@pikku/core 0.12.89 → 0.12.90

package/src/wirings/virtual-user/virtual-user-schedule-store.ts

@@ -0,0 +1,93 @@
+import type {
+  VirtualUserBudget,
+  VirtualUserDisposition,
+} from './virtual-user.types.js'
+
+/**
+ * One persona's standing instruction to keep using the app.
+ *
+ * A virtual user that runs once tells you about one afternoon. What an app
+ * actually wants to know is what a persona hits over a fortnight, and that is
+ * a cadence, not a longer run — a budget already caps how far a single run
+ * goes, and raising it only buys a more tired user.
+ *
+ * The row is the schedule. There is deliberately no timer, interval or
+ * in-memory loop anywhere near it: a process that holds the next run in its own
+ * heap forgets it on the next deploy, and a persona silently stops. Something
+ * outside asks which rows are due; the answer survives restarts because it is
+ * written down.
+ */
+export interface VirtualUserScheduleRecord {
+  persona: string
+  /**
+   * Off by default. A schedule that ran the moment it was written would start
+   * spending an app's model budget as a side effect of a migration.
+   */
+  enabled: boolean
+  disposition: VirtualUserDisposition
+  goals: string[]
+  budget: VirtualUserBudget | null
+  /**
+   * The gap to the next run is drawn between these, not fixed. A persona that
+   * appears at exactly 09:00 every day exercises one cache state and one cron
+   * neighbourhood; a real one does not keep an appointment.
+   */
+  minIntervalMs: number
+  maxIntervalMs: number
+  /** When this persona is next allowed to run. The whole schedule, in one field. */
+  nextRunAt: Date
+  lastRunId: string | null
+  lastRunAt: Date | null
+}
+
+/** A partial write — anything left out keeps whatever the row already had. */
+export interface VirtualUserScheduleInput {
+  persona: string
+  enabled?: boolean
+  disposition?: VirtualUserDisposition
+  goals?: readonly string[]
+  budget?: VirtualUserBudget | null
+  minIntervalMs?: number
+  maxIntervalMs?: number
+  nextRunAt?: Date
+}
+
+/**
+ * Where cadences are kept, alongside {@link VirtualUserRunStore} and separate
+ * from it: a host can want the history of runs it started by hand without
+ * wanting unattended ones, and wiring nothing is how it says so.
+ *
+ * SECURITY: writing a row here spends money on every future tick, without a
+ * caller present to see it happen. The scaffold gates writes behind a scope of
+ * their own for that reason — reading what the virtual users found is a much
+ * smaller permission than deciding they should keep going.
+ */
+export interface VirtualUserScheduleStore {
+  /** Creates or updates one persona's cadence. Returns the row as it now stands. */
+  set(schedule: VirtualUserScheduleInput): Promise<VirtualUserScheduleRecord>
+  get(persona: string): Promise<VirtualUserScheduleRecord | null>
+  list(): Promise<VirtualUserScheduleRecord[]>
+  /** Enabled rows whose `nextRunAt` has passed. */
+  due(now: Date): Promise<VirtualUserScheduleRecord[]>
+  /**
+   * Pushes the persona's next run out, and records which run this was.
+   *
+   * Called *before* the run is dispatched, so a tick that dies halfway does not
+   * leave a row due and get re-dispatched by the next one. The cost is that a
+   * dispatch which throws waits a full interval rather than retrying, which is
+   * the right way round: a persona that is failing to start should not be
+   * retried every minute for a week.
+   *
+   * `from` is the `nextRunAt` the caller read, and the write must match it to
+   * land — the claim is how a tick wins the persona, not just how it records
+   * winning. Two processes on the same cron read the same due row, and without
+   * the compare-and-set both would dispatch: the same user acting twice over,
+   * at twice the budget, producing findings neither run can reproduce. The
+   * loser is told `false` and leaves the persona to whoever got there first.
+   */
+  claim(
+    persona: string,
+    claim: { from: Date; nextRunAt: Date; runId: string | null; at: Date }
+  ): Promise<boolean>
+  remove(persona: string): Promise<void>
+}

package/src/wirings/virtual-user/virtual-user-schedule.test.ts

