Relationships and raw SQL guides #712

Parent

#698

What to build

Raw SQL examples query users and events, but Ferro creates user and event; the NO ACTION row says the constraint is not enforced (it is); the many-to-many join table's name and constraints are documented nowhere. Both pages get one running example shown on the page, real table names, the join-table schema shown as the DDL Ferro creates, and results beside each call.

Pages: guide/relationships.md, guide/raw-sql.md

Acceptance criteria

• Every fact on the page matches the code at the time of the PR; each High finding in the audit rows below is fixed, and each Medium/Low finding is fixed or answered in the PR body with the reason it was left.
• Each page is one kind (tutorial, how-to, reference or explanation) and opens with one sentence saying what it covers, then an example on the first screen (writing-for-humans rules 1–2).
• Each page uses one running example, declared once near the top and reused; each section shows only what changed (rule 3).
• Every code block has a lead-in sentence ending in a colon and a result sentence after it, and shows its result: printed output, or the asserted value inside the embedded snippet range (rules 7–8). Snippet end: markers sit below the assert or print that holds the result.
• Every copyable block either shows the async with engines.session(): wrapper or sits under a sentence that says it runs inside one and links to Connections › Sessions; the page's first block shows the wrapper.
• Every inline Python block that does real work runs under the harness ({test=run prelude=<name>}) or moves into an example script; a block left compile-only says why in its fence marker.
• Every lambda passed to a query method names its parameter after the model in lowercase singular (AGENTS.md I-8); python -m tests._docs_checks reports no violation for the owned files.
• Every error check in an owned example fails when the expected error is not raised (try/except/else: raise AssertionError, or the harness helper).
• Field-declaring examples show both declaration styles as tabs, each backed by a runnable script (AGENTS.md I-7), and the twins use the one Annotated idiom recorded in the docs conventions.
• Headings are short sentence-case noun phrases naming the feature (rule 5); how-to titles name the goal (rule 24); no minimising words (rule 17); admonitions follow rule 20.
• No ADR numbers, issue numbers, codenames, dated or release-bound notes, or contributor-only references in page text; version markers are self-contained blocks at the end of a section.
• Reference material that has a home in Reference is linked, not repeated; each topic ends with a pointer to its reference entry (rule 4).

Files owned

• Modify: docs/pages/guide/relationships.md, docs/pages/guide/raw-sql.md, docs/examples/raw_sql.py, docs/examples/relationships.py, docs/examples/relationships_annotated.py

Interfaces

• Consumes: docs conventions (AGENTS.md ticket (AGENTS.md: rewrite I-8 for the lambda-only query API, add a docstring invariant, record the docs conventions #703))
• Consumes: harness (harness ticket (Docs harness: run inline blocks with a prelude, run docstring examples, and check lambda names and error checks #704))
• Consumes: populated_relations pair as rewritten by the Queries ticket (Queries guide and the typed predicates concept page: lambda-only story, results shown, one running example #709)
• Produces: nothing other tickets rely on

Test scenarios

• Happy path: the strict site build succeeds and every snippet range on the owned pages renders without leading indentation.
• Happy path: every owned example script runs to completion under tests/test_docs_examples.py, and every inline block marked {test=run ...} runs.
• Error path: deleting the raise an owned example's error check expects makes that example's test fail.
• Edge case: python -m tests._docs_checks over the owned files exits 0; renaming one lambda parameter to t makes it exit 1 naming the file and line.

Verify

uv run --no-sync zensical build --clean --strict
uv run --no-sync pytest tests/test_docs_examples.py -q --no-cov -p no:cacheprovider -n 8
uv run --no-sync python -m tests._docs_checks docs/pages/guide/relationships.md docs/pages/guide/raw-sql.md docs/examples/relationships.py docs/examples/relationships_annotated.py docs/examples/raw_sql.py

Blocked by

• Docs site config: Zensical features, Markdown extensions, API reference options and a strict build #701, AGENTS.md: rewrite I-8 for the lambda-only query API, add a docstring invariant, record the docs conventions #703, Docs harness: run inline blocks with a prelude, run docstring examples, and check lambda names and error checks #704, Queries guide and the typed predicates concept page: lambda-only story, results shown, one running example #709

Audit findings