@pikku/kysely 0.13.7 → 0.13.11

package/src/create-audited-kysely.test.ts

@@ -33,8 +33,8 @@ interface AuditEventTable {
   traceId: string | null
   transactionId: string | null
   queryId: string | null
-  actorUserId: string | null
-  actorOrgId: string | null
+  userId: string | null
+  orgId: string | null
   actorPikkuUserId: string | null
   metadataJson: string | null
 }
@@ -76,8 +76,8 @@ async function createAuditEventsTable(
     .addColumn('traceId', 'text')
     .addColumn('transactionId', 'text')
     .addColumn('queryId', 'text')
-    .addColumn('actorUserId', 'text')
-    .addColumn('actorOrgId', 'text')
+    .addColumn('userId', 'text')
+    .addColumn('orgId', 'text')
     .addColumn('actorPikkuUserId', 'text')
     .addColumn('metadataJson', 'text')
     .execute()
@@ -113,9 +113,9 @@ class ImmediateAuditService implements AuditService {
         traceId: event.traceId ?? null,
         transactionId: event.transactionId ?? null,
         queryId: event.queryId ?? null,
-        actorUserId: event.actor?.userId ?? null,
-        actorOrgId: event.actor?.orgId ?? null,
-        actorPikkuUserId: event.actor?.pikkuUserId ?? null,
+        userId: event.userIdentity?.userId ?? null,
+        orgId: event.userIdentity?.orgId ?? null,
+        actorPikkuUserId: event.userIdentity?.pikkuUserId ?? null,
         metadataJson: event.metadata ? JSON.stringify(event.metadata) : null,
       })
       .execute()
@@ -207,7 +207,7 @@ describe('createAuditedKysely', () => {
       changes: { title: 'write tests', done: 0 },
       rowCount: 1,
     })
