@pikku/core 0.12.134 → 0.12.136

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## 0.12.136
+
+### Patch Changes
+
+- 149faae: Webhook `receive` steps lose their boilerplate. `pikkuWebhookReceive` (from `#pikku/trigger` or `#pikku/addon/trigger`) declares one: it is public, typed to the raw request with a required `http`, and never registered as an RPC, and the inspector rejects a `receive` declared with any other wrapper. `parseJson` (in `@pikku/core/utils`, generated as `#pikku/utils` and `#pikku/addon/utils`) parses text or bytes and answers a body that is not JSON with a 400. A webhook source whose `method` includes `'head'` answers HEAD probes itself with a 200.
+
+  `receive` no longer returns `{ respond }`: a handshake returns nothing and writes its answer to `http.response`, like any other HTTP function. The webhook route no longer returns a fetch `Response` either. An HTTP function that returns nothing is now answered with whatever status its response has (200 unless it set another), no longer a forced 204. A webhook receive is also left out of contract versioning, since nothing but its own route calls it.
+
+## 0.12.135
+
+### Patch Changes
+
+- ce3e5f5: Saga compensation for workflows. A function declares `compensate` inline; when a workflow step fails, completed steps are undone newest-first as durable `<step>:compensate` steps. New run statuses `compensating`, `compensated` and `compensation_failed`, `workflow.milestone(name)` to bound the unwind, `{ compensate: false }` to opt a call out, nested-workflow unwinding, and `PikkuWorkflowService.cancelRun` which unwinds too. Graph nodes replace `onError` with `recover` (`nodeId`, `nodeId[]` or `'ignore'`), exposing the error as `wire.graph.recoveringFrom`. **Breaking:** the DSL `onError` step option and the graph `onError` node field are removed; `getRunSteps` is now abstract on `PikkuWorkflowService`.
+- fb36c37: Remove `WebhookSigningSecret` from `@pikku/core/hmac`: declare `verify` on `wireTriggerWebhookSource` instead, or use `hmacDigest`, `verifyHmacSignature`, `verifyPublicKeySignature` and `timingSafeStringEqual` directly. The trigger skill and the online-shop snippet now teach declarative `verify`, and the `verify` JSDoc describes bodiless requests correctly.
+
 ## 0.12.134
 
 ### Patch Changes

package/dist/analytics/analytics.types.d.ts

