@adminiumjs/engine 0.1.0-rc.1

package/dist/adapter-registry.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Adapter registry mechanics + the typed adapter error — the acyclic leaf
+ * under ./adapter.ts (the repo forbids circular imports, 01 §2.3).
+ *
+ * The public import path for everything here is `@adminium/engine/adapter`,
+ * which re-exports this module and binds the process-wide singleton
+ * `adapterRegistry` to the concrete `AdapterProvider` contract
+ * (01-architecture.md §2.3.1):
+ *
+ * ```ts
+ * import { adapterRegistry } from '@adminium/engine/adapter';
+ * import { postgresAdapter } from '@adminium/adapter-postgres';
+ *
+ * adapterRegistry.register(postgresAdapter); // dialect: 'postgres'
+ * ```
+ *
+ * v1.x adapters (MongoDB, MSSQL) plug into the same registry without
+ * touching engine internals.
+ */
+import type { Dialect } from './schema-model.js';
+export declare const ADAPTER_ERROR_CODES: readonly ["AUTH", "HOST_UNREACHABLE", "TLS", "PERMISSION", "TIMEOUT", "SCHEMA_DRIFT", "UNSUPPORTED", "UNKNOWN"];
+export type AdapterErrorCode = (typeof ADAPTER_ERROR_CODES)[number];
+/**
+ * The only error type adapter methods may reject with. The Studio wizard and
+ * the `diagnostics-readout` widget map `code` to remediation copy (e.g. the
+ * allowlist-IP hint per designs/System States).
+ */
+export declare class AdapterError extends Error {
+    readonly code: AdapterErrorCode;
+    /** Machine-oriented details (driver error code, host, …). */
+    readonly detail: string | null;
+    /** Human remediation hint. */
+    readonly hint: string | null;
+    constructor(code: AdapterErrorCode, message: string, options?: {
+        detail?: string;
+        hint?: string;
+        cause?: unknown;
+    });
+}
+/** The minimal shape the registry keys on; the full contract is `AdapterProvider` (./adapter.ts). */
+export interface DialectKeyed {
+    readonly dialect: Dialect;
+}
+export declare class AdapterRegistry<Provider extends DialectKeyed = DialectKeyed> {
+    #private;
+    /**
+     * Register a provider for its dialect. Registering the same dialect twice
+     * is a boot-composition bug and throws; call `unregister` first if a test
+     * genuinely needs to swap providers.
+     */
+    register(provider: Provider): void;
+    /** Look up a provider; throws a typed UNSUPPORTED error when absent. */
+    get(dialect: Dialect): Provider;
+    has(dialect: Dialect): boolean;
+    /** Registered dialects, in registration order. */
+    list(): Dialect[];
+    /** Remove one provider (tests, hot-swap). Returns whether it existed. */
+    unregister(dialect: Dialect): boolean;
+    /** Remove everything (tests only). */
+    clear(): void;
+}
+//# sourceMappingURL=adapter-registry.d.ts.map

package/dist/adapter-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-registry.d.ts","sourceRoot":"","sources":["../src/adapter-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAMjD,eAAO,MAAM,mBAAmB,iHAStB,CAAC;AACX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE;;;;GAIG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;gBAG3B,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAQpE;AAMD,qGAAqG;AACrG,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,qBAAa,eAAe,CAAC,QAAQ,SAAS,YAAY,GAAG,YAAY;;IAGvE;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAOlC,wEAAwE;IACxE,GAAG,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ;IAc/B,GAAG,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO;IAI9B,kDAAkD;IAClD,IAAI,IAAI,OAAO,EAAE;IAIjB,yEAAyE;IACzE,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO;IAIrC,sCAAsC;IACtC,KAAK,IAAI,IAAI;CAGd"}

package/dist/adapter-registry.js

