@graphrefly/graphrefly 0.34.0 → 0.35.0

package/dist/extra/storage-tiers.d.ts

@@ -0,0 +1,284 @@
+/**
+ * Storage tier architecture (Audit 4 — locked 2026-04-24).
+ *
+ * Three-layer design:
+ *
+ * - **Layer 1 — {@link StorageBackend}:** generic bytes-level kv I/O. One
+ *   `read(key) → Uint8Array | undefined`, `write(key, bytes)`, optional
+ *   `delete(key)` / `list(prefix)`. No tier-level concerns (debounce, codec).
+ * - **Layer 2 — Tier specializations** layered over a backend, parametric over
+ *   `T`: {@link SnapshotStorageTier} (one snapshot under one key) and
+ *   {@link AppendLogStorageTier} (sequential entries, optional partition via
+ *   `keyOf`). Both extend {@link BaseStorageTier} which carries
+ *   `flush?` / `rollback?` for the wave-as-transaction model.
+ * - **Layer 3 — High-level wiring:** `Graph.attachSnapshotStorage(tiers)`,
+ *   `reactiveLog.attachStorage(tiers)`, `cqrsGraph.attachEventStorage(tiers)`,
+ *   `jobQueueGraph.attachEventStorage(tiers)`. These layers consume tier
+ *   specializations directly — they don't see the backend.
+ *
+ * Browser-safe by default. {@link memoryBackend} + the in-memory factories
+ * live here; Node-only (`fileBackend` / `sqliteBackend`) lives in
+ * `extra/storage-node.ts`; browser-only (`indexedDbBackend`) lives in
+ * `extra/storage-browser.ts`.
+ *
+ * @module
+ */
+/**
+ * Bytes-level kv backend. One responsibility: read/write byte ranges under
+ * string keys. Tier specializations layer on top.
+ *
+ * @category extra
+ */
+interface StorageBackend {
+    /** Diagnostic name (e.g., `"memory"`, `"file:./checkpoints"`). */
+    readonly name: string;
+    /** Read raw bytes; returns `undefined` on miss. */
+    read(key: string): Uint8Array | undefined | Promise<Uint8Array | undefined>;
+    /** Write raw bytes. Sync backends return `void`; async return `Promise<void>`. */
+    write(key: string, bytes: Uint8Array): void | Promise<void>;
+    /** Optional delete-by-key. */
+    delete?(key: string): void | Promise<void>;
+    /** Optional enumeration; `prefix` filters keys. */
+    list?(prefix?: string): readonly string[] | Promise<readonly string[]>;
+    /** Optional drain hook — adapter authors implement when buffering writes. */
+    flush?(): Promise<void>;
+}
+/**
+ * Codec for tier serialization. Tiers call `encode(value) → bytes` before
+ * `backend.write` and `decode(bytes) → value` after `backend.read`.
+ *
+ * @category extra
+ */
+interface Codec<T = unknown> {
+    readonly name: string;
+    readonly version: number;
+    encode(value: T): Uint8Array;
+    decode(bytes: Uint8Array): T;
+}
+/**
+ * Default JSON codec — UTF-8 text, stable key order (via `stableJsonString`).
+ * Any value JSON-serializable is supported.
+ *
+ * @category extra
+ */
+declare const jsonCodec: Codec<unknown>;
+/** Build a `Codec<T>` over the default JSON encoding. Pure typing helper. */
+declare function jsonCodecFor<T>(): Codec<T>;
+/**
+ * Common tier surface: name + cadence knobs + transaction lifecycle.
+ *
+ * Lifecycle hooks (`flush` / `rollback`) implement Audit 4's "one wave = one
+ * transaction" model. Framework integration:
+ *  - After every wave (and on `batch()` close), framework iterates attached
+ *    tiers and calls `tier.flush()` if exposed.
+ *  - On wave-throw (per C.2 F rollback policy), framework calls
+ *    `tier.rollback()` if exposed — pending writes discarded.
+ *  - Cross-tier atomicity is best-effort. Each tier is its own transaction.
+ *
+ * @category extra
+ */
+interface BaseStorageTier {
+    readonly name: string;
+    /** Debounce window (ms). `0` = sync-through; >0 batches across waves. */
+    readonly debounceMs?: number;
+    /** Force flush every Nth write regardless of debounce. */
+    readonly compactEvery?: number;
+    /** Commit pending; framework calls at wave-close / debounce-fire. */
+    flush?(): Promise<void>;
+    /** Discard pending; framework calls on wave-throw. */
+    rollback?(): Promise<void>;
+}
+/**
+ * Snapshot tier — writes a single record per `save(snapshot)` call.
+ *
+ * The tier maps the snapshot to a backend key via `keyOf(snapshot)` (default
+ * `() => name ?? "snapshot"`). For `Graph.attachSnapshotStorage`, the framework
+ * supplies a closure that pulls the graph name out of the record envelope.
+ *
+ * @category extra
+ */
+interface SnapshotStorageTier<T = unknown> extends BaseStorageTier {
+    save(snapshot: T): void | Promise<void>;
+    load?(): T | Promise<T | undefined> | undefined;
+    /** Skip-save policy — return `false` to skip persisting this snapshot. */
+    filter?: (snapshot: T) => boolean;
+    /** Extract the backend key per-snapshot; default `() => name ?? "snapshot"`. */
+    keyOf?: (snapshot: T) => string;
+}
+/**
+ * Append-log tier — bulk-friendly entry persistence with optional partitioning.
+ *
+ * Entries are appended to a logical stream; `keyOf?` partitions across backend
+ * keys (e.g., `(e) => `${e.type}::${e.aggregateId}`` for CQRS).
+ *
+ * @category extra
+ */
+interface AppendLogStorageTier<T = unknown> extends BaseStorageTier {
+    appendEntries(entries: readonly T[]): void | Promise<void>;
+    loadEntries?(opts?: {
+        cursor?: AppendCursor;
+        pageSize?: number;
+        keyFilter?: string;
+    }): AppendLoadResult<T> | Promise<AppendLoadResult<T>>;
+    /** Partition key per-entry (default `() => name ?? "append-log"`). */
+    keyOf?: (entry: T) => string;
+}
+/** Opaque cursor for windowed `loadEntries` pagination. */
+type AppendCursor = Readonly<{
+    position: number;
+    tag?: string;
+}> & {
+    readonly __brand: "AppendCursor";
+};
+type AppendLoadResult<T> = {
+    entries: readonly T[];
+    cursor: AppendCursor | undefined;
+};
+/**
+ * In-process bytes backend backed by `Map<string, Uint8Array>`. Useful for
+ * tests, hot tiers, and as a default for the convenience factories below.
+ *
+ * @category extra
+ */
+declare function memoryBackend(): StorageBackend;
+type SnapshotStorageOptions<T> = {
+    name?: string;
+    codec?: Codec<T>;
+    debounceMs?: number;
+    compactEvery?: number;
+    filter?: (snapshot: T) => boolean;
+    keyOf?: (snapshot: T) => string;
+};
+/**
+ * Wrap a {@link StorageBackend} as a typed snapshot tier.
+ *
+ * Buffer model: `save(snapshot)` accumulates one pending snapshot in memory.
+ * `flush()` encodes via codec and writes to the backend under
+ * `keyOf(snapshot)` (default `name ?? "snapshot"`). `rollback()` discards
+ * the pending write.
+ *
+ * @category extra
+ */
+declare function snapshotStorage<T>(backend: StorageBackend, opts?: SnapshotStorageOptions<T>): SnapshotStorageTier<T>;
+type AppendLogStorageOptions<T> = {
+    name?: string;
+    codec?: Codec<readonly T[]>;
+    keyOf?: (entry: T) => string;
+    debounceMs?: number;
+    compactEvery?: number;
+};
+/**
+ * Wrap a {@link StorageBackend} as a typed append-log tier.
+ *
+ * Buffer model: `appendEntries(entries)` accumulates per-key buckets in
+ * memory. `flush()` encodes each bucket as a JSON array via codec and writes
+ * under that bucket key. `rollback()` discards pending appends.
+ *
+ * Storage shape: each backend key holds a JSON array of all entries for that
+ * partition, growing on every flush. Adapters that need true append semantics
+ * (versus rewrite) should layer their own tier impl over the same backend.
+ *
+ * @category extra
+ */
+declare function appendLogStorage<T>(backend: StorageBackend, opts?: AppendLogStorageOptions<T>): AppendLogStorageTier<T>;
+/**
+ * Key-value tier — typed records under arbitrary string keys with codec
+ * serialization at the storage-tier boundary. Use for content-addressed
+ * caches (replay), multi-record archives (snapshot index, AI memory), and
+ * fixture stores. Snapshot tier is "one record"; append-log is "sequential
+ * entries"; kv is "many records, addressable by key".
+ *
+ * @category extra
+ */
+interface KvStorageTier<T = unknown> extends BaseStorageTier {
+    load(key: string): T | undefined | Promise<T | undefined>;
+    save(key: string, value: T): void | Promise<void>;
+    delete?(key: string): void | Promise<void>;
+    list?(prefix?: string): readonly string[] | Promise<readonly string[]>;
+    /** Pre-save filter — return `false` to skip persisting this record. */
+    filter?: (key: string, value: T) => boolean;
+}
+type KvStorageOptions<T> = {
+    name?: string;
+    codec?: Codec<T>;
+    debounceMs?: number;
+    compactEvery?: number;
+    filter?: (key: string, value: T) => boolean;
+};
+/**
+ * Wrap a {@link StorageBackend} as a typed kv tier.
+ *
+ * Buffer model: `save(k, v)` encodes via codec and writes to the backend
+ * unless debounced. Pending writes are committed on `flush()` and discarded
+ * on `rollback()` — the wave-as-transaction model.
+ *
+ * @category extra
+ */
+declare function kvStorage<T>(backend: StorageBackend, opts?: KvStorageOptions<T>): KvStorageTier<T>;
+/**
+ * In-memory snapshot tier — `snapshotStorage(memoryBackend(), opts)`.
+ *
+ * @category extra
+ */
+declare function memorySnapshot<T>(opts?: Omit<SnapshotStorageOptions<T>, "name"> & {
+    name?: string;
+}): SnapshotStorageTier<T>;
+/**
+ * In-memory append-log tier — `appendLogStorage(memoryBackend(), opts)`.
+ *
+ * @category extra
+ */
+declare function memoryAppendLog<T>(opts?: Omit<AppendLogStorageOptions<T>, "name"> & {
+    name?: string;
+}): AppendLogStorageTier<T>;
+/**
+ * In-memory kv tier — `kvStorage(memoryBackend(), opts)`.
+ *
+ * @category extra
+ */
+declare function memoryKv<T>(opts?: Omit<KvStorageOptions<T>, "name"> & {
+    name?: string;
+}): KvStorageTier<T>;
+/**
+ * Dict-backed kv tier — wraps a caller-owned plain object as a
+ * {@link StorageBackend} and returns a kv tier over it. Useful for
+ * embedding in a parent state shape or for tests that need access to the
+ * raw bytes.
+ *
+ * The dict stores raw encoded bytes as `Uint8Array`. Use `opts.name` to
+ * control the tier's diagnostic name (defaults to `"dict-kv"`).
+ *
+ * @example
+ * ```ts
+ * const store: Record<string, Uint8Array> = {};
+ * const tier = dictKv<MyRecord>(store);
+ * await tier.save("key1", myRecord);
+ * ```
+ *
+ * @category extra
+ */
+declare function dictKv<T>(storage: Record<string, Uint8Array>, opts?: Omit<KvStorageOptions<T>, "name"> & {
+    name?: string;
+}): KvStorageTier<T>;
+/**
+ * Dict-backed snapshot tier — wraps a caller-owned plain object as a
+ * {@link StorageBackend} and returns a snapshot tier over it. Useful for
+ * embedding checkpoints inside a parent state shape or for tests that need
+ * access to the raw bytes.
+ *
+ * The dict stores raw JSON bytes as `Uint8Array`. Use `opts.name` to control
+ * the storage key (defaults to `"snapshot"`).
+ *
+ * @example
+ * ```ts
+ * const store: Record<string, Uint8Array> = {};
+ * graph.attachSnapshotStorage([dictSnapshot(store, { name: graph.name })]);
+ * ```
+ *
+ * @category extra
+ */
+declare function dictSnapshot<T>(storage: Record<string, Uint8Array>, opts?: Omit<SnapshotStorageOptions<T>, "name"> & {
+    name?: string;
+}): SnapshotStorageTier<T>;
+
+export { type AppendCursor, type AppendLoadResult, type AppendLogStorageOptions, type AppendLogStorageTier, type BaseStorageTier, type Codec, type KvStorageOptions, type KvStorageTier, type SnapshotStorageOptions, type SnapshotStorageTier, type StorageBackend, appendLogStorage, dictKv, dictSnapshot, jsonCodec, jsonCodecFor, kvStorage, memoryAppendLog, memoryBackend, memoryKv, memorySnapshot, snapshotStorage };

