@kernloop/workflows 0.1.0

package/dist/engine.d.ts

@@ -0,0 +1,12 @@
+import type { EngineDeps, Engine } from './engine-types.js';
+export { EngineConfigSchema, type EngineConfig, type EngineConfigInput } from './config.js';
+export { BudgetModeSchema, type BudgetGuard, type BudgetMode } from './budget.js';
+export type { ChildIterateEvent } from './child-iterate.js';
+export type { NodeContext, NodeExecutor, EngineDeps, RunOptions, Engine } from './engine-types.js';
+/**
+ * Create a loop engine over the CANONICAL_LOOP. Throws `unwired_node` if
+ * any executable node lacks an executor (wiring-complete or absent — a
+ * graph that could fail mid-run on a missing executor is a stub).
+ */
+export declare function createEngine(deps: EngineDeps): Engine;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAsCA,OAAO,KAAK,EAA6B,UAAU,EAAc,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEnG,OAAO,EAAE,kBAAkB,EAAE,KAAK,YAAY,EAAE,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAClF,YAAY,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAG5D,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAmRnG;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAErD"}

package/dist/engine.js

@@ -0,0 +1,262 @@
+/**
+ * The loop execution engine. `createEngine({executors, checkpoints, config})`
+ * binds the CANONICAL_LOOP to injected node executors and a checkpoint store —
+ * all real work (model calls, gates, memory) arrives through `executors`; this
+ * package never imports the kernel, a faculty, or the cli (workflows talks
+ * contracts, not plugins). The config schema lives in config.ts; it mirrors the
+ * cli OverlaySchema field-for-field [CLM-0045]. Overrides change behavior
+ * against the SAME frozen graph (a `gate` override swaps a gate executor;
+ * `specialists` adds fan-out children) — the graph is never duplicated. Fan-out
+ * children run SEQUENTIALLY: deterministic trace, unambiguous cursor, no budget
+ * race (per-child spend is sliced off that order, #56); concurrency via a claim.
+ */
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { TaskContractSchema } from '@kernloop/contracts';
+import { CANONICAL_LOOP } from './graph.js';
+import { RunStateSchema, WorkflowError } from './state.js';
+import { asWorkflowError } from './engine-errors.js';
+import { advance, advanceToNextChild, initialState, nextStep, validateEmission, } from './steps.js';
+import { enforceBudget, enforceBudgetPreNode, foldNodeSpend, overBudget, } from './budget.js';
+import { ChildSpendTracker, childSpends } from './child-spend.js';
+import { EngineConfigSchema } from './config.js';
+export { EngineConfigSchema } from './config.js';
+export { BudgetModeSchema } from './budget.js';
+/** Engine implementation; see {@link createEngine}. */
+class LoopEngine {
+    graph = CANONICAL_LOOP;
+    executors;
+    checkpoints;
+    config;
+    /** Pre-node budget reserve floor fraction (#342), hoisted for a short call site. */
+    headroom;
+    budget;
+    onChildIterate;
+    /** Slices the run-global meter per fan-out child for attribution + halt (#56). */
+    childSpend;
+    constructor(deps) {
+        this.executors = deps.executors;
+        this.checkpoints = deps.checkpoints;
+        this.config = EngineConfigSchema.parse(deps.config);
+        this.headroom = this.config.budgetHeadroomFraction;
+        this.budget = deps.budget;
+        this.childSpend = new ChildSpendTracker(deps.meteredSpend);
+        this.onChildIterate = deps.onChildIterate;
+        // Wiring-complete or absent: every executable node must resolve NOW.
+        // The fan-out node is structural (the engine itself runs the sub-chain).
+        for (const node of [...this.graph.nodes, ...this.graph.childChain]) {
+            if (node.kind !== 'fanout' && this.executorFor(node) === undefined) {
+                throw new WorkflowError('unwired_node', `no executor for node "${node.name}" (kind "${node.kind}"${node.gate === undefined ? '' : `, gate "${this.config.nodeOverrides[node.name]?.gate ?? node.gate}"`})`, { node: node.name });
+            }
+        }
+    }
+    async run(task, options = {}) {
+        const parsed = TaskContractSchema.safeParse(task);
+        if (!parsed.success) {
+            throw new WorkflowError('invalid_task', `run() input is not a TaskContract: ${z.prettifyError(parsed.error)}`, {
+                contract: 'TaskContract',
+            });
+        }
+        const runId = options.runId ?? randomUUID();
+        const state = initialState(parsed.data, this.graph.entry);
+        return this.loop(runId, state, 0, options.signal);
+    }
+    async resume(runId, options = {}) {
+        const checkpoint = await this.checkpoints.latest(runId);
+        if (checkpoint === undefined) {
+            throw new WorkflowError('no_checkpoint', `no checkpoint found for run "${runId}"`);
+        }
+        const parsed = RunStateSchema.safeParse(checkpoint.state);
+        if (!parsed.success) {
+            throw new WorkflowError('corrupt_checkpoint', `checkpoint ${String(checkpoint.seq)} of run "${runId}" does not parse: ${z.prettifyError(parsed.error)}`);
+        }
+        const state = parsed.data;
+        if (state.status === 'completed')
+            return this.finish(runId, state, childSpends(state));
+        if (state.status === 'escalated') {
+            // Vote escalation: the human edited the plan; continue from plan with a
+            // fresh K budget [CLM-0043]. Budget halt [CLM-0077]: continue from the
+            // cursor where spend tripped the limit — iteration is NOT reset (no plan
+            // re-edit), and the budget guard re-evaluates as the run proceeds.
+            if (state.haltReason !== 'budget')
+                state.iteration = 0;
+            state.status = 'running';
+            state.haltReason = undefined;
+        }
+        return this.loop(runId, state, checkpoint.seq, options.signal);
+    }
+    /** Run nodes from the cursor until terminal, checkpointing each completion. */
+    async loop(runId, state, seqStart, signal) {
+        let seq = seqStart;
+        this.childSpend.reset(state); // per-process attribution; drops pre-resume spend (#212)
+        while (state.status === 'running') {
+            const step = nextStep(this.graph, state);
+            // #342: halt before dispatch if the next node would overshoot (a near-ceiling).
+            if (enforceBudgetPreNode(state, this.budget, state.observedMaxNodeSpend, this.headroom))
+                break;
+            const executor = this.executorFor(step.node);
+            if (executor === undefined) {
+                throw new WorkflowError('unwired_node', `no executor for node "${step.node.name}"`);
+            }
+            const fanoutIndex = state.cursor.phase === 'fanout' ? state.cursor.childIndex : undefined;
+            if (fanoutIndex !== undefined)
+                this.childSpend.ensureBaseline(fanoutIndex);
+            const iteration = state.iteration;
+            const spentBefore = this.budget?.spent();
+            let output;
+            let childFailed = false;
+            try {
+                if (signal?.aborted === true)
+                    throw new WorkflowError('aborted', 'abort signal fired');
+                output = validateEmission(step.node, await executor(step.input, this.context(runId, state, step, signal)));
+            }
+            catch (error) {
+                const failure = this.classify(error, state, step, signal);
+                if (failure !== undefined) {
+                    return { runId, status: 'failed', nodeTrace: state.trace, error: failure };
+                }
+                // A child executor failed: recorded honestly (classify advanced the cursor), fan-out continues.
+                childFailed = true;
+            }
+            foldNodeSpend(state, this.budget, spentBefore); // #342: per-node delta → observed-max
+            if (!childFailed)
+                advance(this.graph, state, step.node, output, this.advanceOptions(state));
+            if (fanoutIndex !== undefined)
+                this.childSpend.attribute(state, fanoutIndex);
+            enforceBudget(state, this.budget);
+            seq += 1;
+            state.trace.push(this.traceEntry(seq, iteration, step));
+            const persistFailure = await this.persist(runId, seq, iteration, state, step.node.name);
+            if (persistFailure !== undefined) {
+                return { runId, status: 'failed', nodeTrace: state.trace, error: persistFailure };
+            }
+        }
+        return this.terminalResult(runId, state);
+    }
+    /** The escalated-or-completed result, carrying per-child spend attribution (#56). */
+    terminalResult(runId, state) {
+        const childSpend = childSpends(state);
+        if (state.status !== 'escalated')
+            return this.finish(runId, state, childSpend);
+        return {
+            runId,
+            status: 'escalated',
+            nodeTrace: state.trace,
+            findings: state.findings,
+            ...(state.haltReason === undefined ? {} : { haltReason: state.haltReason }),
+            ...(childSpend === undefined ? {} : { childSpend }),
+        };
+    }
+    /** The loop-shaping inputs for one {@link advance} call, resolved from config + seams. */
+    advanceOptions(state) {
+        return {
+            k: this.config.K,
+            kc: this.config.Kc,
+            specialists: this.specialists(),
+            reviewDrivesIteration: this.config.reviewDrivesIteration,
+            parsimonyDrivesIteration: this.config.parsimonyDrivesIteration,
+            // Re-implement allowed only within BOTH the run budget AND the child's own
+            // slice (#56); over either forces escalation before Kc.
+            childWithinBudget: !overBudget(this.budget) &&
+                this.childSpend.withinOwnBudget(this.budget?.mode === 'enforce', state),
+            ...(this.onChildIterate === undefined ? {} : { onIterate: this.onChildIterate }),
+        };
+    }
+    /** Classify a node throw: undefined means "recorded as child failure, continue". */
+    classify(error, state, step, signal) {
+        const wrapped = asWorkflowError(error, step.node.name, signal);
+        if (wrapped.code === 'executor_failed' && state.cursor.phase === 'fanout') {
+            const { childIndex } = state.cursor;
+            const result = state.childResults[childIndex];
+            if (result !== undefined)
+                result.error = wrapped.message;
+            advanceToNextChild(this.graph, state, childIndex);
+            return undefined;
+        }
+        return wrapped;
+    }
+    context(runId, state, step, signal) {
+        // Fan-out: a node reads its CHILD's findings [CLM-0043]; main chain: the
+        // run-level vote-iterate findings. A snapshot, never the live array.
+        const inFanout = step.child !== undefined;
+        const findings = inFanout ? [...(step.childFindings ?? [])] : [...state.findings];
+        const childIteration = step.child === undefined ? undefined : (this.childIterationFor(state, step.child.id) ?? 0);
+        return {
+            runId,
+            taskId: state.task.id,
+            iteration: state.iteration,
+            config: this.config,
+            node: step.node.name,
+            findings,
+            ...(step.child === undefined ? {} : { child: step.child }),
+            ...(childIteration === undefined ? {} : { childIteration }),
+            ...(signal === undefined ? {} : { signal }),
+        };
+    }
+    /** This child's current actor-critic iteration, from the run state. */
+    childIterationFor(state, childId) {
+        return state.childResults.find((r) => r.child.id === childId)?.iteration;
+    }
+    /** Trace/checkpoint rows record the iteration at which the node RAN. */
+    traceEntry(seq, iteration, step) {
+        return {
+            seq,
+            node: step.node.name,
+            iteration,
+            ...(step.child === undefined ? {} : { childId: step.child.id }),
+        };
+    }
+    /**
+     * Persist one checkpoint [CLM-0044]. A rejected save is a run failure:
+     * silently losing a checkpoint would let `resume` lie about what re-runs.
+     */
+    async persist(runId, seq, iteration, state, node) {
+        try {
+            await this.checkpoints.save({
+                runId,
+                seq,
+                node,
+                iteration,
+                state: structuredClone(state),
+                createdAt: new Date().toISOString(),
+            });
+            return undefined;
+        }
+        catch (error) {
+            return new WorkflowError('checkpoint_failed', `checkpoint ${String(seq)} failed to persist: ${error instanceof Error ? error.message : String(error)}`, { node, cause: error });
+        }
+    }
+    /** Resolve a node's executor: gate overrides swap gate executors [CLM-0045]. */
+    executorFor(node) {
+        if (node.kind === 'gate' && node.gate !== undefined) {
+            const gateName = this.config.nodeOverrides[node.name]?.gate ?? node.gate;
+            return this.executors[gateName];
+        }
+        return this.executors[node.name] ?? this.executors[node.kind];
+    }
+    specialists() {
+        const fanout = this.graph.nodes.find((n) => n.kind === 'fanout');
+        if (fanout === undefined)
+            return [];
+        return this.config.nodeOverrides[fanout.name]?.specialists ?? [];
+    }
+    finish(runId, state, childSpend) {
+        const retrospect = this.graph.nodes.find((n) => n.kind === 'retrospect');
+        return {
+            runId,
+            status: 'completed',
+            nodeTrace: state.trace,
+            outcome: state.values[retrospect?.name ?? 'retrospect'],
+            ...(childSpend === undefined ? {} : { childSpend }),
+        };
+    }
+}
+/**
+ * Create a loop engine over the CANONICAL_LOOP. Throws `unwired_node` if
+ * any executable node lacks an executor (wiring-complete or absent — a
+ * graph that could fail mid-run on a missing executor is a stub).
+ */
+export function createEngine(deps) {
+    return new LoopEngine(deps);
+}
+//# sourceMappingURL=engine.js.map

