[tae898]

Closes #293. Part of #289.

I added the user guide for columnar faceting, a test that runs every block of it, and a runnable example.

• docs/modules/ROOT/pages/how-to/facets.adoc (in the nav next to the COLUMNAR index page, linked both ways): what a facet is, the prerequisites (engine 26.12.1 or later, a COLUMNAR index), one runnable walkthrough on a ten-record data set for TERMS, RANGES, HISTOGRAM (calendar), FILTER (disjunctive), HIERARCHY, DISTINCT (with PRECISION), STATS, AFTER paging and facet.searchValues, the ResultSet.facets dict shape as a table, unavailable facets and their reason, the rows-first rule, parameters (named and positional; TOP and PRECISION take an integer literal), the older-engine refusal with a version check, and the known limits (negative zero, DISTINCT above PRECISION). The SQL texts and the asserted values come from tests/test_result_set_facets.py, tests/test_result_set_facets_kinds.py and tests/test_columnar_index.py. There is no speed claim, and no claim about a release beyond "needs engine 26.12.1 or later".
• tests/test_docs_facets_page.py runs the 19 Python blocks in order on one database, as the neighbouring page tests do, and compares each output block. A block that needs the new engine has the title "Needs engine 26.12.1 or later" and role=needs-engine. On an older engine the test asserts the documented refusal (SQL syntax error, or the COLUMNAR index type refusal) for that block instead of its output. There is no skip, and the page's own engine_version check is compared with the test's.
• examples/30_columnar_facets.py loads 1,200 generated products, creates the COLUMNAR indexes, runs three faceted queries and prints the rows and the facets. It checks every count against the same count made in Python. On an engine older than 26.12.1 it prints one line and exits 0. It is listed in examples/README.md and counted in README.md, which also gets one line in the feature list.
• The examples globs in test-python-examples.yml and test-native.yml ended at 2[0-9]_*.py, so a 30th example would never have run. They now include 3[0-9]_*.py.

Verified: compile() of both Python files, pyflakes, pre-commit (black, isort, actionlint, the old-package-name guard) and bandit on both files, and a dry extraction of the page blocks (19 blocks, 15 with output, 14 needing the new engine). Not verified: nothing was run against an engine on the laptop. The page test and the example run for real in CI, on the JVM lane against the latest snapshot and on the native gate against 26.11.1 (refusal branch). The outputs that were derived from the tests but not run before are the first ones to check if CI fails: the paging output on category (TOP 2, two pages), PRECISION 5 and PRECISION 10 on the price column, the tags terms and searchValues outputs on FacetDoc, and the three-facet combinations of the example.

🤖 Generated with Claude Code