@pikku/core 0.12.79 → 0.12.82

package/dist/wirings/workflow/workflow-queue-routing.js

@@ -0,0 +1,38 @@
+import { getSingletonServices, pikkuState } from '../../pikku-state.js';
+import { getDurationInMilliseconds } from '../../time-utils.js';
+import { DEFAULT_STEP_RETRIES } from './workflow-constants.js';
+const toKebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+export const resolveWorkflowConfig = () => {
+    const workflow = getSingletonServices().config?.workflow;
+    return {
+        retries: workflow?.retries ?? DEFAULT_STEP_RETRIES,
+        retryDelay: workflow?.retryDelay ?? 0,
+        orchestratorQueueName: workflow?.orchestratorQueueName ?? 'pikku-workflow-orchestrator',
+        stepWorkerQueueName: workflow?.stepWorkerQueueName ?? 'pikku-workflow-step-worker',
+        sleeperRPCName: workflow?.sleeperRPCName ?? 'pikkuWorkflowSleeper',
+    };
+};
+/**
+ * Falls back to the shared queue whenever the dedicated one was not generated
+ * into queue meta, so a workflow added without a rebuild still runs.
+ */
+const dedicatedQueueName = (prefix, name, strategy, fallback) => {
+    if (!name || strategy === 'shared-groups') {
+        return fallback;
+    }
+    const dedicated = `${prefix}${toKebab(name)}`;
+    return pikkuState(null, 'queue', 'meta')[dedicated] ? dedicated : fallback;
+};
+export const orchestratorQueueName = (strategy, workflowName) => dedicatedQueueName('wf-orchestrator-', workflowName, strategy, resolveWorkflowConfig().orchestratorQueueName);
+export const stepWorkerQueueName = (strategy, rpcName) => dedicatedQueueName('wf-step-', rpcName, strategy, resolveWorkflowConfig().stepWorkerQueueName);
+export const jobGroupFor = (strategy, id) => id && strategy === 'shared-groups' ? { id, tier: id } : undefined;
+export const stepJobOptions = (stepOptions) => {
+    const retries = stepOptions?.retries ?? DEFAULT_STEP_RETRIES;
+    const retryDelay = stepOptions?.retryDelay;
+    const backoff = retryDelay !== undefined && retryDelay !== 'exponential'
+        ? { type: 'fixed', delay: getDurationInMilliseconds(retryDelay) }
+        : retries > 0 || retryDelay === 'exponential'
+            ? 'exponential'
+            : undefined;
+    return { attempts: retries + 1, ...(backoff ? { backoff } : {}) };
+};

package/dist/wirings/workflow/workflow-queue-wiring.d.ts

@@ -0,0 +1,20 @@
+import type { GroupConcurrencyConfig } from '../queue/queue.types.js';
+import type { Logger } from '../../services/logger.js';
+import type { WorkflowQueueStrategy } from './workflow-queue-routing.js';
+export type WorkflowQueueWiringOptions = {
+    strategy: WorkflowQueueStrategy;
+    concurrency: number;
+    groupConcurrency: number | GroupConcurrencyConfig;
+    /**
+     * Resolved only when there is something to warn about: reading the logger
+     * throws while singleton services are uninitialized, and wiring queues before
+     * that point is legitimate.
+     */
+    getLogger: () => Logger | undefined;
+};
+/**
+ * Registers the orchestrator, step-worker and sleeper functions and binds them
+ * to their queues. Idempotent: a queue already carrying a registered function
+ * is left alone.
+ */
+export declare const wireWorkflowQueueWorkers: ({ strategy, concurrency, groupConcurrency, getLogger, }: WorkflowQueueWiringOptions) => void;

package/dist/wirings/workflow/workflow-queue-wiring.js

