@miller-tech/uap 1.27.0 → 1.29.0

package/dist/delivery/escalation.js

@@ -0,0 +1,84 @@
+/**
+ * Escalation Controller (Phase 5)
+ *
+ * An onIteration handler that watches for stagnation and climbs an escalation
+ * ladder: when the best gate score stops improving for N consecutive turns,
+ * advance to the next tier. Tiers escalate cost progressively — widen
+ * exploration, enable the critic, raise the turn budget, and finally switch to
+ * a stronger model — so cheap strategies are exhausted before expensive ones.
+ *
+ * The controller is pure policy: it inspects IterationRecords and returns
+ * directives. The loop owns all mutation. This keeps escalation testable in
+ * isolation and swappable without touching the loop.
+ */
+const DEFAULT_STAGNATION_TURNS = 2;
+const DEFAULT_EPSILON = 0.01;
+/**
+ * The canonical escalation ladder: exhaust cheap strategies before expensive
+ * ones — widen exploration, then enable the critic, then (if configured)
+ * switch to a stronger model with a couple extra turns. Library-owned so
+ * non-CLI callers get the same policy.
+ */
+export function defaultEscalationLadder(options = {}) {
+    const candidates = Math.max(3, options.candidates ?? 3);
+    const tiers = [
+        { label: `widen exploration (${candidates} candidates)`, setCandidates: candidates },
+        { label: 'enable critic', enableCritic: true },
+    ];
+    if (options.escalateExecutor) {
+        tiers.push({
+            label: `escalate model → ${options.escalateModelName ?? 'stronger model'}`,
+            switchExecutor: options.escalateExecutor,
+            raiseMaxTurns: (options.maxTurns ?? 5) + 2,
+        });
+    }
+    return tiers;
+}
+/**
+ * Build a stagnation-driven escalation controller. Returns an `onIteration`
+ * suitable for ConvergenceConfig, plus a `tierIndex` accessor for tests.
+ */
+export function createEscalationController(config) {
+    const stagnationTurns = config.stagnationTurns ?? DEFAULT_STAGNATION_TURNS;
+    const epsilon = config.improvementEpsilon ?? DEFAULT_EPSILON;
+    let bestScore = -1;
+    let stagnant = 0;
+    let nextTier = 0;
+    return {
+        tierIndex: () => nextTier,
+        onIteration: (record) => {
+            // A passing turn ends the loop regardless; nothing to escalate.
+            if (record.passed)
+                return {};
+            if (record.score > bestScore + epsilon) {
+                bestScore = record.score;
+                stagnant = 0;
+                return {};
+            }
+            // No meaningful improvement this turn.
+            stagnant += 1;
+            // Record the high-water mark even without clearing epsilon, so later
+            // tiers measure improvement against the true best.
+            if (record.score > bestScore)
+                bestScore = record.score;
+            if (stagnant < stagnationTurns)
+                return {};
+            // Stagnated — advance a tier if any remain.
+            if (nextTier >= config.tiers.length) {
+                return {}; // ladder exhausted; let the loop run out its budget
+            }
+            const tier = config.tiers[nextTier];
+            nextTier += 1;
+            stagnant = 0; // give the new tier a fresh window to prove itself
+            config.onEscalate?.(tier, record.turn);
+            return {
+                setCandidates: tier.setCandidates,
+                enableCritic: tier.enableCritic,
+                raiseMaxTurns: tier.raiseMaxTurns,
+                switchExecutor: tier.switchExecutor,
+                note: `escalate → ${tier.label}`,
+            };
+        },
+    };
+}
+//# sourceMappingURL=escalation.js.map

