9. Execution Model

9.1 Pipeline

The execution kernel follows:

1. Select one entry source for the run, or fan out multiple CLI inputs into independent batch runs.
2. Load the entry source plus its definition dependencies.
3. Resolve imported and otherwise available library protocol definitions.
4. Prepare callable protocol definitions and references for compilation.
5. Compile the prepared program to Canonical IR plus semantic-analysis input.
6. Validate semantic contracts
7. Typecheck dimensions/units
8. Resolve the executable entry boundary
9. Construct the execution plan
10. Run plan with runtime scheduler, driver, material compute, observation recording, and protocol-output capture

Each stage may emit diagnostics and halt progression depending on tool policy.

CLI batch rule:

1. Multiple CLI input files are separate runs, not one merged program.
2. Each batch item has independent entry-source script statements, material state, diagnostics, artifacts, and output.
3. Top-level executable statements parsed from include/import dependency files are omitted from the current item's script entry and are not executed.

9.2 Canonical IR Role

Canonical IR is the execution-facing normalized form used by validation, typechecking, plan lowering, and runtime-oriented tooling. It is an internal pipeline boundary, not a user-authored language surface. The compile stage produces a compile result containing Canonical IR plus compiler-produced analysis needed by downstream semantic validation.

Canonical IR guarantees:

1. Preserves source spans for diagnostics
2. Preserves first-class core statement/operator structure needed by downstream stages
3. Removes frontend loading declarations from the execution-facing program
4. Lifts protocol return data into protocol-level return fields
5. Canonicalizes protocol references and source control forms into stable internal statement forms
6. Carries inferred environment targets needed by later semantic and plan stages
7. Provides stable IDs for downstream diagnostics, plan mapping, and runtime correlation

Schema layout details are outside the execution model.

9.3 Plan Lowering Semantics

Plan lowering guarantees:

1. Explicit dependencies across executable steps
2. Protocol-reference inline expansion (Module.Protocol() or legacy include form) into concrete plan steps
3. Deterministic step IDs and call-path metadata for reference reuse
4. with env is lowered as gate/context on enclosed executable steps, not as an implicit repetition node
5. Let-bound core operators are materialized into executable plan steps with explicit bind metadata
6. Local runtime constructors (markers, stream, data_ref, data_group_ref, data_schema) lower to runtime-local binding steps rather than driver-backed instrument steps
7. AllocContainer(...) lowers to explicit constructor/bootstrap steps; constructor load = [...] is preserved as runtime bootstrap contract rather than hidden runtime inference
8. Entry-source top-level statements lower as the script plan for the run
9. Protocol declarations lower only when called/referenced by the selected script or compatibility entry

Entry resolution:

1. Top-level executable statements in the entry source select the script entry.
2. The version-scoped compatibility rule may select one unreferenced entry-source protocol when the entry source has no script statements.
3. Otherwise entry resolution emits ENTRY_NO_ENTRYPOINT as an error and produces no executable plan.

9.4 Layer Boundaries

Layer responsibilities:

1. Syntax/frontend layer: parse source and normalize syntax forms.
2. Semantic/type/plan layer: decide legality before execution, including content classification contracts.
3. Runtime orchestration layer: schedule and execute steps under dependency and policy constraints.
4. Runtime state truth layer: registry/store/event-log are the only source of state truth.

Boundary rules:

1. Frontend ergonomics MAY exist, but MUST NOT define runtime truth.
2. Semantic/type/plan checks validate legality, but MUST NOT mutate material state.
3. Runtime layer MAY mutate state only through explicit runtime invariants.
4. User-level names or object-like handles are references, not state truth.
5. User-facing run summaries or report payloads are derived projections over runtime state/event artifacts; they MUST NOT replace runtime truth.

9.5 Runtime State Machine

Step status domain:

1. pending
2. running
3. completed
4. failed
5. skipped

Allowed transitions include:

1. pending -> running -> completed
2. pending -> running -> failed
3. pending -> skipped (dependency unsatisfied or abort path)

9.6 Scheduling and Dependency Rules

Scheduling rule:

