@kernloop/workflows 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Zujkowski and Kernloop contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/budget.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Runtime budget enforcement for the canonical loop (spec §8) [CLM-0077].
+ * The kernel meters per-adapter spend; the engine reads a metered snapshot
+ * through an injected `spent()` seam (workflows imports no kernel — it talks
+ * a plain function) and decides whether a bounded run may continue.
+ *
+ * Two modes, one tracking discipline: `enforce` HALTS the run (escalates,
+ * resumable) the moment metered spend exceeds the parent TaskContract budget;
+ * `unlimited` NEVER halts on budget — the restriction is lifted, the tracking
+ * is not. Usage/cost is metered and reported identically in both modes; an
+ * `unlimited` run is recorded honestly so a report never implies a cap was
+ * honored when it wasn't. Kc still bounds child iteration in unlimited mode
+ * (unlimited budget is not unlimited iterations — raising Kc allows more).
+ */
+import { z } from 'zod';
+import type { Finding } from '@kernloop/contracts';
+import type { RunState } from './state.js';
+/** Enforcement mode for a run's budget (spec §8) [CLM-0077]. */
+export declare const BudgetModeSchema: z.ZodEnum<{
+    enforce: "enforce";
+    unlimited: "unlimited";
+}>;
+export type BudgetMode = z.infer<typeof BudgetModeSchema>;
+/** Metered spend snapshot the engine reads (tokens + usd; wall-clock is the run's). */
+export interface BudgetSpend {
+    readonly tokens: number;
+    readonly usd: number;
+}
+/** The parent budget a bounded run may not exceed (the TaskContract.budget dims). */
+export interface BudgetLimit {
+    readonly tokens: number;
+    readonly usd: number;
+}
+/**
+ * The injected budget guard. `mode` is the enforcement mode; `limit` is the
+ * parent budget; `spent()` returns the live metered snapshot (the CLI's
+ * `totals`). Absent → no runtime enforcement (the engine's tests and any
+ * composition root that does not meter run with no budget halt; Kc still
+ * bounds child iteration). Present with `enforce` → the run halts when spend
+ * exceeds the limit on any tracked dimension.
+ */
+export interface BudgetGuard {
+    readonly mode: BudgetMode;
+    readonly limit: BudgetLimit;
+    readonly spent: () => BudgetSpend;
+}
+/**
+ * True when a bounded run has overspent its parent budget on any tracked
+ * dimension. `unlimited` mode always returns false (never halts); an absent
+ * guard never halts. Comparison is strict `>`: spending exactly the budget is
+ * within it, exceeding it is the halt.
+ */
+export declare function overBudget(guard: BudgetGuard | undefined): boolean;
+/** A per-child sliced budget the fan-out attributes spend against (#56). */
+export interface ChildBudget {
+    readonly tokens: number;
+    readonly usd: number;
+}
+/**
+ * True when a child has overspent ITS OWN sliced budget (#56) — gauged by the
+ * spend ATTRIBUTED to its sub-chain, never the run total, so one child's
+ * overspend is independent of its siblings'. A zero-slice child (a specialist
+ * adds WORK, not budget — spec §6) carries nothing to overspend and is never
+ * gated here; Kc and the run budget still bound it. Strict `>`, mirroring
+ * {@link overBudget}.
+ */
+export declare function childOverOwnBudget(budget: ChildBudget, spend: BudgetSpend): boolean;
+/** The structured finding recorded when an enforce-mode run halts on budget [CLM-0077]. */
+export declare function overspendFinding(guard: BudgetGuard): Finding;
+/**
+ * Runtime budget enforcement [CLM-0077]: in `enforce` mode a run that has now
+ * overspent its parent budget HALTS as escalated (resumable). `unlimited` never
+ * halts here; a finished run is not retro-halted — its cost is still reported in
+ * full by the always-on metering. Mutates `state` in place.
+ */
+export declare function enforceBudget(state: RunState, guard: BudgetGuard | undefined): void;
+/**
+ * The reserve a PRE-node guard keeps free so dispatching the next node cannot
+ * push spend past the limit (#342) — per dimension, the larger of a configurable
+ * headroom floor (`headroomFraction × limit`) and the largest single-node spend
+ * observed so far. The floor covers COLD START (observedMax is 0 until a node
+ * runs, so the first/most-expensive node is otherwise unprotected); observed-max
+ * adapts the reserve to the run's actual worst node.
+ */
+export declare function nodeReserve(limit: BudgetLimit, observedMax: BudgetSpend, headroomFraction: number): BudgetSpend;
+/**
+ * True when dispatching the next node could overshoot the budget (#342): in
+ * `enforce` mode, the remaining budget on some dimension is below the reserve.
+ * Halting BEFORE the node turns the cap from a soft post-hoc trip into a
+ * near-ceiling. `unlimited`/absent never pre-halts.
+ */
+export declare function preNodeOvershoot(guard: BudgetGuard | undefined, observedMax: BudgetSpend, headroomFraction: number): boolean;
+/** The finding recorded when a run halts BEFORE a node on the pre-node guard
+ * (#342) — names remaining + reserve + the largest node so the early halt is
+ * legible, never opaque. */
+export declare function preNodeHaltFinding(guard: BudgetGuard, observedMax: BudgetSpend, headroomFraction: number): Finding;
+/**
+ * Pre-node budget guard (#342): in `enforce` mode, if dispatching the next node
+ * could overshoot, HALT as escalated BEFORE it runs — keeping the post-node
+ * {@link enforceBudget} as the backstop for the first/novel node the reserve
+ * cannot yet anticipate. Mutates `state` in place.
+ */
+export declare function enforceBudgetPreNode(state: RunState, guard: BudgetGuard | undefined, observedMax: BudgetSpend, headroomFraction: number): boolean;
+/** Update the run's largest-single-node spend (#342) from the metered delta
+ * across one node's execution — per dimension max. A negative delta (a
+ * per-process meter reset on resume) contributes nothing. Mutates `state`. */
+export declare function trackNodeSpend(state: RunState, before: BudgetSpend, after: BudgetSpend): void;
+/** Fold a completed node's metered spend into the run's observed-max (#342),
+ * skipping unmetered runs (no guard or no pre-node snapshot). Mutates `state`. */
+export declare function foldNodeSpend(state: RunState, guard: BudgetGuard | undefined, before: BudgetSpend | undefined): void;
+//# sourceMappingURL=budget.d.ts.map

