@pikku/kysely 0.13.3 → 0.13.5

package/dist/src/schema/index.js

@@ -0,0 +1,274 @@
+import { CamelCasePlugin } from 'kysely';
+import { aiSchema } from './ai.schema.js';
+import { channelSchema } from './channel.schema.js';
+import { credentialSchema } from './credential.schema.js';
+import { deploymentSchema } from './deployment.schema.js';
+import { scopeSchema } from './scope.schema.js';
+import { secretSchema } from './secret.schema.js';
+import { sessionSchema } from './session.schema.js';
+import { webhookSchema } from './webhook.schema.js';
+import { workflowSchema } from './workflow.schema.js';
+export { rawStatement, requiredType } from './pikku-schema.types.js';
+/**
+ * Every table the pikku runtime needs, in dependency order.
+ *
+ * Order is load-bearing, not cosmetic: `scope` has foreign keys onto Better
+ * Auth's `user`, and the tables within each schema reference each other. Sort
+ * this list alphabetically and it stops applying.
+ */
+export const pikkuSchemas = [
+    channelSchema,
+    sessionSchema,
+    secretSchema,
+    credentialSchema,
+    deploymentSchema,
+    webhookSchema,
+    workflowSchema,
+    aiSchema,
+    scopeSchema,
+];
+/**
+ * Bind a declaration to a database.
+ *
+ * The plugin is applied here rather than trusted to the caller. Declarations
+ * name tables and columns the way the rest of the codebase queries them
+ * (`aiThreads.resourceId`), and it is `CamelCasePlugin` that turns those into
+ * the physical `ai_threads.resource_id`. Without it the same declaration
+ * silently creates quoted camelCase tables that nothing can read.
+ */
+const bind = (db) => db.withPlugin(new CamelCasePlugin());
+/**
+ * Look up every prerequisite in `db`, reporting the gaps and the types found.
+ *
+ * Both halves come from one introspection because they are one question. The
+ * gaps say whether a schema can be applied at all; the types say how — a
+ * foreign key onto a `uuid` primary key has to be declared `uuid`, and guessing
+ * `text` produces DDL the database refuses.
+ *
+ * Introspection returns physical names, so `requires` is written in physical
+ * names too — this is the one place in the declaration that is not camelCase.
+ */
+export const resolveRequirements = async (db, schemas = pikkuSchemas) => {
+    const tables = new Map((await bind(db).introspection.getTables()).map((table) => [
+        table.name,
+        table,
+    ]));
+    const types = {};
+    const unmet = [];
+    for (const schema of schemas) {
+        for (const requirement of schema.requires ?? []) {
+            const column = tables
+                .get(requirement.table)
+                ?.columns.find((c) => c.name === requirement.column);
+            if (!column) {
+                unmet.push({ schema, requirement });
+            }
+            else {
+                types[`${requirement.table}.${requirement.column}`] = column.dataType;
+            }
+        }
+    }
+    return { types, unmet };
+};
+/**
+ * The prerequisites `db` does not satisfy, as a list rather than a throw.
+ *
+ * Separate from `applyPikkuSchemas` because the two callers want opposite
+ * things from the same answer: a service booting cannot proceed without its
+ * tables, while a tool asking what a project's schema *would* be needs to
+ * describe the gap rather than die on it.
+ */
+export const unsatisfiedRequirements = async (db, schemas = pikkuSchemas) => (await resolveRequirements(db, schemas)).unmet;
+/**
+ * Create the tables, in order, on a database that has whatever they require.
+ *
+ * Prerequisites are checked before anything is created, so a project missing
+ * one is told which schema wanted what — rather than being handed a foreign key
+ * error, or a half-applied database to clean up.
+ *
+ * The statements then run in one transaction, so the same promise holds for a
+ * failure the check cannot foresee: a statement that dies mid-list takes the
+ * ones before it with it. On an engine without transactional DDL the rollback
+ * is the engine's to give, not ours.
+ */
+export const applyPikkuSchemas = async (db, schemas = pikkuSchemas) => {
+    const { types, unmet } = await resolveRequirements(db, schemas);
+    if (unmet.length > 0) {
+        throw new Error(unmet
+            .map(({ schema, requirement }) => `The '${schema.name}' schema requires '${requirement.table}.${requirement.column}', which nothing has created. ` +
+            `${requirement.owner} owns it — apply its schema first.`)
+            .join('\n'));
+    }
+    await db.transaction().execute(async (trx) => {
+        const bound = bind(trx);
+        for (const schema of schemas) {
+            for (const statement of schema.statements) {
+                const query = statement(bound, types);
+                try {
+                    await query.execute();
+                }
+                catch (error) {
+                    throw explain(error, query.compile().sql, schema);
+                }
+            }
+        }
+    });
+};
+/** `references "app"."workflow_runs"` — a foreign key onto a qualified table. */
+const QUALIFIED_REFERENCE = /references "[^"]+"\."[^"]+"/i;
+/**
+ * sqlite's own words for "you put a dot where a table name goes".
+ *
+ * Matched rather than a driver's `code`, because every sqlite binding
+ * (better-sqlite3, node:sqlite, bun:sqlite, libsql) passes the engine's message
+ * through verbatim while disagreeing about how to label it. Postgres phrases the
+ * same class of error the other way round — `syntax error at or near "."` — so
+ * this cannot fire on it.
+ */
+const SQLITE_REJECTED_QUALIFIER = /near "\.":\s*syntax error/i;
+/**
+ * Say what a schema-bound connection did to the DDL, when that is what failed.
+ *
+ * `withSchema(...)` qualifies foreign key targets along with everything else.
+ * Postgres needs that — an unqualified reference resolves against `search_path`,
+ * which a schema-bound connection does not control — and sqlite refuses it: a
+ * `REFERENCES` clause there takes a bare table name, because a foreign key can
+ * only point inside the same database, so there is no qualifier to give. One
+ * declaration cannot spell both, and what the engine says about it is
+ * `near ".": syntax error`, which names neither the schema nor the cause.
+ *
+ * Gated on sqlite's exact phrasing as well as the SQL. Postgres compiles the
+ * same qualified reference legitimately, and can raise a syntax error of its own
+ * on this DDL — a column type resolved from `requires` goes in verbatim — so a
+ * looser `/syntax error/` would answer for postgres in sqlite's name.
+ */
+const explain = (error, sql, schema) => {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!QUALIFIED_REFERENCE.test(sql) ||
+        !SQLITE_REJECTED_QUALIFIER.test(message)) {
+        return error;
+    }
+    return new Error(`The '${schema.name}' schema has a foreign key, and this connection is bound to a schema, ` +
+        `so it compiled to a qualified 'references "schema"."table"' that the database rejected. ` +
+        'sqlite is the engine that does this: its REFERENCES clause takes a bare table name. ' +
+        'Use a connection without withSchema(...) there — sqlite has one schema to be in — ' +
+        'or write the schema down as a migration with `pikku db generate` and apply it yourself. ' +
+        `The database said: ${message}`, { cause: error });
+};
+/** How a table reads in an error message: qualified only when it is. */
+const displayName = (table) => table.schema ? `${table.schema}.${table.name}` : table.name;
+/**
+ * `create table "workflow_runs"` and `create table "app"."workflow_runs"`.
+ *
+ * The schema half is optional and the table is always the LAST quoted
+ * identifier — matching the first one instead reads a `withSchema('app')`
+ * connection's DDL as a table called `app`, which is no table at all.
+ */
+const CREATE_TABLE = /^\s*create table (?:if not exists\s+)?(?:"([^"]+)"\.)?"([^"]+)"/i;
+/**
+ * The tables a schema creates, read back out of its own compiled SQL.
+ *
+ * Derived rather than declared alongside the statements, because a hand-kept
+ * list of names is a second source of truth: rename a table in a statement and
+ * the list keeps answering for the old one.
+ *
+ * Compiled against `db` rather than in the abstract, so the answer carries the
+ * schema the DDL will actually target — the same binding the lookup has to use.
+ */
+export const declaredTables = (schema, db) => {
+    const bound = bind(db);
+    const tables = [];
+    for (const statement of schema.statements) {
+        const match = CREATE_TABLE.exec(statement(bound, {}).compile().sql);
+        if (match)
+            tables.push({ schema: match[1], name: match[2] });
+    }
+    return tables;
+};
+const tablesOf = async (db) => {
+    const tables = await bind(db).introspection.getTables();
+    return {
+        qualified: new Set(tables
+            .filter((table) => table.schema)
+            .map((table) => `${table.schema}.${table.name}`)),
+        bare: new Set(tables.map((table) => table.name)),
+        schemaAware: tables.some((table) => table.schema !== undefined),
+    };
+};
+/**
+ * Qualified declarations match on the pair — but only where that pair means
+ * something.
+ *
+ * `TableMetadata.schema` is optional, and sqlite and mysql leave it unset:
+ * sqlite has one schema to be in, and mysql calls the thing a database. A
+ * `withSchema('main')` connection there declares `main.workflow_runs` while
+ * introspection can only offer `workflow_runs`, and holding out for the pair
+ * would read every existing table as missing — the same false negative this
+ * whole function exists to fix, arrived at from the other side. So when the
+ * engine reports no schemas, the bare name is the only name there is.
+ */
+const isPresent = (existing, table) => table.schema && existing.schemaAware
+    ? existing.qualified.has(`${table.schema}.${table.name}`)
+    : existing.bare.has(table.name);
+/**
+ * Make sure one schema's tables are there, creating them only if none are.
+ *
+ * What a service calls at boot. It looks before it creates, which is the whole
+ * difference from the `.ifNotExists()` DDL this replaces: that spelling turned
+ * every failure into a silent no-op, and hid a foreign key onto `user.id` that
+ * postgres had been rejecting since the day it was written.
+ *
+ * A partially-present schema is refused rather than completed. Half a schema
+ * means something else already applied part of it — a migration, an older
+ * version, a hand-run script — and creating the remainder at boot would leave
+ * two authorities over one set of tables, which is the condition all of this
+ * exists to end.
+ *
+ * Creating at boot is the fallback, not the intent. `pikku db generate` writes
+ * the declaration down as a migration; a project that has done so takes the
+ * `present` path and this never issues DDL at all.
+ */
+export const ensurePikkuSchema = async (db, schema) => {
+    const existing = await tablesOf(db);
+    const declared = declaredTables(schema, db);
+    const missing = declared.filter((table) => !isPresent(existing, table));
+    if (missing.length === 0)
+        return 'present';
+    if (missing.length < declared.length) {
+        throw new Error(`The '${schema.name}' schema is half applied: ${missing.map(displayName).join(', ')} missing, ` +
+            `${declared
+                .filter((table) => isPresent(existing, table))
+                .map(displayName)
+                .join(', ')} already there. ` +
+            'Something else owns part of it. Reconcile it with a migration — ' +
+            '`pikku db generate` writes the declaration down — rather than creating the rest at boot.');
+    }
+    try {
+        await applyPikkuSchemas(db, [schema]);
+        return 'created';
+    }
+    catch (error) {
+        // Two instances booting cold against one database can both see it empty
+        // before either has finished creating. If the other one got there, say so;
+        // anything else is a real failure and still throws. This is a courtesy, not
+        // a guarantee — a boot race is only fully answered by having run the
+        // migration, which is what `pikku db generate` is for.
+        const after = await tablesOf(db);
+        if (declared.every((table) => isPresent(after, table)))
+            return 'present';
+        throw error;
+    }
+};
+/**
+ * Render the declaration as SQL for the dialect `db` was built with.
+ *
+ * `types` comes from `resolveRequirements` against the database the migration
+ * is being written for. Omit it and foreign keys onto another source's columns
+ * compile as `text`, which is a shape, not a migration.
+ */
+export const compilePikkuSchemas = (db, schemas = pikkuSchemas, types = {}) => {
+    const bound = bind(db);
+    return schemas
+        .flatMap((schema) => schema.statements.map((statement) => `${statement(bound, types).compile().sql};`))
+        .join('\n\n');
+};

package/dist/src/schema/pikku-schema.types.d.ts

@@ -0,0 +1,75 @@
+import { type CompiledQuery, type Kysely, type RawBuilder } from 'kysely';
+/**
+ * One DDL statement, bound to a database.
+ *
+ * Bound rather than free-standing because the same declaration serves two
+ * purposes that need the same object: applied to a throwaway database it yields
+ * the schema to introspect, and compiled against a dialect it yields the SQL a
+ * migration is written from.
+ */
+export interface SchemaStatement {
+    execute(): Promise<unknown>;
+    compile(): CompiledQuery;
+}
+export type SchemaStatementFactory = (db: Kysely<any>, types: RequiredTypes) => SchemaStatement;
+/**
+ * The physical types of the columns named in `requires`, keyed `table.column`.
+ *
+ * Introspected from the database the schemas are being applied to, because a
+ * foreign key column has to be declared with the type of the column it points
+ * at and that column belongs to somebody else.
+ */
+export type RequiredTypes = Record<string, string>;
+/**
+ * The declared type for a foreign key onto a column another source owns.
+ *
+ * Falls back to `text` when nothing has been introspected — the case when the
+ * declaration is compiled without a database, where the real type is unknowable
+ * and only the shape of the statement is being inspected.
+ */
+export declare const requiredType: (types: RequiredTypes, table: string, column: string) => RawBuilder<unknown>;
+/**
+ * The tables one part of the pikku runtime needs, declared rather than created.
+ *
+ * `name` labels the generated migration and the drift report, so it is part of
+ * the contract — changing it orphans the migration that was written under the
+ * old one.
+ */
+export interface PikkuSchema {
+    name: string;
+    statements: SchemaStatementFactory[];
+    /**
+     * Tables this schema references but does not create, which something else
+     * must have created first.
+     *
+     * Declared rather than discovered so the failure arrives as a sentence naming
+     * what is missing and who owns it, instead of a foreign key error from the
+     * database — or, worse, a stub table conjured up to make the error go away.
+     */
+    requires?: SchemaRequirement[];
+}
+/**
+ * A column another source owns, which one of these schemas depends on.
+ *
+ * Named down to the column, not just the table, because that is the granularity
+ * the dependency actually has: a foreign key needs the referenced column to
+ * exist *and* needs its type in order to declare a matching one.
+ *
+ * `owner` is carried in the declaration rather than composed into the error at
+ * the point it is thrown, so adding a second prerequisite cannot leave behind a
+ * message that still names the first one's owner.
+ */
+export interface SchemaRequirement {
+    table: string;
+    column: string;
+    owner: string;
+}
+/**
+ * Wrap a raw SQL fragment as a statement.
+ *
+ * For the DDL kysely's schema builder cannot express — a unique index over an
+ * expression, say. Note that raw SQL is *not* rewritten by `withSchema`, so a
+ * fragment naming a table unqualified will resolve against the connection's
+ * search path rather than the schema the rest of the declaration lands in.
+ */
+export declare const rawStatement: (fragment: RawBuilder<unknown>) => SchemaStatementFactory;

package/dist/src/schema/pikku-schema.types.js

@@ -0,0 +1,21 @@
+import { sql } from 'kysely';
+/**
+ * The declared type for a foreign key onto a column another source owns.
+ *
+ * Falls back to `text` when nothing has been introspected — the case when the
+ * declaration is compiled without a database, where the real type is unknowable
+ * and only the shape of the statement is being inspected.
+ */
+export const requiredType = (types, table, column) => sql.raw(types[`${table}.${column}`] ?? 'text');
+/**
+ * Wrap a raw SQL fragment as a statement.
+ *
+ * For the DDL kysely's schema builder cannot express — a unique index over an
+ * expression, say. Note that raw SQL is *not* rewritten by `withSchema`, so a
+ * fragment naming a table unqualified will resolve against the connection's
+ * search path rather than the schema the rest of the declaration lands in.
+ */
+export const rawStatement = (fragment) => (db) => ({
+    execute: () => fragment.execute(db),
+    compile: () => fragment.compile(db),
+});

package/dist/src/schema/scope.schema.d.ts

@@ -0,0 +1,18 @@
+import { type PikkuSchema } from './pikku-schema.types.js';
+/**
+ * Scopes, roles and the grants that bind them to users.
+ *
+ * `pikkuUserRole` and `pikkuUserScope` reference `user.id`, which Better Auth
+ * owns. Auth is a prerequisite rather than an optional companion: a grant is
+ * made to a user, so without the table the user lives in there is nothing to
+ * grant to, and the cascade that revokes grants when a user is deleted has
+ * nothing to hang off.
+ *
+ * `userId` takes its type from `user.id` rather than declaring one, because
+ * that type is Better Auth's to decide: `text` by default, `uuid` under
+ * `generateId: 'uuid'`, an identity `integer` under `'serial'`. The old
+ * hand-written DDL said `text`, and postgres rejects a `text` column
+ * referencing either of the others — so the whole statement failed and projects
+ * wrote these tables by hand instead.
+ */
+export declare const scopeSchema: PikkuSchema;

package/dist/src/schema/scope.schema.js

@@ -0,0 +1,61 @@
+import { sql } from 'kysely';
+import { requiredType } from './pikku-schema.types.js';
+/**
+ * Scopes, roles and the grants that bind them to users.
+ *
+ * `pikkuUserRole` and `pikkuUserScope` reference `user.id`, which Better Auth
+ * owns. Auth is a prerequisite rather than an optional companion: a grant is
+ * made to a user, so without the table the user lives in there is nothing to
+ * grant to, and the cascade that revokes grants when a user is deleted has
+ * nothing to hang off.
+ *
+ * `userId` takes its type from `user.id` rather than declaring one, because
+ * that type is Better Auth's to decide: `text` by default, `uuid` under
+ * `generateId: 'uuid'`, an identity `integer` under `'serial'`. The old
+ * hand-written DDL said `text`, and postgres rejects a `text` column
+ * referencing either of the others — so the whole statement failed and projects
+ * wrote these tables by hand instead.
+ */
+export const scopeSchema = {
+    name: 'scope',
+    requires: [{ table: 'user', column: 'id', owner: 'Better Auth' }],
+    statements: [
+        (db) => db.schema
+            .createTable('pikkuScopes')
+            .addColumn('name', 'text', (col) => col.primaryKey())
+            .addColumn('description', 'text')
+            .addColumn('declared', 'boolean', (col) => col.defaultTo(true).notNull()),
+        (db) => db.schema
+            .createTable('pikkuRoles')
+            .addColumn('name', 'text', (col) => col.primaryKey())
+            .addColumn('description', 'text')
+            .addColumn('createdAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull()),
+        (db) => db.schema
+            .createTable('pikkuRoleScopes')
+            .addColumn('role', 'text', (col) => col.notNull().references('pikkuRoles.name').onDelete('cascade'))
+            .addColumn('scope', 'text', (col) => col.notNull().references('pikkuScopes.name').onDelete('cascade'))
+            .addPrimaryKeyConstraint('pikku_role_scopes_pk', ['role', 'scope']),
+        (db, types) => db.schema
+            .createTable('pikkuUserRole')
+            .addColumn('userId', requiredType(types, 'user', 'id'), (col) => col.notNull().references('user.id').onDelete('cascade'))
+            .addColumn('role', 'text', (col) => col.notNull().references('pikkuRoles.name').onDelete('cascade'))
+            .addColumn('grantedBy', 'text')
+            .addColumn('grantedAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
+            .addPrimaryKeyConstraint('pikku_user_role_pk', ['userId', 'role']),
+        (db, types) => db.schema
+            .createTable('pikkuUserScope')
+            .addColumn('userId', requiredType(types, 'user', 'id'), (col) => col.notNull().references('user.id').onDelete('cascade'))
+            .addColumn('scope', 'text', (col) => col.notNull().references('pikkuScopes.name').onDelete('cascade'))
+            .addColumn('grantedBy', 'text')
+            .addColumn('grantedAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
+            .addPrimaryKeyConstraint('pikku_user_scope_pk', ['userId', 'scope']),
+        (db) => db.schema
+            .createIndex('pikku_role_scopes_scope_idx')
+            .on('pikkuRoleScopes')
+            .column('scope'),
+        (db) => db.schema
+            .createIndex('pikku_user_role_role_idx')
+            .on('pikkuUserRole')
+            .column('role'),
+    ],
+};

package/dist/src/schema/secret.schema.d.ts

@@ -0,0 +1,11 @@
+import type { PikkuSchema } from './pikku-schema.types.js';
+/**
+ * Encrypted secrets and their audit trail.
+ *
+ * The audit table is declared unconditionally, where `init()` created it only
+ * when the service was constructed with auditing on. A migration cannot depend
+ * on runtime configuration, and the asymmetry favours declaring it: an unused
+ * table costs nothing, while turning auditing on against a database that never
+ * got the table fails on the first write.
+ */
+export declare const secretSchema: PikkuSchema;

package/dist/src/schema/secret.schema.js

@@ -0,0 +1,29 @@
+import { sql } from 'kysely';
+/**
+ * Encrypted secrets and their audit trail.
+ *
+ * The audit table is declared unconditionally, where `init()` created it only
+ * when the service was constructed with auditing on. A migration cannot depend
+ * on runtime configuration, and the asymmetry favours declaring it: an unused
+ * table costs nothing, while turning auditing on against a database that never
+ * got the table fails on the first write.
+ */
+export const secretSchema = {
+    name: 'secret',
+    statements: [
+        (db) => db.schema
+            .createTable('secrets')
+            .addColumn('key', 'varchar(255)', (col) => col.primaryKey())
+            .addColumn('ciphertext', 'text', (col) => col.notNull())
+            .addColumn('wrappedDek', 'text', (col) => col.notNull())
+            .addColumn('keyVersion', 'integer', (col) => col.notNull())
+            .addColumn('createdAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
+            .addColumn('updatedAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull()),
+        (db) => db.schema
+            .createTable('secretsAudit')
+            .addColumn('id', 'varchar(36)', (col) => col.primaryKey())
+            .addColumn('secretKey', 'varchar(255)', (col) => col.notNull())
+            .addColumn('action', 'varchar(20)', (col) => col.notNull())
+            .addColumn('performedAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull()),
+    ],
+};

package/dist/src/schema/session.schema.d.ts

@@ -0,0 +1,3 @@
+import type { PikkuSchema } from './pikku-schema.types.js';
+/** Server-side session storage. */
+export declare const sessionSchema: PikkuSchema;

package/dist/src/schema/session.schema.js

@@ -0,0 +1,13 @@
+import { sql } from 'kysely';
+/** Server-side session storage. */
+export const sessionSchema = {
+    name: 'session',
+    statements: [
+        (db) => db.schema
+            .createTable('pikkuUserSessions')
+            .addColumn('pikkuUserId', 'text', (col) => col.primaryKey())
+            .addColumn('session', 'text', (col) => col.notNull())
+            .addColumn('createdAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
+            .addColumn('updatedAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull()),
+    ],
+};

package/dist/src/schema/webhook.schema.d.ts

@@ -0,0 +1,3 @@
+import type { PikkuSchema } from './pikku-schema.types.js';
+/** Webhook deliveries and one row per delivery attempt. */
+export declare const webhookSchema: PikkuSchema;

package/dist/src/schema/webhook.schema.js

@@ -0,0 +1,38 @@
+import { sql } from 'kysely';
+/** Webhook deliveries and one row per delivery attempt. */
+export const webhookSchema = {
+    name: 'webhook',
+    statements: [
+        (db) => db.schema
+            .createTable('webhookDelivery')
+            .addColumn('deliveryId', 'text', (col) => col.primaryKey())
+            .addColumn('organizationId', 'text')
+            .addColumn('url', 'text', (col) => col.notNull())
+            .addColumn('event', 'text')
+            .addColumn('status', 'text', (col) => col.defaultTo('pending').notNull())
+            .addColumn('attempts', 'integer', (col) => col.defaultTo(0).notNull())
+            .addColumn('createdAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
+            .addColumn('updatedAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
+            .addColumn('deliveredAt', 'timestamp'),
+        (db) => db.schema
+            .createTable('webhookDeliveryAttempt')
+            .addColumn('attemptId', 'text', (col) => col.primaryKey())
+            .addColumn('deliveryId', 'text', (col) => col
+            .notNull()
+            .references('webhookDelivery.deliveryId')
+            .onDelete('cascade'))
+            .addColumn('attemptNumber', 'integer', (col) => col.notNull())
+            .addColumn('statusCode', 'integer')
+            .addColumn('responseBody', 'text')
+            .addColumn('error', 'text')
+            .addColumn('createdAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull()),
+        (db) => db.schema
+            .createIndex('idx_webhook_delivery_org')
+            .on('webhookDelivery')
+            .column('organizationId'),
+        (db) => db.schema
+            .createIndex('idx_webhook_delivery_attempt_delivery')
+            .on('webhookDeliveryAttempt')
+            .column('deliveryId'),
+    ],
+};

package/dist/src/schema/workflow.schema.d.ts

@@ -0,0 +1,15 @@
+import type { PikkuSchema } from './pikku-schema.types.js';
+/**
+ * Workflow runs, their steps, per-step history and the versioned graphs.
+ *
+ * Two things from the boot-time DDL are deliberately not carried over. The
+ * primary keys had `defaultTo(sql.raw("'" + crypto.randomUUID() + "'"))`, which
+ * evaluates once while the statement is built — every row would have taken the
+ * same default, so it was never a generator; the services supply the id. And
+ * `workflowStep.fromStepName` was backfilled by an `alterTable(...).catch(() =>
+ * {})` bolted on after the fact, which is the job a migration does.
+ *
+ * `KyselyWorkflowMirror` created these same four tables separately. There is one
+ * declaration now, and both services read it.
+ */
+export declare const workflowSchema: PikkuSchema;

package/dist/src/schema/workflow.schema.js

@@ -0,0 +1,86 @@
+import { sql } from 'kysely';
+/**
+ * Workflow runs, their steps, per-step history and the versioned graphs.
+ *
+ * Two things from the boot-time DDL are deliberately not carried over. The
+ * primary keys had `defaultTo(sql.raw("'" + crypto.randomUUID() + "'"))`, which
+ * evaluates once while the statement is built — every row would have taken the
+ * same default, so it was never a generator; the services supply the id. And
+ * `workflowStep.fromStepName` was backfilled by an `alterTable(...).catch(() =>
+ * {})` bolted on after the fact, which is the job a migration does.
+ *
+ * `KyselyWorkflowMirror` created these same four tables separately. There is one
+ * declaration now, and both services read it.
+ */
+export const workflowSchema = {
+    name: 'workflow',
+    statements: [
+        (db) => db.schema
+            .createTable('workflowRuns')
+            .addColumn('workflowRunId', 'text', (col) => col.primaryKey())
+            .addColumn('workflow', 'text', (col) => col.notNull())
+            .addColumn('status', 'text', (col) => col.notNull())
+            .addColumn('input', 'text', (col) => col.notNull())
+            .addColumn('output', 'text')
+            .addColumn('error', 'text')
+            .addColumn('state', 'text', (col) => col.defaultTo('{}'))
+            .addColumn('inline', 'boolean', (col) => col.defaultTo(false))
+            .addColumn('graphHash', 'text')
+            .addColumn('deterministic', 'boolean', (col) => col.defaultTo(false))
+            .addColumn('plannedSteps', 'text')
+            .addColumn('wire', 'text')
+            .addColumn('createdAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
+            .addColumn('updatedAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull()),
+        (db) => db.schema
+            .createTable('workflowStep')
+            .addColumn('workflowStepId', 'text', (col) => col.primaryKey())
+            .addColumn('workflowRunId', 'text', (col) => col
+            .notNull()
+            .references('workflowRuns.workflowRunId')
+            .onDelete('cascade'))
+            .addColumn('stepName', 'text', (col) => col.notNull())
+            .addColumn('rpcName', 'text')
+            .addColumn('data', 'text')
+            .addColumn('status', 'text', (col) => col.notNull().defaultTo('pending'))
+            .addColumn('result', 'text')
+            .addColumn('error', 'text')
+            .addColumn('childRunId', 'text')
+            .addColumn('branchTaken', 'text')
+            .addColumn('retries', 'integer')
+            .addColumn('retryDelay', 'text')
+            .addColumn('fromStepName', 'text')
+            .addColumn('createdAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
+            .addColumn('updatedAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
+            .addUniqueConstraint('workflow_step_run_name_unique', [
+            'workflowRunId',
+            'stepName',
+        ]),
+        (db) => db.schema
+            .createTable('workflowStepHistory')
+            .addColumn('historyId', 'text', (col) => col.primaryKey())
+            .addColumn('workflowStepId', 'text', (col) => col
+            .notNull()
+            .references('workflowStep.workflowStepId')
+            .onDelete('cascade'))
+            .addColumn('status', 'text', (col) => col.notNull())
+            .addColumn('result', 'text')
+            .addColumn('error', 'text')
+            .addColumn('createdAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
+            .addColumn('runningAt', 'timestamp')
+            .addColumn('scheduledAt', 'timestamp')
+            .addColumn('succeededAt', 'timestamp')
+            .addColumn('failedAt', 'timestamp'),
+        (db) => db.schema
+            .createTable('workflowVersions')
+            .addColumn('workflowName', 'text', (col) => col.notNull())
+            .addColumn('graphHash', 'text', (col) => col.notNull())
+            .addColumn('graph', 'text', (col) => col.notNull())
+            .addColumn('source', 'text', (col) => col.notNull())
+            .addColumn('status', 'text', (col) => col.notNull().defaultTo('active'))
+            .addColumn('createdAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
+            .addPrimaryKeyConstraint('workflow_versions_pk', [
+            'workflowName',
+            'graphHash',
+        ]),
+    ],
+};