@cleocode/contracts 2026.6.12 → 2026.6.13

package/dist/llm/system-of-use.js

@@ -0,0 +1,238 @@
+/**
+ * `SystemOfUse` taxonomy — the structured identity of every CLEO subsystem that
+ * may request an LLM through the E9 chokepoint (`resolveLLMForSystem`).
+ *
+ * ## Why a discriminated descriptor (the hermes `_AUX_TASKS` analog)
+ *
+ * The first cut of the E9 chokepoint (T11749) accepted a flat string-literal
+ * label ({@link SystemOfUseLabel} — `'sentient' | 'memory' | …`). That covered
+ * the seven role-mapped background subsystems but had no room for the OTHER
+ * axes CLEO routes LLMs along:
+ *
+ *   - **orchestration tiers** (`frontier`/`standard`/`fast`/`local`) — the
+ *     capability lane a delegated turn runs in, independent of any role;
+ *   - **tools / skills** — atomic tool primitives and `ct-*` skills that each
+ *     may pin a model (the hermes `_AUX_TASKS` registry: one entry per named
+ *     auxiliary task, each with its own provider/model binding);
+ *   - **cantbook nodes** — per-node model selection inside a `.cantbook` flow;
+ *   - **spawn units** — orchestrator-spawned worker agents that resolve their
+ *     own LLM.
+ *
+ * `SystemOfUse` is the discriminated `{ kind, id }` descriptor that unifies all
+ * of these axes under ONE identity type. {@link BUILTIN_SYSTEMS_OF_USE} is the
+ * static registry of the well-known systems (orchestration tiers + the seven
+ * {@link RoleName}s + the auxiliary systems); `tool:` / `skill:` / `cantbook:` /
+ * `spawn-unit:` keys are OPEN — any runtime id is a valid `SystemOfUse` of the
+ * corresponding kind without a registry edit (see {@link OPEN_SYSTEM_KEY_PREFIXES}).
+ *
+ * ## Relationship to the resolver input
+ *
+ * This descriptor is the *taxonomy / identity* layer. The E9 resolver
+ * (`resolveLLMForSystem`) still accepts the ergonomic flat {@link SystemOfUseLabel}
+ * for the seven role-mapped background subsystems (its locked contract); this
+ * file is the SSoT that label set is derived against ({@link AUX_SYSTEM_IDS}),
+ * and the home of the richer descriptor that profile-axis routing (tiers,
+ * tools, skills, cantbook nodes, spawn units) keys off.
+ *
+ * Contracts-purity: this module is **types + `as const` DATA + type guards**
+ * only — no runtime logic (Gate 10 · T11418). The runtime encode/decode for the
+ * open-axis string keys (`parseSystemKey` / `formatSystemKey`) is intentionally
+ * NOT defined here; it lives in `@cleocode/core` so this package stays type-only
+ * (this module exposes only the {@link OPEN_SYSTEM_KEY_PREFIXES} DATA those
+ * helpers read).
+ *
+ * @module llm/system-of-use
+ * @task T11747
+ * @epic T11745
+ */
+// ---------------------------------------------------------------------------
+// Closed-axis value SSoTs (the type↔value mirrors)
+// ---------------------------------------------------------------------------
+/**
+ * Value-level SSoT for the seven {@link RoleName}s.
+ *
+ * The `RoleName` *type* lives in `config.ts`; this `as const` tuple is the
+ * single iterable VALUE mirror used to build the registry (and any other
+ * `for (const role of ROLE_SYSTEM_IDS)` loop) so the role axis is enumerated
+ * from ONE place. A compile-time `satisfies readonly RoleName[]` keeps it
+ * locked to the type — adding a role to `RoleName` without extending this tuple
+ * is a type error.
+ *
+ * @task T11747
+ */
+export const ROLE_SYSTEM_IDS = [
+    'extraction',
+    'consolidation',
+    'derivation',
+    'hygiene',
+    'judgement',
+    'plugin',
+    'compression',
+];
+/**
+ * Value-level SSoT for the user-facing, *enumerable* background {@link RoleName}s
+ * — the set `cleo llm whoami` reports and `cleo llm profile` accepts.
+ *
+ * This is the proper subset of {@link ROLE_SYSTEM_IDS} that excludes the two
+ * internal sandbox/utility roles (`plugin`, `compression`): they are resolved
+ * by code paths (plugin-scoped single-turn calls, context compression) rather
+ * than configured per-call by users, so they are intentionally NOT enumerated
+ * by the `whoami` / `profile` CLI surface.
+ *
+ * Sourcing the `cli-ops.ts` role list from THIS one tuple (instead of a
+ * duplicated inline array) is the AC3 "ALL_ROLES from one SSoT" requirement
+ * (T11750): the type-checker's `satisfies readonly RoleName[]` keeps every id
+ * locked to {@link RoleName}, so the enumerable set can never silently drift
+ * from the config vocabulary.
+ *
+ * @task T11750
+ * @epic T11745
+ */
+export const WHOAMI_ROLE_IDS = [
+    'extraction',
+    'consolidation',
+    'derivation',
+    'hygiene',
+    'judgement',
+];
+/**
+ * Value-level SSoT for the four orchestration capability tiers. Mirrors the
+ * {@link ProviderTier} type, most→least capable.
+ *
+ * @task T11747
+ */
+export const ORCHESTRATION_TIER_IDS = [
+    'frontier',
+    'standard',
+    'fast',
+    'local',
+];
+/**
+ * Value-level SSoT for the auxiliary subsystem ids (the hermes `_AUX_TASKS`
+ * key set). These are the stable, code-referenced background subsystems CLEO
+ * resolves an LLM for outside the role/tier/tool axes.
+ *
+ * The seven role-mapped resolver labels in {@link SystemOfUseLabel} are derived
+ * from this set plus `default` — keeping the flat resolver vocabulary and the
+ * structured taxonomy in lock-step.
+ *
+ * @task T11747
+ */
+export const AUX_SYSTEM_IDS = [
+    /** Dream-cycle / consolidation subsystem (BRAIN sentient layer). */
+    'sentient',
+    /** BRAIN memory extraction subsystem. */
+    'memory',
+    /** Task-executor judgement subsystem. */
+    'task-executor',
+    /** BRAIN deriver subsystem. */
+    'deriver',
+    /** Hygiene-scan subsystem. */
+    'hygiene',
+    /** Plugin-scoped single-turn calls. */
+    'plugin',
+    /** Context-compression / summarization subsystem. */
+    'compression',
+    /** Decision conflict-validator (ADR write-gate). */
+    'decision-validator',
+    /** Title / summary generation (cheap aux tier). */
+    'title-generation',
+    /** Embedding generation for vector retrieval. */
+    'embedding',
+];
+// ---------------------------------------------------------------------------
+// Open-axis runtime key prefixes
+// ---------------------------------------------------------------------------
+/**
+ * The four OPEN {@link SystemOfUseKind}s and the string-key prefix each is
+ * encoded with for transport across string-only boundaries (config keys, CLI
+ * args, audit logs). E.g. `{ kind: 'tool', id: 'web-search' }` ↔ `'tool:web-search'`.
+ *
+ * Declared as DATA so encode/decode never branches on a hardcoded prefix —
+ * `@cleocode/core` reads this map (Gate 10 keeps the runtime split out).
+ *
+ * @task T11747
+ */
+export const OPEN_SYSTEM_KEY_PREFIXES = {
+    tool: 'tool:',
+    skill: 'skill:',
+    'cantbook-node': 'cantbook:',
+    'spawn-unit': 'spawn-unit:',
+};
+// ---------------------------------------------------------------------------
+// BUILTIN_SYSTEMS_OF_USE registry
+// ---------------------------------------------------------------------------
+/**
+ * Static registry of every well-known (closed-axis) {@link SystemOfUse}: the
+ * four orchestration tiers, the seven {@link RoleName}s, and the ~10 auxiliary
+ * subsystems — the hermes `_AUX_TASKS` analog as a single typed table.
+ *
+ * Open-axis systems (`tool:`/`skill:`/`cantbook:`/`spawn-unit:`) are NOT listed
+ * here — they are valid without a registry edit (see {@link OPEN_SYSTEM_KEY_PREFIXES}).
+ *
+ * Built by spreading the three closed-axis value SSoTs so the registry can
+ * never drift from {@link ROLE_SYSTEM_IDS} / {@link ORCHESTRATION_TIER_IDS} /
+ * {@link AUX_SYSTEM_IDS}.
+ *
+ * @task T11747
+ * @epic T11745
+ */
+export const BUILTIN_SYSTEMS_OF_USE = [
+    ...ORCHESTRATION_TIER_IDS.map((id) => ({ kind: 'orchestration', id })),
+    ...ROLE_SYSTEM_IDS.map((id) => ({ kind: 'role', id })),
+    ...AUX_SYSTEM_IDS.map((id) => ({ kind: 'aux', id })),
+];
+// ---------------------------------------------------------------------------
+// Type guards (contracts-pure — Gate 10 allows `v is T` guards)
+// ---------------------------------------------------------------------------
+/**
+ * Type guard: is `value` a {@link SystemOfUse} descriptor (a `{ kind, id }`
+ * object whose `kind` is a known {@link SystemOfUseKind})?
+ *
+ * Structural-only — does NOT assert that closed-axis ids are registered (use
+ * {@link isBuiltinSystemOfUse} for that); an open-axis or as-yet-unregistered
+ * id still passes.
+ *
+ * @param value - The candidate value.
+ * @returns `true` when `value` is shaped like a {@link SystemOfUse}.
+ * @task T11747
+ */
+export function isSystemOfUse(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    if (typeof v.id !== 'string')
+        return false;
+    return (v.kind === 'role' ||
+        v.kind === 'orchestration' ||
+        v.kind === 'aux' ||
+        v.kind === 'tool' ||
+        v.kind === 'skill' ||
+        v.kind === 'cantbook-node' ||
+        v.kind === 'spawn-unit');
+}
+/**
+ * Type guard: is `value` a closed-axis {@link SystemOfUse} present in
+ * {@link BUILTIN_SYSTEMS_OF_USE} (an exact `kind`+`id` match)?
+ *
+ * @param value - The candidate value.
+ * @returns `true` when `value` is a registered builtin system-of-use.
+ * @task T11747
+ */
+export function isBuiltinSystemOfUse(value) {
+    if (!isSystemOfUse(value))
+        return false;
+    return BUILTIN_SYSTEMS_OF_USE.some((s) => s.kind === value.kind && s.id === value.id);
+}
+/**
+ * Type guard: is `kind` an OPEN-axis {@link OpenSystemKind} (one whose ids are
+ * encoded with an {@link OPEN_SYSTEM_KEY_PREFIXES} prefix)?
+ *
+ * @param kind - The kind discriminant to test.
+ * @returns `true` for `tool` / `skill` / `cantbook-node` / `spawn-unit`.
+ * @task T11747
+ */
+export function isOpenSystemKind(kind) {
+    return kind === 'tool' || kind === 'skill' || kind === 'cantbook-node' || kind === 'spawn-unit';
+}
+//# sourceMappingURL=system-of-use.js.map

