@pikku/core 0.12.52 → 0.12.53

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## 0.12.53
+
+### Patch Changes
+
+- efb0406: Add in-process V8 precise coverage (`pikku dev --coverage` / `pikku serve --coverage`) with per-scenario attribution.
+  - `@pikku/core`: new `V8CoverageService` (node:inspector precise coverage with snapshot + reset), exposed as the optional `coverageService` singleton service.
+  - `@pikku/inspector`: function meta now records `bodyStart`/`bodyEnd` body spans (verbose meta only) so coverage can be mapped without a runtime TypeScript dependency.
+  - `@pikku/cli`: `--coverage` on `pikku dev` and `pikku serve` starts the collector in-process; `pikku scenario run --coverage` resets/snapshots the server between flows and writes `.pikku/coverage/scenario-coverage.json` with per-scenario function coverage.
+  - `@pikku/addon-console`: new exposed `takeLiveCoverage` / `resetLiveCoverage` RPCs; V8 ranges are mapped through inline source maps to original TypeScript lines (offset-based, so esbuild/tsx single-line output keeps full resolution).
+
+- fe4f5ca: Add `stub`/`spy`/`isTestRun` core utils with call recording for scenario assertions.
+  - `@pikku/core`: `StubTracker` moves here from `@pikku/cucumber` (which re-exports it), gaining `record`/`getCalls`/`reset`. New plain-import utils backed by a process-wide tracker: `stub(name, impl?)` (recording fake), `spy(name, real)` (record + pass through), `isTestRun()` (reads `PIKKU_TEST_RUN`). Nothing is injected into service factories and no new factory types exist — swap services with a plain `isTestRun()` conditional where needed. New scenario DSL steps: `workflow.expectService('email.send', { calledWith })` asserts recorded stub calls via the console RPC, `workflow.expectError(...)` walks error branches.
+  - `@pikku/cli`: `pikku dev --test` sets `PIKKU_TEST_RUN` and wraps the dev-provided default services (email) in recording spies; independent of `--coverage`, absent from production `pikku serve`. `pikku scenario run` resets recorded calls per flow.
+  - `@pikku/addon-console`: exposed `getStubCalls` / `resetStubs` RPCs next to the coverage snapshot endpoints.
+
 ## 0.12.52
 
 ### Patch Changes

package/dist/services/index.d.ts

