@pithy-sh/core 0.9.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pithy-sh/core",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
   },
   "scripts": {
     "build": "tsdown && tsc -p tsconfig.build.json && bun ../../tooling/build/src/stampDeclarations.ts",
-    "typecheck": "tsc -p tsconfig.json",
+    "typecheck": "bun check -p tsconfig.json",
     "test": "vitest run",
     "test:node": "vitest run --project=node",
     "test:workers": "vitest run --project=workers",
@@ -39,7 +39,7 @@
     "kysely-d1": "^0.4.0"
   },
   "devDependencies": {
-    "@cloudflare/vitest-plugin": "^1.0.0",
+    "@cloudflare/vitest-plugin": "^1.4.2",
     "@pithy-sh/tsconfig": "workspace:*",
     "@vitest/coverage-v8": "^4.1.0",
     "hono": "^4.13.2",
@@ -47,7 +47,7 @@
     "tsdown": "^0.23.0",
     "typescript": "^7.0.2",
     "vitest": "^4.1.0",
-    "wrangler": "^4.115.0",
+    "wrangler": "^4.151.0",
     "zod": "^4.4.0"
   },
   "peerDependencies": {

package/src/access/access.ts

@@ -0,0 +1,298 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { type RawBuilder, type SqlBool, sql } from "kysely";
+import type { PithyVars } from "../capability/capability";
+import type { ActingOrganization } from "./acting";
+import type { RecordVisibility } from "./visibility";
+
+/**
+ * Who may read a record, and who may change it — the rules media and storage both enforce, and the one
+ * hook an adopter answers to change them.
+ *
+ * ## The rules
+ *
+ * | Level          | Who reads it                                                       |
+ * |----------------|--------------------------------------------------------------------|
+ * | `private`      | The owner, acting for the organization the record was written under. |
+ * | `organization` | Any member of the record's organization, acting for it.            |
+ * | `public`       | Anyone holding the id or URL, signed in or not.                    |
+ *
+ * **Writing** — editing, deleting, changing visibility — is the owner's, acting for the record's
+ * organization, and that of a role holding the capability's manage power (`media:manage`,
+ * `storage:manage`) in the record's organization, so an organization can clean up after somebody who
+ * left. The manage power admits reading too: a record you may delete is a record you may see.
+ *
+ * **The organization is compared as recorded, null included.** A record written with no organization in
+ * force is its owner's while no organization is in force, and nobody's otherwise — not a manager's, since
+ * a power is only ever held *in* an organization. A record with no owner and no organization is the
+ * system's, and no rule reaches it; the hook is the only thing that can.
+ *
+ * ## The hook: allow, deny, or the default
+ *
+ * Asked on every read and every write. **Allow** admits — sharing a record with one person. **Deny**
+ * removes — a legal hold. **Default** is the rules above, and no hook at all is the rules unchanged.
+ * Sharing itself stays the adopter's: their grants, their requests for access, their tables. The hook is
+ * handed the Worker env so it can read them.
+ *
+ * **On a list, a deny filters and a grant does not list.** The rules run in SQL ({@link
+ * readablePredicate}); the hook is asked about each row on the page ({@link keepReadable}) and may only
+ * remove one. A record the hook grants is reached by id, and the adopter lists their own grants from
+ * their own tables.
+ *
+ * **The hook governs the record routes and nothing else.** Duplicate detection and control-plane rollups
+ * keep their non-disclosure rules whatever it answers: a hook that widened a per-subject total would
+ * reopen exactly the disclosure those rules close.
+ */
+
+/** Who is asking: the signed-in person, if any, and the organization they act for, if any. */
+export interface AccessCaller {
+  /** The signed-in user, from `c.var.auth.userId`; `null` for an anonymous caller. */
+  readonly userId: string | null;
+  /** The organization in force, from the acting-organization seam; `null` when none is. */
+  readonly acting: ActingOrganization | null;
+}
+
+/** The fields of a record the rules read. Every capability holding a person's record carries these. */
+export interface AccessRecord {
+  /** The record's id — handed to the hook so it can look up a grant. */
+  readonly id: string;
+  /** The user who owns it, or `null` for a system-owned record. */
+  readonly ownerId: string | null;
+  /** The organization in force when it was written, or `null` when none was. */
+  readonly organizationId: string | null;
+  /** Who may read it. */
+  readonly visibility: RecordVisibility;
+}
+
+/** What the hook is asked about. Reading, or changing — editing, deleting, changing visibility. */
+export type AccessAction = "read" | "write";
+
+/** The hook's answer. `default` defers to the rules. */
+export type PermissionDecision = "allow" | "deny" | "default";
+
+/** Everything the hook is told. */
+export interface PermissionRequest {
+  /** What the caller is trying to do. */
+  readonly action: AccessAction;
+  /** Which capability holds the record — `media` or `storage` — so one hook can serve both. */
+  readonly capability: string;
+  /** The record, as the rules see it. */
+  readonly record: AccessRecord;
+  /** Who is asking, as ids. */
+  readonly caller: { readonly userId: string | null; readonly organizationId: string | null };
+  /** The Worker env, so the hook can read the adopter's own grant tables through their own bindings. */
+  readonly env: Record<string, unknown>;
+}
+
+/** The one hook an adopter supplies. May be async — a grant lives in a table. */
+export type PermissionHook = (request: PermissionRequest) => PermissionDecision | Promise<PermissionDecision>;
+
+/** What a caller may do with one record. */
+export type AccessLevel = "none" | "read" | "write";
+
+/** The organization a caller acts for, as an id. */
+function organizationOf(caller: AccessCaller): string | null {
+  return caller.acting?.organizationId ?? null;
+}
+
+/** Whether the caller acts for the organization the record was written under — null matching null. */
+function actsForRecord(record: AccessRecord, caller: AccessCaller): boolean {
+  return record.organizationId === organizationOf(caller);
+}
+
+/** Whether the caller is the record's owner, acting for the record's organization. */
+function isActingOwner(record: AccessRecord, caller: AccessCaller): boolean {
+  return caller.userId !== null && record.ownerId === caller.userId && actsForRecord(record, caller);
+}
+
+/** Whether the caller holds the manage power in the record's organization. Never for a null organization. */
+function managesRecord(record: AccessRecord, caller: AccessCaller, managePower: string): boolean {
+  return (
+    caller.userId !== null &&
+    record.organizationId !== null &&
+    caller.acting !== null &&
+    caller.acting.organizationId === record.organizationId &&
+    caller.acting.roleAllows(managePower)
+  );
+}
+
+/** The rules alone, with no hook — what `default` means. */
+export function defaultAllows(
+  action: AccessAction,
+  record: AccessRecord,
+  caller: AccessCaller,
+  managePower: string,
+): boolean {
+  if (isActingOwner(record, caller) || managesRecord(record, caller, managePower)) return true;
+  if (action === "write") return false;
+  switch (record.visibility) {
+    case "public":
+      return true;
+    case "organization":
+      return caller.userId !== null && record.organizationId !== null && actsForRecord(record, caller);
+    case "private":
+      return false;
+  }
+}
+
+/** A record's owner and organization, as one reader may be told them. */
+export interface DisclosedTenancy {
+  readonly ownerId: string | null;
+  readonly organizationId: string | null;
+}
+
+/**
+ * Who holds a record, as this reader may learn it: the owner and organization when the reader is signed in
+ * and acts for the record's organization (none matching none), and neither otherwise.
+ *
+ * **Reading a record is not learning who holds it.** A public record is anyone's to read, but its owner's
+ * id beside its organization's id says that person belongs to that organization — and a list with
+ * `includePublic=true` reaches public records in every organization. An organization never learns that one
+ * of its people holds an account in another, so a record read from outside its organization, or by nobody
+ * in particular, names neither. Making a file public is a choice about the file, not about its owner.
+ *
+ * Every view a client sees of a media record or a stored file passes through this.
+ */
+export function disclosedTenancy(record: AccessRecord, caller: AccessCaller): DisclosedTenancy {
+  if (caller.userId === null || !actsForRecord(record, caller)) return { ownerId: null, organizationId: null };
+  return { ownerId: record.ownerId, organizationId: record.organizationId };
+}
+
+/** What {@link accessLevel} needs: the record, the caller, the capability's power, and the hook if any. */
+export interface AccessOptions {
+  /** The record being reached. */
+  readonly record: AccessRecord;
+  /** Who is reaching it. */
+  readonly caller: AccessCaller;
+  /** The capability's name, as the hook sees it. */
+  readonly capability: string;
+  /** The capability's manage power — `media:manage`, `storage:manage`. */
+  readonly managePower: string;
+  /** The adopter's hook, if they supplied one. */
+  readonly hook?: PermissionHook;
+  /** The Worker env, for the hook. */
+  readonly env: Record<string, unknown>;
+}
+
+/** Ask the hook, then the rules where it defers. */
+async function decide(action: AccessAction, options: AccessOptions): Promise<boolean> {
+  const fallback = () => defaultAllows(action, options.record, options.caller, options.managePower);
+  if (!options.hook) return fallback();
+  const decision = await options.hook({
+    action,
+    capability: options.capability,
+    record: options.record,
+    caller: { userId: options.caller.userId, organizationId: organizationOf(options.caller) },
+    env: options.env,
+  });
+  if (decision === "allow") return true;
+  if (decision === "deny") return false;
+  return fallback();
+}
+
+/**
+ * What the caller may do with one record: nothing, read it, or change it.
+ *
+ * Read is decided first, and write is never asked about a record the caller cannot read — so a record
+ * the caller cannot see answers `none`, which a route turns into **not found**, never forbidden. Only a
+ * caller who may already read a record can learn it is not theirs to change.
+ */
+export async function accessLevel(options: AccessOptions): Promise<AccessLevel> {
+  if (!(await decide("read", options))) return "none";
+  return (await decide("write", options)) ? "write" : "read";
+}
+
+/** What {@link keepReadable} needs. The rules already ran in SQL, so no power is consulted here. */
+export interface KeepReadableOptions {
+  readonly capability: string;
+  readonly caller: AccessCaller;
+  readonly hook?: PermissionHook;
+  readonly env: Record<string, unknown>;
+}
+
+/**
+ * Ask the hook about every row on a page and drop the ones it denies.
+ *
+ * Only a deny changes anything: the rows arrived through {@link readablePredicate}, so the rules already
+ * admitted them, and an allow cannot add a row that was never on the page. A page can come back short;
+ * the capability's cursor is computed before this runs, so a short page still says there is more.
+ */
+export async function keepReadable<Row extends AccessRecord>(
+  rows: readonly Row[],
+  options: KeepReadableOptions,
+): Promise<Row[]> {
+  const hook = options.hook;
+  if (!hook) return [...rows];
+  const kept: Row[] = [];
+  for (const row of rows) {
+    const decision = await hook({
+      action: "read",
+      capability: options.capability,
+      record: row,
+      caller: { userId: options.caller.userId, organizationId: organizationOf(options.caller) },
+      env: options.env,
+    });
+    if (decision !== "deny") kept.push(row);
+  }
+  return kept;
+}
+
+/** What a list asks for beyond the rules. */
+export interface ReadablePredicateOptions {
+  /** The capability's manage power — a holder lists every record in their organization. */
+  readonly managePower: string;
+  /** Add every public record. Off by default: nobody receives what they did not ask for. */
+  readonly includePublic?: boolean;
+}
+
+/**
+ * The rules, in SQL — the `where` a list runs, over a table carrying `owner_id`, `organization_id` and
+ * `visibility`.
+ *
+ * **A list returns the caller's own records and their organization's.** Their own is every record they
+ * own in the organization they act for (or in none, while none is in force). Their organization's is every
+ * record in it whose visibility admits members, and every record at all for a holder of the manage power.
+ * `includePublic` adds every public record, and nothing else does.
+ *
+ * `sql.ref` rather than a typed builder, so one predicate serves every capability's table; the
+ * `CamelCasePlugin` still snake-cases each reference. Values are bound parameters, never interpolated.
+ */
+export function readablePredicate(caller: AccessCaller, options: ReadablePredicateOptions): RawBuilder<SqlBool> {
+  const owner = sql.ref("ownerId");
+  const organization = sql.ref("organizationId");
+  const visibility = sql.ref("visibility");
+  const organizationId = organizationOf(caller);
+  const clauses: RawBuilder<SqlBool>[] = [];
+
+  if (caller.userId !== null) {
+    clauses.push(
+      organizationId === null
+        ? sql<SqlBool>`(${owner} = ${caller.userId} and ${organization} is null)`
+        : sql<SqlBool>`(${owner} = ${caller.userId} and ${organization} = ${organizationId})`,
+    );
+  }
+  if (caller.userId !== null && organizationId !== null) {
+    clauses.push(
+      caller.acting?.roleAllows(options.managePower)
+        ? sql<SqlBool>`(${organization} = ${organizationId})`
+        : sql<SqlBool>`(${organization} = ${organizationId} and ${visibility} in ('organization', 'public'))`,
+    );
+  }
+  if (options.includePublic) clauses.push(sql<SqlBool>`(${visibility} = 'public')`);
+
+  if (clauses.length === 0) return sql<SqlBool>`0 = 1`;
+  return sql<SqlBool>`(${sql.join(clauses, sql` or `)})`;
+}
+
+/**
+ * The caller, from a request: the signed-in user and the organization they act for.
+ *
+ * An anonymous caller never resolves an organization — there is no session to resolve one from, and not
+ * asking keeps a public read from paying for a tenancy query it cannot use.
+ */
+export async function accessCaller(vars: Pick<PithyVars, "auth" | "actingOrganization">): Promise<AccessCaller> {
+  const userId = vars.auth?.userId ?? null;
+  if (userId === null) return { userId: null, acting: null };
+  return { userId, acting: await vars.actingOrganization() };
+}

package/src/access/acting.ts

@@ -0,0 +1,59 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The acting-organization seam: which organization a request acts for, and what the caller's role there
+ * allows.
+ *
+ * **Core defines it and one capability fills it.** `@pithy-sh/organization` knows memberships, roles and
+ * the session's selection; `@pithy-sh/media` and `@pithy-sh/storage` need the answer and must never
+ * import the capability that computes it. The split is the `AuthContext` split, for the same reason: a
+ * capability that imported its tenancy from another package would fail open the day that package was
+ * absent, and through this seam it fails closed instead. With no organization capability composed the
+ * resolver answers `null`, every record a request writes carries a null organization, and every rule
+ * that admits by organization admits nobody.
+ *
+ * **A resolver, not a value.** Resolving costs a D1 read — the session's selection, rejoined against a
+ * live membership — and most requests never ask. So the organization capability publishes a function and
+ * the first reader pays for the answer; {@link memoizeActing} makes sure no second reader pays again.
+ * Reading `c.var.auth` at call time rather than at publish time is also what makes it independent of
+ * composition order: a Worker that lists `organization()` ahead of `auth()` still resolves against the
+ * session auth set.
+ *
+ * **Two facts and no more.** The organization id is what a write records and what a read is scoped to;
+ * `roleAllows` is the one authorization question a capability outside tenancy may ask, so it asks it
+ * without learning the role's name or the catalog's shape. A power is a string here because the catalog
+ * is the adopter's and is not known when core compiles; a power nobody declared simply allows nothing.
+ */
+
+/** The organization a request acts for, and the one question a capability may ask about the caller's role. */
+export interface ActingOrganization {
+  /** The organization this request acts for. What a write records and what a scoped read filters on. */
+  readonly organizationId: string;
+  /**
+   * Whether the caller's role in that organization holds a power — `media:manage`, `storage:manage`.
+   * Answered from the membership row read on this request, never from a session claim.
+   */
+  roleAllows(power: string): boolean;
+}
+
+/** How a request learns its acting organization. `null` is a real answer: nothing is in force. */
+export type ActingOrganizationResolver = () => Promise<ActingOrganization | null>;
+
+/** The seam's default: no organization capability is composed, so nothing is ever in force. */
+export const noActingOrganization: ActingOrganizationResolver = async () => null;
+
+/**
+ * Wrap a resolver so it runs at most once per request.
+ *
+ * The promise is kept, not the value, so concurrent readers share one read and a refusal stays a refusal:
+ * a resolver that threw for an unrecognized role must not be retried by the next reader into a different
+ * answer within the same request.
+ */
+export function memoizeActing(resolve: ActingOrganizationResolver): ActingOrganizationResolver {
+  let answer: Promise<ActingOrganization | null> | undefined;
+  return () => {
+    answer ??= resolve();
+    return answer;
+  };
+}

package/src/access/policyCheck.ts

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

package/src/access/usage.ts

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