@graphrefly/graphrefly 0.26.0 → 0.28.0

package/dist/reactive-log-YuH9VYN8.d.ts

@@ -0,0 +1,190 @@
+import { a as Node, V as VersioningLevel } from './node-Cc1TniY8.js';
+
+type ReactiveLogOptions<T> = {
+    name?: string;
+    maxSize?: number;
+    /**
+     * Optional versioning level for the underlying `entries` state node. Set
+     * at construction time; cannot be changed later. Pass `0` for V0 identity
+     * + monotonic version counter, or `1` for V1 + content-addressed cid.
+     */
+    versioning?: VersioningLevel;
+    /**
+     * Storage backend. Defaults to `NativeLogBackend` (ring buffer if `maxSize` is set,
+     * flat array otherwise). Users can plug in persistent / RRB-tree backends via
+     * the {@link LogBackend} interface.
+     */
+    backend?: LogBackend<T>;
+};
+type ReactiveLogBundle<T> = {
+    /** Emits `readonly T[]` on each append/clear/trim (two-phase). */
+    readonly entries: Node<readonly T[]>;
+    /** Current entry count (O(1)). */
+    readonly size: number;
+    /** Positional access (O(1)); returns `undefined` on out-of-range. Supports negative indices (Python-style). */
+    at: (index: number) => T | undefined;
+    append: (value: T) => void;
+    /**
+     * Push all values, emit one snapshot. No-op if `values` is empty.
+     * **Iterable consumption:** `values` is a `readonly T[]` — safe to pass arrays.
+     */
+    appendMany: (values: readonly T[]) => void;
+    clear: () => void;
+    /** Remove the first `n` entries (clamped to `size`). Throws on non-integer or negative `n`. */
+    trimHead: (n: number) => void;
+    /**
+     * Last `n` entries (or fewer) as a derived reactive view. Memoized with
+     * an LRU cache (default cap 64) — repeat calls with the same `n` return
+     * the same node. Throws on non-integer or negative `n`.
+     *
+     * **LRU eviction contract (D3(b)):** when a 65th distinct `n` is passed,
+     * the least-recently-used cached view is evicted and its keepalive is
+     * disposed. External holders of the evicted node will NOT receive further
+     * updates — re-call `tail(n)` for a fresh node, or dispose proactively
+     * via {@link disposeTail} / {@link disposeAllViews}. To avoid surprise:
+     * resolve `tail(n)` at the point of use rather than caching the returned
+     * node across many distinct `n`s.
+     */
+    tail: (n: number) => Node<readonly T[]>;
+    /**
+     * Reactive view of `entries.slice(start, stop)` — non-negative integer
+     * `start`, non-negative integer `stop` (exclusive) or `undefined` (to end).
+     * Memoized with an LRU cache (default cap 64) — repeat calls with the
+     * same `(start, stop)` return the same node.
+     *
+     * Throws on non-integer `start`, negative `start`, non-integer `stop`, or
+     * negative `stop` (P4 — the backend cannot cheaply honor JS-style
+     * negative `stop` without scanning length; disallowed for a consistent
+     * contract between backend, derived recomputation, and cached initial).
+     *
+     * **LRU eviction contract (D3(b)):** same as {@link tail} — past 64
+     * distinct `(start, stop)` pairs, the oldest cached view is evicted and
+     * its keepalive disposed. External holders stop receiving updates.
+     */
+    slice: (start: number, stop?: number) => Node<readonly T[]>;
+    /**
+     * Releases the cached `tail(n)` view if present (disposes its keepalive
+     * subscription). Subsequent `tail(n)` calls create a fresh node. No-op if
+     * `n` was not cached. Returns `true` if a view was disposed.
+     */
+    disposeTail: (n: number) => boolean;
+    /**
+     * Releases the cached `slice(start, stop?)` view if present. No-op if not cached.
+     */
+    disposeSlice: (start: number, stop?: number) => boolean;
+    /** Releases all cached tail/slice views and their keepalive subscriptions. */
+    disposeAllViews: () => void;
+    /**
+     * Releases all internal keepalive subscriptions so the bundle can be
+     * GC'd — currently equivalent to {@link disposeAllViews}, but exposed as
+     * a uniform API across all reactive data structures for lifecycle
+     * symmetry (mirrors `reactiveMap.dispose` / `reactiveList.dispose` /
+     * `reactiveIndex.dispose`). Idempotent. D6(a).
+     */
+    dispose: () => void;
+};
+/**
+ * Storage contract for {@link reactiveLog}. Implementations own the mutable state and
+ * expose a monotonic `version` counter that increments on every structural change.
+ *
+ * The reactive layer reads `version` to decide when to emit; it does not inspect
+ * internal representation. Users can plug in persistent / ring-buffer / skip-list
+ * backends without touching the reactive emission logic.
+ *
+ * @remarks Post-1.0 op-log changesets will extend this interface with a
+ * `changesSince(version: number): Iterable<Change>` method. Current consumers
+ * should treat all methods here as stable.
+ *
+ * @category extra
+ */
+interface LogBackend<T> {
+    /** Monotonic mutation counter; increments on every append/trim/clear that changes state. */
+    readonly version: number;
+    /** Number of entries currently stored. */
+    readonly size: number;
+    /** O(1) positional access; returns `undefined` on out-of-range. */
+    at(index: number): T | undefined;
+    /** Append a value. Applies `maxSize` head-drop if configured. Advances `version`. */
+    append(value: T): void;
+    /** Append a batch; advances `version` once. No-op if `values.length === 0`. */
+    appendMany(values: readonly T[]): void;
+    /** Remove all entries. Returns count removed. Advances `version` only if non-zero. */
+    clear(): number;
+    /** Remove the first `n` entries (clamped). Returns count removed. Throws on negative `n`. */
+    trimHead(n: number): number;
+    /** Fresh snapshot array for `[start, stop)`. Throws on negative `start`. */
+    slice(start: number, stop?: number): readonly T[];
+    /** Last `n` entries as a fresh array. Throws on negative `n`. */
+    tail(n: number): readonly T[];
+    /** Full snapshot as a fresh array. */
+    toArray(): readonly T[];
+}
+/**
+ * Default append-only log backend.
+ *
+ * - When `maxSize` is set: uses a **ring buffer** with `_head` index and circular
+ *   modular arithmetic. Append and trim become O(1); snapshot is O(size) unrolling.
+ * - When `maxSize` is unset: uses a flat array with standard push/splice.
+ *
+ * `appendMany` pre-trims oversize input: if `values.length > maxSize`, only the
+ * tail of `values` is pushed (the rest would be immediately evicted).
+ *
+ * @category extra
+ */
+declare class NativeLogBackend<T> implements LogBackend<T> {
+    private _version;
+    private readonly _maxSize?;
+    private readonly _buf;
+    private _head;
+    private _size;
+    constructor(initial?: readonly T[], maxSize?: number);
+    get version(): number;
+    get size(): number;
+    at(index: number): T | undefined;
+    append(value: T): void;
+    appendMany(values: readonly T[]): void;
+    clear(): number;
+    trimHead(n: number): number;
+    slice(start: number, stop?: number): readonly T[];
+    tail(n: number): readonly T[];
+    toArray(): readonly T[];
+    /** Internal append without version bump — used by `appendMany`. */
+    private _rawAppend;
+}
+/**
+ * Creates an append-only reactive log with immutable array snapshots.
+ *
+ * @param initial - Optional seed entries (copied; pre-trimmed to `maxSize` if set).
+ * @param options - `name`, `maxSize`, and optional pluggable `backend`.
+ * @returns Bundle with `entries` (state node), `append`/`appendMany`/`clear`/`trimHead`,
+ *   `size` / `at`, and memoized derived views `tail(n)` / `slice(start, stop?)`.
+ *
+ * @remarks
+ * **Backend:** The default {@link NativeLogBackend} uses a ring buffer when `maxSize`
+ * is set (O(1) append + trim) and a flat array otherwise. For persistent/structural-
+ * sharing semantics plug in a custom {@link LogBackend}.
+ *
+ * **`initial` + custom `backend` (F5):** When you supply `options.backend`, the
+ * `initial` argument is IGNORED — seed the backend yourself before passing it in.
+ * The `initial` seed only applies to the default `NativeLogBackend`.
+ *
+ * **Memoized views:** {@link ReactiveLogBundle.tail} and {@link ReactiveLogBundle.slice}
+ * cache derived nodes per-argument. Repeat calls with the same `n` / `(start, stop)`
+ * return the same node, bounding keepalive-subscription count to one per unique argument.
+ *
+ * @example
+ * ```ts
+ * import { reactiveLog } from "@graphrefly/graphrefly-ts";
+ *
+ * const lg = reactiveLog<number>([1, 2], { name: "audit", maxSize: 100 });
+ * lg.append(3);
+ * lg.entries.subscribe((msgs) => console.log(msgs));
+ * const last5 = lg.tail(5);          // derived node
+ * const window = lg.slice(10, 20);   // derived node
+ * ```
+ *
+ * @category extra
+ */
+declare function reactiveLog<T>(initial?: readonly T[], options?: ReactiveLogOptions<T>): ReactiveLogBundle<T>;
+
+export { type LogBackend as L, NativeLogBackend as N, type ReactiveLogBundle as R, type ReactiveLogOptions as a, reactiveLog as r };

