test: property-based testing foundation (fast-check) over parse/print and geometry kernels

[devin-ai-integration]

Summary

Adds fast-check (dev dep) and turns five hand-pinned example clusters into general properties over the pure parse/print and geometry kernels. Generators live in one shared module behind the test-utils barrel, so a new hazard (another quote shape, a new gesture kind, another .ad command) is added once and inherited by every property instead of becoming another pinned case.

src/__tests__/test-utils/property-arbitraries.ts (exported via the barrel):

• selectorChainArb — selector chains whose text values include the grammar's hazards: ", ', it's, say "hi", backslash runs, a || b, key=value, embedded newline/tab, unicode, empty and whitespace-only — plus formatSelectorChainExpression, the canonical printer the round-trip needs (the parser has no production serializer).
• refArb / formatRef — @eN~sM, with and without @ and generation.
• viewportRectArb + COMPACT_VIEWPORTS (320×568, 375×667) and gestureInViewportArb, keyed by GESTURE_KINDS as a Record<GestureKind, Arbitrary<GesturePayload>> so a new gesture kind fails to typecheck rather than silently escaping the geometry property.
• replayScriptArb — .ad scripts over the command vocabulary, with comments, blank lines, flags and quoting hazards.
• rawSnapshotNodesArb — bounded snapshot trees for the diff properties.

Properties, each in its owning module's test file:

1. src/selectors/parse.test.ts (new) — parsing a printed chain yields the terms it was printed from, and parse -> print -> parse is a fixed point.
2. snapshot-ref-grammar.test.ts — splitRefGenerationSuffix and the ~sM join are inverses for every ref.
3. gesture-plan-viewport.test.ts — for every gesture kind × viewport × platform, buildGesturePlan either keeps every synthesized point in bounds or refuses with a structured INVALID_ARGS; never a silently out-of-bounds path. The two compact-iPhone viewports are kept as examples of that property (they are COMPACT_VIEWPORTS, ready for smoke-ios-simulator-coverage.test.ts on the unmerged agent/ios-simulator-e2e-coverage branch, which does not exist on main).
4. replay/__tests__/script.test.ts — re-serializing a parsed script is a fixed point, and command + positionals survive the rewrite (flag defaults are legitimately dropped, so the canonical form is the invariant, not the first parse).
5. daemon/__tests__/snapshot-diff.test.ts — diff(a, a) yields no added/removed line, and summary is always exactly a count of the rendered lines: additions + unchanged === countSnapshotComparableLines(current) and removals + unchanged === …(previous).

docs/agents/testing.md gains a "Properties over examples" section: pure parser or geometry change → extend a property, not another example, plus where the generators live, the bounded PROPERTY_RUNS / PROPERTY_RUNS_SMALL budget, and how to replay a shrunk counterexample via fc.assert(..., { seed, path }).

Closes #1413.

Validation

11 files touched, scope unchanged from the issue (no CLI-arg or exec-layer fuzzing). Local gates green: format:check, lint, typecheck, check:layering, check:fallow --base origin/main, check:mcp-metadata. All property tests run in unit-core and land well under the slow-test budget (each property file ≤ 45ms); no new entry in the slow-test report.

Two check:affected steps fail identically on origin/main in this environment and are unrelated to this change — verified on a clean origin/main worktree:

• build: tsdown cannot load tsdown.config.ts (Failed to import module "unrun", an optional peer that is not in the lockfile).
• scripts/__tests__/help-conformance-topic-coverage.test.ts: uncovered help topic ios-system-ui.

Everything else in pnpm test:unit passes (4557 tests). No device-facing behavior changes: this PR adds tests, generators and docs only, so no simulator/device evidence applies.

Link to Devin session: https://app.devin.ai/sessions/fdcb06373f8f4e2fb9558de6f69c2601
Requested by: @thymikee

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-27 15:15 UTC

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.87 MB	1.87 MB	0 B
JS gzip	598.4 kB	598.4 kB	0 B
npm tarball	713.2 kB	713.2 kB	+11 B
npm unpacked	2.49 MB	2.49 MB	+28 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	29.7 ms	29.5 ms	-0.2 ms
CLI --help	61.6 ms	60.7 ms	-0.9 ms

Top changed chunks: no changes in the largest emitted chunks.

[thymikee]

Blocking architecture gap: the new property domains duplicate their owners instead of deriving from them. property-arbitraries.ts manually lists selector keys even though parse.ts exports SELECTOR_KEY_NAMES, and REPLAY_SCRIPT_LINE_ARBS uses satisfies Record<string, …>, which accepts any subset. New selector keys or replay command forms can silently escape the suite; specialized production branches such as open, runtime, and record are already absent. Derive selector domains from the parser-owned export and classify the replay grammar from PUBLIC_COMMANDS or an owning replay registry with an exhaustive assertion plus valid templates/explicit waivers. The gesture/platform derivations, bounded runs, real pure boundaries, and lack of test-only seams are otherwise sound. Exact-head Coverage is also red on the inherited ios-system-ui benchmark gap, so this head is not ready.

[devin-ai-integration]

the new property domains duplicate their owners instead of deriving from them

Fixed in the latest push, and the head is rebased onto latest main (the ios-system-ui benchmark gap is fixed there, so Coverage is no longer red for that reason).

• Selectors: keys come from the parser-owned SELECTOR_KEY_NAMES; the generator only classifies the value shape per key via SELECTOR_KEY_VALUE_KINDS satisfies Record<SelectorKey, 'text' | 'boolean'>, so a new SelectorKey fails to typecheck here. A runtime guard also names the resolving file if a key in SELECTOR_KEY_NAMES has no shape.
• Replay grammar: REPLAY_SCRIPT_LINE_ARBS is replaced by REPLAY_SCRIPT_LINE_PLANS satisfies Record<ReplayCommandName, ReplayLinePlan>, where ReplayCommandName is the union of PUBLIC_COMMANDS and INTERNAL_COMMANDS (runtime is internal, so public alone would have missed it) and each entry is either a valid line template or an explicit { waived: reason }. The specialized branches you named are now templated — open (positional + --relaunch + runtime hints), runtime (--platform), record (--fps, --hide-touches) — alongside snapshot/screenshot/click/press/longpress/wait/fill/type/get/swipe/gesture. Waived commands carry the reason "generic line shape, covered by the wait/longpress templates", i.e. they have no branch in script.ts/script-formatting.ts; a command that grows one has to move to a template. The line set is materialized by iterating the runtime catalogs, so a command present at runtime but absent from the plan throws a guard message naming REPLAY_SCRIPT_LINE_PLANS and its file.

Local after rebase: format:check, lint, typecheck, check:layering, check:fallow --base origin/main clean; pnpm test:unit 4563 passed / 0 failed, no new slow-test entries.

[thymikee]

Re-reviewed at 7a8fccf0607580891ae0e48ec347566465381c0f: the prior domain-ownership gap is fixed. Selector keys derive from SELECTOR_KEY_NAMES with exhaustive value-shape classification, and replay plans are exhaustive over the derived public/internal command catalogs. The PR is mergeable (CLEAN) and all 25 reported checks are green. Ready to merge.