@cleocode/contracts 2026.9.8 → 2026.9.10

package/src/__tests__/acceptance-gate.test.ts

@@ -11,8 +11,14 @@
  * @task T780
  */
 
+import { readFileSync } from 'node:fs';
 import { describe, expect, it } from 'vitest';
-import type { AcceptanceGate, AcceptanceGateResult, FileAssertion } from '../acceptance-gate.js';
+import type {
+  AcceptanceGate,
+  AcceptanceGateBinding,
+  AcceptanceGateResult,
+  FileAssertion,
+} from '../acceptance-gate.js';
 import {
   acceptanceArraySchema,
   acceptanceGateResultSchema,
@@ -23,9 +29,11 @@ import {
   httpGateSchema,
   lintGateSchema,
   manualGateSchema,
+  testCountReportSchema,
   testGateSchema,
 } from '../acceptance-gate-schema.js';
 import type { AcceptanceItem } from '../index.js';
+import type { ProcessCaptureResult } from '../resource-governor.js';
 
 // ─── TestGate ────────────────────────────────────────────────────────────────
 
@@ -734,3 +742,276 @@ describe('acceptanceArraySchema — mixed (string | AcceptanceGate)[] (T780)', (
     expect(typed).toHaveLength(2);
   });
 });
+
+describe('acceptance result captured execution preservation (T12292)', () => {
+  const execution: ProcessCaptureResult = {
+    started: true,
+    targetPid: 1234,
+    exitCode: 0,
+    signal: null,
+    error: null,
+    stopped: null,
+    stdout: 'literal ü | output',
+    stderr: '',
+    outputTruncated: false,
+    durationMs: 12,
+    mode: 'systemd',
+    unitName: 'cleo-tool-fixture.scope',
+    nativeMemory: 'observed-cgroup',
+    resourceLimits: {
+      cgroup: '/user.slice/cleo-tool-fixture.scope',
+      memoryMaxBytes: 4294967296,
+      tasksMax: 256,
+    },
+    cleanupScope: 'process-group',
+    transportClosed: true,
+    targetCloseObserved: true,
+    cleanupObservation: 'scope-terminal',
+    cleanupErrors: [],
+  };
+  const result: AcceptanceGateResult = {
+    index: 3,
+    req: 'PARTNER-EXACT',
+    kind: 'test',
+    result: 'pass',
+    durationMs: 12,
+    checkedAt: '2026-09-20T17:00:00.000Z',
+    checkedBy: 'captured-agent',
+    execution,
+  };
+
+  it('preserves every execution field through JSON and runtime validation', () => {
+    expect(acceptanceGateResultSchema.parse(JSON.parse(JSON.stringify(result)))).toEqual(result);
+  });
+
+  it.each([
+    'deadline',
+    'cancelled',
+    'resource-limit',
+    'output-limit',
+    'transport-error',
+  ] as const)('retains %s as an incomplete observation without inventing a verdict', (stopped) => {
+    const interrupted: AcceptanceGateResult = {
+      ...result,
+      result: 'error',
+      execution: { ...execution, stopped, exitCode: null, targetCloseObserved: false },
+    };
+    expect(acceptanceGateResultSchema.parse(interrupted)).toEqual(interrupted);
+    expect(acceptanceGateResultSchema.safeParse({ ...interrupted, result: 'pass' }).success).toBe(
+      false,
+    );
+  });
+
+  it('rejects a completed verdict for an unstarted target', () => {
+    expect(
+      acceptanceGateResultSchema.safeParse({
+        ...result,
+        execution: { ...execution, started: false, targetPid: null, exitCode: null },
+      }).success,
+    ).toBe(false);
+  });
+
+  it('rejects malformed or contradictory process evidence instead of stripping it', () => {
+    for (const corrupt of [
+      { ...execution, unexpectedAuthority: true },
+      { ...execution, targetPid: 0 },
+      { ...execution, signal: 'SIGTERM' },
+      { ...execution, nativeMemory: 'observed-cgroup', resourceLimits: undefined },
+      { ...execution, resourceLimits: { ...execution.resourceLimits, cgroup: '/wrong-owner' } },
+      { ...execution, durationMs: Number.POSITIVE_INFINITY },
+    ])
+      expect(acceptanceGateResultSchema.safeParse({ ...result, execution: corrupt }).success).toBe(
+        false,
+      );
+  });
+});
+
+describe('typed requirement verification binding (T12292)', () => {
+  const binding: AcceptanceGateBinding = {
+    version: 1,
+    verificationId: '9f4a8d70-6325-4bf8-a30c-b719ade689da',
+    identity: {
+      projectId: 'stable-project',
+      projectRoot: '/project',
+      actor: 'agent-test',
+      operation: 'check.gate.verify',
+      idempotencyKey: 'verification-attempt',
+    },
+    taskId: 'T122',
+    criterionId: 'e1cf21de-92db-46e4-8e3d-156ab78a0b32',
+    criterionHash: 'a'.repeat(64),
+    gateHash: 'b'.repeat(64),
+    capturedAt: '2026-09-20T17:00:00.000Z',
+    deadlineAt: 1790000000000,
+    invocation: {
+      command: 'node',
+      args: ['scripts/verify.mjs', '--task', 'T122'],
+      cwd: '/project',
+      environmentHash: 'c'.repeat(64),
+    },
+    artifacts: [{ path: '/project/scripts/verify.mjs', sha256: 'd'.repeat(64), bytes: 81 }],
+  };
+  const result: AcceptanceGateResult = {
+    index: 3,
+    req: 'PARTNER-122',
+    kind: 'test',
+    result: 'error',
+    durationMs: 5,
+    checkedAt: '2026-09-20T17:00:00.005Z',
+    checkedBy: 'agent-test',
+    binding,
+  };
+
+  it('round-trips bound identity, invocation hashes and untracked input snapshots losslessly', () => {
+    expect(acceptanceGateResultSchema.parse(JSON.parse(JSON.stringify(result)))).toEqual(result);
+  });
+
+  it('preserves an explicitly observed absent input without fabricating a hash', () => {
+    const absent = {
+      ...result,
+      binding: {
+        ...binding,
+        artifacts: [{ path: '/project/scripts/missing.mjs', sha256: null, bytes: null }],
+      },
+    };
+    expect(acceptanceGateResultSchema.parse(absent)).toEqual(absent);
+  });
+
+  it('does not turn a bound process result into a verdict without an actual execution observation', () => {
+    expect(acceptanceGateResultSchema.safeParse({ ...result, result: 'pass' }).success).toBe(false);
+    const legacy = { ...result, binding: undefined, result: 'pass' };
+    expect(acceptanceGateResultSchema.parse(legacy)).toEqual(legacy);
+  });
+
+  it.each([
+    { ...binding, gateHash: 'not-a-hash' },
+    { ...binding, identity: { ...binding.identity, projectRoot: 'relative-root' } },
+    { ...binding, invocation: { ...binding.invocation, cwd: 'relative-cwd' } },
+    { ...binding, artifacts: [{ ...binding.artifacts[0], path: 'relative-input' }] },
+    { ...binding, verificationId: 'not-a-uuid' },
+    { ...binding, identity: { ...binding.identity, actor: 'different-agent' } },
+    { ...binding, capturedAt: '2026-09-20T17:00:01.000Z' },
+    { ...binding, deadlineAt: 1 },
+    { ...binding, artifacts: [binding.artifacts[0], binding.artifacts[0]] },
+    { ...binding, artifacts: [{ ...binding.artifacts[0], sha256: null }] },
+    { ...binding, artifacts: [{ ...binding.artifacts[0], bytes: -1 }] },
+    {
+      ...binding,
+      invocation: { ...binding.invocation, environmentHash: '', env: { SECRET: 'must-not-store' } },
+    },
+    { ...binding, authority: 'implicit' },
+  ])('rejects inconsistent or malformed persisted binding %#', (invalid) => {
+    expect(acceptanceGateResultSchema.safeParse({ ...result, binding: invalid }).success).toBe(
+      false,
+    );
+  });
+});
+
+describe('published acceptance result schema (T12292)', () => {
+  it('retains binding and execution shapes while disclosing runtime-only invariants', () => {
+    const emitted = JSON.parse(
+      readFileSync(new URL('../../schemas/gate-result.schema.json', import.meta.url), 'utf8'),
+    );
+    expect(emitted.properties.binding.properties.gateHash.pattern).toBe('^[a-f0-9]{64}$');
+    expect(emitted.properties.binding.properties.artifacts.items.properties.sha256).toBeDefined();
+    expect(emitted.properties.execution.properties.cleanupObservation).toBeDefined();
+    expect(emitted.properties.binding.additionalProperties).toBe(false);
+    expect(emitted.$comment).toContain('acceptanceGateResultSchema');
+    expect(emitted.$comment).toContain('cross-field');
+    expect(emitted.$comment).toContain('not proof');
+    expect(emitted.required).not.toContain('binding');
+    expect(emitted.required).not.toContain('execution');
+  });
+});
+
+describe('structured minimum-count report schema', () => {
+  // Captured Vitest 4.1.4 JSON: one nested suite, pass + skip + todo.
+  const report = {
+    numTotalTestSuites: 2,
+    numPassedTestSuites: 2,
+    numFailedTestSuites: 0,
+    numPendingTestSuites: 0,
+    numTotalTests: 3,
+    numPassedTests: 1,
+    numFailedTests: 0,
+    numPendingTests: 1,
+    numTodoTests: 1,
+    success: true,
+    testResults: [
+      {
+        name: '/fixture/reporter.test.ts',
+        status: 'passed',
+        assertionResults: [
+          { fullName: 'actual reporter passes', status: 'passed' },
+          { fullName: 'actual reporter skipped', status: 'skipped' },
+          { fullName: 'actual reporter later', status: 'todo' },
+        ],
+      },
+    ],
+  };
+
+  it('recognizes passed tests without counting skipped or todo assertions', () => {
+    const parsed = testCountReportSchema.parse(report);
+    expect(parsed.numPassedTests).toBe(1);
+    expect(parsed.numTotalTests).toBe(3);
+    expect(parsed.numTotalTestSuites).toBe(2);
+    expect(parsed.testResults).toHaveLength(1);
+  });
+
+  it.each([
+    { numPassedTests: 3 },
+    { numTotalTests: 99 },
+    { numPendingTests: 0 },
+    { numTodoTests: 0 },
+    { numPassedTests: 1.5 },
+    { numPassedTests: -1 },
+    { numTotalTests: Number.MAX_SAFE_INTEGER + 1 },
+    { numFailedTestSuites: 1 },
+  ])('rejects malformed or inconsistent counters: %j', (change) => {
+    expect(testCountReportSchema.safeParse({ ...report, ...change }).success).toBe(false);
+  });
+
+  it('rejects summary-only, missing counters, and unsupported assertion states', () => {
+    expect(testCountReportSchema.safeParse({ numPassedTests: 100, success: true }).success).toBe(
+      false,
+    );
+    expect(testCountReportSchema.safeParse({ ...report, numTodoTests: undefined }).success).toBe(
+      false,
+    );
+    expect(
+      testCountReportSchema.safeParse({
+        ...report,
+        testResults: [
+          {
+            ...report.testResults[0],
+            assertionResults: [{ fullName: 'test', status: 'invented' }],
+          },
+        ],
+      }).success,
+    ).toBe(false);
+  });
+
+  it('retains real failed suite reports without converting them into success', () => {
+    const failed = {
+      ...report,
+      success: false,
+      numPassedTestSuites: 1,
+      numFailedTestSuites: 1,
+      testResults: [{ ...report.testResults[0], status: 'failed' }],
+    };
+    expect(testCountReportSchema.parse(failed).success).toBe(false);
+    expect(testCountReportSchema.safeParse({ ...failed, success: true }).success).toBe(false);
+  });
+
+  it('accepts zero-count structure without claiming that any test ran', () => {
+    const empty = {
+      ...report,
+      numTotalTests: 0,
+      numPassedTests: 0,
+      numPendingTests: 0,
+      numTodoTests: 0,
+      testResults: [],
+    };
+    expect(testCountReportSchema.parse(empty).numPassedTests).toBe(0);
+  });
+});

