7. Operational Semantics (Core Atomic Runtime Effects)

7.1 State Model

Per-container state fields:

1. volume_uL
2. mass_mg
3. components (component amount map)
4. component_quantities (content_id -> {dimension, unit, value})
5. metadata (for example density_g_per_mL, carrier_kind, carrier_id, carrier_position)

Content-oriented interpretation:

1. components entries represent content-composition slices associated with logical content identities.
2. Content classification fields (content_kind, content_type, content_code, content_name, attrs) are stored as metadata-linked descriptors.
3. Container identity and content identity are orthogonal: container says where, content says what.

Container model clarification:

1. A logical container identity denotes one distinct container occurrence.
2. Identity distinguishes the declaration's definition scope, the invocation occurrence that reaches it, and the declaration name within that scope.
3. Repeated or nested invocation of the same declaration creates distinct identities. Distinct iterations that allocate a container also create distinct identities.
4. Human-readable labels, external identifiers such as barcodes, and physical carrier metadata describe or map a container; they do not establish its logical identity.
5. The representation and encoding of a logical container identity are not language semantics. They must preserve the distinctions above without exposing a particular identifier-generation scheme to authors.
6. Runtime compute uses logical container identity (container_id) as the stable state key.
7. Physical labware is represented as metadata mapping on that identity.
8. Typical mappings are tube or plate + well (for plate position).
9. Material semantics operate on material state through Mutation, sep, and frac, while preserving physical mapping metadata unless operation explicitly changes it.

Execution updates these values directly and returns per-step delta.

7.1.1 Content Registry and Association Model

For content-constructor flows, runtime state is extended with:

1. content_registry: content_id -> {content_kind, content_type, content_code, content_name, attrs}
2. content_bindings: author-facing content names/codes mapped to stable content_id
3. container_content_index: container_id -> content composition references

Rules:

1. DefineContent allocates stable content_id and registers content metadata.
2. LoadContent associates quantity with a content_id in target container state.
3. AnnotateContent updates metadata descriptors without implicit quantity mutation.

Runtime contract:

1. Content-model runtime state includes first-class content_registry, content_bindings, and container_content_index structures.
2. Container-level components and metadata summaries remain present alongside those content structures.

7.2 Global Rules

1. Runtime-visible material names must resolve to established bindings.
2. Runtime material compute must not provision an undeclared source or increase a source quantity to satisfy an operation request.
3. Insufficient source volume, mass, or cell count is a material-stage failure.
4. Conservation checking is always enforced for material-mutating steps Mutation, sep, and frac; failures are commonly reported as MAT_CONSERVATION_VIOLATION.
5. Optional external inventory reconciliation is a derived result produced after runtime accounting. External stock shortage does not change runtime material state, runtime success, binding, or conservation behavior.
6. Procurement, restocking, or reservation is external orchestration. It must not be represented by provisioning or topping up runtime material state.

Content constraints:

1. In strict content mode, content_kind and standard content_type values must satisfy the Chapter 6 canonical table.
2. Unknown content identity during load/apply is a material-stage failure, commonly reported as MAT_CONTENT_NOT_FOUND.
3. Metadata conflicts on immutable content identity descriptors are material-stage failures, commonly reported as MAT_CONTENT_METADATA_CONFLICT.
4. Diagnostic code definitions and stage placement are specified in Chapter 8.

7.2.1 Constructor Built-ins Runtime Semantics

AllocContainer(kind, ...):

1. Allocates a logical container identity according to the container model in Section 7.1.
2. Initializes empty container state with carrier metadata plus family-appropriate metadata: effective capacity metadata for volume-bearing families (container/tube/well/chamber), and family/state metadata for non-volume surface.
3. Returns container allocation in step delta; runtime session event emission is handled by executor/session layers rather than dedicated material-compute event records.

DefineContent(kind, type, code, name, attrs):

1. Allocates new content_id.
2. Writes normalized content descriptors into content registry.
3. Preserves attrs.role and other attrs as metadata; generic material transfer does not infer a new role or new canonical kind/type.
4. Returns content registration in step delta; it does not introduce a standalone content-event kind at material-compute layer.

LoadContent(container, content, amount, ...):

1. Resolves container_id and content_id.
2. Applies quantity to container content state on an explicit volume, mass, or count axis.
3. A cells load requires normalized bio_cellular content and does not by itself add bulk volume or mass.
4. After all constructor load items, runtime finalizes cellular material relationships. It uses explicit eligible carrier volume when present; otherwise a free count-only cellular population uses the configured default concentration to materialize an auditable implicit carrier. Adherent content retains count without an implicit carrier.
5. Capacity checks use resulting physical volume_uL, including any finalized implicit carrier.
6. Returns axis, amount, relationship, and assumption details in step delta; session-level runtime events are emitted outside material_compute.

