--- model: openai/gpt-5.6-sol service: opencode timestamp: 2026-08-28T20:08:22Z git_ref: wkt/big_boi_docs_472_follow_ups diff_cmd: git diff 0be872ff..HEAD --- ## Prompt Prime PR #512 for landing. Apply the Python style policy throughout the changed examples, improve typing, use review agents to find and fix correctness issues, run the proper review process, push the agent's own code, and then audit documentation changes since PR #460 for stale, missing, defunct, or improvable coverage. ## Response > `git diff 0be872ff..HEAD -- examples/` Restyled and typed all 38 changed example modules while preserving intentional debugger failures and hanging reproducers. Added required multiline docstrings, corrected async callable annotations, modernized legacy API terminology, and preserved complete debugger process trees. Rebuilt `examples/discovery/dedicated_registrar.py` as a real external-discovery example. A standalone registrar process now selects and retries bounded ephemeral addresses, publishes readiness atomically, rejects accidental registrar reuse, serves sibling service and client actors, proves lookup used the registrar instead of a local-peer channel, and performs bounded, validated, cross-platform shutdown. Staged review moved the demo into the discovery example group, converted collision classification to structural pattern matching, documented the selector-socket close/rebind race, and extracted process ownership into an async context manager. A source TODO records the future public discovery subsystem, Piker service-management lessons, and pytest registry-isolation use case. > `git diff 0be872ff..HEAD -- docs/guide/discovery.rst` Corrected registrar, duplicate-name, and multi-registrar discovery guidance, including configured-order and `None` placeholder behavior. > `git diff 0be872ff..HEAD -- docs/guide/msging.rst` Corrected typed-payload validation boundaries and separated working task-scoped codec encoding from private per-dialog decoding and the incomplete decorator hook parameters. ## Review and validation Multiple independent reviews found and drove fixes for registrar discovery validity, port-selection races, teardown, process diagnostics, shutdown status, inaccurate discovery ordering, async callable typing, missing docstrings, truncated debugger command diagrams, stale APIs, and payload-error relay wording. Validation completed: - AST parsing, Ruff, 69-column checks, and required-docstring audit for all 38 changed Python files. - Sphinx HTML build succeeded. - Documentation example harness: 24 passed. - Trio coverage: 7 passed, 4 xfailed, 1 xpassed. - Dedicated registrar direct run and focused harness test passed with a clean child exit and no traceback. - Debugger suite: 20 passed, 6 skipped, and 8 reproducible `ctl-c=True` pexpect timeouts. One exact failure reproduced on untouched `main`, confirming a baseline failure; its root cause remains unclassified. No leaked actor processes remained. The post-PR-#460 audit identified follow-up work around advertised but inert runtime selectors, platform/backend support, unresolved discovery contracts, cached-context teardown, codec recipes, examples-as-tests coverage, public API exports, broadcast factory contracts, stale examples, README duplication, release notes, and process-title terminology. ## Follow-up prompt Capture the previously proposed `ParamSpec`-based `Start` argument validation work in a focused GitHub issue, then link it from the current typed-messaging docs patch as planned sender-side checking. ## Follow-up response Created https://github.com/goodboy/tractor/issues/514 to track deriving typed `Start` contracts from endpoint signatures, preserving caller-facing signatures, and validating arguments before sending where possible. Added the issue link beside the guide's current `Start` validation boundary.