@pithy-sh/core 0.10.0 → 0.12.0

package/src/access/policyCheck.ts

@@ -0,0 +1,77 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import {
+  type CapabilitySettings,
+  SettingsAccountIncomplete,
+  type SettingsFinding,
+  type UnansweredEnvironment,
+} from "../capability/settings";
+import { outsidePolicy, type VisibilityPolicy } from "./visibility";
+
+/**
+ * `pithy doctor`'s check for records a narrowed visibility policy no longer allows.
+ *
+ * **Narrowing `allowed` never rewrites a record.** Making a public file private breaks every link already
+ * published — and for media each one is a Cloudflare call before its bytes are signed — so the kit does
+ * not do it behind anyone's back. A write that would create a record outside the policy is refused; the
+ * records already outside it are named, here, per deployed environment, and moving them is the adopter's
+ * explicit act.
+ *
+ * The local tier says nothing: which records exist is a fact about a deployed database, which only the
+ * account tier can read. An unprovisioned environment, or an account that cannot be reached, is unchecked
+ * rather than clean — and only that environment is: the others are still asked, and what they hold is still
+ * named ({@link SettingsAccountIncomplete}).
+ */
+export interface RecordsOutsidePolicyOptions {
+  /** The capability, for the finding's wording — `media`, `storage`. */
+  readonly capability: string;
+  /** What one record is called, for the finding's wording — `media record`, `file`. */
+  readonly noun: string;
+  /** The table the records live in, as named in SQL. */
+  readonly table: string;
+  /** The resolved policy this Worker composes. */
+  readonly policy: VisibilityPolicy;
+  /** How to move one record to an allowed level — the route or the call. */
+  readonly remedy: string;
+}
+
+/** The settings check: every record outside the policy, named, per deployed environment. */
+export function recordsOutsidePolicy(options: RecordsOutsidePolicyOptions): CapabilitySettings {
+  const levels = outsidePolicy(options.policy);
+  return {
+    local: () => [],
+    async account(context) {
+      if (levels.length === 0) return [];
+      const findings: SettingsFinding[] = [];
+      const unanswered: UnansweredEnvironment[] = [];
+      for (const environment of context.environments) {
+        if (environment.name === "dev") continue;
+        let ids: readonly string[];
+        try {
+          ids = await context.account.appRows({
+            environment: environment.name,
+            workerDirectory: context.workerDirectory,
+            table: options.table,
+            column: "visibility",
+            values: levels,
+          });
+        } catch (cause) {
+          // Staging stood up before prod is the ordinary bring-up. Prod is unchecked; staging still answers.
+          unanswered.push({ environment: environment.name, cause });
+          continue;
+        }
+        if (ids.length === 0) continue;
+        const plural = ids.length === 1 ? options.noun : `${options.noun}s`;
+        findings.push({
+          setting: `${options.capability} visibility.allowed`,
+          environment: environment.name,
+          problem: `${ids.length} ${plural} ${ids.length === 1 ? "is" : "are"} ${levels.join(" or ")}, which visibility.allowed (${options.policy.allowed.join(", ")}) no longer allows: ${ids.join(", ")}.`,
+          action: `Nothing is rewritten for you. ${options.remedy}, or widen visibility.allowed in ${context.workerDirectory}'s pithy.config.ts.`,
+        });
+      }
+      if (unanswered.length > 0) throw new SettingsAccountIncomplete(findings, unanswered);
+      return findings;
+    },
+  };
+}

package/src/access/usage.ts

