@pikku/kysely 0.13.7 → 0.13.11

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

@@ -0,0 +1,131 @@
+import { randomUUID } from 'node:crypto';
+import { parseJson } from './kysely-json.js';
+import { ensurePikkuSchema } from './schema/index.js';
+import { virtualUserSchema } from './schema/virtual-user.schema.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 class KyselyVirtualUserRunStore {
+    db;
+    initialized = false;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Creates the table on first use, like the audit sink — the runtime does not
+     * need it, so it arrives with the feature that fills it rather than in every
+     * database.
+     */
+    async init() {
+        if (this.initialized)
+            return;
+        await ensurePikkuSchema(this.db, virtualUserSchema);
+        this.initialized = true;
+    }
+    async start(run) {
+        await this.init();
+        const runId = randomUUID();
+        await this.db
+            .insertInto('virtualUserRun')
+            .values({
+            runId,
+            persona: run.persona,
+            disposition: run.disposition,
+            // Text on every engine (see the schema), so the seed round-trips
+            // through drivers that hand a BIGINT back as a string.
+            seed: String(run.seed),
+            status: 'running',
+            goals: JSON.stringify(run.goals ?? []),
+            memory: JSON.stringify(run.memory ?? {}),
+            findings: '[]',
+            startedBy: run.startedBy ?? null,
+        })
+            .execute();
+        return runId;
+    }
+    async complete(runId, outcome) {
+        await this.init();
+        await this.db
+            .updateTable('virtualUserRun')
+            .set({
+            status: 'completed',
+            findings: JSON.stringify(outcome.findings),
+            tally: JSON.stringify(outcome.tally),
+            // 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),
+            stoppedBy: outcome.stoppedBy,
+            finishedAt: new Date().toISOString(),
+        })
+            .where('runId', '=', runId)
+            .execute();
+    }
+    async fail(runId, error) {
+        await this.init();
+        await this.db
+            .updateTable('virtualUserRun')
+            .set({
+            status: 'failed',
+            error,
+            finishedAt: new Date().toISOString(),
+        })
+            .where('runId', '=', runId)
+            .execute();
+    }
+    async get(runId) {
+        await this.init();
+        const row = await this.db
+            .selectFrom('virtualUserRun')
+            .selectAll()
+            .where('runId', '=', runId)
+            .executeTakeFirst();
+        return row ? this.toRecord(row) : null;
+    }
+    async list(options) {
+        await this.init();
+        let query = this.db.selectFrom('virtualUserRun').selectAll();
+        if (options?.persona) {
+            query = query.where('persona', '=', options.persona);
+        }
+        const rows = await query
+            .orderBy('createdAt', 'desc')
+            .limit(options?.limit ?? 50)
+            .offset(options?.offset ?? 0)
+            .execute();
+        return rows.map((row) => this.toRecord(row));
+    }
+    toRecord(row) {
+        return {
+            runId: row.runId,
+            persona: row.persona,
+            disposition: row.disposition,
+            seed: Number(row.seed),
+            status: row.status,
+            goals: parseJson(row.goals) ?? [],
+            memory: parseJson(row.memory) ?? {},
+            findings: parseJson(row.findings) ?? [],
+            tally: row.tally ? (parseJson(row.tally) ?? null) : null,
+            stoppedBy: row.stoppedBy,
+            error: row.error,
+            startedBy: row.startedBy,
+            createdAt: new Date(row.createdAt),
+            finishedAt: row.finishedAt ? new Date(row.finishedAt) : null,
+        };
+    }
+}

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

@@ -79,6 +79,7 @@ export declare class KyselyWorkflowService extends PikkuWorkflowService {
      */
     private jsonPathFor;
     protected updateRunStateImpl(runId: string, name: string, value: unknown): Promise<void>;
+    protected findStalledRunIds(before: Date, limit: number): Promise<string[]>;
     getRunState(runId: string): Promise<Record<string, unknown>>;
     protected upsertWorkflowVersionImpl(name: string, graphHash: string, graph: any, source: string, status?: WorkflowVersionStatus): Promise<void>;
     protected updateWorkflowVersionStatusImpl(name: string, graphHash: string, status: WorkflowVersionStatus): Promise<void>;

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

@@ -464,6 +464,28 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
             .where('workflowRunId', '=', runId)
             .execute();
     }
