@eliware/elera-lib 0.2.0 → 0.3.0

package/README.md

@@ -1,123 +1,32 @@
 # @eliware/elera-lib
 
-The alternative SQL client for Eliware applications. It provides generic
-primary/balanced MySQL or MariaDB routing without embedding HAProxy, backup, or
-GitOps policy.
-
-`primary` is the designated write path. `balanced` is an optional read path;
-automatic routing sends only conservative, single-statement read queries to it.
-Transactions always use `primary`.
-
-```js
-import { createDb } from '@eliware/elera-lib';
-const db = await createDb();
-await db.query('SELECT 1');
-await db.close();
-```
-
-Managed applications configure only `ELERA_API_ENDPOINT` and
-`ELERA_API_TOKEN`. Call `createDb({ endpoint, token })` explicitly or omit
-either value when it is available in the process environment.
-
-See `examples/basic-client.mjs` for a complete consumer example using only the
-public package API. Its usage notes are in `examples/README.md`. The managed
-client contract is defined in `contracts/managed-client.md`; it owns initial
-bundle retrieval, credential materialization, and routing-stream setup.
-
-Routing bundles passed to `createDbFromBundle` use the normalized shape
-`routes.primary` and `routes.balanced`, each containing ordered `{ host, port,
-weight }` nodes. A bundle may also carry an explicit `writer`, ordered
-`failover`, and `readers` assignment. The bundle carries `database`,
-`identity`, optional `application`, `credentialName`, `scopes`, and
-`credentials`, and `expiresAt`; `validateBundle` rejects
-expired, malformed, duplicated, or conflicting route data. The checked-in
-contract fixture documents the supervisor-facing wire representation
-separately.
-
-The implementation accepts optional routing bundles and injected credential
-providers, maintains bounded pools per route, supports ordered writer/reader
-candidates, bundle refresh, and quarantine of unhealthy nodes. The WebSocket
-routing-event transport is implemented as a generic adapter. Nodes can be
-immediately excluded or re-admitted with `client.setNodeAvailability(route,
-host, available)`. These are generic client capabilities: the
-library does not know about supervisors, Elera, HAProxy, GitOps, backups, or
-CLI commands. Applications provide those integrations through ordinary
-configuration and callbacks.
-
-An application-scoped token should resolve to one application, database, and
-credential context. The library does not select databases or credentials from
-request arguments. Callers that already have that authorization context may
-pass `tokenContext` to `createDb`; bundle creation and refresh then reject
-cross-database, identity, credential, or scope mismatches.
-
-When a route node is drained, the client immediately stops assigning new work
-to that node while existing operations continue. The drain window defaults to
-45 seconds and is capped at 45 seconds; remaining pool connections are then
-force-closed. `client.drain(host)` returns `wait()` and `forceClose()`
-operations, while `client.nodeStates()` exposes lifecycle and active-operation
-state. Only conservative, single-statement reads are eligible for automatic
-retry after a connection failure; uncertain writes are never retried
-automatically.
-
-`client.availability()` reports whether a primary route is usable. It returns
-`state: 'cluster-unavailable'` when every primary candidate is draining or
-unavailable; the `routes` fields report primary and balanced availability
-independently. A single-node route fails with the exported
-`ServerUnavailableError` using code `SERVER_UNAVAILABLE`; a multi-node route
-with no eligible candidates fails with `ClusterUnavailableError` using code
-`CLUSTER_UNAVAILABLE`.
-
-When an attached routing stream receives a `routing.shutdown` event, the
-client drains the identified node, performs a REST bundle resynchronization,
-and closes the retiring WebSocket with restart code `1012`. If the event
-contains `loadBalancerEndpoint`, that endpoint replaces the current endpoint
-before resynchronization and reconnect. `reconnectDeadlineMs` bounds the
-planned reconnect window; after it expires, no new reconnect is scheduled.
-Reconnects, failovers, and measured reconnect delay are included in telemetry.
-If the WebSocket remains unavailable before the deadline, REST
-resynchronization and bounded reconnect backoff continue until the deadline or
-until the caller closes the stream.
-
-Routing events are validated before application. Shutdown events may include
-`node`, `reason`, `reconnect`, `reconnectDeadlineMs`, and
-`loadBalancerEndpoint`; invalid event fields are reported through `onError` and
-do not change routing state. `routing.update` replaces the writer and reader
-pools atomically, while `routing.drain` excludes only the named node from new
-work and allows active operations to finish.
-
-The public client intentionally exposes SQL operations, health, routing,
-lifecycle, and optional routing-event synchronization methods. REST and
-WebSocket transports are adapters, not supervisor or CLI policy. Underlying
-`mysql2` pools and driver objects remain internal implementation details.
-
-For maintenance workflows, `createQuiesceController` provides a generic
-connection-admission drain and `createSqlVerifier` provides generic connectivity,
-schema, account, and grant checks. Neither API transports or orchestrates dump
-contents. The stream reports `websocket`, `rest`, or `disconnected` mode so
-callers can observe transport health without implementing transport policy.
-
-Applications may opt into generic in-memory telemetry with
-`createDb({ ..., telemetry: true })`. Query, execute, and transaction counts,
-failures, retries, in-flight work, and latency are exposed through
-`client.telemetry` and sent over an attached routing stream once per second.
-Telemetry is observational only; it does not carry SQL or credentials.
-The snapshot may include the application, database, credential name, and
-scopes associated with the already-authorized client, plus reconnect, failover,
-and cumulative reconnect-delay counters. It never includes bearer tokens or
-passwords.
-
-`createMaterializer` supports bounded plaintext use for a caller-provided
-operation. It creates a mode-restricted temporary file and removes its entire
-temporary directory in a `finally` block; this limits lifetime and cleanup but
-does not hide plaintext from the caller. The library does not persist secrets,
-age keys, or supervisor-specific artifact metadata.
-
-The package exports the managed SQL client and internal bundle composition
-primitives, query classification and route selection, routing-bundle validation, generic REST
-and WebSocket routing adapters, SQL administration and verification helpers,
-and lifecycle helpers for quiescing and temporary materialization. These
-helpers remain policy-neutral and do not provision users, manage clusters, or
-perform backup/restore orchestration.
+`@eliware/elera-lib` is Elera's shared protocol and helper package. It contains
+the contracts and policy primitives used by the supervisor, CLI, and
+`@eliware/elera-client`.
+
+It provides routing-bundle validation, version comparison, writer assignment,
+ordered failover helpers, routing-event validation, shared SQL and availability
+errors, the client drain policy, and transport-neutral in-memory telemetry.
+
+Application code that needs native SQL connections must install
+`@eliware/elera-client`. SQL pools, credentials, WebSocket connections,
+database selection, backups, CLI commands, and supervisor orchestration are
+not part of this package.
+
+Routing bundles use normalized `routes.primary` and `routes.balanced` arrays
+containing ordered `{ host, port, weight }` nodes. A bundle may also carry a
+writer, readers, ordered failover nodes, application/database/identity scope,
+credentials, version, and expiry. `validateBundle` rejects malformed,
+expired, duplicated, or conflicting route data.
+
+Routing events are validated before consumers act on them. Shared errors
+distinguish an unavailable server from an unavailable cluster. The drain policy
+caps client drain windows at 45 seconds. Telemetry is observational and never
+contains bearer tokens, passwords, SQL, or connection pools.
+
+The supervisor and CLI own policy, persistence, authentication, provisioning,
+recovery, and transport orchestration. `elera-lib` supplies reusable contracts
+and helpers only.
 
 ## Development
 

