[0x054]

Closes #767

What

Adds the Inspecting SQL guide page under Guide after Raw SQL: .sql() on count and update, the ferro.sql log turned on, a record as a message and as attributes, *** for a secret column, the catalog and transaction records, and a caplog test. Every output block is regenerated from docs/examples/inspecting_sql.py (and its generated _annotated twin). The data-steps, auto-migrate, Connections, Queries and Raw SQL guides link to it.

Verify

Ran the ticket's Verify block on cbec99bd (a formatter-only commit after 79da0d10; main merged at cf1ee43): passed (strict build clean; the four docs test files plus test_docs_output.py and test_docs_twins.py, 847 tests on SQLite + Postgres 18; docs lint exit 0).
TDD: RED the docs lint command named the page and both examples, which did not exist on main; GREEN the same command, the strict build and the four docs test files passed after the edit. Output blocks are checked by tests/test_docs_output.py (1077 passed across the wider docs suite).
Verify block corrected: no

Interfaces

Interfaces changed: none

Laws

• AGENTS.md#I-7: model declared as Assignment/Annotated tabs; twin generated by tests/_docs_twins.py
• AGENTS.md#I-8: every lambda parameter is account; docs lint passes
• AGENTS.md#I-10: n/a: CHANGELOG.md untouched
• docs-page-conventions: printed output is prints:-backed, none typed; one running example; lead-in and result sentences
• GLOSSARY.md: n/a: no term added

Notes for the reviewer

