@adminiumjs/adminium 0.1.0-rc.1

package/dist/export/zip-service.js

@@ -0,0 +1,306 @@
+/**
+ * Zip-export service (M10-T03, 01-architecture.md §4.1/§6.1/§8.2; BRIEF §3).
+ *
+ * WHAT IT EXPORTS — the design decision the docs make loudly, so the
+ * implementation cannot drift: **server + config, never source code.** The zip
+ * carries the runtime-interpreted configuration — connection definitions
+ * (secrets excluded unless {@link ExportZipOptions.includeSecrets} is set),
+ * schema snapshots, overrides, pages/dashboards, views, settings, roles — plus a
+ * manifest for version replay on re-import and a README that says all of this in
+ * its first heading. Adminium does not emit an app; the bundle names its runtime
+ * by pinning the `@adminiumjs/adminium` npm package (01 §4.1: that one package *is* the
+ * complete install — server + dashboard dist + meta migrations), it does not
+ * carry a copy of it.
+ *
+ * The secret policy lives in `redaction.ts` and fails closed: every field that
+ * leaves is on an allow-list, and any value that must be ciphertext is asserted
+ * to be ciphertext before it is written. See that module's header.
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { CONFIG_VERSION } from '@adminium/engine/config';
+import { ALL_MIGRATIONS, writeBool } from '@adminium/meta';
+import { strToU8, zipSync } from 'fflate';
+import { APP_VERSION } from '../version.js';
+import { BUNDLE_RESOURCES, MANIFEST_PATH, PACKAGE_JSON_PATH, README_PATH, resourcePath, } from './bundle.js';
+import { renderPackageJson, renderReadme } from './readme.js';
+import { EXPORTED_COLUMNS, assertCiphertext, assertNoCredentialColumns, pickColumns, redactSettings, secretColumnsFor, } from './redaction.js';
+/** Bumped when the bundle layout changes (re-import replay). */
+export const EXPORT_ZIP_MANIFEST_VERSION = 1;
+/**
+ * Fixed entry timestamp, so two exports of identical config are byte-identical
+ * and bundles stay diffable. The zip format cannot represent anything before
+ * 1980, so this — the zip epoch — is the earliest fixed point available; the
+ * real export time lives in the manifest's `exportedAt`, where it is readable.
+ */
+const ZIP_EPOCH = new Date('1980-01-01T00:00:00.000Z');
+/**
+ * The meta-schema high-water mark for the manifest (§8.2 `metaVersion`): the
+ * name of the last migration this store has applied. Read from the ledger, not
+ * from {@link ALL_MIGRATIONS}, because what matters for replay is what the
+ * *source* actually ran, not what its build happened to ship.
+ */
+async function readMetaVersion(meta) {
+    const rows = await meta.db
+        .selectFrom('adminium_migrations')
+        .select('name')
+        .orderBy('name', 'desc')
+        .limit(1)
+        .execute();
+    const latest = rows[0]?.name;
+    if (latest !== undefined)
+        return latest;
+    // An unmigrated store has no config worth exporting, but refusing here would
+    // be unhelpful — record the build's own baseline instead.
+    return ALL_MIGRATIONS[ALL_MIGRATIONS.length - 1]?.name ?? '0000_empty';
+}
+/** Kysely rows come back with dialect-shaped booleans (0/1) — normalize. */
+function toBool(value) {
+    return value === true || value === 1;
+}
+/**
+ * JSON columns arrive parsed (PG jsonb) or as a string (SQLite/MySQL). The
+ * bundle must carry structure, not a dialect artifact, so normalize both ways.
+ */
+function toJson(value) {
+    if (typeof value !== 'string')
+        return value ?? null;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+/**
+ * `ssl` is `{ mode, caFileId }` — no inline key material, so it travels. The
+ * `caFileId` points at an `adminium_files` row the bundle does not carry, so it
+ * is nulled rather than left dangling at the target.
+ */
+function redactSsl(ssl) {
+    if (ssl === null || typeof ssl !== 'object' || Array.isArray(ssl))
+        return ssl;
+    const record = ssl;
+    if (!('caFileId' in record))
+        return ssl;
+    return { ...record, caFileId: null };
+}
+/**
+ * Read every allow-listed row. Each block projects through {@link pickColumns}
+ * against {@link EXPORTED_COLUMNS}, so a column added by a future migration
+ * cannot ride along unnoticed.
+ */
+async function readBundle(opts) {
+    const { meta, connectionId, includeSecrets } = opts;
+    const { db } = meta;
+    // ── settings ──────────────────────────────────────────────────────────────
+    // Instance-level; a connection-scoped export carries none — they are not that
+    // connection's config, and copying them would silently restyle the target.
+    const settingRows = connectionId === null
+        ? await db.selectFrom('adminium_settings').select(['key', 'value']).execute()
+        : [];
+    const settings = redactSettings(settingRows.map((row) => ({ key: row.key, value: toJson(row.value) })), includeSecrets);
+    // ── roles + permissions ───────────────────────────────────────────────────
+    const roleRows = connectionId === null ? await db.selectFrom('adminium_roles').selectAll().execute() : [];
+    const roles = roleRows.map((row) => ({
+        ...pickColumns(row, EXPORTED_COLUMNS.adminium_roles),
+        isBuiltin: toBool(row.isBuiltin),
+        description: row.description ?? null,
+    }));
+    const permissionRows = connectionId === null
+        ? await db.selectFrom('adminium_role_permissions').selectAll().execute()
+        : [];
+    const rolePermissions = permissionRows.map((row) => ({
+        ...pickColumns(row, EXPORTED_COLUMNS.adminium_role_permissions),
+        actions: toJson(row.actions),
+    }));
+    // ── connections ───────────────────────────────────────────────────────────
+    let connectionQuery = db.selectFrom('adminium_connections').selectAll();
+    if (connectionId !== null)
+        connectionQuery = connectionQuery.where('id', '=', connectionId);
+    const connectionRows = await connectionQuery.execute();
+    const connections = connectionRows.map((row) => {
+        const base = {
+            ...pickColumns(row, EXPORTED_COLUMNS.adminium_connections),
+            readOnly: toBool(row.readOnly),
+            ssl: redactSsl(toJson(row.ssl)),
+            settings: toJson(row.settings),
+        };
+        if (!includeSecrets)
+            return base;
+        // Ciphertext only — assertCiphertext throws rather than let a plaintext DSN
+        // out, whatever the write path did.
+        const secrets = {};
+        for (const column of secretColumnsFor('adminium_connections')) {
+            secrets[column] = assertCiphertext(row[column], `connections.${row.id}.${column}`);
+        }
+        return { ...base, ...secrets };
+    });
+    const connectionIds = connectionRows.map((row) => row.id);
+    // ── snapshots ─────────────────────────────────────────────────────────────
+    // Only the ACTIVE snapshot per connection: history is instance data, and a
+    // bundle carrying every introspection ever run would be enormous for no gain.
+    const snapshotRows = connectionIds.length === 0
+        ? []
+        : await db
+            .selectFrom('adminium_schema_snapshots')
+            .selectAll()
+            .where('connectionId', 'in', connectionIds)
+            // Dialect-correct bind (`repos/util.ts`): sqlite stores 0/1, PG a real
+            // boolean, and neither driver accepts the other's form.
+            .where('isActive', '=', writeBool(meta, true))
+            .execute();
+    const snapshots = snapshotRows.map((row) => ({
+        ...pickColumns(row, EXPORTED_COLUMNS.adminium_schema_snapshots),
+        schema: toJson(row.schema),
+        stats: toJson(row.stats),
+        isActive: toBool(row.isActive),
+        importFormat: row.importFormat ?? null,
+        engineVersion: row.engineVersion ?? null,
+    }));
+    // ── overrides ─────────────────────────────────────────────────────────────
+    const overrideRows = connectionIds.length === 0
+        ? []
+        : await db
+            .selectFrom('adminium_schema_overrides')
+            .selectAll()
+            .where('connectionId', 'in', connectionIds)
+            .execute();
+    const overrides = overrideRows.map((row) => ({
+        ...pickColumns(row, EXPORTED_COLUMNS.adminium_schema_overrides),
+        value: toJson(row.value),
+        columnName: row.columnName ?? null,
+        confidence: row.confidence ?? null,
+    }));
+    // ── pages ─────────────────────────────────────────────────────────────────
+    let pageQuery = db.selectFrom('adminium_pages').selectAll();
+    if (connectionId !== null)
+        pageQuery = pageQuery.where('connectionId', '=', connectionId);
+    const pageRows = await pageQuery.execute();
+    const snapshotIds = new Set(snapshotRows.map((row) => row.id));
+    const pages = pageRows.map((row) => ({
+        ...pickColumns(row, EXPORTED_COLUMNS.adminium_pages),
+        config: toJson(row.config),
+        isEnabled: toBool(row.isEnabled),
+        icon: row.icon ?? null,
+        navGroup: row.navGroup ?? null,
+        // Keep the provenance link only when its snapshot travels with us; a
+        // dangling id would point at a snapshot the target has never seen.
+        generatedFromSnapshotId: row.generatedFromSnapshotId !== null && snapshotIds.has(row.generatedFromSnapshotId)
+            ? row.generatedFromSnapshotId
+            : null,
+    }));
+    // ── views ─────────────────────────────────────────────────────────────────
+    // Shared views only (`user_id IS NULL`). A per-user view belongs to a user the
+    // target install does not have; it is personal state, not instance config.
+    const pageIds = pageRows.map((row) => row.id);
+    const viewRows = pageIds.length === 0
+        ? []
+        : await db
+            .selectFrom('adminium_views')
+            .selectAll()
+            .where('pageId', 'in', pageIds)
+            .where('userId', 'is', null)
+            .execute();
+    const views = viewRows.map((row) => ({
+        ...pickColumns(row, EXPORTED_COLUMNS.adminium_views),
+        config: toJson(row.config),
+        isDefault: toBool(row.isDefault),
+    }));
+    return {
+        settings: settings.rows,
+        roles,
+        rolePermissions,
+        connections,
+        snapshots,
+        overrides,
+        pages,
+        views,
+        droppedSecretKeys: settings.droppedSecretKeys,
+        encryptedSettingKeys: settings.encryptedKeys,
+    };
+}
+/** Stable JSON — two exports of identical config should be identical bytes, so
+ *  bundles stay diffable and reviewable. */
+function toJsonBytes(value) {
+    return strToU8(JSON.stringify(value, null, 2) + '\n');
+}
+/** fflate takes a nested object; our paths are flat `a/b/c` strings. */
+function nest(files) {
+    const root = {};
+    for (const [path, bytes] of Object.entries(files)) {
+        const parts = path.split('/');
+        let cursor = root;
+        for (const part of parts.slice(0, -1)) {
+            cursor[part] ??= {};
+            cursor = cursor[part];
+        }
+        cursor[parts[parts.length - 1]] = bytes;
+    }
+    return root;
+}
+/**
+ * Export the instance's configuration to `outPath`.
+ *
+ * Ordering carries the secret guarantee: redaction runs while reading, the
+ * manifest is built from what redaction actually *did* (not from what was
+ * asked for), and only then are bytes produced.
+ */
+export const exportZip = async (opts) => {
+    // Cheap, and turns a future bad edit to the allow-list into a thrown error at
+    // the top of the export rather than a leak at the bottom of it.
+    assertNoCredentialColumns();
+    const connectionId = opts.connectionId ?? null;
+    const includeSecrets = opts.includeSecrets ?? false;
+    const now = opts.now ?? Date.now;
+    const body = await readBundle({ meta: opts.meta, connectionId, includeSecrets });
+    // What actually travelled encrypted — enumerated from the data, so the
+    // manifest and README can never overstate or understate the bundle.
+    const encrypted = [...body.encryptedSettingKeys];
+    if (includeSecrets) {
+        for (const connection of body.connections) {
+            for (const column of secretColumnsFor('adminium_connections')) {
+                if (connection[column] != null) {
+                    encrypted.push(`connections.${connection.id}.${column}`);
+                }
+            }
+        }
+    }
+    const counts = {};
+    for (const resource of BUNDLE_RESOURCES)
+        counts[resource] = body[resource].length;
+    const manifest = {
+        formatVersion: EXPORT_ZIP_MANIFEST_VERSION,
+        appVersion: opts.appVersion ?? APP_VERSION,
+        configVersion: CONFIG_VERSION,
+        metaVersion: await readMetaVersion(opts.meta),
+        exportedAt: now(),
+        connectionId,
+        secrets: {
+            policy: encrypted.length > 0 ? 'encrypted' : 'omitted',
+            encrypted,
+            omitted: body.droppedSecretKeys,
+        },
+        counts,
+    };
+    const files = {
+        [MANIFEST_PATH]: toJsonBytes(manifest),
+        [README_PATH]: strToU8(renderReadme(manifest)),
+        [PACKAGE_JSON_PATH]: strToU8(renderPackageJson(manifest)),
+    };
+    for (const resource of BUNDLE_RESOURCES) {
+        files[resourcePath(resource)] = toJsonBytes(body[resource]);
+    }
+    const zipped = zipSync(nest(files), { level: 6, mtime: ZIP_EPOCH });
+    const path = resolve(opts.outPath);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, zipped);
+    return {
+        path,
+        bytes: zipped.byteLength,
+        entries: Object.keys(files).sort(),
+        manifestVersion: EXPORT_ZIP_MANIFEST_VERSION,
+        counts,
+    };
+};
+//# sourceMappingURL=zip-service.js.map

