Reactor Semantics

The U0 reactor-semantic API gives fusion, magneto-inertial-fusion, and control systems one explicit vocabulary for saying what a signal means. It is a description and review surface. It cannot admit a control action or actuate a plant.

Ownership boundary

Concern	Owner	U0 rule
Plant and solver truth	SCPN-FUSION-CORE, SCPN-MIF-CORE	SPO consumes declared values, units, frames, clocks, calibration, validity, and provenance; it does not invent them.
Semantic interpretation	SCPN-PHASE-ORCHESTRATOR	SPO assigns typed carrier meaning, checks comparability, and emits review evidence.
Admission and action	SCPN-CONTROL	CONTROL alone decides whether evidence is admissible for an action. U0 records remain review_only.

ReactorContext is faceted instead of tokamak-shaped. Configuration/topology, confinement, drivers, cadence, reaction/fuel, conversion boundary, facility, coordinate frame, evidence class, event identity, and operating point are independent fields. Pulsed, repetitive-target, and single-experiment contexts require an opaque plant- or integrator-supplied event_id; U0 never invents a shot_id. Registry release 1.1.0 includes 34 configurations: the immutable 32-entry 1.0.0 built-in release plus namespaced lattice-confinement and muon-catalysed-fusion extensions.

The separate DEFAULT_REACTOR_SEMANTIC_PROFILE_REGISTRY binds every one of those 34 configurations to its device-family project without claiming that a project assignment is already a semantic producer. Its versioned canonical record is sealed to the reactor-registry digest and the cross-project assignment-map SHA-256. Only conventional_tokamak through the exercised FUSION/TORAX adapter and frc_compression_mif through the exercised MIF adapter currently have verified_review_adapter ingress. The other thirty-two records are explicitly not_declared: they advertise no producer, source schema, adapter API, handoff schema, or semantic profile.

The profile registry is a descriptive SPO binding for producer and consumer contract discovery. It does not replace device-owned reactor-domain.json, declare capability evidence maturity, or determine Studio federation state. It never supplies an implicit generic adapter. CONTROL adapter contracts remain separately versioned fields and are currently absent. The public ReactorResearchControlIntent research-hypothesis schema exists, but no profile advertises it because no producer-to-CONTROL path has exercised it. All profiles are review_only, actionable=false, and preserve independent machine protection as the final veto.

DEFAULT_REACTOR_OBSERVABILITY_PROFILE_REGISTRY adds the machine-readable candidate layer. It covers every registered configuration with explicit direct_cyclic, derived_cyclic, event_relative, noncyclic_feature, and numerical_only routes plus a fail-closed unobservable result. Each candidate fixes its admissible carrier set, reference/repetition/operator requirements, minimum evidence fields, and the disposition when evidence is missing. These records always carry evidence_claimed=false: applicability is a research and schema requirement, never proof that the diagnostic or signal exists.

The catalogue keeps equilibrium profiles, trajectories, yields, and blanket response noncyclic; requires validated modal operators for MHD, pinch, implosion, liner, and electrostatic oscillation phase; requires facility or event references for drive and shot timing; and confines synthetic oscillator coordinates to numerical_phase. It therefore provides a deterministic gap map without allowing architecture-only projects to advertise observations.

Device diagnostic-plan design review

device_diagnostic_plan_review_from_producer_bytes() is the reactor-family- neutral intake for a device owner's portable diagnostic and clock plan. It accepts exact manifest, envelope, and plan bytes plus two identities that the current producer envelope cannot supply uniquely: a 40-character source Git revision and the SHA-256 of the exact installed wheel artefact. The producer's package revision remains a separate field. SPO never imports or executes the device package while interpreting these bytes.

The v1 intake accepts only canonical scpn.reactor-domain.v1 manifest bytes and canonical scpn.reactor-diagnostic-plan-envelope.v1 bytes. It dispatches versions 1.1.0 and 1.2.0 to separate exact plan and channel shapes; fields cannot be omitted, defaulted, or moved between versions. It recomputes the raw manifest and plan digests, rejects recursive key drift, and resolves project ownership, configurations, candidate IDs, observability classes, carriers, evidence slots, and registry pins against SPO's installed frozen registries. Planned and explicitly deferred candidates must cover the applicable catalogue exactly.

Version 1.2.0 adds declaration-only signal inventories, frame transformations, and physical-clock topology. SPO checks exact signal roles, event-marker units, numerical-only phase declarations, admissible frame-kind transformations, connected frames, non-overlapping clock domains, rooted relations, and an acyclic reference topology. Signal quantity and unit text cannot override the registered candidate, carrier, observation state, or phase meaning. Mapping declarations cannot claim evidence, and every accepted 1.2 source document remains embedded byte-for-byte in the review output.

Each DeviceDiagnosticSignalReview preserves the candidate, its derived_cyclic, event_relative, noncyclic_feature, or numerical_only class, the admissible carrier, clock identity, and exact required evidence-slot names. It does not claim that the slots contain observations. A bounded feature therefore remains bounded, an event cycle remains event-relative, and a model oscillator remains numerical phase.

Producer clock vocabulary is not coerced into SPO vocabulary. simulation is only a simulation_monotonic candidate, shot_event_epoch is only shot-relative compatible, and facility_monotonic remains explicitly unmapped. A declared offset bound is not facility synchronisation, wall time, or correlation evidence.

DeviceDiagnosticPlanReview embeds the exact three source documents and seals their digests, source commit, artefact digest, registry identities, typed signal rows, clock rows, candidate coverage, and reference frames. Its fixed verdict is design-declaration-only: no measurement, physical observation, facility binding, classification, semantic ingress, control intent, action, or actuation is created. The portable envelope is defined by device_diagnostic_plan_review.schema.json.

Exact producer fixtures currently exercise this intake for tokamak, dense- plasma-focus, theta-pinch, Z-pinch, MagLIF, mechanical-or-liquid-liner MIF, plasma-jet MIF, laser-ICF, ICF-beam, and ICF-impact device plans. The dense-plasma-focus review keeps a shot-relative discharge-current event_cycle, a facility-clocked neck-mode complex_mode, and a simulation-clocked numerical_phase distinct. The theta-pinch review separately keeps a shot-relative bank-waveform event_cycle, a facility-clocked rotation-probe complex_mode, and a simulation-clocked numerical_phase distinct. The Z-pinch review separately keeps a shot-relative current-and-voltage event_cycle, a facility-clocked pinch-mode complex_mode, and a simulation-clocked numerical_phase distinct. The two liner-MIF reviews keep compression-trajectory bounded_feature, liner-arrival event_cycle, resolved-asymmetry complex_mode, and model numerical_phase distinct. Plasma-jet MIF separately keeps convergence trajectory bounded_feature, jet-arrival event_cycle, merge-asymmetry complex_mode, and model numerical_phase distinct. Laser ICF separately keeps beam timing event_cycle, resolved asymmetry complex_mode, shot outcome and implosion trajectory as distinct bounded_feature rows, and the model oscillator as numerical_phase. Beam ICF separately keeps bunch timing event_cycle, resolved asymmetry complex_mode, shot outcome and implosion trajectory as distinct bounded_feature rows, and the model oscillator as numerical_phase. Impact ICF separately keeps impact timing event_cycle, resolved asymmetry complex_mode, shot outcome and implosion trajectory as distinct bounded_feature rows, and the model oscillator as numerical_phase. None of these similarities equates device or configuration identities, frames, timing bounds, or timescales. In particular, one shared laser-ICF plan does not equate direct drive, indirect drive, and fast/shock ignition. The ICF-beam plan does not equate its ion-beam and pulsed-electron-beam configurations. The ICF-impact plan does not inherit either plan's evidence. The theta-pinch plan does not inherit dense-plasma-focus or z-pinch evidence merely because all three configurations are self-magnetic. One shared Z-pinch plan does not equate the z_pinch and sheared_flow_z_pinch configurations or create evidence for either. Facility clocks remain unmapped, event timing uncertainties remain explicit, and all thirteen device-plan-only semantic-ingress profiles remain not_declared. Passing a design review does not add source evidence to the reactor configuration evidence matrix.

Accepted-plan to physical-evidence request

device_physical_evidence_request_from_plan_review() converts one accepted device-plan review into a request for one exact configuration. It embeds and replays the complete review, pins current reactor, observability, and semantic- profile registries, preserves every planned or deferred candidate, and lists the plan clocks that still require physical correlation. It never executes the producer package.

The first materialised instance targets only laser_icf_direct_drive. Beam timing remains event-relative, resolved implosion asymmetry remains a derived cyclic quantity requiring a validated observation operator, trajectory and shot outcome remain noncyclic, and the synthetic oscillator remains numerical_only and physically ineligible. Sharing an ICF-laser plan does not transfer evidence to indirect-drive or fast/shock-ignition configurations.

The second instance targets only ion_beam_icf from the independently pinned SCPN-ICF-BEAM-CORE review. Bunch timing remains event-relative and the same cyclic/noncyclic/numerical distinctions stay explicit. The host-independent materialisation CLI reads only exact local fixture bytes and never imports or executes producer source.

The third instance targets only projectile_or_impact_icf from exact SCPN-ICF-IMPACT-CORE fixture and wheel custody. Impact timing remains event- relative, asymmetry remains derived-cyclic, trajectory and outcome remain noncyclic, and model phase remains numerical-only. The review owns no other configuration, so the public factory refuses laser, ion-beam, pulsed-electron- beam, and generic beam-target request construction instead of transferring evidence by topology.

The fourth instance targets only pulsed_electron_beam_icf. It deliberately shares the sealed SCPN-ICF-BEAM-CORE review with the ion-beam instance while deriving a different request ID. This proves that review custody can be shared without transferring a physical sample, phase, validity, regime, semantic-ingress state, CONTROL admission, or authority between configurations.

The fifth instance targets only laser_icf_fast_or_shock_ignition. It shares the exact sealed SCPN-ICF-LASER-CORE review with direct drive while deriving a configuration-specific request ID. Beam timing, derived asymmetry, noncyclic trajectory and outcome, and numerical-only model phase retain their distinct meanings; direct-drive evidence or authority is never inherited.

All thirteen physical-evidence obligations remain missing, including physical sample and diagnostic identity, reference and clock correlation, calibration or observation operator, uncertainty, validity, producer evidence-state semantics, quality, reproducibility, observability, and independent validation. New peer discoveries enter as source-bound gaps or provisional candidates; they do not become physical evidence or silently rewrite released meaning.

The request is review_only, non-actionable, non-executing, non-actuating, and cannot request CONTROL admission. Its portable envelope is defined by device_physical_evidence_request.schema.json, with the sealed instances documented in the device physical-evidence request reference.

The companion reactor diagnostic-plan portfolio status records the exact structural-review result for all 22 Reactor Systems device projects. Seven exact producer objects are accepted, thirteen are refused on current owner-side manifest or digest mismatches, and the lattice and muon architecture projects have no declared diagnostic plan. The register is review-only and creates no physical observation, physical phase, CONTROL intent, action, execution, actuation, or machine-protection authority.

External reactor technology and diagnostic atlas

The reactor technology and diagnostic atlas maps all 34 registered configurations across nine confinement families to 37 configuration-specific facility, government-programme, and peer-reviewed sources. Its E5 through E0 ranks describe only the strongest cited external technology evidence. They are not readiness, economics, SCPN implementation, signal admissibility, physical-phase qualification, or CONTROL authority.

The atlas makes external availability, development, and missing capability explicit while refusing every row at the SPO physical-observation boundary. Literature and facility pages are not producer payloads: all rows still lack the complete phenomenon, reference, clock, observation operator or calibration, uncertainty, validity, quality, provenance, and observability-gate chain. Every result is review_only, actionable=false, and preserves independent machine protection as the final veto.

Producer-evidence intake priority

The reactor producer-evidence priority register joins all 34 configurations to exact atlas, occurrence, observability, semantic-ingress, and diagnostic-plan custody across 24 upstream reactor projects plus the CONTROL boundary. Its five readiness lanes contain one reviewed physical-source qualification, two exercised-adapter extensions, two missing diagnostic plans, 13 accepted-plan physical intakes, and 16 configuration rows blocked by refused plans.

The register emits no scalar score and deliberately leaves rows within one lane unordered. External evidence rank never changes the lane. Every producer request still requires a physical sample, phenomenon identity, reference, clock epoch, observation operator or calibration, uncertainty, validity, quality, provenance, observability gate, immutable source revision, reproducible package identity, canonical bytes, and independent validation. The register is review-only, non-actionable, non-actuating, and preserves independent machine protection as the final veto.

Conventional-tokamak L1 physical-payload request

conventional_tokamak_physical_payload_request() materialises the L1 request to SCPN-FUSION-CORE. It binds the exact verified TORAX source schema, adapter API, review-only handoff schema, semantic profile, semantic-profile registry, and observability registry. The bound adapter is fixed as simulation-only, with physical_source_present=false and reusable_as_physical_evidence=false; its twelve noncyclic TORAX observables cannot be relabelled as diagnostic samples or phase evidence.

Request version 1.1.0 embeds the shared producer evidence-state policy. It requires distinct unknown, out_of_distribution, low_observability, and stale dispositions about current plant truth, maps them exactly to U0 validity, and forces physical-regime abstention. Quality cannot substitute for the evidence cause.

The request carries four unselected conventional-tokamak candidates and thirteen missing producer obligations: physical samples, configuration-specific diagnostic identity, phenomenon, reference, physical clocks, observation operator or calibration, uncertainty, validity, producer evidence-state semantics, quality, immutable provenance and reproducibility, a predeclared observability gate, and independent validation. A producer must allocate a new configuration-specific canonical physical payload rather than place physical claims into the simulation schema.

ConventionalTokamakPhysicalPayloadRequest fixes schema allocation, physical source presence, candidate selection, observation admission, phase inference, semantic-ingress extension, CONTROL admission, action, execution, and actuation to their fail-closed states. Its canonical envelope is defined by conventional_tokamak_physical_payload_request.schema.json.

FRC-compression MIF L1 physical-payload request

frc_compression_mif_physical_payload_request() materialises the L1 request to SCPN-MIF-CORE. It binds the exact verified merge-compression source schema, adapter API, review-only handoff schema, semantic profile, semantic-profile registry, and observability registry. The bound adapter is fixed as simulation-only: its mif_model facility, simulation-monotonic clock, model coordinates, merge predicates, and trigger decision are not physical diagnostic evidence.

The request carries four unselected FRC-compression-MIF candidates: driver arrival, resolved asymmetry, translation and compression, and the simulation-only synthetic oscillator coordinate. It names twelve missing producer obligations: physical samples, configuration-specific diagnostic identity, phenomenon, reference, physical clocks, observation operator or calibration, uncertainty, validity, quality, immutable provenance and reproducibility, a predeclared observability gate, and independent validation. SCPN-MIF-CORE must allocate a new configuration-specific canonical physical payload rather than place physical claims into the simulation schema.

FRCCompressionMIFPhysicalPayloadRequest fixes schema allocation, physical source presence, candidate selection, observation admission, phase inference, semantic-ingress extension, CONTROL admission, action, execution, and actuation to their fail-closed states. Its canonical envelope is defined by frc_compression_mif_physical_payload_request.schema.json.

FAIR-MAST magnetic physical-source review

mast_magnetic_source_review_from_producer_bytes() accepts the exact canonical complete-magnetic archive envelope and diagnostic-qualification bytes emitted by SCPN-FUSION-CORE. The intake imports no sibling package. Its caller must pin the full producer Git revision and the SHA-256 of the exact producer wheel; the review separately preserves both source documents, their outer and payload digests, the FAIR-MAST ingestion revision, and the source tree state.

The v1 contract is deliberately specific to the complete shot-27707 FAIR-MAST inventory: 72 arrays, 11 measurement families, 132 qualified channel records, and four reproduced archive grids. Every array, clock, measurement, empirical- quality row, channel-quality row, identifier-only geometry row, completeness claim, event limitation, and archive-to-qualification binding is replayed from the embedded bytes. SCPN-FUSION-CORE is the physical-evidence producer; SCPN-TOKAMAK-CORE remains the spherical-tokamak device owner. This review does not alter the semantic-profile registry's not_declared producer state.

The producer qualification records applied transforms, but it supplies no calibration lineage or transfer functions. It also supplies no physical geometry join, provider quality flags, uncertainty, instrument-clock relation, or resolved facility event identity. The four clock rows are therefore only shot-relative candidates for derived archive grids. They are not instrument clocks and are not mapped to facility, plant-monotonic, simulation-monotonic, or wall time.

MastMagneticSourceReview records authentic physical-source custody while fixing observation_admitted=false, qualified_phase_evidence=false, phase_inference_performed=false, semantic_ingress_declared=false, and classification_performed=false. It cannot create CONTROL intent, execution permission, direct actuation, or actionability; independent machine protection retains the final veto. The canonical review envelope is defined by mast_magnetic_source_review.schema.json.

FAIR-MAST phase-qualification prerequisite request

mast_phase_qualification_request_from_source_review() converts the complete source review into a self-contained, byte-canonical producer request. It binds the source review ID and digest, exact FUSION revision and wheel digest, archive and qualification file/payload digests, ingestion revision and tree state, source-review unresolved fields, shot identity, and the exact observability- registry version and digest. Four spherical-tokamak candidate profiles are embedded as unselected design requirements; none is reported as the observed phenomenon.

Version 1.1.0 also embeds the shared producer evidence-state policy. It requires distinct unknown, out_of_distribution, low_observability, and stale dispositions about current plant truth. These map respectively to U0 validity unknown, out_of_distribution, unobservable, and stale; every mapping forces an unclassified RegimeState.UNKNOWN result. Provider quality is orthogonal and cannot substitute for the disposition. A small score above a predeclared observability gate is not low_observability.

The request keeps thirteen missing evidence obligations separate: controlled phenomenon identity; reproducible source-ingestion state; calibration lineage; physical geometry and frame join; modal observation operator and harmonic basis; provider quality; uncertainty; validity; producer evidence-state semantics; instrument-to-facility clock correlation; resolved event identity; predeclared observability threshold; and independent multi-shot or classifier validation. Each obligation has a producer-facing acceptance condition and requires immutable artifact binding.

MastPhaseQualificationRequest fixes the qualification state to blocked_missing_producer_evidence. It cannot select a phenomenon, admit an observation, make phase inference eligible, declare semantic ingress, request CONTROL admission, create control intent, permit execution, or authorise actuation. Its canonical envelope is defined by mast_phase_qualification_request.schema.json.

DEFAULT_REACTOR_REGIME_MODE_ONTOLOGY closes the remaining open-text meaning above U0 without changing the U0 1.0.0 wire format. It defines eight independent axes: plant readiness, diagnostic observability, confinement or assembly, stability or symmetry, driver synchronization, power or burn, exhaust or boundary, and evidence maturity. Every axis has a closed label vocabulary and explicit universal or context-dependent applicability.

ReactorRegimeAxisAssignment keeps three cases distinct. An applicable axis requires a defined non-unknown label and classification evidence; not_applicable requires a context basis and forbids a physics label; and unknown reports that applicability or classification is unresolved. The last two project into U0 as literal not_applicable and unknown labels with zero confidence. Neither can silently become nominal.

The same ontology names six physical mode families for closed-field MHD, open-field interchange, self-magnetic pinch instability, inertial asymmetry, magneto-inertial asymmetry, and IEC bunching. A physical ReactorModeBinding is valid only with an exact reactor configuration, compatible observability candidate and carrier, physical harmonic basis, operator, frame, reference, orientation, origin, wrap convention, observability threshold, validity, quality, provenance, and admissible evidence class. The separate all-configuration synthetic-oscillator definition admits only numerical_phase with simulation evidence and no physical harmonic. It is an explicit fallback, not a claim of equivalence to a plasma mode.

The ontology record is sealed to the exact reactor and observability registry versions and SHA-256 digests. It remains review_only and actionable=false; it validates identity and refusal rules but performs no classification, extraction, CONTROL admission, machine-protection decision, or actuation.

The deterministic reference portfolio exercises nine non-exclusive design slices:

• A1 axisymmetric tokamak,
• N1 stellarator,
• C1 compact toroid/FRC,
• O1 open-field mirror/cusp,
• P1 Z-pinch/dense-focus,
• I1 inertial fusion/IFE,
• H1 MagLIF/MIF,
• E1 IEC/beam-target, and
• X1 fusion-fission/direct-conversion contexts.

These are scaffold fixtures, not experimental validation or reactor-readiness claims.

Five public contracts

• ReactorContext identifies the physical and facility context without a privileged reactor family.
• ObservableDescriptor binds a value to units, frame, spatial support, diagnostic/channel, clock, calibration, uncertainty, quality, validity, and provenance.
• PhaseSemanticRecord states the mathematical carrier and the declared origin, orientation, wrap convention, reference signal, extractor, observation operator, confidence, and observability threshold.
• PhaseRelation exists only after frame, clock, harmonic, context, and validity compatibility checks pass or explicit transforms are supplied.
• RegimeEstimate preserves independent regime axes, hysteresis, dwell time, threshold provenance, transition reason, and fail-closed validity while fixing its authority to review only.

Eight carriers are not interchangeable

U0 preserves cyclic_phase, complex_mode, field_phase, event_cycle, bounded_feature, categorical_state, protocol_phase, and numerical_phase. A bounded feature, categorical state, protocol stage, or raw event count cannot acquire an angle merely by normalization. Event-cycle phase requires a declared reference signal. Numerical phase cannot claim observed or experimental evidence.

Legacy FusionCoreBridge.observables_to_phases() normalizes scalar features and event-count parity into oscillator coordinates. That method predates U0 and is not a valid U0 semantic producer. A consumer must cross the U0 contract surface and satisfy the carrier-specific checks before comparing or exporting reactor phase meaning.

Fail-closed behavior

Every phase-bearing record declares its own observability threshold; U0 does not impose a universal physics threshold. Below that threshold, validity must be unobservable and phase_rad must be absent. unknown, stale, out_of_distribution, unobservable, and invalid records cannot be compared as usable phases. Non-usable regime evidence can only publish the top-level state unknown.

ProducerEvidenceDisposition makes the producer-side reason explicit without inventing a physical plasma state. Its exhaustive policy is:

Producer disposition	U0 ValidityState	Physical-regime result
unknown	unknown	unclassified RegimeState.UNKNOWN
out_of_distribution	out_of_distribution	unclassified RegimeState.UNKNOWN
low_observability	unobservable	unclassified RegimeState.UNKNOWN
stale	stale	unclassified RegimeState.UNKNOWN

These values describe evidence disposition about current plant truth. They are not physical regime labels, protocol states, quality grades, or action states. producer_evidence_state_policy() rejects untyped string aliases, always sets physical_regime_classified=false, and fixes quality_may_substitute=false. low_observability means below the predeclared observability or minimum-evidence gate; a merely small score above that gate does not qualify. OOD is outside a versioned validated applicability domain, while stale is outside the declared freshness or validity window for the current classification time.

Clock records distinguish plant-monotonic, simulation-monotonic, shot-relative, facility-synchronised, wall-clock, model-tick, and unknown time bases. They carry an explicit epoch and preserve a 0–999 picosecond offset in addition to the integer nanosecond timestamp. Mixed time bases or epochs need an explicit clock transform. validate_observable_sequence additionally rejects mixed streams and non-monotonic or unusable samples.

Serialization uses a strict typed envelope and canonical sorted JSON. Unknown fields, missing fields, duplicate JSON keys, unknown contract kinds, registry drift, unsupported schema versions, and envelope/payload version disagreement are refused. U0 currently accepts exactly schema 1.0.0; compatibility is not guessed.

The portable exchange shape is published as reactor_semantics_u0.schema.json. JSON Schema validates transport structure; the Python runtime additionally enforces registry identity and the cross-field physics/epistemic invariants.

Coupled-transport review handoff

coupled_transport_handoff_from_fusion_bytes() is the public producer adapter. It accepts only canonical scpn-fusion-core.torax-runtime-review-envelope.v1 bytes and independently checks the byte digest, nested payload digest, exact source and model-intersection schemas, Git revision, event identity, provenance digests, simulation clock, completion, solver numerics, U0 registry identity, and the declared non-empirical calibration. It has no runtime dependency on FUSION, TORAX, NumPy, Julia, or an accelerator.

The accepted evidence set is closed: four radial profiles (electron density, electron temperature, ion temperature, and poloidal flux), five global source totals (driven current, electron heat, ion-electron exchange, ion heat, and particles), and three state budgets (particle inventory, poloidal-flux L2, and thermal energy). The normalised rho axis is spatial support, not a thirteenth observable. Profile rows and scalar series must match every clock sample before the adapter selects the final sample. Each quantity has one exact unit and a category-matched absolute_rms_difference plus relative_l2; the absolute RMS is carried in U0's standard-deviation field with confidence fixed to zero and provenance stating that it is numerical, not statistical or empirical.

