Base seam: fix 6 real defects, and rebuild the base suite as a reproducible 34-feature catalogue

[xywang68]

---

Follow-up: the log now reflects the test it ran

Auditing the suite's own narration (not just its assertions) found the cmd: line reporting intent rather than execution. Six fixes:

#	Defect found in the log	Fix
1	Not runnable. json-on-error printed findTargetImage DISPLAY=:77 --imagePath=Screen — env assignment in argument position, so pasting it ran a successful screen read instead of the error path. natives/pointer printed parenthesised prose.	Every seam call goes through target(), which prints the exact quoted argv and the exit status of the call it just made. Host commands go through probe(), printed then run from the same string.
2	Under-reported. image-similarity, text-hint, ocr-similarity, flash, latency ran 2–11 invocations but printed one command — the rejection half of the floor tests was invisible.	target() is the single funnel, so one line per invocation is structural, not discipline.
3	False coverage claim. ocr-similarity was named for the OCR floor but asserted neither direction of it.	See below — the truth is that the floor is not applied, and the feature now says so with a known-gap: line.
4	Names over-claimed. provenance said "records os + java + node" but grepped only built=; wm used pgrep -f openbox, which matches its own command line, so it could pass with no WM; json-on-error's "payload is a JSON array" grepped [, which the JVM's own [DEBUG STARTUP] lines satisfied vacuously.	provenance asserts all five keys; wm checks the openbox PID we started plus pgrep -x; json-on-error parses the payload and asserts a status.
5	No evidence on success. 80-odd ✓ lines were names, so a green run could not be audited.	✓ <what> = <observed> on every passing check.
6	Order dependence. Features relied on the root window surviving from a previous feature.	The fixture is re-shown before each invocation; timing features opt out with NOSHOW=1 and say so, since the re-show lands inside the measured window (it inflated latency from ~1130 ms to 1675 ms).

The finding behind #3

While verifying the floor I measured "0.99 rejects" — then found it was an artifact of a WM-less harness where the fixture had vanished (final screen read: empty). Under the suite's own setup (openbox running) fixtures are durable, and the truth is the opposite: --ocrSimilarity is accepted but never applied. With the text on screen, 0.99 still returns a match. The image floor is applied (image-similarity asserts accept and reject). Asserting an OCR rejection would have passed only when the screen happened to be blank — a false green — so it is not asserted; the report prints a known-gap: line instead, and the README lists it.

Two bugs I introduced and fixed

• target()'s log line went to stdout, so inside $( ) it was captured into the JSON variable and corrupted the payload (all three checks went red). Log lines now go to stderr; stdout carries only the payload. That's the same class as the JVM-log interleaving fixed earlier in this branch.
• The fixture re-show inflated the latency measurement; excluded via NOSHOW=1.

The flash threshold was also recalibrated to the real separation — 15–284 ms while the flash was broken, 780–1010 ms when applied — with an upper bound added to catch a runaway flash. It had failed at 783 < 800 on a loaded host.

Verified

make base-test                 -> feature conformance: 92 passed, 0 failed, ALL FEATURES OK
make one FEATURE=flash         -> 2 passed   (delta 903 ms, bounded)
make one FEATURE=ocr-similarity-> 2 passed, with the known-gap line printed

Also in this push: the banner reports the image's own build stamp from /etc/autobdd-versions instead of a <ver> placeholder, and the catalogue table is the single source of every feature description (so --list, suite headers and run lines cannot drift).

---

Follow-up: the discovery surface (first, non-breaking step of the command-surface plan)

The rename to autobdd find-target --match-image/--match-text is not in this PR — deliberately. Renaming flags on a frozen contract touches 38 call sites in 10 files (incl. framework/libs/screen_session.js) and needs an alias + translation layer plus a release running both surfaces, so it is sequenced behind this.

What this PR now adds is the part that makes any name discoverable. Measured before the change:

findTargetImage --help     -> exit 0 after a 3079 ms whole-screen OCR SCAN
findTargetImage --version  -> exit 0, silently ignored
usage strings in the binary -> 0

--help is the canonical "what does this do?" move for a human and for an agent; it silently did work and reported success. Now:

Arg	Behaviour	Cost
--help, -h	flows, output shape, exit codes, every flag + default, and the known gaps	37 ms, never touches the screen
--list	the supported flows as runnable examples	~37 ms
--version	seam, image build stamp (from /etc/autobdd-versions), Oculix, Node	~37 ms
bad value	findTargetImage: --imageAction expects one of … on stderr, exit 2	—

Previously --imageAction=bogus fell through the action switch and returned a normal-looking result with no action taken — indistinguishable from success to an automated caller. Unknown arguments still warn and are ignored, so the additive-argument guarantee is unchanged.

The flag catalogue is a single array, so --help, --list and unknown-flag detection cannot drift.

Verified

