@pithy-sh/core 0.2.0 → 0.3.1

package/dist/test-utils/oidcFixtures.js

@@ -0,0 +1,111 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/test-utils/oidcFixtures.ts
+/**
+* Mint one RSA key pair and publish its public half as a JWK.
+*
+* Real WebCrypto, not a fixture: a hand-rolled key and a hand-rolled signature would let every signature
+* assertion pass by agreeing with itself. A second minted key is what makes "signed by somebody else" a
+* real statement rather than a label — mint one, publish only the first, and the refusal is the verifier's
+* rather than the test's.
+*
+* Key generation is the slow part of any suite using this and a key is immutable, so mint in a
+* `beforeAll` and reuse.
+*/
+async function mintKey(kid) {
+	const pair = await crypto.subtle.generateKey({
+		name: "RSASSA-PKCS1-v1_5",
+		hash: "SHA-256",
+		modulusLength: 2048,
+		publicExponent: new Uint8Array([
+			1,
+			0,
+			1
+		])
+	}, true, ["sign", "verify"]);
+	const exported = await crypto.subtle.exportKey("jwk", pair.publicKey);
+	if (exported.kty === void 0 || exported.n === void 0 || exported.e === void 0) throw new Error("WebCrypto exported an RSA public key with no kty, n, or e.");
+	return {
+		kid,
+		jwk: {
+			...exported,
+			kty: exported.kty,
+			n: exported.n,
+			e: exported.e,
+			kid,
+			alg: "RS256",
+			use: "sig"
+		},
+		privateKey: pair.privateKey
+	};
+}
+/**
+* base64url without padding — how every segment of a compact JWS is encoded.
+*
+* Exported because a test that builds a token by hand needs it: the tamper case swaps a claims segment and
+* keeps the signature, and re-encoding that segment with padding or with `+`/`/` would make the token
+* refused for the wrong reason.
+*/
+function base64Url(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+}
+/**
+* Sign a compact JWT the way an identity provider signs an OIDC token: `RS256`, `typ: "JWT"`, and the
+* signer's `kid` in the header.
+*
+* `payload` is the claims, written as the provider writes them — `iss`, `aud`, `exp`, and whatever the
+* route's `claims` predicate reads. Nothing here defaults a claim, because a fixture that quietly supplied
+* one would be testing itself.
+*
+* `header` overrides let a test present a header no provider would — `alg: "none"`, `alg: "RS512"`, a `kid`
+* nobody published, or `kid: undefined` — which is how a route proves algorithm confusion and an
+* unpublished key are rejected, instead of trusting that the kit covers it somewhere.
+*/
+async function signToken(payload, signer, header = {}) {
+	const encoder = new TextEncoder();
+	const head = base64Url(encoder.encode(JSON.stringify({
+		alg: "RS256",
+		typ: "JWT",
+		kid: signer.kid,
+		...header
+	})));
+	const body = base64Url(encoder.encode(JSON.stringify(payload)));
+	return `${head}.${body}.${base64Url(new Uint8Array(await crypto.subtle.sign("RSASSA-PKCS1-v1_5", signer.privateKey, encoder.encode(`${head}.${body}`))))}`;
+}
+/**
+* A JWKS transport that publishes `keys` at `jwksUrl` and nothing anywhere else, recording every URL it was
+* asked for in `seen`.
+*
+* **The response is the seam's own shape, which is the whole point of shipping this.** `text()`, never
+* `json()` — {@link OidcJwksResponse} reads the body as text deliberately, so a proxy's HTML error page is a
+* diagnosis rather than a throw. A hand-rolled transport that answers `json()` produces a 502 on every
+* delivery from a fixture that looks correct. Typed as {@link OidcJwksFetch}, that mistake will not compile.
+*
+* **The URL is a parameter rather than a wildcard.** A transport that served keys at any URL would pass a
+* route whose configured `jwksUrl` points at nothing — the one configuration mistake a test of a webhook
+* route exists to catch. Anything else gets a 404 with a body, which is what an issuer's CDN actually
+* returns and what the verifier maps to a 502.
+*
+* `seen` is an array the caller owns, so a test can assert the fetch count: one per delivery with no cache,
+* one per TTL with one, and zero when a cache is pre-seeded. Pass `publishing(url, [], seen)` to prove a
+* path never reaches the network at all — an empty key set is refused, so an unexpected fetch fails loudly.
+*/
+function publishing(jwksUrl, keys, seen = []) {
+	return async (url) => {
+		seen.push(url);
+		if (url !== jwksUrl) return {
+			ok: false,
+			status: 404,
+			text: async () => "{}"
+		};
+		return {
+			ok: true,
+			status: 200,
+			text: async () => JSON.stringify({ keys })
+		};
+	};
+}
+//#endregion
+export { base64Url, mintKey, publishing, signToken };

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.2.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.2.0";
+const PACKAGE_VERSION = "0.3.1";
 //#endregion
 export { PACKAGE_NAME, PACKAGE_VERSION };

