@pikku/kysely 0.13.19 → 0.13.21

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

@@ -0,0 +1,151 @@
+import { DEFAULT_MAX_INTERVAL_MS, DEFAULT_MIN_INTERVAL_MS, } from '@pikku/core/virtual-user';
+import { parseJson } from './kysely-json.js';
+import { requirePikkuSchema } from './schema/index.js';
+import { virtualUserScheduleSchema } from './schema/virtual-user-schedule.schema.js';
+/**
+ * Keeps each persona's cadence in a `virtualUserSchedule` table.
+ *
+ * Wiring this is what turns virtual users from something a person triggers into
+ * something that happens: without it, {@link KyselyVirtualUserRunStore} still
+ * records every run, and every run still had someone behind it. Two services
+ * rather than one so that an app can want the history without wanting the bill.
+ *
+ * Reads and writes the same way the run store does — JSON as text, timestamps
+ * as ISO strings, flags as 0/1 — so a project on SQLite and one on Postgres
+ * hold the same bytes and `SerializePlugin` is optional on both.
+ */
+export class KyselyVirtualUserScheduleStore {
+    db;
+    initialized = false;
+    constructor(db) {
+        this.db = db;
+    }
+    async init() {
+        if (this.initialized)
+            return;
+        await requirePikkuSchema(this.db, virtualUserScheduleSchema);
+        this.initialized = true;
+    }
+    async set(schedule) {
+        await this.init();
+        // Read-then-write rather than a partial upsert: a schedule is configuration
+        // written by a person, and the alternative is two dialects of "leave the
+        // columns I did not mention alone".
+        const existing = await this.get(schedule.persona);
+        const merged = {
+            persona: schedule.persona,
+            enabled: schedule.enabled ?? existing?.enabled ?? false,
+            disposition: schedule.disposition ?? existing?.disposition ?? 'realistic',
+            goals: [...(schedule.goals ?? existing?.goals ?? [])],
+            budget: schedule.budget === undefined
+                ? (existing?.budget ?? null)
+                : schedule.budget,
+            minIntervalMs: schedule.minIntervalMs ??
+                existing?.minIntervalMs ??
+                DEFAULT_MIN_INTERVAL_MS,
+            maxIntervalMs: schedule.maxIntervalMs ??
+                existing?.maxIntervalMs ??
+                DEFAULT_MAX_INTERVAL_MS,
+            // A new schedule is due immediately. Enabling one is a deliberate act, and
+            // waiting a random half-day to find out whether it works is not a feature.
+            nextRunAt: schedule.nextRunAt ?? existing?.nextRunAt ?? new Date(),
+            lastRunId: existing?.lastRunId ?? null,
+            lastRunAt: existing?.lastRunAt ?? null,
+        };
+        const values = {
+            persona: merged.persona,
+            enabled: merged.enabled ? 1 : 0,
+            disposition: merged.disposition,
+            goals: JSON.stringify(merged.goals),
+            budget: merged.budget ? JSON.stringify(merged.budget) : null,
+            minIntervalMs: String(merged.minIntervalMs),
+            maxIntervalMs: String(merged.maxIntervalMs),
+            nextRunAt: merged.nextRunAt.toISOString(),
+        };
+        await this.db
+            .insertInto('virtualUserSchedule')
+            .values(values)
+            .onConflict((oc) => oc.column('persona').doUpdateSet({
+            enabled: values.enabled,
+            disposition: values.disposition,
+            goals: values.goals,
+            budget: values.budget,
+            minIntervalMs: values.minIntervalMs,
+            maxIntervalMs: values.maxIntervalMs,
+            nextRunAt: values.nextRunAt,
+        }))
+            .execute();
+        return merged;
+    }
+    async get(persona) {
+        await this.init();
+        const row = await this.db
+            .selectFrom('virtualUserSchedule')
+            .selectAll()
+            .where('persona', '=', persona)
+            .executeTakeFirst();
+        return row ? this.toRecord(row) : null;
+    }
+    async list() {
+        await this.init();
+        const rows = await this.db
+            .selectFrom('virtualUserSchedule')
+            .selectAll()
+            .orderBy('persona', 'asc')
+            .execute();
+        return rows.map((row) => this.toRecord(row));
+    }
+    async due(now) {
+        await this.init();
+        const rows = await this.db
+            .selectFrom('virtualUserSchedule')
+            .selectAll()
+            .where('enabled', '=', 1)
+            .where('nextRunAt', '<=', now.toISOString())
+            .orderBy('nextRunAt', 'asc')
+            .execute();
+        return rows.map((row) => this.toRecord(row));
+    }
+    async claim(persona, claim) {
+        await this.init();
+        const result = await this.db
+            .updateTable('virtualUserSchedule')
+            .set({
+            nextRunAt: claim.nextRunAt.toISOString(),
+            // A claim with no run id is the one written before dispatch, and must
+            // not blank out which run this persona last managed to start.
+            ...(claim.runId
+                ? { lastRunId: claim.runId, lastRunAt: claim.at.toISOString() }
+                : {}),
+        })
+            .where('persona', '=', persona)
+            // The compare-and-set: whoever writes first moves `nextRunAt`, and every
+            // other tick holding the value they read matches nothing.
+            .where('nextRunAt', '=', claim.from.toISOString())
+            .executeTakeFirst();
+        return Number(result.numUpdatedRows ?? 0) > 0;
+    }
+    async remove(persona) {
+        await this.init();
+        await this.db
+            .deleteFrom('virtualUserSchedule')
+            .where('persona', '=', persona)
+            .execute();
+    }
+    toRecord(row) {
+        return {
+            persona: row.persona,
+            enabled: Boolean(row.enabled),
+            disposition: row.disposition,
+            goals: parseJson(row.goals) ?? [],
+            budget: row.budget
+                ? (parseJson(row.budget) ?? null)
+                : null,
+            minIntervalMs: Number(row.minIntervalMs),
+            maxIntervalMs: Number(row.maxIntervalMs),
+            nextRunAt: new Date(row.nextRunAt),
+            lastRunId: row.lastRunId,
+            lastRunAt: row.lastRunAt ? new Date(row.lastRunAt) : null,
+        };
+    }
+}

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

