@pikku/skills 0.12.46 → 0.12.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.46",
+  "version": "0.12.47",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",

package/skills/pikku-wiring/references/trigger.md

@@ -113,8 +113,8 @@ subscribe to its events as `<source>:<event>`:
   logged and dropped; so is one no `wireTrigger` listens for. Both still get a
   `200`, so the provider does not retry forever.
 - `receive(services, { body, headers, method, url, query })` gets the **raw
-  bytes** — verify the signature over those — and returns `{ events: [{ name,
-id?, data }] }`, or `{ respond: { status, body } }` for a handshake. Throwing
+  bytes** and only parses them: it returns `{ events: [{ name, id?, data }] }`,
+  or `{ respond: { status, body } }` for a handshake. Throwing
   rejects the request with the error's status (`UnauthorizedError` → 401).
   Omitted, the JSON body becomes one event dispatched to a trigger named just
   `<source>`.
@@ -129,12 +129,31 @@ id?, data }] }`, or `{ respond: { status, body } }` for a handshake. Throwing
   even on queues that ignore job ids, and records each attempt and its last
   error. Its `webhookReceipt` table comes from `pikku db generate`; `pikku dev`
   and `pikku serve` use it when a Kysely database is configured.
-- `receive` sees singleton services without `secrets`. Declare the signing
-  secret with `defineCredential({ type: 'singleton', ... })` and hold it as
-  `WebhookSigningSecret.fromCredential(provider, credentialService, name)`
-  from `@pikku/core/hmac`; `receive` calls `await signingSecret.load()` and
-  checks against what it returns. A handshake that hands over the secret
-  (Asana) stores it with `credentialService.set`.
+- Signature checks belong in `verify`, never in `receive`. pikku runs it on
+  every request against the secret in the credential
+  `<name>WebhookSecret` (camelCased: `microsoft-outlook` →
+  `microsoftOutlookWebhookSecret`; `credential` overrides it). Declaring
+  `verify` declares that credential as a singleton string, so there is no
+  `defineCredential` and no service holding the secret; `credentialDescription`
+  tells whoever sets it where to find it. Pick the declared form that matches
+  the provider:
+  - `{ hmac: { header, prefix?, algorithm, encoding, secretEncoding? } }`:
+    a signature over the raw body in one header (GitHub, Shopify, Linear).
+  - `{ token: { header, prefix? } }`: the provider echoes the shared secret
+    (GitLab, Telegram).
+  - `{ publicKey: { header, algorithm?, dsaEncoding? } }`: signed with the
+    provider's private key; the stored secret is its PEM public key (Wise).
+  - Anything else (a timestamp in the signed payload, a signature in the body
+    or query, a URL in the signed string) is a function
+    `(request, secret, services) => boolean`, built from `hmacDigest`,
+    `verifyHmacSignature`, `verifyPublicKeySignature` and
+    `timingSafeStringEqual` in `@pikku/core/hmac`.
+
+  A request with a body that fails is refused with a 401. A bodiless request
+  that fails (a HEAD probe, a validation token in the query) still reaches
+  `receive` so it can answer the handshake, but any events it returns are
+  refused. A handshake that hands over the secret (Asana) stores it with
+  `credentialService.set` under the same credential name.
 
 `check`, `setup` and `teardown` register the route with the provider. Each gets
 `{ url, label, events, previous? }`, where `events` are only the ones some

package/skills/pikku-workflow/SKILL.md

@@ -237,38 +237,52 @@ with `outcome: 'success' | 'denied'`, the decider under `userIdentity`, and the
 run, reason and refusal in `metadata`. Wire an `audit` service to keep it; a
 project without one records nothing and is otherwise unaffected.
 
-### Error handling: `onError`, never try/catch
+### Failure: `compensate`, never try/catch
 
 **Do not wrap steps in try/catch.** The DSL extractor serialises the body into a
 step graph, and a `catch` block is control flow it cannot represent — so the
-graph would no longer describe what actually runs, which is the whole point of
-the DSL mode. This is a settled design decision, not a temporary limitation.
+graph would no longer describe what actually runs. This is a settled design
+decision, not a temporary limitation.
 
-Use the `onError` step option instead: it names an RPC to invoke when the step
-has failed _after_ exhausting its retries.
+Declare how a function is undone **on the function itself**. When a later step
+fails (after its retries), the engine runs the `compensate` of every earlier
+step that completed, newest first, then the failed step's own:
 
 ```typescript
