@pikku/core 0.12.67 → 0.12.70

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

@@ -0,0 +1,38 @@
+import type { ScenarioStepPhase } from './scenario-step.types.js';
+/**
+ * Renders the English sentence a reporter shows for a scenario step.
+ *
+ * This is the inversion of cucumber: rather than parsing English into a call,
+ * we render English out of a typed call, so the readable report survives
+ * without a regex registry paying for it.
+ *
+ * Lives in core so the CLI reporter and the console render identically.
+ */
+/**
+ * Fill a step's `template` from the input that step was actually called with,
+ * so the reported sentence names the values under test — "sees @pikku/addon-todos"
+ * rather than "sees an addon in the gallery" repeated three times.
+ *
+ * A placeholder with no recorded value renders as nothing and the surrounding
+ * whitespace collapses, so an optional input that was omitted reads as a shorter
+ * sentence rather than a literal `{state}` leaking into the report.
+ */
+export declare const renderStepTemplate: (template: string, input: unknown) => string;
+export declare const composeStepProse: ({ phase, description, template, input, actor, keywordWidth, }: {
+    phase: ScenarioStepPhase;
+    description: string;
+    /**
+     * The prose this step renders, with `{placeholders}` filled from `input`.
+     * Unlike `description`, which documents what the step does, this is what a
+     * reader of the report sees. Falls back to `description` when absent.
+     */
+    template?: string;
+    /** The input this step was called with, as recorded on the run. */
+    input?: unknown;
+    actor?: string;
+    /**
+     * Pad the keyword to this width so a ladder of steps lines its sentences up
+     * under each other. Omit for inline prose.
+     */
+    keywordWidth?: number;
+}) => string;

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

@@ -0,0 +1,45 @@
+/**
+ * Renders the English sentence a reporter shows for a scenario step.
+ *
+ * This is the inversion of cucumber: rather than parsing English into a call,
+ * we render English out of a typed call, so the readable report survives
+ * without a regex registry paying for it.
+ *
+ * Lives in core so the CLI reporter and the console render identically.
+ */
+/**
+ * Fill a step's `template` from the input that step was actually called with,
+ * so the reported sentence names the values under test — "sees @pikku/addon-todos"
+ * rather than "sees an addon in the gallery" repeated three times.
+ *
+ * A placeholder with no recorded value renders as nothing and the surrounding
+ * whitespace collapses, so an optional input that was omitted reads as a shorter
+ * sentence rather than a literal `{state}` leaking into the report.
+ */
+export const renderStepTemplate = (template, input) => {
+    const values = input && typeof input === 'object' ? input : {};
+    return template
+        .replace(/\{(\w+)\}/g, (_match, key) => formatValue(values[key]))
+        .replace(/\s+/g, ' ')
+        .trim();
+};
+const formatValue = (value) => {
+    if (value === undefined || value === null) {
+        return '';
+    }
+    if (typeof value === 'object') {
+        return JSON.stringify(value);
+    }
+    return String(value);
+};
+export const composeStepProse = ({ phase, description, template, input, actor, keywordWidth, }) => {
+    const keyword = phase === 'step' ? '' : capitalise(phase);
+    const subject = actor ? `the ${actor}` : '';
+    const rendered = template ? renderStepTemplate(template, input) : description;
+    const sentence = [subject, rendered].filter(Boolean).join(' ');
+    if (keywordWidth === undefined) {
+        return [keyword, sentence].filter(Boolean).join(' ');
+    }
+    return `${keyword.padEnd(keywordWidth)} ${sentence}`;
+};
+const capitalise = (value) => value.charAt(0).toUpperCase() + value.slice(1);

package/dist/wirings/workflow/scenario-step-guards.d.ts

@@ -0,0 +1,16 @@
+import type { PikkuScenarioStepWire, ScenarioEnvironment } from './scenario-step.types.js';
+/**
+ * The actor this step was called with, or a loud error naming the step.
+ *
+ * A step that talks to the target app needs an identity, but `actor` is
+ * optional on the wire because a pure assertion step needs none. This is the
+ * one place that narrowing happens, so every step file stops writing its own
+ * `actorOf(...)` guard.
+ */
+export declare const requireActor: <TActor>(scenarioStep: PikkuScenarioStepWire<TActor> | undefined) => TActor;
+/**
+ * The environment this run targets, or a loud error naming the step. A run
+ * started outside `pikku scenario run` only carries one when the server has
+ * `API_URL` configured.
+ */
+export declare const requireScenarioEnv: (scenarioStep: PikkuScenarioStepWire<unknown> | undefined) => ScenarioEnvironment;

