@sun-asterisk/sungen 3.2.24-beta.6 → 3.2.24

package/src/generators/test-generator/adapters/appium/templates/test-file.hbs

@@ -72,20 +72,38 @@ async function __ensureVisible(selector: string): Promise<WebdriverIO.Element> {
   }
   const safeBottom = Math.round(winH * 0.82); // above the floating bottom-nav band
   let lastY: number | null = null;
+  let lastEl: WebdriverIO.Element | null = null;
   for (let __i = 0; __i < 12; __i++) {
     let y: number | null = null;
+    let existsUndisplayed = false;
     try {
       const el = await $(selector);
       if (await el.isDisplayed()) {
         const r = await driver.getElementRect(el.elementId);
-        if (r.y + r.height <= safeBottom) return el; // rendered AND fully above the floating bottom nav → done
+        // Done when the element sits fully above the floating bottom-nav band — OR is simply too
+        // tall to ever fit there (a scroll container / full-screen list): demanding "fully above"
+        // from such an element makes the loop scroll a page that was already correct, dragging
+        // list-hosted siblings (e.g. the top bar as first list item) out of the viewport.
+        if (r.y + r.height <= safeBottom || r.height >= safeBottom) return el;
         y = r.y;
+        lastEl = el;
+      } else if (el.elementId) {
+        existsUndisplayed = true; // in the tree, just not visible right now
       }
     } catch { /* off-screen / not in tree yet → keep scrolling */ }
+    // Overlay grace (Android mirror of the iOS render grace above): the element is IN the tree but
+    // reports not-displayed — typically a launch popup/overlay covering it that auto-dismisses
+    // within seconds. Scrolling now would carry a list-hosted element (a Compose top bar is often
+    // the first list item) clean out of the viewport, where a down-only loop can never recover it —
+    // so wait the overlay out before the first scroll.
+    if (existsUndisplayed && __i < 4) { await driver.pause(1200); continue; }
     // No-progress break: the element is on screen but a prior scroll didn't move it — it's a FIXED
     // element (e.g. a bottom-nav tab, intentionally in the nav band) or we've hit the end of the
     // scrollable. Stop rather than burn the whole budget; the caller acts on it where it is.
-    if (y !== null && lastY !== null && Math.abs(y - lastY) < 2) return $(selector);
+    // Return the RESOLVED element, never a fresh $() stub: on an animation-churned tree (a looping
+    // banner is enough) a from-scratch re-find takes seconds and outlasts the caller's assertion
+    // budget — the element we just measured is the one the caller should act on.
+    if (y !== null && lastY !== null && Math.abs(y - lastY) < 2) return lastEl ?? $(selector);
     lastY = y;
     await driver.execute('mobile: scrollGesture', { left: 60, top: 420, width: 960, height: 1320, direction: 'down', percent: 0.5 });
     await driver.pause(300);
@@ -116,6 +134,74 @@ async function __assertVisible(selector: string): Promise<void> {
   }
   throw new Error(`Expect ${JSON.stringify(selector)} to be displayed — iOS geometry oracle: rect=${JSON.stringify(r)} is not on screen (0x0 = not rendered / scrolled out)`);
 }