1. A step is schedulable only when every dependency is satisfied.
2. A dependency is satisfied when its status is completed, or when it is skipped for a runtime-control reason that runtime treats as satisfiable (runtime_condition_false, runtime_continue, runtime_break).

Execution policy:

1. Default fail-fast aborts new dispatch after first failure.
2. Continue mode allows independent schedulable steps to continue.

9.7 Reference Reuse Semantics

For expanded protocol-reference groups:

1. Runtime emits REF_DECISION before group execution.
2. Decision is based on cache key + input signature.
3. reuse marks subtree steps completed without driver execution.
4. rerun executes subtree and updates cache.

9.8 Events and Replay

Runtime emits structured events for auditability:

1. Step lifecycle events (STEP_STARTED, STEP_COMPLETED, STEP_FAILED, STEP_SKIPPED)
2. Reference decision events (REF_DECISION)
3. Binding overwrite event (BINDING_OVERWRITTEN) when applicable
4. Data-producing steps may emit artifact metadata and data-binding information through step completion payloads

Replay reconstructs runtime step status/history from event streams and restores material_state snapshots when they are present in completion payloads. Replay does not rebuild the full derived artifact surface (data_objects, data_groups, protocol_outputs, ref_cache) from events alone.

9.9 Material-State Coupling

Runtime and material compute are coupled per completed executable step:

1. Material-mutating step success triggers material update attempt.
2. Data-producing readout steps (img/ecp/phy and decomposed analytical paths) update data artifacts/bindings without applying material deltas.
3. Material update failure is surfaced as runtime material error path.
4. Observation recording persists data_objects, data_bindings, data_groups, data_group_bindings, data_group_indexed_bindings, raw-data metadata, and export references in runtime artifacts.
5. Protocol output capture preserves each protocol's return projection as a run-scoped execution artifact.
6. Global material state, indexed bindings, local bindings, data bindings, and reuse cache persist across all plans in one run.

9.10 Guardrails and Failure Surfaces

Runtime provides deterministic guardrails:

1. Scheduler guard limit to prevent infinite/no-progress loops
2. Unsatisfied dependency diagnostics for permanently blocked steps
3. Stuck-step reporting for unresolved pending states
4. Runtime-condition evaluation failure is surfaced before driver dispatch

9.11 Diagnostic Pipeline Effects

Execution observes the staged diagnostic model defined in Chapter 8. In this chapter, diagnostics are relevant only insofar as they affect pipeline progression, scheduling, runtime failure handling, and derived run reports.

9.12 Earliest-Decidable Rule

Execution follows the Chapter 8 earliest-decidable rule. Operationally, this means:

1. Arg-shape and known-name contract failures at semantic stage, commonly as SEM_* diagnostics.
2. Unit/dimension incompatibilities at type stage, commonly as TYPE_* diagnostics.
3. Reference graph issues at plan stage, commonly as PLAN_* diagnostics.
4. State-dependent failures at runtime/material stage, commonly as RT_* or MAT_* diagnostics.

The complete diagnostic list and stage placement are specified in Chapter 8.

9.13 Conformance Boundary

Execution tooling, planners, runtime executors, replay/report generators, and runtime tests must conform to the pipeline and execution semantics in this chapter. Module layout and test file names are not part of the execution model.

9.14 Material Steps vs Observation Steps

For statement-first/operator contracts in Chapter 6, execution distinguishes three step classes:

1. Material steps: <<, sep, and frac.
2. Runtime-local reference-producing steps: stream and other local runtime constructors that materialize handles/bindings without applying material deltas.
3. Data-producing steps: img, ecp, phy, plus the concrete readout substeps inside decomposed flow/seq/ms paths.

Rules:

1. Data-producing steps MUST NOT apply material deltas.
2. Runtime-local reference-producing steps MUST NOT apply material deltas or trigger material conservation checks.
3. Material conservation checks apply only to material steps.
4. Readout outputs are persisted as data_ref / data_group_ref plus optional raw artifacts and may be consumed by later analytical steps.
5. Ordered material groups, including sep, frac, explicit groups, and plate selector-derived groups, remain addressable by later group[index] expressions. Static indexing resolves to the existing ordered member and does not allocate a replacement container.

9.15 Program And Exec-Options Binding Rule

