@graphrefly/graphrefly 0.27.0 → 0.28.0

package/dist/index-DpHe5e0Q.d.ts

@@ -0,0 +1,186 @@
+import { a as Node, N as NodeOptions } from './node-Cc1TniY8.js';
+import { a as GraphOptions, G as Graph } from './graph-BZGRXwOm.js';
+
+/**
+ * Reduction primitives (roadmap §8.1).
+ *
+ * Composable building blocks for taking heterogeneous massive inputs and producing
+ * prioritized, auditable, human-actionable output. Each primitive is either a Graph
+ * factory or a Node factory, built on top of core + extra primitives.
+ *
+ * @module
+ */
+
+type StepRef = string | Node<unknown>;
+/** A named stage for {@link funnel}. */
+type FunnelStage = {
+    /** Stage name (mounted as subgraph). */
+    name: string;
+    /** Builder: receives a sub-graph, should add an `"input"` and `"output"` node. */
+    build: (sub: Graph) => void;
+};
+/** Options for {@link funnel}. */
+type FunnelOptions = GraphOptions & {
+    meta?: Record<string, unknown>;
+};
+/**
+ * Multi-source merge with sequential reduction stages.
+ *
+ * Sources are merged into a single stream. Each stage is a named subgraph
+ * (mounted via `graph.mount()`). Stages connect linearly:
+ * `merged → stage[0].input → stage[0].output → stage[1].input → ...`
+ *
+ * @param name - Graph name.
+ * @param sources - Input nodes to merge.
+ * @param stages - Sequential reduction stages.
+ * @param opts - Optional graph/meta options.
+ * @returns Graph with `"merged"` and mounted stage subgraphs.
+ *
+ * @category patterns
+ */
+declare function funnel<T>(name: string, sources: ReadonlyArray<Node<T>>, stages: ReadonlyArray<FunnelStage>, opts?: FunnelOptions): Graph;
+/** Options for {@link feedback}. */
+type FeedbackOptions = {
+    /** Maximum feedback iterations before stopping (default: 10). */
+    maxIterations?: number;
+    /** Optional budget gate node path for cost-bounded iteration. */
+    budgetNode?: StepRef;
+    meta?: Record<string, unknown>;
+};
+/**
+ * Introduce a bounded reactive cycle into an existing graph.
+ *
+ * When `condition` emits a non-null DATA value, the feedback effect routes it
+ * back to the `reentry` state node — creating a cycle. Bounded by
+ * `maxIterations` (default 10). The counter node (`__feedback_<condition>`)
+ * is the source of truth — reset it to 0 to allow more iterations.
+ *
+ * To remove the feedback cycle, call `graph.remove("__feedback_<condition>")`.
+ *
+ * @param graph - Existing graph to augment with a feedback cycle.
+ * @param condition - Path to a node whose DATA triggers feedback.
+ * @param reentry - Path to a state node that receives the feedback value.
+ * @param opts - Iteration bounds and metadata.
+ * @returns The same graph (mutated with feedback nodes added).
+ *
+ * @category patterns
+ */
+declare function feedback(graph: Graph, condition: string, reentry: string, opts?: FeedbackOptions): Graph;
+/** A reactive constraint for {@link budgetGate}. */
+type BudgetConstraint<T = unknown> = {
+    /** Constraint node whose value is checked. */
+    node: Node<T>;
+    /** Returns `true` when the constraint is satisfied (budget available). */
+    check: (value: T) => boolean;
+};
+/** Options for {@link budgetGate}. */
+type BudgetGateOptions = Omit<NodeOptions<unknown>, "describeKind" | "name" | "meta"> & {
+    meta?: Record<string, unknown>;
+};
+/**
+ * Pass-through that respects reactive constraint nodes.
+ *
+ * DATA flows through when all constraints are satisfied. When any constraint
+ * is exceeded, PAUSE is sent upstream and DATA is buffered. When constraints
+ * relax, RESUME is sent and buffered DATA flushes.
+ *
+ * @param source - Input node.
+ * @param constraints - Reactive constraint checks.
+ * @param opts - Optional node options.
+ * @returns Gated node.
+ *
+ * @category patterns
+ */
+declare function budgetGate<T>(source: Node<T>, constraints: ReadonlyArray<BudgetConstraint>, opts?: BudgetGateOptions): Node<T>;
+/** A scored item with full breakdown. */
+type ScoredItem<T = unknown> = {
+    /** Original value. */
+    value: T;
+    /** Final weighted score. */
+    score: number;
+    /** Per-signal breakdown: signal index → weighted contribution. */
+    breakdown: number[];
+};
+/** Options for {@link scorer}. */
+type ScorerOptions = Omit<NodeOptions<unknown>, "describeKind" | "name" | "meta"> & {
+    meta?: Record<string, unknown>;
+    /** Custom scoring function per signal. Default: identity (signal value IS the score). */
+    scoreFns?: ReadonlyArray<(value: unknown) => number>;
+};
+/**
+ * Reactive multi-signal scoring with live weights.
+ *
+ * Each source emits items to score. Weights are reactive state nodes that
+ * LLM or human can adjust live. Output is sorted scored items with full
+ * breakdown.
+ *
+ * @param sources - Signal nodes (each emits a numeric score dimension).
+ * @param weights - Reactive weight nodes (one per source).
+ * @param opts - Optional node/meta options.
+ * @returns Node emitting scored output.
+ *
+ * @category patterns
+ */
+declare function scorer(sources: ReadonlyArray<Node<number>>, weights: ReadonlyArray<Node<number>>, opts?: ScorerOptions): Node<ScoredItem<number[]>>;
+/** A single effectiveness record for an action×context pair. */
+type EffectivenessEntry = {
+    readonly key: string;
+    readonly attempts: number;
+    readonly successes: number;
+    readonly successRate: number;
+};
+/** Snapshot shape for the effectiveness tracker node. */
+type EffectivenessSnapshot = ReadonlyMap<string, EffectivenessEntry>;
+/** Bundle returned by {@link effectivenessTracker}. */
+interface EffectivenessTrackerBundle {
+    /** Reactive node — current effectiveness map snapshot. */
+    readonly node: Node<EffectivenessSnapshot>;
+    /** Record a completed action (success or failure). */
+    record(key: string, success: boolean): void;
+    /** Look up effectiveness for a specific key. */
+    lookup(key: string): EffectivenessEntry | undefined;
+    /** Tear down internal keepalive subscriptions. */
+    dispose(): void;
+}
+/** Options for {@link effectivenessTracker}. */
+type EffectivenessTrackerOptions = {
+    /** Name for the reactive map (default "effectiveness-entries"). */
+    name?: string;
+};
+/**
+ * Generic action×context → success rate tracker.
+ *
+ * Generalized from the harness `strategyModel` pattern. Tracks attempts and
+ * successes per string key, exposes a reactive snapshot node, and provides
+ * `record()` / `lookup()` methods.
+ *
+ * Use cases: A/B testing, routing optimization, cache policy tuning, retry
+ * strategy selection — any domain that tracks effectiveness per action.
+ *
+ * @param opts - Optional configuration.
+ * @returns Bundle with reactive node, record(), lookup(), dispose().
+ */
+declare function effectivenessTracker(opts?: EffectivenessTrackerOptions): EffectivenessTrackerBundle;
+
+type index_BudgetConstraint<T = unknown> = BudgetConstraint<T>;
+type index_BudgetGateOptions = BudgetGateOptions;
+type index_EffectivenessEntry = EffectivenessEntry;
+type index_EffectivenessSnapshot = EffectivenessSnapshot;
+type index_EffectivenessTrackerBundle = EffectivenessTrackerBundle;
+type index_EffectivenessTrackerOptions = EffectivenessTrackerOptions;
+type index_FeedbackOptions = FeedbackOptions;
+type index_FunnelOptions = FunnelOptions;
+type index_FunnelStage = FunnelStage;
+type index_ScoredItem<T = unknown> = ScoredItem<T>;
+type index_ScorerOptions = ScorerOptions;
+type index_StepRef = StepRef;
+declare const index_budgetGate: typeof budgetGate;
+declare const index_effectivenessTracker: typeof effectivenessTracker;
+declare const index_feedback: typeof feedback;
+declare const index_funnel: typeof funnel;
+declare const index_scorer: typeof scorer;
+declare namespace index {
+  export { type index_BudgetConstraint as BudgetConstraint, type index_BudgetGateOptions as BudgetGateOptions, type index_EffectivenessEntry as EffectivenessEntry, type index_EffectivenessSnapshot as EffectivenessSnapshot, type index_EffectivenessTrackerBundle as EffectivenessTrackerBundle, type index_EffectivenessTrackerOptions as EffectivenessTrackerOptions, type index_FeedbackOptions as FeedbackOptions, type index_FunnelOptions as FunnelOptions, type index_FunnelStage as FunnelStage, type index_ScoredItem as ScoredItem, type index_ScorerOptions as ScorerOptions, type index_StepRef as StepRef, index_budgetGate as budgetGate, index_effectivenessTracker as effectivenessTracker, index_feedback as feedback, index_funnel as funnel, index_scorer as scorer };
+}
+
+export { type BudgetConstraint as B, type EffectivenessEntry as E, type FeedbackOptions as F, type ScoredItem as S, type BudgetGateOptions as a, type EffectivenessSnapshot as b, type EffectivenessTrackerBundle as c, type EffectivenessTrackerOptions as d, type FunnelOptions as e, type FunnelStage as f, type ScorerOptions as g, type StepRef as h, index as i, budgetGate as j, effectivenessTracker as k, feedback as l, funnel as m, scorer as s };

