@pithy-sh/core 0.1.2 → 0.1.4

package/dist/workflow/dispatch.js

@@ -0,0 +1,148 @@
+import { PithyError, messageOf } from "../error/pithyError.js";
+import "../worker/identity.js";
+import { noopLogger } from "../logger/logger.js";
+import { originVarName } from "../env/stem.js";
+import { loopbackWorkflowBinding } from "./loopback.js";
+//#region src/workflow/dispatch.ts
+/**
+* Read a binding off the per-request env, narrowed to the one method dispatch needs.
+*
+* Exported because the host's dispatch route ({@link ./dispatchRoute.ts}) asks the same question of
+* the same env, and a second duck-type would be a second answer to "is this a Workflow binding" the
+* first day one of them learned about a new shape.
+*/
+function workflowBindingFor(env, name) {
+	const value = env[name];
+	if (typeof value !== "object" || value === null) return void 0;
+	return typeof value.create === "function" ? value : void 0;
+}
+/** The one environment a loopback substitution is made in. Verbatim, and the only one. */
+const LOOPBACK_ENVIRONMENT = "dev";
+/** A non-blank string off the env, or `undefined`. Anything else on that key is not an address. */
+function stringVar(env, name) {
+	const value = env[name];
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : void 0;
+}
+/**
+* The binding to dispatch on: the real one, or — under `pithy dev` — a loopback stand-in for it.
+*
+* ## Why a stand-in exists at all
+*
+* A deployed app Worker starts a capability's Workflow through a **cross-script** binding pointing at
+* `<project>-<env>-email`. `pithy dev` runs no script under that name, so locally that binding cannot
+* work — it is absent, or it is present and every `create` on it fails — and every dispatch it carried
+* went nowhere (pithy-sh/pithy#410). What *does* exist locally is the capability host itself, on a
+* pinned port, with its address in this Worker's own vars as `<STEM>_ORIGIN`. So the seam is filled
+* rather than left empty, and the call site — `enqueueEmail`, the cron handler, `c.var.workflows` — is
+* byte-identical either way.
+*
+* ## Three rules, and each of them is a refusal
+*
+* **In `dev`, a published origin wins over the binding.** The deliberate order, and the one that
+* closes #410 whatever wrangler decides to hand a local Worker for a script it is not running: a
+* binding that is present but cannot reach anything is indistinguishable at runtime from one that
+* works, so preferring it would leave the silence in place and depend on a wrangler behavior nothing
+* here controls. Preferring the origin costs nothing, because a published origin is not something a
+* composition can have by accident — see the next rule.
+*
+* **A published origin names a host `pithy dev` is running.** The orchestrator writes one `--var` per
+* *capability host* in the dev set, and never hands a host its own address. So `EMAIL_ORIGIN` on a
+* Worker's env means exactly one thing: the email host is up, locally, there. An adopter's own
+* app-owned Workflow — the same-script shape, which `wrangler dev` implements unchanged — is never
+* published an origin and so is never diverted.
+*
+* **Only `dev`.** Not `staging`, not `prod`, and — the case that matters — not a composition that
+* stamped no environment at all. A gate that reads silence as `dev` opens itself in exactly the
+* deployment whose `wrangler.jsonc` lost the var.
+*
+* **The environment comes off the request env, not off the host's shell.** `--var ENVIRONMENT` is
+* what puts it on a Worker, and the shell that ran `wrangler dev` does not cross into workerd. The
+* dispatch *route* reads the ambient env instead, because it is registered before any request exists;
+* here there is a request env in hand, and it is the truthful one.
+*/
+function resolveWorkflowBinding(env, request) {
+	const origin = stringVar(env, "ENVIRONMENT") === LOOPBACK_ENVIRONMENT ? stringVar(env, originVarName(request.capability)) : void 0;
+	if (origin) {
+		request.log?.debug("workflow dispatch over loopback", {
+			binding: request.binding,
+			capability: request.capability,
+			origin
+		});
+		return loopbackWorkflowBinding({
+			origin,
+			binding: request.binding,
+			capability: request.capability,
+			fetch: request.fetch
+		});
+	}
+	return workflowBindingFor(env, request.binding);
+}
+/**
+* Start one registered job. The single dispatch path — `createBackend`'s per-request dispatcher and
+* `createEntrypoint`'s cron handler both route through here, so a scheduled run and a manual one
+* validate identically.
+*/
+async function triggerWorkflow(env, registry, key, params, log = noopLogger) {
+	const entry = registry[key];
+	if (!entry) {
+		const known = Object.keys(registry).sort().join(", ");
+		throw new PithyError({
+			code: "core/unknown_workflow",
+			status: 500,
+			message: `No workflow is registered as "${key}".`,
+			action: "Check the key, and compose the capability that declares the job.",
+			detail: known ? `Registered workflows: ${known}.` : "No capability registered any workflow."
+		});
+	}
+	const parsed = entry.spec.params.safeParse(params);
+	if (!parsed.success) throw new PithyError({
+		code: "core/invalid_workflow_params",
+		status: 400,
+		message: `The parameters for workflow "${key}" are not valid.`,
+		action: "Correct the parameters to match the workflow's schema.",
+		detail: parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")
+	});
+	const binding = resolveWorkflowBinding(env, {
+		binding: entry.spec.binding,
+		capability: entry.capability,
+		log
+	});
+	if (!binding) {
+		if (entry.spec.optional) {
+			log.warn("workflow skipped", {
+				workflow: key,
+				binding: entry.spec.binding,
+				reason: "binding absent — the workflow host is not deployed or not bound"
+			});
+			return;
+		}
+		throw new PithyError({
+			code: "core/missing_workflow_binding",
+			status: 500,
+			message: `The workflow binding "${entry.spec.binding}" is not available.`,
+			action: `Deploy the ${entry.capability} workflow host, then bind ${entry.spec.binding} in wrangler.jsonc.`,
+			detail: `Dispatching "${key}" needs a Workflow binding named ${entry.spec.binding} on the Worker env.`
+		});
+	}
+	try {
+		await binding.create({ params: parsed.data });
+	} catch (error) {
+		if (!entry.spec.optional) throw error;
+		log.warn("workflow skipped", {
+			workflow: key,
+			binding: entry.spec.binding,
+			reason: messageOf(error)
+		});
+	}
+}
+/**
+* Build the per-request dispatcher over one registry. A closure rather than a lazily-built registry
+* object: there is one method and no per-job resource to construct, so there is nothing to defer.
+*/
+function buildWorkflowDispatcher(env, registry, log = noopLogger) {
+	return { trigger: (key, params) => triggerWorkflow(env, registry, key, params, log) };
+}
+//#endregion
+export { buildWorkflowDispatcher, resolveWorkflowBinding, triggerWorkflow, workflowBindingFor };

