@graphrefly/graphrefly 0.26.0 → 0.28.0

package/dist/index-HDpJe9hX.d.ts

@@ -0,0 +1,251 @@
+import { A as Actor, a as Node, P as PolicyRuleData, G as GuardAction } from './node-Cc1TniY8.js';
+import { G as Graph, a as GraphOptions, d as GraphPersistSnapshot, C as CausalChain } from './graph-BZGRXwOm.js';
+import { T as TopicGraph } from './index-B0c4cmIO.js';
+
+/**
+ * Audit, policy enforcement, and compliance export (roadmap §9.2).
+ *
+ * Three composed factories that wrap any {@link Graph} with the harness
+ * accountability layer:
+ *
+ * - {@link auditTrail} — reactive mutation log with by-node/by-actor/by-time
+ *   queries.
+ * - {@link policyEnforcer} — reactive ABAC enforcement; in `"audit"` mode
+ *   records would-be denials, in `"enforce"` mode pushes guards onto target
+ *   nodes so subsequent writes throw {@link GuardDenied}.
+ * - {@link complianceSnapshot} — point-in-time export of graph state +
+ *   audit trail + policies for regulatory archival.
+ *
+ * @module
+ */
+
+/** A single recorded mutation/event in an {@link AuditTrailGraph}. */
+interface AuditEntry {
+    seq: number;
+    timestamp_ns: number;
+    wall_clock_ns: number;
+    path: string;
+    type: "data" | "dirty" | "resolved" | "invalidate" | "pause" | "resume" | "complete" | "error" | "teardown";
+    actor?: Actor;
+    value?: unknown;
+    error?: unknown;
+    annotation?: string;
+}
+/** Options for {@link auditTrail}. */
+interface AuditTrailOptions {
+    name?: string;
+    graph?: GraphOptions;
+    /** Ring-buffer cap for the underlying `reactiveLog`. Default: unbounded. */
+    maxSize?: number;
+    /**
+     * Which event types to record. Default: `["data", "error", "complete",
+     * "teardown"]` — the user-meaningful set. Opt in to mid-wave protocol
+     * events (`"dirty"`, `"resolved"`, `"invalidate"`, `"pause"`, `"resume"`)
+     * by listing them explicitly. Note: those tier-1/tier-2 events do not
+     * carry an `actor` (no `lastMutation` populated) — record them only for
+     * protocol-level diagnostics.
+     */
+    includeTypes?: readonly AuditEntry["type"][];
+    /** Per-event filter; return false to skip. */
+    filter?: (entry: AuditEntry) => boolean;
+}
+/**
+ * Mounted audit log — `entries` exposes the reactive `AuditEntry[]`; query
+ * helpers are sync convenience wrappers over the cached snapshot.
+ */
+declare class AuditTrailGraph extends Graph {
+    readonly entries: Node<readonly AuditEntry[]>;
+    readonly count: Node<number>;
+    private readonly _log;
+    private readonly _target;
+    constructor(target: Graph, opts: AuditTrailOptions);
+    /** All entries currently in the ring (snapshot). */
+    all(): readonly AuditEntry[];
+    /** Entries matching `path`. Order preserved. */
+    byNode(path: string): readonly AuditEntry[];
+    /** Entries whose `actor.id` matches. Use `byActorType` for type filtering. */
+    byActor(actorId: string): readonly AuditEntry[];
+    /** Entries whose `actor.type` matches (e.g. `"llm"`, `"human"`). */
+    byActorType(type: string): readonly AuditEntry[];
+    /**
+     * Entries with `timestamp_ns` in `[start_ns, end_ns)` (end exclusive).
+     * Omit `end_ns` to query open-ended.
+     */
+    byTimeRange(start_ns: number, end_ns?: number): readonly AuditEntry[];
+    /** Reference to the audited graph (escape hatch for tooling). */
+    get target(): Graph;
+}
+/**
+ * Wraps any {@link Graph} with a reactive audit trail recording every event
+ * matching `includeTypes` (default: data + error + complete + teardown).
+ *
+ * Each entry carries `seq`, `timestamp_ns` (monotonic), `wall_clock_ns`,
+ * `path`, `type`, and — when available — `actor`, `value`, `error`, and the
+ * `graph.trace()` reasoning annotation for the path.
+ *
+ * The returned graph mounts an `entries` node + `count` derived. Query
+ * helpers (`byNode`, `byActor`, `byTimeRange`) operate on the cached
+ * snapshot synchronously.
+ */
+declare function auditTrail(target: Graph, opts?: AuditTrailOptions): AuditTrailGraph;
+/** A single policy denial recorded by {@link PolicyEnforcerGraph}. */
+interface PolicyViolation {
+    timestamp_ns: number;
+    wall_clock_ns: number;
+    path: string;
+    actor: Actor;
+    action: GuardAction;
+    mode: "audit" | "enforce";
+    /** `"observed"` (audit mode after-the-fact) or `"blocked"` (enforce mode pre-write). */
+    result: "observed" | "blocked";
+}
+/** Options for {@link policyEnforcer}. */
+interface PolicyEnforcerOptions {
+    name?: string;
+    graph?: GraphOptions;
+    /**
+     * `"audit"` (default) — observe events and record would-be denials;
+     * does not block writes. Audit mode requires `lastMutation` attribution
+     * on the audited node — anonymous/internal writes (no `actor` passed,
+     * unguarded node) are skipped silently because the policy cannot be
+     * evaluated without an actor.
+     *
+     * `"enforce"` — push guards onto target nodes so disallowed writes
+     * throw {@link GuardDenied}. Reverted on dispose.
+     */
+    mode?: "audit" | "enforce";
+    /**
+     * Restrict enforcement to specific node paths (qualified). When omitted,
+     * applies to every node visible in `target.describe()` at construction
+     * time (subgraphs are walked transitively) AND subscribes to the full
+     * topology tree via {@link watchTopologyTree}, so nodes added to
+     * `target` OR any transitively-mounted subgraph after construction are
+     * guarded automatically (enforce mode only).
+     *
+     * **Cost:** unrestricted mode runs `describe({detail:"minimal"})` once
+     * at construction (O(N) over the graph tree) plus one topology
+     * subscription per graph instance in the mount tree. Restricted mode
+     * skips both and disables dynamic coverage — callers providing
+     * `paths` must re-create on subgraph changes.
+     */
+    paths?: readonly string[];
+    /** Ring-buffer cap for the violations topic. Default: 1000. */
+    violationsLimit?: number;
+}
+/**
+ * Reactive ABAC enforcement layer. Policies are reactive — pass a
+ * `Node<readonly PolicyRuleData[]>` to allow LLMs (or any reactive source)
+ * to update them at runtime; the enforcer rebinds its internal
+ * {@link NodeGuard} on every push.
+ */
+declare class PolicyEnforcerGraph extends Graph {
+    readonly policies: Node<readonly PolicyRuleData[]>;
+    readonly violations: TopicGraph<PolicyViolation>;
+    readonly violationCount: Node<number>;
+    private readonly _target;
+    private readonly _mode;
+    private _currentGuard;
+    constructor(target: Graph, policies: readonly PolicyRuleData[] | Node<readonly PolicyRuleData[]>, opts: PolicyEnforcerOptions);
+    private _publishViolation;
+    /** Snapshot of recorded violations. */
+    all(): readonly PolicyViolation[];
+    get mode(): "audit" | "enforce";
+    get target(): Graph;
+}
+/**
+ * Wraps a {@link Graph} with reactive policy enforcement. Pass either a
+ * static rule list or a {@link Node} of rules (LLM-updatable). Records
+ * `PolicyViolation` entries to `violations` topic; in `"enforce"` mode also
+ * pushes guards onto target nodes so disallowed writes throw.
+ */
+declare function policyEnforcer(target: Graph, policies: readonly PolicyRuleData[] | Node<readonly PolicyRuleData[]>, opts?: PolicyEnforcerOptions): PolicyEnforcerGraph;
+/**
+ * Reactive {@link CausalChain} that recomputes whenever the audited graph
+ * changes. Returns a `Node<CausalChain>` suitable for subscription, mounting,
+ * or composition (e.g. inside `graphLens.why(node)`).
+ *
+ * **How it stays live:** an internal `version` state is bumped by an observer
+ * attached to `target.observe()`; the derived chain depends on `version`, so
+ * each mutation triggers a recompute. To avoid stalling on no-op events, only
+ * `data`, `error`, `complete`, and `teardown` bump the version (matching the
+ * audit defaults).
+ */
+/**
+ * @deprecated Use `graph.explain(from, to, { reactive: true, ... })` directly.
+ *   This free-function wrapper now dispatches to the consolidated
+ *   {@link Graph.explain} overload for mental-model consistency with
+ *   `describe` / `observe`. Will be removed pre-1.0.
+ */
+declare function reactiveExplainPath(target: Graph, from: string, to: string, opts?: {
+    maxDepth?: number;
+    name?: string;
+    findCycle?: boolean;
+}): {
+    node: Node<CausalChain>;
+    dispose: () => void;
+};
+/** Options for {@link complianceSnapshot}. */
+interface ComplianceSnapshotOptions {
+    audit?: AuditTrailGraph;
+    policies?: PolicyEnforcerGraph;
+    /** Actor recorded as the snapshot taker. */
+    actor?: Actor;
+}
+/** Output of {@link complianceSnapshot}. JSON-serializable. */
+interface ComplianceSnapshotResult {
+    format_version: 1;
+    timestamp_ns: number;
+    wall_clock_ns: number;
+    actor?: Actor;
+    graph: GraphPersistSnapshot;
+    audit?: {
+        count: number;
+        entries: AuditEntry[];
+    };
+    policies?: {
+        mode: "audit" | "enforce";
+        rules: readonly PolicyRuleData[];
+        violations: readonly PolicyViolation[];
+    };
+    /**
+     * Truncated SHA-256 hex (16 chars / ~64 bits) over a canonical encoding
+     * of every field above (excluding `fingerprint` itself). Deterministic
+     * across runs given identical inputs. Suitable for casual tamper-evidence
+     * and content-addressed dedup; for full cryptographic strength, hash the
+     * canonical JSON externally with Web Crypto / Node `crypto`.
+     */
+    fingerprint: string;
+}
+/**
+ * One-shot point-in-time export of a {@link Graph}'s state plus optional
+ * audit + policy bundles. Returns a JSON-serializable object with a
+ * deterministic truncated-SHA-256 {@link ComplianceSnapshotResult.fingerprint}
+ * over the canonical payload for tamper-evidence in regulatory archival.
+ *
+ * **Cryptographic strength:** the fingerprint is truncated to 64 bits for
+ * compact archival. Collision-resistant for casual integrity checks but NOT
+ * sufficient for adversarial tamper-evidence — pair with a full SHA-256
+ * (or stronger) over the canonical JSON when regulatory requirements demand
+ * collision resistance.
+ */
+declare function complianceSnapshot(target: Graph, opts?: ComplianceSnapshotOptions): ComplianceSnapshotResult;
+
+type index_AuditEntry = AuditEntry;
+type index_AuditTrailGraph = AuditTrailGraph;
+declare const index_AuditTrailGraph: typeof AuditTrailGraph;
+type index_AuditTrailOptions = AuditTrailOptions;
+type index_ComplianceSnapshotOptions = ComplianceSnapshotOptions;
+type index_ComplianceSnapshotResult = ComplianceSnapshotResult;
+type index_PolicyEnforcerGraph = PolicyEnforcerGraph;
+declare const index_PolicyEnforcerGraph: typeof PolicyEnforcerGraph;
+type index_PolicyEnforcerOptions = PolicyEnforcerOptions;
+type index_PolicyViolation = PolicyViolation;
+declare const index_auditTrail: typeof auditTrail;
+declare const index_complianceSnapshot: typeof complianceSnapshot;
+declare const index_policyEnforcer: typeof policyEnforcer;
+declare const index_reactiveExplainPath: typeof reactiveExplainPath;
+declare namespace index {
+  export { type index_AuditEntry as AuditEntry, index_AuditTrailGraph as AuditTrailGraph, type index_AuditTrailOptions as AuditTrailOptions, type index_ComplianceSnapshotOptions as ComplianceSnapshotOptions, type index_ComplianceSnapshotResult as ComplianceSnapshotResult, index_PolicyEnforcerGraph as PolicyEnforcerGraph, type index_PolicyEnforcerOptions as PolicyEnforcerOptions, type index_PolicyViolation as PolicyViolation, index_auditTrail as auditTrail, index_complianceSnapshot as complianceSnapshot, index_policyEnforcer as policyEnforcer, index_reactiveExplainPath as reactiveExplainPath };
+}
+
+export { type AuditEntry as A, type ComplianceSnapshotOptions as C, PolicyEnforcerGraph as P, type PolicyViolation as a, AuditTrailGraph as b, type AuditTrailOptions as c, type ComplianceSnapshotResult as d, type PolicyEnforcerOptions as e, auditTrail as f, complianceSnapshot as g, index as i, policyEnforcer as p, reactiveExplainPath as r };

