@pithy-sh/core 0.9.0 → 0.11.0

package/src/access/visibility.ts

@@ -0,0 +1,109 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { ValidationError } from "../error/pithyError";
+
+/**
+ * Who may read a record, and learn that it exists — one convention, written once, for every capability
+ * that holds a record a person owns.
+ *
+ * **Three levels, and the kit owns them.** `private` is the owner, acting for the organization the record
+ * was written under; acting for any other organization, not even them. `organization` is any member of the
+ * record's organization, acting for it. `public` is anyone holding the id or the URL, signed in or not.
+ * Media and storage share the levels, the policy shape and the rules, so a record means the same thing in
+ * both and there is one place the meaning can be wrong.
+ *
+ * **The project decides which levels exist, and which one a record gets when it names none.** `allowed` is
+ * a set rather than a mode, because a set says everything a mode would and one thing it cannot:
+ * `["private", "organization"]` is a guarantee that nothing can be published, even by mistake.
+ */
+
+/** Every level, weakest first. */
+export const RECORD_VISIBILITIES = ["private", "organization", "public"] as const;
+
+export const RecordVisibility = z
+  .enum(RECORD_VISIBILITIES)
+  .describe(
+    "Who may read a record and learn it exists: `private` is the owner acting for the record's organization, `organization` is any member acting for it, `public` is anyone holding the id or URL.",
+  );
+export type RecordVisibility = z.infer<typeof RecordVisibility>;
+
+/**
+ * The levels a project allows, and the one a record gets when a write names none.
+ *
+ * **`default` is `private` and must be in `allowed`**, and a policy that breaks either is refused at
+ * parse — which, for a capability, is at boot. **`allowed` defaults to all three**, so a capability that
+ * accepted `public` before this policy existed is not narrowed by it.
+ */
+export const VisibilityPolicy = z
+  .object({
+    default: RecordVisibility.default("private").describe(
+      "The level a record gets when a write names none. Private, so a forgotten field can never publish a file. Must be one of `allowed`.",
+    ),
+    allowed: z
+      .array(RecordVisibility)
+      .min(1)
+      .default([...RECORD_VISIBILITIES])
+      .describe(
+        'The levels a write may name. All three by default. `["private", "organization"]` means nothing can ever be public; a write naming a level outside it is refused, never coerced.',
+      ),
+  })
+  .describe("Which visibility levels this project allows, and the default for a write that names none.")
+  .check((ctx) => {
+    if (ctx.value.allowed.includes(ctx.value.default)) return;
+    ctx.issues.push({
+      code: "custom",
+      input: ctx.value,
+      path: ["default"],
+      message: `visibility.default is \`${ctx.value.default}\`, which visibility.allowed (${ctx.value.allowed.join(", ")}) does not include.`,
+    });
+  });
+export type VisibilityPolicy = z.output<typeof VisibilityPolicy>;
+export type VisibilityPolicyInput = z.input<typeof VisibilityPolicy>;
+
+/**
+ * The level a write records: the one it named, or the policy's default.
+ *
+ * **Refused, never coerced.** A level outside `allowed` is a mistake somewhere — a client that did not
+ * know the policy, or a policy narrowed under a client — and quietly writing the default instead would
+ * hide it until somebody wondered why a published file was private, or worse. `organization` with no
+ * organization in force is refused for the same reason: a record no member can ever be acting for is not
+ * an organization record, it is a private one that says otherwise.
+ *
+ * Both refusals are the caller's to fix, so the remedy is in `message`; `action` names the config key for
+ * the operator who decides the policy.
+ */
+export function resolveVisibility(
+  policy: VisibilityPolicy,
+  requested: RecordVisibility | undefined,
+  organizationId: string | null,
+): RecordVisibility {
+  const level = requested ?? policy.default;
+  if (!policy.allowed.includes(level)) {
+    throw new ValidationError({
+      message: `Visibility \`${level}\` is not allowed here. Allowed: ${policy.allowed.join(", ")}.`,
+      action: "Name one of visibility.allowed, or widen visibility.allowed in this Worker's pithy.config.ts.",
+      detail: `requested ${requested ?? "(default)"} resolved to ${level}, outside ${policy.allowed.join(", ")}`,
+      params: { visibility: level, allowed: policy.allowed.join(", ") },
+    });
+  }
+  if (level === "organization" && organizationId === null) {
+    throw new ValidationError({
+      message: "Visibility `organization` needs an organization in force. Choose one, or name another level.",
+      action: "Compose @pithy-sh/organization and choose an organization, or set a different visibility.default.",
+      detail: "organization visibility requested with no acting organization",
+      params: { visibility: level },
+    });
+  }
+  return level;
+}
+
+/**
+ * The levels a policy no longer allows — what `pithy doctor` searches records for after `allowed`
+ * narrows. Narrowing never rewrites a record: making a public record private breaks every link already
+ * published, so moving them is the adopter's explicit act, and this is how they find them.
+ */
+export function outsidePolicy(policy: VisibilityPolicy): RecordVisibility[] {
+  return RECORD_VISIBILITIES.filter((level) => !policy.allowed.includes(level));
+}

