[kiwidream]

These are the documentation fixes from the review of #811 (v3.1.1) that should ship in 3.1.1. The tag freezes the notes, and operators follow the tagged runbooks.

3.1.1 notes (#813 items 1, 3, 4, 5)

• Verification:
  • The L3 bullet named a run the tag can't promote. The matrix runs l3-full on every PR that changes VERSION, and the tag promotes the run whose tree matches it.
  • It also cites the first l3-full runs on a tree with 3.x.x: wait out commit-gate contention and append again, so a lease's share keeps its credit (#716) #788 (3.x.x: version 3.1.1 and its release notes #810, and v3.1.1 chore: consolidate release for main #811's first head). Both passed all 33 planned runs.
  • "CI … dispatched on the tag" described a step nobody runs. CI does run on the promoted main commit the tag points at, so the bullet now says that.
• 3.0.x: L3 l3-full fails on v3.0.0: 2fe-async-3-blocks refuses one valid share per run (#716), and 2fe-sync-r3 falls 479 offers short #779: updated with those runs. It stays open for 3.0.x.
• Dual-writer upgrade: a 3.1.0 frontend's peer sync still applies pulled prepared jobs to its own node's database without 3.x.x: peer sync's apply_prepared takes the blob-GC fence, in bounded chunks, so a pulled job keeps its blobs (#785) #799's blob-GC fence. The note says so and gives the remedy.
• Migrations: the notes now say "the SQL of 001 to 031 is unchanged" instead of citing sqlx checksums, which the native runner doesn't keep.

Release guide (#813 item 6)

docs/releasing.md now rewrites the notes' inline relative links to blob/v<version>/ for the GitHub release body, as was done by hand for 3.1.0. I tested the sed on the 3.1.1 notes: it rewrites all 17 relative links and leaves anchors alone.

Runbooks (#814 items 3a and 3b, with item 4's guidance)

• 3.x.x: legacy audit segment range digests use Python's ASCII-escaped JSON; also accept that form so 1.x/2.x bodies with non-ASCII worker names verify without sidecars #709 and 3.x.x: 2.x audit-bundle.v2 bodies fail 'window proof share_parts_digest_hex mismatch' because 3.x recomputes the parts digest with serde_json's sorted keys and 2.x hashed insertion order (post-cutover; sidecars cover the cutover) #731 sections: each now opens by saying that from 3.1.1 the procedure isn't needed.
  • With 3.1.1, the 3.x.x: 2.x audit-bundle.v2 bodies fail 'window proof share_parts_digest_hex mismatch' because 3.x recomputes the parts digest with serde_json's sorted keys and 2.x hashed insertion order (post-cutover; sidecars cover the cutover) #731 checker's re-check exits 3 for rows that import accepts. The section now says to read its totals instead.
  • prism-ledger-ops.md's cutover step is scoped to releases before 3.1.1.
• Migration 032: now listed in the migration transaction, in the 027 pre-migrate section and the cutover-rehearsal report. On a database already at 028, migrate takes only the migration history's lock up front.

Not in this PR

• 3.x.x: correct the 3.1.1 release notes (L3 run, date, #799 caveat, migration checksums) and two publish steps before #811 merges #813 item 2, the release date: it goes in the commit that brings the new 3.x.x head into v3.1.1 chore: consolidate release for main #811.
• The rest of 3.x.x: operator docs and the #731 checker still describe pre-3.1.1 behaviour (cluster-row writes, prepared-apply transaction, stale runbook steps) #814: it can wait for 3.1.2.

Checks

• tests/test_docs_lab_prism_references.py: 147 tests OK.
• scripts/check_prism_settings.py: passes.
• Two local /code-review medium passes; all their findings are addressed.

Part of #813 and #814.

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-29T16:03:25.985749Z	238fcef	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[qbit-reviewer]

1 finding posted inline.

[qbit-reviewer]

1. [medium] The release-notes sed uses '#' as its s delimiter but also puts '#' in [^)#/:], so GNU sed rejects the command

docs/releasing.md:78

docs/releasing.md:78 runs s#\]\(([^)#/:][^):]*)\)#...#g. GNU sed finds the end of an s command's regex by scanning for the delimiter character and skips only backslash escapes; it does not handle bracket expressions. The regex therefore ends at the # inside [^)#, the text /:][^):]*)\) becomes the replacement, and ]​(https:... is read as flags. The result is a compile error ("unknown option to s'"). BSD/macOS sed handles bracket expressions here, which may be why the author's test passed. On Linux, sed exits before writing anything. The shell has already created and truncated /tmp/qbit-release-notes.md by then (line 79), and the documented block goes straight on to gh release create ... --notes-file /tmp/qbit-release-notes.md(lines 80-81). That publishes the v<​version> GitHub release with empty notes, and publishing can't be cleanly undone. Escaping the bracket's hash as[^)#/:]or switching to a delimiter such as|` makes the command work in both seds.