@graphrefly/graphrefly 0.44.0 → 0.45.0

package/dist/index-CYq8vAyV.d.ts

@@ -1,291 +0,0 @@
-import { j as CompileSpecOptions, G as GraphSpec, c as GraphSpecCatalog, C as CatalogFnEntry, a as CatalogSourceEntry, b as ConfigFieldSchema, F as FnFactory, d as GraphSpecFeedbackEdge, e as GraphSpecNode, f as GraphSpecTemplate, g as GraphSpecTemplateRef, h as GraphSpecValidation, S as SourceFactory } from './index-CMh5Rz1y.js';
-import { G as Graph, o as GraphNodeFactory, m as GraphDiffResult } from './graph-D9LFnda9.js';
-import { KvStorageTier } from './extra/storage-tiers.js';
-
-/**
- * Surface: create a graph from a {@link GraphSpec} (§9.3-core).
- *
- * Thin wrapper over {@link compileSpec} that converts the two failure modes
- * ({@link validateSpec} structural errors, and catalog-aware validation
- * errors) into typed {@link SurfaceError} throws. Consumers are MCP/CLI
- * wrappers, not end-user graph code — those should import `compileSpec`
- * directly.
- *
- * @module
- */
-
-/** Options for {@link createGraph}. Same shape as {@link CompileSpecOptions}. */
-type CreateGraphOptions = CompileSpecOptions;
-/**
- * Build a {@link Graph} from a parsed {@link GraphSpec} with surface-layer
- * error typing.
- *
- * @throws {SurfaceError} `invalid-spec` for structural errors;
- *   `catalog-error` when fn/source names or config don't match the catalog.
- */
-declare function createGraph(spec: GraphSpec, opts?: CreateGraphOptions): Graph;
-
-/**
- * Typed errors for the surface layer (§9.3-core).
- *
- * The surface layer is consumed by `@graphrefly/mcp-server` and
- * `@graphrefly/cli`. Both have native error channels (MCP's `isError` flag,
- * CLI's exit codes), so surface functions throw a {@link SurfaceError}
- * carrying a structured code + details payload that wrappers can map to
- * their native shape. No `Result` envelope — keep the callsite idiom
- * `try/catch` and let each wrapper surface the error its own way.
- *
- * @module
- */
-/** Structured error codes emitted by the surface layer. JSON-safe. */
-type SurfaceErrorCode = "invalid-spec" | "graph-not-found" | "graph-exists" | "snapshot-not-found" | "node-not-found" | "reduce-timeout" | "catalog-error" | "restore-failed" | "snapshot-failed" | "tier-no-list" | "compose-not-configured" | "compose-failed" | "internal-error";
-/** JSON-safe shape surfaces should echo back through the wrapper. */
-interface SurfaceErrorPayload {
-    code: SurfaceErrorCode;
-    message: string;
-    /** Optional structured detail; must be JSON-safe. */
-    details?: Readonly<Record<string, unknown>>;
-}
-/**
- * Thrown by surface layer functions on failure. `code` is the stable
- * machine-readable identifier; `details` carries structured context
- * (e.g. `validateSpec` errors, missing path name). Both fields round-trip
- * through `toJSON()` for wrappers that serialize errors over the wire.
- */
-declare class SurfaceError extends Error {
-    readonly code: SurfaceErrorCode;
-    readonly details?: Readonly<Record<string, unknown>>;
-    constructor(code: SurfaceErrorCode, message: string, details?: Readonly<Record<string, unknown>>);
-    /**
-     * JSON-safe payload for wire serialization. Defensively validates
-     * `details` — if it can't be round-tripped through `JSON.stringify`
-     * (cyclic refs, `BigInt`, `Error` instance not pre-toJSON'd), the
-     * payload falls back to `{code, message}` only rather than crashing
-     * the MCP/CLI wrapper when it serializes this error onto the wire.
-     */
-    toJSON(): SurfaceErrorPayload;
-}
-/** Wrap any thrown value as a SurfaceError. Idempotent on existing SurfaceError. */
-declare function asSurfaceError(err: unknown, fallbackCode?: SurfaceErrorCode): SurfaceError;
-
-/**
- * Surface: one-shot `input → pipeline → output` (§9.3-core).
- *
- * `runReduction` compiles a {@link GraphSpec}, pushes an input value to a
- * named state node, awaits the first post-push DATA emission on a named
- * output, then disposes the graph. Stateless per call — no graphId, no
- * registry.
- *
- * Named `runReduction` (not `reduce`) to avoid collision with the
- * reactive {@link reduce} operator in `extra/operators.ts`. The MCP tool
- * name (`graphrefly_reduce`) and CLI subcommand (`graphrefly reduce`) use
- * the short form; the library export carries the verb.
- *
- * The subscribe-before-push ordering is deliberate. `graph.set` propagates
- * synchronously for sync derived/operator chains; for async sources
- * (`fromPromise`, `fromAsyncIter`, LLM adapters) the first post-push DATA
- * arrives on a later tick. Subscribing before the push catches both, and
- * skipping the priming push-on-subscribe emission avoids resolving with the
- * stale pre-push cache (spec §2.2).
- *
- * @module
- */
-
-/** Options for {@link reduce}. */
-interface ReduceOptions {
-    /** Fn/source catalog for {@link createGraph}. */
-    catalog?: GraphSpecCatalog;
-    /** Path of the state node that receives the input. Default `"input"`. */
-    inputPath?: string;
-    /** Path of the node whose first post-push DATA is the result. Default `"output"`. */
-    outputPath?: string;
-    /** Hard deadline in milliseconds. Default `30_000`. */
-    timeoutMs?: number;
-}
-/**
- * Run a spec as a one-shot reduction: `input → graph → output`.
- *
- * Resolves on the first `[DATA, v]` **or** `[RESOLVED]` emitted by
- * `outputPath` after the input push. The RESOLVED path handles spec
- * §1.3.3 equals-substitution (output recomputed to a value equal to its
- * cache, so the graph skips the DATA push) by returning `outputNode.cache`
- * — the caller always gets the settled value, never hangs on idempotent
- * inputs.
- *
- * @throws {SurfaceError} `invalid-spec` / `catalog-error` (propagated from
- *   {@link createGraph}), `node-not-found` when `inputPath`/`outputPath`
- *   can't be resolved, `reduce-timeout` when `timeoutMs` elapses without
- *   a post-push emission, or the ERROR payload from the graph re-thrown
- *   as `internal-error`.
- */
-declare function runReduction(spec: GraphSpec, input: unknown, opts?: ReduceOptions): Promise<unknown>;
-
-/**
- * Surface: snapshot save/restore/diff/list over {@link KvStorageTier} (§9.3-core).
- *
- * One-shot snapshot management for stateless callers (MCP tools, CLI
- * commands) layered on the existing multi-tier auto-checkpoint substrate.
- * A saved snapshot is a `mode: "full"` {@link GraphCheckpointRecord} with
- * `seq: 0` — byte-identical to the baseline anchor
- * {@link Graph.attachSnapshotStorage} writes on its first flush. An
- * auto-checkpointed graph can therefore be restored through this surface,
- * and a surface-saved snapshot can be picked up by `attachSnapshotStorage({
- * autoRestore: true })`.
- *
- * The wire envelope stays at {@link SNAPSHOT_WIRE_VERSION}; no new format.
- *
- * @module
- */
-
-/**
- * Current envelope version. Re-exported from `graph.ts` so the one-shot
- * surface path and `Graph.attachSnapshotStorage` write byte-identical
- * `format_version` fields — no silent wire drift.
- */
-declare const SNAPSHOT_WIRE_VERSION = 1;
-/** Shape returned by {@link saveSnapshot}. */
-interface SaveSnapshotResult {
-    snapshotId: string;
-    timestamp_ns: number;
-}
-/** Options for {@link restoreSnapshot}. */
-interface RestoreSnapshotOptions {
-    /** Passthrough to `Graph.fromSnapshot`. First matching pattern wins. */
-    factories?: Record<string, GraphNodeFactory>;
-}
-/**
- * Write a graph's current state as a one-shot `mode: "full"` record.
- *
- * Uses the same {@link GraphCheckpointRecord} envelope as
- * {@link Graph.attachSnapshotStorage} so the two persistence paths interoperate.
- *
- * @throws {SurfaceError} `snapshot-failed` when the tier's `save` throws.
- */
-declare function saveSnapshot(graph: Graph, snapshotId: string, tier: KvStorageTier): Promise<SaveSnapshotResult>;
-/**
- * Load a snapshot from a tier and materialize it as a new {@link Graph}.
- *
- * Uses {@link Graph.fromSnapshot} to reconstruct topology; pass
- * `factories` when the graph includes non-state nodes that the default
- * hydrator can't rebuild on its own.
- *
- * **Requires a `mode: "full"` record.** Surface-written snapshots from
- * {@link saveSnapshot} always qualify. Records written by
- * {@link Graph.attachSnapshotStorage} with `compactEvery > 1` may be
- * `mode: "diff"` between compacts — those throw `restore-failed` until
- * the tier's next compact flush (or until Phase 8.7 WAL replay lands).
- * If you need interop during development, either call
- * {@link saveSnapshot} explicitly (always full) or configure
- * `attachSnapshotStorage({compactEvery: 1})`.
- *
- * @throws {SurfaceError} `snapshot-not-found` on miss; `restore-failed`
- *   when the payload shape doesn't match, when the record is
- *   `mode: "diff"`, or when `Graph.fromSnapshot` rejects.
- */
-declare function restoreSnapshot(snapshotId: string, tier: KvStorageTier, opts?: RestoreSnapshotOptions): Promise<Graph>;
-/**
- * Load two snapshots and compute a {@link GraphDiffResult} via static
- * {@link Graph.diff}. Returns the audit shape (structural + value diff,
- * no payload); use {@link diffForWAL} directly for WAL-oriented diffs.
- *
- * @throws {SurfaceError} `snapshot-not-found` on either miss.
- */
-declare function diffSnapshots(snapshotIdA: string, snapshotIdB: string, tier: KvStorageTier): Promise<GraphDiffResult>;
-/**
- * Enumerate snapshot ids on a tier.
- *
- * Only keys written by {@link saveSnapshot} are returned. Surface-written
- * records are stored under the `"snapshot:"` key prefix and decoded back to
- * the caller-visible id before being returned — other keys on the same tier
- * (notably `attachSnapshotStorage` baseline/WAL keys written under `graph.name`) are
- * filtered out automatically. This lets a single tier back both the surface
- * and `attachSnapshotStorage` without leaking graph names through `listSnapshots`.
- *
- * @param tier — the storage tier to enumerate.
- * @param opts.includeUnprefixed — when `true`, also return keys that are
- *   NOT under the namespacing prefix. Off by default; set this when reading
- *   pre-namespacing snapshot sets.
- *
- *   **Caveat:** when a tier is shared with {@link Graph.attachSnapshotStorage}, its
- *   auto-checkpoint baseline + WAL keys (written under `graph.name`) are
- *   unprefixed. Calling with `includeUnprefixed: true` returns those keys
- *   alongside surface snapshots — and subsequent `restoreSnapshot` /
- *   `deleteSnapshot` will operate on them via the fallback-lookup path,
- *   potentially overwriting or deleting live auto-checkpoint state. Use
- *   `includeUnprefixed` only against tiers you know are NOT shared with
- *   `attachSnapshotStorage`, or follow up with a predicate filter to separate
- *   ids you own from ones owned by other subsystems.
- *
- * @throws {SurfaceError} `tier-no-list` when the tier does not implement
- *   the optional `list()` method. Check `typeof tier.list === "function"`
- *   before calling if you want to branch on capability.
- */
-declare function listSnapshots(tier: KvStorageTier, opts?: {
-    includeUnprefixed?: boolean;
-}): Promise<readonly string[]>;
-/**
- * Delete a snapshot from a tier.
- *
- * Silent on miss (clear semantics). `tier.clear` is optional — throws
- * `snapshot-failed` when the tier is append-only.
- *
- * @throws {SurfaceError} `snapshot-failed` when `clear` is unsupported
- *   or throws.
- */
-declare function deleteSnapshot(snapshotId: string, tier: KvStorageTier): Promise<void>;
-
-/**
- * Surface layer (§9.3-core) — shared, JSON-safe operations consumed by
- * `@graphrefly/mcp-server` and `@graphrefly/cli`.
- *
- * The surface is a thin projection of existing Graph APIs (`describe`,
- * `observe`, `explain`, `snapshot`, `restore`, static `diff`), plus two
- * genuinely new operations:
- *
- * 1. {@link createGraph} — `compileSpec` wrapped with typed surface errors.
- * 2. {@link reduce} — one-shot `input → pipeline → output`.
- *
- * Snapshot persistence reuses the {@link KvStorageTier} substrate introduced
- * for `Graph.attachSnapshotStorage`, so one-shot snapshots and auto-checkpoints
- * share the {@link GraphCheckpointRecord} envelope. No new wire format.
- *
- * Errors throw as {@link SurfaceError} — wrappers map to their native
- * error channel (MCP `isError`, CLI exit code). No `Result<T, E>` wrapper.
- *
- * @module
- */
-
-declare const index_CatalogFnEntry: typeof CatalogFnEntry;
-declare const index_CatalogSourceEntry: typeof CatalogSourceEntry;
-declare const index_ConfigFieldSchema: typeof ConfigFieldSchema;
-type index_CreateGraphOptions = CreateGraphOptions;
-declare const index_FnFactory: typeof FnFactory;
-declare const index_GraphSpec: typeof GraphSpec;
-declare const index_GraphSpecCatalog: typeof GraphSpecCatalog;
-declare const index_GraphSpecFeedbackEdge: typeof GraphSpecFeedbackEdge;
-declare const index_GraphSpecNode: typeof GraphSpecNode;
-declare const index_GraphSpecTemplate: typeof GraphSpecTemplate;
-declare const index_GraphSpecTemplateRef: typeof GraphSpecTemplateRef;
-declare const index_GraphSpecValidation: typeof GraphSpecValidation;
-type index_ReduceOptions = ReduceOptions;
-type index_RestoreSnapshotOptions = RestoreSnapshotOptions;
-declare const index_SNAPSHOT_WIRE_VERSION: typeof SNAPSHOT_WIRE_VERSION;
-type index_SaveSnapshotResult = SaveSnapshotResult;
-declare const index_SourceFactory: typeof SourceFactory;
-type index_SurfaceError = SurfaceError;
-declare const index_SurfaceError: typeof SurfaceError;
-type index_SurfaceErrorCode = SurfaceErrorCode;
-type index_SurfaceErrorPayload = SurfaceErrorPayload;
-declare const index_asSurfaceError: typeof asSurfaceError;
-declare const index_createGraph: typeof createGraph;
-declare const index_deleteSnapshot: typeof deleteSnapshot;
-declare const index_diffSnapshots: typeof diffSnapshots;
-declare const index_listSnapshots: typeof listSnapshots;
-declare const index_restoreSnapshot: typeof restoreSnapshot;
-declare const index_runReduction: typeof runReduction;
-declare const index_saveSnapshot: typeof saveSnapshot;
-declare namespace index {
-  export { index_CatalogFnEntry as CatalogFnEntry, index_CatalogSourceEntry as CatalogSourceEntry, index_ConfigFieldSchema as ConfigFieldSchema, type index_CreateGraphOptions as CreateGraphOptions, index_FnFactory as FnFactory, index_GraphSpec as GraphSpec, index_GraphSpecCatalog as GraphSpecCatalog, index_GraphSpecFeedbackEdge as GraphSpecFeedbackEdge, index_GraphSpecNode as GraphSpecNode, index_GraphSpecTemplate as GraphSpecTemplate, index_GraphSpecTemplateRef as GraphSpecTemplateRef, index_GraphSpecValidation as GraphSpecValidation, type index_ReduceOptions as ReduceOptions, type index_RestoreSnapshotOptions as RestoreSnapshotOptions, index_SNAPSHOT_WIRE_VERSION as SNAPSHOT_WIRE_VERSION, type index_SaveSnapshotResult as SaveSnapshotResult, index_SourceFactory as SourceFactory, index_SurfaceError as SurfaceError, type index_SurfaceErrorCode as SurfaceErrorCode, type index_SurfaceErrorPayload as SurfaceErrorPayload, index_asSurfaceError as asSurfaceError, index_createGraph as createGraph, index_deleteSnapshot as deleteSnapshot, index_diffSnapshots as diffSnapshots, index_listSnapshots as listSnapshots, index_restoreSnapshot as restoreSnapshot, index_runReduction as runReduction, index_saveSnapshot as saveSnapshot };
-}
-
-export { type CreateGraphOptions as C, type ReduceOptions as R, SNAPSHOT_WIRE_VERSION as S, type RestoreSnapshotOptions as a, type SaveSnapshotResult as b, SurfaceError as c, type SurfaceErrorCode as d, type SurfaceErrorPayload as e, asSurfaceError as f, createGraph as g, deleteSnapshot as h, diffSnapshots as i, runReduction as j, index as k, listSnapshots as l, restoreSnapshot as r, saveSnapshot as s };