@@ -45,3 +45,6 @@ export { NoopAuditService, createInvocationAudit, resolveAuditActorFromWire, res
 export type { AuditActor, AuditConfig, AuditDurability, AuditEvent, AuditEventBatch, AuditLog, AuditLogWriteInput, AuditOutcome, AuditService, AuditSource, ResolvedAuditConfig, } from './audit-service.js';
 export { InMemorySessionStore } from './in-memory-session-store.js';
 export type { MCPMeta, RPCMetaRecord, ServiceMeta, ServicesMetaRecord, MiddlewareDefinitionMeta, MiddlewareInstanceMeta, GroupMeta, MiddlewareGroupsMeta, PermissionDefinitionMeta, PermissionsGroupsMeta, FunctionsMeta, FunctionMeta, MiddlewareMeta, PermissionMeta, AgentsMeta, AgentMeta, EmailsMeta, EmailTemplateMeta, EmailTemplateLocaleMeta, EmailTemplateAssets, } from './meta-service.js';
+export { V8CoverageService, type CoverageService, type CoverageSnapshot, type LineHits, type ScriptCoverage, type FunctionCoverage, type CoverageRange, } from './v8-coverage-service.js';
+export { IstanbulCoverageService } from './istanbul-coverage-service.js';
+export { StubTracker, createStubProxy, getStubTracker, isTestRun, stub, spy, type StubCall, } from './stub-tracker.js';

package/dist/services/index.js

@@ -21,3 +21,6 @@ export { HttpScenarioActor, createHttpScenarioActors, } from './http-scenario-ac
 export { TypedCredentialService } from './typed-credential-service.js';
 export { NoopAuditService, createInvocationAudit, resolveAuditActorFromWire, resolveAuditConfig, } from './audit-service.js';
 export { InMemorySessionStore } from './in-memory-session-store.js';
+export { V8CoverageService, } from './v8-coverage-service.js';
+export { IstanbulCoverageService } from './istanbul-coverage-service.js';
+export { StubTracker, createStubProxy, getStubTracker, isTestRun, stub, spy, } from './stub-tracker.js';

package/dist/services/istanbul-coverage-service.d.ts

@@ -0,0 +1,12 @@
+import type { CoverageService, CoverageSnapshot } from './v8-coverage-service.js';
+/**
+ * Reads istanbul-instrumented counters from the `__coverage__` global —
+ * the coverage backend for runtimes without V8 precise coverage (e.g. Bun,
+ * where source files are instrumented at load time by a Bun loader plugin).
+ */
+export declare class IstanbulCoverageService implements CoverageService {
+    start(): Promise<void>;
+    takeCoverage(): Promise<CoverageSnapshot>;
+    reset(): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/services/istanbul-coverage-service.js

@@ -0,0 +1,41 @@
+const getCoverageGlobal = () => globalThis.__coverage__;
+/**
+ * Reads istanbul-instrumented counters from the `__coverage__` global —
+ * the coverage backend for runtimes without V8 precise coverage (e.g. Bun,
+ * where source files are instrumented at load time by a Bun loader plugin).
+ */
+export class IstanbulCoverageService {
+    async start() { }
+    async takeCoverage() {
+        const coverage = getCoverageGlobal();
+        const lineHits = new Map();
+        for (const file of Object.values(coverage ?? {})) {
+            let hits = lineHits.get(file.path);
+            if (!hits) {
+                hits = new Map();
+                lineHits.set(file.path, hits);
+            }
+            // istanbul line semantics: a statement's count belongs to its start
+            // line only, so an enclosing multi-line statement never masks an
+            // unexecuted inner statement (e.g. a throw inside a taken if).
+            for (const [id, location] of Object.entries(file.statementMap)) {
+                const count = file.s[id] ?? 0;
+                const line = location.start.line;
+                hits.set(line, Math.max(hits.get(line) ?? 0, count));
+            }
+        }
+        return { kind: 'line-hits', lineHits };
+    }
+    async reset() {
+        for (const file of Object.values(getCoverageGlobal() ?? {})) {
+            for (const id of Object.keys(file.s))
+                file.s[id] = 0;
+            for (const id of Object.keys(file.f))
+                file.f[id] = 0;
+            for (const id of Object.keys(file.b)) {
+                file.b[id] = file.b[id].map(() => 0);
+            }
+        }
+    }
+    async stop() { }
+}

package/dist/services/scenario-actors-service.d.ts

@@ -1,12 +1,5 @@
 import type { ConverseOptions, ActorFlowVerdict } from '../wirings/actor-flow/actor-flow.types.js';
-/**
- * A scenario actor: a synthetic user (a normal user row flagged `actor`) that
- * workflow steps can run as. Passed to `workflow.do(step, rpc, data, { actor })`
- * — the step then goes through the actor's authenticated client over the REAL
- * transport (auth middleware, permissions, serialization all exercised),
- * never through internal dispatch. Login is lazy: the first `invoke` signs the
- * actor in and the session is cached for the actor's lifetime.
- */
+/** A synthetic user (a user row flagged `actor`) that workflow steps run as over the real transport */
 export interface ScenarioActor<TAgentName extends string = string> {
     /** Stable actor name (the key in pikku.config.json's actor registry). */
     readonly name: string;
@@ -14,21 +7,10 @@ export interface ScenarioActor<TAgentName extends string = string> {
     readonly email: string;
     /** Invoke an exposed RPC as this actor over the real transport. */
     invoke(rpcName: string, data: unknown): Promise<unknown>;
-    /**
-     * Hold a dynamic conversation with a target Pikku AI agent, in THIS actor's
-     * persona (personality/jobTitle). Drives the target over the real transport
-     * as the signed-in actor, answers its tool-approval requests in-persona, and
-     * returns the actor's verdict on whether the task was met. Deterministic
-     * checks are the caller's job — use `invoke` afterwards. In a typed project
-     * `agent` is constrained to the generated union of agent names.
-     */
+    /** Converse with a Pikku AI agent in this actor's persona and return its verdict */
     converse(options: ConverseOptions<TAgentName>): Promise<ActorFlowVerdict>;
 }
-/**
- * Display/config metadata for an actor (from pikku.config.json). The email
- * identifies the actor's user row; personality/jobTitle exist for the console
- * screen and for agent-driven flows (the agent plays the persona).
- */
+/** Display/config metadata for an actor (from pikku.config.json) */
 export interface ScenarioActorConfig {
     email: string;
     name?: string;

package/dist/services/stub-tracker.d.ts

@@ -0,0 +1,43 @@
+export type StubCall = {
+    service: string;
+    method: string;
+    args: unknown[];
+};
+/**
+ * Tracks calls made to stubbed services and enforces strict mode:
+ * once a scenario asserts any call on a service, every recorded call on that
+ * service must be verified by end of scenario — otherwise the After hook fails.
+ * Services never touched by an assertion stay lenient.
+ */
+export declare class StubTracker {
+    private readonly calls;
+    private readonly touched;
+    record(service: string, method: string, args: unknown[]): void;
+    getCalls(service?: string): StubCall[];
+    reset(): void;
+    stub<T>(service: string): T;
+    assert(service: string, method: string): void;
+    assertCall(service: string, method: string, predicate: (args: unknown[]) => boolean, description: string): void;
+    assertNoCalls(service: string, method?: string, predicate?: (args: unknown[]) => boolean, description?: string): void;
+    verify(): void;
+}
+/**
+ * Creates a Proxy suitable for passing as `existingServices` to
+ * `createSingletonServices`. Every property returns `tracker.stub(prop)`
+ * EXCEPT `schema`, which returns `undefined` so the service factory creates
+ * a real schema service. Stubbing the schema makes validation a no-op —
+ * required fields pass silently and tests validate nothing.
+ */
+export declare function createStubProxy(tracker: StubTracker): Record<string, unknown>;
+/** The process-wide tracker that `stub()`/`spy()` record into — read by the console's getStubCalls/resetStubs RPCs */
+export declare const getStubTracker: () => StubTracker;
+/** True when the server was started by `pikku dev --test` (sets PIKKU_TEST_RUN) */
+export declare const isTestRun: () => boolean;
+/**
+ * Creates a recording fake for a service. Methods present on `impl` run and
+ * their result is returned; missing methods resolve `undefined`. Every call
+ * is recorded so scenarios can assert via workflow.expectService().
+ */
+export declare function stub<T = any>(service: string, impl?: Partial<T>): T;
+/** Wraps a real service so every method call is recorded and passed through */
+export declare function spy<T extends object>(service: string, real: T): T;

package/dist/services/stub-tracker.js

@@ -0,0 +1,146 @@
+/**
+ * Tracks calls made to stubbed services and enforces strict mode:
+ * once a scenario asserts any call on a service, every recorded call on that
+ * service must be verified by end of scenario — otherwise the After hook fails.
+ * Services never touched by an assertion stay lenient.
+ */
+export class StubTracker {
+    calls = new Map();
+    touched = new Set();
+    record(service, method, args) {
+        const list = this.calls.get(service) ?? [];
+        list.push({ method, args, verified: false });
+        this.calls.set(service, list);
+    }
+    getCalls(service) {
+        const result = [];
+        for (const [name, list] of this.calls) {
+            if (service && name !== service)
+                continue;
+            for (const call of list) {
+                result.push({ service: name, method: call.method, args: call.args });
+            }
+        }
+        return result;
+    }
+    reset() {
+        this.calls.clear();
+        this.touched.clear();
+    }
+    stub(service) {
+        const self = this;
+        return new Proxy(Object.create(null), {
+            get(_, method) {
+                return (...args) => {
+                    self.record(service, method, args);
+                    return Promise.resolve();
+                };
+            },
+        });
+    }
+    assert(service, method) {
+        this.touched.add(service);
+        const list = this.calls.get(service) ?? [];
+        const idx = list.findIndex((c) => c.method === method && !c.verified);
+        if (idx === -1) {
+            const seen = list.map((c) => c.method).join(', ') || '(none)';
+            throw new Error(`Expected "${service}.${method}" to have been called. Recorded: ${seen}`);
+        }
+        list[idx].verified = true;
+    }
+    assertCall(service, method, predicate, description) {
+        this.touched.add(service);
+        const list = this.calls.get(service) ?? [];
+        const idx = list.findIndex((c) => c.method === method && !c.verified && predicate(c.args));
+        if (idx === -1) {
+            const seen = list
+                .filter((c) => c.method === method)
+                .map((c) => JSON.stringify(c.args[0]))
+                .join('\n  ') || '(none)';
+            throw new Error(`Expected ${description} but found:\n  ${seen}`);
+        }
+        list[idx].verified = true;
+    }
+    assertNoCalls(service, method, predicate, description) {
+        this.touched.add(service);
+        const list = this.calls.get(service) ?? [];
+        const relevant = (method ? list.filter((c) => c.method === method) : list).filter((c) => !predicate || predicate(c.args));
+        if (relevant.length > 0) {
+            const calls = relevant
+                .map((c) => `${c.method}(${c.args.map((a) => JSON.stringify(a)).join(', ')})`)
+                .join('\n  ');
+            const what = description ?? `"${service}${method ? '.' + method : ''}"`;
+            throw new Error(`Expected no ${what} calls but got:\n  ${calls}`);
+        }
+    }
+    verify() {
+        const errors = [];
+        for (const service of this.touched) {
+            const unverified = (this.calls.get(service) ?? []).filter((c) => !c.verified);
+            for (const c of unverified) {
+                const argStr = c.args.map((a) => JSON.stringify(a)).join(', ');
+                errors.push(`  ${service}.${c.method}(${argStr})`);
+            }
+        }
+        if (errors.length) {
+            throw new Error(`Unexpected stub calls — assert them in the scenario or remove the side effect:\n${errors.join('\n')}`);
+        }
+    }
+}
+/**
+ * Creates a Proxy suitable for passing as `existingServices` to
+ * `createSingletonServices`. Every property returns `tracker.stub(prop)`
+ * EXCEPT `schema`, which returns `undefined` so the service factory creates
+ * a real schema service. Stubbing the schema makes validation a no-op —
+ * required fields pass silently and tests validate nothing.
+ */
+export function createStubProxy(tracker) {
+    return new Proxy({}, {
+        get(_, prop) {
+            if (prop === 'schema')
+                return undefined;
+            return tracker.stub(prop);
+        },
+    });
+}
+const defaultStubTracker = new StubTracker();
+/** The process-wide tracker that `stub()`/`spy()` record into — read by the console's getStubCalls/resetStubs RPCs */
+export const getStubTracker = () => defaultStubTracker;
+/** True when the server was started by `pikku dev --test` (sets PIKKU_TEST_RUN) */
+export const isTestRun = () => globalThis
+    .process?.env?.PIKKU_TEST_RUN === 'true';
+/**
+ * Creates a recording fake for a service. Methods present on `impl` run and
+ * their result is returned; missing methods resolve `undefined`. Every call
+ * is recorded so scenarios can assert via workflow.expectService().
+ */
+export function stub(service, impl) {
+    return new Proxy((impl ?? {}), {
+        get(target, method) {
+            if (typeof method === 'symbol')
+                return target[method];
+            const real = target[method];
+            if (typeof real !== 'function' && real !== undefined)
+                return real;
+            return (...args) => {
+                defaultStubTracker.record(service, method, args);
+                return real ? real.apply(target, args) : Promise.resolve(undefined);
+            };
+        },
+    });
+}
+/** Wraps a real service so every method call is recorded and passed through */
+export function spy(service, real) {
+    return new Proxy(real, {
+        get(target, method) {
+            const value = target[method];
+            if (typeof method === 'symbol' || typeof value !== 'function') {
+                return value;
+            }
+            return (...args) => {
+                defaultStubTracker.record(service, method, args);
+                return value.apply(target, args);
+            };
+        },
+    });
+}

package/dist/services/v8-coverage-service.d.ts

@@ -0,0 +1,41 @@
+export interface CoverageRange {
+    startOffset: number;
+    endOffset: number;
+    count: number;
+}
+export interface FunctionCoverage {
+    functionName: string;
+    isBlockCoverage: boolean;
+    ranges: CoverageRange[];
+}
+export interface ScriptCoverage {
+    scriptId: string;
+    url: string;
+    functions: FunctionCoverage[];
+}
+export type LineHits = Map<string, Map<number, number>>;
+export type CoverageSnapshot = {
+    kind: 'v8-scripts';
+    scripts: ScriptCoverage[];
+    getScriptSource: (scriptId: string) => Promise<string>;
+} | {
+    kind: 'line-hits';
+    lineHits: LineHits;
+};
+export interface CoverageService {
+    start(): Promise<void>;
+    takeCoverage(): Promise<CoverageSnapshot>;
+    reset(): Promise<void>;
+    stop(): Promise<void>;
+}
+export declare class V8CoverageService implements CoverageService {
+    private session;
+    private startPromise;
+    private post;
+    start(): Promise<void>;
+    private doStart;
+    takeCoverage(): Promise<CoverageSnapshot>;
+    getScriptSource(scriptId: string): Promise<string>;
+    reset(): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/services/v8-coverage-service.js

@@ -0,0 +1,63 @@
+// node:inspector is imported lazily inside start() so this module stays
+// loadable on runtimes without it (e.g. Cloudflare Workers).
+export class V8CoverageService {
+    session = null;
+    startPromise = null;
+    post(method, params) {
+        const session = this.session;
+        if (!session) {
+            throw new Error('V8CoverageService not started — call start() first');
+        }
+        return new Promise((resolve, reject) => {
+            session.post(method, params, (err, result) => err ? reject(err) : resolve(result));
+        });
+    }
+    start() {
+        this.startPromise ??= this.doStart();
+        return this.startPromise;
+    }
+    async doStart() {
+        const inspector = await import('node:inspector');
+        this.session = new inspector.Session();
+        this.session.connect();
+        await this.post('Profiler.enable');
+        await this.post('Debugger.enable');
+        await this.post('Profiler.startPreciseCoverage', {
+            callCount: true,
+            detailed: true,
+        });
+    }
+    async takeCoverage() {
+        const { result } = await this.post('Profiler.takePreciseCoverage');
+        return {
+            kind: 'v8-scripts',
+            scripts: result.filter((script) => script.url.startsWith('file://')),
+            getScriptSource: (scriptId) => this.getScriptSource(scriptId),
+        };
+    }
+    async getScriptSource(scriptId) {
+        const { scriptSource } = await this.post('Debugger.getScriptSource', { scriptId });
+        return scriptSource;
+    }
+    async reset() {
+        await this.post('Profiler.stopPreciseCoverage');
+        await this.post('Profiler.startPreciseCoverage', {
+            callCount: true,
+            detailed: true,
+        });
+    }
+    async stop() {
+        if (!this.session)
+            return;
+        try {
+            await this.post('Profiler.stopPreciseCoverage');
+            await this.post('Profiler.disable');
+            await this.post('Debugger.disable');
+        }
+        finally {
+            this.session.disconnect();
+            this.session = null;
+            this.startPromise = null;
+        }
+    }
+}

package/dist/types/core.types.d.ts

@@ -28,6 +28,7 @@ import type { WorkflowRunService } from '../wirings/workflow/workflow.types.js';
 import type { CredentialService } from '../services/credential-service.js';
 import type { EmailService } from '../services/email-service.js';
 import type { MetaService } from '../services/meta-service.js';
+import type { CoverageService } from '../services/v8-coverage-service.js';
 import type { SessionStore } from '../services/session-store.js';
 import type { AuditDurability, AuditLog, AuditService } from '../services/audit-service.js';
 export type PikkuWiringTypes = 'http' | 'scheduler' | 'trigger' | 'channel' | 'rpc' | 'queue' | 'mcp' | 'cli' | 'workflow' | 'agent' | 'gateway';
@@ -110,6 +111,12 @@ export type FunctionMeta = FunctionRuntimeMeta & Partial<{
     isDirectFunction: boolean;
     sourceFile: string;
     exportedName: string;
+    /** File containing the handler body when it differs from sourceFile (imported handlers) */
+    bodySourceFile?: string;
+    /** 1-indexed first line of the handler body (verbose meta; coverage mapping) */
+    bodyStart: number;
+    /** 1-indexed last line of the handler body (verbose meta; coverage mapping) */
+    bodyEnd: number;
 } & CommonWireMeta>;
 export type FunctionsRuntimeMeta = Record<string, FunctionRuntimeMeta>;
 export type FunctionsMeta = Record<string, FunctionMeta>;
@@ -233,6 +240,8 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
     emailService?: EmailService;
     /** Meta service for reading .pikku metadata files (filesystem on Node, R2/KV on CF) */
     metaService?: MetaService;
+    /** V8 precise-coverage collector (`pikku dev --coverage` only) */
+    coverageService?: CoverageService;
     /** Audit service for durable or staged audit event capture */
     audit?: AuditService;
     /**

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

@@ -32,6 +32,18 @@ export interface WorkflowExpectEventuallyOptions extends WorkflowStepOptions {
     /** Poll interval (e.g. '1s'). Default '1s'. */
     interval?: string | number;
 }
+/** Options for workflow.expectError() */
+export interface WorkflowExpectErrorOptions extends WorkflowStepOptions {
+    /** Assert the error message matches (string = substring match). */
+    matches?: string | RegExp;
+}
+/** Options for workflow.expectService() */
+export interface WorkflowExpectServiceOptions extends WorkflowStepOptions {
+    /** Assert a recorded call's first argument deep-equals this value. */
+    calledWith?: unknown;
+    /** Assert the exact number of matching calls. Default: at least one. */
+    times?: number;
+}
 /**
  * Type signature for workflow.do() RPC form - used by inspector
  */
@@ -344,6 +356,10 @@ export interface PikkuWorkflowWire {
      * `options.as` is set) until `predicate` passes or `options.within` elapses.
      */
     expectEventually: <TOutput = any, TInput = any>(stepName: string, rpcName: string, data: TInput, predicate: (output: TOutput) => boolean, options?: WorkflowExpectEventuallyOptions) => Promise<TOutput>;
+    /** Error-path step (scenarios): succeeds only when the RPC throws; returns the message */
+    expectError: <TInput = any>(stepName: string, rpcName: string, data: TInput, options?: WorkflowExpectErrorOptions) => Promise<string>;
+    /** Stub-assertion step (scenarios): asserts `service.method` was called on the target server */
+    expectService: (stepName: string, serviceMethod: string, options?: WorkflowExpectServiceOptions) => Promise<void>;
     /** Sleep for a duration */
     sleep: WorkflowWireSleep;
     /** Suspend workflow until explicitly resumed */

package/dist/wirings/workflow/pikku-workflow-service.d.ts

@@ -368,12 +368,6 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     protected scheduleSleep(runId: string, stepId: string, duration: number | string): Promise<boolean>;
     /** Build HTTP scenario actors for a run started without them; undefined when SCENARIO_ACTOR_SECRET or the API URL is missing */
     private resolveScenarioActors;
-    /**
-     * 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)
-     */
     /**
      * Start a new workflow run
      * Automatically detects workflow type (DSL or graph) from meta and executes accordingly

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

@@ -631,12 +631,6 @@ export class PikkuWorkflowService {
             rpcPath,
         });
     }
-    /**
-     * 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)
-     */
     /**
      * Start a new workflow run
      * Automatically detects workflow type (DSL or graph) from meta and executes accordingly
@@ -1427,6 +1421,62 @@ export class PikkuWorkflowService {
                     }
                 }, 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 = 'console:getStubCalls';
+                    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);

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

@@ -1,7 +1,7 @@
 import type { SerializedError, CommonWireMeta } from '../../types/core.types.js';
 import type { CorePikkuFunctionConfig } from '../../function/functions.types.js';
 export type { WorkflowService } from '../../services/workflow-service.js';
-export type { WorkflowStepOptions, WorkflowExpectEventuallyOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './dsl/workflow-dsl.types.js';
+export type { WorkflowStepOptions, WorkflowExpectEventuallyOptions, WorkflowExpectErrorOptions, WorkflowExpectServiceOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './dsl/workflow-dsl.types.js';
 import type { WorkflowStepMeta } from './dsl/workflow-dsl.types.js';
 export interface WorkflowRunWire {
     type: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.52",
+  "version": "0.12.53",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",

package/src/services/index.ts

@@ -154,3 +154,22 @@ export type {
   EmailTemplateLocaleMeta,
   EmailTemplateAssets,
 } from './meta-service.js'
+export {
+  V8CoverageService,
+  type CoverageService,
+  type CoverageSnapshot,
+  type LineHits,
+  type ScriptCoverage,
+  type FunctionCoverage,
+  type CoverageRange,
+} from './v8-coverage-service.js'
+export { IstanbulCoverageService } from './istanbul-coverage-service.js'
+export {
+  StubTracker,
+  createStubProxy,
+  getStubTracker,
+  isTestRun,
+  stub,
+  spy,
+  type StubCall,
+} from './stub-tracker.js'