@pithy-sh/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pithy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@pithy-sh/core",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pithy-sh/pithy.git",
+    "directory": "packages/core"
+  },
+  "files": [
+    "src",
+    "pithy.manifest.json",
+    "!src/**/*.test.*"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./src/*": "./src/*.ts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit false --outDir dist",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:node": "vitest run --project=node",
+    "test:workers": "vitest run --project=workers",
+    "clean": "rm -rf dist .turbo",
+    "reset": "bun run clean && rm -rf node_modules"
+  },
+  "dependencies": {
+    "@cloudflare/workers-types": "^5.20260729.1",
+    "@hono/zod-validator": "^0.9.0",
+    "hono": "^4.13.2",
+    "kysely": "^0.29.0",
+    "kysely-d1": "^0.4.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-plugin": "^1.0.0",
+    "@pithy-sh/tsconfig": "workspace:*",
+    "@vitest/coverage-v8": "^4.1.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.0",
+    "wrangler": "^4.115.0"
+  }
+}

package/pithy.manifest.json

@@ -0,0 +1,74 @@
+{
+  "name": "controlplane",
+  "package": "@pithy-sh/core",
+  "requiredBindings": [
+    {
+      "type": "d1",
+      "name": "DB"
+    },
+    {
+      "type": "kv",
+      "name": "CONTROL_PLANE",
+      "optional": true
+    }
+  ],
+  "peerCapabilities": [],
+  "optionalCapabilities": ["audit"],
+  "migrationNamespace": "controlplane",
+  "whenToEnable": "Let a management client — the Pithy dashboard, or one you write yourself — reach into this project's own Worker without any data plane in between. It is present-and-denying by default: with no connection registered, every control-plane route answers 403, and there is no backdoor to open. Connect one with `pithy dashboard connect --env production` and the client gets exactly the operations you granted it, per environment, so a staging credential can never touch production. The credential is asymmetric: the client holds a private key, you hold and can revoke the public one, and nothing secret of yours ever leaves your infrastructure. Rotation is append, prove, then expire — never replace — so a rotation that fails leaves the old key working rather than locking anyone out, and revocation is a row you delete, immediate and needing nothing from anybody else. Every call is verified against a signed 60-second single-scope token bound to a digest of its own body, checked for replay, and written to your audit trail with its own actor kind, so 'what did the dashboard do' is answerable separately from 'what did my users do'. Capabilities contribute their own admin routes behind it — @pithy-sh/payments puts manual entitlement grant and revoke here — so adding one adds its management surface with nothing to wire. They describe those routes too, so `GET /control-plane/manifest` tells a client which capabilities this Worker composes and exactly how to call each one, mount paths and required scopes included; a client never has to assume where anything lives. Turning this on grants nobody anything; connecting a client is the deliberate second step.",
+  "scaffold": [
+    "Add a `controlplane()` block to pithy.config.ts. Every option has a working default; leave `issuer` alone unless you run your own management client.",
+    "Bind a D1 database named DB in wrangler.jsonc — the same app database your other capabilities use.",
+    "Only if you set `replayBackend: \"kv\"`: bind a KV namespace named CONTROL_PLANE in wrangler.jsonc. The default records spent token ids in D1 instead, where a primary key decides the race, so most projects need no KV at all.",
+    "Run `pithy migrate` to create pithy_controlplane_connections and pithy_controlplane_replays.",
+    "Run `pithy dashboard connect --env <environment>` to register a management client. Until you do, every control-plane route denies — which is the correct state, not a broken one.",
+    "Add `@pithy-sh/audit` if it is not already installed. The seam emits on every allowed and every denied call, and this is the surface where an unaudited admin action is least acceptable."
+  ],
+  "configOptions": [
+    {
+      "key": "basePath",
+      "default": "/control-plane",
+      "describe": "Where the seam's own routes mount — ping, manifest, and the three key-lifecycle routes. Capability admin routes mount under their own capability's path, not here."
+    },
+    {
+      "key": "issuer",
+      "default": "https://app.pithy.sh",
+      "describe": "The management-client origin a new connection is registered against, and the `iss` every one of its tokens must carry. Trust-critical and effectively permanent: each connection stores the issuer it was created with, and verification checks that stored value, so changing this only affects connections made afterwards. Point it at your own origin if you run your own client. It also seeds the browser origins this Worker answers a CORS preflight for; add any others with `allowedOrigins`."
+    },
+    {
+      "key": "allowedOrigins",
+      "default": [],
+      "describe": "Browser origins allowed to call this Worker's control-plane surface cross-origin, in addition to `issuer`. Additive: an entry here never removes `issuer`, so adding your own console cannot lock out the dashboard that was already working. Read from config alone and never from a connection row — a preflight carries no credential, so answering one costs no database read and says nothing about which origins are registered. List a management client you host yourself here."
+    },
+    {
+      "key": "corsMaxAgeSeconds",
+      "default": 600,
+      "describe": "How long a browser may cache a preflight for this Worker's admin surface, in seconds. The allow-list it caches is a compile-time constant, so ten minutes costs nothing and saves a round trip on every call. Set it to 0 while you are working out an allow-list: a browser that cached a refusal keeps refusing for the full window after you have fixed it, which reads like a change that did not take."
+    },
+    {
+      "key": "maxTokenLifetimeSeconds",
+      "default": 60,
+      "describe": "The longest `exp - iat` a token may claim. A cap rather than a suggestion: it is what keeps the replay memory sound, since a token allowed to live longer than that memory would become replayable the moment its id aged out."
+    },
+    {
+      "key": "clockSkewSeconds",
+      "default": 60,
+      "describe": "How far a caller's clock may drift from this Worker's before its tokens are rejected. Applied either side of `iat` and `exp`."
+    },
+    {
+      "key": "jtiTtlSeconds",
+      "default": 300,
+      "describe": "How long a spent token id is remembered, so the same token cannot be presented twice. Must exceed the maximum token lifetime plus TWO clock skews, because a token is accepted a skew before it was issued and a skew after it expires. Config that would let the memory be shorter is rejected outright, since that gap is exactly where replay reopens."
+    },
+    {
+      "key": "keyRetentionDays",
+      "default": 30,
+      "describe": "How long an expired or revoked key stays on the row before it is pruned. Verification parses this array on every call, so it is bounded on purpose; the audit trail is the history of record, not the row."
+    },
+    {
+      "key": "maxKeys",
+      "default": 8,
+      "describe": "The hardest cap on retained keys, whatever the retention window says. Two live at once is the normal state during a rotation overlap; eight is room for a long tail of superseded ones without letting the blob grow without limit."
+    }
+  ]
+}

package/src/address/address.ts

@@ -0,0 +1,83 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * 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 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 function normalizeAddress(value: string): string {
+  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.
+ */
+export function parseAddress(value: string | null | undefined): string | undefined {
+  if (typeof value !== "string") return undefined;
+  let candidate = value.trim();
+  if (candidate.length === 0 || candidate.length > MAX_ADDRESS_LENGTH) return undefined;
+
+  // `Ada Lovelace <ada@example.com>` — take what the angle brackets delimit, which is the address even
+  // when the display name itself contains an `@`.
+  const angled = /<([^<>]*)>\s*$/.exec(candidate);
+  if (angled?.[1] !== undefined) candidate = angled[1].trim();
+
+  const at = candidate.lastIndexOf("@");
+  if (at <= 0 || at === candidate.length - 1) return undefined;
+
+  // A domain with no dot is either localhost or a mistake, and a space, comma, semicolon, bracket or
+  // quote anywhere means this was never one address. Both are cheap to check and both are worth
+  // refusing before anything is stored.
+  if (!candidate.slice(at + 1).includes(".") || /[\s,;<>"]/.test(candidate)) return undefined;
+
+  return normalizeAddress(candidate);
+}

package/src/audit/auditEvent.ts

@@ -0,0 +1,130 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * The audit-event seam. `AuditEvent` is the shape any capability hands to `emit()` (the request
+ * context's recorder) — the logical event, before storage. `@pithy-sh/audit` owns the D1 table that
+ * persists it (`pithy_audit_events`, with codecs); core owns only this contract so a capability
+ * emits an event without importing the audit package (principle 4). With no audit capability
+ * installed, `emit()` is a no-op and these types are still the contract every emitter writes to.
+ *
+ * Every field carries a `.describe()` — the schema is the documentation, and it drives the
+ * generated audit-event catalog the dashboard reads.
+ */
+
+/** `domain/reason` — a namespaced lowercase action code (`auth/login`, `admin/config_changed`). */
+const AUDIT_ACTION_PATTERN = /^[a-z][a-z0-9]*\/[a-z][a-z0-9_]*$/;
+
+/**
+ * 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 const AuditAction = z
+  .string()
+  .regex(
+    AUDIT_ACTION_PATTERN,
+    "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.");
+export type AuditAction = z.output<typeof AuditAction>;
+
+/** The result of an audited action. A blocked authorization attempt is a first-class record. */
+export 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.",
+  );
+export type AuditOutcome = z.output<typeof AuditOutcome>;
+
+/** How serious the event is — orthogonal to outcome; drives dashboard filtering and alerting. */
+export 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.",
+  );
+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 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').",
+  );
+export type AuditActorType = z.output<typeof AuditActorType>;
+
+/** Capability-specific structured detail attached to an event; Zod-validated on write and read. */
+export 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.",
+  );
+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 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.");
+export type AuditEvent = z.output<typeof AuditEvent>;
+export type AuditEventInput = z.input<typeof AuditEvent>;

