@graphrefly/graphrefly 0.37.0 → 0.38.0

package/dist/index-Di7OdwlO.d.ts

@@ -0,0 +1,427 @@
+import { a as Node } from './node-fSc-hCv8.js';
+import { R as ReactiveLogBundle } from './reactive-log-BgWSA1fg.js';
+import { G as Graph } from './graph-BjW1taJl.js';
+import { B as BaseAuditRecord } from './imperative-audit-ahAE65a9.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).
+ *
+ * Five primitives:
+ * - {@link decay} — pure exponential-decay utility.
+ * - {@link lightCollection} — Map + LRU eviction + audit log; non-Graph bundle.
+ * - {@link collection} / {@link CollectionGraph} — scored memory store with live
+ *   decay-ranking via reactive timer dep.
+ * - {@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
+ */
+
+/**
+ * Exponential decay with floor: `score = max(minScore, baseScore * exp(-ratePerSecond * ageSeconds))`.
+ *
+ * Tolerant fallbacks (deliberate for use inside reactive derived fns):
+ * - non-finite `baseScore` → `minScore`
+ * - non-positive `ageSeconds` (incl. clock skew) → `max(minScore, baseScore)` (no decay)
+ * - non-positive `ratePerSecond` → `max(minScore, baseScore)` (no decay; rate=0 disables)
+ *
+ * Underflow boundary: `Math.exp(-745) === 0`. For very long ages × rates the
+ * result clamps to `minScore`; if you need slow decay over years, choose a
+ * smaller `ratePerSecond` rather than relying on graceful underflow.
+ *
+ * Half-life conversion: `ratePerSecond = Math.LN2 / halfLifeSeconds`.
+ *
+ * @category memory
+ */
+declare function decay(baseScore: number, ageSeconds: number, ratePerSecond: number, minScore?: number): number;
+/**
+ * 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 LightCollectionEntry<T> = {
+    readonly id: string;
+    readonly value: T;
+    readonly createdAtNs: number;
+    readonly lastAccessNs: number;
+};
+type LightCollectionOptions = {
+    name?: string;
+    maxSize?: number;
+};
+interface LightCollectionAuditRecord extends BaseAuditRecord {
+    readonly action: "upsert" | "remove" | "clear";
+    readonly id?: string;
+}
+type LightCollectionBundle<T> = {
+    readonly entries: Node<ReadonlyMap<string, LightCollectionEntry<T>>>;
+    readonly events: ReactiveLogBundle<LightCollectionAuditRecord>;
+    upsert: (id: string, value: T) => void;
+    remove: (id: string) => void;
+    clear: () => void;
+    itemNode: (id: NodeOrValue<string>) => Node<LightCollectionEntry<T> | undefined>;
+    hasNode: (id: NodeOrValue<string>) => Node<boolean>;
+};
+/**
+ * Reactive Map of {@link LightCollectionEntry} with native LRU eviction by
+ * `maxSize`. Backed by `reactiveMap` so iteration order, snapshot delivery,
+ * and copy-on-write semantics match the rest of the data-structure tier.
+ *
+ * **No-Graph composition.** `bundle.entries` is a detached `state()` — mount
+ * manually with `parent.add(bundle.entries)` for `describe()` / `lens.flow`
+ * coverage.
+ *
+ * **`createdAtNs` preservation.** Re-upserting an existing id keeps the
+ * original `createdAtNs`; only `lastAccessNs` advances. Eviction is purely
+ * LRU-by-`lastAccessNs` (newest wins) via `reactiveMap`'s native `maxSize`.
+ *
+ * **No imperative reads.** Per the no-imperative-reads policy: subscribe to
+ * `entries` for the live snapshot, or use `itemNode(id)` / `hasNode(id)` for
+ * single-key reactive reads. For one-shot snapshots use `firstValueFrom` or
+ * `node.cache` after `awaitSettled`.
+ *
+ * **Audit log freeze contract.** Mutations are wrapped via `lightMutation`,
+ * which deep-freezes args at entry by default (per the Audit 2 framework).
+ * That means the `value` you pass to `upsert(id, value)` is frozen by the
+ * time it lands in `LightCollectionEntry.value`. If you store mutable
+ * payloads and need them mutable post-upsert, opt out via `lightMutation`'s
+ * `freeze: false` (currently internal — not exposed on the bundle; if you
+ * hit this, file in `docs/optimizations.md`).
+ *
+ * **Audit no-op records.** Mutations record an audit entry even when the
+ * impl was a no-op (`remove(id)` for a missing id, `clear()` on empty store).
+ * The framework records attempts, not state changes — this is intentional
+ * (see `_internal/imperative-audit.ts` rationale). Audit consumers that
+ * reconstruct state by replaying records can ignore no-op redundant entries
+ * without losing correctness.
+ *
+ * @category memory
+ */
+declare function lightCollection<T>(opts?: LightCollectionOptions): LightCollectionBundle<T>;
+type CollectionEntry<T> = LightCollectionEntry<T> & {
+    readonly baseScore: number;
+};
+type RankedCollectionEntry<T> = CollectionEntry<T> & {
+    readonly score: number;
+};
+type CollectionScoreFn<T> = (value: T) => number;
+type CollectionOptions<T> = {
+    maxSize?: number;
+    /**
+     * 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`.
+     */
+    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`.
+     */
+    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>>>;
+    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.
+     */
+    rescore: () => void;
+    itemNode: (id: NodeOrValue<string>) => Node<CollectionEntry<T> | undefined>;
+};
+/**
+ * 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_LightCollectionAuditRecord = LightCollectionAuditRecord;
+type index_LightCollectionBundle<T> = LightCollectionBundle<T>;
+type index_LightCollectionEntry<T> = LightCollectionEntry<T>;
+type index_LightCollectionOptions = LightCollectionOptions;
+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_decay: typeof decay;
+declare const index_knowledgeGraph: typeof knowledgeGraph;
+declare const index_lightCollection: typeof lightCollection;
+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_LightCollectionAuditRecord as LightCollectionAuditRecord, type index_LightCollectionBundle as LightCollectionBundle, type index_LightCollectionEntry as LightCollectionEntry, type index_LightCollectionOptions as LightCollectionOptions, 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_decay as decay, index_knowledgeGraph as knowledgeGraph, index_lightCollection as lightCollection, index_vectorIndex as vectorIndex };
+}
+
+export { type CollectionAuditRecord as C, type HnswAdapter as H, type KnowledgeGraph as K, type LightCollectionBundle as L, type NodeOrValue as N, type RankedCollectionEntry as R, type VectorSearchResult as V, type VectorIndexGraph as a, type CollectionEntry as b, type CollectionGraph 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 LightCollectionAuditRecord as j, type LightCollectionEntry as k, type LightCollectionOptions as l, type VectorBackend as m, type VectorIndexAuditRecord as n, type VectorIndexOptions as o, type VectorRecord as p, collection as q, cosineSimilarity as r, decay as s, knowledgeGraph as t, lightCollection as u, vectorIndex as v };

package/dist/{index-CzIWlnPp.d.ts → index-DqICM_I7.d.ts}

@@ -1,11 +1,11 @@
 import { NodeInput } from './extra/sources.js';
 import { a as Node } from './node-fSc-hCv8.js';
 import { L as LLMAdapter } from './types-CidcBDuk.js';
-import { T as TopicGraph, M as MessagingHubGraph } from './index-D0ZxFXYl.js';
-import { E as Evaluator, D as DatasetItem, a as EvalResult$1, R as RefineStrategy, b as RefineLoopOptions, c as RefineStatus } from './index-DPqR3wdW.js';
-import { G as Graph, s as GraphProfileResult, r as GraphProfileOptions } from './graph-YQXDndFy.js';
-import { G as GateController } from './pipeline-graph-DX2Twdj-.js';
-import { J as JobQueueGraph } from './index-9mbs_PIG.js';
+import { T as TopicGraph, M as MessagingHubGraph } from './index-BUFCHvOR.js';
+import { E as Evaluator, D as DatasetItem, a as EvalResult$1, R as RefineStrategy, b as RefineLoopOptions, c as RefineStatus } from './index-BI1wMfyc.js';
+import { G as Graph, u as GraphProfileResult, t as GraphProfileOptions } from './graph-BjW1taJl.js';
+import { G as GateController } from './pipeline-graph-9JBbmRxA.js';
+import { J as JobQueueGraph } from './index-D9vBTuzo.js';
 
 /**
  * Strategy model and priority scoring (roadmap §9.0).
@@ -187,6 +187,20 @@ type StrategyKey = `${RootCause}→${Intervention}`;
  * for escape-hatch executors that carry opaque state.
  */
 type ExecuteOutput<A = unknown> = {
+    /**
+     * Execution outcome classification:
+     *
+     * - `"success"`: execution completed cleanly and the artifact (if any) is
+     *   ready for verification. The verifier should proceed with a full
+     *   evaluation pass.
+     * - `"failure"`: execution did not produce a usable artifact — the actuator
+     *   threw, a prompt parse failed, or `shouldApply` skipped the item. The
+     *   verifier should treat this as a non-result and route accordingly.
+     * - `"partial"`: execution produced a candidate that converged but did not
+     *   fully meet verification criteria. Used by `refineExecutor` when the
+     *   iteration cap is reached without full convergence; the artifact holds
+     *   the best candidate achieved.
+     */
     outcome: "success" | "failure" | "partial";
     detail: string;
     /**
@@ -201,6 +215,16 @@ type ExecuteOutput<A = unknown> = {
 /** Full execution result assembled downstream (LLM output + context). */
 interface ExecutionResult<A = unknown> {
     item: TriagedItem;
+    /**
+     * Execution outcome classification. Same semantics as
+     * {@link ExecuteOutput.outcome}:
+     *
+     * - `"success"`: execution completed cleanly; artifact is ready for
+     *   verification.
+     * - `"failure"`: no usable artifact was produced.
+     * - `"partial"`: best candidate produced but convergence criteria not met
+     *   (iteration cap reached in `refineExecutor`).
+     */
     outcome: "success" | "failure" | "partial";
     detail: string;
     /**
@@ -464,6 +488,52 @@ interface ActuatorExecutorConfig<R> {
  * ```
  */
 declare function actuatorExecutor<R>(config: ActuatorExecutorConfig<R>): HarnessExecutor<R>;
+/**
+ * Apply callback shape consumed by {@link dispatchActuator}. Same shape as
+ * {@link ActuatorExecutorConfig.apply}.
+ */
+type ActuatorApplyFn<R> = (item: TriagedItem, opts: {
+    signal: AbortSignal;
+}) => ActuatorResult<R>;
+/** Configuration for {@link dispatchActuator}. */
+interface DispatchActuatorConfig<R> {
+    /**
+     * Per-intervention apply callbacks. Keyed by `TriagedItem.intervention`.
+     * Items whose intervention is not in `routes` fall through to `default`
+     * (when set) or emit a skip-failure `ExecuteOutput`.
+     */
+    routes: Readonly<Partial<Record<TriagedItem["intervention"], ActuatorApplyFn<R>>>>;
+    /** Fallback apply callback for items whose intervention is not in `routes`. */
+    default?: ActuatorApplyFn<R>;
+    /** Node name prefix for `describe()` introspection. Default `"dispatch-actuator"`. */
+    name?: string;
+}
+/**
+ * Multi-intervention actuator — dispatches each `TriagedItem` to one of
+ * several `apply` callbacks based on `item.intervention`.
+ *
+ * Internally builds a single `actuatorExecutor` whose `apply` resolves the
+ * intervention → callback at call-time. Items with no matching route and no
+ * `default` emit a skip-failure with detail
+ * `"no route for intervention 'X'"`.
+ *
+ * @example Multi-intervention dogfood loop.
+ * ```ts
+ * const harness = harnessLoop("repair", {
+ *   adapter,
+ *   executor: dispatchActuator<CatalogPatch>({
+ *     routes: {
+ *       "catalog-fn": catalogFnActuator,
+ *       "template": templateActuator,
+ *       "docs": docEditActuator,
+ *     },
+ *     default: investigateActuator,
+ *   }),
+ *   verifier: evalVerifier<CatalogPatch>({ ... }),
+ * });
+ * ```
+ */
+declare function dispatchActuator<R>(config: DispatchActuatorConfig<R>): HarnessExecutor<R>;
 
 /**
  * autoSolidify — promote successful VERIFY runs into a durable artifact
@@ -1252,6 +1322,7 @@ declare function harnessTrace(harness: HarnessGraph, opts?: HarnessTraceOptions)
  * @module
  */
 
+type index_ActuatorApplyFn<R> = ActuatorApplyFn<R>;
 type index_ActuatorExecutorConfig<R> = ActuatorExecutorConfig<R>;
 type index_ActuatorResult<R> = ActuatorResult<R>;
 type index_AutoSolidifyConfig<R, T = R> = AutoSolidifyConfig<R, T>;
@@ -1263,6 +1334,7 @@ declare const index_DEFAULT_QUEUE_CONFIGS: typeof DEFAULT_QUEUE_CONFIGS;
 declare const index_DEFAULT_SEVERITY_WEIGHTS: typeof DEFAULT_SEVERITY_WEIGHTS;
 declare const index_DEFAULT_TRIAGE_PROMPT: typeof DEFAULT_TRIAGE_PROMPT;
 declare const index_DEFAULT_VERIFY_PROMPT: typeof DEFAULT_VERIFY_PROMPT;
+type index_DispatchActuatorConfig<R> = DispatchActuatorConfig<R>;
 type index_ErrorClass = ErrorClass;
 type index_ErrorClassifier = ErrorClassifier;
 type index_EvalDelta = EvalDelta;
@@ -1323,6 +1395,7 @@ declare const index_createIntakeBridge: typeof createIntakeBridge;
 declare const index_defaultErrorClassifier: typeof defaultErrorClassifier;
 declare const index_defaultLlmExecutor: typeof defaultLlmExecutor;
 declare const index_defaultLlmVerifier: typeof defaultLlmVerifier;
+declare const index_dispatchActuator: typeof dispatchActuator;
 declare const index_evalIntakeBridge: typeof evalIntakeBridge;
 declare const index_evalSource: typeof evalSource;
 declare const index_evalVerifier: typeof evalVerifier;
@@ -1337,7 +1410,7 @@ declare const index_resolvePromptFn: typeof resolvePromptFn;
 declare const index_strategyKey: typeof strategyKey;
 declare const index_strategyModel: typeof strategyModel;
 declare namespace index {
-  export { type index_ActuatorExecutorConfig as ActuatorExecutorConfig, type index_ActuatorResult as ActuatorResult, type index_AutoSolidifyConfig as AutoSolidifyConfig, type index_CodeChange as CodeChange, type index_CodeChangeBridgeOptions as CodeChangeBridgeOptions, index_DEFAULT_DECAY_RATE as DEFAULT_DECAY_RATE, index_DEFAULT_EXECUTE_PROMPT as DEFAULT_EXECUTE_PROMPT, index_DEFAULT_QUEUE_CONFIGS as DEFAULT_QUEUE_CONFIGS, index_DEFAULT_SEVERITY_WEIGHTS as DEFAULT_SEVERITY_WEIGHTS, index_DEFAULT_TRIAGE_PROMPT as DEFAULT_TRIAGE_PROMPT, index_DEFAULT_VERIFY_PROMPT as DEFAULT_VERIFY_PROMPT, type index_ErrorClass as ErrorClass, type index_ErrorClassifier as ErrorClassifier, type index_EvalDelta as EvalDelta, type index_EvalIntakeBridgeOptions as EvalIntakeBridgeOptions, type index_EvalJudgeScore as EvalJudgeScore, type index_EvalResult as EvalResult, type index_EvalTaskDelta as EvalTaskDelta, type index_EvalTaskResult as EvalTaskResult, type index_EvalVerifierConfig as EvalVerifierConfig, type index_EvalVerifierSummary as EvalVerifierSummary, type index_ExecuteOutput as ExecuteOutput, type index_ExecutePromptFn as ExecutePromptFn, type index_ExecutionResult as ExecutionResult, type index_HarnessEvalPairConfig as HarnessEvalPairConfig, type index_HarnessExecutor as HarnessExecutor, index_HarnessGraph as HarnessGraph, type index_HarnessLoopOptions as HarnessLoopOptions, type index_HarnessProfileResult as HarnessProfileResult, type index_HarnessTraceHandle as HarnessTraceHandle, type index_HarnessTraceOptions as HarnessTraceOptions, type index_HarnessVerifier as HarnessVerifier, type index_IntakeBridgeOptions as IntakeBridgeOptions, type index_IntakeItem as IntakeItem, type index_IntakeSource as IntakeSource, type index_Intervention as Intervention, type index_KnownIntakeSource as KnownIntakeSource, type index_LintError as LintError, type index_NotifyEffectOptions as NotifyEffectOptions, type index_NotifyTransport as NotifyTransport, type index_PrioritySignals as PrioritySignals, index_QUEUE_NAMES as QUEUE_NAMES, type index_QueueConfig as QueueConfig, type index_QueueRoute as QueueRoute, type index_RefineExecutorConfig as RefineExecutorConfig, type index_RefineExecutorResult as RefineExecutorResult, type index_RootCause as RootCause, type index_Severity as Severity, type index_StrategyEntry as StrategyEntry, type index_StrategyKey as StrategyKey, type index_StrategyModelBundle as StrategyModelBundle, type index_StrategySnapshot as StrategySnapshot, type index_TestFailure as TestFailure, type index_TraceDetail as TraceDetail, type index_TraceEvent as TraceEvent, type index_TraceEventType as TraceEventType, type index_TriagePromptFn as TriagePromptFn, type index_TriagedItem as TriagedItem, type index_VerifyOutput as VerifyOutput, type index_VerifyPromptFn as VerifyPromptFn, type index_VerifyResult as VerifyResult, index_actuatorExecutor as actuatorExecutor, index_affectedTaskFilter as affectedTaskFilter, index_autoSolidify as autoSolidify, index_beforeAfterCompare as beforeAfterCompare, index_codeChangeBridge as codeChangeBridge, index_createIntakeBridge as createIntakeBridge, index_defaultErrorClassifier as defaultErrorClassifier, index_defaultLlmExecutor as defaultLlmExecutor, index_defaultLlmVerifier as defaultLlmVerifier, index_evalIntakeBridge as evalIntakeBridge, index_evalSource as evalSource, index_evalVerifier as evalVerifier, index_harnessEvalPair as harnessEvalPair, index_harnessLoop as harnessLoop, index_harnessProfile as harnessProfile, index_harnessTrace as harnessTrace, index_notifyEffect as notifyEffect, index_priorityScore as priorityScore, index_refineExecutor as refineExecutor, index_resolvePromptFn as resolvePromptFn, index_strategyKey as strategyKey, index_strategyModel as strategyModel };
+  export { type index_ActuatorApplyFn as ActuatorApplyFn, type index_ActuatorExecutorConfig as ActuatorExecutorConfig, type index_ActuatorResult as ActuatorResult, type index_AutoSolidifyConfig as AutoSolidifyConfig, type index_CodeChange as CodeChange, type index_CodeChangeBridgeOptions as CodeChangeBridgeOptions, index_DEFAULT_DECAY_RATE as DEFAULT_DECAY_RATE, index_DEFAULT_EXECUTE_PROMPT as DEFAULT_EXECUTE_PROMPT, index_DEFAULT_QUEUE_CONFIGS as DEFAULT_QUEUE_CONFIGS, index_DEFAULT_SEVERITY_WEIGHTS as DEFAULT_SEVERITY_WEIGHTS, index_DEFAULT_TRIAGE_PROMPT as DEFAULT_TRIAGE_PROMPT, index_DEFAULT_VERIFY_PROMPT as DEFAULT_VERIFY_PROMPT, type index_DispatchActuatorConfig as DispatchActuatorConfig, type index_ErrorClass as ErrorClass, type index_ErrorClassifier as ErrorClassifier, type index_EvalDelta as EvalDelta, type index_EvalIntakeBridgeOptions as EvalIntakeBridgeOptions, type index_EvalJudgeScore as EvalJudgeScore, type index_EvalResult as EvalResult, type index_EvalTaskDelta as EvalTaskDelta, type index_EvalTaskResult as EvalTaskResult, type index_EvalVerifierConfig as EvalVerifierConfig, type index_EvalVerifierSummary as EvalVerifierSummary, type index_ExecuteOutput as ExecuteOutput, type index_ExecutePromptFn as ExecutePromptFn, type index_ExecutionResult as ExecutionResult, type index_HarnessEvalPairConfig as HarnessEvalPairConfig, type index_HarnessExecutor as HarnessExecutor, index_HarnessGraph as HarnessGraph, type index_HarnessLoopOptions as HarnessLoopOptions, type index_HarnessProfileResult as HarnessProfileResult, type index_HarnessTraceHandle as HarnessTraceHandle, type index_HarnessTraceOptions as HarnessTraceOptions, type index_HarnessVerifier as HarnessVerifier, type index_IntakeBridgeOptions as IntakeBridgeOptions, type index_IntakeItem as IntakeItem, type index_IntakeSource as IntakeSource, type index_Intervention as Intervention, type index_KnownIntakeSource as KnownIntakeSource, type index_LintError as LintError, type index_NotifyEffectOptions as NotifyEffectOptions, type index_NotifyTransport as NotifyTransport, type index_PrioritySignals as PrioritySignals, index_QUEUE_NAMES as QUEUE_NAMES, type index_QueueConfig as QueueConfig, type index_QueueRoute as QueueRoute, type index_RefineExecutorConfig as RefineExecutorConfig, type index_RefineExecutorResult as RefineExecutorResult, type index_RootCause as RootCause, type index_Severity as Severity, type index_StrategyEntry as StrategyEntry, type index_StrategyKey as StrategyKey, type index_StrategyModelBundle as StrategyModelBundle, type index_StrategySnapshot as StrategySnapshot, type index_TestFailure as TestFailure, type index_TraceDetail as TraceDetail, type index_TraceEvent as TraceEvent, type index_TraceEventType as TraceEventType, type index_TriagePromptFn as TriagePromptFn, type index_TriagedItem as TriagedItem, type index_VerifyOutput as VerifyOutput, type index_VerifyPromptFn as VerifyPromptFn, type index_VerifyResult as VerifyResult, index_actuatorExecutor as actuatorExecutor, index_affectedTaskFilter as affectedTaskFilter, index_autoSolidify as autoSolidify, index_beforeAfterCompare as beforeAfterCompare, index_codeChangeBridge as codeChangeBridge, index_createIntakeBridge as createIntakeBridge, index_defaultErrorClassifier as defaultErrorClassifier, index_defaultLlmExecutor as defaultLlmExecutor, index_defaultLlmVerifier as defaultLlmVerifier, index_dispatchActuator as dispatchActuator, index_evalIntakeBridge as evalIntakeBridge, index_evalSource as evalSource, index_evalVerifier as evalVerifier, index_harnessEvalPair as harnessEvalPair, index_harnessLoop as harnessLoop, index_harnessProfile as harnessProfile, index_harnessTrace as harnessTrace, index_notifyEffect as notifyEffect, index_priorityScore as priorityScore, index_refineExecutor as refineExecutor, index_resolvePromptFn as resolvePromptFn, index_strategyKey as strategyKey, index_strategyModel as strategyModel };
 }
 
-export { type TestFailure as $, type ActuatorExecutorConfig as A, type HarnessTraceOptions as B, type CodeChange as C, DEFAULT_DECAY_RATE as D, type ErrorClass as E, type HarnessVerifier as F, type IntakeItem as G, type HarnessEvalPairConfig as H, type IntakeBridgeOptions as I, type IntakeSource as J, type Intervention as K, type KnownIntakeSource as L, type LintError as M, type NotifyEffectOptions as N, type NotifyTransport as O, type PrioritySignals as P, QUEUE_NAMES as Q, type QueueConfig as R, type QueueRoute as S, type RefineExecutorConfig as T, type RefineExecutorResult as U, type RootCause as V, type Severity as W, type StrategyEntry as X, type StrategyKey as Y, type StrategyModelBundle as Z, type StrategySnapshot as _, type ActuatorResult as a, type TraceDetail as a0, type TraceEvent as a1, type TraceEventType as a2, type TriagePromptFn as a3, type TriagedItem as a4, type VerifyOutput as a5, type VerifyPromptFn as a6, type VerifyResult as a7, actuatorExecutor as a8, affectedTaskFilter as a9, autoSolidify as aa, beforeAfterCompare as ab, codeChangeBridge as ac, createIntakeBridge as ad, defaultErrorClassifier as ae, defaultLlmExecutor as af, defaultLlmVerifier as ag, evalIntakeBridge as ah, evalSource as ai, evalVerifier as aj, harnessEvalPair as ak, harnessLoop as al, harnessProfile as am, harnessTrace as an, notifyEffect as ao, priorityScore as ap, refineExecutor as aq, resolvePromptFn as ar, strategyKey as as, strategyModel as at, type AutoSolidifyConfig as b, type CodeChangeBridgeOptions as c, DEFAULT_EXECUTE_PROMPT as d, DEFAULT_QUEUE_CONFIGS as e, DEFAULT_SEVERITY_WEIGHTS as f, DEFAULT_TRIAGE_PROMPT as g, DEFAULT_VERIFY_PROMPT as h, index as i, type ErrorClassifier as j, type EvalDelta as k, type EvalIntakeBridgeOptions as l, type EvalJudgeScore as m, type EvalResult as n, type EvalTaskDelta as o, type EvalTaskResult as p, type EvalVerifierConfig as q, type EvalVerifierSummary as r, type ExecuteOutput as s, type ExecutePromptFn as t, type ExecutionResult as u, type HarnessExecutor as v, HarnessGraph as w, type HarnessLoopOptions as x, type HarnessProfileResult as y, type HarnessTraceHandle as z };
+export { type StrategyModelBundle as $, type ActuatorApplyFn as A, type HarnessProfileResult as B, type CodeChange as C, DEFAULT_DECAY_RATE as D, type ErrorClass as E, type HarnessTraceHandle as F, type HarnessTraceOptions as G, type HarnessEvalPairConfig as H, type HarnessVerifier as I, type IntakeBridgeOptions as J, type IntakeItem as K, type IntakeSource as L, type Intervention as M, type KnownIntakeSource as N, type LintError as O, type NotifyEffectOptions as P, type NotifyTransport as Q, type PrioritySignals as R, QUEUE_NAMES as S, type QueueConfig as T, type QueueRoute as U, type RefineExecutorConfig as V, type RefineExecutorResult as W, type RootCause as X, type Severity as Y, type StrategyEntry as Z, type StrategyKey as _, type ActuatorExecutorConfig as a, type StrategySnapshot as a0, type TestFailure as a1, type TraceDetail as a2, type TraceEvent as a3, type TraceEventType as a4, type TriagePromptFn as a5, type TriagedItem as a6, type VerifyOutput as a7, type VerifyPromptFn as a8, type VerifyResult as a9, actuatorExecutor as aa, affectedTaskFilter as ab, autoSolidify as ac, beforeAfterCompare as ad, codeChangeBridge as ae, createIntakeBridge as af, defaultErrorClassifier as ag, defaultLlmExecutor as ah, defaultLlmVerifier as ai, dispatchActuator as aj, evalIntakeBridge as ak, evalSource as al, evalVerifier as am, harnessEvalPair as an, harnessLoop as ao, harnessProfile as ap, harnessTrace as aq, notifyEffect as ar, priorityScore as as, refineExecutor as at, resolvePromptFn as au, strategyKey as av, strategyModel as aw, type ActuatorResult as b, type AutoSolidifyConfig as c, type CodeChangeBridgeOptions as d, DEFAULT_EXECUTE_PROMPT as e, DEFAULT_QUEUE_CONFIGS as f, DEFAULT_SEVERITY_WEIGHTS as g, DEFAULT_TRIAGE_PROMPT as h, index as i, DEFAULT_VERIFY_PROMPT as j, type DispatchActuatorConfig as k, type ErrorClassifier as l, type EvalDelta as m, type EvalIntakeBridgeOptions as n, type EvalJudgeScore as o, type EvalResult as p, type EvalTaskDelta as q, type EvalTaskResult as r, type EvalVerifierConfig as s, type EvalVerifierSummary as t, type ExecuteOutput as u, type ExecutePromptFn as v, type ExecutionResult as w, type HarnessExecutor as x, HarnessGraph as y, type HarnessLoopOptions as z };

package/dist/{index-BOfHwQc1.d.ts → index-ML6vHKXK.d.ts}

@@ -1,4 +1,4 @@
-import { G as Graph } from './graph-YQXDndFy.js';
+import { G as Graph } from './graph-BjW1taJl.js';
 
 /** Zustand-compatible Store API. */
 interface StoreApi<T> {