@adminiumjs/meta 0.1.0-rc.1

package/dist/bootstrap.d.ts

@@ -0,0 +1,103 @@
+/**
+ * First-run bootstrap (07-meta-store.md §6): migrations + built-in role and
+ * permission seeds + `system.*` settings, plus the guarded creation of the
+ * first super admin. Re-running is safe — every step is guarded by existence
+ * checks and seeds use slug/key natural-key upserts, so upgrades can add new
+ * built-in permission rows without touching user edits.
+ */
+import type { MetaDb } from './connect.js';
+import { type SystemActionKey } from './schema/json-payloads.js';
+import { type User } from './repos/users.js';
+export interface BuiltinRoleDef {
+    slug: string;
+    name: string;
+    description: string;
+    /** System action grants seeded as `{ allowed: true }` rows (§6 step 3). */
+    systemActions: readonly SystemActionKey[];
+}
+/**
+ * The four built-in roles (§3.8, §6). Super-admin gets every system action
+ * (the RBAC layer short-circuits for `super-admin` anyway); admin gets the §6
+ * management set; editor/viewer get table/page grants dynamically at
+ * generation time, no system actions.
+ *
+ * Reserved-key footprint: "every system action" includes ALL FOUR
+ * `RESERVED_SYSTEM_ACTION_KEYS` (automations/webhooks/manifests/sql.run — no
+ * v1 enforcement point). That is deliberate and super-admin-ONLY: the role is
+ * definitionally full-access (and the RBAC layer short-circuits for
+ * `super-admin` anyway), so its reserved rows are inert declarations of
+ * intent, not capabilities. Every other role seeds enforced keys only —
+ * read-only surfaces render stored grants verbatim (e.g. the API-keys scope
+ * chips), and a reserved key there would advertise a feature that does not
+ * exist. When a deferred feature lands, re-add its key to the role defs in
+ * the same change that moves it out of `RESERVED_SYSTEM_ACTION_KEYS`;
+ * `seedBuiltinRoles` runs at every boot and backfills the missing rows on
+ * existing installs.
+ */
+export declare const BUILTIN_ROLES: readonly BuiltinRoleDef[];
+export declare class FirstUserExistsError extends Error {
+    name: string;
+    constructor();
+}
+export declare class BootstrapStateError extends Error {
+    name: string;
+}
+/**
+ * Seed the built-in roles and their permission baselines. Idempotent
+ * natural-key upserts: existing roles are left untouched (user renames of
+ * non-super-admin built-ins survive), and only missing permission rows are
+ * inserted (user permission edits survive upgrades).
+ */
+export declare function seedBuiltinRoles(meta: MetaDb, at?: number): Promise<{
+    createdRoles: string[];
+}>;
+/**
+ * Seed the `system.*` settings keys (§6 step 4). Only system identity keys
+ * are written — behavioral settings stay unset so a fresh install resolves to
+ * registry defaults (indigo / system theme / en_US) without a settings row.
+ */
+export declare function seedSystemSettings(meta: MetaDb, at?: number): Promise<void>;
+export interface FirstRunResult {
+    appliedMigrations: string[];
+    createdRoles: string[];
+}
+/**
+ * Everything a fresh database needs from a single call: apply all pending
+ * migrations, seed built-in roles/permissions, seed system settings.
+ * Safe to run at every boot (§6).
+ */
+export declare function firstRun(meta: MetaDb, at?: number): Promise<FirstRunResult>;
+export interface CreateFirstSuperAdminInput {
+    email: string;
+    /** Defaults to the email local part. */
+    name?: string;
+    /** argon2id — hashing happens in the server. */
+    passwordHash: string;
+}
+/**
+ * Create the very first user and grant `super-admin` (§6 step 2). This is the
+ * entire attack surface of a self-hosted first boot, so it is once-only by
+ * CONSTRUCTION rather than by a check-then-act read:
+ *
+ * everything runs in ONE transaction that first INSERTs the
+ * `system.superAdminCreatedAt` claim row. `adminium_settings.key` is a PRIMARY
+ * KEY, so a second — or a concurrently racing — attempt either sees the row
+ * (fast path below) or loses the INSERT to a duplicate-key violation, and its
+ * whole transaction rolls back. Either way exactly one super admin can ever be
+ * created, on every dialect and across processes/replicas; a plain
+ * `count() === 0` read could not promise that (two racers both read zero).
+ *
+ * Throws {@link FirstUserExistsError} when the claim is already taken or any
+ * user already exists.
+ */
+export declare function createFirstSuperAdmin(meta: MetaDb, input: CreateFirstSuperAdminInput, at?: number): Promise<User>;
+/**
+ * Zero users AND an unclaimed bootstrap ⇒ setup mode: the server serves only
+ * /setup/* (§6 step 1).
+ *
+ * The claim is checked as well as the user count so that bootstrap is
+ * PERMANENTLY closed once it has run: deleting every user later must not
+ * re-open an unauthenticated super-admin-creation endpoint (M10-T04).
+ */
+export declare function isBootstrapRequired(meta: MetaDb): Promise<boolean>;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAIrF,OAAO,EAAa,KAAK,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAGxD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,aAAa,EAAE,SAAS,eAAe,EAAE,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,cAAc,EAyBlD,CAAC;AAEF,qBAAa,oBAAqB,SAAQ,KAAK;IACpC,IAAI,SAA0B;;CAIxC;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IACnC,IAAI,SAAyB;CACvC;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAE,MAAmB,GAAG,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAsBjH;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAE,MAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAS7F;AAED,MAAM,WAAW,cAAc;IAC7B,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAE,MAAmB,GAAG,OAAO,CAAC,cAAc,CAAC,CAK7F;AAED,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAC;CACtB;AAQD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,0BAA0B,EACjC,EAAE,GAAE,MAAmB,GACtB,OAAO,CAAC,IAAI,CAAC,CA4Cf;AAqBD;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQxE"}

