@kernloop/workflows 0.1.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"child-iterate.d.ts","sourceRoot":"","sources":["../src/child-iterate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGxD,gEAAgE;AAChE,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,WAAW,GAAG,UAAU,CAAC;AAE5D,uFAAuF;AACvF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;oEACoE;AACpE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAKtF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,WAAW,EACnB,EAAE,EAAE,MAAM,EACV,YAAY,EAAE,OAAO,GACpB,WAAW,CAMb;AAED,0FAA0F;AAC1F,wBAAgB,SAAS,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAEjF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,QAAQ,EACf,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,SAAS,OAAO,EAAE,GAC3B,IAAI,CAKN;AAED,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAGrF"}

package/dist/child-iterate.js

@@ -0,0 +1,61 @@
+import { verdictDisposition } from './verdict-disposition.js';
+/**
+ * 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 function gateDrivesIteration(node, drivers) {
+    if (node.gate === 'quality')
+        return true;
+    if (node.gate === 'review')
+        return drivers.reviewDrives;
+    if (node.gate === 'parsimony')
+        return drivers.parsimonyDrives;
+    return false;
+}
+/**
+ * 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 function childBranch(verdict, result, kc, withinBudget) {
+    const disposition = verdictDisposition(verdict.result);
+    if (disposition === 'advance')
+        return 'pass';
+    if (disposition === 'escalate')
+        return 'escalate';
+    if (result.iteration >= kc || !withinBudget)
+        return 'escalate';
+    return 'reiterate';
+}
+/** Fold a non-driving gate's findings into the child as hints (review → next attempt). */
+export function foldHints(result, findings) {
+    result.findings.push(...findings);
+}
+/**
+ * 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 function reiterateChild(state, result, findings) {
+    if (state.cursor.phase !== 'fanout')
+        return;
+    result.findings.push(...findings);
+    result.iteration += 1;
+    state.cursor = { phase: 'fanout', childIndex: state.cursor.childIndex, sub: 0 };
+}
+/** Mark a child escalated at the bound: record the findings, never re-attempt. */
+export function escalateChild(result, findings) {
+    result.findings.push(...findings);
+    result.escalated = true;
+}
+//# sourceMappingURL=child-iterate.js.map

package/dist/child-iterate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-iterate.js","sourceRoot":"","sources":["../src/child-iterate.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAoB9D;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAc,EAAE,OAAyB;IAC3E,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACzC,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC,YAAY,CAAC;IACxD,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW;QAAE,OAAO,OAAO,CAAC,eAAe,CAAC;IAC9D,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CACzB,OAAgB,EAChB,MAAmB,EACnB,EAAU,EACV,YAAqB;IAErB,MAAM,WAAW,GAAG,kBAAkB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACvD,IAAI,WAAW,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IAC7C,IAAI,WAAW,KAAK,UAAU;QAAE,OAAO,UAAU,CAAC;IAClD,IAAI,MAAM,CAAC,SAAS,IAAI,EAAE,IAAI,CAAC,YAAY;QAAE,OAAO,UAAU,CAAC;IAC/D,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,SAAS,CAAC,MAAmB,EAAE,QAA4B;IACzE,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAe,EACf,MAAmB,EACnB,QAA4B;IAE5B,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO;IAC5C,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC;IAClC,MAAM,CAAC,SAAS,IAAI,CAAC,CAAC;IACtB,KAAK,CAAC,MAAM,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC,UAAU,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;AAClF,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,aAAa,CAAC,MAAmB,EAAE,QAA4B;IAC7E,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC;IAClC,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC;AAC1B,CAAC"}

