@cleocode/contracts 2026.5.122 → 2026.5.124

package/src/__tests__/completion-operation-contracts.test.ts

@@ -0,0 +1,154 @@
+/**
+ * Contract tests for completion.* and projection.repair dispatch shapes.
+ *
+ * @task T10607
+ * @saga T10538
+ */
+
+import { describe, expect, it } from 'vitest';
+import { OPERATIONS } from '../dispatch/operations-registry.js';
+import {
+  completionEvaluateParamsSchema,
+  completionEvaluationSchema,
+  completionExplainParamsSchema,
+  completionExplanationSchema,
+  completionListParamsSchema,
+  completionListResultSchema,
+  completionProjectionRepairErrorSchema,
+  completionProjectionRepairParamsSchema,
+  completionProjectionRepairResultSchema,
+  unsatisfiedCompletionCriterionSchema,
+} from '../tasks.js';
+
+const requiredOperations = [
+  'completion.list',
+  'completion.evaluate',
+  'completion.explain',
+  'projection.repair',
+] as const;
+
+function operation(name: (typeof requiredOperations)[number]) {
+  const def = OPERATIONS.find(
+    (candidate) => candidate.domain === 'tasks' && candidate.operation === name,
+  );
+  if (def === undefined) throw new Error(`missing tasks.${name}`);
+  return def;
+}
+
+const unsatisfiedCriterion = {
+  acId: 'ac-1',
+  alias: 'AC1',
+  text: 'typed AC result schemas added',
+  kind: 'evidence_bound',
+  status: 'unsatisfied',
+  reason: 'missing_evidence_binding',
+  evidenceBindings: 0,
+} as const;
+
+const totals = { criteria: 1, satisfied: 0, unsatisfied: 1, waived: 0, replaced: 0 };
+
+describe('Completion operation contract schemas', () => {
+  it('validates typed AC result, unsatisfied criterion, evaluate, and explain shapes', () => {
+    expect(unsatisfiedCompletionCriterionSchema.parse(unsatisfiedCriterion).reason).toBe(
+      'missing_evidence_binding',
+    );
+
+    expect(
+      completionEvaluationSchema.parse({
+        taskId: 'T10607',
+        taskStatus: 'pending',
+        ready: false,
+        stale: false,
+        staleReasons: [],
+        satisfied: [],
+        unsatisfied: [unsatisfiedCriterion],
+        waived: [],
+        replaced: [],
+        totals,
+      }).unsatisfied,
+    ).toHaveLength(1);
+
+    expect(
+      completionExplanationSchema.parse({
+        taskId: 'T10607',
+        ready: false,
+        stale: true,
+        summary: 'Task has one unsatisfied completion criterion.',
+        blockers: [unsatisfiedCriterion],
+      }).blockers[0]?.status,
+    ).toBe('unsatisfied');
+  });
+
+  it('validates params/results for completion.list/evaluate/explain/projection.repair', () => {
+    expect(completionListParamsSchema.parse({ taskId: 'T10607', status: 'unsatisfied' })).toEqual({
+      taskId: 'T10607',
+      status: 'unsatisfied',
+    });
+    expect(
+      completionListResultSchema.parse({
+        taskId: 'T10607',
+        criteria: [unsatisfiedCriterion],
+        totals,
+      }).criteria[0]?.alias,
+    ).toBe('AC1');
+
+    expect(
+      completionEvaluateParamsSchema.parse({
+        taskId: 'T10607',
+        includeContext: true,
+        limit: 10,
+        relationDepth: 1,
+      }),
+    ).toEqual({ taskId: 'T10607', includeContext: true, limit: 10, relationDepth: 1 });
+    expect(completionExplainParamsSchema.parse({ taskId: 'T10607', since: '2026-05-26' })).toEqual({
+      taskId: 'T10607',
+      since: '2026-05-26',
+    });
+
+    expect(
+      completionProjectionRepairErrorSchema.parse({
+        code: 'criteria_missing',
+        message: 'Projected AC row no longer exists.',
+        taskId: 'T10607',
+        acId: 'ac-1',
+      }).code,
+    ).toBe('criteria_missing');
+    expect(
+      completionProjectionRepairParamsSchema.parse({ taskId: 'T10607', dryRun: true }),
+    ).toEqual({
+      taskId: 'T10607',
+      dryRun: true,
+    });
+    expect(
+      completionProjectionRepairResultSchema.parse({
+        taskId: 'T10607',
+        repaired: false,
+        dryRun: true,
+        staleBefore: true,
+        staleAfter: true,
+        errors: [
+          {
+            code: 'repair_conflict',
+            message: 'Concurrent projection change detected.',
+            taskId: 'T10607',
+          },
+        ],
+      }).errors[0]?.code,
+    ).toBe('repair_conflict');
+  });
+
+  it('publishes operation metadata with taskId requirements and correct gateways', () => {
+    for (const name of requiredOperations) {
+      const def = operation(name);
+      expect(def.domain).toBe('tasks');
+      expect(def.idempotent).toBe(true);
+      expect(def.requiredParams).toEqual(['taskId']);
+      expect(def.params?.map((param) => param.name)).toContain('taskId');
+    }
+
+    expect(operation('completion.list').gateway).toBe('query');
+    expect(operation('completion.evaluate').gateway).toBe('query');
+    expect(operation('completion.explain').gateway).toBe('query');
+    expect(operation('projection.repair').gateway).toBe('mutate');
+  });
+});

