@pithy-sh/cloudflare 0.1.2 → 0.1.3

package/dist/workflows/stepFailure.d.ts

@@ -0,0 +1,180 @@
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
+/**
+ * **The step's sentence, recovered from an instance the engine has already written its own over.**
+ *
+ * A Workflow instance carries two failure texts. The instance-level `error` is the *platform's*: when a
+ * step raises `NonRetryableError`, the engine replaces whatever was thrown with
+ * `"The execution of the Workflow instance was terminated, as a step threw an NonRetryableError…"`.
+ * The step's own entry in `steps[]` still holds the text the kit raised. Reporting the first is how
+ * `pithy secrets create` on a name that already exists started answering with a sentence about durable
+ * execution instead of one about the secret (pithy-sh/pithy#349), the day #338 made that refusal terminal.
+ *
+ * So this reads the step, and it is read *here* rather than at a call site: every dispatch that polls a
+ * Workflow — secrets write and probe, payments reconcile, vector reprocess — goes through one
+ * `dispatchAndPoll`, and a rule that lives in the primitive cannot be missed by the next caller.
+ *
+ * ## What may cross into an operator's `message`, and what may not
+ *
+ * A `PithyError`'s `message` is public and its `detail` is stripped at the HTTP boundary — that is the
+ * security boundary, and this function is on the wrong side of it: the text arrives from a Worker whose
+ * code we did not write, over an API, and it could say anything. So a step's text is promoted into the
+ * operator's `message` **only when it is demonstrably a sentence the kit itself authored as public**:
+ *
+ * - `PithyError: <text>` — the throw's own name is the proof. `PithyError.message` *is*
+ *   `payload.message`, the field already written to be safe for a client.
+ * - The encoding core's `classifiedSteps` writes, inside the platform's terminal envelope. **This file
+ *   does not restate that encoding**; it calls `decodeWorkflowStepMessage`, which is the same module
+ *   the writer calls, for the reason in its own doc comment: two packages agreeing about a string by
+ *   each writing it down is a coincidence, not a contract (pithy-sh/pithy#353).
+ *
+ * Anything else — a foreign throw, a bare string, the engine's own prose — stays in `detail`, where it
+ * always was. Nothing that was not already public becomes public here.
+ *
+ * `action` rides that encoding and is promoted with the sentence, because it is already the operator's
+ * field: the CLI prints it under the problem line and `operatorError` includes it. `detail` does not
+ * cross, has no encoding, and is not read here.
+ *
+ * ## The literals are captured, not guessed
+ *
+ * Every platform string below was read off a real Workflows engine — the shipped Workflow class driven
+ * under `wrangler dev` (wrangler 4.123.0, 2026-08-14), instance detail fetched from the local dev
+ * session's own instance endpoint. They are frozen so the gate in `stepFailure.test.ts` polices a fixed
+ * set rather than whatever this file happens to believe today.
+ */
+/** A failure as the Workflows API records one: a class name and its text. Instance-level and per-step alike. */
+export declare const WorkflowFailureDetail: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type WorkflowFailureDetail = z.output<typeof WorkflowFailureDetail>;
+/** One attempt at a step. The engine appends one per retry, so the last failed one is the answer. */
+export declare const WorkflowStepAttempt: z.ZodObject<{
+    success: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    error: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type WorkflowStepAttempt = z.output<typeof WorkflowStepAttempt>;
+/**
+ * One entry in an instance's `steps[]`.
+ *
+ * The API's four step shapes (`step`, `sleep`, `waitForEvent`, `termination`) differ in where the
+ * failure lives — a `step` keeps one per attempt, the others keep one on the entry — so both are
+ * optional here and the reader takes whichever is present. Unknown fields (`config`, `output`,
+ * timestamps) are stripped rather than refused: this is a diagnostic read, and a step shape nobody
+ * anticipated must not turn a failed Workflow into a parse error about the failure report.
+ */
+export declare const WorkflowStepRecord: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodString>;
+    success: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    error: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    attempts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        success: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        error: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            message: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type WorkflowStepRecord = z.output<typeof WorkflowStepRecord>;
+/** What a failed instance's steps say about why, once the platform's own prose is set aside. */
+export interface WorkflowStepFailure {
+    /** The failed step's name, when the engine reported one. */
+    step?: string;
+    /** The step's recorded text, verbatim, platform envelope and all. For `detail` — never for `message`. */
+    raw: string;
+    /** The `PithyError` code the step raised, when its text carries one. */
+    code?: string;
+    /** The step's own public sentence — present only when the text is one the kit authored. */
+    sentence?: string;
+    /** The remedy the raising error stated, when it stated one. The CLI's action line. */
+    action?: string;
+}
+/**
+ * The kit-authored public sentence inside a step's recorded text, and the remedy riding with it —
+ * `null` when there is none.
+ *
+ * Exported for the gate, which drives captured engine output through it: a platform sentence reaching an
+ * operator is a test failure, and the test has to be able to ask this question directly.
+ */
+export declare function kitSentence(raw: string): {
+    code?: string;
+    message: string;
+    action?: string;
+} | null;
+/**
+ * The last step that failed, and what it said. `null` when no step reports a failure — an instance the
+ * platform failed on its own (a timeout, a terminate) has steps that all succeeded, or none at all.
+ *
+ * Read from the end: the failing step is the last one the instance reached, and an earlier step that
+ * failed and was retried into success has nothing to say about why the instance ended.
+ *
+ * Each entry is validated on its way in and an entry that will not parse is skipped rather than thrown
+ * on. The caller is already reporting a failure; refusing to describe it because one step of the report
+ * had an unfamiliar shape trades a useful sentence for a useless one.
+ */
+export declare function stepFailure(steps: readonly unknown[] | undefined): WorkflowStepFailure | null;
+/**
+ * The code a terminal Workflow failure falls back to when the fault that ended the run cannot be
+ * attributed. Stated here because two things must agree on it: the thrower below, and the gate that
+ * proves this code is not one a transport failure can arrive under.
+ */
+export declare const WORKFLOW_FAILED_CODE: "core/workflow_failed";
+/** The status pinned to {@link WORKFLOW_FAILED_CODE}, restated so the throw cannot drift off it. */
+export declare const WORKFLOW_FAILED_STATUS: 500;
+/**
+ * **The error an operator is handed for a Workflow that ran and did not complete** (pithy-sh/pithy#365).
+ *
+ * `#353` fixed the sentence and the remedy. The `code` and the `status` were still the *transport's*:
+ * `dispatchAndPoll` threw `CloudflareRequestError`, which fixes `cloudflare/request_failed` and 502 by
+ * construction, so a step that raised `secrets/already_exists` with 409 reached the CLI as a 502 —
+ * "the far side is broken, try later" for a request that was delivered, ran, and was permanently
+ * refused. Anything branching on the pair rather than reading the prose was told the opposite of what
+ * happened.
+ *
+ * ## The distinction that has to survive, and where it lives
+ *
+ * A Workflow whose *step raised* is not the same event as a dispatch that could not be delivered, and
+ * the difference is now in the two machine-readable fields rather than in the message:
+ *
+ * - **The step raised, and the kit pins a status for its code** → that code, that status. Terminal by
+ *   the code's own definition; `secrets/already_exists` is a 409 wherever it is raised.
+ * - **The run ended and nothing is attributable** — a foreign throw, the platform's own prose, an
+ *   `unclassified` fault, an adopter code the kit pins no status for → {@link WORKFLOW_FAILED_CODE},
+ *   500. Terminal, and deliberately not 502.
+ * - **The dispatch itself failed** — the REST call was refused, timed out, or answered with a shape
+ *   nobody expected → `cloudflare/request_failed` / `cloudflare/invalid_response`, 502, thrown by
+ *   `cloudflareRequest` exactly as before. This function is never reached for one.
+ *
+ * So the reader tells them apart on `code` alone, and the three sets are disjoint.
+ *
+ * ## Why the status is recovered from the code rather than carried on the wire
+ *
+ * Nothing but `code`, `message` and `action` crosses a durable step boundary — the engine records the
+ * throw's text and discards the throw. A fourth field could have been encoded, at the cost of
+ * reopening a format `#353` froze against a measurement. It is not needed: **every kit member pins
+ * `status` to one literal**, so the code *is* the status (`kitErrorStatus`). A code the kit does not
+ * define has no pinned status, and rather than invent one this says so with its own code.
+ *
+ * ## `detail` still does not cross
+ *
+ * `detail` is composed here from the platform's raw text and the instance id — the operator's side of
+ * the boundary — and nothing derived from the step's own `detail` is in it, because the step's
+ * `detail` never left the step. The only fields promoted from the far side are `message` and `action`,
+ * both already public, both already proved kit-authored by `kitSentence`.
+ */
+export declare function terminalWorkflowError(args: {
+    /** What the instance's steps said, or `null` when no step reported a failure. */
+    failure: WorkflowStepFailure | null;
+    /** The sentence to use when the step authored none — the caller's own, about the instance. */
+    fallbackMessage: string;
+    /** The operator's context line. Raw platform text and the instance id; never the dispatched params. */
+    detail: string;
+}): PithyError;
+//# sourceMappingURL=stepFailure.d.ts.map

package/dist/workflows/stepFailure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stepFailure.d.ts","sourceRoot":"","sources":["../../src/workflows/stepFailure.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AAMjE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,gHAAgH;AAChH,eAAO,MAAM,qBAAqB;;;iBAQwD,CAAC;AAC3F,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE3E,qGAAqG;AACrG,eAAO,MAAM,mBAAmB;;;;;;iBAK0D,CAAC;AAC3F,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;iBAQ+D,CAAC;AAC/F,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAErE,gGAAgG;AAChG,MAAM,WAAW,mBAAmB;IAClC,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yGAAyG;IACzG,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAmBD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAqBnG;AAcD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,GAAG,mBAAmB,GAAG,IAAI,CAoB7F;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAG,sBAA+B,CAAC;AAEpE,oGAAoG;AACpG,eAAO,MAAM,sBAAsB,EAAG,GAAY,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,iFAAiF;IACjF,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACpC,8FAA8F;IAC9F,eAAe,EAAE,MAAM,CAAC;IACxB,uGAAuG;IACvG,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,UAAU,CAmBb"}

package/dist/workflows/stepFailure.js

@@ -0,0 +1,227 @@
+import { z } from "zod";
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import { ErrorPayload, kitErrorStatus } from "@pithy-sh/core/src/error/payload";
+import { MAX_WORKFLOW_STEP_TEXT, decodeWorkflowStepMessage, splitWorkflowStepCode } from "@pithy-sh/core/src/workflow/stepMessage";
+//#region src/workflows/stepFailure.ts
+/**
+* **The step's sentence, recovered from an instance the engine has already written its own over.**
+*
+* A Workflow instance carries two failure texts. The instance-level `error` is the *platform's*: when a
+* step raises `NonRetryableError`, the engine replaces whatever was thrown with
+* `"The execution of the Workflow instance was terminated, as a step threw an NonRetryableError…"`.
+* The step's own entry in `steps[]` still holds the text the kit raised. Reporting the first is how
+* `pithy secrets create` on a name that already exists started answering with a sentence about durable
+* execution instead of one about the secret (pithy-sh/pithy#349), the day #338 made that refusal terminal.
+*
+* So this reads the step, and it is read *here* rather than at a call site: every dispatch that polls a
+* Workflow — secrets write and probe, payments reconcile, vector reprocess — goes through one
+* `dispatchAndPoll`, and a rule that lives in the primitive cannot be missed by the next caller.
+*
+* ## What may cross into an operator's `message`, and what may not
+*
+* A `PithyError`'s `message` is public and its `detail` is stripped at the HTTP boundary — that is the
+* security boundary, and this function is on the wrong side of it: the text arrives from a Worker whose
+* code we did not write, over an API, and it could say anything. So a step's text is promoted into the
+* operator's `message` **only when it is demonstrably a sentence the kit itself authored as public**:
+*
+* - `PithyError: <text>` — the throw's own name is the proof. `PithyError.message` *is*
+*   `payload.message`, the field already written to be safe for a client.
+* - The encoding core's `classifiedSteps` writes, inside the platform's terminal envelope. **This file
+*   does not restate that encoding**; it calls `decodeWorkflowStepMessage`, which is the same module
+*   the writer calls, for the reason in its own doc comment: two packages agreeing about a string by
+*   each writing it down is a coincidence, not a contract (pithy-sh/pithy#353).
+*
+* Anything else — a foreign throw, a bare string, the engine's own prose — stays in `detail`, where it
+* always was. Nothing that was not already public becomes public here.
+*
+* `action` rides that encoding and is promoted with the sentence, because it is already the operator's
+* field: the CLI prints it under the problem line and `operatorError` includes it. `detail` does not
+* cross, has no encoding, and is not read here.
+*
+* ## The literals are captured, not guessed
+*
+* Every platform string below was read off a real Workflows engine — the shipped Workflow class driven
+* under `wrangler dev` (wrangler 4.123.0, 2026-08-14), instance detail fetched from the local dev
+* session's own instance endpoint. They are frozen so the gate in `stepFailure.test.ts` polices a fixed
+* set rather than whatever this file happens to believe today.
+*/
+/** A failure as the Workflows API records one: a class name and its text. Instance-level and per-step alike. */
+const WorkflowFailureDetail = z.object({
+	name: z.string().optional().describe("The thrown value's class name, as the engine recorded it."),
+	message: z.string().optional().describe("The failure text — the engine's own for a terminal step, else the throw's.")
+}).describe("One failure the Workflows API reports, on an instance or on a step attempt.");
+/** One attempt at a step. The engine appends one per retry, so the last failed one is the answer. */
+const WorkflowStepAttempt = z.object({
+	success: z.boolean().nullish().describe("Whether this attempt returned; `false` once it threw."),
+	error: WorkflowFailureDetail.nullish().describe("What this attempt threw, absent when it returned.")
+}).describe("One attempt at a Workflow step, as the instance-detail endpoint reports it.");
+/**
+* One entry in an instance's `steps[]`.
+*
+* The API's four step shapes (`step`, `sleep`, `waitForEvent`, `termination`) differ in where the
+* failure lives — a `step` keeps one per attempt, the others keep one on the entry — so both are
+* optional here and the reader takes whichever is present. Unknown fields (`config`, `output`,
+* timestamps) are stripped rather than refused: this is a diagnostic read, and a step shape nobody
+* anticipated must not turn a failed Workflow into a parse error about the failure report.
+*/
+const WorkflowStepRecord = z.object({
+	name: z.string().optional().describe("The step's name, as `step.do` was called with it."),
+	type: z.string().optional().describe("Which of the API's step shapes this is — `step`, `sleep`, `waitForEvent`."),
+	success: z.boolean().nullish().describe("Whether the step completed; `false` once every attempt failed."),
+	error: WorkflowFailureDetail.nullish().describe("The failure, for the shapes that record one on the entry."),
+	attempts: z.array(WorkflowStepAttempt).optional().describe("Each attempt at the step, oldest first.")
+}).describe("One step of a Workflow instance, narrowed to the fields a failure report reads.");
+/**
+* The envelope the engine wraps a terminal step throw in, captured verbatim. The inner text is *not*
+* JSON-quoted — a message containing a `"` is embedded raw — so this is a prefix/suffix strip and never
+* a `JSON.parse`.
+*/
+const TERMINAL_STEP_ENVELOPE = Object.freeze({
+	prefix: "Step threw a NonRetryableError with message \"",
+	suffix: "\""
+});
+/**
+* The throw names a kit step error can arrive under. `PithyError` is core's one throw vehicle;
+* `NonRetryableError` is what `classifiedSteps` re-throws a terminal fault as. A name outside this set
+* is somebody else's error, and its text stays in `detail`.
+*/
+const KIT_THROW_NAMES = Object.freeze(["PithyError", "NonRetryableError"]);
+/**
+* The kit-authored public sentence inside a step's recorded text, and the remedy riding with it —
+* `null` when there is none.
+*
+* Exported for the gate, which drives captured engine output through it: a platform sentence reaching an
+* operator is a test failure, and the test has to be able to ask this question directly.
+*/
+function kitSentence(raw) {
+	let text = raw.trim();
+	if (text.startsWith(TERMINAL_STEP_ENVELOPE.prefix) && text.endsWith(TERMINAL_STEP_ENVELOPE.suffix)) text = text.slice(TERMINAL_STEP_ENVELOPE.prefix.length, -TERMINAL_STEP_ENVELOPE.suffix.length);
+	const thrown = KIT_THROW_NAMES.map((name) => `${name}: `).find((prefix) => text.startsWith(prefix));
+	if (thrown === void 0) return null;
+	text = text.slice(thrown.length);
+	if (thrown === "NonRetryableError: ") return decodeWorkflowStepMessage(text);
+	const { code, rest } = splitWorkflowStepCode(text);
+	const message = rest.trim();
+	if (message === "" || message.length > MAX_WORKFLOW_STEP_TEXT) return null;
+	if (/[\n\r]/.test(message)) return null;
+	return code === void 0 ? { message } : {
+		code,
+		message
+	};
+}
+/** The recorded failure text of one step entry, from its last failed attempt or its own error. */
+function failureTextOf(step) {
+	for (let index = (step.attempts?.length ?? 0) - 1; index >= 0; index -= 1) {
+		const attempt = step.attempts?.[index];
+		if (attempt?.success === true) continue;
+		const message = attempt?.error?.message;
+		if (message !== void 0 && message !== "") return message;
+	}
+	const own = step.error?.message;
+	return own === void 0 || own === "" ? void 0 : own;
+}
+/**
+* The last step that failed, and what it said. `null` when no step reports a failure — an instance the
+* platform failed on its own (a timeout, a terminate) has steps that all succeeded, or none at all.
+*
+* Read from the end: the failing step is the last one the instance reached, and an earlier step that
+* failed and was retried into success has nothing to say about why the instance ended.
+*
+* Each entry is validated on its way in and an entry that will not parse is skipped rather than thrown
+* on. The caller is already reporting a failure; refusing to describe it because one step of the report
+* had an unfamiliar shape trades a useful sentence for a useless one.
+*/
+function stepFailure(steps) {
+	if (steps === void 0) return null;
+	for (let index = steps.length - 1; index >= 0; index -= 1) {
+		const parsed = WorkflowStepRecord.safeParse(steps[index]);
+		if (!parsed.success) continue;
+		if (parsed.data.success === true) continue;
+		const raw = failureTextOf(parsed.data);
+		if (raw === void 0) continue;
+		const kit = kitSentence(raw);
+		return {
+			...parsed.data.name === void 0 ? {} : { step: parsed.data.name },
+			raw,
+			...kit?.code === void 0 ? {} : { code: kit.code },
+			...kit === null ? {} : { sentence: kit.message },
+			...kit?.action === void 0 ? {} : { action: kit.action }
+		};
+	}
+	return null;
+}
+/**
+* The code a terminal Workflow failure falls back to when the fault that ended the run cannot be
+* attributed. Stated here because two things must agree on it: the thrower below, and the gate that
+* proves this code is not one a transport failure can arrive under.
+*/
+const WORKFLOW_FAILED_CODE = "core/workflow_failed";
+/** The status pinned to {@link WORKFLOW_FAILED_CODE}, restated so the throw cannot drift off it. */
+const WORKFLOW_FAILED_STATUS = 500;
+/**
+* **The error an operator is handed for a Workflow that ran and did not complete** (pithy-sh/pithy#365).
+*
+* `#353` fixed the sentence and the remedy. The `code` and the `status` were still the *transport's*:
+* `dispatchAndPoll` threw `CloudflareRequestError`, which fixes `cloudflare/request_failed` and 502 by
+* construction, so a step that raised `secrets/already_exists` with 409 reached the CLI as a 502 —
+* "the far side is broken, try later" for a request that was delivered, ran, and was permanently
+* refused. Anything branching on the pair rather than reading the prose was told the opposite of what
+* happened.
+*
+* ## The distinction that has to survive, and where it lives
+*
+* A Workflow whose *step raised* is not the same event as a dispatch that could not be delivered, and
+* the difference is now in the two machine-readable fields rather than in the message:
+*
+* - **The step raised, and the kit pins a status for its code** → that code, that status. Terminal by
+*   the code's own definition; `secrets/already_exists` is a 409 wherever it is raised.
+* - **The run ended and nothing is attributable** — a foreign throw, the platform's own prose, an
+*   `unclassified` fault, an adopter code the kit pins no status for → {@link WORKFLOW_FAILED_CODE},
+*   500. Terminal, and deliberately not 502.
+* - **The dispatch itself failed** — the REST call was refused, timed out, or answered with a shape
+*   nobody expected → `cloudflare/request_failed` / `cloudflare/invalid_response`, 502, thrown by
+*   `cloudflareRequest` exactly as before. This function is never reached for one.
+*
+* So the reader tells them apart on `code` alone, and the three sets are disjoint.
+*
+* ## Why the status is recovered from the code rather than carried on the wire
+*
+* Nothing but `code`, `message` and `action` crosses a durable step boundary — the engine records the
+* throw's text and discards the throw. A fourth field could have been encoded, at the cost of
+* reopening a format `#353` froze against a measurement. It is not needed: **every kit member pins
+* `status` to one literal**, so the code *is* the status (`kitErrorStatus`). A code the kit does not
+* define has no pinned status, and rather than invent one this says so with its own code.
+*
+* ## `detail` still does not cross
+*
+* `detail` is composed here from the platform's raw text and the instance id — the operator's side of
+* the boundary — and nothing derived from the step's own `detail` is in it, because the step's
+* `detail` never left the step. The only fields promoted from the far side are `message` and `action`,
+* both already public, both already proved kit-authored by `kitSentence`.
+*/
+function terminalWorkflowError(args) {
+	const { failure, fallbackMessage, detail } = args;
+	const message = failure?.sentence ?? fallbackMessage;
+	const action = failure?.sentence === void 0 ? void 0 : failure.action;
+	const status = failure?.code === void 0 ? void 0 : kitErrorStatus(failure.code);
+	if (failure?.sentence !== void 0 && failure.code !== void 0 && status !== void 0) {
+		const candidate = {
+			code: failure.code,
+			status,
+			message,
+			action,
+			detail
+		};
+		const parsed = ErrorPayload.safeParse(candidate);
+		if (parsed.success) return new PithyError(parsed.data);
+	}
+	return new PithyError({
+		code: WORKFLOW_FAILED_CODE,
+		status: 500,
+		message,
+		action,
+		detail
+	});
+}
+//#endregion
+export { WORKFLOW_FAILED_CODE, WORKFLOW_FAILED_STATUS, WorkflowFailureDetail, WorkflowStepAttempt, WorkflowStepRecord, kitSentence, stepFailure, terminalWorkflowError };

package/dist/workflows/workflowsClient.d.ts

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import { CloudflareManager, type CloudflareManagerConfig } from "../client/manager";
+/** Pause `ms` milliseconds between status polls. Injectable so tests run with no real delay. */
+export type Sleeper = (ms: number) => Promise<void>;
+export interface CloudflareWorkflowsClientConfig extends CloudflareManagerConfig {
+    /** Override the poll delay (tests). Defaults to a real `setTimeout`. */
+    sleeper?: Sleeper;
+}
+export declare const WorkflowInstanceStatus: z.ZodEnum<{
+    complete: "complete";
+    errored: "errored";
+    paused: "paused";
+    queued: "queued";
+    rollingBack: "rollingBack";
+    running: "running";
+    terminated: "terminated";
+    unknown: "unknown";
+    waiting: "waiting";
+    waitingForPause: "waitingForPause";
+}>;
+export type WorkflowInstanceStatus = z.output<typeof WorkflowInstanceStatus>;
+export declare const WorkflowInstance: z.ZodObject<{
+    status: z.ZodEnum<{
+        complete: "complete";
+        errored: "errored";
+        paused: "paused";
+        queued: "queued";
+        rollingBack: "rollingBack";
+        running: "running";
+        terminated: "terminated";
+        unknown: "unknown";
+        waiting: "waiting";
+        waitingForPause: "waitingForPause";
+    }>;
+    output: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodNull]>>;
+    steps: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+}, z.core.$strip>;
+export type WorkflowInstance = z.output<typeof WorkflowInstance>;
+/**
+ * A client over the Cloudflare Workflows API — the only sanctioned way to reach CF Workflows from
+ * outside a Worker (CLAUDE.md: no hand-rolled CF `fetch` outside `@pithy-sh/cloudflare`). The
+ * `pithy secrets` CLI uses it to trigger a per-env manager's Workflow and poll to completion: the
+ * CLI never runs secret logic locally, since the master key is worker-only.
+ *
+ * The SDK owns transport and envelope handling. Instance status is still re-validated through
+ * {@link WorkflowInstance} rather than taken from the SDK's types: the SDK narrows `output` to
+ * `string | number`, but a Workflow's return value is arbitrary JSON, and the status enum is a wire
+ * value we decode at the boundary like every other external input.
+ */
+export declare class CloudflareWorkflowsClient extends CloudflareManager {
+    #private;
+    constructor(config: CloudflareWorkflowsClientConfig);
+    getServiceType(): string;
+    /** Prove reach by listing the account's Workflows; never throws. */
+    validateServiceAccess(): Promise<boolean>;
+    /** Create (trigger) a Workflow instance and return its id. */
+    createInstance(workflowName: string, params: unknown, instanceId?: string): Promise<string>;
+    /** Fetch an instance's status. Returns `null` on a 404 (a just-created instance can briefly lag). */
+    getInstanceStatus(workflowName: string, instanceId: string): Promise<WorkflowInstance | null>;
+    /**
+     * Trigger a Workflow and poll until it reaches a terminal state. Resolves with the instance
+     * `output` on `complete`. The error never carries the dispatched params (which may be secret).
+     *
+     * **Three failures, three codes, and a caller can tell them apart without reading a word of prose**
+     * (pithy-sh/pithy#365):
+     *
+     * | What happened | Code | Status |
+     * |---|---|---|
+     * | A step raised, and the kit pins a status for its code | that code | that status |
+     * | The run ended terminally, nothing attributable | `core/workflow_failed` | 500 |
+     * | The dispatch or a poll could not be delivered | `cloudflare/request_failed` | 502 |
+     * | We stopped waiting; the instance may still finish | `core/upstream_timeout` | 504 |
+     *
+     * The first two are terminal — the run is over and re-driving it reaches the same end. The last two
+     * are not. Reporting all of them as 502 told an operator to wait for a recovery that would never
+     * come; see `terminalWorkflowError` for the argument in full.
+     */
+    dispatchAndPoll(workflowName: string, params: unknown, options?: {
+        pollIntervalMs?: number;
+        maxPolls?: number;
+        instanceId?: string;
+    }): Promise<unknown>;
+}
+//# sourceMappingURL=workflowsClient.d.ts.map

