@graphrefly/graphrefly 0.43.0 → 0.44.0

package/dist/{pipeline-graph-DPqKDk59.d.cts → pipeline-graph-CIKhynsF.d.cts}

@@ -1,8 +1,8 @@
-import { N as Node, c as NodeActions } from './node-ClS5yC-B.cjs';
-import { D as DerivedFn } from './sugar-DyVGtczU.cjs';
-import { B as BaseAuditRecord } from './index-C9pjcz3l.cjs';
-import { a as ReactiveLogBundle } from './reactive-log-B00laMSQ.cjs';
-import { G as Graph, a as GraphOptions } from './graph-C4SHb3Ly.cjs';
+import { N as Node, c as NodeActions } from './node-kK3CvTrR.cjs';
+import { a as DerivedFn } from './sugar-DQjFmVqb.cjs';
+import { B as BaseAuditRecord } from './index-D0aciIex.cjs';
+import { a as ReactiveLogBundle } from './reactive-log-DIGdYqQ6.cjs';
+import { G as Graph, a as GraphOptions } from './graph-CWvEUQAq.cjs';
 
 /**
  * PipelineGraph subclass (Wave A.1 Unit 1 — locked 2026-04-24).
@@ -55,7 +55,12 @@ interface GateOptions<T = unknown> {
     };
 }
 interface GateController<T> {
-    readonly node: Node<T>;
+    /**
+     * The post-gate output node. Renamed from `node` (Tier 5.2 / EC6,
+     * 2026-04-29) to avoid shadowing `Graph.node(name)` when a gate is
+     * accessed off a `PipelineGraph` instance.
+     */
+    readonly output: Node<T>;
     readonly pending: Node<readonly T[]>;
     readonly count: Node<number>;
     readonly isOpen: Node<boolean>;

package/dist/{pipeline-graph-loP57TBA.d.ts → pipeline-graph-Sgj0gCwn.d.ts}

@@ -1,8 +1,8 @@
-import { N as Node, c as NodeActions } from './node-ClS5yC-B.js';
-import { D as DerivedFn } from './sugar-DLwvMr3F.js';
-import { B as BaseAuditRecord } from './index-CZQXo5tH.js';
-import { a as ReactiveLogBundle } from './reactive-log-BezYsbA_.js';
-import { G as Graph, a as GraphOptions } from './graph-7VguS7a4.js';
+import { N as Node, c as NodeActions } from './node-kK3CvTrR.js';
+import { a as DerivedFn } from './sugar-fhLIE7TT.js';
+import { B as BaseAuditRecord } from './index-Yq60JP3s.js';
+import { a as ReactiveLogBundle } from './reactive-log-BKALbfal.js';
+import { G as Graph, a as GraphOptions } from './graph-D9LFnda9.js';
 
 /**
  * PipelineGraph subclass (Wave A.1 Unit 1 — locked 2026-04-24).
@@ -55,7 +55,12 @@ interface GateOptions<T = unknown> {
     };
 }
 interface GateController<T> {
-    readonly node: Node<T>;
+    /**
+     * The post-gate output node. Renamed from `node` (Tier 5.2 / EC6,
+     * 2026-04-29) to avoid shadowing `Graph.node(name)` when a gate is
+     * accessed off a `PipelineGraph` instance.
+     */
+    readonly output: Node<T>;
     readonly pending: Node<readonly T[]>;
     readonly count: Node<number>;
     readonly isOpen: Node<boolean>;

package/dist/{reactive-layout-v7KPvxoc.d.ts → reactive-layout-DOTs9P3X.d.ts}

