[absorbed into #630 Phase 8] make the package independently publishable and lock the boundary

[BorisTyshkevich]

Part of #630.

Depends on: #637

Goal

Finish the extraction by making @altinity/clickhouse-http an independently buildable/packable package, mechanically enforce the final ownership boundary, remove the rejected @clickhouse/client-web dependency and obsolete vendor-spike runtime/test wiring, and reconcile repository architecture documentation.

At completion, SQL Browser must consume only the package's public built API, generic protocol behavior must have one owner, and moving packages/clickhouse-http to its own GitHub repository must be a mechanical source-history/release operation rather than another architecture refactor.

Package publication-ready shape

The package remains in this repository for /ship review/merge, but it must no longer rely on root source files or workspace-only source resolution.

Required package shape, adjusted only for normal build-script conventions:

packages/clickhouse-http/
  package.json
  README.md
  src/
    ...
  tests/
    ...
  dist/             # generated, not necessarily committed
  tsconfig.json
  tsconfig.build.json or equivalent declaration config
  build script(s)

Package metadata

Final package.json must include:

• name: "@altinity/clickhouse-http";
• an initial independent semver version (0.1.0 unless an existing package-version decision is recorded before implementation);
• private: false;
• type: "module";
• license: "Apache-2.0";
• sideEffects: false unless the implementation has a concrete tested side effect that requires a narrower declaration;
• files limited to publishable artifacts/docs;
• an exports map pointing at built JS and declarations, never src/*.ts;
• matching type declarations;
• package-local build, test, and check:types scripts sufficient to run after extraction into a standalone repository;
• no runtime dependencies unless a previous epic unit intentionally introduced one (this epic should normally leave runtime dependencies empty).

Use existing repository dev tooling where practical. Do not add a new build framework or third-party runtime package.

Build output

Produce standards-compatible ESM JavaScript and TypeScript declarations for the public API.

Requirements:

• browser-first output;
• no Node-only imports in runtime modules;
• no bundling of SQL Browser source;
• declaration output resolves all exported package types without root-project path aliases;
• source maps are optional; do not add them solely for this issue unless package conventions require them;
• the SQL Browser root esbuild build may consume the workspace package's built/public entrypoint and must still inline it into the single dist/sql.html artifact.

Do not ship test files, root-repo docs, spike evidence, or SQL Browser application code in the npm tarball.

Isolated pack/install proof

Add a deterministic package-isolation test/script that proves publication readiness without network access:

1. build the package;
2. run npm pack (or npm pack --json) for packages/clickhouse-http;
3. inspect the tarball file list and fail if root SQL Browser files or package source/test internals leak unexpectedly;
4. create a temporary isolated fixture outside the workspace package tree;
5. install the produced local tarball into that fixture with no registry dependency for runtime code;
6. import the package as ESM and exercise a minimal low-level client construction with injected Fetch;
7. compile a small TypeScript fixture against the installed declaration surface;
8. prove no import resolves back into the SQL Browser repository's src/**.

The fixture must use only the tarball/public package API. A test that imports workspace source directly is not sufficient.

Public API review

Before locking exports, audit every package export introduced by #632–#635.

Keep only capabilities justified by the epic:

• low-level native-Response request client;
• URL serialization required by that client/authenticated preflight;
• ClickHouse progress-line streaming primitive/types;
• HTTP exception text parsing;
• late exception-frame parsing on bytes;
• ClickHouseError and success/error response classification;
• JSON/text/progress response consumers and convenience request methods;
• stateless KILL QUERY;
• ClickHouse SQL string/identifier quoting;
• generic ClickHouse type AST/parser/canonicalization/analysis required by current consumers.

Do not publish SQL Browser compatibility aliases merely because they existed during migration. Root SQL Browser code must migrate to the stable package names in this unit.

Architecture guardrails

Strengthen build/check-boundaries.mjs so the final boundary cannot regress.

At minimum fail with clear file:line diagnostics when:

1. packages/clickhouse-http/** imports from root src/**, application/**, UI, workspace, dashboard, OAuth, or other SQL Browser implementation paths;
2. root SQL Browser imports packages/clickhouse-http/src/**, dist/**, or other package internals instead of @altinity/clickhouse-http public exports;
3. a new generic ClickHouse request/URL implementation appears under src/net/ instead of using the package (target the retired concrete files/symbol patterns narrowly enough to avoid forbidding legitimate authenticated/product policy);
4. a second progress JSON-lines or late-exception-frame implementation is added under SQL Browser source after the old one is removed;
5. the retired @clickhouse/client-web import is reintroduced into production/spike runtime paths without a new recorded architecture decision.

Use the repository's existing deterministic check style; no new lint framework.

Add fixture/sabotage coverage for each new guard. A guard that cannot be made precise should not be replaced by a broad false-positive-prone grep; use the smallest deterministic structural check that enforces the intended invariant.

Remove rejected official-client dependency/wiring

Remove @clickhouse/client-web from root devDependencies/package lock once no retained test/evidence code executes it.

Reconcile the Phase-0/Phase-2 spike tree:

Retain

• docs/ADR-0005-clickhouse-web-client.md as historical decision evidence;
• docs/evidence/585/** historical measurement/results needed by the ADR;
• generic fault/cancellation/browser scenarios that now serve the first-party package contract, moved/renamed out of an "official client spike" namespace when appropriate.

Delete or retire from executable test/build wiring

• official-client adapter code used only for the rejected comparison;
• vendor support-minimum/probe code with no continuing regression purpose;
• npm scripts whose only meaning is "official client migration spike";
• stale import maps/config references to @clickhouse/client-web.

Rename surviving browser-contract scripts to describe the final first-party package (for example test:clickhouse-http:browser) rather than the rejected spike. Update #631/#634/#636/#637 test references in docs/comments only where repository docs require it; issue history itself need not be rewritten.

Remove migration compatibility surface

Search the repository after #637 and remove any remaining compatibility-only artifacts, including where applicable:

• src/net/clickhouse-http-transport.ts;
• src/net/clickhouse-transport.types.ts;
• SQL Browser re-exports of package stream/error/type/quote implementations that have no external internal caller left;
• old transport contract factories that should now be package contract tests, while retaining/repointing their useful assertions;
• duplicate error/stream/url helper functions.

Do not delete a compatibility name that remains a deliberate SQL Browser public-internal API for multiple product modules unless the approved plan proves migration to the package name is safe in the same PR. The invariant is one implementation and public package use, not deletion for its own sake.

Documentation reconciliation

Update in this PR:

• docs/ARCHITECTURE.md — package boundary, authenticated SQL Browser adapter, QueryExecutionService/ExportService ownership, cancellation lifetime;
• CLAUDE.md — repo map/hard-rule wording for the first-party workspace package, while keeping the count of third-party bundled runtime dependencies accurate;
• relevant .wiki source/architecture/project-skill pages that would otherwise be stale;
• docs/ADR-0005-clickhouse-web-client.md with a short follow-up addendum linking the first-party extraction decision and explaining that rejected vendor adoption was replaced by package extraction, without rewriting the historical evidence;
• CHANGELOG.md [Unreleased];
• package README.md documenting API contracts, body-consumption levels, cancellation semantics, error model, and browser/Fetch requirements.

Also add a root maintainer document such as docs/clickhouse-http-repository-extraction.md describing the exact future dedicated-repository move:

• subtree/path to extract;
• package build/test commands;
• expected GitHub repository/package name;
• how SQL Browser changes from workspace dependency to released semver dependency;
• which root browser-contract tests should move with the package versus remain as SQL Browser integration tests;
• release/publish credentials intentionally not specified/stored in git.

This document is a mechanical handoff, not a new decision gate.

Final tests

Package standalone gates

From the package or through root scripts, prove:

• package typecheck;
• package unit tests;
• package build;
• npm pack file-list contract;
• isolated tarball install;
• isolated ESM runtime import;
• isolated TypeScript consumer compile.

SQL Browser gates

Because dependency/workspace exports/build wiring changes, run full root e2e and the renamed first-party browser cancellation suite:

npm run check:types
npm run check:arch
npm run check:schemas
npm run check:examples
npm test
npm run build
npm run test:e2e
npm run test:clickhouse-http:browser

If the final script name differs, document it and ensure it runs Chromium and WebKit cancellation/streaming scenarios from #631.

Also run the package isolation/pack test through a committed root or package script so CI/review can reproduce it.

Acceptance criteria

• @altinity/clickhouse-http has a built ESM + declaration public surface and no SQL Browser source dependency.
• Package metadata is publication-ready and private is false.
• npm pack contains only intended publishable files.
• A tarball installs/imports/typechecks in an isolated fixture with no root-source fallback.
• SQL Browser consumes only package public exports.
• Final architecture guards forbid package→SQL Browser imports and SQL Browser deep imports into package internals.
• Generic request/URL/stream/error mechanics have one implementation in the package.
• Obsolete transport compatibility code is removed or proven still necessary and implementation-free.
• @clickhouse/client-web is absent from root dependency/lock/runtime test wiring.
• Historical ADR/evidence for ADR-0005: adopt @clickhouse/client-web behind the SQL Browser transport adapter #585 remains preserved.
• Surviving browser contract tests are renamed/reseated as first-party package regressions.
• No new third-party runtime dependency is added.
• SQL Browser still builds one self-contained dist/sql.html.
• Package README documents low-level native Response/body ownership and caller-signal lifetime unambiguously.
• Dedicated-repository extraction is documented as a mechanical follow-up.
• Architecture/wiki/ADR/changelog documentation is reconciled.
• Package standalone gates, root full gate, e2e, and Chromium/WebKit contract tests pass.

Non-goals

• Creating the future dedicated GitHub repository from inside /ship.
• Publishing an npm release or configuring npm/GitHub release credentials.
• Adding CI infrastructure for a repository that does not yet exist.
• Adding new client features beyond the API already required by SQL Browser.
• Moving product-specific schema/catalog/lineage/documentation SQL into the package.
• Changing SQL Browser user-facing behavior or persisted formats.

Agent execution notes

Before planning, read #630–#637, root/package manifests and lockfile, build/type/test configs, build/check-boundaries.mjs, ADR-0005, architecture/wiki docs, every package export, and every remaining import of the retired transport/vendor modules. This is a subtractive/release-readiness unit: prove standalone use first, then delete compatibility and lock the boundary. The approved plan must include an invariant map and sabotage cases for package isolation, public-export-only consumption, single protocol ownership, and dependency removal.