mirror-mind 0.0.1 → 0.33.0

package/ts/src/backup/zipBackup.ts

@@ -0,0 +1,267 @@
+// Dated zip backup of the memory database — port of `src/memory/cli/backup.py`
+// (CV22.DS7.TS1). This is the archive `repair-encoding --apply` and
+// `repair-journeys --apply` gate on; the front door's own fixed-name pre-write
+// snapshot (`liveBackup.ts`) is a different, weaker property and stays as is.
+//
+// What the archive is (CR061, which replaced the raw copy DS7.TS1 reproduced):
+//   - one member, `memory.db`: a consistent snapshot of the database as
+//     committed at one instant, taken with `VACUUM INTO` from a read-only
+//     connection, switched to WAL so a restore runs as the original did, and
+//     checked with `PRAGMA quick_check` before it is published. The old raw
+//     copy of `memory.db` plus its `-wal`/`-shm` could restore a torn pair,
+//     and its `memory.db` alone lacked every row still in the WAL;
+//   - the snapshot is taken in a private directory under the OS temp dir, never
+//     in the backups directory, which may be a synced folder;
+//   - the zip is staged beside its final name as
+//     `memory_<stamp>.zip.<pid>-<12 hex>.partial` and renamed into place, so a
+//     process killed mid-write never leaves a plausible archive, and two
+//     backups in the same second never write into one file;
+//   - owner-only (CR062): the archive is written 0600 from its first byte, a
+//     directory the backup creates is 0700, and every `memory_*.zip` in the
+//     directory is tightened to 0600. The directory itself keeps its mode:
+//     REFERENCE.md's posture never mutates a pre-existing directory;
+//   - the member is always named `memory.db` whatever the on-disk file is
+//     called (the restore contract reads that name), and its DOS time is the
+//     moment of capture;
+//   - after writing, stranded staging whose process is gone is swept (the
+//     shared rule in `staging.ts`), a pre-CR061 `.zip.partial` is removed as it
+//     always was, and `memory_*.zip` archives older than 30 days by the stamp in
+//     their NAME are deleted (unparseable names are left alone);
+//   - stdout lines, the deprecated `BACKUP_DIR` warning, and `--silent`
+//     printing nothing on success are Python's. `--silent` no longer hides
+//     failure: the CLI exits 1 with one line when no archive was written
+//     (CR060, `dbSafetyToolsRoute.ts`).
+
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { prepareArchiveSnapshot, snapshotDatabaseTo } from "#db/database.ts";
+import { stagingToken, sweepAbandoned } from "./staging.ts";
+import { writeZipArchive, type ZipEntryInput } from "./zipWriter.ts";
+
+export const RETENTION_DAYS = 30;
+const ARCHIVE_MEMBER = "memory.db";
+/** What Mirror calls an archive; the retention sweep and the tightening both read it. */
+const ARCHIVE_NAME = /^memory_.*\.zip$/;
+/** A zip staged beside its final name: `<archive>.<pid>-<12 hex>.partial`. */
+const ZIP_STAGING = /^memory_\d{8}_\d{6}\.zip\.(\d+)-[0-9a-f]{12}\.partial$/;
+/** A zip staged before CR061 carried no process id, and is swept as it always was. */
+const LEGACY_ZIP_STAGING = /^memory_.*\.zip\.partial$/;
+/** A snapshot's private directory under the temp dir: `mirror-backup-<pid>-XXXXXX`. */
+const SNAPSHOT_DIR_PREFIX = "mirror-backup-";
+const SNAPSHOT_DIR = /^mirror-backup-(\d+)-[A-Za-z0-9]{6}$/;
+const BACKUP_DIR_NAME = "backups";
+
+export const DEPRECATED_BACKUP_DIR_WARNING =
+  "warning: BACKUP_DIR is deprecated and no longer redirects backups. " +
+  "Backups are written under <mirror_home>/backups. " +
+  "Use --backup-dir <path> to choose a destination.";
+
+export interface ZipBackupOptions {
+  /** The database file to archive. Resolved by the caller (mirror home, env, `--db-path`). */
+  dbPath: string;
+  /** Printed as `Mirror home:` when given; `null` reproduces Python's `mirror_home=None` output. */
+  mirrorHome: string | null;
+  /** Explicit destination; `null` means `<dirname(dbPath)>/backups`. */
+  backupDir: string | null;
+  silent?: boolean;
+  /** Process environment view, for the deprecated `BACKUP_DIR` warning. */
+  env?: Readonly<Record<string, string | undefined>>;
+  now?: () => Date;
+  /** Where the snapshot's private directory is made; the OS temp dir by default. */
+  tempDir?: string;
+  stdout?: (line: string) => void;
+  stderr?: (line: string) => void;
+}
+
+/** Python `f"{size / 1024:.0f}"`: round half to even, no decimals. */
+export function formatKilobytes(sizeBytes: number): string {
+  const kb = sizeBytes / 1024;
+  const floor = Math.floor(kb);
+  const fraction = kb - floor;
+  if (fraction > 0.5) return String(floor + 1);
+  if (fraction < 0.5) return String(floor);
+  return String(floor % 2 === 0 ? floor : floor + 1);
+}
+
+function pad(value: number, width = 2): string {
+  return String(value).padStart(width, "0");
+}
+
+/** `datetime.now().strftime("%Y%m%d_%H%M%S")` in local time. */
+export function archiveStamp(now: Date): string {
+  return (
+    `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}_` +
+    `${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`
+  );
+}
+
+/** Parse `memory_YYYYMMDD_HHMMSS.zip` back into a local-time Date, or null. */
+export function parseArchiveStamp(fileName: string): Date | null {
+  const match = /^memory_(\d{4})(\d{2})(\d{2})_(\d{2})(\d{2})(\d{2})\.zip$/.exec(fileName);
+  if (!match) return null;
+  const [year, month, day, hour, minute, second] = match.slice(1).map(Number) as number[];
+  const date = new Date(year as number, (month as number) - 1, day, hour, minute, second);
+  // strptime rejects impossible dates; so do we, by round-tripping.
+  return archiveStamp(date) === fileName.slice("memory_".length, -".zip".length) ? date : null;
+}
+
+/** The snapshot could not be taken, or failed its check: nothing is published. */
+export class BackupSnapshotError extends Error {
+  constructor(detail: string) {
+    super(`could not snapshot the database: ${detail}`);
+    this.name = "BackupSnapshotError";
+  }
+}
+
+/**
+ * The archive's one member: a snapshot of the database as committed, taken in
+ * a private directory under `tempDir` and removed whatever happens. The file is
+ * created empty with mode 0600 before `VACUUM INTO` writes into it, so the copy
+ * is owner-only from its first byte, and the member carries that mode, which is
+ * the mode `unzip` restores it with.
+ */
+export function snapshotEntry(dbPath: string, tempDir: string, capturedAt: Date): ZipEntryInput {
+  const dir = mkdtempSync(join(tempDir, `${SNAPSHOT_DIR_PREFIX}${process.pid}-`));
+  try {
+    const path = join(dir, ARCHIVE_MEMBER);
+    writeFileSync(path, "", { mode: 0o600, flag: "wx" });
+    try {
+      snapshotDatabaseTo(dbPath, path);
+    } catch (error) {
+      throw new BackupSnapshotError(error instanceof Error ? error.message : String(error));
+    }
+    const check = prepareArchiveSnapshot(path);
+    if (!check.ok) throw new BackupSnapshotError(`quick_check: ${check.verdict}`);
+    return {
+      name: ARCHIVE_MEMBER,
+      data: readFileSync(path),
+      mtime: capturedAt,
+      mode: statSync(path).mode,
+    };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Write an archive through a staging file unique to this process and owner-only
+ * from its first byte (CR062), then rename it into place. A process killed
+ * mid-write never leaves a plausible archive, two writers never share a file,
+ * and a failure removes the staging file before it propagates.
+ */
+export function publishArchive(archivePath: string, bytes: Uint8Array): void {
+  const stagingPath = `${archivePath}.${stagingToken()}.partial`;
+  try {
+    writeFileSync(stagingPath, bytes, { mode: 0o600 });
+    renameSync(stagingPath, archivePath);
+  } catch (error) {
+    rmSync(stagingPath, { force: true });
+    throw error;
+  }
+}
+
+/**
+ * CR062, decision D2a: every archive Mirror named in this directory becomes
+ * owner-only, including those written before this CR. The directory keeps its
+ * mode: REFERENCE.md's posture never mutates a pre-existing directory, and on
+ * the Navigator's install this one is a Dropbox folder. Best-effort: an
+ * archive that cannot be tightened is not this backup's failure.
+ */
+function tightenArchives(backupDir: string): void {
+  for (const name of readdirSync(backupDir)) {
+    if (!ARCHIVE_NAME.test(name)) continue;
+    try {
+      chmodSync(join(backupDir, name), 0o600);
+    } catch {
+      // Left as it is; `runtime diagnose` reports loose permissions.
+    }
+  }
+}
+
+/** Staging left behind: pre-CR061 partials as always, the rest only when their writer is gone. */
+function sweepStaging(backupDir: string, tempDir: string): void {
+  for (const name of readdirSync(backupDir)) {
+    if (!LEGACY_ZIP_STAGING.test(name)) continue;
+    try {
+      rmSync(join(backupDir, name));
+    } catch {
+      // A stranded file we cannot remove is not this run's failure.
+    }
+  }
+  sweepAbandoned(backupDir, ZIP_STAGING);
+  sweepAbandoned(tempDir, SNAPSHOT_DIR);
+}
+
+function sweepRetention(backupDir: string, keep: string, now: Date): number {
+  const cutoff = new Date(now.getTime() - RETENTION_DAYS * 24 * 60 * 60 * 1000);
+  let removed = 0;
+  for (const name of readdirSync(backupDir)) {
+    if (name === keep || !ARCHIVE_NAME.test(name)) continue;
+    const stamp = parseArchiveStamp(name);
+    if (stamp === null || stamp.getTime() >= cutoff.getTime()) continue;
+    try {
+      rmSync(join(backupDir, name));
+      removed += 1;
+    } catch {
+      // Same tolerance as the oracle's `except (ValueError, OSError): continue`.
+    }
+  }
+  return removed;
+}
+
+/**
+ * Create the dated archive and sweep old ones. Returns the archive path, or
+ * `null` when the database does not exist (already reported on stdout unless
+ * silent). Exit-code semantics belong to the CLI, as in Python.
+ */
+export function createZipBackup(options: ZipBackupOptions): string | null {
+  const silent = options.silent ?? false;
+  const now = options.now ?? (() => new Date());
+  const env = options.env ?? process.env;
+  const out = options.stdout ?? ((line: string) => process.stdout.write(`${line}\n`));
+  const err = options.stderr ?? ((line: string) => process.stderr.write(`${line}\n`));
+
+  if (options.backupDir === null && env.BACKUP_DIR) err(DEPRECATED_BACKUP_DIR_WARNING);
+  const backupDir = options.backupDir ?? join(dirname(options.dbPath), BACKUP_DIR_NAME);
+
+  if (!silent) {
+    if (options.mirrorHome !== null) out(`Mirror home: ${options.mirrorHome}`);
+    out(`Database: ${options.dbPath}`);
+    out(`Backup dir: ${backupDir}`);
+  }
+  if (!existsSync(options.dbPath)) {
+    if (!silent) out(`Database not found: ${options.dbPath}`);
+    return null;
+  }
+
+  mkdirSync(backupDir, { recursive: true, mode: 0o700 });
+  const capturedAt = now();
+  const archiveName = `memory_${archiveStamp(capturedAt)}.zip`;
+  const archivePath = join(backupDir, archiveName);
+  const tempDir = options.tempDir ?? tmpdir();
+  const member = snapshotEntry(options.dbPath, tempDir, capturedAt);
+  publishArchive(archivePath, writeZipArchive([member]));
+
+  if (!silent)
+    out(`Backup created: ${archiveName} (${formatKilobytes(statSync(archivePath).size)} KB)`);
+
+  sweepStaging(backupDir, tempDir);
+  const removed = sweepRetention(backupDir, archiveName, now());
+  tightenArchives(backupDir);
+  if (!silent && removed > 0)
+    out(`Removed ${removed} backup(s) older than ${RETENTION_DAYS} days.`);
+
+  return archivePath;
+}

package/ts/src/backup/zipReader.ts

@@ -0,0 +1,109 @@
+// The read half of `ts/src/backup/zipWriter.ts` (CV22.DS10.US2).
+//
+// Node ships a zip WRITER's primitives (`deflateRawSync`, `crc32`) but no
+// reader, and `runtime backup --verify` has to open archives written by three
+// different producers: this repository's writer (deflate-raw), Python's
+// `zipfile` in the shipped backup path (deflate), and Python's `zipfile`
+// defaults in any hand-made archive (STORED). Both methods are supported for
+// that reason, not for generality.
+//
+// Scope is deliberately small: list the central directory, and extract one
+// named entry. No streaming, no zip64, no encryption, no directory creation --
+// this module never writes to the filesystem, which is also why zip-slip is not
+// ITS problem: the caller refuses unsafe names (see `runtime/backup.ts`), and
+// nothing here ever turns an entry name into a path.
+
+import { inflateRawSync } from "node:zlib";
+
+const EOCD_SIGNATURE = 0x06054b50;
+const CENTRAL_SIGNATURE = 0x02014b50;
+const LOCAL_SIGNATURE = 0x04034b50;
+const EOCD_MIN_SIZE = 22;
+/** The comment field is 16 bits, so the EOCD starts at most this far from the end. */
+const EOCD_MAX_SCAN = EOCD_MIN_SIZE + 0xffff;
+
+const METHOD_STORED = 0;
+const METHOD_DEFLATED = 8;
+
+export class NotAReadableZipError extends Error {}
+
+export interface ZipDirectoryEntry {
+  name: string;
+  method: number;
+  compressedSize: number;
+  uncompressedSize: number;
+  localHeaderOffset: number;
+}
+
+function findEndOfCentralDirectory(buffer: Buffer): number {
+  const earliest = Math.max(0, buffer.length - EOCD_MAX_SCAN);
+  for (let offset = buffer.length - EOCD_MIN_SIZE; offset >= earliest; offset -= 1) {
+    if (buffer.readUInt32LE(offset) === EOCD_SIGNATURE) return offset;
+  }
+  throw new NotAReadableZipError("end of central directory not found");
+}
+
+/** The archive's central directory, in the order the archive lists it. */
+export function readZipDirectory(buffer: Buffer): ZipDirectoryEntry[] {
+  if (buffer.length < EOCD_MIN_SIZE) throw new NotAReadableZipError("file is too small for a zip");
+  const eocd = findEndOfCentralDirectory(buffer);
+  const count = buffer.readUInt16LE(eocd + 10);
+  let offset = buffer.readUInt32LE(eocd + 16);
+
+  const entries: ZipDirectoryEntry[] = [];
+  for (let index = 0; index < count; index += 1) {
+    if (offset + 46 > buffer.length) throw new NotAReadableZipError("central directory truncated");
+    if (buffer.readUInt32LE(offset) !== CENTRAL_SIGNATURE) {
+      throw new NotAReadableZipError("central directory header not found");
+    }
+    const nameLength = buffer.readUInt16LE(offset + 28);
+    const extraLength = buffer.readUInt16LE(offset + 30);
+    const commentLength = buffer.readUInt16LE(offset + 32);
+    entries.push({
+      // Zip stores names as bytes; `zipfile` writes UTF-8 when the flag is set
+      // and cp437 otherwise. Mirror's own entries are ASCII either way.
+      name: buffer.toString("utf8", offset + 46, offset + 46 + nameLength),
+      method: buffer.readUInt16LE(offset + 10),
+      compressedSize: buffer.readUInt32LE(offset + 20),
+      uncompressedSize: buffer.readUInt32LE(offset + 24),
+      localHeaderOffset: buffer.readUInt32LE(offset + 42),
+    });
+    offset += 46 + nameLength + extraLength + commentLength;
+  }
+  return entries;
+}
+
+/** Every entry name, sorted — the oracle's `sorted(zf.namelist())`. */
+export function readZipEntryNames(buffer: Buffer): string[] {
+  return readZipDirectory(buffer)
+    .map((entry) => entry.name)
+    .sort();
+}
+
+/** The bytes of one named entry, or null when the archive does not hold it. */
+export function readZipEntry(buffer: Buffer, name: string): Buffer | null {
+  const entry = readZipDirectory(buffer).find((candidate) => candidate.name === name);
+  if (entry === undefined) return null;
+
+  const header = entry.localHeaderOffset;
+  if (header + 30 > buffer.length) throw new NotAReadableZipError("local header truncated");
+  if (buffer.readUInt32LE(header) !== LOCAL_SIGNATURE) {
+    throw new NotAReadableZipError("local header not found");
+  }
+  // The local header's own name/extra lengths are authoritative for the data
+  // offset: `zipfile` pads extra fields differently from the central copy.
+  const nameLength = buffer.readUInt16LE(header + 26);
+  const extraLength = buffer.readUInt16LE(header + 28);
+  const start = header + 30 + nameLength + extraLength;
+  const data = buffer.subarray(start, start + entry.compressedSize);
+
+  if (entry.method === METHOD_STORED) return Buffer.from(data);
+  if (entry.method === METHOD_DEFLATED) {
+    try {
+      return inflateRawSync(data);
+    } catch (error) {
+      throw new NotAReadableZipError(`entry '${name}' could not be inflated: ${String(error)}`);
+    }
+  }
+  throw new NotAReadableZipError(`entry '${name}' uses unsupported compression ${entry.method}`);
+}

package/ts/src/backup/zipWriter.ts

@@ -0,0 +1,148 @@
+// Minimal ZIP writer for the dated database backup (CV22.DS7.TS1).
+//
+// Mirrors what Python's `zipfile.ZipFile(..., ZIP_DEFLATED).write(path, name)`
+// produces for a small set of whole files: one deflate-raw local header per
+// member (no data descriptor — sizes are known before the header is written),
+// a central directory, and the end-of-central-directory record. DOS mtimes
+// come from each file's stat in LOCAL time, as zipfile does.
+//
+// Deliberately not implemented: ZIP64 (refused above 4 GiB with a clear error;
+// Python would switch formats silently), encryption, comments, streaming.
+// Members are compressed in memory — fine for a database of tens of MB, which
+// is what this backs up; a streaming writer is the change to make if that
+// stops being true.
+
+import { statSync } from "node:fs";
+import { crc32, deflateRawSync } from "node:zlib";
+
+export interface ZipEntryInput {
+  /** Member name inside the archive (ASCII; `memory.db`, `memory.db-wal`, ...). */
+  name: string;
+  data: Uint8Array;
+  /** Modification time stored as DOS date/time in local time. */
+  mtime: Date;
+  /** POSIX mode bits, stored in the external attributes like zipfile does. */
+  mode: number;
+}
+
+const LOCAL_SIG = 0x04034b50;
+const CENTRAL_SIG = 0x02014b50;
+const EOCD_SIG = 0x06054b50;
+const VERSION_NEEDED = 20;
+const METHOD_DEFLATE = 8;
+const UINT32_MAX = 0xffffffff;
+const UINT16_MAX = 0xffff;
+
+// `version made by`: high byte is the host system (3 = Unix, 0 = MS-DOS/
+// Windows), low byte the zip spec version — the same pair zipfile records.
+const CREATE_SYSTEM = process.platform === "win32" ? 0 : 3;
+
+export class Zip64RequiredError extends Error {
+  constructor(detail: string) {
+    super(`archive needs ZIP64, which this writer does not implement: ${detail}`);
+    this.name = "Zip64RequiredError";
+  }
+}
+
+/** DOS date/time pair for a local-time instant; years before 1980 clamp to 1980. */
+export function dosDateTime(date: Date): { time: number; date: number } {
+  const year = Math.max(date.getFullYear(), 1980);
+  return {
+    time: (date.getHours() << 11) | (date.getMinutes() << 5) | (date.getSeconds() >> 1),
+    date: ((year - 1980) << 9) | ((date.getMonth() + 1) << 5) | date.getDate(),
+  };
+}
+
+/** Read a whole file as a member input, stat-derived mtime and mode included. */
+export function entryFromFile(path: string, name: string, data: Uint8Array): ZipEntryInput {
+  const stat = statSync(path);
+  return { name, data, mtime: stat.mtime, mode: stat.mode };
+}
+
+interface WrittenEntry {
+  input: ZipEntryInput;
+  crc: number;
+  compressed: Buffer;
+  localOffset: number;
+  dos: { time: number; date: number };
+}
+
+function assertFits(value: number, what: string): void {
+  if (value > UINT32_MAX) throw new Zip64RequiredError(`${what} exceeds 4 GiB`);
+}
+
+/** Build the complete archive bytes for `entries`, in the given order. */
+export function writeZipArchive(entries: readonly ZipEntryInput[]): Buffer {
+  if (entries.length > UINT16_MAX) throw new Zip64RequiredError("more than 65535 members");
+
+  const parts: Buffer[] = [];
+  const written: WrittenEntry[] = [];
+  let offset = 0;
+
+  for (const input of entries) {
+    assertFits(input.data.byteLength, `${input.name} uncompressed size`);
+    const compressed = deflateRawSync(input.data);
+    assertFits(compressed.byteLength, `${input.name} compressed size`);
+    assertFits(offset, "archive offset");
+    const name = Buffer.from(input.name, "utf8");
+    const dos = dosDateTime(input.mtime);
+    const crc = crc32(input.data);
+
+    const header = Buffer.alloc(30);
+    header.writeUInt32LE(LOCAL_SIG, 0);
+    header.writeUInt16LE(VERSION_NEEDED, 4);
+    header.writeUInt16LE(0, 6); // flags: no data descriptor, no UTF-8 bit (ASCII names)
+    header.writeUInt16LE(METHOD_DEFLATE, 8);
+    header.writeUInt16LE(dos.time, 10);
+    header.writeUInt16LE(dos.date, 12);
+    header.writeUInt32LE(crc, 14);
+    header.writeUInt32LE(compressed.byteLength, 18);
+    header.writeUInt32LE(input.data.byteLength, 22);
+    header.writeUInt16LE(name.byteLength, 26);
+    header.writeUInt16LE(0, 28);
+
+    written.push({ input, crc, compressed, localOffset: offset, dos });
+    parts.push(header, name, compressed);
+    offset += header.byteLength + name.byteLength + compressed.byteLength;
+  }
+
+  const centralStart = offset;
+  for (const entry of written) {
+    const name = Buffer.from(entry.input.name, "utf8");
+    const header = Buffer.alloc(46);
+    header.writeUInt32LE(CENTRAL_SIG, 0);
+    header.writeUInt16LE((CREATE_SYSTEM << 8) | VERSION_NEEDED, 4);
+    header.writeUInt16LE(VERSION_NEEDED, 6);
+    header.writeUInt16LE(0, 8);
+    header.writeUInt16LE(METHOD_DEFLATE, 10);
+    header.writeUInt16LE(entry.dos.time, 12);
+    header.writeUInt16LE(entry.dos.date, 14);
+    header.writeUInt32LE(entry.crc, 16);
+    header.writeUInt32LE(entry.compressed.byteLength, 20);
+    header.writeUInt32LE(entry.input.data.byteLength, 24);
+    header.writeUInt16LE(name.byteLength, 28);
+    header.writeUInt16LE(0, 30); // extra
+    header.writeUInt16LE(0, 32); // comment
+    header.writeUInt16LE(0, 34); // disk number start
+    header.writeUInt16LE(0, 36); // internal attributes
+    header.writeUInt32LE(((entry.input.mode & 0xffff) << 16) >>> 0, 38);
+    header.writeUInt32LE(entry.localOffset, 42);
+    parts.push(header, name);
+    offset += header.byteLength + name.byteLength;
+  }
+  const centralSize = offset - centralStart;
+  assertFits(centralStart, "central directory offset");
+
+  const eocd = Buffer.alloc(22);
+  eocd.writeUInt32LE(EOCD_SIG, 0);
+  eocd.writeUInt16LE(0, 4);
+  eocd.writeUInt16LE(0, 6);
+  eocd.writeUInt16LE(written.length, 8);
+  eocd.writeUInt16LE(written.length, 10);
+  eocd.writeUInt32LE(centralSize, 12);
+  eocd.writeUInt32LE(centralStart, 16);
+  eocd.writeUInt16LE(0, 20);
+  parts.push(eocd);
+
+  return Buffer.concat(parts);
+}

package/ts/src/builder/activeCheckpoint.ts

@@ -0,0 +1,134 @@
+// CR067 with CR020 — the journey's active checkpoint, shown again without changing it.
+//
+// A checkpoint surface is printed once, by the command that advances the cursor, and the
+// cursor keeps position only, never a checkpoint's evidence. So a lost surface cannot be
+// replayed from it; the Navigator chose not to store emissions (option A). This surface
+// shows where the cursor stands and where the full record lives: the story package's
+// Plan-stage artifacts, each with its state, and its closure records, each marked
+// present or missing. The package path is printed once, because record paths are
+// longer than a card line.
+//
+// CR112: `index.md`, `plan.md`, and `test-guide.md` are written as scaffolds and then
+// authored, and present-or-missing said nothing about which. Each now carries its
+// state -- missing, scaffold, partly authored, authored -- and, while not authored,
+// the sections still to write, by their exact heading text. The glyph carries only
+// done or not; the word carries the state. Closure records keep present or missing:
+// their truth is the seal. The story files' lines come from `artifacts/storyFiles.ts`,
+// which the Plan checkpoint prints too (CR111).
+//
+// CR114: it prints the steps the cursor accepts next, the list the Builder resume
+// prints, from the same selector, so the two cannot disagree. With no cursor it says
+// so, and offers the sync the resume offers, where it gave a Pull command Pull refuses.
+// CR115: before the steps, the cadence they will run at, as the resume prints it.
+
+import type { ArtifactVerdict } from "./artifacts/scaffoldState.ts";
+import { storyFileLines } from "./artifacts/storyFiles.ts";
+import { cadenceCardLines } from "./cadence.ts";
+import { cardPrefixed, cardText, cardWrapped } from "./card.ts";
+import { allowedNextActions, lifecycleStageOf } from "./cursorPosition.ts";
+import type { BuilderDeliveryCursor } from "./deliveryCursor.ts";
+import { renderLifecycleRibbon } from "./lifecycleRibbon.ts";
+import { NO_ITEM_PULLED_YET, pullExplicitly } from "./scopePhrases.ts";
+import { wrapAriadSurface } from "./surfaceProtocol.ts";
+
+const FRAME_TOP = "╭────────────────────────────────────────────────────────╮";
+const FRAME_BOTTOM = "╰────────────────────────────────────────────────────────╯";
+const FRAME_BLANK = "│                                                        │";
+
+/** A story package's closure records, in lifecycle order. */
+export const CLOSURE_RECORDS = ["validation.md", "review.md", "coherence.md", "done.md"] as const;
+
+export interface StoryRecords {
+  /** The package directory, as the Navigator sees it (project-relative when inside). */
+  readonly folder: string;
+  /** The Plan-stage artifacts, judged, in `PLAN_STAGE_ARTIFACTS` order (`judgeStoryFiles`). */
+  readonly artifacts: readonly ArtifactVerdict[];
+  /** The names in `CLOSURE_RECORDS` that exist on disk. */
+  readonly present: ReadonlySet<string>;
+}
+
+export interface ActiveCheckpointView {
+  readonly journey: string;
+  readonly cursor: BuilderDeliveryCursor | null;
+  /** `null` when no story package can be resolved for the cursor. */
+  readonly records: StoryRecords | null;
+}
+
+function recordLines(records: StoryRecords | null): string[] {
+  if (records === null) return [cardText("no story package found")];
+  return [
+    ...cardWrapped(records.folder),
+    ...records.artifacts.flatMap(storyFileLines),
+    ...CLOSURE_RECORDS.map((name) => cardText(`${records.present.has(name) ? "✓" : "○"} ${name}`)),
+  ];
+}
+
+/** What a journey whose delivery cursor was never synced holds. */
+const NO_DELIVERY_CURSOR_YET = "no delivery cursor yet";
+
+/**
+ * The cadence the steps run at (CR115), then the steps the cursor accepts next: what
+ * the Builder resume prints, in its order (CR114).
+ */
+function nextActionLines(cursor: BuilderDeliveryCursor | null): string[] {
+  return [
+    FRAME_BLANK,
+    ...cadenceCardLines(cursor),
+    FRAME_BLANK,
+    cardText("allowed next actions"),
+    ...cardPrefixed(allowedNextActions(cursor), "-"),
+  ];
+}
+
+function positionLines(view: ActiveCheckpointView): string[] {
+  const cursor = view.cursor;
+  if (cursor === null) {
+    return [cardText("active item"), cardText(NO_DELIVERY_CURSOR_YET), ...nextActionLines(null)];
+  }
+  if (!cursor.activeItem) {
+    return [
+      cardText("active item"),
+      cardText(NO_ITEM_PULLED_YET),
+      ...cardWrapped(pullExplicitly(view.journey)),
+      ...nextActionLines(cursor),
+    ];
+  }
+  const item = cursor.activeItemTitle
+    ? `${cursor.activeItem} — ${cursor.activeItemTitle}`
+    : cursor.activeItem;
+  return [
+    cardText("active item"),
+    ...cardWrapped(item),
+    FRAME_BLANK,
+    cardText("last event"),
+    cardText(cursor.lastDeliveryEvent ?? "none"),
+    FRAME_BLANK,
+    cardText("pending confirmation"),
+    cardText(cursor.pendingConfirmation ?? "none"),
+    FRAME_BLANK,
+    cardText("active checkpoint"),
+    cardText(cursor.activeCheckpoint ?? "none"),
+    ...nextActionLines(cursor),
+    FRAME_BLANK,
+    cardText("records"),
+    ...recordLines(view.records),
+  ];
+}
+
+export function renderActiveCheckpoint(view: ActiveCheckpointView): string {
+  const stage = view.cursor === null ? null : lifecycleStageOf(view.cursor);
+  const body = [
+    "Delivery",
+    ...(stage === null ? [] : [renderLifecycleRibbon(stage, view.cursor?.activeItemLevel ?? null)]),
+    "",
+    FRAME_TOP,
+    cardText("       ■  ACTIVE CHECKPOINT"),
+    FRAME_BLANK,
+    ...positionLines(view),
+    FRAME_BLANK,
+    cardText("boundary"),
+    ...cardWrapped("Read-only: the cursor and the project files were not changed."),
+    FRAME_BOTTOM,
+  ].join("\n");
+  return wrapAriadSurface("active_checkpoint", `${body}\n`);
+}