@adminiumjs/adapter-postgres 0.1.0-rc.1

package/dist/query-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-engine.d.ts","sourceRoot":"","sources":["../src/query-engine.ts"],"names":[],"mappings":"AAYA,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,WAAW,EACjB,MAAM,0BAA0B,CAAC;AAUlC;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,GAAG,WAAW,CAoDpF"}

package/dist/query-engine.js

@@ -0,0 +1,73 @@
+/**
+ * `createQueryEngine()` — the Kysely dialect factory for the pooled data
+ * connection (05-introspection-engine.md §3 `QueryEngine`, 08-server-api.md
+ * §3.7 "query port").
+ *
+ * `@adminium/engine` does not depend on `kysely`, so `QueryEngine.dialect`
+ * is typed opaquely there; `@adminium/server` casts it to `kysely.Dialect`
+ * at the composition boundary. This package owns the concrete dependency.
+ */
+import { PostgresDialect } from 'kysely';
+import pg from 'pg';
+import { AdapterError, } from '@adminium/engine/adapter';
+import { PG_MAX_IDENTIFIER_LENGTH, postgresSerializers, quoteIdentifier, } from './serialization.js';
+const DEFAULT_DATA_POOL_MAX = 10;
+/**
+ * Build the CRUD query port for a data-role connection. Accepts a DSN string
+ * or the role-branded config (which must carry a `dsn`). The pool is lazy —
+ * no connection is opened until the first query — and `destroy()` tears it
+ * down idempotently.
+ */
+export function createQueryEngine(config) {
+    const dsn = typeof config === 'string' ? config : config.dsn;
+    if (dsn === undefined || dsn.length === 0) {
+        throw new AdapterError('UNKNOWN', 'postgres query engine requires a DSN', {
+            hint: 'pass a postgres:// connection string (TLS options honored from sslmode)',
+        });
+    }
+    const poolMax = typeof config === 'string' ? undefined : config.poolMax;
+    const pool = new pg.Pool({
+        connectionString: dsn,
+        max: poolMax ?? DEFAULT_DATA_POOL_MAX,
+    });
+    // Surface idle-client failures as pool-level noise, not process crashes —
+    // the same guard `createAdapter`'s pool carries in ./index.ts, which this
+    // pool was missing.
+    //
+    // `pg` emits 'error' on the POOL when a client dies while idle in the pool
+    // (nobody is awaiting a query, so there is no promise to reject). An EventEmitter
+    // 'error' event with no listener is rethrown as an uncaught exception, so a
+    // Postgres-side termination of an idle connection — failover, a restart, an
+    // admin `pg_terminate_backend`, `DROP DATABASE ... WITH (FORCE)`, or an idle
+    // timeout on the server — would take the whole Node process down rather than
+    // being retried on the next checkout. Every one of those is routine operational
+    // life for a long-lived data pool, and the pool recovers on its own: the dead
+    // client is discarded and the next `connect()` opens a fresh one.
+    //
+    // Found by the M7 Wave 4 verification pass: apps/server's crud.test.ts drops its
+    // test database WITH (FORCE) in `afterAll`, which terminates any client still
+    // closing (57P01). That surfaced as a *rare* unhandled error failing the whole
+    // `pnpm test` run — the harness merely reproduced, under load, what a production
+    // failover does on purpose.
+    pool.on('error', () => {
+        /* mapped when the next query fails */
+    });
+    // Structural cast: kysely's `PostgresPool` narrows `QueryResult.command`
+    // to a command-name union while `pg` types it as `string`. The runtime
+    // shapes are identical (kysely's own docs pass a `pg.Pool` here), and the
+    // dialect crosses the `QueryEngine` boundary as `unknown` anyway.
+    const kyselyPool = pool;
+    let destroyed = false;
+    return {
+        dialect: new PostgresDialect({ pool: kyselyPool }),
+        identifiers: { quote: quoteIdentifier, maxLength: PG_MAX_IDENTIFIER_LENGTH },
+        serializers: postgresSerializers,
+        async destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            await pool.end();
+        },
+    };
+}
+//# sourceMappingURL=query-engine.js.map