@@ -0,0 +1,75 @@
+// ---------------------------------------------------------------------------
+// Typed errors (05 §3)
+// ---------------------------------------------------------------------------
+export const ADAPTER_ERROR_CODES = [
+    'AUTH',
+    'HOST_UNREACHABLE',
+    'TLS',
+    'PERMISSION',
+    'TIMEOUT',
+    'SCHEMA_DRIFT',
+    'UNSUPPORTED',
+    'UNKNOWN',
+];
+/**
+ * The only error type adapter methods may reject with. The Studio wizard and
+ * the `diagnostics-readout` widget map `code` to remediation copy (e.g. the
+ * allowlist-IP hint per designs/System States).
+ */
+export class AdapterError extends Error {
+    code;
+    /** Machine-oriented details (driver error code, host, …). */
+    detail;
+    /** Human remediation hint. */
+    hint;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'AdapterError';
+        this.code = code;
+        this.detail = options.detail ?? null;
+        this.hint = options.hint ?? null;
+    }
+}
+export class AdapterRegistry {
+    #providers = new Map();
+    /**
+     * Register a provider for its dialect. Registering the same dialect twice
+     * is a boot-composition bug and throws; call `unregister` first if a test
+     * genuinely needs to swap providers.
+     */
+    register(provider) {
+        if (this.#providers.has(provider.dialect)) {
+            throw new Error(`adapter for dialect "${provider.dialect}" is already registered`);
+        }
+        this.#providers.set(provider.dialect, provider);
+    }
+    /** Look up a provider; throws a typed UNSUPPORTED error when absent. */
+    get(dialect) {
+        const provider = this.#providers.get(dialect);
+        if (provider === undefined) {
+            const known = this.list();
+            throw new AdapterError('UNSUPPORTED', `no adapter registered for dialect "${dialect}"`, {
+                hint: known.length > 0
+                    ? `registered dialects: ${known.join(', ')}`
+                    : 'no adapters registered — did the server boot call register()?',
+            });
+        }
+        return provider;
+    }
+    has(dialect) {
+        return this.#providers.has(dialect);
+    }
+    /** Registered dialects, in registration order. */
+    list() {
+        return [...this.#providers.keys()];
+    }
+    /** Remove one provider (tests, hot-swap). Returns whether it existed. */
+    unregister(dialect) {
+        return this.#providers.delete(dialect);
+    }
+    /** Remove everything (tests only). */
+    clear() {
+        this.#providers.clear();
+    }
+}
+//# sourceMappingURL=adapter-registry.js.map

package/dist/adapter-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-registry.js","sourceRoot":"","sources":["../src/adapter-registry.ts"],"names":[],"mappings":"AAqBA,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,MAAM;IACN,kBAAkB;IAClB,KAAK;IACL,YAAY;IACZ,SAAS;IACT,cAAc;IACd,aAAa;IACb,SAAS;CACD,CAAC;AAGX;;;;GAIG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,IAAI,CAAmB;IAChC,6DAA6D;IACpD,MAAM,CAAgB;IAC/B,8BAA8B;IACrB,IAAI,CAAgB;IAE7B,YACE,IAAsB,EACtB,OAAe,EACf,UAA+D,EAAE;QAEjE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACnF,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC;QACrC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC;IACnC,CAAC;CACF;AAWD,MAAM,OAAO,eAAe;IACjB,UAAU,GAAG,IAAI,GAAG,EAAqB,CAAC;IAEnD;;;;OAIG;IACH,QAAQ,CAAC,QAAkB;QACzB,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CAAC,wBAAwB,QAAQ,CAAC,OAAO,yBAAyB,CAAC,CAAC;QACrF,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAClD,CAAC;IAED,wEAAwE;IACxE,GAAG,CAAC,OAAgB;QAClB,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC9C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;YAC1B,MAAM,IAAI,YAAY,CAAC,aAAa,EAAE,sCAAsC,OAAO,GAAG,EAAE;gBACtF,IAAI,EACF,KAAK,CAAC,MAAM,GAAG,CAAC;oBACd,CAAC,CAAC,wBAAwB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;oBAC5C,CAAC,CAAC,+DAA+D;aACtE,CAAC,CAAC;QACL,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,GAAG,CAAC,OAAgB;QAClB,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;IAED,kDAAkD;IAClD,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;IACrC,CAAC;IAED,yEAAyE;IACzE,UAAU,CAAC,OAAgB;QACzB,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACzC,CAAC;IAED,sCAAsC;IACtC,KAAK;QACH,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC;CACF"}

package/dist/adapter.d.ts

@@ -0,0 +1,384 @@
+/**
+ * The `DatabaseAdapter` contract — 05-introspection-engine.md §3, with the
+ * three-connection privilege model of 01-architecture.md §3.
+ *
+ * `@adminium/engine` defines this interface but never imports adapter
+ * packages; `@adminium/server` composes concrete adapters at boot through
+ * the registry (01-architecture.md §2.3.1, ./adapter-registry.ts). Adapter
+ * packages (`@adminium/adapter-postgres`, …) import ONLY
+ * `@adminium/engine/adapter` — this module — which re-exports the
+ * SchemaModel types they need.
+ *
+ * THE "SCHEMA ONLY" INVARIANT (05 §10): `introspect()` reads catalog
+ * metadata exclusively — never user rows. Row-touching methods (`sample`,
+ * `sampleColumn`, `query`, `mutate`, `count`) exist only on the post-setup
+ * `data`-role instance and are compile-time blocked on the `introspect`
+ * instance via `this` typing on the role-branded interface below (plus a
+ * runtime guard every implementation must add — tested by the shared
+ * adapter test kit, 05-T02).
+ */
+import { AdapterRegistry } from './adapter-registry.js';
+import type { AdapterError } from './adapter-registry.js';
+import type { AdapterCapabilities, DatabaseModel, Dialect, LogicalType } from './schema-model.js';
+/**
+ * The three logical connections per source (01-architecture.md §3):
+ * `introspect` (schema metadata only), `data` (CRUD on included tables),
+ * `meta` (adminium_* tables; owned by @adminium/meta and never handed to
+ * adapters in v1 — listed for completeness of the brand).
+ */
+export type ConnectionRole = 'introspect' | 'data' | 'meta';
+/**
+ * Role-branded connection config. The brand is what makes `introspect()`
+ * uncallable on a data-role instance (and vice versa) at compile time.
+ */
+export interface ConnectionConfig<Role extends ConnectionRole = ConnectionRole> {
+    readonly role: Role;
+    /**
+     * DSN for network dialects (`postgres://…`, `mysql://…`). SQLite accepts
+     * `sqlite:///abs/path.db`, `file:abs/path.db`, or a plain path via `file`.
+     */
+    readonly dsn?: string;
+    /** SQLite: absolute database file path (or ':memory:' for demo/test). */
+    readonly file?: string;
+    /** SQLite open mode; introspect instances always open readonly. */
+    readonly mode?: 'readonly' | 'readwrite';
+    /** Pool size hint (pg introspect role defaults to 5 — 05 §4.1). */
+    readonly poolMax?: number;
+    /** Per-statement timeout; defaults per dialect (05 §4). */
+    readonly statementTimeoutMs?: number;
+}
+export type IntrospectConnectionConfig = ConnectionConfig<'introspect'>;
+export type DataConnectionConfig = ConnectionConfig<'data'>;
+/** Result of `test()` — 05 §3. */
+export interface TestResult {
+    ok: boolean;
+    latencyMs: number;
+    serverVersion: string | null;
+    currentUser: string | null;
+    canWrite: boolean;
+    ssl: boolean;
+    error?: AdapterError;
+}
+/** Dialect-specific privilege probes (01-architecture.md §3). */
+export interface PrivilegeProbe {
+    canReadSchema: boolean;
+    canRead: boolean;
+    canWrite: boolean;
+    canDDL: boolean;
+}
+/**
+ * Result of `probeCapabilities()` — persisted on the connection row and
+ * driving UI honesty (a read-only data role renders the app read-only).
+ */
+export interface CapabilityProbeResult {
+    capabilities: AdapterCapabilities;
+    privileges: PrivilegeProbe;
+    serverVersion: string;
+    /** Current role/user with read-only detection for the connected role. */
+    currentRole: {
+        name: string;
+        readOnly: boolean;
+    };
+}
+export interface IntrospectOptions {
+    /** Default: all non-system (pg) / the connected db (mysql) / 'main' (sqlite). */
+    schemas?: string[];
+    /** Optional include-predicate applied after enumeration (e.g. > 2,000-table guard). */
+    tableFilter?: (table: {
+        schema: string;
+        name: string;
+    }) => boolean;
+    /** Default true — ESTIMATES only, never COUNT during setup (05 §10). */
+    collectRowEstimates?: boolean;
+    /** Default true where supported. */
+    collectActivityStats?: boolean;
+    /** Default 30_000 total, 15_000 per statement. */
+    timeoutMs?: number;
+}
+export interface TableRef {
+    /** null for dialects without schemas (mysql/sqlite). */
+    schema: string | null;
+    name: string;
+}
+/** Filter ops are whitelisted per LogicalType by the engine before compile. */
+export type FilterOp = 'eq' | 'neq' | 'lt' | 'lte' | 'gt' | 'gte' | 'in' | 'not-in' | 'like' | 'ilike' | 'contains' | 'starts-with' | 'ends-with' | 'between' | 'is-null' | 'is-not-null';
+/** AND/OR tree of column predicates (05 §3). Values always bind as parameters. */
+export type FilterSpec = {
+    and: FilterSpec[];
+} | {
+    or: FilterSpec[];
+} | {
+    not: FilterSpec;
+} | {
+    column: string;
+    op: FilterOp;
+    value?: unknown;
+};
+/** Declarative SELECT/aggregate for widgets & grids — compiled through Kysely. */
+export interface QuerySpec {
+    table: TableRef;
+    /** Default: non-secret columns. */
+    select?: string[];
+    aggregates?: {
+        fn: 'count' | 'sum' | 'avg' | 'min' | 'max';
+        column?: string;
+        as: string;
+    }[];
+    groupBy?: (string | {
+        bucket: 'day' | 'week' | 'month';
+        column: string;
+    })[];
+    filter?: FilterSpec;
+    orderBy?: {
+        column: string;
+        dir: 'asc' | 'desc';
+    }[];
+    /** Hard-capped at 1_000 by the engine. */
+    limit?: number;
+    offset?: number;
+}
+export type Row = Record<string, unknown>;
+export interface QueryResult {
+    rows: Row[];
+    /** Column meta for serialization quirks (e.g. mysql unsigned bigint → string). */
+    columns: {
+        name: string;
+        logicalType: LogicalType;
+    }[];
+    warnings?: string[];
+}
+export type MutationSpec = {
+    kind: 'insert';
+    table: TableRef;
+    values: Row | Row[];
+} | {
+    kind: 'update';
+    table: TableRef;
+    filter: FilterSpec;
+    values: Row;
+} | {
+    kind: 'delete';
+    table: TableRef;
+    filter: FilterSpec;
+};
+export interface MutationResult {
+    affected: number;
+    /** Mutated rows where the dialect supports RETURNING; null otherwise. */
+    returning: Row[] | null;
+}
+/** Sampling caps enforced by every implementation (05 §10). */
+export interface SampleOptions {
+    /** Default: non-secret, PII-masked columns. */
+    columns?: string[];
+    /** LIMIT ≤ 100; values truncated at 256 chars. */
+    limit?: number;
+    /** Recorded in adminium_audit_log. */
+    purpose: 'preview' | 'classify' | 'llm';
+}
+/**
+ * Options for the optional single-column sampler. `optIn: true` is a
+ * deliberate speed bump: row values leave the database ONLY when the caller
+ * explicitly acknowledges it (the user-facing "schema only, never your rows"
+ * promise applies to setup — this method must never run during setup and is
+ * always audit-logged).
+ */
+export interface ColumnSampleOptions {
+    /** Must be literally `true` — there is no implicit sampling. */
+    optIn: true;
+    /** LIMIT ≤ 100; values truncated at 256 chars. */
+    limit?: number;
+    purpose: 'preview' | 'classify' | 'llm';
+}
+/**
+ * Per-column metadata the caller hands to
+ * {@link DatabaseAdapter.collectTableStats}. The adapter needs the logical
+ * type (to decide ordered-type min/max and the distinct-count strategy) and
+ * the heuristic privacy flags: PII-suspected and secret columns NEVER
+ * contribute sampled cell values, even when sampling is opted in (06 §4.2).
+ */
+export interface StatsColumnInput {
+    name: string;
+    logicalType: LogicalType;
+    /** Heuristic PII suspicion (05 §7.2) — never yields sampled values. */
+    piiSuspected?: boolean;
+    /** Secret column (05 §7.1) — excluded from every value-touching statistic. */
+    secret?: boolean;
+}
+/**
+ * Options for {@link DatabaseAdapter.collectTableStats}. Sample-free by
+ * default: with `sampling` unset NO cell value ever leaves the database —
+ * only the aggregate statistics (row count, null fraction, distinct count)
+ * the shared-contract invariant permits (06 §1 invariant 5, §4.2).
+ */
+export interface CollectStatsOptions {
+    /**
+     * Columns to profile. When omitted the adapter returns only the row-count
+     * estimate — callers pass the classified column set so privacy flags and
+     * logical types are known without a second round trip.
+     */
+    columns?: StatsColumnInput[];
+    /**
+     * Sampling opt-in. `null`/omitted ⇒ sample-free (default): null-fraction and
+     * distinct-count aggregates only, never a single cell value. When set, up to
+     * `maxValuesPerColumn` most-common values plus min/max on ordered
+     * (numeric/temporal) types are collected — but NEVER for PII-suspected or
+     * secret columns.
+     */
+    sampling?: {
+        maxValuesPerColumn: number;
+    } | null;
+    /**
+     * Row-count ceiling above which per-column null-fraction / distinct-count
+     * fall back to `null` (unknown) instead of a full scan (06 §4.2 "capped
+     * tables → NULL"). Defaults to {@link STATS_MAX_SCAN_ROWS}.
+     */
+    maxScanRows?: number;
+}
+/** A JSON-native scalar a sampled/extent cell can hold (strings truncated). */
+export type StatsScalar = string | number | boolean | null;
+/** Per-column aggregate statistics (06 §4.2). */
+export interface ColumnStats {
+    column: string;
+    /** Fraction of NULL rows in `[0,1]`; `null` when not cheaply available. */
+    nullFraction: number | null;
+    /** Estimated distinct value count; `null` when unknown or capped. */
+    distinctCount: number | null;
+    /**
+     * Ordered-type extent. Present ONLY under sampling opt-in, for
+     * numeric/temporal columns, and NEVER for PII/secret columns. Lossless:
+     * bigint and decimal travel as strings.
+     */
+    min?: StatsScalar;
+    max?: StatsScalar;
+    /**
+     * Most-common values, most-frequent first. Present ONLY under sampling
+     * opt-in and NEVER for PII-suspected or secret columns (06 §4.2 privacy
+     * rule). Each value truncated at {@link STATS_SAMPLE_VALUE_MAX_CHARS} chars.
+     */
+    sampleValues?: StatsScalar[];
+}
+/** Result of {@link DatabaseAdapter.collectTableStats}. */
+export interface StatsResult {
+    table: TableRef;
+    /** Row-count estimate (may be exact — see `rowCountExact`); `null` if unknown. */
+    rowCountEstimate: number | null;
+    /** True when `rowCountEstimate` is an exact `COUNT(*)`, not an estimate. */
+    rowCountExact: boolean;
+    /** Per-column aggregates — one entry per requested column, in input order. */
+    columns: ColumnStats[];
+    /** True when any sampled values / min-max are present (opt-in was honored). */
+    sampled: boolean;
+    /** Non-fatal degradations (estimate unavailable, capped, permission gap). */
+    warnings?: string[];
+}
+/** Default cap on most-common sampled values per column (06 §4.2). */
+export declare const STATS_DEFAULT_SAMPLE_VALUES = 20;
+/** Sampled string values are truncated at this many characters (mirrors 05 §10). */
+export declare const STATS_SAMPLE_VALUE_MAX_CHARS = 256;
+/** Default row-count ceiling for full-scan null/distinct aggregates (06 §4.2). */
+export declare const STATS_MAX_SCAN_ROWS = 1000000;
+/** At/below this estimate an adapter prefers an exact COUNT(*) over a stale estimate (06 §4.2). */
+export declare const STATS_EXACT_COUNT_THRESHOLD = 50000;
+/** Per-LogicalType value converters between JS and the wire format. */
+export interface TypeSerializer {
+    /** JS value → driver parameter (e.g. bigint → string for mysql). */
+    toDb(value: unknown): unknown;
+    /** Driver value → serializable JS (int8/decimal → string, timestamps → ISO-8601 UTC). */
+    fromDb(value: unknown): unknown;
+}
+/**
+ * What `createQueryEngine()` hands the CRUD layer (08-server-api.md §3.7):
+ * everything dynamic Kysely needs for the data connection. The engine
+ * package does not depend on `kysely`, so the dialect is typed opaquely —
+ * `@adminium/server` (which owns the Kysely dependency) casts it to
+ * `kysely.Dialect` at the composition boundary.
+ */
+export interface QueryEngine {
+    /** A Kysely `Dialect` instance for the pooled data connection. */
+    dialect: unknown;
+    /** Identifier quoting rules — identifiers are still snapshot-validated first. */
+    identifiers: {
+        quote(identifier: string): string;
+        maxLength: number;
+    };
+    serializers: Partial<Record<LogicalType, TypeSerializer>>;
+    /** Tear down the underlying pool. */
+    destroy(): Promise<void>;
+}
+/** Workplan alias — 08-server-api.md calls this the CRUD "query port". */
+export type QueryPort = QueryEngine;
+/**
+ * One instance per logical connection (role). Methods carry `this` types so
+ * that `introspect()` type-checks only on an `'introspect'`-role instance
+ * and row-touching methods only on a `'data'`-role instance. Every method
+ * rejects with {@link AdapterError} on failure.
+ *
+ * No raw SQL escape hatch: identifiers are validated against the current
+ * schema snapshot before compilation (unknown table/column → typed
+ * `SCHEMA_DRIFT`), values are always parameterized.
+ */
+export interface DatabaseAdapter<Role extends ConnectionRole = ConnectionRole> {
+    readonly dialect: Dialect;
+    /** Static, dialect-level capabilities (probe refines per-connection). */
+    readonly capabilities: AdapterCapabilities;
+    readonly role: Role;
+    /** Lazy pool; throws AdapterError with a typed code. */
+    connect(config: ConnectionConfig<Role>): Promise<void>;
+    test(): Promise<TestResult>;
+    /** Runs on every connect/test; results persist on the connection row. */
+    probeCapabilities(): Promise<CapabilityProbeResult>;
+    /** SCHEMA ONLY — reads catalog/pragma namespaces exclusively (05 §10). */
+    introspect(this: DatabaseAdapter<'introspect'>, opts?: IntrospectOptions): Promise<DatabaseModel>;
+    /** Capped count: `cap` (default 100_001) renders as "100,000+". */
+    count(this: DatabaseAdapter<'data'>, table: TableRef, filter?: FilterSpec, opts?: {
+        cap?: number;
+    }): Promise<{
+        value: number;
+        capped: boolean;
+    }>;
+    /** Post-setup only; caps per 05 §10 (LIMIT ≤ 100, truncation, secret exclusion, PII masking). */
+    sample(this: DatabaseAdapter<'data'>, table: TableRef, opts: SampleOptions): Promise<Row[]>;
+    /** Optional single-column sampler; see {@link ColumnSampleOptions}. */
+    sampleColumn?(this: DatabaseAdapter<'data'>, table: TableRef, column: string, opts: ColumnSampleOptions): Promise<unknown[]>;
+    query(this: DatabaseAdapter<'data'>, spec: QuerySpec): Promise<QueryResult>;
+    /** insert/update/delete, returning rows where supported. */
+    mutate(this: DatabaseAdapter<'data'>, spec: MutationSpec): Promise<MutationResult>;
+    /**
+     * Collect aggregate statistics for LLM enrichment (06-llm-assist.md §4.2).
+     * Sample-free by default: with `opts.sampling` unset the result carries row
+     * counts, null fractions and distinct counts only — never a single cell
+     * value. Opt-in sampling adds most-common values and ordered min/max, but
+     * NEVER for PII-suspected or secret columns. Cheap-first per dialect
+     * (catalog estimates where available, bounded exact scans as fallback);
+     * an unavailable estimate returns `null`, never a wrong number.
+     */
+    collectTableStats(this: DatabaseAdapter<'data'>, table: TableRef, opts?: CollectStatsOptions): Promise<StatsResult>;
+    /** Release pools/handles; idempotent. */
+    close(): Promise<void>;
+}
+export type IntrospectAdapter = DatabaseAdapter<'introspect'>;
+export type DataAdapter = DatabaseAdapter<'data'>;
+/**
+ * What an adapter package exports and the server registers at boot
+ * (01-architecture.md §2.3.1): a factory keyed by dialect, plus the
+ * QueryPort factory the CRUD layer uses to obtain a Kysely dialect for the
+ * data connection without holding a full adapter instance.
+ */
+export interface AdapterProvider {
+    readonly dialect: Dialect;
+    /** Build an adapter instance for one role-branded connection. */
+    create<Role extends ConnectionRole>(config: ConnectionConfig<Role>): DatabaseAdapter<Role> | Promise<DatabaseAdapter<Role>>;
+    /** Build the CRUD query port for a data-role connection (08 §3.7). */
+    createQueryEngine(config: DataConnectionConfig): QueryEngine | Promise<QueryEngine>;
+}
+/** The process-wide registry the server boot sequence populates. */
+export declare const adapterRegistry: AdapterRegistry<AdapterProvider>;
+/** Convenience wrapper over {@link adapterRegistry}.register. */
+export declare function registerAdapter(provider: AdapterProvider): void;
+export declare function registerAdapter(dialect: Dialect, factory: Omit<AdapterProvider, 'dialect'>): void;
+/** Convenience wrapper over {@link adapterRegistry}.get. */
+export declare function getAdapter(dialect: Dialect): AdapterProvider;
+export * from './schema-model.js';
+export * from './capabilities.js';
+export * from './adapter-registry.js';
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}