package/dist/llm/system-of-use.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-of-use.js","sourceRoot":"","sources":["../../src/llm/system-of-use.ts"],"names":[],"mappings":"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"}

package/dist/llm/system-resolver.d.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).
@@ -15,14 +22,20 @@
  * @epic T11745
  */
 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   |
@@ -38,15 +51,36 @@ import type { RoleName } from '../config.js';
  *
  * @task T11749
  */
-export type SystemOfUse = 'sentient' | 'memory' | 'task-executor' | 'deriver' | 'hygiene' | 'plugin' | 'compression' | 'default';
+export type SystemOfUseLabel = 'sentient' | 'memory' | 'task-executor' | 'deriver' | 'hygiene' | 'plugin' | 'compression' | '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 declare const SYSTEM_ROLE_MAP: Readonly<Record<SystemOfUse, RoleName | null>>;
+export declare const SYSTEM_ROLE_MAP: Readonly<Record<SystemOfUseLabel, RoleName | null>>;
+/**
+ * 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/dist/llm/system-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"system-resolver.d.ts","sourceRoot":"","sources":["../../src/llm/system-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,WAAW,GACnB,UAAU,GACV,QAAQ,GACR,eAAe,GACf,SAAS,GACT,SAAS,GACT,QAAQ,GACR,aAAa,GACb,SAAS,CAAC;AAEd;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,QAAQ,GAAG,IAAI,CAAC,CAUjE,CAAC;AAEX;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,QAAQ,CAAC;IAExB;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B"}
+{"version":3,"file":"system-resolver.d.ts","sourceRoot":"","sources":["../../src/llm/system-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,MAAM,gBAAgB,GACxB,UAAU,GACV,QAAQ,GACR,eAAe,GACf,SAAS,GACT,SAAS,GACT,QAAQ,GACR,aAAa,GACb,SAAS,CAAC;AAEd;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,QAAQ,GAAG,IAAI,CAAC,CAUtE,CAAC;AAEX;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,GAAG,UAAU,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,QAAQ,CAAC;IAExB;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B"}

package/dist/llm/system-resolver.js

@@ -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).
@@ -15,7 +22,7 @@
  * @epic T11745
  */
 /**
- * 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]`.
  *

package/dist/llm/system-resolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"system-resolver.js","sourceRoot":"","sources":["../../src/llm/system-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAqCH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAmD;IAC7E,QAAQ,EAAE,eAAe;IACzB,MAAM,EAAE,YAAY;IACpB,eAAe,EAAE,WAAW;IAC5B,OAAO,EAAE,YAAY;IACrB,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;IAChB,WAAW,EAAE,aAAa;IAC1B,qEAAqE;IACrE,OAAO,EAAE,IAAI;CACL,CAAC"}
+{"version":3,"file":"system-resolver.js","sourceRoot":"","sources":["../../src/llm/system-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AA2CH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAwD;IAClF,QAAQ,EAAE,eAAe;IACzB,MAAM,EAAE,YAAY;IACpB,eAAe,EAAE,WAAW;IAC5B,OAAO,EAAE,YAAY;IACrB,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;IAChB,WAAW,EAAE,aAAa;IAC1B,qEAAqE;IACrE,OAAO,EAAE,IAAI;CACL,CAAC"}

package/dist/operations/__tests__/ensures-schema-registry.test.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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
+ */
+export {};
+//# sourceMappingURL=ensures-schema-registry.test.d.ts.map

package/dist/operations/__tests__/ensures-schema-registry.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensures-schema-registry.test.d.ts","sourceRoot":"","sources":["../../../src/operations/__tests__/ensures-schema-registry.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/operations/__tests__/ensures-schema-registry.test.js

@@ -0,0 +1,113 @@
+/**
+ * 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, 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, value) {
+    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']) {
+            const spec = ENSURES_SCHEMA_REGISTRY.get(name);
+            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);
+            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)');
+    });
+});
+//# sourceMappingURL=ensures-schema-registry.test.js.map

package/dist/operations/__tests__/ensures-schema-registry.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensures-schema-registry.test.js","sourceRoot":"","sources":["../../../src/operations/__tests__/ensures-schema-registry.test.ts"],"names":[],"mappings":"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"}