@graphrefly/graphrefly 0.34.0 → 0.35.0

package/dist/patterns/surface/index.d.ts

@@ -1,8 +1,9 @@
-export { C as CatalogFnEntry, a as CatalogSourceEntry, b as ConfigFieldSchema, F as FnFactory, G as GraphSpec, c as GraphSpecCatalog, d as GraphSpecFeedbackEdge, e as GraphSpecNode, f as GraphSpecTemplate, g as GraphSpecTemplateRef, h as GraphSpecValidation, S as SourceFactory } from '../../index-Chi9IiHJ.js';
-export { C as CreateGraphOptions, R as ReduceOptions, a as RestoreSnapshotOptions, S as SNAPSHOT_WIRE_VERSION, b as SaveSnapshotResult, c as SurfaceError, d as SurfaceErrorCode, e as SurfaceErrorPayload, f as asSurfaceError, g as createGraph, h as deleteSnapshot, i as diffSnapshots, l as listSnapshots, r as restoreSnapshot, j as runReduction, s as saveSnapshot } from '../../index-Bd2AjMQY.js';
-import '../../node-8qx0kgYt.js';
-import '../../graph-BROUZPG9.js';
-import '../../meta-CtDjj7cU.js';
+export { C as CatalogFnEntry, a as CatalogSourceEntry, b as ConfigFieldSchema, F as FnFactory, G as GraphSpec, c as GraphSpecCatalog, d as GraphSpecFeedbackEdge, e as GraphSpecNode, f as GraphSpecTemplate, g as GraphSpecTemplateRef, h as GraphSpecValidation, S as SourceFactory } from '../../index-DlccEIi3.js';
+export { C as CreateGraphOptions, R as ReduceOptions, a as RestoreSnapshotOptions, S as SNAPSHOT_WIRE_VERSION, b as SaveSnapshotResult, c as SurfaceError, d as SurfaceErrorCode, e as SurfaceErrorPayload, f as asSurfaceError, g as createGraph, h as deleteSnapshot, i as diffSnapshots, l as listSnapshots, r as restoreSnapshot, j as runReduction, s as saveSnapshot } from '../../index-Cot94_82.js';
+import '../../node-fSc-hCv8.js';
+import '../../graph-Cv-8x0ZI.js';
+import '../../meta-CC6EPdpK.js';
 import '../../extra/storage-core.js';
-import '../../types-B2LfBvNc.js';
+import '../../extra/storage-tiers.js';
+import '../../types-CidcBDuk.js';
 import '../../extra/sources.js';

package/dist/patterns/surface/index.js

@@ -1 +1 @@
-import{a,b,c,d,e,f,g,h,i,j}from"../../chunk-Y63GWRHO.js";import"../../chunk-U2T2XWDA.js";import"../../chunk-PBN426RU.js";import"../../chunk-L3KUKDZC.js";import"../../chunk-TZQPPQEQ.js";import"../../chunk-2JO6LXFT.js";import"../../chunk-SGS4OJGS.js";import"../../chunk-ESMPEKEV.js";import"../../chunk-533RQFF6.js";import"../../chunk-4F564IPP.js";import"../../chunk-4VVTGLXJ.js";import"../../chunk-T7EQPKOP.js";import"../../chunk-LYCLF26R.js";import"../../chunk-CK2E7BTU.js";import"../../chunk-QYADASLV.js";export{e as SNAPSHOT_WIRE_VERSION,a as SurfaceError,b as asSurfaceError,c as createGraph,j as deleteSnapshot,h as diffSnapshots,i as listSnapshots,g as restoreSnapshot,d as runReduction,f as saveSnapshot};
+import{a,b,c,d,e,f,g,h,i,j}from"../../chunk-PVUTRA5K.js";import"../../chunk-U347KVM4.js";import"../../chunk-ZGVA2SR5.js";import"../../chunk-O32GJOUJ.js";import"../../chunk-5KPIYVCC.js";import"../../chunk-SGS4OJGS.js";import"../../chunk-ESMPEKEV.js";import"../../chunk-533RQFF6.js";import"../../chunk-JJTF75VS.js";import"../../chunk-4VVTGLXJ.js";import"../../chunk-TZQPPQEQ.js";import"../../chunk-MQZWA3DF.js";import"../../chunk-LYCLF26R.js";import"../../chunk-CK2E7BTU.js";import"../../chunk-QYADASLV.js";export{e as SNAPSHOT_WIRE_VERSION,a as SurfaceError,b as asSurfaceError,c as createGraph,j as deleteSnapshot,h as diffSnapshots,i as listSnapshots,g as restoreSnapshot,d as runReduction,f as saveSnapshot};