package/dist/extra/storage-tiers.js

@@ -0,0 +1 @@
+import{a,b,c,d,e,f,g,h,i,j,k}from"../chunk-D5RFJOZ2.js";import"../chunk-CE72X3WO.js";import"../chunk-QYADASLV.js";export{e as appendLogStorage,j as dictKv,k as dictSnapshot,a as jsonCodec,b as jsonCodecFor,f as kvStorage,h as memoryAppendLog,c as memoryBackend,i as memoryKv,g as memorySnapshot,d as snapshotStorage};

package/dist/{fallback-mYSd8vQo.d.ts → fallback-DuEXfA4F.d.ts}

@@ -1,9 +1,9 @@
-import { StorageTier } from './extra/storage-core.js';
-import { C as ChatMessage, a as LLMInvokeOptions, L as LLMAdapter, b as LLMResponse, S as StreamDelta } from './types-B2LfBvNc.js';
-import { d as canonicalJson$1 } from './content-addressed-storage-BUiREIuj.js';
+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-CidcBDuk.js';
+import { d as canonicalJson$1 } from './content-addressed-storage-DuYMjV7o.js';
 
 /**
- * `withReplayCache` — content-addressed response cache over `StorageTier`.
+ * `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,
@@ -15,8 +15,8 @@ import { d as canonicalJson$1 } from './content-addressed-storage-BUiREIuj.js';
  *   fallback adapters where any cache miss is a test failure or a signal to
  *   degrade.
  *
- * Reuses the library's existing `StorageTier` abstraction — the same tiers
- * that power `Graph.attachStorage` (memory / file / sqlite / indexeddb / custom).
+ * 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
@@ -53,7 +53,7 @@ interface ReplayCacheKeyContext {
     readonly context: unknown;
 }
 interface WithReplayCacheOptions {
-    storage: StorageTier;
+    storage: KvStorageTier;
     mode?: ReplayCacheMode;
     /**
      * Custom key function. Receives a {@link ReplayCacheKeyContext} with the
@@ -127,8 +127,8 @@ declare const canonicalJson: typeof canonicalJson$1;
  *    canonical hash for messages-keyed entries at init time. Ideal when you
  *    want full control in code (tests, small demos).
  *
- * 2. **`fixturesStorage: StorageTier`** — the escape hatch for any backend.
- *    Pass a `memoryStorage()`, `indexedDbStorage(...)`, `sqliteStorage(...)`,
+ * 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.
  *
@@ -198,19 +198,19 @@ interface FallbackAdapterOptions {
      * 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 `memoryStorage`. Mutually exclusive with `fixturesDir` and
+     * an internal `memoryKv`. Mutually exclusive with `fixturesDir` and
      * `fixturesStorage`.
      */
     readonly fixtures?: readonly FallbackFixture[];
     /**
-     * Bring-your-own `StorageTier` (`memoryStorage`, `sqliteStorage`,
-     * `indexedDbStorage`, `cascadingCache`, or a custom tier). You own the
+     * 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?: StorageTier;
+    readonly fixturesStorage?: KvStorageTier;
     /**
      * Called on fixture miss when `onMiss === "respond"`. If not provided and
      * `onMiss === "respond"`, a canned "service unavailable" response is
@@ -226,7 +226,7 @@ interface FallbackAdapterOptions {
      */
     readonly record?: {
         readonly adapter: LLMAdapter;
-        readonly storage?: StorageTier;
+        readonly storage?: KvStorageTier;
     };
     /** Stream replay speed multiplier. See {@link withReplayCache}. Default `1`. */
     readonly replaySpeed?: number;