package/dist/export/zip-service.js.map

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

package/dist/files/storage.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Local file storage for adminium_files bytes (07-meta-store.md §3.27, v1
+ * `storage = 'local'`): artifacts live under `<dataDir>/files/<id>` where
+ * `<id>` is the adminium_files row id (`file_<ULID>`), so the row IS the
+ * only name a byte blob ever has.
+ *
+ * FAIL-CLOSED PATH HANDLING (the demo-seed/backup discipline): a storage key
+ * is accepted only when it matches the prefixed-ULID grammar — no separators,
+ * no dots, no traversal — AND the resolved path still lives under the storage
+ * root. Both checks throw; nothing outside `<dataDir>/files/` is ever read,
+ * written, or deleted, whatever a database row claims.
+ */
+import { type ReadStream } from 'node:fs';
+export declare const FILES_DIR = "files";
+export declare class FileStorageError extends Error {
+    readonly name = "FileStorageError";
+}
+/** `file_<26 Crockford chars>` — the only storage-key shape `local` supports. */
+export declare function isSafeStorageKey(key: string): boolean;
+export interface WrittenBytes {
+    storageKey: string;
+    sizeBytes: number;
+    sha256: string;
+}
+/** Incremental writer for large artifacts (export jobs stream pages in). */
+export interface FileWriter {
+    write(chunk: Buffer | string): Promise<void>;
+    /** Close the handle and report size + sha256 of everything written. */
+    close(): Promise<WrittenBytes>;
+    /** Close and delete (failure paths). */
+    abort(): Promise<void>;
+}
+export interface FileStorage {
+    /** Absolute storage root (`<dataDir>/files`). */
+    readonly root: string;
+    /** Write bytes under `key`; returns size + sha256 of what landed on disk. */
+    write(key: string, bytes: Buffer | string): Promise<WrittenBytes>;
+    /** Open an incremental writer under `key`. */
+    openWriter(key: string): Promise<FileWriter>;
+    /** Open a read stream; throws {@link FileStorageError} when missing/unsafe. */
+    read(key: string): Promise<ReadStream>;
+    /** Byte size on disk (existence probe). */
+    size(key: string): Promise<number>;
+    /** Remove bytes; missing files are fine (idempotent GC). */
+    remove(key: string): Promise<void>;
+}
+export declare function createFileStorage(opts: {
+    dataDir: string;
+}): FileStorage;
+//# sourceMappingURL=storage.d.ts.map

