@graphrefly/graphrefly 0.45.0 → 0.46.0

package/dist/memory-composers-CVQqPYEV.d.ts

@@ -0,0 +1,529 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { Graph, GraphOptions, GraphCheckpointRecord, GraphAttachStorageOptions } from '@graphrefly/pure-ts/graph';
+import { a as ChatMessage, k as ToolDefinition, j as ToolCall } from './types-BB5Lw-pB.js';
+import { StorageHandle, SnapshotStorageTier, ReactiveMapBundle, NodeInput } from '@graphrefly/pure-ts/extra';
+import { D as DistillBundle, a as DistillOptions, E as Extraction } from './distill-De6Rnn15.js';
+import { VectorSearchResult, CollectionGraph, collection, VectorIndexGraph, KnowledgeGraph } from './utils/memory/index.js';
+
+type ChatStreamOptions = {
+    graph?: GraphOptions;
+    maxMessages?: number;
+};
+declare class ChatStreamGraph extends Graph {
+    private readonly _log;
+    readonly messages: Node<readonly ChatMessage[]>;
+    /**
+     * Most recently appended message. Stays in the protocol SENTINEL state
+     * (`cache === undefined`, no DATA emitted) until the first append, then
+     * tracks the latest entry. Per COMPOSITION-GUIDE §1a, the SENTINEL is
+     * the canonical "no value yet" signal — consumers detect empty via
+     * `data[i] === undefined` inside reactive fns or `latest.cache === undefined`
+     * outside. No `T | null` placeholder, no `hasLatest` companion.
+     */
+    readonly latest: Node<ChatMessage>;
+    readonly messageCount: Node<number>;
+    constructor(name: string, opts?: ChatStreamOptions);
+    append(role: ChatMessage["role"], content: string, extra?: Partial<ChatMessage>): void;
+    appendToolResult(callId: string, content: string): void;
+    clear(): void;
+    allMessages(): readonly ChatMessage[];
+}
+declare function chatStream(name: string, opts?: ChatStreamOptions): ChatStreamGraph;
+
+type ToolRegistryOptions = {
+    graph?: GraphOptions;
+};
+/**
+ * `ToolRegistryGraph` — name-keyed registry of {@link ToolDefinition}s.
+ *
+ * **Reactive-only execution.** The only execution path is
+ * {@link executeReactive}, which returns a `Node<unknown>` for the handler
+ * result. Composing factories (`toolExecution`, `agentLoop`) consume it
+ * directly inside `retrySource` / `switchMap` chains. There is intentionally
+ * no imperative `execute()` Promise method — the registry was originally a
+ * dual-boundary class (imperative + reactive) and the imperative path was
+ * the only thing in the codebase bridging through `Promise.resolve().then()`
+ * to feed `fromAny`. Removing it left every consumer on a single
+ * reactive-all-the-way path with real abort propagation.
+ *
+ * For non-reactive callers (debug scripts, one-shot tests), bridge with
+ * `awaitSettled(toolRegistry.executeReactive(name, args))`.
+ *
+ * **Wave A Unit 6 refactor:** internal storage migrated from `state<Map>`
+ * (O(N) Map-copy per mutation) to `ReactiveMapBundle<string, ToolDefinition>`
+ * (O(1) mutations + version counter).
+ */
+declare class ToolRegistryGraph extends Graph {
+    readonly definitions: Node<ReadonlyMap<string, ToolDefinition>>;
+    readonly schemas: Node<readonly ToolDefinition[]>;
+    private readonly _bundle;
+    constructor(name: string, opts?: ToolRegistryOptions);
+    register(tool: ToolDefinition): void;
+    unregister(name: string): void;
+    /**
+     * Reactive execution — returns a `Node<unknown>` that emits the handler
+     * result. The returned node is a `producer` that:
+     *
+     * 1. Mints a per-call `AbortController` whose `signal` is threaded into
+     *    the handler call AND into `fromAny` (so a `fromPromise` /
+     *    `fromAsyncIter` inner abandons cleanly when the consumer
+     *    unsubscribes).
+     * 2. Runs `tool.handler(args, {signal})` inside a try/catch — a
+     *    synchronous throw surfaces as `[[ERROR, err]]` downstream instead
+     *    of escaping the producer.
+     * 3. Forwards every message from the inner `fromAny` chain to the
+     *    producer's outputs.
+     * 4. On teardown (subscriber count drops to zero, e.g. `switchMap`
+     *    supersede) calls `ac.abort()` and unsubscribes the inner.
+     *    Signal-aware handlers (e.g. `fetch(url, {signal})`) actually stop.
+     *
+     * Each call mints a fresh node tied to a fresh `handler(args, ...)`
+     * invocation — call `executeReactive` again for repeated invocations.
+     *
+     * @throws `Error` synchronously when `name` is not registered (no node is
+     *   constructed — the caller gets a pre-wiring failure rather than a
+     *   silent ERROR wave on an empty graph).
+     */
+    executeReactive(name: string, args: Record<string, unknown>): Node<unknown>;
+    getDefinition(name: string): ToolDefinition | undefined;
+}
+declare function toolRegistry(name: string, opts?: ToolRegistryOptions): ToolRegistryGraph;
+
+/**
+ * `toolExecution` — reactive per-tool-call executor with retry + rescue.
+ *
+ * Lifted from the inlined `executeToolReactively` helper inside `agent-loop.ts`
+ * so it can be consumed standalone by any caller with a reactive `toolCalls`
+ * batch — not just `agentLoop`. The shape is: one input `Node<readonly
+ * ToolCall[]>` + a `ToolRegistryGraph` → one output `Node<readonly
+ * ToolResult[]>`. Each call maps to a per-call `retrySource(executeReactive)`
+ * → optional `rescue` chain that emits the handler result on success, or a
+ * JSON-wrapped `{ error }` payload on terminal failure so the LLM can see the
+ * error as tool output and decide whether to try again via another tool call.
+ *
+ * **Cancellation.** `executeReactive` mints a per-call `AbortController` and
+ * threads its signal into the handler call. When `switchMap` supersedes the
+ * inner (a fresh `toolCalls` batch arrives) or the outer graph tears down,
+ * the per-call node unsubscribes and `ac.abort()` fires. Signal-aware
+ * handlers (`fetch(url, {signal})`, child-process kill, DB cancel) actually
+ * stop in-flight work; handlers that ignore the signal still complete to
+ * their original termination, but their result is discarded.
+ *
+ * @module
+ */
+
+/** A single tool execution outcome: `{id, content}` where content is a JSON string. */
+interface ToolResult {
+    readonly id: string;
+    readonly content: string;
+}
+type ToolExecutionOptions = {
+    /**
+     * Reactive tool-call batch. Each non-empty emission triggers a fresh
+     * per-call execution fan-out; superseding emissions cancel the prior fan.
+     */
+    toolCalls: Node<readonly ToolCall[]>;
+    /** Registry that resolves tool name → handler. */
+    tools: ToolRegistryGraph;
+    /**
+     * Retry count per individual tool call. `retrySource({count: N})` retries
+     * up to N times on error (N retries = N+1 total attempts). Default: 1.
+     */
+    retryCount?: number;
+    /**
+     * How to surface a terminal error after retries are exhausted.
+     * - `"rescue"` (default): emit `{id, content: JSON.stringify({error})}`
+     *   so the LLM sees the failure as structured tool output and can decide
+     *   how to react. Sibling calls in the same batch continue to their own
+     *   completion; one call's failure does not affect the others.
+     * - `"propagate"`: let the ERROR propagate downstream. **Blast radius:**
+     *   the per-batch `derived` join auto-errors when any per-call node
+     *   terminates with ERROR, so one call's failure discards every sibling's
+     *   DATA (even ones that already settled with a valid ToolResult). Use
+     *   `"propagate"` only when a single tool failure should be fatal for the
+     *   whole batch; prefer `"rescue"` when you want the LLM to see partial
+     *   results plus per-call error markers.
+     */
+    onError?: "rescue" | "propagate";
+};
+/**
+ * Reactive executor for a batch of LLM tool calls.
+ *
+ * Each DATA emission on `toolCalls` dispatches a fresh per-call fan-out: for
+ * every call in the batch, construct a `retrySource(fromAny(tools.execute(
+ * name, args)))` node, optionally `rescue` it into a JSON error shape, and
+ * join the results via a `derived` whose first-run gate waits for every call
+ * to settle before emitting the batch. Empty batches (`calls.length === 0`)
+ * are a caller-side invariant violation (the upstream gate should emit
+ * RESOLVED for empty batches, not DATA) and trigger a loud error — callers
+ * that want to accept empty batches should upstream-filter them first.
+ *
+ * Reference-equality + content-equality dedup is applied to the output batch
+ * so duplicate re-emissions from a completing retrySource don't propagate.
+ *
+ * @param opts - `{ toolCalls, tools, retryCount?, onError? }`.
+ * @returns `Node<readonly ToolResult[]>` — one ToolResult per input ToolCall.
+ */
+declare function toolExecution(opts: ToolExecutionOptions): Node<readonly ToolResult[]>;
+
+type RetrievalQuery = {
+    readonly text?: string;
+    readonly vector?: readonly number[];
+    readonly entityIds?: readonly string[];
+    /**
+     * Optional hierarchical context breadcrumb — e.g.
+     * `["projects", "auth", "tokens"]`. When both the query and a candidate
+     * entry supply a `context`, the retrieval pipeline applies a score boost
+     * proportional to `contextWeight` for entries whose context overlaps
+     * (shared prefix). Entries or queries without `context` are scored
+     * flatly (backward-compatible).
+     */
+    readonly context?: readonly string[];
+};
+type RetrievalPipelineOptions<TMem> = {
+    /** Max candidates from vector search (default 20). */
+    topK?: number;
+    /** KG expansion depth in hops (default 1). */
+    graphDepth?: number;
+    /** Token budget for final packing (default 2000). */
+    budget?: number;
+    /** Cost function for budget packing. */
+    cost: (mem: TMem) => number;
+    /** Score function for ranking. */
+    score: (mem: TMem, context: unknown) => number;
+    /**
+     * Optional accessor: extracts the hierarchical context breadcrumb from a
+     * memory entry. Used with {@link RetrievalQuery.context} and
+     * `contextWeight` to boost entries whose context overlaps the query.
+     * Entries that don't expose context stay at flat behavior.
+     */
+    contextOf?: (mem: TMem) => readonly string[] | undefined;
+    /**
+     * Boost multiplier applied to a candidate's score when its `context`
+     * shares a prefix with the query's `context`. Score is multiplied by
+     * `(1 + contextWeight * sharedDepth / queryDepth)`. Default: 0 (no
+     * context boost).
+     */
+    contextWeight?: number;
+};
+/** A single entry in the retrieval result, with causal trace metadata. */
+type RetrievalEntry<TMem> = {
+    readonly key: string;
+    readonly value: TMem;
+    readonly score: number;
+    readonly sources: ReadonlyArray<"vector" | "graph" | "store">;
+    /**
+     * Hierarchical context breadcrumb for this entry, when
+     * `RetrievalPipelineOptions.contextOf` is supplied and returns a value.
+     */
+    readonly context?: readonly string[];
+};
+/** Causal trace for a retrieval run. */
+type RetrievalTrace<TMem> = {
+    readonly vectorCandidates: ReadonlyArray<VectorSearchResult<TMem>>;
+    readonly graphExpanded: ReadonlyArray<string>;
+    readonly ranked: ReadonlyArray<RetrievalEntry<TMem>>;
+    readonly packed: ReadonlyArray<RetrievalEntry<TMem>>;
+};
+
+type MemoryTier = "permanent" | "active" | "archived";
+type MemoryTiersOptions<TMem> = {
+    /** Exponential decay rate per second for active tier.
+     *  Default: 7-day half-life ≈ ln(2)/(7×86400) ≈ 0.00000114. */
+    decayRate?: number;
+    /** Max entries in the active tier before archiving lowest-scored (default 1000). */
+    maxActive?: number;
+    /** Score threshold below which active entries get archived (default 0.1). */
+    archiveThreshold?: number;
+    /** Predicate: true → entry belongs in permanent tier (default: never). */
+    permanentFilter?: (key: string, mem: TMem) => boolean;
+    /** Storage tier for the archive. Omit to disable archiving. */
+    archiveTier?: SnapshotStorageTier<GraphCheckpointRecord>;
+    /** Options forwarded to `graph.attachSnapshotStorage` for the archive tier. */
+    archiveStorageOptions?: GraphAttachStorageOptions;
+};
+
+type MemoryTiersBundle<TMem> = {
+    /**
+     * Permanent tier: never evicted. Backed by a `collection({ranked:false})`
+     * Graph (Tier 2.3 — was previously a `LightCollectionBundle`; the no-Graph
+     * bundle shape was folded into the unified `CollectionGraph`).
+     */
+    readonly permanent: CollectionGraph<TMem>;
+    /** Active entries node (reactive, holds ReadonlyMap). */
+    readonly activeEntries: Node<unknown>;
+    /** Archive storage handle (null if no tier configured). */
+    readonly archiveHandle: StorageHandle | null;
+    /** Classify a key into its current tier. */
+    tierOf: (key: string) => MemoryTier;
+    /** Move a key to the permanent tier. */
+    markPermanent: (key: string, value: TMem) => void;
+};
+
+interface MemoryWithVectorsOptions<TMem> {
+    /** Optional Graph identity — passed through to the underlying `Graph` ctor. */
+    graph?: GraphOptions;
+    /** Subgraph name. Default: `"memory-vectors"`. */
+    name?: string;
+    /** The substrate distill store to index. */
+    store: DistillBundle<TMem>;
+    /** Embedding dimension. Must match the `embedFn` output length. */
+    dimension: number;
+    /** Extract an embedding vector for a memory entry. */
+    embedFn: (mem: TMem) => readonly number[] | undefined;
+}
+/**
+ * Graph subclass that attaches a vector index to a `DistillBundle`. The inner
+ * `VectorIndexGraph` is mounted at `"vectorIndex"`; an internal effect
+ * subscribes to the substrate store and re-indexes on every change.
+ *
+ * Mirrors `AuditTrailGraph` / `PolicyGateGraph` shape — fully self-contained,
+ * teardown via the Graph's `destroy()` cascade.
+ */
+declare class MemoryWithVectorsGraph<TMem> extends Graph {
+    readonly vectors: VectorIndexGraph<TMem>;
+    constructor(opts: MemoryWithVectorsOptions<TMem>);
+}
+/**
+ * Attach a vector index to a `DistillBundle`. Indexes every entry in the
+ * store as it changes. Returns the `MemoryWithVectorsGraph` whose `vectors`
+ * field exposes the underlying `VectorIndexGraph`.
+ *
+ * Teardown is handled by `Graph.destroy()` — typically inherited via
+ * mounting the result on a parent graph (see `agentMemory`).
+ */
+declare function memoryWithVectors<TMem>(opts: MemoryWithVectorsOptions<TMem>): MemoryWithVectorsGraph<TMem>;
+interface MemoryWithKGOptions<TMem> {
+    /** Optional Graph identity. */
+    graph?: GraphOptions;
+    /** Subgraph name. Default: `"memory-kg"`. */
+    name?: string;
+    /** The substrate distill store to index. */
+    store: DistillBundle<TMem>;
+    /** Inner KnowledgeGraph name. Default: `${name}-kg`. */
+    kgName?: string;
+    /**
+     * Mount path within this Graph for the KnowledgeGraph. Default:
+     * `"knowledge-kg"` (B5c — symmetric with the outer `knowledge` mount so
+     * describe paths render `knowledge::knowledge-kg::*`).
+     */
+    mountPath?: string;
+    /**
+     * Extract entities + relations for a memory entry. Omit to mount an empty
+     * KG without an indexer effect — caller upserts entities / relations
+     * directly on the `kg` field.
+     */
+    entityFn?: (key: string, mem: TMem) => {
+        entities?: Array<{
+            id: string;
+            value: unknown;
+        }>;
+        relations?: Array<{
+            from: string;
+            to: string;
+            relation: string;
+            weight?: number;
+        }>;
+    } | undefined;
+}
+/**
+ * Graph subclass that attaches a knowledge graph alongside a `DistillBundle`.
+ * Mounts the inner `KnowledgeGraph` at `mountPath` (default `"knowledge-kg"`); when
+ * `entityFn` is provided, an indexer effect populates entities/relations on
+ * every store change.
+ */
+declare class MemoryWithKGGraph<TMem> extends Graph {
+    readonly kg: KnowledgeGraph<unknown, string>;
+    constructor(opts: MemoryWithKGOptions<TMem>);
+}
+/**
+ * Attach a knowledge graph alongside a `DistillBundle`. Returns the
+ * `MemoryWithKGGraph` whose `kg` field exposes the inner `KnowledgeGraph`.
+ */
+declare function memoryWithKG<TMem>(opts: MemoryWithKGOptions<TMem>): MemoryWithKGGraph<TMem>;
+/**
+ * Full options for {@link memoryWithTiers} (Tier 4.1 B + 4.3 B refactor,
+ * 2026-04-29). Combines tier-policy options with the distill-side options
+ * needed to construct the underlying store — `memoryWithTiers` is the
+ * **construction site** for the distill bundle so it can wire
+ * `reactiveMap.retention` into the store at construction (eliminating the
+ * §7 feedback cycle the previous `tierClassifier` effect carried).
+ */
+type MemoryWithTiersOptions<TRaw, TMem> = MemoryTiersOptions<TMem> & Omit<DistillOptions<TMem>, "mapOptions" | "score" | "context"> & {
+    /** Optional Graph identity. */
+    graph?: GraphOptions;
+    /** Subgraph name. Default: `"memory-tiers"`. */
+    name?: string;
+    /** Raw source feeding distill. */
+    source: NodeInput<TRaw>;
+    /** Reactive extraction wiring (same shape as `distill`). */
+    extractFn: (raw: Node<TRaw>, existing: Node<ReadonlyMap<string, TMem>>) => NodeInput<Extraction<TMem>>;
+    /** Score function — same signature as `agentMemory.score`. */
+    score: (mem: TMem, context: unknown) => number;
+    /** Optional reactive context node (passed to `score`). */
+    context?: NodeInput<unknown>;
+};
+/**
+ * Graph subclass attaching 3-tier storage (active / archived / permanent) to
+ * a fresh distill store, wiring `reactiveMap.retention` at construction so
+ * archival happens synchronously inside the substrate's mutation pipeline
+ * (no §7 feedback cycle). Promotes `permanentKeys` and `entryCreatedAtNs` to
+ * reactive maps registered on this graph (Tier 4.3 B — Unit 7 Q3) so
+ * `describe()` / `explain()` can walk to "why was X archived?".
+ *
+ * Public-face fields:
+ * - `store` — the distill bundle (construction site, exposed for downstream
+ *   composers).
+ * - `tiers` — tier classification + permanent promotion handles.
+ * - `compact`, `size` — alias for `store.compact` / `store.size` (registered
+ *   under their canonical names so `describe()` keys match `agentMemory`'s
+ *   pre-migration layout).
+ */
+declare class MemoryWithTiersGraph<TRaw, TMem> extends Graph {
+    readonly store: DistillBundle<TMem>;
+    readonly tiers: MemoryTiersBundle<TMem>;
+    readonly compact: Node<Array<{
+        key: string;
+        value: TMem;
+        score: number;
+    }>>;
+    readonly size: Node<number>;
+    readonly permanent: ReturnType<typeof collection<TMem>>;
+    readonly permanentKeys: ReactiveMapBundle<string, true>;
+    readonly entryCreatedAtNs: ReactiveMapBundle<string, number>;
+    constructor(opts: MemoryWithTiersOptions<TRaw, TMem>);
+}
+/**
+ * Attach 3-tier storage (active / archived / permanent) over a fresh distill
+ * store. Returns a `MemoryWithTiersGraph` whose `store` and `tiers` fields
+ * mirror the previous bundle shape.
+ *
+ * **API shape** (Class B audit, 2026-04-30 — breaking change vs.
+ * pre-migration): the factory takes a single opts bag including `source`
+ * and `extractFn`. The bundle is exposed as `result.store` for downstream
+ * composers (vectors / KG / retrieval).
+ *
+ * - `permanentFilter`-matching entries score `Infinity` in retention →
+ *   never archived. Independent permanent-promotion effect upserts them
+ *   into the `permanent` collection.
+ * - Below-threshold entries → retention archives synchronously.
+ * - Over-`maxActive` entries → retention's `maxSize` evicts lowest-scored.
+ */
+declare function memoryWithTiers<TRaw, TMem>(opts: MemoryWithTiersOptions<TRaw, TMem>): MemoryWithTiersGraph<TRaw, TMem>;
+interface MemoryRetrievalOptions<TMem> {
+    /** Optional Graph identity. */
+    graph?: GraphOptions;
+    /** Subgraph name. Default: `"memory-retrieval"`. */
+    name?: string;
+    /** The substrate distill store. */
+    store: DistillBundle<TMem>;
+    /** Optional vector index for similarity search. */
+    vectors?: VectorIndexGraph<TMem> | null;
+    /** Optional knowledge graph for entity-relation expansion. */
+    kg?: KnowledgeGraph<unknown, string> | null;
+    /** Score function (same shape as `agentMemory.score`). */
+    score: (mem: TMem, context: unknown) => number;
+    /** Cost function for budget packing. */
+    cost: (mem: TMem) => number;
+    /** Token / cost budget. Default 2000. */
+    budget?: number;
+    /** Top-K vector candidates. Default 20. */
+    topK?: number;
+    /** KG expansion depth in hops. Default 1. */
+    graphDepth?: number;
+    /** Hierarchical-context boost weight. Default 0. */
+    contextWeight?: number;
+    /** Hierarchical-context accessor for entries. */
+    contextOf?: (mem: TMem) => readonly string[] | undefined;
+    /** Optional reactive context node (passed to `score`). */
+    context?: NodeInput<unknown>;
+}
+/**
+ * Graph subclass that builds the retrieval pipeline (vector + KG + budget
+ * packing) over a `DistillBundle` and optional vectors / kg substrates.
+ *
+ * **C1 rework (2026-04-30):** retrieval is reactive-only. Each
+ * `retrieveReactive(input)` call constructs its own per-input subgraph
+ * mounted at `retrieve_${id}` with named nodes `context`, `result`, and
+ * `projection`. Subgraphs register their own scoped disposers so teardown
+ * is local to the per-call mount.
+ *
+ * **QA F-9 (2026-04-30):** the shared `retrieval` / `retrievalTrace`
+ * state-node mirrors are dropped — they were last-writer-wins under
+ * concurrent `retrieveReactive(...)` calls. Consumers must subscribe to
+ * the per-call `projection` node directly. One-shot consumers use
+ * `awaitSettled(retrieveReactive(input))`.
+ *
+ * **QA F-6 (2026-04-30):** the per-call `result` derived declares
+ * `vectors.entries` / `kg.adjacencyOut` / `kg.adjacencyIn` as deps when
+ * configured, so a vector upsert / KG mutation re-runs retrieval even
+ * when the query / context / store-snapshot are unchanged. Resolves the
+ * §28 closure-mirror gap where these `.cache` reads were undeclared.
+ */
+declare class MemoryRetrievalGraph<TMem> extends Graph {
+    private readonly _store;
+    private readonly _vectors;
+    private readonly _kg;
+    private readonly _opts;
+    private readonly _contextNode;
+    private readonly _topK;
+    private readonly _graphDepth;
+    private readonly _budget;
+    private readonly _contextWeight;
+    private _retrieveSeq;
+    constructor(opts: MemoryRetrievalOptions<TMem>);
+    private _runRetrieval;
+    /**
+     * Reactive consumer API — chain into the graph.
+     *
+     * Each call constructs its own per-input subgraph mounted at
+     * `retrieve_${id}` (auto-incrementing within this MemoryRetrievalGraph
+     * instance) with named nodes:
+     *
+     * - `context` — `fromAny(queryInput)` projection (so the input node is
+     *   visible to `describe()` even when callers pass a raw value).
+     * - `result` — pure derived `{ packed, trace }`.
+     * - `projection` — the packed-array node returned to the caller.
+     *
+     * `result` declares the substrate's `store.entries`, the optional
+     * `context` Node, the local `context` projection, and (when configured)
+     * `vectors.entries` / `kg.adjacencyOut` / `kg.adjacencyIn` as deps —
+     * so vector upserts and KG mutations re-trigger retrieval even when
+     * the input is unchanged.
+     *
+     * **Lifecycle contract (DS-13.5.C, 2026-05-01).** The per-call subgraph
+     * stays mounted while the returned `projection` has at least one
+     * subscriber. When the last subscriber unsubscribes, projection's
+     * `deactivate` cleanup hook fires (canonical "last unsubscribe" signal
+     * via the existing `NodeFnCleanup.onDeactivation` protocol), which calls
+     * `parent.remove(retrieve_${id})` and tears the per-call topology
+     * down via TEARDOWN cascade (post-DS-13.5.A Q16, COMPLETE auto-precedes).
+     *
+     * **Single-shot lifecycle.** This auto-unmount is keyed to the FIRST
+     * last-unsubscribe event — projection is non-resubscribable from the
+     * caller's perspective. Callers who need to subscribe / unsubscribe /
+     * re-subscribe should hold a long-lived subscription externally (e.g.
+     * `keepalive(projection)`) or call `retrieveReactive(...)` again to
+     * mount a fresh per-call subgraph.
+     *
+     * **Caller obligation.** Either subscribe to `projection` (and
+     * eventually unsubscribe to trigger cleanup) OR drop the returned
+     * reference without subscribing — in the no-subscribe case the
+     * subgraph is dormant (no compute fires) and a parent `destroy()`
+     * cascade reclaims it. Holding `projection` without subscribing AND
+     * without ever destroying the parent is the leak case the JSDoc above
+     * the C1 rework covers.
+     *
+     * One-shot callers use `awaitSettled(retrieveReactive(input))`.
+     */
+    retrieveReactive(queryInput: NodeInput<RetrievalQuery | null>): Node<ReadonlyArray<RetrievalEntry<TMem>>>;
+}
+/**
+ * Build the retrieval pipeline (vector + KG + budget packing) over a
+ * `DistillBundle` and optional `vectors` / `kg` substrates. Returns a
+ * `MemoryRetrievalGraph` exposing `retrieval` / `retrievalTrace` reactive
+ * state and the `retrieveReactive(input)` consumer method.
+ */
+declare function memoryRetrieval<TMem>(opts: MemoryRetrievalOptions<TMem>): MemoryRetrievalGraph<TMem>;
+
+export { ChatStreamGraph as C, MemoryRetrievalGraph as M, type RetrievalEntry as R, type ToolExecutionOptions as T, type ChatStreamOptions as a, type MemoryRetrievalOptions as b, type MemoryTier as c, type MemoryTiersBundle as d, type MemoryTiersOptions as e, MemoryWithKGGraph as f, type MemoryWithKGOptions as g, MemoryWithTiersGraph as h, type MemoryWithTiersOptions as i, MemoryWithVectorsGraph as j, type MemoryWithVectorsOptions as k, type RetrievalPipelineOptions as l, type RetrievalQuery as m, type RetrievalTrace as n, ToolRegistryGraph as o, type ToolRegistryOptions as p, type ToolResult as q, chatStream as r, memoryRetrieval as s, memoryWithKG as t, memoryWithTiers as u, memoryWithVectors as v, toolExecution as w, toolRegistry as x };

