@graphrefly/graphrefly 0.38.0 → 0.40.0

package/dist/{index-DqICM_I7.d.ts → index-D1IEZUsj.d.ts}

@@ -1,11 +1,11 @@
 import { NodeInput } from './extra/sources.js';
-import { a as Node } from './node-fSc-hCv8.js';
-import { L as LLMAdapter } from './types-CidcBDuk.js';
-import { T as TopicGraph, M as MessagingHubGraph } from './index-BUFCHvOR.js';
-import { E as Evaluator, D as DatasetItem, a as EvalResult$1, R as RefineStrategy, b as RefineLoopOptions, c as RefineStatus } from './index-BI1wMfyc.js';
-import { G as Graph, u as GraphProfileResult, t as GraphProfileOptions } from './graph-BjW1taJl.js';
-import { G as GateController } from './pipeline-graph-9JBbmRxA.js';
-import { J as JobQueueGraph } from './index-D9vBTuzo.js';
+import { N as Node } from './node-BYInONRr.js';
+import { L as LLMAdapter } from './types-39jk0kaV.js';
+import { T as TopicGraph, M as MessagingHubGraph } from './index-40ZT4MHj.js';
+import { E as Evaluator, D as DatasetItem, a as EvalResult$1, R as RefineStrategy, b as RefineLoopOptions, c as RefineStatus } from './index-BgjS2b8N.js';
+import { G as Graph, t as GraphProfileResult, s as GraphProfileOptions } from './graph-BkIkog4h.js';
+import { G as GateController } from './pipeline-graph-CB4La-UW.js';
+import { J as JobQueueGraph } from './index-IUCY0OFN.js';
 
 /**
  * Strategy model and priority scoring (roadmap §9.0).
@@ -843,6 +843,59 @@ interface NotifyEffectOptions {
  */
 declare function notifyEffect<T>(topic: TopicGraph<T>, transport: NotifyTransport<T>, opts?: NotifyEffectOptions): Node<unknown>;
 
