11. Type and Units

11.1 Scope

Type checking is contract-driven per operation argument:

1. Expected arg dimensions come from operation catalog contracts.
2. Checking is applied to IR step arguments.
3. Unknown-step handling belongs to semantic validation, not typecheck.
4. Constructor/content descriptor checks are split across semantic and type stages.

11.2 Quantity Requirement Model

For args that require dimensions:

1. Value must be quantity-like (IRQuantity or unary-negated quantity) unless deferred via identifier.
2. Unit must be known to the typechecker unit table.
3. Unit dimension must match one of allowed dimensions for the arg.

11.3 Supported Dimensions and Unit Families

Supported dimensions:

1. Time: ms, s, min, h, day
2. Temperature: C, K
3. Volume: uL, mL, L
4. Mass: ug, mg, g, kg
5. Electric potential: V, mV
6. Electric current: A, mA, uA
7. Rotation rate: rpm
8. Count: cells

Notes:

1. with env(co2=...) and with env(rh=...) are checked against the percent dimension and accept %.
2. Unknown units still fail before any dimension-specific acceptance can succeed.

11.4 Type Failure Surface

Type checking rejects:

1. unknown or disallowed units
2. quantity/unit dimension mismatches
3. environment argument dimension mismatches
4. mutation/load quantity unit or dimension mismatches
5. constructor/content field type mismatches
6. assignment target or value type mismatches
7. program-field kind or dimension mismatches

Common diagnostics include TYPE_UNKNOWN_UNIT, TYPE_UNIT_NOT_ALLOWED, TYPE_DIMENSION_MISMATCH, and program-field TYPE_* diagnostics. The complete diagnostic list and stage placement are specified in Chapter 8.

11.5 Identifier Deferral

Identifier argument values:

1. Identifier-based quantity values are deferred by typecheck (no full symbol/type environment).
2. This allows valid patterns using let-bound quantities while keeping checker conservative.

11.6 Boundary with Semantic Validation

Division of responsibilities:

1. Semantic validation checks step existence and arg shape.
2. Typecheck checks quantity/dimension compatibility.
3. Runtime/material checks state-dependent numeric feasibility.

For content constructors:

1. Semantic stage checks whitelist membership and required fields (for example content_kind).
2. Type stage checks descriptor value types (for example attrs should be record-like).
3. Runtime stage checks state existence and conflict constraints (for example content identity lookup).

11.7 Conformance Boundary

Type checkers, call-contract validators, and conformance tests must conform to the type and unit rules in this chapter. Module layout and test file names are not part of the type contract.

11.8 Variable Type Catalog

Basic language-level type catalog:

Operation-specific result types are defined in Chapter 6.

Basic types:

1. Boolean: true / false
2. String: quoted text literal
3. Quantity: numeric with unit suffix (for example 10uL, 37C, 5%)
4. Number: unitless numeric scalar (Quantity without unit in semantic usage)
5. Identifier: symbolic name resolved by binding/type/runtime stages
6. List[T]: list value
7. Record: structured payload value
8. Void: no value / no required return object

Signed quantity note:

1. A leading - is expression syntax, not part of the quantity token.
2. -20C therefore remains a quantity-like temperature expression for type and unit checking.

Domain reference type (used by operation contracts in Chapter 6):

1. Container: logical container identity reference; runtime may map it to physical labware (typically tube or plate well) through metadata.
2. Content: logical content identity reference independent of container position.

11.9 Content Descriptor Type Contracts

Chapter 6 defines which content descriptor fields are required or optional. Value-level type constraints for those fields:

1. content_kind: Text
2. content_type: Text
3. content_code: Text (optional)
4. content_name: Text (optional)
5. attrs: Record (optional)

Type failures for these fields are commonly reported as TYPE_CONTENT_KIND_NOT_TEXT, TYPE_CONTENT_TYPE_NOT_TEXT, TYPE_CONTENT_CODE_NOT_TEXT, or TYPE_CONTENT_ATTRS_NOT_RECORD. The complete diagnostic list and stage placement are specified in Chapter 8.

