@graphrefly/graphrefly 0.27.0 → 0.29.0

package/dist/index-BUVtw1Ay.d.cts

@@ -0,0 +1,186 @@
+import { a as Node, N as NodeOptions } from './node-Dd6wHSib.cjs';
+import { a as GraphOptions, G as Graph } from './graph-DgohqXK-.cjs';
+
+/**
+ * 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-BUi57v_p.d.ts

@@ -0,0 +1,163 @@
+import { a as Node } from './node-Dd6wHSib.js';
+import { R as ReactiveMapBundle } from './reactive-map-FeuTVAJb.js';
+import { a as GraphOptions, G as Graph, C as CausalChain } from './graph-Qjg9gWHI.js';
+import { w as watchTopologyTree } from './topology-tree-one6oSKY.js';
+
+/** Aggregate topology stats emitted by {@link LensGraph.stats}. */
+interface TopologyStats {
+    /** Total primary nodes across this graph and all transitively mounted subgraphs. */
+    nodeCount: number;
+    /** Total directed edges (derived from deps; no duplicates). */
+    edgeCount: number;
+    /** Count of mounted subgraphs (transitive). */
+    subgraphCount: number;
+    /** Qualified paths with no upstream deps (source nodes). Sorted. */
+    sources: readonly string[];
+    /** Qualified paths with no downstream consumers in-graph (sink nodes). Sorted. */
+    sinks: readonly string[];
+    /** Longest path from any source to any sink (in edges). `0` for empty graphs. */
+    depth: number;
+    /** `true` if the dep DAG contains a cycle (feedback edge). */
+    hasCycles: boolean;
+}
+/** A single health problem entry. */
+interface HealthProblem {
+    path: string;
+    /** V1 only reports `"errored"`. Future versions may add `"completed"`, `"disconnected"`. */
+    status: "errored";
+    /** First errored upstream ancestor along the dep chain, when one exists and is distinct from `path`. */
+    upstreamCause?: string;
+}
+/** Aggregate health snapshot. `ok=true` iff `problems.length === 0`. */
+interface HealthReport {
+    ok: boolean;
+    problems: readonly HealthProblem[];
+}
+/** One per-path flow entry stored in {@link LensGraph.flow}. */
+interface FlowEntry {
+    path: string;
+    /** Cumulative DATA emissions observed since the lens activated. */
+    count: number;
+    /** `monotonicNs()` at the most recent DATA emission, or `null` if none yet. */
+    lastUpdate_ns: number | null;
+}
+/** Options for {@link graphLens}. */
+interface GraphLensOptions {
+    name?: string;
+    graph?: GraphOptions;
+    /**
+     * Limit which node paths `flow` tracks. When omitted, every path in
+     * `target.describe()` is observed. Recommended for graphs with hundreds
+     * of nodes since each tracked path adds one observe-event dispatch per
+     * DATA emission.
+     */
+    pathFilter?: (path: string) => boolean;
+    /**
+     * LRU cap on the {@link LensGraph.flow} map. When set, the flow tracker
+     * evicts least-recently-used paths (by insertion / set order) once the
+     * entry count exceeds this bound. Omit for unbounded (not recommended
+     * for long-running graphs with churning paths). Passed through to the
+     * underlying {@link reactiveMap}'s `maxSize`.
+     */
+    maxFlowPaths?: number;
+}
+/**
+ * Reactive observability surface for a target {@link Graph}.
+ * See {@link graphLens}.
+ *
+ * @category observability
+ */
+declare class LensGraph extends Graph {
+    /**
+     * Aggregate structural stats — `nodeCount`, `edgeCount`, `sources`,
+     * `sinks`, `depth`, `hasCycles`, `subgraphCount`. Recomputes on every
+     * structural change via {@link watchTopologyTree} (transitive).
+     *
+     * Named `stats` (not `topology`) because `Graph.topology` already names
+     * the raw `TopologyEvent` stream on every graph including `LensGraph`;
+     * giving the lens its own `topology` accessor with an incompatible
+     * `Node<TopologyStats>` type would break Liskov substitutability.
+     */
+    readonly stats: Node<TopologyStats>;
+    readonly health: Node<HealthReport>;
+    /**
+     * Per-path flow tracker — a live {@link ReactiveMapBundle} keyed by
+     * qualified path. Use `.get(path)` / `.has(path)` / `.size` for O(1)
+     * sync queries; subscribe to `.entries` for a reactive snapshot of the
+     * whole map. Lazy — the snapshot is materialized only while `.entries`
+     * has subscribers.
+     *
+     * Shape intentionally differs from `stats` / `health` (which are plain
+     * `Node<Report>`) because `flow` is a keyed collection, not a single
+     * aggregate value. The map shape exposes cheaper queries than any
+     * snapshot-based design.
+     */
+    readonly flow: ReactiveMapBundle<string, FlowEntry>;
+    private readonly _target;
+    constructor(target: Graph, opts?: GraphLensOptions);
+    /**
+     * Live causal chain from `from` to `to`. Recomputes whenever the target
+     * mutates. Disposed automatically when the lens is destroyed.
+     *
+     * **Lifetime note:** every call to `why()` registers a lens-owned disposer
+     * that runs on `lens.destroy()`. The returned `dispose` function releases
+     * the internal subscription but does NOT remove the lens-owned disposer —
+     * so heavy calling (e.g. per render frame) accumulates no-op disposers
+     * until lens teardown. Cache the returned handle for long-lived queries.
+     *
+     * @param from - Qualified path of the upstream endpoint.
+     * @param to - Qualified path of the downstream endpoint.
+     * @param opts - See {@link reactiveExplainPath}.
+     */
+    why(from: string, to: string, opts?: {
+        maxDepth?: number;
+        name?: string;
+        findCycle?: boolean;
+    }): {
+        node: Node<CausalChain>;
+        dispose: () => void;
+    };
+    /** Reference to the lensed graph. */
+    get target(): Graph;
+}
+/**
+ * Create a reactive observability lens over a {@link Graph}. Returns a
+ * {@link LensGraph} with three reactive surfaces (`stats`, `health`, `flow`)
+ * plus the `why(from, to)` method.
+ *
+ * The returned graph is detached. Mount it via `target.mount("lens", lens)`
+ * if you want it to appear in the target's `describe()`, or keep it standalone.
+ *
+ * @param target - The graph to observe.
+ * @param opts - See {@link GraphLensOptions}.
+ *
+ * @example
+ * ```ts
+ * const g = new Graph("app");
+ * g.add(state(0, { name: "counter" }));
+ * const lens = graphLens(g);
+ * lens.stats.subscribe((msgs) => console.log(msgs[0]?.[1])); // TopologyStats
+ * // Flow queries — O(1) without subscribing to snapshots:
+ * lens.flow.get("counter");        // FlowEntry | undefined
+ * lens.flow.size;                  // number
+ * lens.flow.entries.subscribe(...); // reactive snapshot, lazy-materialized
+ * ```
+ *
+ * @category observability
+ */
+declare function graphLens(target: Graph, opts?: GraphLensOptions): LensGraph;
+
+type index_FlowEntry = FlowEntry;
+type index_GraphLensOptions = GraphLensOptions;
+type index_HealthProblem = HealthProblem;
+type index_HealthReport = HealthReport;
+type index_LensGraph = LensGraph;
+declare const index_LensGraph: typeof LensGraph;
+type index_TopologyStats = TopologyStats;
+declare const index_graphLens: typeof graphLens;
+declare const index_watchTopologyTree: typeof watchTopologyTree;
+declare namespace index {
+  export { type index_FlowEntry as FlowEntry, type index_GraphLensOptions as GraphLensOptions, type index_HealthProblem as HealthProblem, type index_HealthReport as HealthReport, index_LensGraph as LensGraph, type index_TopologyStats as TopologyStats, index_graphLens as graphLens, index_watchTopologyTree as watchTopologyTree };
+}
+
+export { type FlowEntry as F, type GraphLensOptions as G, type HealthProblem as H, LensGraph as L, type TopologyStats as T, type HealthReport as a, graphLens as g, index as i };

package/dist/{messaging-Gt4LPbyA.d.cts → index-BanNUILp.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-Dd6wHSib.cjs';
+import { G as Graph, a as GraphOptions } from './graph-DgohqXK-.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-DRlSzBu9.d.ts → index-BayHDRx6.d.cts}

@@ -1,6 +1,6 @@
-import { A as Actor, N as Node, P as PolicyRuleData, k as GuardAction } from './node-BmerH3kS.js';
-import { a as Graph, G as GraphOptions, s as GraphPersistSnapshot, C as CausalChain } from './graph-CCwGKLCm.js';
-import { T as TopicGraph } from './messaging-XDoYablx.js';
+import { A as Actor, a as Node, P as PolicyRuleData, G as GuardAction } from './node-Dd6wHSib.cjs';
+import { G as Graph, a as GraphOptions, d as GraphPersistSnapshot, C as CausalChain } from './graph-DgohqXK-.cjs';
+import { T as TopicGraph } from './index-BanNUILp.cjs';
 
 /**
  * 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 };