@pikku/kysely 0.13.18 → 0.13.20

package/src/schema/index.ts

@@ -7,6 +7,7 @@ import {
   type SchemaRequirement,
 } 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'
@@ -15,6 +16,7 @@ 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 type {
   PikkuSchema,
@@ -32,18 +34,18 @@ export {
 } 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: PikkuSchema[] = [
   channelSchema,
@@ -55,8 +57,40 @@ export const pikkuSchemas: PikkuSchema[] = [
   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: ReadonlySet<string>
+): PikkuSchema[] =>
+  pikkuSchemas.filter(
+    (schema) =>
+      !schema.ownedBy || schema.ownedBy.some((name) => services.has(name))
+  )
+
 /**
  * Bind a declaration to a database.
  *
@@ -287,9 +321,6 @@ export const declaredTables = (
   return tables
 }
 
-/** What `ensurePikkuSchema` found when it looked. */
-export type EnsureOutcome = 'present' | 'created'
-
 /**
  * What `db` already has, indexed both ways.
  *
@@ -337,58 +368,42 @@ const isPresent = (existing: ExistingTables, table: DeclaredTable): boolean =>
     : 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 (
+export const requirePikkuSchema = async (
   db: Kysely<any>,
   schema: PikkuSchema
-): Promise<EnsureOutcome> => {
+): Promise<void> => {
   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.'
-    )
-  }
+  if (missing.length === 0) return
 
-  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
-  }
+  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.'
+  )
 }
 
 /**

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

@@ -101,6 +101,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[]
 }
 
 /**

package/src/schema/schema.test.ts

@@ -14,9 +14,10 @@ import {
 import Database from 'better-sqlite3'
 import {
   pikkuSchemas,
+  requiredPikkuSchemas,
   compilePikkuSchemas,
   applyPikkuSchemas,
-  ensurePikkuSchema,
+  requirePikkuSchema,
   declaredTables,
   unsatisfiedRequirements,
   type PikkuSchema,
@@ -238,17 +239,32 @@ describe('pikku runtime schema — prerequisites', () => {
   })
 })
 
-describe('ensurePikkuSchema — what a service does at boot', () => {
+describe('requirePikkuSchema — what a service does at boot', () => {
   const memoryDb = () =>
     new Kysely<any>({
       dialect: new SqliteDialect({ database: new Database(':memory:') }),
     })
 
-  test('creates the tables the first time and finds them the second', async () => {
+  test('refuses a database the migration never reached, naming the command', async () => {
     const db = memoryDb()
     try {
-      assert.equal(await ensurePikkuSchema(db, workflowSchema), 'created')
-      assert.equal(await ensurePikkuSchema(db, workflowSchema), 'present')
+      await assert.rejects(
+        requirePikkuSchema(db, workflowSchema),
+        /The 'workflow' schema is not in this database.*pikku db generate/s
+      )
+    } finally {
+      await db.destroy()
+    }
+  })
+
+  test('creates nothing on the way to that refusal', async () => {
+    // The whole point: a service that finds its tables missing stops, and the
+    // database it stopped against is exactly as it was.
+    const db = memoryDb()
+    try {
+      await assert.rejects(requirePikkuSchema(db, workflowSchema))
+      const tables = await db.introspection.getTables()
+      assert.deepEqual(tables, [])
     } finally {
       await db.destroy()
     }
@@ -256,21 +272,22 @@ describe('ensurePikkuSchema — what a service does at boot', () => {
 
   test('two services declaring the same schema do not fight over it', async () => {
     // The workflow service and the workflow mirror both own these tables, and
-    // both call init(). Whoever runs second must find them and stop, rather
-    // than issuing DDL the database will reject.
+    // both call init(). Neither creates anything, so both find the migrated
+    // tables and return.
     const db = memoryDb()
     try {
-      assert.equal(await ensurePikkuSchema(db, workflowSchema), 'created')
-      assert.equal(await ensurePikkuSchema(db, workflowSchema), 'present')
+      await applyPikkuSchemas(db, [workflowSchema])
+      await assert.doesNotReject(requirePikkuSchema(db, workflowSchema))
+      await assert.doesNotReject(requirePikkuSchema(db, workflowSchema))
     } finally {
       await db.destroy()
     }
   })
 
-  test('refuses a half-applied schema rather than filling in the rest', async () => {
+  test('a half-applied schema is refused the same way a missing one is', async () => {
     // Something else already owns part of it — a migration, an older release,
-    // a hand-run script. Creating the remainder at boot leaves two authorities
-    // over one set of tables, which is the condition all of this exists to end.
+    // a hand-run script. Half-present is not a distinct case: the remedy is the
+    // same migration either way, so the sentence names both halves and stops.
     const db = memoryDb()
     try {
       await db.schema
@@ -279,8 +296,8 @@ describe('ensurePikkuSchema — what a service does at boot', () => {
         .execute()
 
       await assert.rejects(
-        ensurePikkuSchema(db, workflowSchema),
-        /The 'workflow' schema is half applied/
+        requirePikkuSchema(db, workflowSchema),
+        /workflow_step.*missing.*workflow_runs already there/s
       )
     } finally {
       await db.destroy()
@@ -288,7 +305,7 @@ describe('ensurePikkuSchema — what a service does at boot', () => {
   })
 })
 
-describe('ensurePikkuSchema — a connection bound to a schema', () => {
+describe('requirePikkuSchema — a connection bound to a schema', () => {
   const WORKFLOW_TABLES = [
     'workflow_runs',
     'workflow_step',
@@ -301,7 +318,7 @@ describe('ensurePikkuSchema — a connection bound to a schema', () => {
    *
    * Stubbed rather than run against a real database because sqlite has one
    * schema and nothing else here speaks postgres — and introspection is the
-   * only thing `ensurePikkuSchema` reads before it decides. DummyDriver takes
+   * only thing `requirePikkuSchema` reads before it decides. DummyDriver takes
    * whatever DDL follows.
    */
   const introspecting = (
@@ -352,9 +369,8 @@ describe('ensurePikkuSchema — a connection bound to a schema', () => {
       WORKFLOW_TABLES.map((name) => ({ schema: 'app', name }))
     )
 
-    assert.equal(
-      await ensurePikkuSchema(db.withSchema('app'), workflowSchema),
-      'present'
+    await assert.doesNotReject(
+      requirePikkuSchema(db.withSchema('app'), workflowSchema)
     )
   })
 
@@ -365,9 +381,9 @@ describe('ensurePikkuSchema — a connection bound to a schema', () => {
       WORKFLOW_TABLES.map((name) => ({ schema: 'public', name }))
     )
 
-    assert.equal(
-      await ensurePikkuSchema(db.withSchema('app'), workflowSchema),
-      'created'
+    await assert.rejects(
+      requirePikkuSchema(db.withSchema('app'), workflowSchema),
+      /is not in this database/
     )
   })
 
@@ -376,7 +392,7 @@ describe('ensurePikkuSchema — a connection bound to a schema', () => {
       WORKFLOW_TABLES.map((name) => ({ schema: 'public', name }))
     )
 
-    assert.equal(await ensurePikkuSchema(db, workflowSchema), 'present')
+    await assert.doesNotReject(requirePikkuSchema(db, workflowSchema))
   })
 
   test('matches on the bare name when the engine reports no schemas', async () => {
@@ -387,9 +403,8 @@ describe('ensurePikkuSchema — a connection bound to a schema', () => {
       WORKFLOW_TABLES.map((name) => ({ schema: undefined, name }))
     )
 
-    assert.equal(
-      await ensurePikkuSchema(db.withSchema('main'), workflowSchema),
-      'present'
+    await assert.doesNotReject(
+      requirePikkuSchema(db.withSchema('main'), workflowSchema)
     )
   })
 
@@ -414,7 +429,7 @@ describe('ensurePikkuSchema — a connection bound to a schema', () => {
     })
 
     await assert.rejects(
-      ensurePikkuSchema(db.withSchema('app'), workflowSchema),
+      applyPikkuSchemas(db.withSchema('app'), [workflowSchema]),
       (error: Error) => {
         assert.equal(error, pgError, 'the engine error must pass through as-is')
         return true
@@ -431,7 +446,7 @@ describe('ensurePikkuSchema — a connection bound to a schema', () => {
     })
     try {
       await assert.rejects(
-        ensurePikkuSchema(db.withSchema('main'), workflowSchema),
+        applyPikkuSchemas(db.withSchema('main'), [workflowSchema]),
         (error: Error) => {
           assert.match(error.message, /bound to a schema/)
           assert.match(error.message, /takes a bare table name/i)
@@ -448,7 +463,7 @@ describe('ensurePikkuSchema — a connection bound to a schema', () => {
     const db = introspecting([{ schema: 'app', name: 'workflow_runs' }])
 
     await assert.rejects(
-      ensurePikkuSchema(db.withSchema('app'), workflowSchema),
+      requirePikkuSchema(db.withSchema('app'), workflowSchema),
       /app\.workflow_step.*missing.*app\.workflow_runs already there/s
     )
   })
@@ -532,3 +547,45 @@ describe('compiling into a schema', () => {
     )
   })
 })
+
+describe('requiredPikkuSchemas', () => {
+  test('a project that reaches no service still gets the ungated schemas', () => {
+    const names = requiredPikkuSchemas(new Set()).map((s) => s.name)
+    assert.deepEqual(names, ['session', 'secret', 'deployment'])
+  })
+
+  test('a service brings in its own schema, in the declared order', () => {
+    const names = requiredPikkuSchemas(
+      new Set(['channelStore', 'workflowService'])
+    ).map((s) => s.name)
+    assert.deepEqual(names, [
+      'channel',
+      'session',
+      'secret',
+      'deployment',
+      'workflow',
+    ])
+  })
+
+  test('any one of a schema s owners is enough to ask for it', () => {
+    // A schema several services share is needed as soon as one of them is.
+    assert.ok(
+      requiredPikkuSchemas(new Set(['workflowRunService'])).some(
+        (s) => s.name === 'workflow'
+      )
+    )
+    assert.ok(
+      requiredPikkuSchemas(new Set(['eventHub'])).some(
+        (s) => s.name === 'channel'
+      )
+    )
+  })
+
+  test('naming every owner asks for everything', () => {
+    const owners = pikkuSchemas.flatMap((s) => s.ownedBy ?? [])
+    assert.equal(
+      requiredPikkuSchemas(new Set(owners)).length,
+      pikkuSchemas.length
+    )
+  })
+})

package/src/schema/scope.schema.ts

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

package/src/schema/virtual-user.schema.ts

@@ -19,7 +19,8 @@ import type { PikkuSchema } from './pikku-schema.types.js'
  * week's does not depend on which database they were found in.
  */
 export const virtualUserSchema: PikkuSchema = {
-  name: 'virtualUser',
+  name: 'virtual-user',
+  ownedBy: ['virtualUserRunStore'],
   statements: [
     (db) =>
       db.schema

package/src/schema/webhook.schema.ts

@@ -4,6 +4,7 @@ import type { PikkuSchema } from './pikku-schema.types.js'
 /** Webhook deliveries and one row per delivery attempt. */
 export const webhookSchema: PikkuSchema = {
   name: 'webhook',
+  ownedBy: ['webhookService'],
   statements: [
     (db) =>
       db.schema

package/src/schema/workflow.schema.ts

@@ -18,6 +18,7 @@ import type { PikkuSchema } from './pikku-schema.types.js'
  */
 export const workflowSchema: PikkuSchema = {
   name: 'workflow',
+  ownedBy: ['workflowService', 'workflowRunService'],
   statements: [
     (db) =>
       db.schema