8. Validation and Diagnostics

Diagnostics in Culsma are stage-placed:

1. each stage emits the failures it can decide earliest
2. diagnostic prefixes (LOAD/LIB, SEM, TYPE, ENTRY, PLAN, RT, MAT) mark that stage placement
3. the diagnostic code set and stage boundary do not imply a single monolithic diagnostic subsystem

8.1 Validation Stages

Culsma uses staged checks:

1. Entry-source and definition-dependency loading
2. Library-definition resolution
3. Compilation to a normalized intermediate representation
4. Semantic validation
5. Type/unit validation
6. Entry resolution
7. Execution-plan construction
8. Runtime execution

Pipeline order:

1. The standard pipeline order is load -> resolve -> compile -> validate -> typecheck -> entry -> plan -> runtime.
2. Compilation produces Canonical IR plus semantic-analysis input; semantic validation consumes both.
3. Execution-plan construction may emit PLAN_* diagnostics while still producing an execution plan; runtime execution consumes plan diagnostics according to the runtime error policy.
4. Runtime material compute, observation recording, and protocol-output capture are part of runtime execution, not separate pre-runtime stages.

8.2 Operation Contract Check Placement

Operation vocabulary definitions and call contracts are specified in Chapter 6.

Call validation applies equally to statements and nested expressions. A constructor in a load item or an expression reached through an alias is subject to the same parameter-name rules as an ordinary call.

1. Step-call syntax accepts IDENTIFIER(...), but semantic validity requires operation presence in the vocabulary; unknown names produce SEM_UNKNOWN_STEP.
2. Missing required arguments, unknown arguments, and duplicate argument names are semantic failures. Unknown names produce SEM_UNKNOWN_ARG; duplicates produce SEM_DUPLICATE_ARG before any value can overwrite another.
3. Container/content source forms follow the constructor contracts in Chapter 6. Missing content kind and missing or malformed content type retain their content-specific diagnostics in §8.2.2.
4. Open attrs keys are metadata, not additional top-level parameters. For example, attrs = { role: culture } is permitted; top-level role = culture produces SEM_UNKNOWN_ARG.

Diagnostic identity follows source origin. Repeated analysis or expansion of one source occurrence MUST report an identical semantic diagnostic only once. Code, message, and severity must all match for this purpose. Distinct source occurrences remain distinct even when their line and column coordinates match in separate files. Diagnostics that describe different bound values also remain distinct. When common origin cannot be established, diagnostics MUST NOT be merged solely because their coordinates or messages match.

8.2.1 Canonical Content Whitelist

content_kind and standard content_type values are constrained by the canonical whitelist defined in Chapter 6.

Validation policy:

1. Missing content_kind is semantic error.
2. Non-whitelisted content_kind is semantic error in strict mode.
3. content_type uses lowercase snake_case tokens.
4. Standard content_type values should use canonical tokens.
5. The canonical content_type surface is closed; uncommon material identities should use the Chapter 6 other_* fallback for their kind.
6. Standard attrs.role values are recommended/controlled by Chapter 6, but attrs remains open metadata; unknown attr keys are not rejected solely for being unknown.

Validation contract:

1. The whitelist is part of the content contract.
2. Dedicated content diagnostics below are part of the staged diagnostic contract.
3. Legacy content kind/type aliases, including older custom/unknown type strings, are compatibility inputs only when legacy normalization mode is explicitly enabled. Such inputs should produce warning diagnostics and normalize to Chapter 6 canonical values.

Enum-family errors remain type diagnostics; member/cycle errors remain semantic errors. Planning/runtime checks apply once final values are known and do not replace earlier diagnostics. Valid explicit enums are executable. Rejected final classifications do not modify material state.

8.2.2 Diagnostic Mapping Table (Content + Mutation Model)

