@pithy-sh/core 0.1.2 → 0.1.4

package/dist/address/address.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Email addresses: the one rule for deciding whether two strings are the same person.
+ *
+ * Four capabilities compare addresses. `auth` matches a sign-in address, `email` suppresses one,
+ * `support` links a sender by `From`, and `testers` invites one. Four rules is four chances to
+ * disagree, and a disagreement here does not present as anything about addresses — it presents as "the
+ * suppression list did not work", or as one customer with two support threads, or as an invitation
+ * nobody can accept because it was minted against `Ada@` and every session carries `ada@`.
+ *
+ * So the rule is written down once, here, and it is deliberately small.
+ *
+ * ## What it normalizes
+ *
+ * - **Surrounding whitespace.** Trimmed. An address pasted out of a spreadsheet carries it.
+ * - **Case, in both halves.** RFC 5321 says the local part is case-sensitive; no mail provider in
+ *   practice treats it that way, and treating `Ada@` and `ada@` as two people splits one customer's
+ *   history in half. The failure the other way — two genuinely distinct mailboxes differing only in
+ *   case — does not exist in the wild.
+ *
+ * ## What it deliberately does not
+ *
+ * - **Subaddressing (`ada+shop@`) and dots in the local part.** Gmail collapses both. Most providers do
+ *   not, and folding them would merge two real people on a self-hosted domain. Showing one customer as
+ *   two is recoverable; showing two customers as one is not.
+ * - **Unicode normalization.** No NFC, no NFKC, no case folding beyond `toLowerCase`. NFKC in
+ *   particular maps distinct codepoints onto ASCII, which is exactly how one address comes to match
+ *   another that was never issued to the same person — the confusable-domain attack, performed by us,
+ *   on our own comparison. An address whose bytes differ stays a different address.
+ * - **Validation.** {@link normalizeAddress} takes any string and returns its normal form. Whether a
+ *   string *is* an address is a question for the boundary that accepted it — Zod, or {@link
+ *   parseAddress} where the input is a mail header. A normalizer that also rejects is a normalizer
+ *   whose callers stop calling it.
+ * - **IDN / punycode.** A unicode domain is not converted to its `xn--` form, or back. Both spellings
+ *   are stable under this rule; a project that accepts one must accept only one, at its boundary.
+ */
+/** The longest address accepted. RFC 5321 caps a path at 256 octets; anything longer is malformed. */
+export declare const MAX_ADDRESS_LENGTH = 256;
+/**
+ * One address, in the one form every comparison in the kit is against.
+ *
+ * Trimmed and lowercased, and nothing else. Total: every string has a normal form, including the ones
+ * that are not addresses. Use {@link parseAddress} where the input is attacker-supplied text that may
+ * not contain an address at all.
+ */
+export declare function normalizeAddress(value: string): string;
+/**
+ * Read one address out of a header-shaped string, or refuse.
+ *
+ * Unwraps `Ada Lovelace <ada@example.com>`, bounds the length, refuses anything that is not
+ * recognizably a single address, and returns it through {@link normalizeAddress}.
+ *
+ * Returns `undefined` rather than throwing. Inbound mail is attacker-controlled, so a malformed `From`
+ * is an expected input, not an exception — the caller decides whether that means "drop the message" or
+ * "store it with no sender", and both are reasonable.
+ */
+export declare function parseAddress(value: string | null | undefined): string | undefined;
+//# sourceMappingURL=address.d.ts.map

package/dist/address/address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.d.ts","sourceRoot":"","sources":["../../src/address/address.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,sGAAsG;AACtG,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAmBjF"}

package/dist/address/address.js

