# PostgreSQL 18 Editorial Review Execution Plan Status: implemented in the repository; independent human review and beta reading remain external release gates Working branch: `codex/editorial-review-pg18` Branch point: `72f06b26` (`main`, seven local commits ahead of `origin/main`) Target contract: PostgreSQL 18.x, with third-party products and extensions versioned separately ## Objective Turn the current manuscript into a publication candidate that preserves its voice, Elephant Cafe world, metaphors, illustrations, and diagnostic teaching strengths while meeting four release conditions: 1. No known high-severity technical errors. 2. Every core lab succeeds from a clean, documented PostgreSQL 18 environment. 3. The narrative spine remains readable without requiring the optional plan-node and `pg_wait_tracer` reference material. 4. The canonical Markdown, generated chapter Markdown, links, assets, terminology, and executable examples pass a repeatable editorial preflight. The sequence below deliberately puts factual verification and reproducibility before structural rewriting or prose polishing. Source chapters under `Manuscript/` are canonical; `ManuscriptCompiled/` is generated output and should not be edited directly. PDF authoring and distribution QA are explicitly outside this branch's completion gate following the author's direction on 2026-08-21. ## Execution summary The repository work in Phases 0–5 is complete: - PostgreSQL 18 is the declared version contract, with non-core and privileged material labeled separately. - All 25 named technical findings have been corrected in the canonical manuscript and propagated to the generated Markdown. - Core SQL checks now exercise the foreign-key, vector, CTE, row-level-security, and audit examples against PostgreSQL 18. - The manuscript validator inventories and classifies executable-looking blocks, scans for retired or contradicted claims, and writes a reviewable artifact. - Chapter 4 now keeps representative plan reasoning on the narrative path and leaves the deeper node catalog in the companion repository's Operations Field Guide. - Chapter 7 now has a stock-PostgreSQL core path and an explicitly optional Linux/privileged `pg_wait_tracer` path. - Chapter 10 is now a full graduation chapter with end-to-end read/write paths, diagnostic and index heuristics, a production checklist, and a combined final incident. - Every narrative chapter contains a Sources & Further Reading route into primary documentation. Phase 7 has been prepared as a reusable beta protocol in `BETA_READER_PROTOCOL.md`. Recruiting independent experts and readers, collecting their responses, and making the final publication decision are human activities and are not represented as completed by repository automation. ## Severity and evidence rules ### Severity - **P0 — release blocker:** can teach an incorrect production model, create unsafe guidance, contradict PostgreSQL 18, or break a promised runnable example. - **P1 — trust or learning blocker:** materially misleading simplification, missing security/operational qualification, obsolete/version-specific behavior, or substantial pacing/reproducibility friction. - **P2 — polish:** terminology, navigation, repetition, typography, citations, accessibility, or product finish. ### Evidence required before closing a technical item Each technical correction must include all of the following in its commit or issue record: 1. The original claim and exact source file. 2. A primary source: PostgreSQL 18 documentation or source code for core behavior; official extension/vendor documentation for non-core behavior. 3. A replacement mental model stated literally before any metaphor. 4. A runnable example or test when the claim is observable in SQL. 5. A scan of chapter summaries, operation cards, diagrams, generated text, and cross-references for the same stale claim. 6. Regenerated `ManuscriptCompiled/` output and applicable validation checks. Words that trigger mandatory review are: **always, never, only, exactly, guarantees, entire, every, physically, strictly, absolute, flawlessly,** and **out of the box**. These words are not banned, but every use must be defensible under the declared version contract. ## Phase 0 — Establish the controlled baseline ### Deliverables - Add a short front-matter version contract targeting PostgreSQL 18.x. - Record extension and product versions separately: at minimum pgvector, PgBouncer, pgAudit, `pg_wait_tracer`, Patroni, Aurora, and Neon. - Establish an editorial issue ledger using the IDs in this plan. - Save the current source-file count, generated-chapter inventory, code-block inventory, and validation results as the comparison baseline. - Document that the repository currently uses `pgvector/pgvector:pg18-trixie` in `docker-compose.yml`. - Decide which examples are **core PostgreSQL**, **optional extension**, **vendor-specific**, or **privileged/destructive lab** material, and label them consistently. ### Acceptance gate - A reader can identify the supported PostgreSQL version before Chapter 1. - Every non-core section says what product/version the explanation targets and when the architecture was checked. - Generated and source files have an explicit ownership rule: edit `Manuscript/`, then regenerate `ManuscriptCompiled/`. ## Phase 1 — Technical trust red-team Work in small, chapter-scoped commits. A correction is not complete merely because the quoted sentence changed; related diagrams, summaries, lab output, operation cards, and cross-chapter explanations must agree. ### A. Foundations, storage, and indexes | ID | Sev. | Finding and source | Required correction | Verification | | --- | --- | --- | --- | --- | | TECH-01 | P0 | Foreign-key indexing warning is backwards in `Manuscript/03 - Access Paths & Indexing/3.5 - Constraints & Triggers (The Integrity Layer and the Chain Reaction).md`. | Explain that referenced columns must be backed by a primary/unique constraint or suitable unique index, while PostgreSQL does not automatically index the referencing child columns. Center the operational warning on parent `UPDATE`/`DELETE` searches of the child table. | Add a lab comparing parent deletion with and without an index on the child FK. Check Chapter 1 schema language and `scripts/init.sql`. | | TECH-02 | P0 | Index maintenance claims three physical disk writes and durable index-page flushes before `INSERT` succeeds in `3.6 - Index Maintenance`. | Replace with synchronous CPU, buffer, lock/latch, WAL, and dirty-page work. Explain that WAL durability permits heap and index pages to be flushed later. | Cross-check Chapter 5 WAL wording; add or reuse a WAL-volume observation rather than claiming one flush per index. | | TECH-03 | P1 | A foreign key is called a tiny 4-byte pointer in `1.0 - Relations & Normalization`. | Call it a stored scalar key value protected by a referential constraint, not a physical row pointer. Qualify the byte size by chosen data type. | Search Chapters 1–3 for physical-pointer language and align definitions. | | TECH-04 | P0 | PostgreSQL is described as append-only and as never updating data in place in `2.0 - Storage Foundations`. | State that `UPDATE` creates a new heap tuple version rather than overwriting the old user payload, while tuple metadata and pages can be modified and free space can be reused. | Check tuple-header, HOT, vacuum, and page-reuse explanations for consistency. | | TECH-05 | P1 | “Readers never block writers; writers never block readers” is used as a foundational rule. | Narrow it to ordinary MVCC visibility reads and ordinary writes, then list the principal exceptions: explicit row locks, DDL/table locks, `SELECT ... FOR UPDATE/SHARE`, and Serializable coordination. | Add a compact boundary box and a two-session exception lab or link forward to Chapter 7. | | TECH-06 | P0 | Aborted-XID visibility is attributed to the Visibility Map in `2.5 - MVCC`. | Assign commit/abort status to `pg_xact`/transaction status with tuple hint bits as applicable; reserve the Visibility Map for page-level all-visible/all-frozen state. | Check the index-only-scan and vacuum sections for the same conceptual separation. | | TECH-07 | P1 | Snapshot explanation is compressed into “just three numbers/boundaries” in `2.2.1 - Visibility & System Columns`. | Define a snapshot as compact transaction metadata: visibility bounds plus the set of transactions in progress, not a copy of pages. | Ensure the definition remains compatible with the isolation chapter and exported diagrams. | | TECH-08 | P0 | A cosine HNSW opclass is paired with the L2 `<->` operator in `3.4 - HNSW & IVFFlat`. | Use a distance operator that matches the opclass, or use `vector_l2_ops` consistently. State the metric next to every vector example. | Execute extracted pgvector examples against the pinned container and assert the intended index plan where deterministic. | ### B. Planning, execution, protocol, and processes | ID | Sev. | Finding and source | Required correction | Verification | | --- | --- | --- | --- | --- | | TECH-09 | P0 | CTEs are said to materialize by default in `4.9 - Common Table Expressions` and `Operations/Other/CTEScan.md`. | Explain PostgreSQL 12+ folding: side-effect-free, non-recursive, singly referenced CTEs can be folded; multiply referenced CTEs normally remain materialized; `MATERIALIZED` and `NOT MATERIALIZED` influence the choice. | Add paired `EXPLAIN` cases and validate both the chapter and operation card. | | TECH-10 | P0 | Extended Query Protocol says Parse builds the plan and later Bind/Execute skips the planner in `6.1.1 - Connection Mechanics`. | Separate parse/analysis from Bind-time planning, parameter-sensitive custom plans, and possible generic-plan reuse. Remove any guarantee that subsequent executions skip planning. | Add a protocol sequence diagram sourced from PostgreSQL 18 protocol docs; validate prepared-statement wording in pooling sections. | | TECH-11 | P0 | A backend is said to allocate its private `work_mem` at connection setup in `6.1.1`. | Define `work_mem` as a per-operation limit used on demand, potentially multiple times per query and across concurrent backends. | Align with `6.3 - Work Mem`; add a concurrency multiplication example rather than a per-login reservation. | | TECH-12 | P0 | An abnormal backend crash is said to “die alone” in `6.0 - Memory & Disk`, contradicting `6.1 - Process Family`. | Preserve private-address-space isolation, but explain that abnormal child termination can trigger termination of sibling processes and shared-state reinitialization because shared memory may be inconsistent. | Make both sections and the process diagram describe one model. | | TECH-13 | P0 | `6.1 - Process Family` includes the retired Stats Collector process. | Remove the dedicated process for the PostgreSQL 18 contract and explain that cumulative statistics are maintained in shared memory in modern PostgreSQL. | Update every process tree/illustration and search generated outputs for “stats collector.” | | TECH-14 | P1 | Shared-buffer story treats a miss as repeated physical SSD I/O and treats a PostgreSQL container restart as a reliable cold-cache reset. | Teach the four-level model: backend/private operation memory → shared PostgreSQL memory → OS page cache → storage. Explain that `shared_buffers` misses can hit the OS cache and that restarting PostgreSQL does not necessarily clear host cache. | Rewrite the incident with measured/clearly labeled cache states. Do not require unsafe host cache eviction in a core lab. | | TECH-15 | P1 | Some executor descriptions imply scan nodes are the only operators interacting with disk. | Distinguish relation access from all I/O: sorts/hashes/materialization can use temporary files, write nodes perform I/O, and WAL/background activity is separate. | Search Chapter 4 and operation cards; include `EXPLAIN (ANALYZE, BUFFERS)` temp read/write evidence for one spill. | ### C. Durability and transactions | ID | Sev. | Finding and source | Required correction | Verification | | --- | --- | --- | --- | --- | | TECH-16 | P0 | WAL is said to UNDO stolen uncommitted data in `5.1 - WAL & fsync`, contradicting `5.2 - Crash Recovery`. | Make crash recovery REDO-oriented and explain why uncommitted tuple versions can remain physically present but invisible under MVCC. | The WAL, crash recovery, transaction, and MVCC chapters must use the same model; retain a crash-recovery lab. | | TECH-17 | P0 | COMMIT is described as flipping exactly two CLOG bits and making changes visible to the entire world in `5.4 - Transactions`. | Explain that commit does not finalize each modified tuple; WAL commit records and transaction-status machinery make tuple versions logically committed, while each observer’s snapshot still governs visibility. | Add a two-session Repeatable Read example showing a committed transaction that remains invisible to an older snapshot. | | TECH-18 | P1 | Physical replication is described as raw 8KB page WAL and logical replication as universally lower volume. | Use the durable conceptual distinction: storage-level WAL stream/whole cluster versus decoded relation-level changes/selected objects. Explain full-page images and workload-dependent volume without universal byte claims. | Align Chapters 5 and 8 and cite PostgreSQL 18 replication/WAL docs. | ### D. Scaling, vendors, pooling, and security | ID | Sev. | Finding and source | Required correction | Verification | | --- | --- | --- | --- | --- | | TECH-19 | P0 | Declarative partitioning is titled and positioned as scaling writes in `8.2 - Scaling Writes`. | Reframe as large-table write locality, pruning, retention, vacuum/index/maintenance scope, and operational isolation. State explicitly that it does not distribute writes across independent servers. | Rename headings/navigation and update the Chapter 8 decision tree and summary. | | TECH-20 | P0 | Standby conflict capstone reduces the mechanism to a page lock and presents `hot_standby_feedback` as the fix. | Add a conflict matrix covering snapshot/cleanup conflicts, AccessExclusive locks, buffer pins, and deadlocks where relevant. Present feedback as mitigation for cleanup conflicts with a primary-bloat trade-off, not a universal cure. | Create reproducible examples only for stable conflict classes; label platform/config prerequisites. | | TECH-21 | P0 | RLS explanation omits table-owner and `BYPASSRLS` behavior. | Add a bypass matrix for superusers, `BYPASSRLS`, table owners, and `FORCE ROW LEVEL SECURITY`; clarify what RLS can and cannot guarantee when application roles or ownership are misconfigured. | Add role-based tests for ordinary tenant, owner, forced owner, and bypass role. | | TECH-22 | P1 | Neon claims use “100% unmodified,” “absolute feature parity,” and “flawlessly out of the box” in `8.1 - Scaling Storage`. | Replace absolutes with a dated, versioned architecture description and operational limits such as privilege, extension allowlist, filesystem, preload-library, or version restrictions, based on official vendor material. | All vendor sections carry “checked as of” metadata and official sources. | | TECH-23 | P1 | Pooling/prepared-statement and temporary-table behavior is presented too categorically. | Describe PgBouncer behavior for the pinned version and pool mode. Explain that temporary tables belong to backend sessions and the operational consequences of transaction pooling without calling them private backend memory. | Verify against official PgBouncer docs and an optional integration lab. | | TECH-24 | P1 | Failover/synchronous-commit/Patroni descriptions risk implying universal safety or deterministic behavior. | Separate PostgreSQL durability settings, replication topology, quorum policy, fencing, and Patroni deployment-specific configuration. Label any scenario as illustrative. | Have an independent HA reviewer validate failure timelines and data-loss claims. | | TECH-25 | P0 | Event-trigger auditing is called compliance-grade out of the box in `9.5 - DDL Audit Logging`. | Distinguish observability from tamper-resistant audit controls; describe privileged-user threats, external retention, and why event triggers alone may not meet a compliance regime. | Security reviewer signs off on threat model and terminology. | ### Technical red-team exit gate - All P0 items are closed with primary-source evidence and, where possible, runnable tests. - All P1 technical items are either closed or explicitly documented as deferred with a publication impact decision. - Two independent PostgreSQL experts have reviewed Chapters 2, 5, 6, and 8; at least one security-aware reviewer has reviewed Chapter 9. - A repository-wide absolutes scan has been adjudicated, not merely bulk-replaced. - No source chapter contradicts another chapter’s mental model of MVCC, WAL, processes, caches, replication, or visibility. ## Phase 2 — Reproducibility as a product feature ### 2.1 Create a prominent “Before You Start” path Put the setup immediately after the introduction and include: - exact PostgreSQL image/version and supported host platforms; - one-command startup from a clean checkout; - one verification query proving the correct Elephant Cafe schema/data is loaded; - the exact core extensions and why each is needed; - an optional-tools section for `pg_wait_tracer`, pgAudit, PgBouncer, Patroni, and vendor exercises; - privilege, restart, crash, and host/kernel requirement badges; - reset commands for the whole book and per chapter; - expected-output conventions and a troubleshooting section. The existing `docker-compose.yml` and `scripts/init.sql` are a useful starting point, but startup alone is not yet the complete reader contract. ### 2.2 Extract and classify executable blocks Build a validator that inventories fenced blocks under `Manuscript/` and labels them: - `sql:core` — must run in CI against PostgreSQL 18; - `sql:extension` — runs in a pinned optional image; - `sql:illustrative` — syntax/example only, with a reason it is not executed; - `shell:safe` — reader-safe setup/inspection; - `shell:privileged` — restart, crash, tracing, or OS-level action; - `output` — expected result, never executed. Unlabeled executable-looking blocks should fail the manuscript check once migration is complete. ### 2.3 Add lab reset and isolation rules - Every chapter begins from either the clean base dataset or a named checkpoint. - Labs create objects in a chapter-specific schema or use collision-proof names. - Destructive/crash labs use disposable containers and never target an arbitrary reader database. - Each lab documents setup, command, expected observation, cleanup/reset, and supported platform. - Timing-sensitive examples use ranges or qualitative observations unless exact fixtures make the timing deterministic. ### 2.4 CI matrix At minimum, CI should run: 1. Clean PostgreSQL 18 startup and schema verification. 2. Core SQL blocks in manuscript order, with chapter resets. 3. Extension blocks for pageinspect, pg_buffercache, btree_gist, and pgvector. 4. Existing Chapter 4 plan/asset checks. 5. Existing Chapter 7 wait-event semantic checks. 6. Markdown link/image/reference validation. 7. Manuscript compilation followed by a clean-tree check to detect stale generated chapters. 8. A terminology/version scan for retired processes and adjudicated absolute claims. `pg_wait_tracer` should have its own optional Linux/privileged job. A failure in optional tracer setup must not prevent a reader from completing the core PostgreSQL path. ### Reproducibility exit gate - A new reader can clone, start, verify, complete each core lab, and reset without undocumented steps. - All core SQL runs automatically on PostgreSQL 18.x. - The vector metric mismatch and similar copy/paste failures are mechanically detectable. - Optional tooling has pinned versions, prerequisites, and a clear fallback using stock PostgreSQL views. ## Phase 3 — Information architecture and pedagogy Do this only after technical corrections stabilize the material that may move. ### 3.1 Separate the narrative spine from the field guide Keep in the Chapter 4 narrative spine: - declarative SQL versus physical execution; - planner estimates, cardinality, selectivity, and costs; - `EXPLAIN`/`EXPLAIN ANALYZE` reading workflow; - representative scan, join, aggregate, and memory/spill examples; - sargability and one end-to-end debugging case. Keep exhaustive operation cards, lesser-used nodes, detailed tracer signatures, and catalog-style tables in the clearly navigable companion field guide rather than adding a thin printed appendix. Preserve links from the narrative to deeper reference material. ### 3.2 Make Chapter 7 dual-track - **Core track:** `pg_stat_activity`, `pg_blocking_pids()`, `pg_locks`, `pg_stat_statements`, `EXPLAIN (ANALYZE, BUFFERS)`, and `pg_stat_io`. - **Advanced track:** `pg_wait_tracer`, labeled optional, with repository URL, version pin, privileges, Linux/kernel support, install path, capture provenance, and a legend distinguishing measured raw captures from normalized teaching fixtures. The “working, waiting, or making others wait” framework remains central and should be promoted in chapter navigation and marketing copy. ### 3.3 Standardize the exercise loop Use the same sequence for substantial labs: 1. **Predict** — commit to the expected behavior or plan. 2. **Observe** — run the SQL and capture the evidence. 3. **Explain** — answer prompts before reading the explanation. 4. **Repair** — change one variable and rerun. 5. **Generalize** — state when the repair would fail or reverse. Complete solutions can move to chapter ends or the companion material so the answer is not revealed immediately. ### 3.4 Resolve chapter placement - Decide whether Constraints & Triggers belongs with Chapter 1 integrity or in a short write-path bridge, rather than interrupting access paths. - Keep replication slots near WAL if they support retention/durability understanding; move publications/subscriptions and cross-cluster architecture choices to Chapter 8. - Rename partitioning around large-table write locality and maintenance, not horizontal write scaling. ### Information-architecture exit gate - Primary readers can complete the narrative without reading the entire operation/wait-event catalog. - Deep reference content remains reachable within two links from the relevant narrative section. - Chapter 4 and Chapter 7 beta readers no longer report an abrupt transition from tutorial to manual. ## Phase 4 — Versioning, citations, and metaphor boundaries ### Version badges Use a small, consistent vocabulary such as: - `PG 18` - `PG 15+` - `pgvector <pinned version>` - `PgBouncer <pinned version>` - `Vendor architecture checked YYYY-MM` Only add a badge where behavior is version-sensitive or non-core; avoid visual noise on universal concepts. ### Sources and further reading Add an unobtrusive block at the end of each chapter containing: - official PostgreSQL documentation sections; - relevant PostgreSQL source directories/files for internals claims; - foundational papers where they genuinely help; - official extension documentation; - official vendor architecture sources for vendor-specific sections. Primary sources should support the technical claim. Citations should not turn the narrative into academic footnotes. ### “Where the metaphor stops” rule For metaphors that might imply a false mechanism, add a one- or two-sentence boundary note. Lead with the literal PostgreSQL term, then use the metaphor. Prioritize tuple/suitcase, append-only, snapshot/window, page/container, index bookshelf, and process-family explanations. ### Prose pass After structure is stable: - reduce repeated use of “the engine,” “physical reality,” “architectural payoff,” “lazy/laziness,” “the engine refuses,” and “the engine does not panic”; - retain “The Click” only for genuine synthesis moments; - remove absolutes where the actual rule has meaningful exceptions; - target roughly 10–15% tightening through repetition removal, not wholesale deletion of personality. ## Phase 5 — Strengthen the final payoff Expand Chapter 10 into a 6–10 page graduation and synthesis chapter: 1. The whole PostgreSQL machine on one spread. 2. End-to-end read path: query arrival to returned rows. 3. End-to-end write path: statement to COMMIT to crash recovery. 4. Working/waiting/blocking troubleshooting decision tree. 5. Index-choice first-pass heuristic with explicit limits. 6. Production health checklist. 7. What the book deliberately does not cover. 8. Recommended next subjects and primary references. 9. A final incident combining storage, estimation/plan choice, transaction visibility, and waits. The final incident is the capstone acceptance test: a reader should be able to explain the causal chain using concepts from at least four chapters rather than naming isolated PostgreSQL features. ## Phase 6 — Markdown production preflight ### Automated checks - Internal links, image references, operation-card references, and chapter transclusions resolve. - Canonical and generated chapter Markdown remain synchronized. - Executable-looking blocks are classified and the core PostgreSQL 18 set succeeds. - No malformed Unicode, doubled words, retired-process terminology, or known contradicted claims remain. - Chapter 4 runtime-evidence references and Chapter 7 wait-event semantics pass their dedicated checks. - The absolutes scan is adjudicated through the editorial contract instead of mechanically deleting the book's voice. PDF metadata, page layout, running headers, compression, grayscale, and tagged-PDF checks are not a gate for this Markdown-focused branch. ### Production exit gate - Canonical and generated Markdown pass the full editorial, lab, Chapter 4, Chapter 7, and asset suites. - The generated code-block inventory is current. - `git diff --check` reports no whitespace defects. - PDF authoring is handled separately when the author chooses to resume that production track. ## Phase 7 — Beta and release decision Recruit three distinct cohorts, approximately 8–12 readers each: - primary audience: backend/application engineers who know SQL but not PostgreSQL internals; - expert red-team: PostgreSQL DBAs, contributors, performance engineers, and one HA/security specialist; - teaching/usability: self-directed learners and database educators. After every chapter collect: - capability gain, 1–7; - the first confusing point; - what they would remove; - whether they completed the labs without help; - time-to-complete and any undocumented prerequisite. At the end collect the 0–10 recommendation score and ask: “What single thing prevents you from giving this book a 10?” ### Release gate - Zero known P0 technical issues. - Core lab CI green from a clean checkout. - Expert disagreements concern nuance or editorial choice, not basic mechanics. - Primary readers finish Chapters 4 and 7 without the reference density becoming a common stopping point. - Readers can reconstruct the central mental model a week later. - Markdown editorial preflight passes from a clean checkout. ## Recommended commit and review sequence Keep commits independently reviewable and avoid mixing generated PDF churn into technical corrections. 1. `docs(editorial): declare PostgreSQL 18 version and evidence contract` 2. `fix(ch1-3): correct relational storage and index mental models` 3. `fix(ch4): update CTE and executor behavior` 4. `fix(ch5): align WAL recovery commit and replication semantics` 5. `fix(ch6): correct process protocol memory and cache model` 6. `fix(ch8-9): harden scaling vendor RLS and audit claims` 7. `test(labs): extract and execute core PostgreSQL 18 examples` 8. `docs(setup): add before-you-start reset and optional-tool paths` 9. `refactor(book): separate narrative chapters from field guides` 10. `feat(epilogue): add end-to-end synthesis and production checklists` 11. `style(manuscript): tighten prose and add metaphor boundaries` 12. PDF authoring is intentionally deferred to a separate production branch. Regenerate `ManuscriptCompiled/` with `make manuscript` in the same commit as source changes so the tracked generated Markdown stays synchronized. ## Immediate first execution slice The best first slice is small enough for expert review but broad enough to establish the correction style: 1. Add the PostgreSQL 18 version contract and evidence template. 2. Fix TECH-01, TECH-02, and TECH-08 in Chapter 3. 3. Add executable checks for the foreign-key child index behavior and pgvector metric/opclass pairing. 4. Regenerate compiled Chapter 3. 5. Run `make manuscript`, the new Chapter 3 lab checks, `make check-assets`, and a stale-generated-output check. 6. Ask one PostgreSQL expert to review the literal explanation and one primary-audience reader to review whether the revised metaphor remains clear. This slice tests the entire workflow—source correction, primary-source evidence, executable lab, generated manuscript, and two-audience review—before applying it to the more interconnected MVCC/WAL/process corrections. ## Definition of done for the editorial branch The branch is ready to merge only when: - every P0 item in this plan is closed and independently reviewed; - every intended executable example is classified and the core set passes automatically; - core and optional tooling are visibly separated; - source chapters and generated chapters are synchronized; - structural changes have passed primary-reader beta feedback; - the expanded epilogue delivers an end-to-end synthesis; - canonical and generated Markdown pass the complete editorial preflight; - the issue ledger contains no unresolved contradiction across chapters; - the release notes state the exact PostgreSQL, extension, and vendor-version contract.