@graphrefly/graphrefly 0.43.0 → 0.45.0

package/dist/decay-CdEBmDIs.d.ts

@@ -1,112 +0,0 @@
-import { N as Node, a as NodeOptions } from './node-ClS5yC-B.js';
-import { R as ReactiveMapBundle, b as ReactiveMapOptions } from './reactive-map-BVVPdvmi.js';
-import { NodeInput } from './extra/sources.js';
-
-/**
- * Composite data patterns (roadmap §3.2b).
- *
- * These helpers compose existing primitives (`node`, `switchMap`, `reactiveMap`,
- * `dynamicNode`, `fromAny`) without introducing new protocol semantics.
- */
-
-/**
- * Verification payload shape is intentionally user-defined.
- */
-type VerifyValue = unknown;
-type VerifiableOptions<TVerify = VerifyValue> = Omit<NodeOptions, "describeKind" | "initial"> & {
-    /** Reactive re-verification trigger. */
-    trigger?: NodeInput<unknown>;
-    /** Re-run verification whenever `source` settles. */
-    autoVerify?: boolean;
-    /** Initial verification companion value. */
-    initialVerified?: TVerify | null;
-};
-type VerifiableBundle<T, TVerify = VerifyValue> = {
-    /** Coerced source node. */
-    node: Node<T>;
-    /** Latest verification result (`null` before first verification). */
-    verified: Node<TVerify | null>;
-    /** Effective trigger node used for verification, if any. */
-    trigger: Node<unknown> | null;
-};
-/**
- * Composes a value node with a reactive verification companion.
- *
- * Uses `switchMap` so newer triggers cancel stale in-flight verification work.
- */
-declare function verifiable<T, TVerify = VerifyValue>(source: NodeInput<T>, verifyFn: (value: T) => NodeInput<TVerify>, opts?: VerifiableOptions<TVerify>): VerifiableBundle<T, TVerify>;
-type Extraction<TMem> = {
-    upsert: Array<{
-        key: string;
-        value: TMem;
-    }>;
-    remove?: string[];
-};
-type DistillOptions<TMem> = {
-    score: (mem: TMem, context: unknown) => number;
-    cost: (mem: TMem) => number;
-    budget?: number;
-    evict?: (key: string, mem: TMem) => boolean | Node<boolean>;
-    consolidate?: (entries: ReadonlyMap<string, TMem>) => NodeInput<Extraction<TMem>>;
-    consolidateTrigger?: NodeInput<unknown>;
-    context?: NodeInput<unknown>;
-    mapOptions?: ReactiveMapOptions<string, TMem>;
-};
-type DistillBundle<TMem> = {
-    store: ReactiveMapBundle<string, TMem>;
-    compact: Node<Array<{
-        key: string;
-        value: TMem;
-        score: number;
-    }>>;
-    size: Node<number>;
-};
-/**
- * Budget-constrained reactive memory composition.
- *
- * **Tier 1.5.4 (Session A.5 lock, 2026-04-27):** `extractFn` receives the
- * source and existing-store as `Node`s. Distill calls `extractFn` ONCE at
- * wiring time and consumes the returned stream of extractions. The user
- * controls reactive composition — wrap with `switchMap` for cancel-on-new-input,
- * `mergeMap` for parallel, `derived` for sync transforms. See COMPOSITION-GUIDE
- * §40 for the recipe.
- */
-declare function distill<TRaw, TMem>(source: NodeInput<TRaw>, extractFn: (raw: Node<TRaw>, existing: Node<ReadonlyMap<string, TMem>>) => NodeInput<Extraction<TMem>>, opts: DistillOptions<TMem>): DistillBundle<TMem>;
-
-/**
- * Pure exponential-decay utility (Tier 2.2 promotion from `patterns/memory/`).
- *
- * Used by `collection`, `agentMemory`, harness `strategy.ts`, and any
- * downstream consumer that needs decay-with-floor scoring. Promoted to
- * `extra/utils/` because the math has zero domain semantics and is reusable
- * by non-memory primitives (e.g. routing weight decay, retry-attempt aging).
- *
- * @module
- */
-/**
- * Default exponential-decay rate corresponding to a 7-day half-life.
- *
- * `Math.LN2 / (7 × 86_400)` ≈ `1.146e-6`. Imported by memory tiers + any
- * consumer that wants the same default cadence as `agentMemory`'s active
- * tier. Tier 4.4 (Wave AM Unit 1) — promoted from
- * `patterns/ai/memory/tiers.ts` so non-memory consumers can share the
- * canonical default without reaching across domains.
- */
-declare const DEFAULT_DECAY_RATE: number;
-/**
- * Exponential decay with floor: `score = max(minScore, baseScore * exp(-ratePerSecond * ageSeconds))`.
- *
- * Tolerant fallbacks (deliberate for use inside reactive derived fns):
- * - non-finite `baseScore` → `minScore`
- * - non-positive `ageSeconds` (incl. clock skew) → `max(minScore, baseScore)` (no decay)
- * - non-positive `ratePerSecond` → `max(minScore, baseScore)` (no decay; rate=0 disables)
- *
- * Underflow boundary: `Math.exp(-745) === 0`. For very long ages × rates the
- * result clamps to `minScore`; if you need slow decay over years, choose a
- * smaller `ratePerSecond` rather than relying on graceful underflow.
- *
- * Half-life conversion: `ratePerSecond = Math.LN2 / halfLifeSeconds`.
- */
-declare function decay(baseScore: number, ageSeconds: number, ratePerSecond: number, minScore?: number): number;
-
-export { type DistillBundle as D, type Extraction as E, type VerifiableBundle as V, type DistillOptions as a, type VerifiableOptions as b, type VerifyValue as c, decay as d, distill as e, DEFAULT_DECAY_RATE as f, verifiable as v };

