@graphrefly/graphrefly 0.45.0 → 0.46.0

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

@@ -0,0 +1,1777 @@
+import { i as TokenUsage, L as LLMAdapter, g as PricingFn, a as ChatMessage, b as LLMInvokeOptions, k as ToolDefinition, c as LLMResponse, S as StreamDelta } from '../../types-BB5Lw-pB.cjs';
+export { C as CapabilitiesRegistry, M as ModelCapabilities, d as ModelFeatures, e as ModelLimits, f as ModelPricing, P as PriceBreakdown, h as PricingRegistry, R as Rate, T as TieredRate, j as ToolCall, l as composePricing, m as computePrice, n as createCapabilitiesRegistry, o as createPricingRegistry, p as pricingFor, r as registryPricing, z as zeroPrice } from '../../types-BB5Lw-pB.cjs';
+import { C as CascadeExhaustionReport } from '../../cascading-baGkiihI.cjs';
+export { A as AdapterProvider, a as AdapterTier, b as AllTiersExhaustedError, c as CascadingLlmAdapterOptions, d as CreateAdapterOptions, O as OpenAICompatAdapterOptions, e as OpenAICompatPreset, f as OpenAISdkLike, g as cascadingLlmAdapter, h as createAdapter, o as openAICompatAdapter, t as tier } from '../../cascading-baGkiihI.cjs';
+import { Node, Actor } from '@graphrefly/pure-ts/core';
+import { ReactiveLogBundle, NodeInput } from '@graphrefly/pure-ts/extra';
+import { a as CircuitBreakerOptions, C as CircuitBreaker } from '../../breaker-ugSdq54q.cjs';
+export { b as CircuitOpenError } from '../../breaker-ugSdq54q.cjs';
+import { R as RateLimitSignal, A as AdaptiveRateLimiterBundle } from '../../adaptive-rate-limiter-Dch_xYIi.cjs';
+import { W as WithReplayCacheOptions } from '../../fallback-Bx46zqky.cjs';
+export { F as FallbackAdapterOptions, a as FallbackFixture, b as FallbackMissError, c as FallbackMissPolicy, R as ReplayCacheKeyContext, d as ReplayCacheMissError, e as ReplayCacheMode, f as fallbackAdapter, w as withReplayCache } from '../../fallback-Bx46zqky.cjs';
+import { E as Extraction } from '../../distill-De6Rnn15.cjs';
+import { Graph } from '@graphrefly/pure-ts/graph';
+import { TopicGraph } from '../messaging/index.cjs';
+import { G as GateController, c as GateOptions } from '../../pipeline-graph-Ce47CB6Y.cjs';
+export { C as ChatStreamGraph, a as ChatStreamOptions, M as MemoryRetrievalGraph, b as MemoryRetrievalOptions, c as MemoryTier, d as MemoryTiersBundle, e as MemoryTiersOptions, f as MemoryWithKGGraph, g as MemoryWithKGOptions, h as MemoryWithTiersGraph, i as MemoryWithTiersOptions, j as MemoryWithVectorsGraph, k as MemoryWithVectorsOptions, R as RetrievalEntry, l as RetrievalPipelineOptions, m as RetrievalQuery, n as RetrievalTrace, T as ToolExecutionOptions, o as ToolRegistryGraph, p as ToolRegistryOptions, q as ToolResult, r as chatStream, s as memoryRetrieval, t as memoryWithKG, u as memoryWithTiers, v as memoryWithVectors, w as toolExecution, x as toolRegistry } from '../../memory-composers-BryDrRBX.cjs';
+import { GraphSpecCatalog } from '../graphspec/index.cjs';
+export { DEFAULT_DECAY_RATE } from '../../base/utils/index.cjs';
+import '../../_internal-B23BagFd.cjs';
+import '../../backoff-Bnb9OoPh.cjs';
+import '../../base/mutation/index.cjs';
+import '../memory/index.cjs';
+
+/**
+ * Observable adapter wrapper — the "inverted statistics" surface.
+ *
+ * The library emits structured facts (token counts, latency, timestamps)
+ * as reactive nodes. Users compose interpretation (pricing, dashboards,
+ * telemetry, budget breakers) as derived layers on top.
+ */
+
+/** One call's structured statistics — emitted after `invoke()` / `stream()` settles. */
+interface CallStatsEvent {
+    /** `monotonicNs()` at call completion — use for event ordering. */
+    readonly timestamp: number;
+    /** `wallClockNs()` at call start — use for human-readable attribution. */
+    readonly wallClock: number;
+    readonly provider: string;
+    readonly model: string;
+    readonly tier?: string;
+    readonly usage: TokenUsage;
+    readonly latencyMs: number;
+    /** `"invoke"` or `"stream"`. */
+    readonly method: "invoke" | "stream";
+    /** Populated when the call errored — usage may be zero or partial. */
+    readonly error?: {
+        readonly type: string;
+        readonly message: string;
+    };
+}
+interface AdapterStats {
+    /**
+     * Reactive node for the most-recent call event. Emits `null` initially
+     * (no calls yet); emits a {@link CallStatsEvent} after each call. Subscribe
+     * and filter `!= null` if you want a `Node<CallStatsEvent>`.
+     */
+    readonly lastCall: Node<CallStatsEvent | null>;
+    /** Full event log (bounded by `opts.logMax`, default 1000). */
+    readonly allCalls: ReactiveLogBundle<CallStatsEvent>;
+    /** Total calls observed since last reset. */
+    readonly totalCalls: Node<number>;
+    /** Sum of every input-token class across observed calls. */
+    readonly totalInputTokens: Node<number>;
+    /** Sum of every output-token class across observed calls. */
+    readonly totalOutputTokens: Node<number>;
+    /** Reset all counters + clear the log. */
+    reset(): void;
+    /**
+     * Release the internal keepalive subscriptions on the three counter
+     * derives (`totalCalls` / `totalInputTokens` / `totalOutputTokens`) so the
+     * bundle can be GC'd when the caller discards it. Idempotent. Long-lived
+     * adapter bundles (module-level singletons) can ignore; transient bundles
+     * (per-request / per-user) should call on teardown.
+     */
+    dispose(): void;
+}
+/**
+ * Wrap any {@link LLMAdapter} with a reactive stats bundle.
+ *
+ * Implementation (Unit 10 B):
+ * - `stats.lastCall` is a `state<CallStatsEvent | null>`.
+ * - Counters (`totalCalls` / `totalInputTokens` / `totalOutputTokens`) are
+ *   **derived views** over `allCalls.entries` — self-maintaining, no manual
+ *   `.cache + 1 + emit` pattern, visible topology in `describe()`.
+ * - `stats.allCalls` is a `reactiveLog<CallStatsEvent>` — bounded, supports
+ *   `tail(n)` / `slice(start, stop)` for dashboard views.
+ * - The wrapped adapter passes DATA through via `adaptInvokeResult`, which
+ *   uses `onFirstData` internally to guard against re-subscription double-fire
+ *   and wires `.catch` for Promise-path error recording (Unit 10 A).
+ */
+declare function observableAdapter(inner: LLMAdapter, opts?: {
+    logMax?: number;
+    name?: string;
+}): {
+    adapter: LLMAdapter;
+    stats: AdapterStats;
+};
+
+/**
+ * `withBreaker` — circuit-breaker middleware for LLM adapters.
+ *
+ * Reuses the library's existing `circuitBreaker` primitive from
+ * `extra/resilience.ts`. When the breaker is open, calls throw
+ * `CircuitOpenError` instead of hitting the provider.
+ */
+
+interface WithBreakerOptions extends CircuitBreakerOptions {
+    /**
+     * Optional external breaker — pass a shared instance to wire the same
+     * breaker across multiple adapters (e.g. all tiers of a `cascadingLlmAdapter`).
+     */
+    breaker?: CircuitBreaker;
+}
+declare function withLLMBreaker(inner: LLMAdapter, opts?: WithBreakerOptions): {
+    adapter: LLMAdapter;
+    breaker: CircuitBreaker;
+};
+
+/**
+ * `withBudgetGate` — cap an adapter by calls / tokens / USD.
+ *
+ * Totals are an O(1)-per-event running accumulator (a `state<BudgetTotals>`
+ * updated imperatively inside `record()`), not a derived reduce over the
+ * full log — avoids the quadratic cost at sustained traffic while preserving
+ * the reactive surface. The full log is still exposed via the bundle for
+ * dashboards / auditors.
+ *
+ * Budgets are enforced imperatively at `invoke()` / `stream()` entry — the
+ * running totals + `isOpen.cache` are read; if closed, the call rejects /
+ * throws `BudgetExhaustedError` without hitting the wrapped adapter. On
+ * success, the call's usage is appended to the log AND debits the running
+ * totals in a single synchronous update.
+ *
+ * Wave A Unit 11 Q4: rejected-Promise path now wires `.catch` (via
+ * `adaptInvokeResult.onError`) so failed invoke calls record a CallStatsEvent
+ * with `error` populated. Prior code silently dropped rejection from the
+ * `totals` / `log` surface.
+ */
+
+declare class BudgetExhaustedError extends Error {
+    readonly which: string;
+    readonly limit: number;
+    readonly observed: number;
+    name: string;
+    constructor(which: string, limit: number, observed: number);
+}
+interface BudgetCaps {
+    calls?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    usd?: number;
+}
+interface BudgetTotals {
+    calls: number;
+    inputTokens: number;
+    outputTokens: number;
+    usd: number;
+}
+interface LLMBudgetGateBundle {
+    totals: Node<BudgetTotals>;
+    isOpen: Node<boolean>;
+    log: ReactiveLogBundle<CallStatsEvent>;
+    reset(): void;
+    /**
+     * QA D2 (Phase 13.6.B QA pass): release every long-lived
+     * subscription this gate holds — `keepalive(isOpen)`, the optional
+     * `onExhausted` subscription, and the Lock 3.C abort fan-out
+     * subscription on `isOpen`. Aborts any in-flight controllers as a
+     * defensive last gasp so callers waiting on a soon-to-be-disposed
+     * adapter don't hang.
+     *
+     * Idempotent: subsequent calls are no-ops. After `dispose()` the
+     * adapter wrapper continues to wrap `inner.invoke` / `inner.stream`
+     * but the budget machinery is best-effort: `record()` no longer
+     * emits `totals` updates, abort fan-out no longer fires. Treat the
+     * bundle as terminated once disposed; long-running apps should
+     * `dispose()` per gate instance to avoid the sub-leak documented
+     * in `docs/optimizations.md`.
+     */
+    dispose(): void;
+}
+interface WithBudgetGateOptions {
+    caps: BudgetCaps;
+    /**
+     * Optional pricing function for USD gating. If omitted, `caps.usd` is
+     * ignored (caps.calls / caps.inputTokens / caps.outputTokens still apply).
+     */
+    pricingFn?: PricingFn;
+    /**
+     * Edge-triggered: fires exactly once when the gate transitions from
+     * open to closed. Subsequent invoke/stream attempts against a closed
+     * gate do NOT re-fire `onExhausted` — use the reactive `isOpen` node
+     * if you need per-attempt notifications. Receives the cap key that
+     * triggered the transition.
+     */
+    onExhausted?: (which: keyof BudgetCaps) => void;
+    /** Name for logs / describe output. */
+    name?: string;
+    /** Max events retained in the log (default 1000). */
+    logMax?: number;
+}
+/**
+ * Wrap an adapter with budget enforcement. Returns `{adapter, budget}` so
+ * callers can subscribe to the bundle for dashboards.
+ */
+declare function withBudgetGate(inner: LLMAdapter, opts: WithBudgetGateOptions): {
+    adapter: LLMAdapter;
+    budget: LLMBudgetGateBundle;
+};
+
+/**
+ * `withDryRun` — short-circuit to a fake adapter when a flag is on.
+ *
+ * Useful for CI / preflight / cost-safety pipelines: wrap a real adapter,
+ * pass `enabled: true` (or a reactive flag) to bypass the wire call. Default
+ * shim is {@link dryRunAdapter}; callers can supply their own.
+ *
+ * **Returns `{adapter, dispose}`** — call `dispose()` to release the internal
+ * keepalive on the reactive `enabled` input. Long-lived adapter instances
+ * (module-level singletons) can ignore dispose; transient adapters (per-
+ * request or per-user) should call it on teardown to allow the source to
+ * be GC'd.
+ */
+
+interface WithDryRunOptions {
+    /**
+     * Toggle — `true` always dry-runs; `false` always passes through; a
+     * `NodeInput<boolean>` reads the current value at call time (factory-time
+     * seed pattern, live-tunable).
+     */
+    enabled: NodeInput<boolean>;
+    /** Dry-run adapter override. Default: `dryRunAdapter({ provider: inner.provider, model: inner.model })`. */
+    mock?: LLMAdapter;
+}
+interface WithDryRunBundle {
+    adapter: LLMAdapter;
+    /**
+     * Release the internal keepalive subscription on the reactive `enabled`
+     * input. Idempotent. Safe to ignore on long-lived adapters.
+     */
+    dispose(): void;
+}
+declare function withDryRun(inner: LLMAdapter, opts: WithDryRunOptions): WithDryRunBundle;
+
+/**
+ * HTTP 429 / rate-limit parser.
+ *
+ * Produces a {@link RateLimitSignal} from provider HTTP errors so adaptive
+ * rate limiters can tighten effective limits. Normalizes:
+ * - `Retry-After` (seconds or HTTP-date)
+ * - `x-ratelimit-reset` / `x-ratelimit-reset-tokens` (epoch secs or duration)
+ * - `x-ratelimit-remaining-{requests,tokens}` + `x-ratelimit-limit-*`
+ * - Anthropic `anthropic-ratelimit-*` headers
+ * - OpenAI / OpenRouter / Groq headers (same family)
+ * - Error message regex fallbacks for providers without structured headers
+ */
+
+interface HttpErrorLike {
+    status?: number;
+    headers?: Headers | Record<string, string | string[] | undefined>;
+    message?: string;
+}
+/**
+ * Extract a {@link RateLimitSignal} from a fetch-style error object, a Response,
+ * or any object exposing `.status` + `.headers` + `.message`.
+ *
+ * Returns `undefined` if no rate-limit information can be extracted.
+ */
+declare function parseRateLimitFromError(err: unknown): RateLimitSignal | undefined;
+
+/**
+ * `withRateLimiter` — adapter middleware bridging to the reactive
+ * `adaptiveRateLimiter` primitive.
+ *
+ * - Consumes live `rpm`/`tpm` caps as reactive `NodeInput<number>` so
+ *   callers can retune at runtime (e.g. from a `ModelLimits.rpm` node).
+ * - Adapts to provider 429 responses via `http429Parser` fed into the
+ *   limiter's `adaptation` signal.
+ * - `costFn` estimates token cost pre-call (e.g. char-based approximation);
+ *   the post-call actual usage is fed back via `limiter.recordUsage()`.
+ */
+
+interface WithRateLimiterOptions {
+    /** Live rpm cap (defaults to `Infinity`). */
+    rpm?: NodeInput<number>;
+    /** Live tpm cap (defaults to `Infinity`). */
+    tpm?: NodeInput<number>;
+    /**
+     * Pre-call token-cost estimate. Default: 0 (only rpm gates). Override with
+     * e.g. a char-based heuristic:
+     * `(msgs) => Math.ceil(msgs.reduce((s, m) => s + m.content.length, 0) / 4)`.
+     */
+    costFn?: (messages: readonly ChatMessage[], opts?: LLMInvokeOptions) => number;
+    /**
+     * Manual adaptation signal source. Defaults to a signal derived from
+     * provider errors via `parseRateLimitFromError` — users can supply a
+     * custom signal chain if they route errors elsewhere.
+     */
+    adaptation?: NodeInput<RateLimitSignal>;
+    burstMultiplier?: number;
+    name?: string;
+    /**
+     * Share an existing {@link AdaptiveRateLimiterBundle} across multiple
+     * adapter wraps. When provided, `withRateLimiter` reuses this bundle
+     * instead of constructing a new one — useful when the RPM/TPM cap is
+     * logically per-provider but the caller wants to harden multiple adapters
+     * (e.g. primary + fallback of the same vendor) against the shared cap.
+     *
+     * When `limiter` is set, `rpm` / `tpm` / `adaptation` / `burstMultiplier`
+     * / `name` are ignored (the supplied bundle owns those). `costFn` is still
+     * used per-wrap — each wrap supplies its own cost estimator.
+     */
+    limiter?: AdaptiveRateLimiterBundle;
+}
+/**
+ * Wrap an adapter with adaptive rate limiting. Returns `{adapter, limiter}`
+ * so callers can subscribe to limiter internals (rpmAvailable, pending, etc.)
+ * for dashboards.
+ */
+declare function withRateLimiter(inner: LLMAdapter, opts?: WithRateLimiterOptions): {
+    adapter: LLMAdapter;
+    limiter: AdaptiveRateLimiterBundle;
+};
+
+/**
+ * `withRetry` — retry `invoke()` / `stream()` on transient errors.
+ *
+ * Streaming retry is tricky: we retry only if the stream fails before
+ * yielding any tokens. Once tokens have started flowing, we surface the
+ * error to avoid replaying from scratch (which would double-bill and
+ * confuse consumers). Opt out of streaming retry via `opts.retryStreaming = false`.
+ *
+ * Uses `ResettableTimer` for backoff sleeps (spec §5.10 escape hatch, same
+ * pattern as `extra/resilience.ts`). Abort-aware — early-aborts before the
+ * first attempt and cleans up the abort listener on both the timer-fires
+ * and abort paths.
+ */
+
+interface WithRetryOptions {
+    /** Max total attempts (including the first). Default 3. */
+    attempts?: number;
+    /** Base delay in ms. Default 500. */
+    baseDelayMs?: number;
+    /** Max delay in ms. Default 10_000. */
+    maxDelayMs?: number;
+    /**
+     * Delay strategy. Default `"decorrelated"` — AWS-style `random(baseDelay,
+     * min(maxDelay, prev * 3))` which smooths retry storms and matches common
+     * SDK expectations. `"exp"` and `"linear"` produce deterministic schedules
+     * when `jitter: false`.
+     */
+    strategy?: "exp" | "linear" | "decorrelated";
+    /**
+     * Add randomized jitter. Ignored for `strategy: "decorrelated"` (which is
+     * inherently jittered). For `exp`/`linear`, symmetric jitter in `[0.5x,
+     * 1.5x]` of the nominal delay.
+     */
+    jitter?: boolean;
+    /**
+     * Predicate: should this error trigger a retry? Default retries network /
+     * 5xx / 429 / transient errors, but not 4xx (other than 429), aborts, or
+     * `BudgetExhaustedError` from upstream middleware.
+     */
+    shouldRetry?: (err: unknown, attempt: number) => boolean;
+    /** Retry streaming calls if they fail pre-first-token. Default true. */
+    retryStreaming?: boolean;
+}
+declare function withRetry(inner: LLMAdapter, opts?: WithRetryOptions): LLMAdapter;
+
+/**
+ * `resilientAdapter` — compose `withRateLimiter` + `withBudgetGate` +
+ * `withLLMBreaker` + `withLLMTimeout` + `withRetry` + fallback over an {@link LLMAdapter}.
+ *
+ * Call-path peer of {@link resilientPipeline} (which operates on a reactive
+ * `Node<T>` chain). Use `resilientPipeline` when composing graph sources; use
+ * `resilientAdapter` when wrapping an adapter so downstream users see a
+ * single hardened `invoke`/`stream` surface.
+ *
+ * Composition order (innermost to outermost, mirrors `resilientPipeline`):
+ *
+ * ```text
+ *   rateLimit → budget → breaker → timeout → retry → fallback
+ * ```
+ *
+ * Rationale:
+ * - **rateLimit innermost** — each attempt acquires a fresh slot; a retry
+ *   after a 429 waits for admission rather than bursting past the cap.
+ * - **budget next** — per-attempt gate close short-circuits retries once a
+ *   cap trips.
+ * - **breaker next** — each attempt observes circuit health; open breaker
+ *   fast-fails retries into fallback.
+ * - **timeout before retry** — each retry re-arms a fresh per-attempt
+ *   deadline. If `timeout` wrapped `retry`, a single deadline would cover
+ *   the entire retry chain — surprising for callers.
+ * - **retry before fallback** — fallback is entered only after the primary
+ *   exhausts its retry budget (or immediately fails in a way the predicate
+ *   doesn't retry).
+ *
+ * Every option is optional — omit the field and that layer is skipped. The
+ * returned bundle exposes the primary adapter plus the internal bundles
+ * (`rateLimiter`, `budget`, `breaker`) so callers can wire them into
+ * dashboards, alerts, or `graphLens`.
+ *
+ * Fallback is implemented via {@link cascadingLlmAdapter}: when `fallback`
+ * is provided, the wrapped primary adapter is placed at tier 0 and the
+ * fallback adapter at tier 1. For N-tier cascades, use `cascadingLlmAdapter`
+ * directly and wrap each tier with `resilientAdapter`.
+ *
+ * @module
+ */
+
+/** Options for {@link resilientAdapter}. Every field is optional — omit to skip that layer. */
+interface ResilientAdapterOptions {
+    /** Admission control. See {@link withRateLimiter}. */
+    rateLimit?: WithRateLimiterOptions;
+    /** Cost/cap gate. See {@link withBudgetGate}. */
+    budget?: WithBudgetGateOptions;
+    /** Circuit breaker. See {@link withBreaker}. */
+    breaker?: WithBreakerOptions;
+    /** Per-attempt deadline in milliseconds. Omit to skip the timeout wrap. */
+    timeoutMs?: number;
+    /** Retry policy on transient errors. See {@link withRetry}. */
+    retry?: WithRetryOptions;
+    /**
+     * Fallback adapter engaged when the primary (post-retry) fails. Implemented
+     * via {@link cascadingLlmAdapter} — the primary becomes tier 0, the
+     * fallback becomes tier 1. For N-tier cascades, use `cascadingLlmAdapter`
+     * directly and wrap each tier with `resilientAdapter` as needed.
+     */
+    fallback?: LLMAdapter;
+    /** Name used as the primary tier name in the fallback cascade. Default `"primary"`. */
+    name?: string;
+    /**
+     * Called when the cascade switches from one tier to the next after a
+     * failure. Only fires when `fallback` is set. Threaded directly to the
+     * inner {@link cascadingLlmAdapter}.
+     */
+    onFallback?: (from: string, to: string, error: unknown) => void;
+    /**
+     * Called when every tier in the cascade has been exhausted (all failed,
+     * skipped by filter, or skipped by breaker). Only fires when `fallback`
+     * is set. Threaded directly to the inner {@link cascadingLlmAdapter}.
+     */
+    onExhausted?: (report: CascadeExhaustionReport) => void;
+    /**
+     * Content-addressed replay cache wrapped OUTERMOST — a cache HIT short-
+     * circuits the entire stack (rate-limit / budget / breaker / retry /
+     * fallback), saving money and latency. Cache MISSes flow through the
+     * normal stack; the successful result is stored on success. See
+     * {@link withReplayCache}.
+     */
+    cache?: WithReplayCacheOptions;
+}
+/** Output bundle of {@link resilientAdapter}. */
+interface ResilientAdapterBundle {
+    /** The final hardened adapter. */
+    adapter: LLMAdapter;
+    /** Rate-limiter internals (for dashboards). Present only when `opts.rateLimit` was set. */
+    rateLimiter?: AdaptiveRateLimiterBundle;
+    /** Budget gate internals (for dashboards). Present only when `opts.budget` was set. */
+    budget?: LLMBudgetGateBundle;
+    /** Circuit breaker (for dashboards). Present only when `opts.breaker` was set. */
+    breaker?: CircuitBreaker;
+}
+/**
+ * Wrap `inner` with the standard resilience stack. See module docs for the
+ * composition order and rationale.
+ *
+ * @example
+ * ```ts
+ * const { adapter, budget, breaker } = resilientAdapter(openai, {
+ *   rateLimit: { rpm: 60, tpm: 90_000 },
+ *   budget: { caps: { usd: 5 } },
+ *   breaker: { failureThreshold: 5, resetTimeoutMs: 30_000 },
+ *   timeoutMs: 30_000,
+ *   retry: { attempts: 3 },
+ *   fallback: webllm,  // cascades to local on exhaustion
+ * });
+ *
+ * // `adapter` is drop-in for anything expecting LLMAdapter.
+ * // Subscribe to `budget.totals`, `breaker.state`, etc. for dashboards.
+ * ```
+ */
+declare function resilientAdapter(inner: LLMAdapter, opts?: ResilientAdapterOptions): ResilientAdapterBundle;
+
+/**
+ * `withLLMTimeout` — cancel `invoke()` / `stream()` after `ms` elapse.
+ *
+ * Wires a child AbortSignal so provider adapters can honor the cancellation
+ * (all shipped adapters forward `signal` through to their fetch / SDK call).
+ *
+ * Uses `ResettableTimer` rather than raw `setTimeout` — same pattern as
+ * `extra/resilience.ts` (spec §5.10 escape hatch documented on the class).
+ */
+
+declare class LLMTimeoutError extends Error {
+    readonly ms: number;
+    name: string;
+    constructor(ms: number);
+}
+declare function withLLMTimeout(inner: LLMAdapter, ms: number): LLMAdapter;
+
+/**
+ * AnthropicAdapter — default fetch-backed, optional SDK-backed.
+ *
+ * - `anthropicAdapter({ apiKey })` uses native `fetch` + SSE parsing.
+ * - `anthropicAdapter({ sdk })` delegates to a user-provided `@anthropic-ai/sdk` instance.
+ *
+ * Token usage mapping:
+ * - `input_tokens`                                → `input.regular`
+ * - `cache_read_input_tokens`                     → `input.cacheRead`
+ * - `cache_creation.ephemeral_5m_input_tokens`    → `input.cacheWrite5m`
+ * - `cache_creation.ephemeral_1h_input_tokens`    → `input.cacheWrite1h`
+ * - `cache_creation_input_tokens` (legacy)        → `input.cacheWrite5m` (default TTL)
+ * - `output_tokens`                               → `output.regular`
+ * - `server_tool_use.web_search_requests`         → `auxiliary.webSearchRequests`
+ */
+
+interface AnthropicAdapterOptions {
+    /** API key. Falls back to `process.env.ANTHROPIC_API_KEY` on Node. */
+    apiKey?: string;
+    /** Default model (overridable per-call via `LLMInvokeOptions.model`). */
+    model?: string;
+    /** Override the base URL. Default `https://api.anthropic.com`. */
+    baseURL?: string;
+    /** API version header. Default `"2023-06-01"`. */
+    anthropicVersion?: string;
+    /** Additional headers to send on every request (overridden by per-call). */
+    headers?: Record<string, string>;
+    /**
+     * User-provided SDK instance. When present, the adapter delegates to it
+     * (uses `.messages.create`) instead of native fetch.
+     * Shape matches `@anthropic-ai/sdk` `.messages` API; any object with a
+     * compatible `create`/`stream` contract works.
+     */
+    sdk?: AnthropicSdkLike;
+    /** Custom fetch (useful for tests). Default `globalThis.fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/** Minimal SDK shape we interoperate with. */
+interface AnthropicSdkLike {
+    messages: {
+        create(params: Record<string, unknown>, opts?: {
+            signal?: AbortSignal;
+        }): Promise<AnthropicMessageResponse>;
+        stream?(params: Record<string, unknown>, opts?: {
+            signal?: AbortSignal;
+        }): AsyncIterable<AnthropicStreamEvent>;
+    };
+}
+interface AnthropicMessageResponse {
+    id: string;
+    content: ReadonlyArray<{
+        type: "text";
+        text: string;
+    } | {
+        type: "tool_use";
+        id: string;
+        name: string;
+        input: Record<string, unknown>;
+    } | {
+        type: "thinking";
+        thinking: string;
+    } | {
+        type: string;
+        [key: string]: unknown;
+    }>;
+    stop_reason?: string;
+    usage: AnthropicUsage;
+    model?: string;
+}
+interface AnthropicUsage {
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
+    cache_creation?: {
+        ephemeral_5m_input_tokens?: number;
+        ephemeral_1h_input_tokens?: number;
+    };
+    server_tool_use?: {
+        web_search_requests?: number;
+    };
+}
+type AnthropicStreamEvent = {
+    type: "message_start";
+    message: {
+        usage: AnthropicUsage;
+    };
+} | {
+    type: "content_block_start";
+    index: number;
+    content_block: Record<string, unknown>;
+} | {
+    type: "content_block_delta";
+    index: number;
+    delta: Record<string, unknown>;
+} | {
+    type: "content_block_stop";
+    index: number;
+} | {
+    type: "message_delta";
+    delta: {
+        stop_reason?: string;
+        usage?: AnthropicUsage;
+    };
+} | {
+    type: "message_stop";
+} | {
+    type: string;
+    [key: string]: unknown;
+};
+declare function anthropicAdapter(opts?: AnthropicAdapterOptions): LLMAdapter;
+
+/**
+ * DryRunAdapter — zero-cost mock provider.
+ *
+ * Returns a deterministic fake response (plus a configurable hook for
+ * customization). Useful for: pipeline smoke tests, CI without API keys,
+ * local development, and as the leaf of a `cascadingLlmAdapter` when every
+ * real tier fails.
+ *
+ * The library ships a minimal implementation only — richer scenario-
+ * scripted mocks (per-stage responses, call recording) belong at the test
+ * harness layer, not in the shipped library.
+ *
+ * Uses `ResettableTimer` for simulated latency (spec §5.10 escape hatch
+ * documented on the class), and throws an `AbortError`-named Error on
+ * abort so retry/timeout middleware can classify it.
+ */
+
+interface DryRunAdapterOptions {
+    provider?: string;
+    model?: string;
+    /** Generate the fake response. Defaults to echoing the last user message. */
+    respond?: (messages: readonly ChatMessage[], opts?: LLMInvokeOptions) => string;
+    /**
+     * Generate a fake usage object. Defaults to a simple character-count
+     * heuristic (`input = sum(messages) / 4`, `output = content / 4`).
+     */
+    usage?: (messages: readonly ChatMessage[], content: string) => TokenUsage;
+    /** Simulated latency in milliseconds (applied to both invoke and stream). */
+    latencyMs?: number;
+    /** Stream chunk size in characters. Default 16. */
+    streamChunkSize?: number;
+}
+/**
+ * Create a DryRun adapter.
+ *
+ * @example
+ * ```ts
+ * const adapter = dryRunAdapter({ respond: (msgs) => "hello from dry-run" });
+ * const resp = await Promise.resolve(adapter.invoke([{ role: "user", content: "hi" }]));
+ * ```
+ */
+declare function dryRunAdapter(opts?: DryRunAdapterOptions): LLMAdapter;
+
+/**
+ * GoogleAdapter — default fetch-backed, optional SDK-backed.
+ *
+ * The SDK-backed path targets the `@google/genai` SDK shape:
+ * `client.models.generateContent({ model, contents, config })` — single
+ * param, with generation params and `abortSignal` under `config`. The
+ * legacy `@google/generative-ai` two-arg `(params, {signal})` shape is no
+ * longer accepted; pass a `GoogleGenAI` instance via `opts.sdk`.
+ *
+ * Maps Gemini `usageMetadata`:
+ * - `promptTokenCount` minus `cachedContentTokenCount` → `input.regular`
+ * - `cachedContentTokenCount`                          → `input.cacheRead`
+ * - `candidatesTokenCount`                             → `output.regular`
+ * - `thoughtsTokenCount`                               → `output.reasoning`
+ * - `toolUsePromptTokenCount`                          → `input.toolUse`
+ * - `promptTokensDetails[]`                            → `input.{image,audio,video}` per modality
+ */
+
+interface GoogleAdapterOptions {
+    /** API key. Falls back to `process.env.GOOGLE_API_KEY` / `GEMINI_API_KEY` on Node. */
+    apiKey?: string;
+    model?: string;
+    baseURL?: string;
+    /** Extra headers on every request. */
+    headers?: Record<string, string>;
+    /**
+     * Optional `@google/genai` SDK instance (e.g. `new GoogleGenAI({apiKey})`).
+     * When omitted, the adapter uses the fetch-backed path against the
+     * Generative Language REST API.
+     */
+    sdk?: GoogleSdkLike;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Duck-type matching the `@google/genai` (`GoogleGenAI`) SDK shape:
+ * single-param `generateContent({ model, contents, config })` where
+ * generation parameters and `abortSignal` live under `config`.
+ *
+ * The `@google/generative-ai` predecessor's two-arg `(params, {signal})`
+ * shape is no longer accepted.
+ */
+interface GoogleSdkLike {
+    models: {
+        generateContent(params: GoogleSdkRequestParams): Promise<GeminiResponse>;
+        generateContentStream?(params: GoogleSdkRequestParams): Promise<AsyncIterable<GeminiResponse>> | AsyncIterable<GeminiResponse>;
+    };
+}
+/** Single-param request shape consumed by `@google/genai`'s `models.generateContent`. */
+interface GoogleSdkRequestParams {
+    model: string;
+    contents: unknown;
+    config?: GoogleSdkRequestConfig;
+}
+/**
+ * Generation config under the new SDK. `abortSignal` is the cancellation
+ * channel — there is no second-arg `{signal}`.
+ */
+interface GoogleSdkRequestConfig {
+    abortSignal?: AbortSignal;
+    temperature?: number;
+    maxOutputTokens?: number;
+    systemInstruction?: unknown;
+    tools?: unknown;
+    thinkingConfig?: unknown;
+    [extra: string]: unknown;
+}
+interface GeminiResponse {
+    candidates?: ReadonlyArray<{
+        content?: {
+            role?: string;
+            parts?: ReadonlyArray<{
+                text?: string;
+                thought?: boolean;
+                functionCall?: {
+                    name: string;
+                    args: Record<string, unknown>;
+                };
+            }>;
+        };
+        finishReason?: string;
+    }>;
+    usageMetadata?: GeminiUsage;
+    modelVersion?: string;
+}
+interface GeminiUsage {
+    promptTokenCount?: number;
+    candidatesTokenCount?: number;
+    totalTokenCount?: number;
+    thoughtsTokenCount?: number;
+    cachedContentTokenCount?: number;
+    toolUsePromptTokenCount?: number;
+    promptTokensDetails?: ReadonlyArray<{
+        modality: string;
+        tokenCount: number;
+    }>;
+    candidatesTokensDetails?: ReadonlyArray<{
+        modality: string;
+        tokenCount: number;
+    }>;
+    cacheTokensDetails?: ReadonlyArray<{
+        modality: string;
+        tokenCount: number;
+    }>;
+}
+declare function googleAdapter(opts?: GoogleAdapterOptions): LLMAdapter;
+
+/**
+ * `frozenContext` — prefix-cache-friendly snapshot of upstream context.
+ *
+ * @module
+ */
+
+type FrozenContextOptions = {
+    /**
+     * Reactive signal that triggers re-materialization. Each `DATA` emission
+     * from this node re-reads the source and refreshes the frozen value.
+     * Typical shapes: `fromTimer(ms)` for periodic refresh, a stage-transition
+     * node for event-driven refresh, or a manual `state<number>` the caller
+     * increments via `setState(n + 1)`.
+     *
+     * When omitted, the frozen value is materialized exactly once (on first
+     * subscribe) and never refreshes for the lifetime of the activation —
+     * use this for session-start snapshots that must stay stable. The
+     * single-shot latch IS reset on `INVALIDATE` (graph-wide flush via
+     * `graph.signal([[INVALIDATE]])`), so callers who need an "evict and
+     * re-materialize" escape hatch get one through the standard graph
+     * lifecycle without having to wire a `refreshTrigger`.
+     */
+    refreshTrigger?: NodeInput<unknown>;
+    name?: string;
+};
+/**
+ * Freeze a reactive source into a stable snapshot that only re-materializes
+ * on explicit trigger. Built for long-running harness loops where system
+ * prompts include `agentMemory` / stage context — every reactive change to
+ * the source invalidates the LLM provider's prefix cache, so re-rendering
+ * the prompt every turn is expensive.
+ *
+ * `frozenContext(source)` reads the source once and caches the value;
+ * downstream `promptNode` compositions see a stable reference until the
+ * optional `refreshTrigger` fires.
+ *
+ * Trade-off: slightly stale context vs. prefix cache hit rate. For most
+ * harness apps, the memory snapshot at session start is "good enough" —
+ * refreshing on a coarse-grained trigger (`fromCron("*\/30min")`, stage
+ * transition) preserves 90%+ prefix cache hits while keeping context useful.
+ *
+ * @example
+ * ```ts
+ * // Freeze agent memory for the duration of a stage.
+ * const frozen = frozenContext(memory.context, {
+ *   refreshTrigger: stage,  // re-materialize on stage change
+ * });
+ * const reply = promptNode({ context: frozen, ... });
+ * ```
+ *
+ * @category patterns.ai
+ */
+declare function frozenContext<T>(source: NodeInput<T>, opts?: FrozenContextOptions): Node<T | null>;
+
+/** Options accepted by {@link promptCall}, {@link llmExtractor}, and {@link llmConsolidator}. */
+type PromptCallOptions = {
+    adapter: LLMAdapter;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    /**
+     * Optional name forwarded to the underlying `promptNode` (used as the
+     * `<name>::messages` / `<name>::response` / `<name>::output` path prefix).
+     * Defaults differ per call site so multiple `promptCall`s wired into the
+     * same graph don't collide on `prompt_node::output`.
+     */
+    name?: string;
+};
+/**
+ * Build a one-shot LLM JSON-call factory: each invocation wraps `input` in a
+ * fresh `node([], { initial: input })`, delegates to `promptNode({format: "json"})`, and
+ * returns a `NodeInput<TOut>` that the caller plugs into `distill` /
+ * `agentLoop` / any reactive composition that accepts `NodeInput`.
+ *
+ * **Per-call lifecycle.** The returned `NodeInput<TOut>` is a producer that
+ * emits exactly one `DATA` per upstream input (per Tier 1.2 Session C lock —
+ * `promptNode` guarantees one DATA per wave). When the consumer's switchMap
+ * supersedes it, the per-call `node([], { initial: input })` and the inner `prompt_node::response`
+ * tear down together.
+ *
+ * @param systemPrompt - System message sent on every call.
+ * @param buildUserContent - Per-input user-content builder (must be JSON-stringifiable).
+ * @param opts - Adapter + model/temperature/maxTokens + optional name prefix.
+ * @param defaultName - Path-prefix fallback when `opts.name` is omitted.
+ * @returns Factory `(input: TIn) => NodeInput<TOut>`.
+ *
+ * @category patterns
+ */
+declare function promptCall<TIn, TOut>(systemPrompt: string, buildUserContent: (input: TIn) => string, opts: PromptCallOptions, defaultName: string): (input: TIn) => NodeInput<TOut>;
+/** Options accepted by {@link llmExtractor} and {@link llmConsolidator}. */
+type LLMExtractorOptions = PromptCallOptions & {
+    /**
+     * Cap the dedup-hint slice of `existingKeys` passed to the LLM. Larger
+     * stores ship more keys (better dedup recall) at the cost of prompt size.
+     * Default 100. Set to `Infinity` to forward every key.
+     */
+    maxExistingKeys?: number;
+};
+/** Alias for backward compatibility. */
+type LLMConsolidatorOptions = LLMExtractorOptions;
+/**
+ * Returns an `extractFn` callback for `distill()` that invokes an LLM to
+ * extract structured memories from raw input.
+ *
+ * The system prompt should instruct the LLM to return JSON matching
+ * `Extraction<TMem>` shape: `{ upsert: [{ key, value }], remove?: [key] }`.
+ *
+ * Built on `promptNode({format: "json"})` — inherits markdown-fence stripping
+ * and content-preview parse errors. Stack `withRetry` on the adapter for
+ * transient-error tolerance (see `patterns/ai/adapters/middleware/retry.ts`).
+ */
+declare function llmExtractor<TRaw, TMem>(systemPrompt: string, opts: LLMExtractorOptions): (raw: TRaw, existing: ReadonlyMap<string, TMem>) => NodeInput<Extraction<TMem>>;
+/**
+ * Returns a `consolidateFn` callback for `distill()` that invokes an LLM to
+ * cluster and merge related memories.
+ */
+declare function llmConsolidator<TMem>(systemPrompt: string, opts: LLMConsolidatorOptions): (entries: ReadonlyMap<string, TMem>) => NodeInput<Extraction<TMem>>;
+
+/**
+ * `promptNode` — universal LLM transform as a reactive derived node.
+ *
+ * The shape: `deps → messagesNode (derived) → switchMap → response (producer) → output`.
+ * Each upstream wave is one LLM call; superseding waves cancel the in-flight
+ * call via the abort signal threaded through `nodeSignal(opts.abort)`.
+ *
+ * The producer-shape on the inner is load-bearing: it emits exactly one DATA
+ * + COMPLETE per wave, so the outer switchMap sees one DATA per wave (matches
+ * the `HarnessExecutor` contract). A `node([response], (batchData, actions, ctx) => {
+ *   const data = ...; actions.emit(parse(data[0]));
+ * }, { describeKind: "derived" })` would have its
+ * own first-run / push-on-subscribe semantics that can leak a transient null
+ * before the real response arrives — observed and reverted in an earlier
+ * attempt; see SESSION-ai-harness-module-review.md line 3654 for context.
+ * Locked as path (b) producer-based by Session C (2026-04-27); inner-node
+ * naming aligned to `prompt_node::response` per the C+D widening (2026-04-30).
+ *
+ * **Retry / replay-cache.** Stack middleware on the adapter:
+ *
+ * ```ts
+ * import { withRetry, withReplayCache } from "@graphrefly/graphrefly/patterns/ai";
+ *
+ * const adapter = withRetry(
+ *   withReplayCache(baseAdapter, { keyFn: (ctx) => ctx.messages[0].content }),
+ *   { count: 3, backoff: 200 },
+ * );
+ * const result = promptNode(adapter, [input], (q) => q);
+ * ```
+ *
+ * `promptNode` no longer ships `retries` / `cache` options — they duplicated
+ * middleware already at the adapter layer.
+ *
+ * **Cross-wave cache (COMPOSITION-GUIDE §32).** The switchMap output cache
+ * survives across new outer DATAs — `promptNode`'s cached value persists
+ * until the next wave fully resolves. Consumers that need to distinguish
+ * "fresh value for THIS session" from "stale cache from a prior session"
+ * (e.g. `agentLoop` resetting on new `run()`) must add a `node([])` mirror
+ * at their session boundary and depend on the mirror, not the `promptNode`
+ * output directly. `promptNode` itself stays primitive — it does not
+ * embed a state-mirror.
+ *
+ * @module
+ */
+
+type PromptNodeOptions = {
+    name?: string;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    /**
+     * Output format:
+     * - `"text"` (default) — emit the response content as a string.
+     * - `"json"` — `JSON.parse` the content (markdown fences stripped).
+     * - `"raw"` — emit the full {@link LLMResponse} object (subsumes the
+     *   pre-Tier-2.3 `fromLLM` shape; use this when you need `usage` /
+     *   `toolCalls` / `finishReason` alongside `content`).
+     */
+    format?: "text" | "json" | "raw";
+    /**
+     * Reactive tool definitions forwarded to the adapter. Pair with
+     * `format: "raw"` (or read `toolCalls` from a downstream parser) when
+     * tool-calling is in scope.
+     *
+     * **Reactive declared edge** (DF12, Tier 7): `tools` is a `Node` so the
+     * tools list participates in `describe()` topology and `explain()` causal
+     * chains. The tools Node is added to `messagesNode`'s declared deps —
+     * tools changes re-invoke the LLM (treated as a new call envelope).
+     * Wrap with `distinctUntilChanged` upstream if your tool selector emits
+     * noisy duplicates that would otherwise spam the adapter. See
+     * COMPOSITION-GUIDE §31 (Dynamic tool selection) for the canonical
+     * `toolSelector` pattern that produces this Node.
+     *
+     * **Activation note:** since `tools` is a real declared dep, `messagesNode`
+     * waits for the tools Node to DATA at least once before firing
+     * (push-on-subscribe SENTINEL gate). Pass a `node<ToolDefinition[]>([], { initial: [] })`
+     * if you want immediate activation with no tools, or the latest published
+     * `toolSelector.tools` Node.
+     */
+    tools?: Node<readonly ToolDefinition[]>;
+    /**
+     * Optional system prompt. Forwarded via `opts.systemPrompt` to the adapter
+     * only — never pushed as a `{role:"system"}` message (avoiding the
+     * double-send class of bug where adapters that normalize both shapes end
+     * up with two system entries).
+     */
+    systemPrompt?: string;
+    /**
+     * Optional reactive abort signal. When the node emits `true`, the in-flight
+     * `adapter.invoke()` call is cancelled via `AbortController.abort()`.
+     * Threaded through `nodeSignal(abort)` — a one-shot bridge. Useful inside
+     * agent state machines where a separate `aborted` state should cancel the
+     * current LLM call without superseding via switchMap.
+     */
+    abort?: Node<boolean>;
+    meta?: Record<string, unknown>;
+};
+/**
+ * Universal LLM transform: wraps a prompt template + model adapter into a reactive derived node.
+ * Re-invokes the LLM whenever any dep changes. Suitable for triage, QA, hypothesis, parity, etc.
+ *
+ * **Topology** (visible in `describe()`):
+ * ```
+ * <deps...>, [tools?]  → <name>::messages   (derived, meta.ai = prompt_node::messages)
+ * <name>::messages     → <name>::output     (switchMap product, meta.ai = prompt_node::output)
+ *   per-wave inner:    <name>::response     (producer, meta.ai = prompt_node::response)
+ * ```
+ * When `opts.tools` is supplied, the tools `Node` is appended to
+ * `messagesNode`'s declared deps so it appears as a real edge in `describe()`
+ * / `explain()` (DF12, Tier 7).
+ *
+ * **No-input semantics** (matches the codebase-wide SENTINEL convention):
+ * - **Initial no-input** (no real input has ever arrived) — emits nothing.
+ *   Outer cache stays `undefined`; `subscribe` consumers see no DATA event.
+ *   Use this to keep downstream gating clean: a `withLatestFrom`-paired
+ *   trigger won't fire until the LLM has actually produced something.
+ * - **Mid-flow no-input** (input dropped to nullish after at least one
+ *   real LLM call) — emits `null` as a domain "input went away" signal.
+ *   Downstream consumers can distinguish "haven't started" from "input
+ *   gone."
+ *
+ * **Retries / caching:** stack `withRetry` / `withReplayCache` middleware on the
+ * `adapter` argument — `promptNode` no longer ships its own duplicated retry /
+ * cache loops (pre-1.0 cleanup, see review session 1).
+ *
+ * @param adapter - LLM adapter (provider-agnostic). Wrap with `withRetry` /
+ *                   `withReplayCache` middleware for transient-error tolerance
+ *                   or replay caching.
+ * @param deps - Input nodes whose values feed the prompt.
+ * @param prompt - Static string or template function receiving dep values.
+ * @param opts - Optional configuration.
+ * @returns `Node` emitting LLM responses (string or parsed JSON).
+ */
+declare function promptNode(adapter: LLMAdapter, deps: readonly Node<unknown>[], prompt: string | ((...depValues: unknown[]) => string), opts: PromptNodeOptions & {
+    format: "raw";
+}): Node<LLMResponse | null>;
+declare function promptNode<T = string>(adapter: LLMAdapter, deps: readonly Node<unknown>[], prompt: string | ((...depValues: unknown[]) => string), opts?: Omit<PromptNodeOptions, "format"> & {
+    format?: "text" | "json";
+}): Node<T | null>;
+
+/**
+ * `streamingPromptNode` + `gatedStream` — streaming LLM transforms.
+ *
+ * **Wave A Unit 2 rewrite:**
+ * - `StreamChunk` retired. The live stream surface is now `deltaTopic:
+ *   TopicGraph<StreamDelta & {seq, ts}>` — every adapter delta (token,
+ *   thinking, tool-call, usage, finish) is published in order. The previous
+ *   shape retained the accumulated text per-chunk, producing O(N²) memory;
+ *   the new shape stores only per-delta payloads (O(N)).
+ * - New `accumulatedText: Node<string>` on the bundle — lazy-built via
+ *   `ctx.store` over token-type deltas. Text-only extractors (`streamExtractor`,
+ *   `keywordFlagExtractor`, `toolCallExtractor`) consume this node.
+ * - `retainedLimit?: number` option exposed for the delta topic (no default —
+ *   session scale is domain-specific per Unit 2 Q2).
+ * - Unconditional `keepalive(output)` removed — callers subscribe as needed.
+ * - System-prompt double-send fixed (matches promptNode Unit 1 fix).
+ * - `format: "json"` throws on parse error with a content-preview diagnostic
+ *   (parity with `promptNode`).
+ * - Shared body between `streamingPromptNode` and `gatedStream` extracted
+ *   into `streamingInvoke` per Unit 2 locked scope.
+ *
+ * @module
+ */
+
+/**
+ * A single delta published to the `deltaTopic`. Every adapter emission is
+ * forwarded — not just token deltas — so consumers see the full event log
+ * (thinking, tool-call-delta, usage, finish).
+ */
+type StampedDelta = StreamDelta & {
+    /** Monotonic per-stream counter starting at 0. */
+    readonly seq: number;
+    /** Wall-clock nanoseconds at publish time (spec §5.11 central timer). */
+    readonly ts: number;
+};
+type StreamingPromptNodeOptions = {
+    name?: string;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    /** Output format — `"json"` attempts JSON.parse on accumulated text. Throws on parse failure. Default: `"text"`. */
+    format?: "text" | "json";
+    systemPrompt?: string;
+    meta?: Record<string, unknown>;
+    /**
+     * Optional retention cap on the delta topic. Omit for unbounded retention
+     * (the topic grows until `dispose()`). Recommended values: `8_192` for
+     * single-shot 8K-token responses, `1_000_000` for persistent session
+     * topics, or explicit `dispose()` for worker-pool patterns.
+     */
+    retainedLimit?: number;
+};
+/**
+ * Bundle returned by {@link streamingPromptNode}.
+ */
+type StreamingPromptNodeHandle<T> = {
+    /** Final parsed result (emits once per invocation, after stream completes). */
+    output: Node<T | null>;
+    /** Live delta topic — every adapter delta in order, stamped with `seq` + `ts`. */
+    deltaTopic: TopicGraph<StampedDelta>;
+    /**
+     * Reactive accumulated-text view — lazy-built over `deltaTopic.latest`
+     * filtered on `type === "token"`. Text-only extractors compose on this.
+     * Emits the empty string before any token arrives.
+     */
+    accumulatedText: Node<string>;
+    /** Tear down the delta topic and release resources. */
+    dispose: () => void;
+};
+/**
+ * Streaming LLM transform: wraps a prompt template + adapter into a reactive
+ * streaming pipeline. Re-invokes the LLM whenever any dep changes; the
+ * previous in-flight stream is canceled automatically via `switchMap`.
+ *
+ * Every adapter delta is published to `deltaTopic` stamped with `seq` + `ts`.
+ * Text consumers subscribe to `accumulatedText` (auto-maintained). Delta-
+ * specific consumers (`costMeterExtractor` on `usage` deltas) subscribe to
+ * `deltaTopic` directly and filter by `delta.type`.
+ *
+ * The async boundary is handled by `fromAny(asyncGenerator)` (spec §5.10).
+ */
+declare function streamingPromptNode<T = string>(adapter: LLMAdapter, deps: readonly Node<unknown>[], prompt: string | ((...depValues: unknown[]) => string), opts?: StreamingPromptNodeOptions): StreamingPromptNodeHandle<T>;
+type GatedStreamOptions = StreamingPromptNodeOptions & {
+    /** Gate options (maxPending, startOpen). */
+    gate?: Omit<GateOptions, "meta">;
+};
+/**
+ * Bundle returned by {@link gatedStream}.
+ */
+type GatedStreamHandle<T> = {
+    /** Final parsed result (after gate approval). */
+    output: Node<T | null>;
+    /** Live delta topic — every adapter delta in order, stamped with `seq` + `ts`. */
+    deltaTopic: TopicGraph<StampedDelta>;
+    /** Reactive accumulated-text view. */
+    accumulatedText: Node<string>;
+    /**
+     * Gate controller — approve, reject (aborts in-flight stream), modify.
+     * The gate's DATA domain is `T` (not `T | null`): the pre-gate `filter`
+     * drops nulls, so the pending queue never holds a null. The controller's
+     * `node` output type stays `T | null` only because `gate.approve()` on an
+     * empty queue would surface `null` — callers should treat `null` as "no
+     * value" rather than as a modeled null signal.
+     */
+    gate: GateController<T>;
+    /** Tear down the delta topic + gate keepalive. */
+    dispose: () => void;
+};
+/**
+ * Streaming LLM transform with human-in-the-loop gate integration.
+ *
+ * Composes {@link streamingPromptNode} with `gate` so that:
+ * - `gate.reject()` discards the pending value **and** aborts the in-flight
+ *   stream (toggles an internal cancel signal → switchMap restart → abort).
+ * - `gate.modify()` transforms the pending value before forwarding downstream.
+ * - `gate.approve()` forwards the final result as normal.
+ *
+ * Wave A Unit 2 defers full `gatedStream` review to Wave B Unit 17 (the
+ * `gate()` primitive itself is reviewed there). This implementation retains
+ * the existing gate API while adopting the Unit 2 delta-topic shape.
+ */
+declare function gatedStream<T = string>(graph: Graph, name: string, adapter: LLMAdapter, deps: readonly Node<unknown>[], prompt: string | ((...depValues: unknown[]) => string), opts?: GatedStreamOptions): GatedStreamHandle<T>;
+
+/**
+ * `systemPromptBuilder` — assembles a reactive system prompt from sections.
+ *
+ * @module
+ */
+
+/**
+ * Assembles a system prompt from reactive sections. Each section is a
+ * `NodeInput<string>` — the prompt updates when any section changes.
+ */
+type SystemPromptHandle = Node<string> & {
+    dispose: () => void;
+};
+declare function systemPromptBuilder(sections: readonly NodeInput<string>[], opts?: {
+    separator?: string;
+    name?: string;
+}): SystemPromptHandle;
+
+/**
+ * Cost meter extractor — derives live cost readings from the delta topic.
+ *
+ * **Wave A Unit 3 rewrite:** signature takes `deltaTopic: TopicGraph<StampedDelta>`
+ * instead of the old `TopicGraph<StreamChunk>`. The meter prefers real
+ * `usage` deltas from the adapter; when no `usage` has been seen yet it
+ * falls back to a char-based estimate over token deltas and stamps
+ * `estimated: true` on the reading. Chunk count is the count of
+ * token-type deltas seen (was `chunk.index + 1`).
+ *
+ * @module
+ */
+
+/** A cost meter reading from the stream. */
+type CostMeterReading = {
+    readonly chunkCount: number;
+    readonly charCount: number;
+    readonly estimatedTokens: number;
+    /**
+     * `true` when no adapter `usage` delta has been observed yet —
+     * `estimatedTokens` is a char-based heuristic and should be treated as an
+     * approximation. Flips to `false` once a real `usage` delta arrives.
+     */
+    readonly estimated: boolean;
+};
+type CostMeterOptions = {
+    /** Characters per token approximation. Default: 4 (GPT-family). */
+    charsPerToken?: number;
+    name?: string;
+};
+/**
+ * Mounts a cost meter on the delta topic. Prefers real `usage` deltas from
+ * the provider; falls back to char-based estimation on token deltas alone
+ * (with `meta.estimated: true` on the reading).
+ *
+ * Default structural equals suppresses DATA emission when two consecutive
+ * readings are identical.
+ */
+declare function costMeterExtractor(deltaTopic: TopicGraph<StampedDelta>, opts?: CostMeterOptions): Node<CostMeterReading>;
+
+/**
+ * Keyword-flag extractor — scans accumulated stream text for configured patterns.
+ * @module
+ */
+
+/** A keyword match detected in the stream. */
+type KeywordFlag = {
+    readonly label: string;
+    readonly pattern: RegExp;
+    readonly match: string;
+    readonly position: number;
+};
+type KeywordFlagExtractorOptions = {
+    patterns: readonly {
+        pattern: RegExp;
+        label: string;
+    }[];
+    name?: string;
+    /**
+     * Maximum length of any pattern's literal text. Used as an overlap window
+     * when cursoring through the accumulated stream so matches that span
+     * chunk boundaries aren't missed. Default: 128.
+     */
+    maxPatternLength?: number;
+};
+/**
+ * Mounts a keyword-flag extractor on accumulated text. Scans for all
+ * configured patterns and emits an array of matches.
+ *
+ * **Wave A Unit 3 rewrite:** signature takes `accumulatedText: Node<string>`
+ * instead of the old `TopicGraph<StreamChunk>`. Patterns are compiled once
+ * at factory time (was per-chunk). `maxPatternLength` is validated at
+ * factory time — any pattern whose source exceeds the window throws
+ * immediately.
+ *
+ * Use cases: design invariant violations (`setTimeout`, `EventEmitter`), PII
+ * detection (SSN, email, phone), toxicity keywords, off-track reasoning.
+ *
+ * **Streaming optimization.** Maintains a cursor across waves in `ctx.store`
+ * so each emission scans only the delta region `accumulated.slice(scannedTo -
+ * maxPatternLength)` — not the full string. Reactivation clears `ctx.store`
+ * and resumes from offset 0 (COMPOSITION-GUIDE §20 RAM semantics).
+ *
+ * Default structural equals suppresses DATA emission when no new flags were
+ * found this wave.
+ */
+declare function keywordFlagExtractor(accumulatedText: Node<string>, opts: KeywordFlagExtractorOptions): Node<readonly KeywordFlag[]>;
+
+/**
+ * Generic stream extractor — mounts an extract function on accumulated text.
+ *
+ * **Wave A Unit 3 rewrite:** signature changed from
+ * `streamExtractor(topic: TopicGraph<StreamChunk>, fn)` to
+ * `streamExtractor(accumulatedText: Node<string>, fn)`. The Unit 2 delta-
+ * topic redesign removed the per-chunk `accumulated` field; callers pass
+ * `streamingPromptNode(...).accumulatedText` (or any other `Node<string>`
+ * source of accumulated text). Source-agnostic — the extractor doesn't care
+ * whether the text came from an LLM, WebSocket, SSE tail, or file reader.
+ *
+ * @module
+ */
+
+/**
+ * Mounts an extractor function on a reactive accumulated-text source. Returns
+ * a derived node that emits extracted values as the text grows.
+ *
+ * @param accumulatedText - Reactive `Node<string>` of accumulated text.
+ * @param extractFn - `(accumulated: string) => T | null`.
+ * @param opts - Optional name + structural equals.
+ * @returns Derived node emitting extracted values.
+ */
+declare function streamExtractor<T>(accumulatedText: Node<string>, extractFn: (accumulated: string) => T | null, opts?: {
+    name?: string;
+    /**
+     * Optional structural equals for the extractor output. When two
+     * consecutive chunks produce structurally-equal outputs, the framework
+     * emits `RESOLVED` instead of `DATA`, saving downstream work. Default:
+     * reference equality (`Object.is`). The library cannot know your
+     * output shape — supply this when your `extractFn` returns structured
+     * objects or arrays.
+     */
+    equals?: (a: T | null, b: T | null) => boolean;
+}): Node<T | null>;
+
+/**
+ * Tool-call extractor — scans accumulated stream text for complete JSON tool call objects.
+ * @module
+ */
+
+/** A tool call detected in the stream. */
+type ExtractedToolCall = {
+    readonly name: string;
+    readonly arguments: Record<string, unknown>;
+    readonly raw: string;
+    readonly startIndex: number;
+};
+/**
+ * Mounts a tool-call extractor on a streaming topic. Scans accumulated text
+ * for complete JSON objects containing `"name"` and `"arguments"` keys (the
+ * standard tool_call shape). Partial JSON is ignored until the closing brace.
+ *
+ * Feeds into the tool interception chain for reactive tool gating mid-stream.
+ *
+ * **Streaming optimization.** Maintains a cursor (`scanFrom`) in `ctx.store`
+ * so each chunk resumes brace-scanning from the position after the last
+ * complete parse (or the last incomplete open brace). Already-parsed objects
+ * are not re-parsed. Default structural equals suppresses DATA emission when
+ * no new tool call completed this chunk.
+ */
+declare function toolCallExtractor(accumulatedText: Node<string>, opts?: {
+    name?: string;
+}): Node<readonly ExtractedToolCall[]>;
+
+/**
+ * Content gate — classifies accumulated stream text as allow / review / block.
+ * @module
+ */
+
+/** Content safety decision. */
+type ContentDecision = "allow" | "block" | "review";
+/** Options for {@link contentGate}. */
+type ContentGateOptions = {
+    /**
+     * Hard-block threshold multiplier (default 1.5).
+     * Scores above `threshold * hardMultiplier` emit `"block"`.
+     * Scores between `threshold` and that emit `"review"`.
+     */
+    hardMultiplier?: number;
+    name?: string;
+};
+/**
+ * Derived node that classifies accumulated stream text as `"allow"`,
+ * `"review"`, or `"block"` based on a classifier score.
+ *
+ * **Wave A Unit 3 rewrite:** signature now takes `accumulatedText: Node<string>`
+ * instead of a `TopicGraph<StreamChunk>` (the `StreamChunk` shape was retired
+ * when the delta topic replaced the per-chunk accumulated-text shape).
+ *
+ * Emits a three-way decision on every text change:
+ * - `"allow"` — score below `threshold`
+ * - `"review"` — score in `[threshold, threshold × hardMultiplier)`
+ * - `"block"` — score at or above `threshold × hardMultiplier`
+ *
+ * @param accumulatedText - Reactive accumulated-text source
+ *                          (`streamingPromptNode(...).accumulatedText`).
+ * @param classifier - `(accumulated: string) => number` scoring function, or
+ *                     a `Node<number>` for live scores.
+ * @param threshold - Score at which output becomes `"review"` or `"block"`.
+ */
+declare function contentGate(accumulatedText: Node<string>, classifier: ((accumulated: string) => number) | Node<number>, threshold: number, opts?: ContentGateOptions): Node<ContentDecision>;
+
+/**
+ * Redactor — stream extractor that replaces matched patterns in accumulated text.
+ *
+ * **Wave A Unit 3 rewrite:** signature now takes `accumulatedText: Node<string>`
+ * instead of the retired `TopicGraph<StreamChunk>`. The output is a
+ * `Node<string>` carrying the sanitized accumulated text — compose with
+ * `contentGate` or downstream UI directly.
+ *
+ * @module
+ */
+
+/** Options for {@link redactor}. */
+type RedactorOptions = {
+    name?: string;
+};
+/**
+ * Derived node that replaces matched patterns in accumulated text.
+ *
+ * @param accumulatedText - Reactive accumulated-text source.
+ * @param patterns - Array of RegExps to match against the text.
+ * @param replaceFn - Replacement producer (default: always `"[REDACTED]"`).
+ * @returns `Node<string>` emitting the sanitized accumulated text.
+ */
+declare function redactor(accumulatedText: Node<string>, patterns: RegExp[], replaceFn?: (match: string, pattern: RegExp) => string, opts?: RedactorOptions): Node<string>;
+
+/**
+ * Options for {@link handoff}.
+ */
+type HandoffOptions = {
+    /**
+     * Reactive gate: when this node's value is `true`, output flows from
+     * `from` to the `to` specialist; when `false`, `from`'s output flows
+     * through unchanged and `to` stays dormant. Omit to always hand off —
+     * useful when `from` is itself a router whose output shape already
+     * encodes routing intent.
+     */
+    condition?: NodeInput<boolean>;
+    name?: string;
+};
+/**
+ * Multi-agent handoff recipe — route `from`'s output into a specialist
+ * agent `toFactory` when `condition` is open. Thin composition over
+ * `switchMap` + gate; not a new primitive, just a named shape.
+ *
+ * The "handoff" pattern (popularized by the OpenAI Agents SDK) covers two
+ * idioms:
+ *
+ * 1. **Full handoff** — a triage agent routes the conversation to a
+ *    specialist, and the specialist becomes the active agent for the rest
+ *    of the turn. Accumulated context (memory, tool definitions) can travel
+ *    along by threading the same `agentMemory` bundle into both.
+ * 2. **Agents-as-tools** — the manager keeps control and calls the
+ *    specialist like a tool for a bounded subtask. Build this by registering
+ *    a `promptNode` instance as a `ToolDefinition` on the parent via
+ *    `toolRegistry`.
+ *
+ * This sugar covers (1) — a reactive route from one agent's output into a
+ * specialist factory. For (2) wire a tool registry manually; the pattern is
+ * additive with this one.
+ *
+ * @example Full handoff on a triage signal.
+ * ```ts
+ * import { handoff, promptNode } from "@graphrefly/graphrefly/patterns/ai";
+ *
+ * const triage = promptNode(adapter, [userMessage], (msg) =>
+ *   `Classify urgency of: ${msg}. Reply "high" or "normal".`);
+ * const isUrgent = derived([triage], ([v]) => v === "high");
+ *
+ * const specialist = handoff(
+ *   userMessage,
+ *   (input) => promptNode(specialistAdapter, [input], (m) => `Respond urgently: ${m}`),
+ *   { condition: isUrgent },
+ * );
+ * ```
+ *
+ * @param from - Source node whose value is threaded into the specialist.
+ * @param toFactory - Factory that takes `from` (as a reactive source) and
+ *   returns the specialist node. Called once, lazily, when the first
+ *   subscriber activates.
+ * @param opts - Optional reactive `condition` gate + name.
+ * @returns Node emitting the specialist's output when the gate is open, or
+ *   `from`'s value when the gate is closed. Null when `from` is null.
+ *
+ * **Performance caveat (Wave A Unit 5):** the specialist is mounted per
+ * source emission — each `v != null` DATA on `from` allocates a fresh
+ * `state<T>(v)` + invokes `toFactory`, and switchMap cancels the prior
+ * branch. For per-turn routing (≤1 emit/sec) this is negligible. For
+ * high-frequency sources (per-token routing, tight event loops), batch
+ * upstream (e.g. via `audit`, `throttle`, or `distinctUntilChanged`) before
+ * handing off — each mount/unmount cycle spins up full subgraphs
+ * (`messagesNode` + adapter bridge + output for a `promptNode` specialist).
+ *
+ * @category patterns.ai
+ */
+declare function handoff<T>(from: NodeInput<T | null>, toFactory: (input: Node<T>) => Node<T | null>, opts?: HandoffOptions): Node<T | null>;
+
+/**
+ * Options for {@link toolSelector}.
+ */
+interface ToolSelectorOptions {
+    readonly name?: string;
+}
+/**
+ * Reactive tool availability (COMPOSITION-GUIDE §31). Given a base tool set
+ * (reactive or static) and one or more reactive predicates, emit the filtered
+ * subset of tools currently allowed. Feeds into `promptNode({ tools: Node<...> })`
+ * so the LLM sees a reactive menu instead of a frozen config.
+ *
+ * Each predicate is a `NodeInput<(tool) => boolean>`. A tool is included iff
+ * **every** predicate returns `true`. When any predicate value is `null` /
+ * `undefined` (e.g. upstream not yet ready) that predicate is treated as a
+ * pass-through — the tool isn't excluded on its basis. Predicate updates
+ * recompute the selected set.
+ *
+ * Pairs with `toolInterceptor` (§D9 / §31): **selection** controls what's
+ * offered to the LLM (pre-generation UX); **interception** gates what's
+ * executed after the LLM chooses (post-generation security). Tool selection
+ * is NOT a security boundary — an LLM can hallucinate tool calls outside
+ * its offered set; always pair with `toolInterceptor` for enforcement.
+ *
+ * @example
+ * ```ts
+ * const hasBudget = node([costMeter], (batchData, actions, ctx) => {
+ *   const data = batchData.map((batch, i) => batch != null && batch.length > 0 ? batch.at(-1) : ctx.prevData[i]);
+ *   actions.emit((data[0] as CostMeter).total < BUDGET);
+ * }, { describeKind: "derived" });
+ * const canDestroy = state(false, { name: "destructive-allowed" });
+ * const tools = toolSelector(registry.schemas, [
+ *   node([hasBudget], (batchData, actions, ctx) => {
+ *     const data = batchData.map((batch, i) => batch != null && batch.length > 0 ? batch.at(-1) : ctx.prevData[i]);
+ *     actions.emit((t) => !t.meta?.expensive || data[0] === true);
+ *   }, { describeKind: "derived" }),
+ *   node([canDestroy], (batchData, actions, ctx) => {
+ *     const data = batchData.map((batch, i) => batch != null && batch.length > 0 ? batch.at(-1) : ctx.prevData[i]);
+ *     actions.emit((t) => !t.meta?.destructive || data[0] === true);
+ *   }, { describeKind: "derived" }),
+ * ]);
+ * const agent = promptNode(graph, "agent", { ..., tools });
+ * ```
+ */
+declare function toolSelector(allTools: NodeInput<readonly ToolDefinition[]>, constraints: readonly NodeInput<(tool: ToolDefinition) => boolean>[], opts?: ToolSelectorOptions): Node<readonly ToolDefinition[]>;
+
+/** Generic per-dimension thresholds. Any dim below its threshold → reject. */
+type AdmissionThresholds<Dims extends string> = Partial<Record<Dims, number>>;
+type AdmissionScoredOptions<Dims extends string, TRaw = unknown> = {
+    /** Score function — must return a finite number for every dimension named in `thresholds`. */
+    scoreFn: (raw: TRaw) => Readonly<Record<Dims, number>>;
+    /** Per-dim minimums. Dims absent here are scored but not gated. */
+    thresholds?: AdmissionThresholds<Dims>;
+};
+/**
+ * Generic N-dimension admission filter. Rejects any input where one of the
+ * configured threshold dimensions scores below its minimum. Missing scores
+ * (`undefined` / `null`) AND non-finite values (`NaN`, `±Infinity`) are
+ * treated as below all thresholds — reject by default rather than admit.
+ *
+ * @example
+ * ```ts
+ * const filter = admissionScored({
+ *   scoreFn: (raw: Note) => ({ relevance: scoreRelevance(raw), age: ageScore(raw) }),
+ *   thresholds: { relevance: 0.4 },  // age scored but ungated
+ * });
+ * ```
+ */
+declare function admissionScored<Dims extends string, TRaw = unknown>(opts: AdmissionScoredOptions<Dims, TRaw>): (raw: TRaw) => boolean;
+/** Scores for the three admission dimensions. Each 0–1. */
+type AdmissionScores = {
+    readonly persistence: number;
+    readonly structure: number;
+    readonly personalValue: number;
+};
+type AdmissionScore3DOptions = {
+    /** Custom scoring function. Required — the previous always-0.5 default was misleading. */
+    scoreFn: (raw: unknown) => AdmissionScores;
+    /** Minimum persistence score to admit (default 0.3). */
+    persistenceThreshold?: number;
+    /** Minimum personalValue score to admit (default 0.3). */
+    personalValueThreshold?: number;
+    /** Require structure score > 0 to admit (default false). */
+    requireStructured?: boolean;
+};
+/**
+ * 3D admission sugar — the persistence / structure / personalValue triple
+ * commonly used in agent-memory literature. Composes `admissionScored`
+ * with thresholds derived from the option fields. Use directly when those
+ * three named dimensions match your domain, or use `admissionScored` with
+ * an arbitrary dimension set instead.
+ *
+ * `requireStructured: true` rejects entries where `structure <= 0` (matches
+ * the pre-Unit-8 `requireStructured && scores.structure <= 0` check).
+ * Implemented as a final-step predicate around `admissionScored` rather
+ * than a `Number.MIN_VALUE` threshold, which would have been a footgun for
+ * future readers.
+ */
+declare function admissionFilter3D(opts: AdmissionScore3DOptions): (raw: unknown) => boolean;
+
+type GaugesAsContextOptions = {
+    /** Group gauges by `meta.tags` (default true). */
+    groupByTags?: boolean;
+    /** Separator between gauge lines (default "\n"). */
+    separator?: string;
+    /**
+     * V0 delta mode (§6.0b): only include nodes whose `v.version` exceeds
+     * the corresponding entry in this map. Nodes without V0 or not in the
+     * map are always included. Callers maintain this map across calls.
+     *
+     * The `id` field guards against node replacement: if a node is removed
+     * and re-added under the same name (new id), it is always included.
+     */
+    sinceVersion?: ReadonlyMap<string, {
+        id: string;
+        version: number;
+    }>;
+};
+/**
+ * Format a graph's readable (gauge) nodes as a context string for LLM
+ * system prompts.
+ *
+ * Gauges are nodes with `meta.description` or `meta.format`. Values are
+ * formatted using `meta.format` and `meta.unit` hints.
+ *
+ * @param graph - The graph to introspect.
+ * @param actor - Optional actor for guard-scoped describe.
+ * @param options - Formatting options.
+ * @returns A formatted string ready for system prompt injection.
+ */
+declare function gaugesAsContext(graph: Graph, actor?: Actor, options?: GaugesAsContextOptions): string;
+
+type GraphFromSpecOptions = {
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    /** Fn/source catalog for resolving named node factories from the LLM-generated spec. */
+    catalog?: GraphSpecCatalog;
+    /** Extra instructions appended to the system prompt. */
+    systemPromptExtra?: string;
+    /**
+     * Optional AbortSignal forwarded to `adapter.invoke({ signal })`. Lets
+     * callers cancel the in-flight LLM call (e.g. when the reactive variant
+     * supersedes mid-flight). When the signal aborts, the underlying call
+     * propagates the abort and `graphFromSpec` rejects with the abort reason.
+     */
+    signal?: AbortSignal;
+};
+/**
+ * Ask an LLM to compose a Graph from a natural-language description.
+ *
+ * The LLM returns a JSON {@link GraphSpec} which is validated, catalog-expanded,
+ * and instantiated via {@link compileSpec} (gains catalog validation, template
+ * expansion, and feedback wiring that `Graph.fromSnapshot` bypasses).
+ *
+ * @param naturalLanguage - The problem/use-case description.
+ * @param adapter - LLM adapter for the generation call.
+ * @param opts - Model options and optional catalog for named node factories.
+ * @returns A constructed Graph.
+ * @throws On invalid LLM output, validation failure, or unresolvable deps.
+ */
+declare function graphFromSpec(naturalLanguage: string, adapter: LLMAdapter, opts?: GraphFromSpecOptions): Promise<Graph>;
+/**
+ * Reactive variant of {@link graphFromSpec}: re-invokes the LLM and
+ * recompiles the graph whenever `input` emits a new natural-language
+ * description. Useful inside the harness or refine loop when the spec text
+ * itself is a reactive value (e.g. fed by a `node([], { initial: ... })` knob, a memory
+ * snapshot, or an upstream `promptNode` output).
+ *
+ * **Supersede:** when the input changes mid-flight, switchMap tears the
+ * inner producer down. The producer's cleanup aborts the in-flight LLM
+ * call via an internal `AbortController` (threaded into `graphFromSpec`'s
+ * new `signal` option) AND destroys any Graph that lands after cancel —
+ * no token leak, no unreferenced compiled graphs. If the user's input
+ * already changed by the time the LLM responds, the about-to-be-discarded
+ * Graph is freed instead of orphaned.
+ *
+ * **Lifetime of the latest emitted Graph:** the caller owns each Graph
+ * that actually reaches them. If you keep multiple historical values, call
+ * `prev?.destroy()` before storing the new one.
+ *
+ * @param input - Reactive source of natural-language descriptions.
+ * @param adapter - LLM adapter for the generation call.
+ * @param opts - Model options and optional catalog for named node factories.
+ * @returns `Node<Graph | null>` — emits the latest compiled graph, or `null`
+ *           while the input is empty / unsettled.
+ */
+declare function graphFromSpecReactive(input: NodeInput<string>, adapter: LLMAdapter, opts?: GraphFromSpecOptions): Node<Graph | null>;
+
+/** OpenAI function-calling tool schema. */
+type OpenAIToolSchema = {
+    readonly type: "function";
+    readonly function: {
+        readonly name: string;
+        readonly description: string;
+        readonly parameters: Record<string, unknown>;
+    };
+};
+/** MCP (Model Context Protocol) tool schema. */
+type McpToolSchema = {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+};
+/** Result of {@link knobsAsTools}. */
+type KnobsAsToolsResult = {
+    /** OpenAI function-calling tool schemas. */
+    readonly openai: readonly OpenAIToolSchema[];
+    /** MCP tool schemas. */
+    readonly mcp: readonly McpToolSchema[];
+    /** GraphReFly ToolDefinitions with handlers that call `graph.set()`. */
+    readonly definitions: readonly ToolDefinition[];
+};
+/**
+ * Derive tool schemas from a graph's writable (knob) nodes.
+ *
+ * Knobs are state nodes whose `meta.access` is `"llm"`, `"both"`, or absent
+ * (default: writable). Each knob becomes a tool that calls `graph.set()`.
+ *
+ * Speaks **domain language** (spec §5.4): the returned schemas use node names
+ * and meta descriptions — no protocol internals exposed.
+ *
+ * @param graph - The graph to introspect.
+ * @param actor - Optional actor for guard-scoped describe.
+ * @returns OpenAI, MCP, and GraphReFly tool schemas.
+ */
+declare function knobsAsTools(graph: Graph, actor?: Actor): KnobsAsToolsResult;
+
+/** A single operation in a strategy plan. */
+type StrategyOperation = {
+    readonly type: "add_node";
+    readonly name: string;
+    readonly nodeType: string;
+    readonly meta?: Record<string, unknown>;
+    readonly initial?: unknown;
+} | {
+    readonly type: "remove_node";
+    readonly name: string;
+} | {
+    readonly type: "connect";
+    readonly from: string;
+    readonly to: string;
+} | {
+    readonly type: "disconnect";
+    readonly from: string;
+    readonly to: string;
+} | {
+    readonly type: "set_value";
+    readonly name: string;
+    readonly value: unknown;
+} | {
+    readonly type: "update_meta";
+    readonly name: string;
+    readonly key: string;
+    readonly value: unknown;
+};
+/** Structured strategy plan returned by {@link suggestStrategy}. */
+type StrategyPlan = {
+    readonly summary: string;
+    readonly operations: readonly StrategyOperation[];
+    readonly reasoning: string;
+};
+type SuggestStrategyOptions = {
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    actor?: Actor;
+    /**
+     * Optional AbortSignal forwarded to `adapter.invoke({ signal })`. Lets
+     * callers cancel the in-flight LLM call (e.g. when the reactive variant
+     * supersedes mid-flight). When the signal aborts, the underlying call
+     * propagates the abort and `suggestStrategy` rejects with the abort reason.
+     */
+    signal?: AbortSignal;
+};
+/**
+ * Ask an LLM to analyze a graph and suggest topology/parameter changes
+ * to solve a stated problem.
+ *
+ * Returns a structured plan — does NOT auto-apply. The caller reviews
+ * and selectively applies operations.
+ *
+ * @param graph - The graph to analyze.
+ * @param problem - Natural-language problem statement.
+ * @param adapter - LLM adapter for the analysis call.
+ * @param opts - Model and actor options.
+ * @returns A structured strategy plan.
+ * @throws On invalid LLM output.
+ */
+declare function suggestStrategy(graph: Graph, problem: string, adapter: LLMAdapter, opts?: SuggestStrategyOptions): Promise<StrategyPlan>;
+/**
+ * Reactive variant of {@link suggestStrategy}: re-invokes the LLM whenever
+ * the `problem` source emits, sampling the latest `graph` value (via
+ * `withLatestFrom`) to describe. The graph is the *secondary* dep — only
+ * problem changes re-trigger analysis. This breaks the feedback cycle that
+ * would otherwise arise if downstream consumers wired `apply(plan)` back
+ * into the same graph node (graph mutation must not auto-fire a re-analysis).
+ *
+ * @param graph - Reactive source of graphs to analyze.
+ * @param problem - Reactive source of natural-language problem statements.
+ * @param adapter - LLM adapter for the analysis call.
+ * @param opts - Model and actor options.
+ * @returns `Node<StrategyPlan | null>` — emits the latest plan, or `null`
+ *           while inputs are unsettled.
+ */
+declare function suggestStrategyReactive(graph: Node<Graph | null>, problem: NodeInput<string>, adapter: LLMAdapter, opts?: SuggestStrategyOptions): Node<StrategyPlan | null>;
+
+/** Validation result from {@link validateGraphDef}. */
+type GraphDefValidation = {
+    readonly valid: boolean;
+    readonly errors: readonly string[];
+};
+/**
+ * Validate an LLM-generated graph definition before passing to
+ * `Graph.fromSnapshot()`.
+ *
+ * Checks:
+ * - Required fields: `name`, `nodes`, `edges`
+ * - Node types are valid enum values
+ * - Edge `from`/`to` reference existing nodes
+ * - No duplicate edge entries
+ *
+ * @param def - The graph definition to validate (parsed JSON).
+ * @returns Validation result with errors array.
+ */
+declare function validateGraphDef(def: unknown): GraphDefValidation;
+
+export { type AdapterStats, type AdmissionScore3DOptions, type AdmissionScoredOptions, type AdmissionScores, type AdmissionThresholds, type AnthropicAdapterOptions, type AnthropicSdkLike, type BudgetCaps, BudgetExhaustedError, type BudgetTotals, type CallStatsEvent, CascadeExhaustionReport, ChatMessage, type ContentDecision, type ContentGateOptions, type CostMeterOptions, type CostMeterReading, type DryRunAdapterOptions, type ExtractedToolCall, type FrozenContextOptions, type GatedStreamHandle, type GatedStreamOptions, type GaugesAsContextOptions, type GoogleAdapterOptions, type GoogleSdkLike, type GoogleSdkRequestConfig, type GoogleSdkRequestParams, type GraphDefValidation, type GraphFromSpecOptions, type HandoffOptions, type HttpErrorLike, type KeywordFlag, type KeywordFlagExtractorOptions, type KnobsAsToolsResult, LLMAdapter, type LLMBudgetGateBundle, type LLMConsolidatorOptions, type LLMExtractorOptions, LLMInvokeOptions, LLMResponse, LLMTimeoutError, type McpToolSchema, type OpenAIToolSchema, PricingFn, type PromptCallOptions, type PromptNodeOptions, type RedactorOptions, type ResilientAdapterBundle, type ResilientAdapterOptions, type StampedDelta, type StrategyOperation, type StrategyPlan, StreamDelta, type StreamingPromptNodeHandle, type StreamingPromptNodeOptions, type SuggestStrategyOptions, type SystemPromptHandle, TokenUsage, ToolDefinition, type ToolSelectorOptions, type WithBreakerOptions, type WithBudgetGateOptions, type WithDryRunBundle, type WithDryRunOptions, type WithRateLimiterOptions, WithReplayCacheOptions, type WithRetryOptions, admissionFilter3D, admissionScored, anthropicAdapter, contentGate, costMeterExtractor, dryRunAdapter, frozenContext, gatedStream, gaugesAsContext, googleAdapter, graphFromSpec, graphFromSpecReactive, handoff, keywordFlagExtractor, knobsAsTools, llmConsolidator, llmExtractor, observableAdapter, parseRateLimitFromError, promptCall, promptNode, redactor, resilientAdapter, streamExtractor, streamingPromptNode, suggestStrategy, suggestStrategyReactive, systemPromptBuilder, toolCallExtractor, toolSelector, validateGraphDef, withBudgetGate, withDryRun, withLLMBreaker, withLLMTimeout, withRateLimiter, withRetry };