@pithy-sh/core 0.1.5 → 0.3.0

package/dist/http/webhookWindow.js

@@ -0,0 +1,35 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/http/webhookWindow.ts
+/**
+* The freshness window a signed webhook is checked against: the default, and the widest one accepted.
+*
+* **Two numbers in a module of their own, because of who has to read them.** They are the bounds a
+* config schema states in its own `.describe()` — `packages/payments/src/config/config.ts` interpolates
+* the maximum into the sentence an adopter reads — and a config schema is one half of a route contract,
+* which a management client validates **in a browser**. `signedWebhook.ts` is a Hono middleware and
+* reaches the whole Worker graph from `PithyHonoEnv` down; importing a number from it dragged `hono`,
+* `kysely`, `kysely-d1` and `@cloudflare/workers-types` into `payments/src/http/schemas.ts`,
+* `payments/src/http/responses.ts` and every module that reaches payments' config (#521).
+*
+* `tooling/browser-scopes` is the gate that caught it, and it is the gate that keeps this file a leaf:
+* **nothing here may import anything.** A constant a browser-facing schema quotes belongs beside the
+* other constants a browser may see, not inside the verifier that enforces it.
+*/
+/** How far a delivery's own timestamp may be from now. Stripe's default, and generous against clock skew. */
+const SIGNED_WEBHOOK_TOLERANCE_SECONDS = 300;
+/**
+* The widest freshness window the verifier accepts, and it refuses above rather than clamping.
+*
+* A tolerance is a replay window in the plainest possible units: every second of it is a second longer a
+* captured delivery keeps working. The five minutes above is Stripe's own and covers clock drift plus ordinary
+* delivery latency; an hour is the far end of a sender that queues a delivery and re-sends it without re-dating
+* it. Past that a number has stopped covering latency and started covering a capture.
+*
+* Refused rather than clamped because an `86400` is a typo or a misunderstanding either way — clamped, the
+* endpoint keeps working and nobody reads the line again; refused, the first delivery says which knob is wrong
+* and it is a two-character fix.
+*/
+const SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS = 3600;
+//#endregion
+export { SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS, SIGNED_WEBHOOK_TOLERANCE_SECONDS };

package/dist/logger/errorHandler.d.ts

@@ -0,0 +1,11 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Context } from "hono";
+/**
+ * Hono `onError` handler: log the fault with its full payload, then render the public response.
+ *
+ * Register it once on the root app — `createBackend` already does. `pithyErrorHandler` remains the
+ * bare encoder for an app that has no logger seam at all.
+ */
+export declare function loggingErrorHandler(err: Error, c: Context): Response;
+//# sourceMappingURL=errorHandler.d.ts.map

package/dist/logger/errorHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorHandler.d.ts","sourceRoot":"","sources":["../../src/logger/errorHandler.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AA8EpC;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,GAAG,QAAQ,CAMpE"}

package/dist/logger/errorHandler.js