Failure condition	Earliest stage	Diagnostic code	Status
missing content kind in a content constructor	semantic	SEM_MISSING_CONTENT_KIND	current
unknown explicit content/container enum member	semantic	SEM_CONTENT_ENUM_MEMBER_INVALID	current
cyclic content binding	semantic	SEM_CONTENT_ENUM_BINDING_CYCLE	current
content/container argument uses the wrong enum family	type	TYPE_CONTENT_ENUM_TYPE_MISMATCH	current
non-text and non-enum container kind	type	TYPE_CONTAINER_KIND_NOT_TEXT	current
final statically bound content classification is invalid	plan	PLAN_CONTENT_CLASSIFICATION_INVALID	current
final statically bound container kind or surface capacity is invalid	plan	PLAN_CONTAINER_KIND_INVALID	current
final runtime content classification is missing, nontext, wrong-family or invalid	material	MAT_CONTENT_CLASSIFICATION_INVALID	current
final runtime container kind is invalid	material	MAT_CONTAINER_KIND_INVALID	current
invalid container capacity, including surface volume capacity	material	MAT_INVALID_CAPACITY	current
non-whitelisted content_kind (strict mode)	semantic	SEM_INVALID_CONTENT_KIND	current
invalid content_type normalization (required mode)	semantic	SEM_INVALID_CONTENT_TYPE_FORMAT	current
unsupported content_type token in strict canonical mode	semantic	SEM_INVALID_CONTENT_TYPE_VALUE	current
legacy or unknown content taxonomy normalized to canonical value or other_* in compatibility mode	semantic	SEM_CONTENT_TAXONOMY_COMPAT_NORMALIZED	current warning
unsupported constructor container kind	semantic	SEM_INVALID_CONTAINER_KIND	current
surface(...) constructor provides volume capacity	semantic	SEM_SURFACE_CAPACITY_FORBIDDEN	current
constructor load = [...] item is not a valid content_spec:quantity pair list	semantic	SEM_INVALID_LOAD_ITEM	current
invalid container target-view member path such as container.structure, container.structure.upper, or container.structure.top.inner	semantic	SEM_CONTAINER_TARGET_VIEW_INVALID	current
non-text content_kind	type	TYPE_CONTENT_KIND_NOT_TEXT	current
non-text content_type	type	TYPE_CONTENT_TYPE_NOT_TEXT	current
non-text content_code	type	TYPE_CONTENT_CODE_NOT_TEXT	current
non-record attrs	type	TYPE_CONTENT_ATTRS_NOT_RECORD	current
ContainerTargetView is used where a material Container is required	type	TYPE_CONTAINER_TARGET_VIEW_POSITION_INVALID	current
mutation statement uses legacy per-source program(...) payload shape	semantic	SEM_MUTATION_PROGRAM_SOURCE_SHAPE_CONFLICT	current
source.partition(program)[i] is used outside mutation source position	semantic	SEM_SOURCE_PARTITION_CONTEXT_INVALID	current
source.partition(program)[i] program does not resolve to a partition-capable concrete program	semantic	SEM_PROGRAM_OWNER_MISMATCH / SEM_PROGRAM_KIND_INVALID	current
source.partition(program)[i] index is missing, non-static, negative, or outside binary range	semantic	SEM_INDEX_NOT_STATIC_INTEGER / SEM_INDEX_NOT_NONNEGATIVE_INTEGER / SEM_INDEX_OUT_OF_RANGE	current
container.contents[i] is used outside mutation source position	semantic	SEM_CONTAINER_CONTENTS_INDEX_CONTEXT_INVALID	current
container.contents[i] index is missing, non-static, or negative	semantic	SEM_INDEX_NOT_STATIC_INTEGER / SEM_INDEX_NOT_NONNEGATIVE_INTEGER	current
standalone content init appears in execution flow	semantic	SEM_STANDALONE_CONTENT_INIT_FORBIDDEN	current
unknown content identity at load/apply	material	MAT_CONTENT_NOT_FOUND	current
incompatible amount axis in content loading	material	MAT_CONTENT_LOAD_AXIS_MISMATCH	current
immutable content metadata conflict	material	MAT_CONTENT_METADATA_CONFLICT	current
selected scientific provider is absent, not applicable, or returns UNRESOLVED	material	MAT_SCIENTIFIC_MODEL_UNRESOLVED	current
selected scientific provider fails	material	MAT_SCIENTIFIC_MODEL_FAILED	current
selected scientific provider returns an invalid proposal	material	MAT_SCIENTIFIC_MODEL_PROPOSAL_INVALID	current
sep.component_fates is not a nested record, omits an output, uses an unknown output name, contains an invalid ratio, or does not sum to 100%	semantic	SEM_SEPARATION_FATE_RULE_SHAPE_INVALID / SEM_SEPARATION_FATE_RULE_SLOT_INVALID / SEM_SEPARATION_FATE_RULE_VALUE_INVALID / SEM_SEPARATION_FATE_RULE_TOTAL_INVALID	current
sep.component_fates references content absent from the runtime source	material	MAT_SEPARATION_FATE_COMPONENT_NOT_FOUND	current
sep.transitions is not a list of typed transition(...) values, uses an invalid selector, uses a bare/cross-program/unknown output member, supplies a string, bare, unknown, or internal target state, or supplies an invalid association selector	semantic	SEM_MATERIAL_TRANSITIONS_SHAPE_INVALID / SEM_MATERIAL_TRANSITION_* / SEM_MATERIAL_SELECTOR_*	current
sep.transitions target is outside the author-settable MaterialRelation enum, a selected index or exact entry ID is unavailable, the selected output has zero quantity, or a component-bound association target is missing from that output	material	MAT_MATERIAL_TRANSITION_* / MAT_MATERIAL_INDEX_OUT_OF_RANGE / MAT_MATERIAL_ENTRY_ID_NOT_FOUND / MAT_MATERIAL_RELATION_INVALID	current
container.contents[i] is read without a current valid indexed contents state	material	MAT_CONTENTS_STATE_NOT_INDEXED	current
container.contents[i] index does not exist in the current contents state	material	MAT_CONTENTS_STATE_INDEX_OUT_OF_RANGE	current
container.contents[i] reads a preserved indexed contents state outside its required preservation context	material	MAT_CONTENTS_STATE_PRESERVATION_NOT_SATISFIED	current

