@graphrefly/graphrefly 0.45.0 → 0.46.0

package/dist/pipeline-graph-Ce47CB6Y.d.cts

@@ -0,0 +1,145 @@
+import { Node, NodeActions } from '@graphrefly/pure-ts/core';
+import { ReactiveLogBundle } from '@graphrefly/pure-ts/extra';
+import { Graph, GraphOptions } from '@graphrefly/pure-ts/graph';
+import { BaseAuditRecord } from './base/mutation/index.cjs';
+
+/**
+ * PipelineGraph subclass (Wave A.1 Unit 1 — locked 2026-04-24).
+ *
+ * Specialized {@link Graph} that hosts workflow-DAG sugar methods:
+ * `task` / `classify` / `combine` / `approval` / `approvalGate` / `catch`.
+ * The legacy `pipeline` / `task` / `branch` / `join` / `subPipeline` /
+ * `approval` / `loop` / `onFailure` factories from {@link ./index} continue
+ * to work for migration ease; new code should prefer methods on this class.
+ *
+ * **Tier 2.3 rename:** the prior `gate(...)` method is now `approvalGate(...)`,
+ * disambiguating it from the other gate-family primitives (`budgetGate` for
+ * numeric constraints, `valve` for boolean switching, `policyGate` for ABAC
+ * rules). The "gating dimension" here is **human judgment**.
+ *
+ * Construction: `pipelineGraph(name, opts?)` or `new PipelineGraph(name, opts)`.
+ */
+
+type StepRef = string | Node<unknown>;
+type DecisionAction = "approve" | "reject" | "modify" | "drop" | "open" | "close" | "teardown";
+interface Decision<T = unknown> extends BaseAuditRecord {
+    readonly action: DecisionAction;
+    readonly count?: number;
+    readonly items?: readonly T[];
+    readonly unflushed?: number;
+}
+/** Recommended `keyOf` for keyed-storage adapters (Audit 2 #7). */
+declare const decisionKeyOf: <T>(d: Decision<T>) => string;
+interface GateOptions<_T = unknown> {
+    /** Bounded default 1000 (Audit 2 cross-cutting). `Infinity` is opt-in. */
+    maxPending?: number;
+    startOpen?: boolean;
+    /**
+     * Reactive auto-approve: gate's `latestIsOpen` mirrors this node's truthy
+     * value. False→true transition drains the pending queue.
+     *
+     * **`COMPLETE` / `ERROR` on the approver are silently ignored** — the gate
+     * stays in its current state. For permanent-open latching, use
+     * `onceOnly: true` (the first truthy approval latches; subsequent falsy
+     * values are ignored). The gate has no graceful terminal-state behavior
+     * for the approver itself.
+     */
+    approver?: Node<unknown>;
+    /** Latch — first truthy approval opens permanently; `close()` becomes no-op. */
+    onceOnly?: boolean;
+    meta?: Record<string, unknown>;
+    handlerVersion?: {
+        id: string;
+        version: string | number;
+    };
+}
+interface GateController<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>;
+    readonly droppedCount: Node<number>;
+    readonly decisions: ReactiveLogBundle<Decision<T>>;
+    readonly audit: ReactiveLogBundle<Decision<T>>;
+    approve(count?: number): void;
+    reject(count?: number): void;
+    modify(fn: (value: T, index: number, pending: readonly T[]) => T, count?: number): void;
+    open(): void;
+    close(): void;
+}
+/**
+ * Terminal-cause discriminator for the {@link PipelineGraph.catch} recovery
+ * handler. Tier 1.6.3 status-enum migration: was `{ kind: "complete" | "error" }`
+ * pre-1.0; aligned with the canonical lifecycle enum
+ * (`status: "running" | "completed" | "errored" | "cancelled"`). The variant
+ * structure is preserved — `errored` still carries `error: unknown` and
+ * `completed` carries no payload.
+ */
+type TerminalCause = {
+    kind: "errored";
+    error: unknown;
+} | {
+    kind: "completed";
+};
+interface CatchOptions<_T> {
+    /**
+     * Which terminal cause to recover. Default `"errored"` (Tier 1.6.3 rename
+     * of `"error"`). `"completed"` recovers COMPLETE; `"terminal"` recovers
+     * either. Aligns with the canonical lifecycle enum that
+     * {@link TerminalCause.kind} now uses.
+     */
+    on?: "errored" | "completed" | "terminal";
+    completeWhenDepsComplete?: boolean;
+    meta?: Record<string, unknown>;
+    handlerVersion?: {
+        id: string;
+        version: string | number;
+    };
+}
+interface ClassifyResult<TTag extends string, T> {
+    readonly tag: TTag | "error";
+    readonly value: T;
+    readonly error?: unknown;
+}
+declare class PipelineGraph extends Graph {
+    /**
+     * Register a workflow task (`node` + auto-add). String deps resolve via
+     * `this.resolve(path)`; Node deps via {@link Graph.nameOf} O(1) lookup.
+     *
+     * `run` receives `(data: readonly unknown[], ctx)` — the snapshot of latest
+     * values per dep (same shape as the old `DerivedFn` sugar).
+     */
+    task<T>(name: string, run: (data: readonly unknown[], ctx: {
+        prevData: readonly unknown[];
+    }) => T | undefined | null, opts?: {
+        deps?: ReadonlyArray<StepRef>;
+        meta?: Record<string, unknown>;
+    }): Node<T>;
+    classify<TTag extends string, T>(name: string, source: StepRef, tagger: (value: T) => TTag, opts?: {
+        meta?: Record<string, unknown>;
+    }): Node<ClassifyResult<TTag, T>>;
+    combine<R extends Record<string, StepRef>>(name: string, deps: R, opts?: {
+        meta?: Record<string, unknown>;
+    }): Node<{
+        [K in keyof R]: unknown;
+    }>;
+    approvalGate<T>(name: string, source: StepRef, opts?: GateOptions<T>): GateController<T>;
+    /**
+     * Reactive approval step: passes items through when `approver` is truthy;
+     * holds at most one pending item (maxPending: 1) when falsy. A thin alias
+     * over `approvalGate({ approver, maxPending: 1 })` — use `approvalGate()`
+     * directly for finer control (maxPending, onceOnly, manual approve/reject).
+     */
+    approval<T>(name: string, source: StepRef, approver: Node<unknown>, opts?: Omit<GateOptions<T>, "approver" | "maxPending">): GateController<T>;
+    catch<T>(name: string, source: StepRef, recover: (cause: TerminalCause, actions: NodeActions) => T, opts?: CatchOptions<T>): Node<T>;
+    private _resolveStep;
+}
+/** Factory wrapper — `pipelineGraph(name, opts?)`. Equivalent to `new PipelineGraph(name, opts)`. */
+declare function pipelineGraph(name: string, opts?: GraphOptions): PipelineGraph;
+
+export { type CatchOptions as C, type Decision as D, type GateController as G, PipelineGraph as P, type StepRef as S, type TerminalCause as T, type ClassifyResult as a, type DecisionAction as b, type GateOptions as c, decisionKeyOf as d, pipelineGraph as p };