package/dist/workflow/naming.js

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
-import { NAME_SEGMENT } from "../naming/segment.js";
 import { InternalError } from "../error/pithyError.js";
+import { NAME_SEGMENT } from "../naming/segment.js";
 import { NAMESPACE_LIMITS } from "../naming/limits.js";
 import { assertValidProjectName, kebab } from "../naming/resource.js";
 //#region src/workflow/naming.ts

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.2.0",
+  "version": "0.3.1",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/capability/bindings.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import { z } from "zod";
+import { FEATURE_RESOURCE_KINDS } from "../naming/feature";
 import { NAME_SEGMENT } from "../naming/segment";
 
 export const BindingType = z
@@ -100,6 +101,19 @@ const CLASS_NAME = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
  */
 const CLASS_MODULE = /^(@[a-z0-9~-][a-z0-9._~-]*\/)?[a-z0-9~-][a-z0-9._~-]*(\/[A-Za-z0-9_~-][A-Za-z0-9._~-]*)*$/;
 
+/**
+ * The kinds whose resource Pithy names and creates — the only kinds `scope` and `resource` mean anything
+ * for.
+ *
+ * {@link FEATURE_RESOURCE_KINDS} rather than a fresh literal, because it is already the repo's answer to
+ * "which bindings does a provisioning run compose a `<project>-<scope>-<thing>` name for": it is the
+ * domain of `ProvisionScope.resource`, and the CLI's own `PROVISIONABLE` map is the same three. Every
+ * other kind's name is composed by a different rule with no `<thing>` slot to fill — a Workflow's from
+ * the capability and the job, a Worker script's by wrangler — and a `secret` already states its scope in
+ * `defineSecretRegistry`, where the value it names lives.
+ */
+const NAMED_RESOURCE_KINDS = new Set<string>(FEATURE_RESOURCE_KINDS);
+
 /**
  * Declares a Cloudflare binding a capability requires in the Worker env. The authoring
  * shape lets `optional` be omitted (defaults false); `createBackend` normalizes via parse.
@@ -151,6 +165,24 @@ export const BindingSpec = z
       .describe(
         "Reach the real Cloudflare resource during local development instead of a local emulation. Set it for a binding that has none — Vectorize and Workers AI both lack local simulation — so `wrangler dev` and any Workflow host, which always runs locally, still work. Left unset rather than defaulting to false, so a spec that does not care emits no flag at all. Ignored in a deployed Worker.",
       ),
+    scope: z
+      .enum(["environment", "global"])
+      .optional()
+      .describe(
+        "Whether the resource behind this binding is one per environment (absent, the default) or one for the whole project. A `global` resource takes the literal `global` where the environment segment goes — `<project>-global-<thing>` — so every environment's stanza names the identical resource and provisioning creates it once. Declare it where the data is not an environment-local fact: `@pithy-sh/email`'s suppression list is one per project, because an unsubscribe recorded through a staging Worker has to be honored by a production one, and three per-environment databases meant it was not (#513). Say nothing where it is: a session store, a cache, and `@pithy-sh/secrets`' own database are per environment, and one line apart in the same env there is no convention to tell them apart by — which is why this is declared rather than inferred. Meaningful only for a `d1`, `kv` or `r2` binding.",
+      ),
+    resource: z
+      .string()
+      .min(1)
+      // The same rule the composed name answers to, asserted here rather than only where the name is
+      // built: a manifest is third-party data read out of `node_modules`, and this string is the last
+      // segment of a Cloudflare resource name. A manifest stating something a provisioning run would
+      // refuse is refused at parse instead, attributed to the capability, before anything is created.
+      .regex(NAME_SEGMENT, "A resource is one name segment: lowercase letters, digits, and single hyphens.")
+      .optional()
+      .describe(
+        "The `<thing>` segment of this resource's name, when it is not the kebabbed binding name. Absent is the ordinary case and means the binding name is the segment (`EMAIL_SUPPRESSIONS` → `email-suppressions`). Declare it where the two must differ: `SUPPORT_BUCKET` backs `<project>-global-support`, because the binding keeps `_BUCKET` for whoever reads `env.SUPPORT_BUCKET` in a Worker while the resource drops it — `r2` is already the composed name's kind, so the suffix repeats it. Meaningful only for a `d1`, `kv` or `r2` binding.",
+      ),
   })
   .describe("Declares a Cloudflare binding a capability requires in the Worker env.")
   .check((ctx) => {
@@ -189,6 +221,23 @@ export const BindingSpec = z
         message: `Service binding "${ctx.value.name}" needs a service — the Worker it calls, as named in apps/.`,
       });
     }
+    // `scope` and `resource` are the two halves of a *provisioned resource's name*, and only
+    // {@link NAMED_RESOURCE_KINDS} have one Pithy composes. On anything else they are inert — a Workflow
+    // would keep its `<capability>-<job>` name, a `secret` its registry's scope — so a manifest that
+    // states one is not describing a resource that exists. Refused rather than ignored, and refused here
+    // rather than in the writer, because a silently-dropped `scope: "global"` reads, in the manifest, as
+    // exactly the declaration #513 exists to make true.
+    if (!NAMED_RESOURCE_KINDS.has(ctx.value.type)) {
+      for (const field of ["scope", "resource"] as const) {
+        if (ctx.value[field] === undefined) continue;
+        ctx.issues.push({
+          code: "custom",
+          input: ctx.value,
+          path: [field],
+          message: `Binding "${ctx.value.name}" declares a ${field}, which only a d1, kv or r2 binding has — this one is a ${ctx.value.type}.`,
+        });
+      }
+    }
   });
 export type BindingSpec = z.infer<typeof BindingSpec>;
 

package/src/capability/capability.ts

@@ -160,6 +160,34 @@ export interface SecretRegistryEntrySeam {
 /** A capability's secret-registry slice: secret name → {@link SecretRegistryEntrySeam}. */
 export type SecretRegistrySeam = Record<string, SecretRegistryEntrySeam>;
 