package/dist/query-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-engine.js","sourceRoot":"","sources":["../src/query-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,eAAe,EAA8B,MAAM,QAAQ,CAAC;AACrE,OAAO,EAAE,MAAM,IAAI,CAAC;AAEpB,OAAO,EACL,YAAY,GAGb,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,wBAAwB,EACxB,mBAAmB,EACnB,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAEjC;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAqC;IACrE,MAAM,GAAG,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;IAC7D,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,YAAY,CAAC,SAAS,EAAE,sCAAsC,EAAE;YACxE,IAAI,EAAE,yEAAyE;SAChF,CAAC,CAAC;IACL,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;IACxE,MAAM,IAAI,GAAG,IAAI,EAAE,CAAC,IAAI,CAAC;QACvB,gBAAgB,EAAE,GAAG;QACrB,GAAG,EAAE,OAAO,IAAI,qBAAqB;KACtC,CAAC,CAAC;IACH,0EAA0E;IAC1E,0EAA0E;IAC1E,oBAAoB;IACpB,EAAE;IACF,2EAA2E;IAC3E,kFAAkF;IAClF,4EAA4E;IAC5E,4EAA4E;IAC5E,6EAA6E;IAC7E,6EAA6E;IAC7E,gFAAgF;IAChF,8EAA8E;IAC9E,kEAAkE;IAClE,EAAE;IACF,iFAAiF;IACjF,8EAA8E;IAC9E,+EAA+E;IAC/E,iFAAiF;IACjF,4BAA4B;IAC5B,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;QACpB,sCAAsC;IACxC,CAAC,CAAC,CAAC;IAEH,yEAAyE;IACzE,uEAAuE;IACvE,0EAA0E;IAC1E,kEAAkE;IAClE,MAAM,UAAU,GAAG,IAAgD,CAAC;IAEpE,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,OAAO;QACL,OAAO,EAAE,IAAI,eAAe,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;QAClD,WAAW,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,wBAAwB,EAAE;QAC5E,WAAW,EAAE,mBAAmB;QAChC,KAAK,CAAC,OAAO;YACX,IAAI,SAAS;gBAAE,OAAO;YACtB,SAAS,GAAG,IAAI,CAAC;YACjB,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/serialization.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Identifier quoting + per-LogicalType value serialization for the Postgres
+ * data connection — 05-introspection-engine.md §3 (`QueryEngine`) and
+ * 08-server-api.md §3.7. Pure module (no `pg`/`kysely` import) so the policy
+ * is unit-testable offline.
+ *
+ * Serialization policy (05 §3 `TypeSerializer` contract):
+ * - `bigint` (int8) and `decimal` (numeric/money) travel as STRINGS end to
+ *   end — the pg driver already returns them as strings and JS numbers would
+ *   silently lose precision.
+ * - timestamps serialize to ISO-8601 UTC; `date`/`time` keep their SQL text
+ *   forms (`YYYY-MM-DD`, `HH:MM:SS`).
+ * - `json` values pass through as parsed objects; `toDb` stringifies so
+ *   Kysely binds a single jsonb parameter.
+ * - BYTEA POLICY: `binary` columns are EXCLUDED from CRUD v1 — no serializer
+ *   is registered for `'binary'`. Grids/forms never select bytea columns
+ *   (they render as an attachment placeholder); file/blob transfer arrives
+ *   with the dedicated attachment endpoints post-v1.
+ */
+import type { LogicalType, TypeSerializer } from '@adminium/engine/adapter';
+/** Postgres truncates identifiers at 63 bytes (NAMEDATALEN - 1). */
+export declare const PG_MAX_IDENTIFIER_LENGTH = 63;
+/**
+ * Double-quote an identifier, escaping embedded quotes. Identifiers are
+ * snapshot-validated before they ever reach this point (no raw SQL escape
+ * hatch — 05 §3); quoting is defense in depth, not sanitization.
+ */
+export declare function quoteIdentifier(identifier: string): string;
+/** Per-LogicalType converters handed to the CRUD layer via `QueryEngine`. */
+export declare const postgresSerializers: Partial<Record<LogicalType, TypeSerializer>>;
+//# sourceMappingURL=serialization.d.ts.map

package/dist/serialization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../src/serialization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE5E,oEAAoE;AACpE,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE1D;AA2BD,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,CAW5E,CAAC"}

package/dist/serialization.js

@@ -0,0 +1,47 @@
+/** Postgres truncates identifiers at 63 bytes (NAMEDATALEN - 1). */
+export const PG_MAX_IDENTIFIER_LENGTH = 63;
+/**
+ * Double-quote an identifier, escaping embedded quotes. Identifiers are
+ * snapshot-validated before they ever reach this point (no raw SQL escape
+ * hatch — 05 §3); quoting is defense in depth, not sanitization.
+ */
+export function quoteIdentifier(identifier) {
+    return `"${identifier.replaceAll('"', '""')}"`;
+}
+function toIsoUtc(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    return value;
+}
+/** `YYYY-MM-DD` from a driver-parsed Date (local calendar date, not UTC). */
+function toIsoDate(value) {
+    if (value instanceof Date) {
+        const month = String(value.getMonth() + 1).padStart(2, '0');
+        const day = String(value.getDate()).padStart(2, '0');
+        return `${value.getFullYear()}-${month}-${day}`;
+    }
+    return value;
+}
+function numericToDb(value) {
+    if (typeof value === 'bigint' || typeof value === 'number')
+        return value.toString();
+    return value;
+}
+const lossless = {
+    toDb: numericToDb,
+    fromDb: (value) => (typeof value === 'number' ? value.toString() : value),
+};
+/** Per-LogicalType converters handed to the CRUD layer via `QueryEngine`. */
+export const postgresSerializers = {
+    bigint: lossless,
+    decimal: lossless,
+    timestamp: { toDb: (value) => value, fromDb: toIsoUtc },
+    timestamptz: { toDb: (value) => value, fromDb: toIsoUtc },
+    date: { toDb: (value) => value, fromDb: toIsoDate },
+    json: {
+        toDb: (value) => (typeof value === 'string' ? value : JSON.stringify(value)),
+        fromDb: (value) => value,
+    },
+    // NOTE: no 'binary' entry on purpose — bytea is excluded from CRUD v1.
+};
+//# sourceMappingURL=serialization.js.map