package/dist/workflow/dispatchRoute.d.ts

@@ -0,0 +1,80 @@
+import type { Hono } from "hono";
+import type { PithyHonoEnv } from "../capability/capability";
+import { type AmbientEnv } from "../env/ambient";
+import type { VerificationStrategy } from "../http/verification";
+import type { WorkflowRegistry } from "./spec";
+/**
+ * The host's dispatch route — the loopback door `pithy dev` starts an instance through.
+ *
+ * ## Why a host needs an HTTP door at all
+ *
+ * A deployed app Worker starts a capability's Workflow through a **cross-script** binding:
+ * `{ binding: "EMAIL_SENDER", script_name: "<project>-<env>-email" }`. `pithy dev` does not run that
+ * second Worker's script under that name, and CLAUDE.md rules out wrangler's cross-`wrangler dev`
+ * registry, so locally the binding names nothing and the call throws (pithy-sh/pithy#410). What
+ * *does* exist locally is loopback: every worker in the dev set has a pinned port and an
+ * `<STEM>_ORIGIN` in every sibling's env. This route is the other end of that wire.
+ *
+ * The instance is started on the **host's own same-script binding** — the one with no `script_name`,
+ * which `wrangler dev` implements unchanged. So the local path and the deployed path run the same
+ * Workflow class, from the same registry, with the same params schema. Only the hop differs.
+ *
+ * ## The environment gate is the security boundary
+ *
+ * An HTTP door into another Worker's Workflows is not something the kit leaves open. The route is
+ * served in a `dev` composition and refused in every other, by a guard that runs before anything
+ * reads the request.
+ *
+ * **It is a mounted refusal, not an unmounted route** — deliberately the opposite of
+ * `@pithy-sh/auth`'s dev-login, and the difference is what the two routes do. Dev-login mints an
+ * authenticated session with no credential presented, so its existence in a production route table is
+ * itself the finding, and it registers nothing outside `dev`. This route starts a job the host
+ * already runs on its own cron, on a binding the caller must already have, and it starts nothing at
+ * all before the guard has run. What an operator gains from mounting it is the answer: a loopback
+ * dispatcher wired into `staging` by mistake gets `auth/forbidden` naming the binding as the path,
+ * rather than a 404 that reads as a typo and sends them looking at the URL.
+ *
+ * **There is no second CI gate**, and that too is the opposite of dev-login's, on purpose. CI is
+ * precisely where the local loop has to work — `pithy dev` under an integration suite is a `dev`
+ * composition dispatching over loopback — and a gate that shut it there would turn the silence #410
+ * repairs back on in the one place nobody is watching for it.
+ *
+ * ## Contract
+ *
+ * `public` verification and a declared request contract, with the guard ahead of both validators so
+ * a refusal is never downgraded to a 400 that tells a caller which request shapes are well-formed.
+ */
+/**
+ * How the route verifies its caller: it does not.
+ *
+ * Stated rather than omitted, because every route declares one (CLAUDE.md §HTTP) and `public` is the
+ * honest answer — there is no credential on this wire. What stands in for one is the environment
+ * gate plus the address: the route answers only in a `dev` composition, and a `dev` composition is a
+ * `wrangler dev` bound to loopback on a port `pithy dev` pinned. Deployed environments reach the same
+ * Workflow through the cross-script binding and never through this.
+ */
+export declare const WORKFLOW_DISPATCH_VERIFICATION: VerificationStrategy;
+/** What the route needs to serve: whose host this is, what it hosts, and where it is running. */
+export interface WorkflowDispatchOptions {
+    /** The capability that owns the host. Named in refusals, so an operator knows which Worker answered. */
+    capability: string;
+    /**
+     * The composed registry this host runs. The route resolves `:binding` against it, so a binding the
+     * host hosts no Workflow for is refused by name — and the params validate against the declaring
+     * spec's own schema rather than against anything restated here.
+     */
+    registry: WorkflowRegistry;
+    /**
+     * The ambient environment the gate reads. Defaults to the process env, which in a Worker is the
+     * script's own vars — where `pithy init` stamps `ENVIRONMENT`. Injectable for tests.
+     */
+    env?: AmbientEnv;
+}
+/**
+ * Mount the dispatch route on a host worker's app.
+ *
+ * The guard is registered as middleware ahead of the validators so the order is structural rather
+ * than remembered: outside `dev` nothing reads the path, the body, or the env.
+ */
+export declare function registerWorkflowDispatchRoute(app: Hono<PithyHonoEnv>, options: WorkflowDispatchOptions): void;
+//# sourceMappingURL=dispatchRoute.d.ts.map