8.2.3 Diagnostic Mapping Table (Atomic Statements + Readout)

Failure condition	Earliest stage	Diagnostic code	Status
External vocabulary field contains a member from another domain, or an invalid value shape for that field	typecheck	TYPE_EXTERNAL_ENUM_MISMATCH	current
stream.unit, data_ref.kind, data_group_ref.kind, or a typed attrs.role/state/bead_property expression names an unknown member or uninstalled namespace	semantic	SEM_INVALID_EXTERNAL_PARAMETER	current
External vocabulary value or dependent parameter combination becomes invalid after protocol argument binding	plan	PLAN_EXTERNAL_ENUM_INVALID	current
Deferred external vocabulary, stored extension identity, or dependent parameter contract fails final validation before execution	runtime	RT_EXTERNAL_ENUM_INVALID	current
with env(...) inferred/explicit-hold target missing	semantic	SEM_ENV_TARGET_REQUIRED	current
with env(...) missing body and explicit hold form	semantic	SEM_ENV_BODY_REQUIRED	current
with env(...) missing every supported environment dimension	semantic	SEM_ENV_THERMAL_REQUIRED	current
scalar with env(thermal = ..., ...) missing required duration for pure hold/incubation or env-bound time scheduling	semantic	SEM_ENV_DURATION_REQUIRED	current
with env(duration=...) without thermal	semantic	SEM_ENV_DURATION_WITHOUT_THERMAL	current
outer duration is used together with thermal_program(...)	semantic	SEM_ENV_DURATION_FORBIDDEN_WITH_THERMAL_PROGRAM	current
with env(...) uses thermal-only modifier outside thermal scope	semantic	SEM_ENV_ARG_CONFLICT	current
hold(...) appears outside a direct with env(...) body, including inside a nested non-env sub-block	source/compile	hard error	current
hold(...) has zero args, multiple args, or an unsupported argument shape	source/compile	hard error	current
hold(...) target is not a valid env target shape	source/compile	hard error	current
legacy hold(sample = ...) compatibility spelling is accepted	source compatibility	no diagnostic	current
agit(...) uses unsupported mode	semantic	SEM_AGIT_MODE_UNKNOWN	current
agit(mode=shake) uses unsupported motion	semantic	SEM_AGIT_MOTION_UNKNOWN	current
agit(...) uses a mode/target or mode/argument combination not allowed by its contract	semantic	SEM_AGIT_ARG_CONFLICT	current
agit(mode=CENTRIFUGE) omits its centrifugal drive	semantic	SEM_MISSING_REQUIRED_ARG	current
agit omits required action duration or the duration/count choice for rocking	semantic	SEM_AGIT_DURATION_REQUIRED	current
A statically resolved explicit-motion or legacy rotation parameter violates its quantity contract	semantic	SEM_AGIT_QUANTITY_INVALID	current
attached program = ... does not resolve to a concrete *_program(...) call	semantic	SEM_PROGRAM_KIND_INVALID	current
legacy generic program(...) form is used	semantic	SEM_LEGACY_PROGRAM_FORM_FORBIDDEN	current
concrete *_program(...) kind is not valid for the owning operator family	semantic	SEM_PROGRAM_OWNER_MISMATCH	current
concrete *_program(...) enum field uses unsupported token	semantic	SEM_INVALID_PROGRAM_ARG_VALUE	current
mutually exclusive program fields are supplied together	semantic	SEM_PROGRAM_ARG_CONFLICT	current
field_program.field is used instead of field_program.voltage	semantic	SEM_FIELD_PROGRAM_FIELD_ALIAS	current
with constraint(...) missing body	semantic	SEM_CONSTRAINT_BODY_REQUIRED	current
with constraint(...) provides neither requirement nor option	semantic	SEM_CONSTRAINT_ITEM_REQUIRED	current
with constraint(...) names an unknown bare requirement or qualified member	semantic	SEM_UNKNOWN_REQUIREMENT	current
Requirement extension identity is unknown, inconsistent, or unsupported by the executor	runtime	RT_DRIVER_REQUIREMENT_UNSUPPORTED	current
spread transfer target resolves to a non-surface	semantic	SEM_SPREAD_TARGET_NOT_SURFACE	current
with constraint(...) duplicates an option key	semantic	SEM_CONSTRAINT_DUPLICATE_OPTION	current
requirement is not valid for block scope	semantic	SEM_CONSTRAINT_SCOPE_INVALID	current
customized is mixed with standard requirements	semantic	SEM_CONSTRAINT_CUSTOMIZED_EXCLUSIVE	current
constraint(customized, ...) omits schema_ref	semantic	SEM_CONSTRAINT_CUSTOMIZED_SCHEMA_REQUIRED	current
unsupported constraint option is supplied	semantic	SEM_CONSTRAINT_UNKNOWN_OPTION	current
active requirement does not allow the action family	semantic	SEM_CONSTRAINT_ACTION_FAMILY_MISMATCH	current
active cold_chain requirement conflicts with env thermal setting	semantic	SEM_CONSTRAINT_ENV_CONFLICT	current
Bound cold-chain thermal setting exceeds its limit	runtime	RT_CONSTRAINT_ENV_CONFLICT	current
Active requirements are unknown, inapplicable, conflicting, or require an unresolved explicit thermal value	runtime	RT_CONSTRAINT_INVALID	current
statement-level quantity field uses a globally invalid/unknown unit form	type	TYPE_DIMENSION_MISMATCH / TYPE_UNKNOWN_UNIT / TYPE_UNIT_NOT_ALLOWED	current
program field quantity/dimension mismatch	type	TYPE_PROGRAM_FIELD_KIND_MISMATCH / TYPE_PROGRAM_FIELD_DIMENSION_MISMATCH	current