package/dist/wirings/workflow/scenario-step-guards.js

@@ -0,0 +1,29 @@
+/**
+ * The actor this step was called with, or a loud error naming the step.
+ *
+ * A step that talks to the target app needs an identity, but `actor` is
+ * optional on the wire because a pure assertion step needs none. This is the
+ * one place that narrowing happens, so every step file stops writing its own
+ * `actorOf(...)` guard.
+ */
+export const requireActor = (scenarioStep) => {
+    const actor = scenarioStep?.actor;
+    if (!actor) {
+        throw new Error(`[scenario] step '${scenarioStep?.name ?? 'unknown'}' was called without an actor. ` +
+            `Pass { actor: actors.<name> } so it runs as that persona.`);
+    }
+    return actor;
+};
+/**
+ * The environment this run targets, or a loud error naming the step. A run
+ * started outside `pikku scenario run` only carries one when the server has
+ * `API_URL` configured.
+ */
+export const requireScenarioEnv = (scenarioStep) => {
+    const env = scenarioStep?.env;
+    if (!env) {
+        throw new Error(`[scenario] step '${scenarioStep?.name ?? 'unknown'}' needs the target environment, but this run carries none. ` +
+            `Run it through 'pikku scenario run <environment>' with scenarios.environments.<environment> declared in pikku.config.json.`);
+    }
+    return env;
+};

package/dist/wirings/workflow/scenario-step.types.d.ts

