@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/src/archive/duplicatecounts.ts

@@ -0,0 +1,98 @@
+import { join } from "node:path";
+import { lstat } from "node:fs/promises";
+// A duplicate's unlink and the live SQLite counter cannot share a transaction.
+// Persist its identity first; settle the receipt and counter together once the
+// source is confirmed gone. A changed source cancels that removal attempt.
+import { createHash } from "node:crypto";
+import type { StateStore } from "../state.js";
+import { identityOrNull } from "./gzfile.js";
+import { sameIdentity, type FileIdentity } from "./fsutil.js";
+import { bumpMark } from "./rows.js";
+
+interface Pending {
+  path: string;
+  identity: FileIdentity;
+}
+const NAMESPACE = "duplicate.unlink.";
+const PR_OF_KEY = new RegExp(`^${NAMESPACE.replaceAll(".", "\\.")}([1-9][0-9]*)\\.`);
+const prefix = (pr: number): string => `${NAMESPACE}${pr}.`;
+
+export function prepareDuplicateCount(store: StateStore, pr: number, value: Pending): string {
+  const key = prefix(pr) + createHash("sha256").update(JSON.stringify(value)).digest("hex");
+  store.db
+    .prepare("INSERT OR IGNORE INTO archive_marks (name,value) VALUES (?,?)")
+    .run(key, JSON.stringify(value));
+  return key;
+}
+
+export function finishDuplicateCount(store: StateStore, key: string, removed: boolean): void {
+  store.db.transaction(() => {
+    const deleted = store.db.prepare("DELETE FROM archive_marks WHERE name=?").run(key).changes;
+    if (deleted && removed) bumpMark(store, "duplicates.removed", 1);
+  })();
+}
+
+export async function recoverDuplicateCounts(
+  store: StateStore,
+  pr: number,
+  legacyPath: string,
+): Promise<number> {
+  const pending = store.db
+    .prepare("SELECT name,value FROM archive_marks WHERE name GLOB ?")
+    .all(`${prefix(pr)}*`) as Array<{ name: string; value: string }>;
+  let recovered = 0;
+  for (const row of pending) {
+    const value = JSON.parse(row.value) as Pending;
+    if (
+      value.path !== legacyPath ||
+      !value.identity ||
+      ![value.identity.dev, value.identity.ino, value.identity.size, value.identity.mtimeMs].every(
+        Number.isFinite,
+      )
+    )
+      throw new Error("unreadable duplicate removal receipt");
+    const current = await identityOrNull(value.path);
+    if (current === null) {
+      // A nonregular replacement is changed, not absent.
+      try {
+        await lstat(value.path);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+        finishDuplicateCount(store, row.name, true);
+        recovered++;
+        continue;
+      }
+      finishDuplicateCount(store, row.name, false);
+    } else if (!sameIdentity(value.identity, current)) finishDuplicateCount(store, row.name, false);
+  }
+  return recovered;
+}
+
+/** Pending unlink accounting survives a reopen as well as a stopped PR pass. */
+export async function recoverAllDuplicateCounts(
+  store: StateStore,
+  root: string,
+  failed: (pr: number, error: unknown) => void,
+): Promise<number> {
+  const rows = store.db
+    .prepare("SELECT name FROM archive_marks WHERE name GLOB ?")
+    .all(`${NAMESPACE}*`) as Array<{ name: string }>;
+  const prs = new Set<number>();
+  for (const row of rows) {
+    const match = PR_OF_KEY.exec(row.name);
+    if (match && Number.isSafeInteger(Number(match[1]))) prs.add(Number(match[1]));
+  }
+  let recovered = 0;
+  for (const pr of prs) {
+    try {
+      recovered += await recoverDuplicateCounts(
+        store,
+        pr,
+        join(root, "archive", `pr-${pr}`, "session.jsonl"),
+      );
+    } catch (error) {
+      failed(pr, error);
+    }
+  }
+  return recovered;
+}

package/src/archive/eligibility.ts