package/dist/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,gEAAgE;AAChE,eAAO,MAAM,gBAAgB;;;EAAmC,CAAC;AACjE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,uFAAuF;AACvF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,qFAAqF;AACrF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,WAAW,CAAC;CACnC;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,CAIlE;AAED,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAGnF;AAED,2FAA2F;AAC3F,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAS5D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,GAAG,SAAS,GAAG,IAAI,CAMnF;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,WAAW,EAClB,WAAW,EAAE,WAAW,EACxB,gBAAgB,EAAE,MAAM,GACvB,WAAW,CAKb;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,WAAW,GAAG,SAAS,EAC9B,WAAW,EAAE,WAAW,EACxB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAWT;AAED;;4BAE4B;AAC5B,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,WAAW,EAClB,WAAW,EAAE,WAAW,EACxB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAYT;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,QAAQ,EACf,KAAK,EAAE,WAAW,GAAG,SAAS,EAC9B,WAAW,EAAE,WAAW,EACxB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAOT;AAED;;8EAE8E;AAC9E,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAK7F;AAED;kFACkF;AAClF,wBAAgB,aAAa,CAC3B,KAAK,EAAE,QAAQ,EACf,KAAK,EAAE,WAAW,GAAG,SAAS,EAC9B,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,IAAI,CAEN"}

package/dist/budget.js

