@pikku/kysely 0.13.6 → 0.13.10

package/dist/src/kysely-secret-service.js

@@ -1,9 +1,12 @@
-import { envelopeEncrypt, envelopeDecrypt, envelopeRewrap, } from '@pikku/core/crypto-utils';
+import { createSecretValue, isSecretValue } from '@pikku/core';
+import { deriveKEK, generateKEKSalt, envelopeEncrypt, envelopeDecrypt, envelopeRewrap, } from '@pikku/core/crypto-utils';
 import { ensurePikkuSchema } from './schema/index.js';
 import { secretSchema } from './schema/secret.schema.js';
 export class KyselySecretService {
     db;
     initialized = false;
+    kekSalts = new Map();
+    keks = new Map();
     key;
     keyVersion;
     previousKey;
@@ -38,12 +41,47 @@ export class KyselySecretService {
         })
             .execute();
     }
-    getKEK(version) {
-        if (version === this.keyVersion)
-            return this.key;
-        if (this.previousKey)
-            return this.previousKey;
-        throw new Error(`No KEK available for key_version ${version}`);
+    async getKEKSalt(version) {
+        const cached = this.kekSalts.get(version);
+        if (cached)
+            return cached;
+        const existing = await this.db
+            .selectFrom('secretKekSalts')
+            .select('salt')
+            .where('keyVersion', '=', version)
+            .executeTakeFirst();
+        let salt = existing?.salt;
+        if (!salt) {
+            await this.db
+                .insertInto('secretKekSalts')
+                .values({
+                keyVersion: version,
+                salt: generateKEKSalt(),
+                createdAt: new Date().toISOString(),
+            })
+                .onConflict((oc) => oc.column('keyVersion').doNothing())
+                .execute();
+            const row = await this.db
+                .selectFrom('secretKekSalts')
+                .select('salt')
+                .where('keyVersion', '=', version)
+                .executeTakeFirstOrThrow();
+            salt = row.salt;
+        }
+        this.kekSalts.set(version, salt);
+        return salt;
+    }
+    async getKEK(version) {
+        const cached = this.keks.get(version);
+        if (cached)
+            return cached;
+        const passphrase = version === this.keyVersion ? this.key : this.previousKey;
+        if (!passphrase) {
+            throw new Error(`No KEK available for key_version ${version}`);
+        }
+        const kek = await deriveKEK(passphrase, await this.getKEKSalt(version));
+        this.keks.set(version, kek);
+        return kek;
     }
     async getSecret(key) {
         const row = await this.db
@@ -53,10 +91,10 @@ export class KyselySecretService {
             .executeTakeFirst();
         if (!row)
             throw new Error('Requested secret not found');
-        const kek = this.getKEK(row.keyVersion);
+        const kek = await this.getKEK(row.keyVersion);
         const result = await envelopeDecrypt(kek, row.ciphertext, row.wrappedDek);
         await this.logAudit(key, 'read');
-        return result;
+        return createSecretValue(result);
     }
     async hasSecret(key) {
         const row = await this.db
@@ -67,7 +105,9 @@ export class KyselySecretService {
         return !!row;
     }
     async setSecret(key, value) {
-        const { ciphertext, wrappedDEK } = await envelopeEncrypt(this.key, value);
+        // Encrypting the wrapper would store its redaction, not the secret —
+        // writing a secret back to the vault is exactly what this method is for.
+        const { ciphertext, wrappedDEK } = await envelopeEncrypt(await this.getKEK(this.keyVersion), isSecretValue(value) ? value.reveal() : value);
         const now = new Date().toISOString();
         await this.db
             .insertInto('secrets')
@@ -101,8 +141,8 @@ export class KyselySecretService {
         const out = {};
         for (const row of rows) {
             try {
-                const kek = this.getKEK(row.keyVersion);
-                out[row.key] = await envelopeDecrypt(kek, row.ciphertext, row.wrappedDek);
+                const kek = await this.getKEK(row.keyVersion);
+                out[row.key] = createSecretValue(await envelopeDecrypt(kek, row.ciphertext, row.wrappedDek));
             }
             catch (cause) {
                 // A stored secret that fails to decrypt is never expected — it means the
@@ -126,8 +166,10 @@ export class KyselySecretService {
             .select(['key', 'wrappedDek'])
             .where('keyVersion', '<', this.keyVersion)
             .execute();
+        const oldKEK = await this.getKEK(this.keyVersion - 1);
+        const newKEK = await this.getKEK(this.keyVersion);
         for (const row of rows) {
-            const newWrappedDEK = await envelopeRewrap(this.previousKey, this.key, row.wrappedDek);
+            const newWrappedDEK = await envelopeRewrap(oldKEK, newKEK, row.wrappedDek);
             await this.db
                 .updateTable('secrets')
                 .set({

package/dist/src/kysely-tables.d.ts

@@ -116,7 +116,12 @@ export interface AIRunTable {
     agentName: string;
     threadId: string;
     resourceId: string;
-    status: Generated<'running' | 'suspended' | 'completed' | 'failed'>;
+    /**
+     * `interrupted` is distinct from `failed`: the run was stopped on purpose,
+     * usually because the user talked over it. Nothing went wrong, so it should
+     * not show up in error reporting.
+     */
+    status: Generated<'running' | 'suspended' | 'completed' | 'failed' | 'interrupted'>;
     errorMessage: string | null;
     suspendReason: 'approval' | 'credential' | 'rpc-missing' | null;
     missingRpcs: string | null;
@@ -146,6 +151,11 @@ export interface SecretsTable {
     createdAt: Generated<Date>;
     updatedAt: Generated<Date>;
 }
+export interface KekSaltsTable {
+    keyVersion: number;
+    salt: string;
+    createdAt: Generated<Date>;
+}
 export interface SecretsAuditTable {
     id: string;
     secretKey: string;
@@ -191,10 +201,14 @@ export interface PikkuScopesTable {
      */
     declared: Generated<boolean>;
 }
-/** A role: an admin-composed bag of scopes. */
+/** A role: a bag of scopes, composed by an admin or declared in code. */
 export interface PikkuRolesTable {
     name: string;
     description: string | null;
+    /** Declared with `defineSystemRole`, and therefore not editable here. */
+    system: Generated<boolean>;
+    /** False for a system role whose declaration has gone: held, but inert. */
+    declared: Generated<boolean>;
     createdAt: Generated<Date>;
 }
 export interface PikkuRoleScopesTable {
@@ -234,6 +248,36 @@ export interface WebhookDeliveryAttemptTable {
     error: string | null;
     createdAt: Generated<Date>;
 }
+/**
+ * One virtual-user run. The JSON columns (`goals`, `memory`, `findings`,
+ * `tally`) are text the store serialises itself, so the row is byte-identical
+ * on every engine.
+ */
+export interface VirtualUserRunTable {
+    runId: string;
+    persona: string;
+    disposition: string;
+    /**
+     * Read back as a string by some drivers — a BIGINT does not always fit a JS
+     * number — so the store narrows it rather than trusting the column type.
+     */
+    seed: string | number | bigint;
+    status: Generated<'running' | 'completed' | 'failed'>;
+    goals: Generated<string>;
+    memory: Generated<string>;
+    findings: Generated<string>;
+    tally: string | null;
+    stoppedBy: string | null;
+    error: string | null;
+    startedBy: string | null;
+    /**
+     * Written as an ISO string and read back as whatever the driver returns — a
+     * bare SQLite driver cannot bind a `Date` at all, and the store normalises
+     * both ends.
+     */
+    createdAt: Generated<Date | string>;
+    finishedAt: Date | string | null;
+}
 export interface KyselyPikkuDB {
     pikkuScopes: PikkuScopesTable;
     pikkuRoles: PikkuRolesTable;
@@ -254,10 +298,13 @@ export interface KyselyPikkuDB {
     pikkuDeployments: PikkuDeploymentsTable;
     pikkuDeploymentFunctions: PikkuDeploymentFunctionsTable;
     secrets: SecretsTable;
+    secretKekSalts: KekSaltsTable;
     secretsAudit: SecretsAuditTable;
     credentials: CredentialsTable;
+    credentialKekSalts: KekSaltsTable;
     credentialsAudit: CredentialsAuditTable;
     pikkuUserSessions: UserSessionsTable;
     webhookDelivery: WebhookDeliveryTable;
     webhookDeliveryAttempt: WebhookDeliveryAttemptTable;
+    virtualUserRun: VirtualUserRunTable;
 }

package/dist/src/kysely-virtual-user-run-store.d.ts

@@ -0,0 +1,43 @@
+import type { Kysely } from 'kysely';
+import type { VirtualUserRunOutcome, VirtualUserRunRecord, VirtualUserRunStart, VirtualUserRunStore } from '@pikku/core/virtual-user';
+import type { KyselyPikkuDB } from './kysely-tables.js';
+/**
+ * Records virtual-user runs in a `virtualUserRun` table.
+ *
+ * The store is the whole record of a run: `runVirtualUser` returns as soon as
+ * the row exists and the engine keeps going without it, so nothing else knows
+ * the run happened. That is why `fail()` exists as its own call — a run that
+ * crashed and a run that found nothing are different answers, and a row left at
+ * `running` is neither.
+ *
+ * Works with or without `SerializePlugin`, which not every project installs: the
+ * JSON columns are written as strings (which the plugin passes through) and read
+ * back through `parseJson` (which passes through what the plugin already
+ * parsed). Timestamps are written as ISO strings for the same reason — a bare
+ * SQLite driver cannot bind a `Date` at all.
+ *
+ * SECURITY: an `adversarial` run's findings are working exploits carrying live
+ * ids. This is a privileged store; the scaffolded reads are scope-gated, and
+ * exposing these rows more widely publishes your own exploits.
+ */
+export declare class KyselyVirtualUserRunStore implements VirtualUserRunStore {
+    private db;
+    private initialized;
+    constructor(db: Kysely<KyselyPikkuDB>);
+    /**
+     * Creates the table on first use, like the audit sink — the runtime does not
+     * need it, so it arrives with the feature that fills it rather than in every
+     * database.
+     */
+    init(): Promise<void>;
+    start(run: VirtualUserRunStart): Promise<string>;
+    complete(runId: string, outcome: VirtualUserRunOutcome): Promise<void>;
+    fail(runId: string, error: string): Promise<void>;
+    get(runId: string): Promise<VirtualUserRunRecord | null>;
+    list(options?: {
+        persona?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<VirtualUserRunRecord[]>;
+    private toRecord;
+}

package/dist/src/kysely-virtual-user-run-store.js

@@ -0,0 +1,131 @@
+import { randomUUID } from 'node:crypto';
+import { parseJson } from './kysely-json.js';
+import { ensurePikkuSchema } from './schema/index.js';
+import { virtualUserSchema } from './schema/virtual-user.schema.js';
+/**
+ * Records virtual-user runs in a `virtualUserRun` table.
+ *
+ * The store is the whole record of a run: `runVirtualUser` returns as soon as
+ * the row exists and the engine keeps going without it, so nothing else knows
+ * the run happened. That is why `fail()` exists as its own call — a run that
+ * crashed and a run that found nothing are different answers, and a row left at
+ * `running` is neither.
+ *
+ * Works with or without `SerializePlugin`, which not every project installs: the
+ * JSON columns are written as strings (which the plugin passes through) and read
+ * back through `parseJson` (which passes through what the plugin already
+ * parsed). Timestamps are written as ISO strings for the same reason — a bare
+ * SQLite driver cannot bind a `Date` at all.
+ *
+ * SECURITY: an `adversarial` run's findings are working exploits carrying live
+ * ids. This is a privileged store; the scaffolded reads are scope-gated, and
+ * exposing these rows more widely publishes your own exploits.
+ */
+export class KyselyVirtualUserRunStore {
+    db;
+    initialized = false;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Creates the table on first use, like the audit sink — the runtime does not
+     * need it, so it arrives with the feature that fills it rather than in every
+     * database.
+     */
+    async init() {
+        if (this.initialized)
+            return;
+        await ensurePikkuSchema(this.db, virtualUserSchema);
+        this.initialized = true;
+    }
+    async start(run) {
+        await this.init();
+        const runId = randomUUID();
+        await this.db
+            .insertInto('virtualUserRun')
+            .values({
+            runId,
+            persona: run.persona,
+            disposition: run.disposition,
+            // Text on every engine (see the schema), so the seed round-trips
+            // through drivers that hand a BIGINT back as a string.
+            seed: String(run.seed),
+            status: 'running',
+            goals: JSON.stringify(run.goals ?? []),
+            memory: JSON.stringify(run.memory ?? {}),
+            findings: '[]',
+            startedBy: run.startedBy ?? null,
+        })
+            .execute();
+        return runId;
+    }
+    async complete(runId, outcome) {
+        await this.init();
+        await this.db
+            .updateTable('virtualUserRun')
+            .set({
+            status: 'completed',
+            findings: JSON.stringify(outcome.findings),
+            tally: JSON.stringify(outcome.tally),
+            // Overwritten rather than merged: the engine's memory already carries
+            // what it was given, plus what it learned on the way.
+            memory: JSON.stringify(outcome.memory),
+            stoppedBy: outcome.stoppedBy,
+            finishedAt: new Date().toISOString(),
+        })
+            .where('runId', '=', runId)
+            .execute();
+    }
+    async fail(runId, error) {
+        await this.init();
+        await this.db
+            .updateTable('virtualUserRun')
+            .set({
+            status: 'failed',
+            error,
+            finishedAt: new Date().toISOString(),
+        })
+            .where('runId', '=', runId)
+            .execute();
+    }
+    async get(runId) {
+        await this.init();
+        const row = await this.db
+            .selectFrom('virtualUserRun')
+            .selectAll()
+            .where('runId', '=', runId)
+            .executeTakeFirst();
+        return row ? this.toRecord(row) : null;
+    }
+    async list(options) {
+        await this.init();
+        let query = this.db.selectFrom('virtualUserRun').selectAll();
+        if (options?.persona) {
+            query = query.where('persona', '=', options.persona);
+        }
+        const rows = await query
+            .orderBy('createdAt', 'desc')
+            .limit(options?.limit ?? 50)
+            .offset(options?.offset ?? 0)
+            .execute();
+        return rows.map((row) => this.toRecord(row));
+    }
+    toRecord(row) {
+        return {
+            runId: row.runId,
+            persona: row.persona,
+            disposition: row.disposition,
+            seed: Number(row.seed),
+            status: row.status,
+            goals: parseJson(row.goals) ?? [],
+            memory: parseJson(row.memory) ?? {},
+            findings: parseJson(row.findings) ?? [],
+            tally: row.tally ? (parseJson(row.tally) ?? null) : null,
+            stoppedBy: row.stoppedBy,
+            error: row.error,
+            startedBy: row.startedBy,
+            createdAt: new Date(row.createdAt),
+            finishedAt: row.finishedAt ? new Date(row.finishedAt) : null,
+        };
+    }
+}

package/dist/src/kysely-workflow-service.d.ts

@@ -52,7 +52,6 @@ export declare class KyselyWorkflowService extends PikkuWorkflowService {
         failedNodeIds: string[];
         branchKeys: Record<string, string>;
     }>;
-    getNodesWithoutSteps(runId: string, nodeIds: string[]): Promise<string[]>;
     getStepInstances(runId: string): Promise<Array<{
         stepName: string;
         status: StepStatus;

package/dist/src/kysely-workflow-service.js

@@ -393,18 +393,6 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
         }
         return { completedNodeIds, failedNodeIds, branchKeys };
     }
-    async getNodesWithoutSteps(runId, nodeIds) {
-        if (nodeIds.length === 0)
-            return [];
-        const result = await this.db
-            .selectFrom('workflowStep')
-            .select('stepName')
-            .where('workflowRunId', '=', runId)
-            .where('stepName', 'in', nodeIds)
-            .execute();
-        const existingStepNames = new Set(result.map((r) => r.stepName));
-        return nodeIds.filter((id) => !existingStepNames.has(id));
-    }
     async getStepInstances(runId) {
         const rows = await this.db
             .selectFrom('workflowStep')

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

@@ -0,0 +1,16 @@
+import type { PikkuSchema } from './pikku-schema.types.js';
+/**
+ * The `audit` table {@link KyselyAuditService} writes to and reads back.
+ *
+ * Deliberately not in `pikkuSchemas`: the runtime never needs this table, only
+ * a project that has wired a durable audit sink does, and creating it for
+ * everyone would put an empty table in every database. `KyselyAuditService.init()`
+ * applies it, so it arrives exactly when the sink that fills it does.
+ *
+ * Every column is text on every engine, matching the platform audit-queue
+ * consumer's row shape — a locally-run project and a deployed stage write rows
+ * the same reader can read. `occurredAt` is an ISO 8601 string rather than a
+ * timestamp for that reason: string ordering is chronological ordering, and the
+ * queue consumer has no shared type to agree on.
+ */
+export declare const auditSchema: PikkuSchema;

package/dist/src/schema/audit.schema.js

@@ -0,0 +1,47 @@
+/**
+ * The `audit` table {@link KyselyAuditService} writes to and reads back.
+ *
+ * Deliberately not in `pikkuSchemas`: the runtime never needs this table, only
+ * a project that has wired a durable audit sink does, and creating it for
+ * everyone would put an empty table in every database. `KyselyAuditService.init()`
+ * applies it, so it arrives exactly when the sink that fills it does.
+ *
+ * Every column is text on every engine, matching the platform audit-queue
+ * consumer's row shape — a locally-run project and a deployed stage write rows
+ * the same reader can read. `occurredAt` is an ISO 8601 string rather than a
+ * timestamp for that reason: string ordering is chronological ordering, and the
+ * queue consumer has no shared type to agree on.
+ */
+export const auditSchema = {
+    name: 'audit',
+    statements: [
+        (db) => db.schema
+            .createTable('audit')
+            .addColumn('auditId', 'text', (col) => col.primaryKey())
+            .addColumn('occurredAt', 'text', (col) => col.notNull())
+            .addColumn('type', 'text', (col) => col.notNull())
+            .addColumn('source', 'text', (col) => col.defaultTo('auto').notNull())
+            .addColumn('outcome', 'text')
+            .addColumn('functionId', 'text')
+            .addColumn('wireType', 'text')
+            .addColumn('traceId', 'text')
+            .addColumn('transactionId', 'text')
+            .addColumn('queryId', 'text')
+            .addColumn('userId', 'text')
+            .addColumn('orgId', 'text')
+            .addColumn('pikkuUserId', 'text')
+            .addColumn('tables', 'text')
+            .addColumn('changedCols', 'text')
+            .addColumn('event', 'text')
+            .addColumn('old', 'text')
+            .addColumn('data', 'text'),
+        // The trail is only ever read newest-first, and the two filters the console
+        // offers are user and type.
+        (db) => db.schema
+            .createIndex('idx_audit_occurred_at')
+            .on('audit')
+            .column('occurredAt'),
+        (db) => db.schema.createIndex('idx_audit_user_id').on('audit').column('userId'),
+        (db) => db.schema.createIndex('idx_audit_type').on('audit').column('type'),
+    ],
+};

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

@@ -5,7 +5,8 @@ import { type PikkuSchema } from './pikku-schema.types.js';
  * The uniqueness rule is an expression index — `user_id` is nullable and two
  * rows with a null user must still collide on name — which the schema builder
  * cannot express, so it stays raw. Raw SQL is not rewritten by `withSchema`,
- * which is why the table is named explicitly rather than left to the search
- * path.
+ * which is why the table goes through `ctx.table` rather than being left to the
+ * search path. The index's own name stays unqualified: an index belongs to the
+ * schema of the table it is on, and postgres rejects one that says otherwise.
  */
 export declare const credentialSchema: PikkuSchema;

package/dist/src/schema/credential.schema.js

@@ -6,8 +6,9 @@ import { rawStatement } from './pikku-schema.types.js';
  * The uniqueness rule is an expression index — `user_id` is nullable and two
  * rows with a null user must still collide on name — which the schema builder
  * cannot express, so it stays raw. Raw SQL is not rewritten by `withSchema`,
- * which is why the table is named explicitly rather than left to the search
- * path.
+ * which is why the table goes through `ctx.table` rather than being left to the
+ * search path. The index's own name stays unqualified: an index belongs to the
+ * schema of the table it is on, and postgres rejects one that says otherwise.
  */
 export const credentialSchema = {
     name: 'credential',
@@ -21,7 +22,12 @@ export const credentialSchema = {
             .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()),
-        rawStatement(sql `CREATE UNIQUE INDEX credentials_name_user_id_unique ON credentials (name, COALESCE(user_id, ''))`),
+        rawStatement(({ table }) => sql `CREATE UNIQUE INDEX credentials_name_user_id_unique ON ${table('credentials')} (name, COALESCE(user_id, ''))`),
+        (db) => db.schema
+            .createTable('credentialKekSalts')
+            .addColumn('keyVersion', 'integer', (col) => col.primaryKey())
+            .addColumn('salt', 'varchar(64)', (col) => col.notNull())
+            .addColumn('createdAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull()),
         (db) => db.schema
             .createTable('credentialsAudit')
             .addColumn('id', 'varchar(36)', (col) => col.primaryKey())

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

@@ -1,7 +1,13 @@
 import { type Kysely } from 'kysely';
-import type { PikkuSchema, RequiredTypes, SchemaRequirement } from './pikku-schema.types.js';
-export type { PikkuSchema, RequiredTypes, SchemaRequirement, SchemaStatement, SchemaStatementFactory, } from './pikku-schema.types.js';
-export { rawStatement, requiredType } from './pikku-schema.types.js';
+import { type PikkuSchema, type RequiredTypes, type SchemaRequirement } from './pikku-schema.types.js';
+export type { PikkuSchema, RequiredTypes, SchemaContext, SchemaRequirement, SchemaStatement, SchemaStatementFactory, } from './pikku-schema.types.js';
+export { rawStatement, requiredType, schemaContext, unqualifiedContext, } from './pikku-schema.types.js';
+/**
+ * Opt-in, so it is named here rather than folded into `pikkuSchemas` — the
+ * runtime works without an audit table, and `KyselyAuditService.init()` applies
+ * this for the projects that wire the sink.
+ */
+export { auditSchema } from './audit.schema.js';
 /**
  * Every table the pikku runtime needs, in dependency order.
  *
@@ -95,5 +101,12 @@ export declare const ensurePikkuSchema: (db: Kysely<any>, schema: PikkuSchema) =
  * `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.
+ *
+ * `schema` qualifies every table the migration creates, for a project that
+ * keeps the runtime tables somewhere other than the default search path. It is
+ * applied here and not to `db` itself because the caller's connection is a
+ * throwaway the declaration was just *applied* to, in whatever schema that
+ * database actually has — qualifying that would create tables in a schema the
+ * scratch database has never heard of. Only the rendered SQL is bound.
  */
-export declare const compilePikkuSchemas: (db: Kysely<any>, schemas?: PikkuSchema[], types?: RequiredTypes) => string;
+export declare const compilePikkuSchemas: (db: Kysely<any>, schemas?: PikkuSchema[], types?: RequiredTypes, schemaName?: string) => string;

package/dist/src/schema/index.js

@@ -1,4 +1,5 @@
 import { CamelCasePlugin } from 'kysely';
+import { schemaContext, } from './pikku-schema.types.js';
 import { aiSchema } from './ai.schema.js';
 import { channelSchema } from './channel.schema.js';
 import { credentialSchema } from './credential.schema.js';
@@ -8,7 +9,13 @@ 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';
+export { rawStatement, requiredType, schemaContext, unqualifiedContext, } from './pikku-schema.types.js';
+/**
+ * Opt-in, so it is named here rather than folded into `pikkuSchemas` — the
+ * runtime works without an audit table, and `KyselyAuditService.init()` applies
+ * this for the projects that wire the sink.
+ */
+export { auditSchema } from './audit.schema.js';
 /**
  * Every table the pikku runtime needs, in dependency order.
  *
@@ -37,6 +44,23 @@ export const pikkuSchemas = [
  * silently creates quoted camelCase tables that nothing can read.
  */
 const bind = (db) => db.withPlugin(new CamelCasePlugin());
+/**
+ * The schema a connection is bound to, or `undefined` for one that is not.
+ *
+ * Read back out of compiled DDL rather than off the connection, because kysely
+ * keeps the `withSchema(...)` setting inside its executor and exposes no way to
+ * ask. Compiling a throwaway `create table` is the same trick `declaredTables`
+ * uses on the real statements, against the same regex — nothing is executed and
+ * the probe never leaves this function.
+ *
+ * Derived rather than passed in so that raw statements follow whatever
+ * connection they are handed. A caller that had to remember to say the schema
+ * twice would eventually say it once.
+ */
+const boundSchema = (db) => CREATE_TABLE.exec(db.schema.createTable('pikkuSchemaProbe').addColumn('id', 'text').compile()
+    .sql)?.[1];
+/** The context for statements compiled against `db`, matching its binding. */
+const contextFor = (db) => schemaContext(boundSchema(db));
 /**
  * Look up every prerequisite in `db`, reporting the gaps and the types found.
  *
@@ -101,9 +125,10 @@ export const applyPikkuSchemas = async (db, schemas = pikkuSchemas) => {
     }
     await db.transaction().execute(async (trx) => {
         const bound = bind(trx);
+        const ctx = contextFor(bound);
         for (const schema of schemas) {
             for (const statement of schema.statements) {
-                const query = statement(bound, types);
+                const query = statement(bound, types, ctx);
                 try {
                     await query.execute();
                 }
@@ -177,9 +202,10 @@ const CREATE_TABLE = /^\s*create table (?:if not exists\s+)?(?:"([^"]+)"\.)?"([^
  */
 export const declaredTables = (schema, db) => {
     const bound = bind(db);
+    const ctx = contextFor(bound);
     const tables = [];
     for (const statement of schema.statements) {
-        const match = CREATE_TABLE.exec(statement(bound, {}).compile().sql);
+        const match = CREATE_TABLE.exec(statement(bound, {}, ctx).compile().sql);
         if (match)
             tables.push({ schema: match[1], name: match[2] });
     }
@@ -265,10 +291,18 @@ export const ensurePikkuSchema = async (db, schema) => {
  * `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.
+ *
+ * `schema` qualifies every table the migration creates, for a project that
+ * keeps the runtime tables somewhere other than the default search path. It is
+ * applied here and not to `db` itself because the caller's connection is a
+ * throwaway the declaration was just *applied* to, in whatever schema that
+ * database actually has — qualifying that would create tables in a schema the
+ * scratch database has never heard of. Only the rendered SQL is bound.
  */
-export const compilePikkuSchemas = (db, schemas = pikkuSchemas, types = {}) => {
-    const bound = bind(db);
+export const compilePikkuSchemas = (db, schemas = pikkuSchemas, types = {}, schemaName) => {
+    const bound = schemaName ? bind(db).withSchema(schemaName) : bind(db);
+    const ctx = contextFor(bound);
     return schemas
-        .flatMap((schema) => schema.statements.map((statement) => `${statement(bound, types).compile().sql};`))
+        .flatMap((schema) => schema.statements.map((statement) => `${statement(bound, types, ctx).compile().sql};`))
         .join('\n\n');
 };