package/dist/index-O6TgGUBV.d.cts

@@ -0,0 +1,195 @@
+import { b as Messages, A as Actor, C as COMPLETE, f as COMPLETE_MSG, g as COMPLETE_ONLY_BATCH, D as DATA, h as DEFAULT_ACTOR, i as DIRTY, j as DIRTY_MSG, k as DIRTY_ONLY_BATCH, l as DepRecord, E as ERROR, F as FnCtx, m as GlobalInspectorEvent, n as GlobalInspectorHook, o as GraphReFlyConfig, G as GuardAction, p as GuardDenied, q as GuardDeniedDetails, H as HashFn, I as INVALIDATE, r as INVALIDATE_MSG, s as INVALIDATE_ONLY_BATCH, M as Message, t as MessageContext, u as MessageTypeRegistration, v as MessageTypeRegistrationInput, a as Node, c as NodeActions, w as NodeCtx, e as NodeDescribeKind, x as NodeFn, d as NodeFnCleanup, y as NodeGuard, z as NodeImpl, B as NodeInspectorHook, J as NodeInspectorHookEvent, N as NodeOptions, K as NodeSink, L as NodeStatus, O as NodeTransportOptions, Q as NodeVersionInfo, R as OnMessageHandler, S as OnSubscribeHandler, T as PAUSE, U as PolicyAllow, W as PolicyDeny, P as PolicyRuleData, X as RESOLVED, Y as RESOLVED_MSG, Z as RESOLVED_ONLY_BATCH, _ as RESUME, $ as START, a0 as START_MSG, a1 as SubscribeContext, a2 as TEARDOWN, a3 as TEARDOWN_MSG, a4 as TEARDOWN_ONLY_BATCH, a5 as V0, a6 as V1, V as VersioningLevel, a7 as VersioningOptions, a8 as accessHintForGuard, a9 as advanceVersion, aa as configure, ab as createVersioning, ac as defaultConfig, ad as defaultHash, ae as isV1, af as node, ag as normalizeActor, ah as policy, ai as policyFromRules, aj as registerBuiltins } from './node-Cc1TniY8.cjs';
+import { D as DescribeDetail, a as DescribeField, b as DescribeNodeOutput, r as resolveDescribeFields } from './meta-Cgj6zeji.cjs';
+import { A as AutoTrackOptions, D as DerivedFn, a as DynamicFn, E as EffectFn, P as PipeOperator, b as ProducerFn, T as TrackFn, c as autoTrackNode, d as derived, e as dynamicNode, f as effect, p as pipe, g as producer, s as state } from './sugar-BV0htudb.cjs';
+
+/**
+ * Batch deferral for tier-3+ messages, plus per-node emit coalescing inside
+ * explicit `batch()` scopes.
+ *
+ * **Canonical invariant:** GRAPHREFLY-SPEC.md §1.3.7 — inside a batch,
+ * tier 0–2 signals propagate immediately; tier 3 (DATA/RESOLVED), tier 4
+ * (COMPLETE/ERROR), and tier 5 (TEARDOWN) are queued and drained in ascending
+ * phase order after the outermost `batch()` callback returns.
+ *
+ * **Per-node emit coalescing (Bug 2 fix, 2026-04-17).** Inside an explicit
+ * `batch()` scope, consecutive emissions from the same node accumulate in
+ * `NodeImpl._batchPendingMessages` (see JSDoc there) instead of each producing
+ * a separate downstream wave. K `.emit()` calls to the same source collapse to
+ * one coalesced `downWithBatch` call per child edge at batch end. Outside batch
+ * (or during drain), coalescing does NOT apply — each emit produces its own wave.
+ *
+ * **Phase vocabulary:**
+ * - Phase 1 = tiers 0–2 — immediate, never queued.
+ * - Phase 2 = tier 3 — {@link drainPhase2}. Value settlements.
+ * - Phase 3 = tier 4 — {@link drainPhase3}. Terminal signals.
+ * - Phase 4 = tier 5 — {@link drainPhase4}. TEARDOWN (unified deferral).
+ *
+ * Drain rule: fire any pending flush hooks first, then the lowest non-empty
+ * phase. Re-enqueues during drain (and hooks registered by reentrant batches
+ * inside subscriber callbacks) bump the loop back to the top so newly-added
+ * hooks and closures get processed.
+ */
+
+/**
+ * Returns whether the current call stack is inside a batch scope **or** while
+ * a deferred drain is in progress. Nested `downWithBatch` calls during drain
+ * still defer (they bump the drain loop).
+ */
+declare function isBatching(): boolean;
+/**
+ * Runs `fn` inside a batch scope. Nested `batch()` calls share one deferral
+ * queue. If `fn` throws, deferred work for the outer frame is discarded
+ * (unless a drain is already in progress — cross-language decision A4).
+ */
+declare function batch(fn: () => void): void;
+/**
+ * Deliver pre-sorted messages through `sink` with tier-based deferral applied.
+ *
+ * `messages` MUST be in ascending tier order (produced by `_frameBatch` in
+ * `node.ts`); the walker exploits that invariant to find phase cuts in one
+ * pass without re-sorting.
+ *
+ * Behavior:
+ * - Tier 0–2 — delivered synchronously.
+ * - Tier 3 — deferred to {@link drainPhase2} when batching, else synchronous.
+ * - Tier 4 — deferred to {@link drainPhase3} when batching, else synchronous.
+ * - Tier 5 — deferred to {@link drainPhase4} when batching, else synchronous.
+ *
+ * Tier-classification uses the caller-supplied `tierOf` so that batch stays
+ * decoupled from `GraphReFlyConfig`. NodeImpl passes `config.tierOf` (a
+ * pre-bound closure built once in the config constructor) at the emit site;
+ * alternate configs can pass their own lookup.
+ */
+declare function downWithBatch(sink: (messages: Messages) => void, messages: Messages, tierOf: (t: symbol) => number): void;
+
+/**
+ * Centralised timestamp utilities.
+ *
+ * Convention: all graphrefly-ts timestamps use nanoseconds (`_ns` suffix).
+ *
+ * - {@link monotonicNs} — monotonic clock (ordering, durations, timeline events).
+ * - {@link wallClockNs} — wall-clock (mutation attribution, cron emission).
+ *
+ * **Precision limits (JS platform):**
+ *
+ * - `monotonicNs`: effective ~microsecond precision. `performance.now()` returns
+ *   milliseconds with ~5µs resolution; the last 3 digits of the nanosecond value
+ *   are always zero. Python's `time.monotonic_ns()` gives true nanoseconds.
+ *
+ * - `wallClockNs`: ~256ns precision loss at current epoch. `Date.now() * 1e6`
+ *   produces values around 1.8×10¹⁸ which exceed IEEE 754's 2⁵³ safe integer
+ *   limit. Python's `time.time_ns()` (arbitrary-precision `int`) has no loss.
+ *   In practice this is irrelevant — JS is single-threaded, so sub-microsecond
+ *   timestamp collisions cannot occur.
+ */
+/** Monotonic nanosecond timestamp via `performance.now()`. */
+declare function monotonicNs(): number;
+/** Wall-clock nanosecond timestamp via `Date.now()`. */
+declare function wallClockNs(): number;
+
+/**
+ * Core layer: message protocol, node primitive, lifecycle (Phase 0).
+ */
+
+declare const index_Actor: typeof Actor;
+declare const index_AutoTrackOptions: typeof AutoTrackOptions;
+declare const index_COMPLETE: typeof COMPLETE;
+declare const index_COMPLETE_MSG: typeof COMPLETE_MSG;
+declare const index_COMPLETE_ONLY_BATCH: typeof COMPLETE_ONLY_BATCH;
+declare const index_DATA: typeof DATA;
+declare const index_DEFAULT_ACTOR: typeof DEFAULT_ACTOR;
+declare const index_DIRTY: typeof DIRTY;
+declare const index_DIRTY_MSG: typeof DIRTY_MSG;
+declare const index_DIRTY_ONLY_BATCH: typeof DIRTY_ONLY_BATCH;
+declare const index_DepRecord: typeof DepRecord;
+declare const index_DerivedFn: typeof DerivedFn;
+declare const index_DescribeDetail: typeof DescribeDetail;
+declare const index_DescribeField: typeof DescribeField;
+declare const index_DescribeNodeOutput: typeof DescribeNodeOutput;
+declare const index_DynamicFn: typeof DynamicFn;
+declare const index_ERROR: typeof ERROR;
+declare const index_EffectFn: typeof EffectFn;
+declare const index_FnCtx: typeof FnCtx;
+declare const index_GlobalInspectorEvent: typeof GlobalInspectorEvent;
+declare const index_GlobalInspectorHook: typeof GlobalInspectorHook;
+declare const index_GraphReFlyConfig: typeof GraphReFlyConfig;
+declare const index_GuardAction: typeof GuardAction;
+declare const index_GuardDenied: typeof GuardDenied;
+declare const index_GuardDeniedDetails: typeof GuardDeniedDetails;
+declare const index_HashFn: typeof HashFn;
+declare const index_INVALIDATE: typeof INVALIDATE;
+declare const index_INVALIDATE_MSG: typeof INVALIDATE_MSG;
+declare const index_INVALIDATE_ONLY_BATCH: typeof INVALIDATE_ONLY_BATCH;
+declare const index_Message: typeof Message;
+declare const index_MessageContext: typeof MessageContext;
+declare const index_MessageTypeRegistration: typeof MessageTypeRegistration;
+declare const index_MessageTypeRegistrationInput: typeof MessageTypeRegistrationInput;
+declare const index_Messages: typeof Messages;
+declare const index_Node: typeof Node;
+declare const index_NodeActions: typeof NodeActions;
+declare const index_NodeCtx: typeof NodeCtx;
+declare const index_NodeDescribeKind: typeof NodeDescribeKind;
+declare const index_NodeFn: typeof NodeFn;
+declare const index_NodeFnCleanup: typeof NodeFnCleanup;
+declare const index_NodeGuard: typeof NodeGuard;
+declare const index_NodeImpl: typeof NodeImpl;
+declare const index_NodeInspectorHook: typeof NodeInspectorHook;
+declare const index_NodeInspectorHookEvent: typeof NodeInspectorHookEvent;
+declare const index_NodeOptions: typeof NodeOptions;
+declare const index_NodeSink: typeof NodeSink;
+declare const index_NodeStatus: typeof NodeStatus;
+declare const index_NodeTransportOptions: typeof NodeTransportOptions;
+declare const index_NodeVersionInfo: typeof NodeVersionInfo;
+declare const index_OnMessageHandler: typeof OnMessageHandler;
+declare const index_OnSubscribeHandler: typeof OnSubscribeHandler;
+declare const index_PAUSE: typeof PAUSE;
+declare const index_PipeOperator: typeof PipeOperator;
+declare const index_PolicyAllow: typeof PolicyAllow;
+declare const index_PolicyDeny: typeof PolicyDeny;
+declare const index_PolicyRuleData: typeof PolicyRuleData;
+declare const index_ProducerFn: typeof ProducerFn;
+declare const index_RESOLVED: typeof RESOLVED;
+declare const index_RESOLVED_MSG: typeof RESOLVED_MSG;
+declare const index_RESOLVED_ONLY_BATCH: typeof RESOLVED_ONLY_BATCH;
+declare const index_RESUME: typeof RESUME;
+declare const index_START: typeof START;
+declare const index_START_MSG: typeof START_MSG;
+declare const index_SubscribeContext: typeof SubscribeContext;
+declare const index_TEARDOWN: typeof TEARDOWN;
+declare const index_TEARDOWN_MSG: typeof TEARDOWN_MSG;
+declare const index_TEARDOWN_ONLY_BATCH: typeof TEARDOWN_ONLY_BATCH;
+declare const index_TrackFn: typeof TrackFn;
+declare const index_V0: typeof V0;
+declare const index_V1: typeof V1;
+declare const index_VersioningLevel: typeof VersioningLevel;
+declare const index_VersioningOptions: typeof VersioningOptions;
+declare const index_accessHintForGuard: typeof accessHintForGuard;
+declare const index_advanceVersion: typeof advanceVersion;
+declare const index_autoTrackNode: typeof autoTrackNode;
+declare const index_batch: typeof batch;
+declare const index_configure: typeof configure;
+declare const index_createVersioning: typeof createVersioning;
+declare const index_defaultConfig: typeof defaultConfig;
+declare const index_defaultHash: typeof defaultHash;
+declare const index_derived: typeof derived;
+declare const index_downWithBatch: typeof downWithBatch;
+declare const index_dynamicNode: typeof dynamicNode;
+declare const index_effect: typeof effect;
+declare const index_isBatching: typeof isBatching;
+declare const index_isV1: typeof isV1;
+declare const index_monotonicNs: typeof monotonicNs;
+declare const index_node: typeof node;
+declare const index_normalizeActor: typeof normalizeActor;
+declare const index_pipe: typeof pipe;
+declare const index_policy: typeof policy;
+declare const index_policyFromRules: typeof policyFromRules;
+declare const index_producer: typeof producer;
+declare const index_registerBuiltins: typeof registerBuiltins;
+declare const index_resolveDescribeFields: typeof resolveDescribeFields;
+declare const index_state: typeof state;
+declare const index_wallClockNs: typeof wallClockNs;
+declare namespace index {
+  export { index_Actor as Actor, index_AutoTrackOptions as AutoTrackOptions, index_COMPLETE as COMPLETE, index_COMPLETE_MSG as COMPLETE_MSG, index_COMPLETE_ONLY_BATCH as COMPLETE_ONLY_BATCH, index_DATA as DATA, index_DEFAULT_ACTOR as DEFAULT_ACTOR, index_DIRTY as DIRTY, index_DIRTY_MSG as DIRTY_MSG, index_DIRTY_ONLY_BATCH as DIRTY_ONLY_BATCH, index_DepRecord as DepRecord, index_DerivedFn as DerivedFn, index_DescribeDetail as DescribeDetail, index_DescribeField as DescribeField, index_DescribeNodeOutput as DescribeNodeOutput, index_DynamicFn as DynamicFn, index_ERROR as ERROR, index_EffectFn as EffectFn, index_FnCtx as FnCtx, index_GlobalInspectorEvent as GlobalInspectorEvent, index_GlobalInspectorHook as GlobalInspectorHook, index_GraphReFlyConfig as GraphReFlyConfig, index_GuardAction as GuardAction, index_GuardDenied as GuardDenied, index_GuardDeniedDetails as GuardDeniedDetails, index_HashFn as HashFn, index_INVALIDATE as INVALIDATE, index_INVALIDATE_MSG as INVALIDATE_MSG, index_INVALIDATE_ONLY_BATCH as INVALIDATE_ONLY_BATCH, index_Message as Message, index_MessageContext as MessageContext, index_MessageTypeRegistration as MessageTypeRegistration, index_MessageTypeRegistrationInput as MessageTypeRegistrationInput, index_Messages as Messages, index_Node as Node, index_NodeActions as NodeActions, index_NodeCtx as NodeCtx, index_NodeDescribeKind as NodeDescribeKind, index_NodeFn as NodeFn, index_NodeFnCleanup as NodeFnCleanup, index_NodeGuard as NodeGuard, index_NodeImpl as NodeImpl, index_NodeInspectorHook as NodeInspectorHook, index_NodeInspectorHookEvent as NodeInspectorHookEvent, index_NodeOptions as NodeOptions, index_NodeSink as NodeSink, index_NodeStatus as NodeStatus, index_NodeTransportOptions as NodeTransportOptions, index_NodeVersionInfo as NodeVersionInfo, index_OnMessageHandler as OnMessageHandler, index_OnSubscribeHandler as OnSubscribeHandler, index_PAUSE as PAUSE, index_PipeOperator as PipeOperator, index_PolicyAllow as PolicyAllow, index_PolicyDeny as PolicyDeny, index_PolicyRuleData as PolicyRuleData, index_ProducerFn as ProducerFn, index_RESOLVED as RESOLVED, index_RESOLVED_MSG as RESOLVED_MSG, index_RESOLVED_ONLY_BATCH as RESOLVED_ONLY_BATCH, index_RESUME as RESUME, index_START as START, index_START_MSG as START_MSG, index_SubscribeContext as SubscribeContext, index_TEARDOWN as TEARDOWN, index_TEARDOWN_MSG as TEARDOWN_MSG, index_TEARDOWN_ONLY_BATCH as TEARDOWN_ONLY_BATCH, index_TrackFn as TrackFn, index_V0 as V0, index_V1 as V1, index_VersioningLevel as VersioningLevel, index_VersioningOptions as VersioningOptions, index_accessHintForGuard as accessHintForGuard, index_advanceVersion as advanceVersion, index_autoTrackNode as autoTrackNode, index_batch as batch, index_configure as configure, index_createVersioning as createVersioning, index_defaultConfig as defaultConfig, index_defaultHash as defaultHash, index_derived as derived, index_downWithBatch as downWithBatch, index_dynamicNode as dynamicNode, index_effect as effect, index_isBatching as isBatching, index_isV1 as isV1, index_monotonicNs as monotonicNs, index_node as node, index_normalizeActor as normalizeActor, index_pipe as pipe, index_policy as policy, index_policyFromRules as policyFromRules, index_producer as producer, index_registerBuiltins as registerBuiltins, index_resolveDescribeFields as resolveDescribeFields, index_state as state, index_wallClockNs as wallClockNs };
+}
+
+export { isBatching as a, batch as b, downWithBatch as d, index as i, monotonicNs as m, wallClockNs as w };