@@ -0,0 +1,146 @@
+/**
+ * Runtime budget enforcement for the canonical loop (spec §8) [CLM-0077].
+ * The kernel meters per-adapter spend; the engine reads a metered snapshot
+ * through an injected `spent()` seam (workflows imports no kernel — it talks
+ * a plain function) and decides whether a bounded run may continue.
+ *
+ * Two modes, one tracking discipline: `enforce` HALTS the run (escalates,
+ * resumable) the moment metered spend exceeds the parent TaskContract budget;
+ * `unlimited` NEVER halts on budget — the restriction is lifted, the tracking
+ * is not. Usage/cost is metered and reported identically in both modes; an
+ * `unlimited` run is recorded honestly so a report never implies a cap was
+ * honored when it wasn't. Kc still bounds child iteration in unlimited mode
+ * (unlimited budget is not unlimited iterations — raising Kc allows more).
+ */
+import { z } from 'zod';
+/** Enforcement mode for a run's budget (spec §8) [CLM-0077]. */
+export const BudgetModeSchema = z.enum(['enforce', 'unlimited']);
+/**
+ * True when a bounded run has overspent its parent budget on any tracked
+ * dimension. `unlimited` mode always returns false (never halts); an absent
+ * guard never halts. Comparison is strict `>`: spending exactly the budget is
+ * within it, exceeding it is the halt.
+ */
+export function overBudget(guard) {
+    if (guard === undefined || guard.mode === 'unlimited')
+        return false;
+    const spent = guard.spent();
+    return spent.tokens > guard.limit.tokens || spent.usd > guard.limit.usd;
+}
+/**
+ * True when a child has overspent ITS OWN sliced budget (#56) — gauged by the
+ * spend ATTRIBUTED to its sub-chain, never the run total, so one child's
+ * overspend is independent of its siblings'. A zero-slice child (a specialist
+ * adds WORK, not budget — spec §6) carries nothing to overspend and is never
+ * gated here; Kc and the run budget still bound it. Strict `>`, mirroring
+ * {@link overBudget}.
+ */
+export function childOverOwnBudget(budget, spend) {
+    if (budget.tokens <= 0 && budget.usd <= 0)
+        return false;
+    return spend.tokens > budget.tokens || spend.usd > budget.usd;
+}
+/** The structured finding recorded when an enforce-mode run halts on budget [CLM-0077]. */
+export function overspendFinding(guard) {
+    const spent = guard.spent();
+    return {
+        severity: 'error',
+        message: `run exceeded its budget (spent ${String(spent.tokens)} tokens / $${String(spent.usd)}; ` +
+            `limit ${String(guard.limit.tokens)} tokens / $${String(guard.limit.usd)}) — ` +
+            'halted in enforce mode; raise the budget or re-run unlimited, then resume',
+    };
+}
+/**
+ * Runtime budget enforcement [CLM-0077]: in `enforce` mode a run that has now
+ * overspent its parent budget HALTS as escalated (resumable). `unlimited` never
+ * halts here; a finished run is not retro-halted — its cost is still reported in
+ * full by the always-on metering. Mutates `state` in place.
+ */
+export function enforceBudget(state, guard) {
+    if (state.status !== 'running' || state.cursor.phase === 'done')
+        return;
+    if (guard === undefined || !overBudget(guard))
+        return;
+    state.status = 'escalated';
+    state.haltReason = 'budget';
+    state.findings.push(overspendFinding(guard));
+}
+/**
+ * The reserve a PRE-node guard keeps free so dispatching the next node cannot
+ * push spend past the limit (#342) — per dimension, the larger of a configurable
+ * headroom floor (`headroomFraction × limit`) and the largest single-node spend
+ * observed so far. The floor covers COLD START (observedMax is 0 until a node
+ * runs, so the first/most-expensive node is otherwise unprotected); observed-max
+ * adapts the reserve to the run's actual worst node.
+ */
+export function nodeReserve(limit, observedMax, headroomFraction) {
+    return {
+        tokens: Math.max(headroomFraction * limit.tokens, observedMax.tokens),
+        usd: Math.max(headroomFraction * limit.usd, observedMax.usd),
+    };
+}
+/**
+ * True when dispatching the next node could overshoot the budget (#342): in
+ * `enforce` mode, the remaining budget on some dimension is below the reserve.
+ * Halting BEFORE the node turns the cap from a soft post-hoc trip into a
+ * near-ceiling. `unlimited`/absent never pre-halts.
+ */
+export function preNodeOvershoot(guard, observedMax, headroomFraction) {
+    if (guard === undefined || guard.mode !== 'enforce')
+        return false;
+    // Already over → the post-node {@link enforceBudget} owns this with its clearer
+    // "exceeded its budget" halt; the pre-node guard only PREVENTS overshoot (still
+    // within budget, but the next node's reserve isn't covered).
+    if (overBudget(guard))
+        return false;
+    const spent = guard.spent();
+    const reserve = nodeReserve(guard.limit, observedMax, headroomFraction);
+    return (guard.limit.tokens - spent.tokens < reserve.tokens || guard.limit.usd - spent.usd < reserve.usd);
+}
+/** The finding recorded when a run halts BEFORE a node on the pre-node guard
+ * (#342) — names remaining + reserve + the largest node so the early halt is
+ * legible, never opaque. */
+export function preNodeHaltFinding(guard, observedMax, headroomFraction) {
+    const spent = guard.spent();
+    const reserve = nodeReserve(guard.limit, observedMax, headroomFraction);
+    return {
+        severity: 'error',
+        message: `run halted BEFORE the next node to avoid budget overshoot (#342): remaining ` +
+            `${String(guard.limit.tokens - spent.tokens)} tokens / $${String(guard.limit.usd - spent.usd)} ` +
+            `< reserve ${String(reserve.tokens)} tokens / $${String(reserve.usd)} ` +
+            `(largest node so far ${String(observedMax.tokens)} tokens / $${String(observedMax.usd)}) — ` +
+            `raise the budget or re-run unlimited, then resume`,
+    };
+}
+/**
+ * Pre-node budget guard (#342): in `enforce` mode, if dispatching the next node
+ * could overshoot, HALT as escalated BEFORE it runs — keeping the post-node
+ * {@link enforceBudget} as the backstop for the first/novel node the reserve
+ * cannot yet anticipate. Mutates `state` in place.
+ */
+export function enforceBudgetPreNode(state, guard, observedMax, headroomFraction) {
+    if (state.status !== 'running' || state.cursor.phase === 'done')
+        return false;
+    if (guard === undefined || !preNodeOvershoot(guard, observedMax, headroomFraction))
+        return false;
+    state.status = 'escalated';
+    state.haltReason = 'budget';
+    state.findings.push(preNodeHaltFinding(guard, observedMax, headroomFraction));
+    return true; // halted before the node — the caller skips dispatch
+}
+/** Update the run's largest-single-node spend (#342) from the metered delta
+ * across one node's execution — per dimension max. A negative delta (a
+ * per-process meter reset on resume) contributes nothing. Mutates `state`. */
+export function trackNodeSpend(state, before, after) {
+    state.observedMaxNodeSpend = {
+        tokens: Math.max(state.observedMaxNodeSpend.tokens, after.tokens - before.tokens),
+        usd: Math.max(state.observedMaxNodeSpend.usd, after.usd - before.usd),
+    };
+}
+/** Fold a completed node's metered spend into the run's observed-max (#342),
+ * skipping unmetered runs (no guard or no pre-node snapshot). Mutates `state`. */
+export function foldNodeSpend(state, guard, before) {
+    if (guard !== undefined && before !== undefined)
+        trackNodeSpend(state, before, guard.spent());
+}
+//# sourceMappingURL=budget.js.map

