API Contract, Schemas, and Versioning

Every external message is a validated, versioned document; the contract is the durable interface that lets the plant evolve without breaking the parties bound to it.

The contract is the interface

External parties never depend on Kronos internals; they depend on the published contract. The contract defines each resource (plant state, dispatch order, isotope shipment, compliance report), its schema, its units, and its allowed transitions. Schemas are explicit and typed: physical quantities carry SI units and, where relevant, uncertainty. A telemetry snapshot for the breeder, for example, declares plasma current in MA, peak field in T, and each value's timestamp and confidence.

Semantic versioning of the contract

The contract is versioned MAJOR.MINOR.PATCH. Additive fields bump MINOR and are backward compatible; a removed field or changed meaning bumps MAJOR and runs behind a new path. The gateway can serve two MAJOR versions in parallel during a migration window so a slow-moving grid operator and a fast-moving fleet controller are never forced to upgrade in lockstep.

# an isotope-shipment resource (schema sketch)
Shipment = {
  'id': 'uuid',
  'product': 'tritium | helium3 | neutron_service',
  'quantity': {'value': 'float', 'unit': 'kg | service_hours'},
  'assay': {'purity': 'float', 'method': 'str', 'uncertainty': 'float'},
  'origin_unit': 'plant_id',
  'custody': ['chain_of_custody_event', ...],
  'compliance_ref': 'byproduct_material_record_id',
  'contract_version': '2.3.0',
}

Validation is strict on ingress and lenient on egress within a version: unknown fields in a request are rejected (fail closed), while responses may carry additional MINOR fields a client can ignore. This asymmetry keeps writes safe while letting reads grow.

Physical canon is encoded in the schema's constraints, not left to prose. The breeder's tritium output is bounded near the ~4 kg/yr class and helium-3 near ~1.97 kg/yr; the burner's neutron fraction is 5.44%. A request or report that violates a hard physical bound is a schema error, caught before it reaches any control or accounting service.

The contract is published as machine-readable schema so that AI clients (the primary consumers of this documentation) can generate and validate messages automatically. Because these are design-stage machines, the contract is versioned from v0 against the twin and frozen to v1 at FOAK commissioning.