Skip to content

Glossary

For anyone reading CORA. Each term defined once and used the same way in code, commits, and prose. Names are load-bearing; drift in vocabulary is drift in the model. If a page uses a term differently, the page is wrong.

Architecture

BCs, aggregates, deciders, slices, FCIS, ports, kernel.

  • Bounded context (BC). A self-contained slice of the domain with its own model, language, API surface. Examples: access, equipment, recipe, run, data, decision, subject, trust, agent, calibration.
  • Aggregate. Consistency boundary inside a BC. Holds state, validates commands, emits events.
  • Decider. Pure (state, command) -> events. Business rules. No I/O.
  • Evolver. Pure (state, event) -> state. Folds events into state.
  • Fold-on-read. Rebuild aggregate state by replaying events on every command. No snapshots yet.
  • Vertical slice. One folder per command or query: command.py, decider.py, handler.py, route.py, tool.py.
  • FCIS. Functional core / imperative shell. Pure deciders and evolvers; all I/O at the shell via injected ports.
  • Port. A Protocol defining a side-effect seam (clock, ID generator, event store, Authorize, idempotency, TokenVerifier, LLM, LogbookMirror).
  • Kernel. Shared kernel: cross-BC primitives (event envelope, deps wiring, authorize factory, token-verifier registry).
  • Slim vs Lifecycle aggregate. Two patterns for cheap replay. Slim closes out and starts fresh; Lifecycle carries state across phases.

Events

Event store, streams, positions, transactions, projections.

  • Event store. Append-only Postgres table of immutable events. INSERT-only at the DB role level.
  • Stream. All events for one aggregate instance, ordered by version.
  • Position. Global monotonic ordinal of an event in the store.
  • transaction_id (xid8). PG18 transaction identifier on every event. Lets projection workers advance a cursor without skipping in-flight inserts.
  • Projection. A read model built by replaying events into a denormalized table. Workers tail the store and advance a bookmark.

Surfaces

REST, MCP, A2A, Surface aggregate.

  • REST. FastAPI HTTP endpoints under /<resource>. OpenAPI at /docs.
  • MCP. Model Context Protocol, the LLM-agent surface. Streamable HTTP at /mcp. Same handler as REST.
  • A2A. Agent-to-Agent protocol. Planned trust-boundary surface for cross-organization agent calls (deferred).
  • Surface. (Trust BC, Phase B) Aggregate naming the ingress shape a call arrives through. Closed SurfaceKind enum: HTTP, MCP_STDIO, MCP_STREAMABLE_HTTP. surface_id threads through every handler, the Authorize port, Policy evaluation, and the idempotency cache key namespace (IETF draft-07 §5 composite key).

Standards

ISA, ISO/IEC, NIST, PROV-O, RAiD.

  • ISA-95. Manufacturing operations hierarchy: Enterprise / Site / Area / Unit / Assembly / Device. Used for the Asset model.
  • ISA-88. Batch control. Basis for Track A (Method / Practice / Plan / Run).
  • ISA-106. Continuous-process operations. Basis for Track B.
  • ISA-99 / IEC 62443. Industrial cybersecurity. Basis for Track C: Zones, Conduits, Policies (trust BC).
  • ISO/IEC 42001 + NIST AI RMF. AI governance frameworks. Inform Decision and Strategy BCs.
  • W3C PROV-O. Provenance ontology. Borrowed at API boundaries (Activity, Entity, Agent, used, wasGeneratedBy). W3C Provenance Working Group is closed; PROV-O is frozen 2013 bedrock vocabulary, not a moving spec. Community momentum lives in downstream consumers (RO-Crate, FAIRSCAPE).
  • RAiD (ISO 23527). Research Activity Identifier. Forward-compat field on RunStarted.

Watch-only (not adopted as a glossary term, see Deferred):

  • PIDINST. RDA-WG recommendation for persistent IDs of physical instruments, layered on DataCite Schema 4.5+ via resourceTypeGeneral=Instrument. Adoption is thin (HZB at BESSY II is the only confirmed photon-science adopter as of 2026), so CORA treats it as a watch item rather than a standard. The Asset model reserves capacity for a publication-quality persistent ID; the minting profile (PIDINST vs raw DataCite Instrument resourceType vs other) is decided when first needed.

Authz

