@pikku/core 0.12.67 → 0.12.70

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

@@ -11,7 +11,6 @@ import {
   pikkuState,
 } from '../../pikku-state.js'
 import { getDurationInMilliseconds } from '../../time-utils.js'
-import { createHttpScenarioActors } from '../../services/http-scenario-actors.js'
 
 const resolveWorkflowMeta = (
   name: string
@@ -46,10 +45,10 @@ const toKebab = (s: string) =>
   s.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()
 import type { PikkuWire, SerializedError } from '../../types/core.types.js'
 import type { QueueService } from '../queue/queue.types.js'
-import { runScheduledTask } from '../scheduler/scheduler-runner.js'
 import type {
   ApprovalOutcome,
-  PikkuScenarioWire,
+  CoreWorkflow,
+  PikkuWorkflowWire,
   StepState,
   StepStatus,
   WorkflowApprovalOptions,
@@ -60,11 +59,9 @@ import type {
   WorkflowRunWire,
   WorkflowStatus,
   WorkflowVersionStatus,
+  WorkflowQueueOptions,
   WorkflowServiceConfig,
   WorkflowStepOptions,
-  WorkflowExpectEventuallyOptions,
-  WorkflowExpectErrorOptions,
-  WorkflowExpectServiceOptions,
 } from './workflow.types.js'
 import {
   continueGraph,
@@ -88,7 +85,12 @@ import {
   type RunTimeline,
   type ReconstructedRunState,
 } from './run-timeline.js'
-import type { JobOptions } from '../queue/queue.types.js'
+import type {
+  GroupConcurrencyConfig,
+  JobGroup,
+  JobOptions,
+  PikkuWorkerConfig,
+} from '../queue/queue.types.js'
 
 /**
  * Default number of retries for a workflow step when none is specified. The
@@ -240,6 +242,101 @@ const WORKFLOW_END_STATES: ReadonlySet<string> = new Set([
   'suspended',
 ])
 
+/**
+ * Everything an extension needs to run something of its own around a run's
+ * function: the registration it was resolved from, the run itself (so `input`
+ * is the same object the function is called with), and the wire it is given.
+ */
+export interface RunLifecycleContext {
+  runId: string
+  run: WorkflowRun
+  workflowMeta: any
+  workflow: CoreWorkflow
+  wire: PikkuWire
+  packageName: string | null
+}
+
+/**
+ * The slice of the run engine an extension is allowed to drive, handed to it at
+ * construction. It exists so that recording a durable step stays available to
+ * an extension without `inlineStep` and friends becoming public API on every
+ * workflow service a production app instantiates.
+ */
+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
+}
+
+/**
+ * A capability layered onto a run without being a workflow service itself.
+ *
+ * The engine names nothing about what an extension is for: a bundler drops an
+ * unused *module* but never an unused class member, so the alternative — a
+ * subclass carrying the capability — puts it in every server built on Pikku
+ * whether or not the app ever uses it. Scenarios are the one implementation
+ * today (`PikkuScenarioService` in `@pikku/core/scenario`).
+ */
+export interface WorkflowRunExtension {
+  /** Per-run state resolved once the run has an id. */
+  attachRunContext(
+    runId: string,
+    workflowMeta: any,
+    options?: Record<string, any>
+  ): Promise<void>
+  /** Release whatever `attachRunContext` stored. */
+  detachRunContext(runId: string): void
+  /** Contribute extra members to the wire a run's function is invoked with. */
+  decorateRunWire(
+    wire: PikkuWire,
+    context: {
+      runId: string
+      workflowMeta: any
+      workflowWire: PikkuWorkflowWire
+    }
+  ): void
+  /** Contribute extra members to the workflow wire itself, in place. */
+  decorateWorkflowWire(
+    workflowWire: PikkuWorkflowWire,
+    context: {
+      name: string
+      runId: string
+      rpcService: any
+      addonNamespace?: string | null
+    }
+  ): void
+  /**
+   * Called immediately before the run's function, inside the run lock. Throwing
+   * skips the function and fails the run.
+   */
+  onBeforeRunFunc(context: RunLifecycleContext): Promise<void>
+  /**
+   * Called once the run reaches a terminal state, in a `finally`, so it runs
+   * whether the function passed or threw. `interrupted` means the run suspended
+   * or went async and is still mid-flight. Throwing here propagates, replacing
+   * a pending failure, so an extension that must not mask one handles that
+   * itself.
+   */
+  onAfterRunFunc(
+    context: RunLifecycleContext,
+    outcome: 'completed' | 'failed' | 'interrupted',
+    failure: unknown
+  ): Promise<void>
+}
+
 /**
  * Abstract workflow state service
  * Implementations provide pluggable storage backends (SQLite, PostgreSQL, etc.)
@@ -247,9 +344,7 @@ const WORKFLOW_END_STATES: ReadonlySet<string> = new Set([
  */
 export abstract class PikkuWorkflowService implements WorkflowService {
   private inlineRuns = new Set<string>()
-  // User-flow actors per run: live authenticated clients (cookie jars) are
-  // process-local by nature, so they ride this map, never the persisted wire.
-  private runActors = new Map<string, ScenarioActors>()
+  private runExtension?: WorkflowRunExtension
 
   protected get logger() {
     return getSingletonServices()?.logger
@@ -257,11 +352,21 @@ export abstract class PikkuWorkflowService implements WorkflowService {
 
   protected mirror?: WorkflowRunMirror
 
+  protected readonly queueStrategy: 'per-workflow' | 'shared-groups'
+  protected readonly queueConcurrency: number
+  protected readonly queueGroupConcurrency: number | GroupConcurrencyConfig
+
   constructor(
-    options: { wireQueues?: boolean; mirror?: WorkflowRunMirror } = {}
+    options: {
+      wireQueues?: boolean
+      mirror?: WorkflowRunMirror
+    } & WorkflowQueueOptions = {}
   ) {
     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()
     }
@@ -306,29 +411,44 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     const registerWorkflowFunc = (
       funcId: string,
       func: { func: unknown },
-      queueName: string
+      queueName: string,
+      config?: PikkuWorkerConfig
     ) => {
       if (functions.has(funcId)) return
       addFunction(funcId, func as never)
       if (!queueMeta[queueName]) {
         queueMeta[queueName] = { pikkuFuncId: funcId, name: queueName }
       }
-      wireQueueWorker({ name: queueName, func } as never)
+      wireQueueWorker({ name: queueName, func, config } as never)
       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: PikkuWorkerConfig | undefined = sharedGroups
+      ? {
+          batchSize: this.queueConcurrency,
+          groupConcurrency: this.queueGroupConcurrency,
+        }
+      : undefined
+
     // Register shared queue workers for monolith deployments
     registerWorkflowFunc(
       'pikkuWorkflowOrchestrator',
       { func: pikkuWorkflowOrchestratorFunc },
-      'pikku-workflow-orchestrator'
+      'pikku-workflow-orchestrator',
+      sharedQueueConfig
     )
     registerWorkflowFunc(
       'pikkuWorkflowStepWorker',
       { func: pikkuWorkflowWorkerFunc },
-      'pikku-workflow-step-worker'
+      'pikku-workflow-step-worker',
+      sharedQueueConfig
     )
 
     // Register per-workflow queue workers (root + addon packages)
@@ -351,18 +471,41 @@ export abstract class PikkuWorkflowService implements WorkflowService {
       }
     }
 
-    registerQueueWorkers(pikkuState(null, 'queue', 'meta'))
+    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)
+      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,
@@ -577,7 +720,10 @@ export abstract class PikkuWorkflowService implements WorkflowService {
    * 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
@@ -927,7 +1073,10 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     await queueService.add(
       this.getOrchestratorQueueName(workflowName),
       { runId },
-      this.resolveStepJobOptions()
+      {
+        ...this.resolveStepJobOptions(),
+        group: this.getJobGroup(workflowName),
+      }
     )
   }
 
@@ -970,7 +1119,12 @@ export abstract class PikkuWorkflowService implements WorkflowService {
       JSON.parse(
         JSON.stringify({ runId, stepName, rpcName, data, fromStepName })
       ),
-      this.resolveStepJobOptions(stepOptions)
+      {
+        ...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),
+      }
     )
   }
 
@@ -1005,7 +1159,12 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     await queueService.add(
       this.getOrchestratorQueueName(workflowName),
       { runId },
-      retryDelay ? { delay: getDurationInMilliseconds(retryDelay) } : undefined
+      {
+        ...(retryDelay
+          ? { delay: getDurationInMilliseconds(retryDelay) }
+          : undefined),
+        group: this.getJobGroup(workflowName),
+      }
     )
   }
 
@@ -1054,7 +1213,10 @@ export abstract class PikkuWorkflowService implements WorkflowService {
         JSON.parse(
           JSON.stringify({ runId, stepName, rpcName, data, fromStepName })
         ),
-        this.resolveStepJobOptions(stepOptions)
+        {
+          ...this.resolveStepJobOptions(stepOptions),
+          group: this.getJobGroup(rpcName),
+        }
       )
     } catch (cause) {
       // The queue is down/unreachable — NOT a step failure. Surface it as a
@@ -1092,37 +1254,28 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     return true
   }
 
