@cleocode/contracts 2026.5.96 → 2026.5.98

package/src/__tests__/operation-def.test.ts

@@ -0,0 +1,185 @@
+/**
+ * Structural-equivalence tests for the dispatch operation-def contracts.
+ *
+ * These tests pin the field shapes of {@link OperationDef} and
+ * {@link Resolution} (and the underlying identity types {@link Gateway},
+ * {@link Tier}, {@link CanonicalDomain}) so accidental narrowing or
+ * widening triggers a compile-time failure during `tsc -b` in the CI
+ * gate.
+ *
+ * The compile-time assertions use the conditional-equality trick
+ * (`Equals<A, B>`) so any structural drift produces a TS2322 or TS2344
+ * at build time. The runtime `expect` shape sanity check below is a
+ * thin smoke verification that constructible literals satisfy each
+ * interface — it does NOT exercise behavior (these are pure type
+ * contracts with no runtime).
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9954 (Phase 0b)
+ */
+
+import { describe, expect, it } from 'vitest';
+import type { CanonicalDomain, Gateway, Tier } from '../dispatch/identity.js';
+import { CANONICAL_DOMAINS } from '../dispatch/identity.js';
+import type { OperationDef, Resolution } from '../dispatch/operation-def.js';
+import type { ParamDef } from '../operations/params.js';
+
+// ─── Compile-time structural-equality helpers ───────────────────────
+
+/** Resolve to `1` IFF `A` and `B` are mutually assignable; `2` otherwise. */
+type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? 1 : 2;
+
+/** Compile-time assert that `T` resolves to `1`. */
+type AssertEquals1<T extends 1> = T;
+
+// ─── Gateway shape pin ──────────────────────────────────────────────
+
+type _GatewayShape = 'query' | 'mutate';
+
+type _AssertGatewayPinned = AssertEquals1<Equals<Gateway, _GatewayShape>>;
+
+// ─── Tier shape pin ─────────────────────────────────────────────────
+
+type _TierShape = 0 | 1 | 2;
+
+type _AssertTierPinned = AssertEquals1<Equals<Tier, _TierShape>>;
+
+// ─── CanonicalDomain shape pin ──────────────────────────────────────
+// CanonicalDomain is derived from the runtime tuple CANONICAL_DOMAINS;
+// pinning the tuple element type guards against silent drift if someone
+// reorders the array but accidentally introduces a `string`-widened
+// element (e.g. `... as string[]`).
+
+type _CanonicalDomainShape = (typeof CANONICAL_DOMAINS)[number];
+
+type _AssertCanonicalDomainPinned = AssertEquals1<Equals<CanonicalDomain, _CanonicalDomainShape>>;
+
+// ─── OperationDef shape pin ─────────────────────────────────────────
+
+type _OperationDefShape = {
+  gateway: Gateway;
+  domain: CanonicalDomain;
+  operation: string;
+  description: string;
+  tier: Tier;
+  idempotent: boolean;
+  sessionRequired: boolean;
+  requiredParams: string[];
+  params?: ParamDef[];
+};
+
+type _AssertOperationDefPinned = AssertEquals1<Equals<OperationDef, _OperationDefShape>>;
+
+// ─── Resolution shape pin ───────────────────────────────────────────
+
+type _ResolutionShape = {
+  domain: CanonicalDomain;
+  operation: string;
+  def: OperationDef;
+};
+
+type _AssertResolutionPinned = AssertEquals1<Equals<Resolution, _ResolutionShape>>;
+
+// ─── Runtime constructibility smoke ─────────────────────────────────
+
+describe('dispatch/operation-def contracts', () => {
+  it('Gateway union covers exactly the 2 documented values', () => {
+    const values: Gateway[] = ['query', 'mutate'];
+    expect(values).toHaveLength(2);
+  });
+
+  it('Tier union covers exactly the 3 documented values', () => {
+    const tiers: Tier[] = [0, 1, 2];
+    expect(tiers).toHaveLength(3);
+  });
+
+  it('CANONICAL_DOMAINS is a non-empty readonly tuple', () => {
+    expect(CANONICAL_DOMAINS.length).toBeGreaterThan(0);
+    // T9954 — snapshot the current count so accidental additions/removals
+    // trip this test and force an explicit human review.
+    expect(CANONICAL_DOMAINS.length).toBe(22);
+  });
+
+  it('CANONICAL_DOMAINS contains the four sentinel newly-promoted domains', () => {
+    // Spot-check the canonical surface: T964 conduit, T1726 sentient/release,
+    // T9528 provenance, T9536 upgrade. Catches the most common drift where
+    // someone deletes one and breaks SDK consumers downstream.
+    expect(CANONICAL_DOMAINS).toContain('conduit');
+    expect(CANONICAL_DOMAINS).toContain('sentient');
+    expect(CANONICAL_DOMAINS).toContain('release');
+    expect(CANONICAL_DOMAINS).toContain('provenance');
+    expect(CANONICAL_DOMAINS).toContain('upgrade');
+  });
+
+  it('OperationDef is constructible with the canonical shape (no params field)', () => {
+    const def: OperationDef = {
+      gateway: 'query',
+      domain: 'tasks',
+      operation: 'show',
+      description: 'tasks.show (query)',
+      tier: 0,
+      idempotent: true,
+      sessionRequired: false,
+      requiredParams: ['taskId'],
+    };
+    expect(def.gateway).toBe('query');
+    expect(def.domain).toBe('tasks');
+    expect(def.params).toBeUndefined();
+  });
+
+  it('OperationDef is constructible with the optional params field populated', () => {
+    const def: OperationDef = {
+      gateway: 'mutate',
+      domain: 'tasks',
+      operation: 'add',
+      description: 'tasks.add (mutate)',
+      tier: 0,
+      idempotent: false,
+      sessionRequired: false,
+      requiredParams: ['title'],
+      params: [
+        {
+          name: 'title',
+          type: 'string',
+          required: true,
+          description: 'Title of the task',
+        },
+      ],
+    };
+    expect(def.params).toHaveLength(1);
+    expect(def.params?.[0].name).toBe('title');
+  });
+
+  it('Resolution wraps a domain + operation + def triple', () => {
+    const def: OperationDef = {
+      gateway: 'query',
+      domain: 'session',
+      operation: 'status',
+      description: 'session.status (query)',
+      tier: 0,
+      idempotent: true,
+      sessionRequired: false,
+      requiredParams: [],
+    };
+    const r: Resolution = {
+      domain: 'session',
+      operation: 'status',
+      def,
+    };
+    expect(r.domain).toBe('session');
+    expect(r.def).toBe(def);
+  });
+
+  // The five `_Assert…Pinned` aliases above will fail compilation if
+  // any shape drifts. The following references prevent unused-locals
+  // diagnostics from removing them.
+  it('compile-time pins are wired (no-op at runtime)', () => {
+    const pinned: [
+      _AssertGatewayPinned,
+      _AssertTierPinned,
+      _AssertCanonicalDomainPinned,
+      _AssertOperationDefPinned,
+      _AssertResolutionPinned,
+    ] = [1, 1, 1, 1, 1];
+    expect(pinned).toEqual([1, 1, 1, 1, 1]);
+  });
+});