package/dist/index-DraikLjn.d.ts

@@ -0,0 +1,86 @@
+import { a as Node } from './node-Cc1TniY8.js';
+import { G as Graph, a as GraphOptions } from './graph-BZGRXwOm.js';
+
+/**
+ * Job queue patterns (roadmap §4.2).
+ *
+ * Queue / flow primitives modeled as graph factories:
+ * - `jobQueue()` — claim/ack/nack workflow with reactive depth.
+ * - `jobFlow()` — multi-stage queue chain.
+ *
+ * Topic / subscription / hub primitives live in `patterns/messaging`.
+ */
+
+type JobState = "queued" | "inflight";
+type JobEnvelope<T> = {
+    id: string;
+    payload: T;
+    attempts: number;
+    metadata: Readonly<Record<string, unknown>>;
+    state: JobState;
+};
+type JobQueueOptions = {
+    graph?: GraphOptions;
+};
+declare class JobQueueGraph<T> extends Graph {
+    private readonly _pending;
+    private readonly _jobs;
+    private _seq;
+    readonly pending: Node<readonly string[]>;
+    readonly jobs: Node<ReadonlyMap<string, JobEnvelope<T>>>;
+    readonly depth: Node<number>;
+    constructor(name: string, opts?: JobQueueOptions);
+    enqueue(payload: T, opts?: {
+        id?: string;
+        metadata?: Record<string, unknown>;
+    }): string;
+    claim(limit?: number): readonly JobEnvelope<T>[];
+    ack(id: string): boolean;
+    nack(id: string, opts?: {
+        requeue?: boolean;
+    }): boolean;
+}
+type JobFlowOptions = {
+    graph?: GraphOptions;
+    stages?: readonly string[];
+    maxPerPump?: number;
+};
+declare class JobFlowGraph<T> extends Graph {
+    private readonly _stageNames;
+    private readonly _queues;
+    private readonly _completed;
+    readonly completed: Node<readonly JobEnvelope<T>[]>;
+    readonly completedCount: Node<number>;
+    constructor(name: string, opts?: JobFlowOptions);
+    stages(): readonly string[];
+    queue(stage: string): JobQueueGraph<T>;
+    enqueue(payload: T, opts?: {
+        id?: string;
+        metadata?: Record<string, unknown>;
+    }): string;
+    retainedCompleted(): readonly JobEnvelope<T>[];
+}
+/**
+ * Creates a Pulsar-inspired job queue graph with claim/ack/nack workflow.
+ */
+declare function jobQueue<T>(name: string, opts?: JobQueueOptions): JobQueueGraph<T>;
+/**
+ * Creates an autonomous multi-stage queue chain graph.
+ */
+declare function jobFlow<T>(name: string, opts?: JobFlowOptions): JobFlowGraph<T>;
+
+type index_JobEnvelope<T> = JobEnvelope<T>;
+type index_JobFlowGraph<T> = JobFlowGraph<T>;
+declare const index_JobFlowGraph: typeof JobFlowGraph;
+type index_JobFlowOptions = JobFlowOptions;
+type index_JobQueueGraph<T> = JobQueueGraph<T>;
+declare const index_JobQueueGraph: typeof JobQueueGraph;
+type index_JobQueueOptions = JobQueueOptions;
+type index_JobState = JobState;
+declare const index_jobFlow: typeof jobFlow;
+declare const index_jobQueue: typeof jobQueue;
+declare namespace index {
+  export { type index_JobEnvelope as JobEnvelope, index_JobFlowGraph as JobFlowGraph, type index_JobFlowOptions as JobFlowOptions, index_JobQueueGraph as JobQueueGraph, type index_JobQueueOptions as JobQueueOptions, type index_JobState as JobState, index_jobFlow as jobFlow, index_jobQueue as jobQueue };
+}
+
+export { type JobEnvelope as J, JobFlowGraph as a, type JobFlowOptions as b, JobQueueGraph as c, type JobQueueOptions as d, type JobState as e, jobQueue as f, index as i, jobFlow as j };