Outside Files owned: docs/pages/guide/queries.md and docs/pages/guide/raw-sql.md each gain one see-also line (the ticket's Produces names them).

Fix round: the example's regions now run in the order the page shows them, so every printed result is reproducible by following the page. I kept the log setup after the first connect() rather than before it: the opening program stays short, and the page says plainly that a reader who wants the migrate records puts those lines before connect(). The operations block therefore prints only the transaction's records, and the catalog record is explained in prose (the earlier .sql() call already touched the table).

Declared deviations:

• The caplog fence is test=compile, not a runnable fence: test=pytest fences build only from the testing how-to. Follow-up filed as Docs harness: run test=pytest fences from pages other than the testing how-to #835 (needs-triage). The same logic runs as the assert-on-records region in the example.
• The PostgreSQL catalog record is prose, not a (postgres) prints block, which would need an argv-driven connect in the example.
• No SQL fences, so tests/test_docs_sql.py PAGES is unchanged; the example docstring now says so.
• The data-steps note now points at Connections > Logging for the two logging lines, and at this page for what they record.

🤖 Generated with Claude Code

[0x054]

Spec: PASS

• Minor · [ticket#Acceptance criteria] · docs/pages/guide/inspecting-sql.md:150 at a50121c · Missing · the caplog fence is {test=compile ...}, so the docs harness never runs that block (its db fixture, its caplog.at_level(..., logger="ferro.sql") call, the [record] = ... unpacking). The AC says every Python block is a snippet or a {test=run prelude=...} fence. The behaviour it shows is pinned elsewhere (tests/test_statement_log.py asserts record.operation / record.params under caplog), so this is not a correctness hole. The fence reason is also inaccurate: the conventions provide {test=pytest path=...} for exactly this case, but today it is wired only to the testing how-to (tests/test_docs_testing_fixtures.py, whose testing_models.py has no Account). Accept the deviation, or file a follow-up that extends that harness to this page.
• Minor · [ticket#What to build] · docs/pages/guide/schema/data-steps.md:251 at a50121c · Misunderstood · the ticket asks the page to turn the statement log on "with two lines of logging", and the data-steps note sends readers to Inspecting SQL "for the two lines". The page has no two-line setup. Its section (inspecting-sql.md:64-72) shows an 8-line collecting handler and links to Connections for logging.basicConfig. Put the two basicConfig/setLevel lines on the page, or point the data-steps link at ../connections.md#logging.
  Cannot verify: none

Quality: FAIL

• Important · [none] · docs/pages/guide/inspecting-sql.md:69-72,130-140 at a50121c · the page shows the regions in a different order from the script that captures their output, so two printed results cannot be reproduced in page order, and the prose contradicts itself. The statement-log handler is shown at line 69, after the first block (line 26) has already run connect(...), yet line 72 says "Every statement from here on, the schema work connect() does included, lands in records". The operations block (line 133) prints ['migrate', 'save'] for "each record so far". In page order the handler was attached after connect(), so there is no migrate record. The secrets block (line 115) comes earlier on the page and runs records.clear() followed by a fetch, so "so far" would print ['fetch']. In the script the order is statement-log → first → … → operations → count-and-update → secrets, and the prints: blocks come from that order. A reader who follows the page, or pastes its blocks in sequence, gets different output from what the page prints, and the migrate explanation at line 142 does not match. Fix: show the statement-log section before the first connect block, and reorder the script regions so the page order and the execution order are the same (or move the operations region's "so far" print ahead of secrets on the page).
• Minor · [none] · docs/examples/inspecting_sql.py:5-6 at a50121c · the module docstring says the page's SQL blocks are regenerated by tests/test_docs_sql.py. The page has no SQL fences and PAGES is unchanged, as the PR body says. The comment is false and points a maintainer at a test that does not cover this page. Drop the clause.

Checked and accepted: the see-also lines in queries.md / raw-sql.md (outside Files owned, named by the ticket's Produces line). The prose operation list ['migrate', 'catalog', 'save'] and the "only $1/$2 and dialect change on PostgreSQL" claim (verified by running the example against Postgres 18 in a fresh schema: output matches the SQLite blocks apart from placeholders and dialect, and the first list is ['migrate', 'catalog', 'save']). I-7 tabs with a generated twin. I-8 account lambdas (lint exit 0). I-10 CHANGELOG untouched. The ## Laws section and Verify block corrected: no match the ticket's Verify.

Verify: PR head a50121c passed (zensical build --clean --strict; the four docs test files with --db-backends=sqlite,postgres, 417 passed; python -m tests._docs_checks over the six paths, exit 0; also tests/test_docs_output.py -k inspecting, 12 passed)
Trial merge: not run (base unchanged; the head already contains origin/main cf1ee43)

[0x054]

Re-review: a50121c..79da0d1

• Important (page order not the run order): ADDRESSED · docs/examples/inspecting_sql.py:44-100 and docs/pages/guide/inspecting-sql.md:69-143 at 79da0d1 · the regions now run in page order: first, count-and-update, statement-log, a-record, attributes, operations, secrets, then the test. The operations region clears the list before its transaction, so its single printed line depends on nothing earlier. Line 72 now says the program above already called connect() and tells the reader to put the lines before connect() to get the migrate records. Keeping the setup after the first connect() is acceptable because the page states what that costs and how to avoid it. I ran the fixed example on Postgres 18 with every record listed: ['save'] after the INSERT, then ['transaction', 'save', 'fetch', 'transaction'], with no catalog record. That matches the new prose that the .sql() call touched Account before the log was on.
• Minor (caplog fence compile-only): NOT ADDRESSED · docs/pages/guide/inspecting-sql.md:150 at 79da0d1 · the fence is still test=compile. The deviation is now declared in the PR body, and follow-up #835 (Docs harness: run test=pytest fences from pages other than the testing how-to) is open. Accepted as a declared deviation; it does not block.
• Minor (data-steps "two lines"): ADDRESSED · docs/pages/guide/schema/data-steps.md:251 at 79da0d1 · now points at ../connections.md#logging for the two lines and at Inspecting SQL for what they record.
• Minor (example docstring names test_docs_sql.py): ADDRESSED · docs/examples/inspecting_sql.py:3-6 at 79da0d1.

No new Critical or Important breakage in the fix diff.

Spec: PASS

Cannot verify: none

Quality: PASS

Verify: PR head 79da0d1 passed (zensical build --clean --strict; the four docs test files with --db-backends=sqlite,postgres, 417 passed; tests/test_docs_output.py -k inspecting, 12 passed; python -m tests._docs_checks over the six paths, exit 0)
Trial merge: not run (base unchanged; the head contains origin/main cf1ee43)