package/dist/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,gEAAgE;AAChE,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;AA6BjE;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,KAA8B;IACvD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW;QAAE,OAAO,KAAK,CAAC;IACpE,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;IAC5B,OAAO,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC;AAC1E,CAAC;AAQD;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAmB,EAAE,KAAkB;IACxE,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC,IAAI,MAAM,CAAC,GAAG,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACxD,OAAO,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,KAAK,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC;AAChE,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,gBAAgB,CAAC,KAAkB;IACjD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;IAC5B,OAAO;QACL,QAAQ,EAAE,OAAO;QACjB,OAAO,EACL,kCAAkC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,cAAc,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI;YACzF,SAAS,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,cAAc,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM;YAC9E,2EAA2E;KAC9E,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAe,EAAE,KAA8B;IAC3E,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,KAAK,MAAM;QAAE,OAAO;IACxE,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO;IACtD,KAAK,CAAC,MAAM,GAAG,WAAW,CAAC;IAC3B,KAAK,CAAC,UAAU,GAAG,QAAQ,CAAC;IAC5B,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CACzB,KAAkB,EAClB,WAAwB,EACxB,gBAAwB;IAExB,OAAO;QACL,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,gBAAgB,GAAG,KAAK,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC;QACrE,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,gBAAgB,GAAG,KAAK,CAAC,GAAG,EAAE,WAAW,CAAC,GAAG,CAAC;KAC7D,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAA8B,EAC9B,WAAwB,EACxB,gBAAwB;IAExB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAClE,gFAAgF;IAChF,gFAAgF;IAChF,6DAA6D;IAC7D,IAAI,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACpC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;IAC5B,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,CAAC,KAAK,EAAE,WAAW,EAAE,gBAAgB,CAAC,CAAC;IACxE,OAAO,CACL,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAChG,CAAC;AACJ,CAAC;AAED;;4BAE4B;AAC5B,MAAM,UAAU,kBAAkB,CAChC,KAAkB,EAClB,WAAwB,EACxB,gBAAwB;IAExB,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;IAC5B,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,CAAC,KAAK,EAAE,WAAW,EAAE,gBAAgB,CAAC,CAAC;IACxE,OAAO;QACL,QAAQ,EAAE,OAAO;QACjB,OAAO,EACL,8EAA8E;YAC9E,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,cAAc,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG;YAChG,aAAa,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,cAAc,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG;YACvE,wBAAwB,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,cAAc,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM;YAC7F,mDAAmD;KACtD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAe,EACf,KAA8B,EAC9B,WAAwB,EACxB,gBAAwB;IAExB,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC;IAC9E,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,WAAW,EAAE,gBAAgB,CAAC;QAAE,OAAO,KAAK,CAAC;IACjG,KAAK,CAAC,MAAM,GAAG,WAAW,CAAC;IAC3B,KAAK,CAAC,UAAU,GAAG,QAAQ,CAAC;IAC5B,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,kBAAkB,CAAC,KAAK,EAAE,WAAW,EAAE,gBAAgB,CAAC,CAAC,CAAC;IAC9E,OAAO,IAAI,CAAC,CAAC,qDAAqD;AACpE,CAAC;AAED;;8EAE8E;AAC9E,MAAM,UAAU,cAAc,CAAC,KAAe,EAAE,MAAmB,EAAE,KAAkB;IACrF,KAAK,CAAC,oBAAoB,GAAG;QAC3B,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,oBAAoB,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QACjF,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,oBAAoB,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC;KACtE,CAAC;AACJ,CAAC;AAED;kFACkF;AAClF,MAAM,UAAU,aAAa,CAC3B,KAAe,EACf,KAA8B,EAC9B,MAA+B;IAE/B,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS;QAAE,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;AAChG,CAAC"}

