@pikku/kysely 0.13.19 → 0.13.21

package/CHANGELOG.md

@@ -1,3 +1,177 @@
+## 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
+
+- 274cab3: The singleton intersection moves to the leaves that name it, the runtime stops
+  creating schema, and `db generate` writes only the runtime tables a project's
+  services own
+
+  `WiredSingletonServices` was exported from the generated function leaf so the
+  auth leaf could import it. Nothing outside a generated leaf ever names it —
+  emit declarations for a project of any size and it appears in none of them —
+  so the auth and middleware leaves derive the intersection themselves and the
+  function leaf keeps it private. `WiredServices` stays exported: 147 `.d.ts`
+  files name it, and unexporting it asks every wired module to name each member
+  service through a specifier it does not have.
+
+  `ensurePikkuSchema` is gone. `requirePikkuSchema` replaces it: a service calls
+  it at boot, it looks, and it issues no DDL at all. `pikku db generate` writes
+  the declaration down as a migration and `pikku db migrate` applies it, and
+  those two are now the only way pikku's runtime tables come into existence. A
+  service that finds them missing says so and stops, naming both commands.
+  Half-present is no longer a distinct case — the remedy is the same migration
+  either way. `audit` and `virtual-user` join `pikkuSchemas` as a consequence:
+  boot was the only thing that had ever created them.
+
+  `pikku db generate` applied all of `pikkuSchemas`, so a project with no agents,
+  no channels and no workflows still had `agent_threads`, `channels` and
+  `workflow_runs` written into its migrations, and then carried them forever. A
+  schema now names the services that own it, and generation gates on
+  `requiredServices` — the set the inspector already builds for service
+  tree-shaking. The gate is one-sided: a schema that names no owner is always
+  written, because the session and secret stores and the deployment record are
+  reached by the runtime itself and nothing in a project's source implies them.
+  Declared scopes now imply `scopeService`, which nothing destructures because
+  the generated auth layer is what reaches it.
+
+  Drift keeps asking the unscoped question. A table already in a database has to
+  stay recognisable as a runtime table after the service that needed it is
+  dropped — scoping it there would report those tables as unexplained.
+
+  Every project in this repo that had been relying on boot-time creation now says
+  where its tables come from. `createConfig` moves into its own `config.ts` in the
+  templates — `pikku db` looks for it there — and the three postgres templates plus
+  the workflow verifier declare `postgresUrl` and run `pikku db generate && pikku
+db migrate` before the server starts, from the single connection string their
+  runtime opens. The e2e harness cannot: its databases are in-memory sqlite built
+  inside the services factory, so nothing outside the process can migrate them. It
+  applies the schemas it owns with `applyPikkuSchemas` instead — the same DDL, run
+  by the one process that has the database.
+
+- Updated dependencies [32616af]
+- Updated dependencies [6848cd9]
+  - @pikku/core@0.12.89
+
 ## 0.13.19
 
 ### 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 { auditSchema, pikkuSchemas, applyPikkuSchemas, compilePikkuSchemas, ensurePikkuSchema, type EnsureOutcome, resolveRequirements, type PikkuSchema, type RequiredTypes, type UnmetRequirement, type SchemaStatementFactory, } from './schema/index.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 { auditSchema, pikkuSchemas, applyPikkuSchemas, compilePikkuSchemas, ensurePikkuSchema, resolveRequirements, } from './schema/index.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-agent-run-state-service.js

@@ -1,5 +1,5 @@
 import { sql } from 'kysely';