package/dist/index-CZ3r5Rxp.d.ts

@@ -1,374 +0,0 @@
-import { N as Node } from './node-kK3CvTrR.js';
-import { B as BaseAuditRecord } from './index-Yq60JP3s.js';
-import { a as ReactiveLogBundle } from './reactive-log-BKALbfal.js';
-import { G as Graph } from './graph-D9LFnda9.js';
-
-/**
- * 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 lightMutation} 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;
-/** Public alias for the `Node | value` shape accepted by reactive read factories. */
-type NodeOrValue<T> = T | Node<T>;
-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>;
-
-type index_CollectionAuditRecord = CollectionAuditRecord;
-type index_CollectionEntry<T> = CollectionEntry<T>;
-type index_CollectionGraph<T> = CollectionGraph<T>;
-type index_CollectionOptions<T> = CollectionOptions<T>;
-type index_CollectionScoreFn<T> = CollectionScoreFn<T>;
-type index_HnswAdapter<TMeta> = HnswAdapter<TMeta>;
-type index_KnowledgeEdge<TRelation extends string = string> = KnowledgeEdge<TRelation>;
-type index_KnowledgeGraph<TEntity, TRelation extends string = string> = KnowledgeGraph<TEntity, TRelation>;
-type index_KnowledgeGraphAuditRecord = KnowledgeGraphAuditRecord;
-type index_KnowledgeGraphOptions = KnowledgeGraphOptions;
-type index_NodeOrValue<T> = NodeOrValue<T>;
-type index_RankedCollectionEntry<T> = RankedCollectionEntry<T>;
-type index_VectorBackend = VectorBackend;
-type index_VectorIndexAuditRecord = VectorIndexAuditRecord;
-type index_VectorIndexGraph<TMeta> = VectorIndexGraph<TMeta>;
-type index_VectorIndexOptions<TMeta> = VectorIndexOptions<TMeta>;
-type index_VectorRecord<TMeta> = VectorRecord<TMeta>;
-type index_VectorSearchResult<TMeta> = VectorSearchResult<TMeta>;
-declare const index_collection: typeof collection;
-declare const index_cosineSimilarity: typeof cosineSimilarity;
-declare const index_knowledgeGraph: typeof knowledgeGraph;
-declare const index_vectorIndex: typeof vectorIndex;
-declare namespace index {
-  export { type index_CollectionAuditRecord as CollectionAuditRecord, type index_CollectionEntry as CollectionEntry, type index_CollectionGraph as CollectionGraph, type index_CollectionOptions as CollectionOptions, type index_CollectionScoreFn as CollectionScoreFn, type index_HnswAdapter as HnswAdapter, type index_KnowledgeEdge as KnowledgeEdge, type index_KnowledgeGraph as KnowledgeGraph, type index_KnowledgeGraphAuditRecord as KnowledgeGraphAuditRecord, type index_KnowledgeGraphOptions as KnowledgeGraphOptions, type index_NodeOrValue as NodeOrValue, type index_RankedCollectionEntry as RankedCollectionEntry, type index_VectorBackend as VectorBackend, type index_VectorIndexAuditRecord as VectorIndexAuditRecord, type index_VectorIndexGraph as VectorIndexGraph, type index_VectorIndexOptions as VectorIndexOptions, type index_VectorRecord as VectorRecord, type index_VectorSearchResult as VectorSearchResult, index_collection as collection, index_cosineSimilarity as cosineSimilarity, index_knowledgeGraph as knowledgeGraph, index_vectorIndex as vectorIndex };
-}
-
-export { type CollectionGraph as C, type HnswAdapter as H, type KnowledgeGraph as K, type NodeOrValue as N, type RankedCollectionEntry as R, type VectorSearchResult as V, type VectorIndexGraph as a, type CollectionAuditRecord as b, type CollectionEntry as c, type CollectionOptions as d, type CollectionScoreFn as e, type KnowledgeEdge as f, type KnowledgeGraphAuditRecord as g, type KnowledgeGraphOptions as h, index as i, type VectorBackend as j, type VectorIndexAuditRecord as k, type VectorIndexOptions as l, type VectorRecord as m, collection as n, cosineSimilarity as o, knowledgeGraph as p, vectorIndex as v };