@pithy-sh/core 0.3.0 → 0.3.1

package/dist/error/messageParams.d.ts

@@ -0,0 +1,28 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { KitErrorCode } from "./payload";
+/**
+ * The `params` a throw site **guarantees** for a kit error code — and therefore the only names a
+ * locale may write as a `{placeholder}` in that code's sentence.
+ *
+ * **Why a declaration exists at all.** `params` crosses the wire with `message` so a translating
+ * client can render its own wording for a code (CLAUDE.md §Errors), and `interpolate` leaves a
+ * placeholder nobody supplied written out as `{apiAnswer}`. So a locale writing a placeholder is
+ * making a claim about a *call site*, and a call is not a declaration — there was nothing in this
+ * repository for a catalog test to read, which is why `@pithy-sh/i18n` could only pin the absence of
+ * placeholders. This is that missing half: one table, in `core`, that both sides import.
+ *
+ * **Guaranteed means every throw, not most.** A name belongs here only when the code's throw sites
+ * pass it on **every** path, including the degraded one — a Cloudflare call that never reached
+ * Cloudflare still supplies `apiAnswer`, as the empty string. A param a throw site passes only
+ * sometimes is still useful to a client reading `payload.params` directly, and is still stripped from
+ * nothing; it simply may not be written into a sentence, because the sentence has to render on the
+ * path where it is missing.
+ *
+ * A code absent from this table guarantees nothing, which is the honest default and the state of all
+ * but one of them.
+ */
+export declare const GUARANTEED_ERROR_PARAMS: Partial<Record<KitErrorCode, readonly string[]>>;
+/** The names a locale may interpolate into `code`'s sentence. Empty when the code guarantees none. */
+export declare function guaranteedErrorParams(code: string): readonly string[];
+//# sourceMappingURL=messageParams.d.ts.map

package/dist/error/messageParams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messageParams.d.ts","sourceRoot":"","sources":["../../src/error/messageParams.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,uBAAuB,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC,CAMpF,CAAC;AAEF,sGAAsG;AACtG,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAErE"}

package/dist/error/messageParams.js

@@ -0,0 +1,31 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/error/messageParams.ts
+/**
+* The `params` a throw site **guarantees** for a kit error code — and therefore the only names a
+* locale may write as a `{placeholder}` in that code's sentence.
+*
+* **Why a declaration exists at all.** `params` crosses the wire with `message` so a translating
+* client can render its own wording for a code (CLAUDE.md §Errors), and `interpolate` leaves a
+* placeholder nobody supplied written out as `{apiAnswer}`. So a locale writing a placeholder is
+* making a claim about a *call site*, and a call is not a declaration — there was nothing in this
+* repository for a catalog test to read, which is why `@pithy-sh/i18n` could only pin the absence of
+* placeholders. This is that missing half: one table, in `core`, that both sides import.
+*
+* **Guaranteed means every throw, not most.** A name belongs here only when the code's throw sites
+* pass it on **every** path, including the degraded one — a Cloudflare call that never reached
+* Cloudflare still supplies `apiAnswer`, as the empty string. A param a throw site passes only
+* sometimes is still useful to a client reading `payload.params` directly, and is still stripped from
+* nothing; it simply may not be written into a sentence, because the sentence has to render on the
+* path where it is missing.
+*
+* A code absent from this table guarantees nothing, which is the honest default and the state of all
+* but one of them.
+*/
+const GUARANTEED_ERROR_PARAMS = { "cloudflare/request_failed": ["apiAnswer"] };
+/** The names a locale may interpolate into `code`'s sentence. Empty when the code guarantees none. */
+function guaranteedErrorParams(code) {
+	return GUARANTEED_ERROR_PARAMS[code] ?? [];
+}
+//#endregion
+export { GUARANTEED_ERROR_PARAMS, guaranteedErrorParams };

package/dist/error/terminal.d.ts

