v2: filter verdicts become enforcement-grade (zero over-accept gate before 2.0.0) #567
Description
Decision (2026-10-07): from ABI v2, filter verdicts are meant to be usable as an enforcement control. That means read-side row-level security and per-record write checks. docs/limitations.md → "Filters are for comparison, not enforcement, for now" stays true until the gate below passes on a published v2 build. Only then is it lifted for v2, and the CHANGELOG says so, as that section already promises.
The contract v2 will publish:
- A
trueis a security claim. A filter answerstrueonly when the pinned server'sWHEREwould admit the row. An over-accept (atruewhere the server says false) is a security-severity defect. - Unknown and declined stay fail-closed. Any path that can't be sure declines rather than guessing. Callers enforcing with filters must treat anything but a definite
trueas "no". - Zero over-accepts is a release criterion. A known over-accept is fixed or declined before the next build ships; it's never carried as a known issue.
The gate before 2.0.0:
- A filter-vs-server differential in CI across every published ClickHouse line and platform, on every v2 build. It needs zero over-accepts and zero over-rejects, with declines listed rather than counted as agreement. The corpus includes adversarial cases from a downstream consumer that enforces with filters.
- No open filter divergences on the line. Today there is one, on 26.3: a non-UInt8/Bool filter on a schema that declares a projection. It's approved to become a decline.
Docs (this repo), once the gate passes on a v2 build:
- update
docs/limitations.md,docs/guides/filters.mdandspec/abi-v2/docs.mdwith the contract above; - restate the lift criterion for v2 (superseding the per-record served-field approach in docs: read the served per-(line, platform) enforcement state once the artifact producer serves it #360 if v2's registry makes it moot);
- add the CHANGELOG line.
v1 keeps the current wording until a v1 build passes the same gate.
Activity
EricAndrechek commentedon Oct 7, 2026
Two lines for the contract text when the gate passes. Both are binding-facing, and both already hold:
true" includes v2'sunknown(n)verdict member (spec rule r3), so a caller that maps an unknown verdict to a pass is wrong by contract.filter.a_closed_filter_is_never_passed_as_null(Rust by construction), and every released 1.x was measured refusing a closed filter on 2026-10-07.EricAndrechek commentedon Oct 8, 2026
For the lift text (ruled 2026-10-08; nothing changes until the lift): the security-grade filter commitment (zero over-accepts, zero over-rejects) covers the Linux artifacts. The macOS (darwin-arm64) artifacts stay a development floor, not an oracle, consistent with
docs/limitations.md's existing macOS section: their float parsing diverges by design (the 53-bit long double). The lift's wording must say so and cross-link that section.EricAndrechek commentedon Oct 8, 2026
Correction to my note above (2026-10-08): the commitment is NOT "Linux only". New measurements (official macOS ClickHouse binaries) show:
So the lift's wording is: the security-grade filter commitment (zero over-accepts, zero over-rejects) is the library against a ClickHouse server on the SAME platform. On 26.7+ all platforms agree. On 26.3, Float-literal and Float-parameter filters get a decline (coming from the artifact producer), and the library should run on the server's architecture. Cross-link
docs/limitations.md's macOS section, which is corrected in #580.EricAndrechek commentedon Oct 9, 2026
One more condition for the lift text (ruled 2026-10-09): the filter guarantee does NOT cover a ClickHouse server configured so that it refuses EVERY query. Documented examples:
max_expanded_ast_elements=1(36), andpage=1on 26.8/26.9 (36). The lift PR will:spec/abi-v2/where-settings/README.md, listing the documented pathological values;docs(limitations): name the first gate-passed build by its artifact b…
EricAndrechek commentedon Oct 9, 2026
Lifted on
v2by #589 (merge2877d6cd): filter verdicts are enforcement-grade against a ClickHouse server of the same line, operating system and CPU architecture, for builds that passed the artifact producer's standing filter differential. Artifact build20261009.074908(served on the v2-dev channel to SDK2.0.0-dev.4) is the first; the differential read12/12on it as published.26.3,26.7,26.8and26.9onlinux-amd64andlinux-arm64;26.7,26.8and26.9ondarwin-arm64. Each pair has its own CHANGELOG entry in all four bindings.26.3ondarwin-arm64. The macOS 26.3 server refuses deep nesting on its smaller thread stack where the library answers. A follow-up onv2states it as a documented platform limitation, with the measured band.spec/abi-v2/where-settings/documented-pathological.tsv), and the 26.3 float platform requirement.main, filters stay for comparison, not enforcement.The section is
docs/limitations.mdonv2.