@fitlab-ai/agent-infra 0.9.5 → 0.9.7

package/lib/server/process-state.ts

@@ -2,22 +2,34 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 
-export type PidRecord = {
-  version: 1;
+export type ProcessStartTime = number;
+
+export type ProcessIdentity = Readonly<{
   pid: number;
-  startTime: string;
+  startTime: ProcessStartTime;
+}>;
+
+export type PidRecord = ProcessIdentity & {
+  version: 2;
 };
 
 export type ProcessStartTimeQuery = { command: string; args: string[] };
 
 export type ProcessState =
   | { kind: 'missing'; snapshot: null }
-  | { kind: 'invalid'; snapshot: string }
-  | { kind: 'legacy'; snapshot: string; pid: number }
+  | { kind: 'legacy-json'; snapshot: string; legacy: LegacyProcessSnapshot }
+  | { kind: 'legacy-pid-only'; snapshot: string; legacy: LegacyProcessSnapshot }
+  | { kind: 'legacy-unknown'; snapshot: string; legacy: LegacyProcessSnapshot; reason: string }
   | { kind: 'stale'; snapshot: string; record: PidRecord }
   | { kind: 'running'; snapshot: string; record: PidRecord };
 
-export type LinuxProcessStat = { state: string; startTime: string };
+export type LegacyProcessSnapshot = Readonly<{
+  pid?: number;
+  raw: string;
+  format: 'json-v1' | 'pid-only' | 'malformed';
+}>;
+
+export type LinuxProcessStat = { state: string; startTime: number };
 
 export function parseLinuxProcessStat(raw: string): LinuxProcessStat | null {
   const closeParen = raw.lastIndexOf(')');
@@ -28,7 +40,9 @@ export function parseLinuxProcessStat(raw: string): LinuxProcessStat | null {
   if (typeof state !== 'string' || state.length !== 1 || !/^\d+$/.test(startTime ?? '')) {
     return null;
   }
-  return { state, startTime: startTime! };
+  const numericStartTime = Number(startTime);
+  if (!Number.isSafeInteger(numericStartTime)) return null;
+  return { state, startTime: numericStartTime };
 }
 
 export function buildProcessStartTimeQuery(
@@ -68,10 +82,22 @@ export function isProcessAlive(pid: number, platform: NodeJS.Platform = process.
   }
 }
 
+function parseDarwinStartTime(output: string): number | null {
+  const match = output.trim().match(/^(?:Sun|Mon|Tue|Wed|Thu|Fri|Sat) ([A-Z][a-z]{2}) (\d{1,2}) (\d{2}):(\d{2}):(\d{2}) (\d{4})$/);
+  if (!match) return null;
+  const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+  const month = months.indexOf(match[1]!);
+  if (month < 0) return null;
+  const timestamp = Date.UTC(
+    Number(match[6]), month, Number(match[2]), Number(match[3]), Number(match[4]), Number(match[5])
+  );
+  return Number.isNaN(timestamp) ? null : timestamp;
+}
+
 export function getProcessStartTime(
   pid: number,
   platform: NodeJS.Platform = process.platform
-): string | null {
+): ProcessStartTime | null {
   if (!Number.isInteger(pid) || pid <= 0) return null;
   if (platform === 'linux') {
     try {
@@ -85,43 +111,71 @@ export function getProcessStartTime(
   const query = buildProcessStartTimeQuery(pid, platform);
   if (query === null) return null;
   try {
-    const output = execFileSync(query.command, query.args, { encoding: 'utf8' }).trim();
+    const output = execFileSync(query.command, query.args, {
+      encoding: 'utf8',
+      env: platform === 'darwin' ? { ...process.env, LC_ALL: 'C', LANG: 'C', TZ: 'UTC' } : process.env
+    }).trim();
     if (output.length === 0) return null;
     if (platform === 'win32') {
       const timestamp = new Date(output);
-      return Number.isNaN(timestamp.getTime()) ? null : timestamp.toISOString();
+      return Number.isNaN(timestamp.getTime()) ? null : timestamp.getTime();
     }
-    return output;
+    if (platform === 'darwin') return parseDarwinStartTime(output);
+    return null;
   } catch {
     return null;
   }
 }
 
-function parsePidRecord(raw: string): { kind: 'invalid' } | { kind: 'legacy'; pid: number } | { kind: 'record'; record: PidRecord } {
+function parsePidRecord(
+  raw: string
+):
+  | { kind: 'legacy-json'; legacy: LegacyProcessSnapshot }
+  | { kind: 'legacy-pid-only'; legacy: LegacyProcessSnapshot }
+  | { kind: 'legacy-unknown'; legacy: LegacyProcessSnapshot; reason: string }
+  | { kind: 'record'; record: PidRecord } {
   const trimmed = raw.trim();
   if (/^[1-9]\d*$/.test(trimmed)) {
     const pid = Number(trimmed);
-    return Number.isSafeInteger(pid) ? { kind: 'legacy', pid } : { kind: 'invalid' };
+    return Number.isSafeInteger(pid)
+      ? { kind: 'legacy-pid-only', legacy: { pid, raw, format: 'pid-only' } }
+      : { kind: 'legacy-unknown', legacy: { raw, format: 'malformed' }, reason: 'pid is not a safe integer' };
   }
   try {
-    const value = JSON.parse(trimmed) as Partial<PidRecord> | null;
+    const value = JSON.parse(trimmed) as { version?: unknown; pid?: unknown; startTime?: unknown } | null;
+    const pidValue: unknown = value?.pid;
+    const startTimeValue: unknown = value?.startTime;
     if (
       value !== null &&
-      value.version === 1 &&
-      Number.isSafeInteger(value.pid) &&
-      (value.pid ?? 0) > 0 &&
-      typeof value.startTime === 'string' &&
-      value.startTime.length > 0
+      value.version === 2 &&
+      typeof pidValue === 'number' &&
+      Number.isSafeInteger(pidValue) &&
+      pidValue > 0 &&
+      typeof startTimeValue === 'number' &&
+      Number.isSafeInteger(startTimeValue) &&
+      startTimeValue >= 0
     ) {
+      const startTime = startTimeValue as number;
       return {
         kind: 'record',
-        record: { version: 1, pid: value.pid!, startTime: value.startTime }
+        record: { version: 2, pid: pidValue, startTime }
       };
     }
+    if (
+      value !== null &&
+      value.version === 1 &&
+      typeof pidValue === 'number' &&
+      Number.isSafeInteger(pidValue) &&
+      pidValue > 0 &&
+      typeof value.startTime === 'string' &&
+      value.startTime.length > 0
+    ) {
+      return { kind: 'legacy-json', legacy: { pid: pidValue, raw, format: 'json-v1' } };
+    }
+    return { kind: 'legacy-unknown', legacy: { raw, format: 'malformed' }, reason: 'unsupported PID record schema' };
   } catch {
-    // Invalid JSON is an invalid PID record.
+    return { kind: 'legacy-unknown', legacy: { raw, format: 'malformed' }, reason: 'invalid PID record JSON' };
   }
-  return { kind: 'invalid' };
 }
 
 export function readProcessState(pidFile: string): ProcessState {
@@ -130,12 +184,13 @@ export function readProcessState(pidFile: string): ProcessState {
     snapshot = fs.readFileSync(pidFile, 'utf8');
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { kind: 'missing', snapshot: null };
-    return { kind: 'invalid', snapshot: '' };
+    return { kind: 'legacy-unknown', snapshot: '', legacy: { raw: '', format: 'malformed' }, reason: 'PID record cannot be read' };
   }
 
   const parsed = parsePidRecord(snapshot);
-  if (parsed.kind === 'invalid') return { kind: 'invalid', snapshot };
-  if (parsed.kind === 'legacy') return { kind: 'legacy', snapshot, pid: parsed.pid };
+  if (parsed.kind === 'legacy-json') return { kind: parsed.kind, snapshot, legacy: parsed.legacy };
+  if (parsed.kind === 'legacy-pid-only') return { kind: parsed.kind, snapshot, legacy: parsed.legacy };
+  if (parsed.kind === 'legacy-unknown') return { kind: parsed.kind, snapshot, legacy: parsed.legacy, reason: parsed.reason };
 
   const currentStartTime = getProcessStartTime(parsed.record.pid);
   if (currentStartTime === null || currentStartTime !== parsed.record.startTime) {
@@ -178,6 +233,6 @@ export function removePidRecordIfMatches(pidFile: string, expected: PidRecord):
   return removePidFileIfMatches(pidFile, state.snapshot);
 }
 
-export function processIdentityMatches(record: PidRecord): boolean {
-  return getProcessStartTime(record.pid) === record.startTime;
+export function processIdentityMatches(identity: ProcessIdentity): boolean {
+  return getProcessStartTime(identity.pid) === identity.startTime;
 }

package/lib/task/artifact-lifecycle.ts

@@ -7,6 +7,7 @@ import { locateActivityLog } from './activity-log.ts';
 import { parseImplementationInputs, selectPendingImplementationInput } from './implementation-inputs.ts';
 import { parseVerdict } from './review-artifacts.ts';
 import { extractSection, findSectionHeading } from './sections.ts';
+import { receiptForOutput, sha256File } from './artifact-receipts.ts';
 
 const artifactFamilyCatalog = [
   { family: 'analysis', sectionAliases: ['分析', 'Analysis'], heading: '分析', labels: ['需求分析报告', 'Requirements Analysis'] },
@@ -16,6 +17,7 @@ const artifactFamilyCatalog = [
   { family: 'code', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['实现报告', 'Implementation Report'] },
   { family: 'review-code', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['代码审查', 'Code Review'] },
   { family: 'manual-validation', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['人工验证', 'Manual Validation'] },
+  { family: 'validation-run', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['验证运行证据', 'Validation Run Evidence'] },
   { family: 'pr-review', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['PR 审查报告', 'PR Review Report'] }
 ] as const;
 
@@ -217,11 +219,7 @@ function resolveReviewedInput(
     diagnostics.push(diagnostic('BROKEN_REFERENCE', review.family, review.name, String(error)));
     return null;
   }
-  const lines = content.split(/\r?\n/);
-  const header = lines.findIndex((line) => /\*\*(?:审查输入|Review Input)\*\*[:：]/.test(line));
-  const referenceBlock = header >= 0 ? lines.slice(header, header + 12).join('\n') : '';
-  const candidates = [...referenceBlock.matchAll(/`([^`]+\.md)`/g)].map((match) => match[1]!);
-  const parsed = candidates.map((name) => parseArtifactName(name)).find((item) => item?.family === expectedFamily);
+  const parsed = parseReviewedInputReference(content, expectedFamily);
   if (!parsed) {
     diagnostics.push(diagnostic('BROKEN_REFERENCE', review.family, review.name, `${review.name} does not reference a canonical ${expectedFamily} artifact`));
     return null;
@@ -230,9 +228,16 @@ function resolveReviewedInput(
   try {
     const stat = fs.lstatSync(abs);
     if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('referenced input is not a regular file');
-    if (stat.mtimeMs > review.mtimeMs) {
-      diagnostics.push(diagnostic('BROKEN_REFERENCE', review.family, review.name, `${parsed.name} is newer than ${review.name}`));
-      return null;
+    const taskContent = fs.readFileSync(path.join(taskDir, 'task.md'), 'utf8');
+    const receipt = receiptForOutput(taskContent, review.name);
+    if (!receipt) throw new Error(`receipt for ${review.name} is missing`);
+    const expectedEvent = reviewEventName(review.family);
+    if (receipt.event !== expectedEvent || receipt.input !== parsed.name) {
+      throw new Error(`receipt for ${review.name} does not match ${parsed.name}`);
+    }
+    const actualSha256 = sha256File(abs);
+    if (actualSha256 !== receipt.inputSha256) {
+      throw new Error(`${parsed.name} content digest does not match receipt`);
     }
     return { ...parsed, path: abs, size: stat.size, mtimeMs: stat.mtimeMs };
   } catch (error) {
@@ -241,6 +246,54 @@ function resolveReviewedInput(
   }
 }
 
+function parseReviewedInputReference(content: string, expectedFamily: ArtifactFamily): { family: ArtifactFamily; round: number; name: string } | null {
+  const lines = content.split(/\r?\n/);
+  const header = lines.findIndex((line) => /\*\*(?:审查输入|Review Input)\*\*[:：]/.test(line));
+  const referenceBlock = header >= 0 ? lines.slice(header, header + 12).join('\n') : '';
+  const candidates = [...referenceBlock.matchAll(/`([^`]+\.md)`/g)].map((match) => match[1]!);
+  return candidates
+    .map((name) => parseArtifactName(name))
+    .find((item) => item?.family === expectedFamily) ?? null;
+}
+
+function parseCodePlanInputReference(content: string): { family: 'plan'; round: number; name: string } | null {
+  const lines = content.split(/\r?\n/);
+  const sectionStart = lines.findIndex((line) => /^##\s+(?:实现输入|Implementation Input)\s*$/.test(line.trim()));
+  if (sectionStart < 0) return null;
+  const bodyLines = lines.slice(sectionStart + 1);
+  const nextSection = bodyLines.findIndex((line) => /^##\s+/.test(line.trim()));
+  const body = (nextSection < 0 ? bodyLines : bodyLines.slice(0, nextSection)).join('\n');
+  const match = body.match(/\*\*(?:方案输入|Plan Input)\*\*[:：]\s*`([^`]+\.md)`/);
+  if (!match) return null;
+  const parsed = parseArtifactName(match[1]!);
+  return parsed?.family === 'plan' ? { ...parsed, family: 'plan' } : null;
+}
+
+function reviewEventName(family: ArtifactFamily): 'review-analysis.completed' | 'review-plan.completed' | 'review-code.completed' {
+  if (family === 'review-analysis') return 'review-analysis.completed';
+  if (family === 'review-plan') return 'review-plan.completed';
+  if (family === 'review-code') return 'review-code.completed';
+  throw new Error(`unsupported review family '${family}'`);
+}
+
+function resolveCodeInputReceipt(taskDir: string, code: ArtifactIdentity): { input: ArtifactIdentity; inputSha256: string } | null {
+  let taskContent: string;
+  try { taskContent = fs.readFileSync(path.join(taskDir, 'task.md'), 'utf8'); }
+  catch { return null; }
+  let receipt;
+  try { receipt = receiptForOutput(taskContent, code.name); }
+  catch { return null; }
+  if (!receipt || receipt.event !== 'code.completed') return null;
+  const plan = inspectArtifactDirectory(taskDir, 'plan');
+  if (plan.status !== 'ready') return null;
+  const input = plan.artifacts.find((artifact) => artifact.name === receipt.input);
+  return input ? { input, inputSha256: receipt.inputSha256 } : null;
+}
+
+function resolveCodePlanInput(taskDir: string, code: ArtifactIdentity): { input: ArtifactIdentity; inputSha256: string } | null {
+  return resolveCodeInputReceipt(taskDir, code);
+}
+
 function assertWritableInventory(inventory: ArtifactInventoryResult): ArtifactError | null {
   if (inventory.status === 'failed') return inventory.error;
   const blockers = inventory.diagnostics.filter((item) => BLOCKING_DIAGNOSTICS.has(item.code));
@@ -257,7 +310,8 @@ const OPTIONAL_CONTEXT: Partial<Record<ArtifactFamily, { family: ArtifactFamily;
   analysis: { family: 'review-analysis', requireReference: true },
   plan: { family: 'review-plan', requireReference: true },
   'review-code': { family: 'review-plan' },
-  'manual-validation': { family: 'review-code' }
+  'manual-validation': { family: 'review-code' },
+  'validation-run': { family: 'review-code' }
 };
 
 function resolveArtifactContext(taskRef: string, family: string, options: InspectOptions = {}): ArtifactContextResult {
@@ -310,11 +364,21 @@ function resolveCodeContext(inventory: ArtifactInventoryResult, options: Inspect
     return withCodeMode(inventory, inputs, 'ready', 'init', codeMax, reviewMax, null, null,
       'No prior code artifact. Starting initial implementation (round 1 -> code.md).');
   }
+  const codePlanInput = resolveCodePlanInput(inventory.taskDir!, latestCode);
+  if (!codePlanInput) {
+    return contextFailure(inventory, 'ARTIFACT_REFERENCE_INVALID', `code completion receipt for ${latestCode.name} is missing or does not match the current plan`, latestCode.name);
+  }
+  if (reviewPlan.latest && !reviewPlan.reviewedInput) {
+    return contextFailure(inventory, 'ARTIFACT_REFERENCE_INVALID', `${reviewPlan.latest.name} has no valid reviewed input`, reviewPlan.latest.name);
+  }
   if (reviewPlan.latest && reviewPlan.reviewedInput?.name === plan.latest.name) {
     const verdict = parseVerdict(reviewPlan.latest.path);
-    if (verdict.ok && verdict.verdict === 'Approved' && reviewPlan.latest.mtimeMs > latestCode.mtimeMs) {
+    const reviewedPlanSha256 = sha256File(reviewPlan.reviewedInput.path);
+    if (verdict.ok && verdict.verdict === 'Approved' && (
+      codePlanInput.input.name !== plan.latest.name || codePlanInput.inputSha256 !== reviewedPlanSha256
+    )) {
       return withCodeMode(inventory, inputs, 'ready', 'init', codeMax, reviewMax, verdict.verdict, reviewPlan.latest.name,
-        `Latest ${reviewPlan.latest.name} is approved and newer than the latest code artifact. Entering replan-driven init.`);
+        `Latest ${reviewPlan.latest.name} approves plan content not captured by the latest code input receipt. Entering replan-driven init.`);
     }
   }
   if (reviewMax < codeMax) {
@@ -376,12 +440,11 @@ function resolveDecisionImplementationInput(
   if (pending.length === 0) return { input: null };
   const activity = locateActivityLog(content);
   if (!activity) return { error: 'task has no unique Activity Log section' };
-  const reviewEntries = activity.entries.filter((entry) =>
+  const completed = activity.entries.some((entry) =>
     /^Review Code \(Round \d+\)$/.test(entry.step) && entry.note.includes(`→ ${review.name}`)
   );
-  const completed = reviewEntries.at(-1);
   if (!completed) return { error: `cannot find completed Activity Log identity for ${review.name}` };
-  try { return { input: selectPendingImplementationInput(rows, completed.time) }; }
+  try { return { input: selectPendingImplementationInput(rows) }; }
   catch (error) { return { error: error instanceof Error ? error.message : String(error) }; }
 }
 
@@ -439,6 +502,7 @@ function buildArtifactLinkSection(content: string, artifact: ArtifactIdentity):
 export {
   artifactFamilyCatalog, artifactName, parseArtifactName, familySpec,
   inspectTaskArtifacts, inspectArtifactDirectory, resolveArtifactContext,
+  parseReviewedInputReference, parseCodePlanInputReference, resolveCodePlanInput, reviewEventName,
   assertWritableInventory, validateCompletedArtifact, buildArtifactLinkSection
 };
 export type {

package/lib/task/artifact-receipts.ts

@@ -0,0 +1,161 @@
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+
+import { extractSection, findSectionHeading, parseTable } from './sections.ts';
+
+const RECEIPT_SECTION_ALIASES = ['产物生命周期收据', 'Artifact Lifecycle Receipts'] as const;
+const RECEIPT_COLUMNS = ['event', 'output', 'input', 'input_sha256', 'completed_at'] as const;
+const RECEIPT_EVENTS = new Set([
+  'review-analysis.completed',
+  'review-plan.completed',
+  'review-code.completed',
+  'code.completed'
+]);
+const SHA256_RE = /^[a-f0-9]{64}$/;
+const ARTIFACT_NAME_RE = /^(analysis|review-analysis|plan|review-plan|code|review-code|manual-validation|validation-run|pr-review)(?:-r([2-9]|[1-9]\d+))?\.md$/;
+const RECEIPT_SHAPES = {
+  'review-analysis.completed': { output: 'review-analysis', input: 'analysis' },
+  'review-plan.completed': { output: 'review-plan', input: 'plan' },
+  'review-code.completed': { output: 'review-code', input: 'code' },
+  'code.completed': { output: 'code', input: 'plan' }
+} as const;
+
+type ArtifactReceiptEvent =
+  | 'review-analysis.completed'
+  | 'review-plan.completed'
+  | 'review-code.completed'
+  | 'code.completed';
+type ArtifactReceipt = {
+  event: ArtifactReceiptEvent;
+  output: string;
+  input: string;
+  inputSha256: string;
+  completedAt: string;
+};
+type ArtifactReceiptParseResult = {
+  present: boolean;
+  rows: readonly ArtifactReceipt[];
+};
+type ReceiptSectionMutation = {
+  aliases: readonly string[];
+  heading: string;
+  body: string;
+};
+
+class ArtifactReceiptError extends Error {
+  readonly code = 'ARTIFACT_RECEIPT_INVALID';
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'ArtifactReceiptError';
+  }
+}
+
+function sha256Bytes(value: Buffer): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function sha256File(filePath: string): string {
+  return sha256Bytes(fs.readFileSync(filePath));
+}
+
+function parseReceiptArtifactName(name: string): { family: string } | null {
+  const match = ARTIFACT_NAME_RE.exec(name);
+  if (!match) return null;
+  const roundText = match[2];
+  if (roundText !== undefined) {
+    const round = Number(roundText);
+    if (!Number.isSafeInteger(round) || String(round) !== roundText) return null;
+  }
+  return { family: match[1]! };
+}
+
+function validateReceiptShape(event: ArtifactReceiptEvent, output: string, input: string): void {
+  const outputIdentity = parseReceiptArtifactName(output);
+  const inputIdentity = parseReceiptArtifactName(input);
+  if (!outputIdentity || !inputIdentity) throw new ArtifactReceiptError(`receipt artifact identity is invalid: ${output} -> ${input}`);
+  const shape = RECEIPT_SHAPES[event];
+  if (outputIdentity.family !== shape.output || inputIdentity.family !== shape.input) {
+    throw new ArtifactReceiptError(`receipt event '${event}' does not match ${output} -> ${input}`);
+  }
+}
+
+function parseArtifactReceipts(content: string): ArtifactReceiptParseResult {
+  const section = extractSection(content, [...RECEIPT_SECTION_ALIASES]);
+  if (!section) return { present: false, rows: [] };
+
+  let table;
+  try {
+    table = parseTable(content, {
+      sectionAliases: [...RECEIPT_SECTION_ALIASES],
+      columns: [...RECEIPT_COLUMNS],
+      keyColumn: 'output'
+    });
+  } catch (error) {
+    throw new ArtifactReceiptError(error instanceof Error ? error.message : String(error));
+  }
+  if (!table) throw new ArtifactReceiptError('receipt section has no receipt table');
+
+  const rows = table.rows.map((row) => {
+    const event = row.values.event ?? '';
+    const output = row.values.output ?? '';
+    const input = row.values.input ?? '';
+    const inputSha256 = row.values.input_sha256 ?? '';
+    const completedAt = row.values.completed_at ?? '';
+    if (!RECEIPT_EVENTS.has(event)) throw new ArtifactReceiptError(`unknown receipt event '${event}'`);
+    if (!output || !input) throw new ArtifactReceiptError('receipt output and input are required');
+    validateReceiptShape(event as ArtifactReceiptEvent, output, input);
+    if (!SHA256_RE.test(inputSha256)) throw new ArtifactReceiptError(`receipt digest for '${output}' is invalid`);
+    if (!completedAt || Number.isNaN(Date.parse(completedAt.replace(' ', 'T')))) {
+      throw new ArtifactReceiptError(`receipt completion time for '${output}' is invalid`);
+    }
+    return {
+      event: event as ArtifactReceiptEvent,
+      output,
+      input,
+      inputSha256,
+      completedAt
+    };
+  });
+  return { present: true, rows };
+}
+
+function receiptForOutput(content: string, output: string): ArtifactReceipt | null {
+  const parsed = parseArtifactReceipts(content);
+  return parsed.rows.find((row) => row.output === output) ?? null;
+}
+
+function upsertArtifactReceipt(content: string, receipt: ArtifactReceipt): ReceiptSectionMutation {
+  if (!RECEIPT_EVENTS.has(receipt.event)) throw new ArtifactReceiptError(`unknown receipt event '${receipt.event}'`);
+  if (!receipt.output || !receipt.input) throw new ArtifactReceiptError('receipt output and input are required');
+  validateReceiptShape(receipt.event, receipt.output, receipt.input);
+  if (!SHA256_RE.test(receipt.inputSha256)) throw new ArtifactReceiptError(`receipt digest for '${receipt.output}' is invalid`);
+  if (!receipt.completedAt || Number.isNaN(Date.parse(receipt.completedAt.replace(' ', 'T')))) {
+    throw new ArtifactReceiptError(`receipt completion time for '${receipt.output}' is invalid`);
+  }
+
+  const existing = parseArtifactReceipts(content).rows;
+  const previous = existing.find((row) => row.output === receipt.output);
+  if (previous && JSON.stringify(previous) !== JSON.stringify(receipt)) {
+    throw new ArtifactReceiptError(`receipt for '${receipt.output}' already exists with different evidence`);
+  }
+  const rows = previous ? existing : [...existing, receipt];
+  const heading = findSectionHeading(content, [...RECEIPT_SECTION_ALIASES]);
+  const body = [
+    `| ${RECEIPT_COLUMNS.join(' | ')} |`,
+    `| ${RECEIPT_COLUMNS.map(() => '---').join(' | ')} |`,
+    ...rows.map((row) => `| ${row.event} | ${row.output} | ${row.input} | ${row.inputSha256} | ${row.completedAt} |`)
+  ].join('\n');
+  return { aliases: [...RECEIPT_SECTION_ALIASES], heading, body };
+}
+
+export {
+  ArtifactReceiptError,
+  RECEIPT_SECTION_ALIASES,
+  parseArtifactReceipts,
+  receiptForOutput,
+  sha256Bytes,
+  sha256File,
+  upsertArtifactReceipt
+};
+export type { ArtifactReceipt, ArtifactReceiptEvent, ArtifactReceiptParseResult, ReceiptSectionMutation };