package/src/__tests__/provenance.test.ts

@@ -0,0 +1,259 @@
+/**
+ * Structural-equivalence tests for the provenance graph contracts.
+ *
+ * These tests pin the literal shapes of the 16 provenance/release/BRAIN
+ * unions promoted in Phase 0c (T9955) so that accidental narrowing or
+ * widening produces a compile-time failure during `tsc -b` in the CI gate.
+ *
+ * The compile-time assertions use the conditional-equality trick
+ * (`Equals<A, B>`) so any structural drift produces a TS2322 or TS2344 at
+ * build time. The runtime `expect` shape sanity check below is a thin
+ * smoke verification that representative literals satisfy each union — it
+ * does NOT exercise behavior (these are pure type contracts with no
+ * runtime).
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9955 (Phase 0c)
+ */
+
+import { describe, expect, it } from 'vitest';
+import type {
+  BrainReleaseLinkType,
+  CommitConventionalType,
+  CommitFileChangeType,
+  CommitLinkKind,
+  CommitLinkSource,
+  PrLinkKind,
+  PrLinkSource,
+  PrState,
+  ReleaseArtifactType,
+  ReleaseChangeType,
+  ReleaseChannel,
+  ReleaseClassifiedBy,
+  ReleaseImpact,
+  ReleaseKind,
+  ReleaseScheme,
+  ReleaseStatus,
+} from '../provenance.js';
+
+// ─── Compile-time structural-equality helpers ───────────────────────
+
+/** Resolve to `1` IFF `A` and `B` are mutually assignable; `2` otherwise. */
+type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? 1 : 2;
+
+/** Compile-time assert that `T` resolves to `1`. */
+type AssertEquals1<T extends 1> = T;
+
+// ─── PrState pin ────────────────────────────────────────────────────
+
+type _PrStateShape = 'open' | 'closed' | 'merged';
+type _AssertPrStatePinned = AssertEquals1<Equals<PrState, _PrStateShape>>;
+
+// ─── CommitLinkKind pin ─────────────────────────────────────────────
+
+type _CommitLinkKindShape = 'implements' | 'fixes' | 'refactors' | 'tests' | 'docs' | 'reverts';
+type _AssertCommitLinkKindPinned = AssertEquals1<Equals<CommitLinkKind, _CommitLinkKindShape>>;
+
+// ─── ReleaseStatus pin (unified — admits both pipelines) ────────────
+
+type _ReleaseStatusShape =
+  | 'planned'
+  | 'pr-opened'
+  | 'pr-merged'
+  | 'published'
+  | 'reconciled'
+  | 'prepared'
+  | 'committed'
+  | 'tagged'
+  | 'pushed'
+  | 'rolled_back'
+  | 'failed'
+  | 'cancelled';
+type _AssertReleaseStatusPinned = AssertEquals1<Equals<ReleaseStatus, _ReleaseStatusShape>>;
+
+// ─── ReleaseChangeType pin (12-value taxonomy) ──────────────────────
+
+type _ReleaseChangeTypeShape =
+  | 'feature'
+  | 'enhancement'
+  | 'bug'
+  | 'hotfix'
+  | 'security'
+  | 'breaking'
+  | 'refactor'
+  | 'docs'
+  | 'chore'
+  | 'revert'
+  | 'deprecation'
+  | 'infrastructure';
+type _AssertReleaseChangeTypePinned = AssertEquals1<
+  Equals<ReleaseChangeType, _ReleaseChangeTypeShape>
+>;
+
+// ─── ReleaseArtifactType pin ────────────────────────────────────────
+
+type _ReleaseArtifactTypeShape =
+  | 'npm'
+  | 'cargo'
+  | 'docker'
+  | 'pypi'
+  | 'github-release'
+  | 'binary'
+  | 'github-tag';
+type _AssertReleaseArtifactTypePinned = AssertEquals1<
+  Equals<ReleaseArtifactType, _ReleaseArtifactTypeShape>
+>;
+
+// ─── BrainReleaseLinkType pin ───────────────────────────────────────
+
+type _BrainReleaseLinkTypeShape = 'approved-by' | 'documented-in' | 'derived-from' | 'observed-in';
+type _AssertBrainReleaseLinkTypePinned = AssertEquals1<
+  Equals<BrainReleaseLinkType, _BrainReleaseLinkTypeShape>
+>;
+
+// ─── Runtime constructibility smoke ─────────────────────────────────
+
+describe('provenance contracts', () => {
+  it('PrState union covers exactly the 3 GitHub PR states', () => {
+    const all: PrState[] = ['open', 'closed', 'merged'];
+    expect(all).toHaveLength(3);
+  });
+
+  it('PrLinkSource enumerates all 5 discovery sources', () => {
+    const all: PrLinkSource[] = ['pr-title', 'pr-body', 'branch-name', 'commit-trailer', 'manual'];
+    expect(all).toHaveLength(5);
+  });
+
+  it('PrLinkKind extends CommitLinkKind with the "tracks" addition', () => {
+    const commit: CommitLinkKind = 'implements';
+    const pr: PrLinkKind = commit; // every commit-link-kind is a valid pr-link-kind
+    expect(pr).toBe('implements');
+    const tracks: PrLinkKind = 'tracks';
+    expect(tracks).toBe('tracks');
+  });
+
+  it('CommitConventionalType enumerates the canonical CC prefixes plus "breaking"', () => {
+    const ccs: CommitConventionalType[] = [
+      'feat',
+      'fix',
+      'chore',
+      'docs',
+      'refactor',
+      'test',
+      'build',
+      'ci',
+      'perf',
+      'revert',
+      'breaking',
+    ];
+    expect(ccs).toHaveLength(11);
+    expect(ccs).toContain('breaking');
+  });
+
+  it('CommitLinkSource and CommitLinkKind are independent unions', () => {
+    const src: CommitLinkSource = 'commit-trailer';
+    const kind: CommitLinkKind = 'implements';
+    expect(src).toBe('commit-trailer');
+    expect(kind).toBe('implements');
+  });
+
+  it('CommitFileChangeType matches the git status letter codes', () => {
+    const codes: CommitFileChangeType[] = ['A', 'M', 'D', 'R', 'C'];
+    expect(codes).toHaveLength(5);
+  });
+
+  it('ReleaseScheme enumerates calver/semver/calver-suffix', () => {
+    const schemes: ReleaseScheme[] = ['calver', 'semver', 'calver-suffix'];
+    expect(schemes).toHaveLength(3);
+  });
+
+  it('ReleaseChannel enumerates the provenance-layer channels', () => {
+    const channels: ReleaseChannel[] = ['latest', 'beta', 'dev', 'hotfix'];
+    expect(channels).toHaveLength(4);
+  });
+
+  it('ReleaseKind enumerates regular/hotfix/prerelease', () => {
+    const kinds: ReleaseKind[] = ['regular', 'hotfix', 'prerelease'];
+    expect(kinds).toHaveLength(3);
+  });
+
+  it('ReleaseStatus admits BOTH new-pipeline and legacy-pipeline statuses', () => {
+    const newPipeline: ReleaseStatus[] = [
+      'planned',
+      'pr-opened',
+      'pr-merged',
+      'published',
+      'reconciled',
+    ];
+    const legacyPipeline: ReleaseStatus[] = ['prepared', 'committed', 'tagged', 'pushed'];
+    const terminals: ReleaseStatus[] = ['rolled_back', 'failed', 'cancelled'];
+    expect(newPipeline).toHaveLength(5);
+    expect(legacyPipeline).toHaveLength(4);
+    expect(terminals).toHaveLength(3);
+  });
+
+  it('ReleaseChangeType enumerates the 12 CLEO change types', () => {
+    const types: ReleaseChangeType[] = [
+      'feature',
+      'enhancement',
+      'bug',
+      'hotfix',
+      'security',
+      'breaking',
+      'refactor',
+      'docs',
+      'chore',
+      'revert',
+      'deprecation',
+      'infrastructure',
+    ];
+    expect(types).toHaveLength(12);
+  });
+
+  it('ReleaseImpact enumerates the 4 semver-bump assessments', () => {
+    const impacts: ReleaseImpact[] = ['major', 'minor', 'patch', 'none'];
+    expect(impacts).toHaveLength(4);
+  });
+
+  it('ReleaseClassifiedBy enumerates auto/manual/approved provenance', () => {
+    const provenance: ReleaseClassifiedBy[] = ['auto', 'manual', 'approved'];
+    expect(provenance).toHaveLength(3);
+  });
+
+  it('ReleaseArtifactType enumerates the 7 supported artifact archetypes', () => {
+    const types: ReleaseArtifactType[] = [
+      'npm',
+      'cargo',
+      'docker',
+      'pypi',
+      'github-release',
+      'binary',
+      'github-tag',
+    ];
+    expect(types).toHaveLength(7);
+  });
+
+  it('BrainReleaseLinkType enumerates the 4 BRAIN↔release semantics', () => {
+    const links: BrainReleaseLinkType[] = [
+      'approved-by',
+      'documented-in',
+      'derived-from',
+      'observed-in',
+    ];
+    expect(links).toHaveLength(4);
+  });
+
+  // The five `_Assert…Pinned` aliases above will fail compilation if any
+  // shape drifts. The following references prevent unused-locals
+  // diagnostics from removing them.
+  it('compile-time pins are wired (no-op at runtime)', () => {
+    const pinned: [
+      _AssertPrStatePinned,
+      _AssertCommitLinkKindPinned,
+      _AssertReleaseStatusPinned,
+      _AssertReleaseChangeTypePinned,
+      _AssertReleaseArtifactTypePinned,
+      _AssertBrainReleaseLinkTypePinned,
+    ] = [1, 1, 1, 1, 1, 1];
+    expect(pinned).toEqual([1, 1, 1, 1, 1, 1]);
+  });
+});

