@pikku/core 0.12.133 → 0.12.135

package/dist/testing/service-tests.d.ts

@@ -41,8 +41,12 @@ export interface ServiceTestConfig {
         leaseService?: () => Promise<LeaseService>;
         /** A workflow service that fences each step write to the claim that made it. */
         workflowFencing?: () => Promise<WorkflowFencingHarness>;
+        /** A workflow service to run saga compensation and graph `recover` against, driven through a queue. */
+        workflowCompensationQueued?: () => Promise<PikkuWorkflowService>;
+        workflowCompensationQueuedOptions?: QueuedCompensationOptions;
     };
 }
+import { type QueuedCompensationOptions } from './service-tests/workflow-compensation-queued-tests.js';
 /**
  * The shared conformance suite every storage backend runs.
  *

package/dist/testing/service-tests.js

@@ -10,6 +10,7 @@ import { defineAgentRunServiceTests } from './service-tests/agent-run-service-te
 import { defineSessionStoreTests } from './service-tests/session-store-tests.js';
 import { defineLeaseServiceTests } from './service-tests/lease-service-tests.js';
 import { defineWorkflowFencingTests } from './service-tests/workflow-fencing-tests.js';
+import { defineWorkflowCompensationQueuedTests, } from './service-tests/workflow-compensation-queued-tests.js';
 /**
  * The shared conformance suite every storage backend runs.
  *
@@ -27,6 +28,9 @@ export function defineServiceTests(config) {
     if (services.workflowService) {
         defineWorkflowServiceTests(name, services.workflowService);
     }
+    if (services.workflowCompensationQueued) {
+        defineWorkflowCompensationQueuedTests(name, services.workflowCompensationQueued, services.workflowCompensationQueuedOptions);
+    }
     if (services.workflowRunService) {
         defineWorkflowRunServiceTests(name, services.workflowRunService);
     }

package/dist/utils/hmac.d.ts

@@ -1,4 +1,3 @@
-import type { CredentialService } from '../services/credential-service.js';
 /**
  * HMAC-SHA256 of a payload, hex-encoded. Senders wrap this in their own scheme
  * prefix (`sha256=`, `v0=`, …).
@@ -12,7 +11,6 @@ export declare function timingSafeStringEqual(a: string, b: string): boolean;
 export type WebhookPayload = string | Uint8Array;
 export type HmacAlgorithm = 'sha1' | 'sha256' | 'sha512';
 export type SecretEncoding = 'utf8' | 'hex' | 'base64';
-type SecretSource = string | null | (() => Promise<string | null>);
 /** The HMAC of `payload` under `secret`, for handshakes that answer with a digest. */
 export declare function hmacDigest(secret: string, algorithm: HmacAlgorithm, payload: WebhookPayload, encoding: 'hex' | 'base64', secretEncoding?: SecretEncoding): string;
 /** Whether `signature` is the HMAC of `payload` under `secret`, compared in constant time. */
@@ -22,34 +20,3 @@ export declare function verifyPublicKeySignature(publicKey: string, signature: s
     algorithm?: string;
     dsaEncoding?: 'der' | 'ieee-p1363';
 }): boolean;
-/**
- * @deprecated Declare `credential` and `verify` on `wireTriggerWebhookSource`,
- * which checks every request before `receive` runs, or use the functions above.
- */
-export declare class WebhookSigningSecret {
-    private readonly provider;
-    private readonly secret;
-    constructor(provider: string, secret: SecretSource);
-    /**
-     * The secret a `setup` step or a handshake stored in the credential store,
-     * so a new one takes effect without a deploy.
-     */
-    static fromCredential(provider: string, credentials: CredentialService | undefined, name: string): WebhookSigningSecret;
-    get configured(): boolean;
-    /** The secret as it is now, to check one delivery against. */
-    load(): Promise<WebhookSigningSecret>;
-    /** For handshakes that answer with a digest, such as Zoom's URL validation. */
-    hmac(algorithm: HmacAlgorithm, payload: WebhookPayload, encoding: 'hex' | 'base64', secretEncoding?: SecretEncoding): string;
-    /** Throws unless `signature` is the HMAC of `payload` under the secret. */
-    verifyHmac(signature: string | undefined, algorithm: HmacAlgorithm, payload: WebhookPayload, encoding: 'hex' | 'base64', secretEncoding?: SecretEncoding): void;
-    /** For providers that send the shared secret itself rather than a signature. */
-    verifyToken(token: string | undefined): void;
-    /** For providers that sign with a private key: the secret is their public key, as PEM. */
-    verifyPublicKey(signature: string | undefined, payload: WebhookPayload, options?: {
-        algorithm?: string;
-        dsaEncoding?: 'der' | 'ieee-p1363';
-    }): void;
-    private require;
-    private rejected;
-}
-export {};

