verikun 0.26.0-rc.4 → 0.26.0

package/.claude/skills/verikun/SKILL.md

@@ -391,6 +391,16 @@ vk ai onboarding.md --timeout 5m        # tighten the run timeout (default 15m)
   at the screen) before deciding the optional UI is absent, so a dialog that animates in a
   beat after the transition is still caught. An absent guard costs about one extra UI dump;
   `VERIKUN_GUARD_SETTLE_MS=0` restores the old single-shot probe.
+- **A compile has to cover the test.** Compilation is nondeterministic, and its worst outcome
+  is a plan that stops part-way: it asserts nothing after that point, so it *passes*, caches
+  green, and replays against later builds — a test exercising none of its subject reporting
+  success. A fresh compile is therefore checked against the prose (its size, and whether the
+  plan references what the test's closing steps name); a failure buys one guided recompile,
+  and a plan still short after that is **rejected at exit `1` and not cached**, so rerunning
+  compiles again rather than replaying it. Under `vk suite` that means `--retries` cannot turn
+  a truncated compile green. `VERIKUN_NO_COMPILE_CHECK=1` turns the check off. The stderr line
+  `compiled N top-level step(s)` (`planSteps` in `--json` and in a suite manifest row) is the
+  number to compare across runs of an unchanged test.
 - **Progress streams to stderr** (never silent in CI); **stdout is the report path**
   (`--json` for a structured summary). It records like any flow, so it ends with the
   same JUnit + HTML report — including the token/cost line and **suggested improvements**
@@ -409,7 +419,8 @@ vk ai onboarding.md --timeout 5m        # tighten the run timeout (default 15m)
   ever called to **compile** (once, on a cache miss) or to **repair** (≤3 per failing step);
   replay is always $0, and every non-`ai` command is $0 always. Full mechanism, the estimate
   formula and the cache multipliers: <https://ddikman.github.io/verikun/reference/cost/>.
-- Exit `0` pass · `1` a step failed (or the budget/timeout was hit) · `2` usage · `3` environment
+- Exit `0` pass · `1` a step failed (or the budget/timeout was hit, or the compile did not
+  cover the test) · `2` usage · `3` environment
   (e.g. the model's API key — `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` — unset, or the `codex` /
   `cursor-agent` CLI missing / not logged in for `--model codex-cli` / `cursor-cli`).
 - **`3` also means the device toolchain is broken**, checked *before* anything is compiled

package/CHANGELOG.md

@@ -6,38 +6,9 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
-### Added
-- **`@include <path>`** in a `vk ai` test inlines another file's prose, so a shared preamble
-  lives in one place. Paths resolve relative to the including file. ([#112])
-- **`vk server --log-file <path|off>`** writes a rotating server log, on by default at
-  `~/.verikun/logs/server-<port>.log`. `VERIKUN_LOG_FILE` sets the same value.
-- **`vk server`** re-adopts pooled devices that come back, sweeping every 60s with backoff.
-- **`/v1/health`** reports `degraded`: pool members still serving but dealt last.
-
-### Changed
-- **`vk suite`** skips `_`-prefixed `*.md` — those are shared fragments, not tests. ([#112])
-- **`vk ai`** compiles each chunk of an `@include`d test separately and caches it, so shared
-  prose is compiled once across a suite. ([#112])
-- **`vk server`** demotes a failing pooled device instead of dropping it, so capacity no
-  longer ratchets down and never recovers.
-- **`vk server`** deals leases healthy-first, then least-recently-used, instead of first-fit.
-- **`vk server`** no longer blames a device when the probe itself fails for a host reason.
-- **`vk server`** keeps the pool intact when an install fails on every device — the build is
-  the suspect, not the phones.
-- **`vk server`** logs error bodies, run tokens, leased serials and every lease eviction.
-- **`vk install`** (Android) removes a differently-signed build of the same package and retries,
-  instead of failing. Its app data is lost; stderr says so. ([#96])
-- **`VERIKUN_CLAIM_TTL_MIN`** now also paces a parallel suite's claim heartbeat — a quarter of
-  the window, capped at 60s — so a short TTL no longer races it.
-
-### Fixed
-- **`vk server`** terminates a worker that stops answering, instead of holding its lease
-  forever while health still advertises the device.
+## [0.26.0] - 2026-09-05
 
-[#96]: https://github.com/ddikman/verikun/issues/96
-[#112]: https://github.com/ddikman/verikun/issues/112
-
-## [0.26.0] - 2026-08-24
+Runs a suite across a pool of devices, and shares prose between tests with `@include`.
 
 ### Added
 - **`vk suite --devices a,b` / `--servers u1,u2`**: run tests across a device pool, next free
@@ -56,6 +27,18 @@ All notable changes to this project are documented here. The format is based on
   working directory don't delete each other's state.
 - **`POST /v1/lease`** and `capacity` / `devices` on `/v1/health`: which device a run token holds,
   and how many the server has.
+- **`@include <path>`** in a `vk ai` test inlines another file's prose, so a shared preamble
+  lives in one place. Paths resolve relative to the including file. ([#112])
+- **`vk server --log-file <path|off>`** writes a rotating server log, on by default at
+  `~/.verikun/logs/server-<port>.log`. `VERIKUN_LOG_FILE` sets the same value.
+- **`vk server`** re-adopts pooled devices that come back, sweeping every 60s with backoff.
+- **`/v1/health`** reports `degraded`: pool members still serving but dealt last.
+- **`VERIKUN_NO_PLAN_LOCK=1`** turns off plan-compile locking, restoring the previous
+  compile-in-parallel behaviour. ([#117])
+- **`VERIKUN_NO_COMPILE_CHECK=1`** turns off the `vk ai` compile-coverage check, restoring
+  the previous accept-anything behaviour. ([#127])
+- **`planSteps`** in a suite manifest row and `vk ai --json`: the plan's compiled size, next
+  to `steps` (what executed). ([#127])
 
 ### Changed
 - **Suite manifest**: adds `totals.wallClockMs`, `concurrency` and a per-test `device`.
@@ -77,13 +60,44 @@ All notable changes to this project are documented here. The format is based on
   phone unasked.
 - **`vk server` failover on a pool**: a failed device is quarantined and a healthy one takes its
   place, so capacity holds. ([#39], [#99])
+- **`vk suite`** skips `_`-prefixed `*.md` — those are shared fragments, not tests. ([#112])
+- **`vk ai`** compiles each chunk of an `@include`d test separately and caches it, so shared
+  prose is compiled once across a suite. ([#112])
+- **`vk suite`** lanes now wait for a shared `@include` fragment's first compile instead of
+  each paying for one. ([#117])
+- **`vk server`** demotes a failing pooled device instead of dropping it, so capacity no
+  longer ratchets down and never recovers.
+- **`vk server`** deals leases healthy-first, then least-recently-used, instead of first-fit.
+- **`vk server`** no longer blames a device when the probe itself fails for a host reason.
+- **`vk server`** keeps the pool intact when an install fails on every device — the build is
+  the suspect, not the phones.
+- **`vk server`** logs error bodies, run tokens, leased serials and every lease eviction.
+- **`vk install`** (Android) removes a differently-signed build of the same package and retries,
+  instead of failing. Its app data is lost; stderr says so. ([#96])
+- **`VERIKUN_CLAIM_TTL_MIN`** now also paces a parallel suite's claim heartbeat — a quarter of
+  the window, capped at 60s — so a short TTL no longer races it.
+- **Contributor docs**: rules stated once, with the history left to the docs site; the companion
+  notes no longer describe it as a prototype.
+- **Docs site**: the contracts, core-principles, plan-engine and AI-plans pages state each rule
+  once and link the page that owns the detail.
+- **Docs site**: shorter remote-device, troubleshooting and cost guides; global flags now live on
+  the Commands page — the standalone page is gone.
 
 ### Fixed
 - **`--server` runs no longer fail with `fetch failed`** when a step follows a pause longer
   than 5s, such as a cold compile.
 - **`--server` screenshots and failure evidence** are no longer corrupted in the archived report.
+- **`vk ai`** rejects a compile that covers only the start of its test, instead of caching
+  and replaying the short plan as a pass. Exit `1`. ([#127])
+- **`vk ai`** no longer seeds a new compile from a cached plan that is itself truncated. ([#127])
+- **`vk server`** terminates a worker that stops answering, instead of holding its lease
+  forever while health still advertises the device.
 
 [#39]: https://github.com/ddikman/verikun/issues/39
+[#96]: https://github.com/ddikman/verikun/issues/96
+[#112]: https://github.com/ddikman/verikun/issues/112
+[#117]: https://github.com/ddikman/verikun/issues/117
+[#127]: https://github.com/ddikman/verikun/issues/127
 
 ## [0.25.1] - 2026-08-21
 

package/README.md

@@ -6,7 +6,7 @@
 
 - **Agent CLI** — `vk <command>`: one-shot commands to inspect the screen as a semantic tree (or screenshot) and act on it.
 - **Puppeteer for native mobile** — a thin wrapper over native Android and iOS automation runners with zero runtime dependencies.
-- **Natural-language tests** — `vk ai <file>`: runs plain-English tests, compiled once and replayed model-free (~$0), calling a model only to self-heal a drifted step. Tests share a preamble with `@include`, written once instead of pasted into each. [What that costs](https://ddikman.github.io/verikun/reference/cost/), and how the `--max-cost-usd` ceiling bounds it.
+- **Natural-language tests** — `vk ai <file>`: runs plain-English tests, compiled once and replayed model-free (~$0), calling a model only to self-heal a drifted step. Tests share a preamble with `@include`, written once instead of pasted into each. A compile that does not cover its test is rejected rather than cached as a pass. [What that costs](https://ddikman.github.io/verikun/reference/cost/), and how the `--max-cost-usd` ceiling bounds it.
 - **Self-improving** — the agent runner will provide prescriptive improvements to existing scripts to help stabilise flakiness for future runs.
 - **CI-ready** — `vk suite` runs a folder of tests as one gated pass/fail run, across one device or a whole pool of them; `vk server` exposes real devices over an authenticated tunnel so a disposable CI runner (no phone attached) can still drive them, and routes around any that goes bad.
 
@@ -63,7 +63,7 @@ There is also no need for an MCP here: verikun runs locally with all its depende
 |---|---|
 | **Getting started** | [Installation](https://ddikman.github.io/verikun/getting-started/installation/) · [Your first test](https://ddikman.github.io/verikun/getting-started/your-first-test/) · [Using it from an AI agent](https://ddikman.github.io/verikun/getting-started/using-from-an-agent/) |
 | **Guides** | [Writing test cases](https://ddikman.github.io/verikun/guides/writing-test-cases/) · [Natural-language tests](https://ddikman.github.io/verikun/guides/natural-language-tests/) · [Suites](https://ddikman.github.io/verikun/guides/suites/) · [Remote devices & CI](https://ddikman.github.io/verikun/guides/remote-devices-and-ci/) · [iOS setup](https://ddikman.github.io/verikun/guides/ios-setup/) · [Platform support](https://ddikman.github.io/verikun/guides/platform-support/) · [Troubleshooting](https://ddikman.github.io/verikun/guides/troubleshooting/) |
-| **Reference** | [Commands](https://ddikman.github.io/verikun/reference/commands/) · [Selectors](https://ddikman.github.io/verikun/reference/selectors/) · [Auto-wait](https://ddikman.github.io/verikun/reference/auto-wait/) · [Global flags](https://ddikman.github.io/verikun/reference/global-flags/) · [Exit codes](https://ddikman.github.io/verikun/reference/exit-codes/) · [Environment variables](https://ddikman.github.io/verikun/reference/environment-variables/) · [Reports & test runs](https://ddikman.github.io/verikun/reference/reports-and-test-runs/) · [Device state](https://ddikman.github.io/verikun/reference/device-state/) · [Device claims](https://ddikman.github.io/verikun/reference/device-claims/) · [Screenshots](https://ddikman.github.io/verikun/reference/screenshots/) · [AI plans & models](https://ddikman.github.io/verikun/reference/ai-plans/) |
+| **Reference** | [Commands](https://ddikman.github.io/verikun/reference/commands/) · [Selectors](https://ddikman.github.io/verikun/reference/selectors/) · [Auto-wait](https://ddikman.github.io/verikun/reference/auto-wait/) · [Global flags](https://ddikman.github.io/verikun/reference/commands/#global-flags) · [Exit codes](https://ddikman.github.io/verikun/reference/exit-codes/) · [Environment variables](https://ddikman.github.io/verikun/reference/environment-variables/) · [Reports & test runs](https://ddikman.github.io/verikun/reference/reports-and-test-runs/) · [Device state](https://ddikman.github.io/verikun/reference/device-state/) · [Device claims](https://ddikman.github.io/verikun/reference/device-claims/) · [Screenshots](https://ddikman.github.io/verikun/reference/screenshots/) · [AI plans & models](https://ddikman.github.io/verikun/reference/ai-plans/) |
 | **Internals** | [Architecture](https://ddikman.github.io/verikun/internals/architecture/) · [Core principles](https://ddikman.github.io/verikun/internals/core-principles/) · [Plan IR & the replay engine](https://ddikman.github.io/verikun/internals/plan-ir-and-engine/) · [Contracts](https://ddikman.github.io/verikun/internals/contracts/) · [Contributing](https://ddikman.github.io/verikun/internals/contributing/) |
 
 **Exit codes**, since they are the machine contract everything else rests on: `0` success · `1` not found / assertion failed / timeout · `2` usage error, ambiguous selector, or a device another job is driving · `3` environment error. Data goes to stdout; diagnostics to stderr. [Full contract](https://ddikman.github.io/verikun/reference/exit-codes/). Parallel agents share a host-level [device claim](https://ddikman.github.io/verikun/reference/device-claims/) so two jobs do not silently land on the same phone.
@@ -83,17 +83,7 @@ npm test         # type-check + the unit suite (no device needed)
 npm link         # optional: put `verikun` and `vk` on your PATH
 ```
 
-Zero runtime dependencies; the only dev dependencies are `typescript` and `@types/node`. The full contributor guide — the test loop, the Flutter device fixture, versioning and releasing — is in [Contributing](https://ddikman.github.io/verikun/internals/contributing/).
-
-To work on the [documentation site](https://ddikman.github.io/verikun/), which is an Astro Starlight project in `docs/` with its own dependencies (so `npm install` above does not cover it):
-
-```sh
-npm run docs:install   # once — installs the site's dependencies (needs Node >= 22.12)
-npm run docs           # dev server with live reload at http://localhost:4321/verikun/
-npm run docs:build     # production build; fails on a dead internal link
-```
-
-Open **http://localhost:4321/verikun/** — the site is served under a base path, so bare `localhost:4321` is a 404. Astro needs **Node ≥ 22.12** while the CLI supports Node ≥ 18, so `nvm use 22` first if your shell's Node is older.
+Zero runtime dependencies; the only dev dependencies are `typescript` and `@types/node`. The full contributor guide — the test loop, the Flutter device fixture, versioning and releasing, and running the documentation site locally — is [Contributing](https://ddikman.github.io/verikun/internals/contributing/).
 
 ## License
 

package/dist/agent/cache.js

@@ -10,6 +10,7 @@ const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const output_1 = require("../output");
+const claims_1 = require("../device/claims");
 const version_1 = require("../version");
 const ir_1 = require("./ir");
 const grammar_1 = require("./grammar");
@@ -86,7 +87,10 @@ function writePlan(input, plan) {
         plan,
     };
     const target = entryPath(planKey(input));
-    const tmp = `${target}.tmp-${process.pid}-${Date.now()}`;
+    // pid + a monotonic counter, not pid + a clock: two writes inside one millisecond would
+    // collide on a timestamp, and `tmpPath` is the one place that shape is decided (it also
+    // guarantees the name never ends in `.json`, so `findSeed` skips a stray scratch file).
+    const tmp = (0, claims_1.tmpPath)(target);
     (0, node_fs_1.writeFileSync)(tmp, JSON.stringify(entry, null, 2));
     (0, node_fs_1.renameSync)(tmp, target);
     return entry;

package/dist/agent/claude.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ClaudeProvider = void 0;
 const errors_1 = require("../errors");
-const format_1 = require("../ui/format");
+const wait_1 = require("../wait");
 const ir_1 = require("./ir");
 const provider_1 = require("./provider");
 const grammar_1 = require("./grammar");
@@ -18,8 +18,6 @@ const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
 // effort (output_config.effort) is rejected by Haiku 4.5; only send it for models
 // that accept it.
 const EFFORT_MODELS = new Set(['claude-opus-4-8', 'claude-sonnet-4-6', 'claude-fable-5']);
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-const backoffMs = (attempt) => Math.min(1000 * 2 ** (attempt - 1), 15000);
 class ClaudeProvider {
     opts;
     constructor(opts) {
@@ -30,27 +28,8 @@ class ClaudeProvider {
         return { plan: (0, ir_1.parsePlan)(json), usage };
     }
     async repair(ctx) {
-        const parts = [
-            'FAILED STEP: ' + JSON.stringify(ctx.failedStep),
-            'FAILURE: ' + ctx.reason,
-        ];
-        if (ctx.candidates && ctx.candidates.length) {
-            parts.push(`The selector matched ${ctx.candidates.length} elements (ambiguous) — pick a more specific selector for the SAME intended element, or give_up if none of them is it.`);
-        }
-        parts.push('CURRENT SCREEN:\n' + (0, format_1.formatCompact)(ctx.hierarchy));
-        const { json, usage } = await this.call(grammar_1.REPAIR_GRAMMAR, parts.join('\n\n'), ir_1.REPAIR_DECISION_JSON_SCHEMA, 1024);
-        const decision = (json ?? {});
-        if (decision.decision === 'give_up') {
-            return {
-                replaceStep: null,
-                declineReason: decision.reason?.trim() || 'no element on the current screen matches the step intent',
-                usage,
-            };
-        }
-        // Hand the proposed leaf back UNVALIDATED — engine.ts validates every repair against
-        // the grammar before splicing (it is the execution trust boundary and can't assume a
-        // provider validated). A missing/invalid step is rejected there as a failed repair.
-        return { replaceStep: (decision.step ?? null), usage };
+        const { json, usage } = await this.call(grammar_1.REPAIR_GRAMMAR, (0, provider_1.repairUserPrompt)(ctx), ir_1.REPAIR_DECISION_JSON_SCHEMA, 1024);
+        return (0, provider_1.repairDecision)(json, usage);
     }
     async call(system, user, schema, maxTokens) {
         const outputConfig = { format: { type: 'json_schema', schema } };
@@ -111,7 +90,7 @@ class ClaudeProvider {
             catch (e) {
                 if (attempt++ >= maxRetries)
                     throw new errors_1.CliError(`Anthropic API request failed: ${e.message}`, 3);
-                await sleep(backoffMs(attempt));
+                await (0, wait_1.sleep)((0, wait_1.backoffMs)(attempt));
                 continue;
             }
             finally {
@@ -122,7 +101,7 @@ class ClaudeProvider {
             // Retry 429 + 5xx with backoff, honoring Retry-After (no SDK to do it for us).
             if ((res.status === 429 || res.status >= 500) && attempt++ < maxRetries) {
                 const retryAfter = Number(res.headers.get('retry-after'));
-                await sleep(Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : backoffMs(attempt));
+                await (0, wait_1.sleep)(Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : (0, wait_1.backoffMs)(attempt));
                 continue;
             }
             const errText = await res.text().catch(() => '');

package/dist/agent/cli-provider.js

@@ -8,7 +8,6 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_os_1 = require("node:os");
 const errors_1 = require("../errors");
-const format_1 = require("../ui/format");
 const ir_1 = require("./ir");
 const provider_1 = require("./provider");
 const grammar_1 = require("./grammar");
@@ -153,23 +152,8 @@ class CliProvider {
         return { plan: (0, ir_1.parsePlan)(json), usage: {} };
     }
     async repair(ctx) {
-        const parts = ['FAILED STEP: ' + JSON.stringify(ctx.failedStep), 'FAILURE: ' + ctx.reason];
-        if (ctx.candidates && ctx.candidates.length) {
-            parts.push(`The selector matched ${ctx.candidates.length} elements (ambiguous) — pick a more specific selector for the SAME intended element, or give_up if none of them is it.`);
-        }
-        parts.push('CURRENT SCREEN:\n' + (0, format_1.formatCompact)(ctx.hierarchy));
-        const json = this.call(grammar_1.REPAIR_GRAMMAR, parts.join('\n\n'), ir_1.REPAIR_DECISION_JSON_SCHEMA);
-        const decision = (json ?? {});
-        if (decision.decision === 'give_up') {
-            return {
-                replaceStep: null,
-                declineReason: decision.reason?.trim() || 'no element on the current screen matches the step intent',
-                usage: {},
-            };
-        }
-        // Hand the proposed leaf back UNVALIDATED — engine.ts validates every repair against the
-        // grammar before splicing (it is the execution trust boundary), exactly like the API providers.
-        return { replaceStep: (decision.step ?? null), usage: {} };
+        // usage:{} for the same reason as compile — billed to the subscription, not per token.
+        return (0, provider_1.repairDecision)(this.call(grammar_1.REPAIR_GRAMMAR, (0, provider_1.repairUserPrompt)(ctx), ir_1.REPAIR_DECISION_JSON_SCHEMA), {});
     }
     /** Spawn the CLI once and return the parsed JSON object it produced. Synchronous (spawnSync);
      *  the async method wrappers satisfy the Promise-returning AgentProvider seam. */

package/dist/agent/engine.js

@@ -6,6 +6,7 @@ const node_crypto_1 = require("node:crypto");
 const selector_1 = require("../ui/selector");
 const state_support_1 = require("../ui/state-support");
 const errors_1 = require("../errors");
+const wait_1 = require("../wait");
 const ir_1 = require("./ir");
 /** An outcome is environment-flavoured if it carries an exit-3 CliError, or simply
  *  reported code 3 — the latter also catches a remote step whose error crossed the
@@ -70,11 +71,10 @@ function isHealable(outcome) {
 }
 /** Default wall-clock ceiling for a whole `vk ai` run (overridable via --timeout). */
 exports.DEFAULT_RUN_TIMEOUT_MS = 15 * 60 * 1000;
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /** How long a CONDITIONAL guard (`if-present`) waits for its selector to show up
  *  before concluding "absent". Interstitials animate in: a permission dialog or promo
  *  panel typically lands a few hundred ms after the transition that triggers it. Every
- *  selector-resolving leaf command already auto-waits ~5s (cli.ts resolveOneWaiting),
+ *  selector-resolving leaf command already auto-waits ~5s (commands/auto-wait.ts),
  *  so before this window existed a guard was strictly LESS patient than a bare `tap` —
  *  and an optional dialog could be missed by the very construct meant to catch it.
  *  Kept far below the leaf 5s because an ABSENT guard pays this window, every time, and
@@ -242,7 +242,7 @@ async function runPlan(plan, deps) {
                     throw new GuardBlindError(selector, lastErr);
                 return false;
             }
-            await sleep(Math.max(0, Math.min(GUARD_POLL_MS, remaining)));
+            await (0, wait_1.sleep)(Math.max(0, Math.min(GUARD_POLL_MS, remaining)));
         }
     };
     const runLeaf = (leaf) => {
@@ -397,7 +397,7 @@ async function runPlan(plan, deps) {
                 // to happen. Fail where the information is.
                 return { status: 'fail', where, reason: `read found no element matching '${selector}' (nothing to store in ctx.${node.into})` };
             }
-            await sleep(Math.max(0, Math.min(GUARD_POLL_MS, remaining)));
+            await (0, wait_1.sleep)(Math.max(0, Math.min(GUARD_POLL_MS, remaining)));
         }
     }
     async function walkNode(node, where, replace, guard) {

package/dist/agent/ir.js

@@ -63,6 +63,30 @@ exports.KNOWN_COMMANDS = new Set([
     // non-recordable selector-resolver here (e.g. `find`) would corrupt an unrelated step.
 ]);
 exports.DEFAULT_LOOP_CAP = 25;
+// The two SIMPLE control nodes appear at every unrolled level (see innerControls), so
+// their shape is written once. Key order is the wire format — keep it.
+const ifPresentSchema = (body) => ({
+    type: 'object',
+    additionalProperties: false,
+    required: ['type', 'selector', 'body'],
+    properties: {
+        type: { type: 'string', enum: ['if-present'] },
+        selector: { type: 'string' },
+        body,
+    },
+});
+const whilePresentSchema = (body) => ({
+    type: 'object',
+    additionalProperties: false,
+    required: ['type', 'selector', 'cap', 'body'],
+    properties: {
+        type: { type: 'string', enum: ['while-present'] },
+        selector: { type: 'string' },
+        bind: { type: 'string' },
+        cap: { type: 'integer' },
+        body,
+    },
+});
 /**
  * JSON Schema for `output_config.format` so the model returns a guaranteed-valid
  * Plan. Deliberately NON-RECURSIVE: instead of a `Plan -> node -> Plan` cycle
@@ -73,16 +97,7 @@ const stepItems = (bodyItems) => ({
     anyOf: [
         leafSchema(),
         readSchema(),
-        {
-            type: 'object',
-            additionalProperties: false,
-            required: ['type', 'selector', 'body'],
-            properties: {
-                type: { type: 'string', enum: ['if-present'] },
-                selector: { type: 'string' },
-                body: { type: 'array', items: bodyItems },
-            },
-        },
+        ifPresentSchema({ type: 'array', items: bodyItems }),
         {
             type: 'object',
             additionalProperties: false,
@@ -112,18 +127,7 @@ const stepItems = (bodyItems) => ({
                 body: { type: 'array', items: bodyItems },
             },
         },
-        {
-            type: 'object',
-            additionalProperties: false,
-            required: ['type', 'selector', 'cap', 'body'],
-            properties: {
-                type: { type: 'string', enum: ['while-present'] },
-                selector: { type: 'string' },
-                bind: { type: 'string' },
-                cap: { type: 'integer' },
-                body: { type: 'array', items: bodyItems },
-            },
-        },
+        whilePresentSchema({ type: 'array', items: bodyItems }),
     ],
 });
 /** The innermost level: leaves, reads, and the two SIMPLE control nodes — `if-present`
@@ -148,30 +152,7 @@ const stepItems = (bodyItems) => ({
  *  here is what would actually cost the schema. */
 const innerControls = () => {
     const leafBody = { type: 'array', items: { anyOf: [leafSchema(), readSchema()] } };
-    return [
-        {
-            type: 'object',
-            additionalProperties: false,
-            required: ['type', 'selector', 'body'],
-            properties: {
-                type: { type: 'string', enum: ['if-present'] },
-                selector: { type: 'string' },
-                body: leafBody,
-            },
-        },
-        {
-            type: 'object',
-            additionalProperties: false,
-            required: ['type', 'selector', 'cap', 'body'],
-            properties: {
-                type: { type: 'string', enum: ['while-present'] },
-                selector: { type: 'string' },
-                bind: { type: 'string' },
-                cap: { type: 'integer' },
-                body: leafBody,
-            },
-        },
-    ];
+    return [ifPresentSchema(leafBody), whilePresentSchema(leafBody)];
 };
 const LEAF_ONLY_ITEMS = { anyOf: [leafSchema(), readSchema(), ...innerControls()] };
 exports.PLAN_JSON_SCHEMA = {