@@ -0,0 +1,280 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import type {
+  VirtualUserRunRecord,
+  VirtualUserRunStore,
+} from './virtual-user-run-store.js'
+import type {
+  VirtualUserScheduleRecord,
+  VirtualUserScheduleStore,
+} from './virtual-user-schedule-store.js'
+import {
+  isDue,
+  nextRunAt,
+  STALE_RUN_AFTER_MS,
+  tickVirtualUserSchedules,
+} from './virtual-user-schedule.js'
+
+const HOUR = 60 * 60 * 1000
+const NOW = new Date('2026-01-01T12:00:00.000Z')
+
+const schedule = (
+  over: Partial<VirtualUserScheduleRecord> = {}
+): VirtualUserScheduleRecord => ({
+  persona: 'guest',
+  enabled: true,
+  disposition: 'realistic',
+  goals: [],
+  budget: null,
+  minIntervalMs: HOUR,
+  maxIntervalMs: 3 * HOUR,
+  nextRunAt: new Date(NOW.getTime() - 1000),
+  lastRunId: null,
+  lastRunAt: null,
+  ...over,
+})
+
+const run = (
+  over: Partial<VirtualUserRunRecord> = {}
+): VirtualUserRunRecord => ({
+  runId: 'run-1',
+  persona: 'guest',
+  disposition: 'realistic',
+  seed: 1,
+  status: 'completed',
+  goals: [],
+  memory: {},
+  findings: [],
+  intents: [],
+  tally: null,
+  stoppedBy: null,
+  error: null,
+  startedBy: null,
+  createdAt: NOW,
+  finishedAt: null,
+  ...over,
+})
+
+const stores = (
+  schedules: VirtualUserScheduleRecord[],
+  runs: VirtualUserRunRecord[]
+) => {
+  const claims: {
+    persona: string
+    from: Date
+    nextRunAt: Date
+    runId: string | null
+  }[] = []
+  const failed: { runId: string; error: string }[] = []
+  const scheduleStore = {
+    // Copies, as every real store hands back: a caller holding the row object
+    // itself would never see the value it read go stale underneath it.
+    due: async (now: Date) =>
+      schedules.filter((s) => isDue(s, now)).map((s) => ({ ...s })),
+    // The row is the lock, so the fake enforces the same compare-and-set the
+    // stores do: a claim lands only while the row still holds what was read.
+    claim: async (persona, claim) => {
+      const row = schedules.find((s) => s.persona === persona)
+      if (!row || row.nextRunAt.getTime() !== claim.from.getTime()) {
+        return false
+      }
+      row.nextRunAt = claim.nextRunAt
+      if (claim.runId) {
+        row.lastRunId = claim.runId
+        row.lastRunAt = claim.at
+      }
+      claims.push({ persona, ...claim })
+      return true
+    },
+  } as unknown as VirtualUserScheduleStore
+  const runStore = {
+    list: async ({ persona } = {}) =>
+      runs.filter((r) => !persona || r.persona === persona),
+    fail: async (runId: string, error: string) => {
+      failed.push({ runId, error })
+    },
+  } as unknown as VirtualUserRunStore
+  return { scheduleStore, runStore, claims, failed }
+}
+
+describe('virtual user schedule', () => {
+  test('a disabled persona is never due, however overdue it looks', () => {
+    const row = schedule({
+      enabled: false,
+      nextRunAt: new Date(NOW.getTime() - 1000 * HOUR),
+    })
+    assert.equal(isDue(row, NOW), false)
+  })
+
+  test('the next run lands somewhere inside the persona interval, not on the hour', () => {
+    const row = schedule({ minIntervalMs: HOUR, maxIntervalMs: 5 * HOUR })
+    const draws = [0, 0.25, 0.5, 0.99].map(
+      (value) => nextRunAt(row, NOW, () => value).getTime() - NOW.getTime()
+    )
+    for (const gap of draws) {
+      assert.ok(gap >= HOUR && gap <= 5 * HOUR, `outside the interval: ${gap}`)
+    }
+    assert.equal(new Set(draws).size, draws.length)
+  })
+
+  test('a fixed cadence is expressed by asking for the same bound twice', () => {
+    const row = schedule({ minIntervalMs: HOUR, maxIntervalMs: HOUR })
+    assert.equal(nextRunAt(row, NOW, () => 0.7).getTime() - NOW.getTime(), HOUR)
+  })
+
+  test('bounds the wrong way round read as a range rather than a negative gap', () => {
+    const row = schedule({ minIntervalMs: 5 * HOUR, maxIntervalMs: HOUR })
+    const gap = nextRunAt(row, NOW, () => 0).getTime() - NOW.getTime()
+    assert.equal(gap, HOUR)
+  })
+
+  test('a due persona is dispatched and pushed out before the run starts', async () => {
+    const { scheduleStore, runStore, claims } = stores([schedule()], [])
+    const order: string[] = []
+    const result = await tickVirtualUserSchedules({
+      schedules: {
+        ...scheduleStore,
+        claim: async (persona, claim) => {
+          order.push('claim')
+          return await scheduleStore.claim(persona, claim)
+        },
+      } as VirtualUserScheduleStore,
+      runs: runStore,
+      now: NOW,
+      random: () => 0.5,
+      dispatch: async () => {
+        order.push('dispatch')
+        return 'run-new'
+      },
+    })
+
+    assert.deepEqual(result.dispatched, [
+      { persona: 'guest', runId: 'run-new' },
+    ])
+    assert.deepEqual(order, ['claim', 'dispatch', 'claim'])
+    assert.ok(claims[0]!.nextRunAt.getTime() > NOW.getTime())
+    assert.equal(claims.at(-1)!.runId, 'run-new')
+  })
+
+  test('a persona already acting is left alone rather than doubled up', async () => {
+    const { scheduleStore, runStore, claims } = stores(
+      [schedule()],
+      [run({ status: 'running', createdAt: new Date(NOW.getTime() - 60_000) })]
+    )
+    let dispatched = 0
+    const result = await tickVirtualUserSchedules({
+      schedules: scheduleStore,
+      runs: runStore,
+      now: NOW,
+      dispatch: async () => {
+        dispatched++
+        return 'run-new'
+      },
+    })
+
+    assert.equal(dispatched, 0)
+    assert.deepEqual(result.skipped, [
+      { persona: 'guest', reason: 'in-flight' },
+    ])
+    assert.deepEqual(claims, [])
+  })
+
+  test('a run stranded by a restart is failed, not waited on forever', async () => {
+    const { scheduleStore, runStore, failed } = stores(
+      [schedule()],
+      [
+        run({
+          status: 'running',
+          createdAt: new Date(NOW.getTime() - STALE_RUN_AFTER_MS - 1),
+        }),
+      ]
+    )
+    const result = await tickVirtualUserSchedules({
+      schedules: scheduleStore,
+      runs: runStore,
+      now: NOW,
+      dispatch: async () => 'run-new',
+    })
+
+    assert.deepEqual(result.reaped, ['run-1'])
+    assert.equal(failed.length, 1)
+    assert.match(failed[0]!.error, /still running/)
+    assert.deepEqual(result.dispatched, [
+      { persona: 'guest', runId: 'run-new' },
+    ])
+  })
+
+  test('a persona that will not start waits its interval instead of spinning', async () => {
+    const { scheduleStore, runStore, claims } = stores([schedule()], [])
+    const result = await tickVirtualUserSchedules({
+      schedules: scheduleStore,
+      runs: runStore,
+      now: NOW,
+      dispatch: async () => {
+        throw new Error('no target')
+      },
+    })
+
+    assert.deepEqual(result.dispatched, [])
+    assert.deepEqual(result.skipped, [
+      { persona: 'guest', reason: 'dispatch-failed' },
+    ])
+    assert.equal(claims.length, 1)
+    assert.ok(claims[0]!.nextRunAt.getTime() >= NOW.getTime() + HOUR)
+  })
+
+  test('two ticks racing over one persona produce a single run', async () => {
+    const row = schedule()
+    const { scheduleStore, runStore } = stores([row], [])
+    const dispatched: string[] = []
+    const tick = () =>
+      tickVirtualUserSchedules({
+        schedules: scheduleStore,
+        runs: runStore,
+        now: NOW,
+        random: () => 0.5,
+        dispatch: async ({ persona }) => {
+          const runId = `run-${dispatched.length + 1}`
+          dispatched.push(persona)
+          return runId
+        },
+      })
+
+    // Both read the row while it is still due — the state two cron processes
+    // are in the moment before either of them writes.
+    const [first, second] = await Promise.all([tick(), tick()])
+
+    assert.equal(dispatched.length, 1)
+    const [won, lost] =
+      first.dispatched.length > 0 ? [first, second] : [second, first]
+    assert.equal(won.dispatched.length, 1)
+    assert.deepEqual(lost.dispatched, [])
+    assert.deepEqual(lost.skipped, [
+      { persona: 'guest', reason: 'claimed-elsewhere' },
+    ])
+  })
+
+  test('one persona failing does not stop the others from running', async () => {
+    const { scheduleStore, runStore } = stores(
+      [schedule({ persona: 'guest' }), schedule({ persona: 'admin' })],
+      []
+    )
+    const result = await tickVirtualUserSchedules({
+      schedules: scheduleStore,
+      runs: runStore,
+      now: NOW,
+      dispatch: async ({ persona }) => {
+        if (persona === 'guest') throw new Error('no target')
+        return 'run-admin'
+      },
+    })
+
+    assert.deepEqual(result.dispatched, [
+      { persona: 'admin', runId: 'run-admin' },
+    ])
+    assert.deepEqual(result.skipped, [
+      { persona: 'guest', reason: 'dispatch-failed' },
+    ])
+  })
+})