package/dist/utils/hmac.js

@@ -1,5 +1,4 @@
 import { createHmac, createVerify, timingSafeEqual } from 'node:crypto';
-import { UnauthorizedError } from '../errors/errors.js';
 /**
  * HMAC-SHA256 of a payload, hex-encoded. Senders wrap this in their own scheme
  * prefix (`sha256=`, `v0=`, …).
@@ -43,63 +42,3 @@ export function verifyPublicKeySignature(publicKey, signature, payload, options
         return false;
     }
 }
-/**
- * @deprecated Declare `credential` and `verify` on `wireTriggerWebhookSource`,
- * which checks every request before `receive` runs, or use the functions above.
- */
-export class WebhookSigningSecret {
-    provider;
-    secret;
-    constructor(provider, secret) {
-        this.provider = provider;
-        this.secret = secret;
-    }
-    /**
-     * The secret a `setup` step or a handshake stored in the credential store,
-     * so a new one takes effect without a deploy.
-     */
-    static fromCredential(provider, credentials, name) {
-        return new WebhookSigningSecret(provider, async () => credentials ? credentials.get(name) : null);
-    }
-    get configured() {
-        return typeof this.secret === 'string';
-    }
-    /** The secret as it is now, to check one delivery against. */
-    async load() {
-        if (typeof this.secret !== 'function') {
-            return this;
-        }
-        return new WebhookSigningSecret(this.provider, await this.secret());
-    }
-    /** For handshakes that answer with a digest, such as Zoom's URL validation. */
-    hmac(algorithm, payload, encoding, secretEncoding = 'utf8') {
-        return hmacDigest(this.require(), algorithm, payload, encoding, secretEncoding);
-    }
-    /** Throws unless `signature` is the HMAC of `payload` under the secret. */
-    verifyHmac(signature, algorithm, payload, encoding, secretEncoding = 'utf8') {
-        if (!verifyHmacSignature(this.require(), signature, algorithm, payload, encoding, secretEncoding)) {
-            throw this.rejected();
-        }
-    }
-    /** For providers that send the shared secret itself rather than a signature. */
-    verifyToken(token) {
-        if (!token || !timingSafeStringEqual(token, this.require())) {
-            throw this.rejected();
-        }
-    }
-    /** For providers that sign with a private key: the secret is their public key, as PEM. */
-    verifyPublicKey(signature, payload, options = {}) {
-        if (!verifyPublicKeySignature(this.require(), signature, payload, options)) {
-            throw this.rejected();
-        }
-    }
-    require() {
-        if (typeof this.secret !== 'string') {
-            throw new UnauthorizedError(`The ${this.provider} webhook receiver has no signing secret`);
-        }
-        return this.secret;
-    }
-    rejected() {
-        return new UnauthorizedError(`Invalid ${this.provider} webhook signature`);
-    }
-}

package/dist/wirings/rpc/rpc-runner.js

@@ -1,3 +1,4 @@
+import { forwardStepName, isCompensationStepName, } from '../../function/compensation-name.js';
 import { runPikkuFunc } from '../../function/function-runner.js';
 import { addonInstanceForNamespace } from '../addon/addon-runner.js';
 import { isAddonFunctionExposed } from '../addon/wire-addon.js';