package/dist/adapter.js

@@ -0,0 +1,54 @@
+/**
+ * The `DatabaseAdapter` contract — 05-introspection-engine.md §3, with the
+ * three-connection privilege model of 01-architecture.md §3.
+ *
+ * `@adminium/engine` defines this interface but never imports adapter
+ * packages; `@adminium/server` composes concrete adapters at boot through
+ * the registry (01-architecture.md §2.3.1, ./adapter-registry.ts). Adapter
+ * packages (`@adminium/adapter-postgres`, …) import ONLY
+ * `@adminium/engine/adapter` — this module — which re-exports the
+ * SchemaModel types they need.
+ *
+ * THE "SCHEMA ONLY" INVARIANT (05 §10): `introspect()` reads catalog
+ * metadata exclusively — never user rows. Row-touching methods (`sample`,
+ * `sampleColumn`, `query`, `mutate`, `count`) exist only on the post-setup
+ * `data`-role instance and are compile-time blocked on the `introspect`
+ * instance via `this` typing on the role-branded interface below (plus a
+ * runtime guard every implementation must add — tested by the shared
+ * adapter test kit, 05-T02).
+ */
+import { AdapterRegistry } from './adapter-registry.js';
+/** Default cap on most-common sampled values per column (06 §4.2). */
+export const STATS_DEFAULT_SAMPLE_VALUES = 20;
+/** Sampled string values are truncated at this many characters (mirrors 05 §10). */
+export const STATS_SAMPLE_VALUE_MAX_CHARS = 256;
+/** Default row-count ceiling for full-scan null/distinct aggregates (06 §4.2). */
+export const STATS_MAX_SCAN_ROWS = 1_000_000;
+/** At/below this estimate an adapter prefers an exact COUNT(*) over a stale estimate (06 §4.2). */
+export const STATS_EXACT_COUNT_THRESHOLD = 50_000;
+// ---------------------------------------------------------------------------
+// Registry binding (01-architecture.md §2.3.1)
+// ---------------------------------------------------------------------------
+/** The process-wide registry the server boot sequence populates. */
+export const adapterRegistry = new AdapterRegistry();
+export function registerAdapter(providerOrDialect, factory) {
+    if (typeof providerOrDialect === 'string') {
+        if (factory === undefined) {
+            throw new Error('registerAdapter(dialect, factory) requires a factory');
+        }
+        adapterRegistry.register({ dialect: providerOrDialect, ...factory });
+        return;
+    }
+    adapterRegistry.register(providerOrDialect);
+}
+/** Convenience wrapper over {@link adapterRegistry}.get. */
+export function getAdapter(dialect) {
+    return adapterRegistry.get(dialect);
+}
+// The './adapter' subpath is the single entry point adapter packages may
+// import (dep-cruiser matrix, 01-architecture.md §2.3) — re-export the
+// SchemaModel types, the capability matrix and the registry mechanics here.
+export * from './schema-model.js';
+export * from './capabilities.js';
+export * from './adapter-registry.js';
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAqRxD,sEAAsE;AACtE,MAAM,CAAC,MAAM,2BAA2B,GAAG,EAAE,CAAC;AAC9C,oFAAoF;AACpF,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAG,CAAC;AAChD,kFAAkF;AAClF,MAAM,CAAC,MAAM,mBAAmB,GAAG,SAAS,CAAC;AAC7C,mGAAmG;AACnG,MAAM,CAAC,MAAM,2BAA2B,GAAG,MAAM,CAAC;AAyHlD,8EAA8E;AAC9E,+CAA+C;AAC/C,8EAA8E;AAE9E,oEAAoE;AACpE,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,eAAe,EAAmB,CAAC;AAKtE,MAAM,UAAU,eAAe,CAC7B,iBAA4C,EAC5C,OAA0C;IAE1C,IAAI,OAAO,iBAAiB,KAAK,QAAQ,EAAE,CAAC;QAC1C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;QAC1E,CAAC;QACD,eAAe,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,iBAAiB,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;QACrE,OAAO;IACT,CAAC;IACD,eAAe,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC;AAC9C,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,UAAU,CAAC,OAAgB;IACzC,OAAO,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AACtC,CAAC;AAED,yEAAyE;AACzE,uEAAuE;AACvE,4EAA4E;AAC5E,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC"}

