@glubean/runner 0.4.1 → 0.7.0

package/dist/workflow/execute.d.ts

@@ -0,0 +1,267 @@
+/**
+ * @module workflow/execute
+ *
+ * vNext `workflow` EXECUTOR — the per-node runtime harness.
+ *
+ * GOVERNING PRINCIPLE (2026-06-09): no backward compatibility. Where `runFlow`
+ * (`contract-core.ts`) and the `test()` harness (`packages/runner`) diverge, this
+ * executor picks the ONE rule decided in the proposal §17 self-consistency corpus
+ * and every node obeys it. See `internal/40-discovery/proposals/contract-workflow-vnext.md`.
+ *
+ * This slice (S2.0) builds the foundation every later node type stands on:
+ *   - a per-node derived child ctx (`makeNodeScope`) that attributes evidence to
+ *     the node, tracks its pass/fail + structured-evidence emission, and — after
+ *     the node settles — QUARANTINES any late evidence the body still emits (§17 #12);
+ *   - `runNode`: brackets the node with `workflow:node_start` / `:node_end`
+ *     events, runs the body under a per-node `AbortController`, and enforces a
+ *     TERMINAL per-node timeout (no retry; §17 #4) that aborts the node (§17 #12).
+ *
+ * On top of it: `runWorkflow` walks setup → nodes → teardown (S2.1); `runBranch`
+ * runs only the taken side (S2.4a, §17 #6); `runPollNode` is the bounded
+ * poll-until with per-attempt quarantine (S2.4b, §17 #3). Control-flow nodes
+ * (branch/poll) own their bracket/bounds and are dispatched by `runNodeList`,
+ * not `runNode`; remaining reserved kinds throw "not implemented yet".
+ */
+import type { TestContext, ProjectionGrade, StaticGrade, Workflow, WorkflowContext, WorkflowNode, ExtractedPredicate } from "@glubean/sdk";
+/**
+ * Human-readable label for a declarative expect item (phase4 §7.2) — derived
+ * from the extracted predicate, never authored, so it cannot drift from what
+ * actually evaluates. Used for assertion-event messages.
+ */
+export declare function predicateLabel(p: ExtractedPredicate): string;
+/**
+ * Host integration point (used by @glubean/runner's http hooks): the ctx that
+ * observability emitted DURING a workflow node body should be attributed to,
+ * or undefined outside any workflow node.
+ */
+export declare function __activeWorkflowNodeCtx(): TestContext | undefined;
+/**
+ * Per-node boundary events ride the generic `ctx.event` channel for this slice
+ * (zero runner-package change — they reach the timeline as namespaced
+ * `GlubeanEvent`s). S2.5 decides whether to promote them to first-class
+ * `node_start` / `node_end` event kinds for richer Cloud rendering.
+ */
+export declare const NODE_START_EVENT = "workflow:node_start";
+export declare const NODE_END_EVENT = "workflow:node_end";
+export type NodeStatus = "passed" | "failed" | "skipped";
+export interface NodeStartEventData {
+    nodeId: string;
+    kind: WorkflowNode["kind"];
+    name: string;
+    /** Set on a retrying node (§17 #7): which attempt this bracket is (1-based). */
+    attempt?: number;
+    /** Set on a retrying node (§17 #7): the configured total attempts. */
+    attempts?: number;
+    [k: string]: unknown;
+}
+export interface NodeEndEventData {
+    nodeId: string;
+    kind: WorkflowNode["kind"];
+    name: string;
+    status: NodeStatus;
+    /** Runtime grade after evidence promotion (§17 #10). */
+    grade: ProjectionGrade;
+    durationMs: number;
+    error?: string;
+    /** Set on a retrying node (§17 #7): which attempt this bracket is (1-based). */
+    attempt?: number;
+    /** Set on a retrying node (§17 #7): the configured total attempts. */
+    attempts?: number;
+    [k: string]: unknown;
+}
+/** A node exceeded its `timeout`. TERMINAL — the node is not retried (§17 #4). */
+export declare class NodeTimeoutError extends Error {
+    readonly nodeId: string;
+    readonly timeoutMs: number;
+    constructor(nodeId: string, timeoutMs: number);
+}
+/**
+ * A workflow phase (setup, or a node) FAILED via soft assertions/validation —
+ * nothing was thrown, so `runNode` has no `error` to report. The executor
+ * synthesizes this as the run's `cause` so teardown + the result carry a
+ * non-empty failure even for the pure soft-failure path (codex S2.1 P2).
+ */
+export declare class WorkflowPhaseFailedError extends Error {
+    readonly workflowId: string;
+    readonly phase: string;
+    constructor(workflowId: string, phase: string);
+}
+/**
+ * A `compute` node returned a thenable — an async fn, or (the case the builder
+ * can't catch) a sync fn that returns a Promise. compute MUST be synchronous and
+ * I/O-free; the executor FAILS the node rather than committing the Promise as
+ * state, so async/I/O can't masquerade as a `full` pure transform (§17 #11).
+ */
+export declare class ComputeAsyncError extends Error {
+    readonly nodeId: string;
+    constructor(nodeId: string);
+}
+/**
+ * A per-node child `TestContext` (+ `signal`). Sibling to `quarantinedCtx`
+ * (`contract-flow-poll.ts`): same "derive with `Object.create`, override the
+ * pass/fail APIs, pass observability through" technique, different policy —
+ * evidence emits IMMEDIATELY while the node is live, then is DROPPED once the
+ * node settles (`seal()`), so a body that ignores `signal` and keeps running
+ * after a timeout/failure cannot leak late evidence into the run (§17 #12).
+ *
+ * It also records, for the executor: whether any assertion/validate/fail FAILED
+ * (the node's pass/fail decision, §17 #5) and whether the node emitted ≥1 piece
+ * of STRUCTURED evidence — protocol `trace`, `assertion`, `schema_validation`,
+ * `metric` — which promotes a statically-`opaque` node to `trace` (§17 #10).
+ * Plain `log` / `warn` / `action` / `event` do NOT count as structured evidence.
+ */
+export interface NodeScope {
+    readonly ctx: WorkflowContext;
+    /** True iff some assertion / error-severity validation / `fail()` recorded a failure (§17 #5). */
+    hasFailure(): boolean;
+    /** True iff the node emitted ≥1 structured evidence (drives opaque→trace, §17 #10). */
+    emittedStructuredEvidence(): boolean;
+    /** Settle the node: subsequent emissions are quarantined (dropped) (§17 #12). */
+    seal(): void;
+}
+export declare function makeNodeScope(base: TestContext, signal: AbortSignal): NodeScope;
+/**
+ * Runtime grade = the static floor, promoted from `opaque` → `trace` iff the node
+ * emitted structured evidence at run time (§17 #10). `full` / `partial` are never
+ * promoted (they are already as good as or better than `trace`).
+ */
+export declare function promoteGrade(staticGrade: StaticGrade, scope: NodeScope): ProjectionGrade;
+export interface NodeRunResult {
+    status: NodeStatus;
+    /** Committed state. On failure this is the PRIOR state — a failed node does not
+     * commit its return (§17 #13). On success: the body's return, or the prior state
+     * when the body returned void/undefined (§17 #2).
+     *
+     * §17 #14: state is treated as IMMUTABLE, but the executor does NOT clone it
+     * (perf). A body that mutates the LIVE state object in place takes effect
+     * IMMEDIATELY and is NOT isolated or rolled back on failure/timeout — commit-on-
+     * success governs the RETURN VALUE, not in-place writes. A node needing rollback
+     * safety MUST return a new object instead of mutating in place. */
+    state: unknown;
+    /** Runtime grade after evidence promotion (§17 #10). */
+    grade: ProjectionGrade;
+    /** The error that failed the node (throw / timeout / fatal), if any. */
+    error?: unknown;
+}
+/** Attempt label for a retrying node's events (§17 #7): `n` of `of`. */
+export interface AttemptInfo {
+    n: number;
+    of: number;
+}
+export interface RunNodeOptions {
+    /** Static floor grade for this node (from the projector); promoted per §17 #10. */
+    staticGrade: StaticGrade;
+    /** Per-node terminal timeout (ms). Omit / non-finite = unbounded (§17 #4). */
+    timeoutMs?: number;
+    /** Stamp this run's node_start/node_end events as attempt n of of (§17 #7). */
+    attempt?: AttemptInfo;
+    /**
+     * Called with the settled verdict JUST BEFORE this run's node_end event is
+     * emitted — the retry wrapper uses it to flush the terminal attempt's buffered
+     * assert/validate evidence INSIDE the attempt bracket, so timeline grouping
+     * holds (codex S2.4c R2 P2). Runs after the scope is sealed; anything it emits
+     * goes straight to the base ctx.
+     */
+    beforeNodeEnd?: (status: NodeStatus, error?: unknown) => void;
+    /**
+     * Adjust the runtime grade before it is reported — applied to BOTH the
+     * node_end event and the returned result, so they always agree. The retry
+     * wrapper uses it to tie opaque→trace promotion to HOST-VISIBLE evidence
+     * across attempts: the scope's structured flag cannot distinguish
+     * pass-through traces from buffered (possibly-discarded) assert counts, and
+     * an earlier attempt's promotion must survive into the terminal bracket
+     * (§17 #10; codex S2.5 R5 P2).
+     */
+    adjustGrade?: (computed: ProjectionGrade, info: {
+        structured: boolean;
+        status: NodeStatus;
+        error?: unknown;
+    }) => ProjectionGrade;
+}
+/**
+ * Run ONE node: bracket it with node_start/node_end, execute its body under a
+ * per-node child ctx + `AbortController`, enforce a TERMINAL timeout (§17 #4),
+ * and quarantine any late evidence after the node settles (§17 #12). Returns the
+ * verdict + the state to carry forward (commit-on-success, §17 #13).
+ */
+export declare function runNode(base: TestContext, node: WorkflowNode, state: unknown, opts: RunNodeOptions): Promise<NodeRunResult>;
+export interface WorkflowNodeOutcome {
+    id: string;
+    status: NodeStatus;
+    /** Runtime grade after evidence promotion (§17 #10). */
+    grade: ProjectionGrade;
+}
+export interface WorkflowRunResult {
+    /** `skipped` if the workflow opts out (meta.skip) or a node called `ctx.skip()`;
+     * `failed` if setup threw / soft-failed or a node failed; else `passed`. */
+    status: "passed" | "failed" | "skipped";
+    /** Last COMMITTED state — passed nodes commit, failed/skipped do not (§17 #13). */
+    state: unknown;
+    /** Per-node outcomes, authored order. */
+    nodes: WorkflowNodeOutcome[];
+    /** The primary cause that failed the run (the one teardown sees), if any. */
+    error?: unknown;
+    /** Why the run skipped: the user-authored ctx.skip(reason) (setup/node/
+     * branch-predicate/poll), or `meta.skip`. Only set when status === "skipped"
+     * (codex S2.5 R6 — the host's skipped status must keep the authored reason). */
+    skipReason?: string;
+}
+/** Branch-family decision event (§17 #9 "branch decision") — rides the generic
+ * ctx.event channel like node_start/node_end; the runner unwraps it into a
+ * first-class `branch_decision` timeline event. */
+export declare const BRANCH_DECISION_EVENT = "workflow:branch_decision";
+export interface BranchDecisionEventData {
+    nodeId: string;
+    mode: "predicate" | "value";
+    takenIndex: number | "default";
+    takenLabel?: string;
+    [k: string]: unknown;
+}
+/** Per-attempt timeline event (§17 #9 "poll attempt timeline"). Rides the generic
+ * `ctx.event` channel like node_start/node_end; emitted through the NODE scope, so
+ * it is observability (never promotes the grade) and is quarantined after seal. */
+export declare const POLL_ATTEMPT_EVENT = "workflow:poll_attempt";
+export interface PollAttemptEventData {
+    nodeId: string;
+    attempt: number;
+    /** `satisfied` — until held; `probe` — until not yet; `failed` — the attempt
+     * threw / exceeded its budget (the poll node fails). */
+    outcome: "satisfied" | "probe" | "failed";
+    durationMs: number;
+    /**
+     * Inbound polls only (design §9.4): the matcher's classification for this
+     * attempt — `matched`, the probe attributions (`no-delivery` /
+     * `type-mismatch` / `correlation-mismatch` / `schema-mismatch`), or the
+     * fail class that ended the poll. Diagnosis, never verdict.
+     */
+    classification?: string;
+    /**
+     * Inbound polls, satisfied attempts only: `receivedAt − pollStart` of the
+     * matched delivery (ms) — the measured side of `expect.within` (§9.4a #5).
+     * NEGATIVE when the delivery arrived before the poll started (allowed
+     * evidence, §9.4a #3).
+     */
+    withinDeltaMs?: number;
+    [k: string]: unknown;
+}
+/**
+ * A fail-class inbound classification (inbound-contract-design §9.4 rows 1–3):
+ * a property of the delivery CHANNEL (forgery / replay / non-JSON), never
+ * noise — it fails the poll node even when a later delivery in the same
+ * snapshot would have matched (§9.4a #4, first terminal wins).
+ */
+export declare class InboundDeliveryFailError extends Error {
+    readonly classification: "signature-invalid" | "stale" | "unparseable";
+    constructor(classification: "signature-invalid" | "stale" | "unparseable", nodeId: string, detail?: string);
+}
+/**
+ * Execute a built `Workflow` against a host `TestContext`. setup runs INSIDE the
+ * protected region so teardown ALWAYS runs — even when setup throws (§17 #1, the
+ * opposite of runFlow). Nodes run in authored order with fail-stop: a non-passed
+ * node stops the rest (emitted `skipped`). A node `ctx.skip()` skips the whole
+ * workflow (mirrors the runner's whole-test skip); `meta.skip` opts the workflow
+ * out entirely (discoverable, never executed). teardown sees the last committed
+ * state + the failing cause; a teardown that throws is logged and never masks it.
+ */
+export declare function runWorkflow<State = unknown>(wf: Workflow<State>, baseCtx: TestContext): Promise<WorkflowRunResult>;
+//# sourceMappingURL=execute.d.ts.map

package/dist/workflow/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/workflow/execute.ts"],"names":[],"mappings":"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"}