@@ -0,0 +1,79 @@
+import { addFunction } from '../../function/function-runner.js';
+import { pikkuState } from '../../pikku-state.js';
+import { wireQueueWorker } from '../queue/queue-runner.js';
+import { pikkuWorkflowOrchestratorFunc, pikkuWorkflowSleeperFunc, pikkuWorkflowWorkerFunc, } from './workflow-queue-workers.js';
+const ORCHESTRATOR_QUEUE_PREFIX = 'wf-orchestrator-';
+const STEP_QUEUE_PREFIX = 'wf-step-';
+const helperFunctionMeta = (funcId) => ({
+    pikkuFuncId: funcId,
+    sessionless: true,
+    functionType: 'helper',
+    inputSchemaName: null,
+    outputSchemaName: null,
+});
+/**
+ * Registers the orchestrator, step-worker and sleeper functions and binds them
+ * to their queues. Idempotent: a queue already carrying a registered function
+ * is left alone.
+ */
+export const wireWorkflowQueueWorkers = ({ strategy, concurrency, groupConcurrency, getLogger, }) => {
+    const functions = pikkuState(null, 'function', 'functions');
+    const functionsMeta = pikkuState(null, 'function', 'meta');
+    const queueMeta = pikkuState(null, 'queue', 'meta');
+    const registerWorkflowFunc = (funcId, func, queueName, config) => {
+        if (functions.has(funcId))
+            return;
+        addFunction(funcId, func);
+        if (!queueMeta[queueName]) {
+            queueMeta[queueName] = { pikkuFuncId: funcId, name: queueName };
+        }
+        wireQueueWorker({ name: queueName, func, config });
+        if (!functionsMeta[funcId]) {
+            functionsMeta[funcId] = helperFunctionMeta(funcId);
+        }
+    };
+    const sharedGroups = strategy === 'shared-groups';
+    const sharedQueueConfig = sharedGroups
+        ? { batchSize: concurrency, groupConcurrency }
+        : undefined;
+    registerWorkflowFunc('pikkuWorkflowOrchestrator', { func: pikkuWorkflowOrchestratorFunc }, 'pikku-workflow-orchestrator', sharedQueueConfig);
+    registerWorkflowFunc('pikkuWorkflowStepWorker', { func: pikkuWorkflowWorkerFunc }, 'pikku-workflow-step-worker', sharedQueueConfig);
+    const registerDedicatedQueues = (meta) => {
+        for (const [queueName, entry] of Object.entries(meta)) {
+            if (functions.has(entry.pikkuFuncId))
+                continue;
+            if (queueName.startsWith(ORCHESTRATOR_QUEUE_PREFIX)) {
+                registerWorkflowFunc(entry.pikkuFuncId, { func: pikkuWorkflowOrchestratorFunc }, queueName);
+            }
+            else if (queueName.startsWith(STEP_QUEUE_PREFIX)) {
+                registerWorkflowFunc(entry.pikkuFuncId, { func: pikkuWorkflowWorkerFunc }, queueName);
+            }
+        }
+    };
+    if (!sharedGroups) {
+        registerDedicatedQueues(pikkuState(null, 'queue', 'meta'));
+        const addons = pikkuState(null, 'addons', 'packages');
+        for (const [, addon] of addons ?? []) {
+            const addonQueueMeta = pikkuState(addon.package, 'queue', 'meta');
+            if (addonQueueMeta) {
+                registerDedicatedQueues(addonQueueMeta);
+            }
+        }
+    }
+    warnOnMissingDedicatedQueues(queueMeta, getLogger);
+    if (!functions.has('pikkuWorkflowSleeper')) {
+        addFunction('pikkuWorkflowSleeper', { func: pikkuWorkflowSleeperFunc });
+    }
+    if (!functionsMeta.pikkuWorkflowSleeper) {
+        functionsMeta.pikkuWorkflowSleeper = helperFunctionMeta('pikkuWorkflowSleeper');
+    }
+};
+const warnOnMissingDedicatedQueues = (queueMeta, getLogger) => {
+    const workflowCount = Object.keys(pikkuState(null, 'workflows', 'meta') ?? {}).length;
+    const dedicatedQueues = Object.keys(queueMeta).filter((name) => name.startsWith(ORCHESTRATOR_QUEUE_PREFIX)).length;
+    if (workflowCount > 0 && dedicatedQueues === 0) {
+        getLogger()?.warn?.(`[pikku] ${workflowCount} workflow(s) registered but no per-workflow orchestrator queues were found in queue meta. ` +
+            `All workflows will share a single orchestrator queue, where one slow step blocks every other workflow behind it. ` +
+            `Check that the generated bootstrap imports the queue-workers meta (pikku-queue-workers-wirings-meta.gen.js).`);
+    }
+};

