@cleocode/contracts 2026.5.111 → 2026.5.113

package/src/index.ts

@@ -224,6 +224,21 @@ export type {
   ConduitTopicSubscribeOptions,
   ConduitUnsubscribe,
 } from './conduit.js';
+// === Config Manifest (T9876 / Saga T9855) ===
+export type {
+  ConfigManifestEntry,
+  ConfigManifestScope,
+  ConfigScope,
+  DriftDetection,
+} from './config/manifest.js';
+export {
+  CLEO_CONFIG_MANIFEST,
+  CONFIG_MANIFEST_ENTRIES,
+  configManifestEntrySchema,
+  GLOBAL_CLEO_CONFIG_MANIFEST,
+  PROJECT_CONTEXT_MANIFEST,
+  PROJECT_INFO_MANIFEST,
+} from './config/manifest.js';
 // === Configuration Types ===
 export type {
   BackupConfig,
@@ -312,6 +327,42 @@ export { CANONICAL_DOMAINS } from './dispatch/identity.js';
 export type { OperationDef, Resolution } from './dispatch/operation-def.js';
 // === Dispatch OPERATIONS data + builder helpers (T10061 — T9833b / E-CLI-BOUNDARY / SG-ARCH-SOLID) ===
 export { defineDomain, defineOp, OPERATIONS } from './dispatch/operations-registry.js';
+// === Docs Provenance Graph (T10166 / Saga T9855 / E12) ===
+export type {
+  DocLifecycleStatus,
+  DocProvenanceResponse,
+  ProvenanceDecisionNode,
+  ProvenanceDocNode,
+  ProvenanceEdge,
+  ProvenanceEdgeRelation,
+  ProvenanceMemoryNode,
+  ProvenanceNode,
+  ProvenanceNodeKind,
+  ProvenanceSessionNode,
+  ProvenanceTaskNode,
+} from './docs/provenance.js';
+export {
+  DOC_LIFECYCLE_STATUSES,
+  docLifecycleStatusSchema,
+  docProvenanceResponseSchema,
+  isDocProvenanceResponse,
+  isProvenanceDecisionNode,
+  isProvenanceDocNode,
+  isProvenanceMemoryNode,
+  isProvenanceSessionNode,
+  isProvenanceTaskNode,
+  PROVENANCE_EDGE_RELATIONS,
+  PROVENANCE_NODE_KINDS,
+  provenanceDecisionNodeSchema,
+  provenanceDocNodeSchema,
+  provenanceEdgeRelationSchema,
+  provenanceEdgeSchema,
+  provenanceMemoryNodeSchema,
+  provenanceNodeKindSchema,
+  provenanceNodeSchema,
+  provenanceSessionNodeSchema,
+  provenanceTaskNodeSchema,
+} from './docs/provenance.js';
 // === DocsAccessor Contracts (T9063) ===
 export type {
   DocExportFormat,
@@ -342,6 +393,7 @@ export {
 // === Doctor: DB-Substrate Survey (T10307 — Saga T10281 / Epic T10282) ===
 // === Doctor: Legacy-Backup Walker (T10309 — Saga T10281 / Epic T10282) ===
 // === Doctor: Cross-DB Invariants (T10323 — Saga T10281 / Epic T10285) ===
+// === Doctor: Invariant Registry Audit (T10340 — Saga T10326 / Epic T10327) ===
 export type {
   ComprehensiveAuditResult,
   DbCrossDbInvariantId,
@@ -356,6 +408,10 @@ export type {
   DbSubstrateSurveyOptions,
   DbSubstrateWarning,
   DbSubstrateWarningKind,
+  InvariantAuditEntry,
+  InvariantAuditResult,
+  InvariantAuditStatus,
+  InvariantAuditViolation,
   LegacyBackupEntry,
   LegacyBackupOriginHint,
   LegacyBackupRecommendation,
@@ -415,6 +471,31 @@ export {
   normalizeError,
   ThinAgentViolationError,
 } from './errors.js';
+// === ADR-051 Evidence Atom Grammar (T10337 — Saga T10326) ===
+export type {
+  EvidenceAtom as EvidenceAtomInput,
+  EvidenceAtomKind,
+  EvidenceValidationResult,
+  GateEvidenceRequirement,
+} from './evidence-atom-schema.js';
+export {
+  callsiteCoverageAtomSchema,
+  commitAtomSchema,
+  decisionAtomSchema,
+  EvidenceAtomSchema,
+  EvidenceParseError,
+  filesAtomSchema,
+  formatGateRequirement,
+  GATE_EVIDENCE_REQUIREMENTS,
+  locDropAtomSchema,
+  noteAtomSchema,
+  parseEvidenceString,
+  prAtomSchema,
+  testRunAtomSchema,
+  toolAtomSchema,
+  urlAtomSchema,
+  validateEvidenceForGate,
+} from './evidence-atom-schema.js';
 // === Evidence Record Types (IVTR typed proof artifacts) ===
 export type {
   CommandOutputRecord,
@@ -455,6 +536,9 @@ export {
   E_EVIDENCE_INSUFFICIENT,
   // SPEC-T9345 release pipeline v2 error code names (T9530)
   E_GH_NOT_AUTHENTICATED,
+  // T10341 — typed CLI-layer validation for --severity + --pipeline-stage
+  E_INVALID_PIPELINE_STAGE,
+  E_INVALID_SEVERITY_VALUE,
   E_INVALID_STATE,
   E_PLAN_NOT_FOUND,
   E_RELEASE_PLAN_INVALID,
@@ -529,6 +613,21 @@ export {
 } from './graph.js';
 export type { AdapterHookProvider } from './hooks.js';
 export type { AdapterInstallProvider, InstallOptions, InstallResult } from './install.js';
+// === Invariants Registry (Saga T10326 / Epic T10327 / Task T10335 — SG-SUBSTRATE-RECONCILIATION) ===
+export type {
+  InvariantDoctorAudit,
+  InvariantLintRule,
+  InvariantRuntimeGate,
+  InvariantSeverity,
+  RegisteredInvariant,
+} from './invariants/index.js';
+export {
+  ADR_056_INVARIANTS,
+  ADR_073_INVARIANTS,
+  getInvariant,
+  getInvariantsByAdr,
+  INVARIANTS_REGISTRY,
+} from './invariants/index.js';
 // === Background Job Status (T9955 — promoted from core/store/tasks-schema.ts) ===
 export type { BackgroundJobStatus } from './jobs.js';
 export type {
@@ -816,6 +915,17 @@ export type {
 } from './operations/dialectic.js';
 // === Operations Types (API wire format, namespaced to avoid collision with domain types) ===
 export * as ops from './operations/index.js';
+// === Operation Input Contracts (T9914 / Saga T9855 / E7) ===
+// Re-exported at top level so SDK consumers (validator T9915, mutate DX
+// surface, generated docs) can import without the `ops.` namespace hop.
+export type {
+  JsonSchema,
+  OperationInputContract,
+  OperationInputContractRegistry,
+  OperationInputExample,
+  ValidationError,
+  ValidationResult,
+} from './operations/input-contract.js';
 // === Lifecycle Operation Types (T1455 — ADR-057 D1 Core normalization) ===
 // Re-exported at top level so @cleocode/core/lifecycle can import without the `ops.` namespace hop.
 // Note: Gate is included here — GateStatus conflict resolved (T1694): lifecycle.ts now re-exports
@@ -1805,6 +1915,25 @@ export type {
   TaskViewNextAction,
   TaskViewPipelineStage,
 } from './tasks.js';
+// === Template Manifest (T9875 / Saga T9855) ===
+export type {
+  PlaceholderSource,
+  PlaceholderSpec,
+  PlaceholderSpecInput,
+  TemplateKind,
+  TemplateManifestEntry,
+  TemplateManifestEntryInput,
+  TemplateSubstitution,
+  UpdateStrategy,
+} from './templates/manifest.js';
+export {
+  PLACEHOLDER_SOURCES,
+  PlaceholderSpecSchema,
+  TEMPLATE_KINDS,
+  TEMPLATE_SUBSTITUTIONS,
+  TEMPLATE_UPDATE_STRATEGIES,
+  TemplateManifestEntrySchema,
+} from './templates/manifest.js';
 // === Tessera Types ===
 export type {
   TesseraInstantiationInput,

package/src/invariants/__tests__/adr-056-release.test.ts

@@ -0,0 +1,102 @@
+/**
+ * Unit tests for the ADR-056 D1-D6 entries in the central invariants
+ * registry (T10339 — R5).
+ *
+ * The release-side executable subsystem at
+ * `packages/core/src/release/invariants/registry.ts` consumes these
+ * metadata entries via `getInvariantsByAdr('ADR-056')`. The tests below
+ * assert the metadata shape downstream consumers (R4 CI gate, R6 doctor
+ * audit, R8 docs renderer) rely on.
+ *
+ * @epic T10327 — E-INVARIANT-REGISTRY-SSOT
+ * @saga T10326 — SG-SUBSTRATE-RECONCILIATION
+ * @task T10339 — R5: release-registry consumes central substrate
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  ADR_056_INVARIANTS,
+  getInvariant,
+  getInvariantsByAdr,
+  INVARIANTS_REGISTRY,
+} from '../index.js';
+
+describe('ADR-056 invariants — central registry entries', () => {
+  it('registers all six ADR-056 decisions D1-D6 under predictable keys', () => {
+    for (let i = 1; i <= 6; i++) {
+      const key = `ADR-056.D${i}`;
+      expect(INVARIANTS_REGISTRY[key]).toBeDefined();
+      expect(INVARIANTS_REGISTRY[key]?.adr).toBe('ADR-056');
+      expect(INVARIANTS_REGISTRY[key]?.code).toBe(`D${i}`);
+    }
+  });
+
+  it('getInvariantsByAdr("ADR-056") returns D1..D6 in declaration order', () => {
+    const adr056 = getInvariantsByAdr('ADR-056');
+    expect(adr056).toHaveLength(6);
+    expect(adr056.map((e) => e.code)).toEqual(['D1', 'D2', 'D3', 'D4', 'D5', 'D6']);
+  });
+
+  it('ADR_056_INVARIANTS convenience binding matches getInvariantsByAdr output', () => {
+    expect(ADR_056_INVARIANTS).toHaveLength(6);
+    const enumerated = getInvariantsByAdr('ADR-056');
+    expect(enumerated).toHaveLength(ADR_056_INVARIANTS.length);
+    for (let i = 0; i < ADR_056_INVARIANTS.length; i++) {
+      expect(enumerated[i]?.code).toBe(ADR_056_INVARIANTS[i]?.code);
+    }
+  });
+
+  it('every entry carries a non-empty name and description', () => {
+    for (const entry of ADR_056_INVARIANTS) {
+      expect(entry.name.length).toBeGreaterThan(0);
+      expect(entry.description.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('D4 is the archive-reason runtime gate (severity:error)', () => {
+    const d4 = getInvariant('ADR-056.D4');
+    expect(d4).toBeDefined();
+    expect(d4?.severity).toBe('error');
+    expect(d4?.runtimeGate).not.toBeNull();
+    expect(d4?.runtimeGate?.functionName).toBe('assertArchiveReason');
+    expect(d4?.runtimeGate?.module).toBe('packages/contracts/src/tasks/archive.ts');
+  });
+
+  it('D5 points at the release-invariants registry runtime gate', () => {
+    const d5 = getInvariant('ADR-056.D5');
+    expect(d5).toBeDefined();
+    expect(d5?.severity).toBe('warning');
+    expect(d5?.runtimeGate).not.toBeNull();
+    expect(d5?.runtimeGate?.functionName).toBe('runInvariants');
+    expect(d5?.runtimeGate?.module).toBe('packages/core/src/release/invariants/registry.ts');
+  });
+
+  it('D6 carries a lintRule pointer to the commit-msg hook (info severity)', () => {
+    const d6 = getInvariant('ADR-056.D6');
+    expect(d6).toBeDefined();
+    expect(d6?.severity).toBe('info');
+    expect(d6?.runtimeGate).toBeNull();
+    expect(d6?.lintRule?.lintScript).toBe('scripts/hooks/commit-msg-release-lint.mjs');
+  });
+
+  it('D1, D2, D3 are info-tier topology/convention decisions with no runtime gate', () => {
+    for (const code of ['D1', 'D2', 'D3'] as const) {
+      const entry = getInvariant(`ADR-056.${code}`);
+      expect(entry).toBeDefined();
+      expect(entry?.severity).toBe('info');
+      expect(entry?.runtimeGate).toBeNull();
+    }
+  });
+
+  it('every severity:"error" ADR-056 entry has a non-null runtimeGate', () => {
+    const errorTier = ADR_056_INVARIANTS.filter((e) => e.severity === 'error');
+    expect(errorTier.length).toBeGreaterThan(0);
+    for (const entry of errorTier) {
+      expect(entry.runtimeGate).not.toBeNull();
+      if (entry.runtimeGate !== null) {
+        expect(entry.runtimeGate.module.length).toBeGreaterThan(0);
+        expect(entry.runtimeGate.functionName.length).toBeGreaterThan(0);
+      }
+    }
+  });
+});

package/src/invariants/__tests__/adr-070-orchestration.test.ts

@@ -0,0 +1,186 @@
+/**
+ * Unit tests for the ADR-070 ORC-### orchestration invariants (T10336).
+ *
+ * The ORC codes are the Orchestrator / Lead / Worker behavioural contract
+ * surfaced through the central INVARIANTS_REGISTRY. The tests below assert:
+ *
+ * 1. At least 10 ORC-### entries are registered (we ship 14).
+ * 2. ORC-012 (the only ORC rule with a hard-enforced dispatch gate today)
+ *    points at the `enforceThinAgent` function in
+ *    `packages/core/src/orchestration/thin-agent.ts`.
+ * 3. Every `severity:'warning'` entry with `runtimeGate: null` carries
+ *    explanatory `description` text — the gap MUST be documented, not
+ *    silent.
+ * 4. ORC keys are emitted under the `ADR-070.` prefix in declaration
+ *    order and are merged into the central registry.
+ *
+ * @epic T10327 — E-INVARIANT-REGISTRY-SSOT
+ * @saga T10326 — SG-SUBSTRATE-RECONCILIATION
+ * @task T10336 — R2: enumerate ADR-070 ORC codes + register
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  ADR_070_INVARIANT_COUNT,
+  ADR_070_INVARIANTS,
+  ADR_070_MIN_ENTRIES,
+} from '../adr-070-orchestration.js';
+import {
+  getInvariant,
+  getInvariantsByAdr,
+  INVARIANTS_REGISTRY,
+  type RegisteredInvariant,
+} from '../index.js';
+
+/**
+ * Minimum ORC-### entry count required by AC1 — "Inventory ~ORC-001
+ * through ~ORC-020". We ship 14 today; the floor is 10 so future
+ * removals trip the gate before silently dropping coverage.
+ */
+const MIN_ORC_ENTRIES = 10;
+
+/**
+ * The ORC entry that has a hard-enforced dispatch-time guard today.
+ * Other entries either prompt-time (skill text) or filed-but-unshipped
+ * (ORC-010 / ORC-011 → T10278 / T10279).
+ */
+const HARD_ENFORCED_ORC_CODE = 'ORC-012';
+
+/**
+ * Expected runtime-gate module + function for ORC-012. Asserting both
+ * fields prevents silent drift if the thin-agent module is renamed or
+ * the export is shadowed.
+ */
+const ORC_012_RUNTIME_GATE = {
+  module: 'packages/core/src/orchestration/thin-agent.ts',
+  functionName: 'enforceThinAgent',
+} as const;
+
+describe('ADR_070_INVARIANTS — enumeration shape', () => {
+  it('exposes at least 10 ORC-### entries', () => {
+    expect(ADR_070_INVARIANTS.length).toBeGreaterThanOrEqual(MIN_ORC_ENTRIES);
+  });
+
+  it('keeps ADR_070_INVARIANT_COUNT in sync with the array length', () => {
+    expect(ADR_070_INVARIANT_COUNT).toBe(ADR_070_INVARIANTS.length);
+  });
+
+  it('declares ADR_070_MIN_ENTRIES at or above the AC1 floor', () => {
+    expect(ADR_070_MIN_ENTRIES).toBeGreaterThanOrEqual(MIN_ORC_ENTRIES);
+    expect(ADR_070_MIN_ENTRIES).toBeLessThanOrEqual(ADR_070_INVARIANTS.length);
+  });
+
+  it('every entry sets adr="ADR-070" and a non-empty ORC-#### code', () => {
+    for (const entry of ADR_070_INVARIANTS) {
+      expect(entry.adr).toBe('ADR-070');
+      expect(entry.code).toMatch(/^ORC-\d{3}$/);
+    }
+  });
+
+  it('every entry carries a non-empty name and description', () => {
+    for (const entry of ADR_070_INVARIANTS) {
+      expect(entry.name.length).toBeGreaterThan(0);
+      expect(entry.description.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('codes are unique across the ADR-070 enumeration', () => {
+    const codes = ADR_070_INVARIANTS.map((e) => e.code);
+    const uniqueCodes = new Set(codes);
+    expect(uniqueCodes.size).toBe(codes.length);
+  });
+});
+
+describe('ADR-070 ORC-012 — thin-agent dispatch gate (hard-enforced)', () => {
+  it('points at enforceThinAgent in packages/core/src/orchestration/thin-agent.ts', () => {
+    const entry = ADR_070_INVARIANTS.find((e) => e.code === HARD_ENFORCED_ORC_CODE);
+    expect(entry).toBeDefined();
+    expect(entry?.severity).toBe('error');
+    expect(entry?.runtimeGate).not.toBeNull();
+    expect(entry?.runtimeGate?.module).toBe(ORC_012_RUNTIME_GATE.module);
+    expect(entry?.runtimeGate?.functionName).toBe(ORC_012_RUNTIME_GATE.functionName);
+  });
+
+  it('is reachable via INVARIANTS_REGISTRY["ADR-070.ORC-012"]', () => {
+    const fromRegistry = INVARIANTS_REGISTRY['ADR-070.ORC-012'];
+    expect(fromRegistry).toBeDefined();
+    expect(fromRegistry?.runtimeGate?.functionName).toBe(ORC_012_RUNTIME_GATE.functionName);
+  });
+});
+
+describe('ADR-070 gap documentation — warning + runtimeGate:null entries', () => {
+  it('every warning entry with runtimeGate:null carries explanatory description text', () => {
+    const gaps: RegisteredInvariant[] = ADR_070_INVARIANTS.filter(
+      (e) => e.severity === 'warning' && e.runtimeGate === null,
+    );
+
+    // We expect at least the prompt-only ORC entries (ORC-001..003, 008, 009)
+    // plus the filed-but-unshipped depth/lead entries (ORC-010 / ORC-011).
+    expect(gaps.length).toBeGreaterThanOrEqual(5);
+
+    // Each gap MUST explain WHY no runtime gate exists. We probe for the
+    // documented surface markers ("UNENFORCED", "Prompt-time",
+    // "FILED but UNSHIPPED" — and the related verb forms). At least one of
+    // these phrases is required so the R6 doctor audit can rely on the
+    // description as a human-readable gap explanation.
+    const gapMarkers = ['UNENFORCED', 'prompt-time', 'Prompt-time', 'UNSHIPPED', 'unshipped'];
+    for (const entry of gaps) {
+      const hasMarker = gapMarkers.some((m) => entry.description.includes(m));
+      expect(hasMarker, `Entry ${entry.code} description is missing a gap marker`).toBe(true);
+      // Sanity check: description is substantive, not a stub.
+      expect(entry.description.length).toBeGreaterThanOrEqual(80);
+    }
+  });
+
+  it('filed-but-unshipped ORC-010 / ORC-011 reference their tracking tasks', () => {
+    const orc010 = ADR_070_INVARIANTS.find((e) => e.code === 'ORC-010');
+    const orc011 = ADR_070_INVARIANTS.find((e) => e.code === 'ORC-011');
+    expect(orc010?.description).toContain('T10278');
+    expect(orc011?.description).toContain('T10279');
+  });
+});
+
+describe('central registry — ADR-070 entries merged via index.ts', () => {
+  it('every ADR-070 entry is reachable via getInvariant("ADR-070.<code>")', () => {
+    for (const entry of ADR_070_INVARIANTS) {
+      const key = `ADR-070.${entry.code}`;
+      const fromRegistry = getInvariant(key);
+      expect(fromRegistry, `Missing registry entry for ${key}`).toBeDefined();
+      expect(fromRegistry?.code).toBe(entry.code);
+    }
+  });
+
+  it('getInvariantsByAdr("ADR-070") returns every entry in declaration order', () => {
+    const adr070 = getInvariantsByAdr('ADR-070');
+    expect(adr070).toHaveLength(ADR_070_INVARIANTS.length);
+    for (let i = 0; i < ADR_070_INVARIANTS.length; i++) {
+      expect(adr070[i]?.code).toBe(ADR_070_INVARIANTS[i]?.code);
+    }
+  });
+
+  it('does not collide with ADR-073 entries under the merged key space', () => {
+    const adr070Keys = ADR_070_INVARIANTS.map((e) => `ADR-070.${e.code}`);
+    const adr073Keys = getInvariantsByAdr('ADR-073').map((e) => `ADR-073.${e.code}`);
+    const intersection = adr070Keys.filter((k) => adr073Keys.includes(k));
+    expect(intersection).toEqual([]);
+  });
+});
+
+describe('ADR-070 severity:"error" entries — runtime gate invariant', () => {
+  it('every error-tier entry has a non-null runtimeGate (R4 T10338 strict gate)', () => {
+    const errorTier: RegisteredInvariant[] = ADR_070_INVARIANTS.filter(
+      (e) => e.severity === 'error',
+    );
+    expect(errorTier.length).toBeGreaterThan(0);
+    for (const entry of errorTier) {
+      expect(
+        entry.runtimeGate,
+        `Error-tier entry ${entry.code} missing runtimeGate`,
+      ).not.toBeNull();
+      if (entry.runtimeGate !== null) {
+        expect(entry.runtimeGate.module.length).toBeGreaterThan(0);
+        expect(entry.runtimeGate.functionName.length).toBeGreaterThan(0);
+      }
+    }
+  });
+});

package/src/invariants/__tests__/registry.test.ts

@@ -0,0 +1,136 @@
+/**
+ * Unit tests for the central invariants registry (T10335).
+ *
+ * The registry is the SSoT for system-wide invariants surfaced via the
+ * SG-SUBSTRATE-RECONCILIATION saga. Downstream R-tasks (R2 ORC codes,
+ * R4 CI gate, R5 release refactor, R6 doctor audit, R8 docs renderer)
+ * all key off the metadata shape asserted below.
+ *
+ * @epic T10327 — E-INVARIANT-REGISTRY-SSOT
+ * @saga T10326 — SG-SUBSTRATE-RECONCILIATION
+ * @task T10335 — R1: registry + ADR-073 I1-I8
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  E_SAGA_INVARIANT_VIOLATION_I3,
+  E_SAGA_INVARIANT_VIOLATION_I5,
+  E_SAGA_INVARIANT_VIOLATION_I7,
+} from '../../errors.js';
+import {
+  ADR_073_INVARIANTS,
+  getInvariant,
+  getInvariantsByAdr,
+  INVARIANTS_REGISTRY,
+  type RegisteredInvariant,
+} from '../index.js';
+
+/**
+ * Map from ADR-073 invariant code → expected LAFS error code in
+ * `packages/contracts/src/errors.ts`. R2/R4 will extend this mapping with
+ * ADR-070 ORC codes once they land — for now the registry only knows
+ * about the three saga-runtime guards.
+ *
+ * NOTE: I4 / I6 / I8 deliberately have no error code today — they are
+ * UNENFORCED warnings. The R4 CI gate (T10338) is the right home for the
+ * strict "every error has an error code" assertion; this test only
+ * validates the subset we already have wired.
+ */
+const ADR_073_ERROR_CODE_MAP: Record<string, string> = {
+  I3: E_SAGA_INVARIANT_VIOLATION_I3,
+  I5: E_SAGA_INVARIANT_VIOLATION_I5,
+  I7: E_SAGA_INVARIANT_VIOLATION_I7,
+};
+
+describe('INVARIANTS_REGISTRY — central registry shape', () => {
+  it('exposes at least 8 entries (ADR-073 I1-I8 baseline)', () => {
+    const entries = Object.values(INVARIANTS_REGISTRY);
+    expect(entries.length).toBeGreaterThanOrEqual(8);
+  });
+
+  it('registers all eight ADR-073 invariants under predictable keys', () => {
+    for (let i = 1; i <= 8; i++) {
+      const key = `ADR-073.I${i}`;
+      expect(INVARIANTS_REGISTRY[key]).toBeDefined();
+      expect(INVARIANTS_REGISTRY[key]?.adr).toBe('ADR-073');
+      expect(INVARIANTS_REGISTRY[key]?.code).toBe(`I${i}`);
+    }
+  });
+
+  it('every entry carries a non-empty name and description', () => {
+    for (const entry of Object.values(INVARIANTS_REGISTRY)) {
+      expect(entry.name.length).toBeGreaterThan(0);
+      expect(entry.description.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('every severity:"error" invariant has a non-null runtimeGate', () => {
+    const errorTier: RegisteredInvariant[] = Object.values(INVARIANTS_REGISTRY).filter(
+      (e) => e.severity === 'error',
+    );
+    expect(errorTier.length).toBeGreaterThan(0);
+    for (const entry of errorTier) {
+      expect(entry.runtimeGate).not.toBeNull();
+      // Triple is fully populated when present.
+      if (entry.runtimeGate !== null) {
+        expect(entry.runtimeGate.module.length).toBeGreaterThan(0);
+        expect(entry.runtimeGate.functionName.length).toBeGreaterThan(0);
+      }
+    }
+  });
+});
+
+describe('getInvariant — lookup helper', () => {
+  it('returns the ADR-073.I3 entry with the expected runtime guard', () => {
+    const i3 = getInvariant('ADR-073.I3');
+    expect(i3).toBeDefined();
+    expect(i3?.adr).toBe('ADR-073');
+    expect(i3?.code).toBe('I3');
+    expect(i3?.severity).toBe('error');
+    expect(i3?.runtimeGate?.functionName).toBe('assertSagaInvariantI3');
+    expect(i3?.runtimeGate?.module).toBe('packages/core/src/sagas/enforcement.ts');
+  });
+
+  it('returns undefined for an unregistered key', () => {
+    expect(getInvariant('ADR-999.X1')).toBeUndefined();
+  });
+});
+
+describe('getInvariantsByAdr — per-ADR enumeration', () => {
+  it('returns all eight ADR-073 invariants in declaration order', () => {
+    const adr073 = getInvariantsByAdr('ADR-073');
+    expect(adr073).toHaveLength(8);
+    expect(adr073.map((e) => e.code)).toEqual(['I1', 'I2', 'I3', 'I4', 'I5', 'I6', 'I7', 'I8']);
+  });
+
+  it('returns an empty array for an unknown ADR', () => {
+    expect(getInvariantsByAdr('ADR-DOES-NOT-EXIST')).toEqual([]);
+  });
+});
+
+describe('ADR_073_INVARIANTS — exported convenience binding', () => {
+  it('matches the entries surfaced via getInvariantsByAdr', () => {
+    expect(ADR_073_INVARIANTS).toHaveLength(8);
+    const enumerated = getInvariantsByAdr('ADR-073');
+    expect(enumerated).toHaveLength(ADR_073_INVARIANTS.length);
+    for (let i = 0; i < ADR_073_INVARIANTS.length; i++) {
+      expect(enumerated[i]?.code).toBe(ADR_073_INVARIANTS[i]?.code);
+    }
+  });
+});
+
+describe('error-code cross-reference (subset — R4 T10338 owns full strict gate)', () => {
+  it('every ADR-073 invariant with a runtimeGate has a known LAFS error code', () => {
+    // TODO(T10338 / R4): replace this targeted subset with a strict registry-wide
+    // assertion that walks every severity:"error" entry and confirms a matching
+    // LAFS error code (E_<ADR>_INVARIANT_VIOLATION_<CODE>) exists in errors.ts.
+    const adr073 = getInvariantsByAdr('ADR-073');
+    for (const entry of adr073) {
+      if (entry.runtimeGate !== null) {
+        const expected = ADR_073_ERROR_CODE_MAP[entry.code];
+        expect(expected).toBeDefined();
+        expect(typeof expected).toBe('string');
+      }
+    }
+  });
+});