@pithy-sh/core 0.1.5 → 0.3.0

package/src/http/signedWebhook.ts

@@ -4,6 +4,9 @@
 import type { MiddlewareHandler } from "hono";
 import type { PithyHonoEnv } from "../capability/capability";
 import { InternalError, WebhookUnverifiedError } from "../error/pithyError";
+// The bounds live in a leaf so a browser-facing config schema can quote them without reaching this
+// middleware's Worker graph (#521). See `webhookWindow.ts`.
+import { SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS, SIGNED_WEBHOOK_TOLERANCE_SECONDS } from "./webhookWindow";
 
 /**
  * The `signed-webhook` strategy, for any sender. Secret, header name, tolerance and the exact received
@@ -43,6 +46,11 @@ import { InternalError, WebhookUnverifiedError } from "../error/pithyError";
  * crafted one, and neither is a delivery to act on; accepting it would also hand a forger an unbounded replay
  * window the moment a secret leaks.
  *
+ * The window's own width is checked before any delivery is. `skew > tolerance` is false when `tolerance` is
+ * `NaN`, so a non-finite tolerance does not widen the window — it deletes it, and every capture verifies
+ * forever. A tolerance outside `0 … {@link SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS}` is therefore refused as the
+ * configuration fault it is, never honored and never clamped.
+ *
  * ## Why the comparison is `crypto.subtle.verify`
  *
  * Comparing HMACs with `===` leaks how many leading bytes matched, and that leak is enough to forge a
@@ -66,9 +74,6 @@ import { InternalError, WebhookUnverifiedError } from "../error/pithyError";
  * kit's error.
  */
 
-/** How far a delivery's own timestamp may be from now. Stripe's default, and generous against clock skew. */
-export const SIGNED_WEBHOOK_TOLERANCE_SECONDS = 300;
-
 /** The header key naming the timestamp, unless a sender names it otherwise. */
 const DEFAULT_TIMESTAMP_KEY = "t";
 
@@ -103,7 +108,12 @@ export interface SignedWebhookScheme {
   timestampKey?: string;
   /** The header key holding a signature. Defaults to `v1`. */
   signatureKey?: string;
-  /** The freshness window, in seconds, either side of now. Defaults to {@link SIGNED_WEBHOOK_TOLERANCE_SECONDS}. */
+  /**
+   * The freshness window, in seconds, either side of now. Defaults to {@link SIGNED_WEBHOOK_TOLERANCE_SECONDS}
+   * and must be a finite number from 0 to {@link SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS}; anything else is
+   * `core/internal`, because this is the second operand of the freshness comparison and one `NaN` does not
+   * widen the window, it removes it.
+   */
   toleranceSeconds?: number;
 }
 
@@ -225,8 +235,9 @@ export type SignedWebhookRefusal =
  * each caller keeps its vocabulary, rather than the whole verifier existing twice with two sets of comments
  * to keep in step. Most callers want {@link verifySignedWebhook}.
  *
- * It still throws for **our** failure: an endpoint holding no usable secret, or handed a clock that is not a
- * clock, is a configuration fault rather than a refusal, and every caller reports that the same way.
+ * It still throws for **our** failure: an endpoint holding no usable secret, given a tolerance that is not a
+ * window, or handed a clock that is not a clock, is a configuration fault rather than a refusal, and every
+ * caller reports that the same way. Those three are checked first, before anything the sender wrote.
  *
  * `body` must be the **exact received bytes**. A parsed-and-re-serialized object is different bytes — key
  * order alone changes it — and would never verify.
@@ -252,18 +263,29 @@ export async function checkSignedWebhook(
     });
   }
 
-  const timestampKey = options.timestampKey ?? DEFAULT_TIMESTAMP_KEY;
-  const signatureKey = options.signatureKey ?? DEFAULT_SIGNATURE_KEY;
-  const parsed = header === null ? undefined : parseSignedWebhookHeader(header, timestampKey, signatureKey);
-  if (parsed === undefined) return { reason: "unreadable" };
-
+  // The freshness window is a comparison between two numbers a caller supplies, and **either** of them
+  // non-finite does not widen it — it removes it, because `NaN > x` and `x > NaN` are both false. So both are
+  // checked here, beside the empty secret, before a byte the sender wrote is read: a configuration fault must
+  // be the same answer whatever arrived, rather than one that surfaces only on a delivery well-formed enough
+  // to reach the comparison.
   const tolerance = options.toleranceSeconds ?? SIGNED_WEBHOOK_TOLERANCE_SECONDS;
