@cleocode/contracts 2026.6.12 → 2026.6.13

package/src/llm/system-resolver.ts

@@ -1,11 +1,18 @@
 /**
- * SystemOfUse contract types for the `resolveLLMForSystem` chokepoint (E9).
+ * `SystemOfUseLabel` contract types for the `resolveLLMForSystem` chokepoint (E9).
  *
- * A "system of use" is the semantic label for the subsystem that is requesting
- * an LLM client — e.g. `'sentient'`, `'memory'`, `'task-executor'`. It is
- * a higher-level, stable identity that CLEO maps to a {@link RoleName} for
- * config resolution. This indirection insulates call-sites from the config
- * vocabulary (roles) and from model/provider churn.
+ * A "system of use label" is the flat, ergonomic vocabulary the E9 resolver
+ * accepts for the seven role-mapped background subsystems — e.g. `'sentient'`,
+ * `'memory'`, `'task-executor'`. It is a higher-level, stable identity that
+ * CLEO maps to a {@link RoleName} for config resolution. This indirection
+ * insulates call-sites from the config vocabulary (roles) and from
+ * model/provider churn.
+ *
+ * The richer, structured `{ kind, id }` taxonomy that covers the OTHER routing
+ * axes (orchestration tiers, tools, skills, cantbook nodes, spawn units) lives
+ * in {@link import('./system-of-use.js').SystemOfUse} (T11747). This label set
+ * is the flat resolver-input subset; both are kept in lock-step (the label set
+ * mirrors the `aux` axis plus `default`).
  *
  * `resolveLLMForSystem` is the single DRY chokepoint that the 4-resolver /
  * 3-picker sprawl will collapse onto (E9 · T11745).
@@ -16,15 +23,21 @@
  */
 
 import type { RoleName } from '../config.js';
+import type { RoleSystem } from './system-of-use.js';
 
 /**
- * Semantic label for a CLEO subsystem that requests an LLM client.
+ * Flat, ergonomic label for a CLEO background subsystem that requests an LLM
+ * client through the E9 resolver.
  *
- * Each `SystemOfUse` value maps to a canonical {@link RoleName} used by
+ * Each `SystemOfUseLabel` value maps to a canonical {@link RoleName} used by
  * `resolveLLMForSystem` for config and credential resolution. Subsystems
  * MUST declare their identity so the resolver can apply the correct
  * per-system overrides and audit trails.
  *
+ * For the full structured taxonomy (tools/skills/cantbook nodes/spawn units/
+ * orchestration tiers), see the discriminated
+ * {@link import('./system-of-use.js').SystemOfUse} descriptor (T11747).
+ *
  * ### Role mapping (static default; overridable via config `systemRoles`)
  *
  * | System            | Default role   |
@@ -40,7 +53,7 @@ import type { RoleName } from '../config.js';
  *
  * @task T11749
  */
-export type SystemOfUse =
+export type SystemOfUseLabel =
   | 'sentient'
   | 'memory'
   | 'task-executor'
@@ -51,13 +64,13 @@ export type SystemOfUse =
   | 'default';
 
 /**
- * Static mapping from {@link SystemOfUse} to the {@link RoleName} used for
+ * Static mapping from {@link SystemOfUseLabel} to the {@link RoleName} used for
  * config resolution. This is the canonical default; callers may override
  * individual systems via `config.llm.systemRoles[system]`.
  *
  * @task T11749
  */
