post-#472 docs follow ups

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.

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.

docs/guide/discovery.rst

@@ -30,9 +30,9 @@ the registry tracks the live tree as it grows and shrinks.
 
 .. note::
    Actor names are **not** enforced unique — the registry is keyed
-   by the full ``(name, uuid)`` pair. Name-based lookups simply
-   resolve to the *last* registered match, so if you boot five
-   actors all named ``'bob'``, you get the freshest ``'bob'`` B)
+   by the full ``(name, uuid)`` pair. A name lookup returns one
+   matching registration, but the API does not promise which match
+   wins. Use unique service names when selection matters.
 
 First boot: who's the registrar?
 --------------------------------
@@ -65,6 +65,43 @@ the one-and-only registrar; boot then fails loudly with a
 ``RuntimeError`` if some other process already bound the registry
 socket(s).
 
+A dedicated registrar
+---------------------
+That second rule — *"if a registrar answers, boot as a plain
+root"* — is all you need to run the registry as its own
+**standalone process**, decoupled from any app tree's root. In the
+daemon process, enter ``open_root_actor()`` with an explicit
+``registry_addrs`` and ``ensure_registry=True``; the latter makes
+startup fail instead of silently joining a registrar that won the
+address. Point each app tree at the address that daemon actually
+bound:
+
+.. literalinclude:: ../../examples/discovery/dedicated_registrar.py
+   :caption: examples/discovery/dedicated_registrar.py
+   :language: python
+
+The example's selector socket binds but deliberately never listens.
+It owns the kernel-selected local address only long enough to read it,
+then closes so Tractor's actual listener can bind the same address.
+This is not a socket transfer: the close/rebind handoff is non-atomic,
+so the example retries with a fresh candidate only when registrar
+startup reports that another process claimed the released address.
+Retries are bounded, and other startup failures remain visible. It
+publishes the selected address only after the actor context enters.
+It also performs the lookup inside a separate ``client`` actor. The
+service is its sibling, not its child, so the client has no spawn-time
+service channel to satisfy the local-peer fast path. The
+``query_actor()`` assertion verifies that a registrar portal handled
+the lookup before ``find_actor()`` makes the service RPC.
+
+This is the "registrar as a subsystem, not the app root actor"
+shape. Two caveats today (both tracked as #472 follow-ups):
+``enable_transports`` is single-proto per runtime, so a registrar
+can't yet serve multiple backends at once; and there's no way to
+spawn a registrar as a *sub*-actor of a shared tree (only as its
+own root), since ``start_actor()`` has no custom-``actor_cls``
+hook.
+
 Looking up actors
 -----------------
 
@@ -92,13 +129,22 @@ Knobs worth knowing:
 - ``registry_addrs=[...]``: query specific (possibly multiple,
   possibly remote) registrars instead of your tree's default,
 
-- ``only_first=False``: deliver a ``list[Portal]`` of *all*
-  matches found across the queried registrars instead of just the
-  first,
+- ``only_first=True``: after all configured registrars are queried
+  concurrently, yield the result in the first ``registry_addrs``
+  position. This is configured order, not first-reachable order, so
+  the result can be ``None`` even when a later registrar returned a
+  portal,
+
+- ``only_first=False``: when any query succeeds, yield an ordered
+  ``list[Portal | None]`` with one result per ``registry_addrs``
+  position; misses remain ``None`` placeholders. When every query
+  misses, yield ``None`` instead of a list. This does not enumerate
+  every duplicate name in one registrar,
 
-- ``raise_on_none=True``: raise a ``RuntimeError`` instead of
-  yielding ``None`` when no match is found — for when absence is
-  a hard error in your app.
+- ``raise_on_none=True``: raise a ``RuntimeError`` when every
+  registrar query returns ``None``. With ``only_first=True`` it does
+  not raise merely because the first ordered result is ``None`` when
+  a later result is a portal.
 
 ``wait_for_actor()``
 ********************
@@ -131,10 +177,11 @@ Yields a portal straight to the registrar actor itself — or a
 Fast paths and address preference
 ---------------------------------
 
-Before doing any RPC to the registrar, every lookup first scans
-the calling actor's *already-connected peers*: if you have a live
-channel to an actor named ``name`` you get a portal over it
-immediately, no registrar round-trip at all.
+Before doing any RPC to the registrar, ``query_actor()``,
+``wait_for_actor()``, and the default ``find_actor()`` lookup first
+scan the calling actor's *already-connected peers*. If the caller
+has a live channel to an actor named ``name``, it gets a portal over
+that channel immediately, with no registrar round-trip.
 
 When a registry entry holds *multiple* addresses (a multihomed
 actor) the "best" one is chosen by locality:
@@ -201,8 +248,8 @@ the existing registrar:
 
 Per the bootstrap rules above, if those addrs are absent this process
 becomes its own registrar root, so the same code works standalone and
-as a tree-joiner. An occupied address that does not complete a Tractor
-registrar handshake fails startup instead of being rebound.
+as a tree-joiner. An occupied address that does not complete a
+Tractor registrar handshake fails startup instead of being rebound.
 
 "Arbiter"? A legacy naming note
 -------------------------------
@@ -226,10 +273,11 @@ Very naive, very honest
 -----------------------
 
 To be clear, this is a **very naive** discovery system: one
-process-tree-local registrar holding a dict, no replication, no
-re-election when it dies, no cross-host propagation. That's
-intentional (for now); it covers the "wire up my services on this
-host" case without dragging in a consensus protocol.
+in-memory registrar holding a dict, no replication, no re-election
+when it dies, and no automatic cross-host propagation. Separate
+programs can use the same reachable registrar, as above, but must be
+configured with its address. That's intentional (for now); it covers
+the "wire up my services" case without a consensus protocol.
 
 On the roadmap (issue `#216`_ tracks a chunk of it):
 
@@ -254,6 +302,7 @@ to hear from you.
      :class:`tractor.Registrar`.
 
 .. _gossip protocol: https://en.wikipedia.org/wiki/Gossip_protocol
-.. _modern protocol: https://en.wikipedia.org/wiki/Rendezvous_protocol
+.. _modern protocol:
+   https://en.wikipedia.org/wiki/Rendezvous_protocol
 .. _discovery: https://zguide.zeromq.org/docs/chapter8/#Discovery
 .. _#216: https://github.com/goodboy/tractor/issues/216