# MintPass Protocol Semantic Dictionary

> **Export Date:** 2026-05-19T02:22:28.421Z
> **Dictionary Version:** 1.0.0
> **Term Count:** 103
> **Programme:** MintPass Protocol Foundations
> **Data Sources:** /api/dictionary-data, /api/semantic-laws, /api/drift-classifications, /api/canonical-mappings

---

## Table of Contents

1. [Non-Authoritative Clarification](#non-authoritative-clarification)
2. [Protocol Semantic Laws](#protocol-semantic-laws)
3. [Drift Classification Summary](#drift-classification-summary)
4. [Canonical Mapping Coverage](#canonical-mapping-coverage)
5. [Governance Framework](#governance-framework)
6. [Dictionary Terms](#dictionary-terms)
   - [Core Protocol](#core-protocol)
   - [Lifecycle & State](#lifecycle-state)
   - [Evaluation & Truth](#evaluation-truth)
   - [Execution & Mutation](#execution-mutation)
   - [Authority & Governance](#authority-governance)
   - [Enforcement & Guardian](#enforcement-guardian)
   - [Agent & Recovery](#agent-recovery)
   - [Profile Extension](#profile-extension)

---

## Non-Authoritative Clarification

> **"Non-authoritative" does not mean operationally unimportant.** It means the field or term must not independently determine protocol truth.

Non-authoritative metadata may be required for presentation, audit trails, evidence collection, domain translation, carrier rendering, and operational context. Dropping non-authoritative data is not a safe default.

**Key Points:**

- A non-authoritative field carries information that is valid and useful, but that information is derived from or subordinate to an authoritative source.
- Non-authoritative fields must be preserved, passed through evaluation surfaces as context, and persisted for audit and operational purposes.
- The error is not in having non-authoritative fields — it is in using them to drive protocol decisions that must be governed by authoritative fields.
- When in doubt: keep the data, route the decision to the authoritative source.

---

## Protocol Semantic Laws

These laws codify existing semantic invariants as citable, implementation-neutral governance instruments.

### PSL-001: State is protocol truth; status is not.

**Governs:** Lifecycle & State

**Rationale:** The canonical lifecycle field `lifecycle_state_canonical` is the sole authoritative signal for where an entitlement exists in its lifecycle. Status fields are projections derived for presentation and must not be used to drive protocol decisions.

**Terms Referenced:** State, Status, Lifecycle

### PSL-002: Evaluation is read-only; execution mutates.

**Governs:** Evaluation & Truth

**Rationale:** Evaluation determines exercisability without producing side effects. Only an authorised execution operation may produce a state change. Conflating evaluation with execution violates the protocol's mutation boundary.

**Terms Referenced:** Evaluation, Execution, Constraint Engine

### PSL-003: The Convergence Engine is the sole authority for exercisability.

**Governs:** Evaluation & Truth

**Rationale:** No external signal, carrier document, or presentation field may override a Convergence Engine outcome. Exercisability is a protocol truth produced only by CE evaluation against the full constraint dimension set.

**Terms Referenced:** Convergence Engine, Evaluation, Entitlement

### PSL-004: Guardian enforces invariants independently of CE outcome.

**Governs:** Enforcement & Guardian

**Rationale:** Guardian protects structural protocol integrity and may block execution even when CE returns PASS. Guardian and CE serve distinct roles; a CE pass does not constitute Guardian clearance.

**Terms Referenced:** Guardian, Convergence Engine, Execution

### PSL-005: BLOCKED is recoverable; DENIED is terminal.

**Governs:** Evaluation & Truth

**Rationale:** A BLOCKED outcome signals a constraint condition that may be resolved through remediation. A DENIED outcome signals a structural or permanent barrier that cannot be overcome by any actor action. These two outcomes must never be treated as equivalent.

**Terms Referenced:** BLOCKED, DENIED, Evaluation

### PSL-006: Enforcement overlays are liftable; Guardian blocks are not.

**Governs:** Enforcement & Guardian

**Rationale:** Administrative enforcement actions — freeze, suspend, hold, restrict — may be reversed by an authorised actor. Guardian invariant violations reflect structural protocol breaches that cannot be overridden by any actor or administrative action.

**Terms Referenced:** Guardian, Enforcement Action, Overlay

### PSL-007: Carriers never create protocol truth.

**Governs:** Authority & Governance

**Rationale:** Presentation formats, transport wrappers, QR codes, PDFs, and carrier documents may reference entitlements but do not define, confirm, or alter their state. Protocol truth lives in the protocol record, not in any derived or rendered form.

**Terms Referenced:** Carrier, State, Entitlement

### PSL-008: Domain language must map into canonical protocol terms before execution.

**Governs:** Profile Extension

**Rationale:** Profile-specific vocabulary must resolve to canonical protocol operations before the protocol acts on them. Operating on untranslated domain language bypasses the semantic governance layer and produces undefined protocol behaviour.

**Terms Referenced:** Domain Translation, Canonical Term, Execution

### PSL-009: All repeatable events must be recorded as event records, not as overwritten timestamps.

**Governs:** Lifecycle & State

**Rationale:** When a lifecycle event can occur more than once, each occurrence must be persisted as an immutable event record. Overwriting a single timestamp destroys the historical record required for audit, analytics, and protocol dispute resolution.

**Terms Referenced:** Lifecycle, State, Audit

### PSL-010: An entitlement's exercisability is evaluated against the full constraint dimension set in deterministic precedence order.

**Governs:** Evaluation & Truth

**Rationale:** The eight evaluation dimensions — lifecycle, temporal, enforcement, dependency, capacity, verification, delegation, acceptance — are evaluated in fixed precedence order. No dimension may be selectively skipped, and precedence may not be altered by external configuration.

**Terms Referenced:** Constraint Engine, Evaluation, Convergence Engine

---

## Drift Classification Summary

The Semantic Drift Classification is the FOURTH independent dimension in the dictionary schema.
It answers: *Is this term at risk of semantic drift, misuse, or confusion?*

| Classification | Count | Description |
|---|---|---|
| **STABLE** | 14 | Term has stable, unambiguous meaning across all protocol contexts |
| **AMBIGUOUS** | 9 | Term has collision risk with common language or other protocol terms |
| **DEPRECATED** | 1 | Term is formally deprecated; use replacement term |
| **DOMAIN_ONLY** | 10 | Term belongs to domain profiles, not core protocol |
| **NOT_FIRST_CLASS** | 4 | Concept is valid but not a primary protocol citizen |
| **PRESENTATION_ONLY** | 3 | Term exists for display purposes only |

**AMBIGUOUS terms:** Status, Policy, Result, Booking, Policy, Action, Dry run, Holder, Decision

**DEPRECATED terms:** Execute

**DOMAIN_ONLY terms:** Redeem, Claim, Coverage, Incident, Membership, Itinerary, Policyholder, Subscription, Gift card, Loyalty

**NOT_FIRST_CLASS terms:** Reservation, Hold, Synthetic, Sandbox

**PRESENTATION_ONLY terms:** Presentation state, Wallet, Availability

**STABLE terms:** Container, Entitlement, State, Consume, Evaluation, Guardian, Authority, Delegation, Enforcement, Authorisation, PASS, BLOCKED, DENIED, Constraint

---

## Canonical Mapping Coverage

**Coverage:** 52 / 103 terms mapped

| Confidence | Count |
|---|---|
| HIGH | 40 |
| MEDIUM | 19 |
| LOW | 17 |

---

## Governance Framework

The governance metadata schema provides 10 fields per term covering semantic stability, migration risk, governance status, and review triggers. Populated for 24 terms in this version.

**Governance Metadata Fields:**
`semantic_stability`, `migration_risk`, `governance_status`, `superseded_by`, `replacement_term`, `deprecated_since`, `last_reviewed`, `review_trigger`, `governance_notes`, `domain_profiles`

---

## Dictionary Terms

## Core Protocol

### Container

> A Container is a governed collection scope that groups one or more Entitlements under shared policy, lifecycle rules, and authority constraints.

**Definition:** Containers establish the organisational boundary within which Entitlements exist. A Container carries its own lifecycle state, policy references, and access controls that apply to all member Entitlements. Creating or modifying a Container is a protocol mutation subject to the full mutation pipeline.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `YES` |
| Semantic Owner | `Core Protocol` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `HIGH` |
| Confidence | `HIGH` |

**Permitted:** Use to represent the top-level scope grouping Entitlements. Reference in issuance, policy, enforcement, and lifecycle operations.

**Prohibited:** Do not use interchangeably with Entitlement. A Container is not itself exercisable.

**API References:** `POST /api/containers`, `GET /api/containers`, `PATCH /api/containers/{id}`

**Related Terms:** Entitlement, Lifecycle, Policy

**Domain Translations:**
- insurance policy → **Container**
- loyalty membership account → **Container**
- subscription plan → **Container**

**Drift Classification:** `STABLE`
  *Authority status=Authoritative. protocol_primitive=YES. cross_domain_stability=UNIVERSAL. migration_risk=HIGH but the term itself is stable — the HIGH reflects impact of change, not likelihood. Consistently used as the top-level scope entity. No known drift vectors.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | LOCKED |
| Migration Risk | HIGH |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Protocol v2.0 major revision |

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `Container` |
| Field | `state` |
| OpenAPI Ref | `#/components/schemas/Container` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `POST /api/containers`, `GET /api/containers`, `GET /api/containers/{id}`, `PATCH /api/containers/{id}`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true

**Implementation Notes:** Container.state is the canonical lifecycle field per SYN-NAME-02 (state renamed from status). Container.status is deprecated (x-replaced-by: state). Container.policy_number is marked x-replaced-by: external_ref. Runtime populates both state (canonical) and status (deprecated) in responses via withContainerState() helper. Container.state enum: draft/active/expired/cancelled. SYN-NAME-02 COMPLETE (commit 36b5b465, deploy 2026-05-10).

---

### Entitlement

> An Entitlement is the canonical record of exercisable rights held by an Actor, subject to constraint evaluation before any mutation is permitted.

**Definition:** Entitlements are the core unit of value in MintPass. Each Entitlement carries a lifecycle state, capacity, constraints, and is governed by its Container's policy. All protocol operations (consume, evaluate, enforce) target Entitlements. Entitlements cannot be exercised without a PASS from the Constraint Engine.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `YES` |
| Semantic Owner | `Core Protocol` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `BREAKING` |
| Confidence | `HIGH` |

**Permitted:** Use as the canonical unit representing exercisable rights.

**Prohibited:** Do not use "coverage", "benefit", or "wallet balance" as synonyms in core protocol logic.

**API References:** `POST /api/entitlements`, `GET /api/entitlements/{id}`, `POST /api/entitlements/{id}/consume`

**Related Terms:** Container, State, Capacity, Constraint

**Domain Translations:**
- insurance coverage → **Entitlement**
- loyalty points balance → **Entitlement**
- subscription access → **Entitlement**

**Drift Classification:** `STABLE`
  *Authority status=Authoritative. protocol_primitive=YES. cross_domain_stability=UNIVERSAL. migration_risk=BREAKING but term is stable — BREAKING reflects change impact. Core unit of value. Prohibited synonyms documented. No known drift vectors.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | LOCKED |
| Migration Risk | BREAKING |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Protocol v2.0 major revision |

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `Entitlement` |
| OpenAPI Ref | `#/components/schemas/Entitlement` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `POST /api/entitlements/issue`, `GET /api/entitlements`, `GET /api/entitlements/{id}`, `PATCH /api/entitlements/{id}`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true

**Implementation Notes:** Entitlement schema carries x-authoritative: true per OA-ANNOTATE-01B. Primary unit of value in MintPass. Contains both authoritative fields: (1) lifecycle_state_canonical (CanonicalLifecycleState: PENDING/ISSUED/ACTIVE/CONSUMED/REVOKED, x-state-class: canonical_lifecycle, x-authoritative: true) — protocol-canonical lifecycle state per LIFECYCLE-RESP-01; (2) state (ClaimWorkflowState: 17 lowercase workflow values, x-authoritative: true) — domain-level claim workflow state per STATE-SPLIT-01B. Also carries non-authoritative field entitlement_status (x-authoritative: false, x-semantic-warning). The canonical lifecycle field is lifecycle_state_canonical (protocol truth); state provides workflow context. SYN-NAME-01 finding #1 flags entitlement_status as PSL-001 violation.

---

### Actor

> An Actor is any authenticated principal that can initiate protocol operations, subject to authority evaluation before execution is permitted.

**Definition:** Actors are the identity layer of the protocol. Every mutation, evaluation, or authority check references an Actor. Actors may hold delegated authority from other Actors.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `YES` |
| Semantic Owner | `GOV` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to identify any authenticated principal in the system.

**Prohibited:** Do not conflate with Holder or Beneficiary — an Actor may operate on behalf of others.

**Related Terms:** Authority, Delegation, Holder

**Canonical Mapping** (Confidence: `MEDIUM`)

| Field | Value |
|---|---|
| Schema | `ActorAuthorityBasis` |
| OpenAPI Ref | `#/components/schemas/ActorAuthorityBasis` |
| Source | `OA-ANNOTATE-01B` |

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: false, x-semantic-warning

**Implementation Notes:** ActorAuthorityBasis carries x-authoritative: false and x-semantic-warning per OA-ANNOTATE-01B. This is a CONSISTENCY_WARNING: the dictionary term Actor has authority_status: Authoritative but the closest OpenAPI schema (ActorAuthorityBasis) is marked x-authoritative: false. Resolution: Actor as a protocol entity is authoritative; ActorAuthorityBasis is a non-authoritative metadata projection for external AI agent interpretation (the schema description confirms: 'Non-authoritative metadata'). The authority_basis field (present on EvaluationEnvelope metadata, Authorisation, ConsumeResponse) carries this non-authoritative context.

---

### Tenant

> A Tenant is the top-level organisational boundary that enforces multi-tenant isolation across all protocol entities.

**Definition:** Tenants provide the highest-level isolation boundary. All protocol entities belong to exactly one Tenant. Cross-tenant operations are forbidden by design.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Core Protocol` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use as the isolation boundary for all multi-tenant operations.

**Prohibited:** Do not allow cross-tenant entity references.

**Related Terms:** Entity, Container

---

### Holder

> A Holder is the Actor or entity for whose benefit an Entitlement is issued, who may or may not be the same as the Actor exercising it.

**Definition:** The Holder is the named beneficiary of an Entitlement at issuance time. The Holder may delegate exercise authority to other Actors.

| Field | Value |
|---|---|
| Authority Status | `Non-authoritative Metadata` |
| Normative Status | `RECOMMENDED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Core Protocol` |
| Cross-Domain Stability | `PROFILE-SCOPED` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use to identify the named beneficiary of an Entitlement.

**Prohibited:** Do not use interchangeably with Actor or Beneficiary.

**Related Terms:** Actor, Beneficiary, Entitlement

**Domain Translations:**
- policyholder → **Holder**

**Drift Classification:** `AMBIGUOUS`
  *Authority status=Non-authoritative Metadata. Definition distinguishes Holder from Actor and Beneficiary, but in many domain contexts 'holder' is used as a generic synonym for the account-owning entity. cross_domain_stability=PROFILE-SCOPED indicates domain variance. Risk: domain integrators conflate Holder with Actor.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | STABLE |
| Migration Risk | LOW |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Beneficiary/Holder disambiguation review |

**Canonical Mapping** (Confidence: `LOW`)

| Field | Value |
|---|---|
| Field | `policyholder_name` |
| Source | `direct inspection` |

**Implementation Notes:** AMBIGUOUS drift classification (DICT-02B) — Holder has multiple usages (policyholder in insurance, cardholder in commerce, wallet holder in loyalty). Implementation surfaces: policyholder_name and policyholder_email fields on Container schema (these are themselves QUARANTINED per SYN-NAME-01 policyholder finding). No canonical Holder schema exists. PSL-008: domain holders must map to Actor in protocol context.

---

### Beneficiary

> A Beneficiary is the party who receives the value of an exercised Entitlement, which may differ from the Holder or the executing Actor.

**Definition:** Beneficiaries receive the outcome of an exercise operation. In insurance, this is the claimant; in commerce, the recipient of goods or services.

| Field | Value |
|---|---|
| Authority Status | `Non-authoritative Metadata` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Core Protocol` |
| Cross-Domain Stability | `PROFILE-SCOPED` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use to identify the recipient of exercised value.

**Prohibited:** Do not conflate with Holder — the Beneficiary may be a third party.

**Related Terms:** Holder, Actor, Consume

---

### Issuer

> An Issuer is the Actor or system authorised to create Entitlements under a given Container policy.

**Definition:** Issuers are the creation-authority for Entitlements. Issuance is a mutation subject to the full pipeline.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `RECOMMENDED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Core Protocol` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to identify the entity authorised to create Entitlements.

**Prohibited:** Do not conflate with Actor — not all Actors are Issuers.

**Related Terms:** Actor, Container, Entitlement

---

### Resource

> A Resource is the protocol-addressable subject of an entitlement right — the thing that may be accessed, consumed, or acted upon.

**Definition:** Resources are the target objects that Entitlements grant rights over. A Resource may be a service, a physical item, a digital asset, or an abstract capability.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `RECOMMENDED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Core Protocol` |
| Cross-Domain Stability | `DOMAIN-VARIABLE` |
| Migration Risk | `MEDIUM` |
| Confidence | `MEDIUM` |

**Permitted:** Use to identify the target of an entitlement right.

**Prohibited:** Do not use as a generic term for any API entity.

**Related Terms:** Entitlement, Capacity

---

### Entity

> An Entity is any protocol-addressable domain object that carries identity, state, and is subject to protocol operations.

**Definition:** Entity is the abstract base concept for all protocol objects. Containers, Entitlements, Actors, and other addressable objects are Entities.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Core Protocol` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `HIGH` |
| Confidence | `HIGH` |

**Permitted:** Use as the abstract base for all protocol-addressable objects.

**Prohibited:** Do not use as a synonym for a specific entity type (Container, Entitlement, etc.).

**Related Terms:** Container, Entitlement, Actor

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `Entity` |
| OpenAPI Ref | `#/components/schemas/Entity` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `POST /api/entities`, `GET /api/entities`, `GET /api/entities/{id}`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true

**Implementation Notes:** Entity and EntityCreateRequest carry x-authoritative: true per OA-ANNOTATE-01B. Entities are the actor/party records within the protocol (carriers, holders, providers). Maps to /api/entities/* route group.

---

## Lifecycle & State

### State

> State is the sole authoritative lifecycle position of an entity, determined by the lifecycle state machine — not inferred from derived fields or timestamps.

**Definition:** state is the exclusive lifecycle truth in the MintPass protocol, operating at two levels: (1) Canonical Protocol Level: lifecycle_state_canonical uses CanonicalLifecycleState enum (PENDING, ISSUED, ACTIVE, CONSUMED, REVOKED) — this is the authoritative protocol state per LIFECYCLE-RESP-01. (2) Domain Workflow Level: Entitlement.state uses ClaimWorkflowState enum (17 lowercase values: draft, issued, active, triggered, claim_initiated, evidence_submitted, assessed, approved, part_approved, declined, paid, settled, expired, closed, consumed, disputed, resolved) — this tracks domain-specific workflow progression per STATE-SPLIT-01B. Both fields carry x-authoritative: true. PSL-001 governs: state is protocol truth; status is not. Agents reading Entitlement responses must handle both fields and understand their distinct purposes.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `YES` |
| Semantic Owner | `Lifecycle` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `BREAKING` |
| Confidence | `HIGH` |

**Permitted:** Use as the sole authoritative lifecycle field.

**Prohibited:** Do not use status, timestamps, or derived fields as proxies for state.

**Related Terms:** Status, Lifecycle, Transition

**Notes:** POST-STATE-SPLIT-01B: lifecycle_state_canonical (CanonicalLifecycleState) is the protocol-canonical state; state (ClaimWorkflowState) is the domain workflow state. Both are authoritative at their respective levels.

**Drift Classification:** `STABLE`
  *Authority status=Authoritative. protocol_primitive=YES. PSL-001 explicitly governs. Notes: 'Single most-important semantic distinction in the API. State ≠ Status.' Term is stable — the drift risk exists on STATUS (which maps to AMBIGUOUS), not on State itself.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | LOCKED |
| Migration Risk | BREAKING |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Protocol v2.0 major revision |

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `Entitlement` |
| Field | `state` |
| Enum | `ClaimWorkflowState (primary), CanonicalLifecycleState (protocol-level)` |
| OpenAPI Ref | `#/components/schemas/EntitlementState` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `GET /api/entitlements/{id}`, `POST /api/lifecycle/transition`, `GET /api/lifecycle/history/{entitlementId}`, `GET /api/lifecycle/matrix`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true, x-mtk-surface: core, x-public-contract: true

**Implementation Notes:** Entitlement.state is the canonical claim workflow field per PSL-001 ('State is protocol truth; status is not'). POST-STATE-SPLIT-01B: state now distinguishes between two enum surfaces: (1) ClaimWorkflowState (17 lowercase values: draft, issued, active, triggered, claim_initiated, evidence_submitted, assessed, approved, part_approved, declined, paid, settled, expired, closed, consumed, disputed, resolved) is returned on Entitlement.state for domain-level workflow tracking. (2) CanonicalLifecycleState (5 UPPERCASE values: PENDING, ISSUED, ACTIVE, CONSUMED, REVOKED) is the protocol-canonical lifecycle state returned on Entitlement.lifecycle_state_canonical (LIFECYCLE-RESP-01). Both enums are authoritative but serve different purposes: lifecycle_state_canonical is protocol truth (CEI canonical operations layer), state is domain workflow (consumer-facing entitlement API). Both carry x-authoritative: true per OA-ANNOTATE-01B. Agents reading Entitlement responses must handle both fields.

---

### Status

> Status is a non-authoritative presentation field that may reflect lifecycle, domain, or UI context — it must not drive protocol logic unless explicitly defined as authoritative.

**Definition:** Status fields appear across the API with heterogeneous authority levels. DEPRECATED on core protocol entities: Container.status and Itinerary.status have been renamed to state per SYN-NAME-02 (2026-05-10). RETAINED on operational/admin schemas (ImportJob, WebhookDelivery) where they represent non-authoritative, presentation-only operational state. ALWAYS prefer state or lifecycle_state_canonical for protocol decisions. PSL-001: state is protocol truth; status is not. Entitlement.entitlement_status is x-authoritative: false and x-semantic-warning (presentation-only). SYN-NAME-01 finding #1 flags status occurrences as conflicts with PSL-001.

| Field | Value |
|---|---|
| Authority Status | `Non-authoritative Metadata` |
| Normative Status | `LEGACY` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `varies` |
| Cross-Domain Stability | `DOMAIN-VARIABLE` |
| Migration Risk | `HIGH` |
| Confidence | `HIGH` |

**Permitted:** Use only as a presentation or domain-specific field with explicit authority annotation.

**Prohibited:** Do not use to drive protocol logic. Do not treat as equivalent to state.

**Related Terms:** State, Presentation state

**Notes:** SYN-NAME-02 (2026-05-10) completed status → state renames on core entities. Status DEPRECATED on lifecycle entities, RETAINED on admin/operational schemas only.

**Drift Classification:** `AMBIGUOUS`
  *Multiple meanings across lifecycle (status as proxy for state), enforcement (enforcement status), presentation (entitlement_status), and domain contexts. PSL-001 directly governs this: state is protocol truth, status is not. OA-ANNOTATE-01B x-semantic-warning annotations flag status fields throughout the API surface. SEM-DICT-01 machine_critical=SENSITIVE and normative_status=LEGACY confirm active risk.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | EVOLVING |
| Migration Risk | HIGH |
| Governance Status | UNDER_REVIEW |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Completion of full status field audit across all API surfaces |

**Canonical Mapping** (Confidence: `MEDIUM`)

| Field | Value |
|---|---|
| Field | `status` |
| Source | `SYN-NAME-01` |

**Semantic Extensions (OA-ANNOTATE-01B):** x-semantic-warning, x-authoritative: false (entitlement_status field)

**Implementation Notes:** QUARANTINED TERM — SYN-NAME-01 §5 findings #1, #2, #4, #5, #8. 18 field occurrences across core/admin/domain schemas (Container.status, Authorisation.status, entitlement_status field, and others). All conflict with PSL-001 ('State is protocol truth; status is not'). Status is AMBIGUOUS (DICT-02B drift classification) with drift_risk HIGH. SYN-NAME-01 finding #1: core schemas use 'status' where 'state' is required by PSL-001. SYN-NAME-01 finding #2: Container.status violates NR-18 (state for authoritative lifecycle). SYN-NAME-01 finding #4: Authorisation.status conflicts with PSL-001. SYN-NAME-01 finding #5: additional status occurrences on domain schemas. SYN-NAME-01 finding #8: presentation-only status fields need explicit x-presentation-only annotation. Planned remediation: SYN-NAME-02 (rename to state on core schemas). Pending: STATUS-AUDIT-01. Map current surfaces with MEDIUM confidence noting pending audit. Note: Per SYN-NAME-02 (2026-05-10), core lifecycle schemas (Container, Itinerary) renamed status → state. The canonical_field for lifecycle entities is now "state". "status" is RETAINED for operational/admin schemas (ImportJob, WebhookDelivery, etc.) and is DEPRECATED on core entities.

---

### Lifecycle

> Lifecycle is the defined sequence of states and transitions that an entity may occupy, governed by the protocol state machine.

**Definition:** The lifecycle defines the complete set of valid states and transitions for an entity type at the protocol level. At the canonical level, CanonicalLifecycleState (PENDING → ISSUED → ACTIVE → CONSUMED/REVOKED) defines the protocol state machine per LIFECYCLE-RESP-01. At the domain level, ClaimWorkflowState defines extended workflow tracking (e.g., claim progression through assessment, approval, payment, settlement). Lifecycle enforcement is determined by the /api/lifecycle/matrix endpoint which returns valid transitions for the canonical state. The POST /api/lifecycle/transition endpoint governs canonical state transitions. Entitlement.lifecycle_state_canonical reflects canonical lifecycle truth; Entitlement.state reflects domain workflow progression.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `YES` |
| Semantic Owner | `Lifecycle` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `HIGH` |
| Confidence | `HIGH` |

**Permitted:** Use to describe the state machine governing entity transitions.

**Prohibited:** Do not add ad-hoc states outside the canonical lifecycle.

**Related Terms:** State, Transition, Terminal state

**Notes:** LIFECYCLE-RESP-01: Entitlement responses now include lifecycle_state_canonical (CanonicalLifecycleState) as the authoritative protocol state, alongside state (ClaimWorkflowState) for workflow tracking.

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `Entitlement` |
| Field | `state` |
| Enum | `CanonicalLifecycleState` |
| OpenAPI Ref | `#/components/schemas/Entitlement` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `POST /api/lifecycle/transition`, `GET /api/lifecycle/history/{entitlementId}`, `GET /api/lifecycle/matrix`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true

**Implementation Notes:** Lifecycle is operationalised at the protocol level through Entitlement.lifecycle_state_canonical (CanonicalLifecycleState enum: PENDING, ISSUED, ACTIVE, CONSUMED, REVOKED) and at the domain level through Entitlement.state (ClaimWorkflowState enum) per POST-STATE-SPLIT-01B (LIFECYCLE-RESP-01). The /api/lifecycle/* route group (transition, history, matrix) operates on the canonical lifecycle state. PSL-001 governs: lifecycle_state_canonical (PENDING/ISSUED/ACTIVE/CONSUMED/REVOKED) is protocol truth; claim workflow state is domain-level tracking. The lifecycle/matrix endpoint returns valid transitions for the protocol-canonical state machine.

---

### Transition

> A Transition is a permitted state change on an entity, executed through the mutation pipeline with full lifecycle and authority validation.

**Definition:** Transitions are the edges of the lifecycle state machine. Each transition requires validation through the mutation pipeline.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `RECOMMENDED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Lifecycle` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to describe a permitted state change.

**Prohibited:** Do not bypass the mutation pipeline for transitions.

**Related Terms:** State, Lifecycle, Mutation

---

### Terminal state

> A terminal state is a lifecycle position from which no further transitions are permitted.

**Definition:** Terminal states at the protocol level are those in CanonicalLifecycleState with no outgoing transitions: CONSUMED (exercised and concluded) and REVOKED (administratively terminated). At the domain workflow level, ClaimWorkflowState may report additional terminal states (expired, closed, declined, resolved, disputed) which represent domain-specific endpoints that ultimately map to protocol-canonical terminal states at enforcement boundaries. Once an entity reaches a canonical terminal state (CONSUMED or REVOKED), no further mutations are allowed per PSL-001.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Lifecycle` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to identify states from which no transitions are permitted.

**Prohibited:** Do not attempt mutations on entities in terminal states.

**Related Terms:** Consumed, Revoked, Lifecycle

**Notes:** STATE-SPLIT-01B: Distinguish protocol-canonical terminal states (CONSUMED, REVOKED in CanonicalLifecycleState) from domain-level terminal states (in ClaimWorkflowState).

**Canonical Mapping** (Confidence: `MEDIUM`)

| Field | Value |
|---|---|
| Schema | `EntitlementState` |
| Enum | `CanonicalLifecycleState: CONSUMED, REVOKED` |
| OpenAPI Ref | `#/components/schemas/CanonicalLifecycleState` |
| Source | `direct inspection` |

**Routes:** `GET /api/lifecycle/matrix`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true

**Implementation Notes:** Terminal states are defined within the CanonicalLifecycleState enum (5 values: PENDING, ISSUED, ACTIVE, CONSUMED, REVOKED). Canonical terminal states per protocol: CONSUMED (exercised and concluded), REVOKED (administratively terminated). Both are final states with no valid outgoing transitions. The /api/lifecycle/matrix endpoint returns CanonicalLifecycleState valid transitions; terminal states inferred as states with no outgoing transitions in the matrix. Entitlement.lifecycle_state_canonical reflects canonical terminal state. Entitlement.state (ClaimWorkflowState) may report workflow-level terminal states (consumed, expired, closed, declined, resolved, disputed) which map to protocol-canonical terminal states at enforcement boundaries per SYN-NAME-02 state mapping.

---

### Active

> ACTIVE is the canonical lifecycle state indicating an Entitlement is live and potentially exercisable, subject to CE evaluation.

**Definition:** An ACTIVE Entitlement has been issued and activated. It may be exercised if CE returns PASS.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Lifecycle` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use as a canonical lifecycle state value.

**Prohibited:** Do not add variant spellings or synonyms.

**Related Terms:** State, Issued, Consumed

**Notes:** Must match DB constraint chk_lifecycle_state_canonical.

---

### Issued

> ISSUED is the canonical lifecycle state indicating an Entitlement has been created but not yet activated.

**Definition:** An ISSUED Entitlement exists but is not yet exercisable. Activation transitions it to ACTIVE.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Lifecycle` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use as a canonical lifecycle state value.

**Prohibited:** Do not add variant spellings or synonyms.

**Related Terms:** State, Active, Pending

**Notes:** Must match DB constraint chk_lifecycle_state_canonical.

---

### Consumed

> CONSUMED is the canonical terminal lifecycle state indicating an Entitlement's value has been fully exercised.

**Definition:** A CONSUMED Entitlement has been fully exercised. No further mutations are permitted. This is a terminal state.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Lifecycle` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use as a canonical terminal lifecycle state value.

**Prohibited:** Do not attempt further mutations on CONSUMED entities.

**Related Terms:** State, Terminal state, Consume

**Notes:** Must match DB constraint chk_lifecycle_state_canonical.

---

### Revoked

> REVOKED is the canonical terminal lifecycle state indicating an Entitlement has been administratively cancelled.

**Definition:** A REVOKED Entitlement has been permanently cancelled by an authorised Actor. No further mutations are permitted. This is a terminal state.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Lifecycle` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use as a canonical terminal lifecycle state value.

**Prohibited:** Do not reverse revocation — it is terminal.

**Related Terms:** State, Terminal state, Revocation

**Notes:** Must match DB constraint chk_lifecycle_state_canonical.

---

### Expired

> EXPIRED is a temporal evaluation result, not a stored lifecycle state.

**Definition:** EXPIRED is determined by the CE's temporal dimension (TMP) at evaluation time. It is never stored as a state value. An expired Entitlement receives DENIED from the CE.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `CE/Lifecycle` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use to describe a temporal evaluation outcome.

**Prohibited:** Do not add EXPIRED as a state machine value. EXPIRED = temporal DENIED from CE.

**Related Terms:** State, Dimension, DENIED

**Notes:** Critical: Do not add EXPIRED as a state machine value.

---

### Presentation state

> A presentation state is a derived, non-authoritative view of entity status intended for UI display only.

**Definition:** Presentation states like entitlement_status are computed from the authoritative state (both lifecycle_state_canonical and state) and other context. They must never be used for protocol decisions. These fields carry x-authoritative: false and x-presentation-only: true annotations. AuditStatsResponse, AvailabilitySnapshot, LedgerBalanceResponse, and similar admin-layer responses all carry x-presentation-only: true. Entitlement.entitlement_status (x-authoritative: false, x-semantic-warning) is derived for UI/presentation purposes only — it does not drive protocol behaviour. Always use lifecycle_state_canonical (protocol truth) or state (domain workflow) for decisions.

| Field | Value |
|---|---|
| Authority Status | `Presentation-only` |
| Normative Status | `PROHIBITED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `UI/API Presentation` |
| Cross-Domain Stability | `DOMAIN-VARIABLE` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use only for UI display purposes.

**Prohibited:** Do not use to drive protocol logic or as a proxy for state.

**Related Terms:** State, Status

**Notes:** POST-STATE-SPLIT-01B: lifecycle_state_canonical (CanonicalLifecycleState) is the authoritative protocol state; presentation states remain presentation-only derivations.

**Drift Classification:** `PRESENTATION_ONLY`
  *Authority status = Presentation-only. normative_status = PROHIBITED for protocol logic use. Definition: 'must never drive protocol logic.' PSL-007 (carriers never create protocol truth) governs this. OA-ANNOTATE-01B x-presentation-only annotations on entitlement_status and related fields. High risk: UI fields frequently mistaken for authoritative signals by API consumers.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | LOCKED |
| Migration Risk | LOW |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Addition of new presentation-layer fields to API surface |

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Field | `entitlement_status` |
| Source | `OA-ANNOTATE-01B` |

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: false, x-presentation-only: true, x-semantic-warning

**Implementation Notes:** Presentation state maps to Entitlement.entitlement_status (x-authoritative: false, x-semantic-warning per OA-ANNOTATE-01B) and other x-presentation-only fields. PRESENTATION_ONLY drift classification (DICT-02B) consistent. PSL-001: status is not protocol truth — it is derived for presentation only. AuditStatsResponse, AvailabilitySnapshot, LedgerBalanceResponse, etc. also carry x-presentation-only: true.

---

## Evaluation & Truth

### Evaluation

> Evaluation is the deterministic process by which the Constraint Engine assesses whether an Entitlement is exercisable under current conditions.

**Definition:** Evaluation is the core CE operation. It assesses all 8 dimensions deterministically and returns an Outcome. Evaluation is read-only — it never mutates state.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `YES` |
| Semantic Owner | `CE` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `HIGH` |
| Confidence | `HIGH` |

**Permitted:** Use to describe the CE assessment process.

**Prohibited:** Do not conflate with execution. Evaluation is read-only; execution is mutation.

**API References:** `GET /api/entitlements/{id}/evaluation`

**Related Terms:** Constraint, Outcome, Dimension

**Notes:** Critical distinction: Evaluation is read-only. Execution is mutation. These must never be conflated.

**Drift Classification:** `STABLE`
  *Authority status=Authoritative. protocol_primitive=YES. PSL-002 governs (evaluation is read-only). PSL-003 establishes CE as sole exercisability authority. Notes: 'Critical distinction: Evaluation is read-only. Execution is mutation.' Well-bounded via GET /api/entitlements/{id}/evaluation.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | LOCKED |
| Migration Risk | HIGH |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Protocol v2.0 major revision |

**Canonical Mapping** (Confidence: `MEDIUM`)

| Field | Value |
|---|---|
| Field | `envelope` |
| Source | `direct inspection` |

**Routes:** `GET /api/entitlements/{id}/evaluation`

**Semantic Extensions (OA-ANNOTATE-01B):** x-semantic-warning

**Implementation Notes:** Evaluation is not a named schema in the OpenAPI spec. The evaluation response is returned as an inline shape under GET /api/entitlements/{id}/evaluation, with the canonical evaluation envelope nested under the 'envelope' property. The 'evidence_only: true' field is always present — stored evaluation results are evidence only, not authoritative for enforcement. PSL-002 governs: evaluation is read-only; execution mutates. PSL-003 governs: the Convergence Engine is the sole authority for exercisability. The /api/entitlements/{id}/evaluation path carries x-semantic-warning per OA-ANNOTATE-01B (37 total semantic warning annotations). EvaluationBlockedResponse and EvaluationDeniedResponse are response schemas (x-authoritative: false on their schema definitions but blocking_constraints field carries x-authoritative: true). STABLE drift classification (DICT-02B) is consistent with x-authoritative annotation evidence.

---

### Constraint

> A Constraint is a protocol rule that limits exercisability of an Entitlement, evaluated by the CE across defined dimensions.

**Definition:** Constraints are the individual rules evaluated by the CE. Each constraint belongs to one of the 8 canonical dimensions.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `YES` |
| Semantic Owner | `CE` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `HIGH` |
| Confidence | `HIGH` |

**Permitted:** Use to describe rules that limit exercisability.

**Prohibited:** Do not create constraints outside the canonical dimension framework.

**Related Terms:** Dimension, Evaluation, Blocking constraint

**Drift Classification:** `STABLE`
  *Authority status=Authoritative. protocol_primitive=YES. Well-defined via 8 canonical dimensions. Cross-domain stability=UNIVERSAL.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | LOCKED |
| Migration Risk | HIGH |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Protocol v2.0 major revision |

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `BlockingConstraintItem` |
| Field | `classification` |
| OpenAPI Ref | `#/components/schemas/BlockingConstraintItem` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `GET /api/entitlements/{id}/evaluation`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true

**Implementation Notes:** BlockingConstraintItem carries x-authoritative: true per OA-ANNOTATE-01B. The blocking_constraints field on EvaluationBlockedResponse also carries x-authoritative: true. Constraints are operationalised as 8 canonical constraint dimensions: LC (Lifecycle), TMP (Temporal), ENF (Enforcement), DEP (Dependency), CAP (Capacity), VER (Verification), DEC (Decision), ACCEPTANCE. PSL-010 governs: constraint dimensions have canonical precedence ordering. STABLE drift classification (DICT-02B) consistent.

---

### Dimension

> A Dimension is one of the 8 canonical constraint evaluation categories assessed by the CE.

**Definition:** 8 canonical dimensions: LC → TMP → ENF → DEP → CAP → VER → DEC → ACCEPTANCE. Precedence: INVALID_CONFIGURATION > DENIED > BLOCKED > PASS (immutable).

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `NO` |
| Semantic Owner | `CE` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to describe one of the 8 canonical evaluation categories.

**Prohibited:** Do not add new dimensions without governance review.

**Related Terms:** Evaluation, Constraint, Outcome

**Notes:** 8 canonical dimensions evaluated in fixed order: LC → TMP → ENF → DEP → CAP → VER → DEC → ACCEPTANCE.

**Canonical Mapping** (Confidence: `MEDIUM`)

| Field | Value |
|---|---|
| Field | `dimension_results` |
| Source | `direct inspection` |

**Routes:** `GET /api/entitlements/{id}/evaluation`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true (blocking_constraints)

**Implementation Notes:** Dimension maps to the 8 canonical constraint dimensions operationalised in the evaluation envelope: LC (Lifecycle), TMP (Temporal), ENF (Enforcement), DEP (Dependency), CAP (Capacity), VER (Verification), DEC (Decision), ACCEPTANCE. The dimension_summary array in the evaluation envelope always returns exactly 8 entries in canonical order. Each dimension has applicability (APPLICABLE, NOT_APPLICABLE, MISSING, INVALID), classification (SUCCESS, CONDITIONAL, STRUCTURAL), and definitive flag. PSL-010 governs: constraint dimensions have canonical precedence ordering.

---

### Outcome

> An Outcome is the CE's authoritative verdict on an evaluation request — PASS, BLOCKED, DENIED, or INVALID_CONFIGURATION.

**Definition:** The Outcome is the final result of a CE evaluation. It determines whether an Entitlement may be exercised.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `NO` |
| Semantic Owner | `CE` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use for the CE's authoritative evaluation verdict.

**Prohibited:** Do not use Result or Decision as synonyms for Outcome in CE context.

**Related Terms:** Evaluation, PASS, BLOCKED, DENIED

**Canonical Mapping** (Confidence: `MEDIUM`)

| Field | Value |
|---|---|
| Field | `decision` |
| Source | `direct inspection` |

**Routes:** `GET /api/entitlements/{id}/evaluation`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true (on blocking_constraints field)

**Implementation Notes:** Outcome maps to the 'decision' field within the evaluation envelope (inline response shape, not a named schema). Decision enum values: PASS, CONDITIONAL, STRUCTURAL — these map to CE/usability layer PASS/BLOCKED/DENIED respectively (D-06 vocabulary layering). The 'exercisable' boolean is the direct machine-readable exercisability signal derived from decision. Note: 'outcome' as a bare field name is NOT used in the authoritative evaluation envelope — the field is named 'decision'. SYN-NAME-01 NR-21 flags bare 'result' as prohibited (must be qualified); same caution applies to bare 'outcome' in implementation references.

---

### Result

> Result is a generic term for the output of an operation; prefer Outcome (CE), Decision (authority), or a domain-qualified term where precision matters.

**Definition:** Result is overloaded across CE, API, and domain contexts. Use the more specific term where available.

| Field | Value |
|---|---|
| Authority Status | `Non-authoritative Metadata` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `various` |
| Cross-Domain Stability | `DOMAIN-VARIABLE` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use only where neither Outcome nor Decision applies.

**Prohibited:** Do not use as a synonym for CE Outcome or authority Decision.

**Related Terms:** Outcome, Decision

**Drift Classification:** `AMBIGUOUS`
  *Dictionary: 'Result is overloaded across CE, API, and domain contexts.' Non-authoritative Metadata. normative_status=OPTIONAL. Authority status=Non-authoritative. Prohibited as synonym for CE Outcome. OA-ANNOTATE-01B x-semantic-warning likely covers evaluation_results schema. Competes with Outcome (CE-specific) and Decision (authority-specific).*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | EVOLVING |
| Migration Risk | MEDIUM |
| Governance Status | UNDER_REVIEW |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Outcome/Result/Decision disambiguation pass complete |

---

### Decision

> A Decision is an authority- or policy-level determination, distinct from the CE Outcome (evaluation) and from Execution (mutation).

**Definition:** Decisions are made by authority or governance logic. They are separate from CE evaluation outcomes.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `RECOMMENDED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `GOV/CE` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use for authority or policy determinations.

**Prohibited:** Do not conflate with CE Outcome.

**Related Terms:** Outcome, Authority, Authorisation

**Drift Classification:** `AMBIGUOUS`
  *Authority status=Authoritative, but term competes with Outcome (CE) and Result (generic). Definition distinguishes authority/policy-level determinations from CE outcomes, but common usage treats 'decision' and 'outcome' as synonyms. OA-ANNOTATE-01B x-semantic-warning likely flags this pair.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | STABLE |
| Migration Risk | MEDIUM |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Outcome/Result/Decision disambiguation pass complete |

**Canonical Mapping** (Confidence: `MEDIUM`)

| Field | Value |
|---|---|
| Field | `decision` |
| Source | `direct inspection` |

**Routes:** `GET /api/entitlements/{id}/evaluation`

**Implementation Notes:** Decision maps to the 'decision' field in the evaluation envelope (PASS, CONDITIONAL, STRUCTURAL). Also maps to the DEC constraint dimension in evaluation (judgement/approval state). AMBIGUOUS drift classification (DICT-02B) consistent with dual usage: (1) evaluation outcome decision field, (2) DEC dimension for judgement/approval. No named schema for 'Decision' as a first-class entity. Distinguish from Outcome which is the semantic concept; decision is the field name.

---

### PASS

> PASS is the CE outcome indicating all evaluated dimensions are satisfied and the Entitlement is exercisable under current constraints.

**Definition:** PASS means all dimensions returned satisfactory results. The Entitlement may be exercised.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `YES` |
| Semantic Owner | `CE` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `HIGH` |
| Confidence | `HIGH` |

**Permitted:** Use as the CE outcome indicating exercisability.

**Prohibited:** Do not add synonyms or variant spellings.

**Related Terms:** Outcome, BLOCKED, DENIED, Evaluation

**Drift Classification:** `STABLE`
  *Authority status=Authoritative. protocol_primitive=YES. machine_critical=CRITICAL. canonical CE outcome value. No synonyms permitted.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | LOCKED |
| Migration Risk | HIGH |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Protocol v2.0 major revision |

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `EntitlementState` |
| Enum | `PASS` |
| OpenAPI Ref | `#/components/schemas/EntitlementState` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `GET /api/entitlements/{id}/evaluation`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true

**Implementation Notes:** PASS appears as an enum value in both EntitlementState (lifecycle: distinct from evaluation PASS — not directly equivalent) and the evaluation envelope decision field (PASS = fully exercisable). STABLE drift classification (DICT-02B) consistent. Note: evaluation envelope decision=PASS maps to exercisable=true. This is the terminal positive outcome of Convergence Engine evaluation.

---

### BLOCKED

> BLOCKED is the CE outcome indicating one or more constraints prevent exercise but the condition may be recoverable.

**Definition:** BLOCKED means exercise is currently prevented but the blocking condition may be resolved. Parse blocking_constraints and next_actions to select a recovery path.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `YES` |
| Semantic Owner | `CE` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `HIGH` |
| Confidence | `HIGH` |

**Permitted:** Use as the CE outcome indicating recoverable constraint failure.

**Prohibited:** Do not treat BLOCKED as terminal — it is recoverable.

**Related Terms:** Outcome, PASS, DENIED, Blocking constraint

**Drift Classification:** `STABLE`
  *Authority status=Authoritative. protocol_primitive=YES. PSL-005 governs (BLOCKED is recoverable, DENIED is terminal). Well-bounded. However note: BLOCKED is also used as an enforcement overlay label — this adjacent usage creates minor ambiguity risk.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | LOCKED |
| Migration Risk | HIGH |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Protocol v2.0 major revision |

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Field | `decision` |
| Enum | `CONDITIONAL` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `GET /api/entitlements/{id}/evaluation`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true (EvaluationBlockedResponse)

**Implementation Notes:** BLOCKED maps to decision=CONDITIONAL in the evaluation envelope (D-06 vocabulary layering: CONDITIONAL at external envelope layer = BLOCKED at CE/usability layer). EvaluationBlockedResponse carries x-authoritative: true per OA-ANNOTATE-01B. BLOCKED = reversible constraint that can be lifted. Distinct from DENIED (PSL-005). blocking_type field on EvaluationBlockedResponse carries classification. STABLE drift classification (DICT-02B) consistent.

---

### DENIED

> DENIED is the CE outcome indicating a terminal constraint that cannot be resolved — exercise is permanently not permitted under current conditions.

**Definition:** DENIED means exercise is permanently blocked under current conditions. No recovery path exists. DENIED outcomes do not include blocking_constraints.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `YES` |
| Semantic Owner | `CE` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `HIGH` |
| Confidence | `HIGH` |

**Permitted:** Use as the CE outcome indicating terminal constraint.

**Prohibited:** Do not treat DENIED as recoverable.

**Related Terms:** Outcome, PASS, BLOCKED, Terminal state

**Drift Classification:** `STABLE`
  *Authority status=Authoritative. protocol_primitive=YES. PSL-005 governs. Terminal, non-recoverable. Well-bounded CE outcome.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | LOCKED |
| Migration Risk | HIGH |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Protocol v2.0 major revision |

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Field | `decision` |
| Enum | `STRUCTURAL` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `GET /api/entitlements/{id}/evaluation`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true (EvaluationDeniedResponse)

**Implementation Notes:** DENIED maps to decision=STRUCTURAL in the evaluation envelope (D-06 vocabulary layering: STRUCTURAL at external envelope layer = DENIED at CE/usability layer). EvaluationDeniedResponse carries x-authoritative: true per OA-ANNOTATE-01B. DENIED = terminal constraint that cannot be lifted. Distinct from BLOCKED (PSL-005). STABLE drift classification (DICT-02B) consistent.

---

### Exercisable

> An Entitlement is exercisable when the CE returns PASS for the current evaluation context.

**Definition:** Exercisability is determined solely by the CE. No other mechanism may declare an Entitlement exercisable.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `NO` |
| Semantic Owner | `CE` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use to describe the condition where CE returns PASS.

**Prohibited:** Do not infer exercisability from state, status, or timestamps alone.

**Related Terms:** PASS, Evaluation, Entitlement

**Canonical Mapping** (Confidence: `MEDIUM`)

| Field | Value |
|---|---|
| Field | `exercisable` |
| Source | `direct inspection` |

**Routes:** `GET /api/entitlements/{id}/evaluation`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true (blocking_constraints sub-field)

**Implementation Notes:** Exercisable maps to the 'exercisable' boolean field within the evaluation envelope. Derivation rule (locked): exercisable = (decision === 'PASS'). This field is the canonical machine-readable exercisability signal per PSL-003 (CE is sole authority for exercisability). CG-20B: this field eliminates the need for external agents to interpret CONDITIONAL vs STRUCTURAL vocabulary. The evaluation envelope is an inline schema (not a named EvaluationEnvelope schema — that name does not exist in the current OpenAPI spec). STABLE drift classification (DICT-02B) consistent.

---

### Blocking constraint

> A blocking constraint is an active constraint that prevents exercise and is returned in the CE response to guide agent recovery.

**Definition:** Blocking constraints are returned only on BLOCKED outcomes. Each constraint is recoverable — resolve the constraint and retry.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `NO` |
| Semantic Owner | `CE` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to describe recoverable constraints returned in BLOCKED outcomes.

**Prohibited:** Do not return blocking constraints for DENIED outcomes.

**Related Terms:** BLOCKED, Constraint, Recovery action

**Notes:** Needs explicit "recoverable" framing in API description.

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `BlockingConstraintItem` |
| Field | `classification` |
| OpenAPI Ref | `#/components/schemas/BlockingConstraintItem` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `GET /api/entitlements/{id}/evaluation`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true

**Implementation Notes:** BlockingConstraintItem carries x-authoritative: true per OA-ANNOTATE-01B. The blocking_constraints field on EvaluationBlockedResponse and EvaluationDeniedResponse also carries x-authoritative: true (field-level annotation). These are the definitive constraints that determined a BLOCKED or DENIED outcome.

---

### Definitive

> A definitive dimension result is one that conclusively determines the overall evaluation outcome.

**Definition:** A definitive result from any dimension immediately determines the overall outcome without requiring further dimension evaluation.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `CE` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use to mark dimension results that conclusively determine the outcome.

**Prohibited:** Do not override a definitive result from a higher-precedence dimension.

**Related Terms:** Dimension, Outcome, Evaluation

---

### Synthetic

> A synthetic dimension result is a CE-computed projection not directly tied to a stored constraint record.

**Definition:** Synthetic results are computed by the CE from context rather than stored constraint records. They provide additional evaluation information.

| Field | Value |
|---|---|
| Authority Status | `Non-authoritative Metadata` |
| Normative Status | `RECOMMENDED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `CE` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use to mark CE-computed projections not tied to stored constraints.

**Prohibited:** Do not treat synthetic results as authoritative stored records.

**Related Terms:** Dimension, Evaluation, Definitive

**Drift Classification:** `NOT_FIRST_CLASS`
  *Authority status=Non-authoritative Metadata. 'A synthetic dimension result is a CE-computed projection not directly tied to a stored constraint record.' Describes a result type within CE evaluation but is not a protocol primitive or entity. Risk: integrators elevate synthetic results to authoritative status.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | STABLE |
| Migration Risk | LOW |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | CE v2.0 specification |

---

## Execution & Mutation

### Execute

> Execute as a mutation verb is DEPRECATED — use Consume for the canonical exercise operation.

**Definition:** The /execute endpoint and 'execute' verb are deprecated. The canonical operation is Consume via POST /api/entitlements/{id}/consume.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `LEGACY` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Execution` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `BREAKING` |
| Confidence | `HIGH` |

**Permitted:** Use only for backward compatibility references.

**Prohibited:** Do not use in new code. Use Consume instead.

**API References:** `POST /api/entitlements/{id}/execute`

**Related Terms:** Consume, Mutation

**Notes:** POST /api/entitlements/{id}/execute is deprecated. Canonical route is /consume.

**Drift Classification:** `DEPRECATED`
  *Dictionary explicitly states: 'Execute as a mutation verb is DEPRECATED — use Consume.' normative_status=LEGACY, migration_risk=BREAKING. The /execute endpoint is the deprecated surface. OA-ANNOTATE-01B includes x-replaced-by annotations on execute references.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | DEPRECATED |
| Migration Risk | BREAKING |
| Governance Status | RATIFIED |
| Superseded By | Consume |
| Replacement Term | Consume |
| Deprecated Since | 2026-01-01 |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Removal of /api/entitlements/{id}/execute endpoint |

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Source | `SYN-NAME-01` |

**Routes:** `POST /api/entitlements/{id}/execute (DEPRECATED — x-replaced-by: POST /api/entitlements/{id}/consume)`

**Semantic Extensions (OA-ANNOTATE-01B):** x-semantic-warning

**Implementation Notes:** QUARANTINED TERM — SYN-NAME-01 §5 findings #9, #10, #11, #15. Execute as a verb in paths/fields is classified DEPRECATED/BREAKING. 3 remaining paths use 'execute' as a verb (§5 #9, #10): POST /api/entitlements/{id}/execute (deprecated, x-replaced-by: POST /api/entitlements/{id}/consume, confirmed in live OpenAPI). 1 deprecated schema (§5 #11): RequestExecuteRequest (x-authoritative: false, x-semantic-warning). 2 boolean fields on evaluation responses (§5 #15): EvaluationBlockedResponse.execute and EvaluationDeniedResponse.execute carry semantic warnings. Planned remediations: SYN-NAME-03 (field rename), SYN-NAME-12 (path removal). DEPRECATED drift classification (DICT-02B) is consistent with SYN-NAME-01 quarantine status. Do not use execute as a verb in new implementation surfaces — use consume.

---

### Consume

> Consume is the canonical protocol operation that records an exercise of entitlement value, debiting capacity and creating an immutable ledger event.

**Definition:** Consume is the primary mutation operation. It debits capacity from an Entitlement and records an immutable ledger event. Requires CE PASS before execution.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `YES` |
| Semantic Owner | `Execution` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `HIGH` |
| Confidence | `HIGH` |

**Permitted:** Use as the canonical exercise operation.

**Prohibited:** Do not use Redeem, Execute, or Claim as synonyms in core protocol logic.

**API References:** `POST /api/entitlements/{id}/consume`

**Related Terms:** Entitlement, Capacity, Ledger event, Idempotency

**Domain Translations:**
- redemption → **Consume**
- claim exercise → **Consume**

**Drift Classification:** `STABLE`
  *Authority status=Authoritative. protocol_primitive=YES. canonical verb for exercise operations. Prohibited synonyms documented (Redeem, Execute, Claim). PSL-002 governs mutation boundary. Well-defined canonical route: POST /api/entitlements/{id}/consume.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | LOCKED |
| Migration Risk | HIGH |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Protocol v2.0 major revision |

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `ConsumeRequest` |
| OpenAPI Ref | `#/components/schemas/ConsumeRequest` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `POST /api/entitlements/{id}/consume`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true

**Implementation Notes:** ConsumeRequest and ConsumeResponse both carry x-authoritative: true per OA-ANNOTATE-01B. This is the canonical execution mutation route. Note: POST /api/entitlements/{id}/execute is DEPRECATED (deprecated: true, x-replaced-by: POST /api/entitlements/{id}/consume) per SYN-NAME-01 §5 findings #9, #10. SYN-NAME-03 (field rename) and SYN-NAME-12 (path removal) are planned remediations for the execute deprecation. STABLE drift classification (DICT-02B) is consistent with authoritative annotation. PSL-002: execution (via /consume) mutates; evaluation (via /evaluation) is read-only.

---

### Redeem

> Redeem is a domain-colloquial term for exercise, particularly in commerce contexts — it maps to Consume in the core protocol.

**Definition:** Redeem is used colloquially in commerce and loyalty contexts. In the protocol, redemption maps to the Consume operation.

| Field | Value |
|---|---|
| Authority Status | `Non-authoritative Metadata` |
| Normative Status | `LEGACY` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Execution` |
| Cross-Domain Stability | `DOMAIN-VARIABLE` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use in domain-specific UI/documentation where 'redeem' is the natural term.

**Prohibited:** Do not use in core protocol logic. Map to Consume.

**Related Terms:** Consume, Execute

**Drift Classification:** `DOMAIN_ONLY`
  *Dictionary: 'Redeem is a domain-colloquial term for exercise, particularly in commerce contexts — it maps to Consume in the core protocol.' normative_status=LEGACY. Prohibited in core protocol logic. PSL-008 requires domain language to map to canonical terms before execution.*
  Profiles: commerce, loyalty

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | STABLE |
| Migration Risk | MEDIUM |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Commerce profile formalisation |

---

### Mutation

> A Mutation is any protocol operation that changes the state or ledger record of a protocol entity.

**Definition:** Mutations are state-changing operations subject to the full mutation pipeline (lifecycle validation, authority checks, CE evaluation).

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Execution` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to describe any state-changing operation.

**Prohibited:** Do not bypass the mutation pipeline for any state change.

**Related Terms:** Consume, Transition, Ledger event

**Canonical Mapping** (Confidence: `MEDIUM`)

| Field | Value |
|---|---|
| Schema | `ConsumeRequest` |
| OpenAPI Ref | `#/components/schemas/ConsumeRequest` |
| Source | `direct inspection` |

**Routes:** `POST /api/entitlements/{id}/consume`, `POST /api/lifecycle/transition`, `POST /api/authorisations`, `POST /api/enforcement/{entity_type}/{entity_id}/revoke`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true

**Implementation Notes:** Mutation as a concept maps to all authoritative write operations that change protocol state. The canonical mutation surface is POST /api/entitlements/{id}/consume (ConsumeRequest, x-authoritative: true). Lifecycle transitions (POST /api/lifecycle/transition), authorisation creation, and enforcement operations are all protocol mutations. PSL-002 governs: evaluation is read-only; execution (mutation) mutates.

---

### Idempotency

> Idempotency is the protocol guarantee that a mutation operation with the same key produces the same result if repeated.

**Definition:** Critical mutations require an idempotency_key. The protocol guarantees that repeating a mutation with the same key returns the stored result without re-executing.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Execution` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to describe the replay-safety guarantee for mutations.

**Prohibited:** Do not allow mutations without idempotency keys on critical operations.

**API References:** `POST /api/entitlements/{id}/consume`, `POST /api/entitlements/{id}/execute`, `POST /api/authorisations`

**Related Terms:** Mutation, Idempotency replay, Consume

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `ConsumeRequest` |
| Field | `idempotency_key` |
| OpenAPI Ref | `#/components/schemas/ConsumeRequest` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `POST /api/entitlements/{id}/consume`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true

**Implementation Notes:** Idempotency maps to the idempotency_key field on ConsumeRequest (x-authoritative: true schema per OA-ANNOTATE-01B). The IdempotencyReplayDetails schema also carries x-authoritative: true, representing the replay metadata returned when an idempotency key matches a prior execution.

---

### Ledger event

> A Ledger event is an immutable record of a completed mutation, forming the canonical audit trail.

**Definition:** Every completed mutation produces a ledger event. Ledger events are immutable and form the canonical audit trail for the protocol.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Execution/Ledger` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to describe immutable records of completed mutations.

**Prohibited:** Do not modify or delete ledger events.

**Related Terms:** Mutation, Consume, Execution receipt

---

### Capacity

> Capacity is the quantified limit on exercisable value within an Entitlement, evaluated by the CE and debited by consume operations.

**Definition:** Capacity tracks the remaining exercisable value of an Entitlement. The CAP dimension evaluates whether sufficient capacity exists.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `CE/Execution` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to describe the quantified limit on exercisable value.

**Prohibited:** Do not use 'balance' as a synonym in core protocol logic.

**Related Terms:** Entitlement, Consume, Quantity

**Domain Translations:**
- balance → **Capacity**
- remaining units → **Capacity**

---

### Quantity

> Quantity is the amount of entitlement value requested in a consume operation.

**Definition:** Quantity specifies how much capacity to debit in a single consume operation.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Execution/CE` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to specify the amount requested in a consume operation.

**Prohibited:** Do not use 'amount' as a synonym when referring to unit counts.

**Related Terms:** Capacity, Consume

---

### Idempotency replay

> Idempotency replay is the protocol behaviour of returning the stored result of a prior mutation when the same idempotency key is received.

**Definition:** When a mutation is replayed with a previously-used idempotency key, the stored result is returned without re-executing the mutation.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Execution` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use to describe the replay behaviour for idempotent operations.

**Prohibited:** Do not re-execute mutations on replay — return the stored result.

**Related Terms:** Idempotency, Mutation

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `IdempotencyReplayDetails` |
| OpenAPI Ref | `#/components/schemas/IdempotencyReplayDetails` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `POST /api/entitlements/{id}/consume`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true

**Implementation Notes:** IdempotencyReplayDetails carries x-authoritative: true per OA-ANNOTATE-01B. Returned when a POST /api/entitlements/{id}/consume request uses an idempotency_key that matches a prior execution — the replay details are returned instead of executing again.

---

### Dry run

> A dry run is a non-mutating evaluation pass that simulates the outcome of an operation without committing any changes.

**Definition:** Dry runs allow agents to preview the result of an operation without actually executing it. Useful for validation and planning.

| Field | Value |
|---|---|
| Authority Status | `Non-authoritative Metadata` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Execution/Sandbox` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use to describe non-mutating simulation of operations.

**Prohibited:** Do not commit changes during a dry run.

**Related Terms:** Evaluation, Sandbox

**Drift Classification:** `AMBIGUOUS`
  *Authority status=Non-authoritative Metadata. Concept exists (non-mutating simulation) but is colloquial and may be confused with Evaluation (which is read-only by definition). Risk: agents treat Evaluation as equivalent to dry run, not understanding that standard evaluation is already non-mutating.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | EVOLVING |
| Migration Risk | LOW |
| Governance Status | PROPOSED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Sandbox v2.0 specification |

**Canonical Mapping** (Confidence: `LOW`)

| Field | Value |
|---|---|
| Field | `mode` |
| Source | `direct inspection` |

**Routes:** `POST /api/entitlements/{id}/consume`

**Implementation Notes:** AMBIGUOUS drift classification (DICT-02B). 'Dry run' maps to the 'mode' field on ConsumeRequest, which may carry a dry-run or simulation mode value. However, the ConsumeRequest 'mode' field is not the canonical term name. No schema named 'DryRun' exists. The evaluation endpoint (GET /api/entitlements/{id}/evaluation) is the authoritative non-mutating surface — dry run should be mapped to evaluation rather than a special mode on consume.

---

### Execution receipt

> An execution receipt is the structured response confirming a completed mutation, including ledger reference and outcome.

**Definition:** Execution receipts provide the canonical confirmation of a completed mutation, including references to the ledger event and outcome.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Execution` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to describe the structured response from a completed mutation.

**Prohibited:** Do not use as a synonym for Ledger event — the receipt is the response, the event is the record.

**Related Terms:** Ledger event, Mutation, Consume

---

### Reservation

> A Reservation is a tentative capacity hold that has not yet been committed — not currently a first-class protocol concept.

**Definition:** Reservation is not currently implemented as a first-class protocol entity. Do not treat availability snapshots as reservation confirmations.

| Field | Value |
|---|---|
| Authority Status | `Non-authoritative Metadata` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Execution` |
| Cross-Domain Stability | `DOMAIN-VARIABLE` |
| Migration Risk | `LOW` |
| Confidence | `MEDIUM` |

**Permitted:** Use only if reservation semantics are explicitly implemented.

**Prohibited:** Do not treat availability snapshots as reservation confirmations.

**Related Terms:** Hold, Capacity

**Notes:** Neither Reservation nor Hold is currently a first-class protocol concept.

**Drift Classification:** `NOT_FIRST_CLASS`
  *Dictionary: 'A Reservation is a tentative capacity hold — not currently a first-class protocol concept.' protocol_primitive=NO. Notes: 'Neither Reservation nor Hold is currently a first-class protocol concept.' Risk: integrators build reservation semantics assuming protocol support that does not exist.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | EXPERIMENTAL |
| Migration Risk | MEDIUM |
| Governance Status | PROPOSED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Governance review for first-class Reservation primitive proposal |

**Canonical Mapping** (Confidence: `MEDIUM`)

| Field | Value |
|---|---|
| Schema | `ReserveResponse` |
| OpenAPI Ref | `#/components/schemas/ReserveResponse` |
| Source | `OA-ANNOTATE-01B` |

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: false

**Implementation Notes:** NOT_FIRST_CLASS drift classification (DICT-02B). ReserveResponse carries x-authoritative: false per OA-ANNOTATE-01B. ReleaseReserveResponse also carries x-authoritative: false and x-semantic-warning. Reservation is not a first-class protocol primitive — it is a capacity management operation for specific commerce scenarios.

---

### Hold

> A Hold is a temporary capacity lock — not currently a first-class protocol concept.

**Definition:** Hold is not currently implemented as a first-class protocol entity. It represents a theoretical temporary lock on capacity.

| Field | Value |
|---|---|
| Authority Status | `Non-authoritative Metadata` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Execution` |
| Cross-Domain Stability | `DOMAIN-VARIABLE` |
| Migration Risk | `LOW` |
| Confidence | `MEDIUM` |

**Permitted:** Use only if hold semantics are explicitly implemented.

**Prohibited:** Do not assume hold semantics exist — they are not implemented.

**Related Terms:** Reservation, Capacity

**Notes:** Neither Reservation nor Hold is currently a first-class protocol concept.

**Drift Classification:** `NOT_FIRST_CLASS`
  *Dictionary: 'A Hold is a temporary capacity lock — not currently a first-class protocol concept.' protocol_primitive=NO. Notes: 'Neither Reservation nor Hold is currently a first-class protocol concept.' Shares NOT_FIRST_CLASS status with Reservation — both describe unimplemented capacity-locking concepts.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | EXPERIMENTAL |
| Migration Risk | LOW |
| Governance Status | PROPOSED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Governance review for first-class Hold primitive proposal |

---

## Authority & Governance

### Authorisation

> Authorisation is a protocol decision record that grants approval for a specific operation before it may be executed.

**Definition:** Authorisations are explicit approval gates. Certain operations require an authorisation record before execution is permitted.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `YES` |
| Semantic Owner | `GOV` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to describe explicit approval gates for operations.

**Prohibited:** Do not conflate with Authority or Authentication.

**API References:** `POST /api/authorisations`

**Related Terms:** Authority, Decision, Actor

**Notes:** Distinction: Authorisation ≠ Authority ≠ Authentication.

**Drift Classification:** `STABLE`
  *Authority status=Authoritative. protocol_primitive=YES. Distinct from Authority (power) and Authentication (identity). Well-bounded via POST /api/authorisations.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | LOCKED |
| Migration Risk | MEDIUM |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Protocol v2.0 major revision |

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `Authorisation` |
| OpenAPI Ref | `#/components/schemas/Authorisation` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `POST /api/authorisations`, `GET /api/authorisations`, `GET /api/authorisations/{id}`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true, x-semantic-warning

**Implementation Notes:** Authorisation schema carries x-authoritative: true AND x-semantic-warning per OA-ANNOTATE-01B. The x-semantic-warning indicates that Authorisation.status (PSL-001 conflict) exists on this schema. This is a SYN-NAME-01 surface violation (finding #5: status on Authorisation schema). SYN-NAME-02 (rename to state) is planned remediation. Fields: authorised_amount, authority_basis, created_at, entitlement_id, id, status. AuthorisationErrorResponse also carries x-authoritative: true and x-semantic-warning. AuthorisationCreateRequest carries x-authoritative: true. STABLE drift classification (DICT-02B) is consistent with authoritative intent despite warning annotation.

---

### Authority

> Authority is an Actor's protocol-verified power to initiate a specific operation on a specific entity.

**Definition:** Authority is the composite of roles, delegation grants, and elevation status that determines what operations an Actor may perform.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `YES` |
| Semantic Owner | `GOV` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `HIGH` |
| Confidence | `HIGH` |

**Permitted:** Use to describe an Actor's verified power to perform operations.

**Prohibited:** Do not conflate with Authorisation (decision record) or Permission (broader capability).

**Related Terms:** Authorisation, Actor authority, Delegation

**Drift Classification:** `STABLE`
  *Authority status=Authoritative. protocol_primitive=YES. Noted distinction from Authorisation (decision record) and Permission (broader capability). Stable within protocol context though common-language 'authority' is broad.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | LOCKED |
| Migration Risk | HIGH |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Protocol v2.0 major revision |

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `AuthorityRequiredErrorResponse` |
| OpenAPI Ref | `#/components/schemas/AuthorityRequiredErrorResponse` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `POST /api/authorisations`, `POST /api/entitlements/{id}/consume`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true

**Implementation Notes:** Authority as a protocol concept maps to AuthorityRequiredErrorResponse (x-authoritative: true per OA-ANNOTATE-01B) and the authority_basis field present on ConsumeResponse and Authorisation. The ActorAuthorityBasis schema carries x-authoritative: false and x-semantic-warning (non-authoritative metadata for AI agent interpretation). STABLE drift classification (DICT-02B) consistent. PSL-005 governs: BLOCKED and DENIED are distinct invariants requiring different agent recovery paths.

---

### Authority basis

> Authority basis is the recorded source of an Actor's authority for a given operation.

**Definition:** The authority basis documents why an Actor has the power to perform a specific operation (e.g., role assignment, delegation grant, elevation).

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `NO` |
| Semantic Owner | `GOV` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to record the source of authority for audit purposes.

**Prohibited:** Do not allow operations without a recorded authority basis.

**Related Terms:** Authority, Actor authority

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `ActorAuthorityBasis` |
| Field | `authority_type` |
| OpenAPI Ref | `#/components/schemas/ActorAuthorityBasis` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `POST /api/entitlements/{id}/consume`, `POST /api/authorisations`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: false, x-semantic-warning

**Implementation Notes:** ActorAuthorityBasis carries x-authoritative: false and x-semantic-warning per OA-ANNOTATE-01B. The authority_basis field appears on ConsumeResponse, Authorisation, and the evaluation envelope metadata. This is non-authoritative metadata for external agent interpretation only — it identifies who acted and under what authority. Not a protocol decision surface.

---

### Actor authority

> Actor authority is the composite of an Actor's roles, delegation grants, and elevation status that determines what operations they may perform.

**Definition:** Actor authority encompasses all sources of power for a specific Actor, evaluated at operation time.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `NO` |
| Semantic Owner | `GOV` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to describe the full authority profile of an Actor.

**Prohibited:** Do not cache authority — evaluate at operation time.

**Related Terms:** Authority, Authority basis, Delegation

**Canonical Mapping** (Confidence: `MEDIUM`)

| Field | Value |
|---|---|
| Schema | `ActorAuthorityBasis` |
| Field | `authority_type` |
| OpenAPI Ref | `#/components/schemas/ActorAuthorityBasis` |
| Source | `OA-ANNOTATE-01B` |

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: false, x-semantic-warning

**Implementation Notes:** Actor authority maps to the same surface as Authority basis (ActorAuthorityBasis, x-authoritative: false). Non-authoritative metadata for AI agent interpretation. PSL-007 governs: carriers never create protocol truth — carrier authority claims must be mapped through the protocol's authority evaluation before any protocol decision.

---

### Delegation

> Delegation is the protocol mechanism by which a principal Actor grants another Actor authority to perform specific operations on their behalf.

**Definition:** Delegation creates a grant record that extends authority from one Actor to another, scoped to specific operations and entities.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `YES` |
| Semantic Owner | `GOV/BDE` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `HIGH` |
| Confidence | `HIGH` |

**Permitted:** Use to describe authority grants between Actors.

**Prohibited:** Do not allow unbounded delegation — always scope to operations and entities.

**Related Terms:** Authority, Actor, Authorisation

**Drift Classification:** `STABLE`
  *Authority status=Authoritative. protocol_primitive=YES. Well-defined via delegation grant mechanism. Cross-domain stability=UNIVERSAL.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | LOCKED |
| Migration Risk | HIGH |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Protocol v2.0 major revision |

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `Delegation` |
| OpenAPI Ref | `#/components/schemas/Delegation` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `POST /api/delegations`, `GET /api/delegations`, `GET /api/delegations/{id}`, `POST /api/delegations/{id}/revoke`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true

**Implementation Notes:** Delegation schema carries x-authoritative: true per OA-ANNOTATE-01B. DelegationCreateRequest, DelegationRevokeRequest, DelegationRevokeResponse, DelegationCheckResponse, and DelegationLogActionRequest/Response all carry x-authoritative: true. Fields: active, created_at, delegate_id, delegator_id, id, scope. STABLE drift classification (DICT-02B) consistent.

---

### Permission

> Permission is a broader capability grant, distinct from the operation-specific Authority verified by the protocol.

**Definition:** Permission is a general capability concept. Authority is the protocol-specific, operation-verified subset of permission.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `RECOMMENDED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `GOV` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use for broader capability grants.

**Prohibited:** Do not use as a synonym for Authority — Authority is operation-specific.

**Related Terms:** Authority, Scope

---

### Scope

> Scope is the API access boundary that limits what resources and operations a credential may access.

**Definition:** Scope defines the boundaries of API access for a given credential or token.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `RECOMMENDED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `GOV` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to define API access boundaries.

**Prohibited:** Do not conflate with Authority — Scope is access boundary, Authority is operation power.

**Related Terms:** Permission, Authority

---

### Consent

> Consent is a profile-level record of agreement, distinct from the ACCEPTANCE dimension which enforces protocol-level terms.

**Definition:** Consent records explicit agreement at the profile level. It is distinct from the ACCEPTANCE CE dimension which enforces protocol-level terms acceptance.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `GOV` |
| Cross-Domain Stability | `PROFILE-SCOPED` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use for profile-level agreement records.

**Prohibited:** Do not conflate with the ACCEPTANCE CE dimension.

**Related Terms:** Acceptance, Authority

---

### Acceptance

> Acceptance is the 8th canonical CE dimension, evaluating whether required terms or conditions have been accepted before exercise.

**Definition:** The ACCEPTANCE dimension is the newest addition to the CE. It evaluates whether required terms, conditions, or agreements have been accepted before exercise is permitted.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `GOV/CE` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use as the 8th canonical CE dimension.

**Prohibited:** Do not conflate with Consent — Acceptance is a CE dimension, Consent is a profile record.

**Related Terms:** Consent, Dimension, Evaluation

---

### Policy

> Policy is an ambiguous term — qualify as "Container policy" (protocol) or "insurance policy" (domain profile) always.

**Definition:** Policy has two distinct meanings: Container governance rules (core protocol) and insurance policy documents (domain profile). Always qualify which meaning is intended.

| Field | Value |
|---|---|
| Authority Status | `Non-authoritative Metadata` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `varies` |
| Cross-Domain Stability | `DOMAIN-VARIABLE` |
| Migration Risk | `HIGH` |
| Confidence | `HIGH` |

**Permitted:** Use only with explicit qualification: 'Container policy' or 'insurance policy'.

**Prohibited:** Do not use unqualified 'policy' — it is ambiguous.

**Related Terms:** Container, Rule

**Drift Classification:** `AMBIGUOUS`
  *Dictionary: 'Policy is an ambiguous term — qualify as Container policy (protocol) or insurance policy (domain profile) always.' Two semantically distinct meanings that collide in insurance domain integrations. OA-ANNOTATE-01A x-semantic-warning coverage. Open question: 'Requires disambiguation decision before OA-ANNOTATE-01B.'*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | EVOLVING |
| Migration Risk | HIGH |
| Governance Status | UNDER_REVIEW |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Insurance profile v1.0 formalisation |

---

### Rule

> A Rule is a specific governance or constraint condition within a policy that governs entity behaviour.

**Definition:** Rules are the individual conditions within a policy that govern entity behaviour and constraint evaluation.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `RECOMMENDED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `GOV` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to describe individual governance conditions.

**Prohibited:** Do not conflate with Constraint — Rules are governance-level, Constraints are CE-level.

**Related Terms:** Policy, Constraint

---

### Jurisdiction

> Jurisdiction is the legal or regulatory context that may impose additional constraints on protocol operations.

**Definition:** Jurisdiction captures the legal/regulatory context that may affect how protocol operations are constrained.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `GOV` |
| Cross-Domain Stability | `DOMAIN-VARIABLE` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use to capture legal/regulatory context.

**Prohibited:** Do not use as a general-purpose location field.

**Related Terms:** Rule, Policy

---

### Origin basis

> Origin basis records the source or provenance of a governance decision or authority grant.

**Definition:** Origin basis tracks where a decision or authority grant came from — useful for audit and dispute resolution.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `RECOMMENDED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `GOV` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use to record decision provenance.

**Related Terms:** Authority basis, Decision

---

### Dispute

> A Dispute is a formal challenge to a protocol decision or outcome, subject to the contestation process.

**Definition:** Disputes are formal challenges that enter the contestation pipeline for resolution.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `GOV` |
| Cross-Domain Stability | `DOMAIN-VARIABLE` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use to describe formal challenges to decisions.

**Prohibited:** Do not resolve disputes outside the contestation pipeline.

**Related Terms:** Contestation, Decision

---

### Contestation

> A Contestation is the structured process for resolving disputes against protocol decisions or outcomes.

**Definition:** Contestations provide a formal resolution mechanism for disputes. They follow a defined lifecycle and may result in decision reversal or confirmation.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `GOV` |
| Cross-Domain Stability | `DOMAIN-VARIABLE` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use to describe the formal dispute resolution process.

**Prohibited:** Do not bypass the contestation pipeline for dispute resolution.

**Related Terms:** Dispute, Decision

---

## Enforcement & Guardian

### Enforcement

> Enforcement is the protocol mechanism that applies administrative overlays (freeze, suspend, restrict) to entities, blocking exercise independently of CE evaluation.

**Definition:** Enforcement applies administrative restrictions to entities. These overlays cause BLOCKED in the CE ENF dimension independently of other constraint evaluation.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `YES` |
| Semantic Owner | `Enforcement` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `HIGH` |
| Confidence | `HIGH` |

**Permitted:** Use to describe administrative overlays on entities.

**Prohibited:** Do not conflate with Guardian — Enforcement is entity overlays, Guardian is invariant protection.

**Related Terms:** Enforcement overlay, Guardian, Enforcement block

**Drift Classification:** `STABLE`
  *Authority status=Authoritative. protocol_primitive=YES. Clearly separated from Guardian. ENF dimension well-defined. Overlays are distinguished from invariants.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | LOCKED |
| Migration Risk | HIGH |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Protocol v2.0 major revision |

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `EnforcementBlockedResponse` |
| OpenAPI Ref | `#/components/schemas/EnforcementBlockedResponse` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `POST /api/enforcement/{entity_type}/{entity_id}/freeze`, `POST /api/enforcement/{entity_type}/{entity_id}/hold`, `POST /api/enforcement/{entity_type}/{entity_id}/lift-restriction`, `POST /api/enforcement/{entity_type}/{entity_id}/release-hold`, `POST /api/enforcement/{entity_type}/{entity_id}/restore`, `POST /api/enforcement/{entity_type}/{entity_id}/restrict`, `POST /api/enforcement/{entity_type}/{entity_id}/revoke`, `GET /api/enforcement/{entity_type}/{entity_id}/state`, `POST /api/enforcement/{entity_type}/{entity_id}/suspend`, `POST /api/enforcement/{entity_type}/{entity_id}/thaw`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true, x-semantic-warning

**Implementation Notes:** EnforcementBlockedResponse carries x-authoritative: true AND x-semantic-warning per OA-ANNOTATE-01B. The x-semantic-warning is consistent with DICT-02B STABLE drift classification (no drift issue — warning relates to enforcement_state vocabulary). The /api/enforcement/* route group (10 routes) covers freeze, hold, restrict, revoke, suspend, restore, release-hold, thaw, lift-restriction, and state read. STABLE drift classification (DICT-02B) consistent with authoritative implementation surface. Enforcement overlays are liftable (PSL-006).

---

### Enforcement overlay

> An enforcement overlay is an active administrative restriction on an entity that causes BLOCKED in the CE ENF dimension.

**Definition:** Enforcement overlays are admin-applied per-entity restrictions. They can be lifted (unlike Guardian blocks which are hard-coded correctness rules).

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Enforcement` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to describe admin-applied entity restrictions.

**Prohibited:** Do not conflate with runtime invariants — overlays are admin-applied and liftable.

**Related Terms:** Enforcement, Enforcement block, Suspension

**Notes:** Enforcement overlays are admin-applied per-entity (can be lifted). Runtime invariants are hard-coded correctness rules (cannot be lifted).

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `EnforcementBlockedResponse` |
| OpenAPI Ref | `#/components/schemas/EnforcementBlockedResponse` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `POST /api/enforcement/{entity_type}/{entity_id}/freeze`, `POST /api/enforcement/{entity_type}/{entity_id}/hold`, `POST /api/enforcement/{entity_type}/{entity_id}/restrict`, `POST /api/enforcement/{entity_type}/{entity_id}/suspend`, `POST /api/enforcement/{entity_type}/{entity_id}/revoke`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true, x-semantic-warning

**Implementation Notes:** Enforcement overlays are the active enforcement actions applied to entities (freeze, hold, restrict, suspend, revoke). These are returned in EnforcementBlockedResponse (x-authoritative: true, x-semantic-warning per OA-ANNOTATE-01B). PSL-006: overlays are liftable except REVOCATION which is terminal. The enforcement/state endpoint returns current overlay state.

---

### Guardian

> Guardian is the invariant-enforcement layer that protects protocol correctness by blocking mutations that would violate system invariants, regardless of CE outcome.

**Definition:** Guardian is the hard correctness layer. It blocks mutations that would violate protocol invariants, regardless of what the CE says. Guardian blocks are non-configurable and non-bypassable.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `YES` |
| Semantic Owner | `Guardian` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `HIGH` |
| Confidence | `HIGH` |

**Permitted:** Use to describe the invariant-enforcement layer.

**Prohibited:** Do not conflate with Enforcement — Guardian is invariant correctness, Enforcement is entity overlays.

**Related Terms:** Guardian block, Invariant, Enforcement

**Notes:** Critical distinction: Guardian ≠ Enforcement. Guardian = invariant correctness. Enforcement = entity-level overlays.

**Drift Classification:** `STABLE`
  *Authority status=Authoritative. protocol_primitive=YES. PSL-004 governs. Notes: 'Critical distinction: Guardian ≠ Enforcement.' Well-bounded concept with no domain colloquial overlap. Enforcement is clearly separated as a distinct term.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | LOCKED |
| Migration Risk | HIGH |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Protocol v2.0 major revision |

**Canonical Mapping** (Confidence: `MEDIUM`)

| Field | Value |
|---|---|
| Schema | `GuardianBlockedErrorResponse` |
| OpenAPI Ref | `#/components/schemas/GuardianBlockedErrorResponse` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `POST /api/entitlements/{id}/consume`, `POST /api/authorisations`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true (on GuardianBlockedErrorResponse), x-semantic-warning

**Implementation Notes:** Guardian is not a resource schema — it is a protocol enforcement gating mechanism. The implementation surface is the GuardianBlockedErrorResponse schema (error response when Guardian blocks a mutation), which carries x-authoritative: true per OA-ANNOTATE-01B. GuardianBlockedErrorResponse fields: detail, error. PSL-004 governs: Guardian enforces invariants independently of CE outcome. The Guardian is independent of the Convergence Engine — it can block even when CE returns PASS. STABLE drift classification (DICT-02B) consistent.

---

### Guardian block

> A Guardian block is a mutation rejection issued by Guardian because the requested operation would violate a protocol invariant.

**Definition:** Guardian blocks are hard rejections that cannot be overridden. They protect protocol correctness.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Guardian` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to describe invariant-violation rejections.

**Prohibited:** Do not attempt to override or bypass Guardian blocks.

**Related Terms:** Guardian, Invariant, Protocol violation

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `GuardianBlockedErrorResponse` |
| OpenAPI Ref | `#/components/schemas/GuardianBlockedErrorResponse` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `POST /api/entitlements/{id}/consume`, `POST /api/authorisations`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true, x-semantic-warning

**Implementation Notes:** GuardianBlockedErrorResponse carries x-authoritative: true AND x-semantic-warning per OA-ANNOTATE-01B. Fields: detail, error. Guardian block is returned when the protocol Guardian (invariant enforcement layer) blocks a mutation despite CE outcome. The x-semantic-warning is consistent with DICT-02B STABLE drift classification.

---

### Enforcement block

> An enforcement block is a BLOCKED outcome from the ENF dimension caused by an active enforcement overlay on the entity.

**Definition:** Enforcement blocks are recoverable — they can be lifted by removing the enforcement overlay.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Enforcement` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to describe BLOCKED outcomes from the ENF dimension.

**Prohibited:** Do not conflate with Guardian block — enforcement blocks are recoverable.

**Related Terms:** Enforcement overlay, BLOCKED, Guardian block

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `EnforcementBlockedResponse` |
| Field | `blocking_action_type` |
| OpenAPI Ref | `#/components/schemas/EnforcementBlockedResponse` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `GET /api/entitlements/{id}/evaluation`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true

**Implementation Notes:** Enforcement block maps to the ENF constraint dimension in evaluation. When enforcement overlays are active, the ENF dimension returns BLOCKED or DENIED. EnforcementBlockedResponse (x-authoritative: true) contains blocking_action_id, blocking_action_type, blocking_reason, blocking_scope. This is returned as an error response when enforcement prevents execution.

---

### Suspension

> Suspension is an enforcement overlay that temporarily prevents exercise while the overlay is active.

**Definition:** Suspension is a recoverable enforcement action. The entity can be unsuspended to restore exercisability.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Enforcement` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to describe temporary enforcement overlays.

**Prohibited:** Do not treat suspension as a lifecycle state — it is an overlay.

**Related Terms:** Enforcement overlay, Restriction

**Notes:** SUSPENDED is an enforcement overlay, not a lifecycle state value.

---

### Restriction

> A Restriction is an enforcement overlay that limits specific operations on an entity without fully suspending it.

**Definition:** Restrictions are partial enforcement overlays that limit certain operations while leaving others available.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `RECOMMENDED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Enforcement` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to describe partial enforcement overlays.

**Prohibited:** Do not conflate with full suspension.

**Related Terms:** Enforcement overlay, Suspension

---

### Revocation

> Revocation is the enforcement action that permanently cancels an Entitlement, transitioning it to the REVOKED terminal state.

**Definition:** Revocation is a terminal enforcement action. Once revoked, an Entitlement cannot be restored.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Enforcement/Lifecycle` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to describe permanent cancellation of Entitlements.

**Prohibited:** Do not reverse revocation — it is terminal.

**Related Terms:** Revoked, Enforcement, Terminal state

**Canonical Mapping** (Confidence: `MEDIUM`)

| Field | Value |
|---|---|
| Schema | `EnforcementBlockedResponse` |
| Field | `blocking_action_type` |
| OpenAPI Ref | `#/components/schemas/EnforcementBlockedResponse` |
| Source | `direct inspection` |

**Routes:** `POST /api/enforcement/{entity_type}/{entity_id}/revoke`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true

**Implementation Notes:** Revocation maps to POST /api/enforcement/{entity_type}/{entity_id}/revoke. This is a terminal enforcement action (cannot be lifted per PSL-006). The blocking_action_type field on EnforcementBlockedResponse identifies REVOCATION as the blocking action type.

---

### Dependency block

> A dependency block is a BLOCKED outcome from the DEP dimension caused by an unsatisfied prerequisite entity or operation.

**Definition:** Dependency blocks occur when a required prerequisite entity or operation has not been satisfied.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `NO` |
| Semantic Owner | `CE` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to describe BLOCKED outcomes from the DEP dimension.

**Prohibited:** Do not conflate with enforcement blocks — dependency blocks are CE-evaluated.

**Related Terms:** BLOCKED, Dimension, Constraint

**Notes:** Evidence = missing Actor-provided input. Dependency = missing upstream protocol state.

**Canonical Mapping** (Confidence: `MEDIUM`)

| Field | Value |
|---|---|
| Field | `dimension_results` |
| Source | `direct inspection` |

**Routes:** `GET /api/entitlements/{id}/evaluation`

**Implementation Notes:** Dependency block maps to the DEP constraint dimension in evaluation. When cross-entitlement dependencies are not satisfied, the DEP dimension returns BLOCKED or DENIED. The dimension_summary array in the evaluation envelope includes the DEP dimension entry. No named schema for dependency constraints at present.

---

### Invariant

> An Invariant is a protocol correctness rule that must hold at all times — violations are blocked by Guardian.

**Definition:** Invariants are non-negotiable correctness rules enforced by the Guardian layer. They cannot be configured or overridden.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Guardian` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to describe non-negotiable correctness rules.

**Prohibited:** Do not allow invariant violations under any circumstances.

**Related Terms:** Guardian, Guardian block, Protocol violation

**Canonical Mapping** (Confidence: `MEDIUM`)

| Field | Value |
|---|---|
| Schema | `GuardianBlockedErrorResponse` |
| OpenAPI Ref | `#/components/schemas/GuardianBlockedErrorResponse` |
| Source | `OA-ANNOTATE-01B` |

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true, x-semantic-warning

**Implementation Notes:** Protocol invariants are enforced by the Guardian (protocol enforcement layer independent of CE). The GuardianBlockedErrorResponse (x-authoritative: true, x-semantic-warning) is returned when an invariant violation is detected. PSL-004: Guardian enforces invariants independently of CE outcome.

---

### Protocol violation

> A Protocol violation is an attempted operation that would break a system invariant, resulting in a Guardian block.

**Definition:** Protocol violations are detected by Guardian and result in hard rejection. They indicate a correctness issue in the calling code.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Guardian` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to describe invariant-violating operations.

**Prohibited:** Do not suppress protocol violations — they indicate bugs.

**Related Terms:** Invariant, Guardian block

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `ProtocolErrorResponse` |
| OpenAPI Ref | `#/components/schemas/ProtocolErrorResponse` |
| Source | `OA-ANNOTATE-01B` |

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true

**Implementation Notes:** ProtocolErrorResponse carries x-authoritative: true per OA-ANNOTATE-01B. Returned when a protocol rule is violated (e.g. invalid state transition, invariant breach). This is distinct from validation errors (ValidationErrorResponse) and enforcement blocks (EnforcementBlockedResponse).

---

### Fail-closed

> Fail-closed is the Guardian principle that ambiguous or error conditions result in blocking rather than permitting mutations.

**Definition:** When Guardian encounters uncertainty, it blocks the operation. This prevents unsafe mutations in edge cases.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Guardian` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to describe the Guardian's default-deny behaviour.

**Prohibited:** Do not implement fail-open behaviour for mutations.

**Related Terms:** Guardian, Invariant

---

## Agent & Recovery

### Next action

> A Next action is the CE's recommended recovery step for an agent facing a BLOCKED evaluation outcome.

**Definition:** Next actions are recovery guidance returned with BLOCKED outcomes. Agents should validate before executing.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `NO` |
| Semantic Owner | `UAR` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to describe recommended recovery steps.

**Prohibited:** Do not blindly execute next actions — validate first.

**Related Terms:** UAR action, Recovery action, BLOCKED

**Notes:** Actions are recovery guidance, NOT protocol truth. Agents must validate before executing.

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `NextAction` |
| OpenAPI Ref | `#/components/schemas/NextAction` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `GET /api/entitlements/{id}/evaluation`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true

**Implementation Notes:** NextAction carries x-authoritative: true per OA-ANNOTATE-01B. Fields: action, description, endpoint, method. Returned within evaluation responses to guide agent recovery paths. UARActionItem and UARActionType also carry x-authoritative: true.

---

### UAR action

> A UAR action is a typed recovery operation from the canonical action set: ESCALATE, REDUCE_SCOPE, REQUEST_AUTHORISATION, RESOLVE_DEPENDENCY, UPGRADE, WAIT.

**Definition:** UAR (User Action Required) actions are the canonical set of recovery operations available to agents. DENY is internal-only.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `UAR` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use the canonical action types for recovery guidance.

**Prohibited:** Do not expose DENY as a user-facing action type.

**Related Terms:** Next action, Recovery action

**Notes:** Canonical types: ESCALATE, REDUCE_SCOPE, REQUEST_AUTHORISATION, RESOLVE_DEPENDENCY, UPGRADE, WAIT. DENY is internal-only.

---

### Recovery action

> A Recovery action is a concrete step an agent can take to resolve a blocking constraint and retry the operation.

**Definition:** Recovery actions provide actionable guidance for resolving BLOCKED outcomes. They map to specific UAR action types.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `RECOMMENDED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `UAR` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to describe concrete recovery steps.

**Prohibited:** Do not execute recovery actions without validation.

**Related Terms:** UAR action, Next action, Blocking constraint

---

### Action

> Action is a general term for an operation or step — prefer the more specific Next action, UAR action, or Recovery action where precision matters.

**Definition:** Action is an overloaded term. Use the more specific variant when describing protocol operations.

| Field | Value |
|---|---|
| Authority Status | `Non-authoritative Metadata` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `various` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use only where the specific action type is not relevant.

**Prohibited:** Do not use when Next action, UAR action, or Recovery action is more precise.

**Related Terms:** Next action, UAR action, Recovery action

**Drift Classification:** `AMBIGUOUS`
  *Dictionary: 'Action is a general term for an operation or step — prefer the more specific Next action, UAR action, or Recovery action where precision matters.' Non-authoritative Metadata. Overloaded across multiple protocol concepts. Risk: agents use generic 'action' when a specific typed action is required.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | EVOLVING |
| Migration Risk | LOW |
| Governance Status | UNDER_REVIEW |
| Last Reviewed | 2026-05-09 |
| Review Trigger | UAR action type taxonomy finalisation |

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `UARActionItem` |
| Field | `type` |
| Enum | `UARActionType` |
| OpenAPI Ref | `#/components/schemas/UARActionItem` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `GET /api/entitlements/{id}/evaluation`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true

**Implementation Notes:** UARActionItem and UARActionType both carry x-authoritative: true per OA-ANNOTATE-01B. Actions are recovery instructions returned within BLOCKED evaluation responses. AMBIGUOUS drift classification (DICT-02B) — Action has multiple meanings (enforcement action, recovery action, UARActionItem). The canonical mapping here is to UARActionItem/Type as the most authoritative surface.

---

### Retryable

> A retryable condition is one where the blocking constraint may be resolved and the operation re-attempted — BLOCKED outcomes are retryable, DENIED outcomes are not.

**Definition:** Retryable maps to BLOCKED outcomes. After resolving the blocking constraint, the agent may retry the operation.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `NO` |
| Semantic Owner | `CE/UAR` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use to describe BLOCKED outcomes that may be resolved.

**Prohibited:** Do not describe DENIED outcomes as retryable.

**Related Terms:** BLOCKED, Recoverable, Terminal

**Canonical Mapping** (Confidence: `MEDIUM`)

| Field | Value |
|---|---|
| Schema | `NextAction` |
| OpenAPI Ref | `#/components/schemas/NextAction` |
| Source | `OA-ANNOTATE-01B` |

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true

**Implementation Notes:** Retryable maps to the NextAction schema (x-authoritative: true per OA-ANNOTATE-01B), which provides agent recovery instructions after a BLOCKED outcome. UARActionType also carries x-authoritative: true and defines the set of recovery action types available.

---

### Recoverable

> Recoverable is a synonym for retryable in recovery context — the blocking condition may be resolved.

**Definition:** Recoverable is interchangeable with retryable. Both indicate that the blocking constraint may be resolved.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `RECOMMENDED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `CE/UAR` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use as a synonym for retryable in recovery contexts.

**Prohibited:** Do not describe DENIED or terminal conditions as recoverable.

**Related Terms:** Retryable, BLOCKED

---

### Terminal

> A terminal condition is one from which no recovery is possible — DENIED outcomes and terminal lifecycle states are non-recoverable.

**Definition:** Terminal conditions cannot be recovered. DENIED CE outcomes and terminal lifecycle states (CONSUMED, REVOKED) are non-recoverable.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `NO` |
| Semantic Owner | `CE/Lifecycle` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use to describe non-recoverable conditions.

**Prohibited:** Do not attempt recovery actions on terminal conditions.

**Related Terms:** DENIED, Terminal state, Retryable

**Canonical Mapping** (Confidence: `MEDIUM`)

| Field | Value |
|---|---|
| Schema | `EntitlementState` |
| Enum | `consumed, expired, closed, paid, settled, declined, resolved` |
| OpenAPI Ref | `#/components/schemas/EntitlementState` |
| Source | `direct inspection` |

**Routes:** `GET /api/lifecycle/matrix`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true

**Implementation Notes:** Terminal states are defined within the EntitlementState enum (x-authoritative: true). Terminal states (no further transitions): consumed, expired, closed. Other states may be terminal depending on the lifecycle matrix. The /api/lifecycle/matrix endpoint returns valid transitions, from which terminal states can be inferred (states with no outgoing transitions).

---

### Agent-critical

> Agent-critical marks protocol elements where agent misunderstanding could cause unsafe mutation, invalid replay, or broken recovery.

**Definition:** Agent-critical annotations flag elements that require careful handling by AI agents and automated systems.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `RECOMMENDED` |
| Machine Critical | `CRITICAL` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Core Protocol` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use to flag elements requiring careful agent handling.

**Prohibited:** Do not ignore agent-critical annotations in automated systems.

**Related Terms:** Evaluation, Consume, Idempotency

**Canonical Mapping** (Confidence: `MEDIUM`)

| Field | Value |
|---|---|
| Schema | `NextAction` |
| OpenAPI Ref | `#/components/schemas/NextAction` |
| Source | `direct inspection` |

**Routes:** `GET /api/entitlements/{id}/evaluation`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: true

**Implementation Notes:** Agent-critical surfaces are those which AI agents must interpret correctly to achieve successful outcomes. The NextAction schema (x-authoritative: true) and the exercisable boolean in the evaluation envelope are the primary agent-critical surfaces. The ai_convenience sub-object in evaluation metadata (execution_status: EXECUTABLE/NOT_EXECUTABLE) provides agent-readable projections.

---

### Orientation

> Orientation is the protocol discovery mechanism that provides agents with the entry points and workflow stages for interacting with the system.

**Definition:** The orientation endpoint (GET /api) provides a zero-knowledge discovery surface for agents to understand available operations.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Core Protocol` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to describe the protocol discovery mechanism.

**Prohibited:** Do not modify orientation responses based on actor context — they must be deterministic.

**API References:** `GET /api`

**Related Terms:** Read surface, Sandbox

---

### Read surface

> A Read surface is a protocol endpoint that returns evaluation evidence or constraint state without performing mutations.

**Definition:** Read surfaces provide observation-only access to protocol state. They return evidence, not authoritative decisions.

| Field | Value |
|---|---|
| Authority Status | `Authoritative` |
| Normative Status | `REQUIRED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `CE` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `MEDIUM` |
| Confidence | `HIGH` |

**Permitted:** Use to describe read-only evaluation endpoints.

**Prohibited:** Do not treat read surface results as authoritative for enforcement decisions — re-evaluate at exercise time.

**API References:** `GET /api/entitlements/{id}/evaluation`

**Related Terms:** Evaluation, Orientation

**Notes:** Evidence only — stored results are NOT authoritative for enforcement decisions.

---

### Sandbox

> A Sandbox is a controlled test environment that provides non-production context for agents to perform live evaluation and consume flows.

**Definition:** The sandbox provides test identifiers, test entitlements, and a safe environment for agents to learn the protocol without affecting production data.

| Field | Value |
|---|---|
| Authority Status | `Non-authoritative Metadata` |
| Normative Status | `RECOMMENDED` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Core Protocol` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use to describe the test environment for agent learning.

**Prohibited:** Do not treat sandbox results as production data.

**API References:** `GET /api/sandbox`

**Related Terms:** Orientation, Test case

**Drift Classification:** `NOT_FIRST_CLASS`
  *Authority status=Non-authoritative Metadata. Sandbox is a test environment concept, not a core protocol primitive. Risk: integrators treat sandbox identifiers as equivalent to production entities. Definition explicitly prohibits treating sandbox results as production data.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | EVOLVING |
| Migration Risk | LOW |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Sandbox v2.0 specification |

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `SandboxDiscovery` |
| OpenAPI Ref | `#/components/schemas/SandboxDiscovery` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `GET /api/sandbox`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: false

**Implementation Notes:** SandboxDiscovery and SandboxTestCase carry x-authoritative: false per OA-ANNOTATE-01B. NOT_FIRST_CLASS drift classification (DICT-02B). Sandbox is a testing/development surface — not a protocol primitive. The sandbox routes serve test scenarios for integration development.

---

### Test case

> A Test case is a predefined sandbox scenario that exercises a specific protocol flow with known inputs and expected outcomes.

**Definition:** Test cases provide structured learning scenarios for agents to understand protocol behaviour under specific conditions.

| Field | Value |
|---|---|
| Authority Status | `Non-authoritative Metadata` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Core Protocol` |
| Cross-Domain Stability | `UNIVERSAL` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use for structured agent learning scenarios.

**Prohibited:** Do not treat test case outcomes as production guarantees.

**Related Terms:** Sandbox, Orientation

---

## Profile Extension

### Claim

> A Claim is an insurance-profile structured request to exercise entitlement value under a Coverage Entitlement.

**Definition:** Claims are insurance-profile specific exercise requests. They map to the Consume operation at the core protocol level.

| Field | Value |
|---|---|
| Authority Status | `Profile-authoritative` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Insurance profile` |
| Cross-Domain Stability | `PROFILE-SCOPED` |
| Migration Risk | `HIGH` |
| Confidence | `HIGH` |

**Permitted:** Use in insurance-profile contexts for structured exercise requests.

**Prohibited:** Do not use Claim as a synonym for Consume in core protocol logic.

**Related Terms:** Consume, Coverage, Incident

**Domain Translations:**
- insurance claim → **Claim → Consume**

**Notes:** Forbidden: Do not use Claim as a synonym for Consume in core protocol logic.

**Drift Classification:** `DOMAIN_ONLY`
  *Authority status = Profile-authoritative (insurance profile only). Definition: 'Claims map to the Consume operation at the core protocol level.' Prohibited as synonym for Consume in core logic. High migration_risk if leaks into core. PSL-008 applies.*
  Profiles: insurance

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | STABLE |
| Migration Risk | HIGH |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Insurance profile v1.0 formalisation |

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `Claim` |
| OpenAPI Ref | `#/components/schemas/Claim` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `POST /api/claims`, `GET /api/claims/{id}`, `POST /api/claims/{id}/assess`, `POST /api/claims/{id}/transition`

**Semantic Extensions (OA-ANNOTATE-01B):** x-semantic-warning

**Implementation Notes:** Claim schema carries x-semantic-warning per OA-ANNOTATE-01B (domain-specific term). DOMAIN_ONLY drift classification (DICT-02B) — 'claim' is an insurance-domain term, not a core protocol primitive. Maps to /api/claims/* route group. ClaimCreateRequest, ClaimAssessRequest/Response, ClaimTransitionRequest/Response, ClaimLine, ClaimLineCreateRequest/Update all carry x-semantic-warning. PSL-008 governs: claim is a domain term that must map to protocol operations at execution time.

---

### Coverage

> Coverage is an insurance-profile interpretation of an Entitlement.

**Definition:** Coverage maps onto the Entitlement primitive in the insurance profile. It represents insured benefits under a policy.

| Field | Value |
|---|---|
| Authority Status | `Profile-authoritative` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Insurance profile` |
| Cross-Domain Stability | `DOMAIN-VARIABLE` |
| Migration Risk | `HIGH` |
| Confidence | `HIGH` |

**Permitted:** Use in insurance-profile contexts.

**Prohibited:** Do not use Coverage as a synonym for Entitlement in core protocol logic.

**Related Terms:** Entitlement, Claim

**Domain Translations:**
- insurance coverage → **Entitlement**

**Notes:** Domain translation: insurance coverage → Entitlement.

**Drift Classification:** `DOMAIN_ONLY`
  *Authority status = Profile-authoritative (insurance profile). Definition: 'Coverage maps onto the Entitlement primitive in the insurance profile.' Prohibited as synonym for Entitlement in core logic. High migration_risk=HIGH. Domain translation: insurance coverage → Entitlement.*
  Profiles: insurance

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | STABLE |
| Migration Risk | HIGH |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Insurance profile v1.0 formalisation |

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `CoverageEvaluation` |
| OpenAPI Ref | `#/components/schemas/CoverageEvaluation` |
| Source | `OA-ANNOTATE-01B` |

**Routes:** `POST /api/coverage/evaluate`

**Semantic Extensions (OA-ANNOTATE-01B):** x-authoritative: false, x-semantic-warning

**Implementation Notes:** CoverageEvaluation carries x-authoritative: false and x-semantic-warning per OA-ANNOTATE-01B. DOMAIN_ONLY drift classification (DICT-02B) — 'coverage' is an insurance-domain term. CoverageEvaluateRequest also carries x-semantic-warning. SYN-NAME-01 §5 finding #14 flags CoverageEvaluation.evaluation_result for semantics overlap with 'outcome'. PSL-008: coverage is a domain term; must map to canonical evaluation/entitlement terms at protocol level.

---

### Incident

> An Incident is an insurance-profile triggering event that may give rise to a Claim.

**Definition:** Incidents are the triggering events in the insurance profile that initiate the claims process.

| Field | Value |
|---|---|
| Authority Status | `Profile-authoritative` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Insurance profile` |
| Cross-Domain Stability | `PROFILE-SCOPED` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use in insurance-profile contexts for triggering events.

**Prohibited:** Do not use Incident in core protocol logic.

**Related Terms:** Claim, Coverage

**Domain Translations:**
- travel disruption event → **Incident**

**Drift Classification:** `DOMAIN_ONLY`
  *Authority status=Profile-authoritative (insurance profile). normative_status=OPTIONAL. Definition: 'Incidents are the triggering events in the insurance profile.' Prohibited in core protocol logic. PSL-008 applies.*
  Profiles: insurance, travel

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | STABLE |
| Migration Risk | LOW |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Insurance profile v1.0 formalisation |

---

### Claim line

> A Claim line is an individual item within a structured Claim, representing a specific benefit or service claimed.

**Definition:** Claim lines break down a Claim into individual benefit items for processing and settlement.

| Field | Value |
|---|---|
| Authority Status | `Profile-authoritative` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Insurance profile` |
| Cross-Domain Stability | `PROFILE-SCOPED` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use in insurance-profile contexts for itemised claim breakdown.

**Prohibited:** Do not use in core protocol logic.

**Related Terms:** Claim, Coverage

---

### Itinerary

> An Itinerary is a travel-profile journey scope that maps to Container metadata in the core protocol.

**Definition:** Itineraries represent travel journey structure in the travel profile. They map to Container metadata at the core level.

| Field | Value |
|---|---|
| Authority Status | `Profile-authoritative` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Travel profile` |
| Cross-Domain Stability | `PROFILE-SCOPED` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use in travel-profile contexts.

**Prohibited:** Do not use in core protocol logic.

**Related Terms:** Itinerary node, Container

**Domain Translations:**
- travel itinerary → **Container metadata**

**Drift Classification:** `DOMAIN_ONLY`
  *Authority status=Profile-authoritative (travel profile). Prohibited in core protocol logic. Maps to Container metadata at the core level. PSL-008 applies.*
  Profiles: travel

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | STABLE |
| Migration Risk | LOW |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Travel profile v1.0 formalisation |

**Canonical Mapping** (Confidence: `LOW`)

| Field | Value |
|---|---|
| Schema | `Itinerary` |
| Field | `state` |
| OpenAPI Ref | `#/components/schemas/Itinerary` |
| Source | `direct inspection` |

**Routes:** `POST /api/itineraries`, `GET /api/itineraries/{id}`

**Implementation Notes:** Itinerary.state is the canonical lifecycle field per SYN-NAME-02 (state renamed from status). Itinerary.status is deprecated (x-replaced-by: state). Note: Itinerary.state runtime population is DEFERRED (SYN-NAME-02 deferred item — schema added, runtime wiring pending). x-domain-profile: travel. SYN-NAME-02 COMPLETE for schema (commit 36b5b465, deploy 2026-05-10).

---

### Itinerary node

> An Itinerary node is a waypoint or segment within an Itinerary.

**Definition:** Itinerary nodes represent individual stops, flights, or segments within a travel itinerary.

| Field | Value |
|---|---|
| Authority Status | `Profile-authoritative` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Travel profile` |
| Cross-Domain Stability | `PROFILE-SCOPED` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use in travel-profile contexts.

**Prohibited:** Do not use in core protocol logic.

**Related Terms:** Itinerary

---

### Availability

> Availability is a profile-level informational snapshot of current resource state — it is not a reservation confirmation.

**Definition:** Availability snapshots are point-in-time views of resource state. They do not guarantee future availability and must not be treated as reservations.

| Field | Value |
|---|---|
| Authority Status | `Presentation-only` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Travel/Commerce` |
| Cross-Domain Stability | `PROFILE-SCOPED` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use for informational snapshots of resource state.

**Prohibited:** Do not treat availability as a reservation confirmation.

**Related Terms:** Reservation, Hold

**Notes:** Availability snapshots must not be treated as reservation confirmations.

**Drift Classification:** `PRESENTATION_ONLY`
  *Authority status=Presentation-only. Definition: 'point-in-time views of resource state — do not guarantee future availability.' Notes: 'must not be treated as reservation confirmations.' High misuse risk: travel domain integrators treat availability snapshots as provisional reservations.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | STABLE |
| Migration Risk | LOW |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Addition of first-class Reservation primitive |

**Canonical Mapping** (Confidence: `HIGH`)

| Field | Value |
|---|---|
| Schema | `AvailabilitySnapshot` |
| OpenAPI Ref | `#/components/schemas/AvailabilitySnapshot` |
| Source | `OA-ANNOTATE-01B` |

**Semantic Extensions (OA-ANNOTATE-01B):** x-presentation-only: true, x-authoritative: false, x-semantic-warning

**Implementation Notes:** AvailabilitySnapshot carries x-presentation-only: true, x-authoritative: false, and x-semantic-warning per OA-ANNOTATE-01B. PRESENTATION_ONLY drift classification (DICT-02B) consistent. Availability is a presentation-layer concept derived from Entitlement/Container capacity data.

---

### Product reference

> A Product reference is a profile-level identifier linking an Entitlement to an external product catalogue.

**Definition:** Product references provide the link between protocol Entitlements and external product/service catalogues.

| Field | Value |
|---|---|
| Authority Status | `Non-authoritative Metadata` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SAFE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Commerce profile` |
| Cross-Domain Stability | `PROFILE-SCOPED` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use for external product catalogue references.

**Prohibited:** Do not use as a substitute for Entitlement identity.

**Related Terms:** Entitlement

---

### Supplier

> A Supplier is a profile-level entity that provides the resource or service underlying an Entitlement.

**Definition:** Suppliers are external entities referenced in profile metadata. They are not core protocol entities.

| Field | Value |
|---|---|
| Authority Status | `Non-authoritative Metadata` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SAFE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Commerce profile` |
| Cross-Domain Stability | `PROFILE-SCOPED` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use for external supplier references.

**Prohibited:** Do not treat as a core protocol entity.

**Related Terms:** Resource, Product reference

---

### Policy number

> A Policy number is an insurance-profile external identifier for the insurance policy document.

**Definition:** Policy numbers are external identifiers from the insurance domain. They reference the insurance policy (which maps to Container in the core protocol).

| Field | Value |
|---|---|
| Authority Status | `Non-authoritative Metadata` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Insurance profile` |
| Cross-Domain Stability | `PROFILE-SCOPED` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use in insurance-profile contexts for external policy references.

**Prohibited:** Do not use as a substitute for Container identity.

**Related Terms:** Container, Policy

---

### Policyholder

> A Policyholder is the insurance-profile term for the Holder of an insurance Container.

**Definition:** Policyholder maps to Holder in the core protocol. It is the named insured on a policy.

| Field | Value |
|---|---|
| Authority Status | `Non-authoritative Metadata` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Insurance profile` |
| Cross-Domain Stability | `PROFILE-SCOPED` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use in insurance-profile contexts.

**Prohibited:** Do not use as a synonym for Holder in core protocol logic.

**Related Terms:** Holder, Container

**Domain Translations:**
- policyholder → **Holder**

**Drift Classification:** `DOMAIN_ONLY`
  *Authority status=Non-authoritative Metadata (insurance profile). Prohibited as synonym for Holder in core logic. Domain translation: policyholder → Holder. PSL-008 applies.*
  Profiles: insurance

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | STABLE |
| Migration Risk | LOW |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Insurance profile v1.0 formalisation |

**Canonical Mapping** (Confidence: `LOW`)

| Field | Value |
|---|---|
| Field | `policyholder_name` |
| Source | `SYN-NAME-01` |

**Semantic Extensions (OA-ANNOTATE-01B):** x-semantic-warning

**Implementation Notes:** QUARANTINED TERM — SYN-NAME-01 §5 findings #12, #17: policyholder/policyholder_name/policyholder_email appear as fields on the Container schema (insurance-domain leakage into core). PSL-008 violation: domain language present in core schema without profile isolation. DOMAIN_ONLY drift classification (DICT-02B) consistent with quarantine. Planned remediation: SYN-NAME-13 (remove policyholder fields from core Container schema). Container.policy_number is marked x-replaced-by: external_ref (OA-ANNOTATE-01B §17 issue #5). No canonical schema named 'Policyholder' exists.

---

### Traveller

> A Traveller is the travel-profile term for the Holder or Beneficiary of a travel Entitlement.

**Definition:** Traveller maps to Holder or Beneficiary in the core protocol depending on context.

| Field | Value |
|---|---|
| Authority Status | `Non-authoritative Metadata` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SAFE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Travel profile` |
| Cross-Domain Stability | `PROFILE-SCOPED` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use in travel-profile contexts.

**Prohibited:** Do not use as a synonym for Holder in core protocol logic.

**Related Terms:** Holder, Beneficiary

---

### Booking

> Booking is an ambiguous profile term that may map to Container, Entitlement, or an external reference depending on profile context.

**Definition:** Booking is profile-dependent and must be explicitly mapped to the correct core protocol entity in each usage context.

| Field | Value |
|---|---|
| Authority Status | `Non-authoritative Metadata` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Travel/Commerce` |
| Cross-Domain Stability | `DOMAIN-VARIABLE` |
| Migration Risk | `MEDIUM` |
| Confidence | `MEDIUM` |

**Permitted:** Use only with explicit profile mapping to Container, Entitlement, or external reference.

**Prohibited:** Do not use without explicit mapping — it is ambiguous.

**Related Terms:** Container, Entitlement

**Notes:** Requires explicit profile mapping for each usage.

**Drift Classification:** `AMBIGUOUS`
  *Dictionary: 'Booking is an ambiguous profile term that may map to Container, Entitlement, or an external reference depending on profile context.' confidence=MEDIUM. Requires explicit profile mapping. OA-ANNOTATE-01B unmapped synonym pair — no current API surface, making it a high-risk future drift vector.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | EVOLVING |
| Migration Risk | MEDIUM |
| Governance Status | PROPOSED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Travel profile v1.0 formalisation |

---

### Membership

> Membership is a loyalty-profile term for a Container that represents a membership account scope.

**Definition:** Membership maps to Container in the loyalty profile. It represents the account scope under which loyalty Entitlements exist.

| Field | Value |
|---|---|
| Authority Status | `Non-authoritative Metadata` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Loyalty profile` |
| Cross-Domain Stability | `PROFILE-SCOPED` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use in loyalty-profile contexts.

**Prohibited:** Do not use as a synonym for Container in core protocol logic.

**Related Terms:** Container, Wallet

**Domain Translations:**
- loyalty membership → **Container**

**Drift Classification:** `DOMAIN_ONLY`
  *Authority status=Non-authoritative Metadata. Prohibited as synonym for Container in core logic. Loyalty profile specific. PSL-008 applies.*
  Profiles: loyalty

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | STABLE |
| Migration Risk | LOW |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Loyalty profile v1.0 formalisation |

---

### Wallet

> A Wallet is a presentation-only aggregate view of multiple Entitlements — it is not a protocol entity.

**Definition:** Wallets are UI constructs that aggregate Entitlements for display. They are not protocol entities and carry no authority.

| Field | Value |
|---|---|
| Authority Status | `Presentation-only` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SAFE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `UI/Presentation` |
| Cross-Domain Stability | `DOMAIN-VARIABLE` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use as a presentation aggregate for Entitlements.

**Prohibited:** Do not treat Wallet as a protocol entity — it is presentation-only.

**Related Terms:** Entitlement, Membership

**Notes:** Wallet is presentation-only — not a protocol entity.

**Drift Classification:** `PRESENTATION_ONLY`
  *Authority status=Presentation-only. Definition: 'Wallet is a presentation-only aggregate view — not a protocol entity.' PSL-007 (carriers never create protocol truth) governs adjacent concepts. High misuse risk: integrators frequently build Wallet as if it were a protocol entity with its own lifecycle.*

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | STABLE |
| Migration Risk | LOW |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Addition of any wallet-like protocol entity |

---

### Loyalty

> Loyalty is a domain profile for points-based and membership entitlement systems.

**Definition:** The loyalty profile maps loyalty program concepts onto the core protocol: membership → Container, points → Entitlement capacity, redemption → Consume.

| Field | Value |
|---|---|
| Authority Status | `Non-authoritative Metadata` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Loyalty profile` |
| Cross-Domain Stability | `PROFILE-SCOPED` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use as a domain profile reference.

**Prohibited:** Do not allow loyalty terminology to colonise core protocol schemas.

**Related Terms:** Membership, Entitlement, Consume

**Domain Translations:**
- loyalty points → **Entitlement capacity**

**Drift Classification:** `DOMAIN_ONLY`
  *Authority status=Non-authoritative Metadata (loyalty profile). Prohibited from colonising core protocol schemas. PSL-008 applies.*
  Profiles: loyalty

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | STABLE |
| Migration Risk | LOW |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Loyalty profile v1.0 formalisation |

---

### Gift card

> A Gift card is a commerce-profile Entitlement with fixed capacity representing stored monetary value.

**Definition:** Gift cards map to Entitlements with capacity in the commerce profile. Gift card balance = Entitlement capacity. Redemption = Consume.

| Field | Value |
|---|---|
| Authority Status | `Non-authoritative Metadata` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Commerce profile` |
| Cross-Domain Stability | `PROFILE-SCOPED` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use in commerce-profile contexts.

**Prohibited:** Do not treat gift card balance as separate from Entitlement capacity.

**Related Terms:** Entitlement, Capacity, Consume

**Domain Translations:**
- gift card balance → **Entitlement capacity**
- gift card redemption → **Consume**

**Drift Classification:** `DOMAIN_ONLY`
  *Authority status=Non-authoritative Metadata (commerce profile). Gift card balance = Entitlement capacity. Redemption = Consume. PSL-008 applies.*
  Profiles: commerce

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | STABLE |
| Migration Risk | LOW |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Commerce profile v1.0 formalisation |

---

### Subscription

> A Subscription is a time-bounded Entitlement governed by the TMP dimension for access period control.

**Definition:** Subscriptions map to time-bounded Entitlements in the core protocol. The TMP dimension controls access period evaluation.

| Field | Value |
|---|---|
| Authority Status | `Non-authoritative Metadata` |
| Normative Status | `OPTIONAL` |
| Machine Critical | `SENSITIVE` |
| Protocol Primitive | `NO` |
| Semantic Owner | `Commerce profile` |
| Cross-Domain Stability | `PROFILE-SCOPED` |
| Migration Risk | `LOW` |
| Confidence | `HIGH` |

**Permitted:** Use in commerce-profile contexts.

**Prohibited:** Do not treat subscription access as separate from Entitlement + TMP evaluation.

**Related Terms:** Entitlement, Dimension

**Domain Translations:**
- subscription access → **Time-bounded Entitlement**

**Drift Classification:** `DOMAIN_ONLY`
  *Authority status=Non-authoritative Metadata (commerce profile). Maps to time-bounded Entitlement. Prohibited as synonym for Entitlement in core logic. PSL-008 applies.*
  Profiles: commerce

**Governance Metadata:**

| Field | Value |
|---|---|
| Semantic Stability | STABLE |
| Migration Risk | LOW |
| Governance Status | RATIFIED |
| Last Reviewed | 2026-05-09 |
| Review Trigger | Commerce profile v1.0 formalisation |

---