package/dist/observable-BXQoW1P-.d.cts

@@ -0,0 +1,36 @@
+import { Node, Messages } from '@graphrefly/pure-ts/core';
+import { Observable } from 'rxjs';
+
+/** Options for {@link toObservable}. */
+type ToObservableOptions = {
+    /**
+     * When `true`, emit raw `Messages` batches instead of extracted `DATA` values.
+     * Terminal batches are still emitted as the final `next()` before the
+     * Observable signal (error/complete).
+     */
+    raw?: boolean;
+};
+/**
+ * Bridge a `Node<T>` to an RxJS `Observable`.
+ *
+ * Default mode emits the node's value on each `DATA` message. Maps `ERROR` to
+ * `subscriber.error()` and `COMPLETE` to `subscriber.complete()`.
+ * Protocol-internal signals (DIRTY, RESOLVED, PAUSE, etc.) are skipped.
+ *
+ * With `{ raw: true }`, emits full `[[Type, Data?], ...]` message batches.
+ * The Observable terminates on ERROR or COMPLETE (the terminal batch is still
+ * emitted as the final `next()` before the Observable signal).
+ *
+ * For graph-level observation, use `toObservable(graph.resolve(path))` or
+ * subscribe to `graph.observe()` directly.
+ *
+ * Unsubscribing the Observable unsubscribes the node.
+ */
+declare function toObservable<T>(node: Node<T>, options?: ToObservableOptions & {
+    raw?: false;
+}): Observable<T>;
+declare function toObservable<T>(node: Node<T>, options: ToObservableOptions & {
+    raw: true;
+}): Observable<Messages>;
+
+export { type ToObservableOptions as T, toObservable as t };