@@ -1,5 +1,5 @@
-import { N as Node } from './node-ClS5yC-B.js';
-import { G as Graph } from './graph-7VguS7a4.js';
+import { N as Node } from './node-kK3CvTrR.js';
+import { G as Graph } from './graph-D9LFnda9.js';
 
 /** Pluggable measurement backend. */
 interface MeasurementAdapter {

package/dist/{reactive-layout-Dsvob4zD.d.cts → reactive-layout-DgctbqZo.d.cts}

@@ -1,5 +1,5 @@
-import { N as Node } from './node-ClS5yC-B.cjs';
-import { G as Graph } from './graph-C4SHb3Ly.cjs';
+import { N as Node } from './node-kK3CvTrR.cjs';
+import { G as Graph } from './graph-CWvEUQAq.cjs';
 
 /** Pluggable measurement backend. */
 interface MeasurementAdapter {

package/dist/{reactive-log-BezYsbA_.d.ts → reactive-log-BKALbfal.d.ts}

@@ -1,4 +1,4 @@
-import { V as VersioningLevel, b as NodeGuard, N as Node } from './node-ClS5yC-B.js';
+import { V as VersioningLevel, b as NodeGuard, N as Node } from './node-kK3CvTrR.js';
 import { AppendLogStorageTier } from './extra/storage-tiers.js';
 
 type ReactiveLogOptions<T> = {

package/dist/{reactive-log-B00laMSQ.d.cts → reactive-log-DIGdYqQ6.d.cts}

@@ -1,4 +1,4 @@
-import { V as VersioningLevel, b as NodeGuard, N as Node } from './node-ClS5yC-B.cjs';
+import { V as VersioningLevel, b as NodeGuard, N as Node } from './node-kK3CvTrR.cjs';
 import { AppendLogStorageTier } from './extra/storage-tiers.cjs';
 
 type ReactiveLogOptions<T> = {

package/dist/{reactive-map-48mnZ-nu.d.cts → reactive-map-CEFGp8TK.d.cts}

@@ -1,4 +1,4 @@
-import { N as Node, V as VersioningLevel, a as NodeOptions } from './node-ClS5yC-B.cjs';
+import { N as Node, V as VersioningLevel, a as NodeOptions } from './node-kK3CvTrR.cjs';
 
 type ReactiveMapOptions<K, V> = {
     /** Optional registry name for `describe()` / debugging. */

package/dist/{reactive-map-BVVPdvmi.d.ts → reactive-map-DS_SIAxv.d.ts}

@@ -1,4 +1,4 @@
-import { N as Node, V as VersioningLevel, a as NodeOptions } from './node-ClS5yC-B.js';
+import { N as Node, V as VersioningLevel, a as NodeOptions } from './node-kK3CvTrR.js';
 
 type ReactiveMapOptions<K, V> = {
     /** Optional registry name for `describe()` / debugging. */

package/dist/resilience-6LYQJAC5.js

@@ -0,0 +1 @@
+import{a,b,c,d,e,f,g,h,i,j,k,l,m,n}from"./chunk-D7GPHKFH.js";import"./chunk-L6NSJVJZ.js";import"./chunk-2T7U5EU6.js";import"./chunk-3G5U5QNE.js";import"./chunk-C72GO4IZ.js";import"./chunk-HITNVN6B.js";import"./chunk-ESMPEKEV.js";import"./chunk-CLVB32RD.js";import"./chunk-4VVTGLXJ.js";import"./chunk-GHBWHMRZ.js";import"./chunk-CRVT7D2P.js";import"./chunk-NTEURFZH.js";import"./chunk-CK2E7BTU.js";import"./chunk-QYADASLV.js";export{e as CircuitOpenError,i as RateLimiterOverflowError,b as ResilientPipelineGraph,l as TimeoutError,a as budgetGate,f as circuitBreaker,m as fallback,j as rateLimiter,c as resilientPipeline,d as retry,n as timeout,h as tokenBucket,g as withBreaker,k as withStatus};

package/dist/{sugar-DLwvMr3F.d.ts → sugar-DQjFmVqb.d.cts}

@@ -1,4 +1,111 @@
-import { a as NodeOptions, F as FnCtx, N as Node, c as NodeActions, d as NodeFnCleanup } from './node-ClS5yC-B.js';
+import { w as NodeDescribeKind, N as Node, A as Actor, F as FnCtx, c as NodeActions, y as NodeFnCleanup, a as NodeOptions } from './node-kK3CvTrR.cjs';
+
+/**
+ * JSON-shaped slice of a node for `Graph.describe()`
+ * (GRAPHREFLY-SPEC §3.6, Appendix B).
+ */
+type DescribeNodeOutput = {
+    type: NodeDescribeKind;
+    status?: Node["status"];
+    deps: string[];
+    meta?: Record<string, unknown>;
+    name?: string;
+    value?: unknown;
+    /** True when the node is in `"sentinel"` state (no value ever). */
+    sentinel?: boolean;
+    v?: {
+        id: string;
+        version: number;
+        cid?: string;
+        prev?: string | null;
+    };
+    guard?: string;
+    lastMutation?: Readonly<{
+        actor: Actor;
+        timestamp_ns: number;
+    }>;
+    /**
+     * Latest annotation attached via `graph.trace(path, annotation)` or via
+     * `graph.add(node, { name: path, annotation })`, when present. Populated by
+     * `Graph.describe` only — `describeNode` has no graph context.
+     */
+    annotation?: string;
+};
+/**
+ * Detail level for progressive disclosure (Phase 3.3b).
+ *
+ * - `"minimal"` — `type`, `deps` only.
+ * - `"standard"` — minimal + `status`, `value`, `meta`, `v`.
+ * - `"full"` — every field.
+ * - `"spec"` — Tier 1.5.3 (Session A.1 lock + Phase 3 path (b)). Projects
+ *   spec-relevant fields (`type`, `deps`, `meta` — including
+ *   `meta.factory` / `meta.factoryArgs`) and strips runtime fields
+ *   (`status`, `lastMutation`, `guard`, `sentinel`, `v`). **Retains
+ *   `value` for state nodes only** so the seed initial value round-trips
+ *   through `decompileSpec` → `compileSpec` without forcing every state
+ *   constructor to spawn `meta.factory`/`factoryArgs` companion nodes.
+ *   The output is structurally identical to the `GraphSpec` shape so
+ *   `decompileSpec(g) === describe(g, { detail: "spec" })`.
+ */
+type DescribeDetail = "minimal" | "standard" | "full" | "spec";
+/** Valid field names for `describe({ fields: [...] })`. */
+type DescribeField = "type" | "status" | "value" | "deps" | "meta" | "v" | "guard" | "lastMutation" | `meta.${string}`;
+/** Resolve which fields to include based on detail level or explicit field list. */
+declare function resolveDescribeFields(detail?: DescribeDetail, fields?: readonly DescribeField[]): Set<string> | null;
+/**
+ * Walk an arbitrary value, replacing non-JSON-serializable fields with
+ * descriptive string placeholders (Tier 1.5.3 Phase 2.5 — DG2=ii). Useful for
+ * `Graph.prototype.tagFactory(name, args)` when the factory's options include
+ * `LLMAdapter` instances, callbacks, or `Node`s that don't survive
+ * serialization. Output preserves structure for documentation / audit value;
+ * recipients of the spec see "<Node>" / "<function>" / etc. in place of the
+ * unserializable bits.
+ *
+ * Heuristics:
+ * - `null` / `undefined` / boolean / number / string — kept as-is.
+ * - `function` — `"<function>"`.
+ * - Object with `subscribe` method — `"<Node>"` (matches Node-shape duck check).
+ * - Array — recursed.
+ * - Plain object — recursed.
+ * - Anything else — `"<unserializable>"`.
+ *
+ * **`undefined`-key caveat (DF11, 2026-04-29 doc lock).** Keys whose value
+ * is `undefined` survive `placeholderArgs` (they are kept as-is per the
+ * heuristic above). However, `JSON.stringify` DROPS such keys at the
+ * serialization boundary, so a spec round-trip via `toJSONString` does
+ * not preserve them. Callers that need `undefined` to round-trip must
+ * substitute an explicit sentinel (e.g. `null`) before tagging — meta-
+ * vs-spec disagreement at the JSON boundary is otherwise inevitable.
+ */
+declare function placeholderArgs(opts: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Build a `meta` fragment that stamps a factory identifier and its construction
+ * arguments onto a node, so `describe({ detail: "spec" })` exposes enough
+ * information for `compileSpec` to recreate the node from the snapshot.
+ *
+ * Use inside node-producing factories at construction time:
+ *
+ * ```ts
+ * import { factoryTag } from "@graphrefly/graphrefly";
+ *
+ * export function rateLimiter<T>(source: NodeInput<T>, opts: RateLimiterOptions): Node<T> {
+ *   return derived([fromAny(source)], fn, {
+ *     name: "rate-limiter",
+ *     meta: { ...factoryTag("rateLimiter", opts), domain: "resilience" },
+ *   });
+ * }
+ * ```
+ *
+ * `factoryArgs` should be JSON-serializable so the spec round-trips through
+ * `decompileSpec → compileSpec`. Function-typed args break determinism — use
+ * the {@link COMPOSITION-GUIDE} §39 `meta.fnId` pattern for those.
+ *
+ * Tier 1.5.3 (Session A.1 lock).
+ */
+declare function factoryTag(factory: string, factoryArgs?: unknown): {
+    factory: string;
+    factoryArgs?: unknown;
+};
 
 /**
  * Sugar constructors over the raw `node()` primitive.
@@ -96,6 +203,52 @@ type DerivedFn<T> = (data: readonly unknown[], ctx: FnCtx) => T | undefined | nu
  * ```
  */
 declare function derived<T = unknown>(deps: readonly Node[], fn: DerivedFn<T>, opts?: NodeOptions<T>): Node<T>;
+/**
+ * Maps a tuple of `Node<V>`s to a tuple of `V`s. Used by {@link derivedT}
+ * and {@link effectT} to propagate dep value types into the callback's
+ * `data` parameter — eliminating per-callsite `as` casts.
+ */
+type NodeValues<TDeps extends readonly Node<unknown>[]> = {
+    readonly [K in keyof TDeps]: TDeps[K] extends Node<infer V> ? V : never;
+};
+/**
+ * Typed callback for {@link derivedT}. Each tuple element corresponds
+ * positionally to the matching dep's value type.
+ */
+type DerivedTFn<TDeps extends readonly Node<unknown>[], TOut> = (data: NodeValues<TDeps>, ctx: FnCtx) => TOut | undefined | null;
+/**
+ * Typed callback for {@link effectT}. Each tuple element corresponds
+ * positionally to the matching dep's value type.
+ */
+type EffectTFn<TDeps extends readonly Node<unknown>[]> = (data: NodeValues<TDeps>, actions: NodeActions, ctx: FnCtx) => NodeFnCleanup | void;
+/**
+ * Typed-tuple variant of {@link derived}. Use when the dep types matter at
+ * the callback boundary — `data` is inferred as a tuple of dep value types
+ * instead of `readonly unknown[]`.
+ *
+ * Same runtime semantics as {@link derived} (first-run gate, snapshot
+ * combine semantics, equals substitution).
+ *
+ * **`partial: true` is rejected at the type level (qa F-E, 2026-04-29).**
+ * Tuple slots in `NodeValues<TDeps>` resolve to `V` (never `V | undefined`),
+ * but `partial: true` lets fn run before every dep has fired. The two are
+ * unsound together — fn would receive `undefined` for an unfired dep but
+ * see it typed as `V`. Callers needing partial firing keep using untyped
+ * {@link derived} where `data` is `readonly unknown[]` and the
+ * `=== undefined` guard is sanctioned (COMPOSITION-GUIDE §3 partial-true
+ * exception).
+ *
+ * @example
+ * ```ts
+ * const a = state(1);
+ * const b = state("hi");
+ * // sum: number, label: string — no casts needed.
+ * const out = derivedT([a, b], ([sum, label]) => `${label}:${sum * 2}`);
+ * ```
+ */
+declare function derivedT<TDeps extends readonly Node<unknown>[], TOut>(deps: TDeps, fn: DerivedTFn<TDeps, TOut>, opts?: Omit<NodeOptions<TOut>, "partial"> & {
+    partial?: false;
+}): Node<TOut>;
 /**
  * User-level effect compute: fires when deps settle. Return value is NOT
  * auto-emitted — use `actions.emit(v)` / `actions.down(msgs)` explicitly if
@@ -105,6 +258,29 @@ declare function derived<T = unknown>(deps: readonly Node[], fn: DerivedFn<T>, o
  * See {@link NodeFnCleanup}.
  */
 type EffectFn = (data: readonly unknown[], actions: NodeActions, ctx: FnCtx) => NodeFnCleanup | void;
+/**
+ * Typed-tuple variant of {@link effect}. Use when the dep types matter at
+ * the callback boundary — `data` is inferred as a tuple of dep value types
+ * instead of `readonly unknown[]`.
+ *
+ * Same runtime semantics as {@link effect} (first-run gate, no auto-emit,
+ * cleanup contract).
+ *
+ * **`partial: true` is rejected at the type level (qa F-E, 2026-04-29).**
+ * See {@link derivedT} for the soundness rationale.
+ *
+ * @example
+ * ```ts
+ * const user = state<User | null>(null);
+ * const cfg = state<Config>(defaultCfg);
+ * effectT([user, cfg], ([u, c]) => {
+ *   if (u != null) hydrate(u, c);
+ * });
+ * ```
+ */
+declare function effectT<TDeps extends readonly Node<unknown>[]>(deps: TDeps, fn: EffectTFn<TDeps>, opts?: Omit<NodeOptions<unknown>, "partial"> & {
+    partial?: false;
+}): Node<unknown>;
 /**
  * Runs a side-effect when deps settle. Return value is not auto-emitted.
  *
@@ -220,4 +396,4 @@ type PipeOperator = (n: Node) => Node;
  */
 declare function pipe(source: Node, ...ops: PipeOperator[]): Node;
 
-export { type AutoTrackOptions as A, type DerivedFn as D, type EffectFn as E, type PipeOperator as P, type TrackFn as T, type DynamicFn as a, type ProducerFn as b, autoTrackNode as c, derived as d, dynamicNode as e, effect as f, producer as g, pipe as p, state as s };
+export { type AutoTrackOptions as A, type DescribeNodeOutput as D, type EffectFn as E, type NodeValues as N, type PipeOperator as P, type TrackFn as T, type DerivedFn as a, type DerivedTFn as b, type DescribeDetail as c, type DescribeField as d, type DynamicFn as e, type EffectTFn as f, type ProducerFn as g, autoTrackNode as h, derived as i, derivedT as j, dynamicNode as k, effect as l, effectT as m, factoryTag as n, placeholderArgs as o, pipe as p, producer as q, resolveDescribeFields as r, state as s };

package/dist/{sugar-DyVGtczU.d.cts → sugar-fhLIE7TT.d.ts}

@@ -1,4 +1,111 @@
-import { a as NodeOptions, F as FnCtx, N as Node, c as NodeActions, d as NodeFnCleanup } from './node-ClS5yC-B.cjs';
+import { w as NodeDescribeKind, N as Node, A as Actor, F as FnCtx, c as NodeActions, y as NodeFnCleanup, a as NodeOptions } from './node-kK3CvTrR.js';
+
+/**
+ * JSON-shaped slice of a node for `Graph.describe()`
+ * (GRAPHREFLY-SPEC §3.6, Appendix B).
+ */
+type DescribeNodeOutput = {
+    type: NodeDescribeKind;
+    status?: Node["status"];
+    deps: string[];
+    meta?: Record<string, unknown>;
+    name?: string;
+    value?: unknown;
+    /** True when the node is in `"sentinel"` state (no value ever). */
+    sentinel?: boolean;
+    v?: {
+        id: string;
+        version: number;
+        cid?: string;
+        prev?: string | null;
+    };
+    guard?: string;
+    lastMutation?: Readonly<{
+        actor: Actor;
+        timestamp_ns: number;
+    }>;
+    /**
+     * Latest annotation attached via `graph.trace(path, annotation)` or via
+     * `graph.add(node, { name: path, annotation })`, when present. Populated by
+     * `Graph.describe` only — `describeNode` has no graph context.
+     */
+    annotation?: string;
+};
+/**
+ * Detail level for progressive disclosure (Phase 3.3b).
+ *
+ * - `"minimal"` — `type`, `deps` only.
+ * - `"standard"` — minimal + `status`, `value`, `meta`, `v`.
+ * - `"full"` — every field.
+ * - `"spec"` — Tier 1.5.3 (Session A.1 lock + Phase 3 path (b)). Projects
+ *   spec-relevant fields (`type`, `deps`, `meta` — including
+ *   `meta.factory` / `meta.factoryArgs`) and strips runtime fields
+ *   (`status`, `lastMutation`, `guard`, `sentinel`, `v`). **Retains
+ *   `value` for state nodes only** so the seed initial value round-trips
+ *   through `decompileSpec` → `compileSpec` without forcing every state
+ *   constructor to spawn `meta.factory`/`factoryArgs` companion nodes.
+ *   The output is structurally identical to the `GraphSpec` shape so
+ *   `decompileSpec(g) === describe(g, { detail: "spec" })`.
+ */
+type DescribeDetail = "minimal" | "standard" | "full" | "spec";
+/** Valid field names for `describe({ fields: [...] })`. */
+type DescribeField = "type" | "status" | "value" | "deps" | "meta" | "v" | "guard" | "lastMutation" | `meta.${string}`;
+/** Resolve which fields to include based on detail level or explicit field list. */
+declare function resolveDescribeFields(detail?: DescribeDetail, fields?: readonly DescribeField[]): Set<string> | null;
+/**
+ * Walk an arbitrary value, replacing non-JSON-serializable fields with
+ * descriptive string placeholders (Tier 1.5.3 Phase 2.5 — DG2=ii). Useful for
+ * `Graph.prototype.tagFactory(name, args)` when the factory's options include
+ * `LLMAdapter` instances, callbacks, or `Node`s that don't survive
+ * serialization. Output preserves structure for documentation / audit value;
+ * recipients of the spec see "<Node>" / "<function>" / etc. in place of the
+ * unserializable bits.
+ *
+ * Heuristics:
+ * - `null` / `undefined` / boolean / number / string — kept as-is.
+ * - `function` — `"<function>"`.
+ * - Object with `subscribe` method — `"<Node>"` (matches Node-shape duck check).
+ * - Array — recursed.
+ * - Plain object — recursed.
+ * - Anything else — `"<unserializable>"`.
+ *
+ * **`undefined`-key caveat (DF11, 2026-04-29 doc lock).** Keys whose value
+ * is `undefined` survive `placeholderArgs` (they are kept as-is per the
+ * heuristic above). However, `JSON.stringify` DROPS such keys at the
+ * serialization boundary, so a spec round-trip via `toJSONString` does
+ * not preserve them. Callers that need `undefined` to round-trip must
+ * substitute an explicit sentinel (e.g. `null`) before tagging — meta-
+ * vs-spec disagreement at the JSON boundary is otherwise inevitable.
+ */
+declare function placeholderArgs(opts: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Build a `meta` fragment that stamps a factory identifier and its construction
+ * arguments onto a node, so `describe({ detail: "spec" })` exposes enough
+ * information for `compileSpec` to recreate the node from the snapshot.
+ *
+ * Use inside node-producing factories at construction time:
+ *
+ * ```ts
+ * import { factoryTag } from "@graphrefly/graphrefly";
+ *
+ * export function rateLimiter<T>(source: NodeInput<T>, opts: RateLimiterOptions): Node<T> {
+ *   return derived([fromAny(source)], fn, {
+ *     name: "rate-limiter",
+ *     meta: { ...factoryTag("rateLimiter", opts), domain: "resilience" },
+ *   });
+ * }
+ * ```
+ *
+ * `factoryArgs` should be JSON-serializable so the spec round-trips through
+ * `decompileSpec → compileSpec`. Function-typed args break determinism — use
+ * the {@link COMPOSITION-GUIDE} §39 `meta.fnId` pattern for those.
+ *
+ * Tier 1.5.3 (Session A.1 lock).
+ */
+declare function factoryTag(factory: string, factoryArgs?: unknown): {
+    factory: string;
+    factoryArgs?: unknown;
+};
 
 /**
  * Sugar constructors over the raw `node()` primitive.
@@ -96,6 +203,52 @@ type DerivedFn<T> = (data: readonly unknown[], ctx: FnCtx) => T | undefined | nu
  * ```
  */
 declare function derived<T = unknown>(deps: readonly Node[], fn: DerivedFn<T>, opts?: NodeOptions<T>): Node<T>;
+/**
+ * Maps a tuple of `Node<V>`s to a tuple of `V`s. Used by {@link derivedT}
+ * and {@link effectT} to propagate dep value types into the callback's
+ * `data` parameter — eliminating per-callsite `as` casts.
+ */
+type NodeValues<TDeps extends readonly Node<unknown>[]> = {
+    readonly [K in keyof TDeps]: TDeps[K] extends Node<infer V> ? V : never;
+};
+/**
+ * Typed callback for {@link derivedT}. Each tuple element corresponds
+ * positionally to the matching dep's value type.
+ */
+type DerivedTFn<TDeps extends readonly Node<unknown>[], TOut> = (data: NodeValues<TDeps>, ctx: FnCtx) => TOut | undefined | null;
+/**
+ * Typed callback for {@link effectT}. Each tuple element corresponds
+ * positionally to the matching dep's value type.
+ */
+type EffectTFn<TDeps extends readonly Node<unknown>[]> = (data: NodeValues<TDeps>, actions: NodeActions, ctx: FnCtx) => NodeFnCleanup | void;
+/**
+ * Typed-tuple variant of {@link derived}. Use when the dep types matter at
+ * the callback boundary — `data` is inferred as a tuple of dep value types
+ * instead of `readonly unknown[]`.
+ *
+ * Same runtime semantics as {@link derived} (first-run gate, snapshot
+ * combine semantics, equals substitution).
+ *
+ * **`partial: true` is rejected at the type level (qa F-E, 2026-04-29).**
+ * Tuple slots in `NodeValues<TDeps>` resolve to `V` (never `V | undefined`),
+ * but `partial: true` lets fn run before every dep has fired. The two are
+ * unsound together — fn would receive `undefined` for an unfired dep but
+ * see it typed as `V`. Callers needing partial firing keep using untyped
+ * {@link derived} where `data` is `readonly unknown[]` and the
+ * `=== undefined` guard is sanctioned (COMPOSITION-GUIDE §3 partial-true
+ * exception).
+ *
+ * @example
+ * ```ts
+ * const a = state(1);
+ * const b = state("hi");
+ * // sum: number, label: string — no casts needed.
+ * const out = derivedT([a, b], ([sum, label]) => `${label}:${sum * 2}`);
+ * ```
+ */
+declare function derivedT<TDeps extends readonly Node<unknown>[], TOut>(deps: TDeps, fn: DerivedTFn<TDeps, TOut>, opts?: Omit<NodeOptions<TOut>, "partial"> & {
+    partial?: false;
+}): Node<TOut>;
 /**
  * User-level effect compute: fires when deps settle. Return value is NOT
  * auto-emitted — use `actions.emit(v)` / `actions.down(msgs)` explicitly if
@@ -105,6 +258,29 @@ declare function derived<T = unknown>(deps: readonly Node[], fn: DerivedFn<T>, o
  * See {@link NodeFnCleanup}.
  */
 type EffectFn = (data: readonly unknown[], actions: NodeActions, ctx: FnCtx) => NodeFnCleanup | void;
+/**
+ * Typed-tuple variant of {@link effect}. Use when the dep types matter at
+ * the callback boundary — `data` is inferred as a tuple of dep value types
+ * instead of `readonly unknown[]`.
+ *
+ * Same runtime semantics as {@link effect} (first-run gate, no auto-emit,
+ * cleanup contract).
+ *
+ * **`partial: true` is rejected at the type level (qa F-E, 2026-04-29).**
+ * See {@link derivedT} for the soundness rationale.
+ *
+ * @example
+ * ```ts
+ * const user = state<User | null>(null);
+ * const cfg = state<Config>(defaultCfg);
+ * effectT([user, cfg], ([u, c]) => {
+ *   if (u != null) hydrate(u, c);
+ * });
+ * ```
+ */
+declare function effectT<TDeps extends readonly Node<unknown>[]>(deps: TDeps, fn: EffectTFn<TDeps>, opts?: Omit<NodeOptions<unknown>, "partial"> & {
+    partial?: false;
+}): Node<unknown>;
 /**
  * Runs a side-effect when deps settle. Return value is not auto-emitted.
  *
@@ -220,4 +396,4 @@ type PipeOperator = (n: Node) => Node;
  */
 declare function pipe(source: Node, ...ops: PipeOperator[]): Node;
 
-export { type AutoTrackOptions as A, type DerivedFn as D, type EffectFn as E, type PipeOperator as P, type TrackFn as T, type DynamicFn as a, type ProducerFn as b, autoTrackNode as c, derived as d, dynamicNode as e, effect as f, producer as g, pipe as p, state as s };
+export { type AutoTrackOptions as A, type DescribeNodeOutput as D, type EffectFn as E, type NodeValues as N, type PipeOperator as P, type TrackFn as T, type DerivedFn as a, type DerivedTFn as b, type DescribeDetail as c, type DescribeField as d, type DynamicFn as e, type EffectTFn as f, type ProducerFn as g, autoTrackNode as h, derived as i, derivedT as j, dynamicNode as k, effect as l, effectT as m, factoryTag as n, placeholderArgs as o, pipe as p, producer as q, resolveDescribeFields as r, state as s };

package/dist/{topology-tree-BSdfSwMi.d.cts → topology-tree-Bcz27hpF.d.cts}

@@ -1,4 +1,4 @@
-import { G as Graph, T as TopologyEvent } from './graph-C4SHb3Ly.cjs';
+import { G as Graph, T as TopologyEvent } from './graph-CWvEUQAq.cjs';
 
 /**
  * Subscribe to structural changes across `graph` and every transitively

package/dist/{topology-tree-BNGvuG82.d.ts → topology-tree-xvaD0fOX.d.ts}

@@ -1,4 +1,4 @@
-import { G as Graph, T as TopologyEvent } from './graph-7VguS7a4.js';
+import { G as Graph, T as TopologyEvent } from './graph-D9LFnda9.js';
 
 /**
  * Subscribe to structural changes across `graph` and every transitively

package/dist/{types-B1jDWVsM.d.cts → types-C0_yquda.d.cts}

@@ -1,4 +1,4 @@
-import { N as Node } from './node-ClS5yC-B.cjs';
+import { N as Node } from './node-kK3CvTrR.cjs';
 import { NodeInput } from './extra/sources.cjs';
 
 /**

package/dist/{types-DkzUUs0H.d.ts → types-CWFysE9E.d.ts}

@@ -1,4 +1,4 @@
-import { N as Node } from './node-ClS5yC-B.js';
+import { N as Node } from './node-kK3CvTrR.js';
 import { NodeInput } from './extra/sources.js';
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@graphrefly/graphrefly",
-	"version": "0.43.0",
+	"version": "0.44.0",
 	"packageManager": "pnpm@10.33.0+sha512.10568bb4a6afb58c9eb3630da90cc9516417abebd3fabbe6739f0ae795728da1491e9db5a544c76ad8eb7570f5c4bb3d6c637b2cb41bfdcdb47fa823c8649319",
 	"description": "Reactive harness layer for agent workflows. Describe automations in plain language, trace every decision, enforce policies, persist checkpoints. Zero dependencies.",
 	"repository": {

package/dist/chunk-3XDYJRYU.js

@@ -1 +0,0 @@
-import{c as B,d as G,f as v,h as W}from"./chunk-FDQGFWLF.js";import{a as L}from"./chunk-L6NSJVJZ.js";import{j as I}from"./chunk-626TESAC.js";import{b as D}from"./chunk-35JTVPOX.js";import{b as U}from"./chunk-KGKJCHEK.js";import{b as K}from"./chunk-TZQPPQEQ.js";import{b as Q}from"./chunk-JQFH2DV6.js";import{C as _,m as z}from"./chunk-V5A7M7RJ.js";import{D as P,G as N,m as f,p as $}from"./chunk-LYCLF26R.js";import{b as x,j as S}from"./chunk-CK2E7BTU.js";import{b as ee}from"./chunk-QYADASLV.js";var re={};ee(re,{JobFlowGraph:()=>w,JobQueueGraph:()=>y,jobEventKeyOf:()=>oe,jobFlow:()=>se,jobQueue:()=>V});var te=256,ne=1024;function F(p,e){if(!Number.isFinite(p)||!Number.isInteger(p)||p<0)throw new Error(`${e} must be a non-negative integer`);return p}function T(p,e){return L("job_queue",p,e)}var oe=p=>p.action,y=class extends I{_pending;_jobs;_seqCursor;pending;jobs;depth;events;audit;_enqueueImpl;_ackImpl;_nackImpl;_removeByIdImpl;constructor(e,n={}){super(e,n.graph),this._pending=U([],{name:"pending"}),this._jobs=K({name:"jobs"}),this.pending=this._pending.items,this.jobs=this._jobs.entries,this.add(this.pending,{name:"pending"}),this.add(this.jobs,{name:"jobs"}),this.depth=N([this.pending],([t])=>t.length,{name:"depth",describeKind:"derived",meta:T("queue_depth"),initial:0}),this.add(this.depth,{name:"depth"}),this.addDisposer(_(this.depth)),this.events=B({name:"events",retainedLimit:1024,graph:this}),this.audit=this.events,this._seqCursor=W(this,"seq",0),this._enqueueImpl=v((t,o)=>{let a=this._seqCursor.cache,s=o.id??`${this.name}-${a}`;if(this._jobs.get(s)!==void 0)throw new Error(`jobQueue("${this.name}"): duplicate job id "${s}"`);let u={id:s,payload:t,attempts:0,metadata:Object.freeze({...o.metadata??{}}),state:"queued"};return this._jobs.set(s,u),this._pending.append(s),s},{audit:this.events,seq:this._seqCursor,freeze:!1,onSuccess:([t],o,{t_ns:a,seq:s})=>({action:"enqueue",id:o,payload:t,t_ns:a,seq:s??0})}),this._ackImpl=v((t,o)=>{this._jobs.delete(t)},{audit:this.events,seq:this._seqCursor,freeze:!1,onSuccess:([t,o],a,{t_ns:s,seq:u})=>({action:"ack",id:t,attempts:o.attempts,t_ns:s,seq:u??0})}),this._nackImpl=v((t,o,a)=>{a?(this._jobs.set(t,{...o,state:"queued"}),this._pending.append(t)):this._jobs.delete(t)},{audit:this.events,seq:this._seqCursor,freeze:!1,onSuccess:([t,o],a,{t_ns:s,seq:u})=>({action:"nack",id:t,attempts:o.attempts,t_ns:s,seq:u??0})}),this._removeByIdImpl=v((t,o)=>{if(o.state==="queued"){let s=this.pending.cache.indexOf(t);s>=0&&this._pending.pop(s)}this._jobs.delete(t)},{audit:this.events,seq:this._seqCursor,freeze:!1,onSuccess:([t,o],a,{t_ns:s,seq:u})=>({action:"remove",id:t,attempts:o.attempts,t_ns:s,seq:u??0})})}attachEventStorage(e){return this.events.attachStorage(e)}enqueue(e,n={}){return this._enqueueImpl(e,n)}claim(e=1){let n=F(e,"job queue claim limit");if(n===0)return[];let t=[];for(;t.length<n&&this.pending.cache.length!==0;){let a=this._pending.pop(0),s=this._jobs.get(a);if(!s||s.state!=="queued")continue;let u={...s,state:"inflight",attempts:s.attempts+1};this._jobs.set(a,u),t.push(u),this.events.append({action:"claim",id:a,attempts:u.attempts,t_ns:$(),seq:G(this._seqCursor)})}return t}ack(e){let n=this._jobs.get(e);return!n||n.state!=="inflight"?!1:(this._ackImpl(e,n),!0)}nack(e,n={}){let t=this._jobs.get(e);return!t||t.state!=="inflight"?!1:(this._nackImpl(e,t,n.requeue??!0),!0)}removeById(e){let n=this._jobs.get(e);return n?(this._removeByIdImpl(e,n),!0):!1}consumeFrom(e,n){return e.subscribe(t=>{for(let o of t){if(o[0]!==x)continue;let a=o[1];this.enqueue(a,n?{metadata:n.metadata}:void 0)}})}},w=class extends I{_stageNames;_stageWorkFns;_queues=new Map;_completed;completed;completedCount;constructor(e,n={}){super(e,n.graph);let t=n.stages??["incoming","processing","done"],o=[],a=new Map,s=new Map;for(let r of t){let i=typeof r=="string"?r.trim():r.name.trim();typeof r!="string"&&r.work&&a.set(i,r.work),typeof r!="string"&&r.maxPerPump!=null&&s.set(i,Math.max(1,F(r.maxPerPump,`job flow stage "${i}" maxPerPump`))),o.push(i)}if(o.length<2)throw new Error(`jobFlow("${e}"): requires at least 2 stages`);if(new Set(o).size!==o.length)throw new Error(`jobFlow("${e}"): stage names must be unique`);this._stageNames=Object.freeze([...o]),this._stageWorkFns=a;for(let r of this._stageNames){let i=V(`${e}-${r}`);this._queues.set(r,i),this.mount(r,i)}this._completed=Q([],{name:"completed",maxSize:ne}),this.completed=this._completed.entries,this.add(this.completed,{name:"completed"}),this.completedCount=N([this.completed],([r])=>r.length,{name:"completedCount",describeKind:"derived",meta:T("job_flow_completed_count"),initial:0}),this.add(this.completedCount,{name:"completedCount"}),this.addDisposer(_(this.completedCount));let X=Math.max(1,F(n.maxPerPump??te,"job flow maxPerPump"));for(let r=0;r<this._stageNames.length;r+=1){let i=this._stageNames[r],l=this.queue(i),j=r+1<this._stageNames.length?this.queue(this._stageNames[r+1]):null,R=this._stageWorkFns.get(i),C=s.get(i)??X,M=j===null;if(R){let h=P([l.pending],()=>{let c=0;for(;c<C;){let g=l.claim(1);if(g.length===0)break;let d=g[0];if(!d)break;let q=[...d.metadata.job_flow_path??[],i],b;try{b=R(d)}catch{l.nack(d.id,{requeue:!1}),c+=1;continue}let k=z(b),E=!1,m;m=k.subscribe(Y=>{if(!E){for(let J of Y)if(J[0]===x){E=!0,m?m():Promise.resolve().then(()=>m?.());let A=J[1],O={...d.metadata,job_flow_path:q};if(M){let Z={...d,payload:A,metadata:Object.freeze(O)};f(()=>{l.ack(d.id),this._completed.append(Z)})}else f(()=>{l.ack(d.id),j.enqueue(A,{metadata:O})});return}else if(J[0]===S){E=!0,m?m():Promise.resolve().then(()=>m?.()),l.nack(d.id,{requeue:!1});return}}}),c+=1}},{name:`pump_${i}`,describeKind:"effect",meta:T("job_flow_pump",{stage:i,has_work:!0})});this.add(h,{name:`pump_${i}`}),this.addDisposer(_(h))}else{let h=P([l.pending],()=>{let c=0;for(;c<C;){let g=l.claim(1);if(g.length===0)break;let d=g[0];if(!d)break;let q=[...d.metadata.job_flow_path??[],i],b={...d.metadata,job_flow_path:q};if(M){let k={...d,metadata:Object.freeze(b)};f(()=>{l.ack(d.id),this._completed.append(k)})}else f(()=>{l.ack(d.id),j.enqueue(d.payload,{metadata:b})});c+=1}},{name:`pump_${i}`,describeKind:"effect",meta:T("job_flow_pump",{stage:i,has_work:!1})});this.add(h,{name:`pump_${i}`}),this.addDisposer(_(h))}}}stages(){return this._stageNames}queue(e){let n=this._queues.get(e);if(!n)throw new Error(`jobFlow("${this.name}"): unknown stage "${e}"`);return n}enqueue(e,n={}){return this.queue(this._stageNames[0]).enqueue(e,n)}retainedCompleted(){return this.completed.cache}};function V(p,e){return new y(p,e)}function se(p,e){let n=new w(p,e),{factory:t,factoryArgs:o,...a}=e??{};return n.tagFactory("jobFlow",D(a)),n}export{oe as a,y as b,w as c,V as d,se as e,re as f};

package/dist/chunk-4I45FVQS.js

@@ -1 +0,0 @@
-import{a as w,b as U,c as K}from"./chunk-35JTVPOX.js";import{A as b,B as F,C as H,D as G,E as h,F as k,G as B,H as Y,I as v,J as P,K as W,i as q,j as z,k as g,m as S,n as C,o as I,p as M,q as _,r as u,s as J,t as Q,u as X,v as Z,w as L,x as m,y as x,z as V}from"./chunk-LYCLF26R.js";import{a as e,b as t,c as o,d as p,e as r,f as n,g as s,h as i,i as y,j as a,k as d,l as c,m as N,n as T,o as E,p as O,q as l,r as A,s as D,t as f,u as R}from"./chunk-CK2E7BTU.js";import{b as j}from"./chunk-QYADASLV.js";var $={};j($,{COMPLETE:()=>y,COMPLETE_MSG:()=>E,COMPLETE_ONLY_BATCH:()=>f,DATA:()=>t,DEFAULT_ACTOR:()=>q,DIRTY:()=>o,DIRTY_MSG:()=>d,DIRTY_ONLY_BATCH:()=>l,ERROR:()=>a,GraphReFlyConfig:()=>_,GuardDenied:()=>J,INVALIDATE:()=>r,INVALIDATE_MSG:()=>N,INVALIDATE_ONLY_BATCH:()=>D,NodeImpl:()=>H,PAUSE:()=>n,RESOLVED:()=>p,RESOLVED_MSG:()=>c,RESOLVED_ONLY_BATCH:()=>A,RESUME:()=>s,START:()=>e,START_MSG:()=>T,TEARDOWN:()=>i,TEARDOWN_MSG:()=>O,TEARDOWN_ONLY_BATCH:()=>R,accessHintForGuard:()=>Z,advanceVersion:()=>x,autoTrackNode:()=>P,batch:()=>S,configure:()=>F,createVersioning:()=>m,defaultConfig:()=>b,defaultHash:()=>L,derived:()=>B,downWithBatch:()=>C,dynamicNode:()=>v,effect:()=>Y,factoryTag:()=>K,isBatching:()=>g,isV1:()=>V,monotonicNs:()=>I,node:()=>G,normalizeActor:()=>z,pipe:()=>W,placeholderArgs:()=>U,policy:()=>Q,policyFromRules:()=>X,producer:()=>k,registerBuiltins:()=>u,resolveDescribeFields:()=>w,state:()=>h,wallClockNs:()=>M});export{$ as a};