@@ -0,0 +1,181 @@
+// Archive eligibility (docs/archiving.md §7.1) — one function,
+// `prEligibility`, the rule every archive pass and the synchronous re-check
+// right before an unlink apply. A PR's files may leave the live tree
+// only when EVERY clause holds:
+//
+//   - pr_state says `closed` (a PR with no registry row is unknown, never
+//     eligible — its dirs are orphans, reported and never touched);
+//   - its close is at least `[archive] after_days` old. The close time is the
+//     newest `pr_closed` event (an indexed lookup), else `pr_state.updated_at`;
+//     a PR restored earlier counts from the newer of its close and its
+//     `archive_prs.restored_at`;
+//   - no worker of `pr-<n>` runs (its lease, confirmed by the process table —
+//     src/workerliveness.ts; leases that cannot be read are unknown and hold);
+//   - no session birth is in flight;
+//   - no `rounds` row is running (or overdue — not terminal either);
+//   - no `session_commands` row is pending or running;
+//   - no `review_failures` row owes work (`work_owed = 1`) — clearing that on
+//     a closed PR is the owner's `resolve-terminal-failure`, never the
+//     archiver's (docs/archiving.md §0);
+//   - no wake is held for it;
+//   - no top-level `inject/pr-<n>/*.md` whose command row is non-terminal or
+//     missing (an undelivered wake a reborn session would receive; a dir we
+//     could not list holds too).
+//
+// Pure over the store and the facts the caller gathered outside it (worker
+// liveness, births, the inject listing): synchronous, a handful of indexed point reads.
+import type { StateStore } from "../state.js";
+import { TERMINAL_COMMAND_STATUSES } from "./prfiles.js";
+
+export const INELIGIBLE_REASONS = [
+  "unknown_pr",
+  "not_closed",
+  "closed_recently",
+  "worker_alive",
+  "worker_unknown",
+  "birth_in_flight",
+  "round_running",
+  "round_overdue",
+  "command_active",
+  "failure_open",
+  "wake_held",
+  "pending_inject",
+  "inject_unknown",
+] as const;
+export type IneligibleReason = (typeof INELIGIBLE_REASONS)[number];
+
+/** What the caller learned outside the database, for one PR. */
+export interface OutsideFacts {
+  /** Does a worker of `pr-<n>` run? null = the leases could not be read (holds). */
+  workerAlive: boolean | null;
+  /** Is a session birth in flight for it (the daemon's `prSessionBirths`)? */
+  birthInFlight: boolean;
+  /** The absolute paths of the top-level `*.md` files in `inject/pr-<n>/`
+   * ([] when the dir is absent); null = the dir could not be listed (holds). */
+  injectFiles: readonly string[] | null;
+}
+
+export interface Eligibility {
+  pr: number;
+  eligible: boolean;
+  /** The first failing clause, in the order above; null when eligible. */
+  reason: IneligibleReason | null;
+  /** Every failing clause. */
+  reasons: IneligibleReason[];
+  /** The close the window is counted from; null for a PR that is not closed. */
+  closed_at: string | null;
+  closed_source: "pr_closed_event" | "pr_state_updated_at" | null;
+  /** The later of the close and an earlier restore — what the window counts
+   * from. */
+  since: string | null;
+  /** The top-level inject files whose command row is terminal (acked,
+   * cancelled or failed) — leftovers, archived as `stale_inject`. */
+  stale_injects: string[];
+}
+
+const DAY_MS = 86_400_000;
+/** A wake whose command reached one of these is stale — the same terminal
+ * statuses whose payloads the inventory lets leave. */
+const TERMINAL_COMMAND: ReadonlySet<string> = new Set(TERMINAL_COMMAND_STATUSES);
+
+/** When the PR closed, as far as the store says: the newest `pr_closed`
+ * event, else the registry row's `updated_at`. */
+export function closedAt(
+  store: StateStore,
+  pr: number,
+): { at: string; source: "pr_closed_event" | "pr_state_updated_at" } | null {
+  const ev = store.lastEventAt("pr_closed", pr);
+  if (ev && Number.isFinite(Date.parse(ev))) return { at: ev, source: "pr_closed_event" };
+  const row = store.db.prepare("SELECT updated_at FROM pr_state WHERE number = ?").get(pr) as
+    { updated_at: string } | undefined;
+  if (row && Number.isFinite(Date.parse(row.updated_at)))
+    return { at: row.updated_at, source: "pr_state_updated_at" };
+  return null;
+}
+
+/**
+ * Is `pr` eligible for archiving at `now`? Synchronous: every database clause
+ * is an indexed point read; worker liveness, births and the inject listing arrive in
+ * `outside`.
+ */
+export function prEligibility(
+  store: StateStore,
+  pr: number,
+  opts: { now: Date; afterDays: number; outside: OutsideFacts },
+): Eligibility {
+  const out: Eligibility = {
+    pr,
+    eligible: false,
+    reason: null,
+    reasons: [],
+    closed_at: null,
+    closed_source: null,
+    since: null,
+    stale_injects: [],
+  };
+  const fail = (r: IneligibleReason): void => {
+    if (!out.reasons.includes(r)) out.reasons.push(r);
+  };
+  const row = store.db.prepare("SELECT state FROM pr_state WHERE number = ?").get(pr) as
+    { state: string } | undefined;
+  if (!row) fail("unknown_pr");
+  else if (row.state !== "closed") fail("not_closed");
+  else {
+    const close = closedAt(store, pr);
+    out.closed_at = close?.at ?? null;
+    out.closed_source = close?.source ?? null;
+    const restored = store.db
+      .prepare("SELECT restored_at FROM archive_prs WHERE pr = ?")
+      .get(pr) as { restored_at: string | null } | undefined;
+    const sinceMs = Math.max(
+      close ? Date.parse(close.at) : Number.NaN,
+      restored?.restored_at ? Date.parse(restored.restored_at) : Number.NEGATIVE_INFINITY,
+    );
+    if (!Number.isFinite(sinceMs)) fail("closed_recently");
+    else {
+      out.since = new Date(sinceMs).toISOString();
+      if (opts.now.getTime() - sinceMs < opts.afterDays * DAY_MS) fail("closed_recently");
+    }
+  }
+  if (out.reasons.includes("unknown_pr") || out.reasons.includes("not_closed")) {
+    out.reason = out.reasons[0]!;
+    return out;
+  }
+
+  const { workerAlive, birthInFlight, injectFiles } = opts.outside;
+  if (workerAlive === null) fail("worker_unknown");
+  else if (workerAlive) fail("worker_alive");
+  if (birthInFlight) fail("birth_in_flight");
+
+  const rounds = store.db
+    .prepare("SELECT DISTINCT status FROM rounds WHERE pr = ? AND status IN ('running', 'overdue')")
+    .all(pr) as Array<{ status: string }>;
+  if (rounds.some((r) => r.status === "running")) fail("round_running");
+  if (rounds.some((r) => r.status === "overdue")) fail("round_overdue");
+
+  if (
+    store.db
+      .prepare(
+        "SELECT 1 FROM session_commands WHERE pr = ? AND status IN ('pending', 'running') LIMIT 1",
+      )
+      .get(pr)
+  )
+    fail("command_active");
+
+  if (store.db.prepare("SELECT 1 FROM review_failures WHERE pr = ? AND work_owed = 1").get(pr))
+    fail("failure_open");
+
+  if (store.hasHeldWakes(pr)) fail("wake_held");
+
+  if (injectFiles === null) fail("inject_unknown");
+  else
+    for (const file of injectFiles) {
+      const command = store.getSessionCommandByInjectPath(file);
+      if (!command || !TERMINAL_COMMAND.has(command.status)) fail("pending_inject");
+      else out.stale_injects.push(file);
+    }
+
+  out.eligible = out.reasons.length === 0;
+  out.reason = out.reasons[0] ?? null;
+  return out;
+}

