Epic: extract the Fetch-native ClickHouse client into a reusable package

[BorisTyshkevich]

Phases

• 1 — freeze native Fetch, Response, and cancellation semantics
• 2 — create @altinity/clickhouse-http and move low-level request/URL mechanics
• 3 — extract progress-stream and late-exception protocol primitives
• 4 — add consuming query APIs, ClickHouse errors, and stateless KILL QUERY
• 5 — extract ClickHouse SQL quoting and type-expression grammar
• 6 — simplify SQL Browser authentication integration around the package
• 7 — migrate query execution and export, then delete generic client mechanics
• 8 — stabilize the standalone package boundary and remove migration scaffolding

/ship owns this checklist and should tick a phase only after that phase's PR is merged and verified on origin/main.

Goal

Replace the rejected @clickhouse/client-web adoption path from #585 with a first-party, Fetch-native ClickHouse client package extracted from generic protocol code SQL Browser already maintains.

The package must preserve the behavior that made the official-driver adaptation unsuitable:

• low-level request returns the exact native Response from fetch();
• HTTP non-2xx responses resolve normally at the low-level boundary;
• response bodies are never consumed unless the caller explicitly chooses a consuming API;
• caller SQL is transmitted unchanged;
• caller-provided Authorization is opaque and emitted unchanged;
• the caller's own AbortSignal controls the real request for the entire response-body lifetime, including after headers arrive;
• raw/binary bytes are never forced through text decoding;
• ClickHouse progress streams and late-exception framing are reusable protocol primitives.

SQL Browser keeps application policy: OAuth/Basic credential acquisition, refresh, credential epochs, connection lifecycle, operation ownership, retry policy, per-tab session policy, result/view policy, product SQL, export UX, and workbench/dashboard state.

This is an architectural refactor. User-visible behavior and persisted formats must remain compatible.

/ship execution

This issue is intentionally phased in the format consumed by skills/ship.

Run:

/ship 630

or:

/ship 630 --planner chatgpt

Each phase is one /ship unit: approved plan, branch, PR, code-review certification, merge, checklist/ship-log reconciliation, then automatic continuation from freshly fetched origin/main.

The phases form one ordered dependency spine. There is no authored decision gate between them.

Why Phase 8 exists separately from #639

Phase 8 and #639 deliberately operate on opposite sides of a repository boundary.

Phase 8 is still entirely inside altinity-sql-browser

It proves that the extracted package is no longer architecturally dependent on SQL Browser before any cross-repository move occurs. It owns:

• package-local build/typecheck/test scripts;
• built ESM and TypeScript declaration surface;
• npm pack and isolated tarball install/import/typecheck proof;
• removal of temporary compatibility adapters/re-exports left by Phases 2–7;
• removal of the rejected @clickhouse/client-web dependency and obsolete executable spike wiring;
• architecture guards preventing package→SQL Browser imports and SQL Browser deep imports into package internals;
• final in-repo ownership cleanup and architecture/ADR/wiki/changelog documentation;
• a tested handoff document describing how to extract the package repository.

At the end of Phase 8, the package can be moved without changing its architecture or API, but it still physically lives under packages/clickhouse-http in this repository.

#639 is the actual cross-repository move and release

#639 starts only after Phase 8 is shipped. It owns:

• creating Altinity/clickhouse-http;
• moving package source/history into that repository;
• adding standalone repository CI/release plumbing;
• publishing/releasing a version;
• changing SQL Browser from workspace dependency to released semver dependency;
• deleting the workspace copy only after the external package passes SQL Browser integration/e2e tests.

The separation is intentional because the current /ship skill is scoped to altinity-sql-browser. If Phase 8 were removed, #639 would combine unresolved architecture cleanup, package isolation, repository creation, release, and consumer cutover in one cross-repository operation. That would make rollback and review substantially harder and would move architecture decisions outside the repo-scoped /ship proof loop.

If the future cross-repository shipping workflow can provide the same plan/review/test/rollback guarantees across both repositories, Phase 8 could theoretically be folded into #639. With the current tooling, keeping the in-repo stabilization phase is the safer boundary.

Architecture decision

If behavior answers “how does ClickHouse HTTP / Fetch work?”, it belongs in the package. If it answers “what should SQL Browser do?”, it stays in SQL Browser.

SQL Browser application policy
            |
            v
 @altinity/clickhouse-http
            |
            v
          Fetch
            |
            v
        ClickHouse

The package must never depend on SQL Browser application, UI, state, auth, workspace, dashboard, or editor modules.

Final ownership boundary

@altinity/clickhouse-http owns

