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

package/src/orchestrator/templates/ai-src/skills/sungen-tc-review/SKILL.md

@@ -46,7 +46,12 @@ Hard-fail gate. Any ✗ is a syntax error — must be fixed; do not score furthe
 - [ ] `Given` → only `is on` · `When` → action (click/fill/select/press/clear/check/uncheck/hover/wait) · `Then` → only `see` · `And` inherits the preceding keyword
 - [ ] NO `Given User see…` (→ `Then`, or entry assertion `Given User is on [X] page`)
 - [ ] NO `When … And User is on [X] dialog` (→ `And User see` or a separate `Given`)
+- [ ] `dismiss [X]` is SETUP, never proof — it is best-effort and never fails, so a scenario that
+      claims an overlay closed must assert it: `Then User see [X] is hidden` (mobile: tap the
+      close/scrim node explicitly, then assert)
+- [ ] `is on` takes ONLY `[X] page` (`[X] screen` on mobile) / `[X] dialog` — `is on [X] step|section|card` ✗ (it compiles to a real navigation, or to a URL assertion that cannot fail). A state inside the page → `Then User see [X] section`.
 - [ ] NO literal-URL navigation (`navigate to "/x"`) → `User is on [X] page` + declare in `selectors.yaml`
+- [ ] NO `{{var}}` inside a `[Target]` (`[{{confirm_value}}]` ✗) — a target is a selector key matched literally. For text that varies (locale, `@cases` column) keep the target static and move the variable into the selector entry's `name:`/`value:`, or pick by text with `with {{var}}`. Only a browser-storage key may embed one.
 
 ### A2. Action → Element type
 
@@ -67,6 +72,16 @@ Hard-fail gate. Any ✗ is a syntax error — must be fixed; do not score furthe
 ### A4. Assertion (8 patterns → determines the Playwright assertion)
 
 - [ ] Visibility `see [T] type` → NO redundant `is visible`; hidden uses `is hidden`
+- [ ] **No state clause on `[T] page`** — `page is hidden`/`is empty`/… are not step forms. `page`
+      asserts a URL, so the clause is dropped and the assertion inverts (`SG-E021`). Assert the
+      expected page, or a marker element
+- [ ] **The state is one the step form can actually assert** — a `wait for` honours only
+      `hidden`/`visible`/`disabled`/`enabled`; `row in [T] table` / `column in [T] table` honour
+      only `is hidden`. Anything else is dropped (`SG-E021`) — move the state onto the element
+- [ ] **No invented step forms** — every step matches a pattern in `sungen-gherkin-syntax`. An
+      unmatched step compiles to a runtime `throw` (`SG-W001`), never a silent pass; park a
+      genuinely unautomatable check as `@manual`
+- [ ] A spec `Format:` line → `matches "<format>"`, NOT `with {{v}}` (an exact value pins data that changes daily; `contains` proves nothing)
 - [ ] Correct pattern: text(`message/header/label with {{v}}`) · partial(`text contains {{v}}`) · input(`field/dropdown with {{v}}`) · state(`is …`) · attribute(`image/link with {{v}}`) · count(`row with {{count}}`) · page(`[T] page`)
 - [ ] Table: `[Col] column in [Table] table`, `[Ref] row in [Table] table with {{v}}`, `table with {{count}}`/`is empty`, `table match data:`; row scope used correctly
 

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

@@ -23,3 +23,24 @@ 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)
+
+# ════════════ State reset between scenarios ════════════
+# Raises the reset floor for a WHOLE run without regenerating any spec — CI can run stricter than
+# local dev. It never LOWERS a tier a feature declared with @reset:. Tiers, weakest → strongest:
+#   none  nothing reset (state carries over by design)      0s
+#   soft  terminate + relaunch — THE DEFAULT               ~1–3s
+#   data  + wipe local DB / cache / prefs / keychain        ~2–5s   (iOS: reinstalls, needs IOS_APP)
+#   full  + remove and reinstall (permissions too)          ~5–30s  (needs APP_APK / IOS_APP)
+# ⚠ data and full WIPE APP DATA on the target device — emulator / dedicated test device only.
+# SUNGEN_RESET_TIER=data
+
+# ════════════ 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-api.ts

@@ -58,6 +58,124 @@ function substitute(text: string, params: Record<string, any>): string {
 function substituteRaw(text: string, params: Record<string, any>): string {
   return text.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, (_m, p) => String(params[p] ?? ''));
 }
