feat(typelayer)!: validate, coerce and filter through chtypes

[EricAndrechek]

Summary

WaveHouse stops modelling ClickHouse itself. Validation, coercion, DEFAULT substitution, row-level security and insert checks now run through chtypes (github.com/wave-rf/chtypes/go v0.5.1, ABI revision 6). chtypes is a cgo dlopen of a per-ClickHouse-version library that runs the server's own parser and analyzer in-process. /v1/query and pipes ask ClickHouse to render their results. The Go that approximated ClickHouse is deleted.

This redoes #589 on current main, which is now multi-tenant. #589 stays open as a draft reference on the old main.

Fixes #387 (timestamp filters and time_range shifted on non-UTC columns), fixes #516 (the TS SDK's client-side stream filters compared timestamps as text), fixes #547 (the dedupe walkthrough posted a column clicks lacks), fixes #558 (discovery now warns on tables without DDL; the second half is moot because the type layer reconstructs column declarations from system.columns and never reads create_table_query).

Breaking, by design:

• cgo is unconditional; there is no pure-Go build.
• Release platforms narrow to linux/amd64, linux/arm64 and darwin/arm64, and Linux binaries need glibc ≥ 2.34.
• A process with the api role refuses to start when no chtypes artifact is installed.
• Several documented behaviours become "whatever ClickHouse does". They are listed below.

What changed

Type layer (internal/typelayer). One process-wide engine holds one lazily opened chtypes registry. Each tenant gets its own table set, bound from that tenant's schema refresh before the registry reports loaded and forgotten when the tenant is removed or moves.

• Pool size: each base table compiles one handle and grows on demand up to min(GOMAXPROCS, 8); each role shape grows the same way up to min(GOMAXPROCS, 4).
• Refusing a tenant: a tenant is refused on its own, and every other tenant keeps working, when:
  • its ClickHouse line has no installed artifact, or
  • its server time zone differs from the zone this process already opened that line with. chtypes fixes a library's zone at first open, so one process serves one zone per line.
• Roles: only api-role processes load chtypes. Ingest-worker and sweeper processes need no artifact.
• Compile profile: carries ClickHouse's type gates, so tables with LowCardinality(<integer>), long FixedString and Variant columns ingest and filter.

Ingest. The request body goes to chtypes as-is: one RowsExportWith call per body, with the role's check clauses as a row filter. Each record's parse outcome and check verdict come back together, so there is no Go decode, no re-encode and no second parse.

• Published bytes: the published row is ClickHouse's own writer output, carrying the inserting role's wire columns.
• Formats: Content-Type declares the format:
  • the JSON family;
  • text/csv and text/tab-separated-values, with RFC 4180's header parameter mapped three ways: present → CSVWithNames/TSVWithNames, absent → positional with header detection off, no parameter → ClickHouse's default detection.
• Dedupe: main's windowed reserve/publish/commit is unchanged. A null or empty id cell counts as missing.

Errors. Bodies keep main's string code class. ClickHouse's numeric code travels as exception_code, both on a whole-request parser refusal (code: "clickhouse.rejected") and on each per-record result.

Query path. /v1/query and pipes go over HTTP to the tenant's target with FORMAT JSONEachRow. Failures are typed chconn.HTTPErrors, so the per-class error mapping is unchanged.

• Fixed settings on every read:
  • wait_end_of_query=1
  • http_write_exception_in_output_format=0
  • a server-side max_execution_time
  • cancel_http_readonly_queries_on_client_close=1
  • readonly=2
  • pinned JSON rendering settings, including date_time_output_format=iso so DateTime is RFC 3339 UTC on every surface
• Write pipes: keep IsMutation routing; they are never cached.
• Cache key: carries a rendering marker, so old and new builds never share an entry.
• Connections: each tenant's HTTP connections are capped at its max_open_conns.

Timestamp filters. Before this change, an RFC 3339 filter value and the time_range bounds were rewritten in Go to zone-less UTC text, and ClickHouse read that text in the column's zone. On any non-UTC column, results were off by the offset. Measured with the server in Europe/Berlin: a DateTime('Asia/Tokyo') column matched nothing, and a DateTime64(3,'America/New_York') column matched the row 4 hours late.

• Fix: ClickHouse now parses the value itself: col OP parseDateTime64BestEffort({p:String}, 8[, '<column zone>']).
• Verified on 26.8 and 24.8: every column returns the right rows, the primary key is still used, and an unparseable value is a 400.

in lists. They travel as ClickHouse external-data tables in a multipart body instead of as URL parameters, which ClickHouse caps at about 128 KiB per value. A 1.26 MiB, 60,000-element list goes through, and the primary key is still used through IN (SELECT …).

Integer claims. A claim bound as {p:String} and compared with an integer column wraps modulo 2^64 (at their own width for 128/256-bit columns), on the server and in chtypes alike. Row filters, insert checks and the /v1/query policy predicate now compare integer columns against a round-trip strict cast:

if(toString(accurateCastOrNull({p:String}, 'T')) = {p:String}, accurateCastOrNull({p:String}, 'T'), NULL)

• In range: a canonical claim answers exactly as before and keeps the primary key in use.
• Out of range or non-canonical: a claim like 007, +5, 1.0 or ≥ 2^64 matches no row and fails an insert check with 403.

Stream. Row filters run through chtypes over the published bytes.

• Narrower rows: a row published by a column-restricted role is evaluated with its own column list.
• Absent columns: a filter over a column the event doesn't carry withholds the row for that reader. The server computes that column again at insert, so judging the stream's copy could let through a row /v1/query excludes.
• Withheld-row metric: labelled by reason (filter, error, decline, unavailable, drift).

Build, CI and release.

• CGO_ENABLED=1 everywhere, go 1.27, golangci-lint v2.13.2.
• glibc builder plus distroless/cc runtime that bakes the pinned artifact (chtypes.lock, scripts/fetch-chtypes.sh --frozen).
• Native-runner release builds per target.
• CI, dev and test ClickHouse move from 26.6.3.62 to 26.8.15.10. chtypes has retired 26.6, and 26.8 is the longest-supported line. The lock pins the exact matching 26.8 build.

Deleted:

• Go-side validation and timestamp canonicalization (internal/discovery/{validation,timestamp}.go).
• The Go row-filter and numeric code (internal/policy/{rowfilter,numeric}.go, LiteralValue, CanonicalNumericLiteral, RowVisible).
• The compact encoder (internal/ingest/compact.go).
• The native-driver result transformer.
• Every CGO_ENABLED=0 path.

Size, measured. Production Go (non-test .go outside tests/) goes from 35,889 to 39,145 (+3,256). The migration trades hand-written ClickHouse modelling for a wrapper around the real thing, and adds per-tenant lifecycle, the HTTP reader and external-data in lists; it does not shrink the codebase lines.

Documented contract changes (please review these first)

surface	before	after
denied insert column	403 column "x" not allowed for insert	400, exception_code 117 (does not reveal whether the column exists)
unknown field / ALIAS / MATERIALIZED supplied	WaveHouse wording	400, exception_code 117
EPHEMERAL column supplied	accepted	accepted where the format names columns (JSON, *WithNames) and a DEFAULT reads it; otherwise 400/117 (positional CSV/TSV carry wire columns only)
_eq check value supplied for a column the role may not write	403	accepted when it equals the claim; injected when omitted
role whose column policy cannot be compiled for the table	n/a	500 retryable:false, no Retry-After; cause logged
JSON array body with content after the closing ]	the tail was ignored	400
JSON array with an empty element ([a,,b], leading or trailing comma)	accepted	400 invalid json
a body whose records ClickHouse's reader cannot separate (e.g. a malformed UUID swallowing the next records)	n/a	every counted record 422, nothing published (ClickHouse itself would silently store a subset under input_format_allow_errors_ratio)
parse error and check failure on one record	403	the 400 with ClickHouse's code
out-of-range or non-canonical integer claim on an integer column	wrapped, or matched	matches no row on a read; 403 on an insert check
text/csv / text/tab-separated-values ingest	415	accepted, with the three-way header mapping
unparseable timestamp on ingest	accepted at the edge, failed at the worker	400 with ClickHouse's code at the edge
bare JSON number in a DateTime64 column	read in the column's units	whatever the server does; on 26.8 that is epoch seconds (epoch milliseconds clamp to 9999-12-31)
unavailable tenant on ingest	n/a	503, Retry-After: 5, generic body; cause in logs only
/v1/query and pipe rendering	Go json.Marshal: alphabetical keys, Decimal as string, NaN/Inf fail the request	ClickHouse JSONEachRow: SELECT order, Decimal as number, NaN/Inf as null; DateTime stays RFC 3339 UTC (date_time_output_format=iso), now at the column's scale (.000Z, not trimmed)
/v1/query and pipe response over 64 MiB	uncapped	502 clickhouse.response_too_large
/v1/query null filter value	silent empty result	400
/v1/query timestamp filter / time_range on a non-UTC column	off by the zone offset	the exact instant
/v1/query in element that isn't a value of the column's type	400	matches no row
row-filtered SSE reader whose filter uses a column the inserting role can't write	Go evaluated the padded row	withheld (decline)
SSE / wire timestamps	RFC 3339 UTC, trailing zeros trimmed	RFC 3339 UTC rendered by ClickHouse at the column's scale; events published before the upgrade replay in the old spelling

Verification

• make ci passed on this exact tree: Go unit 3,635 (-race), integration 532 + 101, e2e 95 (1 skipped), TS SDK 246, Go total coverage 94.8%. No threshold was lowered.
• Stream-vs-query differential: 8,838 cells, comparing stream row-filter verdicts with the production /v1/query answer. It covers every column shape × operator × claim, including hostile spellings and integer claims at and beyond every width. Zero disagreements.
• Live filter-value test against ClickHouse 26.8.15.10 and 24.8.14.39 covering timestamp columns in three zones, time_range, and an external-data in list. It fails if the zone or the cast is removed.
• Tenancy tests:
  • two tenants on one line with different zones: only the second is refused;
  • a missing line affects only that tenant;
  • Forget never blocks a reload hook;
  • binds racing tenant removal never resurrect a removed tenant.
• An ingest-only process boots with no artifact installed, and an api process refuses to.
• Role-shape compiles run outside the role cache's lock (300 distinct _eq claims on one table: 113 µs → 19 µs per request) and every parser handle keeps the full filter cache (600 distinct subscriber claims: 22.9 µs → 3.4 µs per evaluation); both are pinned by benchmarks in internal/typelayer.
• The repo's pre-push reviewers (code and docs, fresh context each round) were run to ship_it on this tree.

Known limitations (waiting on chtypes)

• A table whose column has a volatile DEFAULT such as generateUUIDv4() declines every record that omits that column (422, the whole batch), because chtypes declines non-deterministic expressions rather than guess them; on main ClickHouse generated the value at insert. Measured on the 26.8 artifact. Waiting on chtypes to generate volatile defaults (tracked upstream).
• Float NaN/±Inf read back as null on /v1/query and pipes but as the strings "nan"/"inf"/"-inf" on the stream, because chtypes' export ignores output_format_json_quote_denormals. Documented; waiting on the upstream parity fix.
• A table CHECK whose expression is non-zero but not exactly 1, or not UInt8 (e.g. CHECK x with x = 2) is accepted at ingest but refused by the server at insert (469 / code 1). The worker parks the row, but the stream may already have delivered it. Write CHECKs as explicit comparisons (x > 0). Waiting on the upstream fix.
• A malformed UUID in a batch declines the whole batch (422): ClickHouse's reader swallows the records after it, and WaveHouse refuses rather than report a short batch. Waiting on chtypes to report swallowed records (tracked upstream).

First-run risks on GitHub

• artifacts.wavehouse.dev is a CI dependency on a cold artifact cache. The channel is append-only, so the locked build stays fetchable.
• First use of ubuntu-24.04-arm and macos-latest (advisory release-validation job).
• CodeQL's default setup builds go1.27 with cgo (not a required check).

Follow-ups (not in this PR)

• On ClickHouse lines before 26.5, a policy claim in RFC 3339 form compared with a DateTime column is refused (code 53); 26.5 and later accept it because cast_string_to_date_time_mode defaults to best_effort (measured on 26.8.15.10). Parsing claims explicitly would need the /v1/query and stream renderers changed together.
• /v1/ops/query does not pin wait_end_of_query=1 / http_write_exception_in_output_format=0 like the other read paths, so a statement failing mid-stream can return a 200 with truncated JSON (unchanged from main).
• select_all for a column-restricted role expands to every schema column, EPHEMERAL included, which ClickHouse refuses to SELECT (inferred, unchanged from main).
• A READONLY (code 164) refusal on /v1/ops/query and write pipes is still classed as unavailable (503, retryable), unchanged from main; the read paths map it to 502 clickhouse.misconfigured.
• Serving several server time zones on one ClickHouse line in one process needs one registry per zone over a real artifact copy. Trigger: the first tenant refused for a zone mismatch.
• Share compiled tables across tenants on the same (address, database). Trigger: tenants × tables × pool memory over budget.
• The ingest record-count guard takes the lower of two readings for a BOM-led CSV/TSV body whose first column is an Array, Map, JSON, Dynamic, Tuple or Variant holding a string, so a malformed UUID there can still yield a short batch; such first columns should be classified like String.
• A caller's own /v1/query in elements on a 128/256-bit integer column go through plain accurateCastOrNull, which wraps at the column's width. Caller filters only narrow what policy admits, but the strict cast could cover them too.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 01aefaf0-2d34-4c05-aa14-00be5830b5f8

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

📚 Docs preview is live → https://3f66f5e1-wavehouse-docs.wave-rf.workers.dev

• Commit — a318830: fix(ingest): read BOM- and form-feed-led bodies the way ClickHouse does
• Author — @EricAndrechek, Claude Opus 5.5
• Committed — 2026-10-01 14:30 (UTC-04:00)
• Deployed — 2026-10-01 14:51 EDT

[github-code-quality]

Code Coverage Overview

Languages: Go

Go

The overall line coverage in commit a318830 in the chtypes-v2 branch is 92%. The line coverage in commit 32e03a0 in the main branch is 93%.

Show a line coverage summary of the most impacted files.

File	main 32e03a0	chtypes-v2 a318830	+/-
internal/typelayer/ingest.go	0%	79%	+79%
internal/api/cl...ckhouse_http.go	0%	88%	+88%
internal/typelayer/records.go	0%	90%	+90%
internal/typelayer/filter.go	0%	91%	+91%
internal/typela...er/roletable.go	0%	93%	+93%
internal/api/sql_classify.go	0%	93%	+93%
internal/typela...er/typelayer.go	0%	94%	+94%
internal/query/bind.go	0%	95%	+95%
internal/api/content_type.go	0%	95%	+95%
internal/api/ingest_framing.go	0%	98%	+98%