@pithy-sh/core 0.10.0 → 0.11.0

package/src/controlPlane/migrationState/migrationState.ts

@@ -0,0 +1,200 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import type { MigrationProvider } from "kysely/migration";
+import type { Capability } from "../../capability/capability";
+import { composeDatabases } from "../../data/databases";
+import { InternalError } from "../../error/pithyError";
+import { collectMigrationSets } from "../../migrations/capabilitySets";
+import { composedMigrationKey, createMigrationRegistry, decomposeMigrationKey } from "../../migrations/registry";
+import { readMigrationLedger } from "../../migrations/runner";
+import { type MigrationLastGroup, readMigrationState } from "../../migrations/state";
+import type { CapabilityHealthInput } from "../discovery/health";
+import type { HealthSummary } from "../discovery/healthSummary";
+import type { MigrationDatabaseView, MigrationGroupView, MigrationView } from "../http/responses";
+import { MIGRATIONS_READ_SCOPE } from "../scope/scope";
+
+/**
+ * **Migration state over the control plane (#729).**
+ *
+ * A management client could not answer what is applied where, or whether a deploy left something behind:
+ * the seam registered a ping, the manifest and key rotation, and not one field of it was about a database.
+ * The read already existed — {@link readMigrationLedger} answers both directions — and it needs a D1
+ * binding and the composed provider in one process. **The Worker is the only thing holding both**, and it
+ * is the deployed build, so asked from its side the answer cannot be stale the way the project on disk is.
+ *
+ * Two halves. At assembly, {@link composeMigrationDatabases} builds what this Worker declares per bound
+ * database, through `collectMigrationSets` — the function `pithy migrate` composes with, so the route and
+ * `pithy doctor` compose the same way. Not always from the same inputs: on a D1 two Workers share, the CLI
+ * merges both Workers' sets and the route holds only its own, so `pending` and `undeclared` can differ
+ * there. On a database one Worker binds alone they agree. Per request, {@link readDatabaseMigrations} reads
+ * one database for the route and {@link readMigrationHealth} totals all of them for the manifest.
+ *
+ * **Read-only.** Nothing here runs, reverses or resets a migration. A screen somebody opened to ask must
+ * not hand them the thing that changes the schema.
+ *
+ * **`undeclared` is relative to this Worker.** Two Workers can be bound to one physical D1, and the CLI
+ * composes across all of them. A Worker composes only its own capabilities and cannot learn a co-bound
+ * Worker's, so from inside one, every migration the other shipped to the shared database reads as
+ * undeclared. That is why `undeclaredMigrations` grades nothing.
+ */
+
+/** One database this Worker binds, with what this build declares for it. Built once, at assembly. */
+export interface ComposedMigrationDatabase {
+  /** The database name, as capabilities declare it in `databases`. */
+  database: string;
+  /** The D1 binding it is read through. */
+  binding: string;
+  /** Every migration this build declares for it — empty for a database bound with none. */
+  provider: MigrationProvider;
+  /** Each declared migration's namespace, known from the set it came from. */
+  namespaces: ReadonlyMap<string, string>;
+}
+
+/** A provider declaring nothing, for a database bound with no migrations: everything applied is undeclared. */
+const NOTHING_DECLARED: MigrationProvider = { getMigrations: async () => ({}) };
+
+/**
+ * Every database this Worker binds, with the provider this build composes for it, sorted by name.
+ *
+ * One entry per database `composeDatabases` maps to a binding — the same map the request registry is built
+ * from — so a database bound with no migrations is still reported. Leaving it out would read as not bound.
+ */
+export function composeMigrationDatabases(capabilities: readonly Capability[]): ComposedMigrationDatabase[] {
+  const sets = collectMigrationSets([...capabilities]);
+  const registry = createMigrationRegistry(sets);
+  const bound = composeDatabases([...capabilities]);
+  return Object.entries(bound)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([database, group]) => {
+      const namespaces = new Map<string, string>();
+      for (const set of sets) {
+        if (set.database !== database) continue;
+        for (const localKey of Object.keys(set.migrations))
+          namespaces.set(composedMigrationKey(set, localKey), set.namespace);
+      }
+      return { database, binding: group.binding, provider: registry[database] ?? NOTHING_DECLARED, namespaces };
+    });
+}
+
+/**
+ * One migration as the route reports it.
+ *
+ * A declared migration's namespace comes from the set it was declared in. An undeclared one has only its
+ * key, so it is decomposed — and a key no registry composed answers null rather than a guess.
+ */
+export function migrationView(name: string, namespaces: ReadonlyMap<string, string>): MigrationView {
+  return { name, namespace: namespaces.get(name) ?? decomposeMigrationKey(name)?.namespace ?? null };
+}
+
+/** The D1 binding for `entry`, or a refusal naming it — a Worker missing the binding cannot read it. */
+function bindingOf(env: Record<string, unknown>, entry: ComposedMigrationDatabase): D1Database {
+  const database = env[entry.binding];
+  if (database == null) {
+    throw new InternalError({
+      message: `The ${entry.binding} binding is missing, so database "${entry.database}" cannot be read.`,
+      action: `Declare ${entry.binding} in this Worker's wrangler.jsonc, then deploy again.`,
+    });
+  }
+  return database as D1Database;
+}
+
+function groupView(group: MigrationLastGroup, namespaces: ReadonlyMap<string, string>): MigrationGroupView {
+  return {
+    group: group.group,
+    appliedAt: group.appliedAt.toISOString(),
+    migrations: group.migrations.map((name) => migrationView(name, namespaces)),
+    position:
+      group.position.state === "top"
+        ? { state: "top" }
+        : {
+            state: "buried",
+            above: group.position.above,
+            ungrouped: group.position.ungrouped.map((name) => migrationView(name, namespaces)),
+          },
+  };
+}
+
+/**
+ * Read one database's migration state for the route.
+ *
+ * **A database that cannot be read is `unreadable`, and costs only itself.** The cause goes to
+ * `onUnreadable` — the route logs it, where the operator's context stays the operator's — and never into
+ * the view: a D1 error can name a table or a query, and the view crosses to a management client.
+ */
+export async function readDatabaseMigrations(
+  env: Record<string, unknown>,
+  entry: ComposedMigrationDatabase,
+  onUnreadable?: (entry: ComposedMigrationDatabase, cause: unknown) => void,
+): Promise<MigrationDatabaseView> {
+  try {
+    const state = await readMigrationState(bindingOf(env, entry), entry.provider);
+    const view = (name: string) => migrationView(name, entry.namespaces);
+    return {
+      state: "readable",
+      database: entry.database,
+      binding: entry.binding,
+      applied: state.applied.map(view),
+      pending: state.pending.map(view),
+      undeclared: state.undeclared.map(view),
+      lastGroup: state.lastGroup ? groupView(state.lastGroup, entry.namespaces) : null,
+    };
+  } catch (cause) {
+    onUnreadable?.(entry, cause);
+    return { state: "unreadable", database: entry.database, binding: entry.binding };
+  }
+}
+
+/**
+ * The two health keys the seam contributes to its own manifest entry.
+ *
+ * Both `indexed`: one small select per bound database, bounded by the declared migration count rather
+ * than by the adopter's data. Both behind {@link MIGRATIONS_READ_SCOPE}, which the seam's own route
+ * requires, so a connection without it gets no value rather than a zero.
+ *
+ * **`undeclaredMigrations` declares no nominal, on purpose.** From inside one Worker, a database shared
+ * with another lists the other's migrations as undeclared, so `atMost: 0` would report a corrupted chain
+ * on a database that is entirely fine. Null is what a client reads as unknowable, never as healthy (#471).
+ */
+export const MIGRATION_HEALTH_KEYS = [
+  {
+    key: "pendingMigrations",
+    kind: "count",
+    states: null,
+    scope: MIGRATIONS_READ_SCOPE,
+    cost: "indexed",
+    summary: "Migrations this build declares that a bound database has not applied.",
+    nominal: { atMost: 0 },
+  },
+  {
+    key: "undeclaredMigrations",
+    kind: "count",
+    states: null,
+    scope: MIGRATIONS_READ_SCOPE,
+    cost: "indexed",
+    summary:
+      "Migrations a bound database holds that this Worker does not declare. Relative to this Worker: a database shared with another lists that Worker's migrations here.",
+    nominal: null,
+  },
+] as const satisfies CapabilityHealthInput["keys"];
+
+/**
+ * Total pending and undeclared across every bound database, for the manifest.
+ *
+ * **Throws rather than total a database it could not read.** A partial total is a zero for the database
+ * nobody read. The seam catches the throw and reports the summary `unavailable`, which a client reads as
+ * unknown — null is never zero.
+ */
+export async function readMigrationHealth(
+  env: Record<string, unknown>,
+  databases: readonly ComposedMigrationDatabase[],
+): Promise<HealthSummary> {
+  const ledgers = await Promise.all(
+    databases.map((entry) => readMigrationLedger(bindingOf(env, entry), entry.provider)),
+  );
+  return {
+    pendingMigrations: ledgers.reduce((total, ledger) => total + ledger.pending.length, 0),
+    undeclaredMigrations: ledgers.reduce((total, ledger) => total + ledger.undeclared.length, 0),
+  };
+}