package/dist/delivery/escalation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escalation.js","sourceRoot":"","sources":["../../src/delivery/escalation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAoCH,MAAM,wBAAwB,GAAG,CAAC,CAAC;AACnC,MAAM,eAAe,GAAG,IAAI,CAAC;AAa7B;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,UAAgC,EAAE;IACxE,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC;IACxD,MAAM,KAAK,GAAqB;QAC9B,EAAE,KAAK,EAAE,sBAAsB,UAAU,cAAc,EAAE,aAAa,EAAE,UAAU,EAAE;QACpF,EAAE,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,IAAI,EAAE;KAC/C,CAAC;IACF,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC;YACT,KAAK,EAAE,oBAAoB,OAAO,CAAC,iBAAiB,IAAI,gBAAgB,EAAE;YAC1E,cAAc,EAAE,OAAO,CAAC,gBAAgB;YACxC,aAAa,EAAE,CAAC,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC,GAAG,CAAC;SAC3C,CAAC,CAAC;IACL,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAAwB;IACjE,MAAM,eAAe,GAAG,MAAM,CAAC,eAAe,IAAI,wBAAwB,CAAC;IAC3E,MAAM,OAAO,GAAG,MAAM,CAAC,kBAAkB,IAAI,eAAe,CAAC;IAE7D,IAAI,SAAS,GAAG,CAAC,CAAC,CAAC;IACnB,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,QAAQ,GAAG,CAAC,CAAC;IAEjB,OAAO;QACL,SAAS,EAAE,GAAG,EAAE,CAAC,QAAQ;QACzB,WAAW,EAAE,CAAC,MAAuB,EAAsB,EAAE;YAC3D,gEAAgE;YAChE,IAAI,MAAM,CAAC,MAAM;gBAAE,OAAO,EAAE,CAAC;YAE7B,IAAI,MAAM,CAAC,KAAK,GAAG,SAAS,GAAG,OAAO,EAAE,CAAC;gBACvC,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC;gBACzB,QAAQ,GAAG,CAAC,CAAC;gBACb,OAAO,EAAE,CAAC;YACZ,CAAC;YAED,uCAAuC;YACvC,QAAQ,IAAI,CAAC,CAAC;YACd,qEAAqE;YACrE,mDAAmD;YACnD,IAAI,MAAM,CAAC,KAAK,GAAG,SAAS;gBAAE,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC;YAEvD,IAAI,QAAQ,GAAG,eAAe;gBAAE,OAAO,EAAE,CAAC;YAE1C,4CAA4C;YAC5C,IAAI,QAAQ,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;gBACpC,OAAO,EAAE,CAAC,CAAC,oDAAoD;YACjE,CAAC;YACD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YACpC,QAAQ,IAAI,CAAC,CAAC;YACd,QAAQ,GAAG,CAAC,CAAC,CAAC,mDAAmD;YACjE,MAAM,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;YAEvC,OAAO;gBACL,aAAa,EAAE,IAAI,CAAC,aAAa;gBACjC,YAAY,EAAE,IAAI,CAAC,YAAY;gBAC/B,aAAa,EAAE,IAAI,CAAC,aAAa;gBACjC,cAAc,EAAE,IAAI,CAAC,cAAc;gBACnC,IAAI,EAAE,cAAc,IAAI,CAAC,KAAK,EAAE;aACjC,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/delivery/explorer.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Explorer — best-of-N candidate exploration (Phase 2)
+ *
+ * Instead of committing to a single attempt per turn, the explorer:
+ *  1. generates N candidates concurrently, each steered by a distinct
+ *     strategy seed (diversity by prompt, not temperature — small-model
+ *     profiles pin temperature low for stability)
+ *  2. evaluates each candidate against the real gates on the same baseline
+ *     tree via apply → verify → rollback
+ *  3. ranks objectively (gates passed, then score); a judge tie-breaks
+ *     candidates tied at the top
+ *  4. commits only the winner to the tree
+ *
+ * Candidate verification is sequential by design: gates (npm test, builds)
+ * cannot safely run concurrently in one tree. Worktree-isolated parallel
+ * verification is a planned optimization (inject via `revertibleApplier` +
+ * a per-candidate workspace), not a Phase 2 requirement.
+ *
+ * Fairness caveat: rollback reverts files the model wrote, but gate commands
+ * also mutate the tree (dist/ output, snapshots, caches). Candidate N+1 may
+ * therefore see candidate N's gate side effects. The committed winner is
+ * re-verified after commit so its reported ladder reflects real on-disk
+ * state. Full per-candidate isolation requires the workspace seam above.
+ */
+import type { GateRung, LadderResult, LadderOptions } from './verifier-ladder.js';
+import type { LadderRunner, LoopExecutor } from './convergence-loop.js';
+import type { Applier, ApplyResult, RevertibleApply } from './applier.js';
+import type { Judge } from './judge.js';
+/** Hard ceiling on candidates per turn — guards direct library callers
+ * (the CLI caps lower); each candidate costs a model call + a full gate run. */
+export declare const MAX_CANDIDATES = 8;
+export interface StrategySeed {
+    id: string;
+    hint: string;
+}
+export declare const DEFAULT_STRATEGY_SEEDS: StrategySeed[];
+export interface CandidateResult {
+    id: string;
+    strategy: string;
+    output: string;
+    applyResult: ApplyResult | null;
+    ladder: LadderResult | null;
+    /** Executor failure for this candidate, if any */
+    error?: string;
+    passed: boolean;
+    score: number;
+}
+export interface ExplorationResult {
+    winner: CandidateResult | null;
+    candidates: CandidateResult[];
+    /** Judge rationale when a tie-break occurred */
+    judgeRationale?: string;
+    /** Ladder result of the committed winner (from its evaluation run) */
+    ladder: LadderResult | null;
+}
+export interface ExplorerConfig {
+    /** Number of candidates per turn (default 3) */
+    candidates?: number;
+    seeds?: StrategySeed[];
+    judge?: Judge;
+    projectRoot: string;
+    rungs: GateRung[];
+    ladderOptions?: LadderOptions;
+    ladderRunner?: LadderRunner;
+    /** Override the commit applier (defaults to applyFileBlocks) */
+    applier?: Applier;
+    /** Override the per-candidate revertible applier (defaults to applyFileBlocksWithRollback) */
+    revertibleApplier?: (output: string, projectRoot: string) => RevertibleApply;
+    onCandidate?: (candidate: CandidateResult) => void;
+}
+/**
+ * Generate, evaluate, and commit the best candidate for one loop turn.
+ * The base prompt comes from the loop's prompt builder; each candidate
+ * appends its strategy seed.
+ */
+export declare function exploreAndCommit(task: string, basePrompt: string, executor: LoopExecutor, config: ExplorerConfig): Promise<ExplorationResult>;
+//# sourceMappingURL=explorer.d.ts.map

