@treeseed/dsh-chapters 0.1.23 → 0.2.0

package/lib/repair.d.ts

@@ -0,0 +1,200 @@
+/**
+ * The repair engine (#60) — re-derive the archive from the durable log, never edit it.
+ *
+ * WHY THIS EXISTS (docs/architecture.md § Repair). The durable session log is append-only and complete
+ * (invariant 1), which is the only reason the defects measured in the first `chapters`-preset project
+ * (`/home/adrian/Projects/saip`, see var/saip-audit/SAIP-CHAPTERS-AUDIT-2026-10-22.md) are recoverable
+ * at all: 12 hollow chapters a payload-less read produced, a 203-event completed turn no chapter covers,
+ * a 960 KB chapter file its own tree does not cite, two different `015-*.md` from one rewound counter,
+ * and two checkpoints citing files that were never written. Nothing in the plugin could see or say any
+ * of it. This module is the seeing; `/chapters-repair` is the saying; the fixes run through the SAME
+ * save core every other door uses, so a repaired chapter is byte-identical to a normal one.
+ *
+ * THE CONTRACT, in one line each:
+ *  1. **Supersede, never rewrite.** A damaged chapter gets a NEW number carrying `repairs:`, the old
+ *     record is marked `status: 'superseded'`, and the bad file is COPIED into `.repair-quarantine/`.
+ *     Nothing is deleted; nothing is edited in place (the body-hash guard is the only sanctioned
+ *     chapter-file mutation, and repair is not an exception to it).
+ *  2. **A dead citation is satisfied, not edited.** A compaction manifest already handed the host its
+ *     TOC text naming `…/020-<title>.md`. Repair renders that span and writes it AT the cited path with
+ *     the reserved number, so the committed text becomes true and no log byte moves.
+ *  3. **Numbers stay spent.** Releasing a reservation frees its retry key, never its numbers; a counter
+ *     is raised to `max(spent)+1` and never lowered.
+ *  4. **Journalled, therefore reversible.** An applied run writes `<tree>/repairs/<stamp>.json` FIRST —
+ *     one entry per move with before/after hashes — and `restore <journal-id>` walks it backwards.
+ *  5. **One serialized section per row.** Every registry mutation goes through `store.mutate` (#59): a
+ *     repair that clobbered a live door's commit would be #59 with better intentions.
+ */
+import { releaseReservation, type SessionState } from './registry.ts';
+import type { ChapterRecord } from './archive.ts';
+import type { RenderConfig } from './types.ts';
+/** What can be wrong. Each class maps to exactly one remedy; see `REMEDY`. */
+export type FindingClass = 'hollow-payload' | 'empty-artifact' | 'never-archived-span' | 'orphan-file' | 'unregistered-file' | 'duplicate-number' | 'countervalue-drift' | 'ghost-plan-manifest' | 'unreleased-reservation' | 'dead-citation' | 'tampered-file' | 'test-litter' | 'unrecoverable';
+export type Remedy = 'reread-span' | 'materialize-chapter' | 're-register-file' | 'quarantine-file' | 'release-reservation' | 'expire-manifest' | 'raise-counter' | 'report-only';
+export interface RepairFinding {
+    class: FindingClass;
+    session: string;
+    detail: string;
+    remedy: Remedy;
+    /** The chapter number, seq span or path the remedy acts on — the operator reads this, not prose. */
+    target: {
+        number?: number;
+        path?: string;
+        fromSeq?: number;
+        toSeq?: number;
+    };
+}
+/** What the auditor may ask about the store. The caller owns the filesystem; this stays pure. */
+export interface RepairFileSet {
+    exists(path: string): boolean;
+    bytes(path: string): number;
+    shaMatches(path: string, sha: string): boolean;
+    /** Every chapter `.md` present under this session's tree, however it got there. */
+    chapterPaths: string[];
+    artifactPaths: string[];
+    emptyArtifactPaths: string[];
+    /** Other session roots sitting in the same store (rig litter shows up here). */
+    roots?: string[];
+    /**
+     * Does this chapter file carry the #58 SHELL signature — `tool: unknown`, `arguments: {}`, a
+     * `0 B` result? That signature, not a zero message count, is what a payload-less read leaves behind:
+     * a repair split can legitimately produce a part with no prose (turn/step events only), and calling
+     * that a husk would report damage that is not damage. `false` when the caller cannot read files.
+     */
+    looksLikeShell?(path: string): boolean;
+    /**
+     * FALSE when the caller cannot list a directory — which is the HOST's case: `ArchiveFs` is
+     * write/read/exists only (src/archive.ts), so an in-host repair can never discover a file the registry
+     * does not cite. Reporting "no orphan files" from a port that cannot see them would be a lie of
+     * omission, exactly the class of defect this issue is about; so the audit returns BLIND SPOTS and the
+     * command says them out loud. The offline script (`scripts/chapters-repair.mjs`) has `readdir` and
+     * leaves this true.
+     */
+    canScan?: boolean;
+}
+export interface RepairLogFacts {
+    /** Every `turn/end` seq in the session — the ONLY authority on completeness (§4.3). */
+    turnEndSeqs: number[];
+    /** Signed collection spans, for reporting why a span went unsigned. */
+    collections: Array<{
+        from: number;
+        to: number;
+    }>;
+}
+export interface AuditInput {
+    sessionId: string;
+    /** Workspace cwd, so an absolute record path and the same file listed relatively are ONE path (#69). */
+    cwd?: string | undefined;
+    state: SessionState;
+    files: RepairFileSet;
+    log: RepairLogFacts;
+}
+/**
+ * Compare the three things that can disagree: the log, the files, the records.
+ *
+ * Deliberately READ-ONLY and pure — the same function serves `audit`, `dry-run` and `apply`, so what an
+ * operator sees is exactly what will be done, and a report can never be more optimistic than the run.
+ * A clean store must return an EMPTY list: a repair that prints friendly noise is a repair whose output
+ * nobody reads.
+ */
+export declare function audit(input: AuditInput): {
+    findings: RepairFinding[];
+    blindSpots: FindingClass[];
+};
+/**
+ * A health line from the REGISTRY ALONE (#61), for `/chapters-status` — no log read, no directory scan.
+ *
+ * `audit()` needs the durable log and the files to judge coverage and orphans; a status command must
+ * still say something true at boot, in a project it cannot scan. So this counts only what a row knows
+ * about itself, and the caller must say what was NOT checked. A "0 findings" line from a partial check
+ * would be a lie of omission, and that is the defect family this issue exists to end.
+ */
+export interface RegistryHealth {
+    hollow: number;
+    duplicate: number;
+    drift: number;
+    unreleased: number;
+    ghost: number;
+    superseded: number;
+    chapters: number;
+    sessions: number;
+}
+export declare function registryHealth(states: readonly SessionState[]): {
+    text: string;
+    counts: RegistryHealth;
+};
+/**
+ * The class names an operator may type, and what each expands to (#60). BOTH `/chapters-repair` and
+ * `scripts/chapters-repair.mjs` read this table — two lists is how the command quietly accepted
+ * `--apply bogus` and reported "0 moves" as success while the script refused it. Unknown names must
+ * fail loudly: a repair that does nothing and says nothing is the defect this whole issue is named for.
+ */
+export declare const REPAIR_CLASS_ALIASES: Record<string, string | string[]>;
+/** Resolve operator words into finding classes, or return the unknown names it must refuse. */
+export declare function resolveRepairClasses(input: readonly string[]): {
+    classes: FindingClass[];
+    unknown: string[];
+};
+/** Every class the auditor can produce — the accept-list for operator words. */
+export declare const FINDING_CLASSES: readonly FindingClass[];
+/**
+ * Mark the damaged record superseded and commit its replacement, in ONE pure state transition.
+ *
+ * The old record KEEPS its number, its seqs and its hash: the watermark is `max(endSeq)+1` and a spent
+ * number must never be re-spendable (#59). What changes is that it stops being knowledge — every derived
+ * layer reads it through `isActiveChapter`, so it leaves the TOC, the index and the enrichment queue.
+ */
+export declare function supersedeChapter(state: SessionState, overNumber: number, replacements: readonly ChapterRecord[], reason: FindingClass, at?: number): SessionState;
+/**
+ * Mark a record superseded by a chapter that ALREADY EXISTS — no new bytes (#60).
+ *
+ * The residue after a project-wide repair: a husk whose span was re-archived correctly by an earlier
+ * run, so re-rendering it now is a no-op and `supersedeChapter` (which commits replacements) can never
+ * run. The knowledge is safe; only the false record is still circulating. This closes that last step:
+ * point the husk at whatever active chapter covers its seqs, and let the derived layers drop it.
+ * Refuses (returns the state unchanged with a reason) when nothing covers the span — because silently
+ * superseding an uncovered span would delete the only claim that content exists.
+ */
+export declare function markSupersededBy(state: SessionState, overNumber: number, byNumber: number, reason: FindingClass, at?: number): {
+    state: SessionState;
+    problem?: string;
+};
+/**
+ * The active chapter whose span fully covers `[from..to]`, if any — the candidate a husk defers to.
+ * `exceptNumber` is not cosmetic: the husk covers its OWN span, so without excluding it the search
+ * returns the record about to be superseded and `markSupersededBy` would point a chapter at itself
+ * (caught by `tests/unit/repair.test.ts`).
+ */
+export declare function coveringChapter(state: SessionState, from: number, to: number, exceptNumber?: number): ChapterRecord[];
+/** Raise a counter to the first number nothing has spent. Upward ONLY — never a rewind. */
+export declare function raiseCounters(state: SessionState): SessionState;
+/** Drop a manifest/reservation whose work never landed, keeping every number spent. */
+export declare function expireBookkeeping(state: SessionState, keys: readonly string[]): SessionState;
+export { releaseReservation };
+export interface JournalEntry {
+    kind: 'write' | 'quarantine' | 'registry';
+    path: string;
+    beforeSha: string | null;
+    afterSha: string | null;
+    /** Quarantine target, registry rev, or the span re-read — whatever `undo` needs. */
+    to?: string;
+    rev?: number;
+}
+export interface Journal {
+    id: string;
+    sessionId: string;
+    startedAt: number;
+    classes: FindingClass[];
+    /** Null until the run finishes; an unfinished journal is how `status` knows a run died. */
+    completedAt: number | null;
+    entries: JournalEntry[];
+    findingsBefore: number;
+    findingsAfter: number;
+}
+/** How an entry is undone. The inverse is DERIVED, never hand-written, so a journal cannot lie about itself. */
+export declare function journalEntryInverse(e: JournalEntry): {
+    undo: 'remove' | 'restore-from-quarantine' | 'restore-registry-rev' | 'unchanged';
+};
+/** Chapter-file frontmatter keys a repair adds. `renderChapter` owns every other byte. */
+export declare function repairFrontmatter(lines: readonly string[], marks: JournalEntry[]): string[];
+export type { RenderConfig };