package/src/controlPlane/migrations/0003_connection_principal.ts

@@ -0,0 +1,37 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Kysely } from "kysely";
+import type { Migration } from "kysely/migration";
+
+/**
+ * Who sanctioned a connection, what kind of client it is, and what it is for — `#721`.
+ *
+ * **Appended, not folded into `0001`.** The seam has shipped and adopters' databases hold rows written by
+ * it, so the three columns arrive in a migration of their own, as `0002`'s origin did.
+ *
+ * **Nullable, with no default, and nothing backfilled.** A row registered before this carries no
+ * principal, and none can be recovered: most of the trail that might be mined for one names a token
+ * rather than a person, and a principal read off a token name is the self-assertion this issue exists to
+ * end. So null means *registered before principals were recorded*, the connection keeps working exactly
+ * as it did, its purpose may be set with `pithy dashboard connect --update --purpose`, and its principal
+ * is set only by registering again, under a signed-in session.
+ *
+ * **The Worker reads only `actorKind`**, to stamp it onto the audit rows a connection's calls write. The
+ * other two exist for the adopter's own review, on their own side.
+ */
+export const controlplane_0003_connection_principal: Migration = {
+  up: async (db: Kysely<unknown>): Promise<void> => {
+    await db.schema.alterTable("pithyControlplaneConnections").addColumn("authorizedBy", "text").execute();
+    await db.schema.alterTable("pithyControlplaneConnections").addColumn("actorKind", "text").execute();
+    await db.schema.alterTable("pithyControlplaneConnections").addColumn("purpose", "text").execute();
+  },
+
+  down: async (db: Kysely<unknown>): Promise<void> => {
+    // Dropped column by column, newest first, for the reason `0002` gives: D1's engine drops a column in
+    // place, and a twelve-step rebuild would rewrite every row of a table holding live credentials.
+    await db.schema.alterTable("pithyControlplaneConnections").dropColumn("purpose").execute();
+    await db.schema.alterTable("pithyControlplaneConnections").dropColumn("actorKind").execute();
+    await db.schema.alterTable("pithyControlplaneConnections").dropColumn("authorizedBy").execute();
+  },
+};