make base-test   -> feature conformance: 107 passed, 0 failed, ALL FEATURES OK   (38 features)
make one FEATURE=I
   help         ✓ exits 0, prints flows/flags, no result payload, no engine banner, <= 500 ms
   version      ✓ names the seam, reports the build stamp
   list         ✓ lists the read flow and the acting flow
   usage-error  ✓ exits 2, names the flag, lists accepted values

Still to come (separate PRs)

1. autobdd dispatcher + read-text, engines out of PATH, findTargetImage alias with a stderr-only deprecation notice, legacy-flag translation layer, CI dual-surface run.
2. --match-image / --match-text become canonical (--min-score, --wait 5s, --limit, --click/--hover, --box), the 10 files migrate, and the suite's run lines become autobdd find-target --match-image … for free — because the printed string and the executed argv are the same string.

---

Follow-up: the front door (autobdd find-target / autobdd read-text) — c60370e

Second step of the command-surface plan. Flags are deliberately not renamed yet — that touches 38 call sites in 10 files and needs the legacy translation layer, so it stays the next step. This commit adds the verb layer and the alias.

Path	Role
/usr/local/bin/autobdd	the interface
/usr/local/bin/findTargetImage	deprecated alias — stderr notice only, then defers to the front door
/usr/local/libexec/autobdd/{find-target,read-text}	verb-named entry points, not on PATH (argv[0] dispatch)
/opt/autobdd/seam/src/findTargetImage.js	the single engine

autobdd find-target --imagePath=logo.png --imageAction=click
autobdd read-text

read-text is find-target's whole-screen mode given its own name, so reading the screen is no longer spelled as finding a target called Screen. The alias defers to the front door, so argument translation added later applies to it without a second implementation — and its notice goes to stderr only, because stdout is parsed as target_result: <json>.

Behaviour change: the target is now required

Omitting it used to default to --imagePath=Screen, so a mistyped flag silently ran a whole-screen scan (~3 s) and looked like a successful call — and it made find-target and read-text behaviourally identical. CONTRACT.md §1 always said the target was required; this enforces it (exit 2, with a hint pointing at read-text).

Verified on both surfaces

AutoBDD_Ver=test make base-test                                  -> 124 passed, 0 failed
TARGET_BIN=/usr/local/libexec/autobdd/find-target make base-test -> 124 passed, 0 failed

The suite defaults to the alias, so a green matrix doubles as proof the alias is transparent. 43 features now (group J: front door + alias).

Two of my own test bugs, caught by the run lines

• front-door-read-text was pointed at the find-target entry point and passed anyway, because the engine's default was already Screen — a false green. It now exercises read-text and also asserts that find-target with no target exits 2.
• The alias-agreement check called the alias on both sides.

One observation, recorded not hidden

A single rc=139 (SIGSEGV during native teardown) on a successful front-door call while the host had stacked containers; not reproducible in 23 clean runs since. The front-door feature now asserts exit 0 so it stays visible rather than silent.

Next

--match-image / --match-text become canonical (--min-score, --wait 5s, --limit, --click/--hover, --box), the 10 files migrate, the deprecated alias gains the legacy-flag translation, and the suite's run: lines become autobdd find-target --match-image … for free — the printed string and the executed argv are the same string.

---

Follow-up: the canonical argument vocabulary — 6df4e1e

The v1 flags described how we look and disagreed with themselves: --imageSimilarity and --ocrSimilarity were one concept under two names, and --imageWaitTime was seconds while --ocrWaitTime was milliseconds.

v2 describes what you want, once:

v1	v2
--imagePath / --ocrPath	--match-image / --match-text — the two ways to name the target
--imageSimilarity / --ocrSimilarity	--min-score
--maxSim / --ocrMaxSim	--max-score
--imageWaitTime (s) / --ocrWaitTime (ms)	--wait=5s / --wait=800ms
--imageMaxCount / --ocrMaxCount	--limit
--imageAction=hoverClick	--hover --click (composable flags)
--ocrDetail, --ocrPSM, --ocrOEM	--box, --psm, --oem

