@monoes/monomindcli 2.10.9 → 2.10.13

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

@@ -10,21 +10,116 @@
  * feedback/frequency weighting for free — KG node ranking improves with use
  * automatically.
  *
- * Identity is deterministic and NAME-ONLY (cognee's Entity.identity_fields):
- * the entry KEY is `n:<normalized-name>`, so the same entity extracted from
- * any session merges idempotently via upsert regardless of assigned type.
- * Every write carries `origin_refs` so a bad ingest can be rolled back per
- * run/session.
+ * OWNERSHIP is carried by `KgScope`, not by the store path. Every org under
+ * one project root shares ONE org-memory store, so those namespaces would
+ * otherwise be a single pool that any org can read, merge into, and roll back.
+ * A scope suffixes every one of them (`kg:nodes:org:<org>`, …) and stamps the
+ * asserting org onto every origin ref, so an org's reads, writes, glossary and
+ * rollback all resolve through `kgNamespaces()` and can only reach what that
+ * org asserted. An absent scope means PROJECT-SHARED knowledge — a scope in
+ * its own right, not "all scopes". Crossing from an org into the shared graph
+ * is `kgPromote`, an explicit operation, never a side effect of learning.
  *
- * // monolean: graph traversal is in-process over a full kg:edges list —
- * // fine to ~10k edges; upgrade path is a real SQLite edges table with
- * // indexed src/dst columns if orgs outgrow that.
+ * IDENTITY is the (type, name) tuple, hashed length-prefixed so no component
+ * can bleed into its neighbour and no distinction is truncated away — the same
+ * injective-serialization discipline monograph's `symbolId`/`fileId` use, and
+ * for the same reason. Name-only identity made `Person:Alex` and `Service:Alex`
+ * one entity, and made two names that first differ at character 250 one entity
+ * as well. Keys stay per-namespace, so scope still lives in the NAMESPACE: two
+ * orgs asserting different facts about the same name produce the same id, and
+ * only separate namespaces keep them from overwriting each other.
+ *
+ * Name-only merging did buy something real — it stopped the same entity forking
+ * when the LLM said "Module" and the heuristic said "entity" — so that benefit
+ * is kept by a NAME INDEX (`kg:names`) rather than by a lossy key. Resolution
+ * goes through the index, never through a computed key: a generic assertion
+ * adopts the single same-name entity if there is exactly one, a typed assertion
+ * adopts a lone untyped one and promotes its type, and anything genuinely
+ * ambiguous becomes a separate entity with the alternatives REPORTED as
+ * candidates rather than silently merged.
+ *
+ * KNOWLEDGE IS CLAIMS, not a summary string. Each entity/edge/rule carries a
+ * `claims` ledger of per-origin description contributions; the stored
+ * `description` is DERIVED from it — the most recent contribution wins, because
+ * description length measures verbosity and not truth. That is what makes a
+ * correction expressible ("Now PostgreSQL" supersedes a longer MySQL blurb) and
+ * what makes rollback reversible: withdrawing an origin drops its contribution
+ * and RE-DERIVES the summary from the survivors, so the previous correct
+ * description comes back instead of a bad one being frozen in place.
+ * `origin_refs` remains, derived from the ledger, so provenance readers are
+ * unaffected. Support is never silently truncated: past `MAX_CLAIMS` the entry
+ * records `origins_dropped` and `provenance_complete:false`.
+ *
+ * EVIDENCE travels with the claim. Each contribution records how it was
+ * obtained — `asserted` when someone stated it, `heuristic` when
+ * `heuristicExtract` inferred it from two names sharing a sentence — and the
+ * element's standing is projected from its live claims, with one asserted claim
+ * outranking any number of guesses. A claim written before this recording
+ * leaves the projection UNKNOWN rather than voting: reading an unrecorded
+ * method as `asserted` would relabel the entire pre-existing graph as stated
+ * fact. Retrieval uses exactly this and the `conflict` flag to rank, and
+ * nothing else — source credibility and claim freshness need an evaluation set
+ * to tune against, and guessing at them is the overclaim this replaced.
+ *
+ * MIGRATION: nothing is re-keyed, deleted, or orphaned. An entry written under
+ * the old `n:<normalized-name>` scheme is still found — resolution falls back to
+ * probing the legacy key — and is then adopted IN PLACE under its existing key
+ * and registered in the name index. Legacy rows therefore keep working for
+ * search, stats, glossary and rollback, and keep their edges (whose keys embed
+ * the endpoint keys) intact. Only a genuinely NEW identity distinction — a
+ * second type for a name, or a name that differs only past the old truncation
+ * point — mints a new hashed id.
+ *
+ * // monolean: graph traversal is in-process over a paged kg:edges scan. The
+ * // bridge exposes no indexed adjacency (src/dst) or origin lookup, so every
+ * // neighbourhood/provenance question is a namespace scan; the upgrade path is
+ * // a real SQLite edges table with indexed src/dst/origin columns, which turns
+ * // these O(namespace) scans into O(matches). `kgStats` uses a real
+ * // `bridgeCountEntries` (SELECT COUNT(*) WHERE namespace = ?) instead of a
+ * // scan — that needs no history, a count is correct regardless of when a row
+ * // was written. Adjacency/origin, in contrast, is NOT filled in here: an
+ * // index built only from now on would silently miss every edge/claim written
+ * // before it existed (there is no legacy-key probe for an arbitrary historical
+ * // edge, unlike resolveEntity's single fallback key), so kgSearch/kgRollback
+ * // would go from an honest, complete scan to an INcomplete indexed answer —
+ * // a regression, not the fix. Closing this needs a real backfill/migration
+ * // decision (how to populate the index for existing namespaces, and how to
+ * // know when one is complete enough to trust), not more code here.
  *
  * @module v1/cli/memory/memory-kg
  */
 export declare const KG_NODES_NS = "kg:nodes";
 export declare const KG_EDGES_NS = "kg:edges";
 export declare 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 declare const KG_NAMES_NS = "kg:names";
+/** Derived adjacency index namespace (K7). See `KgNamespaces.adj`. */
+export declare const KG_ADJ_NS = "kg:adj";
+/** Derived origin-support index namespace (K7). See `KgNamespaces.originIdx`. */
+export declare const KG_ORIGIN_IDX_NS = "kg:origin-idx";
+/** Derived-index status namespace (K7). See `KgNamespaces.indexStatus`. */
+export declare const KG_INDEX_STATUS_NS = "kg:index-status";
+/**
+ * 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 declare const KG_ID_VERSION = 2;
+/** 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 declare function nodeKey(type: string, name: string): string;
 export interface KgNodeInput {
     name: string;
     /** Basic type, cognee-style ("Person", "Tool", "Service") — not over-specific. */
@@ -48,27 +143,137 @@ export interface KgIngestResult {
     nodesMerged: number;
     edgesAdded: number;
     edgesMerged: number;
+    /** Writes the bridge refused, one message each (capped at MAX_FAILURES).
+     *  Non-empty ⇒ `success` is false and the counters describe only what
+     *  actually persisted. */
+    failures?: string[];
     error?: string;
+    /** Items the payload asked for that this call refused. Present only when
+     *  non-zero, so a caller who sent a clean payload sees a clean result. */
+    nodesRejected?: number;
+    edgesRejected?: number;
+    /** Items dropped because the payload exceeded the per-call cap. The cap has
+     *  not changed; what has changed is that it is now REPORTED instead of being
+     *  a silent `.slice()`. */
+    nodesTruncated?: number;
+    edgesTruncated?: number;
+    /** Why items were rejected, one message each (capped at MAX_FAILURES). */
+    rejections?: string[];
+    /** Endpoint entities created because an edge named them and they did not
+     *  exist. Edge-only ingestion used to succeed with zero nodes and one edge,
+     *  leaving a fact unreachable through both of its own endpoints. */
+    placeholders?: number;
+    /** Same-name entities this call did NOT merge with, one message each. A
+     *  same-name match is a CANDIDATE, not a merge. */
+    ambiguities?: string[];
+    /** Elements whose support ledger hit `MAX_CLAIMS` on this call, so their
+     *  oldest provenance was dropped. Never silent. */
+    provenanceTruncated?: number;
 }
 /** cognee DataPoint normalization: lowercase, spaces→_, strip apostrophes. */
 export declare function normalizeName(name: string): string;
-/** Identity is NAME-ONLY (cognee's Entity.identity_fields = ["name"]) — type
- *  lives in metadata. Including type in the key forked the same entity when
- *  the LLM said "Module" and the heuristic said "entity". */
-export declare function nodeKey(_type: string, name: string): string;
-/** Idempotently merge extracted nodes/edges into the KG. Same-name entities
- *  collapse onto one node (deterministic key + upsert); origin_refs accumulate
- *  so rollback can undo a single run's contribution. */
+/** Who owns a set of graph facts. `org` absent = project-shared knowledge. */
+export interface KgScope {
+    org?: string;
+}
+export interface KgNamespaces {
+    nodes: string;
+    edges: string;
+    rules: string;
+    /** Name → entity index backing `resolveEntity`. Holds no claims. */
+    names: string;
+    /** Derived adjacency index: entity id -> edge keys touching it (K7). Holds
+     *  no claims either — every entry is rebuildable from `edges`. */
+    adj: string;
+    /** Derived origin-support index: origin ref -> {ns,key} refs it supports,
+     *  across nodes/edges/rules (K7). Rebuildable from all three. */
+    originIdx: string;
+    /** This scope's derived-index build/readiness state (K7). One row. */
+    indexStatus: string;
+}
+/** 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 declare function kgNamespaces(scope?: KgScope): KgNamespaces;
+/** 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 declare function kgQualifyOrigin(originRef: string, scope?: KgScope): string;
+/** How a claim came to exist.
+ *
+ *  `asserted` — someone stated it: an LLM distillation, an explicit
+ *  `memory_kg_ingest`, an org's `org_learn`.
+ *  `heuristic` — `heuristicExtract` inferred it from two names appearing in one
+ *  sentence. Nobody asserted it, and the module header has always called it
+ *  lower-trust; until now nothing downstream could tell the two apart. */
+export type KgExtractionMethod = 'asserted' | 'heuristic';
+/** One origin's assertion about an element. An origin re-asserting replaces its
+ *  own contribution — a run stands behind its latest word, not its first. */
+export interface KgClaim {
+    origin: string;
+    description: string;
+    /** Assertion time, and the ordering that decides which claim is current. */
+    at: number;
+    /** Absent on rows written before extraction method was recorded. Absent means
+     *  UNKNOWN, never `asserted` — defaulting an unrecorded method to the higher
+     *  trust would relabel every old co-occurrence guess as a stated fact. */
+    method?: KgExtractionMethod;
+}
+/** An entity the name index knows about. */
+export interface KgNameCandidate {
+    id: string;
+    /** Identity-bearing type bucket; '' for an entity asserted without a type. */
+    type: string;
+}
+/** 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. */
+    /** 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>;
 export interface RuleVerdict {
     rule: string;
-    verdict: 'accepted' | 'already_known' | 'invalid';
+    /** `failed` — the candidate was fine, but a write the caller was told about
+     *  did not land. It is neither `invalid` (which blames the caller's input)
+     *  nor `accepted`/`already_known` (which claim the graph now holds it). Both
+     *  of those used to be reported unconditionally, so a caller reading verdicts
+     *  saw every rule land while the aggregate `accepted` count said zero. */
+    verdict: 'accepted' | 'already_known' | 'invalid' | 'failed';
     similarTo?: string;
 }
 /** Stage-2 of cognee's curator/writer distillation: the CALLER (an LLM agent)
@@ -76,13 +281,23 @@ export interface RuleVerdict {
  *  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. */