package/src/audit/recorder.ts

@@ -0,0 +1,22 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+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 const noopEmit: AuditEmit = async () => {};

package/src/capability/bindings.ts

@@ -0,0 +1,196 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { NAME_SEGMENT } from "../naming/segment";
+
+export 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.");
+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 function isProvisionedBinding(type: BindingType): boolean {
+  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.
+ */
+export function isWrittenBinding(type: BindingType): boolean {
+  return (
+    type === "d1" ||
+    type === "kv" ||
+    type === "r2" ||
+    type === "ai" ||
+    type === "durable_object" ||
+    type === "ratelimit" ||
+    type === "workflow"
+  );
+}
+
+/**
+ * A JavaScript class name — what `className` may be.
+ *
+ * Constrained because it is no longer only a JSON value. A Durable Object's `className` is written into
+ * the adopter's Worker entry as `export { <className> } from "…";` (#428), which is generated TypeScript
+ * built out of third-party data read from `node_modules` — the shape #171, #174 and #183 each met one
+ * field too late. An identifier cannot close the statement and open another.
+ */
+const CLASS_NAME = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+/**
+ * A bare module specifier — a package, optionally with a path into it.
+ *
+ * The other half of the generated export line, and narrowed for the same reason. No quotes, no
+ * whitespace, no `..`: a specifier that walked back out of its own package would re-export whatever it
+ * landed on, which is `configImports.isInside`'s argument in a regex.
+ */
+const CLASS_MODULE = /^(@[a-z0-9~-][a-z0-9._~-]*\/)?[a-z0-9~-][a-z0-9._~-]*(\/[A-Za-z0-9_~-][A-Za-z0-9._~-]*)*$/;
+
+/**
+ * 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 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(CLASS_NAME, "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(CLASS_MODULE, "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)
+      // Constrained here rather than only where the name is composed, because a manifest is
+      // third-party data read out of `node_modules` and this string lands verbatim in the adopter's
+      // `wrangler.jsonc` as a Cloudflare Workflow name. `NAME_SEGMENT` is the one segment rule every
+      // composed name answers to, so a manifest that states something a deploy would refuse is refused
+      // at parse instead — attributed to the capability, before anything is written.
+      .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) => {
+    // A durable_object binding is inert without the class that backs it — the CLI would emit a
+    // `durable_objects.bindings` entry with no `class_name`, which wrangler rejects. Fail here, at
+    // define/manifest-parse time, attributed to the capability, rather than deep in the writer.
+    if (ctx.value.type === "durable_object" && ctx.value.className === undefined) {
+      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.`,
+      });
+    }
+    // And the module that class comes from. A DO binding is two halves — the `durable_objects.bindings`
+    // entry and a named export on the module `main` points at — and the CLI can only write the second
+    // one if the capability says where the class lives. Without it the wiring is complete in the config
+    // and the deploy fails on "not exported in your entrypoint file" (#428). Refused at define time,
+    // attributed to the capability, for the same reason `className` is.
+    if (ctx.value.type === "durable_object" && ctx.value.classModule === undefined) {
+      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.`,
+      });
+    }
+    // A service binding with no target is unresolvable: the CLI cannot know which Worker to point
+    // `services[].service` at, and wrangler rejects the entry. Fail at define time, attributed to the
+    // capability, rather than emitting a broken binding into an environment's wrangler.jsonc.
+    if (ctx.value.type === "service" && ctx.value.service === undefined) {
+      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/.`,
+      });
+    }
+  });
+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>;