package/dist/reactive-map-CdbNoSgP.d.ts

@@ -0,0 +1,238 @@
+import { a as Node, V as VersioningLevel, N as NodeOptions } from './node-Cc1TniY8.js';
+
+type ReactiveMapOptions<K, V> = {
+    /** Optional registry name for `describe()` / debugging. */
+    name?: string;
+    /**
+     * LRU cap. When set, evicts least-recently-used keys after inserts that exceed this size.
+     * Forwarded to the default `NativeMapBackend`. Ignored if a custom `backend` is provided.
+     */
+    maxSize?: number;
+    /**
+     * Default TTL in seconds. Used when `set`/`setMany` omits per-call `ttl`.
+     * Forwarded to the default `NativeMapBackend`. Ignored if a custom `backend` is provided.
+     */
+    defaultTtl?: number;
+    /**
+     * Storage backend. Defaults to `NativeMapBackend`. Users can plug in persistent
+     * (HAMT / Immutable.js) or shared-state backends via the {@link MapBackend} interface.
+     */
+    backend?: MapBackend<K, V>;
+    /**
+     * Optional versioning level for the underlying `entries` state node. Set at
+     * construction time; cannot be changed later. Pass `0` for V0 identity +
+     * monotonic version counter, or `1` for V1 + content-addressed cid.
+     */
+    versioning?: VersioningLevel;
+} & Omit<NodeOptions, "initial" | "describeKind" | "equals" | "versioning">;
+type ReactiveMapBundle<K, V> = {
+    /** Emits `ReadonlyMap<K, V>` on each structural change (two-phase). */
+    entries: Node<ReadonlyMap<K, V>>;
+    /**
+     * Checks existence. O(1) for live keys. If the key is expired, prunes it AND
+     * emits a snapshot so the reactive surface stays consistent with the return
+     * value. Reads on expired keys are therefore **observable side effects**.
+     *
+     * **LRU touch (F4):** When `maxSize` is configured, a live-key `has` also
+     * marks the entry as most-recently-used — which rearranges internal insertion
+     * order without bumping `version` or emitting. If you care about iteration
+     * order in a downstream subscriber, rely on the `entries` snapshot (a fresh
+     * `ReadonlyMap` per mutation) rather than iterating the backend directly.
+     */
+    has: (key: K) => boolean;
+    /**
+     * Gets value. O(1) for live keys. If the key is expired, prunes it AND emits
+     * a snapshot. Reads on expired keys are therefore **observable side effects**.
+     *
+     * **LRU touch (F4):** When `maxSize` is configured, a live-key `get` also
+     * marks the entry as most-recently-used (no version bump, no emission). See
+     * `has` for the full note on iteration order.
+     */
+    get: (key: K) => V | undefined;
+    /**
+     * Sets value with optional TTL (seconds). Throws on `ttl <= 0`. Applies LRU eviction
+     * if `maxSize` is set. Always emits.
+     */
+    set: (key: K, value: V, opts?: {
+        ttl?: number;
+    }) => void;
+    /**
+     * Bulk set — emits one snapshot for the whole batch. Applies `opts.ttl` (falls back
+     * to `defaultTtl`) to every entry. No-op if `entries` is empty.
+     *
+     * **Iterable consumption:** Consumes `entries` once (single-pass). Pass an array
+     * or `Set` for multi-shot consumers. If the iterator throws mid-iteration,
+     * entries already applied remain committed and a snapshot IS emitted (via the
+     * wrapper's finally-block).
+     */
+    setMany: (entries: Iterable<readonly [K, V]>, opts?: {
+        ttl?: number;
+    }) => void;
+    delete: (key: K) => void;
+    /**
+     * Bulk delete — emits one snapshot. No-op if no keys were present.
+     *
+     * **Iterable consumption:** Consumes `keys` once (single-pass).
+     */
+    deleteMany: (keys: Iterable<K>) => void;
+    clear: () => void;
+    /**
+     * Current entry count — O(1), **pure read** (no emission). May include
+     * expired entries on TTL maps until a mutation or explicit
+     * `pruneExpired()` / `has(key)` / `get(key)` prunes them. Call
+     * `pruneExpired()` first if you need a live count.
+     */
+    readonly size: number;
+    /** Explicitly prunes all expired entries. Emits if any were removed. */
+    pruneExpired: () => void;
+    /**
+     * Releases any internal keepalive subscriptions so the bundle can be
+     * GC'd. `reactiveMap` currently holds none (the `entries` node lives only
+     * as long as external subscribers keep it alive), so `dispose()` is a
+     * no-op today — exposed for API parity with `reactiveIndex.dispose` /
+     * `reactiveList.dispose` / `reactiveLog.dispose`. Idempotent. D6(a).
+     */
+    dispose: () => void;
+};
+/**
+ * Storage contract for {@link reactiveMap}. Implementations own the mutable state,
+ * including optional TTL and LRU semantics, and expose a monotonic `version` counter
+ * that increments on every change to visible state.
+ *
+ * The reactive layer reads `version` before and after each backend call; when it
+ * advances, a snapshot is emitted. Reads (`has`, `get`) may internally prune the
+ * target key if expired and advance `version` — in which case the layer emits so
+ * subscribers see state consistent with the read's return value.
+ *
+ * @remarks Post-1.0 op-log changesets will extend this interface with a
+ * `changesSince(version: number): Iterable<Change>` method. Current consumers
+ * should treat all methods here as stable.
+ *
+ * @category extra
+ */
+interface MapBackend<K, V> {
+    /** Monotonic mutation counter; increments on every visible state change. */
+    readonly version: number;
+    /** Raw entry count (may include expired entries until a read / prune removes them). */
+    readonly size: number;
+    /** Checks existence. May prune target key if expired; advances `version` if pruned. */
+    has(key: K): boolean;
+    /** Gets value. May prune target key if expired; advances `version` if pruned. */
+    get(key: K): V | undefined;
+    /**
+     * Sets a value with optional TTL (seconds). Throws `RangeError` if `ttl <= 0`.
+     * Applies LRU eviction if `maxSize` is configured. Advances `version`.
+     *
+     * **Atomicity contract:** Either fully succeeds or throws before any state
+     * change; `version` advances only on success.
+     */
+    set(key: K, value: V, ttl?: number): void;
+    /**
+     * Atomic bulk set. Pre-validates TTL once, then applies all entries. Advances
+     * `version` at most once (even for N entries). No-op if iterable is empty.
+     *
+     * **Consumes `entries` once** — pass an array if you want repeatability.
+     *
+     * **Atomicity contract:** TTL validation throws before any mutation. If the
+     * iterable itself throws mid-iteration, entries committed before the throw
+     * remain persisted AND `version` is bumped once (surfaced via finally) so
+     * the reactive wrapper emits a snapshot reflecting the partial state. "At
+     * most once" invariant is preserved.
+     */
+    setMany(entries: Iterable<readonly [K, V]>, ttl?: number): void;
+    /** Removes a key. Returns `true` if the key existed. Advances `version` only if true. */
+    delete(key: K): boolean;
+    /**
+     * Atomic bulk delete. Returns count removed. Advances `version` at most once
+     * (even for N keys). No-op if no keys were present. Consumes `keys` once.
+     */
+    deleteMany(keys: Iterable<K>): number;
+    /** Removes all entries. Returns count removed. Advances `version` only if non-zero. */
+    clear(): number;
+    /** Removes all expired entries. Returns count removed. Advances `version` only if non-zero. */
+    pruneExpired(): number;
+    /** Fresh snapshot of non-expired entries (does NOT mutate state). */
+    toMap(): ReadonlyMap<K, V>;
+}
+type NativeMapBackendOptions = {
+    maxSize?: number;
+    /** Default TTL in seconds. */
+    defaultTtl?: number;
+};
+/**
+ * Default `Map<K, {value, expiresAt}>` backend with optional per-key TTL and LRU cap.
+ *
+ * **Complexity:**
+ * - `has`, `get`, `delete`, `size`: O(1)
+ * - `set`: O(1) amortized (LRU touch + eviction)
+ * - `pruneExpired`, `toMap`: O(n)
+ *
+ * LRU order uses native `Map` insertion order. `get` / `has` on a live key "touches"
+ * it by delete-then-reinsert (moving it to the end). This touch does NOT advance
+ * `version` — it's an internal optimization; the externally visible snapshot
+ * preserves iteration order as of the last mutation. **Note:** because touch
+ * reorders the internal `_store` without emitting, an in-process consumer iterating
+ * `_store` directly (custom subclasses) could observe changing order; external
+ * subscribers only see `toMap()` snapshots which are defensively copied and stable.
+ *
+ * @category extra
+ */
+declare class NativeMapBackend<K, V> implements MapBackend<K, V> {
+    private _version;
+    private readonly _store;
+    private readonly _maxSize?;
+    private readonly _defaultTtl?;
+    constructor(options?: NativeMapBackendOptions);
+    get version(): number;
+    get size(): number;
+    has(key: K): boolean;
+    get(key: K): V | undefined;
+    set(key: K, value: V, ttl?: number): void;
+    setMany(entries: Iterable<readonly [K, V]>, ttl?: number): void;
+    delete(key: K): boolean;
+    deleteMany(keys: Iterable<K>): number;
+    clear(): number;
+    pruneExpired(): number;
+    toMap(): ReadonlyMap<K, V>;
+    private _resolveExpiresAt;
+    private _isExpired;
+    private _touchLru;
+    private _evictLruWhileOver;
+}
+/**
+ * Creates a reactive `Map` with optional per-key TTL and optional LRU max size.
+ *
+ * @param options - `name`, `maxSize`, `defaultTtl` (seconds), or custom `backend`.
+ * @returns `ReactiveMapBundle` — imperative methods (`has`/`get`/`set`/`setMany`/`delete`/
+ *   `deleteMany`/`clear`/`pruneExpired`), reactive `entries` node, and O(1)-ish `size`.
+ *
+ * @remarks
+ * **TTL:** Expiry is checked on `get`, `has`, `size`, `pruneExpired`, and before each
+ * snapshot emission (expired keys are pruned first). Reads that discover expired keys
+ * emit a snapshot so subscribers see state consistent with the read's return value.
+ * There is no background timer; monotonic-clock expiry is immune to wall-clock changes.
+ *
+ * **LRU:** Uses native `Map` insertion order — `get` / `has` refreshes position via
+ * delete-then-reinsert; under `maxSize` pressure the first key in iteration order is
+ * evicted. LRU touching does NOT trigger emission (internal optimization).
+ *
+ * **Backend:** The default {@link NativeMapBackend} owns LRU/TTL. For persistent /
+ * HAMT / shared-state semantics plug in a custom {@link MapBackend}. `maxSize` and
+ * `defaultTtl` on the options object are only applied to the default backend — if
+ * you supply `backend`, configure those on your backend directly.
+ *
+ * @example
+ * ```ts
+ * import { reactiveMap } from "@graphrefly/graphrefly-ts";
+ *
+ * const m = reactiveMap<string, number>({ name: "cache", maxSize: 100, defaultTtl: 60 });
+ * m.set("x", 1);
+ * m.setMany([["y", 2], ["z", 3]]);
+ * m.entries.subscribe((msgs) => { console.log(msgs); });
+ * ```
+ *
+ * @category extra
+ */
+declare function reactiveMap<K, V>(options?: ReactiveMapOptions<K, V>): ReactiveMapBundle<K, V>;
+
+export { type MapBackend as M, NativeMapBackend as N, type ReactiveMapBundle as R, type ReactiveMapOptions as a, type NativeMapBackendOptions as b, reactiveMap as r };