package/src/asyncapi/document.ts

@@ -0,0 +1,164 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { z } from "zod";
+import type { Capability } from "../capability/capability";
+import { ErrorBody } from "../error/wire";
+import type { SocketChannel, SocketMessage } from "../http/socket";
+import type { VerificationStrategy } from "../http/verification";
+import {
+  type ContractInfo,
+  type JsonSchema,
+  jsonSchema,
+  openApiPath,
+  type UndescribedField,
+  undescribedFieldsIn,
+} from "../openapi/document";
+
+/**
+ * **The AsyncAPI contract: every socket a Worker serves, and every frame on it.**
+ *
+ * The OpenAPI document stops at the upgrade. This picks up after it, from the `sockets` each composed
+ * capability declares (`../http/socket.ts`): one channel per socket, one message per frame, and one operation
+ * per direction — `send` for what the Worker sends, `receive` for what it accepts, as AsyncAPI names them from
+ * the application's side. Every schema is the one the socket parses with, converted by `z.toJSONSchema` with
+ * its descriptions intact, so an engine with no generator still has typed messages to write against.
+ *
+ * AsyncAPI 3.0, whose schemas are JSON Schema — the dialect `z.toJSONSchema` writes.
+ */
+
+/** The AsyncAPI version this module writes. */
+export const ASYNCAPI_VERSION = "3.0.0";
+
+/** One capability's sockets. Becomes the channels tagged with its name. */
+export interface SocketGroup {
+  /** The capability's name. */
+  readonly tag: string;
+  /** The sockets it declared. */
+  readonly sockets: readonly SocketChannel[];
+}
+
+/** The sockets of every capability that declares one, grouped by capability, in composition order. */
+export function socketGroupsOf(capabilities: readonly Capability[]): SocketGroup[] {
+  return capabilities
+    .filter((capability) => (capability.sockets ?? []).length > 0)
+    .map((capability) => ({ tag: capability.name, sockets: capability.sockets ?? [] }));
+}
+
+/** The subset of an AsyncAPI 3.0 document this module writes. */
+export interface AsyncApiDocument {
+  asyncapi: string;
+  info: ContractInfo;
+  channels: Record<string, Record<string, unknown>>;
+  operations: Record<string, Record<string, unknown>>;
+  components: {
+    messages: Record<string, Record<string, unknown>>;
+    schemas: Record<string, JsonSchema>;
+  };
+}
+
+/** A frame's id in the document: its socket's name and its own, so two sockets' `error` frames stay apart. */
+function messageId(socket: SocketChannel, message: SocketMessage, direction: "send" | "receive"): string {
+  return `${socket.name}.${direction}.${message.name}`;
+}
+
+/** One `components.messages` entry: a JSON frame by its schema, a text frame by its exact text. */
+function messageOf(message: SocketMessage): Record<string, unknown> {
+  if (message.schema === undefined) {
+    return {
+      name: message.name,
+      summary: message.summary,
+      contentType: "text/plain",
+      payload: { type: "string", const: message.text ?? "", description: message.summary },
+    };
+  }
+  return {
+    name: message.name,
+    summary: message.summary,
+    contentType: "application/json",
+    payload: jsonSchema(message.schema, "input"),
+  };
+}
+
+/** The path parameters, from the same schema the upgrade route validates them with. */
+function parametersOf(params: z.ZodType | undefined): Record<string, Record<string, unknown>> {
+  if (params === undefined) return {};
+  const properties = (jsonSchema(params, "input").properties ?? {}) as Record<string, JsonSchema>;
+  return Object.fromEntries(
+    Object.entries(properties).map(([name, property]) => [
+      name,
+      typeof property.description === "string" ? { description: property.description } : {},
+    ]),
+  );
+}
+
+function strategiesOf(socket: SocketChannel): readonly VerificationStrategy[] {
+  return typeof socket.verification === "string" ? [socket.verification] : socket.verification;
+}
+
+/** The AsyncAPI document for these capabilities' sockets. */
+export function asyncApiDocument(info: ContractInfo, groups: readonly SocketGroup[]): AsyncApiDocument {
+  const document: AsyncApiDocument = {
+    asyncapi: ASYNCAPI_VERSION,
+    info,
+    channels: {},
+    operations: {},
+    components: { messages: {}, schemas: { Error: jsonSchema(ErrorBody, "input") } },
+  };
+
+  for (const group of groups) {
+    for (const socket of group.sockets) {
+      const channelMessages: Record<string, { $ref: string }> = {};
+      for (const direction of ["send", "receive"] as const) {
+        const refs: { $ref: string }[] = [];
+        for (const message of socket[direction]) {
+          const id = messageId(socket, message, direction);
+          document.components.messages[id] = messageOf(message);
+          channelMessages[id] = { $ref: `#/components/messages/${id}` };
+          refs.push({ $ref: `#/channels/${socket.name}/messages/${id}` });
+        }
+        if (refs.length > 0) {
+          document.operations[`${socket.name}.${direction}`] = {
+            action: direction,
+            channel: { $ref: `#/channels/${socket.name}` },
+            summary: direction === "send" ? "Frames the Worker sends." : "Frames the Worker accepts.",
+            messages: refs,
+          };
+        }
+      }
+      const parameters = parametersOf(socket.params);
+      document.channels[socket.name] = {
+        address: openApiPath(socket.path),
+        summary: socket.summary,
+        ...(socket.description === undefined ? {} : { description: socket.description }),
+        ...(Object.keys(parameters).length === 0 ? {} : { parameters }),
+        messages: channelMessages,
+        tags: [{ name: group.tag }],
+        bindings: { ws: { method: "GET" } },
+        "x-pithy-verification": strategiesOf(socket),
+        "x-pithy-subprotocols": socket.versions,
+      };
+      for (const [name, schema] of Object.entries(socket.schemas ?? {})) {
+        document.components.schemas[`${socket.name}.${name}`] = jsonSchema(schema, "input");
+      }
+    }
+  }
+  return document;
+}
+
+/**
+ * Every message property, schema property and channel parameter in the document without a description —
+ * the same rule as the OpenAPI document's, over the parts a client generates from.
+ */
+export function undescribedAsyncFields(document: AsyncApiDocument): UndescribedField[] {
+  const parameters = Object.entries(document.channels).flatMap(([channel, item]) =>
+    Object.entries((item.parameters ?? {}) as Record<string, Record<string, unknown>>)
+      .filter(([, parameter]) => typeof parameter.description !== "string")
+      .map(([name]) => ({ pointer: `/channels/${channel}/parameters/${name}` })),
+  );
+  return [
+    ...parameters,
+    ...undescribedFieldsIn(document.components.messages, "/components/messages"),
+    ...undescribedFieldsIn(document.components.schemas, "/components/schemas"),
+  ];
+}

