@kernloop/workflows 0.1.0

package/dist/state.d.ts.map

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

package/dist/state.js

@@ -0,0 +1,151 @@
+/**
+ * Run state, checkpoint record shape, and typed engine errors. The state is
+ * deliberately a plain JSON-serializable object validated by zod: a resume
+ * trusts nothing it reads back from storage [CLM-0044] — a checkpoint that
+ * does not parse is a typed failure, never a silent partial resume.
+ */
+import { z } from 'zod';
+import { FindingSchema, TaskContractSchema, VerdictSchema, } from '@kernloop/contracts';
+/**
+ * Where the run is. `main` points at the NEXT main-chain node to execute;
+ * `fanout` points at the next (child, sub-node) pair; `done` is terminal.
+ * The cursor always names work not yet performed, so resuming from a
+ * checkpoint never re-runs a completed node [CLM-0044].
+ */
+export const CursorSchema = z.discriminatedUnion('phase', [
+    z.strictObject({ phase: z.literal('main'), node: z.string().min(1) }),
+    z.strictObject({
+        phase: z.literal('fanout'),
+        childIndex: z.number().int().nonnegative(),
+        sub: z.number().int().nonnegative(),
+    }),
+    z.strictObject({ phase: z.literal('done') }),
+]);
+/** Metered spend attributed to one fan-out child (tokens + usd), #56. */
+export const ChildSpendSchema = z.strictObject({
+    tokens: z.number().nonnegative(),
+    usd: z.number().nonnegative(),
+});
+/**
+ * One fan-out child's honest result. A child that fails mid-implement gets
+ * `error` and no verdict; a child whose quality gate ran gets its Verdict
+ * (pass or fail — a failing verdict is a result, not an engine error). The
+ * `reviewVerdict` is the advisory review gate's verdict (recorded, never
+ * blocking). All shapes aggregate into integrate's input unfiltered.
+ *
+ * `iteration` and `findings` carry the per-child actor-critic loop [CLM-0043]:
+ * a quality reject re-runs implement, folding the gate's findings into the
+ * coder's next attempt, bounded by Kc (and the run budget). They mirror the
+ * run-level `iteration`/`findings` but scope to one child, and are
+ * checkpointed so a resume mid-child-iteration re-runs nothing finished.
+ * `escalated` marks a child that hit the Kc/budget bound still failing — it is
+ * recorded, never re-attempted, and does NOT sink its siblings or the run.
+ */
+export const ChildResultSchema = z.strictObject({
+    child: TaskContractSchema,
+    output: z.unknown().optional(),
+    verdict: VerdictSchema.optional(),
+    reviewVerdict: VerdictSchema.optional(),
+    /** The parsimony Check-layer gate's verdict (#9/#415): at intensity lite it is
+     * advisory (recorded, never blocking, like `reviewVerdict`); at full/ultra a
+     * REJECT drives child re-iteration. Kept in its OWN slot so the parsimony gate
+     * never clobbers the quality `verdict` (the parsimony node runs after both). */
+    parsimonyVerdict: VerdictSchema.optional(),
+    error: z.string().min(1).optional(),
+    /** How many times implement has been re-run for this child (0 on first). */
+    iteration: z.number().int().nonnegative().default(0),
+    /** Gate findings accumulated across this child's iterations, fed to the coder. */
+    findings: z.array(FindingSchema).default([]),
+    /** Set when the child hit the Kc/budget bound still failing (bounded escalation). */
+    escalated: z.boolean().optional(),
+    /**
+     * Metered model spend ATTRIBUTED to this child's sub-chain (#56): the
+     * run-global meter sliced by the SEQUENTIAL child boundary, summed across all
+     * of the child's Kc iterations. Set as the fan-out runs the child when the
+     * composition root injected a `meteredSpend` seam; absent on an unmetered run.
+     * Per-PROCESS, like the meter it reads (#212): a resume re-attributes from the
+     * fresh meter and DROPS any pre-resume spend, so a child finished before a
+     * resume reports none — keeping the sum within the (also per-process) run cost.
+     */
+    spend: ChildSpendSchema.optional(),
+});
+/** One executed node in the run's trace (deterministic order, child-tagged). */
+export const TraceEntrySchema = z.strictObject({
+    seq: z.number().int().positive(),
+    node: z.string().min(1),
+    iteration: z.number().int().nonnegative(),
+    childId: z.string().min(1).optional(),
+});
+/**
+ * The complete serializable state of one run. Self-contained: a checkpoint's
+ * state plus the injected executors is everything a resume needs.
+ */
+export const RunStateSchema = z.strictObject({
+    task: TaskContractSchema,
+    status: z.enum(['running', 'escalated', 'completed']),
+    cursor: CursorSchema,
+    /**
+     * Why an escalated run halted: `vote` (the K vote-iterate bound — resume
+     * re-plans with a fresh K after the human edit [CLM-0043]); `vote-escalation`
+     * (a vote gate ruled `escalate` — a deadlocked panel asking a human, #192 —
+     * distinct from `vote` so an operator tells a deadlock from K-exhaustion;
+     * resume re-plans the same way); or `budget` (the run exceeded its budget in
+     * enforce mode — resume continues from the cursor once the human raises the
+     * budget or re-runs unlimited [CLM-0077]). Absent while running/completed.
+     */
+    haltReason: z.enum(['vote', 'vote-escalation', 'budget']).optional(),
+    /** Vote-iterate count: how many times the rejected edge re-entered plan. */
+    iteration: z.number().int().nonnegative(),
+    /** Last emission per node name — the values that flow along edges. */
+    values: z.record(z.string(), z.unknown()),
+    /** Findings accumulated from rejecting vote Verdicts, fed back to plan. */
+    findings: z.array(FindingSchema),
+    /** Decomposed (plus overlay-added specialist) children, set at fan-out. */
+    children: z.array(TaskContractSchema),
+    /** Per-child results accumulated as the fan-out progresses. */
+    childResults: z.array(ChildResultSchema),
+    trace: z.array(TraceEntrySchema),
+    /**
+     * Largest single-NODE metered spend seen this run (#342). The pre-node budget
+     * guard reserves at least this much so an enforce-mode cap is not overshot by
+     * one node's spend. PERSISTED in the checkpoint, so a resume RESTORES the
+     * learned max — conservative: the prior worst node still bounds the reserve
+     * even though the per-process `spent()` meter restarts. Defaulted so a pre-#342
+     * checkpoint (which lacks the field) resumes cleanly.
+     */
+    observedMaxNodeSpend: ChildSpendSchema.default({ tokens: 0, usd: 0 }),
+});
+/**
+ * One checkpoint row, persisted through the injected store after EVERY node
+ * completion [CLM-0044]: `{runId, seq, node, iteration, state}` where `node`
+ * is the node that just completed and `state` already points past it.
+ */
+export const CheckpointRecordSchema = z.strictObject({
+    runId: z.string().min(1),
+    seq: z.number().int().positive(),
+    node: z.string().min(1),
+    iteration: z.number().int().nonnegative(),
+    state: RunStateSchema,
+    createdAt: z.string().min(1),
+});
+/**
+ * Typed engine failure. Edge-contract failures name the node and the
+ * contract the emission violated [CLM-0042].
+ */
+export class WorkflowError extends Error {
+    code;
+    /** Node involved, when one is. */
+    node;
+    /** Contract violated, for `edge_contract`. */
+    contract;
+    constructor(code, message, details = {}) {
+        super(message, details.cause === undefined ? undefined : { cause: details.cause });
+        this.name = 'WorkflowError';
+        this.code = code;
+        if (details.node !== undefined)
+            this.node = details.node;
+        if (details.contract !== undefined)
+            this.contract = details.contract;
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

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

package/dist/steps.d.ts

@@ -0,0 +1,77 @@
+import { type Finding, type TaskContract } from '@kernloop/contracts';
+import { type LoopGraph, type LoopNode } from './graph.js';
+import { type RunState } from './state.js';
+/**
+ * Loop-shaping inputs the engine resolves from its config + injected seams and
+ * threads into {@link advance}: the vote bound `K`, the child-iterate bound
+ * `Kc`, overlay specialists, the review-drives-iteration honesty flag, whether
+ * a child re-entry is within budget, and an audit hook fired on each child
+ * re-iteration (the engine wires it to the chain; workflows imports no kernel).
+ */
+export interface AdvanceOptions {
+    readonly k: number;
+    readonly kc: number;
+    readonly specialists: readonly string[];
+    readonly reviewDrivesIteration: boolean;
+    /** Does the parsimony gate drive child re-iteration this run (#9/#415)? True at
+     * intensity full/ultra (a rejecting parsimony verdict re-runs implement), false
+     * at lite/off (advisory or disabled). The CLI derives it from the overlay. */
+    readonly parsimonyDrivesIteration: boolean;
+    /** False when a child re-implement would exceed the run budget (Part B). */
+    readonly childWithinBudget: boolean;
+    /** Fired when a child re-enters implement: {childId, iteration, gate, findingCount}. */
+    readonly onIterate?: (event: {
+        childId: string;
+        iteration: number;
+        gate: string;
+        findingCount: number;
+    }) => void;
+}
+/** The next unit of work the cursor points at. */
+export interface Step {
+    readonly node: LoopNode;
+    readonly input: unknown;
+    /** Set inside the fan-out sub-chain. */
+    readonly child?: TaskContract;
+    /**
+     * The CHILD's accumulated gate findings, inside the fan-out sub-chain — what
+     * the re-running coder must fix [CLM-0043]. Distinct from the run-level
+     * findings (vote re-entries); the engine hands these to the child's
+     * NodeContext so implement reads its own critique, not the run's.
+     */
+    readonly childFindings?: readonly Finding[];
+}
+/** Build the initial state for a fresh run. */
+export declare function initialState(task: TaskContract, entry: string): RunState;
+/**
+ * Resolve the cursor to the node about to run and its input. Inputs follow
+ * the graph's edges: a main-chain node consumes the value its predecessor
+ * emitted (for plan re-entries that is still research's Brief — the
+ * rejecting Verdict's findings travel via NodeContext.findings); the child
+ * sub-chain consumes the child contract, then the implement output.
+ */
+export declare function nextStep(graph: LoopGraph, state: RunState): Step;
+/**
+ * Validate a node's emission against its declared contract before it
+ * crosses the edge [CLM-0042]. Collection emitters (decompose's children)
+ * validate element-wise. Throws a typed error naming node + contract.
+ */
+export declare function validateEmission(node: LoopNode, output: unknown): unknown;
+/**
+ * Synthesize the child contract for an overlay-added specialist (spec §6
+ * "add a specialist") [CLM-0045]. The entry adds WORK, not budget: its
+ * budget is zero so the decomposed children's budget-sum invariant (PM's
+ * job, spec §5.4) survives the addition; a composition root that wants a
+ * funded specialist makes its decompose executor slice for it.
+ */
+export declare function specialistChild(task: TaskContract, specialist: string): TaskContract;
+/** Step to the next fan-out child, or back to the main chain after the last. */
+export declare function advanceToNextChild(graph: LoopGraph, state: RunState, childIndex: number): void;
+/**
+ * Apply one validated emission to the state and move the cursor. Mutates
+ * `state` (the engine snapshots per checkpoint). {@link AdvanceOptions} carries
+ * the vote bound K, the child-iterate bound Kc, overlay specialists, the
+ * review-drives-iteration honesty flag, the budget verdict, and the audit hook.
+ */
+export declare function advance(graph: LoopGraph, state: RunState, node: LoopNode, output: unknown, opts: AdvanceOptions): void;
+//# sourceMappingURL=steps.d.ts.map

package/dist/steps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"steps.d.ts","sourceRoot":"","sources":["../src/steps.ts"],"names":[],"mappings":"AAOA,OAAO,EAGL,KAAK,OAAO,EACZ,KAAK,YAAY,EAElB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAyB,KAAK,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAClF,OAAO,EAAiB,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAU1D;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAC;IACxC;;kFAE8E;IAC9E,QAAQ,CAAC,wBAAwB,EAAE,OAAO,CAAC;IAC3C,4EAA4E;IAC5E,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC,wFAAwF;IACxF,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE;QAC3B,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,YAAY,EAAE,MAAM,CAAC;KACtB,KAAK,IAAI,CAAC;CACZ;AAED,kDAAkD;AAClD,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,wCAAwC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CAC7C;AAED,+CAA+C;AAC/C,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CAaxE;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,GAAG,IAAI,CAoBhE;AAYD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAYzE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,YAAY,CAYpF;AAqID,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAW9F;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CACrB,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,QAAQ,EACf,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,cAAc,GACnB,IAAI,CAwBN"}

package/dist/steps.js

@@ -0,0 +1,270 @@
+/**
+ * Step mechanics for the loop engine: what runs next, what it consumes,
+ * how the state advances when it completes, and the edge-contract
+ * validation that rejects malformed emissions [CLM-0042]. Pure state
+ * transitions — no I/O, no executors; the engine owns those.
+ */
+import { z } from 'zod';
+import { KNOWN_CONTRACTS, TaskContractSchema, } from '@kernloop/contracts';
+import { nodeByName, successor } from './graph.js';
+import { WorkflowError } from './state.js';
+import { childBranch, escalateChild, foldHints, gateDrivesIteration, reiterateChild, } from './child-iterate.js';
+import { verdictDisposition } from './verdict-disposition.js';
+/** Build the initial state for a fresh run. */
+export function initialState(task, entry) {
+    return {
+        task,
+        status: 'running',
+        cursor: { phase: 'main', node: entry },
+        iteration: 0,
+        values: {},
+        findings: [],
+        children: [],
+        childResults: [],
+        trace: [],
+        observedMaxNodeSpend: { tokens: 0, usd: 0 },
+    };
+}
+/**
+ * Resolve the cursor to the node about to run and its input. Inputs follow
+ * the graph's edges: a main-chain node consumes the value its predecessor
+ * emitted (for plan re-entries that is still research's Brief — the
+ * rejecting Verdict's findings travel via NodeContext.findings); the child
+ * sub-chain consumes the child contract, then the implement output.
+ */
+export function nextStep(graph, state) {
+    const cursor = state.cursor;
+    if (cursor.phase === 'done') {
+        throw new WorkflowError('executor_failed', 'internal: stepping a finished run');
+    }
+    if (cursor.phase === 'fanout') {
+        const child = state.children[cursor.childIndex];
+        const node = graph.childChain[cursor.sub];
+        if (child === undefined || node === undefined) {
+            throw new WorkflowError('corrupt_checkpoint', 'fan-out cursor points outside the run state');
+        }
+        const result = state.childResults[cursor.childIndex];
+        const input = cursor.sub === 0 ? child : result?.output;
+        return { node, input, child, childFindings: result?.findings ?? [] };
+    }
+    const node = nodeByName(graph, cursor.node);
+    if (node === undefined) {
+        throw new WorkflowError('corrupt_checkpoint', `cursor names unknown node "${cursor.node}"`);
+    }
+    return { node, input: mainInput(graph, node, state) };
+}
+/** The primary input of a main-chain node (see {@link nextStep}). */
+function mainInput(graph, node, state) {
+    if (node.name === graph.entry)
+        return state.task;
+    if (node.kind === 'integrate')
+        return state.childResults;
+    const incoming = graph.edges.find((e) => e.to === node.name && e.when === undefined) ??
+        graph.edges.find((e) => e.to === node.name);
+    return incoming === undefined ? undefined : state.values[incoming.from];
+}
+/**
+ * Validate a node's emission against its declared contract before it
+ * crosses the edge [CLM-0042]. Collection emitters (decompose's children)
+ * validate element-wise. Throws a typed error naming node + contract.
+ */
+export function validateEmission(node, output) {
+    const schema = KNOWN_CONTRACTS[node.emits];
+    const checked = node.kind === 'decompose' ? z.array(schema).safeParse(output) : schema.safeParse(output);
+    if (!checked.success) {
+        throw new WorkflowError('edge_contract', `node "${node.name}" emitted a malformed ${node.emits}: ${z.prettifyError(checked.error)}`, { node: node.name, contract: node.emits });
+    }
+    return checked.data;
+}
+/**
+ * Synthesize the child contract for an overlay-added specialist (spec §6
+ * "add a specialist") [CLM-0045]. The entry adds WORK, not budget: its
+ * budget is zero so the decomposed children's budget-sum invariant (PM's
+ * job, spec §5.4) survives the addition; a composition root that wants a
+ * funded specialist makes its decompose executor slice for it.
+ */
+export function specialistChild(task, specialist) {
+    return TaskContractSchema.parse({
+        id: `${task.id}.${specialist}`,
+        parent: task.id,
+        goal: `specialist ${specialist}: ${task.goal}`,
+        constraints: task.constraints,
+        budget: { tokens: 0, usd: 0, wallClockMin: 0 },
+        evidence: [],
+        definitionOfDone: [],
+        authorityCeiling: task.authorityCeiling,
+        overlay: task.overlay,
+    });
+}
+/** Move the cursor into the fan-out, or past it when there are no children. */
+function enterFanout(graph, state, from) {
+    const next = successor(graph, from);
+    if (state.children.length > 0) {
+        state.cursor = { phase: 'fanout', childIndex: 0, sub: 0 };
+    }
+    else if (next !== undefined) {
+        state.cursor = { phase: 'main', node: successor(graph, next.to)?.to ?? next.to };
+    }
+}
+/** Apply a completed VOTE: branch on the Verdict, bounded by K [CLM-0043]. */
+function advanceVote(graph, state, node, k) {
+    const verdict = state.values[node.name];
+    const disposition = verdictDisposition(verdict.result);
+    if (disposition === 'advance') {
+        const edge = successor(graph, node.name, 'approved');
+        if (edge !== undefined)
+            state.cursor = { phase: 'main', node: edge.to };
+        return;
+    }
+    state.findings.push(...verdict.findings);
+    if (disposition === 'escalate') {
+        // The gate ruled "a human must decide" (#192): HALT as escalated IMMEDIATELY,
+        // regardless of K — not a re-iterate. A distinct haltReason lets an operator
+        // tell a deadlock from K-exhaustion. Cursor parks on the rejected edge so a
+        // resume after the human rules continues from plan [CLM-0043].
+        const edge = successor(graph, node.name, 'rejected');
+        if (edge !== undefined)
+            state.cursor = { phase: 'main', node: edge.to };
+        state.status = 'escalated';
+        state.haltReason = 'vote-escalation';
+        return;
+    }
+    if (state.iteration >= k) {
+        // K re-entries exhausted: HALT as escalated, cursor parked at plan so a
+        // resume after the human edits continues from there [CLM-0043].
+        const edge = successor(graph, node.name, 'rejected');
+        if (edge !== undefined)
+            state.cursor = { phase: 'main', node: edge.to };
+        state.status = 'escalated';
+        state.haltReason = 'vote';
+        return;
+    }
+    state.iteration += 1;
+    const edge = successor(graph, node.name, 'rejected');
+    if (edge !== undefined)
+        state.cursor = { phase: 'main', node: edge.to };
+}
+/**
+ * Advance the fan-out cursor after one child sub-node completed — branch-aware,
+ * MIRRORING {@link advanceVote}. A driving gate (quality always; review only
+ * when promoted to enforce, the honesty guard) that rejects re-runs implement
+ * within Kc and budget [CLM-0043], or escalates the child at the bound; a
+ * passing gate (and any non-driving gate, whose findings fold in as hints)
+ * advances the sub-chain, then to the next child.
+ */
+function advanceChild(graph, state, output, opts) {
+    if (state.cursor.phase !== 'fanout')
+        return;
+    const { childIndex, sub } = state.cursor;
+    const result = state.childResults[childIndex];
+    if (result === undefined)
+        return;
+    // Route the sub-node's output to the right slot by its role, not its index,
+    // so the chain can grow (quality → review) without positional assumptions.
+    const subNode = graph.childChain[sub];
+    if (subNode?.gate === 'review') {
+        result.reviewVerdict = output;
+    }
+    else if (subNode?.gate === 'parsimony') {
+        result.parsimonyVerdict = output;
+    }
+    else if (subNode?.kind === 'gate') {
+        result.verdict = output;
+    }
+    else {
+        result.output = output;
+    }
+    if (subNode?.kind === 'gate' &&
+        advanceChildGate(graph, state, subNode, output, opts)) {
+        return; // the gate branched (re-iterate or escalate); cursor already moved.
+    }
+    if (sub + 1 < graph.childChain.length) {
+        state.cursor = { phase: 'fanout', childIndex, sub: sub + 1 };
+    }
+    else {
+        advanceToNextChild(graph, state, childIndex);
+    }
+}
+/**
+ * Apply a completed child gate: drive the iteration back-edge (quality, or
+ * review at enforce), or fold a non-driving gate's findings as hints. Returns
+ * true when the cursor branched (re-iterate or escalate at the bound) so the
+ * caller does not also advance the sub-chain — exactly as advanceVote owns the
+ * cursor on the rejected edge.
+ */
+function advanceChildGate(graph, state, gateNode, verdict, opts) {
+    if (state.cursor.phase !== 'fanout')
+        return false;
+    const result = state.childResults[state.cursor.childIndex];
+    if (result === undefined)
+        return false;
+    if (!gateDrivesIteration(gateNode, {
+        reviewDrives: opts.reviewDrivesIteration,
+        parsimonyDrives: opts.parsimonyDrivesIteration,
+    })) {
+        foldHints(result, verdict.findings);
+        return false;
+    }
+    const branch = childBranch(verdict, result, opts.kc, opts.childWithinBudget);
+    if (branch === 'pass')
+        return false;
+    if (branch === 'escalate') {
+        escalateChild(result, verdict.findings);
+        advanceToNextChild(graph, state, state.cursor.childIndex);
+        return true;
+    }
+    reiterateChild(state, result, verdict.findings);
+    opts.onIterate?.({
+        childId: result.child.id,
+        iteration: result.iteration,
+        gate: gateNode.gate ?? gateNode.name,
+        findingCount: result.findings.length,
+    });
+    return true;
+}
+/** Step to the next fan-out child, or back to the main chain after the last. */
+export function advanceToNextChild(graph, state, childIndex) {
+    if (childIndex + 1 < state.children.length) {
+        state.cursor = { phase: 'fanout', childIndex: childIndex + 1, sub: 0 };
+    }
+    else {
+        const fanout = graph.nodes.find((n) => n.kind === 'fanout');
+        const edge = fanout === undefined ? undefined : successor(graph, fanout.name);
+        // Integrate's input is the honest per-child aggregate (childResults):
+        // verdicts element-wise validated at the quality edge, failures carried
+        // alongside as error records — see mainInput's integrate special case.
+        state.cursor = edge === undefined ? { phase: 'done' } : { phase: 'main', node: edge.to };
+    }
+}
+/**
+ * Apply one validated emission to the state and move the cursor. Mutates
+ * `state` (the engine snapshots per checkpoint). {@link AdvanceOptions} carries
+ * the vote bound K, the child-iterate bound Kc, overlay specialists, the
+ * review-drives-iteration honesty flag, the budget verdict, and the audit hook.
+ */
+export function advance(graph, state, node, output, opts) {
+    if (state.cursor.phase === 'fanout') {
+        advanceChild(graph, state, output, opts);
+        return;
+    }
+    state.values[node.name] = output;
+    if (node.kind === 'gate') {
+        advanceVote(graph, state, node, opts.k);
+        return;
+    }
+    if (node.kind === 'decompose') {
+        const children = output;
+        state.children = [...children, ...opts.specialists.map((s) => specialistChild(state.task, s))];
+        state.childResults = state.children.map((child) => ({ child, iteration: 0, findings: [] }));
+        enterFanout(graph, state, node.name);
+        return;
+    }
+    if (node.kind === 'retrospect') {
+        state.cursor = { phase: 'done' };
+        state.status = 'completed';
+        return;
+    }
+    const edge = successor(graph, node.name);
+    state.cursor = edge === undefined ? { phase: 'done' } : { phase: 'main', node: edge.to };
+}
+//# sourceMappingURL=steps.js.map

package/dist/steps.js.map

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

package/dist/verdict-disposition.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The single routing classifier for a {@link VerdictResult} (#192). Every place
+ * the canonical loop branches on a gate's verdict goes through this function, so
+ * that growing the Frozen-Five `VerdictResult` enum is a COMPILE error here (the
+ * `never`-exhaustiveness guard in the `default` arm) rather than a silent
+ * mis-route at a scattered `=== 'pass'` comparison — the latent-defect class the
+ * #192 consumer audit found.
+ *
+ * Three dispositions:
+ * - `advance` — the gate cleared (`approve`/`pass`): proceed.
+ * - `escalate` — the gate ruled "a human must decide" (`escalate`, #192): the
+ *   loop HALTS as escalated and surfaces to the operator (never a silent pass,
+ *   never an automatic reject). Not a synchronous prompt — an autonomous loop
+ *   has no human present at the moment of escalation.
+ * - `block` — the gate did not clear (`reject`/`fail`/`abstain`): re-iterate
+ *   within bounds, else escalate at the bound (the pre-existing behavior).
+ */
+import type { VerdictResult } from '@kernloop/contracts';
+/** How the loop routes a verdict — see {@link verdictDisposition}. */
+export type VerdictDisposition = 'advance' | 'escalate' | 'block';
+/** Classify a {@link VerdictResult} into its loop routing disposition (#192). */
+export declare function verdictDisposition(result: VerdictResult): VerdictDisposition;
+//# sourceMappingURL=verdict-disposition.d.ts.map

package/dist/verdict-disposition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict-disposition.d.ts","sourceRoot":"","sources":["../src/verdict-disposition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,sEAAsE;AACtE,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,CAAC;AAElE,iFAAiF;AACjF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,GAAG,kBAAkB,CAgB5E"}

package/dist/verdict-disposition.js

@@ -0,0 +1,28 @@
+/** Classify a {@link VerdictResult} into its loop routing disposition (#192). */
+export function verdictDisposition(result) {
+    switch (result) {
+        case 'approve':
+        case 'pass':
+            return 'advance';
+        case 'escalate':
+            return 'escalate';
+        case 'reject':
+        case 'fail':
+        case 'abstain':
+            return 'block';
+        /* v8 ignore next 2 -- unreachable: every VerdictResult is handled above; the
+           default exists only as the compile-time exhaustiveness guard (see below). */
+        default:
+            return assertUnreachableResult(result);
+    }
+}
+/**
+ * Compile-time exhaustiveness guard: if a new `VerdictResult` value is added
+ * without a `case` above, `result` is no longer `never` here and this fails to
+ * typecheck — forcing the new disposition to be handled, not silently dropped.
+ */
+/* v8 ignore next 3 -- the guard never runs while the switch is exhaustive */
+function assertUnreachableResult(result) {
+    throw new Error(`unhandled VerdictResult: ${String(result)}`);
+}
+//# sourceMappingURL=verdict-disposition.js.map

package/dist/verdict-disposition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict-disposition.js","sourceRoot":"","sources":["../src/verdict-disposition.ts"],"names":[],"mappings":"AAsBA,iFAAiF;AACjF,MAAM,UAAU,kBAAkB,CAAC,MAAqB;IACtD,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,SAAS,CAAC;QACf,KAAK,MAAM;YACT,OAAO,SAAS,CAAC;QACnB,KAAK,UAAU;YACb,OAAO,UAAU,CAAC;QACpB,KAAK,QAAQ,CAAC;QACd,KAAK,MAAM,CAAC;QACZ,KAAK,SAAS;YACZ,OAAO,OAAO,CAAC;QACjB;uFAC+E;QAC/E;YACE,OAAO,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAC3C,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,6EAA6E;AAC7E,SAAS,uBAAuB,CAAC,MAAa;IAC5C,MAAM,IAAI,KAAK,CAAC,4BAA4B,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAChE,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@kernloop/workflows",
+  "version": "0.1.0",
+  "description": "Kernloop Layer 3 — the canonical loop as data plus the execution engine (spec §6): one blessed graph, per-node checkpoint/resume, and the K-bounded vote-iterate cycle. All real work (model calls, gates, memory) arrives as injected node executors; checkpoint persistence arrives as an injected storage interface — this package imports contracts and zod only.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@kernloop/contracts": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kernloop/kernloop.git",
+    "directory": "packages/workflows"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run --coverage"
+  }
+}