@pithy-sh/core 0.1.2 → 0.1.4

package/dist/error/cause.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Reading a thrown value that no type describes — the one place the kit records **what a runtime does to
+ * an error on its way out** (#223), and **the one place that decides whether what it says may be shown**
+ * (#228).
+ *
+ * Nothing here classifies anything. Classification is policy and belongs to the surface that refuses:
+ * which causes a loader recognizes, and what each refusal says, differ per surface and are meant to.
+ * This module holds only what does not — the facts about the shapes a runtime hands over, and the filter
+ * that decides whether one of its strings is safe to put in front of an adopter.
+ *
+ * **The filter is here for the same reason the facts are, and the argument took two issues to finish.**
+ * #223 moved `rootCause`, `prop` and `isBuildFailureWrapper` in and deliberately left `safeReason` beside
+ * the three refusals, on the reading that what a surface may say is that surface's business. That is true
+ * of the sentences and false of the filter: whether a string carries a path, a stack frame or half a
+ * parser's ANSI box is a property of the string, and the answer cannot differ between the CLI, a
+ * capability loader and the vite plugin without one of them being wrong. It was three near-verbatim
+ * copies, and the hole #223 found in it had to be closed three times (#228).
+ *
+ * `@pithy-sh/vite` depends on this package and on nothing else in the kit. That constraint is what made
+ * core the right home for `rootCause`; it applies to the filter identically.
+ */
+/**
+ * Read a property off an unknown throwable without widening anything to `any`.
+ *
+ * Deliberately duck-typed. Bun's `ResolveMessage` and `BuildMessage` — the two shapes the CLI's `bin` and
+ * the vite plugin actually catch, since both run on Bun — are their own classes and are **not**
+ * `instanceof Error`. An `instanceof` gate here passes a whole suite under vitest, which runs on Node,
+ * and silently drops the parser's own sentence on the runtime that ships. That is #207, and it is why
+ * every reader of a cause in this kit goes through this function.
+ *
+ * Non-enumerable properties are read too — `AggregateError.errors` is one, and {@link rootCause}
+ * depends on it.
+ */
+export declare function prop(cause: unknown, key: string): unknown;
+/**
+ * The diagnostic **inside** Bun's `AggregateError` wrapper — the thing a classifier must actually look at.
+ *
+ * `import()` on Bun hands one build diagnostic over bare and **two or more inside an `AggregateError`**,
+ * whose own `message` is `N errors building "<absolute path>"` and whose `Object.keys` is empty. Node
+ * throws the diagnostic directly, so no Node-shaped fixture can show this: it is found by running on Bun,
+ * and only by running on Bun with a failure of the *realistic* shape.
+ *
+ * **And the realistic shape is the wrapped one.** A stray brace cascades — one missing `}` in a
+ * `pithy.config.ts` produced four diagnostics on Bun 1.3.14 — so a syntax error arrives wrapped far more
+ * often than bare. Classified as-is, the wrapper matches nothing: not a resolution failure, not a parse
+ * error, just something with a message. The refusal then says *the config threw while loading, run the
+ * file directly* while holding the line and column in its hand. #207 fixed the bare case and left this
+ * one; #217 hit it in the capability loaders; #223 is it a third time, which is why it lives here.
+ *
+ * The **first** diagnostic only. The rest are the cascade, not the fault, and naming four positions
+ * buries the one that matters.
+ *
+ * Bounded to four levels: a wrapper holding a wrapper is not a shape any runtime produces today, and an
+ * unbounded walk over an adopter's own `errors` field is not something this should be talked into.
+ * Anything else — a bare diagnostic, an empty `errors`, a non-array `errors` — is returned untouched, so
+ * a runtime that stops wrapping needs no change here.
+ */
+export declare function rootCause(cause: unknown): unknown;
+/**
+ * The wrapper **after the diagnostics are gone** — a build that failed, and that is all that is left.
+ *
+ * {@link rootCause} handles the first `import()`. It cannot handle the second: Bun caches a failed module
+ * and re-throws an `AggregateError` with **no `errors` at all**, just the count and the path. There is
+ * nothing to unwrap, so a classifier that only unwraps reads a syntax error as "it threw" from the second
+ * caller onward — which is what `pithy doctor` shows an adopter, because resolving the project's account
+ * loads the root config before the report does (#206, #223).
+ *
+ * Nothing else Bun throws degrades this way: a `ResolveMessage`, a bare `BuildMessage` and a module's own
+ * `Error` are byte-identical on every import. Only the wrapper forgets.
+ *
+ * So the wrapper is recognized by its own message. **What it proves is narrow and worth stating:** the
+ * module reached the builder and the builder produced diagnostics. It did not fail to resolve — Bun
+ * throws the first `ResolveMessage` bare, wrapping nothing, even for a file with several bad imports —
+ * and it did not run, so it cannot have thrown. It failed to parse or to build. A caller may say that
+ * much and no more: the message itself carries an absolute path and a count, neither of which is the
+ * adopter's business, so it is a *predicate* here rather than a string anyone is tempted to print.
+ */
+export declare function isBuildFailureWrapper(cause: unknown): boolean;
+/**
+ * The thrown value's message, **de-colored** — `undefined` when it has none.
+ *
+ * Duck-typed for {@link prop}'s reason. The de-coloring is here rather than at each caller because an
+ * escape sequence is formatting the runtime added, not something a surface has an opinion about — and
+ * because the three copies of this had already drifted: two stripped with `\u001b`, the third with a
+ * literal escape character sitting in its source where no reviewer would see it (#228).
+ *
+ * This says what the cause *says*. Whether any of it may be shown is {@link safeReason}.
+ */
+export declare function causeMessage(cause: unknown): string | undefined;
+/**
+ * The cause's own message, but **only when the whole of it is one safe sentence** — the kit's single
+ * decision about whether a runtime's string may reach an adopter (#228).
+ *
+ * A parser's reason (`Expected identifier but found "{"`) is a sentence an adopter acts on. The
+ * diagnostic a bundler wraps the same fault in is a multi-line ANSI box quoting an absolute path and the
+ * source line, which is throw-site context wearing a message's clothes. What is dropped here still
+ * reaches `detail`, which the CLI renderer never prints and the HTTP codec strips — so a refusal costs a
+ * developer one frame of digging, and a mistake puts a path, a source line or a stack frame in a field
+ * that is rendered.
+ *
+ * **Provenance first, then content.** Bun's build-failure wrapper is refused outright, before a single
+ * content test runs. The content tests exist for a diagnostic that *might* be safe; the wrapper never is,
+ * because its whole message is a count nobody asked for and a path that must not travel. Leaving it to
+ * the content tests is what leaked: `2 errors building "app/config:12:5.ts"` has no leading slash, sailed
+ * through the absolute-path check, and produced *The config does not parse: 2 errors building
+ * "app/config:12:5.ts". Line 12, column 5.* — a path the adopter never wrote, and a position fabricated
+ * out of a file name (#223). That suppression was written three times because the filter was. It is
+ * written once here, and {@link failurePosition} refuses the same shape for the same reason.
+ *
+ * A trailing period comes off: every caller puts this inside a sentence of its own.
+ */
+export declare function safeReason(cause: unknown): string | undefined;
+/** Where a runtime says a failure was. Two numbers, and never the file they were quoted beside. */
+export interface FailurePosition {
+    /** 1-based line, as the runtime reported it. */
+    line: number;
+    /** Column, as the runtime reported it. */
+    column: number;
+}
+/**
+ * `line`/`column`, from the structured position where a runtime gives one, else from its own `…:LINE:COL`.
+ *
+ * A recorded fact about two runtimes: Bun's `BuildMessage` carries `position`, and a transform that has no
+ * such field states the same thing in its message tail. Only the two numbers are lifted out — never the
+ * path they are appended to. Whether a surface prints them is that surface's policy: two of the three
+ * classifiers do, and the capability loader deliberately does not.
+ *
+ * Refuses Bun's build-failure wrapper on provenance, exactly as {@link safeReason} does. That message
+ * holds a file name and a count and nothing about where anything failed, so a `:12:5` found in it is a
+ * coincidence of the path's own characters — and a fabricated position reads as authoritative.
+ */
+export declare function failurePosition(cause: unknown): FailurePosition | undefined;
+/**
+ * The specifier that did not resolve.
+ *
+ * A recorded fact about two runtimes: Bun's `ResolveMessage` carries it as a **field**, and Node states it
+ * in prose. The field is preferred wherever there is one, because the prose around it names the referrer's
+ * absolute path — the specifier is the adopter's own import, the referrer is our frame.
+ *
+ * Whether a surface names it, and what it advises when it does, is that surface's policy and stays there.
+ */
+export declare function unresolvedSpecifier(cause: unknown): string | undefined;
+//# sourceMappingURL=cause.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cause.d.ts","sourceRoot":"","sources":["../../src/error/cause.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAGzD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAQjD;AAKD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAG7D;AAeD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAG/D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAQ7D;AAED,mGAAmG;AACnG,MAAM,WAAW,eAAe;IAC9B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,GAAG,SAAS,CAS3E;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAKtE"}

package/dist/error/cause.js

@@ -0,0 +1,192 @@
+//#region src/error/cause.ts
+/**
+* Reading a thrown value that no type describes — the one place the kit records **what a runtime does to
+* an error on its way out** (#223), and **the one place that decides whether what it says may be shown**
+* (#228).
+*
+* Nothing here classifies anything. Classification is policy and belongs to the surface that refuses:
+* which causes a loader recognizes, and what each refusal says, differ per surface and are meant to.
+* This module holds only what does not — the facts about the shapes a runtime hands over, and the filter
+* that decides whether one of its strings is safe to put in front of an adopter.
+*
+* **The filter is here for the same reason the facts are, and the argument took two issues to finish.**
+* #223 moved `rootCause`, `prop` and `isBuildFailureWrapper` in and deliberately left `safeReason` beside
+* the three refusals, on the reading that what a surface may say is that surface's business. That is true
+* of the sentences and false of the filter: whether a string carries a path, a stack frame or half a
+* parser's ANSI box is a property of the string, and the answer cannot differ between the CLI, a
+* capability loader and the vite plugin without one of them being wrong. It was three near-verbatim
+* copies, and the hole #223 found in it had to be closed three times (#228).
+*
+* `@pithy-sh/vite` depends on this package and on nothing else in the kit. That constraint is what made
+* core the right home for `rootCause`; it applies to the filter identically.
+*/
+/**
+* Read a property off an unknown throwable without widening anything to `any`.
+*
+* Deliberately duck-typed. Bun's `ResolveMessage` and `BuildMessage` — the two shapes the CLI's `bin` and
+* the vite plugin actually catch, since both run on Bun — are their own classes and are **not**
+* `instanceof Error`. An `instanceof` gate here passes a whole suite under vitest, which runs on Node,
+* and silently drops the parser's own sentence on the runtime that ships. That is #207, and it is why
+* every reader of a cause in this kit goes through this function.
+*
+* Non-enumerable properties are read too — `AggregateError.errors` is one, and {@link rootCause}
+* depends on it.
+*/
+function prop(cause, key) {
+	if (typeof cause !== "object" || cause === null) return void 0;
+	return cause[key];
+}
+/**
+* The diagnostic **inside** Bun's `AggregateError` wrapper — the thing a classifier must actually look at.
+*
+* `import()` on Bun hands one build diagnostic over bare and **two or more inside an `AggregateError`**,
+* whose own `message` is `N errors building "<absolute path>"` and whose `Object.keys` is empty. Node
+* throws the diagnostic directly, so no Node-shaped fixture can show this: it is found by running on Bun,
+* and only by running on Bun with a failure of the *realistic* shape.
+*
+* **And the realistic shape is the wrapped one.** A stray brace cascades — one missing `}` in a
+* `pithy.config.ts` produced four diagnostics on Bun 1.3.14 — so a syntax error arrives wrapped far more
+* often than bare. Classified as-is, the wrapper matches nothing: not a resolution failure, not a parse
+* error, just something with a message. The refusal then says *the config threw while loading, run the
+* file directly* while holding the line and column in its hand. #207 fixed the bare case and left this
+* one; #217 hit it in the capability loaders; #223 is it a third time, which is why it lives here.
+*
+* The **first** diagnostic only. The rest are the cascade, not the fault, and naming four positions
+* buries the one that matters.
+*
+* Bounded to four levels: a wrapper holding a wrapper is not a shape any runtime produces today, and an
+* unbounded walk over an adopter's own `errors` field is not something this should be talked into.
+* Anything else — a bare diagnostic, an empty `errors`, a non-array `errors` — is returned untouched, so
+* a runtime that stops wrapping needs no change here.
+*/
+function rootCause(cause) {
+	let current = cause;
+	for (let depth = 0; depth < 4; depth += 1) {
+		const errors = prop(current, "errors");
+		if (!Array.isArray(errors) || errors.length === 0 || errors[0] === void 0) return current;
+		current = errors[0];
+	}
+	return current;
+}
+/** Bun's wrapper announces itself: `4 errors building "<absolute path>"`, and nothing else says that. */
+const BUILD_FAILURE = /^\d+ errors? building "/;
+/**
+* The wrapper **after the diagnostics are gone** — a build that failed, and that is all that is left.
+*
+* {@link rootCause} handles the first `import()`. It cannot handle the second: Bun caches a failed module
+* and re-throws an `AggregateError` with **no `errors` at all**, just the count and the path. There is
+* nothing to unwrap, so a classifier that only unwraps reads a syntax error as "it threw" from the second
+* caller onward — which is what `pithy doctor` shows an adopter, because resolving the project's account
+* loads the root config before the report does (#206, #223).
+*
+* Nothing else Bun throws degrades this way: a `ResolveMessage`, a bare `BuildMessage` and a module's own
+* `Error` are byte-identical on every import. Only the wrapper forgets.
+*
+* So the wrapper is recognized by its own message. **What it proves is narrow and worth stating:** the
+* module reached the builder and the builder produced diagnostics. It did not fail to resolve — Bun
+* throws the first `ResolveMessage` bare, wrapping nothing, even for a file with several bad imports —
+* and it did not run, so it cannot have thrown. It failed to parse or to build. A caller may say that
+* much and no more: the message itself carries an absolute path and a count, neither of which is the
+* adopter's business, so it is a *predicate* here rather than a string anyone is tempted to print.
+*/
+function isBuildFailureWrapper(cause) {
+	const message = prop(cause, "message");
+	return typeof message === "string" && BUILD_FAILURE.test(message);
+}
+/** Escape sequences a runtime colors its diagnostics with. They are formatting, and they never travel. */
+const ANSI = /\u001b\[[0-9;]*m/g;
+/** Anything that looks like the start of an absolute path — POSIX, `~`, or a Windows drive. */
+const ABSOLUTE_PATH = /(^|[\s'"(])(\/|~\/|[A-Za-z]:[\\/])/;
+/** A stack frame, in the one spelling every runtime here agrees on. */
+const STACK_FRAME = /\bat \S+:\d+:\d+/;
+/** The longest a reason may be before it has stopped being a sentence and started being a diagnostic. */
+const REASON_LIMIT = 160;
+/**
+* The thrown value's message, **de-colored** — `undefined` when it has none.
+*
+* Duck-typed for {@link prop}'s reason. The de-coloring is here rather than at each caller because an
+* escape sequence is formatting the runtime added, not something a surface has an opinion about — and
+* because the three copies of this had already drifted: two stripped with `\u001b`, the third with a
+* literal escape character sitting in its source where no reviewer would see it (#228).
+*
+* This says what the cause *says*. Whether any of it may be shown is {@link safeReason}.
+*/
+function causeMessage(cause) {
+	const message = prop(cause, "message");
+	return typeof message === "string" ? message.replace(ANSI, "") : void 0;
+}
+/**
+* The cause's own message, but **only when the whole of it is one safe sentence** — the kit's single
+* decision about whether a runtime's string may reach an adopter (#228).
+*
+* A parser's reason (`Expected identifier but found "{"`) is a sentence an adopter acts on. The
+* diagnostic a bundler wraps the same fault in is a multi-line ANSI box quoting an absolute path and the
+* source line, which is throw-site context wearing a message's clothes. What is dropped here still
+* reaches `detail`, which the CLI renderer never prints and the HTTP codec strips — so a refusal costs a
+* developer one frame of digging, and a mistake puts a path, a source line or a stack frame in a field
+* that is rendered.
+*
+* **Provenance first, then content.** Bun's build-failure wrapper is refused outright, before a single
+* content test runs. The content tests exist for a diagnostic that *might* be safe; the wrapper never is,
+* because its whole message is a count nobody asked for and a path that must not travel. Leaving it to
+* the content tests is what leaked: `2 errors building "app/config:12:5.ts"` has no leading slash, sailed
+* through the absolute-path check, and produced *The config does not parse: 2 errors building
+* "app/config:12:5.ts". Line 12, column 5.* — a path the adopter never wrote, and a position fabricated
+* out of a file name (#223). That suppression was written three times because the filter was. It is
+* written once here, and {@link failurePosition} refuses the same shape for the same reason.
+*
+* A trailing period comes off: every caller puts this inside a sentence of its own.
+*/
+function safeReason(cause) {
+	if (isBuildFailureWrapper(cause)) return void 0;
+	const text = (causeMessage(cause) ?? "").trim();
+	if (text.length === 0 || text.length > REASON_LIMIT) return void 0;
+	if (text.includes("\n")) return void 0;
+	if (ABSOLUTE_PATH.test(text)) return void 0;
+	if (STACK_FRAME.test(text)) return void 0;
+	return text.replace(/\.$/, "");
+}
+/**
+* `line`/`column`, from the structured position where a runtime gives one, else from its own `…:LINE:COL`.
+*
+* A recorded fact about two runtimes: Bun's `BuildMessage` carries `position`, and a transform that has no
+* such field states the same thing in its message tail. Only the two numbers are lifted out — never the
+* path they are appended to. Whether a surface prints them is that surface's policy: two of the three
+* classifiers do, and the capability loader deliberately does not.
+*
+* Refuses Bun's build-failure wrapper on provenance, exactly as {@link safeReason} does. That message
+* holds a file name and a count and nothing about where anything failed, so a `:12:5` found in it is a
+* coincidence of the path's own characters — and a fabricated position reads as authoritative.
+*/
+function failurePosition(cause) {
+	if (isBuildFailureWrapper(cause)) return void 0;
+	const position = prop(cause, "position");
+	const line = prop(position, "line");
+	const column = prop(position, "column");
+	if (typeof line === "number" && line > 0 && typeof column === "number") return {
+		line,
+		column
+	};
+	const match = /:(\d+):(\d+)/.exec(causeMessage(cause) ?? "");
+	if (!match?.[1] || !match[2]) return void 0;
+	return {
+		line: Number(match[1]),
+		column: Number(match[2])
+	};
+}
+/**
+* The specifier that did not resolve.
+*
+* A recorded fact about two runtimes: Bun's `ResolveMessage` carries it as a **field**, and Node states it
+* in prose. The field is preferred wherever there is one, because the prose around it names the referrer's
+* absolute path — the specifier is the adopter's own import, the referrer is our frame.
+*
+* Whether a surface names it, and what it advises when it does, is that surface's policy and stays there.
+*/
+function unresolvedSpecifier(cause) {
+	const field = prop(cause, "specifier");
+	if (typeof field === "string" && field.length > 0) return field;
+	return /Cannot find (?:package|module) ['"]([^'"]+)['"]/.exec(causeMessage(cause) ?? "")?.[1];
+}
+//#endregion
+export { causeMessage, failurePosition, isBuildFailureWrapper, prop, rootCause, safeReason, unresolvedSpecifier };

package/dist/error/client.d.ts

@@ -0,0 +1,35 @@
+import type { z } from "zod";
+import type { ErrorPayload } from "./payload";
+import { PublicErrorPayload } from "./payload";
+/**
+ * **The one place an error becomes bytes for a client.** Whatever the transport.
+ *
+ * An error leaves this process by more than one road. A JSON response is the busiest, and it had the
+ * boundary written into it — but a Durable Object also pushes error frames down a WebSocket, and a
+ * transport that grew its own projection grew its own idea of what a client may read. That is how
+ * `action` reached a browser after the schema had already classified it: not because anyone disagreed
+ * with the rule, but because the rule lived inside the HTTP codec, and a socket is not HTTP.
+ *
+ * So the rule sits here, above every transport, and each transport calls it:
+ *
+ * - `HttpError.encode` (./http) — the JSON body of a response.
+ * - The multiplayer session Durable Object — the `error` frame on a player's socket.
+ * - Anything added next. An SSE `event:`, a queue consumer echoing a failure, a Workflow surfacing one.
+ *   None of them needs to know *what* is stripped; they need to know they must come through here.
+ *
+ * What it strips, and why that is not a list to maintain: `action` and `detail` are removed by name,
+ * and the result is then parsed by `PublicErrorPayload`, which has neither key. The parse is what makes
+ * the boundary hold for an **adopter's** code as well as the kit's — it is a property of the schema, so
+ * a field classified as operator-facing tomorrow is stripped here without this function changing.
+ *
+ * The mirror is {@link operatorError} in ./terminal, which keeps `action` because whoever ran the
+ * command is the person who can act on "Bind a D1 database named DB in wrangler.jsonc". Two audiences,
+ * two functions, and neither one is a transport.
+ *
+ * It takes the **input** side of `ErrorPayload` rather than the output side, which is the wider of the
+ * two: an adopter's code carries a brand once parsed, and a codec's encode side is handed the shape
+ * before that brand exists. A `PithyError`'s own payload satisfies it either way, and the brand is not
+ * something this function needs — it parses what it is given.
+ */
+export declare function clientError(payload: z.input<typeof ErrorPayload>): PublicErrorPayload;
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/error/client.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,GAAG,kBAAkB,CAKrF"}

package/dist/error/client.js

@@ -0,0 +1,38 @@
+import { PublicErrorPayload } from "./payload.js";
+//#region src/error/client.ts
+/**
+* **The one place an error becomes bytes for a client.** Whatever the transport.
+*
+* An error leaves this process by more than one road. A JSON response is the busiest, and it had the
+* boundary written into it — but a Durable Object also pushes error frames down a WebSocket, and a
+* transport that grew its own projection grew its own idea of what a client may read. That is how
+* `action` reached a browser after the schema had already classified it: not because anyone disagreed
+* with the rule, but because the rule lived inside the HTTP codec, and a socket is not HTTP.
+*
+* So the rule sits here, above every transport, and each transport calls it:
+*
+* - `HttpError.encode` (./http) — the JSON body of a response.
+* - The multiplayer session Durable Object — the `error` frame on a player's socket.
+* - Anything added next. An SSE `event:`, a queue consumer echoing a failure, a Workflow surfacing one.
+*   None of them needs to know *what* is stripped; they need to know they must come through here.
+*
+* What it strips, and why that is not a list to maintain: `action` and `detail` are removed by name,
+* and the result is then parsed by `PublicErrorPayload`, which has neither key. The parse is what makes
+* the boundary hold for an **adopter's** code as well as the kit's — it is a property of the schema, so
+* a field classified as operator-facing tomorrow is stripped here without this function changing.
+*
+* The mirror is {@link operatorError} in ./terminal, which keeps `action` because whoever ran the
+* command is the person who can act on "Bind a D1 database named DB in wrangler.jsonc". Two audiences,
+* two functions, and neither one is a transport.
+*
+* It takes the **input** side of `ErrorPayload` rather than the output side, which is the wider of the
+* two: an adopter's code carries a brand once parsed, and a codec's encode side is handed the shape
+* before that brand exists. A `PithyError`'s own payload satisfies it either way, and the brand is not
+* something this function needs — it parses what it is given.
+*/
+function clientError(payload) {
+	const { action: _action, detail: _detail, ...wire } = payload;
+	return PublicErrorPayload.parse(wire);
+}
+//#endregion
+export { clientError };

package/dist/error/extend.d.ts

@@ -0,0 +1,101 @@
+import type { MessageParams } from "../i18n/catalog";
+import type { ErrorPayload, KitErrorDomain } from "./payload";
+import { ExtendedErrorPayload } from "./payload";
+/**
+ * A kit domain used in an adopter's code. The false branch is `unknown`, which intersects away; the
+ * true branch is a string the caller's own `code` cannot possibly be, so the mistake surfaces at the
+ * declaration with its reason spelled out in the type error rather than as `never`.
+ */
+type ReservedDomain<Code extends string> = Code extends `${KitErrorDomain}/${string}` ? {
+    code: "That domain is the kit's. Namespace your code under a domain of your own.";
+} : unknown;
+/**
+ * The payload behind one code, kit or adopter. `Extract` finds a kit member by its literal `code`;
+ * an adopter's code is branded and so extracts to nothing, and the open member stands in with the
+ * literal intersected back on. Type a vehicle class with it exactly as the kit's own subclasses are:
+ * `declare readonly payload: ErrorPayloadOf<"connect/device_code_expired">`.
+ */
+export type ErrorPayloadOf<Code extends string> = [Extract<ErrorPayload, {
+    code: Code;
+}>] extends [never] ? ExtendedErrorPayload & {
+    code: Code;
+} : Extract<ErrorPayload, {
+    code: Code;
+}>;
+/**
+ * Narrow a caught payload to one code. `payload.code === "core/not_found"` narrows a kit member on
+ * its own, but an adopter's code is branded — the brand is what keeps a kit narrow honest — so the
+ * same comparison against a bare literal is a type error, and `Extract` on it is silently `never`.
+ * This is the way in for both: one guard, kit codes and adopter codes alike.
+ *
+ * ```ts
+ * catch (error) {
+ *   if (error instanceof PithyError && isErrorCode(error.payload, "connect/device_code_expired")) {
+ *     return restartDeviceFlow();
+ *   }
+ * }
+ * ```
+ */
+export declare function isErrorCode<const Code extends `${string}/${string}`>(payload: ErrorPayload, code: Code): payload is ErrorPayloadOf<Code>;
+/**
+ * The one door into `ErrorPayload` for a code the kit does not define. An adopter writing a control
+ * plane, a device-code flow, or a key-rotation lock has failures the kit has no word for; without
+ * this they reuse a kit code that means something else, or stop throwing `PithyError` at all.
+ *
+ * It is a function rather than a plain object literal for the same reason `defineSecretRegistry` is:
+ * the declaration is where the mistake is, so the declaration is where it should fail. A code under
+ * one of the kit's domains does not compile — the kit's domains are reserved the way `pithy_` table
+ * names are, so nobody redefines `auth/forbidden` with a status of their choosing, and a
+ * capability's own typo stays a hard failure instead of becoming somebody's custom error. The parse
+ * below is the second gate, for the grammar, the 4xx/5xx bound, and any caller who cast their way
+ * past the first.
+ *
+ * What it does **not** do is pin a status to a code. A kit member fixes one status per code, and
+ * that cannot survive a set the kit does not hold: this seam bounds the range and nothing more, so
+ * throwing `connect/device_code_expired` as a 410 from one site and a 500 from another passes every
+ * layer. Declare each of your codes in one vehicle class, once, and that stays true by construction.
+ *
+ * It does not move the security boundary either. The payload it returns carries `action` and
+ * `detail` exactly like a kit member, and the HTTP codec strips both from every member alike. An
+ * adopter cannot opt into leaking, because there is nothing to opt into — the wire shape has no such
+ * key to fill, whoever defined the code.
+ *
+ * ```ts
+ * export class DeviceCodeExpiredError extends PithyError {
+ *   declare readonly payload: ErrorPayloadOf<"connect/device_code_expired">;
+ *
+ *   constructor(detail?: string) {
+ *     super(defineErrorPayload({
+ *       code: "connect/device_code_expired",
+ *       status: 410,
+ *       message: "That device code has expired.",
+ *       action: "Run pithy dashboard connect again.",
+ *       detail,
+ *     }));
+ *   }
+ * }
+ * ```
+ */
+export declare function defineErrorPayload<const Code extends `${string}/${string}`>(payload: {
+    /** `domain/reason`, lower snake_case, under a domain of the adopter's own — never one the kit uses. */
+    code: Code;
+    /** The HTTP status this code maps to. A 4xx or a 5xx — an error is not a success. */
+    status: number;
+    /** Public, safe-to-expose summary. Sent to clients and shown in the terminal. */
+    message: string;
+    /** Operator remediation hint. Becomes the CLI action line. Never sent to a client. */
+    action?: string;
+    /** Internal context for logs + audit. NEVER serialized to clients — the HTTP codec strips it. */
+    detail?: string;
+    /**
+     * Values a translating client interpolates into its own wording for this code. Client-facing:
+     * these cross the boundary with `message`, unlike `action` and `detail`.
+     *
+     * Stated here because this parameter type is **hand-written**, not derived from the schema, and
+     * the `as ErrorPayloadOf<Code>` below hides the gap from the compiler. A field left off this
+     * literal is not a type error anywhere — it is simply a field an adopter cannot pass.
+     */
+    params?: MessageParams;
+} & ReservedDomain<Code>): ErrorPayloadOf<Code>;
+export {};
+//# sourceMappingURL=extend.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"extend.d.ts","sourceRoot":"","sources":["../../src/error/extend.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAMjD;;;;GAIG;AACH,KAAK,cAAc,CAAC,IAAI,SAAS,MAAM,IAAI,IAAI,SAAS,GAAG,cAAc,IAAI,MAAM,EAAE,GACjF;IAAE,IAAI,EAAE,2EAA2E,CAAA;CAAE,GACrF,OAAO,CAAC;AAEZ;;;;;GAKG;AACH,MAAM,MAAM,cAAc,CAAC,IAAI,SAAS,MAAM,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GACrG,oBAAoB,GAAG;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GACrC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC,CAAC;AAE1C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,KAAK,CAAC,IAAI,SAAS,GAAG,MAAM,IAAI,MAAM,EAAE,EAClE,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,IAAI,GACT,OAAO,IAAI,cAAc,CAAC,IAAI,CAAC,CAEjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,IAAI,SAAS,GAAG,MAAM,IAAI,MAAM,EAAE,EACzE,OAAO,EAAE;IACP,uGAAuG;IACvG,IAAI,EAAE,IAAI,CAAC;IACX,qFAAqF;IACrF,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iGAAiG;IACjG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB,GAAG,cAAc,CAAC,IAAI,CAAC,GACvB,cAAc,CAAC,IAAI,CAAC,CAiBtB"}

package/dist/error/extend.js

@@ -0,0 +1,76 @@
+import { ExtendedErrorPayload } from "./payload.js";
+import { InternalError } from "./pithyError.js";
+//#region src/error/extend.ts
+/** How much of a rejected code the public message will quote. Enough to debug, not enough to abuse. */
+const QUOTED_CODE_LIMIT = 72;
+/**
+* Narrow a caught payload to one code. `payload.code === "core/not_found"` narrows a kit member on
+* its own, but an adopter's code is branded — the brand is what keeps a kit narrow honest — so the
+* same comparison against a bare literal is a type error, and `Extract` on it is silently `never`.
+* This is the way in for both: one guard, kit codes and adopter codes alike.
+*
+* ```ts
+* catch (error) {
+*   if (error instanceof PithyError && isErrorCode(error.payload, "connect/device_code_expired")) {
+*     return restartDeviceFlow();
+*   }
+* }
+* ```
+*/
+function isErrorCode(payload, code) {
+	return payload.code === code;
+}
+/**
+* The one door into `ErrorPayload` for a code the kit does not define. An adopter writing a control
+* plane, a device-code flow, or a key-rotation lock has failures the kit has no word for; without
+* this they reuse a kit code that means something else, or stop throwing `PithyError` at all.
+*
+* It is a function rather than a plain object literal for the same reason `defineSecretRegistry` is:
+* the declaration is where the mistake is, so the declaration is where it should fail. A code under
+* one of the kit's domains does not compile — the kit's domains are reserved the way `pithy_` table
+* names are, so nobody redefines `auth/forbidden` with a status of their choosing, and a
+* capability's own typo stays a hard failure instead of becoming somebody's custom error. The parse
+* below is the second gate, for the grammar, the 4xx/5xx bound, and any caller who cast their way
+* past the first.
+*
+* What it does **not** do is pin a status to a code. A kit member fixes one status per code, and
+* that cannot survive a set the kit does not hold: this seam bounds the range and nothing more, so
+* throwing `connect/device_code_expired` as a 410 from one site and a 500 from another passes every
+* layer. Declare each of your codes in one vehicle class, once, and that stays true by construction.
+*
+* It does not move the security boundary either. The payload it returns carries `action` and
+* `detail` exactly like a kit member, and the HTTP codec strips both from every member alike. An
+* adopter cannot opt into leaking, because there is nothing to opt into — the wire shape has no such
+* key to fill, whoever defined the code.
+*
+* ```ts
+* export class DeviceCodeExpiredError extends PithyError {
+*   declare readonly payload: ErrorPayloadOf<"connect/device_code_expired">;
+*
+*   constructor(detail?: string) {
+*     super(defineErrorPayload({
+*       code: "connect/device_code_expired",
+*       status: 410,
+*       message: "That device code has expired.",
+*       action: "Run pithy dashboard connect again.",
+*       detail,
+*     }));
+*   }
+* }
+* ```
+*/
+function defineErrorPayload(payload) {
+	const parsed = ExtendedErrorPayload.safeParse(payload);
+	if (!parsed.success) throw new InternalError({
+		message: `error payload: "${quoteCode(payload.code)}" (${payload.status}) is not a usable adopter error code.`,
+		action: "Use `<your_domain>/<reason>` in lower snake_case, a 4xx or 5xx status, and a domain the kit does not own.",
+		detail: parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")
+	});
+	return parsed.data;
+}
+/** The offending code, bounded, for an author-error message that reaches a client. */
+function quoteCode(code) {
+	return code.length <= QUOTED_CODE_LIMIT ? code : `${code.slice(0, QUOTED_CODE_LIMIT)}…`;
+}
+//#endregion
+export { defineErrorPayload, isErrorCode };