@agent-delivery-harness/cli 0.2.0 → 0.5.0

package/src/record-retention.ts

@@ -0,0 +1,325 @@
+/** Opt-in ownership and pruning for tracked per-digest delivery records. */
+import { createHash, randomUUID } from "node:crypto";
+import { execFile } from "node:child_process";
+import { constants as fsConstants } from "node:fs";
+import { chmod, lstat, mkdir, open, readFile, readdir, rename, unlink } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import {
+  ProcessLockRefused,
+  deriveDeliveryRecordPath,
+  resolveRecordStorage,
+  sha256Hex,
+  withProcessLock,
+} from "@agent-delivery-harness/kernel";
+
+const execFileAsync = promisify(execFile);
+const SCOPE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const DIGEST = /^[a-f0-9]{64}$/;
+const LEDGER_VERSION = "delivery-record-retention/1";
+const RETENTION_LEAF = "delivery-record-retention";
+
+interface Receipt {
+  readonly relativePath: string;
+  readonly deliverableDigest: string;
+  readonly sha256: string;
+}
+
+interface Ledger {
+  readonly version: typeof LEDGER_VERSION;
+  readonly scope: string;
+  readonly recordBasePath: string;
+  readonly owned: readonly Receipt[];
+  readonly pendingPrune: readonly Receipt[];
+}
+
+export type RecordRetentionCode =
+  | "retention_scope_invalid"
+  | "retention_bound_invalid"
+  | "retention_ledger_unsafe"
+  | "retention_ledger_invalid"
+  | "retention_ownership_ambiguous"
+  | "retention_path_unowned"
+  | "retention_owned_record_changed"
+  | "retention_owned_record_unsafe"
+  | "retention_history_missing"
+  | "retention_write_failed"
+  | "retention_cleanup_failed"
+  | "retention_lock_unavailable";
+
+export type RecordRetentionResult =
+  | { readonly ok: true; readonly pruned: readonly string[]; readonly ledgerPath: string }
+  | { readonly ok: false; readonly code: RecordRetentionCode; readonly detail: string };
+type RecordRetentionFailure = Extract<RecordRetentionResult, { readonly ok: false }>;
+
+export interface ApplyDeliveryRecordRetentionInput {
+  readonly rootDir: string;
+  readonly storageNamespace: string;
+  readonly scope: string;
+  readonly keepSuperseded: number;
+  readonly recordBasePath: string;
+  readonly current: {
+    readonly relativePath: string;
+    readonly deliverableDigest: string;
+    readonly bytes: string;
+  };
+  readonly writeCurrent: () => Promise<void>;
+}
+
+const failure = (code: RecordRetentionCode, detail: string): RecordRetentionFailure => ({ ok: false, code, detail });
+const scopeDigest = (scope: string): string => createHash("sha256").update(scope, "utf8").digest("hex");
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function receipt(value: unknown, recordBasePath: string): Receipt | undefined {
+  if (!isRecord(value) || Object.keys(value).sort().join(",") !== "deliverableDigest,relativePath,sha256") return undefined;
+  const relativePath = value["relativePath"];
+  const deliverableDigest = value["deliverableDigest"];
+  const sha256 = value["sha256"];
+  if (typeof relativePath !== "string" || typeof deliverableDigest !== "string" || !DIGEST.test(deliverableDigest) ||
+      typeof sha256 !== "string" || !DIGEST.test(sha256) || deriveDeliveryRecordPath(recordBasePath, deliverableDigest) !== relativePath) return undefined;
+  return { relativePath, deliverableDigest, sha256 };
+}
+
+function parseLedger(value: unknown, expectedName: string): Ledger | undefined {
+  if (!isRecord(value) || Object.keys(value).sort().join(",") !== "owned,pendingPrune,recordBasePath,scope,version" ||
+      value["version"] !== LEDGER_VERSION || typeof value["scope"] !== "string" || !SCOPE.test(value["scope"]) ||
+      typeof value["recordBasePath"] !== "string" || !Array.isArray(value["owned"]) || !Array.isArray(value["pendingPrune"]) ||
+      `${scopeDigest(value["scope"])}.json` !== expectedName) return undefined;
+  const owned = value["owned"].map((entry) => receipt(entry, value["recordBasePath"] as string));
+  const pendingPrune = value["pendingPrune"].map((entry) => receipt(entry, value["recordBasePath"] as string));
+  if (owned.some((entry) => entry === undefined) || pendingPrune.some((entry) => entry === undefined)) return undefined;
+  const paths = [...owned, ...pendingPrune].map((entry) => entry!.relativePath);
+  if (new Set(paths).size !== paths.length) return undefined;
+  return {
+    version: LEDGER_VERSION,
+    scope: value["scope"],
+    recordBasePath: value["recordBasePath"],
+    owned: owned as Receipt[],
+    pendingPrune: pendingPrune as Receipt[],
+  };
+}
+
+async function readLedgers(storageDir: string): Promise<RecordRetentionFailure | { readonly ok: true; readonly ledgers: Map<string, Ledger> }> {
+  const ledgers = new Map<string, Ledger>();
+  for (const name of await readdir(storageDir).catch((error: NodeJS.ErrnoException) => {
+    if (error.code === "ENOENT") return [] as string[];
+    throw error;
+  })) {
+    if (!name.endsWith(".json")) continue;
+    const ledgerPath = path.join(storageDir, name);
+    const stats = await lstat(ledgerPath).catch(() => undefined);
+    if (stats === undefined || !stats.isFile() || stats.isSymbolicLink() || (stats.mode & 0o077) !== 0) {
+      return failure("retention_ledger_unsafe", `${ledgerPath} is not an owner-only regular file`);
+    }
+    let value: unknown;
+    try {
+      value = JSON.parse(await readFile(ledgerPath, "utf8"));
+    } catch {
+      return failure("retention_ledger_invalid", `${ledgerPath} is not valid JSON`);
+    }
+    const parsed = parseLedger(value, name);
+    if (parsed === undefined) return failure("retention_ledger_invalid", `${ledgerPath} has an unsupported or inconsistent shape`);
+    ledgers.set(parsed.scope, parsed);
+  }
+  const owners = new Map<string, string>();
+  for (const ledger of ledgers.values()) {
+    for (const entry of [...ledger.owned, ...ledger.pendingPrune]) {
+      const prior = owners.get(entry.relativePath);
+      if (prior !== undefined && prior !== ledger.scope) {
+        return failure("retention_ownership_ambiguous", `${entry.relativePath} is claimed by ${prior} and ${ledger.scope}`);
+      }
+      owners.set(entry.relativePath, ledger.scope);
+    }
+  }
+  return { ok: true, ledgers };
+}
+
+async function writeLedger(ledgerPath: string, ledger: Ledger): Promise<void> {
+  await mkdir(path.dirname(ledgerPath), { recursive: true, mode: 0o700 });
+  await chmod(path.dirname(ledgerPath), 0o700);
+  const temporary = `${ledgerPath}.tmp-${randomUUID()}`;
+  const handle = await open(temporary, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL, 0o600);
+  try {
+    await handle.writeFile(`${JSON.stringify(ledger)}\n`, "utf8");
+    await handle.sync();
+    await handle.chmod(0o600);
+  } finally {
+    await handle.close();
+  }
+  await rename(temporary, ledgerPath);
+}
+
+async function verifyWorkingRecord(rootDir: string, entry: Receipt): Promise<RecordRetentionResult | { readonly ok: true }> {
+  const absolute = path.join(rootDir, entry.relativePath);
+  const stats = await lstat(absolute).catch((error: NodeJS.ErrnoException) => error.code === "ENOENT" ? undefined : Promise.reject(error));
+  if (stats === undefined) return failure("retention_owned_record_changed", `${entry.relativePath} is missing`);
+  if (!stats.isFile() || stats.isSymbolicLink()) return failure("retention_owned_record_unsafe", `${entry.relativePath} is not a regular file`);
+  if (sha256Hex(await readFile(absolute)) !== entry.sha256) {
+    return failure("retention_owned_record_changed", `${entry.relativePath} no longer matches its ownership receipt`);
+  }
+  return { ok: true };
+}
+
+async function gitCarriesExactRecord(rootDir: string, entry: Receipt): Promise<boolean> {
+  try {
+    const { stdout: listing } = await execFileAsync("git", ["ls-tree", "HEAD", "--", entry.relativePath], { cwd: rootDir, encoding: "utf8" });
+    if (!listing.startsWith("100644 blob ") || !listing.endsWith(`\t${entry.relativePath}\n`)) return false;
+    const { stdout } = await execFileAsync("git", ["show", `HEAD:${entry.relativePath}`], { cwd: rootDir, encoding: "buffer", maxBuffer: 20 * 1024 * 1024 });
+    return sha256Hex(stdout) === entry.sha256;
+  } catch {
+    return false;
+  }
+}
+
+export async function applyDeliveryRecordRetention(input: ApplyDeliveryRecordRetentionInput): Promise<RecordRetentionResult> {
+  if (!SCOPE.test(input.scope)) return failure("retention_scope_invalid", "retention scope must be a plain 1-128 character key");
+  if (!Number.isSafeInteger(input.keepSuperseded) || input.keepSuperseded < 0 || input.keepSuperseded > 100) {
+    return failure("retention_bound_invalid", "keepSuperseded must be an integer from 0 through 100");
+  }
+  if (!DIGEST.test(input.current.deliverableDigest) ||
+      deriveDeliveryRecordPath(input.recordBasePath, input.current.deliverableDigest) !== input.current.relativePath) {
+    return failure("retention_ledger_invalid", "the current path is not the configured per-digest record path");
+  }
+
+  const storage = await resolveRecordStorage(input.rootDir, { storageNamespace: input.storageNamespace, leaf: RETENTION_LEAF });
+  const ledgerPath = path.join(storage.storageDir, `${scopeDigest(input.scope)}.json`);
+  // Ownership is global to this worktree store. Serializing only one scope
+  // would let two scopes reserve the same absent digest path concurrently.
+  const lockPath = path.join(storage.storageDir, ".ownership.lock");
+  await mkdir(storage.storageDir, { recursive: true, mode: 0o700 });
+
+  try {
+    return await withProcessLock(lockPath, 5000, async () => {
+      const loaded = await readLedgers(storage.storageDir);
+      if (!loaded.ok) return loaded;
+      const existing = loaded.ledgers.get(input.scope);
+      if (existing !== undefined && existing.recordBasePath !== input.recordBasePath) {
+        return failure("retention_ledger_invalid", `retention scope ${input.scope} was created for a different delivery record path`);
+      }
+      let ledger: Ledger = existing ?? {
+        version: LEDGER_VERSION,
+        scope: input.scope,
+        recordBasePath: input.recordBasePath,
+        owned: [],
+        pendingPrune: [],
+      };
+
+      const currentSha = sha256Hex(input.current.bytes);
+      const currentReceipt: Receipt = {
+        relativePath: input.current.relativePath,
+        deliverableDigest: input.current.deliverableDigest,
+        sha256: currentSha,
+      };
+
+      // A retried delivery may return to a path whose deletion was durably
+      // scheduled by an interrupted later attempt. Cancel that deletion before
+      // touching any pending path; the invocation's verified current record wins.
+      const returningCurrent = ledger.pendingPrune.find((entry) => entry.relativePath === currentReceipt.relativePath);
+      if (returningCurrent !== undefined) {
+        if (returningCurrent.sha256 !== currentReceipt.sha256 || returningCurrent.deliverableDigest !== currentReceipt.deliverableDigest) {
+          return failure("retention_owned_record_changed", `${currentReceipt.relativePath} conflicts with its pending ownership receipt`);
+        }
+        ledger = {
+          ...ledger,
+          owned: [...ledger.owned, returningCurrent],
+          pendingPrune: ledger.pendingPrune.filter((entry) => entry.relativePath !== currentReceipt.relativePath),
+        };
+        await writeLedger(ledgerPath, ledger);
+      }
+
+      // Complete an interrupted, already-proved pruning decision first.
+      for (const pending of ledger.pendingPrune) {
+        const absolute = path.join(input.rootDir, pending.relativePath);
+        const present = await lstat(absolute).then(() => true, (error: NodeJS.ErrnoException) => error.code === "ENOENT" ? false : Promise.reject(error));
+        if (present) {
+          const verified = await verifyWorkingRecord(input.rootDir, pending);
+          if (!verified.ok) return verified;
+          if (!await gitCarriesExactRecord(input.rootDir, pending)) {
+            return failure("retention_history_missing", `${pending.relativePath} is not preserved byte-for-byte at HEAD`);
+          }
+          try {
+            await unlink(absolute);
+          } catch (error) {
+            return failure("retention_cleanup_failed", `could not remove ${pending.relativePath}: ${error instanceof Error ? error.message : String(error)}`);
+          }
+        }
+      }
+      if (ledger.pendingPrune.length > 0) {
+        ledger = { ...ledger, pendingPrune: [] };
+        await writeLedger(ledgerPath, ledger);
+      }
+
+      const currentIndex = ledger.owned.findIndex((entry) => entry.relativePath === currentReceipt.relativePath);
+      if (currentIndex >= 0 && (ledger.owned[currentIndex]!.sha256 !== currentSha ||
+          ledger.owned[currentIndex]!.deliverableDigest !== currentReceipt.deliverableDigest)) {
+        return failure("retention_owned_record_changed", `${currentReceipt.relativePath} conflicts with its ownership receipt`);
+      }
+      for (const other of loaded.ledgers.values()) {
+        if (other.scope !== input.scope && [...other.owned, ...other.pendingPrune].some((entry) => entry.relativePath === currentReceipt.relativePath)) {
+          return failure("retention_ownership_ambiguous", `${currentReceipt.relativePath} belongs to retention scope ${other.scope}`);
+        }
+      }
+      const currentStats = await lstat(path.join(input.rootDir, currentReceipt.relativePath)).catch((error: NodeJS.ErrnoException) =>
+        error.code === "ENOENT" ? undefined : Promise.reject(error));
+      if (currentIndex < 0 && currentStats !== undefined) {
+        return failure("retention_path_unowned", `${currentReceipt.relativePath} existed before retention scope ${input.scope} owned it`);
+      }
+
+      // Validate every prior live receipt before deciding what this attempt may remove.
+      for (const entry of ledger.owned) {
+        if (entry.relativePath === currentReceipt.relativePath && currentStats === undefined) continue;
+        const verified = await verifyWorkingRecord(input.rootDir, entry);
+        if (!verified.ok) return verified;
+      }
+      const ordered = [
+        ...ledger.owned.filter((entry) => entry.relativePath !== currentReceipt.relativePath),
+        currentReceipt,
+      ];
+      const retainCount = input.keepSuperseded + 1;
+      const pendingPrune = ordered.slice(0, Math.max(0, ordered.length - retainCount));
+      for (const entry of pendingPrune) {
+        if (!await gitCarriesExactRecord(input.rootDir, entry)) {
+          return failure("retention_history_missing", `${entry.relativePath} is not preserved byte-for-byte at HEAD`);
+        }
+      }
+
+      // Reserve only an absent output. A crash after this point can recreate it,
+      // but can never reinterpret a pre-existing file as scope-owned.
+      ledger = { ...ledger, owned: ordered, pendingPrune: [] };
+      await writeLedger(ledgerPath, ledger);
+      if (currentStats === undefined) {
+        try {
+          await input.writeCurrent();
+        } catch (error) {
+          return failure("retention_write_failed", error instanceof Error ? error.message : String(error));
+        }
+      }
+      const verifiedCurrent = await verifyWorkingRecord(input.rootDir, currentReceipt);
+      if (!verifiedCurrent.ok) return verifiedCurrent;
+
+      if (pendingPrune.length > 0) {
+        const kept = ordered.slice(pendingPrune.length);
+        ledger = { ...ledger, owned: kept, pendingPrune };
+        await writeLedger(ledgerPath, ledger);
+        for (const entry of pendingPrune) {
+          try {
+            await unlink(path.join(input.rootDir, entry.relativePath));
+          } catch (error) {
+            return failure("retention_cleanup_failed", `could not remove ${entry.relativePath}: ${error instanceof Error ? error.message : String(error)}`);
+          }
+        }
+        ledger = { ...ledger, pendingPrune: [] };
+        await writeLedger(ledgerPath, ledger);
+      }
+      return { ok: true, pruned: pendingPrune.map((entry) => entry.relativePath), ledgerPath };
+    });
+  } catch (error) {
+    if (error instanceof ProcessLockRefused) {
+      return failure("retention_lock_unavailable", `retention scope ${input.scope} is already being updated: ${error.reason}`);
+    }
+    throw error;
+  }
+}

