simframe 0.8.0 → 0.10.0

package/scripts/bench-hpi.mjs

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+// The agent half of the Human Parity Index.
+//
+// Runs every flow in the suite N times, exactly as an agent would run it, and
+// reduces the flow records to an HPI report. The human half is recorded once
+// by a person (`simframe baseline record`) and committed; this side is
+// re-measured on every run, which is what makes HPI a trend rather than a
+// claim.
+//
+// Two rules this file follows, both learned in this repo:
+//
+//   - Nothing is verified through a pipe. `node script.mjs | tail -3` exits
+//     with tail's status, and this project has already shipped a check that
+//     could not fail because of it. Every gate here is an exit code.
+//   - A missing human baseline is reported, never defaulted. HPI_time with no
+//     denominator is null; it is not 1.0, and it is not "parity".
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runScript } from '../src/actions.js';
+import * as api from '../src/index.js';
+import * as baseline from '../src/baseline.js';
+import * as metrics from '../src/metrics.js';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const arg = (name, fallback = null) => {
+  const hit = process.argv.find((a) => a.startsWith(`--${name}=`));
+  return hit ? hit.slice(name.length + 3) : fallback;
+};
+const has = (name) => process.argv.includes(`--${name}`);
+
+const device = arg('device');
+const runs = Math.max(1, Number(arg('runs', '3')));
+const only = arg('flow');
+const out = arg('out');
+const baselineFile = arg('baseline', path.join(ROOT, 'docs', 'research', 'hpi-baseline.json'));
+const gate = has('gate');
+/**
+ * How many times to measure the whole suite.
+ *
+ * Three when gating, because one measurement is mostly noise: identical code
+ * measured three times the same afternoon gave HPI_time 0.475, 0.413 and
+ * 0.371. The gate reads the median of the passes, which is what lets the time
+ * band stay as tight as 25% instead of being widened to cover a single run's
+ * spread.
+ */
+const passes = Math.max(1, Number(arg('passes', gate ? '3' : '1')));
+/**
+ * A pause between runs, and it is not superstition.
+ *
+ * Measured on one 8-run loop: 15.2 s, 15.2 s, then 6.9 s failing, then 25.7 s,
+ * 25.7 s, then the display wedged — and it wedged again within a couple of
+ * minutes of the same load after a device restart. Relaunching an app as fast
+ * as a script can is not what this suite is trying to measure, and a simulator
+ * asked to do it degrades and then stops rendering. The suite paces itself so
+ * the numbers describe simframe rather than the simulator's tolerance for
+ * being hammered.
+ */
+const cooldownMs = Math.max(0, Number(arg('cooldown', '1500')));
+
+const suite = baseline.loadSuite(arg('suite', baseline.SUITE_FILE)).filter((f) => !only || f.name === only);
+if (!suite.length) {
+  console.error(`no flows to run${only ? ` matching "${only}"` : ''}`);
+  process.exit(2);
+}
+
+const { device: dev } = await api.ensureDaemon(device);
+console.log(`device: ${dev.name} (${dev.udid})`);
+console.log(`suite: ${suite.map((f) => f.name).join(', ')} × ${runs} run(s) × ${passes} pass(es)\n`);
+
+const ids = new Set();
+let hardFailures = 0;
+/**
+ * A wedged capture loop is not a slow flow, and every run after it is doomed.
+ *
+ * Measured four times in one session: the display surface stops being readable
+ * mid-suite, the daemon re-resolves the display port and still gets nothing,
+ * and only restarting the device cures it. Grinding through the remaining runs
+ * produced three identical "could not run at all" lines and an HPI computed
+ * from whatever happened to finish first — a number with a hole in it, which
+ * is worse than no number.
+ */
+const WEDGED = /display surface could not be read|did not produce a frame/;
+/**
+ * The host could not do the thing, as distinct from simframe doing it slowly.
+ *
+ * A hosted runner takes 47-55 s to fail `simctl launch com.apple.Preferences`
+ * and then fails it again, three runs in a row — the same class of fault this
+ * repo already records for `simctl openurl`, which returns "Operation timed
+ * out" on a loaded runner. Six of those is nine minutes of CI spent measuring
+ * the runner's patience, and the resulting HPI describes nothing.
+ */
+const ENVIRONMENT = /could not launch|Command failed: xcrun simctl (launch|terminate)|Operation timed out|timed out/i;
+/** Two environmental failures of the same flow is the environment, not a flake. */
+const ENV_GIVE_UP = 2;
+let abort = null;
+const envFailures = new Map();
+
+const passSets = [];
+outer: for (let pass = 1; pass <= passes; pass += 1) {
+  const thisPass = new Set();
+  passSets.push(thisPass);
+  if (passes > 1) console.log(`pass ${pass}/${passes}`);
+  for (const flow of suite) {
+    for (let run = 1; run <= runs; run += 1) {
+    // The same start state the human baseline was recorded from: app not
+    // running, on the home screen. Not part of the timed flow, and
+    // deliberately not expressed as flow steps — see baseline.resetFor.
+    // The reset and its settle live inside the same guard as the run.
+    //
+    // They did not, and a device whose display had failed threw out of
+    // `waitFor` — outside the try — killing the process with a stack trace
+    // instead of the one classification this script exists to make. An
+    // environmental failure has to be classified wherever it happens, not
+    // only where it was convenient to catch.
+    let res;
+    try {
+      const reset = await baseline.resetFor(dev.udid, flow);
+      if (reset.failures.length) console.log(`  (reset: ${reset.failures.join('; ')})`);
+      await api.waitFor(dev.udid, { mode: 'stable', stableMs: 400, timeoutMs: 4000 });
+      res = await runScript(dev.udid, {
+        steps: flow.steps,
+        flowName: flow.name,
+        minSteps: flow.minSteps ?? null,
+      });
+    } catch (err) {
+      // A flow that could not start at all is not a slow flow. It has no
+      // record, so it cannot be averaged into anything; it is reported and
+      // counted.
+      hardFailures += 1;
+      console.log(`FAIL ${flow.name} run ${run}: ${err.message}`);
+      if (WEDGED.test(err.message)) {
+        abort = { kind: 'capture is wedged', message: err.message };
+        break outer;
+      }
+      if (ENVIRONMENT.test(err.message)) {
+        const n = (envFailures.get(flow.name) ?? 0) + 1;
+        envFailures.set(flow.name, n);
+        if (n >= ENV_GIVE_UP) {
+          abort = { kind: `the host cannot run "${flow.name}"`, message: err.message.split('\n')[0] };
+          break outer;
+        }
+      }
+      continue;
+    }
+    ids.add(res.flowId);
+    thisPass.add(res.flowId);
+    const verdicts = res.results.map((r) => r.verification?.verdict).filter(Boolean);
+    console.log(
+      `${res.ok ? 'ok  ' : 'FAIL'} ${flow.name.padEnd(24)} run ${run}/${runs}  ` +
+        `${String(res.totalMs).padStart(6)}ms  ${res.ranSteps}/${res.totalSteps} steps  ` +
+        `${verdicts.filter((v) => v !== 'ok').length ? `verdicts: ${verdicts.join(',')}` : 'all ok'}`,
+    );
+    if (!res.ok) console.log(`     ${res.results.filter((r) => !r.ok).map((r) => r.error).join('; ')}`);
+    if (cooldownMs) await new Promise((r) => setTimeout(r, cooldownMs));
+    }
+  }
+}
+
+// This process's runs only. The log is append-only and holds every earlier
+// measurement, which is what makes it a trend — but a CI number computed over
+// somebody's local runs from last week is not this commit's number.
+const flows = metrics.readFlows(dev.udid).filter((f) => ids.has(f.flow_id));
+const humans = baseline.readBaselines();
+// Each pass measured on its own, so the gate can take a median over them
+// rather than trusting one. Accuracy is pooled over every run instead: one
+// wrong action in thirty is a wrong action, and a median would hide it.
+const allFlows = metrics.readFlows(dev.udid);
+const passReports = passSets
+  .map((set) => metrics.hpi({ flows: allFlows.filter((f) => set.has(f.flow_id)), baselines: humans }))
+  .filter((r) => r.overall.runs > 0);
+const passTimes = passReports.map((r) => r.overall.hpi_time).filter((t) => Number.isFinite(t));
+
+const report = {
+  ...metrics.hpi({ flows, baselines: humans }),
+  measured_at: new Date().toISOString(),
+  device: { udid: dev.udid, name: dev.name, runtime: dev.runtime },
+  runs_per_flow: runs,
+  passes,
+  pass_hpi_time: passTimes,
+  hard_failures: hardFailures,
+  human_baselines: Object.fromEntries(
+    Object.entries(humans).map(([k, v]) => [k, { runs: v.runs, p50: v.wall_time_ms?.p50 ?? null }]),
+  ),
+};
+
+console.log('\nflow                      runs  agent p50   human p50   HPI_time  step_ratio');
+for (const f of report.flows) {
+  console.log(
+    `${f.flow.padEnd(24)} ${String(f.runs).padStart(5)}  ${`${f.agent_ms.p50}ms`.padStart(9)}   ` +
+      `${(f.human_median_ms ? `${f.human_median_ms}ms` : '—').padStart(9)}   ` +
+      `${String(f.hpi_time ?? '—').padStart(8)}  ${String(f.step_ratio ?? '—').padStart(10)}`,
+  );
+}
+report.overall.hpi_time_median_of_passes = passTimes.length ? Number(metrics.median(passTimes).toFixed(3)) : null;
+const o = report.overall;
+console.log(`\nHPI_accuracy ${o.hpi_accuracy}   HPI_time ${o.hpi_time ?? '—'}   HPI ${o.hpi ?? '—'}   step_ratio ${o.step_ratio ?? '—'}`);
+if (passTimes.length > 1) {
+  console.log(`HPI_time per pass: ${passTimes.join(', ')} — median ${o.hpi_time_median_of_passes} (what the gate reads)`);
+}
+if (o.hpi_time == null) {
+  console.log(`no human baseline for any measured flow — HPI_time and HPI are null, not 1.0.`);
+  console.log(`record one: simframe baseline record <flow> --device=${dev.udid} --runs=5`);
+}
+
+if (out) {
+  fs.writeFileSync(out, `${JSON.stringify(report, null, 2)}\n`);
+  console.log(`wrote ${out}`);
+}
+
+const escalations = metrics.breakdown(metrics.readEscalations(dev.udid));
+console.log(`\nescalations in this device's log: ${escalations.total} (${Object.entries(escalations.by_reason).filter(([, n]) => n).map(([r, n]) => `${r} ${n}`).join(', ') || 'none'})`);
+
+if (abort) {
+  console.error(`\n${abort.kind}: ${abort.message}`);
+  console.error('No comparable HPI was measured — what is above is a partial suite and');
+  console.error('must not be adopted as a baseline or read as a regression.');
+  if (/wedged/.test(abort.kind)) {
+    console.error('Only restarting the device is known to cure a wedge:');
+    console.error(`  xcrun simctl shutdown ${dev.udid} && xcrun simctl boot ${dev.udid}`);
+  }
+  // 2, not 1. "I could not measure" and "it got worse" are different answers,
+  // and a job that reports them with the same exit code teaches people to
+  // ignore both. The workflow treats 2 as a loud warning and 1 as a failure.
+  process.exit(2);
+}
+
+if (hardFailures) {
+  console.error(`\n${hardFailures} flow run(s) could not run at all.`);
+  process.exit(1);
+}
+
+if (!gate) process.exit(0);
+
+// ------------------------------------------------------------------ the gate
+const committed = fs.existsSync(baselineFile) ? JSON.parse(fs.readFileSync(baselineFile, 'utf8')) : null;
+if (!committed) {
+  // Loudly inactive rather than quietly passing. A gate with nothing to
+  // compare against cannot detect a regression, and saying "ok" here is how a
+  // CI job comes to mean nothing.
+  console.log(`\nGATE INACTIVE — no committed baseline at ${path.relative(ROOT, baselineFile)}.`);
+  console.log('Commit this run as the baseline to arm it.');
+  process.exit(0);
+}
+
+const base = committed.overall ?? {};
+const failures = metrics.gateAgainst(committed, report);
+
+console.log(`\ngate vs ${path.relative(ROOT, baselineFile)} (measured ${committed.measured_at ?? '?'})`);
+console.log(`  HPI_accuracy ${base.hpi_accuracy ?? '—'} -> ${o.hpi_accuracy ?? '—'}`);
+console.log(`  HPI_time     ${metrics.gateTime(base) ?? '—'} -> ${metrics.gateTime(o) ?? '—'}`);
+console.log(`  band         ${metrics.TIME_REGRESSION * 100}% (median of ${passTimes.length || 1} pass(es))`);
+for (const f of failures) console.log(`FAIL ${f}`);
+process.exit(failures.length ? 1 : 0);