package/dist/child-spend.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Per-child spend attribution for the fan-out (#56). Because the canonical loop
+ * runs children SEQUENTIALLY, the engine slices the run-global meter by the
+ * child boundary: snapshot an injected `meteredSpend` readout when it first
+ * steps into a child, and the delta to any later point is that child's spend,
+ * summed across all its Kc iterations. Pure of I/O — the engine owns the loop;
+ * this owns the arithmetic and the per-child budget verdict.
+ */
+import { type BudgetSpend } from './budget.js';
+import type { RunResult, RunState } from './state.js';
+/**
+ * Tracks the spend baseline of the child the fan-out is currently running and
+ * derives each child's attributed slice from the live meter. Unmetered (no
+ * `meteredSpend` seam) → every readout is undefined and nothing is attributed.
+ */
+export declare class ChildSpendTracker {
+    private readonly meteredSpend;
+    private baseline;
+    constructor(meteredSpend: (() => BudgetSpend) | undefined);
+    /**
+     * Start-of-loop reset: forget the baseline AND drop any pre-resume child spend
+     * (#212), so attribution is per-PROCESS — a resumed run re-attributes from the
+     * fresh meter and `childSpend` stays within the (also per-process) run cost.
+     */
+    reset(state: RunState): void;
+    /** Snapshot the meter as child `index`'s baseline the first time it is stepped. */
+    ensureBaseline(index: number): void;
+    /** Spend attributed to child `index` so far: meter now minus its baseline (≥ 0). */
+    delta(index: number): BudgetSpend | undefined;
+    /** Record child `index`'s attributed spend onto its result row (#56). */
+    attribute(state: RunState, index: number): void;
+    /**
+     * False when the CURRENT fan-out child has overspent its OWN sliced budget —
+     * gating re-iteration in ENFORCE mode only (`enforce` false → never halts
+     * per-child, mirroring the run-level discipline). Sibling-independent.
+     */
+    withinOwnBudget(enforce: boolean, state: RunState): boolean;
+}
+/** Per-child spend entries for a RunResult, or undefined when none was metered (#56). */
+export declare function childSpends(state: RunState): RunResult['childSpend'];
+//# sourceMappingURL=child-spend.d.ts.map

package/dist/child-spend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-spend.d.ts","sourceRoot":"","sources":["../src/child-spend.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtD;;;;GAIG;AACH,qBAAa,iBAAiB;IAGhB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAFzC,OAAO,CAAC,QAAQ,CAAoD;gBAEvC,YAAY,EAAE,CAAC,MAAM,WAAW,CAAC,GAAG,SAAS;IAE1E;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAK5B,mFAAmF;IACnF,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAMnC,oFAAoF;IACpF,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAU7C,yEAAyE;IACzE,SAAS,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAM/C;;;;OAIG;IACH,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO;CAO5D;AAED,yFAAyF;AACzF,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,CAAC,YAAY,CAAC,CAKpE"}

package/dist/child-spend.js

@@ -0,0 +1,76 @@
+/**
+ * Per-child spend attribution for the fan-out (#56). Because the canonical loop
+ * runs children SEQUENTIALLY, the engine slices the run-global meter by the
+ * child boundary: snapshot an injected `meteredSpend` readout when it first
+ * steps into a child, and the delta to any later point is that child's spend,
+ * summed across all its Kc iterations. Pure of I/O — the engine owns the loop;
+ * this owns the arithmetic and the per-child budget verdict.
+ */
+import { childOverOwnBudget } from './budget.js';
+/**
+ * Tracks the spend baseline of the child the fan-out is currently running and
+ * derives each child's attributed slice from the live meter. Unmetered (no
+ * `meteredSpend` seam) → every readout is undefined and nothing is attributed.
+ */
+export class ChildSpendTracker {
+    meteredSpend;
+    baseline;
+    constructor(meteredSpend) {
+        this.meteredSpend = meteredSpend;
+    }
+    /**
+     * Start-of-loop reset: forget the baseline AND drop any pre-resume child spend
+     * (#212), so attribution is per-PROCESS — a resumed run re-attributes from the
+     * fresh meter and `childSpend` stays within the (also per-process) run cost.
+     */
+    reset(state) {
+        this.baseline = undefined;
+        for (const r of state.childResults)
+            r.spend = undefined;
+    }
+    /** Snapshot the meter as child `index`'s baseline the first time it is stepped. */
+    ensureBaseline(index) {
+        const spend = this.meteredSpend?.();
+        if (spend === undefined || this.baseline?.index === index)
+            return;
+        this.baseline = { index, spend };
+    }
+    /** Spend attributed to child `index` so far: meter now minus its baseline (≥ 0). */
+    delta(index) {
+        const spend = this.meteredSpend?.();
+        if (spend === undefined || this.baseline?.index !== index)
+            return undefined;
+        const base = this.baseline.spend;
+        return {
+            tokens: Math.max(0, spend.tokens - base.tokens),
+            usd: Math.max(0, spend.usd - base.usd),
+        };
+    }
+    /** Record child `index`'s attributed spend onto its result row (#56). */
+    attribute(state, index) {
+        const d = this.delta(index);
+        const result = state.childResults[index];
+        if (d !== undefined && result !== undefined)
+            result.spend = d;
+    }
+    /**
+     * False when the CURRENT fan-out child has overspent its OWN sliced budget —
+     * gating re-iteration in ENFORCE mode only (`enforce` false → never halts
+     * per-child, mirroring the run-level discipline). Sibling-independent.
+     */
+    withinOwnBudget(enforce, state) {
+        if (!enforce || state.cursor.phase !== 'fanout')
+            return true;
+        const d = this.delta(state.cursor.childIndex);
+        const result = state.childResults[state.cursor.childIndex];
+        if (d === undefined || result === undefined)
+            return true;
+        return !childOverOwnBudget(result.child.budget, d);
+    }
+}
+/** Per-child spend entries for a RunResult, or undefined when none was metered (#56). */
+export function childSpends(state) {
+    const entries = state.childResults.flatMap((r) => r.spend === undefined ? [] : [{ childId: r.child.id, spend: r.spend }]);
+    return entries.length > 0 ? entries : undefined;
+}
+//# sourceMappingURL=child-spend.js.map

package/dist/child-spend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-spend.js","sourceRoot":"","sources":["../src/child-spend.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,kBAAkB,EAAoB,MAAM,aAAa,CAAC;AAGnE;;;;GAIG;AACH,MAAM,OAAO,iBAAiB;IAGC;IAFrB,QAAQ,CAAoD;IAEpE,YAA6B,YAA6C;QAA7C,iBAAY,GAAZ,YAAY,CAAiC;IAAG,CAAC;IAE9E;;;;OAIG;IACH,KAAK,CAAC,KAAe;QACnB,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC;QAC1B,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,YAAY;YAAE,CAAC,CAAC,KAAK,GAAG,SAAS,CAAC;IAC1D,CAAC;IAED,mFAAmF;IACnF,cAAc,CAAC,KAAa;QAC1B,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC;QACpC,IAAI,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,EAAE,KAAK,KAAK,KAAK;YAAE,OAAO;QAClE,IAAI,CAAC,QAAQ,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IACnC,CAAC;IAED,oFAAoF;IACpF,KAAK,CAAC,KAAa;QACjB,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC;QACpC,IAAI,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,EAAE,KAAK,KAAK,KAAK;YAAE,OAAO,SAAS,CAAC;QAC5E,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QACjC,OAAO;YACL,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;YAC/C,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;SACvC,CAAC;IACJ,CAAC;IAED,yEAAyE;IACzE,SAAS,CAAC,KAAe,EAAE,KAAa;QACtC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC5B,MAAM,MAAM,GAAG,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS;YAAE,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC;IAChE,CAAC;IAED;;;;OAIG;IACH,eAAe,CAAC,OAAgB,EAAE,KAAe;QAC/C,IAAI,CAAC,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC7D,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC9C,MAAM,MAAM,GAAG,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC3D,IAAI,CAAC,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACzD,OAAO,CAAC,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACrD,CAAC;CACF;AAED,yFAAyF;AACzF,MAAM,UAAU,WAAW,CAAC,KAAe;IACzC,MAAM,OAAO,GAAG,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAC/C,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CACvE,CAAC;IACF,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AAClD,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Engine configuration schema (spec §6, §8). EngineConfig is the loop-relevant
+ * subset of the cli's `OverlaySchema` (`packages/cli/src/overlay.ts`): `K`,
+ * `Kc`, `reviewDrivesIteration`, `gates.vote.{strategy,panel}`, and
+ * `nodeOverrides` share its field names and value spaces, so the composition
+ * root maps `Overlay` → `EngineConfig` field-for-field [CLM-0045]. Kept apart
+ * from the engine so neither file outgrows the 400-line budget.
+ */
+import { z } from 'zod';
+/** Engine configuration — see the module docs for the overlay mapping. */
+export declare const EngineConfigSchema: z.ZodPrefault<z.ZodObject<{
+    K: z.ZodDefault<z.ZodNumber>;
+    Kc: z.ZodDefault<z.ZodNumber>;
+    reviewDrivesIteration: z.ZodDefault<z.ZodBoolean>;
+    parsimonyDrivesIteration: z.ZodDefault<z.ZodBoolean>;
+    budgetHeadroomFraction: z.ZodDefault<z.ZodNumber>;
+    gates: z.ZodPrefault<z.ZodObject<{
+        vote: z.ZodPrefault<z.ZodObject<{
+            strategy: z.ZodDefault<z.ZodEnum<{
+                simple_majority: "simple_majority";
+                supermajority: "supermajority";
+                unanimous: "unanimous";
+            }>>;
+            panel: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<3>, z.ZodLiteral<7>]>>;
+            providerDiverse: z.ZodDefault<z.ZodBoolean>;
+            escalateOnNoConsensus: z.ZodDefault<z.ZodBoolean>;
+            precisionWeighted: z.ZodDefault<z.ZodBoolean>;
+            correlationAware: z.ZodDefault<z.ZodBoolean>;
+            correlationForm: z.ZodDefault<z.ZodEnum<{
+                sqrt: "sqrt";
+                linear: "linear";
+            }>>;
+            minDistinctClasses: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    nodeOverrides: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        gate: z.ZodOptional<z.ZodString>;
+        specialists: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>>;
+export type EngineConfig = z.infer<typeof EngineConfigSchema>;
+export type EngineConfigInput = z.input<typeof EngineConfigSchema>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA2CxB,0EAA0E;AAC1E,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBAuChB,CAAC;AAChB,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/config.js

@@ -0,0 +1,90 @@
+/**
+ * Engine configuration schema (spec §6, §8). EngineConfig is the loop-relevant
+ * subset of the cli's `OverlaySchema` (`packages/cli/src/overlay.ts`): `K`,
+ * `Kc`, `reviewDrivesIteration`, `gates.vote.{strategy,panel}`, and
+ * `nodeOverrides` share its field names and value spaces, so the composition
+ * root maps `Overlay` → `EngineConfig` field-for-field [CLM-0045]. Kept apart
+ * from the engine so neither file outgrows the 400-line budget.
+ */
+import { z } from 'zod';
+/** Vote strategies in use (mirrors the cli overlay's VOTE_STRATEGIES). */
+const VoteConfigSchema = z.strictObject({
+    strategy: z.enum(['simple_majority', 'supermajority', 'unanimous']).default('simple_majority'),
+    panel: z.union([z.literal(3), z.literal(7)]).default(3),
+    /** Opt-in PROVIDER-DIVERSE panel-7 voting (#369). Default FALSE (#461): a live
+     * experiment found 3 independent model families gave identical verdicts to a
+     * single strong model on every test proposal — the adversarial ROLES carry the
+     * signal, so a panel-7 ratification vote runs roles-on-the-run-adapter by default
+     * (one model, N personas) and does not require ≥2 authed adapters. Set true to
+     * route voters across the overlay's distinct CLI adapters for genuine model
+     * independence (the #405 distinct-class quorum + diversity findings then engage);
+     * off ⇒ no served identities, so the quorum/findings are inert. */
+    providerDiverse: z.boolean().default(false),
+    /** Opt-in ASK (#192): a deadlocked panel emits `escalate` → the loop halts as
+     * escalated for a human, instead of auto-rejecting. Default off (byte-identical).
+     * Liveness tradeoff (#364): in an UNATTENDED loop there is no "next interaction",
+     * so `escalate` halts indefinitely — keep off for autonomous runs. */
+    escalateOnNoConsensus: z.boolean().default(false),
+    /** Opt-in precision-weighted voting (#369 Inc3): weight each ballot by the
+     * voter's measured calibration. Default off (byte-identical). */
+    precisionWeighted: z.boolean().default(false),
+    /** Opt-in correlation-aware aggregation (#369 Inc4): downweight voters that share
+     * a served model class by `correlationDiscount(form, K)`. Default off (byte-identical);
+     * inert on a single-adapter panel. Mirrors the cli overlay's VoteGateSchema. */
+    correlationAware: z.boolean().default(false),
+    /** The `correlationAware` discount form (#369 Inc4): `sqrt` ⇒ 1/√K, `linear` ⇒ 1/K. */
+    correlationForm: z.enum(['sqrt', 'linear']).default('sqrt'),
+    /** Distinct-class independence quorum (#405/#369 Inc5b): require ≥ this many distinct
+     * served model classes on a diverse panel else the vote ESCALATES to a human instead
+     * of ruling. Absent ⇒ defaults to 2 for a panel-7 RATIFICATION vote (the human-ratified
+     * default-on), off for a panel-3 loop vote; set to 1 to disable it on a ratification
+     * panel. Inert on a single-adapter / endpoint-only panel (no served identities). */
+    minDistinctClasses: z.number().int().min(0).optional(),
+});
+/** One node override (mirrors the cli overlay's NodeOverrideSchema). */
+const NodeOverrideSchema = z.strictObject({
+    gate: z.string().min(1).optional(),
+    specialists: z.array(z.string().min(1)).optional(),
+});
+/** Engine configuration — see the module docs for the overlay mapping. */
+export const EngineConfigSchema = z
+    .strictObject({
+    /** Vote-iterate bound: at most K rejected re-entries into plan (spec §6). */
+    K: z.number().int().min(1).default(3),
+    /**
+     * Child-iterate bound [CLM-0043]: at most Kc re-runs of a child's
+     * implement on a quality reject before the child escalates (spec §6, §8).
+     * Bounds child iteration in BOTH budget modes — unlimited budget is not
+     * unlimited iterations; raising Kc is how an overlay allows more.
+     */
+    Kc: z.number().int().min(1).default(3),
+    /**
+     * Honesty guard (CLM-0064): the review gate is advisory and does NOT drive
+     * child iteration. Default off; an overlay flips it on only when the review
+     * gate is promoted to enforce. We never claim review enforces iteration.
+     */
+    reviewDrivesIteration: z.boolean().default(false),
+    /**
+     * Does the parsimony gate drive child re-iteration this run (#9/#415)? The
+     * CLI computes this from the overlay's `gates.parsimony.intensity`: true at
+     * `full`/`ultra` (a rejecting parsimony verdict re-runs implement within Kc),
+     * false at `lite`/`off` (advisory or disabled). Default false ⇒ a fresh
+     * EngineConfig is byte-identical (the engine never drives parsimony unless the
+     * mapping flips it). The INTENSITY itself lives in the cli Overlay
+     * (`gates.parsimony`) and reaches the executor via `kern.config`; only this
+     * derived drive-flag the engine needs is mirrored here [CLM-0045].
+     */
+    parsimonyDrivesIteration: z.boolean().default(false),
+    /**
+     * Pre-node budget reserve floor as a FRACTION of the limit (#342): the
+     * pre-node guard halts before a node when remaining < max(this × limit,
+     * largest-node-seen). The floor covers COLD START (the first node, before any
+     * spend is observed). Default 0 — observed-max still caps steady-state
+     * overshoot; an overlay raises this to also bound the first node.
+     */
+    budgetHeadroomFraction: z.number().min(0).max(1).default(0),
+    gates: z.strictObject({ vote: VoteConfigSchema.prefault({}) }).prefault({}),
+    nodeOverrides: z.record(z.string().min(1), NodeOverrideSchema).default({}),
+})
+    .prefault({});
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/engine-errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Engine error classification (split from engine.ts to keep it under the LOC
+ * budget, #58): the "kill" path vs an executor failure. Pure helpers the loop
+ * calls when a node throws.
+ */
+import { WorkflowError } from './state.js';
+/** True for AbortError throws and fired signals — the "kill" path [CLM-0044]. */
+export declare function isAbort(error: unknown, signal?: AbortSignal): boolean;
+/** Wrap a non-engine throw in a typed WorkflowError. */
+export declare function asWorkflowError(error: unknown, node: string, signal?: AbortSignal): WorkflowError;
+//# sourceMappingURL=engine-errors.d.ts.map

package/dist/engine-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-errors.d.ts","sourceRoot":"","sources":["../src/engine-errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,iFAAiF;AACjF,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAErE;AAED,wDAAwD;AACxD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,aAAa,CASjG"}

package/dist/engine-errors.js

@@ -0,0 +1,23 @@
+/**
+ * Engine error classification (split from engine.ts to keep it under the LOC
+ * budget, #58): the "kill" path vs an executor failure. Pure helpers the loop
+ * calls when a node throws.
+ */
+import { WorkflowError } from './state.js';
+/** True for AbortError throws and fired signals — the "kill" path [CLM-0044]. */
+export function isAbort(error, signal) {
+    return signal?.aborted === true || (error instanceof Error && error.name === 'AbortError');
+}
+/** Wrap a non-engine throw in a typed WorkflowError. */
+export function asWorkflowError(error, node, signal) {
+    if (error instanceof WorkflowError)
+        return error;
+    const message = error instanceof Error ? error.message : String(error);
+    return isAbort(error, signal)
+        ? new WorkflowError('aborted', `run aborted at node "${node}": ${message}`, { node })
+        : new WorkflowError('executor_failed', `node "${node}" failed: ${message}`, {
+            node,
+            cause: error,
+        });
+}
+//# sourceMappingURL=engine-errors.js.map

package/dist/engine-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-errors.js","sourceRoot":"","sources":["../src/engine-errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,iFAAiF;AACjF,MAAM,UAAU,OAAO,CAAC,KAAc,EAAE,MAAoB;IAC1D,OAAO,MAAM,EAAE,OAAO,KAAK,IAAI,IAAI,CAAC,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC,CAAC;AAC7F,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,eAAe,CAAC,KAAc,EAAE,IAAY,EAAE,MAAoB;IAChF,IAAI,KAAK,YAAY,aAAa;QAAE,OAAO,KAAK,CAAC;IACjD,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC;QAC3B,CAAC,CAAC,IAAI,aAAa,CAAC,SAAS,EAAE,wBAAwB,IAAI,MAAM,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;QACrF,CAAC,CAAC,IAAI,aAAa,CAAC,iBAAiB,EAAE,SAAS,IAAI,aAAa,OAAO,EAAE,EAAE;YACxE,IAAI;YACJ,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;AACT,CAAC"}

package/dist/engine-testkit.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared scripted-executor harness for the engine tests (child iteration,
+ * budget, per-child spend). A deterministic stand-in for the real faculties:
+ * every node returns a canned contract so a test drives the loop's CONTROL
+ * flow (re-iterate, escalate, attribute) without any model call. Not test code
+ * itself — it carries no `describe`/`it`; the `.test.ts` files import it.
+ */
+import type { Brief, Finding, Outcome, TaskContract, Verdict } from '@kernloop/contracts';
+import type { NodeContext, NodeExecutor } from './engine.js';
+/** The root task every engine test decomposes. */
+export declare const task: TaskContract;
+/** A scripted compiler Brief for `taskId`. */
+export declare const brief: (taskId: string) => Brief;
+/** A scripted gate Verdict; a non-pass result carries one finding to fold. */
+export declare const verdict: (taskId: string, gate: string, result: Verdict["result"]) => Verdict;
+/** A scripted success Outcome for `taskId`. */
+export declare const outcome: (taskId: string) => Outcome;
+/** Render a trace as `node[:childId]` labels for order assertions. */
+export declare const names: (trace: readonly {
+    node: string;
+    childId?: string;
+}[]) => string[];
+/**
+ * A scripted executor set. `qualityByChild` maps a child id to the sequence of
+ * quality results it returns (last entry repeats). Records every 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[];
+    }[];
+};
+/** Wrap executors to count calls per node name. */
+export declare function counted(executors: Record<string, NodeExecutor>): {
+    executors: {
+        [k: string]: (input: unknown, ctx: NodeContext) => Promise<unknown>;
+    };
+    calls: Record<string, number>;
+};
+//# sourceMappingURL=engine-testkit.d.ts.map

package/dist/engine-testkit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-testkit.d.ts","sourceRoot":"","sources":["../src/engine-testkit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;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,kDAAkD;AAClD,eAAO,MAAM,IAAI,EAAE,YASlB,CAAC;AAEF,8CAA8C;AAC9C,eAAO,MAAM,KAAK,GAAI,QAAQ,MAAM,KAAG,KAKrC,CAAC;AAEH,8EAA8E;AAC9E,eAAO,MAAM,OAAO,GAAI,QAAQ,MAAM,EAAE,MAAM,MAAM,EAAE,QAAQ,OAAO,CAAC,QAAQ,CAAC,KAAG,OAUhF,CAAC;AAEH,+CAA+C;AAC/C,eAAO,MAAM,OAAO,GAAI,QAAQ,MAAM,KAAG,OAOvC,CAAC;AAEH,sEAAsE;AACtE,eAAO,MAAM,KAAK,GAAI,OAAO,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,KAAG,MAAM,EACF,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;;EAmC7F;AAED,mDAAmD;AACnD,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC;;6BAKjD,OAAO,OAAO,WAAW;;;EAOtC"}

package/dist/engine-testkit.js

@@ -0,0 +1,93 @@
+/** The root task every engine test decomposes. */
+export const task = {
+    id: 'task-1',
+    goal: 'ship the feature',
+    constraints: [],
+    budget: { tokens: 1000, usd: 1, wallClockMin: 10 },
+    evidence: [],
+    definitionOfDone: [],
+    authorityCeiling: 'suggest',
+    overlay: 'repo',
+};
+/** A scripted compiler Brief for `taskId`. */
+export const brief = (taskId) => ({
+    taskId,
+    sections: [],
+    budget: { allotted: 10, used: 0 },
+    compilerVersion: 'scripted-1',
+});
+/** A scripted gate Verdict; a non-pass result carries one finding to fold. */
+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 },
+});
+/** A scripted success Outcome for `taskId`. */
+export const outcome = (taskId) => ({
+    taskId,
+    status: 'success',
+    signals: [],
+    cost: { tokens: 0, usd: 0 },
+    traceRef: `trace-${taskId}`,
+    distillCandidates: [],
+});
+/** Render a trace as `node[:childId]` labels for order assertions. */
+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 the sequence of
+ * quality results it returns (last entry repeats). Records every 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')),
+        parsimony: (_i, ctx) => Promise.resolve(verdict(ctx.child?.id ?? ctx.taskId, 'parsimony', 'pass')),
+        integrate: () => Promise.resolve(outcome(task.id)),
+        retrospect: (input) => Promise.resolve(input),
+    };
+    return { executors, qualityCalls, implementCtx };
+}
+/** Wrap executors to count calls per node name. */
+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=engine-testkit.js.map