package/src/__tests__/scaffold-diagnostics.test.ts

@@ -0,0 +1,137 @@
+/**
+ * Structural-equivalence tests for the scaffold-diagnostics contracts.
+ *
+ * These tests pin the field shapes of {@link ScaffoldResult},
+ * {@link CheckStatus}, {@link CheckResult}, and {@link HookCheckResult}
+ * so accidental narrowing or widening triggers a compile-time failure
+ * during `tsc -b` in the CI gate.
+ *
+ * The compile-time assertions use the conditional-equality trick
+ * (`Equals<A, B>`) so any structural drift produces a TS2322 or TS2344
+ * at build time. The runtime `expect` shape sanity check below is a
+ * thin smoke verification that constructible literals satisfy each
+ * interface — it does NOT exercise behavior (these are pure type
+ * contracts with no runtime).
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 (Phase 0a)
+ */
+
+import { describe, expect, it } from 'vitest';
+import type {
+  CheckResult,
+  CheckStatus,
+  HookCheckResult,
+  ScaffoldResult,
+} from '../scaffold-diagnostics.js';
+
+// ─── Compile-time structural-equality helpers ───────────────────────
+
+/** Resolve to `1` IFF `A` and `B` are mutually assignable; `2` otherwise. */
+type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? 1 : 2;
+
+/** Compile-time assert that `T` resolves to `1`. */
+type AssertEquals1<T extends 1> = T;
+
+// ─── ScaffoldResult shape pin ───────────────────────────────────────
+
+type _ScaffoldResultShape = {
+  action: 'created' | 'repaired' | 'skipped';
+  path: string;
+  details?: string;
+};
+
+type _AssertScaffoldResultPinned = AssertEquals1<Equals<ScaffoldResult, _ScaffoldResultShape>>;
+
+// ─── CheckStatus shape pin ──────────────────────────────────────────
+
+type _CheckStatusShape = 'passed' | 'failed' | 'warning' | 'info';
+
+type _AssertCheckStatusPinned = AssertEquals1<Equals<CheckStatus, _CheckStatusShape>>;
+
+// ─── CheckResult shape pin ──────────────────────────────────────────
+
+type _CheckResultShape = {
+  id: string;
+  category: string;
+  status: CheckStatus;
+  message: string;
+  details: Record<string, unknown>;
+  fix: string | null;
+};
+
+type _AssertCheckResultPinned = AssertEquals1<Equals<CheckResult, _CheckResultShape>>;
+
+// ─── HookCheckResult shape pin ──────────────────────────────────────
+
+type _HookCheckResultShape = {
+  hook: string;
+  installed: boolean;
+  current: boolean;
+  sourcePath: string;
+  installedPath: string;
+};
+
+type _AssertHookCheckResultPinned = AssertEquals1<Equals<HookCheckResult, _HookCheckResultShape>>;
+
+// ─── Runtime constructibility smoke ─────────────────────────────────
+
+describe('scaffold-diagnostics contracts', () => {
+  it('ScaffoldResult is constructible with the canonical shape', () => {
+    const r: ScaffoldResult = { action: 'created', path: '/tmp/x' };
+    expect(r.action).toBe('created');
+    expect(r.path).toBe('/tmp/x');
+    expect(r.details).toBeUndefined();
+  });
+
+  it('ScaffoldResult accepts the optional details field', () => {
+    const r: ScaffoldResult = {
+      action: 'repaired',
+      path: '/tmp/y',
+      details: 'rewrote stale entry',
+    };
+    expect(r.details).toBe('rewrote stale entry');
+  });
+
+  it('CheckResult is constructible with the canonical shape', () => {
+    const r: CheckResult = {
+      id: 'cleo_structure',
+      category: 'scaffold',
+      status: 'passed',
+      message: 'All subdirs present',
+      details: { missing: [] },
+      fix: null,
+    };
+    expect(r.status).toBe('passed');
+    expect(r.fix).toBeNull();
+  });
+
+  it('CheckStatus union covers exactly the 4 documented values', () => {
+    const statuses: CheckStatus[] = ['passed', 'failed', 'warning', 'info'];
+    expect(statuses).toHaveLength(4);
+  });
+
+  it('HookCheckResult is constructible with the canonical shape', () => {
+    const r: HookCheckResult = {
+      hook: 'pre-commit',
+      installed: true,
+      current: false,
+      sourcePath: '/pkg/templates/git-hooks/pre-commit',
+      installedPath: '/proj/.git/hooks/pre-commit',
+    };
+    expect(r.installed).toBe(true);
+    expect(r.current).toBe(false);
+  });
+
+  // The four `_Assert…Pinned` aliases above will fail compilation if
+  // any shape drifts. The following references prevent unused-locals
+  // diagnostics from removing them.
+  it('compile-time pins are wired (no-op at runtime)', () => {
+    const pinned: [
+      _AssertScaffoldResultPinned,
+      _AssertCheckStatusPinned,
+      _AssertCheckResultPinned,
+      _AssertHookCheckResultPinned,
+    ] = [1, 1, 1, 1];
+    expect(pinned).toEqual([1, 1, 1, 1]);
+  });
+});

