agentic-orchestrator 0.1.28 → 0.2.1

package/apps/control-plane/test/collision-override-service.spec.ts

@@ -0,0 +1,878 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  CollisionOverrideService,
+  type CollisionOverrideServicePort,
+} from '../src/application/services/collision-override-service.js';
+import { detectPlanCollisions, type PlanShape } from '../src/core/collisions.js';
+import { ERROR_CODES } from '../src/core/error-codes.js';
+
+type AnyRecord = Record<string, any>;
+
+function clone<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+function makePlan(
+  featureId: string,
+  options: {
+    file?: string;
+    allowedAreas?: string[];
+    contracts?: { openapi?: string; events?: string; db?: string };
+  } = {},
+): PlanShape & { plan_version: number; revision_of: null } {
+  return {
+    feature_id: featureId,
+    plan_version: 1,
+    revision_of: null,
+    files: {
+      create: [],
+      modify: [options.file ?? 'src/shared.ts'],
+      delete: [],
+    },
+    allowed_areas: options.allowedAreas ?? ['src'],
+    contracts: {
+      openapi: options.contracts?.openapi ?? 'none',
+      events: options.contracts?.events ?? 'none',
+      db: options.contracts?.db ?? 'none',
+    },
+  };
+}
+
+async function writePlan(
+  repoRoot: string,
+  plan: PlanShape & { plan_version: number; revision_of: null },
+): Promise<void> {
+  const featureDir = path.join(repoRoot, plan.feature_id);
+  await fs.mkdir(featureDir, { recursive: true });
+  await fs.writeFile(path.join(featureDir, 'plan.json'), JSON.stringify(plan, null, 2), 'utf8');
+}
+
+async function makeHarness(
+  options: {
+    candidatePlan?: PlanShape & { plan_version: number; revision_of: null };
+    acceptedPlans?: Array<PlanShape & { plan_version: number; revision_of: null }>;
+    includeDefaultRecord?: boolean;
+    providePlanSubmit?: boolean;
+  } = {},
+) {
+  const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-collision-override-'));
+  const candidatePlan = clone(options.candidatePlan ?? makePlan('feature_a'));
+  const acceptedPlans = clone(options.acceptedPlans ?? [makePlan('feature_b')]);
+  for (const plan of acceptedPlans) {
+    await writePlan(repoRoot, plan);
+  }
+
+  const collisionResult = detectPlanCollisions(candidatePlan, acceptedPlans, {});
+  const logs: Array<{ featureId: string; note: string }> = [];
+  let index: AnyRecord = {
+    version: 1,
+    active: ['feature_a', ...acceptedPlans.map((plan) => plan.feature_id)],
+    blocked: [],
+    merged: [],
+    locks: {},
+    lock_leases: {},
+    blocked_queue: [],
+    collision_records:
+      options.includeDefaultRecord === false
+        ? []
+        : [
+            {
+              collision_id: 'colrec_1',
+              feature_id: 'feature_a',
+              with_feature_ids: acceptedPlans.map((plan) => plan.feature_id),
+              source_tool: 'plan.submit',
+              plan_version: 1,
+              detected_at: '2026-03-15T00:00:00.000Z',
+              collision_fingerprint: collisionResult.fingerprint,
+              collisions: collisionResult.collisions,
+              plan_snapshot: candidatePlan,
+              resolution: 'rejected',
+            },
+          ],
+    collision_overrides: [],
+    runtime_sessions: {},
+    updated_at: '2026-03-15T00:00:00.000Z',
+  };
+  let currentPlan: AnyRecord = clone(candidatePlan);
+
+  const planSubmit =
+    options.providePlanSubmit === false
+      ? undefined
+      : vi.fn(async () => ({
+          data: {
+            feature_id: 'feature_a',
+            accepted: true,
+            plan_version: 1,
+          },
+        }));
+  const planGet =
+    options.providePlanSubmit === false
+      ? undefined
+      : vi.fn(async () => ({
+          data: {
+            feature_id: 'feature_a',
+            plan: clone(currentPlan),
+          },
+        }));
+  const planUpdate =
+    options.providePlanSubmit === false
+      ? undefined
+      : vi.fn(
+          async (_featureId: string, _expectedPlanVersion: number | null, nextPlan: AnyRecord) => {
+            currentPlan = clone(nextPlan);
+            return {
+              data: {
+                feature_id: 'feature_a',
+                accepted: true,
+                plan_version: Number(nextPlan.plan_version),
+              },
+            };
+          },
+        );
+
+  const port: CollisionOverrideServicePort = {
+    getPolicySnapshot: () => ({}),
+    planPath: (featureId: string) => path.join(repoRoot, featureId, 'plan.json'),
+    featureDiscoverSpecs: async () => ({
+      data: {
+        specs: [
+          { feature_id: 'feature_a' },
+          ...acceptedPlans.map((plan) => ({ feature_id: plan.feature_id })),
+        ],
+      },
+    }),
+    readIndex: async () => clone(index),
+    writeIndex: async (nextIndex: AnyRecord) => {
+      index = clone(nextIndex);
+    },
+    withIndexLock: async <T>(operation: () => Promise<T>) => await operation(),
+    featureLogAppend: vi.fn(async (featureId: string, note: string) => {
+      logs.push({ featureId, note });
+      return {
+        data: {
+          feature_id: featureId,
+          appended: true,
+          log_path: `${featureId}/decisions.md`,
+        },
+      };
+    }),
+    ...(planSubmit ? { planSubmit } : {}),
+    ...(planGet ? { planGet } : {}),
+    ...(planUpdate ? { planUpdate } : {}),
+  };
+
+  return {
+    service: new CollisionOverrideService(port),
+    candidatePlan,
+    collisionResult,
+    logs,
+    planSubmit,
+    planGet,
+    planUpdate,
+    getIndex: () => clone(index),
+    setIndex: (nextIndex: AnyRecord) => {
+      index = clone(nextIndex);
+    },
+    updateAcceptedPlan: async (
+      featureId: string,
+      nextPlan: PlanShape & { plan_version: number; revision_of: null },
+    ) => {
+      const planIndex = acceptedPlans.findIndex((entry) => entry.feature_id === featureId);
+      if (planIndex >= 0) {
+        acceptedPlans[planIndex] = clone(nextPlan);
+      } else {
+        acceptedPlans.push(clone(nextPlan));
+      }
+      await writePlan(repoRoot, nextPlan);
+    },
+    setCurrentPlan: (nextPlan: AnyRecord) => {
+      currentPlan = clone(nextPlan);
+    },
+    cleanup: async () => await fs.rm(repoRoot, { recursive: true, force: true }),
+  };
+}
+
+describe('CollisionOverrideService', () => {
+  const cleanups: Array<() => Promise<void>> = [];
+
+  afterEach(async () => {
+    while (cleanups.length > 0) {
+      const cleanup = cleanups.pop();
+      if (cleanup) {
+        await cleanup();
+      }
+    }
+  });
+
+  it('records collisions, supersedes stale fingerprints, and appends an audit event', async () => {
+    const harness = await makeHarness();
+    cleanups.push(harness.cleanup);
+    const index = harness.getIndex();
+    index.collision_records.unshift({
+      collision_id: 'colrec_old',
+      feature_id: 'feature_a',
+      with_feature_ids: ['feature_b'],
+      source_tool: 'plan.update',
+      plan_version: 2,
+      detected_at: '2026-03-14T00:00:00.000Z',
+      collision_fingerprint: 'fp_old',
+      collisions: harness.collisionResult.collisions,
+      plan_snapshot: harness.candidatePlan,
+      resolution: 'rejected',
+    });
+    harness.setIndex(index);
+
+    const record = await harness.service.recordCollision({
+      featureId: 'feature_a',
+      sourceTool: 'plan.update',
+      planVersion: 2,
+      collisionFingerprint: 'fp_new',
+      collisions: harness.collisionResult.collisions,
+      planSnapshot: harness.candidatePlan as unknown as Record<string, unknown>,
+      resolution: 'blocked',
+      context: {
+        actorType: 'planner',
+        actorId: 'run:test',
+      },
+    });
+
+    const nextIndex = harness.getIndex();
+    expect(record.collision_fingerprint).toBe('fp_new');
+    expect(
+      nextIndex.collision_records.find((entry: AnyRecord) => entry.collision_id === 'colrec_old'),
+    ).toMatchObject({
+      resolution: 'superseded',
+    });
+    expect(
+      harness.logs.some((entry) => entry.note.includes('"event_type":"collision_record_created"')),
+    ).toBe(true);
+  });
+
+  it('marks and clears collision record resolutions when records exist', async () => {
+    const harness = await makeHarness();
+    cleanups.push(harness.cleanup);
+
+    await harness.service.markCollisionRecordResolution(
+      'colrec_1',
+      'override_applied',
+      {
+        override_id: 'colovr_1',
+        resolved_at: '2026-03-15T01:00:00.000Z',
+        note: 'Approved intentional overlap',
+      },
+      {
+        actorType: 'system',
+        actorId: 'run:test',
+      },
+    );
+
+    await harness.service.clearResolvedCollisionRecords('feature_a', 1, {
+      actorType: 'system',
+      actorId: 'run:test',
+    });
+
+    expect(harness.getIndex().collision_records[0]).toMatchObject({
+      resolution: 'override_applied',
+      resolution_details: expect.objectContaining({
+        override_id: 'colovr_1',
+      }),
+    });
+
+    await harness.service.markCollisionRecordResolution(
+      'missing_record',
+      'cleared',
+      { resolved_at: '2026-03-15T02:00:00.000Z' },
+      {
+        actorType: 'system',
+        actorId: 'run:test',
+      },
+    );
+    await harness.service.clearResolvedCollisionRecords('feature_a', 99, {
+      actorType: 'system',
+      actorId: 'run:test',
+    });
+  });
+
+  it('clears unresolved collision records for an accepted plan version', async () => {
+    const harness = await makeHarness();
+    cleanups.push(harness.cleanup);
+
+    await harness.service.clearResolvedCollisionRecords('feature_a', 1, {
+      actorType: 'system',
+      actorId: 'run:test',
+    });
+
+    expect(harness.getIndex().collision_records[0]).toMatchObject({
+      resolution: 'cleared',
+      resolution_details: expect.objectContaining({
+        note: 'Plan accepted without an active collision',
+      }),
+    });
+  });
+
+  it('evaluates contracts, empty collisions, stale overrides, and matching overrides', async () => {
+    const harness = await makeHarness();
+    cleanups.push(harness.cleanup);
+
+    const contractOnly = await harness.service.evaluateApprovals(
+      'feature_a',
+      {
+        files: [],
+        areas: [],
+        contracts: [
+          {
+            with_feature_id: 'feature_b',
+            contract: 'openapi',
+            candidate_mode: 'write',
+            other_mode: 'read',
+          },
+        ],
+      },
+      {
+        actorType: 'system',
+        actorId: 'run:test',
+      },
+    );
+    expect(contractOnly).toMatchObject({
+      approved: false,
+      blocking_feature_ids: ['feature_b'],
+    });
+
+    const empty = await harness.service.evaluateApprovals(
+      'feature_a',
+      {
+        files: [],
+        areas: [],
+        contracts: [],
+      },
+      {
+        actorType: 'system',
+        actorId: 'run:test',
+      },
+    );
+    expect(empty).toMatchObject({
+      approved: true,
+      blocking_feature_ids: [],
+    });
+
+    const indexWithStale = harness.getIndex();
+    indexWithStale.collision_overrides = [
+      {
+        override_id: 'colovr_old',
+        feature_ids: ['feature_a', 'feature_b'],
+        created_at: '2026-03-15T00:00:00.000Z',
+        created_by: 'run:test',
+        rationale: 'old approval',
+        approved_collision_fingerprint: 'stale_fp',
+        approved_paths: ['src/shared.ts'],
+        approved_with_feature_ids: ['feature_b'],
+        status: 'active',
+        source_collision_id: 'colrec_1',
+      },
+    ];
+    harness.setIndex(indexWithStale);
+
+    const stale = await harness.service.evaluateApprovals(
+      'feature_a',
+      harness.collisionResult.collisions,
+      {
+        actorType: 'system',
+        actorId: 'run:test',
+      },
+    );
+    expect(stale.approved).toBe(false);
+    expect(harness.getIndex().collision_overrides[0].status).toBe('stale');
+
+    const matchingFingerprint = detectPlanCollisions(
+      harness.candidatePlan,
+      [makePlan('feature_b')],
+      {},
+    ).collisions;
+    const matchingIndex = harness.getIndex();
+    matchingIndex.collision_overrides = [
+      {
+        override_id: 'colovr_active',
+        feature_ids: ['feature_a', 'feature_b'],
+        created_at: '2026-03-15T00:00:00.000Z',
+        created_by: 'run:test',
+        rationale: 'intentional overlap',
+        approved_collision_fingerprint: detectPlanCollisions(
+          harness.candidatePlan,
+          [makePlan('feature_b')],
+          {},
+        ).fingerprint,
+        approved_paths: ['src/shared.ts'],
+        approved_with_feature_ids: ['feature_b'],
+        status: 'active',
+        source_collision_id: 'colrec_1',
+      },
+    ];
+    harness.setIndex(matchingIndex);
+
+    const approved = await harness.service.evaluateApprovals('feature_a', matchingFingerprint, {
+      actorType: 'system',
+      actorId: 'run:test',
+    });
+    expect(approved.approved).toBe(true);
+    expect(harness.getIndex().collision_overrides[0]).toMatchObject({
+      status: 'applied',
+      applied_at: expect.any(String),
+    });
+    expect(
+      harness.logs.some((entry) =>
+        entry.note.includes('"event_type":"collision_override_applied"'),
+      ),
+    ).toBe(true);
+  });
+
+  it('creates an override from an unresolved collision record and can resume the plan', async () => {
+    const harness = await makeHarness();
+    cleanups.push(harness.cleanup);
+
+    const result = await harness.service.allowOverride({
+      featureId: 'feature_a',
+      withFeatureId: 'feature_b',
+      reason: 'Intentional shared refactor',
+      resume: true,
+      createdBy: 'run:test',
+    });
+
+    expect(result).toMatchObject({
+      override_id: expect.any(String),
+      feature_ids: ['feature_a', 'feature_b'],
+      approved_paths: ['src/shared.ts'],
+      resumed: true,
+    });
+    expect(harness.getIndex().collision_overrides).toHaveLength(1);
+    expect(harness.planSubmit).toHaveBeenCalledTimes(1);
+    expect(harness.logs.some((entry) => entry.note.includes('collision_override_created'))).toBe(
+      true,
+    );
+  });
+
+  it('recovers resumed override plans by promoting stale submit attempts to plan.update', async () => {
+    const harness = await makeHarness();
+    cleanups.push(harness.cleanup);
+    harness.setCurrentPlan({
+      feature_id: 'feature_a',
+      plan_version: 1,
+      summary: 'Current accepted plan',
+      files: { create: [], modify: ['src/current.ts'], delete: [] },
+    });
+    harness.planSubmit?.mockRejectedValueOnce({
+      normalizedResponse: {
+        error: {
+          code: ERROR_CODES.VERSION_CONFLICT,
+        },
+      },
+    });
+
+    const result = await harness.service.allowOverride({
+      featureId: 'feature_a',
+      withFeatureId: 'feature_b',
+      reason: 'Intentional shared refactor',
+      resume: true,
+      createdBy: 'run:test',
+    });
+
+    expect(result.resumed).toBe(true);
+    expect(harness.planGet).toHaveBeenCalledWith('feature_a');
+    expect(harness.planUpdate).toHaveBeenCalledWith(
+      'feature_a',
+      1,
+      expect.objectContaining({
+        feature_id: 'feature_a',
+        plan_version: 2,
+        revision_of: 1,
+      }),
+    );
+  });
+
+  it('reuses an existing matching override instead of creating a duplicate', async () => {
+    const harness = await makeHarness();
+    cleanups.push(harness.cleanup);
+    const existingIndex = harness.getIndex();
+    existingIndex.collision_overrides = [
+      {
+        override_id: 'colovr_existing',
+        feature_ids: ['feature_a', 'feature_b'],
+        created_at: '2026-03-15T00:00:00.000Z',
+        created_by: 'run:test',
+        rationale: 'existing approval',
+        approved_collision_fingerprint: harness.collisionResult.fingerprint,
+        approved_paths: ['src/shared.ts'],
+        approved_with_feature_ids: ['feature_b'],
+        status: 'active',
+        source_collision_id: 'colrec_1',
+      },
+    ];
+    harness.setIndex(existingIndex);
+
+    const result = await harness.service.allowOverride({
+      featureId: 'feature_a',
+      withFeatureId: 'feature_b',
+      reason: 'Intentional shared refactor',
+      resume: false,
+      createdBy: 'run:test',
+    });
+
+    expect(result.override_id).toBe('colovr_existing');
+    expect(harness.getIndex().collision_overrides).toHaveLength(1);
+  });
+
+  it('rejects override approval when there is no unresolved collision record', async () => {
+    const harness = await makeHarness({ includeDefaultRecord: false });
+    cleanups.push(harness.cleanup);
+
+    await expect(
+      harness.service.allowOverride({
+        featureId: 'feature_a',
+        withFeatureId: 'feature_b',
+        reason: 'Intentional shared refactor',
+        createdBy: 'run:test',
+      }),
+    ).rejects.toMatchObject({
+      normalizedResponse: {
+        error: {
+          code: ERROR_CODES.COLLISION_RECORD_NOT_FOUND,
+        },
+      },
+    });
+  });
+
+  it('rejects override approval when the live collision disappeared or drifted', async () => {
+    const harness = await makeHarness();
+    cleanups.push(harness.cleanup);
+
+    await harness.updateAcceptedPlan(
+      'feature_b',
+      makePlan('feature_b', { file: 'docs/other.md', allowedAreas: ['docs'] }),
+    );
+    await expect(
+      harness.service.allowOverride({
+        featureId: 'feature_a',
+        withFeatureId: 'feature_b',
+        reason: 'Intentional shared refactor',
+        createdBy: 'run:test',
+      }),
+    ).rejects.toMatchObject({
+      normalizedResponse: {
+        error: {
+          code: ERROR_CODES.COLLISION_OVERRIDE_NOT_APPLICABLE,
+        },
+      },
+    });
+
+    const driftHarness = await makeHarness({
+      candidatePlan: makePlan('feature_a', {
+        contracts: { openapi: 'write' },
+      }),
+      acceptedPlans: [makePlan('feature_b')],
+    });
+    cleanups.push(driftHarness.cleanup);
+    await driftHarness.updateAcceptedPlan(
+      'feature_b',
+      makePlan('feature_b', {
+        contracts: { openapi: 'read' },
+      }),
+    );
+    await expect(
+      driftHarness.service.allowOverride({
+        featureId: 'feature_a',
+        withFeatureId: 'feature_b',
+        reason: 'Intentional shared refactor',
+        createdBy: 'run:test',
+      }),
+    ).rejects.toMatchObject({
+      normalizedResponse: {
+        error: {
+          code: ERROR_CODES.COLLISION_OVERRIDE_STALE,
+        },
+      },
+    });
+  });
+
+  it('rejects contract-collision overrides and resume requests without plan submission support', async () => {
+    const contractHarness = await makeHarness({
+      candidatePlan: makePlan('feature_a', {
+        contracts: { openapi: 'write' },
+      }),
+      acceptedPlans: [
+        makePlan('feature_b', {
+          contracts: { openapi: 'read' },
+        }),
+      ],
+    });
+    cleanups.push(contractHarness.cleanup);
+
+    await expect(
+      contractHarness.service.allowOverride({
+        featureId: 'feature_a',
+        withFeatureId: 'feature_b',
+        reason: 'Intentional shared contract',
+        createdBy: 'run:test',
+      }),
+    ).rejects.toMatchObject({
+      normalizedResponse: {
+        error: {
+          code: ERROR_CODES.COLLISION_OVERRIDE_CONTRACT_FORBIDDEN,
+        },
+      },
+    });
+
+    const noResumeHarness = await makeHarness({ providePlanSubmit: false });
+    cleanups.push(noResumeHarness.cleanup);
+    await expect(
+      noResumeHarness.service.allowOverride({
+        featureId: 'feature_a',
+        withFeatureId: 'feature_b',
+        reason: 'Intentional shared refactor',
+        resume: true,
+        createdBy: 'run:test',
+      }),
+    ).rejects.toMatchObject({
+      normalizedResponse: {
+        error: {
+          code: ERROR_CODES.INTERNAL_ERROR,
+        },
+      },
+    });
+  });
+
+  it('lists overrides with live-collision and applied status metadata', async () => {
+    const harness = await makeHarness();
+    cleanups.push(harness.cleanup);
+    const index = harness.getIndex();
+    index.collision_overrides = [
+      {
+        override_id: 'colovr_match',
+        feature_ids: ['feature_a', 'feature_b'],
+        created_at: '2026-03-15T00:00:00.000Z',
+        created_by: 'run:test',
+        rationale: 'match',
+        approved_collision_fingerprint: harness.collisionResult.fingerprint,
+        approved_paths: ['src/shared.ts'],
+        approved_with_feature_ids: ['feature_b'],
+        status: 'applied',
+        applied_at: '2026-03-15T00:05:00.000Z',
+        source_collision_id: 'colrec_1',
+      },
+      {
+        override_id: 'colovr_revoked',
+        feature_ids: ['feature_x', 'feature_y'],
+        created_at: '2026-03-14T00:00:00.000Z',
+        created_by: 'run:test',
+        rationale: 'revoked',
+        approved_collision_fingerprint: 'fp_none',
+        approved_paths: ['src/none.ts'],
+        approved_with_feature_ids: ['feature_y'],
+        status: 'revoked',
+        source_collision_id: 'missing_record',
+      },
+    ];
+    harness.setIndex(index);
+
+    const overrides = await harness.service.listOverrides('feature_a');
+
+    expect(overrides).toHaveLength(1);
+    expect(overrides[0]).toMatchObject({
+      override_id: 'colovr_match',
+      matches_live_collision: true,
+      applied_successfully: true,
+      latest_seen_at: '2026-03-15T00:00:00.000Z',
+    });
+  });
+
+  it('revokes overrides, stales feature-linked overrides, and builds approved collision contexts', async () => {
+    const harness = await makeHarness();
+    cleanups.push(harness.cleanup);
+    const index = harness.getIndex();
+    index.collision_overrides = [
+      {
+        override_id: 'colovr_active',
+        feature_ids: ['feature_a', 'feature_b'],
+        created_at: '2026-03-15T00:00:00.000Z',
+        created_by: 'run:test',
+        rationale: 'match',
+        approved_collision_fingerprint: harness.collisionResult.fingerprint,
+        approved_paths: ['src/shared.ts'],
+        approved_with_feature_ids: ['feature_b'],
+        status: 'active',
+        source_collision_id: 'colrec_1',
+      },
+      {
+        override_id: 'colovr_applied',
+        feature_ids: ['feature_a', 'feature_c'],
+        created_at: '2026-03-15T00:00:00.000Z',
+        created_by: 'run:test',
+        rationale: 'applied',
+        approved_collision_fingerprint: 'fp_c',
+        approved_paths: ['src/other.ts'],
+        approved_with_feature_ids: ['feature_c'],
+        status: 'applied',
+        applied_at: '2026-03-15T00:05:00.000Z',
+        source_collision_id: 'missing_record',
+      },
+    ];
+    harness.setIndex(index);
+
+    const revoked = await harness.service.revokeOverride('colovr_active', 'run:test');
+    expect(revoked.status).toBe('revoked');
+
+    await expect(
+      harness.service.revokeOverride('missing_override', 'run:test'),
+    ).rejects.toMatchObject({
+      normalizedResponse: {
+        error: {
+          code: ERROR_CODES.COLLISION_OVERRIDE_NOT_FOUND,
+        },
+      },
+    });
+
+    await harness.service.staleOverridesForFeature('feature_a', 'feature closed', 'run:test');
+    const nextIndex = harness.getIndex();
+    expect(nextIndex.collision_overrides[1].status).toBe('stale');
+
+    const contexts = await harness.service.approvedCollisionContextsForFeature('feature_a');
+    expect(contexts).toEqual([]);
+  });
+
+  it('returns approved collision contexts when source records still exist', async () => {
+    const harness = await makeHarness();
+    cleanups.push(harness.cleanup);
+    const index = harness.getIndex();
+    index.collision_overrides = [
+      {
+        override_id: 'colovr_context',
+        feature_ids: ['feature_a', 'feature_b'],
+        created_at: '2026-03-15T00:00:00.000Z',
+        created_by: 'run:test',
+        rationale: 'context',
+        approved_collision_fingerprint: harness.collisionResult.fingerprint,
+        approved_paths: ['src/shared.ts'],
+        approved_with_feature_ids: ['feature_b'],
+        status: 'applied',
+        applied_at: '2026-03-15T00:05:00.000Z',
+        source_collision_id: 'colrec_1',
+      },
+    ];
+    harness.setIndex(index);
+
+    const contexts = await harness.service.approvedCollisionContextsForFeature('feature_a');
+
+    expect(contexts).toHaveLength(1);
+    expect(contexts[0]).toMatchObject({
+      override_id: 'colovr_context',
+      counterpart_feature_id: 'feature_b',
+      rationale: 'context',
+      approved_paths: ['src/shared.ts'],
+      approved_collision_fingerprint: harness.collisionResult.fingerprint,
+      source_collision_id: 'colrec_1',
+      detected_at: '2026-03-15T00:00:00.000Z',
+      applied_at: '2026-03-15T00:05:00.000Z',
+      source_collision_record: {
+        collision_id: 'colrec_1',
+        feature_id: 'feature_a',
+      },
+    });
+  });
+
+  it('lists overrides without a feature filter in descending created order', async () => {
+    const harness = await makeHarness();
+    cleanups.push(harness.cleanup);
+    const index = harness.getIndex();
+    index.collision_overrides = [
+      {
+        override_id: 'colovr_old',
+        feature_ids: ['feature_x', 'feature_y'],
+        created_at: '2026-03-14T00:00:00.000Z',
+        created_by: 'run:test',
+        rationale: 'older',
+        approved_collision_fingerprint: 'fp_old',
+        approved_paths: ['src/old.ts'],
+        approved_with_feature_ids: ['feature_y'],
+        status: 'active',
+        source_collision_id: 'missing_record',
+      },
+      {
+        override_id: 'colovr_new',
+        feature_ids: ['feature_a', 'feature_b'],
+        created_at: '2026-03-15T00:00:00.000Z',
+        created_by: 'run:test',
+        rationale: 'newer',
+        approved_collision_fingerprint: harness.collisionResult.fingerprint,
+        approved_paths: ['src/shared.ts'],
+        approved_with_feature_ids: ['feature_b'],
+        status: 'active',
+        source_collision_id: 'colrec_1',
+      },
+    ];
+    harness.setIndex(index);
+
+    const overrides = await harness.service.listOverrides();
+
+    expect(overrides.map((entry) => entry.override_id)).toEqual(['colovr_new', 'colovr_old']);
+    expect(overrides[1]).toMatchObject({
+      latest_seen_at: null,
+      matches_live_collision: false,
+      applied_successfully: false,
+    });
+  });
+
+  it('leaves stale overrides unchanged when no usable override exists and resolves contexts for the counterpart feature', async () => {
+    const harness = await makeHarness();
+    cleanups.push(harness.cleanup);
+    const index = harness.getIndex();
+    index.collision_overrides = [
+      {
+        override_id: 'colovr_revoked',
+        feature_ids: ['feature_a', 'feature_b'],
+        created_at: '2026-03-15T00:00:00.000Z',
+        created_by: 'run:test',
+        rationale: 'revoked',
+        approved_collision_fingerprint: harness.collisionResult.fingerprint,
+        approved_paths: ['src/shared.ts'],
+        approved_with_feature_ids: ['feature_b'],
+        status: 'revoked',
+        source_collision_id: 'colrec_1',
+      },
+      {
+        override_id: 'colovr_applied',
+        feature_ids: ['feature_a', 'feature_b'],
+        created_at: '2026-03-15T00:00:00.000Z',
+        created_by: 'run:test',
+        rationale: 'applied',
+        approved_collision_fingerprint: harness.collisionResult.fingerprint,
+        approved_paths: ['src/shared.ts'],
+        approved_with_feature_ids: ['feature_b'],
+        status: 'applied',
+        applied_at: '2026-03-15T00:05:00.000Z',
+        source_collision_id: 'colrec_1',
+      },
+    ];
+    harness.setIndex(index);
+
+    await harness.service.staleOverridesForFeature('feature_missing', 'not touched', 'run:test');
+    expect(harness.getIndex().collision_overrides[1].status).toBe('applied');
+
+    const contexts = await harness.service.approvedCollisionContextsForFeature('feature_b');
+    expect(contexts).toHaveLength(1);
+    expect(contexts[0]).toMatchObject({
+      override_id: 'colovr_applied',
+      counterpart_feature_id: 'feature_a',
+      rationale: 'applied',
+      approved_paths: ['src/shared.ts'],
+      approved_collision_fingerprint: harness.collisionResult.fingerprint,
+      source_collision_id: 'colrec_1',
+      detected_at: '2026-03-15T00:00:00.000Z',
+      applied_at: '2026-03-15T00:05:00.000Z',
+      source_collision_record: {
+        collision_id: 'colrec_1',
+        feature_id: 'feature_a',
+      },
+    });
+  });
+});