@@ -3,11 +3,22 @@
 import type { ErrorPayload } from "./payload";
 import { PublicErrorPayload } from "./payload";
 /**
- * Render an error for the terminal: the public `message` becomes the problem line and the
- * optional `action` the action line — the two-line brand-voice shape `docs/CLI.md` §3.3 specifies.
- * This unifies the CLI's error output into the one `PithyError` family: the CLI catches a
- * `PithyError`, colorizes the first line via its `style.ts`, and prints this. `detail` is internal
- * and never rendered. The same payload that encodes to HTTP renders here — one error, two surfaces.
+ * Render an error for the terminal: the public `message` on top and the optional `action` last — the
+ * brand-voice shape `docs/CLI.md` §3.3 specifies. This unifies the CLI's error output into the one
+ * `PithyError` family: the CLI catches a `PithyError`, colorizes via its `style.ts`, and prints this.
+ * `detail` is internal and never rendered. The same payload that encodes to HTTP renders here — one
+ * error, two surfaces.
+ *
+ * **`message` is one line, and the newline this adds is the only one in the rendering.** #534 tried
+ * the other way — a problem line with an upstream's `errors[]` indented beneath it, which reads
+ * beautifully in a terminal and is unencodable everywhere else. The newline is a *field separator* in
+ * two places that matter more than the indent does. `../workflow/stepMessage` uses it to carry a
+ * terminal step's remedy across a durable boundary, so a multi-line `message` raised inside a Workflow
+ * step was declined whole and the operator got the platform's prose about durable execution instead of
+ * the refusal. And here, the action line is the one line after the message, so a `message` carrying a
+ * break puts upstream text where the remedy goes — a forged action line, from text a Worker we did not
+ * write can choose. Upstream words are marked with a word (`Cloudflare said:`), never with a line: a
+ * word survives a step record, a `--json` line and a browser.
  */
 export declare function renderTerminal(payload: ErrorPayload): string;
 /** An error as an operator's machine surface states it: the wire fields, plus the remedy. */