+ *  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 declare function kgIngestRules(options: {
     rules: {
         rule: string;
         context?: string;
     }[];
     originRef: string;
+    /** Owner of these rules. Omit for project-shared knowledge. */
+    scope?: KgScope;
     dbPath?: string;
     /** Similarity above which a candidate is already_known (default 0.78 —
      *  MiniLM paraphrases of the same rule commonly land 0.78-0.9; cognee's
@@ -92,12 +307,17 @@ export declare function kgIngestRules(options: {
     success: boolean;
     verdicts: RuleVerdict[];
     accepted: number;
+    failures?: string[];
     error?: string;
+    /** Candidates dropped by the per-call cap, reported rather than sliced away
+     *  in silence. */
+    rulesTruncated?: number;
 }>;
 /** List stored rules (for injection or review). */
 export declare function kgListRules(options?: {
     dbPath?: string;
     limit?: number;
+    scope?: KgScope;
 }): Promise<{
     rule: string;
     key: string;
@@ -112,6 +332,18 @@ export interface KgSearchResult {
         target: string;
         fact: string;
         score: number;
+        /** How this edge came to exist. Absent means the edge predates method
+         *  recording — not recorded, which is not the same as `asserted`. */
+        method?: KgExtractionMethod;
+        /** Live origins disagree about what this edge says. Present only when true. */
+        conflict?: boolean;
+        /** The edge's bridge entry id — feed this straight to `memory_feedback`
+         *  (`bridgeApplyFeedback`/`bridgeRecordUsage`) to rate THIS relationship
+         *  directly, rather than only the seed entity that surfaced it (K5). */
+        id: string;
+        /** The edge's stable graph key (`e:<hash>`, see `edgeKey`), for direct
+         *  `bridgeGetEntry` lookup or diagnostics — distinct from `id` above. */
+        key: string;
     }[];
     seeds: {
         name: string;
@@ -120,33 +352,117 @@ export interface KgSearchResult {
         score: number;
         id: string;
     }[];
+    /** True when the edge scan did NOT cover the whole namespace — the scan hit
+     *  `SEARCH_EDGE_SCAN_MAX`, or the backend became unreadable partway. A
+     *  relationship that exists may be missing from `triplets`; absence here is
+     *  not evidence of absence in the graph. */
+    truncated?: boolean;
+    /** Edge rows actually read, so a caller can see how close it ran to the cap. */
+    scannedEdges?: number;
+    /** What the seed retrieval ACTUALLY ran, straight from the bridge — never what
+     *  was hoped for. `keyword-fallback` means the vector path was tried and did
+     *  not serve these results. Absent only when the bridge reported nothing. */
+    method?: 'semantic' | 'keyword' | 'keyword-fallback';
+    /** Why the vector path did not serve the seeds (absent when it did). */
+    fallbackReason?: string;
     error?: string;
 }
-/** Vector-seed → neighborhood → triplet ranking (cognee's brute-force triplet
- *  search, scaled down). Seed scores already carry the Phase 1 feedback blend. */
+/** 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 declare function kgSearch(options: {
     query: string;
     dbPath?: string;
     limit?: number;
     nodeSet?: string;
+    /** Whose graph to search. Omit for project-shared knowledge; a scoped search
+     *  never reaches another org's facts, and never the shared graph either. */
+    scope?: KgScope;
 }): Promise<KgSearchResult>;
 export declare function kgGlossary(options?: {
     dbPath?: string;
     limit?: number;
+    /** Whose entity names to offer. The coordinator glossary MUST be scoped:
+     *  suggesting another org's entity names is how one org's claims get merged
+     *  into another's graph under a shared name. */
+    scope?: KgScope;
 }): Promise<string[]>;