package/src/controlPlane/scope/scope.ts

@@ -78,8 +78,20 @@ export const MANIFEST_READ_SCOPE: ControlPlaneScope = "manifest:read";
 export const KEYS_ROTATE_SCOPE: ControlPlaneScope = "keys:rotate";
 
 /**
- * Every grantable scope the seam's own routes use — what `pithy dashboard connect` offers by default.
- * Ping is absent because it is not grantable; see {@link ANY_VERIFIED_CALLER}.
+ * Read where each database this Worker binds stands: what is applied, what is pending, what is undeclared,
+ * and which run put it there (#729). Read-only by construction — every route behind it is a `GET`, and
+ * nothing over the seam runs, reverses or resets a migration. The two migration health keys on the seam's
+ * manifest entry sit behind it too, so a connection without it gets no number rather than a zero.
+ */
+export const MIGRATIONS_READ_SCOPE: ControlPlaneScope = "migrations:read";
+
+/**
+ * The seam's base grant — what `pithy dashboard connect` grants whatever the Worker composes. Ping is absent
+ * because it is not grantable; see {@link ANY_VERIFIED_CALLER}.
+ *
+ * **{@link MIGRATIONS_READ_SCOPE} is absent on purpose.** It is a read — every route requiring it is a `GET`
+ * — so `connect` derives it from the seam's `adminRoutes` the way it derives every capability's reads. The
+ * base exists for `keys:rotate`, which is not a read and would otherwise drop out.
  */
 export const SEAM_SCOPES: readonly ControlPlaneScope[] = [MANIFEST_READ_SCOPE, KEYS_ROTATE_SCOPE];
 