package/dist/wirings/workflow/workflow-recovery.d.ts

@@ -0,0 +1,68 @@
+import type { Logger } from '../../services/logger.js';
+/**
+ * Per-process, advisory record of when a run may next be re-dispatched.
+ *
+ * Keyed by run rather than by step because the run is the unit of re-drive:
+ * `resumeWorkflow` replays the whole run and re-dispatches every step still
+ * owed a job, so holding off a single step while resuming its run would
+ * suppress nothing.
+ *
+ * Losing this on restart costs extra dispatches, never correctness.
+ */
+export declare class RedispatchBackoff {
+    private readonly eligibleAt;
+    private readonly delays;
+    isEligible(runId: string, now: number): boolean;
+    note(runId: string, now: number): void;
+}
+type SweepDeps = {
+    resume: (runId: string) => Promise<void>;
+    logger?: Logger;
+};
+/**
+ * Re-drive runs whose next move was lost, and report which were resumed.
+ *
+ * Arming a step is two writes to two systems — the step row, then the queue or
+ * scheduler job — so a process that dies between them leaves a run that is
+ * `running` with nothing in flight. Nothing notices: the run parks on a step
+ * that will never complete and never error, so it neither finishes nor fails.
+ * (Seen on a `workflow.sleep()`: a deploy restart landed between the sleep
+ * step's insert and its timer, parking the run permanently.)
+ *
+ * Replay is the recovery — `resumeWorkflow` re-orchestrates from persisted step
+ * state, and every settled step is memoized, so resuming a run that was not
+ * actually stuck costs an orchestration pass and changes nothing. That
+ * idempotence is what makes an idle-time heuristic safe here; a run that is
+ * legitimately mid-sleep is excluded anyway, since its step is `scheduled`.
+ */
+export declare const sweepStalledRuns: (findStalledRunIds: (before: Date, limit: number) => Promise<string[]>, options: {
+    stalledAfterMs?: number;
+    limit?: number;
+} | undefined, deps: SweepDeps) => Promise<{
+    resumed: string[];
+}>;
+/**
+ * Re-drive steps whose dispatch was lost, and report which runs were nudged.
+ *
+ * The step row is the outbox record and this is the relay. Age is the only
+ * signal available — a step `pending` because its dispatch was lost is
+ * indistinguishable from one whose job is merely still queued — so a step past
+ * `undispatchedAfterMs` is re-dispatched regardless, and correctness rests on
+ * the claim in `executeWorkflowStepInner` rather than on the guess being right.
+ * A redundant dispatch costs one queue message: the loser reads `running` and
+ * returns without invoking anything.
+ *
+ * Re-dispatches back off per run (doubling from 30s, capped at 10m) so a
+ * genuine queue backlog is not amplified by a tick that keeps firing at the
+ * steps the backlog is already delaying.
+ */
+export declare const sweepUndispatchedSteps: (findUndispatchedSteps: (before: Date, limit: number) => Promise<Array<{
+    runId: string;
+    stepId: string;
+}>>, backoff: RedispatchBackoff, options: {
+    undispatchedAfterMs?: number;
+    limit?: number;
+} | undefined, deps: SweepDeps) => Promise<{
+    redispatched: string[];
+}>;
+export {};

package/dist/wirings/workflow/workflow-recovery.js

