@graphrefly/graphrefly 0.45.0 → 0.47.0

package/dist/base/mutation/index.d.cts

@@ -0,0 +1,177 @@
+import { NodeGuard, Node } from '@graphrefly/pure-ts/core';
+import { ReactiveLogOptions, ReactiveLogBundle } from '@graphrefly/pure-ts/extra';
+import { Graph } from '@graphrefly/pure-ts/graph';
+
+/**
+ * Universal mutation framework (Phase 14 — DS-14 locked 2026-05-05).
+ *
+ * Single `mutate(act, opts)` factory replaces the prior `lightMutation` +
+ * `wrapMutation` two-tier split (pre-1.0 break per Q-O2).
+ *
+ * Two frames:
+ * - `"inline"` — no batch; up() runs raw. Seq bumps before action; persists
+ *   on throw. Hot-path-friendly for atomic single-write mutations.
+ * - `"transactional"` — opens `batch(() => up(...))`. On throw: batch discards
+ *   deferred deliveries, then `down()` runs (if provided), then failure record.
+ *
+ * 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.
+ */
+
+/**
+ * Bounded increment for a self-owned counter state node.
+ *
+ * Reads `counter.cache`, bumps by `by` (default 1) if `cur + by <= cap`,
+ * writes back. Returns `false` when the cap would be exceeded (no-op write).
+ * 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 so caller bodies (which may
+ * be inside reactive fn execution paths) stay free of cross-node `.cache`
+ * reads.
+ *
+ * **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.
+ *
+ * @param counter - Self-owned counter Node. Caller is the sole writer.
+ * @param cap - Upper bound (inclusive). Pass `Number.MAX_SAFE_INTEGER` for
+ *              "effectively unbounded" use cases (e.g. token meters).
+ * @param by - Delta to add (default `1`). Must be a finite non-negative
+ *             number; callers should pre-validate. Overflow-safe via
+ *             `by > cap - cur` check rather than `cur + by >= cap`.
+ */
+declare function tryIncrementBounded(counter: Node<number>, cap: number, by?: 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;
+};
+/**
+ * Mutation action shape. Plain function shorthand auto-wraps as `{ up: fn }`.
+ *
+ * - `up` — the mutation action (the "up migration").
+ * - `down` — optional rollback for closure mutations that `batch()` can't
+ *   reach. Receives the SAME frozen args as `up`. Runs AFTER batch reactive
+ *   rollback, BEFORE the failure record. Throws inside `down` are
+ *   console.error'd without masking the original error. Only meaningful
+ *   with `frame: "transactional"`.
+ */
+type MutationAct<TArgs extends readonly unknown[], TResult> = {
+    up: (...args: TArgs) => TResult;
+    down?: (...args: TArgs) => void;
+};
+type MutationFrame = "inline" | "transactional";
+type MutateOpts<TArgs extends readonly unknown[], TResult, R extends BaseAuditRecord> = {
+    /** Frame mode. `"inline"` = no batch; `"transactional"` = batch + rollback. */
+    frame: MutationFrame;
+    /**
+     * Optional log to append records to. When omitted, the wrapper still
+     * provides freeze / seq-advance / rollback-on-throw but skips record
+     * emission — useful for primitives that want centralized mutation
+     * semantics without a dedicated log surface (e.g. `Topic.publish`).
+     */
+    log?: ReactiveLogBundle<R>;
+    /** Build the success record from the action's args + result + meta. */
+    onSuccessRecord?: (args: TArgs, result: TResult, meta: SuccessMeta) => R | undefined;
+    /** Build the failure record from the args + error + meta. */
+    onFailureRecord?: (args: TArgs, error: unknown, meta: FailureMeta) => R | undefined;
+    /** Deep-freeze args at entry (default `true`). Opt out for hot paths. */
+    freeze?: boolean;
+    /** Optional sequence cursor — auto-advanced and stamped onto records. */
+    seq?: Node<number>;
+    /** Optional handler version — stamped per Audit 5. */
+    handlerVersion?: {
+        id: string;
+        version: string | number;
+    };
+};
+/**
+ * Universal mutation factory (Phase 14 — DS-14 Q-O2).
+ *
+ * Replaces the prior `lightMutation` + `wrapMutation` two-tier split.
+ * Single factory with `frame: "inline" | "transactional"` discriminant.
+ *
+ * @param act - The mutation action. Either a plain function (auto-wrapped as
+ *   `{ up: fn }`) or a `{ up, down? }` object for explicit rollback.
+ * @param opts - Configuration: frame, log, record builders, freeze, seq.
+ * @returns A typed wrapper function with the same signature as `act.up`.
+ */
+declare function mutate<TArgs extends readonly unknown[], TResult, R extends BaseAuditRecord>(act: MutationAct<TArgs, TResult> | ((...args: TArgs) => TResult), opts: MutateOpts<TArgs, TResult, R>): (...args: TArgs) => TResult;
+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;
+/**
+ * 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, type BaseAuditRecord, DEFAULT_AUDIT_GUARD, type FailureMeta, type MutateOpts, type MutationAct, type MutationFrame, type SuccessMeta, appendAudit, bumpCursor, createAuditLog, mutate, registerCursor, registerCursorMap, tryIncrementBounded };

package/dist/base/mutation/index.d.ts

@@ -0,0 +1,177 @@
+import { NodeGuard, Node } from '@graphrefly/pure-ts/core';
+import { ReactiveLogOptions, ReactiveLogBundle } from '@graphrefly/pure-ts/extra';
+import { Graph } from '@graphrefly/pure-ts/graph';
+
+/**
+ * Universal mutation framework (Phase 14 — DS-14 locked 2026-05-05).
+ *
+ * Single `mutate(act, opts)` factory replaces the prior `lightMutation` +
+ * `wrapMutation` two-tier split (pre-1.0 break per Q-O2).
+ *
+ * Two frames:
+ * - `"inline"` — no batch; up() runs raw. Seq bumps before action; persists
+ *   on throw. Hot-path-friendly for atomic single-write mutations.
+ * - `"transactional"` — opens `batch(() => up(...))`. On throw: batch discards
+ *   deferred deliveries, then `down()` runs (if provided), then failure record.
+ *
+ * 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.
+ */
+
+/**
+ * Bounded increment for a self-owned counter state node.
+ *
+ * Reads `counter.cache`, bumps by `by` (default 1) if `cur + by <= cap`,
+ * writes back. Returns `false` when the cap would be exceeded (no-op write).
+ * 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 so caller bodies (which may
+ * be inside reactive fn execution paths) stay free of cross-node `.cache`
+ * reads.
+ *
+ * **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.
+ *
+ * @param counter - Self-owned counter Node. Caller is the sole writer.
+ * @param cap - Upper bound (inclusive). Pass `Number.MAX_SAFE_INTEGER` for
+ *              "effectively unbounded" use cases (e.g. token meters).
+ * @param by - Delta to add (default `1`). Must be a finite non-negative
+ *             number; callers should pre-validate. Overflow-safe via
+ *             `by > cap - cur` check rather than `cur + by >= cap`.
+ */
+declare function tryIncrementBounded(counter: Node<number>, cap: number, by?: 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;
+};
+/**
+ * Mutation action shape. Plain function shorthand auto-wraps as `{ up: fn }`.
+ *
+ * - `up` — the mutation action (the "up migration").
+ * - `down` — optional rollback for closure mutations that `batch()` can't
+ *   reach. Receives the SAME frozen args as `up`. Runs AFTER batch reactive
+ *   rollback, BEFORE the failure record. Throws inside `down` are
+ *   console.error'd without masking the original error. Only meaningful
+ *   with `frame: "transactional"`.
+ */
+type MutationAct<TArgs extends readonly unknown[], TResult> = {
+    up: (...args: TArgs) => TResult;
+    down?: (...args: TArgs) => void;
+};
+type MutationFrame = "inline" | "transactional";
+type MutateOpts<TArgs extends readonly unknown[], TResult, R extends BaseAuditRecord> = {
+    /** Frame mode. `"inline"` = no batch; `"transactional"` = batch + rollback. */
+    frame: MutationFrame;
+    /**
+     * Optional log to append records to. When omitted, the wrapper still
+     * provides freeze / seq-advance / rollback-on-throw but skips record
+     * emission — useful for primitives that want centralized mutation
+     * semantics without a dedicated log surface (e.g. `Topic.publish`).
+     */
+    log?: ReactiveLogBundle<R>;
+    /** Build the success record from the action's args + result + meta. */
+    onSuccessRecord?: (args: TArgs, result: TResult, meta: SuccessMeta) => R | undefined;
+    /** Build the failure record from the args + error + meta. */
+    onFailureRecord?: (args: TArgs, error: unknown, meta: FailureMeta) => R | undefined;
+    /** Deep-freeze args at entry (default `true`). Opt out for hot paths. */
+    freeze?: boolean;
+    /** Optional sequence cursor — auto-advanced and stamped onto records. */
+    seq?: Node<number>;
+    /** Optional handler version — stamped per Audit 5. */
+    handlerVersion?: {
+        id: string;
+        version: string | number;
+    };
+};
+/**
+ * Universal mutation factory (Phase 14 — DS-14 Q-O2).
+ *
+ * Replaces the prior `lightMutation` + `wrapMutation` two-tier split.
+ * Single factory with `frame: "inline" | "transactional"` discriminant.
+ *
+ * @param act - The mutation action. Either a plain function (auto-wrapped as
+ *   `{ up: fn }`) or a `{ up, down? }` object for explicit rollback.
+ * @param opts - Configuration: frame, log, record builders, freeze, seq.
+ * @returns A typed wrapper function with the same signature as `act.up`.
+ */
+declare function mutate<TArgs extends readonly unknown[], TResult, R extends BaseAuditRecord>(act: MutationAct<TArgs, TResult> | ((...args: TArgs) => TResult), opts: MutateOpts<TArgs, TResult, R>): (...args: TArgs) => TResult;
+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;
+/**
+ * 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, type BaseAuditRecord, DEFAULT_AUDIT_GUARD, type FailureMeta, type MutateOpts, type MutationAct, type MutationFrame, type SuccessMeta, appendAudit, bumpCursor, createAuditLog, mutate, registerCursor, registerCursorMap, tryIncrementBounded };

package/dist/base/mutation/index.js

@@ -0,0 +1,22 @@
+import {
+  DEFAULT_AUDIT_GUARD,
+  appendAudit,
+  bumpCursor,
+  createAuditLog,
+  mutate,
+  registerCursor,
+  registerCursorMap,
+  tryIncrementBounded
+} from "../../chunk-BXGZFGZ4.js";
+import "../../chunk-AZDQPQ3V.js";
+export {
+  DEFAULT_AUDIT_GUARD,
+  appendAudit,
+  bumpCursor,
+  createAuditLog,
+  mutate,
+  registerCursor,
+  registerCursorMap,
+  tryIncrementBounded
+};
+//# sourceMappingURL=index.js.map

package/dist/base/mutation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}