package/src/audit/auditEvent.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import { z } from "zod";
+import { ControlPlaneActorKind } from "../controlPlane/data/connection";
 
 /**
  * The audit-event seam. `AuditEvent` is the shape any capability hands to `emit()` (the request
@@ -95,6 +96,9 @@ export const AuditEvent = z
       .string()
       .nullish()
       .describe("The acting principal's stable id (user id, service/token name); null for `system`/`anonymous`."),
+    actorKind: ControlPlaneActorKind.nullish().describe(
+      "For a `control-plane` actor, what kind of management client acted — `agent`, `dashboard` or `script` — from the connection it called through (#721). `actorType` names all three alike; this is what tells them apart. Stamped by `requireControlPlane`, so an emit site does not set it; null for every other actor type, and for a connection registered before the kind was recorded.",
+    ),
     sessionId: z
       .string()
       .nullish()

package/src/capability/bindings.ts

@@ -23,10 +23,87 @@ export const BindingType = z
       .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.",
       ),
+    z
+      .literal("hyperdrive")
+      .describe("Hyperdrive — a pooled, cached connection to an existing database. The adopter creates the config."),
+    z.literal("browser").describe("Browser Rendering — a headless browser the Worker drives."),
+    z.literal("images").describe("Cloudflare Images — transform and optimize images from the Worker."),
+    z
+      .literal("analytics_engine_datasets")
+      .describe("Workers Analytics Engine — write data points to a dataset, query them with SQL."),
+    z.literal("pipelines").describe("Pipelines — send records into a stream that lands in R2. The adopter creates it."),
+    z
+      .literal("mtls_certificates")
+      .describe("mTLS certificate — present a client certificate on outbound requests. The adopter uploads it."),
+    z
+      .literal("dispatch_namespaces")
+      .describe("Workers for Platforms dispatch namespace — call Workers uploaded into it. The adopter creates it."),
+    z
+      .literal("artifacts")
+      .describe(
+        "Artifacts — versioned storage that speaks Git, one namespace of repositories per environment. Cloudflare creates the namespace on its first repo.",
+      ),
   ])
   .describe("Kind of Cloudflare resource a binding refers to.");
 export type BindingType = z.infer<typeof BindingType>;
 
+/**
+ * **How a stanza the kit creates gets this kind's entries** (#662).
+ *
+ * Every `env.<name>` stanza Pithy creates starts from the top level, because wrangler inherits none of the keys a
+ * binding lives in. What it starts with depends on whose resource the entry names, and that is a fact about the
+ * kind, not about the JSON shape wrangler happens to give it:
+ *
+ * - **`carry`** — account-level and identical everywhere. A dataset, a certificate, a rate limiter's
+ *   `namespace_id`: the top level's entries come down whole into every stanza, because nothing in them is an
+ *   environment's own.
+ * - **`provision`** — the environment owns the resource. Seeded empty, refilled by the provisioner, because
+ *   dev's database id in staging's stanza is staging writing to dev's database.
+ * - **`branch`** — an account-level resource and a per-environment *decision*. Carried into a feature, which is a
+ *   branch of `dev`; left empty in a declared environment, which is not. A `send_email` entry names an address
+ *   verified once at the account, and where this environment's mail goes is a choice production does not inherit
+ *   from a laptop. A Hyperdrive config is one origin database's connection, and a pipeline stream feeds one sink:
+ *   the account holds both, but the top level's are dev's, and a declared environment seeded with them would read
+ *   and write dev's Postgres and dev's sink with nothing failing.
+ *
+ * Three values, not a boolean. `send_email` was carried everywhere for a day and wrote a developer's address into
+ * production's first stanza (#650 review); emptied everywhere, it left a feature with no `NOTIFY`.
+ */
+export type SeedPolicy = "carry" | "provision" | "branch";
+
+/**
+ * The policy per kind, as a total record — so a kind added to {@link BindingType} without one is a type error
+ * here, and `bindings.test.ts` fails on a member whose answer it does not state.
+ */
+const SEED_POLICY: Record<BindingType, SeedPolicy> = {
+  ai: "carry",
+  ratelimit: "carry",
+  browser: "carry",
+  images: "carry",
+  hyperdrive: "branch",
+  analytics_engine_datasets: "carry",
+  mtls_certificates: "carry",
+  dispatch_namespaces: "carry",
+  pipelines: "branch",
+  d1: "provision",
+  kv: "provision",
+  r2: "provision",
+  vectorize: "provision",
+  queue: "provision",
+  durable_object: "provision",
+  workflow: "provision",
+  service: "provision",
+  secret: "provision",
+  email: "branch",
+  // The namespace is environment-derived, so a stanza starts empty and its own name is written in (#673).
+  artifacts: "provision",
+};
+
+/** How a newly created stanza gets this kind's entries. See {@link SeedPolicy}. */
+export function seedPolicy(type: BindingType): SeedPolicy {
+  return SEED_POLICY[type];
+}
+
 /**
  * Whether a provision command creates the **resource** behind this kind of binding, rather than the
  * adopter standing it up themselves.
@@ -69,19 +146,54 @@ export function isProvisionedBinding(type: BindingType): boolean {
  *
  * `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.
+ *
+ * **The pure-wrangler-entry kinds are written and never provisioned (#662).** `hyperdrive`, `browser`, `images`,
+ * `analytics_engine_datasets`, `pipelines`, `mtls_certificates` and `dispatch_namespaces` each take a binding name
+ * and, where wrangler requires one, the account-level resource the spec states as `target`. Pithy writes the
+ * entry; the adopter stands the resource up. `queue` writes its `queues.producers` entry under the name
+ * `pithy provision` creates the queue with, and `email` writes `send_email` with nothing but its name.
+ *
+ * **`artifacts` is written and never provisioned (#673).** Its entry is `{ binding, namespace }`, and the namespace
+ * is `<project>-<env>`, derivable offline. There is no create call to make: Cloudflare creates a namespace the first
+ * time a repo is created in it. There is a teardown call, because repos cost storage, and `pithy feature destroy`
+ * makes it.
  */
 export function isWrittenBinding(type: BindingType): boolean {
-  return (
-    type === "d1" ||
-    type === "kv" ||
-    type === "r2" ||
-    type === "ai" ||
-    type === "durable_object" ||
-    type === "ratelimit" ||
-    type === "workflow"
-  );
+  return WRITTEN.has(type);
 }
 