+  // The realistic source is not a hostile caller — it is a route reading `Number(env.WEBHOOK_TOLERANCE)` for a
+  // variable nobody set or somebody misspelled. TypeScript types that `number`, every layer between passes it
+  // on with `??` (which catches `undefined`, never `NaN`), and nothing downstream looks again. The upper bound
+  // is the same argument as the constant it defaults to: a tolerance is a replay window, so it is configuration
+  // that has to be small, not merely present.
+  if (!Number.isFinite(tolerance) || tolerance < 0 || tolerance > SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS) {
+    throw new InternalError({
+      message: "This webhook endpoint is not configured.",
+      action: `Give the ${options.header} guard a tolerance between 0 and ${SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS} seconds.`,
+      detail: `The signed-webhook guard on ${options.header} was given a tolerance of ${String(tolerance)} seconds, and a freshness window must be a number from 0 to ${SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS}.`,
+    });
+  }
   const nowSeconds = Math.floor((options.now ?? new Date()).getTime() / 1000);
-  // Fail closed on a clock that is not one. `Math.abs(NaN - t) > tolerance` is false, so an invalid Date would
-  // pass the window silently — the one check in this file that could fail open, in the file whose whole
-  // argument is that it fails closed. Comparing against a sentinel instead would still be a comparison against
-  // a number nobody chose. Only a caller-supplied `now` reaches here as NaN: the header's timestamp is a
-  // digit-checked string before it is a number, so this is our fault and takes our code, like the secret above.
+  // The other operand, and the same fault one field over. `Math.abs(NaN - t) > tolerance` is false, so an
+  // invalid Date passes a delivery of any age. Comparing against a sentinel instead would still be a comparison
+  // against a number nobody chose. Only a caller-supplied `now` reaches here as NaN: the header's timestamp is
+  // a digit-checked string before it is a number, so this is our fault and takes our code, like the two above.
   if (!Number.isFinite(nowSeconds)) {
     throw new InternalError({
       message: "This webhook endpoint is not configured.",
@@ -271,6 +293,12 @@ export async function checkSignedWebhook(
       detail: `The signed-webhook guard on ${options.header} was handed a clock that is not a valid Date, so no delivery's freshness can be judged.`,
     });
   }
+
+  const timestampKey = options.timestampKey ?? DEFAULT_TIMESTAMP_KEY;
+  const signatureKey = options.signatureKey ?? DEFAULT_SIGNATURE_KEY;
+  const parsed = header === null ? undefined : parseSignedWebhookHeader(header, timestampKey, signatureKey);
+  if (parsed === undefined) return { reason: "unreadable" };
+
   const skew = Math.abs(nowSeconds - parsed.timestamp);
   if (skew > tolerance) return { reason: "stale", skew, tolerance };
 

package/src/http/webhookWindow.ts

@@ -0,0 +1,35 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * 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. */
+export 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.
+ */
+export const SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS = 3600;

package/src/logger/errorHandler.ts

@@ -0,0 +1,94 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Context } from "hono";
+import { renderPithyError, toPithyError } from "../error/http";
+import type { Logger } from "./logger";
+import { createWorkerLogger } from "./worker";
+
+/**
+ * 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: number): "debug" | "error" {
+  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: Logger | null = null;
+
+/** The request's logger if one was bound, else the shared fallback. */
+function loggerFor(c: Context): Logger {
+  const bound: unknown = (c as Context<{ Variables: { log?: Logger } }>).get("log");
+  if (bound) return bound as Logger;
+  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.
+ */
+export function loggingErrorHandler(err: Error, c: Context): Response {
+  const pithy = toPithyError(err);
+  // The same object the response is rendered from, so the record and the body can never describe two
+  // different faults. `error` is the reserved field the engine lifts — `action` and `detail` included.
+  loggerFor(c)[levelFor(pithy.payload.status)]("request failed", { error: pithy });
+  return renderPithyError(pithy, c);
+}

package/src/naming/provisionScope.ts

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 
+import { InternalError } from "../error/pithyError";
 import { assertValidEnvironment, FEATURE_ENVIRONMENT, GLOBAL_SCOPE } from "./environment";
 import {
   type FeatureIdentity,
@@ -29,7 +30,11 @@ import { resourceNames } from "./resourceNames";
  *
  * - {@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
@@ -45,6 +50,45 @@ import { resourceNames } from "./resourceNames";
  */
 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. */
@@ -65,8 +109,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;
   /**
@@ -94,6 +160,67 @@ function secretEntryName(project: string, secret: string, secretScope: SecretNam
   return scoped();
 }
 
+/**
+ * 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 function bindingResourceName(
+  project: string,
+  binding: string,
+  kind: FeatureResourceKind,
+  naming: ProjectGlobalNaming,
+): string;
+export function bindingResourceName(
+  project: string,
+  binding: string,
+  kind: FeatureResourceKind,
+  naming: BindingNaming,
+  scoped: (thing: string) => string,
+): string;
+export function bindingResourceName(
+  project: string,
+  binding: string,
+  kind: FeatureResourceKind,
+  naming: BindingNaming,
+  scoped?: (thing: string) => string,
+): string {
+  const thing = naming.resource ?? binding;
+  if (naming.scope === GLOBAL_SCOPE) return resourceNames(project).global[KIND_NAMER[kind]](thing);
+  // The second wall behind the overloads, not the first. A caller with no environment reaching a naming
+  // that is not `global` has nothing this function could compose, and the honest answer is to say so
+  // rather than return a name with a segment nobody chose.
+  if (scoped === undefined) {
+    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.
  *
@@ -116,7 +243,10 @@ export function environmentScope(project: string, environment: string): Provisio
     stanza: environment,
     // Long-lived ids for an environment the project ships to: reviewed, committed, kept.
     source: true,
-    resource: (binding, kind) => names[KIND_NAMER[kind]](binding),
+    // A declared environment is one of the scopes a project-global resource is shared *between*.
+    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)),
@@ -129,12 +259,28 @@ export function environmentScope(project: string, environment: string): Provisio
  *
  * 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 function featureScope(identity: FeatureIdentity): ProvisionScope {
   return {
     stanza: FEATURE_ENVIRONMENT,
     // One job's ids, for resources `destroy` deletes. Never a tracked file.
     source: false,
+    // A feature owns every resource it names — see the docstring above for why a database and a secret
+    // part company here.
+    honorsGlobal: false,
     resource: (binding, kind) => featureResourceName(identity, binding, kind),
     worker: (worker) => featureWorkerName(identity, worker),
     secretEntry: (secret, secretScope) =>

package/src/schema/describedness.ts

@@ -40,7 +40,7 @@ interface Def {
 }
 
 /** The kind tag Zod puts on a schema's definition. */
-function kindOf(schema: z.ZodType): string {
+export function kindOf(schema: z.ZodType): string {
   return (schema as unknown as { def: Def }).def.type;
 }
 
@@ -150,22 +150,67 @@ export 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 function describedInChain(schema: z.ZodType): boolean {
+export function descriptionInChain(schema: z.ZodType): string | undefined {
   let current: z.ZodType | undefined = schema;
   const seen = new Set<z.ZodType>();
   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 undefined;
     seen.add(current);
     current = (current as unknown as { def?: { innerType?: z.ZodType } }).def?.innerType;
   }
-  return false;
+  return undefined;
+}
+
+/** Whether a description sits anywhere in a field's transparent-wrapper chain. See {@link descriptionInChain}. */
+export function describedInChain(schema: z.ZodType): boolean {
+  return descriptionInChain(schema) !== undefined;
+}
+
+/** 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 function unwrapField(schema: z.ZodType, path = "schema"): UnwrappedField {
+  const description = descriptionInChain(schema);
+  let current = schema;
+  let optional = false;
+  const seen = new Set<z.ZodType>();
+  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 === undefined ? {} : { description }) };
 }
 
 /** What one walk found: the complaints, and how much it actually looked at. */