@graphrefly/graphrefly 0.38.0 → 0.40.0

package/dist/{index-DTDVDzhA.d.ts → index-C-dkXOpB.d.cts}

@@ -1,35 +1,37 @@
-import { a as Node } from './node-fSc-hCv8.js';
-import { G as Graph } from './graph-BjW1taJl.js';
-import { L as LLMAdapter } from './types-CidcBDuk.js';
+import { D as DescribeNodeOutput } from './meta-Ct9nqQS5.cjs';
+import { N as Node } from './node-BYInONRr.cjs';
+import { G as Graph, b as GraphDescribeOutput } from './graph-E6likq7w.cjs';
+import { L as LLMAdapter } from './types-1Dhoi7HM.cjs';
 
 /**
  * LLM graph composition (roadmap §8.3).
  *
  * Declarative GraphSpec schema + compiler/decompiler for graph topology.
- * The LLM designs graphs as JSON; compileSpec instantiates them; decompileGraph
- * extracts them back. Templates support reusable subgraph patterns. Feedback
- * edges express bounded cycles via §8.1 feedback().
+ * The LLM designs graphs as JSON; `compileSpec` instantiates them;
+ * `decompileSpec` extracts them back. Templates support reusable subgraph
+ * patterns. Feedback edges express bounded cycles via §8.1 feedback().
+ *
+ * **Tier 1.5.3 Phase 3 (2026-04-27):** `GraphSpec` is a structural alias of
+ * {@link GraphDescribeOutput} with two LLM-author-friendly extras
+ * (`templates?` / `feedback?`). Per-node factory references are encoded in
+ * `meta.factory` + `meta.factoryArgs` (no more `fn` / `source` / `config` /
+ * `initial` fields). State node initial values live in
+ * `meta.factoryArgs.initial` (state self-tags with
+ * `factoryTag("state", { initial })`).
  *
  * @module
  */
 