@@ -8,6 +8,7 @@ import type { CoreUserSession, PikkuWire, PikkuWiringTypes } from '../types/core
  * events carry more than a fixed set of props.
  */
 export type AnalyticsEventBase = {
+    /** The event name, as declared in `defineAnalyticsEvents`. */
     name: string;
 } & Record<string, unknown>;
 export interface AnalyticsEventInput {
@@ -20,8 +21,11 @@ export interface AnalyticsEventInput {
  * which is what makes an unauthenticated ingest safe to expose.
  */
 export interface AnalyticsIdentity {
+    /** The session's user id, or null for a visitor with no session. */
     userId: string | null;
+    /** The session's organization, when it has one. */
     orgId?: string;
+    /** The pikku user the session resolves to; absent without a session. */
     pikkuUserId?: string;
     /**
      * Identifiers a destination keys on that pikku does not mint — GA4's
@@ -80,14 +84,23 @@ resolved?: Pick<AnalyticsIdentity, 'vendorIds' | 'consent' | 'anonymousId'>) =>
  * through, so a sink never has to trust — or re-derive — any of them.
  */
 export interface AnalyticsRecord {
+    /** The event name. */
     name: string;
+    /** The validated props the event carried. */
     props?: Record<string, unknown>;
+    /** When the server accepted the event, as an ISO timestamp. */
     occurredAt: string;
+    /** When a browser says it happened, in epoch milliseconds; only on relayed events. */
     at?: number;
+    /** Who the event is attributed to, stamped from the session and cookies. */
     userIdentity: AnalyticsIdentity;
+    /** The trace the emitting invocation belongs to. */
     traceId?: string;
+    /** The function that recorded the event, when one did. */
     functionId?: string;
+    /** The kind of wire the event came in on. */
     wireType?: PikkuWiringTypes;
+    /** `client` when relayed from a browser, `server` when a function recorded it. */
     source: 'server' | 'client';
 }
 /**
@@ -100,6 +113,7 @@ export interface AnalyticsRecord {
  * to implement and every caller had to choose between.
  */
 export interface AnalyticsService {
+    /** Delivers one batch of accepted records; a rejection is logged, never surfaced to the caller. */
     write(batch: AnalyticsRecord[]): Promise<void>;
 }
 /**
@@ -111,7 +125,9 @@ export interface AnalyticsService {
  * should look like once it gets there is the sink's, and lives in its mapper.
  */
 export interface AnalyticsSink {
+    /** The destination the filtered records are written to. */
     service: AnalyticsService;
+    /** Returns true for the records this destination should get; omit to send everything. */
     accepts?: (record: AnalyticsRecord) => boolean;
 }
 /**
@@ -119,6 +135,7 @@ export interface AnalyticsSink {
  * beacon is free to omit `at`.
  */
 export interface AnalyticsClientContext {
+    /** When the browser says the event happened, in epoch milliseconds. */
     at?: number;
 }
 /**
@@ -127,8 +144,11 @@ export interface AnalyticsClientContext {
  * narrow `Events` in its own `SingletonServices`.
  */
 export interface AnalyticsLog<Events extends AnalyticsEventBase = AnalyticsEventBase> {
+    /** Buffers an event for the invocation; pass `client` when relaying one from a browser. */
     record(event: Events, client?: AnalyticsClientContext): Promise<void>;
+    /** Writes what is buffered to the service now, rather than when the invocation ends. */
     flush(): Promise<void>;
+    /** Flushes and stops accepting events; called for you when the invocation ends. */
     close(): Promise<void>;
 }
 /**

package/dist/analytics/anonymous-analytics-identity.d.ts

@@ -19,5 +19,7 @@ export interface AnonymousAnalyticsIdentityOptions {
  * browser script needs it, and a cookie scripts cannot touch is both harder to
  * misuse and not subject to the seven-day cap browsers place on script-set
  * ones. An app that wants a vendor SDK to read it must opt out deliberately.
+ *
+ * @example snippet: analyticsIdentity
  */
 export declare const anonymousAnalyticsIdentity: (options?: AnonymousAnalyticsIdentityOptions) => AnalyticsIdentityResolver;

package/dist/analytics/anonymous-analytics-identity.js

@@ -14,6 +14,8 @@ const DEFAULT_COOKIE = {
  * browser script needs it, and a cookie scripts cannot touch is both harder to
  * misuse and not subject to the seven-day cap browsers place on script-set
  * ones. An app that wants a vendor SDK to read it must opt out deliberately.
+ *
+ * @example snippet: analyticsIdentity
  */
 export const anonymousAnalyticsIdentity = (options = {}) => {
     return (wire, resolved) => {

package/dist/analytics/compose-analytics-identity.d.ts

@@ -10,5 +10,7 @@ import type { AnalyticsIdentityResolver } from './analytics.types.js';
  *
  * A later resolver wins a key it sets, so a minter's freshly created id
  * replaces the absent one the cookie reader could not find.
+ *
+ * @example snippet: analyticsIdentity
  */
 export declare const composeAnalyticsIdentity: (...resolvers: AnalyticsIdentityResolver[]) => AnalyticsIdentityResolver;

package/dist/analytics/compose-analytics-identity.js

@@ -9,6 +9,8 @@
  *
  * A later resolver wins a key it sets, so a minter's freshly created id
  * replaces the absent one the cookie reader could not find.
+ *
+ * @example snippet: analyticsIdentity
  */
 export const composeAnalyticsIdentity = (...resolvers) => {
     return (wire, initial) => {

package/dist/analytics/cookie-analytics-identity.d.ts

@@ -20,5 +20,7 @@ export interface CookieAnalyticsIdentityOptions {
  * Resolves nothing off an HTTP wire, which is correct: a cron task and a queue
  * worker have no browser behind them, so any vendor id they produced would be
  * invented.
+ *
+ * @example snippet: analyticsIdentity
  */
 export declare const cookieAnalyticsIdentity: (options: CookieAnalyticsIdentityOptions) => AnalyticsIdentityResolver;

package/dist/analytics/cookie-analytics-identity.js

@@ -9,6 +9,8 @@ const DENIALS = new Set(['0', 'false', 'denied', 'deny', 'no']);
  * Resolves nothing off an HTTP wire, which is correct: a cron task and a queue
  * worker have no browser behind them, so any vendor id they produced would be
  * invented.
+ *
+ * @example snippet: analyticsIdentity
  */
 export const cookieAnalyticsIdentity = (options) => {
     return (wire) => {

package/dist/analytics/define-analytics-events.d.ts

@@ -7,6 +7,7 @@ import type { StandardSchemaV1 } from '@standard-schema/spec';
  * and saying so here fails at the declaration rather than in generated code.
  */
 export type AnalyticsEventPropsSchema = StandardSchemaV1 & {
+    /** The object schema's fields, which the CLI reads to list an event's props. */
     shape: Record<string, unknown>;
 };
 /** Events keyed by name; each value is the schema for that event's props. */
@@ -18,5 +19,7 @@ export type AnalyticsEventDefinitions = Record<string, AnalyticsEventPropsSchema
  * It must stay an exported const — the schema pipeline reads the value by name.
  * It registers nothing at runtime: where events go is an `AnalyticsService` on
  * singleton services.
+ *
+ * @example snippet: analyticsEvents
  */
 export declare const defineAnalyticsEvents: <const Events extends AnalyticsEventDefinitions>(events: Events) => Events;

package/dist/analytics/define-analytics-events.js

@@ -5,5 +5,7 @@
  * It must stay an exported const — the schema pipeline reads the value by name.
  * It registers nothing at runtime: where events go is an `AnalyticsService` on
  * singleton services.
+ *
+ * @example snippet: analyticsEvents
  */
 export const defineAnalyticsEvents = (events) => events;

package/dist/analytics/fan-out-analytics.d.ts

@@ -11,5 +11,7 @@ import type { AnalyticsService, AnalyticsSink } from './analytics.types.js';
  * is down must not cost the others their events. A destination that throws is
  * reported by the caller's existing flush guard, which already treats analytics
  * as best-effort.
+ *
+ * @example snippet: shopServices
  */
 export declare const fanOutAnalytics: (sinks: ReadonlyArray<AnalyticsSink | AnalyticsService>) => AnalyticsService;

package/dist/analytics/fan-out-analytics.js

@@ -10,6 +10,8 @@
  * is down must not cost the others their events. A destination that throws is
  * reported by the caller's existing flush guard, which already treats analytics
  * as best-effort.
+ *
+ * @example snippet: shopServices
  */
 export const fanOutAnalytics = (sinks) => {
     const resolved = sinks.map((sink) => 'service' in sink ? sink : { service: sink });

package/dist/analytics/logger-analytics-service.d.ts

@@ -9,6 +9,8 @@ import type { AnalyticsRecord, AnalyticsService } from './analytics.types.js';
  */
 export declare class LoggerAnalyticsService implements AnalyticsService {
     private readonly logger;
+    /** @param logger Receives each event at `debug`. */
     constructor(logger: Logger);
+    /** Logs each record in the batch at `debug`. */
     write(batch: AnalyticsRecord[]): Promise<void>;
 }

package/dist/analytics/logger-analytics-service.js

@@ -7,9 +7,11 @@
  */
 export class LoggerAnalyticsService {
     logger;
+    /** @param logger Receives each event at `debug`. */
     constructor(logger) {
         this.logger = logger;
     }
+    /** Logs each record in the batch at `debug`. */
     async write(batch) {
         for (const event of batch) {
             this.logger.debug(`analytics: ${event.name}`, {

package/dist/analytics/mint-cookie.d.ts

@@ -10,6 +10,7 @@ export interface MintCookieOptions {
      * is answered has already done the thing the send gate was meant to prevent.
      */
     requires?: string[];
+    /** What the visitor agreed to, as resolved by an earlier resolver; `requires` is checked against it. */
     consent?: Record<string, boolean>;
     /**
      * Replace the cookie already on the device rather than returning it.
@@ -37,8 +38,14 @@ export interface MintCookieOptions {
  * has been sent; a cron task and a queue worker have no browser to store it,
  * and a stream's headers are long gone. Both return undefined rather than
  * pretending.
+ *
+ * @example snippet: mintVendorCookie
  */
 export declare const mintCookie: (wire: AnyWire, name: string, options: MintCookieOptions, mint: () => string) => string | undefined;
-/** Cryptographically random digits, the shape both vendor formats use. */
+/**
+ * Cryptographically random digits, the shape both vendor formats use.
+ *
+ * @example snippet: mintVendorCookie
+ */
 export declare const randomDigits: (length: number) => string;
 export {};

package/dist/analytics/mint-cookie.js

@@ -21,11 +21,11 @@ const permitted = (requires, consent) => {
  * has been sent; a cron task and a queue worker have no browser to store it,
  * and a stream's headers are long gone. Both return undefined rather than
  * pretending.
+ *
+ * @example snippet: mintVendorCookie
  */
 export const mintCookie = (wire, name, options, mint) => {
-    const existing = options.overwrite
-        ? null
-        : wire.http?.request?.cookie(name);
+    const existing = options.overwrite ? null : wire.http?.request?.cookie(name);
     if (existing)
         return existing;
     const cache = minted.get(wire) ?? new Map();
@@ -43,7 +43,11 @@ export const mintCookie = (wire, name, options, mint) => {
     minted.set(wire, cache);
     return value;
 };
-/** Cryptographically random digits, the shape both vendor formats use. */
+/**
+ * Cryptographically random digits, the shape both vendor formats use.
+ *
+ * @example snippet: mintVendorCookie
+ */
 export const randomDigits = (length) => {
     const bytes = new Uint8Array(length);
     crypto.getRandomValues(bytes);

package/dist/function/compensation-name.d.ts

@@ -0,0 +1,4 @@
+export declare const COMPENSATION_STEP_SUFFIX = ":compensate";
+export declare const compensationStepName: (stepName: string) => string;
+export declare const isCompensationStepName: (stepName: string) => boolean;
+export declare const forwardStepName: (stepName: string) => string;

package/dist/function/compensation-name.js

@@ -0,0 +1,6 @@
+export const COMPENSATION_STEP_SUFFIX = ':compensate';
+export const compensationStepName = (stepName) => `${stepName}${COMPENSATION_STEP_SUFFIX}`;
+export const isCompensationStepName = (stepName) => stepName.endsWith(COMPENSATION_STEP_SUFFIX);
+export const forwardStepName = (stepName) => isCompensationStepName(stepName)
+    ? stepName.slice(0, -COMPENSATION_STEP_SUFFIX.length)
+    : stepName;

package/dist/function/function-meta.types.d.ts

@@ -49,6 +49,11 @@ export type FunctionRuntimeMeta = {
      * everywhere else, so it is never network-callable.
      */
     scenarioStep?: boolean;
+    /**
+     * A webhook source's `receive` step, declared with `pikkuWebhookReceive`.
+     * Only its source's route runs it, so it is never RPC-callable.
+     */
+    webhookReceive?: boolean;
     /**
      * The body of a `pikkuScenario(...)`. Only ever run by `pikku scenario run`,
      * so it is held back from the app bootstrap and from every deployed unit.
@@ -58,6 +63,8 @@ export type FunctionRuntimeMeta = {
     readonly?: boolean;
     deploy?: 'serverless' | 'server' | 'auto';
     sessionless?: boolean;
+    /** The function declares a `compensate`, run as the sibling `<id>:compensate` when a workflow unwinds. */
+    compensate?: boolean;
     /** When true, workflow steps calling this function are dispatched via the queue. No queue service configured is a hard error. */
     workflowQueued?: boolean;
     /** Retry count when this function is used as a workflow step. */

package/dist/function/function-runner.js

@@ -1,4 +1,5 @@
 import { beginChanges } from './abort-scope.js';
+import { forwardStepName, isCompensationStepName } from './compensation-name.js';
 import { runMiddleware, combineMiddleware } from '../middleware-runner.js';
 import { combineChannelMiddleware, wrapChannelWithMiddleware, } from '../wirings/channel/channel-middleware-runner.js';
 import { runPermissions } from '../permissions.js';
@@ -71,6 +72,22 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
     let funcConfig = funcMap.get(funcName);
     const allMeta = pikkuState(packageName, 'function', 'meta');
     let funcMeta = allMeta[funcName];
+    if ((!funcConfig || !funcMeta) && isCompensationStepName(funcName)) {
+        const forwardName = forwardStepName(funcName);
+        const forward = funcMap.get(forwardName);
+        const forwardMeta = allMeta[forwardName];
+        if (forward?.compensate && forwardMeta) {
+            const { compensate, ...rest } = forward;
+            funcConfig = { ...rest, func: compensate };
+            funcMeta = {
+                ...forwardMeta,
+                pikkuFuncId: funcName,
+                outputs: null,
+                expose: false,
+                compensate: undefined,
+            };
+        }
+    }
     if (!funcConfig || !funcMeta) {
         const { baseName, version } = parseVersionedId(funcName);
         if (version !== null) {

package/dist/function/functions.types.d.ts

@@ -17,12 +17,23 @@ export type CorePikkuPermissionConfig<In = any, Services extends CoreSecretlessS
 };
 export declare const pikkuPermission: <In = any, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Wire extends PickRequired<PikkuWire<In, never, false, any, PikkuRPC, never, never>, 'session'> = PickRequired<PikkuWire<In, never, false, any, PikkuRPC, never, never>, 'session'>>(permission: CorePikkuPermission<In, Services, Wire> | CorePikkuPermissionConfig<In, Services, Wire>) => CorePikkuPermission<In, Services, Wire>;
 export type CorePikkuPermissionFactory<In = any, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Wire extends PikkuWire<In, never, false, any, PikkuRPC, never, never> = PikkuWire<In, never, false, any, PikkuRPC, never, never>> = (input: In) => CorePikkuPermission<any, Services, Wire>;
+/**
+ * Declares a permission that takes configuration, so one check serves many
+ * call sites: `hasProfileRole({ role: 'support' })`.
+ *
+ * @example snippet: permissionFactory
+ */
 export declare const pikkuPermissionFactory: <In = any>(factory: CorePikkuPermissionFactory<In>) => CorePikkuPermissionFactory<In>;
 /**
  * Renders a human-readable approval prompt for an AI agent, in place of the
  * raw tool arguments.
  */
 export type CorePikkuApprovalDescription<In = any, Services extends CoreSecretlessSingletonServices = CoreSecretlessSingletonServices> = (services: Services, data: In) => Promise<string>;
+/**
+ * Declares the approval prompt a function shows in place of its raw arguments.
+ *
+ * @example snippet: approvalDescription
+ */
 export declare const pikkuApprovalDescription: <In = any, Services extends CoreSecretlessSingletonServices = CoreSecretlessSingletonServices>(fn: CorePikkuApprovalDescription<In, Services>) => CorePikkuApprovalDescription<In, Services>;
 export type CorePikkuAuth<Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Session extends CoreUserSession = CoreUserSession> = (services: Services, session: Session) => Promise<boolean> | boolean;
 export type CorePikkuAuthConfig<Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Session extends CoreUserSession = CoreUserSession> = {
@@ -83,6 +94,13 @@ export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any,
     approvalRequired?: boolean;
     /** When true, workflow steps calling this function are dispatched via the queue. No queue service configured is a hard error. Defaults to false (inline). */
     workflowQueued?: boolean;
+    /**
+     * Undoes this function's effect when a workflow that called it unwinds. It
+     * receives the function's own input, and `wire.workflow.compensatingFor`
+     * carries the forward output (or the error, when the forward step failed).
+     * It is never callable on its own — only the workflow engine runs it.
+     */
+    compensate?: (services: any, data: any, wire: any) => Promise<any> | any;
     /** Number of retry attempts when this function is used as a workflow step. */
     workflowRetries?: number;
     /** Timeout for this function when used as a workflow step (e.g. '30s', '5m'). */

package/dist/function/functions.types.js

@@ -1,9 +1,20 @@
 export const pikkuPermission = (permission) => {
     return typeof permission === 'function' ? permission : permission.func;
 };
+/**
+ * Declares a permission that takes configuration, so one check serves many
+ * call sites: `hasProfileRole({ role: 'support' })`.
+ *
+ * @example snippet: permissionFactory
+ */
 export const pikkuPermissionFactory = (factory) => {
     return factory;
 };
+/**
+ * Declares the approval prompt a function shows in place of its raw arguments.
+ *
+ * @example snippet: approvalDescription
+ */
 export const pikkuApprovalDescription = (fn) => {
     return fn;
 };

package/dist/middleware/require-origin.d.ts

@@ -16,6 +16,8 @@ export declare const isAllowedOrigin: (requestOrigin: string | null, hostOrigin:
  * before the function body. It stops another site's page from posting to an unauthed
  * route — it is not flood control, because `Origin` is trusted from nobody but a browser.
  * A missing `Origin` is rejected too: a real browser sets one on a cross-origin-capable POST.
+ *
+ * @example snippet: requireOrigin
  */
 export declare const requireOrigin: import("./middleware.types.js").CorePikkuMiddlewareFactory<{
     /** Extra allowed origins beyond the request's own host, or a resolver for them. */

package/dist/middleware/require-origin.js

@@ -33,6 +33,8 @@ export const isAllowedOrigin = (requestOrigin, hostOrigin, configuredOrigins) =>
  * before the function body. It stops another site's page from posting to an unauthed
  * route — it is not flood control, because `Origin` is trusted from nobody but a browser.
  * A missing `Origin` is rejected too: a real browser sets one on a cross-origin-capable POST.
+ *
+ * @example snippet: requireOrigin
  */
 export const requireOrigin = pikkuMiddlewareFactory(({ origins = [] } = {}) => pikkuMiddleware({
     name: 'requireOrigin',

package/dist/permissions.d.ts

@@ -8,6 +8,11 @@ import type { PikkuRPC } from './wirings/rpc/rpc-types.js';
 export type PermissionWire = PikkuWire<any, never, false, any, PikkuRPC, never, never>;
 import type { CorePermissionGroup, CorePikkuPermission } from './function/functions.types.js';
 export declare const clearPermissionsCache: () => void;
+/**
+ * Applies permissions to every function, ahead of the per-function ones.
+ *
+ * @example snippet: globalPermission
+ */
 export declare const addGlobalPermission: (permissions: CorePermissionGroup | CorePikkuPermission[], packageName?: string | null) => CorePermissionGroup | CorePikkuPermission[];
 export declare const runPermissions: ({ funcPermissions, services, wire, data, packageName, label, }: {
     funcPermissions?: CorePermissionGroup | CorePikkuPermission[];

package/dist/permissions.js

@@ -29,6 +29,11 @@ export const clearPermissionsCache = () => {
         delete globalPermissionsCache[key];
     }
 };
+/**
+ * Applies permissions to every function, ahead of the per-function ones.
+ *
+ * @example snippet: globalPermission
+ */
 export const addGlobalPermission = (permissions, packageName = null) => {
     const state = pikkuState(packageName, 'permissions', 'global');
     if (Array.isArray(permissions)) {

package/dist/testing/service-tests/queued-workflow-harness.d.ts

@@ -0,0 +1,61 @@
+import type { PikkuWorkflowService } from '../../wirings/workflow/pikku-workflow-service.js';
+import type { CompensatingFor } from '../../wirings/workflow/dsl/workflow-dsl.types.js';
+export type Handler = {
+    forward: (data: any, wire: any) => Promise<any> | any;
+    compensate?: (data: any, context: CompensatingFor) => Promise<void> | void;
+    queued?: boolean;
+};
+interface Job {
+    queue: string;
+    data: any;
+    attempts?: number;
+    attempt?: number;
+}
+/**
+ * Drives a workflow the way a deployment does: every orchestration and every
+ * `workflowQueued` step goes through a queue, and a pump plays the workers.
+ * Delays are ignored, so a retry runs on the next pass.
+ */
+export declare class QueuedWorkflowHarness {
+    handlers: Record<string, Handler>;
+    log: string[];
+    contexts: Array<{
+        rpc: string;
+        context: CompensatingFor | undefined;
+    }>;
+    recovering: Array<{
+        rpc: string;
+        from: any;
+    }>;
+    queue: Job[];
+    jobsRun: Array<{
+        queue: string;
+        step?: string;
+    }>;
+    ws: PikkuWorkflowService;
+    /** Return true to drop the job instead of running it, simulating a worker that never ran. */
+    dropWhen?: (job: Job) => boolean;
+    /** Make `queue.add` throw for a job, simulating the broker being unreachable. */
+    rejectAddWhen?: (queue: string, data: any) => boolean;
+    constructor(service: PikkuWorkflowService);
+    readonly rpc: {
+        rpcWithWire: (rpcName: string, data: any, wire: any) => Promise<any>;
+    };
+    register(name: string, handler: Handler): void;
+    defineDsl(name: string, body: (workflow: any, input: any) => Promise<any>): void;
+    defineGraph(name: string, entry: string, nodes: Record<string, any>): void;
+    start(name: string, input?: any): Promise<string>;
+    /** Run jobs until the queue is empty. */
+    pump(limit?: number): Promise<void>;
+    run(runId: string): Promise<import("../../wirings/workflow/workflow.types.js").WorkflowRun>;
+    steps(runId: string): Promise<(import("../../wirings/workflow/workflow.types.js").StepState & {
+        stepName: string;
+        rpcName?: string;
+        data?: any;
+    })[]>;
+    get undone(): string[];
+    ok(output?: any): Handler;
+    boom(message?: string): Handler;
+    undoable(output?: any): Handler;
+}
+export {};