@pikku/kysely 0.13.20 → 0.13.21

package/CHANGELOG.md

@@ -1,3 +1,123 @@
+## 0.13.21
+
+### Patch Changes
+
+- cfd364a: Remove the last `@pikku/core/ecosystem` references and guard against new ones
+
+  `@pikku/kysely`'s workflow-service test still imported `StepState` from
+  `@pikku/core/ecosystem/workflow`, a subpath that no longer exists in
+  `@pikku/core`'s `exports`. Nothing caught it: the import is type-only, so tsx
+  erases it before it can fail at runtime, and the package tsconfig excludes
+  `**/*.test.ts`, so `yarn tsc` never saw it either. It now imports from
+  `@pikku/core/workflow`.
+
+  A new guard test in `@pikku/core` scans the repository for the dead specifier
+  and fails if one comes back, so the next stale import is a red test rather than
+  a silent `any`.
+
+- 05e47cf: feat(virtual-user): keep the transcript a run already produced
+
+  The engine returns `intents` and `steps` on every run — what the user set out
+  to do, and every turn it took getting there — and `VirtualUserRunOutcome` kept
+  neither. The record held counts and findings, so the one question anybody
+  actually asks of a completed run ("what did it _do_?") had no answer anywhere,
+  even though the answer had been computed and thrown away a moment earlier.
+
+  `VirtualUserRunOutcome` now carries both, and `VirtualUserRunStore` gains a
+  `steps(runId, options?)` read. Intents ride on the run record: there are a
+  handful of them and every read of the run wants them. Steps get their own
+  `virtualUserRunStep` table, because a run at a 500-step budget carries more
+  transcript than every other column together and `list()` would pay for it on
+  every row.
+
+  Three things the kysely store had to get right, all of them driver differences
+  rather than design:
+
+  - steps are inserted in chunks of 50, because a bare sqlite driver binds at
+    most 999 variables per statement and ten columns times a 500-step budget is
+    five thousand — an un-chunked insert fails on long runs, which are the
+    interesting ones;
+  - `ok` is stored as 0 or 1, since a bare driver cannot bind a boolean at all
+    and `SerializePlugin` is not installed everywhere;
+  - `response` is stored JSON-encoded, because a truncated API response usually
+    starts with a brace and `SerializePlugin` would otherwise read it back as an
+    object rather than the string the engine saw.
+
+  Completing a run that does not exist no longer writes steps: there is no
+  foreign key to refuse them and nothing would ever read or reap them.
+
+  **This adds a table to the `virtualUser` schema**, and the runtime creates
+  nothing: a database that already has `virtualUserRun` gets the store's own
+  refusal at startup until `pikku db generate` writes the migration and
+  `pikku db migrate` applies it. Landing it now costs nothing, because
+  `scaffold.virtualUser` is not yet switched on anywhere.
+
+- 05e47cf: feat(virtual-user): put each persona on its own clock
+
+  A budget says where one run stops. Nothing said how often a persona should use
+  the application, so in practice each one ran whenever somebody remembered — and
+  what actually tells you about a product is the same user coming back over a
+  fortnight.
+
+  Each persona now gets a row rather than a bigger budget. `virtualUserSchedule`
+  holds `enabled`, the disposition and goals to run with, an interval **range**,
+  and `nextRunAt`. `tickVirtualUserSchedules` acts on whichever rows are due:
+
+  ```ts
+  wireScheduler({
+    name: 'virtualUsers',
+    schedule: '0 * * * *',
+    func: tickVirtualUserSchedules,
+  })
+  ```
+
+  The tick is generated and wired by nobody, deliberately. A scaffolded
+  `wireScheduler` would start spending an application's model budget the moment
+  somebody ran `pikku all`, on a host that may not run schedulers at all. Tick
+  resolution bounds how late a due persona is, never how often it runs.
+
+  Three things it does that are easy to leave out:
+
+  - The next due time is written **before** the run is dispatched, so a tick that
+    dies halfway cannot hand the same persona to the next one. A dispatch that
+    throws waits a full interval instead of retrying every minute for a week.
+    That write is a compare-and-set against the `nextRunAt` the tick read, so it
+    is also how a tick _wins_ the persona: two processes on the same cron see the
+    same due row, and only the one whose claim lands dispatches.
+  - A persona whose previous run is still `running` is skipped, not queued. Two
+    copies of the same user acting at once is a different test, and its findings
+    do not reproduce.
+  - A run still `running` after two hours is failed. Without that, one restart
+    mid-run blocks that persona's schedule permanently — which is where the
+    stranded-record cost of not using a queue finally gets paid.
+
+  Reschedule-on-completion was the other candidate and is worse in exactly one
+  way, fatally: a crash between finishing and scheduling ends the persona forever,
+  and the evidence is an absence.
+
+  New: `VirtualUserScheduleStore` in core (with the tick, `isDue` and `nextRunAt`
+  as pure functions), `KyselyVirtualUserScheduleStore` and its own schema —
+  its own rather than a third table in `virtualUserSchema`, and owned by its own
+  store, so a project that records runs and never wants them unattended carries no
+  cadence table. `scaffold.virtualUser` gains `setVirtualUserSchedule`,
+  `listVirtualUserSchedules` and the tick, behind a new `virtualUser:schedule`
+  scope: starting a run spends money once with a caller watching, while writing a
+  schedule spends it repeatedly with nobody there.
+
+  The console's Virtual Users screen gains a **Run now** button beside a persona's
+  run history, gated on `pikku:console:virtualUsers:run`. It dispatches the
+  project's own `runVirtualUser` rather than starting a run itself, so a run the
+  application would refuse — an acted-upon persona, a non-accountable disposition
+  in production — is still refused.
+
+- Updated dependencies [3c0012c]
+- Updated dependencies [05e47cf]
+- Updated dependencies [cfd364a]
+- Updated dependencies [05e47cf]
+- Updated dependencies [05e47cf]
+- Updated dependencies [05e47cf]
+  - @pikku/core@0.12.90
+
 ## 0.13.20
 
 ### Patch Changes