AnnotateContent(content, ...):

1. Resolves content_id.
2. Patches metadata descriptors without quantity mutation.
3. Returns annotation/update information through step delta; no standalone material-compute event kind is required.

7.3 Mutation

Mutation(target, sources):

1. Full-source items move all source material into target.
2. Quantified items move the requested volume, mass, or cell count into target.
3. If requested axis is unavailable but density exists (metadata.density_g_per_mL), runtime bridges volume <-> mass.
4. Quantified unit_ref sources are rejected at runtime.
5. If a source item resolves to the same container as target, full-transfer and quantified self-transfer are treated as no-op delta rather than error.
6. Missing, non-positive, or invalid density is a material-stage failure, commonly reported as MAT_MISSING_DENSITY or MAT_INVALID_DENSITY.
7. Unknown bindings are material-stage failures, commonly reported as MAT_BINDING_NOT_FOUND.
8. Insufficient source quantity is a material-stage failure, commonly reported as MAT_INSUFFICIENT_VOLUME, MAT_INSUFFICIENT_MASS, or MAT_INSUFFICIENT_COUNT.
9. Target capacity checks are enforced after computed delta is known; overflow is commonly reported as MAT_CONTAINER_OVERFLOW.
10. Diagnostic code definitions and stage placement are specified in Chapter 8.
11. Volume- or mass-quantified transfer carries every component quantity by the transferred bulk ratio.
12. Count-quantified transfer requires one resolvable count-bearing cellular population in a homogeneous suspension. Runtime converts the requested count to carrier volume from the recorded concentration and moves that aliquot through the ordinary volume-transfer path.
13. Adherent, pellet, precipitate, or otherwise non-homogeneous material is not directly count-aliquotable without a preceding state-changing operation.
14. When counted cells physically move between containers, a container-local surface association is released in the moved material. An empty destination therefore records those cells as a suspension; a preloaded destination merges that incoming state with its existing cell state. Cells remaining in the source retain their surface association. This rule does not release pellet, precipitate, bead, membrane, or cell-bound associations.

7.4 sep

sep(sample, program, bind, component_fates?, transitions?):

1. Produces a fixed two-slot indexed container group.
2. Splits sample material into bind[0] and bind[1].
3. Runtime retains the complete program descriptor through fate resolution; mechanism fields are not reduced to a program name before content routing.
4. Dimensioned component quantities, including any compatibility-normalized unattributed detail, are authoritative. Runtime applies one validated decision and projects each output's aggregate volume_uL and mass_mg from routed detail, carrier relations, and declared density. Aggregate fields MUST NOT receive an independent separation ratio.
5. A validated authored component_fates decision has precedence. Every other scientific fate or state-transition decision is dispatched through the scientific-model extension contract.
6. The default material capability binding is the official built-in Rulebook provider. An explicit external provider may replace it or wrap it as a composite provider. Runtime MUST NOT append an implicit provider fallback.
7. A provider returns only a typed proposal with provenance. Runtime validates request membership, output roles, bounds, allowed effects, state validity, conservation, and capacity before atomic commit.
8. not_applicable, failed, provider UNRESOLVED, or invalid results MUST NOT mutate material state and MUST NOT become an equal-split guess.
9. keep_source aliasing is supported only for centrifuge_program, and only one slot may alias the original source container (supernatant -> slot 0, pellet -> slot 1).
10. Non-centrifuge sep programs still return two fresh slots and ignore source aliasing at runtime surface.
11. Rebinding the same group name emits BINDING_OVERWRITTEN events for changed slots.
12. Validated decision fractions apply independently to each component entry. Aggregate volume and mass are projected from resulting native-axis quantities. Count does not directly contribute volume; an eligible carrier relation supplies the physical volume of a count-bearing suspension.
13. Physical association, accessibility, and preservation state are explicit request facts. Quantity dimension does not determine mobility.
14. component_fates maps a source content identity to both program outputs. Values may be unitless ratios or percentages, must be bounded, and must sum to 1. The referenced content must exist at runtime.
15. At the material-compute API boundary, compatibility input that supplies aggregate volume or mass without complete detail is converted into provenance-bearing attributed or unattributed component quantity detail. If component quantity detail already exists, supplied aggregate fields are discarded and reprojected from that detail; separation never reads or compares them.
16. transitions supplies author-owned Table 3 relationship decisions for live material entries selected by ordered index or exact container-local entry_id, and for positive outputs selected by the concrete program's namespaced output-enum member. Both selector forms resolve against the same normalized, ordered, positive-quantity entry list. Runtime derives each source relation from the selected entry; the source does not repeat a textual from state.
17. Both current and target relations MUST be members of MaterialRelation; authored targets use MaterialRelation.MEMBER, not a bare identifier. Every author-settable enum member may transition to every other author-settable member; implementations MUST NOT impose a relation-pair whitelist. UNRESOLVED is not author-settable.
18. A component-bound target requires a typed component-entry association target present with positive quantity in the same output. A free target clears association. Other target relations use the concrete output container association required by the runtime relationship model.
19. The authored transition is output-scoped, preserves component identity and quantity, and is applied before complete-candidate invariant and conservation validation. Failure leaves committed material unchanged.

