agentic-orchestrator 0.1.28 → 0.2.0

package/apps/control-plane/src/application/services/collision-override-service.ts

@@ -0,0 +1,906 @@
+import crypto from 'node:crypto';
+import { nowIso, readJson } from '../../core/fs.js';
+import {
+  collectApprovedPaths,
+  collisionSubsetForFeature,
+  createCollisionFingerprint,
+  detectPlanCollisions,
+  hasContractCollisions,
+  splitPlanCollisionsByFeature,
+  type PlanCollisionPair,
+  type PlanCollisionsShape,
+  type PlanShape,
+  type PolicyShape,
+} from '../../core/collisions.js';
+import { ERROR_CODES } from '../../core/error-codes.js';
+import { asPlanRecord, recoverStalePlanSubmitConflict } from '../../core/plan-submit-recovery.js';
+import { fail } from '../../core/response.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyRecord = Record<string, any>;
+
+type FeatureContext = {
+  actorType: string;
+  actorId: string;
+};
+
+type CollisionRecordResolution =
+  | 'rejected'
+  | 'blocked'
+  | 'override_applied'
+  | 'cleared'
+  | 'superseded';
+
+type CollisionRecord = {
+  collision_id: string;
+  feature_id: string;
+  with_feature_ids: string[];
+  source_tool: 'plan.submit' | 'plan.update';
+  plan_version: number;
+  detected_at: string;
+  collision_fingerprint: string;
+  collisions: PlanCollisionsShape;
+  plan_snapshot: Record<string, unknown>;
+  resolution: CollisionRecordResolution;
+  resolution_details?: {
+    override_id?: string;
+    resolved_at?: string;
+    note?: string;
+  };
+};
+
+export type CollisionOverride = {
+  override_id: string;
+  feature_ids: [string, string];
+  created_at: string;
+  created_by: string;
+  rationale: string;
+  approved_collision_fingerprint: string;
+  approved_paths: string[];
+  approved_with_feature_ids: string[];
+  status: 'active' | 'stale' | 'revoked' | 'applied';
+  last_seen_at?: string;
+  applied_at?: string;
+  source_collision_id: string;
+};
+
+type ApprovedCollisionContext = {
+  override_id: string;
+  counterpart_feature_id: string;
+  rationale: string;
+  approved_paths: string[];
+  approved_collision_fingerprint: string;
+  source_collision_id: string;
+  detected_at: string;
+  applied_at?: string;
+  source_collision_record: CollisionRecord;
+};
+
+type OverrideEvaluation = {
+  approved: boolean;
+  matched_overrides: CollisionOverride[];
+  blocking_feature_ids: string[];
+};
+
+type OverrideListItem = CollisionOverride & {
+  latest_seen_at: string | null;
+  matches_live_collision: boolean;
+  applied_successfully: boolean;
+};
+
+export interface CollisionOverrideServicePort {
+  getPolicySnapshot(): AnyRecord;
+  planPath(featureId: string): string;
+  featureDiscoverSpecs(): Promise<{ data: { specs: Array<{ feature_id: string }> } }>;
+  readIndex(): Promise<AnyRecord>;
+  writeIndex(index: AnyRecord): Promise<void>;
+  withIndexLock<T>(operation: () => Promise<T>): Promise<T>;
+  featureLogAppend?(
+    featureId: string,
+    note: string,
+    context: FeatureContext,
+  ): Promise<{ data: { feature_id: string; appended: boolean; log_path: string } }>;
+  planSubmit?(
+    featureId: string,
+    plan: AnyRecord,
+    expectedVersion?: number | null,
+  ): Promise<{ data: { feature_id: string | null; accepted: boolean; plan_version: number } }>;
+  planGet?(featureId: string): Promise<{ data: { feature_id: string; plan: unknown } }>;
+  planUpdate?(
+    featureId: string,
+    expectedPlanVersion: number | null,
+    plan: AnyRecord,
+  ): Promise<{ data: { feature_id: string | null; accepted: boolean; plan_version: number } }>;
+}
+
+function asArray<T = unknown>(value: unknown): T[] {
+  return Array.isArray(value) ? (value as T[]) : [];
+}
+
+function normalizeSet(values: string[]): string[] {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+
+function defined<T>(value: T | null): value is T {
+  return value !== null;
+}
+
+function normalizeFeaturePair(featureId: string, withFeatureId: string): [string, string] {
+  return [featureId, withFeatureId].sort((left, right) => left.localeCompare(right)) as [
+    string,
+    string,
+  ];
+}
+
+function usableOverride(override: CollisionOverride): boolean {
+  return override.status === 'active' || override.status === 'applied';
+}
+
+function readCollisionRecords(index: AnyRecord): CollisionRecord[] {
+  return asArray(index.collision_records).filter(
+    (entry): entry is CollisionRecord => entry !== null && typeof entry === 'object',
+  );
+}
+
+function readCollisionOverrides(index: AnyRecord): CollisionOverride[] {
+  return asArray(index.collision_overrides).filter(
+    (entry): entry is CollisionOverride => entry !== null && typeof entry === 'object',
+  );
+}
+
+function samePair(featureIds: [string, string], override: CollisionOverride): boolean {
+  return override.feature_ids[0] === featureIds[0] && override.feature_ids[1] === featureIds[1];
+}
+
+function unresolvedCollisionRecord(record: CollisionRecord): boolean {
+  return record.resolution === 'rejected' || record.resolution === 'blocked';
+}
+
+function pairFingerprint(
+  featureId: string,
+  collisions: PlanCollisionsShape,
+  withFeatureId: string,
+): string {
+  return createCollisionFingerprint(
+    featureId,
+    collisionSubsetForFeature(collisions, withFeatureId),
+  );
+}
+
+function recordMatchesOverridePair(record: CollisionRecord, override: CollisionOverride): boolean {
+  return (
+    (record.feature_id === override.feature_ids[0] &&
+      record.with_feature_ids.includes(override.feature_ids[1])) ||
+    (record.feature_id === override.feature_ids[1] &&
+      record.with_feature_ids.includes(override.feature_ids[0]))
+  );
+}
+
+function buildCollisionEventNote(event: Record<string, unknown>): string {
+  return `collision_event ${JSON.stringify(event)}`;
+}
+
+function buildCurrentPlanExpectedVersion(plan: AnyRecord): number | null {
+  return Number.isInteger(plan.revision_of) ? Number(plan.revision_of) : null;
+}
+
+export class CollisionOverrideService {
+  private readonly port: CollisionOverrideServicePort;
+
+  constructor(port: CollisionOverrideServicePort) {
+    this.port = port;
+  }
+
+  private async collectAcceptedPlans(excludeFeatureId: string | null = null): Promise<PlanShape[]> {
+    const specs = await this.port.featureDiscoverSpecs();
+    const index = await this.port.readIndex();
+    const merged = new Set(asArray<string>(index.merged));
+    const plans: PlanShape[] = [];
+
+    for (const item of specs.data.specs) {
+      if (item.feature_id === excludeFeatureId || merged.has(item.feature_id)) {
+        continue;
+      }
+      const plan = await readJson<PlanShape>(this.port.planPath(item.feature_id), null);
+      if (plan) {
+        plans.push(plan);
+      }
+    }
+
+    return plans;
+  }
+
+  private async appendEventToFeatures(
+    featureIds: string[],
+    event: Record<string, unknown>,
+    context: FeatureContext,
+  ): Promise<void> {
+    if (!this.port.featureLogAppend) {
+      return;
+    }
+    const note = buildCollisionEventNote(event);
+    for (const featureId of normalizeSet(featureIds)) {
+      await this.port.featureLogAppend(featureId, note, context).catch(() => undefined);
+    }
+  }
+
+  private async resolveCurrentPairCollision(
+    record: CollisionRecord,
+    withFeatureId: string,
+  ): Promise<PlanCollisionPair> {
+    const policy = this.port.getPolicySnapshot() as PolicyShape;
+    const acceptedPlans = await this.collectAcceptedPlans(record.feature_id);
+    const planSnapshot = record.plan_snapshot as unknown as PlanShape;
+    const currentCollision = detectPlanCollisions(planSnapshot, acceptedPlans, policy);
+    const pair = splitPlanCollisionsByFeature(record.feature_id, currentCollision.collisions).find(
+      (entry) => entry.with_feature_id === withFeatureId,
+    );
+
+    if (!pair) {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.COLLISION_OVERRIDE_NOT_APPLICABLE,
+          'Recorded collision no longer exists for the requested feature pair',
+          {
+            feature_id: record.feature_id,
+            with_feature_id: withFeatureId,
+            source_collision_id: record.collision_id,
+            retryable: false,
+            requires_human: true,
+          },
+        ),
+      };
+    }
+
+    return pair;
+  }
+
+  async recordCollision(params: {
+    featureId: string;
+    sourceTool: 'plan.submit' | 'plan.update';
+    planVersion: number;
+    collisionFingerprint: string;
+    collisions: PlanCollisionsShape;
+    planSnapshot: Record<string, unknown>;
+    resolution: CollisionRecordResolution;
+    resolutionDetails?: CollisionRecord['resolution_details'];
+    context: FeatureContext;
+  }): Promise<CollisionRecord> {
+    const detectedAt = nowIso();
+    const withFeatureIds = normalizeSet(
+      splitPlanCollisionsByFeature(params.featureId, params.collisions).map(
+        (entry) => entry.with_feature_id,
+      ),
+    );
+
+    const record = await this.port.withIndexLock(async () => {
+      const index = await this.port.readIndex();
+      const collisionRecords = readCollisionRecords(index);
+
+      for (const existing of collisionRecords) {
+        if (
+          existing.feature_id !== params.featureId ||
+          existing.source_tool !== params.sourceTool ||
+          existing.plan_version !== params.planVersion
+        ) {
+          continue;
+        }
+        if (!unresolvedCollisionRecord(existing)) {
+          continue;
+        }
+        if (existing.collision_fingerprint !== params.collisionFingerprint) {
+          existing.resolution = 'superseded';
+          existing.resolution_details = {
+            resolved_at: detectedAt,
+            note: 'Superseded by a newer collision fingerprint for the same plan version',
+          };
+        }
+      }
+
+      const collisionRecord: CollisionRecord = {
+        collision_id: `colrec_${crypto.randomUUID()}`,
+        feature_id: params.featureId,
+        with_feature_ids: withFeatureIds,
+        source_tool: params.sourceTool,
+        plan_version: params.planVersion,
+        detected_at: detectedAt,
+        collision_fingerprint: params.collisionFingerprint,
+        collisions: params.collisions,
+        plan_snapshot: params.planSnapshot,
+        resolution: params.resolution,
+        ...(params.resolutionDetails ? { resolution_details: params.resolutionDetails } : {}),
+      };
+
+      collisionRecords.push(collisionRecord);
+      index.collision_records = collisionRecords;
+      index.version += 1;
+      index.updated_at = detectedAt;
+      await this.port.writeIndex(index);
+      return collisionRecord;
+    });
+
+    await this.appendEventToFeatures(
+      [params.featureId, ...withFeatureIds],
+      {
+        event_type: 'collision_record_created',
+        collision_id: record.collision_id,
+        feature_pair: normalizeSet([params.featureId, ...withFeatureIds]),
+        fingerprint: params.collisionFingerprint,
+        approved_paths: collectApprovedPaths(params.collisions),
+        rationale: null,
+        source_tool: params.sourceTool,
+      },
+      params.context,
+    );
+
+    return record;
+  }
+
+  async markCollisionRecordResolution(
+    collisionId: string,
+    resolution: CollisionRecordResolution,
+    resolutionDetails: CollisionRecord['resolution_details'],
+    context: FeatureContext,
+  ): Promise<void> {
+    const result = await this.port.withIndexLock(async () => {
+      const index = await this.port.readIndex();
+      const collisionRecords = readCollisionRecords(index);
+      const record = collisionRecords.find((item) => item.collision_id === collisionId);
+      if (!record) {
+        return null;
+      }
+
+      record.resolution = resolution;
+      record.resolution_details = resolutionDetails;
+      index.collision_records = collisionRecords;
+      index.version += 1;
+      index.updated_at = resolutionDetails?.resolved_at ?? nowIso();
+      await this.port.writeIndex(index);
+      return record;
+    });
+
+    if (!result) {
+      return;
+    }
+
+    await this.appendEventToFeatures(
+      [result.feature_id, ...result.with_feature_ids],
+      {
+        event_type: 'collision_record_updated',
+        collision_id: result.collision_id,
+        feature_pair: normalizeSet([result.feature_id, ...result.with_feature_ids]),
+        fingerprint: result.collision_fingerprint,
+        approved_paths: collectApprovedPaths(result.collisions),
+        rationale: resolutionDetails?.note ?? null,
+        resolution,
+      },
+      context,
+    );
+  }
+
+  async clearResolvedCollisionRecords(
+    featureId: string,
+    planVersion: number,
+    context: FeatureContext,
+  ): Promise<void> {
+    const cleared = await this.port.withIndexLock(async () => {
+      const index = await this.port.readIndex();
+      const collisionRecords = readCollisionRecords(index);
+      const now = nowIso();
+      const changed = collisionRecords.filter(
+        (record) =>
+          record.feature_id === featureId &&
+          record.plan_version === planVersion &&
+          unresolvedCollisionRecord(record),
+      );
+
+      if (changed.length === 0) {
+        return [] as CollisionRecord[];
+      }
+
+      for (const record of changed) {
+        record.resolution = 'cleared';
+        record.resolution_details = {
+          resolved_at: now,
+          note: 'Plan accepted without an active collision',
+        };
+      }
+
+      index.collision_records = collisionRecords;
+      index.version += 1;
+      index.updated_at = now;
+      await this.port.writeIndex(index);
+      return changed;
+    });
+
+    for (const record of cleared) {
+      await this.appendEventToFeatures(
+        [record.feature_id, ...record.with_feature_ids],
+        {
+          event_type: 'collision_record_cleared',
+          collision_id: record.collision_id,
+          feature_pair: normalizeSet([record.feature_id, ...record.with_feature_ids]),
+          fingerprint: record.collision_fingerprint,
+          approved_paths: collectApprovedPaths(record.collisions),
+          rationale: null,
+        },
+        context,
+      );
+    }
+  }
+
+  async evaluateApprovals(
+    featureId: string,
+    collisions: PlanCollisionsShape,
+    context: FeatureContext,
+  ): Promise<OverrideEvaluation> {
+    if (hasContractCollisions(collisions)) {
+      return {
+        approved: false,
+        matched_overrides: [],
+        blocking_feature_ids: normalizeSet(
+          collisions.contracts.map((entry) => entry.with_feature_id),
+        ),
+      };
+    }
+
+    const pairs = splitPlanCollisionsByFeature(featureId, collisions);
+    if (pairs.length === 0) {
+      return {
+        approved: true,
+        matched_overrides: [],
+        blocking_feature_ids: [],
+      };
+    }
+
+    return await this.port
+      .withIndexLock(async () => {
+        const index = await this.port.readIndex();
+        const overrides = readCollisionOverrides(index);
+        const updatedPairs = new Set<string>();
+        const matched: CollisionOverride[] = [];
+        const newlyApplied: CollisionOverride[] = [];
+        const blockingFeatureIds: string[] = [];
+        const currentAt = nowIso();
+
+        for (const pair of pairs) {
+          const featurePair = normalizeFeaturePair(featureId, pair.with_feature_id);
+          const candidates = overrides.filter((entry) => samePair(featurePair, entry));
+          const matching = candidates.find(
+            (entry) =>
+              usableOverride(entry) && entry.approved_collision_fingerprint === pair.fingerprint,
+          );
+
+          if (matching) {
+            matching.last_seen_at = currentAt;
+            if (matching.status === 'active') {
+              matching.status = 'applied';
+              newlyApplied.push(matching);
+            }
+            if (!matching.applied_at) {
+              matching.applied_at = currentAt;
+              if (!newlyApplied.includes(matching)) {
+                newlyApplied.push(matching);
+              }
+            }
+            matched.push(matching);
+            updatedPairs.add(pair.with_feature_id);
+            continue;
+          }
+
+          const staleCandidates = candidates.filter(
+            (entry) =>
+              usableOverride(entry) && entry.approved_collision_fingerprint !== pair.fingerprint,
+          );
+          for (const entry of staleCandidates) {
+            entry.status = 'stale';
+            entry.last_seen_at = currentAt;
+          }
+          if (staleCandidates.length > 0) {
+            updatedPairs.add(pair.with_feature_id);
+          }
+          blockingFeatureIds.push(pair.with_feature_id);
+        }
+
+        if (updatedPairs.size > 0) {
+          index.collision_overrides = overrides;
+          index.version += 1;
+          index.updated_at = currentAt;
+          await this.port.writeIndex(index);
+        }
+
+        return {
+          approved: blockingFeatureIds.length === 0,
+          matched_overrides: matched,
+          blocking_feature_ids: normalizeSet(blockingFeatureIds),
+          newly_applied: newlyApplied,
+        };
+      })
+      .then(async (result) => {
+        for (const override of result.newly_applied) {
+          await this.appendEventToFeatures(
+            [...override.feature_ids],
+            {
+              event_type: 'collision_override_applied',
+              override_id: override.override_id,
+              feature_pair: override.feature_ids,
+              fingerprint: override.approved_collision_fingerprint,
+              approved_paths: override.approved_paths,
+              rationale: override.rationale,
+            },
+            context,
+          );
+        }
+
+        return {
+          approved: result.approved,
+          matched_overrides: result.matched_overrides,
+          blocking_feature_ids: result.blocking_feature_ids,
+        };
+      });
+  }
+
+  async allowOverride(params: {
+    featureId: string;
+    withFeatureId: string;
+    reason: string;
+    resume?: boolean;
+    createdBy: string;
+  }): Promise<{
+    override_id: string;
+    feature_ids: [string, string];
+    collision_fingerprint: string;
+    approved_paths: string[];
+    resumed: boolean;
+  }> {
+    const context: FeatureContext = {
+      actorType: 'system',
+      actorId: params.createdBy,
+    };
+
+    const record = await this.port.withIndexLock(async () => {
+      const index = await this.port.readIndex();
+      const collisionRecords = readCollisionRecords(index)
+        .filter(
+          (entry) =>
+            entry.feature_id === params.featureId &&
+            entry.with_feature_ids.includes(params.withFeatureId) &&
+            unresolvedCollisionRecord(entry),
+        )
+        .sort((left, right) => right.detected_at.localeCompare(left.detected_at));
+      return collisionRecords[0] ?? null;
+    });
+
+    if (!record) {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.COLLISION_RECORD_NOT_FOUND,
+          'No unresolved collision record exists for the requested feature pair',
+          {
+            feature_id: params.featureId,
+            with_feature_id: params.withFeatureId,
+            retryable: false,
+            requires_human: true,
+          },
+        ),
+      };
+    }
+
+    const recordedPairFingerprint = pairFingerprint(
+      params.featureId,
+      record.collisions,
+      params.withFeatureId,
+    );
+    const currentPair = await this.resolveCurrentPairCollision(record, params.withFeatureId);
+
+    if (currentPair.fingerprint !== recordedPairFingerprint) {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.COLLISION_OVERRIDE_STALE,
+          'The current collision fingerprint no longer matches the recorded collision',
+          {
+            feature_id: params.featureId,
+            with_feature_id: params.withFeatureId,
+            source_collision_id: record.collision_id,
+            recorded_collision_fingerprint: recordedPairFingerprint,
+            current_collision_fingerprint: currentPair.fingerprint,
+            retryable: false,
+            requires_human: true,
+          },
+        ),
+      };
+    }
+
+    if (hasContractCollisions(currentPair.collisions)) {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.COLLISION_OVERRIDE_CONTRACT_FORBIDDEN,
+          'Contract collisions cannot be approved with an intentional collision override',
+          {
+            feature_id: params.featureId,
+            with_feature_id: params.withFeatureId,
+            source_collision_id: record.collision_id,
+            collision_fingerprint: currentPair.fingerprint,
+            retryable: false,
+            requires_human: true,
+          },
+        ),
+      };
+    }
+
+    const override = await this.port.withIndexLock(async () => {
+      const index = await this.port.readIndex();
+      const overrides = readCollisionOverrides(index);
+      const featureIds = normalizeFeaturePair(params.featureId, params.withFeatureId);
+      const existing = overrides.find(
+        (entry) =>
+          samePair(featureIds, entry) &&
+          usableOverride(entry) &&
+          entry.approved_collision_fingerprint === currentPair.fingerprint,
+      );
+
+      if (existing) {
+        existing.last_seen_at = nowIso();
+        index.collision_overrides = overrides;
+        index.version += 1;
+        index.updated_at = existing.last_seen_at;
+        await this.port.writeIndex(index);
+        return existing;
+      }
+
+      const createdAt = nowIso();
+      const nextOverride: CollisionOverride = {
+        override_id: `colovr_${crypto.randomUUID()}`,
+        feature_ids: featureIds,
+        created_at: createdAt,
+        created_by: params.createdBy,
+        rationale: params.reason,
+        approved_collision_fingerprint: currentPair.fingerprint,
+        approved_paths: currentPair.approved_paths,
+        approved_with_feature_ids: [params.withFeatureId],
+        status: 'active',
+        last_seen_at: createdAt,
+        source_collision_id: record.collision_id,
+      };
+
+      overrides.push(nextOverride);
+      index.collision_overrides = overrides;
+      index.version += 1;
+      index.updated_at = createdAt;
+      await this.port.writeIndex(index);
+      return nextOverride;
+    });
+
+    await this.appendEventToFeatures(
+      [...override.feature_ids],
+      {
+        event_type: 'collision_override_created',
+        override_id: override.override_id,
+        feature_pair: override.feature_ids,
+        fingerprint: override.approved_collision_fingerprint,
+        approved_paths: override.approved_paths,
+        rationale: override.rationale,
+      },
+      context,
+    );
+
+    let resumed = false;
+    if (params.resume) {
+      if (!this.port.planSubmit || !this.port.planGet || !this.port.planUpdate) {
+        throw {
+          normalizedResponse: fail(
+            ERROR_CODES.INTERNAL_ERROR,
+            'Collision override resume is not available in this runtime context',
+            {
+              feature_id: params.featureId,
+              with_feature_id: params.withFeatureId,
+              retryable: false,
+              requires_human: true,
+            },
+          ),
+        };
+      }
+      const resumePlan = record.plan_snapshot as AnyRecord;
+      try {
+        await this.port.planSubmit(
+          params.featureId,
+          resumePlan,
+          buildCurrentPlanExpectedVersion(resumePlan),
+        );
+      } catch (error) {
+        const recovered = await recoverStalePlanSubmitConflict({
+          error,
+          featureId: params.featureId,
+          submittedPlan: asPlanRecord(resumePlan),
+          readAcceptedPlan: async (featureId) => (await this.port.planGet(featureId)).data.plan,
+          submitPlanUpdate: async (featureId, expectedPlanVersion, nextPlan) =>
+            await this.port.planUpdate(featureId, expectedPlanVersion, nextPlan),
+          buildEquivalentSuccess: (featureId, currentPlanVersion) => ({
+            data: {
+              feature_id: featureId,
+              accepted: true,
+              plan_version: currentPlanVersion,
+            },
+          }),
+        });
+        if (!recovered) {
+          throw error;
+        }
+      }
+      resumed = true;
+    }
+
+    return {
+      override_id: override.override_id,
+      feature_ids: override.feature_ids,
+      collision_fingerprint: override.approved_collision_fingerprint,
+      approved_paths: override.approved_paths,
+      resumed,
+    };
+  }
+
+  async listOverrides(featureId?: string): Promise<OverrideListItem[]> {
+    const index = await this.port.readIndex();
+    const overrides = readCollisionOverrides(index);
+    const collisionRecords = readCollisionRecords(index);
+    const filtered = featureId
+      ? overrides.filter((entry) => entry.feature_ids.includes(featureId))
+      : overrides;
+
+    return filtered
+      .map((override) => {
+        const latestRecord = collisionRecords
+          .filter((record) => recordMatchesOverridePair(record, override))
+          .sort((left, right) => right.detected_at.localeCompare(left.detected_at))[0];
+
+        const latestCounterpart =
+          latestRecord?.feature_id === override.feature_ids[0]
+            ? override.feature_ids[1]
+            : override.feature_ids[0];
+        const latestFingerprint =
+          latestRecord && latestCounterpart
+            ? pairFingerprint(latestRecord.feature_id, latestRecord.collisions, latestCounterpart)
+            : null;
+
+        return {
+          ...override,
+          latest_seen_at: latestRecord?.detected_at ?? null,
+          matches_live_collision:
+            latestRecord !== undefined &&
+            unresolvedCollisionRecord(latestRecord) &&
+            latestFingerprint === override.approved_collision_fingerprint,
+          applied_successfully: Boolean(override.applied_at),
+        };
+      })
+      .sort((left, right) => right.created_at.localeCompare(left.created_at));
+  }
+
+  async revokeOverride(overrideId: string, revokedBy: string): Promise<CollisionOverride> {
+    const context: FeatureContext = {
+      actorType: 'system',
+      actorId: revokedBy,
+    };
+
+    const override = await this.port.withIndexLock(async () => {
+      const index = await this.port.readIndex();
+      const overrides = readCollisionOverrides(index);
+      const existing = overrides.find((entry) => entry.override_id === overrideId);
+      if (!existing) {
+        throw {
+          normalizedResponse: fail(
+            ERROR_CODES.COLLISION_OVERRIDE_NOT_FOUND,
+            'Collision override was not found',
+            {
+              override_id: overrideId,
+              retryable: false,
+              requires_human: true,
+            },
+          ),
+        };
+      }
+
+      existing.status = 'revoked';
+      existing.last_seen_at = nowIso();
+      index.collision_overrides = overrides;
+      index.version += 1;
+      index.updated_at = existing.last_seen_at;
+      await this.port.writeIndex(index);
+      return existing;
+    });
+
+    await this.appendEventToFeatures(
+      [...override.feature_ids],
+      {
+        event_type: 'collision_override_revoked',
+        override_id: override.override_id,
+        feature_pair: override.feature_ids,
+        fingerprint: override.approved_collision_fingerprint,
+        approved_paths: override.approved_paths,
+        rationale: override.rationale,
+      },
+      context,
+    );
+
+    return override;
+  }
+
+  async staleOverridesForFeature(featureId: string, note: string, actorId: string): Promise<void> {
+    const context: FeatureContext = {
+      actorType: 'system',
+      actorId,
+    };
+
+    const stale = await this.port.withIndexLock(async () => {
+      const index = await this.port.readIndex();
+      const overrides = readCollisionOverrides(index);
+      const changed = overrides.filter(
+        (entry) => entry.feature_ids.includes(featureId) && usableOverride(entry),
+      );
+      if (changed.length === 0) {
+        return [] as CollisionOverride[];
+      }
+
+      const staleAt = nowIso();
+      for (const entry of changed) {
+        entry.status = 'stale';
+        entry.last_seen_at = staleAt;
+      }
+      index.collision_overrides = overrides;
+      index.version += 1;
+      index.updated_at = staleAt;
+      await this.port.writeIndex(index);
+      return changed;
+    });
+
+    for (const override of stale) {
+      await this.appendEventToFeatures(
+        [...override.feature_ids],
+        {
+          event_type: 'collision_override_stale',
+          override_id: override.override_id,
+          feature_pair: override.feature_ids,
+          fingerprint: override.approved_collision_fingerprint,
+          approved_paths: override.approved_paths,
+          rationale: note,
+        },
+        context,
+      );
+    }
+  }
+
+  async approvedCollisionContextsForFeature(
+    featureId: string,
+  ): Promise<ApprovedCollisionContext[]> {
+    const index = await this.port.readIndex();
+    const overrides = readCollisionOverrides(index).filter(
+      (entry) => entry.feature_ids.includes(featureId) && usableOverride(entry),
+    );
+    const records = readCollisionRecords(index);
+
+    return overrides
+      .map((override) => {
+        const sourceRecord = records.find(
+          (record) => record.collision_id === override.source_collision_id,
+        );
+        if (!sourceRecord) {
+          return null;
+        }
+
+        return {
+          override_id: override.override_id,
+          counterpart_feature_id:
+            override.feature_ids[0] === featureId
+              ? override.feature_ids[1]
+              : override.feature_ids[0],
+          rationale: override.rationale,
+          approved_paths: override.approved_paths,
+          approved_collision_fingerprint: override.approved_collision_fingerprint,
+          source_collision_id: override.source_collision_id,
+          detected_at: sourceRecord.detected_at,
+          applied_at: override.applied_at,
+          source_collision_record: sourceRecord,
+        };
+      })
+      .filter(defined);
+  }
+}