The frozen TORAX deck contains deuterium main ions and neon impurity but models no fusion reaction, burn, or fusion power. deuterium_deuterium therefore identifies only the evidence-supported fuel class. The producer must retain the explicit deuterium_only_input_no_fusion_power_or_burn_model qualifier; SPO refuses an unqualified reaction label.

ReactorSemanticHandoff carries one exact canonical FUSION producer envelope alongside its U0 interpretation. The source bytes and the complete handoff payload have independent SHA-256 seals, so a downstream reviewer can verify the producer-to-semantics chain without trusting a live Python object graph.

The coupled-transport profile is deliberately narrow. Every observable retains FUSION provenance and shares one simulation-monotonic clock domain and epoch. SPO emits exactly one bounded_feature record per observable, with zero phase confidence and observability, unobservable phase validity, and explicit unknown phase quality. This expected phase-extraction state does not invalidate an otherwise usable nonphase observable or prevent review admission. Amplitude, angle, frequency, bandwidth, mode, harmonic, origin, orientation, wrap, reference signal, observation operator, and phase relations are forbidden. The regime remains unknown with zero confidence. The handoff fixes authority="review_only" and actionable=false; it has no path to ControlAction.

Cross-project consumers pass the exact serialized bytes to handoff_from_bytes(). It admits only the unique canonical UTF-8 encoding; handoff_from_json() remains the Python string surface for local composition. When no registry is supplied, the decoder resolves only the exact immutable registry release declared by the sealed payload's version-and-digest pair. This preserves recognised historical 1.0.0 bytes without requiring a consumer to preparse untrusted JSON. An explicitly supplied mismatched registry or an unknown release remains an error; serializers still require an explicit historical registry and never silently rewrite the object to the current one. Importing scpn_phase_orchestrator.reactor_semantics does not initialise UPDE, supervisor, native accelerator, or Julia runtimes. The decoder refuses duplicate keys, unknown or extra fields, digest drift, registry or U0 version drift, mixed clocks, missing event identity, FUSION ownership loss, phase relabeling, relations, regime inference, and authority escalation. The portable shape is published as reactor_semantic_handoff.schema.json.

Freshness is a consumer-owned admission policy. A consumer compares sample and calibration timestamps only against an explicitly supplied reference clock in the same domain and epoch; it must not compare simulation-monotonic evidence to wall time implicitly.

MIF merge-compression review handoff

mif_merge_compression_handoff_from_mif_bytes() is the dedicated adapter for scpn-mif-core.merge-compression-observation.v1. It accepts exact canonical SCPN-MIF-CORE bytes without importing or executing that sibling package. The adapter independently verifies source and payload digests, source revision, event identity, review-only authority, reactor vocabulary, complete simulation clock, model-evidence validity, kinematic vector shape, derived geometry, merge predicates, and trigger prerequisites.

The configuration is the registry's frc_compression_mif, whose family is magneto_inertial and whose topology is a compressed field-reversed configuration. The shorter frc alias is intentionally rejected because it resolves to an uncompressed magnetic-closed FRC.

Each serialized oscillator angle becomes one numerical_phase record. Its meaning is limited to the MIF model state: [0,2pi) wrap, positive model evolution, event-start origin and reference, identity model-state observation operator, simulation-monotonic clock, and simulation evidence. Position, velocity, phase-lock error, Kuramoto order parameter, tolerances, streaks, safety margin, and integrator error remain bounded_feature. Lock, trigger, and gate values remain categorical_state. Their phase observability is zero; none acquires an angle. V1 emits no phase relation and leaves the reactor regime unknown because MIF supplies no versioned regime classifier.

MIFMergeCompressionHandoff embeds the exact source JSON and its SHA-256 beside the complete U0 graph. mif_merge_compression_handoff_to_bytes() seals that graph in a second canonical envelope; mif_merge_compression_handoff_from_bytes() verifies the full chain and, when the caller omits a registry, resolves only the allowlisted exact release named by the sealed payload. Historical 1.0.0 and current 1.1.0 bytes therefore share one public admission surface without losing their distinct identities. Both source and handoff are fixed to review_only and actionable=false, and the module has no control-action dependency. The portable shape is published as mif_merge_compression_handoff.schema.json.

Portable reactor regime assessment

ReactorRegimeAssessment is the digest-sealed portable identity for one complete eight-axis regime vector. It binds the exact source handoff, event, reactor context, producer and source revisions, clock and validity window, and the exact reactor, semantic-profile, observability, and regime-ontology registries. Axis rows are always serialized in lexicographic axis_id order.

Each ReactorRegimeAxisAssessment separates ontology-derived static applicability from the result disposition: classified, unknown, or not_applicable. A classified row requires a closed ontology label, positive confidence and observability, probability uncertainty with a named basis, usable validity and quality, provenance, evidence IDs, and a typed binding for every evidence role required by that axis definition. Classifier identity is therefore required for confinement/assembly, while owner declaration, diagnostic inventory, clock/reference, reaction-model, boundary, or maturity roles remain distinct rather than being mislabeled as classifiers.

unknown is the correct result when a statically applicable axis lacks enough qualified evidence. It has no physics label, zero confidence, unit uncertainty probability, and an explicit reason; its evidence list may be empty. not_applicable is accepted only when the pinned ontology computes that result for the exact configuration. It cannot be used to hide missing evidence.

classification_performed=false states that this codec validates supplied results but never runs a classifier. The complete envelope and every axis are permanently review_only and non-actionable. No collapsed nominal/critical verdict, control target, actuator, CODAC, or interlock field exists. Consumers must independently retrieve the referenced artifacts; a syntactically valid digest is not proof of their contents. The current MIF handoff still supports only an all-unknown applicable vector plus ontology-derived non-applicability; the assessment contract does not upgrade numerical model state into measured physical evidence.

The transport shape is published as reactor_regime_assessment.schema.json.

Reactor research ControlIntent hypothesis

ReactorResearchControlIntent is a digest-sealed SPO research hypothesis for possible later CONTROL review. Its name does not confer CONTROL authority. The contract permanently fixes authority="review_only", actionable=false, and execution_permitted=false; it imports no supervisor, actuation, device adapter, or SCPN-CONTROL runtime.

Each hypothesis binds the exact SPO producer revision and artifact, source semantic handoff and producer revision, a prior CONTROL review-admission decision, a classified regime-axis assignment, semantic and evidence sets, registry/observability/ontology identities, and a device-owner control-contract schema and digest. Its candidate variable includes units, device bounds, evidence-bound baseline, proposed value and delta, direction, maximum delta and rate, proposed rate, and rate horizon. Complete clock identity, validity, evidence class, quality, confidence subject, observability, and unit-aware uncertainty remain explicit.

The objective vocabulary is restricted to five physical axes. The target vocabulary is narrower still: it refuses harmful and ambiguous targets and permits only established confinement/assembly, symmetric or quiescent stability, synchronized drivers, rising or sustained power/burn, and conditioned or regulated boundary/exhaust hypotheses. CONTROL must still apply its own objective/target/variable/direction allowlists.

The JSON Schema validates transport shape; the Python decoder additionally enforces sorted identifiers, ontology applicability, source and target labels, registry digests, baseline/delta/value equality, delta/rate/horizon equality, clock ordering, evidence quality, and non-actuation invariants. Neither proves an external digest merely by receiving it. A future consumer must independently decode or retrieve the exact source handoff, prior CONTROL decision, regime assignment, and device contract.

No current semantic profile declares this surface. In particular, the current MIF handoff has an unknown regime, while this contract requires a classified, valid, quality-qualified source assignment. CONTROL has no ControlIntent consumer or action edge. The portable shape is published as reactor_control_intent.schema.json.

from scpn_phase_orchestrator import (
    ObservableDescriptor,
    PhaseRelation,
    PhaseSemanticRecord,
    ReactorContext,
    RegimeEstimate,
)
from scpn_phase_orchestrator.reactor_semantics import (
    build_reactor_reference_portfolio,
    canonical_json,
    coupled_transport_handoff_from_fusion_bytes,
    handoff_from_bytes,
    handoff_to_bytes,
)

reference = build_reactor_reference_portfolio()
tokamak_context: ReactorContext = reference[0].context
payload = canonical_json(tokamak_context)

# Cross-project path: exact FUSION bytes -> SPO semantic bytes.
fusion_bytes = open("torax_runtime_review_envelope_v1.json", "rb").read()
semantic_bytes = handoff_to_bytes(
    coupled_transport_handoff_from_fusion_bytes(fusion_bytes)
)

The root package exports only the five stable contracts. Registry, evidence, serialization, relation-building, enums, and portfolio helpers live under scpn_phase_orchestrator.reactor_semantics so their use remains explicit.

reactor_semantics

Reactor-family-neutral phase semantics and regime evidence.

This facade is non-actuating. It describes reactor context, observations, semantic carriers, compatible relations, and review-only regime estimates.

Classes

ObservableDescriptor dataclass

ObservableDescriptor(
    observable_id: str,
    reactor_context: ReactorContext,
    physical_quantity: str,
    units: str,
    coordinate_frame: str,
    spatial_support: str,
    diagnostic: str,
    channel: str,
    value: JsonValue,
    clock: ClockReference,
    calibration: CalibrationReference,
    uncertainty: Uncertainty,
    quality: QualityAssessment,
    validity: ValidityWindow,
    provenance: ProvenanceRecord,
    schema_version: str = U0_SCHEMA_VERSION,
)

Calibrated, timestamped, provenance-bearing reactor observable.

Methods:

to_record

to_record() -> dict[str, object]

Return a deterministic JSON-compatible observable record.

Returns

dict[str, object] Complete observable fields for serialization.

from_record classmethod