For source-level contracts:

1. sep/frac bind mechanism configuration through explicit de-instrumentalized program arguments.
2. img/ecp/phy bind standard measurement targets through quantity = ... and optional schema_ref.
3. mutation_stmt (<<) no longer binds source-level program; execution requirements are expressed separately through constraint(...).
4. Constructor/init forms bind through AllocContainer / DefineContent / LoadContent plan steps after frontend lowering.
5. Semantic stage validates program family/field legality, quantity legality, schema_ref placement, and constraint compatibility.
6. Type stage checks quantity dimensions inside program fields, constructor loads, and indexed argument expressions.
7. Runtime receives only validated bound execution fields and does not infer missing source-level structure.

This preserves deterministic staged checking for Chapter 4 source-level call shapes.

9.16 Derived Run Summary Layer

Runtime execution and user-facing protocol summary are distinct layers.

Rules:

1. Atomic/operator return values are for in-protocol semantic references (data_ref, data_group_ref, sep_container_group, fraction_group, unit_stream_ref) rather than whole-run reporting.
2. Protocol-level return capture preserves the source return contract: returning an existing container value yields a container_ref payload, not a derived summary row or plain string alias.
3. Protocol-level reporting fields such as final products, used containers, process-step counts, and QC/readout rollups SHOULD be derived after execution from their owning runtime artifacts; structured runtime events MAY provide trace evidence where appropriate.
4. Material input inventory and reagent consumption MUST be derived from a run-scoped material-accounting record that is updated from material movements during execution rather than reconstructed from the event stream.
5. A derived run report is a projection over completed runtime artifacts, including the run-scoped material-accounting record; it is not a second execution pass.
6. CLI/tooling machine output MUST keep protocol returns separate from the derived run report.
7. Batch output MUST preserve an independent return value, derived report, diagnostics, and runtime artifact set for each run.
8. Derived summary generation MUST NOT rerun protocol semantics, mutate runtime truth, or redefine operator or protocol return contracts.
9. Material accounting MUST register both externally supplied initial inventory and stocks introduced by LoadContent as input lots.
10. Reagent consumption MUST include every consumed input lot without a presentation-oriented row limit and MUST exclude generated intermediate material unless that material was explicitly registered as an input lot.
11. Volume, mass, and cell count are independent accounting axes. A reagent-consumption JSON row MUST use null, rather than numeric zero, when the input lot has no quantity on an optional axis.
12. Quantity-changing material operations MUST expose auditable source-to-destination movements. Runtime MUST reject a quantity change for which no movement contract can be derived with MAT_MOVEMENT_CONTRACT_MISSING.
13. When an external inventory snapshot is supplied, the derived result MAY reconcile reagent consumption against that snapshot after runtime accounting completes.
14. External inventory sufficiency is a result field independent of runtime success. It MUST NOT mutate runtime state or retroactively redefine the runtime result.

9.16.1 Run-Scoped Material Accounting

Each run MUST maintain an independent material-accounting record. The record is updated as material movements occur and is made available to report projection after execution. The record itself is not part of the public serialized output contract.

The record MUST provide enough information to:

1. identify externally supplied initial inventory and stocks introduced by LoadContent as distinct input lots;
2. preserve input-lot provenance through source-to-destination movements;
3. associate each movement with its execution step, source, optional destination, and independent volume/mass/count quantities; and
4. determine consumed volume, mass, and cell count for each input lot without reconstructing that result from the event stream.

The internal representation and storage strategy are implementation-defined.

9.16.2 Derived Report Content

A derived run report SHOULD make the following information available when the corresponding runtime evidence exists:

Area	Required semantic content
execution	overall success, diagnostic count, and completed/failed/skipped step counts
materials	input inventory, final products, intermediate material, and reagent consumption
external inventory	optional sufficiency, shortages, and remaining quantities derived by reconciling reagent consumption with an external inventory snapshot
quality and readout	result identity plus result-specific measured or evaluated values
resources	allocated/touched containers, container kinds, and used tools or devices
process	counts grouped by mutation, separation, environment, and readout activity
alerts	user-facing alerts derived from runtime diagnostics