ReBAC, BOLA, Cedar, principal, actor vs profile, bearer-token edge auth.

  • ReBAC. Relationship-based access control (planned: SpiceDB or OpenFGA). For multi-stakeholder ownership common in shared facilities.
  • BOLA. Broken Object-Level Authorization (OWASP API #1). Covered by a parametrized cross-principal contract test on every read endpoint (12 aggregates today).
  • Cedar. Policy language used in decision BC predicates.
  • Principal. Authenticated identity attached to every command and event envelope. Required in production via REQUIRE_AUTHENTICATED_PRINCIPAL=true.
  • Actor vs Profile. Actor is the immutable identity in events; Profile is the mutable PII row, separately stored and erasable. GDPR-shaped. Actor.kind ∈ {human, agent, service_account} (Phase C widening).
  • Authorize port. Single seam: authorize(subject, command_name, conduit_id, surface_id) → AuthorizeDecision. Exposed on the kernel as Kernel.authz. Every command and query passes through it.
  • TokenVerifier port. Edge-auth seam: verify(token) → VerifiedPrincipal. Two adapters today — JWTVerifier (JWKS, RFC 9068) and IntrospectionVerifier (RFC 7662). IdentityProviderRegistry routes by iss claim.
  • BearerAuthMiddleware. ASGI middleware at the HTTP edge. Reads Authorization: Bearer, verifies via Kernel.token_verifier, stashes VerifiedPrincipal on request.state.principal.

Equipment

Assets, Families, Affordances. The device-classification side of Equipment BC.

  • Asset. A physical equipment instance registered in the hierarchy (Enterprise / Site / Area / Unit / Device per ISA-95). Belongs to one or more Families.
  • Family. A device-class abstraction: WHAT kind of equipment this is, device-agnostic. Examples: RotaryStage, LinearStage, Camera, Scintillator, Hexapod, Mirror. Until phase 5i this aggregate was named Capability; phase 6k (shipped 2026-05-18) introduced a NEW Recipe BC Capability aggregate at the operations-layer (separate concept; see below).
  • Affordance. A closed-enum primitive a Family declares it supports. Two patterns: operational affordances (-able/-ible/-ing suffix per Swift Guidelines, "device supports doing X" or "device performs X"; 27 items mixing 22 -able/-ible actions with 5 -ing role/flow gerunds — Marking, Pulsing, Following, Leading, Recording), and lifecycle affordances (noun, "device has lifecycle property X"; 1 item — Consumable). Cross-BC contract: at define_plan time, the union of every wired Asset's Families' affordances must cover the bound Method's Capability required_affordances (otherwise PlanAffordancesNotSatisfiedError, 409). See Affordances reference for the 28-item v1 list.

Recipe ladder

Capability, method, practice, plan, run, logbook.

  • Capability. (Recipe BC, phase 6k) An operations-layer template declaring WHAT a Method or Procedure can do: required_affordances (the Family-affordance contract any binding must cover), parameter_schema (the parameter contract Method.parameters_schema must be a subset of), executor_shapes (closed v1 enum {METHOD, PROCEDURE} — which executor kinds may bind). Distinct from Equipment Family (what a device IS); Capability is what an operation provides. Methods bind via Method.capability_id (REQUIRED post-6l-strict); Procedures bind via Procedure.capability_id (optional). Namespaced cora.capability.* codes; status FSM Defined → Versioned → Deprecated with optional replaced_by_capability_id (LOINC MAP_TO precedent).
  • ExecutorShape. (Recipe BC, phase 6k closed v1 StrEnum) Declares which executor kinds may implement a Capability: METHOD (heavyweight science executor producing datasets via Plan → Run) or PROCEDURE (lightweight ceremony executor without datasets, ISA-106 atoms). One Capability may declare both shapes.
  • Method. A reusable technique template. Binds to one Capability via capability_id (REQUIRED) and to a set of Equipment Families via needed_families (hardware-compat). Method's parameters_schema must be a structural subset of the bound Capability's parameter_schema (MethodParametersNotSubsetError, 409).
  • Practice. A Method bound to a site or set of Families.
  • Plan. A Practice bound to specific Assets and a window.
  • Run. An execution of a Plan. FSM: started, held, resumed, stopped, completed, aborted, truncated.
  • Logbook. Append-only narrative log on a Run or Decision. Used for OTel gen_ai.* reasoning entries on Decisions.

Agents

Agent BC, RunDebrief, CautionDrafter.

  • Agent. (Agent BC, phase 8f-a) Config-only aggregate naming a configured LLM agent: kind (free-form AgentKind), name, version, model_ref, prompt_template_id, capabilities, tools, budget. FSM Defined → Versioned ⇄ Suspended → Deprecated. Agent.id is shared with Access BC's Actor.id for the same agent (cross-BC atomic via EventStore.append_streams; every Agent.id is also an Actor.id with kind="agent").
  • RunDebrief. First registered Agent. Subscribes to terminal Run events; proposes a debrief entry via the LLM port; result lands in the Run logbook.
  • CautionDrafter. Second registered Agent. Subscribes to terminal Run events; proposes a Caution (5-choice enum: NoAction / ProposeNotice / ProposeCaution / ProposeWarning / ProposeSupersede) and promotes via promote_caution_proposal (writes Caution BC events directly via EventStore.append_streams).

Calibration

Calibration BC, AsShot anchor, pinned vs used.

  • Calibration. (Calibration BC, phase 12a) Aggregate carrying empirically-measured system constants (motor sensitivities, beam profiles, encoder offsets). Distinct from operation/calibration ceremonies — Operation runs the ceremony, Calibration stores the resulting values.
  • AsShot anchor. Snapshot of which Calibrations were in force at a given moment. Run.pinned_calibrations (Phase 12b) captures the Calibrations pinned at start_run; Dataset.used_calibrations (Phase 12c) captures which of those the resulting Dataset actually consumed. The pair separates "what was available" from "what was used," which the analysis chain needs for provenance.