@graphrefly/ts 0.0.0

package/dist/reactive-collection-BxBqtIOE.d.cts

@@ -0,0 +1,344 @@
+import { N as Node, D as Dispatcher } from './types-bNMSWKqF.cjs';
+import { d as Graph } from './graph-s23RbbFO.cjs';
+import { f as KvStorageTier, d as AppendLogStorageTier } from './append-log-DisvEReb.cjs';
+import { C as Codec } from './codec-BB7p8fJc.cjs';
+
+/**
+ * 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 };