-await workflow.do(
-  'Charge',
-  'chargePayment',
-  { orderId },
-  {
-    retries: 3,
-    retryDelay: '1s',
-    onError: 'refundReservation', // compensation RPC
-  }
-)
+export const chargePayment = pikkuFunc({
+  func: async ({ payments }, { orderId }) => payments.charge(orderId),
+  compensate: async ({ payments }, { orderId }, { workflow }) => {
+    const { ok, output } = workflow!.compensatingFor!
+    // ok: false → the charge itself failed; output is null, `error` is set
+    if (ok) await payments.refund(output.chargeId)
+  },
+})
 ```
 
-The handler receives `{ error: { message } }`, and the original error is still
-thrown afterwards — so the workflow still fails. `onError` is **compensation, not
-recovery**: it exists to undo work, not to swallow the failure and carry on. If
-you genuinely need to branch on a failure, have the step return a result object
-(`{ success: false, reason }`) and branch on that, the way the `processOrder`
-example branches on `payment.success`.
-
-Full step options: `description`, `retries`, `retryDelay`, `onError` (plus
-`actor`, which is scenario-only — see `pikku-scenario`).
+- `compensate` gets the **same input** as the forward call. `wire.workflow.compensatingFor`
+  is `{ ok: true, output, stepName }` or `{ ok: false, output: null, error, stepName }`.
+- It is never callable over HTTP, MCP or RPC — only the engine runs it, as the
+  durable step `<step>:compensate` with the same retry defaults as forward steps.
+- Opt a call site out with `{ compensate: false }` (graph nodes likewise).
+- A run ends `compensated` (everything undone), `compensation_failed` (a
+  compensation ran out of retries; `stuckSteps` names them — steps that ran
+  before a stuck one are not undone, parallel siblings still are) or `failed`
+  (nothing needed undoing).
+- `await workflow.milestone('paid')` bounds the unwind: steps finished before the
+  last milestone are kept, and the run ends `compensated` with `restedAt: 'paid'`.
+- A failing child workflow unwinds itself first; a stuck child makes the parent
+  `compensation_failed`. Cancelling a run (`cancelRun`) unwinds it the same way,
+  children first.
+
+To **recover** instead of undo, use a graph node's `recover`:
+`recover: 'nodeId' | ['a','b'] | 'ignore'`. The failure is routed to those nodes
+(`'ignore'` continues to `next` with a null output) and the failing step is not
+compensated. The error arrives as `wire.graph.recoveringFrom`
+(`{ nodeId, stepName, error }`). The DSL has no recovery — branch on a result
+object (`{ success: false, reason }`) instead.
+
+Full step options: `description`, `retries`, `retryDelay`, `compensate: false`
+(plus `actor`, which is scenario-only — see `pikku-scenario`).
 
 ### Parallel fan-out
 

package/skills/pikku-workflow/references/workflow-reference.md

@@ -2,7 +2,7 @@
 
 ## Step execution: inline vs queue dispatch
 
-Whether a step runs **inline** (same process/session, no queue round-trip) or is **dispatched to the queue** is decided **purely by the step's function** — there is no workflow-level or per-call dispatch flag. `workflow.do(...)` options are only `description`/`retries`/`retryDelay`/`onError`.
+Whether a step runs **inline** (same process/session, no queue round-trip) or is **dispatched to the queue** is decided **purely by the step's function** — there is no workflow-level or per-call dispatch flag. `workflow.do(...)` options are only `description`/`retries`/`retryDelay`/`compensate: false`.
 
 - **Steps default to inline.** Most steps don't need their own worker; running them inline avoids a queue round-trip per step, so a normally-started workflow executes its whole chain in one orchestrator pass.
 - **`workflowQueued: true` opts a function out.** Set it on the **function config** (`pikkuFunc` / `pikkuSessionlessFunc`, same level as `auth`/`expose`) to dispatch that step via the queue — for expensive/long-running steps that deserve their own worker, retry isolation, and concurrency limits. `workflowRetries` and `workflowTimeout` sit alongside it.