package/dist/fallback-CqYVLL6X.d.ts

@@ -1,250 +0,0 @@
-import { KvStorageTier } from './extra/storage-tiers.js';
-import { C as ChatMessage, a as LLMInvokeOptions, L as LLMAdapter, b as LLMResponse, S as StreamDelta } from './types-DkzUUs0H.js';
-import { d as canonicalJson$1 } from './content-addressed-storage-DuYMjV7o.js';
-
-/**
- * `withReplayCache` — content-addressed response cache over `KvStorageTier`.
- *
- * - Key: sha256 of canonicalized (messages + invoke options minus `signal`).
- * - `"read-write"` (default): returns cached response if present; on miss,
- *   passes through and stores the result.
- * - `"write-only"`: never reads; populates the cache for later runs.
- * - `"read"`: reads only; on miss, passes through without writing.
- * - `"read-strict"`: reads only; on miss, **throws `ReplayCacheMissError`**
- *   instead of passing through. Use for fixture-driven tests or offline
- *   fallback adapters where any cache miss is a test failure or a signal to
- *   degrade.
- *
- * Reuses the library's existing `KvStorageTier` abstraction — any kv tier
- * (memoryKv / fileKv / sqliteKv / indexedDbKv / custom).
- *
- * **Concurrent cache-miss dedup:** uses `singleFromAny` so two concurrent
- * calls with the same key share one upstream request. Second caller sees the
- * same response that the first caller fetched; no duplicate provider spend.
- *
- * **Circular-ref safe:** `canonicalJson` uses a seen-set replacer so
- * user-supplied `ToolDefinition.parameters` with `$ref` cycles don't stack-
- * overflow the key computation.
- *
- * **Stream cadence capture:** when `cacheStreaming: true` AND
- * `captureStreamCadence: true`, per-chunk delays (ms since previous chunk)
- * are recorded alongside the content. Replay honors the recorded cadence
- * unless `replaySpeed` is set, which multiplies the effective per-chunk
- * delay (`replaySpeed: 2` → 2× faster; `replaySpeed: 0` → instant).
- * Without `captureStreamCadence`, replay is instant regardless.
- */
-
-type ReplayCacheMode = "read" | "read-strict" | "write-only" | "read-write";
-declare class ReplayCacheMissError extends Error {
-    readonly key: string;
-    readonly method: "invoke" | "stream";
-    name: string;
-    constructor(key: string, method: "invoke" | "stream");
-}
-/**
- * Context object passed to {@link WithReplayCacheOptions.keyFn}. Extending
- * with additional fields is forward-compatible — current implementations
- * ignoring unknown fields continue to work.
- */
-interface ReplayCacheKeyContext {
-    readonly messages: readonly ChatMessage[];
-    readonly opts: LLMInvokeOptions | undefined;
-    /** Shortcut to `opts?.keyContext` — avoids an extra guard in callers. */
-    readonly context: unknown;
-}
-interface WithReplayCacheOptions {
-    storage: KvStorageTier;
-    mode?: ReplayCacheMode;
-    /**
-     * Custom key function. Receives a {@link ReplayCacheKeyContext} with the
-     * chat messages, the invoke options, and the caller-supplied
-     * `opts.keyContext`. Defaults to sha256 of canonical JSON over
-     * `(messages, opts without signal/keyContext)`.
-     *
-     * Legacy 2-arg form `(messages, opts?)` also accepted — the adapter
-     * detects arity and dispatches. Prefer the object form for new code.
-     */
-    keyFn?: ((ctx: ReplayCacheKeyContext) => string | Promise<string>) | ((messages: readonly ChatMessage[], opts?: LLMInvokeOptions) => string | Promise<string>);
-    /** Prefix for cached keys (useful when sharing a tier across domains). */
-    keyPrefix?: string;
-    /**
-     * Whether to cache streaming responses (by consuming the full stream
-     * and replaying it as one synthetic token chunk). Default `false`.
-     */
-    cacheStreaming?: boolean;
-    /**
-     * When `cacheStreaming: true`, also record per-chunk delays (ms since
-     * previous chunk) so replay can honor the original streaming cadence.
-     * Default `false` (chunks replay instantly).
-     */
-    captureStreamCadence?: boolean;
-    /**
-     * Stream replay speed multiplier. `1` = original cadence (requires
-     * `captureStreamCadence`). `2` = 2× faster. `0` = instant. Default `1`.
-     */
-    replaySpeed?: number;
-}
-/** Wrap an adapter with a replay cache. */
-declare function withReplayCache(inner: LLMAdapter, opts: WithReplayCacheOptions): LLMAdapter;
-/**
- * Canonical JSON — re-exported from `src/extra/content-addressed-storage.ts`
- * so `fallbackAdapter` and other cache-adjacent code that historically
- * imported from here continue to work. Same behavior.
- */
-declare const canonicalJson: typeof canonicalJson$1;
-
-/**
- * `fallbackAdapter` — fixture-backed {@link LLMAdapter} for offline demos,
- * deterministic tests, and graceful degradation in production.
- *
- * A peer of `anthropicAdapter` / `openAICompatAdapter` / `googleAdapter` /
- * `ollamaAdapter` / `dryRunAdapter`, but whose role is to serve pre-recorded
- * or canned responses when real providers aren't reachable. Install it as a
- * tier via the existing routing primitives (no new composer needed):
- *
- * ```ts
- * // Graceful offline fallback for a user app:
- * resilientAdapter(anthropicAdapter({ ... }), {
- *   fallback: fallbackAdapter({ fixturesDir: "./fixtures" }),
- * });
- *
- * // Or the general N-tier shape:
- * cascadingLlmAdapter([
- *   { name: "primary",  adapter: anthropicAdapter({ ... }) },
- *   { name: "fallback", adapter: fallbackAdapter({ fixturesDir: "./fixtures" }) },
- * ]);
- * ```
- *
- * The `provider` field is `"fallback"` so its role is self-documenting in
- * logs, stats, cost tables, and audit trails.
- *
- * ## Three fixture sources (mutually exclusive)
- *
- * Pick exactly one of:
- *
- * 1. **`fixtures: FallbackFixture[]`** — inline, hand-authored. Supports
- *    both hash-keyed and messages-keyed shapes; the adapter computes the
- *    canonical hash for messages-keyed entries at init time. Ideal when you
- *    want full control in code (tests, small demos).
- *
- * 2. **`fixturesStorage: KvStorageTier`** — the escape hatch for any backend.
- *    Pass a `memoryKv()`, `indexedDbKv(...)`, `sqliteKv(...)`,
- *    `cascadingCache(...)`, or a custom tier. You own the layout — no
- *    auto-namespacing.
- *
- *    **Filesystem directories (Node only):** the core `fallbackAdapter`
- *    does NOT import `node:fs` / `node:path` — it's safe to bundle for
- *    browsers. For a directory convenience, import `fallbackAdapter` from
- *    `@graphrefly/graphrefly/patterns/ai/node` (node subpath);
- *    that variant adds `fixturesDir: string` (auto-namespaced to
- *    `join(dir, keyPrefix)`, cache-format validated at init).
- *
- * ## Record mode
- *
- * `record: { adapter: real, storage }` proxies every call to `real` AND
- * persists the response through the provided tier. Use the node subpath's
- * `fallbackAdapter` for `record.dir` (auto-namespaced + `record.dir` defaults
- * to `fixturesDir` when both are file-backed).
- *
- * ## Three use cases, one implementation
- *
- * | Use case | Config |
- * |---|---|
- * | **User apps** — degrade when the cloud provider errors or network is down | `fallbackAdapter({ fixturesStorage: ... })` installed as a fallback tier |
- * | **Tests** — deterministic replays, fail loudly on miss | `fallbackAdapter({ fixturesStorage: ..., onMiss: "throw" })` |
- * | **Eval offline replay** — zero-spend repeat runs | `fallbackAdapter({ fixturesStorage: ... })` as the only adapter |
- *
- * ## Implementation
- *
- * Thin sugar over {@link withReplayCache}. Key shape comes from its
- * `canonicalJson` — fixtures written by either tool are interchangeable.
- *
- * @module
- */
-
-type FallbackMissPolicy = "throw" | "respond";
-/**
- * Thrown when `fallbackAdapter({ onMiss: "throw" })` receives a request that
- * has no matching fixture. Alias of `ReplayCacheMissError` for now — the
- * adapter is a thin sugar over `withReplayCache` and shares its miss-error.
- */
-declare const FallbackMissError: typeof ReplayCacheMissError;
-type FallbackMissError = ReplayCacheMissError;
-/**
- * One recorded fixture. Two authoring shapes:
- * - **Hash-keyed** — `{ key, response, stream? }`. Key is `sha256(canonicalJson({messages, opts}))`
- *   with `fallback:` prefix. This is what `record` mode writes.
- * - **Messages-keyed** — `{ messages, invokeOpts?, response }`. The adapter
- *   computes the key at init time. Ergonomic for hand-authored fixtures.
- */
-type FallbackFixture = {
-    readonly key: string;
-    readonly response: LLMResponse;
-    readonly stream?: {
-        readonly chunks: readonly StreamDelta[];
-        readonly delaysMs?: readonly number[];
-    };
-} | {
-    readonly messages: readonly ChatMessage[];
-    readonly invokeOpts?: Omit<LLMInvokeOptions, "signal">;
-    readonly response: LLMResponse;
-};
-interface FallbackAdapterOptions {
-    /** Adapter provider label. Default `"fallback"`. */
-    readonly provider?: string;
-    /** Adapter model label. Default `"fallback"`. */
-    readonly model?: string;
-    /**
-     * Inline hand-authored fixtures. Supports both hash-keyed (`{key, response, stream?}`)
-     * and messages-keyed (`{messages, invokeOpts?, response}`) shapes — the adapter
-     * computes the canonical hash for messages-keyed entries at init time. Held in
-     * an internal `memoryKv`. Mutually exclusive with `fixturesDir` and
-     * `fixturesStorage`.
-     */
-    readonly fixtures?: readonly FallbackFixture[];
-    /**
-     * Bring-your-own `KvStorageTier` (`memoryKv`, `sqliteKv`,
-     * `indexedDbKv`, `cascadingCache`, or a custom tier). You own the
-     * layout — no auto-namespacing. Mutually exclusive with `fixtures`.
-     *
-     * For filesystem directories, use the node subpath's `fallbackAdapter`
-     * with its `fixturesDir` option (auto-namespaced + validated).
-     */
-    readonly fixturesStorage?: KvStorageTier;
-    /**
-     * Called on fixture miss when `onMiss === "respond"`. If not provided and
-     * `onMiss === "respond"`, a canned "service unavailable" response is
-     * returned (marked with `metadata.degraded: true`).
-     */
-    readonly respond?: (messages: readonly ChatMessage[], opts?: LLMInvokeOptions) => string | LLMResponse;
-    /** Miss policy. Default `"respond"`. */
-    readonly onMiss?: FallbackMissPolicy;
-    /**
-     * Record mode. Proxies every call to `record.adapter` AND persists the
-     * result through `record.storage`. For filesystem `record.dir` convenience,
-     * use the node subpath's `fallbackAdapter`.
-     */
-    readonly record?: {
-        readonly adapter: LLMAdapter;
-        readonly storage?: KvStorageTier;
-    };
-    /** Stream replay speed multiplier. See {@link withReplayCache}. Default `1`. */
-    readonly replaySpeed?: number;
-    /** Key prefix. Kept compatible with `withReplayCache` defaults. Default `"fallback"`. */
-    readonly keyPrefix?: string;
-    /**
-     * Custom key function — forwarded directly to the underlying
-     * {@link withReplayCache}. Use to shard fixtures by `invokeOpts.keyContext`
-     * (tenant, session, feature flag). Accepts either the new
-     * {@link ReplayCacheKeyContext} object form or the legacy 2-arg
-     * `(messages, opts?)` form.
-     */
-    readonly keyFn?: ((ctx: ReplayCacheKeyContext) => string) | ((messages: readonly ChatMessage[], opts?: LLMInvokeOptions) => string);
-}
-/**
- * Build a fixture-backed {@link LLMAdapter}. See module docs for use cases
- * (offline demo, tests, degraded-mode) and recipe snippets.
- */
-declare function fallbackAdapter(opts?: FallbackAdapterOptions): LLMAdapter;
-
-export { type FallbackAdapterOptions as F, type ReplayCacheKeyContext as R, type WithReplayCacheOptions as W, type FallbackFixture as a, FallbackMissError as b, type FallbackMissPolicy as c, ReplayCacheMissError as d, type ReplayCacheMode as e, canonicalJson as f, fallbackAdapter as g, withReplayCache as w };