8.3 Semantic Diagnostics (SEM_*)

Primary semantic diagnostics:

These codes cover statement legality, argument shape, binding legality, requirement compatibility, and operator-family membership:

1. SEM_UNKNOWN_STEP: step/operator name is not in the semantic vocabulary
2. SEM_MISSING_REQUIRED_ARG: a required argument is missing
3. SEM_UNKNOWN_ARG: an argument name is not allowed for the call
4. SEM_DUPLICATE_ARG: the same argument name appears more than once
5. SEM_UNBOUND_NAME_REFERENCE: a referenced local/runtime-visible name is not bound in scope
6. SEM_MISSING_CONTENT_KIND: content declaration omits required kind
7. SEM_INVALID_CONTENT_KIND: content kind is outside the whitelist
8. SEM_INVALID_CONTENT_TYPE_FORMAT: content type token shape is invalid
9. SEM_INVALID_CONTENT_TYPE_VALUE: content type token is not allowed for the selected kind
10. SEM_INVALID_CONTAINER_KIND: constructor uses an unsupported container kind
11. SEM_SURFACE_CAPACITY_FORBIDDEN: surface(...) uses forbidden volume capacity
12. SEM_INVALID_LOAD_ITEM: constructor load=[...] item shape is invalid
13. SEM_STANDALONE_CONTENT_INIT_FORBIDDEN: execution flow contains standalone content-init material forms
14. SEM_MUTATION_PROGRAM_SOURCE_SHAPE_CONFLICT: mutation-attached program shape is invalid for the source style
15. SEM_ENV_TARGET_REQUIRED: with env(...) has no inferred or explicit target
16. SEM_ENV_BODY_REQUIRED: with env(...) has neither body nor explicit hold form
17. SEM_ENV_THERMAL_REQUIRED: with env(...) provides no supported environment dimension
18. SEM_ENV_DURATION_REQUIRED: scalar thermal env is missing an explicit duration where the block is a pure hold/incubation or otherwise requires an enclosing time boundary
19. SEM_ENV_DURATION_WITHOUT_THERMAL: duration appears without thermal
20. SEM_ENV_DURATION_FORBIDDEN_WITH_THERMAL_PROGRAM: outer duration is used with thermal_program(...)
21. SEM_ENV_ARG_CONFLICT: env arguments conflict with the selected env mode
22. SEM_CONTAINER_TARGET_VIEW_INVALID: container target-view member path is incomplete or outside the closed accessor set
23. SEM_AGIT_MODE_UNKNOWN: agit(...) mode is unsupported
24. SEM_AGIT_ARG_CONFLICT: agit(...) target or argument combination is invalid for the selected mode; deferred combinations retain runtime ownership (RT_EXTERNAL_ENUM_INVALID)
25. SEM_PROGRAM_KIND_INVALID: attached program does not resolve to a known concrete *_program(...)
26. SEM_LEGACY_PROGRAM_FORM_FORBIDDEN: legacy generic program(...) form is forbidden
27. SEM_PROGRAM_OWNER_MISMATCH: concrete *_program(...) kind is not valid for the owning operator family
28. SEM_INVALID_PROGRAM_ARG_VALUE: program enum/token field value is unsupported
29. SEM_PROGRAM_ARG_CONFLICT: mutually exclusive program fields are supplied together
30. SEM_FIELD_PROGRAM_FIELD_ALIAS: field_program.field is used instead of field_program.voltage
31. SEM_UNKNOWN_REQUIREMENT: constraint(...) names an unknown requirement
32. SEM_CONSTRAINT_BODY_REQUIRED: with constraint(...) is missing a body
33. SEM_CONSTRAINT_ITEM_REQUIRED: with constraint(...) provides neither requirement nor option
34. SEM_CONSTRAINT_DUPLICATE_OPTION: the same constraint option key appears more than once
35. SEM_CONSTRAINT_SCOPE_INVALID: requirement is not legal in the current scope
36. SEM_CONSTRAINT_CONFLICT: two active requirements conflict
37. SEM_CONSTRAINT_CUSTOMIZED_EXCLUSIVE: customized is mixed with standard requirements
38. SEM_CONSTRAINT_CUSTOMIZED_SCHEMA_REQUIRED: customized omits required schema_ref
39. SEM_CONSTRAINT_UNKNOWN_OPTION: unsupported constraint option key is supplied
40. SEM_CONSTRAINT_ACTION_FAMILY_MISMATCH: active requirement disallows the action family
41. SEM_CONSTRAINT_ENV_CONFLICT: active requirement conflicts with env settings
42. SEM_MATERIAL_TRANSITIONS_SHAPE_INVALID / SEM_MATERIAL_TRANSITION_SHAPE_INVALID / SEM_MATERIAL_TRANSITION_ARGS_INVALID: the sep.transitions collection or one transition(...) call has an invalid shape.
43. SEM_MATERIAL_SELECTOR_INVALID / SEM_MATERIAL_SELECTOR_CONTAINER_MISMATCH: a transition subject or association target is neither a same-sample materials[index] selector nor a same-sample materials.get(entry_id) selector with a statically resolvable non-empty string key.
44. SEM_MATERIAL_TRANSITION_OUTPUT_INVALID: output is not a namespaced member of the concrete output enum owned by the selected separation program, including bare identifiers and members of another program's output enum.
45. SEM_MATERIAL_TRANSITION_TARGET_INVALID: to is a string, a bare or unknown identifier, a member of another enum, or the internal MaterialRelation.UNRESOLVED sentinel rather than an author-settable MaterialRelation.MEMBER.
46. SEM_MATERIAL_TRANSITION_ASSOCIATION_REQUIRED / SEM_MATERIAL_TRANSITION_ASSOCIATION_FORBIDDEN / SEM_MATERIAL_TRANSITION_ASSOCIATION_INVALID: associated_with does not match the target relation's typed association contract.

