[absorbed into #630 Phase 2] create the package and move low-level request/URL mechanics

[BorisTyshkevich]

Part of #630.

Depends on: #631

Goal

Create an in-repo first-party workspace package named @altinity/clickhouse-http and move the low-level ClickHouse HTTP request/URL mechanics behind its public API without changing SQL Browser behavior.

This unit establishes the real package boundary. It does not yet move progress-stream parsing, ClickHouse error consumers, SQL Browser auth policy, product queries, or application services.

Architecture decision

Use packages/clickhouse-http/ as an npm workspace package. SQL Browser must consume it through the package name/public exports, not by importing packages/clickhouse-http/src/** directly.

The package must have no imports from src/** or any other SQL Browser implementation path.

Root npm ci, the existing single-file esbuild build, and the full test/type/architecture gate must continue to work. No new third-party runtime dependency is introduced; this is first-party source bundled into the existing artifact.

Required public API in this unit

The package must expose a low-level client equivalent to:

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

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

export interface ClickHouseHttpDeps {
  fetch(): typeof fetch;
  endpoint(): string;
}

export function createClickHouseHttpClient(deps: ClickHouseHttpDeps): ClickHouseHttpClient;

Exact symbol names may use the package's naming convention, but the contract above is fixed:

• sql is opaque and unchanged;
• authorization is the complete opaque header value;
• dependency accessors are read live per request;
• exactly one Fetch invocation;
• native Response returned unchanged;
• non-2xx resolves;
• no body consumption;
• no retry;
• no token lookup;
• no lifecycle callback;
• caller signal is passed to the real Fetch request directly.

URL serialization

Move the implementation currently owned by chUrl() into the package as one authoritative URL builder used by request().

Preserve current SQL Browser wire behavior in this unit:

default_format=<caller value>
enable_http_compression=1
<settings serialized by key>
<params serialized by key>

params remains the current exact wire vocabulary. The package must not invent a second native-parameter abstraction yet: callers may supply param_*, query_id, session_id, role, and other ClickHouse query-string controls exactly as today.

Do not trim/filter truthy values in a way that changes current 0/empty-string serialization. Use one deterministic serializer and cover encoding with #631's contract cases.

SQL Browser integration

Keep the existing ClickHouseTransport seam temporarily so this PR is a narrow move rather than an application-wide rewrite.

src/net/clickhouse-http-transport.ts should become a compatibility adapter:

• send() delegates to @altinity/clickhouse-http's low-level request();
• current streamLines remains SQL Browser-owned until [absorbed into #630 Phase 3] extract progress-stream and late-exception protocol primitives #633;
• chUrl may remain as a temporary compatibility re-export/wrapper if existing callers/tests require it, but it must delegate to the package serializer rather than retain a duplicate implementation.

The reusable transport contract from #631 must run unchanged against the adapter and, where practical, directly against the package client so the new boundary is proven rather than only transitively assumed.

Workspace/package requirements

Add the minimal npm-workspace configuration needed for root npm ci to link the local package. The root app must import @altinity/clickhouse-http by package name.

Initial package layout:

packages/clickhouse-http/
  package.json
  src/
    index.ts
    client.ts
    url.ts
  tests/            # if package-local tests are the cleanest fit

The final independently publishable build/packaging surface is #638. This issue only needs a development-time workspace package that is isolated and testable.

Package metadata in this unit must include at least:

• name: "@altinity/clickhouse-http";
• private: true until [absorbed into #630 Phase 8] make the package independently publishable and lock the boundary #638 makes publication readiness explicit;
• type: "module";
• Apache-2.0 license declaration;
• an explicit export surface that resolves inside the workspace.

Do not add a runtime dependency to the package.

Architecture enforcement

Extend build/check-boundaries.mjs in this unit only as needed to enforce the new source boundary:

• packages/clickhouse-http/** cannot import from root src/**;
• root SQL Browser source may import the package public entrypoint, not packages/clickhouse-http/src/** internals.

The checks must be deterministic and run in npm run check:arch.

Tests

Package/request tests

Prove:

• strict native Response identity;
• one Fetch invocation on 2xx and non-2xx;
• no body consumption;
• exact SQL body;
• opaque Authorization;
• caller signal identity/passthrough;
• live endpoint() and fetch() accessors;
• current URL serialization/encoding;
• no package import reaches SQL Browser source.

SQL Browser regression

The full #631 transport contract must remain green against the compatibility adapter.

Because workspace/dependency wiring changes the runtime module graph, run the relevant browser/e2e suite in addition to the full gate.

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

If the repository's targeted client browser suite is materially faster, run it during iteration; the final PR still needs the normal relevant e2e evidence required by /ship for dependency/workspace changes.

Acceptance criteria

• packages/clickhouse-http exists as an npm workspace package named @altinity/clickhouse-http.
• The package has zero imports from SQL Browser src/**.
• SQL Browser imports the package through its public package export.
• Low-level request() satisfies every [absorbed into #630 Phase 1] freeze native Fetch, Response, and cancellation semantics #631 Fetch/native-Response contract invariant.
• URL serialization has one implementation in the package.
• src/net/clickhouse-http-transport.ts no longer contains an independent request/URL implementation.
• Current stream parsing remains behaviorally unchanged and intentionally deferred to [absorbed into #630 Phase 3] extract progress-stream and late-exception protocol primitives #633.
• build/check-boundaries.mjs prevents package→app imports and root deep-imports into package internals.
• Root npm ci/typecheck/tests/build/e2e remain green.
• No new third-party runtime dependency is added.

Non-goals

• Moving streamLines, parseExceptionText, findExceptionFrame, or StreamResult.
• Adding queryJson, queryText, queryProgress, or killQuery convenience APIs.
• Moving SQL quoting or ClickHouse type parsing.
• Changing authedFetch, token refresh, credential epochs, auth classification, or connection state.
• Deleting the SQL Browser transport compatibility seam yet.
• Making the package publishable to npm yet; [absorbed into #630 Phase 8] make the package independently publishable and lock the boundary #638 owns that final isolation/build/pack step.
• Creating the future dedicated GitHub repository.

Agent execution notes

Before planning, read #630, #631, root package.json/package-lock.json, tsconfig.json, build/build.mjs, build/check-boundaries.mjs, the current transport types/implementation, and the strengthened contract/browser tests. Keep this PR a behavior-preserving ownership move: package first, compatibility adapter second, no duplicate request implementation left behind.