package/dist/workflow/dispatchRoute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatchRoute.d.ts","sourceRoot":"","sources":["../../src/workflow/dispatchRoute.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAW,IAAI,EAAQ,MAAM,MAAM,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,KAAK,UAAU,EAAsC,MAAM,gBAAgB,CAAC;AAGrF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAQjE,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,8BAA8B,EAAE,oBAA+B,CAAC;AAK7E,iGAAiG;AACjG,MAAM,WAAW,uBAAuB;IACtC,wGAAwG;IACxG,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,QAAQ,EAAE,gBAAgB,CAAC;IAC3B;;;OAGG;IACH,GAAG,CAAC,EAAE,UAAU,CAAC;CAClB;AAqBD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,uBAAuB,GAAG,IAAI,CAkE7G"}

package/dist/workflow/dispatchRoute.js

@@ -0,0 +1,134 @@
+import { ForbiddenError, PithyError } from "../error/pithyError.js";
+import { validationHook } from "../http/validation.js";
+import { WORKFLOW_DISPATCH_ROUTE, WorkflowDispatchParams, WorkflowDispatchRequest } from "./schemas.js";
+import { workflowBindingFor } from "./dispatch.js";
+import { ambientEnv, compositionEnvironment } from "../env/ambient.js";
+import { zValidator } from "@hono/zod-validator";
+//#region src/workflow/dispatchRoute.ts
+/**
+* The host's dispatch route — the loopback door `pithy dev` starts an instance through.
+*
+* ## Why a host needs an HTTP door at all
+*
+* A deployed app Worker starts a capability's Workflow through a **cross-script** binding:
+* `{ binding: "EMAIL_SENDER", script_name: "<project>-<env>-email" }`. `pithy dev` does not run that
+* second Worker's script under that name, and CLAUDE.md rules out wrangler's cross-`wrangler dev`
+* registry, so locally the binding names nothing and the call throws (pithy-sh/pithy#410). What
+* *does* exist locally is loopback: every worker in the dev set has a pinned port and an
+* `<STEM>_ORIGIN` in every sibling's env. This route is the other end of that wire.
+*
+* The instance is started on the **host's own same-script binding** — the one with no `script_name`,
+* which `wrangler dev` implements unchanged. So the local path and the deployed path run the same
+* Workflow class, from the same registry, with the same params schema. Only the hop differs.
+*
+* ## The environment gate is the security boundary
+*
+* An HTTP door into another Worker's Workflows is not something the kit leaves open. The route is
+* served in a `dev` composition and refused in every other, by a guard that runs before anything
+* reads the request.
+*
+* **It is a mounted refusal, not an unmounted route** — deliberately the opposite of
+* `@pithy-sh/auth`'s dev-login, and the difference is what the two routes do. Dev-login mints an
+* authenticated session with no credential presented, so its existence in a production route table is
+* itself the finding, and it registers nothing outside `dev`. This route starts a job the host
+* already runs on its own cron, on a binding the caller must already have, and it starts nothing at
+* all before the guard has run. What an operator gains from mounting it is the answer: a loopback
+* dispatcher wired into `staging` by mistake gets `auth/forbidden` naming the binding as the path,
+* rather than a 404 that reads as a typo and sends them looking at the URL.
+*
+* **There is no second CI gate**, and that too is the opposite of dev-login's, on purpose. CI is
+* precisely where the local loop has to work — `pithy dev` under an integration suite is a `dev`
+* composition dispatching over loopback — and a gate that shut it there would turn the silence #410
+* repairs back on in the one place nobody is watching for it.
+*
+* ## Contract
+*
+* `public` verification and a declared request contract, with the guard ahead of both validators so
+* a refusal is never downgraded to a 400 that tells a caller which request shapes are well-formed.
+*/
+/**
+* How the route verifies its caller: it does not.
+*
+* Stated rather than omitted, because every route declares one (CLAUDE.md §HTTP) and `public` is the
+* honest answer — there is no credential on this wire. What stands in for one is the environment
+* gate plus the address: the route answers only in a `dev` composition, and a `dev` composition is a
+* `wrangler dev` bound to loopback on a port `pithy dev` pinned. Deployed environments reach the same
+* Workflow through the cross-script binding and never through this.
+*/
+const WORKFLOW_DISPATCH_VERIFICATION = "public";
+/** The environment this route serves in. Verbatim, and the only one. */
+const DISPATCH_ENVIRONMENT = "dev";
+/** The job this host hosts on a given binding, or `undefined`. */
+function specForBinding(registry, binding) {
+	return Object.values(registry).find((entry) => entry.spec.binding === binding);
+}
+/**
+* The refusal. `auth/forbidden` (403) rather than a 404: the door exists, it is shut because of
+* *where* this Worker is running, and pretending otherwise costs the operator the sentence that ends
+* their search. `action` names the real path and is stripped before it reaches the caller, like every
+* other action.
+*/
+function refuseOutsideDev(capability, environment) {
+	return new ForbiddenError({
+		message: `Workflow dispatch over HTTP is served only in the ${DISPATCH_ENVIRONMENT} environment.`,
+		action: `Dispatch through the cross-script ${capability} Workflow binding, or run this host under pithy dev.`,
+		detail: `The composition's ENVIRONMENT is ${environment ?? "unstamped"}.`
+	});
+}
+/**
+* Mount the dispatch route on a host worker's app.
+*
+* The guard is registered as middleware ahead of the validators so the order is structural rather
+* than remembered: outside `dev` nothing reads the path, the body, or the env.
+*/
+function registerWorkflowDispatchRoute(app, options) {
+	const { capability, registry } = options;
+	const ambient = options.env;
+	const guard = async (_c, next) => {
+		const environment = compositionEnvironment(ambient ?? ambientEnv());
+		if (environment !== DISPATCH_ENVIRONMENT) throw refuseOutsideDev(capability, environment);
+		await next();
+	};
+	app.post(WORKFLOW_DISPATCH_ROUTE, guard, zValidator("param", WorkflowDispatchParams, validationHook), zValidator("json", WorkflowDispatchRequest, validationHook), async (c) => {
+		const { binding } = c.req.valid("param");
+		const { id, params } = c.req.valid("json");
+		const entry = specForBinding(registry, binding);
+		if (!entry) {
+			const known = Object.values(registry).map((registered) => registered.spec.binding).sort().join(", ");
+			throw new PithyError({
+				code: "core/unknown_workflow",
+				status: 500,
+				message: `No workflow on this host is bound to "${binding}".`,
+				action: `Check the binding name against the ${capability} capability's declared workflows.`,
+				detail: known ? `This host hosts: ${known}.` : "This host hosts no workflows at all."
+			});
+		}
+		const parsed = entry.spec.params.safeParse(params);
+		if (!parsed.success) throw new PithyError({
+			code: "core/invalid_workflow_params",
+			status: 400,
+			message: `The parameters for workflow "${entry.key}" are not valid.`,
+			action: "Correct the parameters to match the workflow's schema.",
+			detail: parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")
+		});
+		const target = workflowBindingFor(c.env, binding);
+		if (!target) throw new PithyError({
+			code: "core/missing_workflow_binding",
+			status: 500,
+			message: `The workflow binding "${binding}" is not available on this host.`,
+			action: `Bind ${binding} in the ${capability} host's wrangler.jsonc, then restart it.`,
+			detail: `Dispatching "${entry.key}" needs a same-script Workflow binding named ${binding}.`
+		});
+		await target.create({
+			id,
+			params: parsed.data
+		});
+		return c.json({
+			binding,
+			id,
+			started: true
+		}, 202);
+	});
+}
+//#endregion
+export { WORKFLOW_DISPATCH_VERIFICATION, registerWorkflowDispatchRoute };

