@pikku/kysely 0.13.19 → 0.13.20

package/dist/src/schema/index.js

@@ -1,6 +1,7 @@
 import { CamelCasePlugin } from 'kysely';
 import { schemaContext, } from './pikku-schema.types.js';
 import { agentSchema } from './agent.schema.js';
+import { auditSchema } from './audit.schema.js';
 import { channelSchema } from './channel.schema.js';
 import { credentialSchema } from './credential.schema.js';
 import { deploymentSchema } from './deployment.schema.js';
@@ -9,19 +10,21 @@ import { secretSchema } from './secret.schema.js';
 import { sessionSchema } from './session.schema.js';
 import { webhookSchema } from './webhook.schema.js';
 import { workflowSchema } from './workflow.schema.js';
+import { virtualUserSchema } from './virtual-user.schema.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.
+ * Every table any part of the pikku runtime can need, 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.
+ *
+ * `audit` and `virtualUser` are in the list now. They used to be left out and
+ * created by their own services at boot, which was the only way they ever came
+ * into existence — so with the runtime no longer creating anything, leaving
+ * them out would mean a wired audit sink starting up against a table that
+ * nothing writes a migration for. Both are gated by `ownedBy`, so a project
+ * that wires neither still carries neither.
  */
 export const pikkuSchemas = [
     channelSchema,
@@ -33,7 +36,31 @@ export const pikkuSchemas = [
     workflowSchema,
     agentSchema,
     scopeSchema,
+    auditSchema,
+    virtualUserSchema,
 ];
+export { agentSchema } from './agent.schema.js';
+export { auditSchema } from './audit.schema.js';
+export { channelSchema } from './channel.schema.js';
+export { credentialSchema } from './credential.schema.js';
+export { deploymentSchema } from './deployment.schema.js';
+export { scopeSchema } from './scope.schema.js';
+export { secretSchema } from './secret.schema.js';
+export { sessionSchema } from './session.schema.js';
+export { virtualUserSchema } from './virtual-user.schema.js';
+export { webhookSchema } from './webhook.schema.js';
+export { workflowSchema } from './workflow.schema.js';
+/**
+ * The schemas a project needs, given the services its code actually reaches.
+ *
+ * `services` is the inspector's `requiredServices` — the same set that drives
+ * service tree-shaking, so a schema is written for exactly the projects whose
+ * functions, middleware or wirings reach the service that owns its tables.
+ *
+ * The gate is one-sided: a schema declaring no `ownedBy` is always in, because
+ * nothing a project writes implies it and leaving it out would be a guess.
+ */
+export const requiredPikkuSchemas = (services) => pikkuSchemas.filter((schema) => !schema.ownedBy || schema.ownedBy.some((name) => services.has(name)));
 /**
  * Bind a declaration to a database.
  *
@@ -237,53 +264,36 @@ 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.
+ * Refuse to start unless one schema's tables are already there.
  *
- * 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.
+ * What a service calls at boot, and it never issues DDL. The runtime is not an
+ * author of the schema: `pikku db generate` writes the declaration down as a
+ * migration and `pikku db migrate` applies it, and those two are the only way
+ * these tables come into existence. A service that finds them missing says so
+ * and stops.
  *
- * 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.
+ * This is the whole point of gating what `db generate` writes. While boot could
+ * still create, a schema that generation left out was created silently at
+ * startup instead — two authorities over one set of tables, which is the
+ * condition all of this exists to end. With creation gone, a schema generation
+ * missed is a sentence at startup naming the command that fixes it.
  *
- * 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.
+ * Half-present is not a distinct case any more. Every missing table is reported
+ * the same way, because the remedy is the same one either way.
  */
-export const ensurePikkuSchema = async (db, schema) => {
+export const requirePikkuSchema = 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;
-    }
+        return;
+    const present = declared.filter((table) => isPresent(existing, table));
+    throw new Error(`The '${schema.name}' schema is not in this database: ${missing.map(displayName).join(', ')} missing` +
+        (present.length > 0
+            ? `, ${present.map(displayName).join(', ')} already there`
+            : '') +
+        '. The runtime does not create these — run `pikku db generate` to write the ' +
+        'migration, then `pikku db migrate` to apply it.');
 };
 /**
  * Render the declaration as SQL for the dialect `db` was built with.

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

@@ -80,6 +80,26 @@ export interface PikkuSchema {
      * database — or, worse, a stub table conjured up to make the error go away.
      */
     requires?: SchemaRequirement[];