package/dist/delivery/explorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explorer.d.ts","sourceRoot":"","sources":["../../src/delivery/explorer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAElF,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAExE,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC1E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;gFACgF;AAChF,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,sBAAsB,EAAE,YAAY,EAiBhD,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IAChC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IAC5B,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;IAC/B,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,gDAAgD;IAChD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,gEAAgE;IAChE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8FAA8F;IAC9F,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,eAAe,CAAC;IAC7E,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,eAAe,KAAK,IAAI,CAAC;CACpD;AAID;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,iBAAiB,CAAC,CA6H5B"}

package/dist/delivery/explorer.js

@@ -0,0 +1,166 @@
+/**
+ * Explorer — best-of-N candidate exploration (Phase 2)
+ *
+ * Instead of committing to a single attempt per turn, the explorer:
+ *  1. generates N candidates concurrently, each steered by a distinct
+ *     strategy seed (diversity by prompt, not temperature — small-model
+ *     profiles pin temperature low for stability)
+ *  2. evaluates each candidate against the real gates on the same baseline
+ *     tree via apply → verify → rollback
+ *  3. ranks objectively (gates passed, then score); a judge tie-breaks
+ *     candidates tied at the top
+ *  4. commits only the winner to the tree
+ *
+ * Candidate verification is sequential by design: gates (npm test, builds)
+ * cannot safely run concurrently in one tree. Worktree-isolated parallel
+ * verification is a planned optimization (inject via `revertibleApplier` +
+ * a per-candidate workspace), not a Phase 2 requirement.
+ *
+ * Fairness caveat: rollback reverts files the model wrote, but gate commands
+ * also mutate the tree (dist/ output, snapshots, caches). Candidate N+1 may
+ * therefore see candidate N's gate side effects. The committed winner is
+ * re-verified after commit so its reported ladder reflects real on-disk
+ * state. Full per-candidate isolation requires the workspace seam above.
+ */
+import { runLadder } from './verifier-ladder.js';
+import { applyFileBlocks, applyFileBlocksWithRollback } from './applier.js';
+/** Hard ceiling on candidates per turn — guards direct library callers
+ * (the CLI caps lower); each candidate costs a model call + a full gate run. */
+export const MAX_CANDIDATES = 8;
+export const DEFAULT_STRATEGY_SEEDS = [
+    {
+        id: 'direct',
+        hint: 'STRATEGY: Make the most direct, minimal change that satisfies the task. Touch as few files as possible.',
+    },
+    {
+        id: 'test-first',
+        hint: 'STRATEGY: Reason from the failing gates first. Identify exactly what the gates check, then implement precisely that.',
+    },
+    {
+        id: 'defensive',
+        hint: 'STRATEGY: Implement with rigorous edge-case handling — empty inputs, wrong types, boundary values.',
+    },
+    {
+        id: 'rewrite',
+        hint: 'STRATEGY: Re-derive the solution from scratch rather than patching the previous attempt.',
+    },
+];
+const DEFAULT_CANDIDATES = 3;
+/**
+ * Generate, evaluate, and commit the best candidate for one loop turn.
+ * The base prompt comes from the loop's prompt builder; each candidate
+ * appends its strategy seed.
+ */
+export async function exploreAndCommit(task, basePrompt, executor, config) {
+    const count = Math.min(MAX_CANDIDATES, Math.max(1, config.candidates ?? DEFAULT_CANDIDATES));
+    const seeds = config.seeds && config.seeds.length > 0 ? config.seeds : DEFAULT_STRATEGY_SEEDS;
+    const ladderRunner = config.ladderRunner ?? runLadder;
+    const apply = config.applier ?? applyFileBlocks;
+    const applyRevertible = config.revertibleApplier ?? applyFileBlocksWithRollback;
+    // 1. Generate all candidates concurrently (model calls parallelize fine)
+    const generations = await Promise.all(Array.from({ length: count }, async (_, i) => {
+        const seed = seeds[i % seeds.length];
+        const prompt = `${basePrompt}\n\n${seed.hint}`;
+        try {
+            return { seed, output: await executor(prompt), error: undefined };
+        }
+        catch (err) {
+            return { seed, output: '', error: err instanceof Error ? err.message : String(err) };
+        }
+    }));
+    // 2. Evaluate sequentially on the same baseline via apply → verify → rollback
+    const candidates = [];
+    for (let i = 0; i < generations.length; i++) {
+        const { seed, output, error } = generations[i];
+        const id = `c${i + 1}`;
+        if (error) {
+            const candidate = {
+                id,
+                strategy: seed.id,
+                output: '',
+                applyResult: null,
+                ladder: null,
+                error,
+                passed: false,
+                score: 0,
+            };
+            candidates.push(candidate);
+            config.onCandidate?.(candidate);
+            continue;
+        }
+        const { result: applyResult, restore } = applyRevertible(output, config.projectRoot);
+        let ladder = null;
+        try {
+            if (!applyResult.error && applyResult.filesWritten.length > 0) {
+                ladder = await ladderRunner(config.rungs, config.projectRoot, config.ladderOptions);
+            }
+        }
+        finally {
+            restore();
+        }
+        const candidate = {
+            id,
+            strategy: seed.id,
+            output,
+            applyResult,
+            ladder,
+            passed: ladder?.passed ?? false,
+            score: ladder?.score ?? 0,
+        };
+        candidates.push(candidate);
+        config.onCandidate?.(candidate);
+    }
+    // Only candidates that wrote files and reached a real ladder run are
+    // committable; anything else (executor error, no/rejected blocks) cannot
+    // win regardless of its zero score.
+    const committable = (c) => c.ladder !== null && (c.applyResult?.filesWritten.length ?? 0) > 0;
+    // 3. Rank by evaluation tier, then pass/score. A committable candidate
+    //    always outranks a non-committable one (fixes error candidates with
+    //    score 0 tying with evaluated candidates that scored 0).
+    const ranked = [...candidates].sort((a, b) => {
+        const ca = committable(a);
+        const cb = committable(b);
+        if (ca !== cb)
+            return ca ? -1 : 1;
+        if (a.passed !== b.passed)
+            return a.passed ? -1 : 1;
+        return b.score - a.score;
+    });
+    const top = ranked[0];
+    if (!top || !committable(top)) {
+        return { winner: null, candidates, ladder: null };
+    }
+    // Judge tie-break among committable candidates tied with the top result
+    let winner = top;
+    let judgeRationale;
+    const tied = ranked.filter((c) => committable(c) && c.passed === top.passed && c.score === top.score);
+    if (tied.length > 1 && config.judge) {
+        try {
+            const verdict = await config.judge(task, tied.map((c) => ({
+                id: c.id,
+                strategy: c.strategy,
+                output: c.output,
+                ladderFeedback: c.ladder?.feedback ?? '',
+                score: c.score,
+            })));
+            const chosen = tied.find((c) => c.id === verdict.winnerId);
+            if (chosen) {
+                winner = chosen;
+                judgeRationale = verdict.rationale;
+            }
+        }
+        catch {
+            // Judge is a public seam; a throwing judge falls back to objective top.
+        }
+    }
+    // 4. Commit the winner by re-applying. Re-verify the committed tree so the
+    //    reported ladder reflects on-disk state (losers' gate side effects may
+    //    have perturbed it between the winner's evaluation and now).
+    const committed = await apply(winner.output, config.projectRoot);
+    let finalLadder = winner.ladder;
+    if (committed.filesWritten.length > 0) {
+        finalLadder = await ladderRunner(config.rungs, config.projectRoot, config.ladderOptions);
+    }
+    return { winner: { ...winner, ladder: finalLadder }, candidates, judgeRationale, ladder: finalLadder };
+}
+//# sourceMappingURL=explorer.js.map