package/dist/fallback-Ctlj2tMY.d.cts

@@ -1,250 +0,0 @@
-import { KvStorageTier } from './extra/storage-tiers.cjs';
-import { C as ChatMessage, a as LLMInvokeOptions, L as LLMAdapter, b as LLMResponse, S as StreamDelta } from './types-B1jDWVsM.cjs';
-import { d as canonicalJson$1 } from './content-addressed-storage-4-ST1tYk.cjs';
-
-/**
- * `withReplayCache` — content-addressed response cache over `KvStorageTier`.
- *
- * - Key: sha256 of canonicalized (messages + invoke options minus `signal`).
- * - `"read-write"` (default): returns cached response if present; on miss,
- *   passes through and stores the result.
- * - `"write-only"`: never reads; populates the cache for later runs.
- * - `"read"`: reads only; on miss, passes through without writing.
- * - `"read-strict"`: reads only; on miss, **throws `ReplayCacheMissError`**
- *   instead of passing through. Use for fixture-driven tests or offline
- *   fallback adapters where any cache miss is a test failure or a signal to
- *   degrade.
- *
- * Reuses the library's existing `KvStorageTier` abstraction — any kv tier
- * (memoryKv / fileKv / sqliteKv / indexedDbKv / custom).
- *
- * **Concurrent cache-miss dedup:** uses `singleFromAny` so two concurrent
- * calls with the same key share one upstream request. Second caller sees the
- * same response that the first caller fetched; no duplicate provider spend.
- *
- * **Circular-ref safe:** `canonicalJson` uses a seen-set replacer so
- * user-supplied `ToolDefinition.parameters` with `$ref` cycles don't stack-
- * overflow the key computation.
- *
- * **Stream cadence capture:** when `cacheStreaming: true` AND
- * `captureStreamCadence: true`, per-chunk delays (ms since previous chunk)
- * are recorded alongside the content. Replay honors the recorded cadence
- * unless `replaySpeed` is set, which multiplies the effective per-chunk
- * delay (`replaySpeed: 2` → 2× faster; `replaySpeed: 0` → instant).
- * Without `captureStreamCadence`, replay is instant regardless.
- */
-
-type ReplayCacheMode = "read" | "read-strict" | "write-only" | "read-write";
-declare class ReplayCacheMissError extends Error {
-    readonly key: string;
-    readonly method: "invoke" | "stream";
-    name: string;
-    constructor(key: string, method: "invoke" | "stream");
-}
-/**
- * Context object passed to {@link WithReplayCacheOptions.keyFn}. Extending
- * with additional fields is forward-compatible — current implementations
- * ignoring unknown fields continue to work.
- */
-interface ReplayCacheKeyContext {
-    readonly messages: readonly ChatMessage[];
-    readonly opts: LLMInvokeOptions | undefined;
-    /** Shortcut to `opts?.keyContext` — avoids an extra guard in callers. */
-    readonly context: unknown;
-}
-interface WithReplayCacheOptions {
-    storage: KvStorageTier;
-    mode?: ReplayCacheMode;
-    /**
-     * Custom key function. Receives a {@link ReplayCacheKeyContext} with the
-     * chat messages, the invoke options, and the caller-supplied
-     * `opts.keyContext`. Defaults to sha256 of canonical JSON over
-     * `(messages, opts without signal/keyContext)`.
-     *
-     * Legacy 2-arg form `(messages, opts?)` also accepted — the adapter
-     * detects arity and dispatches. Prefer the object form for new code.
-     */
-    keyFn?: ((ctx: ReplayCacheKeyContext) => string | Promise<string>) | ((messages: readonly ChatMessage[], opts?: LLMInvokeOptions) => string | Promise<string>);
-    /** Prefix for cached keys (useful when sharing a tier across domains). */
-    keyPrefix?: string;
-    /**
-     * Whether to cache streaming responses (by consuming the full stream
-     * and replaying it as one synthetic token chunk). Default `false`.
-     */
-    cacheStreaming?: boolean;
-    /**
-     * When `cacheStreaming: true`, also record per-chunk delays (ms since
-     * previous chunk) so replay can honor the original streaming cadence.
-     * Default `false` (chunks replay instantly).
-     */
-    captureStreamCadence?: boolean;
-    /**
-     * Stream replay speed multiplier. `1` = original cadence (requires
-     * `captureStreamCadence`). `2` = 2× faster. `0` = instant. Default `1`.
-     */
-    replaySpeed?: number;
-}
-/** Wrap an adapter with a replay cache. */
-declare function withReplayCache(inner: LLMAdapter, opts: WithReplayCacheOptions): LLMAdapter;
-/**
- * Canonical JSON — re-exported from `src/extra/content-addressed-storage.ts`
- * so `fallbackAdapter` and other cache-adjacent code that historically
- * imported from here continue to work. Same behavior.
- */
-declare const canonicalJson: typeof canonicalJson$1;
-
-/**
- * `fallbackAdapter` — fixture-backed {@link LLMAdapter} for offline demos,
- * deterministic tests, and graceful degradation in production.
- *
- * A peer of `anthropicAdapter` / `openAICompatAdapter` / `googleAdapter` /
- * `ollamaAdapter` / `dryRunAdapter`, but whose role is to serve pre-recorded
- * or canned responses when real providers aren't reachable. Install it as a
- * tier via the existing routing primitives (no new composer needed):
- *
- * ```ts
- * // Graceful offline fallback for a user app:
- * resilientAdapter(anthropicAdapter({ ... }), {
- *   fallback: fallbackAdapter({ fixturesDir: "./fixtures" }),
- * });
- *
- * // Or the general N-tier shape:
- * cascadingLlmAdapter([
- *   { name: "primary",  adapter: anthropicAdapter({ ... }) },
- *   { name: "fallback", adapter: fallbackAdapter({ fixturesDir: "./fixtures" }) },
- * ]);
- * ```
- *
- * The `provider` field is `"fallback"` so its role is self-documenting in
- * logs, stats, cost tables, and audit trails.
- *
- * ## Three fixture sources (mutually exclusive)
- *
- * Pick exactly one of:
- *
- * 1. **`fixtures: FallbackFixture[]`** — inline, hand-authored. Supports
- *    both hash-keyed and messages-keyed shapes; the adapter computes the
- *    canonical hash for messages-keyed entries at init time. Ideal when you
- *    want full control in code (tests, small demos).
- *
- * 2. **`fixturesStorage: KvStorageTier`** — the escape hatch for any backend.
- *    Pass a `memoryKv()`, `indexedDbKv(...)`, `sqliteKv(...)`,
- *    `cascadingCache(...)`, or a custom tier. You own the layout — no
- *    auto-namespacing.
- *
- *    **Filesystem directories (Node only):** the core `fallbackAdapter`
- *    does NOT import `node:fs` / `node:path` — it's safe to bundle for
- *    browsers. For a directory convenience, import `fallbackAdapter` from
- *    `@graphrefly/graphrefly/patterns/ai/node` (node subpath);
- *    that variant adds `fixturesDir: string` (auto-namespaced to
- *    `join(dir, keyPrefix)`, cache-format validated at init).
- *
- * ## Record mode
- *
- * `record: { adapter: real, storage }` proxies every call to `real` AND
- * persists the response through the provided tier. Use the node subpath's
- * `fallbackAdapter` for `record.dir` (auto-namespaced + `record.dir` defaults
- * to `fixturesDir` when both are file-backed).
- *
- * ## Three use cases, one implementation
- *
- * | Use case | Config |
- * |---|---|
- * | **User apps** — degrade when the cloud provider errors or network is down | `fallbackAdapter({ fixturesStorage: ... })` installed as a fallback tier |
- * | **Tests** — deterministic replays, fail loudly on miss | `fallbackAdapter({ fixturesStorage: ..., onMiss: "throw" })` |
- * | **Eval offline replay** — zero-spend repeat runs | `fallbackAdapter({ fixturesStorage: ... })` as the only adapter |
- *
- * ## Implementation
- *
- * Thin sugar over {@link withReplayCache}. Key shape comes from its
- * `canonicalJson` — fixtures written by either tool are interchangeable.
- *
- * @module
- */
-
-type FallbackMissPolicy = "throw" | "respond";
-/**
- * Thrown when `fallbackAdapter({ onMiss: "throw" })` receives a request that
- * has no matching fixture. Alias of `ReplayCacheMissError` for now — the
- * adapter is a thin sugar over `withReplayCache` and shares its miss-error.
- */
-declare const FallbackMissError: typeof ReplayCacheMissError;
-type FallbackMissError = ReplayCacheMissError;
-/**
- * One recorded fixture. Two authoring shapes:
- * - **Hash-keyed** — `{ key, response, stream? }`. Key is `sha256(canonicalJson({messages, opts}))`
- *   with `fallback:` prefix. This is what `record` mode writes.
- * - **Messages-keyed** — `{ messages, invokeOpts?, response }`. The adapter
- *   computes the key at init time. Ergonomic for hand-authored fixtures.
- */
-type FallbackFixture = {
-    readonly key: string;
-    readonly response: LLMResponse;
-    readonly stream?: {
-        readonly chunks: readonly StreamDelta[];
-        readonly delaysMs?: readonly number[];
-    };
-} | {
-    readonly messages: readonly ChatMessage[];
-    readonly invokeOpts?: Omit<LLMInvokeOptions, "signal">;
-    readonly response: LLMResponse;
-};
-interface FallbackAdapterOptions {
-    /** Adapter provider label. Default `"fallback"`. */
-    readonly provider?: string;
-    /** Adapter model label. Default `"fallback"`. */
-    readonly model?: string;
-    /**
-     * Inline hand-authored fixtures. Supports both hash-keyed (`{key, response, stream?}`)
-     * and messages-keyed (`{messages, invokeOpts?, response}`) shapes — the adapter
-     * computes the canonical hash for messages-keyed entries at init time. Held in
-     * an internal `memoryKv`. Mutually exclusive with `fixturesDir` and
-     * `fixturesStorage`.
-     */
-    readonly fixtures?: readonly FallbackFixture[];
-    /**
-     * Bring-your-own `KvStorageTier` (`memoryKv`, `sqliteKv`,
-     * `indexedDbKv`, `cascadingCache`, or a custom tier). You own the
-     * layout — no auto-namespacing. Mutually exclusive with `fixtures`.
-     *
-     * For filesystem directories, use the node subpath's `fallbackAdapter`
-     * with its `fixturesDir` option (auto-namespaced + validated).
-     */
-    readonly fixturesStorage?: KvStorageTier;
-    /**
-     * Called on fixture miss when `onMiss === "respond"`. If not provided and
-     * `onMiss === "respond"`, a canned "service unavailable" response is
-     * returned (marked with `metadata.degraded: true`).
-     */
-    readonly respond?: (messages: readonly ChatMessage[], opts?: LLMInvokeOptions) => string | LLMResponse;
-    /** Miss policy. Default `"respond"`. */
-    readonly onMiss?: FallbackMissPolicy;
-    /**
-     * Record mode. Proxies every call to `record.adapter` AND persists the
-     * result through `record.storage`. For filesystem `record.dir` convenience,
-     * use the node subpath's `fallbackAdapter`.
-     */
-    readonly record?: {
-        readonly adapter: LLMAdapter;
-        readonly storage?: KvStorageTier;
-    };
-    /** Stream replay speed multiplier. See {@link withReplayCache}. Default `1`. */
-    readonly replaySpeed?: number;
-    /** Key prefix. Kept compatible with `withReplayCache` defaults. Default `"fallback"`. */
-    readonly keyPrefix?: string;
-    /**
-     * Custom key function — forwarded directly to the underlying
-     * {@link withReplayCache}. Use to shard fixtures by `invokeOpts.keyContext`
-     * (tenant, session, feature flag). Accepts either the new
-     * {@link ReplayCacheKeyContext} object form or the legacy 2-arg
-     * `(messages, opts?)` form.
-     */
-    readonly keyFn?: ((ctx: ReplayCacheKeyContext) => string) | ((messages: readonly ChatMessage[], opts?: LLMInvokeOptions) => string);
-}
-/**
- * Build a fixture-backed {@link LLMAdapter}. See module docs for use cases
- * (offline demo, tests, degraded-mode) and recipe snippets.
- */
-declare function fallbackAdapter(opts?: FallbackAdapterOptions): LLMAdapter;
-
-export { type FallbackAdapterOptions as F, type ReplayCacheKeyContext as R, type WithReplayCacheOptions as W, type FallbackFixture as a, FallbackMissError as b, type FallbackMissPolicy as c, ReplayCacheMissError as d, type ReplayCacheMode as e, canonicalJson as f, fallbackAdapter as g, withReplayCache as w };