@@ -0,0 +1,101 @@
+import { DEFAULT_STALLED_RUN_LIMIT, DEFAULT_STALLED_RUN_MS, DEFAULT_UNDISPATCHED_STEP_LIMIT, DEFAULT_UNDISPATCHED_STEP_MS, REDISPATCH_BACKOFF_MAX_ENTRIES, REDISPATCH_BACKOFF_MAX_MS, REDISPATCH_BACKOFF_MS, } from './workflow-constants.js';
+/**
+ * Per-process, advisory record of when a run may next be re-dispatched.
+ *
+ * Keyed by run rather than by step because the run is the unit of re-drive:
+ * `resumeWorkflow` replays the whole run and re-dispatches every step still
+ * owed a job, so holding off a single step while resuming its run would
+ * suppress nothing.
+ *
+ * Losing this on restart costs extra dispatches, never correctness.
+ */
+export class RedispatchBackoff {
+    eligibleAt = new Map();
+    delays = new Map();
+    isEligible(runId, now) {
+        const at = this.eligibleAt.get(runId);
+        return at === undefined || at <= now;
+    }
+    note(runId, now) {
+        const previous = this.delays.get(runId);
+        const delay = Math.min(previous === undefined ? REDISPATCH_BACKOFF_MS : previous * 2, REDISPATCH_BACKOFF_MAX_MS);
+        // A run that settles is never returned again, so entries are only evicted
+        // by this bound — oldest first, which is also least recently re-dispatched.
+        if (this.eligibleAt.size >= REDISPATCH_BACKOFF_MAX_ENTRIES) {
+            const oldest = this.eligibleAt.keys().next();
+            if (!oldest.done) {
+                this.eligibleAt.delete(oldest.value);
+                this.delays.delete(oldest.value);
+            }
+        }
+        this.delays.set(runId, delay);
+        this.eligibleAt.set(runId, now + delay);
+    }
+}
+const resumeEach = async (runIds, { resume, logger }, failure) => {
+    const succeeded = [];
+    for (const runId of runIds) {
+        try {
+            await resume(runId);
+            succeeded.push(runId);
+        }
+        catch (err) {
+            // One unresumable run must not stop the sweep from recovering the rest.
+            logger?.error(failure(runId, err instanceof Error ? err.message : String(err)));
+        }
+    }
+    return succeeded;
+};
+/**
+ * Re-drive runs whose next move was lost, and report which were resumed.
+ *
+ * Arming a step is two writes to two systems — the step row, then the queue or
+ * scheduler job — so a process that dies between them leaves a run that is
+ * `running` with nothing in flight. Nothing notices: the run parks on a step
+ * that will never complete and never error, so it neither finishes nor fails.
+ * (Seen on a `workflow.sleep()`: a deploy restart landed between the sleep
+ * step's insert and its timer, parking the run permanently.)
+ *
+ * Replay is the recovery — `resumeWorkflow` re-orchestrates from persisted step
+ * state, and every settled step is memoized, so resuming a run that was not
+ * actually stuck costs an orchestration pass and changes nothing. That
+ * idempotence is what makes an idle-time heuristic safe here; a run that is
+ * legitimately mid-sleep is excluded anyway, since its step is `scheduled`.
+ */
+export const sweepStalledRuns = async (findStalledRunIds, options, deps) => {
+    const before = new Date(Date.now() - (options?.stalledAfterMs ?? DEFAULT_STALLED_RUN_MS));
+    const runIds = await findStalledRunIds(before, options?.limit ?? DEFAULT_STALLED_RUN_LIMIT);
+    return {
+        resumed: await resumeEach(runIds, deps, (runId, detail) => `Failed to resume stalled workflow run ${runId}: ${detail}`),
+    };
+};
+/**
+ * Re-drive steps whose dispatch was lost, and report which runs were nudged.
+ *
+ * The step row is the outbox record and this is the relay. Age is the only
+ * signal available — a step `pending` because its dispatch was lost is
+ * indistinguishable from one whose job is merely still queued — so a step past
+ * `undispatchedAfterMs` is re-dispatched regardless, and correctness rests on
+ * the claim in `executeWorkflowStepInner` rather than on the guess being right.
+ * A redundant dispatch costs one queue message: the loser reads `running` and
+ * returns without invoking anything.
+ *
+ * Re-dispatches back off per run (doubling from 30s, capped at 10m) so a
+ * genuine queue backlog is not amplified by a tick that keeps firing at the
+ * steps the backlog is already delaying.
+ */
+export const sweepUndispatchedSteps = async (findUndispatchedSteps, backoff, options, deps) => {
+    const before = new Date(Date.now() - (options?.undispatchedAfterMs ?? DEFAULT_UNDISPATCHED_STEP_MS));
+    const steps = await findUndispatchedSteps(before, options?.limit ?? DEFAULT_UNDISPATCHED_STEP_LIMIT);
+    const now = Date.now();
+    const runIds = new Set();
+    for (const { runId } of steps) {
+        if (!backoff.isEligible(runId, now))
+            continue;
+        backoff.note(runId, now);
+        runIds.add(runId);
+    }
+    return {
+        redispatched: await resumeEach(runIds, deps, (runId, detail) => `Failed to re-dispatch workflow run ${runId}: ${detail}`),
+    };
+};