from_record(
    payload: object,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> ObservableDescriptor

Construct an observable from strict serialized input.

Parameters

payload : object Candidate observable mapping. registry : ReactorConfigurationRegistry Registry used to validate the embedded reactor context.

Returns

ObservableDescriptor Validated observable descriptor.

PhaseRelation dataclass

PhaseRelation(
    relation_id: str,
    source_phase_id: str,
    target_phase_id: str,
    relation_type: PhaseRelationType,
    interpretation: RelationInterpretation,
    reference_transform: str | None,
    clock_transform_id: str | None,
    harmonic_ratio: tuple[int, int],
    lag_s: float,
    causal_direction: str | None,
    identification_method: str,
    evidence_class: EvidenceClass,
    schema_version: str = U0_SCHEMA_VERSION,
)

Validated relationship between two compatible phase records.

Methods:

to_record

to_record() -> dict[str, object]

Return a deterministic JSON-compatible relation record.

Returns

dict[str, object] Complete phase-relation fields for serialization.

from_record classmethod

from_record(payload: object) -> PhaseRelation

Construct a relation from strict serialized input.

Parameters

payload : object Candidate phase-relation mapping.

Returns

PhaseRelation Validated phase relation.

PhaseSemanticRecord dataclass

PhaseSemanticRecord(
    phase_id: str,
    reactor_context_id: str,
    observable_ids: tuple[str, ...],
    carrier_type: SemanticCarrier,
    phenomenon: str,
    phase_rad: float | None,
    amplitude: float | None,
    frequency_hz: float | None,
    bandwidth_hz: float | None,
    mode_identity: str | None,
    mode_harmonic: tuple[int, int] | None,
    phase_origin: str | None,
    orientation: str | None,
    reference_frame: str,
    clock_domain: str,
    clock_kind: ClockKind,
    clock_epoch: str,
    wrap_convention: str | None,
    reference_signal: str | None,
    extractor: str,
    extractor_version: str,
    observation_operator: str | None,
    uncertainty: Uncertainty,
    confidence: float,
    observability: float,
    observability_threshold: float,
    validity: ValidityWindow,
    quality: QualityAssessment,
    evidence_class: EvidenceClass,
    schema_version: str = U0_SCHEMA_VERSION,
)

Typed phase meaning derived from one or more observables.

Attributes

is_usable property

is_usable: bool

Return whether phase comparison is permitted.

Methods:

to_record

to_record() -> dict[str, object]

Return a deterministic JSON-compatible phase record.

Returns

dict[str, object] Complete phase-semantic fields for serialization.

from_record classmethod

from_record(payload: object) -> PhaseSemanticRecord

Construct a phase semantic record from strict serialized input.

Parameters

payload : object Candidate phase-semantic mapping.

Returns

PhaseSemanticRecord Validated phase-semantic record.

Raises

ValueError If the observable identifier collection is not a list.

ReactorContext dataclass

ReactorContext(
    context_id: str,
    configuration: str,
    confinement_family: ConfinementFamily,
    topology: str,
    coordinate_frame: str,
    drivers: tuple[DriverKind, ...],
    cadence: OperatingCadence,
    reaction: ReactionKind,
    conversion: ConversionKind,
    facility: str,
    event_id: str | None,
    configuration_version: str,
    operating_point: Mapping[str, JsonValue],
    evidence_class: EvidenceClass,
    registry_version: str,
    registry_digest: str,
    schema_version: str = U0_SCHEMA_VERSION,
)

Faceted reactor identity with no privileged configuration family.

Methods:

validate_registry

validate_registry(
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> ReactorContext

Validate configuration identity and family against a registry.

Parameters

registry : ReactorConfigurationRegistry Registry that owns the expected configuration identity.

Returns

ReactorContext This context after successful validation.

Raises

ValueError If registry identity, family, or topology differs.

to_record

to_record() -> dict[str, object]

Return a deterministic JSON-compatible context record.

Returns

dict[str, object] Complete reactor-context fields for serialization.

from_record classmethod

from_record(
    payload: object,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> ReactorContext

Construct and registry-validate a context from serialized input.

Parameters

payload : object Candidate reactor-context mapping. registry : ReactorConfigurationRegistry Registry used to validate the decoded configuration.

Returns

ReactorContext Validated reactor context.

Raises

ValueError If list, operating-point, or registry fields are invalid.

RegimeAxis dataclass

RegimeAxis(name: str, label: str, confidence: float)

One independently estimated physical or operational regime axis.

Methods:

to_record

to_record() -> dict[str, object]

Return a JSON-compatible regime-axis record.

Returns

dict[str, object] Complete regime-axis fields for serialization.

from_record classmethod

from_record(payload: object) -> RegimeAxis

Construct a regime axis from strict serialized input.

Parameters

payload : object Candidate regime-axis mapping.

Returns

RegimeAxis Validated regime axis.

RegimeEstimate dataclass

RegimeEstimate(
    regime_id: str,
    reactor_context_id: str,
    axes: tuple[RegimeAxis, ...],
    state: RegimeState,
    evidence_ids: tuple[str, ...],
    classifier: str,
    classifier_version: str,
    threshold_provenance: tuple[str, ...],
    confidence: float,
    hysteresis: float,
    dwell_time_s: float,
    transition_reason: str,
    safety_effect: str,
    validity: ValidityWindow,
    semantic_owner: str = SEMANTIC_OWNER,
    action_owner: str = ACTION_OWNER,
    authority: str = REVIEW_ONLY_AUTHORITY,
    schema_version: str = U0_SCHEMA_VERSION,
)

Compositional non-actuating reactor regime estimate.

Methods:

to_record

to_record() -> dict[str, object]

Return a deterministic JSON-compatible regime record.

Returns

dict[str, object] Complete regime-estimate fields for serialization.

from_record classmethod

from_record(payload: object) -> RegimeEstimate

Construct a compositional regime estimate from strict input.

Parameters

payload : object Candidate regime-estimate mapping.

Returns

RegimeEstimate Validated compositional regime estimate.

Raises

ValueError If axes, evidence identifiers, or threshold provenance are not lists.

ControlVariableDirection

Bases: StrEnum

Direction of a bounded candidate relative to the reviewed baseline.

ControlVariableEnvelope dataclass

ControlVariableEnvelope(
    variable_id: str,
    units: str,
    lower_bound: float,
    upper_bound: float,
    max_abs_delta: float,
    max_abs_rate_per_s: float,
    baseline_value: float,
    proposed_value: float,
    proposed_delta: float,
    proposed_rate_per_s: float,
    rate_horizon_s: float,
    baseline_evidence_id: str,
    baseline_timestamp_ns: int,
    direction: ControlVariableDirection,
)

Device-contract-bound candidate value that cannot execute itself.

Methods:

__post_init__

__post_init__() -> None

Validate and normalise the bounded variable proposal.

to_record

to_record() -> dict[str, object]

Return a complete JSON-compatible variable envelope.

Returns

dict[str, object] Deterministic control-variable fields suitable for serialization.

from_record classmethod

from_record(raw: object) -> ControlVariableEnvelope

Decode one strict variable envelope.

Parameters

raw : object Candidate serialized control-variable mapping.

Returns

ControlVariableEnvelope Validated immutable control-variable envelope.

Raises

ValueError If fields, direction, bounds, rates, or baseline evidence are invalid.

ReactorControlObjective

Bases: StrEnum

Ontology axis that a research hypothesis proposes to influence.

ReactorResearchControlIntent dataclass

ReactorResearchControlIntent(
    intent_id: str,
    reactor_context_id: str,
    configuration: str,
    event_id: str,
    producer_project: str,
    producer_revision: str,
    producer_artifact_sha256: str,
    source_handoff_schema: str,
    source_handoff_sha256: str,
    source_revision: str,
    source_admission_schema: str,
    source_admission_sha256: str,
    source_admission_decision_digest: str,
    source_regime_id: str,
    source_regime_assignment_sha256: str,
    source_regime_label: str,
    source_semantic_ids: tuple[str, ...],
    evidence_ids: tuple[str, ...],
    evidence_class: EvidenceClass,
    source_validity: ValidityState,
    source_quality: QualityState,
    objective: ReactorControlObjective,
    hypothesized_target_regime_label: str,
    effect_hypothesis: str,
    device_control_contract_id: str,
    device_control_contract_schema: str,
    device_control_contract_sha256: str,
    variable: ControlVariableEnvelope,
    clock_domain: str,
    clock_kind: ClockKind,
    clock_epoch: str,
    evidence_timestamp_ns: int,
    sample_rate_hz: float,
    latency_s: float,
    timestamp_offset_ps: int,
    issued_at_ns: int,
    valid_until_ns: int,
    confidence_subject_id: str,
    confidence: float,
    observability: float,
    uncertainty_abs: float,
    uncertainty_units: str,
    uncertainty_basis: str,
    reactor_registry_version: str,
    reactor_registry_digest: str,
    observability_registry_version: str,
    observability_registry_digest: str,
    ontology_version: str,
    ontology_digest: str,
    downstream_control_review_required: bool = True,
    device_adapter_required: bool = True,
    operator_approval_required: bool = True,
    machine_protection_veto_required: bool = True,
    execution_permitted: bool = False,
    authority: str = REVIEW_ONLY_AUTHORITY,
    actionable: bool = False,
    schema: str = REACTOR_CONTROL_INTENT_SCHEMA,
    schema_version: str = REACTOR_CONTROL_INTENT_VERSION,
)

One non-executable reactor control hypothesis for CONTROL review.

Methods:

__post_init__

__post_init__() -> None

Validate and normalise the review-only intent contract.

to_record

to_record() -> dict[str, object]

Return the complete deterministic ControlIntent payload.

Returns

dict[str, object] JSON-compatible review-only intent payload.

ConventionalTokamakAdapterBinding dataclass

ConventionalTokamakAdapterBinding(
    ingress_state: str,
    producer_project: str,
    source_schema: str,
    adapter_api: str,
    handoff_schema: str,
    semantic_profile: str,
    semantic_profile_version: str,
    evidence_state: str = _CURRENT_EVIDENCE_STATE,
    source_kind: str = "simulation",
    physical_source_present: bool = False,
    reusable_as_physical_evidence: bool = False,
)

Exact identity of the exercised adapter that this L1 request extends.

ConventionalTokamakPhysicalCandidateRequirement dataclass

ConventionalTokamakPhysicalCandidateRequirement(
    candidate_id: str,
    phenomenon: str,
    observability_class: str,
    admissible_carriers: tuple[str, ...],
    required_evidence: tuple[str, ...],
    unmet_evidence: str,
    reference_required: bool,
    observation_operator_required: bool,
    repeated_cycle_required: bool,
    evidence_claimed: bool = False,
)

One applicable observability candidate, recorded without selection.

ConventionalTokamakPhysicalPayloadRequest dataclass

ConventionalTokamakPhysicalPayloadRequest()

Digest-bound L1 request that carries no physical evidence itself.

ConventionalTokamakPhysicalPayloadRequestRefusalCode

Bases: StrEnum

Stable refusal categories for request-envelope intake.

ConventionalTokamakPhysicalPayloadRequestRefusalError

ConventionalTokamakPhysicalPayloadRequestRefusalError(
    code: ConventionalTokamakPhysicalPayloadRequestRefusalCode,
    detail: str,
)

Bases: ValueError

Raised when bytes cannot reconstruct the exact producer request.

ConventionalTokamakPhysicalPayloadRequirement dataclass

ConventionalTokamakPhysicalPayloadRequirement(
    requirement_id: ConventionalTokamakPhysicalPayloadRequirementId,
    evidence_subject: str,
    acceptance_condition: str,
    immutable_artifact_binding_required: bool = True,
    missing: bool = True,
)

One missing producer prerequisite and its acceptance condition.

ConventionalTokamakPhysicalPayloadRequirementId

Bases: StrEnum

Stable identifiers for producer-owned physical evidence obligations.

DevicePhysicalCandidateRequirement dataclass

DevicePhysicalCandidateRequirement(
    candidate_id: str,
    phenomenon: str,
    observability_class: str,
    plan_disposition: str,
    channel_identifiers: tuple[str, ...],
    declared_carriers: tuple[str, ...],
    clock_identifiers: tuple[str, ...],
    evidence_slots: tuple[str, ...],
    required_physical_evidence: tuple[str, ...],
    unmet_evidence: str,
    reference_required: bool,
    observation_operator_required: bool,
    repeated_cycle_required: bool,
    physical_selection_eligible: bool,
    plan_revision_required: bool,
    synthetic_declaration_only: bool = True,
    physical_sample_present: bool = False,
    evidence_claimed: bool = False,
    observation_claimed: bool = False,
)

One configuration-specific candidate retained without evidence promotion.

DevicePhysicalClockRequirement dataclass

DevicePhysicalClockRequirement(
    plan_clock_identifier: str,
    plan_clock_kind: str,
    epoch: str,
    resolution_s: float,
    uncertainty_s: float,
    compatibility: str,
    physical_correlation_required: bool,
    eligible_for_physical_reference: bool,
    mapping_evidence_claimed: bool = False,
)

One plan clock and the missing physical-correlation boundary.

DevicePhysicalEvidenceRequest dataclass

DevicePhysicalEvidenceRequest(
    configuration: str, source_review_json: str
)

Configuration-specific request derived from one accepted design review.

DevicePhysicalEvidenceRequestRefusalCode

Bases: StrEnum

Stable reason categories for request-envelope refusal.

DevicePhysicalEvidenceRequestRefusalError

DevicePhysicalEvidenceRequestRefusalError(
    code: DevicePhysicalEvidenceRequestRefusalCode,
    detail: str,
)

Bases: ValueError

Raised when bytes cannot reconstruct an exact physical-evidence request.

DevicePhysicalEvidenceRequirement dataclass

DevicePhysicalEvidenceRequirement(
    requirement_id: DevicePhysicalEvidenceRequirementId,
    evidence_subject: str,
    acceptance_condition: str,
    immutable_artifact_binding_required: bool = True,
    missing: bool = True,
)

One absent producer prerequisite and its acceptance condition.

DevicePhysicalEvidenceRequirementId

Bases: StrEnum

Stable identifiers for producer-owned physical-evidence obligations.

DeviceDiagnosticClockReview dataclass

DeviceDiagnosticClockReview(
    plan_clock_identifier: str,
    plan_clock_kind: str,
    epoch: str,
    resolution_s: float,
    uncertainty_s: float,
    spo_clock_kind_candidate: ClockKind | None,
    compatibility: DiagnosticClockCompatibility,
    mapping_evidence_claimed: bool = False,
)

One reviewed producer clock without a physical mapping claim.

DeviceDiagnosticPlanRefusalCode

Bases: StrEnum

Stable reason categories for fail-closed intake refusal.

DeviceDiagnosticPlanReview dataclass

DeviceDiagnosticPlanReview(
    source_revision: str,
    source_artifact_sha256: str,
    source_manifest_json: str,
    source_envelope_json: str,
    source_plan_json: str,
)

Portable review of one exact producer declaration set.

DeviceDiagnosticSignalReview dataclass

DeviceDiagnosticSignalReview(
    channel_identifier: str,
    candidate_id: str,
    observability_class: ObservabilityClass,
    carrier: SemanticCarrier,
    clock_identifier: str,
    evidence_slots: tuple[str, ...],
    synthetic: bool = True,
    evidence_claimed: bool = False,
    observation_claimed: bool = False,
)

One typed synthetic signal declaration accepted for design review.

DiagnosticClockCompatibility

Bases: StrEnum

Relationship between a producer clock and the SPO clock vocabulary.

CalibrationReference dataclass

CalibrationReference(
    calibration_id: str,
    transfer_function_id: str,
    calibrated_at_ns: int,
)

Calibration and transfer-function provenance.

Methods:

to_record

to_record() -> dict[str, object]

Return a JSON-compatible calibration record.

Returns

dict[str, object] Complete calibration fields for serialization.

from_record classmethod

from_record(payload: object) -> CalibrationReference

Construct a calibration reference from strict serialized input.

Parameters

payload : object Candidate calibration mapping.

Returns

CalibrationReference Validated calibration reference.

ClockReference dataclass

ClockReference(
    domain: str,
    kind: ClockKind,
    epoch: str,
    timestamp_ns: int,
    sample_rate_hz: float,
    latency_s: float,
    picosecond_offset: int = 0,
    synchronized_to: str | None = None,
)

Timestamp and sampling identity for one observation.

Methods:

to_record

to_record() -> dict[str, object]

Return a JSON-compatible clock record.

Returns

dict[str, object] Complete clock fields for serialization.

from_record classmethod

from_record(payload: object) -> ClockReference

Construct a clock record from strict serialized input.

Parameters

payload : object Candidate clock mapping.

Returns

ClockReference Validated clock reference.

Raises

ValueError If the mapping or synchronization identity is invalid.

ProvenanceRecord dataclass

ProvenanceRecord(
    source_project: str,
    component: str,
    symbol: str,
    artifact_uri: str,
    sha256: str,
    attributes: tuple[tuple[str, str], ...] = (),
)

Immutable source identity for a reactor semantic object.

Methods:

to_record

to_record() -> dict[str, object]

Return a JSON-compatible provenance record.

Returns

dict[str, object] Complete provenance fields for serialization.

from_record classmethod

from_record(payload: object) -> ProvenanceRecord

Construct provenance from strict serialized input.

Parameters

payload : object Candidate provenance mapping.

Returns

ProvenanceRecord Validated immutable source identity.

Raises

ValueError If the mapping or provenance attributes are invalid.

QualityAssessment dataclass

QualityAssessment(
    state: QualityState,
    flags: tuple[str, ...] = (),
    signal_to_noise: float | None = None,
)

Signal or estimator quality with explicit flags.

Methods:

to_record

to_record() -> dict[str, object]

Return a JSON-compatible quality record.

Returns

dict[str, object] Complete quality fields for serialization.

from_record classmethod

from_record(payload: object) -> QualityAssessment

Construct a quality assessment from strict serialized input.

Parameters

payload : object Candidate quality mapping.

Returns

QualityAssessment Validated signal-quality assessment.

Raises

ValueError If the mapping or quality flag list is invalid.

Uncertainty dataclass

Uncertainty(
    standard_deviation: float,
    confidence_level: float,
    lower_bound: float | None = None,
    upper_bound: float | None = None,
    circular_std_rad: float | None = None,
)

Uncertainty bounds shared by scalar and circular quantities.

Methods:

to_record

to_record() -> dict[str, object]

Return a JSON-compatible uncertainty record.

Returns

dict[str, object] Complete uncertainty fields for serialization.

from_record classmethod

from_record(payload: object) -> Uncertainty

Construct uncertainty from strict serialized input.

Parameters

payload : object Candidate uncertainty mapping.

Returns

Uncertainty Validated uncertainty bounds.

ValidityWindow dataclass

ValidityWindow(
    state: ValidityState,
    valid_from_ns: int,
    valid_until_ns: int,
    reasons: tuple[str, ...] = (),
)

Validity interval and fail-closed epistemic state.

Methods:

to_record

to_record() -> dict[str, object]

Return a JSON-compatible validity record.

Returns

dict[str, object] Complete validity fields for serialization.

from_record classmethod

from_record(payload: object) -> ValidityWindow

Construct validity from strict serialized input.

Parameters

payload : object Candidate validity mapping.

Returns

ValidityWindow Validated validity interval and state.

Raises

ValueError If the mapping or reason list is invalid.

FRCCompressionMIFAdapterBinding dataclass

FRCCompressionMIFAdapterBinding(
    ingress_state: str,
    producer_project: str,
    source_schema: str,
    adapter_api: str,
    handoff_schema: str,
    semantic_profile: str,
    semantic_profile_version: str,
    evidence_state: str = _CURRENT_EVIDENCE_STATE,
    source_kind: str = "simulation",
    physical_source_present: bool = False,
    reusable_as_physical_evidence: bool = False,
)

Exact identity of the exercised adapter that this L1 request extends.

FRCCompressionMIFPhysicalCandidateRequirement dataclass

FRCCompressionMIFPhysicalCandidateRequirement(
    candidate_id: str,
    phenomenon: str,
    observability_class: str,
    admissible_carriers: tuple[str, ...],
    required_evidence: tuple[str, ...],
    unmet_evidence: str,
    reference_required: bool,
    observation_operator_required: bool,
    repeated_cycle_required: bool,
    evidence_claimed: bool = False,
)

One applicable observability candidate, recorded without selection.

FRCCompressionMIFPhysicalPayloadRequest dataclass

FRCCompressionMIFPhysicalPayloadRequest()

Digest-bound L1 request that carries no physical evidence itself.

FRCCompressionMIFPhysicalPayloadRequestRefusalCode

Bases: StrEnum

Stable refusal categories for request-envelope intake.

FRCCompressionMIFPhysicalPayloadRequestRefusalError

FRCCompressionMIFPhysicalPayloadRequestRefusalError(
    code: FRCCompressionMIFPhysicalPayloadRequestRefusalCode,
    detail: str,
)

Bases: ValueError

Raised when bytes cannot reconstruct the exact producer request.

FRCCompressionMIFPhysicalPayloadRequirement dataclass

FRCCompressionMIFPhysicalPayloadRequirement(
    requirement_id: FRCCompressionMIFPhysicalPayloadRequirementId,
    evidence_subject: str,
    acceptance_condition: str,
    immutable_artifact_binding_required: bool = True,
    missing: bool = True,
)

One missing producer prerequisite and its acceptance condition.

FRCCompressionMIFPhysicalPayloadRequirementId

Bases: StrEnum

Stable identifiers for producer-owned physical evidence obligations.

ReactorSemanticHandoff dataclass

ReactorSemanticHandoff(
    source_schema: str,
    source_revision: str,
    source_envelope_json: str,
    event_id: str,
    context: ReactorContext,
    observables: tuple[ObservableDescriptor, ...],
    semantics: tuple[PhaseSemanticRecord, ...],
    phase_relations: tuple[PhaseRelation, ...],
    regime: RegimeEstimate,
    source_project: str = _FUSION_OWNER,
    authority: str = REVIEW_ONLY_AUTHORITY,
    actionable: bool = False,
    schema: str = HANDOFF_SCHEMA,
    schema_version: str = HANDOFF_SCHEMA_VERSION,
)

One immutable review bundle spanning producer and U0 evidence.

Parameters

source_schema : str Exact owner-allocated FUSION producer schema identifier. source_revision : str Exact 40-character FUSION Git revision. source_envelope_json : str Byte-canonical producer envelope. The handoff embeds these bytes so a downstream consumer can independently recompute the provenance digest. event_id : str Opaque identity supplied to the producer for this simulation event. context : ReactorContext Registry-validated U0 context. observables : tuple[ObservableDescriptor, ...] Declared transport profiles and budgets. semantics : tuple[PhaseSemanticRecord, ...] Nonphase bounded-feature interpretations of the observables. phase_relations : tuple[PhaseRelation, ...] Empty for the coupled-transport exchange. regime : RegimeEstimate UNKNOWN, review-only regime result.

Attributes

source_envelope_sha256 property

source_envelope_sha256: str

Return the SHA-256 digest of the embedded producer bytes.

MastMagneticClockReview dataclass

MastMagneticClockReview(
    name: str,
    sample_count: int,
    first_value_s: float,
    last_value_s: float,
    step_s: float,
    spo_clock_kind_candidate: ClockKind = ClockKind.SHOT_RELATIVE,
    archive_grid_reproduced: bool = True,
    instrument_clock_relation_claimed: bool = False,
    mapping_evidence_claimed: bool = False,
)

One derived archive grid, explicitly not an instrument-clock mapping.

MastMagneticMeasurementReview dataclass

MastMagneticMeasurementReview(
    array_name: str,
    clock_name: str,
    units: str,
    channel_count: int,
    source_valid_for_shot: bool,
    applied_transform_recorded: bool = True,
    calibration_lineage_available: bool = False,
    observation_operator_available: bool = False,
    provider_quality_flags_supplied: bool = False,
    uncertainty_supplied: bool = False,
    phase_eligible: bool = False,
)

One producer-qualified measurement family without phase eligibility.

MastMagneticSourceRefusalCode

Bases: StrEnum

Stable categories for fail-closed source-review refusal.

MastMagneticSourceRefusalError

MastMagneticSourceRefusalError(
    code: MastMagneticSourceRefusalCode, detail: str
)

Bases: ValueError

Raised when FAIR-MAST bytes cannot form a safe SPO review.

MastMagneticSourceReview dataclass

MastMagneticSourceReview(
    source_revision: str,
    source_artifact_sha256: str,
    source_archive_json: str,
    source_qualification_json: str,
)

Digest-sealed review of complete magnetic source and qualification bytes.

MastPhaseCandidateRequirement dataclass

MastPhaseCandidateRequirement(
    candidate_id: str,
    phenomenon: str,
    observability_class: str,
    admissible_carriers: tuple[str, ...],
    required_evidence: tuple[str, ...],
    unmet_evidence: str,
    reference_required: bool,
    observation_operator_required: bool,
    repeated_cycle_required: bool,
    evidence_claimed: bool = False,
)

One registered spherical-tokamak phenomenon candidate, not a claim.

MastPhaseQualificationRequest dataclass

MastPhaseQualificationRequest(source_review_json: str)

Digest-bound request for evidence absent from a FAIR-MAST source review.

MastPhaseQualificationRequestRefusalCode

Bases: StrEnum

Stable refusal categories for request-envelope intake.

MastPhaseQualificationRequestRefusalError

MastPhaseQualificationRequestRefusalError(
    code: MastPhaseQualificationRequestRefusalCode,
    detail: str,
)

Bases: ValueError

Raised when bytes cannot reconstruct the exact qualification request.

MastPhaseQualificationRequirement dataclass

MastPhaseQualificationRequirement(
    requirement_id: MastPhaseQualificationRequirementId,
    evidence_subject: str,
    acceptance_condition: str,
    immutable_artifact_binding_required: bool = True,
    missing: bool = True,
)

One producer-owned prerequisite with an explicit acceptance condition.

MastPhaseQualificationRequirementId

Bases: StrEnum

Stable identifiers for missing physical-qualification evidence.

MIFMergeCompressionHandoff dataclass

MIFMergeCompressionHandoff(source_revision: str, source_envelope_json: str, event_id: str, context: ReactorContext, observables: tuple[ObservableDescriptor, ...], semantics: tuple[PhaseSemanticRecord, ...], regime: RegimeEstimate, source_schema: str = MIF_MERGE_COMPRESSION_SOURCE_SCHEMA, source_project: str = _MIF_PROJECT, phase_relations: tuple[] = (), authority: str = REVIEW_ONLY_AUTHORITY, actionable: bool = False, schema: str = MIF_MERGE_COMPRESSION_HANDOFF_SCHEMA, schema_version: str = MIF_MERGE_COMPRESSION_HANDOFF_VERSION)

Immutable, non-actuating MIF merge-compression semantic handoff.

Attributes

source_envelope_sha256 property

source_envelope_sha256: str

Return SHA-256 of the exact embedded MIF bytes.

Methods:

__post_init__

__post_init__() -> None

Validate source custody and the complete U0 contract graph.

ObservabilityClass

Bases: StrEnum

Epistemic route by which a candidate could acquire meaning.

ReactorObservabilityProfileRegistry dataclass

ReactorObservabilityProfileRegistry(
    version: str,
    reactor_registry_version: str,
    reactor_registry_digest: str,
    candidates: Mapping[str, ReactorSignalCandidateProfile],
)

Immutable candidate catalogue covering every built-in configuration.

Attributes

digest property

digest: str

Return the SHA-256 of the canonical registry record.

Methods:

__post_init__

__post_init__() -> None

Validate registry identity, coverage, and reactor-registry binding.

for_configuration

for_configuration(
    configuration: str,
) -> tuple[ReactorSignalCandidateProfile, ...]

Return sorted candidates applicable to a configuration or alias.

Parameters

configuration : str Canonical reactor configuration identifier or registered alias.

Returns

tuple[ReactorSignalCandidateProfile, ...] Applicable candidates ordered by candidate identifier.

resolve

resolve(candidate_id: str) -> ReactorSignalCandidateProfile

Resolve one exact candidate identifier.

Parameters

candidate_id : str Exact observability candidate identifier.

Returns

ReactorSignalCandidateProfile Registered candidate profile.

Raises

ValueError If the identifier is invalid or is not registered.

to_record

to_record() -> dict[str, object]

Return the canonical registry record.

Returns

dict[str, object] JSON-compatible registry identity and candidate records.

ReactorSignalCandidateProfile dataclass

ReactorSignalCandidateProfile(
    candidate_id: str,
    phenomenon: str,
    configurations: tuple[str, ...],
    observability_class: ObservabilityClass,
    admissible_carriers: tuple[SemanticCarrier, ...],
    required_evidence: tuple[str, ...],
    unmet_evidence: UnmetEvidenceDisposition,
    reference_required: bool,
    observation_operator_required: bool,
    repeated_cycle_required: bool,
    authority: str = "review_only",
    actionable: bool = False,
    evidence_claimed: bool = False,
)

Evidence requirements for one candidate phenomenon.

Applicability means only that the phenomenon is meaningful to investigate for those configurations. It does not assert implementation, measurement, observability, experimental validation, or readiness.

Methods:

__post_init__

__post_init__() -> None

Validate applicability, carrier, evidence, and authority invariants.

to_record

to_record() -> dict[str, object]

Return a complete deterministic candidate record.

Returns

dict[str, object] JSON-compatible candidate profile fields.

UnmetEvidenceDisposition

Bases: StrEnum

Fail-closed result when a candidate lacks its required evidence.

ProducerEvidenceDisposition

Bases: StrEnum

Producer-owned reason that current plant truth is not classifiable.

ProducerEvidenceStatePolicy dataclass

ProducerEvidenceStatePolicy(
    disposition: ProducerEvidenceDisposition,
    validity_state: ValidityState,
    meaning: str,
)

One exact disposition-to-U0 validity and abstention policy.

Methods:

to_record

to_record() -> dict[str, object]

Return the deterministic public policy record.

Returns

dict[str, object] Canonical policy fields for portable serialization.

ReactorReferenceSlice dataclass

ReactorReferenceSlice(
    slice_id: str,
    family: str,
    context: ReactorContext,
    observable: ObservableDescriptor,
    semantics: tuple[PhaseSemanticRecord, ...],
    regime: RegimeEstimate,
)

One multi-contract semantic fixture for a reactor family.

ReactorRegimeAssessment dataclass

ReactorRegimeAssessment(
    assessment_id: str,
    reactor_context_id: str,
    configuration: str,
    event_id: str,
    producer_project: str,
    producer_revision: str,
    producer_artifact_sha256: str,
    source_project: str,
    source_revision: str,
    source_handoff_schema: str,
    source_handoff_sha256: str,
    source_semantic_ids: tuple[str, ...],
    clock_domain: str,
    clock_kind: ClockKind,
    clock_epoch: str,
    clock_synchronization_id: str,
    evidence_timestamp_ns: int,
    assessed_at_ns: int,
    valid_from_ns: int,
    valid_until_ns: int,
    sample_rate_hz: float,
    latency_s: float,
    timestamp_offset_ps: int,
    axes: tuple[ReactorRegimeAxisAssessment, ...],
    reactor_registry_version: str,
    reactor_registry_digest: str,
    semantic_profile_registry_version: str,
    semantic_profile_registry_digest: str,
    observability_registry_version: str,
    observability_registry_digest: str,
    ontology_version: str,
    ontology_digest: str,
    classification_performed: bool = False,
    authority: str = REVIEW_ONLY_AUTHORITY,
    actionable: bool = False,
    schema: str = REACTOR_REGIME_ASSESSMENT_SCHEMA,
    schema_version: str = REACTOR_REGIME_ASSESSMENT_VERSION,
)

Portable identity for a full eight-axis reactor regime assessment.

Methods:

__post_init__

__post_init__() -> None

Validate and normalise a complete review-only assessment.

to_record

to_record() -> dict[str, object]

Return the complete deterministic assessment payload.

Returns

dict[str, object] JSON-compatible eight-axis assessment fields.

ReactorRegimeAxisAssessment dataclass

ReactorRegimeAxisAssessment(
    axis_id: str,
    static_applicability: AxisApplicability,
    disposition: ReactorRegimeAxisDisposition,
    label: str | None,
    confidence: float,
    observability: float,
    uncertainty_probability: float,
    uncertainty_basis_id: str | None,
    evidence_ids: tuple[str, ...],
    evidence_bindings: tuple[
        ReactorRegimeEvidenceBinding, ...
    ],
    evidence_class: EvidenceClass,
    validity: ValidityState,
    quality: QualityState,
    validity_id: str,
    quality_id: str,
    provenance_id: str,
    applicability_basis: tuple[str, ...],
    unknown_reason_id: str | None,
    classifier_id: str | None,
    classifier_version: str | None,
    classifier_sha256: str | None,
    threshold_policy_id: str | None,
    threshold_policy_version: str | None,
    threshold_policy_sha256: str | None,
    hysteresis_policy_id: str | None,
    hysteresis_policy_version: str | None,
    hysteresis_policy_sha256: str | None,
    dwell_samples: int | None,
    authority: str = REVIEW_ONLY_AUTHORITY,
    actionable: bool = False,
)

One evidence-bound row of a complete regime assessment.

Methods:

__post_init__

__post_init__() -> None

Validate and normalise one ontology-bound axis assessment.

to_record

to_record() -> dict[str, object]

Return a complete deterministic axis row.

Returns

dict[str, object] JSON-compatible axis disposition and evidence fields.

from_record classmethod

from_record(raw: object) -> ReactorRegimeAxisAssessment

Decode one strict axis row.

Parameters

raw : object Candidate serialized axis-assessment mapping.

Returns

ReactorRegimeAxisAssessment Validated immutable axis assessment.

Raises

ValueError If fields, enums, evidence bindings, or disposition invariants fail.

ReactorRegimeAxisDisposition

Bases: StrEnum

Classification disposition, separate from static applicability.

ReactorRegimeEvidenceBinding dataclass

ReactorRegimeEvidenceBinding(
    role_id: str, reference_id: str
)

Bind one ontology-required evidence role to a referenced artifact.

Methods:

__post_init__

__post_init__() -> None

Validate and normalise the evidence binding identifiers.

to_record

to_record() -> dict[str, str]

Return one deterministic evidence-role binding.

Returns

dict[str, str] JSON-compatible role and reference identifiers.

from_record classmethod

from_record(raw: object) -> ReactorRegimeEvidenceBinding

Decode one strict evidence-role binding.

Parameters

raw : object Candidate serialized evidence binding.

Returns

ReactorRegimeEvidenceBinding Validated immutable role-to-reference binding.

AxisApplicability

Bases: StrEnum

Whether one regime axis has meaning in a particular context.

AxisApplicabilityPolicy

Bases: StrEnum

How static reactor context constrains an axis.

ModeDomain

Bases: StrEnum

Epistemically distinct physical and model-owned mode domains.

ReactorModeBinding dataclass

ReactorModeBinding(
    definition: ReactorModeDefinition,
    configuration: str,
    carrier: SemanticCarrier,
    evidence_class: EvidenceClass,
    mode_identity: str,
    harmonic_coordinates: tuple[int, int] | None,
    observation_operator_id: str | None,
    reference_frame: str | None,
    reference_signal_id: str | None,
    orientation: str | None,
    phase_origin: str | None,
    wrap_convention: str | None,
    observability_threshold: float | None,
    validity_id: str,
    quality_id: str,
    provenance_id: str,
    authority: str = "review_only",
    actionable: bool = False,
)

Evidence-bearing identity for one extracted physical or numerical mode.

Methods:

__post_init__

__post_init__() -> None

Validate binding identity, evidence, and domain-specific fields.

to_record

to_record() -> dict[str, object]

Return the complete deterministic mode binding.

Returns

dict[str, object] JSON-compatible physical or numerical mode binding fields.

ReactorModeDefinition dataclass

ReactorModeDefinition(
    mode_id: str,
    meaning: str,
    domain: ModeDomain,
    candidate_id: str,
    configurations: tuple[str, ...],
    admissible_carriers: tuple[SemanticCarrier, ...],
    admissible_evidence: tuple[EvidenceClass, ...],
    harmonic_basis: str | None,
    required_semantic_fields: tuple[str, ...],
    authority: str = "review_only",
    actionable: bool = False,
)

Namespaced physical or numerical mode-family definition.

Methods:

__post_init__

__post_init__() -> None

Validate mode identity, applicability, evidence, and domain rules.

to_record

to_record() -> dict[str, object]

Return a deterministic mode-family definition.

Returns

dict[str, object] JSON-compatible mode definition fields.

ReactorRegimeAxisAssignment dataclass

ReactorRegimeAxisAssignment(
    definition: ReactorRegimeAxisDefinition,
    applicability: AxisApplicability,
    label: str | None,
    confidence: float,
    evidence_ids: tuple[str, ...],
    applicability_basis: tuple[str, ...],
    authority: str = "review_only",
    actionable: bool = False,
)

Fail-closed runtime assignment against one axis definition.

Methods:

__post_init__

__post_init__() -> None

Validate applicability, label, confidence, evidence, and authority.

to_regime_axis

to_regime_axis() -> RegimeAxis

Project into U0 without collapsing absence into a nominal label.

Returns

RegimeAxis U0 regime axis preserving applicability or classification state.

to_record

to_record() -> dict[str, object]

Return a deterministic assignment record.

Returns

dict[str, object] JSON-compatible axis assignment fields.

ReactorRegimeAxisDefinition dataclass

ReactorRegimeAxisDefinition(
    axis_id: str,
    meaning: str,
    labels: tuple[str, ...],
    candidate_ids: tuple[str, ...],
    applicability_policy: AxisApplicabilityPolicy,
    required_evidence: tuple[str, ...],
    authority: str = "review_only",
    actionable: bool = False,
)

Versioned meaning and closed labels for one compositional regime axis.

Methods:

__post_init__

__post_init__() -> None

Validate axis vocabulary, evidence requirements, and authority.

to_record

to_record() -> dict[str, object]

Return a deterministic definition record.

Returns

dict[str, object] JSON-compatible axis definition fields.

ReactorRegimeModeOntologyRegistry dataclass

ReactorRegimeModeOntologyRegistry(
    version: str,
    reactor_registry_version: str,
    reactor_registry_digest: str,
    observability_registry_version: str,
    observability_registry_digest: str,
    axes: Mapping[str, ReactorRegimeAxisDefinition],
    modes: Mapping[str, ReactorModeDefinition],
)

Immutable ontology bound to exact reactor and observability registries.

Attributes

digest property

digest: str

Return SHA-256 of the canonical ontology record.

Methods:

__post_init__

__post_init__() -> None

Validate exact registry bindings, ontology entries, and coverage.

resolve_axis

resolve_axis(axis_id: str) -> ReactorRegimeAxisDefinition

Resolve one exact cross-family axis identifier.

Parameters

axis_id : str Exact regime-axis identifier.

Returns

ReactorRegimeAxisDefinition Registered cross-family axis definition.

Raises

ValueError If the identifier is invalid or is not registered.

resolve_mode

resolve_mode(mode_id: str) -> ReactorModeDefinition

Resolve one exact namespaced mode-family identifier.

Parameters

mode_id : str Exact namespaced mode-family identifier.

Returns

ReactorModeDefinition Registered mode-family definition.

Raises

ValueError If the identifier is invalid or is not registered.

modes_for_configuration

modes_for_configuration(
    configuration: str,
) -> tuple[ReactorModeDefinition, ...]

Return physical definitions plus the explicit numerical fallback.

Parameters

configuration : str Canonical reactor configuration identifier or registered alias.

Returns

tuple[ReactorModeDefinition, ...] Mode definitions applicable to the resolved configuration.

applicability_for

applicability_for(
    axis_id: str, configuration: str
) -> AxisApplicability

Return static semantic applicability, never a measured regime state.

Parameters

axis_id : str Exact regime-axis identifier. configuration : str Canonical reactor configuration identifier or registered alias.

Returns

AxisApplicability Static applicability derived from ontology and observability scope.

to_record

to_record() -> dict[str, object]

Return the canonical JSON-compatible ontology record.

Returns

dict[str, object] Ontology identity, axis definitions, and mode definitions.

ReactorConfiguration dataclass

ReactorConfiguration(
    identifier: str,
    confinement_family: ConfinementFamily,
    topology: str,
)

One reactor configuration known to a registry.

Parameters

identifier : str Stable configuration identifier. Extensions use a namespaced identifier such as "institution.example:novel_configuration". confinement_family : ConfinementFamily Broad physical family. topology : str Human-readable geometry or topology description.

Methods:

to_record

to_record() -> dict[str, str]

Return a deterministic JSON-compatible record.

Returns

dict[str, str] Configuration identifier, family, and topology fields.

ReactorConfigurationRegistry dataclass

ReactorConfigurationRegistry(
    version: str,
    configurations: Mapping[str, ReactorConfiguration],
    aliases: Mapping[str, str],
)

Immutable registry of reactor configurations and aliases.

Attributes

digest property

digest: str

Return the SHA-256 digest of the canonical registry record.

Methods:

resolve

resolve(identifier: str) -> ReactorConfiguration

Resolve a canonical identifier or alias.

Parameters

identifier : str Canonical reactor configuration identifier or registered alias.

Returns

ReactorConfiguration Registered canonical configuration.

Raises

ValueError If the identifier is not registered.

register

register(
    configuration: ReactorConfiguration,
    *,
    aliases: tuple[str, ...] = (),
) -> ReactorConfigurationRegistry

Return a new registry containing one namespaced extension.

Built-in identifiers cannot be shadowed. Extensions must contain a namespace separator so local names cannot silently acquire new meaning.

Parameters

configuration : ReactorConfiguration Namespaced configuration to add. aliases : tuple[str, ...] Optional namespaced aliases for the new configuration.

Returns

ReactorConfigurationRegistry New immutable registry containing the extension.

Raises

ValueError If identifiers are not namespaced, collide, or are invalid.

to_record

to_record() -> dict[str, object]

Return the sorted deterministic registry record.

Returns

dict[str, object] JSON-compatible registry version, aliases, and configurations.

ReactorSemanticProfile dataclass

ReactorSemanticProfile(
    configuration: str,
    device_project: str,
    ingress_state: SemanticIngressState,
    producer_project: str | None = None,
    source_schema: str | None = None,
    adapter_api: str | None = None,
    handoff_schema: str | None = None,
    semantic_profile: str | None = None,
    semantic_profile_version: str | None = None,
    control_adapter_contract: str | None = None,
    control_intent_profile: str | None = None,
    authority: str = "review_only",
    actionable: bool = False,
    machine_protection_final_veto: bool = True,
)

SPO binding for one reactor configuration.

device_project records scientific ownership. Producer and adapter fields are populated only when an exercised, versioned ingress exists. Absence is explicit and cannot be interpreted as an inherited generic reactor adapter.

Methods:

__post_init__

__post_init__() -> None

Validate ownership, ingress completeness, and review authority.

to_record

to_record() -> dict[str, object]

Return the complete deterministic profile record.

Returns

dict[str, object] JSON-compatible ownership, ingress, and authority fields.

ReactorSemanticProfileRegistry dataclass

ReactorSemanticProfileRegistry(
    version: str,
    reactor_registry_version: str,
    reactor_registry_digest: str,
    assignment_map_sha256: str,
    profiles: Mapping[str, ReactorSemanticProfile],
)

Immutable semantic ownership and verified-ingress registry.

Attributes

digest property

digest: str

Return the SHA-256 of the canonical registry record.

Methods:

__post_init__

__post_init__() -> None

Validate complete coverage and exact reactor-registry binding.

resolve

resolve(configuration: str) -> ReactorSemanticProfile

Resolve a canonical configuration or registry alias.

Parameters

configuration : str Canonical reactor configuration identifier or registered alias.

Returns

ReactorSemanticProfile Semantic ownership and ingress profile for the configuration.

to_record

to_record() -> dict[str, object]

Return a canonical JSON-compatible registry record.

Returns

dict[str, object] Registry identity and all configuration profiles.

SemanticIngressState

Bases: StrEnum

Evidence-backed availability of a producer-to-SPO adapter.

ClockKind

Bases: StrEnum

Declared time basis; domains of different kinds are never implicit peers.

ConfinementFamily

Bases: StrEnum

Broad physical confinement family, independent of reactor geometry.

ConversionKind

Bases: StrEnum

Energy-conversion or experimental boundary.

DriverKind

Bases: StrEnum

Energy, confinement, or compression driver.

EvidenceClass

Bases: StrEnum

Maturity and epistemic source of a claim.

OperatingCadence

Bases: StrEnum

Temporal operating form of a device or experiment.

PhaseRelationType

Bases: StrEnum

Declared relationship between two phase records.

QualityState

Bases: StrEnum

Measurement or estimator quality.

ReactionKind

Bases: StrEnum

Fusion reaction or fuel class, separate from confinement.

RegimeState

Bases: StrEnum

Top-level operational state without erasing regime axes.

RelationInterpretation

Bases: StrEnum

Operational interpretation of a phase relationship.

SemanticCarrier

Bases: StrEnum

Mathematical carrier of a semantic record.

ValidityState

Bases: StrEnum

Fail-closed validity state for a semantic object.

Functions:

build_abstaining_regime_assessment

build_abstaining_regime_assessment(
    handoff: ReactorSemanticHandoff
    | MIFMergeCompressionHandoff,
    *,
    producer_revision: str,
    producer_artifact_sha256: str,
) -> ReactorRegimeAssessment

Project a verified semantic handoff into an unclassified regime vector.

The builder derives static applicability from the installed ontology. It emits only not_applicable or explicit unknown axis dispositions; no handoff value is interpreted as classifier evidence or a physics label. Source bytes retain the handoff's exact allowlisted registry release; the new assessment uses the installed assessment registries and ontology.

Parameters

handoff : ReactorSemanticHandoff | MIFMergeCompressionHandoff Already-validated FUSION or MIF semantic handoff. producer_revision : str Exact 40-character SPO revision producing the assessment. producer_artifact_sha256 : str SHA-256 identity of the SPO producer artifact.

Returns

ReactorRegimeAssessment Complete deterministic eight-axis review-only assessment.

Raises

ValueError If the handoff type, registry release, clocks, common validity, or identities are invalid.

build_phase_relation

build_phase_relation(
    source: PhaseSemanticRecord,
    target: PhaseSemanticRecord,
    *,
    relation_id: str,
    relation_type: PhaseRelationType,
    interpretation: RelationInterpretation,
    identification_method: str,
    evidence_class: EvidenceClass,
    reference_transform: str | None = None,
    clock_transform_id: str | None = None,
    harmonic_ratio: tuple[int, int] = (1, 1),
    lag_s: float = 0.0,
    causal_direction: str | None = None,
) -> PhaseRelation

Build a relation only when phase records are semantically comparable.

Different frames, clock domains, or harmonics require explicit transforms. Non-phase carriers and unusable records are rejected.

Parameters

source : PhaseSemanticRecord Source phase record. target : PhaseSemanticRecord Target phase record. relation_id : str Identifier for the relation. relation_type : PhaseRelationType Declared relationship type. interpretation : RelationInterpretation Operational interpretation of the relation. identification_method : str Method used to identify the relation. evidence_class : EvidenceClass Evidence maturity supporting the relation. reference_transform : str or None Explicit transform between reference frames, when required. clock_transform_id : str or None Explicit transform between clock identities, when required. harmonic_ratio : tuple[int, int] Positive source-to-target harmonic ratio. lag_s : float Signed relation lag in seconds. causal_direction : str or None Optional declared causal direction.

Returns

PhaseRelation Validated relation between the supplied phase records.

Raises

ValueError If records are unusable or their semantic identities are incompatible.

validate_observable_sequence

validate_observable_sequence(
    observables: tuple[ObservableDescriptor, ...],
) -> tuple[ObservableDescriptor, ...]

Return one usable, strictly monotonic observable stream or fail closed.

Parameters

observables : tuple[ObservableDescriptor, ...] Candidate samples from one observable stream.

Returns

tuple[ObservableDescriptor, ...] The unchanged validated sequence.

Raises

ValueError If the sequence is empty, mixed, non-monotonic, or unusable.

control_intent_digest

control_intent_digest(
    intent: ReactorResearchControlIntent,
) -> str

Return SHA-256 of canonical ControlIntent bytes.

Parameters

intent : ReactorResearchControlIntent Validated intent whose canonical bytes are hashed.

Returns

str Lowercase hexadecimal SHA-256 digest.

control_intent_from_bytes

control_intent_from_bytes(
    payload: bytes,
) -> ReactorResearchControlIntent

Decode only the canonical, duplicate-free, size-bounded representation.

Parameters

payload : bytes Candidate canonical ControlIntent bytes.

Returns

ReactorResearchControlIntent Validated intent reconstructed from the bytes.

Raises

ValueError If the bytes are empty, oversized, malformed, duplicated, or noncanonical.

control_intent_from_record

control_intent_from_record(
    raw: object,
) -> ReactorResearchControlIntent

Decode a strict record and verify its complete identity bindings.

Parameters

raw : object Candidate serialized ControlIntent envelope.

Returns

ReactorResearchControlIntent Validated review-only intent.

Raises

ValueError If schema, digest, enum, registry, or intent invariants are invalid.

control_intent_to_bytes

control_intent_to_bytes(
    intent: ReactorResearchControlIntent,
) -> bytes

Serialize an intent to its unique canonical UTF-8 representation.

Parameters

intent : ReactorResearchControlIntent Validated review-only intent to encode.

Returns

bytes Canonical compact JSON bytes.

control_intent_to_record

control_intent_to_record(
    intent: ReactorResearchControlIntent,
) -> dict[str, object]

Return a digest-sealed portable ControlIntent envelope.

Parameters

intent : ReactorResearchControlIntent Validated review-only intent to serialize.

Returns

dict[str, object] Envelope containing the intent payload and its SHA-256 digest.

conventional_tokamak_physical_payload_request_digest

conventional_tokamak_physical_payload_request_digest(
    request: ConventionalTokamakPhysicalPayloadRequest,
) -> str

Return the SHA-256 of the complete canonical request envelope.

Parameters

request : ConventionalTokamakPhysicalPayloadRequest Request to digest.

Returns

str Lowercase SHA-256 digest.

conventional_tokamak_physical_payload_request_from_bytes

conventional_tokamak_physical_payload_request_from_bytes(
    data: bytes, *, expected_sha256: str | None = None
) -> ConventionalTokamakPhysicalPayloadRequest

Decode canonical bytes, verify their digest, and replay all bindings.

Parameters

data : bytes Canonical request envelope. expected_sha256 : str | None, optional Expected digest of the complete envelope.

Returns

ConventionalTokamakPhysicalPayloadRequest Reconstructed request after digest and contract validation.

conventional_tokamak_physical_payload_request_from_record

conventional_tokamak_physical_payload_request_from_record(
    record: object,
) -> ConventionalTokamakPhysicalPayloadRequest

Rebuild the static request and compare every registry-derived field.

Parameters

record : object Decoded request payload to validate.

Returns

ConventionalTokamakPhysicalPayloadRequest Reconstructed request after exact contract replay.

conventional_tokamak_physical_payload_request_to_bytes

conventional_tokamak_physical_payload_request_to_bytes(
    request: ConventionalTokamakPhysicalPayloadRequest,
) -> bytes

Serialize the request as unique canonical digest-sealed JSON.

Parameters

request : ConventionalTokamakPhysicalPayloadRequest Request to encode.

Returns

bytes Canonical digest-sealed request envelope.

conventional_tokamak_physical_payload_request_to_record

conventional_tokamak_physical_payload_request_to_record(
    request: ConventionalTokamakPhysicalPayloadRequest,
) -> dict[str, object]

Return the complete deterministic request payload.

Parameters

request : ConventionalTokamakPhysicalPayloadRequest Request whose governed fields are serialized.

Returns

dict[str, object] Canonically ordered request payload.

coupled_transport_handoff_from_fusion_bytes

coupled_transport_handoff_from_fusion_bytes(
    source_envelope: bytes,
    *,
    expected_sha256: str | None = None,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> ReactorSemanticHandoff

Validate canonical FUSION bytes and map twelve noncyclic quantities.

Parameters

source_envelope : bytes Canonical FUSION TORAX review-envelope bytes. expected_sha256 : str | None Optional expected digest of the exact source bytes. registry : ReactorConfigurationRegistry Reactor registry used to validate the projected context.

Returns

ReactorSemanticHandoff Review-only handoff containing bounded-feature semantics.

Raises

ValueError If source custody, schema, payload, evidence, or context validation fails.

device_physical_evidence_request_digest

device_physical_evidence_request_digest(
    request: DevicePhysicalEvidenceRequest,
) -> str

Return the SHA-256 of the complete canonical request envelope.

Parameters

request : DevicePhysicalEvidenceRequest Request to digest.

Returns

str Lowercase SHA-256 digest.

device_physical_evidence_request_from_bytes

device_physical_evidence_request_from_bytes(
    data: bytes, *, expected_sha256: str | None = None
) -> DevicePhysicalEvidenceRequest

Decode canonical bytes, verify their digest, and replay all bindings.

Parameters

data : bytes Canonical request envelope. expected_sha256 : str | None, optional Expected digest of the complete envelope.

Returns

DevicePhysicalEvidenceRequest Reconstructed request after digest and contract validation.

device_physical_evidence_request_from_plan_review

device_physical_evidence_request_from_plan_review(
    review: DeviceDiagnosticPlanReview,
    *,
    configuration: str,
) -> DevicePhysicalEvidenceRequest

Build one physical-evidence request from an accepted plan review.

Parameters

review : DeviceDiagnosticPlanReview Revalidated synthetic design review. configuration : str Exact configuration owned by the reviewed producer declaration.

Returns

DevicePhysicalEvidenceRequest Self-contained request with no physical or control authority.

device_physical_evidence_request_from_record

device_physical_evidence_request_from_record(
    record: object,
) -> DevicePhysicalEvidenceRequest

Rebuild a request and replay every source and registry-derived field.

Parameters

record : object Decoded request payload to validate.

Returns

DevicePhysicalEvidenceRequest Reconstructed request after exact source and registry replay.

device_physical_evidence_request_to_bytes

device_physical_evidence_request_to_bytes(
    request: DevicePhysicalEvidenceRequest,
) -> bytes

Serialise a request as unique canonical digest-sealed JSON.

Parameters

request : DevicePhysicalEvidenceRequest Request to encode.

Returns

bytes Canonical digest-sealed request envelope.

device_physical_evidence_request_to_record

device_physical_evidence_request_to_record(
    request: DevicePhysicalEvidenceRequest,
) -> dict[str, object]

Return the complete deterministic request payload.

Parameters

request : DevicePhysicalEvidenceRequest Request whose source and registry bindings are serialized.

Returns

dict[str, object] Canonically ordered request payload.

device_diagnostic_plan_review_digest

device_diagnostic_plan_review_digest(
    review: DeviceDiagnosticPlanReview,
) -> str

Return SHA-256 of the complete canonical review envelope.

Parameters

review : DeviceDiagnosticPlanReview Validated design review.

Returns

str Lowercase hexadecimal SHA-256 digest.

device_diagnostic_plan_review_from_bytes

device_diagnostic_plan_review_from_bytes(
    data: bytes,
) -> DeviceDiagnosticPlanReview

Decode a canonical review envelope and verify its custody chain.

Parameters

data : bytes Canonical digest-sealed envelope.

Returns

DeviceDiagnosticPlanReview Reconstructed, revalidated review.

device_diagnostic_plan_review_from_producer_bytes

device_diagnostic_plan_review_from_producer_bytes(
    *,
    source_revision: str,
    source_artifact_sha256: str,
    manifest_bytes: bytes,
    envelope_bytes: bytes,
    plan_bytes: bytes,
) -> DeviceDiagnosticPlanReview

Review exact producer bytes against the installed SPO registries.

Parameters

source_revision, source_artifact_sha256 : str Exact producer Git revision and installed artefact SHA-256. manifest_bytes, envelope_bytes, plan_bytes : bytes Exact canonical producer documents.

Returns

DeviceDiagnosticPlanReview A design-only, non-evidence, non-actuating portable review.

Raises

DeviceDiagnosticPlanRefusal If identity, bytes, registry bindings, or semantics do not match.

device_diagnostic_plan_review_from_record

device_diagnostic_plan_review_from_record(
    record: object,
) -> DeviceDiagnosticPlanReview

Rebuild a review record and revalidate all embedded source bytes.

Parameters

record : object Candidate payload record.

Returns

DeviceDiagnosticPlanReview Reconstructed, revalidated review.

device_diagnostic_plan_review_to_bytes

device_diagnostic_plan_review_to_bytes(
    review: DeviceDiagnosticPlanReview,
) -> bytes

Serialize a review in a digest-sealed canonical envelope.

Parameters

review : DeviceDiagnosticPlanReview Validated design review.

Returns

bytes Canonical digest-sealed envelope.

device_diagnostic_plan_review_to_record

device_diagnostic_plan_review_to_record(
    review: DeviceDiagnosticPlanReview,
) -> dict[str, object]

Return the complete deterministic review payload record.

Parameters

review : DeviceDiagnosticPlanReview Validated design review.

Returns

dict[str, object] Complete deterministic payload.

frc_compression_mif_physical_payload_request_digest

frc_compression_mif_physical_payload_request_digest(
    request: FRCCompressionMIFPhysicalPayloadRequest,
) -> str

Return the SHA-256 of the complete canonical request envelope.

Parameters

request : FRCCompressionMIFPhysicalPayloadRequest Request to digest.

Returns

str Lowercase SHA-256 digest.

frc_compression_mif_physical_payload_request_from_bytes

frc_compression_mif_physical_payload_request_from_bytes(
    data: bytes, *, expected_sha256: str | None = None
) -> FRCCompressionMIFPhysicalPayloadRequest

Decode canonical bytes, verify their digest, and replay all bindings.

Parameters

data : bytes Canonical request envelope. expected_sha256 : str | None, optional Expected digest of the complete envelope.

Returns

FRCCompressionMIFPhysicalPayloadRequest Reconstructed request after digest and contract validation.

frc_compression_mif_physical_payload_request_from_record

frc_compression_mif_physical_payload_request_from_record(
    record: object,
) -> FRCCompressionMIFPhysicalPayloadRequest

Rebuild the static request and compare every registry-derived field.

Parameters

record : object Decoded request payload to validate.

Returns

FRCCompressionMIFPhysicalPayloadRequest Reconstructed request after exact contract replay.

frc_compression_mif_physical_payload_request_to_bytes

frc_compression_mif_physical_payload_request_to_bytes(
    request: FRCCompressionMIFPhysicalPayloadRequest,
) -> bytes

Serialize the request as unique canonical digest-sealed JSON.

Parameters

request : FRCCompressionMIFPhysicalPayloadRequest Request to encode.

Returns

bytes Canonical digest-sealed request envelope.

frc_compression_mif_physical_payload_request_to_record

frc_compression_mif_physical_payload_request_to_record(
    request: FRCCompressionMIFPhysicalPayloadRequest,
) -> dict[str, object]

Return the complete deterministic request payload.

Parameters

request : FRCCompressionMIFPhysicalPayloadRequest Request whose governed fields are serialized.

Returns

dict[str, object] Canonically ordered request payload.

canonicalize_source_envelope

canonicalize_source_envelope(payload: str) -> str

Canonicalize strict producer JSON for embedding in a handoff.

Parameters

payload : str Candidate producer-envelope JSON text.

Returns

str Canonical compact JSON object text.

Raises

ValueError If the input is empty, oversized, malformed, duplicated, or not an object.

handoff_digest

handoff_digest(
    handoff: ReactorSemanticHandoff,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> str

Return the SHA-256 digest of canonical handoff JSON.

Parameters

handoff : ReactorSemanticHandoff Validated handoff whose canonical bytes are hashed. registry : ReactorConfigurationRegistry Reactor registry used to validate embedded contracts.

Returns

str Lowercase hexadecimal SHA-256 digest.

handoff_from_bytes

handoff_from_bytes(
    payload: bytes,
    *,
    registry: ReactorConfigurationRegistry | None = None,
) -> ReactorSemanticHandoff

Decode the unique canonical UTF-8 handoff representation.

This is the cross-project admission surface. Unlike handoff_from_json, it rejects alternate whitespace, key ordering, a trailing newline, and any other byte representation of the same JSON value.

Parameters

payload : bytes Candidate canonical handoff bytes. registry : ReactorConfigurationRegistry or None Explicit reactor registry required by embedded U0 contracts. When omitted, resolve only the exact allowlisted release declared by the digest-sealed payload.

Returns

ReactorSemanticHandoff Validated handoff reconstructed from the canonical bytes.

Raises

ValueError If the input is empty, oversized, malformed, or not canonical JSON.

handoff_from_json

handoff_from_json(
    payload: str,
    *,
    registry: ReactorConfigurationRegistry | None = None,
) -> ReactorSemanticHandoff

Deserialize handoff JSON while refusing duplicate object keys.

Parameters

payload : str Candidate JSON handoff text. registry : ReactorConfigurationRegistry or None Explicit reactor registry required by embedded U0 contracts. When omitted, resolve only the exact allowlisted release declared by the digest-sealed payload.

Returns

ReactorSemanticHandoff Validated review-only semantic handoff.

Raises

ValueError If JSON is empty, oversized, malformed, duplicated, or semantically invalid.

handoff_from_record

handoff_from_record(
    raw: object,
    *,
    registry: ReactorConfigurationRegistry | None = None,
) -> ReactorSemanticHandoff

Decode a strict handoff record and verify its complete digest chain.

Parameters

raw : object Candidate serialized handoff envelope. registry : ReactorConfigurationRegistry or None Explicit reactor registry required by embedded U0 contracts. When omitted, resolve only the exact allowlisted release declared by the digest-sealed payload.

Returns

ReactorSemanticHandoff Validated review-only semantic handoff.

Raises

ValueError If schema, digest, registry, source, or contract-graph checks fail.

handoff_to_bytes

handoff_to_bytes(
    handoff: ReactorSemanticHandoff,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> bytes

Serialize a handoff to its unique canonical UTF-8 bytes.

Parameters

handoff : ReactorSemanticHandoff Validated semantic handoff to encode. registry : ReactorConfigurationRegistry Reactor registry used to validate embedded contracts.

Returns

bytes Canonical compact JSON bytes.

handoff_to_json

handoff_to_json(
    handoff: ReactorSemanticHandoff,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> str

Serialize a handoff to byte-stable canonical JSON.

Parameters

handoff : ReactorSemanticHandoff Validated semantic handoff to serialize. registry : ReactorConfigurationRegistry Reactor registry used to validate embedded contracts.

Returns

str Canonical compact JSON text.

handoff_to_record

handoff_to_record(
    handoff: ReactorSemanticHandoff,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> dict[str, object]

Return the digest-sealed portable handoff record.

Parameters

handoff : ReactorSemanticHandoff Validated semantic handoff to serialize. registry : ReactorConfigurationRegistry Reactor registry used to validate embedded contracts.

Returns

dict[str, object] Envelope containing the handoff payload and payload digest.

mast_magnetic_source_review_digest

mast_magnetic_source_review_digest(
    review: MastMagneticSourceReview,
) -> str

Return SHA-256 of the complete canonical review envelope.

Parameters

review : MastMagneticSourceReview Validated FAIR-MAST source review.

Returns

str Lowercase SHA-256 hexadecimal digest.

mast_magnetic_source_review_from_bytes

mast_magnetic_source_review_from_bytes(
    data: bytes,
) -> MastMagneticSourceReview

Decode canonical review bytes and replay the complete custody chain.

Parameters

data : bytes Candidate canonical review envelope.

Returns

MastMagneticSourceReview Reconstructed review after envelope, digest, and source replay.

mast_magnetic_source_review_from_producer_bytes

mast_magnetic_source_review_from_producer_bytes(
    *,
    source_revision: str,
    source_artifact_sha256: str,
    archive_bytes: bytes,
    qualification_bytes: bytes,
) -> MastMagneticSourceReview

Review exact installed-producer bytes without importing producer code.

Parameters

source_revision : str Full Git SHA of the producer source used to build the installed wheel. source_artifact_sha256 : str SHA-256 of that exact producer wheel. archive_bytes : bytes Canonical complete FAIR-MAST magnetic archive envelope. qualification_bytes : bytes Canonical diagnostic-qualification document bound to the archive.

Returns

MastMagneticSourceReview Revalidated, review-only physical-source custody record.

mast_magnetic_source_review_from_record

mast_magnetic_source_review_from_record(
    record: object,
) -> MastMagneticSourceReview

Rebuild a review and replay every embedded source invariant.

Parameters

record : object Candidate complete review payload.

Returns

MastMagneticSourceReview Reconstructed review after exact source and derived-field replay.

mast_magnetic_source_review_to_bytes

mast_magnetic_source_review_to_bytes(
    review: MastMagneticSourceReview,
) -> bytes

Serialize a review in a canonical digest-sealed envelope.

Parameters

review : MastMagneticSourceReview Validated FAIR-MAST source review.

Returns

bytes Unique canonical UTF-8 review envelope with one trailing newline.

mast_magnetic_source_review_to_record

mast_magnetic_source_review_to_record(
    review: MastMagneticSourceReview,
) -> dict[str, object]

Return the complete deterministic review payload.

Parameters

review : MastMagneticSourceReview Validated FAIR-MAST source review.

Returns

dict[str, object] Complete payload including both exact source documents.

mast_phase_qualification_request_digest

mast_phase_qualification_request_digest(
    request: MastPhaseQualificationRequest,
) -> str

Return the SHA-256 of the complete canonical request envelope.

Parameters

request : MastPhaseQualificationRequest Validated qualification request.

Returns

str Lowercase SHA-256 digest.

mast_phase_qualification_request_from_bytes

mast_phase_qualification_request_from_bytes(
    data: bytes,
) -> MastPhaseQualificationRequest

Decode canonical request bytes and replay every derived field.

Parameters

data : bytes Candidate canonical request envelope.

Returns

MastPhaseQualificationRequest Fully reconstructed request.

mast_phase_qualification_request_from_record

mast_phase_qualification_request_from_record(
    record: object,
) -> MastPhaseQualificationRequest

Rebuild a request and replay its embedded source-review invariants.

Parameters

record : object Candidate request payload.

Returns

MastPhaseQualificationRequest Reconstructed request after exact comparison.

mast_phase_qualification_request_from_source_review

mast_phase_qualification_request_from_source_review(
    review: MastMagneticSourceReview,
) -> MastPhaseQualificationRequest

Build the exact pending-evidence request from a physical-source review.

Parameters

review : MastMagneticSourceReview Revalidated physical-source custody with no phase qualification.

Returns

MastPhaseQualificationRequest Self-contained review-only producer request.

mast_phase_qualification_request_to_bytes

mast_phase_qualification_request_to_bytes(
    request: MastPhaseQualificationRequest,
) -> bytes

Serialize a request as unique canonical digest-sealed JSON bytes.

Parameters

request : MastPhaseQualificationRequest Validated qualification request.

Returns

bytes Canonical UTF-8 envelope with one trailing newline.

mast_phase_qualification_request_to_record

mast_phase_qualification_request_to_record(
    request: MastPhaseQualificationRequest,
) -> dict[str, object]

Return the deterministic request payload.

Parameters

request : MastPhaseQualificationRequest Validated qualification request.

Returns

dict[str, object] Complete JSON-compatible request payload.

mif_merge_compression_handoff_digest

mif_merge_compression_handoff_digest(
    handoff: MIFMergeCompressionHandoff,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> str

Return SHA-256 of the canonical MIF handoff bytes.

Parameters

handoff : MIFMergeCompressionHandoff Validated handoff whose canonical bytes are hashed. registry : ReactorConfigurationRegistry Reactor registry used when producing the canonical bytes.

Returns

str Lowercase hexadecimal SHA-256 digest.

mif_merge_compression_handoff_from_bytes

mif_merge_compression_handoff_from_bytes(
    payload: bytes,
    *,
    registry: ReactorConfigurationRegistry | None = None,
) -> MIFMergeCompressionHandoff

Decode only the unique canonical MIF handoff byte representation.

Parameters

payload : bytes Candidate canonical MIF handoff bytes. registry : ReactorConfigurationRegistry or None Explicit reactor registry required by the encoded identity binding. When omitted, resolve only the exact allowlisted release declared by the digest-sealed payload.

Returns

MIFMergeCompressionHandoff Validated handoff reconstructed from the bytes.

Raises

ValueError If bytes are empty, oversized, malformed, noncanonical, or invalid.

mif_merge_compression_handoff_from_mif_bytes

mif_merge_compression_handoff_from_mif_bytes(
    source_envelope: bytes,
    *,
    expected_sha256: str | None = None,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> MIFMergeCompressionHandoff

Validate canonical MIF bytes and assign strict U0 semantic carriers.

Parameters

source_envelope : bytes Canonical producer envelope to validate and project. expected_sha256 : str | None Optional expected SHA-256 digest of source_envelope. registry : ReactorConfigurationRegistry Reactor registry against which the projected context is validated.

Returns

MIFMergeCompressionHandoff Validated review-only merge-and-compression handoff.

mif_merge_compression_handoff_from_record

mif_merge_compression_handoff_from_record(
    raw: object,
    *,
    registry: ReactorConfigurationRegistry | None = None,
) -> MIFMergeCompressionHandoff

Decode a strict MIF handoff record and verify its digest chain.

Parameters

raw : object Candidate portable MIF handoff record. registry : ReactorConfigurationRegistry or None Explicit reactor registry required by the encoded identity binding. When omitted, resolve only the exact allowlisted release declared by the digest-sealed payload.

Returns

MIFMergeCompressionHandoff Validated handoff reconstructed from the record.

Raises

ValueError If schema, version, digest, registry, U0, or contract invariants fail.

mif_merge_compression_handoff_to_bytes

mif_merge_compression_handoff_to_bytes(
    handoff: MIFMergeCompressionHandoff,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> bytes

Serialize a MIF handoff to unique canonical UTF-8 bytes.

Parameters

handoff : MIFMergeCompressionHandoff Validated handoff to serialize. registry : ReactorConfigurationRegistry Reactor registry used to validate and encode nested contracts.

Returns

bytes Canonical compact JSON representation of the handoff.

mif_merge_compression_handoff_to_record

mif_merge_compression_handoff_to_record(
    handoff: MIFMergeCompressionHandoff,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> dict[str, object]

Return the digest-sealed portable MIF handoff record.

Parameters

handoff : MIFMergeCompressionHandoff Validated handoff to encode as a record. registry : ReactorConfigurationRegistry Reactor registry used to validate and encode nested contracts.

Returns

dict[str, object] Portable envelope containing the payload and its SHA-256 digest.

resolve_reactor_observability_profile_registry_release

resolve_reactor_observability_profile_registry_release(
    version: str, digest: str
) -> ReactorObservabilityProfileRegistry

Resolve one exact immutable observability-catalogue release.

Parameters

version : str Semantic version of the requested registry. digest : str Lowercase SHA-256 digest of the requested registry.

Returns

ReactorObservabilityProfileRegistry Exact immutable registry matching both identifiers.

Raises

ValueError If either identifier is invalid or the release is unknown.

producer_evidence_state_policy

producer_evidence_state_policy(
    disposition: ProducerEvidenceDisposition,
) -> ProducerEvidenceStatePolicy

Resolve one typed producer disposition without string coercion.

Parameters

disposition : ProducerEvidenceDisposition Exact typed producer evidence disposition.

Returns

ProducerEvidenceStatePolicy Immutable policy assigned to the disposition.

Raises

TypeError If disposition is not the declared enum type.

build_reactor_reference_portfolio

build_reactor_reference_portfolio() -> tuple[
    ReactorReferenceSlice, ...
]

Return deterministic non-actuating records for all U0 family slices.

These records verify semantic breadth. They are scaffold evidence and make no experimental-validation or reactor-readiness claim.

Returns

tuple[ReactorReferenceSlice, ...] One deterministic review-only reference record per defined family slice.

regime_assessment_digest

regime_assessment_digest(
    assessment: ReactorRegimeAssessment,
) -> str

Return SHA-256 of the complete canonical envelope bytes.

Parameters

assessment : ReactorRegimeAssessment Validated assessment whose canonical bytes are hashed.

Returns

str Lowercase hexadecimal SHA-256 digest.

regime_assessment_from_bytes

regime_assessment_from_bytes(
    data: bytes,
) -> ReactorRegimeAssessment

Decode bounded canonical bytes with duplicate-key refusal.

Parameters

data : bytes Candidate canonical assessment bytes.

Returns

ReactorRegimeAssessment Validated assessment reconstructed from the bytes.

Raises

ValueError If the input is malformed, duplicated, oversized, or noncanonical.

regime_assessment_from_record

regime_assessment_from_record(
    raw: object,
) -> ReactorRegimeAssessment

Decode and verify one strict assessment record.

Parameters

raw : object Candidate serialized assessment envelope.

Returns

ReactorRegimeAssessment Validated review-only eight-axis assessment.

Raises

ValueError If schema, digest, enum, axis, clock, or registry validation fails.

regime_assessment_to_bytes

regime_assessment_to_bytes(
    assessment: ReactorRegimeAssessment,
) -> bytes

Encode canonical UTF-8 JSON bytes.

Parameters

assessment : ReactorRegimeAssessment Validated assessment to encode.

Returns

bytes Canonical compact JSON bytes.

regime_assessment_to_record

regime_assessment_to_record(
    assessment: ReactorRegimeAssessment,
) -> dict[str, object]

Return a digest-sealed portable assessment envelope.

Parameters

assessment : ReactorRegimeAssessment Validated eight-axis assessment to serialize.

Returns

dict[str, object] Envelope containing the assessment payload and payload digest.

resolve_reactor_registry_release

resolve_reactor_registry_release(
    version: str, digest: str
) -> ReactorConfigurationRegistry

Resolve one exact immutable registry release.

Producer objects remain bound to the release under which their bytes were authored. Recognising that release preserves custody; it does not silently upgrade or reinterpret the producer object against the current registry.

Parameters

version : str Exact semantic version declared by the producer. digest : str Exact SHA-256 digest of the canonical registry record.

Returns

ReactorConfigurationRegistry Recognised immutable release.

Raises

ValueError If the version and digest pair is not a recognised release.

canonical_json

canonical_json(
    contract: ReactorSemanticContract,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> str

Serialize a contract to byte-stable canonical JSON.

Parameters

contract : ReactorSemanticContract Contract to serialize. registry : ReactorConfigurationRegistry Registry used to validate embedded reactor identities.

Returns

str Canonical JSON text with sorted keys and compact separators.

contract_digest

contract_digest(
    contract: ReactorSemanticContract,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> str

Return the SHA-256 digest of canonical contract JSON.

Parameters

contract : ReactorSemanticContract Contract to digest. registry : ReactorConfigurationRegistry Registry used to validate embedded reactor identities.

Returns

str Lowercase hexadecimal SHA-256 digest.

contract_from_json

contract_from_json(
    payload: str,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> ReactorSemanticContract

Deserialize canonical or ordinary JSON with duplicate-key refusal.

Parameters

payload : str JSON contract envelope. registry : ReactorConfigurationRegistry Registry used to validate embedded reactor identities.

Returns

ReactorSemanticContract Validated concrete contract.

Raises

ValueError If the JSON is empty, malformed, duplicated, or contract-invalid.

contract_from_record

contract_from_record(
    raw: object,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> ReactorSemanticContract

Load one contract and refuse unknown fields, kinds, or schema versions.

Parameters

raw : object Candidate contract envelope. registry : ReactorConfigurationRegistry Registry used to validate embedded reactor identities.

Returns

ReactorSemanticContract Validated concrete contract.

Raises

ValueError If the envelope, payload, schema, or contract type is invalid.

contract_to_record

contract_to_record(
    contract: ReactorSemanticContract,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> dict[str, object]

Return a typed envelope for a U0 contract.

Parameters

contract : ReactorSemanticContract Contract to serialize. registry : ReactorConfigurationRegistry Registry used to validate embedded reactor identities.

Returns

dict[str, object] Typed U0 contract envelope.

Raises

TypeError If contract is not a supported concrete contract type.

Module reference

The package facade above is the supported discovery surface. The references below document the modules that define and validate each part of the wire contract, including the producer-specific adapters and the review-only assessment and research-intent envelopes.

abstaining_assessment

Fail-closed handoff projection without reactor-regime classification.

Classes

Functions:

build_abstaining_regime_assessment

build_abstaining_regime_assessment(
    handoff: ReactorSemanticHandoff
    | MIFMergeCompressionHandoff,
    *,
    producer_revision: str,
    producer_artifact_sha256: str,
) -> ReactorRegimeAssessment

Project a verified semantic handoff into an unclassified regime vector.

The builder derives static applicability from the installed ontology. It emits only not_applicable or explicit unknown axis dispositions; no handoff value is interpreted as classifier evidence or a physics label. Source bytes retain the handoff's exact allowlisted registry release; the new assessment uses the installed assessment registries and ontology.

Parameters

handoff : ReactorSemanticHandoff | MIFMergeCompressionHandoff Already-validated FUSION or MIF semantic handoff. producer_revision : str Exact 40-character SPO revision producing the assessment. producer_artifact_sha256 : str SHA-256 identity of the SPO producer artifact.

Returns

ReactorRegimeAssessment Complete deterministic eight-axis review-only assessment.

Raises

ValueError If the handoff type, registry release, clocks, common validity, or identities are invalid.

contracts

U0 reactor context, observation, phase, relationship, and regime contracts.

Classes

ReactorContext dataclass

ReactorContext(
    context_id: str,
    configuration: str,
    confinement_family: ConfinementFamily,
    topology: str,
    coordinate_frame: str,
    drivers: tuple[DriverKind, ...],
    cadence: OperatingCadence,
    reaction: ReactionKind,
    conversion: ConversionKind,
    facility: str,
    event_id: str | None,
    configuration_version: str,
    operating_point: Mapping[str, JsonValue],
    evidence_class: EvidenceClass,
    registry_version: str,
    registry_digest: str,
    schema_version: str = U0_SCHEMA_VERSION,
)

Faceted reactor identity with no privileged configuration family.

Methods:

validate_registry

validate_registry(
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> ReactorContext

Validate configuration identity and family against a registry.

Parameters

registry : ReactorConfigurationRegistry Registry that owns the expected configuration identity.

Returns

ReactorContext This context after successful validation.

Raises

ValueError If registry identity, family, or topology differs.

to_record

to_record() -> dict[str, object]

Return a deterministic JSON-compatible context record.

Returns

dict[str, object] Complete reactor-context fields for serialization.

from_record classmethod

from_record(
    payload: object,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> ReactorContext

Construct and registry-validate a context from serialized input.

Parameters

payload : object Candidate reactor-context mapping. registry : ReactorConfigurationRegistry Registry used to validate the decoded configuration.

Returns

ReactorContext Validated reactor context.

Raises

ValueError If list, operating-point, or registry fields are invalid.

ObservableDescriptor dataclass

ObservableDescriptor(
    observable_id: str,
    reactor_context: ReactorContext,
    physical_quantity: str,
    units: str,
    coordinate_frame: str,
    spatial_support: str,
    diagnostic: str,
    channel: str,
    value: JsonValue,
    clock: ClockReference,
    calibration: CalibrationReference,
    uncertainty: Uncertainty,
    quality: QualityAssessment,
    validity: ValidityWindow,
    provenance: ProvenanceRecord,
    schema_version: str = U0_SCHEMA_VERSION,
)

Calibrated, timestamped, provenance-bearing reactor observable.

Methods:

to_record

to_record() -> dict[str, object]

Return a deterministic JSON-compatible observable record.

Returns

dict[str, object] Complete observable fields for serialization.

from_record classmethod

from_record(
    payload: object,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> ObservableDescriptor

Construct an observable from strict serialized input.

Parameters

payload : object Candidate observable mapping. registry : ReactorConfigurationRegistry Registry used to validate the embedded reactor context.

Returns

ObservableDescriptor Validated observable descriptor.

PhaseSemanticRecord dataclass

PhaseSemanticRecord(
    phase_id: str,
    reactor_context_id: str,
    observable_ids: tuple[str, ...],
    carrier_type: SemanticCarrier,
    phenomenon: str,
    phase_rad: float | None,
    amplitude: float | None,
    frequency_hz: float | None,
    bandwidth_hz: float | None,
    mode_identity: str | None,
    mode_harmonic: tuple[int, int] | None,
    phase_origin: str | None,
    orientation: str | None,
    reference_frame: str,
    clock_domain: str,
    clock_kind: ClockKind,
    clock_epoch: str,
    wrap_convention: str | None,
    reference_signal: str | None,
    extractor: str,
    extractor_version: str,
    observation_operator: str | None,
    uncertainty: Uncertainty,
    confidence: float,
    observability: float,
    observability_threshold: float,
    validity: ValidityWindow,
    quality: QualityAssessment,
    evidence_class: EvidenceClass,
    schema_version: str = U0_SCHEMA_VERSION,
)

Typed phase meaning derived from one or more observables.

Attributes

is_usable property

is_usable: bool

Return whether phase comparison is permitted.

Methods:

to_record

to_record() -> dict[str, object]

Return a deterministic JSON-compatible phase record.

Returns

dict[str, object] Complete phase-semantic fields for serialization.

from_record classmethod

from_record(payload: object) -> PhaseSemanticRecord

Construct a phase semantic record from strict serialized input.

Parameters

payload : object Candidate phase-semantic mapping.

Returns

PhaseSemanticRecord Validated phase-semantic record.

Raises

ValueError If the observable identifier collection is not a list.

PhaseRelation dataclass

PhaseRelation(
    relation_id: str,
    source_phase_id: str,
    target_phase_id: str,
    relation_type: PhaseRelationType,
    interpretation: RelationInterpretation,
    reference_transform: str | None,
    clock_transform_id: str | None,
    harmonic_ratio: tuple[int, int],
    lag_s: float,
    causal_direction: str | None,
    identification_method: str,
    evidence_class: EvidenceClass,
    schema_version: str = U0_SCHEMA_VERSION,
)

Validated relationship between two compatible phase records.

Methods:

to_record

to_record() -> dict[str, object]

Return a deterministic JSON-compatible relation record.

Returns

dict[str, object] Complete phase-relation fields for serialization.

from_record classmethod

from_record(payload: object) -> PhaseRelation

Construct a relation from strict serialized input.

Parameters

payload : object Candidate phase-relation mapping.

Returns

PhaseRelation Validated phase relation.

RegimeAxis dataclass

RegimeAxis(name: str, label: str, confidence: float)

One independently estimated physical or operational regime axis.

Methods:

to_record

to_record() -> dict[str, object]

Return a JSON-compatible regime-axis record.

Returns

dict[str, object] Complete regime-axis fields for serialization.

from_record classmethod

from_record(payload: object) -> RegimeAxis

Construct a regime axis from strict serialized input.

Parameters

payload : object Candidate regime-axis mapping.

Returns

RegimeAxis Validated regime axis.

RegimeEstimate dataclass

RegimeEstimate(
    regime_id: str,
    reactor_context_id: str,
    axes: tuple[RegimeAxis, ...],
    state: RegimeState,
    evidence_ids: tuple[str, ...],
    classifier: str,
    classifier_version: str,
    threshold_provenance: tuple[str, ...],
    confidence: float,
    hysteresis: float,
    dwell_time_s: float,
    transition_reason: str,
    safety_effect: str,
    validity: ValidityWindow,
    semantic_owner: str = SEMANTIC_OWNER,
    action_owner: str = ACTION_OWNER,
    authority: str = REVIEW_ONLY_AUTHORITY,
    schema_version: str = U0_SCHEMA_VERSION,
)

Compositional non-actuating reactor regime estimate.

Methods:

to_record

to_record() -> dict[str, object]

Return a deterministic JSON-compatible regime record.

Returns

dict[str, object] Complete regime-estimate fields for serialization.

from_record classmethod

from_record(payload: object) -> RegimeEstimate

Construct a compositional regime estimate from strict input.

Parameters

payload : object Candidate regime-estimate mapping.

Returns

RegimeEstimate Validated compositional regime estimate.

Raises

ValueError If axes, evidence identifiers, or threshold provenance are not lists.

Functions:

build_phase_relation

build_phase_relation(
    source: PhaseSemanticRecord,
    target: PhaseSemanticRecord,
    *,
    relation_id: str,
    relation_type: PhaseRelationType,
    interpretation: RelationInterpretation,
    identification_method: str,
    evidence_class: EvidenceClass,
    reference_transform: str | None = None,
    clock_transform_id: str | None = None,
    harmonic_ratio: tuple[int, int] = (1, 1),
    lag_s: float = 0.0,
    causal_direction: str | None = None,
) -> PhaseRelation

Build a relation only when phase records are semantically comparable.

Different frames, clock domains, or harmonics require explicit transforms. Non-phase carriers and unusable records are rejected.

Parameters

source : PhaseSemanticRecord Source phase record. target : PhaseSemanticRecord Target phase record. relation_id : str Identifier for the relation. relation_type : PhaseRelationType Declared relationship type. interpretation : RelationInterpretation Operational interpretation of the relation. identification_method : str Method used to identify the relation. evidence_class : EvidenceClass Evidence maturity supporting the relation. reference_transform : str or None Explicit transform between reference frames, when required. clock_transform_id : str or None Explicit transform between clock identities, when required. harmonic_ratio : tuple[int, int] Positive source-to-target harmonic ratio. lag_s : float Signed relation lag in seconds. causal_direction : str or None Optional declared causal direction.

Returns

PhaseRelation Validated relation between the supplied phase records.

Raises

ValueError If records are unusable or their semantic identities are incompatible.

validate_observable_sequence

validate_observable_sequence(
    observables: tuple[ObservableDescriptor, ...],
) -> tuple[ObservableDescriptor, ...]

Return one usable, strictly monotonic observable stream or fail closed.

Parameters

observables : tuple[ObservableDescriptor, ...] Candidate samples from one observable stream.

Returns

tuple[ObservableDescriptor, ...] The unchanged validated sequence.

Raises

ValueError If the sequence is empty, mixed, non-monotonic, or unusable.

conventional_tokamak_physical_payload_request

Define the exact L1 producer request for conventional-tokamak evidence.

The request binds the existing simulation-only FUSION review adapter, but does not reinterpret its TORAX output as a physical sample. It names the evidence a new producer payload must carry before SPO can review a physical observation.

Classes

ConventionalTokamakPhysicalPayloadRequirementId

Bases: StrEnum

Stable identifiers for producer-owned physical evidence obligations.

ConventionalTokamakPhysicalPayloadRequirement dataclass

ConventionalTokamakPhysicalPayloadRequirement(
    requirement_id: ConventionalTokamakPhysicalPayloadRequirementId,
    evidence_subject: str,
    acceptance_condition: str,
    immutable_artifact_binding_required: bool = True,
    missing: bool = True,
)

One missing producer prerequisite and its acceptance condition.

ConventionalTokamakPhysicalCandidateRequirement dataclass

ConventionalTokamakPhysicalCandidateRequirement(
    candidate_id: str,
    phenomenon: str,
    observability_class: str,
    admissible_carriers: tuple[str, ...],
    required_evidence: tuple[str, ...],
    unmet_evidence: str,
    reference_required: bool,
    observation_operator_required: bool,
    repeated_cycle_required: bool,
    evidence_claimed: bool = False,
)

One applicable observability candidate, recorded without selection.

ConventionalTokamakAdapterBinding dataclass

ConventionalTokamakAdapterBinding(
    ingress_state: str,
    producer_project: str,
    source_schema: str,
    adapter_api: str,
    handoff_schema: str,
    semantic_profile: str,
    semantic_profile_version: str,
    evidence_state: str = _CURRENT_EVIDENCE_STATE,
    source_kind: str = "simulation",
    physical_source_present: bool = False,
    reusable_as_physical_evidence: bool = False,
)

Exact identity of the exercised adapter that this L1 request extends.

ConventionalTokamakPhysicalPayloadRequestRefusalCode

Bases: StrEnum

Stable refusal categories for request-envelope intake.

ConventionalTokamakPhysicalPayloadRequestRefusalError

ConventionalTokamakPhysicalPayloadRequestRefusalError(
    code: ConventionalTokamakPhysicalPayloadRequestRefusalCode,
    detail: str,
)

Bases: ValueError

Raised when bytes cannot reconstruct the exact producer request.

ConventionalTokamakPhysicalPayloadRequest dataclass

ConventionalTokamakPhysicalPayloadRequest()

Digest-bound L1 request that carries no physical evidence itself.

Functions:

conventional_tokamak_physical_payload_request

conventional_tokamak_physical_payload_request() -> (
    ConventionalTokamakPhysicalPayloadRequest
)

Build the current exact L1 producer prerequisite request.

Returns

ConventionalTokamakPhysicalPayloadRequest Registry-derived, review-only request for conventional tokamak evidence.

conventional_tokamak_physical_payload_request_to_record

conventional_tokamak_physical_payload_request_to_record(
    request: ConventionalTokamakPhysicalPayloadRequest,
) -> dict[str, object]

Return the complete deterministic request payload.

Parameters

request : ConventionalTokamakPhysicalPayloadRequest Request whose governed fields are serialized.

Returns

dict[str, object] Canonically ordered request payload.

conventional_tokamak_physical_payload_request_from_record

conventional_tokamak_physical_payload_request_from_record(
    record: object,
) -> ConventionalTokamakPhysicalPayloadRequest

Rebuild the static request and compare every registry-derived field.

Parameters

record : object Decoded request payload to validate.

Returns

ConventionalTokamakPhysicalPayloadRequest Reconstructed request after exact contract replay.

conventional_tokamak_physical_payload_request_to_bytes

conventional_tokamak_physical_payload_request_to_bytes(
    request: ConventionalTokamakPhysicalPayloadRequest,
) -> bytes

Serialize the request as unique canonical digest-sealed JSON.

Parameters

request : ConventionalTokamakPhysicalPayloadRequest Request to encode.

Returns

bytes Canonical digest-sealed request envelope.

conventional_tokamak_physical_payload_request_from_bytes

conventional_tokamak_physical_payload_request_from_bytes(
    data: bytes, *, expected_sha256: str | None = None
) -> ConventionalTokamakPhysicalPayloadRequest

Decode canonical bytes, verify their digest, and replay all bindings.

Parameters

data : bytes Canonical request envelope. expected_sha256 : str | None, optional Expected digest of the complete envelope.

Returns

ConventionalTokamakPhysicalPayloadRequest Reconstructed request after digest and contract validation.

conventional_tokamak_physical_payload_request_digest

conventional_tokamak_physical_payload_request_digest(
    request: ConventionalTokamakPhysicalPayloadRequest,
) -> str

Return the SHA-256 of the complete canonical request envelope.

Parameters

request : ConventionalTokamakPhysicalPayloadRequest Request to digest.

Returns

str Lowercase SHA-256 digest.

control_intent

Digest-sealed, review-only reactor control hypotheses.

This module deliberately has no dependency on supervisor, actuation, CONTROL, device adapters, or hardware transports. An intent is evidence for a later admission decision; it is never an executable command.

Classes

ReactorControlObjective

Bases: StrEnum

Ontology axis that a research hypothesis proposes to influence.

ControlVariableDirection

Bases: StrEnum

Direction of a bounded candidate relative to the reviewed baseline.

ControlVariableEnvelope dataclass

ControlVariableEnvelope(
    variable_id: str,
    units: str,
    lower_bound: float,
    upper_bound: float,
    max_abs_delta: float,
    max_abs_rate_per_s: float,
    baseline_value: float,
    proposed_value: float,
    proposed_delta: float,
    proposed_rate_per_s: float,
    rate_horizon_s: float,
    baseline_evidence_id: str,
    baseline_timestamp_ns: int,
    direction: ControlVariableDirection,
)

Device-contract-bound candidate value that cannot execute itself.

Methods:

__post_init__

__post_init__() -> None

Validate and normalise the bounded variable proposal.

to_record

to_record() -> dict[str, object]

Return a complete JSON-compatible variable envelope.

Returns

dict[str, object] Deterministic control-variable fields suitable for serialization.

from_record classmethod

from_record(raw: object) -> ControlVariableEnvelope

Decode one strict variable envelope.

Parameters

raw : object Candidate serialized control-variable mapping.

Returns

ControlVariableEnvelope Validated immutable control-variable envelope.

Raises

ValueError If fields, direction, bounds, rates, or baseline evidence are invalid.

ReactorResearchControlIntent dataclass

ReactorResearchControlIntent(
    intent_id: str,
    reactor_context_id: str,
    configuration: str,
    event_id: str,
    producer_project: str,
    producer_revision: str,
    producer_artifact_sha256: str,
    source_handoff_schema: str,
    source_handoff_sha256: str,
    source_revision: str,
    source_admission_schema: str,
    source_admission_sha256: str,
    source_admission_decision_digest: str,
    source_regime_id: str,
    source_regime_assignment_sha256: str,
    source_regime_label: str,
    source_semantic_ids: tuple[str, ...],
    evidence_ids: tuple[str, ...],
    evidence_class: EvidenceClass,
    source_validity: ValidityState,
    source_quality: QualityState,
    objective: ReactorControlObjective,
    hypothesized_target_regime_label: str,
    effect_hypothesis: str,
    device_control_contract_id: str,
    device_control_contract_schema: str,
    device_control_contract_sha256: str,
    variable: ControlVariableEnvelope,
    clock_domain: str,
    clock_kind: ClockKind,
    clock_epoch: str,
    evidence_timestamp_ns: int,
    sample_rate_hz: float,
    latency_s: float,
    timestamp_offset_ps: int,
    issued_at_ns: int,
    valid_until_ns: int,
    confidence_subject_id: str,
    confidence: float,
    observability: float,
    uncertainty_abs: float,
    uncertainty_units: str,
    uncertainty_basis: str,
    reactor_registry_version: str,
    reactor_registry_digest: str,
    observability_registry_version: str,
    observability_registry_digest: str,
    ontology_version: str,
    ontology_digest: str,
    downstream_control_review_required: bool = True,
    device_adapter_required: bool = True,
    operator_approval_required: bool = True,
    machine_protection_veto_required: bool = True,
    execution_permitted: bool = False,
    authority: str = REVIEW_ONLY_AUTHORITY,
    actionable: bool = False,
    schema: str = REACTOR_CONTROL_INTENT_SCHEMA,
    schema_version: str = REACTOR_CONTROL_INTENT_VERSION,
)

One non-executable reactor control hypothesis for CONTROL review.

Methods:

__post_init__

__post_init__() -> None

Validate and normalise the review-only intent contract.

to_record

to_record() -> dict[str, object]

Return the complete deterministic ControlIntent payload.

Returns

dict[str, object] JSON-compatible review-only intent payload.

Functions:

control_intent_to_record

control_intent_to_record(
    intent: ReactorResearchControlIntent,
) -> dict[str, object]

Return a digest-sealed portable ControlIntent envelope.

Parameters

intent : ReactorResearchControlIntent Validated review-only intent to serialize.

Returns

dict[str, object] Envelope containing the intent payload and its SHA-256 digest.

control_intent_from_record

control_intent_from_record(
    raw: object,
) -> ReactorResearchControlIntent

Decode a strict record and verify its complete identity bindings.

Parameters

raw : object Candidate serialized ControlIntent envelope.

Returns

ReactorResearchControlIntent Validated review-only intent.

Raises

ValueError If schema, digest, enum, registry, or intent invariants are invalid.

control_intent_to_bytes

control_intent_to_bytes(
    intent: ReactorResearchControlIntent,
) -> bytes

Serialize an intent to its unique canonical UTF-8 representation.

Parameters

intent : ReactorResearchControlIntent Validated review-only intent to encode.

Returns

bytes Canonical compact JSON bytes.

control_intent_from_bytes

control_intent_from_bytes(
    payload: bytes,
) -> ReactorResearchControlIntent

Decode only the canonical, duplicate-free, size-bounded representation.

Parameters

payload : bytes Candidate canonical ControlIntent bytes.

Returns

ReactorResearchControlIntent Validated intent reconstructed from the bytes.

Raises

ValueError If the bytes are empty, oversized, malformed, duplicated, or noncanonical.

control_intent_digest

control_intent_digest(
    intent: ReactorResearchControlIntent,
) -> str

Return SHA-256 of canonical ControlIntent bytes.

Parameters

intent : ReactorResearchControlIntent Validated intent whose canonical bytes are hashed.

Returns

str Lowercase hexadecimal SHA-256 digest.

coupled_transport

Strict FUSION coupled-transport evidence to nonphase U0 semantics.

Classes

Functions:

coupled_transport_handoff_from_fusion_bytes

coupled_transport_handoff_from_fusion_bytes(
    source_envelope: bytes,
    *,
    expected_sha256: str | None = None,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> ReactorSemanticHandoff

Validate canonical FUSION bytes and map twelve noncyclic quantities.

Parameters

source_envelope : bytes Canonical FUSION TORAX review-envelope bytes. expected_sha256 : str | None Optional expected digest of the exact source bytes. registry : ReactorConfigurationRegistry Reactor registry used to validate the projected context.

Returns

ReactorSemanticHandoff Review-only handoff containing bounded-feature semantics.

Raises

ValueError If source custody, schema, payload, evidence, or context validation fails.

diagnostic_plan_depth

Validate declaration-only signal, frame, and clock depth for plan 1.2.

Classes

DiagnosticPlanDepthRefusalKind

Bases: StrEnum

Boundary category to preserve the parent intake's refusal vocabulary.

DiagnosticPlanDepthError

DiagnosticPlanDepthError(
    kind: DiagnosticPlanDepthRefusalKind, detail: str
)

Bases: ValueError

Raised when a 1.2 declaration violates its exact depth contract.

Functions:

validate_diagnostic_plan_depth

validate_diagnostic_plan_depth(
    plan: Mapping[str, object],
    *,
    candidate_classes: Mapping[str, str],
    clock_kinds: Mapping[str, str],
    frame_kinds: Mapping[str, str],
) -> None

Validate all members added by producer envelope version 1.2.0.

Parameters

plan : Mapping[str, object] Decoded diagnostic plan. candidate_classes : Mapping[str, str] Governed observability class for each candidate identifier. clock_kinds : Mapping[str, str] Declared clock kind for each clock identifier. frame_kinds : Mapping[str, str] Declared frame kind for each reference-frame identifier.

The declarations remain synthetic design metadata. In particular, signal quantity and unit text never select a candidate, change its registered carrier, create an observation, or establish a physical phase.

diagnostic_plan_physical_evidence_request

Derive a physical-evidence request from an accepted diagnostic-plan review.

The request preserves exact producer-plan custody while keeping every plan channel synthetic. It identifies the physical evidence a producer must supply for one reactor configuration before SPO may admit an observation or consider phase qualification. Numerical-only candidates remain model coordinates and cannot become physical selection targets.

Classes

DevicePhysicalEvidenceRequirementId

Bases: StrEnum

Stable identifiers for producer-owned physical-evidence obligations.

DevicePhysicalEvidenceRequirement dataclass

DevicePhysicalEvidenceRequirement(
    requirement_id: DevicePhysicalEvidenceRequirementId,
    evidence_subject: str,
    acceptance_condition: str,
    immutable_artifact_binding_required: bool = True,
    missing: bool = True,
)

One absent producer prerequisite and its acceptance condition.

DevicePhysicalCandidateRequirement dataclass

DevicePhysicalCandidateRequirement(
    candidate_id: str,
    phenomenon: str,
    observability_class: str,
    plan_disposition: str,
    channel_identifiers: tuple[str, ...],
    declared_carriers: tuple[str, ...],
    clock_identifiers: tuple[str, ...],
    evidence_slots: tuple[str, ...],
    required_physical_evidence: tuple[str, ...],
    unmet_evidence: str,
    reference_required: bool,
    observation_operator_required: bool,
    repeated_cycle_required: bool,
    physical_selection_eligible: bool,
    plan_revision_required: bool,
    synthetic_declaration_only: bool = True,
    physical_sample_present: bool = False,
    evidence_claimed: bool = False,
    observation_claimed: bool = False,
)

One configuration-specific candidate retained without evidence promotion.

DevicePhysicalClockRequirement dataclass

DevicePhysicalClockRequirement(
    plan_clock_identifier: str,
    plan_clock_kind: str,
    epoch: str,
    resolution_s: float,
    uncertainty_s: float,
    compatibility: str,
    physical_correlation_required: bool,
    eligible_for_physical_reference: bool,
    mapping_evidence_claimed: bool = False,
)

One plan clock and the missing physical-correlation boundary.

DevicePhysicalEvidenceRequestRefusalCode

Bases: StrEnum

Stable reason categories for request-envelope refusal.

DevicePhysicalEvidenceRequestRefusalError

DevicePhysicalEvidenceRequestRefusalError(
    code: DevicePhysicalEvidenceRequestRefusalCode,
    detail: str,
)

Bases: ValueError

Raised when bytes cannot reconstruct an exact physical-evidence request.

DevicePhysicalEvidenceRequest dataclass

DevicePhysicalEvidenceRequest(
    configuration: str, source_review_json: str
)

Configuration-specific request derived from one accepted design review.

Functions:

device_physical_evidence_request_from_plan_review

device_physical_evidence_request_from_plan_review(
    review: DeviceDiagnosticPlanReview,
    *,
    configuration: str,
) -> DevicePhysicalEvidenceRequest

Build one physical-evidence request from an accepted plan review.

Parameters

review : DeviceDiagnosticPlanReview Revalidated synthetic design review. configuration : str Exact configuration owned by the reviewed producer declaration.

Returns

DevicePhysicalEvidenceRequest Self-contained request with no physical or control authority.

device_physical_evidence_request_to_record

device_physical_evidence_request_to_record(
    request: DevicePhysicalEvidenceRequest,
) -> dict[str, object]

Return the complete deterministic request payload.

Parameters

request : DevicePhysicalEvidenceRequest Request whose source and registry bindings are serialized.

Returns

dict[str, object] Canonically ordered request payload.

device_physical_evidence_request_from_record

device_physical_evidence_request_from_record(
    record: object,
) -> DevicePhysicalEvidenceRequest

Rebuild a request and replay every source and registry-derived field.

Parameters

record : object Decoded request payload to validate.

Returns

DevicePhysicalEvidenceRequest Reconstructed request after exact source and registry replay.

device_physical_evidence_request_to_bytes

device_physical_evidence_request_to_bytes(
    request: DevicePhysicalEvidenceRequest,
) -> bytes

Serialise a request as unique canonical digest-sealed JSON.

Parameters

request : DevicePhysicalEvidenceRequest Request to encode.

Returns

bytes Canonical digest-sealed request envelope.

device_physical_evidence_request_from_bytes

device_physical_evidence_request_from_bytes(
    data: bytes, *, expected_sha256: str | None = None
) -> DevicePhysicalEvidenceRequest

Decode canonical bytes, verify their digest, and replay all bindings.

Parameters

data : bytes Canonical request envelope. expected_sha256 : str | None, optional Expected digest of the complete envelope.

Returns

DevicePhysicalEvidenceRequest Reconstructed request after digest and contract validation.

device_physical_evidence_request_digest

device_physical_evidence_request_digest(
    request: DevicePhysicalEvidenceRequest,
) -> str

Return the SHA-256 of the complete canonical request envelope.

Parameters

request : DevicePhysicalEvidenceRequest Request to digest.

Returns

str Lowercase SHA-256 digest.

diagnostic_plan_review

Fail-closed review of portable device diagnostic-plan declarations.

The module consumes producer-owned bytes without importing a device package. Acceptance means only that a synthetic design declaration is internally consistent with the installed SPO registries. It creates no observation, semantic ingress, classifier result, control intent, or actuator authority.

Classes

DeviceDiagnosticPlanRefusalCode

Bases: StrEnum

Stable reason categories for fail-closed intake refusal.

DeviceDiagnosticPlanRefusalError

DeviceDiagnosticPlanRefusalError(
    code: DeviceDiagnosticPlanRefusalCode, detail: str
)

Bases: ValueError

Raised when producer bytes cannot form a safe design review.

DiagnosticClockCompatibility

Bases: StrEnum

Relationship between a producer clock and the SPO clock vocabulary.

DeviceDiagnosticClockReview dataclass

DeviceDiagnosticClockReview(
    plan_clock_identifier: str,
    plan_clock_kind: str,
    epoch: str,
    resolution_s: float,
    uncertainty_s: float,
    spo_clock_kind_candidate: ClockKind | None,
    compatibility: DiagnosticClockCompatibility,
    mapping_evidence_claimed: bool = False,
)

One reviewed producer clock without a physical mapping claim.

DeviceDiagnosticSignalReview dataclass

DeviceDiagnosticSignalReview(
    channel_identifier: str,
    candidate_id: str,
    observability_class: ObservabilityClass,
    carrier: SemanticCarrier,
    clock_identifier: str,
    evidence_slots: tuple[str, ...],
    synthetic: bool = True,
    evidence_claimed: bool = False,
    observation_claimed: bool = False,
)

One typed synthetic signal declaration accepted for design review.

DeviceDiagnosticPlanReview dataclass

DeviceDiagnosticPlanReview(
    source_revision: str,
    source_artifact_sha256: str,
    source_manifest_json: str,
    source_envelope_json: str,
    source_plan_json: str,
)

Portable review of one exact producer declaration set.

Functions:

device_diagnostic_plan_review_from_producer_bytes

device_diagnostic_plan_review_from_producer_bytes(
    *,
    source_revision: str,
    source_artifact_sha256: str,
    manifest_bytes: bytes,
    envelope_bytes: bytes,
    plan_bytes: bytes,
) -> DeviceDiagnosticPlanReview

Review exact producer bytes against the installed SPO registries.

Parameters

source_revision, source_artifact_sha256 : str Exact producer Git revision and installed artefact SHA-256. manifest_bytes, envelope_bytes, plan_bytes : bytes Exact canonical producer documents.

Returns

DeviceDiagnosticPlanReview A design-only, non-evidence, non-actuating portable review.

Raises

DeviceDiagnosticPlanRefusal If identity, bytes, registry bindings, or semantics do not match.

device_diagnostic_plan_review_to_record

device_diagnostic_plan_review_to_record(
    review: DeviceDiagnosticPlanReview,
) -> dict[str, object]

Return the complete deterministic review payload record.

Parameters

review : DeviceDiagnosticPlanReview Validated design review.

Returns

dict[str, object] Complete deterministic payload.

device_diagnostic_plan_review_from_record

device_diagnostic_plan_review_from_record(
    record: object,
) -> DeviceDiagnosticPlanReview

Rebuild a review record and revalidate all embedded source bytes.

Parameters

record : object Candidate payload record.

Returns

DeviceDiagnosticPlanReview Reconstructed, revalidated review.

device_diagnostic_plan_review_to_bytes

device_diagnostic_plan_review_to_bytes(
    review: DeviceDiagnosticPlanReview,
) -> bytes

Serialize a review in a digest-sealed canonical envelope.

Parameters

review : DeviceDiagnosticPlanReview Validated design review.

Returns

bytes Canonical digest-sealed envelope.

device_diagnostic_plan_review_from_bytes

device_diagnostic_plan_review_from_bytes(
    data: bytes,
) -> DeviceDiagnosticPlanReview

Decode a canonical review envelope and verify its custody chain.

Parameters

data : bytes Canonical digest-sealed envelope.

Returns

DeviceDiagnosticPlanReview Reconstructed, revalidated review.

device_diagnostic_plan_review_digest

device_diagnostic_plan_review_digest(
    review: DeviceDiagnosticPlanReview,
) -> str

Return SHA-256 of the complete canonical review envelope.

Parameters

review : DeviceDiagnosticPlanReview Validated design review.

Returns

str Lowercase hexadecimal SHA-256 digest.

evidence

Clock, calibration, uncertainty, quality, validity, and provenance records.

Classes

ClockReference dataclass

ClockReference(
    domain: str,
    kind: ClockKind,
    epoch: str,
    timestamp_ns: int,
    sample_rate_hz: float,
    latency_s: float,
    picosecond_offset: int = 0,
    synchronized_to: str | None = None,
)

Timestamp and sampling identity for one observation.

Methods:

to_record

to_record() -> dict[str, object]

Return a JSON-compatible clock record.

Returns

dict[str, object] Complete clock fields for serialization.

from_record classmethod

from_record(payload: object) -> ClockReference

Construct a clock record from strict serialized input.

Parameters

payload : object Candidate clock mapping.

Returns

ClockReference Validated clock reference.

Raises

ValueError If the mapping or synchronization identity is invalid.

CalibrationReference dataclass

CalibrationReference(
    calibration_id: str,
    transfer_function_id: str,
    calibrated_at_ns: int,
)

Calibration and transfer-function provenance.

Methods:

to_record

to_record() -> dict[str, object]

Return a JSON-compatible calibration record.

Returns

dict[str, object] Complete calibration fields for serialization.

from_record classmethod

from_record(payload: object) -> CalibrationReference

Construct a calibration reference from strict serialized input.

Parameters

payload : object Candidate calibration mapping.

Returns

CalibrationReference Validated calibration reference.

Uncertainty dataclass

Uncertainty(
    standard_deviation: float,
    confidence_level: float,
    lower_bound: float | None = None,
    upper_bound: float | None = None,
    circular_std_rad: float | None = None,
)

Uncertainty bounds shared by scalar and circular quantities.

Methods:

to_record

to_record() -> dict[str, object]

Return a JSON-compatible uncertainty record.

Returns

dict[str, object] Complete uncertainty fields for serialization.

from_record classmethod

from_record(payload: object) -> Uncertainty

Construct uncertainty from strict serialized input.

Parameters

payload : object Candidate uncertainty mapping.

Returns

Uncertainty Validated uncertainty bounds.

QualityAssessment dataclass

QualityAssessment(
    state: QualityState,
    flags: tuple[str, ...] = (),
    signal_to_noise: float | None = None,
)

Signal or estimator quality with explicit flags.

Methods:

to_record

to_record() -> dict[str, object]

Return a JSON-compatible quality record.

Returns

dict[str, object] Complete quality fields for serialization.

from_record classmethod

from_record(payload: object) -> QualityAssessment

Construct a quality assessment from strict serialized input.

Parameters

payload : object Candidate quality mapping.

Returns

QualityAssessment Validated signal-quality assessment.

Raises

ValueError If the mapping or quality flag list is invalid.

ValidityWindow dataclass

ValidityWindow(
    state: ValidityState,
    valid_from_ns: int,
    valid_until_ns: int,
    reasons: tuple[str, ...] = (),
)

Validity interval and fail-closed epistemic state.

Methods:

to_record

to_record() -> dict[str, object]

Return a JSON-compatible validity record.

Returns

dict[str, object] Complete validity fields for serialization.

from_record classmethod

from_record(payload: object) -> ValidityWindow

Construct validity from strict serialized input.

Parameters

payload : object Candidate validity mapping.

Returns

ValidityWindow Validated validity interval and state.

Raises

ValueError If the mapping or reason list is invalid.

ProvenanceRecord dataclass

ProvenanceRecord(
    source_project: str,
    component: str,
    symbol: str,
    artifact_uri: str,
    sha256: str,
    attributes: tuple[tuple[str, str], ...] = (),
)

Immutable source identity for a reactor semantic object.

Methods:

to_record

to_record() -> dict[str, object]

Return a JSON-compatible provenance record.

Returns

dict[str, object] Complete provenance fields for serialization.

from_record classmethod

from_record(payload: object) -> ProvenanceRecord

Construct provenance from strict serialized input.

Parameters

payload : object Candidate provenance mapping.

Returns

ProvenanceRecord Validated immutable source identity.

Raises

ValueError If the mapping or provenance attributes are invalid.

Functions:

frc_compression_mif_physical_payload_request

Define the exact L1 producer request for FRC-compression MIF evidence.

The request binds the existing simulation-only SCPN-MIF-CORE review adapter, but does not reinterpret its merge-compression model output as a physical sample. It names the evidence a new producer payload must carry before SPO can review a physical observation.

Classes

FRCCompressionMIFPhysicalPayloadRequirementId

Bases: StrEnum

Stable identifiers for producer-owned physical evidence obligations.

FRCCompressionMIFPhysicalPayloadRequirement dataclass

FRCCompressionMIFPhysicalPayloadRequirement(
    requirement_id: FRCCompressionMIFPhysicalPayloadRequirementId,
    evidence_subject: str,
    acceptance_condition: str,
    immutable_artifact_binding_required: bool = True,
    missing: bool = True,
)

One missing producer prerequisite and its acceptance condition.

FRCCompressionMIFPhysicalCandidateRequirement dataclass

FRCCompressionMIFPhysicalCandidateRequirement(
    candidate_id: str,
    phenomenon: str,
    observability_class: str,
    admissible_carriers: tuple[str, ...],
    required_evidence: tuple[str, ...],
    unmet_evidence: str,
    reference_required: bool,
    observation_operator_required: bool,
    repeated_cycle_required: bool,
    evidence_claimed: bool = False,
)

One applicable observability candidate, recorded without selection.

FRCCompressionMIFAdapterBinding dataclass

FRCCompressionMIFAdapterBinding(
    ingress_state: str,
    producer_project: str,
    source_schema: str,
    adapter_api: str,
    handoff_schema: str,
    semantic_profile: str,
    semantic_profile_version: str,
    evidence_state: str = _CURRENT_EVIDENCE_STATE,
    source_kind: str = "simulation",
    physical_source_present: bool = False,
    reusable_as_physical_evidence: bool = False,
)

Exact identity of the exercised adapter that this L1 request extends.

FRCCompressionMIFPhysicalPayloadRequestRefusalCode

Bases: StrEnum

Stable refusal categories for request-envelope intake.

FRCCompressionMIFPhysicalPayloadRequestRefusalError

FRCCompressionMIFPhysicalPayloadRequestRefusalError(
    code: FRCCompressionMIFPhysicalPayloadRequestRefusalCode,
    detail: str,
)

Bases: ValueError

Raised when bytes cannot reconstruct the exact producer request.

FRCCompressionMIFPhysicalPayloadRequest dataclass

FRCCompressionMIFPhysicalPayloadRequest()

Digest-bound L1 request that carries no physical evidence itself.

Functions:

frc_compression_mif_physical_payload_request

frc_compression_mif_physical_payload_request() -> (
    FRCCompressionMIFPhysicalPayloadRequest
)

Build the current exact L1 producer prerequisite request.

Returns

FRCCompressionMIFPhysicalPayloadRequest Registry-derived, review-only request for FRC-compression MIF evidence.

frc_compression_mif_physical_payload_request_to_record

frc_compression_mif_physical_payload_request_to_record(
    request: FRCCompressionMIFPhysicalPayloadRequest,
) -> dict[str, object]

Return the complete deterministic request payload.

Parameters

request : FRCCompressionMIFPhysicalPayloadRequest Request whose governed fields are serialized.

Returns

dict[str, object] Canonically ordered request payload.

frc_compression_mif_physical_payload_request_from_record

frc_compression_mif_physical_payload_request_from_record(
    record: object,
) -> FRCCompressionMIFPhysicalPayloadRequest

Rebuild the static request and compare every registry-derived field.

Parameters

record : object Decoded request payload to validate.

Returns

FRCCompressionMIFPhysicalPayloadRequest Reconstructed request after exact contract replay.

frc_compression_mif_physical_payload_request_to_bytes

frc_compression_mif_physical_payload_request_to_bytes(
    request: FRCCompressionMIFPhysicalPayloadRequest,
) -> bytes

Serialize the request as unique canonical digest-sealed JSON.

Parameters

request : FRCCompressionMIFPhysicalPayloadRequest Request to encode.

Returns

bytes Canonical digest-sealed request envelope.

frc_compression_mif_physical_payload_request_from_bytes

frc_compression_mif_physical_payload_request_from_bytes(
    data: bytes, *, expected_sha256: str | None = None
) -> FRCCompressionMIFPhysicalPayloadRequest

Decode canonical bytes, verify their digest, and replay all bindings.

Parameters

data : bytes Canonical request envelope. expected_sha256 : str | None, optional Expected digest of the complete envelope.

Returns

FRCCompressionMIFPhysicalPayloadRequest Reconstructed request after digest and contract validation.

frc_compression_mif_physical_payload_request_digest

frc_compression_mif_physical_payload_request_digest(
    request: FRCCompressionMIFPhysicalPayloadRequest,
) -> str

Return the SHA-256 of the complete canonical request envelope.

Parameters

request : FRCCompressionMIFPhysicalPayloadRequest Request to digest.

Returns

str Lowercase SHA-256 digest.

handoff

Digest-sealed, non-actuating handoff of reactor semantic evidence.

Classes

ReactorSemanticHandoff dataclass

ReactorSemanticHandoff(
    source_schema: str,
    source_revision: str,
    source_envelope_json: str,
    event_id: str,
    context: ReactorContext,
    observables: tuple[ObservableDescriptor, ...],
    semantics: tuple[PhaseSemanticRecord, ...],
    phase_relations: tuple[PhaseRelation, ...],
    regime: RegimeEstimate,
    source_project: str = _FUSION_OWNER,
    authority: str = REVIEW_ONLY_AUTHORITY,
    actionable: bool = False,
    schema: str = HANDOFF_SCHEMA,
    schema_version: str = HANDOFF_SCHEMA_VERSION,
)

One immutable review bundle spanning producer and U0 evidence.

Parameters

source_schema : str Exact owner-allocated FUSION producer schema identifier. source_revision : str Exact 40-character FUSION Git revision. source_envelope_json : str Byte-canonical producer envelope. The handoff embeds these bytes so a downstream consumer can independently recompute the provenance digest. event_id : str Opaque identity supplied to the producer for this simulation event. context : ReactorContext Registry-validated U0 context. observables : tuple[ObservableDescriptor, ...] Declared transport profiles and budgets. semantics : tuple[PhaseSemanticRecord, ...] Nonphase bounded-feature interpretations of the observables. phase_relations : tuple[PhaseRelation, ...] Empty for the coupled-transport exchange. regime : RegimeEstimate UNKNOWN, review-only regime result.

Attributes

source_envelope_sha256 property

source_envelope_sha256: str

Return the SHA-256 digest of the embedded producer bytes.

Functions:

handoff_to_record

handoff_to_record(
    handoff: ReactorSemanticHandoff,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> dict[str, object]

Return the digest-sealed portable handoff record.

Parameters

handoff : ReactorSemanticHandoff Validated semantic handoff to serialize. registry : ReactorConfigurationRegistry Reactor registry used to validate embedded contracts.

Returns

dict[str, object] Envelope containing the handoff payload and payload digest.

handoff_from_record

handoff_from_record(
    raw: object,
    *,
    registry: ReactorConfigurationRegistry | None = None,
) -> ReactorSemanticHandoff

Decode a strict handoff record and verify its complete digest chain.

Parameters

raw : object Candidate serialized handoff envelope. registry : ReactorConfigurationRegistry or None Explicit reactor registry required by embedded U0 contracts. When omitted, resolve only the exact allowlisted release declared by the digest-sealed payload.

Returns

ReactorSemanticHandoff Validated review-only semantic handoff.

Raises

ValueError If schema, digest, registry, source, or contract-graph checks fail.

handoff_to_json

handoff_to_json(
    handoff: ReactorSemanticHandoff,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> str

Serialize a handoff to byte-stable canonical JSON.

Parameters

handoff : ReactorSemanticHandoff Validated semantic handoff to serialize. registry : ReactorConfigurationRegistry Reactor registry used to validate embedded contracts.

Returns

str Canonical compact JSON text.

handoff_to_bytes

handoff_to_bytes(
    handoff: ReactorSemanticHandoff,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> bytes

Serialize a handoff to its unique canonical UTF-8 bytes.

Parameters

handoff : ReactorSemanticHandoff Validated semantic handoff to encode. registry : ReactorConfigurationRegistry Reactor registry used to validate embedded contracts.

Returns

bytes Canonical compact JSON bytes.

handoff_from_json

handoff_from_json(
    payload: str,
    *,
    registry: ReactorConfigurationRegistry | None = None,
) -> ReactorSemanticHandoff

Deserialize handoff JSON while refusing duplicate object keys.

Parameters

payload : str Candidate JSON handoff text. registry : ReactorConfigurationRegistry or None Explicit reactor registry required by embedded U0 contracts. When omitted, resolve only the exact allowlisted release declared by the digest-sealed payload.

Returns

ReactorSemanticHandoff Validated review-only semantic handoff.

Raises

ValueError If JSON is empty, oversized, malformed, duplicated, or semantically invalid.

handoff_from_bytes

handoff_from_bytes(
    payload: bytes,
    *,
    registry: ReactorConfigurationRegistry | None = None,
) -> ReactorSemanticHandoff

Decode the unique canonical UTF-8 handoff representation.

This is the cross-project admission surface. Unlike handoff_from_json, it rejects alternate whitespace, key ordering, a trailing newline, and any other byte representation of the same JSON value.

Parameters

payload : bytes Candidate canonical handoff bytes. registry : ReactorConfigurationRegistry or None Explicit reactor registry required by embedded U0 contracts. When omitted, resolve only the exact allowlisted release declared by the digest-sealed payload.

Returns

ReactorSemanticHandoff Validated handoff reconstructed from the canonical bytes.

Raises

ValueError If the input is empty, oversized, malformed, or not canonical JSON.

handoff_digest

handoff_digest(
    handoff: ReactorSemanticHandoff,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> str

Return the SHA-256 digest of canonical handoff JSON.

Parameters

handoff : ReactorSemanticHandoff Validated handoff whose canonical bytes are hashed. registry : ReactorConfigurationRegistry Reactor registry used to validate embedded contracts.

Returns

str Lowercase hexadecimal SHA-256 digest.

canonicalize_source_envelope

canonicalize_source_envelope(payload: str) -> str

Canonicalize strict producer JSON for embedding in a handoff.

Parameters

payload : str Candidate producer-envelope JSON text.

Returns

str Canonical compact JSON object text.

Raises

ValueError If the input is empty, oversized, malformed, duplicated, or not an object.

mast_magnetic_review

Review complete FAIR-MAST magnetic source and qualification bytes.

The adapter preserves a physical-source custody chain without promoting the source to an SPO phase observation. In particular, a complete archive and a producer qualification do not supply calibration lineage, transfer functions, provider quality flags, uncertainty, an instrument-clock relation, or a facility event identity. Consequently this module cannot infer phase, declare semantic ingress, classify a regime, or create a control object.

Classes

MastMagneticSourceRefusalCode

Bases: StrEnum

Stable categories for fail-closed source-review refusal.

MastMagneticSourceRefusalError

MastMagneticSourceRefusalError(
    code: MastMagneticSourceRefusalCode, detail: str
)

Bases: ValueError

Raised when FAIR-MAST bytes cannot form a safe SPO review.

MastMagneticClockReview dataclass

MastMagneticClockReview(
    name: str,
    sample_count: int,
    first_value_s: float,
    last_value_s: float,
    step_s: float,
    spo_clock_kind_candidate: ClockKind = ClockKind.SHOT_RELATIVE,
    archive_grid_reproduced: bool = True,
    instrument_clock_relation_claimed: bool = False,
    mapping_evidence_claimed: bool = False,
)

One derived archive grid, explicitly not an instrument-clock mapping.

MastMagneticMeasurementReview dataclass

MastMagneticMeasurementReview(
    array_name: str,
    clock_name: str,
    units: str,
    channel_count: int,
    source_valid_for_shot: bool,
    applied_transform_recorded: bool = True,
    calibration_lineage_available: bool = False,
    observation_operator_available: bool = False,
    provider_quality_flags_supplied: bool = False,
    uncertainty_supplied: bool = False,
    phase_eligible: bool = False,
)

One producer-qualified measurement family without phase eligibility.

MastMagneticSourceReview dataclass

MastMagneticSourceReview(
    source_revision: str,
    source_artifact_sha256: str,
    source_archive_json: str,
    source_qualification_json: str,
)

Digest-sealed review of complete magnetic source and qualification bytes.

Functions:

mast_magnetic_source_review_from_producer_bytes

mast_magnetic_source_review_from_producer_bytes(
    *,
    source_revision: str,
    source_artifact_sha256: str,
    archive_bytes: bytes,
    qualification_bytes: bytes,
) -> MastMagneticSourceReview

Review exact installed-producer bytes without importing producer code.

Parameters

source_revision : str Full Git SHA of the producer source used to build the installed wheel. source_artifact_sha256 : str SHA-256 of that exact producer wheel. archive_bytes : bytes Canonical complete FAIR-MAST magnetic archive envelope. qualification_bytes : bytes Canonical diagnostic-qualification document bound to the archive.

Returns

MastMagneticSourceReview Revalidated, review-only physical-source custody record.

mast_magnetic_source_review_to_record

mast_magnetic_source_review_to_record(
    review: MastMagneticSourceReview,
) -> dict[str, object]

Return the complete deterministic review payload.

Parameters

review : MastMagneticSourceReview Validated FAIR-MAST source review.

Returns

dict[str, object] Complete payload including both exact source documents.

mast_magnetic_source_review_from_record

mast_magnetic_source_review_from_record(
    record: object,
) -> MastMagneticSourceReview

Rebuild a review and replay every embedded source invariant.

Parameters

record : object Candidate complete review payload.

Returns

MastMagneticSourceReview Reconstructed review after exact source and derived-field replay.

mast_magnetic_source_review_to_bytes

mast_magnetic_source_review_to_bytes(
    review: MastMagneticSourceReview,
) -> bytes

Serialize a review in a canonical digest-sealed envelope.

Parameters

review : MastMagneticSourceReview Validated FAIR-MAST source review.

Returns

bytes Unique canonical UTF-8 review envelope with one trailing newline.

mast_magnetic_source_review_from_bytes

mast_magnetic_source_review_from_bytes(
    data: bytes,
) -> MastMagneticSourceReview

Decode canonical review bytes and replay the complete custody chain.

Parameters

data : bytes Candidate canonical review envelope.

Returns

MastMagneticSourceReview Reconstructed review after envelope, digest, and source replay.

mast_magnetic_source_review_digest

mast_magnetic_source_review_digest(
    review: MastMagneticSourceReview,
) -> str

Return SHA-256 of the complete canonical review envelope.

Parameters

review : MastMagneticSourceReview Validated FAIR-MAST source review.

Returns

str Lowercase SHA-256 hexadecimal digest.

mast_phase_qualification_request

Build an exact producer request from reviewed FAIR-MAST source custody.

The request names what SCPN-FUSION-CORE must supply before SPO may qualify a physical observation or infer phase. It carries no evidence for those missing requirements and cannot grant semantic ingress or CONTROL authority.

Classes

MastPhaseQualificationRequirementId

Bases: StrEnum

Stable identifiers for missing physical-qualification evidence.

MastPhaseQualificationRequirement dataclass

MastPhaseQualificationRequirement(
    requirement_id: MastPhaseQualificationRequirementId,
    evidence_subject: str,
    acceptance_condition: str,
    immutable_artifact_binding_required: bool = True,
    missing: bool = True,
)

One producer-owned prerequisite with an explicit acceptance condition.

MastPhaseCandidateRequirement dataclass

MastPhaseCandidateRequirement(
    candidate_id: str,
    phenomenon: str,
    observability_class: str,
    admissible_carriers: tuple[str, ...],
    required_evidence: tuple[str, ...],
    unmet_evidence: str,
    reference_required: bool,
    observation_operator_required: bool,
    repeated_cycle_required: bool,
    evidence_claimed: bool = False,
)

One registered spherical-tokamak phenomenon candidate, not a claim.

MastPhaseQualificationRequestRefusalCode

Bases: StrEnum

Stable refusal categories for request-envelope intake.

MastPhaseQualificationRequestRefusalError

MastPhaseQualificationRequestRefusalError(
    code: MastPhaseQualificationRequestRefusalCode,
    detail: str,
)

Bases: ValueError

Raised when bytes cannot reconstruct the exact qualification request.

MastPhaseQualificationRequest dataclass

MastPhaseQualificationRequest(source_review_json: str)

Digest-bound request for evidence absent from a FAIR-MAST source review.

Functions:

mast_phase_qualification_request_from_source_review

mast_phase_qualification_request_from_source_review(
    review: MastMagneticSourceReview,
) -> MastPhaseQualificationRequest

Build the exact pending-evidence request from a physical-source review.

Parameters

review : MastMagneticSourceReview Revalidated physical-source custody with no phase qualification.

Returns

MastPhaseQualificationRequest Self-contained review-only producer request.

mast_phase_qualification_request_to_record

mast_phase_qualification_request_to_record(
    request: MastPhaseQualificationRequest,
) -> dict[str, object]

Return the deterministic request payload.

Parameters

request : MastPhaseQualificationRequest Validated qualification request.

Returns

dict[str, object] Complete JSON-compatible request payload.

mast_phase_qualification_request_from_record

mast_phase_qualification_request_from_record(
    record: object,
) -> MastPhaseQualificationRequest

Rebuild a request and replay its embedded source-review invariants.

Parameters

record : object Candidate request payload.

Returns

MastPhaseQualificationRequest Reconstructed request after exact comparison.

mast_phase_qualification_request_to_bytes

mast_phase_qualification_request_to_bytes(
    request: MastPhaseQualificationRequest,
) -> bytes

Serialize a request as unique canonical digest-sealed JSON bytes.

Parameters

request : MastPhaseQualificationRequest Validated qualification request.

Returns

bytes Canonical UTF-8 envelope with one trailing newline.

mast_phase_qualification_request_from_bytes

mast_phase_qualification_request_from_bytes(
    data: bytes,
) -> MastPhaseQualificationRequest

Decode canonical request bytes and replay every derived field.

Parameters

data : bytes Candidate canonical request envelope.

Returns

MastPhaseQualificationRequest Fully reconstructed request.

mast_phase_qualification_request_digest

mast_phase_qualification_request_digest(
    request: MastPhaseQualificationRequest,
) -> str

Return the SHA-256 of the complete canonical request envelope.

Parameters

request : MastPhaseQualificationRequest Validated qualification request.

Returns

str Lowercase SHA-256 digest.

mif_merge_compression

Strict MIF merge-compression evidence to review-only U0 semantics.

Classes

MIFMergeCompressionHandoff dataclass

MIFMergeCompressionHandoff(source_revision: str, source_envelope_json: str, event_id: str, context: ReactorContext, observables: tuple[ObservableDescriptor, ...], semantics: tuple[PhaseSemanticRecord, ...], regime: RegimeEstimate, source_schema: str = MIF_MERGE_COMPRESSION_SOURCE_SCHEMA, source_project: str = _MIF_PROJECT, phase_relations: tuple[] = (), authority: str = REVIEW_ONLY_AUTHORITY, actionable: bool = False, schema: str = MIF_MERGE_COMPRESSION_HANDOFF_SCHEMA, schema_version: str = MIF_MERGE_COMPRESSION_HANDOFF_VERSION)

Immutable, non-actuating MIF merge-compression semantic handoff.

Attributes

source_envelope_sha256 property

source_envelope_sha256: str

Return SHA-256 of the exact embedded MIF bytes.

Methods:

__post_init__

__post_init__() -> None

Validate source custody and the complete U0 contract graph.

Functions:

mif_merge_compression_handoff_from_mif_bytes

mif_merge_compression_handoff_from_mif_bytes(
    source_envelope: bytes,
    *,
    expected_sha256: str | None = None,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> MIFMergeCompressionHandoff

Validate canonical MIF bytes and assign strict U0 semantic carriers.

Parameters

source_envelope : bytes Canonical producer envelope to validate and project. expected_sha256 : str | None Optional expected SHA-256 digest of source_envelope. registry : ReactorConfigurationRegistry Reactor registry against which the projected context is validated.

Returns

MIFMergeCompressionHandoff Validated review-only merge-and-compression handoff.

mif_merge_compression_handoff_to_record

mif_merge_compression_handoff_to_record(
    handoff: MIFMergeCompressionHandoff,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> dict[str, object]

Return the digest-sealed portable MIF handoff record.

Parameters

handoff : MIFMergeCompressionHandoff Validated handoff to encode as a record. registry : ReactorConfigurationRegistry Reactor registry used to validate and encode nested contracts.

Returns

dict[str, object] Portable envelope containing the payload and its SHA-256 digest.

mif_merge_compression_handoff_from_record

mif_merge_compression_handoff_from_record(
    raw: object,
    *,
    registry: ReactorConfigurationRegistry | None = None,
) -> MIFMergeCompressionHandoff

Decode a strict MIF handoff record and verify its digest chain.

Parameters

raw : object Candidate portable MIF handoff record. registry : ReactorConfigurationRegistry or None Explicit reactor registry required by the encoded identity binding. When omitted, resolve only the exact allowlisted release declared by the digest-sealed payload.

Returns

MIFMergeCompressionHandoff Validated handoff reconstructed from the record.

Raises

ValueError If schema, version, digest, registry, U0, or contract invariants fail.

mif_merge_compression_handoff_to_bytes

mif_merge_compression_handoff_to_bytes(
    handoff: MIFMergeCompressionHandoff,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> bytes

Serialize a MIF handoff to unique canonical UTF-8 bytes.

Parameters

handoff : MIFMergeCompressionHandoff Validated handoff to serialize. registry : ReactorConfigurationRegistry Reactor registry used to validate and encode nested contracts.

Returns

bytes Canonical compact JSON representation of the handoff.

mif_merge_compression_handoff_from_bytes

mif_merge_compression_handoff_from_bytes(
    payload: bytes,
    *,
    registry: ReactorConfigurationRegistry | None = None,
) -> MIFMergeCompressionHandoff

Decode only the unique canonical MIF handoff byte representation.

Parameters

payload : bytes Candidate canonical MIF handoff bytes. registry : ReactorConfigurationRegistry or None Explicit reactor registry required by the encoded identity binding. When omitted, resolve only the exact allowlisted release declared by the digest-sealed payload.

Returns

MIFMergeCompressionHandoff Validated handoff reconstructed from the bytes.

Raises

ValueError If bytes are empty, oversized, malformed, noncanonical, or invalid.

mif_merge_compression_handoff_digest

mif_merge_compression_handoff_digest(
    handoff: MIFMergeCompressionHandoff,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> str

Return SHA-256 of the canonical MIF handoff bytes.

Parameters

handoff : MIFMergeCompressionHandoff Validated handoff whose canonical bytes are hashed. registry : ReactorConfigurationRegistry Reactor registry used when producing the canonical bytes.

Returns

str Lowercase hexadecimal SHA-256 digest.

observability_profiles

Machine-readable phase-meaning requirements across reactor concepts.

The catalogue records candidate phenomena and the evidence required to assign semantic carriers. It is a design constraint, not evidence that a diagnostic, producer, phase, or reactor capability exists.

Classes

ObservabilityClass

Bases: StrEnum

Epistemic route by which a candidate could acquire meaning.

UnmetEvidenceDisposition

Bases: StrEnum

Fail-closed result when a candidate lacks its required evidence.

ReactorSignalCandidateProfile dataclass

ReactorSignalCandidateProfile(
    candidate_id: str,
    phenomenon: str,
    configurations: tuple[str, ...],
    observability_class: ObservabilityClass,
    admissible_carriers: tuple[SemanticCarrier, ...],
    required_evidence: tuple[str, ...],
    unmet_evidence: UnmetEvidenceDisposition,
    reference_required: bool,
    observation_operator_required: bool,
    repeated_cycle_required: bool,
    authority: str = "review_only",
    actionable: bool = False,
    evidence_claimed: bool = False,
)

Evidence requirements for one candidate phenomenon.

Applicability means only that the phenomenon is meaningful to investigate for those configurations. It does not assert implementation, measurement, observability, experimental validation, or readiness.

Methods:

__post_init__

__post_init__() -> None

Validate applicability, carrier, evidence, and authority invariants.

to_record

to_record() -> dict[str, object]

Return a complete deterministic candidate record.

Returns

dict[str, object] JSON-compatible candidate profile fields.

ReactorObservabilityProfileRegistry dataclass

ReactorObservabilityProfileRegistry(
    version: str,
    reactor_registry_version: str,
    reactor_registry_digest: str,
    candidates: Mapping[str, ReactorSignalCandidateProfile],
)

Immutable candidate catalogue covering every built-in configuration.

Attributes

digest property

digest: str

Return the SHA-256 of the canonical registry record.

Methods:

__post_init__

__post_init__() -> None

Validate registry identity, coverage, and reactor-registry binding.

for_configuration

for_configuration(
    configuration: str,
) -> tuple[ReactorSignalCandidateProfile, ...]

Return sorted candidates applicable to a configuration or alias.

Parameters

configuration : str Canonical reactor configuration identifier or registered alias.

Returns

tuple[ReactorSignalCandidateProfile, ...] Applicable candidates ordered by candidate identifier.

resolve

resolve(candidate_id: str) -> ReactorSignalCandidateProfile

Resolve one exact candidate identifier.

Parameters

candidate_id : str Exact observability candidate identifier.

Returns

ReactorSignalCandidateProfile Registered candidate profile.

Raises

ValueError If the identifier is invalid or is not registered.

to_record

to_record() -> dict[str, object]

Return the canonical registry record.

Returns

dict[str, object] JSON-compatible registry identity and candidate records.

Functions:

resolve_reactor_observability_profile_registry_release

resolve_reactor_observability_profile_registry_release(
    version: str, digest: str
) -> ReactorObservabilityProfileRegistry

Resolve one exact immutable observability-catalogue release.

Parameters

version : str Semantic version of the requested registry. digest : str Lowercase SHA-256 digest of the requested registry.

Returns

ReactorObservabilityProfileRegistry Exact immutable registry matching both identifiers.

Raises

ValueError If either identifier is invalid or the release is unknown.

producer_evidence_state

Separate producer evidence disposition from physical reactor regime.

These states describe why producer evidence cannot support a current physical classification. They are not plasma states, operating modes, phase labels, or quality grades. The only permitted regime projection is an unclassified RegimeState.UNKNOWN result.

Classes

ProducerEvidenceDisposition

Bases: StrEnum

Producer-owned reason that current plant truth is not classifiable.

ProducerEvidenceStatePolicy dataclass

ProducerEvidenceStatePolicy(
    disposition: ProducerEvidenceDisposition,
    validity_state: ValidityState,
    meaning: str,
)

One exact disposition-to-U0 validity and abstention policy.

Methods:

to_record

to_record() -> dict[str, object]

Return the deterministic public policy record.

Returns

dict[str, object] Canonical policy fields for portable serialization.

Functions:

producer_evidence_state_policy

producer_evidence_state_policy(
    disposition: ProducerEvidenceDisposition,
) -> ProducerEvidenceStatePolicy

Resolve one typed producer disposition without string coercion.

Parameters

disposition : ProducerEvidenceDisposition Exact typed producer evidence disposition.

Returns

ProducerEvidenceStatePolicy Immutable policy assigned to the disposition.

Raises

TypeError If disposition is not the declared enum type.

reference_portfolio

Non-actuating U0 reference records spanning nine reactor families.

Classes

ReactorReferenceSlice dataclass

ReactorReferenceSlice(
    slice_id: str,
    family: str,
    context: ReactorContext,
    observable: ObservableDescriptor,
    semantics: tuple[PhaseSemanticRecord, ...],
    regime: RegimeEstimate,
)

One multi-contract semantic fixture for a reactor family.

Functions:

build_reactor_reference_portfolio

build_reactor_reference_portfolio() -> tuple[
    ReactorReferenceSlice, ...
]

Return deterministic non-actuating records for all U0 family slices.

These records verify semantic breadth. They are scaffold evidence and make no experimental-validation or reactor-readiness claim.

Returns

tuple[ReactorReferenceSlice, ...] One deterministic review-only reference record per defined family slice.

regime_assessment

Digest-sealed, review-only identity for a complete reactor regime vector.

The codec validates an already supplied eight-axis assessment. It does not run a classifier, infer a regime, admit evidence for control, or actuate a device.

Classes

ReactorRegimeAxisDisposition

Bases: StrEnum

Classification disposition, separate from static applicability.

ReactorRegimeEvidenceBinding dataclass

ReactorRegimeEvidenceBinding(
    role_id: str, reference_id: str
)

Bind one ontology-required evidence role to a referenced artifact.

Methods:

__post_init__

__post_init__() -> None

Validate and normalise the evidence binding identifiers.

to_record

to_record() -> dict[str, str]

Return one deterministic evidence-role binding.

Returns

dict[str, str] JSON-compatible role and reference identifiers.

from_record classmethod

from_record(raw: object) -> ReactorRegimeEvidenceBinding

Decode one strict evidence-role binding.

Parameters

raw : object Candidate serialized evidence binding.

Returns

ReactorRegimeEvidenceBinding Validated immutable role-to-reference binding.

ReactorRegimeAxisAssessment dataclass

ReactorRegimeAxisAssessment(
    axis_id: str,
    static_applicability: AxisApplicability,
    disposition: ReactorRegimeAxisDisposition,
    label: str | None,
    confidence: float,
    observability: float,
    uncertainty_probability: float,
    uncertainty_basis_id: str | None,
    evidence_ids: tuple[str, ...],
    evidence_bindings: tuple[
        ReactorRegimeEvidenceBinding, ...
    ],
    evidence_class: EvidenceClass,
    validity: ValidityState,
    quality: QualityState,
    validity_id: str,
    quality_id: str,
    provenance_id: str,
    applicability_basis: tuple[str, ...],
    unknown_reason_id: str | None,
    classifier_id: str | None,
    classifier_version: str | None,
    classifier_sha256: str | None,
    threshold_policy_id: str | None,
    threshold_policy_version: str | None,
    threshold_policy_sha256: str | None,
    hysteresis_policy_id: str | None,
    hysteresis_policy_version: str | None,
    hysteresis_policy_sha256: str | None,
    dwell_samples: int | None,
    authority: str = REVIEW_ONLY_AUTHORITY,
    actionable: bool = False,
)

One evidence-bound row of a complete regime assessment.

Methods:

__post_init__

__post_init__() -> None

Validate and normalise one ontology-bound axis assessment.

to_record

to_record() -> dict[str, object]

Return a complete deterministic axis row.

Returns

dict[str, object] JSON-compatible axis disposition and evidence fields.

from_record classmethod

from_record(raw: object) -> ReactorRegimeAxisAssessment

Decode one strict axis row.

Parameters

raw : object Candidate serialized axis-assessment mapping.

Returns

ReactorRegimeAxisAssessment Validated immutable axis assessment.

Raises

ValueError If fields, enums, evidence bindings, or disposition invariants fail.

ReactorRegimeAssessment dataclass

ReactorRegimeAssessment(
    assessment_id: str,
    reactor_context_id: str,
    configuration: str,
    event_id: str,
    producer_project: str,
    producer_revision: str,
    producer_artifact_sha256: str,
    source_project: str,
    source_revision: str,
    source_handoff_schema: str,
    source_handoff_sha256: str,
    source_semantic_ids: tuple[str, ...],
    clock_domain: str,
    clock_kind: ClockKind,
    clock_epoch: str,
    clock_synchronization_id: str,
    evidence_timestamp_ns: int,
    assessed_at_ns: int,
    valid_from_ns: int,
    valid_until_ns: int,
    sample_rate_hz: float,
    latency_s: float,
    timestamp_offset_ps: int,
    axes: tuple[ReactorRegimeAxisAssessment, ...],
    reactor_registry_version: str,
    reactor_registry_digest: str,
    semantic_profile_registry_version: str,
    semantic_profile_registry_digest: str,
    observability_registry_version: str,
    observability_registry_digest: str,
    ontology_version: str,
    ontology_digest: str,
    classification_performed: bool = False,
    authority: str = REVIEW_ONLY_AUTHORITY,
    actionable: bool = False,
    schema: str = REACTOR_REGIME_ASSESSMENT_SCHEMA,
    schema_version: str = REACTOR_REGIME_ASSESSMENT_VERSION,
)

Portable identity for a full eight-axis reactor regime assessment.

Methods:

__post_init__

__post_init__() -> None

Validate and normalise a complete review-only assessment.

to_record

to_record() -> dict[str, object]

Return the complete deterministic assessment payload.

Returns

dict[str, object] JSON-compatible eight-axis assessment fields.

Functions:

regime_assessment_to_record

regime_assessment_to_record(
    assessment: ReactorRegimeAssessment,
) -> dict[str, object]

Return a digest-sealed portable assessment envelope.

Parameters

assessment : ReactorRegimeAssessment Validated eight-axis assessment to serialize.

Returns

dict[str, object] Envelope containing the assessment payload and payload digest.

regime_assessment_from_record

regime_assessment_from_record(
    raw: object,
) -> ReactorRegimeAssessment

Decode and verify one strict assessment record.

Parameters

raw : object Candidate serialized assessment envelope.

Returns

ReactorRegimeAssessment Validated review-only eight-axis assessment.

Raises

ValueError If schema, digest, enum, axis, clock, or registry validation fails.

regime_assessment_to_bytes

regime_assessment_to_bytes(
    assessment: ReactorRegimeAssessment,
) -> bytes

Encode canonical UTF-8 JSON bytes.

Parameters

assessment : ReactorRegimeAssessment Validated assessment to encode.

Returns

bytes Canonical compact JSON bytes.

regime_assessment_from_bytes

regime_assessment_from_bytes(
    data: bytes,
) -> ReactorRegimeAssessment

Decode bounded canonical bytes with duplicate-key refusal.

Parameters

data : bytes Candidate canonical assessment bytes.

Returns

ReactorRegimeAssessment Validated assessment reconstructed from the bytes.

Raises

ValueError If the input is malformed, duplicated, oversized, or noncanonical.

regime_assessment_digest

regime_assessment_digest(
    assessment: ReactorRegimeAssessment,
) -> str

Return SHA-256 of the complete canonical envelope bytes.

Parameters

assessment : ReactorRegimeAssessment Validated assessment whose canonical bytes are hashed.

Returns

str Lowercase hexadecimal SHA-256 digest.

regime_ontology

Closed meanings for reactor regime axes and physical or numerical modes.

The ontology validates names and evidence bindings. It does not infer a regime, extract a mode, admit evidence for control, or actuate a device.

Classes

AxisApplicability

Bases: StrEnum

Whether one regime axis has meaning in a particular context.

AxisApplicabilityPolicy

Bases: StrEnum

How static reactor context constrains an axis.

ModeDomain

Bases: StrEnum

Epistemically distinct physical and model-owned mode domains.

ReactorRegimeAxisDefinition dataclass

ReactorRegimeAxisDefinition(
    axis_id: str,
    meaning: str,
    labels: tuple[str, ...],
    candidate_ids: tuple[str, ...],
    applicability_policy: AxisApplicabilityPolicy,
    required_evidence: tuple[str, ...],
    authority: str = "review_only",
    actionable: bool = False,
)

Versioned meaning and closed labels for one compositional regime axis.

Methods:

__post_init__

__post_init__() -> None

Validate axis vocabulary, evidence requirements, and authority.

to_record

to_record() -> dict[str, object]

Return a deterministic definition record.

Returns

dict[str, object] JSON-compatible axis definition fields.

ReactorRegimeAxisAssignment dataclass

ReactorRegimeAxisAssignment(
    definition: ReactorRegimeAxisDefinition,
    applicability: AxisApplicability,
    label: str | None,
    confidence: float,
    evidence_ids: tuple[str, ...],
    applicability_basis: tuple[str, ...],
    authority: str = "review_only",
    actionable: bool = False,
)

Fail-closed runtime assignment against one axis definition.

Methods:

__post_init__

__post_init__() -> None

Validate applicability, label, confidence, evidence, and authority.

to_regime_axis

to_regime_axis() -> RegimeAxis

Project into U0 without collapsing absence into a nominal label.

Returns

RegimeAxis U0 regime axis preserving applicability or classification state.

to_record

to_record() -> dict[str, object]

Return a deterministic assignment record.

Returns

dict[str, object] JSON-compatible axis assignment fields.

ReactorModeDefinition dataclass

ReactorModeDefinition(
    mode_id: str,
    meaning: str,
    domain: ModeDomain,
    candidate_id: str,
    configurations: tuple[str, ...],
    admissible_carriers: tuple[SemanticCarrier, ...],
    admissible_evidence: tuple[EvidenceClass, ...],
    harmonic_basis: str | None,
    required_semantic_fields: tuple[str, ...],
    authority: str = "review_only",
    actionable: bool = False,
)

Namespaced physical or numerical mode-family definition.

Methods:

__post_init__

__post_init__() -> None

Validate mode identity, applicability, evidence, and domain rules.

to_record

to_record() -> dict[str, object]

Return a deterministic mode-family definition.

Returns

dict[str, object] JSON-compatible mode definition fields.

ReactorModeBinding dataclass

ReactorModeBinding(
    definition: ReactorModeDefinition,
    configuration: str,
    carrier: SemanticCarrier,
    evidence_class: EvidenceClass,
    mode_identity: str,
    harmonic_coordinates: tuple[int, int] | None,
    observation_operator_id: str | None,
    reference_frame: str | None,
    reference_signal_id: str | None,
    orientation: str | None,
    phase_origin: str | None,
    wrap_convention: str | None,
    observability_threshold: float | None,
    validity_id: str,
    quality_id: str,
    provenance_id: str,
    authority: str = "review_only",
    actionable: bool = False,
)

Evidence-bearing identity for one extracted physical or numerical mode.

Methods:

__post_init__

__post_init__() -> None

Validate binding identity, evidence, and domain-specific fields.

to_record

to_record() -> dict[str, object]

Return the complete deterministic mode binding.

Returns

dict[str, object] JSON-compatible physical or numerical mode binding fields.

ReactorRegimeModeOntologyRegistry dataclass

ReactorRegimeModeOntologyRegistry(
    version: str,
    reactor_registry_version: str,
    reactor_registry_digest: str,
    observability_registry_version: str,
    observability_registry_digest: str,
    axes: Mapping[str, ReactorRegimeAxisDefinition],
    modes: Mapping[str, ReactorModeDefinition],
)

Immutable ontology bound to exact reactor and observability registries.

Attributes

digest property

digest: str

Return SHA-256 of the canonical ontology record.

Methods:

__post_init__

__post_init__() -> None

Validate exact registry bindings, ontology entries, and coverage.

resolve_axis

resolve_axis(axis_id: str) -> ReactorRegimeAxisDefinition

Resolve one exact cross-family axis identifier.

Parameters

axis_id : str Exact regime-axis identifier.

Returns

ReactorRegimeAxisDefinition Registered cross-family axis definition.

Raises

ValueError If the identifier is invalid or is not registered.

resolve_mode

resolve_mode(mode_id: str) -> ReactorModeDefinition

Resolve one exact namespaced mode-family identifier.

Parameters

mode_id : str Exact namespaced mode-family identifier.

Returns

ReactorModeDefinition Registered mode-family definition.

Raises

ValueError If the identifier is invalid or is not registered.

modes_for_configuration

modes_for_configuration(
    configuration: str,
) -> tuple[ReactorModeDefinition, ...]

Return physical definitions plus the explicit numerical fallback.

Parameters

configuration : str Canonical reactor configuration identifier or registered alias.

Returns

tuple[ReactorModeDefinition, ...] Mode definitions applicable to the resolved configuration.

applicability_for

applicability_for(
    axis_id: str, configuration: str
) -> AxisApplicability

Return static semantic applicability, never a measured regime state.

Parameters

axis_id : str Exact regime-axis identifier. configuration : str Canonical reactor configuration identifier or registered alias.

Returns

AxisApplicability Static applicability derived from ontology and observability scope.

to_record

to_record() -> dict[str, object]

Return the canonical JSON-compatible ontology record.

Returns

dict[str, object] Ontology identity, axis definitions, and mode definitions.

Functions:

registry

Extension-safe fusion-reactor configuration registry.

Classes

ReactorConfiguration dataclass

ReactorConfiguration(
    identifier: str,
    confinement_family: ConfinementFamily,
    topology: str,
)

One reactor configuration known to a registry.

Parameters

identifier : str Stable configuration identifier. Extensions use a namespaced identifier such as "institution.example:novel_configuration". confinement_family : ConfinementFamily Broad physical family. topology : str Human-readable geometry or topology description.

Methods:

to_record

to_record() -> dict[str, str]

Return a deterministic JSON-compatible record.

Returns

dict[str, str] Configuration identifier, family, and topology fields.

ReactorConfigurationRegistry dataclass

ReactorConfigurationRegistry(
    version: str,
    configurations: Mapping[str, ReactorConfiguration],
    aliases: Mapping[str, str],
)

Immutable registry of reactor configurations and aliases.

Attributes

digest property

digest: str

Return the SHA-256 digest of the canonical registry record.

Methods:

resolve

resolve(identifier: str) -> ReactorConfiguration

Resolve a canonical identifier or alias.

Parameters

identifier : str Canonical reactor configuration identifier or registered alias.

Returns

ReactorConfiguration Registered canonical configuration.

Raises

ValueError If the identifier is not registered.

register

register(
    configuration: ReactorConfiguration,
    *,
    aliases: tuple[str, ...] = (),
) -> ReactorConfigurationRegistry

Return a new registry containing one namespaced extension.

Built-in identifiers cannot be shadowed. Extensions must contain a namespace separator so local names cannot silently acquire new meaning.

Parameters

configuration : ReactorConfiguration Namespaced configuration to add. aliases : tuple[str, ...] Optional namespaced aliases for the new configuration.

Returns

ReactorConfigurationRegistry New immutable registry containing the extension.

Raises

ValueError If identifiers are not namespaced, collide, or are invalid.

to_record

to_record() -> dict[str, object]

Return the sorted deterministic registry record.

Returns

dict[str, object] JSON-compatible registry version, aliases, and configurations.

Functions:

resolve_reactor_registry_release

resolve_reactor_registry_release(
    version: str, digest: str
) -> ReactorConfigurationRegistry

Resolve one exact immutable registry release.

Producer objects remain bound to the release under which their bytes were authored. Recognising that release preserves custody; it does not silently upgrade or reinterpret the producer object against the current registry.

Parameters

version : str Exact semantic version declared by the producer. digest : str Exact SHA-256 digest of the canonical registry record.

Returns

ReactorConfigurationRegistry Recognised immutable release.

Raises

ValueError If the version and digest pair is not a recognised release.

semantic_profiles

Versioned ownership and verified-ingress profiles for reactor semantics.

Classes

SemanticIngressState

Bases: StrEnum

Evidence-backed availability of a producer-to-SPO adapter.

ReactorSemanticProfile dataclass

ReactorSemanticProfile(
    configuration: str,
    device_project: str,
    ingress_state: SemanticIngressState,
    producer_project: str | None = None,
    source_schema: str | None = None,
    adapter_api: str | None = None,
    handoff_schema: str | None = None,
    semantic_profile: str | None = None,
    semantic_profile_version: str | None = None,
    control_adapter_contract: str | None = None,
    control_intent_profile: str | None = None,
    authority: str = "review_only",
    actionable: bool = False,
    machine_protection_final_veto: bool = True,
)

SPO binding for one reactor configuration.

device_project records scientific ownership. Producer and adapter fields are populated only when an exercised, versioned ingress exists. Absence is explicit and cannot be interpreted as an inherited generic reactor adapter.

Methods:

__post_init__

__post_init__() -> None

Validate ownership, ingress completeness, and review authority.

to_record

to_record() -> dict[str, object]

Return the complete deterministic profile record.

Returns

dict[str, object] JSON-compatible ownership, ingress, and authority fields.

ReactorSemanticProfileRegistry dataclass

ReactorSemanticProfileRegistry(
    version: str,
    reactor_registry_version: str,
    reactor_registry_digest: str,
    assignment_map_sha256: str,
    profiles: Mapping[str, ReactorSemanticProfile],
)

Immutable semantic ownership and verified-ingress registry.

Attributes

digest property

digest: str

Return the SHA-256 of the canonical registry record.

Methods:

__post_init__

__post_init__() -> None

Validate complete coverage and exact reactor-registry binding.

resolve

resolve(configuration: str) -> ReactorSemanticProfile

Resolve a canonical configuration or registry alias.

Parameters

configuration : str Canonical reactor configuration identifier or registered alias.

Returns

ReactorSemanticProfile Semantic ownership and ingress profile for the configuration.

to_record

to_record() -> dict[str, object]

Return a canonical JSON-compatible registry record.

Returns

dict[str, object] Registry identity and all configuration profiles.

Functions:

serialization

Canonical serialization and strict dispatch for U0 contracts.

Classes

Functions:

contract_to_record

contract_to_record(
    contract: ReactorSemanticContract,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> dict[str, object]

Return a typed envelope for a U0 contract.

Parameters

contract : ReactorSemanticContract Contract to serialize. registry : ReactorConfigurationRegistry Registry used to validate embedded reactor identities.

Returns

dict[str, object] Typed U0 contract envelope.

Raises

TypeError If contract is not a supported concrete contract type.

contract_from_record

contract_from_record(
    raw: object,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> ReactorSemanticContract

Load one contract and refuse unknown fields, kinds, or schema versions.

Parameters

raw : object Candidate contract envelope. registry : ReactorConfigurationRegistry Registry used to validate embedded reactor identities.

Returns

ReactorSemanticContract Validated concrete contract.

Raises

ValueError If the envelope, payload, schema, or contract type is invalid.

canonical_json

canonical_json(
    contract: ReactorSemanticContract,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> str

Serialize a contract to byte-stable canonical JSON.

Parameters

contract : ReactorSemanticContract Contract to serialize. registry : ReactorConfigurationRegistry Registry used to validate embedded reactor identities.

Returns

str Canonical JSON text with sorted keys and compact separators.

contract_from_json

contract_from_json(
    payload: str,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> ReactorSemanticContract

Deserialize canonical or ordinary JSON with duplicate-key refusal.

Parameters

payload : str JSON contract envelope. registry : ReactorConfigurationRegistry Registry used to validate embedded reactor identities.

Returns

ReactorSemanticContract Validated concrete contract.

Raises

ValueError If the JSON is empty, malformed, duplicated, or contract-invalid.

contract_digest

contract_digest(
    contract: ReactorSemanticContract,
    *,
    registry: ReactorConfigurationRegistry = DEFAULT_REACTOR_REGISTRY,
) -> str

Return the SHA-256 digest of canonical contract JSON.

Parameters

contract : ReactorSemanticContract Contract to digest. registry : ReactorConfigurationRegistry Registry used to validate embedded reactor identities.

Returns

str Lowercase hexadecimal SHA-256 digest.

vocabulary

Closed semantic primitives for the U0 reactor contract.

The reactor configuration itself is deliberately not an enum. Configurations are registry entries so new reactor topologies can be added without changing the carrier algebra or pretending that they are tokamaks.

Classes

SemanticCarrier

Bases: StrEnum

Mathematical carrier of a semantic record.

ConfinementFamily

Bases: StrEnum

Broad physical confinement family, independent of reactor geometry.

DriverKind

Bases: StrEnum

Energy, confinement, or compression driver.

OperatingCadence

Bases: StrEnum

Temporal operating form of a device or experiment.

ClockKind

Bases: StrEnum

Declared time basis; domains of different kinds are never implicit peers.

ReactionKind

Bases: StrEnum

Fusion reaction or fuel class, separate from confinement.

ConversionKind

Bases: StrEnum

Energy-conversion or experimental boundary.

EvidenceClass

Bases: StrEnum

Maturity and epistemic source of a claim.

ValidityState

Bases: StrEnum

Fail-closed validity state for a semantic object.

QualityState

Bases: StrEnum

Measurement or estimator quality.

PhaseRelationType

Bases: StrEnum

Declared relationship between two phase records.

RelationInterpretation

Bases: StrEnum

Operational interpretation of a phase relationship.

RegimeState

Bases: StrEnum

Top-level operational state without erasing regime axes.

Functions:

require_text

require_text(value: object, *, field: str) -> str

Return a stripped non-empty string.

Parameters

value : object Candidate value. field : str Field name used in diagnostics.

Returns

str Validated text.

Raises

ValueError If the value is not a non-empty string.

require_enum

require_enum(
    value: object, enum_type: type[EnumType], *, field: str
) -> EnumType

Return an enum member without coercing untyped public input.

Parameters

value : object Candidate enum member. enum_type : type[EnumType] Required enum class. field : str Field name used in diagnostics.

Returns

EnumType The validated enum member.

Raises

ValueError If value is not a member of enum_type.

require_identifier

require_identifier(value: object, *, field: str) -> str

Return a validated identifier.

Identifiers support namespaces separated by a colon, allowing extension registries without changing the core configuration vocabulary.

Parameters

value : object Candidate identifier. field : str Field name used in diagnostics.

Returns

str The validated identifier.

Raises

ValueError If value is empty, not text, or violates identifier syntax.

require_semver

require_semver(value: object, *, field: str) -> str

Return a strict MAJOR.MINOR.PATCH version.

Parameters

value : object Candidate semantic version. field : str Field name used in diagnostics.

Returns

str The validated semantic version.

Raises

ValueError If value is not non-empty text in MAJOR.MINOR.PATCH form.

require_u0_schema

require_u0_schema(value: object) -> str

Return the supported U0 schema version or refuse compatibility.

Parameters

value : object Candidate U0 schema version.

Returns

str The exact supported U0 schema version.

Raises

ValueError If the version is malformed, historical, or forward-incompatible.

require_sha256

require_sha256(value: object, *, field: str) -> str

Return one lowercase hexadecimal SHA-256 digest.

Parameters

value : object Candidate digest. field : str Field name used in diagnostics.

Returns

str The validated 64-character digest.

Raises

ValueError If value is not a lowercase hexadecimal SHA-256 digest.

finite_real

finite_real(value: object, *, field: str) -> float

Return a finite real scalar while rejecting booleans.

Parameters

value : object Candidate scalar. field : str Field name used in diagnostics.

Returns

float The validated finite scalar.

Raises

ValueError If value is boolean, non-real, or non-finite.

non_negative_real

non_negative_real(value: object, *, field: str) -> float

Return a finite non-negative real scalar.

Parameters

value : object Candidate scalar. field : str Field name used in diagnostics.

Returns

float The validated non-negative scalar.

Raises

ValueError If value is not finite and real or is negative.

probability

probability(value: object, *, field: str) -> float

Return a probability in the closed interval zero to one.

Parameters

value : object Candidate probability. field : str Field name used in diagnostics.

Returns

float The validated probability.

Raises

ValueError If value is not finite and real or lies outside [0, 1].

non_negative_integer

non_negative_integer(value: object, *, field: str) -> int

Return a non-negative integer while rejecting booleans.

Parameters

value : object Candidate integer. field : str Field name used in diagnostics.

Returns

int The validated non-negative integer.

Raises

ValueError If value is boolean, non-integral, or negative.

require_exact_keys

require_exact_keys(
    payload: object,
    *,
    required: frozenset[str],
    optional: frozenset[str] = frozenset(),
    field: str,
) -> dict[str, object]

Return a mapping only when its key set matches the contract.

Parameters

payload : object Candidate mapping. required : frozenset[str] Keys that must be present. optional : frozenset[str] Additional permitted keys. field : str Field name used in diagnostics.

Returns

dict[str, object] The validated input mapping.

Raises

ValueError If the input is not a string-keyed mapping or its key set differs.