@graphrefly/graphrefly 0.43.0 → 0.45.0

package/dist/index-CQG3D1cp.d.ts

@@ -1,468 +0,0 @@
-import { N as Node } from './node-ClS5yC-B.js';
-import { B as BaseAuditRecord } from './index-CZQXo5tH.js';
-import { a as ReactiveLogBundle } from './reactive-log-BezYsbA_.js';
-import { AppendLogStorageTier } from './extra/storage-tiers.js';
-import { a as GraphOptions, G as Graph } from './graph-7VguS7a4.js';
-
-/**
- * CQRS patterns (roadmap §4.5).
- *
- * Composition layer over reactiveLog (3.2), pipeline/sagas (4.1), event bus (4.2),
- * projections (4.3). Guards (1.5) enforce command/query boundary.
- *
- * - `cqrs(name, opts?)` → `CqrsGraph` — top-level factory
- * - `CqrsGraph.command(name, handler)` — write-only node; guard rejects `observe`
- * - `CqrsGraph.event(name)` — backed by `reactiveLog`; append-only
- * - `CqrsGraph.projection(name, events, reducer, initial)` — read-only derived; guard rejects `write`
- * - `CqrsGraph.saga(name, events, handler)` — event-driven side effects
- */
-
-/**
- * Immutable envelope for events emitted by command handlers.
- *
- * **Wave C.1 Unit 17 (locked 2026-04-24):** Extended ES standard fields —
- * `aggregateId` / `aggregateVersion` for per-aggregate streams; correlation /
- * causation IDs for distributed tracing; `metadata` for free-form context.
- * Optional `handlerVersion` (Audit 5) traces which handler version produced
- * the event.
- *
- * `seq` is a per-graph monotonic counter that provides stable ordering when
- * multiple events share the same `timestampNs` (same wall-clock tick).
- */
-type CqrsEvent<T = unknown> = {
-    type: string;
-    payload: T;
-    /** Wall-clock nanoseconds (via `wallClockNs()`). */
-    timestampNs: number;
-    /** Monotonic sequence within this CqrsGraph instance. */
-    seq: number;
-    /** Aggregate identifier (per-aggregate streams). */
-    aggregateId?: string;
-    /** Per-aggregate monotonic version (set when `aggregateId` is provided). */
-    aggregateVersion?: number;
-    /** Distributed-trace correlation id. */
-    correlationId?: string;
-    /** Causation chain id (this event was caused by event `causationId`). */
-    causationId?: string;
-    /** Free-form metadata frozen at append. */
-    metadata?: Readonly<Record<string, unknown>>;
-    /** V0 identity of the event log node at append time (§6.0b). */
-    v0?: {
-        id: string;
-        version: number;
-    };
-    /** Handler version stamped on emit (Audit 5). */
-    handlerVersion?: {
-        id: string;
-        version: string | number;
-    };
-};
-/** Compile-time event-map registry: `{ "orderPlaced": OrderPayload, ... }`. */
-type CqrsEventMap = Record<string, unknown>;
-/** Recommended `keyOf` for CQRS event-store storage tiers (Audit 4). */
-declare const cqrsEventKeyOf: (e: CqrsEvent) => string;
-interface DispatchRecord<T = unknown> extends BaseAuditRecord {
-    readonly commandName: string;
-    readonly payload: T;
-    /** Action result. Tier 1.6.2 canonical enum (renamed from `status`). */
-    readonly outcome: "success" | "failure";
-    readonly error?: unknown;
-    readonly errorType?: string;
-    /**
-     * Event names emitted by the handler.
-     * - `outcome: "success"`: events that persisted in the event log.
-     * - `outcome: "failure"`: events the handler ATTEMPTED to emit before throwing;
-     *   they were rolled back and did NOT persist. Documents the failed attempt's
-     *   intentions for debugging handler logic. The actual event log shows only
-     *   what's durable.
-     */
-    readonly emittedEvents?: readonly string[];
-}
-declare const dispatchKeyOf: <T>(r: DispatchRecord<T>) => string;
-interface SagaInvocation<T = unknown> extends BaseAuditRecord {
-    readonly eventType: string;
-    /** Action result. Tier 1.6.2 canonical enum (renamed from `status`). */
-    readonly outcome: "success" | "failure";
-    readonly error?: unknown;
-    readonly errorType?: string;
-    readonly aggregateId?: string;
-    readonly event?: CqrsEvent<T>;
-}
-declare const sagaInvocationKeyOf: <T>(i: SagaInvocation<T>) => string;
-/**
- * Saga registration result (M10) — a typed bundle replacing the prior
- * `Node<unknown>` return that side-attached `_saga` via an unsafe cast.
- *
- * `node` is the saga's effect node (subscribe to observe processing
- * activity). `invocations` is the per-event-type audit log; `audit` aliases
- * `invocations` (Audit 2 `.audit` duplication). `cursors` exposes the
- * per-event-type cursor state nodes for monitoring / testing.
- *
- * @category patterns
- */
-interface SagaController<T = unknown> {
-    readonly node: Node<unknown>;
-    readonly invocations: ReactiveLogBundle<SagaInvocation<T>>;
-    readonly audit: ReactiveLogBundle<SagaInvocation<T>>;
-    readonly cursors: {
-        readonly [eventName: string]: Node<number>;
-    };
-}
-type CommandActions = {
-    /** Append an event to a named event log (bypasses event guard). */
-    emit: (eventName: string, payload: unknown) => void;
-};
-/**
- * Command handler receives the dispatch payload and actions to emit events.
- *
- * **Purity:** Handlers should not mutate the payload. Event emission via
- * `actions.emit()` is the only sanctioned side effect.
- */
-type CommandHandler<T = unknown> = (payload: T, actions: CommandActions) => void;
-/**
- * Projection reducer folds events into a read model.
- *
- * **Purity contract:** Reducers MUST be pure — return a new state value
- * without mutating `state` or any event.
- *
- * - In **`"replay"`** mode the `state` parameter is always the original
- *   `initial` value (full event-sourcing replay on every recompute).
- * - In **`"scan"`** mode the `state` parameter is the _previous_ output
- *   (incremental fold); `events` contains only the events appended since
- *   the last computation.
- */
-type ProjectionReducer<TState = unknown, TEvent = unknown> = (state: TState, events: readonly CqrsEvent<TEvent>[]) => TState;
-/**
- * Snapshot integration for {@link ProjectionOptions}.
- *
- * `load` is called once at projection construction and the returned value
- * seeds the initial state. `save` (optional) is called after each reducer
- * run, debounced by `saveDebounceMs` (default 1000 ms) and capped by
- * `saveEvery` (default 1000 events).
- */
-type ProjectionSnapshotOpts<TState> = {
-    /** Load a previously-saved state. `undefined` → start from `initial`. */
-    load: () => TState | undefined | Promise<TState | undefined>;
-    /** Persist the current state. Called after reducer; may be async. */
-    save?: (state: TState) => void | Promise<void>;
-    /**
-     * Debounce window (ms) before `save` fires after the last event. Default 1000.
-     */
-    saveDebounceMs?: number;
-    /**
-     * Force a save after every Nth state change regardless of debounce.
-     * Default 1000. Both knobs compose: save fires at whichever condition is
-     * met first.
-     */
-    saveEvery?: number;
-};
-/**
- * Options for {@link CqrsGraph.projection}.
- *
- * **Wave C.3 Unit 21 (locked 2026-04-24):**
- * - `mode: "scan"` (default) — incremental fold; `"replay"` — full replay
- *   each wave.
- * - `snapshot` — load/save integration for cold-start + auto-checkpoint.
- * - `freezeInputs` (default `true`) — freeze event arrays before passing
- *   to reducer (purity enforcement).
- * - `rebuild()` / `reset()` on the returned {@link ProjectionController}.
- *
- * @category patterns
- */
-type ProjectionOptions<TState> = {
-    name: string;
-    events: readonly string[];
-    reducer: ProjectionReducer<TState>;
-    initial: TState;
-    /**
-     * Fold strategy. Default `"scan"` (incremental). `"replay"` = full replay.
-     *
-     * **Scan-mode ordering caveat:** scan-mode assumes monotonic per-stream
-     * arrival order. When multiple event streams are merged for a projection,
-     * events arriving with a `timestampNs` earlier than the current sort cursor
-     * are skipped from the incremental sweep. This is an acceptable trade-off
-     * for incremental fold; use `mode: "replay"` for strict cross-stream
-     * ordering.
-     */
-    mode?: "replay" | "scan";
-    /** Snapshot integration for rebuild + auto-checkpoint. */
-    snapshot?: ProjectionSnapshotOpts<TState>;
-    /**
-     * Freeze event arrays before passing to reducer (default `true`).
-     * Set to `false` only if your reducer intentionally mutates the input
-     * (strongly discouraged — prefer immutable reducers).
-     */
-    freezeInputs?: boolean;
-};
-/**
- * Controller returned by {@link CqrsGraph.projection}.
- *
- * `node` is the reactive read model. `rebuild()` performs a paginated
- * cold-storage replay (requires `attachEventStorage` tiers). `reset()`
- * reloads from `snapshot.load()` and re-folds the live event log on top.
- *
- * @category patterns
- */
-interface ProjectionController<TState> {
-    readonly node: Node<TState>;
-    /**
-     * Async paginated rebuild from attached storage tiers. Throws
-     * {@link RebuildError} on adapter / decode / reducer failure.
-     *
-     * @param opts.fromTier - Storage tier to read from (default: first attached).
-     * @param opts.pageSize - Entries per page (default 1000).
-     */
-    rebuild(opts?: {
-        fromTier?: AppendLogStorageTier<CqrsEvent>;
-        pageSize?: number;
-    }): Promise<TState>;
-    /**
-     * Reload from `snapshot.load()` (if configured) and re-fold the live
-     * in-memory event log on top. Returns the rebuilt state. No-op on the
-     * reactive node if the state is unchanged.
-     */
-    reset(): Promise<TState>;
-}
-type SagaHandler<T = unknown> = (event: CqrsEvent<T>) => void;
-type CqrsOptions = {
-    graph?: GraphOptions;
-    /** Bounded retention for event streams; default 1024 (cross-cutting). */
-    retainedLimit?: number;
-    /** Freeze command payloads on dispatch (default `true`). */
-    freezeCommandPayload?: boolean;
-    /** Freeze event payloads on emit (default `true`). */
-    freezeEventPayload?: boolean;
-    /** LRU eviction threshold for per-aggregate streams (default 10_000). */
-    maxAggregates?: number;
-};
-type CommandRegistration<TPayload = unknown> = {
-    handler: CommandHandler<TPayload>;
-    emits?: readonly string[];
-    handlerVersion?: {
-        id: string;
-        version: string | number;
-    };
-};
-type DispatchOptions = {
-    correlationId?: string;
-    causationId?: string;
-    metadata?: Record<string, unknown>;
-    /**
-     * Optimistic-concurrency check: if set, dispatch verifies the aggregate
-     * (identified by `aggregateId`) is at this version. On mismatch, dispatch
-     * throws {@link OptimisticConcurrencyError} BEFORE the handler runs.
-     *
-     * Requires `aggregateId` to be set. Without it the check is a no-op.
-     */
-    expectedAggregateVersion?: number;
-    /**
-     * Aggregate this dispatch targets. Events emitted by the handler that
-     * also carry this `aggregateId` participate in per-aggregate versioning
-     * and LRU eviction (see {@link CqrsOptions.maxAggregates}). Events whose
-     * handler-supplied `aggregateId` differs from the dispatch's `aggregateId`
-     * are emitted untouched (their own `aggregateVersion` is computed from
-     * their own aggregate's stream).
-     */
-    aggregateId?: string;
-};
-type SagaOptions = {
-    aggregateId?: string;
-    errorPolicy?: "advance" | "hold";
-    handlerVersion?: {
-        id: string;
-        version: string | number;
-    };
-};
-/**
- * Eviction record emitted on `aggregateEvictions` when an aggregate's
- * per-aggregate stream is removed under `maxAggregates` LRU pressure. The
- * eviction does NOT delete events from the fan-in stream — only the
- * per-aggregate dedicated stream and its version counter.
- */
-interface AggregateEvictionRecord {
-    readonly aggregateId: string;
-    readonly type: string;
-    readonly t_ns: number;
-    /** The version count the aggregate reached before eviction (for diagnostics). */
-    readonly lastVersion: number;
-}
-declare class CqrsGraph<EM extends CqrsEventMap = Record<string, unknown>> extends Graph {
-    /** Fan-in event streams (one per type, all aggregates merged). */
-    private readonly _eventLogs;
-    /**
-     * Per-aggregate event streams: type → aggregateId → entry. Used for
-     * `event(type, aggregateId)` dual-form access and per-aggregate version
-     * tracking. Only populated when an event with `aggregateId` is emitted.
-     */
-    private readonly _eventLogsByAggregate;
-    /** Per-aggregate version counters: `${type}::${aggregateId}` → current version. */
-    private readonly _aggregateVersions;
-    /**
-     * LRU access order for `${type}::${aggregateId}`. Map insertion order
-     * tracks recency — `delete` + `set` on access moves to the end.
-     */
-    private readonly _aggregateLru;
-    private readonly _commandRegs;
-    private readonly _projections;
-    private readonly _sagas;
-    private readonly _keepaliveDisposers;
-    private _seq;
-    private readonly _retainedLimit;
-    private readonly _freezeCommandPayload;
-    private readonly _freezeEventPayload;
-    private readonly _maxAggregates;
-    private readonly _dispatchSeqCursor;
-    /** Audit log of every command dispatch (Audit 2). */
-    readonly dispatches: ReactiveLogBundle<DispatchRecord>;
-    /** Alias for {@link CqrsGraph.dispatches} (Audit 2 `.audit` duplication). */
-    readonly audit: ReactiveLogBundle<DispatchRecord>;
-    /** Per-aggregate LRU eviction observability; secondary log to `dispatches`. */
-    readonly aggregateEvictions: ReactiveLogBundle<AggregateEvictionRecord>;
-    constructor(name: string, opts?: CqrsOptions);
-    /**
-     * Read the current per-aggregate version (last emitted `aggregateVersion`
-     * for that `(type, aggregateId)` pair). Returns `0` if no events have been
-     * emitted yet for this aggregate. Useful for callers preparing
-     * {@link DispatchOptions.expectedAggregateVersion}.
-     */
-    aggregateVersion(type: string, aggregateId: string): number;
-    /** LRU touch — moves the key to the end of the access order. */
-    private _touchAggregate;
-    /**
-     * Evict the oldest aggregate streams (least-recently-touched) until the
-     * aggregate count is back within `_maxAggregates`. Emits one
-     * `AggregateEvictionRecord` per eviction. The fan-in stream is NOT touched
-     * — events stay in the type-level log; only the per-aggregate stream and
-     * version counter are removed.
-     */
-    private _enforceAggregateLru;
-    destroy(): void;
-    /** Tiers attached via {@link attachEventStorage}; auto-wired into future event streams. */
-    private readonly _attachedEventTiers;
-    private readonly _attachedTierDisposers;
-    /**
-     * Wire append-log storage tiers for ALL CQRS event streams — both currently
-     * registered AND any future streams created via `event(name)` /
-     * `event(name, aggregateId)` / handler emit. (M4 fix.)
-     *
-     * Returns a disposer that releases all storage subscriptions wired by this
-     * call (including those for streams that were created after the call).
-     */
-    attachEventStorage(tiers: readonly AppendLogStorageTier<CqrsEvent>[]): () => void;
-    /** Wire newly-created event stream into all currently-attached tier sets. */
-    private _autoWireStreamStorage;
-    /**
-     * Register a named event stream backed by `reactiveLog`.
-     * Guard denies external `write` — only commands append internally.
-     */
-    event(name: string): Node<readonly CqrsEvent[]>;
-    event(name: string, aggregateId: string): Node<readonly CqrsEvent[]>;
-    /**
-     * Get-or-create the per-aggregate event stream for `(type, aggregateId)`.
-     * Mounts the stream as a sibling node named `<type>_<aggregateId>` so it
-     * appears in `describe()`. LRU access is touched on every call.
-     */
-    private _ensureAggregateStream;
-    /** Try `resolve(path)`; return `undefined` instead of throwing on missing. */
-    private resolveOptional;
-    /** Internal: append to an event log, auto-registering if needed. */
-    private _appendEvent;
-    /**
-     * Register a command with its handler. Guard denies `observe` (write-only).
-     * Use `dispatch(name, payload)` to execute.
-     *
-     * The command node carries dynamic `meta.error` — a reactive companion
-     * that holds the last handler error (or `null` on success).
-     */
-    command<T = unknown>(name: string, handlerOrReg: CommandHandler<T> | CommandRegistration<T>): Node<T>;
-    /**
-     * Execute a registered command. Wraps the entire dispatch in `batch()` so
-     * the command node DATA and all emitted events settle atomically.
-     *
-     * If the handler throws, `meta.error` on the command node is set to the
-     * error and the exception is re-thrown.
-     *
-     * **Tier 8 / COMPOSITION-GUIDE §35:** dispatch routes through the shared
-     * {@link wrapMutation} framework so freeze / rollback-on-throw / seq-cursor
-     * advance / audit-record stamping flow through one centralized helper.
-     * Failure records emit OUTSIDE the rolled-back batch (M5 / C4 invariants
-     * preserved by the framework).
-     */
-    dispatch<T = unknown>(commandName: string, payload: T, opts?: DispatchOptions): void;
-    /**
-     * Register a read-only projection derived from event streams.
-     * Guard denies `write` — value is computed from events only.
-     *
-     * **Wave C.3 Unit 21 (locked 2026-04-24):**
-     * - Object-bag signature replaces the positional `(name, events, reducer, initial)` form.
-     * - `mode: "scan"` (default) — incremental fold; `"replay"` — full replay each wave.
-     * - `snapshot` integration for cold-start load + auto-checkpoint save.
-     * - `freezeInputs` (default `true`) — freeze the event array before passing to reducer.
-     * - Returns `ProjectionController<TState>` with `.node`, `.rebuild()`, `.reset()`.
-     *
-     * Fan-in across `events` is implemented by depending on all event-type fan-in
-     * nodes directly, which preserves `describe()` edges (e.g. `orderPlaced →
-     * orderCount`). Events are sorted by `(timestampNs, seq, aggregateId)` before
-     * passing to the reducer (Option-3 cross-aggregate ordering, C.3).
-     */
-    projection<TState>(opts: ProjectionOptions<TState>): ProjectionController<TState>;
-    /**
-     * Register an event-driven side effect. Runs handler for each **new** event
-     * from the specified streams (tracks last-processed entry count per stream).
-     *
-     * The saga node carries dynamic `meta.error` — a reactive companion that
-     * holds the last handler error (or `null` on success). Handler errors do
-     * not propagate out of the saga run (the event cursor still advances so
-     * the same entry is not delivered twice).
-     */
-    saga<T = unknown>(name: string, eventNames: readonly string[], handler: SagaHandler<T>, opts?: SagaOptions): SagaController<T>;
-}
-/**
- * Create a CQRS graph container.
- *
- * @example
- * ```ts
- * const app = cqrs("orders");
- * app.event("orderPlaced");
- * app.command("placeOrder", (payload, { emit }) => {
- *   emit("orderPlaced", { orderId: payload.id, amount: payload.amount });
- * });
- * const { node: orderCount } = app.projection({
- *   name: "orderCount",
- *   events: ["orderPlaced"],
- *   reducer: (_s, events) => events.length,
- *   initial: 0,
- * });
- * app.dispatch("placeOrder", { id: "1", amount: 100 });
- * ```
- */
-declare function cqrs<EM extends CqrsEventMap = Record<string, unknown>>(name: string, opts?: CqrsOptions): CqrsGraph<EM>;
-
-type index_AggregateEvictionRecord = AggregateEvictionRecord;
-type index_CommandActions = CommandActions;
-type index_CommandHandler<T = unknown> = CommandHandler<T>;
-type index_CommandRegistration<TPayload = unknown> = CommandRegistration<TPayload>;
-type index_CqrsEvent<T = unknown> = CqrsEvent<T>;
-type index_CqrsEventMap = CqrsEventMap;
-type index_CqrsGraph<EM extends CqrsEventMap = Record<string, unknown>> = CqrsGraph<EM>;
-declare const index_CqrsGraph: typeof CqrsGraph;
-type index_CqrsOptions = CqrsOptions;
-type index_DispatchOptions = DispatchOptions;
-type index_DispatchRecord<T = unknown> = DispatchRecord<T>;
-type index_ProjectionController<TState> = ProjectionController<TState>;
-type index_ProjectionOptions<TState> = ProjectionOptions<TState>;
-type index_ProjectionReducer<TState = unknown, TEvent = unknown> = ProjectionReducer<TState, TEvent>;
-type index_ProjectionSnapshotOpts<TState> = ProjectionSnapshotOpts<TState>;
-type index_SagaController<T = unknown> = SagaController<T>;
-type index_SagaHandler<T = unknown> = SagaHandler<T>;
-type index_SagaInvocation<T = unknown> = SagaInvocation<T>;
-type index_SagaOptions = SagaOptions;
-declare const index_cqrs: typeof cqrs;
-declare const index_cqrsEventKeyOf: typeof cqrsEventKeyOf;
-declare const index_dispatchKeyOf: typeof dispatchKeyOf;
-declare const index_sagaInvocationKeyOf: typeof sagaInvocationKeyOf;
-declare namespace index {
-  export { type index_AggregateEvictionRecord as AggregateEvictionRecord, type index_CommandActions as CommandActions, type index_CommandHandler as CommandHandler, type index_CommandRegistration as CommandRegistration, type index_CqrsEvent as CqrsEvent, type index_CqrsEventMap as CqrsEventMap, index_CqrsGraph as CqrsGraph, type index_CqrsOptions as CqrsOptions, type index_DispatchOptions as DispatchOptions, type index_DispatchRecord as DispatchRecord, type index_ProjectionController as ProjectionController, type index_ProjectionOptions as ProjectionOptions, type index_ProjectionReducer as ProjectionReducer, type index_ProjectionSnapshotOpts as ProjectionSnapshotOpts, type index_SagaController as SagaController, type index_SagaHandler as SagaHandler, type index_SagaInvocation as SagaInvocation, type index_SagaOptions as SagaOptions, index_cqrs as cqrs, index_cqrsEventKeyOf as cqrsEventKeyOf, index_dispatchKeyOf as dispatchKeyOf, index_sagaInvocationKeyOf as sagaInvocationKeyOf };
-}
-
-export { type AggregateEvictionRecord as A, type CqrsEventMap as C, type DispatchOptions as D, type ProjectionController as P, type SagaController as S, type CqrsEvent as a, CqrsGraph as b, type CqrsOptions as c, type CommandActions as d, type CommandHandler as e, type CommandRegistration as f, type DispatchRecord as g, type ProjectionOptions as h, index as i, type ProjectionReducer as j, type ProjectionSnapshotOpts as k, type SagaHandler as l, type SagaInvocation as m, type SagaOptions as n, cqrs as o, cqrsEventKeyOf as p, dispatchKeyOf as q, sagaInvocationKeyOf as s };

