@graphrefly/graphrefly 0.44.0 → 0.45.0

package/dist/index-B17QddL1.d.cts

@@ -1,374 +0,0 @@
-import { N as Node } from './node-kK3CvTrR.cjs';
-import { B as BaseAuditRecord } from './index-D0aciIex.cjs';
-import { a as ReactiveLogBundle } from './reactive-log-DIGdYqQ6.cjs';
-import { G as Graph } from './graph-CWvEUQAq.cjs';
-
-/**
- * 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 };