package/scripts/check-package.mjs

@@ -75,6 +75,13 @@ function requiredFiles() {
     throw new Error('no skill found under skills/ — has the layout moved? This check would silently pass.');
   }
 
+  // The flow suite. `simframe baseline` and `simframe hpi` read it at
+  // runtime, so an absent one is a command that only fails once installed.
+  for (const f of walk(path.join(ROOT, 'flows'), (p) => p.endsWith('.json'))) required.add(rel(f));
+  if (!walk(path.join(ROOT, 'flows'), (p) => p.endsWith('.json')).length) {
+    throw new Error('no flow suite found under flows/ — has the layout moved? This check would silently pass.');
+  }
+
   // Anything package.json points at to run.
   const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
   for (const target of Object.values(pkg.bin ?? {})) required.add(target.replace(/^\.\//, ''));

package/scripts/check-private.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// No third-party app identifiers in this repository. Ever, from anyone.
+//
+// simframe is a general-purpose tool: you install it and Claude Code drives
+// *your* app on the simulator. It has no relationship with any particular app,
+// so no particular app's bundle id belongs in it — not in the source, not in
+// the docs, and not in a secret either. A denylist of specific strings would
+// assume there is one app to protect, which is the wrong shape for this.
+//
+// So the rule is a pattern, not a list, and it needs no configuration at all.
+// Anything shaped like a reverse-DNS bundle id is flagged unless it is one of:
+//
+//   * a platform's own                 com.apple.*, com.android.*, com.google.*
+//   * a documentation placeholder      com.example.*, com.acme.*, com.mycompany.*
+//   * this project's own identifiers
+//
+// That works on a fresh clone, on a fork, and in a pull request from a stranger,
+// which a secret does not. An optional `.private-strings` file (gitignored) or
+// $SIMFRAME_PRIVATE_STRINGS still adds extra patterns for anyone who wants them,
+// but nothing depends on either existing.
+//
+// How this got written: a 282-line field-notes file about a real third-party app
+// was committed here by `git add -A` and pushed, an hour after the first version
+// of this script was written to prevent exactly that. It could not fire, because
+// it was waiting for a denylist nobody had supplied. A guard with a
+// precondition is a guard that is off.
+//
+// Nothing here ever prints a match. It prints the file and the line number, so
+// the output of a failed run is safe to paste into an issue, a CI log, or a
+// conversation with an agent — which is where the last one would have gone.
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const LIST_FILE = path.join(ROOT, '.private-strings');
+
+/**
+ * Bundle-id-shaped strings, and the ones that are fine.
+ *
+ * The first segment is restricted to real reverse-DNS prefixes, which is what
+ * keeps ordinary property chains out: `res.state.seq`, `registry.paths.dir` and
+ * `import.meta.url` all look exactly like bundle ids until you require the head
+ * to be a TLD.
+ */
+const BUNDLE = /\b(?:com|io|org|net|dev|co|app|me|xyz|uk|de|fr|jp|nl|se|ca|au)\.[A-Za-z][A-Za-z0-9_-]{1,30}(?:\.[A-Za-z][A-Za-z0-9_-]{0,30}){1,3}\b/g;
+
+/** Platform-owned, placeholder, or ours. Anything else is somebody's app. */
+export const ALLOWED = [
+  /^com\.apple\./i,
+  /^com\.android\./i,
+  /^com\.google\./i,
+  /^org\.swift\./i,
+  /^org\.json\./i,
+  /^com\.facebook\./i,     // idb, a reference implementation named in the docs
+  /^com\.example\./i,
+  /^com\.acme\./i,
+  /^com\.mycompany\./i,
+  /^com\.yourcompany\./i,
+  /^io\.github\./i,
+];
+
+export function isAllowedIdentifier(id) {
+  return ALLOWED.some((re) => re.test(id));
+}
+
+/** Extra patterns, for anyone who wants them. Nothing depends on this existing. */
+export function patternsFrom({ env, file } = {}) {
+  const raw = [
+    ...String(env ?? '').split(/[\n,]/),
+    ...String(file ?? '').split(/\n/),
+  ];
+  return [...new Set(
+    raw
+      .map((s) => s.trim())
+      .filter((s) => s && !s.startsWith('#'))
+      // One character would match everything, which is a check that only ever
+      // fails and therefore only ever gets disabled.
+      .filter((s) => s.length >= 3)
+      .map((s) => s.toLowerCase()),
+  )];
+}
+
+/** Which lines of `text` are a problem. Line numbers only, never matches. */
+export function offendingLines(text, patterns = []) {
+  const hits = [];
+  const lines = String(text).split('\n');
+  for (let i = 0; i < lines.length; i += 1) {
+    const lower = lines[i].toLowerCase();
+    const why = [];
+    const extra = patterns.filter((p) => lower.includes(p)).length;
+    if (extra) why.push(`${extra} denied pattern(s)`);
+    const ids = (lines[i].match(BUNDLE) ?? []).filter((id) => !isAllowedIdentifier(id));
+    // Reported as a count and a shape, never as the identifier: knowing which
+    // app leaked is worth less to a bug report than not restating it.
+    if (ids.length) why.push(`${ids.length} third-party bundle id(s)`);
+    if (why.length) hits.push({ line: i + 1, why: why.join(', ') });
+  }
+  return hits;
+}
+
+function trackedFiles() {
+  return execFileSync('git', ['ls-files', '-z'], { cwd: ROOT, encoding: 'utf8' })
+    .split('\0')
+    .filter(Boolean);
+}
+
+function main() {
+  const patterns = patternsFrom({
+    env: process.env.SIMFRAME_PRIVATE_STRINGS,
+    file: fs.existsSync(LIST_FILE) ? fs.readFileSync(LIST_FILE, 'utf8') : '',
+  });
+  const files = trackedFiles();
+  let failed = 0;
+  for (const rel of files) {
+    const full = path.join(ROOT, rel);
+    let text;
+    try {
+      const stat = fs.statSync(full);
+      if (!stat.isFile() || stat.size > 4_000_000) continue;
+      text = fs.readFileSync(full, 'utf8');
+    } catch {
+      continue;
+    }
+    // A NUL byte means this is not text, and a substring hit in it is noise.
+    if (text.includes('\0')) continue;
+    for (const hit of offendingLines(text, patterns)) {
+      console.error(`check-private: ${rel}:${hit.line} — ${hit.why}`);
+      failed += 1;
+    }
+  }
+  console.log(`check-private: ${files.length} tracked file(s); no third-party bundle ids`
+    + (patterns.length ? `, plus ${patterns.length} local pattern(s)` : '')
+    + ` — ${failed} line(s) flagged`);
+  if (failed) {
+    console.error('check-private: nothing above prints the match itself. '
+      + 'A third-party app identifier does not belong in a general-purpose tool.');
+    process.exitCode = 1;
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) main();

package/scripts/eval-perception.mjs

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+// The perception eval harness. Deferred since Phase 5; four things wait on it.
+//
+// What it is, and the design decision behind it. The obvious harness replays
+// stored frames through the perception path and diffs the element lists, which
+// is what Phase 13 step 5 describes. That harness cannot exist: the element
+// list is the accessibility tree fused with OCR, the tree is not in the frame,
+// and OCR runs in the daemon against a live framebuffer. A frame on disk is
+// half the input.
+//
+// So the split is different and, for what actually needs gating, better. The
+// machine records the *input* — the fused element list for a screen, exactly as
+// perception produced it. A person authors the *expected output*. Everything
+// downstream of the element list is a pure function, so the check runs offline,
+// deterministically, with no simulator and no daemon:
+//
+//   resolution   matching.resolve(targets, query)  — which element a query picks
+//   identity     fingerprint.tokens(targets)       — which screen this is
+//   change       analyze.signatureDiff(a, b)       — whether a frame moved
+//
+// Those three are precisely the thresholds every blocked item wants to change.
+// What it does *not* cover is whether perception found the elements at all,
+// which is inherently live and stays with eval-fingerprint.mjs and the
+// integration job. Said plainly here rather than implied, because a harness
+// that is trusted for more than it measures is worse than no harness.
+//
+// Two rules from this repo:
+//   - The gate is an exit code. Nothing is verified through a pipe: this
+//     project has already shipped a check that could not fail because
+//     `node script.mjs | tail` reports tail's status.
+//   - A fixture with no authored expectations is reported as unauthored, never
+//     counted as a pass. An empty test suite is green.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as fingerprint from '../src/fingerprint.js';
+import * as matching from '../src/matching.js';
+import * as analyze from '../src/analyze.js';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const DIR = path.join(ROOT, 'test', 'perception', 'screens');
+const arg = (n, d = null) => {
+  const hit = process.argv.find((a) => a.startsWith(`--${n}=`));
+  return hit ? hit.slice(n.length + 3) : d;
+};
+const has = (n) => process.argv.includes(`--${n}`);
+
+export function fixtures(dir = DIR, only = null) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((f) => f.endsWith('.json'))
+    .filter((f) => (only ? f.includes(only) : true))
+    .sort()
+    .map((f) => ({ file: f, ...JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8')) }));
+}
+
+/**
+ * Check one screen's authored expectations against the pure layers.
+ *
+ * Returns findings rather than printing, so the same function backs the CLI and
+ * the unit tests — and so a finding can be counted without being formatted.
+ */
+export function checkScreen(fx) {
+  const findings = [];
+  const screen = fx.points ?? null;
+  const targets = fx.targets ?? [];
+  const expect = fx.expect ?? {};
+  const authored = (expect.resolutions?.length ?? 0)
+    + (expect.ambiguous?.length ?? 0)
+    + (expect.none?.length ?? 0)
+    + (fx.frame_pairs?.length ?? 0)
+    + (expect.identity ? 1 : 0);
+
+  for (const r of expect.resolutions ?? []) {
+    const out = matching.resolve(targets, r.query, { screen });
+    if (out.status !== 'ok') {
+      findings.push({
+        kind: 'resolution',
+        query: r.query,
+        want: r.label,
+        got: out.status === 'ambiguous'
+          ? `ambiguous between ${out.alternatives.map((a) => a.label).join(', ')}`
+          : 'nothing resolved',
+      });
+      continue;
+    }
+    const got = out.target.label ?? '(icon-only)';
+    // Compared on the label because that is what the author can see and mean.
+    // Coordinates would make a fixture break every time a row moved a point.
+    if (got !== r.label) {
+      findings.push({ kind: 'resolution', query: r.query, want: r.label, got: `"${got}" at ${out.target.x},${out.target.y}` });
+    }
+  }
+
+  // The other half of the contract, and the half with the wrong-tap risk in it:
+  // "when two things answer equally well it says so rather than guessing".
+  for (const q of expect.ambiguous ?? []) {
+    const out = matching.resolve(targets, typeof q === 'string' ? q : q.query, { screen });
+    if (out.status !== 'ambiguous') {
+      findings.push({
+        kind: 'should-ask',
+        query: typeof q === 'string' ? q : q.query,
+        want: 'ambiguous',
+        got: out.status === 'ok' ? `picked "${out.target.label}" at score ${out.score}` : 'nothing resolved',
+      });
+    }
+  }
+
+  for (const q of expect.none ?? []) {
+    const out = matching.resolve(targets, q, { screen });
+    if (out.status !== 'none') {
+      findings.push({
+        kind: 'should-find-nothing',
+        query: q,
+        want: 'none',
+        got: out.status === 'ok' ? `picked "${out.target.label}"` : 'ambiguous',
+      });
+    }
+  }
+
+  // Identity drift. A token-rule change that silently alters a screen's
+  // structural hash discards every stored map and graph for it, and the failure
+  // is invisible — an old hash is a well-formed hash that matches nothing.
+  if (expect.identity && screen) {
+    const now = fingerprint.fingerprint(targets, screen);
+    if (now.hash !== expect.identity.hash) {
+      const similarity = fingerprint.similarity(now.tokens, expect.identity.tokens ?? []);
+      findings.push({
+        kind: 'identity',
+        query: '(structural hash)',
+        want: `${expect.identity.hash?.slice(0, 12)} (${expect.identity.tokens?.length ?? 0} tokens)`,
+        got: `${now.hash?.slice(0, 12)} (${now.tokens.length} tokens), similarity ${similarity.toFixed(2)}`,
+      });
+    }
+  }
+
+  // Frame pairs, for the change detector. `changed: true` means an action that
+  // a person would call visible — a switch flipping, a radio dot moving.
+  for (const pair of fx.frame_pairs ?? []) {
+    const a = analyze.hexToSignature(pair.after);
+    const b = analyze.hexToSignature(pair.before);
+    // Two different questions about the same pair of frames: has the *screen*
+    // changed (the mean, which drives stillness) and has a *control* changed
+    // (the largest single region, which drives the verdict). A switch flip
+    // answers no to the first and yes to the second, which is the whole reason
+    // both exist.
+    const diff = pair.per_cell ? analyze.maxCellDelta(a, b) : analyze.signatureDiff(a, b);
+    const seen = diff > (pair.threshold ?? 0.004);
+    if (seen !== Boolean(pair.changed)) {
+      findings.push({
+        kind: 'change',
+        query: pair.note ?? '(frame pair)',
+        want: pair.changed ? 'a visible change' : 'no change',
+        got: `${pair.per_cell ? 'max cell' : 'mean'} ${diff.toFixed(5)} against a threshold of ${pair.threshold ?? 0.004}`,
+      });
+    }
+  }
+
+  return { authored, findings };
+}
+
+async function record() {
+  const api = await import('../src/index.js');
+  const device = arg('device');
+  const name = arg('name');
+  if (!name) throw new Error('--record needs --name=<app>/<screen>');
+  const id = await api.screenIdentity(device, { fresh: true, confirmNovel: false });
+  const entry = id.entry ?? {};
+  const out = {
+    app: name.split('/')[0],
+    screen: name.split('/').slice(1).join('/') || name,
+    note: arg('note') ?? null,
+    recorded_at: new Date().toISOString(),
+    points: id.points,
+    // The recorded input. Trimmed to what the pure layers read, so a fixture
+    // is reviewable by a person rather than a wall of machine state.
+    targets: (entry.targets ?? []).map((t) => ({
+      label: t.label ?? null,
+      value: t.value ?? null,
+      type: t.type ?? null,
+      x: t.x, y: t.y,
+      frame: t.frame ?? null,
+      region: t.region ?? null,
+      source: t.source ?? null,
+      aliases: t.aliases ?? undefined,
+      navSlot: t.navSlot ?? undefined,
+      enabled: t.enabled ?? undefined,
+      selected: t.selected ?? undefined,
+    })),
+    expect: {
+      identity: { hash: entry.structuralHash, tokens: entry.structuralTokens ?? [] },
+      // Authored by hand. The machine records what perception saw; a person
+      // says what it should mean. Deriving these from current behaviour would
+      // bake today's bugs in as the specification.
+      resolutions: [],
+      ambiguous: [],
+      none: [],
+    },
+  };
+  fs.mkdirSync(DIR, { recursive: true });
+  const file = path.join(DIR, `${name.replace(/\//g, '__')}.json`);
+  fs.writeFileSync(file, `${JSON.stringify(out, null, 2)}\n`);
+  console.log(`recorded ${out.targets.length} element(s) from ${name} -> ${path.relative(ROOT, file)}`);
+  console.log('  now author expect.resolutions / expect.ambiguous / expect.none by hand');
+}
+
+function check() {
+  const all = fixtures(DIR, arg('only'));
+  if (!all.length) {
+    console.error('check-perception: no fixtures. Record some with --record --name=<app>/<screen>');
+    process.exitCode = 1;
+    return;
+  }
+  let failed = 0;
+  let unauthored = 0;
+  let checks = 0;
+  const apps = new Set();
+  for (const fx of all) {
+    apps.add(fx.app);
+    const { authored, findings } = checkScreen(fx);
+    checks += authored;
+    if (!authored) {
+      unauthored += 1;
+      console.log(`  ??  ${fx.app}/${fx.screen}  recorded, no expectations authored`);
+      continue;
+    }
+    if (!findings.length) {
+      console.log(`  ok  ${fx.app}/${fx.screen}  ${authored} expectation(s)`);
+      continue;
+    }
+    failed += findings.length;
+    console.log(`FAIL  ${fx.app}/${fx.screen}`);
+    for (const f of findings) {
+      console.log(`        ${f.kind}: ${f.query}\n          want ${f.want}\n          got  ${f.got}`);
+    }
+  }
+  console.log(`\n${all.length} screen(s) across ${apps.size} app(s), ${checks} expectation(s), ${failed} failure(s)`
+    + (unauthored ? `, ${unauthored} unauthored` : ''));
+  // An unauthored fixture is not a pass. A suite that counts recordings as
+  // successes is a suite that goes green by adding files.
+  if (failed || unauthored) process.exitCode = 1;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  if (has('record')) await record();
+  else if (has('list')) for (const f of fixtures()) console.log(`${f.app}/${f.screen}  ${f.targets?.length ?? 0} elements`);
+  else check();
+}