@cleocode/contracts 2026.5.121 → 2026.5.122

package/src/__tests__/validator-types.test.ts

@@ -0,0 +1,359 @@
+/**
+ * Type-level and runtime shape tests for T10510 Validator role contracts.
+ *
+ * Covers the AgentRole enum extension and the four envelope types
+ * (`ValidatorFinding`, `ValidatorAttestation`, `ValidatorRejection`,
+ * `ValidatorVerdict`) plus their Zod schemas and type guards.
+ *
+ * @task T10510
+ * @epic T10383 (E-VALIDATOR-ROLE)
+ * @saga T10377 (SG-IVTR-AC-BINDING)
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  AGENT_ROLES,
+  type AgentRole,
+  isAgentRole,
+  isValidatorAttestation,
+  isValidatorRejection,
+  isValidatorVerdict,
+  VALIDATOR_ID_REGEX,
+  type ValidatorAttestation,
+  type ValidatorFinding,
+  type ValidatorRejection,
+  type ValidatorVerdict,
+  validatorAttestationSchema,
+  validatorFindingSchema,
+  validatorRejectionSchema,
+  validatorVerdictSchema,
+} from '../validator/index.js';
+
+// ============================================================================
+// Test fixtures
+// ============================================================================
+
+const NOW = '2026-05-24T12:00:00Z';
+
+const passFinding: ValidatorFinding = {
+  acId: '11111111-1111-4111-8111-111111111111',
+  status: 'pass',
+  reasoning: 'AC satisfied — implementation matches spec',
+  checkedAt: NOW,
+};
+
+const failFinding: ValidatorFinding = {
+  acId: '22222222-2222-4222-8222-222222222222',
+  status: 'fail',
+  reasoning: 'Missing error handling for the null branch',
+  evidenceRefs: ['src/foo.ts:42', 'tests/foo.test.ts:17'],
+  checkedAt: NOW,
+};
+
+const inconclusiveFinding: ValidatorFinding = {
+  acId: '33333333-3333-4333-8333-333333333333',
+  status: 'inconclusive',
+  reasoning: 'Cannot reproduce the claimed test — file not present',
+  checkedAt: NOW,
+};
+
+// ============================================================================
+// AgentRole enum
+// ============================================================================
+
+describe('AgentRole enum (T10510)', () => {
+  it('contains the four canonical roles', () => {
+    expect(AGENT_ROLES).toEqual(['orchestrator', 'lead', 'worker', 'validator']);
+  });
+
+  it('AGENT_ROLES is a readonly tuple of length 4', () => {
+    // `as const` is a compile-time readonly marker — there is no runtime
+    // freeze. The TS type guard below ensures mutation attempts are rejected
+    // by the compiler; runtime length is the structural invariant.
+    expect(AGENT_ROLES.length).toBe(4);
+    // @ts-expect-error — readonly tuple disallows .push at the type level.
+    AGENT_ROLES.push;
+  });
+
+  it('AgentRole type compiles for all four values', () => {
+    const roles: AgentRole[] = ['orchestrator', 'lead', 'worker', 'validator'];
+    expect(roles).toHaveLength(4);
+  });
+
+  it('isAgentRole accepts canonical values', () => {
+    for (const r of AGENT_ROLES) {
+      expect(isAgentRole(r)).toBe(true);
+    }
+  });
+
+  it('isAgentRole rejects unknown strings and non-strings', () => {
+    expect(isAgentRole('subagent')).toBe(false);
+    expect(isAgentRole('Validator')).toBe(false);
+    expect(isAgentRole('')).toBe(false);
+    expect(isAgentRole(undefined)).toBe(false);
+    expect(isAgentRole(null)).toBe(false);
+    expect(isAgentRole(42)).toBe(false);
+    expect(isAgentRole({})).toBe(false);
+  });
+});
+
+// ============================================================================
+// VALIDATOR_ID_REGEX
+// ============================================================================
+
+describe('VALIDATOR_ID_REGEX (T10510)', () => {
+  it('accepts canonical validator agentIds', () => {
+    expect(VALIDATOR_ID_REGEX.test('validator-prime')).toBe(true);
+    expect(VALIDATOR_ID_REGEX.test('validator-sec-001')).toBe(true);
+    expect(VALIDATOR_ID_REGEX.test('validator-a')).toBe(true);
+    expect(VALIDATOR_ID_REGEX.test('validator-9-test')).toBe(true);
+  });
+
+  it('rejects malformed validator agentIds', () => {
+    expect(VALIDATOR_ID_REGEX.test('validator-')).toBe(false);
+    expect(VALIDATOR_ID_REGEX.test('Validator-prime')).toBe(false);
+    expect(VALIDATOR_ID_REGEX.test('validator-Prime')).toBe(false);
+    expect(VALIDATOR_ID_REGEX.test('worker-prime')).toBe(false);
+    expect(VALIDATOR_ID_REGEX.test('validator-_x')).toBe(false);
+  });
+});
+
+// ============================================================================
+// ValidatorFinding
+// ============================================================================
+
+describe('ValidatorFinding (T10510)', () => {
+  it('accepts pass / fail / inconclusive', () => {
+    expect(validatorFindingSchema.safeParse(passFinding).success).toBe(true);
+    expect(validatorFindingSchema.safeParse(failFinding).success).toBe(true);
+    expect(validatorFindingSchema.safeParse(inconclusiveFinding).success).toBe(true);
+  });
+
+  it('rejects empty acId', () => {
+    const bad = { ...passFinding, acId: '' };
+    expect(validatorFindingSchema.safeParse(bad).success).toBe(false);
+  });
+
+  it('rejects empty reasoning', () => {
+    const bad = { ...passFinding, reasoning: '' };
+    expect(validatorFindingSchema.safeParse(bad).success).toBe(false);
+  });
+
+  it('rejects unknown status value', () => {
+    const bad = { ...passFinding, status: 'warn' };
+    expect(validatorFindingSchema.safeParse(bad).success).toBe(false);
+  });
+
+  it('accepts optional evidenceRefs array', () => {
+    const withRefs = { ...passFinding, evidenceRefs: ['a', 'b'] };
+    expect(validatorFindingSchema.safeParse(withRefs).success).toBe(true);
+  });
+});
+
+// ============================================================================
+// ValidatorAttestation
+// ============================================================================
+
+describe('ValidatorAttestation (T10510)', () => {
+  const baseAttestation: ValidatorAttestation = {
+    verdict: 'attest',
+    taskId: 'T10510',
+    validatorId: 'validator-prime',
+    findings: [passFinding],
+    attestedAt: NOW,
+    schemaVersion: '1',
+  };
+
+  it('accepts a well-formed attestation with all passes', () => {
+    expect(validatorAttestationSchema.safeParse(baseAttestation).success).toBe(true);
+  });
+
+  it('accepts optional summary', () => {
+    const withSummary = { ...baseAttestation, summary: 'All ACs verified' };
+    expect(validatorAttestationSchema.safeParse(withSummary).success).toBe(true);
+  });
+
+  it('accepts multiple pass findings', () => {
+    const multi = {
+      ...baseAttestation,
+      findings: [passFinding, { ...passFinding, acId: '44444444-4444-4444-8444-444444444444' }],
+    };
+    expect(validatorAttestationSchema.safeParse(multi).success).toBe(true);
+  });
+
+  it('REJECTS attestation containing any fail finding', () => {
+    const mixed = { ...baseAttestation, findings: [passFinding, failFinding] };
+    const r = validatorAttestationSchema.safeParse(mixed);
+    expect(r.success).toBe(false);
+  });
+
+  it('REJECTS attestation containing inconclusive finding', () => {
+    const mixed = { ...baseAttestation, findings: [passFinding, inconclusiveFinding] };
+    expect(validatorAttestationSchema.safeParse(mixed).success).toBe(false);
+  });
+
+  it('REJECTS empty findings array', () => {
+    const empty = { ...baseAttestation, findings: [] };
+    expect(validatorAttestationSchema.safeParse(empty).success).toBe(false);
+  });
+
+  it('REJECTS malformed validatorId', () => {
+    const bad = { ...baseAttestation, validatorId: 'worker-prime' };
+    expect(validatorAttestationSchema.safeParse(bad).success).toBe(false);
+  });
+
+  it('REJECTS wrong verdict discriminant', () => {
+    const bad = { ...baseAttestation, verdict: 'reject' };
+    expect(validatorAttestationSchema.safeParse(bad).success).toBe(false);
+  });
+
+  it('REJECTS wrong schemaVersion', () => {
+    const bad = { ...baseAttestation, schemaVersion: '2' };
+    expect(validatorAttestationSchema.safeParse(bad).success).toBe(false);
+  });
+});
+
+// ============================================================================
+// ValidatorRejection
+// ============================================================================
+
+describe('ValidatorRejection (T10510)', () => {
+  const baseRejection: ValidatorRejection = {
+    verdict: 'reject',
+    taskId: 'T10510',
+    validatorId: 'validator-sec-001',
+    findings: [failFinding],
+    summary: 'AC#2 fails — null branch unhandled',
+    rejectedAt: NOW,
+    schemaVersion: '1',
+  };
+
+  it('accepts a well-formed rejection with a fail finding', () => {
+    expect(validatorRejectionSchema.safeParse(baseRejection).success).toBe(true);
+  });
+
+  it('accepts a rejection with only an inconclusive finding', () => {
+    const inc = { ...baseRejection, findings: [inconclusiveFinding] };
+    expect(validatorRejectionSchema.safeParse(inc).success).toBe(true);
+  });
+
+  it('accepts mixed pass + fail findings', () => {
+    const mixed = { ...baseRejection, findings: [passFinding, failFinding] };
+    expect(validatorRejectionSchema.safeParse(mixed).success).toBe(true);
+  });
+
+  it('REJECTS rejection where every finding is pass', () => {
+    const allPass = { ...baseRejection, findings: [passFinding, passFinding] };
+    const r = validatorRejectionSchema.safeParse(allPass);
+    expect(r.success).toBe(false);
+  });
+
+  it('REJECTS empty findings array', () => {
+    const empty = { ...baseRejection, findings: [] };
+    expect(validatorRejectionSchema.safeParse(empty).success).toBe(false);
+  });
+
+  it('REJECTS empty summary', () => {
+    const bad = { ...baseRejection, summary: '' };
+    expect(validatorRejectionSchema.safeParse(bad).success).toBe(false);
+  });
+
+  it('accepts optional remediationHints', () => {
+    const withHints = {
+      ...baseRejection,
+      remediationHints: ['Add null guard to foo()', 'Add regression test'],
+    };
+    expect(validatorRejectionSchema.safeParse(withHints).success).toBe(true);
+  });
+});
+
+// ============================================================================
+// ValidatorVerdict discriminated union
+// ============================================================================
+
+describe('ValidatorVerdict (T10510)', () => {
+  const attestation: ValidatorAttestation = {
+    verdict: 'attest',
+    taskId: 'T10510',
+    validatorId: 'validator-prime',
+    findings: [passFinding],
+    attestedAt: NOW,
+    schemaVersion: '1',
+  };
+  const rejection: ValidatorRejection = {
+    verdict: 'reject',
+    taskId: 'T10510',
+    validatorId: 'validator-prime',
+    findings: [failFinding],
+    summary: 'fail',
+    rejectedAt: NOW,
+    schemaVersion: '1',
+  };
+
+  it('schema accepts both attest and reject envelopes', () => {
+    expect(validatorVerdictSchema.safeParse(attestation).success).toBe(true);
+    expect(validatorVerdictSchema.safeParse(rejection).success).toBe(true);
+  });
+
+  it('schema rejects envelope with unknown verdict', () => {
+    const bad = { ...attestation, verdict: 'maybe' };
+    expect(validatorVerdictSchema.safeParse(bad).success).toBe(false);
+  });
+
+  it('discriminant narrows in TypeScript at compile time', () => {
+    const handle = (v: ValidatorVerdict): string => {
+      if (v.verdict === 'attest') {
+        // TS narrows to ValidatorAttestation here
+        return `attested ${v.attestedAt}`;
+      }
+      // TS narrows to ValidatorRejection here
+      return `rejected ${v.rejectedAt} — ${v.summary}`;
+    };
+    expect(handle(attestation)).toContain('attested');
+    expect(handle(rejection)).toContain('rejected');
+  });
+});
+
+// ============================================================================
+// Type guards
+// ============================================================================
+
+describe('Validator type guards (T10510)', () => {
+  const attestation: ValidatorAttestation = {
+    verdict: 'attest',
+    taskId: 'T10510',
+    validatorId: 'validator-prime',
+    findings: [passFinding],
+    attestedAt: NOW,
+    schemaVersion: '1',
+  };
+  const rejection: ValidatorRejection = {
+    verdict: 'reject',
+    taskId: 'T10510',
+    validatorId: 'validator-prime',
+    findings: [failFinding],
+    summary: 'fail',
+    rejectedAt: NOW,
+    schemaVersion: '1',
+  };
+
+  it('isValidatorAttestation returns true only for attestations', () => {
+    expect(isValidatorAttestation(attestation)).toBe(true);
+    expect(isValidatorAttestation(rejection)).toBe(false);
+    expect(isValidatorAttestation(null)).toBe(false);
+    expect(isValidatorAttestation({})).toBe(false);
+  });
+
+  it('isValidatorRejection returns true only for rejections', () => {
+    expect(isValidatorRejection(rejection)).toBe(true);
+    expect(isValidatorRejection(attestation)).toBe(false);
+    expect(isValidatorRejection(null)).toBe(false);
+  });
+
+  it('isValidatorVerdict returns true for both shapes', () => {
+    expect(isValidatorVerdict(attestation)).toBe(true);
+    expect(isValidatorVerdict(rejection)).toBe(true);
+    expect(isValidatorVerdict({ verdict: 'attest' })).toBe(false);
+    expect(isValidatorVerdict(null)).toBe(false);
+  });
+});

package/src/config.ts

@@ -530,6 +530,50 @@ export interface DecisionsConfig {
   validatorConfidenceThreshold?: number;
 }
 
+/**
+ * Operating mode for the Lead-tier wave roll-up
+ * (`packages/core/src/orchestration/lead-rollup.ts`).
+ *
+ * - `'passive'` — Default, backward-compatible behaviour. `rollupWaveStatus` /
+ *   `rollupEpicStatus` compute the rollup contract from manifest +
+ *   verification rows only. The Lead reads the result and decides what to do
+ *   externally.
+ * - `'active'`  — Enables the Lead↔Worker Max-N loop scaffolded by T10383
+ *   (E-VALIDATOR-ROLE). The rollup will additionally surface retry-eligible
+ *   workers and emit Lead-initiated retry signals.  The wiring of retries
+ *   themselves lives in T10512 — this flag is the gate.
+ * - `'auto'`    — Reserved for future heuristic selection (e.g. switch to
+ *   active mode iff the epic has ≥N pending workers). Treated as `'passive'`
+ *   at runtime until the heuristic ships.
+ *
+ * @task T10513
+ * @saga T10377
+ * @adr ADR-070
+ */
+export type LeadRollupMode = 'passive' | 'active' | 'auto';
+
+/**
+ * Lead-tier wave roll-up configuration.
+ *
+ * Single-key config block gating the Lead↔Worker Max-N loop introduced by
+ * SG-IVTR-AC-BINDING (T10377) and council action #9 of E-VALIDATOR-ROLE
+ * (T10383). The whole point of this block is to keep the existing
+ * `rollupWaveStatus` / `rollupEpicStatus` function signatures unchanged —
+ * callers pick up new behaviour by flipping the config key, never by
+ * threading a new parameter.
+ *
+ * @task T10513
+ * @saga T10377
+ */
+export interface LeadRollupConfig {
+  /**
+   * Roll-up operating mode. Defaults to `'passive'` for backward compatibility.
+   *
+   * @defaultValue 'passive'
+   */
+  mode?: LeadRollupMode;
+}
+
 /** CLEO project configuration (config.json). */
 export interface CleoConfig {
   /** Configuration schema version string. */
@@ -603,6 +647,20 @@ export interface CleoConfig {
    * @task T9410
    */
   auth?: AuthConfig;
+  /**
+   * Lead-tier wave roll-up configuration.
+   *
+   * Gates the Lead↔Worker Max-N loop scaffolded under SG-IVTR-AC-BINDING
+   * (T10377) and council action #9 of E-VALIDATOR-ROLE (T10383). When
+   * absent, the roll-up defaults to `{ mode: 'passive' }` — the legacy
+   * compute-from-manifest behaviour — so existing callers continue to work
+   * unchanged.
+   *
+   * @defaultValue undefined
+   * @task T10513
+   * @saga T10377
+   */
+  leadRollup?: LeadRollupConfig;
 }
 
 /**

package/src/data-accessor.ts

@@ -107,6 +107,49 @@ export interface TaskFieldUpdates {
   pipelineStage?: string | null;
 }
 
+/**
+ * A row of the `task_acceptance_criteria` table (T10502).
+ *
+ * @task T10508
+ */
+export interface AcRow {
+  /** UUIDv4 stable identifier, immutable for the AC's lifetime. */
+  id: string;
+  /** Owning task ID. */
+  taskId: string;
+  /** 1-based ordinal — never reused per task (gaps remain on shrink). */
+  ordinal: number;
+  /** The AC statement text. Structured gates are serialised as JSON. */
+  text: string;
+  /** ISO-8601 timestamp the row was created. */
+  createdAt: string;
+  /** ISO-8601 last-edit timestamp; null until first edit. */
+  updatedAt: string | null;
+  /** Optional sha256(text) snapshot; writers MAY populate, readers MUST treat null as "unknown". */
+  contentHash: string | null;
+}
+
+/**
+ * A row of the `evidence_ac_bindings` table (T10503) — the M:N join between
+ * evidence atoms and acceptance criteria. Powers the AC-coverage gate
+ * (T10509) — "what evidence has been recorded against this AC?".
+ *
+ * @task T10509
+ * @saga T10377 (SG-IVTR-AC-BINDING)
+ */
+export interface AcBindingRow {
+  /** UUIDv4 — set by the writer (T10505/T10506). */
+  id: string;
+  /** Stable hash / composite key of the evidence atom. NOT an FK. */
+  evidenceAtomId: string;
+  /** FK → `task_acceptance_criteria(id)`. */
+  acId: string;
+  /** One of {direct, satisfies, coverage}. */
+  bindingType: 'direct' | 'satisfies' | 'coverage';
+  /** ISO-8601 timestamp of binding creation. */
+  createdAt: string;
+}
+
 /**
  * Subset of DataAccessor methods available inside a transaction callback.
  * Write-only — reads use the outer accessor (snapshot isolation).
@@ -129,8 +172,70 @@ export interface TransactionAccessor {
   removeRelation(taskId: string, relatedTo: string, relationType?: string): Promise<void>;
   /** Remove all relations for a task (both directions) — used for set-replace. @task T9514 */
   clearRelations(taskId: string): Promise<void>;
+  /**
+   * Insert AC rows into `task_acceptance_criteria` with caller-supplied
+   * UUIDs and ordinals. Ordinals MUST NOT collide with existing rows for
+   * the same task — the UNIQUE (task_id, ordinal) index enforces this.
+   * @task T10508
+   */
+  insertAcRows(
+    rows: Array<{ id: string; taskId: string; ordinal: number; text: string }>,
+  ): Promise<void>;
+  /**
+   * Read all AC rows for a task, ordered by ordinal ASC.
+   * Available inside transactions for shrink/replace flows that need to
+   * read the current state before deletion.
+   * @task T10508
+   */
+  getAcRows(taskId: string): Promise<AcRow[]>;
+  /**
+   * Delete all AC rows for a task. Used by update-replace-all + update-shrink
+   * flows AFTER the history rows have been appended.
+   * @task T10508
+   */
+  deleteAcRowsForTask(taskId: string): Promise<void>;
+  /**
+   * Append a history row to `task_acceptance_criteria_history` capturing the
+   * AC text that is about to be superseded.
+   * @task T10508
+   */
+  appendAcHistory(
+    rows: Array<{ acId: string; previousText: string; reason: string }>,
+  ): Promise<void>;
+  /**
+   * Read all `evidence_ac_bindings` rows whose `ac_id` ∈ the given set.
+   * Used by the AC-coverage gate (T10509) to compute which ACs are
+   * satisfied vs unsatisfied inside the same transaction that flips the
+   * task to `done`.
+   *
+   * Returns the empty array when `acIds` is empty.
+   *
+   * @task T10509
+   */
+  getAcBindings(acIds: readonly string[]): Promise<AcBindingRow[]>;
+  /**
+   * Insert rows into `evidence_ac_bindings`. Used by the Validator SDK
+   * tools (T10511) to persist coverage bindings transactionally after a
+   * Validator attestation. The UNIQUE (evidence_atom_id, ac_id, binding_type)
+   * index collapses idempotent re-inserts via `ON CONFLICT DO NOTHING`.
+   *
+   * No-op when `rows` is empty.
+   *
+   * @task T10511
+   * @saga T10377 (SG-IVTR-AC-BINDING)
+   */
+  insertAcBindings(
+    rows: Array<{
+      id: string;
+      evidenceAtomId: string;
+      acId: string;
+      bindingType: 'direct' | 'satisfies' | 'coverage';
+    }>,
+  ): Promise<void>;
 }
 
+// Re-export AcRow at the module level for both transaction + outer accessor use.
+
 /**
  * DataAccessor interface.
  *
@@ -193,6 +298,21 @@ export interface DataAccessor {
   /** Remove a row from the task_relations table (T9240). */
   removeRelation(taskId: string, relatedTo: string, relationType?: string): Promise<void>;
 
+  /**
+   * Read AC rows for a task from `task_acceptance_criteria`, ordered by
+   * ordinal ASC. Returns the empty array if no rows exist.
+   * @task T10508
+   */
+  getAcRows(taskId: string): Promise<AcRow[]>;
+
+  /**
+   * Read `evidence_ac_bindings` rows whose `ac_id` ∈ the given set.
+   * Powers the AC-coverage gate (T10509). Returns the empty array when
+   * `acIds` is empty or no bindings exist for the supplied ids.
+   * @task T10509
+   */
+  getAcBindings(acIds: readonly string[]): Promise<AcBindingRow[]>;
+
   // ---- Metadata (schema_meta KV store) ----
 
   /** Read a typed value from the metadata store. Returns null if not found. */