trajectories 0.0.0 → 0.1.2

package/legacy/src/sync-truth.ts

@@ -0,0 +1,843 @@
+import type { Database } from "bun:sqlite";
+
+/**
+ * Remote truthfulness primitives: the failure semantics a sync surface must
+ * obey, as a typed vocabulary, a pure state machine, and a persistence
+ * contract — with no transport of any kind in this module.
+ *
+ * Ported from Wake (`iAmCorey/Wake@d9f702b6df0e85`, tag v0.6.5, MIT — mechanics
+ * with attribution, no code copied), `crates/wake-core/src/remote.rs`, whose
+ * remote mirror is the authority for what "the source did not answer" and "the
+ * source answered and holds nothing" are allowed to mean:
+ *
+ * - A **probe before the transfer** decides which paths exist remotely; the full
+ *   whitelist is never handed to the transfer. Wake measured why on this host
+ *   (`remote.rs#L13-L22`): openrsync aborts the remaining file list when one
+ *   source's parent is missing — later sources silently untransferred while the
+ *   exit code is only 23 — and any sender-side I/O error suppresses the deletion
+ *   phase, so `--delete` would never fire. The probe's output is filtered to
+ *   lines equal to a whitelist entry (`#L264-L281`), in whitelist order.
+ * - A **failed probe fails the whole attempt** (`#L333-L354`): no transfer runs
+ *   for that round, and nothing is deleted or written because of it — "cannot
+ *   treat cannot-connect as the remote is empty". An empty source is a fact only
+ *   a reached probe may produce, which is why `empty` is its own terminal kind
+ *   here rather than a quiet `ok`.
+ * - **Exit 24 (a source vanished mid-transfer) is not a failure** (`#L407-L431`);
+ *   exit 23 is a generic "partial transfer" code that may be reclassified as
+ *   vanished sources only when *every* error line names a missing source, across
+ *   the GNU and openrsync dialects (`#L421-L431`). Wake tolerates one re-probe
+ *   when the sources vanished between the probe and the transfer.
+ * - The mirror is **disposable**: removing a source purges its mirror, and the
+ *   purge is re-asserted after every round because an in-flight transfer cannot
+ *   be cancelled and would write the removed tree back (`#L202-L222`).
+ * - Host names are validated before they reach a session key or an argv
+ *   (`#L194-L200`), and a failed attempt records its account while `last_sync_at`
+ *   keeps naming the last sync that completed
+ *   (`crates/wake-core/src/db.rs#L116-L122`, `#L864-L877`).
+ *
+ * What this module deliberately is not: a transport, a scheduler, a mirror. It
+ * spawns no process and touches no filesystem; the drivers that do take the
+ * observations here and hand back the reports. Everything in it is pure except
+ * `readSyncStamps`, which reads a table this build does not create — see
+ * {@link SYNC_STAMP_DDL} for that decision and its ladder obligation.
+ */
+
+// ── Terminal vocabulary ────────────────────────────────────────────────────
+
+/**
+ * Where one sync attempt stands, from the store's point of view. The set is
+ * closed and the kinds are claims, not moods:
+ *
+ * - `ok` — the source was reached and every path its probe confirmed present
+ *   transferred. The mirror holds what the source holds as of this attempt.
+ * - `empty` — the source was reached and holds none of the whitelist. Reachable
+ *   only through a successful probe: this is the kind a failure must never be
+ *   mistaken for.
+ * - `partial` — the source was reached and transferred a subset; the missing
+ *   part is exactly the sources that vanished while the transfer read them. The
+ *   mirror is incomplete in a known way.
+ * - `unreachable` — no contact *in the round that settled*: no transfer ran, and
+ *   nothing was written or deleted for it. The mirror holds exactly what the
+ *   attempt's earlier rounds left, which is nothing at all when none reached.
+ * - `refused` — contact was established or attempted, but the attempt stopped
+ *   short of a mirror state this store can vouch for: an invalid source name, a
+ *   local tool that is not there, a mirror deletion that failed, or a transfer
+ *   error that is not a vanished source. Never a claim of emptiness.
+ */
+export type SyncOutcomeKind = "ok" | "empty" | "partial" | "unreachable" | "refused";
+
+/** Kinds that leave the mirror complete. Exhaustive over the union on purpose. */
+const COMPLETE_KINDS: Record<SyncOutcomeKind, boolean> = {
+  ok: true,
+  empty: true,
+  partial: false,
+  unreachable: false,
+  refused: false,
+};
+
+/** The claim ceiling each terminal verdict licenses ({@link SyncMirrorStanding}). */
+const MIRROR_STANDING: Record<SyncOutcomeKind, SyncMirrorStanding> = {
+  ok: "current",
+  empty: "current",
+  partial: "incomplete",
+  unreachable: "not-claimed",
+  refused: "not-claimed",
+};
+
+/** Why an attempt settled where it did: the machine's closed account of itself. */
+export type SyncReason =
+  /** The source name cannot be addressed: see {@link hostNameRefusal}. */
+  | "host_name_invalid"
+  /** The probe's tool (Wake: `ssh`) is not on this machine. */
+  | "probe_tool_unavailable"
+  /** The probe tool exited non-zero: connect, auth, host key, or remote shell. */
+  | "probe_failed"
+  /** A reached source holds none of the whitelist. */
+  | "source_empty"
+  /** Every path a reached probe confirmed present transferred. */
+  | "transferred"
+  /** Sources vanished before the transfer could read them (Wake's exit 24 / 23). */
+  | "sources_vanished"
+  /** A mirror deletion the probe licensed did not complete. */
+  | "mirror_purge_failed"
+  /** The transfer's tool (Wake: `rsync`) is not on this machine. */
+  | "transfer_tool_unavailable"
+  /** The transfer failed for a reason that is not a vanished source. */
+  | "transfer_failed";
+
+/**
+ * What the attempt did to the disposable mirror beside the store. Only a probe
+ * that reached the source licenses a mirror write, so the two kinds are also a
+ * proof: `keep-untouched` is exactly the no-reached-probe case, and a driver
+ * that reads it as "the mirror is fresh" is reading it wrong — it means this
+ * attempt produced no evidence about the mirror at all.
+ */
+export type SyncCacheAction =
+  /** No probe in this attempt reached the source: the mirror keeps exactly what the last settled attempt left. */
+  | { readonly kind: "keep-untouched" }
+  /**
+   * The source was reached and `paths` are the whitelist paths whose mirror
+   * entries this attempt actually deleted (Wake `remove_cached`,
+   * `remote.rs#L361-L387`). An empty `paths` is a verdict too: the mirror was
+   * compared against a reached source and nothing was removed — whether because
+   * nothing was absent, or because the deletion that was licensed failed. What
+   * the probe licensed is the outcome's own `absent`, deleted or not.
+   */
+  | { readonly kind: "purge"; readonly paths: readonly string[] };
+
+/**
+ * What the caller persists. `last_sync_at` is a claim about *completeness*, not
+ * about activity: an attempt that did not complete records its account and
+ * leaves the stamp naming the last sync that did. This is the one deliberate
+ * tightening of Wake's own record — it stamps a clean success for exit 24
+ * (`db.rs#L864-L877`), which would render a partial transfer as a clean sync.
+ */
+export type SyncStampAction =
+  | { readonly kind: "update-stamp" }
+  | { readonly kind: "record-error" };
+
+/** One settled attempt, with everything a driver, a stamp and a disclosure need. */
+export interface SyncOutcome {
+  /** The name the attempt addressed (Wake: a remote host). */
+  readonly source: string;
+  readonly kind: SyncOutcomeKind;
+  readonly reason: SyncReason;
+  /**
+   * The attempt's account of itself — Wake's `<tool> exited with N: <stderr tail>`
+   * shape (`remote.rs#L462-L471`), a mirror's filesystem error, or the name of a
+   * refusal. `null` exactly when the outcome is a fact (`ok`, `empty`).
+   */
+  readonly detail: string | null;
+  /**
+   * The paths the settling round's probe confirmed present, in whitelist order.
+   * Empty when the round that settled never reached the source — a fact about
+   * that probe, not a claim that the source holds nothing.
+   */
+  readonly present: readonly string[];
+  /**
+   * The whitelist paths the settling round's probe found absent — a *fact* only
+   * when that round reached the source, and the set the round's deletion was
+   * licensed for whether or not the deletion landed. Empty otherwise, where it
+   * claims nothing at all.
+   */
+  readonly absent: readonly string[];
+  /** Probe+transfer rounds this attempt ran: 1, or 2 when a vanished round earned Wake's one re-probe. */
+  readonly rounds: 1 | 2;
+  readonly cache: SyncCacheAction;
+  readonly stamp: SyncStampAction;
+}
+
+// ── Source names ───────────────────────────────────────────────────────────
+
+/** Why a name cannot address a source. Closed, because a refusal is reported. */
+export type HostNameRefusal =
+  | "empty"
+  /** A leading `-` (or any non-alphanumeric head) is an option a transport would execute. */
+  | "leading_non_alphanumeric"
+  /** `:` is the separator in this store's session keys (`source:native-id`, identity.ts). */
+  | "colon"
+  | "invalid_character";
+
+/** Wake's charset (`remote.rs#L194-L200`): ASCII alphanumerics plus `. _ - @`. */
+const HOST_NAME_CHAR = /^[A-Za-z0-9._@-]$/;
+const HOST_NAME_HEAD = /^[A-Za-z0-9]$/;
+
+/** Why a name was refused, in the words a refusal detail carries. */
+const HOST_REFUSAL_TEXT: Record<HostNameRefusal, string> = {
+  empty: "it is empty",
+  leading_non_alphanumeric:
+    "it starts with a non-alphanumeric character, which a transport would read as an option",
+  colon: "':' is the separator in this store's session keys (source:native-id)",
+  invalid_character: "it contains characters outside [A-Za-z0-9._@-]",
+};
+
+/**
+ * Wake's `valid_host_name` (`remote.rs#L194-L200`), decomposed into the reasons
+ * it refuses. The name lands in this store's session keys and in a transport's
+ * argv, so an empty name, a colon, a leading option character, or a character
+ * outside the allowed set is refused before any tool runs — `user@host`,
+ * aliases and IPv4 stay addressable, and an IPv6 literal belongs in the user's
+ * ssh config behind an alias.
+ */
+export function hostNameRefusal(name: string): HostNameRefusal | null {
+  if (name.length === 0) return "empty";
+  if (name.includes(":")) return "colon";
+  if (!HOST_NAME_HEAD.test(name[0]!)) return "leading_non_alphanumeric";
+  for (const char of name) {
+    if (!HOST_NAME_CHAR.test(char)) return "invalid_character";
+  }
+  return null;
+}
+
+// ── Probe ──────────────────────────────────────────────────────────────────
+
+/** What a probe reported, as the driver saw it. */
+export type ProbeReport =
+  | { readonly kind: "spawn_failed"; readonly detail: string }
+  | {
+      readonly kind: "exited";
+      readonly code: number | null;
+      readonly stdout: string;
+      readonly stderr: string;
+    };
+
+/** What a probe means. `reached` is the only state that licenses a claim about content. */
+export type ProbeResult =
+  | { readonly state: "tool_unavailable"; readonly detail: string }
+  | { readonly state: "failed"; readonly detail: string }
+  | {
+      readonly state: "reached";
+      readonly present: readonly string[];
+      readonly absent: readonly string[];
+    };
+
+/**
+ * The paths a probe's stdout confirms, split against the whitelist, in whitelist
+ * order. Only lines equal to a whitelist entry count (`remote.rs#L264-L281`): a
+ * remote rc file's echo, a MOTD, a parent directory, or a child path must never
+ * become a transfer source. Wake's probe prints a whitelist entry once per line,
+ * so the same line twice is still one path.
+ */
+function partitionPaths(stdout: string, paths: readonly string[]): {
+  present: readonly string[];
+  absent: readonly string[];
+} {
+  const lines = new Set<string>();
+  for (const line of stdout.split(/\r?\n/)) lines.add(line.trim());
+  const present: string[] = [];
+  const absent: string[] = [];
+  for (const path of paths) (lines.has(path) ? present : absent).push(path);
+  return { present, absent };
+}
+
+/**
+ * Classify a probe report. Exit 0 is the only accepted outcome — Wake accepts
+ * nothing else for the probe (`remote.rs#L388-L394`) because a non-zero exit
+ * means ssh itself failed (auth, reachability, host key, no remote `sh`), and
+ * its stderr tail is the account a user needs.
+ */
+export function classifyProbe(
+  report: ProbeReport,
+  paths: readonly string[],
+  tool = "ssh",
+): ProbeResult {
+  if (report.kind === "spawn_failed") return { state: "tool_unavailable", detail: report.detail };
+  if (report.code !== 0) {
+    return { state: "failed", detail: exitText(tool, report.code, report.stderr) };
+  }
+  const { present, absent } = partitionPaths(report.stdout, paths);
+  return { state: "reached", present, absent };
+}
+
+// ── Transfer ───────────────────────────────────────────────────────────────
+
+/** What a transfer reported. */
+export type TransferReport =
+  | { readonly kind: "spawn_failed"; readonly detail: string }
+  | { readonly kind: "exited"; readonly code: number | null; readonly stderr: string };
+
+/**
+ * The dialects rsync reports errors in. Data, not branches: a shape this table
+ * does not know is not evidence either way, so a new dialect is one row here
+ * and nothing else changes.
+ */
+export interface RsyncDialect {
+  readonly id: string;
+  /** A line reporting a failed rsync operation. */
+  readonly errorLine: RegExp;
+  /** A line reporting a source the sender could not stat: the vanished shape. */
+  readonly vanishedSource: RegExp;
+  /** Lines that report the transfer's outcome rather than a failure. Never error lines. */
+  readonly summaries: readonly RegExp[];
+}
+
+/**
+ * GNU and openrsync, pinned from Wake's own test fixtures
+ * (`remote.rs#L478-L496`) and its summary-line exclusion (`#L421-L431`). The
+ * GNU summary matters most: without the exclusion, exit 23's own summary line
+ * ("some files/attrs were not transferred (see previous errors)") would read as
+ * an unaccounted error and turn a vanished transfer into a refusal.
+ */
+export const RSYNC_DIALECTS: readonly RsyncDialect[] = [
+  {
+    id: "gnu",
+    // rsync: [sender] link_stat "/home/u/.codex/state_5.sqlite-wal" failed: No such file or directory (2)
+    // rsync: [sender] send_files failed to open "/y": Permission denied (13)
+    errorLine: /^rsync:\s+(?:\[[a-z]+\]\s+)?.*\b(?:failed|error)\b/,
+    vanishedSource: /^rsync:\s+(?:\[[a-z]+\]\s+)?.*\bfailed: No such file or directory(?: \(\d+\))?$/,
+    summaries: [
+      /some files\/attrs were not transferred/,
+      /some files vanished before they could be transferred/,
+    ],
+  },
+  {
+    id: "openrsync",
+    // rsync(63771): error: .codex/state_5.sqlite-wal: (l)stat: No such file or directory
+    errorLine: /^rsync\(\d+\): error:/,
+    vanishedSource: /^rsync\(\d+\): error: .*(?:\(l\)stat|lstat|link_stat|stat): No such file or directory$/,
+    summaries: [],
+  },
+];
+
+/**
+ * How rsync's stderr reads, dialect-resolved:
+ *
+ * - `no_error_lines` — no line is an error this table recognizes. Wake refuses
+ *   to reclassify an evidence-free exit 23 on this shape (`remote.rs#L421-L431`).
+ * - `vanished_only` — at least one error line, every one of them a source that
+ *   is not there.
+ * - `unaccounted` — an error line that is not a vanished source: permission,
+ *   I/O, or anything else the exit code's meaning cannot absorb.
+ */
+export type RsyncStderrShape = "no_error_lines" | "vanished_only" | "unaccounted";
+
+/** Classify every line of a transfer's stderr against {@link RSYNC_DIALECTS}. */
+export function rsyncStderrShape(stderr: string): RsyncStderrShape {
+  let errors = 0;
+  let vanished = 0;
+  for (const line of stderr.split(/\r?\n/)) {
+    if (line.length === 0) continue;
+    if (RSYNC_DIALECTS.some((dialect) => dialect.summaries.some((s) => s.test(line)))) continue;
+    const dialect = RSYNC_DIALECTS.find((d) => d.errorLine.test(line));
+    if (!dialect) continue;
+    errors += 1;
+    if (dialect.vanishedSource.test(line)) vanished += 1;
+  }
+  if (errors === 0) return "no_error_lines";
+  return vanished === errors ? "vanished_only" : "unaccounted";
+}
+
+/** What a transfer means. */
+export type TransferResult =
+  | { readonly state: "tool_unavailable"; readonly detail: string }
+  | { readonly state: "complete" }
+  /**
+   * Sources vanished before the transfer read them. `exitCode` 24 is rsync's own
+   * claim (accepted unless an error line contradicts it); 23 is the generic code
+   * reclassified only on unanimous vanished-source evidence (`remote.rs#L407-L431`).
+   */
+  | { readonly state: "vanished_sources"; readonly exitCode: 23 | 24; readonly detail: string }
+  | { readonly state: "failed"; readonly detail: string };
+
+/**
+ * Classify a transfer report. Exit 0 is complete whatever the stderr says
+ * (warnings are not failures); everything else is resolved against the error
+ * lines, because the exit code alone cannot tell "a source vanished while the
+ * agent wrote it" from "the transfer broke".
+ */
+export function classifyTransfer(report: TransferReport, tool = "rsync"): TransferResult {
+  if (report.kind === "spawn_failed") return { state: "tool_unavailable", detail: report.detail };
+  const { code, stderr } = report;
+  if (code === 0) return { state: "complete" };
+  const shape = rsyncStderrShape(stderr);
+  if (code === 24 && shape !== "unaccounted") {
+    return {
+      state: "vanished_sources",
+      exitCode: 24,
+      detail: `sources vanished before the transfer read them — ${exitText(tool, code, stderr)}`,
+    };
+  }
+  if (code === 23 && shape === "vanished_only") {
+    return {
+      state: "vanished_sources",
+      exitCode: 23,
+      detail: `sources vanished before the transfer read them — ${exitText(tool, code, stderr)}`,
+    };
+  }
+  return { state: "failed", detail: exitText(tool, code, stderr) };
+}
+
+/**
+ * `<tool> exited with N: <stderr tail>` — Wake's `exit_error`
+ * (`remote.rs#L462-L471`): the last three lines, joined, capped at 500
+ * characters because a single runaway line would otherwise become the account.
+ * A process killed by a signal has no exit code and says so.
+ */
+function exitText(tool: string, code: number | null, stderr: string): string {
+  const trimmed = stderr.trim();
+  const tail =
+    trimmed.length === 0
+      ? ""
+      : trimmed.split(/\r?\n/).slice(-STDERR_TAIL_LINES).join("; ");
+  const capped =
+    tail.length <= STDERR_TAIL_CHARS ? tail : Array.from(tail).slice(0, STDERR_TAIL_CHARS).join("");
+  return code === null
+    ? `${tool} terminated by signal: ${capped}`
+    : `${tool} exited with ${code}: ${capped}`;
+}
+
+const STDERR_TAIL_LINES = 3;
+const STDERR_TAIL_CHARS = 500;
+
+// ── The state machine ──────────────────────────────────────────────────────
+
+/**
+ * Where an attempt is. `probe` and `transfer` are Wake's two steps; `purge` is
+ * the deletion of whitelist paths a reached probe found absent, which Wake runs
+ * between them (`remote.rs#L345-L349`); `settled` is terminal.
+ */
+export type SyncStage = "probe" | "purge" | "transfer" | "settled";
+
+/** What the driver does next, in the order given. */
+export type SyncDirective =
+  /** Run the probe for this attempt's whitelist. */
+  | { readonly kind: "probe" }
+  /** Delete these whitelist-relative paths from the mirror. */
+  | { readonly kind: "purge"; readonly paths: readonly string[] }
+  /** Transfer these source-relative paths (always a probe-confirmed subset of the whitelist). */
+  | { readonly kind: "transfer"; readonly paths: readonly string[] };
+
+/** What the driver hands back. */
+export type SyncObservation =
+  | { readonly kind: "probe"; readonly report: ProbeReport }
+  | { readonly kind: "purge"; readonly report: PurgeReport }
+  | { readonly kind: "transfer"; readonly report: TransferReport };
+
+/** A mirror deletion's result: absence is success, a failure is a sync failure. */
+export type PurgeReport =
+  | { readonly state: "removed" }
+  | { readonly state: "failed"; readonly detail: string };
+
+/**
+ * One attempt's whole memory. Nothing else is carried between steps, so a
+ * driver that crashes mid-attempt leaves no state a later attempt can misread.
+ */
+export interface SyncAttempt {
+  readonly source: string;
+  readonly paths: readonly string[];
+  readonly stage: SyncStage;
+  /** 1, or 2 after a vanished round earned Wake's one re-probe (`remote.rs#L355-L359`). */
+  readonly round: 1 | 2;
+  /**
+   * True once any probe in this attempt reached the source, and never unset:
+   * reaching is the only thing that licenses a mirror write, so it stays a fact
+   * of the attempt even after a later round fails to reach again.
+   */
+  readonly reached: boolean;
+  /** The last reached probe's confirmed paths, in whitelist order; empty until one lands. */
+  readonly present: readonly string[];
+  /** The last reached probe's absent paths; empty until one lands. */
+  readonly absent: readonly string[];
+  /**
+   * Every path this attempt's purges actually removed from the mirror: the union
+   * of the absent sets of purges that reported success. A record of deletions
+   * that landed, not of deletions that were licensed — a purge that failed joins
+   * nothing here, and the paths it was licensed to delete stay visible in the
+   * settled outcome's `absent`. It is also not a claim about what the mirror
+   * holds now: a path a later probe finds present again is transferred, not
+   * resurrected.
+   */
+  readonly deleted: readonly string[];
+  /** Set exactly when `stage` is `settled`. */
+  readonly outcome: SyncOutcome | null;
+}
+
+/** What a step produced: the state to carry, and the work to run. */
+export interface SyncAdvance {
+  readonly state: SyncAttempt;
+  readonly directives: readonly SyncDirective[];
+}
+
+/**
+ * Start an attempt. An invalid source name settles immediately — refused,
+ * mirror untouched — because the name would otherwise reach a session key or an
+ * argv; a valid one asks for the probe.
+ */
+export function beginSyncAttempt(source: string, paths: readonly string[]): SyncAdvance {
+  const refusal = hostNameRefusal(source);
+  const attempt: SyncAttempt = {
+    source,
+    paths: [...paths],
+    stage: "probe",
+    round: 1,
+    reached: false,
+    present: [],
+    absent: [],
+    deleted: [],
+    outcome: null,
+  };
+  if (refusal) {
+    return settle(
+      attempt,
+      "refused",
+      "host_name_invalid",
+      `invalid sync source name "${source}": ${HOST_REFUSAL_TEXT[refusal]}`,
+    );
+  }
+  return { state: attempt, directives: [{ kind: "probe" }] };
+}
+
+/**
+ * One transition. The observation must match the stage the attempt is waiting
+ * on; anything else is a driver bug and throws rather than being absorbed into
+ * an outcome the store would then believe.
+ */
+export function advanceSyncAttempt(attempt: SyncAttempt, observation: SyncObservation): SyncAdvance {
+  if (attempt.stage === "settled") {
+    throw new Error(`sync attempt for ${attempt.source} is settled; no observation can move it`);
+  }
+  if (observation.kind !== attempt.stage) {
+    throw new Error(
+      `sync attempt for ${attempt.source} waits on a ${attempt.stage} observation, got ${observation.kind}`,
+    );
+  }
+  switch (observation.kind) {
+    case "probe":
+      return advanceProbe(attempt, observation.report);
+    case "purge":
+      return advancePurge(attempt, observation.report);
+    case "transfer":
+      return advanceTransfer(attempt, observation.report);
+  }
+}
+
+function advanceProbe(attempt: SyncAttempt, report: ProbeReport): SyncAdvance {
+  const result = classifyProbe(report, attempt.paths);
+  if (result.state === "tool_unavailable") {
+    return settle(attempt, "unreachable", "probe_tool_unavailable", result.detail);
+  }
+  if (result.state === "failed") {
+    return settle(attempt, "unreachable", "probe_failed", result.detail);
+  }
+  const reached: SyncAttempt = {
+    ...attempt,
+    reached: true,
+    present: result.present,
+    absent: result.absent,
+  };
+  if (result.absent.length > 0) {
+    return {
+      state: { ...reached, stage: "purge" },
+      directives: [{ kind: "purge", paths: result.absent }],
+    };
+  }
+  if (result.present.length === 0) {
+    return settle(reached, "empty", "source_empty", null);
+  }
+  return {
+    state: { ...reached, stage: "transfer" },
+    directives: [{ kind: "transfer", paths: result.present }],
+  };
+}
+
+function advancePurge(attempt: SyncAttempt, report: PurgeReport): SyncAdvance {
+  if (report.state === "failed") {
+    // The deletion was licensed and did not land. Nothing joins `deleted`; the
+    // paths the probe licensed stay visible in the settled outcome's `absent`,
+    // and the account names the filesystem failure.
+    return settle(attempt, "refused", "mirror_purge_failed", report.detail);
+  }
+  // Only a purge that reported success puts paths into `deleted`, so the record
+  // a driver reads names mirror entries that are really gone.
+  const deleted = [...attempt.deleted];
+  for (const path of attempt.absent) if (!deleted.includes(path)) deleted.push(path);
+  const purged: SyncAttempt = { ...attempt, deleted };
+  if (purged.present.length === 0) {
+    return settle(purged, "empty", "source_empty", null);
+  }
+  return {
+    state: { ...purged, stage: "transfer" },
+    directives: [{ kind: "transfer", paths: purged.present }],
+  };
+}
+
+function advanceTransfer(attempt: SyncAttempt, report: TransferReport): SyncAdvance {
+  const result = classifyTransfer(report);
+  switch (result.state) {
+    case "complete":
+      return settle(attempt, "ok", "transferred", null);
+    case "tool_unavailable":
+      return settle(attempt, "refused", "transfer_tool_unavailable", result.detail);
+    case "vanished_sources":
+      if (result.exitCode === 23 && attempt.round === 1) {
+        // The probe-to-transfer window is a race with a writer on the source; one
+        // re-probe is the whole of Wake's tolerance (`remote.rs#L355-L359`).
+        return {
+          // The round's facts belong to the round: a fresh probe is pending, so
+          // the state carries nothing from the round that vanished. What stays is
+          // what the attempt itself did (`reached`, `deleted`).
+          state: { ...attempt, stage: "probe", round: 2, present: [], absent: [] },
+          directives: [{ kind: "probe" }],
+        };
+      }
+      return settle(attempt, "partial", "sources_vanished", result.detail);
+    case "failed":
+      return settle(attempt, "refused", "transfer_failed", result.detail);
+  }
+}
+
+/**
+ * Settle with the attempt's own facts. The stamp action is derived here, once:
+ * only `ok` and `empty` advance `last_sync_at` (see {@link SyncStampAction}).
+ */
+function settle(
+  attempt: SyncAttempt,
+  kind: SyncOutcomeKind,
+  reason: SyncReason,
+  detail: string | null,
+): SyncAdvance {
+  const outcome: SyncOutcome = {
+    source: attempt.source,
+    kind,
+    reason,
+    detail,
+    present: attempt.present,
+    absent: attempt.absent,
+    rounds: attempt.round,
+    cache: attempt.reached
+      ? { kind: "purge", paths: attempt.deleted }
+      : { kind: "keep-untouched" },
+    stamp: COMPLETE_KINDS[kind] ? { kind: "update-stamp" } : { kind: "record-error" },
+  };
+  return { state: { ...attempt, stage: "settled", outcome }, directives: [] };
+}
+
+// ── The disposable mirror's lifecycle ──────────────────────────────────────
+
+/**
+ * Which mirror directories belong to no configured source, and are therefore
+ * disposable. Wake purges these after every sync round rather than only on the
+ * removal itself (`remote.rs#L202-L222`): a transfer already in flight cannot be
+ * cancelled and would write the removed tree back, so the verdict is re-asserted
+ * until it holds. The rule is name equality against the configured set (Wake's
+ * `known.contains`), so a directory this build's validation would refuse is an
+ * orphan exactly when nothing configured claims it.
+ *
+ * Returns names in code-unit order so two callers — and two rounds — delete the
+ * same set in the same order. The caller owns the mirror root and the deletion;
+ * this function only decides.
+ */
+export function orphanedMirrors(
+  configured: readonly string[],
+  present: readonly string[],
+): readonly string[] {
+  const known = new Set(configured);
+  const orphans = new Set<string>();
+  for (const name of present) if (!known.has(name)) orphans.add(name);
+  return [...orphans].sort();
+}
+
+// ── The stamp: persistence contract ────────────────────────────────────────
+
+/**
+ * One source's sync stamp, as the table would hold it. `last_sync_at` names the
+ * last sync that *completed*; an attempt that did not leaves it alone and puts
+ * its account in `last_sync_error` — which is why the two are validated against
+ * each other below.
+ */
+export interface SyncStampRow {
+  source: string;
+  /** The last complete sync, or null for a source that has never completed one. */
+  last_sync_at: string | null;
+  /** The last attempt's verdict. Never absent: a stamp is written by an attempt. */
+  last_outcome: SyncOutcomeKind;
+  /** The last attempt's account; null exactly when the last attempt completed. */
+  last_sync_error: string | null;
+  /** When the last attempt ran (complete or not) — the staleness floor's own stamp. */
+  updated_at: string;
+}
+
+/**
+ * The stamp table, schema-ready — and deliberately **not** executed by this
+ * cycle.
+ *
+ * The decision, since it is the one this module could plausibly get wrong: C8
+ * ships no transport, so no code path can write a row. Taking a schema version
+ * for a table nothing populates would migrate every store this build touches —
+ * and make every older installed build refuse them (`SCHEMA_MISMATCH`) — for
+ * zero data, would grow PR #52's ladder obligation from "accept 15" to "accept
+ * 15 and 16" on an unaccepted branch, and would freeze a row shape before the
+ * transport that owns it exists. The boring option wins: the contract lands now
+ * (this DDL, {@link SyncStampRow}, {@link readSyncStamps},
+ * {@link stampedSyncRow}, tests), and the cycle that ships the writer adds this
+ * constant to `CREATE_TABLES_SQL`, claims `SCHEMA_VERSION` 16, and enters the
+ * ladder from every live shape (13, 14, 15) the way C7's step did.
+ *
+ * The CHECKs are the contract, not decoration: a row cannot claim a complete
+ * outcome without a stamp or without clearing the error, and cannot record a
+ * failure without an account.
+ */
+export const SYNC_STAMP_DDL = `
+CREATE TABLE IF NOT EXISTS sync_stamps (
+  source          TEXT PRIMARY KEY,
+  last_sync_at    TEXT,
+  last_outcome    TEXT NOT NULL CHECK (last_outcome IN ('ok', 'empty', 'partial', 'unreachable', 'refused')),
+  last_sync_error TEXT,
+  updated_at      TEXT NOT NULL,
+  CHECK (last_outcome IN ('ok', 'empty') OR last_sync_error IS NOT NULL),
+  CHECK (last_outcome NOT IN ('ok', 'empty') OR (last_sync_error IS NULL AND last_sync_at IS NOT NULL))
+);
+`;
+
+const SYNC_STAMP_TABLE = "sync_stamps";
+
+/**
+ * The stamps a store holds, in source order, or `null` when the store has no
+ * stamp table at all.
+ *
+ * `null` is not `[]`. A store that predates the table has *unknown* sync state,
+ * and a surface that renders it as "never synced" — or worse, as clean — would
+ * state a fact the store cannot support. This is the same distinction
+ * `StoreStatus.coverage` draws for a store that predates the coverage table, and
+ * the same guard `TrajectoryDb.getSourceCoverageSummary` uses.
+ */
+export function readSyncStamps(db: Database): SyncStampRow[] | null {
+  const present = db
+    .query<{ name: string }, [string]>(
+      "SELECT name FROM sqlite_master WHERE type = 'table' AND name = ? LIMIT 1;",
+    )
+    .get(SYNC_STAMP_TABLE);
+  if (!present) return null;
+  return db
+    .query<SyncStampRow, []>(
+      `SELECT source, last_sync_at, last_outcome, last_sync_error, updated_at
+       FROM ${SYNC_STAMP_TABLE} ORDER BY source ASC`,
+    )
+    .all();
+}
+
+/**
+ * The row an attempt writes, given the row already there. Pure, and the place
+ * the stamp's two invariants are enforced once: a completing outcome stamps
+ * `last_sync_at` and clears the error; an incomplete one keeps the previous
+ * stamp (the last *complete* sync, even if that is another attempt's) and
+ * records the account. A previous row is only carried forward when it names the
+ * same source.
+ *
+ * An incomplete outcome with no detail is recorded under its reason code rather
+ * than as an empty account — the row never claims a failure it cannot explain.
+ */
+export function stampedSyncRow(
+  previous: SyncStampRow | null,
+  outcome: SyncOutcome,
+  attemptedAt: string,
+): SyncStampRow {
+  const complete = COMPLETE_KINDS[outcome.kind];
+  const carried = previous?.source === outcome.source ? previous.last_sync_at : null;
+  return {
+    source: outcome.source,
+    last_sync_at: complete ? attemptedAt : carried,
+    last_outcome: outcome.kind,
+    last_sync_error: complete ? null : (outcome.detail ?? outcome.reason),
+    updated_at: attemptedAt,
+  };
+}
+
+// ── Coverage honesty ───────────────────────────────────────────────────────
+
+/**
+ * What the mirror that stands beside a stamp may be read as — the claim
+ * ceiling, per source:
+ *
+ * - `current` — the last attempt completed: as of `last_sync_at`, the mirror
+ *   holds what the source held.
+ * - `incomplete` — the last attempt reached the source and transferred a
+ *   subset: the mirror is missing what vanished, and nothing was purged to hide
+ *   it.
+ * - `not-claimed` — no contact, or an attempt this store does not vouch for: the
+ *   mirror may hold anything, and this store says nothing about the source.
+ */
+export type SyncMirrorStanding = "current" | "incomplete" | "not-claimed";
+
+/** One source's disclosure, derived from its stamp and nothing else. */
+export interface SyncSourceDisclosure {
+  readonly source: string;
+  /** The last attempt's verdict, verbatim. */
+  readonly outcome: SyncOutcomeKind;
+  /** The last complete sync; null when no attempt has ever completed for this source. */
+  readonly last_synced_at: string | null;
+  /** The last attempt's account; null when it completed. */
+  readonly error: string | null;
+  readonly last_attempt_at: string;
+  readonly mirror: SyncMirrorStanding;
+}
+
+/**
+ * What a consuming surface discloses about sync state. Deliberately shaped like
+ * the coverage envelope (`coverage: {degraded, total, oldest_updated_at}`), with
+ * the same rule for absence: an unknown is not a zero.
+ *
+ * - `unknown` — the store holds no stamp table: sync state is not knowable here.
+ *   Never render as "clean" and never as "never synced".
+ * - `never_synced` — the table exists and is empty: no attempt has run, which is
+ *   a fact about attempts, not about what the mirror holds.
+ * - `recorded` — one entry per stamped source, the count whose last attempt did
+ *   not complete, and the least-recently-*completed* sync (the staleness floor).
+ */
+export type SyncDisclosure =
+  | { readonly state: "unknown" }
+  | { readonly state: "never_synced" }
+  | {
+      readonly state: "recorded";
+      /** Stamped sources. A source with no stamp is absent, not clean. */
+      readonly total: number;
+      /** Sources whose last attempt did not complete — the `degraded` analog. */
+      readonly incomplete: number;
+      /** The oldest `last_sync_at`; null when nothing has ever completed. */
+      readonly oldest_synced_at: string | null;
+      readonly sources: readonly SyncSourceDisclosure[];
+    };
+
+/** Derive the disclosure from stored stamps (`null` = the store predates the table). */
+export function discloseSyncState(stamps: readonly SyncStampRow[] | null): SyncDisclosure {
+  if (stamps === null) return { state: "unknown" };
+  if (stamps.length === 0) return { state: "never_synced" };
+  const sources = [...stamps]
+    .sort((a, b) => (a.source < b.source ? -1 : a.source > b.source ? 1 : 0))
+    .map<SyncSourceDisclosure>((row) => ({
+      source: row.source,
+      outcome: row.last_outcome,
+      last_synced_at: row.last_sync_at,
+      error: row.last_sync_error,
+      last_attempt_at: row.updated_at,
+      mirror: MIRROR_STANDING[row.last_outcome],
+    }));
+  let oldest: string | null = null;
+  let incomplete = 0;
+  for (const source of sources) {
+    if (source.mirror !== "current") incomplete += 1;
+    if (source.last_synced_at === null) continue;
+    if (oldest === null || source.last_synced_at < oldest) oldest = source.last_synced_at;
+  }
+  return { state: "recorded", total: sources.length, incomplete, oldest_synced_at: oldest, sources };
+}