verikun 0.29.0 → 0.29.1

package/CHANGELOG.md

@@ -6,6 +6,14 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.29.1] - 2026-09-26
+
+### Fixed
+- **`vk ai`** no longer guesses `id:` selectors; an element the test names only by label compiles
+  to `text:` — write the id into the test to pin it. ([#148])
+
+[#148]: https://github.com/ddikman/verikun/issues/148
+
 ## [0.29.0] - 2026-09-16
 
 ### Changed

package/dist/agent/grammar.js

@@ -118,7 +118,7 @@ Do NOT hard-code a run of indices you were not told the length of. If the prose
 varies per run — emit a while-present over {{ctx.i}} rather than tap _0, _1, _2, _3.
 A hard-coded list is right only when the prose states the exact count.
 
-SELECTORS (the engine auto-heals case/whitespace/partial, so prefer stable identifiers):
+SELECTORS (the engine auto-heals case/whitespace/partial, so prefer an id the test gives you):
   @login            resource-id 'login' (shorthand for id:login)
   id:login          resource-id (full, suffix, or short)
   text:Sign in      visible text (case-insensitive)
@@ -156,7 +156,17 @@ RULES:
   below the fold — that is now redundant. Emit an explicit swipe only when the SCROLLING
   ITSELF is what the test asks for ("scroll the feed three times"), or to reveal content
   that is not in the hierarchy until it is built (an infinite/lazy list).
-- Prefer resource-id / accessibility selectors over visible text where possible.
+- IDS COME FROM THE TEST. Use @x / id:x only with an id the test writes (or one a PRIOR PLAN
+  shown to you already uses). You cannot see the app, so never compose an id from a label, a
+  description, or the pattern of the app's other ids: a made-up id matches nothing, and a
+  wait/assert on it FAILS the test with no repair. An element the test names only by what it
+  says ("tap Sign in", "the Home tab") is text:<those words> — forgiving, and it also matches an
+  accessibility label.
+- An outcome the test states ("the tab bar (Home, Search, Profile) appears") is checked on what
+  it NAMES — the id it gives, or the words it quotes or lists — never on an id you made up. A
+  description that names nothing you could select without inventing it ("it shows the
+  signed-in user's name") is context, not a step; so is rationale (why a step exists, what a
+  field already holds).
 - Translate the test literally and minimally: do not invent ACTION steps (tap/text/swipe/key/assert)
   the prose does not imply. The ONE exception is screenshot — insert screenshot steps liberally as
   post-run review evidence: after each screen transition (launch, a navigation tap, a submit, a

package/dist/agent/lint.js

@@ -2,7 +2,7 @@
 // Compile-fidelity lint: does the plan the model produced still say what the prose said?
 //
 // The model is a compiler, and this is the compiler's own sanity check. It exists because
-// compilation is NONDETERMINISTIC in a way that is invisible until a run fails, and three
+// compilation is NONDETERMINISTIC in a way that is invisible until a run fails, and four
 // failure modes showed up repeatedly against a real suite:
 //
 //   1. An explicit directive silently vanishes. The same prose ("Launch the app WITH ITS
@@ -18,8 +18,12 @@
 //      against later builds. A test exercising none of its subject reporting success is the
 //      worst failure mode a testing tool has, which is why the two rules that detect it are
 //      the only FATAL findings here.
+//   4. A selector names an id the test never gave (issue #148). The compiler cannot see the
+//      app, so it composed one from the app's naming pattern, and 3 of 4 such guesses named
+//      nothing in the app. A wait/assert is never repaired, so the test went red — and each
+//      recompile guessed differently, so it flaked.
 //
-// 1 and 2 are cheap to detect and cheap to fix: hand the finding back to the model and let
+// 1, 2 and 4 are cheap to detect and cheap to fix: hand the finding back to the model and let
 // it compile once more. That is far better than the alternative, which is a plan that is
 // quietly wrong and burns a device run to say so. 3 gets the same guided recompile, but a
 // plan that STILL does not cover its test must never run — see `fatal` below.
@@ -34,9 +38,11 @@ exports.instructionLines = instructionLines;
 exports.instructionUnits = instructionUnits;
 exports.actionNodes = actionNodes;
 exports.tailAnchors = tailAnchors;
+exports.ungroundedIds = ungroundedIds;
 exports.lintPlan = lintPlan;
 exports.looksTruncated = looksTruncated;
 const ir_1 = require("./ir");
+const selector_1 = require("../ui/selector");
 /** Walk every node in the plan, including control-node bodies. */
 function* walk(nodes) {
     for (const n of nodes) {
@@ -257,15 +263,95 @@ function planMentions(tokens, anchor) {
         return b.length >= 3 && (b.includes(a) || a.includes(b));
     });
 }
+// --- ids: does every id the plan selects by come from the prose? (issue #148) ------------
+/** Commands whose FIRST positional is a selector. The rest of `text`'s positionals, and every
+ *  positional of `type`/`launch`/…, is data — `type @handle` types a handle, it selects nothing. */
+const SELECTOR_FIRST = new Set(['tap', 'click', 'text', 'wait', 'assert']);
+/** Every string the engine resolves as a selector — unlike `planTokens`, which also returns data. */
+function selectorsOf(plan) {
+    const out = [];
+    for (const n of walk(plan.steps)) {
+        if (n.type === 'command') {
+            if (SELECTOR_FIRST.has(n.command) && n.positionals[0])
+                out.push(n.positionals[0]);
+            if (n.command === 'swipe' || n.command === 'scroll') {
+                for (const f of n.flags)
+                    if (f.name === 'on')
+                        out.push(f.value);
+            }
+        }
+        else if (n.type === 'when') {
+            out.push(...n.branches.map((b) => b.selector));
+        }
+        else {
+            out.push(n.selector);
+        }
+    }
+    return out;
+}
+/** The id values (`@x` / `id:x`) the plan selects by, parsed by the engine's own parser so the
+ *  two can never disagree about what an id selector is — trailing state modifiers included. */
+function planIds(plan) {
+    const out = [];
+    for (const raw of selectorsOf(plan)) {
+        let sel;
+        try {
+            sel = (0, selector_1.parseSelector)(raw);
+        }
+        catch {
+            continue; // an empty value or contradictory modifiers: a runtime error, not a guess
+        }
+        if (sel.kind === 'id' && !out.includes(sel.value))
+            out.push(sel.value);
+    }
+    return out;
+}
+/** `com.app:id/login` and `login` name the same element. */
+const RESOURCE_PKG_RE = /^[\w.]+:id\//;
+/** `{{ctx.i}}` / `{{env.X}}` are filled at run time, so they are never part of a guess. */
+const PLACEHOLDER_RE = /\{\{[^}]*\}\}/;
+/** The literal parts of an id worth judging. Under three characters a substring matches
+ *  anything, so a part that short has no opinion. */
+const idParts = (id) => id
+    .replace(RESOURCE_PKG_RE, '')
+    .split(PLACEHOLDER_RE)
+    .map(normToken)
+    .filter((p) => p.length >= 3);
+/** Every word of the prose, and every quoted span whole — an iOS identifier may hold spaces. */
+function proseTokens(nl) {
+    const out = [];
+    for (const m of nl.matchAll(ANCHOR_RE))
+        out.push(m[1] ?? m[2] ?? m[3] ?? '');
+    out.push(...nl.split(/[\s`"“”'‘’()[\]{}<>,;!?]+/));
+    return out.map(normToken).filter((t) => t.length > 0);
+}
+/**
+ * The ids the plan selects by that neither the prose nor `seed` gives — each one a guess.
+ *
+ * LENIENT on purpose, since a false positive costs a recompile: an id is grounded when every
+ * literal part of it (package qualifier and placeholders dropped, case and punctuation ignored)
+ * sits inside ONE token of the prose, so `@spinner` is grounded by `vk_spinner` and
+ * `id:option_{{ctx.i}}` by `option_0`. One token, never two: `settings_tab` built from the words
+ * "Settings tab" is precisely how a guess is made.
+ *
+ * `seed` is a prior plan the compiler was told to reuse. A green run re-persists the HEALED plan
+ * and a repair takes its id off a live screen, so an id a seed already uses is grounded too —
+ * pass one only where it can hold a repair (see `compileFromSegments` in ../cli.ts).
+ */
+function ungroundedIds(nl, plan, seed) {
+    const ground = [...proseTokens(nl), ...(seed ? planIds(seed).flatMap(idParts) : [])];
+    return planIds(plan).filter((id) => idParts(id).some((part) => !ground.some((t) => t.includes(part))));
+}
 /**
  * Check a compiled plan against the prose it came from.
  *
  * @param nl   the natural-language test, verbatim
  * @param plan the plan the model just produced
+ * @param seed the prior plan the model was handed to adapt, if any — its ids are not guesses
  * @returns findings; empty means the plan is consistent with the prose. A finding with
  *          `fatal` set means the plan does not cover the test and must not be run.
  */
-function lintPlan(nl, plan) {
+function lintPlan(nl, plan, seed) {
     const findings = [];
     if (FRESH_START_RE.test(nl) && !hasLeafWithFlag(plan, 'launch', 'clear')) {
         findings.push({
@@ -281,6 +367,21 @@ function lintPlan(nl, plan) {
                 '(skip when absent), or behind when (when the screen is one of several known kinds).',
         });
     }
+    // Not fatal: a guess that happens to be right still runs, and a wrong one fails its step
+    // loudly, so the guided recompile is the remedy. The exception is an ABSENCE check (`--gone`,
+    // a guard that skips): it passes on any selector that never matches, a wrong label as much as
+    // a guessed id, so making this rule fatal would not close it.
+    const guessed = ungroundedIds(nl, plan, seed);
+    if (guessed.length > 0) {
+        const named = guessed.slice(0, 5).map((id) => JSON.stringify(id)).join(', ');
+        findings.push({
+            message: `The plan selects by id ${named}${guessed.length > 5 ? ` and ${guessed.length - 5} more` : ''}, but the test ` +
+                `never gives ${guessed.length === 1 ? 'that id' : 'those ids'}. You cannot see the app, so an id the test does not state is a guess — it matches ` +
+                'nothing, and a wait/assert on it fails the test with no repair. Use an id only when the test writes it; ' +
+                'select an element the test names by its label with text:<label>, and do not check something the test ' +
+                'names nothing selectable for.',
+        });
+    }
     if (!coverageChecksEnabled())
         return findings;
     const units = instructionUnits(nl);

package/dist/cli.js

@@ -1905,7 +1905,14 @@ async function compileFromSegments(segments, key, opts, cost, provider) {
             // FREE, and refusing it over a ceiling we were never about to spend against would fail
             // a test for somebody else's tokens.
             assertBudgetForCompile(cost, opts.maxCostUsd, `compiling ${where} — the test is only partly compiled`);
-            const seed = seedPlan(segKey, where);
+            // A section's entry is only ever raw compile output — a green run re-persists the WHOLE
+            // test's key, never a section's — so an id in it that its own prose never gives can only be
+            // a guess (issue #148), and handing it back as "reuse this" would keep it alive.
+            let seed = seedPlan(segKey, where);
+            if (seed && (0, lint_1.ungroundedIds)(seg.text, seed.plan).length > 0) {
+                (0, output_1.err)(`[ai] ${where}: ignoring a prior plan that guesses ids its prose never gives — compiling fresh`);
+                seed = null;
+            }
             (0, output_1.err)(`[ai] ${where}: compiling with ${opts.model}…${lock.degraded ? ` (${lock.degraded})` : ''}`);
             let compiled;
             try {
@@ -1939,6 +1946,14 @@ async function compileFromSegments(segments, key, opts, cost, provider) {
                 (0, output_1.err)(`[ai] ${where}: the compiled section does not cover its prose (${compiled.plan.steps.length} step(s)) — not caching it; compiling the test as one instead`);
                 return null; // the finally below releases the lock
             }
+            // A guessed id in a FRAGMENT is issue #148 spliced into every test that includes it. Same
+            // answer as a short section: keep it out of the cache and compile the test whole, where the
+            // lint hands the guess back for one guided recompile.
+            const guessed = (0, lint_1.ungroundedIds)(seg.text, compiled.plan);
+            if (guessed.length > 0) {
+                (0, output_1.err)(`[ai] ${where}: the compiled section selects by ids its prose never gives (${guessed.join(', ')}) — not caching it; compiling the test as one instead`);
+                return null; // the finally below releases the lock
+            }
             // INSIDE the lock and before the release: a waiter re-reads the cache the instant the
             // lock disappears, so releasing first would hand it a miss and buy the second compile
             // this whole mechanism exists to prevent.
@@ -2013,7 +2028,10 @@ async function obtainPlan(key, file, opts, cost, provider, segments = []) {
     // sometimes only the test's opening compiles at all. One guided retry is much cheaper
     // than discovering it as a device-run failure several steps later, or (worse, for a
     // truncation) as a pass. Budget is re-checked HERE: the first attempt is already billed.
-    let remaining = (0, lint_1.lintPlan)(key.nl, compiled.plan);
+    //
+    // The seed goes in too: a green run re-persists the HEALED plan, whose repaired ids came off a
+    // live screen, so flagging them would push every new build off a selector the device confirmed.
+    let remaining = (0, lint_1.lintPlan)(key.nl, compiled.plan, seed?.plan);
     if (remaining.length > 0) {
         const feedback = remaining.map((f) => `- ${f.message}`).join('\n');
         (0, output_1.err)(`[ai] compiled plan does not match the test — recompiling once:\n${feedback}`);
@@ -2029,7 +2047,7 @@ async function obtainPlan(key, file, opts, cost, provider, segments = []) {
                 retryFeedback: feedback,
             });
             cost.add(retry.usage, 'compile');
-            const still = (0, lint_1.lintPlan)(key.nl, retry.plan);
+            const still = (0, lint_1.lintPlan)(key.nl, retry.plan, seed?.plan);
             // Keep the retry either way: it was compiled with strictly more information. If it
             // still trips the lint, say so rather than pretending the plan is clean — and for a
             // coverage finding, do not claim it will run, because the gate below rejects it.

package/dist/version.js

@@ -3,4 +3,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // GENERATED by scripts/gen-version.mjs from package.json's "version" at build time
 // (the `prebuild` script). Do NOT edit by hand; bump package.json instead.
-exports.VERSION = '0.29.0';
+exports.VERSION = '0.29.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verikun",
-  "version": "0.29.0",
+  "version": "0.29.1",
   "description": "Drive Android emulators/devices and iOS simulators for AI agents: tap, type, swipe, screenshot, and inspect the UI hierarchy by semantic identifiers — like Puppeteer for native apps.",
   "keywords": [
     "android",