package/dist/workflows/workflowsClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflowsClient.d.ts","sourceRoot":"","sources":["../../src/workflows/workflowsClient.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,KAAK,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAGpF,gGAAgG;AAChG,MAAM,MAAM,OAAO,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEpD,MAAM,WAAW,+BAAgC,SAAQ,uBAAuB;IAC9E,wEAAwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,eAAO,MAAM,sBAAsB;;;;;;;;;;;EAawD,CAAC;AAC5F,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE7E,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;iBAqBuE,CAAC;AACrG,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAOjE;;;;;;;;;;GAUG;AACH,qBAAa,yBAA0B,SAAQ,iBAAiB;;IAG9D,YAAY,MAAM,EAAE,+BAA+B,EAGlD;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,oEAAoE;IAC9D,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED,8DAA8D;IACxD,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYhG;IAED,qGAAqG;IAC/F,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAoBlG;IAED;;;;;;;;;;;;;;;;;OAiBG;IACG,eAAe,CACnB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,OAAO,EACf,OAAO,GAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAO,GAChF,OAAO,CAAC,OAAO,CAAC,CAmClB;CACF"}

package/dist/workflows/workflowsClient.js

@@ -0,0 +1,156 @@
+import { CloudflareInvalidResponseError, cloudflareRequest, isNotFoundError } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+import { stepFailure, terminalWorkflowError } from "./stepFailure.js";
+import { z } from "zod";
+import { UpstreamTimeoutError } from "@pithy-sh/core/src/error/pithyError";
+//#region src/workflows/workflowsClient.ts
+const WorkflowInstanceStatus = z.enum([
+	"queued",
+	"running",
+	"paused",
+	"errored",
+	"terminated",
+	"complete",
+	"waitingForPause",
+	"waiting",
+	"rollingBack",
+	"unknown"
+]).describe("Lifecycle state of a Cloudflare Workflow instance, from the status endpoint.");
+const WorkflowInstance = z.object({
+	status: WorkflowInstanceStatus.describe("The instance's current lifecycle state."),
+	output: z.unknown().optional().describe("The Workflow's return value, present once `status` is `complete`."),
+	error: z.union([
+		z.string(),
+		z.object({ message: z.string().optional().describe("Failure message.") }).describe("The structured form of the failure, when the API sends an object rather than a string."),
+		z.null()
+	]).optional().describe("The instance-level failure, present when `status` is `errored` or `terminated`."),
+	steps: z.array(z.unknown()).optional().describe("The instance's steps, each validated where it is read (`stepFailure`). Held as `unknown` here on purpose: the API has four step shapes, this client reads one field of one of them, and a shape nobody anticipated must not turn a failed Workflow into a parse error about the failure report.")
+}).describe("A Cloudflare Workflow instance's status, as returned by the instance-detail endpoint.");
+/** Terminal states a poll stops on. */
+const TERMINAL = /* @__PURE__ */ new Set([
+	"complete",
+	"errored",
+	"terminated"
+]);
+const defaultSleeper = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+* A client over the Cloudflare Workflows API — the only sanctioned way to reach CF Workflows from
+* outside a Worker (CLAUDE.md: no hand-rolled CF `fetch` outside `@pithy-sh/cloudflare`). The
+* `pithy secrets` CLI uses it to trigger a per-env manager's Workflow and poll to completion: the
+* CLI never runs secret logic locally, since the master key is worker-only.
+*
+* The SDK owns transport and envelope handling. Instance status is still re-validated through
+* {@link WorkflowInstance} rather than taken from the SDK's types: the SDK narrows `output` to
+* `string | number`, but a Workflow's return value is arbitrary JSON, and the status enum is a wire
+* value we decode at the boundary like every other external input.
+*/
+var CloudflareWorkflowsClient = class extends CloudflareManager {
+	#sleeper;
+	constructor(config) {
+		super(config);
+		this.#sleeper = config.sleeper ?? defaultSleeper;
+	}
+	getServiceType() {
+		return "Workflows";
+	}
+	/** Prove reach by listing the account's Workflows; never throws. */
+	async validateServiceAccess() {
+		try {
+			for await (const _workflow of this.getClient().workflows.list({ account_id: this.accountId })) break;
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/** Create (trigger) a Workflow instance and return its id. */
+	async createInstance(workflowName, params, instanceId) {
+		return cloudflareRequest(`create instance of ${workflowName}`, async () => {
+			const created = await this.getClient().workflows.instances.create(workflowName, {
+				account_id: this.accountId,
+				params,
+				...instanceId ? { instance_id: instanceId } : {}
+			});
+			if (!created.id) throw new CloudflareInvalidResponseError({ detail: `create instance of ${workflowName}: missing instance id` });
+			return created.id;
+		});
+	}
+	/** Fetch an instance's status. Returns `null` on a 404 (a just-created instance can briefly lag). */
+	async getInstanceStatus(workflowName, instanceId) {
+		const operation = `get status of ${workflowName}/${instanceId}`;
+		return cloudflareRequest(operation, async () => {
+			let response;
+			try {
+				response = await this.getClient().workflows.instances.get(instanceId, {
+					account_id: this.accountId,
+					workflow_name: workflowName
+				});
+			} catch (error) {
+				if (isNotFoundError(error)) return null;
+				throw error;
+			}
+			const parsed = WorkflowInstance.safeParse(response);
+			if (!parsed.success) throw new CloudflareInvalidResponseError({ detail: `${operation}: unexpected shape` });
+			return parsed.data;
+		});
+	}
+	/**
+	* Trigger a Workflow and poll until it reaches a terminal state. Resolves with the instance
+	* `output` on `complete`. The error never carries the dispatched params (which may be secret).
+	*
+	* **Three failures, three codes, and a caller can tell them apart without reading a word of prose**
+	* (pithy-sh/pithy#365):
+	*
+	* | What happened | Code | Status |
+	* |---|---|---|
+	* | A step raised, and the kit pins a status for its code | that code | that status |
+	* | The run ended terminally, nothing attributable | `core/workflow_failed` | 500 |
+	* | The dispatch or a poll could not be delivered | `cloudflare/request_failed` | 502 |
+	* | We stopped waiting; the instance may still finish | `core/upstream_timeout` | 504 |
+	*
+	* The first two are terminal — the run is over and re-driving it reaches the same end. The last two
+	* are not. Reporting all of them as 502 told an operator to wait for a recovery that would never
+	* come; see `terminalWorkflowError` for the argument in full.
+	*/
+	async dispatchAndPoll(workflowName, params, options = {}) {
+		const pollIntervalMs = options.pollIntervalMs ?? 1e3;
+		const maxPolls = options.maxPolls ?? 120;
+		const id = await this.createInstance(workflowName, params, options.instanceId);
+		for (let poll = 0; poll < maxPolls; poll++) {
+			await this.#sleeper(pollIntervalMs);
+			const instance = await this.getInstanceStatus(workflowName, id);
+			if (!instance) continue;
+			if (!TERMINAL.has(instance.status)) continue;
+			if (instance.status === "complete") return instance.output;
+			const failure = stepFailure(instance.steps);
+			throw terminalWorkflowError({
+				failure,
+				fallbackMessage: `Workflow ${workflowName} did not complete (${instance.status}).`,
+				detail: `instance ${id} ended ${instance.status}: ${describeFailure(failure, instance.error)}`
+			});
+		}
+		throw new UpstreamTimeoutError({
+			message: `Workflow ${workflowName} did not finish in time.`,
+			action: `Check the instance in the Cloudflare dashboard; it may still complete.`,
+			detail: `instance ${id} still running after ${maxPolls} polls`
+		});
+	}
+};
+/** The most specific instance-error text, for a failure `detail`. Never the dispatched params. */
+function describeError(error) {
+	if (!error) return "no error detail";
+	if (typeof error === "string") return error;
+	return error.message ?? "no error detail";
+}
+/**
+* Everything known about why, for the `detail` line: the failed step's name and its recorded text
+* verbatim, then the instance's own. Both, because they differ — that difference is the bug this
+* function exists because of — and `detail` is the operator's side of the boundary, where the raw
+* platform text belongs. Never the dispatched params.
+*/
+function describeFailure(failure, error) {
+	const instance = describeError(error);
+	if (failure === null) return instance;
+	return `${failure.step === void 0 ? "step" : `step '${failure.step}'`} raised${failure.code === void 0 ? "" : ` [${failure.code}]`} ${failure.raw} — instance error: ${instance}`;
+}
+//#endregion
+export { CloudflareWorkflowsClient, WorkflowInstance, WorkflowInstanceStatus };