@phuetz/code-buddy 1.6.1 → 2.0.0

package/dist/memory/collective-knowledge-graph.js

@@ -0,0 +1,1228 @@
+/**
+ * Collective Knowledge Graph (CKG) — Phases 0 + 1.
+ *
+ * A SHARED memory for the agent collective so agent B benefits from what agent A learned.
+ * Today every memory store is machine-/process-local and nothing capitalizes knowledge
+ * across the collective (see plan ~/.claude/plans/wobbly-brewing-ullman.md).
+ *
+ * Phase 0 — unified `remember()` / `recall()` on an APPEND-ONLY JSONL ledger:
+ *  - The ledger is the single shared write path. POSIX O_APPEND makes small-line appends
+ *    atomic, so multiple agents/processes pointing at the same ledger file accumulate
+ *    correctly WITHOUT a database — counting happens at read time by replaying the log.
+ *    This is what makes "B benefits from A" and concurrent-write correctness hold before
+ *    the SQLite backing of Phase 2.
+ *
+ * Phase 1 — bi-temporal supersede + hybrid retrieval:
+ *  - A fact that CHANGES (same logical id, different text) invalidates the old version
+ *    (`validTo` set) and records a `supersedes` edge — Mem0 ADD/UPDATE + Zep bi-temporal.
+ *  - `recallHybrid()` fuses local embeddings (semantic, $0) + keyword + salience, with NO
+ *    LLM at retrieval (Zep). So a PARAPHRASED query still finds the right knowledge.
+ *
+ * Reuses pure helpers: `contentHash` + `computeSalience` (knowledge-graph), `scanForSecrets`/
+ * `redactSecrets` (privacy-lint), `defaultFleetAgentId` (fleet), local embeddings
+ * (`getEmbeddingProvider`). Borrows Code Explorer's id convention `Type:scope:name` and edge
+ * shape `(from, to, type, confidence, reason)`.
+ *
+ * The in-process indexes below remove repeated ledger replay and accelerate common
+ * lexical recall, but dense retrieval is still an exact scan. `buddy-memory/` is
+ * the deliberate long-term scale path; do not duplicate its Rust storage/index
+ * engine in this TypeScript facade.
+ *
+ * @module memory/collective-knowledge-graph
+ */
+import { createHash } from 'node:crypto';
+import { appendFileSync, closeSync, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, statSync, } from 'node:fs';
+import { dirname, join } from 'path';
+import { logger } from '../utils/logger.js';
+import { contentHash, computeSalience } from './knowledge-graph.js';
+import { defaultFleetAgentId } from '../fleet/colab-store.js';
+import { getCodeBuddyHome } from '../utils/codebuddy-home.js';
+import { EmbeddingProvider } from '../embeddings/embedding-provider.js';
+import { BM25Index } from '../search/bm25.js';
+import { cosineSimilarityF32, hybridMmrRank } from './hybrid-mmr.js';
+import { DiskEmbeddingCache } from '../research/paper-qa/disk-embedding-cache.js';
+import { withTimeout } from '../utils/errors.js';
+import { writeFileAtomicSync } from '../utils/atomic-write.js';
+import { canonicalObject, factMatchKey, factRetention, parseFactKey, reconcileFact, FACT_CATEGORIES, } from './ckg-fact-reconciliation.js';
+import { redactRememberInput } from './ckg-redaction.js';
+import { chooseCkgEngine, isCkgSnapshotLoadable, snapshotPathFor } from './ckg-engine-policy.js';
+/** Multilingual embeddings — all-MiniLM (the global default) is English-leaning and misses
+ *  French synonyms (measured: it failed paraphrase recall); this model discriminates French
+ *  cleanly (sim 0.48 vs 0.005 on the same probe). A dedicated instance avoids clobbering
+ *  EnhancedMemory's all-MiniLM singleton. */
+const CKG_EMBEDDING_MODEL = 'Xenova/paraphrase-multilingual-MiniLM-L12-v2';
+/** Cross-agent corroboration: a fact independent agents agree on is more trustworthy
+ *  (Bayesian-trust / corroboration-multiplier idea). Each extra independent source lifts
+ *  confidence toward 1; same-agent repeats don't (no echo-chamber inflation). */
+function corroboratedConfidence(base, distinctAgents) {
+    return Math.max(0, Math.min(0.99, base + 0.12 * Math.max(0, distinctAgents - 1)));
+}
+/** Ranking boost from corroboration (caps at 2× for 6+ independent agents). */
+function corroborationBoost(distinctAgents) {
+    return Math.min(2, 1 + 0.2 * Math.max(0, distinctAgents - 1));
+}
+const SCOPE = 'collective';
+function normalizeName(s) {
+    const normalized = s
+        .toLowerCase()
+        .normalize('NFD')
+        .replace(/\p{M}+/gu, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    if (normalized.length <= 80)
+        return normalized;
+    return `${normalized.slice(0, 71)}-${contentHash('name', normalized).slice(0, 8)}`;
+}
+/** Code-Explorer id convention: `Type:scope:name`. */
+function entityId(type, name) {
+    return `${type}:${SCOPE}:${normalizeName(name)}`;
+}
+function tokenize(s) {
+    return new Set((s.toLowerCase().normalize('NFD').replace(/\p{M}+/gu, '').match(/[a-z0-9]{2,}/g)) ?? []);
+}
+/** Recall-oriented keyword overlap: fraction of query tokens present in the candidate. */
+function keywordOverlap(query, text) {
+    if (query.size === 0)
+        return 0;
+    const cand = tokenize(text);
+    let hit = 0;
+    for (const t of query)
+        if (cand.has(t))
+            hit++;
+    return hit / query.size;
+}
+/**
+ * The collective shared-memory facade. Construct two instances pointing at the SAME
+ * `ledgerPath` to model two agents/processes sharing one collective store.
+ */
+export class CollectiveKnowledgeGraph {
+    ledgerPath;
+    embeddingCachePath;
+    agentId;
+    /** Currently-true nodes (validTo === null), keyed by logical id. */
+    current = new Map();
+    /** Invalidated (superseded) versions, keyed by `id@contentHash`. */
+    superseded = new Map();
+    relations = new Map();
+    /** Model/name/content fingerprint → hot embedding vector. */
+    embCache = new Map();
+    diskEmbCache;
+    /** Common recall keys, maintained while ledger events are applied. */
+    recallTokenIndex = new Map();
+    recallTypeIndex = new Map();
+    recallNameIndex = new Map();
+    indexedEntityTokens = new Map();
+    recallBm25 = new BM25Index();
+    /** Byte position immediately after the last complete JSONL line applied to the view. */
+    ledgerOffset = 0;
+    /** Last observed file metadata, used to make unchanged loads an O(1) stat. */
+    ledgerSize = 0;
+    ledgerMtimeMs = 0;
+    ledgerDevice = null;
+    ledgerInode = null;
+    embeddingCacheLoaded = false;
+    embeddingModel;
+    embedder = null;
+    /** Rust engine client (lazy) — selected by `chooseCkgEngine` (explicit rust, or auto when the
+     *  binary exists and the snapshot is loadable). Writes go to the SAME ledger, so the TS path
+     *  stays consistent and falls back transparently. */
+    engine = null;
+    engineTried = false;
+    constructor(options = {}) {
+        this.ledgerPath = options.ledgerPath ?? join(getCodeBuddyHome(), 'collective', 'ckg-ledger.jsonl');
+        this.embeddingCachePath = `${this.ledgerPath}.emb.jsonl`;
+        this.agentId = options.agentId ?? safeAgentId();
+        this.embeddingModel = options.embeddingModel ?? CKG_EMBEDDING_MODEL;
+        this.embedder = options.embedder ?? null;
+        this.diskEmbCache =
+            options.persistentEmbeddingCache === false
+                ? null
+                : new DiskEmbeddingCache({
+                    directory: options.embeddingCacheDirectory ?? join(dirname(this.ledgerPath), 'ckg-embeddings'),
+                    maxEntries: 200_000,
+                });
+    }
+    /** The Rust engine client when selected and available, else null.
+     *  Lazy + cached; any failure → null so callers use the in-process TS implementation.
+     *  Default (unset/`auto`): rust only if the binary exists on disk and the snapshot is loadable. */
+    async engineClient() {
+        if (this.engineTried)
+            return this.engine;
+        this.engineTried = true;
+        try {
+            const { BuddyMemoryClient, resolveBuddyMemoryBin } = await import('./buddy-memory-client.js');
+            const preference = chooseCkgEngine({
+                env: process.env.CODEBUDDY_CKG_ENGINE,
+                binaryPath: resolveBuddyMemoryBin(),
+                snapshotLoadable: isCkgSnapshotLoadable(snapshotPathFor(this.ledgerPath)),
+            });
+            if (preference !== 'rust') {
+                this.engine = null;
+                return null;
+            }
+            const c = new BuddyMemoryClient({ ledgerPath: this.ledgerPath, agentId: this.agentId });
+            if (!c.available()) {
+                this.engine = null;
+                return null;
+            }
+            await c.call('ping');
+            this.engine = c;
+        }
+        catch (err) {
+            logger.debug(`[ckg] engine unavailable: ${err instanceof Error ? err.message : String(err)}`);
+            this.engine = null;
+        }
+        return this.engine;
+    }
+    /** Dedicated multilingual embedder (lazy; isolated from EnhancedMemory's all-MiniLM singleton). */
+    getEmbedder() {
+        if (!this.embedder) {
+            this.embedder = new EmbeddingProvider({ provider: 'local', modelName: this.embeddingModel });
+        }
+        return this.embedder;
+    }
+    /** Path of the shared ledger (for diagnostics/tests). */
+    getLedgerPath() {
+        return this.ledgerPath;
+    }
+    /**
+     * Remember a piece of collective knowledge. Best-effort, never-throws. Secrets are
+     * redacted (the lesson is kept, the secret is not). Identical text reinforces (mentions++);
+     * a stable name with new text supersedes the old version.
+     */
+    remember(input) {
+        try {
+            this.load();
+            const safeInput = redactRememberInput(input);
+            const raw = (safeInput.text ?? '').trim();
+            if (!raw)
+                return null;
+            // Privacy: redact every persisted remember field before deriving ids or hashes.
+            const text = raw;
+            const type = safeInput.type ?? 'fact';
+            const name = safeInput.name?.trim() || normalizeName(text);
+            const id = entityId(type, name);
+            const recordedAt = new Date().toISOString();
+            const agentId = safeInput.agentId ?? this.agentId;
+            const ch = contentHash(type, text);
+            const confidence = clamp01(safeInput.confidence ?? 0.8);
+            const entityEvent = {
+                v: 1, kind: 'entity', recordedAt, agentId, contentHash: ch,
+                id, type, name, text, confidence,
+                ...(safeInput.source ? { source: safeInput.source } : {}),
+            };
+            this.append(entityEvent);
+            for (const rel of safeInput.relations ?? []) {
+                const targetType = rel.targetType ?? 'concept';
+                const targetId = entityId(targetType, rel.targetName);
+                const relCh = contentHash('relation', `${id}|${rel.predicate}|${targetId}`);
+                const relEvent = {
+                    v: 1, kind: 'relation', recordedAt, agentId, contentHash: relCh,
+                    sourceId: id, targetId, relType: rel.predicate,
+                    ...(rel.reason ? { reason: rel.reason } : {}),
+                    ...(safeInput.source ? { source: safeInput.source } : {}),
+                };
+                this.append(relEvent);
+                if (!this.current.has(targetId)) {
+                    const tEvent = {
+                        v: 1, kind: 'entity', recordedAt, agentId, contentHash: contentHash(targetType, rel.targetName),
+                        id: targetId, type: targetType, name: rel.targetName, text: rel.targetName, confidence: 0.5,
+                    };
+                    this.append(tEvent);
+                }
+            }
+            return this.toResult(this.current.get(id));
+        }
+        catch (err) {
+            logger.warn(`[ckg] remember failed: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    /**
+     * Read-only view of the current (non-superseded) entity for a type + name.
+     * Lets the peer CKG bridge detect first-hand local knowledge that a remote
+     * entry would supersede, so it can coexist under a disambiguated name instead.
+     */
+    getCurrentEntity(type, name) {
+        try {
+            this.load();
+            const entity = this.current.get(entityId(type, name));
+            if (!entity)
+                return null;
+            return {
+                contentHash: entity.contentHash,
+                text: entity.text,
+                contributors: [...entity.contributors],
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Ingest a DISCOVERY and auto-link it to its nearest existing discoveries — Patrice's
+     * vision: "à chaque découverte, l'enregistrer et relier les découvertes aux plus proches"
+     * (Zettelkasten / A-MEM). Uses the multilingual embeddings to find semantic neighbours and
+     * adds `related_to` edges. Async (embeds); best-effort linking (a failure still stores the
+     * node). This is how a corpus of scientific publications self-organises into a graph.
+     */
+    async ingest(input) {
+        const eng = await this.engineClient();
+        if (eng) {
+            try {
+                // Phase 1 engine: stores the discovery (auto-link/embeddings arrive in Phase 2).
+                const { relationClassifier: _rc, autoLinkK: _k, autoLinkThreshold: _t, ...rest } = input;
+                return (await eng.call('ingest', { type: 'discovery', ...rest })) ?? null;
+            }
+            catch (err) {
+                logger.warn(`[ckg] engine ingest failed, TS fallback: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        const stored = this.remember({ type: 'discovery', ...input });
+        if (!stored)
+            return null;
+        try {
+            this.load(); // see other agents' discoveries too
+            const self = this.current.get(stored.id);
+            if (!self)
+                return stored;
+            const provider = this.getEmbedder();
+            this.loadEmbeddingCache();
+            const selfVec = await this.embedEntity(provider, self);
+            const sims = [];
+            for (const e of this.current.values()) {
+                if (e.id === self.id)
+                    continue;
+                const v = await this.embedEntity(provider, e);
+                sims.push({ e, sim: cosineSimilarityF32(selfVec, v) });
+            }
+            sims.sort((a, b) => b.sim - a.sim);
+            const k = input.autoLinkK ?? 3;
+            const threshold = input.autoLinkThreshold ?? 0.5;
+            for (const { e, sim } of sims.slice(0, k)) {
+                if (sim < threshold)
+                    break;
+                let relType = 'related_to';
+                if (input.relationClassifier) {
+                    try {
+                        relType = await input.relationClassifier(self.text, e.text);
+                    }
+                    catch {
+                        relType = 'related_to';
+                    }
+                }
+                this.linkRelated(self.id, e.id, sim, stored.agentId, relType);
+            }
+        }
+        catch (err) {
+            logger.debug(`[ckg] auto-link skipped: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return this.toResult(this.current.get(stored.id));
+    }
+    /** Ingest a scientific publication as an auto-linked discovery (title + abstract).
+     *  Pass `relationClassifier` to tag neighbour links as supports/contradicts. */
+    async ingestPublication(pub, opts = {}) {
+        const text = (pub.abstract ? `${pub.title}. ${pub.abstract}` : pub.title).trim();
+        const name = (pub.id ?? pub.title).trim();
+        // Publication feeds are polled repeatedly. Reasserting the exact same paper
+        // is not independent corroboration: it only bloats the append-only ledger,
+        // recomputes embeddings/relations, and makes the autonomous research phase
+        // look productive forever. Keep generic `remember()` reinforcement intact,
+        // but make this polling-oriented entry point idempotent. A changed abstract
+        // under the same stable id still flows through `ingest()` and supersedes the
+        // previous version through the existing bi-temporal machinery.
+        const existing = this.getEntity(name);
+        if (existing.status === 'current' && existing.entity?.text === text) {
+            return null;
+        }
+        return this.ingest({
+            type: 'discovery',
+            name,
+            text,
+            source: pub.source ?? 'publication',
+            ...(pub.agentId ? { agentId: pub.agentId } : {}),
+            ...(opts.relationClassifier ? { relationClassifier: opts.relationClassifier } : {}),
+            ...(opts.autoLinkK !== undefined ? { autoLinkK: opts.autoLinkK } : {}),
+            ...(opts.autoLinkThreshold !== undefined ? { autoLinkThreshold: opts.autoLinkThreshold } : {}),
+        });
+    }
+    /**
+     * Recall collective knowledge (Phase 0 — keyword × salience, synchronous, no model load).
+     * Reloads the shared ledger first so writes from OTHER agents/processes are visible.
+     */
+    recall(query, opts = {}) {
+        this.load();
+        const limit = opts.limit ?? 5;
+        const q = tokenize(query);
+        const typeFilter = opts.types ? new Set(opts.types) : null;
+        const scored = [];
+        for (const id of this.recallCandidateIds(q, typeFilter)) {
+            const e = this.current.get(id);
+            if (!e)
+                continue;
+            if (typeFilter && !typeFilter.has(e.type))
+                continue;
+            const kw = keywordOverlap(q, `${e.name} ${e.text}`);
+            if (q.size > 0 && kw === 0)
+                continue;
+            const salience = computeSalience(e.mentions, new Date(e.updatedAt));
+            const score = (q.size > 0 ? kw : 1) * salience * corroborationBoost(e.contributors.size);
+            scored.push({ e, score });
+        }
+        scored.sort((a, b) => b.score - a.score);
+        return scored.slice(0, limit).map(({ e, score }) => this.toResult(e, score));
+    }
+    /**
+     * Hybrid recall (Phase 1) — fuses local embeddings (semantic, $0) + keyword + salience,
+     * with NO LLM at retrieval (Zep). A paraphrased query with no shared keywords still finds
+     * the right knowledge. Embeddings are cached by contentHash across reloads.
+     */
+    async recallHybrid(query, opts = {}) {
+        const eng = await this.engineClient();
+        if (eng) {
+            try {
+                // Phase 1 engine: keyword recall over the shared ledger (semantic+MMR arrive in Phase 2).
+                return (await eng.call('recallHybrid', {
+                    query,
+                    limit: opts.limit ?? 5,
+                    ...(opts.types ? { types: opts.types } : {}),
+                })) ?? [];
+            }
+            catch (err) {
+                logger.warn(`[ckg] engine recallHybrid failed, TS fallback: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        this.load();
+        const limit = opts.limit ?? 5;
+        const typeFilter = opts.types ? new Set(opts.types) : null;
+        const candidates = [...this.current.values()].filter((e) => !typeFilter || typeFilter.has(e.type));
+        if (candidates.length === 0)
+            return [];
+        const provider = this.getEmbedder();
+        this.loadEmbeddingCache();
+        let qVec = null;
+        try {
+            qVec = (await provider.embed(query)).embedding;
+            for (const e of candidates) {
+                await this.embedEntity(provider, e);
+            }
+        }
+        catch (err) {
+            // Embeddings unavailable → degrade gracefully to keyword recall (still useful, $0, no crash).
+            logger.warn('[ckg] semantic recall unavailable; retrieval is explicitly degraded to keyword-only', { error: err instanceof Error ? err.message : String(err) });
+            return this.recall(query, { limit, ...(opts.types ? { types: opts.types } : {}) });
+        }
+        // The unfiltered hot path reuses the in-memory BM25 index built during
+        // ledger replay. A typed subset gets a small temporary index so its IDF
+        // remains identical to the previous behavior.
+        const lexicalIndex = typeFilter ? new BM25Index() : this.recallBm25;
+        if (typeFilter) {
+            lexicalIndex.addDocuments(candidates.map((e) => ({ id: e.id, content: `${e.name} ${e.text}` })));
+        }
+        const lexScores = new Map(lexicalIndex.search(query, this.current.size).map((r) => [r.id, r.score]));
+        const byId = new Map(candidates.map((e) => [e.id, e]));
+        const semById = new Map();
+        const hybridCandidates = candidates.map((e) => {
+            const vec = this.getCachedEmbedding(e) ?? null;
+            const sem = vec && qVec ? Math.max(0, cosineSimilarityF32(qVec, vec)) : null;
+            if (sem !== null)
+                semById.set(e.id, sem);
+            const salience = computeSalience(e.mentions, new Date(e.updatedAt));
+            return {
+                id: e.id,
+                lexicalScore: lexScores.get(e.id) ?? 0,
+                semanticScore: sem,
+                vector: vec,
+                // Recency is a gentle tie-breaker; cross-agent corroboration lifts
+                // trusted facts. Applied AFTER rank fusion (see hybrid-mmr.ts).
+                prior: (0.7 + 0.3 * Math.min(1, salience)) * corroborationBoost(e.contributors.size),
+            };
+        });
+        // Weighted RRF fusion + MMR rerank — see memory/hybrid-mmr.ts for why
+        // RANK fusion (scale-free) replaces the previous linear mix of an
+        // unbounded keyword score with a bounded cosine.
+        const ranked = hybridMmrRank(hybridCandidates, {
+            k: limit,
+            ...(opts.mmrLambda !== undefined ? { lambda: opts.mmrLambda } : {}),
+            ...(opts.semanticWeight !== undefined ? { semanticWeight: opts.semanticWeight } : {}),
+        });
+        return ranked.map((r) => {
+            const e = byId.get(r.id);
+            return { ...this.toResult(e, r.relevance), similarity: semById.get(r.id) ?? 0 };
+        });
+    }
+    /** A `<collective_knowledge>` system block for prompt injection (token-budgeted).
+     *  Uses the same retrieval as `buddy research recall` (`recallHybrid`) plus
+     *  keyword `recall()` so a title buried in a long prompt is not drowned by a
+     *  recent off-topic node. Bound in size; each line is truncated so one blob
+     *  cannot fill the budget alone. */
+    async formatCollectiveContext(query, maxChars = 1_600, timeoutMs = 3_000) {
+        let hybrid = [];
+        try {
+            hybrid = await withTimeout(this.recallHybrid(query, { limit: 8 }), timeoutMs, 'Collective knowledge recall timed out');
+        }
+        catch (err) {
+            logger.debug(`[ckg] collective context skipped: ${err instanceof Error ? err.message : String(err)}`);
+            return '';
+        }
+        const lexical = this.recall(query, { limit: 8 });
+        const hits = selectCollectiveContextHits(query, lexical, hybrid);
+        return packCollectiveContext(hits, maxChars);
+    }
+    /** Invalidated (superseded) versions, for audit / bi-temporal queries. */
+    getSuperseded() {
+        this.load();
+        return [...this.superseded.values()].map((e) => ({ ...this.toResult(e), validTo: e.validTo }));
+    }
+    getStats() {
+        this.load();
+        return {
+            entities: this.current.size,
+            superseded: this.superseded.size,
+            relations: this.relations.size,
+            ledgerPath: this.ledgerPath,
+        };
+    }
+    /**
+     * List the indexed entities (newest first) for administration — `buddy research list`. Ingested
+     * publications/code insights are type `'discovery'`; pass `type` to filter (e.g. to the documents).
+     */
+    listEntities(opts = {}) {
+        this.load();
+        let items = [...this.current.values()];
+        if (opts.type)
+            items = items.filter((e) => e.type === opts.type);
+        items.sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0)); // newest first
+        if (opts.limit && opts.limit > 0)
+            items = items.slice(0, opts.limit);
+        return items.map((e) => ({
+            id: e.id,
+            name: e.name,
+            type: e.type,
+            ...(e.source ? { source: e.source } : {}),
+            confidence: e.confidence,
+            mentions: e.mentions,
+            contributors: e.contributors.size,
+            createdAt: e.createdAt,
+        }));
+    }
+    /**
+     * Inspect ONE node by id (or exact/normalized name), including its
+     * bi-temporal status and superseded/retracted history — `buddy research show`.
+     */
+    getEntity(idOrName) {
+        this.load();
+        const id = this.resolveEntityId(idOrName);
+        if (!id)
+            return { status: 'not_found', history: [] };
+        const history = [...this.superseded.values()]
+            .filter((e) => e.id === id)
+            .sort((a, b) => ((a.validTo ?? '') < (b.validTo ?? '') ? -1 : 1))
+            .map((e) => ({ ...this.toResult(e), validTo: e.validTo }));
+        const cur = this.current.get(id);
+        if (cur)
+            return { status: 'current', entity: { ...this.toResult(cur), validTo: null }, history };
+        // No current version but history exists: a supersede always installs a new
+        // current, so this state can only result from a retraction tombstone.
+        const latest = history[history.length - 1];
+        return latest ? { status: 'retracted', entity: latest, history } : { status: 'not_found', history: [] };
+    }
+    /**
+     * Retract a node — append-only tombstone; the ledger only grows, and a later
+     * `remember()` of the same id revives the node. Idempotent: retracting a
+     * missing or already-retracted node is a no-op. — `buddy research retract`.
+     */
+    retract(idOrName, opts = {}) {
+        try {
+            this.load(); // see other agents' writes first (same hygiene as remember)
+            const id = this.resolveEntityId(idOrName);
+            if (!id)
+                return { retracted: false, id: null, status: 'not_found' };
+            if (!this.current.has(id))
+                return { retracted: false, id, status: 'already_retracted' };
+            const recordedAt = new Date().toISOString();
+            const event = {
+                v: 1,
+                kind: 'retraction',
+                recordedAt,
+                agentId: this.agentId,
+                contentHash: contentHash('retraction', `${id}|${recordedAt}`),
+                id,
+                ...(opts.reason ? { reason: opts.reason } : {}),
+            };
+            this.append(event);
+            return { retracted: true, id, status: 'retracted' };
+        }
+        catch (err) {
+            logger.warn(`[ckg] retract failed: ${err instanceof Error ? err.message : String(err)}`);
+            return { retracted: false, id: null, status: 'not_found' };
+        }
+    }
+    /** Resolve an id, exact name, or normalized name to a known entity id. */
+    resolveEntityId(idOrName) {
+        const raw = idOrName.trim();
+        if (!raw)
+            return null;
+        const known = (id) => this.current.has(id) || [...this.superseded.values()].some((e) => e.id === id);
+        if (raw.includes(':') && known(raw))
+            return raw;
+        const norm = normalizeName(raw);
+        const indexed = this.recallNameIndex.get(`exact:${raw}`) ??
+            this.recallNameIndex.get(`normalized:${norm}`);
+        if (indexed)
+            return indexed;
+        for (const e of this.superseded.values()) {
+            if (e.name === raw || normalizeName(e.name) === norm)
+                return e.id;
+        }
+        return null;
+    }
+    // -- structured facts (Memory-Kernel reconciliation) ---------------------
+    /**
+     * Remember a STRUCTURED fact `(subject, predicate, object, category)` with
+     * Memory-Kernel discipline (jarvis-OS concepts, clean-room). The closed
+     * vocabulary is enforced here — an out-of-vocab predicate/category is
+     * QUARANTINED (never enters the active graph). Otherwise the fact is stored
+     * as a `fact` node whose `name` is the deterministic match key
+     * `subject|predicate|category` and whose `text` is the canonical object, so
+     * the ledger's own bi-temporal machinery gives us for free:
+     *   - same key + same object → reinforce (mentions++), no duplicate;
+     *   - same key + new object on a STABLE category → bi-temporal supersede;
+     *   - same key + new object on a non-stable category → a coexisting node
+     *     (multiple preferences may hold at once).
+     * Never-throws (mirrors `remember`).
+     */
+    rememberFact(input) {
+        try {
+            this.load();
+            const key = factMatchKey(input);
+            const object = canonicalObject(input);
+            const existing = this.current.get(entityId('fact', key));
+            const verdict = reconcileFact(input, existing ? existing.text : null);
+            if (verdict.kind === 'quarantine') {
+                logger.debug(`[ckg] fact quarantined: ${verdict.reasons.join('; ')}`);
+                return { verdict, stored: null };
+            }
+            // A differing object on a non-stable category coexists as a distinct
+            // node (disambiguated by the object hash) instead of superseding.
+            const name = verdict.kind === 'coexist' ? `${key}#${contentHash('fact', object).slice(0, 8)}` : key;
+            const stored = this.remember({
+                type: 'fact',
+                name,
+                text: object,
+                ...(input.agentId ? { agentId: input.agentId } : {}),
+                source: input.source ?? 'fact',
+                ...(input.confidence !== undefined ? { confidence: input.confidence } : {}),
+            });
+            return { verdict, stored };
+        }
+        catch (err) {
+            logger.warn(`[ckg] rememberFact failed: ${err instanceof Error ? err.message : String(err)}`);
+            return { verdict: { kind: 'quarantine', reasons: [String(err)] }, stored: null };
+        }
+    }
+    /**
+     * Recall structured facts ranked by relevance × category-derived retention
+     * (jarvis-OS salience). Facts whose retention has decayed below
+     * `minRetention` are dropped (identity/decision are immortal → never drop).
+     * Reuses keyword recall over the fact nodes; the category is recovered from
+     * the match-key stored in the node name.
+     */
+    recallFacts(query, opts = {}) {
+        const limit = opts.limit ?? 5;
+        const minRetention = opts.minRetention ?? 0;
+        const now = Date.now();
+        // Over-fetch then re-rank with retention (a faded fact can out-keyword a fresh one).
+        const hits = this.recall(query, { limit: limit * 4, types: ['fact'] });
+        const ranked = hits
+            .map((h) => {
+            const category = categoryFromFactName(h.name);
+            const node = this.current.get(h.id);
+            const ageDays = node ? (now - new Date(node.updatedAt).getTime()) / 86_400_000 : 0;
+            const retention = category ? factRetention(category, ageDays) : 1;
+            return { ...h, category, retention, salience: h.salience * retention };
+        })
+            .filter((h) => h.retention >= minRetention)
+            .sort((a, b) => b.salience - a.salience);
+        return ranked.slice(0, limit);
+    }
+    /**
+     * List all current structured facts (parsed from fact nodes), each annotated
+     * with its category-derived retention. For the Markdown mirror + inspection.
+     */
+    listFacts() {
+        this.load();
+        const now = Date.now();
+        const out = [];
+        for (const e of this.current.values()) {
+            if (e.type !== 'fact')
+                continue;
+            const parsed = parseFactKey(e.name);
+            if (!parsed)
+                continue;
+            const ageDays = (now - new Date(e.updatedAt).getTime()) / 86_400_000;
+            out.push({
+                subject: parsed.subject,
+                predicate: parsed.predicate,
+                object: e.text,
+                category: parsed.category,
+                mentions: e.mentions,
+                confidence: e.confidence,
+                retention: factRetention(parsed.category, ageDays),
+                corroborations: e.contributors.size,
+                updatedAt: e.updatedAt,
+            });
+        }
+        return out;
+    }
+    /**
+     * Export a READ-ONLY Markdown mirror of the structured facts, one file per
+     * category (Memory-Kernel unidirectional mirror, jarvis-OS concept). Each file
+     * carries a "do not edit" banner — the ledger is the source of truth, editing
+     * an .md changes nothing. Obsidian-compatible. Returns the files written.
+     */
+    exportFactMirror(dir) {
+        const facts = this.listFacts();
+        const byCategory = new Map();
+        for (const cat of FACT_CATEGORIES)
+            byCategory.set(cat, []);
+        for (const f of facts)
+            byCategory.get(f.category).push(f);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        const files = [];
+        const generatedAt = new Date().toISOString();
+        for (const [category, items] of byCategory) {
+            if (items.length === 0)
+                continue;
+            // Most salient first: retention × confidence, then reinforcement count.
+            items.sort((a, b) => b.retention * b.confidence - a.retention * a.confidence || b.mentions - a.mentions);
+            const lines = [
+                `<!-- AUTO-GÉNÉRÉ depuis le ledger CKG — NE PAS ÉDITER (régénéré à chaque \`buddy research mirror\`) -->`,
+                `# ${category}`,
+                '',
+                `_${items.length} fait(s) · miroir du ${generatedAt}_`,
+                '',
+            ];
+            for (const f of items) {
+                const corr = f.corroborations > 1 ? ` · ${f.corroborations} agents` : '';
+                lines.push(`- **${f.subject} ${f.predicate} ${f.object}** ` +
+                    `(conf ${f.confidence.toFixed(2)} · rét ${f.retention.toFixed(2)} · vu ${f.mentions}×${corr})`);
+            }
+            const file = join(dir, `${category}.md`);
+            writeFileAtomicSync(file, lines.join('\n') + '\n', { mode: 0o600 });
+            files.push(file);
+        }
+        return { files, factCount: facts.length };
+    }
+    // -- internals ------------------------------------------------------------
+    /** Load vectors written by previous processes, accepting only this instance's model. */
+    loadEmbeddingCache() {
+        if (this.embeddingCacheLoaded)
+            return;
+        this.embeddingCacheLoaded = true;
+        if (!this.diskEmbCache || !existsSync(this.embeddingCachePath))
+            return;
+        let content;
+        try {
+            content = readFileSync(this.embeddingCachePath, 'utf8');
+        }
+        catch (err) {
+            logger.debug(`[ckg] embedding cache unavailable: ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        for (const line of content.split('\n')) {
+            const event = parseEmbeddingCacheEvent(line);
+            if (!event || event.model !== this.embeddingModel || this.embCache.has(event.hash))
+                continue;
+            this.embCache.set(event.hash, Float32Array.from(event.vec));
+        }
+    }
+    async embedEntity(provider, entity) {
+        const cached = this.getCachedEmbedding(entity);
+        if (cached)
+            return cached;
+        const vector = (await provider.embed(`${entity.name}. ${entity.text}`)).embedding;
+        this.setCachedEmbedding(entity, vector);
+        return vector;
+    }
+    persistEmbedding(hash, vector) {
+        try {
+            const dir = dirname(this.embeddingCachePath);
+            if (!existsSync(dir))
+                mkdirSync(dir, { recursive: true });
+            const event = { hash, model: this.embeddingModel, vec: Array.from(vector) };
+            appendFileSync(this.embeddingCachePath, `${JSON.stringify(event)}\n`, 'utf8');
+        }
+        catch (err) {
+            // Persistence is an optimisation: semantic recall remains available in-memory.
+            logger.debug(`[ckg] embedding cache write skipped: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    append(event) {
+        const dir = dirname(this.ledgerPath);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        // Audit 2026-09-02 : si un crash a laissé une queue de ligne déchirée
+        // (fichier ne finissant pas par '\n'), un append direct s'y souderait —
+        // la ligne déchirée ET ce nouvel événement deviendraient invalides. On
+        // isole en préfixant '\n' dans le MÊME write (l'atomicité O_APPEND par
+        // syscall est préservée). Pire cas en course : une ligne vide, ignorée
+        // par le parseur.
+        let needsLeadingNewline = false;
+        try {
+            if (existsSync(this.ledgerPath)) {
+                const fd = openSync(this.ledgerPath, 'r');
+                try {
+                    const size = fstatSync(fd).size;
+                    if (size > 0) {
+                        const buf = Buffer.alloc(1);
+                        readSync(fd, buf, 0, 1, size - 1);
+                        needsLeadingNewline = buf[0] !== 0x0a;
+                    }
+                }
+                finally {
+                    closeSync(fd);
+                }
+            }
+        }
+        catch {
+            // Vérification best-effort : en échec, comportement historique.
+        }
+        // One write() of the full JSON line + newline. O_APPEND is atomic per
+        // syscall (the companion Rust engine must not split payload and '\n').
+        appendFileSync(this.ledgerPath, `${needsLeadingNewline ? '\n' : ''}${JSON.stringify(event)}\n`, 'utf8');
+        // `load` is the single event-application path. This avoids double-applying a local
+        // append while still picking up writes that another process raced in before ours.
+        this.load();
+    }
+    /**
+     * Bring the in-memory view up to date from the append-only ledger. Unchanged files cost
+     * one stat; growth reads only bytes after the last complete JSONL line. Truncation,
+     * replacement, or an in-place rewrite falls back to a full replay.
+     */
+    load() {
+        if (!existsSync(this.ledgerPath)) {
+            if (this.ledgerSize > 0 || this.ledgerOffset > 0)
+                this.resetLedgerView();
+            return;
+        }
+        let stats;
+        try {
+            stats = statSync(this.ledgerPath);
+        }
+        catch {
+            return;
+        }
+        const sameFile = this.ledgerDevice === null ||
+            (this.ledgerDevice === stats.dev && this.ledgerInode === stats.ino);
+        const unchanged = sameFile && stats.size === this.ledgerSize && stats.mtimeMs === this.ledgerMtimeMs;
+        if (unchanged)
+            return;
+        const requiresFullReplay = !sameFile ||
+            stats.size < this.ledgerSize ||
+            stats.size < this.ledgerOffset ||
+            (stats.size === this.ledgerSize && stats.mtimeMs !== this.ledgerMtimeMs);
+        if (requiresFullReplay)
+            this.resetLedgerView();
+        const bytesToRead = stats.size - this.ledgerOffset;
+        if (bytesToRead <= 0) {
+            this.rememberLedgerMetadata(stats);
+            return;
+        }
+        const chunk = Buffer.allocUnsafe(bytesToRead);
+        let fd = null;
+        let bytesRead = 0;
+        try {
+            fd = openSync(this.ledgerPath, 'r');
+            while (bytesRead < bytesToRead) {
+                const count = readSync(fd, chunk, bytesRead, bytesToRead - bytesRead, this.ledgerOffset + bytesRead);
+                if (count === 0)
+                    break;
+                bytesRead += count;
+            }
+        }
+        catch {
+            return;
+        }
+        finally {
+            if (fd !== null) {
+                try {
+                    closeSync(fd);
+                }
+                catch {
+                    // The bytes already read remain usable; a close failure must not break recall.
+                }
+            }
+        }
+        // Do not advance past a torn final line. A later append completes it and the next
+        // incremental read starts from the same byte offset.
+        const completeEnd = chunk.subarray(0, bytesRead).lastIndexOf(0x0a) + 1;
+        if (completeEnd === 0) {
+            this.rememberLedgerMetadata(stats);
+            return;
+        }
+        const content = chunk.subarray(0, completeEnd).toString('utf8');
+        for (const line of content.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            let event;
+            try {
+                event = JSON.parse(trimmed);
+            }
+            catch {
+                continue; // a torn final line is skipped, not fatal
+            }
+            if (event.kind === 'entity')
+                this.applyEntity(event);
+            else if (event.kind === 'relation')
+                this.applyRelation(event);
+            else if (event.kind === 'retraction')
+                this.applyRetraction(event);
+        }
+        this.ledgerOffset += completeEnd;
+        this.rememberLedgerMetadata(stats);
+    }
+    resetLedgerView() {
+        this.current.clear();
+        this.superseded.clear();
+        this.relations.clear();
+        this.clearRecallIndexes();
+        this.ledgerOffset = 0;
+        this.ledgerSize = 0;
+        this.ledgerMtimeMs = 0;
+        this.ledgerDevice = null;
+        this.ledgerInode = null;
+    }
+    rememberLedgerMetadata(stats) {
+        this.ledgerSize = stats.size;
+        this.ledgerMtimeMs = stats.mtimeMs;
+        this.ledgerDevice = stats.dev;
+        this.ledgerInode = stats.ino;
+    }
+    /**
+     * Apply a retraction tombstone: the current version moves to the superseded
+     * (audit) map with `validTo` stamped, and disappears from `current` — so
+     * recall/recallHybrid/listEntities exclude it with no changes of their own.
+     * Replay order is file order, so a later entity event for the same id
+     * REVIVES the node (append-only undo) by simply installing a fresh current.
+     */
+    applyRetraction(e) {
+        if (!e.id)
+            return;
+        const cur = this.current.get(e.id);
+        if (!cur)
+            return; // idempotent: nothing current to retract
+        this.unindexEntity(cur);
+        cur.validTo = e.recordedAt;
+        this.superseded.set(`${cur.id}@${cur.contentHash}`, cur);
+        this.current.delete(e.id);
+    }
+    applyEntity(e) {
+        if (!e.id || !e.type || e.name === undefined)
+            return;
+        const cur = this.current.get(e.id);
+        if (!cur) {
+            const fresh = this.makeEntity(e);
+            this.current.set(e.id, fresh);
+            this.indexEntity(fresh);
+            return;
+        }
+        // Same id + same text → reinforce. Distinct agents corroborating lifts confidence
+        // (collective trust); same-agent repeats only bump the mention count.
+        if (cur.contentHash === e.contentHash) {
+            cur.mentions += 1;
+            cur.updatedAt = e.recordedAt;
+            if (e.agentId)
+                cur.contributors.add(e.agentId);
+            cur.confidence = corroboratedConfidence(cur.baseConfidence, cur.contributors.size);
+            return;
+        }
+        // Same id, DIFFERENT text → bi-temporal supersede: invalidate old, install new, link them.
+        cur.validTo = e.recordedAt;
+        this.unindexEntity(cur);
+        this.superseded.set(`${cur.id}@${cur.contentHash}`, cur);
+        const fresh = this.makeEntity(e);
+        this.current.set(e.id, fresh);
+        this.indexEntity(fresh);
+        const relId = contentHash('relation', `${e.id}@${fresh.contentHash}|supersedes|${e.id}@${cur.contentHash}`);
+        this.relations.set(relId, {
+            id: relId,
+            sourceId: e.id,
+            targetId: `${e.id}@${cur.contentHash}`,
+            type: 'supersedes',
+            reason: `fact changed (was ${cur.contentHash.slice(0, 8)})`,
+            mentions: 1,
+        });
+    }
+    makeEntity(e) {
+        const base = e.confidence ?? 0.8;
+        return {
+            id: e.id, type: e.type, name: e.name, text: e.text ?? e.name, contentHash: e.contentHash,
+            baseConfidence: base, confidence: base, mentions: 1,
+            contributors: new Set(e.agentId ? [e.agentId] : []),
+            ...(e.agentId ? { agentId: e.agentId } : {}),
+            ...(e.source ? { source: e.source } : {}),
+            validTo: null, createdAt: e.recordedAt, updatedAt: e.recordedAt,
+        };
+    }
+    /** Append + apply a typed neighbour edge between two discoveries (default `related_to`;
+     *  `supports`/`contradicts` when a classifier judged the pair). */
+    linkRelated(sourceId, targetId, sim, agentId, relType = 'related_to') {
+        const relCh = contentHash('relation', `${sourceId}|${relType}|${targetId}`);
+        if (this.relations.has(relCh))
+            return; // already linked with this relation
+        const event = {
+            v: 1, kind: 'relation', recordedAt: new Date().toISOString(),
+            agentId: agentId ?? this.agentId, contentHash: relCh,
+            sourceId, targetId, relType, reason: `semantic neighbour (${sim.toFixed(2)})`,
+        };
+        this.append(event);
+    }
+    applyRelation(e) {
+        if (!e.sourceId || !e.targetId || !e.relType)
+            return;
+        const relId = e.contentHash;
+        const existing = this.relations.get(relId);
+        if (existing) {
+            existing.mentions += 1;
+            return;
+        }
+        this.relations.set(relId, {
+            id: relId, sourceId: e.sourceId, targetId: e.targetId, type: e.relType,
+            ...(e.reason ? { reason: e.reason } : {}),
+            mentions: 1,
+        });
+    }
+    recallCandidateIds(queryTokens, typeFilter) {
+        if (queryTokens.size > 0) {
+            const ids = new Set();
+            for (const token of queryTokens) {
+                for (const id of this.recallTokenIndex.get(token) ?? [])
+                    ids.add(id);
+            }
+            return ids;
+        }
+        if (typeFilter) {
+            const ids = new Set();
+            for (const type of typeFilter) {
+                for (const id of this.recallTypeIndex.get(type) ?? [])
+                    ids.add(id);
+            }
+            return ids;
+        }
+        return new Set(this.current.keys());
+    }
+    indexEntity(entity) {
+        this.unindexEntity(entity);
+        const tokens = tokenize(`${entity.name} ${entity.text}`);
+        this.indexedEntityTokens.set(entity.id, tokens);
+        for (const token of tokens) {
+            let ids = this.recallTokenIndex.get(token);
+            if (!ids) {
+                ids = new Set();
+                this.recallTokenIndex.set(token, ids);
+            }
+            ids.add(entity.id);
+        }
+        let typed = this.recallTypeIndex.get(entity.type);
+        if (!typed) {
+            typed = new Set();
+            this.recallTypeIndex.set(entity.type, typed);
+        }
+        typed.add(entity.id);
+        this.recallNameIndex.set(`exact:${entity.name}`, entity.id);
+        this.recallNameIndex.set(`normalized:${normalizeName(entity.name)}`, entity.id);
+        this.recallBm25.addDocument({ id: entity.id, content: `${entity.name} ${entity.text}` });
+    }
+    unindexEntity(entity) {
+        const tokens = this.indexedEntityTokens.get(entity.id);
+        if (tokens) {
+            for (const token of tokens) {
+                const ids = this.recallTokenIndex.get(token);
+                ids?.delete(entity.id);
+                if (ids?.size === 0)
+                    this.recallTokenIndex.delete(token);
+            }
+            this.indexedEntityTokens.delete(entity.id);
+        }
+        const typed = this.recallTypeIndex.get(entity.type);
+        typed?.delete(entity.id);
+        if (typed?.size === 0)
+            this.recallTypeIndex.delete(entity.type);
+        for (const key of [`exact:${entity.name}`, `normalized:${normalizeName(entity.name)}`]) {
+            if (this.recallNameIndex.get(key) === entity.id)
+                this.recallNameIndex.delete(key);
+        }
+        this.recallBm25.removeDocument(entity.id);
+    }
+    clearRecallIndexes() {
+        this.recallTokenIndex.clear();
+        this.recallTypeIndex.clear();
+        this.recallNameIndex.clear();
+        this.indexedEntityTokens.clear();
+        this.recallBm25 = new BM25Index();
+    }
+    getCachedEmbedding(entity) {
+        const fingerprint = this.embeddingFingerprint(entity);
+        const memory = this.embCache.get(fingerprint);
+        if (memory)
+            return memory;
+        const stored = this.diskEmbCache?.get(fingerprint);
+        if (stored)
+            this.embCache.set(fingerprint, stored);
+        return stored;
+    }
+    setCachedEmbedding(entity, vector) {
+        const fingerprint = this.embeddingFingerprint(entity);
+        this.embCache.set(fingerprint, vector);
+        this.diskEmbCache?.set(fingerprint, vector);
+        if (this.diskEmbCache)
+            this.persistEmbedding(fingerprint, vector);
+    }
+    embeddingFingerprint(entity) {
+        return createHash('sha1')
+            .update(`${this.embeddingModel}\n${entity.name}\n${entity.contentHash}`)
+            .digest('hex');
+    }
+    toResult(e, salience) {
+        const rels = [...this.relations.values()].filter((r) => r.sourceId === e.id);
+        return {
+            id: e.id, type: e.type, name: e.name, text: e.text,
+            salience: salience ?? computeSalience(e.mentions, new Date(e.updatedAt)),
+            mentions: e.mentions,
+            confidence: e.confidence,
+            corroborations: e.contributors.size,
+            ...(e.agentId ? { agentId: e.agentId } : {}),
+            ...(e.source ? { source: e.source } : {}),
+            relations: rels.map((r) => ({
+                predicate: r.type,
+                target: r.targetId,
+                ...(r.reason ? { reason: r.reason } : {}),
+            })),
+        };
+    }
+}
+function clamp01(n) {
+    return Math.max(0, Math.min(1, Number.isFinite(n) ? n : 0.8));
+}
+/** Query tokens of length ≥ 6 that also appear in the candidate (topical core). */
+function topicalTokenSet(query, text) {
+    const q = tokenize(query);
+    const cand = tokenize(text);
+    const out = new Set();
+    for (const t of q) {
+        if (t.length >= 6 && cand.has(t))
+            out.add(t);
+    }
+    return out;
+}
+/**
+ * Prefer keyword hits (`research recall` fallback) when the query names a
+ * topic; drop hybrid-only neighbours that only match wrapper words
+ * ("mémoire collective") or recency. Paraphrases with no keyword hit still
+ * use `recallHybrid` alone.
+ */
+export function selectCollectiveContextHits(query, lexical, hybrid) {
+    if (lexical.length === 0)
+        return hybrid;
+    const best = lexical[0];
+    const bestTokens = topicalTokenSet(query, `${best.name} ${best.text}`);
+    const allowed = lexical.filter((h) => {
+        if (h.id === best.id)
+            return true;
+        if (bestTokens.size === 0)
+            return h.salience >= best.salience * 0.75;
+        const tokens = topicalTokenSet(query, `${h.name} ${h.text}`);
+        for (const t of tokens) {
+            if (bestTokens.has(t))
+                return true;
+        }
+        return false;
+    });
+    const allowedIds = new Set(allowed.map((h) => h.id));
+    const ordered = [];
+    const seen = new Set();
+    for (const h of [...hybrid, ...allowed]) {
+        if (!allowedIds.has(h.id) || seen.has(h.id))
+            continue;
+        seen.add(h.id);
+        ordered.push(h);
+    }
+    return ordered;
+}
+/** Pack recall hits into a bounded prompt block; truncate per line, never skip the first fit. */
+export function packCollectiveContext(hits, maxChars) {
+    if (hits.length === 0 || maxChars <= 0)
+        return '';
+    const lines = [];
+    let used = 0;
+    const perLine = Math.min(280, Math.max(120, Math.floor(maxChars / 2)));
+    for (const h of hits) {
+        const who = h.agentId ? ` (par ${h.agentId})` : '';
+        let body = h.text.replace(/\s+/g, ' ').trim();
+        if (body.length > perLine)
+            body = `${body.slice(0, perLine - 1)}…`;
+        const line = `- [${h.type}] ${body}${who}`;
+        if (used + line.length + 1 > maxChars) {
+            if (lines.length === 0) {
+                const room = maxChars - 1;
+                if (room > 48)
+                    lines.push(`${line.slice(0, room - 1)}…`);
+            }
+            break;
+        }
+        lines.push(line);
+        used += line.length + 1;
+    }
+    if (lines.length === 0)
+        return '';
+    return `<collective_knowledge>\n${lines.join('\n')}\n</collective_knowledge>`;
+}
+function parseEmbeddingCacheEvent(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const candidate = parsed;
+    if (typeof candidate.hash !== 'string' || typeof candidate.model !== 'string')
+        return null;
+    if (!Array.isArray(candidate.vec) || candidate.vec.length === 0)
+        return null;
+    if (!candidate.vec.every((value) => typeof value === 'number' && Number.isFinite(value)))
+        return null;
+    return { hash: candidate.hash, model: candidate.model, vec: [...candidate.vec] };
+}
+/** Recover the fact category from a fact node's match-key name. */
+function categoryFromFactName(name) {
+    return parseFactKey(name)?.category ?? null;
+}
+function safeAgentId() {
+    try {
+        return defaultFleetAgentId();
+    }
+    catch {
+        return 'unknown/unknown';
+    }
+}
+let singleton = null;
+/** Process-wide CKG bound to the default shared ledger. */
+export function getCollectiveKnowledgeGraph() {
+    if (!singleton)
+        singleton = new CollectiveKnowledgeGraph();
+    return singleton;
+}
+/** Test seam — reset the singleton. */
+export function resetCollectiveKnowledgeGraph() {
+    singleton = null;
+}
+//# sourceMappingURL=collective-knowledge-graph.js.map