+
+// Checkbox / toggle / radio state oracle. There is NO single authoritative source for it on
+// mobile, and the standard one lies in a way that cannot be detected from the read itself:
+// UiAutomator2 puts `checked` on EVERY Android node and defaults it to "false" when the widget
+// publishes no checked semantics. So a custom-rendered control — a Flutter widget without
+// `Semantics(checked: …)`, an RN `Pressable` without `accessibilityState={ checked: … }` — is not
+// ABSENT from the tree, it reports a confident false while sitting visibly ON, and a strict
+// `toHaveAttribute('checked','true')` fails with no way to see why.
+// Hence: probe every signal both runtimes expose, and let the DIRECTION of the assertion decide
+// how to combine them (__assertCheckedState below).
+//   Android: `checked`, `selected`, isSelected()   iOS: `value` ("1"/"0"), `selected`, isSelected()
+// Descendants are probed too, bounded: on a composite row (label + control merged into one a11y
+// node) the state routinely sits on an inner node while the queried outer node reports the default.
+// A child xpath must start with `.//` — a leading `//` is ABSOLUTE in Appium even when chained.
+async function __probeCheckedSignals(el: WebdriverIO.Element): Promise<{ source: string; value: boolean }[]> {
+  const out: { source: string; value: boolean }[] = [];
+  const read = async (node: WebdriverIO.Element, prefix: string): Promise<void> => {
+    for (const attr of driver.isIOS ? ['value', 'selected'] : ['checked', 'selected']) {
+      let raw: string | null = null;
+      try { raw = await node.getAttribute(attr); } catch { continue; } // attribute unsupported on this node
+      const v = String(raw ?? '').trim().toLowerCase();
+      if (v === 'true' || v === '1') out.push({ source: `${prefix}${attr}="${raw}"`, value: true });
+      else if (v === 'false' || v === '0') out.push({ source: `${prefix}${attr}="${raw}"`, value: false });
+      // anything else (empty, a real iOS `value` string like "Off") carries no parseable state → skip
+    }
+    try { out.push({ source: `${prefix}isSelected()`, value: await node.isSelected() }); } catch { /* not supported here */ }
+  };
+  await read(el, '');
+  // Only descend when the node itself yielded nothing positive — otherwise we already have the
+  // answer and a subtree walk would turn one assertion into dozens of round-trips for nothing.
+  if (!out.some(s => s.value)) {
+    let kids: WebdriverIO.Element[] = [];
+    try { kids = await el.$$('.//*'); } catch { /* no child query on this node */ }
+    for (const k of kids.slice(0, 8)) await read(k, 'descendant.');
+  }
+  return out;
+}
+
+// Assert checked/unchecked from the probed signals. The two directions are deliberately NOT
+// symmetric, because the evidence isn't:
+//   checked   → ANY credible positive signal passes. One runtime exposing the state is enough;
+//               demanding the standard attribute is what breaks custom-rendered controls.
+//   unchecked → NO signal anywhere may be positive. Strictly stronger than reading one attribute,
+//               so a visibly-ON custom toggle can't slip through as a false PASS.
+// Polls like WDIO's own matchers do — a tap-then-assert reads the tree mid-animation.
+// KNOWN LIMIT, stated rather than hidden: on Android a UiAutomator2-defaulted `checked="false"` is
+// indistinguishable from a genuine false — that information is not in the tree. So `unchecked`
+// passes on "no positive signal anywhere", which is the strongest available evidence, not proof.
+async function __assertCheckedState(el: WebdriverIO.Element, expected: boolean, label: string): Promise<void> {
+  // Fail loud with the REAL cause when the element never resolved (mirrors check-action, #430).
+  if (!el.elementId) throw new Error((el as any).error?.message || `Element not found: ${el.selector}`);
+  let signals: { source: string; value: boolean }[] = [];
+  for (let __i = 0; __i < 10; __i++) {
+    signals = await __probeCheckedSignals(el);
+    if (signals.some(s => s.value) === expected) return;
+    await driver.pause(500);
+  }
+  const want = expected ? 'checked' : 'unchecked';
+  if (signals.length === 0) {
+    throw new Error(
+      `Expect ${label} to be ${want} — the control publishes NO checked/selected state, on itself or any child. ` +
+      `A custom-rendered control has to publish it for any tool to read it: Flutter → wrap it in Semantics(checked: …); ` +
+      `React Native → accessibilityState={ checked: … }. Until then assert a visible consequence instead ` +
+      `(a label/text change), or tag the scenario @manual.`,
+    );
+  }
+  throw new Error(`Expect ${label} to be ${want} — read [${signals.map(s => `${s.source} → ${s.value}`).join(', ')}]`);
+}
 {{#if singleAuthRole}}
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -133,7 +219,9 @@ function __authSelector(s: { type: string; value: string }): string {
     case 'accessibility-id': case 'testid': case 'label': case 'placeholder': case 'text': return '~' + s.value;
     case 'android-uiautomator': return 'android=' + s.value;
     case 'ios-predicate': return '-ios predicate string:' + s.value;
-    case 'id': return 'id=' + s.value;
+    // Appium's id strategy prepends `<appPackage>:id/` to colon-less values, which breaks bare
+    // Compose testTagsAsResourceId ids — match those exactly via UiSelector on Android instead.
+    case 'id': return (!driver.isIOS && !s.value.includes(':')) ? 'android=new UiSelector().resourceId("' + s.value + '")' : 'id=' + s.value;
     case 'xpath': case 'locator': default: return s.value;
   }
 }
@@ -205,10 +293,29 @@ async function __ensureAuth(role: string): Promise<void> {
   }
 
   // ── Mode B: legacy authedMarker (present on the landing screen ⟺ logged in) ──
-  const markerPresent = async (): Promise<boolean> => present(cfg.authedMarker, 6000);
-  if (await markerPresent()) return; // idempotent — already authenticated (session kept by noReset)
+  // markerTimeoutMs: contract override for slow-booting apps — a cold start that needs 10-15s+ to
+  // render the landing screen false-negatives the 6s default into "logged out" and then blocks the
+  // spec when the login form never appears.
+  const __budget = cfg.markerTimeoutMs || 6000;
+  // When the contract also names a loggedOutMarker (an element unique to the login screen), the
+  // state is decided by WHICHEVER marker renders first (alternating short probes): a slow-booting
+  // landing screen costs only its real boot time instead of gambling on one fixed timeout, and a
+  // genuine logged-out state is detected without waiting out the full authed budget first.
+  if (cfg.loggedOutMarker) {
+    let loggedOut = false;
+    const __t0 = Date.now();
+    while (Date.now() - __t0 < __budget) {
+      if (await present(cfg.authedMarker, 3000)) return; // logged in — nothing to do
+      if (await present(cfg.loggedOutMarker, 3000)) { loggedOut = true; break; }
+    }
+    if (!loggedOut) {
+      throw new Error(`@auth:${role} could not decide the login state within ${__budget}ms — neither authedMarker nor loggedOutMarker rendered. Check the markers in ${rel}.`);
+    }
+  } else if (await present(cfg.authedMarker, __budget)) {
+    return; // idempotent — already authenticated (session kept by noReset)
+  }
   await runSteps(cfg.loginSteps);
-  if (!(await markerPresent())) {
+  if (!(await present(cfg.authedMarker, __budget))) {
     throw new Error(`@auth:${role} login failed — verify credentials / loginSteps / authedMarker in ${rel}.`);
   }
 }
@@ -267,25 +374,32 @@ describe('{{featureName}}', () => {
     // of cold-starting, which strands top-of-screen elements above the viewport.
     await driver.pause(500);
     await driver.activateApp(__APP_PKG__);
+    // Restore the NATIVE context — a prior scenario that entered a WebView (`switch to [X] frame`)
+    // without switching back would otherwise poison every following native find.
+    try { await driver.switchContext('NATIVE_APP'); } catch { /* single-context session */ }
     // Restore portrait so a prior scenario's `rotate to landscape` can't leak into this one — the
     // app relaunch above resets in-app state, but device orientation is OS-level and persists.
     try { await driver.setOrientation('PORTRAIT'); } catch { /* orientation control not supported */ }
     // Settle after a cold (re)launch: a Flutter app first renders a BLANK accessibility skeleton
     // (nested FrameLayout/View, no content-desc) for several seconds before the real tree appears.
-    // That skeleton is static, so a "two equal reads" check alone false-positives on it and we'd
-    // proceed before any element exists (→ every find fails). So require the tree to (a) contain
-    // rendered content — at least one non-empty content-desc/text — AND (b) be stable across two
-    // reads. A generous timeout covers slow cold renders on a stressed emulator. Best-effort: a
-    // timeout never fails the scenario, it just falls through to the step's own auto-wait.
-    let __prevSrc = '';
+    // So require rendered content — at least one non-empty content-desc/text — on two consecutive
+    // reads before proceeding. A generous timeout covers slow cold renders on a stressed emulator.
+    // Best-effort: a timeout never fails the scenario, it just falls through to the step's own
+    // auto-wait.
+    // "Settled" = rendered content present on TWO consecutive reads. Deliberately NOT full source
+    // equality: a UI with any looping animation (a rotating promo carousel is enough) never yields
+    // two identical snapshots, so an equality oracle starves and burns the whole timeout on every
+    // scenario. Two content-bearing reads still reject the blank first-frame skeleton (no
+    // content-desc/text at all) that a single read could false-positive on.
+    let __prevHadContent = false;
     await driver
       .waitUntil(
         async () => {
           const src = await driver.getPageSource();
           const hasContent = /content-desc="[^"]+"|\btext="[^"]+"/.test(src);
-          const stable = hasContent && src === __prevSrc;
-          __prevSrc = src;
-          return stable;
+          const settled = hasContent && __prevHadContent;
+          __prevHadContent = hasContent;
+          return settled;
         },
         { timeout: 30000, interval: 400, timeoutMsg: 'UI did not settle (no rendered content)' },
       )

package/src/generators/test-generator/template-engine.ts

@@ -43,6 +43,10 @@ export class TemplateEngine {
       return String(text).replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
     });
 
+    Handlebars.registerHelper('includes', function(text: string, search: string) {
+      return typeof text === 'string' && text.includes(search);
+    });
+
     // Comparison helpers for conditional logic
     Handlebars.registerHelper('eq', function(a: any, b: any) {
       return a === b;

package/src/generators/test-generator/utils/selector-resolver.ts

@@ -677,6 +677,10 @@ export class SelectorResolver {
       case 'android-uiautomator':
       case 'ios-predicate':
       case 'id':
+      // css: only meaningful INSIDE a WebView context (hybrid screens, after `switch to [X]
+      // frame`) — the appium adapter's partial already renders it raw; without this pass-through
+      // the type fell to the placeholder strategy and compiled to an undefined selector.
+      case 'css':
         return withExtras({
           strategy: type,
           value,

package/src/harness/audit.ts

@@ -236,7 +236,9 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   const ledger = viewpointLedger(viewpointPath, scenarios, featureText);
   const negSideEffect = negativeSideEffect(scenarios);
   const ownership = crossArtifactOwnership(screenDir, scenarios);
-  const unsourced = sourceBacked(scenarios, parseSpecClauses(specPath).frs.map((f) => f.id), parseViewpointItems(viewpointPath).map((i) => i.text), viewpoints.map((v) => v.id), featureText);
+  // @exploration scenarios are probes outside the official suite — the finding's own fix
+  // ("tag it @exploration") must actually exempt them from source tracing.
+  const unsourced = sourceBacked(scenarios.filter((s) => !s.exploration), parseSpecClauses(specPath).frs.map((f) => f.id), parseViewpointItems(viewpointPath).map((i) => i.text), viewpoints.map((v) => v.id), featureText);
 
   // H3 — stateful-flow regression depth. For a UI flow whose scenarios mutate a cart/checkout
   // collection, the regression dimensions (count/quantity proof · teardown · multi-source) cap the

package/src/harness/capability-plan.ts

@@ -153,7 +153,9 @@ export function manualReasonMismatches(featurePath: string): ReasonMismatch[] {
     for (let k = i + 1; k < lines.length && k <= i + 16; k++) {
       const l = lines[k].trim();
       if (/^#/.test(l)) parts.push(l.replace(/^#+\s*/, ''));
-      else if (l === '') continue;
+      // A blank line after collected comments ends the body block — scanning past it would
+      // swallow the NEXT section's banner comment and mis-infer the reason code from it.
+      else if (l === '') { if (parts.length) break; continue; }
       else break;
     }
     // The block scanned here includes the tester PROCEDURE, so several codes can

package/src/harness/parse.ts

@@ -36,6 +36,7 @@ export interface ScenarioInfo {
   queryRefs?: string[];       // named queries referenced by this scenario (inline `query [name]` + @query: tags)
   apiRefs?: string[];         // named API endpoints referenced by this scenario (@api: tags)
   requiresCaps?: string[];    // @requires:<cap> — automation-ready but needs an opt-in driver (TQ-11)
+  exploration?: boolean;      // @exploration — a probe outside the official suite, exempt from source tracing
   deferredToFlow?: boolean;   // @deferred:flow — owned by a flow, not automated on this screen (H6)
   ownedByFlow?: string;       // @owned-by:<flow> — the flow that owns this deferred scenario (H6)
   /** Ordered steps with their resolved bucket (And/But inherit) — flow handoff analysis (#569). */
@@ -253,6 +254,7 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
     queryRefs: queryRefs.size ? [...queryRefs] : undefined,
     apiRefs: apiRefs.size ? [...apiRefs] : undefined,
     requiresCaps: requiresCaps.length ? requiresCaps : undefined,
+    exploration: tags.some((t) => /^@exploration\b/i.test(t)) || undefined,
     deferredToFlow: deferredToFlow || undefined,
     ownedByFlow,
   };

package/src/harness/script-check.ts

@@ -197,8 +197,12 @@ export async function runScriptCheck(screenDir: string, screenName: string, kind
   // ONLY the template form, so on the current codegen every @cases scenario was
   // reported MISSING (+ its test EXTRA) despite compiling and running fine.
   // Canonicalize the extracted title to the bare scenario name so both shapes
-  // (and plain titles) compare on the same footing.
-  const canonSpecTitle = (t: string) => t.replace(/\s*—(\s*\$\{__row\.__label\})?$/, '');
+  // (and plain titles) compare on the same footing. Mobile/mocha specs append the
+  // tags to the title (`it('<name> [@high @spec:FR-01]')` — mocha has no tag option),
+  // so strip that suffix too or every mobile scenario reads MISSING + EXTRA (#429).
+  const canonSpecTitle = (t: string) => t
+    .replace(/\s*\[@[^\]]*\]$/, '')
+    .replace(/\s*—(\s*\$\{__row\.__label\})?$/, '');
   const specTitleSet = new Set(specTitles.map(canonSpecTitle));
   const expectedSet = new Set(automated.map((s) => s.name));
   const missingInSpec = automated.filter((s) => !specTitleSet.has(s.name)).map((s) => s.name);

package/src/harness/sensors.ts

@@ -17,6 +17,8 @@ import { readTextFile } from './read-text';
 const BUSINESS_CRITICAL_CATS = [
   // UI commerce cores
   'LIST', 'CART', 'PRODUCT', 'FILTER', 'CHECKOUT', 'ORDER', 'DETAIL', 'DISCOVERY', 'CATEGORY', 'BRAND', 'DUPLICATE', 'CONSISTENCY',
+  // Payment surfaces are business-core in any commerce/fintech app (JALPAY, PAYMENT, WALLET …)
+  'PAY', 'WALLET',
   // API / DB capability cores — for an api/db suite the operation IS the business core
   'API', 'ENDPOINT', 'CRUD', 'QUERY', 'CONTRACT', 'RESOURCE',
 ];
@@ -27,7 +29,9 @@ const BUSINESS_CRITICAL_CATS = [
 const BUCKET_ORDER: Array<[string, string[]]> = [
   ['business-core', BUSINESS_CRITICAL_CATS],
   ['behavior', ['LOGIC', 'TRANSITION', 'WORKFLOW']],
-  ['validation-security', ['VAL', 'SEC', 'SUB', 'AUTH', 'LOGIN']],
+  // ERROR/EMPTY: error handling and empty-state guards are the same defensive family as
+  // validation — every non-trivial suite declares them, so `other` would swallow them.
+  ['validation-security', ['VAL', 'SEC', 'SUB', 'AUTH', 'LOGIN', 'ERROR', 'EMPTY']],
   ['navigation', ['NAV']],
   ['presentation', ['UI', 'LAYOUT', 'RESPONSIVE', 'DISPLAY', 'SEO', 'ACCESSIBILITY', 'USABILITY', 'VISUAL']],
 ];

package/src/orchestrator/mobile-runtime-scaffolder.ts

@@ -61,7 +61,11 @@ export function emitMobileRuntime(cwd: string, opts: MobileInitOptions): Scaffol
       // appActivity is optional — leave empty when not provided so UiAutomator2
       // auto-resolves the launcher activity from appPackage. Only pin when explicitly passed.
       .replace('__APP_ACTIVITY__', opts.appActivity || '')
-      .replace('__ANDROID_UDID__', opts.androidUdid || 'emulator-5554')
+      // GLOBAL replace: the template holds this placeholder twice (the connectivity self-heal
+      // helper + the 'appium:udid' capability, #615). String-form .replace would fill only the
+      // first and ship a literal '__ANDROID_UDID__' as the session udid. Do NOT globalize the
+      // others: __APP_ACTIVITY__/__IOS_VERSION__ keep a second occurrence as sentinel comparisons.
+      .replace(/__ANDROID_UDID__/g, opts.androidUdid || 'emulator-5554')
       .replace('__IOS_BUNDLE_ID__', opts.iosBundleId || 'com.example.app')
       .replace('__IOS_DEVICE__', opts.iosDevice || 'iPhone 16')
       .replace('__IOS_VERSION__', opts.iosVersion || '18.0');

package/src/orchestrator/templates/ai-src/skills/sungen-gherkin-syntax/SKILL.md

@@ -257,7 +257,7 @@ Full config + catalog examples → **Advanced → Database** doc.
 
 ### Unsupported DB engine — fallback (ask, don't improvise)
 
-Direct SQL verification (`@query`, the Data Driver) covers these SQL engines: **`{postgres, sqlite, mysql}`** — plus the three native NoSQL engines above (Cosmos, MongoDB, DynamoDB). When a datasource's `engine` (or the DB the user describes) is **outside all of those** — e.g. Cassandra, Oracle, Neo4j, a proprietary store:
+Direct SQL verification (`@query`, the Data Driver) covers these SQL engines: **`{postgres, sqlite, device-sqlite, mysql}`** (`device-sqlite` = an ON-DEVICE app database on a mobile project — pulled fresh per query through the Appium session via `package:` + `db_path:`; debuggable build or emulator required) — plus the three native NoSQL engines above (Cosmos, MongoDB, DynamoDB). When a datasource's `engine` (or the DB the user describes) is **outside all of those** — e.g. Cassandra, Oracle, Neo4j, a proprietary store:
 
 1. **Do not** attempt a direct connect. **Do not** improvise a verification method.
 2. Present a fixed `AskUserQuestion` with exactly these 3 branches (always these, no others invented):
@@ -275,7 +275,7 @@ Direct SQL verification (`@query`, the Data Driver) covers these SQL engines: **
 Example:
 ```
 AskUserQuestion:
-  question: "This datasource's engine (cassandra) isn't a supported Data Driver engine ({postgres, sqlite, mysql} + Cosmos/MongoDB/DynamoDB) — direct connect isn't supported. How should DB state be verified?"
+  question: "This datasource's engine (cassandra) isn't a supported Data Driver engine ({postgres, sqlite, device-sqlite, mysql} + Cosmos/MongoDB/DynamoDB) — direct connect isn't supported. How should DB state be verified?"
   options:
     - "@api — verify via the project's internal API (Recommended: qa/api/ catalog found)"
     - "@manual — emit a @manual step + cqlsh check"
@@ -317,7 +317,13 @@ Every claim below is checked against a shipped `.hbs` under
 
 **Mobile-only `[mobile]`** — the gesture catalog (swipe, long-press, pinch-zoom, pull-to-refresh,
 rotate, background/foreground, notifications, grant-permission, clipboard set, set-geolocation,
-hide-keyboard, tap-top-of) has no web counterpart. Full syntax → `sungen-mobile-gestures`.
+hide-keyboard, tap-top-of) has no web counterpart, and neither do the lifecycle / device-state /
+timing steps (`restart the app`, `reinstall the app`, `turn airplane mode|wifi|mobile data on|off`,
+`turn device location on|off` — the latter two Android-only, throw on iOS — the window
+assertions `see [X] disappear within N seconds` / `still visible after N seconds`, and the
+device-oracle trio `open deep link {{url}}` · `see device log contains {{v}}` · `pass|fail
+biometric authentication` (biometric = emulator/Simulator only).
+Full syntax → `sungen-mobile-gestures`.
 
 **Divergences — compiles on both, means something different:**
 
@@ -328,7 +334,7 @@ hide-keyboard, tap-top-of) has no web counterpart. Full syntax → `sungen-mobil
 | `wait for [T] page` | waits for the URL | fixed `driver.pause(500)` settle — not a real wait condition |
 | `hover [T] icon \| row` | real hover | no-op — hover-revealed content is normally already visible on mobile; use `tap` |
 | `fill [T] alert with {{v}}` | fills native `prompt()` | no-op (comment only) — app-specific, handle manually |
-| `switch to [T] frame` | enters an `<iframe>` | switches a hybrid app's WebView context; no-op on a pure-native screen (no WebView found) |
+| `switch to [T] frame` | enters an `<iframe>` | switches a hybrid app's WebView context; no-op on a pure-native screen. **Needs `APPIUM_CHROMEDRIVER_AUTODOWNLOAD=1`** (.env.appium) or the switch fails with "No Chromedriver found". INSIDE the webview, selectors are **css/xpath only** — UiSelector-based types and the text-value asserts (`label with {{v}}`) don't apply there; assert element presence via css/xpath refs, then `switch to [main] frame` back |
 | `see [X] with {{v}}` (filtered visibility forms) | CSS `hasText` filter | hand-rolled substring match over `getText()`/`content-desc` (Android) or `label`/`value` (iOS) — same substring semantics, different attribute set |
 | `… is sorted …` / `… is loading` inside a filtered row/state check | reads `aria-sort`/`aria-busy` | **throws** — no native analog for these two states specifically (the plain, unfiltered `is loading` on a spinner still works on both) |
 | `scope: dialog` selector option | resolves inside the dialog | no effect (`SG-W021`) — steps resolve against the whole screen |

package/src/orchestrator/templates/ai-src/skills/sungen-mobile-gestures/SKILL.md

@@ -38,6 +38,29 @@ patterns (`click`, `hover`, `fill`) don't cover.
 >   requests it yet — there is currently no phrasing that compiles to an actual clipboard-read
 >   assertion. Don't author "see clipboard contains X" expecting it to compile; tag it `@manual` instead.
 > - **`set location to {{lat}}, {{lng}}`** → `driver.setGeoLocation(...)`.
+> - **`restart the app`** → kill → relaunch → content settle (same oracle as the per-scenario
+>   relaunch). THE step for persistence oracles: pinned card, dismissal survival, show-once tooltips.
+> - **`reinstall the app`** → remove → install from the session's build file → launch. **Requires
+>   the session to have installed via `APP_APK` / `IOS_APP`** (the `appium:app` cap) — attaching by
+>   package only makes the step fail loud with that exact fix in the message.
+> - **`turn airplane mode|wifi|mobile data on|off`** → `mobile: setConnectivity`. **Android-only** —
+>   XCUITest cannot toggle connectivity; on iOS the step throws loud. Keep such scenarios
+>   `@platform:android`. Do NOT author cleanup steps to restore connectivity "in case the test
+>   dies": the generated `wdio.conf.ts` restores the baseline (airplane off, wifi/data/location on)
+>   via adb in `onPrepare`/`onComplete`, healing even a run whose Appium session died mid-toggle (#615).
+> - **`turn device location on|off`** → `mobile: isGpsEnabled` + `mobile: toggleGps` (the execute
+>   aliases — WDIO v9 dropped the legacy wrappers), idempotent. **Android-only**, throws loud on iOS.
+> - **`see [X] disappear within N seconds`** → reverse `waitForDisplayed` with the step's deadline
+>   (+2s churn grace) — the auto-dismiss / expiry oracle (a 5s tooltip, a 60s barcode).
+> - **`see [X] still visible after N seconds`** → wait out the window, then the platform-aware
+>   visibility oracle — the "must NOT auto-dismiss / must stay valid" counterpart.
+> - **`open deep link {{url}}`** → `mobile: deepLink` (VIEW intent / XCUITest deepLink with the
+>   feature's app id) — THE entry for push-param / universal-link routing scenarios.
+> - **`see device log contains {{v}}`** → logcat (Android) / syslog (iOS) poll-accumulate ≤10s —
+>   makes SILENT failure modes and analytics events observable (they leave only a log line).
+> - **`pass|fail biometric authentication`** (face wording → iOS faceId) → **emulator/Simulator
+>   only**: Android `mobile: fingerprint` (finger 1 must be ENROLLED; fail = unenrolled id), iOS
+>   `mobile: sendBiometricMatch`. Real devices reject the command — the step fails loud.
 >
 > 📜 **`scroll to [X]` — two failure modes seen, with the real cause (measured):**
 > 1. *"Default scrollable element '//android.widget.ScrollView' not found"* — wdio's mobile scroll runs

package/src/orchestrator/templates/env.appium.example

@@ -23,3 +23,14 @@ JAVA_HOME=/opt/homebrew/opt/openjdk@21
 # IOS_UDID=<device-udid>             # REQUIRED — physical device (`xcrun xctrace list devices`), not a sim
 # IOS_BUNDLE_ID=<ios bundle id>      # REQUIRED — the iOS bundle (⚠ NOT the Android package)
 # IOS_TEAM_ID=<Apple Team ID>        # REQUIRED — 10-char id (Xcode → Settings → Accounts)
+
+# ════════════ Appium server security (opt-in) ════════════
+# Allow `mobile: shell` (raw adb passthrough) for device-level oracles (e.g. pulling an app's
+# SQLite DB via run-as). Starts the server with --allow-insecure=uiautomator2:adb_shell.
+# SECURITY: gives the session shell access — enable only on trusted local/dev machines,
+# never on shared CI runners you don't control.
+# APPIUM_ALLOW_ADB_SHELL=1
+
+# Hybrid WebView: auto-download the chromedriver matching the device's WebView (needed by
+# `switch to [X] frame` on hybrid screens). Downloads a binary at session start — opt-in.
+# APPIUM_CHROMEDRIVER_AUTODOWNLOAD=1

package/src/orchestrator/templates/specs-db.ts

@@ -27,7 +27,7 @@ const ident = (s: string): string => {
 // SQL engines: verified via the direct guarded-SELECT path and needing the `$n`→`?` placeholder
 // rewrite. This literal is the single source of truth for that rewrite condition and is quoted, by
 // name, in the sungen-gherkin-syntax skill's "direct SQL verification" note — keep them in sync.
-const SUPPORTED_ENGINES = ['postgres', 'sqlite', 'mysql'] as const;
+const SUPPORTED_ENGINES = ['postgres', 'sqlite', 'device-sqlite', 'mysql'] as const;
 // NoSQL engines: implement the Engine contract natively (no SQL rewrite). Tracked separately so the
 // SQL-rewrite guard and its skill-parity test stay pinned to the three SQL engines above.
 const NOSQL_ENGINES = ['cosmos', 'mongodb', 'dynamodb'] as const;
@@ -43,9 +43,15 @@ interface SshConfig {
 }
 
 interface DataSourceConfig {
-  engine: 'postgres' | 'mysql' | 'sqlite' | 'cosmos' | 'mongodb' | 'dynamodb';
+  engine: 'postgres' | 'mysql' | 'sqlite' | 'device-sqlite' | 'cosmos' | 'mongodb' | 'dynamodb';
   url: string;
   readonly?: boolean;
+  // device-sqlite (mobile): an ON-DEVICE app database, pulled FRESH per query through the active
+  // Appium session (pullFile's `@<package>/<path>` app-container syntax — run-as under the hood,
+  // so it needs a debuggable build or an emulator). `package` = the app id, `db_path` = the
+  // path inside the app's data dir (e.g. databases/app.db). No `url`. Same SQLite dialect.
+  package?: string;
+  db_path?: string;
   statement_timeout_ms?: number;
   max_rows?: number;
   // Fallback path: tunnel the DB SOCKET through an SSH bastion. DB-only — the browser/E2E
@@ -160,7 +166,7 @@ function loadConfig(): Record<string, DataSourceConfig> {
  * reorder is essential there too (an author-written PartiQL `WHERE sk = $2 AND pk = $1`).
  */
 export function rewritePlaceholders(engine: string, sql: string, params: any[]): { sql: string; params: any[] } {
-  if (engine !== 'sqlite' && engine !== 'mysql' && engine !== 'dynamodb') return { sql, params };
+  if (engine !== 'sqlite' && engine !== 'device-sqlite' && engine !== 'mysql' && engine !== 'dynamodb') return { sql, params };
   let out = '';
   let inStr = false;
   const newParams: any[] = [];
@@ -517,10 +523,11 @@ class DataSource {
     const { key, conf } = this.cfg(name);
     if (this.engines.has(key)) return { engine: this.engines.get(key)!, conf };
     let engine: Engine;
-    if (conf.engine === 'postgres' || conf.engine === 'mysql' || conf.engine === 'sqlite') {
-      // url is required for the SQL engines (host-based, or a sqlite file path). NoSQL engines that
-      // have no connection URL (e.g. DynamoDB region+creds) supply their own config and skip this.
-      if (!conf.url) throw new Error(`Data Driver: datasource "${key}" has no url (set it in .env.qa).`);
+    if (conf.engine === 'postgres' || conf.engine === 'mysql' || conf.engine === 'sqlite' || conf.engine === 'device-sqlite') {
+      // url is required for the HOST-based SQL engines (or a sqlite file path). device-sqlite has
+      // no url — the file comes off the device (package + db_path, validated in its exec builder);
+      // NoSQL engines without a URL (e.g. DynamoDB region+creds) also supply their own config.
+      if (!conf.url && conf.engine !== 'device-sqlite') throw new Error(`Data Driver: datasource "${key}" has no url (set it in .env.qa).`);
       engine = new SqlEngine(conf.engine, await this.sqlExec(key, conf));
     } else if (conf.engine === 'cosmos') {
       engine = this.cosmosEngine(key, conf);
@@ -586,6 +593,62 @@ class DataSource {
         }
       };
     }
+    // device-sqlite — an ON-DEVICE app database. Every query pulls a FRESH copy through the
+    // active Appium session so the oracle always reads CURRENT device state (persistence checks
+    // assert AFTER actions). pullFile's `@<package>/<path>` app-container syntax uses run-as
+    // under the hood → needs a debuggable build or an emulator. SQLite WAL sidecars (-wal/-shm)
+    // are pulled best-effort alongside: Room defaults to WAL, where recent commits live in the
+    // -wal file — without it the main file silently misses the newest writes.
+    if (conf.engine === 'device-sqlite') {
+      if (!conf.package || !conf.db_path) {
+        throw new Error(`Data Driver: datasource "${key}" (device-sqlite) needs package: and db_path: (path inside the app data dir, e.g. databases/app.db).`);
+      }
+      const pkg = conf.package;
+      const rel = conf.db_path.replace(/^\/+/, '');
+      return async (sql, params) => {
+        const wd = (globalThis as any).driver;
+        if (!wd || typeof wd.pullFile !== 'function') {
+          throw new Error(`Data Driver: datasource "${key}" (device-sqlite) needs an active Appium session — device @query steps only run inside mobile specs.`);
+        }
+        const fs = require('node:fs'); const os = require('node:os'); const path = require('node:path');
+        const base = path.join(os.tmpdir(), `sungen-devdb-${process.pid}-${Date.now()}`);
+        const files: string[] = [];
+        const pull = async (suffix: string, required: boolean): Promise<void> => {
+          let b64: string | null = null;
+          let pullErr: unknown;
+          try {
+            b64 = await wd.pullFile(`@${pkg}/${rel}${suffix}`);
+          } catch (e) {
+            pullErr = e;
+            // pullFile's container route does `run-as cp → /data/local/tmp`, which newer Android
+            // blocks for the app UID. Fallback: stream base64 over run-as via `mobile: shell`
+            // (opt-in — APPIUM_ALLOW_ADB_SHELL=1, see the wdio.conf template).
+            try {
+              const out = await wd.execute('mobile: shell', { command: 'run-as', args: [pkg, 'base64', `${rel}${suffix}`] });
+              b64 = String(out).replace(/\s+/g, '');
+            } catch (e2) {
+              if (required) {
+                throw new Error(`Data Driver: could not pull @${pkg}/${rel} from the device. pullFile: ${pullErr} · shell fallback: ${e2} — needs a DEBUGGABLE build; if pullFile's container route fails on this Android version, set APPIUM_ALLOW_ADB_SHELL=1 (.env.appium).`);
+              }
+              return;
+            }
+          }
+          if (b64 == null) return;
+          fs.writeFileSync(base + suffix, Buffer.from(b64, 'base64'));
+          files.push(base + suffix);
+        };
+        await pull('', true);
+        await pull('-wal', false);
+        await pull('-shm', false);
+        try {
+          const Database = require('better-sqlite3');
+          const db = new Database(base, { readonly: false }); // WAL recovery needs write access to the TEMP copy
+          try { return db.prepare(sql).all(...params); } finally { db.close(); }
+        } finally {
+          for (const f of files) { try { fs.unlinkSync(f); } catch { /* best-effort */ } }
+        }
+      };
+    }
     // sqlite
     if (conf.ssh) console.warn(`Data Driver: datasource "${key}" sets ssh: but engine is sqlite (file-based) — ssh ignored.`);
     const Database = require('better-sqlite3');