package/dist/checkpoints.d.ts

@@ -0,0 +1,40 @@
+import { type CheckpointRecord } from './state.js';
+/**
+ * What the engine needs from storage [CLM-0044]. `save` MUST be durable
+ * when it resolves — the engine treats a rejected save as a run failure
+ * (a checkpoint that silently failed to persist would let `resume` lie).
+ */
+export interface CheckpointStore {
+    /** Append one checkpoint. Records for a run arrive in increasing `seq`. */
+    save(record: CheckpointRecord): Promise<void>;
+    /** The highest-`seq` checkpoint for a run, or undefined if none. */
+    latest(runId: string): Promise<CheckpointRecord | undefined>;
+    /** All checkpoints for a run, in increasing `seq`. */
+    list(runId: string): Promise<readonly CheckpointRecord[]>;
+}
+/** In-memory store: honest, bounded to the process lifetime. */
+export declare class InMemoryCheckpointStore implements CheckpointStore {
+    private readonly byRun;
+    save(record: CheckpointRecord): Promise<void>;
+    latest(runId: string): Promise<CheckpointRecord | undefined>;
+    list(runId: string): Promise<readonly CheckpointRecord[]>;
+}
+/**
+ * Append-only JSONL file store: one checkpoint per line. Reads tolerate
+ * corrupt lines (unparseable JSON or schema-invalid records) by skipping
+ * them — a torn final line is exactly what a kill mid-write leaves behind,
+ * and the last COMPLETE checkpoint is the resume point [CLM-0044]. Skipped
+ * lines are counted on the instance so callers can surface the damage; they
+ * are never silently repaired.
+ */
+export declare class JsonlCheckpointStore implements CheckpointStore {
+    private readonly file;
+    /** Corrupt lines encountered by reads since construction. */
+    corruptLines: number;
+    constructor(file: string);
+    save(record: CheckpointRecord): Promise<void>;
+    latest(runId: string): Promise<CheckpointRecord | undefined>;
+    list(runId: string): Promise<readonly CheckpointRecord[]>;
+    private parseLine;
+}
+//# sourceMappingURL=checkpoints.d.ts.map

package/dist/checkpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoints.d.ts","sourceRoot":"","sources":["../src/checkpoints.ts"],"names":[],"mappings":"AAWA,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE3E;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,IAAI,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,oEAAoE;IACpE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAAC;IAC7D,sDAAsD;IACtD,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,gBAAgB,EAAE,CAAC,CAAC;CAC3D;AAED,gEAAgE;AAChE,qBAAa,uBAAwB,YAAW,eAAe;IAC7D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyC;IAE/D,IAAI,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAO7C,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAK5D,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,gBAAgB,EAAE,CAAC;CAG1D;AAED;;;;;;;GAOG;AACH,qBAAa,oBAAqB,YAAW,eAAe;IAC1D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,6DAA6D;IAC7D,YAAY,SAAK;gBAEL,IAAI,EAAE,MAAM;IAIlB,IAAI,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAK7C,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAK5D,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,gBAAgB,EAAE,CAAC;IAkB/D,OAAO,CAAC,SAAS;CAelB"}

package/dist/checkpoints.js

