@pithy-sh/core 0.1.0

package/src/entitlement/require.ts

@@ -0,0 +1,199 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { MiddlewareHandler } from "hono";
+import type { PithyHonoEnv } from "../capability/capability";
+import { InternalError, messageOf, PithyError, UnauthorizedError } from "../error/pithyError";
+import {
+  ENTITLEMENT_DENIED_ACTION,
+  type EntitlementHolder,
+  EntitlementKey,
+  grantedEntitlementKeys,
+} from "./entitlement";
+
+/**
+ * The entitlement gate — the middleware half of the seam. `requireEntitlement("pro")` is the
+ * `verification`-strategy sibling every paid route carries: it says what the caller must *hold*, the
+ * way `requireAuth()` says who the caller must *be*, and it belongs on the route line beside it.
+ *
+ *   app.get("/reports", requireAuth(), requireEntitlement("pro"), zValidator(…), handler)
+ *
+ * It lives in `@pithy-sh/core` rather than in `@pithy-sh/payments` for the same reason `requireAuth()`
+ * is copied into each capability instead of imported from `@pithy-sh/auth`: a gate that arrives with a
+ * package fails **open** when that package is absent. Depending on the core seam means an uncomposed
+ * provider leaves `noEntitlementProvider` on the request, and every gate denies.
+ *
+ * Two names, not one variadic, because "any of these" and "all of these" are both plausible readings
+ * of `requireEntitlement("pro", "team")` and the wrong reading is a security bug rather than a typo.
+ */
+
+/**
+ * Why a gate denied — recorded in `detail` and in the audit event, never sent to the client.
+ *
+ * **Three readings, and keeping them apart is the whole job.** Nothing composed is one. A holder that has
+ * bought nothing is the second. A caller acting for **no** holder at all is the third — the ordinary state
+ * of somebody signed in with no organization selected, and before #412 it was spelled `payments resolved
+ * []`, identically to the second. They want opposite fixes: one is a sale, the other is a subject resolver
+ * returning nothing, and an operator reading one sentence had no way to tell which they were looking at.
+ *
+ * The holder is named only when the resolver reports one, and it is named as {@link EntitlementHolder}'s
+ * `label` — display text, never a value this gate compares. A resolver that cannot say omits it, and the
+ * sentence is exactly what it was.
+ */
+function denialDetail(
+  keys: readonly string[],
+  provider: string | null,
+  held: ReadonlySet<string>,
+  reading: HolderReading,
+): string {
+  const required = keys.join(" | ");
+  if (provider === null) {
+    return `no entitlement provider is composed, so \`${required}\` cannot be held. Add a payments capability to this Worker's pithy.config.ts.`;
+  }
+  switch (reading.kind) {
+    // The resolver could have answered and said nobody. Distinct from `failed` below, and the distinction is
+    // the point: this is a caller with no organization selected, which is a wiring or session question, not
+    // a broken provider.
+    case "nobody":
+      return `${provider} resolved no holder for this caller, so nothing can be held; the route requires \`${required}\`. Under organization billing this is a caller acting for no organization, not an unentitled one.`;
+    // It tried and raised. Saying "no holder" here would send an operator to an unwired resolver when the
+    // resolver is wired and erroring — the opposite diagnosis, and the exact ambiguity this sentence set
+    // exists to remove. The cause is already on the log line beside this.
+    case "failed":
+      return `${provider} could not resolve a holder for this caller — the read raised, see the preceding log line; the route requires \`${required}\`.`;
+    case "known":
+      return `${provider} resolved [${[...held].sort().join(", ")}] for ${reading.holder.label}; the route requires \`${required}\`.`;
+    // A resolver that never offered a holder at all — every one written before this existed. Reads exactly
+    // as it always did, which is what keeps the three sentences above meaning something when they appear.
+    default:
+      return `${provider} resolved [${[...held].sort().join(", ")}]; the route requires \`${required}\`.`;
+  }
+}
+
+/** The gate's denial: one code, one status, whatever the reason. The reason rides in `detail`. */
+function denied(
+  keys: readonly string[],
+  provider: string | null,
+  held: ReadonlySet<string>,
+  reading: HolderReading,
+): PithyError {
+  return new PithyError({
+    code: "payments/entitlement_required",
+    status: 403,
+    message: "This feature requires an active subscription or purchase.",
+    action: "Purchase or restore the product that grants access, then retry.",
+    detail: denialDetail(keys, provider, held, reading),
+  });
+}
+
+/**
+ * What asking the resolver who it answered for actually produced. Four states, because collapsing any two
+ * of them gives an operator the wrong diagnosis:
+ *
+ * - `unavailable` — the resolver offers no `holder()`. Nothing to report, and nothing went wrong.
+ * - `nobody` — it answered, and the answer is that this caller acts for no holder.
+ * - `known` — it answered with one.
+ * - `failed` — it raised. **Not `nobody`.** A caller with no organization selected and a session store that
+ *   is down look identical from the gate, and they are opposite problems: one is wiring, one is an outage.
+ */
+type HolderReading =
+  | { readonly kind: "unavailable" }
+  | { readonly kind: "nobody" }
+  | { readonly kind: "known"; readonly holder: EntitlementHolder }
+  | { readonly kind: "failed" };
+
+/**
+ * Require any one of `keys`. Every key is parsed at construction, so a store SKU where an entitlement
+ * key belongs (`com.acme.pro.monthly`) fails on deploy rather than gating on something no projection
+ * ever writes. An empty list is refused for the same reason: it reads as "nothing required" but would
+ * deny every caller forever.
+ */
+export function requireAnyEntitlement(keys: readonly string[]): MiddlewareHandler<PithyHonoEnv> {
+  if (keys.length === 0) {
+    throw new InternalError({
+      message: "requireAnyEntitlement() needs at least one entitlement key.",
+      action: "Name the entitlements that grant access, or drop the gate if the route is not paid.",
+    });
+  }
+  const required = keys.map((key) => EntitlementKey.parse(key));
+
+  return async (c, next) => {
+    // A gate is not an identity check: an anonymous caller is 401, so a 403 never confirms to an
+    // unauthenticated stranger that the route exists and is paid.
+    const auth = c.var.auth;
+    if (!auth) {
+      throw new UnauthorizedError({
+        message: "Authentication required.",
+        action: "Sign in and retry with a valid session or bearer token.",
+      });
+    }
+
+    const resolver = c.var.entitlements;
+    // A provider whose store is unreachable must not become an open door, so a throw is a denial.
+    // The cause goes to the log, where an operator sees the difference between "unentitled" and
+    // "broken" — the response cannot, without telling a client about our infrastructure.
+    let held: Set<string>;
+    try {
+      held = grantedEntitlementKeys(await resolver.list(), new Date());
+    } catch (error) {
+      c.var.log.error("entitlement resolution failed", { provider: resolver.provider, cause: messageOf(error) });
+      held = new Set();
+    }
+
+    // **Read after the decision, never before it.** Everything below this line is reporting: the gate has
+    // already passed or denied on `held` alone, so nothing the holder says can change the outcome. A holder
+    // read above the check would be a holder in reach of the check.
+    if (required.some((key) => held.has(key))) {
+      await next();
+      return;
+    }
+
+    // Who the resolver answered for — see {@link HolderReading} for why a throw is its own state rather
+    // than folding into "nobody".
+    let reading: HolderReading = { kind: "unavailable" };
+    if (resolver.holder) {
+      try {
+        const answered = await resolver.holder();
+        reading = answered === undefined ? { kind: "nobody" } : { kind: "known", holder: answered };
+      } catch (error) {
+        // Same rule the list read follows one step up: a provider that cannot answer is a denial, never an
+        // open door and never a 500. This one is strictly weaker — it costs a log line, not a decision.
+        reading = { kind: "failed" };
+        c.var.log.error("entitlement holder resolution failed", {
+          provider: resolver.provider,
+          cause: messageOf(error),
+        });
+      }
+    }
+
+    // A blocked attempt is a first-class audit record (`outcome: "denied"`), not only a 403. `emit()`
+    // is non-fatal by contract and a no-op with no audit capability composed, so this is always safe.
+    //
+    // `tenant` is what makes the trail readable per customer — "which of our companies is hitting the
+    // paywall" is the question, and `actorId` cannot answer it because one person acts in two tenants. It
+    // is the value the **resolver reported**, never one derived here from `auth`: this middleware has no
+    // idea whose action it was, and guessing would put the wrong customer on a row somebody bills from.
+    // `null` is a real answer meaning *not tenant-scoped*, which is what per-person billing is.
+    await c.var.emit({
+      action: ENTITLEMENT_DENIED_ACTION,
+      outcome: "denied",
+      severity: "info",
+      actorType: "user",
+      actorId: auth.userId,
+      sessionId: auth.sessionId,
+      resourceType: "entitlement",
+      resourceId: required.join("|"),
+      // Only a holder we actually have. A failed read stamps null — "not tenant-scoped" is wrong but
+      // inventing a tenant from a read that raised would be worse, and the log line carries the truth.
+      tenant: reading.kind === "known" ? reading.holder.tenant : null,
+      metadata: { provider: resolver.provider, required, held: [...held].sort() },
+    });
+
+    throw denied(required, resolver.provider, held, reading);
+  };
+}
+
+/** Require one entitlement. The common case: one key gates one feature. */
+export function requireEntitlement(key: string): MiddlewareHandler<PithyHonoEnv> {
+  return requireAnyEntitlement([key]);
+}

