@miller-tech/uap 1.26.6 → 1.28.0

package/dist/delivery/applier.js

@@ -0,0 +1,258 @@
+/**
+ * File-block Applier
+ *
+ * Materializes model output into the project tree. Models emit complete
+ * files as fenced blocks:
+ *
+ *   ```file:relative/path/from/root.ts
+ *   <entire file content>
+ *   ```
+ *
+ * Whole-file emission is deliberate: small models are far more reliable
+ * emitting complete files than unified diffs. Fences of 3+ backticks are
+ * supported so file contents containing ``` can be wrapped in ````.
+ */
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmdirSync, rmSync, writeFileSync, } from 'fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'path';
+/** Max bytes a single emitted file may have (guards runaway generations). */
+const MAX_FILE_BYTES = 1_000_000;
+const FILE_BLOCK_RE = /^(`{3,})file:([^\n]+)\n([\s\S]*?)^\1\s*$/gm;
+/**
+ * Paths the model is never allowed to write. The harness executes project
+ * scripts during gate verification, so a model-supplied build/test/lint
+ * command in package.json, a git/husky hook, or a CI workflow would be
+ * arbitrary code execution against the host. These are blocked outright;
+ * delivering a change that legitimately needs them is out of scope for an
+ * autonomous loop and must go through a human.
+ */
+const PROTECTED_SEGMENTS = new Set([
+    '.git',
+    '.husky',
+    '.github',
+    '.gitlab',
+    '.circleci',
+    'node_modules',
+]);
+const PROTECTED_BASENAMES = new Set([
+    'package.json',
+    'package-lock.json',
+    'npm-shrinkwrap.json',
+    'yarn.lock',
+    'pnpm-lock.yaml',
+    '.npmrc',
+    '.yarnrc',
+    '.yarnrc.yml',
+]);
+/** Extract file blocks from model output without writing anything. */
+export function parseFileBlocks(output) {
+    const blocks = [];
+    for (const match of output.matchAll(FILE_BLOCK_RE)) {
+        const path = match[2].trim();
+        if (!path)
+            continue;
+        blocks.push({ path, content: match[3] });
+    }
+    return blocks;
+}
+/**
+ * Resolve `target`'s parent to its real (symlink-followed) location and
+ * confirm it stays inside the project root. Lexical checks alone let a
+ * pre-existing symlink inside the repo redirect a write outside it.
+ */
+function realParentEscapes(target, realRoot) {
+    let dir = dirname(target);
+    // Walk up to the nearest existing ancestor (target/intermediate dirs may
+    // not exist yet) and realpath that.
+    while (!existsSync(dir)) {
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    let realDir;
+    try {
+        realDir = realpathSync(dir);
+    }
+    catch {
+        return true;
+    }
+    const rel = relative(realRoot, realDir);
+    return rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+}
+function validatePath(blockPath, projectRoot, realRoot) {
+    if (isAbsolute(blockPath))
+        return 'absolute paths are not allowed';
+    const target = resolve(projectRoot, blockPath);
+    const rel = relative(resolve(projectRoot), target);
+    if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        return 'path escapes the project root';
+    }
+    // Block protected segments anywhere in the path (case-insensitive), and
+    // protected basenames. Closes config/hook/CI-driven code execution.
+    const segments = rel.split(sep);
+    for (const seg of segments) {
+        if (PROTECTED_SEGMENTS.has(seg.toLowerCase())) {
+            return `writes into ${seg} are not allowed`;
+        }
+    }
+    const base = segments[segments.length - 1].toLowerCase();
+    if (PROTECTED_BASENAMES.has(base)) {
+        return `writes to ${base} are not allowed (would alter executed scripts)`;
+    }
+    // Reject writing through an existing symlink, and any symlinked ancestor.
+    try {
+        if (existsSync(target) && lstatSync(target).isSymbolicLink()) {
+            return 'target is a symlink';
+        }
+    }
+    catch {
+        return 'could not stat target';
+    }
+    if (realParentEscapes(target, realRoot)) {
+        return 'path resolves outside the project root via a symlink';
+    }
+    return null;
+}
+function realRootOf(projectRoot) {
+    try {
+        return realpathSync(resolve(projectRoot));
+    }
+    catch {
+        return resolve(projectRoot);
+    }
+}
+/**
+ * Default applier: parse file blocks and write them under projectRoot.
+ * Paths are validated against traversal and .git writes; oversized files
+ * are rejected rather than truncated.
+ */
+export function applyFileBlocks(output, projectRoot) {
+    const blocks = parseFileBlocks(output);
+    if (blocks.length === 0) {
+        return {
+            filesWritten: [],
+            rejected: [],
+            error: 'No file blocks found in the output. Emit every created/modified file as a fenced block: ```file:relative/path … ```',
+        };
+    }
+    const realRoot = realRootOf(projectRoot);
+    const filesWritten = [];
+    const rejected = [];
+    for (const block of blocks) {
+        const invalid = validatePath(block.path, projectRoot, realRoot);
+        if (invalid) {
+            rejected.push({ path: block.path, reason: invalid });
+            continue;
+        }
+        if (Buffer.byteLength(block.content, 'utf-8') > MAX_FILE_BYTES) {
+            rejected.push({ path: block.path, reason: `file exceeds ${MAX_FILE_BYTES} bytes` });
+            continue;
+        }
+        const target = join(projectRoot, block.path);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, block.content, 'utf-8');
+        filesWritten.push(block.path);
+    }
+    return { filesWritten, rejected };
+}
+/** Topmost directory segments that did not exist before applying `paths`. */
+function newDirsFor(paths, projectRoot) {
+    const created = new Set();
+    for (const path of paths) {
+        const segments = path.split(sep);
+        let current = projectRoot;
+        for (let i = 0; i < segments.length - 1; i++) {
+            current = join(current, segments[i]);
+            if (!existsSync(current))
+                created.add(current);
+        }
+    }
+    // Deepest first so rmdir succeeds bottom-up
+    return [...created].sort((a, b) => b.length - a.length);
+}
+/**
+ * Apply file blocks with a snapshot of the prior state of every target, so
+ * the application can be undone. Used by the explorer to evaluate competing
+ * candidates against the same baseline tree without git machinery.
+ */
+export function applyFileBlocksWithRollback(output, projectRoot) {
+    const blocks = parseFileBlocks(output);
+    const realRoot = realRootOf(projectRoot);
+    // Snapshot prior content (or absence) of every valid target, and the set
+    // of directories that do not yet exist, BEFORE writing anything.
+    const snapshots = new Map();
+    const validPaths = [];
+    for (const block of blocks) {
+        if (validatePath(block.path, projectRoot, realRoot))
+            continue;
+        const target = join(projectRoot, block.path);
+        if (!snapshots.has(block.path)) {
+            snapshots.set(block.path, existsSync(target) ? readFileSync(target, 'utf-8') : null);
+            validPaths.push(block.path);
+        }
+    }
+    const newDirs = newDirsFor(validPaths, projectRoot);
+    // Track what actually hit disk so an exception mid-apply still rolls back.
+    const written = [];
+    let restored = false;
+    const restore = () => {
+        if (restored)
+            return;
+        restored = true;
+        for (const path of written) {
+            const target = join(projectRoot, path);
+            const prior = snapshots.get(path);
+            if (prior === null || prior === undefined) {
+                rmSync(target, { force: true });
+            }
+            else {
+                writeFileSync(target, prior, 'utf-8');
+            }
+        }
+        for (const dir of newDirs) {
+            try {
+                rmdirSync(dir); // empty-only — throws (caught) if a surviving file remains
+            }
+            catch {
+                // Non-empty (a surviving file lives here) or already gone — leave it.
+            }
+        }
+    };
+    let result;
+    try {
+        // Re-implement the write loop here so `written` reflects partial progress.
+        if (blocks.length === 0) {
+            result = {
+                filesWritten: [],
+                rejected: [],
+                error: 'No file blocks found in the output. Emit every created/modified file as a fenced block: ```file:relative/path … ```',
+            };
+        }
+        else {
+            const rejected = [];
+            for (const block of blocks) {
+                const invalid = validatePath(block.path, projectRoot, realRoot);
+                if (invalid) {
+                    rejected.push({ path: block.path, reason: invalid });
+                    continue;
+                }
+                if (Buffer.byteLength(block.content, 'utf-8') > MAX_FILE_BYTES) {
+                    rejected.push({ path: block.path, reason: `file exceeds ${MAX_FILE_BYTES} bytes` });
+                    continue;
+                }
+                const target = join(projectRoot, block.path);
+                mkdirSync(dirname(target), { recursive: true });
+                writeFileSync(target, block.content, 'utf-8');
+                if (!written.includes(block.path))
+                    written.push(block.path);
+            }
+            result = { filesWritten: [...written], rejected };
+        }
+    }
+    catch (err) {
+        restore();
+        throw err;
+    }
+    return { result, restore };
+}
+//# sourceMappingURL=applier.js.map

package/dist/delivery/applier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"applier.js","sourceRoot":"","sources":["../../src/delivery/applier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,UAAU,EACV,SAAS,EACT,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,MAAM,EACN,aAAa,GACd,MAAM,IAAI,CAAC;AACZ,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAwBzE,6EAA6E;AAC7E,MAAM,cAAc,GAAG,SAAS,CAAC;AAEjC,MAAM,aAAa,GAAG,4CAA4C,CAAC;AAEnE;;;;;;;GAOG;AACH,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC;IACjC,MAAM;IACN,QAAQ;IACR,SAAS;IACT,SAAS;IACT,WAAW;IACX,cAAc;CACf,CAAC,CAAC;AACH,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC;IAClC,cAAc;IACd,mBAAmB;IACnB,qBAAqB;IACrB,WAAW;IACX,gBAAgB;IAChB,QAAQ;IACR,SAAS;IACT,aAAa;CACd,CAAC,CAAC;AAEH,sEAAsE;AACtE,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,MAAM,MAAM,GAAgB,EAAE,CAAC;IAC/B,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC7B,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,SAAS,iBAAiB,CAAC,MAAc,EAAE,QAAgB;IACzD,IAAI,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1B,yEAAyE;IACzE,oCAAoC;IACpC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,MAAM;QAC1B,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;IACD,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,GAAG,GAAG,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACxC,OAAO,GAAG,KAAK,IAAI,IAAI,GAAG,CAAC,UAAU,CAAC,KAAK,GAAG,EAAE,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC;AACvE,CAAC;AAED,SAAS,YAAY,CAAC,SAAiB,EAAE,WAAmB,EAAE,QAAgB;IAC5E,IAAI,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,gCAAgC,CAAC;IAEnE,MAAM,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IAC/C,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,CAAC;IACnD,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,CAAC,UAAU,CAAC,KAAK,GAAG,EAAE,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAClE,OAAO,+BAA+B,CAAC;IACzC,CAAC;IAED,wEAAwE;IACxE,oEAAoE;IACpE,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAChC,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,kBAAkB,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;YAC9C,OAAO,eAAe,GAAG,kBAAkB,CAAC;QAC9C,CAAC;IACH,CAAC;IACD,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACzD,IAAI,mBAAmB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QAClC,OAAO,aAAa,IAAI,iDAAiD,CAAC;IAC5E,CAAC;IAED,0EAA0E;IAC1E,IAAI,CAAC;QACH,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC;YAC7D,OAAO,qBAAqB,CAAC;QAC/B,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,uBAAuB,CAAC;IACjC,CAAC;IACD,IAAI,iBAAiB,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC;QACxC,OAAO,sDAAsD,CAAC;IAChE,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,UAAU,CAAC,WAAmB;IACrC,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC,WAAW,CAAC,CAAC;IAC9B,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,WAAmB;IACjE,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO;YACL,YAAY,EAAE,EAAE;YAChB,QAAQ,EAAE,EAAE;YACZ,KAAK,EACH,qHAAqH;SACxH,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;IACzC,MAAM,YAAY,GAAa,EAAE,CAAC;IAClC,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAE7C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;QAChE,IAAI,OAAO,EAAE,CAAC;YACZ,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;YACrD,SAAS;QACX,CAAC;QACD,IAAI,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,cAAc,EAAE,CAAC;YAC/D,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,gBAAgB,cAAc,QAAQ,EAAE,CAAC,CAAC;YACpF,SAAS;QACX,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7C,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC9C,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC;AACpC,CAAC;AAED,6EAA6E;AAC7E,SAAS,UAAU,CAAC,KAAe,EAAE,WAAmB;IACtD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,OAAO,GAAG,WAAW,CAAC;QAC1B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC7C,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;YACrC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;gBAAE,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IACD,4CAA4C;IAC5C,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;AAC1D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,MAAc,EAAE,WAAmB;IAC7E,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;IAEzC,yEAAyE;IACzE,iEAAiE;IACjE,MAAM,SAAS,GAAG,IAAI,GAAG,EAAyB,CAAC;IACnD,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,WAAW,EAAE,QAAQ,CAAC;YAAE,SAAS;QAC9D,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/B,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YACrF,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IACD,MAAM,OAAO,GAAG,UAAU,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;IAEpD,2EAA2E;IAC3E,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,MAAM,OAAO,GAAG,GAAS,EAAE;QACzB,IAAI,QAAQ;YAAE,OAAO;QACrB,QAAQ,GAAG,IAAI,CAAC;QAChB,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;YAC3B,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;YACvC,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAClC,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBAC1C,MAAM,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAClC,CAAC;iBAAM,CAAC;gBACN,aAAa,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;YACxC,CAAC;QACH,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;YAC1B,IAAI,CAAC;gBACH,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,2DAA2D;YAC7E,CAAC;YAAC,MAAM,CAAC;gBACP,sEAAsE;YACxE,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IAEF,IAAI,MAAmB,CAAC;IACxB,IAAI,CAAC;QACH,2EAA2E;QAC3E,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,GAAG;gBACP,YAAY,EAAE,EAAE;gBAChB,QAAQ,EAAE,EAAE;gBACZ,KAAK,EACH,qHAAqH;aACxH,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,MAAM,QAAQ,GAA4B,EAAE,CAAC;YAC7C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBAC3B,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;gBAChE,IAAI,OAAO,EAAE,CAAC;oBACZ,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;oBACrD,SAAS;gBACX,CAAC;gBACD,IAAI,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,cAAc,EAAE,CAAC;oBAC/D,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,gBAAgB,cAAc,QAAQ,EAAE,CAAC,CAAC;oBACpF,SAAS;gBACX,CAAC;gBACD,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;gBAC7C,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;gBAChD,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBAC9C,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;oBAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC9D,CAAC;YACD,MAAM,GAAG,EAAE,YAAY,EAAE,CAAC,GAAG,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC;QACpD,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,CAAC;QACV,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AAC7B,CAAC"}

package/dist/delivery/convergence-loop.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Convergence Loop
+ *
+ * Drives an underlying model through execute → apply → verify → feedback
+ * iterations until the project's completion gates (verifier ladder) pass or
+ * the turn budget is exhausted.
+ *
+ * The loop owns pluggable seams so phases extend without breaking changes:
+ *  - executor: how a prompt becomes model output
+ *  - applier: how model output is materialized into the project tree
+ *  - promptBuilder: how instruction/feedback/critique compose a prompt
+ *  - ladderRunner: how gates are verified
+ *  - explorer (Phase 2): best-of-N candidate exploration with judge tie-break
+ *  - critic (Phase 3): structured repair plans replacing raw gate dumps
+ *  - onIteration: per-turn control hook (Phase 5 escalation controllers)
+ */
+import type { GateRung, LadderResult, LadderOptions } from './verifier-ladder.js';
+import type { Applier } from './applier.js';
+import type { StrategySeed } from './explorer.js';
+import type { Judge } from './judge.js';
+import type { Critic } from './critic.js';
+export type LoopExecutor = (prompt: string) => Promise<string>;
+/** Pluggable ladder runner — production uses runLadder, tests inject a stub. */
+export type LadderRunner = (rungs: GateRung[], projectRoot: string, options?: LadderOptions) => LadderResult | Promise<LadderResult>;
+export interface PromptContext {
+    instruction: string;
+    /** 1-based turn about to execute */
+    turn: number;
+    /** Model output from the previous turn (truncated) */
+    previousOutput?: string;
+    /** Gate feedback from the previous turn's ladder run */
+    feedback?: string;
+    /** Apply-stage error from the previous turn (e.g. no file blocks found) */
+    applyError?: string;
+    /** Files written by the previous turn */
+    previousFiles?: string[];
+    /** Structured repair steps from the critic (Phase 3) */
+    critique?: string[];
+}
+export type PromptBuilder = (context: PromptContext) => string;
+export interface CandidateSummary {
+    id: string;
+    strategy: string;
+    passed: boolean;
+    score: number;
+    error?: string;
+}
+export interface IterationRecord {
+    /** Real 1-based loop turn (executor-error turns are recorded too) */
+    turn: number;
+    passed: boolean;
+    /** Fraction of gates passed this iteration (0 when the turn never reached verification) */
+    score: number;
+    gateResults: LadderResult['results'];
+    /** Files the applier wrote this turn */
+    filesApplied: string[];
+    /** Executor failure, if the model call itself errored */
+    executorError?: string;
+    /** Apply failure, if output could not be materialized */
+    applyError?: string;
+    /** Strategy seed of the committed candidate (explorer mode) */
+    strategy?: string;
+    /** All candidates evaluated this turn (explorer mode) */
+    candidates?: CandidateSummary[];
+    /** Judge rationale when a tie-break decided the winner (explorer mode) */
+    judgeRationale?: string;
+    durationMs: number;
+}
+export interface DeliveryResult {
+    success: boolean;
+    /** True when the baseline check found all gates already green (no turns ran) */
+    alreadyDelivered: boolean;
+    turns: number;
+    /** Highest gate score observed across iterations */
+    bestScore: number;
+    /** Turn that achieved bestScore (0 when no iterations reached verification) */
+    bestTurn: number;
+    history: IterationRecord[];
+    /** Feedback from the final ladder run (or apply/executor error context) */
+    finalFeedback: string;
+    /** Raw model output from the final turn */
+    finalOutput: string;
+    totalDurationMs: number;
+}
+export interface ExplorerSettings {
+    /** Candidates per turn (default 3) */
+    candidates?: number;
+    seeds?: StrategySeed[];
+    judge?: Judge;
+}
+export interface ConvergenceConfig {
+    /** Maximum execute→apply→verify iterations (default 5) */
+    maxTurns?: number;
+    /** Project whose gates define "delivered" */
+    projectRoot: string;
+    /** Override auto-detected gates (e.g. subset via CLI --gates) */
+    rungs?: GateRung[];
+    /** Ladder options forwarded to the runner */
+    ladderOptions?: LadderOptions;
+    /**
+     * Run the ladder once before turn 1 (default true). When the baseline is
+     * already green there is nothing to converge on — the loop returns
+     * alreadyDelivered without calling the model, preventing false-success
+     * outcomes from polluting adaptive routing.
+     */
+    baselineCheck?: boolean;
+    /** Max characters of prior model output included in retry prompts (default 3000) */
+    previousOutputChars?: number;
+    /** Best-of-N exploration per turn (Phase 2); omit for single-candidate turns */
+    explorer?: ExplorerSettings;
+    /** Structured critique of failed turns (Phase 3) */
+    critic?: Critic;
+    /**
+     * Called after every iteration. Return 'stop' to abort the loop early
+     * (Phase 5 escalation controllers hook in here).
+     */
+    onIteration?: (record: IterationRecord) => void | 'stop';
+}
+/** Default prompt strategy: lean contract + structured retry context. */
+export declare const defaultPromptBuilder: PromptBuilder;
+export declare class ConvergenceLoop {
+    private readonly config;
+    private readonly executor;
+    private readonly ladderRunner;
+    private readonly applier;
+    private readonly promptBuilder;
+    constructor(config: ConvergenceConfig, executor: LoopExecutor, seams?: {
+        ladderRunner?: LadderRunner;
+        applier?: Applier;
+        promptBuilder?: PromptBuilder;
+    });
+    /** Single-candidate turn: execute → apply → verify. */
+    private runSingleTurn;
+    /** Explorer turn: best-of-N candidates, commit the winner (Phase 2). */
+    private runExplorerTurn;
+    /**
+     * Run the loop for an instruction until all required gates pass or the
+     * turn budget is exhausted. Returns the full iteration history so callers
+     * can record outcomes and inspect convergence behavior.
+     */
+    deliver(instruction: string): Promise<DeliveryResult>;
+}
+//# sourceMappingURL=convergence-loop.d.ts.map

package/dist/delivery/convergence-loop.d.ts.map

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