package/dist/bootstrap.js

@@ -0,0 +1,225 @@
+/**
+ * First-run bootstrap (07-meta-store.md §6): migrations + built-in role and
+ * permission seeds + `system.*` settings, plus the guarded creation of the
+ * first super admin. Re-running is safe — every step is guarded by existence
+ * checks and seeds use slug/key natural-key upserts, so upgrades can add new
+ * built-in permission rows without touching user edits.
+ */
+import { randomUUID } from 'node:crypto';
+import { applyMigrations } from './migrator.js';
+import { SYSTEM_ACTION_KEYS } from './schema/json-payloads.js';
+import { permissionsRepo } from './repos/permissions.js';
+import { rolesRepo } from './repos/roles.js';
+import { settingsRepo } from './repos/settings.js';
+import { usersRepo } from './repos/users.js';
+import { packJson } from './repos/util.js';
+/**
+ * The four built-in roles (§3.8, §6). Super-admin gets every system action
+ * (the RBAC layer short-circuits for `super-admin` anyway); admin gets the §6
+ * management set; editor/viewer get table/page grants dynamically at
+ * generation time, no system actions.
+ *
+ * Reserved-key footprint: "every system action" includes ALL FOUR
+ * `RESERVED_SYSTEM_ACTION_KEYS` (automations/webhooks/manifests/sql.run — no
+ * v1 enforcement point). That is deliberate and super-admin-ONLY: the role is
+ * definitionally full-access (and the RBAC layer short-circuits for
+ * `super-admin` anyway), so its reserved rows are inert declarations of
+ * intent, not capabilities. Every other role seeds enforced keys only —
+ * read-only surfaces render stored grants verbatim (e.g. the API-keys scope
+ * chips), and a reserved key there would advertise a feature that does not
+ * exist. When a deferred feature lands, re-add its key to the role defs in
+ * the same change that moves it out of `RESERVED_SYSTEM_ACTION_KEYS`;
+ * `seedBuiltinRoles` runs at every boot and backfills the missing rows on
+ * existing installs.
+ */
+export const BUILTIN_ROLES = [
+    {
+        slug: 'super-admin',
+        name: 'Super Admin',
+        description: 'Full access to everything, including users, roles, and settings.',
+        systemActions: SYSTEM_ACTION_KEYS,
+    },
+    {
+        slug: 'admin',
+        name: 'Admin',
+        description: 'Manages connections, schema, and LLM assist.',
+        systemActions: ['connections.manage', 'schema.remap', 'llm.run'],
+    },
+    {
+        slug: 'editor',
+        name: 'Editor',
+        description: 'Reads, creates, and updates records; views pages.',
+        systemActions: [],
+    },
+    {
+        slug: 'viewer',
+        name: 'Viewer',
+        description: 'Read-only access to records and pages.',
+        systemActions: [],
+    },
+];
+export class FirstUserExistsError extends Error {
+    name = 'FirstUserExistsError';
+    constructor() {
+        super('createFirstSuperAdmin is only allowed when zero users exist.');
+    }
+}
+export class BootstrapStateError extends Error {
+    name = 'BootstrapStateError';
+}
+/**
+ * Seed the built-in roles and their permission baselines. Idempotent
+ * natural-key upserts: existing roles are left untouched (user renames of
+ * non-super-admin built-ins survive), and only missing permission rows are
+ * inserted (user permission edits survive upgrades).
+ */
+export async function seedBuiltinRoles(meta, at = Date.now()) {
+    const roles = rolesRepo(meta);
+    const permissions = permissionsRepo(meta);
+    const createdRoles = [];
+    for (const def of BUILTIN_ROLES) {
+        let role = await roles.findBySlug(def.slug);
+        if (!role) {
+            role = await roles.create({ slug: def.slug, name: def.name, description: def.description, isBuiltin: true }, at);
+            createdRoles.push(def.slug);
+        }
+        for (const action of def.systemActions) {
+            const existing = await permissions.find(role.id, 'system', action);
+            if (!existing) {
+                await permissions.grant(role.id, 'system', action, { allowed: true });
+            }
+        }
+    }
+    return { createdRoles };
+}
+/**
+ * Seed the `system.*` settings keys (§6 step 4). Only system identity keys
+ * are written — behavioral settings stay unset so a fresh install resolves to
+ * registry defaults (indigo / system theme / en_US) without a settings row.
+ */
+export async function seedSystemSettings(meta, at = Date.now()) {
+    const settings = settingsRepo(meta);
+    if ((await settings.get('system.instanceId')) === null) {
+        await settings.set('system.instanceId', randomUUID(), { at });
+    }
+    if ((await settings.get('system.bootstrappedAt')) === null) {
+        await settings.set('system.bootstrappedAt', at, { at });
+        await settings.set('system.configVersion', 1, { at });
+    }
+}
+/**
+ * Everything a fresh database needs from a single call: apply all pending
+ * migrations, seed built-in roles/permissions, seed system settings.
+ * Safe to run at every boot (§6).
+ */
+export async function firstRun(meta, at = Date.now()) {
+    const { applied } = await applyMigrations(meta.db, { dialect: meta.dialect });
+    const { createdRoles } = await seedBuiltinRoles(meta, at);
+    await seedSystemSettings(meta, at);
+    return { appliedMigrations: applied, createdRoles };
+}
+/**
+ * The settings key whose ROW PRESENCE claims the one-and-only first-run
+ * bootstrap (M10-T04). See the registry entry for why it exists.
+ */
+const SUPER_ADMIN_CLAIM_KEY = 'system.superAdminCreatedAt';
+/**
+ * Create the very first user and grant `super-admin` (§6 step 2). This is the
+ * entire attack surface of a self-hosted first boot, so it is once-only by
+ * CONSTRUCTION rather than by a check-then-act read:
+ *
+ * everything runs in ONE transaction that first INSERTs the
+ * `system.superAdminCreatedAt` claim row. `adminium_settings.key` is a PRIMARY
+ * KEY, so a second — or a concurrently racing — attempt either sees the row
+ * (fast path below) or loses the INSERT to a duplicate-key violation, and its
+ * whole transaction rolls back. Either way exactly one super admin can ever be
+ * created, on every dialect and across processes/replicas; a plain
+ * `count() === 0` read could not promise that (two racers both read zero).
+ *
+ * Throws {@link FirstUserExistsError} when the claim is already taken or any
+ * user already exists.
+ */
+export async function createFirstSuperAdmin(meta, input, at = Date.now()) {
+    return meta.db.transaction().execute(async (trx) => {
+        const tmeta = { db: trx, dialect: meta.dialect };
+        const users = usersRepo(tmeta);
+        const roles = rolesRepo(tmeta);
+        // Fast, readable rejections for the common (non-racing) cases.
+        const claimed = await trx
+            .selectFrom('adminium_settings')
+            .select('key')
+            .where('key', '=', SUPER_ADMIN_CLAIM_KEY)
+            .executeTakeFirst();
+        if (claimed !== undefined)
+            throw new FirstUserExistsError();
+        if ((await users.count()) > 0)
+            throw new FirstUserExistsError();
+        const superAdmin = await roles.findBySlug('super-admin');
+        if (!superAdmin) {
+            throw new BootstrapStateError('built-in roles missing — run firstRun() before createFirstSuperAdmin().');
+        }
+        // The claim itself. A racer that passed the reads above collides here and
+        // its transaction aborts — this INSERT, not the reads, is the guarantee.
+        try {
+            await trx
+                .insertInto('adminium_settings')
+                .values({ key: SUPER_ADMIN_CLAIM_KEY, value: packJson(at), updatedAt: at, updatedBy: null })
+                .execute();
+        }
+        catch (error) {
+            // The only row that can already hold this PK is another bootstrap's
+            // claim (nothing else ever writes this key), so a failed INSERT means
+            // we lost the race. Anything genuinely unexpected still surfaces: it
+            // would have to be a non-duplicate write error, which we rethrow.
+            if (isDuplicateKeyError(error))
+                throw new FirstUserExistsError();
+            throw error;
+        }
+        const name = input.name ?? input.email.split('@')[0] ?? input.email;
+        const user = await users.create({ email: input.email, name, passwordHash: input.passwordHash, status: 'active' }, at);
+        await roles.assignToUser(user.id, superAdmin.id, null, at);
+        return user;
+    });
+}
+/**
+ * Duplicate-key detection across the three v1 dialects: SQLite
+ * (`SQLITE_CONSTRAINT_PRIMARYKEY` / "UNIQUE constraint failed"), Postgres
+ * (SQLSTATE 23505), MySQL/MariaDB (errno 1062 / `ER_DUP_ENTRY`). Falls back to
+ * a message probe so an unrecognized driver shape still reads as a duplicate
+ * rather than a 500 on the security-critical path.
+ */
+function isDuplicateKeyError(error) {
+    if (error === null || typeof error !== 'object')
+        return false;
+    const e = error;
+    if (typeof e.code === 'string') {
+        if (e.code === '23505')
+            return true; // Postgres unique_violation
+        if (e.code.startsWith('SQLITE_CONSTRAINT'))
+            return true;
+        if (e.code === 'ER_DUP_ENTRY')
+            return true;
+    }
+    if (e.errno === 1062)
+        return true; // MySQL/MariaDB
+    return typeof e.message === 'string' && /duplicate|unique constraint/i.test(e.message);
+}
+/**
+ * Zero users AND an unclaimed bootstrap ⇒ setup mode: the server serves only
+ * /setup/* (§6 step 1).
+ *
+ * The claim is checked as well as the user count so that bootstrap is
+ * PERMANENTLY closed once it has run: deleting every user later must not
+ * re-open an unauthenticated super-admin-creation endpoint (M10-T04).
+ */
+export async function isBootstrapRequired(meta) {
+    if ((await usersRepo(meta).count()) > 0)
+        return false;
+    const claimed = await meta.db
+        .selectFrom('adminium_settings')
+        .select('key')
+        .where('key', '=', SUPER_ADMIN_CLAIM_KEY)
+        .executeTakeFirst();
+    return claimed === undefined;
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/bootstrap.js.map

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

package/dist/columns.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Portable column-type helpers (07-meta-store.md §2.1).
+ *
+ * Every migration receives a {@link ColumnHelpers} instance built for the
+ * target dialect; this module is one of the few places allowed to branch on
+ * dialect (07-meta-store.md acceptance #1).
+ *
+ * | helper   | PostgreSQL   | MySQL/MariaDB | SQLite    |
+ * |----------|--------------|---------------|-----------|
+ * | id       | varchar(36)  | char(36)      | char(36)  |
+ * | str(n)   | varchar(n)   | varchar(n)    | text      |
+ * | text     | text         | text          | text      |
+ * | json     | jsonb        | json          | text      |
+ * | bool     | boolean      | tinyint(1)    | integer   |
+ * | int      | integer      | integer       | integer   |
+ * | bigint   | bigint       | bigint        | integer   |
+ * | ts       | bigint       | bigint        | integer   | epoch ms UTC
+ */
+import { type ColumnDataType, type RawBuilder } from 'kysely';
+export type MetaDialect = 'postgres' | 'mysql' | 'sqlite';
+/** What Kysely's `addColumn` accepts: a known data-type string or raw SQL. */
+export type PortableColumnType = ColumnDataType | RawBuilder<unknown>;
+export interface ColumnHelpers {
+    readonly dialect: MetaDialect;
+    /** Type-prefixed ULID primary/foreign key column. */
+    readonly id: PortableColumnType;
+    /** Indexable/unique string, n ≤ 320. */
+    str(n: number): PortableColumnType;
+    /** Unbounded text — never indexed. */
+    readonly text: PortableColumnType;
+    /** Opaque JSON payload — serialized/parsed + Zod-validated in repos, never queried with JSON operators. */
+    readonly json: PortableColumnType;
+    /** Boolean — repos coerce reads to JS boolean. */
+    readonly bool: PortableColumnType;
+    readonly int: PortableColumnType;
+    /** Values always < 2^53; returned as JS number. */
+    readonly bigint: PortableColumnType;
+    /** Epoch milliseconds UTC — never native datetime (07-meta-store.md §2.1). */
+    readonly ts: PortableColumnType;
+    /** Dialect-correct boolean literal for DDL `DEFAULT` clauses. */
+    boolDefault(value: boolean): RawBuilder<unknown>;
+}
+export declare function columnHelpers(dialect: MetaDialect): ColumnHelpers;
+//# sourceMappingURL=columns.d.ts.map

package/dist/columns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"columns.d.ts","sourceRoot":"","sources":["../src/columns.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAO,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEnE,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE1D,8EAA8E;AAC9E,MAAM,MAAM,kBAAkB,GAAG,cAAc,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;AAEtE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,qDAAqD;IACrD,QAAQ,CAAC,EAAE,EAAE,kBAAkB,CAAC;IAChC,wCAAwC;IACxC,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,kBAAkB,CAAC;IACnC,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,2GAA2G;IAC3G,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,GAAG,EAAE,kBAAkB,CAAC;IACjC,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,EAAE,kBAAkB,CAAC;IAChC,iEAAiE;IACjE,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;CAClD;AAMD,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,aAAa,CAkCjE"}

package/dist/columns.js

@@ -0,0 +1,57 @@
+/**
+ * Portable column-type helpers (07-meta-store.md §2.1).
+ *
+ * Every migration receives a {@link ColumnHelpers} instance built for the
+ * target dialect; this module is one of the few places allowed to branch on
+ * dialect (07-meta-store.md acceptance #1).
+ *
+ * | helper   | PostgreSQL   | MySQL/MariaDB | SQLite    |
+ * |----------|--------------|---------------|-----------|
+ * | id       | varchar(36)  | char(36)      | char(36)  |
+ * | str(n)   | varchar(n)   | varchar(n)    | text      |
+ * | text     | text         | text          | text      |
+ * | json     | jsonb        | json          | text      |
+ * | bool     | boolean      | tinyint(1)    | integer   |
+ * | int      | integer      | integer       | integer   |
+ * | bigint   | bigint       | bigint        | integer   |
+ * | ts       | bigint       | bigint        | integer   | epoch ms UTC
+ */
+import { sql } from 'kysely';
+// 2048 covers the longest legitimate short-string columns (URLs in notifications/webhooks);
+// anything longer belongs in a `text` column. MySQL utf8mb4 varchar(2048) is fine un-indexed.
+const MAX_STR = 2048;
+export function columnHelpers(dialect) {
+    const str = (n) => {
+        if (!Number.isInteger(n) || n < 1 || n > MAX_STR) {
+            throw new RangeError(`str(n): n must be an integer in [1, ${MAX_STR}], got ${n}`);
+        }
+        return dialect === 'sqlite' ? 'text' : `varchar(${n})`;
+    };
+    return {
+        dialect,
+        // Ids are type-prefixed ULIDs of VARIABLE length (3-4 char prefix + '_' +
+        // 26 ULID chars, e.g. usr_… = 30, view_… = 31). Postgres `char(36)`
+        // (bpchar) blank-pads to 36 on write and hands the padding back on every
+        // read — 'view_…' comes back as 'view_…     ', breaking id round-trips.
+        // MySQL strips CHAR pad spaces at retrieval and SQLite ignores the length
+        // entirely, so only Postgres deviates from the 07-meta-store.md §2.1 table.
+        //
+        // DECISION (2026-07-20, pre-release): this change alters the DDL that the
+        // already-written migrations 0001–0009 emit on postgres, with no
+        // compensating ALTER, and the checksum ledger cannot see it (it hashes
+        // migration sources, not this helper). That is acceptable exactly once:
+        // no Adminium release exists and no deployed pg meta store predates it.
+        // After v1.0 ships, a column-type change like this MUST ship as a new
+        // migration instead — never edit this helper's emitted types again.
+        id: dialect === 'postgres' ? 'varchar(36)' : sql `char(36)`,
+        str,
+        text: 'text',
+        json: dialect === 'postgres' ? 'jsonb' : dialect === 'mysql' ? 'json' : 'text',
+        bool: dialect === 'postgres' ? 'boolean' : dialect === 'mysql' ? sql `tinyint(1)` : 'integer',
+        int: 'integer',
+        bigint: dialect === 'sqlite' ? 'integer' : 'bigint',
+        ts: dialect === 'sqlite' ? 'integer' : 'bigint',
+        boolDefault: (value) => dialect === 'postgres' ? (value ? sql `true` : sql `false`) : value ? sql `1` : sql `0`,
+    };
+}
+//# sourceMappingURL=columns.js.map

package/dist/columns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"columns.js","sourceRoot":"","sources":["../src/columns.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,GAAG,EAAwC,MAAM,QAAQ,CAAC;AA4BnE,4FAA4F;AAC5F,8FAA8F;AAC9F,MAAM,OAAO,GAAG,IAAI,CAAC;AAErB,MAAM,UAAU,aAAa,CAAC,OAAoB;IAChD,MAAM,GAAG,GAAG,CAAC,CAAS,EAAsB,EAAE;QAC5C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,OAAO,EAAE,CAAC;YACjD,MAAM,IAAI,UAAU,CAAC,uCAAuC,OAAO,UAAU,CAAC,EAAE,CAAC,CAAC;QACpF,CAAC;QACD,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAE,WAAW,CAAC,GAAsB,CAAC;IAC7E,CAAC,CAAC;IACF,OAAO;QACL,OAAO;QACP,0EAA0E;QAC1E,oEAAoE;QACpE,yEAAyE;QACzE,wEAAwE;QACxE,0EAA0E;QAC1E,4EAA4E;QAC5E,EAAE;QACF,0EAA0E;QAC1E,iEAAiE;QACjE,uEAAuE;QACvE,wEAAwE;QACxE,wEAAwE;QACxE,sEAAsE;QACtE,oEAAoE;QACpE,EAAE,EAAE,OAAO,KAAK,UAAU,CAAC,CAAC,CAAE,aAAgC,CAAC,CAAC,CAAC,GAAG,CAAA,UAAU;QAC9E,GAAG;QACH,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;QAC9E,IAAI,EAAE,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAA,YAAY,CAAC,CAAC,CAAC,SAAS;QAC5F,GAAG,EAAE,SAAS;QACd,MAAM,EAAE,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ;QACnD,EAAE,EAAE,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ;QAC/C,WAAW,EAAE,CAAC,KAAc,EAAE,EAAE,CAC9B,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAA,MAAM,CAAC,CAAC,CAAC,GAAG,CAAA,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAA,GAAG,CAAC,CAAC,CAAC,GAAG,CAAA,GAAG;KACtF,CAAC;AACJ,CAAC"}

package/dist/connect.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Meta-store Kysely factories (07-meta-store.md §1 connect.ts, §5.2).
+ *
+ * Database drivers are injected by the caller (apps/server or tests):
+ * each factory accepts the corresponding Kysely dialect config carrying a
+ * live driver instance/pool — this package declares no driver dependencies.
+ *
+ * The meta instance runs `CamelCasePlugin` (07-meta-store.md §2.2): TS models
+ * are camelCase, physical columns snake_case. The dynamic source-DB instance
+ * (owned by the server) keeps raw names and never touches adminium_* tables.
+ */
+import { Kysely, type MysqlDialectConfig, type PostgresDialectConfig, type SqliteDialectConfig } from 'kysely';
+import type { MetaDialect } from './columns.js';
+import type { MetaDB } from './schema/tables.js';
+/** The single handle every repo and the migrator operate on. */
+export interface MetaDb {
+    db: Kysely<MetaDB>;
+    dialect: MetaDialect;
+}
+/**
+ * SQLite meta-store around an injected better-sqlite3-compatible database.
+ * Call {@link initMetaDb} (or `applyMigrations`/`firstRun`, which do it for
+ * you) before FK-dependent work — SQLite needs `PRAGMA foreign_keys = ON`
+ * per connection (07-meta-store.md §2.2).
+ */
+export declare function createSqliteMetaDb(config: SqliteDialectConfig): MetaDb;
+/**
+ * PostgreSQL meta-store around an injected `pg` Pool. The pool must parse
+ * int8 as JS number (all ts values < 2^53 — 07-meta-store.md §2.1).
+ */
+export declare function createPostgresMetaDb(config: PostgresDialectConfig): MetaDb;
+/** MySQL/MariaDB meta-store around an injected `mysql2` pool. */
+export declare function createMysqlMetaDb(config: MysqlDialectConfig): MetaDb;
+/** One-time per-connection setup (currently: SQLite FK pragma). */
+export declare function initMetaDb(meta: MetaDb): Promise<void>;
+/** Release the underlying pool/connection. */
+export declare function destroyMetaDb(meta: MetaDb): Promise<void>;
+//# sourceMappingURL=connect.d.ts.map

package/dist/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAEL,MAAM,EAKN,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACzB,MAAM,QAAQ,CAAC;AAEhB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,gEAAgE;AAChE,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACnB,OAAO,EAAE,WAAW,CAAC;CACtB;AAiBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAEtE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAE1E;AAED,iEAAiE;AACjE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAEpE;AAED,mEAAmE;AACnE,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5D;AAED,8CAA8C;AAC9C,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/D"}

package/dist/connect.js

@@ -0,0 +1,57 @@
+/**
+ * Meta-store Kysely factories (07-meta-store.md §1 connect.ts, §5.2).
+ *
+ * Database drivers are injected by the caller (apps/server or tests):
+ * each factory accepts the corresponding Kysely dialect config carrying a
+ * live driver instance/pool — this package declares no driver dependencies.
+ *
+ * The meta instance runs `CamelCasePlugin` (07-meta-store.md §2.2): TS models
+ * are camelCase, physical columns snake_case. The dynamic source-DB instance
+ * (owned by the server) keeps raw names and never touches adminium_* tables.
+ */
+import { CamelCasePlugin, Kysely, MysqlDialect, PostgresDialect, SqliteDialect, } from 'kysely';
+import { enableSqliteForeignKeys } from './migrator.js';
+function build(dialect, kyselyDialect) {
+    return {
+        db: new Kysely({
+            dialect: kyselyDialect,
+            // Case-mapping is for COLUMN names only. Without maintainNestedObjectKeys
+            // the plugin also recursively camelCases plain-object VALUES — which
+            // silently corrupts driver-decoded JSON payloads (pg `jsonb` and mysql2
+            // `json` return parsed objects): a stored {"en_US": …} label came back
+            // {"enUS": …}. SQLite never hit it because its JSON is text.
+            plugins: [new CamelCasePlugin({ maintainNestedObjectKeys: true })],
+        }),
+        dialect,
+    };
+}
+/**
+ * SQLite meta-store around an injected better-sqlite3-compatible database.
+ * Call {@link initMetaDb} (or `applyMigrations`/`firstRun`, which do it for
+ * you) before FK-dependent work — SQLite needs `PRAGMA foreign_keys = ON`
+ * per connection (07-meta-store.md §2.2).
+ */
+export function createSqliteMetaDb(config) {
+    return build('sqlite', new SqliteDialect(config));
+}
+/**
+ * PostgreSQL meta-store around an injected `pg` Pool. The pool must parse
+ * int8 as JS number (all ts values < 2^53 — 07-meta-store.md §2.1).
+ */
+export function createPostgresMetaDb(config) {
+    return build('postgres', new PostgresDialect(config));
+}
+/** MySQL/MariaDB meta-store around an injected `mysql2` pool. */
+export function createMysqlMetaDb(config) {
+    return build('mysql', new MysqlDialect(config));
+}
+/** One-time per-connection setup (currently: SQLite FK pragma). */
+export async function initMetaDb(meta) {
+    if (meta.dialect === 'sqlite')
+        await enableSqliteForeignKeys(meta.db);
+}
+/** Release the underlying pool/connection. */
+export async function destroyMetaDb(meta) {
+    await meta.db.destroy();
+}
+//# sourceMappingURL=connect.js.map

package/dist/connect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.js","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,eAAe,EACf,MAAM,EACN,YAAY,EACZ,eAAe,EACf,aAAa,GAKd,MAAM,QAAQ,CAAC;AAGhB,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AASxD,SAAS,KAAK,CAAC,OAAoB,EAAE,aAAsB;IACzD,OAAO;QACL,EAAE,EAAE,IAAI,MAAM,CAAS;YACrB,OAAO,EAAE,aAAa;YACtB,0EAA0E;YAC1E,qEAAqE;YACrE,wEAAwE;YACxE,uEAAuE;YACvE,6DAA6D;YAC7D,OAAO,EAAE,CAAC,IAAI,eAAe,CAAC,EAAE,wBAAwB,EAAE,IAAI,EAAE,CAAC,CAAC;SACnE,CAAC;QACF,OAAO;KACR,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAA2B;IAC5D,OAAO,KAAK,CAAC,QAAQ,EAAE,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;AACpD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAA6B;IAChE,OAAO,KAAK,CAAC,UAAU,EAAE,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC;AACxD,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,iBAAiB,CAAC,MAA0B;IAC1D,OAAO,KAAK,CAAC,OAAO,EAAE,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;AAClD,CAAC;AAED,mEAAmE;AACnE,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY;IAC3C,IAAI,IAAI,CAAC,OAAO,KAAK,QAAQ;QAAE,MAAM,uBAAuB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACxE,CAAC;AAED,8CAA8C;AAC9C,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAY;IAC9C,MAAM,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC;AAC1B,CAAC"}

package/dist/ids.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Type-prefixed monotonic ULID generator for every adminium_* primary key.
+ *
+ * Format: `<prefix>_<26-char Crockford-base32 ULID>` — e.g. `usr_01J8ME7Q2RZX4V9T6W3YB0KD5N`.
+ * The longest registered prefix is 4 chars, so every id fits the portable
+ * `char(36)` id column (07-meta-store.md §2.1) with room to spare.
+ *
+ * ULIDs are lexicographically time-sortable (48-bit ms timestamp + 80-bit
+ * randomness); within one millisecond the random part is incremented
+ * (monotonic mode) so ids generated by one process always sort in creation
+ * order (08-server-api.md §1.5 cursor pagination relies on this).
+ */
+declare const ULID_LEN: number;
+/**
+ * Prefix registry: every id-bearing adminium_* table has exactly one prefix
+ * (07-meta-store.md §3). Junction/KV tables (user_roles, user_prefs,
+ * notification_prefs, settings, changelog_seen, migrations ledger) have
+ * natural/composite keys and no prefix.
+ */
+export declare const ID_PREFIXES: {
+    readonly usr: "adminium_users";
+    readonly sess: "adminium_sessions";
+    readonly rst: "adminium_password_resets";
+    readonly key: "adminium_api_keys";
+    readonly role: "adminium_roles";
+    readonly perm: "adminium_role_permissions";
+    readonly aud: "adminium_audit_log";
+    readonly job: "adminium_jobs";
+    readonly conn: "adminium_connections";
+    readonly snap: "adminium_schema_snapshots";
+    readonly ovr: "adminium_schema_overrides";
+    readonly page: "adminium_pages";
+    readonly view: "adminium_views";
+    readonly run: "adminium_llm_runs";
+    readonly ntf: "adminium_notifications";
+    readonly auto: "adminium_automations";
+    readonly arun: "adminium_automation_runs";
+    readonly rep: "adminium_scheduled_reports";
+    readonly exp: "adminium_exports";
+    readonly imp: "adminium_imports";
+    readonly file: "adminium_files";
+    readonly tpl: "adminium_email_templates";
+    readonly wh: "adminium_webhooks";
+    readonly whd: "adminium_webhook_deliveries";
+    readonly flag: "adminium_feature_flags";
+    readonly mft: "adminium_manifests";
+};
+export type IdPrefix = keyof typeof ID_PREFIXES;
+/** Maximum column width every id must fit (07-meta-store.md §2.1). */
+export declare const ID_MAX_LENGTH = 36;
+export declare class InvalidIdError extends Error {
+    name: string;
+}
+/**
+ * Generate a new type-prefixed monotonic ULID: `newId('usr')` → `usr_01J…`.
+ * Ids from the same process are strictly increasing even within one
+ * millisecond or across a backwards clock step.
+ */
+export declare function newId(prefix: IdPrefix): string;
+export interface ParsedId {
+    /** Registered prefix, e.g. `usr`. */
+    prefix: IdPrefix;
+    /** The table this id belongs to, e.g. `adminium_users`. */
+    table: string;
+    /** The bare 26-char ULID. */
+    ulid: string;
+    /** Millisecond timestamp encoded in the ULID. */
+    time: number;
+}
+/** Parse and validate a prefixed id; throws {@link InvalidIdError} on any malformed input. */
+export declare function parseId(id: string): ParsedId;
+/** True when `id` is a well-formed prefixed ULID (optionally of a specific prefix). */
+export declare function isId(id: unknown, prefix?: IdPrefix): boolean;
+/** Millisecond timestamp embedded in a prefixed ULID. */
+export declare function idTime(id: string): number;
+/** Internal — deterministic tests only. */
+export declare function _resetIdState(): void;
+export { ULID_LEN as _ULID_LENGTH };
+//# sourceMappingURL=ids.d.ts.map

package/dist/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../src/ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,QAAA,MAAM,QAAQ,QAAsB,CAAC;AAErC;;;;;GAKG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2Bd,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,WAAW,CAAC;AAOhD,sEAAsE;AACtE,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC,qBAAa,cAAe,SAAQ,KAAK;IAC9B,IAAI,SAAoB;CAClC;AAiDD;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,CAc9C;AAED,MAAM,WAAW,QAAQ;IACvB,qCAAqC;IACrC,MAAM,EAAE,QAAQ,CAAC;IACjB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,8FAA8F;AAC9F,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,CAY5C;AAED,uFAAuF;AACvF,wBAAgB,IAAI,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,OAAO,CAQ5D;AAED,yDAAyD;AACzD,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEzC;AAED,2CAA2C;AAC3C,wBAAgB,aAAa,IAAI,IAAI,CAGpC;AAED,OAAO,EAAE,QAAQ,IAAI,YAAY,EAAE,CAAC"}