+    /**
+     * The singleton services whose `init()` requires these tables, or absent for
+     * a schema every project needs.
+     *
+     * Named as services rather than as wirings because a service is what the
+     * tables actually belong to: one `requirePikkuSchema` call site per service,
+     * and `pikku db generate` writes the schema for a project whose functions
+     * reach any of them. A wiring is a poor proxy — a project can construct
+     * `KyselyWorkflowService` and wire no workflows at all.
+     *
+     * Absent means unconditional. `secrets` is on every project and the session
+     * and deployment stores are reached by generated code rather than by
+     * functions, so nothing a project writes implies them and their absence
+     * cannot be inferred.
+     *
+     * Under-naming is safe now that the runtime creates nothing: a schema left
+     * out of the migration is a sentence at startup, not a table conjured behind
+     * your back. Over-naming costs an unused table. Prefer over-naming.
+     */
+    ownedBy?: string[];
 }
 /**
  * A column another source owns, which one of these schemas depends on.

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

@@ -18,6 +18,7 @@ import { requiredType } from './pikku-schema.types.js';
  */
 export const scopeSchema = {
     name: 'scope',
+    ownedBy: ['scopeService'],
     requires: [{ table: 'user', column: 'id', owner: 'Better Auth' }],
     statements: [
         (db) => db.schema

package/dist/src/schema/virtual-user.schema.js

@@ -17,7 +17,8 @@ import { sql } from 'kysely';
  * week's does not depend on which database they were found in.
  */
 export const virtualUserSchema = {
-    name: 'virtualUser',
+    name: 'virtual-user',
+    ownedBy: ['virtualUserRunStore'],
     statements: [
         (db) => db.schema
             .createTable('virtualUserRun')

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

@@ -2,6 +2,7 @@ import { sql } from 'kysely';
 /** Webhook deliveries and one row per delivery attempt. */
 export const webhookSchema = {
     name: 'webhook',
+    ownedBy: ['webhookService'],
     statements: [
         (db) => db.schema
             .createTable('webhookDelivery')

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

@@ -16,6 +16,7 @@ import { sql } from 'kysely';
  */
 export const workflowSchema = {
     name: 'workflow',
+    ownedBy: ['workflowService', 'workflowRunService'],
     statements: [
         (db) => db.schema
             .createTable('workflowRuns')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/kysely",
-  "version": "0.13.19",
+  "version": "0.13.20",
   "description": "Kysely-backed Pikku services — workflow state, secrets, sessions, scopes and audit",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
@@ -21,7 +21,7 @@
     "prepublishOnly": "yarn build"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.87"
+    "@pikku/core": "^0.12.89"
   },
   "dependencies": {
     "kysely": "^0.29.5"

package/src/index.ts

@@ -32,12 +32,22 @@ export {
   type CreateCoercionPluginOptions,
 } from './coercion-plugin.js'
 export {
+  agentSchema,
   auditSchema,
+  channelSchema,
+  credentialSchema,
+  deploymentSchema,
+  scopeSchema,
+  secretSchema,
+  sessionSchema,
+  virtualUserSchema,
+  webhookSchema,
+  workflowSchema,
   pikkuSchemas,
+  requiredPikkuSchemas,
   applyPikkuSchemas,
   compilePikkuSchemas,
-  ensurePikkuSchema,
-  type EnsureOutcome,
+  requirePikkuSchema,
   resolveRequirements,
   type PikkuSchema,
   type RequiredTypes,

package/src/kysely-agent-run-state-service.ts

@@ -9,7 +9,7 @@ import type {
   SaveScoreInput,
 } from '@pikku/core/services'
 import type { PendingApproval } from '@pikku/core/agent'
-import { ensurePikkuSchema } from './schema/index.js'
+import { requirePikkuSchema } from './schema/index.js'
 import { agentSchema } from './schema/agent.schema.js'
 import { getRunScores, saveRunScore } from './kysely-agent-run-scores.js'
 
@@ -20,7 +20,7 @@ export class KyselyAgentRunStateService implements AgentRunStateService {
 
   async init(): Promise<void> {
     if (this.initialized) return
-    await ensurePikkuSchema(this.db, agentSchema)
+    await requirePikkuSchema(this.db, agentSchema)
     this.initialized = true
   }
 

package/src/kysely-agent-storage-service.ts

@@ -14,7 +14,7 @@ import type { Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
 import { parseJson } from './kysely-json.js'
 import { getRunScores, saveRunScore } from './kysely-agent-run-scores.js'
-import { ensurePikkuSchema } from './schema/index.js'
+import { requirePikkuSchema } from './schema/index.js'
 import { agentSchema } from './schema/agent.schema.js'
 
 export class KyselyAgentStorageService
@@ -26,7 +26,7 @@ export class KyselyAgentStorageService
 
   public async init(): Promise<void> {
     if (this.initialized) return
-    await ensurePikkuSchema(this.db, agentSchema)
+    await requirePikkuSchema(this.db, agentSchema)
     this.initialized = true
   }
 

package/src/kysely-audit-service.test.ts

@@ -309,21 +309,13 @@ describe('KyselyAuditService against a CamelCasePlugin connection', () => {
 })
 
 describe('KyselyAuditService.init', () => {
-  test('creates the audit table on a database that has none', async () => {
+  test('refuses to boot against a database that has none', async () => {
     const fresh = new Kysely<any>({
       dialect: new SqliteDialect({ database: new Database(':memory:') }),
       plugins: [new CamelCasePlugin()],
     })
     const freshService = new KyselyAuditService(fresh)
-    await freshService.init()
-    await freshService.write([
-      event({ eventId: 'e1', type: 't', occurredAt: '2026-01-01' }),
-    ])
-    const { events } = await freshService.query()
-    assert.deepEqual(
-      events.map((e) => e.eventId),
-      ['e1']
-    )
+    await assert.rejects(freshService.init(), /pikku db generate/)
   })
 
   // Two boots against one database, and the second must not wipe the first.

package/src/kysely-audit-service.ts

@@ -6,7 +6,7 @@ import type {
   AuditQueryResult,
 } from '@pikku/core/services'
 import type { Kysely } from 'kysely'
-import { ensurePikkuSchema } from './schema/index.js'
+import { requirePikkuSchema } from './schema/index.js'
 import { auditSchema } from './schema/audit.schema.js'
 
 const jsonOrNull = (v: unknown): string | null =>
@@ -103,7 +103,7 @@ export class KyselyAuditService implements AuditService {
    */
   public async init(): Promise<void> {
     if (this.initialized) return
-    await ensurePikkuSchema(this.db, auditSchema)
+    await requirePikkuSchema(this.db, auditSchema)
     this.initialized = true
   }
 

package/src/kysely-channel-store.ts

@@ -3,7 +3,7 @@ import type { Channel } from '@pikku/core/channel'
 import type { Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
 import { parseJson } from './kysely-json.js'
-import { ensurePikkuSchema } from './schema/index.js'
+import { requirePikkuSchema } from './schema/index.js'
 import { channelSchema } from './schema/channel.schema.js'
 
 export class KyselyChannelStore extends ChannelStore {
@@ -15,7 +15,7 @@ export class KyselyChannelStore extends ChannelStore {
 
   public async init(): Promise<void> {
     if (this.initialized) return
-    await ensurePikkuSchema(this.db, channelSchema)
+    await requirePikkuSchema(this.db, channelSchema)
     this.initialized = true
   }
 

package/src/kysely-credential-service.ts

@@ -8,7 +8,7 @@ import {
 import type { CredentialService } from '@pikku/core/services'
 import type { Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
-import { ensurePikkuSchema } from './schema/index.js'
+import { requirePikkuSchema } from './schema/index.js'
 import { credentialSchema } from './schema/credential.schema.js'
 
 export interface KyselyCredentialServiceConfig {
@@ -42,7 +42,7 @@ export class KyselyCredentialService implements CredentialService {
 
   public async init(): Promise<void> {
     if (this.initialized) return
-    await ensurePikkuSchema(this.db, credentialSchema)
+    await requirePikkuSchema(this.db, credentialSchema)
     this.initialized = true
   }
 

package/src/kysely-deployment-service.ts

@@ -9,7 +9,7 @@ import type { SecretService } from '@pikku/core/services'
 import { getAllFunctionNames } from '@pikku/core/function'
 import type { Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
-import { ensurePikkuSchema } from './schema/index.js'
+import { requirePikkuSchema } from './schema/index.js'
 import { deploymentSchema } from './schema/deployment.schema.js'
 
 export class KyselyDeploymentService implements DeploymentService {
@@ -31,7 +31,7 @@ export class KyselyDeploymentService implements DeploymentService {
 
   public async init(): Promise<void> {
     if (this.initialized) return
-    await ensurePikkuSchema(this.db, deploymentSchema)
+    await requirePikkuSchema(this.db, deploymentSchema)
     this.initialized = true
   }
 

package/src/kysely-scope-service.test.ts

@@ -5,6 +5,7 @@ import Database from 'better-sqlite3'
 import { SerializePlugin } from './serialize-plugin.js'
 import type { KyselyPikkuDB } from './kysely-tables.js'
 import { KyselyScopeService } from './kysely-scope-service.js'
+import { applyPikkuSchemas, scopeSchema } from './schema/index.js'
 
 const SCOPES = [
   { id: 'admin' },
@@ -41,6 +42,7 @@ beforeEach(async () => {
     plugins: [new CamelCasePlugin(), new SerializePlugin()],
   })
   await createUserTable(db)
+  await applyPikkuSchemas(db, [scopeSchema])
   service = new KyselyScopeService(db)
   await service.init()
   await service.syncScopes(SCOPES)

package/src/kysely-scope-service.ts

@@ -8,7 +8,7 @@ import {
 } from '@pikku/core/errors'
 import type { Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
-import { ensurePikkuSchema } from './schema/index.js'
+import { requirePikkuSchema } from './schema/index.js'
 import { scopeSchema } from './schema/scope.schema.js'
 
 /**
@@ -30,7 +30,7 @@ export class KyselyScopeService implements ScopeService {
 
   public async init(): Promise<void> {
     if (this.initialized) return
-    await ensurePikkuSchema(this.db, scopeSchema)
+    await requirePikkuSchema(this.db, scopeSchema)
     this.initialized = true
   }
 

package/src/kysely-secret-service.ts

@@ -10,7 +10,7 @@ import type { SecretService, SecretValues } from '@pikku/core/services'
 import type { SecretValue } from '@pikku/core/classification'
 import type { Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
-import { ensurePikkuSchema } from './schema/index.js'
+import { requirePikkuSchema } from './schema/index.js'
 import { secretSchema } from './schema/secret.schema.js'
 
 export interface KyselySecretServiceConfig {
@@ -44,7 +44,7 @@ export class KyselySecretService implements SecretService {
 
   public async init(): Promise<void> {
     if (this.initialized) return
-    await ensurePikkuSchema(this.db, secretSchema)
+    await requirePikkuSchema(this.db, secretSchema)
     this.initialized = true
   }
 

package/src/kysely-services.test.ts

@@ -18,6 +18,30 @@ import { KyselyAgentRunService } from './kysely-agent-run-service.js'
 import { KyselySecretService } from './kysely-secret-service.js'
 import { KyselyCredentialService } from './kysely-credential-service.js'
 import { KyselySessionStore } from './kysely-session-store.js'
+import {
+  agentSchema,
+  applyPikkuSchemas,
+  channelSchema,
+  credentialSchema,
+  deploymentSchema,
+  secretSchema,
+  sessionSchema,
+  workflowSchema,
+} from './schema/index.js'
+
+/**
+ * Every schema the services under test boot against. They no longer create
+ * their own tables, so the harness stands in for `pikku db migrate`.
+ */
+const SERVICE_SCHEMAS = [
+  channelSchema,
+  workflowSchema,
+  deploymentSchema,
+  agentSchema,
+  secretSchema,
+  credentialSchema,
+  sessionSchema,
+]
 
 function createSqliteDb(): Kysely<KyselyPikkuDB> {
   return new Kysely<KyselyPikkuDB>({
@@ -345,6 +369,7 @@ describe('Kysely Services - SQLite', () => {
 
   before(async () => {
     db = createSqliteDb()
+    await applyPikkuSchemas(db, SERVICE_SCHEMAS)
   })
 
   after(async () => {
@@ -365,6 +390,7 @@ describe(
     before(async () => {
       db = createPostgresDb()!
       await dropAllTables(db)
+      await applyPikkuSchemas(db, SERVICE_SCHEMAS)
     })
 
     after(async () => {

package/src/kysely-session-store.ts

@@ -3,7 +3,7 @@ import type { CoreUserSession } from '@pikku/core/types'
 import type { Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
 import { parseJson } from './kysely-json.js'
-import { ensurePikkuSchema } from './schema/index.js'
+import { requirePikkuSchema } from './schema/index.js'
 import { sessionSchema } from './schema/session.schema.js'
 
 export class KyselySessionStore implements SessionStore {
@@ -13,7 +13,7 @@ export class KyselySessionStore implements SessionStore {
 
   public async init(): Promise<void> {
     if (this.initialized) return
-    await ensurePikkuSchema(this.db, sessionSchema)
+    await requirePikkuSchema(this.db, sessionSchema)
     this.initialized = true
   }
 

package/src/kysely-tables.test.ts

@@ -5,15 +5,7 @@ import { join } from 'node:path'
 import { Kysely, SqliteDialect } from 'kysely'
 import Database from 'better-sqlite3'
 
-import { applyPikkuSchemas, ensurePikkuSchema } from './schema/index.js'
-import { virtualUserSchema } from './schema/virtual-user.schema.js'
-
-/**
- * Opt-in schemas that still have an interface in `KyselyPikkuDB`, so the drift
- * check covers them too. A table being opt-in says when it is created, not
- * whether its type is allowed to disagree with its DDL.
- */
-const OPTIONAL_SCHEMAS = [virtualUserSchema]
+import { applyPikkuSchemas } from './schema/index.js'
 
 /**
  * `KyselyPikkuDB` and the schema declaration describe the same tables, and
@@ -73,9 +65,6 @@ const declaredSchema = async (): Promise<Map<string, Set<string>>> => {
       .addColumn('id', 'text', (col) => col.primaryKey())
       .execute()
     await applyPikkuSchemas(db)
-    for (const schema of OPTIONAL_SCHEMAS) {
-      await ensurePikkuSchema(db, schema)
-    }
 
     const tables = await db.introspection.getTables()
     return new Map(

package/src/kysely-tables.ts

@@ -324,6 +324,34 @@ export interface VirtualUserRunTable {
   finishedAt: Date | string | null
 }
 
+/**
+ * One audit event. Every column is text on every engine so a locally-run
+ * project and a deployed stage write rows the same reader can read; the JSON
+ * columns (`tables`, `changedCols`, `event`, `old`, `data`) are serialised by
+ * {@link KyselyAuditService} rather than by a plugin.
+ */
+export interface AuditTable {
+  auditId: string
+  /** ISO 8601, because string ordering is chronological ordering. */
+  occurredAt: string
+  type: string
+  source: Generated<string>
+  outcome: string | null
+  functionId: string | null
+  wireType: string | null
+  traceId: string | null
+  transactionId: string | null
+  queryId: string | null
+  userId: string | null
+  orgId: string | null
+  pikkuUserId: string | null
+  tables: string | null
+  changedCols: string | null
+  event: string | null
+  old: string | null
+  data: string | null
+}
+
 export interface KyselyPikkuDB {
   pikkuScopes: PikkuScopesTable
   pikkuRoles: PikkuRolesTable
@@ -354,4 +382,5 @@ export interface KyselyPikkuDB {
   webhookDelivery: WebhookDeliveryTable
   webhookDeliveryAttempt: WebhookDeliveryAttemptTable
   virtualUserRun: VirtualUserRunTable
+  audit: AuditTable
 }

package/src/kysely-virtual-user-run-store.test.ts

@@ -6,6 +6,7 @@ import { CamelCasePlugin, Kysely, SqliteDialect } from 'kysely'
 import { KyselyVirtualUserRunStore } from './kysely-virtual-user-run-store.js'
 import { SerializePlugin } from './serialize-plugin.js'
 import type { KyselyPikkuDB } from './kysely-tables.js'
+import { applyPikkuSchemas, virtualUserSchema } from './schema/index.js'
 
 // SerializePlugin is here because most projects in this package run with it, and
 // it is the harder case: it deserialises JSON columns the store has already
@@ -16,6 +17,12 @@ const newDb = () =>
     plugins: [new CamelCasePlugin(), new SerializePlugin()],
   })
 
+const migratedDb = async () => {
+  const db = newDb()
+  await applyPikkuSchemas(db, [virtualUserSchema])
+  return db
+}
+
 const TALLY = {
   steps: 12,
   calls: 30,
@@ -36,15 +43,23 @@ describe('KyselyVirtualUserRunStore', () => {
   let db: Kysely<KyselyPikkuDB>
   let store: KyselyVirtualUserRunStore
 
-  beforeEach(() => {
-    db = newDb()
+  beforeEach(async () => {
+    db = await migratedDb()
     store = new KyselyVirtualUserRunStore(db)
   })
 
-  // The runtime never needs this table, so it arrives with the feature that
-  // fills it rather than in every database — which means the first write has to
-  // create it.
-  test('creates its table on first use', async () => {
+  // The runtime never creates this table, so a project that skipped the
+  // migration has to be told which command writes it rather than quietly
+  // getting one at first use.
+  test('refuses to start against a database that never migrated it', async () => {
+    const store = new KyselyVirtualUserRunStore(newDb())
+    await assert.rejects(
+      store.start({ persona: 'susan', disposition: 'realistic', seed: 42 }),
+      /pikku db generate/
+    )
+  })
+
+  test('writes against a migrated table', async () => {
     const runId = await store.start({
       persona: 'susan',
       disposition: 'realistic',
@@ -184,6 +199,7 @@ describe('KyselyVirtualUserRunStore', () => {
       dialect: new SqliteDialect({ database: new Database(':memory:') }),
       plugins: [new CamelCasePlugin()],
     })
+    await applyPikkuSchemas(bare, [virtualUserSchema])
     const bareStore = new KyselyVirtualUserRunStore(bare)
 
     const runId = await bareStore.start({