package/dist/workflow/faults.d.ts

@@ -0,0 +1,97 @@
+/**
+ * **Every fault that reaches a durable step is classified — retryable or terminal — at a stated site.**
+ *
+ * A Workflow is chosen *because of* its retry semantics: durable execution, a journal, steps that resume,
+ * backoff that survives an eviction. A step that inherits the platform default has not decided; it has
+ * deferred, and the default is retry-everything. So a deterministic refusal — a name that already exists,
+ * a value too large, a payload that will not parse — is answered slowly instead of immediately, the retry
+ * budget burns down on an answer that cannot change, and an instant refusal looks like an outage
+ * (pithy-sh/pithy#338).
+ *
+ * ## The three layers, and which owns what
+ *
+ * 1. **The capability states its own codes.** A {@link WorkflowRetryPolicy} names the `PithyError` codes
+ *    that capability retries, each with the reason a second attempt can answer differently. One statement
+ *    per capability, in one file, the way `@pithy-sh/email`'s `errorMapping.ts` already states the Email
+ *    Service's `E_*` codes.
+ * 2. **Core owns D1.** `withD1Retry` already classifies D1's fault vocabulary, so this asks it rather than
+ *    growing a second copy — and that is also the no-double-retry rule: a fault the inner layer refused to
+ *    retry (a constraint violation, a SQL error) is terminal here too, while a transient one stays
+ *    retryable so the step re-drives it with backoff far longer than the inner loop's.
+ * 3. **Everything else is terminal.** Retry is opted into, never inherited. The platform default is the
+ *    opposite, and it is the wrong way round: a terminal fault wrongly called transient burns the whole
+ *    budget before surfacing, while a transient one wrongly called terminal surfaces immediately with the
+ *    fault written on it. One of those is a diagnosis; the other is a hang.
+ *
+ * ## Where the wrapping happens, and why it cannot be anywhere else
+ *
+ * {@link classifiedSteps} converts a terminal fault **inside** the step callback. The platform's retry loop
+ * lives inside `step.do`: by the time a `step.do` promise rejects, every retry has already been spent. A
+ * wrapper around the call would classify a fault the engine had already re-driven five times — correct
+ * looking, and exactly as slow as doing nothing.
+ */
+/** Whether the platform should try a step's body again, or stop with the answer it has. */
+export type WorkflowFaultDisposition = "retry" | "terminal";
+/**
+ * One capability's stated retry classification — the whole of what it retries, and why.
+ *
+ * A record rather than a set, because the value is the argument: "what would a second attempt see that
+ * this one did not" is the question that decides, and writing the answer down is what keeps the next code
+ * from being added to the list by reflex.
+ */
+export interface WorkflowRetryPolicy {
+    /** The capability whose Workflows this governs — `secrets`, `payments`, `email`. Named in the fault's reason. */
+    capability: string;
+    /**
+     * `PithyError` code → why a retry can answer differently. **Everything absent is terminal**, including
+     * codes another capability retries: a 502 from a payment rail is worth re-driving, and a 502 from a
+     * store that has already taken the write is not.
+     */
+    retryable: Readonly<Record<string, string>>;
+}
+/** One fault, classified: what it was, what happens next, and the stated reason for it. */
+export interface WorkflowFault {
+    /** Retry, or stop. */
+    disposition: WorkflowFaultDisposition;
+    /** The `PithyError` code, `d1/<fault>` for a D1 fault class, or `unclassified`. */
+    code: string;
+    /** Why — the policy's own sentence for a retry, or what made this terminal. */
+    reason: string;
+}
+/**
+ * Classify one fault against a capability's policy. Pure, so a capability's classification is a unit
+ * test rather than a claim — and so the same function decides in a test, in Miniflare, and in production.
+ */
+export declare function classifyWorkflowFault(error: unknown, policy: WorkflowRetryPolicy): WorkflowFault;
+/** The half of a Workflow step this kit uses: run a named body, or serve its journalled result. */
+export interface WorkflowStepLike {
+    /** Run a named step, or return its journalled result if this instance already completed it. */
+    do<T>(name: string, fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * The platform's terminal-error class — `NonRetryableError` from `cloudflare:workflows`, taken as a
+ * parameter.
+ *
+ * Injected rather than imported because `@pithy-sh/core` is bundled into every adopter's Worker *and*
+ * imported by the CLI under node, so it may not import a `cloudflare:` module. The Workflow class is
+ * already inside workerd and already imports one; handing the class in costs it a word and keeps the
+ * classification itself testable anywhere.
+ *
+ * **One argument, deliberately.** `NonRetryableError`'s constructor also takes a `name`, and the engine
+ * recognizes the error *by* that name: measured against a real Workflow in `wrangler dev`, passing any
+ * name but the default turned an instance that failed in 0.7s back into one that retried for 32s and
+ * then failed. The signature is narrowed so nobody can reintroduce that by being helpful.
+ */
+export interface TerminalErrorConstructor {
+    new (message: string): Error;
+}
+/**
+ * Wrap a Workflow's step runner so every fault it raises is classified against `policy`, and a terminal
+ * one is re-thrown as the platform's terminal error — **inside the step**, before the retry loop reads it.
+ *
+ * The result is structurally a step runner, so a body that already takes one (`reconcilePayments`,
+ * `runSendBatch`, `runAtRestKeyRotation`) takes this instead with no change: the classification is
+ * declared once, at the entrypoint, and every step below it inherits the decision.
+ */
+export declare function classifiedSteps(step: WorkflowStepLike, policy: WorkflowRetryPolicy, terminalError: TerminalErrorConstructor): WorkflowStepLike;
+//# sourceMappingURL=faults.d.ts.map

package/dist/workflow/faults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"faults.d.ts","sourceRoot":"","sources":["../../src/workflow/faults.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,2FAA2F;AAC3F,MAAM,MAAM,wBAAwB,GAAG,OAAO,GAAG,UAAU,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,iHAAiH;IACjH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC7C;AAED,2FAA2F;AAC3F,MAAM,WAAW,aAAa;IAC5B,sBAAsB;IACtB,WAAW,EAAE,wBAAwB,CAAC;IACtC,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;CAChB;AAsDD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,mBAAmB,GAAG,aAAa,CA0BhG;AAED,mGAAmG;AACnG,MAAM,WAAW,gBAAgB;IAC/B,+FAA+F;IAC/F,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACvD;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,wBAAwB;IACvC,KAAK,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,gBAAgB,EACtB,MAAM,EAAE,mBAAmB,EAC3B,aAAa,EAAE,wBAAwB,GACtC,gBAAgB,CA2BlB"}

package/dist/workflow/faults.js

@@ -0,0 +1,111 @@
+import { PithyError } from "../error/pithyError.js";
+import { d1TransientFault } from "../data/withD1Retry.js";
+import { encodeWorkflowStepMessage } from "./stepMessage.js";
+//#region src/workflow/faults.ts
+/** The `code` reported for a throw no layer recognizes. */
+const UNCLASSIFIED = "unclassified";
+/**
+* The code a thrown value carries, or `null` when it is not a `PithyError`.
+*
+* The structural read is not belt-and-braces: `instanceof` is per module instance, and a bundler that
+* gives a host worker two copies of core would silently answer `false` for a perfectly good
+* `PithyError` — which here means classifying a stated retryable fault as terminal. The shape is
+* checked, not assumed.
+*/
+function pithyCodeOf(error) {
+	if (error instanceof PithyError) return error.payload.code;
+	if (error && typeof error === "object" && "payload" in error) {
+		const payload = error.payload;
+		if (payload && typeof payload === "object" && "code" in payload) {
+			const code = payload.code;
+			if (typeof code === "string") return code;
+		}
+	}
+	return null;
+}
+/** The public message of a thrown value, for the terminal error's own text. */
+function messageOf(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* The operator's remedy a thrown value carries, or `undefined` when it states none.
+*
+* Read structurally for the same reason {@link pithyCodeOf} is: `instanceof` is per module instance,
+* and two copies of core in one bundle would answer `false` for a perfectly good `PithyError` — here
+* meaning a remedy the raising error stated is silently dropped at the boundary. That is the bug this
+* function exists to end, so it is not reintroduced by the check.
+*
+* **`detail` is deliberately not read here, and there is no sibling for it.** `action` is already
+* operator-facing — the CLI prints it, `operatorError` includes it. `detail` is throw-site context and
+* stays at the throw site.
+*/
+function pithyActionOf(error) {
+	if (error instanceof PithyError) return error.payload.action;
+	if (error && typeof error === "object" && "payload" in error) {
+		const payload = error.payload;
+		if (payload && typeof payload === "object" && "action" in payload) {
+			const action = payload.action;
+			if (typeof action === "string") return action;
+		}
+	}
+}
+/**
+* Classify one fault against a capability's policy. Pure, so a capability's classification is a unit
+* test rather than a claim — and so the same function decides in a test, in Miniflare, and in production.
+*/
+function classifyWorkflowFault(error, policy) {
+	const code = pithyCodeOf(error);
+	if (code !== null) {
+		const reason = policy.retryable[code];
+		if (reason !== void 0) return {
+			disposition: "retry",
+			code,
+			reason
+		};
+		return {
+			disposition: "terminal",
+			code,
+			reason: `${policy.capability} does not retry ${code}: a second attempt reaches the same answer.`
+		};
+	}
+	const d1 = d1TransientFault(error);
+	if (d1 !== null) return {
+		disposition: "retry",
+		code: `d1/${d1}`,
+		reason: `D1 reported a transient ${d1} fault; withD1Retry classifies it retryable.`
+	};
+	return {
+		disposition: "terminal",
+		code: UNCLASSIFIED,
+		reason: `Nothing classifies this fault, and ${policy.capability} retries only what it states.`
+	};
+}
+/**
+* Wrap a Workflow's step runner so every fault it raises is classified against `policy`, and a terminal
+* one is re-thrown as the platform's terminal error — **inside the step**, before the retry loop reads it.
+*
+* The result is structurally a step runner, so a body that already takes one (`reconcilePayments`,
+* `runSendBatch`, `runAtRestKeyRotation`) takes this instead with no change: the classification is
+* declared once, at the entrypoint, and every step below it inherits the decision.
+*/
+function classifiedSteps(step, policy, terminalError) {
+	return { do(name, fn) {
+		return step.do(name, async () => {
+			try {
+				return await fn();
+			} catch (error) {
+				const fault = classifyWorkflowFault(error, policy);
+				if (fault.disposition === "retry") throw error;
+				const terminal = new terminalError(encodeWorkflowStepMessage({
+					code: fault.code,
+					message: messageOf(error),
+					action: pithyActionOf(error)
+				}));
+				terminal.cause = error;
+				throw terminal;
+			}
+		});
+	} };
+}
+//#endregion
+export { classifiedSteps, classifyWorkflowFault };