-  /** Build HTTP scenario actors for a run started without them; undefined when SCENARIO_ACTOR_SECRET or the API URL is missing */
-  private async resolveScenarioActors(): Promise<ScenarioActors | undefined> {
-    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
+  /**
+   * 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.
+   */
+  public setRunExtension<T extends WorkflowRunExtension>(
+    create: (engine: WorkflowRunEngine) => T
+  ): T {
+    const engine: WorkflowRunEngine = {
+      inlineStep: this.inlineStep.bind(this),
+      updateRunStatus: this.updateRunStatus.bind(this),
+      onChildWorkflowFailed: this.onChildWorkflowFailed.bind(this),
+      verifyStepName: this.verifyStepName.bind(this),
     }
-    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,
-    })
+    const extension = create(engine)
+    this.runExtension = extension
+    return extension
+  }
+
+  public getRunExtension(): WorkflowRunExtension | undefined {
+    return this.runExtension
   }
 
   /**
@@ -1130,13 +1283,21 @@ export abstract class PikkuWorkflowService implements WorkflowService {
    * 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.
    */
   public async startWorkflow<I>(
     name: string,
     input: I,
     wire: WorkflowRunWire,
     rpcService: any,
-    options?: { inline?: boolean; startNode?: string; actors?: ScenarioActors }
+    options?: {
+      inline?: boolean
+      startNode?: string
+      actors?: ScenarioActors
+      onRunCreated?: (runId: string) => void
+    }
   ): Promise<{ runId: string }> {
     // Resolve workflow from static meta (root or addon namespace), then dynamic DB
     const resolved = resolveWorkflowMeta(name)
@@ -1200,14 +1361,9 @@ export abstract class PikkuWorkflowService implements WorkflowService {
       }
     )
 
