@monoes/monomindcli 2.16.12 → 2.16.14

package/dist/src/memory/memory-kg.js

@@ -88,2395 +88,16 @@
  *
  * @module v1/cli/memory/memory-kg
  */
-import { createHash } from 'node:crypto';
-import { mergeKey } from './entity-name-key.js';
-import { bridgeCountEntries, bridgeDeleteEntry, bridgeGetEntry, bridgeListEntries, bridgeSearchEntries, bridgeStoreEntry, } from './memory-bridge.js';
-export const KG_NODES_NS = 'kg:nodes';
-export const KG_EDGES_NS = 'kg:edges';
-export const RULES_NS = 'rules';
-/** Name → entity index. Index rows are NOT claims, so they live outside the
- *  three claim namespaces: putting them in `kg:nodes` would make them seed
- *  candidates for `kgSearch` and rows in `kgStats`. */
-export const KG_NAMES_NS = 'kg:names';
-/** Derived adjacency index namespace (K7). See `KgNamespaces.adj`. */
-export const KG_ADJ_NS = 'kg:adj';
-/** Derived origin-support index namespace (K7). See `KgNamespaces.originIdx`. */
-export const KG_ORIGIN_IDX_NS = 'kg:origin-idx';
-/** Derived-index status namespace (K7). See `KgNamespaces.indexStatus`. */
-export const KG_INDEX_STATUS_NS = 'kg:index-status';
-const MAX_NAME_LEN = 200;
-const MAX_DESC_LEN = 2000;
-/** Nodes/edges/rules accepted per call. Overflow is REPORTED, never sliced away
- *  in silence — see `KgIngestResult.nodesTruncated`. */
-const MAX_NODES_PER_CALL = 500;
-const MAX_EDGES_PER_CALL = 1000;
-const MAX_RULES_PER_CALL = 50;
-/** Per-origin description contributions retained on one element.
- *
- *  A cap has to exist — the bridge caps a stored value, and an element asserted
- *  by ten thousand runs would otherwise stop being writable. What must NOT
- *  happen is the old `origin_refs.slice(-100)`, which dropped the oldest
- *  provenance and left the entry claiming complete history. Past this cap the
- *  oldest contributions are dropped AND the entry records `origins_dropped`
- *  with `provenance_complete: false`, so a reader can tell that a rollback of an
- *  old origin may find nothing to withdraw. */
-const MAX_CLAIMS = 200;
-// ── Identity ────────────────────────────────────────────────────────
-/**
- * Version of the identity scheme implemented by `entityId`/`edgeKey`/`ruleKey`.
- *
- * Bump when a derivation changes. Entries written under an older scheme are not
- * orphaned: resolution probes the previous key shape and adopts the row in
- * place (see `resolveEntity`), so a bump costs a second keyed lookup on the
- * miss path rather than a migration.
- *
- * Version 1 was the name-only scheme (`n:<normalized-name>`, truncated to 200
- * characters), under which `Person:Alex` and `Service:Alex` were one entity and
- * two names first differing at character 250 were one entity.
- */
-export const KG_ID_VERSION = 2;
-/** Identity-grade name normalization: the same folding as `normalizeName` but
- *  WITHOUT its 200-character truncation, which silently merged long names that
- *  differ only past the cut. `normalizeName` keeps truncating because it feeds
- *  tags and display, where length matters and collisions do not. */
-function canonicalName(name) {
-    return String(name).trim().toLowerCase().replace(/['’]/g, '').replace(/\s+/g, '_');
-}
-/** Types that assert nothing. A generic label must not fork an entity away from
- *  its typed self, so it maps to the empty discriminator and is resolved by
- *  name (see `resolveEntity`). */
-const GENERIC_TYPES = new Set(['', 'entity', 'unknown']);
-/** The identity-bearing part of a type: '' when the caller told us nothing. */
-function typeBucket(type) {
-    const t = canonicalName(type ?? '');
-    return GENERIC_TYPES.has(t) ? '' : t;
-}
-/** Hash a tuple injectively: every component is length-prefixed, so no
- *  component's content can masquerade as a delimiter or bleed into its
- *  neighbour, and no two distinct tuples share an input string. Same discipline
- *  as monograph's `symbolId`/`fileId` (packages/@monomind/monograph/src/types.ts),
- *  and adopted here for the same reason — the previous scheme lost distinctions
- *  to truncation and to an unescaped separator. */
-function hashTuple(components) {
-    const canonical = components.map((c) => `${Buffer.byteLength(c, 'utf8')}:${c}`).join('');
-    return createHash('sha256').update(canonical, 'utf8').digest('hex').slice(0, 32);
-}
-/** Mint an entity id from the full identity tuple.
- *
- *  This MINTS; it does not RESOLVE. A caller that computes an id and writes to
- *  it bypasses the name index and re-forks the entities the index exists to
- *  keep together — every ingest path goes through `resolveEntity` instead. */
-export function nodeKey(type, name) {
-    return `n:${hashTuple([String(KG_ID_VERSION), typeBucket(type), canonicalName(name)])}`;
-}
-/** The pre-`KG_ID_VERSION` key for a name: name-only, truncated at 200. Probed
- *  on a miss so existing graphs keep working without being re-keyed. */
-function legacyNodeKey(name) {
-    return `n:${normalizeName(name)}`;
-}
-/** Rows per `bridgeListEntries` call while scanning a namespace.
- *
- *  A single list call cannot return more than the backend's own 10,000-row
- *  ceiling (`MAX_QUERY_LIMIT` in sql-backend.ts), so the old `limit: MAX_LIST`
- *  scans were not "large enough to be safe" — they were exactly the point past
- *  which the graph goes silently invisible. Everything below pages instead.
- *
- *  1,000 balances the two costs: one page is at most ~1 MB even at the bridge's
- *  16 KB value cap (typical KG entries are far smaller), and it takes a tenth
- *  of the round trips a 100-row page would. */
-const SCAN_PAGE = 1_000;
-/** Edge rows `kgSearch` will read before giving up and reporting `truncated`.
- *  Search is interactive and runs a full scan per query, so unlike rollback it
- *  keeps a ceiling — five times the old silent one, and now stated in the
- *  result rather than hidden. */
-const SEARCH_EDGE_SCAN_MAX = 50_000;
-/** Page through an entire namespace, handing each page to `onPage` so callers
- *  fold as they go instead of materializing the namespace.
- *
- *  `onPage` returning exactly `false` stops the scan early (only `kgSearch`
- *  does that); any other return value continues. Returns false when the backend
- *  was unavailable — an unreadable namespace must never be mistaken for an
- *  empty one.
- *
- *  Callers that MUTATE what they find must collect during the scan and mutate
- *  afterwards: deleting a row pulls every later row back one position, so under
- *  an advancing offset the row that slid into the gap is never read. (The
- *  bridge's upsert no longer reorders — it reuses the existing entry id and
- *  preserves `createdAt` — so rewrites alone are safe; deletes are not, and
- *  both callers here delete.) */
-async function scanNamespace(namespace, dbPath, onPage) {
-    for (let offset = 0;; offset += SCAN_PAGE) {
-        const res = await bridgeListEntries({ namespace, limit: SCAN_PAGE, offset, dbPath });
-        if (!res)
-            return false;
-        if (res.entries.length && onPage(res.entries) === false)
-            return true;
-        if (res.entries.length < SCAN_PAGE)
-            return true;
-    }
-}
-/** Delete every entry in `namespace`. Used only to reset a DERIVED-index
- *  namespace (`kg:adj`/`kg:origin-idx`) before a fresh `kgRebuildIndex` —
- *  never a canonical one. Collect-then-delete, same reason `kgRollback`
- *  does: deleting mid-scan pulls later rows back under an advancing offset.
- *  Returns false (nothing deleted) on an unreadable or partially-deletable
- *  namespace, so the caller never proceeds as if a clear that didn't fully
- *  happen did. */
-async function clearNamespace(namespace, dbPath) {
-    const doomed = [];
-    const covered = await scanNamespace(namespace, dbPath, (page) => {
-        for (const e of page)
-            doomed.push(e);
-    });
-    if (!covered)
-        return false;
-    let ok = true;
-    for (const e of doomed) {
-        const del = await bridgeDeleteEntry({ id: e.id, namespace, dbPath });
-        if (!del?.deleted)
-            ok = false;
-    }
-    return ok;
-}
-/** Cap on reported failure messages — a dead backend fails every write, and a
- *  500-entry failure list is noise, not signal. `error` carries the true count. */
-const MAX_FAILURES = 20;
-/** `bridgeStoreEntry` never throws: it returns `null` when no backend is
- *  reachable and `{ success: false, error }` when the write itself failed.
- *  Both look like success to an `await` that ignores the result, which is how
- *  the graph came to claim knowledge it had not persisted. Every write in this
- *  module goes through here.
- *
- *  @returns a failure message, or null when the write landed. */
-function storeFailure(res, what) {
-    if (!res)
-        return `${what}: memory backend unavailable`;
-    if (!res.success)
-        return `${what}: ${res.error ?? 'store rejected'}`;
-    return null;
-}
-/** Accumulates write failures across a multi-write operation. The memory
- *  bridge exposes no transaction primitive, so ingest CANNOT be atomic: some
- *  writes land and some do not. Rather than hide that, callers get exact
- *  counters for what persisted plus the failure list for what did not. */
-class FailureLog {
-    messages = [];
-    count = 0;
-    /** @returns true when the write failed (caller should not count it). */
-    add(res, what) {
-        const msg = storeFailure(res, what);
-        if (!msg)
-            return false;
-        this.count++;
-        if (this.messages.length < MAX_FAILURES)
-            this.messages.push(msg);
-        return true;
-    }
-    note(message) {
-        this.count++;
-        if (this.messages.length < MAX_FAILURES)
-            this.messages.push(message);
-    }
-    get failed() {
-        return this.count > 0;
-    }
-    /** Summary for the result's `error` field; undefined when everything landed. */
-    summary() {
-        if (!this.count)
-            return undefined;
-        return `${this.count} bridge operation(s) failed; graph state is partial`;
-    }
-}
-/** Attempts a compare-and-swap claim write, retrying while the bridge reports
- *  a version conflict (K5): a concurrent writer applied its own claim to the
- *  same row between our read and our write. `attempt()` must re-read,
- *  re-merge (via `applyClaim`), and re-attempt the write itself on every call
- *  — retrying with the SAME stale write would just lose the update again,
- *  the exact bug this exists to close.
- *
- *  Exhausting `maxAttempts` under sustained contention is returned as-is (the
- *  last conflict response) rather than retried forever: the caller's
- *  `FailureLog` reports it as a real, visible failure — never a silent lost
- *  update — same as any other write the bridge refused. */
-async function withCasRetry(attempt, maxAttempts = 3) {
-    let res = null;
-    for (let i = 0; i < maxAttempts; i++) {
-        res = await attempt();
-        if (!res?.conflict)
-            return res;
-    }
-    return res;
-}
-/** cognee DataPoint normalization: lowercase, spaces→_, strip apostrophes. */
-export function normalizeName(name) {
-    return String(name)
-        .trim()
-        .toLowerCase()
-        .replace(/['’]/g, '')
-        .replace(/\s+/g, '_')
-        .slice(0, MAX_NAME_LEN);
-}
-/** Edge identity: the endpoint IDs (already collision-free) plus the relation,
- *  hashed injectively so a relation containing the old `|` separator can no
- *  longer forge a different edge's key. */
-function edgeKey(srcKey, relation, dstKey) {
-    return `e:${hashTuple([String(KG_ID_VERSION), srcKey, canonicalName(relation), dstKey])}`;
-}
-/** The pre-`KG_ID_VERSION` edge key, for the same in-place adoption as
- *  `legacyNodeKey`. Composed from the RESOLVED endpoint keys, so it names the
- *  legacy edge exactly when both endpoints are themselves legacy rows. */
-function legacyEdgeKey(srcKey, relation, dstKey) {
-    return `e:${srcKey}|${normalizeName(relation)}|${dstKey}`;
-}
-/** Rule identity: the full rule text. The old key truncated the normalized rule
- *  at 120 characters, so two rules sharing a long preamble were one rule. */
-function ruleKey(rule) {
-    return `rule:${hashTuple([String(KG_ID_VERSION), canonicalName(rule)])}`;
-}
-function legacyRuleKey(rule) {
-    return `rule:${normalizeName(rule).slice(0, 120)}`;
-}
-/** The namespaces a scope owns. Every read and write in this module resolves
- *  through here, which is what makes ownership enforced rather than advisory:
- *  there is no code path that reaches an org's facts without naming that org,
- *  and none that reaches every org at once. */
-export function kgNamespaces(scope) {
-    const org = scope?.org?.trim();
-    if (!org)
-        return {
-            nodes: KG_NODES_NS,
-            edges: KG_EDGES_NS,
-            rules: RULES_NS,
-            names: KG_NAMES_NS,
-            adj: KG_ADJ_NS,
-            originIdx: KG_ORIGIN_IDX_NS,
-            indexStatus: KG_INDEX_STATUS_NS,
-        };
-    const suffix = `:org:${normalizeName(org)}`;
-    return {
-        nodes: KG_NODES_NS + suffix,
-        edges: KG_EDGES_NS + suffix,
-        rules: RULES_NS + suffix,
-        names: KG_NAMES_NS + suffix,
-        adj: KG_ADJ_NS + suffix,
-        originIdx: KG_ORIGIN_IDX_NS + suffix,
-        indexStatus: KG_INDEX_STATUS_NS + suffix,
-    };
-}
-/** Stamp the asserting org onto a provenance ref, so a claim's origin says WHO
- *  asserted it and not merely which run id — `run:m4x2` alone is ambiguous
- *  across orgs, and a promoted claim in the shared graph would otherwise carry
- *  an origin no one owns.
- *
- *  Applied by the ingest/rollback entry points rather than by callers: a
- *  caller that forgets is exactly how ownership stopped being enforced. */
-export function kgQualifyOrigin(originRef, scope) {
-    const org = scope?.org?.trim();
-    return org ? `org:${normalizeName(org)}/${originRef}` : originRef;
-}
-function claimsOf(md) {
-    const raw = md.claims;
-    if (Array.isArray(raw))
-        return raw
-            .filter((c) => c && typeof c.origin === 'string')
-            .map((c) => ({
-            origin: c.origin,
-            description: typeof c.description === 'string' ? c.description : '',
-            at: typeof c.at === 'number' ? c.at : 0,
-            ...(c.method === 'asserted' || c.method === 'heuristic' ? { method: c.method } : {}),
-        }));
-    // Pre-ledger row (including every entry written before KG_ID_VERSION 2):
-    // seed one contribution per recorded origin, all carrying the one description
-    // the merge left behind. That is the honest reconstruction — the old merge
-    // destroyed which origin said what — and it preserves current rollback
-    // behaviour exactly: withdrawing one of several origins leaves the summary
-    // unchanged, withdrawing the last deletes the element.
-    const origins = Array.isArray(md.origin_refs) ? md.origin_refs : [];
-    const description = typeof md.description === 'string' ? md.description : '';
-    const at = typeof md.valid_from === 'number' ? md.valid_from : 0;
-    return origins.map((origin) => ({ origin, description, at }));
-}
-/** Add or replace `origin`'s contribution and re-derive everything that hangs
- *  off the ledger. */
-function applyClaim(md, origin, description, now, method = 'asserted') {
-    const existing = claimsOf(md);
-    const dropped = typeof md.origins_dropped === 'number' ? md.origins_dropped : 0;
-    // An EMPTY description is support without content — "this entity exists",
-    // which is what naming an edge endpoint asserts. It must never overwrite what
-    // the same origin already said, or an edge listing a node the same payload
-    // described would blank that description out.
-    const prior = existing.find((c) => c.origin === origin);
-    if (!description.trim() && prior?.description.trim())
-        return deriveClaims(existing, dropped);
-    const claims = existing.filter((c) => c.origin !== origin);
-    claims.push({ origin, description, at: now, method });
-    return deriveClaims(claims, dropped);
-}
-/** The element's standing, from its surviving claims.
- *
- *  One asserted claim outranks any number of co-occurrence guesses: a fact
- *  someone stated does not become less stated because a heuristic also stumbled
- *  onto it. A claim with no recorded method makes the whole projection UNKNOWN
- *  rather than voting — an old row cannot be read as evidence either way. */
-function deriveMethod(claims) {
-    if (!claims.length || claims.some((c) => !c.method))
-        return undefined;
-    return claims.some((c) => c.method === 'asserted') ? 'asserted' : 'heuristic';
-}
-function deriveClaims(claims, alreadyDropped) {
-    let dropped = alreadyDropped;
-    if (claims.length > MAX_CLAIMS) {
-        // Oldest support goes first, and the loss is RECORDED. The scheme this
-        // replaced did the same drop silently and left the entry claiming a
-        // complete history it no longer had.
-        dropped += claims.length - MAX_CLAIMS;
-        claims = claims.slice(-MAX_CLAIMS);
-    }
-    return {
-        claims,
-        description: currentDescription(claims),
-        origin_refs: claims.map((c) => c.origin),
-        provenance_complete: dropped === 0,
-        origins_dropped: dropped,
-        conflict: new Set(claims.map((c) => c.description.trim()).filter(Boolean)).size > 1,
-        method: deriveMethod(claims),
-    };
-}
-/** The current summary: the most recent contribution that actually says
- *  something. LATEST wins, not longest — length measures verbosity, and
- *  "longest wins" is why re-ingesting a corrected "Now PostgreSQL" left the
- *  stale MySQL blurb in place. */
-function currentDescription(claims) {
-    let best;
-    for (const c of claims) {
-        if (!c.description.trim())
-            continue;
-        if (!best || c.at >= best.at)
-            best = c;
-    }
-    return best?.description ?? '';
-}
-/** Withdraw one origin. Returns null when nothing supports the element any
- *  more (the caller deletes it); otherwise the RE-DERIVED state, which is what
- *  restores a previous correct description after a bad update is rolled back. */
-function withoutOrigin(md, origin) {
-    const remaining = claimsOf(md).filter((c) => c.origin !== origin);
-    if (!remaining.length)
-        return null;
-    return deriveClaims(remaining, typeof md.origins_dropped === 'number' ? md.origins_dropped : 0);
-}
-function nameIndexKey(name) {
-    return `nm:${hashTuple([String(KG_ID_VERSION), canonicalName(name)])}`;
-}
-/** A coarser, additive index alongside the exact one: bucketed by `mergeKey`
- *  (case/separator/plural-insensitive), so "Node.js" and "nodejs" land in the
- *  same bucket even though their exact `nameIndexKey`s differ. Purely a hint
- *  like the exact index — `resolveEntity` still applies the same (type, name)
- *  merge rules to whatever it finds here, so a bucket hit is a candidate,
- *  never an automatic cross-type merge. */
-function mergeIndexKey(name) {
-    return `nmk:${hashTuple([String(KG_ID_VERSION), mergeKey(name)])}`;
-}
-/** @returns the indexed entities, or null when the backend could not be read.
- *
- *  The null is load-bearing: an unreadable index looks exactly like an empty
- *  one, and treating a read failure as "no entities with this name" would make
- *  the next write REPLACE the row with a single entry, erasing every other
- *  same-name entity from the index. A later generic assertion would then see one
- *  candidate and adopt it — a silent wrong merge caused by a read hiccup. */
-async function readNameIndex(name, ns, dbPath) {
-    const res = await bridgeGetEntry({ key: nameIndexKey(name), namespace: ns.names, dbPath });
-    if (!res)
-        return null;
-    const raw = res.entry?.metadata?.entities;
-    if (!Array.isArray(raw))
-        return [];
-    return raw.filter((c) => c && typeof c.id === 'string');
-}
-/** Persist (or clear) the index row for one name.
- *
- *  The index is a HINT, not a source of truth: it is written after the entity
- *  write lands, and a row that goes stale — pointing at an entity a rollback
- *  removed — self-heals, because resolving onto a missing id makes the next
- *  ingest create that entity fresh with an empty claim ledger, which is exactly
- *  what a new entity is. Nothing reads the index to decide what the graph
- *  contains; `kgStats`, `kgSearch` and `kgRollback` all read the claim
- *  namespaces. */
-async function writeNameIndex(name, entities, ns, dbPath, failures) {
-    const key = nameIndexKey(name);
-    if (!entities.length) {
-        await bridgeDeleteEntry({ key, namespace: ns.names, dbPath });
-        return;
-    }
-    const res = await bridgeStoreEntry({
-        key,
-        value: name,
-        namespace: ns.names,
-        dbPath,
-        upsert: true,
-        generateEmbeddingFlag: false,
-        tags: ['kg', 'name-index'],
-        metadata: { kg: 'name', name, entities },
-    });
-    failures.add(res, `name index ${key}`);
-    await writeMergeIndex(name, entities, ns, dbPath, failures);
-}
-/** Add `entities` into the merge-key bucket for `name`, unioned with whatever
- *  other exact spellings already sharing that bucket contributed. Additive
- *  only — a name written with fewer entities than before (e.g. a rollback's
- *  survivor list) never removes another spelling's candidates from the shared
- *  bucket. That is a smaller staleness cost than the exact index already
- *  accepts, and self-heals the same way: a stale candidate that no longer
- *  resolves to a live entity simply is not adopted. */
-async function writeMergeIndex(name, entities, ns, dbPath, failures) {
-    const key = mergeIndexKey(name);
-    const existing = await bridgeGetEntry({ key, namespace: ns.names, dbPath });
-    const prior = existing?.entry?.metadata?.entities;
-    const merged = new Map();
-    if (Array.isArray(prior))
-        for (const c of prior)
-            if (c && typeof c.id === 'string')
-                merged.set(c.id, c);
-    for (const c of entities)
-        merged.set(c.id, c);
-    const res = await bridgeStoreEntry({
-        key,
-        value: mergeKey(name),
-        namespace: ns.names,
-        dbPath,
-        upsert: true,
-        generateEmbeddingFlag: false,
-        tags: ['kg', 'name-merge-index'],
-        metadata: { kg: 'name-merge', mergeKey: mergeKey(name), entities: [...merged.values()] },
-    });
-    failures.add(res, `merge index ${key}`);
-}
-/** @returns candidates from the merge-key bucket, or null on a read failure —
- *  same null-is-load-bearing contract as `readNameIndex`. */
-async function readMergeIndex(name, ns, dbPath) {
-    const res = await bridgeGetEntry({ key: mergeIndexKey(name), namespace: ns.names, dbPath });
-    if (!res)
-        return null;
-    const raw = res.entry?.metadata?.entities;
-    if (!Array.isArray(raw))
-        return [];
-    return raw.filter((c) => c && typeof c.id === 'string');
-}
-/**
- * Resolve (type, name) to the entity that should carry the assertion.
- *
- * Identity is the (type, name) tuple, so distinct types are distinct entities.
- * The one thing name-only identity got right — a generic label must not fork an
- * entity away from its typed self — is preserved here instead of in the key:
- *
- *  - exact type-bucket match  → that entity
- *  - generic assertion, exactly one same-name entity → adopt it
- *  - typed assertion, exactly one same-name entity and it is untyped → adopt it
- *    and promote its type (its ID does not change, so references stay valid)
- *  - anything else            → a new entity, with the alternatives as candidates
- *
- * @returns null when the name index could not be read — the caller must refuse
- * the assertion rather than resolve it against an index it could not see.
- */
-async function resolveEntity(name, type, ns, dbPath) {
-    const bucket = typeBucket(type);
-    let known = await readNameIndex(name, ns, dbPath);
-    if (known === null)
-        return null;
-    /** True when the index row already holds exactly `known` — the only case in
-     *  which an unchanged resolution needs no index write. */
-    let indexed = known.length > 0;
-    if (!indexed) {
-        // Nothing indexed. Before minting, probe the pre-KG_ID_VERSION key: an
-        // existing graph's rows are adopted IN PLACE (keeping their key, and so
-        // keeping the edges whose keys embed it) rather than re-keyed or orphaned.
-        const legacyKey = legacyNodeKey(name);
-        const legacy = await bridgeGetEntry({ key: legacyKey, namespace: ns.nodes, dbPath });
-        if (legacy?.found && legacy.entry) {
-            const md = legacy.entry.metadata;
-            known = [{ id: legacyKey, type: typeBucket(typeof md.type === 'string' ? md.type : '') }];
-            indexed = false;
-        }
-    }
-    if (!indexed && known.length === 0) {
-        // Still nothing under this exact spelling — check for a spelling variant
-        // (case, separators, a plain plural) already known under the same
-        // merge-key bucket. A hit is only a CANDIDATE: it still goes through the
-        // exact/promote/mint rules below, so it can never merge across types.
-        const merged = await readMergeIndex(name, ns, dbPath);
-        if (merged && merged.length > 0)
-            known = merged;
-    }
-    const exact = known.find((c) => c.type === bucket);
-    if (exact)
-        return { id: exact.id, candidates: others(known, exact.id), index: indexed ? null : known };
-    // A generic assertion adopts the one entity that bears this name; a typed
-    // assertion adopts a lone UNTYPED entity and PROMOTES it — same id, so every
-    // edge and returned reference to it stays valid. A typed assertion never
-    // absorbs a differently-typed entity, and neither adopts when the name is
-    // already ambiguous.
-    if (known.length === 1 && (!bucket || !known[0].type)) {
-        const only = known[0];
-        const promoted = { id: only.id, type: bucket || only.type };
-        return { id: only.id, candidates: [], index: [promoted] };
-    }
-    const minted = { id: mintEntityId(type, name, known), type: bucket };
-    return { id: minted.id, candidates: known, index: [...known, minted] };
-}
-/** An ID for a new entity that no entity under this name already uses.
- *
- *  `nodeKey(type, name)` alone is not sufficient, because promotion decouples
- *  an entity's ID from its current type: an entity minted untyped keeps the
- *  `''`-bucket ID after a typed assertion promotes it, so a LATER untyped
- *  assertion would re-derive that same ID and write its claims into the
- *  promoted entity — while simultaneously reporting that entity as one it had
- *  "kept separate from". The discriminator is bumped only on collision, so the
- *  first entity of a (type, name) still gets exactly `nodeKey(type, name)`. */
-function mintEntityId(type, name, known) {
-    const taken = new Set(known.map((c) => c.id));
-    let id = nodeKey(type, name);
-    for (let n = 1; taken.has(id); n++)
-        id = `n:${hashTuple([String(KG_ID_VERSION), typeBucket(type), canonicalName(name), String(n)])}`;
-    return id;
-}
-function others(known, id) {
-    return known.filter((c) => c.id !== id);
-}
-// ── Ingest ──────────────────────────────────────────────────────────
-/** Merge extracted nodes/edges into the KG.
- *
- *  Identity is the (type, name) tuple resolved through the name index, so an
- *  entity is idempotent under re-extraction but two different things sharing a
- *  name stay two things. Each write adds this origin's CONTRIBUTION to the
- *  element's claim ledger, from which the description and `origin_refs` are
- *  derived — which is what lets a later ingest correct an earlier one and lets
- *  rollback put the earlier one back.
- *
- *  The COMPLETE payload is validated before anything is written, and every edge
- *  endpoint is made to exist (as a placeholder entity when the caller named one
- *  that does not) before the edge lands. An edge whose endpoint could not be
- *  created is rejected rather than written: retrieval is seeded from nodes, so
- *  an edge with a missing endpoint is a fact that cannot be found through
- *  either of the things it is about.
- *
- *  NOT ATOMIC — the memory bridge has no transaction primitive, so a failure
- *  part-way through leaves earlier writes persisted. The counters therefore
- *  report only what actually landed, `failures` lists what did not, and
- *  `success` is false whenever anything was refused. A partial ingest is safe
- *  to retry: every write is a keyed upsert. */
-export async function kgIngest(options) {
-    const { dbPath } = options;
-    const method = options.method ?? 'asserted';
-    const ns = kgNamespaces(options.scope);
-    const originRef = kgQualifyOrigin(options.originRef, options.scope);
-    const failures = new FailureLog();
-    const report = new IngestReport();
-    let nodesAdded = 0, nodesMerged = 0, edgesAdded = 0, edgesMerged = 0;
-    try {
-        // ── Validate the COMPLETE payload before mutating anything ──
-        // An invalid item that surfaces halfway through leaves the graph holding
-        // part of a payload the caller was told was rejected.
-        const allNodes = options.nodes ?? [];
-        const allEdges = options.edges ?? [];
-        const nodes = allNodes.slice(0, MAX_NODES_PER_CALL);
-        const edges = allEdges.slice(0, MAX_EDGES_PER_CALL);
-        report.nodesTruncated = allNodes.length - nodes.length;
-        report.edgesTruncated = allEdges.length - edges.length;
-        const validNodes = [];
-        nodes.forEach((n, i) => {
-            if (!n?.name?.trim())
-                return report.rejectNode(`node[${i}]: missing name`);
-            validNodes.push({
-                input: n,
-                type: n.type?.trim() || 'entity',
-                desc: (n.description ?? '').slice(0, MAX_DESC_LEN),
-            });
-        });
-        const validEdges = [];
-        edges.forEach((e, i) => {
-            const missing = !e?.source?.trim()
-                ? 'source'
-                : !e?.target?.trim()
-                    ? 'target'
-                    : !e?.relation?.trim()
-                        ? 'relation'
-                        : '';
-            if (missing)
-                return report.rejectEdge(`edge[${i}]: missing ${missing}`);
-            validEdges.push(e);
-        });
-        /** Entity IDs this call has already resolved AND confirmed to exist, so an
-         *  edge does not re-resolve an endpoint the node loop just wrote. */
-        const resolved = new Map();
-        // Length-prefix the type so the split point is unambiguous regardless of
-        // what characters `name` contains (it can hold arbitrary text, including
-        // whatever separator a naive join might pick) — same discipline
-        // hashTuple() above uses for the same reason. A bare `\0`-joined string
-        // here was written as an actual NUL byte, not the literal two-character
-        // escape text, which is harmless at runtime (this key is an in-memory
-        // Map key only, never persisted) but made git treat this file as binary.
-        const memoKey = (name, type) => {
-            const t = typeBucket(type);
-            return `${t.length}:${t}${canonicalName(name)}`;
-        };
-        for (const { input: n, type, desc } of validNodes) {
-            const target = await resolveEntity(n.name, type, ns, dbPath);
-            if (!target) {
-                failures.note(`node ${n.name}: name index unreadable`);
-                continue;
-            }
-            report.noteAmbiguity(n.name, target.candidates);
-            const wrote = await writeEntity({
-                id: target.id,
-                name: n.name,
-                type,
-                description: desc,
-                nodeSet: n.nodeSet,
-                originRef,
-                method,
-                ns,
-                dbPath,
-                failures,
-                report,
-            });
-            if (wrote === null)
-                continue;
-            if (wrote)
-                nodesAdded++;
-            else
-                nodesMerged++;
-            resolved.set(memoKey(n.name, type), target.id);
-            if (target.index)
-                await writeNameIndex(n.name, target.index, ns, dbPath, failures);
-            await onEntrySupported(ns, ns.nodes, target.id, originRef, dbPath);
-        }
-        /** Resolve an edge endpoint, creating an explicit placeholder entity when
-         *  the caller named something that does not exist. Returns null when the
-         *  endpoint could not be made to exist — the edge is then rejected rather
-         *  than written without it. */
-        const endpoint = async (name, type) => {
-            const memo = memoKey(name, type ?? 'entity');
-            const hit = resolved.get(memo);
-            if (hit)
-                return hit;
-            const target = await resolveEntity(name, type ?? 'entity', ns, dbPath);
-            if (!target) {
-                failures.note(`endpoint ${name}: name index unreadable`);
-                return null;
-            }
-            report.noteAmbiguity(name, target.candidates);
-            // Always write: naming an endpoint IS an assertion that it exists, so
-            // this origin joins the entity's support either way. A write that CREATES
-            // the entity is the placeholder case worth reporting.
-            const wrote = await writeEntity({
-                id: target.id,
-                name,
-                type: type ?? 'entity',
-                description: '',
-                placeholder: true,
-                originRef,
-                method,
-                ns,
-                dbPath,
-                failures,
-                report,
-            });
-            if (wrote === null)
-                return null;
-            if (wrote)
-                report.placeholders++;
-            if (target.index)
-                await writeNameIndex(name, target.index, ns, dbPath, failures);
-            resolved.set(memo, target.id);
-            await onEntrySupported(ns, ns.nodes, target.id, originRef, dbPath);
-            return target.id;
-        };
-        for (const e of validEdges) {
-            const srcKey = await endpoint(e.source, e.sourceType);
-            const dstKey = await endpoint(e.target, e.targetType);
-            if (!srcKey || !dstKey) {
-                report.rejectEdge(`edge ${e.source}-${e.relation}->${e.target}: endpoint not persisted`);
-                continue;
-            }
-            const desc = (e.description ?? '').slice(0, MAX_DESC_LEN);
-            const fallbackFact = `${e.source} ${e.relation} ${e.target}`;
-            // New key first, then the pre-KG_ID_VERSION shape: a legacy edge between
-            // two adopted legacy endpoints keeps its own key rather than being
-            // duplicated under a new one. Resolved once — a CAS retry re-reads this
-            // same key, it does not re-run legacy resolution.
-            let key = edgeKey(srcKey, e.relation, dstKey);
-            const probe = await bridgeGetEntry({ key, namespace: ns.edges, dbPath });
-            if (!probe?.found) {
-                const legacy = legacyEdgeKey(srcKey, e.relation, dstKey);
-                const hit = await bridgeGetEntry({ key: legacy, namespace: ns.edges, dbPath });
-                if (hit?.found && hit.entry)
-                    key = legacy;
-            }
-            // Re-read and re-merge on every CAS attempt (see withCasRetry): a stale
-            // `md`/`derived` retried against a fresh row would silently re-lose
-            // whatever a concurrent writer just added (K5).
-            let md = {};
-            let derived;
-            let isNew = false;
-            const res = await withCasRetry(async () => {
-                const existing = await bridgeGetEntry({ key, namespace: ns.edges, dbPath });
-                isNew = !(existing?.found && existing.entry);
-                md = (existing?.entry?.metadata ?? {});
-                derived = applyClaim(md, originRef, desc, Date.now(), method);
-                const ver = existing?.entry?.version;
-                return bridgeStoreEntry({
-                    key,
-                    value: derived.description || fallbackFact,
-                    namespace: ns.edges,
-                    dbPath,
-                    upsert: true,
-                    generateEmbeddingFlag: false,
-                    tags: ['kg', normalizeName(e.relation)],
-                    metadata: {
-                        ...md,
-                        kg: 'edge',
-                        id_version: KG_ID_VERSION,
-                        src: srcKey,
-                        dst: dstKey,
-                        relation: normalizeName(e.relation),
-                        source_name: e.source,
-                        target_name: e.target,
-                        ...derived,
-                        valid_from: md.valid_from ?? Date.now(),
-                        valid_to: null,
-                    },
-                    ifVersion: isNew ? 'absent' : typeof ver === 'number' ? ver : undefined,
-                });
-            });
-            if (failures.add(res, `edge ${key}`))
-                continue;
-            report.noteProvenanceLoss(md, derived);
-            if (isNew)
-                edgesAdded++;
-            else
-                edgesMerged++;
-            await onEntrySupported(ns, ns.edges, key, originRef, dbPath);
-            if (isNew)
-                await onEdgeWritten(ns, key, srcKey, dstKey, dbPath);
-        }
-        return {
-            success: !failures.failed,
-            nodesAdded,
-            nodesMerged,
-            edgesAdded,
-            edgesMerged,
-            ...(failures.failed ? { failures: failures.messages, error: failures.summary() } : {}),
-            ...report.fields(),
-        };
-    }
-    catch (err) {
-        return {
-            success: false,
-            nodesAdded,
-            nodesMerged,
-            edgesAdded,
-            edgesMerged,
-            ...(failures.messages.length ? { failures: failures.messages } : {}),
-            ...report.fields(),
-            error: err instanceof Error ? err.message : String(err),
-        };
-    }
-}
-/** Write one entity's claim contribution.
- *
- *  @returns true when the entity was created, false when an existing one was
- *  merged into, and null when the bridge refused the write (the caller must not
- *  count it, and must not treat the entity as existing). */
-async function writeEntity(o) {
-    // Re-read and re-merge on every CAS attempt (see withCasRetry) rather than
-    // once up front: a stale `md`/`derived` retried against a fresh row would
-    // silently re-lose whatever a concurrent writer just added (K5).
-    let md = {};
-    let derived;
-    let isNew = false;
-    const res = await withCasRetry(async () => {
-        const existing = await bridgeGetEntry({ key: o.id, namespace: o.ns.nodes, dbPath: o.dbPath });
-        isNew = !(existing?.found && existing.entry);
-        md = (existing?.entry?.metadata ?? {});
-        derived = applyClaim(md, o.originRef, o.description, Date.now(), o.method);
-        // Keep the most specific type: a generic heuristic 'entity' never
-        // overwrites an LLM-assigned one, and a specific one promotes an untyped
-        // entity.
-        const prevType = typeof md.type === 'string' ? md.type : '';
-        const bestType = typeBucket(prevType) ? prevType : o.type;
-        const nodeSet = o.nodeSet ?? (typeof md.node_set === 'string' ? md.node_set : null);
-        const ver = existing?.entry?.version;
-        return bridgeStoreEntry({
-            key: o.id,
-            value: `${o.name} — ${derived.description || bestType}`,
-            namespace: o.ns.nodes,
-            dbPath: o.dbPath,
-            upsert: true,
-            tags: ['kg', normalizeName(bestType), ...(nodeSet ? [normalizeName(nodeSet)] : [])],
-            metadata: {
-                ...md,
-                kg: 'node',
-                id_version: KG_ID_VERSION,
-                type: bestType,
-                name: o.name,
-                node_set: nodeSet,
-                ...derived,
-                // A placeholder stops being one the moment a real assertion describes it.
-                placeholder: o.placeholder === true && !derived.description ? true : undefined,
-                version: (typeof md.version === 'number' ? md.version : 0) + 1,
-                valid_from: md.valid_from ?? Date.now(),
-                valid_to: null,
-            },
-            // isNew ⇒ this row must not already exist; otherwise it must still be at
-            // the version we just read. Absent when the loaded backend/test double
-            // does not report a version, so behaviour is unchanged there (see
-            // bridgeGetEntry's `version` field).
-            ifVersion: isNew ? 'absent' : typeof ver === 'number' ? ver : undefined,
-        });
-    });
-    // Name first: the ID is a digest, and a failure message a human cannot map
-    // back to the thing that failed is not a diagnosis.
-    if (o.failures.add(res, `node ${o.name} (${o.id})`))
-        return null;
-    // Only after the write landed: a refused write dropped no provenance, because
-    // it changed nothing.
-    o.report.noteProvenanceLoss(md, derived);
-    return isNew;
-}
-/** The accepted/rejected/truncated bookkeeping a caller needs in order to know
- *  that what it sent is what the graph holds. */
-class IngestReport {
-    nodesRejected = 0;
-    edgesRejected = 0;
-    nodesTruncated = 0;
-    edgesTruncated = 0;
-    placeholders = 0;
-    provenanceTruncated = 0;
-    rejections = [];
-    ambiguities = [];
-    rejectNode(message) {
-        this.nodesRejected++;
-        if (this.rejections.length < MAX_FAILURES)
-            this.rejections.push(message);
-    }
-    rejectEdge(message) {
-        this.edgesRejected++;
-        if (this.rejections.length < MAX_FAILURES)
-            this.rejections.push(message);
-    }
-    noteAmbiguity(name, candidates) {
-        if (!candidates.length || this.ambiguities.length >= MAX_FAILURES)
-            return;
-        const types = candidates.map((c) => c.type || 'untyped').join(', ');
-        this.ambiguities.push(`${name}: kept separate from ${candidates.length} same-name (${types})`);
-    }
-    noteProvenanceLoss(md, derived) {
-        const before = typeof md.origins_dropped === 'number' ? md.origins_dropped : 0;
-        if (derived.origins_dropped > before)
-            this.provenanceTruncated++;
-    }
-    /** Only non-zero counters are emitted, so a clean payload yields a clean
-     *  result and the existing `KgIngestResult` shape is unchanged for callers
-     *  that construct it themselves. */
-    fields() {
-        return {
-            ...(this.nodesRejected ? { nodesRejected: this.nodesRejected } : {}),
-            ...(this.edgesRejected ? { edgesRejected: this.edgesRejected } : {}),
-            ...(this.nodesTruncated ? { nodesTruncated: this.nodesTruncated } : {}),
-            ...(this.edgesTruncated ? { edgesTruncated: this.edgesTruncated } : {}),
-            ...(this.rejections.length ? { rejections: this.rejections } : {}),
-            ...(this.placeholders ? { placeholders: this.placeholders } : {}),
-            ...(this.ambiguities.length ? { ambiguities: this.ambiguities } : {}),
-            ...(this.provenanceTruncated ? { provenanceTruncated: this.provenanceTruncated } : {}),
-        };
-    }
-}
-/** Stage-2 of cognee's curator/writer distillation: the CALLER (an LLM agent)
- *  proposes candidate rules; this accepts each unless a semantically
- *  near-identical rule exists (embedding dedup — deterministic keys can't
- *  collapse paraphrases). Accepted rules are stored both as KG nodes
- *  (node_set=rules) and as plain `rules`-namespace entries so the existing
- *  injection/search surfaces pick them up with zero new plumbing.
- *
- *  A candidate that dedups against an existing rule still ADDS its origin to
- *  that rule's support set: two independent runs asserting the same rule mean
- *  the rule survives either one being rolled back. Dropping the second origin
- *  (as this used to) made rollback of the FIRST run delete knowledge the
- *  second run independently vouched for.
- *
- *  Like `kgIngest`, NOT atomic — see that function's note. */
-export async function kgIngestRules(options) {
-    const verdicts = [];
-    const threshold = options.dedupThreshold ?? 0.78;
-    const failures = new FailureLog();
-    const ns = kgNamespaces(options.scope);
-    // Direct writes here store the qualified ref; nested kgIngest calls get the
-    // RAW ref plus the scope and qualify it themselves, so it is stamped once.
-    const originRef = kgQualifyOrigin(options.originRef, options.scope);
-    let accepted = 0;
-    const all = options.rules ?? [];
-    const batch = all.slice(0, MAX_RULES_PER_CALL);
-    const rulesTruncated = all.length - batch.length;
-    try {
-        for (const r of batch) {
-            const rule = r?.rule?.trim();
-            if (!rule || rule.length < 8) {
-                verdicts.push({ rule: r?.rule ?? '', verdict: 'invalid' });
-                continue;
-            }
-            const similar = await bridgeSearchEntries({
-                query: rule,
-                namespace: ns.rules,
-                limit: 1,
-                threshold,
-                dbPath: options.dbPath,
-            });
-            const top = similar?.results?.[0];
-            // Issue #111: FTS5 keyword scores are min-max normalized per batch.
-            // With limit:1, the sole result always scores 1.0 — any rule sharing
-            // even one keyword was falsely marked as a duplicate.
-            //
-            // Only trust embedding-backed (semantic) cosine scores for dedup.
-            // Keyword-only matches can't distinguish paraphrases from merely
-            // overlapping vocabulary — fall back to exact-text comparison.
-            // (Key-based upsert on store already handles identical keys.)
-            const provenance = top?.provenance;
-            let isDuplicate = false;
-            if (top && provenance?.startsWith('semantic:')) {
-                const rawCosine = parseFloat(provenance.slice('semantic:'.length));
-                isDuplicate = rawCosine >= threshold;
-            }
-            else if (top) {
-                // Keyword-only: only suppress true near-exact duplicates.
-                const existing = (top.content || '').replace(/\s+/g, ' ').trim().toLowerCase();
-                const candidate = rule.replace(/\s+/g, ' ').trim().toLowerCase();
-                isDuplicate = existing === candidate;
-            }
-            if (isDuplicate && top?.key) {
-                // `already_known` is a claim that this origin now supports the existing
-                // rule. If reinforcement did not land, it does not — and a later
-                // rollback of the OTHER origin would delete a rule this run believes it
-                // vouched for.
-                const reinforced = await reinforceRuleOrigin(top.key, top.content, options.originRef, options.scope, options.dbPath, failures);
-                verdicts.push({
-                    rule,
-                    verdict: reinforced ? 'already_known' : 'failed',
-                    similarTo: top.key,
-                });
-                continue;
-            }
-            // Identity is the full rule text. The old key truncated at 120 normalized
-            // characters, so two rules sharing a long preamble were the same rule.
-            // A rule stored under that scheme is adopted in place rather than
-            // duplicated under the new key.
-            let key = ruleKey(rule);
-            let priorMd = {};
-            const current = await bridgeGetEntry({ key, namespace: ns.rules, dbPath: options.dbPath });
-            if (current?.found && current.entry)
-                priorMd = current.entry.metadata;
-            else {
-                const legacy = legacyRuleKey(rule);
-                const hit = await bridgeGetEntry({
-                    key: legacy,
-                    namespace: ns.rules,
-                    dbPath: options.dbPath,
-                });
-                if (hit?.found && hit.entry) {
-                    key = legacy;
-                    priorMd = hit.entry.metadata;
-                }
-            }
-            // The mirrored KG node is named by the FULL rule text. Truncating it to
-            // 200 characters put two rules sharing a long preamble on one node — the
-            // same collision `ruleKey` was just widened to prevent, reintroduced one
-            // namespace over.
-            const ruleName = rule;
-            const stored = await bridgeStoreEntry({
-                key,
-                value: rule + (r.context ? `\n(context: ${r.context.slice(0, 500)})` : ''),
-                namespace: ns.rules,
-                dbPath: options.dbPath,
-                upsert: true,
-                tags: ['rule'],
-                metadata: {
-                    ...priorMd,
-                    ...applyClaim(priorMd, originRef, rule, Date.now()),
-                    id_version: KG_ID_VERSION,
-                    derived_from: originRef,
-                    // Lets the dedup path reinforce the matching KG node without having
-                    // to re-derive the node name from the stored value (which may carry
-                    // an appended context block).
-                    rule: ruleName,
-                },
-            });
-            const nodeRes = await kgIngest({
-                nodes: [{ name: ruleName, type: 'Rule', description: rule, nodeSet: 'rules' }],
-                originRef: options.originRef,
-                scope: options.scope,
-                dbPath: options.dbPath,
-            });
-            const ruleFailed = failures.add(stored, `rule ${key}`);
-            if (!ruleFailed)
-                await onEntrySupported(ns, ns.rules, key, originRef, options.dbPath);
-            if (nodeRes.failures?.length)
-                for (const m of nodeRes.failures)
-                    failures.note(m);
-            // Only count a rule as accepted when BOTH of its writes landed; a rule
-            // present in one namespace only is not the state the caller was told
-            // about. The per-rule verdict now says the same thing — it read
-            // `accepted` unconditionally, so the two halves of one result disagreed.
-            const landed = !ruleFailed && nodeRes.success;
-            if (landed)
-                accepted++;
-            verdicts.push({ rule, verdict: landed ? 'accepted' : 'failed' });
-        }
-        return {
-            success: !failures.failed,
-            verdicts,
-            accepted,
-            ...(failures.failed ? { failures: failures.messages, error: failures.summary() } : {}),
-            ...(rulesTruncated ? { rulesTruncated } : {}),
-        };
-    }
-    catch (err) {
-        return {
-            success: false,
-            verdicts,
-            accepted,
-            ...(failures.messages.length ? { failures: failures.messages } : {}),
-            ...(rulesTruncated ? { rulesTruncated } : {}),
-            error: err instanceof Error ? err.message : String(err),
-        };
-    }
-}
-/** Add `originRef` to an already-stored rule's support set — both the
- *  `rules`-namespace entry and its `node_set=rules` KG node. Idempotent in
- *  effect: re-asserting an origin the rule already carries leaves the support
- *  set unchanged.
- *
- *  @returns true when the rule genuinely carries this origin afterwards —
- *  including the no-op case where it already did. False means the support set
- *  is not what the caller is about to be told it is. */
-async function reinforceRuleOrigin(matchedKey, matchedContent, 
-/** RAW ref — qualified here for the rules entry, and passed on unqualified
- *  to `kgIngest`, which qualifies it once with the same scope. */
-originRef, scope, dbPath, failures) {
-    const ns = kgNamespaces(scope);
-    const qualified = kgQualifyOrigin(originRef, scope);
-    const existing = await bridgeGetEntry({ key: matchedKey, namespace: ns.rules, dbPath });
-    if (!existing?.found || !existing.entry) {
-        // The dedup hit came from search; if the entry can't be re-read by key the
-        // support set cannot be updated, and silently proceeding is exactly the
-        // provenance loss this function exists to prevent.
-        failures.note(`rule ${matchedKey}: matched by dedup but not readable by key`);
-        return false;
-    }
-    const entry = existing.entry;
-    const md = entry.metadata;
-    const origins = Array.isArray(md.origin_refs) ? md.origin_refs : [];
-    // The KG node's name: recorded at accept time, else the first line of the
-    // stored value (any context block is appended after a newline).
-    const ruleName = typeof md.rule === 'string' && md.rule
-        ? md.rule
-        : (matchedContent || entry.content).split('\n')[0];
-    // Both writes are attempted regardless: skipping the node write because the
-    // entry write failed would leave the two halves disagreeing about who
-    // supports this rule. Only the REPORT changes.
-    let ok = true;
-    if (!origins.includes(qualified)) {
-        const res = await bridgeStoreEntry({
-            key: entry.key,
-            value: entry.content,
-            namespace: ns.rules,
-            dbPath,
-            upsert: true,
-            generateEmbeddingFlag: entry.hasEmbedding,
-            tags: entry.tags,
-            metadata: {
-                ...md,
-                rule: ruleName,
-                // A dedup hit is SUPPORT, not a correction: the candidate asserts the
-                // rule the entry already holds. Its contribution therefore carries no
-                // description of its own — passing one here (the truncated `rule` name,
-                // as this did) made the newest claim disagree with the stored text and
-                // flagged the rule as conflicted with a truncation of itself.
-                ...applyClaim(md, qualified, '', Date.now()),
-            },
-        });
-        if (failures.add(res, `rule ${entry.key}`))
-            ok = false;
-        else
-            await onEntrySupported(ns, ns.rules, entry.key, qualified, dbPath);
-    }
-    // The rule's KG node needs the same origin — rollback walks nodes separately.
-    const nodeRes = await kgIngest({
-        nodes: [{ name: ruleName, type: 'Rule', description: '', nodeSet: 'rules' }],
-        originRef,
-        scope,
-        dbPath,
-    });
-    if (nodeRes.failures?.length)
-        for (const m of nodeRes.failures)
-            failures.note(m);
-    return ok && nodeRes.success;
-}
-/** List stored rules (for injection or review). */
-export async function kgListRules(options) {
-    const res = await bridgeListEntries({
-        namespace: kgNamespaces(options?.scope).rules,
-        limit: options?.limit ?? 50,
-        dbPath: options?.dbPath,
-    });
-    return (res?.entries ?? []).map((e) => ({ rule: e.content, key: e.key }));
-}
-/** Seed candidates pulled before filtering and ranking. */
-const SEARCH_SEED_LIMIT = 15;
-/** Extra candidates fetched when a `nodeSet` narrows the graph.
- *
- *  The bridge has no tag filter, so set membership can only be tested after
- *  retrieval. Filtering the unfiltered top-15 meant a node that IS in the set
- *  but ranks 16th overall was missed — the set made results scarcer instead of
- *  more precise. Over-fetching moves the cutoff after the filter. */
-const SEARCH_NODE_SET_OVERFETCH = 4;
-/** How far a co-occurrence guess drops below an equally-seeded stated fact.
- *  Enough to lose a tie, not enough to hide it: `mentioned_with` between two
- *  strong seeds is still worth surfacing when nothing better was asserted. */
-const HEURISTIC_PENALTY = 0.15;
-/** Live origins disagree about what this edge says. Still returned — a disputed
- *  fact is information — but it does not outrank a settled one. */
-const CONFLICT_PENALTY = 0.1;
-/** Seeded retrieval → neighborhood → triplet ranking (cognee's brute-force
- *  triplet search, scaled down). Seed scores already carry the Phase 1 feedback
- *  blend, and the seed retrieval may be vector or keyword — `method` on the
- *  result says which actually ran.
- *
- *  Ranking weighs exactly two evidence signals, both read off the claim ledger:
- *  extraction method and description conflict. It deliberately does NOT model
- *  source credibility, claim freshness, or whether the relation itself answers
- *  the query — those need an evaluation set to tune against, and guessing at
- *  them would be the same overclaim this weighting exists to correct. */
-export async function kgSearch(options) {
-    try {
-        const limit = options.limit ?? 8;
-        const ns = kgNamespaces(options.scope);
-        const seedsRes = await bridgeSearchEntries({
-            query: options.query,
-            namespace: ns.nodes,
-            // Over-fetch when a set filter follows, so the cutoff lands AFTER it.
-            limit: options.nodeSet ? SEARCH_SEED_LIMIT * SEARCH_NODE_SET_OVERFETCH : SEARCH_SEED_LIMIT,
-            threshold: 0.25,
-            dbPath: options.dbPath,
-        });
-        // What the retrieval actually was, carried on every return below: a keyword
-        // fallback presented as vector-seeded search is the overclaim B5 names.
-        const retrieval = {
-            ...(seedsRes?.searchMethod ? { method: seedsRes.searchMethod } : {}),
-            ...(seedsRes?.fallbackReason ? { fallbackReason: seedsRes.fallbackReason } : {}),
-        };
-        let seedResults = seedsRes?.results ?? [];
-        if (options.nodeSet) {
-            const setTag = normalizeName(options.nodeSet);
-            seedResults = seedResults.filter((r) => (r.tags ?? []).includes(setTag));
-        }
-        seedResults = seedResults.slice(0, SEARCH_SEED_LIMIT);
-        if (!seedResults.length)
-            return { success: true, context: '', triplets: [], seeds: [], ...retrieval };
-        const seedScore = new Map();
-        for (const s of seedResults)
-            seedScore.set(s.key, s.score);
-        const triplets = [];
-        let scannedEdges = 0;
-        let truncated = false;
-        /** Score one edge against the seeded entities and, if relevant, push its
-         *  triplet — shared by the indexed and exhaustive gathering paths below
-         *  so ranking never depends on which one ran (K7). */
-        const considerEdge = (e) => {
-            scannedEdges++;
-            const md = (e.metadata ?? {});
-            if (md?.kg !== 'edge' || md.valid_to != null)
-                return;
-            const src = String(md.src ?? '');
-            const dst = String(md.dst ?? '');
-            const sSrc = seedScore.get(src) ?? 0;
-            const sDst = seedScore.get(dst) ?? 0;
-            if (sSrc === 0 && sDst === 0)
-                return;
-            // Both endpoints seeded beats one; the unseeded endpoint contributes a
-            // neutral 0.35 so bridging edges from a strong seed still surface.
-            const relevance = (Math.max(sSrc, 0.35) + Math.max(sDst, 0.35)) / 2 + (sSrc > 0 && sDst > 0 ? 0.1 : 0);
-            // Evidence, from the claim ledger. An edge whose method was never
-            // recorded is left at its relevance score — unknown is not evidence
-            // against it, and penalizing it would demote the entire pre-existing
-            // graph relative to anything written today.
-            const method = md.method === 'asserted' || md.method === 'heuristic'
-                ? md.method
-                : undefined;
-            const conflict = md.conflict === true;
-            const score = Math.max(0, relevance -
-                (method === 'heuristic' ? HEURISTIC_PENALTY : 0) -
-                (conflict ? CONFLICT_PENALTY : 0));
-            triplets.push({
-                source: String(md.source_name ?? src),
-                relation: String(md.relation ?? 'related_to'),
-                target: String(md.target_name ?? dst),
-                fact: e.content,
-                score,
-                ...(method ? { method } : {}),
-                ...(conflict ? { conflict } : {}),
-                id: e.id,
-                key: e.key,
-            });
-        };
-        // Scores are per-edge, so pruning to the running top-`limit` after every
-        // batch yields exactly the same result as sorting the whole set at the end.
-        const pruneToLimit = () => {
-            if (triplets.length > limit) {
-                triplets.sort((a, b) => b.score - a.score);
-                triplets.length = limit;
-            }
-        };
-        // K7: gather candidate edges via each seed's adjacency entry — O(seeds ×
-        // degree) instead of a full namespace scan — when the scope's index is
-        // ready and every seed's adjacency entry resolves. Any seed that misses
-        // (index not ready, or an unresolvable ref) falls the WHOLE query back to
-        // the exhaustive scan rather than silently searching only some seeds.
-        let covered = false;
-        let usedIndex = false;
-        if ((await readIndexStatus(ns, options.dbPath)).state === 'ready') {
-            const candidateKeys = new Set();
-            let indexOk = true;
-            for (const s of seedResults) {
-                const adj = await readAdj(ns, s.key, options.dbPath);
-                if (adj === null) {
-                    indexOk = false;
-                    break;
-                }
-                for (const key of adj.edgeKeys)
-                    candidateKeys.add(key);
-            }
-            if (indexOk) {
-                for (const key of candidateKeys) {
-                    const res = await bridgeGetEntry({ key, namespace: ns.edges, dbPath: options.dbPath });
-                    if (res?.found && res.entry)
-                        considerEdge(res.entry);
-                }
-                pruneToLimit();
-                usedIndex = true;
-                covered = true;
-            }
-        }
-        // Paged edge scan (see monolean note in module header). Each page is folded
-        // into the running top-`limit` immediately, so memory stays at one page
-        // regardless of how many edges the namespace holds.
-        if (!usedIndex) {
-            covered = await scanNamespace(ns.edges, options.dbPath, (page) => {
-                for (const e of page)
-                    considerEdge(e);
-                pruneToLimit();
-                if (scannedEdges >= SEARCH_EDGE_SCAN_MAX) {
-                    truncated = true;
-                    return false;
-                }
-                return true;
-            });
-        }
-        // An unreadable namespace is an incomplete answer, not an empty graph.
-        if (!covered)
-            truncated = true;
-        triplets.sort((a, b) => b.score - a.score);
-        const seeds = seedResults.slice(0, limit).map((s) => {
-            // metadata is not in search results; parse from rendered content "name — description"
-            const dash = s.content.indexOf(' — ');
-            return {
-                name: dash > 0 ? s.content.slice(0, dash) : s.key,
-                // Tags carry the stored type (`['kg', <type>, …]`). The key never did:
-                // reading `key.split(':')[1]` reported the type of `n:shared_service`
-                // as `shared_service`, and under hashed IDs would report a digest.
-                type: (s.tags ?? [])[1] ?? 'entity',
-                description: dash > 0 ? s.content.slice(dash + 3) : s.content,
-                score: s.score,
-                id: s.id,
-            };
-        });
-        const context = [
-            ...triplets.map((t) => `${t.source} —${t.relation}→ ${t.target}${t.fact && t.fact !== `${t.source} ${t.relation} ${t.target}` ? ` (${t.fact})` : ''}`),
-            ...(triplets.length ? [] : seeds.map((s) => `${s.name}: ${s.description}`)),
-        ].join('\n');
-        return {
-            success: true,
-            context,
-            triplets,
-            seeds,
-            scannedEdges,
-            ...(truncated && { truncated }),
-            ...retrieval,
-        };
-    }
-    catch (err) {
-        return {
-            success: false,
-            context: '',
-            triplets: [],
-            seeds: [],
-            error: err instanceof Error ? err.message : String(err),
-        };
-    }
-}
-// ── Glossary (anti-duplicate-entity injection for extraction prompts) ──
-export async function kgGlossary(options) {
-    const limit = options?.limit ?? 40;
-    // Running top-`limit` by rank, deduplicated by normalized name. Folding each
-    // page in and pruning keeps the whole node namespace in scope without ever
-    // holding more than a page plus `limit` names.
-    let top = [];
-    await scanNamespace(kgNamespaces(options?.scope).nodes, options?.dbPath, (page) => {
-        for (const e of page) {
-            const md = e.metadata;
-            // Glossary is for ENTITY name reuse — rule prose and extraction-source
-            // Session nodes would drown it.
-            const t = String(md?.type ?? '').toLowerCase();
-            if (md?.node_set === 'rules' || t === 'rule' || t === 'session')
-                continue;
-            const fw = typeof md.feedback_weight === 'number' ? md.feedback_weight : 0.5;
-            const freq = typeof md.frequency_weight === 'number' ? md.frequency_weight : 0;
-            const version = typeof md.version === 'number' ? md.version : 1;
-            const name = String(md.name ?? e.key);
-            top.push({ name, norm: normalizeName(name), rank: version + freq + fw });
-        }
-        top.sort((a, b) => b.rank - a.rank);
-        const seen = new Set();
-        const pruned = [];
-        for (const n of top) {
-            if (seen.has(n.norm))
-                continue;
-            seen.add(n.norm);
-            pruned.push(n);
-            if (pruned.length >= limit)
-                break;
-        }
-        top = pruned;
-    });
-    return top.map((n) => n.name);
-}
-// ── Rollback (per-origin bad-ingest recovery) ───────────────────────
-function originsOf(entry) {
-    const origins = (entry.metadata ?? {}).origin_refs;
-    return Array.isArray(origins) ? origins : [];
-}
-/** Every entry in `namespace` that `originRef` supports, collected by an
- *  EXHAUSTIVE paged scan. `covered` is false when the backend became
- *  unreadable partway — an incomplete answer, never an empty one.
- *
- *  Collecting rather than streaming is required by the callers that mutate:
- *  deleting a row pulls later rows back, so an advancing offset would skip
- *  whatever slid into the gap. Only origin-carrying entries are retained, so
- *  memory tracks the operation's own footprint, not the namespace size. */
-async function collectByOrigin(namespace, originRef, dbPath) {
-    const entries = [];
-    const covered = await scanNamespace(namespace, dbPath, (page) => {
-        for (const e of page)
-            if (originsOf(e).includes(originRef))
-                entries.push(e);
-    });
-    return { entries, covered };
-}
-/** Withdraw `originRef`'s support from the graph: remove it from every
- *  node/edge/rule it backs, and delete the element once no origin remains.
- *
- *  The withdrawn ref is REWRITTEN out of the surviving elements' origin lists,
- *  not left behind. Retaining it (as this used to) meant a second rollback saw
- *  a two-entry list and retained again — so an element could outlive the
- *  withdrawal of every origin that ever supported it.
- *
- *  The scan is EXHAUSTIVE: it pages each namespace to the end rather than
- *  reading one capped list. A capped scan let an element past the cap keep a
- *  withdrawn origin while the caller was told the rollback succeeded.
- *
- *  Collect-then-mutate is deliberate: deleting a row pulls every later row back
- *  one position, so a delete inside the page loop would make an advancing
- *  offset skip whatever slid into the gap. (Rewrites are no longer a hazard —
- *  the bridge's upsert reuses the existing entry id and preserves `createdAt`
- *  rather than re-inserting at the head of the default ordering — but this
- *  function deletes as well as rewrites.) Only origin-carrying entries are
- *  retained during the scan, so memory tracks the rollback's own footprint, not
- *  the namespace size. */
-export async function kgRollback(options) {
-    const failures = new FailureLog();
-    const namespaces = kgNamespaces(options.scope);
-    const originRef = kgQualifyOrigin(options.originRef, options.scope);
-    let deleted = 0, retained = 0;
-    /** Entity IDs this rollback removed, and the names that pointed at them. */
-    const removedIds = new Set();
-    const removedNames = new Set();
-    try {
-        // K7: one indexed read across all three namespaces, tried before the
-        // exhaustive per-namespace scan. Only trusted when the scope's index is
-        // `ready` AND every ref it names still resolves — `kgIndexedByOrigin`
-        // returns null otherwise, and this falls straight back to the scan.
-        let indexedByNs = null;
-        if ((await readIndexStatus(namespaces, options.dbPath)).state === 'ready') {
-            const indexed = await kgIndexedByOrigin(namespaces, originRef, options.dbPath);
-            if (indexed !== null) {
-                indexedByNs = new Map([
-                    [namespaces.nodes, []],
-                    [namespaces.edges, []],
-                    [namespaces.rules, []],
-                ]);
-                for (const { ns, entry } of indexed)
-                    indexedByNs.get(ns)?.push(entry);
-            }
-        }
-        for (const ns of [namespaces.nodes, namespaces.edges, namespaces.rules]) {
-            const found = indexedByNs
-                ? { entries: indexedByNs.get(ns) ?? [], covered: true }
-                : await collectByOrigin(ns, originRef, options.dbPath);
-            // A partial scan cannot be reported as a completed withdrawal.
-            if (!found.covered) {
-                failures.note(`${ns}: memory backend unavailable`);
-                continue;
-            }
-            const withdrawn = found.entries.map((e) => ({
-                entry: e,
-                // Re-derive from the claim ledger rather than editing an origin list:
-                // this is what puts back the description a withdrawn origin overwrote.
-                remaining: withoutOrigin((e.metadata ?? {}), originRef),
-            }));
-            for (const { entry: e, remaining } of withdrawn) {
-                const md = (e.metadata ?? {});
-                if (remaining === null) {
-                    const del = await bridgeDeleteEntry({ id: e.id, namespace: ns, dbPath: options.dbPath });
-                    if (del?.deleted) {
-                        deleted++;
-                        await onOriginWithdrawn(namespaces, ns, e.key, originRef, options.dbPath);
-                        await onEntryDeleted(namespaces, e.key, options.dbPath, ns === namespaces.edges
-                            ? { src: String(md.src ?? ''), dst: String(md.dst ?? '') }
-                            : undefined);
-                    }
-                    else
-                        failures.note(`${ns}/${e.key}: delete failed`);
-                    if (ns === namespaces.nodes && del?.deleted) {
-                        removedIds.add(e.key);
-                        if (typeof md.name === 'string')
-                            removedNames.add(md.name);
-                    }
-                    continue;
-                }
-                const store = await bridgeStoreEntry({
-                    key: e.key,
-                    value: rerender(e.content, md, remaining.description, ns === namespaces.rules),
-                    namespace: ns,
-                    dbPath: options.dbPath,
-                    upsert: true,
-                    // Edges are stored without embeddings; re-deriving one here would
-                    // silently change how the entry behaves in search.
-                    generateEmbeddingFlag: e.hasEmbedding,
-                    tags: e.tags,
-                    metadata: { ...md, ...remaining },
-                });
-                if (!failures.add(store, `${ns}/${e.key}: origin withdrawal`)) {
-                    retained++;
-                    await onOriginWithdrawn(namespaces, ns, e.key, originRef, options.dbPath);
-                }
-            }
-        }
-        // Drop the removed entities out of the name index, so a later ingest of the
-        // same name does not resolve onto an entity that no longer exists.
-        for (const name of removedNames) {
-            const known = await readNameIndex(name, namespaces, options.dbPath);
-            if (known === null) {
-                // An unreadable index must not be rewritten from a guess — doing so
-                // would erase every same-name entity this rollback did NOT remove.
-                failures.note(`${namespaces.names}: name index unreadable for ${name}`);
-                continue;
-            }
-            const survivors = known.filter((c) => !removedIds.has(c.id));
-            if (survivors.length !== known.length)
-                await writeNameIndex(name, survivors, namespaces, options.dbPath, failures);
-        }
-        const danglingEdgesRemoved = removedIds.size
-            ? await removeEdgesMissingEndpoints(namespaces, removedIds, options.dbPath, failures)
-            : 0;
-        return {
-            success: !failures.failed,
-            deleted,
-            retained,
-            ...(failures.failed ? { failures: failures.messages, error: failures.summary() } : {}),
-            ...(danglingEdgesRemoved ? { danglingEdgesRemoved } : {}),
-        };
-    }
-    catch (err) {
-        return {
-            success: false,
-            deleted,
-            retained,
-            ...(failures.messages.length ? { failures: failures.messages } : {}),
-            error: err instanceof Error ? err.message : String(err),
-        };
-    }
-}
-/** Re-render a stored value after its derived description changed.
- *
- *  Rules are left alone: their value is the rule text plus an optional context
- *  block, not a rendering of a description. */
-function rerender(content, md, description, isRule) {
-    if (isRule || description === md.description)
-        return content;
-    if (md.kg === 'edge')
-        return description || `${md.source_name} ${md.relation} ${md.target_name}`;
-    return `${md.name} — ${description || md.type}`;
-}
-/** Delete every edge incident to one of `removedIds`. Collect-then-mutate for
- *  the same reason `kgRollback` does. */
-async function removeEdgesMissingEndpoints(ns, removedIds, dbPath, failures) {
-    const doomed = [];
-    const covered = await scanNamespace(ns.edges, dbPath, (page) => {
-        for (const e of page) {
-            const md = (e.metadata ?? {});
-            const src = String(md.src ?? '');
-            const dst = String(md.dst ?? '');
-            if (removedIds.has(src) || removedIds.has(dst))
-                doomed.push({ entry: e, src, dst });
-        }
-    });
-    if (!covered) {
-        failures.note(`${ns.edges}: memory backend unavailable during dangling-edge sweep`);
-        return 0;
-    }
-    let removed = 0;
-    for (const { entry: e, src, dst } of doomed) {
-        const del = await bridgeDeleteEntry({ id: e.id, namespace: ns.edges, dbPath });
-        if (del?.deleted) {
-            removed++;
-            // Only the surviving endpoint needs its adjacency entry pruned — the
-            // removed one's own entry is moot, its entity is gone too.
-            await onEntryDeleted(ns, e.key, dbPath, {
-                src: removedIds.has(src) ? dst : src,
-                dst: removedIds.has(src) ? dst : src,
-            });
-        }
-        else
-            failures.note(`${ns.edges}/${e.key}: dangling-edge delete failed`);
-    }
-    return removed;
-}
-/** Copy one origin's claims out of an org's scope into project-shared
- *  knowledge.
- *
- *  Sharing is deliberate, never a side effect of learning: `kgIngest` under a
- *  scope only ever writes that org's namespaces, and this is the one path a
- *  claim takes across the boundary. The org keeps its own copy untouched — the
- *  shared copy is an INDEPENDENT assertion under `promoted:<org-ref>`, so
- *  rolling back either side leaves the other standing, and a shared claim
- *  always names the org that vouched for it.
- *
- *  Like ingest, NOT atomic: the counters report what actually landed. */
-export async function kgPromote(options) {
-    const empty = { nodes: 0, edges: 0, rules: 0 };
-    if (!options.from?.org?.trim())
-        return {
-            success: false,
-            ...empty,
-            promotedAs: '',
-            error: 'promotion needs an owning org to promote from',
-        };
-    const ns = kgNamespaces(options.from);
-    const sourceRef = kgQualifyOrigin(options.originRef, options.from);
-    const promotedAs = `promoted:${sourceRef}`;
-    const failures = new FailureLog();
-    try {
-        const [nodeHits, edgeHits, ruleHits] = await Promise.all([
-            collectByOrigin(ns.nodes, sourceRef, options.dbPath),
-            collectByOrigin(ns.edges, sourceRef, options.dbPath),
-            collectByOrigin(ns.rules, sourceRef, options.dbPath),
-        ]);
-        // A partial read would promote a partial claim set while reporting the
-        // whole origin as shared.
-        for (const [name, hit] of [
-            ['nodes', nodeHits],
-            ['edges', edgeHits],
-            ['rules', ruleHits],
-        ])
-            if (!hit.covered)
-                failures.note(`${name}: memory backend unavailable`);
-        if (failures.failed)
-            return {
-                success: false,
-                ...empty,
-                promotedAs,
-                failures: failures.messages,
-                error: failures.summary(),
-            };
-        // Rule NODES are re-created by kgIngestRules; promoting them again through
-        // kgIngest would double-count and strip their rules-namespace entry.
-        const nodes = nodeHits.entries
-            .filter((e) => {
-            const md = (e.metadata ?? {});
-            return md.node_set !== 'rules' && String(md.type ?? '').toLowerCase() !== 'rule';
-        })
-            .map((e) => {
-            const md = (e.metadata ?? {});
-            return {
-                name: String(md.name ?? e.key),
-                type: String(md.type ?? 'entity'),
-                description: String(md.description ?? ''),
-                nodeSet: typeof md.node_set === 'string' ? md.node_set : undefined,
-            };
-        });
-        const edges = edgeHits.entries.map((e) => {
-            const md = (e.metadata ?? {});
-            return {
-                source: String(md.source_name ?? md.src ?? ''),
-                target: String(md.target_name ?? md.dst ?? ''),
-                relation: String(md.relation ?? 'related_to'),
-                description: String(md.description ?? ''),
-            };
-        });
-        const rules = ruleHits.entries.map((e) => {
-            const md = (e.metadata ?? {});
-            return { rule: String(md.rule ?? e.content.split('\n')[0]) };
-        });
-        let promotedNodes = 0, promotedEdges = 0, promotedRules = 0;
-        /** A batch that REJECTED part of what it was handed did not promote the
-         *  whole origin, so it cannot be reported as a clean share. Rejections are
-         *  not in `failures` — they are the caller's payload being refused, not the
-         *  bridge failing — so they have to be carried across explicitly. */
-        const carry = (res, what) => {
-            if (res.failures?.length)
-                for (const m of res.failures)
-                    failures.note(m);
-            const rejected = (res.nodesRejected ?? 0) + (res.edgesRejected ?? 0);
-            if (rejected)
-                failures.note(`${what}: ${rejected} item(s) rejected — ${res.rejections?.[0]}`);
-        };
-        // kgIngest caps a call at 500 nodes / 1000 edges, so a large origin has to
-        // be promoted in batches rather than silently truncated. Nodes go first so
-        // every edge endpoint already exists when the edges land.
-        for (let i = 0; i < nodes.length; i += MAX_NODES_PER_CALL) {
-            const res = await kgIngest({
-                nodes: nodes.slice(i, i + MAX_NODES_PER_CALL),
-                originRef: promotedAs,
-                dbPath: options.dbPath,
-            });
-            promotedNodes += res.nodesAdded + res.nodesMerged;
-            carry(res, 'promoted nodes');
-        }
-        for (let i = 0; i < edges.length; i += MAX_EDGES_PER_CALL) {
-            const res = await kgIngest({
-                nodes: [],
-                edges: edges.slice(i, i + MAX_EDGES_PER_CALL),
-                originRef: promotedAs,
-                dbPath: options.dbPath,
-            });
-            promotedEdges += res.edgesAdded + res.edgesMerged;
-            carry(res, 'promoted edges');
-        }
-        for (let i = 0; i < rules.length; i += MAX_RULES_PER_CALL) {
-            const res = await kgIngestRules({
-                rules: rules.slice(i, i + MAX_RULES_PER_CALL),
-                originRef: promotedAs,
-                dbPath: options.dbPath,
-            });
-            promotedRules += res.accepted;
-            if (res.failures?.length)
-                for (const m of res.failures)
-                    failures.note(m);
-            const invalid = res.verdicts.filter((v) => v.verdict === 'invalid').length;
-            if (invalid)
-                failures.note(`promoted rules: ${invalid} rejected as invalid`);
-        }
-        return {
-            success: !failures.failed,
-            nodes: promotedNodes,
-            edges: promotedEdges,
-            rules: promotedRules,
-            promotedAs,
-            ...(failures.failed ? { failures: failures.messages, error: failures.summary() } : {}),
-        };
-    }
-    catch (err) {
-        return {
-            success: false,
-            ...empty,
-            promotedAs,
-            ...(failures.messages.length ? { failures: failures.messages } : {}),
-            error: err instanceof Error ? err.message : String(err),
-        };
-    }
-}
-/** Entities whose descriptions are stale relative to their connectivity —
- *  the LLM half runs in the LIVE agent: it rewrites each candidate's
- *  description from the neighborhood facts and resubmits via memory_kg_ingest.
- *  A resubmission is a NEW contribution and therefore the current one, so a
- *  shorter but better-supported summary now wins; under "longest description
- *  wins" a consolidation that tightened the prose was silently discarded.
- *  No LLM here (fully local constraint). */
-export async function kgConsolidateCandidates(options) {
-    const minEdges = options?.minEdges ?? 3;
-    const limit = options?.limit ?? 10;
-    const ns = kgNamespaces(options?.scope);
-    // Degree index over the FULL edge namespace. Only the first 12 facts per node
-    // are kept (that is all the result exposes), so the index costs a bounded
-    // amount per node rather than one string per edge.
-    const degree = new Map();
-    await scanNamespace(ns.edges, options?.dbPath, (page) => {
-        for (const e of page) {
-            const md = e.metadata;
-            for (const end of [String(md.src ?? ''), String(md.dst ?? '')]) {
-                if (!end)
-                    continue;
-                const slot = degree.get(end) ?? { count: 0, facts: [] };
-                slot.count++;
-                if (slot.facts.length < 12)
-                    slot.facts.push(e.content);
-                degree.set(end, slot);
-            }
-        }
-    });
-    let candidates = [];
-    await scanNamespace(ns.nodes, options?.dbPath, (page) => {
-        for (const n of page) {
-            const md = n.metadata;
-            const slot = degree.get(n.key);
-            if (!slot || slot.count < minEdges)
-                continue;
-            const description = String(md.description ?? '');
-            // Cap the growth target at MAX_DESC_LEN — a very-high-degree node whose
-            // description is already at the cap can never "grow out" of candidacy and
-            // would otherwise permanently occupy a slot.
-            if (description.length >= Math.min(40 * slot.count, MAX_DESC_LEN))
-                continue;
-            candidates.push({
-                name: String(md.name ?? n.key),
-                type: String(md.type ?? 'entity'),
-                description,
-                edgeCount: slot.count,
-                neighborhood: slot.facts,
-            });
-        }
-        // Ranking is per-node, so keeping only the running top-`limit` after each
-        // page gives the same answer as ranking every node at the end.
-        candidates.sort((a, b) => b.edgeCount - a.edgeCount);
-        candidates = candidates.slice(0, limit);
-    });
-    return candidates;
-}
-// ── Stats ───────────────────────────────────────────────────────────
-/** Real counts, not page lengths. `bridgeListEntries.total` reports how many
- *  rows that one call returned, so the old capped list made a 10,001-node graph
- *  report exactly 10,000 forever.
- *
- *  Tries a real indexed `SELECT COUNT(*) WHERE namespace = ?` first
- *  (`bridgeCountEntries`, K7) — cheap and exact, since every row in a KG
- *  namespace is exactly one node/edge/rule (the name index lives in its own
- *  namespace). Falls back to the paginated scan — one query per 1,000 rows,
- *  still exact — when the loaded bridge predates `bridgeCountEntries`, or a
- *  test double doesn't stub it. */
-export async function kgStats(options) {
-    const ns = kgNamespaces(options?.scope);
-    const count = async (namespace) => {
-        try {
-            const real = await bridgeCountEntries(namespace, options?.dbPath);
-            if (real !== null)
-                return real;
-        }
-        catch {
-            /* bridgeCountEntries unavailable on this loaded bridge (or a test
-               double that doesn't stub it) — fall back to the exhaustive scan. */
-        }
-        let n = 0;
-        await scanNamespace(namespace, options?.dbPath, (page) => {
-            n += page.length;
-        });
-        return n;
-    };
-    const [nodes, edges, rules] = await Promise.all([
-        count(ns.nodes),
-        count(ns.edges),
-        count(ns.rules),
-    ]);
-    return { nodes, edges, rules };
-}
-/** Complete, uncapped read of every edge touching `endpointId` (as either
- *  src or dst) and/or asserted by `originRef` — at least one filter is
- *  required. This is the ground truth an indexed adjacency/origin lookup
- *  (K7) must agree with once one exists: an exhaustive paged scan, the same
- *  mechanism `kgRollback` already trusts for origin withdrawal, so it never
- *  depends on an index and never inherits the old first-page cap.
- *
- *  `truncated: true` means the scan did not finish — an incomplete answer,
- *  never an empty one. Callers comparing this against a future index must
- *  treat a truncated reference read as "unknown", not as "no matches". */
-export async function kgReferenceEdges(options) {
-    if (!options.endpointId && !options.originRef) {
-        return { success: false, edges: [], error: 'endpointId or originRef is required' };
-    }
-    const ns = kgNamespaces(options.scope);
-    const originRef = options.originRef
-        ? kgQualifyOrigin(options.originRef, options.scope)
-        : undefined;
-    const edges = [];
-    try {
-        const covered = await scanNamespace(ns.edges, options.dbPath, (page) => {
-            for (const e of page) {
-                const md = (e.metadata ?? {});
-                if (md.kg !== 'edge')
-                    continue;
-                const src = String(md.src ?? '');
-                const dst = String(md.dst ?? '');
-                if (options.endpointId && src !== options.endpointId && dst !== options.endpointId)
-                    continue;
-                const originRefs = originsOf(e);
-                if (originRef && !originRefs.includes(originRef))
-                    continue;
-                edges.push({
-                    key: e.key,
-                    src,
-                    dst,
-                    relation: String(md.relation ?? 'related_to'),
-                    originRefs,
-                });
-            }
-        });
-        return { success: true, edges, ...(covered ? {} : { truncated: true }) };
-    }
-    catch (err) {
-        return { success: false, edges, error: err instanceof Error ? err.message : String(err) };
-    }
-}
-const KG_INDEX_SCHEMA_VERSION = 1;
-const INDEX_STATUS_KEY = 'status';
-/** Edge keys recorded per adjacency entry before the index refuses to grow it
- *  further and fails the SCOPE's index rather than risk an oversized or
- *  silently truncated row. A hub node past this reads via the exhaustive
- *  scan, exactly as before the index existed — this only gates the fast
- *  path, never correctness. */
-const MAX_ADJ_EDGES_PER_NODE = 2000;
-/** Refs recorded per origin-support entry before the same refusal applies. */
-const MAX_ORIGIN_INDEX_REFS = 5000;
-async function readIndexStatus(ns, dbPath) {
-    const res = await bridgeGetEntry({ key: INDEX_STATUS_KEY, namespace: ns.indexStatus, dbPath });
-    if (!res?.found || !res.entry)
-        return { state: 'absent', schemaVersion: KG_INDEX_SCHEMA_VERSION };
-    const md = (res.entry.metadata ?? {});
-    // An older/foreign schema is not a resumable build — start over rather than
-    // trust rows shaped by a version this code no longer understands.
-    if (md.schemaVersion !== KG_INDEX_SCHEMA_VERSION) {
-        return { state: 'absent', schemaVersion: KG_INDEX_SCHEMA_VERSION };
-    }
-    return { ...md, schemaVersion: KG_INDEX_SCHEMA_VERSION };
-}
-async function writeIndexStatus(ns, status, dbPath) {
-    const res = await bridgeStoreEntry({
-        key: INDEX_STATUS_KEY,
-        value: `kg index: ${status.state}`,
-        namespace: ns.indexStatus,
-        dbPath,
-        upsert: true,
-        generateEmbeddingFlag: false,
-        metadata: { ...status, updatedAt: Date.now() },
-    });
-    return Boolean(res?.success);
-}
-/** Downgrade a scope's index to `failed` after a dual-write hiccup, so reads
- *  fall back to the exhaustive scan instead of silently drifting. Never
- *  throws — this runs from inside a best-effort maintenance path. */
-async function markIndexFailed(ns, dbPath, error) {
-    try {
-        const current = await readIndexStatus(ns, dbPath);
-        if (current.state === 'absent' || current.state === 'failed')
-            return; // nothing to protect
-        // Not resumable: the cursor here is stale (either a completed build's end
-        // position, or mid-build), and a dual-write hiccup means something is
-        // missing from an UNKNOWN part of the index — only a fresh rescan finds it.
-        await writeIndexStatus(ns, { ...current, state: 'failed', resumable: false, error }, dbPath);
-    }
-    catch {
-        /* best-effort: if even the downgrade write fails, the next rebuild's
-           validation step still catches an inconsistent index before it is
-           ever trusted for a read. */
-    }
-}
-/** This scope's derived-index build/readiness state. `absent` means no one
- *  has ever called `kgRebuildIndex` for it — every read behaves exactly as
- *  it did before this index existed. */
-export async function kgIndexStatus(options) {
-    return readIndexStatus(kgNamespaces(options?.scope), options?.dbPath);
-}
-async function readAdj(ns, entityId, dbPath) {
-    const res = await bridgeGetEntry({ key: entityId, namespace: ns.adj, dbPath });
-    if (!res)
-        return null; // backend unavailable, distinct from "no entry yet"
-    if (!res.found || !res.entry)
-        return { edgeKeys: [] };
-    const md = (res.entry.metadata ?? {});
-    return { edgeKeys: Array.isArray(md.edgeKeys) ? md.edgeKeys : [] };
-}
-async function addToAdj(ns, entityId, edgeKey, dbPath) {
-    const current = await readAdj(ns, entityId, dbPath);
-    if (current === null)
-        return false;
-    if (current.edgeKeys.includes(edgeKey))
-        return true; // already present, idempotent
-    if (current.edgeKeys.length >= MAX_ADJ_EDGES_PER_NODE)
-        return false;
-    const res = await bridgeStoreEntry({
-        key: entityId,
-        value: `kg adjacency: ${entityId}`,
-        namespace: ns.adj,
-        dbPath,
-        upsert: true,
-        generateEmbeddingFlag: false,
-        metadata: { edgeKeys: [...current.edgeKeys, edgeKey] },
-    });
-    return Boolean(res?.success);
-}
-async function removeFromAdj(ns, entityId, edgeKey, dbPath) {
-    const current = await readAdj(ns, entityId, dbPath);
-    if (current === null)
-        return false;
-    if (!current.edgeKeys.includes(edgeKey))
-        return true; // already absent
-    const res = await bridgeStoreEntry({
-        key: entityId,
-        value: `kg adjacency: ${entityId}`,
-        namespace: ns.adj,
-        dbPath,
-        upsert: true,
-        generateEmbeddingFlag: false,
-        metadata: { edgeKeys: current.edgeKeys.filter((k) => k !== edgeKey) },
-    });
-    return Boolean(res?.success);
-}
-async function readOriginIndex(ns, originRef, dbPath) {
-    const res = await bridgeGetEntry({ key: originRef, namespace: ns.originIdx, dbPath });
-    if (!res)
-        return null;
-    if (!res.found || !res.entry)
-        return { refs: [] };
-    const md = (res.entry.metadata ?? {});
-    return { refs: Array.isArray(md.refs) ? md.refs : [] };
-}
-async function addToOriginIndex(ns, originRef, ref, dbPath) {
-    const current = await readOriginIndex(ns, originRef, dbPath);
-    if (current === null)
-        return false;
-    if (current.refs.some((r) => r.ns === ref.ns && r.key === ref.key))
-        return true;
-    if (current.refs.length >= MAX_ORIGIN_INDEX_REFS)
-        return false;
-    const res = await bridgeStoreEntry({
-        key: originRef,
-        value: `kg origin index: ${originRef}`,
-        namespace: ns.originIdx,
-        dbPath,
-        upsert: true,
-        generateEmbeddingFlag: false,
-        metadata: { refs: [...current.refs, ref] },
-    });
-    return Boolean(res?.success);
-}
-async function removeFromOriginIndex(ns, originRef, ref, dbPath) {
-    const current = await readOriginIndex(ns, originRef, dbPath);
-    if (current === null)
-        return false;
-    const next = current.refs.filter((r) => !(r.ns === ref.ns && r.key === ref.key));
-    if (next.length === current.refs.length)
-        return true; // already absent
-    const res = await bridgeStoreEntry({
-        key: originRef,
-        value: `kg origin index: ${originRef}`,
-        namespace: ns.originIdx,
-        dbPath,
-        upsert: true,
-        generateEmbeddingFlag: false,
-        metadata: { refs: next },
-    });
-    return Boolean(res?.success);
-}
-// ── Dual-write hooks ──────────────────────────────────────────────────
-//
-// Best-effort and self-gating: a no-op (one status read) while the scope's
-// index is `absent`, so ordinary ingest/rollback pay nothing extra until
-// someone opts in by calling `kgRebuildIndex`. A failure here fails the
-// INDEX (downgrades the scope to `failed`), never the canonical write or
-// delete it accompanies — the index is a cache, not a second source of truth.
-/** After a node/edge/rule write lands, record that `originRef` supports it. */
-async function onEntrySupported(ns, entryNs, entryKey, originRef, dbPath) {
-    const status = await readIndexStatus(ns, dbPath);
-    if (status.state === 'absent' || status.state === 'failed')
-        return;
-    const ok = await addToOriginIndex(ns, originRef, { ns: entryNs, key: entryKey }, dbPath);
-    if (!ok)
-        await markIndexFailed(ns, dbPath, `origin index write failed for ${originRef}`);
-}
-/** After an edge write lands, record it in both endpoints' adjacency. */
-async function onEdgeWritten(ns, edgeKey, src, dst, dbPath) {
-    const status = await readIndexStatus(ns, dbPath);
-    if (status.state === 'absent' || status.state === 'failed')
-        return;
-    const okSrc = await addToAdj(ns, src, edgeKey, dbPath);
-    const okDst = src === dst ? true : await addToAdj(ns, dst, edgeKey, dbPath);
-    if (!okSrc || !okDst)
-        await markIndexFailed(ns, dbPath, `adjacency write failed for ${edgeKey}`);
-}
-/** After `kgRollback` deletes an entry outright (no origin left to support
- *  it), remove it from every index it could appear in. */
-async function onEntryDeleted(ns, entryKey, dbPath, endpoints) {
-    const status = await readIndexStatus(ns, dbPath);
-    if (status.state === 'absent' || status.state === 'failed')
-        return;
-    let ok = true;
-    if (endpoints) {
-        ok = (await removeFromAdj(ns, endpoints.src, entryKey, dbPath)) && ok;
-        if (endpoints.dst !== endpoints.src)
-            ok = (await removeFromAdj(ns, endpoints.dst, entryKey, dbPath)) && ok;
-    }
-    if (!ok)
-        await markIndexFailed(ns, dbPath, `adjacency removal failed for ${entryKey}`);
-}
-/** After `kgRollback` withdraws one origin's support from an entry that
- *  survives (another origin still supports it), drop just that origin's ref. */
-async function onOriginWithdrawn(ns, entryNs, entryKey, originRef, dbPath) {
-    const status = await readIndexStatus(ns, dbPath);
-    if (status.state === 'absent' || status.state === 'failed')
-        return;
-    const ok = await removeFromOriginIndex(ns, originRef, { ns: entryNs, key: entryKey }, dbPath);
-    if (!ok)
-        await markIndexFailed(ns, dbPath, `origin index removal failed for ${originRef}`);
-}
-// ── Indexed reads (used by kgSearch/kgRollback only when state === 'ready') ─
-/** The indexed equivalent of `kgReferenceEdges({ endpointId })`: edges
- *  touching one entity, read via its adjacency entry instead of a namespace
- *  scan. Returns `null` when any edge key it names cannot be resolved — a
- *  torn index must never be presented as a complete answer. */
-async function kgIndexedEdgesByEndpoint(ns, entityId, dbPath) {
-    const adj = await readAdj(ns, entityId, dbPath);
-    if (adj === null)
-        return null;
-    const edges = [];
-    for (const key of adj.edgeKeys) {
-        const res = await bridgeGetEntry({ key, namespace: ns.edges, dbPath });
-        if (!res?.found || !res.entry)
-            return null; // stale ref — do not half-answer
-        const md = (res.entry.metadata ?? {});
-        edges.push({
-            key,
-            src: String(md.src ?? ''),
-            dst: String(md.dst ?? ''),
-            relation: String(md.relation ?? 'related_to'),
-            originRefs: originsOf(res.entry),
-        });
-    }
-    return edges;
-}
-/** The indexed equivalent of `collectByOrigin`: every {namespace,key} entry
- *  one origin supports, read via its origin-index entry instead of scanning
- *  every namespace. Returns `null` on any unresolvable ref, same reasoning
- *  as `kgIndexedEdgesByEndpoint`. */
-/** Returns each entry paired with the namespace it was read from (from the
- *  index's own ref, not trusted from the entry itself) so a caller can sort
- *  results back into per-namespace buckets without guessing. */
-async function kgIndexedByOrigin(ns, originRef, dbPath) {
-    const idx = await readOriginIndex(ns, originRef, dbPath);
-    if (idx === null)
-        return null;
-    const entries = [];
-    for (const ref of idx.refs) {
-        const res = await bridgeGetEntry({ key: ref.key, namespace: ref.ns, dbPath });
-        if (!res?.found || !res.entry)
-            return null;
-        entries.push({ ns: ref.ns, entry: res.entry });
-    }
-    return entries;
-}
-// ── Rebuild (K7): the one function that builds/repairs the derived index ──
-/** Entities/origins sampled for post-build validation. A scan that saw fewer
- *  than this many distinct entities AND origins gets FULL validation, not a
- *  sample — most real scopes will. `KgRebuildResult.status.validation` says
- *  which happened, honestly, rather than letting "validated" imply "all". */
-const VALIDATE_SAMPLE = 200;
-function phaseOrder(phase) {
-    return phase === 'edges' ? 1 : phase === 'rules' ? 2 : 0;
-}
-function sameEdgeKeySet(a, b) {
-    const ak = new Set(a.map((e) => e.key));
-    const bk = new Set(b.map((e) => e.key));
-    if (ak.size !== bk.size)
-        return false;
-    for (const k of ak)
-        if (!bk.has(k))
-            return false;
-    return true;
-}
-/** (Re)build a scope's derived index from canonical data — nodes, then
- *  edges, then rules, that fixed order, resuming from the last checkpointed
- *  `{phase, offset}` rather than restarting when a prior call was
- *  interrupted mid-build. Every write here (`addToAdj`/`addToOriginIndex`)
- *  is idempotent, so a page reprocessed after an interruption cannot
- *  duplicate an entry.
- *
- *  A concurrent ingest/rollback during the build is safe, not just tolerated:
- *  the dual-write hooks run whenever state is not `absent`/`failed`, so a
- *  write made mid-build is captured whether or not the scan has reached that
- *  row yet — at worst twice, which idempotency absorbs for free. The one
- *  residual race (a row deleted between the scan reading it and the scan's
- *  own write landing) can leave a dangling ref in the index; it is never
- *  observable as wrong data, because every indexed READ
- *  (`kgIndexedEdgesByEndpoint`/`kgIndexedByOrigin`) returns `null` — and the
- *  caller falls back to the exhaustive scan — the instant it cannot resolve
- *  a ref it holds. This is the backend's real capability (single-row CAS,
- *  no cross-row transaction), used honestly rather than claiming atomicity
- *  it cannot provide.
- *
- *  Ends in `validating`: samples up to `VALIDATE_SAMPLE` of the entities and
- *  origins the scan actually saw, and re-reads them through the just-built
- *  index, comparing against a FRESH, independent reference read
- *  (`kgReferenceEdges`/`collectByOrigin`) — not the in-memory data the build
- *  itself computed, which would only prove the build agrees with itself. A
- *  write that silently failed, or a concurrent change the dual-write hooks
- *  missed, is exactly what this catches before the index is ever trusted. */
-export async function kgRebuildIndex(options) {
-    const ns = kgNamespaces(options?.scope);
-    const dbPath = options?.dbPath;
-    let status = await readIndexStatus(ns, dbPath);
-    // Resume from the checkpointed cursor for an interrupted build or a
-    // resumable (build-phase) failure; a fresh scan for everything else —
-    // `absent`, `ready` (this call IS the deliberate re-verify), and a
-    // validation-phase failure, where something already written was wrong.
-    const resume = status.state === 'building' || (status.state === 'failed' && status.resumable);
-    if (!resume) {
-        status = {
-            state: 'building',
-            schemaVersion: KG_INDEX_SCHEMA_VERSION,
-            cursor: { phase: 'nodes', offset: 0 },
-            counts: { nodes: 0, edges: 0, rules: 0 },
-            startedAt: Date.now(),
-        };
-        if (!(await writeIndexStatus(ns, status, dbPath))) {
-            return { success: false, status, error: 'could not persist initial build status' };
-        }
-    }
-    const seenEntities = [];
-    const seenOrigins = [];
-    const noteEntity = (id) => {
-        if (id && !seenEntities.includes(id) && seenEntities.length < VALIDATE_SAMPLE) {
-            seenEntities.push(id);
-        }
-    };
-    const noteOrigin = (ref) => {
-        if (!seenOrigins.includes(ref) && seenOrigins.length < VALIDATE_SAMPLE)
-            seenOrigins.push(ref);
-    };
-    // `addToAdj`/`addToOriginIndex` only APPEND onto whatever is already
-    // there. That's exactly right for a RESUME (everything present was
-    // written earlier in this same build attempt), but wrong for a FRESH
-    // build: a stale or corrupted entry left over from a PRIOR build (e.g.
-    // the exact thing a failed validation just caught) would never be
-    // cleared, only added to. So a fresh build clears both derived-index
-    // namespaces up front, once, before touching any phase — every write for
-    // the rest of THIS build attempt, in this call or a later one resuming
-    // it, can then safely append, because the namespace is known to hold only
-    // rows this attempt wrote.
-    if (!resume) {
-        const adjCleared = await clearNamespace(ns.adj, dbPath);
-        const originCleared = await clearNamespace(ns.originIdx, dbPath);
-        if (!adjCleared || !originCleared) {
-            status = { ...status, state: 'failed', error: 'could not clear prior index before rebuild' };
-            await writeIndexStatus(ns, status, dbPath);
-            return { success: false, status, error: status.error };
-        }
-    }
-    const phases = [
-        { phase: 'nodes', namespace: ns.nodes },
-        { phase: 'edges', namespace: ns.edges },
-        { phase: 'rules', namespace: ns.rules },
-    ];
-    try {
-        for (const { phase, namespace } of phases) {
-            if (phaseOrder(status.cursor?.phase) > phaseOrder(phase))
-                continue; // already scanned
-            let offset = status.cursor?.phase === phase ? (status.cursor.offset ?? 0) : 0;
-            let count = status.counts?.[phase] ?? 0;
-            for (;;) {
-                const page = await bridgeListEntries({ namespace, limit: SCAN_PAGE, offset, dbPath });
-                if (!page) {
-                    // The cursor stays exactly where it was: everything indexed before
-                    // this page is still correct, only incomplete, so a retry resumes.
-                    status = {
-                        ...status,
-                        state: 'failed',
-                        resumable: true,
-                        error: `${namespace}: backend unavailable during rebuild`,
-                    };
-                    await writeIndexStatus(ns, status, dbPath);
-                    return { success: false, status, error: status.error };
-                }
-                for (const e of page.entries) {
-                    const md = (e.metadata ?? {});
-                    count++;
-                    if (phase === 'edges' && md.kg === 'edge') {
-                        const src = String(md.src ?? '');
-                        const dst = String(md.dst ?? '');
-                        if (src) {
-                            await addToAdj(ns, src, e.key, dbPath);
-                            noteEntity(src);
-                        }
-                        if (dst && dst !== src) {
-                            await addToAdj(ns, dst, e.key, dbPath);
-                            noteEntity(dst);
-                        }
-                    }
-                    if (phase === 'nodes')
-                        noteEntity(e.key);
-                    for (const originRef of originsOf(e)) {
-                        await addToOriginIndex(ns, originRef, { ns: namespace, key: e.key }, dbPath);
-                        noteOrigin(originRef);
-                    }
-                }
-                offset += page.entries.length;
-                status = {
-                    ...status,
-                    cursor: { phase, offset },
-                    counts: { ...status.counts, [phase]: count },
-                };
-                await writeIndexStatus(ns, status, dbPath);
-                if (page.entries.length < SCAN_PAGE)
-                    break; // last page of this namespace
-            }
-        }
-        status = { ...status, state: 'validating' };
-        await writeIndexStatus(ns, status, dbPath);
-        const mismatches = [];
-        for (const id of seenEntities) {
-            const indexed = await kgIndexedEdgesByEndpoint(ns, id, dbPath);
-            const reference = await kgReferenceEdges({ endpointId: id, scope: options?.scope, dbPath });
-            if (indexed === null || !reference.success || reference.truncated) {
-                mismatches.push(`entity ${id}: reference read incomplete`);
-                continue;
-            }
-            if (!sameEdgeKeySet(indexed, reference.edges))
-                mismatches.push(`entity ${id}: adjacency mismatch`);
-        }
-        for (const originRef of seenOrigins) {
-            const indexed = await kgIndexedByOrigin(ns, originRef, dbPath);
-            if (indexed === null) {
-                mismatches.push(`origin ${originRef}: index unreadable`);
-                continue;
-            }
-            const refA = await collectByOrigin(ns.nodes, originRef, dbPath);
-            const refB = await collectByOrigin(ns.edges, originRef, dbPath);
-            const refC = await collectByOrigin(ns.rules, originRef, dbPath);
-            if (!refA.covered || !refB.covered || !refC.covered) {
-                mismatches.push(`origin ${originRef}: reference scan incomplete`);
-                continue;
-            }
-            const expected = new Set([
-                ...refA.entries.map((e) => `${ns.nodes}|${e.key}`),
-                ...refB.entries.map((e) => `${ns.edges}|${e.key}`),
-                ...refC.entries.map((e) => `${ns.rules}|${e.key}`),
-            ]);
-            const indexedKeys = new Set(indexed.map((e) => `${e.ns}|${e.entry.key}`));
-            if (expected.size !== indexedKeys.size || [...expected].some((k) => !indexedKeys.has(k))) {
-                mismatches.push(`origin ${originRef}: support-index mismatch`);
-            }
-        }
-        const full = seenEntities.length < VALIDATE_SAMPLE && seenOrigins.length < VALIDATE_SAMPLE;
-        const validation = {
-            sampledEntities: seenEntities.length,
-            sampledOrigins: seenOrigins.length,
-            full,
-        };
-        if (mismatches.length) {
-            const summary = mismatches.slice(0, 5).join('; ');
-            status = {
-                ...status,
-                state: 'failed',
-                error: `validation failed: ${summary}${mismatches.length > 5 ? ` (+${mismatches.length - 5} more)` : ''}`,
-            };
-            await writeIndexStatus(ns, status, dbPath);
-            return { success: false, status, validation, error: status.error };
-        }
-        status = { ...status, state: 'ready', error: undefined };
-        await writeIndexStatus(ns, status, dbPath);
-        return { success: true, status, validation };
-    }
-    catch (err) {
-        status = {
-            ...status,
-            state: 'failed',
-            error: err instanceof Error ? err.message : String(err),
-        };
-        try {
-            await writeIndexStatus(ns, status, dbPath);
-        }
-        catch {
-            /* best-effort — see markIndexFailed */
-        }
-        return { success: false, status, error: status.error };
-    }
-}
-/** Verify that every edge's endpoints exist.
- *
- *  `kgIngest` now creates missing endpoints before writing an edge and
- *  `kgRollback` removes edges whose endpoints it deleted, so a healthy graph
- *  reports nothing. This exists for graphs written before either rule, and as
- *  the check that says so rather than assuming it. */
-export async function kgIntegrityCheck(options) {
-    const ns = kgNamespaces(options?.scope);
-    const limit = options?.limit ?? 100;
-    const dangling = [];
-    let edges = 0;
-    try {
-        /** Endpoint id → exists. One keyed lookup per DISTINCT endpoint. */
-        const seen = new Map();
-        const exists = async (id) => {
-            const hit = seen.get(id);
-            if (hit !== undefined)
-                return hit;
-            const res = await bridgeGetEntry({ key: id, namespace: ns.nodes, dbPath: options?.dbPath });
-            const found = Boolean(res?.found && res.entry);
-            seen.set(id, found);
-            return found;
-        };
-        // Collect first, then probe: the probes are reads, but interleaving many
-        // per page would hold the page open far longer than the scan needs.
-        const rows = [];
-        const covered = await scanNamespace(ns.edges, options?.dbPath, (page) => {
-            for (const e of page) {
-                const md = (e.metadata ?? {});
-                if (md.kg !== 'edge')
-                    continue;
-                edges++;
-                rows.push({ key: e.key, src: String(md.src ?? ''), dst: String(md.dst ?? '') });
-            }
-        });
-        for (const row of rows) {
-            if (dangling.length >= limit)
-                break;
-            const missing = [];
-            if (!row.src || !(await exists(row.src)))
-                missing.push(row.src || '<no src>');
-            if (!row.dst || !(await exists(row.dst)))
-                missing.push(row.dst || '<no dst>');
-            if (missing.length)
-                dangling.push({ key: row.key, missing });
-        }
-        return {
-            success: true,
-            edges,
-            dangling,
-            ...(covered && dangling.length < limit ? {} : { truncated: true }),
-        };
-    }
-    catch (err) {
-        return {
-            success: false,
-            edges,
-            dangling,
-            error: err instanceof Error ? err.message : String(err),
-        };
-    }
-}
+import { normalizeName } from './memory-kg-model.js';
+export { kgIndexStatus } from './memory-kg-index.js';
+export { kgIngest } from './memory-kg-ingest.js';
+export { KG_ADJ_NS, KG_EDGES_NS, KG_ID_VERSION, KG_INDEX_STATUS_NS, KG_NAMES_NS, KG_NODES_NS, KG_ORIGIN_IDX_NS, kgNamespaces, kgQualifyOrigin, nodeKey, normalizeName, RULES_NS, } from './memory-kg-model.js';
+export { kgConsolidateCandidates, kgPromote, kgStats } from './memory-kg-promote.js';
+export { kgIntegrityCheck, kgRebuildIndex } from './memory-kg-rebuild.js';
+export { kgRollback } from './memory-kg-rollback.js';
+export { kgIngestRules, kgListRules } from './memory-kg-rules.js';
+export { kgReferenceEdges } from './memory-kg-scan.js';
+export { kgGlossary, kgSearch } from './memory-kg-search.js';
 // ── Heuristic extraction (LLM-less fallback) ────────────────────────
 /** Regex extraction for when no LLM is in the loop (memory-palace lineage):
  *  proper-noun phrases and `code identifiers` become entities, sentence