@viloforge/vfkb 0.2.3 → 0.4.1

package/dist/cli.js

@@ -3,8 +3,10 @@
 // `hook session-start` / `hook post-tool-use` carry the harness JSON contract.
 import { addEntry, captureToolCall, readAll, renderContext, renderContextBundle, renderContextMap, renderNaiveDump, renderResume, initContextSpine, supersede, deriveTrust, } from './engine.js';
 import { SessionState, effectiveSessionId } from './session.js';
-import { defaultProject } from './storage.js';
+import { brainDir, defaultProject, withExclusive, writeMeta } from './storage.js';
+import { purgeJournal, recoverFromJournal } from './journal.js';
 import { runExport } from './export.js';
+import { broadcast as runBroadcast } from './broadcast.js';
 import { promote, archive, mergeDuplicate, findLexicalDuplicates, promoteIfCorroborated, eligibleForPromotion, } from './curator.js';
 import { distill } from './distiller.js';
 import { recordSignal, tally } from './counters.js';
@@ -80,7 +82,7 @@ async function main() {
         throw err;
     }
 }
-const USAGE = 'usage: vfkb <add|list|search|query|map|context|context init|resume|resume-note|curate|distill|save|' +
+const USAGE = 'usage: vfkb <add|broadcast|journal purge|list|search|query|map|context|context init|resume|resume-note|curate|distill|save|' +
     'export|import|init|doctor|supersede|context-block|context-block-naive|--version|' +
     'hook session-start|hook pre-tool-use|hook post-tool-use|hook stop|hook session-end>\n';
 async function dispatch() {
@@ -134,6 +136,43 @@ async function dispatch() {
         }
         return;
     }