package/dist/{index-B4MP_8V_.d.cts → index-Oi8d8w4R.d.cts}

@@ -1,4 +1,4 @@
-import { G as Graph } from './graph-6tZ5jEzr.cjs';
+import { G as Graph } from './graph-D48Qw9Cg.cjs';
 
 /** Zustand-compatible Store API. */
 interface StoreApi<T> {

package/dist/{index-BW1z3BN9.d.ts → index-ROpQmGjE.d.ts}

@@ -1,6 +1,6 @@
-import { M as MeasurementAdapter, P as PreparedSegment, L as LineBreaksResult, C as CharPosition, a as LayoutCursor, I as Interval, b as LayoutLine, c as LayoutNextLineContext, d as LayoutNextLineResult, R as ReactiveLayoutBundle, e as ReactiveLayoutOptions, S as SegmentBreakKind, f as SegmentMeasureStats, g as analyzeAndMeasure, h as carveTextLineSlots, i as computeCharPositions, j as computeLineBreaks, l as layoutNextLine, r as reactiveLayout } from './reactive-layout-D9gejYXE.js';
-import { N as Node } from './node-C_IBuvX2.js';
-import { G as Graph } from './graph-DQ69XU0g.js';
+import { M as MeasurementAdapter, P as PreparedSegment, L as LineBreaksResult, C as CharPosition, a as LayoutCursor, I as Interval, b as LayoutLine, c as LayoutNextLineContext, d as LayoutNextLineResult, R as ReactiveLayoutBundle, e as ReactiveLayoutOptions, S as SegmentBreakKind, f as SegmentMeasureStats, g as analyzeAndMeasure, h as carveTextLineSlots, i as computeCharPositions, j as computeLineBreaks, l as layoutNextLine, r as reactiveLayout } from './reactive-layout-D8u4wuUR.js';
+import { a as Node } from './node-Cc1TniY8.js';
+import { G as Graph } from './graph-BZGRXwOm.js';
 
 /**
  * MeasurementAdapter implementations (roadmap §7.1 — pluggable backends).
@@ -355,6 +355,17 @@ type ReactiveFlowLayoutOptions = {
     obstacles?: Obstacle[];
     /** Minimum slot width (px) below which a slot is discarded rather than squeezed. Default `20`. */
     minSlotWidth?: number;
+    /**
+     * Vertical gap (px) inserted after a hard-break segment (the spacing
+     * between paragraphs). When unset (or explicitly set to `null`), tracks
+     * the current `lineHeight` reactively — one line-height of visible
+     * paragraph gap, matching dense editorial layouts. Set to `0` for
+     * paragraph-preserving layout that reclaims the break line; set larger
+     * (e.g. `2 * lineHeight`) for looser manuscript settings. Reactive —
+     * update via `setParagraphSpacing(n)` or restore to track-lineHeight
+     * mode via `setParagraphSpacing(null)`.
+     */
+    paragraphSpacing?: number | null;
 };
 /** Result bundle from `reactiveFlowLayout`. */
 type ReactiveFlowLayoutBundle = {
@@ -365,6 +376,7 @@ type ReactiveFlowLayoutBundle = {
     setContainer: (c: FlowContainer) => void;
     setColumns: (c: FlowColumns) => void;
     setObstacles: (o: Obstacle[]) => void;
+    setParagraphSpacing: (ps: number | null) => void;
     segments: Node<PreparedSegment[]>;
     flowLines: Node<PositionedLine[]>;
 };
@@ -377,6 +389,17 @@ type FlowLinesResult = {
      *  container couldn't fit all text. */
     cursor: LayoutCursor;
 };
+/** Optional tuning knobs for {@link computeFlowLines}. */
+type ComputeFlowLinesOptions = {
+    /**
+     * Vertical gap (px) inserted after a hard-break segment (the spacing
+     * between paragraphs). Defaults to `lineHeight` — one line-height of
+     * visible paragraph gap, which matches dense editorial layouts. Set to
+     * `0` for paragraph-preserving layout that reclaims the break line;
+     * set larger (e.g. `2 * lineHeight`) for looser manuscript settings.
+     */
+    paragraphSpacing?: number;
+};
 /**
  * Lay out `segments` across N columns, wrapping each line around `obstacles`.
  * Pure function — no reactive wiring. Exported for testing and for consumers
@@ -385,7 +408,7 @@ type FlowLinesResult = {
  * `carveTextLineSlots` guarantees left-to-right-ordered, non-overlapping slots,
  * so this function does not sort them.
  */
-declare function computeFlowLines(segments: PreparedSegment[], container: FlowContainer, columns: FlowColumns, obstacles: Obstacle[], lineHeight: number, minSlotWidth: number): FlowLinesResult;
+declare function computeFlowLines(segments: PreparedSegment[], container: FlowContainer, columns: FlowColumns, obstacles: Obstacle[], lineHeight: number, minSlotWidth: number, opts?: ComputeFlowLinesOptions): FlowLinesResult;
 /**
  * Create a reactive flow-layout graph: N columns of text wrapping around
  * shape obstacles. Re-runs only the dependent derived nodes on any input
@@ -433,6 +456,7 @@ type index_CircleObstacle = CircleObstacle;
 type index_CliMeasureAdapter = CliMeasureAdapter;
 declare const index_CliMeasureAdapter: typeof CliMeasureAdapter;
 type index_CliMeasureAdapterOptions = CliMeasureAdapterOptions;
+type index_ComputeFlowLinesOptions = ComputeFlowLinesOptions;
 type index_ContentBlock = ContentBlock;
 type index_FlowColumns = FlowColumns;
 type index_FlowContainer = FlowContainer;
@@ -485,7 +509,7 @@ declare const index_reactiveFlowLayout: typeof reactiveFlowLayout;
 declare const index_reactiveLayout: typeof reactiveLayout;
 declare const index_rectIntervalForBand: typeof rectIntervalForBand;
 declare namespace index {
-  export { type index_BlockAdapters as BlockAdapters, index_CanvasMeasureAdapter as CanvasMeasureAdapter, type index_CanvasMeasureAdapterOptions as CanvasMeasureAdapterOptions, type index_CanvasModule as CanvasModule, index_CharPosition as CharPosition, type index_CircleObstacle as CircleObstacle, index_CliMeasureAdapter as CliMeasureAdapter, type index_CliMeasureAdapterOptions as CliMeasureAdapterOptions, type index_ContentBlock as ContentBlock, type index_FlowColumns as FlowColumns, type index_FlowContainer as FlowContainer, type index_FlowLinesResult as FlowLinesResult, type index_ImageMeasurer as ImageMeasurer, index_ImageSizeAdapter as ImageSizeAdapter, index_Interval as Interval, index_LayoutCursor as LayoutCursor, index_LayoutLine as LayoutLine, index_LayoutNextLineContext as LayoutNextLineContext, index_LayoutNextLineResult as LayoutNextLineResult, index_LineBreaksResult as LineBreaksResult, type index_MeasuredBlock as MeasuredBlock, index_MeasurementAdapter as MeasurementAdapter, index_NodeCanvasMeasureAdapter as NodeCanvasMeasureAdapter, type index_Obstacle as Obstacle, type index_PositionedBlock as PositionedBlock, type index_PositionedLine as PositionedLine, index_PrecomputedAdapter as PrecomputedAdapter, type index_PrecomputedAdapterOptions as PrecomputedAdapterOptions, index_PreparedSegment as PreparedSegment, type index_ReactiveBlockLayoutBundle as ReactiveBlockLayoutBundle, type index_ReactiveBlockLayoutOptions as ReactiveBlockLayoutOptions, type index_ReactiveFlowLayoutBundle as ReactiveFlowLayoutBundle, type index_ReactiveFlowLayoutOptions as ReactiveFlowLayoutOptions, index_ReactiveLayoutBundle as ReactiveLayoutBundle, index_ReactiveLayoutOptions as ReactiveLayoutOptions, type index_RectObstacle as RectObstacle, index_SegmentBreakKind as SegmentBreakKind, index_SegmentMeasureStats as SegmentMeasureStats, index_SvgBoundsAdapter as SvgBoundsAdapter, type index_SvgMeasurer as SvgMeasurer, index_analyzeAndMeasure as analyzeAndMeasure, index_carveTextLineSlots as carveTextLineSlots, index_circleIntervalForBand as circleIntervalForBand, index_computeBlockFlow as computeBlockFlow, index_computeCharPositions as computeCharPositions, index_computeFlowLines as computeFlowLines, index_computeLineBreaks as computeLineBreaks, index_computeTotalHeight as computeTotalHeight, index_layoutNextLine as layoutNextLine, index_measureBlock as measureBlock, index_measureBlocks as measureBlocks, index_reactiveBlockLayout as reactiveBlockLayout, index_reactiveFlowLayout as reactiveFlowLayout, index_reactiveLayout as reactiveLayout, index_rectIntervalForBand as rectIntervalForBand };
+  export { type index_BlockAdapters as BlockAdapters, index_CanvasMeasureAdapter as CanvasMeasureAdapter, type index_CanvasMeasureAdapterOptions as CanvasMeasureAdapterOptions, type index_CanvasModule as CanvasModule, index_CharPosition as CharPosition, type index_CircleObstacle as CircleObstacle, index_CliMeasureAdapter as CliMeasureAdapter, type index_CliMeasureAdapterOptions as CliMeasureAdapterOptions, type index_ComputeFlowLinesOptions as ComputeFlowLinesOptions, type index_ContentBlock as ContentBlock, type index_FlowColumns as FlowColumns, type index_FlowContainer as FlowContainer, type index_FlowLinesResult as FlowLinesResult, type index_ImageMeasurer as ImageMeasurer, index_ImageSizeAdapter as ImageSizeAdapter, index_Interval as Interval, index_LayoutCursor as LayoutCursor, index_LayoutLine as LayoutLine, index_LayoutNextLineContext as LayoutNextLineContext, index_LayoutNextLineResult as LayoutNextLineResult, index_LineBreaksResult as LineBreaksResult, type index_MeasuredBlock as MeasuredBlock, index_MeasurementAdapter as MeasurementAdapter, index_NodeCanvasMeasureAdapter as NodeCanvasMeasureAdapter, type index_Obstacle as Obstacle, type index_PositionedBlock as PositionedBlock, type index_PositionedLine as PositionedLine, index_PrecomputedAdapter as PrecomputedAdapter, type index_PrecomputedAdapterOptions as PrecomputedAdapterOptions, index_PreparedSegment as PreparedSegment, type index_ReactiveBlockLayoutBundle as ReactiveBlockLayoutBundle, type index_ReactiveBlockLayoutOptions as ReactiveBlockLayoutOptions, type index_ReactiveFlowLayoutBundle as ReactiveFlowLayoutBundle, type index_ReactiveFlowLayoutOptions as ReactiveFlowLayoutOptions, index_ReactiveLayoutBundle as ReactiveLayoutBundle, index_ReactiveLayoutOptions as ReactiveLayoutOptions, type index_RectObstacle as RectObstacle, index_SegmentBreakKind as SegmentBreakKind, index_SegmentMeasureStats as SegmentMeasureStats, index_SvgBoundsAdapter as SvgBoundsAdapter, type index_SvgMeasurer as SvgMeasurer, index_analyzeAndMeasure as analyzeAndMeasure, index_carveTextLineSlots as carveTextLineSlots, index_circleIntervalForBand as circleIntervalForBand, index_computeBlockFlow as computeBlockFlow, index_computeCharPositions as computeCharPositions, index_computeFlowLines as computeFlowLines, index_computeLineBreaks as computeLineBreaks, index_computeTotalHeight as computeTotalHeight, index_layoutNextLine as layoutNextLine, index_measureBlock as measureBlock, index_measureBlocks as measureBlocks, index_reactiveBlockLayout as reactiveBlockLayout, index_reactiveFlowLayout as reactiveFlowLayout, index_reactiveLayout as reactiveLayout, index_rectIntervalForBand as rectIntervalForBand };
 }
 
-export { rectIntervalForBand as A, type BlockAdapters as B, CanvasMeasureAdapter as C, type FlowColumns as F, type ImageMeasurer as I, type MeasuredBlock as M, NodeCanvasMeasureAdapter as N, type Obstacle as O, type PositionedBlock as P, type ReactiveBlockLayoutBundle as R, SvgBoundsAdapter as S, type CanvasMeasureAdapterOptions as a, type CanvasModule as b, type CircleObstacle as c, CliMeasureAdapter as d, type CliMeasureAdapterOptions as e, type ContentBlock as f, type FlowContainer as g, type FlowLinesResult as h, index as i, ImageSizeAdapter as j, type PositionedLine as k, PrecomputedAdapter as l, type PrecomputedAdapterOptions as m, type ReactiveBlockLayoutOptions as n, type ReactiveFlowLayoutBundle as o, type ReactiveFlowLayoutOptions as p, type RectObstacle as q, type SvgMeasurer as r, circleIntervalForBand as s, computeBlockFlow as t, computeFlowLines as u, computeTotalHeight as v, measureBlock as w, measureBlocks as x, reactiveBlockLayout as y, reactiveFlowLayout as z };
+export { reactiveFlowLayout as A, type BlockAdapters as B, CanvasMeasureAdapter as C, rectIntervalForBand as D, type FlowColumns as F, type ImageMeasurer as I, type MeasuredBlock as M, NodeCanvasMeasureAdapter as N, type Obstacle as O, type PositionedBlock as P, type ReactiveBlockLayoutBundle as R, SvgBoundsAdapter as S, type CanvasMeasureAdapterOptions as a, type CanvasModule as b, type CircleObstacle as c, CliMeasureAdapter as d, type CliMeasureAdapterOptions as e, type ComputeFlowLinesOptions as f, type ContentBlock as g, type FlowContainer as h, index as i, type FlowLinesResult as j, ImageSizeAdapter as k, type PositionedLine as l, PrecomputedAdapter as m, type PrecomputedAdapterOptions as n, type ReactiveBlockLayoutOptions as o, type ReactiveFlowLayoutBundle as p, type ReactiveFlowLayoutOptions as q, type RectObstacle as r, type SvgMeasurer as s, circleIntervalForBand as t, computeBlockFlow as u, computeFlowLines as v, computeTotalHeight as w, measureBlock as x, measureBlocks as y, reactiveBlockLayout as z };