+
+/** The five predefined XML entities — a bound value containing a bare `&` or `<` would
+ *  otherwise re-create exactly the invalid_xml rejection this encoding exists to avoid. */
+function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/**
+ * Bind `:param` tokens into an XML string template by WHITELIST of the passed param
+ * names — a generic `:word` scan would mangle namespace prefixes (soapenv:Envelope).
+ * Longest name first + a word-boundary lookahead so `:id` can never eat the prefix
+ * of `:id_2` or the head of `:idx`. Values are XML-escaped by default; a token the
+ * template wraps as `<![CDATA[:param]]>` binds raw inside its CDATA section instead.
+ * Replacer FUNCTIONS everywhere — a value containing `$&`-style sequences must never
+ * be interpreted as a replacement pattern.
+ */
+function bindXmlParams(template: string, params: Record<string, any>): string {
+  let out = template;
+  for (const name of Object.keys(params).sort((a, b) => b.length - a.length)) {
+    const value = String(params[name] ?? '');
+    // A value containing "]]>" would terminate the CDATA section early and ship
+    // malformed XML — split it across two sections so the document stays valid.
+    const cdataSafe = value.split(']]>').join(']]]]><![CDATA[>');
+    out = out.replace(new RegExp(`<!\\[CDATA\\[:${name}\\]\\]>`, 'g'), () => `<![CDATA[${cdataSafe}]]>`);
+    out = out.replace(new RegExp(`:${name}(?![A-Za-z0-9_])`, 'g'), () => escapeXml(value));
+  }
+  return out;
+}
+
+/** Decode an XML-ish response body: Content-Type charset, else the XML declaration's
+ *  encoding (read from an ASCII-compatible prefix), else UTF-8. Unknown charsets fall
+ *  back to UTF-8 rather than failing the whole request. */
+function decodeXmlAwareText(bytes: Buffer, contentType: string): string {
+  // A UTF-16 BOM means the latin1 declaration scan below would see NUL-laden
+  // garbage that still "parses" \u2014 decode by the BOM first.
+  if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe) return new TextDecoder('utf-16le').decode(bytes);
+  if (bytes.length >= 2 && bytes[0] === 0xfe && bytes[1] === 0xff) return new TextDecoder('utf-16be').decode(bytes);
+  const head = bytes.subarray(0, 200).toString('latin1');
+  const declared = (head.match(/^\uFEFF?\s*<\?xml[^>]*\bencoding=["']([^"']+)["']/i) || [])[1];
+  // Candidates in precedence order; an unsupported CT charset falls back to the
+  // XML declaration's encoding rather than straight to a mojibake UTF-8 decode.
+  const candidates = [(contentType.match(/charset=["']?([^;"'\s]+)/i) || [])[1], declared, 'utf-8'];
+  for (const charset of candidates) {
+    if (!charset) continue;
+    try { return new TextDecoder(charset).decode(bytes); } catch { /* next candidate */ }
+  }
+  return new TextDecoder('utf-8').decode(bytes);
+}
+
+/**
+ * Parse an XML response body to a plain object, or null on a real parse failure (the
+ * caller then keeps the raw string, matching the non-JSON behavior).
+ *
+ * Locked parser posture:
+ *  - processEntities/htmlEntities OFF — fast-xml-parser's entity processing (ON by
+ *    default, including DOCTYPE entities) is exactly the XXE-shaped surface a QA tool
+ *    must not expose to a live server's response. The five predefined entities are
+ *    decoded AFTERWARDS by our own pass.
+ *  - parseTagValue/parseAttributeValue OFF — `<error_code>01000001</error_code>` must
+ *    stay a string; numeric coercion destroys leading zeros.
+ *  - attributes kept with the `@_` prefix (`{{r.body.tag.@_id}}`).
+ *  - repeated elements: XML cannot distinguish "one item" from "a list of one" — the
+ *    catalog declares `arrayPaths:` (dot jpaths INCLUDING the root element) and those
+ *    paths are ALWAYS arrays, so `[0]` access works for 1 and N occurrences alike
+ *    (an EMPTY parent has no child key at all — no array to index).
+ */
+function parseXmlBody(text: string, label: string, arrayPaths?: string[]): any | null {
+  let XMLParser: any;
+  try {
+    // Lazy require: generated projects created before this capability existed don't
+    // have the dep; they must fail with the install command, not MODULE_NOT_FOUND.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    ({ XMLParser } = require('fast-xml-parser'));
+  } catch {
+    throw new Error(`API Driver: ${label} — the response is XML but "fast-xml-parser" is not installed in this project. Run: npm install --save-dev fast-xml-parser`);
+  }
+  const arraySet = new Set(arrayPaths || []);
+  const parser = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: '@_',
+    processEntities: false,
+    htmlEntities: false,
+    parseTagValue: false,
+    parseAttributeValue: false,
+    trimValues: true,
+    isArray: (_name: string, jpath: string) => arraySet.has(jpath),
+  });
+  try {
+    return decodeXmlEntitiesDeep(parser.parse(text));
+  } catch {
+    return null;
+  }
+}
+
+/** Decode the five predefined XML entities in every string leaf (`&amp;` last, so a
+ *  literal `&amp;lt;` decodes to `&lt;` and not further). */
+function decodeXmlEntitiesDeep(value: any): any {
+  if (typeof value === 'string') {
+    return value
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"')
+      .replace(/&apos;/g, "'")
+      .replace(/&amp;/g, '&');
+  }
+  if (Array.isArray(value)) return value.map(decodeXmlEntitiesDeep);
+  if (value !== null && typeof value === 'object') {
+    const out: Record<string, any> = {};
+    for (const [k, v] of Object.entries(value)) out[k] = decodeXmlEntitiesDeep(v);
+    return out;
+  }
+  return value;
+}
 /** Delete any case-insensitive variant of a header (HTTP header names are case-insensitive, but a
  *  plain object keys on exact case — so a datasource `Content-Type` and our `content-type` would
  *  both be sent). Call before setting, or to let fetch own the header (multipart boundary). */
@@ -94,7 +212,11 @@ function loadStorageStateCookieHeader(storageStatePath: string, url: string): st
   const targetIsSecure = target.protocol === 'https:';
   const matches = cookies.filter((c) => {
     const domain = (c.domain || '').replace(/^\./, '');
-    const domainOk = !domain || target.hostname === domain || target.hostname.endsWith(`.${domain}`);
+    // A cookie with NO domain must match nothing, not everything — Playwright
+    // always records a domain, so a domainless entry only comes from a hand-
+    // edited state file, and treating it as a wildcard would attach the session
+    // cookie to any origin a response-bound absolute URL points at.
+    const domainOk = !!domain && (target.hostname === domain || target.hostname.endsWith(`.${domain}`));
     const pathOk = target.pathname.startsWith(c.path || '/');
     const notExpired = c.expires === undefined || c.expires < 0 || c.expires > nowSec;
     // A Secure cookie must never leave over plaintext. Playwright's own cookie jar enforces this,
@@ -201,22 +323,72 @@ class ApiClient {
    */
   async call(
     label: string,
-    req: { method: string; path: string; body?: unknown; encoding?: 'json' | 'form' | 'multipart'; files?: Record<string, FileSpec | FileSpec[]>; bodyFile?: FileSpec; headers?: Record<string, string>; timeout?: number; datasource?: string },
+    req: { method: string; path: string; body?: unknown; encoding?: 'json' | 'form' | 'multipart' | 'xml'; files?: Record<string, FileSpec | FileSpec[]>; bodyFile?: FileSpec; headers?: Record<string, string>; timeout?: number; datasource?: string; arrayPaths?: string[] },
     params: Record<string, any> = {},
     opts: { storageState?: string } = {},
   ): Promise<{ status: number; ok: boolean; body: any; headers: Record<string, string> }> {
     const { conf } = this.cfg(req.datasource);
     const base = (conf.base_url || conf.baseUrl || '').replace(/\/$/, '');
     if (!base) throw new Error(`API Driver: ${label} — datasource has no base_url (set it in .env.qa).`);
-    const urlPath = substitute(req.path, params);   // path params (:id) bind at runtime
 
-    const headers: Record<string, string> = { ...(conf.headers || {}) };
+    // Whole-token path (`path: ":url"`): bind RAW and use an absolute http(s)
+    // value directly — an export/download link returned by a prior response
+    // (often on another origin, e.g. blob storage). substitute() would percent-
+    // encode the whole URL into `https%3A%2F%2F…` and joinApiUrl would glue it
+    // onto base_url. Raw binding also keeps presigned query escapes (%2F)
+    // untouched; new URL() is used for VALIDATION only (a response value can be
+    // anything — file:/data: schemes are refused, never fetched).
+    let fullUrl: string;
+    let absolute = false;
+    const wholeToken = req.path.match(/^:([A-Za-z_][A-Za-z0-9_]*)$/);
+    if (wholeToken) {
+      // The bound value MUST be an absolute http(s) URL. Anything else — empty
+      // string (a broken export returning {"url":""}), a relative path, or a
+      // data:/mailto:/file: form — is refused loudly: falling through to the
+      // legacy base_url join would silently GET the API root and let the
+      // scenario false-pass on exactly the failure it exists to catch. (A
+      // whole-token path was never valid before this feature, so there is no
+      // legacy behavior to preserve.)
+      const wholeVal = String(params[wholeToken[1]] ?? '');
+      let parsed: URL | null = null;
+      if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(wholeVal)) {
+        try { parsed = new URL(wholeVal); } catch { parsed = null; }
+      }
+      if (!parsed || (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')) {
+        throw new Error(`API Driver: ${label} — :${wholeToken[1]} must be an absolute http(s) URL (the value is bound from a live response); got: ${JSON.stringify(wholeVal)}`);
+      }
+      if (parsed.username || parsed.password) {
+        throw new Error(`API Driver: ${label} — :${wholeToken[1]} must not carry credentials (user:pass@host): fetch refuses such URLs.`);
+      }
+      // Raw string, not parsed.toString(): URL normalization could rewrite the
+      // presigned query escapes (%2F) the storage host signed.
+      fullUrl = wholeVal;
+      absolute = true;
+    } else if (/^https?:\/\//i.test(req.path)) {
+      // Literal absolute catalog path — its :params (if any) bind with the normal encoding.
+      fullUrl = substitute(req.path, params);
+      absolute = true;
+    } else {
+      fullUrl = joinApiUrl(base, substitute(req.path, params));   // path params (:id) bind at runtime
+    }
+
+    // Cross-origin absolute URL: the datasource's own headers must NOT travel to
+    // another origin — auth tokens, cookies and tenant keys live in conf.headers
+    // with no metadata separating them from benign defaults, so ALL of them stay
+    // home; only headers declared on the entry itself are sent. An unparseable
+    // base counts as a different origin (fail closed).
+    const sameOrigin = !absolute || (() => {
+      try { return new URL(fullUrl).origin === new URL(base).origin; } catch { return false; }
+    })();
+    const headers: Record<string, string> = sameOrigin ? { ...(conf.headers || {}) } : {};
     // catalog headers; :param tokens bind at runtime — raw (no URL-encoding, unlike the path)
     for (const [k, v] of Object.entries(req.headers || {}))
       headers[k] = substituteRaw(String(v), params);
     // Body: substitute `:param` into the body template (object values), then encode per `encoding`.
+    // An XML body is a raw STRING template and binds by param-name WHITELIST below —
+    // the generic whole-value substitution here must not touch it.
     let body: any;
-    if (req.body !== undefined && req.body !== null) {
+    if (req.body !== undefined && req.body !== null && req.encoding !== 'xml') {
       body = JSON.parse(JSON.stringify(req.body).replace(/":([A-Za-z_][A-Za-z0-9_]*)"/g, (_m, p) => JSON.stringify(params[p] ?? null)));
     }
     // Map the wire format to a fetch request body (#345): json → JSON string (application/json,
@@ -244,6 +416,17 @@ class ApiClient {
       // drop any datasource default Content-Type so it doesn't conflict with / duplicate it.
       deleteHeader(headers, 'content-type');
       fetchBody = buildMultipart(req.files, body, params, label);
+    } else if (req.encoding === 'xml' && req.body !== undefined && req.body !== null) {
+      // XML body: the catalog carries a raw string template (any shape — attributes,
+      // namespaces, CDATA, nesting). :params bind by WHITELIST of the passed param
+      // names, never by a generic `:word` scan — that scan would mangle namespace
+      // prefixes (soapenv:Envelope, xsi:type) into bound values. A BODYLESS xml
+      // entry is fine — a GET whose xml RESPONSE needs arrayPaths carries no body.
+      if (typeof req.body !== 'string') {
+        throw new Error(`API Driver: ${label} — encoding: xml requires body: to be a string template (a YAML block scalar holding the raw XML).`);
+      }
+      fetchBody = bindXmlParams(req.body, params);
+      if (!hasHeader(headers, 'content-type')) headers['content-type'] = 'application/xml';
     } else if (body !== undefined) {
       const enc = req.encoding ?? 'json';
       if (enc === 'form') {
@@ -266,9 +449,6 @@ class ApiClient {
       throw new Error(`API Driver: ${label} — a ${req.method.toUpperCase()} request cannot carry a body. Remove body:/files:/bodyFile: from the catalog entry, or change its method to POST/PUT/PATCH.`);
     }
 
-    // Full URL (not a baseURL-relative path) so a base path component like /api/v3 is preserved.
-    const fullUrl = joinApiUrl(base, urlPath);
-
     // @hybrid: `storageState` is the @auth role's saved session (Playwright's `context.storageState()`
     // JSON) — reuse its cookies (scoped to `fullUrl`'s domain/path) so the request shares the
     // browser's authenticated session without a browser/Playwright context.
@@ -292,9 +472,32 @@ class ApiClient {
         ...(fetchBody !== undefined ? { body: fetchBody } : {}),
         signal: controller.signal,
       });
-      const text = await res.text();
+      // Read bytes, not res.text(): the fetch spec hard-decodes text() as UTF-8, so a
+      // Shift_JIS/ISO-8859-1 XML response (common from OTA backends) would mojibake
+      // silently. XML-ish responses decode by Content-Type charset, then the XML
+      // declaration's encoding, then UTF-8; everything else keeps the UTF-8 decode
+      // res.text() always performed.
+      const bytes = Buffer.from(await res.arrayBuffer());
+      const contentType = res.headers.get('content-type') || '';
+      // XML detection: an explicit xml Content-Type (text/xml, application/xml,
+      // application/soap+xml — never text/html), else — only when the CT is absent or
+      // octet-stream — a sniff REQUIRING the `<?xml` declaration. Never sniff on a bare
+      // `<`: the parser does not validate, so an HTML 502 page would come back as a
+      // junk object instead of the raw string an author can at least read.
+      const ctIsXml = /xml/i.test(contentType) && !/html/i.test(contentType);
+      const maySniff = !contentType || /octet-stream/i.test(contentType);
+      // Non-XML branch uses TextDecoder, NOT Buffer.toString: the fetch spec's
+      // "UTF-8 decode" (what res.text() did) STRIPS a leading BOM, and a BOM'd
+      // JSON response must keep parsing as an object exactly as before.
+      const text = ctIsXml || maySniff ? decodeXmlAwareText(bytes, contentType) : new TextDecoder('utf-8').decode(bytes);
+      const isXml = (ctIsXml || (maySniff && /^\uFEFF?\s*<\?xml/.test(text))) && text.length > 0;
       let parsed: any = text;
-      try { parsed = text ? JSON.parse(text) : null; } catch { /* non-JSON → keep text */ }
+      if (isXml) {
+        const xml = parseXmlBody(text, label, req.arrayPaths);
+        parsed = xml !== null ? xml : text; // real parse failure → keep the raw string
+      } else {
+        try { parsed = text ? JSON.parse(text) : null; } catch { /* non-JSON → keep text */ }
+      }
       return { status: res.status, ok: res.ok, body: parsed, headers: Object.fromEntries(res.headers.entries()) };
     } finally {
       clearTimeout(timer);
@@ -310,7 +513,7 @@ class ApiClient {
    */
   async callN(
     label: string,
-    req: { method: string; path: string; body?: unknown; encoding?: 'json' | 'form' | 'multipart'; files?: Record<string, FileSpec | FileSpec[]>; bodyFile?: FileSpec; headers?: Record<string, string>; timeout?: number; datasource?: string },
+    req: { method: string; path: string; body?: unknown; encoding?: 'json' | 'form' | 'multipart' | 'xml'; files?: Record<string, FileSpec | FileSpec[]>; bodyFile?: FileSpec; headers?: Record<string, string>; timeout?: number; datasource?: string; arrayPaths?: string[] },
     params: Record<string, any> = {},
     n = 1,
     opts: { storageState?: string } = {},

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');

package/src/orchestrator/templates/specs-regex-escape.ts

@@ -0,0 +1,16 @@
+/* eslint-disable */
+/**
+ * Sungen regex-escape helper — auto-generated into specs/regex-escape.ts. DO NOT EDIT.
+ *
+ * Test-data values are LITERAL TEXT. When a generated assertion needs an anchored
+ * match (`filter({ hasText: /^…$/ })`), the runtime value is interpolated into a
+ * `new RegExp(...)` — so a value containing `( [ $ . * +` would either throw a
+ * SyntaxError or silently match the wrong element unless it is escaped HERE, at
+ * runtime, where the real value is finally known. Template-time escaping cannot do
+ * this: at generate time the value is still a placeholder marker.
+ */
+
+/** Escape a runtime string so RegExp treats every character literally. */
+export function escapeRegExp(text: string): string {
+  return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/orchestrator/templates/specs-test-data.ts

@@ -50,16 +50,42 @@ export class TestDataLoader {
     if (value === undefined || value === null) {
       throw new Error(`Test data key not found: ${key}`);
     }
-    // A projected array (e.g. `{{q.rows[*].name}}`) serializes as a JSON list so the full
-    // ordered set is preserved for the assert-compare — String([...]) would flatten it to a
-    // lossy comma-join that can't be distinguished from a scalar containing commas.
-    const result = Array.isArray(value)
-      ? this.interpolate(JSON.stringify(value))
+    // A projected array (e.g. `{{q.rows[*].name}}`) and a PLAIN object (an API response
+    // body) serialize as JSON text — String([...]) flattens to a lossy comma-join and
+    // String({}) is "[object Object]", both un-assertable. Embedded `{{ref}}`s interpolate
+    // INSIDE the value before stringify, so a ref carrying quotes/backslashes can never
+    // corrupt the serialized JSON (the old order substituted raw text into JSON text).
+    // Only PLAIN objects take this path: Date/Buffer/ObjectId values bound by @query from
+    // a real driver keep their String()/toString() output — JSON.stringify would wrap a
+    // Date in quotes and flip every assertion that already compares its string form.
+    const result = isJsonContainer(value)
+      ? JSON.stringify(this.interpolateDeep(value))
       : this.interpolate(String(value));
     assertNoUnresolvedEnvRef(key, result);
     return result;
   }
 
+  /**
+   * Interpolate `{{ref}}`s in every string leaf AND key of a JSON container,
+   * recursively (matching the old whole-JSON-text pass). Non-plain nested
+   * objects are passed through untouched — JSON.stringify serializes them via
+   * toJSON. A truly cyclic object throws a RangeError; every current bind
+   * source (JSON.parse output, DB rows, YAML after load-time resolution) is
+   * acyclic. Built with Object.fromEntries, which DEFINES data properties — a
+   * body field literally named "__proto__" survives instead of silently
+   * rewiring the result's prototype to external input.
+   */
+  private interpolateDeep(value: any): any {
+    if (typeof value === 'string') return this.interpolate(value);
+    if (Array.isArray(value)) return value.map((v) => this.interpolateDeep(v));
+    if (isPlainObject(value)) {
+      return Object.fromEntries(
+        Object.entries(value).map(([k, v]) => [this.interpolate(k), this.interpolateDeep(v)])
+      );
+    }
+    return value;
+  }
+
   /**
    * Resolve a key to its RAW, uncoerced value (array/object/number kept as-is) — for binding
    * DB query / API request params, where type-strict sinks (MySQL numeric columns, MongoDB,
@@ -68,7 +94,8 @@ export class TestDataLoader {
    * as get()), so an override like `token={{login.body.token}}` or `id={{prefix}}-001` still
    * interpolates — only the final scalar/array/object type is preserved uncoerced. Arrays and
    * objects are returned as-is; refs embedded inside their elements are not interpolated (unlike
-   * get()'s JSON-text pass), since raw() callers bind structured values directly, not text.
+   * get(), which interpolates every string leaf of a plain container before serializing), since
+   * raw() callers bind structured values directly, not text.
    * Throws on missing, mirroring get()'s guard.
    */
   raw(key: string): any {
@@ -202,6 +229,26 @@ export class TestDataLoader {
   }
 }
 
+/**
+ * A value get() must serialize as JSON: an array, or a PLAIN object (literal or
+ * null-prototype). Class instances at the TOP level (Date, Buffer, ObjectId…,
+ * and driver row wrappers like mysql2's RowDataPacket) are NOT containers —
+ * they keep the String()/toString() path their existing assertions rely on;
+ * nested inside a plain container they serialize through JSON.stringify/toJSON.
+ */
+function isJsonContainer(value: any): boolean {
+  return Array.isArray(value) || isPlainObject(value);
+}
+
+// Prototype check only — a `value.constructor === Object` probe is defeated by
+// a body FIELD literally named "constructor" (JSON.parse gives it as an own
+// property), which would silently fall back to "[object Object]" again.
+function isPlainObject(value: any): boolean {
+  if (value === null || typeof value !== 'object') return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
 function loadYamlSync(filePath: string): Record<string, any> | null {
   if (!fs.existsSync(filePath)) return null;
   const content = fs.readFileSync(filePath, 'utf-8');