@@ -0,0 +1,87 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { renderPithyError, toPithyError } from "../error/http.js";
+import { createWorkerLogger } from "./worker.js";
+//#region src/logger/errorHandler.ts
+/**
+* The `onError` handler that **writes the fault down** before it renders it.
+*
+* ## The defect this closes
+*
+* A misconfigured knob — a webhook tolerance, a lock horizon, a batch size — now refuses instead of
+* silently deleting the check it was part of (#521), and every one of those refusals carries an
+* `action` naming the variable an operator must fix. In a deployed Worker that `action` reached
+* nothing. `clientError` strips it on the way to the wire, which is correct and is the point; the
+* terminal renderer is a CLI surface no Worker runs; and the request produced exactly one record — the
+* access log line, `{"msg":"request","status":500}`. So the remedy existed and nobody could read it,
+* which is the unfollowable-action defect one layer out: not an action that does not help, an action
+* that does not arrive.
+*
+* ## Why it is here and not in the encoder
+*
+* `error/http.ts` is on the client side of the logger boundary and `logger/boundary.test.ts` gates
+* that: the three client/operator-facing error surfaces (`http.ts`, `terminal.ts`, `payload.ts`) must
+* not import the logger, so a record carrying `detail` cannot reach a response through them. That is a
+* deliberate decision, not an oversight, and the fix respects its direction rather than working around
+* it — the log is written on the internal side, and the encoder is imported *by* it. Nothing here can
+* put a log record into a response: {@link renderPithyError} takes the payload and this module never
+* touches the body.
+*
+* ## What lands
+*
+* One record, with the whole payload — `code`, `status`, `message`, `action`, `detail`. The logger
+* engine lifts a reserved `error` field into {@link import("./record").LogRecord.error}, so nothing
+* here formats or flattens anything; the fields the request logger already binds (`request`, `method`,
+* `path`, `env`, `version`) ride along, which is what makes the line correlatable with the access log
+* line beside it.
+*
+* **The client boundary does not move.** The response is byte-identical to what
+* `pithyErrorHandler` produced: `HttpError.encode` still runs through `clientError`, `action` and
+* `detail` are still stripped, and a forger still learns a status and a bland sentence. Both halves are
+* pinned in `errorHandler.test.ts` — the log carries the action, the wire body does not.
+*/
+/**
+* Level by status, and it is one branch on purpose.
+*
+* **5xx is ours.** `core/internal`, `core/upstream_failed`, `core/upstream_timeout`: the code means
+* *read our logs*, so the log is where it goes, at the level an operator's alerting already watches.
+*
+* **4xx is the caller's**, and it is already visible — the access log line beside this one carries its
+* status. Logging it at `error` would put an unauthenticated caller in charge of how much this Worker
+* writes, which is a bill and a haystack rather than a signal. It is still recorded, at `debug`, with
+* the identical payload: an operator chasing a 403 nobody can explain turns the level down and gets
+* every field, including the `action`, without a second code path existing to drift.
+*/
+function levelFor(status) {
+	return status >= 500 ? "error" : "debug";
+}
+/**
+* The fallback logger, built once, for an app that registers this handler without
+* `createBackend`'s base middleware — the email host's dev dispatch door, a hand-assembled Hono app.
+*
+* `noopLogger` would be the tidier default and it is the wrong one here: this handler exists so a
+* fault reaches a surface, and a fallback that reaches none is the defect with a new spelling. This is
+* the same CF-native adapter `createBackend` defaults to, minus the per-request correlation there is
+* nothing to derive it from.
+*/
+let fallback = null;
+/** The request's logger if one was bound, else the shared fallback. */
+function loggerFor(c) {
+	const bound = c.get("log");
+	if (bound) return bound;
+	fallback ??= createWorkerLogger();
+	return fallback;
+}
+/**
+* Hono `onError` handler: log the fault with its full payload, then render the public response.
+*
+* Register it once on the root app — `createBackend` already does. `pithyErrorHandler` remains the
+* bare encoder for an app that has no logger seam at all.
+*/
+function loggingErrorHandler(err, c) {
+	const pithy = toPithyError(err);
+	loggerFor(c)[levelFor(pithy.payload.status)]("request failed", { error: pithy });
+	return renderPithyError(pithy, c);
+}
+//#endregion
+export { loggingErrorHandler };

package/dist/naming/environment.js

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
-import { NAME_SEGMENT } from "./segment.js";
 import { PithyError, ValidationError } from "../error/pithyError.js";
+import { NAME_SEGMENT } from "./segment.js";
 import { z } from "zod";
 //#region src/naming/environment.ts
 /**

package/dist/naming/provisionScope.d.ts

@@ -19,7 +19,11 @@ import { type FeatureIdentity, type FeatureResourceKind } from "./feature";
  *
  * - {@link environmentScope} — a **declared** environment (`staging`, `prod`, whatever the root
  *   `pithy.config.ts` lists). Names are `<project>-<env>-<thing>`, the rule every other namer in the
- *   kit follows, so the environment segment of a name is always the stanza the name lives in.
+ *   kit follows, so the environment segment of a name is always the stanza the name lives in — unless
+ *   the thing being named is one the whole project shares, which a binding says with
+ *   {@link BindingNaming} and a secret with its registry, and which puts the literal `global` in that
+ *   slot instead. `global` is a scope beside the environments rather than one of them, so this is the
+ *   same statement and not an exception to it: the segment still says which scope owns the resource.
  * - {@link featureScope} — one branch's **ephemeral** environment. Names are
  *   `<project>-f<issue>-<slug>-<thing>`, with no environment segment because a feature *is* an
  *   environment, and the `f<issue>` marker is what teardown recomputes and what keeps a feature's
@@ -33,6 +37,43 @@ import { type FeatureIdentity, type FeatureResourceKind } from "./feature";
  * `SecretRegistryEntrySeam` types `backend` as a `string`.
  */
 export type SecretNameScope = "environment" | "global";