package/dist/src/index.d.ts

@@ -15,10 +15,11 @@ export { KyselyWebhookService } from './kysely-webhook-service.js';
 export { createAuditedKysely, type CreateAuditedKyselyOptions, } from './create-audited-kysely.js';
 export { KyselyAuditService } from './kysely-audit-service.js';
 export { KyselyVirtualUserRunStore } from './kysely-virtual-user-run-store.js';
+export { KyselyVirtualUserScheduleStore } from './kysely-virtual-user-schedule-store.js';
 export { SerializePlugin, BaseSerializePlugin, type Serializer, type Deserializer, } from './serialize-plugin.js';
 export { createCoercionPlugin, type ColumnKind, type CoercionMap, type CreateCoercionPluginOptions, } from './coercion-plugin.js';
 export { agentSchema, auditSchema, channelSchema, credentialSchema, deploymentSchema, scopeSchema, secretSchema, sessionSchema, virtualUserSchema, webhookSchema, workflowSchema, pikkuSchemas, requiredPikkuSchemas, applyPikkuSchemas, compilePikkuSchemas, requirePikkuSchema, resolveRequirements, type PikkuSchema, type RequiredTypes, type UnmetRequirement, type SchemaStatementFactory, } from './schema/index.js';
 export type { KyselyPikkuDB } from './kysely-tables.js';
 export type { WorkflowRunService } from '@pikku/core/workflow';
 export type { AgentRunService, AgentRunRow } from '@pikku/core/agent';
-export type { VirtualUserRunStore, VirtualUserRunRecord, } from '@pikku/core/virtual-user';
+export type { VirtualUserRunStore, VirtualUserRunRecord, VirtualUserScheduleStore, VirtualUserScheduleRecord, } from '@pikku/core/virtual-user';

package/dist/src/index.js

@@ -15,6 +15,7 @@ export { KyselyWebhookService } from './kysely-webhook-service.js';
 export { createAuditedKysely, } from './create-audited-kysely.js';
 export { KyselyAuditService } from './kysely-audit-service.js';
 export { KyselyVirtualUserRunStore } from './kysely-virtual-user-run-store.js';
+export { KyselyVirtualUserScheduleStore } from './kysely-virtual-user-schedule-store.js';
 export { SerializePlugin, BaseSerializePlugin, } from './serialize-plugin.js';
 export { createCoercionPlugin, } from './coercion-plugin.js';
 export { agentSchema, auditSchema, channelSchema, credentialSchema, deploymentSchema, scopeSchema, secretSchema, sessionSchema, virtualUserSchema, webhookSchema, workflowSchema, pikkuSchemas, requiredPikkuSchemas, applyPikkuSchemas, compilePikkuSchemas, requirePikkuSchema, resolveRequirements, } from './schema/index.js';

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