@@ -0,0 +1,92 @@
+/**
+ * Checkpoint persistence — an INJECTED interface (p2 design notes, open
+ * question 2): the composition root decides where checkpoints live; the
+ * engine only knows this contract. Two real implementations ship here, both
+ * wiring-complete: an in-memory store (tests, ephemeral runs) and an
+ * append-only JSONL file store (a durable one the composition root can bind
+ * today). Ported from v1's ICheckpointStore/InMemoryCheckpointStore
+ * (nexus-agents orchestration/graph) — see PORT-NOTES.md for the deltas.
+ */
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { CheckpointRecordSchema } from './state.js';
+/** In-memory store: honest, bounded to the process lifetime. */
+export class InMemoryCheckpointStore {
+    byRun = new Map();
+    save(record) {
+        const records = this.byRun.get(record.runId) ?? [];
+        records.push(record);
+        this.byRun.set(record.runId, records);
+        return Promise.resolve();
+    }
+    latest(runId) {
+        const records = this.byRun.get(runId);
+        return Promise.resolve(records?.[records.length - 1]);
+    }
+    list(runId) {
+        return Promise.resolve(this.byRun.get(runId) ?? []);
+    }
+}
+/**
+ * Append-only JSONL file store: one checkpoint per line. Reads tolerate
+ * corrupt lines (unparseable JSON or schema-invalid records) by skipping
+ * them — a torn final line is exactly what a kill mid-write leaves behind,
+ * and the last COMPLETE checkpoint is the resume point [CLM-0044]. Skipped
+ * lines are counted on the instance so callers can surface the damage; they
+ * are never silently repaired.
+ */
+export class JsonlCheckpointStore {
+    file;
+    /** Corrupt lines encountered by reads since construction. */
+    corruptLines = 0;
+    constructor(file) {
+        this.file = path.resolve(file);
+    }
+    async save(record) {
+        await mkdir(path.dirname(this.file), { recursive: true });
+        await appendFile(this.file, `${JSON.stringify(record)}\n`, 'utf8');
+    }
+    async latest(runId) {
+        const records = await this.list(runId);
+        return records[records.length - 1];
+    }
+    async list(runId) {
+        let raw;
+        try {
+            raw = await readFile(this.file, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+        const records = [];
+        for (const line of raw.split('\n')) {
+            if (line.trim() === '')
+                continue;
+            const record = this.parseLine(line);
+            if (record === undefined)
+                continue;
+            if (record.runId === runId)
+                records.push(record);
+        }
+        return records.sort((a, b) => a.seq - b.seq);
+    }
+    parseLine(line) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            this.corruptLines += 1;
+            return undefined;
+        }
+        const result = CheckpointRecordSchema.safeParse(parsed);
+        if (!result.success) {
+            this.corruptLines += 1;
+            return undefined;
+        }
+        return result.data;
+    }
+}
+//# sourceMappingURL=checkpoints.js.map

package/dist/checkpoints.js.map

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

package/dist/child-iterate-fixtures.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared scripted fixtures for the child-iteration + budget-mode tests
+ * [CLM-0043, CLM-0077]. Kept apart so neither test file outgrows the 400-line
+ * budget; not a runtime export (test-only, imported by `*.test.ts`).
+ */
+import type { Brief, Finding, Outcome, TaskContract, Verdict } from '@kernloop/contracts';
+import type { NodeContext, NodeExecutor } from './engine.js';
+export declare const task: TaskContract;
+export declare const brief: (taskId: string) => Brief;
+export declare const verdict: (taskId: string, gate: string, result: Verdict["result"]) => Verdict;
+export declare const outcome: (taskId: string) => Outcome;
+export declare const names: (trace: readonly {
+    node: string;
+    childId?: string;
+}[]) => string[];
+/**
+ * A scripted executor set. `qualityByChild` maps a child id to its sequence of
+ * quality results (last entry repeats). Records each implement's NodeContext so
+ * tests can assert the folded child findings + childIteration.
+ */
+export declare function scripted(qualityByChild?: Record<string, Array<Verdict['result']>>): {
+    executors: Record<string, NodeExecutor>;
+    qualityCalls: Record<string, number>;
+    implementCtx: {
+        childId: string;
+        iteration: number;
+        findings: readonly Finding[];
+    }[];
+};
+export declare function counted(executors: Record<string, NodeExecutor>): {
+    executors: {
+        [k: string]: (input: unknown, ctx: NodeContext) => Promise<unknown>;
+    };
+    calls: Record<string, number>;
+};
+//# sourceMappingURL=child-iterate-fixtures.d.ts.map