package/dist/pipeline-graph-B85HUrWg.d.cts

@@ -0,0 +1,120 @@
+import { a as Node, c as NodeActions } from './node-fSc-hCv8.cjs';
+import { D as DerivedFn } from './sugar-DgaGJcI6.cjs';
+import { R as ReactiveLogBundle } from './reactive-log-CgbNqksB.cjs';
+import { G as Graph, a as GraphOptions } from './graph-kTltt95s.cjs';
+import { B as BaseAuditRecord } from './imperative-audit-ahAE65a9.cjs';
+
+/**
+ * PipelineGraph subclass (Wave A.1 Unit 1 — locked 2026-04-24).
+ *
+ * Specialized {@link Graph} that hosts workflow-DAG sugar methods:
+ * `task` / `classify` / `combine` / `approval` / `gate` / `catch`. The
+ * legacy `pipeline` / `task` / `branch` / `join` / `subPipeline` /
+ * `approval` / `gate` / `loop` / `onFailure` factories from
+ * {@link ./index} continue to work for migration ease; new code should
+ * prefer methods on this class.
+ *
+ * Construction: `pipelineGraph(name, opts?)` or `new PipelineGraph(name, opts)`.
+ */
+
+type StepRef = string | Node<unknown>;
+type DecisionAction = "approve" | "reject" | "modify" | "drop" | "open" | "close" | "teardown";
+interface Decision<T = unknown> extends BaseAuditRecord {
+    readonly action: DecisionAction;
+    readonly count?: number;
+    readonly items?: readonly T[];
+    readonly unflushed?: number;
+}
+/** Recommended `keyOf` for keyed-storage adapters (Audit 2 #7). */
+declare const decisionKeyOf: <T>(d: Decision<T>) => string;
+interface GateOptions<T = unknown> {
+    /** Bounded default 1000 (Audit 2 cross-cutting). `Infinity` is opt-in. */
+    maxPending?: number;
+    startOpen?: boolean;
+    /**
+     * Reactive auto-approve: gate's `latestIsOpen` mirrors this node's truthy
+     * value. False→true transition drains the pending queue.
+     *
+     * **`COMPLETE` / `ERROR` on the approver are silently ignored** — the gate
+     * stays in its current state. For permanent-open latching, use
+     * `onceOnly: true` (the first truthy approval latches; subsequent falsy
+     * values are ignored). The gate has no graceful terminal-state behavior
+     * for the approver itself.
+     */
+    approver?: Node<unknown>;
+    /** Latch — first truthy approval opens permanently; `close()` becomes no-op. */
+    onceOnly?: boolean;
+    meta?: Record<string, unknown>;
+    handlerVersion?: {
+        id: string;
+        version: string | number;
+    };
+}
+interface GateController<T> {
+    readonly node: Node<T>;
+    readonly pending: Node<readonly T[]>;
+    readonly count: Node<number>;
+    readonly isOpen: Node<boolean>;
+    readonly droppedCount: Node<number>;
+    readonly decisions: ReactiveLogBundle<Decision<T>>;
+    readonly audit: ReactiveLogBundle<Decision<T>>;
+    approve(count?: number): void;
+    reject(count?: number): void;
+    modify(fn: (value: T, index: number, pending: readonly T[]) => T, count?: number): void;
+    open(): void;
+    close(): void;
+}
+type TerminalCause = {
+    kind: "error";
+    error: unknown;
+} | {
+    kind: "complete";
+};
+interface CatchOptions<T> {
+    /** Default `"error"`; `"complete"` recovers COMPLETE; `"terminal"` recovers either. */
+    on?: "error" | "complete" | "terminal";
+    completeWhenDepsComplete?: boolean;
+    meta?: Record<string, unknown>;
+    handlerVersion?: {
+        id: string;
+        version: string | number;
+    };
+}
+interface ClassifyResult<TTag extends string, T> {
+    readonly tag: TTag | "error";
+    readonly value: T;
+    readonly error?: unknown;
+}
+declare class PipelineGraph extends Graph {
+    constructor(name: string, opts?: GraphOptions);
+    /**
+     * Register a workflow task (`derived` + auto-add). String deps resolve via
+     * `this.resolve(path)`; Node deps via {@link Graph.nameOf} O(1) lookup.
+     */
+    task<T>(name: string, run: DerivedFn<T>, opts?: {
+        deps?: ReadonlyArray<StepRef>;
+        meta?: Record<string, unknown>;
+    }): Node<T>;
+    classify<TTag extends string, T>(name: string, source: StepRef, tagger: (value: T) => TTag, opts?: {
+        meta?: Record<string, unknown>;
+    }): Node<ClassifyResult<TTag, T>>;
+    combine<R extends Record<string, StepRef>>(name: string, deps: R, opts?: {
+        meta?: Record<string, unknown>;
+    }): Node<{
+        [K in keyof R]: unknown;
+    }>;
+    gate<T>(name: string, source: StepRef, opts?: GateOptions<T>): GateController<T>;
+    /**
+     * Reactive approval step: passes items through when `approver` is truthy;
+     * holds at most one pending item (maxPending: 1) when falsy. A thin alias
+     * over `gate({ approver, maxPending: 1 })` — use `gate()` directly for
+     * finer control (maxPending, onceOnly, manual approve/reject).
+     */
+    approval<T>(name: string, source: StepRef, approver: Node<unknown>, opts?: Omit<GateOptions<T>, "approver" | "maxPending">): GateController<T>;
+    catch<T>(name: string, source: StepRef, recover: (cause: TerminalCause, actions: NodeActions) => T, opts?: CatchOptions<T>): Node<T>;
+    private _resolveStep;
+}
+/** Factory wrapper — `pipelineGraph(name, opts?)`. Equivalent to `new PipelineGraph(name, opts)`. */
+declare function pipelineGraph(name: string, opts?: GraphOptions): PipelineGraph;
+
+export { type CatchOptions as C, type Decision as D, type GateController as G, PipelineGraph as P, type StepRef as S, type TerminalCause as T, type ClassifyResult as a, type DecisionAction as b, type GateOptions as c, decisionKeyOf as d, pipelineGraph as p };

