@graphrefly/graphrefly 0.38.0 → 0.40.0

package/dist/{index-CijfwEWx.d.ts → index-Cczxgd2D.d.ts}

@@ -1,5 +1,5 @@
-import { j as CompileSpecOptions, G as GraphSpec, c as GraphSpecCatalog, C as CatalogFnEntry, a as CatalogSourceEntry, b as ConfigFieldSchema, F as FnFactory, d as GraphSpecFeedbackEdge, e as GraphSpecNode, f as GraphSpecTemplate, g as GraphSpecTemplateRef, h as GraphSpecValidation, S as SourceFactory } from './index-DTDVDzhA.js';
-import { G as Graph, q as GraphNodeFactory, o as GraphDiffResult } from './graph-BjW1taJl.js';
+import { j as CompileSpecOptions, G as GraphSpec, c as GraphSpecCatalog, C as CatalogFnEntry, a as CatalogSourceEntry, b as ConfigFieldSchema, F as FnFactory, d as GraphSpecFeedbackEdge, e as GraphSpecNode, f as GraphSpecTemplate, g as GraphSpecTemplateRef, h as GraphSpecValidation, S as SourceFactory } from './index-DhLyOHYZ.js';
+import { G as Graph, p as GraphNodeFactory, n as GraphDiffResult } from './graph-BkIkog4h.js';
 import { KvStorageTier } from './extra/storage-tiers.js';
 
 /**

package/dist/{index-CAbHN_rP.d.cts → index-CgnCFhr2.d.cts}

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

package/dist/{index-B2IUcH13.d.cts → index-Ck35nA-T.d.ts}

@@ -1,6 +1,6 @@
-import { A as Actor, a as Node, P as PolicyRuleData, G as GuardAction } from './node-fSc-hCv8.cjs';
-import { G as Graph, a as GraphOptions, b as GraphPersistSnapshot, C as CausalChain } from './graph-CHsVwf9S.cjs';
-import { T as TopicGraph } from './index-BpMZzX9P.cjs';
+import { A as Actor, N as Node, P as PolicyRuleData, G as GuardAction } from './node-BYInONRr.js';
+import { G as Graph, a as GraphOptions, c as GraphPersistSnapshot } from './graph-BkIkog4h.js';
+import { T as TopicGraph } from './index-40ZT4MHj.js';
 
 /**
  * Audit, policy enforcement, and compliance export (roadmap §9.2).
@@ -10,9 +10,10 @@ import { T as TopicGraph } from './index-BpMZzX9P.cjs';
  *
  * - {@link auditTrail} — reactive mutation log with by-node/by-actor/by-time
  *   queries.
- * - {@link policyEnforcer} — reactive ABAC enforcement; in `"audit"` mode
- *   records would-be denials, in `"enforce"` mode pushes guards onto target
- *   nodes so subsequent writes throw {@link GuardDenied}.
+ * - {@link policyGate} — reactive ABAC gate (Tier 2.3 rename of
+ *   `policyEnforcer`); in `"audit"` mode records would-be denials, in
+ *   `"enforce"` mode pushes guards onto target nodes so subsequent writes
+ *   throw {@link GuardDenied}.
  * - {@link complianceSnapshot} — point-in-time export of graph state +
  *   audit trail + policies for regulatory archival.
  *
@@ -88,7 +89,7 @@ declare class AuditTrailGraph extends Graph {
  * snapshot synchronously.
  */
 declare function auditTrail(target: Graph, opts?: AuditTrailOptions): AuditTrailGraph;
