Skip to content

docs: correct worker-boundary claims and align style - #32

Merged
jmgilman merged 1 commit into
masterfrom
docs/post-refactor-review
Aug 25, 2026
Merged

jmgilman merged 1 commit into
masterfrom
docs/post-refactor-review

Conversation

@jmgilman

Copy link
Copy Markdown
Contributor

Summary

Independent three-axis review of all user-facing docs after the worker-isolation cutover (#27–#31), followed by the approved fix scope: all accuracy findings, all language-style findings, and low-cost Diátaxis fixes.

Accuracy (9 HIGH findings fixed)

  • Exposure claim (README, tutorial, public-api, security-model): "only the final value crosses the worker boundary" was false — native-call argument maps and validated native results cross the private worker protocol (limits.go:42-49). Docs now say only main's final converted value is exposed to the caller.
  • Elapsed budget (index, public-api, security-model): MaxExecutionTime covers slot wait, spawn, protocol exchange, Starlark execution, and parent dispatch; kill/reap OS overhead is outside the budget (limits.go:28-31). Removed "worker cleanup" from the covered phases.
  • Probe (public-api): the build probe cannot detect silent host work before ServeWorkerAndExit (builder.go:118-121); first-statement ordering is a host obligation.
  • MaxConcurrentExecutions (public-api): bounds spawn attempts and live workers, not live workers only.

Style (20 findings fixed)

  • Replaced ungrounded "production hosts normally supply…" (5 docs) with the direct only-when condition.
  • One primary action per procedural step; conditions before actions; literal identifiers as code; removed gloss and ambiguous pronouns.
  • Canonical terminology across all docs: worker process, native call, top-level source loading.

Diátaxis (approved subset)

  • index.md is now an orientation page routing to all six pages by reader need.
  • Tutorial: prerequisites section before the first dependent command.
  • Both how-to guides end with executable verification sections.
  • Explanation retitled "Understanding CodeMode's security model" (path unchanged).

Deliberately out of scope (maintainer decision): new pages, moving procedures out of reference pages, tutorial restructure/voice change, README/SECURITY shortening.

Validation

  • moon run docs:build (strict MkDocs) passes.
  • go test ./... -count=1 passes (compile-checked examples).
  • Functional verification: tutorial, Rego how-to, and disable-capabilities how-to executed end-to-end from the docs as written; every documented output line reproduced verbatim, including execute: permission denied and the search_api: [] / capability not found / invalid program block. The verification run surfaced and fixed four reproducibility defects in the Rego guide (variable shadowing compile error, unobservable denial text, const scope, missing go mod tidy).

Post-refactor docs review (session 008 worker cutover left stale claims):
- Fix the two systemic accuracy errors: only main's final value is
  exposed to the caller (native args/results do cross the private
  worker protocol), and MaxExecutionTime excludes kill/reap overhead.
- Fix probe detection and MaxConcurrentExecutions scope in the API
  reference to match builder.go and limits.go godoc.
- Standardize terminology: worker process, native call, top-level
  source loading.
- Replace ungrounded 'production hosts normally' claims with direct
  conditions; split multi-action steps; format literal identifiers.
- Rework index.md into a Diataxis orientation page; add tutorial
  prerequisites; retitle the security explanation; add functionally
  verified verification sections to both how-to guides.
@jmgilman
jmgilman merged commit 906541d into master Aug 25, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant