fix(#627): support ClickHouse 24.8 meta-less result streams in Table view

.wiki/Architecture.md

@@ -71,7 +71,16 @@ module mocking.
    now calls the package's own stateless `killQuery` directly, and there
    is exactly one generic ClickHouse HTTP transport implementation left in
    the repository.
-3. `JSONStringsEachRowWithProgress` is folded line by line by pure stream logic.
+3. `JSONStringsEachRowWithProgress` is folded line by line by pure stream logic
+   (`core/stream.js`'s `applyStreamLine`). A `meta` line establishes named/
+   typed columns when the server sends one. **#627**: a meta-less first `row`
+   (ClickHouse 24.8 and earlier never emit `meta` for ordinary queries)
+   instead establishes name-only columns from that row's own keys, with the
+   unknown-type sentinel `type: ''` — never a value-based type guess. Row
+   values are stored in whichever order was established first, meta or not.
+   This fallback belongs to `core/stream.js` as SQL Browser result policy;
+   the package's own stream reading (`streamLines`) is unchanged and never
+   synthesizes metadata.
 4. Results resolve through the panel registry to table, chart, logs, KPI, filter,
    text, or graph-oriented renderers.
 5. One auth refresh is attempted for expired/denied tokens.

.wiki/Decisions-and-Roadmap.md

@@ -163,6 +163,15 @@ Two roadmap tracks are current:
   `Response`/rejection while the caller's `AbortSignal` controls the real
   fetch, or a deliberate renegotiation of the transport contract's
   cancellation semantics themselves.
+  **Current state (#627, landed):** the general meta-line compatibility bug
+  called out above is resolved — `core/stream.ts`'s `applyStreamLine` now
+  establishes name-only columns (`type: ''`) from the first row when a
+  stream never sends `meta`, instead of silently discarding every row.
+  ClickHouse 24.8 is now limited support: query execution and Table results
+  work; automatic typed-result parity (charts/KPI/logs/type-aware
+  formatting) remains outside the 24.8 guarantee, since those servers still
+  never provide result-type metadata. This is independent of ADR-0005, which
+  **remains Rejected**.
 
 - **#630 — extract the SQL Browser's own Fetch-native transport mechanics
   into a first-party package.** Independent of the #585/ADR-0005 track above

CHANGELOG.md

@@ -483,6 +483,13 @@ auto-generated per-PR notes; this file is the curated, human-readable history.
   changed at any point across either amendment.
 
 ### Fixed
+- **#627: preserve Table results from ClickHouse 24.8 streams that omit result
+  metadata.** The first meta-less row now establishes column names in response
+  object-key order with the explicit unknown-type sentinel `type: ''`, and
+  later rows retain that established order without value-based type inference.
+  Meta-first streams keep their existing typed behavior. ClickHouse 24.8 is
+  documented as limited support: query execution and Table results are
+  supported, while typed-result features may degrade when metadata is absent.
 - **#642: `check:arch`'s generic layering rules (and Rule B) now fail closed
   on a computed dynamic `import(...)` instead of silently skipping it.**
   `extractSpecifiers` (renamed `extractStaticSpecifiers`) used to include a

README.md

@@ -782,17 +782,25 @@ panel-sizing spec.
 
 The full system-requirements matrix — minimum browser versions, supported
 ClickHouse server versions, and IdP/OAuth requirements — is tracked in #71.
-A known ClickHouse-version compatibility gap that any such matrix needs to
-account for is tracked in #627: query results render silently empty on
-servers predating a 2025 ClickHouse streaming-format change (see
-`docs/ADR-0005-clickhouse-web-client.md`).
 
 One feature is narrower than the rest of the app: [**Export**](#export) needs
 the File System Access API, which today is **Chromium-only** (Chrome/Edge) over
 HTTPS or `localhost`. On Firefox, Safari, or plain HTTP, the Export button stays
 visible but disabled with a tooltip explaining why — no other feature is
 affected.
 
+## ClickHouse server compatibility
+
+**ClickHouse 24.8: Limited support — query execution and Table results are
+supported. Typed result features such as automatic charts, KPI
+interpretation, logs detection, and type-aware formatting may be unavailable
+because these servers do not provide result metadata in the streaming format
+used by SQL Browser.**
+
+SQL Browser does not infer ClickHouse result types from returned values. The
+exact first 25.x release that supplies the missing streaming metadata has
+not been established.
+
 ## Development
 
 For source development, testing, end-to-end checks, and release workflows, see

docs/ADR-0005-clickhouse-web-client.md

@@ -105,8 +105,10 @@ reason:
    `{"meta":[...]}` column-header line on ClickHouse 24.8 — that capability
    was added by ClickHouse GitHub PR #74181 ("JSONEachRowWithProgress format
    will include meta, totals, and extremes"), merged 2025-01-06, postdating
-   24.8. `src/core/stream.ts`'s `applyStreamLine()` has no meta-less
-   fallback, so every row silently maps to an empty/null value —
+   24.8. `src/core/stream.ts`'s `applyStreamLine()` had no meta-less
+   fallback at the time of this evidence (since fixed in #627 — see the
+   "#627 production compatibility follow-up" note below), so every row
+   silently mapped to an empty/null value —
    **identically** for the current transport and the candidate: on both
    24.8 rows, the live precision corpus shows `currentMatchesOfficial: true`
    (both adapters agree with each other) while both disagree with the
@@ -147,10 +149,22 @@ semantics. This ADR's final Rejected decision rests on that new finding,
 not on either of the two gates above (both remain exactly as characterized
 by the 2026-08-07 methodology amendment).
 
-**This does not mean ClickHouse 24.8 is newly supported.** #627 is
-unaffected by this decision either way — the current transport and the
-candidate share the identical meta-line defect, and fixing it is
-independent, ongoing work tracked on its own.
+**This did not mean ClickHouse 24.8 was newly supported at the time of this
+decision.** #627 was unaffected by this decision either way — the current
+transport and the candidate shared the identical meta-line defect, and
+fixing it was independent, ongoing work tracked on its own. See the
+"#627 production compatibility follow-up" note immediately below: that work
+has since landed.
+
+**#627 production compatibility follow-up:** ClickHouse 24.8 now has
+limited, data-safe support for ordinary query execution and Table results.
+When result metadata is absent, SQL Browser establishes column names from
+the first row and records the unknown ClickHouse result type as `type: ''`,
+preserving returned values without inventing type semantics. This resolves
+the production compatibility defect observed by the #585 spike. It does
+**not** adopt, authorize, or reopen `@clickhouse/client-web`; ADR-0005
+remains **Rejected**. The committed #585 matrix remains historical evidence
+of the pre-#627 behavior.
 
 **The current custom transport (`src/net/ch-client.ts`) remains
 authoritative — no cutover was ever attempted or is now authorized.** No
@@ -266,9 +280,11 @@ the "Decision" section above).
 `@clickhouse/client-web` need" — it does not, by itself, set or change SQL
 Browser's own general ClickHouse-version support floor. That remains a
 separate, open question: #71 tracks the documented support matrix, and #627
-tracks fixing the underlying meta-line bug this derivation surfaced, which
-affects the *current* transport regardless of this ADR's outcome or of
-which client SQL Browser eventually ships.
+tracked fixing the underlying meta-line bug this derivation surfaced (since
+fixed — see the "#627 production compatibility follow-up" note under
+"## Decision: Rejected" above), which affected the *current* transport
+regardless of this ADR's outcome or of which client SQL Browser eventually
+ships.
 
 ## Exact server matrix
 
@@ -858,10 +874,12 @@ surfaced that they fail for two very different *kinds* of reasons:
 - `supported-server matrix`'s failure is **symmetric**: the current
   transport and the candidate read back the same wrong (empty) values on
   24.8, because the root cause (`src/core/stream.ts`'s `applyStreamLine()`
-  has no fallback for a ClickHouse response that never sends a `meta`
-  line — a real, pre-existing, general SQL Browser defect, now tracked as
-  #627) lives entirely on the SQL Browser side, unrelated to which HTTP
-  client issues the request. A candidate that fails identically to the
+  had no fallback for a ClickHouse response that never sends a `meta`
+  line — a real, pre-existing, general SQL Browser defect, tracked as #627
+  and since fixed there; see the "#627 production compatibility follow-up"
+  note under "## Decision: Rejected" above) lived entirely on the SQL
+  Browser side, unrelated to which HTTP client issues the request. A
+  candidate that fails identically to the
   status quo isn't *worse* than the status quo on this axis — the original
   Phase 0 evidence run's mechanical rule (any required hard gate failing →
   Rejected) didn't distinguish "the candidate regressed something" from

docs/ARCHITECTURE.md

@@ -237,6 +237,20 @@ section below). A single automatic token refresh on 401/403/
 `authenticatedRequest()` (#630 Phase 6): before `authConfirmed` flips, an
 auth failure signs out; after, it is a query error.
 
+`applyStreamLine` normalizes both shapes a progress stream can take. A
+meta-first stream (a `{meta:[...]}` line before any row) establishes
+server-provided names/types directly. **#627**: if a `row` line arrives
+before any columns exist — ClickHouse 24.8 and earlier never emit `meta` for
+ordinary queries — SQL Browser establishes name-only columns from that
+row's object keys instead, using the unknown-type sentinel `type: ''`, and
+every subsequent row maps through that established name order. This
+fallback is SQL Browser result POLICY owned by `core/stream.ts`, not
+package protocol parsing — `packages/clickhouse-http` never synthesizes
+metadata; it only decodes whatever the server actually sent. Typed result
+consumers (chart auto-detection, KPI/logs interpretation, type-aware
+formatting) degrade to their existing generic/fail-closed behavior when a
+column's type is unknown, rather than inferring a type from values.
+
 ### Transport seam (#585 Phase 1) and the clickhouse-http package (#630 Phases 2-4)
 
 Generic request construction and stream mechanics are split out behind a

docs/evidence/585/README.md

@@ -4,4 +4,23 @@ Generated by `tests/spike/clickhouse-client/run-matrix.mjs`. See `decision-table
 the canonical hard-gate table (generated from `results.json`, never hand-edited),
 `results.json` for the full machine-readable evidence, and `critical-questions.md` /
 `support-minimum-analysis.md` / `deletion-estimate.md` / `compatibility-matrix.md` for the
-plan's named deliverables. Validate with `npm run check:client-spike:evidence`.
+plan's named deliverables.
+
+This directory is immutable historical #585 evidence. It was generated and validated by
+the then-present `tests/spike/clickhouse-client` tooling; that executable harness and its
+`check:client-spike:evidence` npm script were retired in #630 Phase 8. Do not regenerate
+these historical results. Current ClickHouse 24.8 production compatibility evidence for
+#627 lives in `../627/`.
+
+## Post-spike production follow-up
+
+* #585's pinned 24.8 rows correctly record the pre-#627 failure (see
+  `compatibility-matrix.md`) — those rows are truthful historical observations and are not
+  rewritten to "passed".
+* #627 is the independent production compatibility fix: `src/core/stream.ts`'s
+  `applyStreamLine()` now establishes name-only columns (`type: ''`) from the first row
+  when a stream omits `meta` entirely, instead of silently discarding every row.
+* Current live verification against the same two pinned 24.8 images lives in
+  `docs/evidence/627/`.
+* ADR-0005 remains **Rejected** — this follow-up does not adopt, authorize, or reopen
+  `@clickhouse/client-web`.