package/dist/error/terminal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../../src/error/terminal.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAE5D;AAED,6FAA6F;AAC7F,MAAM,MAAM,aAAa,GAAG,kBAAkB,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAErE;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,aAAa,CAGlE"}
+{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../../src/error/terminal.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAE5D;AAED,6FAA6F;AAC7F,MAAM,MAAM,aAAa,GAAG,kBAAkB,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAErE;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,aAAa,CAGlE"}

package/dist/error/terminal.js

@@ -3,11 +3,22 @@
 import { PublicErrorPayload } from "./payload.js";
 //#region src/error/terminal.ts
 /**
-* Render an error for the terminal: the public `message` becomes the problem line and the
-* optional `action` the action line — the two-line brand-voice shape `docs/CLI.md` §3.3 specifies.
-* This unifies the CLI's error output into the one `PithyError` family: the CLI catches a
-* `PithyError`, colorizes the first line via its `style.ts`, and prints this. `detail` is internal
-* and never rendered. The same payload that encodes to HTTP renders here — one error, two surfaces.
+* Render an error for the terminal: the public `message` on top and the optional `action` last — the
+* brand-voice shape `docs/CLI.md` §3.3 specifies. This unifies the CLI's error output into the one
+* `PithyError` family: the CLI catches a `PithyError`, colorizes via its `style.ts`, and prints this.
+* `detail` is internal and never rendered. The same payload that encodes to HTTP renders here — one
+* error, two surfaces.
+*
+* **`message` is one line, and the newline this adds is the only one in the rendering.** #534 tried
+* the other way — a problem line with an upstream's `errors[]` indented beneath it, which reads
+* beautifully in a terminal and is unencodable everywhere else. The newline is a *field separator* in
+* two places that matter more than the indent does. `../workflow/stepMessage` uses it to carry a
+* terminal step's remedy across a durable boundary, so a multi-line `message` raised inside a Workflow
+* step was declined whole and the operator got the platform's prose about durable execution instead of
+* the refusal. And here, the action line is the one line after the message, so a `message` carrying a
+* break puts upstream text where the remedy goes — a forged action line, from text a Worker we did not
+* write can choose. Upstream words are marked with a word (`Cloudflare said:`), never with a line: a
+* word survives a step record, a `--json` line and a browser.
 */
 function renderTerminal(payload) {
 	return payload.action ? `${payload.message}\n${payload.action}` : payload.message;

package/dist/version.generated.d.ts

@@ -3,5 +3,5 @@
 /** This package's npm name — the join key against a release feed. */
 export declare const PACKAGE_NAME = "@pithy-sh/core";
 /** This package's version, stamped from its own package.json at generation time. */
-export declare const PACKAGE_VERSION = "0.3.0";
+export declare const PACKAGE_VERSION = "0.3.1";
 //# sourceMappingURL=version.generated.d.ts.map

package/dist/version.generated.js

@@ -4,6 +4,6 @@
 /** This package's npm name — the join key against a release feed. */
 const PACKAGE_NAME = "@pithy-sh/core";
 /** This package's version, stamped from its own package.json at generation time. */
-const PACKAGE_VERSION = "0.3.0";
+const PACKAGE_VERSION = "0.3.1";
 //#endregion
 export { PACKAGE_NAME, PACKAGE_VERSION };

package/dist/workflow/stepMessage.d.ts

@@ -68,6 +68,21 @@
  * `message`, throw-site context in `detail`, and a durable boundary is not a reason to move the line.
  * `action` crosses because `action` is already operator-facing — the CLI prints it and `operatorError`
  * includes it. This stops losing a field that was always meant for this reader.
+ *
+ * ## The encoder owns producing something the reader accepts
+ *
+ * The reader is strict, and it has to be: text the kit did not write must not become an operator's
+ * sentence. The consequence is that a *writer* handing it a shape it declines loses the whole channel —
+ * the code, the sentence and the remedy at once — and the operator is handed `core/workflow_failed` 500
+ * with the platform's prose about durable execution. That is not a hypothetical. #534 put an upstream's
+ * `errors[]` into a multi-line `message`, and every Cloudflare refusal raised inside a `classifiedSteps`
+ * step stopped crossing this boundary at all: the first newline read as the code/action separator and
+ * the second as a shape this never writes, so the read returned `null` and the refusal died at the step.
+ *
+ * So {@link encodeWorkflowStepMessage} is **total**: whatever fields it is handed, what it writes decodes
+ * back. Each half is flattened to one line and, past the bound, truncated with an ellipsis rather than
+ * dropped. The asymmetry with the reader is deliberate and is the whole point — the writer owns text the
+ * kit authored and may reshape it; the reader is handed text from a Worker we did not write and may not.
  */
 /**
  * The separator between the step's sentence and its action. One newline, stated once.
@@ -107,9 +122,19 @@ export declare function splitWorkflowStepCode(text: string): {
 /**
  * The text a terminal step throws. The inverse of {@link decodeWorkflowStepMessage}, and tested as one.
  *
- * An action is appended only when there is one to append and it is a single line. An action carrying a
- * break would encode a shape the reader declines, taking the sentence down with it — so the sentence
- * is kept and the action dropped. Losing the remedy is a worse day; losing both is a worse one still.
+ * **What this writes, that reads back — for a well-formed code and a sentence there is one.** Each half
+ * goes through {@link encodable}, so a multi-line sentence is flattened rather than fatal and an overlong
+ * one is truncated rather than declined. An action is appended only when there is one left after that —
+ * a remedy that was empty or only whitespace leaves no trailing separator, because a dangling separator
+ * is a field the reader would have to decline.
+ *
+ * **Two inputs it deliberately cannot represent, so "total" is not the whole word for it.** An empty
+ * `message` encodes to text {@link decodeWorkflowStepMessage} declines, and so does a `code` that does
+ * not match `CODE_PREFIX`. Both refusals are the boundary working: a step that failed without a sentence
+ * has none to promote — the caller's own `fallbackMessage` is what the operator should see — and a code
+ * the reader cannot recognize is exactly the foreign text this encoding exists to keep out of an
+ * operator's sentence. Neither is reachable from a kit throw site; an adopter code declared through
+ * `defineErrorPayload` is checked against the same shape.
  */
 export declare function encodeWorkflowStepMessage(fields: WorkflowStepMessage): string;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"stepMessage.d.ts","sourceRoot":"","sources":["../../src/workflow/stepMessage.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAc1C,uGAAuG;AACvG,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAInF;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAK7E;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAYlF"}
+{"version":3,"file":"stepMessage.d.ts","sourceRoot":"","sources":["../../src/workflow/stepMessage.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAc1C,uGAAuG;AACvG,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAInF;AAuBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAK7E;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAYlF"}

package/dist/workflow/stepMessage.js

@@ -69,6 +69,21 @@
 * `message`, throw-site context in `detail`, and a durable boundary is not a reason to move the line.
 * `action` crosses because `action` is already operator-facing — the CLI prints it and `operatorError`
 * includes it. This stops losing a field that was always meant for this reader.
+*
+* ## The encoder owns producing something the reader accepts
+*
+* The reader is strict, and it has to be: text the kit did not write must not become an operator's
+* sentence. The consequence is that a *writer* handing it a shape it declines loses the whole channel —
+* the code, the sentence and the remedy at once — and the operator is handed `core/workflow_failed` 500
+* with the platform's prose about durable execution. That is not a hypothetical. #534 put an upstream's
+* `errors[]` into a multi-line `message`, and every Cloudflare refusal raised inside a `classifiedSteps`
+* step stopped crossing this boundary at all: the first newline read as the code/action separator and
+* the second as a shape this never writes, so the read returned `null` and the refusal died at the step.
+*
+* So {@link encodeWorkflowStepMessage} is **total**: whatever fields it is handed, what it writes decodes
+* back. Each half is flattened to one line and, past the bound, truncated with an ellipsis rather than
+* dropped. The asymmetry with the reader is deliberate and is the whole point — the writer owns text the
+* kit authored and may reshape it; the reader is handed text from a Worker we did not write and may not.
 */
 /**
 * The separator between the step's sentence and its action. One newline, stated once.
@@ -111,16 +126,43 @@ function splitWorkflowStepCode(text) {
 	};
 }
 /**
+* One half as this encoding can carry it: a single line, within the bound.
+*
+* Both reshapes exist because the alternative is losing the field, and the two ways a half can be
+* unreadable are the two ways a writer actually gets it wrong. A line break would encode a shape the
+* reader declines — the sentence would take the remedy down with it, or the remedy would forge a
+* second field — so every break collapses to a space, exactly as `@pithy-sh/cloudflare` flattens an
+* upstream's own text before it lands in `message`. Length is the same argument with a different
+* cause: half a sentence naming its code and its remedy beats the platform's prose about durable
+* execution, so the tail is spent rather than the field. The whole of it was never here anyway —
+* `detail` holds the raw text, on the far side of a boundary it does not cross.
+*/
+function encodable(text) {
+	const flattened = text.replace(/\s*[\n\r]+\s*/g, " ").trim();
+	if (flattened.length <= 512) return flattened;
+	return `${flattened.slice(0, 511).trimEnd()}…`;
+}
+/**
 * The text a terminal step throws. The inverse of {@link decodeWorkflowStepMessage}, and tested as one.
 *
-* An action is appended only when there is one to append and it is a single line. An action carrying a
-* break would encode a shape the reader declines, taking the sentence down with it — so the sentence
-* is kept and the action dropped. Losing the remedy is a worse day; losing both is a worse one still.
+* **What this writes, that reads back — for a well-formed code and a sentence there is one.** Each half
+* goes through {@link encodable}, so a multi-line sentence is flattened rather than fatal and an overlong
+* one is truncated rather than declined. An action is appended only when there is one left after that —
+* a remedy that was empty or only whitespace leaves no trailing separator, because a dangling separator
+* is a field the reader would have to decline.
+*
+* **Two inputs it deliberately cannot represent, so "total" is not the whole word for it.** An empty
+* `message` encodes to text {@link decodeWorkflowStepMessage} declines, and so does a `code` that does
+* not match `CODE_PREFIX`. Both refusals are the boundary working: a step that failed without a sentence
+* has none to promote — the caller's own `fallbackMessage` is what the operator should see — and a code
+* the reader cannot recognize is exactly the foreign text this encoding exists to keep out of an
+* operator's sentence. Neither is reachable from a kit throw site; an adopter code declared through
+* `defineErrorPayload` is checked against the same shape.
 */
 function encodeWorkflowStepMessage(fields) {
-	const stated = `${fields.code}: ${fields.message}`;
-	const action = fields.action?.trim();
-	if (action === void 0 || action === "" || LINE_BREAK.test(action)) return stated;
+	const stated = `${fields.code}: ${encodable(fields.message)}`;
+	const action = encodable(fields.action ?? "");
+	if (action === "") return stated;
 	return `${stated}
 ${action}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pithy-sh/core",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/error/messageParams.ts

@@ -0,0 +1,38 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { KitErrorCode } from "./payload";
+
+/**
+ * The `params` a throw site **guarantees** for a kit error code — and therefore the only names a
+ * locale may write as a `{placeholder}` in that code's sentence.
+ *
+ * **Why a declaration exists at all.** `params` crosses the wire with `message` so a translating
+ * client can render its own wording for a code (CLAUDE.md §Errors), and `interpolate` leaves a
+ * placeholder nobody supplied written out as `{apiAnswer}`. So a locale writing a placeholder is
+ * making a claim about a *call site*, and a call is not a declaration — there was nothing in this
+ * repository for a catalog test to read, which is why `@pithy-sh/i18n` could only pin the absence of
+ * placeholders. This is that missing half: one table, in `core`, that both sides import.
+ *
+ * **Guaranteed means every throw, not most.** A name belongs here only when the code's throw sites
+ * pass it on **every** path, including the degraded one — a Cloudflare call that never reached
+ * Cloudflare still supplies `apiAnswer`, as the empty string. A param a throw site passes only
+ * sometimes is still useful to a client reading `payload.params` directly, and is still stripped from
+ * nothing; it simply may not be written into a sentence, because the sentence has to render on the
+ * path where it is missing.
+ *
+ * A code absent from this table guarantees nothing, which is the honest default and the state of all
+ * but one of them.
+ */
+export const GUARANTEED_ERROR_PARAMS: Partial<Record<KitErrorCode, readonly string[]>> = {
+  // `@pithy-sh/cloudflare`'s `cloudflareRefusal` composes every Cloudflare refusal and always passes
+  // `apiAnswer`: Cloudflare's own code and sentence, punctuated to append (`": 10000 Authentication
+  // error"`), or `""` when the call failed without an answer. The value carries its own separator so
+  // one sentence renders correctly both ways — a locale cannot write an `if`.
+  "cloudflare/request_failed": ["apiAnswer"],
+};
+
+/** The names a locale may interpolate into `code`'s sentence. Empty when the code guarantees none. */
+export function guaranteedErrorParams(code: string): readonly string[] {
+  return GUARANTEED_ERROR_PARAMS[code as KitErrorCode] ?? [];
+}

package/src/error/terminal.ts

@@ -5,11 +5,22 @@ import type { ErrorPayload } from "./payload";
 import { PublicErrorPayload } from "./payload";
 
 /**
- * Render an error for the terminal: the public `message` becomes the problem line and the
- * optional `action` the action line — the two-line brand-voice shape `docs/CLI.md` §3.3 specifies.
- * This unifies the CLI's error output into the one `PithyError` family: the CLI catches a
- * `PithyError`, colorizes the first line via its `style.ts`, and prints this. `detail` is internal
- * and never rendered. The same payload that encodes to HTTP renders here — one error, two surfaces.
+ * Render an error for the terminal: the public `message` on top and the optional `action` last — the
+ * brand-voice shape `docs/CLI.md` §3.3 specifies. This unifies the CLI's error output into the one
+ * `PithyError` family: the CLI catches a `PithyError`, colorizes via its `style.ts`, and prints this.
+ * `detail` is internal and never rendered. The same payload that encodes to HTTP renders here — one
+ * error, two surfaces.
+ *
+ * **`message` is one line, and the newline this adds is the only one in the rendering.** #534 tried
+ * the other way — a problem line with an upstream's `errors[]` indented beneath it, which reads
+ * beautifully in a terminal and is unencodable everywhere else. The newline is a *field separator* in
+ * two places that matter more than the indent does. `../workflow/stepMessage` uses it to carry a
+ * terminal step's remedy across a durable boundary, so a multi-line `message` raised inside a Workflow
+ * step was declined whole and the operator got the platform's prose about durable execution instead of
+ * the refusal. And here, the action line is the one line after the message, so a `message` carrying a
+ * break puts upstream text where the remedy goes — a forged action line, from text a Worker we did not
+ * write can choose. Upstream words are marked with a word (`Cloudflare said:`), never with a line: a
+ * word survives a step record, a `--json` line and a browser.
  */
 export function renderTerminal(payload: ErrorPayload): string {
   return payload.action ? `${payload.message}\n${payload.action}` : payload.message;

package/src/version.generated.ts

@@ -13,4 +13,4 @@
 export const PACKAGE_NAME = "@pithy-sh/core";
 
 /** This package's version, stamped from its own package.json at generation time. */
-export const PACKAGE_VERSION = "0.3.0";
+export const PACKAGE_VERSION = "0.3.1";

package/src/workflow/stepMessage.ts

@@ -69,6 +69,21 @@
  * `message`, throw-site context in `detail`, and a durable boundary is not a reason to move the line.
  * `action` crosses because `action` is already operator-facing — the CLI prints it and `operatorError`
  * includes it. This stops losing a field that was always meant for this reader.
+ *
+ * ## The encoder owns producing something the reader accepts
+ *
+ * The reader is strict, and it has to be: text the kit did not write must not become an operator's
+ * sentence. The consequence is that a *writer* handing it a shape it declines loses the whole channel —
+ * the code, the sentence and the remedy at once — and the operator is handed `core/workflow_failed` 500
+ * with the platform's prose about durable execution. That is not a hypothetical. #534 put an upstream's
+ * `errors[]` into a multi-line `message`, and every Cloudflare refusal raised inside a `classifiedSteps`
+ * step stopped crossing this boundary at all: the first newline read as the code/action separator and
+ * the second as a shape this never writes, so the read returned `null` and the refusal died at the step.
+ *
+ * So {@link encodeWorkflowStepMessage} is **total**: whatever fields it is handed, what it writes decodes
+ * back. Each half is flattened to one line and, past the bound, truncated with an ellipsis rather than
+ * dropped. The asymmetry with the reader is deliberate and is the whole point — the writer owns text the
+ * kit authored and may reshape it; the reader is handed text from a Worker we did not write and may not.
  */
 
 /**
@@ -123,17 +138,48 @@ export function splitWorkflowStepCode(text: string): { code?: string; rest: stri
   return { code: matched[1], rest: text.slice(matched[0].length) };
 }
 
+/**
+ * One half as this encoding can carry it: a single line, within the bound.
+ *
+ * Both reshapes exist because the alternative is losing the field, and the two ways a half can be
+ * unreadable are the two ways a writer actually gets it wrong. A line break would encode a shape the
+ * reader declines — the sentence would take the remedy down with it, or the remedy would forge a
+ * second field — so every break collapses to a space, exactly as `@pithy-sh/cloudflare` flattens an
+ * upstream's own text before it lands in `message`. Length is the same argument with a different
+ * cause: half a sentence naming its code and its remedy beats the platform's prose about durable
+ * execution, so the tail is spent rather than the field. The whole of it was never here anyway —
+ * `detail` holds the raw text, on the far side of a boundary it does not cross.
+ */
+function encodable(text: string): string {
+  // The break and the whitespace that dressed it: an indent under a line is structure, and structure
+  // that survives as run-on spaces reads as a typo. Whitespace elsewhere in the half is left alone —
+  // this reshapes what the line break did, not what the sentence says.
+  const flattened = text.replace(/\s*[\n\r]+\s*/g, " ").trim();
+  if (flattened.length <= MAX_WORKFLOW_STEP_TEXT) return flattened;
+  return `${flattened.slice(0, MAX_WORKFLOW_STEP_TEXT - 1).trimEnd()}…`;
+}
+
 /**
  * The text a terminal step throws. The inverse of {@link decodeWorkflowStepMessage}, and tested as one.
  *
- * An action is appended only when there is one to append and it is a single line. An action carrying a
- * break would encode a shape the reader declines, taking the sentence down with it — so the sentence
- * is kept and the action dropped. Losing the remedy is a worse day; losing both is a worse one still.
+ * **What this writes, that reads back — for a well-formed code and a sentence there is one.** Each half
+ * goes through {@link encodable}, so a multi-line sentence is flattened rather than fatal and an overlong
+ * one is truncated rather than declined. An action is appended only when there is one left after that —
+ * a remedy that was empty or only whitespace leaves no trailing separator, because a dangling separator
+ * is a field the reader would have to decline.
+ *
+ * **Two inputs it deliberately cannot represent, so "total" is not the whole word for it.** An empty
+ * `message` encodes to text {@link decodeWorkflowStepMessage} declines, and so does a `code` that does
+ * not match `CODE_PREFIX`. Both refusals are the boundary working: a step that failed without a sentence
+ * has none to promote — the caller's own `fallbackMessage` is what the operator should see — and a code
+ * the reader cannot recognize is exactly the foreign text this encoding exists to keep out of an
+ * operator's sentence. Neither is reachable from a kit throw site; an adopter code declared through
+ * `defineErrorPayload` is checked against the same shape.
  */
 export function encodeWorkflowStepMessage(fields: WorkflowStepMessage): string {
-  const stated = `${fields.code}: ${fields.message}`;
-  const action = fields.action?.trim();
-  if (action === undefined || action === "" || LINE_BREAK.test(action)) return stated;
+  const stated = `${fields.code}: ${encodable(fields.message)}`;
+  const action = encodable(fields.action ?? "");
+  if (action === "") return stated;
   return `${stated}${WORKFLOW_STEP_SEPARATOR}${action}`;
 }