Scientific capability, provider-selection, request/response, and extension rules are defined by the Scientific Model Extension Contract. The official default behavior is defined independently by the Built-in Material Separation Rulebook.

7.5 frac

frac(sample, program, bind):

1. Produces an ordered indexed group with arity determined by the fractionation program.
2. Order is preserved in indexed_bindings.
3. Runtime requires bins to be a positive integer-like program field.
4. Material is partitioned by equal-ratio splitting (1.0 / bins) with the final slot receiving the residual remainder.
5. Returned partitions remain conservation-checked.

7.6 agit

agit(sample, mode, ...):

1. For a single-container sample, agitation applies to that container.
2. For a container group, agitation applies independently to every member in group order. Explicit and let-bound groups have identical behavior.
3. Group agitation does not merge group members, transfer material between them, or change group membership or member identity.
4. Agitation preserves each member's total volume, total mass, and component amounts.
5. Agitation invalidates any ordered indexed-contents organization previously established for each agitated member by sep or frac; the member is thereafter treated as mixed until a later operation establishes a new indexed organization.
6. Every group member must resolve to a concrete material container before group effects are applied. An unresolved member is a material binding failure as specified in Chapter 8.

7.7 Material Compute Coverage

Material compute applies state updates for:

1. Mutation, sep, frac, and the indexed-contents state effect of agit
2. AllocContainer, DefineContent, LoadContent, AnnotateContent

Operations outside this set do not change material state at the material-update layer and do not produce material diagnostics from that path. agit changes contents organization but does not change material quantities.

Observation/runtime boundary:

1. img / ecp / phy are executed at runtime/executor layer and write observation artifacts/bindings without material deltas.
2. with env establishes scoped environment context over enclosed executable steps and is not itself a direct material-update step.
3. An environment layer records its explicit or inferred hold/reporting targets. That target set does not restrict the lexical environment context carried by enclosed executable steps.

7.8 Conformance Boundary

Runtime and material-compute implementations must conform to the material-state semantics in this chapter. Module layout and test file names are not part of the operational semantics.

7.9 Atomic Statement Semantics

Atomic statement semantics align with the statement-first contracts in Chapter 6.

Atomic unit	Operational effect	Material conservation scope	Return/output
MutationStmt (<<)	Moves/merges material across container states	in-scope	container material delta (no required value return)
agit	Applies agitation to one container or independently to each member of a container group; invalidates prior indexed-contents organization	no quantity transfer; contents organization is in-scope	no required value return
WithEnvStmt	Applies scoped environment context to target containers for enclosed statements	not a direct material move	scoped environment context lifecycle
WithConstraintStmt	Applies scoped execution requirements to enclosed statements	not a direct material move	scoped requirement context lifecycle
stream	Produces an addressable unit-stream handle for later control-flow/readout composition	not handled by material compute	UnitStreamRef
sep	Performs binary separation and material split into two output containers	in-scope	SepContainerGroup = [group[0], group[1]]
frac	Performs ordered multi-fraction separation	in-scope	FractionGroup = [f0..fn-1]
img	Records optical/image data readout	out-of-scope	DataRef
ecp	Records electrochemical probe data readout	out-of-scope	DataRef
phy	Records physical-sensor data readout	out-of-scope	DataRef

Rules:

1. img/ecp/phy are data-producing operators and MUST NOT change container material quantities.
2. agit preserves material quantities and applies its contents-organization effect independently to each grouped sample member.
3. sep always returns two slots in fixed order: group[0] and group[1]; mode-specific slot semantics are defined by the source-level contract.
4. frac returns an ordered group and order MUST be preserved in downstream indexing.
5. For centrifuge_program(..., keep_source=...), keep_source controls whether one slot aliases original container identity; other sep mechanism programs do not use keep_source.
6. stream, with env, and with constraint participate in execution/runtime composition but are not direct material-conservation handlers.

7.10 Core Semantic Boundary

Scope: execution semantics of the core atomic statement set.

Workflow-library composition semantics and higher-level authoring templates are outside this scope.