@pikku/kysely 0.13.7 → 0.13.10

package/CHANGELOG.md

@@ -1,3 +1,183 @@
+## 0.13.10
+
+### Patch Changes
+
+- 3df4f95: Scaffold virtual user runs as RPCs, backed by a run store.
+
+  `pikku persona run` could already turn a declared persona loose on a running
+  stage, but only from a terminal, and the result only existed in that terminal's
+  output. There was no way for CI, a console, or a scheduled job to start a run —
+  and nothing kept what a run found, so this week's findings could not be compared
+  against last week's.
+
+  `scaffold.virtualUser` now generates two RPCs and the function behind them:
+  - `runVirtualUser({ persona, goals?, memory?, disposition?, budget?, seed? })
+-> { runId }`
+  - `getVirtualUserRun({ runId }) -> { status, findings, tally, memory, … }`
+
+  They are gated on separate scopes — `virtualUser:run` and `virtualUser:read` —
+  because an adversarial run's findings are working exploits carrying live ids,
+  which makes reading them the more sensitive of the two. Production refuses every
+  disposition but `accountable`, checked against the effective one so the
+  per-run override cannot smuggle another in.
+
+  **A run is not a workflow and not a queued job.** It explores, so no two
+  attempts take the same steps and there is nothing to replay; and the record
+  already carries the progress a queue would only be holding on the way to the
+  same place. `runVirtualUser` writes the record, dispatches without awaiting, and
+  returns the id. The cost is stated on the type: a restart mid-run strands a
+  record at `running`, so a run older than its budget window and still `running`
+  is dead rather than working.
+
+  `@pikku/core` gains `VirtualUserRunStore` (with `virtualUserRunStore` on
+  `CoreSingletonServices`), and `@pikku/kysely` ships
+  `KyselyVirtualUserRunStore`, which creates its own table on first use like the
+  audit sink — the runtime never needs it, so it arrives with the feature that
+  fills it rather than in every database.
+
+  Also in core: `prepareVirtualUserRun`, which derives the catalogue, intents,
+  scopes and reachable agents in one place. `pikku persona run` reads the
+  inspector state and the generated RPC reads `metaService`, and the two have to
+  agree — otherwise the same persona and seed explore a different API depending on
+  how the run was started. `personaScopes` moved here from the CLI for the same
+  reason and is still re-exported from its old home. `PRODUCTION_DISPOSITION` is
+  now exported from `@pikku/core/virtual-user`, which it should always have been.
+
+- Updated dependencies [3df4f95]
+  - @pikku/core@0.12.77
+
+## 0.13.9
+
+### Patch Changes
+
+- 62ea4cc: The audit trail is now readable — in the generated meta, through an RPC, and as
+  a page in the console.
+
+  `audit: true` reaches `FunctionRuntimeMeta.audit` as its resolved form
+  (`{ durability }`), so which functions record anything is answerable without
+  running them. It is informational: the runner still resolves audit from the live
+  function config, so meta and runtime cannot disagree.
+
+  `AuditService` grows an optional read side — `query(AuditQuery)` and `facets()`.
+  Optional because a sink can legitimately be write-only: a queue producer that
+  hands events to another system has nothing to read back, and a reader that finds
+  these absent should say the trail is not readable here rather than that it is
+  empty. The two are very different answers to give someone auditing a system.
+
+  `KyselyAuditService` implements both, newest first with offset paging, filtered
+  by user, action and time window. Two things it now gets right that are easy to
+  get wrong: an empty filter array means "match nothing" rather than "no filter",
+  and results are read by physical _and_ camelCase key, because `CamelCasePlugin`
+  is on most pikku Kysely instances and renames result keys on the way out — the
+  mismatch does not throw, it returns a page of `undefined`. `init()` creates the
+  `audit` table for projects that do not migrate it themselves, from a new
+  exported `auditSchema` that stays out of `pikkuSchemas` because the runtime does
+  not need it.
+
+  The console addon exposes `console:getAudits` and `console:getAuditFilters`
+  behind a new `pikku:audit:read` scope, and forwards the application's `audit`
+  service into the addon's own services — without that last part every install
+  reported the trail as unreadable, whatever sink it had configured.
+
+  The console gets an Audit trail page: an infinite list filtered server-side by
+  user and action, and a row that opens the whole event, metadata rendered as a
+  JSON tree. Refused, unreadable and empty are three different screens, because
+  "you may not read this", "nobody can read this" and "nothing happened" are three
+  different facts.
+
+  Events name the person who caused them. The trail records a user id — the only
+  thing stable enough to record, since a name can change after the event — so
+  `getAudits` resolves those ids against better-auth's user directory at read
+  time, and the page shows the name while keeping the recorded id on the event.
+  The filter follows: pick a colleague by name, filter by the id. A scenario
+  actor is labelled as one, so synthetic traffic is not mistaken for real, and a
+  caller who was signed out shows the wire identity pikku resolved for them
+  rather than being credited to the system.
+
+  **Breaking, for anyone already reading `AuditEvent`:** `actor` is now
+  `userIdentity`, and its type `AuditActor` is `AuditUserIdentity`; `AuditQuery`
+  takes `userIds`/`orgId` in place of `actorUserIds`/`actorOrgId`, and
+  `AuditFacets` returns `userIds`. In pikku an _actor_ is a synthetic person a
+  scenario drives, flagged on the user row — so naming the causer of an event
+  `actor` made the synthetic case unsayable (`actor.actor === true`) and implied
+  every recorded action was a test. The overwhelming majority are ordinary
+  customers. The `audit` table follows: `actor_user_id` / `actor_org_id`
+  are now `user_id` / `org_id`, and a `pikku_user_id` column joins them so the
+  wire identity of a caller who never signed in survives the round trip — the
+  sink was dropping it, which left the console's Session field permanently
+  blank. A project that already migrated the table needs to rename the two
+  columns and add the third; `KyselyAuditService.init()` creates the new shape
+  for anyone who did not.
+
+- 78b29f0: `SecretService` now returns a `SecretValue<T>` rather than the bare value, so a
+  vault secret cannot reach a sink by accident.
+
+  `SecretValue` is nominally typed, which means it is not assignable to `string`
+  (or to any other concretely-typed field). Every sink with a real type — a
+  database column, an email body, a session payload — rejects it with no lint
+  rule involved. The sinks typed `any`, `unknown`, or a free generic — the logger,
+  queue payloads, webhook and email inputs, and a function's own output — are
+  guarded with `Safe<T>`, which collapses a `SecretValue` found anywhere inside
+  `T`, however deeply nested, to `never`.
+
+  Unwrap deliberately at the point the secret reaches the wire:
+
+  ```ts
+  const secret = await secrets.getSecret('BETTER_AUTH_SECRET')
+  betterAuth({ secret: secret.reveal() })
+  ```
+
+  Two behaviours cover what types cannot see. Structured serialization redacts —
+  `JSON.stringify` and node's inspect both yield `[secret]`, so an audit or log
+  write stays honest without crashing the request. String coercion throws
+  `SecretCoercionError`, because a template literal is always a leak.
+
+  `AuditLog.write` is guarded the same way as the logger, since an audit event
+  carries `input` and `metadata` as `unknown` and nominality alone cannot stop a
+  secret landing in one.
+
+  `.reveal()` is the deliberate escape hatch, and what it hands back is an
+  ordinary string as far as every sink signature is concerned. **PKU953** closes
+  that gap: under `pikku all --security` the inspector reports a revealed secret
+  that flows into a logger, an audit, a queue, an email or a webhook — `console` included.
+
+  This also fixed a real one: `remote-addon-auth.ts` called `String(token)` on an
+  `unknown` and wrote the result straight into an `Authorization` header.
+
+- Updated dependencies [62ea4cc]
+- Updated dependencies [9dddff8]
+- Updated dependencies [78b29f0]
+  - @pikku/core@0.12.76
+
+## 0.13.8
+
+### Patch Changes
+
+- cabd9dc: Add a `db.schema` CLI config option, so `pikku db generate` can write the runtime tables into a named postgres schema.
+
+  Without it the generator emits unqualified `create table` against the default `search_path` of `"$user", public`. A project that keeps everything in one namespace — `app`, say — gets a second copy of every runtime table in `public` alongside the ones it already has, which is how stray `public.ai_*` tables appear next to the real `app.ai_*` ones.
+
+  `compilePikkuSchemas` takes the schema and binds only the rendered SQL, never the caller's connection: that connection is the throwaway database the declaration was just applied to, and qualifying it would create tables in a schema the scratch database has never heard of.
+
+  Raw SQL is not rewritten by `withSchema`, so `rawStatement` now also accepts a builder taking a `SchemaContext` — the expression index on `credentials` uses it to qualify its own table. Statements otherwise pick the context up from whatever connection they are handed, so a schema-bound connection needs nothing said twice.
+
+  Two fixes fall out of it:
+  - The `ALTER TABLE` delta for a partially covered source is written from bare introspected names, so it is qualified explicitly. Unqualified it altered a table in whichever schema `search_path` found.
+  - A source was only counted as partially covered on an exact name match, so a project whose migrations already create `app.workflow_step` read as "nothing covered" and had its whole schema re-emitted over tables that were already there. It now matches the schema qualifier the same way the drift diff does.
+
+  `db.schema` is postgres only, and is rejected with an explanation on sqlite, whose `REFERENCES` clause takes a bare table name.
+
+- Updated dependencies [32277d5]
+- Updated dependencies [ea8aabf]
+- Updated dependencies [33e96ab]
+- Updated dependencies [fd72e58]
+- Updated dependencies [fd72e58]
+- Updated dependencies [fd72e58]
+- Updated dependencies [894b2f8]
+- Updated dependencies [dd19aa7]
+- Updated dependencies [50ec500]
+  - @pikku/core@0.12.75
+
 ## 0.13.7
 
 ### Patch Changes

