@crewhaus/tool-lifecycle 0.7.0

package/dist/lib/migrate.js

@@ -0,0 +1,264 @@
+/**
+ * `StoreMigrate`'s half: what a harness's store version IS, what the
+ * migration path actually carries, and what it leaves behind.
+ *
+ * The copy itself is `@crewhaus/harness-lifecycle`'s `runRetentionExport` —
+ * the same enumerate-and-copy code the retention export verb uses, which
+ * copies session and audit files VERBATIM (an audit day file has to keep its
+ * exact bytes or the hash chain over it stops verifying). Nothing about
+ * selection or copying is re-implemented here.
+ *
+ * What is here is the part that makes a migration honest rather than a hope:
+ *
+ *   - THE STORE VERSION. Read, reported, and never quietly changed. This
+ *     build can move a store; it cannot rewrite records into a new shape,
+ *     because the memory-entry 1→2 transform lives in `apps/cli`
+ *     (`migrateMemories`) and reaching it needs packages this one does not
+ *     depend on. A version-changing migration is REFUSED by name instead of
+ *     being silently performed as a copy, which would leave a caller
+ *     believing their store was upgraded.
+ *   - WHAT IS NOT CARRIED. The export path covers `.crewhaus/sessions` and
+ *     `.crewhaus/audit`. Memories, prompts, graders, the registry and the
+ *     policy files are NOT part of it. A migration that reports success while
+ *     leaving them behind is exactly the half-migration that puts a store in
+ *     neither shape, so everything under `.crewhaus` that the copy does not
+ *     carry is enumerated and returned.
+ *   - THE RECEIPT. Every file that was copied, with its sha256, written to
+ *     the destination. A re-run reads it back, so "already migrated" and
+ *     "migrated just now" are distinguishable, and an interrupted run can be
+ *     resumed by running it again.
+ */
+import { lstatSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import * as path from "node:path";
+import { fail, renderPath } from "./result";
+/**
+ * The two directories under `.crewhaus` that ARE the harness's record store:
+ * the pair `runRetentionExport` carries, and the same pair
+ * `openHarnessRecordStore` enumerates and a sweep deletes from. Mirrored here
+ * because `@crewhaus/harness-lifecycle` keeps the relpaths private.
+ */
+export const COVERED_STORE_DIRS = ["sessions", "audit"];
+export const RECEIPT_FILENAME = "store-migration.json";
+/**
+ * The file `runRetentionExport` writes into its output directory on every
+ * REAL run, on top of the copies themselves.
+ *
+ * Mirrored here (the package does not export the name) because it is a
+ * destination this tool writes but does not copy: leaving it out of the
+ * written set made the conflict check miss it, so a destination that already
+ * held a `manifest.json` — a previous `crewhaus retention export`, say — had
+ * it overwritten without `overwrite` being asked for and without the preview
+ * ever naming it. `index.test.ts` pins the coupling: a real migration must
+ * produce this file at this name.
+ */
+export const EXPORT_MANIFEST_FILENAME = "manifest.json";
+export const RECORD_SHAPE_MIGRATION_UNAVAILABLE = "a version-changing migration rewrites every record, and the record transforms live in apps/cli " +
+    "(migrateMemories, over @crewhaus/memory-store + @crewhaus/migration-engine) which " +
+    "@crewhaus/tool-lifecycle does not depend on. This tool moves a store between roots at the " +
+    "version it already has; it will not claim to have upgraded one.";
+/**
+ * Read `<harnessDir>/.crewhaus/meta.json`, the file `crewhaus migrate
+ * memories` stamps (`{ memories: { schemaVersion, migratedAt } }`).
+ *
+ * An unreadable or malformed meta file is `unknown`, never version 1: a
+ * migration that guesses the version it is migrating FROM is a migration that
+ * rewrites records twice.
+ */
+export function readStoreVersion(harnessDirAbs) {
+    const metaPath = path.join(harnessDirAbs, ".crewhaus", "meta.json");
+    let raw;
+    try {
+        raw = readFileSync(metaPath, "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return { state: "unstamped" };
+        return {
+            state: "unknown",
+            reason: `.crewhaus/meta.json could not be read (${code ?? "unknown error"})`,
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return {
+            state: "unknown",
+            reason: `.crewhaus/meta.json is not valid JSON (${err.message})`,
+        };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return { state: "unknown", reason: ".crewhaus/meta.json is not a JSON object" };
+    }
+    const memories = parsed["memories"];
+    if (memories === undefined)
+        return { state: "unstamped" };
+    if (typeof memories !== "object" || memories === null || Array.isArray(memories)) {
+        return {
+            state: "unknown",
+            reason: '.crewhaus/meta.json has a "memories" field that is not an object',
+        };
+    }
+    const version = memories["schemaVersion"];
+    if (typeof version !== "number" || !Number.isInteger(version) || version < 1) {
+        return {
+            state: "unknown",
+            reason: `.crewhaus/meta.json has memories.schemaVersion ${JSON.stringify(version)}, which is not a positive integer`,
+        };
+    }
+    return { state: "known", memoriesSchemaVersion: version };
+}
+/**
+ * Everything directly under `.crewhaus` that the export path does not copy.
+ *
+ * Returned so the result can name it. A caller who migrates a store and is
+ * told only "42 sessions, 3 audit days" will believe the memories came too.
+ */
+export function uncoveredStateEntries(harnessDirAbs) {
+    const stateDir = path.join(harnessDirAbs, ".crewhaus");
+    let names;
+    try {
+        names = readdirSync(stateDir).sort();
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return { ok: true, value: [] };
+        return fail("unreadable", `.crewhaus could not be listed (${code ?? "unknown error"})`);
+    }
+    const covered = new Set(COVERED_STORE_DIRS);
+    return {
+        ok: true,
+        value: names
+            .filter((n) => !covered.has(n))
+            .map((n) => ({
+            entry: `.crewhaus/${n}`,
+            reason: "not part of the store export path (@crewhaus/harness-lifecycle carries .crewhaus/sessions and .crewhaus/audit only)",
+        })),
+    };
+}
+/**
+ * What is already at the destination, and whether a previous migration put it
+ * there. A receipt naming a DIFFERENT source is the case that matters: two
+ * harnesses' stores merged into one directory cannot be told apart
+ * afterwards, and the audit chains cannot both be valid.
+ */
+export function inspectDestination(destAbs, plannedRelPaths) {
+    let exists = true;
+    try {
+        if (!statSync(destAbs).isDirectory()) {
+            return fail("not-a-directory", `"${renderPath(destAbs)}" exists and is not a directory`);
+        }
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            exists = false;
+        else
+            return fail("unreadable", `the destination could not be read (${code ?? "unknown error"})`);
+    }
+    const conflicts = [];
+    if (exists) {
+        for (const rel of plannedRelPaths) {
+            try {
+                // lstat, not stat: the question is whether the NAME is taken, not
+                // whether it leads anywhere. `stat` follows a symlink and reports a
+                // DANGLING one as absent — so a link left at a destination path read
+                // as "nothing here", `overwrite` was never asked for, and the copy
+                // went through the link to whatever it pointed at.
+                lstatSync(path.join(destAbs, ...rel.split("/")));
+                conflicts.push(rel);
+            }
+            catch (err) {
+                // ENOENT is the normal case: nothing is there. Anything else means
+                // the entry could not be identified, which is not the same as absent
+                // and still counts as "something is in the way".
+                if (err.code !== "ENOENT")
+                    conflicts.push(rel);
+            }
+        }
+    }
+    const receiptPath = path.join(destAbs, RECEIPT_FILENAME);
+    let receiptRaw;
+    try {
+        receiptRaw = readFileSync(receiptPath, "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT") {
+            return {
+                ok: true,
+                value: {
+                    exists,
+                    conflicts,
+                    receiptProblem: `a ${RECEIPT_FILENAME} is present but could not be read (${code ?? "unknown error"})`,
+                },
+            };
+        }
+    }
+    if (receiptRaw === undefined)
+        return { ok: true, value: { exists, conflicts } };
+    try {
+        const parsed = JSON.parse(receiptRaw);
+        if (typeof parsed?.sourceRoot !== "string") {
+            return {
+                ok: true,
+                value: {
+                    exists,
+                    conflicts,
+                    receiptProblem: `${RECEIPT_FILENAME} does not name a source root`,
+                },
+            };
+        }
+        return { ok: true, value: { exists, conflicts, receipt: parsed } };
+    }
+    catch (err) {
+        return {
+            ok: true,
+            value: {
+                exists,
+                conflicts,
+                receiptProblem: `${RECEIPT_FILENAME} is not valid JSON (${err.message})`,
+            },
+        };
+    }
+}
+/** The destination-relative paths a migration of this selection would write. */
+export function plannedPaths(opts) {
+    const rels = [];
+    for (const id of opts.sessions) {
+        rels.push(`sessions/${id}.json`);
+        if (opts.withEventLog.has(id))
+            rels.push(`sessions/${id}.jsonl`);
+    }
+    for (const day of opts.auditDays)
+        rels.push(`audit/${day}.jsonl`);
+    if (opts.chainTail)
+        rels.push("audit/_chain-tail.json");
+    return rels;
+}
+/**
+ * Every destination-relative path a REAL migration writes: the copies, plus
+ * the export's own `manifest.json` and this tool's receipt.
+ *
+ * Distinct from {@link plannedPaths} on purpose. `plannedPaths` is the set
+ * that is copied from a source and can therefore be hashed on both sides;
+ * this is the set that is WRITTEN, which is what the conflict check and the
+ * containment check have to be asked about. Reporting the first as the second
+ * is how a destination file nobody copied gets destroyed quietly.
+ */
+export function writtenPaths(plannedRelPaths) {
+    return [...plannedRelPaths, EXPORT_MANIFEST_FILENAME, RECEIPT_FILENAME];
+}
+export function writeReceipt(destAbs, receipt) {
+    const p = path.join(destAbs, RECEIPT_FILENAME);
+    try {
+        writeFileSync(p, `${JSON.stringify(receipt, null, 2)}\n`, { mode: 0o600 });
+        return { ok: true, value: p };
+    }
+    catch (err) {
+        return fail("unreadable", `the migration receipt could not be written: ${err.message}`);
+    }
+}

package/dist/lib/result.d.ts

@@ -0,0 +1,72 @@
+import { type SafePath } from "../paths";
+/** Compact JSON — the reader is a model, and every byte is context. */
+export declare const json: (value: unknown) => string;
+/** A caller-supplied path, safe to put in a message: bounded and printable. */
+export declare function renderPath(given: string): string;
+/**
+ * Why something could not be loaded.
+ *
+ * `missing` is the only code a caller may carry on past ("there is no store
+ * here"); every other one is a refusal that must be returned. It is a field
+ * rather than something sniffed out of the message so that rewording a
+ * message can never silently turn a refusal into a carry-on.
+ */
+export type FailCode = "refused" | "missing" | "not-a-directory" | "bad-input" | "unreadable" | "too-large";
+export type Failure = {
+    readonly ok: false;
+    readonly reason: string;
+    readonly code: FailCode;
+};
+export type Loaded<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | Failure;
+export declare function fail(code: FailCode, reason: string): Failure;
+/** The JSON a tool returns when it will not proceed. */
+export declare function refusal(tool: string, code: FailCode, reason: string, extra?: {}): string;
+/**
+ * Resolve a caller-supplied path inside the workspace.
+ *
+ * The NUL guard is here rather than in `paths.ts` (which is a verbatim copy
+ * of `@crewhaus/tool-pkg`'s, deliberately): a NUL truncates a path at the
+ * syscall boundary, so `a\u0000/../../etc` can resolve one way in the
+ * containment check and another way in the `open` that follows. Refused at
+ * the gate instead of surfacing later as "unreadable".
+ */
+export declare function contain(toolName: string, rel: string): Loaded<SafePath>;
+/**
+ * Contain every path an operation will WRITE, not just the directory it was
+ * handed.
+ *
+ * `contain` resolves the ROOT through its symlinks and proves the root sits
+ * inside the workspace. It says nothing about the names BELOW it — and the
+ * writes these tools perform all go to those names: a store export copies to
+ * `<dest>/sessions/<id>.json`, a knowledge push appends to
+ * `<shared>/memories.jsonl`, a pull drops files into
+ * `<harness>/.crewhaus/prompts`. A symlink sitting at one of those names
+ * sends the write to the link's target instead, and a DANGLING one is the
+ * worst case: `stat` reports it absent, so it does not even look like a
+ * conflict, while `open(…, "w")` through it CREATES the target. Validating
+ * the directory and then writing through a link underneath it is exactly the
+ * "validate one spelling, act on another" shape this repository keeps paying
+ * for.
+ *
+ * Each write path therefore goes through the SAME `resolveSafe` the root went
+ * through — symlink-aware, dangling links followed by hand — rather than a
+ * second symlink walker written here. Returns the refusal, or `undefined`
+ * when every write path stays inside the workspace.
+ */
+export declare function containWritePaths(toolName: string, root: SafePath, rels: ReadonlyArray<string>): Failure | undefined;
+/** Resolve a directory that must already exist. */
+export declare function containExistingDir(toolName: string, rel: string): Loaded<SafePath>;
+/** True when `candidate` is `parent` or lives underneath it (both absolute). */
+export declare function isInside(parent: string, candidate: string): boolean;
+/** True when either absolute path contains the other, or they are equal. */
+export declare function overlaps(a: string, b: string): boolean;
+/** Epoch ms → ISO, or `undefined` when there is nothing to render. */
+export declare function iso(ms: number | undefined): string | undefined;
+/** A bounded slice of a list, plus the full count, for a result field. */
+export declare function sample<T>(items: ReadonlyArray<T>, limit?: number): {
+    shown: T[];
+    total: number;
+};

package/dist/lib/result.js

@@ -0,0 +1,139 @@
+/**
+ * The shared answer shapes for this package: how a caller-supplied path is
+ * echoed back, how a directory argument is contained, and how a read that
+ * COULD NOT BE PERFORMED is distinguished from one that found nothing.
+ *
+ * That last distinction is the whole point of the `Loaded` type. Four
+ * irreversible operations sit behind these tools; every one of them decides
+ * what to destroy from something it read first. A read that failed and got
+ * reported as an empty result is how a retention sweep deletes a store it
+ * could not enumerate, so an unreadable directory has its own code and its
+ * own reason here, and never collapses into `[]`.
+ */
+import { statSync } from "node:fs";
+import * as path from "node:path";
+import { ToolPermissionError, resolveSafe } from "../paths";
+/** Compact JSON — the reader is a model, and every byte is context. */
+export const json = (value) => JSON.stringify(value);
+/**
+ * How much of a caller-supplied path is echoed back in a result.
+ *
+ * The message goes into a model's context, so a caller cannot be allowed to
+ * spend that context with a megabyte of path, and cannot be allowed to
+ * smuggle control characters (a NUL, an ANSI escape, a newline that forges a
+ * second line of output) through a string a human or a model then reads.
+ */
+const MAX_ECHOED_PATH_CHARS = 200;
+/** A caller-supplied path, safe to put in a message: bounded and printable. */
+export function renderPath(given) {
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: neutralising control characters is the point
+    const printable = given.replace(/[\u0000-\u001f\u007f]/g, "\uFFFD");
+    return printable.length > MAX_ECHOED_PATH_CHARS
+        ? `${printable.slice(0, MAX_ECHOED_PATH_CHARS)}…`
+        : printable;
+}
+export function fail(code, reason) {
+    return { ok: false, reason, code };
+}
+/** The JSON a tool returns when it will not proceed. */
+export function refusal(tool, code, reason, extra = {}) {
+    return json({ tool, status: "refused", code, reason, ...extra });
+}
+/**
+ * Resolve a caller-supplied path inside the workspace.
+ *
+ * The NUL guard is here rather than in `paths.ts` (which is a verbatim copy
+ * of `@crewhaus/tool-pkg`'s, deliberately): a NUL truncates a path at the
+ * syscall boundary, so `a\u0000/../../etc` can resolve one way in the
+ * containment check and another way in the `open` that follows. Refused at
+ * the gate instead of surfacing later as "unreadable".
+ */
+export function contain(toolName, rel) {
+    if (rel.includes("\u0000")) {
+        return fail("refused", `"${renderPath(rel)}" contains a NUL byte`);
+    }
+    try {
+        return { ok: true, value: resolveSafe(toolName, rel) };
+    }
+    catch (err) {
+        if (err instanceof ToolPermissionError) {
+            // The error's own message carries the path unrendered; rebuild it so a
+            // control character in the caller's input cannot reach the output.
+            return fail("refused", `tool "${toolName}" rejected path "${renderPath(rel)}": resolved location escapes the workspace root`);
+        }
+        throw err;
+    }
+}
+/**
+ * Contain every path an operation will WRITE, not just the directory it was
+ * handed.
+ *
+ * `contain` resolves the ROOT through its symlinks and proves the root sits
+ * inside the workspace. It says nothing about the names BELOW it — and the
+ * writes these tools perform all go to those names: a store export copies to
+ * `<dest>/sessions/<id>.json`, a knowledge push appends to
+ * `<shared>/memories.jsonl`, a pull drops files into
+ * `<harness>/.crewhaus/prompts`. A symlink sitting at one of those names
+ * sends the write to the link's target instead, and a DANGLING one is the
+ * worst case: `stat` reports it absent, so it does not even look like a
+ * conflict, while `open(…, "w")` through it CREATES the target. Validating
+ * the directory and then writing through a link underneath it is exactly the
+ * "validate one spelling, act on another" shape this repository keeps paying
+ * for.
+ *
+ * Each write path therefore goes through the SAME `resolveSafe` the root went
+ * through — symlink-aware, dangling links followed by hand — rather than a
+ * second symlink walker written here. Returns the refusal, or `undefined`
+ * when every write path stays inside the workspace.
+ */
+export function containWritePaths(toolName, root, rels) {
+    const shownRoot = root.rel === "" ? "." : root.rel;
+    for (const rel of rels) {
+        const under = root.rel === "" ? rel : `${root.rel}/${rel}`;
+        if (!contain(toolName, under).ok) {
+            return fail("refused", `"${renderPath(rel)}" under "${renderPath(shownRoot)}" resolves outside the workspace root — a symlink on that path leads out, so the write would land on the link's target rather than inside "${renderPath(shownRoot)}". Remove the link and run again; there is no flag for writing through it.`);
+        }
+    }
+    return undefined;
+}
+/** Resolve a directory that must already exist. */
+export function containExistingDir(toolName, rel) {
+    const safe = contain(toolName, rel);
+    if (!safe.ok)
+        return safe;
+    const shown = renderPath(rel);
+    let stat;
+    try {
+        stat = statSync(safe.value.real);
+    }
+    catch (err) {
+        const code = err.code;
+        // ENOENT is "there is nothing here"; EACCES/ELOOP/anything else is "this
+        // could not be read", which is a different answer and must not be
+        // reported as absence.
+        return code === "ENOENT"
+            ? fail("missing", `"${shown}" does not exist`)
+            : fail("unreadable", `"${shown}" could not be read (${code ?? "unknown error"})`);
+    }
+    if (!stat.isDirectory())
+        return fail("not-a-directory", `"${shown}" is not a directory`);
+    return safe;
+}
+/** True when `candidate` is `parent` or lives underneath it (both absolute). */
+export function isInside(parent, candidate) {
+    const p = path.resolve(parent);
+    const c = path.resolve(candidate);
+    return c === p || c.startsWith(`${p}${path.sep}`);
+}
+/** True when either absolute path contains the other, or they are equal. */
+export function overlaps(a, b) {
+    return isInside(a, b) || isInside(b, a);
+}
+/** Epoch ms → ISO, or `undefined` when there is nothing to render. */
+export function iso(ms) {
+    return ms === undefined ? undefined : new Date(ms).toISOString();
+}
+/** A bounded slice of a list, plus the full count, for a result field. */
+export function sample(items, limit = 50) {
+    return { shown: items.slice(0, limit), total: items.length };
+}

package/dist/lib/retention.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Reading a retention selection well enough to refuse it.
+ *
+ * `@crewhaus/harness-lifecycle` decides WHAT a sweep or purge deletes: the
+ * age rule, the pins, the audit windows, the audit-chain exclusion. None of
+ * that is re-decided here. What this module adds is the question the package
+ * does not answer — is this selection plausibly what the operator meant? —
+ * and the two shapes of "no" that matter:
+ *
+ *   1. THE RULE SELECTED EVERYTHING. A window that expires every session in
+ *      the store is either a deliberate wipe or a misconfiguration, and the
+ *      two are indistinguishable from inside the rule. It has to be said out
+ *      loud before the delete, not discovered after it.
+ *   2. A TIMESTAMP IS NOT A DATE. A session whose mtime is at or near epoch
+ *      zero is a broken clock, a failed copy or a restored archive — not data
+ *      from 1970. Age rules read it as infinitely old and delete it first.
+ *      There is deliberately no flag to wave this through: the fix is to
+ *      repair or pin the record, not to confirm a number nobody believes.
+ *
+ * The selection itself comes from running the package's OWN dry run, so the
+ * set being judged here is the set the real call will act on, produced by the
+ * same code — not a preview re-derived beside it.
+ */
+import type { RetentionEnforcementReport } from "@crewhaus/harness-lifecycle";
+/**
+ * Timestamps at or below this are treated as broken rather than old:
+ * 1971-01-01T00:00:00Z. A real harness session at or before that is not a
+ * thing; a zeroed or truncated mtime lands here every time.
+ *
+ * The comparison is inclusive because every sentence describing this rule —
+ * the tool's description, the refusal it prints — says "at or before", and a
+ * boundary that the prose and the code disagree about is a boundary nobody
+ * can reason about. Exactly `EPOCH_SANITY_MS` is a fabricated number, not
+ * data from the first instant of 1971.
+ */
+export declare const EPOCH_SANITY_MS: number;
+/** The shape of an inventory entry this module needs, structurally. */
+export type InventorySession = {
+    readonly sessionId: string;
+    readonly record: {
+        readonly id: string;
+        readonly createdAt: number;
+    };
+};
+export type SelectedRecord = {
+    readonly id: string;
+    readonly createdAtMs: number;
+    readonly paths: ReadonlyArray<string>;
+};
+export type Selection = {
+    readonly records: ReadonlyArray<SelectedRecord>;
+    readonly count: number;
+    readonly oldestMs?: number;
+    readonly newestMs?: number;
+    /** Selected records whose timestamp is at or below {@link EPOCH_SANITY_MS}. */
+    readonly epochZero: ReadonlyArray<SelectedRecord>;
+    /**
+     * Selected ids that were not in the inventory snapshot, so their age could
+     * not be read. Not an empty set of timestamps — an unknown one.
+     */
+    readonly unknownTimestamp: ReadonlyArray<string>;
+    readonly sessionsInStore: number;
+};
+/**
+ * Join the package's deletion list to the inventory snapshot, so the caller
+ * can be told not just HOW MANY records would go but how old the oldest and
+ * newest of them are — the two numbers that make a misconfigured window
+ * visible before it runs.
+ */
+export declare function summarizeSelection(report: RetentionEnforcementReport, sessions: ReadonlyArray<InventorySession>): Selection;
+export type BreadthOptions = {
+    readonly allowDeleteAll: boolean;
+    readonly maxDeletions?: number;
+    /** The parsed `before` cutoff, epoch ms, for a purge. */
+    readonly cutoffMs?: number;
+    readonly nowMs: number;
+};
+export type BreadthRefusal = {
+    readonly code: "refused";
+    readonly reason: string;
+};
+/**
+ * The refusals that keep a plausible-looking rule from taking the whole
+ * store. Order matters: the broken-timestamp refusal comes first because it
+ * explains WHY a rule that looks narrow selected everything.
+ */
+export declare function breadthRefusal(selection: Selection, opts: BreadthOptions): BreadthRefusal | undefined;

package/dist/lib/retention.js

@@ -0,0 +1,96 @@
+/**
+ * Timestamps at or below this are treated as broken rather than old:
+ * 1971-01-01T00:00:00Z. A real harness session at or before that is not a
+ * thing; a zeroed or truncated mtime lands here every time.
+ *
+ * The comparison is inclusive because every sentence describing this rule —
+ * the tool's description, the refusal it prints — says "at or before", and a
+ * boundary that the prose and the code disagree about is a boundary nobody
+ * can reason about. Exactly `EPOCH_SANITY_MS` is a fabricated number, not
+ * data from the first instant of 1971.
+ */
+export const EPOCH_SANITY_MS = Date.UTC(1971, 0, 1);
+/**
+ * Join the package's deletion list to the inventory snapshot, so the caller
+ * can be told not just HOW MANY records would go but how old the oldest and
+ * newest of them are — the two numbers that make a misconfigured window
+ * visible before it runs.
+ */
+export function summarizeSelection(report, sessions) {
+    const byId = new Map();
+    for (const s of sessions)
+        byId.set(s.record.id, s);
+    const records = [];
+    const unknownTimestamp = [];
+    for (const deletion of report.deleted) {
+        const entry = byId.get(deletion.id);
+        if (entry === undefined) {
+            // The enforcement pass named a record the snapshot does not have. That
+            // is a real divergence (a racing writer, a store that changed shape),
+            // and it is reported rather than silently treated as age-zero.
+            unknownTimestamp.push(deletion.id);
+            continue;
+        }
+        records.push({ id: deletion.id, createdAtMs: entry.record.createdAt, paths: deletion.paths });
+    }
+    const times = records.map((r) => r.createdAtMs);
+    return {
+        records,
+        count: report.deleted.length,
+        ...(times.length > 0 ? { oldestMs: Math.min(...times), newestMs: Math.max(...times) } : {}),
+        epochZero: records.filter((r) => r.createdAtMs <= EPOCH_SANITY_MS),
+        unknownTimestamp,
+        sessionsInStore: sessions.length,
+    };
+}
+/**
+ * The refusals that keep a plausible-looking rule from taking the whole
+ * store. Order matters: the broken-timestamp refusal comes first because it
+ * explains WHY a rule that looks narrow selected everything.
+ */
+export function breadthRefusal(selection, opts) {
+    if (selection.epochZero.length > 0) {
+        const shown = selection.epochZero
+            .slice(0, 5)
+            .map((r) => `${r.id} (${new Date(r.createdAtMs).toISOString()})`)
+            .join(", ");
+        return {
+            code: "refused",
+            reason: `refusing to delete on an age rule while ${selection.epochZero.length} selected record(s) carry a timestamp at or before ${new Date(EPOCH_SANITY_MS).toISOString()}: ${shown}. A timestamp that low is a broken clock or a failed copy, not data that old, and every age rule reads it as infinitely old. Repair the timestamps, or pin those sessions in .crewhaus/retention.json, and run again. There is no flag to override this.`,
+        };
+    }
+    if (selection.unknownTimestamp.length > 0) {
+        return {
+            code: "refused",
+            reason: `refusing: ${selection.unknownTimestamp.length} selected record(s) were not in the inventory snapshot, so their age could not be read (${selection.unknownTimestamp.slice(0, 5).join(", ")}). Something is writing to the store during the sweep; re-run when it is quiet.`,
+        };
+    }
+    if (opts.cutoffMs !== undefined &&
+        opts.cutoffMs > opts.nowMs &&
+        selection.count > 0 &&
+        !opts.allowDeleteAll) {
+        return {
+            code: "refused",
+            reason: `refusing: the purge cutoff ${new Date(opts.cutoffMs).toISOString()} is in the future, so "older than the cutoff" means every record in the store that its retention window allows. Pass a past cutoff, or set allowDeleteAll to confirm.`,
+        };
+    }
+    if (opts.maxDeletions !== undefined && selection.count > opts.maxDeletions) {
+        return {
+            code: "refused",
+            reason: `refusing: the selection is ${selection.count} record(s), over the maxDeletions limit of ${opts.maxDeletions} this call set.`,
+        };
+    }
+    if (!opts.allowDeleteAll &&
+        selection.count > 0 &&
+        selection.sessionsInStore > 0 &&
+        selection.count === selection.sessionsInStore) {
+        const window = selection.oldestMs !== undefined && selection.newestMs !== undefined
+            ? ` (oldest ${new Date(selection.oldestMs).toISOString()}, newest ${new Date(selection.newestMs).toISOString()})`
+            : "";
+        return {
+            code: "refused",
+            reason: `refusing: the age rule selects EVERY session in the store — ${selection.count} of ${selection.sessionsInStore}${window}. That is either a deliberate wipe or a misconfigured window, and this tool will not guess which. Set allowDeleteAll to confirm it is the former.`,
+        };
+    }
+    return undefined;
+}