@pikku/core 0.12.67 → 0.12.70

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

@@ -3,7 +3,6 @@ import { pikkuWorkflowWorkerFunc, pikkuWorkflowOrchestratorFunc, pikkuWorkflowSl
 import { wireQueueWorker } from '../queue/queue-runner.js';
 import { getSingletonServices, getCreateWireServices, pikkuState, } from '../../pikku-state.js';
 import { getDurationInMilliseconds } from '../../time-utils.js';
-import { createHttpScenarioActors } from '../../services/http-scenario-actors.js';
 const resolveWorkflowMeta = (name) => {
     const rootMeta = pikkuState(null, 'workflows', 'meta');
     if (rootMeta[name]) {
@@ -29,7 +28,6 @@ const resolveWorkflowMeta = (name) => {
     return null;
 };
 const toKebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
-import { runScheduledTask } from '../scheduler/scheduler-runner.js';
 import { continueGraph, executeGraphStep, runWorkflowGraph, runFromMeta, } from './graph/graph-runner.js';
 import { PikkuError, addError, isExpectedError, } from '../../errors/error-handler.js';
 import { RPCNotFoundError } from '../rpc/rpc-runner.js';
@@ -179,16 +177,20 @@ const WORKFLOW_END_STATES = new Set([
  */
 export class PikkuWorkflowService {
     inlineRuns = new Set();
-    // User-flow actors per run: live authenticated clients (cookie jars) are
-    // process-local by nature, so they ride this map, never the persisted wire.
-    runActors = new Map();
+    runExtension;
     get logger() {
         return getSingletonServices()?.logger;
     }
     mirror;
+    queueStrategy;
+    queueConcurrency;
+    queueGroupConcurrency;
     constructor(options = {}) {
         const wireQueues = options.wireQueues ?? true;
         this.mirror = options.mirror;
+        this.queueStrategy = options.queueStrategy ?? 'per-workflow';
+        this.queueConcurrency = options.queueConcurrency ?? 20;
+        this.queueGroupConcurrency = options.queueGroupConcurrency ?? 2;
         if (wireQueues) {
             this.wireQueueWorkers();
         }
@@ -226,21 +228,32 @@ export class PikkuWorkflowService {
             outputSchemaName: null,
         });
         const queueMeta = pikkuState(null, 'queue', 'meta');
-        const registerWorkflowFunc = (funcId, func, queueName) => {
+        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 });
+            wireQueueWorker({ name: queueName, func, config });
             if (!functionsMeta[funcId]) {
                 functionsMeta[funcId] = mkMeta(funcId);
             }
         };
+        // Under 'shared-groups' every workflow runs through these two queues and is
+        // kept from hogging them by the per-group cap, so the per-workflow queues
+        // below are left unconsumed — one set of pollers for the whole system
+        // instead of one per workflow.
+        const sharedGroups = this.queueStrategy === 'shared-groups';
+        const sharedQueueConfig = sharedGroups
+            ? {
+                batchSize: this.queueConcurrency,
+                groupConcurrency: this.queueGroupConcurrency,
+            }
+            : undefined;
         // Register shared queue workers for monolith deployments
-        registerWorkflowFunc('pikkuWorkflowOrchestrator', { func: pikkuWorkflowOrchestratorFunc }, 'pikku-workflow-orchestrator');
-        registerWorkflowFunc('pikkuWorkflowStepWorker', { func: pikkuWorkflowWorkerFunc }, 'pikku-workflow-step-worker');
+        registerWorkflowFunc('pikkuWorkflowOrchestrator', { func: pikkuWorkflowOrchestratorFunc }, 'pikku-workflow-orchestrator', sharedQueueConfig);
+        registerWorkflowFunc('pikkuWorkflowStepWorker', { func: pikkuWorkflowWorkerFunc }, 'pikku-workflow-step-worker', sharedQueueConfig);
         // Register per-workflow queue workers (root + addon packages)
         const registerQueueWorkers = (queueMeta) => {
             for (const [queueName, meta] of Object.entries(queueMeta)) {
@@ -254,16 +267,32 @@ export class PikkuWorkflowService {
                 }
             }
         };
-        registerQueueWorkers(pikkuState(null, 'queue', 'meta'));
-        const addons = pikkuState(null, 'addons', 'packages');
-        if (addons) {
-            for (const [, addon] of addons) {
-                const addonQueueMeta = pikkuState(addon.package, 'queue', 'meta');
-                if (addonQueueMeta) {
-                    registerQueueWorkers(addonQueueMeta);
+        if (!sharedGroups) {
+            registerQueueWorkers(pikkuState(null, 'queue', 'meta'));
+            const addons = pikkuState(null, 'addons', 'packages');
+            if (addons) {
+                for (const [, addon] of addons) {
+                    const addonQueueMeta = pikkuState(addon.package, 'queue', 'meta');
+                    if (addonQueueMeta) {
+                        registerQueueWorkers(addonQueueMeta);
+                    }
                 }
             }
         }
+        // Workflows exist but no per-workflow orchestrator queue was registered:
+        // the generated queue meta never reached the runtime (most often the
+        // bootstrap doesn't import the queue-workers meta, so `queue.meta` is
+        // empty). Everything still "works" — dispatch silently falls back to the
+        // single shared orchestrator queue — but the isolation is gone: one slow
+        // workflow step head-of-line-blocks every other workflow behind it. That
+        // is invisible until a queue starves, so say so loudly at wiring time.
+        const workflowCount = Object.keys(pikkuState(null, 'workflows', 'meta') ?? {}).length;
+        const perWorkflowQueues = Object.keys(queueMeta).filter((name) => name.startsWith('wf-orchestrator-')).length;
+        if (workflowCount > 0 && perWorkflowQueues === 0) {
+            this.logger?.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).`);
+        }
         if (!functions.has('pikkuWorkflowSleeper')) {
             addFunction('pikkuWorkflowSleeper', {
                 func: pikkuWorkflowSleeperFunc,
@@ -387,7 +416,10 @@ export class PikkuWorkflowService {
      * Creates pending step in both workflow_step and workflow_step_history
      * @param runId - Run ID
      * @param stepName - Step cache key
-     * @param rpcName - RPC function name
+     * @param rpcName - The name this step was dispatched by: an RPC for a
+     *   `workflow.do` step, a step function for a scenario step, null for a
+     *   closure. Nothing dispatches off this value — it is recorded so a reader
+     *   can join a step back to the function that ran it.
      * @param data - Step input data
      * @param stepOptions - Step options (retries, retryDelay)
      * @returns Step state with generated stepId
@@ -513,7 +545,10 @@ export class PikkuWorkflowService {
         // dispatch/infra failure recover: the job is rethrown and retried instead of
         // the run hanging. Passing `attempts` per-job overrides the queue default, so
         // this holds even when the orchestrator queue is configured `retry_limit 0`.
-        await queueService.add(this.getOrchestratorQueueName(workflowName), { runId }, this.resolveStepJobOptions());
+        await queueService.add(this.getOrchestratorQueueName(workflowName), { runId }, {
+            ...this.resolveStepJobOptions(),
+            group: this.getJobGroup(workflowName),
+        });
     }
     /**
      * Resolve a step's retry policy into queue job options. The workflow is the
@@ -538,7 +573,12 @@ export class PikkuWorkflowService {
     }
     async queueStepWorker(runId, stepName, rpcName, data, stepOptions, fromStepName) {
         const queueService = this.verifyQueueService();
-        await queueService.add(this.getStepWorkerQueueName(rpcName), JSON.parse(JSON.stringify({ runId, stepName, rpcName, data, fromStepName })), this.resolveStepJobOptions(stepOptions));
+        await queueService.add(this.getStepWorkerQueueName(rpcName), JSON.parse(JSON.stringify({ runId, stepName, rpcName, data, fromStepName })), {
+            ...this.resolveStepJobOptions(stepOptions),
+            // Group by step function, mirroring how per-step queues split them —
+            // one slow step function can't monopolise the shared step worker.
+            group: this.getJobGroup(rpcName),
+        });
     }
     /**
      * Execute a workflow sleep step completion
@@ -560,7 +600,12 @@ export class PikkuWorkflowService {
             const run = await this.getRun(runId);
             workflowName = run?.workflow;
         }
-        await queueService.add(this.getOrchestratorQueueName(workflowName), { runId }, retryDelay ? { delay: getDurationInMilliseconds(retryDelay) } : undefined);
+        await queueService.add(this.getOrchestratorQueueName(workflowName), { runId }, {
+            ...(retryDelay
+                ? { delay: getDurationInMilliseconds(retryDelay) }
+                : undefined),
+            group: this.getJobGroup(workflowName),
+        });
     }
     /**
      * Dispatch a workflow step to be executed asynchronously.
@@ -592,7 +637,10 @@ export class PikkuWorkflowService {
             throw new Error(`Workflow step '${stepName}' (function '${rpcName}') is marked 'workflowQueued: true' but no queue service is configured.`);
         }
         try {
-            await getSingletonServices().queueService.add(this.getStepWorkerQueueName(rpcName), JSON.parse(JSON.stringify({ runId, stepName, rpcName, data, fromStepName })), this.resolveStepJobOptions(stepOptions));
+            await getSingletonServices().queueService.add(this.getStepWorkerQueueName(rpcName), JSON.parse(JSON.stringify({ runId, stepName, rpcName, data, fromStepName })), {
+                ...this.resolveStepJobOptions(stepOptions),
+                group: this.getJobGroup(rpcName),
+            });
         }
         catch (cause) {
             // The queue is down/unreachable — NOT a step failure. Surface it as a
@@ -620,40 +668,34 @@ export class PikkuWorkflowService {
         await getSingletonServices().schedulerService.scheduleRPC(duration, this.getConfig().sleeperRPCName, { runId, stepId });
         return true;
     }
-    /** Build HTTP scenario actors for a run started without them; undefined when SCENARIO_ACTOR_SECRET or the API URL is missing */
-    async resolveScenarioActors() {
-        const services = getSingletonServices();
-        const variables = services?.variables;
-        const metaService = services?.metaService;
-        if (!variables || !metaService) {
-            return undefined;
-        }
-        const secret = await variables.get('SCENARIO_ACTOR_SECRET');
-        const apiUrl = await variables.get('API_URL');
-        if (!secret || !apiUrl) {
-            services?.logger?.warn('A scenario was started without actors but SCENARIO_ACTOR_SECRET / API_URL is not configured — running without actors.');
-            return undefined;
-        }
-        const actorsConfig = await metaService.getScenarioActorsMeta();
-        if (!actorsConfig || Object.keys(actorsConfig).length === 0) {
-            return undefined;
-        }
-        const signInPath = (await variables.get('SCENARIO_SIGN_IN_PATH')) ??
-            '/api/auth/sign-in/actor';
-        const rpcPath = (await variables.get('SCENARIO_RPC_PATH')) ?? '/rpc';
-        return createHttpScenarioActors({
-            apiUrl,
-            secret,
-            actors: actorsConfig,
-            signInPath,
-            rpcPath,
-        });
+    /**
+     * Install the one extension a run may have, built from a handle onto the run
+     * engine so that `inlineStep` and friends stay protected rather than becoming
+     * public API. Returns the extension, so the caller keeps a typed reference to
+     * whatever it just built.
+     */
+    setRunExtension(create) {
+        const engine = {
+            inlineStep: this.inlineStep.bind(this),
+            updateRunStatus: this.updateRunStatus.bind(this),
+            onChildWorkflowFailed: this.onChildWorkflowFailed.bind(this),
+            verifyStepName: this.verifyStepName.bind(this),
+        };
+        const extension = create(engine);
+        this.runExtension = extension;
+        return extension;
+    }
+    getRunExtension() {
+        return this.runExtension;
     }
     /**
      * Start a new workflow run
      * Automatically detects workflow type (DSL or graph) from meta and executes accordingly
      * @param options.inline - If true, execute workflow directly without queue service
      * @param options.startNode - Starting node ID for graph workflows (from wire config)
+     * @param options.onRunCreated - Called with the run id the moment the run exists.
+     * An inline run that fails throws instead of returning, so this is the only
+     * way a caller can still read that run back — its steps, and which one failed.
      */
     async startWorkflow(name, input, wire, rpcService, options) {
         // Resolve workflow from static meta (root or addon namespace), then dynamic DB
@@ -689,13 +731,8 @@ export class PikkuWorkflowService {
             deterministic: workflowMeta.deterministic,
             plannedSteps: workflowMeta.plannedSteps,
         });
-        const actors = options?.actors ??
-            (workflowMeta.source === 'scenario'
-                ? await this.resolveScenarioActors()
-                : undefined);
-        if (actors) {
-            this.runActors.set(runId, actors);
-        }
+        options?.onRunCreated?.(runId);
+        await this.runExtension?.attachRunContext(runId, workflowMeta, options);
         if (shouldInline) {
             this.inlineRuns.add(runId);
             try {
@@ -728,7 +765,7 @@ export class PikkuWorkflowService {
             }
             finally {
                 this.inlineRuns.delete(runId);
-                this.runActors.delete(runId);
+                this.runExtension?.detachRunContext(runId);
             }
         }
         else {
@@ -853,14 +890,30 @@ export class PikkuWorkflowService {
             workflowWire.pikkuUserId = run.wire?.pikkuUserId;
             const wire = {
                 workflow: workflowWire,
-                scenario: workflowMeta?.source === 'scenario' ? workflowWire : undefined,
                 pikkuUserId: run.wire?.pikkuUserId,
                 session: rpcService?.wire?.session,
                 rpc: rpcService?.wire?.rpc,
-                // User-flow actors registered for this run (see startWorkflow options)
-                actors: this.runActors.get(runId),
             };
+            this.runExtension?.decorateRunWire(wire, {
+                runId,
+                workflowMeta,
+                workflowWire,
+            });
+            const lifecycle = {
+                runId,
+                run,
+                workflowMeta,
+                workflow,
+                wire,
+                packageName: pkgName,
+            };
+            // `interrupted` means the run has not reached a terminal state — it is
+            // suspended or waiting — so teardown would run while the run is still
+            // mid-flight.
+            let outcome = 'completed';
+            let failure;
             try {
+                await this.runExtension?.onBeforeRunFunc(lifecycle);
                 const result = await runPikkuFunc('workflow', workflowMeta.name, workflowMeta.pikkuFuncId, {
                     singletonServices: getSingletonServices(),
                     wire,
@@ -872,10 +925,13 @@ export class PikkuWorkflowService {
                 await this.onChildWorkflowCompleted(run, result);
             }
             catch (error) {
+                failure = error;
                 if (error instanceof WorkflowAsyncException) {
+                    outcome = 'interrupted';
                     throw error;
                 }
                 if (error instanceof WorkflowCancelledException) {
+                    outcome = 'failed';
                     await this.updateRunStatus(runId, 'cancelled', undefined, {
                         message: error.message || 'Workflow cancelled',
                         stack: '',
@@ -885,6 +941,7 @@ export class PikkuWorkflowService {
                     throw error;
                 }
                 if (error instanceof WorkflowSuspendedException) {
+                    outcome = 'interrupted';
                     await this.updateRunStatus(runId, 'suspended', undefined, {
                         message: error.message || 'Workflow suspended',
                         stack: '',
@@ -892,6 +949,7 @@ export class PikkuWorkflowService {
                     });
                     throw error;
                 }
+                outcome = 'failed';
                 await this.updateRunStatus(runId, 'failed', undefined, {
                     message: error.message,
                     stack: error.stack,
@@ -900,6 +958,9 @@ export class PikkuWorkflowService {
                 await this.onChildWorkflowFailed(run, error);
                 throw error;
             }
+            finally {
+                await this.runExtension?.onAfterRunFunc(lifecycle, outcome, failure);
+            }
         });
     }
     async onChildWorkflowCompleted(childRun, result) {
@@ -1279,7 +1340,21 @@ export class PikkuWorkflowService {
             }
         });
     }
-    async inlineStep(runId, logicalStepName, fn, stepOptions) {
+    async inlineStep(runId, logicalStepName, fn, stepOptions, 
+    /**
+     * The input this step was called with, recorded on the run so a reporter can
+     * name the values under test. A closure step has none; a scenario step does.
+     */
+    data = null, 
+    /**
+     * The name this step was dispatched by, for the kinds of inline step that
+     * have one. A closure step has no name; a scenario step is a step RPC, so
+     * it records the step function that ran — which is the only way to join a
+     * step back to its declaration when its durable name was built at runtime
+     * (a step called in a loop reaches the run as `sees @pikku/addon-todos`,
+     * declared as `sees ${packageName}`).
+     */
+    rpcName = null) {
         const fromStepName = this.lastStepName(runId);
         const stepName = this.nextStepKey(runId, logicalStepName);
         // Check if step already exists
@@ -1288,8 +1363,8 @@ export class PikkuWorkflowService {
             stepState = await this.getStepState(runId, stepName);
         }
         catch {
-            // Step doesn't exist - create it (inline, no RPC)
-            stepState = await this.insertStepState(runId, stepName, null, null, stepOptions, fromStepName);
+            // Step doesn't exist - create it (inline, so never dispatched)
+            stepState = await this.insertStepState(runId, stepName, rpcName, data, stepOptions, fromStepName);
         }
         if (stepState.status === 'succeeded') {
             // Return cached result
@@ -1430,7 +1505,11 @@ export class PikkuWorkflowService {
             const run = await this.getRun(runId);
             if (!run?.workflow)
                 return;
-            await queueService.add(this.getOrchestratorQueueName(run.workflow), { runId }, { ...this.resolveStepJobOptions(), delay });
+            await queueService.add(this.getOrchestratorQueueName(run.workflow), { runId }, {
+                ...this.resolveStepJobOptions(),
+                delay,
+                group: this.getJobGroup(run.workflow),
+            });
         }
         catch (error) {
             this.logger?.warn(`Failed to schedule approval expiry wake for run ${runId}; expiry will still resolve on the next replay`, error);
@@ -1582,90 +1661,6 @@ export class PikkuWorkflowService {
                     return await this.inlineStep(runId, stepName, rpcNameOrFn, dataOrOptions);
                 }
             },
-            // Durable polling step: invoke an RPC (as an actor when options.as is
-            // set) until the predicate passes or `within` elapses. The whole poll is
-            // ONE recorded step, so replay returns the cached outcome.
-            expectEventually: async (stepName, rpcName, data, predicate, options) => {
-                this.verifyStepName(stepName);
-                const resolvedRpcName = addonNamespace && !rpcName.includes(':')
-                    ? `${addonNamespace}:${rpcName}`
-                    : rpcName;
-                const within = getDurationInMilliseconds(options?.within ?? '30s');
-                const interval = getDurationInMilliseconds(options?.interval ?? '1s');
-                return await this.inlineStep(runId, stepName, async () => {
-                    const deadline = Date.now() + within;
-                    let last;
-                    while (true) {
-                        last = options?.actor
-                            ? await options.actor.invoke(resolvedRpcName, data)
-                            : await rpcService.rpcWithWire(resolvedRpcName, data, {});
-                        if (predicate(last))
-                            return last;
-                        if (Date.now() + interval > deadline) {
-                            throw new Error(`[workflow] expectEventually '${stepName}' ('${resolvedRpcName}'` +
-                                `${options?.actor ? ` as '${options.actor.name}'` : ''}) did not pass within ${within}ms; ` +
-                                `last result: ${JSON.stringify(last)?.slice(0, 300)}`);
-                        }
-                        await new Promise((resolve) => setTimeout(resolve, interval));
-                    }
-                }, options);
-            },
-            expectError: async (stepName, rpcName, data, options) => {
-                this.verifyStepName(stepName);
-                const resolvedRpcName = addonNamespace && !rpcName.includes(':')
-                    ? `${addonNamespace}:${rpcName}`
-                    : rpcName;
-                return await this.inlineStep(runId, stepName, async () => {
-                    let result;
-                    try {
-                        result = options?.actor
-                            ? await options.actor.invoke(resolvedRpcName, data)
-                            : await rpcService.rpcWithWire(resolvedRpcName, data, {});
-                    }
-                    catch (e) {
-                        const message = e?.message ?? String(e);
-                        if (options?.matches) {
-                            const matched = typeof options.matches === 'string'
-                                ? message.includes(options.matches)
-                                : options.matches.test(message);
-                            if (!matched) {
-                                throw new Error(`[workflow] expectError '${stepName}' ('${resolvedRpcName}') threw, but the message did not match ${options.matches}: ${message}`);
-                            }
-                        }
-                        return message;
-                    }
-                    throw new Error(`[workflow] expectError '${stepName}' ('${resolvedRpcName}') expected an error but the call succeeded: ${JSON.stringify(result)?.slice(0, 300)}`);
-                }, options);
-            },
-            expectService: async (stepName, serviceMethod, options) => {
-                this.verifyStepName(stepName);
-                const [service, method] = serviceMethod.split('.');
-                if (!service || !method) {
-                    throw new Error(`[workflow] expectService '${stepName}' needs 'service.method', got '${serviceMethod}'`);
-                }
-                await this.inlineStep(runId, stepName, async () => {
-                    const rpcName = 'pikkuScenarioGetStubCalls';
-                    const calls = options?.actor
-                        ? await options.actor.invoke(rpcName, { service })
-                        : await rpcService.rpcWithWire(rpcName, { service }, {});
-                    const matching = (calls ?? []).filter((c) => c.service === service &&
-                        c.method === method &&
-                        (options?.calledWith === undefined ||
-                            JSON.stringify(c.args?.[0]) ===
-                                JSON.stringify(options.calledWith)));
-                    const expected = options?.times;
-                    const ok = expected === undefined
-                        ? matching.length > 0
-                        : matching.length === expected;
-                    if (!ok) {
-                        const seen = (calls ?? [])
-                            .map((c) => `${c.service}.${c.method}(${JSON.stringify(c.args?.[0])?.slice(0, 120) ?? ''})`)
-                            .join('\n  ') || '(none)';
-                        throw new Error(`[workflow] expectService '${stepName}' expected ${expected ?? 'at least one'} call(s) to '${serviceMethod}'` +
-                            `${options?.calledWith !== undefined ? ` with ${JSON.stringify(options.calledWith)}` : ''}, found ${matching.length}. Recorded:\n  ${seen}`);
-                    }
-                }, options);
-            },
             // Implement workflow.sleep()
             sleep: async (stepName, duration) => {
                 this.verifyStepName(stepName);
@@ -1679,10 +1674,13 @@ export class PikkuWorkflowService {
                 this.verifyStepName(reason);
                 return await this.approvalStep(runId, reason, options);
             }),
-            runScheduledTask: async (taskName) => {
-                await runScheduledTask({ name: taskName });
-            },
         };
+        this.runExtension?.decorateWorkflowWire(workflowWire, {
+            name,
+            runId,
+            rpcService,
+            addonNamespace,
+        });
         return workflowWire;
     }
     verifyStepName(stepName) {
@@ -1712,7 +1710,7 @@ export class PikkuWorkflowService {
      * queues — but it produces to them — so registrations would miss them.
      */
     getOrchestratorQueueName(workflowName) {
-        if (workflowName) {
+        if (workflowName && this.queueStrategy !== 'shared-groups') {
             const perWorkflow = `wf-orchestrator-${toKebab(workflowName)}`;
             const meta = pikkuState(null, 'queue', 'meta');
             if (meta[perWorkflow]) {
@@ -1722,7 +1720,7 @@ export class PikkuWorkflowService {
         return this.getConfig().orchestratorQueueName;
     }
     getStepWorkerQueueName(rpcName) {
-        if (rpcName) {
+        if (rpcName && this.queueStrategy !== 'shared-groups') {
             const perStep = `wf-step-${toKebab(rpcName)}`;
             const meta = pikkuState(null, 'queue', 'meta');
             if (meta[perStep]) {
@@ -1731,4 +1729,19 @@ export class PikkuWorkflowService {
         }
         return this.getConfig().stepWorkerQueueName;
     }
+    /**
+     * Fairness key for a job on a shared queue. Under `'per-workflow'` the queue
+     * name already isolates workflows, so no group is needed — returning one
+     * anyway would cap a workflow inside its own dedicated queue.
+     *
+     * The tier repeats the id so a workflow can be given its own limit purely
+     * from config, with no per-workflow wiring; an unmatched tier falls back to
+     * the default limit.
+     */
+    getJobGroup(id) {
+        if (!id || this.queueStrategy !== 'shared-groups') {
+            return undefined;
+        }
+        return { id, tier: id };
+    }
 }

package/dist/wirings/workflow/scenario-cookie-jar.d.ts

@@ -0,0 +1,29 @@
+/** A session held the way a browser holds one, for code driving a real target. */
+export interface ScenarioCookieJar {
+    /** `fetch`, but it sends what the target has set and keeps what it sets. */
+    fetch: typeof fetch;
+    /** Forgets the session — what an actor does before signing in again. */
+    clear(): void;
+    /**
+     * Whether the target has set anything yet. This is a fact about the jar, not
+     * about the session: a target that sets a CSRF or locale cookie before anyone
+     * signs in fills the jar without establishing one. Whoever needs to know
+     * whether a sign-in happened has to track the sign-in.
+     */
+    readonly empty: boolean;
+}
+/**
+ * A `fetch` that remembers cookies.
+ *
+ * A browser persists the session cookie on its own; anything driving a target
+ * from this process has to. Every response is read, not just the sign-in, so a
+ * cookie the target rotates mid-session is followed rather than dropped.
+ *
+ * The jar is a closure local, so two jars never share a session — which is what
+ * lets one scenario sign in as several people without one of them inheriting
+ * the other's session.
+ *
+ * It also stamps `Origin`, because Better Auth rejects a state-changing POST
+ * whose Origin does not match its baseURL.
+ */
+export declare const createCookieJar: (apiUrl: string) => ScenarioCookieJar;

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

@@ -0,0 +1,51 @@
+/**
+ * A `fetch` that remembers cookies.
+ *
+ * A browser persists the session cookie on its own; anything driving a target
+ * from this process has to. Every response is read, not just the sign-in, so a
+ * cookie the target rotates mid-session is followed rather than dropped.
+ *
+ * The jar is a closure local, so two jars never share a session — which is what
+ * lets one scenario sign in as several people without one of them inheriting
+ * the other's session.
+ *
+ * It also stamps `Origin`, because Better Auth rejects a state-changing POST
+ * whose Origin does not match its baseURL.
+ */
+export const createCookieJar = (apiUrl) => {
+    const jar = new Map();
+    const origin = new URL(apiUrl).origin;
+    return {
+        fetch: async (input, init) => {
+            const headers = new Headers(init?.headers);
+            headers.set('origin', origin);
+            const held = [...jar].map(([name, value]) => `${name}=${value}`);
+            const caller = headers.get('cookie');
+            if (held.length > 0 || caller) {
+                headers.set('cookie', [caller, ...held].filter(Boolean).join('; '));
+            }
+            const response = await fetch(input, { ...init, headers });
+            for (const raw of response.headers.getSetCookie()) {
+                const [pair] = raw.split(';');
+                const separator = pair.indexOf('=');
+                if (separator > 0) {
+                    const name = pair.slice(0, separator);
+                    const value = pair.slice(separator + 1);
+                    // An empty value is how a target deletes a cookie — drop the name
+                    // rather than holding a cookie whose value says it is gone.
+                    if (value) {
+                        jar.set(name, value);
+                    }
+                    else {
+                        jar.delete(name);
+                    }
+                }
+            }
+            return response;
+        },
+        clear: () => jar.clear(),
+        get empty() {
+            return jar.size === 0;
+        },
+    };
+};

package/dist/wirings/workflow/scenario-poll.d.ts

@@ -0,0 +1,20 @@
+/** How long to keep trying, and how long to wait between tries. */
+export interface PollOptions {
+    /** Total time to keep attempting before giving up. Default 15s. */
+    timeoutMs?: number;
+    /** Gap between attempts. Default 250ms. */
+    intervalMs?: number;
+}
+/**
+ * Attempt something until it answers, or the deadline passes.
+ *
+ * `undefined` means "not yet" and nothing else — `false`, `0` and `''` are all
+ * answers, because a probe asking whether something happened reports `false`
+ * when it did not. Answering `undefined` at the deadline rather than throwing
+ * leaves the error to the caller, who is the only one who knows what was being
+ * waited for.
+ *
+ * A step that polls its target — a delivery reaching a terminal status, a run
+ * finishing — reaches for this rather than writing the deadline loop again.
+ */
+export declare const pollUntil: <T>(attempt: () => Promise<T | undefined> | T | undefined, { timeoutMs, intervalMs }?: PollOptions) => Promise<T | undefined>;

package/dist/wirings/workflow/scenario-poll.js

@@ -0,0 +1,25 @@
+/**
+ * Attempt something until it answers, or the deadline passes.
+ *
+ * `undefined` means "not yet" and nothing else — `false`, `0` and `''` are all
+ * answers, because a probe asking whether something happened reports `false`
+ * when it did not. Answering `undefined` at the deadline rather than throwing
+ * leaves the error to the caller, who is the only one who knows what was being
+ * waited for.
+ *
+ * A step that polls its target — a delivery reaching a terminal status, a run
+ * finishing — reaches for this rather than writing the deadline loop again.
+ */
+export const pollUntil = async (attempt, { timeoutMs = 15_000, intervalMs = 250 } = {}) => {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const answer = await attempt();
+        if (answer !== undefined) {
+            return answer;
+        }
+        if (Date.now() >= deadline) {
+            return undefined;
+        }
+        await new Promise((done) => setTimeout(done, intervalMs));
+    }
+};