-/** A single node declaration in a GraphSpec. */
-type GraphSpecNode = {
-    /** Node kind: state, producer, derived, effect, operator. */
-    type: "state" | "producer" | "derived" | "effect" | "operator";
-    /** Dependency node names (for derived/effect/operator). */
-    deps?: string[];
-    /** Named function from the catalog (for derived/effect/operator/producer). */
-    fn?: string;
-    /** Named source from the catalog (for producer). */
-    source?: string;
-    /** Freeform config passed to the catalog fn/source factory. */
-    config?: Record<string, unknown>;
-    /** Initial value (for state nodes). */
-    initial?: unknown;
-    /** Human/LLM-readable metadata. */
-    meta?: Record<string, unknown>;
-};
+/**
+ * A single node declaration in a GraphSpec — structural alias of
+ * {@link DescribeNodeOutput}.
+ *
+ * Per-node factory provenance lives in `meta.factory` + `meta.factoryArgs`
+ * (use {@link factoryTag} to stamp them at construction time). State node
+ * initial values come through `meta.factoryArgs.initial` for tagged states,
+ * with fallback to `value` (since spec projection retains state values).
+ */
+type GraphSpecNode = DescribeNodeOutput;
 /** Template instantiation node — expanded at compile time. */
 type GraphSpecTemplateRef = {
     type: "template";
@@ -56,25 +58,24 @@ type GraphSpecFeedbackEdge = {
     /** Max iterations before stopping (default: 10). */
     maxIterations?: number;
 };
-/** Declarative graph topology for LLM composition (§8.3). */
-type GraphSpec = {
-    /** Graph name. */
-    name: string;
-    /** Node declarations (keyed by node name). */
+/**
+ * Declarative graph topology for LLM composition (§8.3).
+ *
+ * Tier 1.5.3 Phase 3 (2026-04-27): structural alias of
+ * {@link GraphDescribeOutput} extended with optional `templates` /
+ * `feedback` fields for LLM-author convenience. Top-level `factory` /
+ * `factoryArgs` (Phase 2.5 carry) ride along on every describe output.
+ *
+ * Round-trip property: `decompileSpec(g) === g.describe({ detail: "spec" })`
+ * (modulo the small feedback-edge extraction sugar).
+ */
+type GraphSpec = Omit<GraphDescribeOutput, "nodes" | "expand"> & {
+    /** Node declarations (keyed by node name). Either a structural describe entry or a template ref. */
     nodes: Record<string, GraphSpecNode | GraphSpecTemplateRef>;
-    /** Reusable subgraph templates. */
+    /** Reusable subgraph templates (LLM-author extra; not present in `describe()` output). */
     templates?: Record<string, GraphSpecTemplate>;
-    /** Feedback edges (bounded cycles). */
+    /** Feedback edges (bounded cycles, LLM-author extra). */
     feedback?: GraphSpecFeedbackEdge[];
-    /**
-     * Top-level factory identifier (Tier 1.5.3 Phase 2.5 — DG1=B). When set
-     * and `compileSpec` is given a `catalog.graphFactories[factory]` entry,
-     * the spec's reconstruction is delegated to that factory wholesale (the
-     * `nodes` / `edges` / `templates` fields below are not used).
-     */
-    factory?: string;
-    /** JSON-serializable construction args, paired with `factory`. */
-    factoryArgs?: unknown;
 };
 /**
  * Factory for creating a derived/effect/operator node from catalog.
@@ -237,26 +238,28 @@ type CompileSpecOptions = {
  */
 declare function compileSpec(spec: GraphSpec, opts?: CompileSpecOptions): Graph;
 /**
- * Extract a GraphSpec from a running graph.
+ * Extract a {@link GraphSpec} from a running graph.
  *
- * Uses `describe({ detail: "standard" })` as a starting point, then enriches:
- * - Feedback edges recovered from counter node meta (`feedbackFrom`/`feedbackTo`)
- * - Template refs recovered from output node meta (`_templateName`/`_templateBind`)
- * - Structural fingerprinting as fallback for 2+ identical mounted subgraphs
+ * Tier 1.5.3 Phase 3 (2026-04-27): thin projection over
+ * `graph.describe({ detail: "spec" })`. The describe-output already carries
+ * structural fields (`type`, `deps`, optional `value`) plus per-node
+ * `meta.factory` / `meta.factoryArgs` for tagged factories and top-level
+ * `factory` / `factoryArgs` for graph-level tags. The only sugar this helper
+ * adds is a feedback-edge recovery scan over `meta.feedbackFrom` /
+ * `meta.feedbackTo` companion fields stamped by the §8.1 `feedback()`
+ * primitive.
+ *
+ * **Removed in Phase 3:** template fingerprinting / `_templateName` /
+ * `_templateBind` recovery. Mounted subgraphs surface as nested `subname::*`
+ * paths in `desc.nodes`; if you need the template-instantiation form, build
+ * the spec by hand or read the meta companions directly.
  *
  * @param graph - Running graph to decompile.
  * @returns A GraphSpec representation.
  *
  * @category patterns
  */
-/**
- * Tier 1.5.3 / D5 rename — `decompileSpec` is the canonical name post-Session A.1
- * lock. Once Phase 3 lands `GraphSpec ≡ GraphDescribeOutput`, the body becomes
- * `g.describe({ detail: "spec" })`. For now it delegates to the existing
- * implementation so behavior is unchanged.
- */
 declare function decompileSpec(graph: Graph): GraphSpec;
-declare function decompileGraph(graph: Graph): GraphSpec;
 /** A single change in a spec diff. */
 type SpecDiffEntry = {
     type: "added" | "removed" | "changed";
@@ -357,7 +360,6 @@ type index_SourceFactory = SourceFactory;
 type index_SpecDiffEntry = SpecDiffEntry;
 type index_SpecDiffResult = SpecDiffResult;
 declare const index_compileSpec: typeof compileSpec;
-declare const index_decompileGraph: typeof decompileGraph;
 declare const index_decompileSpec: typeof decompileSpec;
 declare const index_extractFnFactory: typeof extractFnFactory;
 declare const index_extractSourceFactory: typeof extractSourceFactory;
@@ -370,7 +372,7 @@ declare const index_specDiff: typeof specDiff;
 declare const index_validateSpec: typeof validateSpec;
 declare const index_validateSpecAgainstCatalog: typeof validateSpecAgainstCatalog;
 declare namespace index {
-  export { type index_CatalogFnEntry as CatalogFnEntry, type index_CatalogSourceEntry as CatalogSourceEntry, type index_CompileSpecOptions as CompileSpecOptions, type index_ConfigFieldSchema as ConfigFieldSchema, type index_FnFactory as FnFactory, type index_GraphFactory as GraphFactory, type index_GraphSpec as GraphSpec, type index_GraphSpecCatalog as GraphSpecCatalog, type index_GraphSpecFeedbackEdge as GraphSpecFeedbackEdge, type index_GraphSpecNode as GraphSpecNode, type index_GraphSpecTemplate as GraphSpecTemplate, type index_GraphSpecTemplateRef as GraphSpecTemplateRef, type index_GraphSpecValidation as GraphSpecValidation, type index_LLMComposeOptions as LLMComposeOptions, type index_LLMRefineOptions as LLMRefineOptions, type index_SourceFactory as SourceFactory, type index_SpecDiffEntry as SpecDiffEntry, type index_SpecDiffResult as SpecDiffResult, index_compileSpec as compileSpec, index_decompileGraph as decompileGraph, index_decompileSpec as decompileSpec, index_extractFnFactory as extractFnFactory, index_extractSourceFactory as extractSourceFactory, index_generateCatalogPrompt as generateCatalogPrompt, index_isRichFnEntry as isRichFnEntry, index_isRichSourceEntry as isRichSourceEntry, index_llmCompose as llmCompose, index_llmRefine as llmRefine, index_specDiff as specDiff, index_validateSpec as validateSpec, index_validateSpecAgainstCatalog as validateSpecAgainstCatalog };
+  export { type index_CatalogFnEntry as CatalogFnEntry, type index_CatalogSourceEntry as CatalogSourceEntry, type index_CompileSpecOptions as CompileSpecOptions, type index_ConfigFieldSchema as ConfigFieldSchema, type index_FnFactory as FnFactory, type index_GraphFactory as GraphFactory, type index_GraphSpec as GraphSpec, type index_GraphSpecCatalog as GraphSpecCatalog, type index_GraphSpecFeedbackEdge as GraphSpecFeedbackEdge, type index_GraphSpecNode as GraphSpecNode, type index_GraphSpecTemplate as GraphSpecTemplate, type index_GraphSpecTemplateRef as GraphSpecTemplateRef, type index_GraphSpecValidation as GraphSpecValidation, type index_LLMComposeOptions as LLMComposeOptions, type index_LLMRefineOptions as LLMRefineOptions, type index_SourceFactory as SourceFactory, type index_SpecDiffEntry as SpecDiffEntry, type index_SpecDiffResult as SpecDiffResult, index_compileSpec as compileSpec, index_decompileSpec as decompileSpec, index_extractFnFactory as extractFnFactory, index_extractSourceFactory as extractSourceFactory, index_generateCatalogPrompt as generateCatalogPrompt, index_isRichFnEntry as isRichFnEntry, index_isRichSourceEntry as isRichSourceEntry, index_llmCompose as llmCompose, index_llmRefine as llmRefine, index_specDiff as specDiff, index_validateSpec as validateSpec, index_validateSpecAgainstCatalog as validateSpecAgainstCatalog };
 }
 
-export { validateSpecAgainstCatalog as A, type CatalogFnEntry as C, type FnFactory as F, type GraphSpec as G, type LLMComposeOptions as L, type SourceFactory as S, type CatalogSourceEntry as a, type ConfigFieldSchema as b, type GraphSpecCatalog as c, type GraphSpecFeedbackEdge as d, type GraphSpecNode as e, type GraphSpecTemplate as f, type GraphSpecTemplateRef as g, type GraphSpecValidation as h, index as i, type CompileSpecOptions as j, type GraphFactory as k, type LLMRefineOptions as l, type SpecDiffEntry as m, type SpecDiffResult as n, compileSpec as o, decompileGraph as p, decompileSpec as q, extractFnFactory as r, extractSourceFactory as s, generateCatalogPrompt as t, isRichFnEntry as u, isRichSourceEntry as v, llmCompose as w, llmRefine as x, specDiff as y, validateSpec as z };
+export { type CatalogFnEntry as C, type FnFactory as F, type GraphSpec as G, type LLMComposeOptions as L, type SourceFactory as S, type CatalogSourceEntry as a, type ConfigFieldSchema as b, type GraphSpecCatalog as c, type GraphSpecFeedbackEdge as d, type GraphSpecNode as e, type GraphSpecTemplate as f, type GraphSpecTemplateRef as g, type GraphSpecValidation as h, index as i, type CompileSpecOptions as j, type GraphFactory as k, type LLMRefineOptions as l, type SpecDiffEntry as m, type SpecDiffResult as n, compileSpec as o, decompileSpec as p, extractFnFactory as q, extractSourceFactory as r, generateCatalogPrompt as s, isRichFnEntry as t, isRichSourceEntry as u, llmCompose as v, llmRefine as w, specDiff as x, validateSpec as y, validateSpecAgainstCatalog as z };

package/dist/{index-B-ORMr3k.d.ts → index-C5cQ7Gfx.d.ts}

@@ -1,9 +1,9 @@
-import { T as ToObservableOptions, t as toObservable } from './observable-EAV_rNfM.js';
+import { T as ToObservableOptions, t as toObservable } from './observable-DO8DDEzv.js';
 import { OnModuleInit, OnModuleDestroy, ExecutionContext, CanActivate, DynamicModule } from '@nestjs/common';
 import { ModuleRef } from '@nestjs/core';
-import { G as Graph, b as GraphPersistSnapshot } from './graph-BjW1taJl.js';
-import { A as Actor } from './node-fSc-hCv8.js';
-import { c as CqrsOptions, b as CqrsGraph, a as CqrsEvent } from './index-BFaALJxR.js';
+import { G as Graph, c as GraphPersistSnapshot } from './graph-BkIkog4h.js';
+import { A as Actor } from './node-BYInONRr.js';
+import { c as CqrsOptions, b as CqrsGraph, a as CqrsEvent } from './index-CD2dBMet.js';
 import { AppendLogStorageTier } from './extra/storage-tiers.js';
 
 /** Class constructor key for decorator registries and Nest `ModuleRef.get()`. */

package/dist/{index-ML6vHKXK.d.ts → index-C6ZUaos7.d.ts}

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

package/dist/{index-Vz7KPfgz.d.ts → index-CAP3UGsq.d.ts}

@@ -1,4 +1,4 @@
-import { C as CatchOptions, a as ClassifyResult, D as Decision, b as DecisionAction, G as GateController, c as GateOptions, P as PipelineGraph, S as StepRef, T as TerminalCause, d as decisionKeyOf, p as pipelineGraph } from './pipeline-graph-9JBbmRxA.js';
+import { C as CatchOptions, a as ClassifyResult, D as Decision, b as DecisionAction, G as GateController, c as GateOptions, P as PipelineGraph, S as StepRef, T as TerminalCause, d as decisionKeyOf, p as pipelineGraph } from './pipeline-graph-CB4La-UW.js';
 
 /**
  * Orchestration patterns (roadmap §4.1).

package/dist/{index-BFaALJxR.d.ts → index-CD2dBMet.d.ts}

@@ -1,8 +1,8 @@
-import { a as Node } from './node-fSc-hCv8.js';
-import { R as ReactiveLogBundle } from './reactive-log-BgWSA1fg.js';
+import { N as Node } from './node-BYInONRr.js';
+import { B as BaseAuditRecord } from './index-BQ1fR4li.js';
+import { a as ReactiveLogBundle } from './reactive-log-BlAsPLl2.js';
 import { AppendLogStorageTier } from './extra/storage-tiers.js';
-import { a as GraphOptions, G as Graph } from './graph-BjW1taJl.js';
-import { B as BaseAuditRecord } from './imperative-audit-ahAE65a9.js';
+import { a as GraphOptions, G as Graph } from './graph-BkIkog4h.js';
 
 /**
  * CQRS patterns (roadmap §4.5).
@@ -64,13 +64,14 @@ declare const cqrsEventKeyOf: (e: CqrsEvent) => string;
 interface DispatchRecord<T = unknown> extends BaseAuditRecord {
     readonly commandName: string;
     readonly payload: T;
-    readonly status: "success" | "failed";
+    /** Action result. Tier 1.6.2 canonical enum (renamed from `status`). */
+    readonly outcome: "success" | "failure";
     readonly error?: unknown;
     readonly errorType?: string;
     /**
      * Event names emitted by the handler.
-     * - `status: "success"`: events that persisted in the event log.
-     * - `status: "failed"`: events the handler ATTEMPTED to emit before throwing;
+     * - `outcome: "success"`: events that persisted in the event log.
+     * - `outcome: "failure"`: events the handler ATTEMPTED to emit before throwing;
      *   they were rolled back and did NOT persist. Documents the failed attempt's
      *   intentions for debugging handler logic. The actual event log shows only
      *   what's durable.
@@ -80,7 +81,8 @@ interface DispatchRecord<T = unknown> extends BaseAuditRecord {
 declare const dispatchKeyOf: <T>(r: DispatchRecord<T>) => string;
 interface SagaInvocation<T = unknown> extends BaseAuditRecord {
     readonly eventType: string;
-    readonly status: "success" | "failed";
+    /** Action result. Tier 1.6.2 canonical enum (renamed from `status`). */
+    readonly outcome: "success" | "failure";
     readonly error?: unknown;
     readonly errorType?: string;
     readonly aggregateId?: string;

package/dist/index-CGhMJNHb.d.cts

@@ -0,0 +1,128 @@
+import { N as Node } from './node-BYInONRr.cjs';
+import { b as GraphDescribeOutput, G as Graph } from './graph-E6likq7w.cjs';
+import { w as watchTopologyTree } from './topology-tree-3LBKFsUo.cjs';
+
+/**
+ * Reactive graph observability preset (Tier 5.3 reshape — Session A.4 lock).
+ *
+ * `graphLens(target)` is a thin compositor (~30 LOC of glue) over two
+ * already-shipped reactive primitives:
+ *
+ * - `target.describe({ reactive: true })` — live topology snapshot.
+ * - `target.observe({ reactive: true, tiers: ["data"] })` — coalesced data
+ *   changesets per outermost batch flush.
+ *
+ * It returns three Nodes plus a dispose function:
+ *
+ * - `topology: Node<GraphDescribeOutput>` — the live describe snapshot,
+ *   re-emitting on every settle of the target tree (structural change,
+ *   error/complete/teardown transition).
+ * - `health: Node<HealthReport>` — `{ok, problems[]}` aggregated from the
+ *   live describe; `ok=false` when any node enters `"errored"` status,
+ *   with `upstreamCause` walked backward through deps.
+ * - `flow: Node<ReadonlyMap<string, FlowEntry>>` — per-path DATA counters
+ *   accumulating as `target.observe({reactive: true, tiers: ["data"]})`
+ *   delivers changesets. The map is reconciled against `topology` on each
+ *   topology change so removed nodes drop their entries.
+ *
+ * Pre-Tier-5.3 shipped a `LensGraph` class with `stats` / `health` / `flow`
+ * (as a `ReactiveMapBundle`) / `why(from, to)` / `flowEntryNode(...)`. The
+ * surface collapsed because every concern was already a one-liner over
+ * `describe({reactive:true})` + `observe({reactive:true, tiers})` once those
+ * landed in Tier 1.5.1 / 1.5.2 — the class added no protocol-level concept,
+ * just glue. Callers who need topology stats compose a derived over
+ * `topology` directly; callers who need a causal chain call
+ * `target.explain(from, to, { reactive: true })`.
+ *
+ * The transitive topology-subscription helper {@link watchTopologyTree} is
+ * re-exported here for downstream factories that need full-tree dynamic
+ * coverage without taking a dep on `graph/`.
+ *
+ * @module
+ */
+
+/** 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[];
+}
+/** Per-path flow entry stored in the {@link GraphLensView.flow} map. */
+interface FlowEntry {
+    path: string;
+    /** Cumulative DATA emissions observed since the lens activated. */
+    count: number;
+    /** Monotonic ns at the most recent DATA emission for this path, or `null` if none yet. */
+    lastUpdate_ns: number | null;
+}
+/** Output of {@link graphLens}. */
+interface GraphLensView {
+    /** Live describe snapshot. Re-emits on structural change AND status transitions. */
+    topology: Node<GraphDescribeOutput>;
+    /** Live `{ok, problems[]}`. Aggregated from `topology`; equality-deduped. */
+    health: Node<HealthReport>;
+    /** Per-path DATA counter map. Re-emits per outermost batch flush. */
+    flow: Node<ReadonlyMap<string, FlowEntry>>;
+    /**
+     * Tear down the underlying `describe({reactive:true})` subscription.
+     * The `flow` node activates lazily; subscribing-then-unsubscribing reclaims
+     * its observe stream automatically. Call `dispose()` once when finished.
+     */
+    dispose(): void;
+}
+/** Build a `HealthReport` from a fresh `GraphDescribeOutput`. */
+declare function computeHealthReport(described: GraphDescribeOutput): HealthReport;
+/** Structural equality for {@link HealthReport} — used as the `health` derived's `equals`. */
+declare function healthReportEqual(a: HealthReport, b: HealthReport): boolean;
+/**
+ * Reactive observability preset over a target {@link Graph}.
+ *
+ * @param target - The graph to observe.
+ *
+ * @example
+ * ```ts
+ * const g = new Graph("app");
+ * g.add(state(0, { name: "counter" }), { name: "counter" });
+ *
+ * const lens = graphLens(g);
+ * lens.topology.subscribe((msgs) => console.log("topology:", msgs));
+ * lens.health.subscribe((msgs) => console.log("health:", msgs));
+ * lens.flow.subscribe((msgs) => {
+ *   for (const [type, payload] of msgs) {
+ *     if (type === DATA) console.log("flow map size:", (payload as ReadonlyMap<string, FlowEntry>).size);
+ *   }
+ * });
+ *
+ * // Causal chains: use the underlying primitive directly — `graphLens` no
+ * // longer wraps it, since `graph.explain({ reactive: true })` already
+ * // provides everything the old `lens.why()` did.
+ * const why = g.explain("counter", "consumer", { reactive: true });
+ *
+ * // Tear down when done.
+ * lens.dispose();
+ * ```
+ *
+ * @category observability
+ */
+declare function graphLens(target: Graph): GraphLensView;
+
+type index_FlowEntry = FlowEntry;
+type index_GraphLensView = GraphLensView;
+type index_HealthProblem = HealthProblem;
+type index_HealthReport = HealthReport;
+declare const index_computeHealthReport: typeof computeHealthReport;
+declare const index_graphLens: typeof graphLens;
+declare const index_healthReportEqual: typeof healthReportEqual;
+declare const index_watchTopologyTree: typeof watchTopologyTree;
+declare namespace index {
+  export { type index_FlowEntry as FlowEntry, type index_GraphLensView as GraphLensView, type index_HealthProblem as HealthProblem, type index_HealthReport as HealthReport, index_computeHealthReport as computeHealthReport, index_graphLens as graphLens, index_healthReportEqual as healthReportEqual, index_watchTopologyTree as watchTopologyTree };
+}
+
+export { type FlowEntry as F, type GraphLensView as G, type HealthProblem as H, type HealthReport as a, computeHealthReport as c, graphLens as g, healthReportEqual as h, index as i };

package/dist/{index-B3D_z0Z6.d.cts → index-CL7oilfm.d.cts}

@@ -1,4 +1,4 @@
-import { a as Node } from './node-fSc-hCv8.cjs';
+import { N as Node } from './node-BYInONRr.cjs';
 
 /**
  * A Nanostores-compatible atom.

package/dist/{index-Bn0uZEL4.d.ts → index-CQtWm7jS.d.ts}

@@ -1,12 +1,12 @@
-import { i as index$2 } from './index-JYtN9uqM.js';
-import { i as index$3 } from './index-8OxXae3g.js';
-import { i as index$4 } from './index-B-ORMr3k.js';
-import { i as index$5 } from './index-CIcu6fIR.js';
-import { a as Node } from './node-fSc-hCv8.js';
-import { i as index$6 } from './index-CDvC1m5p.js';
-import { i as index$7 } from './index-BjWZARLy.js';
-import { i as index$8 } from './index-BiomL7AW.js';
-import { i as index$9 } from './index-ML6vHKXK.js';
+import { i as index$2 } from './index-CoM4rzyB.js';
+import { i as index$3 } from './index-yLt-aPMp.js';
+import { i as index$4 } from './index-C5cQ7Gfx.js';
+import { i as index$5 } from './index-2n8Eai6M.js';
+import { N as Node } from './node-BYInONRr.js';
+import { i as index$6 } from './index-B2RUoIUz.js';
+import { i as index$7 } from './index-Ctb7_2sG.js';
+import { i as index$8 } from './index-BJSZxSFX.js';
+import { i as index$9 } from './index-C6ZUaos7.js';
 
 /**
  * Options for creating signals.

package/dist/{index-CM-i58FY.d.cts → index-CRm0YIzC.d.cts}

@@ -1,12 +1,12 @@
-import { i as index$2 } from './index-D_QQ_dTD.cjs';
-import { i as index$3 } from './index-B3D_z0Z6.cjs';
-import { i as index$4 } from './index-CAV-3RpJ.cjs';
-import { i as index$5 } from './index-BFuVcqL8.cjs';
-import { a as Node } from './node-fSc-hCv8.cjs';
-import { i as index$6 } from './index-9xhIaM-w.cjs';
-import { i as index$7 } from './index-CpZKtdMw.cjs';
-import { i as index$8 } from './index-CqSJ25A9.cjs';
-import { i as index$9 } from './index-CAbHN_rP.cjs';
+import { i as index$2 } from './index-DYTBbF8T.cjs';
+import { i as index$3 } from './index-CL7oilfm.cjs';
+import { i as index$4 } from './index-Bd91Nmf4.cjs';
+import { i as index$5 } from './index-D3ayz3hy.cjs';
+import { N as Node } from './node-BYInONRr.cjs';
+import { i as index$6 } from './index-DOBLxOti.cjs';
+import { i as index$7 } from './index-PgwvGWa1.cjs';
+import { i as index$8 } from './index-z8WFPVI8.cjs';
+import { i as index$9 } from './index-CgnCFhr2.cjs';
 
 /**
  * Options for creating signals.

package/dist/index-CUIkE1l9.d.cts

@@ -0,0 +1,230 @@
+import { f as factoryTag, p as placeholderArgs } from './meta-Ct9nqQS5.cjs';
+import { N as Node } from './node-BYInONRr.cjs';
+import { S as StatusValue, C as CircuitState, R as RateLimiterState, a as RateLimiterOptions, b as CircuitBreakerOptions, c as RetryOptions, F as FallbackInput, N as NS_PER_MS, d as NS_PER_SEC } from './index-DGTo1yka.cjs';
+import { G as Graph, a as GraphOptions } from './graph-E6likq7w.cjs';
+import { B as BudgetConstraint } from './budget-gate-DiP_nK0n.cjs';
+
+/**
+ * Resilience composition with correct nesting order (roadmap §9.0b — Tier 5.2 Wave-B rebuild).
+ *
+ * {@link resilientPipeline} composes the resilience primitives from
+ * `extra/resilience/` in the canonical nesting order:
+ *
+ * ```text
+ *   rateLimit → budget → breaker → timeout → retry → fallback → status
+ * ```
+ *
+ * Returns a {@link ResilientPipelineGraph} (Graph subclass) with mounted
+ * intermediate nodes and per-layer status companions, replacing the prior
+ * bundle return. Each intermediate is mounted under a stable name so
+ * `pipeline.describe()` shows the resilience chain in topology snapshots,
+ * mermaid renders, and `lens.health` aggregations.
+ *
+ * **Per-attempt timeout vs. retry ordering.** `timeout` is applied BEFORE
+ * `retry` so each retry attempt resubscribes to a fresh deadline (per-attempt
+ * semantics). If `timeout` wrapped `retry`, a single deadline would apply to
+ * the entire retry chain — not what callers expect.
+ *
+ * **`breakerOnOpen` + `retry` interaction.** With `breakerOnOpen: "error"` AND
+ * `retry`, retry sees `CircuitOpenError` and resubscribes; the next attempt
+ * very likely also breaker-open → another error → retry burns its budget
+ * against an open circuit. Either set retry's `backoff` long enough for the
+ * breaker reset window OR keep the default `breakerOnOpen: "skip"` (emits
+ * RESOLVED when open; downstream drops the beat without retry firing).
+ *
+ * **Reactive options (switchMap rebuild).** Every primitive option accepts a
+ * `T | Node<T>` (precedent-aligned with `FallbackInput<T>`). When the caller
+ * supplies a static value, the layer is built once at construction. When the
+ * caller supplies a `Node<T>`, the pipeline subscribes via `switchMap` and
+ * **rebuilds the layer on every option emission** — the chain stalls until
+ * the option Node emits its first DATA. Each rebuild creates a fresh
+ * primitive instance, so internal state is lost (rate-limiter pending buffer,
+ * breaker failure count, retry attempt count, in-flight timeout). Per-layer
+ * **companion Nodes** (`droppedCount`, `rateLimitState`, `breakerState`) are
+ * therefore exposed ONLY for the static-options path. Primitive-side widening
+ * (filed in `docs/optimizations.md` under "Tier 5.2 follow-up — primitive-side
+ * reactive-options widening") will preserve internal state once it lands and
+ * the pipeline will trivially forward Node-form options to the primitive.
+ *
+ * @module
+ */
+
+/**
+ * `T | Node<T>` for primitive options — precedent-aligned with
+ * {@link FallbackInput} and `policyGate.policies`. When the caller supplies a
+ * static value, the layer is built once at construction. When the caller
+ * supplies a `Node<T>`, the pipeline subscribes via {@link switchMap}: the
+ * layer is rebuilt on every option emission. **State-loss caveat:** each
+ * rebuild creates a fresh primitive instance — `rateLimiter` loses its pending
+ * buffer, `circuitBreaker` resets failure count, `retry` resets attempt
+ * count, `timeout` cancels in-flight deadline. This is the documented
+ * switchMap-pattern semantics; primitive-side widening (filed in
+ * `docs/optimizations.md`) will preserve internal state once it lands and the
+ * pipeline can forward Node-form options directly.
+ *
+ * Per-layer **companion Nodes** (`droppedCount`, `rateLimitState`,
+ * `breakerState`) are exposed only for the static-options path — Node-form
+ * leaves them as `undefined` because each rebuild creates new companion
+ * instances and a switchMap-mirrored companion would track only the latest
+ * bundle. Callers needing both reactive options AND companions wait for
+ * primitive-side widening.
+ */
+type NodeOrValue<T> = T | Node<T>;
+/**
+ * Options for {@link resilientPipeline}. Every layer is optional — omit a
+ * field and that layer is skipped.
+ *
+ * Reactive (`Node<T>`) forms are accepted everywhere a primitive value would
+ * fit; the pipeline subscribes via `switchMap` and rebuilds the layer on each
+ * emission. See module JSDoc for the rebuild semantics + state-loss caveat.
+ */
+interface ResilientPipelineOptions<T> {
+    /**
+     * Admission control — at most `maxEvents` `DATA` per `windowNs`. See
+     * {@link rateLimiter}.
+     *
+     * `maxBuffer` is optional at the pipeline layer (defaults to `Infinity`,
+     * preserving the historical unbounded behavior). Pass an explicit positive
+     * integer to opt in to a bounded queue.
+     */
+    rateLimit?: NodeOrValue<Omit<RateLimiterOptions, "maxBuffer"> & {
+        maxBuffer?: number;
+    }>;
+    /** Cost/constraint gate. See {@link budgetGate}. */
+    budget?: NodeOrValue<ReadonlyArray<BudgetConstraint>>;
+    /** Circuit breaker — fail-fast when the downstream resource is unhealthy. See {@link circuitBreaker}. */
+    breaker?: NodeOrValue<CircuitBreakerOptions>;
+    /**
+     * Behavior when the breaker is open:
+     * - `"skip"` (default) — emit `RESOLVED` (lets downstream drop the beat).
+     * - `"error"` — emit a `CircuitOpenError` so `retry` / `fallback` can react.
+     *   See module JSDoc for the retry-budget burn caveat.
+     *
+     * Static (configuration-only — no reactive form).
+     */
+    breakerOnOpen?: "skip" | "error";
+    /** Retry policy on terminal `ERROR`. See {@link retry}. */
+    retry?: NodeOrValue<RetryOptions>;
+    /**
+     * Per-attempt deadline in milliseconds. Converted to ns internally. Omit
+     * to skip the timeout wrap.
+     *
+     * Specified in ms (not ns) because callers consistently think in
+     * millisecond deadlines; the underlying {@link timeout} primitive takes ns
+     * internally.
+     */
+    timeoutMs?: NodeOrValue<number>;
+    /** Final fallback value emitted on terminal `ERROR` after retry exhausts. See {@link fallback}. */
+    fallback?: FallbackInput<T>;
+    /**
+     * Initial status reported by the status node. Default `"pending"`. Static.
+     */
+    initialStatus?: StatusValue;
+    /** Wrapper graph name. Default `"resilient_pipeline"`. */
+    name?: string;
+    /** Wrapper graph options. */
+    graph?: GraphOptions;
+}
+/**
+ * Graph subclass returned by {@link resilientPipeline}. Mounts each
+ * configured intermediate under a stable name and exposes per-layer status
+ * companions.
+ *
+ * @category patterns
+ */
+declare class ResilientPipelineGraph<T> extends Graph {
+    /**
+     * Final resilient node — subscribe to this for `DATA` emissions.
+     *
+     * Named `output` (not `node`) because `Graph.node(name)` already names the
+     * path-resolution method on the base class; a `readonly node` field would
+     * shadow it.
+     */
+    readonly output: Node<T>;
+    /** Live status: `"pending" | "running" | "completed" | "errored"`. */
+    readonly status: Node<StatusValue>;
+    /**
+     * Last error payload, or `null` when not errored.
+     *
+     * Named `lastError` (not `error`) because `Graph.error(name, err)` already
+     * names a method on the base class.
+     */
+    readonly lastError: Node<unknown | null>;
+    /** Breaker state when `opts.breaker` is provided; `undefined` otherwise. */
+    readonly breakerState: Node<CircuitState> | undefined;
+    /**
+     * Drop-counter when `opts.rateLimit` is provided; `undefined` otherwise.
+     *
+     * **Lifetime note:** `droppedCount` retains its final value through
+     * terminal (`COMPLETE` / `ERROR` / `TEARDOWN`); the underlying counter
+     * resets to `0` only at the next subscription cycle.
+     */
+    readonly droppedCount: Node<number> | undefined;
+    /**
+     * Combined rate-limit state when `opts.rateLimit` is provided; `undefined`
+     * otherwise. Same lifecycle as {@link droppedCount} but exposes
+     * `pendingCount` and `paused` alongside the drop counter for richer
+     * backpressure observability (Tier 5.2 D7).
+     */
+    readonly rateLimitState: Node<RateLimiterState> | undefined;
+    constructor(source: Node<T>, opts?: ResilientPipelineOptions<T>);
+}
+/**
+ * Compose a resilient pipeline around `source` in the canonical nesting
+ * order — `rateLimit → budget → breaker → timeout → retry → fallback → status`.
+ * Omit any option to skip that layer.
+ *
+ * Returns a {@link ResilientPipelineGraph} (Graph subclass) —
+ * `pipeline.output` is the externally visible final node; `pipeline.status`
+ * / `pipeline.lastError` / `pipeline.breakerState` / `pipeline.droppedCount`
+ * are the per-layer companions. Call `pipeline.describe()` to see the
+ * mounted intermediates; compose with {@link graphLens}'s `health` for
+ * aggregate status.
+ *
+ * **Naming note:** `output` and `lastError` (not `node` / `error`) avoid
+ * clashes with `Graph.node(name)` and `Graph.error(name, err)` on the base
+ * class.
+ *
+ * @param source - Upstream node to wrap.
+ * @param opts - See {@link ResilientPipelineOptions}. All fields optional.
+ *
+ * @example
+ * ```ts
+ * const safeFetch = resilientPipeline(fetchNode, {
+ *   rateLimit: { maxEvents: 10, windowNs: NS_PER_SEC },
+ *   breaker: { failureThreshold: 5 },
+ *   retry: { count: 3, backoff: "exponential" },
+ *   timeoutMs: 10_000,
+ *   fallback: null,
+ * });
+ * safeFetch.output.subscribe(msgs => console.log(msgs));
+ * safeFetch.status.subscribe(msgs => console.log(msgs));
+ * safeFetch.describe({ format: "ascii" }); // visualize the chain
+ * ```
+ *
+ * @category patterns
+ */
+declare function resilientPipeline<T>(source: Node<T>, opts?: ResilientPipelineOptions<T>): ResilientPipelineGraph<T>;
+
+declare const index_BudgetConstraint: typeof BudgetConstraint;
+declare const index_CircuitBreakerOptions: typeof CircuitBreakerOptions;
+declare const index_CircuitState: typeof CircuitState;
+declare const index_FallbackInput: typeof FallbackInput;
+declare const index_NS_PER_MS: typeof NS_PER_MS;
+declare const index_NS_PER_SEC: typeof NS_PER_SEC;
+type index_NodeOrValue<T> = NodeOrValue<T>;
+declare const index_RateLimiterOptions: typeof RateLimiterOptions;
+declare const index_RateLimiterState: typeof RateLimiterState;
+type index_ResilientPipelineGraph<T> = ResilientPipelineGraph<T>;
+declare const index_ResilientPipelineGraph: typeof ResilientPipelineGraph;
+type index_ResilientPipelineOptions<T> = ResilientPipelineOptions<T>;
+declare const index_RetryOptions: typeof RetryOptions;
+declare const index_StatusValue: typeof StatusValue;
+declare const index_factoryTag: typeof factoryTag;
+declare const index_placeholderArgs: typeof placeholderArgs;
+declare const index_resilientPipeline: typeof resilientPipeline;
+declare namespace index {
+  export { index_BudgetConstraint as BudgetConstraint, index_CircuitBreakerOptions as CircuitBreakerOptions, index_CircuitState as CircuitState, index_FallbackInput as FallbackInput, index_NS_PER_MS as NS_PER_MS, index_NS_PER_SEC as NS_PER_SEC, type index_NodeOrValue as NodeOrValue, index_RateLimiterOptions as RateLimiterOptions, index_RateLimiterState as RateLimiterState, index_ResilientPipelineGraph as ResilientPipelineGraph, type index_ResilientPipelineOptions as ResilientPipelineOptions, index_RetryOptions as RetryOptions, index_StatusValue as StatusValue, index_factoryTag as factoryTag, index_placeholderArgs as placeholderArgs, index_resilientPipeline as resilientPipeline };
+}
+
+export { type NodeOrValue as N, ResilientPipelineGraph as R, type ResilientPipelineOptions as a, index as i, resilientPipeline as r };