-    assert.deepEqual(events[0]?.actor, {
+    assert.deepEqual(events[0]?.userIdentity, {
       userId: 'user-1',
       orgId: 'org-1',
       pikkuUserId: 'user-1',
@@ -257,7 +257,7 @@ describe('createAuditedKysely', () => {
       title: 'after',
       done: 1,
     })
-    assert.deepEqual(events[0]?.actor, {
+    assert.deepEqual(events[0]?.userIdentity, {
       userId: 'user-2',
       orgId: undefined,
       pikkuUserId: 'user-2',
@@ -455,7 +455,7 @@ describe('createAuditedKysely', () => {
       ['todos:best-effort', 'todos:best-effort']
     )
     assert.deepEqual(
-      persisted.map((event) => event.actorUserId),
+      persisted.map((event) => event.userId),
       ['user-best-effort', 'user-best-effort']
     )
     assert.equal(persisted[0]?.queryId, 'q-1')

package/src/index.ts

@@ -19,6 +19,7 @@ export {
   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,
@@ -34,7 +35,9 @@ export {
   type SerializePluginOptions,
 } from './serialize-plugin.js'
 
+export { virtualUserSchema } from './schema/virtual-user.schema.js'
 export {
+  auditSchema,
   pikkuSchemas,
   applyPikkuSchemas,
   compilePikkuSchemas,
@@ -55,3 +58,7 @@ export {
 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/src/kysely-audit-service.test.ts

@@ -0,0 +1,360 @@
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+import Database from 'better-sqlite3'
+import { CamelCasePlugin, Kysely, SqliteDialect, sql } from 'kysely'
+import type { AuditEvent } from '../../../core/src/index.js'
+
+import { KyselyAuditService } from './kysely-audit-service.js'
+
+/**
+ * The `audit` table as the docs specify it — all TEXT on every engine, so the
+ * service is exercised against the same shape a project would migrate to.
+ */
+const CREATE_AUDIT_TABLE = `
+  CREATE TABLE audit (
+    audit_id       TEXT NOT NULL PRIMARY KEY,
+    occurred_at    TEXT NOT NULL,
+    type           TEXT NOT NULL,
+    source         TEXT NOT NULL DEFAULT 'auto',
+    outcome        TEXT,
+    function_id    TEXT,
+    wire_type      TEXT,
+    trace_id       TEXT,
+    transaction_id TEXT,
+    query_id       TEXT,
+    user_id        TEXT,
+    org_id         TEXT,
+    pikku_user_id  TEXT,
+    tables         TEXT,
+    changed_cols   TEXT,
+    event          TEXT,
+    old            TEXT,
+    data           TEXT
+  )
+`
+
+let db: Kysely<any>
+let service: KyselyAuditService
+
+const event = (
+  overrides: Partial<AuditEvent> & Pick<AuditEvent, 'type' | 'occurredAt'>
+): AuditEvent => ({
+  source: 'explicit',
+  ...overrides,
+})
+
+beforeEach(async () => {
+  db = new Kysely<any>({
+    dialect: new SqliteDialect({ database: new Database(':memory:') }),
+  })
+  await sql.raw(CREATE_AUDIT_TABLE).execute(db)
+  service = new KyselyAuditService(db)
+})
+
+const seed = () =>
+  service.write([
+    event({
+      eventId: 'e1',
+      type: 'invoice.update',
+      occurredAt: '2026-01-01T00:00:00.000Z',
+      userIdentity: { userId: 'alice', orgId: 'org-a' },
+      metadata: { entity: 'invoice', entityId: 'inv-1' },
+    }),
+    event({
+      eventId: 'e2',
+      type: 'invoice.delete',
+      occurredAt: '2026-01-02T00:00:00.000Z',
+      userIdentity: { userId: 'bob', orgId: 'org-a' },
+    }),
+    event({
+      eventId: 'e3',
+      type: 'invoice.update',
+      occurredAt: '2026-01-03T00:00:00.000Z',
+      userIdentity: { userId: 'alice', orgId: 'org-b' },
+    }),
+  ])
+
+describe('KyselyAuditService.query', () => {
+  test('returns the trail newest first', async () => {
+    await seed()
+    const { events, nextCursor } = await service.query()
+    assert.deepEqual(
+      events.map((e) => e.eventId),
+      ['e3', 'e2', 'e1']
+    )
+    assert.equal(nextCursor, null, 'a complete page has no next cursor')
+  })
+
+  test('round-trips the event, including parsed metadata', async () => {
+    await seed()
+    const { events } = await service.query({ types: ['invoice.update'] })
+    const first = events.find((e) => e.eventId === 'e1')!
+    assert.equal(first.type, 'invoice.update')
+    assert.equal(first.source, 'explicit')
+    assert.deepEqual(first.userIdentity, {
+      userId: 'alice',
+      orgId: 'org-a',
+      pikkuUserId: undefined,
+    })
+    assert.deepEqual(first.metadata, { entity: 'invoice', entityId: 'inv-1' })
+  })
+
+  test('keeps the wire identity of a caller who never signed in', async () => {
+    await service.write([
+      event({
+        eventId: 'e4',
+        type: 'invoice.view',
+        occurredAt: '2026-01-04T00:00:00.000Z',
+        userIdentity: { pikkuUserId: 'pk_9' },
+      }),
+    ])
+    const { events } = await service.query({ types: ['invoice.view'] })
+    assert.deepEqual(events[0]!.userIdentity, {
+      userId: undefined,
+      orgId: undefined,
+      pikkuUserId: 'pk_9',
+    })
+  })
+
+  test('filters by user', async () => {
+    await seed()
+    const { events } = await service.query({ userIds: ['alice'] })
+    assert.deepEqual(
+      events.map((e) => e.eventId),
+      ['e3', 'e1']
+    )
+  })
+
+  test('filters by type', async () => {
+    await seed()
+    const { events } = await service.query({ types: ['invoice.delete'] })
+    assert.deepEqual(
+      events.map((e) => e.eventId),
+      ['e2']
+    )
+  })
+
+  test('combines filters as a conjunction', async () => {
+    await seed()
+    const { events } = await service.query({
+      userIds: ['alice'],
+      types: ['invoice.update'],
+      orgId: 'org-b',
+    })
+    assert.deepEqual(
+      events.map((e) => e.eventId),
+      ['e3']
+    )
+  })
+
+  test('an empty filter array matches nothing rather than everything', async () => {
+    await seed()
+    const byUser = await service.query({ userIds: [] })
+    assert.deepEqual(byUser.events, [])
+    const byType = await service.query({ types: [] })
+    assert.deepEqual(byType.events, [])
+  })
+
+  test('bounds by occurredAt, `from` inclusive and `to` exclusive', async () => {
+    await seed()
+    const { events } = await service.query({
+      from: '2026-01-02T00:00:00.000Z',
+      to: '2026-01-03T00:00:00.000Z',
+    })
+    assert.deepEqual(
+      events.map((e) => e.eventId),
+      ['e2']
+    )
+  })
+
+  test('pages, reporting the next offset only while more remain', async () => {
+    await seed()
+    const first = await service.query({ limit: 2 })
+    assert.deepEqual(
+      first.events.map((e) => e.eventId),
+      ['e3', 'e2']
+    )
+    assert.equal(first.nextCursor, 2)
+
+    const second = await service.query({ limit: 2, offset: first.nextCursor! })
+    assert.deepEqual(
+      second.events.map((e) => e.eventId),
+      ['e1']
+    )
+    assert.equal(second.nextCursor, null)
+  })
+
+  // Without the audit_id tiebreak the engine may order a same-timestamp batch
+  // differently per query, which drops or repeats rows across a page boundary.
+  test('orders totally when timestamps tie', async () => {
+    const sameTime = '2026-02-01T00:00:00.000Z'
+    await service.write(
+      ['a', 'b', 'c', 'd'].map((id) =>
+        event({ eventId: id, type: 't', occurredAt: sameTime })
+      )
+    )
+    const first = await service.query({ limit: 2 })
+    const second = await service.query({ limit: 2, offset: 2 })
+    const seen = [...first.events, ...second.events].map((e) => e.eventId)
+    assert.deepEqual(seen, ['d', 'c', 'b', 'a'])
+    assert.equal(new Set(seen).size, 4, 'no row may appear on two pages')
+  })
+
+  test('caps an oversized limit', async () => {
+    await service.write(
+      Array.from({ length: 5 }, (_, i) =>
+        event({
+          eventId: `e${i}`,
+          type: 't',
+          occurredAt: `2026-03-0${i + 1}T00:00:00.000Z`,
+        })
+      )
+    )
+    const { events } = await service.query({ limit: 10_000 })
+    assert.equal(events.length, 5, 'the cap must not lose rows below it')
+  })
+
+  test('a malformed data column surfaces rather than dropping the event', async () => {
+    await sql
+      .raw(
+        `INSERT INTO audit (audit_id, occurred_at, type, source, data)
+         VALUES ('bad', '2026-04-01T00:00:00.000Z', 'legacy.write', 'auto', 'not json')`
+      )
+      .execute(db)
+    const { events } = await service.query()
+    assert.equal(events.length, 1)
+    assert.equal(events[0]!.metadata as unknown, 'not json')
+  })
+})
+
+/**
+ * The two connections a project actually hands this service. `CamelCasePlugin`
+ * is on almost every pikku Kysely instance, and it renames result columns on
+ * the way out — `audit_id` arrives as `auditId` — so a service that only reads
+ * the physical names returns a page of undefined-everything against the setup
+ * most projects have.
+ */
+describe('KyselyAuditService against a CamelCasePlugin connection', () => {
+  let camelDb: Kysely<any>
+  let camelService: KyselyAuditService
+
+  beforeEach(async () => {
+    camelDb = new Kysely<any>({
+      dialect: new SqliteDialect({ database: new Database(':memory:') }),
+      plugins: [new CamelCasePlugin()],
+    })
+    await sql.raw(CREATE_AUDIT_TABLE).execute(camelDb)
+    camelService = new KyselyAuditService(camelDb)
+  })
+
+  test('reads back everything it wrote', async () => {
+    await camelService.write([
+      event({
+        eventId: 'e1',
+        type: 'invoice.update',
+        occurredAt: '2026-01-01T00:00:00.000Z',
+        outcome: 'success',
+        functionId: 'cancelInvoice',
+        wireType: 'http',
+        traceId: 'trace-1',
+        userIdentity: { userId: 'alice', orgId: 'org-a' },
+        metadata: { entity: 'invoice' },
+      }),
+    ])
+    const { events } = await camelService.query()
+    assert.equal(events.length, 1)
+    assert.deepEqual(events[0], {
+      eventId: 'e1',
+      occurredAt: '2026-01-01T00:00:00.000Z',
+      type: 'invoice.update',
+      source: 'explicit',
+      outcome: 'success',
+      functionId: 'cancelInvoice',
+      wireType: 'http',
+      traceId: 'trace-1',
+      transactionId: undefined,
+      queryId: undefined,
+      userIdentity: {
+        userId: 'alice',
+        orgId: 'org-a',
+        pikkuUserId: undefined,
+      },
+      metadata: { entity: 'invoice' },
+    })
+  })
+
+  test('still filters and facets by user', async () => {
+    await camelService.write([
+      event({
+        eventId: 'e1',
+        type: 'a',
+        occurredAt: '2026-01-01T00:00:00.000Z',
+        userIdentity: { userId: 'alice' },
+      }),
+      event({
+        eventId: 'e2',
+        type: 'b',
+        occurredAt: '2026-01-02T00:00:00.000Z',
+        userIdentity: { userId: 'bob' },
+      }),
+    ])
+    const { events } = await camelService.query({ userIds: ['bob'] })
+    assert.deepEqual(
+      events.map((e) => e.eventId),
+      ['e2']
+    )
+    const facets = await camelService.facets()
+    assert.deepEqual(facets.userIds, ['alice', 'bob'])
+  })
+})
+
+describe('KyselyAuditService.init', () => {
+  test('creates the audit table on a database that has none', async () => {
+    const fresh = new Kysely<any>({
+      dialect: new SqliteDialect({ database: new Database(':memory:') }),
+      plugins: [new CamelCasePlugin()],
+    })
+    const freshService = new KyselyAuditService(fresh)
+    await freshService.init()
+    await freshService.write([
+      event({ eventId: 'e1', type: 't', occurredAt: '2026-01-01' }),
+    ])
+    const { events } = await freshService.query()
+    assert.deepEqual(
+      events.map((e) => e.eventId),
+      ['e1']
+    )
+  })
+
+  // Two boots against one database, and the second must not wipe the first.
+  test('is idempotent and keeps what is already there', async () => {
+    await service.write([
+      event({ eventId: 'e1', type: 't', occurredAt: '2026-01-01' }),
+    ])
+    await service.init()
+    await service.init()
+    const { events } = await service.query()
+    assert.deepEqual(
+      events.map((e) => e.eventId),
+      ['e1']
+    )
+  })
+})
+
+describe('KyselyAuditService.facets', () => {
+  test('lists the distinct users and types across the whole trail', async () => {
+    await seed()
+    const facets = await service.facets()
+    assert.deepEqual(facets.userIds, ['alice', 'bob'])
+    assert.deepEqual(facets.types, ['invoice.delete', 'invoice.update'])
+  })
+
+  test('omits userless events from the user list', async () => {
+    await service.write([
+      event({ eventId: 'cron', type: 'cleanup.ran', occurredAt: '2026-05-01' }),
+    ])
+    const facets = await service.facets()
+    assert.deepEqual(facets.userIds, [])
+    assert.deepEqual(facets.types, ['cleanup.ran'])
+  })
+})

package/src/kysely-audit-service.ts

@@ -1,9 +1,78 @@
-import type { AuditEvent, AuditEventBatch, AuditService } from '@pikku/core'
+import type {
+  AuditEvent,
+  AuditEventBatch,
+  AuditFacets,
+  AuditQuery,
+  AuditQueryResult,
+  AuditService,
+} from '@pikku/core'
 import type { Kysely } from 'kysely'
+import { ensurePikkuSchema } from './schema/index.js'
+import { auditSchema } from './schema/audit.schema.js'
 
 const jsonOrNull = (v: unknown): string | null =>
   v != null ? JSON.stringify(v) : null
 
+const parseJson = (v: unknown): any => {
+  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: Record<string, any>, name: string): any => {
+  const value = row[name]
+  if (value !== undefined) return value
+  return row[name.replace(/_(\w)/g, (_, char: string) => char.toUpperCase())]
+}
+
+/** Rows are TEXT on every engine, so the shape is whatever the driver returned. */
+const rowToEvent = (row: Record<string, any>): AuditEvent => {
+  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 = (): string =>
@@ -15,14 +84,30 @@ const fallbackId = (): string =>
  *
  * 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 implements AuditService {
+  private initialized = false
+
   constructor(private 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.
+   */
+  public async init(): Promise<void> {
+    if (this.initialized) return
+    await ensurePikkuSchema(this.db, auditSchema)
+    this.initialized = true
+  }
+
   async audit(event: AuditEvent): Promise<void> {
     await this.write([event])
   }
@@ -44,8 +129,9 @@ export class KyselyAuditService implements AuditService {
         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,
@@ -59,4 +145,95 @@ export class KyselyAuditService implements AuditService {
       .onConflict((oc: any) => 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: AuditQuery = {}): Promise<AuditQueryResult> {
+    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 as any).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(): Promise<AuditFacets> {
+    const [users, types] = await Promise.all([
+      (this.db as any)
+        .selectFrom('audit')
+        .select('user_id')
+        .distinct()
+        .where('user_id', 'is not', null)
+        .orderBy('user_id', 'asc')
+        .execute(),
+      (this.db as any)
+        .selectFrom('audit')
+        .select('type')
+        .distinct()
+        .orderBy('type', 'asc')
+        .execute(),
+    ])
+    return {
+      userIds: users.map((r: any) => column(r, 'user_id')),
+      types: types.map((r: any) => 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.
+   */
+  private applyFilters(builder: any, query: AuditQuery): any {
+    // `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: any) => 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
+  }
 }