package/src/__tests__/operation-envelope-validation.test.ts

@@ -0,0 +1,140 @@
+/**
+ * Contract tests for operation-aware LAFS envelope validation.
+ *
+ * @task T10610
+ * @saga T10538
+ */
+
+import { describe, expect, it } from 'vitest';
+import type { LAFSEnvelope } from '../lafs.js';
+import {
+  E_LAFS_OPERATION_ERROR_SHAPE,
+  E_LAFS_OPERATION_RESULT_SCHEMA,
+  E_LAFS_OPERATION_UNREGISTERED,
+  validateOperationEnvelope,
+} from '../operation-envelope-validation.js';
+import { tasksTreeResultSchema } from '../workgraph.js';
+
+const baseMeta: LAFSEnvelope['_meta'] = {
+  specVersion: '1.0.0',
+  schemaVersion: '1.0.0',
+  timestamp: '2026-05-26T10:00:00.000Z',
+  operation: 'tasks.frontier',
+  requestId: 'req-T10610',
+  transport: 'cli',
+  strict: true,
+  mvi: 'standard',
+  contextVersion: 1,
+};
+
+function successEnvelope(
+  operation: string,
+  result: NonNullable<LAFSEnvelope['result']>,
+): LAFSEnvelope {
+  return {
+    $schema: 'https://lafs.dev/schemas/v1/envelope.schema.json',
+    _meta: { ...baseMeta, operation },
+    success: true,
+    result,
+    error: null,
+  };
+}
+
+function failureEnvelope(operation = 'tasks.frontier'): LAFSEnvelope {
+  return {
+    $schema: 'https://lafs.dev/schemas/v1/envelope.schema.json',
+    _meta: { ...baseMeta, operation },
+    success: false,
+    result: null,
+    error: {
+      code: 'E_CONTRACT',
+      message: 'contract failed',
+      category: 'CONTRACT',
+      retryable: false,
+      retryAfterMs: null,
+      details: { taskId: 'T10610' },
+      agentAction: 'stop',
+    },
+  };
+}
+
+const frontierResult = {
+  rootId: 'T10538',
+  groups: { ready: [], blocked: [], blockedBy: [] },
+};
+
+describe('operation-aware LAFS envelope validation', () => {
+  it('checks _meta.operation against the canonical operations registry', () => {
+    const valid = validateOperationEnvelope(successEnvelope('tasks.frontier', frontierResult));
+    expect(valid.valid).toBe(true);
+    expect(valid.operation?.domain).toBe('tasks');
+    expect(valid.operation?.operation).toBe('frontier');
+
+    const invalid = validateOperationEnvelope(
+      successEnvelope('tasks.not-a-real-operation', frontierResult),
+    );
+    expect(invalid.valid).toBe(false);
+    expect(invalid.issues).toContainEqual(
+      expect.objectContaining({
+        path: '/_meta/operation',
+        code: E_LAFS_OPERATION_UNREGISTERED,
+      }),
+    );
+  });
+
+  it('validates successful payloads against the operation result schema', () => {
+    const invalid = validateOperationEnvelope(
+      successEnvelope('tasks.frontier', { rootId: 'T10538', groups: { ready: [] } }),
+    );
+    expect(invalid.valid).toBe(false);
+    expect(invalid.resultSchemaOperation).toBe('tasks.frontier');
+    expect(invalid.issues.some((issue) => issue.code === E_LAFS_OPERATION_RESULT_SCHEMA)).toBe(
+      true,
+    );
+
+    const valid = validateOperationEnvelope(successEnvelope('tasks.frontier', frontierResult));
+    expect(valid.valid).toBe(true);
+    expect(valid.resultSchemaOperation).toBe('tasks.frontier');
+  });
+
+  it('enforces canonical error-envelope shape before result schemas', () => {
+    const validFailure = validateOperationEnvelope(failureEnvelope());
+    expect(validFailure.valid).toBe(true);
+    expect(validFailure.resultSchemaOperation).toBe('tasks.frontier');
+
+    const invalidFailure = validateOperationEnvelope({
+      ...failureEnvelope(),
+      result: frontierResult,
+    });
+    expect(invalidFailure.valid).toBe(false);
+    expect(invalidFailure.issues).toContainEqual(
+      expect.objectContaining({
+        path: '/result',
+        code: E_LAFS_OPERATION_ERROR_SHAPE,
+      }),
+    );
+  });
+
+  it('rejects relation groups edges in hierarchy tree result contracts', () => {
+    const result = tasksTreeResultSchema.safeParse({
+      rootId: 'T10538',
+      nodes: [],
+      edges: [{ fromId: 'T10538', toId: 'T10545', kind: 'groups', source: 'relation' }],
+      pageInfo: { hasMore: false },
+    });
+    expect(result.success).toBe(false);
+
+    const envelope = validateOperationEnvelope(
+      successEnvelope('tasks.tree', {
+        rootId: 'T10538',
+        nodes: [],
+        edges: [{ fromId: 'T10538', toId: 'T10545', kind: 'groups', source: 'relation' }],
+        pageInfo: { hasMore: false },
+      }),
+    );
+    expect(envelope.valid).toBe(false);
+    expect(envelope.issues.some((issue) => issue.code === E_LAFS_OPERATION_RESULT_SCHEMA)).toBe(
+      true,
+    );
+  });
+});