+/**
+ * **Which branches of a `json` secret's schema this Worker's configuration actually uses** — secret
+ * name → the top-level keys that apply, in the order they should be offered.
+ *
+ * A `json` secret is often a bundle of independent blocks: `payments-provider-credentials` is five
+ * optional rail blocks, `turnstile-secret-keys` is two optional widgets. The schema says which blocks
+ * are *possible*; only the composed config says which are *real*, and a credential for a rail that is
+ * off is a value nothing will ever read. So `pithy secrets create` asks per field for the blocks named
+ * here, and never offers — never writes — one that is not.
+ *
+ * **It is declared, not matched by name.** `PaymentsRailToggles.paddle` and
+ * `PaymentsProviderCredentials.paddle` happen to be spelled the same today, and a CLI that keyed off
+ * that would be right by coincidence: nothing makes a config flag and a schema key the same thing, and
+ * two of them one line apart cannot be told apart by convention (#513). The capability already knows
+ * the answer at construction — it has both halves in hand — so it states it, and the CLI reads a fact
+ * instead of inferring one.
+ *
+ * **It lives on the capability rather than on the entry** because a registry entry is plain data,
+ * shared by every Worker that declares the name and projected into `pithy.manifest.json`. This answer
+ * is per composition — the same secret, two Workers, two configs — so it belongs where the config is.
+ *
+ * An absent declaration is not an empty one. A capability that says nothing leaves the CLI with no way
+ * to know which blocks apply, and it falls back to asking for the whole document rather than guessing;
+ * an empty array says *none of them apply*, which is the same fallback for a different reason. A
+ * secret whose schema has no branches at all needs no declaration — every field is asked.
+ */
+export type SecretBranchSeam = Record<string, readonly string[]>;
+
 /**
  * The structural seam for one capability's token-profile slice — profile name → the scoped CF API
  * token that capability's code needs. Declared next to the code that uses it (alongside
@@ -298,6 +326,12 @@ export interface Capability<
    * every declared secret in one batch — and no capability needs to know another's secrets.
    */
   secretRegistry?: SecretRegistrySeam;
