@moretea-labs/forge 1.6.0 → 1.7.1

package/src/runtime/control-plane/execution/repository-work-attribution.ts

@@ -0,0 +1,106 @@
+import { readExecutionSession } from './session-store';
+import { controllerSessionPrincipalId, getControllerSession, listControllerSessions } from '../facade/controller-session-store';
+import { getWorkContract } from '../facade/work-contract-store';
+import { isTerminalWorkContractStatus } from '../facade/types';
+
+export interface RepositoryWorkAttributionCaller {
+  sessionId?: string;
+  principalId?: string;
+  controllerInstanceId?: string;
+}
+
+export interface RepositoryWorkAttributionTarget {
+  repoId: string;
+  activeCheckoutId: string;
+}
+
+export function resolveExplicitClaimedRepositoryWork(
+  controllerHome: string,
+  target: RepositoryWorkAttributionTarget,
+  caller: RepositoryWorkAttributionCaller | undefined,
+  workId: string,
+) {
+  if (!caller?.principalId?.trim()) return undefined;
+  const work = getWorkContract({ controllerHome, repoId: target.repoId }, workId);
+  if (!work || isTerminalWorkContractStatus(work.status)) throw new Error(`WORK_ATTRIBUTION_INVALID: ${workId}`);
+  const owner = getControllerSession({ controllerHome, repoId: target.repoId }, workId);
+  if (!owner) throw new Error(`WORK_CONTROLLER_CLAIM_REQUIRED: ${workId}`);
+  if (controllerSessionPrincipalId(owner) !== caller.principalId.trim()) {
+    throw new Error(`WORK_CONTROLLER_OWNERSHIP_MISMATCH: ${workId}`);
+  }
+  if (work.checkoutId && work.checkoutId !== target.activeCheckoutId) {
+    throw new Error(
+      `WORK_CHECKOUT_MISMATCH: work=${workId}; resolved_checkout=${target.activeCheckoutId}; expected_work_checkout=${work.checkoutId}; retry with checkout_id=${work.checkoutId} and the same work_id`,
+    );
+  }
+  return work;
+}
+
+export function assertNoBoundExecutionSessionMutation(
+  controllerHome: string,
+  target: RepositoryWorkAttributionTarget,
+  caller?: RepositoryWorkAttributionCaller,
+): void {
+  if (!caller?.principalId?.trim() || !caller.sessionId?.trim()) return;
+  const executionSession = readExecutionSession(controllerHome, {
+    sessionId: caller.sessionId,
+    principalId: caller.principalId,
+    controllerInstanceId: caller.controllerInstanceId,
+  });
+  const workId = executionSession?.activeWorkId?.trim();
+  if (!workId || executionSession?.activeRepositoryId !== target.repoId) return;
+  const work = getWorkContract({ controllerHome, repoId: target.repoId }, workId);
+  if (!work) throw new Error(`WORK_ATTRIBUTION_INVALID: ${workId}`);
+  if (isTerminalWorkContractStatus(work.status)) {
+    throw new Error(`WORK_ATTRIBUTION_TERMINAL: ${work.workId}:${work.status}`);
+  }
+  throw new Error(`WORK_ATTRIBUTION_REQUIRED: ${work.workId}; active execution session mutations must pass work_id explicitly`);
+}
+
+export function resolveClaimedRepositoryWorkId(
+  controllerHome: string,
+  target: RepositoryWorkAttributionTarget,
+  caller?: RepositoryWorkAttributionCaller,
+  explicitWorkId?: unknown,
+): string | undefined {
+  const requestedWorkId = typeof explicitWorkId === 'string' ? explicitWorkId.trim() : '';
+  if (requestedWorkId) {
+    const work = resolveExplicitClaimedRepositoryWork(controllerHome, target, caller, requestedWorkId);
+    return work?.workId;
+  }
+  if (!caller?.principalId?.trim()) return undefined;
+  if (caller.sessionId?.trim()) {
+    const executionSession = readExecutionSession(controllerHome, {
+      sessionId: caller.sessionId,
+      principalId: caller.principalId,
+      controllerInstanceId: caller.controllerInstanceId,
+    });
+    const workId = executionSession?.activeWorkId?.trim();
+    if (workId
+      && executionSession?.activeRepositoryId === target.repoId
+      && (!executionSession.activeCheckoutId || executionSession.activeCheckoutId === target.activeCheckoutId)) {
+      const work = getWorkContract({ controllerHome, repoId: target.repoId }, workId);
+      if (work && isTerminalWorkContractStatus(work.status)) {
+        throw new Error(`WORK_ATTRIBUTION_TERMINAL: ${work.workId}:${work.status}`);
+      }
+      const owner = getControllerSession({ controllerHome, repoId: target.repoId }, workId);
+      if (work && owner?.sessionId === caller.sessionId && controllerSessionPrincipalId(owner) === caller.principalId.trim()) {
+        return workId;
+      }
+    }
+  }
+  const principal = caller.principalId.trim();
+  const candidates = listControllerSessions({ controllerHome, repoId: target.repoId })
+    .filter((owner) => controllerSessionPrincipalId(owner) === principal)
+    .map((owner) => ({ owner, work: getWorkContract({ controllerHome, repoId: target.repoId }, owner.workId) }))
+    .filter((entry): entry is { owner: ReturnType<typeof listControllerSessions>[number]; work: NonNullable<ReturnType<typeof getWorkContract>> } => Boolean(
+      entry.work
+      && !isTerminalWorkContractStatus(entry.work.status)
+      && (!entry.work.checkoutId || entry.work.checkoutId === target.activeCheckoutId),
+    ));
+  if (candidates.length === 1) return candidates[0].work.workId;
+  if (candidates.length > 1) {
+    throw new Error(`WORK_ATTRIBUTION_AMBIGUOUS: principal ${principal} owns ${candidates.length} active Works on checkout ${target.activeCheckoutId}`);
+  }
+  return undefined;
+}