• endpoint/URL construction;
• default_format, ClickHouse settings and caller-supplied query/protocol parameters;
• direct fetch() invocation;
• opaque Authorization emission;
• caller AbortSignal passthrough;
• native Response low-level API;
• non-consuming HTTP success/error classification;
• explicit JSON/text/progress response consumers;
• ClickHouse HTTP exception parsing;
• progress-bearing JSON-lines decoding;
• X-ClickHouse-Exception-Tag / __exception__ late-exception framing;
• stateless KILL QUERY wire operation;
• ClickHouse SQL string/identifier quoting;
• generic ClickHouse type-expression AST/parsing/canonicalization.

SQL Browser owns

• OAuth discovery/PKCE/login/token storage;
• Basic-auth probing and auth-mode selection;
• token refresh and refresh single-flight;
• credential epochs and stale-work fences;
• login rejection versus query-level 401/403 classification;
• connection lifecycle state;
• owner-scoped AbortController lifecycle;
• authenticated execution scopes and frozen cancellation leases;
• retry decisions (SESSION_IS_LOCKED, safe read retry, non-idempotent uncertainty);
• per-tab logical-session policy;
• logical result modes (Table, KPI, etc.) and format/settings mapping;
• row caps and UI result accumulation;
• schema/catalog/documentation/lineage/capability SQL;
• workbench/dashboard behavior;
• export file picker/progress/.partial UX.

Hard invariants

1. Native response identity. Low-level request returns response === fetchResponse, including non-2xx.
2. No hidden body consumption. Low-level request leaves bodyUsed === false.
3. One Fetch invocation. No transport retry, credential lookup, or hidden request.
4. Exact SQL. No trim, trailing-semicolon removal, format rewriting, comment rewriting, or body normalization.
5. Opaque Authorization. Complete string emitted unchanged and never cached between requests.
6. Live endpoint/fetch dependencies. Next request observes current accessors.
7. Native cancellation lifetime. Caller signal controls actual Fetch and post-header body lifetime; no derived-signal bridge may sever it.
8. Cancellation isolation. Aborting A cannot affect B.
9. Raw-byte safety. Raw/export/binary paths never require UTF-8 decoding.
10. Single protocol owner. At completion, generic URL/stream/error/request mechanics have one implementation: the package.
11. Application policy stays out. Package cannot refresh credentials, publish lifecycle state, own operation registries, decide retries, or understand SQL Browser views.
12. Single artifact remains. SQL Browser still builds one self-contained dist/sql.html.
13. Auth authority remains fenced. Credential awaits and async auth-body inspection remain bound to the captured credential epoch.
14. Raw success can stay raw. Export can classify HTTP success/error without consuming a successful response body.

---

Delivery phases

Phase 1 — freeze native Fetch, Response, and cancellation semantics

Characterization/test-infrastructure phase only. Do not refactor the transport.

Strengthen the existing transport contract and real-browser fault harness to prove:

• exactly one injected fetch call, including pre-aborted input;
• strict native Response identity;
• non-2xx resolves with untouched body;
• exact SQL including whitespace/comments/trailing semicolon/authored FORMAT;
• opaque Bearer/Basic/custom Authorization;
• raw invalid-UTF-8 bytes remain byte-identical;
• current URL serialization/encoding including zero/empty values where supported;
• live origin() and fetch() accessors;
• pre-aborted signal invokes the injected fetch but does not reach the real server;
• abort while awaiting headers => AbortError;
• after headers, request stays resolved but aborting the original signal makes an in-progress body read reject AbortError;
• no later stream callbacks after observable cancellation;
• concurrent request remains unaffected;
• abort after full body completion has no effect.

The post-header proof must execute end-to-end in Chromium and WebKit using the real browser Fetch stack; an already-errored synthetic ReadableStream is insufficient.

Claims: A1, A3.

Phase 2 — create @altinity/clickhouse-http and move low-level request/URL mechanics

Create packages/clickhouse-http as a private npm workspace package with zero runtime dependencies and public package-name imports.

Expose a low-level client equivalent to:

interface ClickHouseHttpRequest {
  sql: string;
  defaultFormat: string;
  settings?: Record<string, string | number>;
  params?: Record<string, string | number>;
  authorization: string;
  signal?: AbortSignal;
}

interface ClickHouseHttpClient {
  request(request: ClickHouseHttpRequest): Promise<Response>;
}

Move current chUrl() behavior into one authoritative package serializer. Preserve default_format, enable_http_compression=1, settings and existing caller-supplied protocol/query parameters exactly.

Keep the old transport only as a temporary compatibility adapter delegating send() to package request(); stream reading remains local until Phase 3.