@@ -86,6 +87,15 @@ const resolvePikkuFunction = (rpcName, packageName = null) => {
             };
         }
     }
+    if (!rpcMeta && isCompensationStepName(rpcName)) {
+        const forward = forwardStepName(rpcName);
+        const funcs = pikkuState(null, 'function', 'functions');
+        const forwardId = rpc[forward] ?? (funcs.has(forward) ? forward : undefined);
+        const forwardFunc = forwardId ? funcs.get(forwardId) : undefined;
+        if (forwardId && forwardFunc?.compensate) {
+            return { pikkuFuncId: `${forwardId}:compensate`, packageName: null };
+        }
+    }
     if (!rpcMeta) {
         throw new RPCNotFoundError(rpcName);
     }
@@ -203,7 +213,17 @@ export class ContextAwareRPCService {
             };
         }
         const addonFunctionMeta = pikkuState(resolved.package, 'function', 'meta');
-        const funcMeta = addonFunctionMeta[resolved.function];
+        let funcMeta = addonFunctionMeta[resolved.function];
+        if (!funcMeta && isCompensationStepName(resolved.function)) {
+            const forwardName = forwardStepName(resolved.function);
+            const forwardMeta = addonFunctionMeta[forwardName];
+            if (forwardMeta?.compensate) {
+                funcMeta = {
+                    ...forwardMeta,
+                    pikkuFuncId: `${forwardMeta.pikkuFuncId || forwardName}:compensate`,
+                };
+            }
+        }
         if (!funcMeta) {
             return NOT_RESOLVED;
         }

package/dist/wirings/trigger/webhook-source-runner.js