package/dist/pipeline-graph-HOTU4UG0.d.ts

@@ -0,0 +1,120 @@
+import { a as Node, c as NodeActions } from './node-fSc-hCv8.js';
+import { D as DerivedFn } from './sugar-D13E2M_z.js';
+import { R as ReactiveLogBundle } from './reactive-log-ByBb8g6A.js';
+import { G as Graph, a as GraphOptions } from './graph-Cv-8x0ZI.js';
+import { B as BaseAuditRecord } from './imperative-audit-ahAE65a9.js';
+
+/**
+ * PipelineGraph subclass (Wave A.1 Unit 1 — locked 2026-04-24).
+ *
+ * Specialized {@link Graph} that hosts workflow-DAG sugar methods:
+ * `task` / `classify` / `combine` / `approval` / `gate` / `catch`. The
+ * legacy `pipeline` / `task` / `branch` / `join` / `subPipeline` /
+ * `approval` / `gate` / `loop` / `onFailure` factories from
+ * {@link ./index} continue to work for migration ease; new code should
+ * prefer methods on this class.
+ *
+ * Construction: `pipelineGraph(name, opts?)` or `new PipelineGraph(name, opts)`.
+ */
+
+type StepRef = string | Node<unknown>;
+type DecisionAction = "approve" | "reject" | "modify" | "drop" | "open" | "close" | "teardown";
+interface Decision<T = unknown> extends BaseAuditRecord {
+    readonly action: DecisionAction;
+    readonly count?: number;
+    readonly items?: readonly T[];
+    readonly unflushed?: number;
+}
+/** Recommended `keyOf` for keyed-storage adapters (Audit 2 #7). */
+declare const decisionKeyOf: <T>(d: Decision<T>) => string;
+interface GateOptions<T = unknown> {
+    /** Bounded default 1000 (Audit 2 cross-cutting). `Infinity` is opt-in. */
+    maxPending?: number;
+    startOpen?: boolean;
+    /**
+     * Reactive auto-approve: gate's `latestIsOpen` mirrors this node's truthy
+     * value. False→true transition drains the pending queue.
+     *
+     * **`COMPLETE` / `ERROR` on the approver are silently ignored** — the gate
+     * stays in its current state. For permanent-open latching, use
+     * `onceOnly: true` (the first truthy approval latches; subsequent falsy
+     * values are ignored). The gate has no graceful terminal-state behavior
+     * for the approver itself.
+     */
+    approver?: Node<unknown>;
+    /** Latch — first truthy approval opens permanently; `close()` becomes no-op. */
+    onceOnly?: boolean;
+    meta?: Record<string, unknown>;
+    handlerVersion?: {
+        id: string;
+        version: string | number;
+    };
+}
+interface GateController<T> {
+    readonly node: Node<T>;
+    readonly pending: Node<readonly T[]>;
+    readonly count: Node<number>;
+    readonly isOpen: Node<boolean>;
+    readonly droppedCount: Node<number>;
+    readonly decisions: ReactiveLogBundle<Decision<T>>;
+    readonly audit: ReactiveLogBundle<Decision<T>>;
+    approve(count?: number): void;
+    reject(count?: number): void;
+    modify(fn: (value: T, index: number, pending: readonly T[]) => T, count?: number): void;
+    open(): void;
+    close(): void;
+}
+type TerminalCause = {
+    kind: "error";
+    error: unknown;
+} | {
+    kind: "complete";
+};
+interface CatchOptions<T> {
+    /** Default `"error"`; `"complete"` recovers COMPLETE; `"terminal"` recovers either. */
+    on?: "error" | "complete" | "terminal";
+    completeWhenDepsComplete?: boolean;
+    meta?: Record<string, unknown>;
+    handlerVersion?: {
+        id: string;
+        version: string | number;
+    };
+}
+interface ClassifyResult<TTag extends string, T> {
+    readonly tag: TTag | "error";
+    readonly value: T;
+    readonly error?: unknown;
+}
+declare class PipelineGraph extends Graph {
+    constructor(name: string, opts?: GraphOptions);
+    /**
+     * Register a workflow task (`derived` + auto-add). String deps resolve via
+     * `this.resolve(path)`; Node deps via {@link Graph.nameOf} O(1) lookup.
+     */
+    task<T>(name: string, run: DerivedFn<T>, opts?: {
+        deps?: ReadonlyArray<StepRef>;
+        meta?: Record<string, unknown>;
+    }): Node<T>;
+    classify<TTag extends string, T>(name: string, source: StepRef, tagger: (value: T) => TTag, opts?: {
+        meta?: Record<string, unknown>;
+    }): Node<ClassifyResult<TTag, T>>;
+    combine<R extends Record<string, StepRef>>(name: string, deps: R, opts?: {
+        meta?: Record<string, unknown>;
+    }): Node<{
+        [K in keyof R]: unknown;
+    }>;
+    gate<T>(name: string, source: StepRef, opts?: GateOptions<T>): GateController<T>;
+    /**
+     * Reactive approval step: passes items through when `approver` is truthy;
+     * holds at most one pending item (maxPending: 1) when falsy. A thin alias
+     * over `gate({ approver, maxPending: 1 })` — use `gate()` directly for
+     * finer control (maxPending, onceOnly, manual approve/reject).
+     */
+    approval<T>(name: string, source: StepRef, approver: Node<unknown>, opts?: Omit<GateOptions<T>, "approver" | "maxPending">): GateController<T>;
+    catch<T>(name: string, source: StepRef, recover: (cause: TerminalCause, actions: NodeActions) => T, opts?: CatchOptions<T>): Node<T>;
+    private _resolveStep;
+}
+/** Factory wrapper — `pipelineGraph(name, opts?)`. Equivalent to `new PipelineGraph(name, opts)`. */
+declare function pipelineGraph(name: string, opts?: GraphOptions): PipelineGraph;
+
+export { type CatchOptions as C, type Decision as D, type GateController as G, PipelineGraph as P, type StepRef as S, type TerminalCause as T, type ClassifyResult as a, type DecisionAction as b, type GateOptions as c, decisionKeyOf as d, pipelineGraph as p };