-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';
 export class KyselyAgentRunStateService {
@@ -11,7 +11,7 @@ export class KyselyAgentRunStateService {
     async init() {
         if (this.initialized)
             return;
-        await ensurePikkuSchema(this.db, agentSchema);
+        await requirePikkuSchema(this.db, agentSchema);
         this.initialized = true;
     }
     async createRun(run) {

package/dist/src/kysely-agent-storage-service.js

@@ -1,6 +1,6 @@
 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 {
     db;
@@ -11,7 +11,7 @@ export class KyselyAgentStorageService {
     async init() {
         if (this.initialized)
             return;
-        await ensurePikkuSchema(this.db, agentSchema);
+        await requirePikkuSchema(this.db, agentSchema);
         this.initialized = true;
     }
     async createThread(resourceId, options) {

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

@@ -1,4 +1,4 @@
-import { ensurePikkuSchema } from './schema/index.js';
+import { requirePikkuSchema } from './schema/index.js';
 import { auditSchema } from './schema/audit.schema.js';
 const jsonOrNull = (v) => v != null ? JSON.stringify(v) : null;
 const parseJson = (v) => {
@@ -90,7 +90,7 @@ export class KyselyAuditService {
     async init() {
         if (this.initialized)
             return;
-        await ensurePikkuSchema(this.db, auditSchema);
+        await requirePikkuSchema(this.db, auditSchema);
         this.initialized = true;
     }
     async audit(event) {

package/dist/src/kysely-channel-store.js

@@ -1,6 +1,6 @@
 import { ChannelStore } from '@pikku/core/channel';
 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 {
     db;
@@ -12,7 +12,7 @@ export class KyselyChannelStore extends ChannelStore {
     async init() {
         if (this.initialized)
             return;
-        await ensurePikkuSchema(this.db, channelSchema);
+        await requirePikkuSchema(this.db, channelSchema);
         this.initialized = true;
     }
     async addChannel({ channelId, channelName, openingData, }) {

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

@@ -1,5 +1,5 @@
 import { deriveKEK, envelopeDecrypt, envelopeEncrypt, envelopeRewrap, generateKEKSalt, } from '@pikku/core/crypto-utils';
-import { ensurePikkuSchema } from './schema/index.js';
+import { requirePikkuSchema } from './schema/index.js';
 import { credentialSchema } from './schema/credential.schema.js';
 export class KyselyCredentialService {
     db;
@@ -22,7 +22,7 @@ export class KyselyCredentialService {
     async init() {
         if (this.initialized)
             return;
-        await ensurePikkuSchema(this.db, credentialSchema);
+        await requirePikkuSchema(this.db, credentialSchema);
         this.initialized = true;
     }
     async logAudit(name, userId, action) {

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

@@ -1,6 +1,6 @@
 import { buildRemoteHeaders } from '@pikku/core/remote';
 import { getAllFunctionNames } from '@pikku/core/function';
-import { ensurePikkuSchema } from './schema/index.js';
+import { requirePikkuSchema } from './schema/index.js';
 import { deploymentSchema } from './schema/deployment.schema.js';
 export class KyselyDeploymentService {
     db;
@@ -21,7 +21,7 @@ export class KyselyDeploymentService {
     async init() {
         if (this.initialized)
             return;
-        await ensurePikkuSchema(this.db, deploymentSchema);
+        await requirePikkuSchema(this.db, deploymentSchema);
         this.initialized = true;
     }
     async start(config) {

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

@@ -1,5 +1,5 @@
 import { SystemRoleImmutableError, SystemRoleShadowedError, } from '@pikku/core/errors';
-import { ensurePikkuSchema } from './schema/index.js';
+import { requirePikkuSchema } from './schema/index.js';
 import { scopeSchema } from './schema/scope.schema.js';
 /**
  * Resolves and administers user scopes against four self-created tables.
@@ -22,7 +22,7 @@ export class KyselyScopeService {
     async init() {
         if (this.initialized)
             return;
-        await ensurePikkuSchema(this.db, scopeSchema);
+        await requirePikkuSchema(this.db, scopeSchema);
         this.initialized = true;
     }
     /**

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

@@ -1,6 +1,6 @@
 import { deriveKEK, envelopeDecrypt, envelopeEncrypt, envelopeRewrap, generateKEKSalt, } from '@pikku/core/crypto-utils';
 import { createSecretValue, isSecretValue } from '@pikku/core/classification';
-import { ensurePikkuSchema } from './schema/index.js';
+import { requirePikkuSchema } from './schema/index.js';
 import { secretSchema } from './schema/secret.schema.js';
 export class KyselySecretService {
     db;
@@ -23,7 +23,7 @@ export class KyselySecretService {
     async init() {
         if (this.initialized)
             return;
-        await ensurePikkuSchema(this.db, secretSchema);
+        await requirePikkuSchema(this.db, secretSchema);
         this.initialized = true;
     }
     async logAudit(secretKey, action) {

package/dist/src/kysely-session-store.js

@@ -1,5 +1,5 @@
 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 {
     db;
@@ -10,7 +10,7 @@ export class KyselySessionStore {
     async init() {
         if (this.initialized)
             return;
-        await ensurePikkuSchema(this.db, sessionSchema);
+        await requirePikkuSchema(this.db, sessionSchema);
         this.initialized = true;
     }
     async get(pikkuUserId) {

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;
@@ -289,6 +290,76 @@ export interface VirtualUserRunTable {
     createdAt: Generated<Date | string>;
     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;
+}
+/**
+ * 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;
@@ -319,4 +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

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { parseJson } from './kysely-json.js';
-import { ensurePikkuSchema } from './schema/index.js';
+import { requirePikkuSchema } from './schema/index.js';
 import { virtualUserSchema } from './schema/virtual-user.schema.js';
 /**
  * Records virtual-user runs in a `virtualUserRun` table.
@@ -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;
@@ -35,7 +44,7 @@ export class KyselyVirtualUserRunStore {
     async init() {
         if (this.initialized)
             return;
-        await ensurePikkuSchema(this.db, virtualUserSchema);
+        await requirePikkuSchema(this.db, virtualUserSchema);
         this.initialized = true;
     }
     async start(run) {
@@ -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;
+}