+const WRITTEN = new Set<BindingType>([
+  "d1",
+  "kv",
+  "r2",
+  "ai",
+  "durable_object",
+  "ratelimit",
+  "workflow",
+  "queue",
+  "email",
+  "hyperdrive",
+  "browser",
+  "images",
+  "analytics_engine_datasets",
+  "pipelines",
+  "mtls_certificates",
+  "dispatch_namespaces",
+  "artifacts",
+]);
+
+/**
+ * The kinds whose wrangler entry names an account-level resource the adopter creates, and what wrangler calls
+ * that field — what `BindingSpec.target` is written as. `true` where wrangler refuses the entry without it.
+ */
+export const TARGET_KINDS: Readonly<Partial<Record<BindingType, { field: string; required: boolean }>>> = {
+  hyperdrive: { field: "id", required: true },
+  mtls_certificates: { field: "certificate_id", required: true },
+  pipelines: { field: "stream", required: true },
+  dispatch_namespaces: { field: "namespace", required: true },
+  analytics_engine_datasets: { field: "dataset", required: false },
+};
+
 /**
  * A JavaScript class name — what `className` may be.
  *
@@ -101,13 +213,16 @@ const CLASS_NAME = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
  */
 const CLASS_MODULE = /^(@[a-z0-9~-][a-z0-9._~-]*\/)?[a-z0-9~-][a-z0-9._~-]*(\/[A-Za-z0-9_~-][A-Za-z0-9._~-]*)*$/;
 