Add architecture checks forbidding package imports from root src/** and SQL Browser deep imports into packages/clickhouse-http/src/**.

Claims: A2, A4, A5.

Phase 3 — extract progress-stream and late-exception protocol primitives

Move generic protocol mechanics, not SQL Browser result state.

Package owns:

• progress line shape (meta, row, progress, exception);
• incremental UTF-8 decoder/newline buffering/malformed-line behavior;
• per-network-chunk callback semantics;
• parseExceptionText();
• tagged late-exception framing;
• legacy final-tail exception fallback;
• byte-accurate clean-data boundary.

Expose byte-oriented exception framing such as:

findExceptionFrame(tailBytes: Uint8Array, tag?: string | null)
  => { message: string; cleanBytes: number } | null

Keep StreamResult, row caps, percentages, raw/result presentation state, editor caret extraction and auth-expiry UI policy in SQL Browser.

No duplicate stream/error implementation remains behind compatibility wrappers.

Claims: A6, A7.

Phase 4 — add consuming query APIs, ClickHouse errors, and stateless KILL QUERY

Preserve low-level request() unchanged.

Add explicit higher layers:

ensureClickHouseSuccess(response): Promise<Response>
consumeJsonResponse<T>(response): Promise<T>
consumeTextResponse(response): Promise<string>
consumeProgressResponse(response, callbacks?): Promise<Response>

ensureClickHouseSuccess returns the same successful response without consuming it; only non-2xx consumes error text and throws minimal ClickHouseError.

Add convenience queryJson, queryText, queryProgress composed from exactly one request plus one consumer. They must not know SQL Browser modes such as Table/KPI.

Add stateless killQuery({queryId, authorization, ...}): safely quoted, ASYNC, one request, no registry/retry/credential lookup.

Abort/network/body-reader errors must remain native rather than being wrapped as ClickHouse errors.

Claims: A8, A9.

Phase 5 — extract ClickHouse SQL quoting and type-expression grammar

Move reusable pure ClickHouse language helpers into the package:

• string-literal quoting;
• identifier quoting and qualification;
• generic ClickHouse type-expression AST/parser/canonicalization/wrapper analysis/enum inspection.

Preserve current grammar/test behavior for nested types, literals, Tuple, Enum8/Enum16, Nullable, LowCardinality, arrays, malformed input, wrapper ordering and canonicalization.

killQuery must use the same public string-literal helper.

Keep SQL Browser display formatting, FORMAT detection/preparation, parameter-control policy and Dashboard/UI decisions outside the package.

No duplicate scanner/parser/quoter may remain.

Claims: A10, A11.

Phase 6 — simplify SQL Browser authentication integration around the package

High-risk trust-boundary phase.

Create one SQL Browser-owned authenticated request module that composes credential/epoch/lifecycle policy over package request() and package response consumers.

Preserve:

• epoch captured before first await;
• settings/params snapshot before credential await;
• URL/preparation failure timing before token lookup;
• epoch fence after every credential-related await and cloned error-body read;
• final epoch fence immediately before actual request side effect;
• complete Authorization computed per attempt;
• at most one auth refresh retry;
• post-confirmation 401/403 remain query outcomes, not sign-out;
• only current 2xx reports connected;
• only current non-abort network rejection reports offline;
• stale work never mutates replacement lifecycle state;
• original caller AbortSignal reaches actual Fetch with no derived controller/listener bridge;
• frozen cancellation lease path does not read mutable tokens/refresh/lifecycle.

ChCtx and cancellation leases remain SQL Browser-owned.

Real-browser cancellation tests must run through the authenticated path, not only the raw package client.

Claims: A12, A13.

Phase 7 — migrate query execution and export, then delete generic client mechanics

Move application consumers off legacy runQuery / exportQuery / ordinary transport helpers.

QueryExecutionService keeps SQL Browser policy:

• Table/KPI/TSV/raw format mapping;
• row-limit settings;
• fresh query ID per attempt;
• SESSION_IS_LOCKED retry;
• safe read network retry;
• no automatic retry for uncertain non-idempotent work;
• script stop-on-first-failure;
• owner-scoped cancellation.

ExportService keeps file picker/progress/.partial UX but uses authenticated native Response, package success classification, direct byte streaming, and package findExceptionFrame on retained tail bytes.

Successful raw export must never use response.text().

After all callers migrate, delete superseded generic runQuery, exportQuery, ordinary mutable-context killQuery, old transport stream plumbing and transport seam files when no architectural purpose remains. Keep only SQL Browser product operations/thin authenticated helpers and frozen-lease cancellation policy.

Run full e2e plus Chromium/WebKit cancellation/export streaming proof.

Claims: A14, A15, A16.

Phase 8 — stabilize the standalone package boundary and remove migration scaffolding

This phase does not create another repository and does not publish a release. Its purpose is to leave altinity-sql-browser in a clean state where repository extraction is mechanical.

Make packages/clickhouse-http independently buildable and packable inside the current repository:

• built browser-first ESM;
• TypeScript declarations;
• package-local build, test, check:types scripts;
• no root-source imports or workspace-only type resolution;
• publication-shaped exports, files, license and version metadata;
• no runtime dependency unless explicitly introduced earlier.

Add deterministic isolated-package proof:

1. build package;
2. npm pack;
3. inspect tarball contents;
4. install tarball into a temporary fixture outside the workspace package tree;
5. import it as ESM;
6. compile a TypeScript consumer against its declarations;
7. prove resolution does not fall back into SQL Browser src/**.

Then remove migration scaffolding:

• compatibility-only package/root aliases and transport wrappers no longer needed after Phase 7;
• @clickhouse/client-web dependency and executable vendor-spike wiring;
• stale import maps/scripts referring to rejected adoption.

Retain ADR/evidence history for #585 and reuse/rename generic browser fault scenarios as first-party package regressions.

Strengthen architecture guards for:

• package→SQL Browser imports;
• SQL Browser package deep imports;
• regrowth of a second generic request/URL implementation;
• regrowth of duplicate progress/late-exception parsers;
• accidental reintroduction of @clickhouse/client-web without a new decision.

Update package README, docs/ARCHITECTURE.md, CLAUDE.md, relevant .wiki, ADR-0005 addendum and CHANGELOG.md. Add docs/clickhouse-http-repository-extraction.md as the tested handoff for #639.

At Phase 8 completion the package still lives in this repository, but its source/API/build/test boundary is ready to move unchanged.

Claims: A17, A18.

---

Tests

Every phase must leave the full repository gate green:

npm run check:types
npm run check:arch
npm run check:schemas
npm run check:examples
npm test
npm run build

Phase 1

Run the targeted Chromium/WebKit fault/cancellation suite. Cover pre-abort, awaiting headers, post-header body abort, concurrent isolation, exact Response identity, raw bytes, SQL/Auth/URL fidelity.

Phase 2

Run package/request contract tests plus relevant e2e because workspace/dependency wiring changes.

Phase 3

Test split/multi-line chunks, UTF-8 split boundaries, malformed lines, trailing remainder, reader error identity, tagged/legacy exception framing, false-positive resistance and invalid-UTF-8 clean bytes.

Phase 4

Test successful non-consuming classification, JSON/text/progress consumption, ClickHouseError on non-2xx, native abort/body errors, one-request convenience APIs, and KILL QUERY quoting/state isolation. Re-run real-browser post-header cancellation.

Phase 5

Run the complete existing type-parser corpus plus quoting edge cases and affected parameter/KPI/dashboard-variable consumers.

Phase 6

Run all auth/epoch/refresh/lifecycle race tests and Chromium/WebKit post-header cancellation through the authenticated path.

Phase 7

Run QueryExecutionService retry/result mapping tests, ExportService raw-byte/late-error/partial-file/cancellation tests, full e2e, and real-browser export cancellation after headers.

Phase 8

Run package-local build/type/test, npm pack, isolated ESM import, isolated TypeScript compile, architecture sabotage tests, root full gate, full e2e, and renamed first-party Chromium/WebKit package regression suite.

Global acceptance criteria

• A1 Native Fetch/Response/cancellation contract is characterized in unit and Chromium/WebKit tests.
• A2 @altinity/clickhouse-http exists as an in-repo package with no SQL Browser source imports.
• A3 Low-level request preserves native Response identity, exact SQL/Auth, raw bytes, one Fetch call and caller-signal lifetime.
• A4 SQL Browser consumes the package through public package exports.
• A5 URL serialization has one package implementation.
• A6 Progress-stream decoding has one package implementation while SQL Browser retains result/view state.
• A7 ClickHouse HTTP and late exception parsing/framing are package-owned and byte-safe.
• A8 Explicit non-consuming and consuming response APIs exist with a minimal ClickHouse error model.
• A9 Stateless package KILL QUERY exists without credential lookup/retry/registry ownership.
• A10 ClickHouse SQL quoting has one package implementation.
• A11 Generic ClickHouse type grammar/parser/canonicalization has one package implementation.
• A12 SQL Browser authentication is composed through one authenticated request layer over package request().
• A13 Epoch/refresh/lifecycle/cancellation/frozen-lease invariants remain regression-tested and unchanged.
• A14 QueryExecutionService owns logical format/cap/retry policy and no longer owns generic HTTP/stream mechanics.
• A15 ExportService streams native bytes and uses package late-exception framing while retaining export UX/policy.
• A16 Superseded generic transport/client mechanics are deleted rather than retained as a second implementation.
• A17 Package can build, pack, install, import and typecheck in isolation with no root-source fallback.
• A18 Final architecture guards/docs are reconciled, obsolete @clickhouse/client-web executable wiring is removed, and follow-up: move @altinity/clickhouse-http into a dedicated Altinity repository #639 has a tested mechanical extraction handoff.

Non-goals

• Reimplementing the full @clickhouse/client-web feature surface.
• ORM/query-builder APIs.
• Automatic retry in the package.
• Package-owned OAuth, Basic credential acquisition, refresh, lifecycle state or query registry.
• Moving SQL Browser schema/catalog/lineage/documentation product queries into the package.
• Redesigning workbench/dashboard UX or changing persisted formats.
• Adding another third-party runtime dependency.
• Creating Altinity/clickhouse-http or publishing npm from this issue; that is follow-up: move @altinity/clickhouse-http into a dedicated Altinity repository #639 after Phase 8 ships.

Related

• ADR-0005: adopt @clickhouse/client-web behind the SQL Browser transport adapter #585 — rejected @clickhouse/client-web adoption; Phase 1 transport seam is the starting point.
• Umbrella: V2 architecture refactor — shell primitives, composition root, state reactivity, transport adapter #593 — V2 architecture umbrella that sequenced ADR-0005: adopt @clickhouse/client-web behind the SQL Browser transport adapter #585.
• follow-up: move @altinity/clickhouse-http into a dedicated Altinity repository #639 — post-Phase-8 cross-repository move/release/cutover.
• [absorbed into #630 Phase 1] freeze native Fetch, Response, and cancellation semantics #631–[absorbed into #630 Phase 8] make the package independently publishable and lock the boundary #638 — closed as absorbed historical drafts of the eight phases above.
• docs/ADR-0005-clickhouse-web-client.md — rejection/cancellation incompatibility evidence.
• skills/ship/SKILL.md — autonomous delivery contract.

[BorisTyshkevich]

Dedicated-repository extraction is tracked separately as #639. It intentionally starts only after #638 and is not part of the repo-scoped /ship 631,632,633,634,635,636,637,638 auto-chain.

[BorisTyshkevich]

Ship log — #630

Phase	Status	PR
1 — freeze native Fetch, Response, and cancellation semantics	shipped	#640
2 — create @altinity/clickhouse-http and move low-level request/URL mechanics	shipped	#641
3 — extract progress-stream and late-exception protocol primitives	in review	#644
4 — add consuming query APIs, ClickHouse errors, and stateless KILL QUERY	—	—
5 — extract ClickHouse SQL quoting and type-expression grammar	—	—
6 — simplify SQL Browser authentication integration around the package	—	—
7 — migrate query execution and export, then delete generic client mechanics	—	—
8 — stabilize the standalone package boundary and remove migration scaffolding	—	—

Phase 1 — handoff

• Landed: Strengthened tests/unit/clickhouse-transport-contract.ts and
  tests/unit/clickhouse-http-transport.test.ts to prove strict native Response
  identity, no hidden body consumption, exactly-one-Fetch (incl. pre-abort), exact
  SQL/Authorization fidelity, raw invalid-UTF-8 byte safety, live origin()/fetch()
  accessors, and exact URL-serialization literals. Added a real Chromium/WebKit e2e
  proof (tests/e2e/clickhouse-http-transport.{html,spec.js}) covering pre-abort,
  abort-while-awaiting-headers, native post-header body cancellation,
  no-callbacks-after-cancellation, concurrent isolation, and abort-after-completion —
  driven through the actual production transport. tests/spike/clickhouse-client/fault-server.mjs
  gained byte-safe body capture, opt-in CORS mode, and a deterministic post-header-hold
  fixture; .github/workflows/ci.yml's e2e path filter now includes that one shared
  fixture file. Zero production source files changed
  (src/net/clickhouse-http-transport.ts, clickhouse-transport.types.ts,
  ch-client.ts byte-identical to origin/main).
• Decisions taken (not in the issue): none — the plan's file footprint, scope
  boundary, and Definition of Done were followed as written.
• Deviations from the spec: none.
• Deferred acceptance criteria: A2, A4–A18 → later phases (per the plan; this phase
  claims only A1 and A3).
• Follow-ups filed: none.
• Plan review: approved (ChatGPT-author / Fable-high-approve loop) on pass 3/5,
  conversation https://chatgpt.com/c/6a75a3fa-2c64-83eb-a750-b2c66edac40b
• Review outcome: certified head bebe53a / merged as 20f2b59 on origin/main.
  Code review: 2 passes. Pass 1 (test(#630): freeze native Fetch/Response/cancellation semantics (phase 1) #640 (comment))
  accepted 2 findings (Authorization matrix used only IANA-registered schemes,
  weaker than the stated "opaque, any scheme" claim — added a genuinely nonstandard
  scheme case; fault-server.mjs's new res.on('error', ...) suppression was wired
  unconditionally, contradicting its own cors-opt-in docstring — scoped it to
  cors:true only with a regression test) and rejected 1 (CI path-filter comment
  lines — not a second filter entry). Fixed in bebe53a, CI re-verified green at that
  SHA. Pass 2 (test(#630): freeze native Fetch/Response/cancellation semantics (phase 1) #640 (comment))
  certified clean: VERDICT: SHIP, no findings. Conversation:
  https://chatgpt.com/c/6a75b957-d5bc-83eb-89ba-d6bf87f6a1ff. One high-effort pre-PR
  read-only pass (Sonnet) over the complete branch diff additionally found no
  blocking issues, confirmed via direct sabotage of 4 distinct invariants (all
  caught).

Phase 2 — handoff

• Landed: Created packages/clickhouse-http as the repository's first npm
  workspace package (zero runtime deps). Moved chUrl()/URL serialization and the
  low-level createClickHouseHttpClient(deps).request(request) into it — a direct,
  branch-free native-fetch passthrough. src/net/clickhouse-http-transport.ts's
  send() is now a thin async delegating adapter to the package; streamLines()
  and all SQL Browser auth/epoch/lifecycle/retry policy stay local and unchanged.
  ch-client.ts's composition graph is untouched structurally; its eager
  pre-credential chUrl() preflight now calls the package serializer. Added 4 new
  build/check-boundaries.mjs architecture rules (package→root-src ban,
  root→package-internals-deep-import ban, zero-bare-specifiers-in-package-source,
  bare-package-import-restricted-to-src/net) each mirrored as a coverage-gated unit
  test with a real sabotage probe. Dockerfile now copies packages/ before
  npm ci; CI's unit/build/bundle/e2e/docker path filters include packages/**.
  Moved (not duplicated) the exact-literal chUrl() test suite into the package
  test; removed the older duplicate in ch-client.test.ts. Bundle-size attribution
  now classifies packages/** as first-party project code. 8 raw-ESM e2e fixtures
  reaching the transport gained an @altinity/clickhouse-http import-map entry
  (full raw-fixture-graph audit performed twice independently — implementer and
  reviewer — confirming no additional fixture needs one). All nine Phase-1
  transport invariants now pass directly against the package's own request(),
  not only through the compatibility adapter.
• Decisions taken (not in the issue): none beyond the plan's own explicit
  choices (Checkpoint 1/2/3 migration order; keeping ch-client.ts's eager
  pre-credential chUrl() validation synchronous while the package request() and
  the adapter send() stay async, to preserve today's rejected-promise
  settlement contract for malformed URL values).
• Deviations from the spec: none — the plan implemented cleanly as written.
• Deferred acceptance criteria: A6–A18 → later phases (per the plan; this phase
  claims only A2, A4, A5).
• Follow-ups filed: none.
• Plan review: approved by Fable/high on the 3rd real review pass, 5-pass cap not
  exhausted. Process note: the automated ChatGPT-author/Fable-review Workflow
  loop hit a real infrastructure failure partway through pass 2 — Agent Chrome
  disconnected from CDP mid-run, then on a scripted resume attempt was killed and
  restarted with a fresh, logged-out profile (chrome_unavailable → login_required
  across repeated automated retries). After the user manually restarted and
  re-authenticated Chrome, the plan-review loop was completed by hand at the
  user's explicit direction ("get result and push it to fable for review, not by
  skill and playwright"): the completed ChatGPT response was read directly from the
  DOM (no Playwright), the plan extracted and written to the canonical plan file,
  and Fable/high invoked directly via the Agent tool (bypassing the
  chatgpt-review skill) for both the pass-2 review (3 accepted findings: a Docker
  build break from Checkpoint 1 onward — Dockerfile never copied packages/
  before npm ci; a zero-runtime-deps sabotage that stayed green — a hoisted bare
  import in package source would evade every proposed check; a minor
  async-vs-sync settlement-semantics drift) and the pass-3 re-review, which
  returned VERDICT: APPROVED with no remaining gaps. Revision prompts were
  submitted to the existing ChatGPT conversation via direct DOM manipulation
  (document.execCommand('insertText', ...) + a real click on the send button),
  preserving conversation continuity (same session, no new conversation started).
  Conversation: https://chatgpt.com/c/6a75c289-fc18-83ed-a241-544db9395485.
• Review outcome: certified head 62f0183 / merged as 5f62b39 on origin/main.
  Code review: 2 passes. Pass 1 (feat(#630): create @altinity/clickhouse-http, move low-level request/URL (phase 2) #641 (comment))
  raised 3 findings, all rejected after independent verification: a pre-existing
  (predates this PR by weeks, commit f16e4a1a/Refactor app.ts into explicit application services and route sessions #276) dynamic-import regex gap in
  check-boundaries.mjs with no live exploit path — filed separately as
  check-boundaries.mjs's dynamic-import scanner misses backtick no-substitution template literals #642 (inbox); a
  Checkpoint-1-commit CI-run evidentiary gap explained by GitHub Actions'
  per-push (not per-commit) trigger semantics; and a WebKit e2e reproduction-scope
  caveat matching this repo's documented Chromium-only PR CI policy. Pass 2
  (feat(#630): create @altinity/clickhouse-http, move low-level request/URL (phase 2) #641 (comment))
  certified clean: VERDICT: SHIP, the same dynamic-import finding resurfaced and
  was again correctly rejected as a non-blocking pre-existing gap. Conversation:
  https://chatgpt.com/c/6a75e669-98f0-83eb-bae4-66411c3cd313. One
  targeted read-only review (Sonnet, Medium-risk budget) covering the 6
  invariant-map items not independently spot-checked by the coordinator (import-ban
  sabotages, move-not-duplicate claims, ch-client.ts composition, streamLines()
  locality, single-serializer invariant, direct-package contract registration)
  found no defects. Coordinator independently verified: diff footprint, npm ci
  workspace linkage, full six-command gate, genuine 100% package coverage (via
  lcov, not just the console table), the bare-specifier-ban sabotage, a real
  docker build (legacy driver — buildx blocked in this sandbox) succeeding and
  failing exactly as expected when the COPY packages ./packages fix is removed,
  the new e2e spec (18/18 Chromium+WebKit) through the package-backed adapter, and
  the full root e2e regression (432 passed, 4 pre-existing skips).

Phase 3 — handoff

• Landed: Moved streamLines(), parseExceptionText(), findExceptionFrame(),
  and the StreamLine/StreamCallbacks/ProgressMetaColumn wire types out of
  src/net/clickhouse-http-transport.ts/src/core/stream.ts into
  packages/clickhouse-http/src/{progress-stream,exceptions}.ts — a real move+delete,
  not an additive compatibility layer (no forwarding wrapper anywhere). findExceptionFrame
  now takes the retained tail as a raw Uint8Array and computes byte offsets via a
  lossless latin1 byte↔char view, never TextDecoder, on the clean prefix — genuinely
  byte-safe, verified with invalid-UTF-8-plus-multibyte-message boundary cases.
  src/net/ch-client.ts's runQuery now calls the package's streamLines directly
  (no longer through the transport seam); export-service.ts's streamToFile calls
  the package's findExceptionFrame on its retained holdback directly through
  ch-client.ts's zero-logic re-export gateway, deleting the caller-side latin1
  converter it used to carry. StreamResult, row caps, progress percentages,
  raw/result presentation, editor-caret positioning (parseErrorPos), and
  auth-expiry/denial UI policy (isAuthExpiredBody, authDeniedMessage) all remain
  in SQL Browser, logic byte-for-byte unchanged. build/check-boundaries.mjs gains a
  narrow legacy-owner regression rule (rejects the three former owners regaining any
  moved identifier), mirrored with sabotage probes. The real-browser Chromium/WebKit
  transport harness now streams through the package's streamLines directly.
  Compile-fallout retargeted at every site: tests/unit/ch-client.test.ts,
  clickhouse-http-transport.test.ts, stream.test.ts, and 3 spike files
  (progress-bridge.ts, current-adapter.ts, browser-harness.ts).
• Decisions taken (not in the issue): none beyond the plan's own explicit choices.
• Deviations from the spec: the implementation agent found and fixed a real bug
  in its own required sabotage-check tooling — the new check-boundaries.mjs rule's
  comment-stripping regex used two sequential passes (strip all block comments, then
  all line comments), which let a /*-shaped substring inside an unstripped //
  comment (this file's own prose mentioning `src/core/**`) act as a spurious
  block-comment opener and silently swallow real code — including a reintroduced
  export interface StreamLine sabotage probe, which then passed both check:arch
  and its mirror test undetected. Fixed with a single alternation-based regex
  (commit 9ff449e), independently re-verified by both the coordinator and the
  pre-PR reviewer by reproducing the exact sabotage. The implementer also touched
  CHANGELOG.md despite the explicit mutation-boundary instruction not to (that's the
  coordinator's job) — content verified factually accurate against the diff by both
  the coordinator and the pre-PR reviewer, so left as-is rather than redone.
• Deferred acceptance criteria: A8–A18 → later phases (per the plan; this phase
  claims only A6 and A7).
• Follow-ups filed: check-boundaries.mjs's dynamic-import scanner misses backtick no-substitution template literals #642
  (inbox, filed during Phase 2's code review — pre-existing dynamic-import regex
  gap in check-boundaries.mjs, unrelated to Phase 3 but referenced in its context);
  Two architecture-mirror tests use an unsound two-pass comment-strip regex #643 (inbox — two other,
  untouched test files carry the same unsound two-pass comment-strip pattern this
  phase's own bug demonstrated, found during the high-risk pre-PR review).
• Plan review: approved by Fable/high on the 2nd real review pass (1 REVISE with
  2 findings, both incorporated and independently re-verified; then APPROVED),
  5-pass cap not exhausted. Process note: the automated ChatGPT-author/Fable-review
  Workflow loop again hit repeated timed_out/invalid_response results from the
  private plan-author command across all 4 allowed attempts in pass 1 — this time not
  a Chrome crash (Chrome stayed connected and logged in throughout), just the
  response-completion detection never settling before the 540s timeout on a very
  long generation. The actual ChatGPT tab had a complete, well-delimited response
  sitting unread each time. Recovered the same way as Phase 2's incident: read the
  completed response directly from the DOM, extracted the plan, invoked Fable/high
  directly via the Agent tool for review, and submitted the revision prompt via
  direct DOM manipulation — preserving the same conversation/session throughout.
  Conversation: https://chatgpt.com/c/6a75ec0f-5484-83eb-bd23-29d5d8762d77.
• Review outcome: FULL STOP — no certified head after 3 code review passes.
  Head d3488d6, PR feat(#630): extract progress-stream and late-exception primitives (phase 3) #644 OPEN, not merged. Pass 1 accepted 1 finding (comment-strip
  regex had no string/template-literal awareness; fixed ad792f3). Pass 2 accepted
  1 finding (the fixed scanner still had no regex-literal awareness; fixed
  8e9af14). Pass 3 accepted 1 finding (the regex-vs-division heuristic
  unconditionally treated ) as division even when it closes an if/while/for
  condition; fixed locally and pushed as d3488d6) — but pass 3 itself never
  returned a clean VERDICT: SHIP, so there is no certified head, and the 3-pass
  cap is exhausted with no clean pass at any head. This is the third consecutive
  pass finding a distinct bypass in the same build/check-boundaries.mjs "Phase 3
  legacy-owner" scanner (and its identical test mirror) — a real, recurring
  root-cause pattern (a hand-rolled JS/TS lexer covering comments, strings,
  templates, and regex-vs-division has an effectively unbounded edge-case
  surface), not 3 independent isolated bugs. Before pass 3, the coordinator
  attempted a root-cause fix — replacing the hand-rolled scanner with the repo's
  already-available typescript devDependency's real parser — but discovered
  typescript@7.0.2 is the new native/Go-ported compiler rewrite, whose
  importable surface has no synchronous text-to-AST parse entry point (real
  parsing only exists behind a heavy, language-server-style Project/Program
  client API); introducing a second, differently-versioned typescript dependency
  just for this one check would itself be an out-of-scope dependency decision, so
  patching the existing scanner continued. Conversation:
  https://chatgpt.com/c/6a760219-4f44-83ed-a52b-97ab7df35586. Every fix commit was
  independently re-verified by the coordinator (direct reproduction of each
  reported bypass, confirmed corrected; the real StreamLine-reintroduction
  sabotage re-confirmed caught after every fix; full six-command gate green after
  every commit). One
  high-effort pre-PR read-only pass (Sonnet) over the complete branch diff (run
  before the code review loop started) found no
  blocking issues — confirmed the production cutover is real (not forwarding),
  no-duplicate-implementation, the result-policy boundary held with unchanged logic,
  the byte-accurate exception boundary is genuinely byte-safe, the comment-stripper
  bugfix is correct and applied identically in both files, and all compile-fallout
  sites were genuinely retargeted (not just passing check:types by coincidence).
  Coordinator independently verified: diff footprint, full six-command gate, direct
  reproduction of the StreamLine-reintroduction sabotage (confirmed caught after the
  fix), the new e2e spec (18/18 Chromium+WebKit, Scenario 6 now labelled "package
  streamLines()"), and the full root e2e regression (432 passed, 4 pre-existing skips).