package/dist/capabilities.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Per-engine capability matrix — 05-introspection-engine.md §2.1/§4,
+ * research/gap-analysis.md §2.1 (M9-T04).
+ *
+ * The canonical static dialect-level `AdapterCapabilities` per source engine.
+ * Adapter packages re-export their slice (`POSTGRES_CAPABILITIES` etc. are
+ * `ENGINE_CAPABILITY_MATRIX.<dialect>`) so the wizard, the remap editor, and
+ * the adapters all degrade from the SAME facts; per-connection probes refine
+ * these at runtime (e.g. MariaDB 10.5+ RETURNING) but never contradict the
+ * static shape shown during setup.
+ *
+ * Alongside the raw flags, this module derives DEGRADATION NOTES — stable
+ * codes for the honesty copy Studio shows ("MySQL row counts are estimates",
+ * "SQLite enums are synthesized from CHECK constraints", "schema files have
+ * no live health"). Codes, not copy: user-facing text lives behind the
+ * dashboard's i18n layer.
+ */
+import type { AdapterCapabilities } from './schema-model.js';
+/** Engines a live connection can use ('generic' is import-only). */
+export declare const SOURCE_ENGINES: readonly ["postgres", "mysql", "sqlite"];
+export type SourceEngine = (typeof SOURCE_ENGINES)[number];
+/**
+ * Where a model's metadata came from, for degradation purposes: a live
+ * engine connection or a parsed schema file (no live database at all).
+ */
+export type CapabilitySource = {
+    kind: 'live';
+    engine: SourceEngine;
+} | {
+    kind: 'import';
+};
+/** The matrix (gap-analysis §2.1): one column per live engine. */
+export declare const ENGINE_CAPABILITY_MATRIX: Readonly<Record<SourceEngine, AdapterCapabilities>>;
+/** Import baseline (see above) — exported for parsers and the wizard. */
+export declare const IMPORT_BASE_CAPABILITIES: AdapterCapabilities;
+/** Static capabilities for a source (live engine column or import baseline). */
+export declare function capabilitiesForSource(source: CapabilitySource): AdapterCapabilities;
+/**
+ * Stable degradation-note codes. The dashboard maps each to translated copy;
+ * anything not listed for a source needs no caveat there.
+ */
+export declare const CAPABILITY_NOTE_CODES: readonly ["mysql-approximate-row-estimates", "mysql-weaker-fk-enum-metadata", "sqlite-check-enum-synthesis", "sqlite-no-comments", "import-no-row-counts", "import-no-live-health"];
+export type CapabilityNoteCode = (typeof CAPABILITY_NOTE_CODES)[number];
+/**
+ * Degradation notes for a source, derived from the matrix flags where the
+ * flags express the fact, with the per-engine specials (estimate drift,
+ * MyISAM) keyed explicitly. Order = display order.
+ */
+export declare function capabilityNotesForSource(source: CapabilitySource): CapabilityNoteCode[];
+/**
+ * How trustworthy `rowCountEstimate` is for a source — drives the wizard's
+ * row-count column: 'estimate' renders plain, 'approximate' with a leading ≈,
+ * 'none' as an em-dash with an explanation (never wrong data).
+ */
+export type RowEstimateQuality = 'estimate' | 'approximate' | 'none';
+export declare function rowEstimateQualityForSource(source: CapabilitySource): RowEstimateQuality;
+//# sourceMappingURL=capabilities.d.ts.map