package/src/dispatch/identity.ts

@@ -0,0 +1,109 @@
+/**
+ * Dispatch identity contracts.
+ *
+ * Canonical home for the three primitive identity types every dispatch
+ * operation is keyed on:
+ *
+ *   - {@link Gateway}          — CQRS read vs write classification
+ *   - {@link Tier}             — progressive-disclosure tier (0/1/2)
+ *   - {@link CanonicalDomain}  — the closed set of dispatch domains
+ *
+ * Promoted to `@cleocode/contracts` in Phase 0b of the SG-ARCH-SOLID
+ * Saga (T9831 · E-CONTRACTS-FOUNDATION T9832 · T9954) alongside
+ * {@link OperationDef} / {@link Resolution}. Originally defined in
+ * `packages/cleo/src/dispatch/types.ts` (lines 16, 27, 58, 86). The
+ * `packages/cleo` definition is now a re-export shim — every consumer
+ * continues to compile unchanged.
+ *
+ * `CANONICAL_DOMAINS` remains the runtime SSoT — adding/removing a
+ * domain still requires editing the array here exactly as before.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9954 (Phase 0b)
+ */
+
+// ── Gateway ──────────────────────────────────────────────────────────
+
+/**
+ * CQRS gateway: read-only queries vs state-modifying mutations.
+ *
+ * Originally defined in `packages/cleo/src/dispatch/types.ts:16`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9954 (Phase 0b)
+ */
+export type Gateway = 'query' | 'mutate';
+
+// ── Tier ─────────────────────────────────────────────────────────────
+
+/**
+ * Progressive disclosure tier.
+ *
+ * - `0` — tasks + session (~80% of agents)
+ * - `1` — + memory + check (~15% of agents)
+ * - `2` — + pipeline + orchestrate + tools + admin + nexus (~5%)
+ *
+ * Originally defined in `packages/cleo/src/dispatch/types.ts:27`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9954 (Phase 0b)
+ */
+export type Tier = 0 | 1 | 2;
+
+// ── CanonicalDomain ──────────────────────────────────────────────────
+
+/**
+ * The closed set of dispatch canonical-domain names.
+ *
+ * T964: `conduit` promoted to first-class domain (supersedes ADR-042 Decision 1).
+ * CONDUIT is agent-to-agent messaging and is semantically disjoint from
+ * ORCHESTRATE (wave planning + spawn-prompt generation). The original
+ * "exactly 10 canonical domains" invariant that justified folding CONDUIT
+ * under ORCHESTRATE has been broken multiple times (intelligence, diagnostics,
+ * docs, playbook); promoting CONDUIT aligns registry with wire-format, CLI,
+ * and core module structure at zero behavior cost.
+ *
+ * T1726: `sentient` and `release` promoted to first-class domains. Both were
+ * reachable via the CLI and had registered DomainHandlers but were absent from
+ * CANONICAL_DOMAINS, making them invisible to SDK consumers via OPERATIONS.
+ *
+ * Originally defined in `packages/cleo/src/dispatch/types.ts:58`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9954 (Phase 0b)
+ */
+export const CANONICAL_DOMAINS = [
+  'tasks',
+  'session',
+  'memory',
+  'check',
+  'pipeline',
+  'orchestrate',
+  'tools',
+  'admin',
+  'nexus',
+  'sticky',
+  'intelligence',
+  'diagnostics',
+  'docs',
+  'playbook',
+  'conduit',
+  'sentient',
+  'release',
+  'llm',
+  // T9528: provenance-graph maintenance verbs (backfill, verify, repair).
+  'provenance',
+  // T9536: `cleo upgrade workflows` — re-render release-pipeline workflow
+  // templates + 3-way merge with `.workflow-overrides.yml`.
+  'upgrade',
+  // T9546/T9547: 'cleo worktree list/prune/force-unlock' — worktree lifecycle.
+  'worktree',
+  // T9973: 'cleo focus <id>' — single-envelope task orientation (8 calls → 1).
+  'focus',
+] as const;
+
+/**
+ * One of the canonical dispatch domain names.
+ *
+ * Derived as a string-literal union from {@link CANONICAL_DOMAINS} so
+ * adding/removing a domain in the array automatically updates the type.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9954 (Phase 0b)
+ */
+export type CanonicalDomain = (typeof CANONICAL_DOMAINS)[number];