package/src/wirings/virtual-user/virtual-user-schedule.ts

@@ -0,0 +1,156 @@
+import type { VirtualUserRunStore } from './virtual-user-run-store.js'
+import type {
+  VirtualUserScheduleRecord,
+  VirtualUserScheduleStore,
+} from './virtual-user-schedule-store.js'
+
+/**
+ * How long a run may sit at `running` before it is read as dead rather than
+ * busy.
+ *
+ * A run holds no process across a restart — see {@link VirtualUserRunRecord} —
+ * so a deploy mid-run strands the record, and a stranded record would block its
+ * persona's schedule for good. Twice the longest duration budget anyone sets in
+ * practice, because the failure this guards against is cheap to recover from
+ * and expensive to trigger early: reaping a run that was still working loses
+ * its findings.
+ */
+export const STALE_RUN_AFTER_MS = 2 * 60 * 60 * 1000
+
+/**
+ * The cadence a schedule gets when it is written without one: roughly a run a
+ * day, at an hour nobody can predict.
+ *
+ * Sparse on purpose. Every tick spends model budget with no caller present to
+ * notice, so the default is the one an app can leave switched on and forget,
+ * not the one that finds the most.
+ */
+export const DEFAULT_MIN_INTERVAL_MS = 6 * 60 * 60 * 1000
+export const DEFAULT_MAX_INTERVAL_MS = 24 * 60 * 60 * 1000
+
+/** Whether a row is the tick's business, for stores that cannot ask in a query. */
+export const isDue = (schedule: VirtualUserScheduleRecord, now: Date) =>
+  schedule.enabled && schedule.nextRunAt.getTime() <= now.getTime()
+
+/**
+ * When this persona should next appear, drawn from its own interval.
+ *
+ * Uniform between the two bounds. Reversed bounds are read as a range rather
+ * than rejected, because a schedule is configuration and a swapped pair is a
+ * typo, not an attack.
+ */
+export const nextRunAt = (
+  schedule: Pick<VirtualUserScheduleRecord, 'minIntervalMs' | 'maxIntervalMs'>,
+  now: Date,
+  random: () => number
+) => {
+  const low = Math.max(
+    0,
+    Math.min(schedule.minIntervalMs, schedule.maxIntervalMs)
+  )
+  const high = Math.max(
+    0,
+    Math.max(schedule.minIntervalMs, schedule.maxIntervalMs)
+  )
+  return new Date(now.getTime() + low + random() * (high - low))
+}
+
+export type VirtualUserSkipReason =
+  'in-flight' | 'dispatch-failed' | 'claimed-elsewhere'
+
+export interface VirtualUserTickResult {
+  dispatched: { persona: string; runId: string }[]
+  skipped: { persona: string; reason: VirtualUserSkipReason }[]
+  /** Runs found stranded at `running` and marked failed. */
+  reaped: string[]
+}
+
+export interface VirtualUserTickParams {
+  schedules: VirtualUserScheduleStore
+  runs: VirtualUserRunStore
+  /** Starts one run and answers with its id. Nothing here knows how. */
+  dispatch: (schedule: VirtualUserScheduleRecord) => Promise<string>
+  now?: Date
+  random?: () => number
+  staleAfterMs?: number
+}
+
+/**
+ * Acts on whichever personas are due, once.
+ *
+ * The whole cadence lives in this one call, so what schedules it is the host's
+ * choice — a cron wiring, a platform scheduler, or a person clicking a button.
+ * Pikku does not start a timer on an app's behalf; a scaffold that did would
+ * begin spending model budget the moment a project ran `pikku all`.
+ *
+ * A persona is skipped, not queued, while its previous run is still going. Two
+ * copies of the same user acting at once is not a heavier test, it is a
+ * different one, and every finding it produces is unreproducible. Two ticks
+ * running at once are held to the same rule by the claim, which only lands for
+ * whichever of them still sees the `nextRunAt` it read.
+ */
+export const tickVirtualUserSchedules = async ({
+  schedules,
+  runs,
+  dispatch,
+  now = new Date(),
+  random = Math.random,
+  staleAfterMs = STALE_RUN_AFTER_MS,
+}: VirtualUserTickParams): Promise<VirtualUserTickResult> => {
+  const result: VirtualUserTickResult = {
+    dispatched: [],
+    skipped: [],
+    reaped: [],
+  }
+
+  for (const schedule of await schedules.due(now)) {
+    const [latest] = await runs.list({ persona: schedule.persona, limit: 1 })
+    if (latest?.status === 'running') {
+      if (now.getTime() - latest.createdAt.getTime() < staleAfterMs) {
+        result.skipped.push({ persona: schedule.persona, reason: 'in-flight' })
+        continue
+      }
+      await runs.fail(
+        latest.runId,
+        `Abandoned: still running ${Math.round((now.getTime() - latest.createdAt.getTime()) / 60000)}m after it started, which is longer than any budget allows.`
+      )
+      result.reaped.push(latest.runId)
+    }
+
+    const due = nextRunAt(schedule, now, random)
+    const acquired = await schedules.claim(schedule.persona, {
+      from: schedule.nextRunAt,
+      nextRunAt: due,
+      runId: null,
+      at: now,
+    })
+    if (!acquired) {
+      result.skipped.push({
+        persona: schedule.persona,
+        reason: 'claimed-elsewhere',
+      })
+      continue
+    }
+
+    let runId: string
+    try {
+      runId = await dispatch(schedule)
+    } catch {
+      result.skipped.push({
+        persona: schedule.persona,
+        reason: 'dispatch-failed',
+      })
+      continue
+    }
+
+    await schedules.claim(schedule.persona, {
+      from: due,
+      nextRunAt: due,
+      runId,
+      at: now,
+    })
+    result.dispatched.push({ persona: schedule.persona, runId })
+  }
+
+  return result
+}

package/src/wirings/workflow/pikku-workflow-service.ts

@@ -644,8 +644,9 @@ export abstract class PikkuWorkflowService implements WorkflowService {
    * overriding this, or no concurrency for one to exclude: the relay makes
    * duplicate dispatch routine, and the claim is what keeps a duplicate from
    * becoming a second execution. Every `@pikku/kysely` dialect qualifies on its
-   * status-guarded claim, `in-memory` on being inline and single-process;
-   * `mongodb` still qualifies on neither.
+   * status-guarded claim, `mongodb` on the same claim expressed as a
+   * single-document update, `in-memory` on being inline and single-process —
+   * none of them overrides this yet.
    */
   protected async findUndispatchedSteps(
     _before: Date,