@zelari/core 1.29.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":"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"}

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

@@ -12,9 +12,25 @@
  * 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.
@@ -62,4 +78,41 @@ export interface UnresolvedFinding {
     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

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

@@ -12,10 +12,27 @@
  * 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).
@@ -58,6 +75,64 @@ export function parseVerifyVerdict(text) {
     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();

package/dist/kraken/verdict.js.map

@@ -1 +1 @@
-{"version":3,"file":"verdict.js","sourceRoot":"","sources":["../../src/kraken/verdict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAqBH;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,YAAY,GAAG,kDAAkD,CAAC;AAExE;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAA+B;IAChE,MAAM,MAAM,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IACpD,IAAI,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IAEtE,YAAY,CAAC,SAAS,GAAG,CAAC,CAAC;IAC3B,IAAI,KAA6B,CAAC;IAClC,IAAI,IAAI,GAA2B,IAAI,CAAC;IACxC,OAAO,CAAC,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACpD,IAAI,GAAG,KAAK,CAAC;QACb,yEAAyE;QACzE,yDAAyD;QACzD,IAAI,KAAK,CAAC,KAAK,KAAK,YAAY,CAAC,SAAS;YAAE,YAAY,CAAC,SAAS,IAAI,CAAC,CAAC;IAC1E,CAAC;IAED,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC;IAC/D,CAAC;IAED,MAAM,OAAO,GAAkB,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;IAClF,mEAAmE;IACnE,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAC1D,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AAC/B,CAAC;AAkBD,iFAAiF;AACjF,SAAS,WAAW,CAAC,GAAW;IAC9B,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,OAAO,CAAC,MAAM,IAAI,kBAAkB;QAAE,OAAO,OAAO,CAAC;IACzD,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,kBAAkB,CAAC,iBAAiB,CAAC;AAClE,CAAC"}
+{"version":3,"file":"verdict.js","sourceRoot":"","sources":["../../src/kraken/verdict.ts"],"names":[],"mappings":"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"}

package/dist/kraken/weakness.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Kraken graph engine — weakness-based hypothesis ranking (Bennett 2023).
+ *
+ * "The Optimal Choice of Hypothesis Is the Weakest, Not the Shortest"
+ * Michael Timothy Bennett, AGI 2023 — arXiv:2301.12987v4.
+ *
+ * Bennett's formal result, restated for a coding-agent context:
+ *
+ *   In a lattice of declarative programs, the **weakness** of a statement
+ *   `l` is the cardinality of its extension `|Z_l|` — the number of
+ *   statements `l` is a sub-statement of. For an unknown parent task
+ *   `ω` of a known child `α`, the probability of a model `h ∈ M_α`
+ *   generalising to `ω` is
+ *
+ *       p(h ∈ M_ω | h ∈ M_α, α ⊏ ω) = 2^|Z_{S_α} ∩ Z_h| / 2^|Z_{S_α}|
+ *
+ *   which is monotonically increasing in `|Z_h|`. The weakest sufficient
+ *   hypothesis maximises the probability of generalisation — and in
+ *   Bennett's experiments (binary 8-bit add / mult) weakness generalised
+ *   at 1.1×–5× the rate of MDL (Occam's Razor as length).
+ *
+ *   "Explanations should be no more specific than necessary."
+ *                                                  — Bennett's Razor
+ *
+ * For a natural-language plan we can't compute `|Z_h|` exactly. This
+ * module provides three usable approximations, cheapest first:
+ *
+ *   1. `weaknessFromVerdict(text)` — heuristic string scan for
+ *      "specificity markers" (e.g. "exactly", "must", "always",
+ *      "guaranteed", "line N"). Catches gross over-claiming, free.
+ *   2. `measureSpecificity(text)` — caller-agnostic shape of an LLM
+ *      meter prompt; the CLI uses {@link WEAKNESS_METER_PROMPT} plus a
+ *      model call to get a principled specificity score.
+ *   3. `extensionSize` (if a caller computes it themselves) — feeds
+ *      `rankByWeakness` directly.
+ *
+ * `rankByWeakness(candidates)` is the single ranking entry point; it
+ * combines the three into a normalised weakness score in `[0, 1]`.
+ *
+ * No CLI dependencies (see CORREZIONE-1 in the engine plan).
+ *
+ * @since v1.31.x — weakness-based hypothesis selection
+ */
+import { z } from 'zod';
+/**
+ * Bennett's Razor in one sentence, suitable for inclusion in system prompts.
+ *
+ * "Explanations should be no more specific than necessary." — Bennett 2023.
+ *
+ * The expanded form below spells out the operational meaning: when two
+ * solutions both satisfy a task, prefer the one that makes fewer specific
+ * claims about the world. It is deliberately phrased as a *tie-breaker*,
+ * not a goal in itself — a plan that is too weak to act on is still useless.
+ */
+export declare const BENNETTS_RAZOR: string;
+/**
+ * Short form — a single sentence, for inclusion in compact prompts.
+ */
+export declare const BENNETTS_RAZOR_SHORT = "Prefer the solution that is no more specific than necessary.";
+/**
+ * Compute a heuristic `specificity` score in `[0, 1]` for `text`.
+ *
+ * Returns `0` for an empty / whitespace-only string (a maximally weak claim).
+ * A score of `1` means "highly specific — many marker hits and/or many
+ * clauses"; a score of `0` means "no specificity signals at all".
+ */
+export declare function weaknessFromVerdict(text: string | undefined | null): number;
+/**
+ * Weakness = `1 - specificity`, in `[0, 1]`. The default tie-breaker
+ * when no `extensionSize` or LLM meter is available.
+ */
+export declare function weaknessScoreFromText(text: string | undefined | null): number;
+/**
+ * The meter prompt. A caller wraps this with their own model invocation
+ * (see `src/cli/kraken/weaknessMeter.ts`) and parses the JSON response.
+ *
+ * Kept as a string here (not a function) so it can be snapshotted in
+ * tests and re-used across providers without re-importing the CLI.
+ */
+export declare const WEAKNESS_METER_PROMPT = "You are measuring the SPECIFICITY of a candidate solution to a software task.\n\nSpecificity means: how many specific commitments does this solution make that a more general plan would not have to make? Examples of specific commitments: exact file paths, exact line numbers, exact semver versions, exact function signatures, guarantees about runtime behaviour, assertions about what other agents/users will do.\n\nA maximally general solution is one that asserts nothing beyond the task itself (\"just do the task\"). A maximally specific solution is one that pins every possible value, path, and invariant.\n\nOutput ONLY a JSON object of the form:\n{\"specificity\": <float in [0,1]>, \"assumptions\": [<short string>, ...]}\n\nwhere\n- specificity = 0.0  \u2192 solution asserts nothing beyond the task\n- specificity = 1.0  \u2192 solution pins every value, path, version, and invariant\n- assumptions = the list of specific commitments you identified, each \u2264 12 words, deduped, sorted by strength (most specific first). Cap the list at 12.\n\nDo not add prose, do not add a code fence, do not explain your reasoning. JSON only.";
+/**
+ * Zod schema for the meter response. Use this in the CLI to parse the
+ * model's output — gives type safety + a clear error path for malformed
+ * JSON, which is the most common failure mode of meter calls.
+ */
+export declare const WeaknessMeterResponseSchema: z.ZodObject<{
+    specificity: z.ZodNumber;
+    assumptions: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type WeaknessMeterResponse = z.infer<typeof WeaknessMeterResponseSchema>;
+/**
+ * Convenience: turn a meter response into a weakness score in `[0, 1]`.
+ * Pure: no I/O. The meter itself is the only thing that costs.
+ */
+export declare function weaknessFromMeter(meter: WeaknessMeterResponse): number;
+/**
+ * Convenience: turn an `assumptions` list (from a meter response) into a
+ * heuristic *specificity* score. Used as a fallback when the meter returns
+ * a `specificity` outside `[0,1]` or one of the JSON fields is missing
+ * after parsing. Each assumption is treated as one specificity hit.
+ */
+export declare function specificityFromAssumptions(assumptions: readonly string[]): number;
+/**
+ * A hypothesis / plan / skill candidate. At least one of the weakness
+ * signals should be populated; `rankByWeakness` will use the strongest
+ * signal available.
+ */
+export interface HypothesisCandidate {
+    /** Stable id (writer node id, skill name, plan hash, …). */
+    id: string;
+    /** The text we may scan heuristically if no other signal is set. */
+    text?: string;
+    /**
+     * Optional: caller's pre-computed extension size `|Z_h|`. When set,
+     * overrides everything else. Use this if you have a real lattice
+     * representation (Kraken's Spec Council does not, today).
+     */
+    extensionSize?: number;
+    /**
+     * Optional: result of {@link WeaknessMeterResponseSchema}.parsed.
+     * Overrides the heuristic scan.
+     */
+    meter?: WeaknessMeterResponse;
+}
+/** A candidate plus the score it received. */
+export interface RankedHypothesis<T extends HypothesisCandidate = HypothesisCandidate> {
+    candidate: T;
+    /** Normalised weakness score in `[0, 1]`. Higher = weaker = more general. */
+    weaknessScore: number;
+    /** 1-based rank, weakest first. Ties get the same rank. */
+    rank: number;
+    /** Which signal drove the score (for debugging / auditing). */
+    source: 'extensionSize' | 'meter' | 'heuristic';
+}
+/**
+ * Rank candidates by weakness, weakest first. Stable: equal scores keep
+ * input order. The function is pure and synchronous; no LLM, no I/O.
+ *
+ * Strategy per candidate:
+ *   1. `extensionSize` (raw count) → normalised across the candidate set
+ *      to `[0, 1]` by dividing by the max within the set.
+ *   2. `meter.specificity` → `1 - specificity` if present and valid.
+ *   3. `weaknessScoreFromText(candidate.text)` → heuristic.
+ *   4. `0` if nothing is set (the candidate is "as general as the empty claim").
+ */
+export declare function rankByWeakness<T extends HypothesisCandidate>(candidates: readonly T[]): RankedHypothesis<T>[];
+/**
+ * Pick the weakest candidate (rank 1) from a list. Convenience for the
+ * Spec Council's "all PASS, pick one" branch. Returns `undefined` if the
+ * input is empty.
+ */
+export declare function pickWeakest<T extends HypothesisCandidate>(candidates: readonly T[]): T | undefined;
+/**
+ * Filter candidates to those with weakness ≥ `threshold` (in `[0, 1]`).
+ * Useful for "among all PASS solutions, keep only the ones that are
+ * *enough* general" — e.g. drop a solution whose heuristic scan flags
+ * ≥ 4 specific markers.
+ */
+export declare function filterByWeakness<T extends HypothesisCandidate>(candidates: readonly T[], threshold: number): T[];
+//# sourceMappingURL=weakness.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"weakness.d.ts","sourceRoot":"","sources":["../../src/kraken/weakness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,QAMhB,CAAC;AAEZ;;GAEG;AACH,eAAO,MAAM,oBAAoB,iEAC+B,CAAC;AAkDjE;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAmB3E;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAE7E;AAMD;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,snCAcmD,CAAC;AAEtF;;;;GAIG;AACH,eAAO,MAAM,2BAA2B;;;iBAGtC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,qBAAqB,GAAG,MAAM,CAEtE;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAOjF;AAMD;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,4DAA4D;IAC5D,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,KAAK,CAAC,EAAE,qBAAqB,CAAC;CAC/B;AAED,8CAA8C;AAC9C,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,mBAAmB,GAAG,mBAAmB;IACnF,SAAS,EAAE,CAAC,CAAC;IACb,6EAA6E;IAC7E,aAAa,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,MAAM,EAAE,eAAe,GAAG,OAAO,GAAG,WAAW,CAAC;CACjD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,mBAAmB,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,GAAG,gBAAgB,CAAC,CAAC,CAAC,EAAE,CA+D7G;AAyBD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,mBAAmB,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,GAAG,SAAS,CAGlG;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,mBAAmB,EAC5D,UAAU,EAAE,SAAS,CAAC,EAAE,EACxB,SAAS,EAAE,MAAM,GAChB,CAAC,EAAE,CAGL"}