+/** What a `target` may be: a Cloudflare id or resource name, starting alphanumeric. */
+const TARGET = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
 /**
  * The kinds whose resource Pithy names and creates — the only kinds `scope` and `resource` mean anything
  * for.
  *
  * {@link FEATURE_RESOURCE_KINDS} rather than a fresh literal, because it is already the repo's answer to
  * "which bindings does a provisioning run compose a `<project>-<scope>-<thing>` name for": it is the
- * domain of `ProvisionScope.resource`, and the CLI's own `PROVISIONABLE` map is the same three. Every
+ * domain of `ProvisionScope.resource`, and the CLI's own `PROVISIONABLE` map is the same four. Every
  * other kind's name is composed by a different rule with no `<thing>` slot to fill — a Workflow's from
  * the capability and the job, a Worker script's by wrangler — and a `secret` already states its scope in
  * `defineSecretRegistry`, where the value it names lives.
@@ -159,6 +274,16 @@ export const BindingSpec = z
       .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.',
       ),
+    target: z
+      .string()
+      .min(1)
+      // An id or a resource name, never prose: a manifest is third-party data out of `node_modules`, and this
+      // string lands in the adopter's `wrangler.jsonc` and in every stanza the kit carries it into.
+      .regex(TARGET, "A target is a resource id or name: letters, digits, `.`, `_` and `-`.")
+      .optional()
+      .describe(
+        "The account-level resource this binding addresses, which the adopter creates themselves: a Hyperdrive config id, an mTLS certificate id, a Pipelines stream, a dispatch namespace, or an Analytics Engine dataset. Written into the field wrangler names for it (`id`, `certificate_id`, `stream`, `namespace`, `dataset`), and carried whole into every environment, because the resource is the account's. Required for `hyperdrive`, `mtls_certificates`, `pipelines` and `dispatch_namespaces`; optional for `analytics_engine_datasets`. Refused on every other kind.",
+      ),
     remote: z
       .boolean()
       .optional()
@@ -169,7 +294,7 @@ export const BindingSpec = z
       .enum(["environment", "global"])
       .optional()
       .describe(
-        "Whether the resource behind this binding is one per environment (absent, the default) or one for the whole project. A `global` resource takes the literal `global` where the environment segment goes — `<project>-global-<thing>` — so every environment's stanza names the identical resource and provisioning creates it once. Declare it where the data is not an environment-local fact: `@pithy-sh/email`'s suppression list is one per project, because an unsubscribe recorded through a staging Worker has to be honored by a production one, and three per-environment databases meant it was not (#513). Say nothing where it is: a session store, a cache, and `@pithy-sh/secrets`' own database are per environment, and one line apart in the same env there is no convention to tell them apart by — which is why this is declared rather than inferred. Meaningful only for a `d1`, `kv` or `r2` binding.",
+        "Whether the resource behind this binding is one per environment (absent, the default) or one for the whole project. A `global` resource takes the literal `global` where the environment segment goes — `<project>-global-<thing>` — so every environment's stanza names the identical resource and provisioning creates it once. Declare it where the data is not an environment-local fact: `@pithy-sh/email`'s suppression list is one per project, because an unsubscribe recorded through a staging Worker has to be honored by a production one, and three per-environment databases meant it was not (#513). Say nothing where it is: a session store, a cache, and `@pithy-sh/secrets`' own database are per environment, and one line apart in the same env there is no convention to tell them apart by — which is why this is declared rather than inferred. Meaningful only for a `d1`, `kv`, `r2` or `queue` binding.",
       ),
     resource: z
       .string()
@@ -181,7 +306,7 @@ export const BindingSpec = z
       .regex(NAME_SEGMENT, "A resource is one name segment: lowercase letters, digits, and single hyphens.")
       .optional()
       .describe(
-        "The `<thing>` segment of this resource's name, when it is not the kebabbed binding name. Absent is the ordinary case and means the binding name is the segment (`EMAIL_SUPPRESSIONS` → `email-suppressions`). Declare it where the two must differ: `SUPPORT_BUCKET` backs `<project>-global-support`, because the binding keeps `_BUCKET` for whoever reads `env.SUPPORT_BUCKET` in a Worker while the resource drops it — `r2` is already the composed name's kind, so the suffix repeats it. Meaningful only for a `d1`, `kv` or `r2` binding.",
+        "The `<thing>` segment of this resource's name, when it is not the kebabbed binding name. Absent is the ordinary case and means the binding name is the segment (`EMAIL_SUPPRESSIONS` → `email-suppressions`). Declare it where the two must differ: `SUPPORT_BUCKET` backs `<project>-global-support`, because the binding keeps `_BUCKET` for whoever reads `env.SUPPORT_BUCKET` in a Worker while the resource drops it — `r2` is already the composed name's kind, so the suffix repeats it. Meaningful only for a `d1`, `kv`, `r2` or `queue` binding.",
       ),
   })
   .describe("Declares a Cloudflare binding a capability requires in the Worker env.")
@@ -234,10 +359,31 @@ export const BindingSpec = z
           code: "custom",
           input: ctx.value,
           path: [field],
-          message: `Binding "${ctx.value.name}" declares a ${field}, which only a d1, kv or r2 binding has — this one is a ${ctx.value.type}.`,
+          message: `Binding "${ctx.value.name}" declares a ${field}, which only a d1, kv, r2 or queue binding has — this one is a ${ctx.value.type}.`,
         });
       }
     }
+    // `target` is the resource a carried kind addresses, written into the one field wrangler names for it. A kind
+    // that requires it is refused without it — wrangler refuses the entry, and a writer emitting one would stop
+    // `wrangler dev` and `wrangler deploy` both. A kind with no such field is refused with it, for the reason
+    // `scope` is: a declaration nothing writes reads, in the spec, as one that was honored.
+    const target = TARGET_KINDS[ctx.value.type];
+    if (target?.required && ctx.value.target === undefined) {
+      ctx.issues.push({
+        code: "custom",
+        input: ctx.value,
+        path: ["target"],
+        message: `Binding "${ctx.value.name}" needs a target — the ${ctx.value.type} resource it addresses, written as \`${target.field}\`.`,
+      });
+    }
+    if (target === undefined && ctx.value.target !== undefined) {
+      ctx.issues.push({
+        code: "custom",
+        input: ctx.value,
+        path: ["target"],
+        message: `Binding "${ctx.value.name}" declares a target, which a ${ctx.value.type} binding does not take.`,
+      });
+    }
   });
 export type BindingSpec = z.infer<typeof BindingSpec>;