@@ -277,6 +277,7 @@ export interface VirtualUserRunTable {
     goals: Generated<string>;
     memory: Generated<string>;
     findings: Generated<string>;
+    intents: Generated<string>;
     tally: string | null;
     stoppedBy: string | null;
     error: string | null;
@@ -316,6 +317,49 @@ export interface AuditTable {
     old: string | null;
     data: string | null;
 }
+/**
+ * One turn of a run's transcript.
+ *
+ * Its own table rather than a column on {@link VirtualUserRunTable}: a run at a
+ * 500-step budget carries more transcript than every other column together, and
+ * the run list would pay for it on every row.
+ */
+export interface VirtualUserRunStepTable {
+    runId: string;
+    /** The engine's step number. `stepIndex` because `index` is reserved in mysql. */
+    stepIndex: number;
+    intentId: string | null;
+    /** JSON: the action the engine scheduled, or the `invalid` shape. */
+    action: string;
+    status: number | null;
+    /** 0 or 1: not every driver in this package can bind a boolean. */
+    ok: number | null;
+    /** JSON-encoded, so a brace-leading response is not read back as an object. */
+    response: string | null;
+    /** JSON array, null when the turn produced no finding. */
+    findingKinds: string | null;
+    tokensIn: Generated<number>;
+    tokensOut: Generated<number>;
+}
+/**
+ * One persona's cadence. Nullable timestamps and 0/1 flags for the same driver
+ * reasons as {@link VirtualUserRunTable}.
+ */
+export interface VirtualUserScheduleTable {
+    persona: string;
+    /** 0 or 1: not every driver in this package can bind a boolean. */
+    enabled: Generated<number>;
+    disposition: string;
+    goals: Generated<string>;
+    /** JSON, or null for the engine's own default budget. */
+    budget: string | null;
+    /** BIGINT, so a driver may hand either back. */
+    minIntervalMs: string | number | bigint;
+    maxIntervalMs: string | number | bigint;
+    nextRunAt: Date | string;
+    lastRunId: string | null;
+    lastRunAt: Date | string | null;
+}
 export interface KyselyPikkuDB {
     pikkuScopes: PikkuScopesTable;
     pikkuRoles: PikkuRolesTable;
@@ -346,5 +390,7 @@ export interface KyselyPikkuDB {
     webhookDelivery: WebhookDeliveryTable;
     webhookDeliveryAttempt: WebhookDeliveryAttemptTable;
     virtualUserRun: VirtualUserRunTable;
+    virtualUserRunStep: VirtualUserRunStepTable;
+    virtualUserSchedule: VirtualUserScheduleTable;
     audit: AuditTable;
 }

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

@@ -1,25 +1,7 @@
 import type { Kysely } from 'kysely';
+import type { StepRecord } from '@pikku/core/virtual-user';
 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;
@@ -39,5 +21,11 @@ export declare class KyselyVirtualUserRunStore implements VirtualUserRunStore {
         limit?: number;
         offset?: number;
     }): Promise<VirtualUserRunRecord[]>;
+    steps(runId: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<StepRecord[]>;
+    private writeSteps;
+    private toStep;
     private toRecord;
 }

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

@@ -21,6 +21,15 @@ import { virtualUserSchema } from './schema/virtual-user.schema.js';
  * ids. This is a privileged store; the scaffolded reads are scope-gated, and
  * exposing these rows more widely publishes your own exploits.
  */
+/**
+ * How many step rows go in one insert.
+ *
+ * Not a performance dial. A bare SQLite driver binds at most 999 variables per
+ * statement, and ten columns times a 500-step budget is five thousand — so an
+ * un-chunked insert does not fail on a long run, it fails on the *interesting*
+ * long run, which is the one nobody wants to lose.
+ */
+const STEP_INSERT_CHUNK = 50;
 export class KyselyVirtualUserRunStore {
     db;
     initialized = false;
@@ -61,7 +70,7 @@ export class KyselyVirtualUserRunStore {
     }
     async complete(runId, outcome) {
         await this.init();
-        await this.db
+        const updated = await this.db
             .updateTable('virtualUserRun')
             .set({
             status: 'completed',
@@ -70,11 +79,17 @@ export class KyselyVirtualUserRunStore {
             // 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),
+            intents: JSON.stringify(outcome.intents),
             stoppedBy: outcome.stoppedBy,
             finishedAt: new Date().toISOString(),
         })
             .where('runId', '=', runId)
-            .execute();
+            .executeTakeFirst();
+        // Nothing owns steps written against a run that is not there, and nothing
+        // would ever read or reap them — there is no foreign key to refuse them.
+        if (updated.numUpdatedRows === 0n)
+            return;
+        await this.writeSteps(runId, outcome.steps);
     }
     async fail(runId, error) {
         await this.init();
@@ -110,6 +125,57 @@ export class KyselyVirtualUserRunStore {
             .execute();
         return rows.map((row) => this.toRecord(row));
     }
+    async steps(runId, options) {
+        await this.init();
+        const rows = await this.db
+            .selectFrom('virtualUserRunStep')
+            .selectAll()
+            .where('runId', '=', runId)
+            .orderBy('stepIndex', 'asc')
+            .limit(options?.limit ?? 1000)
+            .offset(options?.offset ?? 0)
+            .execute();
+        return rows.map((row) => this.toStep(row));
+    }
+    async writeSteps(runId, steps) {
+        for (let at = 0; at < steps.length; at += STEP_INSERT_CHUNK) {
+            const chunk = steps.slice(at, at + STEP_INSERT_CHUNK);
+            await this.db
+                .insertInto('virtualUserRunStep')
+                .values(chunk.map((step) => ({
+                runId,
+                stepIndex: step.index,
+                intentId: step.intentId ?? null,
+                action: JSON.stringify(step.action),
+                status: step.status ?? null,
+                ok: step.ok === undefined ? null : step.ok ? 1 : 0,
+                response: step.response === undefined
+                    ? null
+                    : JSON.stringify(step.response),
+                findingKinds: step.findingKinds
+                    ? JSON.stringify(step.findingKinds)
+                    : null,
+                tokensIn: step.tokensIn,
+                tokensOut: step.tokensOut,
+            })))
+                .execute();
+        }
+    }
+    toStep(row) {
+        return {
+            index: Number(row.stepIndex),
+            ...(row.intentId ? { intentId: row.intentId } : {}),
+            action: parseJson(row.action),
+            ...(row.status === null ? {} : { status: Number(row.status) }),
+            ...(row.ok === null ? {} : { ok: Boolean(row.ok) }),
+            ...(row.response === null ? {} : { response: parseJson(row.response) }),
+            ...(row.findingKinds
+                ? { findingKinds: parseJson(row.findingKinds) }
+                : {}),
+            tokensIn: Number(row.tokensIn),
+            tokensOut: Number(row.tokensOut),
+        };
+    }
     toRecord(row) {
         return {
             runId: row.runId,
@@ -120,6 +186,7 @@ export class KyselyVirtualUserRunStore {
             goals: parseJson(row.goals) ?? [],
             memory: parseJson(row.memory) ?? {},
             findings: parseJson(row.findings) ?? [],
+            intents: parseJson(row.intents) ?? [],
             tally: row.tally ? (parseJson(row.tally) ?? null) : null,
             stoppedBy: row.stoppedBy,
             error: row.error,

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

@@ -0,0 +1,33 @@
+import type { Kysely } from 'kysely';
+import type { VirtualUserScheduleInput, VirtualUserScheduleRecord, VirtualUserScheduleStore } from '@pikku/core/virtual-user';
+import type { KyselyPikkuDB } from './kysely-tables.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 declare class KyselyVirtualUserScheduleStore implements VirtualUserScheduleStore {
+    private db;
+    private initialized;
+    constructor(db: Kysely<KyselyPikkuDB>);
+    init(): Promise<void>;
+    set(schedule: VirtualUserScheduleInput): Promise<VirtualUserScheduleRecord>;
+    get(persona: string): Promise<VirtualUserScheduleRecord | null>;
+    list(): Promise<VirtualUserScheduleRecord[]>;
+    due(now: Date): Promise<VirtualUserScheduleRecord[]>;
+    claim(persona: string, claim: {
+        from: Date;
+        nextRunAt: Date;
+        runId: string | null;
+        at: Date;
+    }): Promise<boolean>;
+    remove(persona: string): Promise<void>;
+    private toRecord;
+}

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/schema/index.d.ts

@@ -26,6 +26,7 @@ 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';
 /**

package/dist/src/schema/index.js

@@ -11,6 +11,7 @@ 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';
 /**
  * Every table any part of the pikku runtime can need, in dependency order.
@@ -38,6 +39,7 @@ export const pikkuSchemas = [
     scopeSchema,
     auditSchema,
     virtualUserSchema,
+    virtualUserScheduleSchema,
 ];
 export { agentSchema } from './agent.schema.js';
 export { auditSchema } from './audit.schema.js';
@@ -48,6 +50,7 @@ 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';
 /**

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']),
+    ],
+};

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

@@ -1,6 +1,7 @@
 import type { PikkuSchema } from './pikku-schema.types.js';
 /**
- * The `virtualUserRun` table {@link KyselyVirtualUserRunStore} writes to.
+ * The `virtualUserRun` and `virtualUserRunStep` tables
+ * {@link KyselyVirtualUserRunStore} writes to.
  *
  * Deliberately not in `pikkuSchemas`: the runtime never needs this table, only
  * a project that runs virtual users does, and creating it for everyone would