package/dist/src/index.d.ts

@@ -16,8 +16,11 @@ export { KyselyScopeService } from './kysely-scope-service.js';
 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 { SerializePlugin, SqliteSerializePlugin, BaseSerializePlugin, defaultSerializer, defaultDeserializer, maybeJson, skipTransform, dateRegex, type Serializer, type Deserializer, type SerializePluginOptions, } from './serialize-plugin.js';
-export { pikkuSchemas, applyPikkuSchemas, compilePikkuSchemas, ensurePikkuSchema, type EnsureOutcome, resolveRequirements, unsatisfiedRequirements, rawStatement, requiredType, type PikkuSchema, type RequiredTypes, type SchemaRequirement, type UnmetRequirement, type SchemaStatement, type SchemaStatementFactory, } from './schema/index.js';
+export { virtualUserSchema } from './schema/virtual-user.schema.js';
+export { auditSchema, pikkuSchemas, applyPikkuSchemas, compilePikkuSchemas, ensurePikkuSchema, type EnsureOutcome, resolveRequirements, unsatisfiedRequirements, rawStatement, requiredType, type PikkuSchema, type RequiredTypes, type SchemaRequirement, type UnmetRequirement, type SchemaStatement, 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/ai-agent';
+export type { VirtualUserRunStore, VirtualUserRunRecord, } from '@pikku/core/virtual-user';

package/dist/src/index.js

@@ -14,5 +14,7 @@ export { KyselyScopeService } from './kysely-scope-service.js';
 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 { SerializePlugin, SqliteSerializePlugin, BaseSerializePlugin, defaultSerializer, defaultDeserializer, maybeJson, skipTransform, dateRegex, } from './serialize-plugin.js';
-export { pikkuSchemas, applyPikkuSchemas, compilePikkuSchemas, ensurePikkuSchema, resolveRequirements, unsatisfiedRequirements, rawStatement, requiredType, } from './schema/index.js';
+export { virtualUserSchema } from './schema/virtual-user.schema.js';
+export { auditSchema, pikkuSchemas, applyPikkuSchemas, compilePikkuSchemas, ensurePikkuSchema, resolveRequirements, unsatisfiedRequirements, rawStatement, requiredType, } from './schema/index.js';

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

@@ -1,4 +1,4 @@
-import type { AuditEvent, AuditEventBatch, AuditService } from '@pikku/core';
+import type { AuditEvent, AuditEventBatch, AuditFacets, AuditQuery, AuditQueryResult, AuditService } from '@pikku/core';
 import type { Kysely } from 'kysely';
 /**
  * Durable {@link AuditService} that persists AuditEvents to an `audit` table
@@ -6,14 +6,46 @@ import type { Kysely } from 'kysely';
  *
  * The column mapping matches a platform audit-queue consumer, so a locally-run
  * project and a deployed stage write identical rows (the read side relies only
- * on `type`, `occurred_at`, `actor_user_id`, and the `data` JSON that holds
+ * on `type`, `occurred_at`, `user_id`, and the `data` JSON that holds
  * `metadata`). The `audit` table is an optional per-project migration (not in
  * the generated schema), so rows are inserted untyped; all columns are TEXT on
  * every engine and ON CONFLICT DO NOTHING keeps writes idempotent on retries.
  */
 export declare class KyselyAuditService implements AuditService {
     private db;
+    private initialized;
     constructor(db: Kysely<any>);
+    /**
+     * Creates the `audit` table if the database has none.
+     *
+     * Optional — a project that migrates the table itself can skip it, and the
+     * declaration is written to match the documented shape either way. Calling it
+     * on a database that already has the table is a no-op, so two instances
+     * booting cold do not race each other into a half-applied schema.
+     */
+    init(): Promise<void>;
     audit(event: AuditEvent): Promise<void>;
     write(batch: AuditEventBatch): Promise<void>;
+    /**
+     * A page of the trail, newest first.
+     *
+     * Offset paging, matching the rest of the console. The trail is append-only
+     * and ordered by `occurred_at DESC`, so events written *while* a reader is
+     * paging shift the window and can repeat a row across pages. That is visible
+     * but harmless for browsing; anything that must not miss a row should page by
+     * a bounded `from`/`to` window instead of scrolling.
+     *
+     * Ties on `occurred_at` are broken by `audit_id` so the order is total —
+     * without it a batch flushed in one call shares a timestamp and the engine is
+     * free to order it differently per query, which drops or repeats rows at a
+     * page boundary.
+     */
+    query(query?: AuditQuery): Promise<AuditQueryResult>;
+    facets(): Promise<AuditFacets>;
+    /**
+     * An empty array means "match nothing" and is applied as such. Treating it as
+     * "no filter" would turn a reader's deselect-everything into a full-trail
+     * read, which is the opposite of what they asked for.
+     */
+    private applyFilters;
 }

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

@@ -1,4 +1,64 @@
+import { ensurePikkuSchema } from './schema/index.js';
+import { auditSchema } from './schema/audit.schema.js';
 const jsonOrNull = (v) => v != null ? JSON.stringify(v) : null;
+const parseJson = (v) => {
+    if (typeof v !== 'string')
+        return v ?? undefined;
+    try {
+        return JSON.parse(v);
+    }
+    catch {
+        // A row written by something other than this service, or truncated in
+        // transit. Surfacing the raw text beats dropping the event: the row is
+        // still evidence that something happened, and swallowing it would make the
+        // trail quietly incomplete.
+        return v;
+    }
+};
+/**
+ * A column by its physical name, whatever the connection renamed it to.
+ *
+ * `CamelCasePlugin` is on most pikku Kysely instances and rewrites result keys
+ * on the way out, so the same row arrives keyed `audit_id` or `auditId`
+ * depending on a plugin this service is never told about. Reading both is
+ * cheaper than demanding a particular connection — and quieter to get wrong,
+ * since the mismatch does not throw, it just returns a page of undefined.
+ */
+const column = (row, name) => {
+    const value = row[name];
+    if (value !== undefined)
+        return value;
+    return row[name.replace(/_(\w)/g, (_, char) => char.toUpperCase())];
+};
+/** Rows are TEXT on every engine, so the shape is whatever the driver returned. */
+const rowToEvent = (row) => {
+    const userId = column(row, 'user_id');
+    const orgId = column(row, 'org_id');
+    const pikkuUserId = column(row, 'pikku_user_id');
+    return {
+        eventId: column(row, 'audit_id') ?? undefined,
+        occurredAt: column(row, 'occurred_at'),
+        type: row.type,
+        source: row.source ?? 'auto',
+        outcome: row.outcome ?? undefined,
+        functionId: column(row, 'function_id') ?? undefined,
+        wireType: column(row, 'wire_type') ?? undefined,
+        traceId: column(row, 'trace_id') ?? undefined,
+        transactionId: column(row, 'transaction_id') ?? undefined,
+        queryId: column(row, 'query_id') ?? undefined,
+        userIdentity: userId || orgId || pikkuUserId
+            ? {
+                userId: userId ?? undefined,
+                orgId: orgId ?? undefined,
+                pikkuUserId: pikkuUserId ?? undefined,
+            }
+            : undefined,
+        metadata: parseJson(row.data),
+    };
+};
+/** The most a single page may return, whatever the caller asked for. */
+const MAX_LIMIT = 200;
+const DEFAULT_LIMIT = 50;
 // No global `crypto` is guaranteed across every runtime, and audit_id is the
 // PK — any collision is dropped by ON CONFLICT DO NOTHING.
 const fallbackId = () => `evt_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
@@ -8,16 +68,31 @@ const fallbackId = () => `evt_${Date.now().toString(36)}${Math.random().toString
  *
  * The column mapping matches a platform audit-queue consumer, so a locally-run
  * project and a deployed stage write identical rows (the read side relies only
- * on `type`, `occurred_at`, `actor_user_id`, and the `data` JSON that holds
+ * on `type`, `occurred_at`, `user_id`, and the `data` JSON that holds
  * `metadata`). The `audit` table is an optional per-project migration (not in
  * the generated schema), so rows are inserted untyped; all columns are TEXT on
  * every engine and ON CONFLICT DO NOTHING keeps writes idempotent on retries.
  */
 export class KyselyAuditService {
     db;
+    initialized = false;
     constructor(db) {
         this.db = db;
     }
+    /**
+     * Creates the `audit` table if the database has none.
+     *
+     * Optional — a project that migrates the table itself can skip it, and the
+     * declaration is written to match the documented shape either way. Calling it
+     * on a database that already has the table is a no-op, so two instances
+     * booting cold do not race each other into a half-applied schema.
+     */
+    async init() {
+        if (this.initialized)
+            return;
+        await ensurePikkuSchema(this.db, auditSchema);
+        this.initialized = true;
+    }
     async audit(event) {
         await this.write([event]);
     }
@@ -37,8 +112,9 @@ export class KyselyAuditService {
                 trace_id: e.traceId ?? null,
                 transaction_id: e.transactionId ?? null,
                 query_id: e.queryId ?? null,
-                actor_user_id: e.actor?.userId ?? null,
-                actor_org_id: e.actor?.orgId ?? null,
+                user_id: e.userIdentity?.userId ?? null,
+                org_id: e.userIdentity?.orgId ?? null,
+                pikku_user_id: e.userIdentity?.pikkuUserId ?? null,
                 tables: jsonOrNull(metadata?.tables),
                 changed_cols: jsonOrNull(metadata?.changedColumns),
                 event: e.eventId ?? null,
@@ -52,4 +128,88 @@ export class KyselyAuditService {
             .onConflict((oc) => oc.doNothing())
             .execute();
     }
+    /**
+     * A page of the trail, newest first.
+     *
+     * Offset paging, matching the rest of the console. The trail is append-only
+     * and ordered by `occurred_at DESC`, so events written *while* a reader is
+     * paging shift the window and can repeat a row across pages. That is visible
+     * but harmless for browsing; anything that must not miss a row should page by
+     * a bounded `from`/`to` window instead of scrolling.
+     *
+     * Ties on `occurred_at` are broken by `audit_id` so the order is total —
+     * without it a batch flushed in one call shares a timestamp and the engine is
+     * free to order it differently per query, which drops or repeats rows at a
+     * page boundary.
+     */
+    async query(query = {}) {
+        const limit = Math.min(Math.max(query.limit ?? DEFAULT_LIMIT, 1), MAX_LIMIT);
+        const offset = Math.max(query.offset ?? 0, 0);
+        let builder = this.db.selectFrom('audit').selectAll();
+        builder = this.applyFilters(builder, query);
+        const rows = await builder
+            .orderBy('occurred_at', 'desc')
+            .orderBy('audit_id', 'desc')
+            // One extra row is the cheapest honest way to know whether another page
+            // exists — a COUNT would be a second scan of the same filter.
+            .limit(limit + 1)
+            .offset(offset)
+            .execute();
+        const hasMore = rows.length > limit;
+        return {
+            events: rows.slice(0, limit).map(rowToEvent),
+            nextCursor: hasMore ? offset + limit : null,
+        };
+    }
+    async facets() {
+        const [users, types] = await Promise.all([
+            this.db
+                .selectFrom('audit')
+                .select('user_id')
+                .distinct()
+                .where('user_id', 'is not', null)
+                .orderBy('user_id', 'asc')
+                .execute(),
+            this.db
+                .selectFrom('audit')
+                .select('type')
+                .distinct()
+                .orderBy('type', 'asc')
+                .execute(),
+        ]);
+        return {
+            userIds: users.map((r) => column(r, 'user_id')),
+            types: types.map((r) => r.type).filter(Boolean),
+        };
+    }
+    /**
+     * An empty array means "match nothing" and is applied as such. Treating it as
+     * "no filter" would turn a reader's deselect-everything into a full-trail
+     * read, which is the opposite of what they asked for.
+     */
+    applyFilters(builder, query) {
+        // `in ()` is a syntax error on Postgres and SQLite alike, so an empty
+        // selection is expressed as a predicate that cannot hold.
+        const matchNothing = (b) => b.where('audit_id', 'is', null);
+        if (query.userIds) {
+            builder = query.userIds.length
+                ? builder.where('user_id', 'in', query.userIds)
+                : matchNothing(builder);
+        }
+        if (query.types) {
+            builder = query.types.length
+                ? builder.where('type', 'in', query.types)
+                : matchNothing(builder);
+        }
+        if (query.orgId) {
+            builder = builder.where('org_id', '=', query.orgId);
+        }
+        if (query.from) {
+            builder = builder.where('occurred_at', '>=', query.from);
+        }
+        if (query.to) {
+            builder = builder.where('occurred_at', '<', query.to);
+        }
+        return builder;
+    }
 }

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

@@ -1,4 +1,5 @@
-import type { SecretService } from '@pikku/core/services';
+import { type SecretValue } from '@pikku/core';
+import type { SecretService, SecretValues } from '@pikku/core/services';
 import type { Kysely } from 'kysely';
 import type { KyselyPikkuDB } from './kysely-tables.js';
 export interface KyselySecretServiceConfig {
@@ -23,10 +24,10 @@ export declare class KyselySecretService implements SecretService {
     private logAudit;
     private getKEKSalt;
     private getKEK;
-    getSecret<T = string>(key: string): Promise<T>;
+    getSecret<T = string>(key: string): Promise<SecretValue<T>>;
     hasSecret(key: string): Promise<boolean>;
     setSecret(key: string, value: unknown): Promise<void>;
     deleteSecret(key: string): Promise<void>;
-    getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<T>;
+    getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<Partial<SecretValues<T>>>;
     rotateKEK(): Promise<number>;
 }

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

@@ -1,3 +1,4 @@
+import { createSecretValue, isSecretValue } from '@pikku/core';
 import { deriveKEK, generateKEKSalt, envelopeEncrypt, envelopeDecrypt, envelopeRewrap, } from '@pikku/core/crypto-utils';
 import { ensurePikkuSchema } from './schema/index.js';
 import { secretSchema } from './schema/secret.schema.js';
@@ -93,7 +94,7 @@ export class KyselySecretService {
         const kek = await this.getKEK(row.keyVersion);
         const result = await envelopeDecrypt(kek, row.ciphertext, row.wrappedDek);
         await this.logAudit(key, 'read');
-        return result;
+        return createSecretValue(result);
     }
     async hasSecret(key) {
         const row = await this.db
@@ -104,7 +105,9 @@ export class KyselySecretService {
         return !!row;
     }
     async setSecret(key, value) {
-        const { ciphertext, wrappedDEK } = await envelopeEncrypt(await this.getKEK(this.keyVersion), value);
+        // Encrypting the wrapper would store its redaction, not the secret —
+        // writing a secret back to the vault is exactly what this method is for.
+        const { ciphertext, wrappedDEK } = await envelopeEncrypt(await this.getKEK(this.keyVersion), isSecretValue(value) ? value.reveal() : value);
         const now = new Date().toISOString();
         await this.db
             .insertInto('secrets')
@@ -139,7 +142,7 @@ export class KyselySecretService {
         for (const row of rows) {
             try {
                 const kek = await this.getKEK(row.keyVersion);
-                out[row.key] = await envelopeDecrypt(kek, row.ciphertext, row.wrappedDek);
+                out[row.key] = createSecretValue(await envelopeDecrypt(kek, row.ciphertext, row.wrappedDek));
             }
             catch (cause) {
                 // A stored secret that fails to decrypt is never expected — it means the

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

@@ -248,6 +248,36 @@ export interface WebhookDeliveryAttemptTable {
     error: string | null;
     createdAt: Generated<Date>;
 }
+/**
+ * One virtual-user run. The JSON columns (`goals`, `memory`, `findings`,
+ * `tally`) are text the store serialises itself, so the row is byte-identical
+ * on every engine.
+ */
+export interface VirtualUserRunTable {
+    runId: string;
+    persona: string;
+    disposition: string;
+    /**
+     * Read back as a string by some drivers — a BIGINT does not always fit a JS
+     * number — so the store narrows it rather than trusting the column type.
+     */
+    seed: string | number | bigint;
+    status: Generated<'running' | 'completed' | 'failed'>;
+    goals: Generated<string>;
+    memory: Generated<string>;
+    findings: Generated<string>;
+    tally: string | null;
+    stoppedBy: string | null;
+    error: string | null;
+    startedBy: string | null;
+    /**
+     * Written as an ISO string and read back as whatever the driver returns — a
+     * bare SQLite driver cannot bind a `Date` at all, and the store normalises
+     * both ends.
+     */
+    createdAt: Generated<Date | string>;
+    finishedAt: Date | string | null;
+}
 export interface KyselyPikkuDB {
     pikkuScopes: PikkuScopesTable;
     pikkuRoles: PikkuRolesTable;
@@ -276,4 +306,5 @@ export interface KyselyPikkuDB {
     pikkuUserSessions: UserSessionsTable;
     webhookDelivery: WebhookDeliveryTable;
     webhookDeliveryAttempt: WebhookDeliveryAttemptTable;
+    virtualUserRun: VirtualUserRunTable;
 }

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

@@ -0,0 +1,43 @@
+import type { Kysely } from 'kysely';
+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;
+    constructor(db: Kysely<KyselyPikkuDB>);
+    /**
+     * 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.
+     */
+    init(): Promise<void>;
+    start(run: VirtualUserRunStart): Promise<string>;
+    complete(runId: string, outcome: VirtualUserRunOutcome): Promise<void>;
+    fail(runId: string, error: string): Promise<void>;
+    get(runId: string): Promise<VirtualUserRunRecord | null>;
+    list(options?: {
+        persona?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<VirtualUserRunRecord[]>;
+    private toRecord;
+}