package/dist/{fallback-9YznPvPP.d.cts → fallback-axI2cXwt.d.cts}

@@ -1,9 +1,9 @@
-import { StorageTier } from './extra/storage-core.cjs';
-import { C as ChatMessage, a as LLMInvokeOptions, L as LLMAdapter, b as LLMResponse, S as StreamDelta } from './types-Cp_4coR_.cjs';
-import { d as canonicalJson$1 } from './content-addressed-storage-DqIWCmZG.cjs';
+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-BMSGPlpO.cjs';
+import { d as canonicalJson$1 } from './content-addressed-storage-4-ST1tYk.cjs';
 
 /**
- * `withReplayCache` — content-addressed response cache over `StorageTier`.
+ * `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,
@@ -15,8 +15,8 @@ import { d as canonicalJson$1 } from './content-addressed-storage-DqIWCmZG.cjs';
  *   fallback adapters where any cache miss is a test failure or a signal to
  *   degrade.
  *
- * Reuses the library's existing `StorageTier` abstraction — the same tiers
- * that power `Graph.attachStorage` (memory / file / sqlite / indexeddb / custom).
+ * 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
@@ -53,7 +53,7 @@ interface ReplayCacheKeyContext {
     readonly context: unknown;
 }
 interface WithReplayCacheOptions {
-    storage: StorageTier;
+    storage: KvStorageTier;
     mode?: ReplayCacheMode;
     /**
      * Custom key function. Receives a {@link ReplayCacheKeyContext} with the
@@ -127,8 +127,8 @@ declare const canonicalJson: typeof canonicalJson$1;
  *    canonical hash for messages-keyed entries at init time. Ideal when you
  *    want full control in code (tests, small demos).
  *
- * 2. **`fixturesStorage: StorageTier`** — the escape hatch for any backend.
- *    Pass a `memoryStorage()`, `indexedDbStorage(...)`, `sqliteStorage(...)`,
+ * 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.
  *
@@ -198,19 +198,19 @@ interface FallbackAdapterOptions {
      * 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 `memoryStorage`. Mutually exclusive with `fixturesDir` and
+     * an internal `memoryKv`. Mutually exclusive with `fixturesDir` and
      * `fixturesStorage`.
      */
     readonly fixtures?: readonly FallbackFixture[];
     /**
-     * Bring-your-own `StorageTier` (`memoryStorage`, `sqliteStorage`,
-     * `indexedDbStorage`, `cascadingCache`, or a custom tier). You own the
+     * 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?: StorageTier;
+    readonly fixturesStorage?: KvStorageTier;
     /**
      * Called on fixture miss when `onMiss === "respond"`. If not provided and
      * `onMiss === "respond"`, a canned "service unavailable" response is
@@ -226,7 +226,7 @@ interface FallbackAdapterOptions {
      */
     readonly record?: {
         readonly adapter: LLMAdapter;
-        readonly storage?: StorageTier;
+        readonly storage?: KvStorageTier;
     };
     /** Stream replay speed multiplier. See {@link withReplayCache}. Default `1`. */
     readonly replaySpeed?: number;