@monoes/monomindcli 2.16.12 → 2.16.14

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

@@ -0,0 +1,256 @@
+/**
+ * Memory Knowledge Graph — the K7 derived index: status, adjacency entries,
+ * origin-support entries, the dual-write hooks that keep them in sync, and
+ * the indexed reads used once a scope is `ready`. Split out of
+ * memory-kg.ts, which re-exports the public symbols.
+ */
+import { bridgeGetEntry, bridgeStoreEntry } from './memory-bridge.js';
+import { kgNamespaces } from './memory-kg-model.js';
+import { originsOf } from './memory-kg-scan.js';
+export 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;
+export 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 };
+}
+export 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);
+}
+export 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 : [] };
+}
+export 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 : [] };
+}
+export 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. */
+export 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. */
+export 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. */
+export 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. */
+export 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. */
+export 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. */
+export 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;
+}
+//# sourceMappingURL=memory-kg-index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory-kg-index.js","sourceRoot":"","sources":["../../../src/memory/memory-kg-index.ts"],"names":[],"mappings":"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"}

package/dist/src/memory/memory-kg-ingest.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Memory Knowledge Graph — ingest: kgIngest (entity resolution, claim
+ * merge under compare-and-swap, placeholder endpoints) and its per-call
+ * report. Split out of memory-kg.ts, which re-exports kgIngest.
+ */
+import type { KgExtractionMethod } from './memory-kg-claims.js';
+import type { KgEdgeInput, KgIngestResult, KgNodeInput, KgScope } from './memory-kg-model.js';
+/** 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 declare function kgIngest(options: {
+    nodes: KgNodeInput[];
+    edges?: KgEdgeInput[];
+    /** Provenance: run id, session id, or doc hash this extraction came from.
+     *  Stored qualified by `scope` — see `kgQualifyOrigin`. */
+    originRef: string;
+    /** Owner of these facts. Omit for project-shared knowledge. */
+    scope?: KgScope;
+    /** How this payload was produced. Defaults to `asserted`; `heuristicExtract`
+     *  callers must pass `heuristic` so a co-occurrence guess is not stored as a
+     *  stated fact. Recorded per origin, so the same element can hold a heuristic
+     *  claim from one run and an asserted one from another. */
+    method?: KgExtractionMethod;
+    dbPath?: string;
+}): Promise<KgIngestResult>;
+//# sourceMappingURL=memory-kg-ingest.d.ts.map

package/dist/src/memory/memory-kg-ingest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-kg-ingest.d.ts","sourceRoot":"","sources":["../../../src/memory/memory-kg-ingest.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAiB,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAG/E,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EAEd,WAAW,EACX,OAAO,EACR,MAAM,sBAAsB,CAAC;AAoB9B;;;;;;;;;;;;;;;;;;;;+CAoB+C;AAC/C,wBAAsB,QAAQ,CAAC,OAAO,EAAE;IACtC,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,WAAW,EAAE,CAAC;IACtB;+DAC2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;+DAG2D;IAC3D,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,cAAc,CAAC,CAsN1B"}