package/dist/{index-D8wS_PeY.d.cts → index-DxsnAMWD.d.cts}

@@ -1,12 +1,12 @@
-import { i as index$2 } from './index-ByQxazQJ.cjs';
-import { i as index$3 } from './index-DO_6JN9Z.cjs';
-import { i as index$4 } from './index-DlLp-2Xn.cjs';
-import { i as index$5 } from './index-DYme44FM.cjs';
-import { N as Node } from './node-BmerH3kS.cjs';
-import { i as index$6 } from './index-Xi3u0HCQ.cjs';
-import { i as index$7 } from './index-VHqptjhu.cjs';
-import { i as index$8 } from './index-B1tloyhO.cjs';
-import { i as index$9 } from './index-B6EhDnjH.cjs';
+import { i as index$2 } from './index-CRO83MmV.cjs';
+import { i as index$3 } from './index-Cyojz0AE.cjs';
+import { i as index$4 } from './index-cByzxQIC.cjs';
+import { i as index$5 } from './index-DL-rYJrx.cjs';
+import { a as Node } from './node-Cc1TniY8.cjs';
+import { i as index$6 } from './index-B_agccPe.cjs';
+import { i as index$7 } from './index-B2pwesl9.cjs';
+import { i as index$8 } from './index-D_NwnRYS.cjs';
+import { i as index$9 } from './index-Oi8d8w4R.cjs';
 
 /**
  * Options for creating signals.

package/dist/{messaging-Gt4LPbyA.d.cts → index-DyxjtScX.d.cts}

@@ -1,13 +1,18 @@
-import { N as Node } from './node-BmerH3kS.cjs';
-import { a as Graph, G as GraphOptions } from './graph-DNCrvZSn.cjs';
+import { a as Node } from './node-Cc1TniY8.cjs';
+import { G as Graph, a as GraphOptions } from './graph-D48Qw9Cg.cjs';
 
 /**
  * Messaging patterns (roadmap §4.2).
  *
- * Pulsar-inspired messaging features modeled as graph factories:
- * - `topic()` for append-only topic streams
- * - `subscription()` for cursor-based consumers
- * - `jobQueue()` for queue claim/ack flow
+ * Pulsar-inspired messaging primitives modeled as graph factories:
+ * - `topic()` for append-only topic streams with a retained window.
+ * - `subscription()` for cursor-based consumers.
+ * - `topicBridge()` for autonomous topic-to-topic relay.
+ * - `messagingHub()` for a lazy topic registry.
+ *
+ * Job queue / job flow primitives live in `patterns/job-queue` — they are a
+ * distinct domain that happens to share reactive-log / reactive-map
+ * infrastructure with topics.
  */
 
 type TopicOptions = {
@@ -62,55 +67,6 @@ declare class SubscriptionGraph<T> extends Graph {
         ack?: boolean;
     }): readonly T[];
 }