package/dist/child-iterate-fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-iterate-fixtures.d.ts","sourceRoot":"","sources":["../src/child-iterate-fixtures.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC1F,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE7D,eAAO,MAAM,IAAI,EAAE,YASlB,CAAC;AAEF,eAAO,MAAM,KAAK,GAAI,QAAQ,MAAM,KAAG,KAKrC,CAAC;AAEH,eAAO,MAAM,OAAO,GAAI,QAAQ,MAAM,EAAE,MAAM,MAAM,EAAE,QAAQ,OAAO,CAAC,QAAQ,CAAC,KAAG,OAUhF,CAAC;AAEH,eAAO,MAAM,OAAO,GAAI,QAAQ,MAAM,KAAG,OAOvC,CAAC;AAEH,eAAO,MAAM,KAAK,GAAI,OAAO,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,aACO,CAAC;AAElF;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,cAAc,GAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAM;;;;iBAE/C,MAAM;mBAAa,MAAM;kBAAY,SAAS,OAAO,EAAE;;EAiC7F;AAED,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC;;6BAKjD,OAAO,OAAO,WAAW;;;EAOtC"}

package/dist/child-iterate-fixtures.js

@@ -0,0 +1,86 @@
+export const task = {
+    id: 'task-1',
+    goal: 'ship the feature',
+    constraints: [],
+    budget: { tokens: 1000, usd: 1, wallClockMin: 10 },
+    evidence: [],
+    definitionOfDone: [],
+    authorityCeiling: 'suggest',
+    overlay: 'repo',
+};
+export const brief = (taskId) => ({
+    taskId,
+    sections: [],
+    budget: { allotted: 10, used: 0 },
+    compilerVersion: 'scripted-1',
+});
+export const verdict = (taskId, gate, result) => ({
+    taskId,
+    gate,
+    result,
+    confidence: 1,
+    findings: result === 'approve' || result === 'pass'
+        ? []
+        : [{ severity: 'error', message: `${gate} wants ${taskId} fixed` }],
+    cost: { tokens: 0, usd: 0 },
+});
+export const outcome = (taskId) => ({
+    taskId,
+    status: 'success',
+    signals: [],
+    cost: { tokens: 0, usd: 0 },
+    traceRef: `trace-${taskId}`,
+    distillCandidates: [],
+});
+export const names = (trace) => trace.map((t) => (t.childId === undefined ? t.node : `${t.node}:${t.childId}`));
+/**
+ * A scripted executor set. `qualityByChild` maps a child id to its sequence of
+ * quality results (last entry repeats). Records each implement's NodeContext so
+ * tests can assert the folded child findings + childIteration.
+ */
+export function scripted(qualityByChild = {}) {
+    const qualityCalls = {};
+    const implementCtx = [];
+    const executors = {
+        frame: () => Promise.resolve(task),
+        research: () => Promise.resolve(brief(task.id)),
+        plan: () => Promise.resolve(brief(task.id)),
+        vote: (_i, ctx) => Promise.resolve(verdict(ctx.taskId, 'vote', 'approve')),
+        decompose: () => Promise.resolve([
+            { ...task, id: `${task.id}.c1`, parent: task.id },
+            { ...task, id: `${task.id}.c2`, parent: task.id },
+        ]),
+        implement: (input, ctx) => {
+            const c = input;
+            implementCtx.push({
+                childId: c.id,
+                iteration: ctx.childIteration ?? -1,
+                findings: ctx.findings,
+            });
+            return Promise.resolve(outcome(c.id));
+        },
+        quality: (_i, ctx) => {
+            const id = ctx.child?.id ?? ctx.taskId;
+            const seq = qualityByChild[id] ?? ['pass'];
+            const n = qualityCalls[id] ?? 0;
+            qualityCalls[id] = n + 1;
+            return Promise.resolve(verdict(id, 'quality', seq[Math.min(n, seq.length - 1)] ?? 'pass'));
+        },
+        review: (_i, ctx) => Promise.resolve(verdict(ctx.child?.id ?? ctx.taskId, 'review', 'approve')),
+        integrate: () => Promise.resolve(outcome(task.id)),
+        retrospect: (input) => Promise.resolve(input),
+    };
+    return { executors, qualityCalls, implementCtx };
+}
+export function counted(executors) {
+    const calls = {};
+    const wrapped = Object.fromEntries(Object.entries(executors).map(([key, fn]) => [
+        key,
+        (input, ctx) => {
+            calls[key] = (calls[key] ?? 0) + 1;
+            return fn(input, ctx);
+        },
+    ]));
+    return { executors: wrapped, calls };
+}
+//# sourceMappingURL=child-iterate-fixtures.js.map