package/src/runtime/control-plane/execution/retained-work-resume.ts

@@ -0,0 +1,203 @@
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+import type { RepositoryRecord } from '../../../cli/repositories/types';
+import { listRepositories, selectRepositoryCheckout } from '../../../cli/repositories/registry';
+import { repositoryGitStatus } from '../../../cli/repositories/structured-git';
+import { ensureManagedWorkspace } from '../../execution/managed-workspace';
+import { getControllerSession } from '../facade/controller-session-store';
+import { getWorkContract, resumeRetainedCancelledWorkContract, updateWorkContract } from '../facade/work-contract-store';
+import { gitCommitAtRef, gitWorktreeSnapshot } from './work-lifecycle-audit';
+import { readWorkHandle, writeWorkHandle } from './work-handle-store';
+
+export interface RetainedWorkResumeIdentity {
+  principalId: string;
+  sessionId: string;
+  controllerInstanceId: string;
+}
+
+export interface ReauthorizeRetainedCancelledWorkInput {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  workId: string;
+  identity: RetainedWorkResumeIdentity;
+  requestedBy?: string;
+  approvalConfirmed?: boolean;
+  prepareDependencies?: boolean;
+}
+
+/**
+ * Canonical orchestration authority for explicitly re-authorizing the exact
+ * retained cancelled repository Work. Transport adapters provide authenticated
+ * identity and typed user intent only; they must not duplicate these lifecycle,
+ * ownership, zero-delta, or reconstruction rules.
+ */
+export function reauthorizeRetainedCancelledRepositoryWork(
+  input: ReauthorizeRetainedCancelledWorkInput,
+): { reconstructedCheckout: boolean } {
+  const { controllerHome, repository, workId, identity } = input;
+  const store = { controllerHome, repoId: repository.repoId };
+  let work = getWorkContract(store, workId);
+  if (!work || work.status !== 'cancelled') return { reconstructedCheckout: false };
+  if (input.approvalConfirmed !== true || input.requestedBy !== 'user') {
+    throw new Error(`WORK_CANCELLED_RESUME_REAUTHORIZATION_REQUIRED: ${workId}; use exact work_id with requested_by=user and approval_confirmed=true`);
+  }
+  if (!work.principalId?.trim() || work.principalId.trim() !== identity.principalId) {
+    throw new Error(`WORK_CANCELLED_RESUME_PRINCIPAL_MISMATCH: ${workId}`);
+  }
+  const owner = getControllerSession(store, workId);
+  if (owner && (owner.principalId?.trim() || owner.controllerId) !== identity.principalId) {
+    throw new Error(`WORK_CANCELLED_RESUME_CONTROLLER_OWNERSHIP_MISMATCH: ${workId}`);
+  }
+  if (work.completionReceipt || work.completionOutcome) throw new Error(`WORK_CANCELLED_RESUME_COMPLETION_CONFLICT: ${workId}`);
+  if (work.reconciliations.length > 0) throw new Error(`WORK_CANCELLED_RESUME_DELIVERY_HISTORY_AMBIGUOUS: ${workId}`);
+  if (work.phase !== 'cleanup' || work.phaseEvidence.cleanup.state !== 'skipped' || work.phaseEvidence.cleanup.source !== 'recorded') {
+    throw new Error(`WORK_CANCELLED_RESUME_HISTORY_AMBIGUOUS: ${workId}`);
+  }
+  if (work.workKind !== 'repository_change' || work.worktreePolicy.required !== true) {
+    throw new Error(`WORK_CANCELLED_RESUME_ISOLATED_REPOSITORY_WORK_REQUIRED: ${workId}`);
+  }
+
+  let handle = readWorkHandle(controllerHome, repository.repoId, workId);
+  if (handle) {
+    if (handle.repositoryId !== repository.repoId || (handle.workContractId && handle.workContractId !== workId)) {
+      throw new Error(`WORK_CANCELLED_RESUME_HANDLE_IDENTITY_MISMATCH: ${workId}`);
+    }
+    if (handle.principalId !== identity.principalId) throw new Error(`WORK_CANCELLED_RESUME_HANDLE_PRINCIPAL_MISMATCH: ${workId}`);
+    if (['committed', 'merged', 'cleaned', 'failed_terminal_cleanup'].includes(handle.state)
+      || handle.finalization.commit === 'done'
+      || handle.finalization.merge === 'done'
+      || handle.cleanupReceipt?.complete === true) {
+      throw new Error(`WORK_CANCELLED_RESUME_DELIVERY_OR_CLEANUP_CONFLICT: ${workId}`);
+    }
+  }
+
+  const registryRepository = listRepositories(controllerHome, { includeRemoved: true })
+    .find((candidate) => candidate.repoId === repository.repoId);
+  if (!registryRepository) throw new Error(`WORK_CANCELLED_RESUME_REPOSITORY_MISSING: ${workId}`);
+  const recordedCheckoutId = work.checkoutId?.trim();
+  const recordedWorktree = work.worktreeRef?.trim();
+  const checkoutRecord = recordedCheckoutId
+    ? registryRepository.checkouts.find((candidate) => candidate.checkoutId === recordedCheckoutId)
+    : undefined;
+  const checkoutActive = checkoutRecord?.lifecycle === 'active';
+  const worktreePresent = Boolean(recordedWorktree && existsSync(recordedWorktree));
+
+  if (checkoutActive && worktreePresent && recordedCheckoutId && recordedWorktree) {
+    const retained = selectRepositoryCheckout(registryRepository, recordedCheckoutId);
+    if (resolve(retained.canonicalRoot) !== resolve(recordedWorktree)) {
+      throw new Error(`WORK_CANCELLED_RESUME_CHECKOUT_REUSED: ${workId}`);
+    }
+    if (!handle) throw new Error(`WORK_CANCELLED_RESUME_HANDLE_REQUIRED: ${workId}`);
+    if (handle.checkoutId !== recordedCheckoutId || resolve(handle.worktreePath) !== resolve(recordedWorktree)) {
+      throw new Error(`WORK_CANCELLED_RESUME_CHECKOUT_OWNERSHIP_MISMATCH: ${workId}`);
+    }
+    const status = repositoryGitStatus(retained);
+    if (!status.branch || status.branch !== handle.branch) throw new Error(`WORK_CANCELLED_RESUME_BRANCH_OWNERSHIP_MISMATCH: ${workId}`);
+    writeWorkHandle(controllerHome, {
+      ...handle,
+      principalId: identity.principalId,
+      sessionId: identity.sessionId,
+      updatedAt: new Date().toISOString(),
+    });
+    resumeRetainedCancelledWorkContract(store, workId, {
+      principalId: identity.principalId,
+      controllerInstanceId: identity.controllerInstanceId,
+      summary: 'Explicit current user re-authorized the same retained cancelled Work; exact managed checkout ownership was revalidated.',
+    });
+    return { reconstructedCheckout: false };
+  }
+
+  if (checkoutActive) throw new Error(`WORK_CANCELLED_RESUME_PRESERVATION_AMBIGUOUS: ${workId}`);
+  if (!recordedCheckoutId || !recordedWorktree || !handle) throw new Error(`WORK_CANCELLED_RESUME_HANDLE_REQUIRED: ${workId}`);
+
+  const actualChangedPaths = work.scopeEvidence?.actualChangedPaths;
+  if (!actualChangedPaths || actualChangedPaths.length !== 0
+    || work.checks.length !== 0
+    || work.checkRefs.length !== 0
+    || work.evidenceState !== 'none') {
+    throw new Error(`WORK_CANCELLED_RESUME_ZERO_DELTA_PROOF_REQUIRED: ${workId}`);
+  }
+  const recordedBase = work.baseRevision?.trim();
+  if (!recordedBase) throw new Error(`WORK_CANCELLED_RESUME_BASE_REVISION_REQUIRED: ${workId}`);
+  const baseRevision = gitCommitAtRef(repository.canonicalRoot, recordedBase);
+  if (!baseRevision) throw new Error(`WORK_CANCELLED_RESUME_BASE_REVISION_MISSING: ${workId}`);
+  const handleBase = handle.baseCommit ? gitCommitAtRef(repository.canonicalRoot, handle.baseCommit) : undefined;
+  const handleHead = handle.expectedHead ? gitCommitAtRef(repository.canonicalRoot, handle.expectedHead) : undefined;
+  if ((handle.baseCommit && handleBase !== baseRevision) || (handle.expectedHead && handleHead !== baseRevision)) {
+    throw new Error(`WORK_CANCELLED_RESUME_REVISION_AMBIGUOUS: ${workId}`);
+  }
+  if (handle.checkoutId !== recordedCheckoutId || resolve(handle.worktreePath) !== resolve(recordedWorktree)) {
+    throw new Error(`WORK_CANCELLED_RESUME_CHECKOUT_OWNERSHIP_MISMATCH: ${workId}`);
+  }
+  if (handle.branch) {
+    const historicalBranchHead = gitCommitAtRef(repository.canonicalRoot, `refs/heads/${handle.branch}`);
+    if (historicalBranchHead && historicalBranchHead !== baseRevision) {
+      throw new Error(`WORK_CANCELLED_RESUME_UNIQUE_COMMIT_CONFLICT: ${workId}`);
+    }
+  }
+  if (worktreePresent) {
+    const retainedSnapshot = gitWorktreeSnapshot(recordedWorktree);
+    if (!retainedSnapshot || !retainedSnapshot.clean || retainedSnapshot.head !== baseRevision || (handle.branch && retainedSnapshot.branch !== handle.branch)) {
+      throw new Error(`WORK_CANCELLED_RESUME_ZERO_DELTA_PHYSICAL_CONFLICT: ${workId}`);
+    }
+  }
+
+  const branchName = `work/resume-${workId.replace(/[^A-Za-z0-9._-]+/g, '-').slice(0, 42)}-${baseRevision.slice(0, 12)}`;
+  const existingResumeBranch = gitCommitAtRef(repository.canonicalRoot, `refs/heads/${branchName}`);
+  if (existingResumeBranch && existingResumeBranch !== baseRevision) {
+    throw new Error(`WORK_CANCELLED_RESUME_RECONSTRUCTION_BRANCH_CONFLICT: ${workId}`);
+  }
+  const workspace = ensureManagedWorkspace(controllerHome, repository, {
+    requestId: `${workId}:explicit-user-resume:${baseRevision}`,
+    title: `${work.objective} explicit user resume`,
+    branchName,
+    baseRef: baseRevision,
+    prepareDependencies: input.prepareDependencies === true,
+  });
+  if (!workspace.managed || !workspace.checkoutId || !workspace.root || !workspace.branch) {
+    throw new Error(`WORK_CANCELLED_RESUME_RECONSTRUCTION_FAILED: ${workId}`);
+  }
+  const refreshedRepository = listRepositories(controllerHome, { includeRemoved: true })
+    .find((candidate) => candidate.repoId === repository.repoId);
+  if (!refreshedRepository) throw new Error(`WORK_CANCELLED_RESUME_REPOSITORY_MISSING: ${workId}`);
+  const reconstructed = selectRepositoryCheckout(refreshedRepository, workspace.checkoutId);
+  const reconstructedStatus = repositoryGitStatus(reconstructed);
+  if (!reconstructedStatus.clean || reconstructedStatus.head !== baseRevision || reconstructedStatus.branch !== workspace.branch) {
+    throw new Error(`WORK_CANCELLED_RESUME_RECONSTRUCTION_REVISION_MISMATCH: ${workId}`);
+  }
+
+  work = updateWorkContract(store, workId, {
+    checkoutId: workspace.checkoutId,
+    worktreeRef: workspace.root,
+    baseRevision,
+    controllerInstanceId: identity.controllerInstanceId,
+  });
+  const now = new Date().toISOString();
+  handle = writeWorkHandle(controllerHome, {
+    ...handle,
+    principalId: identity.principalId,
+    sessionId: identity.sessionId,
+    checkoutId: workspace.checkoutId,
+    worktreePath: workspace.root,
+    branch: workspace.branch,
+    sourceCheckoutId: repository.activeCheckoutId,
+    managedWorktree: true,
+    baseCommit: baseRevision,
+    deliveryBaseCommit: baseRevision,
+    expectedHead: baseRevision,
+    state: 'prepared',
+    validatedInputFingerprint: undefined,
+    failureReason: undefined,
+    cleanupReceipt: undefined,
+    finalization: { validation: 'pending', commit: 'pending', merge: 'pending', branchCleanup: 'pending', worktreeCleanup: 'pending' },
+    updatedAt: now,
+  });
+  resumeRetainedCancelledWorkContract(store, workId, {
+    principalId: identity.principalId,
+    controllerInstanceId: identity.controllerInstanceId,
+    summary: 'Explicit current user re-authorized the same cancelled Work; prior managed checkout was absent and a fresh isolated checkout was reconstructed at the exact zero-delta base revision.',
+    checkoutId: workspace.checkoutId,
+    worktreeRef: workspace.root,
+  });
+  return { reconstructedCheckout: true };
+}

