Add prompt-io provenance for d2-ext + docstring patches

ai/prompt-io/claude/20260625T232506Z_0a3c48fc_prompt_io.md

@@ -0,0 +1,65 @@
+---
+model: claude-fable-5[1m]
+service: claude
+session: 638d5a98-abd2-4217-a447-19f2330eb334
+timestamp: 2026-06-25T23:25:06Z
+git_ref: 0a3c48fc
+scope: code
+substantive: true
+raw_file: 20260625T232506Z_0a3c48fc_prompt_io.raw.md
+---
+
+## Prompt
+
+Same `/code-review` follow-up session (PR #460). Finding #10:
+the new `api/` autodoc reference pages surfaced 22 docutils
+warnings sourced from informal reST in public docstrings. The
+user opted to fix it on this branch,
+
+> well we're on a clean main so why not just do these now too?
+
+Goal: drive the docs build warning-free (24 -> 0) without any
+code/behaviour change — docstring content only.
+
+## Response summary
+
+Surgical docstring-RST lint across 9 library modules + the one
+offending `NEWS.rst` changelog entry,
+
+- bullet lists given a blank line + base-column indent
+  (`Context`, `Context.cancel_called`/`.cancelled_caught`/
+  `.outcome`, `ActorNursery.cancel_called`, `query_actor`,
+  `open_crash_handler`, the `#318` `NEWS.rst` entry),
+- the under-short `Behaviour:` underline in `Context.cancel`
+  demoted to a `**bold**` label,
+- unbalanced/pluralized-role backticks fixed — closed the
+  `wait_for_actor` summary backtick; applied the `` `role`\ s ``
+  escaped-plural idiom in `gather_contexts`, `mk_pdb`,
+  `MsgCodec`, msg `Error`, `open_context_from_portal`,
+- the `|_` method-tree in `ContextCancelled.canceller` made a
+  literal block (bare `|` was parsed as a substitution ref).
+
+Verified: build `24 -> 0` warnings; `import tractor` clean under
+`-W error::SyntaxWarning`; the `\ s` idiom renders as e.g.
+"acms" (no backslash/space leak in HTML); `ruff` clean; diff
+confirmed docstring-content-only.
+
+Initial generation was delegated to a constrained subagent
+(docstring-only edits + a rebuild-to-zero verification gate);
+the orchestrator independently re-built, reviewed the full
+diff, and added the `NEWS.rst` fix to reach zero.
+
+## Files changed
+
+- `tractor/_context.py`, `tractor/_exceptions.py`,
+  `tractor/devx/debug/_post_mortem.py`,
+  `tractor/devx/debug/_repl.py`, `tractor/discovery/_api.py`,
+  `tractor/msg/_codec.py`, `tractor/msg/types.py`,
+  `tractor/runtime/_supervise.py`,
+  `tractor/trionics/_mngrs.py` — docstring reST fixes,
+- `NEWS.rst` — blank line before a bullet list in the `#318`
+  entry.
+
+## Human edits
+
+None — committed as generated (`0a3c48fc`).

ai/prompt-io/claude/20260625T232506Z_0a3c48fc_prompt_io.raw.md

@@ -0,0 +1,35 @@
+---
+model: claude-fable-5[1m]
+service: claude
+timestamp: 2026-06-25T23:25:06Z
+git_ref: 0a3c48fc
+diff_cmd: git diff 0a3c48fc~1..0a3c48fc
+---
+
+# Raw output pointers (diff-ref mode)
+
+The generated patch is committed; the verbatim content is the
+diff:
+
+> `git diff 0a3c48fc~1..0a3c48fc`
+
+## Generation notes (non-code, verbatim)
+
+- Pure docstring-content edits; no signatures, logic, or
+  non-docstring lines touched (confirmed via `git diff` review).
+- reST fix patterns applied: blank-line + base-column indent
+  for bullet lists ("Unexpected indentation" / "Definition
+  list ..." / "Block quote ..."); `**bold**` in place of an
+  under-length section underline ("Title underline too short");
+  closing/escaping backticks ("Inline interpreted text ...
+  without end-string"); literal-block for an ASCII tree whose
+  `|` chars tripped "Inline substitution_reference ...".
+- The pluralized-role idiom is written `\\ s` in the Python
+  source (so the runtime docstring holds `` `role`\ s ``); a
+  bare `\ ` would raise a 3.13 invalid-escape SyntaxWarning.
+  Verified clean via `python -W error::SyntaxWarning -c
+  "import tractor"`.
+- Verification gate: `sphinx-build` warning count 24 -> 2
+  (subagent, docstrings only) -> 0 after the orchestrator added
+  the `NEWS.rst` blank-line fix; rendered-HTML spot-check
+  confirmed no literal `\ s` leak; `ruff check` clean.

ai/prompt-io/claude/20260625T232506Z_3a5cfde0_prompt_io.md

@@ -0,0 +1,64 @@
+---
+model: claude-fable-5[1m]
+service: claude
+session: 638d5a98-abd2-4217-a447-19f2330eb334
+timestamp: 2026-06-25T23:25:06Z
+git_ref: 3a5cfde0
+scope: code
+substantive: true
+raw_file: 20260625T232506Z_3a5cfde0_prompt_io.raw.md
+---
+
+## Prompt
+
+Follow-up to a `/code-review` of PR #460 (this branch) which
+surfaced lower-severity findings in the `.. d2::` sphinx
+directive. The user's driving instructions across the session,
+
+> yup do both *at least*, then report back.
+
+(re: "implement #7 (+ optionally #8) on the branch") and,
+
+> well we're on a clean main so why not just do these now too?
+
+(re: also doing #9). The three findings being addressed,
+
+- #7: a `d2` render that is *attempted and fails* (binary
+  present but errors on the source) silently degraded to the
+  stale committed SVG and the build still exited 0,
+- #8: `parallel_*_safe = True` was declared while `run()`
+  writes the shared output SVG during the read phase (torn
+  write under `sphinx-build -j`),
+- #9: output keyed only by `src.stem` so two `.d2` sources
+  with the same stem collide.
+
+## Response summary
+
+Reworked `docs/_ext/d2diagrams.py`,
+
+- `render_svg()` now returns a `RenderResult` tristate
+  (`OK` / `FELL_BACK` / `NO_OUTPUT` / `FAILED`) so `run()` can
+  distinguish a graceful no-binary fallback from a real render
+  failure; `FAILED` emits a `reporter.error` (build fails under
+  `-W`),
+- the render writes into a sibling temp-file then `os.replace()`
+  (atomic) so a failed/torn render can never clobber a good
+  committed SVG,
+- a per-build `_seen_outputs` map (reset on `builder-inited`)
+  errors on a same-stem output collision.
+
+Verified: a corrupted `.d2` errors under `-W` (exit 1) with the
+committed SVG byte-unchanged; the collision guard fires on a
+duplicate stem; `nix run nixpkgs#d2` render path + atomic swap
+leave no temp residue; `ruff` clean.
+
+## Response summary (cont.) — Files changed
+
+- `docs/_ext/d2diagrams.py` — tristate render result, atomic
+  temp-file render, output-collision guard, doc-string policy
+  update.
+
+## Human edits
+
+None — committed as generated (`3a5cfde0`). The user noted
+follow-up refinements may come in later commits.

ai/prompt-io/claude/20260625T232506Z_3a5cfde0_prompt_io.raw.md

@@ -0,0 +1,35 @@
+---
+model: claude-fable-5[1m]
+service: claude
+timestamp: 2026-06-25T23:25:06Z
+git_ref: 3a5cfde0
+diff_cmd: git diff 3a5cfde0~1..3a5cfde0
+---
+
+# Raw output pointers (diff-ref mode)
+
+The generated patch is committed; per the diff-ref decision
+rule the verbatim content is the diff itself:
+
+> `git diff 3a5cfde0~1..3a5cfde0 -- docs/_ext/d2diagrams.py`
+
+## Generation notes (non-code, verbatim)
+
+- `RenderResult` enum added; `render_svg()` return type changed
+  `bool -> RenderResult`. Mapping in `run()`: `FAILED` ->
+  `state_machine.reporter.error(...)`, `NO_OUTPUT` -> raw `.d2`
+  source as a `literal_block`, `OK`/`FELL_BACK` -> `image`.
+- Atomicity via `tempfile.mkstemp(dir=out.parent, ...)` +
+  `os.replace(tmp, out)`; temp unlinked on any failure path.
+- Collision guard: module-level `_seen_outputs: dict[str,str]`
+  keyed by output basename, cleared by a `builder-inited`
+  handler connected in `setup()`.
+- `parallel_read_safe`/`parallel_write_safe` kept `True` but
+  now justified by the atomic swap (documented inline).
+- Empirical verification performed before commit:
+  - broken `.d2` + `sphinx-build -W` -> exit 1, ERROR node
+    rendered, committed `actor_tree.svg` md5 unchanged,
+  - duplicate-stem orphan page -> "d2 output collision" error,
+  - `nix run nixpkgs#d2` forced re-render -> deterministic
+    (no git drift), no `.tmp` residue,
+  - `ruff check` clean.