@graphrefly/ts 0.0.0

package/dist/reactive-collection-Cb1II1Fi.d.ts

@@ -0,0 +1,344 @@
+import { N as Node, D as Dispatcher } from './types-h12mNYbq.js';
+import { d as Graph } from './graph-DfdF9zy4.js';
+import { f as KvStorageTier, d as AppendLogStorageTier } from './append-log-DzKMmjxx.js';
+import { C as Codec } from './codec-BB7p8fJc.js';
+
+/**
+ * Public policy vocabulary (D80): shared option shapes only.
+ *
+ * Runtime policy mechanics stay structure-owned: each reactive collection still owns
+ * backend mutation, victim application, delta emission, and graph-bound node-as-opt wiring.
+ */
+type ReactiveOpt<T> = T | Node<T>;
+/** Capacity vocabulary shared by structures that bound retained entries. */
+interface CapacityPolicy<Order extends string = never> {
+    readonly maxSize: ReactiveOpt<number>;
+    readonly order?: Order;
+}
+/** Capacity policy variant for structures whose eviction order must be explicit. */
+type OrderedCapacityPolicy<Order extends string> = CapacityPolicy<Order> & {
+    readonly order: Order;
+};
+/** Score-based retention vocabulary; higher scores are retained. */
+interface RetentionPolicy<Entry> {
+    readonly maxSize?: ReactiveOpt<number>;
+    score(entry: Entry): number;
+}
+/**
+ * Static view-cache vocabulary for memoized helper nodes.
+ *
+ * This is intentionally not a release/keepalive API: eviction may drop the structure's
+ * memo reference, but externally held Node views remain valid.
+ */
+interface ViewCachePolicy {
+    readonly maxEntries?: number;
+}
+
+/**
+ * Delta-event payloads for the reactive data structures (CSP-2.8, D54/D60).
+ *
+ * Each reactive structure has a DELTA port (an always-on push stream, D60) that emits ONE of
+ * these change payloads per mutation (O(1)/mutation). The SNAPSHOT port (a lazy pull-mode node)
+ * carries the materialized state instead — see {@link collectionCore}. These are the structure-
+ * specific verbs; the delta stream emits the raw payload (no envelope — version/timestamp/audit
+ * framing is a storage concern, D57, layered separately if needed).
+ *
+ * Per-language (D6/D24, never in parity, no conformance). Canonical authority:
+ * ~/src/graphrefly/decisions/decisions.jsonl D54/D60.
+ */
+/** List structure delta events. */
+type ListChange<T> = {
+    readonly kind: "append";
+    readonly value: T;
+} | {
+    readonly kind: "appendMany";
+    readonly values: readonly T[];
+} | {
+    readonly kind: "insert";
+    readonly index: number;
+    readonly value: T;
+} | {
+    readonly kind: "insertMany";
+    readonly index: number;
+    readonly values: readonly T[];
+} | {
+    readonly kind: "pop";
+    readonly index: number;
+    readonly value: T;
+} | {
+    readonly kind: "trimHead";
+    readonly n: number;
+} | {
+    readonly kind: "clear";
+    readonly count: number;
+};
+/**
+ * Map structure delta events. `delete.reason` distinguishes the four delete sources (D60 #3c):
+ * an explicit `.delete`, a TTL `expired` read-prune, an `lru-evict` under `maxSize`, or an
+ * `archived` retention sweep.
+ */
+type MapChange<K, V> = {
+    readonly kind: "set";
+    readonly key: K;
+    readonly value: V;
+} | {
+    readonly kind: "delete";
+    readonly key: K;
+    readonly previous: V;
+    readonly reason: "expired" | "lru-evict" | "archived" | "explicit";
+} | {
+    readonly kind: "clear";
+    readonly count: number;
+};
+/** Dual-key index structure delta events. */
+type IndexChange<K, V> = {
+    readonly kind: "upsert";
+    readonly primary: K;
+    readonly secondary: unknown;
+    readonly value: V;
+} | {
+    readonly kind: "delete";
+    readonly primary: K;
+} | {
+    readonly kind: "deleteMany";
+    readonly primaries: readonly K[];
+} | {
+    readonly kind: "clear";
+    readonly count: number;
+};
+/** Append-only log structure delta events. */
+type LogChange<T> = {
+    readonly kind: "append";
+    readonly value: T;
+} | {
+    readonly kind: "appendMany";
+    readonly values: readonly T[];
+} | {
+    readonly kind: "clear";
+    readonly count: number;
+} | {
+    readonly kind: "trimHead";
+    readonly n: number;
+};
+
+/**
+ * The shared reactiveCollection core (CSP-2.8, D60).
+ *
+ * Every reactive data structure (list/map/index/log) is `collectionCore(backend) + a typed method
+ * surface` (D60 #5). The core owns the TWO output ports and nothing else:
+ *
+ *   - BACKEND — the single materialized state (D60 #1): a plain mutable object with a monotonic
+ *     `version` + a `snapshot()`. It applies deltas and IS the materialized state; there is NO ACC
+ *     node and NO effect bridge re-deriving it (the misdesign D60 rejected — the backend already
+ *     integrates, its cost is intrinsic). The backend is a closure object, not a graph node, so its
+ *     durability is structural (survives last-subscriber disconnect; node ROM/RAM is moot, D60 #1).
+ *
+ *   - DELTA port (D60 #2a) — an always-on bare source ({@link CollectionCore.delta}); each mutation
+ *     pushes ONE change payload (O(1)/mutation). Downstream watches events anytime. It is the
+ *     structure's BACKBONE: the snapshot node declares it as its dep (D60 reactiveList topology).
+ *
+ *   - SNAPSHOT port (D60 #2b) — a pull-mode node ({@link CollectionCore.snapshot}, R-pull/D59) that
+ *     is QUIET by default and, on a cone-routed RESUME demand, LAZILY reads `backend.snapshot()`
+ *     (one O(n) materialization) and pushes it once, then re-quiets. The O(n) build happens ONLY on
+ *     demand — never eagerly per mutation (D60 #2b: lazy is P·O(n), not M·O(n)). It has NO value of
+ *     its own — its fn reads the backend on demand, so the backend stays the single source of truth
+ *     (D60 #3). Coalesce-on-no-change is free: the delta-dep's DIRTY/DATA arms the pull node via
+ *     R-pull's quiet-absorb accounting; a demand with no intervening delta is silent (C-16).
+ *
+ * Demand path: a downstream consumer issues `ctx.upNext([[RESUME, core.pullId]])` (boundary-deferred
+ * self-demand, R-up-routing/D59) — it needs the snapshot node upstream in its declared cone, NOT its
+ * reference. Cold-start (a demand before any mutation) is silent by substrate coalesce (C-16); for an
+ * initial/imperative read use the structure's synchronous quick-read (the deliberately-non-reactive
+ * peek, D60) — the reactive pull serves the watch-delta-then-demand pattern.
+ *
+ * Per-language (D6/D24, never in parity, no conformance — the substrate pull is already C-16).
+ */
+
+interface CollectionCoreOptions {
+    /** Debug/inspection name; the delta/snapshot nodes derive `${name}.delta` / `${name}.snapshot`. */
+    name?: string;
+    /** Dispatcher for the core's nodes (default = process-global, D26). */
+    dispatcher?: Dispatcher;
+    /** Graph funnel for describe-visible input folds (D61). Required by *From/attach methods. */
+    graph?: Graph;
+}
+/**
+ * Public D121 collection-view surface. A view is a derived surface: `delta` is the pushed update
+ * port, `snapshot` is a lazy pull node, and neither port is writable authority.
+ */
+interface ReactiveView<C, S> {
+    /** Derived DELTA/update stream for the view. For light views this is recomputed from the parent backend. */
+    readonly delta: Node<C>;
+    /** Derived SNAPSHOT pull node: demand via `pullId` to materialize the current view. */
+    readonly snapshot: Node<S>;
+    /** The snapshot node's pullId (R-pull/D59), minted per view instance. */
+    readonly pullId: symbol;
+    /** Release memoized/light-view resources owned by the parent collection. */
+    dispose(): void;
+}
+
+/**
+ * Reactive dual-key index (CSP-2.8, D54/D60) — unique primary key, rows sorted by (secondary, primary).
+ *
+ * Shape = the shared {@link collectionCore} two ports over a sorted-array + parallel-Map BACKEND
+ * (D60). The SNAPSHOT port delivers the ordered `IndexRow[]`. Secondary/reverse lookup = "Z"
+ * (review #4): `has`/`get`/`rangeByPrimary` are SYNCHRONOUS point-reads over the backend's parallel
+ * Map (NOT topology, like `.cache`); `byPrimary` is an OPTIONAL reactive derived over the delta
+ * backbone (a pushed primary→value map), LAZILY created on first access (no default keepalive,
+ * R-rom-ram). The two coexist: the derived is the reactive reverse-lookup port; the sync reads are
+ * the point query.
+ *
+ * Per-language (D6/D24, never in parity, no conformance — the substrate pull is already C-16).
+ */
+
+type ReactiveIndexOpt<T> = ReactiveOpt<T>;
+type ReactiveIndexCapacityOrder = "secondary" | "primary" | "lru";
+interface ReactiveIndexCapacityPolicy extends OrderedCapacityPolicy<ReactiveIndexCapacityOrder> {
+}
+interface ReactiveIndexOptions extends CollectionCoreOptions {
+    /**
+     * D73 explicit capacity policy: no implicit eviction default.
+     * `order` chooses eviction semantics and `maxSize` may be static or node-valued (D68).
+     */
+    readonly capacity?: ReactiveIndexCapacityPolicy;
+    /** Static D80 memo policy for D121 light views. Eviction does not dispose returned views. */
+    readonly viewCache?: ViewCachePolicy;
+}
+interface IndexRow<K, V = unknown> {
+    readonly primary: K;
+    readonly secondary: unknown;
+    readonly value: V;
+}
+interface ReactiveIndex<K, V = unknown> {
+    readonly delta: Node<IndexChange<K, V>>;
+    /** SNAPSHOT pull node: demand → rows sorted by (secondary, primary) (lazy O(n)). */
+    readonly snapshot: Node<readonly IndexRow<K, V>[]>;
+    readonly pullId: symbol;
+    /** Row count (O(1)). Sync non-reactive read. */
+    readonly size: number;
+    /** O(1) primary-key existence. Sync read (Z). */
+    has(primary: K): boolean;
+    /** O(1) value lookup by primary key. Sync read (Z). */
+    get(primary: K): V | undefined;
+    /** Values whose primary sorts within `[start, end)`, ascending primary order. Sync read (Z). */
+    rangeByPrimary(start: K, end: K): V[];
+    /**
+     * D121 light range view over the primary axis. `delta` forwards parent index mutations, and
+     * `snapshot` is a pull node that materializes the current range on demand.
+     */
+    range(start: K, end: K): ReactiveView<IndexChange<K, V>, readonly V[]>;
+    /** Ordered rows (fresh copy). Sync non-reactive read (cold-start peek). */
+    toArray(): readonly IndexRow<K, V>[];
+    /** Primary→value map (fresh copy). Sync non-reactive read. */
+    toPrimaryMap(): ReadonlyMap<K, V>;
+    /**
+     * OPTIONAL reactive reverse-lookup port (Z): a derived primary→value map, pushed on every
+     * mutation. Lazily created on first access (no keepalive — live only while subscribed). Use the
+     * synchronous {@link ReactiveIndex.get} for a one-shot point query.
+     */
+    readonly byPrimary: Node<ReadonlyMap<K, V>>;
+    /** Insert/replace a row. Returns `true` if a NEW row was inserted (primary was absent). */
+    upsert(primary: K, secondary: unknown, value: V): boolean;
+    /** Bulk upsert; one delta per row. No-op if empty. */
+    upsertMany(rows: Iterable<{
+        primary: K;
+        secondary: unknown;
+        value: V;
+    }>): void;
+    delete(primary: K): void;
+    /** Bulk delete; one delta event. No-op if nothing removed. */
+    deleteMany(primaries: Iterable<K>): void;
+    clear(): void;
+    /** D54 widening: every row from `src` is upserted. Returns a disposer. */
+    upsertFrom(src: Node<{
+        primary: K;
+        secondary: unknown;
+        value: V;
+    }>): () => void;
+    dispose(): void;
+}
+/**
+ * Create a reactive dual-key index (D54/D60). DELTA + lazy pull SNAPSHOT + pullId via
+ * {@link collectionCore}; this layer adds the sorted backend + Z reverse-lookup surface.
+ */
+declare function reactiveIndex<K, V = unknown>(options?: ReactiveIndexOptions): ReactiveIndex<K, V>;
+
+/** D161 strict-JSON snapshot frame format tag for reactive collection persistence. */
+declare const REACTIVE_COLLECTION_SNAPSHOT_FORMAT: "graphrefly.reactive-collection.snapshot.v1";
+/** D161 strict-JSON change frame format tag for reactive collection persistence. */
+declare const REACTIVE_COLLECTION_CHANGE_FORMAT: "graphrefly.reactive-collection.change.v1";
+/** D161 v1 frame version for reactive collection snapshot/change storage. */
+declare const REACTIVE_COLLECTION_FRAME_VERSION: 1;
+/** D161 collection kinds recognized by the unified persistence frame envelope. */
+type ReactiveCollectionStorageKind = "reactiveList" | "reactiveLog" | "reactiveMap" | "reactiveIndex";
+/** D161 durable baseline frame; storage is passive and does not own graph restore. */
+interface ReactiveCollectionSnapshotFrame<K extends ReactiveCollectionStorageKind = ReactiveCollectionStorageKind, S = unknown> {
+    readonly format: typeof REACTIVE_COLLECTION_SNAPSHOT_FORMAT;
+    readonly version: typeof REACTIVE_COLLECTION_FRAME_VERSION;
+    readonly kind: K;
+    /** Last append-log seq reflected by this snapshot; -1 means no change-log entry. */
+    readonly changeCursor: number;
+    readonly snapshot: S;
+}
+/** D161 append-log change frame; change-log replay is collection-state folding, not graph restore. */
+interface ReactiveCollectionChangeFrame<K extends ReactiveCollectionStorageKind = ReactiveCollectionStorageKind, C = unknown> {
+    readonly format: typeof REACTIVE_COLLECTION_CHANGE_FORMAT;
+    readonly version: typeof REACTIVE_COLLECTION_FRAME_VERSION;
+    readonly kind: K;
+    readonly change: C;
+}
+/** D161 passive load/fold result consumed by synchronous restoreReactive* helpers. */
+interface ReactiveCollectionRestoreState<K extends ReactiveCollectionStorageKind = ReactiveCollectionStorageKind, S = unknown> {
+    readonly kind: K;
+    readonly state: S;
+    readonly source: "empty" | "changes" | "snapshot" | "snapshot+changes";
+    readonly snapshot: {
+        readonly found: boolean;
+        readonly changeCursor: number;
+    };
+    readonly changes: {
+        readonly applied: number;
+        readonly cursor: number;
+    };
+}
+/** D161 restore state for a reactiveList materialized as a strict-JSON array snapshot. */
+type ReactiveListRestoreState<T = unknown> = ReactiveCollectionRestoreState<"reactiveList", readonly T[]>;
+/** D161 restore state for a reactiveLog materialized as a strict-JSON array snapshot. */
+type ReactiveLogRestoreState<T = unknown> = ReactiveCollectionRestoreState<"reactiveLog", readonly T[]>;
+/** D161 passive restore-state shape for reactiveMap; policy-aware restore remains deferred. */
+type ReactiveMapRestoreState<K = unknown, V = unknown> = ReactiveCollectionRestoreState<"reactiveMap", readonly (readonly [K, V])[]>;
+/** D161 passive restore-state shape for reactiveIndex; key-codec restore remains deferred. */
+type ReactiveIndexRestoreState<K = unknown, V = unknown> = ReactiveCollectionRestoreState<"reactiveIndex", readonly IndexRow<K, V>[]>;
+/** D161 passive storage inputs for collection load/fold helpers. */
+interface LoadReactiveCollectionStateOptions {
+    readonly snapshotStore: KvStorageTier<unknown>;
+    readonly snapshotKey?: string;
+    readonly storagePrefix?: string;
+    readonly changeLog?: AppendLogStorageTier<unknown>;
+}
+/** Build the default D161 snapshot key for a storage prefix. */
+declare function collectionSnapshotKey(storagePrefix?: string): string;
+/** Build a D161 strict-JSON snapshot frame before validation/encoding. */
+declare function reactiveCollectionSnapshotFrame<K extends ReactiveCollectionStorageKind, S>(kind: K, snapshot: S, opts?: {
+    readonly changeCursor?: number;
+}): ReactiveCollectionSnapshotFrame<K, S>;
+/** Build a D161 strict-JSON change frame before validation/encoding. */
+declare function reactiveCollectionChangeFrame<K extends ReactiveCollectionStorageKind, C>(kind: K, change: C): ReactiveCollectionChangeFrame<K, C>;
+/** Validate a D161 snapshot frame and reject non-strict-JSON payloads honestly. */
+declare function assertReactiveCollectionSnapshotFrame<K extends ReactiveCollectionStorageKind, S = unknown>(value: unknown, expectedKind: K): ReactiveCollectionSnapshotFrame<K, S>;
+/** Validate a D161 change frame and reject non-strict-JSON payloads honestly. */
+declare function assertReactiveCollectionChangeFrame<K extends ReactiveCollectionStorageKind, C = unknown>(value: unknown, expectedKind: K): ReactiveCollectionChangeFrame<K, C>;
+/** Codec for D161 snapshot frames with strict JSON validation on both encode and decode. */
+declare function reactiveCollectionSnapshotFrameCodec<K extends ReactiveCollectionStorageKind, S = unknown>(kind: K): Codec<ReactiveCollectionSnapshotFrame<K, S>>;
+/** Codec for D161 change frames with strict JSON validation on both encode and decode. */
+declare function reactiveCollectionChangeFrameCodec<K extends ReactiveCollectionStorageKind, C = unknown>(kind: K): Codec<ReactiveCollectionChangeFrame<K, C>>;
+/** D161 passive load/fold for reactiveList; reads storage but never mutates graph topology. */
+declare function loadReactiveListState<T = unknown>(opts: LoadReactiveCollectionStateOptions): Promise<ReactiveListRestoreState<T>>;
+/** D161 passive load/fold for reactiveLog; reads storage but never mutates graph topology. */
+declare function loadReactiveLogState<T = unknown>(opts: LoadReactiveCollectionStateOptions): Promise<ReactiveLogRestoreState<T>>;
+/** D161 passive load/fold scaffold for reactiveMap; synchronous policy restore is deferred. */
+declare function loadReactiveMapState<K = unknown, V = unknown>(opts: LoadReactiveCollectionStateOptions): Promise<ReactiveMapRestoreState<K, V>>;
+/** D161 passive load/fold scaffold for reactiveIndex; key-codec restore is deferred. */
+declare function loadReactiveIndexState<K = unknown, V = unknown>(opts: LoadReactiveCollectionStateOptions): Promise<ReactiveIndexRestoreState<K, V>>;
+
+export { loadReactiveLogState as A, loadReactiveMapState as B, type CapacityPolicy as C, reactiveCollectionChangeFrame as D, reactiveCollectionChangeFrameCodec as E, reactiveCollectionSnapshotFrame as F, reactiveCollectionSnapshotFrameCodec as G, reactiveIndex as H, type IndexChange as I, type CollectionCoreOptions as J, type ListChange as L, type MapChange as M, type OrderedCapacityPolicy as O, REACTIVE_COLLECTION_CHANGE_FORMAT as R, type ViewCachePolicy as V, type IndexRow as a, type LoadReactiveCollectionStateOptions as b, type LogChange as c, REACTIVE_COLLECTION_FRAME_VERSION as d, REACTIVE_COLLECTION_SNAPSHOT_FORMAT as e, type ReactiveCollectionChangeFrame as f, type ReactiveCollectionRestoreState as g, type ReactiveCollectionSnapshotFrame as h, type ReactiveCollectionStorageKind as i, type ReactiveIndex as j, type ReactiveIndexCapacityOrder as k, type ReactiveIndexCapacityPolicy as l, type ReactiveIndexOpt as m, type ReactiveIndexOptions as n, type ReactiveIndexRestoreState as o, type ReactiveListRestoreState as p, type ReactiveLogRestoreState as q, type ReactiveMapRestoreState as r, type ReactiveOpt as s, type ReactiveView as t, type RetentionPolicy as u, assertReactiveCollectionChangeFrame as v, assertReactiveCollectionSnapshotFrame as w, collectionSnapshotKey as x, loadReactiveIndexState as y, loadReactiveListState as z };