package/lib/repair.js

@@ -0,0 +1,354 @@
+/**
+ * The repair engine (#60) — re-derive the archive from the durable log, never edit it.
+ *
+ * WHY THIS EXISTS (docs/architecture.md § Repair). The durable session log is append-only and complete
+ * (invariant 1), which is the only reason the defects measured in the first `chapters`-preset project
+ * (`/home/adrian/Projects/saip`, see var/saip-audit/SAIP-CHAPTERS-AUDIT-2026-10-22.md) are recoverable
+ * at all: 12 hollow chapters a payload-less read produced, a 203-event completed turn no chapter covers,
+ * a 960 KB chapter file its own tree does not cite, two different `015-*.md` from one rewound counter,
+ * and two checkpoints citing files that were never written. Nothing in the plugin could see or say any
+ * of it. This module is the seeing; `/chapters-repair` is the saying; the fixes run through the SAME
+ * save core every other door uses, so a repaired chapter is byte-identical to a normal one.
+ *
+ * THE CONTRACT, in one line each:
+ *  1. **Supersede, never rewrite.** A damaged chapter gets a NEW number carrying `repairs:`, the old
+ *     record is marked `status: 'superseded'`, and the bad file is COPIED into `.repair-quarantine/`.
+ *     Nothing is deleted; nothing is edited in place (the body-hash guard is the only sanctioned
+ *     chapter-file mutation, and repair is not an exception to it).
+ *  2. **A dead citation is satisfied, not edited.** A compaction manifest already handed the host its
+ *     TOC text naming `…/020-<title>.md`. Repair renders that span and writes it AT the cited path with
+ *     the reserved number, so the committed text becomes true and no log byte moves.
+ *  3. **Numbers stay spent.** Releasing a reservation frees its retry key, never its numbers; a counter
+ *     is raised to `max(spent)+1` and never lowered.
+ *  4. **Journalled, therefore reversible.** An applied run writes `<tree>/repairs/<stamp>.json` FIRST —
+ *     one entry per move with before/after hashes — and `restore <journal-id>` walks it backwards.
+ *  5. **One serialized section per row.** Every registry mutation goes through `store.mutate` (#59): a
+ *     repair that clobbered a live door's commit would be #59 with better intentions.
+ */
+import { appendChapters, isActiveChapter, releaseReservation } from "./registry.js";
+import { sameStoredPath } from "./archive.js";
+const REMEDY = {
+    'hollow-payload': 'reread-span',
+    'empty-artifact': 'quarantine-file',
+    'never-archived-span': 'reread-span',
+    'orphan-file': 'materialize-chapter',
+    'unregistered-file': 're-register-file',
+    'duplicate-number': 'reread-span',
+    'countervalue-drift': 'raise-counter',
+    'ghost-plan-manifest': 'expire-manifest',
+    'unreleased-reservation': 'release-reservation',
+    'dead-citation': 'materialize-chapter',
+    'tampered-file': 'report-only',
+    'test-litter': 'report-only',
+    unrecoverable: 'report-only',
+};
+/**
+ * Compare the three things that can disagree: the log, the files, the records.
+ *
+ * Deliberately READ-ONLY and pure — the same function serves `audit`, `dry-run` and `apply`, so what an
+ * operator sees is exactly what will be done, and a report can never be more optimistic than the run.
+ * A clean store must return an EMPTY list: a repair that prints friendly noise is a repair whose output
+ * nobody reads.
+ */
+export function audit(input) {
+    const { sessionId, state, files, log, cwd } = input;
+    const findings = [];
+    const add = (f) => {
+        findings.push({ ...f, session: sessionId, remedy: REMEDY[f.class] });
+    };
+    const active = state.chapters.filter(isActiveChapter);
+    // 1. Hollow chapters: the pair that turned 12 recoverable archives into permanent ones (#58).
+    for (const c of active) {
+        // STRICT equality: `messages` is ABSENT on records written before counts existed, and on every row
+        // a repair re-registered from a file whose frontmatter has no such field (render.ts: "absent … never
+        // a lying zero"). Coercing undefined to 0 turned 162 legitimate re-registrations into false
+        // "hollow-payload" findings on the first real run — an auditor that invents damage is worse than one
+        // that misses it, because the operator learns to distrust the report.
+        // A record with `messages === 0` is suspect, but not always a wound: a repair that split one enormous
+        // turn into event-bounded parts knowingly produced parts holding tool calls and no prose (save-core
+        // names each in its warnings). The discriminator is CONTENT, not provenance — my first guess was a
+        // `repairs` stamp, and it missed, because parts made by the never-archived-span branch carry no
+        // stamp at all, so a healthy repaired tree reported 14 fresh "husks". A #58 shell deferred
+        // ZERO-BYTE blobs (its read had no payloads to defer); a real tool-only part has bytes. An empty
+        // Evidence, not arithmetic: a payload-less read left EITHER zero-byte deferred blobs (it "archived"
+        // 335 empty results) OR the shell signature in the bytes (`tool: unknown`, `arguments: {}`). A bare
+        // empty artifact list is NOT evidence — a repair split legitimately produces an empty part (turn and
+        // step events only), and three of those were reported as husks until this rule named its evidence.
+        const shellSignature = files.looksLikeShell?.(c.path) ?? false;
+        const zeroByteBlobs = c.artifacts.length > 0 && c.artifacts.every((a) => a.bytes === 0);
+        if (c.messages === 0 && c.endSeq >= c.startSeq && (zeroByteBlobs || shellSignature)) {
+            add({ class: 'hollow-payload', detail: `chapter ${c.number} ("${c.title}") has messages 0 over seqs ${c.startSeq}-${c.endSeq} — a payload read that went wrong, not a short conversation`, target: { number: c.number, path: c.path, fromSeq: c.startSeq, toSeq: c.endSeq } });
+        }
+        else if (!files.exists(c.path)) {
+            // 2. A record whose file is gone: knowledge for the reader, a ghost for every tool.
+            add({ class: 'orphan-file', detail: `chapter ${c.number} is recorded at ${c.path} but no such file exists — the record is a ghost: re-render it from the log`, target: { number: c.number, path: c.path, fromSeq: c.startSeq, toSeq: c.endSeq } });
+        }
+        else if (!files.shaMatches(c.path, c.sha256)) {
+            add({ class: 'tampered-file', detail: `chapter ${c.number}'s body hash no longer matches ${c.path}`, target: { number: c.number, path: c.path } });
+        }
+        for (const a of c.artifacts) {
+            if (a.bytes === 0 || files.emptyArtifactPaths.includes(a.path)) {
+                add({ class: 'empty-artifact', detail: `chapter ${c.number} cites the 0-byte blob ${a.path} (sha ${a.sha256.slice(0, 12)}…) as an artifact`, target: { path: a.path, number: c.number } });
+            }
+        }
+    }
+    // 3. Files the registry does not cite — the shape a lost update leaves behind (#59: the 960 KB case).
+    // #69: cited-ness is compared with `sameStoredPath`, NEVER string equality — that is how one file at
+    // one path became a cited record AND its own unregistered twin, and the auditor reported its own
+    // archive as lost knowledge.
+    const cited = state.chapters.map((c) => c.path);
+    for (const p of files.chapterPaths) {
+        if (!cited.some((q) => sameStoredPath(q, p, cwd)) && !p.includes('.repair-quarantine')) {
+            const m = /\/(\d{3})-/.exec(p);
+            const num = m ? Number(m[1]) : undefined;
+            add({ class: 'unregistered-file', detail: `${p} exists on disk and no chapter record cites it — the registry lost its commit${num !== undefined ? ` (number ${num})` : ''}`, ...(num !== undefined ? { target: { path: p, number: num } } : { target: { path: p } }) });
+        }
+    }
+    // 4. Two records on one number (identity is (number, sha256), never number alone).
+    const byNumber = new Map();
+    for (const c of state.chapters)
+        byNumber.set(c.number, [...(byNumber.get(c.number) ?? []), c]);
+    for (const [n, list] of byNumber) {
+        if (list.length > 1) {
+            add({ class: 'duplicate-number', detail: `chapter number ${n} is carried by ${list.length} different records (${list.map((c) => c.path.split('/').pop()).join(', ')}) — a lost update re-spent it`, target: { number: n } });
+        }
+    }
+    // 5. A counter at or below what is already spent: the next door would collide (#59).
+    const maxSpent = state.chapters.reduce((m, c) => Math.max(m, c.number), 0);
+    if (state.nextChapterNumber <= maxSpent) {
+        add({ class: 'countervalue-drift', detail: `nextChapterNumber ${state.nextChapterNumber} is not above the highest spent number ${maxSpent}`, target: { number: maxSpent + 1 } });
+    }
+    // 6. Coverage: a completed turn inside no chapter. turn/end is the ONLY authority on completeness —
+    //    the old note inferred "unfinished" from a missing signature and was wrong (#59).
+    const covered = new Set();
+    for (const c of active)
+        for (let s = c.startSeq; s <= c.endSeq; s++)
+            covered.add(s);
+    const lastEnd = log.turnEndSeqs.length > 0 ? Math.max(...log.turnEndSeqs) : -1;
+    let holeStart = -1;
+    const flushHole = (to) => {
+        if (holeStart >= 0) {
+            add({ class: 'never-archived-span', detail: `seqs ${holeStart}-${to} belong to COMPLETED turns and are inside no chapter — signed collections do not cover them`, target: { fromSeq: holeStart, toSeq: to } });
+            holeStart = -1;
+        }
+    };
+    for (let s = 0; s <= lastEnd; s++) {
+        if (!covered.has(s))
+            holeStart = holeStart < 0 ? s : holeStart;
+        else
+            flushHole(s - 1);
+    }
+    flushHole(lastEnd);
+    // 7. Bookkeeping: manifests the row still carries for work that never landed. The manifest IS the
+    //    plan the post-commit finalizer was going to execute — `path` is the chapter it promised to
+    //    commit, `number` its reserved chapter number, `chapters` the bullets it already handed the host
+    //    as TOC text (src/registry.ts PlanManifest). Read the real shape, not an imagined one.
+    for (const [key, plan] of Object.entries(state.plans ?? {})) {
+        if (!state.chapters.some((c) => sameStoredPath(c.path, plan.path, cwd)) && !files.exists(plan.path)) {
+            add({ class: 'ghost-plan-manifest', detail: `finalize manifest ${key} promises chapter ${plan.number} at ${plan.path}, which never landed`, target: { path: plan.path, number: plan.number } });
+        }
+        // 8. Dead citations: the manifest's OWN committed TOC bullets naming files that do not exist.
+        //    The host already holds that text — satisfaction, never editing, is the honest repair (#60).
+        for (const ch of plan.chapters ?? []) {
+            if (!files.exists(ch.path)) {
+                const num = /\/(\d{3})-/.exec(ch.path)?.[1];
+                add({
+                    class: 'dead-citation',
+                    detail: `a committed checkpoint cites ${ch.path} (number ${num ?? '?'}) and that file was never written — render the span and write it AT that path; do not touch the text`,
+                    ...(num !== undefined ? { target: { path: ch.path, number: Number(num) } } : { target: { path: ch.path } }),
+                });
+            }
+        }
+    }
+    for (const [key, numbers] of Object.entries(state.reservations ?? {})) {
+        const landed = numbers.every((n) => state.chapters.some((c) => c.number === n));
+        if (!landed) {
+            add({ class: 'unreleased-reservation', detail: `reservation ${key} holds [${numbers.join(', ')}] and not every number produced a record — its key can never land`, ...(numbers[0] !== undefined ? { target: { number: numbers[0] } } : { target: {} }) });
+        }
+    }
+    // 9. Someone else's data in this store: reported, never decided here.
+    for (const root of files.roots ?? []) {
+        add({ class: 'test-litter', detail: `the store holds a second root ${root} (not this session's tree); it is not touched automatically — inspect it before removing anything`, target: { path: root } });
+    }
+    // What we could NOT look at, stated rather than implied. The host port has no directory listing, so
+    // unlisted files and stray roots are invisible there; the offline script sees them.
+    const blindSpots = files.canScan === false ? ['orphan-file', 'test-litter'] : [];
+    return { findings, blindSpots };
+}
+export function registryHealth(states) {
+    const counts = { hollow: 0, duplicate: 0, drift: 0, unreleased: 0, ghost: 0, superseded: 0, chapters: 0, sessions: states.length };
+    for (const st of states) {
+        counts.chapters += st.chapters.length;
+        counts.superseded += st.chapters.filter((c) => c.status === 'superseded').length;
+        counts.hollow += st.chapters.filter((c) => c.messages === 0 && c.artifacts.every((a) => a.bytes === 0)).length;
+        const seen = new Set();
+        for (const c of st.chapters) {
+            if (seen.has(c.number))
+                counts.duplicate += 1;
+            seen.add(c.number);
+        }
+        if (st.chapters.length > 0 && st.nextChapterNumber <= Math.max(...st.chapters.map((c) => c.number)))
+            counts.drift += 1;
+        for (const [key, nums] of Object.entries(st.reservations ?? {})) {
+            if (!nums.every((n) => st.chapters.some((c) => c.number === n)))
+                counts.unreleased += 1;
+            void key;
+        }
+        for (const plan of Object.values(st.plans ?? {})) {
+            if (!st.chapters.some((c) => c.path === plan.path) && plan.path !== '')
+                counts.ghost += 1;
+        }
+    }
+    const parts = Object.keys(counts)
+        .filter((k) => k !== 'chapters' && k !== 'sessions')
+        .map((k) => `${k}=${counts[k]}`);
+    return {
+        text: `${counts.sessions} session row(s), ${counts.chapters} chapter record(s) — ${parts.join(' · ')}`,
+        counts,
+    };
+}
+// ─────────────────────────────────────────────────── operator vocabulary (pure, ONE list)
+/**
+ * The class names an operator may type, and what each expands to (#60). BOTH `/chapters-repair` and
+ * `scripts/chapters-repair.mjs` read this table — two lists is how the command quietly accepted
+ * `--apply bogus` and reported "0 moves" as success while the script refused it. Unknown names must
+ * fail loudly: a repair that does nothing and says nothing is the defect this whole issue is named for.
+ */
+export const REPAIR_CLASS_ALIASES = {
+    hollow: 'hollow-payload',
+    gaps: 'never-archived-span',
+    citations: 'dead-citation',
+    bookkeeping: ['ghost-plan-manifest', 'unreleased-reservation', 'countervalue-drift'],
+    files: 'unregistered-file',
+    orphans: 'unregistered-file',
+    all: 'all',
+};
+/** Resolve operator words into finding classes, or return the unknown names it must refuse. */
+export function resolveRepairClasses(input) {
+    if (input.length === 0 || input.includes('all'))
+        return { classes: 'all', unknown: [] };
+    const expanded = input.flatMap((c) => REPAIR_CLASS_ALIASES[c] ?? c);
+    if (expanded.includes('all'))
+        return { classes: 'all', unknown: [] };
+    const unknown = expanded.filter((c) => !FINDING_CLASSES.includes(c));
+    return { classes: expanded, unknown };
+}
+/** Every class the auditor can produce — the accept-list for operator words. */
+export const FINDING_CLASSES = [
+    'hollow-payload', 'empty-artifact', 'never-archived-span', 'orphan-file', 'unregistered-file',
+    'duplicate-number', 'countervalue-drift', 'ghost-plan-manifest', 'unreleased-reservation',
+    'dead-citation', 'tampered-file', 'test-litter', 'unrecoverable',
+];
+// ─────────────────────────────────────────────────── supersede (pure)
+/**
+ * Mark the damaged record superseded and commit its replacement, in ONE pure state transition.
+ *
+ * The old record KEEPS its number, its seqs and its hash: the watermark is `max(endSeq)+1` and a spent
+ * number must never be re-spendable (#59). What changes is that it stops being knowledge — every derived
+ * layer reads it through `isActiveChapter`, so it leaves the TOC, the index and the enrichment queue.
+ */
+export function supersedeChapter(state, overNumber, replacements, reason, at = Date.now()) {
+    const stamped = replacements.map((r) => ({ ...r, repairs: [...(r.repairs ?? []), { class: reason, over: overNumber, at }] }));
+    const withMarks = {
+        ...state,
+        chapters: state.chapters.map((c) => (c.number === overNumber && replacements.length > 0
+            ? { ...c, status: 'superseded', supersededBy: replacements[0].number }
+            : c)),
+    };
+    return appendChapters(withMarks, stamped);
+}
+/**
+ * Mark a record superseded by a chapter that ALREADY EXISTS — no new bytes (#60).
+ *
+ * The residue after a project-wide repair: a husk whose span was re-archived correctly by an earlier
+ * run, so re-rendering it now is a no-op and `supersedeChapter` (which commits replacements) can never
+ * run. The knowledge is safe; only the false record is still circulating. This closes that last step:
+ * point the husk at whatever active chapter covers its seqs, and let the derived layers drop it.
+ * Refuses (returns the state unchanged with a reason) when nothing covers the span — because silently
+ * superseding an uncovered span would delete the only claim that content exists.
+ */
+export function markSupersededBy(state, overNumber, byNumber, reason, at = Date.now()) {
+    const over = state.chapters.find((c) => c.number === overNumber);
+    const by = state.chapters.find((c) => c.number === byNumber);
+    if (over === undefined)
+        return { state, problem: `no record for chapter ${overNumber}` };
+    if (by === undefined)
+        return { state, problem: `no covering chapter ${byNumber} to supersede ${overNumber} with` };
+    if (byNumber === overNumber)
+        return { state, problem: `chapter ${overNumber} cannot supersede itself` };
+    // Full coverage is the caller's job (`coveringChapter` returns a SET); this guard only insists the
+    // named successor starts no later than the husk, so the citation never claims a partial span.
+    if (by.startSeq > over.startSeq) {
+        return { state, problem: `chapter ${byNumber} starts at ${by.startSeq}, above ${overNumber}'s span start ${over.startSeq}` };
+    }
+    return {
+        state: {
+            ...state,
+            chapters: state.chapters.map((c) => (c.number === overNumber
+                ? { ...c, status: 'superseded', supersededBy: byNumber, repairs: [...(c.repairs ?? []), { class: reason, over: overNumber, at }] }
+                : c)),
+        },
+    };
+}
+/**
+ * The active chapter whose span fully covers `[from..to]`, if any — the candidate a husk defers to.
+ * `exceptNumber` is not cosmetic: the husk covers its OWN span, so without excluding it the search
+ * returns the record about to be superseded and `markSupersededBy` would point a chapter at itself
+ * (caught by `tests/unit/repair.test.ts`).
+ */
+export function coveringChapter(state, from, to, exceptNumber) {
+    // A REPAIR may have split the span across several chapters, so coverage is a UNION, not one record:
+    // insisting on a single coverer left 14 husks unsuperseded in the first full project run, each
+    // "not covered" when in fact three chapters carried it between them.
+    const pool = state.chapters.filter((c) => isActiveChapter(c) && c.number !== exceptNumber && c.startSeq <= to && c.endSeq >= from);
+    const sorted = [...pool].sort((a, b) => a.startSeq - b.startSeq);
+    let cursor = from;
+    const chosen = [];
+    for (const c of sorted) {
+        if (c.startSeq > cursor)
+            break; // a real hole: nothing reaches `cursor`
+        chosen.push(c);
+        cursor = Math.max(cursor, c.endSeq + 1);
+        if (cursor > to)
+            return chosen;
+    }
+    return [];
+}
+/** Raise a counter to the first number nothing has spent. Upward ONLY — never a rewind. */
+export function raiseCounters(state) {
+    const maxChapter = state.chapters.reduce((m, c) => Math.max(m, c.number), 0);
+    const maxPlan = state.chapters.flatMap((c) => c.planDocs ?? [])
+        .map((d) => /plan-(\d+)-/.exec(d.path)?.[1]).filter((n) => n !== undefined).map(Number)
+        .reduce((m, n) => Math.max(m, n), 0);
+    return {
+        ...state,
+        nextChapterNumber: Math.max(state.nextChapterNumber, maxChapter + 1),
+        nextPlanNumber: Math.max(state.nextPlanNumber, maxPlan + 1),
+    };
+}
+/** Drop a manifest/reservation whose work never landed, keeping every number spent. */
+export function expireBookkeeping(state, keys) {
+    const plans = { ...state.plans };
+    const reservations = { ...state.reservations };
+    for (const k of keys) {
+        delete plans[k];
+        delete reservations[k];
+    }
+    return { ...state, plans, reservations };
+}
+export { releaseReservation };
+/** How an entry is undone. The inverse is DERIVED, never hand-written, so a journal cannot lie about itself. */
+export function journalEntryInverse(e) {
+    if (e.kind === 'registry')
+        return { undo: 'restore-registry-rev' };
+    if (e.kind === 'quarantine')
+        return { undo: 'restore-from-quarantine' };
+    if (e.beforeSha === null)
+        return { undo: 'remove' };
+    return { undo: 'restore-from-quarantine' };
+}
+/** Chapter-file frontmatter keys a repair adds. `renderChapter` owns every other byte. */
+export function repairFrontmatter(lines, marks) {
+    return [...lines, ...marks.map((m) => `repairs: ${m.path}`)];
+}
+//# sourceMappingURL=repair.js.map

