docs: tighten changelog and release-note guidance (#319)

Author: pinodeca

CHANGELOG.md

@@ -10,29 +10,22 @@ Pre-1.0 note: while `pg_durable` is in major version `0`, minor releases may inc
 
 ### Added
 
-- **`df.http_multipart()` (#302):** send `multipart/form-data` requests. Parts are described as a JSONB array of objects with `name` and `data_b64`, optionally `filename` and `content_type`. Gated by the same `include_http => true` grant as `df.http()`.
-- **Binary HTTP response bodies:** `df.http()` and `df.http_multipart()` now capture non-textual responses instead of losing them to lossy UTF-8 conversion. The response envelope gained an `encoding` field — `text` when the body is the response as-is, `base64` when it holds the base64 of the raw bytes. A body is treated as text when the `Content-Type` is absent, `text/*`, a `+json`/`+xml`/`+yaml` suffix type, or a common textual `application/*` type; everything else is base64.
-- **Variable substitution in multipart `data_b64`:** a part's `data_b64` can now reference an earlier result, e.g. `'data_b64', '$pdf.body'`, letting a payload produced by one HTTP step be uploaded by the next with no intermediate table. The reference must be the *whole* value; mixing it with surrounding text fails the node rather than sending a corrupt part, because splicing into base64 cannot produce a valid encoding.
-- **`examples/audio-roundtrip/`:** a self-verifying example that sends text to Azure OpenAI text-to-speech and pipes the returned MP3 straight into a Whisper transcription upload, then checks the transcript against the original phrase.
-- **`transaction_mode` argument for `df.start()`:** selects which transaction the *start itself* runs in. `'caller'` (the default) is the historical behaviour — the start joins the caller's transaction and is rolled back with it. `'new'` persists and enqueues the work on a separate PostgreSQL session, so it commits independently and **survives a rollback of the caller's transaction**. This provides the same rollback-survival outcome as Oracle autonomous transactions or `REQUIRES_NEW` for asynchronously started work; it is not a synchronous autonomous routine. The returned ID confirms launch, while completion and execution errors are observed through monitoring APIs. Nothing about the started function changes; only the commit boundary of the start does. An unrecognised value raises rather than falling back to the default, and `'new'` is rejected inside a workflow, where a `df.sql()` node's single autocommitted statement already makes a plain `df.start()` independent of any caller transaction. Because the separate session sees only committed rows, the captured `df.vars` snapshot excludes variables set earlier in the caller's open transaction. Each call uses an extra backend, so per-row and other high-fan-out call sites should avoid this mode; target effects should be idempotent because a connection failure can make launch outcome uncertain. The three-argument `df.start()` is dropped in favour of the four-argument one, but its C symbol is retained, so the new `.so` stays backward compatible with all previous schemas in this provider line (see `docs/upgrade-testing.md`).
+- **`df.http_multipart()` (#302):** send `multipart/form-data` requests, gated by the same `include_http => true` grant as `df.http()`.
+- **Binary HTTP response bodies:** `df.http()` and `df.http_multipart()` preserve non-text responses as base64 and identify the body format in the response envelope's `encoding` field.
+- **Audio round-trip example:** demonstrates piping Azure OpenAI text-to-speech output directly into a Whisper transcription upload.
+- **Independent starts (#285):** `df.start(..., transaction_mode => 'new')` commits the start on a separate session, allowing asynchronously started work to survive a caller rollback. The default `'caller'` mode retains the existing transaction behavior.
 
 ### Fixed
 
-- **Multipart parts larger than 57 bytes (#302):** `data_b64` was decoded with a strict base64 decoder that rejects embedded whitespace, but PostgreSQL's `encode(bytea, 'base64')` wraps its output at 76 columns. Any part whose source data exceeded 57 bytes therefore failed to decode. Whitespace in `data_b64` is now ignored, so `encode()` output can be used directly.
-- **Unix-socket worker connections (#292):** a Unix-socket `PGHOST` is now percent-encoded when pg_durable builds the worker's PostgreSQL connection URL, allowing sqlx to connect through socket directories. TCP addresses and hostnames are unchanged.
+- **Unix-socket worker connections (#292):** workers can now connect when `PGHOST` names a Unix-socket directory.
 
 ### Changed
 
-- **Loop execution and replay determinism (#228):** non-root `df.loop()` nodes now run as dedicated child sub-orchestrations, replay-recorded result/variable maps serialize in canonical key order, and root/non-root loops share the same body and while-condition policy. This fixes non-root loop restarts and makes `df.break()` in a while-condition behave identically at either graph position. A loop is now hosted by the same `execute-subtree` orchestration that runs parallel branches, rather than a separate loop orchestration.
+- **Loop execution (#228):** root and nested loops now share consistent execution, restart, and `df.break()` behavior.
 
-  > ⚠️ **Replay-breaking for in-flight instances.** These changes alter recorded orchestration inputs and scheduling order, and duroxide validates both by exact equality on replay.
-  >
-  > - **Every in-flight JOIN (`&`) or RACE (`|`) branch fails**, unconditionally. The `execute-subtree` input envelope gained `instance_id`, `vars`, `label`, and `iteration` fields, so a branch scheduled under 0.2.4 replays with an input shape the 0.2.5 binary rejects. This is *not* limited to workflows carrying multiple variables or named results.
-  > - **In-flight root and non-root `df.loop()` instances may fail** with a nondeterminism error, because loop scheduling and recorded inputs both changed.
-  >
-  > The engine fails closed on a mismatch, but `df.instances` may remain `pending` or `running` because the replay aborts before pg_durable can record its normal failure status. Operators that require in-flight continuity should quiesce and drain before upgrading; operators that accept failed/recreated work can upgrade directly and inspect or cancel stale instances afterward. See `docs/upgrade-testing.md` under "Loop and sub-orchestration replay compatibility".
+  > **Upgrade warning:** in-flight JOIN/RACE branches will fail on replay after upgrading, and in-flight loops may fail. Drain in-flight work before upgrading when continuity is required; see `docs/upgrade-testing.md` for details.
 
-- **HTTP envelope fields are addressable with dot notation:** `$resp.body`, `$resp.status`, `$resp.ok`, and `$resp.encoding` now resolve against an HTTP result. Previously dot notation only worked on SQL results (which carry a `rows` array), so reading an HTTP envelope required an intervening SQL node such as `SELECT ($resp::jsonb->>'ok')::boolean`. `rows` still takes precedence, so SQL results are unaffected.
+- **HTTP result substitution:** HTTP response fields such as `$resp.body`, `$resp.status`, `$resp.ok`, and `$resp.encoding` are now directly addressable with dot notation.
 - **Dependencies:** bumped `duroxide` to 0.1.30 (#305), `uuid` to 1.24.0 (#293), `serde_json` to 1.0.151, and `tokio` to 1.53.1 (#298).
 
 ### Documentation

prompts/pg_durable-release.md

@@ -95,18 +95,24 @@ here (by the agent or human) and lands via a PR — it is **not** automated.
    version, following [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
    (grouped Added / Changed / Fixed / Security / Documentation, plus a Breaking
    Changes callout when relevant).
-3. **If the section is missing or empty**, draft it:
+3. Review the section as user-facing release history, even if it is already
+   complete. Propose edits when entries are wordy, implementation-focused, or
+   more detailed than users need. Remove pure CI/infrastructure work, expected
+   behavior of a newly added feature, and bugs introduced and fixed within the
+   same unreleased cycle. Keep operationally important compatibility, migration,
+   and security guidance, but link to detailed docs instead of reproducing them.
+4. **If the section is missing, empty, or needs the editorial fixes above**,
+   draft or revise it:
    ```bash
    # Merged, user-facing changes since the previous tag
    git log --oneline --no-merges vX.Y.<prev>..main
    # Resolve a squashed commit to its PR when the number isn't in the subject
    gh api repos/microsoft/pg_durable/commits/<sha>/pulls --jq '.[].number'
    ```
-   Curate into user-facing entries with PR references. **Exclude** pure CI/infra
-   noise (e.g. adding a linter, Dependabot config) — that lives in git history,
-   not the changelog. Verify dependency lines against `Cargo.toml` (don't claim a
-   `duroxide`/`duroxide-pg` bump that didn't happen).
-4. Open a PR with the changelog (and any docs sweep from Step 2), get it merged
+    Curate into user-facing entries with PR references. Verify dependency lines
+    against `Cargo.toml` (don't claim a `duroxide`/`duroxide-pg` bump that didn't
+    happen).
+5. Open a PR with the changelog (and any docs sweep from Step 2), get it merged
    to `main`. **Do not tag until the changelog for the release is on `main`.**
 
 > **Update the tracking issue:** link the changelog PR and tick **Changelog
@@ -195,16 +201,33 @@ gh run watch "$(gh run list --workflow package-release.yml --limit 1 --json data
 
 ## Step 5: Fill release notes and publish
 
-The Package Release run creates the draft with placeholder notes. Replace them
-with the curated changelog **plus** an **Acknowledgements** credit and GitHub's
-auto-generated **New Contributors** section, then publish. The release-body
-content already lives in the committed `CHANGELOG.md`, so extract this version's
-section on the fly into a throwaway temp file — **do not** create or commit a
-separate `release-notes-*.md`.
+The Package Release run creates the draft with placeholder notes. Write a brief,
+punchy release summary as a **separate editorial exercise** from the changelog,
+then add an **Acknowledgements** credit and GitHub's auto-generated **New
+Contributors** section. The changelog is the complete user-facing history; the
+GitHub Release should help readers scan the release's value and upgrade impact.
+
+Use the committed changelog as source material, but do not copy it verbatim:
+
+- Prefer one short sentence per item and combine closely related changes.
+- Lead with headline capabilities and meaningful behavior changes.
+- Keep breaking, migration, security, and operational warnings concise but
+  prominent; link to detailed documentation.
+- Omit routine dependencies, documentation-only changes, internal refactors,
+  and CI/infrastructure work unless they materially affect users.
+- Omit expected details of a newly introduced feature and bugs introduced and
+  fixed within the same release cycle.
+- Aim for substantially fewer words than the corresponding changelog section.
+
+Draft the summary in a throwaway temp file. Do **not** create or commit a
+separate `release-notes-*.md`; the durable detailed record remains
+`CHANGELOG.md`.
 
 ```bash
-# 1. Extract the "## [X.Y.Z]" block from CHANGELOG.md (stops at the next "## [" heading)
-awk '/^## \[X\.Y\.Z\]/{f=1;next} /^## \[/{f=0} f' CHANGELOG.md > /tmp/notes-X.Y.Z.md
+# 1. Extract the changelog section as source material and seed a separate draft.
+#    Rewrite the draft editorially before continuing; do not leave it as a copy.
+awk '/^## \[X\.Y\.Z\]/{f=1;next} /^## \[/{f=0} f' CHANGELOG.md > /tmp/changelog-X.Y.Z.md
+cp /tmp/changelog-X.Y.Z.md /tmp/release-summary-X.Y.Z.md
 
 # 2. Fetch GitHub's auto-generated notes ONCE. `gh release edit` has NO
 #    --generate-notes flag (only `gh release create` does), so we generate the
@@ -232,21 +255,22 @@ awk '/^## What.s Changed/{skip=1; next} /^## /{skip=0} /^\*\*Full Changelog\*\*/
 contributors=$(grep -oE 'by @[A-Za-z0-9-]+' /tmp/gen-notes-X.Y.Z.md \
   | sed 's/by //' | sort -u | grep -viE '@(dependabot|github-actions)' | paste -sd ' ' -)
 
-# 5. Assemble: curated changelog + Acknowledgements credit + trimmed auto notes,
+# 5. Assemble: concise release summary + Acknowledgements + trimmed auto notes,
 #    then set the release body
 {
-  cat /tmp/notes-X.Y.Z.md
+  cat /tmp/release-summary-X.Y.Z.md
   printf '\n---\n\n## Acknowledgements\n\nThanks to everyone who contributed to this release: %s.\n\n' "$contributors"
   cat /tmp/auto-notes-X.Y.Z.md
 } > /tmp/release-body-X.Y.Z.md
 gh release edit vX.Y.Z --notes-file /tmp/release-body-X.Y.Z.md
 ```
 
 - The temp files are transient (e.g. under `/tmp`); they are **not** part of any
-  PR and the Package Release workflow never reads them. The single source of
-  truth for curated content is the committed `CHANGELOG.md`.
+  PR and the Package Release workflow never reads them. `CHANGELOG.md` remains
+  the durable detailed record; the GitHub Release is its concise editorial
+  companion.
 - `--notes-file` sets **only the GitHub Release body** — it does not touch
-  `CHANGELOG.md`. The curated text comes from the changelog you already merged.
+  `CHANGELOG.md`.
 - The `releases/generate-notes` API returns a "## What's Changed" PR dump, a
   "## New Contributors" section, and a "Full Changelog" link. We **drop**
   "What's Changed" from the body (it re-lists the same PRs the curated changelog