package/src/runtime/control-plane/execution/session-store.ts

@@ -163,6 +163,24 @@ export function updateExecutionSession(
   return updated;
 }
 
+export function invalidateExecutionSession(
+  controllerHome: string,
+  sessionId: string,
+  reason: string,
+): ExecutionSessionContext | undefined {
+  const current = peekExecutionSession(controllerHome, sessionId);
+  if (!current || current.invalidatedAt) return current;
+  const at = now();
+  const invalidated: ExecutionSessionContext = {
+    ...current,
+    updatedAt: at,
+    invalidatedAt: at,
+    invalidationReason: reason.trim().slice(0, 512) || 'transport session closed',
+  };
+  writeExecutionSession(controllerHome, invalidated, 'session_invalidated');
+  return invalidated;
+}
+
 function writeExecutionSession(controllerHome: string, session: ExecutionSessionContext, action: string): void {
   writeControlPlaneRecord(controllerHome, {
     namespace: 'execution_session',

package/src/runtime/control-plane/execution/verification-evidence.ts

@@ -14,7 +14,6 @@ export interface VerificationEvidenceIdentity {
   workspaceFingerprint?: string;
   checkId: string;
   requestedChecks: string[];
-  commandId?: string;
 }
 
 export interface EffectiveVerificationEvidence {
@@ -23,6 +22,12 @@ export interface EffectiveVerificationEvidence {
   staleReason?: string;
 }
 
+export interface HistoricalVerificationEvidenceIdentity extends Omit<VerificationEvidenceIdentity, 'workspaceFingerprint'> {
+  repoId: string;
+  workId: string;
+  checkoutId?: string;
+}
+
 function decodeGitQuotedPath(rawPath: string): string {
   if (!rawPath.startsWith('"') && !rawPath.endsWith('"')) return rawPath;
   if (!rawPath.startsWith('"') || !rawPath.endsWith('"')) {
@@ -146,14 +151,13 @@ export function workValidationInputFingerprint(
   })).digest('hex');
 }
 
-/** Stable identity for inputs that make a check result reusable. */
+/** Stable identity for semantic inputs that make a check result reusable. Invocation ids are audited separately. */
 export function verificationInputFingerprint(input: VerificationEvidenceIdentity): string {
   return createHash('sha256').update(JSON.stringify({
     sourceRevision: input.sourceRevision,
     workspaceFingerprint: input.workspaceFingerprint ?? null,
     checkId: input.checkId,
     requestedChecks: [...input.requestedChecks].sort(),
-    commandId: input.commandId ?? null,
   })).digest('hex');
 }
 
@@ -161,6 +165,57 @@ export function commandFingerprint(checkId: string, commandId: string | undefine
   return createHash('sha256').update(JSON.stringify({ checkId, commandId: commandId ?? null })).digest('hex');
 }
 
+/**
+ * Selects immutable Work-bound verification evidence for an explicit historical
+ * revision. Unlike current-workspace reuse, the historical workspace identity
+ * comes from each durable receipt record and is verified against the record's
+ * persisted semantic and command fingerprints.
+ */
+export function historicalVerificationEvidenceAtRevision(
+  records: VerificationRecord[],
+  expected: HistoricalVerificationEvidenceIdentity,
+): EffectiveVerificationEvidence[] {
+  return records
+    .filter((record) => record.checkId === expected.checkId)
+    .map((record) => {
+      if (record.supersedes || record.outcome === 'superseded') {
+        return { record, current: false, staleReason: 'superseded' };
+      }
+      if (!record.sourceRevision || !record.workspaceFingerprint || !record.verificationInputFingerprint || !record.commandFingerprint) {
+        return { record, current: false, staleReason: 'historical evidence has no exact input identity' };
+      }
+      if (record.sourceRevision !== expected.sourceRevision) {
+        return { record, current: false, staleReason: `source revision changed: ${record.sourceRevision} -> ${expected.sourceRevision}` };
+      }
+      const receipt = record.receipt;
+      if (
+        !receipt
+        || receipt.repoId !== expected.repoId
+        || receipt.workId !== expected.workId
+        || receipt.checkId !== expected.checkId
+        || (expected.checkoutId !== undefined && receipt.checkoutId !== expected.checkoutId)
+      ) {
+        return { record, current: false, staleReason: 'historical receipt identity changed' };
+      }
+      if (receipt.status !== 'passed' || receipt.runtimeStatus !== 'succeeded' || !receipt.ok || receipt.timedOut || receipt.cancelled) {
+        return { record, current: false, staleReason: 'historical receipt is not a valid pass' };
+      }
+      const expectedFingerprint = verificationInputFingerprint({
+        sourceRevision: expected.sourceRevision,
+        workspaceFingerprint: record.workspaceFingerprint,
+        checkId: expected.checkId,
+        requestedChecks: expected.requestedChecks,
+      });
+      if (record.verificationInputFingerprint !== expectedFingerprint) {
+        return { record, current: false, staleReason: 'verification inputs changed' };
+      }
+      if (record.commandFingerprint !== commandFingerprint(record.checkId, receipt.commandId)) {
+        return { record, current: false, staleReason: 'check command identity changed' };
+      }
+      return { record, current: true };
+    });
+}
+
 /**
  * Keeps historical evidence auditable while preventing a previous revision or
  * changed check inputs from being selected as proof for the current Work.

package/src/runtime/control-plane/execution/work-completion-authority.ts

@@ -0,0 +1,58 @@
+import { completeRequirementFromWork } from '../persistence/requirement-store';
+import {
+  appendWorkEvidence,
+  recordWorkCompletionReceipt,
+  type WorkContractStoreOptions,
+} from '../facade/work-contract-store';
+import type { WorkContract, WorkKind } from '../facade/types';
+
+export interface WorkRequirementProjectionResult {
+  attempted: boolean;
+  ok: boolean;
+  warning?: string;
+}
+
+/**
+ * Project one already-terminal Work receipt into Requirement semantic review.
+ * Work completion remains authoritative; Requirement projection is downstream
+ * and must never turn a durable completion receipt back into a failed Work.
+ */
+export function projectRequirementDeliveryFromCompletedWork(
+  options: WorkContractStoreOptions,
+  work: WorkContract,
+): WorkRequirementProjectionResult {
+  if (!work.requirementId || !options.controllerHome) return { attempted: false, ok: true };
+  try {
+    completeRequirementFromWork(
+      { controllerHome: options.controllerHome },
+      { requirementId: work.requirementId, work },
+    );
+    return { attempted: true, ok: true };
+  } catch (error) {
+    const warning = `Work completion remains authoritative; Requirement projection could not be applied: ${error instanceof Error ? error.message : String(error)}`.slice(0, 2_000);
+    try {
+      appendWorkEvidence(options, work.workId, {
+        title: 'requirement completion projection pending',
+        summary: warning,
+        detailLevel: 'summary',
+      });
+    } catch {
+      // The completion receipt is already canonical and durable. Diagnostic
+      // persistence is downstream and cannot invalidate terminal Work state.
+    }
+    return { attempted: true, ok: false, warning };
+  }
+}
+
+/** Record the canonical Work completion fact, then update downstream Requirement review state. */
+export function completeWorkWithReceipt(
+  options: WorkContractStoreOptions,
+  workId: string,
+  receipt: NonNullable<WorkContract['completionReceipt']>,
+  completionOutcome: NonNullable<WorkContract['completionOutcome']>,
+  completionWorkKind?: WorkKind,
+): WorkContract {
+  const recorded = recordWorkCompletionReceipt(options, workId, receipt, completionOutcome, completionWorkKind);
+  projectRequirementDeliveryFromCompletedWork(options, recorded);
+  return recorded;
+}