@pikku/core 0.12.89 → 0.12.91

package/dist/wirings/persona/index.d.ts

@@ -17,4 +17,5 @@ export type { CorePersona, CorePersonas, PersonaAccountMeta, PersonaDefinitions,
  * Lambda deploy would load outright.
  */
 export { HttpPersona, createHttpPersonas, type HttpPersonasConfig, } from '../../services/http-personas.js';
+export { ActorSignIn, OperatorSignIn, establishOperatorSession, IMPERSONATE_USER_ID_HEADER, type PersonaSignIn, type OperatorSignInOptions, type OperatorSessionResult, } from '../../services/persona-sign-in.js';
 export { postScenarioJson, readScenarioHttpResponse, } from '../../services/personas-service.js';

package/dist/wirings/persona/index.js

@@ -13,4 +13,5 @@ export { personaEmail, personaEmails } from './persona-email.js';
  * Lambda deploy would load outright.
  */
 export { HttpPersona, createHttpPersonas, } from '../../services/http-personas.js';
+export { ActorSignIn, OperatorSignIn, establishOperatorSession, IMPERSONATE_USER_ID_HEADER, } from '../../services/persona-sign-in.js';
 export { postScenarioJson, readScenarioHttpResponse, } from '../../services/personas-service.js';

package/dist/wirings/rpc/rpc-runner.js

@@ -270,10 +270,9 @@ export class ContextAwareRPCService {
         };
         if (rpcName.includes(':')) {
             const addonCall = this.resolveAddonFunction(rpcName);
-            if (addonCall === NOT_RESOLVED) {
-                throw new RPCNotFoundError(rpcName);
+            if (addonCall !== NOT_RESOLVED) {
+                return await this.executeAddonFunction(addonCall, data, mergedWire);
             }
-            return this.executeAddonFunction(addonCall, data, mergedWire);
         }
         let resolved;
         try {
@@ -281,8 +280,8 @@ export class ContextAwareRPCService {
         }
         catch (e) {
             if (e instanceof RPCNotFoundError && this.services.deploymentService) {
-                const session = await resolveWireSession(this.wire);
-                return this.services.deploymentService.invoke(rpcName, data, session, this.wire.traceId);
+                const session = await resolveWireSession(mergedWire);
+                return this.services.deploymentService.invoke(rpcName, data, session, mergedWire.traceId);
             }
             throw e;
         }

package/dist/wirings/virtual-user/index.d.ts

@@ -16,11 +16,13 @@
  * {@link VirtualUserTarget}, which in production is an `HttpPersona`
  * signed in as a real user against staging or production.
  */
-export type { ApiCatalogueEntry, IntentSource, VirtualUserDisposition, VirtualUserFinding, VirtualUserRunResult, VirtualUserTarget, } from './virtual-user.types.js';
+export type { ApiCatalogueEntry, IntentRecord, IntentSource, StepRecord, VirtualUserBudget, VirtualUserDisposition, VirtualUserFinding, VirtualUserRunResult, VirtualUserTarget, } from './virtual-user.types.js';
 export { PRODUCTION_DISPOSITION } from './virtual-user.types.js';
 export { runVirtualUser, type RunVirtualUserParams, } from './run-virtual-user.js';
 export { personaScopes, prepareVirtualUserRun, type VirtualUserPreparation, } from './prepare-virtual-user-run.js';
 export type { VirtualUserRunOutcome, VirtualUserRunRecord, VirtualUserRunStart, VirtualUserRunStore, } from './virtual-user-run-store.js';
+export type { VirtualUserScheduleInput, VirtualUserScheduleRecord, VirtualUserScheduleStore, } from './virtual-user-schedule-store.js';
+export { DEFAULT_MAX_INTERVAL_MS, DEFAULT_MIN_INTERVAL_MS, isDue, nextRunAt, STALE_RUN_AFTER_MS, tickVirtualUserSchedules, type VirtualUserTickParams, type VirtualUserTickResult, } from './virtual-user-schedule.js';
 export { DISPOSITIONS, dispositionProfile, type DispositionProfile, type VirtualUserTuning, } from './virtual-user-dispositions.js';
 export { catalogueClassification, catalogueLookup, isReadOnly, reachableCatalogue, unreachableCatalogue, } from './virtual-user-catalogue.js';
 export { type AgentReachability, type ReachableAgent, } from './virtual-user-agents.js';

package/dist/wirings/virtual-user/index.js

@@ -1,6 +1,7 @@
 export { PRODUCTION_DISPOSITION } from './virtual-user.types.js';
 export { runVirtualUser, } from './run-virtual-user.js';
 export { personaScopes, prepareVirtualUserRun, } from './prepare-virtual-user-run.js';
+export { DEFAULT_MAX_INTERVAL_MS, DEFAULT_MIN_INTERVAL_MS, isDue, nextRunAt, STALE_RUN_AFTER_MS, tickVirtualUserSchedules, } from './virtual-user-schedule.js';
 export { DISPOSITIONS, dispositionProfile, } from './virtual-user-dispositions.js';
 export { catalogueClassification, catalogueLookup, isReadOnly, reachableCatalogue, unreachableCatalogue, } from './virtual-user-catalogue.js';
 export { IntentStack, intentsForPersona } from './virtual-user-intents.js';

package/dist/wirings/virtual-user/virtual-user-agents.d.ts

@@ -13,7 +13,6 @@
  */
 /** The part of an agent's meta this needs. */
 export interface AgentReachability {
-    name?: string;
     description?: string;
     scopes?: readonly string[];
     auth?: boolean;
@@ -24,7 +23,13 @@ export interface ReachableAgent {
     description?: string;
 }
 /**
- * The agents to offer, keyed by the name they are declared under.
+ * The agents to offer, named by the key they are registered under.
+ *
+ * That key is the export's own name, which is what `addAgent` stores and what
+ * `resolveAgent` looks up. The `name` an agent declares in its config is a
+ * display label and is frequently something else entirely — offering that one
+ * hands the persona a name the server cannot resolve, and the run dies on a
+ * 500 the moment it takes the offer.
  *
  * Like {@link reachableCatalogue}, this narrows *what is offered* and never
  * what is enforced: the server decides who may talk to what, and an agent

package/dist/wirings/virtual-user/virtual-user-agents.js

@@ -1,6 +1,12 @@
 import { hasScopes } from '../../scopes.js';
 /**
- * The agents to offer, keyed by the name they are declared under.
+ * The agents to offer, named by the key they are registered under.
+ *
+ * That key is the export's own name, which is what `addAgent` stores and what
+ * `resolveAgent` looks up. The `name` an agent declares in its config is a
+ * display label and is frequently something else entirely — offering that one
+ * hands the persona a name the server cannot resolve, and the run dies on a
+ * 500 the moment it takes the offer.
  *
  * Like {@link reachableCatalogue}, this narrows *what is offered* and never
  * what is enforced: the server decides who may talk to what, and an agent
@@ -19,6 +25,6 @@ export const reachableAgents = (agents, scopes) => Object.entries(agents)
     return hasScopes(agent.scopes, scopes);
 })
     .map(([id, agent]) => ({
-    name: agent.name ?? id,
+    name: id,
     ...(agent.description ? { description: agent.description } : {}),
 }));

package/dist/wirings/virtual-user/virtual-user-run-store.d.ts

@@ -1,4 +1,4 @@
-import type { VirtualUserDisposition, VirtualUserFinding, VirtualUserTally } from './virtual-user.types.js';
+import type { IntentRecord, StepRecord, VirtualUserDisposition, VirtualUserFinding, VirtualUserTally } from './virtual-user.types.js';
 /**
  * One recorded run: who ran, what they were told, and what came back.
  *
@@ -34,6 +34,16 @@ export interface VirtualUserRunRecord {
      */
     memory: Record<string, string>;
     findings: VirtualUserFinding[];
+    /**
+     * What the user set out to do and how far each one got, which is the spine a
+     * transcript hangs off — the steps alone are a list of calls with no account
+     * of what they were for.
+     *
+     * Small and bounded, so it rides on the run row rather than in a table of its
+     * own: a run has as many intents as the app has scenarios, and every read of
+     * the run wants them.
+     */
+    intents: IntentRecord[];
     tally: VirtualUserTally | null;
     /** Which budget or stopping rule ended the run. */
     stoppedBy: string | null;
@@ -62,6 +72,16 @@ export interface VirtualUserRunOutcome {
     tally: VirtualUserTally;
     memory: Record<string, string>;
     stoppedBy: string | null;
+    intents: readonly IntentRecord[];
+    /**
+     * Every turn the run took. Kept because a finding is an assertion until you
+     * can see what the user did before it, and because a run that found nothing
+     * is only readable as work through its steps.
+     *
+     * Stored apart from the run — see {@link VirtualUserRunStore.steps} — so
+     * listing runs does not drag a budget's worth of turns along with it.
+     */
+    steps: readonly StepRecord[];
 }
 /**
  * Where runs are kept. Declared here rather than in a database package so the
@@ -87,4 +107,15 @@ export interface VirtualUserRunStore {
         limit?: number;
         offset?: number;
     }): Promise<VirtualUserRunRecord[]>;
+    /**
+     * One run's turns, in the order they happened.
+     *
+     * Its own call rather than a field on the record: a run at a 500-step budget
+     * carries more transcript than every other column put together, and `list`
+     * would pay for it on every row.
+     */
+    steps(runId: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<StepRecord[]>;
 }

package/dist/wirings/virtual-user/virtual-user-schedule-store.d.ts

@@ -0,0 +1,89 @@
+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/dist/wirings/virtual-user/virtual-user-schedule-store.js

@@ -0,0 +1 @@
+export {};

package/dist/wirings/virtual-user/virtual-user-schedule.d.ts

@@ -0,0 +1,71 @@
+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 declare const STALE_RUN_AFTER_MS: number;
+/**
+ * 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 declare const DEFAULT_MIN_INTERVAL_MS: number;
+export declare const DEFAULT_MAX_INTERVAL_MS: number;
+/** Whether a row is the tick's business, for stores that cannot ask in a query. */
+export declare const isDue: (schedule: VirtualUserScheduleRecord, now: Date) => boolean;
+/**
+ * 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 declare const nextRunAt: (schedule: Pick<VirtualUserScheduleRecord, "minIntervalMs" | "maxIntervalMs">, now: Date, random: () => number) => Date;
+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 declare const tickVirtualUserSchedules: ({ schedules, runs, dispatch, now, random, staleAfterMs, }: VirtualUserTickParams) => Promise<VirtualUserTickResult>;

package/dist/wirings/virtual-user/virtual-user-schedule.js

@@ -0,0 +1,101 @@
+/**
+ * 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, now) => 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, now, random) => {
+    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));
+};
+/**
+ * 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, }) => {
+    const result = {
+        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;
+        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/dist/wirings/workflow/pikku-workflow-service.d.ts

@@ -109,8 +109,9 @@ export declare 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 findUndispatchedSteps(_before: Date, _limit: number): Promise<Array<{
         runId: string;

package/dist/wirings/workflow/pikku-workflow-service.js

@@ -266,8 +266,9 @@ export class PikkuWorkflowService {
      * 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.
      */
     async findUndispatchedSteps(_before, _limit) {
         return [];

package/dist/wirings/workflow/scenario-cookie-jar.js

@@ -5,8 +5,17 @@ export const createCookieJar = (apiUrl) => {
         fetch: async (input, init) => {
             const headers = new Headers(init?.headers);
             headers.set('origin', origin);
-            const held = [...jar].map(([name, value]) => `${name}=${value}`);
+            // The caller's own cookie header wins per name: a request that already
+            // carries a session is stating which one it means, and emitting the jar's
+            // copy alongside it sends the same name twice.
             const caller = headers.get('cookie');
+            const named = new Set((caller ?? '')
+                .split(';')
+                .map((pair) => pair.split('=')[0]?.trim())
+                .filter(Boolean));
+            const held = [...jar]
+                .filter(([name]) => !named.has(name))
+                .map(([name, value]) => `${name}=${value}`);
             if (held.length > 0 || caller) {
                 headers.set('cookie', [caller, ...held].filter(Boolean).join('; '));
             }

package/knowledge/decisions/internals/a-virtual-user-cadence-is-a-row-not-a-timer.md

@@ -0,0 +1,66 @@
+---
+type: decision
+title: A virtual user cadence is a row, not a timer
+description: How often a persona runs is stored as a due time per persona and acted on by a tick the project schedules — pikku never starts a timer, and a run never reschedules itself
+tags: virtual-user, storage, scheduling
+---
+
+# A virtual user cadence is a row, not a timer
+
+A run has a budget; a persona has a cadence. The two get confused because both
+answer "how often", and neither answers the other's question: a budget caps one
+outing, and raising it only buys a more tired user. What tells you about a
+product is the same person coming back over a fortnight.
+
+That cadence is one row per persona in `virtualUserSchedule`, holding
+`nextRunAt`. `tickVirtualUserSchedules` acts on whichever rows are due. There is
+no timer, no interval, and no in-memory loop.
+
+**Not a timer**, because a process holding the next run in its own heap forgets
+it on the next deploy, and the persona silently stops — with nothing anywhere
+saying it used to run. The row survives restarts, and any instance can act on
+it.
+
+**Not reschedule-on-completion**, which is the tempting shape: finish a run,
+draw a delay, schedule the next. It has exactly one failure mode and it is
+fatal — a crash between the two ends the persona forever, and the evidence is an
+absence. A due time written down before the run starts cannot be lost by the run
+failing.
+
+**Not a scaffolded cron.** The tick is generated as an ordinary function and
+wired by nobody. A `wireScheduler` emitted by codegen would start spending an
+application's model budget the moment somebody ran `pikku all`, on a host that
+may not even run schedulers. One line in the project turns it on:
+
+```ts
+wireScheduler({ name: 'virtualUsers', schedule: '0 * * * *', func: tickVirtualUserSchedules })
+```
+
+Tick resolution bounds how *late* a due persona is, never how often it runs — a
+persona due at 09:07 under an hourly tick starts at 10:00. Running the tick more
+often costs one indexed query and changes no cadence.
+
+Three rules make a tick safe to run at any resolution, from any number of
+instances:
+
+- **The due time is written before the run is dispatched**, so a tick that dies
+  halfway cannot leave the row due for the next one to pick up again. A dispatch
+  that throws therefore waits a full interval, which is the right way round: a
+  persona failing to start should not be retried every minute for a week.
+- **A persona whose previous run is still `running` is skipped, not queued.**
+  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.
+- **A run still `running` after `STALE_RUN_AFTER_MS` is failed and the persona
+  runs again.** This is where the stranded-record cost of
+  [a virtual user run being neither a workflow nor a queued job](a-virtual-user-run-is-not-a-workflow-and-not-a-queued-job.md)
+  gets paid: without it, one restart mid-run would block that persona's schedule
+  permanently.
+
+The interval is a range (`minIntervalMs`, `maxIntervalMs`), drawn per run. A
+user who arrives at exactly 09:00 every day exercises one cache state and one
+cron neighbourhood; a real one does not keep an appointment.
+
+**What this rules out:** a `setTimeout` or interval anywhere in the run path;
+the engine scheduling its own next run; a scaffolded scheduled task; a queue
+holding the next run; and a cadence that lives only in a config file, which
+cannot record when the persona last actually went.

package/knowledge/decisions/internals/a-virtual-user-run-is-not-a-workflow-and-not-a-queued-job.md

@@ -37,9 +37,14 @@ left at `running` is neither.
 
 The cost is real and is stated on the type: **a restart mid-run strands a record
 at `running` with nothing left to finish it.** A run older than its budget
-window and still `running` is dead, not working — that is a read-side rule, and
-it is cheaper than the two dependencies avoided. Nothing retries; a stranded run
-is started again, with its seed if the caller wants the same exploration.
+window and still `running` is dead, not working — a read-side rule, and cheaper
+than the two dependencies avoided. Nothing retries; a stranded run is started
+again, with its seed if the caller wants the same exploration.
+
+Where that rule is actually applied is
+[the schedule tick](a-virtual-user-cadence-is-a-row-not-a-timer.md), which has
+to: a record stuck at `running` would otherwise block its persona's cadence
+forever.
 
 **What this rules out:** dispatching the run through `startWorkflow`; a
 scaffolded queue worker; awaiting the engine inside the request (a run takes

package/knowledge/decisions/internals/index.md

@@ -16,6 +16,7 @@ caller is entitled to assume.
 - [A scenario step's prose template is offered to a virtual user unfilled](a-scenario-step-template-is-offered-unfilled.md) — A reporter fills placeholders from a run that happened; there is no run yet, and the filled form would answer the question the user is there to answer
 - [A secret that fails to decrypt fails the whole read](a-secret-that-fails-to-decrypt-fails-the-whole-read.md) — getSecrets throws naming the key and its key_version rather than omitting the row, because a silent omission surfaces as an unrelated failure much later
 - [A virtual user decides whether to trust its notes once per turn, by one roll](a-virtual-user-decides-whether-to-trust-memory-once-per-turn.md) — The difference between the stale, newcomer and auditor dispositions is expressed as a single probability rather than as prose in each prompt
+- [A virtual user cadence is a row, not a timer](a-virtual-user-cadence-is-a-row-not-a-timer.md) — how often a persona runs is stored as a due time per persona and acted on by a tick the project schedules — pikku never starts a timer, and a run never reschedules itself
 - [A virtual user run is not a workflow and not a queued job](a-virtual-user-run-is-not-a-workflow-and-not-a-queued-job.md) — runVirtualUser writes its record, dispatches the run without awaiting it, and returns the id — because an exploratory run has nothing to replay and the record already carries what a queue would be holding
 - [A wall-clock threshold is a load test in disguise](a-wall-clock-threshold-is-a-load-test-in-disguise.md) — The KEK derivation test asserted a fixed 50ms budget for work that took 10ms, which went red about one run in five once the suite was large enough to compete for the machine
 - [A workflow's wire is built from the run record, not from the RPC service](a-workflow-wire-is-built-from-the-run-not-from-the-rpc-service.md) — The RPC service exposes no wire, so every rpcService.wire read was undefined; the run record is the only thing that carries the caller across a step boundary

package/knowledge/decisions/internals/the-ecosystem-entry-point-carries-the-adapter-surface.md

@@ -32,12 +32,13 @@ The stability distinction the split was built to express is now carried by
 exports. Moving a symbol across an area boundary is still a visible diff; it
 just no longer requires a parallel tree of re-export files to be visible.
 
-Two modules survive at the old specifiers and are not entry points:
-`bootstrap-compat/root.ts` and `bootstrap-compat/ecosystem.ts` exist because
-`packages/cli` is generated by the published CLI pinned in its `build.sh`, which
-still emits `@pikku/core/ecosystem` and a bare `@pikku/core`. A test pins their
-exact contents so neither can grow, and both go when the pin moves to a CLI
-released from this branch.
+One module survives at an old specifier and is not an entry point:
+`bootstrap-compat/root.ts` exists because `packages/cli` is generated by the
+published CLI pinned in its `build.sh`, which still emits a bare `@pikku/core`.
+The matching `bootstrap-compat/ecosystem.ts` has already gone, along with every
+`@pikku/core/ecosystem` import in the repo — a guard test now fails if one comes
+back. A test pins the root shim's exact contents so it cannot grow, and it goes
+when the pin moves to a CLI released from this branch.
 
 **What this rules out:** re-introducing any specifier that re-exports another
 subpath's names. A curated facade over a module that is already published is the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.89",
+  "version": "0.12.91",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/src/app-leaf-surface.test.ts

@@ -28,8 +28,8 @@ const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '../../..')
 /**
  * Membership is discovered, not listed: every directory holding a
  * `pikku.config.json` is a Pikku project, so a project added later arrives
- * guarded rather than invisible. Listing them by hand is how the ecosystem
- * guard reported green on four packages it had never scanned.
+ * guarded rather than invisible. Listing them by hand is how an earlier
+ * version of this guard reported green on four packages it had never scanned.
  */
 const skipped = new Set([
   'node_modules',