+    // --- broadcast "<text>" --to <dir>[,<dir>…] [--op <name>] [--tag a,b] ---
+    // ADR-0063 §3: one cross-repo record per target brain, engine-written,
+    // origin/date/tag stamped, per-target result + commit posture, no commits.
+    if (cmd === 'broadcast') {
+        const p = parseArgs('broadcast', argsOf(sub, rest), {
+            to: 'value',
+            op: 'value',
+            tag: 'value',
+        });
+        const text = p.positionals.join(' ').trim();
+        const targets = flagList(p, 'to') ?? [];
+        if (!text || targets.length === 0) {
+            throw new UsageError('usage: vfkb broadcast "<text>" --to <dir>[,<dir>…] [--op <name>] [--tag a,b]');
+        }
+        try {
+            const results = runBroadcast(text, targets, {
+                op: flagValue(p, 'op'),
+                tags: flagList(p, 'tag'),
+            });
+            let failed = 0;
+            for (const r of results) {
+                if (r.ok) {
+                    process.stdout.write(`written\t${r.target}\t${r.id}\t${r.posture}${r.healed ? '\t(manifest healed — brain was wired but manifest-less, vfkb#193)' : ''}\n`);
+                }
+                else {
+                    failed++;
+                    process.stdout.write(`REFUSED\t${r.target}\t${r.reason}\n`);
+                }
+            }
+            process.stdout.write(`\nbroadcast: ${results.length - failed}/${results.length} written${failed ? ` — ${failed} refused (partial broadcast, visible by design)` : ''}\n`);
+            process.exit(failed > 0 ? 1 : 0);
+        }
+        catch (err) {
+            process.stderr.write(`error: ${err.message}\n`);
+            process.exit(1);
+        }
+    }
     // export <agents-md|okf> [--out <path>] — ADR-0047 brain export projections:
     // deterministic, generated-marked, never auto-committed publish artifacts.
     if (cmd === 'export') {
@@ -502,9 +541,32 @@ async function dispatch() {
             // NEXT session can resume from it (append-only). ADR-0039: the id comes from the
             // hook's own stdin (KB_SESSION_ID is an optional override) — no harness wiring needed.
             const session = SessionState.load(effectiveSessionId(payloadId));
-            const additionalContext = rest.includes('--naive')
-                ? renderNaiveDump(project, undefined, lim ? Number(lim) : undefined)
-                : renderResume(project, session);
+            // ADR-0064 §2: journal recovery runs BEFORE the digest renders, so a
+            // brain destroyed by a careless git operation is whole again by the time
+            // the session reads it. Fail-open (a hook must never error a session);
+            // the restore report rides the injected digest — the loud channel —
+            // because hook stderr is not reliably surfaced.
+            let restoreNote = '';
+            try {
+                const rec = withExclusive(() => recoverFromJournal(brainDir()));
+                if (rec.restored > 0) {
+                    // Restores bypass appendRecord (no re-journaling loop), so refresh
+                    // the freshness meta here — a long-lived index consumer must not
+                    // keep serving a pre-restore view (review m9).
+                    writeMeta();
+                    restoreNote =
+                        `⚠ vfkb restored ${rec.restored} journaled entr${rec.restored === 1 ? 'y' : 'ies'} ` +
+                            `lost from entries.jsonl — likely a destructive git operation on uncommitted brain ` +
+                            `state (ADR-0064). Verify with kb_list and commit the brain on your next topic branch.\n\n`;
+                }
+            }
+            catch {
+                /* fail-open — recovery must never cost a session its start */
+            }
+            const additionalContext = restoreNote +
+                (rest.includes('--naive')
+                    ? renderNaiveDump(project, undefined, lim ? Number(lim) : undefined)
+                    : renderResume(project, session));
             session.save();
             process.stdout.write(JSON.stringify({
                 hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext },
@@ -639,6 +701,25 @@ async function dispatch() {
         process.stdout.write((r.committed ? 'committed: ' : 'no-op: ') + r.message + '\n');
         return;
     }
+    // --- journal purge (--id <id> | --all) — the ADR-0064 §4 redaction escape
+    // hatch: removes journal lines and suppresses their (id, updated) pairs so
+    // recovery never resurrects a deliberately redacted entry.
+    if (cmd === 'journal') {
+        if (sub !== 'purge') {
+            throw new UsageError('usage: vfkb journal purge (--id <id> | --all)');
+        }
+        const p = parseArgs('journal purge', rest, { id: 'value', all: 'boolean' });
+        const id = flagValue(p, 'id');
+        const all = p.flags.has('all');
+        if (!!id === all) {
+            throw new UsageError('usage: vfkb journal purge (--id <id> | --all)');
+        }
+        const r = withExclusive(() => purgeJournal(brainDir(), { id, all }));
+        process.stdout.write(r.purged > 0
+            ? `purged ${r.purged} journal line(s); pair(s) suppressed — recovery will never restore them (ADR-0064 §4). Remember: a redaction of entries.jsonl is complete only with this purge.\n`
+            : 'no matching journal lines\n');
+        return;
+    }
     process.stderr.write(USAGE);
     process.exit(1);
 }

package/dist/doctor.js

@@ -3,9 +3,10 @@
 // or inconsistent wiring, and the dual-clone drift signal (a brain last stamped by
 // a different engine build). Deterministic; unit-tested (the inner gate per ADR-0023).
 import { execFileSync } from 'node:child_process';
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, realpathSync } from 'node:fs';
+import { join, dirname, relative, resolve, isAbsolute } from 'node:path';
 import { SCHEMA_VERSION, ENGINE_VERSION, ENGINE_COMMIT } from './version.js';
+import { journalStatus } from './journal.js';
 import { readManifest } from './manifest.js';
 function readJson(path) {
     if (!existsSync(path))
@@ -312,12 +313,81 @@ export async function checkNpmCurrency(opts) {
         clearTimeout(timer);
     }
 }
+// #186 — what OLD (pre-plugin) vfkb wiring actually is: a hook command that
+// invokes the ENGINE's hook dispatcher, either through the committed bootstrap
+// (ADR-0031) or by naming a hook subcommand directly.
+//
+// The predicate used to be `JSON.stringify(hook).includes('vfkb')`, which
+// classified ANY hook mentioning the string as old wiring — including the
+// ADR-0059 INACTIVE guard (`.claude/vfkb-guard.mjs`) that the plugin's own
+// MIGRATION_GUIDE tells every consumer to commit. So a correctly migrated repo
+// was told to delete its own INACTIVE detector, and real double wiring was
+// buried in a warning consumers had learned to ignore.
+const HOOK_SUBCOMMANDS = ['session-start', 'pre-tool-use', 'post-tool-use', 'stop', 'session-end'];
+export function isEngineWiring(hookJson) {
+    // Compare against the LITERAL command text, not its JSON encoding: a tab in the
+    // command is the two characters \\t once stringified, and a quoted subcommand is
+    // \\". Un-escaping first means the separator rule below is about real whitespace
+    // and quoting rather than about JSON spelling. (Review of PR #216, minor 5: the
+    // previous `\\?` sat before the whitespace, where JSON never puts a backslash.)
+    const text = hookJson.replace(/\\[tnr]/g, ' ').replace(/\\(.)/g, '$1');
+    if (/bootstrap\.mjs/.test(text))
+        return true;
+    return new RegExp(`\\bhook["'\\s]+(${HOOK_SUBCOMMANDS.join('|')})\\b`).test(text);
+}
+// #212 — a sentinel commit means "this build does not know its own identity"
+// (version.ts's honest `dev` fallback on the tsc/dist path), NOT "a different
+// engine stamped this brain". Comparing a sentinel against a real sha is not a
+// drift observation, it is an absence of one.
+//
+// The old predicate exempted a dev RUNNING engine but not a dev MANIFEST, so a
+// brain stamped by a dist-path build (e.g. the documented `node dist/cli.js`
+// fallback, which is how ViloGate's manifest got `"dev"`) reported drift forever
+// against every real-sha engine.
+export function engineDrift(manifestCommit, runningCommit) {
+    if (!manifestCommit || manifestCommit === 'dev')
+        return false;
+    if (!runningCommit || runningCommit === 'dev')
+        return false;
+    return manifestCommit !== runningCommit;
+}
+// #206 — the work tree that actually governs a path, or undefined outside a repo.
+function repoToplevel(root) {
+    try {
+        return execFileSync('git', ['-C', root, 'rev-parse', '--show-toplevel'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+// Containment on path BOUNDARIES: `/repo` must not be judged to contain
+// `/repo-other/...`. Both sides are realpath'd so a symlinked brain dir (or a
+// /tmp that resolves to /private/tmp) compares honestly rather than by spelling.
+function isUnder(parent, child) {
+    if (!parent)
+        return false;
+    const real = (p) => {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            return resolve(p);
+        }
+    };
+    const rel = relative(real(parent), real(child));
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
 export function runDoctor(opts) {
     const { root, brainDir, env } = opts;
+    // The identity we compare the brain's stamp against (injectable — see DoctorOpts).
+    const runningCommit = opts.engineCommit ?? ENGINE_COMMIT;
     const checks = [];
     const add = (name, status, detail) => checks.push({ name, status, detail });
     // 1. Engine identity (info).
-    add('engine', 'ok', `version ${ENGINE_VERSION} · commit ${ENGINE_COMMIT} · schema v${SCHEMA_VERSION}`);
+    add('engine', 'ok', `version ${ENGINE_VERSION} · commit ${runningCommit} · schema v${SCHEMA_VERSION}`);
     // Read the project settings once (used by plugin detection, hooks checks, and
     // project-consistency below), and detect ADR-0045 plugin wiring up front — it changes
     // what "healthy" means for the wiring checks AND which advice is safe to give
@@ -329,9 +399,19 @@ export function runDoctor(opts) {
     // 2. Brain ↔ engine compat (the load-bearing check).
     const mf = readManifest(brainDir);
     if (!mf) {
-        add('brain manifest', 'warn', plugin
-            ? `no manifest.json in ${brainDir} — it will be stamped on the next write`
-            : `no manifest.json in ${brainDir} — run \`vfkb init\` (or it will be stamped on next write)`);
+        add('brain manifest', 'warn', 
+        // #188 — the ordinary write path (addEntry → appendRecord → backend.append)
+        // never touches manifest.json. `writeManifest` has exactly two callers:
+        // `vfkb init` (init.ts) and the broadcast heal, which fires only when the
+        // manifest is ABSENT (broadcast.ts). Saying "on the next write" claimed
+        // behaviour the code does not have.
+        // On a PLUGIN-wired repo the message must not prescribe `vfkb init` — that
+        // advice is what scaffolds double wiring (issue #77), and the invariant is
+        // asserted in doctor.test.ts. A plugin-born brain simply has no manifest
+        // until a cross-repo broadcast heals it (vfkb#193).
+        plugin
+            ? `no manifest.json in ${brainDir} — plugin-born brains have none until a cross-repo broadcast heals it (vfkb#193); the ordinary write path never creates one`
+            : `no manifest.json in ${brainDir} — run \`vfkb init\` to stamp it (the ordinary write path never creates one)`);
     }
     else if (typeof mf.schema_version !== 'number') {
         add('brain manifest', 'warn', 'manifest has no numeric schema_version');
@@ -343,10 +423,58 @@ export function runDoctor(opts) {
         add('brain↔engine compat', 'warn', `brain schema v${mf.schema_version} is older than engine v${SCHEMA_VERSION} — migration may be needed`);
     }
     else {
-        add('brain↔engine compat', 'ok', `schema v${mf.schema_version} matches`);
+        // #212 — a sentinel stamp is suppressed as DRIFT (it is not drift), but it must
+        // not become invisible: the brain's provenance genuinely is unrecorded, and the
+        // stamping half of #212 (a build that does not know its commit should not write
+        // one) is still open. Reported in the detail rather than as a new warn — it is a
+        // true statement, but not one the consumer can act on, and this PR exists to stop
+        // doctor crying wolf.
+        const sentinel = mf.engine_commit === 'dev'
+            ? ` · stamped by a build that did not know its own commit ("dev") — provenance unknown (#212)`
+            : '';
+        add('brain↔engine compat', 'ok', `schema v${mf.schema_version} matches${sentinel}`);
         // Drift signal: same schema but a different engine build last stamped the brain.
-        if (mf.engine_commit && ENGINE_COMMIT !== 'dev' && mf.engine_commit !== ENGINE_COMMIT) {
-            add('engine drift', 'warn', `brain last stamped by engine ${mf.engine_commit}, running ${ENGINE_COMMIT} — possible dual-clone drift`);
+        if (engineDrift(mf.engine_commit, runningCommit)) {
+            add('engine drift', 'warn', `brain last stamped by engine ${mf.engine_commit}, running ${runningCommit} — possible dual-clone drift`);
+        }
+    }
+    // 2b. Durable-capture journal (ADR-0064): what would recovery do, and is a
+    // redaction half-done? Read-only — recovery itself runs at session start.
+    {
+        const js = journalStatus(brainDir);
+        if (js.suppressedInEntries > 0) {
+            add('journal', 'warn', `${js.suppressedInEntries} suppressed (purged) pair(s) still present in entries.jsonl — a redaction is half-done: remove the line(s) from entries.jsonl too (ADR-0064 §4)`);
+        }
+        else if (js.restorable > 0) {
+            add('journal', 'warn', `${js.restorable} journaled entr${js.restorable === 1 ? 'y' : 'ies'} missing from entries.jsonl — the next session-start restores them (or run \`vfkb hook session-start\` after checking why they vanished; recovery runs ONLY there)`);
+        }
+        else {
+            add('journal', 'ok', `${js.walLines} line(s) in the uncommitted window, nothing to restore`);
+        }
+        // Migration gap (review M3): an existing consumer that never re-ran init
+        // has no .journal/ gitignore line — its next `git add .vfkb` would COMMIT
+        // the wal (a tracked journal dies by the same reset --hard, RFC-034
+        // Alternatives; and a committed wal defeats §4 redaction).
+        // #206 — judge only a journal the repo actually governs. With the brain on
+        // the default ~/.vfkb tier (VFKB_DATA_DIR outside the work tree),
+        // `check-ignore` exits 128 ("path outside work tree"), which the catch-all
+        // below read as plain "not ignored" — so doctor advised editing a .gitignore
+        // that does not govern that path at all.
+        if (existsSync(join(brainDir, '.journal')) && isUnder(repoToplevel(root), join(brainDir, '.journal'))) {
+            try {
+                execFileSync('git', ['-C', root, 'check-ignore', '-q', join(brainDir, '.journal', 'wal.jsonl')], {
+                    stdio: 'ignore',
+                });
+            }
+            catch {
+                try {
+                    execFileSync('git', ['-C', root, 'rev-parse', '--is-inside-work-tree'], { stdio: 'ignore' });
+                    add('journal gitignore', 'warn', `.vfkb/.journal/ exists but is NOT gitignored — add '.vfkb/.journal/' to .gitignore before the next brain commit (a committed journal defeats its purpose and the ADR-0064 §4 redaction)`);
+                }
+                catch {
+                    /* not a git repo — nothing to ignore */
+                }
+            }
         }
     }
     // 3. $VFKB_BUNDLE_DIR resolves the bundles (the portability indirection, FR-2).
@@ -395,7 +523,7 @@ export function runDoctor(opts) {
     // 5. Hooks wiring (same plugin logic as check 4).
     const hooks = settings?.hooks ?? {};
     const expected = ['SessionStart', 'PreToolUse', 'Stop', 'SessionEnd'];
-    const have = expected.filter((e) => JSON.stringify(hooks[e] ?? '').includes('vfkb'));
+    const have = expected.filter((e) => isEngineWiring(JSON.stringify(hooks[e] ?? '')));
     if (plugin && have.length > 0) {
         add('.claude/settings.json', 'warn', `vfkb hooks present ALONGSIDE the plugin (double wiring) — remove them; the plugin's hooks are primary (ADR-0045)`);
     }

package/dist/engine.js

@@ -370,6 +370,32 @@ export function latestHandoff(all = readAll(), today = nowIso().slice(0, 10), su
     }
     return latest;
 }
+// --- Cross-repo operations pin (ADR-0063 §2): the delivery channel for visitor
+// records. Same selection-is-a-filter discipline as the handoff pin: newest
+// injectable entry tagged `cross-repo`. Entries also tagged handoff/next are
+// excluded defensively — ADR-0063 §1 forbids the combination (it would claim the
+// resident's continuity pin), and excluding them here keeps one entry from ever
+// rendering in both pinned sections.
+const CROSS_REPO_PIN_CAP_CHARS = 2000;
+export function latestCrossRepo(all = readAll(), today = nowIso().slice(0, 10), superseded = supersededIds(all)) {
+    let latest = null;
+    for (const e of all) {
+        if (!e.tags.includes('cross-repo'))
+            continue;
+        if (e.tags.includes('handoff') || e.tags.includes('next'))
+            continue;
+        if (!isInjectable(e, today, superseded))
+            continue;
+        if (!latest) {
+            latest = e;
+            continue;
+        }
+        const cmp = e.updated.localeCompare(latest.updated) || e.created.localeCompare(latest.created);
+        if (cmp >= 0)
+            latest = e;
+    }
+    return latest;
+}
 export function renderContextBundle(project = defaultProject(), budget = SESSION_BUDGET_CHARS) {
     const all = readAll();
     const today = nowIso().slice(0, 10);
@@ -405,25 +431,74 @@ export function renderContextBundle(project = defaultProject(), budget = SESSION
             : handoff.text;
         body += `## Last handoff\n- [${handoff.type} ${trustGlyph(handoff)}] ${text}\n\n`;
     }
+    // Cross-repo operations (ADR-0063 §2): pinned after the handoff, never
+    // budget-dropped — resident continuity and visitor records each get one
+    // guaranteed slot; neither can evict the other. Same bounded-pin discipline
+    // as the handoff (visitor records are free text from another session).
+    const crossRepo = latestCrossRepo(all, today, superseded);
+    if (crossRepo && !constitutionalIds.has(crossRepo.id)) {
+        const text = crossRepo.text.length > CROSS_REPO_PIN_CAP_CHARS
+            ? `${crossRepo.text.slice(0, CROSS_REPO_PIN_CAP_CHARS)}… (truncated — kb_get ${crossRepo.id} for the rest)`
+            : crossRepo.text;
+        body += `## Cross-repo operations\n- [${crossRepo.type} ${trustGlyph(crossRepo)}] ${text}\n\n`;
+    }
     // Context Map (ADR-0006): the navigational index, always injected, never dropped.
     body += renderContextMap() + '\n\n';
+    // Ranked lines are collected (not appended) so the omission note can evict
+    // trailing lines when needed — under the old append-as-you-go shape, a body
+    // that filled the budget exactly silently dropped the note itself, hiding
+    // that anything was cut at all (#177, the quiet-omission case).
+    const kept = [];
+    let keptLen = 0;
     let dropped = 0;
+    const fixedLen = () => header.length + body.length + footer.length;
     for (const e of injectable) {
         if (constitutionalIds.has(e.id))
             continue; // already in the Constitution section
         if (handoff && e.id === handoff.id)
             continue; // already pinned in Last handoff
+        if (crossRepo && e.id === crossRepo.id)
+            continue; // already pinned in Cross-repo operations
         const line = `- [${e.type} ${trustGlyph(e)}] ${e.text}\n`;
-        if (header.length + body.length + line.length + footer.length > budget) {
+        if (fixedLen() + keptLen + line.length > budget) {
             dropped++;
             continue;
         }
-        body += line;
+        kept.push(line);
+        keptLen += line.length;
     }
     if (dropped > 0) {
-        const note = `<!-- ${dropped} lower-ranked entries omitted for the ${budget}-char budget -->\n`;
-        if (header.length + body.length + note.length + footer.length <= budget)
-            body += note;
+        // Visible and actionable, not an HTML comment: name the count and the pull
+        // path. Evicting a kept line changes `dropped` and possibly the note's
+        // digit count, so the fit is re-checked each round.
+        const note = () => `(+ ${dropped} lower-ranked entries omitted for the ${budget}-char budget — kb_search / kb_list pulls them)\n`;
+        const evicted = [];
+        while (kept.length > 0 && fixedLen() + keptLen + note().length > budget) {
+            const line = kept.pop();
+            keptLen -= line.length;
+            evicted.push(line);
+            dropped++;
+        }
+        if (fixedLen() + keptLen + note().length <= budget) {
+            body += kept.join('') + note();
+        }
+        else {
+            // The note cannot fit even with everything evicted (fixed never-dropped
+            // sections leave less slack than one note line). Losing content to a
+            // note that then never renders would be a double loss — restore the
+            // evicted lines and emit without the note (review finding, round 1:
+            // the empty-kept fallback rendered FEWER entries than stock, noteless).
+            while (evicted.length > 0) {
+                const line = evicted.pop();
+                kept.push(line);
+                keptLen += line.length;
+                dropped--;
+            }
+            body += kept.join('');
+        }
+    }
+    else {
+        body += kept.join('');
     }
     return header + body + footer;
 }

package/dist/init.js

@@ -201,7 +201,7 @@ export function initProject(root, opts = {}) {
     // 4. .gitignore — the derived/operational stanza (append once).
     {
         const path = join(root, '.gitignore');
-        const lines = ['.vfkb/index-meta.json', '.vfkb/.sessions/', '.vfkb/.signals/'];
+        const lines = ['.vfkb/index-meta.json', '.vfkb/.sessions/', '.vfkb/.signals/', '.vfkb/.journal/'];
         const existed = existsSync(path);
         const cur = existed ? readFileSync(path, 'utf8') : '';
         const missing = lines.filter((l) => !cur.split(/\r?\n/).includes(l));

package/dist/journal.js

@@ -0,0 +1,207 @@
+// ADR-0064 (RFC-034) — durable capture: an untracked write-ahead journal
+// closes the brain-loss window between an engine append and the next brain
+// commit. `<brain>/.journal/` is gitignored BY DESIGN: `git checkout --`,
+// `reset --hard`, and stash operate on tracked state and leave it alive.
+//
+// Key discipline (review-hardened, RFC-034 §2/§3): everything is keyed on the
+// `(id, updated)` PAIR, never the bare id — entries.jsonl is an append-only
+// LWW log (a retag appends a new revision line for an existing id), and a
+// bare-id key would prune exactly the uncommitted revision lines the journal
+// exists to protect.
+//
+// This module deliberately imports nothing from storage.ts (storage imports
+// journalAppend, so an import back would cycle); callers pass the brain dir
+// and hold the ADR-0040 lock around recovery themselves.
+import { execFileSync } from 'node:child_process';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, sep } from 'node:path';
+const walPath = (brain) => join(brain, '.journal', 'wal.jsonl');
+const suppressedPath = (brain) => join(brain, '.journal', 'suppressed');
+// Wal rewrites (prune/purge) are temp-file + rename so a crash mid-rewrite
+// cannot truncate the journal. Residual race, documented (review m5): plain
+// `journalAppend`s are deliberately lock-free, so a mirror line landing
+// between a rewrite's read and its rename is dropped from the wal — the
+// primary append is unaffected; that one entry merely loses journal
+// protection until its next revision or commit. Compound-rare and fails
+// toward the pre-journal status quo, never toward corruption.
+function rewriteWal(wal, keep) {
+    const tmp = `${wal}.tmp`;
+    writeFileSync(tmp, keep.length > 0 ? keep.map((l) => l.raw).join('\n') + '\n' : '', 'utf8');
+    renameSync(tmp, wal);
+}
+const pairOf = (r) => `${String(r.id)}\u0000${String(r.updated ?? '')}`;
+function parseLines(text) {
+    const out = [];
+    for (const raw of text.split('\n')) {
+        if (raw.trim().length === 0)
+            continue;
+        try {
+            const rec = JSON.parse(raw);
+            if (typeof rec.id !== 'string')
+                continue;
+            out.push({ raw, pair: pairOf(rec), id: rec.id });
+        }
+        catch {
+            /* a torn/corrupt journal line protects nothing — skip it */
+        }
+    }
+    return out;
+}
+function pairsOfFile(path) {
+    if (!existsSync(path))
+        return new Set();
+    return new Set(parseLines(readFileSync(path, 'utf8')).map((l) => l.pair));
+}
+function suppressedPairs(brain) {
+    const p = suppressedPath(brain);
+    if (!existsSync(p))
+        return new Set();
+    return new Set(readFileSync(p, 'utf8')
+        .split('\n')
+        .filter((l) => l.includes('\t'))
+        .map((l) => l.replace('\t', '\u0000')));
+}
+/**
+ * Mirror one engine append into the journal — called JOURNAL-FIRST (before the
+ * primary append; a crash between the two leaves an extra journal line that
+ * idempotent recovery treats as lost-and-restorable, which is benign; the
+ * reverse order would leave a crash window with the primary unprotected).
+ * Fail-open with a loud edge: the safety net must never make capture itself
+ * less reliable. `VFKB_NO_JOURNAL=1` is the kill switch (contrast arms,
+ * emergencies).
+ */
+export function journalAppend(brain, rec) {
+    if (process.env.VFKB_NO_JOURNAL)
+        return;
+    try {
+        mkdirSync(join(brain, '.journal'), { recursive: true });
+        appendFileSync(walPath(brain), JSON.stringify(rec) + '\n', 'utf8');
+    }
+    catch (err) {
+        process.stderr.write(`vfkb: journal mirror failed (primary append proceeds unprotected): ${err.message}\n`);
+    }
+}
+// Conservative git classification (RFC-034 §3): a brain is a git brain iff
+// rev-parse succeeds; if the subsequent HEAD read fails for ANY reason
+// (unborn branch, detached/corrupt state, entries not tracked), prune nothing
+// this pass — never prune on uncertainty.
+function pairsAtHead(brain) {
+    const repoDir = dirname(brain);
+    const git = (...a) => execFileSync('git', ['-C', repoDir, ...a], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    try {
+        if (git('rev-parse', '--is-inside-work-tree') !== 'true')
+            return 'not-git';
+    }
+    catch {
+        return 'not-git';
+    }
+    try {
+        const top = git('rev-parse', '--show-toplevel');
+        const rel = relative(top, join(brain, 'entries.jsonl')).split(sep).join('/');
+        const head = execFileSync('git', ['-C', repoDir, 'cat-file', '-p', `HEAD:${rel}`], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        return new Set(parseLines(head).map((l) => l.pair));
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * Deterministic recovery + prune (RFC-034 §2/§3). Caller holds the ADR-0040
+ * lock (recovery is a read-decide-append op). Idempotent: a second run
+ * restores nothing.
+ *
+ * - restore: every journaled `(id, updated)` line absent from entries.jsonl
+ *   (and not suppressed) is re-appended VERBATIM — byte-identical, same ids.
+ * - prune: git brains drop wal lines whose pair is committed at HEAD
+ *   (committed is durable); non-git brains drop pairs present in
+ *   entries.jsonl itself; suppressed pairs are dropped as deliberately dead.
+ */
+export function recoverFromJournal(brain) {
+    // Kill-switch symmetry (review m7): an operator who disabled the journal in
+    // an emergency must not keep getting session-start restores from a stale wal.
+    if (process.env.VFKB_NO_JOURNAL)
+        return { restored: 0, pruned: 0 };
+    const wal = walPath(brain);
+    if (!existsSync(wal))
+        return { restored: 0, pruned: 0 };
+    const walLines = parseLines(readFileSync(wal, 'utf8'));
+    if (walLines.length === 0)
+        return { restored: 0, pruned: 0 };
+    const entriesPath = join(brain, 'entries.jsonl');
+    const present = pairsOfFile(entriesPath);
+    const suppressed = suppressedPairs(brain);
+    const toRestore = walLines.filter((l) => !present.has(l.pair) && !suppressed.has(l.pair));
+    if (toRestore.length > 0) {
+        // Torn-tail guard (review M1): a crash mid-append or a hand-redaction saved
+        // without a final newline leaves entries.jsonl ending in a partial line —
+        // appending blind would GLUE the restored line onto it, corrupting the very
+        // entry recovery exists to save (and the same-pass prune would then drop
+        // the journal copy: permanent loss in the non-git tier).
+        let prefix = '';
+        if (existsSync(entriesPath)) {
+            const cur = readFileSync(entriesPath, 'utf8');
+            if (cur.length > 0 && !cur.endsWith('\n'))
+                prefix = '\n';
+        }
+        appendFileSync(entriesPath, prefix + toRestore.map((l) => l.raw).join('\n') + '\n', 'utf8');
+    }
+    // Prune. After restore, every wal pair is in entries.jsonl; durability of
+    // the FILE is git's job for git brains, the file itself otherwise.
+    const head = pairsAtHead(brain);
+    let keep;
+    if (head === 'unknown') {
+        // HEAD unreadable — prune NOTHING this pass (RFC-034 §3, literally: never
+        // prune on uncertainty; even suppressed lines wait for a readable pass).
+        keep = walLines;
+    }
+    else if (head === 'not-git') {
+        keep = walLines.filter((l) => !suppressed.has(l.pair) && !present.has(l.pair) && !toRestore.includes(l));
+    }
+    else {
+        keep = walLines.filter((l) => !suppressed.has(l.pair) && !head.has(l.pair));
+    }
+    const pruned = walLines.length - keep.length;
+    if (pruned > 0) {
+        rewriteWal(wal, keep);
+    }
+    return { restored: toRestore.length, pruned };
+}
+/**
+ * Redaction escape hatch (RFC-034 §4): remove matching lines from the journal
+ * and record their pairs in `.journal/suppressed` — a suppressed pair is never
+ * recovered again, so a deliberate redaction of entries.jsonl stays redacted.
+ * A FUTURE clean revision of the same id journals and recovers normally (its
+ * new `updated` stamp makes a new pair).
+ */
+export function purgeJournal(brain, opts) {
+    const wal = walPath(brain);
+    if (!existsSync(wal))
+        return { purged: 0 };
+    const walLines = parseLines(readFileSync(wal, 'utf8'));
+    const gone = walLines.filter((l) => (opts.all ? true : l.id === opts.id));
+    if (gone.length === 0)
+        return { purged: 0 };
+    const keep = walLines.filter((l) => !gone.includes(l));
+    mkdirSync(join(brain, '.journal'), { recursive: true });
+    appendFileSync(suppressedPath(brain), gone.map((l) => l.pair.replace('\u0000', '\t')).join('\n') + '\n', 'utf8');
+    rewriteWal(wal, keep);
+    return { purged: gone.length };
+}
+/** Doctor's read-only view: what would recovery do, and is a redaction half-done? */
+export function journalStatus(brain) {
+    const wal = walPath(brain);
+    const walLines = existsSync(wal) ? parseLines(readFileSync(wal, 'utf8')) : [];
+    const present = pairsOfFile(join(brain, 'entries.jsonl'));
+    const suppressed = suppressedPairs(brain);
+    return {
+        walLines: walLines.length,
+        restorable: walLines.filter((l) => !present.has(l.pair) && !suppressed.has(l.pair)).length,
+        suppressedInEntries: [...suppressed].filter((p) => present.has(p)).length,
+    };
+}