+  /**
+   * Which branches of this capability's `json` secrets this Worker's configuration uses — see
+   * {@link SecretBranchSeam}. Additive and optional: a capability whose secrets are flat, or which has
+   * no `json` secret at all, declares nothing.
+   */
+  secretBranches?: SecretBranchSeam;
   /**
    * The scoped CF API tokens this capability's code needs, as a token-profile slice (profile name →
    * {@link TokenProfileSeam}). Additive and optional, and declared next to {@link Capability.secretRegistry}

package/src/createBackend.ts

@@ -18,11 +18,11 @@ import { isControlPlaneCapability } from "./controlPlane/capability";
 import { allowedOriginSet, corsSurface, registerControlPlaneCors } from "./controlPlane/http/cors";
 import { buildDbRegistry, composeDatabases, type DbRegistry } from "./data/databases";
 import { noEntitlementProvider } from "./entitlement/entitlement";
-import { pithyErrorHandler } from "./error/http";
 import { ValidationError } from "./error/pithyError";
 import { catalogFor, composeMessages } from "./i18n/registry";
 import { bakedTranslator, DEFAULT_LOCALE } from "./i18n/translator";
 import { buildKvRegistry, composeKv, type KvRegistry } from "./kv/namespaces";
+import { loggingErrorHandler } from "./logger/errorHandler";
 import type { Logger } from "./logger/logger";
 import { bindRequestContext, createWorkerLogger } from "./logger/worker";
 import { HEALTH_PATH } from "./worker/health";
@@ -111,7 +111,8 @@ function envNameOf(env: Record<string, unknown>, fallback: string | undefined):
  * each capability's middleware; and mounts the capability (then app) routes. On every request
  * `c.var.db` is the typed database registry — one `Kysely` per named database (`c.var.db.app`) —
  * and `c.var.kv` the typed namespace registry — one `TypedKv` per store (`c.var.kv.cms.pages`).
- * `PithyError`s become their declared HTTP status via {@link pithyErrorHandler}.
+ * `PithyError`s become their declared HTTP status via {@link loggingErrorHandler}, which also writes
+ * each fault to the request logger with its `action` and `detail` — the fields the wire body strips.
  *
  * Binding validation runs **once on the first request**, not at module load: in Workers `env` is
  * per-request, so there is no env to check until a request arrives. The result is memoized.
@@ -178,7 +179,10 @@ export function createBackend<
   // Build internally against the loose base env (db/kv are `unknown`, so `c.set` accepts the merged
   // registries); the precise types ride on the return below.
   const app = new Hono<PithyHonoEnv>();
-  app.onError(pithyErrorHandler);
+  // The logging handler, not the bare encoder: a fault's `action` names the var or command an operator
+  // must fix, `clientError` strips it on the way to the wire (correctly), and without this the remedy
+  // reached no surface at all in a deployed Worker — one access log line reading `status: 500` (#521).
+  app.onError(loggingErrorHandler);
 
   // Set once at assembly (the per-request `env` constraint holds: correlation binds per request below,
   // not here). Defaults to the CF-native Mode 2 logger — structured records to Workers Logs, zero-config.

package/src/error/http.ts

@@ -73,20 +73,44 @@ function fromHttpException(error: HTTPException): PithyError | null {
 }
 
 /**
- * Hono `onError` handler. Register once on the root app (`app.onError(pithyErrorHandler)`): any
- * `PithyError` becomes `{ error: <public payload> }` at its declared status; a Hono `HTTPException`
- * 400 becomes `validation/invalid_input`; any other throw is wrapped as a `core/internal` 500
- * carrying the original as `cause` (kept internal) and a generic public message — mirroring the
- * CLI's "unexpected crash" path.
+ * Whatever was thrown, as the `PithyError` the response will be rendered from.
+ *
+ * A `PithyError` is itself; a Hono `HTTPException` 400 becomes `validation/invalid_input`; anything
+ * else is wrapped as a `core/internal` 500 carrying the original as `cause` (kept internal) and a
+ * generic public message — mirroring the CLI's "unexpected crash" path.
+ *
+ * Split out from {@link pithyErrorHandler} so a caller that wants to **read** the fault before it is
+ * encoded — the logging handler in `logger/errorHandler.ts` — works from the same object the response
+ * is built from, rather than translating a second time and logging a different instance of it. The
+ * split is what keeps this module free of the logger: the translation is exported, the log is written
+ * on the other side of the boundary. See `logger/boundary.test.ts`.
  */