package/dist/index-CZQXo5tH.d.ts

@@ -1,209 +0,0 @@
-import { b as NodeGuard, N as Node } from './node-ClS5yC-B.js';
-import { G as Graph } from './graph-7VguS7a4.js';
-import { R as ReactiveLogOptions, a as ReactiveLogBundle } from './reactive-log-BezYsbA_.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[], TResult, R extends BaseAuditRecord> = {
-    /**
-     * Optional audit log. When omitted, the wrapper still provides freeze /
-     * seq-advance / rollback-on-throw (`wrapMutation`) but skips audit-record
-     * emission entirely — useful for primitives that want centralized mutation
-     * semantics without a dedicated audit log surface (e.g. `Topic.publish`).
-     * Pair with `onSuccess` / `onFailure` to emit records.
-     */
-    audit?: ReactiveLogBundle<R>;
-    /** Build the success record from the action's args + result + meta. */
-    onSuccess?: (args: TArgs, result: TResult, 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[], TResult, R extends BaseAuditRecord> = MutationOpts<TArgs, TResult, R>;
-type LightMutationOpts<TArgs extends readonly unknown[], TResult, R extends BaseAuditRecord> = MutationOpts<TArgs, TResult, R>;
-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`, optionally 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, if `audit` is provided AND `onSuccess`
- *    is set, `appendAudit(onSuccess, ...)`.
- * 4. On throw, if `audit` is provided AND `onFailure` is set,
- *    `appendAudit(onFailure, ...)` then re-throw. When `audit` is omitted the
- *    wrapper still provides freeze + seq + re-throw semantics — useful for
- *    primitives that want centralized mutation contracts without an audit log
- *    surface (e.g. `Topic.publish`).
- *
- * **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, TResult, 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: if `audit` is provided AND `onSuccess` is set,
- *     `appendAudit(onSuccess, ...)` inside the batch.
- *  6. On throw: catch OUTSIDE the batch so the failure record (if any) emits
- *     in a fresh transaction after rollback — it persists. Re-throw so callers
- *     see the failure. When `audit` is omitted the wrapper still provides
- *     batch + freeze + rollback + re-throw semantics — useful for primitives
- *     that want orchestration-tier mutation contracts without an audit log
- *     surface.
- *
- * **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, TResult, 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 };