@@ -0,0 +1,148 @@
+import type { ScenarioActor } from '../../services/scenario-actors-service.js';
+/**
+ * Scenario steps: named, typed units of scenario behaviour.
+ *
+ * A step's body is an ordinary pikku function, so it may drive a browser, call
+ * an RPC as its actor, or run a workflow. `given`/`when`/`then` are sugar over
+ * `step` — they only change the prose the reporter renders.
+ */
+/**
+ * Which Gherkin-style keyword the reporter prefixes this step with. `step`
+ * renders no prefix at all.
+ */
+export type ScenarioStepPhase = 'step' | 'given' | 'when' | 'then';
+/**
+ * Options accepted by `scenario.step/given/when/then`.
+ *
+ * Note the retry default differs from an ordinary workflow step: retrying a
+ * failed assertion is the wrong behaviour for a test primitive, so steps
+ * default to no retries.
+ */
+export interface ScenarioStepOptions {
+    /** The actor this step runs as. Required for steps declaring `browser: true`. */
+    actor?: unknown;
+    /** Overrides the step's own `description` for this call site only. */
+    description?: string;
+    /** Defaults to 0 for steps — a failed assertion must not be retried. */
+    retries?: number;
+    retryDelay?: number | string;
+}
+/**
+ * The environment a scenario run targets, as declared in pikku.config.json
+ * under `scenarios.environments`.
+ */
+export interface ScenarioEnvironment {
+    /** Base API URL of the target app, INCLUDING the HTTP prefix. */
+    apiUrl: string;
+    /** Base URL of the app's UI, for environments with browser steps. */
+    appUrl?: string;
+}
+/**
+ * The `scenarioStep` wire, present on every scenario step invocation.
+ *
+ * `TActor` is the project's own actor type, so a step reaches only the RPCs its
+ * actors can actually call. It defaults to the open `ScenarioActor` for a
+ * project that declares no registry.
+ */
+export interface PikkuScenarioStepWire<TActor = ScenarioActor> {
+    /** Registered step name (also its pikkuFuncId) */
+    name: string;
+    /** Durable key within the run; may carry an `#ordinal` suffix when repeated */
+    stepName: string;
+    runId: string;
+    phase: ScenarioStepPhase;
+    /**
+     * The actor this step runs as, when one was given. Call RPCs through it
+     * (`actor.invoke(...)`) so they run against the target environment as that
+     * persona.
+     */
+    actor?: TActor;
+    /**
+     * The environment this run targets. A step runs in the CLI process, where
+     * there is no `variables` service — this is how a raw-HTTP step learns the
+     * target's URL without reaching for `process.env`.
+     */
+    env?: ScenarioEnvironment;
+}
+/**
+ * How a browser step names an element.
+ *
+ * A `data-testid` on its own is rarely enough to name exactly one: `where`
+ * matches the element's own data attributes (so a step asserts a status
+ * without reading translated copy back to the app), `prefix` matches a family
+ * of ids, `containing` picks the match holding a piece of text, and `within`
+ * scopes the lookup to one row or section.
+ *
+ * Declared here so a step's input type is structural; the driver
+ * (`@pikku/playwright`) is what resolves it against a real page.
+ */
+export interface TestIdSelector {
+    testId: string;
+    /** Match every test id beginning with `testId`, e.g. every `flow-card-*`. */
+    prefix?: boolean;
+    /** Data attributes the element must also carry, e.g. `{ 'data-open': 'true' }`. */
+    where?: Record<string, string>;
+    /** Narrow to the one match holding this text. */
+    containing?: string;
+    /** Scope the lookup to one enclosing element, e.g. the row for one user. */
+    within?: TestIdSelector;
+}
+/**
+ * Structural browser handle, present only when the runner provisioned a
+ * browser for this step (`browser: true` on the step config).
+ *
+ * `@pikku/core` deliberately never imports playwright — it must stay
+ * dependency-free for edge runtimes. `@pikku/playwright` augments this
+ * interface via `declare module`, so `wire.browser.page` is a fully typed
+ * Playwright `Page` in a project that installs it.
+ */
+export interface PikkuBrowserWire {
+    /** The actor whose browser context this is */
+    readonly actor: string;
+    goto(url: string): Promise<void>;
+    screenshot(name?: string): Promise<Uint8Array>;
+}
+/**
+ * What one actor's window looked like at the moment a scenario failed.
+ *
+ * A browser step fails with a selector timeout that says nothing about *why*
+ * the page never rendered. The answer is almost always in the page's own
+ * errors, which the driver has been collecting all along.
+ */
+export interface ScenarioBrowserFailure {
+    /** The actor whose window this is. */
+    actor: string;
+    /** Where the window was pointed, when the driver can still report it. */
+    url?: string;
+    /** Path the screenshot was written to; absent when none could be taken. */
+    screenshot?: string;
+    consoleErrors: string[];
+    pageErrors: string[];
+    failedRequests: string[];
+    apiErrors: string[];
+}
+/**
+ * Supplied by `@pikku/playwright` (or any other driver) and consumed by the
+ * scenario runner. Declared here so the CLI depends only on core.
+ *
+ * `reset` and `captureFailure` are optional so a driver written against an
+ * earlier version keeps compiling; the runner treats a driver without them as
+ * one that simply offers no isolation and no diagnostics.
+ */
+export interface ScenarioBrowserProvider {
+    /** Resolve — creating on first use — the browser session for an actor. */
+    sessionFor(actorName: string): Promise<PikkuBrowserWire>;
+    /**
+     * Discard every actor's per-scenario state — cookies, storage, open pages —
+     * while keeping the browser itself. Called between scenarios, so one
+     * scenario cannot leave the next signed in as somebody else.
+     */
+    reset?(): Promise<void>;
+    /**
+     * Snapshot every open window for a failed scenario. `label` identifies the
+     * scenario in artifact filenames. Never throws: a failure to capture must
+     * not replace the failure being captured.
+     */
+    captureFailure?(label: string): Promise<ScenarioBrowserFailure[]>;
+    close(): Promise<void>;
+}

package/dist/wirings/workflow/scenario-step.types.js

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

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

@@ -1,7 +1,9 @@
 import type { SerializedError, CommonWireMeta } from '../../types/core.types.js';