@@ -0,0 +1,71 @@
+//#region src/address/address.ts
+/**
+* Email addresses: the one rule for deciding whether two strings are the same person.
+*
+* Four capabilities compare addresses. `auth` matches a sign-in address, `email` suppresses one,
+* `support` links a sender by `From`, and `testers` invites one. Four rules is four chances to
+* disagree, and a disagreement here does not present as anything about addresses — it presents as "the
+* suppression list did not work", or as one customer with two support threads, or as an invitation
+* nobody can accept because it was minted against `Ada@` and every session carries `ada@`.
+*
+* So the rule is written down once, here, and it is deliberately small.
+*
+* ## What it normalizes
+*
+* - **Surrounding whitespace.** Trimmed. An address pasted out of a spreadsheet carries it.
+* - **Case, in both halves.** RFC 5321 says the local part is case-sensitive; no mail provider in
+*   practice treats it that way, and treating `Ada@` and `ada@` as two people splits one customer's
+*   history in half. The failure the other way — two genuinely distinct mailboxes differing only in
+*   case — does not exist in the wild.
+*
+* ## What it deliberately does not
+*
+* - **Subaddressing (`ada+shop@`) and dots in the local part.** Gmail collapses both. Most providers do
+*   not, and folding them would merge two real people on a self-hosted domain. Showing one customer as
+*   two is recoverable; showing two customers as one is not.
+* - **Unicode normalization.** No NFC, no NFKC, no case folding beyond `toLowerCase`. NFKC in
+*   particular maps distinct codepoints onto ASCII, which is exactly how one address comes to match
+*   another that was never issued to the same person — the confusable-domain attack, performed by us,
+*   on our own comparison. An address whose bytes differ stays a different address.
+* - **Validation.** {@link normalizeAddress} takes any string and returns its normal form. Whether a
+*   string *is* an address is a question for the boundary that accepted it — Zod, or {@link
+*   parseAddress} where the input is a mail header. A normalizer that also rejects is a normalizer
+*   whose callers stop calling it.
+* - **IDN / punycode.** A unicode domain is not converted to its `xn--` form, or back. Both spellings
+*   are stable under this rule; a project that accepts one must accept only one, at its boundary.
+*/
+/** The longest address accepted. RFC 5321 caps a path at 256 octets; anything longer is malformed. */
+const MAX_ADDRESS_LENGTH = 256;
+/**
+* One address, in the one form every comparison in the kit is against.
+*
+* Trimmed and lowercased, and nothing else. Total: every string has a normal form, including the ones
+* that are not addresses. Use {@link parseAddress} where the input is attacker-supplied text that may
+* not contain an address at all.
+*/
+function normalizeAddress(value) {
+	return value.trim().toLowerCase();
+}
+/**
+* Read one address out of a header-shaped string, or refuse.
+*
+* Unwraps `Ada Lovelace <ada@example.com>`, bounds the length, refuses anything that is not
+* recognizably a single address, and returns it through {@link normalizeAddress}.
+*
+* Returns `undefined` rather than throwing. Inbound mail is attacker-controlled, so a malformed `From`
+* is an expected input, not an exception — the caller decides whether that means "drop the message" or
+* "store it with no sender", and both are reasonable.
+*/
+function parseAddress(value) {
+	if (typeof value !== "string") return void 0;
+	let candidate = value.trim();
+	if (candidate.length === 0 || candidate.length > 256) return void 0;
+	const angled = /<([^<>]*)>\s*$/.exec(candidate);
+	if (angled?.[1] !== void 0) candidate = angled[1].trim();
+	const at = candidate.lastIndexOf("@");
+	if (at <= 0 || at === candidate.length - 1) return void 0;
+	if (!candidate.slice(at + 1).includes(".") || /[\s,;<>"]/.test(candidate)) return void 0;
+	return normalizeAddress(candidate);
+}
+//#endregion
+export { MAX_ADDRESS_LENGTH, normalizeAddress, parseAddress };

package/dist/audit/auditEvent.d.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+/**
+ * The action taxonomy is **federated, not centralized**: `action` is an open, namespace-validated
+ * `domain/reason` string, and each capability owns and exports its own action constants (`auth/*`,
+ * `entitlement/*`, `admin/*`) — added without touching core, the way migrations and table prefixes
+ * already federate. Core never holds a closed union of every event.
+ */
+export declare const AuditAction: z.ZodString;
+export type AuditAction = z.output<typeof AuditAction>;
+/** The result of an audited action. A blocked authorization attempt is a first-class record. */
+export declare const AuditOutcome: z.ZodEnum<{
+    denied: "denied";
+    failure: "failure";
+    success: "success";
+}>;
+export type AuditOutcome = z.output<typeof AuditOutcome>;
+/** How serious the event is — orthogonal to outcome; drives dashboard filtering and alerting. */
+export declare const AuditSeverity: z.ZodEnum<{
+    critical: "critical";
+    info: "info";
+    warning: "warning";
+}>;
+export type AuditSeverity = z.output<typeof AuditSeverity>;
+/**
+ * What kind of principal acted. `anonymous` covers an unauthenticated request; `system` an internal job.
+ *
+ * `control-plane` is its own kind rather than a flavour of `service` because the question an adopter
+ * actually asks is "what did the management client do", separately from "what did my users do". A
+ * control-plane caller is not a user of their app at all — it holds no session and owns no user row —
+ * so folding it into `user` or `service` would make that question unanswerable from the trail.
+ */
+export declare const AuditActorType: z.ZodEnum<{
+    anonymous: "anonymous";
+    "control-plane": "control-plane";
+    service: "service";
+    system: "system";
+    user: "user";
+}>;
+export type AuditActorType = z.output<typeof AuditActorType>;
+/** Capability-specific structured detail attached to an event; Zod-validated on write and read. */
+export declare const AuditMetadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export type AuditMetadata = z.output<typeof AuditMetadata>;
+/**
+ * One audit event as an emitter supplies it. `occurredAt` is optional — the recorder stamps it at
+ * write time when absent. The nullable correlation fields (`actorId`, `sessionId`, request fields,
+ * resource fields) are populated from request context where available; an emitter sets only what it
+ * knows. The recorder turns this into the stored `pithy_audit_events` row.
+ *
+ * `tenant` is the one field here that names a *dimension* of the trail rather than a detail of the
+ * action, and it is on this seam rather than on the recorder's origin for the reason the origin fields
+ * are not: the recorder cannot know it. `project`, `environment` and `worker` are constant across every
+ * row a multi-tenant Worker writes, so without this the trail cannot be read per customer at all — and
+ * it must be stamped here, at write time, because the tenant of an action is a fact *at the time of the
+ * action* while membership is a fact *now*. Deriving one from the other later moves a year of history
+ * between tenants every time somebody joins or leaves.
+ */
+export declare const AuditEvent: z.ZodObject<{
+    action: z.ZodString;
+    outcome: z.ZodEnum<{
+        denied: "denied";
+        failure: "failure";
+        success: "success";
+    }>;
+    severity: z.ZodDefault<z.ZodEnum<{
+        critical: "critical";
+        info: "info";
+        warning: "warning";
+    }>>;
+    actorType: z.ZodEnum<{
+        anonymous: "anonymous";
+        "control-plane": "control-plane";
+        service: "service";
+        system: "system";
+        user: "user";
+    }>;
+    actorId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    sessionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    resourceType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    resourceId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    ip: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    userAgent: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    requestId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    tenant: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    occurredAt: z.ZodOptional<z.ZodDate>;
+    metadata: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$strip>;
+export type AuditEvent = z.output<typeof AuditEvent>;
+export type AuditEventInput = z.input<typeof AuditEvent>;
+//# sourceMappingURL=auditEvent.d.ts.map

package/dist/audit/auditEvent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auditEvent.d.ts","sourceRoot":"","sources":["../../src/audit/auditEvent.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgBxB;;;;;GAKG;AACH,eAAO,MAAM,WAAW,aAM+F,CAAC;AACxH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AAEvD,gGAAgG;AAChG,eAAO,MAAM,YAAY;;;;EAItB,CAAC;AACJ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC;AAEzD,iGAAiG;AACjG,eAAO,MAAM,aAAa;;;;EAIvB,CAAC;AACJ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc;;;;;;EAIxB,CAAC;AACJ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D,mGAAmG;AACnG,eAAO,MAAM,aAAa,wCAIvB,CAAC;AACJ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwCiF,CAAC;AACzG,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AACrD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC"}

package/dist/audit/auditEvent.js

@@ -0,0 +1,69 @@
+import { z } from "zod";
+/**
+* The action taxonomy is **federated, not centralized**: `action` is an open, namespace-validated
+* `domain/reason` string, and each capability owns and exports its own action constants (`auth/*`,
+* `entitlement/*`, `admin/*`) — added without touching core, the way migrations and table prefixes
+* already federate. Core never holds a closed union of every event.
+*/
+const AuditAction = z.string().regex(/^[a-z][a-z0-9]*\/[a-z][a-z0-9_]*$/, "An audit action must be a namespaced `domain/reason` code: lowercase, the domain and reason separated by a single `/` (e.g. `auth/login`).").describe("A namespaced `domain/reason` action code (`auth/login`, `admin/config_changed`); the federated taxonomy.");
+/** The result of an audited action. A blocked authorization attempt is a first-class record. */
+const AuditOutcome = z.enum([
+	"success",
+	"failure",
+	"denied"
+]).describe("The result of the audited action: `success`, `failure` (it was attempted and errored), or `denied` (an authorization gate blocked it). `denied` is first-class — blocked attempts are recorded, not only successes.");
+/** How serious the event is — orthogonal to outcome; drives dashboard filtering and alerting. */
+const AuditSeverity = z.enum([
+	"info",
+	"warning",
+	"critical"
+]).describe("The event's severity, orthogonal to its outcome: `info` (routine), `warning` (notable), `critical` (alert-worthy). Drives dashboard filtering and alerting.");
+/**
+* What kind of principal acted. `anonymous` covers an unauthenticated request; `system` an internal job.
+*
+* `control-plane` is its own kind rather than a flavour of `service` because the question an adopter
+* actually asks is "what did the management client do", separately from "what did my users do". A
+* control-plane caller is not a user of their app at all — it holds no session and owns no user row —
+* so folding it into `user` or `service` would make that question unanswerable from the trail.
+*/
+const AuditActorType = z.enum([
+	"user",
+	"service",
+	"system",
+	"anonymous",
+	"control-plane"
+]).describe("The kind of principal that acted: `user` (an authenticated person), `service` (a service account or CI token), `system` (an internal job, no external actor), `anonymous` (an unauthenticated request), or `control-plane` (a management client calling in under the `control-plane` strategy — a principal outside the adopter's own user base, whose actions are answerable separately from their users').");
+/** Capability-specific structured detail attached to an event; Zod-validated on write and read. */
+const AuditMetadata = z.record(z.string(), z.unknown()).describe("Capability-specific structured detail (a JSON object), validated on write and read. Never put a secret, credential, or sensitive payload here — the trail is queryable and long-lived.");
+/**
+* One audit event as an emitter supplies it. `occurredAt` is optional — the recorder stamps it at
+* write time when absent. The nullable correlation fields (`actorId`, `sessionId`, request fields,
+* resource fields) are populated from request context where available; an emitter sets only what it
+* knows. The recorder turns this into the stored `pithy_audit_events` row.
+*
+* `tenant` is the one field here that names a *dimension* of the trail rather than a detail of the
+* action, and it is on this seam rather than on the recorder's origin for the reason the origin fields
+* are not: the recorder cannot know it. `project`, `environment` and `worker` are constant across every
+* row a multi-tenant Worker writes, so without this the trail cannot be read per customer at all — and
+* it must be stamped here, at write time, because the tenant of an action is a fact *at the time of the
+* action* while membership is a fact *now*. Deriving one from the other later moves a year of history
+* between tenants every time somebody joins or leaves.
+*/
+const AuditEvent = z.object({
+	action: AuditAction.describe("What happened, as a namespaced `domain/reason` action code."),
+	outcome: AuditOutcome.describe("Whether the action succeeded, failed, or was denied."),
+	severity: AuditSeverity.default("info").describe("How serious the event is; defaults to `info`."),
+	actorType: AuditActorType.describe("The kind of principal that acted."),
+	actorId: z.string().nullish().describe("The acting principal's stable id (user id, service/token name); null for `system`/`anonymous`."),
+	sessionId: z.string().nullish().describe("The session this action belongs to, tying a chain of actions together; null when none."),
+	resourceType: z.string().nullish().describe("The type of resource the action targeted (e.g. `user`, `secret`); null when not resource-scoped."),
+	resourceId: z.string().nullish().describe("The id of the resource the action targeted; null when not resource-scoped."),
+	ip: z.string().nullish().describe("The client IP the request came from, for correlation; null when unknown."),
+	userAgent: z.string().nullish().describe("The client user-agent string, for correlation; null when unknown."),
+	requestId: z.string().nullish().describe("The request correlation id, tying this event to a single request/trace; null when unknown."),
+	tenant: z.string().nullish().describe("Whose action it was — the id of the tenant the action was taken *for*, in the emitter's own tenancy model. Opaque here: compared, never interpreted. **The one dimension an emitter supplies.** The recorder stamps `project`, `environment` and `worker` from the Worker's own vars and no emitter can touch them, but no var can know which customer an action belonged to, so this one comes from the call site and is exactly as trustworthy as it — set it where the tenant is already resolved and authorized, never from an unvalidated request field. Optional and nullable: a single-tenant app has no such dimension and must not invent one, and null means *not tenant-scoped* (a CLI-originated action, a fleet-wide operator action) rather than unknown. It is not `actorId`: one person can act in two tenants, so who acted does not answer for whom."),
+	occurredAt: z.date().optional().describe("When the action occurred. Optional on emit — the recorder stamps the current time when absent."),
+	metadata: AuditMetadata.nullish().describe("Capability-specific structured detail; null when there is none.")
+}).describe("One audit event as an emitter supplies it to `emit()` — the logical event before storage.");
+//#endregion
+export { AuditAction, AuditActorType, AuditEvent, AuditMetadata, AuditOutcome, AuditSeverity };

package/dist/audit/recorder.d.ts

@@ -0,0 +1,18 @@
+import type { AuditEventInput } from "./auditEvent";
+/**
+ * The recorder seam. `emit()` on the request context (`c.var.emit`) takes one {@link AuditEventInput}
+ * and durably records it. `@pithy-sh/audit`'s middleware replaces the default with a real D1-backed
+ * recorder; with no audit capability installed the default is {@link noopEmit}, so an emitter can
+ * always call `emit()` without first checking whether auditing is on.
+ *
+ * `emit()` is **non-fatal by contract**: it never throws and never rejects, so an audited action is
+ * never broken by an audit write. The real recorder swallows and logs its own failures; the no-op
+ * simply resolves.
+ */
+export type AuditEmit = (event: AuditEventInput) => Promise<void>;
+/**
+ * The default recorder when no audit capability is composed: accept the event and drop it. Resolves
+ * without throwing, so calling `emit()` is always safe whether or not auditing is installed.
+ */
+export declare const noopEmit: AuditEmit;
+//# sourceMappingURL=recorder.d.ts.map

package/dist/audit/recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../../src/audit/recorder.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,QAAQ,EAAE,SAA0B,CAAC"}

package/dist/audit/recorder.js

@@ -0,0 +1,8 @@
+//#region src/audit/recorder.ts
+/**
+* The default recorder when no audit capability is composed: accept the event and drop it. Resolves
+* without throwing, so calling `emit()` is always safe whether or not auditing is installed.
+*/
+const noopEmit = async () => {};
+//#endregion
+export { noopEmit };

package/dist/capability/bindings.d.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+export declare const BindingType: z.ZodUnion<readonly [z.ZodLiteral<"d1">, z.ZodLiteral<"kv">, z.ZodLiteral<"r2">, z.ZodLiteral<"ai">, z.ZodLiteral<"vectorize">, z.ZodLiteral<"queue">, z.ZodLiteral<"ratelimit">, z.ZodLiteral<"email">, z.ZodLiteral<"secret">, z.ZodLiteral<"workflow">, z.ZodLiteral<"service">, z.ZodLiteral<"durable_object">]>;
+export type BindingType = z.infer<typeof BindingType>;
+/**
+ * Whether a provision command creates the **resource** behind this kind of binding, rather than the
+ * adopter standing it up themselves.
+ *
+ * The three are the ones whose resource exists only after `pithy <capability> provision`: a `secret` is a
+ * Secrets Store entry (a `.dev.vars` string in local dev), a `workflow` runs in a deployed host Worker,
+ * and a `vectorize` binding addresses a provisioned index. `pithy add` says so in a note, at the moment
+ * the adopter is thinking about the capability.
+ *
+ * **This is not the same question as "did anything write the stanza".** Collapsing the two is what left
+ * `workflow:EMAIL_SENDER` unwritten and every route answering 500 (#258): the entry is derivable offline
+ * even though the Workflow it names is not deployed yet, so {@link isWrittenBinding} writes it and this
+ * one still reports that provisioning is what makes it work. A binding can be in both sets, and the
+ * Workflow is.
+ *
+ * `service` is not here. Its entry is also written for the adopter — by `pithy feature`, out of the
+ * target Worker's env-scoped script name — but it is wiring between an app's own Workers rather than a
+ * capability's provisioned resource, and no shipped capability declares one.
+ */
+export declare function isProvisionedBinding(type: BindingType): boolean;
+/**
+ * Whether `pithy add` writes this kind's `wrangler.jsonc` entry, offline, at the moment it composes the
+ * capability.
+ *
+ * Together with {@link isProvisionedBinding} this is the whole answer to "where does this binding come
+ * from" — the invariant `capabilities/requiredBindings.test.ts` states. A kind in **neither** set is a
+ * binding a capability requires and nothing supplies: the composition refuses to assemble, the error
+ * names the binding, and no command anywhere fixes it. `ratelimit` was exactly that, which is why a
+ * scaffolded project composing `auth` answered 500 on every route including `/health` (#258).
+ *
+ * Membership turns on one question only: **is every field wrangler requires derivable offline?** A rate
+ * limiter's are — the stanza is a policy with no resource behind it. A Workflow's are, because the
+ * manifest binding states the job and the exported class, and the rest is the project-scoped naming rule.
+ * A Vectorize index's `index_name` is a provisioning output and is not, so an entry carrying only
+ * `binding` would fail wrangler's validator and stop `wrangler dev` and `wrangler deploy` both — worse
+ * than no entry. A `secret` has no `wrangler.jsonc` array at all.
+ *
+ * `service` is in neither, deliberately: `pithy feature` writes it out of the target Worker's env-scoped
+ * script name, and no shipped capability declares one.
+ */
+export declare function isWrittenBinding(type: BindingType): boolean;
+/**
+ * Declares a Cloudflare binding a capability requires in the Worker env. The authoring
+ * shape lets `optional` be omitted (defaults false); `createBackend` normalizes via parse.
+ */
+export declare const BindingSpec: z.ZodObject<{
+    type: z.ZodUnion<readonly [z.ZodLiteral<"d1">, z.ZodLiteral<"kv">, z.ZodLiteral<"r2">, z.ZodLiteral<"ai">, z.ZodLiteral<"vectorize">, z.ZodLiteral<"queue">, z.ZodLiteral<"ratelimit">, z.ZodLiteral<"email">, z.ZodLiteral<"secret">, z.ZodLiteral<"workflow">, z.ZodLiteral<"service">, z.ZodLiteral<"durable_object">]>;
+    name: z.ZodString;
+    optional: z.ZodDefault<z.ZodBoolean>;
+    className: z.ZodOptional<z.ZodString>;
+    classModule: z.ZodOptional<z.ZodString>;
+    job: z.ZodOptional<z.ZodString>;
+    service: z.ZodOptional<z.ZodString>;
+    remote: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type BindingSpec = z.infer<typeof BindingSpec>;
+/** Authoring shape for a capability's `requiredBindings`: `optional` may be omitted. */
+export type BindingSpecInput = z.input<typeof BindingSpec>;
+//# sourceMappingURL=bindings.d.ts.map

package/dist/capability/bindings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.d.ts","sourceRoot":"","sources":["../../src/capability/bindings.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,WAAW,sTAmBuC,CAAC;AAChE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAE/D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAU3D;AAqBD;;;GAGG;AACH,eAAO,MAAM,WAAW;;;;;;;;;iBAqFpB,CAAC;AACL,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,wFAAwF;AACxF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC"}

package/dist/capability/bindings.js

@@ -0,0 +1,97 @@
+import { NAME_SEGMENT } from "../naming/segment.js";
+import { z } from "zod";
+//#region src/capability/bindings.ts
+const BindingType = z.union([
+	z.literal("d1").describe("D1 SQL database (SQLite at the edge)."),
+	z.literal("kv").describe("Workers KV — eventually-consistent key/value store."),
+	z.literal("r2").describe("R2 bucket — S3-compatible object storage."),
+	z.literal("ai").describe("Workers AI — run models on Cloudflare's GPU network."),
+	z.literal("vectorize").describe("Vectorize — vector DB for embeddings and similarity search."),
+	z.literal("queue").describe("Cloudflare Queue — async message producer/consumer."),
+	z.literal("ratelimit").describe("Workers Rate Limiting — per-key request limiting."),
+	z.literal("email").describe("Email Sending binding (Cloudflare Email Service)."),
+	z.literal("secret").describe("Secret from the Secrets Store, encrypted at rest."),
+	z.literal("workflow").describe("Cloudflare Workflow — durable, multi-step execution."),
+	z.literal("service").describe("Service binding — direct RPC to another Worker."),
+	z.literal("durable_object").describe("Durable Object — a single-threaded, stateful actor with its own storage. Backed by an exported DO class; the CLI wires the namespace binding and the class migration tag.")
+]).describe("Kind of Cloudflare resource a binding refers to.");
+/**
+* Whether a provision command creates the **resource** behind this kind of binding, rather than the
+* adopter standing it up themselves.
+*
+* The three are the ones whose resource exists only after `pithy <capability> provision`: a `secret` is a
+* Secrets Store entry (a `.dev.vars` string in local dev), a `workflow` runs in a deployed host Worker,
+* and a `vectorize` binding addresses a provisioned index. `pithy add` says so in a note, at the moment
+* the adopter is thinking about the capability.
+*
+* **This is not the same question as "did anything write the stanza".** Collapsing the two is what left
+* `workflow:EMAIL_SENDER` unwritten and every route answering 500 (#258): the entry is derivable offline
+* even though the Workflow it names is not deployed yet, so {@link isWrittenBinding} writes it and this
+* one still reports that provisioning is what makes it work. A binding can be in both sets, and the
+* Workflow is.
+*
+* `service` is not here. Its entry is also written for the adopter — by `pithy feature`, out of the
+* target Worker's env-scoped script name — but it is wiring between an app's own Workers rather than a
+* capability's provisioned resource, and no shipped capability declares one.
+*/
+function isProvisionedBinding(type) {
+	return type === "secret" || type === "workflow" || type === "vectorize";
+}
+/**
+* Whether `pithy add` writes this kind's `wrangler.jsonc` entry, offline, at the moment it composes the
+* capability.
+*
+* Together with {@link isProvisionedBinding} this is the whole answer to "where does this binding come
+* from" — the invariant `capabilities/requiredBindings.test.ts` states. A kind in **neither** set is a
+* binding a capability requires and nothing supplies: the composition refuses to assemble, the error
+* names the binding, and no command anywhere fixes it. `ratelimit` was exactly that, which is why a
+* scaffolded project composing `auth` answered 500 on every route including `/health` (#258).
+*
+* Membership turns on one question only: **is every field wrangler requires derivable offline?** A rate
+* limiter's are — the stanza is a policy with no resource behind it. A Workflow's are, because the
+* manifest binding states the job and the exported class, and the rest is the project-scoped naming rule.
+* A Vectorize index's `index_name` is a provisioning output and is not, so an entry carrying only
+* `binding` would fail wrangler's validator and stop `wrangler dev` and `wrangler deploy` both — worse
+* than no entry. A `secret` has no `wrangler.jsonc` array at all.
+*
+* `service` is in neither, deliberately: `pithy feature` writes it out of the target Worker's env-scoped
+* script name, and no shipped capability declares one.
+*/
+function isWrittenBinding(type) {
+	return type === "d1" || type === "kv" || type === "r2" || type === "ai" || type === "durable_object" || type === "ratelimit" || type === "workflow";
+}
+/**
+* Declares a Cloudflare binding a capability requires in the Worker env. The authoring
+* shape lets `optional` be omitted (defaults false); `createBackend` normalizes via parse.
+*/
+const BindingSpec = z.object({
+	type: BindingType.describe("Resource kind this binding provides."),
+	name: z.string().min(1).describe("Binding name expected in the Worker env (e.g. \"DB\", \"SESSIONS\")."),
+	optional: z.boolean().default(false).describe("If true, createBackend won't fail when this binding is absent."),
+	className: z.string().min(1).regex(/^[A-Za-z_$][A-Za-z0-9_$]*$/, "A className is a JavaScript identifier: letters, digits, `_` and `$`, not leading a digit.").optional().describe("The exported class this binding is backed by. For a `durable_object` binding it is the DO class (e.g. \"MultiplayerSession\") the CLI writes into `durable_objects.bindings`, the DO class migration tag, and the `export { … }` line in the Worker entry. For a `workflow` binding it is the `WorkflowEntrypoint` subclass (e.g. \"EmailSendWorkflow\") the CLI writes as `class_name` — the same value the capability's own `WorkflowSpec.className` carries. Ignored for every other kind."),
+	classModule: z.string().min(1).regex(/^(@[a-z0-9~-][a-z0-9._~-]*\/)?[a-z0-9~-][a-z0-9._~-]*(\/[A-Za-z0-9_~-][A-Za-z0-9._~-]*)*$/, "A classModule is a bare module specifier: a package, optionally with a path into it.").optional().describe("The module the class is exported from (e.g. \"@pithy-sh/multiplayer/src/session/durableObject\") — what the CLI writes the Worker entry's `export { <className> } from \"<classModule>\";` against. Required for a `durable_object` binding, because wrangler resolves `class_name` against the entry `main` names and refuses the deploy when nothing there exports it. Its own module, never the package entry point, which `pithy.config.ts` loads in Node. Ignored for every other kind."),
+	job: z.string().min(1).regex(NAME_SEGMENT, "A job is one name segment: lowercase letters, digits, and single hyphens.").optional().describe("The job within the capability this Workflow runs (e.g. \"send\") — the `<job>` segment of the deployed `<project>-<env>-<capability>-<job>` name, and the second half of the `<capability>/<job>` dispatch key. Meaningful only for a `workflow` binding, where it is what lets `pithy add` name the Workflow offline instead of leaving the binding unwritten. Ignored for every other kind."),
+	service: z.string().min(1).optional().describe("The Worker this binding calls, named as it appears in `apps/<name>/` (e.g. \"api\"). Meaningful only for a `service` binding — the CLI resolves it to that Worker's environment-scoped script name when writing `services` into wrangler.jsonc, so worker-to-worker RPC targets the right deployment per environment. Ignored for every other kind."),
+	remote: z.boolean().optional().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.")
+}).describe("Declares a Cloudflare binding a capability requires in the Worker env.").check((ctx) => {
+	if (ctx.value.type === "durable_object" && ctx.value.className === void 0) ctx.issues.push({
+		code: "custom",
+		input: ctx.value,
+		path: ["className"],
+		message: `Durable Object binding "${ctx.value.name}" needs a className — the exported DO class it is backed by.`
+	});
+	if (ctx.value.type === "durable_object" && ctx.value.classModule === void 0) ctx.issues.push({
+		code: "custom",
+		input: ctx.value,
+		path: ["classModule"],
+		message: `Durable Object binding "${ctx.value.name}" needs a classModule — the module its class is exported from.`
+	});
+	if (ctx.value.type === "service" && ctx.value.service === void 0) ctx.issues.push({
+		code: "custom",
+		input: ctx.value,
+		path: ["service"],
+		message: `Service binding "${ctx.value.name}" needs a service — the Worker it calls, as named in apps/.`
+	});
+});
+//#endregion
+export { BindingSpec, BindingType, isProvisionedBinding, isWrittenBinding };