package/dist/wirings/workflow/workflow-run-engine.types.d.ts

@@ -0,0 +1,54 @@
+import type { PikkuRawWire, SerializedError } from '../../types/core.types.js';
+import type { CoreWorkflow, PikkuWorkflowWire, StepState, WorkflowRun, WorkflowStatus, WorkflowStepOptions } from './workflow.types.js';
+export interface RunLifecycleContext {
+    runId: string;
+    run: WorkflowRun;
+    workflowMeta: any;
+    workflow: CoreWorkflow;
+    wire: PikkuRawWire;
+    packageName: string | null;
+}
+/**
+ * The subset of the workflow service a step executor is allowed to call back
+ * into.
+ */
+export interface WorkflowRunEngine {
+    inlineStep(runId: string, logicalStepName: string, fn: Function, stepOptions?: WorkflowStepOptions, data?: any, funcName?: string): Promise<any>;
+    updateRunStatus(runId: string, status: WorkflowStatus, output?: any, error?: SerializedError): Promise<void>;
+    onChildWorkflowFailed(run: WorkflowRun, error: unknown): Promise<void>;
+    verifyStepName(stepName: unknown): void;
+}
+/**
+ * Hooks a host may install to decorate runs it did not start. Used by the
+ * scenario service to attach its own per-run state.
+ */
+export interface WorkflowRunExtension {
+    attachRunContext(runId: string, workflowMeta: any, options?: Record<string, any>): Promise<void>;
+    detachRunContext(runId: string): void;
+    decorateRunWire(wire: PikkuRawWire, context: {
+        runId: string;
+        workflowMeta: any;
+        workflowWire: PikkuWorkflowWire;
+    }): void;
+    decorateWorkflowWire(workflowWire: PikkuWorkflowWire, context: {
+        name: string;
+        runId: string;
+        rpcService: any;
+        addonNamespace?: string | null;
+    }): void;
+    onBeforeRunFunc(context: RunLifecycleContext): Promise<void>;
+    onAfterRunFunc(context: RunLifecycleContext, outcome: 'completed' | 'failed' | 'interrupted', failure: unknown): Promise<void>;
+}
+/**
+ * Per-run bookkeeping held only for the lifetime of an in-process execution.
+ */
+export type RunContext = {
+    activeExecutions: number;
+    inline?: boolean;
+    ordinals: Map<string, number>;
+    lastStep?: string;
+    replay?: {
+        steps?: Map<string, StepState>;
+        run?: WorkflowRun;
+    };
+};

package/dist/wirings/workflow/workflow-run-ownership.d.ts

