@viloforge/vfkb 0.2.3 → 0.4.0

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

@@ -6,6 +6,7 @@ import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join, dirname } 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))
@@ -349,6 +350,40 @@ export function runDoctor(opts) {
             add('engine drift', 'warn', `brain last stamped by engine ${mf.engine_commit}, running ${ENGINE_COMMIT} — 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).
+        if (existsSync(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).
     // On a plugin-wired repo the plugin vendors its own engine copy (ADR-0045), so an
     // unset bundle dir is healthy, not a gap.

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,
+    };
+}

package/dist/storage.js

@@ -8,6 +8,7 @@ import { basename, dirname, join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { createHash } from 'node:crypto';
 import { storageBackend } from './backend.js';
+import { journalAppend } from './journal.js';
 import { normalizeEntry } from './validate.js';
 export function isTombstone(r) {
     return r.deleted === true;
@@ -51,7 +52,15 @@ export function defaultProject() {
 //     GUARANTEED side-effect (mykb L11; ADR-0014) — policy, so it lives here,
 //     above the backend's raw append. ---
 export function appendRecord(rec) {
-    storageBackend().append(rec);
+    const be = storageBackend();
+    // ADR-0064: journal-first untracked mirror — the durability floor for the
+    // window between this append and the next brain commit. JSONL-fs only: the
+    // journal is the file tier's crash net; a non-fs backend owns its own
+    // durability, and its location() is not a filesystem path (mirroring it
+    // materialized a literal 'memory:/test/.journal' dir in the cwd).
+    if (be.name === 'jsonl-fs')
+        journalAppend(be.location(), rec);
+    be.append(rec);
     writeMeta();
 }
 // ADR-0040: the exclusive section for read-decide-append engine ops, provided by

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viloforge/vfkb",
-  "version": "0.2.3",
+  "version": "0.4.0",
   "description": "ViloForge KnowledgeBase (vfkb) — per-project knowledge substrate for the ViloForge software factory. Greenfield TypeScript.",
   "type": "module",
   "main": "dist/engine.js",