package/lib/repair.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repair.js","sourceRoot":"","sources":["../src/repair.ts"],"names":[],"mappings":"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"}

package/lib/rules-commands.d.ts

@@ -16,6 +16,28 @@ export interface RulesIo {
     /** provenance of the ADD path: 'manual' for commands, the session id for the tool */
     sourceSession?: string;
     now: () => Date;
+    /**
+     * #50 §7.5: the current session's ancestor path (root-first), so `active`,
+     * `list --scope session` and `conflicts` can tell which session rules bind.
+     * Absent ⇒ the session tier is reported as unresolved, never guessed.
+     */
+    ancestors?: () => Promise<ReadonlySet<string>>;
+    /** #52: true when the ancestry walk hit its cap (delegation or continuation). */
+    ancestryTruncated?: () => Promise<boolean>;
+    /** #50 §7.7: ONE bounded model call, report-only. Absent ⇒ the verb refuses. */
+    ask?: (prompt: string) => Promise<string>;
+    /** §7.3/§7.4 numbers the answer is measured with — the SAME config the doors
+     * render from, so `active` cannot report a view the head will not show. */
+    budgetTokens?: number;
+    projectCap?: number;
+    sessionCap?: number;
+    /** §7.5: reported by `active`, and drives whether mined rules govern on arrival */
+    autoActivate?: boolean | undefined;
+    /** the shared settings table (`rules.model` lives beside `enrichment.model`) */
+    settings?: {
+        get(key: string): string | undefined;
+        put(key: string, value: string): Promise<void>;
+    } | undefined;
 }
 export interface RulesReply {
     kind: 'success' | 'error';