@fitlab-ai/agent-infra 0.9.10 → 0.9.12

package/lib/task/orchestration.ts

@@ -3,9 +3,11 @@ import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 
 import { parseTypedTaskFrontmatter } from './frontmatter.ts';
-import { parseReviewSummary } from './review-artifacts.ts';
+import { validateCurrentTaskContract } from './current-contract.ts';
+import { parseReviewSummary, resolveCanonicalVerdict } from './review-artifacts.ts';
 import { inspectArtifactDirectory } from './artifact-lifecycle.ts';
-import { parseLedger, summarizeLedgerStage, validateLedgerRows } from './ledger.ts';
+import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.ts';
+import type { LedgerDocument } from './ledger.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import {
   activateDelegation,
@@ -27,7 +29,6 @@ import type {
 } from './delegation-receipts.ts';
 import { normalizeAgentClients } from '../agent-clients/config.ts';
 import { resolveAgentRuntimeStoreRoot } from '../runtime/agent-runtime.ts';
-import { inspectPlatformPullRequest } from '../platform/pull-requests.ts';
 import {
   getAgentClientCapability,
   getAgentClientDelegationEvidence,
@@ -50,6 +51,8 @@ import { assertGitRepositoryBinding } from '../git/worktree-identity.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.ts';
 import { hasActiveCodexLifecycleEvidence } from '../agent-clients/adapters/codex-lifecycle/store.ts';
 import type { CodexCapabilityProvenanceDetail } from '../agent-clients/adapters/codex-lifecycle/capability-store.ts';
+import { extractReviewBaseline, extractReviewDiffBase, extractReviewTargetHead, extractReviewedHead } from './review-fingerprint.ts';
+import { resolveDeliveryTarget, resolveDiffBase, resolveTargetHead } from './delivery-target.ts';
 
 type OrchestrationStatus = 'running' | 'paused' | 'completed';
 type ModelPolicySource = Readonly<{
@@ -82,8 +85,8 @@ type CleanCompletionEvidence = Readonly<{
   headTree: string;
   worktreeTree: string;
   lastReviewedCommit: string;
-  prNumber: number;
-  prHead: string;
+  prNumber: number | null;
+  prHead: string | null;
 }>;
 type OrchestrationRun = Readonly<{
   taskId: string;
@@ -271,9 +274,8 @@ function isCompletionEvidence(value: unknown): value is CleanCompletionEvidence
     && exactText(value.headTree)
     && exactText(value.worktreeTree)
     && exactText(value.lastReviewedCommit)
-    && Number.isSafeInteger(value.prNumber)
-    && (value.prNumber as number) > 0
-    && exactText(value.prHead);
+    && (value.prNumber === null || (Number.isSafeInteger(value.prNumber) && (value.prNumber as number) > 0))
+    && (value.prHead === null || exactText(value.prHead));
 }
 
 const ORCHESTRATION_RUN_KEYS = [
@@ -521,6 +523,44 @@ function artifactName(family: string, round: number): string {
   return round === 1 ? `${family}.md` : `${family}-r${round}.md`;
 }
 
+function validateSavedCurrentDiffBase(
+  repoRoot: string,
+  metadata: ReturnType<typeof parseTypedTaskFrontmatter>,
+  taskDir: string,
+  reviewedHead: string
+): Readonly<{ code: string; message: string }> | null {
+  const reviewRound = highestRound(taskDir, 'review-code');
+  const reviewContent = fs.readFileSync(path.join(taskDir, artifactName('review-code', reviewRound)), 'utf8');
+  const savedTargetHead = extractReviewTargetHead(reviewContent);
+  const savedDiffBase = extractReviewDiffBase(reviewContent);
+  const savedReviewedHead = extractReviewedHead(reviewContent) || extractReviewBaseline(reviewContent);
+  if (!savedTargetHead && !savedDiffBase && !savedReviewedHead) return null;
+  if (savedReviewedHead && savedReviewedHead !== reviewedHead) {
+    return { code: 'ORCHESTRATION_REVIEWED_HEAD_MISMATCH', message: 'review-code saved reviewed head does not match last_reviewed_commit' };
+  }
+  if (!savedTargetHead || !savedDiffBase) {
+    return { code: 'ORCHESTRATION_REVIEW_TARGET_INVALID', message: 'review-code must save target head and diff base together' };
+  }
+  const savedBase = resolveDiffBase(repoRoot, reviewedHead, savedTargetHead);
+  if (!savedBase.ok) return { code: 'ORCHESTRATION_REVIEW_TARGET_INVALID', message: savedBase.message };
+  if (savedBase.diffBase !== savedDiffBase) {
+    return { code: 'ORCHESTRATION_REVIEW_DIFF_BASE_MISMATCH', message: 'saved review diff base does not match reviewed head and saved target head' };
+  }
+  const target = resolveDeliveryTarget(repoRoot, {
+    remote: typeof metadata.delivery_remote === 'string' ? metadata.delivery_remote : undefined,
+    baseRef: typeof metadata.delivery_base_ref === 'string' ? metadata.delivery_base_ref : undefined
+  });
+  if (!target.ok) return { code: target.code, message: target.message };
+  const currentTarget = resolveTargetHead(repoRoot, target.value);
+  if (!currentTarget.ok) return { code: currentTarget.code, message: currentTarget.message };
+  const currentBase = resolveDiffBase(repoRoot, reviewedHead, currentTarget.head!);
+  if (!currentBase.ok) return { code: currentBase.code, message: currentBase.message };
+  if (currentBase.diffBase !== savedDiffBase) {
+    return { code: 'ORCHESTRATION_REVIEW_TARGET_CHANGED', message: 'current delivery target changed the reviewed diff base; re-run review-code' };
+  }
+  return null;
+}
+
 function hasReviewAfterArtifact(taskDir: string, family: string, reviewFamily: string): boolean {
   const artifact = inspectArtifactDirectory(taskDir, family as 'analysis' | 'plan' | 'code');
   const review = inspectArtifactDirectory(taskDir, reviewFamily as 'review-analysis' | 'review-plan' | 'review-code');
@@ -530,14 +570,20 @@ function hasReviewAfterArtifact(taskDir: string, family: string, reviewFamily: s
     && review.reviewedInput?.name === artifact.latest.name;
 }
 
-function latestReviewApproved(taskDir: string, family: 'review-analysis' | 'review-plan' | 'review-code'): boolean {
+function latestReviewApproved(taskDir: string, family: 'review-analysis' | 'review-plan' | 'review-code'): { approved: boolean; error: string | null } {
   const round = highestRound(taskDir, family);
-  if (round === 0) return false;
-  const parsed = parseReviewSummary(fs.readFileSync(path.join(taskDir, artifactName(family, round)), 'utf8'));
-  return parsed.ok && parsed.summary.verdict === 'Approved' && parsed.summary.counts !== null;
+  if (round === 0) return { approved: false, error: null };
+  let content: string;
+  try { content = fs.readFileSync(path.join(taskDir, artifactName(family, round)), 'utf8'); }
+  catch (error) { return { approved: false, error: String(error) }; }
+  const parsed = parseReviewSummary(content);
+  if (!parsed.ok) return { approved: false, error: `${parsed.code}: ${parsed.message}` };
+  const verdict = resolveCanonicalVerdict(parsed.summary);
+  if (!verdict.ok) return { approved: false, error: `${verdict.code}: ${verdict.message}` };
+  return { approved: verdict.verdict === 'Approved', error: null };
 }
 
-function routeFromFacts(taskDir: string): Omit<OrchestrationNext, 'requestedModel' | 'requestedReasoningEffort'> | null {
+function routeFromFacts(taskDir: string): Omit<OrchestrationNext, 'requestedModel' | 'requestedReasoningEffort'> | { error: string } | null {
   const analysisRound = highestRound(taskDir, 'analysis');
   const analysisReviewRound = highestRound(taskDir, 'review-analysis');
   const planRound = highestRound(taskDir, 'plan');
@@ -552,7 +598,9 @@ function routeFromFacts(taskDir: string): Omit<OrchestrationNext, 'requestedMode
     const round = analysisReviewRound + 1;
     return { action: 'review-analysis', role: 'reviewer', stage: 'review-analysis', round, artifact: artifactName('review-analysis', round) };
   }
-  if (!latestReviewApproved(taskDir, 'review-analysis')) {
+  const analysisVerdict = latestReviewApproved(taskDir, 'review-analysis');
+  if (analysisVerdict.error) return { error: analysisVerdict.error };
+  if (!analysisVerdict.approved) {
     const round = analysisRound + 1;
     return { action: 'analyze-task', role: 'executor', stage: 'analysis', round, artifact: artifactName('analysis', round) };
   }
@@ -564,7 +612,9 @@ function routeFromFacts(taskDir: string): Omit<OrchestrationNext, 'requestedMode
     const round = planReviewRound + 1;
     return { action: 'review-plan', role: 'reviewer', stage: 'review-plan', round, artifact: artifactName('review-plan', round) };
   }
-  if (!latestReviewApproved(taskDir, 'review-plan')) {
+  const planVerdict = latestReviewApproved(taskDir, 'review-plan');
+  if (planVerdict.error) return { error: planVerdict.error };
+  if (!planVerdict.approved) {
     const round = planRound + 1;
     return { action: 'plan-task', role: 'executor', stage: 'plan', round, artifact: artifactName('plan', round) };
   }
@@ -576,7 +626,9 @@ function routeFromFacts(taskDir: string): Omit<OrchestrationNext, 'requestedMode
     const round = codeReviewRound + 1;
     return { action: 'review-code', role: 'reviewer', stage: 'review-code', round, artifact: artifactName('review-code', round) };
   }
-  if (!latestReviewApproved(taskDir, 'review-code')) {
+  const codeVerdict = latestReviewApproved(taskDir, 'review-code');
+  if (codeVerdict.error) return { error: codeVerdict.error };
+  if (!codeVerdict.approved) {
     const round = codeRound + 1;
     return { action: 'code-task', role: 'executor', stage: 'code', round, artifact: artifactName('code', round) };
   }
@@ -599,12 +651,21 @@ function routeOrchestration(taskRef: string, options: OrchestrationOptions = {})
     return failed('ORCHESTRATION_TASK_READ_FAILED', String(error), resolved.taskId);
   }
   let metadata: ReturnType<typeof parseTypedTaskFrontmatter>;
-  try {
-    metadata = parseTypedTaskFrontmatter(content);
-  } catch (error) {
-    return failed('ORCHESTRATION_TASK_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
+  let currentLedger: LedgerDocument | null = null;
+  if (resolved.state === 'active') {
+    const contract = validateCurrentTaskContract(content);
+    if (!contract.ok) return failed('ORCHESTRATION_CURRENT_CONTRACT_INVALID', contract.message, resolved.taskId);
+    metadata = contract.metadata;
+    currentLedger = contract.ledger;
+  } else {
+    try {
+      metadata = parseTypedTaskFrontmatter(content);
+    } catch (error) {
+      return failed('ORCHESTRATION_TASK_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
+    }
   }
   const routed = routeFromFacts(resolved.taskDir);
+  if (routed && 'error' in routed) return failed('ORCHESTRATION_REVIEW_INVALID', routed.error, resolved.taskId);
   if (!routed) return failed('ORCHESTRATION_ROUTE_UNKNOWN', 'cannot determine a unique lifecycle action', resolved.taskId);
   const run = readRun(resolved.taskDir);
   const policy = run ? rolePolicy(run, routed.role) : null;
@@ -622,7 +683,9 @@ function routeOrchestration(taskRef: string, options: OrchestrationOptions = {})
     if (!review.ok || review.summary.manualValidation === null) {
       return failed('ORCHESTRATION_REVIEW_INVALID', 'latest code review has no numeric manual-validation count', resolved.taskId);
     }
-    const rows = parseLedger(content);
+    const ledger = currentLedger ?? parseLedgerDocument(content);
+    if (!ledger.present) return failed('ORCHESTRATION_CURRENT_CONTRACT_INVALID', `${LEDGER_SECTION_MISSING_CODE}: ${LEDGER_SECTION_MISSING_MESSAGE}`, resolved.taskId);
+    const rows = ledger.rows;
     const ledgerError = validateLedgerRows(rows);
     if (ledgerError) return failed('ORCHESTRATION_LEDGER_INVALID', ledgerError.message, resolved.taskId);
     if (!summarizeLedgerStage(rows, 'code').canAdvance) {
@@ -631,29 +694,8 @@ function routeOrchestration(taskRef: string, options: OrchestrationOptions = {})
     if (run?.status === 'completed') {
       return { status: 'completed', changed: false, taskId: resolved.taskId, run, next: null, error: null };
     }
-
-    let config: unknown;
-    try {
-      config = JSON.parse(fs.readFileSync(path.join(resolved.repoRoot, '.agents', '.airc.json'), 'utf8'));
-    } catch (error) {
-      return failed('ORCHESTRATION_CONFIG_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
-    }
-    if (!config || typeof config !== 'object' || Array.isArray(config)) {
-      return failed('ORCHESTRATION_CONFIG_INVALID', 'project configuration must be an object', resolved.taskId);
-    }
-    const projectConfig = config as Record<string, unknown>;
-    if (!Object.hasOwn(projectConfig, 'prFlow') || projectConfig.prFlow === 'disabled') {
-      return { status: 'running', changed: false, taskId: resolved.taskId, run, next, error: null };
-    }
-    if (projectConfig.prFlow !== 'required') {
-      return failed('ORCHESTRATION_CONFIG_INVALID', "project configuration 'prFlow' must be 'required' or 'disabled'", resolved.taskId);
-    }
-    const prNumber = Number(metadata.pr_number);
-    if (!Number.isInteger(prNumber) || prNumber <= 0) {
-      return { status: 'running', changed: false, taskId: resolved.taskId, run, next, error: null };
-    }
     if (!run) {
-      return { status: 'running', changed: false, taskId: resolved.taskId, run, next, error: null };
+      return { status: 'running', changed: false, taskId: resolved.taskId, run, next: null, error: null };
     }
     if (run.status !== 'running' || run.pendingDelegation !== null) {
       return failed('ORCHESTRATION_RUN_NOT_RUNNING', 'clean completion requires an idle running orchestration', resolved.taskId);
@@ -667,35 +709,19 @@ function routeOrchestration(taskRef: string, options: OrchestrationOptions = {})
       return failed('ORCHESTRATION_SNAPSHOT_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
     }
     if (before.headTree !== before.worktreeTree) {
-      return { status: 'running', changed: false, taskId: resolved.taskId, run, next, error: null };
+      return { status: 'running', changed: false, taskId: resolved.taskId, run, next: null, error: null };
     }
     const lastReviewedCommit = String(metadata.last_reviewed_commit ?? '');
     if (before.head !== lastReviewedCommit) {
       return failed('ORCHESTRATION_REVIEWED_HEAD_MISMATCH', 'local HEAD does not match last_reviewed_commit', resolved.taskId);
     }
-
-    const inspect: NonNullable<OrchestrationOptions['inspectPullRequest']> =
-      options.inspectPullRequest ?? inspectPlatformPullRequest;
-    let inspection: ReturnType<NonNullable<OrchestrationOptions['inspectPullRequest']>>;
-    try {
-      inspection = inspect(resolved.taskId, { cwd: gitRoot });
-    } catch (error) {
-      return failed('ORCHESTRATION_PR_INSPECTION_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
-    }
-    if (inspection.status === 'blocked') {
-      return failed('ORCHESTRATION_PR_INSPECTION_BLOCKED', inspection.error?.message ?? 'pull request inspection is blocked', resolved.taskId);
-    }
-    if (inspection.status === 'failed') {
-      return failed('ORCHESTRATION_PR_INSPECTION_FAILED', inspection.error?.message ?? 'pull request inspection failed', resolved.taskId);
-    }
-    const inspectedPrNumber = inspection.task?.prNumber ?? inspection.prNumber;
-    const prHead = inspection.pullRequest?.head?.sha;
-    if (typeof prHead !== 'string') {
-      return failed('ORCHESTRATION_PR_INSPECTION_INVALID', 'pull request inspection returned incomplete identity evidence', resolved.taskId);
-    }
-    if (inspectedPrNumber !== prNumber || prHead !== before.head) {
-      return failed('ORCHESTRATION_PR_HEAD_MISMATCH', 'pull request identity does not match the reviewed local HEAD', resolved.taskId);
-    }
+    const diffBaseError = validateSavedCurrentDiffBase(
+      resolved.repoRoot,
+      metadata,
+      resolved.taskDir,
+      lastReviewedCommit
+    );
+    if (diffBaseError) return failed(diffBaseError.code, diffBaseError.message, resolved.taskId);
 
     let after: RepositorySnapshot;
     try {
@@ -704,7 +730,7 @@ function routeOrchestration(taskRef: string, options: OrchestrationOptions = {})
       return failed('ORCHESTRATION_SNAPSHOT_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
     }
     if (after.headTree !== after.worktreeTree) {
-      return { status: 'running', changed: false, taskId: resolved.taskId, run, next, error: null };
+      return { status: 'running', changed: false, taskId: resolved.taskId, run, next: null, error: null };
     }
     if (after.head !== before.head || after.headTree !== before.headTree) {
       return failed('ORCHESTRATION_REPOSITORY_CHANGED', 'repository changed while clean completion evidence was collected', resolved.taskId);
@@ -718,8 +744,8 @@ function routeOrchestration(taskRef: string, options: OrchestrationOptions = {})
       headTree: after.headTree,
       worktreeTree: after.worktreeTree,
       lastReviewedCommit,
-      prNumber,
-      prHead
+      prNumber: null,
+      prHead: null
     };
     const completed = withUpdatedRun(run, {
       status: 'completed',
@@ -827,10 +853,7 @@ function prepareOrchestrationDelegationUnlocked(
   }
   const updated = withUpdatedRun(run, {
     nextStage: next.stage,
-    pendingDelegation: receipt,
-    commitAuthorization: next.stage === 'commit' && run.commitAuthorization.issuedAt === null
-      ? { issuedAt: (options.now ?? (() => new Date().toISOString()))(), consumedAt: null }
-      : run.commitAuthorization
+    pendingDelegation: receipt
   });
   saveRun(resolved.taskDir, updated);
   return { status: 'running', changed: true, taskId: resolved.taskId, run: updated, next, error: null };
@@ -1435,16 +1458,15 @@ function advanceOrchestration(taskRef: string, options: OrchestrationOptions = {
   if (!run?.pendingDelegation) return failed('ORCHESTRATION_DELEGATION_MISSING', 'no pending delegation exists', resolved.taskId);
   const result = consumeDelegation(run.pendingDelegation, { now: options.now });
   if (!result.ok) return pauseOrchestration(taskRef, result.code, result.message, true, options);
-  const completed = result.receipt.stage === 'commit';
+  if (result.receipt.stage === 'commit') {
+    return failed('ORCHESTRATED_COMMIT_REMOVED', 'Orchestrated commit is no longer a lifecycle stage; use local checkpoint delivery from code-task', resolved.taskId);
+  }
   const updated = withUpdatedRun(run, {
-    status: completed ? 'completed' : 'running',
+    status: 'running',
     nextStage: null,
     stepCount: run.stepCount + 1,
     pendingDelegation: null,
-    receipts: Object.freeze([...run.receipts, result.receipt]),
-    commitAuthorization: completed
-      ? { ...run.commitAuthorization, consumedAt: (options.now ?? (() => new Date().toISOString()))() }
-      : run.commitAuthorization
+    receipts: Object.freeze([...run.receipts, result.receipt])
   });
   saveRun(resolved.taskDir, updated);
   return { status: updated.status, changed: true, taskId: resolved.taskId, run: updated, next: null, error: null };

package/lib/task/pr-delivery-fact.ts

@@ -0,0 +1,254 @@
+const PR_DELIVERY_FACT_KEY = 'pr_delivery_fact';
+
+type PrDeliveryIdentity = {
+  repository: string;
+  number: number;
+  nodeId: string;
+  url: string;
+  head: { repository: string; ref: string; sha: string };
+  base: { repository: string; ref: string; sha: string };
+};
+
+type PrDeliveryBindingSource =
+  | 'created'
+  | 'reused'
+  | 'explicit-bind'
+  | 'external-unique'
+  | 'external-explicit';
+
+type PrDeliveryProvenance =
+  | 'create-post'
+  | 'reuse'
+  | 'explicit-bind'
+  | 'external-unique'
+  | 'external-explicit';
+
+type PrDeliveryFact =
+  | { version: 1; state: 'unbound'; reason: 'initial' }
+  | { version: 1; state: 'skipped'; reason: 'explicit'; decidedAt: string }
+  | {
+      version: 1;
+      state: 'bound';
+      identity: PrDeliveryIdentity;
+      binding: {
+        status: 'verified';
+        source: PrDeliveryBindingSource;
+        verifiedAt: string;
+        issueNumber: number | null;
+        remoteState: 'open' | 'closed';
+        mergedAt: string | null;
+        mergeCommitSha: string | null;
+      };
+      provenance: { establishedBy: PrDeliveryProvenance };
+    };
+
+type CreationOutcome =
+  | { kind: 'planned'; action: 'create' | 'reuse'; createdByCurrentOperation: false }
+  | { kind: 'not-created'; reason: 'precondition-failed' | 'post-rejected'; createdByCurrentOperation: false }
+  | { kind: 'created'; createdByCurrentOperation: true }
+  | { kind: 'reused'; createdByCurrentOperation: false }
+  | { kind: 'no-op'; createdByCurrentOperation: false }
+  | { kind: 'unknown'; errorCode: 'PR_CREATE_OUTCOME_UNKNOWN' };
+
+type PrDeliveryFactReadResult =
+  | { status: 'valid'; fact: PrDeliveryFact }
+  | { status: 'missing'; fact: null }
+  | { status: 'invalid'; fact: null; error: Error };
+
+function factError(message: string): Error & { code: string } {
+  return Object.assign(new Error(`PR_DELIVERY_FACT_INVALID: ${message}`), { code: 'PR_DELIVERY_FACT_INVALID' });
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function exactKeys(value: Record<string, unknown>, keys: readonly string[], label: string): void {
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
+    throw factError(`${label} has an invalid field set`);
+  }
+}
+
+function text(value: unknown, label: string): string {
+  if (typeof value !== 'string' || !value || value.trim() !== value) throw factError(`${label} must be a non-empty string`);
+  return value;
+}
+
+function nullableText(value: unknown, label: string): string | null {
+  return value === null ? null : text(value, label);
+}
+
+function positiveNumber(value: unknown, label: string): number {
+  if (!Number.isSafeInteger(value) || (value as number) <= 0) throw factError(`${label} must be a positive integer`);
+  return value as number;
+}
+
+function optionalTimestamp(value: unknown, label: string): string | null {
+  const result = nullableText(value, label);
+  if (result !== null && Number.isNaN(Date.parse(result))) throw factError(`${label} must be a valid timestamp`);
+  return result;
+}
+
+function parseIdentity(value: unknown): PrDeliveryIdentity {
+  if (!isRecord(value)) throw factError('identity must be an object');
+  exactKeys(value, ['repository', 'number', 'nodeId', 'url', 'head', 'base'], 'identity');
+  const head = parseRef(value.head, 'head');
+  const base = parseRef(value.base, 'base');
+  return {
+    repository: text(value.repository, 'identity.repository'),
+    number: positiveNumber(value.number, 'identity.number'),
+    nodeId: text(value.nodeId, 'identity.nodeId'),
+    url: text(value.url, 'identity.url'),
+    head,
+    base
+  };
+}
+
+function parseRef(value: unknown, label: string): { repository: string; ref: string; sha: string } {
+  if (!isRecord(value)) throw factError(`${label} must be an object`);
+  exactKeys(value, ['repository', 'ref', 'sha'], label);
+  return {
+    repository: text(value.repository, `${label}.repository`),
+    ref: text(value.ref, `${label}.ref`),
+    sha: text(value.sha, `${label}.sha`)
+  };
+}
+
+function parseFact(value: unknown): PrDeliveryFact {
+  if (!isRecord(value)) throw factError('fact must be an object');
+  if (value.version !== 1 || typeof value.state !== 'string') throw factError('version or state is invalid');
+  if (value.state === 'unbound') {
+    exactKeys(value, ['version', 'state', 'reason'], 'unbound fact');
+    if (value.reason !== 'initial') throw factError('unbound reason is invalid');
+    return { version: 1, state: 'unbound', reason: value.reason };
+  }
+  if (value.state === 'skipped') {
+    exactKeys(value, ['version', 'state', 'reason', 'decidedAt'], 'skipped fact');
+    if (value.reason !== 'explicit') throw factError('skipped reason is invalid');
+    const decidedAt = text(value.decidedAt, 'skipped.decidedAt');
+    if (Number.isNaN(Date.parse(decidedAt))) throw factError('skipped.decidedAt must be a valid timestamp');
+    return { version: 1, state: 'skipped', reason: 'explicit', decidedAt };
+  }
+  if (value.state !== 'bound') throw factError('state is invalid');
+  exactKeys(value, ['version', 'state', 'identity', 'binding', 'provenance'], 'bound fact');
+  if (!isRecord(value.binding)) throw factError('binding must be an object');
+  exactKeys(value.binding, ['status', 'source', 'verifiedAt', 'issueNumber', 'remoteState', 'mergedAt', 'mergeCommitSha'], 'binding');
+  if (value.binding.status !== 'verified') throw factError('binding status is invalid');
+  const sources: readonly PrDeliveryBindingSource[] = ['created', 'reused', 'explicit-bind', 'external-unique', 'external-explicit'];
+  if (!sources.includes(value.binding.source as PrDeliveryBindingSource)) throw factError('binding source is invalid');
+  const verifiedAt = text(value.binding.verifiedAt, 'binding.verifiedAt');
+  if (Number.isNaN(Date.parse(verifiedAt))) throw factError('binding.verifiedAt must be a valid timestamp');
+  const issueNumber = value.binding.issueNumber === null ? null : positiveNumber(value.binding.issueNumber, 'binding.issueNumber');
+  if (value.binding.remoteState !== 'open' && value.binding.remoteState !== 'closed') throw factError('binding.remoteState is invalid');
+  const mergedAt = optionalTimestamp(value.binding.mergedAt, 'binding.mergedAt');
+  const mergeCommitSha = nullableText(value.binding.mergeCommitSha, 'binding.mergeCommitSha');
+  if (Boolean(mergedAt) !== Boolean(mergeCommitSha)) throw factError('mergedAt and mergeCommitSha must be paired');
+  if (!isRecord(value.provenance)) throw factError('provenance must be an object');
+  exactKeys(value.provenance, ['establishedBy'], 'provenance');
+  const provenance: readonly PrDeliveryProvenance[] = ['create-post', 'reuse', 'explicit-bind', 'external-unique', 'external-explicit'];
+  if (!provenance.includes(value.provenance.establishedBy as PrDeliveryProvenance)) throw factError('provenance.establishedBy is invalid');
+  if (value.provenance.establishedBy !== provenanceForSource(value.binding.source as PrDeliveryBindingSource)) {
+    throw factError('binding.source and provenance.establishedBy do not match');
+  }
+  return {
+    version: 1,
+    state: 'bound',
+    identity: parseIdentity(value.identity),
+    binding: {
+      status: 'verified',
+      source: value.binding.source as PrDeliveryBindingSource,
+      verifiedAt,
+      issueNumber,
+      remoteState: value.binding.remoteState,
+      mergedAt,
+      mergeCommitSha
+    },
+    provenance: { establishedBy: value.provenance.establishedBy as PrDeliveryProvenance }
+  };
+}
+
+function decodePrDeliveryFact(value: unknown): PrDeliveryFact {
+  if (typeof value === 'string') {
+    try { return parseFact(JSON.parse(value)); }
+    catch (error) { throw error instanceof Error && error.message.startsWith('PR_DELIVERY_FACT_INVALID:') ? error : factError('value is not valid JSON'); }
+  }
+  return parseFact(value);
+}
+
+function encodePrDeliveryFact(fact: PrDeliveryFact): string {
+  return JSON.stringify(parseFact(fact));
+}
+
+function readPrDeliveryFact(metadata: Record<string, unknown>): PrDeliveryFactReadResult {
+  if (!Object.hasOwn(metadata, PR_DELIVERY_FACT_KEY) || metadata[PR_DELIVERY_FACT_KEY] === '') return { status: 'missing', fact: null };
+  try { return { status: 'valid', fact: decodePrDeliveryFact(metadata[PR_DELIVERY_FACT_KEY]) }; }
+  catch (error) { return { status: 'invalid', fact: null, error: error instanceof Error ? error : factError(String(error)) }; }
+}
+
+function buildUnboundFact(): PrDeliveryFact {
+  return { version: 1, state: 'unbound', reason: 'initial' };
+}
+
+function buildSkippedFact(decidedAt: string): PrDeliveryFact {
+  return parseFact({ version: 1, state: 'skipped', reason: 'explicit', decidedAt });
+}
+
+function provenanceForSource(source: PrDeliveryBindingSource): PrDeliveryProvenance {
+  return source === 'created' ? 'create-post' : source === 'reused' ? 'reuse' : source;
+}
+
+function buildBoundFact(input: {
+  identity: PrDeliveryIdentity;
+  source: PrDeliveryBindingSource;
+  verifiedAt: string;
+  issueNumber?: number | null;
+  remoteState: 'open' | 'closed';
+  mergedAt?: string | null;
+  mergeCommitSha?: string | null;
+}): PrDeliveryFact {
+  return parseFact({
+    version: 1,
+    state: 'bound',
+    identity: input.identity,
+    binding: {
+      status: 'verified',
+      source: input.source,
+      verifiedAt: input.verifiedAt,
+      issueNumber: input.issueNumber ?? null,
+      remoteState: input.remoteState,
+      mergedAt: input.mergedAt ?? null,
+      mergeCommitSha: input.mergeCommitSha ?? null
+    },
+    provenance: { establishedBy: provenanceForSource(input.source) }
+  });
+}
+
+function factFrontmatterMutation(fact: PrDeliveryFact): { set: { [PR_DELIVERY_FACT_KEY]: string } } {
+  return { set: { [PR_DELIVERY_FACT_KEY]: encodePrDeliveryFact(fact) } };
+}
+
+function identityFromPullRequest(pullRequest: PrDeliveryIdentity): PrDeliveryIdentity {
+  return parseIdentity(pullRequest);
+}
+
+export {
+  PR_DELIVERY_FACT_KEY,
+  buildBoundFact,
+  buildSkippedFact,
+  buildUnboundFact,
+  decodePrDeliveryFact,
+  encodePrDeliveryFact,
+  factFrontmatterMutation,
+  identityFromPullRequest,
+  readPrDeliveryFact
+};
+export type {
+  CreationOutcome,
+  PrDeliveryBindingSource,
+  PrDeliveryFact,
+  PrDeliveryFactReadResult,
+  PrDeliveryIdentity,
+  PrDeliveryProvenance
+};