Presence defines the mode, so there are no modes to remember: --match-image alone, --match-text alone, or both (a picture gated on its region's text). --match-text is literal and case-insensitive by default with --match-regex opting in, so a phrase containing : or ( cannot silently change meaning — v1 --textHint was regex and keeps that behaviour through the legacy path.

Every v1 name still works, translated in the engine and warned about on stderr only. docs/CONTRACT.md gains §2 (canonical) and §2b (deprecation table). A legacy-flags feature asserts the v1 names still match and still click, that stdout carries exactly one result line and no deprecation text, and that the notice lands on stderr.

The suite migrated, so the run lines now read what they run:

run: findTargetImage --match-image=/tmp/…/hello.png --click --flash=0s
✓ reports clicked == center = 900
✓ the pointer is really at the reported centre = 900,1100

Verified: 44 features, 130 checks, 0 failed.

Also: usage-error now exercises a canonical flag (--min-score=abc), and the whole log moved to stderr so a run: line can never print after the check it produced.

Correction to my earlier claim

rc=139 (SIGSEGV during native teardown) on a successful front-door call has now been seen twice, so my earlier "one-off" characterisation was wrong. Output is correct both times — the crash is after the result is written. Not reproducible in 23 clean runs; the front-door feature asserts exit 0 so it stays visible rather than silent. Mitigation candidate for a follow-up: skip the JVM/native teardown on the success path.

---

Follow-up: the front door is now the default surface — b1b88f1

The suite drives /usr/local/libexec/autobdd/find-target by default and prints the surface it used:

════════════════════════════════════════════════════════════════════════════
 AutoBDD base image — feature conformance
   image   : xyteam/autobdd-base  (built 2026-09-22T19:02:59Z)
   display : :1  1920x1200x24
   surface : /usr/local/libexec/autobdd/find-target
   catalogue: 44 features — see base-test/features.sh
════════════════════════════════════════════════════════════════════════════

TARGET_BIN=findTargetImage runs the same matrix through the deprecated alias (the CI dual-surface check). The alias stays covered inside the default run too: group J's alias-transparent and legacy-flags both invoke findTargetImage explicitly, the latter proving the v1 argument names still match and still click.

Guidance bugs found while doing this

• The banner and footer printed a command that cannot work. AutoBDD_Ver=test make base-test runs the script on the host, where none of the image's tooling exists. Both now print make docker-run jobs="base-test".
• The suite now detects the host case and exits 2 with a one-line pointer, instead of failing once per assertion with convert: command not found noise — which is how a first-time user loses an afternoon.
• test-projects/autobdd-base-test/README.md was stale: it still documented findTargetImage, --textHint, --maxSim and --imageAction=click; described four sections of checks where there are now ten groups; and omitted features.sh/one.sh from the layout. Rewritten to cover the default surface and how to switch it, the four env vars that matter, the run-one-at-a-time caveat (with the measured latency inflation), the group table, how to read a run, and the COPY seam/ cache trap (step 12).
• Root README's feature-conformance section and sample output now match the real banner.

Verified

AutoBDD_Ver=test make docker-run jobs="base-test"
  -> surface : /usr/local/libexec/autobdd/find-target
  -> feature conformance: 130 passed, 0 failed      ALL FEATURES OK

bash base-test/run.sh          # on the host
  -> exit 2, one-line pointer, no Xvfb started

---

Follow-up: documentation audit, and the last v1 consumer — bd12649

I grepped every doc for v1 flag names, the old command name and stale counts rather than assuming the earlier passes had caught everything. They hadn't:

README.md — the seam section still documented the v1 arguments as current (--ocrPath, --ocrSimilarity, --ocrMaxSim, --ocrWaitTime, --ocrMaxCount, --ocrAction, --ocrDetail, --ocrPSM, --ocrOEM) with findTargetImage examples; the illustrative run output showed --imagePath=…; the feature table and honesty notes named --textHint, --maxSim, --imageAction, --imageMaxCount, --ocrSimilarity; and the intro claimed the interface was findTargetImage. Now: canonical table + examples with docs/CONTRACT.md as the source of truth (so the two cannot drift again), real run lines in the sample, canonical names throughout, and the duplicated Basic usage block removed.

docs/CONTRACT.md — the v1 argument table was left dangling under a "Raw arguments" heading, reading as if current. Retitled Raw argument reference (v1 — deprecated) with a pointer to the §2b mapping; the --imageAction/--ocrDetail prose and the center row now use canonical names.

framework/libs/screen_session.js — the last v1 emitter. It still built findTargetImage --imagePath=… --imageAction=…, so after the rename every framework call would have warned on stderr seven times. It now emits the front door with canonical flags. Subtlety worth flagging: textHint was a regex and --match-text is literal by default, so --match-regex is passed to preserve the existing semantics exactly — documented in the code.

autobdd find-target --match-image=/tmp/…/hello.png --min-score=0.8 --max-score=1 \
  --match-text="HELLO" --match-regex --wait=5s --hover --click --limit=1
→ {"name":"hello.png","score":1,"clicked":"object"}      stderr: (empty)

Verified: the generated framework command matches and clicks with empty stderr; base suite 131 passed, 0 failed. The framework e2e suite itself was not run — it needs the L2 image with Chrome — so that consumer is verified at the command-string level plus the engine's v2/legacy coverage.

No v1 flag name remains in any documentation except the deprecation tables (§2b) and the intentional historical notes in CHANGELOG.md.

Also in this commit: the help text's known-gap line and the suite's user-facing known-gap line now say --box (what a reader would type), and the help feature asserts both that the canonical flag is listed and that the deprecated v1 names are, so the deprecation table cannot silently vanish.