package/dist/engine.js.map

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

package/dist/graph.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The canonical loop as DATA (spec §6): one blessed graph, declared here and
+ * never duplicated. Overlays change behavior through engine config (gate
+ * swaps, added specialists, K) against this SAME object [CLM-0045]; the
+ * graph itself is frozen.
+ *
+ *   Frame → Research → Plan → VOTE —approved→ Decompose
+ *     → FanOut(children: each implement → quality gate) → Integrate
+ *     → Retrospect
+ *   VOTE —rejected+findings→ Plan   (at most K re-entries, then escalate)
+ *
+ * EVERY edge declares the contract that crosses it [CLM-0042]; the engine
+ * zod-validates each node's emission against its declared contract before
+ * the value crosses the edge. Gate nodes always emit a Verdict.
+ */
+import type { ContractRef } from '@kernloop/contracts';
+/** Node kinds in the canonical loop (spec §6). */
+export type LoopNodeKind = 'task' | 'gate' | 'decompose' | 'fanout' | 'integrate' | 'retrospect';
+/** The gates the loop invokes. */
+export type LoopGateName = 'vote' | 'quality' | 'review' | 'parsimony';
+/**
+ * One node of the loop. `consumes` is the contract of the node's primary
+ * input (`null` for the entry node, whose input is the run's TaskContract);
+ * `emits` is the contract the node's output must satisfy — the engine
+ * validates it at the outgoing edge. Nodes whose output is a collection
+ * (decompose → children, fanout → child verdicts) validate element-wise.
+ */
+export interface LoopNode {
+    readonly name: string;
+    readonly kind: LoopNodeKind;
+    readonly consumes: ContractRef | null;
+    readonly emits: ContractRef;
+    /** For gate nodes: which gate executor to call (overlay may swap it). */
+    readonly gate?: LoopGateName;
+}
+/**
+ * One edge of the loop. `contract` names which of the frozen five crosses
+ * it [CLM-0042]. Gate nodes branch: `when` selects the edge taken for an
+ * approving vs. rejecting Verdict.
+ */
+export interface LoopEdge {
+    readonly from: string;
+    readonly to: string;
+    readonly contract: ContractRef;
+    readonly when?: 'approved' | 'rejected';
+}
+/** The canonical loop: main chain, branch edges, and the fan-out sub-chain. */
+export interface LoopGraph {
+    /** Name of the entry node. */
+    readonly entry: string;
+    readonly nodes: readonly LoopNode[];
+    readonly edges: readonly LoopEdge[];
+    /**
+     * The per-child sub-chain run inside the fan-out node, in order. Each
+     * decomposed child TaskContract flows through these nodes sequentially.
+     */
+    readonly childChain: readonly LoopNode[];
+}
+/**
+ * THE canonical loop (spec §6) [CLM-0042]. Edge contracts, honestly:
+ *
+ * - frame emits the framed TaskContract (refined goal/constraints);
+ * - research compiles context into a Brief;
+ * - plan emits the plan as a Brief (a reproducible, provenance-tagged
+ *   artifact — spec §4);
+ * - vote judges the plan Brief and emits a Verdict; the approved edge
+ *   carries that Verdict into decompose, the rejected edge carries it back
+ *   to plan (the engine feeds its findings to the plan executor and bounds
+ *   the cycle at K re-entries [CLM-0043]);
+ * - decompose emits child TaskContracts (element-wise validated);
+ * - fanout runs each child through implement → quality → review → parsimony
+ *   and emits the per-child Verdicts (element-wise validated); child failures travel
+ *   alongside as structured error records — see the engine's ChildResult;
+ * - integrate merges child results into an Outcome;
+ * - retrospect closes the run with the final Outcome (memory writes and
+ *   Observer feeds are the injected executor's job, not the engine's).
+ */
+export declare const CANONICAL_LOOP: LoopGraph;
+/** Look up a node by name in the main chain or the child sub-chain. */
+export declare function nodeByName(graph: LoopGraph, name: string): LoopNode | undefined;
+/**
+ * The successor of a node along the main chain. For gate nodes pass the
+ * branch taken (`approved`/`rejected`); plain nodes have exactly one
+ * outgoing edge. Returns undefined for the terminal node.
+ */
+export declare function successor(graph: LoopGraph, from: string, branch?: 'approved' | 'rejected'): LoopEdge | undefined;
+//# sourceMappingURL=graph.d.ts.map