package/src/createBackend.ts

@@ -3,6 +3,7 @@
 
 import { Hono } from "hono";
 import { z } from "zod";
+import { noActingOrganization } from "./access/acting";
 import { noopEmit } from "./audit/recorder";
 import { BindingSpec } from "./capability/bindings";
 import type {
@@ -18,6 +19,7 @@ import { validateBindings } from "./capability/validateBindings";
 import { pithyCommandOf } from "./cli/command";
 import { isControlPlaneCapability } from "./controlPlane/capability";
 import { allowedOriginSet, corsSurface, registerControlPlaneCors } from "./controlPlane/http/cors";
+import { registerReadinessGuards } from "./controlPlane/http/readiness";
 import { buildDbRegistry, composeDatabases, type DbRegistry } from "./data/databases";
 import { noEntitlementProvider } from "./entitlement/entitlement";
 import { ValidationError } from "./error/pithyError";
@@ -205,15 +207,19 @@ export function createBackend<
   // not here). Defaults to the CF-native Mode 2 logger — structured records to Workers Logs, zero-config.
   const baseLogger = options.logger ?? createWorkerLogger();
 
+  // Every composed capability's `adminRoutes`, folded per path: the surface CORS answers for, and the
+  // surface no readiness guard may refuse. One computation, so the two cannot disagree.
+  const adminSurface = corsSurface(all);
+
   // **CORS first — before this Worker's own base middleware and before every capability's.**
   //
   // Hono runs middleware in registration order, so whatever registers first is the only thing that can
   // put a header on a response somebody else short-circuits. Capabilities short-circuit for real
-  // reasons: `@pithy-sh/vector`'s `provisionGuard` is an `app.use("*")` that throws on every request
-  // when the provision record disagrees with config. Register CORS after that and a misprovisioned
-  // Worker answers a management call with no `Access-Control-Allow-Origin`, so the dashboard sees the
-  // opaque `fetch` TypeError this exists to remove — on precisely the misconfiguration where the
-  // operator most needs to read the real message. Ahead of `validateBindings` for the same reason.
+  // reasons: a rate limit, or a readiness guard like `@pithy-sh/vector`'s `provisionGuard`, which
+  // throws on every request off the admin surface when the provision record disagrees with config.
+  // Register CORS after either and the refusal reaches a browser with no `Access-Control-Allow-Origin`,
+  // so the dashboard sees the opaque `fetch` TypeError this exists to remove instead of the reason.
+  // Ahead of `validateBindings` for the same reason.
   //
   // It lives here rather than in the capability's `middleware` hook because that hook runs inside the
   // loop below, in the adopter's composition order, and this must not depend on where they listed
@@ -222,7 +228,7 @@ export function createBackend<
   const controlPlane = all.find(isControlPlaneCapability);
   if (controlPlane) {
     const cors = controlPlane.controlPlaneConfig;
-    registerControlPlaneCors(app, corsSurface(all), allowedOriginSet(cors), cors.corsMaxAgeSeconds);
+    registerControlPlaneCors(app, adminSurface, allowedOriginSet(cors), cors.corsMaxAgeSeconds);
   }
 
   let validated = false;
@@ -233,6 +239,9 @@ export function createBackend<
       validated = true;
     }
     if (c.get("auth") === undefined) c.set("auth", null);
+    // Nothing in force until `@pithy-sh/organization`'s middleware publishes a resolver. Media and storage
+    // read it to scope every record, so a Worker with no tenancy answers null rather than throwing.
+    if (c.get("actingOrganization") === undefined) c.set("actingOrganization", noActingOrganization);
     // Null means nothing negotiated, which is not the same fact as "the default was chosen" — only
     // `@pithy-sh/i18n` ever sets it, and `c.var.t` works either way.
     if (c.get("locale") === undefined) c.set("locale", null);
@@ -316,6 +325,15 @@ export function createBackend<
   for (const cap of all) {
     for (const middleware of cap.middleware ?? []) middleware(app);
   }