package/RELEASE_NOTES.md

@@ -1,5 +1,38 @@
 # Release notes
 
+## 0.3.0 — Shared protocol and helper boundary
+
+### Breaking changes
+
+- Narrows `@eliware/elera-lib` to shared Elera contracts, validation, routing,
+  lifecycle, telemetry, and error helpers.
+- Removes the managed SQL client, SQL pools, credential providers, and
+  application-facing database orchestration from this package. Those concerns
+  belong to `@eliware/elera-client` or repository-specific implementations.
+- Removes supervisor- and CLI-specific administration, provisioning, and
+  connection behavior from the public library.
+
+### Changed
+
+- Makes routing-bundle validation enforce the complete shared contract,
+  including application, database, identity, credentials, writer, readers,
+  failover, version, expiry, node identity, and service ports.
+- Aligns the checked-in routing schema and fixture with the shared wire
+  contract.
+- Synchronizes the public runtime exports and TypeScript declarations with the
+  reduced shared-library boundary.
+- Keeps REST/WebSocket transport behavior, routing failover, lifecycle policy,
+  and telemetry primitives transport- and application-policy-neutral.
+
+### Verification
+
+- Adds focused validation for the complete routing-bundle contract, routing
+  nodes, shared errors, and public exports.
+- Removes client-specific tests and implementation from the shared package so
+  they can be maintained by `@eliware/elera-client`.
+- Contract verification, tests, lint, and coverage checks pass for the shared
+  library.
+
 ## 0.2.0 — Managed endpoint and token client
 
 ### Breaking changes

package/contracts/managed-client.md

@@ -0,0 +1,36 @@
+# Shared contract boundary
+
+This document describes the bundle and event contract consumed by Elera
+components. It is not an application-client API; application-facing SQL
+connections belong to `@eliware/elera-client`.
+
+## Routing bundles
+
+The supervisor publishes a complete `v1` bundle containing application,
+database, identity, credentials, writer, readers, ordered failover nodes,
+bundle version, expiry, node identity, and service ports. The normalized route
+arrays are `routes.primary` and `routes.balanced`.
+
+`validateBundle()` rejects missing required fields, malformed nodes or ports,
+expired timestamps, duplicate writer/failover nodes, and invalid route arrays.
+Consumers must validate a complete bundle before using it. Partial routing
+events must be merged with the active complete bundle by the consumer before
+validation.
+
+## Routing events
+
+`validateRoutingEvent()` defines the shared event boundary for routing updates,
+drains, recovery, and shutdown. Event handling and transport orchestration are
+owned by the consuming client or supervisor; this package supplies contracts
+and validation only.
+
+## Shared helpers
+
+The public package provides bundle and node validation, version comparison,
+writer/failover calculation, shared SQL errors, client drain policy, and
+transport-neutral telemetry. It does not retrieve bundles, open SQL pools,
+materialize application credentials, provision databases, manage Galera, or
+implement CLI and supervisor workflows.
+
+See `README.md` for the complete export boundary and
+`contracts/routing-bundle.schema.json` for the machine-readable contract.

package/contracts/routing-bundle.fixture.json

@@ -0,0 +1,17 @@
+{
+  "apiVersion": "v1",
+  "application": "billing",
+  "applicationId": "18446744073709551621",
+  "databaseId": "18446744073709551622",
+  "identityId": "18446744073709551623",
+  "database": "billing",
+  "identity": "billing-runtime",
+  "credentials": { "username": "billing_runtime", "password": "fixture-only" },
+  "writer": { "host": "sql0.internal", "port": 3306 },
+  "failover": [{ "host": "sql1.internal", "port": 3306 }],
+  "readers": [{ "host": "sql0.internal", "port": 3306, "weight": 100 }, { "host": "sql1.internal", "port": 3306, "weight": 80 }, { "host": "sql2.internal", "port": 3306, "weight": 60 }],
+  "nodeIdentity": "sql0.internal",
+  "ports": { "sql": 3306, "http": 8080 },
+  "bundleVersion": 1,
+  "expiresAt": "2099-01-01T00:00:00Z"
+}

package/contracts/routing-bundle.schema.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://eliware.dev/contracts/routing-bundle.schema.json",
+  "type": "object",
+  "required": ["apiVersion", "application", "database", "identity", "credentials", "writer", "readers", "failover", "bundleVersion", "expiresAt", "nodeIdentity", "ports"],
+  "properties": { "apiVersion": { "const": "v1" }, "application": { "type": "string", "minLength": 1 }, "applicationId": { "type": "string", "minLength": 1 }, "databaseId": { "type": "string", "minLength": 1 }, "identityId": { "type": "string", "minLength": 1 }, "database": { "type": "string", "minLength": 1 }, "identity": { "type": "string", "minLength": 1 }, "credentials": { "type": "object", "required": ["username", "password"], "properties": { "username": { "type": "string", "minLength": 1 }, "password": { "type": "string" } }, "additionalProperties": false }, "writer": { "$ref": "#/$defs/node" }, "failover": { "$ref": "#/$defs/nodes" }, "readers": { "$ref": "#/$defs/nodes" }, "nodeIdentity": { "type": "string", "minLength": 1 }, "ports": { "$ref": "#/$defs/ports" }, "bundleVersion": { "type": ["string", "number"] }, "refreshAfter": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" } },
+  "$defs": { "node": { "type": "object", "required": ["host"], "properties": { "host": { "type": "string", "minLength": 1 }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "weight": { "type": "number", "minimum": 0 } }, "additionalProperties": false }, "nodes": { "type": "array", "items": { "$ref": "#/$defs/node" } }, "ports": { "type": "object", "required": ["sql", "http"], "properties": { "sql": { "type": "integer", "minimum": 1, "maximum": 65535 }, "http": { "type": "integer", "minimum": 1, "maximum": 65535 }, "ws": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 65535 } } },
+  "additionalProperties": false
+}

package/examples/README.md

@@ -1,13 +1,11 @@
 # Elera library example
 
-`basic-client.mjs` is a minimal managed consumer application. It imports only
-the public `@eliware/elera-lib` package API, opens a SQL client from the Elera
-endpoint and application token, performs a health check and query, and closes
-the client in a `finally` block.
+`basic-client.mjs` demonstrates the shared `@eliware/elera-lib` contract
+helpers. Native SQL application examples belong to `@eliware/elera-client`.
 
-Run it with:
+Run it with a complete bundle:
 
-    ELERA_API_ENDPOINT=http://supervisor-or-load-balancer:8080 ELERA_API_TOKEN=application-token node examples/basic-client.mjs
+    ELERA_BUNDLE_JSON='{"apiVersion":"v1","application":"billing","database":"billing","identity":"billing-runtime","credentials":{"username":"billing_runtime","password":"fixture-only"},"writer":{"host":"elera-0","port":3306},"readers":[{"host":"elera-0","port":3306}],"failover":[{"host":"elera-1","port":3306}],"bundleVersion":1,"expiresAt":"2099-01-01T00:00:00Z","nodeIdentity":"elera-0","ports":{"sql":3306,"http":8080},"routes":{"primary":[{"host":"elera-0","port":3306}],"balanced":[{"host":"elera-0","port":3306}]}}' node examples/basic-client.mjs
 
 The example is infrastructure-neutral. It contains no Docker, Kubernetes,
 Supervisor, CLI, Galera, or test-lab setup.