package/src/__tests__/evidence-atom-schema.test.ts

@@ -540,7 +540,10 @@ describe('GATE_EVIDENCE_REQUIREMENTS (T10337)', () => {
     ];
     expect(validateEvidenceForGate('implemented', d).ok).toBe(true);
 
-    const e: EvidenceAtomInput[] = [{ kind: 'pr', prNumber: 357 }];
+    const e: EvidenceAtomInput[] = [
+      { kind: 'pr', prNumber: 357 },
+      { kind: 'files', paths: ['src/fix.ts'] },
+    ];
     expect(validateEvidenceForGate('implemented', e).ok).toBe(true);
   });
 
@@ -552,11 +555,11 @@ describe('GATE_EVIDENCE_REQUIREMENTS (T10337)', () => {
     if (!r.ok) {
       expect(r.message).toMatch(/^Gate 'implemented' requires evidence: /);
       expect(r.message).toContain('[commit AND files]');
-      expect(r.message).toContain('[pr]');
+      expect(r.message).toContain('[pr AND files]');
     }
   });
 
-  it('testsPassed accepts test-run, tool, pr — single-atom alternatives', () => {
+  it('testsPassed accepts actual runs and tools but rejects PR provenance', () => {
     expect(
       validateEvidenceForGate('testsPassed', [
         { kind: 'test-run', path: '/tmp/v.json' },
@@ -570,7 +573,7 @@ describe('GATE_EVIDENCE_REQUIREMENTS (T10337)', () => {
     expect(
       validateEvidenceForGate('testsPassed', [{ kind: 'pr', prNumber: 357 }] as EvidenceAtomInput[])
         .ok,
-    ).toBe(true);
+    ).toBe(false);
   });
 
   it('testsPassed rejects empty evidence', () => {
@@ -579,7 +582,7 @@ describe('GATE_EVIDENCE_REQUIREMENTS (T10337)', () => {
 
   it('qaPassed accepts a single tool atom (behavior parity with legacy)', () => {
     // Critical parity check: GATE_EVIDENCE_REQUIREMENTS.qaPassed.oneOf is
-    // [['tool'], ['pr']] — not [['tool', 'tool']]. The legacy runtime did NOT
+    // [['tool']] — not [['tool', 'tool']]. The legacy runtime did NOT
     // count distinct tool names, so one tool atom passes.
     expect(
       validateEvidenceForGate('qaPassed', [{ kind: 'tool', tool: 'lint' }] as EvidenceAtomInput[])
@@ -587,11 +590,11 @@ describe('GATE_EVIDENCE_REQUIREMENTS (T10337)', () => {
     ).toBe(true);
   });
 
-  it('qaPassed also accepts pr atom', () => {
+  it('qaPassed rejects PR provenance without a review tool result', () => {
     expect(
       validateEvidenceForGate('qaPassed', [{ kind: 'pr', prNumber: 357 }] as EvidenceAtomInput[])
         .ok,
-    ).toBe(true);
+    ).toBe(false);
   });
 
   it('documented accepts files or url', () => {
@@ -656,7 +659,7 @@ describe('formatGateRequirement (T10337)', () => {
     expect(s).toContain('[commit AND note]');
     expect(s).toContain('[decision AND files]');
     expect(s).toContain('[decision AND note]');
-    expect(s).toContain('[pr]');
+    expect(s).toContain('[pr AND files]');
     // Joiner between combinations is ' OR '.
     expect(s.split(' OR ').length).toBe(5);
   });
@@ -678,7 +681,7 @@ describe('formatGateRequirementHint (T9949)', () => {
     expect(h).toContain("--evidence 'commit:<sha>;note:<short description>'");
     expect(h).toContain("--evidence 'decision:D-arch-001;files:path/a.ts,path/b.ts'");
     expect(h).toContain("--evidence 'decision:D-arch-001;note:<short description>'");
-    expect(h).toContain("--evidence 'pr:357'");
+    expect(h).toContain("--evidence 'pr:357;files:path/a.ts,path/b.ts'");
     // Routes a `note:`-only caller at the partner atom they need.
     expect(h).toContain("'note:' alone is NOT accepted for this gate");
     expect(h).toContain("'commit:'");
@@ -686,11 +689,11 @@ describe('formatGateRequirementHint (T9949)', () => {
   });
 
   it('routes note-only callers for testsPassed at the right alternatives', () => {
-    // testsPassed accepts test-run, tool, or pr — none of which involve note.
+    // testsPassed accepts test-run or tool — neither involves note.
     const h = formatGateRequirementHint('testsPassed');
     expect(h).toContain("--evidence 'test-run:/tmp/vitest-out.json'");
     expect(h).toContain("--evidence 'tool:test'");
-    expect(h).toContain("--evidence 'pr:357'");
+    expect(h).not.toContain('pr:357');
     // When no combination includes note at all, the helper falls through to a
     // generic "not accepted, see ADR-051" clarifier rather than fabricating a
     // partner suggestion.
@@ -731,9 +734,9 @@ describe('validateEvidenceForGate failure surface (T9949)', () => {
     ] as EvidenceAtomInput[]);
     expect(r.ok).toBe(false);
     if (!r.ok) {
-      // Legacy single-line message preserved byte-for-byte.
+      // Error includes the same artifact requirement as the validator.
       expect(r.message).toBe(
-        "Gate 'implemented' requires evidence: [commit AND files] OR [commit AND note] OR [decision AND files] OR [decision AND note] OR [pr]",
+        "Gate 'implemented' requires evidence: [commit AND files] OR [commit AND note] OR [decision AND files] OR [decision AND note] OR [pr AND files]",
       );
       // New rich hint includes the same content as formatGateRequirementHint.
       expect(r.hint).toBe(formatGateRequirementHint('implemented'));
@@ -747,7 +750,7 @@ describe('validateEvidenceForGate failure surface (T9949)', () => {
     expect(r.ok).toBe(false);
     if (!r.ok) {
       expect(r.hint).toContain("--evidence 'tool:test'");
-      expect(r.hint).toContain("--evidence 'pr:357'");
+      expect(r.hint).not.toContain('pr:357');
       expect(r.hint).toContain("'note:' is NOT accepted for this gate");
     }
   });

package/src/__tests__/memory-wire-shapes.test.ts

@@ -58,6 +58,7 @@ type AssertEquals1<T extends 1> = T;
 // ─── Search: BrainCompactHit shape pin ──────────────────────────────
 
 type _BrainCompactHitShape = {
+  matchedHistoricalIds?: string[];
   id: string;
   type: 'decision' | 'pattern' | 'learning' | 'observation';
   title: string;
@@ -73,6 +74,7 @@ type _AssertBrainCompactHitPinned = AssertEquals1<Equals<BrainCompactHit, _Brain
 // ─── Search: SearchBrainCompactParams shape pin ─────────────────────
 
 type _SearchBrainCompactParamsShape = {
+  includeHistory?: boolean;
   query: string;
   limit?: number;
   tables?: Array<'decisions' | 'patterns' | 'learnings' | 'observations'>;

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

@@ -20,6 +20,19 @@ describe('operations-registry', () => {
     expect(JSON.stringify(OPERATIONS)).toMatchSnapshot();
   });
 
+  it('declares deletion force and cascade as distinct optional boolean controls', () => {
+    const deletion = OPERATIONS.find(
+      (operation) => operation.domain === 'tasks' && operation.operation === 'delete',
+    );
+    expect(deletion?.requiredParams).toEqual(['taskId']);
+    expect(deletion?.params).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ name: 'force', type: 'boolean', required: false }),
+        expect.objectContaining({ name: 'cascade', type: 'boolean', required: false }),
+      ]),
+    );
+  });
+
   it('OPERATIONS count is consistent', () => {
     expect(OPERATIONS.length).toBeGreaterThan(0);
     const queryCount = OPERATIONS.filter((o) => o.gateway === 'query').length;
@@ -40,6 +53,19 @@ describe('operations-registry', () => {
     }
   });
 
+  it('registers docs.status as a read-only, session-independent query', () => {
+    const matches = OPERATIONS.filter(
+      (operation) => operation.domain === 'docs' && operation.operation === 'status',
+    );
+    expect(matches).toHaveLength(1);
+    expect(matches[0]).toMatchObject({
+      gateway: 'query',
+      idempotent: true,
+      sessionRequired: false,
+      requiredParams: [],
+    });
+  });
+
   it('defineOp is an identity function', () => {
     const def = OPERATIONS[0];
     expect(defineOp(def)).toBe(def);