From a95ca7577f21d511348672fa323ea874863d2213 Mon Sep 17 00:00:00 2001 From: goodboy Date: Sat, 29 Aug 2026 20:10:13 -0400 Subject: [PATCH] Record PR #512 prompt provenance Capture the human direction, generated changes, review findings and validation results for the docs-example landing pass. Point generated-code references at the complete commit range from the pre-remediation branch head. Prompt-IO: ai/prompt-io/opencode/20260828T200822Z_0be872ff_prompt_io.md (this patch was generated in some part by `opencode` using `gpt-5.6-sol` (`openai`)) --- .../20260828T200822Z_0be872ff_prompt_io.md | 62 +++++++++++++ ...20260828T200822Z_0be872ff_prompt_io.raw.md | 90 +++++++++++++++++++ 2 files changed, 152 insertions(+) create mode 100644 ai/prompt-io/opencode/20260828T200822Z_0be872ff_prompt_io.md create mode 100644 ai/prompt-io/opencode/20260828T200822Z_0be872ff_prompt_io.raw.md diff --git a/ai/prompt-io/opencode/20260828T200822Z_0be872ff_prompt_io.md b/ai/prompt-io/opencode/20260828T200822Z_0be872ff_prompt_io.md new file mode 100644 index 00000000..6304e7e8 --- /dev/null +++ b/ai/prompt-io/opencode/20260828T200822Z_0be872ff_prompt_io.md @@ -0,0 +1,62 @@ +--- +model: openai/gpt-5.6-sol +service: opencode +session: pr512-docs-review +timestamp: 2026-08-28T20:08:22Z +git_ref: wkt/big_boi_docs_472_follow_ups +scope: code +substantive: true +raw_file: 20260828T200822Z_0be872ff_prompt_io.raw.md +--- + +## Prompt + +Prime PR #512 for landing by applying the repository Python style and +typing policy across changed examples, reviewing and correcting the +result with delegated agents, validating it, and auditing documentation +changes since PR #460 for broader follow-up work. + +## Response summary + +Completed a branch-wide style, typing, and docstring pass over the +changed examples. Reworked the dedicated registrar example so it proves +external discovery, handles bind collisions, publishes readiness +atomically, and shuts down cleanly across platforms. Staged review moved +it under the discovery examples, introduced an async lifecycle manager, +and captured public-subsystem, Piker, and pytest follow-ups. Corrected +discovery and typed-messaging documentation after cross-checking runtime +behavior. +Created issue #514 for typed `Start` contracts and linked its planned +sender-side argument validation from the messaging guide. +Independent review passes were repeated until no actionable findings +remained. Static checks, Sphinx, runnable examples, Trio coverage, and +focused registrar checks passed; Ctrl-C debugger failures remain +unclassified after one case reproduced on untouched `main`. + +## Files changed + +- `examples/discovery/dedicated_registrar.py` - implement robust + standalone registrar discovery and teardown. +- `examples/**/*.py` - apply style, typing, docstring, and terminology + corrections to the 38 changed example modules. +- `docs/guide/discovery.rst` - document actual registrar and + multi-registrar behavior. +- `docs/guide/msging.rst` - document actual validation and codec-hook + boundaries. + +## Human edits + +The human selected PR #512, required the `/py-codestyle` policy and +typing improvements throughout the examples, required delegated review +agents to find additional fixes, authorized agents to own and push their +code through the proper review process, and requested a broad audit of +documentation changes since PR #460 rendered as an evolving Taken WIP. +The human then required the earlier `ParamSpec` proposal to be captured +as a dedicated GitHub issue and linked from the current docs patch. +The human also required the registrar demo to move under discovery, use +structural matching and an async context manager, explain socket ownership, +and preserve public API, Piker, and pytest-harness follow-ups. +The human also explicitly retracted messages intended for another +session; those messages did not direct the result. No direct manual +source edits were identified; the agent applied the human-directed +changes. diff --git a/ai/prompt-io/opencode/20260828T200822Z_0be872ff_prompt_io.raw.md b/ai/prompt-io/opencode/20260828T200822Z_0be872ff_prompt_io.raw.md new file mode 100644 index 00000000..554459f5 --- /dev/null +++ b/ai/prompt-io/opencode/20260828T200822Z_0be872ff_prompt_io.raw.md @@ -0,0 +1,90 @@ +--- +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.