package/src/env/ambient.ts

@@ -0,0 +1,67 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { ENVIRONMENT_VAR } from "../worker/identity";
+
+/**
+ * What the *ambient* environment says about the composition being assembled — the two questions a
+ * capability may ask before it registers anything, and the one reader for both.
+ *
+ * ## Why a capability can ask this at all
+ *
+ * A Worker is handed its bindings per request, so `c.env` does not exist when `createBackend` calls a
+ * capability's `routes()`. `process.env` does: with `nodejs_compat` and a compatibility date past
+ * 2025-04-01 — every Worker `pithy init` scaffolds — workerd populates `process.env` from the script's
+ * own `vars` and secrets, and it is populated at module scope, before the first request. Verified
+ * against a real `wrangler dev`: at module scope `Object.keys(process.env)` is exactly the declared
+ * vars.
+ *
+ * That is the whole reach of this module, and the limit is the interesting half:
+ *
+ * - **`ENVIRONMENT` is here**, because `pithy init` stamps it into every environment stanza of every
+ *   Worker's `wrangler.jsonc` ({@link ENVIRONMENT_VAR}). A composition can therefore know it is `dev`
+ *   without being told.
+ * - **The host's environment is not here.** `CI=true` in the shell that ran `wrangler dev` does *not*
+ *   appear inside the Worker — workerd replaces `process.env` with the bindings rather than merging.
+ *   {@link ./ci.ts} carries that consequence and what is done about it.
+ *
+ * Read at call time, never captured at import: a module-scope snapshot is unstubbable in a test and
+ * would freeze the answer for the life of an isolate that outlives a `.dev.vars` edit.
+ */
+
+/** A process environment as this module reads one — the shape of `process.env`, and nothing assumed of it. */
+export type AmbientEnv = Readonly<Record<string, string | undefined>>;
+
+/**
+ * The ambient environment, or an empty one where there is no `process` at all.
+ *
+ * Guarded rather than assumed: this module is bundled into Workers, and a runtime without
+ * `nodejs_compat` has no `process`. An empty environment answers "nothing was stamped", which is the
+ * refusing answer everywhere it is used — a missing `process` must never read as `dev`.
+ */
+export function ambientEnv(): AmbientEnv {
+  return (globalThis as { process?: { env?: AmbientEnv } }).process?.env ?? {};
+}
+
+/**
+ * Whether an environment variable counts as **set**: any non-blank value, blank is no override.
+ *
+ * One rule, stated once. It is `PITHY_OFFLINE`'s (#218), and the reason it is not "`=== "true"`" is
+ * that runners disagree — `true`, `1`, and an operator's own word all mean the same thing, and a
+ * variable someone deliberately blanked (`CI=`) is the one case that means "no".
+ */
+export function ambientFlag(env: AmbientEnv, name: string): boolean {
+  return (env[name] ?? "").trim().length > 0;
+}
+
+/**
+ * The environment this composition was stamped for — `dev`, `staging`, `prod`, or an adopter's own —
+ * and `undefined` where nothing stamped one.
+ *
+ * **`undefined`, never a defaulted `dev`.** The callers are gates, and a gate that assumes `dev` when
+ * it was told nothing opens itself in exactly the deployment whose `wrangler.jsonc` lost the var.
+ */
+export function compositionEnvironment(env: AmbientEnv = ambientEnv()): string | undefined {
+  const value = (env[ENVIRONMENT_VAR] ?? "").trim();
+  return value.length > 0 ? value : undefined;
+}