package/dist/serialization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialization.js","sourceRoot":"","sources":["../src/serialization.ts"],"names":[],"mappings":"AAqBA,oEAAoE;AACpE,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,CAAC;AAE3C;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,UAAkB;IAChD,OAAO,IAAI,UAAU,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC;AACjD,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,KAAK,YAAY,IAAI;QAAE,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC;IACtD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,6EAA6E;AAC7E,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,KAAK,YAAY,IAAI,EAAE,CAAC;QAC1B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAC5D,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACrD,OAAO,GAAG,KAAK,CAAC,WAAW,EAAE,IAAI,KAAK,IAAI,GAAG,EAAE,CAAC;IAClD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC;IACpF,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,QAAQ,GAAmB;IAC/B,IAAI,EAAE,WAAW;IACjB,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;CAC1E,CAAC;AAEF,6EAA6E;AAC7E,MAAM,CAAC,MAAM,mBAAmB,GAAiD;IAC/E,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,QAAQ;IACjB,SAAS,EAAE,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE;IACvD,WAAW,EAAE,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE;IACzD,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE;IACnD,IAAI,EAAE;QACJ,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAC5E,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK;KACzB;IACD,uEAAuE;CACxE,CAAC"}

package/dist/stats.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Postgres table-statistics collector — 06-llm-assist.md §4.2.
+ *
+ * Cheap-first strategy (sample-free by default): row-count from
+ * `pg_class.reltuples` with an exact `COUNT(*)` fallback for small/stale
+ * tables; per-column null-fraction and distinct-count from `pg_stats` when the
+ * table has been analyzed, else a single bounded full-scan of aggregates
+ * (`SUM(col IS NULL)`, `COUNT(DISTINCT col)`) — aggregates only, never a cell
+ * value. `pg_stats.most_common_vals` is row data and is deliberately never
+ * read: concrete values appear ONLY under the sampling opt-in, and NEVER for
+ * PII-suspected or secret columns.
+ *
+ * Executor-agnostic (like introspect.ts): takes a `sql → rows` runner so the
+ * logic is unit-testable without the `pg` driver.
+ */
+import type { CollectStatsOptions, StatsResult, TableRef } from '@adminium/engine/adapter';
+/** Any `sql → rows` runner (the pg data pool in production). */
+export type StatsExecutor = (sql: string) => Promise<Record<string, unknown>[]>;
+/**
+ * Normalize `pg_stats.n_distinct`: `>0` is an absolute estimate, `<0` is the
+ * negative fraction of the row count, `0`/absent means unknown.
+ */
+export declare function normalizePgDistinct(nDistinct: number | null, rowCount: number | null): number | null;
+export declare function collectPostgresStats(exec: StatsExecutor, table: TableRef, opts?: CollectStatsOptions): Promise<StatsResult>;
+//# sourceMappingURL=stats.d.ts.map

package/dist/stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../src/stats.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EACV,mBAAmB,EAGnB,WAAW,EAEX,QAAQ,EACT,MAAM,0BAA0B,CAAC;AAUlC,gEAAgE;AAChE,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;AAmChF;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAKpG;AA8BD,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,QAAQ,EACf,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC,WAAW,CAAC,CAmItB"}

package/dist/stats.js

