@adminiumjs/adminium 0.1.0-rc.1

package/dist/connections/effective-schema.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Effective schema = active snapshot + active override ops applied in
+ * created_at order, later ops winning per (op, table, column) target
+ * (07-meta-store.md §3.15; M3-T06 read path). Pure functions — no I/O.
+ *
+ * The returned model is the snapshot's `DatabaseModel` JSON with
+ * display-layer fields attached (`label`, `hidden`, `excluded`, …). It is a
+ * reply/derived shape and is never re-parsed by the strict engine schema.
+ */
+import type { ColumnModel, DatabaseModel, Relation, TableModel } from '@adminium/engine';
+import type { SchemaOverride } from '@adminium/meta';
+export interface EffectiveColumn extends ColumnModel {
+    label?: string;
+    hidden?: boolean;
+    /** Resolved mask state (overrides > classifier default). */
+    masked?: boolean;
+    enumLabels?: Record<string, string>;
+    enumTones?: Record<string, string>;
+}
+export interface EffectiveTable extends Omit<TableModel, 'columns'> {
+    columns: EffectiveColumn[];
+    label?: string;
+    labelPlural?: string;
+    icon?: string;
+    excluded?: boolean;
+    keyField?: string;
+}
+export interface EffectiveRelation extends Relation {
+    label?: string;
+}
+export interface EffectiveModel extends Omit<DatabaseModel, 'tables' | 'relations'> {
+    tables: EffectiveTable[];
+    relations: EffectiveRelation[];
+}
+/**
+ * Effective table-label map (`tableName` → label) from active override rows.
+ * Provenance user > llm > heuristic (06 §8.3): a user `table.label` row beats
+ * an accepted `llm.label` bundle for the same table REGARDLESS of created_at
+ * order; within one origin, later rows win (§3.15). `llm.label` values are
+ * localized bundles — resolved to the connection's default locale (en_US).
+ *
+ * Shared by {@link applyOverrides} (the read path) and the generation
+ * pipeline (`generate/run.ts` overlays it onto the parsed model so generated
+ * page titles — and through `adminium_pages`, the sidebar nav — carry
+ * renames).
+ */
+export declare function activeTableLabels(overrides: readonly SchemaOverride[], defaultLocale?: string): Map<string, string>;
+export interface ApplyOverridesOptions {
+    /** Locale `llm.label` L10n bundles resolve to; en_US in v1. */
+    defaultLocale?: string;
+}
+/** Apply active override rows (already in created_at order) onto a snapshot model. */
+export declare function applyOverrides(model: DatabaseModel, overrides: readonly SchemaOverride[], opts?: ApplyOverridesOptions): EffectiveModel;
+/**
+ * Column mask/secret resolution for the serialization layer (08 §5.3).
+ * Source of truth: `column.pii` override rows; classifier `maskedByDefault`
+ * fills in when no row targets the column. `secret` columns are
+ * hard-excluded (05 §7.1 rule 1) and not unmaskable.
+ */
+export interface TableColumnPolicy {
+    masked: ReadonlySet<string>;
+    secret: ReadonlySet<string>;
+}
+export declare function columnPolicyFor(table: EffectiveTable): TableColumnPolicy;
+//# sourceMappingURL=effective-schema.d.ts.map

package/dist/connections/effective-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effective-schema.d.ts","sourceRoot":"","sources":["../../src/connections/effective-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,QAAQ,EAAe,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACtG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,cAAe,SAAQ,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC;IACjE,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAkB,SAAQ,QAAQ;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAe,SAAQ,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,WAAW,CAAC;IACjF,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,SAAS,EAAE,iBAAiB,EAAE,CAAC;CAChC;AAiBD;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,SAAS,cAAc,EAAE,EACpC,aAAa,GAAE,MAAuB,GACrC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAwBrB;AAED,MAAM,WAAW,qBAAqB;IACpC,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,sFAAsF;AACtF,wBAAgB,cAAc,CAC5B,KAAK,EAAE,aAAa,EACpB,SAAS,EAAE,SAAS,cAAc,EAAE,EACpC,IAAI,GAAE,qBAA0B,GAC/B,cAAc,CA6JhB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC5B,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,iBAAiB,CAcxE"}

