@viloforge/vfkb 0.2.1

package/dist/engine.js

@@ -0,0 +1,668 @@
+// vfkb engine facade. The storage kernel lives in storage.ts (append-only JSONL,
+// tombstones, LWW, content-hash freshness — ADR-0013/0014) and the read index in
+// index-store.ts. This module is: schema defaults, the injection FILTER (ADR-0005),
+// the tiered Heuristic reranker (ADR-0012), the budgeted render (ADR-0015), capture.
+// Pure Node stdlib, ZERO runtime deps.
+import { randomBytes } from 'node:crypto';
+import { appendRecord, materialize, readRecords, lastMalformed, withExclusive, contextSpinePath, readContextSpine, writeContextSpine, defaultProject, } from './storage.js';
+import { selectIndex } from './index-store.js';
+import { testHoldForRace } from './lock.js';
+import { assertNoSecrets } from './secrets.js';
+import { tally } from './counters.js';
+import { SessionState } from './session.js';
+export { brainDir } from './storage.js';
+export const SESSION_BUDGET_CHARS = 10_000; // Claude Code additionalContext cap (ADR-0015).
+// Fluid types are editable (last-write-wins); the decision family is immutable
+// (supersede-only) — ADR-0004. RFC = a `proposed` decision (ADR-0007),
+// constitutional = a flagged decision (ADR-0008) — both are the `decision` type,
+// not new types.
+const FLUID_TYPES = new Set(['fact', 'gotcha', 'pattern', 'link']);
+const DECISION_FAMILY = new Set(['decision']);
+export function isDecisionFamily(type) {
+    return DECISION_FAMILY.has(type);
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+function newId() {
+    return randomBytes(6).toString('hex');
+}
+// --- Derived trust (ADR-0011): NOT a stored field. ---
+export function deriveTrust(role) {
+    if (role === 'human')
+        return 'operator';
+    if (role === 'init' || role === 'import')
+        return 'import';
+    return 'agent'; // architect | pm | executor | judge
+}
+// Fold a `--why`/`why=` rationale into the entry text (gotcha 91338268: the envelope
+// has no `why` field, so rationale only persists in the text). No-op if blank or if a
+// "Why:" line is already present. Matches the import convention (mykb why → "Why: …").
+export function foldWhy(text, why) {
+    const w = (why ?? '').trim();
+    if (!w)
+        return text;
+    if (/(^|\n)\s*why:/i.test(text))
+        return text;
+    return `${text}\n\nWhy: ${w}`;
+}
+export function addEntry(type, text, opts = {}) {
+    text = foldWhy(text, opts.why);
+    assertNoSecrets(text); // no-secrets write-time lint (D6e) — throws on a planted secret
+    const role = opts.role ?? 'executor';
+    const ts = nowIso();
+    const entry = {
+        id: newId(),
+        type,
+        text,
+        tags: opts.tags ?? [],
+        zone: opts.zone ?? (deriveTrust(role) === 'operator' ? 'established' : 'incoming'),
+        author: { role },
+        refs: opts.supersedes || opts.contradicts?.length
+            ? {
+                supersedes: opts.supersedes,
+                contradicts: opts.contradicts?.length ? opts.contradicts : undefined,
+            }
+            : undefined,
+        why: opts.why?.trim() || undefined, // structural rationale (ADR-0042 §1)
+        provenance: {
+            status: opts.provStatus ?? (deriveTrust(role) === 'operator' ? 'verified' : 'unverified'),
+            date: ts,
+            origin: opts.origin,
+        },
+        validity: { valid_from: ts, valid_until: opts.validUntil },
+        // default a brand-new decision to `proposed` (an RFC, ADR-0007) unless told.
+        status: opts.status ?? (isDecisionFamily(type) ? 'proposed' : undefined),
+        constitutional: isDecisionFamily(type) ? opts.constitutional : undefined,
+        session_id: opts.sessionId ?? process.env.KB_SESSION_ID ?? undefined,
+        created: ts,
+        updated: ts,
+    };
+    appendRecord(entry);
+    return entry;
+}
+export function readAll() {
+    return materialize();
+}
+// Fluid-type edit (last-write-wins). Throws on the decision family (ADR-0004:
+// decisions/RFC/constitutional are immutable — supersede, don't edit).
+export function updateEntry(id, patch) {
+    return withExclusive(() => {
+        const cur = readAll().find((e) => e.id === id);
+        if (!cur)
+            throw new Error(`no such entry: ${id}`);
+        if (!FLUID_TYPES.has(cur.type)) {
+            throw new Error(`entry ${id} is a ${cur.type} (decision family) — immutable; supersede it, don't edit (ADR-0004)`);
+        }
+        const next = { ...cur, ...patch, updated: nowIso() };
+        appendRecord(next);
+        return next;
+    });
+}
+// Non-destructive provenance re-stamp (D-iii / ADR-0024). Flips the trust label
+// (provenance.status) while leaving the entry's TEXT byte-identical — the curator's
+// never-rewrite Brake stays intact. This is how corroborated promotion makes its trust
+// elevation AGENT-OBSERVABLE (the ✓ glyph + the verified-only filter), not just a zone
+// move. Deliberately metadata-only: it does not touch text/zone/status.
+export function setProvenanceStatus(id, status) {
+    return withExclusive(() => {
+        const cur = readAll().find((e) => e.id === id);
+        if (!cur)
+            throw new Error(`no such entry: ${id}`);
+        const next = {
+            ...cur,
+            provenance: { ...cur.provenance, status },
+            updated: nowIso(),
+        };
+        appendRecord(next);
+        return next;
+    });
+}
+// Delete = additive tombstone (never rewrites; merge=union safe).
+export function deleteEntry(id) {
+    appendRecord({ id, deleted: true, updated: nowIso() });
+}
+// Deterministic rebuild of the read index from JSONL (ADR-0014).
+export function rebuild() {
+    const ix = selectIndex();
+    ix.rebuild();
+    return ix;
+}
+export function getIndex() {
+    return selectIndex();
+}
+export function buildContextMap() {
+    const all = readAll();
+    const superseded = supersededIds(all);
+    const byType = { fact: 0, decision: 0, gotcha: 0, pattern: 0, link: 0 };
+    const byZone = { incoming: 0, established: 0, archive: 0 };
+    const decisions = { accepted: 0, proposed: 0, superseded: 0, deprecated: 0, constitutional: 0 };
+    const tagCounts = new Map();
+    for (const e of all) {
+        byType[e.type]++;
+        byZone[e.zone]++;
+        for (const t of e.tags)
+            tagCounts.set(t, (tagCounts.get(t) ?? 0) + 1);
+        if (isDecisionFamily(e.type)) {
+            const eff = effectiveStatus(e, superseded);
+            if (eff === 'accepted')
+                decisions.accepted++;
+            else if (eff === 'proposed')
+                decisions.proposed++;
+            else if (eff === 'superseded')
+                decisions.superseded++;
+            else if (eff === 'deprecated')
+                decisions.deprecated++;
+            if (e.constitutional && eff === 'accepted')
+                decisions.constitutional++;
+        }
+    }
+    const topTags = [...tagCounts.entries()]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .slice(0, 8)
+        .map(([tag, n]) => ({ tag, n }));
+    return { total: all.length, byType, byZone, decisions, topTags, malformed: lastMalformed().length };
+}
+export function renderContextMap(map = buildContextMap()) {
+    const types = Object.entries(map.byType)
+        .filter(([, n]) => n > 0)
+        .map(([t, n]) => `${t} ${n}`)
+        .join(' · ');
+    const d = map.decisions;
+    const decLine = `decisions: ${d.accepted} accepted (${d.constitutional} constitutional)` +
+        (d.proposed ? ` · ${d.proposed} proposed` : '') +
+        (d.superseded ? ` · ${d.superseded} superseded` : '') +
+        (d.deprecated ? ` · ${d.deprecated} deprecated` : '');
+    const tags = map.topTags.length ? map.topTags.map((t) => `${t.tag}(${t.n})`).join(' ') : '(none)';
+    return (`<vfkb-map>\n` +
+        `${map.total} entries · ${types} · zones: established ${map.byZone.established}/incoming ${map.byZone.incoming}\n` +
+        `${decLine}\n` +
+        `top tags: ${tags}\n` +
+        (map.malformed ? `⚠ ${map.malformed} malformed record${map.malformed === 1 ? '' : 's'} excluded (ADR-0042 — inspect the brain file)\n` : '') +
+        `pull more: search <terms> · filter by type/tag/status/author\n` +
+        `</vfkb-map>`);
+}
+// =========================================================================
+// Decision family (ADR-0004/0007/0008/0009). Decisions are immutable in their
+// CONTENT (text/rationale) — superseded, not edited. But lifecycle/identity
+// fields the ENGINE manages (status, refs.supersedes, adr_no) may change via
+// the dedicated operations below, which preserve the content verbatim.
+// =========================================================================
+// Supersede a decision with a new one (additive edge — the old is never edited).
+// The old entry's effective status becomes `superseded`, derived from the edge.
+// Read-decide-append → runs under the brain lock (ADR-0040): two concurrent
+// supersedes of the same target must not both act on the pre-edge snapshot and
+// fork the lineage — the second sees the first's edge and is rejected.
+export function supersede(oldId, text, opts = {}) {
+    return withExclusive(() => {
+        const all = readAll();
+        const old = all.find((e) => e.id === oldId);
+        if (!old)
+            throw new Error(`no such entry: ${oldId}`);
+        if (!isDecisionFamily(old.type)) {
+            throw new Error(`entry ${oldId} is not a decision — fluid types are edited, not superseded`);
+        }
+        if (supersededIds(all).has(oldId)) {
+            throw new Error(`entry ${oldId} is already superseded — superseding it again would fork the lineage; ` +
+                'supersede its live successor instead');
+        }
+        testHoldForRace(); // test-only seam between the read and the append (ADR-0040 DoD)
+        return addEntry('decision', text, {
+            role: opts.role ?? 'human',
+            why: opts.why,
+            tags: opts.tags,
+            status: opts.status ?? 'accepted',
+            constitutional: opts.constitutional ?? old.constitutional,
+            supersedes: oldId,
+            sessionId: opts.sessionId,
+        });
+    });
+}
+// Lifecycle transition (proposed→accepted→deprecated). Appends a new version with
+// the SAME content but a new status. Cannot set `superseded` (that is edge-derived),
+// and refuses to alter `text` (content-immutability — use supersede() instead).
+export function transitionDecision(id, status) {
+    if (status === 'superseded') {
+        throw new Error('`superseded` is derived from a supersession edge — use supersede()');
+    }
+    return withExclusive(() => {
+        const cur = readAll().find((e) => e.id === id);
+        if (!cur)
+            throw new Error(`no such entry: ${id}`);
+        if (!isDecisionFamily(cur.type)) {
+            throw new Error(`entry ${id} is not a decision — use updateEntry() for fluid types`);
+        }
+        testHoldForRace();
+        const next = { ...cur, status, updated: nowIso() };
+        appendRecord(next);
+        return next;
+    });
+}
+// The set of ids superseded by some live entry (the supersession edges).
+export function supersededIds(entries = readAll()) {
+    const s = new Set();
+    for (const e of entries)
+        if (e.refs?.supersedes)
+            s.add(e.refs.supersedes);
+    return s;
+}
+// Effective status folds the supersession edge in: an entry pointed at by a live
+// supersession is `superseded` regardless of its own stored status.
+export function effectiveStatus(e, superseded = supersededIds()) {
+    if (superseded.has(e.id))
+        return 'superseded';
+    return e.status;
+}
+// Stamp human ADR ordinals (ADR-0009). Assigns the next monotonic `adr_no` to live
+// decision-family entries lacking one, in `created` order. Idempotent: already-
+// stamped entries keep their number. Models the engine's merge-to-main step (main
+// is serialized + sole-writer → monotonic, no collision).
+export function stampOrdinals() {
+    const live = readAll();
+    let max = 0;
+    for (const e of live)
+        if (typeof e.adr_no === 'number' && e.adr_no > max)
+            max = e.adr_no;
+    // "Creation order" = append-log order (first appearance in the JSONL). This is
+    // the ground-truth write order, immune to same-millisecond `created` collisions.
+    const firstSeen = new Map();
+    readRecords().forEach((r, i) => {
+        if (!firstSeen.has(r.id))
+            firstSeen.set(r.id, i);
+    });
+    const unstamped = live
+        .filter((e) => isDecisionFamily(e.type) && typeof e.adr_no !== 'number')
+        .sort((a, b) => (firstSeen.get(a.id) ?? 0) - (firstSeen.get(b.id) ?? 0));
+    let stamped = 0;
+    for (const e of unstamped) {
+        appendRecord({ ...e, adr_no: ++max, updated: nowIso() });
+        stamped++;
+    }
+    return stamped;
+}
+// Derive the always-injected Constitution (ADR-0008): live, accepted, constitutional
+// decisions that are not superseded/deprecated.
+export function deriveConstitution() {
+    const live = readAll();
+    const superseded = supersededIds(live);
+    return live
+        .filter((e) => isDecisionFamily(e.type) &&
+        e.constitutional === true &&
+        effectiveStatus(e, superseded) === 'accepted')
+        .sort((a, b) => (a.adr_no ?? 1e9) - (b.adr_no ?? 1e9));
+}
+// --- Injection filter (ADR-0005 + ADR-0011 valid_until). Hard gate. ---
+export function isInjectable(e, today = nowIso().slice(0, 10), superseded) {
+    if (e.zone === 'archive')
+        return false;
+    if (superseded?.has(e.id))
+        return false; // superseded by a live edge (ADR-0004)
+    if (e.status === 'deprecated' || e.status === 'superseded')
+        return false;
+    if (e.provenance.status === 'stale' || e.provenance.status === 'expired')
+        return false;
+    if (e.validity.valid_until && e.validity.valid_until.slice(0, 10) < today)
+        return false;
+    return true; // unverified entries ARE injected (labelled) per ADR-0005.
+}
+// --- Heuristic reranker (ADR-0012). Soft sort over the survivors of the filter. ---
+const TYPE_WEIGHT = {
+    pattern: 5, // patterns + gotchas first (L3 tiered render)
+    gotcha: 5,
+    decision: 4,
+    fact: 2,
+    link: 1,
+};
+function withinTierScore(e) {
+    let s = 0;
+    if (deriveTrust(e.author.role) === 'operator')
+        s += 3; // operator-trust boost
+    if (e.provenance.status === 'verified')
+        s += 1;
+    return s;
+}
+// Tiered sort (L3): TYPE tier is the PRIMARY key (patterns/gotchas first), so
+// trust/recency reorder *within* a tier but never lift a fact above a pattern.
+// This is the correct order for the *injection* bundle and for non-text listing,
+// where there is no query and thus no relevance signal. For an explicit text
+// SEARCH, relevance is primary and this comparator is only the tiebreak among
+// equally-relevant entries (ADR-0012 — the read layer threads the score through).
+export function heuristicCompare(a, b) {
+    const tier = TYPE_WEIGHT[b.type] - TYPE_WEIGHT[a.type];
+    if (tier !== 0)
+        return tier;
+    const within = withinTierScore(b) - withinTierScore(a);
+    if (within !== 0)
+        return within;
+    return b.updated.localeCompare(a.updated); // recency tiebreak
+}
+export function rerank(entries) {
+    return [...entries].sort(heuristicCompare);
+}
+// --- Tier-A session-start bundle (ADR-0015), budgeted to 10k chars. ---
+function trustGlyph(e) {
+    const t = deriveTrust(e.author.role);
+    const v = e.provenance.status === 'verified' ? '✓' : e.provenance.status === 'unverified' ? '⚠' : '';
+    return `${v}${t}`;
+}
+// --- Last-handoff pin (ADR-0049): the read side of Track 8 (ADR-0033). Selection is a
+// filter, not an inference: newest-by-`updated` among injectable entries tagged
+// handoff/next. A superseded/archived/expired handoff ages out via isInjectable.
+const HANDOFF_PIN_CAP_CHARS = 2000; // bound the pinned section; the live 07-08 handoff ≈ 1.5k
+export function latestHandoff(all = readAll(), today = nowIso().slice(0, 10), superseded = supersededIds(all)) {
+    let latest = null;
+    for (const e of all) {
+        if (!(e.tags.includes('handoff') || e.tags.includes('next')))
+            continue;
+        if (!isInjectable(e, today, superseded))
+            continue;
+        if (!latest) {
+            latest = e;
+            continue;
+        }
+        // Total order (adversarial-review finding): updated, then created, then append
+        // position — `>= 0` keeps the LATER entry on a full timestamp tie, which in an
+        // append-only log is the newest write. A strict `>` here silently favored the
+        // oldest entry on same-millisecond stamps (bulk adds, imports).
+        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);
+    const superseded = supersededIds(all);
+    const injectable = rerank(all.filter((e) => isInjectable(e, today, superseded)));
+    const header = `<vfkb-context project="${project}">\n`;
+    const footer = `\n</vfkb-context>`;
+    let body = '';
+    // Constitution always leads (ADR-0008): accepted, constitutional, non-superseded
+    // decisions, injected first and never budget-dropped.
+    const constitution = deriveConstitution();
+    if (constitution.length > 0) {
+        body += '## Constitution (always applies)\n';
+        for (const c of constitution) {
+            const n = typeof c.adr_no === 'number' ? `ADR-${String(c.adr_no).padStart(4, '0')} ` : '';
+            body += `- [${n}constitutional] ${c.text}\n`;
+        }
+        body += '\n';
+    }
+    const constitutionalIds = new Set(constitution.map((c) => c.id));
+    // Last handoff (ADR-0049): pinned after the Constitution, never budget-dropped —
+    // otherwise the ADR-0012 type tiers budget-drop every fact under enough gotchas,
+    // and the Track 8 handoff is exactly the entry a fresh session cannot lose.
+    // Bounded pin (adversarial-review finding): a handoff is free text and may be
+    // machine-generated (the B2 fallback enumerates entries), so unlike the short
+    // curated Constitution it must not unbound the render — truncate at the cap and
+    // name the id so the rest stays one kb_get away. A constitutional handoff is
+    // already pinned in the Constitution section; don't render it twice.
+    const handoff = latestHandoff(all, today, superseded);
+    if (handoff && !constitutionalIds.has(handoff.id)) {
+        const text = handoff.text.length > HANDOFF_PIN_CAP_CHARS
+            ? `${handoff.text.slice(0, HANDOFF_PIN_CAP_CHARS)}… (truncated — kb_get ${handoff.id} for the rest)`
+            : handoff.text;
+        body += `## Last handoff\n- [${handoff.type} ${trustGlyph(handoff)}] ${text}\n\n`;
+    }
+    // Context Map (ADR-0006): the navigational index, always injected, never dropped.
+    body += renderContextMap() + '\n\n';
+    let dropped = 0;
+    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
+        const line = `- [${e.type} ${trustGlyph(e)}] ${e.text}\n`;
+        if (header.length + body.length + line.length + footer.length > budget) {
+            dropped++;
+            continue;
+        }
+        body += line;
+    }
+    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;
+    }
+    return header + body + footer;
+}
+// --- Project context document (D-ii / ADR-0025 ← RFC-007): the agent's first read.
+// An ASSEMBLED artifact: the AUTHORED narrative spine (<brain>/context.md — job-to-be-done,
+// architecture, tech profile, conventions, Vision/Taste per ADR-0010) STITCHED with DERIVED
+// sections vfkb already owns (Constitution ADR-0008, Context Map ADR-0006, load-bearing
+// decisions, links). The derived half is rendered live so it never drifts into a stale
+// hand-copy (the RFC-005 anti-drift lesson). Read ON-DEMAND via kb_context — NOT auto-injected
+// (session-start keeps the budget-bounded map+resume; ADR-0015). No new entry type.
+const CONTEXT_SPINE_SCAFFOLD = `# Project Context
+
+## Job-to-be-done
+<what this project is — the job it does for its users>
+
+## Architecture
+<the shape of the system: key components and how they fit>
+
+## Tech profile
+<languages, frameworks, runtimes, datastores>
+
+## Conventions
+<load-bearing conventions an agent must follow>
+
+## Vision / Taste
+<the taste/voice this project holds to (ADR-0010)>
+`;
+// Scaffold the authored spine if absent (onboarding D-O8). Idempotent: never overwrites
+// an existing spine.
+export function initContextSpine() {
+    const p = contextSpinePath();
+    if (readContextSpine() !== null)
+        return { created: false, path: p };
+    writeContextSpine(CONTEXT_SPINE_SCAFFOLD);
+    return { created: true, path: p };
+}
+export function renderContext(project = defaultProject()) {
+    const all = readAll();
+    const sup = supersededIds(all);
+    const out = [`# ${project} — project context`, ''];
+    const spine = readContextSpine();
+    if (spine) {
+        out.push('<!-- authored spine (architect-maintained) -->', spine, '');
+    }
+    else {
+        out.push('_(no authored context spine yet — run `vfkb context init` to scaffold `context.md`. The derived sections below are always current.)_', '');
+    }
+    // Derived sections — stitched live from the brain so they never drift from a hand-copy.
+    const constitution = deriveConstitution();
+    if (constitution.length > 0) {
+        out.push('## Constitution (derived — always applies)');
+        for (const c of constitution) {
+            const n = typeof c.adr_no === 'number' ? `ADR-${String(c.adr_no).padStart(4, '0')} ` : '';
+            out.push(`- [${n}constitutional] ${c.text}`);
+        }
+        out.push('');
+    }
+    out.push('## Map (derived)', renderContextMap(), '');
+    const decisions = all.filter((e) => e.type === 'decision' && !e.constitutional && effectiveStatus(e, sup) === 'accepted');
+    if (decisions.length > 0) {
+        out.push('## Load-bearing decisions (derived)');
+        for (const d of decisions) {
+            const n = typeof d.adr_no === 'number' ? `ADR-${String(d.adr_no).padStart(4, '0')} ` : '';
+            out.push(`- [${n}decision] ${d.text}`);
+        }
+        out.push('');
+    }
+    const links = all.filter((e) => e.type === 'link' && isInjectable(e, undefined, sup));
+    if (links.length > 0) {
+        out.push('## Links & docs (derived)');
+        for (const l of links)
+            out.push(`- ${l.text}`);
+        out.push('');
+    }
+    return out.join('\n').trim() + '\n';
+}
+// --- Naive flat dump (NOT used in production). Represents a mykb-v1-style memory:
+//     all live entries in load/creation order, flat, NO supersession/stale filter,
+//     NO rerank, budget-cut from the end (so the newest can be dropped). Used only
+//     by the L4 scenario harness as the contrast baseline. ---
+export function renderNaiveDump(project = defaultProject(), budget = SESSION_BUDGET_CHARS, limit) {
+    let entries = readAll()
+        .filter((e) => e.zone !== 'archive')
+        .sort((a, b) => a.created.localeCompare(b.created)); // oldest first (load order)
+    // A `limit` reproduces the Stark-FQDN incident faithfully: a load-order memory
+    // truncated to a token budget keeps the OLDER entries and drops the newest
+    // correction — exactly mykb v1's failure mode.
+    if (typeof limit === 'number')
+        entries = entries.slice(0, limit);
+    const header = `<context project="${project}">\n`;
+    const footer = `\n</context>`;
+    let body = '';
+    for (const e of entries) {
+        const line = `- ${e.text}\n`;
+        if (header.length + body.length + line.length + footer.length > budget)
+            break; // drops newest
+        body += line;
+    }
+    return header + body + footer;
+}
+// vfkb's own knowledge tools (bare `kb_*` or harness-namespaced `mcp__vfkb__*`).
+// Capturing an agent reading/writing its own brain is self-pollution — the noise
+// then gets re-surfaced by search/injection. Never capture these.
+function isOwnKnowledgeTool(name) {
+    const n = name.toLowerCase();
+    return n.startsWith('kb_') || n.includes('vfkb');
+}
+const RESULT_SUMMARY_CAP = 120;
+export function classifyToolOutcome(result) {
+    if (result === undefined || result === null)
+        return { outcome: 'ok', summary: '' };
+    if (typeof result === 'object') {
+        const r = result;
+        const exit = typeof r.exit_code === 'number' ? r.exit_code
+            : typeof r.exitCode === 'number' ? r.exitCode
+                : undefined;
+        const isErr = r.isError === true || r.error != null || (typeof r.stderr === 'string' && r.stderr.trim() !== '') ||
+            (exit !== undefined && exit !== 0);
+        const basis = r.error ?? r.stderr ?? r.message ?? r.result ?? r;
+        const summary = (typeof basis === 'string' ? basis : JSON.stringify(basis)).slice(0, RESULT_SUMMARY_CAP);
+        return { outcome: isErr ? 'error' : 'ok', summary };
+    }
+    const s = String(result).slice(0, RESULT_SUMMARY_CAP);
+    const isErr = /(^|\s)(error|failed|failure|exception|denied|traceback|refused)\b/i.test(s);
+    return { outcome: isErr ? 'error' : 'ok', summary: s };
+}
+export function captureToolCall(ev) {
+    if (!ev.tool_name)
+        return null;
+    if (isOwnKnowledgeTool(ev.tool_name))
+        return null;
+    const inputSummary = typeof ev.tool_input === 'object' && ev.tool_input
+        ? JSON.stringify(ev.tool_input).slice(0, 200)
+        : String(ev.tool_input ?? '');
+    const { outcome, summary } = classifyToolOutcome(ev.tool_result);
+    const text = `Tool ${ev.tool_name} invoked${inputSummary ? `: ${inputSummary}` : ''}` +
+        (summary ? ` → ${outcome}: ${summary}` : '');
+    try {
+        return addEntry('fact', text, {
+            role: 'executor',
+            tags: ['captured', `capture:${outcome}`],
+            provStatus: 'unverified',
+            origin: { kind: 'tool_call', tool: ev.tool_name, call_id: ev.call_id },
+            sessionId: ev.session_id,
+        });
+    }
+    catch {
+        // no-secrets lint (or any write error) → skip the capture, never crash the harness.
+        return null;
+    }
+}
+// Ids of entries currently eligible for injection (filter + supersession applied).
+export function currentInjectableIds() {
+    const all = readAll();
+    const sup = supersededIds(all);
+    return all.filter((e) => isInjectable(e, undefined, sup)).map((e) => e.id);
+}
+// --- Per-turn delta injection (Tier C, Pi-only — ADR-0015). Inject only entries
+//     not already injected this session (dedup via SessionState, L4). Returns ''
+//     when there is nothing new this turn. ---
+export function renderContextDelta(session, project = defaultProject()) {
+    const all = readAll();
+    const superseded = supersededIds(all);
+    const fresh = rerank(all.filter((e) => isInjectable(e, undefined, superseded))).filter((e) => !session.isInjected(e.id));
+    session.bumpTurn();
+    if (fresh.length === 0)
+        return '';
+    session.markInjected(fresh.map((e) => e.id));
+    const lines = fresh.map((e) => `- [${e.type} ${trustGlyph(e)}] ${e.text}`).join('\n');
+    return `<vfkb-context-delta project="${project}">\n${lines}\n</vfkb-context-delta>`;
+}
+// =========================================================================
+// Session continuity (ADR-0020 / RFC-005) — vfkb's knowledge half of the
+// vtf/vfkb seam. The resume DIGEST is DERIVED from a session record's signals
+// against the LIVE brain at render time, never a stored prose blob — so it
+// cannot go stale (the failure that opened this work). The "Resume" view is a
+// Tier-A render: the prior-session digest + the live knowledge bundle, both
+// re-derived from ground truth and budgeted to the 10k cap.
+// =========================================================================
+// Entries created within a session's [startedAt, lastAt] window — recomputed from
+// the live brain, so a since-deleted/tombstoned entry never reappears (anti-stale).
+function sessionWindow(all, from, to) {
+    const added = all.filter((e) => e.created >= from && e.created <= to);
+    const superseded = added.filter((e) => e.refs?.supersedes); // each new edge = one supersession in-window
+    return { added, superseded };
+}
+const DIGEST_LESSON_CAP = 5; // bound the learned-lessons section in the digest
+// The auto-distilled `incoming` lessons of a session window (M3 / ADR-0020 Phase B):
+// candidate gotchas the distiller wrote (tag `distilled`, still incoming = unverified).
+// DERIVED from the live brain — a lesson later promoted (zone≠incoming) or archived drops
+// out on the next render, so this can no more go stale than the M1 counts can.
+function distilledLessons(added) {
+    return added
+        .filter((e) => e.zone === 'incoming' && e.tags.includes('distilled'))
+        .sort((a, b) => b.created.localeCompare(a.created)); // newest first
+}
+// Render a single session record as a derived digest. Observed facts (added/
+// superseded counts + distilled candidate lessons) come from the live brain; the note +
+// caller signals are labelled ASSERTED (verified-vs-asserted — the discipline whose
+// absence produced the stale-L4 claim).
+export function renderResumeDigest(rec, all = readAll()) {
+    const { added, superseded } = sessionWindow(all, rec.startedAt, rec.lastAt);
+    const when = (rec.lastAt ?? '').slice(0, 16).replace('T', ' ');
+    const lines = [
+        `## Resume — last recorded session (${when}Z)`,
+        `- observed (re-derived from the brain): ${added.length} entries added, ` +
+            `${superseded.length} superseded, ${rec.injectedIds?.length ?? 0} injected, ` +
+            `${rec.capturedIds?.length ?? 0} captured, ${rec.turnCount ?? 0} turns`,
+    ];
+    // M3: the real learned lessons, not just counts — auto-distilled candidates, trust-
+    // labelled (ADR-0005) so a resuming session treats them as unverified, not as fact.
+    const lessons = distilledLessons(added);
+    if (lessons.length > 0) {
+        lines.push(`- learned (auto-distilled this session — candidates, verify before trusting):`);
+        for (const e of lessons.slice(0, DIGEST_LESSON_CAP)) {
+            const net = tally(e.id).net;
+            const corr = net > 0 ? ` (+${net} corroborating)` : '';
+            lines.push(`  - [${e.type} ${trustGlyph(e)}] ${e.text}${corr}`);
+        }
+        if (lessons.length > DIGEST_LESSON_CAP) {
+            lines.push(`  - …and ${lessons.length - DIGEST_LESSON_CAP} more (search tag:distilled)`);
+        }
+    }
+    if (rec.note)
+        lines.push(`- next (ASSERTED by operator, unverified): ${rec.note}`);
+    for (const s of rec.signals ?? [])
+        lines.push(`- ${s.label} (ASSERTED by caller): ${s.value}`);
+    return lines.join('\n');
+}
+// The "Resume" render (ADR-0020 pt 5): the most recent PRIOR session's digest +
+// the live Tier-A knowledge bundle, budgeted to the 10k cap. Both halves are
+// derived from ground truth at call time.
+export function renderResume(project = defaultProject(), session = SessionState.load()) {
+    const all = readAll();
+    const prior = SessionState.records().find((r) => r.sessionId !== session.sessionId);
+    const digest = prior
+        ? renderResumeDigest(prior, all)
+        : '## Resume\n- (first recorded session — no prior continuity)';
+    const head = `<vfkb-resume project="${project}">\n${digest}\n</vfkb-resume>`;
+    const bundle = renderContextBundle(project, Math.max(0, SESSION_BUDGET_CHARS - head.length - 1));
+    return `${head}\n${bundle}`;
+}