package/src/__tests__/satisfies-atom.test.ts

@@ -58,17 +58,18 @@ describe('satisfies atom regexes (ADR-079-r2 §2.1)', () => {
   });
 
   describe('AC_UUID_REGEX', () => {
-    it('accepts strict lowercase UUIDv4', () => {
+    it('accepts strict lowercase UUIDv4 and deterministic UUIDv5-shaped AC ids', () => {
       expect(AC_UUID_REGEX.test('a1b2c3d4-5e6f-4890-abcd-ef1234567890')).toBe(true);
       expect(AC_UUID_REGEX.test('00000000-0000-4000-8000-000000000000')).toBe(true);
+      expect(AC_UUID_REGEX.test('a1b2c3d4-5e6f-5890-abcd-ef1234567890')).toBe(true);
     });
     it('rejects mixed-case', () => {
       // Council-mandated strictness (ADR-079-r2 §2.2): "Validators MUST
       // reject mixed-case to prevent silent dedupe failures."
       expect(AC_UUID_REGEX.test('A1B2C3D4-5E6F-4890-ABCD-EF1234567890')).toBe(false);
     });
-    it('rejects wrong version nibble (not 4)', () => {
-      expect(AC_UUID_REGEX.test('a1b2c3d4-5e6f-5890-abcd-ef1234567890')).toBe(false);
+    it('rejects wrong version nibble (not 4/5)', () => {
+      expect(AC_UUID_REGEX.test('a1b2c3d4-5e6f-6890-abcd-ef1234567890')).toBe(false);
     });
     it('rejects wrong variant nibble (not 8/9/a/b)', () => {
       expect(AC_UUID_REGEX.test('a1b2c3d4-5e6f-4890-cbcd-ef1234567890')).toBe(false);
@@ -126,6 +127,15 @@ describe('satisfiesAtomSchema (ADR-079-r2 §5.2)', () => {
     expect(a.versionPin).toBeUndefined();
   });
 
+  it('accepts deterministic UUIDv5-shaped AC id form without version-pin', () => {
+    const a = satisfiesAtomSchema.parse({
+      kind: 'satisfies',
+      targetTaskId: 'T10495',
+      targetAcId: '8f4a2c1e-b09d-5f6a-9c3e-7a1d4f8c0b2e',
+    });
+    expect(a.targetAcId).toBe('8f4a2c1e-b09d-5f6a-9c3e-7a1d4f8c0b2e');
+  });
+
   it('accepts alias form without version-pin', () => {
     const a = satisfiesAtomSchema.parse({
       kind: 'satisfies',
@@ -210,6 +220,16 @@ describe('parseEvidenceString — satisfies atom (T10506)', () => {
     });
   });
 
+  it('parses deterministic UUIDv5-shaped AC id form', () => {
+    const atoms = parseEvidenceString('satisfies:T10495#8f4a2c1e-b09d-5f6a-9c3e-7a1d4f8c0b2e');
+    expect(atoms).toHaveLength(1);
+    expect(atoms[0]).toEqual({
+      kind: 'satisfies',
+      targetTaskId: 'T10495',
+      targetAcId: '8f4a2c1e-b09d-5f6a-9c3e-7a1d4f8c0b2e',
+    });
+  });
+
   it('parses alias form', () => {
     const atoms = parseEvidenceString('satisfies:T10495#AC2');
     expect(atoms).toHaveLength(1);

package/src/__tests__/workgraph-context-scaffold-contracts.test.ts

@@ -0,0 +1,232 @@
+/**
+ * Contract tests for bounded WorkGraph context packs, readiness, and scaffold envelopes.
+ *
+ * @task T10609
+ * @saga T10538
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  workGraphContextPackParamsSchema,
+  workGraphContextPackSchema,
+  workGraphReadinessParamsSchema,
+  workGraphReadinessResultSchema,
+  workGraphScaffoldApplyParamsSchema,
+  workGraphScaffoldApplyResultSchema,
+  workGraphScaffoldValidateParamsSchema,
+  workGraphScaffoldValidateResultSchema,
+  workGraphSliceParamsSchema,
+  workGraphSliceSchema,
+} from '../workgraph.js';
+
+const taskNode = {
+  id: 'T10609',
+  type: 'task',
+  title: 'Add contracts',
+  status: 'pending',
+  priority: 'high',
+  parentId: 'T10545',
+} as const;
+
+const emptyPageInfo = { hasMore: false } as const;
+
+const readyGroups = {
+  ready: [
+    {
+      ...taskNode,
+      role: 'worker',
+      dependencyBlockers: [],
+      gateBlockers: [],
+    },
+  ],
+  blocked: [],
+  blockedBy: [],
+} as const;
+
+describe('WorkGraph bounded context and scaffold contracts', () => {
+  it('validates bounded context packs with graph slices, relation edges, readiness, budget, and omissions', () => {
+    expect(
+      workGraphContextPackParamsSchema.parse({
+        rootId: 'T10545',
+        tokenBudget: 1500,
+        includeRelations: true,
+        includeReadiness: true,
+        includeRollup: true,
+        limit: 25,
+      }),
+    ).toEqual({
+      rootId: 'T10545',
+      tokenBudget: 1500,
+      includeRelations: true,
+      includeReadiness: true,
+      includeRollup: true,
+      limit: 25,
+    });
+
+    const parsed = workGraphContextPackSchema.parse({
+      rootId: 'T10545',
+      generatedAt: '2026-05-26T10:00:00.000Z',
+      budget: {
+        tokenBudget: 1500,
+        estimatedTokens: 1200,
+        remainingTokens: 300,
+        truncated: true,
+      },
+      slice: {
+        rootId: 'T10545',
+        direction: 'descendants',
+        nodes: [taskNode],
+        edges: [{ fromId: 'T10545', toId: 'T10609', kind: 'contains' }],
+        pageInfo: { nextCursor: '0002:T10610', hasMore: true },
+        omissions: [
+          {
+            path: 'slice.nodes[25:]',
+            reason: 'budget_exceeded',
+            message: 'Additional nodes omitted to stay under token budget',
+            estimatedTokens: 400,
+          },
+        ],
+      },
+      relationEdges: {
+        rootId: 'T10609',
+        direction: 'both',
+        edges: [
+          {
+            source: 'dependency',
+            fromId: 'T10609',
+            toId: 'T10608',
+            kind: 'depends_on',
+          },
+          {
+            source: 'relation',
+            fromId: 'T10538',
+            toId: 'T10545',
+            kind: 'groups',
+            relationType: 'groups',
+            reason: 'Saga membership',
+          },
+        ],
+      },
+      readiness: {
+        rootId: 'T10545',
+        role: 'worker',
+        ready: true,
+        warnings: [],
+        groups: readyGroups,
+      },
+      rollup: {
+        rootId: 'T10545',
+        direct: { total: 1, byStatus: { pending: 1 }, byType: { task: 1 } },
+        subtree: { total: 1, byStatus: { pending: 1 }, byType: { task: 1 } },
+        percentDenominator: { basis: 'subtree-total', total: 1, description: 'subtree total' },
+        percentages: { done: 0, active: 0, blocked: 0, pending: 100, cancelled: 0 },
+        staleProjection: false,
+        projectionMismatches: [],
+      },
+      omissions: [
+        { path: 'rollup.history', reason: 'not_requested', message: 'History not requested' },
+      ],
+    });
+
+    expect(parsed.budget.truncated).toBe(true);
+    expect(parsed.relationEdges?.edges.map((edge) => edge.source)).toEqual([
+      'dependency',
+      'relation',
+    ]);
+    expect(parsed.readiness?.groups.ready[0]?.id).toBe('T10609');
+  });
+
+  it('validates graph slice and readiness envelopes independently', () => {
+    expect(
+      workGraphSliceParamsSchema.parse({
+        rootId: 'T10545',
+        direction: 'descendants',
+        maxDepth: 2,
+        includeRelations: true,
+        cursor: '0001:T10609',
+        limit: 50,
+      }),
+    ).toEqual({
+      rootId: 'T10545',
+      direction: 'descendants',
+      maxDepth: 2,
+      includeRelations: true,
+      cursor: '0001:T10609',
+      limit: 50,
+    });
+
+    expect(
+      workGraphSliceSchema.parse({
+        rootId: 'T10545',
+        direction: 'descendants',
+        nodes: [taskNode],
+        edges: [{ fromId: 'T10545', toId: 'T10609', kind: 'contains' }],
+        pageInfo: emptyPageInfo,
+      }).nodes,
+    ).toHaveLength(1);
+
+    expect(
+      workGraphReadinessParamsSchema.parse({
+        rootId: 'T10545',
+        role: 'worker',
+        includeGateBlockers: true,
+      }),
+    ).toEqual({ rootId: 'T10545', role: 'worker', includeGateBlockers: true });
+
+    expect(
+      workGraphReadinessResultSchema.parse({
+        rootId: 'T10545',
+        role: 'worker',
+        ready: true,
+        warnings: [],
+        groups: readyGroups,
+      }).ready,
+    ).toBe(true);
+  });
+
+  it('validates scaffold validate/apply contracts and hierarchy diagnostics', () => {
+    const nodes = [
+      { id: 'T10545', type: 'epic' },
+      { id: 'T10609', type: 'task', parentId: 'T10545' },
+    ] as const;
+    const edges = [
+      {
+        source: 'dependency',
+        fromId: 'T10609',
+        toId: 'T10608',
+        kind: 'depends_on',
+      },
+    ] as const;
+
+    expect(
+      workGraphScaffoldValidateParamsSchema.parse({ rootId: 'T10545', nodes, edges, dryRun: true }),
+    ).toEqual({ rootId: 'T10545', nodes, edges, dryRun: true });
+
+    expect(
+      workGraphScaffoldValidateResultSchema.parse({
+        rootId: 'T10545',
+        valid: true,
+        dryRun: true,
+        issues: [{ code: 'W_EXISTING_NODE', message: 'Node already exists', severity: 'warning' }],
+        hierarchy: { valid: true, violations: [] },
+      }).valid,
+    ).toBe(true);
+
+    expect(
+      workGraphScaffoldApplyParamsSchema.parse({ rootId: 'T10545', nodes, edges, apply: true }),
+    ).toEqual({ rootId: 'T10545', nodes, edges, apply: true });
+
+    expect(
+      workGraphScaffoldApplyResultSchema.parse({
+        rootId: 'T10545',
+        valid: true,
+        dryRun: false,
+        applied: true,
+        nodesChanged: 2,
+        edgesChanged: 1,
+        issues: [],
+        hierarchy: { valid: true, violations: [] },
+      }).edgesChanged,
+    ).toBe(1);
+  });
+});