@pithy-sh/storage 0.1.0

package/src/provision/provisionStorage.ts

@@ -0,0 +1,192 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import type { DeclaredEnvironments } from "@pithy-sh/core/src/naming/environment";
+import { resourceNames } from "@pithy-sh/core/src/naming/resourceNames";
+import { type ManagedEnvironment, managedEnvironments } from "@pithy-sh/secrets/src/scope";
+import { STORAGE_CAPABILITY } from "../workflows/specs";
+
+/**
+ * The provisioning orchestration for the storage capability — the live counterpart to
+ * `pithy add storage`'s config wiring.
+ *
+ * The split is deliberate and worth stating, because the two commands look like one. `pithy add`
+ * writes *bindings*: it installs the package, adds `storage()` to `pithy.config.ts`, and puts a
+ * `STORAGE_BUCKET` entry in `wrangler.jsonc`. It touches no Cloudflare account and provisions
+ * nothing — an `add` that reached out to an account would make adding a capability an operation you
+ * could not do offline, or in CI, or without credentials. This command stands up what those bindings
+ * point at: the R2 bucket, the per-environment credential secret, and the sweep worker.
+ *
+ * The `STORAGE_SWEEP` Workflow binding is the exception, and it belongs to this side of the split.
+ * Wrangler requires a `name` and a `class_name` on every `workflows` entry, and the deployed name is
+ * per environment — so `add` writes none (a partial entry stops wrangler loading the config) and the
+ * CLI writes the complete entry here, once the host worker exists.
+ *
+ * The live Cloudflare/wrangler steps sit behind the {@link StorageProvisioner} seam, so the
+ * orchestration — order, idempotency, per-environment fan-out — is unit-tested with a fake that
+ * records its call order, and no account. **Every step is idempotent**: find-then-create for the
+ * bucket, create-then-update for the secret, and a deploy that overwrites. Re-running is a no-op.
+ *
+ * **What it does not do.** Cloudflare exposes no API for minting an R2 S3 access-key pair, so nothing
+ * here mints one. The pair is supplied by the operator — flags, or `R2_CREDENTIALS` in `.dev.vars` —
+ * and written into the secret as given. That is a real limitation, and the manifest says so rather
+ * than promising a mint that does not happen.
+ */
+
+/**
+ * The bucket objects live in, **per project and per environment** — `acme-staging-storage`,
+ * `acme-prod-storage`.
+ *
+ * One bucket per account would mean staging writes objects into the bucket prod reads, and a staging
+ * teardown deletes prod's files. Buckets are free — the cost is bytes and operations — so a shared one
+ * buys nothing and risks everything. The same posture `@pithy-sh/media` takes, and the opposite of
+ * `@pithy-sh/email`'s deliberately project-shared suppression database.
+ *
+ * The project segment is what makes provisioning's find-then-create safe. R2's namespace is flat and
+ * account-wide, so an unprefixed `pithy-storage-prod` would be *found* by a second Pithy project in the
+ * same account and silently adopted — two apps writing objects into one bucket, and either teardown
+ * deleting both. The name is the only partition R2 offers, so the name carries the owner.
+ *
+ * Named as an **R2 bucket** through core's naming facade, which is the one namespace whose rule is
+ * genuinely 3–63 lowercase characters, starting and ending alphanumeric. Every other namespace Pithy
+ * writes into was once held to that same 63 for no reason; asking for a bucket by name is how this one
+ * keeps it on purpose.
+ */
+export function storageBucketName(project: string, env: ManagedEnvironment): string {
+  return resourceNames(project).env(env).r2(STORAGE_CAPABILITY);
+}
+
+/**
+ * The deployed sweep-worker name for a project's environment — also its resolved config's basename.
+ *
+ * A **Worker script**, so 63 rather than the Workflow's 64, and refused rather than truncated: a script
+ * cannot be renamed once a deploy or a `service` binding points at it.
+ */
+export function storageWorkerName(project: string, env: ManagedEnvironment): string {
+  return resourceNames(project).env(env).worker(STORAGE_CAPABILITY);
+}
+
+/** The provisioned resources an environment's worker and secret are wired to. */
+export interface StorageResources {
+  /** The R2 bucket objects live in. */
+  bucketName: string;
+}
+
+/** The live Cloudflare/wrangler seam. Each step must be idempotent. */
+export interface StorageProvisioner {
+  /**
+   * Verify account prerequisites before any resource is created — most importantly a registered
+   * `workers.dev` subdomain, which Cloudflare requires to deploy a Workflow-hosting worker. Failing
+   * here means failing before a bucket exists, rather than half way through a fan-out.
+   */
+  preflight(): Promise<void>;
+  /** Create (or reuse) this environment's R2 bucket; returns its name. Idempotent. */
+  ensureBucket(env: ManagedEnvironment): Promise<{ bucketName: string }>;
+  /**
+   * Write this environment's `storage-r2-credentials` secret — the account id, S3 key pair, scoped
+   * token, and bucket name the object store presigns with. Idempotent (create, else update). Runs
+   * before the worker is deployed: a worker that boots without its credentials fails on its first
+   * multipart abort.
+   */
+  writeCredentials(env: ManagedEnvironment, resources: StorageResources): Promise<void>;
+  /** Deploy the prebuilt sweep worker for this environment, wired to the provisioned bucket. */
+  deployWorker(env: ManagedEnvironment, resources: StorageResources): Promise<void>;
+}
+
+/** What provisioning produced, per environment. */
+export interface StorageProvisionResult {
+  /** Each environment provisioned, with the resources its worker and secret were wired to. */
+  environments: Array<{ env: ManagedEnvironment } & StorageResources>;
+}
+
+/**
+ * Provision the storage infrastructure: check the account, create every environment's bucket, write
+ * every environment's credentials, then deploy every environment's sweep worker.
+ *
+ * The phase order is the contract. A secret must not name a bucket that does not exist, and a worker
+ * must not boot before the secret it reads. Fanning each phase across all environments — rather than
+ * completing one environment end to end before starting the next — means a failure creating prod's
+ * bucket stops the run before staging's worker is deployed against a half-provisioned account.
+ *
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
+ */
+export async function provisionStorage(
+  provisioner: StorageProvisioner,
+  environments: DeclaredEnvironments | readonly string[],
+): Promise<StorageProvisionResult> {
+  await provisioner.preflight();
+
+  const resources = new Map<ManagedEnvironment, StorageResources>();
+  for (const env of managedEnvironments(environments)) {
+    const { bucketName } = await provisioner.ensureBucket(env);
+    resources.set(env, { bucketName });
+  }
+
+  for (const env of managedEnvironments(environments)) {
+    await provisioner.writeCredentials(env, resourcesFor(resources, env));
+  }
+  for (const env of managedEnvironments(environments)) {
+    await provisioner.deployWorker(env, resourcesFor(resources, env));
+  }
+
+  return { environments: managedEnvironments(environments).map((env) => ({ env, ...resourcesFor(resources, env) })) };
+}
+
+/** Read back an environment's resources. Absent is impossible by construction, so the throw is a bug check. */
+function resourcesFor(resources: Map<ManagedEnvironment, StorageResources>, env: ManagedEnvironment): StorageResources {
+  const found = resources.get(env);
+  if (!found) throw new InternalError({ message: `No provisioned resources for the ${env} environment.` });
+  return found;
+}
+
+/** The teardown seam — the inverse of {@link StorageProvisioner}. Every step idempotent. */
+export interface StorageDeprovisioner {
+  /** Delete this environment's sweep worker. Idempotent (a missing worker is a no-op). */
+  deleteWorker(env: ManagedEnvironment): Promise<void>;
+  /**
+   * Delete this environment's R2 bucket **and every file in it**. **Destructive** — nothing here is
+   * recoverable. Idempotent (a missing bucket is a no-op).
+   *
+   * Emptying the bucket is part of the contract, not a nicety: R2 refuses to delete a bucket that still
+   * holds an object, or the parts of a multipart upload that was never completed. An implementation that
+   * only called the control-plane delete would work on an untouched bucket and fail on every bucket
+   * anyone had used.
+   */
+  deleteBucket(env: ManagedEnvironment): Promise<void>;
+}
+
+/** Teardown options. By default the stored files are **kept** — only the sweep workers come down. */
+export interface StorageDeprovisionOptions {
+  /**
+   * Also delete the R2 buckets, with every file in them. Off by default, because those files are the
+   * adopter's data and no deploy can restore them — the flag is the confirmation.
+   */
+  deleteStorage?: boolean;
+}
+
+/**
+ * Tear down the storage infrastructure, reversing {@link provisionStorage}: delete every environment's
+ * sweep worker first (they bind the bucket), then — only when `deleteStorage` is set — the buckets and
+ * everything in them. Idempotent end to end.
+ *
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
+ */
+export async function deprovisionStorage(
+  deprovisioner: StorageDeprovisioner,
+  environments: DeclaredEnvironments | readonly string[],
+  options: StorageDeprovisionOptions = {},
+): Promise<void> {
+  for (const env of managedEnvironments(environments)) {
+    await deprovisioner.deleteWorker(env);
+  }
+  if (options.deleteStorage) {
+    for (const env of managedEnvironments(environments)) {
+      await deprovisioner.deleteBucket(env);
+    }
+  }
+}