package/dist/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../src/graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,kDAAkD;AAClD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,GAAG,YAAY,CAAC;AAEjG,kCAAkC;AAClC,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEvE;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;CACzC;AAED,+EAA+E;AAC/E,MAAM,WAAW,SAAS;IACxB,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,QAAQ,EAAE,CAAC;CAC1C;AAYD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,cAAc,EAAE,SA4B3B,CAAC;AAEH,uEAAuE;AACvE,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAE/E;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,UAAU,GAAG,UAAU,GAC/B,QAAQ,GAAG,SAAS,CAEtB"}

package/dist/graph.js

@@ -0,0 +1,72 @@
+/** Deep-freeze a graph so the canonical loop is immutable data. */
+function freezeGraph(graph) {
+    for (const node of [...graph.nodes, ...graph.childChain])
+        Object.freeze(node);
+    for (const edge of graph.edges)
+        Object.freeze(edge);
+    Object.freeze(graph.nodes);
+    Object.freeze(graph.edges);
+    Object.freeze(graph.childChain);
+    return Object.freeze(graph);
+}
+/**
+ * THE canonical loop (spec §6) [CLM-0042]. Edge contracts, honestly:
+ *
+ * - frame emits the framed TaskContract (refined goal/constraints);
+ * - research compiles context into a Brief;
+ * - plan emits the plan as a Brief (a reproducible, provenance-tagged
+ *   artifact — spec §4);
+ * - vote judges the plan Brief and emits a Verdict; the approved edge
+ *   carries that Verdict into decompose, the rejected edge carries it back
+ *   to plan (the engine feeds its findings to the plan executor and bounds
+ *   the cycle at K re-entries [CLM-0043]);
+ * - decompose emits child TaskContracts (element-wise validated);
+ * - fanout runs each child through implement → quality → review → parsimony
+ *   and emits the per-child Verdicts (element-wise validated); child failures travel
+ *   alongside as structured error records — see the engine's ChildResult;
+ * - integrate merges child results into an Outcome;
+ * - retrospect closes the run with the final Outcome (memory writes and
+ *   Observer feeds are the injected executor's job, not the engine's).
+ */
+export const CANONICAL_LOOP = freezeGraph({
+    entry: 'frame',
+    nodes: [
+        { name: 'frame', kind: 'task', consumes: null, emits: 'TaskContract' },
+        { name: 'research', kind: 'task', consumes: 'TaskContract', emits: 'Brief' },
+        { name: 'plan', kind: 'task', consumes: 'Brief', emits: 'Brief' },
+        { name: 'vote', kind: 'gate', consumes: 'Brief', emits: 'Verdict', gate: 'vote' },
+        { name: 'decompose', kind: 'decompose', consumes: 'Verdict', emits: 'TaskContract' },
+        { name: 'fanout', kind: 'fanout', consumes: 'TaskContract', emits: 'Verdict' },
+        { name: 'integrate', kind: 'integrate', consumes: 'Verdict', emits: 'Outcome' },
+        { name: 'retrospect', kind: 'retrospect', consumes: 'Outcome', emits: 'Outcome' },
+    ],
+    edges: [
+        { from: 'frame', to: 'research', contract: 'TaskContract' },
+        { from: 'research', to: 'plan', contract: 'Brief' },
+        { from: 'plan', to: 'vote', contract: 'Brief' },
+        { from: 'vote', to: 'decompose', contract: 'Verdict', when: 'approved' },
+        { from: 'vote', to: 'plan', contract: 'Verdict', when: 'rejected' },
+        { from: 'decompose', to: 'fanout', contract: 'TaskContract' },
+        { from: 'fanout', to: 'integrate', contract: 'Verdict' },
+        { from: 'integrate', to: 'retrospect', contract: 'Outcome' },
+    ],
+    childChain: [
+        { name: 'implement', kind: 'task', consumes: 'TaskContract', emits: 'Outcome' },
+        { name: 'quality', kind: 'gate', consumes: 'Outcome', emits: 'Verdict', gate: 'quality' },
+        { name: 'review', kind: 'gate', consumes: 'Outcome', emits: 'Verdict', gate: 'review' },
+        { name: 'parsimony', kind: 'gate', consumes: 'Outcome', emits: 'Verdict', gate: 'parsimony' },
+    ],
+});
+/** Look up a node by name in the main chain or the child sub-chain. */
+export function nodeByName(graph, name) {
+    return graph.nodes.find((n) => n.name === name) ?? graph.childChain.find((n) => n.name === name);
+}
+/**
+ * The successor of a node along the main chain. For gate nodes pass the
+ * branch taken (`approved`/`rejected`); plain nodes have exactly one
+ * outgoing edge. Returns undefined for the terminal node.
+ */
+export function successor(graph, from, branch) {
+    return graph.edges.find((e) => e.from === from && (e.when === undefined || e.when === branch));
+}
+//# sourceMappingURL=graph.js.map

