@zelari/core 1.28.0 → 1.30.0

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"}

package/dist/kraken/weakness.js

@@ -0,0 +1,305 @@
+/**
+ * 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
+// ---------------------------------------------------------------------------
+/**
+ * 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 const BENNETTS_RAZOR = [
+    "Bennett's Razor (arXiv:2301.12987): explanations should be no more specific than necessary.",
+    'When two solutions both satisfy the task, prefer the one that assumes the least.',
+    'A claim is "more specific" when it pins down an exact value, path, version, or invariant that a more general plan would not have to commit to.',
+    'Specificity is a tie-breaker, not a goal: a plan that is too vague to act on is still useless.',
+    'Weakness ranking only applies among solutions that already meet the bar; do not weaken a passing plan below the bar in the name of weakness.',
+].join(' ');
+/**
+ * Short form — a single sentence, for inclusion in compact prompts.
+ */
+export const BENNETTS_RAZOR_SHORT = 'Prefer the solution that is no more specific than necessary.';
+// ---------------------------------------------------------------------------
+// Heuristic specificity scan (no LLM call, deterministic)
+// ---------------------------------------------------------------------------
+/**
+ * Lexical markers that correlate with a *specific* claim. Each match adds a
+ * small weight to {@link SPECIFICITY_MARKER_WEIGHT}; the sum is clamped to
+ * `[0, 1]` after the scan.
+ *
+ * The list is intentionally small and conservative: false positives in the
+ * "specific" direction (under-ranking a weak plan) are worse than false
+ * positives in the "general" direction, because a too-weak plan is just
+ * under-rendered in the workbench, while a too-strong one may be chosen
+ * over a better one.
+ */
+const SPECIFICITY_MARKERS = [
+    /\bguarantee[ds]?\b/i,
+    /\bexact(?:ly)?\b/i,
+    /\bmust\b/i,
+    /\bshall\b/i,
+    /\balways\b/i,
+    /\bnever\b/i,
+    /\brequire[ds]?\b/i,
+    /\bmandatory\b/i,
+    /\bline\s+\d+/i, // "line 42"
+    /\bversion\s+[\d.]+/i, // "version 1.2.3"
+    /\bv?\d+\.\d+\.\d+\b/, // bare semver
+    /\b[0-9a-f]{7,40}\b/i, // git short SHA / commit hash
+    /\bthe\s+(?:file|path)\s+(?:is|at)\b/i,
+    /\bprecise(?:ly)?\b/i,
+    /\bassert(?:s|ed|ion)?\b/i,
+    /\bconfirm(?:s|ed)?\b/i,
+    /\bwill\s+(?:definitely|certainly|always)\b/i,
+];
+/** Per-marker weight. Chosen so ~3 matches already saturate the score. */
+const SPECIFICITY_MARKER_WEIGHT = 0.25;
+/**
+ * Per-claim count penalty. Every *new sentence containing a verb* adds a
+ * tiny weight. This catches the "I will do A, then B, then C, then D"
+ * pattern that no individual marker hits but is clearly over-specified.
+ */
+const SPECIFICITY_CLAUSE_WEIGHT = 0.05;
+/** Maximum number of clause-penalty increments (caps runaway). */
+const SPECIFICITY_CLAUSE_MAX = 6;
+/**
+ * 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 function weaknessFromVerdict(text) {
+    if (typeof text !== 'string')
+        return 0;
+    const trimmed = text.trim();
+    if (trimmed === '')
+        return 0;
+    let score = 0;
+    for (const re of SPECIFICITY_MARKERS) {
+        if (re.test(trimmed))
+            score += SPECIFICITY_MARKER_WEIGHT;
+    }
+    // Clause count: count sentences / semicolon-separated statements with a verb.
+    const clauses = trimmed
+        .split(/[.!?;]+|\n+/)
+        .map((c) => c.trim())
+        .filter((c) => c.length > 0 && /\b\w+ing\b|\b\w+ed\b|\bwill\b|\bcan\b|\bmust\b|\bshould\b|\bmay\b/i.test(c));
+    const clausePenalty = Math.min(clauses.length, SPECIFICITY_CLAUSE_MAX) * SPECIFICITY_CLAUSE_WEIGHT;
+    score += clausePenalty;
+    return clamp01(score);
+}
+/**
+ * Weakness = `1 - specificity`, in `[0, 1]`. The default tie-breaker
+ * when no `extensionSize` or LLM meter is available.
+ */
+export function weaknessScoreFromText(text) {
+    return 1 - weaknessFromVerdict(text);
+}
+// ---------------------------------------------------------------------------
+// LLM-as-weakness-meter
+// ---------------------------------------------------------------------------
+/**
+ * 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 const WEAKNESS_METER_PROMPT = `You are measuring the SPECIFICITY of a candidate solution to a software task.
+
+Specificity 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.
+
+A 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.
+
+Output ONLY a JSON object of the form:
+{"specificity": <float in [0,1]>, "assumptions": [<short string>, ...]}
+
+where
+- specificity = 0.0  → solution asserts nothing beyond the task
+- specificity = 1.0  → solution pins every value, path, version, and invariant
+- assumptions = the list of specific commitments you identified, each ≤ 12 words, deduped, sorted by strength (most specific first). Cap the list at 12.
+
+Do 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 const WeaknessMeterResponseSchema = z.object({
+    specificity: z.number().min(0).max(1),
+    assumptions: z.array(z.string().min(1).max(200)).max(12),
+});
+/**
+ * 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 function weaknessFromMeter(meter) {
+    return clamp01(1 - clamp01(meter.specificity));
+}
+/**
+ * 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 function specificityFromAssumptions(assumptions) {
+    if (!Array.isArray(assumptions) || assumptions.length === 0)
+        return 0;
+    // 1 assumption = low specificity; 6+ = saturate. Empirically: most
+    // reasonable solutions have 0–6 real assumptions; beyond that the
+    // plan is almost certainly over-specified.
+    const raw = Math.min(assumptions.length, 6) / 6;
+    return clamp01(raw);
+}
+/**
+ * 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 function rankByWeakness(candidates) {
+    if (candidates.length === 0)
+        return [];
+    const raws = candidates.map((c) => computeRaw(c));
+    const extScores = raws.filter((r) => r.source === 'extensionSize').map((r) => r.raw);
+    const extMax = extScores.length > 0 ? Math.max(...extScores) : 1;
+    const extMin = extScores.length > 0 ? Math.min(...extScores) : 0;
+    const extRange = extMax - extMin;
+    const scored = raws.map((r) => {
+        let score;
+        switch (r.source) {
+            case 'extensionSize':
+                // Normalise within-set. If all extensionSize are equal, every
+                // candidate gets the same normalised score (the max), which
+                // preserves "they're all equally weak" → stable order.
+                score = extRange > 0 ? (r.raw - extMin) / extRange : 1;
+                break;
+            case 'meter':
+                score = clamp01(1 - clamp01(r.raw));
+                break;
+            case 'heuristic':
+                score = clamp01(r.raw);
+                break;
+        }
+        return { candidate: r.candidate, score, source: r.source };
+    });
+    // Pass 2: stable sort by score desc, then by input order.
+    const indexed = scored.map((s, i) => ({ ...s, originalIndex: i }));
+    indexed.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        return a.originalIndex - b.originalIndex;
+    });
+    // Pass 3: assign 1-based ranks with ties. Equal scores → same rank; the
+    // next distinct score jumps to reflect the count of earlier ties.
+    let lastScore;
+    let lastRank = 0;
+    let seen = 0;
+    return indexed.map((s) => {
+        seen += 1;
+        if (lastScore === undefined || s.score !== lastScore) {
+            lastRank = seen;
+            lastScore = s.score;
+        }
+        return {
+            candidate: s.candidate,
+            weaknessScore: s.score,
+            rank: lastRank,
+            source: s.source,
+        };
+    });
+}
+function computeRaw(c) {
+    if (typeof c.extensionSize === 'number' && Number.isFinite(c.extensionSize) && c.extensionSize >= 0) {
+        return { candidate: c, raw: c.extensionSize, source: 'extensionSize' };
+    }
+    if (c.meter && typeof c.meter.specificity === 'number' && Number.isFinite(c.meter.specificity)) {
+        return { candidate: c, raw: clamp01(c.meter.specificity), source: 'meter' };
+    }
+    return { candidate: c, raw: weaknessScoreFromText(c.text), source: 'heuristic' };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function clamp01(n) {
+    if (!Number.isFinite(n))
+        return 0;
+    if (n < 0)
+        return 0;
+    if (n > 1)
+        return 1;
+    return n;
+}
+/**
+ * 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 function pickWeakest(candidates) {
+    const ranked = rankByWeakness(candidates);
+    return ranked.length > 0 ? ranked[0].candidate : 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 function filterByWeakness(candidates, threshold) {
+    const ranked = rankByWeakness(candidates);
+    return ranked.filter((r) => r.weaknessScore >= threshold).map((r) => r.candidate);
+}
+//# sourceMappingURL=weakness.js.map

package/dist/kraken/weakness.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zelari/core",
-  "version": "1.28.0",
+  "version": "1.30.0",
   "description": "Zelari Code core library — provider-neutral agent loop (AgentHarness), multi-agent council orchestration, and built-in skills. Used by the zelari-code CLI; consumable by other agent frontends.",
   "author": "Anathema Studio <https://anathema-studio.com/>",
   "license": "MIT",