package/dist/engine-testkit.js.map

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

package/dist/engine-types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The execution engine's public type surface — the contracts a caller of
+ * `createEngine` touches: the per-node {@link NodeContext}, the injected
+ * {@link NodeExecutor}, the {@link EngineDeps} bag, {@link RunOptions}, and the
+ * {@link Engine} interface itself. Split out of engine.ts to keep that file under
+ * the 400-line ceiling (#58); engine.ts re-exports every name here, so consumers
+ * still import from `./engine.js` (or `@kernloop/workflows`) unchanged.
+ */
+import type { Finding, TaskContract } from '@kernloop/contracts';
+import type { CheckpointStore } from './checkpoints.js';
+import type { RunResult } from './state.js';
+import type { BudgetGuard, BudgetSpend } from './budget.js';
+import type { ChildIterateEvent } from './child-iterate.js';
+import type { EngineConfig, EngineConfigInput } from './config.js';
+/** Per-invocation context handed to every node executor. */
+export interface NodeContext {
+    readonly runId: string;
+    readonly taskId: string;
+    /** Vote-iterate cycle count: 0 on first entry, +1 per rejected re-entry. */
+    readonly iteration: number;
+    readonly config: EngineConfig;
+    /** The node being executed (resolved gate executors see the gate node). */
+    readonly node: string;
+    /**
+     * Findings the executing node must address: the run-level vote-iterate
+     * findings on the main chain; inside the fan-out the CHILD's accumulated gate
+     * findings — what the re-running coder must fix [CLM-0043].
+     */
+    readonly findings: readonly Finding[];
+    /** The child contract, inside the fan-out sub-chain. */
+    readonly child?: TaskContract;
+    /** This child's actor-critic iteration (0 on first implement), inside the fan-out. */
+    readonly childIteration?: number;
+    readonly signal?: AbortSignal;
+}
+/** An injected unit of work: consumes the edge value, emits the declared contract. */
+export type NodeExecutor = (input: unknown, ctx: NodeContext) => Promise<unknown>;
+/** What `createEngine` needs. Executors are keyed by node name, node kind, or gate name. */
+export interface EngineDeps {
+    readonly executors: Readonly<Record<string, NodeExecutor>>;
+    readonly checkpoints: CheckpointStore;
+    readonly config?: EngineConfigInput;
+    /**
+     * Runtime budget guard (spec §8) [CLM-0077]. Absent → no budget enforcement
+     * (Kc still bounds child iteration). In `enforce` mode the run escalates when
+     * metered spend exceeds the parent budget; `unlimited` never halts but spend
+     * is still tracked. Injected by the CLI from the mode + parent budget + live
+     * `totals`; workflows imports no kernel, so `spent()` is a plain seam.
+     */
+    readonly budget?: BudgetGuard;
+    /**
+     * Always-on metered-spend readout for PER-CHILD attribution (#56) — the raw
+     * run-global meter the engine snapshots at each child boundary to slice spend
+     * per child (see {@link ChildSpendTracker}), in BOTH budget modes. Absent → no
+     * per-child attribution or halt. The CLI wires it to the budget guard's
+     * `totals`; workflows imports no kernel, so this is a plain seam.
+     */
+    readonly meteredSpend?: () => BudgetSpend;
+    /**
+     * Audit hook fired on each child re-iteration [CLM-0043] — the CLI appends a
+     * `loop.child.iterate` event to the hash chain so the refine history is
+     * recorded (the Observer can later read iterations-to-pass as fitness).
+     */
+    readonly onChildIterate?: (event: ChildIterateEvent) => void;
+}
+/** Per-run options. */
+export interface RunOptions {
+    /** Caller-chosen run id (defaults to a UUID). */
+    readonly runId?: string;
+    /** Abort signal: an aborted run halts mid-node, last checkpoint intact. */
+    readonly signal?: AbortSignal;
+}
+/** The engine: run the canonical loop, or resume a checkpointed run. */
+export interface Engine {
+    run(task: TaskContract, options?: RunOptions): Promise<RunResult>;
+    resume(runId: string, options?: Pick<RunOptions, 'signal'>): Promise<RunResult>;
+}
+//# sourceMappingURL=engine-types.d.ts.map

package/dist/engine-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-types.d.ts","sourceRoot":"","sources":["../src/engine-types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEnE,4DAA4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,wDAAwD;IACxD,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;IAC9B,sFAAsF;IACtF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,sFAAsF;AACtF,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAElF,4FAA4F;AAC5F,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;IAC3D,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,WAAW,CAAC;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC9D;AAED,uBAAuB;AACvB,MAAM,WAAW,UAAU;IACzB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,wEAAwE;AACxE,MAAM,WAAW,MAAM;IACrB,GAAG,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAClE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACjF"}

package/dist/engine-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=engine-types.js.map

package/dist/engine-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-types.js","sourceRoot":"","sources":["../src/engine-types.ts"],"names":[],"mappings":""}