package/dist/pipeline-graph-DXCwY9vG.d.ts

@@ -0,0 +1,145 @@
+import { Node, NodeActions } from '@graphrefly/pure-ts/core';
+import { ReactiveLogBundle } from '@graphrefly/pure-ts/extra';
+import { Graph, GraphOptions } from '@graphrefly/pure-ts/graph';
+import { BaseAuditRecord } from './base/mutation/index.js';
+
+/**
+ * PipelineGraph subclass (Wave A.1 Unit 1 — locked 2026-04-24).
+ *
+ * Specialized {@link Graph} that hosts workflow-DAG sugar methods:
+ * `task` / `classify` / `combine` / `approval` / `approvalGate` / `catch`.
+ * The legacy `pipeline` / `task` / `branch` / `join` / `subPipeline` /
+ * `approval` / `loop` / `onFailure` factories from {@link ./index} continue
+ * to work for migration ease; new code should prefer methods on this class.
+ *
+ * **Tier 2.3 rename:** the prior `gate(...)` method is now `approvalGate(...)`,
+ * disambiguating it from the other gate-family primitives (`budgetGate` for
+ * numeric constraints, `valve` for boolean switching, `policyGate` for ABAC
+ * rules). The "gating dimension" here is **human judgment**.
+ *
+ * Construction: `pipelineGraph(name, opts?)` or `new PipelineGraph(name, opts)`.
+ */
+
+type StepRef = string | Node<unknown>;
+type DecisionAction = "approve" | "reject" | "modify" | "drop" | "open" | "close" | "teardown";
+interface Decision<T = unknown> extends BaseAuditRecord {
+    readonly action: DecisionAction;
+    readonly count?: number;
+    readonly items?: readonly T[];
+    readonly unflushed?: number;
+}
+/** Recommended `keyOf` for keyed-storage adapters (Audit 2 #7). */
+declare const decisionKeyOf: <T>(d: Decision<T>) => string;
+interface GateOptions<_T = unknown> {
+    /** Bounded default 1000 (Audit 2 cross-cutting). `Infinity` is opt-in. */
+    maxPending?: number;
+    startOpen?: boolean;
+    /**
+     * Reactive auto-approve: gate's `latestIsOpen` mirrors this node's truthy
+     * value. False→true transition drains the pending queue.
+     *
+     * **`COMPLETE` / `ERROR` on the approver are silently ignored** — the gate
+     * stays in its current state. For permanent-open latching, use
+     * `onceOnly: true` (the first truthy approval latches; subsequent falsy
+     * values are ignored). The gate has no graceful terminal-state behavior
+     * for the approver itself.
+     */
+    approver?: Node<unknown>;
+    /** Latch — first truthy approval opens permanently; `close()` becomes no-op. */
+    onceOnly?: boolean;
+    meta?: Record<string, unknown>;
+    handlerVersion?: {
+        id: string;
+        version: string | number;
+    };
+}
+interface GateController<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>;
+    readonly droppedCount: Node<number>;
+    readonly decisions: ReactiveLogBundle<Decision<T>>;
+    readonly audit: ReactiveLogBundle<Decision<T>>;
+    approve(count?: number): void;
+    reject(count?: number): void;
+    modify(fn: (value: T, index: number, pending: readonly T[]) => T, count?: number): void;
+    open(): void;
+    close(): void;
+}
+/**
+ * Terminal-cause discriminator for the {@link PipelineGraph.catch} recovery
+ * handler. Tier 1.6.3 status-enum migration: was `{ kind: "complete" | "error" }`
+ * pre-1.0; aligned with the canonical lifecycle enum
+ * (`status: "running" | "completed" | "errored" | "cancelled"`). The variant
+ * structure is preserved — `errored` still carries `error: unknown` and
+ * `completed` carries no payload.
+ */
+type TerminalCause = {
+    kind: "errored";
+    error: unknown;
+} | {
+    kind: "completed";
+};
+interface CatchOptions<_T> {
+    /**
+     * Which terminal cause to recover. Default `"errored"` (Tier 1.6.3 rename
+     * of `"error"`). `"completed"` recovers COMPLETE; `"terminal"` recovers
+     * either. Aligns with the canonical lifecycle enum that
+     * {@link TerminalCause.kind} now uses.
+     */
+    on?: "errored" | "completed" | "terminal";
+    completeWhenDepsComplete?: boolean;
+    meta?: Record<string, unknown>;
+    handlerVersion?: {
+        id: string;
+        version: string | number;
+    };
+}
+interface ClassifyResult<TTag extends string, T> {
+    readonly tag: TTag | "error";
+    readonly value: T;
+    readonly error?: unknown;
+}
+declare class PipelineGraph extends Graph {
+    /**
+     * Register a workflow task (`node` + auto-add). String deps resolve via
+     * `this.resolve(path)`; Node deps via {@link Graph.nameOf} O(1) lookup.
+     *
+     * `run` receives `(data: readonly unknown[], ctx)` — the snapshot of latest
+     * values per dep (same shape as the old `DerivedFn` sugar).
+     */
+    task<T>(name: string, run: (data: readonly unknown[], ctx: {
+        prevData: readonly unknown[];
+    }) => T | undefined | null, opts?: {
+        deps?: ReadonlyArray<StepRef>;
+        meta?: Record<string, unknown>;
+    }): Node<T>;
+    classify<TTag extends string, T>(name: string, source: StepRef, tagger: (value: T) => TTag, opts?: {
+        meta?: Record<string, unknown>;
+    }): Node<ClassifyResult<TTag, T>>;
+    combine<R extends Record<string, StepRef>>(name: string, deps: R, opts?: {
+        meta?: Record<string, unknown>;
+    }): Node<{
+        [K in keyof R]: unknown;
+    }>;
+    approvalGate<T>(name: string, source: StepRef, opts?: GateOptions<T>): GateController<T>;
+    /**
+     * Reactive approval step: passes items through when `approver` is truthy;
+     * holds at most one pending item (maxPending: 1) when falsy. A thin alias
+     * over `approvalGate({ approver, maxPending: 1 })` — use `approvalGate()`
+     * directly for finer control (maxPending, onceOnly, manual approve/reject).
+     */
+    approval<T>(name: string, source: StepRef, approver: Node<unknown>, opts?: Omit<GateOptions<T>, "approver" | "maxPending">): GateController<T>;
+    catch<T>(name: string, source: StepRef, recover: (cause: TerminalCause, actions: NodeActions) => T, opts?: CatchOptions<T>): Node<T>;
+    private _resolveStep;
+}
+/** Factory wrapper — `pipelineGraph(name, opts?)`. Equivalent to `new PipelineGraph(name, opts)`. */
+declare function pipelineGraph(name: string, opts?: GraphOptions): PipelineGraph;
+
+export { type CatchOptions as C, type Decision as D, type GateController as G, PipelineGraph as P, type StepRef as S, type TerminalCause as T, type ClassifyResult as a, type DecisionAction as b, type GateOptions as c, decisionKeyOf as d, pipelineGraph as p };