@@ -1,6 +1,6 @@
 import { QueueWebhookService } from '@pikku/core/services';
 import { PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, } from '@pikku/core/services';
-import { ensurePikkuSchema } from './schema/index.js';
+import { requirePikkuSchema } from './schema/index.js';
 import { webhookSchema } from './schema/webhook.schema.js';
 /**
  * Durable {@link QueueWebhookService}: still delivers through the
@@ -19,7 +19,7 @@ export class KyselyWebhookService extends QueueWebhookService {
     async init() {
         if (this.initialized)
             return;
-        await ensurePikkuSchema(this.db, webhookSchema);
+        await requirePikkuSchema(this.db, webhookSchema);
         this.initialized = true;
     }
     async send(input) {

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

@@ -22,7 +22,7 @@ export declare class KyselyWorkflowMirror implements WorkflowRunMirror {
      * Create the underlying tables if none of them exist yet.
      *
      * Safe to call from either the mirror or `KyselyWorkflowService.init()` —
-     * both apply the same `workflowSchema`, and `ensurePikkuSchema` is a no-op
+     * both apply the same `workflowSchema`, and `requirePikkuSchema` is a no-op
      * once the tables are there. A database holding only *part* of the schema
      * throws rather than filling in the rest: something else owns those tables,
      * and boot is not where that gets reconciled.

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

@@ -1,4 +1,4 @@
-import { ensurePikkuSchema } from './schema/index.js';
+import { requirePikkuSchema } from './schema/index.js';
 import { workflowSchema } from './schema/workflow.schema.js';
 /**
  * Kysely-backed `WorkflowRunMirror`.
@@ -22,7 +22,7 @@ export class KyselyWorkflowMirror {
      * Create the underlying tables if none of them exist yet.
      *
      * Safe to call from either the mirror or `KyselyWorkflowService.init()` —
-     * both apply the same `workflowSchema`, and `ensurePikkuSchema` is a no-op
+     * both apply the same `workflowSchema`, and `requirePikkuSchema` is a no-op
      * once the tables are there. A database holding only *part* of the schema
      * throws rather than filling in the rest: something else owns those tables,
      * and boot is not where that gets reconciled.
@@ -30,7 +30,7 @@ export class KyselyWorkflowMirror {
     async init() {
         if (this.initialized)
             return;
-        await ensurePikkuSchema(this.db, workflowSchema);
+        await requirePikkuSchema(this.db, workflowSchema);
         this.initialized = true;
     }
     async createRun(runId, workflowName, input, inline, graphHash, wire, options) {

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

@@ -2,7 +2,7 @@ import { PikkuWorkflowService, WorkflowStepFunctionMismatchError, } from '@pikku
 import { sql } from 'kysely';
 import { KyselyWorkflowRunService } from './kysely-workflow-run-service.js';
 import { parseJson } from './kysely-json.js';
-import { ensurePikkuSchema } from './schema/index.js';
+import { requirePikkuSchema } from './schema/index.js';
 import { workflowSchema } from './schema/workflow.schema.js';
 export class KyselyWorkflowService extends PikkuWorkflowService {
     db;
@@ -16,7 +16,7 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
     async init() {
         if (this.initialized)
             return;
-        await ensurePikkuSchema(this.db, workflowSchema);
+        await requirePikkuSchema(this.db, workflowSchema);
         this.initialized = true;
     }
     async createRunImpl(workflowName, input, inline, graphHash, wire, options) {

package/dist/src/schema/agent.schema.js

@@ -11,6 +11,7 @@ import { sql } from 'kysely';
  */
 export const agentSchema = {
     name: 'agent',
+    ownedBy: ['agentStorage', 'agentRunState', 'agentRunService'],
     statements: [
         (db) => db.schema
             .createTable('agentThreads')

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

@@ -2,10 +2,11 @@ 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.
+ * Gated by `ownedBy` rather than written for everyone: only a project that has
+ * wired a durable audit sink needs this table, and generating it for the rest
+ * would put an empty table in every database. `KyselyAuditService.init()`
+ * requires it and never creates it, so it arrives with the migration `pikku db
+ * generate` writes for the sink that fills it.
  *
  * 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

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

@@ -1,10 +1,11 @@
 /**
  * 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.
+ * Gated by `ownedBy` rather than written for everyone: only a project that has
+ * wired a durable audit sink needs this table, and generating it for the rest
+ * would put an empty table in every database. `KyselyAuditService.init()`
+ * requires it and never creates it, so it arrives with the migration `pikku db
+ * generate` writes for the sink that fills it.
  *
  * 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
@@ -14,6 +15,7 @@
  */
 export const auditSchema = {
     name: 'audit',
+    ownedBy: ['audit', 'auditLog'],
     statements: [
         (db) => db.schema
             .createTable('audit')

package/dist/src/schema/channel.schema.js

@@ -2,6 +2,7 @@ import { sql } from 'kysely';
 /** Channels and their topic subscriptions, also read by the event-hub store. */
 export const channelSchema = {
     name: 'channel',
+    ownedBy: ['channelStore', 'eventHub'],
     statements: [
         (db) => db.schema
             .createTable('channels')

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

@@ -12,6 +12,7 @@ import { rawStatement } from './pikku-schema.types.js';
  */
 export const credentialSchema = {
     name: 'credential',
+    ownedBy: ['credentialService'],
     statements: [
         (db) => db.schema
             .createTable('credentials')

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

@@ -3,19 +3,43 @@ import { type PikkuSchema, type RequiredTypes, type SchemaRequirement } from './
 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.
+ * 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 declare const pikkuSchemas: PikkuSchema[];
+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 { virtualUserScheduleSchema } from './virtual-user-schedule.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 declare const requiredPikkuSchemas: (services: ReadonlySet<string>) => PikkuSchema[];
 export interface UnmetRequirement {
     schema: PikkuSchema;
     requirement: SchemaRequirement;
@@ -74,27 +98,25 @@ export interface DeclaredTable {
  * schema the DDL will actually target — the same binding the lookup has to use.
  */
 export declare const declaredTables: (schema: PikkuSchema, db: Kysely<any>) => DeclaredTable[];
-/** What `ensurePikkuSchema` found when it looked. */
-export type EnsureOutcome = 'present' | 'created';
 /**
- * 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.
+ * Refuse to start unless one schema's tables are already there.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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 declare const ensurePikkuSchema: (db: Kysely<any>, schema: PikkuSchema) => Promise<EnsureOutcome>;
+export declare const requirePikkuSchema: (db: Kysely<any>, schema: PikkuSchema) => Promise<void>;
 /**
  * Render the declaration as SQL for the dialect `db` was built with.
  *

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,22 @@ 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';
+import { virtualUserScheduleSchema } from './virtual-user-schedule.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 +37,33 @@ export const pikkuSchemas = [
     workflowSchema,
     agentSchema,
     scopeSchema,
+    auditSchema,
+    virtualUserSchema,
+    virtualUserScheduleSchema,
 ];
+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 { virtualUserScheduleSchema } from './virtual-user-schedule.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 +267,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-schedule.schema.d.ts

@@ -0,0 +1,15 @@
+import type { PikkuSchema } from './pikku-schema.types.js';
+/**
+ * The `virtualUserSchedule` table {@link KyselyVirtualUserScheduleStore} writes
+ * to: one row per persona that keeps using the app on its own.
+ *
+ * Its own schema rather than a third table in {@link virtualUserSchema}, and
+ * owned by its own store: recording what a persona did and deciding that it
+ * keeps going on its own are separate opt-ins, and a project that only wants
+ * the first should not be handed a cadence table it never writes to.
+ *
+ * `persona` is the primary key: a persona has one cadence, and a second row for
+ * the same one would mean two copies of the same user acting at once — not a
+ * heavier test, a different and unreproducible one.
+ */
+export declare const virtualUserScheduleSchema: PikkuSchema;

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

@@ -0,0 +1,43 @@
+/**
+ * The `virtualUserSchedule` table {@link KyselyVirtualUserScheduleStore} writes
+ * to: one row per persona that keeps using the app on its own.
+ *
+ * Its own schema rather than a third table in {@link virtualUserSchema}, and
+ * owned by its own store: recording what a persona did and deciding that it
+ * keeps going on its own are separate opt-ins, and a project that only wants
+ * the first should not be handed a cadence table it never writes to.
+ *
+ * `persona` is the primary key: a persona has one cadence, and a second row for
+ * the same one would mean two copies of the same user acting at once — not a
+ * heavier test, a different and unreproducible one.
+ */
+export const virtualUserScheduleSchema = {
+    name: 'virtual-user-schedule',
+    ownedBy: ['virtualUserScheduleStore'],
+    statements: [
+        (db) => db.schema
+            .createTable('virtualUserSchedule')
+            .addColumn('persona', 'varchar(255)', (col) => col.primaryKey())
+            // 0 or 1 rather than a boolean, matching the run tables: a bare sqlite
+            // driver cannot bind one, and `SerializePlugin` is not installed
+            // everywhere. Off by default, so creating the table spends nothing.
+            .addColumn('enabled', 'integer', (col) => col.defaultTo(0).notNull())
+            .addColumn('disposition', 'varchar(50)', (col) => col.notNull())
+            .addColumn('goals', 'text', (col) => col.defaultTo('[]').notNull())
+            .addColumn('budget', 'text')
+            // The gap to the next run is drawn between these rather than fixed, so
+            // the persona does not keep an appointment.
+            .addColumn('minIntervalMs', 'bigint', (col) => col.notNull())
+            .addColumn('maxIntervalMs', 'bigint', (col) => col.notNull())
+            // The entire schedule. Written before a run is dispatched, so a tick
+            // that dies halfway cannot leave the row due for the next one.
+            .addColumn('nextRunAt', 'timestamp', (col) => col.notNull())
+            .addColumn('lastRunId', 'varchar(36)')
+            .addColumn('lastRunAt', 'timestamp'),
+        // The only read that matters at speed: which rows are due, on every tick.
+        (db) => db.schema
+            .createIndex('idx_virtual_user_schedule_due')
+            .on('virtualUserSchedule')
+            .columns(['enabled', 'nextRunAt']),
+    ],
+};