-/** A single policy denial recorded by {@link PolicyEnforcerGraph}. */
+/** A single policy denial recorded by {@link PolicyGateGraph}. */
 interface PolicyViolation {
     timestamp_ns: number;
     wall_clock_ns: number;
@@ -99,8 +100,8 @@ interface PolicyViolation {
     /** `"observed"` (audit mode after-the-fact) or `"blocked"` (enforce mode pre-write). */
     result: "observed" | "blocked";
 }
-/** Options for {@link policyEnforcer}. */
-interface PolicyEnforcerOptions {
+/** Options for {@link policyGate}. */
+interface PolicyGateOptions {
     name?: string;
     graph?: GraphOptions;
     /**
@@ -122,14 +123,28 @@ interface PolicyEnforcerOptions {
      * `target` OR any transitively-mounted subgraph after construction are
      * guarded automatically (enforce mode only).
      *
+     * Accepts a static `readonly string[]` or a reactive
+     * `Node<readonly string[]>` (Tier 3.4 — F.9 reactive primitive carve-out).
+     * When a `Node` is passed, the enforcer rebinds the guarded path set on
+     * every emission: paths added to the new set get wrapped, paths removed
+     * from the new set get released, and the audit-mode allow-list filter
+     * uses the latest cached value. Static-array callers retain the current
+     * "caller owns the path set" semantics.
+     *
      * **Cost:** unrestricted mode runs `describe({detail:"minimal"})` once
      * at construction (O(N) over the graph tree) plus one topology
      * subscription per graph instance in the mount tree. Restricted mode
-     * skips both and disables dynamic coverage — callers providing
-     * `paths` must re-create on subgraph changes.
+     * (static or reactive) skips both and disables `watchTopologyTree`
+     * dynamic coverage — for reactive callers, the path-set Node is the
+     * single source of truth for which paths are guarded.
+     */
+    paths?: readonly string[] | Node<readonly string[]>;
+    /**
+     * Ring-buffer cap for the violations topic. Default: 1000. Static
+     * number only — reactive form is deferred pending TopicGraph reactive
+     * `retainedLimit` support (see Tier 10.8 design follow-up in
+     * `docs/optimizations.md`).
      */
-    paths?: readonly string[];
-    /** Ring-buffer cap for the violations topic. Default: 1000. */
     violationsLimit?: number;
 }
 /**
@@ -138,14 +153,14 @@ interface PolicyEnforcerOptions {
  * to update them at runtime; the enforcer rebinds its internal
  * {@link NodeGuard} on every push.
  */
-declare class PolicyEnforcerGraph extends Graph {
+declare class PolicyGateGraph extends Graph {
     readonly policies: Node<readonly PolicyRuleData[]>;
     readonly violations: TopicGraph<PolicyViolation>;
     readonly violationCount: Node<number>;
     private readonly _target;
     private readonly _mode;
     private _currentGuard;
-    constructor(target: Graph, policies: readonly PolicyRuleData[] | Node<readonly PolicyRuleData[]>, opts: PolicyEnforcerOptions);
+    constructor(target: Graph, policies: readonly PolicyRuleData[] | Node<readonly PolicyRuleData[]>, opts: PolicyGateOptions);
     private _publishViolation;
     /** Snapshot of recorded violations. */
     all(): readonly PolicyViolation[];
@@ -157,37 +172,16 @@ declare class PolicyEnforcerGraph extends Graph {
  * static rule list or a {@link Node} of rules (LLM-updatable). Records
  * `PolicyViolation` entries to `violations` topic; in `"enforce"` mode also
  * pushes guards onto target nodes so disallowed writes throw.
- */
-declare function policyEnforcer(target: Graph, policies: readonly PolicyRuleData[] | Node<readonly PolicyRuleData[]>, opts?: PolicyEnforcerOptions): PolicyEnforcerGraph;
-/**
- * Reactive {@link CausalChain} that recomputes whenever the audited graph
- * changes. Returns a `Node<CausalChain>` suitable for subscription, mounting,
- * or composition (e.g. inside `graphLens.why(node)`).
  *
- * **How it stays live:** an internal `version` state is bumped by an observer
- * attached to `target.observe()`; the derived chain depends on `version`, so
- * each mutation triggers a recompute. To avoid stalling on no-op events, only
- * `data`, `error`, `complete`, and `teardown` bump the version (matching the
- * audit defaults).
- */
-/**
- * @deprecated Use `graph.explain(from, to, { reactive: true, ... })` directly.
- *   This free-function wrapper now dispatches to the consolidated
- *   {@link Graph.explain} overload for mental-model consistency with
- *   `describe` / `observe`. Will be removed pre-1.0.
+ * Self-tags via `g.tagFactory("policyGate", placeholderArgs(opts))` so
+ * `graph.describe()` surfaces `factory: "policyGate"` provenance (Phase 2.5
+ * DT5 ride-along, locked with the Tier 2.3 rename).
  */
-declare function reactiveExplainPath(target: Graph, from: string, to: string, opts?: {
-    maxDepth?: number;
-    name?: string;
-    findCycle?: boolean;
-}): {
-    node: Node<CausalChain>;
-    dispose: () => void;
-};
+declare function policyGate(target: Graph, policies: readonly PolicyRuleData[] | Node<readonly PolicyRuleData[]>, opts?: PolicyGateOptions): PolicyGateGraph;
 /** Options for {@link complianceSnapshot}. */
 interface ComplianceSnapshotOptions {
     audit?: AuditTrailGraph;
-    policies?: PolicyEnforcerGraph;
+    policies?: PolicyGateGraph;
     /** Actor recorded as the snapshot taker. */
     actor?: Actor;
 }
@@ -236,16 +230,15 @@ 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_PolicyGateGraph = PolicyGateGraph;
+declare const index_PolicyGateGraph: typeof PolicyGateGraph;
+type index_PolicyGateOptions = PolicyGateOptions;
 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 const index_policyGate: typeof policyGate;
 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 index_AuditEntry as AuditEntry, index_AuditTrailGraph as AuditTrailGraph, type index_AuditTrailOptions as AuditTrailOptions, type index_ComplianceSnapshotOptions as ComplianceSnapshotOptions, type index_ComplianceSnapshotResult as ComplianceSnapshotResult, index_PolicyGateGraph as PolicyGateGraph, type index_PolicyGateOptions as PolicyGateOptions, type index_PolicyViolation as PolicyViolation, index_auditTrail as auditTrail, index_complianceSnapshot as complianceSnapshot, index_policyGate as policyGate };
 }
 
-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 };
+export { type AuditEntry as A, type ComplianceSnapshotOptions as C, PolicyGateGraph as P, type PolicyViolation as a, AuditTrailGraph as b, type AuditTrailOptions as c, type ComplianceSnapshotResult as d, type PolicyGateOptions as e, auditTrail as f, complianceSnapshot as g, index as i, policyGate as p };

package/dist/{index-BpMZzX9P.d.cts → index-Cnr1WrlX.d.cts}

@@ -1,6 +1,6 @@
-import { a as Node } from './node-fSc-hCv8.cjs';
-import { G as Graph, a as GraphOptions } from './graph-CHsVwf9S.cjs';
-import { R as ReactiveLogBundle } from './reactive-log-C3IMAGpT.cjs';
+import { N as Node } from './node-BYInONRr.cjs';
+import { G as Graph, a as GraphOptions } from './graph-E6likq7w.cjs';
+import { a as ReactiveLogBundle } from './reactive-log-_zeEnB9H.cjs';
 import { AppendLogStorageTier } from './extra/storage-tiers.cjs';
 
 type TopicOptions = {

package/dist/{index-JYtN9uqM.d.ts → index-CoM4rzyB.d.ts}

@@ -1,4 +1,4 @@
-import { a as Node } from './node-fSc-hCv8.js';
+import { N as Node } from './node-BYInONRr.js';
 
 /**
  * Options for creating an atom.

package/dist/{index-Ckil6miL.d.cts → index-CtFNGe-m.d.cts}

@@ -1,5 +1,5 @@
-import { G as Graph } from './graph-CHsVwf9S.cjs';
-import { M as MeasurementAdapter } from './reactive-layout-BMLDB4Vd.cjs';
+import { G as Graph } from './graph-E6likq7w.cjs';
+import { M as MeasurementAdapter } from './reactive-layout-BtZfUKuL.cjs';
 
 /**
  * Three-pane demo shell (roadmap §7.2).

package/dist/{index-BjWZARLy.d.ts → index-Ctb7_2sG.d.ts}

@@ -1,4 +1,4 @@
-import { a as Node } from './node-fSc-hCv8.js';
+import { N as Node } from './node-BYInONRr.js';
 
 /** Svelte store contract — implements the minimal `subscribe` method. */
 interface SvelteReadable<T> {

package/dist/index-CuPUehFa.d.cts

@@ -0,0 +1,218 @@
+import { N as Node, A as Actor, P as PolicyRuleData } from './node-BYInONRr.cjs';
+import { G as Graph, b as GraphDescribeOutput, a as GraphOptions, d as GraphDescribeOptions, D as DescribeFilter } from './graph-E6likq7w.cjs';
+import { P as PolicyGateGraph, a as PolicyViolation } from './index-BmSQLAZo.cjs';
+import { T as TopicGraph } from './index-Cnr1WrlX.cjs';
+
+/**
+ * Composable safety layer (roadmap §9.0b — Tier 5.1 Wave-B rebuild).
+ *
+ * {@link guardedExecution} wraps any {@link Graph} with:
+ *
+ * - {@link policyGate} — reactive ABAC (Tier 2.3 rename of `policyEnforcer`),
+ *   policies stored as a `Node` so LLMs / humans can update them at runtime.
+ *   Full transitive dynamic coverage via `watchTopologyTree`.
+ * - Reactive {@link GuardedExecutionGraph.scopedDescribeNode} — a thin
+ *   delegate over `target.describe({ reactive: true, actor })` that re-derives
+ *   on every settle (topology change, error transition, actor swap).
+ * - The enforcer's `violations` topic is republished as `violations` on
+ *   the wrapper, composable with {@link graphLens}'s `health`.
+ * - The wrapper-level `lints` topic surfaces non-policy diagnostic warnings
+ *   (`empty-policies` / `audit-no-effect` / `no-actor`) so misconfigurations
+ *   are caught reactively rather than via thrown errors at scattered call sites.
+ * - The `scope` derived publishes the current configuration tuple
+ *   (`{actor, mode, policiesCount}`) for dashboards.
+ *
+ * V1 scope: policies + actor + reactive scoped describe + lints + scope.
+ * Budget-as-option is NOT in V1 — it requires a cost-tracking design that
+ * hasn't landed yet. Callers who need a budget limit today append a
+ * budget-aware {@link PolicyRuleData} to the policies list (check current
+ * cost and `deny` when exhausted).
+ *
+ * @module
+ */
+
+/** Diagnostic warning published on {@link GuardedExecutionGraph.lints}. */
+interface GuardedExecutionLint {
+    /**
+     * - `"empty-policies"` — `policies` Node emitted an empty array in
+     *   `mode: "enforce"`. Static empty arrays throw at construction; this
+     *   covers the reactive case.
+     * - `"audit-no-effect"` — `mode: "audit"` plus the target has no per-node
+     *   guards, so `scopedDescribeNode` filters by per-node guards only and
+     *   policies will never gate visibility (they still populate `violations`
+     *   on writes).
+     * - `"no-actor"` — neither a wrapper-configured nor per-call actor was
+     *   supplied. `scopedDescribeNode` falls back to "describe everything"
+     *   for the corresponding subscription.
+     */
+    kind: "empty-policies" | "audit-no-effect" | "no-actor";
+    message: string;
+    timestamp_ns: number;
+}
+/** Configuration tuple published on {@link GuardedExecutionGraph.scope}. */
+interface GuardedScope {
+    /** The wrapper-configured default actor, or `null` when none configured. */
+    actor: Actor | null;
+    mode: "audit" | "enforce";
+    /** Current policy count (reactive — re-emits on `policies` Node updates). */
+    policiesCount: number;
+}
+/** Options for {@link guardedExecution}. */
+interface GuardedExecutionOptions {
+    /**
+     * Policies enforced against every guarded write. Static list or a live
+     * `Node<readonly PolicyRuleData[]>` (LLM-updatable).
+     *
+     * **Empty-policies handling:**
+     * - Static empty array + `mode: "enforce"` throws `RangeError` at
+     *   construction (deny-by-default is almost certainly a misconfiguration).
+     * - Node-supplied empty array + `mode: "enforce"` emits a one-time
+     *   `"empty-policies"` lint on first such emission (the wrapper can't
+     *   throw mid-run — surface the warning reactively).
+     * - `mode: "audit"` tolerates empty policies (no guards stacked; policies
+     *   only feed the `violations` channel on writes).
+     */
+    policies: readonly PolicyRuleData[] | Node<readonly PolicyRuleData[]>;
+    /**
+     * Default actor used when the caller invokes
+     * {@link GuardedExecutionGraph.scopedDescribeNode} without an override.
+     * Accepts a static {@link Actor} or a `Node<Actor>` — when a Node is
+     * supplied, the reactive describe re-derives on every actor emission so
+     * harnesses binding a per-turn actor get a single live describe Node
+     * instead of re-creating one per turn.
+     *
+     * Omit to scope per-call only. A `"no-actor"` lint fires once per instance
+     * if neither a configured nor per-call actor is ever supplied (the
+     * resulting describe is unscoped — full visibility).
+     */
+    actor?: Actor | Node<Actor>;
+    /**
+     * `"enforce"` (default) — push guards onto target nodes so disallowed
+     * writes throw {@link GuardDenied}.
+     * `"audit"` — record would-be denials to the `violations` topic without
+     * blocking writes.
+     */
+    mode?: "audit" | "enforce";
+    /** Ring-buffer cap for the `violations` topic. Default 1000 (inherited from policyGate). */
+    violationsLimit?: number;
+    /** Ring-buffer cap for the `lints` topic. Default 64 — each lint kind fires at most once per instance. */
+    lintsLimit?: number;
+    /** Wrapper graph name. Default `${target.name}_guarded`. */
+    name?: string;
+    /** Wrapper graph options. */
+    graph?: GraphOptions;
+}
+/**
+ * Wrapper over a target {@link Graph} providing reactive ABAC + reactive
+ * scoped describe + diagnostic lints. Mounts a {@link PolicyGateGraph} under
+ * `enforcer`, a {@link TopicGraph} of {@link GuardedExecutionLint} under
+ * `lints`, and a `scope` derived publishing `{actor, mode, policiesCount}`.
+ *
+ * @category patterns
+ */
+declare class GuardedExecutionGraph extends Graph {
+    readonly enforcer: PolicyGateGraph;
+    readonly violations: TopicGraph<PolicyViolation>;
+    readonly lints: TopicGraph<GuardedExecutionLint>;
+    readonly scope: Node<GuardedScope>;
+    /**
+     * Canonical reactive describe scoped to the wrapper's configured `actor`.
+     * Subscribes ONCE at construction; lifecycle owned by the wrapper (disposed
+     * on `wrapper.destroy()`). Use this property for the common case
+     * (long-lived consumer wanting "describe scoped to my actor"); use
+     * {@link scopedDescribeNode} only when a per-call actor override or
+     * different `detail`/`fields` is required.
+     *
+     * Re-derives on every settle of the target graph: structural changes,
+     * status transitions (errors flip nodes into `"errored"`), and actor
+     * emissions (when a `Node<Actor>` is bound, including the SENTINEL bridge
+     * applied internally — see qa G1B).
+     */
+    readonly scopedDescribe: Node<GraphDescribeOutput>;
+    private readonly _target;
+    private readonly _actorNode;
+    private readonly _mode;
+    private readonly _firedLintKinds;
+    constructor(target: Graph, opts: GuardedExecutionOptions);
+    private _fireLint;
+    /**
+     * **Per-call escape hatch.** Prefer {@link scopedDescribe} (the mounted
+     * property) for the common case of "describe scoped to my actor." Use
+     * this method ONLY when you need a per-call actor override or different
+     * `detail`/`fields`/`filter`.
+     *
+     * Returns a live `Node<GraphDescribeOutput>` scoped to the supplied (or
+     * configured) actor, plus an explicit `dispose` for caller-controlled
+     * lifecycle. Re-derives on every settle of the target graph: structural
+     * changes, status transitions, and actor emissions (when a `Node<Actor>`
+     * is bound).
+     *
+     * **Lifecycle (qa G1A — EC1 fix).** Each call instantiates a fresh
+     * `target.describe({reactive: true})` handle (with its own version state,
+     * observe handle, transitive topology subscriptions, derived + keepalive).
+     * The caller MUST invoke the returned `dispose()` when finished to release
+     * these resources. Disposers ARE also tracked on the wrapper graph so
+     * `wrapper.destroy()` cleans up any handles the caller forgot — but a
+     * long-lived wrapper with heavy per-call usage will leak until destroy
+     * unless `dispose()` is called explicitly.
+     *
+     * @param actorOverride - Optional per-call override. Static {@link Actor}
+     *   or `Node<Actor>`. Omit to use the wrapper-configured default.
+     * @param opts - Standard {@link GraphDescribeOptions} fields (`detail`,
+     *   `fields`, `filter`). `actor` / `reactive` / `reactiveName` are
+     *   controlled by the wrapper.
+     * @returns `{node, dispose}` — `node` is the live describe Node; `dispose`
+     *   tears down the underlying reactive describe subscription idempotently.
+     */
+    scopedDescribeNode(actorOverride?: Actor | Node<Actor>, opts?: Omit<GraphDescribeOptions, "actor" | "reactive" | "reactiveName">): {
+        node: Node<GraphDescribeOutput>;
+        dispose: () => void;
+    };
+    /** The wrapped graph (escape hatch for tooling). */
+    get target(): Graph;
+}
+/**
+ * Wrap a {@link Graph} with {@link policyGate} plus a reactive scoped describe
+ * lens. Returns a {@link GuardedExecutionGraph} that can be mounted, diffed,
+ * or composed with {@link graphLens}.
+ *
+ * @param target - The graph to guard.
+ * @param opts - See {@link GuardedExecutionOptions}.
+ *
+ * @example
+ * ```ts
+ * const guarded = guardedExecution(app, {
+ *   actor: state<Actor>({ type: "human", id: "alice" }), // reactive — re-derive on swap
+ *   policies: [
+ *     { effect: "allow", action: "read", actorType: "human" },
+ *     { effect: "deny", action: "write", pathPattern: "system::*" },
+ *   ],
+ *   mode: "enforce",
+ * });
+ *
+ * // Canonical: subscribe to the mounted reactive describe (no per-call leak).
+ * guarded.scopedDescribe.subscribe((msgs) => { /* live describe per actor / topology change *\/ });
+ * // Per-call escape hatch (different actor / detail) — caller manages dispose.
+ * const detailed = guarded.scopedDescribeNode(undefined, { detail: "standard" });
+ * try { detailed.node.subscribe(/* … *\/); } finally { detailed.dispose(); }
+ * guarded.violations.events.subscribe(msgs => console.log("violations:", msgs));
+ * guarded.lints.events.subscribe(msgs => console.warn("lints:", msgs));
+ * guarded.scope.subscribe(msgs => console.log("scope:", msgs));
+ * ```
+ *
+ * @category patterns
+ */
+declare function guardedExecution(target: Graph, opts: GuardedExecutionOptions): GuardedExecutionGraph;
+
+declare const index_DescribeFilter: typeof DescribeFilter;
+type index_GuardedExecutionGraph = GuardedExecutionGraph;
+declare const index_GuardedExecutionGraph: typeof GuardedExecutionGraph;
+type index_GuardedExecutionLint = GuardedExecutionLint;
+type index_GuardedExecutionOptions = GuardedExecutionOptions;
+type index_GuardedScope = GuardedScope;
+declare const index_guardedExecution: typeof guardedExecution;
+declare namespace index {
+  export { index_DescribeFilter as DescribeFilter, index_GuardedExecutionGraph as GuardedExecutionGraph, type index_GuardedExecutionLint as GuardedExecutionLint, type index_GuardedExecutionOptions as GuardedExecutionOptions, type index_GuardedScope as GuardedScope, index_guardedExecution as guardedExecution };
+}
+
+export { GuardedExecutionGraph as G, type GuardedExecutionLint as a, type GuardedExecutionOptions as b, type GuardedScope as c, guardedExecution as g, index as i };

package/dist/index-D1Gc7wV5.d.ts

@@ -0,0 +1,230 @@
+import { f as factoryTag, p as placeholderArgs } from './meta-D8OyedKp.js';
+import { N as Node } from './node-BYInONRr.js';
+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-BAQrjuZF.js';
+import { G as Graph, a as GraphOptions } from './graph-BkIkog4h.js';
+import { B as BudgetConstraint } from './budget-gate-CmmVtasH.js';
+
+/**
+ * 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 };