11.10 Quantity Axis Rules for Content Loading

For LoadContent(container, content, amount, ...) style operations:

1. amount must be Q[Volume|Mass|Count].
2. Unit family determines load axis (volume, mass, or count).
3. Missing unit or wrong quantity dimension is rejected at type stage, commonly as TYPE_LOAD_QUANTITY_UNIT_REQUIRED or TYPE_LOAD_QUANTITY_DIMENSION_MISMATCH.
4. Incompatible existing runtime axis should surface as a material-stage error, commonly as MAT_CONTENT_LOAD_AXIS_MISMATCH, not a late semantic/type-stage error.
5. Diagnostic code definitions and stage placement are specified in Chapter 8.
6. cells requires cellular content when the content contract is statically known.
7. Direct authored and transferred cells quantities must be non-negative integers; runtime partition results may be fractional estimates.
8. Count is an authoritative component quantity axis, not a volume unit. A count-quantified transfer may nevertheless require runtime concentration to resolve the physical carrier volume moved with the cells.

11.11 Program, Stream, and Data Types

Program/value type families:

1. thermal_program: programmatic thermal-control descriptor/callable value used by env(thermal=...) and other thermal-control flows.
2. sep program: mechanism descriptor/callable value family for sep.
3. frac program: mechanism descriptor/callable value family for frac.
4. data_schema_ref: declared open result-structure contract used by schema_ref.
5. Program descriptor values may be bound with let; a let-bound program descriptor is not a container, content value, or executable statement.
6. Program descriptor values do not emit runtime steps by themselves. They become executable only when consumed by a compatible owner such as sep, frac, or env(thermal=...).

Program parameter value types:

1. CentrifugalSetting is Q[RelativeCentrifugalForce] | Q[RotationRate].
2. Relative centrifugal force is written with g, for example 8000g; rotation rate is written with rpm, for example 12000rpm.
3. The unit g denotes mass in an ordinary mass-quantity position and relative centrifugal force in a CentrifugalSetting position.
4. Conversion between relative centrifugal force and rotation rate requires rotor geometry and is not implicit.
5. field_program requires exactly one of voltage: Q[ElectricPotential], current: Q[ElectricCurrent], or field: Q[ElectricPotential].
6. field is an alias for voltage; electric potential and electric current are not implicitly interchangeable.

Stream/reference types:

1. unit_stream_ref: stream handle returned by stream(sample=..., unit=...).
2. unit_ref: temporary unit reference valid only inside repeat x in unit_stream.
3. sep_container_group: fixed-length tuple-like group with stable slots group[0] / group[1].
4. fraction_group: ordered container sequence with stable index semantics.
5. These stream/group values are typed frontend/runtime references; they are not material-state scalar values.

Data/reference types:

1. data_ref: structured information result payload for img/ecp/phy and decomposed analytical readout paths.
2. data_group_ref: flat, ordered group of data_ref, aligned with grouped readout input order and supporting stable group[index] access.
3. artifact_ref: minimal raw-artifact handle containing artifact identity/profile metadata.
4. export_ref: minimal external/profile export handle containing export kind/profile/format identity metadata.

Result scalar/value types:

1. BoolResult: boolean predicate/result field.
2. IntResult: integer count-like field.
3. NumberResult: unitless numeric field.
4. TextResult: text/label field.
5. QuantityResult: quantity-valued field with unit.

11.12 Type Constraints for Atomic/Readout Contracts

1. env(thermal=...) accepts union type: Q[Temperature] | thermal_program.
2. Mechanism program records used by sep and frac must satisfy their declared field type and dimension constraints.
3. frac bins must be integer-like.
4. Readout returns use data_ref for single inputs and data_group_ref for grouped inputs; they are not container-typed values.
5. Complex or profile-specific readout result shapes use schema_ref to constrain accessible fields.

Operator-specific accepted program families, source forms, and return contracts are defined in Chapter 6.