package/dist/connections/effective-schema.js

@@ -0,0 +1,249 @@
+/**
+ * Effective schema = active snapshot + active override ops applied in
+ * created_at order, later ops winning per (op, table, column) target
+ * (07-meta-store.md §3.15; M3-T06 read path). Pure functions — no I/O.
+ *
+ * The returned model is the snapshot's `DatabaseModel` JSON with
+ * display-layer fields attached (`label`, `hidden`, `excluded`, …). It is a
+ * reply/derived shape and is never re-parsed by the strict engine schema.
+ */
+function tableId(table) {
+    return table.id;
+}
+/** Locale every connection resolves L10n bundles to in v1 (06 §6.1: always required). */
+const DEFAULT_LOCALE = 'en_US';
+/** Resolve one §8.3 locale→string map to `locale`, falling back to en_US. */
+function resolveLocalized(map, locale) {
+    if (typeof map !== 'object' || map === null || Array.isArray(map))
+        return null;
+    const rec = map;
+    const candidate = rec[locale] ?? rec[DEFAULT_LOCALE];
+    return typeof candidate === 'string' && candidate.length > 0 ? candidate : null;
+}
+/**
+ * Effective table-label map (`tableName` → label) from active override rows.
+ * Provenance user > llm > heuristic (06 §8.3): a user `table.label` row beats
+ * an accepted `llm.label` bundle for the same table REGARDLESS of created_at
+ * order; within one origin, later rows win (§3.15). `llm.label` values are
+ * localized bundles — resolved to the connection's default locale (en_US).
+ *
+ * Shared by {@link applyOverrides} (the read path) and the generation
+ * pipeline (`generate/run.ts` overlays it onto the parsed model so generated
+ * page titles — and through `adminium_pages`, the sidebar nav — carry
+ * renames).
+ */
+export function activeTableLabels(overrides, defaultLocale = DEFAULT_LOCALE) {
+    const labels = new Map();
+    const userLabeled = new Set();
+    for (const row of overrides) {
+        if (row.status !== 'active')
+            continue;
+        const op = row.op;
+        if (op === 'table.label') {
+            // ANY active user row locks the table against llm bundles — including a
+            // degenerate empty label (the write path now rejects '', but legacy rows
+            // may exist). '' acts as an explicit clear so §3.15 later-row-wins holds
+            // verbatim without ever emitting a label the engine's min(1) forbids.
+            userLabeled.add(row.tableName);
+            const label = row.value.label;
+            if (typeof label === 'string' && label.length > 0) {
+                labels.set(row.tableName, label);
+            }
+            else {
+                labels.delete(row.tableName);
+            }
+        }
+        else if (op === 'llm.label' && row.columnName === null && !userLabeled.has(row.tableName)) {
+            const resolved = resolveLocalized(row.value.label, defaultLocale);
+            if (resolved !== null)
+                labels.set(row.tableName, resolved);
+        }
+    }
+    return labels;
+}
+/** Apply active override rows (already in created_at order) onto a snapshot model. */
+export function applyOverrides(model, overrides, opts = {}) {
+    const locale = opts.defaultLocale ?? DEFAULT_LOCALE;
+    const effective = structuredClone(model);
+    const tables = new Map(effective.tables.map((t) => [tableId(t), t]));
+    const columnOf = (table, name) => table?.columns.find((c) => c.name === name);
+    // Provenance user > llm for COLUMN labels too: a user `column.label` row
+    // locks its column against the llm bundle regardless of created_at order.
+    const userLabeledColumns = new Set();
+    for (const row of overrides) {
+        if (row.status === 'active' && row.op === 'column.label' && row.columnName !== null) {
+            userLabeledColumns.add(`${row.tableName}\u0000${row.columnName}`);
+        }
+    }
+    for (const row of overrides) {
+        if (row.status !== 'active')
+            continue;
+        const table = tables.get(row.tableName);
+        const value = row.value;
+        switch (row.op) {
+            case 'table.label': {
+                if (table === undefined)
+                    break;
+                // Empty label = explicit clear (legacy rows only — the write path
+                // rejects ''); mirrors activeTableLabels so both paths agree.
+                const label = value.label;
+                if (typeof label === 'string' && label.length > 0)
+                    table.label = label;
+                else
+                    delete table.label;
+                if (typeof value.labelPlural === 'string')
+                    table.labelPlural = value.labelPlural;
+                if (typeof value.icon === 'string')
+                    table.icon = value.icon;
+                break;
+            }
+            case 'table.exclude': {
+                if (table !== undefined)
+                    table.excluded = value.excluded === true;
+                break;
+            }
+            case 'table.keyField': {
+                if (table !== undefined)
+                    table.keyField = value.column;
+                break;
+            }
+            case 'column.label': {
+                const column = columnOf(table, row.columnName);
+                if (column === undefined)
+                    break;
+                // Same '' = explicit clear normalization as table.label; the row still
+                // locks the column against llm bundles via userLabeledColumns.
+                const label = value.label;
+                if (typeof label === 'string' && label.length > 0)
+                    column.label = label;
+                else
+                    delete column.label;
+                break;
+            }
+            case 'column.semanticType': {
+                const column = columnOf(table, row.columnName);
+                if (column === undefined)
+                    break;
+                const semantics = column.semantics ?? {
+                    primary: 'plain',
+                    flags: { secret: false, pii: null, maskedByDefault: false },
+                    format: null,
+                    pair: null,
+                    confidence: 1,
+                    source: 'override',
+                };
+                column.semantics = {
+                    ...semantics,
+                    primary: value.semanticType,
+                    confidence: 1,
+                    source: 'override',
+                };
+                break;
+            }
+            case 'column.enumLabels': {
+                const column = columnOf(table, row.columnName);
+                if (column === undefined)
+                    break;
+                column.enumLabels = value.labels;
+                if (value.tones !== undefined)
+                    column.enumTones = value.tones;
+                break;
+            }
+            case 'column.pii': {
+                const column = columnOf(table, row.columnName);
+                if (column === undefined)
+                    break;
+                column.masked = value.masked === true;
+                if (column.semantics !== null && typeof value.kind === 'string') {
+                    column.semantics = {
+                        ...column.semantics,
+                        flags: { ...column.semantics.flags, pii: value.kind, maskedByDefault: value.masked === true },
+                    };
+                }
+                break;
+            }
+            case 'column.hidden': {
+                const column = columnOf(table, row.columnName);
+                if (column !== undefined)
+                    column.hidden = value.hidden === true;
+                break;
+            }
+            case 'llm.label': {
+                // §8.3 label bundle (origin 'llm'): `value.label` is a locale→string
+                // map; table-scoped when columnName is null, column-scoped otherwise.
+                // Silently skipped before M11 — the accepted rename never reached the
+                // effective model. TABLE labels are folded in by the post-loop
+                // `activeTableLabels` pass (single home for the user>llm precedence);
+                // only the column scope is handled here.
+                if (row.columnName === null)
+                    break;
+                if (userLabeledColumns.has(`${row.tableName}\u0000${row.columnName}`))
+                    break;
+                const column = columnOf(table, row.columnName);
+                if (column === undefined)
+                    break;
+                const resolved = resolveLocalized(value.label, locale);
+                if (resolved !== null)
+                    column.label = resolved;
+                break;
+            }
+            case 'relation.add': {
+                const from = row.tableName;
+                const relation = {
+                    id: `override:${from}.${String(value.fromColumn)}->${String(value.toTable)}`,
+                    kind: 'override',
+                    cardinality: value.cardinality === 'many-to-one' ? 'one-to-many' : value.cardinality,
+                    from: { tableId: from, columns: [value.fromColumn] },
+                    to: { tableId: value.toTable, columns: [value.toColumn] },
+                    through: null,
+                    onDelete: null,
+                    onUpdate: null,
+                    selfReferential: from === value.toTable,
+                    confidence: 1,
+                };
+                effective.relations = [
+                    ...effective.relations.filter((r) => r.id !== relation.id),
+                    relation,
+                ];
+                break;
+            }
+            case 'relation.remove': {
+                effective.relations = effective.relations.filter((r) => !(r.from.tableId === row.tableName &&
+                    r.from.columns.includes(value.fromColumn) &&
+                    r.to.tableId === value.toTable));
+                break;
+            }
+            case 'relation.label': {
+                const relation = effective.relations.find((r) => r.from.tableId === row.tableName && r.from.columns.includes(value.fromColumn));
+                if (relation !== undefined)
+                    relation.label = value.label;
+                break;
+            }
+        }
+    }
+    // Table labels last, from the ONE precedence-aware resolver — a user
+    // `table.label` beats an accepted `llm.label` bundle whichever came first.
+    for (const [name, label] of activeTableLabels(overrides, locale)) {
+        const table = tables.get(name);
+        if (table !== undefined)
+            table.label = label;
+    }
+    return effective;
+}
+export function columnPolicyFor(table) {
+    const masked = new Set();
+    const secret = new Set();
+    for (const column of table.columns) {
+        const semantics = column.semantics;
+        if (semantics?.flags.secret === true || semantics?.primary === 'secret') {
+            secret.add(column.name);
+            continue;
+        }
+        const maskedByOverride = column.masked;
+        const maskedByDefault = semantics?.flags.maskedByDefault === true;
+        if (maskedByOverride ?? maskedByDefault)
+            masked.add(column.name);
+    }
+    return { masked, secret };
+}
+//# sourceMappingURL=effective-schema.js.map