-export function pithyErrorHandler(err: Error, c: Context): Response {
+export function toPithyError(err: Error): PithyError {
+  if (err instanceof PithyError) return err;
   const translated = err instanceof HTTPException ? fromHttpException(err) : null;
-  const pithy =
-    err instanceof PithyError
-      ? err
-      : (translated ?? new InternalError({ detail: err instanceof Error ? err.message : String(err) }, { cause: err }));
+  return translated ?? new InternalError({ detail: err instanceof Error ? err.message : String(err) }, { cause: err });
+}
+
+/** Render an already-translated fault as its HTTP response — the client half, and only that. */
+export function renderPithyError(pithy: PithyError, c: Context): Response {
   // A kit member pins a literal status; an adopter's carries a `number` the schema has already
   // bounded to 400–599. Hono types the argument as its own literal union, and that is the one gap
   // between the two — the value is validated, so the assertion narrows rather than trusts.
   return c.json({ error: HttpError.encode(pithy.payload) }, pithy.payload.status as ContentfulStatusCode);
 }
+
+/**
+ * Hono `onError` handler — the **encoder**, with no log of its own.
+ *
+ * Any `PithyError` becomes `{ error: <public payload> }` at its declared status; a Hono
+ * `HTTPException` 400 becomes `validation/invalid_input`; any other throw is wrapped as a
+ * `core/internal` 500.
+ *
+ * **Prefer `loggingErrorHandler` from `logger/errorHandler.ts`** — `createBackend` registers that one,
+ * and it is what makes a misconfiguration's `action` reach an operator instead of dying at the wire
+ * (#521). This one stays exported for an app assembled without the logger seam, and it stays here,
+ * logger-free, because this module is on the client side of the logger boundary.
+ */
+export function pithyErrorHandler(err: Error, c: Context): Response {
+  return renderPithyError(toPithyError(err), c);
+}

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;