package/dist/delivery/explorer.js.map

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

package/dist/delivery/index.d.ts

@@ -5,8 +5,13 @@
  * iterations against the project's real completion gates until delivery
  * is achieved.
  */
-export { ConvergenceLoop, defaultPromptBuilder, type ConvergenceConfig, type DeliveryResult, type IterationRecord, type LoopExecutor, type LadderRunner, type PromptBuilder, type PromptContext, } from './convergence-loop.js';
+export { ConvergenceLoop, defaultPromptBuilder, type CandidateSummary, type ConvergenceConfig, type DeliveryResult, type ExplorerSettings, type IterationDirective, type IterationRecord, type LoopExecutor, type LadderRunner, type OnIteration, type PracticeProvider, type PromptBuilder, type PromptContext, } from './convergence-loop.js';
+export { createEscalationController, defaultEscalationLadder, type DefaultLadderOptions, type EscalationConfig, type EscalationController, type EscalationTier, } from './escalation.js';
+export { InMemoryPracticeStore, FilePracticeStore, extractKeywords, distillPractice, defaultPracticePath, type PracticeCard, type PracticeInput, type PracticeStore, } from './practice.js';
+export { exploreAndCommit, DEFAULT_STRATEGY_SEEDS, MAX_CANDIDATES, type CandidateResult, type ExplorationResult, type ExplorerConfig, type StrategySeed, } from './explorer.js';
+export { createModelJudge, extractJson, type Judge, type JudgeCandidate, type JudgeVerdict, } from './judge.js';
+export { createModelCritic, parseFixList, type Critic, type Critique, type CritiqueInput, } from './critic.js';
 export { detectRungs, runLadder, runRung, formatFeedback, type GateRung, type RungResult, type RungFailureReason, type LadderResult, type LadderOptions, } from './verifier-ladder.js';