package/dist/graph.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @kernloop/workflows — Layer 3 (spec §2, §6): the canonical loop as data
+ * plus the execution engine. One blessed graph [CLM-0042]; a K-bounded
+ * vote-iterate cycle [CLM-0043]; per-node checkpoints making any run
+ * resumable [CLM-0044]; overlay-shaped config overriding gates and
+ * specialists against the same graph object [CLM-0045].
+ */
+export { CANONICAL_LOOP, nodeByName, successor, type LoopGraph, type LoopNode, type LoopEdge, type LoopNodeKind, type LoopGateName, } from './graph.js';
+export { createEngine, EngineConfigSchema, BudgetModeSchema, type Engine, type EngineConfig, type EngineConfigInput, type EngineDeps, type NodeContext, type NodeExecutor, type RunOptions, type BudgetGuard, type BudgetMode, type ChildIterateEvent, } from './engine.js';
+export { InMemoryCheckpointStore, JsonlCheckpointStore, type CheckpointStore, } from './checkpoints.js';
+export { CheckpointRecordSchema, ChildResultSchema, CursorSchema, RunStateSchema, TraceEntrySchema, WorkflowError, type CheckpointRecord, type ChildResult, type Cursor, type RunResult, type RunState, type TraceEntry, type WorkflowErrorCode, } from './state.js';
+export { workflowsManifest } from './manifest.js';
+export { verdictDisposition, type VerdictDisposition } from './verdict-disposition.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,cAAc,EACd,UAAU,EACV,SAAS,EACT,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,KAAK,MAAM,EACX,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,iBAAiB,GACvB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,KAAK,eAAe,GACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,MAAM,EACX,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,iBAAiB,GACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @kernloop/workflows — Layer 3 (spec §2, §6): the canonical loop as data
+ * plus the execution engine. One blessed graph [CLM-0042]; a K-bounded
+ * vote-iterate cycle [CLM-0043]; per-node checkpoints making any run
+ * resumable [CLM-0044]; overlay-shaped config overriding gates and
+ * specialists against the same graph object [CLM-0045].
+ */
+export { CANONICAL_LOOP, nodeByName, successor, } from './graph.js';
+export { createEngine, EngineConfigSchema, BudgetModeSchema, } from './engine.js';
+export { InMemoryCheckpointStore, JsonlCheckpointStore, } from './checkpoints.js';
+export { CheckpointRecordSchema, ChildResultSchema, CursorSchema, RunStateSchema, TraceEntrySchema, WorkflowError, } from './state.js';
+export { workflowsManifest } from './manifest.js';
+export { verdictDisposition } from './verdict-disposition.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,cAAc,EACd,UAAU,EACV,SAAS,GAMV,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,GAWjB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,uBAAuB,EACvB,oBAAoB,GAErB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,aAAa,GAQd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAA2B,MAAM,0BAA0B,CAAC"}