package/src/env/ci.ts

@@ -0,0 +1,43 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { type AmbientEnv, ambientEnv, ambientFlag } from "./ambient";
+
+/**
+ * Is this continuous integration? One read, one rule, one place — the convention starts here.
+ *
+ * Nothing in this repository read `CI` before #243, so this is the declaration rather than a fourth
+ * copy of one. It exists because a gate that inlines `!!process.env.CI` at the point it guards is a
+ * gate whose meaning is re-decided by whoever writes the next one.
+ *
+ * ## What counts as set
+ *
+ * **Any non-blank value.** `CI=true`, `CI=1`, and `CI=woodpecker` are all CI; `CI=` (set but empty,
+ * which some runners do) and an absent `CI` are not. That is `PITHY_OFFLINE`'s rule (#218) applied
+ * unchanged, rather than a second rule for a second variable — see {@link ambientFlag}.
+ *
+ * ## Why anything reads it
+ *
+ * CI is where an unsupervised capability is most reachable and least watched. A `dev` composition is
+ * exactly what CI boots — integration suites, packaging checks, `pithy dev` itself — so "not `dev`"
+ * does not cover CI, and CI is not production, so neither signal implies the other. Anything gated on
+ * both asks twice, in two statements: an `||` folded into one expression is one edit from an `&&`, and
+ * the failure mode is a session-minting endpoint that answers.
+ *
+ * ## Where it can be read, and where it cannot
+ *
+ * In the CLI, and in anything else running under Node, this is the host's own `CI`. **Inside a Worker
+ * it is not**: workerd populates `process.env` from the script's bindings and nothing else, so the
+ * shell variable does not cross that boundary (see {@link ./ambient.ts}). A Worker-side gate is
+ * therefore only as truthful as what started the Worker — which is why `pithy dev` forwards `CI` into
+ * every Worker it launches as a var, and why a gate that depends on this must also carry a second,
+ * independent refusal that needs no forwarding.
+ */
+
+/** The variable every CI runner sets without configuration. The name is not ours to choose. */
+export const CI_ENV = "CI";
+
+/** Whether this process is running under continuous integration. Any non-blank `CI`; blank is not CI. */
+export function isContinuousIntegration(env: AmbientEnv = ambientEnv()): boolean {
+  return ambientFlag(env, CI_ENV);
+}