package/dist/connections/effective-schema.js.map

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

package/dist/connections/introspect.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Introspection pipeline (M3-T05): adapter `introspect()` → column/table
+ * classification (`@adminium/engine`) → canonical checksum → snapshot row →
+ * auto-proposed PII mask overrides ("Mask PII columns · On by default",
+ * 05-introspection-engine.md §7.2).
+ *
+ * 08 §2.4 runs this as an `introspect` job (202 + jobId, progress on
+ * `jobs:<id>`); `registerIntrospectJob` wires that. The route falls back to
+ * a synchronous run (with the 05 §10 duration budget) when the jobs worker
+ * is not registered — dev/test topologies.
+ */
+import { type MetaDb, type SchemaSnapshot } from '@adminium/meta';
+import { z } from 'zod';
+import { type ConnectionManager } from './manager.js';
+export interface IntrospectionResult {
+    snapshot: SchemaSnapshot;
+    /** True when the checksum matched the latest snapshot — nothing written. */
+    noop: boolean;
+    /** Count of PII mask overrides proposed by this run. */
+    proposedMasks: number;
+}
+export interface RunIntrospectionOptions {
+    manager: ConnectionManager;
+    meta: MetaDb;
+    connectionId: string;
+    createdBy?: string | null | undefined;
+    /** 05 §10 total budget; default 30s. */
+    timeoutMs?: number | undefined;
+}
+export declare function runIntrospection(opts: RunIntrospectionOptions): Promise<IntrospectionResult>;
+export declare const INTROSPECT_JOB_KIND = "introspect";
+export declare const introspectJobPayloadSchema: z.ZodObject<{
+    connectionId: z.ZodString;
+    createdBy: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    userId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+/** Minimal structural view of the jobs registry (jobs/registry.ts). */
+export interface IntrospectJobRegistry {
+    registerJobHandler<T>(kind: string, schema: z.ZodType<T>, handler: (payload: T, ctx: {
+        progress(pct: number, info?: {
+            step?: string;
+            message?: string;
+        }): void;
+    }) => Promise<unknown>): void;
+    has(kind: string): boolean;
+}
+/** Wire the async path of `POST /connections/:id/introspect` (08 §2.4). */
+export declare function registerIntrospectJob(registry: IntrospectJobRegistry, deps: {
+    manager: ConnectionManager;
+    meta: MetaDb;
+}): void;
+//# sourceMappingURL=introspect.d.ts.map

package/dist/connections/introspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspect.d.ts","sourceRoot":"","sources":["../../src/connections/introspect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EAAgC,KAAK,MAAM,EAAE,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChG,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAA0B,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAE9E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,cAAc,CAAC;IACzB,4EAA4E;IAC5E,IAAI,EAAE,OAAO,CAAC;IACd,wDAAwD;IACxD,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACtC,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAmCD,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAqClG;AAED,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAEhD,eAAO,MAAM,0BAA0B;;;;iBAKrC,CAAC;AAEH,uEAAuE;AACvE,MAAM,WAAW,qBAAqB;IACpC,kBAAkB,CAAC,CAAC,EAClB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,EAAE,CACP,OAAO,EAAE,CAAC,EACV,GAAG,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;YAAE,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;KAAE,KAC7E,OAAO,CAAC,OAAO,CAAC,GACpB,IAAI,CAAC;IACR,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAED,2EAA2E;AAC3E,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,qBAAqB,EAC/B,IAAI,EAAE;IAAE,OAAO,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjD,IAAI,CAaN"}

package/dist/connections/introspect.js

@@ -0,0 +1,111 @@
+/**
+ * Introspection pipeline (M3-T05): adapter `introspect()` → column/table
+ * classification (`@adminium/engine`) → canonical checksum → snapshot row →
+ * auto-proposed PII mask overrides ("Mask PII columns · On by default",
+ * 05-introspection-engine.md §7.2).
+ *
+ * 08 §2.4 runs this as an `introspect` job (202 + jobId, progress on
+ * `jobs:<id>`); `registerIntrospectJob` wires that. The route falls back to
+ * a synchronous run (with the 05 §10 duration budget) when the jobs worker
+ * is not registered — dev/test topologies.
+ */
+import { applyClassification, hashModel } from '@adminium/engine';
+import { AdapterError } from '@adminium/engine/adapter';
+import { overridesRepo, snapshotsRepo } from '@adminium/meta';
+import { z } from 'zod';
+import { adapterErrorToAppError } from './manager.js';
+/**
+ * Auto-propose `column.pii { masked: true }` overrides for columns the
+ * classifier flagged `maskedByDefault`, skipping any (table, column) that
+ * already has a `column.pii` row (user decisions are never overwritten).
+ */
+async function proposePiiMasks(meta, connectionId, model) {
+    const overrides = overridesRepo(meta);
+    const existing = await overrides.listForConnection(connectionId);
+    const covered = new Set(existing.filter((o) => o.op === 'column.pii').map((o) => `${o.tableName}\x00${o.columnName ?? ''}`));
+    let proposed = 0;
+    for (const table of model.tables) {
+        for (const column of table.columns) {
+            if (column.semantics?.flags.maskedByDefault !== true)
+                continue;
+            const key = `${table.id}\x00${column.name}`;
+            if (covered.has(key))
+                continue;
+            await overrides.create({
+                connectionId,
+                op: 'column.pii',
+                tableName: table.id,
+                columnName: column.name,
+                value: {
+                    masked: true,
+                    ...(column.semantics.flags.pii === null ? {} : { kind: column.semantics.flags.pii }),
+                },
+            });
+            proposed += 1;
+        }
+    }
+    return proposed;
+}
+export async function runIntrospection(opts) {
+    const { manager, meta, connectionId } = opts;
+    const snapshots = snapshotsRepo(meta);
+    const adapter = await manager.introspectAdapter(connectionId);
+    let model;
+    let engineVersion = null;
+    try {
+        const probe = await adapter.probeCapabilities().catch(() => null);
+        engineVersion = probe?.serverVersion ?? null;
+        model = await adapter.introspect({ timeoutMs: opts.timeoutMs ?? 30_000 });
+    }
+    catch (error) {
+        if (error instanceof AdapterError)
+            throw adapterErrorToAppError(error);
+        throw error;
+    }
+    finally {
+        await adapter.close().catch(() => undefined);
+    }
+    const classified = applyClassification(model);
+    const checksum = hashModel(classified);
+    const stats = {};
+    for (const table of classified.tables) {
+        if (table.rowCountEstimate !== null)
+            stats[table.id] = { rowCount: table.rowCountEstimate };
+    }
+    const { snapshot, noop } = await snapshots.create({
+        connectionId,
+        source: 'introspection',
+        engineVersion,
+        schema: classified,
+        stats: Object.keys(stats).length > 0 ? stats : null,
+        checksum,
+        createdBy: opts.createdBy ?? null,
+    });
+    const proposedMasks = noop ? 0 : await proposePiiMasks(meta, connectionId, classified);
+    await manager.connections.update(connectionId, { status: 'connected' });
+    return { snapshot, noop, proposedMasks };
+}
+export const INTROSPECT_JOB_KIND = 'introspect';
+export const introspectJobPayloadSchema = z.object({
+    connectionId: z.string(),
+    createdBy: z.string().nullish(),
+    /** Jobs owner convention (routes/jobs `jobOwnerId`) — lets the enqueuing user poll their job. */
+    userId: z.string().nullish(),
+});
+/** Wire the async path of `POST /connections/:id/introspect` (08 §2.4). */
+export function registerIntrospectJob(registry, deps) {
+    if (registry.has(INTROSPECT_JOB_KIND))
+        return;
+    registry.registerJobHandler(INTROSPECT_JOB_KIND, introspectJobPayloadSchema, async (payload, ctx) => {
+        ctx.progress(5, { step: 'connecting', message: 'Connecting…' });
+        const result = await runIntrospection({
+            manager: deps.manager,
+            meta: deps.meta,
+            connectionId: payload.connectionId,
+            createdBy: payload.createdBy ?? null,
+        });
+        ctx.progress(100, { step: 'done', message: 'Ready' });
+        return { snapshotId: result.snapshot.id, noop: result.noop, proposedMasks: result.proposedMasks };
+    });
+}
+//# sourceMappingURL=introspect.js.map

package/dist/connections/introspect.js.map

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

package/dist/connections/manager.d.ts

@@ -0,0 +1,97 @@
+/**
+ * ConnectionManager — the three-connection privilege model at runtime
+ * (01-architecture.md §3, M3-T04):
+ *
+ * - `introspect` — a short-lived adapter instance per introspection run,
+ * - `data`      — a pooled dynamic-Kysely handle per connection (the CRUD
+ *                 query port, 08-server-api.md §2.7), created lazily and
+ *                 disposed on connection delete,
+ * - `meta`      — the existing MetaDb; never handed to adapters.
+ *
+ * Meta-placement enforcement (01 §3.1): when the meta store lives in the
+ * same physical database as a source's data DSN and the probed data role is
+ * read-only or DDL-less, the manager refuses with `META_PLACEMENT_INVALID`
+ * — the rule lives here, not only in the wizard UI.
+ */
+import { Kysely } from 'kysely';
+import { AdapterError, type AdapterProvider, type AdapterRegistry, type CapabilityProbeResult, type DatabaseAdapter, type QueryEngine } from '@adminium/engine/adapter';
+import type { Dialect } from '@adminium/engine';
+import { connectionsRepo, type Connection, type DsnCrypto, type MetaDb } from '@adminium/meta';
+import { AppError } from '../errors.js';
+/** Dynamic source-DB row shape — identifiers are snapshot-validated upstream. */
+export type SourceDatabase = Record<string, Record<string, unknown>>;
+export interface DataHandle {
+    /** Dynamic Kysely over the pooled data connection. */
+    db: Kysely<SourceDatabase>;
+    engine: QueryEngine;
+    /** Source dialect (from the connection row) — drives per-dialect SQL compilation. */
+    dialect: Dialect;
+}
+export interface ConnectionTestSummary {
+    ok: boolean;
+    latencyMs: number;
+    serverVersion: string | null;
+    /** The probed data/introspect role cannot write — app runs read-only. */
+    readOnly: boolean;
+    capabilities: CapabilityProbeResult | null;
+    error: {
+        code: string;
+        message: string;
+        hint: string | null;
+    } | null;
+}
+export interface ConnectionManagerOptions {
+    meta: MetaDb;
+    crypto: DsnCrypto;
+    registry?: AdapterRegistry<AdapterProvider> | undefined;
+    /**
+     * The meta store's own DSN (env `ADMINIUM_META_URL` / bootstrap file).
+     * Compared against source data DSNs for the same-db placement check;
+     * null/undefined (embedded SQLite meta) can never collide.
+     */
+    metaDsn?: string | null | undefined;
+    /** SSRF guard tuning; default blocks loopback only in production. */
+    blockLoopback?: boolean | undefined;
+}
+/** 502-ish mapping for adapter failures surfaced through API routes. */
+export declare function adapterErrorToAppError(error: AdapterError): AppError;
+export declare class ConnectionManager {
+    #private;
+    readonly connections: ReturnType<typeof connectionsRepo>;
+    constructor(opts: ConnectionManagerOptions);
+    get meta(): MetaDb;
+    provider(engine: string): AdapterProvider;
+    hasAdapter(engine: string): boolean;
+    /** Guard + dial + test + probe one DSN with a short-lived introspect-role instance. */
+    testDsn(engine: string, dsn: string): Promise<ConnectionTestSummary>;
+    /**
+     * 01 §3.1 decision-tree rule, re-validated server-side: same-db meta
+     * placement is impossible against a read-only or DDL-less data role.
+     */
+    enforceMetaPlacement(dataDsn: string, probe: ConnectionTestSummary): void;
+    mustFind(connectionId: string): Promise<Connection>;
+    /**
+     * Short-lived introspect-role adapter for one run. The caller owns the
+     * lifecycle and must `close()` it (runIntrospection does).
+     */
+    introspectAdapter(connectionId: string): Promise<DatabaseAdapter<'introspect'>>;
+    /**
+     * Short-lived DATA-role adapter for one run — the symmetric twin of
+     * {@link introspectAdapter}, and the only way to reach the adapter methods
+     * that need row access (`collectTableStats`, 06 §4.2). The caller owns the
+     * lifecycle and must `close()` it. Deliberately NOT pooled alongside
+     * {@link data}: that handle is a long-lived Kysely for CRUD serving, whereas
+     * this is opened for one statistics pass and released.
+     *
+     * The DATA role, not introspect: the introspect role is schema-only by design
+     * (§3), so aggregates collected over it would fail on permissions.
+     */
+    dataAdapter(connectionId: string): Promise<DatabaseAdapter<'data'>>;
+    /** Pooled data handle (dynamic Kysely over the data DSN); lazy + cached. */
+    data(connectionId: string): Promise<DataHandle>;
+    /** Tear down a connection's pooled handles (connection delete / DSN change). */
+    dispose(connectionId: string): Promise<void>;
+    /** Graceful shutdown: release every pooled data handle. */
+    disposeAll(): Promise<void>;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/connections/manager.d.ts.map

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