package/src/archive/extract.ts

@@ -0,0 +1,342 @@
+// `qcr archive extract <pr> --to <dir>` (docs/archiving.md §11,
+// §15): one PR's archive decompressed into a scratch directory, every byte
+// verified against the sha256 its manifest records. Read-only over the
+// archive, and never into a live tree.
+//
+// Layout under `<to>/`:
+//
+//   transcripts/<name>.jsonl     each archived transcript gzip, decompressed
+//                                (a `.v<k>` or `session-at-close-…` name kept)
+//   files/<live path>            each state file too large for a bundle, and every
+//                                worker round log and lens JSONL (state/live/,
+//                                state/lens/; `qcr open <to>` reads them)
+//   state-<pass>/<live path>     each bundle's records, at the live path they
+//                                were archived from (`same_as` resolved)
+//   manifest.json, ledger.md,    copied as they are — plain, and carrying no
+//   meta.json                    hash of their own
+//
+// Refused before anything is written: a `--to` inside the sandbox root (its
+// live trees `state/`, the pi sessions root, `inject/` and `archive/`, and its
+// code), inside any of those trees wherever a symlink puts them, or one that
+// would CONTAIN any of them (`/`, the root's parent). Symlinks are resolved
+// first. Below `--to`, no symlink is ever followed: every directory an
+// extraction writes in is a plain directory under it, and temporary files are created in a
+// fresh private directory beside the target, never at another output name. Nothing is ever
+// overwritten: a file already there with the same bytes is left (a re-run is
+// idempotent); one with other bytes is reported, never replaced.
+//
+// This runs in the CLI process, never in the daemon; it takes no lock (the
+// archiver only appends to a manifest and never rewrites a placed gzip).
+import { constants } from "node:fs";
+import {
+  copyFile,
+  lstat,
+  mkdir,
+  mkdtemp,
+  realpath,
+  rmdir,
+  utimes,
+  writeFile,
+} from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { readBundleRecords } from "./bundle.js";
+import { fileDigest, gunzipToFile, renameNoReplace, unlinkIfPresent } from "./fsutil.js";
+import {
+  MANIFEST_FILE,
+  ManifestUnreadable,
+  readManifestIfPresent,
+  type Manifest,
+} from "./manifest.js";
+import { injectDirOf } from "./prfiles.js";
+import { holdsArchiveFiles } from "./restore.js";
+
+/** The suffix of a file being extracted (never left behind on a failure). */
+export const EXTRACT_PARTIAL_SUFFIX = ".extract-partial";
+
+export interface ExtractOptions {
+  /** The sandbox root. */
+  root: string;
+  /** `<root>/<[pi] session_dir>`. */
+  sessionsRoot: string;
+  pr: number;
+  /** The scratch directory (created when absent). */
+  to: string;
+  bytesPerS: number;
+  signal?: AbortSignal;
+}
+
+export interface ExtractedFile {
+  /** Relative to `--to`. */
+  path: string;
+  /** The archive file it came from, relative to the PR's archive dir. */
+  from: string;
+  bytes: number;
+  sha256: string;
+  /** `written` now, or `present` already with these exact bytes. */
+  outcome: "written" | "present";
+}
+
+export type ExtractResult =
+  | { ok: false; reason: string }
+  | {
+      ok: true;
+      dir: string;
+      files: ExtractedFile[];
+      /** The plain files copied as they are (no hash to check them by). */
+      copied: string[];
+      /** Files that could not be extracted (verify failure, a different file
+       * already at the target, an unsafe name) — the rest still were. */
+      errors: Array<{ path: string; error: string }>;
+    };
+
+/** `p` with every existing prefix resolved through symlinks. */
+async function realish(p: string): Promise<string> {
+  const abs = resolve(p);
+  const rest: string[] = [];
+  let cur = abs;
+  for (;;) {
+    try {
+      const real = await realpath(cur);
+      return rest.length > 0 ? join(real, ...rest.reverse()) : real;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+      const up = dirname(cur);
+      if (up === cur) return abs;
+      rest.push(basename(cur));
+      cur = up;
+    }
+  }
+}
+
+const inside = (child: string, parent: string): boolean =>
+  child === parent || child.startsWith(parent.endsWith(sep) ? parent : `${parent}${sep}`);
+
+/**
+ * Why `to` may not take an extraction, or null. Refused: inside the sandbox
+ * root or any live tree (symlinks resolved), or containing any of them.
+ */
+export async function liveTreeRefusal(
+  to: string,
+  root: string,
+  sessionsRoot: string,
+): Promise<string | null> {
+  const target = await realish(to);
+  // The most specific tree first, so the refusal names it; the root last.
+  const trees: Array<[string, string]> = [
+    ["the pi sessions root", sessionsRoot],
+    ["state/", join(root, "state")],
+    ["the wake drop-box root", dirname(injectDirOf(root, 0))],
+    ["archive/", join(root, "archive")],
+    ["the sandbox root", root],
+  ];
+  for (const [label, path] of trees) {
+    const real = await realish(path);
+    if (inside(target, real))
+      return `--to ${to} is inside ${label} (${real}) — an extraction never goes into a live tree`;
+    if (inside(real, target))
+      return `--to ${to} contains ${label} (${real}) — an extraction never goes into a live tree`;
+  }
+  return null;
+}
+
+/** A name from the archive, safe to place under `to`: relative, no `..`. */
+function safeUnder(to: string, rel: string): string | null {
+  if (rel.length === 0 || rel.includes("\0") || isAbsolute(rel)) return null;
+  if (rel.split(/[\\/]/).some((seg) => seg === "..")) return null;
+  const target = resolve(to, rel);
+  return inside(target, resolve(to)) && target !== resolve(to) ? target : null;
+}
+
+/**
+ * The partial `target` is written through, made safe to create: every
+ * directory from `to` down to the target's is created or found as a PLAIN
+ * directory (a symlink there is refused, so a write never leaves `--to`).
+ */
+async function preparePartial(to: string, target: string): Promise<void> {
+  const rel = relative(to, dirname(target));
+  let cur = to;
+  for (const seg of rel === "" ? [] : rel.split(sep)) {
+    cur = join(cur, seg);
+    try {
+      await mkdir(cur);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+    }
+    if (!(await lstat(cur)).isDirectory())
+      throw new Error(`${cur} is not a plain directory — an extraction never follows a link`);
+  }
+}
+
+/**
+ * Write one target through its partial: `preparePartial`, then `write` (which
+ * creates the partial and places it). Any failure removes the partial — never
+ * through a directory that was refused — and is returned as its message; a
+ * stop is thrown.
+ */
+async function throughPartial(
+  to: string,
+  target: string,
+  signal: AbortSignal | undefined,
+  write: (partial: string) => Promise<void>,
+): Promise<string | null> {
+  let staging: string | undefined;
+  let partial: string | undefined;
+  try {
+    await preparePartial(to, target);
+    staging = await mkdtemp(join(dirname(target), ".qcr-extract-"));
+    partial = join(staging, `payload${EXTRACT_PARTIAL_SUFFIX}`);
+    await write(partial);
+    return null;
+  } catch (err) {
+    if (signal?.aborted) throw err;
+    return (err as Error).message;
+  } finally {
+    if (partial) await unlinkIfPresent(partial).catch(() => false);
+    if (staging) await rmdir(staging).catch(() => {});
+  }
+}
+
+/** Place `partial` at `target` without replacing anything: a target already
+ * holding the same bytes is `present`; one holding others is an error. */
+async function place(
+  partial: string,
+  target: string,
+  got: { bytes: number; sha256: string },
+  mtimeMs: number | null,
+  bytesPerS: number,
+  signal?: AbortSignal,
+): Promise<"written" | "present"> {
+  if (mtimeMs !== null) await utimes(partial, mtimeMs / 1000, mtimeMs / 1000);
+  if ((await renameNoReplace(partial, target)) === "placed") return "written";
+  await unlinkIfPresent(partial);
+  // What is there is read only when it is a plain file: a link is never
+  // followed out of `--to`, and a FIFO never blocks the read.
+  if (!(await lstat(target)).isFile())
+    throw new Error(`${target} exists and is not a plain file — never followed or overwritten`);
+  const there = await fileDigest(target, { bytesPerS, ...(signal ? { signal } : {}) });
+  if (there.bytes === got.bytes && there.sha256 === got.sha256) return "present";
+  throw new Error(`${target} already holds other bytes — never overwritten`);
+}
+
+/** Extract one PR's archive into `opts.to` (see the header). */
+export async function extractPr(opts: ExtractOptions): Promise<ExtractResult> {
+  const { root, pr, bytesPerS, signal } = opts;
+  const refusal = await liveTreeRefusal(opts.to, root, opts.sessionsRoot);
+  if (refusal) return { ok: false, reason: refusal };
+  const dir = join(root, "archive", `pr-${pr}`);
+  let manifest: Manifest | null;
+  try {
+    manifest = await readManifestIfPresent(dir);
+  } catch (err) {
+    if (err instanceof ManifestUnreadable) return { ok: false, reason: err.message };
+    throw err;
+  }
+  if (manifest === null) {
+    return {
+      ok: false,
+      reason: (await holdsArchiveFiles(dir))
+        ? `${join(dir, "manifest.json")} is missing beside archived files — what they hold cannot be verified`
+        : `pr-${pr} has no archive manifest — nothing of it was archived`,
+    };
+  }
+  const to = resolve(opts.to);
+  await mkdir(to, { recursive: true });
+  const files: ExtractedFile[] = [];
+  const errors: Array<{ path: string; error: string }> = [];
+
+  // Each archive gzip once (a reused entry points at an existing one).
+  const gzips = new Map<string, { bytes: number; sha256: string; mtime_ms: number }>();
+  for (const e of manifest.entries)
+    if ((e.kind === "transcript" || e.kind === "file") && !gzips.has(e.archive))
+      gzips.set(e.archive, { bytes: e.bytes, sha256: e.sha256, mtime_ms: e.mtime_ms });
+  for (const [archive, expect] of gzips) {
+    signal?.throwIfAborted();
+    const rel = archive.replace(/\.gz$/, "");
+    const target = safeUnder(to, rel);
+    if (!target || !archive.endsWith(".gz") || !safeUnder(dir, archive)) {
+      errors.push({ path: archive, error: "an unsafe archive name — skipped" });
+      continue;
+    }
+    const error = await throughPartial(to, target, signal, async (partial) => {
+      const got = await gunzipToFile(join(dir, archive), partial, {
+        bytesPerS,
+        signal,
+        exclusive: true,
+      });
+      if (got.bytes !== expect.bytes || got.sha256 !== expect.sha256)
+        throw new Error(
+          `${archive} decompressed to ${got.bytes} bytes / ${got.sha256.slice(0, 12)}…, the manifest records ${expect.bytes} / ${expect.sha256.slice(0, 12)}…`,
+        );
+      const outcome = await place(partial, target, got, expect.mtime_ms, bytesPerS, signal);
+      files.push({ path: relative(to, target), from: archive, ...got, outcome });
+    });
+    if (error !== null) errors.push({ path: rel, error });
+  }
+
+  // Each bundle's records, under `state-<pass>/`.
+  for (const e of manifest.entries) {
+    if (e.kind !== "bundle") continue;
+    signal?.throwIfAborted();
+    const bundleDir = e.archive.replace(/\.jsonl\.gz$/, "");
+    if (!safeUnder(dir, e.archive) || !safeUnder(to, bundleDir) || bundleDir === e.archive) {
+      errors.push({ path: e.archive, error: "an unsafe bundle name — skipped" });
+      continue;
+    }
+    let records: Awaited<ReturnType<typeof readBundleRecords>>;
+    try {
+      records = await readBundleRecords(join(dir, e.archive), null, {
+        bytesPerS,
+        ...(signal ? { signal } : {}),
+      });
+    } catch (err) {
+      if (signal?.aborted) throw err;
+      errors.push({ path: e.archive, error: `does not verify: ${(err as Error).message}` });
+      continue;
+    }
+    for (const f of e.files) {
+      const target = safeUnder(to, join(bundleDir, f.path));
+      if (!target || !safeUnder(to, f.path)) {
+        errors.push({ path: f.path, error: "an unsafe record path — skipped" });
+        continue;
+      }
+      const rec = records.get(f.path);
+      const sha = rec?.record.sha256 ?? null;
+      if (!rec || rec.data.length !== f.bytes || sha !== f.sha256) {
+        errors.push({
+          path: relative(to, target),
+          error: rec
+            ? `${e.archive} holds ${rec.data.length} bytes / ${sha!.slice(0, 12)}… for it, the manifest records ${f.bytes} / ${f.sha256.slice(0, 12)}…`
+            : `${e.archive} holds no record for ${f.path}`,
+        });
+        continue;
+      }
+      const error = await throughPartial(to, target, signal, async (partial) => {
+        await writeFile(partial, rec.data, { flag: "wx" });
+        const got = { bytes: rec.data.length, sha256: sha };
+        const outcome = await place(partial, target, got, f.mtime_ms, bytesPerS, signal);
+        files.push({ path: relative(to, target), from: e.archive, ...got, outcome });
+      });
+      if (error !== null) errors.push({ path: relative(to, target), error });
+    }
+  }
+
+  // The plain record, as it is.
+  const copied: string[] = [];
+  for (const name of [MANIFEST_FILE, "ledger.md", "meta.json"]) {
+    const src = join(dir, name);
+    try {
+      if (!(await lstat(src)).isFile()) continue;
+    } catch {
+      continue;
+    }
+    const target = join(to, name);
+    const error = await throughPartial(to, target, signal, async (partial) => {
+      await copyFile(src, partial, constants.COPYFILE_EXCL);
+      const got = await fileDigest(partial, { bytesPerS, ...(signal ? { signal } : {}) });
+      await place(partial, target, got, null, bytesPerS, signal);
+      copied.push(name);
+    });
+    if (error !== null) errors.push({ path: name, error });
+  }
+  return { ok: true, dir: to, files, copied, errors };
+}