@graphrefly/graphrefly 0.38.0 → 0.40.0

package/dist/{resilience-Bys63Cpd.d.ts → index-BAQrjuZF.d.ts}

@@ -1,4 +1,4 @@
-import { a as Node } from './node-fSc-hCv8.js';
+import { N as Node } from './node-BYInONRr.js';
 
 /**
  * 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-BiomL7AW.d.ts → index-BJSZxSFX.d.ts}

@@ -1,5 +1,5 @@
 import { Ref, WatchSource } from 'vue';
-import { a as Node } from './node-fSc-hCv8.js';
+import { N as Node } from './node-BYInONRr.js';
 
 /**
  * Subscribe to a read-only `Node<T>` as a Vue `Ref<T>`. Auto-unsubscribes on scope disposal.

package/dist/index-BQ1fR4li.d.ts

@@ -0,0 +1,210 @@
+import { b as NodeGuard, N as Node } from './node-BYInONRr.js';
+import { G as Graph } from './graph-BkIkog4h.js';
+import { R as ReactiveLogOptions, a as ReactiveLogBundle } from './reactive-log-BlAsPLl2.js';
+
+/**
+ * Audited-mutation framework (Audit 2 — locked 2026-04-24; promoted to
+ * `extra/mutation/` per consolidation plan §1, Tier 2.2).
+ *
+ * Phase-4 primitives share the same shape: imperative mutation methods +
+ * closure state + reactive audit log + freeze-at-entry + rollback-on-throw.
+ * This module factors out the common machinery so each primitive becomes
+ * declarative wiring over typed audit records:
+ *  - `approvalGate`, `pipeline.approvalGate`  (Wave A.2 Unit 8)
+ *  - `JobQueueGraph`                          (Wave B.3 Unit 15)
+ *  - `CqrsGraph.dispatch`                     (Wave C.2 Unit 20)
+ *  - `CqrsGraph.saga`                         (Wave C.3 Unit 22)
+ *  - `processManager`                         (Wave 7)
+ */
+
+/**
+ * Bounded increment for a self-owned counter state node.
+ *
+ * Reads `counter.cache`, bumps by 1 if under `cap`, writes back. Returns
+ * `false` when the cap is reached. Documented P3 exception: the counter is
+ * not a declared dep of the caller — it's a private budget read+written from
+ * a single call site. This helper keeps the `.cache` access in one named
+ * place.
+ *
+ * **Safety today:**
+ *   1. Single-threaded JS runner never invokes the caller concurrently.
+ *   2. `counter.down` writes the cache synchronously before returning, so
+ *      synchronous re-entry through a downstream publish reads the
+ *      freshly-incremented value — no double-count.
+ *
+ * **Future risk:** under a free-threaded runner (PY no-GIL or hypothetical
+ * concurrent TS runner), two concurrent firings could still race. Revisit
+ * when that surfaces.
+ */
+declare function tryIncrementBounded(counter: Node<number>, cap: number): boolean;
+/** Shared base shape for every audit record. Per-primitive types extend this. */
+interface BaseAuditRecord {
+    readonly t_ns: number;
+    readonly seq?: number;
+    readonly handlerVersion?: {
+        id: string;
+        version: string | number;
+    };
+}
+/**
+ * Allow `observe` and `signal`; deny external `write` on the audit log so
+ * consumers can subscribe + signal-bridge but cannot inject fake records.
+ */
+declare const DEFAULT_AUDIT_GUARD: NodeGuard;
+type AuditLogOpts<R extends BaseAuditRecord> = {
+    name: string;
+    /** Bounded retention; default 1024 per Audit 2 / cross-cutting bounded-default policy. */
+    retainedLimit?: number;
+    /** Override the default audit guard. */
+    guard?: NodeGuard;
+    /** Mount the audit `entries` Node under this graph (and activate withLatest). */
+    graph?: Graph;
+    /** Pass-through to {@link reactiveLog}. */
+    versioning?: ReactiveLogOptions<R>["versioning"];
+};
+/**
+ * Build a reactive audit log with sane defaults: bounded retention, deny-write
+ * guard, `withLatest()` companions activated. Returns the {@link ReactiveLogBundle}
+ * directly — primitives expose this as `<primitive>.events` / `.decisions` /
+ * `.dispatches` / `.invocations` and alias it as `.audit`.
+ *
+ * @category internal
+ */
+declare function createAuditLog<R extends BaseAuditRecord>(opts: AuditLogOpts<R>): ReactiveLogBundle<R>;
+type FailureMeta = {
+    t_ns: number;
+    seq?: number;
+    errorType: string;
+};
+type SuccessMeta = {
+    t_ns: number;
+    seq?: number;
+};
+/** Common opts shared by both tiers. */
+type MutationOpts<TArgs extends readonly unknown[], R extends BaseAuditRecord> = {
+    /** Where to emit the audit record on success / failure. */
+    audit: ReactiveLogBundle<R>;
+    /** Build the success record from the action's args + result + meta. */
+    onSuccess?: (args: TArgs, result: unknown, meta: SuccessMeta) => R | undefined;
+    /** Build the failure record from the args + error + meta. */
+    onFailure?: (args: TArgs, error: unknown, meta: FailureMeta) => R | undefined;
+    /** Freeze inputs at entry (default `true`). Pass `false` for hot paths. */
+    freeze?: boolean;
+    /** Optional sequence cursor — auto-advanced and stamped onto records. */
+    seq?: Node<number>;
+    /** Optional handler version — stamped into the record (Audit 5). */
+    handlerVersion?: {
+        id: string;
+        version: string | number;
+    };
+};
+type WrapMutationOpts<TArgs extends readonly unknown[], R extends BaseAuditRecord> = MutationOpts<TArgs, R>;
+type LightMutationOpts<TArgs extends readonly unknown[], R extends BaseAuditRecord> = MutationOpts<TArgs, R>;
+/**
+ * Advance a cursor node and return the new value. Emits `[DIRTY], [DATA, next]`
+ * directly on the cursor — atomic outside a batch, rollback-discardable inside.
+ *
+ * Resets to `0` if the cursor cache is missing, non-numeric, `NaN`, or
+ * non-finite (e.g. corrupted by `restore()` from a malformed snapshot, or
+ * by a misbehaving codec). `??` alone would let `NaN` and `""` pass through
+ * and silently corrupt audit ordering downstream.
+ *
+ * Works whether or not the cursor has any subscribers — `down` updates the
+ * cache regardless, so primitives that bump before consumers attach (e.g.
+ * `JobQueueGraph.enqueue`) still see a coherent sequence.
+ *
+ * @category internal
+ */
+declare function bumpCursor(seq: Node<number>): number;
+/**
+ * Build a record via the supplied builder, stamp `handlerVersion` if present,
+ * and append it to the audit log. `undefined` records are skipped (callers
+ * pass an `onSuccess` / `onFailure` that returns `undefined` to opt out per
+ * call).
+ *
+ * @category internal
+ */
+declare function appendAudit<TArgs extends readonly unknown[], TValue, R extends BaseAuditRecord, M extends SuccessMeta | FailureMeta>(audit: ReactiveLogBundle<R>, builder: (args: TArgs, value: TValue, meta: M) => R | undefined, args: TArgs, value: TValue, meta: M, handlerVersion?: {
+    id: string;
+    version: string | number;
+}): void;
+/**
+ * Substrate-tier wrapper: run `action`, append a typed audit record on
+ * success or failure, advance an optional `seq` cursor. No batch frame — this
+ * is the hot-path-friendly variant for atomic single-write mutations.
+ *
+ * Behavior contract:
+ * 1. Freeze args at entry (default `true`; opt out with `freeze: false` for
+ *    hot paths — e.g. wrapping `vectorIndex.upsert(id, vector[768], meta)`
+ *    where the deep-freeze of a 768-dim vector is a measurable tax).
+ * 2. Bump `seq` (if provided) BEFORE the action runs. There is no batch frame,
+ *    so the bump persists even on throw — the failure-audit record stamps the
+ *    same `seq` so audit consumers see a contiguous sequence.
+ * 3. Run `action(args)`. On success, `appendAudit(onSuccess, ...)`.
+ * 4. On throw, `appendAudit(onFailure, ...)` then re-throw so callers see the
+ *    failure.
+ *
+ * **Distinguish from {@link wrapMutation}:** `wrapMutation` opens a `batch()`
+ * frame (rollback-on-throw, seq advance discarded on rollback) and is the
+ * right choice when the action runs a user-supplied handler or a multi-step
+ * sequence that could leave inconsistent state mid-throw.
+ *
+ * **Cursor / log alignment caveat (substrate-tier):** `seq` is bumped BEFORE
+ * `action()` runs, and the audit-log append happens AFTER. There is no batch
+ * frame, so a synchronous subscriber to `seq` that fires between the two —
+ * including a subscriber on `audit.entries` itself if the substrate causes
+ * it to fire transitively — observes `seq=N` while the corresponding record
+ * is not yet in the log. Audit consumers that join `seq` and `audit.entries`
+ * reactively must tolerate this one-tick lag, or use {@link wrapMutation}
+ * (whose `batch()` frame defers downstream delivery until commit, so cursor
+ * and log appear together to subscribers). The same caveat applies to
+ * **re-entrant** invocation: if an `audit.entries` / `seq` subscriber
+ * triggers another `lightMutation`, the inner record can land on the log
+ * before the outer call's success/failure record.
+ *
+ * @category internal
+ */
+declare function lightMutation<TArgs extends readonly unknown[], TResult, R extends BaseAuditRecord>(action: (...args: TArgs) => TResult, opts: LightMutationOpts<TArgs, R>): (...args: TArgs) => TResult;
+/**
+ * Orchestration-tier wrapper: like {@link lightMutation} but adds a `batch()`
+ * frame around the action so an in-flight throw rolls back partial state.
+ *
+ * Behavior contract:
+ *  1. Freeze args at entry (default `true`).
+ *  2. Open a batch frame (rollback-on-throw via core batch — Audit 2 #6).
+ *  3. Bump `seq` INSIDE the batch so a framework-level rollback discards the
+ *     cursor advance (cursor stays in sync with audit log). M5.
+ *  4. Run `action(args)` and capture result.
+ *  5. On success: `appendAudit(onSuccess, ...)` inside the batch.
+ *  6. On throw: catch OUTSIDE the batch so the failure record emits in a
+ *     fresh transaction after rollback — it persists. Re-throw so callers see
+ *     the failure.
+ *
+ * **Distinguish from the file-private `wrapMutation` in
+ * `src/extra/reactive-map.ts:540`:** that helper is a transactional wrapper
+ * for the reactiveMap version counter (`pre/post-version` snapshot diffing,
+ * read vs. mutation gating). Different concern, file-private, not exported.
+ * This `wrapMutation` is the public Phase-4 audit framework.
+ *
+ * @category internal
+ */
+declare function wrapMutation<TArgs extends readonly unknown[], TResult, R extends BaseAuditRecord>(action: (...args: TArgs) => TResult, opts: WrapMutationOpts<TArgs, R>): (...args: TArgs) => TResult;
+/**
+ * Promote a closure counter to a state node mounted under `graph`.
+ * Replaces ad-hoc `let _seq = 0` patterns with a node observable in
+ * `describe()` and persistable via storage tiers.
+ *
+ * @category internal
+ */
+declare function registerCursor(graph: Graph, name: string, initial?: number): Node<number>;
+/**
+ * Promote a closure `Map<K, number>` to N state nodes (one per key) mounted
+ * under `<graph>::<name>::<key>`. Used by saga (per-event-type cursor).
+ *
+ * @category internal
+ */
+declare function registerCursorMap<K extends string>(graph: Graph, name: string, keys: readonly K[], initial?: number): {
+    readonly [P in K]: Node<number>;
+};
+
+export { type AuditLogOpts as A, type BaseAuditRecord as B, DEFAULT_AUDIT_GUARD as D, type FailureMeta as F, type LightMutationOpts as L, type MutationOpts as M, type SuccessMeta as S, type WrapMutationOpts as W, appendAudit as a, bumpCursor as b, createAuditLog as c, registerCursorMap as d, lightMutation as l, registerCursor as r, tryIncrementBounded as t, wrapMutation as w };

package/dist/{index-D7-RSD93.d.cts → index-BTHOTC0Q.d.cts}

@@ -1,9 +1,9 @@
-import { a as Node } from './node-fSc-hCv8.cjs';
-import { R as ReactiveLogBundle } from './reactive-log-C3IMAGpT.cjs';
+import { N as Node } from './node-BYInONRr.cjs';
+import { B as BaseAuditRecord } from './index-DVDapw2k.cjs';
+import { a as ReactiveLogBundle } from './reactive-log-_zeEnB9H.cjs';
 import { NodeInput } from './extra/sources.cjs';
 import { AppendLogStorageTier } from './extra/storage-tiers.cjs';
-import { G as Graph, a as GraphOptions } from './graph-CHsVwf9S.cjs';
-import { B as BaseAuditRecord } from './imperative-audit-ahAE65a9.cjs';
+import { G as Graph, a as GraphOptions } from './graph-E6likq7w.cjs';
 
 /**
  * Job queue patterns (roadmap §4.2).