Repository navigation
docs: document the racket value model, in-process backend testing, and macos native-ui orchestration (#325) - #326
Merged
Conversation
…d macos native-ui orchestration Findings from the clean-room taskboard journey (#314): a context-free agent reached a green packaged acceptance from documented inputs alone but had to black-box-probe or invent five things. This ships each one as documented truth instead of per-agent improvisation. - protocol.md: the Racket-side authoring model - define-record/define-enum generate constructors named after the type, record-ref/enum-case are the accessors, (void) is the only Optional null, and record values are tied to the declaring module instance. - product-acceptance.md: a validated in-process backend recipe using the public rivet/protocol frames over pipes with serve, including the hello-before-first-frame and state-event-before-response orderings. - native-ui-testing.md: the macOS launch orchestration (packaged bundle, disposable data root, pid handoff, exit polling, restart leg) and the real keyboard path (focus assertion + CGEvent typing). - macos-ax.swift: focus/typeText/postKey/closeWindowOrderly helpers in the reference driver so keyboard scenarios copy over (type-checked). - getting-started (en/zh): snake_case native identifier rule and the build-before-native-UI ordering. The in-process recipe and the state-event ordering were executed before being documented; the driver type-checks.
This was referenced Oct 25, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes #325. The clean-room taskboard journey under #314 (context-free agent, documented inputs only, green packaged acceptance on macOS) surfaced five high-impact documentation gaps; this PR converts each into documented truth, verified before writing:
define-record/define-enumgenerate constructors named after the type;record-ref/enum-caseare the accessors;(void)is the only Optional null ('()/#frejected — the encoding is type-directed); record values are tied to the declaring module instance (fresh-namespace tests must takerecord-reffrom the same namespace).serveover pipes with the publicrivet/protocolframes — no hand-written codec needed (the journey hand-wrote one only because this recipe did not exist). Documents the hello-before-first-frame ordering and that a State mutation emits the$stateevent before the response frame. The exact sketch in the doc was executed against a real backend before being committed.focus(kAXFocusedAttribute assertion),typeText(CGEvent unicode events),postKey(Return 36 / Escape 53),closeWindowOrderly— added tomacos-ax.swiftso the documented "copy the driver" path covers keyboard scenarios.created-at-ms→created_at_ms) and the build-before-native-UI ordering.Validation
define-state/define-rpc, hello asserted,$state-then-response ordering asserted, orderly shutdown) before being documented.swiftc -typecheck rivet/tests/native-ui/macos-ax.swiftgreen.raco test rivet/tests/documentation.rkt: 731 passed (doc map/links).raco test rivet/ rivet-cli/: all green (the live DMG suite passes standalone; it skips only when the Finder-automation probe times out).Scope
Docs and the reference test driver only — no product-facing code changes. Per #314's slice order, the fixes should be re-validated by repeating a journey slice against the updated docs.