package/src/env/stem.ts

@@ -0,0 +1,34 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * How a member of the dev set publishes its address, and how a sibling looks it up.
+ *
+ * `pithy dev` pins one port per worker at feature-create and exports `<STEM>_PORT` / `<STEM>_ORIGIN`
+ * for every one of them, so a worker reaches its peers at a known address rather than through
+ * wrangler's cross-`wrangler dev` service registry (CLAUDE.md §CLI). The stem is the join: the CLI
+ * writes the var, and code running *inside* the Worker reads it.
+ *
+ * **It lives in core because both ends are now real.** It was the CLI's private helper while only the
+ * CLI used it; the loopback Workflow dispatcher ({@link ../workflow/loopback.ts}) made the runtime the
+ * other end of the same wire, and two copies of a name-derivation rule are two answers the first day
+ * one of them learns about a character the other does not.
+ */
+
+/**
+ * The env-var stem for a worker or capability: uppercased, every non-alphanumeric run collapsed to a
+ * single `_`, leading and trailing separators dropped. `media-cli` → `MEDIA_CLI`.
+ *
+ * Deterministic, so the name a worker publishes is the name every sibling looks up.
+ */
+export function envStem(name: string): string {
+  return name
+    .toUpperCase()
+    .replace(/[^A-Z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+}
+
+/** The var carrying one member's loopback address — `email` → `EMAIL_ORIGIN`. */
+export function originVarName(name: string): string {
+  return `${envStem(name)}_ORIGIN`;
+}

package/src/error/cause.ts

@@ -0,0 +1,208 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * 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 function prop(cause: unknown, key: string): unknown {
+  if (typeof cause !== "object" || cause === null) return undefined;
+  return (cause as Record<string, unknown>)[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.
+ */
+export function rootCause(cause: unknown): unknown {
+  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] === undefined) 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.
+ */
+export function isBuildFailureWrapper(cause: unknown): boolean {
+  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. */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: stripping the control characters is the point.
+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}.
+ */
+export function causeMessage(cause: unknown): string | undefined {
+  const message = prop(cause, "message");
+  return typeof message === "string" ? message.replace(ANSI, "") : 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 function safeReason(cause: unknown): string | undefined {
+  if (isBuildFailureWrapper(cause)) return undefined;
+  const text = (causeMessage(cause) ?? "").trim();
+  if (text.length === 0 || text.length > REASON_LIMIT) return undefined;
+  if (text.includes("\n")) return undefined;
+  if (ABSOLUTE_PATH.test(text)) return undefined;
+  if (STACK_FRAME.test(text)) return undefined;
+  return text.replace(/\.$/, "");
+}
+
+/** 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 function failurePosition(cause: unknown): FailurePosition | undefined {
+  if (isBuildFailureWrapper(cause)) return undefined;
+  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 undefined;
+  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.
+ */
+export function unresolvedSpecifier(cause: unknown): string | undefined {
+  const field = prop(cause, "specifier");
+  if (typeof field === "string" && field.length > 0) return field;
+  const match = /Cannot find (?:package|module) ['"]([^'"]+)['"]/.exec(causeMessage(cause) ?? "");
+  return match?.[1];
+}

package/src/error/client.ts

@@ -0,0 +1,43 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+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 function clientError(payload: z.input<typeof ErrorPayload>): PublicErrorPayload {
+  // Removed by name first, then by schema. Doubled deliberately: the spread states the intent at the
+  // one site that has it, and the parse is what an adopter's own code is held to.
+  const { action: _action, detail: _detail, ...wire } = payload;
+  return PublicErrorPayload.parse(wire);
+}