From be0a10b0d2203d53d775e1ed5385b37b23fa06c7 Mon Sep 17 00:00:00 2001 From: goodboy Date: Thu, 25 Jun 2026 19:31:37 -0400 Subject: [PATCH] Add prompt-io provenance for d2-ext + docstring patches --- .../20260625T232506Z_0a3c48fc_prompt_io.md | 65 +++++++++++++++++++ ...20260625T232506Z_0a3c48fc_prompt_io.raw.md | 35 ++++++++++ .../20260625T232506Z_3a5cfde0_prompt_io.md | 64 ++++++++++++++++++ ...20260625T232506Z_3a5cfde0_prompt_io.raw.md | 35 ++++++++++ 4 files changed, 199 insertions(+) create mode 100644 ai/prompt-io/claude/20260625T232506Z_0a3c48fc_prompt_io.md create mode 100644 ai/prompt-io/claude/20260625T232506Z_0a3c48fc_prompt_io.raw.md create mode 100644 ai/prompt-io/claude/20260625T232506Z_3a5cfde0_prompt_io.md create mode 100644 ai/prompt-io/claude/20260625T232506Z_3a5cfde0_prompt_io.raw.md diff --git a/ai/prompt-io/claude/20260625T232506Z_0a3c48fc_prompt_io.md b/ai/prompt-io/claude/20260625T232506Z_0a3c48fc_prompt_io.md new file mode 100644 index 00000000..f44771a0 --- /dev/null +++ b/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`). diff --git a/ai/prompt-io/claude/20260625T232506Z_0a3c48fc_prompt_io.raw.md b/ai/prompt-io/claude/20260625T232506Z_0a3c48fc_prompt_io.raw.md new file mode 100644 index 00000000..a5783f44 --- /dev/null +++ b/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. diff --git a/ai/prompt-io/claude/20260625T232506Z_3a5cfde0_prompt_io.md b/ai/prompt-io/claude/20260625T232506Z_3a5cfde0_prompt_io.md new file mode 100644 index 00000000..70cbd540 --- /dev/null +++ b/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. diff --git a/ai/prompt-io/claude/20260625T232506Z_3a5cfde0_prompt_io.raw.md b/ai/prompt-io/claude/20260625T232506Z_3a5cfde0_prompt_io.raw.md new file mode 100644 index 00000000..4dd68c9e --- /dev/null +++ b/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.