docs: document the Racket-side value model and the backend/native-ui testing paths (taskboard journey findings) #325

Source

Clean-room taskboard journey under #314 (2026-10-25): a context-free agent implementing one keyboard/focus/draft/error-recovery scenario from documented inputs only reached a green packaged acceptance, but had to black-box-probe or invent the following. These gaps are the journey's primary output; the knowledge currently lives only in the journey project's comments, not upstream.

High impact

1. Record values on the Racket side are undocumented. The constructor is the type name itself ((Task id title ms)), field access is (record-ref t 'field) — the name record-ref appears in no docs/*.md (found via namespace enumeration); match on a record is a syntax error. Document the construction/access model next to the schema docs.
2. Optional null's Racket representation is undocumented. (void) is the only accepted null; '() and #f are rejected for Optional fields while being legal empty lists in (List T) contexts — the encoding is type-directed, which is nowhere stated. Without the experiment, a wrong representation surfaces only as a runtime Error frame at the RPC boundary.
3. No "how to test a backend" guide. product-acceptance.md requires contract suites over "product behavior, schema, golden output, and real storage", but nothing documents instantiating and driving a backend in-process: serve's signature, two return values, plain binary ports, hello timing. The journey hand-wrote an LE codec + pipe pair to build a real RVT1 loopback test — worth shipping as a documented recipe instead of per-agent improvisation.
4. No macOS launch orchestration for native-ui suites. native-ui-testing.md says "copy the driver, replace identifiers"; the Windows example is one pwsh -File line. Nothing covers: locating the packaged .app executable, passing --pid, injecting a disposable data root, awaiting orderly exit, and the restart leg. The journey's scripts/e2e/macos.sh is a working reference to draw from.
5. No keyboard-input reference for AX drivers. The scenario alphabet is type + Return + Esc, but macos-ax.swift only demonstrates AXPress. Document the supported injection paths (focus via kAXFocusedAttribute + CGEvent unicode/keycode events) and their reliability boundaries, or extend the reference driver.

Medium/low

6. Generated Swift naming rules (RPC → method, State getter/setter, Record fields stay snake_case, Optional → T?) are only inferable after a build; getting-started should state the build-before-native-UI ordering.
7. Persistence/data-directory guidance is absent (platform conventions, override hook for disposable acceptance roots). The journey invented TASKBOARD_DATA_DIR + atomic writes.
8. Record values cannot cross module instances (fresh-namespace "restart" tests hit a record-value? contract failure) — worth a sentence for test authors.
9. raco docs is empty for rivet itself although inspect's capability-sourcing lists it as the first discovery command.
10. Scaffold ships a GeneratedBackend.swift inconsistent with the scaffold's own host code until first build; a docs note would prevent first-read confusion.

Positive records (worked as documented)

Schema compatibility gate caught removals precisely; doctor/inspect/acceptance --json all matched their docs; evidence pre-clean + kind pinning worked; build errors pointed at exact Swift source lines; the reference driver skeleton (bounded waits, snapshot depth, orderly close) copied over cleanly.

Scope note

Fixing 1–5 is a docs/reference-driver change in this repository; it should be re-validated by repeating the journey slice after the docs land (see #314's slice order).