docs(#585): amend ADR-0005 decision to Accepted; open #627 for the meta-line gap

.wiki/Decisions-and-Roadmap.md

@@ -105,38 +105,45 @@ Two roadmap tracks are current:
   repaint extraction), Phase 6 #590 (implemented on `wip/590-reactive-workspace`
   — `app.currentWorkspace`/`app.mainSurface` are signal-backed accessor pairs,
   `dashboardTreeRevision` is retired; see `docs/ADR-0001-reactivity.md`'s #590
-  addendum), Phase 7 #585/ADR-0005 — **decided 2026-08-06: Rejected** (the
-  `@clickhouse/client-web` transport spike; independent of the shell track;
-  Phase 0 completed with no production cutover — see below). #592 (extend
-  `check-boundaries` to lock in the shell primitives) is a guardrail issue
-  alongside the phases. All are labeled `refactor`; re-check
-  `gh issue list --label refactor` for the current phase status before
-  planning shell work.
-- **#585 / ADR-0005 — Rejected (2026-08-06).** The Phase 0 validation spike
-  (`docs/ADR-0005-clickhouse-web-client.md`) compared
-  `@clickhouse/client-web@1.23.1` against the current custom transport over a
-  reusable parity/precision harness (`tests/spike/clickhouse-client/`) and
-  found three of ten hard gates fail: the supported-server matrix (both
-  proposed-oldest ClickHouse 24.8.x rows fail — a genuine, version-specific
-  meta-line gap in ClickHouse's own streaming JSON formats, predating
-  ClickHouse GitHub PR #74181, that affects the *current* production code
-  identically, not an official-client defect), the browser matrix (one
-  isolated but unclassified WebKit failure — deliberately NOT asserted as a
-  confirmed Docker-contention root cause, per a review finding that the
-  committed evidence didn't back that attribution — still recorded as a
-  failed row per the mechanical no-reinterpreting-a-flake-as-a-pass rule),
-  and net production-code deletion (mechanically estimated at negative,
-  see `docs/evidence/585/deletion-estimate.md` for the current figure). Phase
-  0 completed as a fully valid outcome — **no production cutover occurred**, and
-  `src/net/ch-client.ts` (the current custom transport) **remains
-  authoritative**. Phase 1 (separating application policy from the concrete
-  transport implementation) — **landed** on `wip/585-phase1-transport-seam`:
-  `src/net/clickhouse-transport.types.ts` (the `ClickHouseTransport` contract)
-  + `src/net/clickhouse-http-transport.ts` (`createHttpTransport`, the current
-  implementation behind it) put the existing transport behind a narrow seam
-  with zero behavior change; `ch-client.ts` keeps every auth/epoch/retry
-  policy and product operation. Phases 2–4 (production adoption, cutover, and
-  custom-transport deletion) do not proceed without a new decision.
+  addendum), Phase 7 #585/ADR-0005 — **decided 2026-08-06: Rejected, amended
+  2026-08-07: Accepted** (the `@clickhouse/client-web` transport spike;
+  independent of the shell track; Phase 0 completed, Phase 1 landed, Phase
+  2/3 now authorized — see below). #592 (extend `check-boundaries` to lock in
+  the shell primitives) is a guardrail issue alongside the phases. All are
+  labeled `refactor`; re-check `gh issue list --label refactor` for the
+  current phase status before planning shell work.
+- **#585 / ADR-0005 — Accepted (2026-08-06, amended 2026-08-07).** The
+  Phase 0 validation spike (`docs/ADR-0005-clickhouse-web-client.md`)
+  compared `@clickhouse/client-web@1.23.1` against the current custom
+  transport over a reusable parity/precision harness
+  (`tests/spike/clickhouse-client/`). The original 2026-08-06 run reached
+  Rejected on two of ten hard gates (a third, the browser matrix, was a
+  WebKit flake — root-caused as this sandbox's Docker-contention flakiness,
+  fixed via retries + honest flaky-cell recording (PR #624), and re-verified
+  clean 16/16): the supported-server matrix (both proposed-oldest ClickHouse
+  24.8.x rows fail — a genuine, version-specific meta-line gap in
+  ClickHouse's own streaming JSON formats, predating ClickHouse GitHub PR
+  #74181, that affects the *current* production code identically, not an
+  official-client defect — tracked as its own general compatibility bug,
+  independent of this ADR, by #627), and net production-code deletion
+  (mechanically estimated at -154 physical LOC). A 2026-08-07
+  decision-methodology amendment reclassified both as non-blocking — the
+  first because it fails identically for the current transport and the
+  candidate (not evidence against the candidate specifically), the second
+  because LOC delta alone is a narrow proxy for maintenance cost — and the
+  decision now computes as **Accepted** from the same underlying evidence
+  (see the ADR's "Decision-methodology amendment addendum"). `src/net/ch-client.ts`
+  (the current custom transport) **remains authoritative until Phase 3
+  cutover completes**. Phase 1 (separating application policy from the
+  concrete transport implementation) — **landed** on
+  `wip/585-phase1-transport-seam`: `src/net/clickhouse-transport.types.ts`
+  (the `ClickHouseTransport` contract) + `src/net/clickhouse-http-transport.ts`
+  (`createHttpTransport`, the current implementation behind it) put the
+  existing transport behind a narrow seam with zero behavior change;
+  `ch-client.ts` keeps every auth/epoch/retry policy and product operation.
+  Phase 2 (production official-client implementation) and Phase 3
+  (production cutover) **may now proceed**; Phase 4 (custom-transport
+  deletion) after Phase 3's own acceptance criteria are met.
 
 Re-read GitHub before acting because issue state can change; a MERGED PR is
 not proof its code is on `main` (see the reset above).

CHANGELOG.md

@@ -9,6 +9,28 @@ auto-generated per-PR notes; this file is the curated, human-readable history.
 
 ## [Unreleased]
 
+### Changed
+- **ADR-0005 amended: `@clickhouse/client-web` now Accepted (was Rejected).**
+  Clarified that the meta-line gap the original 2026-08-06 evidence run
+  counted as a failing gate is a general SQL Browser compatibility bug
+  (`src/core/stream.ts`'s missing meta-less fallback for ClickHouse servers
+  predating ClickHouse GitHub PR #74181), not a `@clickhouse/client-web`
+  defect — it fails identically for the current production transport, so it
+  isn't evidence against the candidate; tracked independently as #627.
+  Separately, a 2026-08-07 decision-methodology amendment demoted "net
+  production-code deletion" from a hard pass/fail gate to a measured metric
+  (LOC delta alone is a narrow proxy for maintenance cost) and narrowed
+  "supported-server matrix" to gate on current-generation ClickHouse rows
+  only. `tests/spike/clickhouse-client/run-matrix.mjs`'s `computeGates()` was
+  updated accordingly and evidence was recomputed from the same underlying
+  facts (no live matrix re-run) via the new
+  `tests/spike/clickhouse-client/recompute-decision.mjs`, flipping the
+  decision to **Accepted**. This authorizes #585 Phase 2 (production
+  official-client implementation) and Phase 3 (production cutover) to
+  proceed; production behavior is still unchanged as of this entry —
+  `src/net/ch-client.ts` remains authoritative until cutover. No `src/**`
+  code changed.
+
 ## [0.7.3] - 2026-08-06
 
 ### Added

README.md

@@ -782,6 +782,10 @@ 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