-export { applyFileBlocks, parseFileBlocks, type Applier, type ApplyResult, type FileBlock, } from './applier.js';
+export { applyFileBlocks, applyFileBlocksWithRollback, parseFileBlocks, type Applier, type ApplyResult, type FileBlock, type RevertibleApply, } from './applier.js';
 export { OpenAICompatClient, type OpenAICompatClientOptions } from '../models/openai-compat-client.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/delivery/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/delivery/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,aAAa,GACnB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,WAAW,EACX,SAAS,EACT,OAAO,EACP,cAAc,EACd,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,aAAa,GACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,eAAe,EACf,eAAe,EACf,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,SAAS,GACf,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,mCAAmC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/delivery/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,aAAa,GACnB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,0BAA0B,EAC1B,uBAAuB,EACvB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,mBAAmB,EACnB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,aAAa,GACnB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,cAAc,EACd,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,YAAY,GAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,KAAK,KAAK,EACV,KAAK,cAAc,EACnB,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,KAAK,MAAM,EACX,KAAK,QAAQ,EACb,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,WAAW,EACX,SAAS,EACT,OAAO,EACP,cAAc,EACd,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,aAAa,GACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,eAAe,EACf,2BAA2B,EAC3B,eAAe,EACf,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,mCAAmC,CAAC"}