@@ -0,0 +1,17 @@
+import { ForbiddenError } from '../../errors/errors.js';
+import type { CoreUserSession } from '../../types/core.types.js';
+import type { WorkflowRunWire } from './workflow.types.js';
+export declare class WorkflowRunForbiddenError extends ForbiddenError {
+    constructor();
+}
+/**
+ * A run started through a session records that session's user as its owner, and
+ * only that user may read it. Who may *answer* a run's approval gates is the
+ * gate's own declaration — see `approvers` on `workflow.approval()`.
+ *
+ * A run with no recorded owner — started by a trigger, a scheduler, or a route
+ * wired without auth — has nobody to compare a caller against, so ownership is
+ * not a control that exists for it. Gate those with `auth` or `permissions` on
+ * the entrypoint instead.
+ */
+export declare const assertWorkflowRunOwner: (wire: WorkflowRunWire | undefined, session: CoreUserSession | undefined) => void;

package/dist/wirings/workflow/workflow-run-ownership.js

@@ -0,0 +1,30 @@
+import { ForbiddenError } from '../../errors/errors.js';
+import { addError } from '../../errors/error-handler.js';
+export class WorkflowRunForbiddenError extends ForbiddenError {
+    constructor() {
+        super('Not authorized to access this workflow run');
+    }
+}
+addError(WorkflowRunForbiddenError, {
+    status: 403,
+    message: 'Not authorized to access this workflow run.',
+});
+/**
+ * A run started through a session records that session's user as its owner, and
+ * only that user may read it. Who may *answer* a run's approval gates is the
+ * gate's own declaration — see `approvers` on `workflow.approval()`.
+ *
+ * A run with no recorded owner — started by a trigger, a scheduler, or a route
+ * wired without auth — has nobody to compare a caller against, so ownership is
+ * not a control that exists for it. Gate those with `auth` or `permissions` on
+ * the entrypoint instead.
+ */
+export const assertWorkflowRunOwner = (wire, session) => {
+    const owner = wire?.pikkuUserId;
+    if (!owner) {
+        return;
+    }
+    if (!session?.userId || session.userId !== owner) {
+        throw new WorkflowRunForbiddenError();
+    }
+};

package/dist/wirings/workflow/workflow-suspend.d.ts

@@ -0,0 +1,12 @@
+import type { ApprovalStore } from './workflow-approval.js';
+/** The durable step name a suspension point is recorded under. */
+export declare const suspendStepNameFor: (reason: string) => string;
+/** What the suspend gate needs from the workflow service. */
+export type SuspendStore = Pick<ApprovalStore, 'getStepState' | 'insertStepState' | 'setStepRunning' | 'setStepResult'>;
+/**
+ * Record a suspension point and unwind the run.
+ *
+ * A suspension that has already succeeded returns instead of throwing, so a
+ * replay walks past a gate the run has already passed through.
+ */
+export declare const recordSuspension: (store: SuspendStore, runId: string, reason: string, stepName: string, fromStepName: string | undefined) => Promise<void>;

package/dist/wirings/workflow/workflow-suspend.js

@@ -0,0 +1,33 @@
+import { WorkflowSuspendedException } from './workflow-errors.js';
+/** The durable step name a suspension point is recorded under. */
+export const suspendStepNameFor = (reason) => `__workflow_suspend:${reason}`;
+/**
+ * Record a suspension point and unwind the run.
+ *
+ * A suspension that has already succeeded returns instead of throwing, so a
+ * replay walks past a gate the run has already passed through.
+ */
+export const recordSuspension = async (store, runId, reason, stepName, fromStepName) => {
+    const insert = () => store.insertStepState(runId, stepName, 'pikkuWorkflowSuspend', { reason }, undefined, fromStepName);
+    let stepState;
+    try {
+        stepState = await store.getStepState(runId, stepName);
+    }
+    catch {
+        stepState = await insert();
+    }
+    if (!stepState.stepId) {
+        stepState = await insert();
+    }
+    if (stepState.status === 'succeeded') {
+        return;
+    }
+    if (stepState.status === 'pending') {
+        await store.setStepRunning(stepState.stepId);
+    }
+    await store.setStepResult(stepState.stepId, {
+        reason,
+        suspendedAt: new Date().toISOString(),
+    });
+    throw new WorkflowSuspendedException(runId, reason);
+};