+  // Readiness guards after every capability's middleware, so the verifier, `emit` and every rate limit
+  // are in place, and before any capability's routes, so a terminal handler cannot outrun them. Each is
+  // skipped on the admin surface: the control plane answers whatever else is wrong with the Worker,
+  // because it is how a management client finds out what that is (#763).
+  registerReadinessGuards(
+    app,
+    adminSurface,
+    all.flatMap((cap) => cap.readiness ?? []),
+  );
   // Each hook's slice of the route table is noted as it mounts, so the OpenAPI contract can tag every
   // operation with the capability that owns it (`openapi/routeGroups.ts`).
   for (const cap of all) {

package/src/createEntrypoint.ts

@@ -4,6 +4,7 @@
 import type { ExecutionContext, ForwardableEmailMessage } from "@cloudflare/workers-types";
 import type { Capability, CapabilityEmailHandler } from "./capability/capability";
 import { type CreateBackendOptions, createBackend } from "./createBackend";
+import { withLocalServices } from "./worker/serviceLoopback";
 import { triggerWorkflow } from "./workflow/dispatch";
 import { composeWorkflows, scheduledWorkflows } from "./workflow/register";
 
@@ -88,7 +89,11 @@ export function createEntrypoint<
   const registry = composeWorkflows(all);
   const scheduled = scheduledWorkflows(registry);
 
-  const entrypoint: PithyEntrypoint = { fetch: (request, env, ctx) => app.fetch(request, env, ctx) };
+  // Under `pithy dev`, a service binding's local stand-in goes into the env before anything reads it — the
+  // binding check included (#617). Anywhere else this hands back the env it was given.
+  const entrypoint: PithyEntrypoint = {
+    fetch: (request, env, ctx) => app.fetch(request, withLocalServices(env), ctx),
+  };
 
   // Cron-carrying jobs get the Worker's one `scheduled` entry. Each is started independently so one
   // job whose binding is missing cannot stop the rest of the schedule from running; the failure is
@@ -102,7 +107,7 @@ export function createEntrypoint<
         // can never receive on a schedule therefore fails loudly here, which is the author's bug and
         // is exactly what should surface.
         try {
-          await triggerWorkflow(env, registry, entry.key, {});
+          await triggerWorkflow(withLocalServices(env), registry, entry.key, {});
         } catch (error) {
           failures.push(error);
         }
@@ -114,7 +119,8 @@ export function createEntrypoint<
   // Only expose an `email` handler when something actually handles inbound mail — an inert one would
   // silently drop any message Email Routing delivered to this Worker.
   if (handlers.length > 0) {
-    entrypoint.email = async (message, env, ctx) => {
+    entrypoint.email = async (message, given, ctx) => {
+      const env = withLocalServices(given);
       if (handlers.length === 1) {
         await handlers[0]?.(message, env, ctx);
         return;

package/src/entitlement/allowance.ts

@@ -0,0 +1,85 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Context } from "hono";
+import type { PithyHonoEnv } from "../capability/capability";
+import { InternalError, messageOf } from "../error/pithyError";
+import type { MeterLimit } from "./entitlement";
+
+/**
+ * The allowance readers — how much the current caller may have, and whether a switch is on.
+ *
+ *   const seats = await quota(c, "seats");                  // number, or null for unlimited
+ *   if (seats !== null && (await countMembers(orgId)) >= seats) throw new SeatLimitReached(…);
+ *   if (await feature(c, "auditExport")) { … }               // boolean, never null
+ *
+ * **Neither takes an entitlement key, and that is the point.** A route does not know which tier the
+ * caller's holder is on, and during an upgrade overlap it holds two. The provider resolves across every
+ * key the holder has and answers the higher, so an adopter compares numbers and never ranks tiers.
+ *
+ * **Read, never enforced.** A quota denies nothing on its own and a feature set to `false` denies
+ * nothing either — `requireEntitlement` still gates on the key alone. What a number means for a request
+ * is the adopter's code to decide, because only the adopter can count what it owns.
+ *
+ * **They live in core for the reason `requireEntitlement` does.** A reader that arrived with
+ * `@pithy-sh/payments` would be absent when payments is, and a route reading an allowance must then fail
+ * rather than read something. So with no provider composed — or one that declares no allowances — both
+ * throw `core/internal` naming the gap. Never `0`, which is a paywall shut for a reason nobody can see;
+ * never unlimited, which is a paywall that does not exist.
+ */
+
+/** The refusal when nothing on the request can answer an allowance. The adopter's wiring, so `core/internal`. */
+function noProvider(c: Context<PithyHonoEnv>, kind: "quota" | "feature", name: string): InternalError {
+  const provider = c.var.entitlements?.provider ?? null;
+  return new InternalError({
+    message: `No ${kind} "${name}" can be resolved here.`,
+    action: "Compose a payments capability that declares its entitlements in this Worker's pithy.config.ts.",
+    detail:
+      provider === null
+        ? `no entitlement provider is composed, so ${kind}("${name}") has nothing to read.`
+        : `${provider} resolves entitlements and declares no allowances, so ${kind}("${name}") has nothing to read.`,
+  });
+}
+
+/** How many of `name` the caller's holder may have: a whole number, or `null` for unlimited. */
+export async function quota(c: Context<PithyHonoEnv>, name: string): Promise<number | null> {
+  const resolver = c.var.entitlements;
+  if (!resolver?.quota) throw noProvider(c, "quota", name);
+  return resolver.quota(name);
+}
+
+/** Whether `name` is on for the caller's holder. Always a boolean. */
+export async function feature(c: Context<PithyHonoEnv>, name: string): Promise<boolean> {
+  const resolver = c.var.entitlements;
+  if (!resolver?.feature) throw noProvider(c, "feature", name);
+  return resolver.feature(name);
+}
+
+/**
+ * The ceiling a capability enforces on a meter it counts itself, for the current caller.
+ *
+ * **No provider, or one that binds nothing to this meter, is `{ enforced: false }`** — and the capability
+ * keeps its own configured ceiling. Enforcement is opt-in per meter because a cap that arrives by surprise
+ * breaks an adopter who was already over it.
+ *
+ * **A provider that throws refuses, and logs.** Storage already says which way round to err: over-counting
+ * briefly and reclaiming is the right way round, and under-counting has no recovery. Treating a failed read
+ * as unenforced would hand a customer an unbounded allowance for as long as the read kept failing. The cost
+ * is real and is stated rather than discovered: our bug becomes a refused write for a paying customer.
+ * Enforcement being opt-in is what bounds it — an adopter who would rather over-serve leaves the meter
+ * advisory.
+ */
+export async function meterLimit(c: Context<PithyHonoEnv>, meter: string): Promise<MeterLimit> {
+  const resolver = c.var.entitlements;
+  if (!resolver?.meterLimit) return { enforced: false };
+  try {
+    return await resolver.meterLimit(meter);
+  } catch (error) {
+    c.var.log?.error("meter limit resolution failed", { provider: resolver.provider, meter, cause: messageOf(error) });
+    throw new InternalError({
+      message: "Usage could not be checked, so nothing was written.",
+      action: "Read the preceding log line for why the allowance read failed.",
+      detail: `${resolver.provider} threw resolving the ${meter} meter's ceiling; refusing rather than serving unbounded.`,
+    });
+  }
+}

package/src/entitlement/entitlement.ts

@@ -132,8 +132,46 @@ export interface EntitlementResolver {
    * See {@link EntitlementHolder} for why this is a label and a tenant rather than the holder itself.
    */
   holder?(): Promise<EntitlementHolder | undefined>;
+  /**
+   * How many of `name` the current caller's holder may have — a whole number, or `null` for unlimited.
+   * Optional: a provider with no allowances omits it, and {@link import("./allowance").quota} refuses
+   * rather than inventing a number. A provider throws for a name it does not declare, never answers 0.
+   */
+  quota?(name: string): Promise<number | null>;
+  /** Whether `name` is on for the current caller's holder. Never null. Optional, as {@link quota} is. */
+  feature?(name: string): Promise<boolean>;
+  /**
+   * The ceiling a capability that counts its own rows enforces for `meter` — storage's bytes, media's
+   * items — or `{ enforced: false }` where the provider binds no ceiling to it. Optional, and absent is
+   * `{ enforced: false }`: a capability composed with no provider keeps its own configured behavior.
+   */
+  meterLimit?(meter: string): Promise<MeterLimit>;
 }
 
+/**
+ * What a provider says about one meter for the current caller: whether it binds a ceiling at all, and if
+ * it does, what the ceiling is and whose rows it covers. `limit: null` is unlimited — an enforced meter on
+ * a subject whose plan or override says so.
+ *
+ * Two states rather than a nullable number, because "this meter is advisory here" and "this subject is
+ * unlimited" are different facts and a capability must fall back to its own configured ceiling on the
+ * first and never on the second.
+ *
+ * **An enforced ceiling says which rows it is the whole of**, because a ceiling counted against the wrong
+ * rows is a different allowance. Under organization billing the plan's 10 GB is the company's: counted
+ * against one member's files it becomes 10 GB per member, and a paid quota is bypassed by an invitation.
+ * So `tenant` is the organization the ceiling was resolved for, exactly as {@link EntitlementHolder.tenant}
+ * is, and a capability sums every row it holds for that tenant, whoever wrote it. `null` means the holder
+ * is not a tenant: the ceiling is the caller's own, and the caller's rows are what count.
+ *
+ * It is a counting key, never a gate. A capability that would write a row for a different tenant than the
+ * one the ceiling covers refuses the write — that row would sit outside the sum, and under-counting has no
+ * recovery.
+ */
+export type MeterLimit =
+  | { readonly enforced: false }
+  | { readonly enforced: true; readonly limit: number | null; readonly tenant: string | null };
+
 /**
  * How a resolver's holder appears in a denial's `detail` and on the denial's audit row — and **nothing a
  * gate may compare**.

package/src/entitlement/meter.ts

@@ -0,0 +1,69 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Capability } from "../capability/capability";
+import type { Logger } from "../logger/logger";
+
+/**
+ * The usage-meter seam — how a capability that writes the rows a meter counts asks whether one more is
+ * allowed, when there is no request to ask through.
+ *
+ * `@pithy-sh/email` enqueues from a route, from a Workflow step and from a cron, and only the first has a
+ * `c.var.entitlements`. So the meter it charges is found the way the ledger is found — among the composed
+ * capabilities, by a structural predicate — and it is handed the holder explicitly. Nothing here imports the
+ * provider: an email capability composed with no payments finds no meter and enqueues as it always did.
+ *
+ * **A meter refuses; it never bills.** `charge` either records the use or throws the provider's own refusal
+ * (`payments/quota_exceeded`, 402). What it counted is never reported to a store — the kit does not sell
+ * overage — so this seam has no way to read a count back out.
+ */
+
+/** Who a charge is against: the holder pair, exactly as the provider keys it. */
+export interface MeterSubject {
+  /** The kind of holder — `user` or `organization` under `@pithy-sh/payments`. */
+  readonly subjectType: string;
+  /** The holder's id. */
+  readonly subjectId: string;
+}
+
+/** One charge against one meter. */
+export interface MeterCharge {
+  /** Who uses it. */
+  readonly subject: MeterSubject;
+  /** Which meter — `emails`. */
+  readonly meter: string;
+  /** How many. A whole number from 1. */
+  readonly amount: number;
+  /** The clock. Defaults to now. */
+  readonly now?: Date;
+  /** Where a refused or failed charge is logged. Optional; the provider logs through its own when absent. */
+  readonly log?: Logger;
+}
+
+/** The meter a provider exposes. */
+export interface UsageMeter {
+  /** The capability answering — `payments`. */
+  readonly provider: string;
+  /**
+   * Record `amount` of `meter` against `subject`, or refuse. An advisory meter records nothing and refuses
+   * nothing. **A charge that cannot be checked refuses**, because under-counting has no recovery.
+   */
+  charge(env: Record<string, unknown>, charge: MeterCharge): Promise<void>;
+}
+
+/** A composed capability that provides a meter. */
+export interface UsageMeterProvider extends Capability {
+  /** The meter. */
+  readonly usageMeter: UsageMeter;
+}
+
+/** Whether a composed capability provides a usage meter. Structural, so no provider package is imported. */
+export function isUsageMeterProvider(capability: Capability): capability is UsageMeterProvider {
+  const meter = (capability as { usageMeter?: { charge?: unknown } }).usageMeter;
+  return typeof meter?.charge === "function";
+}
+
+/** The composed usage meter, or undefined when nothing composed provides one. */
+export function composedUsageMeter(capabilities: readonly Capability[]): UsageMeter | undefined {
+  return capabilities.find(isUsageMeterProvider)?.usageMeter;
+}