@zelari/core 1.28.0 → 1.30.0

package/dist/kraken/runtime/types.d.ts

@@ -0,0 +1,220 @@
+/**
+ * Kraken script runtime — public types.
+ *
+ * A Kraken "script plan" is a TypeScript module the planner emits (or a user
+ * hands in) that imports the SDK from `@zelari/kraken-runtime` and calls
+ * `tentacle()`, `merge()`, `checkpoint()`, etc. The runtime compiles the
+ * module with esbuild (CLI side), loads it in a Node `vm` context with a
+ * capability-based sandbox, and runs it. Every call into the SDK is a
+ * bridge from the sandboxed script to the parent process — there is no
+ * direct filesystem, process, or network access in the script.
+ *
+ * Safety invariants (see F1.1 in `.zelari/docs/kraken-best-in-class-roadmap.md`):
+ *   - The script cannot read `process.env` or `fs` outside the SDK.
+ *   - Every `tentacle()` call increments a counter; the run aborts past
+ *     `MAX_TENTACLES` (default 200) regardless of what the script does.
+ *   - The script runs under a wall-clock budget (`ZELARI_KRAKEN_PLAN_TIMEOUT_MS`,
+ *     default 30 minutes) enforced by the `vm` timeout.
+ *   - `merge()` is one-shot per plan: a second call throws `PlanError` and
+ *     the run is settled.
+ *
+ * @since Kraken v1.30.x — workflow script runtime (F1.1)
+ */
+import type { z } from 'zod';
+import type { TaskNodeKind, TaskNodeStatus } from '../graph.js';
+/** A node the script plans to spawn. Mirrors the JSON-DAG shape for parity. */
+export interface TentacleOptions<T = unknown> {
+    /** What kind of subagent this is. */
+    kind: TaskNodeKind;
+    /** Short label for status / radio (max 200 chars). */
+    label: string;
+    /** Full self-contained prompt handed to the subagent. */
+    prompt: string;
+    /** Path/glob allowlist. Required for parallel writers. */
+    scope?: string[];
+    /** Acceptance checklist enforced by the verify tentacle. */
+    acceptance?: string[];
+    /** Upstream tentacle refs whose results are injected as context. */
+    deps?: TentacleRef[];
+    /**
+     * Optional Zod schema. If set, the subagent is asked to emit JSON matching
+     * the schema as its final message; the parsed result is exposed as
+     * `TentacleRef.result`. Use for structured hand-offs between tentacles.
+     */
+    outputSchema?: z.ZodType<T>;
+    /** Tool-call budget. Default: `deep` for writers, `medium` for readers. */
+    thoroughness?: 'quick' | 'medium' | 'deep';
+    /** Model override. Default: routed by `krakenModel` per kind. */
+    model?: string;
+    /** Max retries before the node is left `error` (no fix-node spawn). */
+    maxRetries?: number;
+    /** Wall-clock cap (ms) for this single tentacle. 0 disables. */
+    maxRuntimeMs?: number;
+}
+/**
+ * A reference to a tentacle the script spawned. The `result` is populated
+ * only when the subagent emitted a parseable JSON matching `outputSchema`;
+ * otherwise the raw `findings` text is the fallback.
+ */
+export interface TentacleRef<T = unknown> {
+    id: string;
+    kind: TaskNodeKind;
+    label: string;
+    status: TaskNodeStatus;
+    /** Parsed JSON if `outputSchema` was set and the subagent emitted it. */
+    result?: T;
+    /** Raw text conclusion (always populated, capped to `MAX_FINDINGS_CHARS`). */
+    findings: string;
+    /** Verdict trailer for `verify` / `spec` / `conformance` tentacles. */
+    verdict?: 'pass' | 'fail' | 'unknown';
+    scope?: string[];
+    durationMs?: number;
+    worktree?: string | null;
+}
+/** How a `merge()` call should land the worktrees in the parent HEAD. */
+export type MergeStrategy = 'squash' | 'squash-sequential' | 'rebase' | 'manual';
+export interface MergeOptions {
+    strategy?: MergeStrategy;
+    message?: string;
+    /** Delete the worktrees after a successful merge. Default: true. */
+    cleanup?: boolean;
+}
+/** Per-tentacle outcome from the runtime's perspective. */
+export interface MergeResult {
+    merged: string[];
+    conflicts: {
+        nodeId: string;
+        reason: string;
+    }[];
+    /** True when every input tentacle was merged without conflict. */
+    ok: boolean;
+}
+/** Snapshot of the running plan, persisted as JSON. */
+export interface PlanSnapshot {
+    graphId: string;
+    goal: string;
+    takenAt: string;
+    completed: TentacleRef[];
+    inFlight: TentacleRef[];
+    failed: TentacleRef[];
+    /** Tentacles the script already declared but not yet started. */
+    pending: TentacleRef[];
+}
+/** What the user (or a hook) can emit to the radio / workbench. */
+export interface EmitPayload {
+    kind: string;
+    detail?: string;
+    data?: Record<string, unknown>;
+}
+/** Error categories the script runtime can raise. */
+export type PlanErrorKind = 'budget_exceeded' | 'merge_already_done' | 'merge_conflict' | 'compile_error' | 'runtime_error' | 'sandbox_breach' | 'cancelled';
+/** Structured error from the runtime; scripts should not throw raw values. */
+export declare class PlanError extends Error {
+    readonly name = "PlanError";
+    readonly kind: PlanErrorKind;
+    readonly cause?: unknown;
+    constructor(kind: PlanErrorKind, message: string, cause?: unknown);
+}
+/** Capabilities injected into the script sandbox. Pure values + functions. */
+export interface PlanCapabilities {
+    tentacle<T = unknown>(opts: TentacleOptions<T>): Promise<TentacleRef<T>>;
+    /** Wait for N tentacles to complete (parallel); returns the same refs typed. */
+    barrier<T extends readonly TentacleRef[]>(refs: T): Promise<{
+        -readonly [K in keyof T]: T[K];
+    }>;
+    /** Race N tentacles; first to complete wins, others are cancelled. */
+    race<T extends readonly TentacleRef[]>(refs: T): Promise<T[number]>;
+    /** Bounded loop helper. Throws PlanError('budget_exceeded') past `maxIter`. */
+    while_<T>(cond: () => boolean | Promise<boolean>, body: () => Promise<T>, maxIter: number): Promise<T[]>;
+    until<T>(cond: () => boolean | Promise<boolean>, body: () => Promise<T>, maxIter: number): Promise<T[]>;
+    /** Sequential merge of N worktrees into the parent HEAD. */
+    merge(refs: readonly TentacleRef[], opts?: MergeOptions): Promise<MergeResult>;
+    /** Snapshot the current plan state to `.zelari/kraken/snapshots/<id>.json`. */
+    checkpoint(label?: string): Promise<PlanSnapshot>;
+    /** Structured log line to the radio + workbench. */
+    log(msg: string, data?: Record<string, unknown>): void;
+    /** Emit a custom radio event for downstream tools. */
+    emit(payload: EmitPayload): void;
+    /** Read-only access to the plan-level context (graph id, goal, etc.). */
+    getContext(): PlanContext;
+    /** Cross-session message: enqueue a message for `peerId` (a TentacleRef). */
+    sendTo(peerId: string, payload: EmitPayload): void;
+}
+/** Read-only metadata exposed to the script via `getContext()`. */
+export interface PlanContext {
+    graphId: string;
+    goal: string;
+    parentCwd: string;
+    sessionId: string;
+    /** Tentacles emitted so far, by id. */
+    tentacles: ReadonlyMap<string, TentacleRef>;
+    /** Tentacle cap (`ZELARI_KRAKEN_MAX_TENTACLES`, default 200). */
+    maxTentacles: number;
+    /** Wall-clock budget for the whole plan (ms). */
+    planTimeoutMs: number;
+}
+/** Bridge between the host (executor) and the script runtime. */
+export interface PlanHostBridge {
+    /**
+     * Run one tentacle, returning the raw host result. The runner turns this
+     * into a `TentacleRef` and parses verdicts where appropriate.
+     *
+     * `worktree` is the worktree path the host created for this tentacle, or
+     * `null` if none (read-only kinds). The script runtime uses it to drive
+     * `merge()` later.
+     */
+    runTentacle(args: {
+        node: TentacleOptions;
+        parentCwd: string;
+        sessionId: string;
+    }): Promise<HostTentacleResult>;
+    /** Merge N worktrees into the parent HEAD, sequentially. */
+    mergeWorktrees(args: {
+        refs: readonly TentacleRef[];
+        parentCwd: string;
+        strategy: MergeStrategy;
+        message?: string;
+        cleanup?: boolean;
+    }): Promise<MergeResult>;
+    /** Append a structured log line to the radio + workbench. */
+    log(line: string): void;
+    /** Persist a snapshot JSON to disk. */
+    saveSnapshot(snapshot: PlanSnapshot, dir: string): Promise<string>;
+    /** Read the abort signal; the script should respect it between awaits. */
+    signal(): AbortSignal | undefined;
+}
+/** Raw tentacle outcome from the host. The runner wraps this in a
+ *  `TentacleRef` and stashes it for snapshot / merge. */
+export interface HostTentacleResult {
+    ok: boolean;
+    /** Subagent's final text conclusion. Undefined on failure. */
+    result?: string;
+    /** Error message. Undefined on success. */
+    error?: string;
+    /** Wall-clock duration (ms). Optional; the host may not measure this. */
+    durationMs?: number;
+    /** Worktree path the host created, or null. */
+    worktree?: string | null;
+}
+/** What `runScriptPlan` returns to the executor — the same shape the JSON
+ *  DAG path returns, so the executor doesn't need to special-case the two. */
+export interface ScriptRunResult {
+    /** All tentacles that ran, keyed by id. */
+    tentacles: ReadonlyMap<string, TentacleRef>;
+    /** Number of `merge()` calls made. 0 = never merged, ≥1 = merged at least once. */
+    mergeCount: number;
+    /** Aggregate verdict surfaced to the workbench / digest. */
+    converged: boolean;
+    /** When the run stopped because the abort signal fired. */
+    cancelled: boolean;
+    /** Wall-clock duration of the whole plan (ms). */
+    durationMs: number;
+    /** Any unresolved findings (verify FAIL with rework budget spent, etc.). */
+    unresolvedFindings: {
+        nodeId: string;
+        label: string;
+        reason: string;
+        findings: string;
+    }[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/kraken/runtime/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/kraken/runtime/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhE,+EAA+E;AAC/E,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO;IAC1C,qCAAqC;IACrC,IAAI,EAAE,YAAY,CAAC;IACnB,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,oEAAoE;IACpE,IAAI,CAAC,EAAE,WAAW,EAAE,CAAC;IACrB;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5B,2EAA2E;IAC3E,YAAY,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC3C,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,cAAc,CAAC;IACvB,yEAAyE;IACzE,MAAM,CAAC,EAAE,CAAC,CAAC;IACX,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACtC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,yEAAyE;AACzE,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,mBAAmB,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEjF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAChD,kEAAkE;IAClE,EAAE,EAAE,OAAO,CAAC;CACb;AAED,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,iEAAiE;IACjE,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB;AAED,mEAAmE;AACnE,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,qDAAqD;AACrD,MAAM,MAAM,aAAa,GACrB,iBAAiB,GACjB,oBAAoB,GACpB,gBAAgB,GAChB,eAAe,GACf,eAAe,GACf,gBAAgB,GAChB,WAAW,CAAC;AAEhB,8EAA8E;AAC9E,qBAAa,SAAU,SAAQ,KAAK;IAClC,SAAkB,IAAI,eAAe;IACrC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;gBACb,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAKlE;AAED,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IACzE,gFAAgF;IAChF,OAAO,CAAC,CAAC,SAAS,SAAS,WAAW,EAAE,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC;QAAE,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;KAAE,CAAC,CAAC;IAChG,sEAAsE;IACtE,IAAI,CAAC,CAAC,SAAS,SAAS,WAAW,EAAE,EACnC,IAAI,EAAE,CAAC,GACN,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IACtB,+EAA+E;IAC/E,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IACzG,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IACxG,4DAA4D;IAC5D,KAAK,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/E,+EAA+E;IAC/E,UAAU,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAClD,oDAAoD;IACpD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACvD,sDAAsD;IACtD,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IACjC,yEAAyE;IACzE,UAAU,IAAI,WAAW,CAAC;IAC1B,6EAA6E;IAC7E,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;CACpD;AAED,mEAAmE;AACnE,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC5C,iEAAiE;IACjE,YAAY,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,iEAAiE;AACjE,MAAM,WAAW,cAAc;IAC7B;;;;;;;OAOG;IACH,WAAW,CAAC,IAAI,EAAE;QAChB,IAAI,EAAE,eAAe,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAChC,4DAA4D;IAC5D,cAAc,CAAC,IAAI,EAAE;QACnB,IAAI,EAAE,SAAS,WAAW,EAAE,CAAC;QAC7B,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,aAAa,CAAC;QACxB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACzB,6DAA6D;IAC7D,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,uCAAuC;IACvC,YAAY,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnE,0EAA0E;IAC1E,MAAM,IAAI,WAAW,GAAG,SAAS,CAAC;CACnC;AAED;yDACyD;AACzD,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;8EAC8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC5C,mFAAmF;IACnF,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,SAAS,EAAE,OAAO,CAAC;IACnB,2DAA2D;IAC3D,SAAS,EAAE,OAAO,CAAC;IACnB,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,kBAAkB,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3F"}

package/dist/kraken/runtime/types.js

@@ -0,0 +1,35 @@
+/**
+ * Kraken script runtime — public types.
+ *
+ * A Kraken "script plan" is a TypeScript module the planner emits (or a user
+ * hands in) that imports the SDK from `@zelari/kraken-runtime` and calls
+ * `tentacle()`, `merge()`, `checkpoint()`, etc. The runtime compiles the
+ * module with esbuild (CLI side), loads it in a Node `vm` context with a
+ * capability-based sandbox, and runs it. Every call into the SDK is a
+ * bridge from the sandboxed script to the parent process — there is no
+ * direct filesystem, process, or network access in the script.
+ *
+ * Safety invariants (see F1.1 in `.zelari/docs/kraken-best-in-class-roadmap.md`):
+ *   - The script cannot read `process.env` or `fs` outside the SDK.
+ *   - Every `tentacle()` call increments a counter; the run aborts past
+ *     `MAX_TENTACLES` (default 200) regardless of what the script does.
+ *   - The script runs under a wall-clock budget (`ZELARI_KRAKEN_PLAN_TIMEOUT_MS`,
+ *     default 30 minutes) enforced by the `vm` timeout.
+ *   - `merge()` is one-shot per plan: a second call throws `PlanError` and
+ *     the run is settled.
+ *
+ * @since Kraken v1.30.x — workflow script runtime (F1.1)
+ */
+/** Structured error from the runtime; scripts should not throw raw values. */
+export class PlanError extends Error {
+    name = 'PlanError';
+    kind;
+    cause;
+    constructor(kind, message, cause) {
+        super(message);
+        this.kind = kind;
+        if (cause !== undefined)
+            this.cause = cause;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/kraken/runtime/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/kraken/runtime/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAuGH,8EAA8E;AAC9E,MAAM,OAAO,SAAU,SAAQ,KAAK;IAChB,IAAI,GAAG,WAAW,CAAC;IAC5B,IAAI,CAAgB;IACpB,KAAK,CAAW;IACzB,YAAY,IAAmB,EAAE,OAAe,EAAE,KAAe;QAC/D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IAC9C,CAAC;CACF"}

package/dist/kraken/verdict.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Kraken graph engine — verify verdict parsing (pure).
+ *
+ * A `verify` node's job is to judge a writer's work, but a tentacle that runs
+ * to completion is a *successful run* regardless of what it concluded: the
+ * executor marked the node `done` and never read the text. A verify that said
+ * "this is wrong" was indistinguishable from one that said "this is correct",
+ * so the graph converged over known-bad work and the only iteration the engine
+ * could do was on execution failure, never on quality.
+ *
+ * This module turns that free text into a decision. The verify prompt asks for
+ * a `VERDICT: PASS` / `VERDICT: FAIL` trailer; the executor parses it and, on
+ * FAIL, spawns a bounded rework round.
+ *
+ * **Pillar 2 extension (v1.30.x)**: `spec` and `conformance` personas emit
+ * the same trailer PLUS a per-requirement table in a JSON code block. The
+ * parser extracts both: the trailer is the gate, the table is the
+ * structured findings the executor can surface in the digest and feed
+ * into a follow-up `fix` node.
+ *
+ * **v1.31.x (Bennett's Razor)**: each parsed verdict now also carries a
+ * `weaknessScore` in `[0, 1]`, computed from the persona's free text via
+ * `weaknessFromVerdict` (see `./weakness.js`). 1.0 = "maximally general
+ * claim" (weak), 0.0 = "maximally specific claim" (strong). The gate
+ * (PASS/FAIL) is unchanged — weakness is metadata, surfaced in the
+ * workbench digest so the user can see whether a PASS was earned by a
+ * tightly-asserted reviewer or a loosely-claimed one.
+ *
+ * No CLI dependencies (see CORREZIONE-1 in the engine plan).
+ *
+ * @since v1.28.x — verify quality gate
+ * @since v1.30.x — spec / conformance persona verdicts
+ * @since v1.31.x — weakness score on persona verdicts
+ */
+/**
+ * What a verify node concluded.
+ *
+ * `unknown` means no trailer was found. It is deliberately distinct from
+ * `pass` so the caller can *report* the omission (a model that quietly stops
+ * emitting the trailer would otherwise disable the whole gate invisibly) while
+ * still treating it as non-blocking.
+ */
+export type VerifyVerdict = 'pass' | 'fail' | 'unknown';
+export interface ParsedVerdict {
+    verdict: VerifyVerdict;
+    /**
+     * The verify's own reasoning — everything except the trailer line, trimmed
+     * and capped. Fed back into the rework node so it knows what to fix.
+     */
+    findings: string;
+}
+/**
+ * Cap on retained findings text. Mirrors `MAX_UPSTREAM_CHARS_PER_DEP` in the
+ * CLI executor, since findings travel the same route (into a sub-agent prompt).
+ */
+export declare const MAX_FINDINGS_CHARS = 2800;
+/**
+ * Extract a verify node's verdict from its conclusion text.
+ *
+ * The **last** trailer wins. Models routinely restate the instruction before
+ * answering ("...end with VERDICT: PASS or VERDICT: FAIL") and a first-match
+ * scan would read that echo as the answer — inverting the gate on exactly the
+ * verbose runs where the judgement matters most.
+ */
+export declare function parseVerifyVerdict(text: string | undefined | null): ParsedVerdict;
+/**
+ * A verify verdict the run could not resolve, carried in the execution summary
+ * and rendered in the digest.
+ *
+ * Lives here (pure) rather than in the CLI executor so the executor and the
+ * status/digest renderer can share it without importing each other.
+ */
+export interface UnresolvedFinding {
+    /** The writer node whose work was judged. */
+    nodeId: string;
+    label: string;
+    /** 'fail' → rework budget exhausted; 'unknown' → no parseable verdict. */
+    reason: 'fail' | 'unknown';
+    findings: string;
+}
+/** One row of the spec / conformance per-requirement table. */
+export interface RequirementVerdict {
+    requirement: string;
+    /** pass = satisfied, fail = violated, unknown = not assessed. */
+    met: 'pass' | 'fail' | 'unknown';
+    /** Path / line / output the reviewer cites as evidence. */
+    evidence?: string;
+}
+/** Structured verdict for `spec` and `conformance` personas.
+ *
+ *  The trailer (`VERDICT: PASS|FAIL`) is the gate; the `requirements` table
+ *  is the per-row reasoning the executor can surface and feed forward.
+ *  `weaknessScore` (Bennett 2023) is metadata: 1.0 = the reviewer asserted
+ *  very little (maximally weak / general), 0.0 = the reviewer pinned
+ *  specific paths, versions, or invariants. It does NOT change the gate,
+ *  but is surfaced in the workbench digest so a user can tell a tightly
+ *  earned PASS from a loosely claimed one. */
+export interface PersonaVerdict {
+    verdict: VerifyVerdict;
+    findings: string;
+    requirements: RequirementVerdict[];
+    /**
+     * Bennett-style weakness score in `[0, 1]`, computed from the persona's
+     * free text by `weaknessFromVerdict`. Higher = weaker = more general.
+     * `1` for the no-trailer case (a missing verdict asserts nothing) and
+     * for the all-empty case.
+     *
+     * @since v1.31.x
+     */
+    weaknessScore: number;
+}
+/** Extract the per-requirement JSON block (if any) from a `spec` or
+ *  `conformance` reply. The block is a ```json ... ``` fenced object
+ *  with a `requirements: [...]` array. */
+export declare function extractRequirementsBlock(text: string | undefined | null): RequirementVerdict[];
+/** Full parser for a `spec` or `conformance` reply: trailer + table. */
+export declare function parsePersonaVerdict(text: string | undefined | null): PersonaVerdict;
+//# sourceMappingURL=verdict.d.ts.map

package/dist/kraken/verdict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict.d.ts","sourceRoot":"","sources":["../../src/kraken/verdict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAIH;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,aAAa,CAAC;IACvB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAUvC;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,aAAa,CAsBjF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACjC,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;8CAQ8C;AAC9C,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,aAAa,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,kBAAkB,EAAE,CAAC;IACnC;;;;;;;OAOG;IACH,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;0CAE0C;AAC1C,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,kBAAkB,EAAE,CAgC9F;AAED,wEAAwE;AACxE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,cAAc,CAcnF"}

package/dist/kraken/verdict.js

@@ -0,0 +1,143 @@
+/**
+ * Kraken graph engine — verify verdict parsing (pure).
+ *
+ * A `verify` node's job is to judge a writer's work, but a tentacle that runs
+ * to completion is a *successful run* regardless of what it concluded: the
+ * executor marked the node `done` and never read the text. A verify that said
+ * "this is wrong" was indistinguishable from one that said "this is correct",
+ * so the graph converged over known-bad work and the only iteration the engine
+ * could do was on execution failure, never on quality.
+ *
+ * This module turns that free text into a decision. The verify prompt asks for
+ * a `VERDICT: PASS` / `VERDICT: FAIL` trailer; the executor parses it and, on
+ * FAIL, spawns a bounded rework round.
+ *
+ * **Pillar 2 extension (v1.30.x)**: `spec` and `conformance` personas emit
+ * the same trailer PLUS a per-requirement table in a JSON code block. The
+ * parser extracts both: the trailer is the gate, the table is the
+ * structured findings the executor can surface in the digest and feed
+ * into a follow-up `fix` node.
+ *
+ * **v1.31.x (Bennett's Razor)**: each parsed verdict now also carries a
+ * `weaknessScore` in `[0, 1]`, computed from the persona's free text via
+ * `weaknessFromVerdict` (see `./weakness.js`). 1.0 = "maximally general
+ * claim" (weak), 0.0 = "maximally specific claim" (strong). The gate
+ * (PASS/FAIL) is unchanged — weakness is metadata, surfaced in the
+ * workbench digest so the user can see whether a PASS was earned by a
+ * tightly-asserted reviewer or a loosely-claimed one.
+ *
+ * No CLI dependencies (see CORREZIONE-1 in the engine plan).
+ *
+ * @since v1.28.x — verify quality gate
+ * @since v1.30.x — spec / conformance persona verdicts
+ * @since v1.31.x — weakness score on persona verdicts
+ */
+import { weaknessScoreFromText } from './weakness.js';
+/**
+ * Cap on retained findings text. Mirrors `MAX_UPSTREAM_CHARS_PER_DEP` in the
+ * CLI executor, since findings travel the same route (into a sub-agent prompt).
+ */
+export const MAX_FINDINGS_CHARS = 2800;
+/**
+ * Matches a verdict trailer at the start of a line: `VERDICT: PASS`.
+ * Tolerates leading whitespace, markdown emphasis/bullets the model may wrap
+ * it in (`**VERDICT: FAIL**`, `- VERDICT: PASS`), and any trailing text on the
+ * line (a model that appends "— 3 gaps found" should still be understood).
+ */
+const VERDICT_LINE = /^[\s>*_-]*VERDICT[\s*_]*:[\s*_]*(PASS|FAIL)\b/gim;
+/**
+ * Extract a verify node's verdict from its conclusion text.
+ *
+ * The **last** trailer wins. Models routinely restate the instruction before
+ * answering ("...end with VERDICT: PASS or VERDICT: FAIL") and a first-match
+ * scan would read that echo as the answer — inverting the gate on exactly the
+ * verbose runs where the judgement matters most.
+ */
+export function parseVerifyVerdict(text) {
+    const source = typeof text === 'string' ? text : '';
+    if (source.trim() === '')
+        return { verdict: 'unknown', findings: '' };
+    VERDICT_LINE.lastIndex = 0;
+    let match;
+    let last = null;
+    while ((match = VERDICT_LINE.exec(source)) !== null) {
+        last = match;
+        // A zero-length match would spin forever; the pattern cannot produce one
+        // (it requires the literal "VERDICT"), but guard anyway.
+        if (match.index === VERDICT_LINE.lastIndex)
+            VERDICT_LINE.lastIndex += 1;
+    }
+    if (!last) {
+        return { verdict: 'unknown', findings: capFindings(source) };
+    }
+    const verdict = last[1].toUpperCase() === 'FAIL' ? 'fail' : 'pass';
+    // Everything before the trailer is the reasoning that produced it.
+    const findings = capFindings(source.slice(0, last.index));
+    return { verdict, findings };
+}
+/** Extract the per-requirement JSON block (if any) from a `spec` or
+ *  `conformance` reply. The block is a ```json ... ``` fenced object
+ *  with a `requirements: [...]` array. */
+export function extractRequirementsBlock(text) {
+    if (typeof text !== 'string' || text.trim() === '')
+        return [];
+    // Find the LAST ```json ... ``` block (LLMs sometimes emit the spec first,
+    // then the actual answer; we want the final one).
+    const re = /```json\s*([\s\S]*?)```/gi;
+    let m;
+    let last = null;
+    while ((m = re.exec(text)) !== null) {
+        last = m[1];
+        if (m.index === re.lastIndex)
+            re.lastIndex += 1;
+    }
+    if (!last)
+        return [];
+    try {
+        const obj = JSON.parse(last);
+        if (!obj || !Array.isArray(obj.requirements))
+            return [];
+        const out = [];
+        for (const r of obj.requirements) {
+            if (!r || typeof r !== 'object')
+                continue;
+            const row = r;
+            const req = typeof row.requirement === 'string' ? row.requirement : '';
+            const metRaw = typeof row.met === 'string' ? row.met.toLowerCase() : '';
+            const met = metRaw === 'pass' || metRaw === 'true' ? 'pass'
+                : metRaw === 'fail' || metRaw === 'false' ? 'fail'
+                    : 'unknown';
+            const evidence = typeof row.evidence === 'string' ? row.evidence : undefined;
+            if (req)
+                out.push({ requirement: req, met, ...(evidence ? { evidence } : {}) });
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+/** Full parser for a `spec` or `conformance` reply: trailer + table. */
+export function parsePersonaVerdict(text) {
+    const base = parseVerifyVerdict(text);
+    return {
+        verdict: base.verdict,
+        findings: base.findings,
+        requirements: extractRequirementsBlock(text),
+        // Bennett's weakness = "how little the reviewer's free text asserts"
+        // (arXiv:2301.12987). `weaknessScoreFromText` is the weakness form
+        // (1.0 = maximally general / no claims; 0.0 = maximally specific).
+        // The verdict gate is the trailer; weakness is metadata surfaced in
+        // the workbench so a user can see whether a PASS was earned by a
+        // tightly-asserted or loosely-claimed reviewer.
+        weaknessScore: weaknessScoreFromText(text),
+    };
+}
+/** Trim and cap findings text, marking the cut so a reader knows it happened. */
+function capFindings(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length <= MAX_FINDINGS_CHARS)
+        return trimmed;
+    return `${trimmed.slice(0, MAX_FINDINGS_CHARS)}\n… [truncated]`;
+}
+//# sourceMappingURL=verdict.js.map

package/dist/kraken/verdict.js.map

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