@glubean/runner 0.5.0 → 0.8.0

package/dist/runner-resolve.js

@@ -0,0 +1,264 @@
+/**
+ * Shared runner-resolution internals — the delicate "where does the runner
+ * harness live + how do we spawn it" code, factored out of `executor.ts` so the
+ * test harness (`TestExecutor`) AND the load harness (`runLoadFileInSubprocess`)
+ * resolve the SAME project-local runner the SAME way.
+ *
+ * Three reused seams:
+ *  - `resolveRunnerRoot` — the **dual-package hazard fix**: prefer the project's
+ *    own `@glubean/runner` dist (so the spawned harness + the user file co-resolve
+ *    the project's `@glubean/sdk`), fall back to the bundled copy with a warning.
+ *    **Most delicate code in the package — change with care.**
+ *  - `resolveTsxPath` — locate the tsx CLI to transform the user's TypeScript.
+ *  - `prepareZeroProject` — scratch-mode (no node_modules) `--import` register +
+ *    `GLUBEAN_VENDORED_ROOT` redirect + temp package.json, with a cleanup closure.
+ *
+ * Internal to `@glubean/runner` — not part of the public `index.ts` surface.
+ */
+import { existsSync, unlinkSync, readFileSync, writeFileSync, realpathSync } from "node:fs";
+import { dirname, resolve, join } from "node:path";
+import { createRequire } from "node:module";
+// ── Project-local runner resolution (Plan 1) ────────────────────────────────
+/**
+ * Walk up from a starting file path looking for the first package.json
+ * whose `name` field matches `expectedName`. Layout-independent — works
+ * regardless of dist/ depth.
+ *
+ * Returns the realpath of the package root, or undefined if not found.
+ */
+function findPackageRoot(startFile, expectedName) {
+    let dir = dirname(startFile);
+    for (let i = 0; i < 16; i++) {
+        const candidate = resolve(dir, "package.json");
+        if (existsSync(candidate)) {
+            try {
+                const pkg = JSON.parse(readFileSync(candidate, "utf-8"));
+                if (pkg?.name === expectedName) {
+                    try {
+                        return realpathSync(dir);
+                    }
+                    catch {
+                        return dir;
+                    }
+                }
+            }
+            catch {
+                // corrupt / non-json; keep walking
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+    return undefined;
+}
+/**
+ * Compare two version strings (numeric major.minor.patch). Returns true
+ * if `a < b`. Tolerant of missing fields and non-numeric tails.
+ */
+function semverLt(a, b) {
+    const parse = (s) => s.split(/[.\-+]/).slice(0, 3).map((p) => parseInt(p, 10) || 0);
+    const [aMajor, aMinor, aPatch] = parse(a);
+    const [bMajor, bMinor, bPatch] = parse(b);
+    if (aMajor !== bMajor)
+        return aMajor < bMajor;
+    if (aMinor !== bMinor)
+        return aMinor < bMinor;
+    return aPatch < bPatch;
+}
+/**
+ * Resolve the runner dist/ directory + package root.
+ *
+ * Preference: project-local `@glubean/runner` (found from `projectCwd`'s
+ * `node_modules` chain). Fallback: bundled (the consumer's own runner copy).
+ *
+ * Returns warnings to be yielded as `{ type: "warning", ... }` events at
+ * the start of every `run()` call. Always emits a warning when falling
+ * back to bundled (so users see why "configure() values..." errors may
+ * appear in a misconfigured project).
+ */
+export function resolveRunnerRoot(projectCwd, bundledDistDir, bundledPkgRoot) {
+    const warnings = [];
+    try {
+        // Root `createRequire` at a stub path INSIDE the project cwd — not
+        // at `import.meta.url` (the workspace executor file). If we use the
+        // workspace URL, Node's resolver returns the workspace's own
+        // `@glubean/runner` via package self-reference (the `exports` field
+        // points back at itself), regardless of `paths: [projectCwd]`. With
+        // a cwd-rooted stub there's no self-reference and Node walks the
+        // project's node_modules chain correctly.
+        const req = createRequire(resolve(projectCwd, "__glubean_resolve_stub__.js"));
+        const mainEntry = req.resolve("@glubean/runner");
+        const pkgRoot = findPackageRoot(mainEntry, "@glubean/runner");
+        if (!pkgRoot) {
+            warnings.push({
+                code: "runner_pkg_root_not_found",
+                message: `Could not locate @glubean/runner's package.json above ${mainEntry}; using bundled runner.`,
+            });
+            return {
+                distDir: bundledDistDir,
+                pkgRoot: bundledPkgRoot,
+                source: "bundled",
+                pendingWarnings: warnings,
+            };
+        }
+        const projectDistDir = dirname(mainEntry);
+        if (!existsSync(resolve(projectDistDir, "harness.js"))) {
+            warnings.push({
+                code: "runner_fallback_no_dist",
+                message: `Project @glubean/runner at ${pkgRoot} has no built harness.js (looked in ${projectDistDir}); using bundled runner.`,
+            });
+            return {
+                distDir: bundledDistDir,
+                pkgRoot: bundledPkgRoot,
+                source: "bundled",
+                pendingWarnings: warnings,
+            };
+        }
+        let version;
+        let projectProtocol;
+        try {
+            const pkg = JSON.parse(readFileSync(resolve(pkgRoot, "package.json"), "utf-8"));
+            version = pkg.version;
+            projectProtocol = pkg.glubeanRunnerProtocol;
+        }
+        catch {
+            // best effort
+        }
+        // Min-protocol check: emit a warning if project's protocol is older
+        // than what this consumer needs, but DON'T fall back. Using project-
+        // local runner with an old protocol just means some new env channels
+        // may be silently ignored. Falling back to bundled when the project
+        // has its own SDK would re-introduce the dual-package hazard the
+        // whole fix exists to prevent. Project-local wins; missing features
+        // are surfaced via warning so the user knows to upgrade.
+        try {
+            const bundledPkg = JSON.parse(readFileSync(resolve(bundledPkgRoot, "package.json"), "utf-8"));
+            const bundledMin = bundledPkg.glubeanRunnerProtocolMinimum;
+            if (bundledMin && (!projectProtocol || semverLt(projectProtocol, bundledMin))) {
+                warnings.push({
+                    code: "runner_protocol_old",
+                    message: `Project @glubean/runner ${version ?? "<unknown>"} declares glubeanRunnerProtocol=${projectProtocol ?? "<unset>"}, ` +
+                        `but this consumer was built for >= ${bundledMin}. ` +
+                        `Using project-local runner anyway; some newer features may be silently unavailable. ` +
+                        `Run \`npm i -D @glubean/runner@latest\` to silence.`,
+                });
+            }
+        }
+        catch {
+            // bundled pkg.json unreadable — skip the check; happens in test fixtures
+        }
+        return {
+            distDir: projectDistDir,
+            pkgRoot,
+            source: "project",
+            resolvedFrom: mainEntry,
+            version,
+            pendingWarnings: warnings,
+        };
+    }
+    catch {
+        // No project-local runner installed. Plan 1 AC4: emit a warning whenever
+        // bundled is used so users see why version-skew "configure() values..."
+        // errors may appear.
+        warnings.push({
+            code: "runner_fallback_no_project",
+            message: `No project-local @glubean/runner found at ${projectCwd}; using consumer's bundled runner. ` +
+                `If your tests import @glubean/sdk from this project, install runner to keep module identity ` +
+                `consistent: \`npm i -D @glubean/runner\`.`,
+        });
+        return {
+            distDir: bundledDistDir,
+            pkgRoot: bundledPkgRoot,
+            source: "bundled",
+            pendingWarnings: warnings,
+        };
+    }
+}
+// ── End of project-local resolution ─────────────────────────────────────────
+// ── tsx path resolution ─────────────────────────────────────────────────────
+let _tsxPath;
+/** Resolve the tsx CLI entry used to transform the user's TypeScript in the
+ *  spawned harness subprocess. Cached after the first lookup. */
+export function resolveTsxPath() {
+    if (_tsxPath)
+        return _tsxPath;
+    const req = createRequire(import.meta.url);
+    _tsxPath = resolve(dirname(req.resolve("tsx/package.json")), "dist/cli.mjs");
+    return _tsxPath;
+}
+/**
+ * Set up zero-project (scratch) mode for a spawn rooted at `cwd`: when the cwd
+ * has no `@glubean/sdk` in node_modules, redirect the user file's `@glubean/*`
+ * imports to the resolved runner's vendored copy (via the register hook +
+ * `GLUBEAN_VENDORED_ROOT`) and ensure a `"type":"module"` package.json so the
+ * `.ts` file loads as ESM. When the cwd already has `@glubean/sdk`, this is a
+ * no-op (empty args/env, no-op cleanup).
+ *
+ * Pure w.r.t. instance state — both `TestExecutor` and the load spawn call it
+ * and own the returned `tsxArgs`/`env`/`cleanup`.
+ */
+export function prepareZeroProject(cwd, runnerDistDir, runnerPkgRoot) {
+    if (existsSync(join(cwd, "node_modules", "@glubean", "sdk"))) {
+        return { tsxArgs: [], env: {}, cleanup: () => { } };
+    }
+    // Plan 1: relocate zero-project subpaths with the harness — if harness moved
+    // to project-local runner, register + vendored root must move too, otherwise
+    // scratch mode mixes project harness with bundled @glubean/* resolution.
+    const registerPath = resolve(runnerDistDir, "zero-project-register.mjs");
+    const tsxArgs = ["--import", registerPath];
+    // Use the runner package root as the synthetic parent. From there, Node's
+    // normal package resolution finds sibling @glubean/* packages in both
+    // workspace installs (packages/runner/node_modules) and published installs
+    // (ancestor node_modules).
+    const env = { GLUBEAN_VENDORED_ROOT: runnerPkgRoot };
+    const pkgPath = join(cwd, "package.json");
+    let tempPackageJson = false;
+    let originalPackageJson;
+    if (!existsSync(pkgPath)) {
+        try {
+            writeFileSync(pkgPath, '{"type":"module"}\n');
+            tempPackageJson = "created";
+        }
+        catch {
+            // Non-critical
+        }
+    }
+    else {
+        try {
+            const original = readFileSync(pkgPath, "utf-8");
+            const pkg = JSON.parse(original);
+            if (pkg.type !== "module") {
+                originalPackageJson = original;
+                pkg.type = "module";
+                writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+                tempPackageJson = "patched";
+            }
+        }
+        catch {
+            // Non-critical
+        }
+    }
+    return {
+        tsxArgs,
+        env,
+        cleanup() {
+            if (!tempPackageJson)
+                return;
+            try {
+                if (tempPackageJson === "created") {
+                    unlinkSync(pkgPath);
+                }
+                else if (tempPackageJson === "patched" && originalPackageJson) {
+                    writeFileSync(pkgPath, originalPackageJson);
+                }
+            }
+            catch {
+                // Non-critical
+            }
+            tempPackageJson = false;
+        },
+    };
+}
+//# sourceMappingURL=runner-resolve.js.map

package/dist/runner-resolve.js.map

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

package/dist/workflow/event-timeline.d.ts

@@ -0,0 +1,3 @@
+import type { GlubeanEvent } from "@glubean/sdk";
+export declare function workflowEventToTimeline(ev: GlubeanEvent): Record<string, unknown> | null;
+//# sourceMappingURL=event-timeline.d.ts.map

package/dist/workflow/event-timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-timeline.d.ts","sourceRoot":"","sources":["../../src/workflow/event-timeline.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAYjD,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAqExF"}

package/dist/workflow/event-timeline.js

@@ -0,0 +1,72 @@
+import { NODE_START_EVENT, NODE_END_EVENT, POLL_ATTEMPT_EVENT, BRANCH_DECISION_EVENT, } from "./execute.js";
+const NODE_STATUSES = new Set(["passed", "failed", "skipped"]);
+const NODE_GRADES = new Set(["full", "partial", "trace", "opaque"]);
+const POLL_OUTCOMES = new Set(["satisfied", "probe", "failed"]);
+export function workflowEventToTimeline(ev) {
+    if (ev.type !== NODE_START_EVENT &&
+        ev.type !== NODE_END_EVENT &&
+        ev.type !== POLL_ATTEMPT_EVENT &&
+        ev.type !== BRANCH_DECISION_EVENT) {
+        return null;
+    }
+    const d = ev.data;
+    if (!d || typeof d.nodeId !== "string")
+        return null;
+    const attemptFields = {
+        ...(typeof d.attempt === "number" ? { attempt: d.attempt } : {}),
+        ...(typeof d.attempts === "number" ? { attempts: d.attempts } : {}),
+    };
+    if (ev.type === NODE_START_EVENT) {
+        return {
+            type: "node_start",
+            nodeId: d.nodeId,
+            kind: typeof d.kind === "string" ? d.kind : "unknown",
+            name: typeof d.name === "string" ? d.name : d.nodeId,
+            ...attemptFields,
+        };
+    }
+    if (ev.type === NODE_END_EVENT) {
+        if (typeof d.status !== "string" || !NODE_STATUSES.has(d.status))
+            return null;
+        if (typeof d.grade !== "string" || !NODE_GRADES.has(d.grade))
+            return null;
+        return {
+            type: "node_end",
+            nodeId: d.nodeId,
+            kind: typeof d.kind === "string" ? d.kind : "unknown",
+            name: typeof d.name === "string" ? d.name : d.nodeId,
+            status: d.status,
+            grade: d.grade,
+            durationMs: typeof d.durationMs === "number" ? d.durationMs : 0,
+            ...(typeof d.error === "string" ? { error: d.error } : {}),
+            ...attemptFields,
+        };
+    }
+    if (ev.type === POLL_ATTEMPT_EVENT) {
+        if (typeof d.attempt !== "number" ||
+            typeof d.outcome !== "string" ||
+            !POLL_OUTCOMES.has(d.outcome)) {
+            return null;
+        }
+        return {
+            type: "poll_attempt",
+            nodeId: d.nodeId,
+            attempt: d.attempt,
+            outcome: d.outcome,
+            durationMs: typeof d.durationMs === "number" ? d.durationMs : 0,
+        };
+    }
+    // BRANCH_DECISION_EVENT (addendum §9 — branch/switch/route taken case)
+    if ((d.mode !== "predicate" && d.mode !== "value") ||
+        (typeof d.takenIndex !== "number" && d.takenIndex !== "default")) {
+        return null;
+    }
+    return {
+        type: "branch_decision",
+        nodeId: d.nodeId,
+        mode: d.mode,
+        takenIndex: d.takenIndex,
+        ...(typeof d.takenLabel === "string" ? { takenLabel: d.takenLabel } : {}),
+    };
+}
+//# sourceMappingURL=event-timeline.js.map

package/dist/workflow/event-timeline.js.map

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

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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"}