@graphrefly/graphrefly 0.45.0 → 0.47.0

package/dist/utils/memory/index.d.cts

@@ -0,0 +1,660 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { ReactiveLogBundle } from '@graphrefly/pure-ts/extra';
+import { Graph } from '@graphrefly/pure-ts/graph';
+import { BaseAuditRecord } from '../../base/mutation/index.cjs';
+import { N as NodeOrValue } from '../../_internal-B23BagFd.cjs';
+
+/**
+ * DS-14.7 — Reactive Fact Store / Live Knowledge Graph (locked 2026-05-13).
+ *
+ * Static-topology agent-memory substrate that satisfies MEME L2 (cascade
+ * invalidation) and L3 (obsolescence reasoning) plus Hassabis's
+ * filter/consolidate/continual-learning frame, **without** materializing one
+ * reactive node per fact. ~12 fixed operator nodes never grow regardless of how
+ * many facts the store holds; facts live as columnar DATA inside an indexed
+ * `state<FactStore>` (optionally sharded), and cascade is implemented as
+ * bounded recursive message emission. Termination rests on a per-root
+ * semantic contract — a fact only drives the cascade when it transitions to
+ * obsolete (`validTo` set), and each obsolete root emits its cascade exactly
+ * once across all waves — plus an empty-array fixpoint short-circuit. The
+ * cascade is modeled as DATA arrays (NOT INVALIDATE messages), so spec §1.4's
+ * idempotent-within-a-wave INVALIDATE guarantee does NOT govern this loop;
+ * convergence is the per-root contract, not a spec §1.4 diamond-merge.
+ *
+ * Canonical design: `archive/docs/SESSION-DS-14.7-reactive-fact-store.md`
+ * (9Q walk complete; Q9-open items 1–9 all resolved).
+ *
+ * Locked decisions baked in here:
+ * - `cascadeMaxIterations` default **8**; overflow emits a per-batch summary
+ *   `{ droppedCount, sample, rootFactId }` to `cascadeOverflow` (Q9-open-4).
+ *   The overflow `sample` is capped at `OVERFLOW_SAMPLE_SIZE` (8),
+ *   independent of `cascadeMaxIterations`.
+ * - `shardBy` default hash-mod **4**; caller override; `dependentsIndex`
+ *   unsharded for v1 (Q9-open-1).
+ * - `MemoryFragment` adds `embedding? / parent_fragment_id? / provenance?`
+ *   (Q9-open-3).
+ * - `dependentsIndex` updates synchronous + atomic with `factStore` commit
+ *   (Q9-open-2).
+ * - Scoring contract `(fragment, storeReadHandle) => number` — read-only
+ *   handle, no mutation exposure (Q9-open-5).
+ * - Consolidator emits to a dedicated `consolidated` topic that the pattern
+ *   default-wires back to `ingest`; caller can intercept (Q9-open-6).
+ * - Query surface = structured `MemoryQuery` via the `query` topic (default);
+ *   function-shaped is caller-side `derived` over `factStore` (Q9-open-7).
+ * - Bi-temporal is pattern-layer only — no DS-14 envelope shape change
+ *   (Q9-open-9); `simpleFactStore()` deferred to v1.1 (Q9-open-8 — NOT built).
+ *
+ * **Cascade cycle visibility.** `cascadeProcessor` stays synchronous (preserves
+ * spec §1.4 batch-dedupe — LLM-driven dependency extraction lives UPSTREAM of
+ * the cascade topic, never inside the recursion). Every cascade message carries
+ * a `causalReason` field and the cycle nodes are tagged `meta.cycle:"cascade"`
+ * so `describe()` / `explain()` surface the otherwise-invisible
+ * `dependentsIndex` fn-body lookup.
+ *
+ * @module
+ */
+
+/** Stable identity for a stored fact. */
+type FactId = string;
+/** Shard partition key (string | number — any hashable scalar). */
+type ShardKey = string | number;
+/**
+ * A single stored memory fact. Pattern convention only — NOT a spec primitive
+ * and NOT a DS-14 envelope field (bi-temporal stays pattern-layer per
+ * Q9-open-9). Each field is a reactive lever (see design PART 2.3):
+ * `validTo` set → cascade fires; `confidence < θ` → review; `sources` →
+ * `dependentsIndex` edges feeding cascade.
+ */
+interface MemoryFragment<T> {
+    readonly id: FactId;
+    readonly payload: T;
+    /** Transaction time (when learned). `bigint` ns (e.g. `BigInt(monotonicNs())`). */
+    readonly t_ns: bigint;
+    /** Valid-time start. `undefined` = unbounded past. */
+    readonly validFrom?: bigint;
+    /** Valid-time end. Setting this is the MEME L3 obsolescence lever. */
+    readonly validTo?: bigint;
+    /** Confidence 0..1. Dropping below the review threshold emits a review. */
+    readonly confidence: number;
+    readonly tags: readonly string[];
+    /** Dependency edges — fact IDs this fact is derived from / depends on. */
+    readonly sources: readonly FactId[];
+    /** Optional dense embedding (recipes use it for retrieval). */
+    readonly embedding?: readonly number[];
+    /** Version-chain pointer — consolidator emits successor fragments. */
+    readonly parent_fragment_id?: FactId;
+    /** Free-form provenance string for audit. */
+    readonly provenance?: string;
+}
+/**
+ * Columnar in-memory store. Held as DATA inside a `state<FactStore<T>>` node
+ * (one per shard). `byId` is the authoritative map; the typed companions are
+ * kept for the recipe layer (`bitemporal-query`, `influence-analysis`) — v1
+ * stores fragments directly and lazily projects columns on demand.
+ */
+interface FactStore<T> {
+    readonly byId: ReadonlyMap<FactId, MemoryFragment<T>>;
+}
+/** Reverse dependency index: fact → IDs that depend on it. Unsharded (v1). */
+type DependentsIndex = ReadonlyMap<FactId, readonly FactId[]>;
+/** Read-only projection passed to scoring policies (no mutation surface). */
+interface StoreReadHandle<T> {
+    get(id: FactId): MemoryFragment<T> | undefined;
+    has(id: FactId): boolean;
+    readonly size: number;
+    values(): IterableIterator<MemoryFragment<T>>;
+}
+type ScoringPolicy<T> = (fragment: MemoryFragment<T>, store: StoreReadHandle<T>) => number;
+type DecayPolicy = (confidence: number, ageNs: bigint) => number;
+type AdmissionFilter<T> = (fragment: MemoryFragment<T>) => boolean;
+/** Outcome / RL signal — write-back lever for continual learning. */
+interface OutcomeSignal {
+    readonly factId: FactId;
+    readonly reward: number;
+}
+/** Structured query (Q9-open-7 default surface). Serializable + inspectable. */
+interface MemoryQuery {
+    /** Match any of these tags (OR). Omit for no tag filter. */
+    readonly tags?: readonly string[];
+    /** Bi-temporal "as of" — only facts valid at this instant. */
+    readonly asOf?: bigint;
+    /** Minimum confidence (inclusive). */
+    readonly minConfidence?: number;
+    /** Cap results (sorted by confidence desc, then t_ns desc). */
+    readonly limit?: number;
+}
+interface MemoryAnswer<T> {
+    readonly query: MemoryQuery;
+    readonly results: readonly MemoryFragment<T>[];
+}
+type CascadeReason = "cascade" | "obsolete" | "manual";
+/** A single cascade invalidation message flowing through the cascade cycle. */
+interface CascadeEvent {
+    readonly factId: FactId;
+    readonly rootFactId: FactId;
+    readonly reason: CascadeReason;
+    /**
+     * The triggering root fact's own `validTo`. Cascade-invalidated dependents
+     * inherit this (NOT a fresh wall-clock read), so the store is a
+     * deterministic rebuildable projection: replaying the same ingest stream
+     * yields byte-identical `validTo` on cascade-invalidated fragments. Each
+     * dependent inherits the `validTo` of the *nearest obsolete fact that
+     * drove its invalidation*: in a pure chain A→B→C where only A is
+     * explicitly obsoleted, B and C both inherit A's `validTo` (B has no own
+     * `validTo`, so when B becomes a cascade root the detector reads
+     * `B.validTo` === A's value). If an intermediate B is itself explicitly
+     * obsoleted with its *own* `validTo`, B's dependents inherit B's value,
+     * not A's — "stale from when its driving source was invalidated."
+     * Deterministic either way. Always defined: only obsolete facts
+     * (`validTo` set) drive the cascade as roots.
+     */
+    readonly rootValidTo: bigint;
+    /** Cascade recursion depth (1 = first wave). Bounded by `cascadeMaxIterations`. */
+    readonly iteration: number;
+    /**
+     * Human-readable causal chain — makes the `dependentsIndex` fn-body lookup
+     * visible in `explain()` output even though it is not a topology edge
+     * (design Q3 / COMPOSITION-GUIDE §24 mitigation).
+     */
+    readonly causalReason: string;
+}
+/** Per-batch overflow summary (Q9-open-4 — never per-message). */
+interface CascadeOverflow {
+    readonly droppedCount: number;
+    readonly sample: readonly FactId[];
+    readonly rootFactId: FactId;
+}
+interface ReviewRequest {
+    readonly factId: FactId;
+    readonly confidence: number;
+    readonly threshold: number;
+}
+interface FactStoreAuditRecord extends BaseAuditRecord {
+    readonly action: "ingest" | "invalidate" | "outcome" | "consolidate" | "overflow";
+    readonly id?: FactId;
+    readonly reason?: CascadeReason;
+}
+interface ReactiveFactStoreConfig<T> {
+    readonly extractDependencies: (f: MemoryFragment<T>) => readonly FactId[];
+    /** Shard partition fn. Default: FNV-1a hash of `id` mod `shardCount`. */
+    readonly shardBy?: (f: MemoryFragment<T>) => ShardKey;
+    /** Shard count for the default hash-mod sharder. Default 4 (§3.2). */
+    readonly shardCount?: number;
+    readonly scoring?: Node<ScoringPolicy<T>>;
+    readonly decay?: Node<DecayPolicy>;
+    readonly admissionFilter?: Node<AdmissionFilter<T>>;
+    readonly ingest: Node<MemoryFragment<T>>;
+    readonly outcome?: Node<OutcomeSignal>;
+    readonly query?: Node<MemoryQuery>;
+    /**
+     * Consolidator trigger — a reactive timer/cron Node (e.g. `fromCron(...)`).
+     * When supplied, the `consolidated` node maps each tick to summarized
+     * fragments emitted on the `consolidated` topic and default-wired back to
+     * the internal ingest path.
+     */
+    readonly consolidateTrigger?: Node<unknown>;
+    /**
+     * Consolidation summarizer. Reads a store snapshot, returns successor
+     * fragments (typically with `parent_fragment_id` set). Default: no-op
+     * (emits nothing) so the cron tick is observable without forcing a policy.
+     */
+    readonly consolidate?: (store: StoreReadHandle<T>) => readonly MemoryFragment<T>[];
+    /** Cascade recursion cap (§3.1). Default 8. */
+    readonly cascadeMaxIterations?: number;
+    /** Confidence below which a {@link ReviewRequest} is emitted. Default 0.3. */
+    readonly reviewThreshold?: number;
+    /**
+     * Record every committed fragment (post-admission-filter, with full
+     * payload) into a replayable {@link ReactiveFactStoreGraph.ingestLog}.
+     * Default `false` (the log retains every fragment in memory — opt in only
+     * when you intend to persist + replay).
+     *
+     * Enables the canonical **rebuildable-projection** recipe: the store is a
+     * deterministic projection of its ingest stream (cascade `validTo` is
+     * derived from the triggering root, not wall-clock; consolidator successors
+     * are re-derived from replayed state, not logged — the projection is still
+     * deterministic), so persisting the ingest log and replaying it on restart
+     * reconstructs a byte-identical store. Pair with the BigInt-safe codec
+     * ({@link MemoryFragment} carries `bigint` time fields). The tier MUST be
+     * `mode:"append"` (the default) — `attachStorage` ships per-wave deltas, so
+     * an `"overwrite"` tier would truncate the log (and `attachStorage` now
+     * throws on one).
+     *
+     * **First run — persist:**
+     * ```ts
+     * import { reactiveFactStore } from "@graphrefly/graphrefly";
+     * import { appendLogStorage, bigintJsonCodecFor } from "@graphrefly/pure-ts/extra";
+     *
+     * const tier = appendLogStorage(backend, {
+     *   name: "facts-ingest",
+     *   codec: bigintJsonCodecFor<readonly MemoryFragment<Doc>[]>(),
+     * });
+     * const mem = reactiveFactStore<Doc>({ ingest, extractDependencies, recordIngest: true });
+     * mem.ingestLog!.attachStorage([tier]); // forwards every committed fragment
+     * ```
+     *
+     * **Restart — replay (rebuild the projection):** read the persisted entries
+     * and feed them through `config.ingest`. Replay is just the reactive input —
+     * there is no imperative restore primitive.
+     * ```ts
+     * const { entries } = await tier.loadEntries!();
+     * const mem = reactiveFactStore<Doc>({ ingest, extractDependencies });
+     * for (const f of entries) ingest.emit(f); // identical store rebuilt
+     * ```
+     *
+     * **Do NOT do both at once.** On restart, either replay through `ingest`
+     * (above) **or** rely on `attachStorage`'s auto-restore — never both:
+     * `attachStorage` restores the persisted entries into a fresh `ingestLog`,
+     * and a manual replay loop would then re-append + re-persist them (doubling
+     * the durable log every restart). If you want continued persistence on the
+     * rebuilt store, set `recordIngest:true` and call `attachStorage([tier])`
+     * **after** the replay loop completes (the log already holds the replayed
+     * fragments, so `attachStorage` ships no spurious deltas).
+     *
+     * **Memory:** the in-memory log is unbounded (every committed fragment is
+     * retained for the store's lifetime). For a long-lived high-volume store,
+     * `ingestLog.trimHead(n)` after a confirmed `tier.flush()` bounds it (the
+     * durable tier remains the full record).
+     */
+    readonly recordIngest?: boolean;
+}
+interface ReactiveFactStoreGraph<T> extends Graph {
+    /** Per-shard `state<FactStore<T>>` nodes (length = shard count). */
+    readonly shards: readonly Node<FactStore<T>>[];
+    /** Unified read view across all shards (derived). */
+    readonly factStore: Node<FactStore<T>>;
+    readonly dependentsIndex: Node<DependentsIndex>;
+    readonly answer: Node<MemoryAnswer<T> | null>;
+    readonly cascade: Node<readonly CascadeEvent[]>;
+    readonly cascadeOverflow: Node<CascadeOverflow | null>;
+    readonly review: Node<ReviewRequest | null>;
+    readonly consolidated: Node<readonly MemoryFragment<T>[]>;
+    readonly events: ReactiveLogBundle<FactStoreAuditRecord>;
+    /**
+     * Payload-carrying, replayable log of every committed fragment. Present iff
+     * {@link ReactiveFactStoreConfig.recordIngest} is `true`. Unlike
+     * {@link ReactiveFactStoreGraph.events} (action-only audit), each entry is
+     * the full {@link MemoryFragment} — `attachStorage` it for a durable,
+     * replayable projection source (see `recordIngest` docs for the recipe).
+     */
+    readonly ingestLog?: ReactiveLogBundle<MemoryFragment<T>>;
+    /** Reactive read: a single fact by id (SENTINEL until the fact exists). */
+    itemNode(id: FactId): Node<MemoryFragment<T> | undefined>;
+}
+/**
+ * Build a static-topology reactive fact store (DS-14.7 architecture C).
+ *
+ * Topology (~12 fixed nodes — never grows with fact count):
+ *  - `shards[0..N]` — `state<FactStore<T>>` columnar stores (default 4 shards).
+ *  - `factStore` — derived union read view across shards.
+ *  - `dependentsIndex` — `state<DependentsIndex>` reverse-dep map, unsharded,
+ *    updated synchronously + atomically with each commit (Q9-open-2).
+ *  - `extractOp` — derived: ingest → admission-filtered fragment + dep edges.
+ *  - `invalidationDetector` — derived: scans committed store for `validTo`-set
+ *    / low-confidence facts, resolves dependents via `dependentsIndex`, emits
+ *    cascade messages.
+ *  - `cascade` — topic node carrying `CascadeEvent[]`.
+ *  - `cascadeProcessor` — derived, **synchronous**, `meta.cycle:"cascade"`:
+ *    dedupes by factId, writes invalidations back to shards, recurses until
+ *    fixpoint OR `cascadeMaxIterations` → `cascadeOverflow`.
+ *  - `cascadeOverflow` — per-batch overflow summary node.
+ *  - `queryOp` / `answer` — structured `MemoryQuery` → results (SENTINEL-safe).
+ *  - `outcomeProcessor` — outcome signal → confidence write-back.
+ *  - `consolidated` — cron-tick → summarized fragments on the
+ *    `consolidated` topic,
+ *    default-wired back into the ingest path.
+ *  - `review` — low-confidence proactive-verification requests.
+ *
+ * The cascade cycle (`invalidationDetector → cascade → cascadeProcessor →
+ * shards → invalidationDetector`) is a real, bounded reactive cycle. Both
+ * `invalidationDetector` and `cascadeProcessor` are tagged
+ * `meta.cycle:"cascade"` and every cascade message carries `causalReason`, so
+ * `describe()` / `explain()` surface the otherwise-invisible
+ * `dependentsIndex` lookup (COMPOSITION-GUIDE §24).
+ *
+ * @category memory
+ */
+declare function reactiveFactStore<T>(config: ReactiveFactStoreConfig<T>): ReactiveFactStoreGraph<T>;
+
+/**
+ * Memory patterns (roadmap §4.3) — public-face Phase-4 primitives audited under
+ * `archive/docs/SESSION-public-face-blocks-review.md` (Wave A, locked 2026-04-25).
+ *
+ * Three primitives (the pure `decay` helper was promoted to `extra/utils/decay.ts`
+ * per Tier 2.2 and is no longer re-exported here; `lightCollection` was folded
+ * into `collection({ranked:false})` per Tier 2.3 and is no longer a separate
+ * factory):
+ * - {@link collection} / {@link CollectionGraph} — keyed memory store with
+ *   optional decay-aware ranking. Pass `{ ranked: false }` for the previous
+ *   `lightCollection` shape (Map + LRU + audit, no scoring).
+ * - {@link vectorIndex} / {@link VectorIndexGraph} — reactive vector store with
+ *   optional HNSW backend, retention, and reactive {@link VectorIndexGraph.searchNode}.
+ * - {@link knowledgeGraph} / {@link KnowledgeGraph} — entities + typed edges with
+ *   symmetric adjacency indexes and reactive {@link KnowledgeGraph.relatedNode}.
+ *
+ * **No imperative reads.** Per the API-style policy locked 2026-04-25, public-face
+ * primitives expose reactive reads only — `itemNode` / `hasNode` / `searchNode` /
+ * `relatedNode`. One-shot snapshots use `node.cache` after `awaitSettled`, or
+ * `firstValueFrom(node)`.
+ *
+ * **Audit logs.** Every imperative mutation (`upsert / remove / clear / link /
+ * unlink / rescore / reindex`) is wrapped via {@link mutate} and appends a
+ * typed record to a public `events` log on the bundle / graph.
+ *
+ * @module
+ */
+
+/**
+ * Cosine similarity over `(a, b)`. When lengths differ, the shorter is
+ * implicitly zero-padded to the longer length. Returns `0` if either vector
+ * has zero norm. Public utility — used by {@link VectorIndexGraph.searchNode}
+ * and exposed for downstream consumers (e.g. `patterns/ai/memory/`) that need
+ * the same scoring at the boundary.
+ *
+ * **Numeric guards.** Returns `0` for non-finite results (overflow producing
+ * `Infinity`/`NaN` from very-large vectors, or `NaN` propagating from any
+ * `NaN`/`Infinity` component). Without this guard, downstream sort
+ * comparators would order NaN-scored rows arbitrarily.
+ *
+ * **Depth.** This is a per-call computation; no internal caching. For very
+ * large indexes (>10k) consider precomputing norms or using HNSW.
+ *
+ * @category memory
+ */
+declare function cosineSimilarity(a: readonly number[], b: readonly number[]): number;
+
+type CollectionEntry<T> = {
+    readonly id: string;
+    readonly value: T;
+    readonly createdAtNs: number;
+    readonly lastAccessNs: number;
+    readonly baseScore: number;
+};
+type RankedCollectionEntry<T> = CollectionEntry<T> & {
+    readonly score: number;
+};
+type CollectionScoreFn<T> = (value: T) => number;
+type CollectionOptions<T> = {
+    maxSize?: number;
+    /**
+     * Whether to expose a live decay-aware `ranked` node + `rescore` mutator.
+     * Default `true`. Pass `false` to fold in the previous `lightCollection`
+     * shape — entries are still keyed/audited/LRU-evicted, but the timer-driven
+     * `ranked` + scoring machinery is skipped. `ranked` then resolves to a
+     * static empty array Node and `rescore()` is a no-op (so callers writing
+     * type-generic code don't need to special-case the unranked path).
+     */
+    ranked?: boolean;
+    /**
+     * Produces a base score at insert/update time. Static fn or a reactive
+     * `Node<(value: T) => number>` — when supplied as a Node, `ranked` re-derives
+     * whenever the score fn changes, but `baseScore` on each entry is only
+     * recomputed via {@link CollectionGraph.rescore}. Default `() => 1`.
+     *
+     * Ignored when `ranked: false` (entries record `baseScore: 0`).
+     */
+    score?: CollectionScoreFn<T> | Node<CollectionScoreFn<T>>;
+    /**
+     * Exponential decay rate per second. `0` disables decay (default). When
+     * positive, `ranked` becomes fully reactive on time via a `fromTimer` source
+     * (cadence auto-derived from `decayRate` unless overridden via
+     * `refreshIntervalMs`). Half-life: `ratePerSecond = Math.LN2 / halfLifeSeconds`.
+     *
+     * Ignored when `ranked: false`.
+     */
+    decayRate?: number;
+    /** Minimum score floor after decay. Default `0`. */
+    minScore?: number;
+    /**
+     * Override for the `ranked` refresh tick cadence (milliseconds). When
+     * unset and `decayRate > 0`, defaults to `1000 * Math.LN2 / (10 * decayRate)`
+     * — roughly one tick per 10% of the half-life (~10% staleness budget).
+     */
+    refreshIntervalMs?: number;
+};
+interface CollectionAuditRecord extends BaseAuditRecord {
+    readonly action: "upsert" | "remove" | "clear" | "rescore";
+    readonly id?: string;
+}
+type CollectionGraph<T> = Graph & {
+    readonly events: ReactiveLogBundle<CollectionAuditRecord>;
+    readonly items: Node<ReadonlyMap<string, CollectionEntry<T>>>;
+    /**
+     * Live decay-aware ranking, sorted by score descending. When the
+     * collection was constructed with `ranked: false`, this is a static
+     * empty-array Node (kept for type uniformity).
+     */
+    readonly ranked: Node<readonly RankedCollectionEntry<T>[]>;
+    readonly size: Node<number>;
+    upsert: (id: string, value: T, opts?: {
+        score?: number;
+    }) => void;
+    remove: (id: string) => void;
+    clear: () => void;
+    /**
+     * Recompute every entry's `baseScore` via the latest score fn. O(N). Useful
+     * when a reactive `score` Node has emitted a new fn and the caller wants
+     * existing entries re-scored without an explicit re-upsert.
+     *
+     * No-op (still records an audit entry) when constructed with
+     * `ranked: false`.
+     */
+    rescore: () => void;
+    itemNode: (id: NodeOrValue<string>) => Node<CollectionEntry<T> | undefined>;
+    /** Reactive `true` once the entry exists; tracks upsert / remove. */
+    hasNode: (id: NodeOrValue<string>) => Node<boolean>;
+};
+/**
+ * Scored memory store with live decay-aware ranking.
+ *
+ * Topology (mounted on the returned graph):
+ *  - `items` — `reactiveMap<id, CollectionEntry<T>>` (with `retention` configured
+ *    for score-based eviction when `maxSize` is set).
+ *  - `ranked` — `Node<readonly RankedCollectionEntry<T>[]>`, sorted by live
+ *    decayed score. **Lazy** — does NOT compute until subscribed (no internal
+ *    keepalive). Use `keepalive(coll.ranked)` for eager activation.
+ *  - `size` — `Node<number>`, count of entries.
+ *  - `_refreshTick` — `fromTimer`-driven `monotonicNs()` source, mounted only
+ *    when `decayRate > 0`. Drives `ranked`'s time-dependent re-derivation.
+ *  - `_seq` — sequence cursor for the audit log.
+ *  - `events` — bounded reactive log of every mutation.
+ *
+ * **Time as a reactive dep.** When `decayRate > 0`, `ranked`'s deps are
+ * `[items, refreshTick]` — the tick payload IS `monotonicNs()`, so the fn is
+ * pure of deps and dry-run-reproducible with a mocked clock.
+ *
+ * **Lazy timer.** With no subscriber to `ranked`, the timer source does not
+ * fire — the activation chain is downstream-driven. To keep the timer warm
+ * without consuming results, register `graph.addDisposer(keepalive(coll.ranked))`.
+ *
+ * **Eviction at write-time.** Score-based retention runs on every successful
+ * `upsert / remove / clear` (it is mutation-driven, not tick-driven). The
+ * retention scorer reads `monotonicNs()` to compute decayed scores at eviction
+ * time — this is a deliberate impurity vs. `ReactiveMapRetention.score`'s
+ * "pure of `(key, value)`" docstring: write-time is the right moment to evict
+ * stale-by-decay entries.
+ *
+ * **No imperative reads.** Subscribe to `items` / `ranked` for live snapshots,
+ * or use `itemNode(id)` for single-key reactive reads.
+ *
+ * **`rescore` ordering caveat.** `rescore()` reads `items.entries.cache`
+ * (the post-emission snapshot) and writes via `setMany`. When called
+ * stand-alone it sees the latest committed state. When wrapped inside a
+ * user-level `batch(() => { coll.upsert(...); coll.rescore(); })`, the
+ * `cache` snapshot reflects state BEFORE the batch — so a just-staged
+ * upsert is invisible to the rescore scan. If you need rescore to include
+ * the staged upsert, either call `rescore()` after the batch settles or
+ * pass the new `baseScore` directly via `upsert(id, value, { score })`.
+ *
+ * **Audit no-op records.** Like `lightCollection`, mutations record audit
+ * entries even when the impl was a no-op (e.g., `rescore()` on an empty
+ * store). Intentional — the framework records attempts.
+ *
+ * @category memory
+ */
+declare function collection<T>(name: string, opts?: CollectionOptions<T>): CollectionGraph<T>;
+type VectorBackend = "flat" | "hnsw";
+type VectorRecord<TMeta> = {
+    readonly id: string;
+    readonly vector: readonly number[];
+    readonly meta?: TMeta;
+    /** Wall-clock-monotonic timestamp at last upsert; used for the default LRU retention. */
+    readonly upsertedAtNs: number;
+};
+type VectorSearchResult<TMeta> = {
+    readonly id: string;
+    readonly score: number;
+    readonly meta?: TMeta;
+};
+type HnswAdapter<TMeta> = {
+    upsert: (id: string, vector: readonly number[], meta?: TMeta) => void;
+    remove: (id: string) => void;
+    clear: () => void;
+    search: (query: readonly number[], k: number) => ReadonlyArray<VectorSearchResult<TMeta>>;
+    /** Optional adapter teardown. Called from `graph.destroy()` via `addDisposer`. */
+    dispose?: () => void;
+};
+type VectorIndexOptions<TMeta> = {
+    name?: string;
+    backend?: VectorBackend;
+    dimension?: number;
+    /**
+     * Strict-dimension default. When `true` (default) AND `dimension` is unset,
+     * mixed-length upserts throw `RangeError`. Set `false` to opt into the
+     * lenient zero-padding behavior of {@link VectorIndexGraph.searchNode}.
+     */
+    strictDimension?: boolean;
+    /** Optional dependency seam for HNSW. */
+    hnswFactory?: () => HnswAdapter<TMeta>;
+    /** Maximum live entries (LRU-by-upsert-time when set; user-overridable via `retentionScore`). */
+    maxSize?: number;
+    /** Custom retention scorer. Higher score = kept. Defaults to `r => r.upsertedAtNs`. */
+    retentionScore?: (record: VectorRecord<TMeta>) => number;
+};
+interface VectorIndexAuditRecord extends BaseAuditRecord {
+    readonly action: "upsert" | "remove" | "clear" | "reindex" | "evict";
+    readonly id?: string;
+}
+type VectorIndexGraph<TMeta> = Graph & {
+    readonly backend: VectorBackend;
+    readonly events: ReactiveLogBundle<VectorIndexAuditRecord>;
+    readonly entries: Node<ReadonlyMap<string, VectorRecord<TMeta>>>;
+    upsert: (id: string, vector: readonly number[], meta?: TMeta) => void;
+    remove: (id: string) => void;
+    clear: () => void;
+    /** Re-push every live entry into the optional HNSW adapter. No-op for `flat`. */
+    reindex: () => void;
+    /**
+     * Reactive top-K search. Re-derives whenever entries / query / k change.
+     * Lazy. Use `firstValueFrom(searchNode(...))` for one-shot reads.
+     */
+    searchNode: (query: Node<readonly number[]>, k?: NodeOrValue<number>) => Node<readonly VectorSearchResult<TMeta>[]>;
+};
+/**
+ * Reactive vector store with optional HNSW backend.
+ *
+ * **Storage on `reactiveMap`.** `entries` is a `reactiveMap<id, VectorRecord<TMeta>>`
+ * with optional score-based retention (`maxSize` + LRU-by-`upsertedAtNs` by
+ * default; user can supply a custom `retentionScore`). On retention eviction,
+ * the HNSW adapter (if configured) is also notified via `adapter.remove(id)`.
+ *
+ * **Reactive search.** `searchNode(queryNode, k)` returns a `Node<readonly
+ * VectorSearchResult<TMeta>[]>` that re-derives on entries / query / k change.
+ * Lazy — only computes when subscribed. Imperative `search()` is intentionally
+ * not exposed (no-imperative-reads policy). Use `firstValueFrom(searchNode(...))`
+ * for one-shot reads.
+ *
+ * **Strict dimension.** Default `strictDimension: true` — if `dimension` is
+ * unset and an upsert produces a vector of a different length than the first
+ * upserted, throws `RangeError`. Pass `strictDimension: false` to opt into
+ * the lenient zero-padding fallback (the previous default).
+ *
+ * **Adapter lifecycle.** When the HNSW adapter exposes a `dispose()` method,
+ * it is bound to the graph's teardown via `addDisposer`. When retention
+ * evicts an entry, `adapter.remove(id)` is invoked synchronously inside the
+ * retention `onArchive` callback.
+ *
+ * **Cosine zero-pad.** The flat backend uses cosine similarity over the
+ * pairwise max-length zero-pad. Mixing dimensions silently degrades scores
+ * unless strict mode catches it at upsert time. For embedding-model vectors,
+ * L2-normalize at the source — `vectorIndex` does not normalize.
+ *
+ * @category memory
+ */
+declare function vectorIndex<TMeta>(opts?: VectorIndexOptions<TMeta>): VectorIndexGraph<TMeta>;
+type KnowledgeEdge<TRelation extends string = string> = {
+    readonly from: string;
+    readonly to: string;
+    readonly relation: TRelation;
+    readonly weight: number;
+};
+type KnowledgeGraphOptions = {
+    /** Cap on entity count (LRU-by-upsert-time when set). */
+    entitiesMaxSize?: number;
+    /** Cap on edge count (LRU-by-upsert-time when set). */
+    edgesMaxSize?: number;
+    /**
+     * Orphan-entity garbage collection. `"keep"` (default) leaves entities
+     * untouched when their last edge is unlinked; `"remove"` deletes the
+     * entity post-`unlink` if no edges reference it.
+     */
+    orphanGC?: "keep" | "remove";
+};
+interface KnowledgeGraphAuditRecord extends BaseAuditRecord {
+    readonly action: "upsertEntity" | "removeEntity" | "link" | "unlink" | "orphanRemove";
+    readonly id?: string;
+    readonly from?: string;
+    readonly to?: string;
+    readonly relation?: string;
+    /** Edge weight at the time of the `link`. Omitted for non-edge actions. */
+    readonly weight?: number;
+}
+type KnowledgeGraph<TEntity, TRelation extends string = string> = Graph & {
+    readonly events: ReactiveLogBundle<KnowledgeGraphAuditRecord>;
+    readonly entities: Node<ReadonlyMap<string, TEntity>>;
+    readonly edges: Node<ReadonlyMap<string, KnowledgeEdge<TRelation>>>;
+    readonly adjacencyOut: Node<ReadonlyMap<string, readonly KnowledgeEdge<TRelation>[]>>;
+    readonly adjacencyIn: Node<ReadonlyMap<string, readonly KnowledgeEdge<TRelation>[]>>;
+    readonly entityCount: Node<number>;
+    readonly edgeCount: Node<number>;
+    upsertEntity: (id: string, value: TEntity) => void;
+    removeEntity: (id: string) => void;
+    link: (from: string, to: string, relation: TRelation, weight?: number) => void;
+    unlink: (from: string, to: string, relation?: TRelation) => void;
+    relatedNode: (id: NodeOrValue<string>, relation?: NodeOrValue<TRelation>) => Node<readonly KnowledgeEdge<TRelation>[]>;
+};
+/**
+ * Reactive knowledge graph: entities + typed edges + symmetric adjacency.
+ *
+ * Topology (mounted on the returned graph):
+ *  - `entities` — `reactiveMap<id, TEntity>` (optional `entitiesMaxSize` LRU).
+ *  - `edges` — `reactiveMap<tripleKey, KnowledgeEdge<TRelation>>` keyed by
+ *    `${from}${to}${relation}` (optional `edgesMaxSize` LRU).
+ *    Entity IDs / relations must NOT contain ``.
+ *  - `adjacencyOut` — `Node<ReadonlyMap<from, readonly edge[]>>`. **Full O(E)
+ *    rebuild on every `link` / `unlink` mutation.** (Prior JSDoc claim of
+ *    "O(E) build" referred to a single rebuild — the per-mutation cost is
+ *    O(E), not O(1) amortized. For very large graphs with frequent edge
+ *    churn, consider batching via `reactiveMap.setMany`.)
+ *  - `adjacencyIn` — `Node<ReadonlyMap<to, readonly edge[]>>`. Same O(E) per
+ *    mutation rebuild characteristic.
+ *  - `entityCount` / `edgeCount` — observability deriveds.
+ *  - `events` — bounded reactive audit log.
+ *
+ * **`link()` semantics.** Calling `link(a, b, rel, w)` twice with different
+ * weights replaces the weight on the existing edge (keyed by the triple).
+ * `unlink` then `link` re-creates the edge (and bumps `lastUpsertNs` for
+ * retention purposes).
+ *
+ * **Edge weight convention.** Higher weight = stronger relation. Default `1`.
+ *
+ * **Orphan GC.** `orphanGC: "remove"` deletes an entity from `entities` after
+ * an `unlink` that empties its adjacency on both sides. Default `"keep"`.
+ *
+ * **No imperative reads.** Use `relatedNode(id, relation?)` for reactive reads.
+ *
+ * @category memory
+ */
+declare function knowledgeGraph<TEntity, TRelation extends string = string>(name: string, opts?: KnowledgeGraphOptions): KnowledgeGraph<TEntity, TRelation>;
+
+export { type AdmissionFilter, type CascadeEvent, type CascadeOverflow, type CascadeReason, type CollectionAuditRecord, type CollectionEntry, type CollectionGraph, type CollectionOptions, type CollectionScoreFn, type DecayPolicy, type DependentsIndex, type FactId, type FactStore, type FactStoreAuditRecord, type HnswAdapter, type KnowledgeEdge, type KnowledgeGraph, type KnowledgeGraphAuditRecord, type KnowledgeGraphOptions, type MemoryAnswer, type MemoryFragment, type MemoryQuery, NodeOrValue, type OutcomeSignal, type RankedCollectionEntry, type ReactiveFactStoreConfig, type ReactiveFactStoreGraph, type ReviewRequest, type ScoringPolicy, type ShardKey, type StoreReadHandle, type VectorBackend, type VectorIndexAuditRecord, type VectorIndexGraph, type VectorIndexOptions, type VectorRecord, type VectorSearchResult, collection, cosineSimilarity, knowledgeGraph, reactiveFactStore, vectorIndex };