@@ -0,0 +1,141 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { type Kysely, type RawBuilder, sql } from "kysely";
+import { z } from "zod";
+
+/**
+ * What an account is holding — records and bytes, per owner and per organization — for the control plane.
+ *
+ * ## A per-owner figure is always an organization's figure
+ *
+ * **A report run by an organization for user X filters by that organization's id**, because the
+ * organization must never learn that the same person holds an account in another one. The number alone
+ * leaks it: a per-user total summed across organizations discloses that the user exists elsewhere, with no
+ * name attached and no row shown — the figure simply does not reconcile with what the organization can
+ * see. So an unscoped per-owner read is not a convenience this offers. It is a read that does not exist:
+ * {@link UsageQuery} refuses `groupBy: "owner"` and an `ownerId` filter unless an organization is named,
+ * and every per-owner row is keyed by the organization it was counted in.
+ *
+ * Duplicate detection is the same disclosure in different clothes — *does anybody hold this file* against
+ * *how much does this person hold* — and both are closed by the same column. Neither consults an
+ * adopter's permission hook: a hook that widened a per-subject total would reopen exactly this.
+ *
+ * ## The organization is the column, not a join
+ *
+ * Counted by the `organizationId` written on each record, which is the fact at the time of the write. A
+ * join through current membership would re-attribute last quarter's bytes the moment somebody changed
+ * organization. Only stored records count — a pending upload holds nothing yet, and a failed one never
+ * will.
+ *
+ * ## Indexed
+ *
+ * The tables carry `(organizationId, createdAt)` and `(ownerId, createdAt)`, so an organization's slice
+ * over a window is one index range and a grouping by organization walks the index rather than sorting.
+ */
+
+/** The sentinel that names records written with no organization in force — a query string cannot say null. */
+export const NO_ORGANIZATION = "none";
+
+const Id = z.string().min(1).max(128);
+
+/** What a usage read asks. */
+export const UsageQuery = z
+  .object({
+    groupBy: z
+      .enum(["owner", "organization"])
+      .describe(
+        "`organization` is one row per organization; `owner` is one row per owner within the organization named, never across organizations.",
+      ),
+    organizationId: Id.optional().describe(
+      "Restrict to one organization. Required with `groupBy=owner` and with `ownerId`, because a per-owner figure is only ever an organization's. `none` is the records written with no organization in force.",
+    ),
+    ownerId: Id.optional().describe("Restrict to one owner, within the organization named."),
+    since: z.iso.datetime().optional().describe("Count records created at or after this instant, ISO-8601."),
+    until: z.iso.datetime().optional().describe("Count records created before this instant, ISO-8601."),
+    limit: z.coerce.number().int().min(1).max(500).optional().describe("The most rows to return. 100 by default."),
+  })
+  .describe("A request for records and bytes held, grouped by owner or by organization.")
+  .check((ctx) => {
+    if (ctx.value.organizationId !== undefined) return;
+    if (ctx.value.groupBy !== "owner" && ctx.value.ownerId === undefined) return;
+    ctx.issues.push({
+      code: "custom",
+      input: ctx.value,
+      path: ["organizationId"],
+      message: `A per-owner read names its organization. Pass organizationId, or \`${NO_ORGANIZATION}\` for records written with none.`,
+    });
+  });
+export type UsageQuery = z.output<typeof UsageQuery>;
+
+/** One row of a usage read. */
+export const UsageRow = z
+  .object({
+    organizationId: z
+      .string()
+      .nullable()
+      .describe("The organization these records were written under. Null for records written with none."),
+    ownerId: z
+      .string()
+      .nullable()
+      .optional()
+      .describe("The owner, on a per-owner read. Null for system-owned records. Absent on a per-organization read."),
+    records: z.number().int().nonnegative().describe("How many stored records."),
+    bytes: z.number().int().nonnegative().describe("Their total size in bytes. A record of unknown size counts zero."),
+  })
+  .describe("Records and bytes held by one organization, or by one owner within one organization.");
+export type UsageRow = z.infer<typeof UsageRow>;
+
+/** What a usage read answers. */
+export const UsageResponse = z
+  .object({
+    rows: z.array(UsageRow).describe("Largest first. Capped at the requested limit."),
+    truncated: z.boolean().describe("Whether more rows matched than were returned."),
+  })
+  .describe("Records and bytes held, grouped as asked.");
+export type UsageResponse = z.infer<typeof UsageResponse>;
+
+/** The default page of a usage read. */
+const DEFAULT_LIMIT = 100;
+
+/** Rows as SQLite returns them, before the counts are made numbers. */
+export interface RawUsageRow {
+  organizationId: string | null;
+  ownerId?: string | null;
+  records: number | string;
+  bytes: number | string | null;
+}
+
+/**
+ * The statement a usage read runs, over one record table — `pithyMediaAssets`, `pithyStorageObjects` —
+ * carrying `ownerId`, `organizationId`, `size`, `status` and `createdAt`. Exported so a test can ask SQLite
+ * how it plans the very statement {@link usageRollup} executes. Every value is a bound parameter.
+ */
+export function usageStatement(table: string, query: UsageQuery): RawBuilder<RawUsageRow> {
+  const limit = query.limit ?? DEFAULT_LIMIT;
+  const organization = sql.ref("organizationId");
+  const owner = sql.ref("ownerId");
+  const filters = [sql`${sql.ref("status")} = 'stored'`];
+  if (query.organizationId === NO_ORGANIZATION) filters.push(sql`${organization} is null`);
+  else if (query.organizationId !== undefined) filters.push(sql`${organization} = ${query.organizationId}`);
+  if (query.ownerId !== undefined) filters.push(sql`${owner} = ${query.ownerId}`);
+  if (query.since !== undefined) filters.push(sql`${sql.ref("createdAt")} >= ${Date.parse(query.since)}`);
+  if (query.until !== undefined) filters.push(sql`${sql.ref("createdAt")} < ${Date.parse(query.until)}`);
+
+  const keys = query.groupBy === "owner" ? sql`${organization}, ${owner}` : sql`${organization}`;
+  return sql<RawUsageRow>`select ${keys}, count(*) as records, coalesce(sum(${sql.ref("size")}), 0) as bytes from ${sql.table(table)} where ${sql.join(filters, sql` and `)} group by ${keys} order by bytes desc limit ${limit + 1}`;
+}
+
+/** Read usage off one record table through any Kysely over D1 with the `CamelCasePlugin`. */
+export async function usageRollup(db: Kysely<unknown>, table: string, query: UsageQuery): Promise<UsageResponse> {
+  const limit = query.limit ?? DEFAULT_LIMIT;
+  const result = await usageStatement(table, query).execute(db);
+  const byOwner = query.groupBy === "owner";
+  const rows = result.rows.slice(0, limit).map((row) => ({
+    organizationId: row.organizationId ?? null,
+    ...(byOwner ? { ownerId: row.ownerId ?? null } : {}),
+    records: Number(row.records),
+    bytes: Number(row.bytes ?? 0),
+  }));
+  return { rows, truncated: result.rows.length > limit };
+}

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/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/audit/recorder.ts

@@ -1,7 +1,8 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 
-import type { AuditEventInput } from "./auditEvent";
+import type { Loggable } from "../privacy/types";
+import type { AuditEventInput, AuditMetadata } from "./auditEvent";
 
 /**
  * The recorder seam. `emit()` on the request context (`c.var.emit`) takes one {@link AuditEventInput}
@@ -12,8 +13,15 @@ import type { AuditEventInput } from "./auditEvent";
  * `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.
+ *
+ * **`metadata` refuses a value marked with a privacy class** (#132). The trail is the longest-lived internal
+ * surface there is — a row in the adopter's D1 with no retention window — so a `pii()`/`phi()`/`secret()`/
+ * `pci()` value in it, or inside an object in it, is a compile error, by the same `Loggable` rule the logger
+ * applies. `AuditMetadata` the schema stays permissive: a stored row still parses.
  */
-export type AuditEmit = (event: AuditEventInput) => Promise<void>;
+export type AuditEmit = <M extends AuditMetadata = AuditMetadata>(
+  event: Omit<AuditEventInput, "metadata"> & { metadata?: (M & Loggable<M>) | null | undefined },
+) => Promise<void>;
 
 /**
  * The default recorder when no audit capability is composed: accept the event and drop it. Resolves

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>;