-/** Delete every node/edge/rule whose ONLY origin is `originRef`. Elements with
- *  other origins survive (shared knowledge isn't destroyed by one bad run);
- *  their origin lists retain the ref — acceptable residue.
- *  // monolean: no origin-list rewrite — needs an update-by-id bridge API */
+/** 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 declare function kgRollback(options: {
     originRef: string;
+    /** Whose knowledge to withdraw from. A rollback can only reach the named
+     *  scope's namespaces — an org's rollback is an ownership boundary, not just
+     *  a label on the output. */
+    scope?: KgScope;
     dbPath?: string;
 }): Promise<{
     success: boolean;
     deleted: number;
     retained: number;
+    failures?: string[];
     error?: string;
+    /** Edges deleted because this rollback removed an endpoint they name. A
+     *  relation between two things is not a fact once one of them is gone, and
+     *  retrieval is node-seeded, so leaving them behind left unreachable rows
+     *  claiming a graph that no longer exists. */
+    danglingEdgesRemoved?: number;
 }>;
+export interface KgPromoteResult {
+    success: boolean;
+    nodes: number;
+    edges: number;
+    rules: number;
+    /** Origin the shared copy carries, so the promotion can be withdrawn on its
+     *  own and the shared graph records who shared the claim. */
+    promotedAs: string;
+    failures?: string[];
+    error?: string;
+}
+/** 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 declare function kgPromote(options: {
+    /** The org-side ref to promote, unqualified (e.g. `run:m4x2`). */
+    originRef: string;
+    /** Owner the claims are promoted FROM. Promoting from the shared scope is a
+     *  no-op and is refused rather than silently duplicating. */
+    from: KgScope;
+    dbPath?: string;
+}): Promise<KgPromoteResult>;
 export interface ConsolidationCandidate {
     name: string;
     type: string;
@@ -157,26 +473,177 @@ export interface ConsolidationCandidate {
 }
 /** 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
- *  (longer descriptions win on merge). No LLM here (fully local constraint). */
+ *  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 declare function kgConsolidateCandidates(options?: {
     dbPath?: string;
     /** Minimum edges for a node to qualify (default 3). */
     minEdges?: number;
     limit?: number;
+    scope?: KgScope;
 }): Promise<ConsolidationCandidate[]>;
+/** 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 declare function kgStats(options?: {
     dbPath?: string;
+    /** Whose graph to measure. Counting every org's facts under one org's name
+     *  is what made `org memory <name> stats` a fiction. */
+    scope?: KgScope;
 }): Promise<{
     nodes: number;
     edges: number;
     rules: number;
 }>;