package/dist/delivery/index.js

@@ -6,7 +6,12 @@
  * is achieved.
  */
 export { ConvergenceLoop, defaultPromptBuilder, } from './convergence-loop.js';
+export { createEscalationController, defaultEscalationLadder, } from './escalation.js';
+export { InMemoryPracticeStore, FilePracticeStore, extractKeywords, distillPractice, defaultPracticePath, } from './practice.js';
+export { exploreAndCommit, DEFAULT_STRATEGY_SEEDS, MAX_CANDIDATES, } from './explorer.js';
+export { createModelJudge, extractJson, } from './judge.js';
+export { createModelCritic, parseFixList, } from './critic.js';
 export { detectRungs, runLadder, runRung, formatFeedback, } from './verifier-ladder.js';
-export { applyFileBlocks, parseFileBlocks, } from './applier.js';
+export { applyFileBlocks, applyFileBlocksWithRollback, parseFileBlocks, } from './applier.js';
 export { OpenAICompatClient } from '../models/openai-compat-client.js';
 //# sourceMappingURL=index.js.map

package/dist/delivery/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/delivery/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,eAAe,EACf,oBAAoB,GAQrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,WAAW,EACX,SAAS,EACT,OAAO,EACP,cAAc,GAMf,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,eAAe,EACf,eAAe,GAIhB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,kBAAkB,EAAkC,MAAM,mCAAmC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/delivery/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,eAAe,EACf,oBAAoB,GAarB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,0BAA0B,EAC1B,uBAAuB,GAKxB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,mBAAmB,GAIpB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,cAAc,GAKf,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,gBAAgB,EAChB,WAAW,GAIZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,iBAAiB,EACjB,YAAY,GAIb,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,WAAW,EACX,SAAS,EACT,OAAO,EACP,cAAc,GAMf,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,eAAe,EACf,2BAA2B,EAC3B,eAAe,GAKhB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,kBAAkB,EAAkC,MAAM,mCAAmC,CAAC"}

package/dist/delivery/judge.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Candidate Judge
+ *
+ * Tie-breaks exploration candidates whose objective (gate) scores are equal.
+ * Objective verification always outranks judgment — the judge is consulted
+ * only among candidates tied at the top of the ladder ranking.
+ */
+import type { LoopExecutor } from './convergence-loop.js';
+export interface JudgeCandidate {
+    /** Stable candidate id, e.g. 'c1' */
+    id: string;
+    /** Strategy seed that produced this candidate */
+    strategy: string;
+    /** Model output (the judge prompt truncates it before embedding) */
+    output: string;
+    /** Gate feedback for this candidate */
+    ladderFeedback: string;
+    /** Objective gate score */
+    score: number;
+}
+export interface JudgeVerdict {
+    winnerId: string;
+    rationale: string;
+}
+export type Judge = (task: string, candidates: JudgeCandidate[]) => Promise<JudgeVerdict>;
+/** Extract the first JSON object from model output (tolerates prose/fences). */
+export declare function extractJson(text: string): Record<string, unknown> | null;
+/**
+ * Model-backed judge. Falls back to the first candidate (caller's ranking
+ * order) when the verdict is unparseable or names an unknown candidate.
+ */
+export declare function createModelJudge(executor: LoopExecutor): Judge;
+//# sourceMappingURL=judge.d.ts.map

package/dist/delivery/judge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"judge.d.ts","sourceRoot":"","sources":["../../src/delivery/judge.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,MAAM,WAAW,cAAc;IAC7B,qCAAqC;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,cAAc,EAAE,MAAM,CAAC;IACvB,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,KAAK,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,EAAE,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AA4B1F,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAQxE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,GAAG,KAAK,CA0B9D"}

