@pithy-sh/core 0.10.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/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>;
 

package/src/capability/capability.ts

@@ -2,8 +2,9 @@
 // SPDX-License-Identifier: MIT
 
 import type { ExecutionContext, ForwardableEmailMessage } from "@cloudflare/workers-types";
-import type { Hono } from "hono";
+import type { Hono, MiddlewareHandler } from "hono";
 import type { z } from "zod";
+import type { ActingOrganizationResolver } from "../access/acting";
 import type { AuditEmit } from "../audit/recorder";
 import type { ControlPlaneContext } from "../controlPlane/context";
 import type { AdminRoute } from "../controlPlane/discovery/adminRoute";
@@ -31,6 +32,19 @@ import type { CapabilitySettings } from "./settings";
 export interface PithyVars {
   /** The authenticated identity, populated by `@pithy-sh/auth`; `null` until a strategy sets it. */
   auth: AuthContext | null;
+  /**
+   * Which organization this request acts for, and what the caller's role there allows — a resolver,
+   * populated by `@pithy-sh/organization`'s middleware. With no organization capability composed it is
+   * {@link import("../access/acting").noActingOrganization}, which answers `null`: nothing is in force,
+   * every record a request writes carries a null organization, and every rule that admits by organization
+   * admits nobody.
+   *
+   * **A seam beside {@link auth}, never a field on it.** `auth` says who is signed in; this says what they
+   * may do *here*, and a capability that gates on it — media, storage — must not import the capability
+   * that computes it. Lazy, because resolving it is a D1 read most requests never need; read it with
+   * `await c.var.actingOrganization()`, or through `accessCaller` in `access/access.ts`.
+   */
+  actingOrganization: ActingOrganizationResolver;
   /**
    * The resolved request locale, populated by `@pithy-sh/i18n`'s middleware; `null` in a Worker that
    * does not compose it — which is what "nothing was negotiated" looks like, as distinct from "the
@@ -132,6 +146,12 @@ export type PithyHonoEnv = { Bindings: Record<string, unknown>; Variables: Pithy
 
 export type PithyMiddleware = (app: Hono<PithyHonoEnv>) => void;
 
+/**
+ * One readiness guard: a handler that refuses because **this Worker** is in a bad state. See
+ * {@link Capability.readiness} for where it runs and where it does not.
+ */
+export type PithyReadinessGuard = MiddlewareHandler<PithyHonoEnv>;
+
 /**
  * The structural seam for one capability's secret-registry slice — secret name → its declaration.
  * Core carries it on the {@link Capability} contract so a capability can declare which secrets it
@@ -230,29 +250,18 @@ export type SecretBranchSeam = Record<string, readonly string[]>;
 export type InapplicableSecretSeam = Record<string, string>;
 
 /**
- * The structural seam for one capability's token-profile slice — profile name → the scoped CF API
- * token that capability's code needs. Declared next to the code that uses it (alongside
- * {@link Capability.secretRegistry}), so a capability owns its token's least-privilege scope and where
- * the minted value lands. Core carries only the structural axes (never interpreted here); the concrete
- * `TokenProfile`, the permission catalog, `defineTokenProfile`, and the mint engine live in
- * `@pithy-sh/cloudflare`/the CLI. `pithy token` aggregates every capability's slice into one registry.
+ * One route a capability gates on an `AuthContext` scope — see {@link Capability.scopeGates}.
+ *
+ * Descriptive, never behavioral: the gate itself is the capability's own middleware, and this is what a
+ * diagnostic reads to name it. `route` is the method and the mounted path, as the route table writes them.
  */
-export interface TokenProfileSeam {
-  /** The CF permissions the token grants, as short catalog keys (`d1:read`, `secrets:write`). */
-  readonly permissions: readonly string[];
-  /** The resource scope: `"account"` (the whole account, the default) or an explicit CF resource map. */
-  readonly resources?: "account" | Record<string, string>;
-  /** The secret-registry name the minted value is stored under — its backend decides the destination. */
-  readonly secret?: string;
-  /** A built-in destination override (`dev-vars` | `ephemeral` | `secrets-store`) for a tooling profile. */
-  readonly defaultStore?: string;
-  /** Why the profile exists / what consumes it — surfaced in `pithy token` help and docs. */
-  readonly description?: string;
+export interface ScopeGate {
+  /** The scope the gate requires, as the resolved config names it — `leaderboard:submit`. */
+  readonly scope: string;
+  /** The method and mounted path it guards, `POST /leaderboard/:board`. */
+  readonly route: string;
 }
 
-/** A capability's token-profile slice: profile name → {@link TokenProfileSeam}. */
-export type TokenProfileSeamMap = Record<string, TokenProfileSeam>;
-
 /**
  * One thing an **adopter** plugged into a capability — the capability's own name for something the kit
  * did not ship and cannot enumerate. `@pithy-sh/auth` declares one per additional Better Auth plugin
@@ -379,13 +388,6 @@ export interface Capability<
    * whenever it is composed declares nothing, which is the ordinary case.
    */
   inapplicableSecrets?: InapplicableSecretSeam;
-  /**
-   * The scoped CF API tokens this capability's code needs, as a token-profile slice (profile name →
-   * {@link TokenProfileSeam}). Additive and optional, and declared next to {@link Capability.secretRegistry}
-   * — the value of a minted token lands in the secret the profile names. `pithy token` aggregates every
-   * capability's slice with the built-in tooling profiles into one registry.
-   */
-  tokenProfiles?: TokenProfileSeamMap;
   /**
    * Extra CF permissions this capability needs the **CI system token** to hold, as short catalog keys
    * (e.g. `email:routing` for email provisioning, `kv:write` for a module that seeds KV in CI). They
@@ -393,6 +395,20 @@ export interface Capability<
    * extends what CI can do without the adopter hand-editing token scopes. Additive and optional.
    */
   ciPermissions?: readonly string[];
+  /**
+   * The CF permissions this capability's **deployed Workers** call Cloudflare with, as short catalog keys
+   * (`secrets:write`, `images:write`, `analytics:read`). The runtime counterpart of {@link ciPermissions}.
+   *
+   * **A deployed application holds one Cloudflare API token, and this is the only way into it (#728).**
+   * Every composed capability's keys union into the project-level `runtime` profile, minted per
+   * environment into the Secrets Store and read by every Worker of that environment through one binding,
+   * the way every capability's `ciPermissions` union into the one `ci-system` token. A capability cannot
+   * declare a token of its own. A project whose composition declares none mints no runtime token.
+   *
+   * Build it from the resolved config, as `secretRegistry` is built: a capability configured to call
+   * nothing on Cloudflare declares nothing, and adds nothing to the token. Additive and optional.
+   */
+  runtimePermissions?: readonly string[];
   /**
    * The admin routes this capability contributes behind the `control-plane` strategy, described well
    * enough for a management client to call them — full mounted path, required scope, and a one-line
@@ -539,8 +555,30 @@ export interface Capability<
    * parsed with. A capability with no socket leaves it unset.
    */
   sockets?: readonly SocketChannel[];
-  /** Composable middleware (e.g. turnstile(), requireAuth()). */
+  /**
+   * Composable middleware (e.g. turnstile(), requireAuth()). Runs on every request, the control-plane
+   * surface included. A refusal that protects a route — a rate limit, authentication, a CSRF check —
+   * belongs here. A refusal because the Worker itself is broken belongs in {@link Capability.readiness}.
+   */
   middleware?: PithyMiddleware[];
+  /**
+   * Guards that refuse because **this Worker is misconfigured or unprovisioned** — `@pithy-sh/vector`'s
+   * `provisionGuard`, when the deployed index disagrees with config. Not for protecting a route: a rate
+   * limit, authentication and a CSRF check refuse a *caller*, and they belong in
+   * {@link Capability.middleware}.
+   *
+   * `createBackend` mounts every readiness guard after every capability's `middleware` and before any
+   * capability's routes, so the verifier, `emit` and every rate limit are already in place. It skips
+   * each guard on the admin surface — every composed capability's `adminRoutes`, the seam's own
+   * included, the set CORS is derived from. The control plane is the diagnostic surface, so it cannot
+   * sit behind the faults it diagnoses. Every other request meets the guard, `GET /health` aside, which
+   * is registered ahead of all of it.
+   *
+   * A handler rather than a registrar like `middleware`, because core decides where it mounts. A guard
+   * that wanted its own path would be deciding the exemption by path shape, which is the thing this
+   * exists to take away from it.
+   */
+  readiness?: PithyReadinessGuard[];
   /**
    * Whether this capability fills the entitlement seam — replaces `c.var.entitlements` with a real
    * resolver. `@pithy-sh/payments` declares it; nothing else does today.
@@ -552,6 +590,27 @@ export interface Capability<
    * flag and say so, which turns a fleet of production 403s into one line at startup.
    */
   providesEntitlements?: boolean;
+  /**
+   * Whether this capability fills `AuthContext.scopes` — whether anything will ever put a string in the
+   * array the scope gates read. `@pithy-sh/auth` declares it when an adopter supplies `resolveScopes`, and
+   * not otherwise (#560).
+   *
+   * The same reason {@link providesEntitlements} exists, one seam over. Every scope gate fails closed, so a
+   * Worker composing `leaderboard` with no resolver is not broken: it refuses every caller on the gated
+   * routes, forever, and the runtime cannot tell that from a caller who simply is not trusted. `pithy doctor`
+   * compares this flag against {@link scopeGates} and says so.
+   */
+  providesScopes?: boolean;
+  /**
+   * The routes this capability gates on an `AuthContext` scope, built from the resolved config — a gate the
+   * config has switched off is not declared. Omit it when nothing is gated, which is the ordinary case.
+   *
+   * **Declared so the CLI can name what will deny.** With no capability composed that
+   * {@link providesScopes}, every route listed here answers 403 to every caller, and `pithy doctor` names
+   * each one. Each capability's route-contract test holds this list to the `scopes` its `describeRoute`s
+   * carry, so the declaration cannot drift from the routes.
+   */
+  scopeGates?: readonly ScopeGate[];
   /**
    * This capability's client-safe projection — the **only** values of its config that may reach a
    * browser bundle. Resolved at build time against a {@link ClientProjectionContext} (the environment),
@@ -599,6 +658,17 @@ export interface Capability<
    * time, and read by `pithy doctor`.
    */
   extensions?: readonly CapabilityExtension[];
+  /**
+   * The role powers this capability's own routes gate on, through the acting-organization seam —
+   * `media:manage`, `storage:manage`. Omit it when a capability asks no power, which is the normal case.
+   *
+   * **Declared so the catalog requirement can be conditional.** `@pithy-sh/organization` refuses a role
+   * catalog in which no role holds a power a composed capability gates on — a route nobody could ever use
+   * — and a project that composes no media must not be refused for not placing `media:manage`. The
+   * organization capability reads this list at compose, across every composed capability, rather than
+   * importing any of them.
+   */
+  powers?: readonly string[];
   /** Bindings this capability needs in the env (normalized — `optional` is always set). */
   requiredBindings: BindingSpec[];
 }