package/dist/reactive-collection-storage-BNiEc-Gd.d.ts

@@ -0,0 +1,217 @@
+import { Q as StateNode, d as Graph } from './graph-DfdF9zy4.js';
+import { N as Node } from './types-h12mNYbq.js';
+import { AgenticMemoryStrictJsonValue, AgenticMemoryRecordFrame, AgenticMemoryRecord } from './solutions/index.js';
+import { f as KvStorageTier, d as AppendLogStorageTier } from './append-log-DzKMmjxx.js';
+import { b as LoadReactiveCollectionStateOptions, a as IndexRow, n as ReactiveIndexOptions, j as ReactiveIndex, o as ReactiveIndexRestoreState, p as ReactiveListRestoreState, q as ReactiveLogRestoreState, r as ReactiveMapRestoreState } from './reactive-collection-Cb1II1Fi.js';
+import { b as ReactiveListOptions, d as ReactiveLogOptions, g as ReactiveMapOptions, R as ReactiveList, c as ReactiveLog, e as ReactiveMap } from './reactive-map-BcB4KsQR.js';
+
+declare const AGENTIC_MEMORY_RECORD_SNAPSHOT_FORMAT: "graphrefly.agenticMemory.records.snapshot";
+declare const AGENTIC_MEMORY_RECORD_CHANGE_FORMAT: "graphrefly.agenticMemory.records.change";
+declare const AGENTIC_MEMORY_RECORD_STORAGE_FRAME_VERSION: 1;
+interface AgenticMemoryRecordSnapshotFrame<TJson extends AgenticMemoryStrictJsonValue = AgenticMemoryStrictJsonValue> {
+    readonly format: typeof AGENTIC_MEMORY_RECORD_SNAPSHOT_FORMAT;
+    readonly version: typeof AGENTIC_MEMORY_RECORD_STORAGE_FRAME_VERSION;
+    readonly changeCursor: number;
+    readonly records: readonly AgenticMemoryRecordFrame<TJson>[];
+}
+interface AgenticMemoryRecordChangeFrame<TJson extends AgenticMemoryStrictJsonValue = AgenticMemoryStrictJsonValue> {
+    readonly format: typeof AGENTIC_MEMORY_RECORD_CHANGE_FORMAT;
+    readonly version: typeof AGENTIC_MEMORY_RECORD_STORAGE_FRAME_VERSION;
+    readonly change: {
+        readonly kind: "replaceAll";
+        readonly records: readonly AgenticMemoryRecordFrame<TJson>[];
+    };
+}
+interface AgenticMemoryRecordsRestoreState<TJson extends AgenticMemoryStrictJsonValue = AgenticMemoryStrictJsonValue> {
+    readonly records: readonly AgenticMemoryRecord<TJson>[];
+    readonly source: "empty" | "changes" | "snapshot" | "snapshot+changes";
+    readonly snapshot: {
+        readonly found: boolean;
+        readonly changeCursor: number;
+    };
+    readonly changes: {
+        readonly applied: number;
+        readonly cursor: number;
+    };
+}
+interface LoadAgenticMemoryRecordsStateOptions {
+    readonly snapshotStore: KvStorageTier<unknown>;
+    readonly snapshotKey?: string;
+    readonly storagePrefix?: string;
+    readonly changeLog?: AppendLogStorageTier<unknown>;
+}
+interface AgenticMemoryRecordsPersistenceCursor {
+    readonly kind: "persistence.cursor";
+    readonly changeSeq: number;
+    readonly snapshotWrites: number;
+    readonly changeWrites: number;
+}
+interface AgenticMemoryRecordsPersistenceStatus {
+    readonly state: "starting" | "ready" | "flushing" | "errored" | "disposed";
+    readonly pending: number;
+    readonly writes: number;
+    readonly errors: number;
+    readonly cursor: AgenticMemoryRecordsPersistenceCursor;
+}
+interface AgenticMemoryRecordsPersistenceError {
+    readonly phase: "snapshot" | "change";
+    readonly message: string;
+    readonly cursor: AgenticMemoryRecordsPersistenceCursor;
+}
+interface PersistAgenticMemoryRecordsOptions {
+    readonly name?: string;
+    readonly snapshotStore: KvStorageTier<unknown>;
+    readonly snapshotKey?: string;
+    readonly storagePrefix?: string;
+    readonly changeLog?: AppendLogStorageTier<unknown>;
+    readonly initialChangeCursor?: number;
+    readonly snapshotOnAttach?: boolean;
+    readonly snapshotEveryChanges?: number;
+}
+interface AgenticMemoryRecordsPersistenceHandle {
+    readonly ready: StateNode<boolean>;
+    readonly status: StateNode<AgenticMemoryRecordsPersistenceStatus>;
+    readonly error: StateNode<AgenticMemoryRecordsPersistenceError | null>;
+    readonly cursor: StateNode<AgenticMemoryRecordsPersistenceCursor>;
+    flush(done?: (status: AgenticMemoryRecordsPersistenceStatus) => void): void;
+    snapshot(done?: (status: AgenticMemoryRecordsPersistenceStatus) => void): void;
+    dispose(done?: (status: AgenticMemoryRecordsPersistenceStatus) => void): void;
+}
+interface OpenPersistentAgenticMemoryRecordsOptions<TJson extends AgenticMemoryStrictJsonValue> extends LoadAgenticMemoryRecordsStateOptions, Omit<PersistAgenticMemoryRecordsOptions, "snapshotStore" | "changeLog" | "initialChangeCursor"> {
+    readonly graph: Graph;
+    readonly name?: string;
+    readonly initial?: readonly AgenticMemoryRecord<TJson>[];
+}
+interface PersistentAgenticMemoryRecords<TJson extends AgenticMemoryStrictJsonValue> {
+    readonly records: StateNode<readonly AgenticMemoryRecord<TJson>[]>;
+    readonly persistence: AgenticMemoryRecordsPersistenceHandle;
+    readonly loaded: AgenticMemoryRecordsRestoreState<TJson>;
+}
+declare function agenticMemoryRecordsSnapshotKey(storagePrefix?: string): string;
+declare function agenticMemoryRecordSnapshotFrame<TJson extends AgenticMemoryStrictJsonValue = AgenticMemoryStrictJsonValue>(records: readonly AgenticMemoryRecord<TJson>[], opts?: {
+    readonly changeCursor?: number;
+}): AgenticMemoryRecordSnapshotFrame<TJson>;
+declare function agenticMemoryRecordChangeFrame<TJson extends AgenticMemoryStrictJsonValue = AgenticMemoryStrictJsonValue>(records: readonly AgenticMemoryRecord<TJson>[]): AgenticMemoryRecordChangeFrame<TJson>;
+declare function assertAgenticMemoryRecordSnapshotFrame<TJson extends AgenticMemoryStrictJsonValue = AgenticMemoryStrictJsonValue>(value: unknown): AgenticMemoryRecordSnapshotFrame<TJson>;
+declare function assertAgenticMemoryRecordChangeFrame<TJson extends AgenticMemoryStrictJsonValue = AgenticMemoryStrictJsonValue>(value: unknown): AgenticMemoryRecordChangeFrame<TJson>;
+declare function loadAgenticMemoryRecordsState<TJson extends AgenticMemoryStrictJsonValue = AgenticMemoryStrictJsonValue>(opts: LoadAgenticMemoryRecordsStateOptions): Promise<AgenticMemoryRecordsRestoreState<TJson>>;
+declare function persistAgenticMemoryRecords<TJson extends AgenticMemoryStrictJsonValue = AgenticMemoryStrictJsonValue>(graph: Graph, records: Node<readonly AgenticMemoryRecord<TJson>[]>, opts: PersistAgenticMemoryRecordsOptions): AgenticMemoryRecordsPersistenceHandle;
+declare function openPersistentAgenticMemoryRecords<TJson extends AgenticMemoryStrictJsonValue = AgenticMemoryStrictJsonValue>(opts: OpenPersistentAgenticMemoryRecordsOptions<TJson>): Promise<PersistentAgenticMemoryRecords<TJson>>;
+
+type PersistableKind = "reactiveList" | "reactiveLog" | "reactiveMap" | "reactiveIndex";
+type PersistableCollection<T, K extends PersistableKind> = K extends "reactiveList" ? ReactiveList<T> : K extends "reactiveLog" ? ReactiveLog<T> : K extends "reactiveMap" ? ReactiveMap<unknown, T> : ReactiveIndex<unknown, T>;
+/** D161 adapter write-progress cursor; this is not a domain replay or wire-bridge cursor. */
+interface ReactiveCollectionPersistenceCursor {
+    readonly kind: "persistence.cursor";
+    readonly collection: PersistableKind;
+    readonly changeSeq: number;
+    readonly snapshotWrites: number;
+    readonly changeWrites: number;
+}
+/** D161 graph-visible persistence sidecar status fact. */
+interface ReactiveCollectionPersistenceStatus {
+    readonly state: "starting" | "ready" | "flushing" | "errored" | "disposed";
+    readonly pending: number;
+    readonly writes: number;
+    readonly errors: number;
+    readonly cursor: ReactiveCollectionPersistenceCursor;
+}
+/** D161 graph-visible persistence sidecar error fact. */
+interface ReactiveCollectionPersistenceError {
+    readonly phase: "snapshot" | "change";
+    readonly message: string;
+    readonly cursor: ReactiveCollectionPersistenceCursor;
+}
+/** Options for the D161 graph-bound persistence sidecar over a reactive collection. */
+interface PersistReactiveCollectionOptions<K extends PersistableKind = PersistableKind> {
+    readonly kind: K;
+    readonly name?: string;
+    readonly snapshotStore: KvStorageTier<unknown>;
+    readonly snapshotKey?: string;
+    readonly storagePrefix?: string;
+    readonly changeLog?: AppendLogStorageTier<unknown>;
+    /** Adapter write cursor seed for wrappers that already folded a change log. */
+    readonly initialChangeCursor?: number;
+    /** Default true: write one durable baseline when the adapter attaches. */
+    readonly snapshotOnAttach?: boolean;
+    /** Optional snapshot cadence. Manual snapshots remain available via handle.snapshot(). */
+    readonly snapshotEveryChanges?: number;
+}
+/** D161 sidecar controls; flush waits for queued storage promises to settle, not fsync. */
+interface ReactiveCollectionPersistenceHandle {
+    readonly ready: StateNode<boolean>;
+    readonly status: StateNode<ReactiveCollectionPersistenceStatus>;
+    readonly error: StateNode<ReactiveCollectionPersistenceError | null>;
+    readonly cursor: StateNode<ReactiveCollectionPersistenceCursor>;
+    flush(done?: (status: ReactiveCollectionPersistenceStatus) => void): void;
+    snapshot(done?: (status: ReactiveCollectionPersistenceStatus) => void): void;
+    dispose(done?: (status: ReactiveCollectionPersistenceStatus) => void): void;
+}
+/**
+ * D161 graph-bound sidecar over an existing collection. It writes passive storage frames and
+ * exposes adapter progress as graph-visible DATA facts; it never restores or mutates the collection.
+ */
+declare function persistReactiveCollection<T, K extends PersistableKind>(graph: Graph, collection: PersistableCollection<T, K>, opts: PersistReactiveCollectionOptions<K>): ReactiveCollectionPersistenceHandle;
+type CollectionOptionsWithoutGraphName<T> = Omit<T, "graph" | "name">;
+/** Options for D161 load -> restore -> persist composition for reactiveList. */
+interface OpenPersistentReactiveListOptions<T> extends LoadReactiveCollectionStateOptions, Omit<PersistReactiveCollectionOptions<"reactiveList">, "kind" | "snapshotStore" | "changeLog" | "initialChangeCursor"> {
+    readonly graph: Graph;
+    readonly name?: string;
+    readonly initial?: readonly T[];
+    readonly collection?: CollectionOptionsWithoutGraphName<ReactiveListOptions>;
+}
+/** Options for D161 load -> restore -> persist composition for reactiveLog. */
+interface OpenPersistentReactiveLogOptions<T> extends LoadReactiveCollectionStateOptions, Omit<PersistReactiveCollectionOptions<"reactiveLog">, "kind" | "snapshotStore" | "changeLog" | "initialChangeCursor"> {
+    readonly graph: Graph;
+    readonly name?: string;
+    readonly initial?: readonly T[];
+    readonly collection?: CollectionOptionsWithoutGraphName<ReactiveLogOptions>;
+}
+/** Options for D161 load -> restore -> persist composition for reactiveMap. */
+interface OpenPersistentReactiveMapOptions<K, V> extends LoadReactiveCollectionStateOptions, Omit<PersistReactiveCollectionOptions<"reactiveMap">, "kind" | "snapshotStore" | "changeLog" | "initialChangeCursor"> {
+    readonly graph: Graph;
+    readonly name?: string;
+    readonly initial?: readonly (readonly [K, V])[];
+    readonly collection?: CollectionOptionsWithoutGraphName<ReactiveMapOptions<K, V>>;
+}
+/** Options for D161 load -> restore -> persist composition for reactiveIndex. */
+interface OpenPersistentReactiveIndexOptions<K, V> extends LoadReactiveCollectionStateOptions, Omit<PersistReactiveCollectionOptions<"reactiveIndex">, "kind" | "snapshotStore" | "changeLog" | "initialChangeCursor"> {
+    readonly graph: Graph;
+    readonly name?: string;
+    readonly initial?: readonly IndexRow<K, V>[];
+    readonly collection?: CollectionOptionsWithoutGraphName<ReactiveIndexOptions>;
+}
+/** Return value for D161 persistent reactiveList composition. */
+interface PersistentReactiveList<T> {
+    readonly collection: ReactiveList<T>;
+    readonly persistence: ReactiveCollectionPersistenceHandle;
+    readonly loaded: ReactiveListRestoreState<T>;
+}
+/** Return value for D161 persistent reactiveLog composition. */
+interface PersistentReactiveLog<T> {
+    readonly collection: ReactiveLog<T>;
+    readonly persistence: ReactiveCollectionPersistenceHandle;
+    readonly loaded: ReactiveLogRestoreState<T>;
+}
+/** Return value for D161 persistent reactiveMap composition. */
+interface PersistentReactiveMap<K, V> {
+    readonly collection: ReactiveMap<K, V>;
+    readonly persistence: ReactiveCollectionPersistenceHandle;
+    readonly loaded: ReactiveMapRestoreState<K, V>;
+}
+/** Return value for D161 persistent reactiveIndex composition. */
+interface PersistentReactiveIndex<K, V> {
+    readonly collection: ReactiveIndex<K, V>;
+    readonly persistence: ReactiveCollectionPersistenceHandle;
+    readonly loaded: ReactiveIndexRestoreState<K, V>;
+}
+/** D161 convenience wrapper: passive load, sync restoreReactiveList, then sidecar persist. */
+declare function openPersistentReactiveList<T = unknown>(opts: OpenPersistentReactiveListOptions<T>): Promise<PersistentReactiveList<T>>;
+/** D161 convenience wrapper: passive load, sync restoreReactiveLog, then sidecar persist. */
+declare function openPersistentReactiveLog<T = unknown>(opts: OpenPersistentReactiveLogOptions<T>): Promise<PersistentReactiveLog<T>>;
+/** D161 convenience wrapper: passive load, sync restoreReactiveMap, then sidecar persist. */
+declare function openPersistentReactiveMap<K = unknown, V = unknown>(opts: OpenPersistentReactiveMapOptions<K, V>): Promise<PersistentReactiveMap<K, V>>;
+/** D161 convenience wrapper: passive load, sync restoreReactiveIndex, then sidecar persist. */
+declare function openPersistentReactiveIndex<K = unknown, V = unknown>(opts: OpenPersistentReactiveIndexOptions<K, V>): Promise<PersistentReactiveIndex<K, V>>;
+
+export { AGENTIC_MEMORY_RECORD_CHANGE_FORMAT as A, assertAgenticMemoryRecordSnapshotFrame as B, loadAgenticMemoryRecordsState as C, openPersistentAgenticMemoryRecords as D, openPersistentReactiveIndex as E, openPersistentReactiveList as F, openPersistentReactiveLog as G, openPersistentReactiveMap as H, persistAgenticMemoryRecords as I, persistReactiveCollection as J, type LoadAgenticMemoryRecordsStateOptions as L, type OpenPersistentAgenticMemoryRecordsOptions as O, type PersistAgenticMemoryRecordsOptions as P, type ReactiveCollectionPersistenceCursor as R, AGENTIC_MEMORY_RECORD_SNAPSHOT_FORMAT as a, AGENTIC_MEMORY_RECORD_STORAGE_FRAME_VERSION as b, type AgenticMemoryRecordChangeFrame as c, type AgenticMemoryRecordSnapshotFrame as d, type AgenticMemoryRecordsPersistenceCursor as e, type AgenticMemoryRecordsPersistenceError as f, type AgenticMemoryRecordsPersistenceHandle as g, type AgenticMemoryRecordsPersistenceStatus as h, type AgenticMemoryRecordsRestoreState as i, type OpenPersistentReactiveIndexOptions as j, type OpenPersistentReactiveListOptions as k, type OpenPersistentReactiveLogOptions as l, type OpenPersistentReactiveMapOptions as m, type PersistReactiveCollectionOptions as n, type PersistentAgenticMemoryRecords as o, type PersistentReactiveIndex as p, type PersistentReactiveList as q, type PersistentReactiveLog as r, type PersistentReactiveMap as s, type ReactiveCollectionPersistenceError as t, type ReactiveCollectionPersistenceHandle as u, type ReactiveCollectionPersistenceStatus as v, agenticMemoryRecordChangeFrame as w, agenticMemoryRecordSnapshotFrame as x, agenticMemoryRecordsSnapshotKey as y, assertAgenticMemoryRecordChangeFrame as z };