package/dist/{reactive-layout-DBJ3Vz-m.d.ts → reactive-layout-Btv0-efV.d.ts}

@@ -1,5 +1,5 @@
-import { a as Node } from './node-8qx0kgYt.js';
-import { G as Graph } from './graph-BROUZPG9.js';
+import { a as Node } from './node-fSc-hCv8.js';
+import { G as Graph } from './graph-Cv-8x0ZI.js';
 
 /** Pluggable measurement backend. */
 interface MeasurementAdapter {

package/dist/{reactive-layout-Dk9AOQb_.d.cts → reactive-layout-D9zqqaqK.d.cts}

@@ -1,5 +1,5 @@
-import { a as Node } from './node-8qx0kgYt.cjs';
-import { G as Graph } from './graph-DaoydJ_u.cjs';
+import { a as Node } from './node-fSc-hCv8.cjs';
+import { G as Graph } from './graph-kTltt95s.cjs';
 
 /** Pluggable measurement backend. */
 interface MeasurementAdapter {

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

@@ -0,0 +1,188 @@
+import { a as Node, V as VersioningLevel, f as NodeGuard } from './node-fSc-hCv8.js';
+import { AppendLogStorageTier } from './extra/storage-tiers.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;
+    /**
+     * Optional guard policy applied to the `entries` node. Use to deny
+     * external `write` while permitting `observe` / `signal` — eliminates the
+     * passthrough-derived pattern in CQRS event streams (Audit 1 #7).
+     */
+    guard?: NodeGuard;
+    /**
+     * 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>;
+};
+/**
+ * Discriminated view spec for {@link ReactiveLogBundle.view}. New `kind`s
+ * (e.g. `"filter"`, `"windowByTime"`) layer in without new methods.
+ */
+type ViewSpec<_T = unknown> = {
+    kind: "tail";
+    n: number;
+} | {
+    kind: "slice";
+    start: number;
+    stop?: number;
+} | {
+    kind: "fromCursor";
+    cursor: Node<number>;
+};
+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. */
+    at: (index: number) => T | undefined;
+    append: (value: T) => void;
+    /** Push all values, emit one snapshot. No-op if `values` is empty. */
+    appendMany: (values: readonly T[]) => void;
+    clear: () => void;
+    /** Remove the first `n` entries (clamped to `size`). */
+    trimHead: (n: number) => void;
+    /**
+     * Activate the {@link ReactiveLogBundle.lastValue} / {@link ReactiveLogBundle.hasLatest}
+     * companion nodes (lazy — installed on first call, reused thereafter).
+     * Returns `entries` so chaining reads naturally.
+     *
+     * **Companion-node access is on the bundle** (not `entries.meta`) because
+     * `Node.meta` is frozen at construction; bundle-level lazy properties
+     * give the same semantics with simpler ergonomics.
+     */
+    withLatest: () => Node<readonly T[]>;
+    /**
+     * Most-recently-appended value, or `undefined` if no entries exist (spec
+     * §5.12 SENTINEL alignment). Accessing this property activates the
+     * companion lazily — same as calling {@link ReactiveLogBundle.withLatest}.
+     *
+     * **Caveat when `T` itself includes `undefined`:** `lastValue.cache` is
+     * ambiguous (could mean "no entries yet" OR "an undefined value was
+     * appended"). Use {@link ReactiveLogBundle.hasLatest} to disambiguate.
+     */
+    readonly lastValue: Node<T | undefined>;
+    /** Reactive `true` once at least one entry has been appended. */
+    readonly hasLatest: Node<boolean>;
+    /**
+     * Reactive view per discriminated `ViewSpec`. Memoized per-spec — repeat
+     * calls with identical spec return the same node.
+     */
+    view: (spec: ViewSpec<T>) => Node<readonly T[]>;
+    /**
+     * Subscribe to `upstream` and append every DATA into this log. Returns a
+     * disposer. ERROR / COMPLETE on `upstream` propagate through the disposer
+     * (caller is responsible for terminal handling on the log).
+     */
+    attach: (upstream: Node<T>) => () => void;
+    /**
+     * Wire one or more append-log storage tiers. Each tier receives entries on
+     * every append wave; tier-internal flush/rollback honors the wave-as-
+     * transaction model (Audit 4). Returns a disposer.
+     */
+    attachStorage: (tiers: readonly AppendLogStorageTier<T>[]) => () => void;
+    /** Releases all cached views (tail + slice + fromCursor). */
+    disposeAllViews: () => void;
+    /** Releases all internal keepalives. Idempotent. */
+    dispose: () => void;
+};
+/**
+ * Storage contract for {@link reactiveLog}. Implementations own the mutable state and
+ * expose a monotonic `version` counter that increments on every structural change.
+ *
+ * **Audit 1:** `snapshot()` returns an immutable readonly view (codec encodes
+ * at the storage tier boundary). `restore(values)` replaces backend state on
+ * cold-tier startup load — fires one DATA emission for the restored shape.
+ *
+ * @category extra
+ */
+interface LogBackend<T> {
+    readonly version: number;
+    readonly 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[];
+    /** Immutable snapshot for codec serialization. Equivalent to `toArray()`. */
+    snapshot(): readonly T[];
+    /** Replace backend state with `values` (used by cold-tier restore). */
+    restore(values: readonly T[]): void;
+}
+/**
+ * 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.
+ *
+ * @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[];
+    snapshot(): readonly T[];
+    restore(values: readonly T[]): void;
+    private _rawAppend;
+}
+/**
+ * Creates an append-only reactive log with immutable array snapshots.
+ *
+ * @category extra
+ */
+declare function reactiveLog<T>(initial?: readonly T[], options?: ReactiveLogOptions<T>): ReactiveLogBundle<T>;
+/**
+ * Bundle returned by {@link mergeReactiveLogs}. `node` is the merged output;
+ * `dispose()` releases the internal subscriptions to all input logs and the
+ * keepalive on `node`. After dispose the merge stops responding to inputs
+ * but `node`'s last cached value remains queryable.
+ *
+ * @category extra
+ */
+interface MergedReactiveLog<T> {
+    readonly node: Node<readonly T[]>;
+    dispose(): void;
+}
+/**
+ * Fan-in helper that merges N reactive logs into a single time-ordered output
+ * by concatenation. Returns `{ node, dispose }`. Producer-pattern: subscribes
+ * to each input internally; COMPLETE on an input drops it from the active
+ * set; ERROR propagates per spec §2.2. Memoized by reference identity on the
+ * `logs` array — repeat calls with the same reference return the same bundle.
+ *
+ * Internal subscriptions are invisible in `describe()` (sanctioned per §24);
+ * `explain()` across the merge surfaces only the merged stream. Caller must
+ * `dispose()` when done to release subscriptions to input logs (no auto-GC
+ * because of the memoization map).
+ *
+ * @category extra
+ */
+declare function mergeReactiveLogs<T>(logs: readonly Node<readonly T[]>[]): MergedReactiveLog<T>;
+
+export { type LogBackend as L, type MergedReactiveLog as M, NativeLogBackend as N, type ReactiveLogBundle as R, type ViewSpec as V, type ReactiveLogOptions as a, mergeReactiveLogs as m, reactiveLog as r };

package/dist/reactive-log-CgbNqksB.d.cts

@@ -0,0 +1,188 @@
+import { a as Node, V as VersioningLevel, f as NodeGuard } from './node-fSc-hCv8.cjs';
+import { AppendLogStorageTier } from './extra/storage-tiers.cjs';
+
+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;
+    /**
+     * Optional guard policy applied to the `entries` node. Use to deny
+     * external `write` while permitting `observe` / `signal` — eliminates the
+     * passthrough-derived pattern in CQRS event streams (Audit 1 #7).
+     */
+    guard?: NodeGuard;
+    /**
+     * 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>;
+};
+/**
+ * Discriminated view spec for {@link ReactiveLogBundle.view}. New `kind`s
+ * (e.g. `"filter"`, `"windowByTime"`) layer in without new methods.
+ */
+type ViewSpec<_T = unknown> = {
+    kind: "tail";
+    n: number;
+} | {
+    kind: "slice";
+    start: number;
+    stop?: number;
+} | {
+    kind: "fromCursor";
+    cursor: Node<number>;
+};
+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. */
+    at: (index: number) => T | undefined;
+    append: (value: T) => void;
+    /** Push all values, emit one snapshot. No-op if `values` is empty. */
+    appendMany: (values: readonly T[]) => void;
+    clear: () => void;
+    /** Remove the first `n` entries (clamped to `size`). */
+    trimHead: (n: number) => void;
+    /**
+     * Activate the {@link ReactiveLogBundle.lastValue} / {@link ReactiveLogBundle.hasLatest}
+     * companion nodes (lazy — installed on first call, reused thereafter).
+     * Returns `entries` so chaining reads naturally.
+     *
+     * **Companion-node access is on the bundle** (not `entries.meta`) because
+     * `Node.meta` is frozen at construction; bundle-level lazy properties
+     * give the same semantics with simpler ergonomics.
+     */
+    withLatest: () => Node<readonly T[]>;
+    /**
+     * Most-recently-appended value, or `undefined` if no entries exist (spec
+     * §5.12 SENTINEL alignment). Accessing this property activates the
+     * companion lazily — same as calling {@link ReactiveLogBundle.withLatest}.
+     *
+     * **Caveat when `T` itself includes `undefined`:** `lastValue.cache` is
+     * ambiguous (could mean "no entries yet" OR "an undefined value was
+     * appended"). Use {@link ReactiveLogBundle.hasLatest} to disambiguate.
+     */
+    readonly lastValue: Node<T | undefined>;
+    /** Reactive `true` once at least one entry has been appended. */
+    readonly hasLatest: Node<boolean>;
+    /**
+     * Reactive view per discriminated `ViewSpec`. Memoized per-spec — repeat
+     * calls with identical spec return the same node.
+     */
+    view: (spec: ViewSpec<T>) => Node<readonly T[]>;
+    /**
+     * Subscribe to `upstream` and append every DATA into this log. Returns a
+     * disposer. ERROR / COMPLETE on `upstream` propagate through the disposer
+     * (caller is responsible for terminal handling on the log).
+     */
+    attach: (upstream: Node<T>) => () => void;
+    /**
+     * Wire one or more append-log storage tiers. Each tier receives entries on
+     * every append wave; tier-internal flush/rollback honors the wave-as-
+     * transaction model (Audit 4). Returns a disposer.
+     */
+    attachStorage: (tiers: readonly AppendLogStorageTier<T>[]) => () => void;
+    /** Releases all cached views (tail + slice + fromCursor). */
+    disposeAllViews: () => void;
+    /** Releases all internal keepalives. Idempotent. */
+    dispose: () => void;
+};
+/**
+ * Storage contract for {@link reactiveLog}. Implementations own the mutable state and
+ * expose a monotonic `version` counter that increments on every structural change.
+ *
+ * **Audit 1:** `snapshot()` returns an immutable readonly view (codec encodes
+ * at the storage tier boundary). `restore(values)` replaces backend state on
+ * cold-tier startup load — fires one DATA emission for the restored shape.
+ *
+ * @category extra
+ */
+interface LogBackend<T> {
+    readonly version: number;
+    readonly 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[];
+    /** Immutable snapshot for codec serialization. Equivalent to `toArray()`. */
+    snapshot(): readonly T[];
+    /** Replace backend state with `values` (used by cold-tier restore). */
+    restore(values: readonly T[]): void;
+}
+/**
+ * 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.
+ *
+ * @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[];
+    snapshot(): readonly T[];
+    restore(values: readonly T[]): void;
+    private _rawAppend;
+}
+/**
+ * Creates an append-only reactive log with immutable array snapshots.
+ *
+ * @category extra
+ */
+declare function reactiveLog<T>(initial?: readonly T[], options?: ReactiveLogOptions<T>): ReactiveLogBundle<T>;
+/**
+ * Bundle returned by {@link mergeReactiveLogs}. `node` is the merged output;
+ * `dispose()` releases the internal subscriptions to all input logs and the
+ * keepalive on `node`. After dispose the merge stops responding to inputs
+ * but `node`'s last cached value remains queryable.
+ *
+ * @category extra
+ */
+interface MergedReactiveLog<T> {
+    readonly node: Node<readonly T[]>;
+    dispose(): void;
+}
+/**
+ * Fan-in helper that merges N reactive logs into a single time-ordered output
+ * by concatenation. Returns `{ node, dispose }`. Producer-pattern: subscribes
+ * to each input internally; COMPLETE on an input drops it from the active
+ * set; ERROR propagates per spec §2.2. Memoized by reference identity on the
+ * `logs` array — repeat calls with the same reference return the same bundle.
+ *
+ * Internal subscriptions are invisible in `describe()` (sanctioned per §24);
+ * `explain()` across the merge surfaces only the merged stream. Caller must
+ * `dispose()` when done to release subscriptions to input logs (no auto-GC
+ * because of the memoization map).
+ *
+ * @category extra
+ */
+declare function mergeReactiveLogs<T>(logs: readonly Node<readonly T[]>[]): MergedReactiveLog<T>;
+
+export { type LogBackend as L, type MergedReactiveLog as M, NativeLogBackend as N, type ReactiveLogBundle as R, type ViewSpec as V, type ReactiveLogOptions as a, mergeReactiveLogs as m, reactiveLog as r };

package/dist/{reactive-map-LjwjcFaW.d.ts → reactive-map-CHyeCf4D.d.ts}

@@ -1,4 +1,4 @@
-import { a as Node, V as VersioningLevel, N as NodeOptions } from './node-8qx0kgYt.js';
+import { a as Node, V as VersioningLevel, N as NodeOptions } from './node-fSc-hCv8.js';
 
 type ReactiveMapOptions<K, V> = {
     /** Optional registry name for `describe()` / debugging. */

package/dist/{reactive-map-Cm89Hk0c.d.cts → reactive-map-DmgeADH8.d.cts}

@@ -1,4 +1,4 @@
-import { a as Node, V as VersioningLevel, N as NodeOptions } from './node-8qx0kgYt.cjs';
+import { a as Node, V as VersioningLevel, N as NodeOptions } from './node-fSc-hCv8.cjs';
 
 type ReactiveMapOptions<K, V> = {
     /** Optional registry name for `describe()` / debugging. */