-import type { CorePikkuFunctionConfig } from '../../function/functions.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, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, PikkuScenarioWire, } from './dsl/workflow-dsl.types.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 { ScenarioStepPhase, ScenarioStepOptions, PikkuScenarioStepWire, PikkuBrowserWire, ScenarioBrowserProvider, } from './scenario-step.types.js';
 import type { WorkflowStepMeta } from './dsl/workflow-dsl.types.js';
 export interface WorkflowRunWire {
     type: string;
@@ -18,6 +20,43 @@ export interface WorkflowServiceConfig {
     stepWorkerQueueName: string;
     sleeperRPCName: string;
 }
+/**
+ * How a workflow service spreads its jobs across queues.
+ *
+ * Passed to the service constructor rather than read from `config.workflow`:
+ * the queues are wired during construction, before singleton services (and so
+ * before `config`) exist.
+ */
+export interface WorkflowQueueOptions {
+    /**
+     * - `'per-workflow'` (default) — each workflow gets its own
+     *   `wf-orchestrator-*` / `wf-step-*` queue. Complete isolation, and it's
+     *   what lets serverless providers deploy one unit per workflow. Costs one
+     *   set of pollers per queue, which adds up on pull-based backends.
+     * - `'shared-groups'` — every workflow shares the orchestrator/step-worker
+     *   queues and stays isolated via {@link queueGroupConcurrency}, so no
+     *   workflow can occupy more than its share. One set of pollers total.
+     *   Only for single-process (monolith) runtimes; a per-unit serverless
+     *   deploy needs the per-workflow queues to route to its units.
+     */
+    queueStrategy?: 'per-workflow' | 'shared-groups';
+    /**
+     * Total concurrent workflow jobs per node under `'shared-groups'`.
+     * Defaults to 20.
+     */
+    queueConcurrency?: number;
+    /**
+     * How many jobs of one workflow may run at once under `'shared-groups'`.
+     * Defaults to 2. Tiers are keyed by workflow name, so a specific workflow
+     * can be given its own limit without any extra wiring.
+     *
+     * Note tiers can only lower a workflow's limit, not raise it above
+     * `default`: the backend's pre-fetch exclusion is applied per group using
+     * `default` alone. To give one workflow more room, raise `default` and
+     * restrict the others by tier.
+     */
+    queueGroupConcurrency?: number | GroupConcurrencyConfig;
+}
 export interface WorkflowPlannedStep {
     /** Durable step key — matches the runtime step name stored in the DB */
     stepName: string;
@@ -197,6 +236,77 @@ export type CoreWorkflow<PikkuFunctionConfig extends CorePikkuFunctionConfig<any
     /** Tags for organization and filtering */
     tags?: string[];
 };
+/**
+ * A scenario as a feature references it: either the scenario itself, or the
+ * scenario paired with the input to run it with. The paired form is gherkin's
+ * `Examples:` — the same scenario run once per row, written as an ordinary
+ * loop rather than a table.
+ */
+export type CoreFeatureScenario = CorePikkuFunctionConfig<any, any, any> | {
+    scenario: CorePikkuFunctionConfig<any, any, any>;
+    data: unknown;
+};
+/**
+ * A feature: an ordered group of scenarios, mirroring gherkin's Feature ↔
+ * Scenario structure. Scenarios are referenced by imported identifier, so a
+ * renamed or deleted scenario is a compile error rather than a silent skip.
+ *
+ * Hooks run **once around the whole group** (`before → a → b → c → after`),
+ * not per scenario — per-scenario setup is the scenario's own `before`. That
+ * is the one thing a feature deliberately cannot express: gherkin's
+ * `Background:` runs per scenario.
+ */
+export type CoreFeature = {
+    /** Human-readable name. The export identifier is the id. */
+    name: string;
+    description?: string;
+    tags?: string[];
+    /** Readonly because `pikkuFeature`'s `const` generic infers a readonly tuple. */
+    scenarios: readonly CoreFeatureScenario[];
+    before?: CorePikkuFunctionHook;
+    after?: CorePikkuFunctionHook;
+};
+/** One entry of a feature's scenario list, as extracted from the source. */
+export type FeatureMetaEntry = {
+    /** The scenario's declared export name — its key in `WorkflowsMeta`. */
+    scenario: string;
+    /** The input this entry runs the scenario with — gherkin's `Examples:`. */
+    data?: unknown;
+};
+/**
+ * A feature as the console reads it: the document structure around a group of
+ * scenarios. Generated to `scenarios/features.gen.json` and read off disk, so
+ * nothing app-facing has to import the scenario bootstrap to describe one.
+ */
+export type FeatureMeta = {
+    /** The export identifier. */
+    id: string;
+    name: string;
+    description?: string;
+    tags: string[];
+    /** In declared order — a feature's reading order is its declaration order. */
+    entries: FeatureMetaEntry[];
+    /**
+     * Entries that could not be read statically (a spread, a `.map()`). Their
+     * membership is only known once the scenario bootstrap has been evaluated,
+     * so a non-zero count means this listing is partial.
+     */
+    unresolvedEntries: number;
+    /** Hooks are runtime-only; only their presence is knowable from meta. */
+    hasBefore: boolean;
+    hasAfter: boolean;
+};
+export type FeaturesMeta = Record<string, FeatureMeta>;
+/** One planned scenario run, resolved from a feature's scenario list. */
+export type FeaturePlanEntry = {
+    featureId: string;
+    featureName: string;
+    scenarioName: string;
+    /** The input this entry runs the scenario with, if the feature supplied one. */
+    data?: unknown;
+    /** The scenario's own tags unioned with the containing feature's. */
+    tags: string[];
+};
 /**
  * Workflow client interface
  */
@@ -236,6 +346,13 @@ export type WorkflowsMeta = Record<string, CommonWireMeta & {
     expose?: boolean;
     /** True for pikkuScenario workflows (complex + actor steps). */
     scenario?: boolean;
+    /**
+     * Why a scenario is held out of a default run. Stating the reason in code
+     * keeps the quarantine next to the scenario it applies to, rather than in
+     * a CI invocation nobody reads. Naming the scenario with `--flows` runs it
+     * regardless.
+     */
+    skip?: string;
     /** Actor names a scenario declares (personas it runs steps as). */
     actors?: string[];
 }>;

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.67",
+  "version": "0.12.70",
+  "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",
@@ -22,6 +23,7 @@
     "./function": "./dist/function/index.js",
     "./channel": "./dist/wirings/channel/index.js",
     "./workflow": "./dist/wirings/workflow/index.js",
+    "./scenario": "./dist/wirings/workflow/pikku-scenario-service.js",
     "./workflow/timeline": "./dist/wirings/workflow/run-timeline.js",
     "./workflow/types": "./dist/wirings/workflow/workflow.types.js",
     "./actor-flow": "./dist/wirings/actor-flow/index.js",

package/src/function/functions.types.ts

@@ -248,6 +248,17 @@ export type CorePermissionGroup<PikkuPermission = CorePikkuPermission<any>> =
   | Record<string, PikkuPermission | PikkuPermission[]>
   | undefined
 
+/**
+ * A lifecycle hook: the same call signature as the function it hangs off, but
+ * its return value is discarded. A hook is setup/teardown, not a step — it has
+ * no id, no meta and no schema, so it is never recorded and never replayed.
+ */
+export type CorePikkuFunctionHook<Services = any, Data = any, Wire = any> = (
+  services: Services,
+  data: Data,
+  wire: Wire
+) => Promise<void> | void
+
 export type CorePikkuFunctionConfig<
   PikkuFunction extends
     | CorePikkuFunction<any, any, any, any, any>
@@ -282,6 +293,8 @@ export type CorePikkuFunctionConfig<
   workflowRetries?: number
   /** Timeout for this function when used as a workflow step (e.g. '30s', '5m'). */
   workflowTimeout?: string
+  /** Scenario steps only: this step drives a browser, so the runner must provision one before calling it. */
+  browser?: boolean
   audit?:
     | boolean
     | {
@@ -289,6 +302,25 @@ export type CorePikkuFunctionConfig<
       }
   approvalDescription?: any
   func: PikkuFunction
+  /**
+   * Scenarios only: runs before the scenario body, with the scenario's own
+   * signature. Throwing skips the body and fails the run, but `after` still
+   * runs.
+   */
+  before?: CorePikkuFunctionHook
+  /**
+   * Scenarios only: always runs after the scenario body, in a `finally`.
+   * Throwing fails a run that would otherwise have passed; on an
+   * already-failed run it attaches as the `cause` and never replaces the
+   * original error.
+   */
+  after?: CorePikkuFunctionHook
+  /**
+   * Scenarios only: why this scenario is held out of a default run. It is
+   * reported as skipped rather than quietly omitted, and naming it directly
+   * with `--flows` runs it anyway.
+   */
+  skip?: string
   auth?: boolean
   /**
    * Scopes the session must hold to run this function. All of them are

package/src/index.ts

@@ -55,6 +55,7 @@ export type {
   CorePikkuAuthConfig,
   CorePikkuFunction,
   CorePikkuFunctionConfig,
+  CorePikkuFunctionHook,
   CorePikkuPermission,
   CorePikkuPermissionConfig,
   CorePikkuPermissionFactory,

package/src/internal.ts

@@ -1,4 +1,8 @@
-export { pikkuState, resetPikkuState } from './pikku-state.js'
+export {
+  pikkuState,
+  resetPikkuState,
+  getAllPackageStates,
+} from './pikku-state.js'
 export { httpRouter } from './wirings/http/routers/http-router.js'
 export type {
   CreateSingletonServices,

package/src/pikku-state.ts

@@ -104,6 +104,7 @@ const createEmptyPackageState = (): PikkuPackageState => ({
   },
   workflows: {
     registrations: new Map(),
+    features: new Map(),
     meta: {},
   },
   trigger: {

package/src/services/http-scenario-actors.test.ts

@@ -38,11 +38,27 @@ const startTarget = async () => {
           res.writeHead(401).end()
           return
         }
+        const rpcName = req.url.slice('/api/rpc/'.length)
+        if (rpcName === 'html-error') {
+          res
+            .writeHead(500, { 'content-type': 'text/html' })
+            .end('<html><body>Gateway blew up</body></html>')
+          return
+        }
+        if (rpcName === 'forbidden') {
+          res
+            .writeHead(403, { 'content-type': 'application/json' })
+            .end(
+              JSON.stringify({ message: 'MissingScopeError', scope: 'admin' })
+            )
+          return
+        }
         res.writeHead(200, { 'content-type': 'application/json' }).end(
           JSON.stringify({
-            rpcName: req.url.slice('/api/rpc/'.length),
+            rpcName,
             echoed: body.data,
             cookie,
+            userHeader: req.headers['x-user-id'] ?? null,
           })
         )
         return
@@ -115,6 +131,74 @@ describe('HttpScenarioActor', async () => {
     assert.match(result.cookie, new RegExp(`session=s${loginsBefore + 1}`))
   })
 
+  test('invokeRaw returns the status and body instead of throwing', async () => {
+    const actors = makeActors()
+
+    // A refusal is the expected outcome of a permissions scenario, so the
+    // status and the payload that names the missing scope both have to survive.
+    const res = await actors.customer!.invokeRaw('forbidden', {})
+
+    assert.equal(res.status, 403)
+    assert.equal(res.ok, false)
+    assert.deepEqual(res.body, {
+      message: 'MissingScopeError',
+      scope: 'admin',
+    })
+  })
+
+  test('invokeRaw reports a success the same way', async () => {
+    const actors = makeActors()
+    const res = await actors.manager!.invokeRaw('listTodos', { page: 2 })
+
+    assert.equal(res.status, 200)
+    assert.equal(res.ok, true)
+    assert.deepEqual((res.body as any).echoed, { page: 2 })
+  })
+
+  test('invokeRaw carries the response text so a step can search it', async () => {
+    const actors = makeActors()
+    const res = await actors.customer!.invokeRaw('forbidden', {})
+
+    assert.match(res.serialized, /MissingScopeError/)
+    assert.match(res.serialized, /admin/)
+  })
+
+  test('invokeRaw keeps a non-JSON error body instead of failing to parse it', async () => {
+    const actors = makeActors()
+    const res = await actors.manager!.invokeRaw('html-error', {})
+
+    assert.equal(res.status, 500)
+    assert.equal(res.ok, false)
+    assert.equal(res.body, '<html><body>Gateway blew up</body></html>')
+    assert.match(res.serialized, /Gateway blew up/)
+  })
+
+  test('invokeRaw reports an empty body as an empty string', async () => {
+    const actors = makeActors()
+    const res = await actors.manager!.invokeRaw('listTodos', {})
+
+    assert.equal(typeof res.serialized, 'string')
+  })
+
+  test('invokeRaw passes extra headers through', async () => {
+    const actors = makeActors()
+    const res = await actors.manager!.invokeRaw(
+      'whoAmI',
+      {},
+      { headers: { 'x-user-id': 'impersonated-1' } }
+    )
+
+    assert.equal((res.body as any).userHeader, 'impersonated-1')
+  })
+
+  test('invoke still throws on a refusal, naming the status and body', async () => {
+    const actors = makeActors()
+    await assert.rejects(
+      actors.customer!.invoke('forbidden', {}),
+      /'forbidden' as 'customer' returned 403.*MissingScopeError/
+    )
+  })
+
   test('a wrong impersonation secret surfaces status and body', async () => {
     const actors = makeActors('wrong-secret')
     await assert.rejects(