package/dist/reactive-map-DUeRmb9d.d.cts

@@ -0,0 +1,238 @@
+import { a as Node, V as VersioningLevel, N as NodeOptions } from './node-Cc1TniY8.cjs';
+
+type ReactiveMapOptions<K, V> = {
+    /** Optional registry name for `describe()` / debugging. */
+    name?: string;
+    /**
+     * LRU cap. When set, evicts least-recently-used keys after inserts that exceed this size.
+     * Forwarded to the default `NativeMapBackend`. Ignored if a custom `backend` is provided.
+     */
+    maxSize?: number;
+    /**
+     * Default TTL in seconds. Used when `set`/`setMany` omits per-call `ttl`.
+     * Forwarded to the default `NativeMapBackend`. Ignored if a custom `backend` is provided.
+     */
+    defaultTtl?: number;
+    /**
+     * Storage backend. Defaults to `NativeMapBackend`. Users can plug in persistent
+     * (HAMT / Immutable.js) or shared-state backends via the {@link MapBackend} interface.
+     */
+    backend?: MapBackend<K, V>;
+    /**
+     * Optional versioning level for the underlying `entries` state node. Set at
+     * construction time; cannot be changed later. Pass `0` for V0 identity +
+     * monotonic version counter, or `1` for V1 + content-addressed cid.
+     */
+    versioning?: VersioningLevel;
+} & Omit<NodeOptions, "initial" | "describeKind" | "equals" | "versioning">;
+type ReactiveMapBundle<K, V> = {
+    /** Emits `ReadonlyMap<K, V>` on each structural change (two-phase). */
+    entries: Node<ReadonlyMap<K, V>>;
+    /**
+     * Checks existence. O(1) for live keys. If the key is expired, prunes it AND
+     * emits a snapshot so the reactive surface stays consistent with the return
+     * value. Reads on expired keys are therefore **observable side effects**.
+     *
+     * **LRU touch (F4):** When `maxSize` is configured, a live-key `has` also
+     * marks the entry as most-recently-used — which rearranges internal insertion
+     * order without bumping `version` or emitting. If you care about iteration
+     * order in a downstream subscriber, rely on the `entries` snapshot (a fresh
+     * `ReadonlyMap` per mutation) rather than iterating the backend directly.
+     */
+    has: (key: K) => boolean;
+    /**
+     * Gets value. O(1) for live keys. If the key is expired, prunes it AND emits
+     * a snapshot. Reads on expired keys are therefore **observable side effects**.
+     *
+     * **LRU touch (F4):** When `maxSize` is configured, a live-key `get` also
+     * marks the entry as most-recently-used (no version bump, no emission). See
+     * `has` for the full note on iteration order.
+     */
+    get: (key: K) => V | undefined;
+    /**
+     * Sets value with optional TTL (seconds). Throws on `ttl <= 0`. Applies LRU eviction
+     * if `maxSize` is set. Always emits.
+     */
+    set: (key: K, value: V, opts?: {
+        ttl?: number;
+    }) => void;
+    /**
+     * Bulk set — emits one snapshot for the whole batch. Applies `opts.ttl` (falls back
+     * to `defaultTtl`) to every entry. No-op if `entries` is empty.
+     *
+     * **Iterable consumption:** Consumes `entries` once (single-pass). Pass an array
+     * or `Set` for multi-shot consumers. If the iterator throws mid-iteration,
+     * entries already applied remain committed and a snapshot IS emitted (via the
+     * wrapper's finally-block).
+     */
+    setMany: (entries: Iterable<readonly [K, V]>, opts?: {
+        ttl?: number;
+    }) => void;
+    delete: (key: K) => void;
+    /**
+     * Bulk delete — emits one snapshot. No-op if no keys were present.
+     *
+     * **Iterable consumption:** Consumes `keys` once (single-pass).
+     */
+    deleteMany: (keys: Iterable<K>) => void;
+    clear: () => void;
+    /**
+     * Current entry count — O(1), **pure read** (no emission). May include
+     * expired entries on TTL maps until a mutation or explicit
+     * `pruneExpired()` / `has(key)` / `get(key)` prunes them. Call
+     * `pruneExpired()` first if you need a live count.
+     */
+    readonly size: number;
+    /** Explicitly prunes all expired entries. Emits if any were removed. */
+    pruneExpired: () => void;
+    /**
+     * Releases any internal keepalive subscriptions so the bundle can be
+     * GC'd. `reactiveMap` currently holds none (the `entries` node lives only
+     * as long as external subscribers keep it alive), so `dispose()` is a
+     * no-op today — exposed for API parity with `reactiveIndex.dispose` /
+     * `reactiveList.dispose` / `reactiveLog.dispose`. Idempotent. D6(a).
+     */
+    dispose: () => void;
+};
+/**
+ * Storage contract for {@link reactiveMap}. Implementations own the mutable state,
+ * including optional TTL and LRU semantics, and expose a monotonic `version` counter
+ * that increments on every change to visible state.
+ *
+ * The reactive layer reads `version` before and after each backend call; when it
+ * advances, a snapshot is emitted. Reads (`has`, `get`) may internally prune the
+ * target key if expired and advance `version` — in which case the layer emits so
+ * subscribers see state consistent with the read's return value.
+ *
+ * @remarks Post-1.0 op-log changesets will extend this interface with a
+ * `changesSince(version: number): Iterable<Change>` method. Current consumers
+ * should treat all methods here as stable.
+ *
+ * @category extra
+ */
+interface MapBackend<K, V> {
+    /** Monotonic mutation counter; increments on every visible state change. */
+    readonly version: number;
+    /** Raw entry count (may include expired entries until a read / prune removes them). */
+    readonly size: number;
+    /** Checks existence. May prune target key if expired; advances `version` if pruned. */
+    has(key: K): boolean;
+    /** Gets value. May prune target key if expired; advances `version` if pruned. */
+    get(key: K): V | undefined;
+    /**
+     * Sets a value with optional TTL (seconds). Throws `RangeError` if `ttl <= 0`.
+     * Applies LRU eviction if `maxSize` is configured. Advances `version`.
+     *
+     * **Atomicity contract:** Either fully succeeds or throws before any state
+     * change; `version` advances only on success.
+     */
+    set(key: K, value: V, ttl?: number): void;
+    /**
+     * Atomic bulk set. Pre-validates TTL once, then applies all entries. Advances
+     * `version` at most once (even for N entries). No-op if iterable is empty.
+     *
+     * **Consumes `entries` once** — pass an array if you want repeatability.
+     *
+     * **Atomicity contract:** TTL validation throws before any mutation. If the
+     * iterable itself throws mid-iteration, entries committed before the throw
+     * remain persisted AND `version` is bumped once (surfaced via finally) so
+     * the reactive wrapper emits a snapshot reflecting the partial state. "At
+     * most once" invariant is preserved.
+     */
+    setMany(entries: Iterable<readonly [K, V]>, ttl?: number): void;
+    /** Removes a key. Returns `true` if the key existed. Advances `version` only if true. */
+    delete(key: K): boolean;
+    /**
+     * Atomic bulk delete. Returns count removed. Advances `version` at most once
+     * (even for N keys). No-op if no keys were present. Consumes `keys` once.
+     */
+    deleteMany(keys: Iterable<K>): number;
+    /** Removes all entries. Returns count removed. Advances `version` only if non-zero. */
+    clear(): number;
+    /** Removes all expired entries. Returns count removed. Advances `version` only if non-zero. */
+    pruneExpired(): number;
+    /** Fresh snapshot of non-expired entries (does NOT mutate state). */
+    toMap(): ReadonlyMap<K, V>;
+}
+type NativeMapBackendOptions = {
+    maxSize?: number;
+    /** Default TTL in seconds. */
+    defaultTtl?: number;
+};
+/**
+ * Default `Map<K, {value, expiresAt}>` backend with optional per-key TTL and LRU cap.
+ *
+ * **Complexity:**
+ * - `has`, `get`, `delete`, `size`: O(1)
+ * - `set`: O(1) amortized (LRU touch + eviction)
+ * - `pruneExpired`, `toMap`: O(n)
+ *
+ * LRU order uses native `Map` insertion order. `get` / `has` on a live key "touches"
+ * it by delete-then-reinsert (moving it to the end). This touch does NOT advance
+ * `version` — it's an internal optimization; the externally visible snapshot
+ * preserves iteration order as of the last mutation. **Note:** because touch
+ * reorders the internal `_store` without emitting, an in-process consumer iterating
+ * `_store` directly (custom subclasses) could observe changing order; external
+ * subscribers only see `toMap()` snapshots which are defensively copied and stable.
+ *
+ * @category extra
+ */
+declare class NativeMapBackend<K, V> implements MapBackend<K, V> {
+    private _version;
+    private readonly _store;
+    private readonly _maxSize?;
+    private readonly _defaultTtl?;
+    constructor(options?: NativeMapBackendOptions);
+    get version(): number;
+    get size(): number;
+    has(key: K): boolean;
+    get(key: K): V | undefined;
+    set(key: K, value: V, ttl?: number): void;
+    setMany(entries: Iterable<readonly [K, V]>, ttl?: number): void;
+    delete(key: K): boolean;
+    deleteMany(keys: Iterable<K>): number;
+    clear(): number;
+    pruneExpired(): number;
+    toMap(): ReadonlyMap<K, V>;
+    private _resolveExpiresAt;
+    private _isExpired;
+    private _touchLru;
+    private _evictLruWhileOver;
+}
+/**
+ * Creates a reactive `Map` with optional per-key TTL and optional LRU max size.
+ *
+ * @param options - `name`, `maxSize`, `defaultTtl` (seconds), or custom `backend`.
+ * @returns `ReactiveMapBundle` — imperative methods (`has`/`get`/`set`/`setMany`/`delete`/
+ *   `deleteMany`/`clear`/`pruneExpired`), reactive `entries` node, and O(1)-ish `size`.
+ *
+ * @remarks
+ * **TTL:** Expiry is checked on `get`, `has`, `size`, `pruneExpired`, and before each
+ * snapshot emission (expired keys are pruned first). Reads that discover expired keys
+ * emit a snapshot so subscribers see state consistent with the read's return value.
+ * There is no background timer; monotonic-clock expiry is immune to wall-clock changes.
+ *
+ * **LRU:** Uses native `Map` insertion order — `get` / `has` refreshes position via
+ * delete-then-reinsert; under `maxSize` pressure the first key in iteration order is
+ * evicted. LRU touching does NOT trigger emission (internal optimization).
+ *
+ * **Backend:** The default {@link NativeMapBackend} owns LRU/TTL. For persistent /
+ * HAMT / shared-state semantics plug in a custom {@link MapBackend}. `maxSize` and
+ * `defaultTtl` on the options object are only applied to the default backend — if
+ * you supply `backend`, configure those on your backend directly.
+ *
+ * @example
+ * ```ts
+ * import { reactiveMap } from "@graphrefly/graphrefly-ts";
+ *
+ * const m = reactiveMap<string, number>({ name: "cache", maxSize: 100, defaultTtl: 60 });
+ * m.set("x", 1);
+ * m.setMany([["y", 2], ["z", 3]]);
+ * m.entries.subscribe((msgs) => { console.log(msgs); });
+ * ```
+ *
+ * @category extra
+ */
+declare function reactiveMap<K, V>(options?: ReactiveMapOptions<K, V>): ReactiveMapBundle<K, V>;
+
+export { type MapBackend as M, NativeMapBackend as N, type ReactiveMapBundle as R, type ReactiveMapOptions as a, type NativeMapBackendOptions as b, reactiveMap as r };