@eliware/elera-lib 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+Eliware-authored code is licensed under the Apache License, Version 2.0.
+Third-party components retain their respective licenses; see
+THIRD-PARTY-NOTICES.md.
+
+Copyright 2026 Eliware
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not
+use this file except in compliance with the License. You may obtain a copy at:
+
+https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+License for the specific language governing permissions and limitations.

package/README.md

@@ -0,0 +1,74 @@
+# @eliware/elera-lib
+
+The alternative SQL client for Eliware applications. It provides generic
+primary/balanced MySQL or MariaDB routing without embedding Elera, HAProxy,
+backup, or GitOps policy. It is a v0.1.0 alternative to `@eliware/mysql`; the
+existing package is intentionally unchanged.
+
+`primary` is the preferred connection path. `balanced` is an optional alternate
+path. Both may accept writes; automatic routing sends only conservative,
+single-statement read queries to `balanced`. Transactions always use `primary`.
+
+```js
+import { createDbFromEnvironment } from '@eliware/elera-lib';
+const db = await createDbFromEnvironment();
+await db.query('SELECT 1');
+await db.close();
+```
+
+Environment variables: `MYSQL_PRIMARY_HOST` (or `MYSQL_HOST`),
+`MYSQL_PRIMARY_PORT` (or `MYSQL_PORT`), optional `MYSQL_BALANCED_HOST`,
+optional `MYSQL_BALANCED_PORT`, `MYSQL_USER`, `MYSQL_PASSWORD`, and
+`MYSQL_DATABASE`. Pool settings may be supplied with `MYSQL_CONNECT_TIMEOUT`,
+`MYSQL_ACQUIRE_TIMEOUT`, `MYSQL_CONNECTION_LIMIT`, `MYSQL_QUEUE_LIMIT`, and
+`MYSQL_SSL`. Configure primary and balanced routes explicitly; applications
+should not rely on ambiguous single-endpoint aliases.
+
+Routing bundles passed to `createDbFromBundle` use the normalized shape
+`routes.primary` and `routes.balanced`, each containing ordered `{ host, port,
+weight }` nodes. A bundle also carries `database`, `identity`, optional
+`credentials`, and `expiresAt`; `validateBundle` rejects expired or malformed
+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. 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.
+
+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.
+
+`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 SQL client and environment/bundle factories, 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.
+
+## Development
+
+```bash
+npm ci
+npm test
+npm run lint
+npm run typecheck
+npm run pack
+```

package/RELEASE_NOTES.md

@@ -0,0 +1,71 @@
+# Release notes
+
+## 0.1.0 — Baseline release
+
+`@eliware/elera-lib` is a generic MariaDB/MySQL client library for applications
+that need multiple connection routes without embedding supervisor, HAProxy,
+GitOps, backup, or CLI policy.
+
+### SQL client and pooling
+
+- Creates clients from explicit connection profiles or environment variables.
+- Creates clients from validated routing bundles.
+- Maintains independent bounded pools for primary and balanced routes.
+- Keeps the underlying MySQL driver and pool implementation private.
+- Supports `query`, `execute`, transactions, health checks, and graceful close.
+- Pins transactions to the primary route.
+- Preserves credentials while applying refreshed routing bundles.
+
+### Routing and failover
+
+- Classifies conservative, single-statement reads for balanced routing.
+- Sends writes and transactions to the primary route by default.
+- Supports explicit `primary`, `balanced`, and `auto` route selection.
+- Selects ordered, weighted candidate nodes from a routing bundle.
+- Quarantines unhealthy nodes and retries retryable connection failures.
+- Validates bundle shape and expiry before use.
+- Supports bundle refresh and refresh-needed checks.
+- Supports node recovery and re-admission after quarantine.
+
+### Routing-event transport
+
+- Provides a generic WebSocket routing-stream adapter.
+- Accepts versioned routing updates, drain events, and recovery events.
+- Falls back to a caller-provided REST bundle fetch when WebSockets are
+  unavailable or fail.
+- Sends no SQL statements, credentials, dumps, or application data over the
+  event stream.
+- Keeps supervisor-specific protocol decisions outside the library.
+
+### Lifecycle and maintenance
+
+- Provides connection-admission quiescing for graceful drains.
+- Stops new work while allowing active work to finish.
+- Supports deterministic pool shutdown and cleanup.
+- Provides bounded temporary-file materialization for caller-provided
+  operations, with mode `0600` and recursive cleanup in `finally` blocks.
+
+### Verification and administration
+
+- Provides generic connectivity, schema, account, and grant verification.
+- Provides SQL helpers for administrative and migration workflows.
+- Exposes structured error classification through `SqlClientError`,
+  `classifyError`, and `asSqlError`.
+- Supports injected drivers, credential providers, clocks, logging, and stream
+  transports for deterministic testing.
+
+### Security and scope
+
+- Redacts passwords and private TLS key material from profile representations.
+- Does not persist credentials, bearer tokens, age keys, or plaintext artifacts.
+- Does not expose supervisor-specific endpoints or CLI commands as library
+  policy.
+- Requires applications to provide their own credential and routing adapters.
+
+### Compatibility and validation
+
+- ESM package targeting Node.js 26 or newer.
+- TypeScript declarations are included with the package.
+- Existing `@eliware/mysql` is not modified or required.
+- Strict test coverage is maintained at 100% statements, branches, functions,
+  and lines with zero lint warnings.

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,5 @@
+# Third-party notices
+
+Eliware-authored code is Apache-2.0 licensed. `mysql2` and transitive npm
+dependencies retain their respective licenses as recorded in package metadata.
+Review the complete dependency tree before redistribution.

package/package.json

@@ -0,0 +1,51 @@
+{
+    "name": "@eliware/elera-lib",
+    "version": "0.1.0",
+    "description": "Eliware SQL client with primary and balanced connection routing",
+    "license": "Apache-2.0",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/eliware/elera-lib.git"
+    },
+    "type": "module",
+    "engines": {
+        "node": ">=26"
+    },
+    "exports": {
+        ".": {
+            "types": "./src/index.d.ts",
+            "import": "./src/index.mjs"
+        }
+    },
+    "files": [
+        "src",
+        "README.md",
+        "RELEASE_NOTES.md",
+        "LICENSE",
+        "THIRD-PARTY-NOTICES.md"
+    ],
+    "scripts": {
+        "test": "eliware-test",
+        "integration": "node scripts/integration.mjs",
+        "lint": "eliware-test --lint",
+        "check": "node --check src/index.mjs",
+        "contracts": "node scripts/verify-contracts.mjs",
+        "typecheck": "tsc --project tsconfig.json",
+        "pack": "npm pack --dry-run",
+        "audit": "npm audit --omit=dev --audit-level=moderate"
+    },
+    "dependencies": {
+        "@eliware/common": "^2.0.0",
+        "mysql2": "^3.24.2"
+    },
+    "devDependencies": {
+        "@eliware/test": "^2.0.0",
+        "@types/node": "^26.4.0",
+        "ajv": "^8.20.0",
+        "ajv-formats": "^3.0.1",
+        "typescript": "^7.0.2"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/src/admin/migrations.mjs

@@ -0,0 +1,27 @@
+export function createMigrationRunner({ query, migrations = [] }) {
+  if (typeof query !== 'function') throw new TypeError('query function is required');
+  if (!Array.isArray(migrations)) throw new TypeError('migrations must be an array');
+  const ordered = [...migrations].sort((a, b) => a.version - b.version);
+  return {
+    async status() {
+      const [rows] = await query('SELECT version, name FROM schema_migrations ORDER BY version');
+      return { applied: rows };
+    },
+    async migrate() {
+      await query('CREATE TABLE IF NOT EXISTS schema_migrations (version INT PRIMARY KEY, name VARCHAR(255) NOT NULL, applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP)');
+      const [rows] = await query('SELECT version FROM schema_migrations ORDER BY version');
+      const applied = new Set(rows.map((row) => Number(row.version)));
+      for (const migration of ordered) {
+        if (!Number.isInteger(migration.version) || !migration.name || !Array.isArray(migration.statements)) throw new TypeError('invalid migration');
+        if (applied.has(migration.version)) continue;
+        await query('START TRANSACTION');
+        try {
+          for (const statement of migration.statements) { if (typeof statement !== 'string' || !statement.trim()) throw new TypeError('migration statements must be non-empty strings'); await query(statement); }
+          await query('INSERT INTO schema_migrations (version, name) VALUES (?, ?)', [migration.version, migration.name]);
+          await query('COMMIT');
+        } catch (error) { try { await query('ROLLBACK'); } catch {} throw error; }
+      }
+      return this.status();
+    }
+  };
+}

package/src/admin/sql.mjs

@@ -0,0 +1,7 @@
+export function createAdminSql({ query }) {
+  if (typeof query !== 'function') throw new TypeError('query function is required');
+  return {
+    async transaction(work) { await query('START TRANSACTION'); try { const result = await work({ query }); await query('COMMIT'); return result; } catch (error) { try { await query('ROLLBACK'); } catch {} throw error; } },
+    async migration(statements = []) { return this.transaction(async ({ query: run }) => { for (const statement of statements) { if (typeof statement !== 'string' || !statement.trim()) throw new TypeError('migration statements must be non-empty strings'); await run(statement); } }); }
+  };
+}

package/src/bundle.mjs

@@ -0,0 +1,17 @@
+const routes = ['primary', 'balanced'];
+
+export function validateBundle(bundle) {
+  if (!bundle || typeof bundle !== 'object') throw new TypeError('routing bundle is required');
+  if (!bundle.expiresAt || Number.isNaN(Date.parse(bundle.expiresAt))) throw new TypeError('routing bundle expiresAt is required');
+  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] ?? []) {
+      if (!node.host || !Number.isInteger(Number(node.port)) || Number(node.port) < 1 || Number(node.port) > 65535) throw new TypeError(`invalid ${route} bundle node`);
+      if (node.weight !== undefined && (!Number.isFinite(Number(node.weight)) || Number(node.weight) < 0)) throw new TypeError(`invalid ${route} bundle weight`);
+    }
+  }
+  return bundle;
+}
+
+export function bundleExpired(bundle, now = Date.now()) { return Date.parse(bundle.expiresAt) <= now; }
+export function bundleNeedsRefresh(bundle, now = Date.now()) { return bundle.refreshAfter ? Date.parse(bundle.refreshAfter) <= now : bundleExpired(bundle, now); }

package/src/client/create-db.mjs

@@ -0,0 +1,39 @@
+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, bundleExpired, bundleNeedsRefresh } from '../bundle.mjs';
+import { createRouteFactory } from './route-factory.mjs';
+import { classifyQuery, routeFor } from '../routing.mjs';
+
+export async function createDb({ primary, balanced, bundle, credentialProvider, mysqlLib = mysql, log = defaultLog, routing = 'auto', identity, quarantineMs = 5000, now = () => Date.now() } = {}) {
+  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');
+  }
+  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 client = {
+    async query(sql, values, options) { const selected = choose(sql, options); try { return await selected.query(sql, values); } catch (error) { if (error.retryable && routeFor(sql, options?.route ?? routing) === 'balanced') return balancedPool.query(sql, values); throw error; } },
+    async execute(sql, values, options) { return choose(sql, options).execute(sql, values); },
+    async transaction(callback) { 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'); const previous = [primaryPool, balancedPool]; const credentials = candidate.credentials ?? { username: primaryConfig.user, password: primaryConfig.password }; primaryConfig = validateProfile({ ...primaryConfig, host: candidate.routes.primary[0]?.host, port: candidate.routes.primary[0]?.port, user: credentials.username, password: credentials.password, database: candidate.database }, 'primary'); balancedConfig = candidate.routes.balanced?.[0] ? validateProfile({ ...primaryConfig, host: candidate.routes.balanced[0].host, port: candidate.routes.balanced[0].port }, 'balanced') : undefined; activeBundle = candidate; primaryPool = makeRoute('primary', primaryConfig); balancedPool = balancedConfig ? makeRoute('balanced', balancedConfig) : null; await Promise.all(previous.filter(Boolean).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'); stream.setOnUpdate?.(async (event) => { if (event.type === 'routing.update' && event.routes?.primary?.length) await client.refresh({ ...activeBundle, database: event.database ?? activeBundle?.database ?? primaryConfig.database, credentials: event.credentials ?? activeBundle?.credentials, routes: event.routes, bundleVersion: event.bundleVersion ?? activeBundle?.bundleVersion, expiresAt: activeBundle?.expiresAt ?? new Date(now() + 60000).toISOString() }); for (const host of event.type === 'routing.drain' ? [event.node] : event.type === 'routing.recovery' ? [event.node] : []) { primaryPool.setAvailability(host, event.type === 'routing.recovery'); balancedPool?.setAvailability(host, event.type === 'routing.recovery'); } }); await stream.connect(); return () => stream.close?.(); },
+    bundle: () => activeBundle,
+    async close() { await Promise.all([primaryPool.close(), balancedPool?.close()]); },
+    classify: classifyQuery,
+    config: { primary: redactedProfile(primaryConfig), balanced: balancedConfig && redactedProfile(balancedConfig) }
+  };
+  log.debug?.('SQL client created', { balanced: Boolean(balancedPool), routing });
+  return client;
+}

package/src/client/environment.mjs

@@ -0,0 +1,7 @@
+import { createDb } from './create-db.mjs';
+
+export async function createDbFromEnvironment({ env = process.env, ...options } = {}) {
+  const primary = { host: env.MYSQL_PRIMARY_HOST ?? env.MYSQL_HOST, port: env.MYSQL_PRIMARY_PORT ?? env.MYSQL_PORT, user: env.MYSQL_USER, password: env.MYSQL_PASSWORD, database: env.MYSQL_DATABASE, options: { connectTimeout: env.MYSQL_CONNECT_TIMEOUT, acquireTimeout: env.MYSQL_ACQUIRE_TIMEOUT, connectionLimit: env.MYSQL_CONNECTION_LIMIT, queueLimit: env.MYSQL_QUEUE_LIMIT, ssl: env.MYSQL_SSL } };
+  const balanced = env.MYSQL_BALANCED_PORT ? { host: env.MYSQL_BALANCED_HOST ?? primary.host, port: env.MYSQL_BALANCED_PORT } : undefined;
+  return createDb({ ...options, primary, balanced });
+}

package/src/client/from-bundle.mjs

@@ -0,0 +1,14 @@
+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/route-factory.mjs

@@ -0,0 +1,18 @@
+import { bundleExpired } from '../bundle.mjs';
+import { createNodePool, createRoutePool } from '../pools.mjs';
+
+const bundleProfiles = (bundle, route, base) => {
+  const routes = bundle.routes?.[route] ?? [];
+  return routes.map((node) => ({ ...base, host: node.host, port: node.port, weight: node.weight }));
+};
+
+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 })));
+}

package/src/config.mjs

@@ -0,0 +1,31 @@
+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

@@ -0,0 +1,12 @@
+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/errors.mjs

@@ -0,0 +1,18 @@
+export class SqlClientError extends Error {
+  constructor(message, { code = 'SQL_CLIENT_ERROR', retryable = false, cause } = {}) {
+    super(message, { cause }); this.name = 'SqlClientError'; this.code = code; this.retryable = retryable;
+  }
+}
+
+export function classifyError(error) {
+  const code = error?.code;
+  if (['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'PROTOCOL_CONNECTION_LOST', 'PROTOCOL_ENQUEUE_AFTER_FATAL_ERROR'].includes(code)) return { code: 'CONNECTION_ERROR', retryable: true };
+  if (['ER_ACCESS_DENIED_ERROR', 'ER_DBACCESS_DENIED_ERROR'].includes(code)) return { code: 'AUTHENTICATION_ERROR', retryable: false };
+  return { code: code ?? 'SQL_ERROR', retryable: false };
+}
+
+export function asSqlError(error, message = 'SQL operation failed') {
+  if (error instanceof SqlClientError) return error;
+  const classification = classifyError(error);
+  return new SqlClientError(message, { ...classification, cause: error });
+}

package/src/index.d.ts

@@ -0,0 +1,66 @@
+import type { PoolOptions } from 'mysql2/promise';
+
+export interface ConnectionProfile {
+  host: string;
+  port?: number | string;
+  user?: string;
+  password?: string;
+  database: string;
+  options?: Partial<PoolOptions>;
+}
+
+export interface RoutingNode { host: string; port: number | string; weight?: number; }
+export interface RoutingBundle {
+  apiVersion?: string;
+  database?: string;
+  identity?: string;
+  credentials?: { username?: string; password?: string };
+  bundleVersion?: number | string;
+  expiresAt: string;
+  refreshAfter?: string;
+  routes: { primary?: RoutingNode[]; balanced?: RoutingNode[] };
+}
+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 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 }>;
+  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>;
+  config: { primary: ConnectionProfile; balanced?: ConnectionProfile };
+}
+
+export interface RoutingStream {
+  connect(): Promise<void>;
+  setOnUpdate(handler: (event: unknown) => void): void;
+  close(): void;
+  state(): { connected: boolean; expectedVersion: number };
+}
+
+export function createDb(options: { primary: ConnectionProfile; balanced?: Partial<ConnectionProfile>; bundle?: RoutingBundle; credentialProvider?: CredentialProvider; identity?: string; mysqlLib?: unknown; log?: unknown; routing?: 'auto' | 'primary' | 'balanced'; quarantineMs?: number; now?: () => number }): Promise<DbClient>;
+export function createDbFromEnvironment(options?: { env?: Record<string, string | undefined>; mysqlLib?: unknown; log?: unknown; routing?: 'auto' | 'primary' | 'balanced'; bundle?: RoutingBundle; credentialProvider?: CredentialProvider; identity?: string }): Promise<DbClient>;
+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 function classifyError(error: unknown): { retryable: boolean; code?: string };
+export function asSqlError(error: unknown): SqlClientError;
+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; application?: string; fetchBundle: (application: string) => Promise<RoutingBundle>; onUpdate?: (event: unknown) => void; onError?: (error: unknown) => void; reconnectMs?: number; maxReconnectMs?: number }): RoutingStream;
+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;

package/src/index.mjs

@@ -0,0 +1,14 @@
+export { createDb } from './client/create-db.mjs';
+export { createDbFromBundle, profilesFromBundle } from './client/from-bundle.mjs';
+export { createDbFromEnvironment } from './client/environment.mjs';
+export { classifyQuery, routeFor } from './routing.mjs';
+export { validateProfile, redactedProfile } from './config.mjs';
+export { SqlClientError, 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 { createQuiesceController } from './lifecycle/quiesce.mjs';
+export { createSqlVerifier } from './verification/sql.mjs';
+export { createMaterializer } from './lifecycle/materializer.mjs';

package/src/lifecycle/materializer.mjs

@@ -0,0 +1,16 @@
+import { randomUUID } from "node:crypto";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export function createMaterializer({ makeTemp = mkdtemp, write = writeFile, remove = rm, id = randomUUID } = {}) {
+  return {
+    async withFile(content, operation) {
+      if (typeof operation !== "function") throw new TypeError("materializer operation is required");
+      const directory = await makeTemp(join(tmpdir(), "elera-material-") );
+      const path = join(directory, id());
+      try { await write(path, content, { mode: 0o600 }); return await operation(path); }
+      finally { await remove(directory, { recursive: true, force: true }); }
+    }
+  };
+}

package/src/lifecycle/quiesce.mjs

@@ -0,0 +1,20 @@
+export function createQuiesceController({ close = async () => {}, onChange } = {}) {
+  let state = 'open';
+  let active = 0;
+  const publish = (next) => { state = next; onChange?.(state); };
+  const leave = () => { active = Math.max(0, active - 1); };
+  const enter = () => {
+    if (state !== 'open') throw Object.assign(new Error('SQL client is quiesced'), { code: 'QUIESCED' });
+    active += 1;
+    let left = false;
+    return () => { if (!left) { left = true; leave(); } };
+  };
+  const waitForIdle = async () => { while (active) await new Promise((resolve) => setTimeout(resolve, 10)); };
+  return {
+    state: () => ({ state, active }),
+    enter,
+    async begin() { publish('quiescing'); await waitForIdle(); publish('quiesced'); },
+    async end() { publish('open'); },
+    async close() { await close(); publish('closed'); }
+  };
+}

package/src/pools/node-pool.mjs

@@ -0,0 +1,15 @@
+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 ?? {};
+  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;
+  return { host: profile.host, port: profile.port, weight: Number(profile.weight ?? 100), get available() { return now() >= unavailableUntil; }, set available(value) { unavailableUntil = value ? 0 : now() + quarantineMs; }, get failures() { return failures; },
+    async query(sql, values) { try { const result = sessionStatements.length ? await withConnection((connection, statement, params) => connection.query(statement, params), sql, values) : await 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) { try { const result = sessionStatements.length ? await withConnection((connection, statement, params) => connection.execute(statement, params), sql, values) : await pool.execute(sql, values); failures = 0; return result; } catch (error) { if (connectionFailure(error)) { failures += 1; unavailableUntil = now() + quarantineMs; } throw asSqlError(error); } },
+    async getConnection() { try { return await pool.getConnection(); } 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() { await pool.end(); } };
+}

package/src/pools/route-pool.mjs

@@ -0,0 +1,39 @@
+export function createRoutePool(nodes) {
+  let cursor = 0;
+  const candidates = () => nodes.filter((node) => node.available);
+  const choose = () => {
+    const available = candidates();
+    if (!available.length) throw new Error('no eligible SQL nodes available');
+    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 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, query, execute, health, close };
+}

package/src/pools.mjs

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

package/src/routing/node-set.mjs

@@ -0,0 +1,6 @@
+import { validateBundle } from '../bundle.mjs';
+export function selectRouteNodes({ bundle, route = 'primary', now = Date.now() } = {}) {
+  validateBundle(bundle); if (Date.parse(bundle.expiresAt) <= now) throw new TypeError('routing bundle is expired');
+  const nodes = bundle.routes?.[route]; if (!Array.isArray(nodes) || nodes.length === 0) throw new TypeError(`routing bundle ${route} route is empty`);
+  return nodes.map(({ host, port, weight }) => ({ host, port: Number(port), ...(weight === undefined ? {} : { weight: Number(weight) }) }));
+}

package/src/routing/stream-client.mjs

@@ -0,0 +1,27 @@
+import { log as defaultLog } from '@eliware/common';
+
+export function createRoutingStream({ endpoint, token, application = 'default', fetchBundle, WebSocketImpl = globalThis.WebSocket, onUpdate, onError, reconnectMs = 1000, maxReconnectMs = 30000, now = () => Date.now() } = {}) {
+  if (!endpoint || typeof fetchBundle !== 'function') throw new TypeError('endpoint and fetchBundle are required');
+  let socket; let closed = false; let timer; let expectedVersion = 0; let delay = reconnectMs; let updateHandler = onUpdate;
+  const log = arguments[0]?.log ?? defaultLog;
+  const streamUrl = () => `${endpoint.replace(/^http/i, 'ws').replace(/\/$/, '')}/api/v1/routing/stream?application=${encodeURIComponent(application)}&token=${encodeURIComponent(token ?? '')}`;
+  async function fallback() { try { const bundle = await fetchBundle(application); onUpdate?.({ type: 'routing.resync', version: expectedVersion, bundle, receivedAt: now() }); } catch (error) { onError?.(error); log.warn?.('Routing REST fallback failed', { error }); } }
+  function schedule() { if (closed || timer) return; timer = setTimeout(() => { timer = undefined; void connect(); }, delay); delay = Math.min(maxReconnectMs, delay * 2); }
+  async function connect() {
+    if (closed || typeof WebSocketImpl !== 'function') { await fallback(); schedule(); return; }
+    try {
+      socket = new WebSocketImpl(streamUrl());
+      socket.onopen = () => { delay = reconnectMs; };
+      socket.onmessage = async ({ data }) => {
+        try {
+          const event = JSON.parse(data); const version = Number(event.version ?? 0);
+          if (expectedVersion && version > expectedVersion + 1) await fallback();
+          expectedVersion = Math.max(expectedVersion, version); updateHandler?.(event);
+        } catch (error) { onError?.(error); }
+      };
+      socket.onerror = (error) => { onError?.(error); };
+      socket.onclose = () => { socket = undefined; void fallback(); schedule(); };
+    } catch (error) { onError?.(error); await fallback(); schedule(); }
+  }
+  return { connect, setOnUpdate: (handler) => { updateHandler = handler; }, close: () => { closed = true; clearTimeout(timer); socket?.close?.(); }, state: () => ({ connected: socket?.readyState === 1, expectedVersion }) };
+}

package/src/routing.mjs

@@ -0,0 +1,15 @@
+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);
+}

package/src/verification/sql.mjs

@@ -0,0 +1,8 @@
+const literal = (value) => `'${String(value).replaceAll("'", "''")}'`;
+export function createSqlVerifier({ query } = {}) {
+  if (typeof query !== 'function') throw new TypeError('query function is required');
+  const connectivity = async () => { await query('SELECT 1 AS healthy'); return { verified: true }; };
+  const schema = async (database) => { const [rows] = await query(`SELECT SCHEMA_NAME FROM information_schema.SCHEMATA WHERE SCHEMA_NAME = ${literal(database)}`); return { database, verified: rows.length > 0 }; };
+  const account = async (user, host = '%') => { const [rows] = await query(`SHOW GRANTS FOR ${literal(user)}@${literal(host)}`); return { user, host, verified: rows.length > 0, grants: rows.map((row) => Object.values(row)[0]) }; };
+  return { connectivity, schema, account, async all({ database, user, host = '%' } = {}) { const [connection, structure, grants] = await Promise.all([connectivity(), schema(database), account(user, host)]); return { verified: connection.verified && structure.verified && grants.verified, connectivity: connection, schema: structure, account: grants }; } };
+}