@@ -70,7 +70,7 @@ const signedWith = async (verify, request, secret, services) => {
         return value?.startsWith(prefix) ? value.slice(prefix.length) : undefined;
     };
     if ('hmac' in verify) {
-        const { header: name, prefix, algorithm, encoding, secretEncoding } = verify.hmac;
+        const { header: name, prefix, algorithm, encoding, secretEncoding, } = verify.hmac;
         return verifyHmacSignature(secret, header(name, prefix), algorithm, request.body, encoding, secretEncoding);
     }
     if ('token' in verify) {
@@ -81,23 +81,30 @@ const signedWith = async (verify, request, secret, services) => {
     return verifyPublicKeySignature(secret, header(name), request.body, options);
 };
 /**
- * Whether the request was checked against the source's signing secret. Throws
- * when it was checked and failed. A source without `verify` checks in its own
- * `receive`, and a request without a body has nothing signed to check.
+ * Whether the request was signed with the source's secret. A request with a
+ * body is refused when it was not. A request without one — a HEAD probe, a
+ * validation token in the query — only comes back unverified, so `receive`
+ * can answer it but not dispatch from it. A source without `verify` checks in
+ * its own `receive`.
  */
 const verifyRequest = async (source, request, services) => {
     if (!source?.verify)
         return true;
-    if (request.body.length === 0)
-        return false;
+    const bodiless = request.body.length === 0;
     const secret = await services.credentialService?.get(source.credential ?? webhookSecretCredentialName(source.name));
     if (typeof secret !== 'string' || !secret) {
+        if (bodiless)
+            return false;
         throw new UnauthorizedError(`The ${source.name} webhook source has no signing secret`);
     }
-    if (!(await signedWith(source.verify, request, secret, services))) {
-        throw new UnauthorizedError(`Invalid ${source.name} webhook signature`);
-    }
-    return true;
+    const signed = await signedWith(source.verify, request, secret, services).catch((error) => {
+        if (bodiless)
+            return false;
+        throw error;
+    });
+    if (signed || bodiless)
+        return signed;
+    throw new UnauthorizedError(`Invalid ${source.name} webhook signature`);
 };
 const validateEvents = async (source, events, logger) => {
     const valid = [];

package/dist/wirings/trigger/webhook-source.types.d.ts

@@ -120,10 +120,11 @@ export type CoreTriggerWebhookSource<Events extends Record<string, StandardSchem
     /** What the secret is and where to find it, shown to whoever has to set it. */
     credentialDescription?: string;
     /**
-     * Checked before `receive` on every request with a body. A request is
+     * Checked before `receive` on every request. A request with a body is
      * refused when the credential is not set or the signature does not match.
-     * A request without a body — a HEAD probe, a validation token in the query —
-     * reaches `receive` unchecked, and may be answered but dispatches nothing.
+     * A request without a body that fails the check — a HEAD probe, a
+     * validation token in the query — still reaches `receive`, which may answer
+     * it, but any events it returns are refused.
      */
     verify?: WebhookVerify;
     /** Omitted: the JSON body is one event dispatched to the trigger named `<name>`. */

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

@@ -3,6 +3,7 @@
  * These types define the step-based workflow format extracted by the inspector
  */
 import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { SerializedError } from '../../../errors/serialized-error.js';
 import type { WorkflowRun } from '../workflow.types.js';
 import type { ScenarioPersona } from '../../../services/personas-service.js';
 import type { ScenarioStepOptions, ScenarioStepPhase, ScenarioSurface } from '../scenario-step.types.js';
@@ -17,12 +18,11 @@ export interface WorkflowStepOptions {
     /** Delay between retry attempts (e.g., '1s', '2s', '2min') */
     retryDelay?: string | number;
     /**
-     * RPC to invoke for compensation when this step fails after exhausting its
-     * retries. Mirrors a graph node's `onError`: the handler receives
-     * `{ error: { message } }` and the original error is still thrown, so the
-     * workflow fails — this is compensation, not recovery.
+     * Set to `false` to leave this step out of an unwind even though its
+     * function declares a `compensate`. It cannot substitute a different
+     * compensation.
      */
-    onError?: string;
+    compensate?: false;
     /**
      * Run this step as an actor (scenarios). The RPC is sent through the
      * actor's authenticated client over the REAL transport — never dispatched
@@ -93,6 +93,10 @@ export type WorkflowWireSleep = (stepName: string, duration: string) => Promise<
  * loops, like dynamic `do()` step names.
  */
 export type WorkflowWireSuspend = (reason: string) => Promise<void>;
+/**
+ * Type signature for workflow.milestone() - used by inspector.
+ */
+export type WorkflowWireMilestone = (name: string) => Promise<void>;
 /**
  * Who is allowed to answer an approval gate, relative to the user who started
  * the run.
@@ -436,6 +440,14 @@ export interface SuspendStepMeta {
     /** Reason string passed to workflow.suspend() — becomes the durable step key */
     reason: string;
 }
+/**
+ * Milestone step metadata (workflow.milestone())
+ */
+export interface MilestoneStepMeta {
+    type: 'milestone';
+    /** Name passed to workflow.milestone() — where a compensating run rests */
+    name: string;
+}
 /**
  * Approval step metadata (workflow.approval())
  */
@@ -485,7 +497,7 @@ export interface ArrayPredicateStepMeta {
 /**
  * Workflow step metadata (extracted by inspector)
  */
-export type WorkflowStepMeta = RpcStepMeta | ScenarioStepMeta | BranchStepMeta | ParallelGroupStepMeta | FanoutStepMeta | ReturnStepMeta | InlineStepMeta | SleepStepMeta | CancelStepMeta | SuspendStepMeta | ApprovalStepMeta | SwitchStepMeta | FilterStepMeta | ArrayPredicateStepMeta | SetStepMeta;
+export type WorkflowStepMeta = RpcStepMeta | ScenarioStepMeta | BranchStepMeta | ParallelGroupStepMeta | FanoutStepMeta | ReturnStepMeta | InlineStepMeta | SleepStepMeta | CancelStepMeta | SuspendStepMeta | MilestoneStepMeta | ApprovalStepMeta | SwitchStepMeta | FilterStepMeta | ArrayPredicateStepMeta | SetStepMeta;
 /**
  * Workflow step wire context for RPC functions
  * Provides step-level metadata including retry attempt tracking
@@ -520,7 +532,22 @@ export interface WorkflowStepWire {
  * Workflow wire object for DSL workflows
  * Provides workflow-specific capabilities to function execution
  */
+export type CompensatingFor<Out = unknown> = {
+    ok: true;
+    output: Out;
+    stepName?: string;
+} | {
+    ok: false;
+    output: null;
+    error: SerializedError;
+    stepName?: string;
+};
 export interface PikkuWorkflowWire {
+    /**
+     * Set only while a function's `compensate` is running: the outcome of the
+     * forward call being undone. `undefined` on a forward run.
+     */
+    compensatingFor?: CompensatingFor;
     /** The workflow name */
     name: string;
     /** The current run ID */
@@ -535,6 +562,11 @@ export interface PikkuWorkflowWire {
     sleep: WorkflowWireSleep;
     /** Suspend workflow until explicitly resumed */
     suspend: WorkflowWireSuspend;
+    /**
+     * A named checkpoint. On failure the unwind stops at the last milestone
+     * reached and the run rests there. The name must be a string literal.
+     */
+    milestone: WorkflowWireMilestone;
     /** Suspend workflow until a human records a decision against this gate */
     approval: WorkflowWireApproval;
 }

package/dist/wirings/workflow/graph/graph-node.d.ts

@@ -27,7 +27,8 @@ type GraphNodeConfigMap<FuncMap extends Record<string, string>, RPCMap extends R
         /** How the per-item instances run. Defaults to 'parallel'. */
         mode?: ForEachMode;
         input?: (ref: <N extends Extract<keyof FuncMap, string>, P extends keyof ComputeNodeOutputs<FuncMap, RPCMap>[N] & string>(nodeId: N, path: P) => TypedRef<ComputeNodeOutputs<FuncMap, RPCMap>[N][P]>, template: TemplateFn, $item: ItemFn) => InputWithRefs<ComputeNodeInputs<FuncMap, RPCMap>[K]>;
-        onError?: Extract<keyof FuncMap, string> | Extract<keyof FuncMap, string>[];
+        recover?: Extract<keyof FuncMap, string> | Extract<keyof FuncMap, string>[] | 'ignore';
+        compensate?: false;
         retries?: number;
         retryDelay?: string | number;
         notes?: string;

package/dist/wirings/workflow/graph/graph-node.js

@@ -20,7 +20,8 @@ export function createGraph() {
                 mode: def?.mode,
                 input: def?.input,
                 next: def?.next,
-                onError: def?.onError,
+                recover: def?.recover,
+                compensate: def?.compensate,
                 retries: def?.retries,
                 retryDelay: def?.retryDelay,
             };

package/dist/wirings/workflow/graph/graph-runner.d.ts

@@ -8,7 +8,7 @@ export declare class ChildWorkflowStartedException extends Error {
     constructor(parentRunId: string, stepId: string, childRunId: string);
 }
 export declare function stripInstanceOrdinal(name: string): string;
-export declare function continueGraph(workflowService: PikkuWorkflowService, runId: string, graphName: string, overrideMeta?: WorkflowRuntimeMeta): Promise<void>;
+export declare function continueGraph(workflowService: PikkuWorkflowService, runId: string, graphName: string, overrideMeta?: WorkflowRuntimeMeta, rpcService?: any): Promise<void>;
 export declare function executeGraphStep(workflowService: PikkuWorkflowService, rpcService: any, runId: string, stepId: string, nodeId: string, rpcName: string, data: any, graphName: string): Promise<any>;
 export declare function runFromMeta(workflowService: PikkuWorkflowService, runId: string, meta: WorkflowRuntimeMeta, _rpcService: any): Promise<void>;
 export declare function runWorkflowGraph(workflowService: PikkuWorkflowService, graphName: string, triggerInput: any, rpcService?: any, inline?: boolean, startNode?: string, wire?: WorkflowRunWire, overrideMeta?: WorkflowRuntimeMeta): Promise<{