Material quantities MUST preserve their unit axis. Volume reporting SHOULD make microlitre and millilitre representations available where applicable; mass reporting uses milligrams. Missing optional values MUST remain distinguishable from numeric zero.

Concrete JSON keys, envelope names, schema-title strings, and implementation class names are serialization and compatibility concerns; they do not define the report semantics in this reference.

Typical summary inputs include:

1. completed runtime material state
2. the run-scoped material-accounting record
3. runtime data artifacts and data-group bindings
4. step status history and skip reasons
5. structured runtime events for trace-oriented summaries

Typical summary outputs include:

1. material input/final-product/reagent-consumption tables Input-inventory and reagent-consumption rows are derived from the run-scoped material-accounting record; final-product state remains a projection of completed runtime material state.
2. per-result container state summaries such as a preferred non-buffer primary component and derived primary concentration when deterministically computable
3. process summary counts by step family/tool class
4. resource-usage summaries such as container counts and tool/device usage
5. QC/readout result rollups
6. user-facing alerts derived from diagnostics

9.16.3 Inventory Check

Inventory check is an optional post-runtime reconciliation projection. It compares the completed run's material-accounting result with an immutable external inventory snapshot and reports availability without participating in material execution. The external snapshot is distinct from the input lots registered inside the run-scoped material-accounting record.

Rules:

1. Reconciliation reports whether inventory was checked and, when checked, whether the supplied inventory was sufficient.
2. A checked result identifies required, available, shortage, and remaining quantities on their original volume, mass, or count axes when those values are available.
3. External shortage does not make an otherwise successful runtime execution fail. Tooling or laboratory orchestration may separately decide whether the inventory result permits physical work to proceed.
4. Reconciliation must not create sources, increase quantities, rewrite movements, or alter the run-scoped material-accounting record.
5. Automatic purchasing, reservation, or restocking is outside core runtime semantics and requires a separate external integration.

9.17 Protocol Return Projection

Protocol return projection is the execution-boundary semantics for return expr; and return out = expr, ...;.

Rules:

1. A protocol return projects the resolved runtime value of the return expression into the output schema.
2. Projection is not source text echoing and is not an internal runtime-state dump.
3. Named returns name output ports only; the value projection rule is the same for positional and named return expressions.
4. Literal scalar values project as scalar values.
5. Quantity values project as structured quantity values with kind, value, and unit.
6. A resolved concrete material container projects as container_ref.
7. A resolved ordered concrete material container group projects as container_group_ref.
8. A resolved readout/data handle projects as data_ref.
9. A resolved ordered readout/data group projects as data_group_ref.
10. Readout/data returns are not coerced into material returns.
11. Material group returns are not coerced into readout/data returns.
12. CLI and tool formatting MUST render projected values; formatting MUST NOT decide or redefine projection semantics.
13. A count-bearing container_ref includes aggregate count_cells and dimensioned component_quantities; count fields may be omitted when no count-bearing content is present for backward-compatible volume/mass projections.

container_group_ref contract:

1. It represents an ordered group of concrete material containers at the protocol boundary.
2. members contains container_ref projections for each concrete member.
3. member_count equals the number of projected members.
4. Member order MUST preserve the order of the source/runtime group. For sep, this is the fixed slot order group[0], group[1]. For frac, this is ascending fraction index order. For source group([...]), this is source element order. For a plate selector-derived group, this is selector expansion order.

Minimal shape:

{
  "kind": "container_group_ref",
  "member_count": 2,
  "members": [
    {
      "kind": "container_ref",
      "id": "A1",
      "container_kind": "well",
      "volume_uL": 20,
      "mass_mg": 20
    },
    {
      "kind": "container_ref",
      "id": "A2",
      "container_kind": "well",
      "volume_uL": 20,
      "mass_mg": 20
    }
  ]
}

Compatibility boundary:

1. Composite list/record return projection is reserved for a follow-up compatibility decision. Baseline conformance requires explicit container-group projection for ordered concrete material groups.
2. Unresolved protocol returns SHOULD surface runtime diagnostics rather than silently producing successful null outputs. Tightening this behavior requires diagnostic mapping updates in Chapter 8 and conformance rows in Chapter 12.