8.3.1 Content/Constructor Semantic Diagnostics

Content descriptors are checked where they declare initial material or replacement products. Container construction also validates its own family and argument contract.

Code	Condition
SEM_MISSING_CONTENT_KIND	A content declaration is missing its required kind.
SEM_INVALID_CONTENT_KIND	The supplied content kind is outside the canonical contract.
SEM_INVALID_CONTENT_TYPE_FORMAT	A supplied content type is not in normalized identifier form.
SEM_INVALID_CONTAINER_KIND	Container construction uses an unsupported concrete kind.
SEM_MATERIAL_REPLACE_INVALID	Replacement has an invalid receiver, same-container selector map, value shape, product descriptor, or quantity declaration.

Replacement shares normal descriptor checks; accepting the method shape does not bypass content validation. Source-dependent material constraints are checked at execution under Section 8.8.1.

8.3.2 Statement-First Mutation Semantic Diagnostics

For mutation statements (target << [sources...]) in the statement-first model:

1. SEM_MUTATION_PROGRAM_SOURCE_SHAPE_CONFLICT: mutation-specific program payloads are authored in a legacy shape that the source surface no longer accepts.

2. SEM_STANDALONE_CONTENT_INIT_FORBIDDEN: execution flow contains standalone content/blood/buffer/... init as flowable material. Contract:

3. These codes are part of the mutation/content-model contract.

4. The codes above are emitted in the pipeline.

8.4 Type Diagnostics (TYPE_*)

Primary type/unit diagnostics:

These codes cover quantity dimensions, unit families, typed assignment, and typed constructor/program fields:

1. TYPE_DIMENSION_MISMATCH: value has the wrong physical dimension
2. TYPE_UNKNOWN_UNIT: unit token is unknown to the typechecker
3. TYPE_UNIT_NOT_ALLOWED: a quantity/unit is not allowed in the contract position
4. TYPE_UNIT_LEGACY_ALIAS: unit token is accepted as a legacy alias but is not a canonical spelling
5. TYPE_ENV_THERMAL_DIMENSION_MISMATCH: thermal value is not temperature-compatible
6. TYPE_ENV_DURATION_DIMENSION_MISMATCH: duration value is not time-compatible
7. TYPE_ENV_PERCENT_DIMENSION_MISMATCH: co2/rh value is not percent-compatible
8. TYPE_MUTATION_QUANTITY_UNIT_REQUIRED: quantified mutation source is missing a unit-bearing quantity
9. TYPE_MUTATION_QUANTITY_DIMENSION_MISMATCH: quantified mutation source uses the wrong dimension
10. TYPE_LOAD_QUANTITY_UNIT_REQUIRED: constructor/load amount is missing required unit-bearing quantity
11. TYPE_LOAD_QUANTITY_DIMENSION_MISMATCH: constructor/load amount uses the wrong dimension
12. TYPE_PROGRAM_FIELD_KIND_MISMATCH: program field has the wrong value kind
13. TYPE_PROGRAM_FIELD_DIMENSION_MISMATCH: program quantity field has the wrong dimension
14. TYPE_LOCAL_ASSIGN_TARGET_FORBIDDEN: local assignment target form is not type-legal
15. TYPE_LOCAL_ASSIGN_MISMATCH: assigned value is not type-compatible with the local target
16. TYPE_MEMBER_ASSIGN_TARGET_FORBIDDEN: member assignment target root is not type-legal
17. TYPE_MEMBER_ASSIGN_PATH_FORBIDDEN: member assignment path is not allowed
18. TYPE_CONTAINER_TARGET_VIEW_POSITION_INVALID: a ContainerTargetView is used where a material Container is required
19. TYPE_QUANTITY_DIVISION_BY_ZERO: a quantity-expression denominator is known to be zero after binding resolution or concrete call expansion.
20. TYPE_QUANTITY_VALUE_NONFINITE: a quantity calculation is not finitely representable, including a denominator that underflows to zero during conversion.