package/dist/observable-BXQoW1P-.d.ts

@@ -0,0 +1,36 @@
+import { Node, Messages } from '@graphrefly/pure-ts/core';
+import { Observable } from 'rxjs';
+
+/** Options for {@link toObservable}. */
+type ToObservableOptions = {
+    /**
+     * When `true`, emit raw `Messages` batches instead of extracted `DATA` values.
+     * Terminal batches are still emitted as the final `next()` before the
+     * Observable signal (error/complete).
+     */
+    raw?: boolean;
+};
+/**
+ * Bridge a `Node<T>` to an RxJS `Observable`.
+ *
+ * Default mode emits the node's value on each `DATA` message. Maps `ERROR` to
+ * `subscriber.error()` and `COMPLETE` to `subscriber.complete()`.
+ * Protocol-internal signals (DIRTY, RESOLVED, PAUSE, etc.) are skipped.
+ *
+ * With `{ raw: true }`, emits full `[[Type, Data?], ...]` message batches.
+ * The Observable terminates on ERROR or COMPLETE (the terminal batch is still
+ * emitted as the final `next()` before the Observable signal).
+ *
+ * For graph-level observation, use `toObservable(graph.resolve(path))` or
+ * subscribe to `graph.observe()` directly.
+ *
+ * Unsubscribing the Observable unsubscribes the node.
+ */
+declare function toObservable<T>(node: Node<T>, options?: ToObservableOptions & {
+    raw?: false;
+}): Observable<T>;
+declare function toObservable<T>(node: Node<T>, options: ToObservableOptions & {
+    raw: true;
+}): Observable<Messages>;
+
+export { type ToObservableOptions as T, toObservable as t };