+export interface KgReferenceEdge {
+    key: string;
+    src: string;
+    dst: string;
+    relation: string;
+    originRefs: string[];
+}
+/** 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 declare function kgReferenceEdges(options: {
+    endpointId?: string;
+    originRef?: string;
+    scope?: KgScope;
+    dbPath?: string;
+}): Promise<{
+    success: boolean;
+    edges: KgReferenceEdge[];
+    truncated?: boolean;
+    error?: string;
+}>;
+export type KgIndexState = 'absent' | 'building' | 'validating' | 'ready' | 'failed';
+export interface KgIndexStatus {
+    state: KgIndexState;
+    schemaVersion: number;
+    /** Resume point for an interrupted `kgRebuildIndex`. */
+    cursor?: {
+        phase: 'nodes' | 'edges' | 'rules';
+        offset: number;
+    };
+    counts?: {
+        nodes: number;
+        edges: number;
+        rules: number;
+    };
+    startedAt?: number;
+    updatedAt?: number;
+    error?: string;
+    /** Only meaningful when `state === 'failed'`. True for a build-phase
+     *  failure (the backend went unavailable mid-scan, or a dual-write hook
+     *  hit an error after `ready`): everything already written is still
+     *  correct, just incomplete, so the next call RESUMES from `cursor`. False
+     *  for a validation-phase failure (the built index disagreed with an
+     *  independent reference read): something already written is wrong, not
+     *  merely incomplete, so the next call restarts a fresh scan — resuming
+     *  would re-derive the same mistake instead of correcting it. */
+    resumable?: boolean;
+}
+/** 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 declare function kgIndexStatus(options?: {
+    scope?: KgScope;
+    dbPath?: string;
+}): Promise<KgIndexStatus>;
+export interface KgRebuildResult {
+    success: boolean;
+    status: KgIndexStatus;
+    validation?: {
+        sampledEntities: number;
+        sampledOrigins: number;
+        full: boolean;
+    };
+    error?: string;
+}
+/** (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 declare function kgRebuildIndex(options?: {
+    scope?: KgScope;
+    dbPath?: string;
+}): Promise<KgRebuildResult>;
+export interface KgIntegrityResult {
+    success: boolean;
+    edges: number;
+    /** Edges naming an endpoint that does not exist. Retrieval is node-seeded,
+     *  so such an edge is a fact unreachable through either of the things it is
+     *  about — it can only be found by a check like this one. */
+    dangling: {
+        key: string;
+        missing: string[];
+    }[];
+    /** True when the edge scan did not cover the namespace: absence of a dangling
+     *  edge here is then not evidence that there is none. */
+    truncated?: boolean;
+    error?: string;
+}
+/** 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 declare function kgIntegrityCheck(options?: {
+    dbPath?: string;
+    scope?: KgScope;
+    /** Dangling edges to report before stopping (default 100). */
+    limit?: number;
+}): Promise<KgIntegrityResult>;
 /** Regex extraction for when no LLM is in the loop (memory-palace lineage):
  *  proper-noun phrases and `code identifiers` become entities, sentence
- *  co-occurrence becomes relates_to edges. Lower-trust by design — real
+ *  co-occurrence becomes `mentioned_with` edges. Lower-trust by design — real
  *  entity/relation quality comes from the LLM path (memory_kg_ingest called
- *  by the live agent, or the org coordinator's org_learn tool). */
+ *  by the live agent, or the org coordinator's org_learn tool).
+ *
+ *  Callers MUST ingest this with `method: 'heuristic'`. "Lower-trust by design"
+ *  was true and unenforced: nothing downstream could tell these edges from
+ *  facts an agent stated, so ranking treated them identically. */
 export declare function heuristicExtract(text: string, opts?: {
     sourceName?: string;
 }): {