Expression results use the receiving slot's unit-required or dimension-mismatch code. This applies equally to literals, bindings, and calculated quantities. Deferred runtime failures retain the existing execution error path; they do not produce fabricated quantities.

8.4.0 Record Field Resolution Diagnostics

Record projection failures belong to semantic validation:

Failure	Diagnostic
A known record lacks the requested field	SEM_RECORD_FIELD_MISSING
A field is read from a known non-record scalar or list	SEM_RECORD_MEMBER_BASE_INVALID
Alias or field resolution encounters a cycle	SEM_EXPRESSION_BINDING_CYCLE

Unbound formal parameters defer value-dependent checks to concrete call expansion. Successful projection does not suppress receiving-operation type, unit, dimension, or separation-fate diagnostics. Enum namespace shadowing and domain member failures retain their owning domain diagnostics.

8.4.1 Content Metadata Type Diagnostics

1. TYPE_CONTENT_ATTRS_NOT_RECORD: attrs for content declaration is not a record/map.
2. TYPE_CONTENT_CODE_NOT_TEXT: content_code is not text-like.
3. TYPE_CONTENT_KIND_NOT_TEXT: content_kind argument is not text-like in constructor call.

Contract:

1. These diagnostics are emitted by type/semantic boundary checks after constructor lowering.

8.5 Entry Resolution Diagnostics (ENTRY_*)

Entry resolution runs after semantic and type validation and before plan lowering:

1. ENTRY_LEGACY_IMPLICIT_PROTOCOL (warning): entry resolution selected the unique unreferenced root protocol through the version-scoped compatibility rule
2. ENTRY_NO_ENTRYPOINT (error): the entry source contains no top-level executable statements and does not satisfy the compatibility entry rule

An entry-resolution error prevents plan execution. Dependency files do not undergo entry resolution and therefore may contain definitions without an executable entry.

8.6 Plan Diagnostics (PLAN_*)

Primary plan diagnostics:

These codes cover protocol-reference expansion, call-frame binding, and compatibility-entry parameter resolution:

1. PLAN_UNKNOWN_REFERENCE: referenced protocol cannot be found during plan expansion
2. PLAN_REFERENCE_CYCLE: protocol-reference expansion forms a cycle
3. PLAN_CALL_ARG_MISSING: a referenced protocol call is missing a required argument
4. PLAN_CALL_ARG_UNKNOWN: a referenced protocol call supplies an unknown argument
5. PLAN_CALL_ARG_DUPLICATE: a referenced protocol call duplicates an argument name
6. PLAN_CALL_ARG_DEFAULT_EVAL_FAILED: a default parameter value cannot be resolved in call binding
7. PLAN_CALL_PARAM_REDECLARED: protocol body redefines a protected parameter name
8. PLAN_ENTRY_PARAM_MISSING: the selected compatibility protocol is missing a required entry argument
9. PLAN_SELECTED_PROTOCOL_NOT_FOUND: plan lowering received a protocol entry resolution whose selected protocol is absent from the supplied IR program

These diagnostics cover repeated/recursive reference expansion and parameterized protocol binding failures.

8.7 Load Diagnostics (LOAD_*)

For entry-source loading and definition dependency loading, load/frontend stage may emit:

1. LOAD_DUPLICATE_PROTOCOL_NAME: loaded source files define the same protocol name twice
2. LOAD_NO_INPUT_SOURCES: no entry sources were provided
3. LOAD_SOURCE_NOT_FOUND: an input source path cannot be found
4. LIB_IMPORT_NOT_FOUND: a library import cannot be resolved
5. LIB_IMPORT_CYCLE: library imports form a cycle
6. LIB_PROTOCOL_NAME_CONFLICT: imported/external protocol names conflict with existing names

Contract:

1. Load/frontend failures are decided by the source-loading / frontend-resolution stage and must not be replaced by SEM_* codes.
2. Load/library failures may surface as hard exceptions with stable string prefixes rather than in-memory Diagnostic objects.
3. LOAD_* covers entry-source and include dependency loading; LIB_* covers import resolution and external protocol namespace assembly.