package/dist/files/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/files/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAM5D,eAAO,MAAM,SAAS,UAAU,CAAC;AAEjC,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,SAAkB,IAAI,sBAAsB;CAC7C;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,4EAA4E;AAC5E,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,uEAAuE;IACvE,KAAK,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;IAC/B,wCAAwC;IACxC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAClE,8CAA8C;IAC9C,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7C,+EAA+E;IAC/E,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACvC,2CAA2C;IAC3C,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC,4DAA4D;IAC5D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,CA8ExE"}

package/dist/files/storage.js

@@ -0,0 +1,100 @@
+/**
+ * Local file storage for adminium_files bytes (07-meta-store.md §3.27, v1
+ * `storage = 'local'`): artifacts live under `<dataDir>/files/<id>` where
+ * `<id>` is the adminium_files row id (`file_<ULID>`), so the row IS the
+ * only name a byte blob ever has.
+ *
+ * FAIL-CLOSED PATH HANDLING (the demo-seed/backup discipline): a storage key
+ * is accepted only when it matches the prefixed-ULID grammar — no separators,
+ * no dots, no traversal — AND the resolved path still lives under the storage
+ * root. Both checks throw; nothing outside `<dataDir>/files/` is ever read,
+ * written, or deleted, whatever a database row claims.
+ */
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { mkdir, open, rm, stat, writeFile } from 'node:fs/promises';
+import { join, resolve, sep } from 'node:path';
+import { isId } from '@adminium/meta';
+export const FILES_DIR = 'files';
+export class FileStorageError extends Error {
+    name = 'FileStorageError';
+}
+/** `file_<26 Crockford chars>` — the only storage-key shape `local` supports. */
+export function isSafeStorageKey(key) {
+    return isId(key, 'file');
+}
+export function createFileStorage(opts) {
+    const root = resolve(opts.dataDir, FILES_DIR);
+    /** Grammar check + containment check — both fail closed. */
+    function pathFor(key) {
+        if (!isSafeStorageKey(key)) {
+            throw new FileStorageError(`unsafe storage key: ${JSON.stringify(key)}`);
+        }
+        const target = resolve(join(root, key));
+        if (target !== join(root, key) || !target.startsWith(root + sep)) {
+            throw new FileStorageError(`storage key escapes the files root: ${JSON.stringify(key)}`);
+        }
+        return target;
+    }
+    return {
+        root,
+        async write(key, bytes) {
+            const target = pathFor(key);
+            await mkdir(root, { recursive: true });
+            const buffer = typeof bytes === 'string' ? Buffer.from(bytes, 'utf8') : bytes;
+            await writeFile(target, buffer, { mode: 0o600 });
+            return {
+                storageKey: key,
+                sizeBytes: buffer.byteLength,
+                sha256: createHash('sha256').update(buffer).digest('hex'),
+            };
+        },
+        async openWriter(key) {
+            const target = pathFor(key);
+            await mkdir(root, { recursive: true });
+            const handle = await open(target, 'w', 0o600);
+            const hash = createHash('sha256');
+            let sizeBytes = 0;
+            return {
+                async write(chunk) {
+                    const buffer = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk;
+                    hash.update(buffer);
+                    sizeBytes += buffer.byteLength;
+                    await handle.write(buffer);
+                },
+                async close() {
+                    await handle.close();
+                    return { storageKey: key, sizeBytes, sha256: hash.digest('hex') };
+                },
+                async abort() {
+                    await handle.close();
+                    await rm(target, { force: true });
+                },
+            };
+        },
+        async read(key) {
+            const target = pathFor(key);
+            try {
+                await stat(target);
+            }
+            catch {
+                throw new FileStorageError(`no bytes stored under ${JSON.stringify(key)}`);
+            }
+            return createReadStream(target);
+        },
+        async size(key) {
+            const target = pathFor(key);
+            try {
+                return (await stat(target)).size;
+            }
+            catch {
+                throw new FileStorageError(`no bytes stored under ${JSON.stringify(key)}`);
+            }
+        },
+        async remove(key) {
+            const target = pathFor(key);
+            await rm(target, { force: true });
+        },
+    };
+}
+//# sourceMappingURL=storage.js.map