package/dist/child-iterate-fixtures.js.map

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

package/dist/child-iterate.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The review-driven child iteration back-edge [CLM-0043] — the actor-critic
+ * inner loop. It MIRRORS the proven vote→plan machinery (steps.ts
+ * `advanceVote`): the branching lives in `advanceChild`, NOT in the graph,
+ * which stays frozen and acyclic. When a child's quality gate rejects and the
+ * child is still within its Kc bound (and the run is within budget), the
+ * cursor resets to the child's `implement` sub-node, the gate's findings fold
+ * into `child.findings` (read by the coder's next attempt), and the child's
+ * `iteration` increments — the same shape as a rejected vote re-entering plan.
+ *
+ * At the bound (Kc exhausted OR budget exceeded) the child is marked
+ * `escalated` with its findings recorded, and the fan-out advances to the next
+ * child: one stuck child must not sink the sprint. On a passing quality gate
+ * the chain advances through review to the next child (today's behavior).
+ *
+ * HONESTY GUARD: the review gate is advisory (CLM-0064) and does NOT drive
+ * iteration by default. Quality drives the loop; review findings ride along as
+ * non-gating hints folded into the next attempt. Review-driven iteration is
+ * gated behind `reviewDrivesIteration` (default off) — enabled only when the
+ * review gate is promoted to enforce; we never claim review enforces.
+ */
+import type { Finding, Verdict } from '@kernloop/contracts';
+import type { LoopNode } from './graph.js';
+import type { ChildResult, RunState } from './state.js';
+/** How a child sub-gate's verdict steers the fan-out cursor. */
+export type ChildBranch = 'pass' | 'reiterate' | 'escalate';
+/** An audit event fired on each child re-iteration (the CLI wires it to the chain). */
+export interface ChildIterateEvent {
+    readonly childId: string;
+    readonly iteration: number;
+    readonly gate: string;
+    readonly findingCount: number;
+}
+/** Which gates drive child iteration this run — flags the engine resolves from
+ * config (review at enforce; parsimony at intensity full/ultra). */
+export interface IterationDrivers {
+    readonly reviewDrives: boolean;
+    readonly parsimonyDrives: boolean;
+}
+/**
+ * Whether THIS gate sub-node drives child iteration. Quality always drives.
+ * Review drives only when `reviewDrives` is on (the review gate is at enforce)
+ * — the honesty guard. Parsimony drives only when `parsimonyDrives` is on (the
+ * overlay's `gates.parsimony.intensity` is full/ultra, #9/#415) — at lite/off it
+ * is advisory/disabled. Non-driving gates never trigger a re-implement; their
+ * findings still fold in as hints (see {@link foldHints}).
+ */
+export declare function gateDrivesIteration(node: LoopNode, drivers: IterationDrivers): boolean;
+/**
+ * Decide the branch after a driving gate ran for a child. `pass` advances the
+ * sub-chain; `reiterate` re-runs implement (within Kc and budget); `escalate`
+ * stops the child at the bound. `withinBudget` is false when a re-entry would
+ * exceed the run budget (Part B) — that forces `escalate` before Kc.
+ *
+ * An `escalate` VERDICT (#192) — the gate ruling "a human must decide" — forces
+ * `escalate` IMMEDIATELY, regardless of Kc or budget: a human ruling is not a
+ * re-attempt. Routing goes through {@link verdictDisposition} so a future
+ * `VerdictResult` value is a compile error here, never a silent mis-branch.
+ */
+export declare function childBranch(verdict: Verdict, result: ChildResult, kc: number, withinBudget: boolean): ChildBranch;
+/** Fold a non-driving gate's findings into the child as hints (review → next attempt). */
+export declare function foldHints(result: ChildResult, findings: readonly Finding[]): void;
+/**
+ * Re-enter the child's implement sub-node: fold the driving gate's findings,
+ * bump the child iteration, reset the sub-cursor to 0 (implement). Mirrors a
+ * rejected vote pushing findings and re-entering plan.
+ */
+export declare function reiterateChild(state: RunState, result: ChildResult, findings: readonly Finding[]): void;
+/** Mark a child escalated at the bound: record the findings, never re-attempt. */
+export declare function escalateChild(result: ChildResult, findings: readonly Finding[]): void;
+//# sourceMappingURL=child-iterate.d.ts.map