8.8 Runtime and Material Diagnostics (RT_*, MAT_*)

Execution/runtime layer:

These codes cover scheduler/runtime orchestration failures and runtime binding failures that remain after earlier stages:

1. RT_DRIVER_ERROR: driver execution failed
2. RT_MATERIAL_ERROR: runtime step failed because material update failed
3. RT_ABORTED_AFTER_FAILURE: fail-fast runtime aborted further dispatch after a failure
4. RT_UNSATISFIED_DEPENDENCY: a step cannot run because dependencies never became satisfiable
5. RT_STUCK_STEP: scheduler detected no progress for pending work
6. RT_SCHEDULER_GUARD_LIMIT: scheduler hit the no-progress/guard limit
7. RT_RUNTIME_CONDITION_UNRESOLVED: runtime condition could not be evaluated
8. RT_DRIVER_REQUIREMENT_UNSUPPORTED: selected driver cannot satisfy an active requirement
9. RT_LOCAL_ASSIGN_INVALID_TARGET: runtime local assignment target shape is invalid
10. RT_LOCAL_ASSIGN_UNRESOLVED: runtime local assignment value could not be resolved or constructed from its bound fields
11. RT_MEMBER_ASSIGN_TARGET_INVALID: runtime member assignment target is invalid
12. RT_MEMBER_ASSIGN_VALUE_UNRESOLVED: runtime member assignment value could not be resolved
13. RT_APPEND_TARGET_INVALID: runtime append target is invalid
14. RT_APPEND_VALUE_UNRESOLVED: runtime append value could not be resolved
15. RT_REPEAT_BODY_INVALID: repeat body structure is invalid at runtime execution
16. RT_REPEAT_ITERABLE_INVALID: repeat iterable does not resolve to a valid runtime iterable

Material compute layer:

1. MAT_BINDING_NOT_FOUND: referenced runtime material or carrier binding cannot be resolved
2. MAT_INSUFFICIENT_VOLUME / MAT_INSUFFICIENT_MASS / MAT_INSUFFICIENT_COUNT: source material is insufficient for the requested transfer
3. MAT_DILUTION_UNDERSPECIFIED / MAT_DILUTION_INVALID_TARGET: dilution operation is missing required information or uses an invalid target
4. MAT_MISSING_DENSITY / MAT_INVALID_DENSITY: density bridge is required but missing or invalid
5. MAT_INVALID_RECOVERY_RATIO: requested recovery ratio is invalid
6. MAT_CONSERVATION_VIOLATION: material conservation check failed
7. MAT_CONTAINER_OVERFLOW: post-step volume exceeds container capacity
8. MAT_INVALID_CAPACITY: declared container capacity is invalid
9. MAT_CONTENT_NOT_FOUND: referenced content identity cannot be resolved at material stage
10. MAT_CONTENT_LOAD_AXIS_MISMATCH: requested content load axis is incompatible with runtime representation
11. MAT_CONTENT_METADATA_CONFLICT: immutable content metadata conflict is detected at runtime
12. MAT_SCIENTIFIC_MODEL_UNRESOLVED: the selected provider is absent, not applicable, or returns UNRESOLVED; committed material remains unchanged
13. MAT_SCIENTIFIC_MODEL_FAILED: the selected provider fails; committed material remains unchanged
14. MAT_SCIENTIFIC_MODEL_PROPOSAL_INVALID: kernel validation rejects a provider proposal; committed material remains unchanged
15. MAT_UNSUPPORTED_UNIT: runtime material layer does not support the requested unit conversion or axis
16. MAT_MOVEMENT_CONTRACT_MISSING: a successful material operation changed container quantities without exposing an auditable source-to-destination movement contract
17. MAT_CELL_COUNT_VALUE_INVALID: an authored load or quantified transfer uses a negative or non-integral cell count
18. MAT_INVALID_CELL_SUSPENSION_CONCENTRATION: required cell-suspension concentration is missing, non-finite, zero, or negative
19. MAT_COUNT_TRANSFER_SOURCE_NOT_SUSPENSION: a count aliquot is requested from adherent, pellet, or otherwise non-homogeneous material
20. MAT_COUNT_TRANSFER_AMBIGUOUS: a count aliquot does not identify one population when multiple cellular populations are present
21. MAT_IMPLICIT_CARRIER_OVERFLOW: constructor finalization would materialize implicit carrier beyond container capacity
22. MAT_CONTENT_QUANTITY_AXIS_CONFLICT: the same content identity would merge incompatible quantity axes
23. MAT_SEPARATION_FATE_COMPONENT_NOT_FOUND / MAT_SEPARATION_FATE_RULE_*: runtime source-dependent validation of authored component fate rules failed
24. MAT_MATERIAL_INDEX_OUT_OF_RANGE / MAT_MATERIAL_ENTRY_ID_NOT_FOUND / MAT_MATERIAL_ENTRY_ID_AMBIGUOUS / MAT_MATERIAL_ENTRY_INVALID / MAT_MATERIAL_RELATION_INVALID: runtime cannot resolve exactly one selected live material entry or its current enum relation.
25. MAT_MATERIAL_TRANSITION_TARGET_INVALID: the target is outside the author-settable MaterialRelation enum domain; free text and UNRESOLVED are rejected.
26. MAT_MATERIAL_TRANSITION_OUTPUT_EMPTY / MAT_MATERIAL_TRANSITION_OUTPUT_UNRESOLVED / MAT_MATERIAL_TRANSITION_DUPLICATE: the output-scoped transition cannot be applied uniquely to positive quantity.
27. MAT_MATERIAL_TRANSITION_ASSOCIATION_REQUIRED / MAT_MATERIAL_TRANSITION_ASSOCIATION_FORBIDDEN / MAT_MATERIAL_TRANSITION_ASSOCIATION_KIND_INVALID / MAT_MATERIAL_TRANSITION_ASSOCIATION_OUTPUT_EMPTY: the target relationship's typed association invariant is not satisfied.
28. MAT_PLATE_REF_INVALID: a carrier reference is malformed, inconsistent with its allocated carrier, or has incomplete well membership for a whole-carrier effect; reject before mutation. An absent carrier uses MAT_BINDING_NOT_FOUND.