+    async findStalledRunIds(before, limit) {
+        const rows = await this.db
+            .selectFrom('workflowRuns as r')
+            .select('r.workflowRunId')
+            .where('r.status', '=', 'running')
+            .where(({ not, exists, selectFrom }) => not(exists(selectFrom('workflowStep as s')
+            .select('s.workflowStepId')
+            .whereRef('s.workflowRunId', '=', 'r.workflowRunId')
+            .where('s.status', 'in', ['running', 'scheduled', 'suspended']))))
+            // The run row only moves on a status change, so idleness has to hold for
+            // the steps too — expressed as "no step touched since `before`" rather
+            // than max(updated_at) so it stays one index-friendly NOT EXISTS.
+            .where('r.updatedAt', '<', before)
+            .where(({ not, exists, selectFrom }) => not(exists(selectFrom('workflowStep as s')
+            .select('s.workflowStepId')
+            .whereRef('s.workflowRunId', '=', 'r.workflowRunId')
+            .where('s.updatedAt', '>=', before))))
+            .orderBy('r.updatedAt', 'asc')
+            .limit(limit)
+            .execute();
+        return rows.map((row) => row.workflowRunId);
+    }
     async getRunState(runId) {
         const row = await this.db
             .selectFrom('workflowRuns')

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

@@ -0,0 +1,16 @@
+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.
+ *
+ * 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
+ * the same reader can read. `occurredAt` is an ISO 8601 string rather than a
+ * timestamp for that reason: string ordering is chronological ordering, and the
+ * queue consumer has no shared type to agree on.
+ */
+export declare const auditSchema: PikkuSchema;

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

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ *
+ * 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
+ * the same reader can read. `occurredAt` is an ISO 8601 string rather than a
+ * timestamp for that reason: string ordering is chronological ordering, and the
+ * queue consumer has no shared type to agree on.
+ */
+export const auditSchema = {
+    name: 'audit',
+    statements: [
+        (db) => db.schema
+            .createTable('audit')
+            .addColumn('auditId', 'text', (col) => col.primaryKey())
+            .addColumn('occurredAt', 'text', (col) => col.notNull())
+            .addColumn('type', 'text', (col) => col.notNull())
+            .addColumn('source', 'text', (col) => col.defaultTo('auto').notNull())
+            .addColumn('outcome', 'text')
+            .addColumn('functionId', 'text')
+            .addColumn('wireType', 'text')
+            .addColumn('traceId', 'text')
+            .addColumn('transactionId', 'text')
+            .addColumn('queryId', 'text')
+            .addColumn('userId', 'text')
+            .addColumn('orgId', 'text')
+            .addColumn('pikkuUserId', 'text')
+            .addColumn('tables', 'text')
+            .addColumn('changedCols', 'text')
+            .addColumn('event', 'text')
+            .addColumn('old', 'text')
+            .addColumn('data', 'text'),
+        // The trail is only ever read newest-first, and the two filters the console
+        // offers are user and type.
+        (db) => db.schema
+            .createIndex('idx_audit_occurred_at')
+            .on('audit')
+            .column('occurredAt'),
+        (db) => db.schema.createIndex('idx_audit_user_id').on('audit').column('userId'),
+        (db) => db.schema.createIndex('idx_audit_type').on('audit').column('type'),
+    ],
+};

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

@@ -5,7 +5,8 @@ import { type PikkuSchema } from './pikku-schema.types.js';
  * The uniqueness rule is an expression index — `user_id` is nullable and two
  * rows with a null user must still collide on name — which the schema builder
  * cannot express, so it stays raw. Raw SQL is not rewritten by `withSchema`,
- * which is why the table is named explicitly rather than left to the search
- * path.
+ * which is why the table goes through `ctx.table` rather than being left to the
+ * search path. The index's own name stays unqualified: an index belongs to the
+ * schema of the table it is on, and postgres rejects one that says otherwise.
  */
 export declare const credentialSchema: PikkuSchema;

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

@@ -6,8 +6,9 @@ import { rawStatement } from './pikku-schema.types.js';
  * The uniqueness rule is an expression index — `user_id` is nullable and two
  * rows with a null user must still collide on name — which the schema builder
  * cannot express, so it stays raw. Raw SQL is not rewritten by `withSchema`,
- * which is why the table is named explicitly rather than left to the search
- * path.
+ * which is why the table goes through `ctx.table` rather than being left to the
+ * search path. The index's own name stays unqualified: an index belongs to the
+ * schema of the table it is on, and postgres rejects one that says otherwise.
  */
 export const credentialSchema = {
     name: 'credential',
@@ -21,7 +22,7 @@ export const credentialSchema = {
             .addColumn('keyVersion', 'integer', (col) => col.notNull())
             .addColumn('createdAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
             .addColumn('updatedAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull()),
-        rawStatement(sql `CREATE UNIQUE INDEX credentials_name_user_id_unique ON credentials (name, COALESCE(user_id, ''))`),
+        rawStatement(({ table }) => sql `CREATE UNIQUE INDEX credentials_name_user_id_unique ON ${table('credentials')} (name, COALESCE(user_id, ''))`),
         (db) => db.schema
             .createTable('credentialKekSalts')
             .addColumn('keyVersion', 'integer', (col) => col.primaryKey())

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

@@ -1,7 +1,13 @@
 import { type Kysely } from 'kysely';
-import type { PikkuSchema, RequiredTypes, SchemaRequirement } from './pikku-schema.types.js';
-export type { PikkuSchema, RequiredTypes, SchemaRequirement, SchemaStatement, SchemaStatementFactory, } from './pikku-schema.types.js';
-export { rawStatement, requiredType } from './pikku-schema.types.js';
+import { type PikkuSchema, type RequiredTypes, type SchemaRequirement } from './pikku-schema.types.js';
+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.
  *
@@ -95,5 +101,12 @@ export declare const ensurePikkuSchema: (db: Kysely<any>, schema: PikkuSchema) =
  * `types` comes from `resolveRequirements` against the database the migration
  * is being written for. Omit it and foreign keys onto another source's columns
  * compile as `text`, which is a shape, not a migration.
+ *
+ * `schema` qualifies every table the migration creates, for a project that
+ * keeps the runtime tables somewhere other than the default search path. It is
+ * applied here and not to `db` itself because the caller's connection is a
+ * throwaway the declaration was just *applied* to, in whatever schema that
+ * database actually has — qualifying that would create tables in a schema the
+ * scratch database has never heard of. Only the rendered SQL is bound.
  */
-export declare const compilePikkuSchemas: (db: Kysely<any>, schemas?: PikkuSchema[], types?: RequiredTypes) => string;
+export declare const compilePikkuSchemas: (db: Kysely<any>, schemas?: PikkuSchema[], types?: RequiredTypes, schemaName?: string) => string;

package/dist/src/schema/index.js

@@ -1,4 +1,5 @@
 import { CamelCasePlugin } from 'kysely';
+import { schemaContext, } from './pikku-schema.types.js';
 import { aiSchema } from './ai.schema.js';
 import { channelSchema } from './channel.schema.js';
 import { credentialSchema } from './credential.schema.js';
@@ -8,7 +9,13 @@ import { secretSchema } from './secret.schema.js';
 import { sessionSchema } from './session.schema.js';
 import { webhookSchema } from './webhook.schema.js';
 import { workflowSchema } from './workflow.schema.js';
-export { rawStatement, requiredType } 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.
  *
@@ -37,6 +44,23 @@ export const pikkuSchemas = [
  * silently creates quoted camelCase tables that nothing can read.
  */
 const bind = (db) => db.withPlugin(new CamelCasePlugin());
+/**
+ * The schema a connection is bound to, or `undefined` for one that is not.
+ *
+ * Read back out of compiled DDL rather than off the connection, because kysely
+ * keeps the `withSchema(...)` setting inside its executor and exposes no way to
+ * ask. Compiling a throwaway `create table` is the same trick `declaredTables`
+ * uses on the real statements, against the same regex — nothing is executed and
+ * the probe never leaves this function.
+ *
+ * Derived rather than passed in so that raw statements follow whatever
+ * connection they are handed. A caller that had to remember to say the schema
+ * twice would eventually say it once.
+ */
+const boundSchema = (db) => CREATE_TABLE.exec(db.schema.createTable('pikkuSchemaProbe').addColumn('id', 'text').compile()
+    .sql)?.[1];
+/** The context for statements compiled against `db`, matching its binding. */
+const contextFor = (db) => schemaContext(boundSchema(db));
 /**
  * Look up every prerequisite in `db`, reporting the gaps and the types found.
  *
@@ -101,9 +125,10 @@ export const applyPikkuSchemas = async (db, schemas = pikkuSchemas) => {
     }
     await db.transaction().execute(async (trx) => {
         const bound = bind(trx);
+        const ctx = contextFor(bound);
         for (const schema of schemas) {
             for (const statement of schema.statements) {
-                const query = statement(bound, types);
+                const query = statement(bound, types, ctx);
                 try {
                     await query.execute();
                 }
@@ -177,9 +202,10 @@ const CREATE_TABLE = /^\s*create table (?:if not exists\s+)?(?:"([^"]+)"\.)?"([^
  */
 export const declaredTables = (schema, db) => {
     const bound = bind(db);
+    const ctx = contextFor(bound);
     const tables = [];
     for (const statement of schema.statements) {
-        const match = CREATE_TABLE.exec(statement(bound, {}).compile().sql);
+        const match = CREATE_TABLE.exec(statement(bound, {}, ctx).compile().sql);
         if (match)
             tables.push({ schema: match[1], name: match[2] });
     }
@@ -265,10 +291,18 @@ export const ensurePikkuSchema = async (db, schema) => {
  * `types` comes from `resolveRequirements` against the database the migration
  * is being written for. Omit it and foreign keys onto another source's columns
  * compile as `text`, which is a shape, not a migration.
+ *
+ * `schema` qualifies every table the migration creates, for a project that
+ * keeps the runtime tables somewhere other than the default search path. It is
+ * applied here and not to `db` itself because the caller's connection is a
+ * throwaway the declaration was just *applied* to, in whatever schema that
+ * database actually has — qualifying that would create tables in a schema the
+ * scratch database has never heard of. Only the rendered SQL is bound.
  */
-export const compilePikkuSchemas = (db, schemas = pikkuSchemas, types = {}) => {
-    const bound = bind(db);
+export const compilePikkuSchemas = (db, schemas = pikkuSchemas, types = {}, schemaName) => {
+    const bound = schemaName ? bind(db).withSchema(schemaName) : bind(db);
+    const ctx = contextFor(bound);
     return schemas
-        .flatMap((schema) => schema.statements.map((statement) => `${statement(bound, types).compile().sql};`))
+        .flatMap((schema) => schema.statements.map((statement) => `${statement(bound, types, ctx).compile().sql};`))
         .join('\n\n');
 };

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

@@ -11,7 +11,40 @@ export interface SchemaStatement {
     execute(): Promise<unknown>;
     compile(): CompiledQuery;
 }
-export type SchemaStatementFactory = (db: Kysely<any>, types: RequiredTypes) => SchemaStatement;
+export type SchemaStatementFactory = (db: Kysely<any>, types: RequiredTypes, ctx: SchemaContext) => SchemaStatement;
+/**
+ * What a statement needs to know about the schema its DDL lands in.
+ *
+ * Only raw SQL needs this. The schema builder learns the schema from the
+ * connection — `withSchema('app')` qualifies every table it names, foreign key
+ * targets included — but a raw fragment is passed through verbatim, so a
+ * statement that spells its own SQL has to spell the qualifier too.
+ */
+export interface SchemaContext {
+    /**
+     * A table as the surrounding DDL addresses it: `"app"."credentials"` on a
+     * schema-bound connection, `"credentials"` otherwise.
+     *
+     * Takes the physical name, not the camelCase one the schema builder accepts.
+     * Raw SQL does not go through `CamelCasePlugin`, so it is already written in
+     * physical names throughout and this is no exception.
+     */
+    table: (name: string) => RawBuilder<unknown>;
+}
+/**
+ * The `SchemaContext` for DDL that names no schema.
+ *
+ * The default everywhere a schema has not been asked for, which is every engine
+ * but postgres and most postgres projects too.
+ */
+export declare const unqualifiedContext: SchemaContext;
+/**
+ * A `SchemaContext` qualifying every table into `schema`.
+ *
+ * Identifiers are quoted rather than interpolated bare so a schema named after
+ * a reserved word still compiles.
+ */
+export declare const schemaContext: (schema: string | undefined) => SchemaContext;
 /**
  * The physical types of the columns named in `requires`, keyed `table.column`.
  *
@@ -68,8 +101,11 @@ export interface SchemaRequirement {
  * Wrap a raw SQL fragment as a statement.
  *
  * For the DDL kysely's schema builder cannot express — a unique index over an
- * expression, say. Note that raw SQL is *not* rewritten by `withSchema`, so a
- * fragment naming a table unqualified will resolve against the connection's
- * search path rather than the schema the rest of the declaration lands in.
+ * expression, say. Raw SQL is *not* rewritten by `withSchema`, so a fragment
+ * naming a table unqualified resolves against the connection's search path
+ * rather than the schema the rest of the declaration lands in. Take the
+ * function form and name tables through `ctx.table` to stay with them; the
+ * bare-fragment form is for SQL that names no table at all.
  */
-export declare const rawStatement: (fragment: RawBuilder<unknown>) => SchemaStatementFactory;
+export declare function rawStatement(fragment: RawBuilder<unknown>): SchemaStatementFactory;
+export declare function rawStatement(build: (ctx: SchemaContext) => RawBuilder<unknown>): SchemaStatementFactory;

package/dist/src/schema/pikku-schema.types.js

@@ -1,4 +1,22 @@
 import { sql } from 'kysely';
+/**
+ * The `SchemaContext` for DDL that names no schema.
+ *
+ * The default everywhere a schema has not been asked for, which is every engine
+ * but postgres and most postgres projects too.
+ */
+export const unqualifiedContext = {
+    table: (name) => sql.raw(`"${name}"`),
+};
+/**
+ * A `SchemaContext` qualifying every table into `schema`.
+ *
+ * Identifiers are quoted rather than interpolated bare so a schema named after
+ * a reserved word still compiles.
+ */
+export const schemaContext = (schema) => schema
+    ? { table: (name) => sql.raw(`"${schema}"."${name}"`) }
+    : unqualifiedContext;
 /**
  * The declared type for a foreign key onto a column another source owns.
  *
@@ -7,15 +25,12 @@ import { sql } from 'kysely';
  * and only the shape of the statement is being inspected.
  */
 export const requiredType = (types, table, column) => sql.raw(types[`${table}.${column}`] ?? 'text');
-/**
- * Wrap a raw SQL fragment as a statement.
- *
- * For the DDL kysely's schema builder cannot express — a unique index over an
- * expression, say. Note that raw SQL is *not* rewritten by `withSchema`, so a
- * fragment naming a table unqualified will resolve against the connection's
- * search path rather than the schema the rest of the declaration lands in.
- */
-export const rawStatement = (fragment) => (db) => ({
-    execute: () => fragment.execute(db),
-    compile: () => fragment.compile(db),
-});
+export function rawStatement(source) {
+    return (db, _types, ctx = unqualifiedContext) => {
+        const fragment = typeof source === 'function' ? source(ctx) : source;
+        return {
+            execute: () => fragment.execute(db),
+            compile: () => fragment.compile(db),
+        };
+    };
+}

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

@@ -0,0 +1,19 @@
+import type { PikkuSchema } from './pikku-schema.types.js';
+/**
+ * The `virtualUserRun` table {@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
+ * put an empty table in every database. `KyselyVirtualUserRunStore.init()`
+ * applies it, so it arrives exactly when the thing that fills it does.
+ *
+ * `persona` is text rather than a foreign key: personas are declared in code
+ * with `definePersonas()`, not rows, and a run has to outlive the deletion of
+ * the persona it ran as.
+ *
+ * The JSON columns are text on every engine, like the audit table's, because
+ * the store serialises them itself — a project on SQLite and one on Postgres
+ * then hold the same bytes, and comparing this week's findings against last
+ * week's does not depend on which database they were found in.
+ */
+export declare const virtualUserSchema: PikkuSchema;

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

@@ -0,0 +1,54 @@
+import { sql } from 'kysely';
+/**
+ * The `virtualUserRun` table {@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
+ * put an empty table in every database. `KyselyVirtualUserRunStore.init()`
+ * applies it, so it arrives exactly when the thing that fills it does.
+ *
+ * `persona` is text rather than a foreign key: personas are declared in code
+ * with `definePersonas()`, not rows, and a run has to outlive the deletion of
+ * the persona it ran as.
+ *
+ * The JSON columns are text on every engine, like the audit table's, because
+ * the store serialises them itself — a project on SQLite and one on Postgres
+ * then hold the same bytes, and comparing this week's findings against last
+ * week's does not depend on which database they were found in.
+ */
+export const virtualUserSchema = {
+    name: 'virtualUser',
+    statements: [
+        (db) => db.schema
+            .createTable('virtualUserRun')
+            .addColumn('runId', 'varchar(36)', (col) => col.primaryKey())
+            .addColumn('persona', 'varchar(255)', (col) => col.notNull())
+            .addColumn('disposition', 'varchar(50)', (col) => col.notNull())
+            .addColumn('seed', 'bigint', (col) => col.notNull())
+            // running | completed | failed. Not derived from `finishedAt` being
+            // null: a crashed run has no finish time either, and "crashed" and
+            // "still going" are not the same answer.
+            .addColumn('status', 'varchar(50)', (col) => col.defaultTo('running').notNull())
+            .addColumn('goals', 'text', (col) => col.defaultTo('[]').notNull())
+            .addColumn('memory', 'text', (col) => col.defaultTo('{}').notNull())
+            .addColumn('findings', 'text', (col) => col.defaultTo('[]').notNull())
+            // Counts the engine kept: steps, calls, mutations, tokens, elapsed.
+            .addColumn('tally', 'text')
+            .addColumn('stoppedBy', 'varchar(255)')
+            // Why the run itself failed, as opposed to what it found.
+            .addColumn('error', 'text')
+            .addColumn('startedBy', 'varchar(255)')
+            .addColumn('createdAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
+            .addColumn('finishedAt', 'timestamp'),
+        // The two reads: the run list newest-first, and one persona's history when
+        // a finding needs comparing against what that persona found before.
+        (db) => db.schema
+            .createIndex('idx_virtual_user_run_created')
+            .on('virtualUserRun')
+            .column('createdAt'),
+        (db) => db.schema
+            .createIndex('idx_virtual_user_run_persona')
+            .on('virtualUserRun')
+            .columns(['persona', 'createdAt']),
+    ],
+};

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/create-audited-kysely.ts","../src/index.ts","../src/kysely-ai-agent-run-service.ts","../src/kysely-ai-run-state-service.ts","../src/kysely-ai-storage-service.ts","../src/kysely-audit-service.ts","../src/kysely-channel-store.ts","../src/kysely-credential-service.ts","../src/kysely-deployment-service.ts","../src/kysely-eventhub-store.ts","../src/kysely-json.ts","../src/kysely-scope-service.ts","../src/kysely-secret-service.ts","../src/kysely-session-store.ts","../src/kysely-tables.ts","../src/kysely-webhook-service.ts","../src/kysely-workflow-mirror.ts","../src/kysely-workflow-run-service.ts","../src/kysely-workflow-service.ts","../src/serialize-plugin.ts","../src/schema/ai.schema.ts","../src/schema/channel.schema.ts","../src/schema/credential.schema.ts","../src/schema/deployment.schema.ts","../src/schema/index.ts","../src/schema/pikku-schema.types.ts","../src/schema/scope.schema.ts","../src/schema/secret.schema.ts","../src/schema/session.schema.ts","../src/schema/webhook.schema.ts","../src/schema/workflow.schema.ts","../bin/pikku-kysely-pure.ts"],"version":"6.0.3"}
+{"root":["../src/create-audited-kysely.ts","../src/index.ts","../src/kysely-ai-agent-run-service.ts","../src/kysely-ai-run-state-service.ts","../src/kysely-ai-storage-service.ts","../src/kysely-audit-service.ts","../src/kysely-channel-store.ts","../src/kysely-credential-service.ts","../src/kysely-deployment-service.ts","../src/kysely-eventhub-store.ts","../src/kysely-json.ts","../src/kysely-scope-service.ts","../src/kysely-secret-service.ts","../src/kysely-session-store.ts","../src/kysely-tables.ts","../src/kysely-virtual-user-run-store.ts","../src/kysely-webhook-service.ts","../src/kysely-workflow-mirror.ts","../src/kysely-workflow-run-service.ts","../src/kysely-workflow-service.ts","../src/serialize-plugin.ts","../src/schema/ai.schema.ts","../src/schema/audit.schema.ts","../src/schema/channel.schema.ts","../src/schema/credential.schema.ts","../src/schema/deployment.schema.ts","../src/schema/index.ts","../src/schema/pikku-schema.types.ts","../src/schema/scope.schema.ts","../src/schema/secret.schema.ts","../src/schema/session.schema.ts","../src/schema/virtual-user.schema.ts","../src/schema/webhook.schema.ts","../src/schema/workflow.schema.ts","../bin/pikku-kysely-pure.ts"],"version":"6.0.3"}

package/package.json

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