@viloforge/vfkb 0.2.1

package/dist/counters.js

@@ -0,0 +1,61 @@
+// Counter/signal stream (M2b — ADR-0021 pt 3/4). Helpful/harmful tallies keyed by
+// entry id, recorded as an APPEND-ONLY stream and AGGREGATED AT READ — the entry
+// envelope is NEVER edited (deltas-not-rewrites; counters fight the immutability model
+// if stored on the entry). This is the evidence that drives CORROBORATED promotion:
+// auto-distill alone cannot mint trusted knowledge (ADR-0021 pt 4).
+//
+// Storage (M2b sub-decision a, settled 2026-06-25): OPERATIONAL / gitignored, under
+// <brain>/.signals/counters.jsonl — mirrors <brain>/.sessions. The DURABLE effect
+// (promotion) lands in the committed entries.jsonl SoR; raw tallies are append-only
+// agent-trust telemetry that survives container restart but is not committed. Keeps the
+// brain the single committed source of truth.
+import { appendFileSync, mkdirSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { brainDir } from './storage.js';
+function signalsFile() {
+    return join(brainDir(), '.signals', 'counters.jsonl');
+}
+// Append a single signal. Never reads/mutates the entry — purely additive.
+export function recordSignal(entryId, kind, source) {
+    const sig = { entryId, kind, at: new Date().toISOString(), source };
+    mkdirSync(join(brainDir(), '.signals'), { recursive: true });
+    appendFileSync(signalsFile(), JSON.stringify(sig) + '\n', 'utf8');
+    return sig;
+}
+export function readSignals() {
+    const f = signalsFile();
+    if (!existsSync(f))
+        return [];
+    return readFileSync(f, 'utf8')
+        .split('\n')
+        .filter((l) => l.trim().length > 0)
+        .map((l) => JSON.parse(l));
+}
+// Aggregate-at-read for one entry.
+export function tally(entryId, signals = readSignals()) {
+    let helpful = 0;
+    let harmful = 0;
+    for (const s of signals) {
+        if (s.entryId !== entryId)
+            continue;
+        if (s.kind === 'helpful')
+            helpful++;
+        else if (s.kind === 'harmful')
+            harmful++;
+    }
+    return { helpful, harmful, net: helpful - harmful };
+}
+// Aggregate-at-read for the whole stream.
+export function tallies(signals = readSignals()) {
+    const out = new Map();
+    for (const s of signals) {
+        const t = out.get(s.entryId) ?? { helpful: 0, harmful: 0, net: 0 };
+        if (s.kind === 'helpful')
+            t.helpful++;
+        else if (s.kind === 'harmful')
+            t.harmful++;
+        t.net = t.helpful - t.harmful;
+        out.set(s.entryId, t);
+    }
+    return out;
+}

package/dist/curator.js

@@ -0,0 +1,87 @@
+// ACE curator (ADR-0021 / RFC-006) — the maintenance side of auto-distill.
+// DELTAS + COUNTERS, NEVER REWRITES (IMPL-PLAN L12 context-collapse). Every op here
+// acts ONLY through the engine's non-destructive primitives and leaves the entry's
+// TEXT byte-identical. That invariant is the load-bearing safety rail and is enforced
+// by the structural Brake in test/curator.test.ts (any in-place text edit fails the
+// build) — because a prose "don't rewrite" rule an LLM curator will eventually ignore.
+//
+// M2a ships the curator ops + the Brake + the retrieval-quality regression. The
+// distiller (write side) and the counter/signal stream that DRIVES promotion are M2b.
+import { readAll, updateEntry, setProvenanceStatus, transitionDecision, isDecisionFamily } from './engine.js';
+import { tally } from './counters.js';
+function get(id) {
+    const e = readAll().find((x) => x.id === id);
+    if (!e)
+        throw new Error(`no such entry: ${id}`);
+    return e;
+}
+// promote: an `incoming` candidate becomes trusted-zone (`established`). Fluid types
+// move zone; a decision's standing is its status (transitionDecision), never a zone
+// promotion here. Text is never touched.
+export function promote(id) {
+    const e = get(id);
+    if (isDecisionFamily(e.type)) {
+        throw new Error(`promote() is for fluid types; a decision's standing is its status (use transitionDecision)`);
+    }
+    return updateEntry(id, { zone: 'established' });
+}
+// CORROBORATED promotion (ADR-0021 pt 4): auto-distilled `incoming` knowledge CANNOT be
+// minted into the trusted set on a single distillation — it needs ≥N independent
+// corroborating signals (or a human, who uses the unguarded promote() above). The
+// evidence is the append-only counter stream, aggregated at read; promotion itself is
+// still the same non-destructive zone transition (text never touched). This is the gate
+// that keeps machine extraction from self-promoting.
+export const PROMOTION_THRESHOLD = 2; // net helpful signals required (≥2 corroborations)
+export function eligibleForPromotion(id, threshold = PROMOTION_THRESHOLD) {
+    return tally(id).net >= threshold;
+}
+export function promoteIfCorroborated(id, threshold = PROMOTION_THRESHOLD) {
+    const t = tally(id);
+    if (t.net < threshold) {
+        throw new Error(`entry ${id} is not corroborated (net ${t.net} < ${threshold}) — auto-distill alone cannot mint trusted knowledge (ADR-0021); needs more signals or a human promote`);
+    }
+    // D-iii (ADR-0024): the trust elevation must be AGENT-OBSERVABLE, not just a zone move.
+    // Corroboration-by-recurrence is the independent "second agent" signal §3.6 requires
+    // (the recurrence, not the author, asserts it) — so promotion both moves the zone AND
+    // re-stamps provenance verified, putting the lesson into the verified-only view + the ✓
+    // glyph. Text stays byte-identical (the never-rewrite Brake holds — setProvenanceStatus
+    // touches only metadata).
+    promote(id);
+    return setProvenanceStatus(id, 'verified');
+}
+// archive: retire a stale/noise entry out of the injection set. Fluid → zone
+// `archive`; decision → `deprecated` (status). Text is never touched.
+export function archive(id) {
+    const e = get(id);
+    if (isDecisionFamily(e.type))
+        return transitionDecision(id, 'deprecated');
+    return updateEntry(id, { zone: 'archive' });
+}
+// mergeDuplicate: keep `winnerId`, retire the fluid duplicate `loserId` by archiving
+// it + tagging the edge so the merge is auditable. NEITHER entry's text is rewritten.
+// Decisions are merged by an explicit supersede() edge, never here.
+export function mergeDuplicate(loserId, winnerId) {
+    const loser = get(loserId);
+    get(winnerId); // winner must exist
+    if (isDecisionFamily(loser.type)) {
+        throw new Error(`merge a decision via supersede(), not the curator`);
+    }
+    const tags = [...new Set([...loser.tags, `merged-into:${winnerId}`])];
+    return updateEntry(loserId, { zone: 'archive', tags });
+}
+export function findLexicalDuplicates(entries = readAll()) {
+    const norm = (t) => t.toLowerCase().replace(/\s+/g, ' ').trim();
+    const seen = new Map(); // normalized text → first (winner) id
+    const out = [];
+    for (const e of entries) {
+        if (e.zone === 'archive' || isDecisionFamily(e.type))
+            continue;
+        const key = `${e.type}:${norm(e.text)}`;
+        const winner = seen.get(key);
+        if (winner)
+            out.push({ loser: e.id, winner });
+        else
+            seen.set(key, e.id);
+    }
+    return out;
+}

package/dist/distiller.js

@@ -0,0 +1,116 @@
+// Auto-distill write side (M2b — ADR-0021 pt 1 / RFC-006 / D7b). Turns a session's
+// captured signals into CANDIDATE knowledge written ONLY to `incoming` / `unverified` /
+// agent-trust. CONTAINMENT is the safety property: the trusted set is never polluted by
+// machine extraction — a deterministic test asserts every distilled entry is
+// incoming+unverified+agent (test/distiller.test.ts). v1 is a DETERMINISTIC distiller;
+// an optional off-hot-path LLM distiller slots behind the same `Distiller` seam
+// (ADR-0013: opt-in, graceful-degrade, NEVER on the always-on inject path).
+//
+// Signal v1 (the realistic deterministic lesson): a captured tool call whose bounded
+// outcome (M2b sub-decision b) is `error` → a candidate gotcha "Tool X can fail: …".
+// RECURRENCE = CORROBORATION: a second session re-distilling the same error SIGNATURE
+// does NOT duplicate — it records a corroborating counter signal on the existing
+// candidate, which is what drives corroborated promotion (ADR-0021 pt 4).
+import { createHash } from 'node:crypto';
+import { addEntry, readAll } from './engine.js';
+import { recordSignal } from './counters.js';
+const SIG_PREFIX = 'distill-sig:';
+const DISTILLED_TAG = 'distilled';
+// A captured error fact carries tag `capture:error`, origin.tool, and text
+// "Tool X invoked: … → error: <summary>". Normalize the summary to an error CLASS so
+// transient specifics (paths, ids, timestamps) don't fragment the signature.
+function errorClass(summary) {
+    return summary
+        .toLowerCase()
+        .replace(/0x[0-9a-f]+|\b[0-9a-f]{8,}\b/g, '#') // hashes / hex ids
+        .replace(/\b\d+\b/g, '#') // numbers
+        .replace(/[\/\\][^\s'"]+/g, '/path') // file paths
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 80);
+}
+function toolOf(e) {
+    return e.provenance.origin?.kind === 'tool_call' ? e.provenance.origin.tool : 'unknown';
+}
+// The bounded error summary as captured after the "→ error:" marker.
+function summaryOf(e) {
+    const m = e.text.match(/→ error:\s*(.*)$/);
+    return (m ? m[1] : e.text).trim();
+}
+function signature(tool, summary) {
+    const basis = `${tool}::${errorClass(summary)}`;
+    return SIG_PREFIX + createHash('sha256').update(basis).digest('hex').slice(0, 12);
+}
+// Select the captured ERROR facts this distiller acts on. `capturedIds` (a session's
+// signals) restricts the set; absent it, all `capture:error`-tagged live facts. We read
+// from the brain, so already-skipped self-tool calls never appear (the 31f4266 skip
+// holds end-to-end); a defensive guard re-asserts it.
+function errorCaptures(capturedIds, all = readAll()) {
+    const idSet = capturedIds && capturedIds.length ? new Set(capturedIds) : null;
+    return all.filter((e) => e.type === 'fact' &&
+        e.tags.includes('capture:error') &&
+        e.provenance.origin?.kind === 'tool_call' &&
+        !/^kb_|vfkb/i.test(toolOf(e)) &&
+        (!idSet || idSet.has(e.id)));
+}
+// PROPOSE (does not write): the candidate gotchas implied by the error captures, one per
+// distinct signature. Deterministic: same captures → same candidates (stable sigs).
+export function distillCandidates(capturedIds, all = readAll()) {
+    const bySig = new Map();
+    for (const e of errorCaptures(capturedIds, all)) {
+        const tool = toolOf(e);
+        const summary = summaryOf(e);
+        const sig = signature(tool, summary);
+        const cur = bySig.get(sig);
+        if (cur) {
+            cur.sourceIds.push(e.id);
+            continue;
+        }
+        bySig.set(sig, {
+            sig,
+            tool,
+            // Trust lives in the GLYPH/provenance (provStatus below), NOT baked into the immutable
+            // text — so when corroborated promotion re-stamps the entry verified (D-iii/ADR-0024) the
+            // text doesn't contradict the ✓. (Text-Brake-safe: only new distills; never rewrites existing.)
+            text: `Tool ${tool} can fail: ${summary} — auto-distilled from a captured failure`,
+            sourceIds: [e.id],
+            origin: { kind: 'tool_call', tool },
+        });
+    }
+    return [...bySig.values()];
+}
+// WRITE side. For each candidate signature: if no live (non-archive) distilled gotcha
+// with that signature exists, create one in incoming/unverified/agent-trust
+// (CONTAINMENT — explicit, not relying on defaults). If one already exists, this is a
+// recurrence → record a corroborating counter signal, never a duplicate.
+export function distill(capturedIds) {
+    const all = readAll();
+    const existingBySig = new Map();
+    for (const e of all) {
+        if (e.zone === 'archive')
+            continue;
+        const sigTag = e.tags.find((t) => t.startsWith(SIG_PREFIX));
+        if (sigTag)
+            existingBySig.set(sigTag, e);
+    }
+    const created = [];
+    const corroborated = [];
+    for (const c of distillCandidates(capturedIds, all)) {
+        const existing = existingBySig.get(c.sig);
+        if (existing) {
+            recordSignal(existing.id, 'helpful', 'distill:recurrence');
+            corroborated.push(existing.id);
+            continue;
+        }
+        const entry = addEntry('gotcha', c.text, {
+            role: 'executor', // agent-trust (deriveTrust → 'agent')
+            zone: 'incoming', // CONTAINMENT — never the trusted set
+            provStatus: 'unverified', // CONTAINMENT — never verified by machine extraction
+            tags: [DISTILLED_TAG, c.sig, `tool:${c.tool}`],
+            origin: c.origin,
+        });
+        created.push(entry);
+        existingBySig.set(c.sig, entry); // a repeated sig within one pass corroborates, not duplicates
+    }
+    return { created, corroborated };
+}