+/**
+ * `effectivenessTracker` — action×context → success rate tracker.
+ *
+ * Demoted from `patterns/reduction` to `patterns/harness/` per Tier 2.3
+ * (consolidation plan §1 Rule 6). The only in-tree consumer is the harness
+ * strategy model, so the primitive moves alongside it. Building-block status
+ * is dropped: this is a harness-shaped preset (a small composition over
+ * `reactiveMap` with attempt-counting semantics) rather than an orthogonal
+ * primitive.
+ *
+ * @module
+ */
+
+/** A single effectiveness record for an action×context pair. */
+type EffectivenessEntry = {
+    readonly key: string;
+    readonly attempts: number;
+    readonly successes: number;
+    readonly successRate: number;
+};
+/** Snapshot shape for the effectiveness tracker node. */
+type EffectivenessSnapshot = ReadonlyMap<string, EffectivenessEntry>;
+/** Bundle returned by {@link effectivenessTracker}. */
+interface EffectivenessTrackerBundle {
+    /** Reactive node — current effectiveness map snapshot. */
+    readonly node: Node<EffectivenessSnapshot>;
+    /** Record a completed action (success or failure). */
+    record(key: string, success: boolean): void;
+    /** Look up effectiveness for a specific key. */
+    lookup(key: string): EffectivenessEntry | undefined;
+    /** Tear down internal keepalive subscriptions. */
+    dispose(): void;
+}
+/** Options for {@link effectivenessTracker}. */
+type EffectivenessTrackerOptions = {
+    /** Name for the reactive map (default "effectiveness-entries"). */
+    name?: string;
+};
+/**
+ * Generic action×context → success rate tracker.
+ *
+ * Generalized from the harness `strategyModel` pattern. Tracks attempts and
+ * successes per string key, exposes a reactive snapshot node, and provides
+ * `record()` / `lookup()` methods.
+ *
+ * Use cases: A/B testing, routing optimization, cache policy tuning, retry
+ * strategy selection — any domain that tracks effectiveness per action.
+ *
+ * @param opts - Optional configuration.
+ * @returns Bundle with reactive node, record(), lookup(), dispose().
+ */
+declare function effectivenessTracker(opts?: EffectivenessTrackerOptions): EffectivenessTrackerBundle;
+
 /**
  * evalVerifier — re-run the affected eval tasks against the execute-stage
  * artifact instead of asking an LLM to opine on the fix.
@@ -1335,6 +1388,10 @@ declare const index_DEFAULT_SEVERITY_WEIGHTS: typeof DEFAULT_SEVERITY_WEIGHTS;
 declare const index_DEFAULT_TRIAGE_PROMPT: typeof DEFAULT_TRIAGE_PROMPT;
 declare const index_DEFAULT_VERIFY_PROMPT: typeof DEFAULT_VERIFY_PROMPT;
 type index_DispatchActuatorConfig<R> = DispatchActuatorConfig<R>;
+type index_EffectivenessEntry = EffectivenessEntry;
+type index_EffectivenessSnapshot = EffectivenessSnapshot;
+type index_EffectivenessTrackerBundle = EffectivenessTrackerBundle;
+type index_EffectivenessTrackerOptions = EffectivenessTrackerOptions;
 type index_ErrorClass = ErrorClass;
 type index_ErrorClassifier = ErrorClassifier;
 type index_EvalDelta = EvalDelta;
@@ -1396,6 +1453,7 @@ declare const index_defaultErrorClassifier: typeof defaultErrorClassifier;
 declare const index_defaultLlmExecutor: typeof defaultLlmExecutor;
 declare const index_defaultLlmVerifier: typeof defaultLlmVerifier;
 declare const index_dispatchActuator: typeof dispatchActuator;
+declare const index_effectivenessTracker: typeof effectivenessTracker;
 declare const index_evalIntakeBridge: typeof evalIntakeBridge;
 declare const index_evalSource: typeof evalSource;
 declare const index_evalVerifier: typeof evalVerifier;
@@ -1410,7 +1468,7 @@ declare const index_resolvePromptFn: typeof resolvePromptFn;
 declare const index_strategyKey: typeof strategyKey;
 declare const index_strategyModel: typeof strategyModel;
 declare namespace index {
-  export { type index_ActuatorApplyFn as ActuatorApplyFn, type index_ActuatorExecutorConfig as ActuatorExecutorConfig, type index_ActuatorResult as ActuatorResult, type index_AutoSolidifyConfig as AutoSolidifyConfig, type index_CodeChange as CodeChange, type index_CodeChangeBridgeOptions as CodeChangeBridgeOptions, index_DEFAULT_DECAY_RATE as DEFAULT_DECAY_RATE, index_DEFAULT_EXECUTE_PROMPT as DEFAULT_EXECUTE_PROMPT, index_DEFAULT_QUEUE_CONFIGS as DEFAULT_QUEUE_CONFIGS, index_DEFAULT_SEVERITY_WEIGHTS as DEFAULT_SEVERITY_WEIGHTS, index_DEFAULT_TRIAGE_PROMPT as DEFAULT_TRIAGE_PROMPT, index_DEFAULT_VERIFY_PROMPT as DEFAULT_VERIFY_PROMPT, type index_DispatchActuatorConfig as DispatchActuatorConfig, type index_ErrorClass as ErrorClass, type index_ErrorClassifier as ErrorClassifier, type index_EvalDelta as EvalDelta, type index_EvalIntakeBridgeOptions as EvalIntakeBridgeOptions, type index_EvalJudgeScore as EvalJudgeScore, type index_EvalResult as EvalResult, type index_EvalTaskDelta as EvalTaskDelta, type index_EvalTaskResult as EvalTaskResult, type index_EvalVerifierConfig as EvalVerifierConfig, type index_EvalVerifierSummary as EvalVerifierSummary, type index_ExecuteOutput as ExecuteOutput, type index_ExecutePromptFn as ExecutePromptFn, type index_ExecutionResult as ExecutionResult, type index_HarnessEvalPairConfig as HarnessEvalPairConfig, type index_HarnessExecutor as HarnessExecutor, index_HarnessGraph as HarnessGraph, type index_HarnessLoopOptions as HarnessLoopOptions, type index_HarnessProfileResult as HarnessProfileResult, type index_HarnessTraceHandle as HarnessTraceHandle, type index_HarnessTraceOptions as HarnessTraceOptions, type index_HarnessVerifier as HarnessVerifier, type index_IntakeBridgeOptions as IntakeBridgeOptions, type index_IntakeItem as IntakeItem, type index_IntakeSource as IntakeSource, type index_Intervention as Intervention, type index_KnownIntakeSource as KnownIntakeSource, type index_LintError as LintError, type index_NotifyEffectOptions as NotifyEffectOptions, type index_NotifyTransport as NotifyTransport, type index_PrioritySignals as PrioritySignals, index_QUEUE_NAMES as QUEUE_NAMES, type index_QueueConfig as QueueConfig, type index_QueueRoute as QueueRoute, type index_RefineExecutorConfig as RefineExecutorConfig, type index_RefineExecutorResult as RefineExecutorResult, type index_RootCause as RootCause, type index_Severity as Severity, type index_StrategyEntry as StrategyEntry, type index_StrategyKey as StrategyKey, type index_StrategyModelBundle as StrategyModelBundle, type index_StrategySnapshot as StrategySnapshot, type index_TestFailure as TestFailure, type index_TraceDetail as TraceDetail, type index_TraceEvent as TraceEvent, type index_TraceEventType as TraceEventType, type index_TriagePromptFn as TriagePromptFn, type index_TriagedItem as TriagedItem, type index_VerifyOutput as VerifyOutput, type index_VerifyPromptFn as VerifyPromptFn, type index_VerifyResult as VerifyResult, index_actuatorExecutor as actuatorExecutor, index_affectedTaskFilter as affectedTaskFilter, index_autoSolidify as autoSolidify, index_beforeAfterCompare as beforeAfterCompare, index_codeChangeBridge as codeChangeBridge, index_createIntakeBridge as createIntakeBridge, index_defaultErrorClassifier as defaultErrorClassifier, index_defaultLlmExecutor as defaultLlmExecutor, index_defaultLlmVerifier as defaultLlmVerifier, index_dispatchActuator as dispatchActuator, index_evalIntakeBridge as evalIntakeBridge, index_evalSource as evalSource, index_evalVerifier as evalVerifier, index_harnessEvalPair as harnessEvalPair, index_harnessLoop as harnessLoop, index_harnessProfile as harnessProfile, index_harnessTrace as harnessTrace, index_notifyEffect as notifyEffect, index_priorityScore as priorityScore, index_refineExecutor as refineExecutor, index_resolvePromptFn as resolvePromptFn, index_strategyKey as strategyKey, index_strategyModel as strategyModel };
+  export { type index_ActuatorApplyFn as ActuatorApplyFn, type index_ActuatorExecutorConfig as ActuatorExecutorConfig, type index_ActuatorResult as ActuatorResult, type index_AutoSolidifyConfig as AutoSolidifyConfig, type index_CodeChange as CodeChange, type index_CodeChangeBridgeOptions as CodeChangeBridgeOptions, index_DEFAULT_DECAY_RATE as DEFAULT_DECAY_RATE, index_DEFAULT_EXECUTE_PROMPT as DEFAULT_EXECUTE_PROMPT, index_DEFAULT_QUEUE_CONFIGS as DEFAULT_QUEUE_CONFIGS, index_DEFAULT_SEVERITY_WEIGHTS as DEFAULT_SEVERITY_WEIGHTS, index_DEFAULT_TRIAGE_PROMPT as DEFAULT_TRIAGE_PROMPT, index_DEFAULT_VERIFY_PROMPT as DEFAULT_VERIFY_PROMPT, type index_DispatchActuatorConfig as DispatchActuatorConfig, type index_EffectivenessEntry as EffectivenessEntry, type index_EffectivenessSnapshot as EffectivenessSnapshot, type index_EffectivenessTrackerBundle as EffectivenessTrackerBundle, type index_EffectivenessTrackerOptions as EffectivenessTrackerOptions, type index_ErrorClass as ErrorClass, type index_ErrorClassifier as ErrorClassifier, type index_EvalDelta as EvalDelta, type index_EvalIntakeBridgeOptions as EvalIntakeBridgeOptions, type index_EvalJudgeScore as EvalJudgeScore, type index_EvalResult as EvalResult, type index_EvalTaskDelta as EvalTaskDelta, type index_EvalTaskResult as EvalTaskResult, type index_EvalVerifierConfig as EvalVerifierConfig, type index_EvalVerifierSummary as EvalVerifierSummary, type index_ExecuteOutput as ExecuteOutput, type index_ExecutePromptFn as ExecutePromptFn, type index_ExecutionResult as ExecutionResult, type index_HarnessEvalPairConfig as HarnessEvalPairConfig, type index_HarnessExecutor as HarnessExecutor, index_HarnessGraph as HarnessGraph, type index_HarnessLoopOptions as HarnessLoopOptions, type index_HarnessProfileResult as HarnessProfileResult, type index_HarnessTraceHandle as HarnessTraceHandle, type index_HarnessTraceOptions as HarnessTraceOptions, type index_HarnessVerifier as HarnessVerifier, type index_IntakeBridgeOptions as IntakeBridgeOptions, type index_IntakeItem as IntakeItem, type index_IntakeSource as IntakeSource, type index_Intervention as Intervention, type index_KnownIntakeSource as KnownIntakeSource, type index_LintError as LintError, type index_NotifyEffectOptions as NotifyEffectOptions, type index_NotifyTransport as NotifyTransport, type index_PrioritySignals as PrioritySignals, index_QUEUE_NAMES as QUEUE_NAMES, type index_QueueConfig as QueueConfig, type index_QueueRoute as QueueRoute, type index_RefineExecutorConfig as RefineExecutorConfig, type index_RefineExecutorResult as RefineExecutorResult, type index_RootCause as RootCause, type index_Severity as Severity, type index_StrategyEntry as StrategyEntry, type index_StrategyKey as StrategyKey, type index_StrategyModelBundle as StrategyModelBundle, type index_StrategySnapshot as StrategySnapshot, type index_TestFailure as TestFailure, type index_TraceDetail as TraceDetail, type index_TraceEvent as TraceEvent, type index_TraceEventType as TraceEventType, type index_TriagePromptFn as TriagePromptFn, type index_TriagedItem as TriagedItem, type index_VerifyOutput as VerifyOutput, type index_VerifyPromptFn as VerifyPromptFn, type index_VerifyResult as VerifyResult, index_actuatorExecutor as actuatorExecutor, index_affectedTaskFilter as affectedTaskFilter, index_autoSolidify as autoSolidify, index_beforeAfterCompare as beforeAfterCompare, index_codeChangeBridge as codeChangeBridge, index_createIntakeBridge as createIntakeBridge, index_defaultErrorClassifier as defaultErrorClassifier, index_defaultLlmExecutor as defaultLlmExecutor, index_defaultLlmVerifier as defaultLlmVerifier, index_dispatchActuator as dispatchActuator, index_effectivenessTracker as effectivenessTracker, index_evalIntakeBridge as evalIntakeBridge, index_evalSource as evalSource, index_evalVerifier as evalVerifier, index_harnessEvalPair as harnessEvalPair, index_harnessLoop as harnessLoop, index_harnessProfile as harnessProfile, index_harnessTrace as harnessTrace, index_notifyEffect as notifyEffect, index_priorityScore as priorityScore, index_refineExecutor as refineExecutor, index_resolvePromptFn as resolvePromptFn, index_strategyKey as strategyKey, index_strategyModel as strategyModel };
 }
 
-export { type StrategyModelBundle as $, type ActuatorApplyFn as A, type HarnessProfileResult as B, type CodeChange as C, DEFAULT_DECAY_RATE as D, type ErrorClass as E, type HarnessTraceHandle as F, type HarnessTraceOptions as G, type HarnessEvalPairConfig as H, type HarnessVerifier as I, type IntakeBridgeOptions as J, type IntakeItem as K, type IntakeSource as L, type Intervention as M, type KnownIntakeSource as N, type LintError as O, type NotifyEffectOptions as P, type NotifyTransport as Q, type PrioritySignals as R, QUEUE_NAMES as S, type QueueConfig as T, type QueueRoute as U, type RefineExecutorConfig as V, type RefineExecutorResult as W, type RootCause as X, type Severity as Y, type StrategyEntry as Z, type StrategyKey as _, type ActuatorExecutorConfig as a, type StrategySnapshot as a0, type TestFailure as a1, type TraceDetail as a2, type TraceEvent as a3, type TraceEventType as a4, type TriagePromptFn as a5, type TriagedItem as a6, type VerifyOutput as a7, type VerifyPromptFn as a8, type VerifyResult as a9, actuatorExecutor as aa, affectedTaskFilter as ab, autoSolidify as ac, beforeAfterCompare as ad, codeChangeBridge as ae, createIntakeBridge as af, defaultErrorClassifier as ag, defaultLlmExecutor as ah, defaultLlmVerifier as ai, dispatchActuator as aj, evalIntakeBridge as ak, evalSource as al, evalVerifier as am, harnessEvalPair as an, harnessLoop as ao, harnessProfile as ap, harnessTrace as aq, notifyEffect as ar, priorityScore as as, refineExecutor as at, resolvePromptFn as au, strategyKey as av, strategyModel as aw, type ActuatorResult as b, type AutoSolidifyConfig as c, type CodeChangeBridgeOptions as d, DEFAULT_EXECUTE_PROMPT as e, DEFAULT_QUEUE_CONFIGS as f, DEFAULT_SEVERITY_WEIGHTS as g, DEFAULT_TRIAGE_PROMPT as h, index as i, DEFAULT_VERIFY_PROMPT as j, type DispatchActuatorConfig as k, type ErrorClassifier as l, type EvalDelta as m, type EvalIntakeBridgeOptions as n, type EvalJudgeScore as o, type EvalResult as p, type EvalTaskDelta as q, type EvalTaskResult as r, type EvalVerifierConfig as s, type EvalVerifierSummary as t, type ExecuteOutput as u, type ExecutePromptFn as v, type ExecutionResult as w, type HarnessExecutor as x, HarnessGraph as y, type HarnessLoopOptions as z };
+export { type RootCause as $, type ActuatorApplyFn as A, type ExecutionResult as B, type CodeChange as C, DEFAULT_DECAY_RATE as D, type EffectivenessEntry as E, type HarnessExecutor as F, HarnessGraph as G, type HarnessEvalPairConfig as H, type HarnessLoopOptions as I, type HarnessProfileResult as J, type HarnessTraceHandle as K, type HarnessTraceOptions as L, type HarnessVerifier as M, type IntakeBridgeOptions as N, type IntakeItem as O, type IntakeSource as P, type Intervention as Q, type KnownIntakeSource as R, type LintError as S, type NotifyEffectOptions as T, type NotifyTransport as U, type PrioritySignals as V, QUEUE_NAMES as W, type QueueConfig as X, type QueueRoute as Y, type RefineExecutorConfig as Z, type RefineExecutorResult as _, type ActuatorExecutorConfig as a, type Severity as a0, type StrategyEntry as a1, type StrategyKey as a2, type StrategyModelBundle as a3, type StrategySnapshot as a4, type TestFailure as a5, type TraceDetail as a6, type TraceEvent as a7, type TraceEventType as a8, type TriagePromptFn as a9, strategyKey as aA, strategyModel as aB, type TriagedItem as aa, type VerifyOutput as ab, type VerifyPromptFn as ac, type VerifyResult as ad, actuatorExecutor as ae, affectedTaskFilter as af, autoSolidify as ag, beforeAfterCompare as ah, codeChangeBridge as ai, createIntakeBridge as aj, defaultErrorClassifier as ak, defaultLlmExecutor as al, defaultLlmVerifier as am, dispatchActuator as an, effectivenessTracker as ao, evalIntakeBridge as ap, evalSource as aq, evalVerifier as ar, harnessEvalPair as as, harnessLoop as at, harnessProfile as au, harnessTrace as av, notifyEffect as aw, priorityScore as ax, refineExecutor as ay, resolvePromptFn as az, type ActuatorResult as b, type AutoSolidifyConfig as c, type CodeChangeBridgeOptions as d, DEFAULT_EXECUTE_PROMPT as e, DEFAULT_QUEUE_CONFIGS as f, DEFAULT_SEVERITY_WEIGHTS as g, DEFAULT_TRIAGE_PROMPT as h, index as i, DEFAULT_VERIFY_PROMPT as j, type DispatchActuatorConfig as k, type EffectivenessSnapshot as l, type EffectivenessTrackerBundle as m, type EffectivenessTrackerOptions as n, type ErrorClass as o, type ErrorClassifier as p, type EvalDelta as q, type EvalIntakeBridgeOptions as r, type EvalJudgeScore as s, type EvalResult as t, type EvalTaskDelta as u, type EvalTaskResult as v, type EvalVerifierConfig as w, type EvalVerifierSummary as x, type ExecuteOutput as y, type ExecutePromptFn as z };

package/dist/{index-BFuVcqL8.d.cts → index-D3ayz3hy.d.cts}

@@ -1,4 +1,4 @@
-import { a as Node } from './node-fSc-hCv8.cjs';
+import { N as Node } from './node-BYInONRr.cjs';
 
 /**
  * Subscribe to a read-only `Node<T>` as a React value. Re-renders on node value settlement.

package/dist/{index-CQsqqEVz.d.cts → index-D4uimgee.d.cts}

@@ -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-DuHpXSOn.cjs';
+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-MWrQZXCq.cjs';
 
 /**
  * Orchestration patterns (roadmap §4.1).

package/dist/{resilience-BWP2c7Af.d.cts → index-DGTo1yka.d.cts}

@@ -1,4 +1,4 @@
-import { a as Node } from './node-fSc-hCv8.cjs';
+import { N as Node } from './node-BYInONRr.cjs';
 
 /**
  * Backoff strategies for {@link retry} (roadmap §3.1). Delays are in **nanoseconds**.
@@ -153,11 +153,29 @@ declare function withMaxAttempts(strategy: BackoffStrategy, maxAttempts: number)
  */
 declare function resolveBackoffPreset(name: BackoffPreset): BackoffStrategy;
 