package/src/review-evidence.ts

@@ -0,0 +1,284 @@
+/**
+ * The shipped review-outcome evidence writer. It transcribes concluded host
+ * results without running reviewers or upgrading their self-attestation.
+ *
+ * Capture `delivery-harness review-context --json` before review, then pass
+ * that original document to `emit-review-evidence --context <path>` with a
+ * review-outcome/1 document on stdin naming its contextDigest. Reviewer names
+ * come from the resolved activated charters; for example a named result is
+ * `{ "id": "outcome-correctness", "result": "rejected" }`.
+ *
+ * The raw context and outcome remain digest-bound artifacts. Submission is
+ * still the authority on whether the resulting evidence satisfies the gate.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  resolveReviewCharters,
+  validateReviewedContext, parseReviewOutcome, deriveTelemetry, reviewerLists,
+  capturePortableEvidenceContext, repositoryEvidenceReader, createArtifactsPort,
+  ReviewInputError as OutcomeError,
+  BlockedError,
+  digestCanonical,
+  evaluatePreparationReceipt,
+  sha256Hex,
+  type CapturedCandidate,
+  type PreparationReceipt,
+  type HarnessConfig,
+  REVIEW_GREEN_1,
+  REVIEW_GREEN_2,
+} from "@agent-delivery-harness/kernel";
+import type { CommandContext } from "./boundary.ts";
+
+// ── The charters the compiled policy activates ───────────────────────────────
+
+/**
+ * The compiled policy this repository is judged under, and the installed
+ * generation whose archive carries the charters its lenses reference by
+ * identity. One activated lens is one reviewer, and the basename of the
+ * charter path the archive's manifest declares is the reviewer id the evidence
+ * carries — the same two documents `policy-projection-check.ts` compiles the
+ * projection from.
+ */
+export const COMPILED_SNAPSHOT_FILE = ".agents/policy/compiled-snapshot.json";
+export const INSTALLED_ARCHIVE_DIR = ".agent-skills/current";
+
+export const CHARTER_EXTENSION = ".md";
+
+/** Review payloads this provider can emit, in preference order. */
+export const REVIEW_PAYLOAD_SPECS = [REVIEW_GREEN_2, REVIEW_GREEN_1] as const;
+export const REVIEW_PAYLOAD_SPEC = REVIEW_GREEN_2;
+
+/** The envelope spec the manifest declares. */
+export const ENVELOPE_SPEC = "delivery-evidence/1";
+
+/** The outcome document this emitter reads. */
+export const OUTCOME_SPEC = "review-outcome/1";
+
+/** This emitter's own version, carried in the manifest's provider triple. */
+export const EMITTER_VERSION = "1.0.0";
+
+export type { ResolvedCharter } from "@agent-delivery-harness/kernel";
+export async function resolveActivatedCharters(rootDir: string, config?: Pick<HarnessConfig, "additionalReviewLenses">) {
+  return resolveReviewCharters(repositoryEvidenceReader(rootDir, createArtifactsPort()), config);
+}
+export async function resolveReviewerCharters(rootDir: string): Promise<string[]> {
+  return (await resolveActivatedCharters(rootDir)).map((charter) => charter.reviewerId).sort();
+}
+
+/** Exact review input, retained by the host before acquiring any outcomes. */
+export const REVIEW_CONTEXT_SPEC = "review-context/1";
+
+function manifestCandidate(captured: CapturedCandidate) {
+  return {
+    vcs: captured.vcs,
+    treeSha: captured.treeSha,
+    headSha: captured.headSha,
+    deliverable: { digest: captured.deliverable.digest, identity: captured.deliverable.identity },
+    base: { ref: captured.base.ref, tipSha: captured.base.tipSha, mergeBaseSha: captured.base.mergeBaseSha },
+    workspaceId: captured.workspaceId,
+  };
+}
+
+export async function buildReviewContext(
+  rootDir: string,
+  config: HarnessConfig,
+  candidate: CapturedCandidate,
+  receipt: PreparationReceipt,
+) {
+  const inputs = await capturePortableEvidenceContext(config, repositoryEvidenceReader(rootDir, createArtifactsPort()), receipt.preparationFingerprint);
+  const charters = inputs.reviewerCharters;
+  if (charters.length === 0 || inputs.release === null) throw new OutcomeError("the compiled policy activates no review lens or installed release");
+  const binding = {
+    gate: resolveGateBinding(config),
+    candidate: manifestCandidate(candidate),
+    preparationFingerprint: inputs.preparationFingerprint,
+    configurationDigest: inputs.configurationDigest,
+    policyDigest: inputs.policyDigest,
+    release: inputs.release,
+    workflowGraphSha256: inputs.workflowGraphSha256,
+    charters,
+  };
+  return { spec: REVIEW_CONTEXT_SPEC, digest: digestCanonical(binding), binding };
+}
+
+export type ReviewContextDocument = Awaited<ReturnType<typeof buildReviewContext>>;
+
+export { validateReviewedContext, parseReviewOutcome, deriveTelemetry, reviewerLists, REVIEWER_RESULTS } from "@agent-delivery-harness/kernel";
+export type { ReviewOutcome, ReviewerOutcome, ReviewerResult } from "@agent-delivery-harness/kernel";
+export { OutcomeError };
+// ── The gate this provider serves ────────────────────────────────────────────
+
+export interface GateBinding {
+  readonly obligationId: string;
+  readonly providerId: string;
+}
+
+/**
+ * The obligation this manifest answers, and the provider it answers as, taken
+ * from the config rather than from a constant — a provider id that has drifted
+ * from the gate it serves is rejected as `unknown_provider` at evaluation, long
+ * after the review it describes has been paid for.
+ */
+export function resolveGateBinding(config: HarnessConfig): GateBinding {
+  const obligations = config.obligations.filter((obligation) =>
+    REVIEW_PAYLOAD_SPECS.some((payloadSpec) => obligation.acceptedPayloadSpecs.includes(payloadSpec)),
+  );
+  if (obligations.length !== 1) {
+    throw new OutcomeError(
+      `the gate declares ${obligations.length} obligations accepting a supported review.green payload; this provider serves exactly one`,
+    );
+  }
+  const obligation = obligations[0]!;
+  if (obligation.providers.length !== 1) {
+    throw new OutcomeError(
+      `obligation ${obligation.id} names ${obligation.providers.length} providers; this provider serves exactly one`,
+    );
+  }
+  return { obligationId: obligation.id, providerId: obligation.providers[0]! };
+}
+
+function resolveReviewPayloadSpec(
+  config: HarnessConfig,
+  obligationId: string,
+): (typeof REVIEW_PAYLOAD_SPECS)[number] {
+  const obligation = config.obligations.find((entry) => entry.id === obligationId);
+  const payloadSpec = REVIEW_PAYLOAD_SPECS.find((candidate) => obligation?.acceptedPayloadSpecs.includes(candidate));
+  if (payloadSpec === undefined) throw new OutcomeError(`obligation ${obligationId} accepts no supported review.green payload`);
+  return payloadSpec;
+}
+
+// ── The manifest ─────────────────────────────────────────────────────────────
+
+export interface EmitResult {
+  readonly manifestPath: string;
+  readonly runRoot: string;
+}
+
+/**
+ * Capture the candidate, allocate the run root, stamp one approval per
+ * approving reviewer, and write the manifest. The capture is deliberately the
+ * same call the recorder makes at submission (same config, same workspace id,
+ * same identity computation): anything else describes a tree the recorder will
+ * refuse to recognise.
+ */
+export async function emitReviewEvidence(context: CommandContext, original: unknown, document: unknown): Promise<EmitResult> {
+  const { rootDir, config } = context;
+  const wiring = await context.wire();
+  const capture = await wiring.captureCandidate();
+  if (!capture.ok) throw new OutcomeError(`the candidate could not be captured: ${capture.code}`);
+  const captured = capture.candidate;
+  const preparation = await evaluatePreparationReceipt(rootDir, { config, candidate: captured }, wiring.storageOptions);
+  if (!preparation.prepared) throw new BlockedError([...preparation.blockers]);
+  const current = await buildReviewContext(rootDir, config, captured, preparation.receipt);
+  validateReviewedContext(original, current, document);
+  const charters = current.binding.charters.map((charter) => charter.reviewerId).sort();
+  const outcome = parseReviewOutcome(document, charters);
+  const binding = current.binding.gate;
+  const payloadSpec = resolveReviewPayloadSpec(config, binding.obligationId);
+  const candidate = manifestCandidate(captured);
+
+  const provider = {
+    id: binding.providerId,
+    version: EMITTER_VERSION,
+    // One emitter run is one evaluated pass over this candidate.
+    runId: `r-${randomUUID()}`,
+    finalPassId: outcome.finalPassId ?? "pass-1",
+  };
+  const reviewed = original as ReviewContextDocument;
+  const originalRunHistory = outcome.runHistory ?? [{
+    preparedTreeSha: reviewed.binding.candidate.treeSha,
+    evaluatedInPassId: provider.finalPassId,
+  }];
+  const finalEntry = originalRunHistory.at(-1)!;
+  if (finalEntry["preparedTreeSha"] !== reviewed.binding.candidate.treeSha ||
+      finalEntry["evaluatedInPassId"] !== provider.finalPassId) {
+    throw new OutcomeError("the supplied final review pass does not name the original reviewed candidate");
+  }
+  // ENV-9's final tree is a preparation coordinate. A proven neutral reuse
+  // projects that coordinate without claiming the reviewers saw a new raw
+  // tree, adding a round, or overwriting their original history.
+  const runHistory = originalRunHistory.map((entry, index) => index === originalRunHistory.length - 1
+    ? { ...entry, preparedTreeSha: captured.treeSha } : entry);
+
+  const allocation = await context.artifacts.allocateRunRoot({ providerId: provider.id, runId: provider.runId });
+  if (!allocation.ok) throw new OutcomeError(`the run root was refused: ${allocation.reason}`);
+  const runRoot = allocation.runRoot.path;
+
+  const lists = reviewerLists(charters, outcome);
+  await mkdir(path.join(runRoot, "reviewers"), { recursive: true });
+  const artifacts: { path: string; sha256: string; role: string }[] = [];
+  for (const [name, value] of [["review-context", original], ["review-outcome", document]] as const) {
+    const bytes = `${JSON.stringify(value, null, 2)}\n`;
+    await writeFile(path.join(runRoot, `${name}.json`), bytes, "utf8");
+    artifacts.push({ path: `${name}.json`, sha256: sha256Hex(bytes), role: name });
+  }
+  if (digestCanonical(reviewed.binding.candidate) !== digestCanonical(candidate)) {
+    const bytes = `${JSON.stringify({
+      spec: "review-context-projection/1",
+      basis: "unchanged-deliverable-and-review-inputs",
+      originalContextDigest: reviewed.digest,
+      reviewedCandidate: reviewed.binding.candidate,
+      preparedCandidate: candidate,
+      originalRunHistory,
+      reviewRoundAdded: false,
+    }, null, 2)}\n`;
+    await writeFile(path.join(runRoot, "review-context-projection.json"), bytes, "utf8");
+    artifacts.push({ path: "review-context-projection.json", sha256: sha256Hex(bytes), role: "review-context-projection" });
+  }
+  for (const reviewerId of lists.approved) {
+    // §9.2: the stamp re-states the whole binding, so each approval is
+    // independently interpretable in an audit.
+    const stamp = `${JSON.stringify(
+      {
+        schemaVersion: 1,
+        reviewerId,
+        result: "approved",
+        provider: { id: provider.id, runId: provider.runId, finalPassId: provider.finalPassId },
+        workspaceId: candidate.workspaceId,
+        candidate,
+      },
+      null,
+      2,
+    )}\n`;
+    const relativePath = `reviewers/${reviewerId}.json`;
+    await writeFile(path.join(runRoot, relativePath), stamp, "utf8");
+    artifacts.push({ path: relativePath, sha256: sha256Hex(stamp), role: "reviewer-approval" });
+  }
+
+  const manifest = {
+    spec: ENVELOPE_SPEC,
+    provider,
+    candidate,
+    repository: null,
+    runHistory,
+    artifacts,
+    attestation: { level: "self", signatures: [] },
+    recordedAt: new Date().toISOString(),
+    claims: [
+      {
+        obligation: binding.obligationId,
+        payloadSpec,
+        payload: {
+          verdict: outcome.verdict,
+          finalized: true,
+          editedAfterFinalPass: false,
+          reviewers: {
+            selected: lists.selected,
+            completed: lists.completed,
+            failed: lists.failed,
+            timedOut: lists.timedOut,
+          },
+          findings: outcome.findings,
+          telemetry: { ...deriveTelemetry(outcome.findings, runHistory.length), ...(outcome.cost === undefined ? {} : { cost: outcome.cost }) },
+        },
+      },
+    ],
+  };
+
+  const manifestPath = path.join(runRoot, "manifest.json");
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+  return { manifestPath, runRoot };
+}