-type JobState = "queued" | "inflight";
-type JobEnvelope<T> = {
-    id: string;
-    payload: T;
-    attempts: number;
-    metadata: Readonly<Record<string, unknown>>;
-    state: JobState;
-};
-type JobQueueOptions = {
-    graph?: GraphOptions;
-};
-declare class JobQueueGraph<T> extends Graph {
-    private readonly _pending;
-    private readonly _jobs;
-    private _seq;
-    readonly pending: Node<readonly string[]>;
-    readonly jobs: Node<ReadonlyMap<string, JobEnvelope<T>>>;
-    readonly depth: Node<number>;
-    constructor(name: string, opts?: JobQueueOptions);
-    enqueue(payload: T, opts?: {
-        id?: string;
-        metadata?: Record<string, unknown>;
-    }): string;
-    claim(limit?: number): readonly JobEnvelope<T>[];
-    ack(id: string): boolean;
-    nack(id: string, opts?: {
-        requeue?: boolean;
-    }): boolean;
-}
-type JobFlowOptions = {
-    graph?: GraphOptions;
-    stages?: readonly string[];
-    maxPerPump?: number;
-};
-declare class JobFlowGraph<T> extends Graph {
-    private readonly _stageNames;
-    private readonly _queues;
-    private readonly _completed;
-    readonly completed: Node<readonly JobEnvelope<T>[]>;
-    readonly completedCount: Node<number>;
-    constructor(name: string, opts?: JobFlowOptions);
-    stages(): readonly string[];
-    queue(stage: string): JobQueueGraph<T>;
-    enqueue(payload: T, opts?: {
-        id?: string;
-        metadata?: Record<string, unknown>;
-    }): string;
-    retainedCompleted(): readonly JobEnvelope<T>[];
-}
 type TopicBridgeOptions<TIn, TOut> = {
     graph?: GraphOptions;
     cursor?: number;
@@ -210,7 +166,7 @@ declare function topic<T>(name: string, opts?: TopicOptions): TopicGraph<T>;
  *
  * @example
  * ```ts
- * import { messagingHub } from "@graphrefly/graphrefly-ts";
+ * import { messagingHub } from "@graphrefly/graphrefly/patterns/messaging";
  *
  * const hub = messagingHub("main", { defaultTopicOptions: { retainedLimit: 256 } });
  * hub.publish("orders", { id: 1 });
@@ -223,47 +179,29 @@ declare function messagingHub(name: string, opts?: MessagingHubOptions): Messagi
  * Creates a cursor-based subscription graph over a topic.
  */
 declare function subscription<T>(name: string, topicGraph: TopicGraph<T>, opts?: SubscriptionOptions): SubscriptionGraph<T>;
-/**
- * Creates a Pulsar-inspired job queue graph with claim/ack/nack workflow.
- */
-declare function jobQueue<T>(name: string, opts?: JobQueueOptions): JobQueueGraph<T>;
-/**
- * Creates an autonomous multi-stage queue chain graph.
- */
-declare function jobFlow<T>(name: string, opts?: JobFlowOptions): JobFlowGraph<T>;
 /**
  * Creates an autonomous cursor-based topic relay graph.
  */
 declare function topicBridge<TIn, TOut = TIn>(name: string, sourceTopic: TopicGraph<TIn>, targetTopic: TopicGraph<TOut>, opts?: TopicBridgeOptions<TIn, TOut>): TopicBridgeGraph<TIn, TOut>;
 
-type messaging_JobEnvelope<T> = JobEnvelope<T>;
-type messaging_JobFlowGraph<T> = JobFlowGraph<T>;
-declare const messaging_JobFlowGraph: typeof JobFlowGraph;
-type messaging_JobFlowOptions = JobFlowOptions;
-type messaging_JobQueueGraph<T> = JobQueueGraph<T>;
-declare const messaging_JobQueueGraph: typeof JobQueueGraph;
-type messaging_JobQueueOptions = JobQueueOptions;
-type messaging_JobState = JobState;
-type messaging_MessagingHubGraph = MessagingHubGraph;
-declare const messaging_MessagingHubGraph: typeof MessagingHubGraph;
-type messaging_MessagingHubOptions = MessagingHubOptions;
-type messaging_SubscriptionGraph<T> = SubscriptionGraph<T>;
-declare const messaging_SubscriptionGraph: typeof SubscriptionGraph;
-type messaging_SubscriptionOptions = SubscriptionOptions;
-type messaging_TopicBridgeGraph<TIn, TOut = TIn> = TopicBridgeGraph<TIn, TOut>;
-declare const messaging_TopicBridgeGraph: typeof TopicBridgeGraph;
-type messaging_TopicBridgeOptions<TIn, TOut> = TopicBridgeOptions<TIn, TOut>;
-type messaging_TopicGraph<T> = TopicGraph<T>;
-declare const messaging_TopicGraph: typeof TopicGraph;
-type messaging_TopicOptions = TopicOptions;
-declare const messaging_jobFlow: typeof jobFlow;
-declare const messaging_jobQueue: typeof jobQueue;
-declare const messaging_messagingHub: typeof messagingHub;
-declare const messaging_subscription: typeof subscription;
-declare const messaging_topic: typeof topic;
-declare const messaging_topicBridge: typeof topicBridge;
-declare namespace messaging {
-  export { type messaging_JobEnvelope as JobEnvelope, messaging_JobFlowGraph as JobFlowGraph, type messaging_JobFlowOptions as JobFlowOptions, messaging_JobQueueGraph as JobQueueGraph, type messaging_JobQueueOptions as JobQueueOptions, type messaging_JobState as JobState, messaging_MessagingHubGraph as MessagingHubGraph, type messaging_MessagingHubOptions as MessagingHubOptions, messaging_SubscriptionGraph as SubscriptionGraph, type messaging_SubscriptionOptions as SubscriptionOptions, messaging_TopicBridgeGraph as TopicBridgeGraph, type messaging_TopicBridgeOptions as TopicBridgeOptions, messaging_TopicGraph as TopicGraph, type messaging_TopicOptions as TopicOptions, messaging_jobFlow as jobFlow, messaging_jobQueue as jobQueue, messaging_messagingHub as messagingHub, messaging_subscription as subscription, messaging_topic as topic, messaging_topicBridge as topicBridge };
+type index_MessagingHubGraph = MessagingHubGraph;
+declare const index_MessagingHubGraph: typeof MessagingHubGraph;
+type index_MessagingHubOptions = MessagingHubOptions;
+type index_SubscriptionGraph<T> = SubscriptionGraph<T>;
+declare const index_SubscriptionGraph: typeof SubscriptionGraph;
+type index_SubscriptionOptions = SubscriptionOptions;
+type index_TopicBridgeGraph<TIn, TOut = TIn> = TopicBridgeGraph<TIn, TOut>;
+declare const index_TopicBridgeGraph: typeof TopicBridgeGraph;
+type index_TopicBridgeOptions<TIn, TOut> = TopicBridgeOptions<TIn, TOut>;
+type index_TopicGraph<T> = TopicGraph<T>;
+declare const index_TopicGraph: typeof TopicGraph;
+type index_TopicOptions = TopicOptions;
+declare const index_messagingHub: typeof messagingHub;
+declare const index_subscription: typeof subscription;
+declare const index_topic: typeof topic;
+declare const index_topicBridge: typeof topicBridge;
+declare namespace index {
+  export { index_MessagingHubGraph as MessagingHubGraph, type index_MessagingHubOptions as MessagingHubOptions, index_SubscriptionGraph as SubscriptionGraph, type index_SubscriptionOptions as SubscriptionOptions, index_TopicBridgeGraph as TopicBridgeGraph, type index_TopicBridgeOptions as TopicBridgeOptions, index_TopicGraph as TopicGraph, type index_TopicOptions as TopicOptions, index_messagingHub as messagingHub, index_subscription as subscription, index_topic as topic, index_topicBridge as topicBridge };
 }
 
-export { TopicGraph as T, messaging as m };
+export { MessagingHubGraph as M, SubscriptionGraph as S, TopicGraph as T, type MessagingHubOptions as a, type SubscriptionOptions as b, TopicBridgeGraph as c, type TopicBridgeOptions as d, type TopicOptions as e, topicBridge as f, index as i, messagingHub as m, subscription as s, topic as t };

package/dist/{audit-ClmqGOCx.d.cts → index-HDpJe9hX.d.ts}

@@ -1,6 +1,6 @@
-import { A as Actor, N as Node, P as PolicyRuleData, k as GuardAction } from './node-BmerH3kS.cjs';
-import { a as Graph, G as GraphOptions, s as GraphPersistSnapshot, C as CausalChain } from './graph-DNCrvZSn.cjs';
-import { T as TopicGraph } from './messaging-Gt4LPbyA.cjs';
+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).
@@ -29,7 +29,7 @@ interface AuditEntry {
     actor?: Actor;
     value?: unknown;
     error?: unknown;
-    reason?: string;
+    annotation?: string;
 }
 /** Options for {@link auditTrail}. */
 interface AuditTrailOptions {
@@ -170,6 +170,12 @@ declare function policyEnforcer(target: Graph, policies: readonly PolicyRuleData
  * `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;
@@ -224,22 +230,22 @@ interface ComplianceSnapshotResult {
  */
 declare function complianceSnapshot(target: Graph, opts?: ComplianceSnapshotOptions): ComplianceSnapshotResult;
 
-type audit_AuditEntry = AuditEntry;
-type audit_AuditTrailGraph = AuditTrailGraph;
-declare const audit_AuditTrailGraph: typeof AuditTrailGraph;
-type audit_AuditTrailOptions = AuditTrailOptions;
-type audit_ComplianceSnapshotOptions = ComplianceSnapshotOptions;
-type audit_ComplianceSnapshotResult = ComplianceSnapshotResult;
-type audit_PolicyEnforcerGraph = PolicyEnforcerGraph;
-declare const audit_PolicyEnforcerGraph: typeof PolicyEnforcerGraph;
-type audit_PolicyEnforcerOptions = PolicyEnforcerOptions;
-type audit_PolicyViolation = PolicyViolation;
-declare const audit_auditTrail: typeof auditTrail;
-declare const audit_complianceSnapshot: typeof complianceSnapshot;
-declare const audit_policyEnforcer: typeof policyEnforcer;
-declare const audit_reactiveExplainPath: typeof reactiveExplainPath;
-declare namespace audit {
-  export { type audit_AuditEntry as AuditEntry, audit_AuditTrailGraph as AuditTrailGraph, type audit_AuditTrailOptions as AuditTrailOptions, type audit_ComplianceSnapshotOptions as ComplianceSnapshotOptions, type audit_ComplianceSnapshotResult as ComplianceSnapshotResult, audit_PolicyEnforcerGraph as PolicyEnforcerGraph, type audit_PolicyEnforcerOptions as PolicyEnforcerOptions, type audit_PolicyViolation as PolicyViolation, audit_auditTrail as auditTrail, audit_complianceSnapshot as complianceSnapshot, audit_policyEnforcer as policyEnforcer, audit_reactiveExplainPath as reactiveExplainPath };
+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, audit as b, AuditTrailGraph as c, type AuditTrailOptions as d, type ComplianceSnapshotResult as e, type PolicyEnforcerOptions as f, auditTrail as g, complianceSnapshot as h, policyEnforcer as p, reactiveExplainPath as r };
+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-DVGiGFGT.d.cts → index-O6TgGUBV.d.cts}

@@ -1,6 +1,6 @@
-import { s as Messages, A as Actor, C as COMPLETE, b as COMPLETE_MSG, c as COMPLETE_ONLY_BATCH, D as DATA, d as DEFAULT_ACTOR, e as DIRTY, f as DIRTY_MSG, g as DIRTY_ONLY_BATCH, h as DepRecord, E as ERROR, F as FnCtx, G as GlobalInspectorEvent, i as GlobalInspectorHook, j as GraphReFlyConfig, k as GuardAction, l as GuardDenied, m as GuardDeniedDetails, H as HashFn, I as INVALIDATE, n as INVALIDATE_MSG, o as INVALIDATE_ONLY_BATCH, M as Message, p as MessageContext, q as MessageTypeRegistration, r as MessageTypeRegistrationInput, N as Node, t as NodeActions, u as NodeCtx, v as NodeDescribeKind, w as NodeFn, x as NodeFnCleanup, y as NodeGuard, z as NodeImpl, B as NodeInspectorHook, J as NodeInspectorHookEvent, a 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, V as PolicyDeny, P as PolicyRuleData, W as RESOLVED, X as RESOLVED_MSG, Y as RESOLVED_ONLY_BATCH, Z as RESUME, _ as START, $ as START_MSG, a0 as SubscribeContext, a1 as TEARDOWN, a2 as TEARDOWN_MSG, a3 as TEARDOWN_ONLY_BATCH, a4 as V0, a5 as V1, a6 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-BmerH3kS.cjs';
-import { D as DescribeDetail, a as DescribeField, b as DescribeNodeOutput, r as resolveDescribeFields } from './meta-BxCA7rcr.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-D02n5JjF.cjs';
+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

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

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

package/dist/{index-C8oil6M6.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-u5Ulnqag.js';
-import { N as Node } from './node-BmerH3kS.js';
-import { a as Graph } from './graph-CCwGKLCm.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 };