package/examples/basic-client.mjs

@@ -1,13 +1,7 @@
-import { createDb } from '@eliware/elera-lib';
+import { createTelemetry, validateBundle } from '@eliware/elera-lib';
 
-// Set ELERA_API_ENDPOINT and ELERA_API_TOKEN before running this example.
-const db = await createDb();
+// Native SQL application examples live in @eliware/elera-client.
+const bundle = validateBundle(JSON.parse(process.env.ELERA_BUNDLE_JSON ?? '{}'));
+const telemetry = createTelemetry({ application: bundle.application, database: bundle.database });
 
-try {
-  const health = await db.health('primary');
-  if (!health.ok) throw new Error('primary SQL route is not healthy');
-  const [rows] = await db.query('SELECT 1 AS healthy');
-  console.log(JSON.stringify({ health, rows }));
-} finally {
-  await db.close();
-}
+console.log(JSON.stringify({ bundleVersion: bundle.bundleVersion, telemetry: telemetry.snapshot() }));

package/package.json

@@ -1,21 +1,21 @@
 {
     "name": "@eliware/elera-lib",
-    "version": "0.2.0",
-    "description": "Managed MySQL and MariaDB client using Elera endpoint and bearer-token routing",
+    "version": "0.3.0",
+    "description": "Shared Elera routing, event, lifecycle, telemetry, validation, and protocol helpers",
     "keywords": [
         "eliware",
         "elera",
         "mysql",
         "mariadb",
         "galera",
-        "sql",
-        "database",
-        "bearer-token",
+        "protocol",
+        "contracts",
         "routing",
         "failover",
         "telemetry",
         "websocket",
-        "connection-pool"
+        "protocol-contracts",
+        "mysql-client"
     ],
     "repository": {
         "type": "git",
@@ -27,6 +27,7 @@
     },
     "license": "Apache-2.0",
     "type": "module",
+    "sideEffects": false,
     "engines": {
         "node": ">=26"
     },
@@ -38,6 +39,7 @@
     },
     "files": [
         "src",
+        "contracts",
         "examples",
         "README.md",
         "RELEASE_NOTES.md",
@@ -56,8 +58,7 @@
     },
     "dependencies": {
         "@eliware/common": "^2.0.0",
-        "@eliware/snowflake": "^2.0.0",
-        "mysql2": "^3.24.2"
+        "@eliware/snowflake": "^2.0.0"
     },
     "devDependencies": {
         "@eliware/test": "^2.0.0",

package/src/bundle.mjs

@@ -1,13 +1,28 @@
 import { validateRoutingNode, validateRoutingNodes } from './routing/node-validation.mjs';
 const routes = ['primary', 'balanced'];
+const requiredText = (value, name) => { if (typeof value !== 'string' || value.length === 0) throw new TypeError(`${name} is required`); };
+const validatePorts = (ports) => {
+  if (!ports || typeof ports !== 'object') throw new TypeError('routing bundle ports are required');
+  for (const name of ['sql', 'http']) validateRoutingNode({ host: name, port: ports[name] }, `routing bundle ports.${name}`);
+};
 
 export function validateBundle(bundle) {
   if (!bundle || typeof bundle !== 'object') throw new TypeError('routing bundle is required');
+  if (bundle.apiVersion !== 'v1') throw new TypeError('routing bundle apiVersion must be v1');
+  requiredText(bundle.application, 'routing bundle application');
+  requiredText(bundle.database, 'routing bundle database');
+  requiredText(bundle.identity, 'routing bundle identity');
+  requiredText(bundle.nodeIdentity, 'routing bundle nodeIdentity');
+  if (!bundle.credentials || typeof bundle.credentials !== 'object') throw new TypeError('routing bundle credentials are required');
+  requiredText(bundle.credentials.username, 'routing bundle credentials.username');
+  if (typeof bundle.credentials.password !== 'string') throw new TypeError('routing bundle credentials.password is required');
+  if (bundle.bundleVersion === undefined || !['string', 'number'].includes(typeof bundle.bundleVersion)) throw new TypeError('routing bundle bundleVersion is required');
+  validatePorts(bundle.ports);
   if (!bundle.expiresAt || Number.isNaN(Date.parse(bundle.expiresAt))) throw new TypeError('routing bundle expiresAt is required');
-  const writer = bundle.writer !== undefined ? validateRoutingNode(bundle.writer, 'routing bundle writer') : undefined;
-  const failover = bundle.failover !== undefined ? validateRoutingNodes(bundle.failover, 'routing bundle failover') : [];
+  const writer = validateRoutingNode(bundle.writer, 'routing bundle writer');
+  const failover = validateRoutingNodes(bundle.failover, 'routing bundle failover');
   if (writer && failover.some((node) => node.host === writer.host && node.port === writer.port)) throw new TypeError('routing bundle failover duplicates writer');
-  if (bundle.readers !== undefined) validateRoutingNodes(bundle.readers, 'routing bundle readers');
+  validateRoutingNodes(bundle.readers, 'routing bundle readers');
   for (const route of routes) {
     if (bundle.routes?.[route] !== undefined && !Array.isArray(bundle.routes[route])) throw new TypeError(`bundle.routes.${route} must be an array`);
     for (const node of bundle.routes?.[route] ?? []) {

package/src/index.d.ts

@@ -1,121 +1,21 @@
-import type { PoolOptions } from 'mysql2/promise';
-
-export interface ConnectionProfile {
-  host: string;
-  port?: number | string;
-  user?: string;
-  password?: string;
-  database: string;
-  options?: Partial<PoolOptions> & { socket?: string };
-}
-
-export interface RoutingNode { host: string; port: number | string; weight?: number; }
-export interface WriterAssignment { host: string; port: number | string; }
-export interface RoutingPorts { sql?: number | string; http?: number | string; ws?: number | string; [name: string]: number | string | undefined; }
-export interface NodeIdentity { id?: string; name?: string; address?: string; ports?: RoutingPorts; }
-export interface RoutingBundle {
-  apiVersion?: string;
-  applicationId?: string;
-  databaseId?: string;
-  identityId?: string;
-  database?: string;
-  identity?: string;
-  application?: string;
-  credentialName?: string;
-  scopes?: string[];
-  credentials?: { username?: string; password?: string };
-  bundleVersion?: number | string;
-  expiresAt: string;
-  refreshAfter?: string;
-  routes: { primary?: RoutingNode[]; balanced?: RoutingNode[] };
-  writer?: WriterAssignment;
-  failover?: WriterAssignment[];
-  readers?: WriterAssignment[];
-  nodeIdentity?: NodeIdentity;
-  ports?: RoutingPorts;
-}
-/** Application-facing configuration for the managed Elera client.
- * Managed applications provide only the supervisor/load-balancer endpoint and
- * their application-scoped bearer token. Bundle retrieval, credentials, and
- * SQL routing are library responsibilities.
- */
-export interface ManagedClientOptions {
-  endpoint?: string;
-  token?: string;
-  mysqlLib?: unknown;
-  log?: unknown;
-  routing?: 'auto' | 'primary' | 'balanced';
-  quarantineMs?: number;
-  drainTimeoutMs?: number;
-  now?: () => number;
-  telemetry?: true | Telemetry;
-}
-export interface CredentialProviderResult { user: string; password: string; }
-export type CredentialProvider = (context: { database: string; identity: string | null; route: string }) => Promise<CredentialProviderResult> | CredentialProviderResult;
-export type QueryFunction = (sql: string, values?: unknown) => Promise<any>;
-export interface DbOptions { route?: 'auto' | 'primary' | 'balanced'; connection?: unknown; }
+export interface RoutingNode { host: string; port: number | string; weight?: number; nodeId?: string; }
+export interface RoutingBundle { apiVersion?: string; applicationId?: string; databaseId?: string; identityId?: string; application?: string; database?: string; identity?: string; credentialName?: string; scopes?: string[]; credentials?: { username?: string; password?: string }; bundleVersion?: number | string; expiresAt: string; refreshAfter?: string; routes: { primary?: RoutingNode[]; balanced?: RoutingNode[] }; writer?: RoutingNode; failover?: RoutingNode[]; readers?: RoutingNode[]; nodeIdentity?: Record<string, unknown>; ports?: Record<string, number | string>; }
 export interface TelemetrySnapshot { type: 'client.telemetry'; application: string; credentialName?: string; database?: string; scopes?: string[]; queries: number; failures: number; retries: number; reconnects: number; failoverCount: number; reconnectDelayMs: number; inflight: number; totalLatencyMs: number; maxLatencyMs: number; avgLatencyMs: number; sentAt: string; }
-export interface Telemetry { begin(): number; record(event?: { latencyMs?: number; failed?: boolean; retry?: boolean; reconnect?: boolean; failover?: boolean }): void; recordReconnect(event?: { delayMs?: number; failover?: boolean }): void; snapshot(): TelemetrySnapshot; start(stream: Pick<RoutingStream, 'sendTelemetry'>): void; stop(): void; }
-
-export interface DbClient {
-  query(sql: string, values?: unknown, options?: DbOptions): Promise<unknown>;
-  execute(sql: string, values?: unknown, options?: DbOptions): Promise<unknown>;
-  transaction<T>(callback: (transaction: Pick<DbClient, 'query' | 'execute'>) => Promise<T>): Promise<T>;
-  health(route?: 'primary' | 'balanced'): Promise<{ ok: boolean; route: string; latencyMs: number; telemetry?: TelemetrySnapshot }>;
-  close(): Promise<void>;
-  refresh(bundle: RoutingBundle): Promise<{ bundleVersion: number | string | null; refreshRequired: boolean }>;
-  bundle(): RoutingBundle | undefined;
-  classify(sql: string): 'primary' | 'balanced';
-  attachRoutingStream(stream: RoutingStream): Promise<() => void>;
-  setNodeAvailability(route: 'primary' | 'balanced', host: string, available: boolean): void;
-  availability(): { state: 'available' | 'cluster-unavailable'; routes: { primary: boolean; balanced: boolean } };
-  drain(host: string, timeoutMs?: number): { host: string; timeoutMs: number; wait(): Promise<unknown[]>; forceClose(): Promise<unknown[]> };
-  nodeStates(): Array<{ host: string; port: number; route: 'primary' | 'balanced'; state: 'ready' | 'draining' | 'unavailable' | 'recovering'; active: number; available: boolean }>;
-  config: { primary: ConnectionProfile; balanced?: ConnectionProfile };
-  telemetry?: Telemetry;
-}
-
-export interface RoutingStream {
-  connect(): Promise<void>;
-  setOnUpdate(handler: (event: unknown) => void | Promise<void>): void;
-  close(): void;
-  sendTelemetry(payload: unknown): void;
-  setTelemetry?(telemetry?: Pick<Telemetry, 'recordReconnect'>): void;
-  state(): { connected: boolean; mode: 'websocket' | 'rest' | 'disconnected'; expectedVersion: number | string; endpoint: string; reconnectDeadlineAt?: number };
-}
-
-export type RoutingEvent = { type: 'routing.update' | 'routing.resync' | 'routing.drain' | 'routing.recovery'; node?: string; version?: number | string; [key: string]: unknown } | { type: 'routing.shutdown'; node?: string; reason?: string; reconnect?: boolean; reconnectDeadlineMs?: number; loadBalancerEndpoint?: string };
-export function validateRoutingEvent(event: unknown): RoutingEvent;
-
-export function createDb(options: { primary: ConnectionProfile; balanced?: Partial<ConnectionProfile>; bundle?: RoutingBundle; tokenContext?: { application?: string; database?: string; credentialName?: string; identity?: string; scopes?: string[] }; credentialProvider?: CredentialProvider; identity?: string; mysqlLib?: unknown; log?: unknown; routing?: 'auto' | 'primary' | 'balanced'; quarantineMs?: number; drainTimeoutMs?: number; now?: () => number; telemetry?: true | Telemetry }): Promise<DbClient>;
-export function profilesFromBundle(bundle: RoutingBundle): { primary: ConnectionProfile; balanced?: ConnectionProfile };
-export function createDbFromBundle(options: { bundle: RoutingBundle; createClient?: typeof createDb; credentialProvider?: CredentialProvider; tokenContext?: { application?: string; database?: string; credentialName?: string; identity?: string; scopes?: string[] }; mysqlLib?: unknown; log?: unknown; routing?: 'auto' | 'primary' | 'balanced'; quarantineMs?: number; drainTimeoutMs?: number; now?: () => number; telemetry?: true | Telemetry }): Promise<DbClient>;
-export function createDb(options?: ManagedClientOptions & { fetchImpl?: typeof fetch; fetchPath?: string; WebSocketImpl?: typeof WebSocket }): Promise<DbClient>;
-export function validateTokenContext(bundle: RoutingBundle, tokenContext?: { application?: string; database?: string; credentialName?: string; identity?: string; scopes?: string[] }): RoutingBundle;
-export function classifyQuery(sql: unknown): 'primary' | 'balanced';
-export function routeFor(sql: unknown, requested?: 'auto' | 'primary' | 'balanced'): 'primary' | 'balanced';
-export function validateProfile(profile: ConnectionProfile, name?: string): ConnectionProfile;
-export function redactedProfile(profile: ConnectionProfile): ConnectionProfile;
-export class SqlClientError extends Error { code?: string; retryable?: boolean; cause?: unknown; }
-export class ClusterUnavailableError extends SqlClientError {}
-export class ServerUnavailableError extends SqlClientError {}
-export function classifyError(error: unknown): { retryable: boolean; code?: string };
-export function asSqlError(error: unknown): SqlClientError;
+export interface Telemetry { snapshot(): TelemetrySnapshot; begin(): number; record(event?: unknown): void; recordReconnect(event?: unknown): void; }
 export function validateBundle(bundle: RoutingBundle): RoutingBundle;
 export function bundleExpired(bundle: RoutingBundle, now?: number): boolean;
 export function bundleNeedsRefresh(bundle: RoutingBundle, now?: number): boolean;
-export function createAdminSql(options: { query: QueryFunction }): { transaction<T>(work: (context: { query: QueryFunction }) => Promise<T>): Promise<T>; migration(statements?: string[]): Promise<unknown> };
-export function createMigrationRunner(options: { query: QueryFunction; migrations?: Array<{ version: number; name: string; statements: string[] }> }): { status(): Promise<{ applied: unknown[] }>; migrate(): Promise<unknown> };
-export function selectRouteNodes(options: { bundle: RoutingBundle; route?: 'primary' | 'balanced'; now?: number }): RoutingNode[];
-export function createRoutingStream(options: { endpoint: string; token?: string; fetchBundle: () => Promise<RoutingBundle>; onUpdate?: (event: unknown) => void; onError?: (error: unknown) => void; reconnectMs?: number; maxReconnectMs?: number; heartbeatMs?: number; telemetry?: Pick<Telemetry, 'recordReconnect'> }): RoutingStream;
-export const DEFAULT_BUNDLE_PATH: '/api/v1/routing/bundle';
-export function fetchRoutingBundle(options: { endpoint: string; token: string; path?: string; fetchImpl?: typeof fetch; signal?: AbortSignal }): Promise<RoutingBundle>;
-export function writerAssignment(bundle: RoutingBundle): WriterAssignment;
-export function failoverNodes(bundle: RoutingBundle): WriterAssignment[];
+export function validateRoutingEvent(event: unknown): unknown;
 export function compareBundleVersions(left: number | string | undefined, right: number | string | undefined): number;
+export function writerAssignment(bundle: RoutingBundle): RoutingNode;
+export function failoverNodes(bundle: RoutingBundle): RoutingNode[];
+export function validateRoutingNode(node: RoutingNode, name?: string): RoutingNode;
+export function validateRoutingNodes(nodes: RoutingNode[], name?: string): RoutingNode[];
 export const CLIENT_DRAIN_TIMEOUT_MS: 45000;
 export function clientDrainTimeout(timeoutMs?: number): number;
-export function createQuiesceController(options?: { close?: () => Promise<void>; onChange?: (state: string) => void }): { state(): { state: string; active: number }; enter(): () => void; begin(): Promise<void>; end(): Promise<void>; close(): Promise<void> };
-export function createSqlVerifier(options: { query: QueryFunction }): { connectivity(): Promise<{ verified: boolean }>; schema(database: string): Promise<{ database: string; verified: boolean }>; account(user: string, host?: string): Promise<{ user: string; host: string; verified: boolean; grants: string[] }>; all(options?: { database?: string; user?: string; host?: string }): Promise<unknown> };
-export function createMaterializer(options?: Record<string, unknown>): unknown;
-export function createTelemetry(options?: { application?: string; credentialName?: string; database?: string; scopes?: string[]; intervalMs?: number; now?: () => number; setIntervalImpl?: typeof setInterval; clearIntervalImpl?: typeof clearInterval }): Telemetry;
+export function createTelemetry(options?: Record<string, unknown>): Telemetry;
+export class SqlClientError extends Error { code?: string; retryable?: boolean; cause?: unknown; }
+export class ClusterUnavailableError extends SqlClientError {}
+export class ServerUnavailableError extends SqlClientError {}
+export function classifyError(error: unknown): { retryable: boolean; code?: string };
+export function asSqlError(error: unknown): SqlClientError;

package/src/index.mjs

@@ -1,20 +1,8 @@
-export { createDb } from './client/managed.mjs';
-export { validateTokenContext } from './client/authorization-context.mjs';
-export { createDbFromBundle, profilesFromBundle } from './client/from-bundle.mjs';
-export { classifyQuery, routeFor } from './routing.mjs';
-export { validateProfile, redactedProfile } from './config.mjs';
 export { SqlClientError, ClusterUnavailableError, ServerUnavailableError, classifyError, asSqlError } from './errors.mjs';
 export { validateBundle, bundleExpired, bundleNeedsRefresh } from './bundle.mjs';
-export { createAdminSql } from './admin/sql.mjs';
-export { createMigrationRunner } from './admin/migrations.mjs';
-export { selectRouteNodes } from './routing/node-set.mjs';
-export { createRoutingStream } from './routing/stream-client.mjs';
-export { fetchRoutingBundle, DEFAULT_BUNDLE_PATH } from './routing/bundle-fetcher.mjs';
 export { validateRoutingEvent } from './routing/event-contract.mjs';
-export { writerAssignment, failoverNodes } from './routing/assignment.mjs';
 export { compareBundleVersions } from './routing/bundle-version.mjs';
+export { writerAssignment, failoverNodes } from './routing/assignment.mjs';
+export { validateRoutingNode, validateRoutingNodes } from './routing/node-validation.mjs';
 export { CLIENT_DRAIN_TIMEOUT_MS, clientDrainTimeout } from './lifecycle/drain-policy.mjs';
-export { createQuiesceController } from './lifecycle/quiesce.mjs';
-export { createSqlVerifier } from './verification/sql.mjs';
-export { createMaterializer } from './lifecycle/materializer.mjs';
 export { createTelemetry } from './telemetry.mjs';

package/src/client/authorization-context.mjs

@@ -1,9 +0,0 @@
-export function validateTokenContext(bundle, tokenContext = {}) {
-  if (!bundle || typeof bundle !== 'object') throw new TypeError('routing bundle is required');
-  for (const field of ['application', 'database', 'credentialName']) {
-    if (tokenContext[field] !== undefined && bundle[field] !== tokenContext[field]) throw new Error(`routing bundle ${field} does not match token context`);
-  }
-  if (tokenContext.identity !== undefined && bundle.identity !== tokenContext.identity) throw new Error('routing bundle identity does not match token context');
-  if (tokenContext.scopes !== undefined && (!Array.isArray(bundle.scopes) || tokenContext.scopes.some((scope) => !bundle.scopes.includes(scope)))) throw new Error('routing bundle scopes exceed token context');
-  return bundle;
-}

package/src/client/bundle-profiles.mjs

@@ -1,7 +0,0 @@
-import { validateRoutingNode } from '../routing/node-validation.mjs';
-
-export function bundleProfiles(bundle, route, base) {
-  if (route === 'primary' && bundle.writer?.host) return [bundle.writer, ...(bundle.failover ?? [])].map((node, index) => { const valid = validateRoutingNode(node, `primary assignment[${index}]`); return { ...base, host: valid.host, port: valid.port, weight: valid.weight }; });
-  const nodes = route === 'balanced' && bundle.readers?.length ? bundle.readers : bundle.routes?.[route] ?? [];
-  return nodes.map((node) => { const valid = validateRoutingNode(node, `${route} route node`); return { ...base, host: valid.host, port: valid.port, weight: valid.weight }; });
-}

package/src/client/create-db.mjs

@@ -1,53 +0,0 @@
-import { log as defaultLog } from '@eliware/common';
-import * as mysql from 'mysql2/promise';
-import { validateProfile, redactedProfile } from '../config.mjs';
-import { asSqlError } from '../errors.mjs';
-import { resolveCredentials, credentialContext } from '../credential-provider.mjs';
-import { validateBundle as validateBundleShape, bundleExpired, bundleNeedsRefresh } from '../bundle.mjs';
-import { createRouteFactory } from './route-factory.mjs';
-import { classifyQuery, routeFor } from '../routing.mjs';
-import { compareBundleVersions } from '../routing/bundle-version.mjs';
-import { clientDrainTimeout } from '../lifecycle/drain-policy.mjs';
-import { createTelemetry } from '../telemetry.mjs';
-import { createTimedOperation } from './telemetry-wrapper.mjs';
-import { validateTokenContext } from './authorization-context.mjs';
-
-const olderVersion = (candidate, current) => compareBundleVersions(candidate, current) < 0;
-
-export async function createDb({ primary, balanced, bundle, credentialProvider, mysqlLib = mysql, log = defaultLog, routing = 'auto', identity, tokenContext, quarantineMs = 5000, drainTimeoutMs = 45000, now = () => Date.now(), telemetry } = {}) {
-  if (!primary || typeof primary !== 'object') throw new TypeError('primary connection profile is required');
-  const credentials = await resolveCredentials(credentialProvider, credentialContext(primary, { identity }));
-  let primaryConfig = validateProfile({ ...primary, ...credentials }, 'primary');
-  if (!primaryConfig.user || typeof primaryConfig.password !== 'string') throw new TypeError('primary.user and primary.password are required');
-  let balancedConfig = balanced ? validateProfile({ ...primaryConfig, ...balanced, ...credentials }, 'balanced') : undefined;
-  if (credentials.user || credentials.password) {
-    primaryConfig = validateProfile({ ...primaryConfig, ...credentials }, 'primary');
-    if (balancedConfig) balancedConfig = validateProfile({ ...balancedConfig, ...credentials }, 'balanced');
-  }
-  const validateBundle = (candidate) => validateTokenContext(validateBundleShape(candidate), tokenContext);
-  let activeBundle = bundle ? validateBundle(bundle) : undefined;
-  const makeRoute = (route, fallback) => createRouteFactory({ bundle: activeBundle, now, mysqlLib, log, quarantineMs })(route, fallback);
-  let primaryPool = makeRoute('primary', primaryConfig);
-  let balancedPool = balancedConfig || activeBundle?.routes?.balanced ? makeRoute('balanced', balancedConfig ?? primaryConfig) : null;
-  const choose = (sql, options = {}) => options.connection ?? (routeFor(sql, options.route ?? routing) === 'balanced' && balancedPool ? balancedPool : primaryPool);
-  const metrics = telemetry === true ? createTelemetry({ application: bundle?.application ?? 'default', credentialName: bundle?.credentialName, database: bundle?.database, scopes: bundle?.scopes, now }) : telemetry;
-  const timed = createTimedOperation({ metrics, now });
-  const client = {
-    async query(sql, values, options) { return timed(async () => { const selected = choose(sql, options); try { return await selected.query(sql, values); } catch (error) { const requestedRoute = options?.route ?? routing; if (error.retryable && balancedPool && routeFor(sql, requestedRoute) === 'balanced' && classifyQuery(sql) === 'balanced') { metrics?.record?.({ retry: true }); return balancedPool.query(sql, values); } throw error; } }); },
-    async execute(sql, values, options) { return timed(async () => choose(sql, options).execute(sql, values)); },
-    async transaction(callback) { return timed(async () => { const node = primaryPool.choose(); const connection = await node.getConnection(); try { await connection.beginTransaction(); const tx = { query: (sql, values) => connection.query(sql, values), execute: (sql, values) => connection.execute(sql, values) }; const result = await callback(tx); await connection.commit(); return result; } catch (error) { await connection.rollback().catch(() => {}); throw asSqlError(error); } finally { connection.release(); } }); },
-    async health(route = 'primary') { const started = now(); const selected = route === 'balanced' && balancedPool ? balancedPool : primaryPool; const nodes = await selected.health(); return { ok: nodes.some((node) => node.ok), route: selected === balancedPool ? 'balanced' : 'primary', nodes, latencyMs: now() - started }; },
-    async refresh(nextBundle) { const candidate = validateBundle(nextBundle); if (bundleExpired(candidate, now())) throw new Error('routing bundle is expired'); if (olderVersion(candidate.bundleVersion, activeBundle?.bundleVersion)) return { bundleVersion: activeBundle?.bundleVersion, refreshRequired: bundleNeedsRefresh(activeBundle, now()) }; const previous = [primaryPool, balancedPool]; const credentials = candidate.credentials ?? { username: primaryConfig.user, password: primaryConfig.password }; const writer = candidate.writer ?? candidate.routes.primary?.[0]; const reader = candidate.readers?.[0] ?? candidate.routes.balanced?.[0]; activeBundle = candidate; if (writer) { primaryConfig = validateProfile({ ...primaryConfig, host: writer.host, port: writer.port, user: credentials.username, password: credentials.password, database: candidate.database }, 'primary'); primaryPool = makeRoute('primary', primaryConfig); } else { for (const node of primaryPool.nodes) node.drain?.(drainTimeoutMs); } if (reader) { balancedConfig = validateProfile({ ...primaryConfig, host: reader.host, port: reader.port }, 'balanced'); balancedPool = makeRoute('balanced', balancedConfig); } else if (balancedPool) { for (const node of balancedPool.nodes) node.drain?.(drainTimeoutMs); } await Promise.all(previous.filter(Boolean).filter((pool) => pool !== primaryPool && pool !== balancedPool).map((pool) => pool.close())); return { bundleVersion: activeBundle.bundleVersion ?? null, refreshRequired: bundleNeedsRefresh(activeBundle, now()) }; },
-    async attachRoutingStream(stream) { if (!stream?.connect) throw new TypeError('routing stream is required'); metrics?.start?.(stream); stream.setTelemetry?.(metrics); stream.setOnUpdate?.(async (event) => { const update = event.type === 'routing.update' ? event : event.type === 'routing.resync' ? event.bundle : undefined; if (update) await client.refresh({ ...activeBundle, ...update, database: update.database ?? activeBundle?.database ?? primaryConfig.database, credentials: update.credentials ?? activeBundle?.credentials, routes: update.routes ?? activeBundle?.routes, bundleVersion: update.bundleVersion ?? update.version ?? activeBundle?.bundleVersion, expiresAt: update.expiresAt ?? activeBundle?.expiresAt ?? new Date(now() + 60000).toISOString() }); if (event.type === 'routing.drain' || event.type === 'routing.shutdown') for (const pool of [primaryPool, balancedPool].filter(Boolean)) pool.drain(event.node, drainTimeoutMs); if (event.type === 'routing.recovery') for (const pool of [primaryPool, balancedPool].filter(Boolean)) pool.recover(event.node, drainTimeoutMs); }); await stream.connect(); return () => stream.close?.(); },
-    drain(host, timeoutMs = drainTimeoutMs) { const effectiveTimeout = clientDrainTimeout(timeoutMs); const pools = [primaryPool, balancedPool].filter(Boolean); pools.forEach((pool) => pool.drain(host, effectiveTimeout)); return { host, timeoutMs: effectiveTimeout, wait: () => Promise.all(pools.map((pool) => pool.waitForIdle(effectiveTimeout))), forceClose: () => Promise.all(pools.map((pool) => pool.forceClose(host))) }; },
-    availability() { const states = this.nodeStates(); const primaryAvailable = states.some((node) => node.route === 'primary' && node.available); return { state: primaryAvailable ? 'available' : 'cluster-unavailable', routes: { primary: primaryAvailable, balanced: states.some((node) => node.route === 'balanced' && node.available) } }; },
-    nodeStates() { return [primaryPool, balancedPool].filter(Boolean).flatMap((pool) => pool.nodes.map((node) => ({ host: node.host, port: node.port, route: pool === primaryPool ? 'primary' : 'balanced', state: node.state, active: node.active, available: node.available }))); },
-    setNodeAvailability(route, host, available) { const pool = route === 'balanced' ? balancedPool : primaryPool; pool?.setAvailability(host, available); },
-    bundle: () => activeBundle,
-    async close() { metrics?.stop?.(); await Promise.all([primaryPool.close(), balancedPool?.close()]); },
-    classify: classifyQuery,
-    telemetry: metrics, config: { primary: redactedProfile(primaryConfig), balanced: balancedConfig && redactedProfile(balancedConfig) }
-  };
-  log.debug?.('SQL client created', { balanced: Boolean(balancedPool), routing });
-  return client;
-}

package/src/client/from-bundle.mjs

@@ -1,14 +0,0 @@
-import { validateBundle } from '../bundle.mjs';
-
-export function profilesFromBundle(bundle) {
-  const valid = validateBundle(bundle);
-  const credentials = valid.credentials ?? {};
-  const base = { host: valid.routes.primary[0]?.host, port: valid.routes.primary[0]?.port, user: credentials.username, password: credentials.password, database: valid.database };
-  return { primary: base, balanced: valid.routes.balanced?.[0] ? { ...base, host: valid.routes.balanced[0].host, port: valid.routes.balanced[0].port } : undefined };
-}
-
-export async function createDbFromBundle({ bundle, createClient, ...options } = {}) {
-  const profiles = profilesFromBundle(bundle);
-       const factory = createClient ?? (await import('./create-db.mjs')).createDb;
-  return factory({ ...options, ...profiles, bundle, identity: bundle.identity });
-}

package/src/client/managed.mjs

@@ -1,15 +0,0 @@
-import { createDbFromBundle } from './from-bundle.mjs';
-import { fetchRoutingBundle } from '../routing/bundle-fetcher.mjs';
-import { createRoutingStream } from '../routing/stream-client.mjs';
-
-export async function createDb({ endpoint = process.env.ELERA_API_ENDPOINT, token = process.env.ELERA_API_TOKEN, fetchImpl = globalThis.fetch, fetchPath, WebSocketImpl = globalThis.WebSocket, ...options } = {}) {
-  const fetchBundle = () => fetchRoutingBundle({ endpoint, token, fetchImpl, path: fetchPath });
-  const bundle = await fetchBundle();
-  const stream = createRoutingStream({ endpoint, token, fetchBundle, WebSocketImpl, ...options });
-  const tokenContext = { application: bundle.application, database: bundle.database, credentialName: bundle.credentialName, identity: bundle.identity, scopes: bundle.scopes };
-  const client = await createDbFromBundle({ bundle, tokenContext, ...options });
-  const detach = await client.attachRoutingStream(stream);
-  const close = client.close.bind(client);
-  client.close = async () => { await detach?.(); await close(); };
-  return client;
-}

package/src/client/route-factory.mjs

@@ -1,14 +0,0 @@
-import { bundleExpired } from '../bundle.mjs';
-import { createNodePool, createRoutePool } from '../pools.mjs';
-import { bundleProfiles } from './bundle-profiles.mjs';
-
-const routeProfiles = (bundle, route, fallback, now) => {
-  if (!bundle) return [fallback];
-  if (bundleExpired(bundle, now())) return [fallback];
-  const profiles = bundleProfiles(bundle, route, fallback);
-  return profiles.length ? profiles : [fallback];
-};
-
-export function createRouteFactory({ bundle, now, mysqlLib, log, quarantineMs }) {
-  return (route, fallback) => createRoutePool(routeProfiles(bundle, route, fallback, now).map((profile) => createNodePool({ profile, mysqlLib, log, now, quarantineMs })), { preferred: route === 'primary' });
-}

package/src/client/telemetry-wrapper.mjs

@@ -1,15 +0,0 @@
-const emptyMetrics = { begin: () => undefined, record: () => {} };
-
-export function createTimedOperation({ metrics = emptyMetrics, now = () => Date.now() } = {}) {
-  return async function timed(operation) {
-    const started = metrics.begin();
-    try {
-      const result = await operation();
-      metrics.record({ latencyMs: started === undefined ? 0 : now() - started });
-      return result;
-    } catch (error) {
-      metrics.record({ latencyMs: started === undefined ? 0 : now() - started, failed: true });
-      throw error;
-    }
-  };
-}

package/src/config.mjs

@@ -1,31 +0,0 @@
-const integer = (value, name, { min = 0, max = 65535 } = {}) => {
-  const number = Number(value);
-  if (!Number.isInteger(number) || number < min || number > max) throw new TypeError(`${name} must be an integer between ${min} and ${max}`);
-  return number;
-};
-
-export function validateProfile(profile, name = 'connection') {
-  if (!profile || typeof profile !== 'object') throw new TypeError(`${name} profile is required`);
-  if (!profile.host || typeof profile.host !== 'string') throw new TypeError(`${name}.host is required`);
-  if (profile.user !== undefined && typeof profile.user !== 'string') throw new TypeError(`${name}.user must be a string`);
-  if (profile.password !== undefined && typeof profile.password !== 'string') throw new TypeError(`${name}.password must be a string`);
-  if (!profile.database || typeof profile.database !== 'string') throw new TypeError(`${name}.database is required`);
-  const port = integer(profile.port ?? 3306, `${name}.port`, { min: 1 });
-  const options = profile.options ?? {};
-  const connectionLimit = integer(options.connectionLimit ?? 10, `${name}.options.connectionLimit`, { min: 1, max: 1000 });
-  const queueLimit = integer(options.queueLimit ?? 0, `${name}.options.queueLimit`, { max: 1000000 });
-  const connectTimeout = integer(options.connectTimeout ?? 10000, `${name}.options.connectTimeout`, { max: 3600000 });
-  const acquireTimeout = integer(options.acquireTimeout ?? 10000, `${name}.options.acquireTimeout`, { max: 3600000 });
-  if (options.ssl !== undefined && typeof options.ssl !== 'object' && typeof options.ssl !== 'string') throw new TypeError(`${name}.options.ssl must be an object or string`);
-  return { ...profile, port, options: { ...options, connectionLimit, queueLimit, connectTimeout, acquireTimeout } };
-}
-
-export function redactedProfile(profile) {
-  const { password: _password, options = {}, ...safe } = profile;
-  const safeOptions = { ...options };
-  if (safeOptions.ssl && typeof safeOptions.ssl === 'object') {
-    safeOptions.ssl = { ...safeOptions.ssl };
-    for (const key of ['key', 'privateKey', 'passphrase']) delete safeOptions.ssl[key];
-  }
-  return { ...safe, options: safeOptions };
-}

package/src/credential-provider.mjs

@@ -1,12 +0,0 @@
-export async function resolveCredentials(provider, context) {
-  if (provider === undefined) return {};
-  if (typeof provider !== 'function') throw new TypeError('credentialProvider must be a function');
-  const result = await provider(context);
-  if (!result || typeof result !== 'object') throw new TypeError('credentialProvider must return an object');
-  if (typeof result.user !== 'string' || typeof result.password !== 'string') throw new TypeError('credentialProvider must return user and password');
-  return result;
-}
-
-export function credentialContext(primary, options) {
-  return { database: primary.database, identity: options.identity ?? null, route: options.route ?? 'primary' };
-}

package/src/pools/node-pool.mjs

@@ -1,23 +0,0 @@
-import { asSqlError } from '../errors.mjs';
-const connectionFailure = (error) => asSqlError(error).retryable;
-export function createNodePool({ profile, mysqlLib, log, now = () => Date.now(), quarantineMs = 5000 }) {
-  const { acquireTimeout: _acquireTimeout, ...driverOptions } = profile.options ?? {};
-  if (driverOptions.socketPath === undefined) delete driverOptions.socketPath;
-  const pool = mysqlLib.createPool({ host: profile.host, port: profile.port, user: profile.user, password: profile.password, database: profile.database, waitForConnections: true, ...driverOptions });
-  const sessionStatements = profile.options?.sessionStatements ?? [];
-  const withConnection = async (operation, sql, values) => { const connection = await pool.getConnection(); try { for (const statement of sessionStatements) await connection.query(statement); return operation(connection, sql, values); } finally { connection.release(); } };
-  let failures = 0; let unavailableUntil = 0; let forcedUnavailable = false; let lifecycle = 'ready'; let active = 0; let idleResolve; let drainTimer;
-  const begin = () => { active += 1; };
-  const end = () => { active = Math.max(0, active - 1); if (!active) idleResolve?.(); };
-  const run = async (work) => { begin(); try { return await work(); } finally { end(); } };
-  const drain = (timeoutMs = 45000) => { lifecycle = 'draining'; forcedUnavailable = true; unavailableUntil = Number.POSITIVE_INFINITY; clearTimeout(drainTimer); drainTimer = setTimeout(() => { void forceClose(); }, timeoutMs); drainTimer.unref?.(); return { state: lifecycle, active }; };
-  const waitForIdle = async (timeoutMs = 45000) => { if (!active) return true; await Promise.race([new Promise((resolve) => { idleResolve = resolve; }), new Promise((resolve) => setTimeout(resolve, timeoutMs))]); idleResolve = undefined; return active === 0; };
-  const forceClose = async () => { lifecycle = 'unavailable'; await pool.end(); };
-  const recover = () => { clearTimeout(drainTimer); drainTimer = undefined; lifecycle = 'recovering'; forcedUnavailable = false; unavailableUntil = 0; lifecycle = 'ready'; return lifecycle; };
-  return { host: profile.host, port: profile.port, weight: Number(profile.weight ?? 100), get available() { return lifecycle === 'ready' && !forcedUnavailable && now() >= unavailableUntil; }, set available(value) { if (value) recover(); else drain(); }, get failures() { return failures; }, get state() { return lifecycle; }, get active() { return active; }, drain, recover, waitForIdle, forceClose,
-    async query(sql, values) { if (!this.available) throw new Error(`SQL node ${profile.host} is unavailable`); try { const result = await run(() => sessionStatements.length ? withConnection((connection, statement, params) => connection.query(statement, params), sql, values) : pool.query(sql, values)); failures = 0; return result; } catch (error) { if (connectionFailure(error)) { failures += 1; unavailableUntil = now() + quarantineMs; log?.warn?.('SQL node quarantined', { host: profile.host, port: profile.port, error: error.message }); } throw asSqlError(error); } },
-    async execute(sql, values) { if (!this.available) throw new Error(`SQL node ${profile.host} is unavailable`); try { const result = await run(() => sessionStatements.length ? withConnection((connection, statement, params) => connection.execute(statement, params), sql, values) : pool.execute(sql, values)); failures = 0; return result; } catch (error) { if (connectionFailure(error)) { failures += 1; unavailableUntil = now() + quarantineMs; } throw asSqlError(error); } },
-    async getConnection() { if (!this.available) throw new Error(`SQL node ${profile.host} is unavailable`); try { const connection = await pool.getConnection(); begin(); const release = connection.release.bind(connection); let released = false; connection.release = () => { if (released) return; released = true; end(); release(); }; return connection; } catch (error) { if (connectionFailure(error)) unavailableUntil = now() + quarantineMs; throw asSqlError(error); } },
-    async health() { try { await pool.query('SELECT 1'); failures = 0; unavailableUntil = 0; return { ok: true, host: profile.host, port: profile.port }; } catch (error) { if (connectionFailure(error)) { failures += 1; unavailableUntil = now() + quarantineMs; } throw asSqlError(error); } },
-    async close() { clearTimeout(drainTimer); lifecycle = 'unavailable'; await pool.end(); } };
-}

package/src/pools/route-pool.mjs

@@ -1,47 +0,0 @@
-import { ClusterUnavailableError, ServerUnavailableError } from '../errors.mjs';
-
-export function createRoutePool(nodes, { preferred = false, unavailableError = nodes.length === 1 ? ServerUnavailableError : ClusterUnavailableError } = {}) {
-  let cursor = 0;
-  const candidates = () => nodes.filter((node) => node.available);
-  const choose = () => {
-    const available = candidates();
-    if (!available.length) throw new unavailableError('no eligible SQL nodes available');
-    if (preferred) return available[0];
-    const total = available.reduce((sum, node) => sum + Math.max(0, node.weight), 0);
-    if (!total) return available[cursor++ % available.length];
-    let target = cursor++ % total;
-    let selected = available[available.length - 1];
-    for (const node of available) {
-      const weight = Math.max(0, node.weight);
-      if (target < weight) {
-        selected = node;
-        break;
-      }
-      target -= weight;
-    }
-    return selected;
-  };
-  const setAvailability = (host, available) => {
-    for (const node of nodes) if (node.host === host) node.available = available;
-  };
-  const lifecycle = (host, state) => nodes.filter((node) => node.host === host).map((node) => state === 'draining' ? node.drain() : node.recover());
-  const drain = (host, timeoutMs) => { for (const node of nodes.filter((value) => value.host === host)) node.drain?.(timeoutMs); return lifecycle(host, 'draining'); };
-  const recover = (host) => lifecycle(host, 'recovering');
-  const waitForIdle = (timeoutMs) => Promise.all(nodes.map((node) => node.waitForIdle?.(timeoutMs) ?? true));
-  const forceClose = (host) => Promise.all(nodes.filter((node) => !host || node.host === host).map((node) => node.forceClose?.() ?? node.close()));
-  const query = (sql, values) => choose().query(sql, values);
-  const execute = (sql, values) => choose().execute(sql, values);
-  const health = async () => {
-    const results = [];
-    for (const node of nodes) {
-      try {
-        results.push(await node.health());
-      } catch (error) {
-        results.push({ ok: false, host: node.host, port: node.port, error: error.message });
-      }
-    }
-    return results;
-  };
-  const close = async () => Promise.all(nodes.map((node) => node.close()));
-  return { nodes, choose, setAvailability, drain, recover, waitForIdle, forceClose, query, execute, health, close };
-}

package/src/pools.mjs

@@ -1,3 +0,0 @@
-export { createNodePool } from './pools/node-pool.mjs';
-export { createRoutePool } from './pools/route-pool.mjs';
-/* istanbul ignore file -- barrel exports only. */

package/src/routing.mjs

@@ -1,15 +0,0 @@
-const READ_PATTERN = /^(SELECT|SHOW|DESCRIBE|DESC|EXPLAIN)\b/i;
-
-export function classifyQuery(sql) {
-  if (typeof sql !== 'string') return 'primary';
-  const statement = sql.trim().replace(/^(--[^\n]*\n|#[^\n]*\n|\/\*[\s\S]*?\*\/\s*)+/, '').trim();
-  if (!READ_PATTERN.test(statement) || statement.includes(';')) return 'primary';
-  if (/\b(FOR\s+UPDATE|LOCK\s+IN\s+SHARE\s+MODE|INTO\s+(OUTFILE|DUMPFILE)|CALL)\b/i.test(statement)) return 'primary';
-  return 'balanced';
-}
-
-export function routeFor(sql, requested = 'auto') {
-  if (requested === 'primary' || requested === 'balanced') return requested;
-  if (requested !== 'auto') throw new TypeError(`Unsupported SQL route: ${requested}`);
-  return classifyQuery(sql);
-}