+/**
+ * What a binding's manifest says about the *name* of the resource behind it — the two fields of
+ * `BindingSpec` that a composed name reads, and nothing else.
+ *
+ * Structural rather than an import of `BindingSpec`, for the reason {@link SecretNameScope} is a literal
+ * union rather than an import of `SecretScope`: this module composes names and must not depend on the
+ * capability contract to do it. A caller with a whole spec passes the spec; a caller with neither field
+ * passes `{}`.
+ *
+ * **Both fields absent is the ordinary binding**, and it composes exactly what it always did:
+ * `<project>-<env>-<kebabbed binding>`.
+ */
+export interface BindingNaming {
+    /**
+     * `global` where one resource serves the whole project, absent or `environment` where each environment
+     * gets its own. See `BindingSpec.scope` — this is that field, and the reason it exists is that
+     * `EMAIL_SUPPRESSIONS` and `SECRETS` sit one line apart in the same env and no convention tells them
+     * apart.
+     */
+    readonly scope?: SecretNameScope;
+    /**
+     * The `<thing>` segment, where it is not the binding name. See `BindingSpec.resource` —
+     * `SUPPORT_BUCKET` backs `<project>-global-support`.
+     */
+    readonly resource?: string;
+}
+/**
+ * A {@link BindingNaming} that says `global` in its **type**, not only in its value.
+ *
+ * The distinction earns its keep at exactly one call: {@link bindingResourceName} needs a per-environment
+ * fallback from a writer filling in one stanza, and cannot need one from a capability's own namer, which
+ * has no environment to fall back to because its resource has none. Typing the declaration is what lets
+ * the compiler tell those two callers apart, so the namer omits an argument it could only have invented.
+ */
+export interface ProjectGlobalNaming extends BindingNaming {
+    readonly scope: "global";
+}
 /** Where a provisioning run's resources are named, and where their ids are written. */
 export interface ProvisionScope {
     /** The `env.<stanza>` key in each Worker's config that this scope's ids are written into. */
@@ -53,8 +94,30 @@ export interface ProvisionScope {
      * called?" and "which stanza does it go in?" — because those three answers have to agree.
      */
     readonly source: boolean;
-    /** This scope's Cloudflare name for a provisionable binding. */
-    resource(binding: string, kind: FeatureResourceKind): string;
+    /**
+     * This scope's Cloudflare name for a provisionable binding, given what the binding's manifest says
+     * about naming it.
+     *
+     * **The naming is required, not defaulted.** A caller with nothing to say passes `{}` and gets the
+     * name it always got; what it may not do is *omit* the question. `pithy add` and `pithy provision`
+     * both compose this name, from two different call paths, and the whole of #513 is that one of them
+     * had no way to hear "this resource is one per project" — so the app Worker bound three suppression
+     * databases where the email Worker bound one, and an unsubscribe on either was invisible to the other.
+     * A parameter with a default is a parameter a new call site inherits an answer to without ever
+     * reading the question.
+     */
+    resource(binding: string, kind: FeatureResourceKind, naming: BindingNaming): string;
+    /**
+     * Whether a binding that declares itself project-global is actually named that way here — and so
+     * belongs to the project rather than to this run.
+     *
+     * The asymmetry between the two scopes, stated by the object that implements it rather than inferred
+     * by a caller comparing two composed names. A declared environment honors `global` and shares the one
+     * resource; {@link featureScope} does not, so a feature's copy is the feature's own. A caller reading
+     * the manifest alone gets that backwards, and the way it goes wrong is silent: the feature's database
+     * is created, judged to be the project's, kept out of the teardown record, and orphaned.
+     */
+    readonly honorsGlobal: boolean;
     /** The script name a Worker deploys under in this scope. */
     worker(worker: string): string;
     /**
@@ -66,6 +129,35 @@ export interface ProvisionScope {
      */
     secretEntry(secret: string, secretScope: SecretNameScope): string;
 }
+/**
+ * The same branch, one line down, for a provisioned resource: a `global` binding resolves to the
+ * project's single `<project>-global-<thing>`, and everything else to the scope's own name for it.
+ *
+ * Written beside {@link secretEntryName} and shaped like it deliberately — the argument is the same
+ * argument. A value defined as one value must have one name, or the scoping mints a second copy of it;
+ * the only difference is that a secret's second copy is read and a database's is *written to*, which is
+ * why this one is the bug where an unsubscribe recorded in `staging` was invisible in `prod` (#513).
+ *
+ * `thing` is `naming.resource` when the manifest states one and the binding name otherwise. Either way
+ * it goes to the same composer, which kebabs it — so a binding passed verbatim keeps the name it has
+ * always had (`kebab("EMAIL_SUPPRESSIONS") === "email-suppressions"`), and this function cannot change
+ * what any existing spec composes.
+ *
+ * **Exported, because `pithy add` composes this name too and has no {@link ProvisionScope} to do it
+ * with.** It writes a `database_name` into a `wrangler.jsonc` stanza long before an account is reached,
+ * from a Worker's declared environment rather than a provisioning run's — and it is the writer that got
+ * #513 wrong. Handing it the scoped name as a callback is what lets the *global* branch live here once:
+ * a second copy of it in the writer is the arrangement this issue exists to end.
+ *
+ * **And exported for the third writer, which is the capability's own namer.** `suppressionDatabaseName`
+ * and `supportBucketName` name the same two resources their manifests declare, and they composed them
+ * with a second expression until #513 — which is how `<project>-global-email-suppressions` and
+ * `<project>-staging-email-suppressions` came to be the same database under two names. They pass a
+ * {@link ProjectGlobalNaming} and no callback: a namer for a project-global resource has no environment,
+ * so there is no scoped name for it to supply and the overload will not let it pretend otherwise.
+ */
+export declare function bindingResourceName(project: string, binding: string, kind: FeatureResourceKind, naming: ProjectGlobalNaming): string;
+export declare function bindingResourceName(project: string, binding: string, kind: FeatureResourceKind, naming: BindingNaming, scoped: (thing: string) => string): string;
 /**
  * A declared environment's scope — `staging`, `prod`, or whatever the root `pithy.config.ts` lists.
  *
@@ -88,6 +180,19 @@ export declare function environmentScope(project: string, environment: string):
  *
  * Its stanza is {@link FEATURE_ENVIRONMENT} and nothing else, which is what makes a feature's resources
  * in a declared environment's stanza unexpressible rather than merely discouraged.
+ *
+ * **A feature takes a binding's {@link BindingNaming} and ignores it — and that is the asymmetry against
+ * `secretEntry` one line below, which honors `global` here as everywhere.** A global *secret* is a value
+ * defined once for the project, so a feature binds the project's copy rather than minting a second: it is
+ * **read**. A global *database* is a resource a feature would **migrate** — `provisionFeature` runs
+ * `pithy migrate` against everything it names — so honoring `global` here would point one branch's
+ * schema changes at the project's live suppression list, and point teardown at it afterwards. A feature
+ * owns every resource it names, exactly so that destroying the feature destroys them all; there is no
+ * shared name to match and nothing for teardown to spare.
+ *
+ * `resource` is ignored for the same reason it is moot: a feature's `<thing>` segment is the binding plus
+ * the kind, and the whole name is recomputed on teardown rather than looked up, so nothing outside the
+ * feature reads the string.
  */
 export declare function featureScope(identity: FeatureIdentity): ProvisionScope;
 //# sourceMappingURL=provisionScope.d.ts.map

package/dist/naming/provisionScope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provisionScope.d.ts","sourceRoot":"","sources":["../../src/naming/provisionScope.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EAIzB,MAAM,WAAW,CAAC;AAGnB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,QAAQ,CAAC;AAEvD,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B,6FAA6F;IAC7F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAAC;IAC7D,4DAA4D;IAC5D,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B;;;;;;OAMG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,eAAe,GAAG,MAAM,CAAC;CACnE;AAiBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,cAAc,CAYrF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,cAAc,CAUtE"}
+{"version":3,"file":"provisionScope.d.ts","sourceRoot":"","sources":["../../src/naming/provisionScope.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EAIzB,MAAM,WAAW,CAAC;AAGnB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,QAAQ,CAAC;AAEvD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAoB,SAAQ,aAAa;IACxD,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;CAC1B;AAED,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B,6FAA6F;IAC7F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,aAAa,GAAG,MAAM,CAAC;IACpF;;;;;;;;;OASG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,4DAA4D;IAC5D,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B;;;;;;OAMG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,eAAe,GAAG,MAAM,CAAC;CACnE;AAiBD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,mBAAmB,EACzB,MAAM,EAAE,mBAAmB,GAC1B,MAAM,CAAC;AACV,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,mBAAmB,EACzB,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAChC,MAAM,CAAC;AAsBV;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,cAAc,CAerF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,cAAc,CAatE"}

package/dist/naming/provisionScope.js

@@ -1,5 +1,6 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
+import { InternalError } from "../error/pithyError.js";
 import { FEATURE_ENVIRONMENT, assertValidEnvironment } from "./environment.js";
 import { featureResourceName, featureSecretEntryName, featureWorkerName } from "./feature.js";
 import { resourceNames } from "./resourceNames.js";
@@ -21,6 +22,15 @@ function secretEntryName(project, secret, secretScope, scoped) {
 	if (secretScope === "global") return resourceNames(project).global.secretEntry(secret);
 	return scoped();
 }
+function bindingResourceName(project, binding, kind, naming, scoped) {
+	const thing = naming.resource ?? binding;
+	if (naming.scope === "global") return resourceNames(project).global[KIND_NAMER[kind]](thing);
+	if (scoped === void 0) throw new InternalError({
+		message: "A resource name could not be composed.",
+		detail: `bindingResourceName was asked for a scoped name for "${binding}" with no scope to compose it in. Pass the environment's composer, or declare the binding \`scope: "global"\`.`
+	});
+	return scoped(thing);
+}
 /**
 * A declared environment's scope — `staging`, `prod`, or whatever the root `pithy.config.ts` lists.
 *
@@ -42,7 +52,8 @@ function environmentScope(project, environment) {
 	return {
 		stanza: environment,
 		source: true,
-		resource: (binding, kind) => names[KIND_NAMER[kind]](binding),
+		honorsGlobal: true,
+		resource: (binding, kind, naming) => bindingResourceName(project, binding, kind, naming, (thing) => names[KIND_NAMER[kind]](thing)),
 		worker: (worker) => `${worker}-${environment}`,
 		secretEntry: (secret, secretScope) => secretEntryName(project, secret, secretScope, () => names.secretEntry(secret))
 	};
@@ -53,15 +64,29 @@ function environmentScope(project, environment) {
 *
 * Its stanza is {@link FEATURE_ENVIRONMENT} and nothing else, which is what makes a feature's resources
 * in a declared environment's stanza unexpressible rather than merely discouraged.
+*
+* **A feature takes a binding's {@link BindingNaming} and ignores it — and that is the asymmetry against
+* `secretEntry` one line below, which honors `global` here as everywhere.** A global *secret* is a value
+* defined once for the project, so a feature binds the project's copy rather than minting a second: it is
+* **read**. A global *database* is a resource a feature would **migrate** — `provisionFeature` runs
+* `pithy migrate` against everything it names — so honoring `global` here would point one branch's
+* schema changes at the project's live suppression list, and point teardown at it afterwards. A feature
+* owns every resource it names, exactly so that destroying the feature destroys them all; there is no
+* shared name to match and nothing for teardown to spare.
+*
+* `resource` is ignored for the same reason it is moot: a feature's `<thing>` segment is the binding plus
+* the kind, and the whole name is recomputed on teardown rather than looked up, so nothing outside the
+* feature reads the string.
 */
 function featureScope(identity) {
 	return {
 		stanza: FEATURE_ENVIRONMENT,
 		source: false,
+		honorsGlobal: false,
 		resource: (binding, kind) => featureResourceName(identity, binding, kind),
 		worker: (worker) => featureWorkerName(identity, worker),
 		secretEntry: (secret, secretScope) => secretEntryName(identity.project, secret, secretScope, () => featureSecretEntryName(identity, secret))
 	};
 }
 //#endregion
-export { environmentScope, featureScope };
+export { bindingResourceName, environmentScope, featureScope };

package/dist/naming/resource.js

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

package/dist/naming/resourceNames.js

@@ -4,8 +4,8 @@ import { InternalError, ValidationError } from "../error/pithyError.js";
 import { GLOBAL_SCOPE, assertValidEnvironment } from "./environment.js";
 import { NAMESPACE_LIMITS } from "./limits.js";
 import { assertValidProjectName, kebab, resourceName } from "./resource.js";
-import { workflowHostName, workflowScriptName } from "../workflow/naming.js";
 import { featureResourceName, featureWorkerName } from "./feature.js";
+import { workflowHostName, workflowScriptName } from "../workflow/naming.js";
 //#region src/naming/resourceNames.ts
 /**
 * Compose `<project>-<scope>-<thing>` under one namespace's rule.

package/dist/schema/describedness.d.ts

@@ -1,6 +1,8 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 import { z } from "zod";
+/** The kind tag Zod puts on a schema's definition. */
+export declare function kindOf(schema: z.ZodType): string;
 /**
  * The children of one schema, by kind. **Throws for a kind this walk has never been taught** — a
  * walker whose unknown case is silently empty cannot report the thing it exists to report.
@@ -15,13 +17,40 @@ import { z } from "zod";
  */
 export declare function childSchemas(schema: z.ZodType, path: string): z.ZodType[];
 /**
- * Whether a description sits anywhere in a field's transparent-wrapper chain.
+ * The description documenting a field, from anywhere in its transparent-wrapper chain.
  *
  * `.describe("…").optional()` puts it on the inner type and `.optional().describe("…")` puts it on the
  * wrapper. Both are one described field. Only {@link TRANSPARENT} wrappers are followed — an `array`
  * or a `pipe` describes something other than what it holds.
+ *
+ * The **words**, and not only whether there are any, because the descriptions are the object model's
+ * documentation (CLAUDE.md §Zod) and a surface that shows them to a human — `pithy secrets create`
+ * asking for one field at a time — needs the same chain the gate walks. Two walks of one chain is how
+ * a field renders undocumented in a prompt while the meta-test calls it described.
  */
+export declare function descriptionInChain(schema: z.ZodType): string | undefined;
+/** Whether a description sits anywhere in a field's transparent-wrapper chain. See {@link descriptionInChain}. */
 export declare function describedInChain(schema: z.ZodType): boolean;
+/** One field of an object, with its transparent wrappers taken off. See {@link unwrapField}. */
+export interface UnwrappedField {
+    /** What the field actually is, once `.optional()` and the rest of {@link TRANSPARENT} are removed. */
+    schema: z.ZodType;
+    /** Whether the field may be left out of the object entirely — an `optional`, `default` or `prefault`. */
+    optional: boolean;
+    /** The description documenting it, from anywhere in the chain. See {@link descriptionInChain}. */
+    description?: string;
+}
+/**
+ * One field, unwrapped: what it is, whether it may be omitted, and the words that document it.
+ *
+ * **The unwrapping half of this walk, exported rather than copied.** `collectMissing` already steps
+ * through {@link TRANSPARENT} on its way down, and a caller asking *what is this field* asks exactly
+ * that question — so it asks it here. The nineteen private copies this module replaced all started as
+ * one function that looked too small to share.
+ *
+ * `nullable` is not omissible: `null` is a value a caller states, and the key is still required.
+ */
+export declare function unwrapField(schema: z.ZodType, path?: string): UnwrappedField;
 /** What one walk found: the complaints, and how much it actually looked at. */
 export interface SchemaWalk {
     /** One line per object, enum, union or field with no `.describe()` anywhere that documents it. */

package/dist/schema/describedness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"describedness.d.ts","sourceRoot":"","sources":["../../src/schema/describedness.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgGxB;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,CAsCzE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,OAAO,CAU3D;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,kGAAkG;IAClG,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,yFAAyF;IACzF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,CAAC,CAAC,OAAO,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,EACpB,SAAS,UAAQ,GAChB,IAAI,CAsBN;AAED,mEAAmE;AACnE,wBAAgB,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,SAAW,GAAG,UAAU,CAI1E;AAED,sFAAsF;AACtF,MAAM,WAAW,UAAW,SAAQ,UAAU;IAC5C,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,UAAU,CAY/F"}
+{"version":3,"file":"describedness.d.ts","sourceRoot":"","sources":["../../src/schema/describedness.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAsCxB,sDAAsD;AACtD,wBAAgB,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,MAAM,CAEhD;AAuDD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,CAsCzE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,MAAM,GAAG,SAAS,CAUxE;AAED,kHAAkH;AAClH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,OAAO,CAE3D;AAED,gGAAgG;AAChG,MAAM,WAAW,cAAc;IAC7B,sGAAsG;IACtG,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAClB,yGAAyG;IACzG,QAAQ,EAAE,OAAO,CAAC;IAClB,kGAAkG;IAClG,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,SAAW,GAAG,cAAc,CAa9E;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,kGAAkG;IAClG,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,yFAAyF;IACzF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,CAAC,CAAC,OAAO,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,EACpB,SAAS,UAAQ,GAChB,IAAI,CAsBN;AAED,mEAAmE;AACnE,wBAAgB,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,SAAW,GAAG,UAAU,CAI1E;AAED,sFAAsF;AACtF,MAAM,WAAW,UAAW,SAAQ,UAAU;IAC5C,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,UAAU,CAY/F"}

package/dist/schema/describedness.js

@@ -101,22 +101,58 @@ function childSchemas(schema, path) {
 	}
 }
 /**
-* Whether a description sits anywhere in a field's transparent-wrapper chain.
+* The description documenting a field, from anywhere in its transparent-wrapper chain.
 *
 * `.describe("…").optional()` puts it on the inner type and `.optional().describe("…")` puts it on the
 * wrapper. Both are one described field. Only {@link TRANSPARENT} wrappers are followed — an `array`
 * or a `pipe` describes something other than what it holds.
+*
+* The **words**, and not only whether there are any, because the descriptions are the object model's
+* documentation (CLAUDE.md §Zod) and a surface that shows them to a human — `pithy secrets create`
+* asking for one field at a time — needs the same chain the gate walks. Two walks of one chain is how
+* a field renders undocumented in a prompt while the meta-test calls it described.
 */
-function describedInChain(schema) {
+function descriptionInChain(schema) {
 	let current = schema;
 	const seen = /* @__PURE__ */ new Set();
 	while (current && !seen.has(current)) {
-		if (current.description) return true;
-		if (!TRANSPARENT.has(kindOf(current))) return false;
+		if (current.description) return current.description;
+		if (!TRANSPARENT.has(kindOf(current))) return void 0;
 		seen.add(current);
 		current = current.def?.innerType;
 	}
-	return false;
+}
+/** Whether a description sits anywhere in a field's transparent-wrapper chain. See {@link descriptionInChain}. */
+function describedInChain(schema) {
+	return descriptionInChain(schema) !== void 0;
+}
+/**
+* One field, unwrapped: what it is, whether it may be omitted, and the words that document it.
+*
+* **The unwrapping half of this walk, exported rather than copied.** `collectMissing` already steps
+* through {@link TRANSPARENT} on its way down, and a caller asking *what is this field* asks exactly
+* that question — so it asks it here. The nineteen private copies this module replaced all started as
+* one function that looked too small to share.
+*
+* `nullable` is not omissible: `null` is a value a caller states, and the key is still required.
+*/
+function unwrapField(schema, path = "schema") {
+	const description = descriptionInChain(schema);
+	let current = schema;
+	let optional = false;
+	const seen = /* @__PURE__ */ new Set();
+	while (TRANSPARENT.has(kindOf(current)) && !seen.has(current)) {
+		if (kindOf(current) !== "nullable" && kindOf(current) !== "readonly") optional = true;
+		seen.add(current);
+		const inner = childSchemas(current, path)[0];
+		if (!inner) break;
+		current = inner;
+	}
+	return {
+		schema: current,
+		optional,
+		...description === void 0 ? {} : { description }
+	};
 }
 /**
 * Record any object/enum/union missing a `.describe()` — on the schema itself or on any of its
@@ -179,4 +215,4 @@ function undescribedExports(modules) {
 	};
 }
 //#endregion
-export { childSchemas, collectMissing, describedInChain, undescribed, undescribedExports };
+export { childSchemas, collectMissing, describedInChain, descriptionInChain, kindOf, undescribed, undescribedExports, unwrapField };

package/dist/test-utils/oidcFixtures.d.ts

@@ -0,0 +1,93 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { OidcJwk, OidcJwksFetch } from "../http/oidcWebhook";
+/**
+ * The identity provider's half of the protocol `requireOidcWebhook` verifies: mint a signing key,
+ * publish it as a JWKS, and sign tokens with it.
+ *
+ * **Why it ships rather than staying private to the kit's own suite.** A route guarded by
+ * `requireOidcWebhook` can only be tested by presenting a token the
+ * guard accepts, and building one means WebCrypto key generation, base64url without padding, a compact
+ * JWS, and a transport that publishes the public half. That came to 103 lines the first time an adopter
+ * wrote it, none of it adopter-specific — and a hand-rolled copy is **a second definition of the wire
+ * format**, which is the argument this repository already makes about signers. It can agree with itself
+ * and disagree with the verifier. The first copy did: its fake transport returned `json()` where
+ * {@link OidcJwksResponse} declares `text()`, so every delivery 502'd from a fixture that looked right.
+ * Here that is unrepresentable — {@link publishing} is typed as the seam, so a `json()` is a red build
+ * rather than a wrong answer at runtime.
+ *
+ * **Real WebCrypto, never a stubbed signature.** Every negative case an adopter writes with these is a
+ * token somebody really signed — the impostor key, the wrong `kid`, the tampered claims. A hand-rolled
+ * key and a hand-rolled signature would let every signature assertion pass by agreeing with itself.
+ *
+ * **What is deliberately not here.** No helper that builds a *provider's* claims: GitHub's
+ * `repo:owner/name:environment:x` is the adopter's business and differs per provider, so claims stay a
+ * plain object the test writes. And no algorithm-confusion forgery — that proves a property of the kit's
+ * verifier, which the kit tests, rather than of an adopter's route.
+ *
+ * `oidcFixtures.test.ts` holds all of this to the real `verifyOidcToken`:
+ * a token it accepts, and one it refuses for each reason. That is what keeps the fixture and the verifier
+ * from drifting apart while both stay green.
+ */
+/** A minted signing key: the JWK a verifier is given, and the private half a test signs with. */
+export interface MintedKey {
+    /** The key id, matched against a token header's `kid`. */
+    kid: string;
+    /** The public key as a JWK, in the shape a JWKS endpoint publishes it. */
+    jwk: OidcJwk;
+    /** The private half. What signs a token. */
+    privateKey: CryptoKey;
+}
+/**
+ * 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.
+ */
+export declare function mintKey(kid: string): Promise<MintedKey>;
+/**
+ * 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.
+ */
+export declare function base64Url(bytes: Uint8Array): string;
+/**
+ * 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.
+ */
+export declare function signToken(payload: unknown, signer: MintedKey, header?: Record<string, unknown>): Promise<string>;
+/**
+ * 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.
+ */
+export declare function publishing(jwksUrl: string, keys: readonly OidcJwk[], seen?: string[]): OidcJwksFetch;
+//# sourceMappingURL=oidcFixtures.d.ts.map

package/dist/test-utils/oidcFixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oidcFixtures.d.ts","sourceRoot":"","sources":["../../src/test-utils/oidcFixtures.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAoB,MAAM,qBAAqB,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,iGAAiG;AACjG,MAAM,WAAW,SAAS;IACxB,0DAA0D;IAC1D,GAAG,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,GAAG,EAAE,OAAO,CAAC;IACb,4CAA4C;IAC5C,UAAU,EAAE,SAAS,CAAC;CACvB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAiB7D;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAInD;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,SAAS,EACjB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,OAAO,EAAE,EAAE,IAAI,GAAE,MAAM,EAAO,GAAG,aAAa,CAMxG"}