@@ -0,0 +1,195 @@
+import { STATS_DEFAULT_SAMPLE_VALUES, STATS_EXACT_COUNT_THRESHOLD, STATS_MAX_SCAN_ROWS, STATS_SAMPLE_VALUE_MAX_CHARS, } from '@adminium/engine/adapter';
+import { quoteIdentifier } from './serialization.js';
+/** Ordered logical types eligible for min/max under sampling opt-in. */
+const ORDERED_TYPES = new Set([
+    'integer',
+    'bigint',
+    'decimal',
+    'float',
+    'date',
+    'time',
+    'timestamp',
+    'timestamptz',
+]);
+function num(value) {
+    if (value === null || value === undefined)
+        return null;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : null;
+}
+function str(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function literal(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}
+function clampFraction(value) {
+    if (value === null)
+        return null;
+    if (value < 0)
+        return 0;
+    if (value > 1)
+        return 1;
+    return value;
+}
+/**
+ * Normalize `pg_stats.n_distinct`: `>0` is an absolute estimate, `<0` is the
+ * negative fraction of the row count, `0`/absent means unknown.
+ */
+export function normalizePgDistinct(nDistinct, rowCount) {
+    if (nDistinct === null || nDistinct === 0)
+        return null;
+    if (nDistinct > 0)
+        return Math.round(nDistinct);
+    if (rowCount === null)
+        return null;
+    return Math.round(Math.abs(nDistinct) * rowCount);
+}
+function toScalar(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        return value;
+    }
+    if (typeof value === 'bigint')
+        return value.toString();
+    if (value instanceof Date)
+        return value.toISOString();
+    if (value instanceof Uint8Array)
+        return '[binary]';
+    return String(value);
+}
+function truncate(value) {
+    if (typeof value === 'string' && value.length > STATS_SAMPLE_VALUE_MAX_CHARS) {
+        return value.slice(0, STATS_SAMPLE_VALUE_MAX_CHARS);
+    }
+    return value;
+}
+/** One batched full-scan: `COUNT(*)` + per-column null count + distinct count. */
+function buildNullDistinctScan(qualified, columns) {
+    const parts = columns.map((name, k) => {
+        const q = quoteIdentifier(name);
+        return `sum(CASE WHEN ${q} IS NULL THEN 1 ELSE 0 END)::int8 AS nf_${k}, count(DISTINCT ${q})::int8 AS dc_${k}`;
+    });
+    const cols = parts.length > 0 ? `, ${parts.join(', ')}` : '';
+    return `SELECT count(*)::int8 AS row_total${cols} FROM ${qualified}`;
+}
+export async function collectPostgresStats(exec, table, opts = {}) {
+    const schema = table.schema ?? 'public';
+    const name = table.name;
+    const qualified = `${quoteIdentifier(schema)}.${quoteIdentifier(name)}`;
+    const columns = opts.columns ?? [];
+    const sampling = opts.sampling ?? null;
+    const maxScanRows = opts.maxScanRows ?? STATS_MAX_SCAN_ROWS;
+    const warnings = [];
+    // 1. Row-count estimate from the catalog, exact COUNT for small/stale tables.
+    const relRows = await exec(`SELECT c.reltuples::float8 AS reltuples
+     FROM pg_catalog.pg_class c
+     JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+     WHERE n.nspname = ${literal(schema)} AND c.relname = ${literal(name)}
+     LIMIT 1`);
+    const reltuples = num(relRows[0]?.['reltuples']);
+    let rowCountEstimate;
+    let rowCountExact;
+    if (reltuples !== null && reltuples >= STATS_EXACT_COUNT_THRESHOLD) {
+        rowCountEstimate = Math.round(reltuples);
+        rowCountExact = false;
+    }
+    else {
+        // reltuples null / negative (never analyzed) / below threshold → exact count.
+        const countRows = await exec(`SELECT count(*)::int8 AS n FROM ${qualified}`);
+        rowCountEstimate = num(countRows[0]?.['n']);
+        rowCountExact = rowCountEstimate !== null;
+    }
+    // 2. Cheap per-column stats from pg_stats (never most_common_vals — row data).
+    const statByCol = new Map();
+    if (columns.length > 0) {
+        const statRows = await exec(`SELECT attname, null_frac::float8 AS null_frac, n_distinct::float8 AS n_distinct
+       FROM pg_catalog.pg_stats
+       WHERE schemaname = ${literal(schema)} AND tablename = ${literal(name)}`);
+        for (const row of statRows) {
+            const attname = str(row['attname']);
+            if (attname === null)
+                continue;
+            statByCol.set(attname, {
+                nullFrac: num(row['null_frac']),
+                nDistinct: num(row['n_distinct']),
+            });
+        }
+    }
+    const colStats = columns.map((c) => ({
+        column: c.name,
+        nullFraction: null,
+        distinctCount: null,
+    }));
+    const uncovered = [];
+    columns.forEach((c, i) => {
+        const covered = statByCol.get(c.name);
+        if (covered !== undefined) {
+            colStats[i].nullFraction = clampFraction(covered.nullFrac);
+            colStats[i].distinctCount = normalizePgDistinct(covered.nDistinct, rowCountEstimate);
+        }
+        else {
+            uncovered.push(i);
+        }
+    });
+    // 3. Full-scan fallback for un-analyzed columns on tables under the cap.
+    if (uncovered.length > 0) {
+        const scannable = rowCountEstimate !== null && rowCountEstimate <= maxScanRows;
+        if (scannable) {
+            const scanRows = await exec(buildNullDistinctScan(qualified, uncovered.map((i) => columns[i].name)));
+            const row = scanRows[0] ?? {};
+            const total = num(row['row_total']);
+            uncovered.forEach((ci, k) => {
+                const nulls = num(row[`nf_${k}`]);
+                colStats[ci].nullFraction =
+                    total === null || total === 0 ? (total === 0 ? 0 : null) : nulls === null ? null : nulls / total;
+                colStats[ci].distinctCount = num(row[`dc_${k}`]);
+            });
+        }
+        else {
+            warnings.push(`null-fraction/distinct-count skipped for ${uncovered.length} column(s): table exceeds maxScanRows and lacks analyzed statistics`);
+        }
+    }
+    // 4. Sampling opt-in — most-common values + ordered min/max; never PII/secret.
+    let sampled = false;
+    if (sampling !== null) {
+        const maxValues = sampling.maxValuesPerColumn > 0
+            ? Math.floor(sampling.maxValuesPerColumn)
+            : STATS_DEFAULT_SAMPLE_VALUES;
+        for (let i = 0; i < columns.length; i += 1) {
+            const c = columns[i];
+            if (c.piiSuspected === true || c.secret === true)
+                continue; // NEVER sample PII/secret.
+            const q = quoteIdentifier(c.name);
+            if (ORDERED_TYPES.has(c.logicalType)) {
+                // No ::text cast — ordered types are numeric/temporal; the driver
+                // returns numbers/dates that toScalar keeps JSON-native (bigint/decimal
+                // arrive as strings for lossless transport).
+                const mm = await exec(`SELECT min(${q}) AS lo, max(${q}) AS hi FROM ${qualified}`);
+                colStats[i].min = toScalar(mm[0]?.['lo']);
+                colStats[i].max = toScalar(mm[0]?.['hi']);
+                sampled = true;
+            }
+            const mcv = await exec(`SELECT ${q}::text AS v, count(*)::int8 AS c
+         FROM ${qualified}
+         WHERE ${q} IS NOT NULL
+         GROUP BY ${q}
+         ORDER BY count(*) DESC, ${q}
+         LIMIT ${maxValues}`);
+            colStats[i].sampleValues = mcv.map((r) => truncate(toScalar(r['v'])));
+            sampled = true;
+        }
+    }
+    const result = {
+        table: { schema: table.schema, name },
+        rowCountEstimate,
+        rowCountExact,
+        columns: colStats,
+        sampled,
+    };
+    if (warnings.length > 0)
+        result.warnings = warnings;
+    return result;
+}
+//# sourceMappingURL=stats.js.map