package/dist/files/storage.js.map

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

package/dist/generate/materialize-llm.d.ts

@@ -0,0 +1,45 @@
+/**
+ * LLM page-row materialization (06-llm-assist.md §8.3 step 3).
+ *
+ * The apply executor seeds `origin: 'llm'` page rows with a minimal config —
+ * `{source, llmRunId}` for template pages, `{domain, tables, layout, source,
+ * llmRunId}` for dashboards — and defers the full §6.1 envelope to "the
+ * regeneration hook". This module IS that expansion. `runGeneration` calls it
+ * after every persist, so the post-apply hook AND any manual regeneration
+ * repair seed rows into envelopes the client can parse; `upsertGenerated`
+ * itself never touches non-generated origins (user delta wins, 04 §6.3), so
+ * without this pass a seed row would stay an invalid-config card forever.
+ *
+ * Failure is per-row and non-fatal: a table that is excluded from the run, a
+ * template whose required slot cannot fill, or an envelope the frozen contract
+ * rejects leaves the seed's config untouched, records a warning on the run,
+ * and DISABLES the row — a parked page beats the invalid-config card the
+ * client would otherwise render forever. Every later run retries; success
+ * re-enables.
+ *
+ * A successful expansion also syncs the ROW's nav projection (title, nav
+ * group, icon back-fill) from the validated envelope: the bootstrap tree and
+ * the client's `/p/$slug` resolver read the row columns, not the document, so
+ * without the sync a materialized llm page would stay invisible and
+ * unreachable. An §8.3 nav-group re-placement still wins — the envelope
+ * follows the row's group when one was stamped.
+ */
+import { type DatabaseModel } from '@adminium/engine';
+import { type MetaDb } from '@adminium/meta';
+export interface MaterializeLlmResult {
+    /** Page ids whose seed config became a validated envelope this run. */
+    materialized: string[];
+    warnings: string[];
+}
+/**
+ * Expand every still-seed `origin: 'llm'` page row of a connection into a
+ * validated §6.1 envelope. Idempotent — materialized rows (config carries `v`)
+ * are never re-touched, so a user's later layout edits survive regeneration.
+ */
+export declare function materializeLlmPages(opts: {
+    meta: MetaDb;
+    model: DatabaseModel;
+    connectionId: string;
+    at?: number | undefined;
+}): Promise<MaterializeLlmResult>;
+//# sourceMappingURL=materialize-llm.d.ts.map

package/dist/generate/materialize-llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"materialize-llm.d.ts","sourceRoot":"","sources":["../../src/generate/materialize-llm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAA2C,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE/F,OAAO,EAAa,KAAK,MAAM,EAAa,MAAM,gBAAgB,CAAC;AAEnE,MAAM,WAAW,oBAAoB;IACnC,uEAAuE;IACvE,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAqFD;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAkEhC"}