Count-specific type diagnostics:

1. TYPE_CELL_COUNT_VALUE_INVALID: a statically visible authored cell count is negative or non-integral.
2. TYPE_LOAD_COUNT_CONTENT_MISMATCH: cells is applied to content that is statically known not to be bio_cellular.

8.8.1 Content Runtime Diagnostics

Content-aware execution validates identity, quantity representation, and the current source state before applying a material change. These failures retain normal binding and conservation diagnostics where those contracts are involved.

Code	Condition
MAT_CONTENT_NOT_FOUND	The referenced content identity cannot be resolved.
MAT_CONTENT_LOAD_AXIS_MISMATCH	The requested load axis or amount is incompatible with the available representation.
MAT_CONTENT_METADATA_CONFLICT	Immutable content metadata conflict during declaration or merge.
MAT_MATERIAL_REPLACE_INVALID	Replacement arguments or the resulting entry set violate the replacement contract.
MAT_MATERIAL_REPLACE_ACTIVE_PARTS	The receiver still has active indexed contents.
MAT_MATERIAL_REPLACE_SOURCE_UNSUPPORTED	A selected source has no tracked mass, volume, or count quantity.
MAT_MATERIAL_REPLACE_DUPLICATE_PRODUCT	A product repeats a content identity already present in the container or product list.
MAT_QUANTITY_UNKNOWN	Numeric mass is required but unavailable, or an unknown-mass operation lacks explicit fates/free relationship or requests an unsupported relationship change.

Material selectors retain their existing resolution diagnostics. A replacement failure leaves both the subject and product registrations unchanged, as required by Section 7.2.2. Scientific-model provider failures have the separate ownership and commit boundary in Section 8.8.2.

8.8.2 Scientific Model Diagnostics

1. MAT_SCIENTIFIC_MODEL_UNRESOLVED: no selected provider produced an applicable typed decision.
2. MAT_SCIENTIFIC_MODEL_FAILED: the selected provider failed before producing a proposal.
3. MAT_SCIENTIFIC_MODEL_PROPOSAL_INVALID: the selected provider produced a proposal rejected by kernel validation.

Contract:

1. Provider diagnostics are structured evidence; they do not directly become committed runtime diagnostics.
2. Runtime maps provider status and validation outcome to the codes above.
3. Every failure path leaves committed material state unchanged.
4. Runtime MUST NOT replace these outcomes with an equal-split or other guessed scientific result.

8.9 Earliest-Decidable Rule

Diagnostics should be emitted by the earliest stage that can decide them:

1. Step/arg/name contract failures at semantic stage
2. Constructor whitelist/shape failures at semantic stage
3. Unit/dimension and metadata type incompatibilities at type stage
4. Execution-entry selection at entry-resolution stage
5. Reference graph and plan consistency issues at plan stage
6. Source and dependency loading errors at load/frontend stage
7. State-dependent failures at runtime/material stage

8.10 Diagnostic Object Contract

Diagnostic objects should include:

1. code
2. message
3. severity
4. span (where available)
5. node_id (where available)

Diagnostic object fields:

1. The shared diagnostic object carries code, message, severity, span, and node_id.
2. stage and stability classification are diagnostic classifications; they are not required fields on every in-memory diagnostic object.

8.11 Conformance Boundary

Diagnostic producers across source loading, semantic validation, type checking, entry resolution, planning, runtime execution, and material-state handling must conform to the diagnostic codes and stage placement in this chapter. Module layout and test file names are not part of the diagnostic contract.