package/dist/stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.js","sourceRoot":"","sources":["../src/stats.ts"],"names":[],"mappings":"AAuBA,OAAO,EACL,2BAA2B,EAC3B,2BAA2B,EAC3B,mBAAmB,EACnB,4BAA4B,GAC7B,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAKrD,wEAAwE;AACxE,MAAM,aAAa,GAA6B,IAAI,GAAG,CAAc;IACnE,SAAS;IACT,QAAQ;IACR,SAAS;IACT,OAAO;IACP,MAAM;IACN,MAAM;IACN,WAAW;IACX,aAAa;CACd,CAAC,CAAC;AAEH,SAAS,GAAG,CAAC,KAAc;IACzB,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACvD,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IACxB,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACvC,CAAC;AAED,SAAS,GAAG,CAAC,KAAc;IACzB,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AACtE,CAAC;AAED,SAAS,OAAO,CAAC,KAAa;IAC5B,OAAO,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC;AAC5C,CAAC;AAED,SAAS,aAAa,CAAC,KAAoB;IACzC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC;IACxB,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC;IACxB,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAwB,EAAE,QAAuB;IACnF,IAAI,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvD,IAAI,SAAS,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAChD,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,QAAQ,CAAC,CAAC;AACpD,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACvD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;QACzF,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC;IACvD,IAAI,KAAK,YAAY,IAAI;QAAE,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC;IACtD,IAAI,KAAK,YAAY,UAAU;QAAE,OAAO,UAAU,CAAC;IACnD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED,SAAS,QAAQ,CAAC,KAAkB;IAClC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,4BAA4B,EAAE,CAAC;QAC7E,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,4BAA4B,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,kFAAkF;AAClF,SAAS,qBAAqB,CAAC,SAAiB,EAAE,OAA0B;IAC1E,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;QACpC,MAAM,CAAC,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;QAChC,OAAO,iBAAiB,CAAC,2CAA2C,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,EAAE,CAAC;IACjH,CAAC,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7D,OAAO,qCAAqC,IAAI,SAAS,SAAS,EAAE,CAAC;AACvE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,IAAmB,EACnB,KAAe,EACf,OAA4B,EAAE;IAE9B,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,QAAQ,CAAC;IACxC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IACxB,MAAM,SAAS,GAAG,GAAG,eAAe,CAAC,MAAM,CAAC,IAAI,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC;IACxE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;IACnC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC;IACvC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,mBAAmB,CAAC;IAC5D,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,8EAA8E;IAC9E,MAAM,OAAO,GAAG,MAAM,IAAI,CACxB;;;yBAGqB,OAAO,CAAC,MAAM,CAAC,oBAAoB,OAAO,CAAC,IAAI,CAAC;aAC5D,CACV,CAAC;IACF,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC;IACjD,IAAI,gBAA+B,CAAC;IACpC,IAAI,aAAsB,CAAC;IAC3B,IAAI,SAAS,KAAK,IAAI,IAAI,SAAS,IAAI,2BAA2B,EAAE,CAAC;QACnE,gBAAgB,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACzC,aAAa,GAAG,KAAK,CAAC;IACxB,CAAC;SAAM,CAAC;QACN,8EAA8E;QAC9E,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,mCAAmC,SAAS,EAAE,CAAC,CAAC;QAC7E,gBAAgB,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QAC5C,aAAa,GAAG,gBAAgB,KAAK,IAAI,CAAC;IAC5C,CAAC;IAED,+EAA+E;IAC/E,MAAM,SAAS,GAAG,IAAI,GAAG,EAAiE,CAAC;IAC3F,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,MAAM,IAAI,CACzB;;4BAEsB,OAAO,CAAC,MAAM,CAAC,oBAAoB,OAAO,CAAC,IAAI,CAAC,EAAE,CACzE,CAAC;QACF,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;YAC3B,MAAM,OAAO,GAAG,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;YACpC,IAAI,OAAO,KAAK,IAAI;gBAAE,SAAS;YAC/B,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE;gBACrB,QAAQ,EAAE,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;gBAC/B,SAAS,EAAE,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;aAClC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAkB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAClD,MAAM,EAAE,CAAC,CAAC,IAAI;QACd,YAAY,EAAE,IAAI;QAClB,aAAa,EAAE,IAAI;KACpB,CAAC,CAAC,CAAC;IACJ,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACvB,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,QAAQ,CAAC,CAAC,CAAE,CAAC,YAAY,GAAG,aAAa,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YAC5D,QAAQ,CAAC,CAAC,CAAE,CAAC,aAAa,GAAG,mBAAmB,CAAC,OAAO,CAAC,SAAS,EAAE,gBAAgB,CAAC,CAAC;QACxF,CAAC;aAAM,CAAC;YACN,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,yEAAyE;IACzE,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,SAAS,GAAG,gBAAgB,KAAK,IAAI,IAAI,gBAAgB,IAAI,WAAW,CAAC;QAC/E,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,QAAQ,GAAG,MAAM,IAAI,CACzB,qBAAqB,CACnB,SAAS,EACT,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC,IAAI,CAAC,CACvC,CACF,CAAC;YACF,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAC9B,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC;YACpC,SAAS,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE;gBAC1B,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;gBAClC,QAAQ,CAAC,EAAE,CAAE,CAAC,YAAY;oBACxB,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,KAAK,CAAC;gBACnG,QAAQ,CAAC,EAAE,CAAE,CAAC,aAAa,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;YACpD,CAAC,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,QAAQ,CAAC,IAAI,CACX,4CAA4C,SAAS,CAAC,MAAM,qEAAqE,CAClI,CAAC;QACJ,CAAC;IACH,CAAC;IAED,+EAA+E;IAC/E,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,MAAM,SAAS,GACb,QAAQ,CAAC,kBAAkB,GAAG,CAAC;YAC7B,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,kBAAkB,CAAC;YACzC,CAAC,CAAC,2BAA2B,CAAC;QAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3C,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAE,CAAC;YACtB,IAAI,CAAC,CAAC,YAAY,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI;gBAAE,SAAS,CAAC,2BAA2B;YACvF,MAAM,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YAClC,IAAI,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC;gBACrC,kEAAkE;gBAClE,wEAAwE;gBACxE,6CAA6C;gBAC7C,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,gBAAgB,CAAC,gBAAgB,SAAS,EAAE,CAAC,CAAC;gBACnF,QAAQ,CAAC,CAAC,CAAE,CAAC,GAAG,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;gBAC3C,QAAQ,CAAC,CAAC,CAAE,CAAC,GAAG,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;gBAC3C,OAAO,GAAG,IAAI,CAAC;YACjB,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,IAAI,CACpB,UAAU,CAAC;gBACH,SAAS;iBACR,CAAC;oBACE,CAAC;mCACc,CAAC;iBACnB,SAAS,EAAE,CACrB,CAAC;YACF,QAAQ,CAAC,CAAC,CAAE,CAAC,YAAY,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YACvE,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAgB;QAC1B,KAAK,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE;QACrC,gBAAgB;QAChB,aAAa;QACb,OAAO,EAAE,QAAQ;QACjB,OAAO;KACR,CAAC;IACF,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,CAAC,QAAQ,GAAG,QAAQ,CAAC;IACpD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/type-map.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Postgres dbType → portable LogicalType mapping — 05-introspection-engine.md
+ * §2.2 ("canonical table — extend, never fork"), Postgres column.
+ *
+ * Input is the verbatim `pg_catalog.format_type(atttypid, atttypmod)` string
+ * (e.g. `character varying(120)`, `timestamp with time zone`, `numeric(10,2)`)
+ * so the mapping is pure and unit-testable offline. Enum/domain/array
+ * resolution happens in the introspection assembler (it needs `pg_type`
+ * rows); this module only handles the base-name mapping plus the
+ * length/precision/scale extraction rules.
+ */
+import type { ColumnDefault, LogicalType } from '@adminium/engine/adapter';
+export interface MappedType {
+    logicalType: LogicalType;
+    maxLength: number | null;
+    numericPrecision: number | null;
+    numericScale: number | null;
+}
+/**
+ * Map a verbatim Postgres type string to its portable shape. Unmappable
+ * types become `'unknown'` with the verbatim `dbType` preserved by the
+ * caller (rendered read-only as text — 05 §2.2).
+ */
+export declare function mapPostgresType(dbType: string): MappedType;
+/**
+ * Classify a column default — 05 §4.1: `serial`/`nextval` and identity
+ * columns → `autoincrement`; `now()`/`CURRENT_TIMESTAMP` → `now`;
+ * `gen_random_uuid()`/`uuid_generate_v4()` → `uuid`.
+ *
+ * @param defaultExpr `pg_get_expr(adbin, adrelid)` output, or null.
+ * @param identity `pg_attribute.attidentity` ('' | 'a' | 'd').
+ */
+export declare function classifyDefault(defaultExpr: string | null, identity: string): ColumnDefault;
+//# sourceMappingURL=type-map.d.ts.map