package/dist/delivery/judge.js

@@ -0,0 +1,70 @@
+/**
+ * Candidate Judge
+ *
+ * Tie-breaks exploration candidates whose objective (gate) scores are equal.
+ * Objective verification always outranks judgment — the judge is consulted
+ * only among candidates tied at the top of the ladder ranking.
+ */
+const CANDIDATE_OUTPUT_CHARS = 2_000;
+function buildJudgePrompt(task, candidates) {
+    const sections = [
+        'You are a strict senior code reviewer judging competing solutions to the same task.',
+        'Rate on: correctness, completeness, simplicity, and how well gate feedback was addressed.',
+        '',
+        `TASK: ${task}`,
+        '',
+    ];
+    for (const c of candidates) {
+        sections.push(`=== CANDIDATE ${c.id} (strategy: ${c.strategy}, gate score: ${Math.round(c.score * 100)}%) ===`);
+        sections.push(c.output.slice(0, CANDIDATE_OUTPUT_CHARS));
+        if (c.ladderFeedback) {
+            sections.push(`Gate feedback: ${c.ladderFeedback.slice(0, 500)}`);
+        }
+        sections.push('');
+    }
+    sections.push(`Respond with ONLY a JSON object: {"winner": "<candidate id>", "rationale": "<one sentence>"}`);
+    return sections.join('\n');
+}
+/** Extract the first JSON object from model output (tolerates prose/fences). */
+export function extractJson(text) {
+    const match = text.match(/\{[\s\S]*?\}/);
+    if (!match)
+        return null;
+    try {
+        return JSON.parse(match[0]);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Model-backed judge. Falls back to the first candidate (caller's ranking
+ * order) when the verdict is unparseable or names an unknown candidate.
+ */
+export function createModelJudge(executor) {
+    return async (task, candidates) => {
+        const fallback = {
+            winnerId: candidates[0].id,
+            rationale: 'judge fallback: kept objective ranking',
+        };
+        if (candidates.length < 2)
+            return fallback;
+        let raw;
+        try {
+            raw = await executor(buildJudgePrompt(task, candidates));
+        }
+        catch {
+            return fallback;
+        }
+        const parsed = extractJson(raw);
+        const winner = typeof parsed?.winner === 'string' ? parsed.winner : undefined;
+        if (!winner || !candidates.some((c) => c.id === winner)) {
+            return fallback;
+        }
+        return {
+            winnerId: winner,
+            rationale: typeof parsed?.rationale === 'string' ? parsed.rationale : '',
+        };
+    };
+}
+//# sourceMappingURL=judge.js.map

package/dist/delivery/judge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"judge.js","sourceRoot":"","sources":["../../src/delivery/judge.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAwBH,MAAM,sBAAsB,GAAG,KAAK,CAAC;AAErC,SAAS,gBAAgB,CAAC,IAAY,EAAE,UAA4B;IAClE,MAAM,QAAQ,GAAG;QACf,qFAAqF;QACrF,2FAA2F;QAC3F,EAAE;QACF,SAAS,IAAI,EAAE;QACf,EAAE;KACH,CAAC;IAEF,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,QAAQ,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC,QAAQ,iBAAiB,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC;QAChH,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,sBAAsB,CAAC,CAAC,CAAC;QACzD,IAAI,CAAC,CAAC,cAAc,EAAE,CAAC;YACrB,QAAQ,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QACpE,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpB,CAAC;IAED,QAAQ,CAAC,IAAI,CACX,8FAA8F,CAC/F,CAAC;IACF,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IACzC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAA4B,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAsB;IACrD,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE;QAChC,MAAM,QAAQ,GAAiB;YAC7B,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE;YAC1B,SAAS,EAAE,wCAAwC;SACpD,CAAC;QACF,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,QAAQ,CAAC;QAE3C,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,QAAQ,CAAC,gBAAgB,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;QAC3D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;QAChC,MAAM,MAAM,GAAG,OAAO,MAAM,EAAE,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;QAC9E,IAAI,CAAC,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,EAAE,CAAC;YACxD,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,OAAO;YACL,QAAQ,EAAE,MAAM;YAChB,SAAS,EAAE,OAAO,MAAM,EAAE,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE;SACzE,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}

package/dist/delivery/practice.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Practice Store (Phase 4)
+ *
+ * Best-practice "cards" learned from past deliveries and injected into future
+ * prompts for similar tasks. A card records guidance distilled from a
+ * *successful* run — the winning strategy seed and how many turns it took —
+ * keyed by task keywords.
+ *
+ * Provenance matters: cards are derived from the harness's own strategy seeds
+ * and gate outcomes, never from raw model output. This keeps the long-term
+ * store free of model-authored text (a stored-prompt-injection vector).
+ */
+export interface PracticeCard {
+    id: string;
+    /** Winning strategy seed id (provenance anchor — never model text) */
+    strategy: string;
+    /** Lowercased keywords that gate retrieval relevance */
+    keywords: string[];
+    /** Guidance injected into prompts — always regenerated from strategy+bestTurns */
+    guidance: string;
+    /** Times this practice has been reinforced by a successful delivery */
+    successCount: number;
+    /** Fewest turns a delivery using this practice took (lower = stronger) */
+    bestTurns: number;
+}
+/** Input to record a successful delivery as a practice. */
+export interface PracticeInput {
+    strategy: string;
+    keywords: string[];
+    turns: number;
+}
+export interface PracticeStore {
+    /** Retrieve the most relevant cards for a task instruction */
+    retrieve(instruction: string, limit?: number): PracticeCard[];
+    /** Reinforce or create a card from a successful delivery */
+    record(input: PracticeInput): void;
+}
+/** Extract lowercased keyword tokens from a task instruction. */
+export declare function extractKeywords(text: string, max?: number): string[];
+/** In-memory store — the base implementation; the file store persists it. */
+export declare class InMemoryPracticeStore implements PracticeStore {
+    protected cards: PracticeCard[];
+    constructor(cards?: PracticeCard[]);
+    retrieve(instruction: string, limit?: number): PracticeCard[];
+    record(input: PracticeInput): void;
+    /** Smallest unused pN id — robust to merges and dropped (corrupt) cards. */
+    private nextId;
+    all(): PracticeCard[];
+}
+/** File-backed practice store (JSON). Self-heals on missing/corrupt files. */
+export declare class FilePracticeStore extends InMemoryPracticeStore {
+    private readonly path;
+    constructor(path: string);
+    /**
+     * Load cards from disk, validating every field. The on-disk file is NOT
+     * trusted to supply guidance text — guidance is regenerated from the
+     * validated strategy + bestTurns via distillPractice, so a tampered file
+     * cannot inject prompt text (the read path enforces the same provenance
+     * the write path guarantees). Structurally-invalid cards are dropped.
+     */
+    private static load;
+    record(input: PracticeInput): void;
+    private persist;
+}
+/** Default on-disk location for a project's learned practices. */
+export declare function defaultPracticePath(projectRoot: string): string;
+/**
+ * Distill a one-line practice from a successful delivery. Provenance-safe:
+ * built only from the winning strategy and turn count, not model output.
+ */
+export declare function distillPractice(winningStrategy: string | undefined, turns: number): string;
+//# sourceMappingURL=practice.d.ts.map

package/dist/delivery/practice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"practice.d.ts","sourceRoot":"","sources":["../../src/delivery/practice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,kFAAkF;IAClF,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9D,4DAA4D;IAC5D,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;CACpC;AAYD,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,SAAK,GAAG,MAAM,EAAE,CAUhE;AAYD,6EAA6E;AAC7E,qBAAa,qBAAsB,YAAW,aAAa;IACzD,SAAS,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC;gBAEpB,KAAK,GAAE,YAAY,EAAO;IAItC,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,YAAY,EAAE;IAcxD,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAqBlC,4EAA4E;IAC5E,OAAO,CAAC,MAAM;IAQd,GAAG,IAAI,YAAY,EAAE;CAGtB;AAED,8EAA8E;AAC9E,qBAAa,iBAAkB,SAAQ,qBAAqB;IAC1D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;gBAElB,IAAI,EAAE,MAAM;IAKxB;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,IAAI;IAgCnB,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAKlC,OAAO,CAAC,OAAO;CAYhB;AAED,kEAAkE;AAClE,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAM1F"}