package/src/provision/resolveStorageConfig.ts

@@ -0,0 +1,80 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { hostWorkflowsFor, resolveWorkflowHost, type WorkflowHostTemplate } from "@pithy-sh/core/src/workflow/host";
+import { masterKeySecretName } from "@pithy-sh/secrets/src/provision/provisionSecrets";
+import type { ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
+import type { StorageConfig } from "../config/config";
+import { STORAGE_CAPABILITY, storageWorkflowRegistry } from "../workflows/specs";
+import type { StorageResources } from "./provisionStorage";
+
+/**
+ * Resolve the sweep worker's committed `wrangler.jsonc` template into one environment's standalone
+ * config. Every per-environment decision lives here; everything static — the compatibility date, the
+ * bindings' names — stays as the template committed it.
+ *
+ * Thin over core's {@link resolveWorkflowHost}, which owns the mechanics (clone, fill by binding name,
+ * stamp `ENVIRONMENT`). What this file adds is one thing the generic resolver deliberately does not
+ * do: it **rewrites `workflows` and `triggers.crons` from the capability's specs** rather than from
+ * the template's own block. The template carries both so it reads as a complete, deployable config,
+ * but `workflows/specs.ts` is the single source of the binding name, the class name, and the
+ * schedule — so changing the sweep's cron is a one-line spec edit, not a spec edit plus a JSONC edit
+ * that nothing checks agree.
+ *
+ * Pure: the caller parses the template and writes the result.
+ */
+
+/** The resolved ids and per-env values for one environment's sweep-worker deploy. */
+export interface StorageConfigParams {
+  /**
+   * The project name — the `<project>` segment the deployed worker and Workflow names lead with. The
+   * root `pithy.config.ts` `name`, resolved by `requireProjectName` and never guessed: a Worker script
+   * name is account-scoped, so a wrong value here overwrites another project's running host.
+   */
+  project: string;
+  /** The target environment. */
+  env: ManagedEnvironment;
+  /** The app database id for this environment — where the `pithy_storage_*` tables live. */
+  appDatabaseId: string;
+  /** This environment's secrets database id (`<project>-<env>-secrets`) — holds the R2 credentials. */
+  secretsDatabaseId: string;
+  /** The CF Secrets Store id holding the per-env master key. */
+  storeId: string;
+  /** The provisioned bucket the worker binds. */
+  resources: StorageResources;
+  /** The app's resolved storage config — serialized into the worker's `STORAGE_CONFIG` var. */
+  storageConfig: StorageConfig;
+}
+
+/** Fill the template for one environment. */
+export function resolveStorageConfig(
+  template: WorkflowHostTemplate,
+  params: StorageConfigParams,
+): WorkflowHostTemplate {
+  const { project, env, appDatabaseId, secretsDatabaseId, storeId, resources, storageConfig } = params;
+
+  // Derived before the resolve rather than assigned after it: `resolveWorkflowHost` refuses to fill a
+  // template that declares `workflows` without them, because the only unscoped name it could invent is
+  // one a second project in the same account would collide with.
+  const derived = hostWorkflowsFor(storageWorkflowRegistry, { project, capability: STORAGE_CAPABILITY, env });
+
+  const resolved = resolveWorkflowHost(template, {
+    project,
+    capability: STORAGE_CAPABILITY,
+    env,
+    databaseIds: { DB: appDatabaseId, SECRETS: secretsDatabaseId },
+    r2BucketNames: { STORAGE_BUCKET: resources.bucketName },
+    secretsStoreId: storeId,
+    // The master key entry is project- and env-scoped, matching what the secrets manager wrote.
+    masterKeySecretName: masterKeySecretName(project, env),
+    vars: { STORAGE_CONFIG: JSON.stringify(storageConfig) },
+    workflows: derived.workflows,
+  });
+
+  // Only declare a cron block when a spec actually carries one. An empty `crons` array is a
+  // declaration wrangler honors, and a worker that advertises a schedule it does not have is a
+  // deployment nobody can reason about.
+  resolved.triggers = derived.crons.length > 0 ? { crons: derived.crons } : undefined;
+
+  return resolved;
+}

package/src/quota/quota.ts

@@ -0,0 +1,241 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { sql } from "kysely";
+import type { StorageObjectRow, StorageObjectStatus } from "../data/storageObject";
+import { STORAGE_OBJECTS_TABLE, type StorageDatabase } from "../data/tables";
+import { StorageQuotaExceededError } from "../error/errors";
+
+/**
+ * Per-owner byte quotas.
+ *
+ * **Quota is checked when an upload *starts*, and the sum counts `pending` rows alongside `stored`
+ * ones.** That is the whole design, and it is not an optimization.
+ *
+ * Counting only completed uploads would make the check meaningless under concurrency: ten clients
+ * that each declare 1 GiB against a 1 GiB quota all read a used total of zero, all pass, and all
+ * upload. Nothing in that sequence is a bug in any single request — the check is simply measuring the
+ * wrong thing. Making the client declare its size up front, and having the `pending` row *reserve*
+ * those bytes the moment it is written, turns the quota into something a concurrent burst cannot
+ * walk past: the second init reads the first's reservation.
+ *
+ * **The reservation only holds if the sum and the insert are one statement.** A `SELECT sum(size)`
+ * followed by a separate `INSERT` reproduces the very race it was meant to close, one round trip
+ * later: ten concurrent inits all read a used total that none of them has yet contributed to, all
+ * pass, and all insert. D1 has no interactive transactions, so a `BEGIN`/`COMMIT` wrapper is not
+ * available — {@link insertReservingQuota} is the mechanism instead. It writes the pending row with a
+ * conditional `INSERT … SELECT … WHERE`, so the sum is evaluated *inside* the write, and a row that
+ * would breach the limit simply does not appear.
+ *
+ * {@link assertWithinQuota} survives as the cheap pre-check a handler runs before it creates anything
+ * that would need cleaning up. It is a courtesy, not the enforcement.
+ *
+ * **Completion settles the same way it reserved.** A part URL carries no signed `Content-Length`, so
+ * an owner may PUT more than they declared, and the overshoot has to be re-asserted when the row turns
+ * `stored`. That re-assertion is {@link updateSettlingQuota} — a conditional `UPDATE`, the same shape
+ * as the conditional `INSERT` — because two completions racing on a plain check both read a total
+ * neither has yet contributed and both pass. The rule is one rule: every write that changes what an
+ * owner holds evaluates the sum inside itself.
+ *
+ * The reservation is not free — an abandoned upload holds bytes it never stored. That is what
+ * `pendingTtlSeconds` and the orphan sweep are for: a `pending` row past its TTL is aborted and
+ * dropped, returning its reservation. Over-counting briefly and reclaiming is the right way round;
+ * under-counting has no recovery.
+ *
+ * A `null` limit is unlimited and skips the query entirely. A `null` owner (a system object) has no
+ * quota — there is no principal to bill it to.
+ */
+
+/** What a quota check needs. */
+export interface QuotaCheck {
+  /** The storage database. */
+  db: StorageDatabase;
+  /** The owner the bytes are billed to. Null is a system object, which no quota applies to. */
+  ownerId: string | null;
+  /** The configured per-owner ceiling in bytes. Null is unlimited. */
+  limitBytes: number | null;
+  /** The bytes this upload declares — what the pending row is about to reserve. */
+  additionalBytes: number;
+}
+
+/** A quota check plus the row whose insertion *is* the reservation. */
+export interface QuotaReservation extends QuotaCheck {
+  /** The row to write, already through `StorageObject.encode` — the SQLite shape, never the app one. */
+  record: StorageObjectRow;
+}
+
+/** A quota check plus the row whose update *is* the settlement. */
+export interface QuotaSettlement extends QuotaCheck {
+  /**
+   * The whole row to write, already through `StorageObject.encode`. Its `id` is what the update
+   * targets — the settlement rewrites one known row rather than a set.
+   */
+  record: StorageObjectRow;
+}
+
+/**
+ * The statuses that bill an owner: a `pending` row reserves its declared bytes and a `stored` one
+ * holds real ones. `failed` bills nothing.
+ *
+ * Exported because the orphan sweep asks the same question of the same rows — a key is *claimed* if
+ * and only if a row bills for it — and the two predicates drifting apart is what let a `failed` row
+ * shield its R2 object from collection while counting toward nobody's quota
+ * (`workflows/sweep.ts`).
+ */
+export const QUOTA_COUNTED_STATUSES: readonly StorageObjectStatus[] = ["pending", "stored"];
+
+/**
+ * Bytes an owner currently holds: every `pending` reservation plus every `stored` object. `failed`
+ * rows are excluded — they hold no bytes and reserve nothing.
+ */
+export async function usedBytes(db: StorageDatabase, ownerId: string): Promise<number> {
+  const row = await db
+    .selectFrom(STORAGE_OBJECTS_TABLE)
+    // `size` is nullable (a caller may not declare one), and SUM over no rows is NULL — coalesce both
+    // to zero here rather than letting a null leak into arithmetic.
+    .select(sql<number>`coalesce(sum(size), 0)`.as("used"))
+    .where("ownerId", "=", ownerId)
+    .where("status", "in", [...QUOTA_COUNTED_STATUSES])
+    .executeTakeFirst();
+  return Number(row?.used ?? 0);
+}
+
+/** A size a caller declared has to be a real byte count. Zero is fine; negative is a client bug. */
+function assertDeclaredSize(additionalBytes: number): void {
+  if (additionalBytes >= 0) return;
+  throw new StorageQuotaExceededError({
+    message: "An upload needs a size.",
+    action: "Declare the file's byte count when you start the upload.",
+    detail: `negative declared size ${additionalBytes}`,
+  });
+}
+
+/**
+ * Throw `storage/quota_exceeded` when this upload would put the owner over their limit. The
+ * comparison is `used + additional > limit`, so an upload landing exactly on the limit is allowed —
+ * a quota is a ceiling you may reach, not one you must stay under.
+ *
+ * **This is a pre-check, not the reservation.** It reads a total nothing holds still, so between it
+ * and any later write a concurrent init can have taken the room. Use it to refuse an obviously
+ * oversized upload *before* opening an R2 multipart upload there would then be nothing to clean up
+ * for, and let {@link insertReservingQuota} be the boundary that actually decides.
+ */
+export async function assertWithinQuota(check: QuotaCheck): Promise<void> {
+  if (check.limitBytes === null || check.ownerId === null) return;
+  assertDeclaredSize(check.additionalBytes);
+
+  const used = await usedBytes(check.db, check.ownerId);
+  if (used + check.additionalBytes > check.limitBytes) {
+    throw new StorageQuotaExceededError({
+      detail: `owner would hold ${used + check.additionalBytes} bytes against a limit of ${check.limitBytes}`,
+    });
+  }
+}
+
+/**
+ * Insert a storage row **only if** it fits inside the owner's quota, and throw
+ * `storage/quota_exceeded` when it does not.
+ *
+ * The sum and the write are one statement — `INSERT … SELECT <values> WHERE (SELECT sum(size) …) <=
+ * limit - additional` — because two statements cannot be made to hold a reservation without a
+ * transaction, and D1 has none to offer. SQLite evaluates the sub-select while it holds the write
+ * lock, so a burst of concurrent inits is serialized by the database itself: each one sees every
+ * reservation that landed before it, and the first that would breach the limit inserts nothing.
+ *
+ * `RETURNING id` is how "inserted nothing" is read back. Zero rows is not an error to SQLite — the
+ * `WHERE` simply matched nothing — so the absence of a returned row *is* the quota answer.
+ */
+export async function insertReservingQuota(reservation: QuotaReservation): Promise<void> {
+  const { db, ownerId, limitBytes, additionalBytes, record } = reservation;
+  if (limitBytes === null || ownerId === null) {
+    await db.insertInto(STORAGE_OBJECTS_TABLE).values(record).execute();
+    return;
+  }
+  assertDeclaredSize(additionalBytes);
+
+  // The column list is read off the encoded record rather than spelled out, so a new column on
+  // `StorageObject` is carried here without an edit — and stays camelCase, which `CamelCasePlugin`
+  // snake-cases on the way out.
+  const columns = Object.keys(record) as (keyof StorageObjectRow)[];
+  const values = db
+    .selectNoFrom((eb) => columns.map((column) => eb.val(record[column]).as(column)))
+    // `used <= limit - additional` rather than `used + additional <= limit`: same integers, but the
+    // owner's total stays alone on the left where the sub-select can be compared against a constant.
+    .where((eb) =>
+      eb(
+        eb
+          .selectFrom(STORAGE_OBJECTS_TABLE)
+          .select(sql<number>`coalesce(sum(size), 0)`.as("used"))
+          .where("ownerId", "=", ownerId)
+          .where("status", "in", [...QUOTA_COUNTED_STATUSES]),
+        "<=",
+        limitBytes - additionalBytes,
+      ),
+    );
+
+  const inserted = await db
+    .insertInto(STORAGE_OBJECTS_TABLE)
+    .columns(columns)
+    .expression(values)
+    .returning("id")
+    .executeTakeFirst();
+
+  if (!inserted) {
+    throw new StorageQuotaExceededError({
+      detail: `reservation of ${additionalBytes} bytes lost against a limit of ${limitBytes}`,
+    });
+  }
+}
+
+/**
+ * Rewrite one row **only if** the bytes it newly claims still fit inside the owner's quota, and throw
+ * `storage/quota_exceeded` when they do not.
+ *
+ * This is {@link insertReservingQuota}'s other half, and it exists for the identical reason. A
+ * completion measures what R2 actually holds against what the pending row reserved, and the difference
+ * is bytes the owner has not been granted yet. Settling that difference with a separate
+ * {@link assertWithinQuota} would put the enforcement back where it never worked: two completions
+ * racing both read a total neither has yet contributed to, both pass, and the owner ends over the
+ * limit — the same defect the conditional insert was written to close, one lifecycle stage later.
+ *
+ * `additionalBytes` is the **overshoot**, not the object's size. The row being updated is still
+ * `pending`, so the sub-select in the `WHERE` already counts its reservation: SQLite evaluates the
+ * condition against the pre-update table. Passing the full size would bill the reservation twice.
+ *
+ * `RETURNING id` reads back whether the row moved. Zero rows updated is not an error to SQLite — the
+ * `WHERE` simply matched nothing — so the absence of a returned row *is* the quota answer.
+ */
+export async function updateSettlingQuota(settlement: QuotaSettlement): Promise<void> {
+  const { db, ownerId, limitBytes, additionalBytes, record } = settlement;
+  if (limitBytes === null || ownerId === null) {
+    await db.updateTable(STORAGE_OBJECTS_TABLE).set(record).where("id", "=", record.id).execute();
+    return;
+  }
+  assertDeclaredSize(additionalBytes);
+
+  const updated = await db
+    .updateTable(STORAGE_OBJECTS_TABLE)
+    .set(record)
+    .where("id", "=", record.id)
+    // Same comparison as the reservation — `used <= limit - additional` — so both halves of the
+    // lifecycle answer the same arithmetic and one of them cannot drift.
+    .where((eb) =>
+      eb(
+        eb
+          .selectFrom(STORAGE_OBJECTS_TABLE)
+          .select(sql<number>`coalesce(sum(size), 0)`.as("used"))
+          .where("ownerId", "=", ownerId)
+          .where("status", "in", [...QUOTA_COUNTED_STATUSES]),
+        "<=",
+        limitBytes - additionalBytes,
+      ),
+    )
+    .returning("id")
+    .executeTakeFirst();
+
+  if (!updated) {
+    throw new StorageQuotaExceededError({
+      detail: `settlement of ${additionalBytes} further bytes lost against a limit of ${limitBytes}`,
+    });
+  }
+}

package/src/secret/registry.ts

@@ -0,0 +1,118 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { R2Credentials } from "@pithy-sh/cloudflare/src/r2/r2Credentials";
+import type { SecretOrigin, SecretRotation } from "@pithy-sh/core/src/capability/secretOrigin";
+import { defineSecretRegistry, type SecretRegistry } from "@pithy-sh/secrets/src/registry";
+import { z } from "zod";
+
+/**
+ * The R2 credential bundle the {@link ObjectStore} seam reads, and the **factory** that declares it
+ * under any name (CLAUDE.md §Secrets).
+ *
+ * Why a factory and not a bare name. `sharedSecretsStore(env, registry)` throws for any name absent
+ * from the *aggregated* registry, and that registry is built only from the composed capabilities'
+ * `secretRegistry` slices. So `objectStore({ bucket, secretName })` cannot resolve a string on its
+ * own — something must have declared that name, with a schema, on a capability. The factory is that
+ * something: storage declares `storage-r2-credentials` for `STORAGE_BUCKET`, `@pithy-sh/media`
+ * declares `media-r2-credentials` for `MEDIA_BUCKET`, and both point the same seam at their own
+ * bucket without either package knowing the other's name.
+ *
+ * One factory is also what makes the join key safe. `aggregateSecretRegistries` allows a name to be
+ * declared twice only when every axis agrees (`backend`, `scope`, `valueType`, `rotatable`); two
+ * hand-written declarations drift, one factory cannot.
+ */
+
+/**
+ * The credentials one R2 bucket is addressed and presigned with. Composed from
+ * {@link R2Credentials} rather than redeclaring the key pair — that shape is `@pithy-sh/cloudflare`'s
+ * to define, and `CloudflareR2Manager` validates its config against it.
+ */
+export const R2StorageCredentials = R2Credentials.extend({
+  accountId: z.string().min(1).describe("The Cloudflare account id the bucket lives in — the S3 endpoint host."),
+  bucket: z.string().min(1).describe("The R2 bucket name every presigned URL and server-side object call targets."),
+  apiToken: z
+    .string()
+    .min(1)
+    .describe(
+      "The R2-scoped Cloudflare API token the key pair was derived from. Carried alongside because an R2 S3 access key IS a CF API token — the id is the key id, the SHA-256 of the value is the secret — so whatever provisions the pair already holds it, and `CloudflareR2Manager` needs it to prove bucket access.",
+    ),
+}).describe("The account, key pair, scoped token, and bucket name the object store presigns and addresses R2 with.");
+export type R2StorageCredentials = z.output<typeof R2StorageCredentials>;
+
+/**
+ * One R2-credentials registry entry. Spelled out as a type so the factory can return
+ * `Record<N, R2CredentialsEntry>` — a computed key alone widens to a string index signature, which
+ * would lose the literal name `SecretsAccessor.get` narrows on.
+ */
+export interface R2CredentialsEntry {
+  /**
+   * An encrypted row in the per-environment secrets D1 — where these values actually live.
+   *
+   * No `wrangler.jsonc` binds an R2 credential bundle from the Cloudflare Secrets Store; `pithy storage
+   * provision` and `pithy media provision` write it through `dispatchSecretWrite` → the manager
+   * Workflow → `SystemSecretsStore`, which is the D1 path. The registry's `backend` is the *single*
+   * place a secret's storage location is decided and is what the read seam routes on, so declaring
+   * `cf-secrets-store` here would send every deployed read to a binding that does not exist.
+   */
+  backend: "d1";
+  /** Each environment addresses its own bucket with its own key pair. */
+  scope: "environment";
+  /** R2 S3 key pairs are minted and replaced whole, not rotated with overlap windows. */
+  rotatable: false;
+  /** A JSON bundle, validated against {@link R2StorageCredentials} before it is exposed. */
+  valueType: "json";
+  /** The bundle's shape. */
+  schema: typeof R2StorageCredentials;
+  /** Where the pair comes from. `obtained`, always — see {@link R2_CREDENTIALS_PAGE}. */
+  origin: SecretOrigin;
+  /** How the pair is replaced. `manual`, always — the same page, by the same human. */
+  rotation: SecretRotation;
+}
+
+/**
+ * Where a human makes an R2 S3 access-key pair, and where the same human makes the next one.
+ *
+ * **Nothing here will ever mint one, and that is the fact the declaration carries.** Cloudflare has no
+ * API that returns an S3 access-key pair, so `pithy storage provision` and `pithy media provision` both
+ * take one as a flag and write it as given — a generated value would open no bucket and would replace a
+ * loud gap with a quiet one. Naming the page is the whole of the help the kit can offer, which is exactly
+ * what `obtained` is for.
+ *
+ * Origin and rotation name the same page because it is the same page: replacement is making another pair
+ * and deleting the old one. That is also why {@link R2CredentialsEntry.rotatable} is false — there is no
+ * overlap window to hold two live versions through.
+ */
+const R2_CREDENTIALS_PAGE = "https://developers.cloudflare.com/r2/api/tokens/";
+
+/**
+ * The one entry shape every name shares — declared once so no two declarations can disagree.
+ *
+ * The two declaration axes live here rather than at each name for the reason the rest of the entry does:
+ * `storage-r2-credentials` and `media-r2-credentials` are the same kind of credential from the same
+ * issuer, and `aggregateSecretRegistries` refuses a name two capabilities describe differently. One
+ * factory is how they cannot.
+ */
+const R2_CREDENTIALS_ENTRY: R2CredentialsEntry = {
+  backend: "d1",
+  scope: "environment",
+  rotatable: false,
+  valueType: "json",
+  schema: R2StorageCredentials,
+  origin: { kind: "obtained", issuer: "cloudflare", documentation: R2_CREDENTIALS_PAGE },
+  rotation: { kind: "manual", issuer: "cloudflare", documentation: R2_CREDENTIALS_PAGE },
+};
+
+/**
+ * A one-entry secret-registry slice declaring `name` as an R2 credential bundle. Hang it on the
+ * declaring capability's `secretRegistry`, then pass the same `name` to `objectStore`.
+ */
+export function r2CredentialsRegistry<const N extends string>(name: N): Record<N, R2CredentialsEntry> {
+  return defineSecretRegistry({ [name]: R2_CREDENTIALS_ENTRY } as Record<N, R2CredentialsEntry> & SecretRegistry);
+}
+
+/** The name storage's own bucket credentials are stored and resolved under. */
+export const STORAGE_R2_SECRET = "storage-r2-credentials";
+
+/** The storage capability's secret-registry slice — aggregated into the shared accessor at startup. */
+export const storageSecretsRegistry = r2CredentialsRegistry(STORAGE_R2_SECRET);