package/dist/wirings/workflow/workflow.types.d.ts

@@ -2,7 +2,7 @@ import type { SerializedError, CommonWireMeta } from '../../types/core.types.js'
 import type { CorePikkuFunctionConfig, CorePikkuFunctionHook } from '../../function/functions.types.js';
 import type { GroupConcurrencyConfig } from '../queue/queue.types.js';
 export type { WorkflowService } from '../../services/workflow-service.js';
-export type { WorkflowStepOptions, WorkflowExpectEventuallyOptions, WorkflowExpectErrorOptions, WorkflowExpectServiceOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, WorkflowWireApproval, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, ScenarioStepInvocation, ScenarioStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, PikkuScenarioWire, } from './dsl/workflow-dsl.types.js';
+export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, Condition, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, ScenarioStepInvocation, ScenarioStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, PikkuScenarioWire, } from './dsl/workflow-dsl.types.js';
 export type { ScenarioStepPhase, ScenarioStepOptions, PikkuScenarioStepWire, PikkuBrowserWire, ScenarioBrowserProvider, } from './scenario-step.types.js';
 import type { WorkflowStepMeta } from './dsl/workflow-dsl.types.js';
 export interface WorkflowRunWire {
@@ -49,6 +49,13 @@ export interface WorkflowRun {
 export interface StepState {
     stepId: string;
     status: StepStatus;
+    /**
+     * The function the workflow dispatched this step with, recorded so a worker
+     * can reject a queue message naming anything else. `null` is a step with no
+     * function of its own (inline work); `undefined` is a store that never
+     * recorded one, and cannot be compared against.
+     */
+    rpcName?: string | null;
     result?: any;
     error?: SerializedError;
     attemptCount: number;

package/knowledge/decisions/internals/a-non-streaming-agent-run-registers-with-airunstate-too.md

@@ -0,0 +1,22 @@
+---
+type: decision
+title: A non-streaming agent run registers with aiRunState on the same terms as a streaming one
+description: Otherwise interruptAIAgent finds the run, passes the ownership check, then cannot stop it — and reports that as if the run were on another host
+tags: core, ai-agent
+---
+
+# A non-streaming agent run registers with `aiRunState` too
+
+`runAIAgent` registers its run with `aiRunState` exactly as `streamAIAgent`
+does, even though nothing is streaming and there is no channel to interrupt.
+
+`interruptAIAgent` resolves a run through `aiRunState` first, checks ownership,
+then looks for a local abort handle. A run that skipped registration is invisible
+at the first step. A run that registered but has no handle is visible, passes the
+ownership check, and then cannot be stopped — which the interrupt path reports as
+"running on another instance". That message would be wrong and actively
+misleading: the run is right here, and the deployment is single-instance.
+
+**What this rules out:** treating registration as a streaming concern. It is an
+addressability concern, and the two paths have to be addressable the same way for
+the interrupt path's diagnosis to mean anything.

package/knowledge/decisions/internals/a-resumed-agent-turn-is-as-interruptible-as-the-first.md

@@ -0,0 +1,20 @@
+---
+type: decision
+title: A resumed turn is as interruptible as the first one
+description: It is the same person listening to the same voice, and after an approval it is where most of the reply actually gets spoken
+tags: core, ai-agent
+---
+
+# A resumed turn is as interruptible as the first one
+
+Resuming after an approval registers for interruption on the same terms as the
+original turn.
+
+It is the same person listening to the same voice, so the reason to allow
+interruption has not changed. And after an approval is precisely where most of
+the reply gets spoken: an approved delete is followed by the agent describing
+what it did, which is a normal thing for a listener to talk over.
+
+**What this rules out:** treating the resume as a short continuation not worth
+wiring for interruption. By volume of speech it is usually the larger half of
+the exchange.

package/knowledge/decisions/internals/a-scenario-step-template-is-offered-unfilled.md

@@ -0,0 +1,21 @@
+---
+type: decision
+title: A scenario step's prose template is offered to a virtual user unfilled
+description: 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
+tags: core, virtual-user
+---
+
+# A scenario step's prose template is offered unfilled
+
+When a scenario step becomes a catalogue entry, its prose template goes in with
+its placeholders intact — braces and all.
+
+A reporter fills those placeholders from a run that already happened. There is
+no run yet at derivation time, so there is nothing to fill them from. More
+importantly, filling them would answer the wrong question: "invites {email}"
+tells the user to choose someone, where "invites ada@example.com" tells it whom
+— and *whom* is the scenario author's answer, not something the virtual user
+worked out.
+
+**What this rules out:** substituting example or fixture values to make the
+catalogue read more naturally. It reads better and tests less.

package/knowledge/decisions/internals/a-virtual-user-decides-whether-to-trust-memory-once-per-turn.md

@@ -0,0 +1,21 @@
+---
+type: decision
+title: A virtual user decides whether to trust its notes once per turn, by one roll
+description: The difference between the stale, newcomer and auditor dispositions is expressed as a single probability rather than as prose in each prompt
+tags: core, virtual-user
+---
+
+# A virtual user decides whether to trust its notes once per turn
+
+Each turn the run makes one weighted decision: does this user act on what it
+already recorded, or go and look again.
+
+That single roll is where the dispositions differ. `stale` almost always trusts
+its notes — that is what makes it stale. A `newcomer` has none to trust. An
+`auditor` re-checks nearly everything, which is the entire point of an auditor.
+Expressing it as one probability keeps the difference between those runs in one
+readable place instead of spread through three prompts as English that drifts.
+
+**What this rules out:** encoding "you are suspicious of your own notes" into
+each disposition's prompt text, where the behaviour becomes a property of how
+the model reads prose rather than something the run controls and can report.

package/knowledge/decisions/internals/a-wall-clock-threshold-is-a-load-test-in-disguise.md

@@ -0,0 +1,46 @@
+---
+type: decision
+title: A wall-clock threshold is a load test in disguise
+description: 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
+tags: core, testing, crypto
+---
+
+# A wall-clock threshold is a load test in disguise
+
+`crypto-utils.test.ts` guards a real property: unwrapping N secrets must not
+cost N KEK derivations. Deriving a KEK is a deliberately slow KDF, so doing it
+per secret turns a 10ms operation into a 4-second one.
+
+It guarded it with `assert.ok(elapsed < 50)`. Measured on this machine:
+
+| | |
+| --- | --- |
+| one `deriveKEK` | ~86ms |
+| 50 `envelopeDecrypt` | 10.8ms |
+| the old 50ms threshold | 4.6x headroom |
+| the failure it guards against | ~4281ms — a **396x** separation |
+
+So the assertion had 4.6x of margin to detect a 396x regression. Everything
+between those two numbers was noise, and once core's suite reached ~2000 tests
+competing for the same cores, a 10ms window drifting past 50ms became routine:
+roughly one run in five went red, always on a machine where nothing was wrong.
+
+**Calibrate against a measurement taken in the same run.** The test already
+derives a KEK, so timing that call is free, and the assertion becomes
+`elapsed < oneDerivation` — unwrapping all fifty must cost less than deriving
+once. Under load both sides slow down together, so the ratio holds.
+
+**What this rules out:** raising the constant. 100ms or 200ms buys a smaller
+flake rate and the same class of bug, and it drifts again the next time the
+suite grows or CI moves to a noisier runner. Any assertion of the form
+"operation X takes less than N milliseconds" has this problem; express it as a
+ratio against something measured alongside it.
+
+Worth knowing: `envelopeDecrypt(kek: CryptoKey, …)` takes the derived key as a
+parameter, so it *cannot* derive one — the property is already enforced by the
+signature, and [[the-api-report-pins-members-not-just-names]] would catch a
+change to it. The test is defence in depth, which is a reason to make it cheap
+and quiet rather than to delete it.
+
+Related: [[an-unref-d-timer-cannot-be-awaited-under-node-test]], the other
+source of nondeterminism found in the same pass.