Modules¶
Each module is a bounded area of CORA's domain with its own aggregates, events, and slices. Every module page follows the same shape: purpose, maturity, aggregates, value objects, FSM, events, slices, storage, cross-module boundaries, and runnable examples.
- Two surfaces, same behavior. Every slice exposes a REST path for human operators and integration callers (hit it with
curl,httpx,HTTPie, or any HTTP client) and an MCP tool for agent callers via the Model Context Protocol SDK. The MCP tool name matches the slice verb, and the argument keys mirror the REST JSON body 1-to-1. Same payload, same errors, same events: pick whichever fits the caller. - Auth. Every call carries the calling actor's identity. In bearer mode (
IDENTITY_PROVIDERSconfigured) the sameBearerAuthMiddlewareverifies tokens for both REST and MCP streamable-HTTP, with audience bound per Surface; in legacy mode anX-Principal-Id: <uuid>header from a verifying proxy carries it instead. Either way, REST and MCP land on the sameprincipal_idat the handler. See the Auth page. - Idempotency. Slices marked required in the Idempotency column of each module's Slices table accept an
Idempotency-Key: <uuid>header. Resending the same key with the same body returns the cached response, so operator retries after network blips are safe.
Cross-module relationship vocabulary¶
The Cross-Module boundaries table on each module page uses a fixed set of verbs to classify the coupling. Anything not in this table is something the decider does not check at write time.
| Verb | Meaning |
|---|---|
gated-by |
A port owned by the other module sits in front of every write slice and can refuse the command. Used for Trust's Authorize port. |
reads-from |
This module's handler loads state from the other module's read model or aggregate at write time, but never writes to it. |
writes-to via append_streams |
A single command emits events into both streams atomically in one Postgres transaction (cross-aggregate write). |
shared-id-with |
An id field references the other module's aggregate. Validated for UUID shape at the API boundary, not for existence at write time. |
shared-enum-with |
This module references a closed enum owned by the other (no instance link). |
depends-on / depends-on-kind |
This module references a type-level value (Family.id, Supply.kind string) owned by the other. depends-on-kind marks the kinds-not-ids variant. |
upstream-of / upstream-of-kind |
Inverse of reads-from / depends-on-kind. Used when the row sits on the producer's page describing a downstream consumer. |
targeted-by |
The other module holds a polymorphic target reference (e.g. Caution.target = AssetTarget(asset_id=...)) pointing at this module. |
aligns-with |
No schema link today, but the two aggregates belong in the same conceptual frame and a reader should know they sit side by side. |
Pages¶
-
Run stable
Execution layer of the recipe ladder. One Run is one execution instance with a closed FSM, parameter resolution, reading logbook, and cross-module anchors to Plan, Subject, Asset, Clearance, Campaign, and Calibration.
-
Safety stable
Formal regulatory clearances that gate work. ESAF, SAF, A-form, DUO, ESRA, ERA, PLHD, DOOR, BTR, and Form 9 lifecycles, with multi-step review chains and cross-module coverage queries.
-
Caution stable
Operator-authored tribal-knowledge notes. Lightweight three-state lifecycle, supersession-as-edit, non-blocking banners at Run.start. Distinct from Safety: never gates work, no review board.
-
Calibration stable
Empirical instrument values keyed by
(asset, quantity, operating_point). Append-only revisions, per-revision status, polymorphic source (Measured / Computed / Asserted), AsShot pinning into Run and Dataset. -
Agent stable
Typed configuration for CORA's five agents: two LLM (RunDebriefer, CautionDrafter) and three deterministic (RunSupervisor, CautionPromoter, ClearanceExpirer). Four-state lifecycle with Suspended pause, shared id with Access Actor, MCP tool allowlist, declarative budgets, and passive plus active runtimes.
-
Campaign stable
Operator-declared coordinated study container above Run. Series, sweep, coordinated, or scheduling-block intent, five-state lifecycle with operator hold, atomic two-stream membership writes, and an open-status-default list view.
-
Operation stable
Episodic operational tasks: bakeout, characterization, alignment, recovery. Five-state Procedure FSM with truncate for retroactive cleanup, polymorphic per-step entries (setpoint, action, check), and optional binding as a Phase-of-Run.
-
Supply stable
Continuously-available resources (photon beam, LN2, compressed air, electrical power, vacuum). Five-state availability FSM with Phoebus-style latched recovery, typed
(facility_code, containing_asset_id, kind, name)address with cross-BC bindings to the Federation Facility + Equipment Asset hierarchies, and operator-asserted transitions today. -
Access stable
Foundation BC for principal identity: one aggregate (
Actor), three events, two-state lifecycle, shared identity withAgent. The "who you are" layer that every other module references when attributing an event. -
Equipment stable
Eight aggregates (
Assembly,Asset,Family,Fixture,Frame,Model,Mount,Role), four-state Asset lifecycle, three-state condition orthogonal to lifecycle, a three-tier intrinsic Asset tree (Unit/Component/DeviceviaAssetTier) bound to its owning Facility byfacility_code, settings-schema validation against the Family-declared Capability, and typed ports for wiring devices into Plans. -
Recipe stable
Five aggregates of CORA's planning side:
Capability,Method,Plan,Practice,Recipe.Capabilityis the executor-agnostic template above the recipe ladder;Method,Practice, andPlanare its upper rungs (ISA-88 general/site/master recipe), andRecipeis the deployment-bound step body. The control-recipe rung, Run, is the "what actually happened" layer below. -
Trust stable
ISA-99/IEC-62443 topology of
Zone,Conduit,Surface,Policy,Visit. Pure Policy Decision Point; Authorize port gates every write-side decider in CORA; first concrete entries-table observation logbook for per-decision audit. -
Subject stable
One aggregate, seven-state lifecycle with three terminal dispositions, mount/dismount cycle, Asset-lifecycle guard on mount, generic across science domains (materials samples, biological specimens, manufactured parts, astronomical targets, computational subjects).
-
Data stable
Five aggregates across a dataset's life:
Dataset(logical content identity, Trial / Production / Retracted intent, lineage edges, AsShot calibration citation),Distribution(byte-copies at storage Supplies, DCAT-3 shaped, four-state availability FSM),Attestation(recorded checksum / format / bit-rot fact-chain that flips Distribution status),Edition(citable, sealable, DOI-mintable publication packages, four-state FSM), andAcquisition(the birth-certificate fact linking a producing Asset and Run to the Dataset it captured). -
Decision stable
One aggregate, atomic-immutable for decision facts,
parent_idchains for corrections, appeals, supersessions, and invalidations. PROV-AGENT-aligned field names, ISO 17025decision_rulecitation, operator rating accrual channel. -
:material-link-variant-outline:{ .lg .middle } Federation beta
Cross-facility data flows: peer-facility identity (
Facility), flow authorization (Permit), secret-material binding (Credential), and per-facility registry-head signing (Seal). Trust gates who may act inside the facility; Federation gates what crosses the boundary. -
Enclosure alpha
Permit-status observation for spaces that gate experiments (hutches, sample-prep cabinets, instrument vaults). Three-state status (
Permitted,NotPermitted,Unknown) driven only by monitor-side observations, plus an orthogonal operator-driven decommission lifecycle. Sibling to Supply.