package/dist/manifest.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The workflows package's registration record (spec §4). Kind is
+ * `strategy`: the canonical loop is strategy-as-data (spec §2 lists L3 as
+ * "data: graphs"), not an L2 plugin — `faculty` would claim a peer of
+ * compiler/memory/gates, `gate` and `agentTemplate` are roles the loop
+ * INVOKES, and skills/workshopTools are something else entirely. Of the
+ * frozen ManifestKind values, `strategy` is the honest one.
+ */
+import { type Manifest } from '@kernloop/contracts';
+/**
+ * The workflows registration manifest. Consumes a TaskContract (the run
+ * entry), emits an Outcome (retrospect's close). Tier `suggest`: the engine
+ * orchestrates and proposes; every blocking decision inside the loop is a
+ * gate's, under the gate's own tier. Zero token cost — the engine never
+ * calls a model (all work is injected executors); latency is dominated by
+ * the executors themselves.
+ */
+export declare const workflowsManifest: Manifest;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpE;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAuB9B,CAAC"}

package/dist/manifest.js

@@ -0,0 +1,41 @@
+/**
+ * The workflows package's registration record (spec §4). Kind is
+ * `strategy`: the canonical loop is strategy-as-data (spec §2 lists L3 as
+ * "data: graphs"), not an L2 plugin — `faculty` would claim a peer of
+ * compiler/memory/gates, `gate` and `agentTemplate` are roles the loop
+ * INVOKES, and skills/workshopTools are something else entirely. Of the
+ * frozen ManifestKind values, `strategy` is the honest one.
+ */
+import { ManifestSchema } from '@kernloop/contracts';
+/**
+ * The workflows registration manifest. Consumes a TaskContract (the run
+ * entry), emits an Outcome (retrospect's close). Tier `suggest`: the engine
+ * orchestrates and proposes; every blocking decision inside the loop is a
+ * gate's, under the gate's own tier. Zero token cost — the engine never
+ * calls a model (all work is injected executors); latency is dominated by
+ * the executors themselves.
+ */
+export const workflowsManifest = ManifestSchema.parse({
+    name: '@kernloop/workflows',
+    version: '0.1.0',
+    kind: 'strategy',
+    capabilities: [
+        {
+            name: 'workflow.canonical',
+            description: 'Run the canonical loop (spec §6) over injected executors with per-node checkpoint/resume and the K-bounded vote-iterate cycle',
+        },
+    ],
+    contracts: {
+        consumes: ['TaskContract'],
+        emits: ['Outcome'],
+    },
+    cost: {
+        tokens: 0,
+        usd: 0,
+        latencyMs: 0,
+    },
+    tier: 'suggest',
+    claims: ['CLM-0042', 'CLM-0043', 'CLM-0044', 'CLM-0045'],
+    maturity: 'stable',
+});
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,cAAc,EAAiB,MAAM,qBAAqB,CAAC;AAEpE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAa,cAAc,CAAC,KAAK,CAAC;IAC9D,IAAI,EAAE,qBAAqB;IAC3B,OAAO,EAAE,OAAO;IAChB,IAAI,EAAE,UAAU;IAChB,YAAY,EAAE;QACZ;YACE,IAAI,EAAE,oBAAoB;YAC1B,WAAW,EACT,+HAA+H;SAClI;KACF;IACD,SAAS,EAAE;QACT,QAAQ,EAAE,CAAC,cAAc,CAAC;QAC1B,KAAK,EAAE,CAAC,SAAS,CAAC;KACnB;IACD,IAAI,EAAE;QACJ,MAAM,EAAE,CAAC;QACT,GAAG,EAAE,CAAC;QACN,SAAS,EAAE,CAAC;KACb;IACD,IAAI,EAAE,SAAS;IACf,MAAM,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,CAAC;IACxD,QAAQ,EAAE,QAAQ;CACnB,CAAC,CAAC"}