+/**
+ * Resilience utilities — roadmap §3.1 + §3.1c (retry, breaker, rate limit, status,
+ * fallback, cache, timeout, budgetGate).
+ */
+
 type RetryOptions = {
-    /** Max retry attempts after each terminal `ERROR` (not counting the first failure). */
+    /**
+     * Max retry attempts after each terminal `ERROR` (not counting the first failure).
+     *
+     * **Required when `backoff` is set.** Pass `Infinity` to opt in to unbounded retries
+     * — the explicit value rules out the silent-infinite-budget footgun (a flaky provider
+     * + exponential backoff + omitted `count` would previously default to ~2.1B retries).
+     */
     count?: number;
     /** Delay between attempts; strategies use **nanoseconds**. */
     backoff?: BackoffStrategy | BackoffPreset;
+    /**
+     * Caller-supplied metadata merged into the produced node's `meta` (Tier 5.2
+     * D8 widening). Use {@link domainMeta} to tag the layer for `describe()`
+     * grouping. The primitive's `factoryTag("retry", …)` always wins against
+     * caller keys.
+     */
+    meta?: Record<string, unknown>;
 };
 /** Factory-mode-only options. `initial` seeds the outer node's cache before the first attempt. */
 type RetryFactoryOptions<T> = RetryOptions & {
@@ -177,12 +195,16 @@ type RetryFactoryOptions<T> = RetryOptions & {
  * same retry pipeline as inner-node ERROR.
  *
  * @param input - Upstream node or factory that returns a fresh node per attempt.
- * @param opts - `count` caps attempts; `backoff` supplies delay in **nanoseconds** (or a preset name); `initial` seeds the outer node cache (factory mode only).
+ * @param opts - `count` caps attempts (**required when `backoff` is set**; pass `Infinity` to opt in to unbounded); `backoff` supplies delay in **nanoseconds** (or a preset name); `initial` seeds the outer node cache (factory mode only).
  * @returns Node that retries on error.
  *
+ * @throws {RangeError} when `backoff` is provided without an explicit `count` (unbounded-retry footgun guard) or when `count < 0`.
+ *
  * @remarks
  * **Protocol:** Forwards unknown message tuples unchanged; handles `DIRTY`, `DATA`, `RESOLVED`, `COMPLETE`, `ERROR`.
  *
+ * **Backoff floor:** every scheduled delay is floored at 1ms via `Math.max(1, delayNs / NS_PER_MS)` even when the strategy returns 0ns. This avoids 0-delay re-entrancy on the active stack frame on a tight ERROR loop. Strategies that return `null`/`undefined` stop retrying immediately and forward the original error.
+ *
  * @example
  * ```ts
  * // Source mode — resubscribe the same node:
@@ -226,7 +248,12 @@ interface CircuitBreakerOptions {
     cooldown?: BackoffStrategy;
     /** Max trial requests allowed in half-open state. Default: 1. */
     halfOpenMax?: number;
-    /** Clock function returning nanoseconds (for testability). Default: `monotonicNs`. */
+    /**
+     * Clock function returning **nanoseconds** with `monotonicNs()` semantics
+     * (monotonically non-decreasing; suitable for elapsed-time arithmetic — never
+     * use `Date.now()` because wall-clock skew can flip elapsed math negative).
+     * Default: `monotonicNs` from `core/clock`. Override for deterministic tests.
+     */
     now?: () => number;
 }
 interface CircuitBreaker {
@@ -236,7 +263,13 @@ interface CircuitBreaker {
     recordSuccess(): void;
     /** Record a failed execution. May transition to open. */
     recordFailure(error?: unknown): void;
-    /** Current circuit state (read-only, does not trigger transitions). */
+    /**
+     * Current circuit state (read-only, does not trigger transitions).
+     *
+     * **Telemetry:** wrap with {@link withBreaker} to surface this as a reactive
+     * `Node<CircuitState>` companion (`bundle.breakerState`) — every state
+     * transition (`closed`/`open`/`half-open`) emits to subscribers.
+     */
     readonly state: CircuitState;
     /** Number of consecutive failures in the current closed period. */
     readonly failureCount: number;
@@ -282,6 +315,8 @@ type WithBreakerBundle<T> = {
  * @remarks
  * **Success path:** `COMPLETE` calls {@link CircuitBreaker.recordSuccess}. **Failure path:** upstream `ERROR` calls {@link CircuitBreaker.recordFailure} and is forwarded.
  *
+ * **State telemetry:** `breakerState: Node<CircuitState>` is a reactive companion that mirrors `breaker.state` — every transition (`closed`/`open`/`half-open`) emits a `DATA`. Also accessible via `node.meta.breakerState` for `describe()` traversal.
+ *
  * @example
  * ```ts
  * import { state, withBreaker, circuitBreaker } from "@graphrefly/graphrefly-ts";
@@ -295,9 +330,17 @@ type WithBreakerBundle<T> = {
  */
 declare function withBreaker<T>(breaker: CircuitBreaker, options?: {
     onOpen?: "skip" | "error";
+    meta?: Record<string, unknown>;
 }): (source: Node<T>) => WithBreakerBundle<T>;
 interface TokenBucket {
-    /** Number of tokens currently available (after refill). */
+    /**
+     * Number of tokens currently available (after refill).
+     *
+     * **Float-valued.** When `refillPerSecond` is fractional (or `capacity` × elapsed-fraction
+     * yields a non-integer), the bucket accumulates fractional refill credit between
+     * `tryConsume`s. Consumers should not assume integer tokens — e.g. with
+     * `tokenBucket(10, 2.5)` after 100ms of elapsed time `available()` may report `0.25`.
+     */
     available(): number;
     /** Try to consume `cost` tokens. Returns `true` if successful. */
     tryConsume(cost?: number): boolean;
@@ -310,35 +353,79 @@ interface TokenBucket {
      */
     putBack(cost?: number): void;
 }
+/** Optional configuration for {@link tokenBucket}. */
+interface TokenBucketOptions {
+    /**
+     * Clock function returning **nanoseconds** with `monotonicNs()` semantics
+     * (monotonically non-decreasing). Default: `monotonicNs` from `core/clock`.
+     * Override for deterministic tests — eliminates the need for `vi.useFakeTimers`
+     * to drive token-refill scheduling.
+     */
+    clock?: () => number;
+}
 /**
  * Token-bucket meter (capacity + refill rate per second). Use with {@link rateLimiter} or custom gates.
  *
  * @param capacity - Maximum tokens (must be positive).
- * @param refillPerSecond - Tokens added per elapsed second (non-negative).
+ * @param refillPerSecond - Tokens added per elapsed second (non-negative; may be fractional).
+ * @param opts - Optional `clock` override for deterministic testing.
  * @returns {@link TokenBucket} instance.
  *
+ * @remarks
+ * **Float behavior:** the internal token counter is float-valued — fractional refill
+ * accumulates between `tryConsume` calls. See {@link TokenBucket.available} for caveats.
+ *
+ * **Clock injection:** pass `opts.clock` to drive refill scheduling deterministically
+ * in tests. The contract matches {@link circuitBreaker}'s `now` option: must return
+ * `monotonicNs()`-style nanoseconds, never `Date.now()` (wall-clock skew breaks
+ * elapsed math).
+ *
  * @example
  * ```ts
  * import { tokenBucket } from "@graphrefly/graphrefly-ts";
  *
  * const bucket = tokenBucket(10, 2); // capacity 10, refill 2 tokens/sec
  * bucket.tryConsume(3); // true — 7 tokens remaining
- * bucket.available();   // ~7 (plus any elapsed refill)
+ * bucket.available();   // ~7 (plus any elapsed refill — float-valued)
+ *
+ * // Deterministic test:
+ * let t = 0;
+ * const tb = tokenBucket(5, 1, { clock: () => t });
+ * tb.tryConsume(5);    // exhausts
+ * t = 1_000_000_000;   // advance 1s → +1 refill
+ * tb.tryConsume(1);    // true
  * ```
  *
  * @category extra
  */
-declare function tokenBucket(capacity: number, refillPerSecond: number): TokenBucket;
+declare function tokenBucket(capacity: number, refillPerSecond: number, opts?: TokenBucketOptions): TokenBucket;
 type RateLimiterOverflowPolicy = "drop-oldest" | "drop-newest" | "error";
 type RateLimiterOptions = {
     /** Maximum `DATA` emissions per window (must be > 0). */
     maxEvents: number;
     /** Window length in nanoseconds (must be > 0). */
     windowNs: number;
-    /** Cap on items queued while waiting for token refill (must be >= 1). Unbounded if omitted. */
-    maxBuffer?: number;
+    /**
+     * Cap on items queued while waiting for token refill.
+     *
+     * **Required.** Pass a finite positive integer (>= 1) for a bounded queue, OR
+     * the literal `Infinity` to opt in to an unbounded queue (caller acknowledges
+     * the unbounded-memory-growth risk on a high-rate source). Omitting this
+     * throws at construction time — the silent-unbounded-buffer footgun is the
+     * most common rateLimiter mis-configuration.
+     */
+    maxBuffer: number;
     /** Overflow policy when `maxBuffer` is exceeded. Default: `"drop-newest"`. */
     onOverflow?: RateLimiterOverflowPolicy;
+    /**
+     * Caller-supplied metadata merged into the produced node's `meta` (Tier 5.2
+     * D8 widening). Use {@link domainMeta} to tag the layer for `describe()` /
+     * mermaid grouping (e.g. `domainMeta("resilient", "rate-limit")`). The
+     * primitive's own `factoryTag("rateLimiter", opts)` and the `droppedCount`
+     * / `rateLimitState` companion seeds always win against caller-supplied
+     * keys so the audit trail can't be silently overwritten.
+     */
+    meta?: Record<string, unknown>;
 };
 /**
  * Thrown by {@link rateLimiter} when `onOverflow: "error"` and the pending buffer is full.
@@ -349,19 +436,78 @@ declare class RateLimiterOverflowError extends Error {
     name: string;
     constructor(maxBuffer: number);
 }
+/**
+ * Combined runtime state surfaced by {@link rateLimiter} alongside `droppedCount`.
+ * Tier 5.2 D7 widening — exposes pending-buffer occupancy and a `paused`
+ * flag so consumers can render backpressure (UI), feed `lens.health`, or
+ * gate downstream effects.
+ */
+type RateLimiterState = {
+    /** Cumulative `DATA` items dropped due to overflow since this subscription cycle started. */
+    droppedCount: number;
+    /** Items currently buffered awaiting a token refill. `0` when the limiter is passing through. */
+    pendingCount: number;
+    /** `true` when at least one item is queued (the limiter is actively throttling). */
+    paused: boolean;
+};
+/** Bundle returned by {@link rateLimiter}. */
+type RateLimiterBundle<T> = {
+    /** The throttled stream — at most `maxEvents` `DATA` per `windowNs`. */
+    node: Node<T>;
+    /**
+     * Reactive companion: count of `DATA` items dropped since the producer
+     * activated.
+     *
+     * - Increments on every drop under any overflow policy (`drop-newest`,
+     *   `drop-oldest`). The `error` policy terminates the stream after a single
+     *   overflow, so `droppedCount` increments at most once in that path.
+     * - **Lifecycle scoping (qa A1 + EC7):** the counter retains its final
+     *   value through terminal (`COMPLETE` / `ERROR` / `TEARDOWN`) so consumers
+     *   see the final drop count, not zero. The closure-held counter resets to
+     *   `0` only when the producer fn re-runs — which only happens on a new
+     *   subscription cycle, and only if the producer was constructed with
+     *   `resubscribable: true`. The default `rateLimiter` producer is NOT
+     *   resubscribable, so a single producer-fn run is the typical lifetime.
+     * - Producer-pattern note: this companion is invisible to `describe()`
+     *   traversal from `node` (effect-mirror limitation; same shape as
+     *   `withBreaker.breakerState` and `withStatus.status`). Surface it via
+     *   `node.meta.droppedCount` if you need it in topology snapshots.
+     */
+    droppedCount: Node<number>;
+    /**
+     * Reactive companion: combined `{droppedCount, pendingCount, paused}` view.
+     *
+     * - `pendingCount` reflects the live buffer occupancy and updates on every
+     *   push / shift / overflow drop; `paused` is shorthand for
+     *   `pendingCount > 0`.
+     * - Equality-deduped — re-emits only when one of the three fields actually
+     *   changes (so a busy steady-state where every DATA passes immediately
+     *   produces one `paused: false` emission, not one per DATA).
+     * - **Lifecycle scoping (qa EC7):** same contract as `droppedCount` —
+     *   retains its final value through terminal; resets to the initial
+     *   `{droppedCount: 0, pendingCount: 0, paused: false}` only on a new
+     *   producer-fn run (resubscribable upstream required).
+     * - Same producer-pattern caveat as `droppedCount` re: `describe()` visibility.
+     */
+    rateLimitState: Node<RateLimiterState>;
+};
 /**
  * Token-bucket rate limiter: at most `maxEvents` `DATA` values per `windowNs`.
  *
  * Uses {@link tokenBucket} internally (capacity = `maxEvents`, refill = `maxEvents / windowSeconds`).
- * Excess items are queued FIFO until a token is available. The queue may be bounded via
- * `maxBuffer` with a configurable overflow policy.
+ * Excess items are queued FIFO (in a fixed-capacity {@link RingBuffer} for O(1) push/shift)
+ * until a token is available. The queue is bounded by the **required** `maxBuffer` option
+ * with a configurable overflow policy.
  *
  * @param source - Upstream node.
- * @param opts - Rate + optional bounded-buffer configuration.
- * @returns Node that emits DATA at most `maxEvents` per `windowNs`.
+ * @param opts - Rate + bounded-buffer configuration. `maxBuffer` is required (use `Infinity` to opt in to unbounded).
+ * @returns `{ node, droppedCount }` bundle. Subscribe to `node` for the throttled stream and to `droppedCount` for backpressure pressure.
+ *
+ * @throws {RangeError} when `maxEvents` / `windowNs` is non-positive, when `maxBuffer` is omitted, or when `maxBuffer` is a finite value < 1.
  *
  * @remarks
- * **Terminal:** `COMPLETE` / `ERROR` cancel the refill timer, drop the pending queue, and propagate.
+ * **Terminal:** `COMPLETE` / `ERROR` cancel the refill timer, drop the pending queue,
+ * reset `droppedCount` to `0`, and propagate.
  *
  * @example
  * ```ts
@@ -369,13 +515,18 @@ declare class RateLimiterOverflowError extends Error {
  *
  * const src = state(0);
  * // Allow at most 5 DATA values per second; queue up to 100 excess items, drop newest beyond.
- * const limited = rateLimiter(src, { maxEvents: 5, windowNs: NS_PER_SEC, maxBuffer: 100 });
+ * const { node: limited, droppedCount } = rateLimiter(src, {
+ *   maxEvents: 5,
+ *   windowNs: NS_PER_SEC,
+ *   maxBuffer: 100,
+ * });
+ * droppedCount.subscribe(([m]) => console.log("dropped so far:", m[1]));
  * ```
  *
  * @category extra
  */
-declare function rateLimiter<T>(source: Node<T>, opts: RateLimiterOptions): Node<T>;
-type StatusValue = "pending" | "active" | "completed" | "errored";
+declare function rateLimiter<T>(source: Node<T>, opts: RateLimiterOptions): RateLimiterBundle<T>;
+type StatusValue = "pending" | "running" | "completed" | "errored";
 type WithStatusBundle<T> = {
     node: Node<T>;
     status: Node<StatusValue>;
@@ -386,10 +537,25 @@ type WithStatusBundle<T> = {
  *
  * @param src - Upstream node to mirror.
  * @param options - `initialStatus` defaults to `"pending"`.
- * @returns `{ node, status, error }` where `error` holds the last `ERROR` payload.
+ * @returns `{ node, status, error }` where `out` is the mirrored stream, `status` is a
+ *   reactive `Node<StatusValue>` (`"pending" | "running" | "completed" | "errored"`),
+ *   and `error` holds the last `ERROR` payload (cleared to `null` on the next `DATA`
+ *   after `errored`).
  *
  * @remarks
- * **Recovery:** After `errored`, the next `DATA` clears `error` and sets `active` inside {@link batch} (matches graphrefly-py).
+ * **Lifecycle:** `pending` (no DATA yet) → `running` (on first DATA) → `completed`
+ * (on COMPLETE) or `errored` (on ERROR). After `errored`, the next `DATA` clears
+ * `error` and re-enters `running` inside a {@link batch} so subscribers see one
+ * consistent transition (matches graphrefly-py).
+ *
+ * **Producer-pattern visibility:** `out` is built via `node([], fn, …)`, so `src`
+ * appears as the source dependency in `describe()` traversal but the `status` /
+ * `error` companions are mirrored via subscribe-callback effects — they appear
+ * under `out.meta.status` / `out.meta.error` (and as `<name>::__meta__::status`
+ * paths in `describe()`) rather than as separate top-level edges. Subscribers
+ * to `out` see the throttled DATA stream; `status` / `error` companions may not
+ * appear as edges in `describe()` if no consumer subscribes to them (per
+ * COMPOSITION-GUIDE §1, push-on-subscribe semantics).
  *
  * @example
  * ```ts
@@ -399,13 +565,14 @@ type WithStatusBundle<T> = {
  * const { node, status, error } = withStatus(src);
  *
  * status.subscribe((msgs) => console.log("status:", msgs));
- * src.down([[DATA, 42]]); // status → "active"
+ * src.down([[DATA, 42]]); // status → "running"
  * ```
  *
  * @category extra
  */
 declare function withStatus<T>(src: Node<T>, options?: {
     initialStatus?: StatusValue;
+    meta?: Record<string, unknown>;
 }): WithStatusBundle<T>;
 /**
  * Thrown by {@link timeout} when no `DATA` arrives within the deadline.
@@ -449,7 +616,9 @@ type FallbackInput<T> = T | Node<T> | PromiseLike<T> | AsyncIterable<T>;
  *
  * @category extra
  */
-declare function fallback<T>(source: Node<T>, fb: FallbackInput<T>): Node<T>;
+declare function fallback<T>(source: Node<T>, fb: FallbackInput<T>, options?: {
+    meta?: Record<string, unknown>;
+}): Node<T>;
 /**
  * Emits `ERROR` with {@link TimeoutError} if no `DATA` arrives within the deadline.
  *
@@ -457,9 +626,14 @@ declare function fallback<T>(source: Node<T>, fb: FallbackInput<T>): Node<T>;
  * the timer. Terminal messages (`COMPLETE`/`ERROR`) cancel the timer.
  *
  * @param source - Upstream node.
- * @param timeoutNs - Deadline in nanoseconds.
+ * @param timeoutNs - Deadline in **nanoseconds** (must be > 0). Internally converted to milliseconds for `setTimeout` scheduling.
  * @returns Node that errors on timeout.
  *
+ * @throws {RangeError} when `timeoutNs <= 0`.
+ *
+ * @remarks
+ * **Scheduling:** internally uses {@link ResettableTimer} (raw `setTimeout`) per spec §5.10's resilience-operator carve-out. The deadline is `timeoutNs / NS_PER_MS` ms; sub-millisecond `timeoutNs` values get the same minimum-1ms host-scheduler granularity that `setTimeout` provides.
+ *
  * @example
  * ```ts
  * import { timeout, never, NS_PER_SEC } from "@graphrefly/graphrefly-ts";
@@ -470,6 +644,8 @@ declare function fallback<T>(source: Node<T>, fb: FallbackInput<T>): Node<T>;
  *
  * @category extra
  */
-declare function timeout<T>(source: Node<T>, timeoutNs: number): Node<T>;
+declare function timeout<T>(source: Node<T>, timeoutNs: number, options?: {
+    meta?: Record<string, unknown>;
+}): Node<T>;
 
-export { type BackoffPreset as B, type CircuitState as C, type ExponentialBackoffOptions as E, type FallbackInput as F, type JitterMode as J, NS_PER_MS as N, type RateLimiterOptions as R, type StatusValue as S, TimeoutError as T, type WithBreakerBundle as W, type CircuitBreakerOptions as a, type RetryOptions as b, NS_PER_SEC as c, type BackoffStrategy as d, type CircuitBreaker as e, CircuitOpenError as f, RateLimiterOverflowError as g, type RateLimiterOverflowPolicy as h, type TokenBucket as i, type WithStatusBundle as j, circuitBreaker as k, constant as l, decorrelatedJitter as m, exponential as n, fallback as o, fibonacci as p, linear as q, rateLimiter as r, resolveBackoffPreset as s, retry as t, timeout as u, tokenBucket as v, withBreaker as w, withMaxAttempts as x, withStatus as y };
+export { type BackoffPreset as B, type CircuitState as C, type ExponentialBackoffOptions as E, type FallbackInput as F, type JitterMode as J, NS_PER_MS as N, type RateLimiterState as R, type StatusValue as S, TimeoutError as T, type WithBreakerBundle as W, type RateLimiterOptions as a, type CircuitBreakerOptions as b, type RetryOptions as c, NS_PER_SEC as d, type BackoffStrategy as e, type CircuitBreaker as f, CircuitOpenError as g, RateLimiterOverflowError as h, type RateLimiterOverflowPolicy as i, type TokenBucket as j, type WithStatusBundle as k, circuitBreaker as l, constant as m, decorrelatedJitter as n, exponential as o, fallback as p, fibonacci as q, linear as r, rateLimiter as s, resolveBackoffPreset as t, retry as u, timeout as v, tokenBucket as w, withBreaker as x, withMaxAttempts as y, withStatus as z };

package/dist/{index-BmWuVdER.d.ts → index-DH4fm2Ck.d.ts}

@@ -1,5 +1,5 @@
-import { G as Graph } from './graph-BjW1taJl.js';
-import { M as MeasurementAdapter } from './reactive-layout-D-tRiNhg.js';
+import { G as Graph } from './graph-BkIkog4h.js';
+import { M as MeasurementAdapter } from './reactive-layout-KJj4E2dT.js';
 
 /**
  * Three-pane demo shell (roadmap §7.2).