@graphrefly/graphrefly 0.39.0 → 0.40.0

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

@@ -1,8 +1,8 @@
 import { N as Node } from './node-BYInONRr.js';
-import { B as BaseAuditRecord } from './index-CusEP3Sv.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-30XSgtVX.js';
+import { a as GraphOptions, G as Graph } from './graph-BkIkog4h.js';
 
 /**
  * CQRS patterns (roadmap §4.5).

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-BAlaVimV.d.ts → index-CQtWm7jS.d.ts}

@@ -1,12 +1,12 @@
 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-C7VV_qOs.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-CPhBvRJU.js';
+import { i as index$9 } from './index-C6ZUaos7.js';
 
 /**
  * Options for creating signals.

package/dist/{index-8R1vzNOx.d.cts → index-CRm0YIzC.d.cts}

@@ -1,12 +1,12 @@
 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-FVoPvhAu.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-DIHcMLr6.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 };

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

@@ -1,6 +1,6 @@
-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-DlrWu9Hs.cjs';
-import { G as Graph, p as GraphNodeFactory, n as GraphDiffResult } from './graph-BUwMAxJI.cjs';
-import { KvStorageTier } from './extra/storage-tiers.cjs';
+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';
 
 /**
  * Surface: create a graph from a {@link GraphSpec} (§9.3-core).

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

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

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

@@ -1,6 +1,6 @@
 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-30XSgtVX.js';
-import { T as TopicGraph } from './index-DszPlZzK.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).

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

@@ -1,5 +1,5 @@
 import { N as Node } from './node-BYInONRr.cjs';
-import { G as Graph, a as GraphOptions } from './graph-BUwMAxJI.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';
 

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

@@ -1,5 +1,5 @@
-import { G as Graph } from './graph-BUwMAxJI.cjs';
-import { M as MeasurementAdapter } from './reactive-layout-8CSc0tiA.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-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 };