-export const SYSTEM_ROLE_MAP: Readonly<Record<SystemOfUse, RoleName | null>> = {
+export const SYSTEM_ROLE_MAP: Readonly<Record<SystemOfUseLabel, RoleName | null>> = {
   sentient: 'consolidation',
   memory: 'extraction',
   'task-executor': 'judgement',
@@ -69,6 +82,28 @@ export const SYSTEM_ROLE_MAP: Readonly<Record<SystemOfUse, RoleName | null>> = {
   default: null,
 } as const;
 
+/**
+ * Input accepted by `resolveLLMForSystem()`.
+ *
+ * The chokepoint accepts EITHER:
+ *
+ *  - the flat, ergonomic {@link SystemOfUseLabel} for the role-mapped background
+ *    subsystems (`'sentient'`, `'memory'`, … — the original locked vocabulary), OR
+ *  - a structured {@link RoleSystem} descriptor (`{ kind: 'role', id: RoleName }`)
+ *    for a *direct* role resolution.
+ *
+ * The descriptor form makes the E9 equivalence
+ * `resolveLLMForRole(role) ≡ resolveLLMForSystem({ kind: 'role', id: role })`
+ * (T11750 · AC1) directly expressible at the chokepoint, so role callers can
+ * collapse onto the same single resolution path with ZERO duplicate resolution
+ * logic. Both forms funnel through the SAME `resolveLLMForRole` core inside
+ * `@cleocode/core`.
+ *
+ * @task T11750
+ * @epic T11745
+ */
+export type SystemResolverInput = SystemOfUseLabel | RoleSystem;
+
 /**
  * Options accepted by `resolveLLMForSystem()`.
  *

package/src/operations/__tests__/ensures-schema-registry.test.ts

@@ -0,0 +1,169 @@
+/**
+ * Tests for the ensures-schema Zod registry (T11762 ST-1 · T11900).
+ *
+ * Behavior-parity guard: every input the deleted bespoke validators
+ * (`validateDecompositionTaskTree` / `validateIvtrEvidenceOutput`,
+ * `packages/playbooks/src/runtime.ts:794-902`) REJECTED must still be rejected
+ * here, with the FIRST Zod issue message equal to the SUFFIX of the original
+ * violation string (the part after the `ensures.schema[<name>] on <nodeId>: `
+ * prefix that ST-2's runtime wrapper re-applies). Every input they ACCEPTED must
+ * still parse. The ACs call out: empty array, missing title, empty acceptance,
+ * `{}` evidence, numeric evidence.
+ *
+ * @task T11900
+ * @epic T11762
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  ENSURES_SCHEMA_REGISTRY,
+  type EnsuresSchemaSpec,
+  evidenceSchema,
+  LEGACY_PASSTHROUGH_SCHEMA_NAMES,
+  passthroughSchema,
+  taskTreeSchema,
+} from '../ensures-schema-registry.js';
+
+/** First Zod issue message for a failing parse (or `undefined` if it parsed). */
+function firstIssueMessage(schema: typeof taskTreeSchema, value: unknown): string | undefined {
+  const result = schema.safeParse(value);
+  return result.success ? undefined : result.error.issues[0]?.message;
+}
+
+describe('ensures-schema-registry — registry DATA', () => {
+  it('registers the two strict schemas plus every legacy passthrough name', () => {
+    // T11762 ST-2 (R1): the two strict ports (`task_tree`, `evidence`) PLUS the
+    // legacy starter `.cantbook` schema names — registered with passthrough so
+    // the fail-closed flip does not regress the shipped playbooks.
+    expect([...ENSURES_SCHEMA_REGISTRY.keys()].sort()).toEqual(
+      ['task_tree', 'evidence', ...LEGACY_PASSTHROUGH_SCHEMA_NAMES].sort(),
+    );
+  });
+
+  it('each strict spec carries name, contextKey (= name by default), and a schema', () => {
+    for (const name of ['task_tree', 'evidence'] as const) {
+      const spec = ENSURES_SCHEMA_REGISTRY.get(name) as EnsuresSchemaSpec;
+      expect(spec).toBeDefined();
+      expect(spec.name).toBe(name);
+      expect(spec.contextKey).toBe(name);
+      expect(typeof spec.schema.safeParse).toBe('function');
+    }
+  });
+
+  it('every legacy passthrough name is registered with the passthrough schema', () => {
+    // R1: passthrough accepts ANY value (including `undefined`) so the historical
+    // "silently skipped" behavior is preserved EXACTLY.
+    for (const name of LEGACY_PASSTHROUGH_SCHEMA_NAMES) {
+      const spec = ENSURES_SCHEMA_REGISTRY.get(name) as EnsuresSchemaSpec;
+      expect(spec).toBeDefined();
+      expect(spec.name).toBe(name);
+      expect(spec.schema).toBe(passthroughSchema);
+      expect(spec.schema.safeParse(undefined).success).toBe(true);
+      expect(spec.schema.safeParse({ anything: 1 }).success).toBe(true);
+      expect(spec.schema.safeParse(42).success).toBe(true);
+    }
+  });
+});
+
+describe('ensures-schema-registry — task_tree (ports validateDecompositionTaskTree)', () => {
+  it('accepts a minimal valid task tree', () => {
+    expect(taskTreeSchema.safeParse([{ title: 'Build X', acceptance: ['does X'] }]).success).toBe(
+      true,
+    );
+  });
+
+  it('accepts a tree with optional id/parentId/depends populated', () => {
+    expect(
+      taskTreeSchema.safeParse([
+        { title: 'Root', acceptance: ['ac1'], id: 'T1' },
+        { title: 'Child', acceptance: ['ac2', 'ac3'], id: 'T2', parentId: 'T1', depends: ['T1'] },
+      ]).success,
+    ).toBe(true);
+  });
+
+  it('rejects a non-array (parity: "task_tree must be a non-empty array")', () => {
+    expect(firstIssueMessage(taskTreeSchema, 'not-an-array')).toBe(
+      'task_tree must be a non-empty array',
+    );
+  });
+
+  it('rejects an EMPTY ARRAY (parity: empty-array message)', () => {
+    expect(firstIssueMessage(taskTreeSchema, [])).toBe(
+      'task_tree is an empty array — decomposition produced no tasks',
+    );
+  });
+
+  it('rejects a MISSING TITLE (parity: "title must be a non-empty string")', () => {
+    expect(firstIssueMessage(taskTreeSchema, [{ acceptance: ['ac1'] }])).toBe(
+      'title must be a non-empty string',
+    );
+  });
+
+  it('rejects a whitespace-only title (parity: same non-empty-title message)', () => {
+    expect(firstIssueMessage(taskTreeSchema, [{ title: '   ', acceptance: ['ac1'] }])).toBe(
+      'title must be a non-empty string',
+    );
+  });
+
+  it('rejects an EMPTY ACCEPTANCE array (parity: non-empty-acceptance message)', () => {
+    expect(firstIssueMessage(taskTreeSchema, [{ title: 'X', acceptance: [] }])).toBe(
+      'must have a non-empty acceptance array',
+    );
+  });
+
+  it('rejects an acceptance array with no non-empty strings (parity message)', () => {
+    expect(firstIssueMessage(taskTreeSchema, [{ title: 'X', acceptance: ['   ', ''] }])).toBe(
+      'acceptance array contains no non-empty strings',
+    );
+  });
+});
+
+describe('ensures-schema-registry — evidence (ports validateIvtrEvidenceOutput)', () => {
+  it('accepts a non-empty string', () => {
+    expect(evidenceSchema.safeParse('commit:abc123').success).toBe(true);
+  });
+
+  it('accepts a non-empty array', () => {
+    expect(evidenceSchema.safeParse(['atom']).success).toBe(true);
+  });
+
+  it('accepts an object with at least one key', () => {
+    expect(evidenceSchema.safeParse({ commit: 'abc' }).success).toBe(true);
+  });
+
+  it('rejects null/undefined (parity: must-be-present message)', () => {
+    expect(firstIssueMessage(evidenceSchema, null)).toBe(
+      'evidence must be present (non-null, non-undefined)',
+    );
+    expect(firstIssueMessage(evidenceSchema, undefined)).toBe(
+      'evidence must be present (non-null, non-undefined)',
+    );
+  });
+
+  it('rejects an empty / whitespace-only string (parity message)', () => {
+    expect(firstIssueMessage(evidenceSchema, '')).toBe('evidence string must not be empty');
+    expect(firstIssueMessage(evidenceSchema, '   ')).toBe('evidence string must not be empty');
+  });
+
+  it('rejects an empty array (parity message)', () => {
+    expect(firstIssueMessage(evidenceSchema, [])).toBe('evidence array must not be empty');
+  });
+
+  it('rejects an EMPTY OBJECT {} (parity: at-least-one-key message)', () => {
+    expect(firstIssueMessage(evidenceSchema, {})).toBe(
+      'evidence object must have at least one key (got {})',
+    );
+  });
+
+  it('rejects NUMERIC evidence (parity: wrong-type message with typeof)', () => {
+    expect(firstIssueMessage(evidenceSchema, 42)).toBe(
+      'evidence must be a string, array, or object (got number)',
+    );
+  });
+
+  it('rejects boolean evidence (parity: wrong-type message with typeof)', () => {
+    expect(firstIssueMessage(evidenceSchema, true)).toBe(
+      'evidence must be a string, array, or object (got boolean)',
+    );
+  });
+});

package/src/operations/ensures-schema-registry.ts

@@ -0,0 +1,260 @@
+/**
+ * Ensures-schema Zod registry — the cantbook `ensures.schema` name → Zod
+ * validator SSoT (T11762 ST-1 · Lane A).
+ *
+ * ## Why this exists
+ *
+ * The playbook runtime (`packages/playbooks/src/runtime.ts`) validates a node's
+ * post-merge `context` against a named shape declared as `ensures.schema:` in a
+ * `.cantbook`. Historically the runtime HARDCODED two bespoke validators
+ * (`validateDecompositionTaskTree` / `validateIvtrEvidenceOutput`) in an
+ * `if (schema === 'task_tree') … else if (=== 'evidence')` block, and silently
+ * SKIPPED any other schema name. T11762 replaces that hardcode with a
+ * registry-driven lookup so:
+ *
+ *   - `ensures.schema` names resolve to a registered Zod validator (AC1).
+ *   - the runtime no longer hardcodes `'task_tree'` / `'evidence'` (AC2).
+ *   - an unknown schema name FAILS CLOSED instead of silently passing.
+ *
+ * This module holds ONLY the Gate-10 (`lint-no-runtime-in-contracts`)-ALLOWED
+ * kinds: the Zod schema **const values**, the {@link EnsuresSchemaSpec} **type**,
+ * and the registry **data** (a `ReadonlyMap` value). The bodied accessors
+ * (`getEnsuresSchema` / `listEnsuresSchemaNames` / `defineEnsuresSchema`) live in
+ * `@cleocode/core` (`packages/core/src/dispatch/contracts/ensures-schema.ts`,
+ * ST-1b) because a `Map.get` helper is a net-new runtime function that the
+ * contracts-purity gate forbids in this leaf package.
+ *
+ * ## Message parity (behavior preservation)
+ *
+ * The Zod schemas are crafted so that — for every input the deleted bespoke
+ * validators rejected — the FIRST Zod issue message equals the SUFFIX of the
+ * original human-readable violation string (the part after the
+ * `ensures.schema[<name>] on <nodeId>: ` prefix). ST-2's runtime wrapper
+ * re-applies that prefix, so the end-to-end violation strings are unchanged. The
+ * ST-1 parity test asserts on these issue messages directly.
+ *
+ * ## Genkit-forward naming
+ *
+ * The registry surface is deliberately Genkit-shaped so a future Genkit
+ * `ai.defineSchema(name, zodSchema)` bridge (T11768) is a thin adapter over this
+ * SSoT, never a competing source.
+ *
+ * @packageDocumentation
+ * @module @cleocode/contracts/operations/ensures-schema-registry
+ *
+ * @epic T11762 — E-OUTPUT-SCHEMA-ENFORCEMENT
+ * @task T11900 — ST-1: ensures-schema Zod registry DATA + schemas
+ * @see validateDecompositionTaskTree — the ported bespoke task_tree validator
+ * @see validateIvtrEvidenceOutput — the ported bespoke evidence validator
+ */
+
+import { type ZodType, z } from 'zod';
+
+/**
+ * One registered `ensures.schema` entry: the Zod validator plus which playbook
+ * `context` key holds the value to validate.
+ *
+ * @public
+ */
+export interface EnsuresSchemaSpec {
+  /**
+   * The schema NAME used in `ensures.schema:` (e.g. `'task_tree'`, `'evidence'`).
+   */
+  readonly name: string;
+  /**
+   * The playbook `context` key whose value is validated. Defaults to {@link name}
+   * (matching today's `context['task_tree']` / `context['evidence']` convention).
+   */
+  readonly contextKey: string;
+  /**
+   * The Zod validator applied to `context[contextKey]`.
+   */
+  readonly schema: ZodType;
+}
+
+// ─── task_tree — ports validateDecompositionTaskTree (runtime.ts:794-855) ──────
+
+/**
+ * Zod schema for a single `task_tree` entry.
+ *
+ * Parity rules ported from `validateDecompositionTaskTree`:
+ *  - `title` must be a non-empty string (after trim).
+ *  - `acceptance` must be a non-empty array containing at least one non-empty
+ *    (after-trim) string.
+ *  - `id` / `parentId` / `depends` are optional and not hard-validated (the
+ *    bespoke validator was intentionally lenient on these).
+ *
+ * @remarks
+ * The `title` check is split so the message echoes the bespoke
+ * `entry[i].title must be a non-empty string` regardless of whether the field is
+ * absent, the wrong type, or whitespace-only.
+ */
+export const taskTreeEntrySchema: ZodType = z.object({
+  title: z
+    .string({ message: 'title must be a non-empty string' })
+    .refine((s) => s.trim().length > 0, { message: 'title must be a non-empty string' }),
+  acceptance: z
+    .array(z.unknown(), { message: 'must have a non-empty acceptance array' })
+    .min(1, { message: 'must have a non-empty acceptance array' })
+    .refine((arr) => arr.some((s) => typeof s === 'string' && s.trim().length > 0), {
+      message: 'acceptance array contains no non-empty strings',
+    }),
+  id: z.string().optional(),
+  parentId: z.string().optional(),
+  depends: z.array(z.string()).optional(),
+});
+
+/**
+ * Zod schema for the `task_tree` context value emitted by a RCASD decomposition
+ * node — a non-empty array of {@link taskTreeEntrySchema} entries.
+ *
+ * Parity: an empty array is rejected with `task_tree is an empty array …`; a
+ * non-array is rejected by Zod's base array type error.
+ *
+ * @public
+ */
+export const taskTreeSchema: ZodType = z
+  .array(taskTreeEntrySchema, { message: 'task_tree must be a non-empty array' })
+  .min(1, { message: 'task_tree is an empty array — decomposition produced no tasks' });
+
+// ─── evidence — ports validateIvtrEvidenceOutput (runtime.ts:873-902) ──────────
+
+/**
+ * Zod schema for the `evidence` context value emitted by an IVTR validation
+ * node.
+ *
+ * Parity rules ported from `validateIvtrEvidenceOutput`. Valid evidence is one
+ * of:
+ *  - a non-empty (after-trim) string,
+ *  - a non-empty array,
+ *  - an object with at least one key.
+ *
+ * `null` / `undefined`, the empty string, the empty array, the empty object, and
+ * any other primitive (number, boolean) are rejected — matching the bespoke
+ * validator exactly.
+ *
+ * @remarks
+ * A `z.union` of the three valid shapes would reject the SAME set of inputs, but
+ * collapses every rejection to a generic `"Invalid input"` union error. To
+ * preserve the bespoke validator's branch-specific messages (`evidence must be
+ * present …`, `evidence string must not be empty`, `evidence array must not be
+ * empty`, `evidence object must have at least one key (got {})`, `evidence must
+ * be a string, array, or object (got <type>)`), this schema replicates the
+ * original branch order in a single `superRefine`. The `superRefine` callback is
+ * an inline argument — NOT an exported bodied function/arrow — so it does not
+ * trip the Gate-10 contracts-purity lint.
+ *
+ * @public
+ */
+export const evidenceSchema: ZodType = z.unknown().superRefine((value, ctx) => {
+  if (value === null || value === undefined) {
+    ctx.addIssue({
+      code: 'custom',
+      message: 'evidence must be present (non-null, non-undefined)',
+    });
+    return;
+  }
+  if (typeof value === 'string') {
+    if (value.trim().length === 0) {
+      ctx.addIssue({ code: 'custom', message: 'evidence string must not be empty' });
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      ctx.addIssue({ code: 'custom', message: 'evidence array must not be empty' });
+    }
+    return;
+  }
+  if (typeof value === 'object') {
+    if (Object.keys(value).length === 0) {
+      ctx.addIssue({
+        code: 'custom',
+        message: 'evidence object must have at least one key (got {})',
+      });
+    }
+    return;
+  }
+  // Numbers, booleans, symbols, bigints, functions — not valid evidence shapes.
+  ctx.addIssue({
+    code: 'custom',
+    message: `evidence must be a string, array, or object (got ${typeof value})`,
+  });
+});
+
+// ─── passthrough — legacy starter `ensures.schema` names (R1 fail-closed) ──────
+
+/**
+ * Passthrough validator that accepts ANY value (including `undefined`).
+ *
+ * Used to register the legacy `ensures.schema` names already declared in the
+ * shipped starter `.cantbook` files ({@link LEGACY_PASSTHROUGH_SCHEMA_NAMES}).
+ *
+ * @remarks
+ * Before T11762, the runtime hardcoded ONLY `task_tree` / `evidence` and
+ * SILENTLY SKIPPED every other `ensures.schema` name. ST-2 flips that to
+ * fail-closed: an UNREGISTERED name is now a contract violation. To avoid
+ * regressing the in-repo starter playbooks (`release` / `rcasd` / `ivtr`),
+ * which declare a dozen descriptive schema names that were never actually
+ * shape-checked, each such name is registered here with this passthrough
+ * schema — preserving their historical "always pass" behavior EXACTLY while
+ * still failing-closed for genuinely-unknown names (Risk R1). Tightening any of
+ * these into a real shape is a follow-up; the name is the SSoT anchor.
+ *
+ * @public
+ */
+export const passthroughSchema: ZodType = z.unknown();
+
+/**
+ * The legacy `ensures.schema` names declared in the shipped starter
+ * `.cantbook` files that were SILENTLY SKIPPED pre-T11762. Registered with
+ * {@link passthroughSchema} so the fail-closed flip (ST-2) does not regress
+ * them. Kept as exported DATA so the parity test can assert the exact set.
+ *
+ * @public
+ */
+export const LEGACY_PASSTHROUGH_SCHEMA_NAMES: readonly string[] = [
+  // release.cantbook
+  'version_bump_report',
+  'changelog_entry',
+  'publish_report',
+  // rcasd.cantbook
+  'research_summary',
+  'consensus_decision',
+  'architecture_plan',
+  'specification_document',
+  // ivtr.cantbook
+  'implementation_diff',
+  'validation_report',
+  'audit_report',
+  'test_report',
+  'release_confirmation',
+];
+
+/**
+ * The ensures-schema registry DATA — a `ReadonlyMap` from `ensures.schema` name
+ * to its {@link EnsuresSchemaSpec}.
+ *
+ * This is a VALUE (data), not a bodied function, so it is Gate-10-safe in the
+ * `@cleocode/contracts` leaf package. The bodied accessor layer in
+ * `@cleocode/core` (ST-1b) reads this map.
+ *
+ * Two strict entries (`task_tree`, `evidence`) port the deleted bespoke
+ * validators; the remaining entries are the legacy starter names
+ * ({@link LEGACY_PASSTHROUGH_SCHEMA_NAMES}) registered with
+ * {@link passthroughSchema} so the ST-2 fail-closed flip does not regress the
+ * shipped playbooks (Risk R1).
+ *
+ * @public
+ */
+export const ENSURES_SCHEMA_REGISTRY: ReadonlyMap<string, EnsuresSchemaSpec> = new Map<
+  string,
+  EnsuresSchemaSpec
+>([
+  ['task_tree', { name: 'task_tree', contextKey: 'task_tree', schema: taskTreeSchema }],
+  ['evidence', { name: 'evidence', contextKey: 'evidence', schema: evidenceSchema }],
+  ...LEGACY_PASSTHROUGH_SCHEMA_NAMES.map((name): [string, EnsuresSchemaSpec] => [
+    name,
+    { name, contextKey: name, schema: passthroughSchema },
+  ]),
+]);