-    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)
@@ -1244,7 +1400,7 @@ export abstract class PikkuWorkflowService implements WorkflowService {
         }
       } finally {
         this.inlineRuns.delete(runId)
-        this.runActors.delete(runId)
+        this.runExtension?.detachRunContext(runId)
       }
     } else {
       await this.resumeWorkflow(runId)
@@ -1415,15 +1571,33 @@ export abstract class PikkuWorkflowService implements WorkflowService {
       workflowWire.pikkuUserId = run.wire?.pikkuUserId
       const wire: PikkuWire = {
         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: RunLifecycleContext = {
+        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' | 'failed' | 'interrupted' = 'completed'
+      let failure: any
       try {
+        await this.runExtension?.onBeforeRunFunc(lifecycle)
+
         const result = await runPikkuFunc(
           'workflow',
           workflowMeta.name,
@@ -1440,11 +1614,15 @@ export abstract class PikkuWorkflowService implements WorkflowService {
         await this.updateRunStatus(runId, 'completed', result)
         await this.onChildWorkflowCompleted(run, result)
       } catch (error: any) {
+        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: '',
@@ -1455,6 +1633,7 @@ export abstract class PikkuWorkflowService implements WorkflowService {
         }
 
         if (error instanceof WorkflowSuspendedException) {
+          outcome = 'interrupted'
           await this.updateRunStatus(runId, 'suspended', undefined, {
             message: error.message || 'Workflow suspended',
             stack: '',
@@ -1463,6 +1642,7 @@ export abstract class PikkuWorkflowService implements WorkflowService {
           throw error
         }
 
+        outcome = 'failed'
         await this.updateRunStatus(runId, 'failed', undefined, {
           message: error.message,
           stack: error.stack,
@@ -1471,6 +1651,8 @@ export abstract class PikkuWorkflowService implements WorkflowService {
         await this.onChildWorkflowFailed(run, error)
 
         throw error
+      } finally {
+        await this.runExtension?.onAfterRunFunc(lifecycle, outcome, failure)
       }
     })
   }
@@ -1489,7 +1671,7 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     await this.resumeWorkflow(parentRunId)
   }
 
-  private async onChildWorkflowFailed(
+  protected async onChildWorkflowFailed(
     childRun: WorkflowRun,
     error: Error
   ): Promise<void> {
@@ -2018,11 +2200,25 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     )
   }
 
-  private async inlineStep(
+  protected async inlineStep(
     runId: string,
     logicalStepName: string,
     fn: Function,
-    stepOptions?: WorkflowStepOptions
+    stepOptions?: WorkflowStepOptions,
+    /**
+     * 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: any = 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: string | null = null
   ): Promise<any> {
     const fromStepName = this.lastStepName(runId)
     const stepName = this.nextStepKey(runId, logicalStepName)
@@ -2031,12 +2227,12 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     try {
       stepState = await this.getStepState(runId, stepName)
     } catch {
-      // Step doesn't exist - create it (inline, no RPC)
+      // Step doesn't exist - create it (inline, so never dispatched)
       stepState = await this.insertStepState(
         runId,
         stepName,
-        null,
-        null,
+        rpcName,
+        data,
         stepOptions,
         fromStepName
       )
@@ -2225,7 +2421,11 @@ export abstract class PikkuWorkflowService implements WorkflowService {
       await queueService.add(
         this.getOrchestratorQueueName(run.workflow),
         { runId },
-        { ...this.resolveStepJobOptions(), delay }
+        {
+          ...this.resolveStepJobOptions(),
+          delay,
+          group: this.getJobGroup(run.workflow),
+        }
       )
     } catch (error) {
       this.logger?.warn(
@@ -2420,8 +2620,8 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     runId: string,
     rpcService: any,
     addonNamespace?: string | null
-  ): PikkuScenarioWire {
-    const workflowWire: PikkuScenarioWire = {
+  ): PikkuWorkflowWire {
+    const workflowWire: PikkuWorkflowWire = {
       name,
       runId,
       getRun: async () => (await this.getRun(runId)) as WorkflowRun,
@@ -2457,146 +2657,6 @@ export abstract class PikkuWorkflowService implements WorkflowService {
         }
       },
 
-      // 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: string,
-        rpcName: string,
-        data: any,
-        predicate: (output: any) => boolean,
-        options?: WorkflowExpectEventuallyOptions
-      ) => {
-        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: any
-            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: string,
-        rpcName: string,
-        data: any,
-        options?: WorkflowExpectErrorOptions
-      ) => {
-        this.verifyStepName(stepName)
-        const resolvedRpcName =
-          addonNamespace && !rpcName.includes(':')
-            ? `${addonNamespace}:${rpcName}`
-            : rpcName
-        return await this.inlineStep(
-          runId,
-          stepName,
-          async () => {
-            let result: any
-            try {
-              result = options?.actor
-                ? await options.actor.invoke(resolvedRpcName, data)
-                : await rpcService.rpcWithWire(resolvedRpcName, data, {})
-            } catch (e: any) {
-              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: string,
-        serviceMethod: string,
-        options?: WorkflowExpectServiceOptions
-      ) => {
-        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: Array<{
-              service: string
-              method: string
-              args: unknown[]
-            }> = 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: string, duration: string | number) => {
         this.verifyStepName(stepName)
@@ -2615,16 +2675,18 @@ export abstract class PikkuWorkflowService implements WorkflowService {
       approval: (async (reason: string, options: WorkflowApprovalOptions) => {
         this.verifyStepName(reason)
         return await this.approvalStep(runId, reason, options)
-      }) as PikkuScenarioWire['approval'],
-
-      runScheduledTask: async (taskName: string) => {
-        await runScheduledTask({ name: taskName })
-      },
+      }) as PikkuWorkflowWire['approval'],
     }
+    this.runExtension?.decorateWorkflowWire(workflowWire, {
+      name,
+      runId,
+      rpcService,
+      addonNamespace,
+    })
     return workflowWire
   }
 
-  private verifyStepName(stepName: string) {
+  protected verifyStepName(stepName: string) {
     if (typeof stepName !== 'string') {
       throw new WorkflowStepNameNotString(stepName)
     }
@@ -2655,7 +2717,7 @@ export abstract class PikkuWorkflowService implements WorkflowService {
    * queues — but it produces to them — so registrations would miss them.
    */
   protected getOrchestratorQueueName(workflowName?: string): string {
-    if (workflowName) {
+    if (workflowName && this.queueStrategy !== 'shared-groups') {
       const perWorkflow = `wf-orchestrator-${toKebab(workflowName)}`
       const meta = pikkuState(null, 'queue', 'meta')
       if (meta[perWorkflow]) {
@@ -2666,7 +2728,7 @@ export abstract class PikkuWorkflowService implements WorkflowService {
   }
 
   protected getStepWorkerQueueName(rpcName?: string): string {
-    if (rpcName) {
+    if (rpcName && this.queueStrategy !== 'shared-groups') {
       const perStep = `wf-step-${toKebab(rpcName)}`
       const meta = pikkuState(null, 'queue', 'meta')
       if (meta[perStep]) {
@@ -2675,4 +2737,20 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     }
     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.
+   */
+  protected getJobGroup(id?: string): JobGroup | undefined {
+    if (!id || this.queueStrategy !== 'shared-groups') {
+      return undefined
+    }
+    return { id, tier: id }
+  }
 }