package/dist/type-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-map.d.ts","sourceRoot":"","sources":["../src/type-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AA+D3E,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,WAAW,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAsBD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAoB1D;AAUD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,CAS3F"}

package/dist/type-map.js

@@ -0,0 +1,135 @@
+/** `format_type` base name (parenthesized modifiers stripped) → LogicalType. */
+const BASE_TYPE_MAP = {
+    // text family
+    text: 'text',
+    citext: 'text',
+    name: 'text',
+    'character varying': 'varchar',
+    varchar: 'varchar',
+    character: 'varchar',
+    char: 'varchar',
+    bpchar: 'varchar',
+    // integers (serial pseudo-types never appear in format_type output but are
+    // kept for defensive parsing of imported DDL strings)
+    smallint: 'integer',
+    integer: 'integer',
+    int2: 'integer',
+    int4: 'integer',
+    serial: 'integer',
+    smallserial: 'integer',
+    bigint: 'bigint',
+    int8: 'bigint',
+    bigserial: 'bigint',
+    oid: 'integer',
+    // exact + approximate numerics
+    numeric: 'decimal',
+    decimal: 'decimal',
+    money: 'decimal',
+    real: 'float',
+    float4: 'float',
+    'double precision': 'float',
+    float8: 'float',
+    // booleans
+    boolean: 'boolean',
+    bool: 'boolean',
+    // date/time
+    date: 'date',
+    'time without time zone': 'time',
+    'time with time zone': 'time',
+    time: 'time',
+    timetz: 'time',
+    'timestamp without time zone': 'timestamp',
+    timestamp: 'timestamp',
+    'timestamp with time zone': 'timestamptz',
+    timestamptz: 'timestamptz',
+    interval: 'interval',
+    // structured / misc
+    uuid: 'uuid',
+    json: 'json',
+    jsonb: 'json',
+    bytea: 'binary',
+    inet: 'inet',
+    cidr: 'inet',
+    // PostGIS (flag; rendered read-only as text in v1 — 05 §2.2)
+    geometry: 'geometry',
+    geography: 'geometry',
+};
+/** Binary-float precision constants surfaced by the catalogs. */
+const FLOAT4_PRECISION = 24;
+const FLOAT8_PRECISION = 53;
+/** Strip `(…)` modifiers, `[]` suffixes, and interval field qualifiers. */
+function baseTypeName(dbType) {
+    let base = dbType.trim().toLowerCase();
+    base = base.replace(/\[\s*\]\s*$/g, ''); // array suffix (possibly multi-dim already collapsed)
+    while (/\[\s*\]$/.test(base))
+        base = base.replace(/\[\s*\]$/, '');
+    base = base.replace(/\(([^)]*)\)/, '').replace(/\s+/g, ' ').trim();
+    if (base.startsWith('interval'))
+        return 'interval';
+    return base;
+}
+/** Extract `(n)` / `(p,s)` modifier numbers, when present. */
+function modifiers(dbType) {
+    const match = /\(([\d\s,]+)\)/.exec(dbType);
+    if (match?.[1] === undefined)
+        return [];
+    return match[1]
+        .split(',')
+        .map((part) => Number.parseInt(part.trim(), 10))
+        .filter((n) => Number.isFinite(n));
+}
+/**
+ * Map a verbatim Postgres type string to its portable shape. Unmappable
+ * types become `'unknown'` with the verbatim `dbType` preserved by the
+ * caller (rendered read-only as text — 05 §2.2).
+ */
+export function mapPostgresType(dbType) {
+    const base = baseTypeName(dbType);
+    const logicalType = BASE_TYPE_MAP[base] ?? 'unknown';
+    const mods = modifiers(dbType);
+    let maxLength = null;
+    let numericPrecision = null;
+    let numericScale = null;
+    if (logicalType === 'varchar' || logicalType === 'text') {
+        maxLength = mods[0] ?? null;
+    }
+    else if (logicalType === 'decimal') {
+        numericPrecision = mods[0] ?? null;
+        numericScale = mods[1] ?? null;
+    }
+    else if (logicalType === 'float') {
+        numericPrecision =
+            base === 'real' || base === 'float4' ? FLOAT4_PRECISION : FLOAT8_PRECISION;
+    }
+    return { logicalType, maxLength, numericPrecision, numericScale };
+}
+const NOW_DEFAULT = /^(now\(\)|current_timestamp(\(\d*\))?|transaction_timestamp\(\)|statement_timestamp\(\)|current_date|current_time(\(\d*\))?)/i;
+const UUID_DEFAULT = /^(gen_random_uuid\(\)|uuid_generate_v4\(\))/i;
+const AUTOINCREMENT_DEFAULT = /^nextval\(/i;
+/** `'…'::type`, bare numbers, booleans, or a typed NULL are literals. */
+const LITERAL_DEFAULT = /^('(?:[^']|'')*'(?:::[a-z_"][\w ."[\]]*(?:\(\d+(?:,\s*\d+)?\))?)?|-?\d+(\.\d+)?|true|false|NULL(?:::[a-z_"][\w ."[\]]*)?)$/i;
+/**
+ * Classify a column default — 05 §4.1: `serial`/`nextval` and identity
+ * columns → `autoincrement`; `now()`/`CURRENT_TIMESTAMP` → `now`;
+ * `gen_random_uuid()`/`uuid_generate_v4()` → `uuid`.
+ *
+ * @param defaultExpr `pg_get_expr(adbin, adrelid)` output, or null.
+ * @param identity `pg_attribute.attidentity` ('' | 'a' | 'd').
+ */
+export function classifyDefault(defaultExpr, identity) {
+    if (identity === 'a' || identity === 'd')
+        return { kind: 'autoincrement' };
+    if (defaultExpr === null || defaultExpr === '')
+        return null;
+    const text = defaultExpr.trim();
+    if (AUTOINCREMENT_DEFAULT.test(text))
+        return { kind: 'autoincrement' };
+    if (NOW_DEFAULT.test(text))
+        return { kind: 'now' };
+    if (UUID_DEFAULT.test(text))
+        return { kind: 'uuid' };
+    if (LITERAL_DEFAULT.test(text))
+        return { kind: 'literal', text };
+    return { kind: 'expression', text };
+}
+//# sourceMappingURL=type-map.js.map

package/dist/type-map.js.map

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

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@adminiumjs/adapter-postgres",
+  "version": "0.1.0-rc.1",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MoSofi/Adminium.git",
+    "directory": "packages/adapter-postgres"
+  },
+  "homepage": "https://adminium.dev",
+  "bugs": "https://github.com/MoSofi/Adminium/issues",
+  "type": "module",
+  "description": "PostgreSQL adapter",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@adminium/engine": "npm:@adminiumjs/engine@0.1.0-rc.1",
+    "kysely": "^0.28.2",
+    "pg": "^8.16.3"
+  },
+  "files": [
+    "dist"
+  ]
+}