@pithy-sh/core 0.9.0 → 0.11.0

package/src/error/wire.ts

@@ -0,0 +1,40 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+// Its own module, importing nothing but zod, so a browser and a socket's frame schemas can name the error
+// shape without reaching the HTTP codec or Hono. The OpenAPI and AsyncAPI documents both describe it here.
+
+/**
+ * The wire body of every error a route returns, whatever its status: `pithyErrorHandler` renders
+ * `{ error: clientError(payload) }`, and a socket's error frame carries the same `error` object. The payload's own schema is a union over every kit code, which
+ * would put several hundred variants into each operation, so the contract describes the envelope and
+ * names the code list's home instead.
+ */
+export const ErrorBody = z
+  .object({
+    error: z
+      .object({
+        code: z
+          .string()
+          .describe(
+            "Namespaced `domain/reason`, e.g. `auth/invalid_token`. Stable: a client switches on it. The full list is `pithy schema --json`'s `errorCodes`.",
+          ),
+        status: z.number().int().describe("The HTTP status, repeated in the body."),
+        message: z
+          .string()
+          .describe("English, for a person. A client that translates renders its own wording for `code` instead."),
+        params: z
+          .record(z.string(), z.unknown())
+          .optional()
+          .describe("Values a translating client interpolates into its own wording for `code`."),
+        issues: z
+          .array(z.unknown())
+          .optional()
+          .describe("For `validation/invalid_input`: one entry per field that failed, with its path."),
+      })
+      .describe("The public error payload. Never carries the operator's remedy or internal detail."),
+  })
+  .describe("The body of every error response.");
+export type ErrorBody = z.infer<typeof ErrorBody>;

package/src/http/authContext.ts

@@ -15,12 +15,24 @@ import { Locale } from "../i18n/locale";
  * stored choice outrank their device's `Accept-Language`. That link read `c.var.locale` at first,
  * which nothing ever wrote, so it silently contributed nothing and the chain degraded to
  * `param → cookie → header → default` while the docs said otherwise.
+ *
+ * **`scopes` answers one question: did this request come from the adopter's own trusted backend, or from a
+ * device?** The name reads like a grant to the user, and it is not one. Tenancy roles went to `c.var.acting`
+ * with `@pithy-sh/organization`; management access is the control plane's, with its own credential and its
+ * own scope type. What is left is an attestation about the caller, which `@pithy-sh/auth`'s `resolveScopes`
+ * makes on every request from something the request proves — a service binding, a verified client
+ * certificate, a short-lived token bound to this origin — and never from anything it merely says (#560).
  */
 export const AuthContext = z
   .object({
     userId: z.string().describe("ID of the authenticated user (populated by @pithy-sh/auth)."),
     sessionId: z.string().describe("ID of the active session this request belongs to."),
-    scopes: z.array(z.string()).default([]).describe("Permission scopes granted to this session."),
+    scopes: z
+      .array(z.string())
+      .default([])
+      .describe(
+        "Attestations about the caller, not permissions granted to the user: what this request's caller was established to be — the adopter's own trusted backend, say — by the `resolveScopes` seam on `@pithy-sh/auth`, resolved per request and never cached. Empty when no resolver is configured. Tenancy roles are not here; they are `c.var.acting`.",
+      ),
     locale: Locale.nullish().describe(
       "The reader's own stored language, from `pithy_auth_users.locale`; null or absent when they have never chosen.",
     ),

package/src/http/oidcWebhook.ts

@@ -491,8 +491,8 @@ export async function verifyOidcToken(token: string, options: VerifyOidcTokenOpt
 }
 
 /**
- * The OIDC gate, as a route wears it: `app.post(path, requireOidcWebhook({…}), zValidator("json", Body,
- * validationHook), handler)`.
+ * The OIDC gate, as a route wears it: `app.post(path, requireOidcWebhook({…}), validate("json", Body),
+ * handler)`.
  *
  * ## Why the header is read before anything else
  *
@@ -528,7 +528,7 @@ export async function verifyOidcToken(token: string, options: VerifyOidcTokenOpt
  * null-check.
  *
  * The body is never read here — unlike the HMAC gate, whose proof covers the bytes. An OIDC token proves who
- * sent the request and says nothing about what they sent, so the route's `zValidator` is the only thing that
+ * sent the request and says nothing about what they sent, so the route's `validate` is the only thing that
  * touches the body, and it sees an untouched stream.
  */
 export function requireOidcWebhook(options: OidcWebhookGuardOptions): MiddlewareHandler<PithyHonoEnv> {

package/src/http/routeContract.ts

@@ -65,7 +65,7 @@ function probeContext(record: () => void) {
   return { req, env: {}, var: {}, get: () => undefined, set: () => {} } as unknown as Context;
 }
 
-/** Does this middleware read `c.req.param()` — i.e. is it a `zValidator("param", …)`? */
+/** Does this middleware read `c.req.param()` — i.e. is it a `validate("param", …)`? */
 async function readsPathParams(handler: (c: Context, next: Next) => unknown): Promise<boolean> {
   let read = false;
   try {

package/src/http/routeSpec.ts

@@ -0,0 +1,81 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { MiddlewareHandler } from "hono";
+import type { z } from "zod";
+import type { VerificationStrategy } from "./verification";
+
+/**
+ * The third half of a route declaration. `validate` says what a caller may send and the guards say who
+ * may send it; this says what the route is for, how its caller is verified, and what comes back. It is
+ * the part the OpenAPI contract (`../openapi/document.ts`) cannot read from anywhere else: a guard is an
+ * anonymous closure, and a handler's `c.json(… satisfies Response)` is a compile-time check that leaves
+ * nothing behind at runtime.
+ *
+ * It sits first on the route line, ahead of the guards, and does nothing when it runs but call `next`.
+ * Its whole value is the spec it carries under {@link ROUTE_SPEC}, which a reader of the composed app
+ * finds by walking `app.routes`.
+ *
+ * ```ts
+ * app.get(
+ *   `${base}/:board/top`,
+ *   describeRoute({ summary: "Read the top of a board.", verification: ["bearer", "session"], responses: { 200: TopPage } }),
+ *   requireAuth(),
+ *   validate("param", BoardParam),
+ *   handler,
+ * );
+ * ```
+ */
+
+/** The key a {@link describeRoute} middleware carries its spec under. Global, so two copies of core agree. */
+export const ROUTE_SPEC = Symbol.for("pithy.routeSpec");
+
+/** One response a route can give that is not a JSON body: bytes, a redirect, HTML, or nothing at all. */
+export interface RouteResponse {
+  /** What this response means, in one sentence. */
+  readonly description: string;
+  /** The JSON body, when there is one. Its input side is the wire: what a client parses with it. */
+  readonly schema?: z.ZodType;
+  /** The media type when the body is not JSON, e.g. `text/html` or `application/octet-stream`. */
+  readonly contentType?: string;
+}
+
+/** The HTTP methods an `app.all` route is documented under. OpenAPI has no "any method". */
+export type DocumentedMethod = "get" | "post" | "put" | "patch" | "delete" | "head" | "options";
+
+/** What a route is for, how its caller is verified, and what it returns. */
+export interface RouteSpec {
+  /** One sentence, in the brand voice. The operation's title in the contract. */
+  readonly summary: string;
+  /** Anything a client author must know that the schemas do not say. */
+  readonly description?: string;
+  /**
+   * How the caller is verified. A list when the route takes more than one — `requireAuth()` accepts a
+   * bearer token or a session, so most authenticated routes declare both.
+   */
+  readonly verification: VerificationStrategy | readonly VerificationStrategy[];
+  /** Scopes the caller's credential must carry, beyond being verified. */
+  readonly scopes?: readonly string[];
+  /**
+   * Every success response, by status. A Zod schema is a JSON body described by the schema itself; a
+   * {@link RouteResponse} covers everything else. Errors are not listed: every route can answer with the
+   * one `PithyError` body, and the contract says so once.
+   */
+  readonly responses: Readonly<Record<number, z.ZodType | RouteResponse>>;
+  /** For an `app.all` route only: the methods it is documented under. */
+  readonly methods?: readonly DocumentedMethod[];
+}
+
+/** Declare what a route is for, how its caller is verified, and what it returns. See {@link RouteSpec}. */
+export function describeRoute(spec: RouteSpec): MiddlewareHandler {
+  const middleware: MiddlewareHandler = async (_c, next) => {
+    await next();
+  };
+  return Object.assign(middleware, { [ROUTE_SPEC]: spec });
+}
+
+/** The spec a {@link describeRoute} middleware carries, or `undefined` for any other handler. */
+export function routeSpecOf(handler: unknown): RouteSpec | undefined {
+  if (typeof handler !== "function") return undefined;
+  return (handler as { [ROUTE_SPEC]?: RouteSpec })[ROUTE_SPEC];
+}

package/src/http/sameOrigin.ts

@@ -45,7 +45,7 @@ export type SameOriginGate = MiddlewareHandler<PithyHonoEnv>;
  * Require this request to come from an origin the Worker trusts — the CSRF gate a cookie-authenticated
  * mutating route wears, beside the strategy that says who the caller is.
  *
- *   app.post("/organizations", requireAuth(), requireSameOrigin(), zValidator(…), handler)
+ *   app.post("/organizations", requireAuth(), requireSameOrigin(), validate(…), handler)
  *
  * A bearer request carries no ambient credential and is CSRF-exempt; that exemption belongs to the
  * published gate, since the capability that owns the credential model is the one that knows.

package/src/http/scopeGates.ts

@@ -0,0 +1,34 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { Hono } from "hono";
+import type { PithyHonoEnv, ScopeGate } from "../capability/capability";
+import { routeSpecOf } from "./routeSpec";
+
+/**
+ * **A capability's scope gates, read off its own routes rather than listed beside them (#560).**
+ *
+ * `Capability.scopeGates` is what `pithy doctor` names when nothing composed fills `AuthContext.scopes`.
+ * A list written out by hand next to the routes is a second copy of something the routes already say: every
+ * gated route carries `describeRoute({ scopes })`, because that is how the OpenAPI contract learns it. So the
+ * registrar is run against a throwaway app and the specs are read back — the same walk `openApiDocument`
+ * makes over a composed app, and a route whose scope changes changes what this returns with it.
+ *
+ * **Only `bearer` and `session` routes.** Those are the strategies `requireAuth()` takes, so a scope on one
+ * is an `AuthContext` scope. A `control-plane` route also names scopes, and they are a different credential
+ * entirely — a signed management token with its own type, never `c.var.auth` — so naming one here would tell
+ * an adopter to configure a resolver that could never open it.
+ */
+export function scopeGatesOf(register: (app: Hono<PithyHonoEnv>) => void): ScopeGate[] {
+  const app = new Hono<PithyHonoEnv>();
+  register(app);
+  const gates: ScopeGate[] = [];
+  for (const route of app.routes) {
+    const spec = routeSpecOf(route.handler);
+    if (!spec?.scopes || spec.scopes.length === 0) continue;
+    const verification = [spec.verification].flat();
+    if (!verification.some((strategy) => strategy === "bearer" || strategy === "session")) continue;
+    for (const scope of spec.scopes) gates.push({ scope, route: `${route.method} ${route.path}` });
+  }
+  return gates;
+}

package/src/http/signedWebhook.ts

@@ -377,8 +377,8 @@ export async function verifySignedWebhook(
 }
 
 /**
- * The `signed-webhook` gate, as a route wears it: `app.post(path, requireSignedWebhook({…}), zValidator("json",
- * Body, validationHook), handler)`.
+ * The `signed-webhook` gate, as a route wears it: `app.post(path, requireSignedWebhook({…}), validate("json",
+ * Body), handler)`.
  *
  * ## Why the header is read before anything else
  *
@@ -402,7 +402,7 @@ export async function verifySignedWebhook(
  * `c.req.text()` is not.
  *
  * `c.req.text()` rather than `c.req.raw.text()`, and the distinction is load-bearing. Hono caches its own
- * body reads and serves `c.req.json()` out of the cached text, so a `zValidator("json", …)` after this gate
+ * body reads and serves `c.req.json()` out of the cached text, so a `validate("json", …)` after this gate
  * parses identical bytes. Reading `c.req.raw` would consume the stream and leave the validator with nothing.
  */
 export function requireSignedWebhook(options: SignedWebhookGuardOptions): MiddlewareHandler<PithyHonoEnv> {

package/src/http/socket.ts

@@ -0,0 +1,55 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { z } from "zod";
+import type { SocketVersions } from "./subprotocol";
+import type { VerificationStrategy } from "./verification";
+
+/**
+ * **A WebSocket, described for the AsyncAPI contract.** The socket's counterpart of `describeRoute`.
+ *
+ * OpenAPI cannot describe a socket: after the upgrade there are no requests, only frames each way. So a
+ * capability that serves one declares it on its `sockets` contribution, built from its resolved config —
+ * the path it mounted, how a caller is verified, the versions it serves, and a Zod schema for every frame
+ * each side may send. `../asyncapi/document.ts` reads the declarations into an AsyncAPI document, the way
+ * `../openapi/document.ts` reads the route table into OpenAPI.
+ *
+ * The schemas are the ones the socket parses with, never a copy: a frame the Worker receives is parsed with
+ * the schema declared here, so the document and the socket cannot disagree about what is accepted.
+ */
+
+/** One frame one side of a socket may send. */
+export interface SocketMessage {
+  /** The frame's name, unique within its socket: `state`, `error`, `action`. */
+  readonly name: string;
+  /** What the frame is, in one sentence. */
+  readonly summary: string;
+  /** The frame's JSON body. Absent for a plain-text frame. */
+  readonly schema?: z.ZodType;
+  /** A plain-text frame's exact text — `ping`, `pong`. The one exception to JSON frames, stated per frame. */
+  readonly text?: string;
+}
+
+/** One WebSocket a capability serves. */
+export interface SocketChannel {
+  /** A stable name for the socket, unique in the Worker: `multiplayerSession`, `matchmakingPresence`. */
+  readonly name: string;
+  /** The upgrade path, as Hono registered it: `/multiplayer/sessions/:id/socket`. */
+  readonly path: string;
+  /** What the socket is for, in one sentence. */
+  readonly summary: string;
+  /** Anything a client author must know that the schemas do not say. */
+  readonly description?: string;
+  /** How the upgrade request is verified. */
+  readonly verification: VerificationStrategy | readonly VerificationStrategy[];
+  /** The path parameters' schema — the same one the upgrade route validates them with. */
+  readonly params?: z.ZodType;
+  /** The subprotocol versions this socket serves. */
+  readonly versions: SocketVersions;
+  /** Every frame the Worker sends. */
+  readonly send: readonly SocketMessage[];
+  /** Every frame the Worker accepts. Anything else is answered with a `validation/invalid_input` error frame. */
+  readonly receive: readonly SocketMessage[];
+  /** Further named schemas a client needs, such as each configured game's `action` and `view`. */
+  readonly schemas?: Readonly<Record<string, z.ZodType>>;
+}

package/src/http/subprotocol.ts

@@ -0,0 +1,47 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { ValidationError } from "../error/pithyError";
+
+/**
+ * **A socket's version is negotiated at the upgrade, and the Worker serves two.**
+ *
+ * An app store client lags its Worker by months — the same version boundary an admin response crosses
+ * (CLAUDE.md §HTTP). So a socket's frames change the way a response does: a field added to a frame is
+ * optional, and a client ignores a `type` and a key it does not know. A change no client could ignore is a
+ * new subprotocol, offered in `Sec-WebSocket-Protocol` (`pithy.multiplayer.v1`), and the Worker keeps
+ * serving the one before it, so a client released before the change keeps playing.
+ *
+ * The first versioned protocol's previous version is the unversioned one: a client that offers no
+ * subprotocol at all, which is every client written before versions existed. `previous: null` names it.
+ */
+
+/** The header a client offers subprotocols in, and the server answers with the one it chose. */
+export const SUBPROTOCOL_HEADER = "Sec-WebSocket-Protocol";
+
+/** The versions one socket serves: the current one, and the one before it — `null` when that is unversioned. */
+export interface SocketVersions {
+  readonly current: string;
+  readonly previous: string | null;
+}
+
+/**
+ * The version this upgrade speaks: the current one when the client offers it, else the previous one when
+ * the client offers that, else `null` for an unversioned client where the previous version is unversioned.
+ * A client that offers only versions this Worker does not serve is refused with a 400 naming the ones it
+ * does — a socket that opened anyway would speak frames the client cannot read.
+ */
+export function negotiateSubprotocol(offered: string | null | undefined, versions: SocketVersions): string | null {
+  const asked = (offered ?? "")
+    .split(",")
+    .map((protocol) => protocol.trim())
+    .filter((protocol) => protocol.length > 0);
+  if (asked.length === 0 && versions.previous === null) return null;
+  if (asked.includes(versions.current)) return versions.current;
+  if (versions.previous !== null && asked.includes(versions.previous)) return versions.previous;
+  const served = [versions.current, ...(versions.previous === null ? [] : [versions.previous])].join(", ");
+  throw new ValidationError({
+    message: `This socket speaks ${served}${versions.previous === null ? ", or no subprotocol" : ""}. The client offered ${asked.length === 0 ? "none" : asked.join(", ")}.`,
+    action: `Offer ${versions.current} in ${SUBPROTOCOL_HEADER}.`,
+  });
+}

package/src/http/validation.ts

@@ -1,6 +1,8 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 
+import { zValidator } from "@hono/zod-validator";
+import type { ValidationTargets } from "hono";
 import type { z } from "zod";
 import { fromZodError } from "../error/pithyError";
 
@@ -10,15 +12,21 @@ import { fromZodError } from "../error/pithyError";
  * mandatory, and both belong on the route line — reading a route tells you what it takes without
  * opening the handler.
  *
- * Routes use `zValidator(target, Schema, validationHook)` from `@hono/zod-validator`. The library
- * owns the middleware and the `c.req.valid(target)` typing; this file owns exactly one thing —
- * what happens when the parse fails. Without the hook, zod-validator answers with its own JSON
- * body, which is neither a `PithyError` payload nor routed through `pithyErrorHandler`. With it,
- * a malformed request is indistinguishable from every other failure the app can produce.
+ * Routes use `validate(target, Schema)`. `@hono/zod-validator` owns the middleware and the
+ * `c.req.valid(target)` typing; this file owns two things — what happens when the parse fails, and
+ * leaving the schema readable on the middleware afterwards.
  *
- * The hook is deliberately not a wrapper around `zValidator`. A wrapper would be a second name for
- * a library we do not re-export (CLAUDE.md §Toolchain), and it would hide the target from the route
- * line — the one thing the migration exists to make visible.
+ * The failure: without {@link validationHook}, zod-validator answers with its own JSON body, which is
+ * neither a `PithyError` payload nor routed through `pithyErrorHandler`. With it, a malformed request
+ * is indistinguishable from every other failure the app can produce.
+ *
+ * The schema: `zValidator` returns the same anonymous closure whatever it validates, so once a route is
+ * registered nothing can tell which schema it holds. That was tolerable while the only reader was the
+ * route line. The OpenAPI contract (`../openapi/document.ts`) is a second reader, and it reads the
+ * composed app, so the schema has to survive registration. `validate` is `zValidator` with the hook
+ * applied and the `{ target, schema }` pair attached under {@link REQUEST_CONTRACT}. It was once kept
+ * out of here on purpose, as a second name for a library; it earns the name now by carrying the one
+ * thing the library drops. The target stays the first argument, so the route line reads as before.
  */
 
 /**
@@ -39,3 +47,37 @@ export function validationHook(outcome: ValidationOutcome): void {
   if (outcome.success) return;
   throw fromZodError(outcome.error as z.ZodError);
 }
+
+/** The key a {@link validate} middleware carries its contract under. Global, so two copies of core agree. */
+export const REQUEST_CONTRACT = Symbol.for("pithy.requestContract");
+
+/** What one validator declares: the part of the request it reads, and the schema that part must satisfy. */
+export interface RequestContract {
+  /** The request part, as Hono names it: `json`, `query`, `param`, `header`, `cookie` or `form`. */
+  readonly target: keyof ValidationTargets;
+  /** The schema the part is parsed with. Its input side is what a caller sends. */
+  readonly schema: z.ZodType;
+}
+
+/**
+ * Declare what a route accepts in one part of the request, and fail a malformed one as a
+ * `validation/invalid_input` 400. The handler reads the parsed value with `c.req.valid(target)`.
+ *
+ * ```ts
+ * app.post(path, requireAuth(), validate("param", BoardParam), validate("json", SubmitScoreBody), handler);
+ * ```
+ */
+export function validate<Target extends keyof ValidationTargets, Schema extends z.ZodType>(
+  target: Target,
+  schema: Schema,
+) {
+  const middleware = zValidator(target, schema, validationHook);
+  const contract: RequestContract = { target, schema };
+  return Object.assign(middleware, { [REQUEST_CONTRACT]: contract });
+}
+
+/** The contract a {@link validate} middleware carries, or `undefined` for any other handler. */
+export function requestContractOf(handler: unknown): RequestContract | undefined {
+  if (typeof handler !== "function") return undefined;
+  return (handler as { [REQUEST_CONTRACT]?: RequestContract })[REQUEST_CONTRACT];
+}

package/src/index.ts

@@ -101,6 +101,7 @@ export {
   ControlPlaneScope,
   KEYS_ROTATE_SCOPE,
   MANIFEST_READ_SCOPE,
+  MIGRATIONS_READ_SCOPE,
   SEAM_SCOPES,
 } from "./controlPlane/scope/scope";
 export { exportPublicJwk, type MintControlPlaneToken, mintControlPlaneToken } from "./controlPlane/token/mint";

package/src/migrations/bookkeeping.ts

@@ -3,7 +3,7 @@
 
 import type { D1Database } from "@cloudflare/workers-types";
 import type { DatabaseIntrospector, DatabaseMetadataOptions, SchemaMetadata, TableMetadata } from "kysely";
-import { CamelCasePlugin, Kysely } from "kysely";
+import { CamelCasePlugin, Kysely, sql } from "kysely";
 import { D1Dialect } from "kysely-d1";
 
 /**
@@ -42,8 +42,17 @@ export const MIGRATION_LOCK_TABLE = "pithy_migrations_lock";
  */
 export const MIGRATION_OWNER_TABLE = "pithy_migrations_owner";
 
+/**
+ * Which run applied each migration — one row per applied migration, written by the runner from the
+ * `MigrationResult[]` Kysely hands back (`./groups`). Beside the ledger for the same reason the owner
+ * stamp is: Kysely creates `pithy_migrations` and its insert sets `name` and `timestamp` only, so there
+ * is nowhere in it to put a group — and a group is not a migration, so a rollback or a full reset must
+ * not remove the table. A reversed group's own rows go; the table stays.
+ */
+export const MIGRATION_GROUP_TABLE = "pithy_migrations_groups";
+
 /** Pithy's bookkeeping tables — hidden by the introspector the way Kysely hides its own defaults. */
-const INTERNAL_TABLES = [MIGRATION_TABLE, MIGRATION_LOCK_TABLE, MIGRATION_OWNER_TABLE];
+const INTERNAL_TABLES = [MIGRATION_TABLE, MIGRATION_LOCK_TABLE, MIGRATION_OWNER_TABLE, MIGRATION_GROUP_TABLE];
 
 /** Table names from `sqlite_master` only — no pragma joins, no column metadata. */
 class D1Introspector implements DatabaseIntrospector {
@@ -83,3 +92,31 @@ export class D1MigrationDialect extends D1Dialect {
 export function migrationKysely<DB = unknown>(database: D1Database): Kysely<DB> {
   return new Kysely<DB>({ dialect: new D1MigrationDialect({ database }), plugins: [new CamelCasePlugin()] });
 }
+
+/**
+ * The applied migrations, **in the order Kysely steps down from them** — oldest first, tip last.
+ *
+ * Kysely's `Migrator` sorts the ledger by `timestamp`, breaks a tie on the name, and reverses that list to
+ * decide what the next `migrateDown()` reverses. So anything that asks *is this the top of the chain* has
+ * to read the same order: concluding it from the order some other table was written in answers a different
+ * question, and the answer only differs in the cases that matter (`./groups`, #694).
+ *
+ * Empty when the ledger table does not exist — a database nothing has migrated. Existence is checked
+ * against `sqlite_master`, a plain select D1 permits, rather than by catching the read's error, so a
+ * genuine read failure surfaces instead of being read as "nothing applied".
+ */
+export async function appliedMigrationChain<DB>(db: Kysely<DB>): Promise<string[]> {
+  const present = await sql<{
+    name: string;
+  }>`select name from sqlite_master where type = 'table' and name = ${MIGRATION_TABLE}`.execute(db);
+  if (present.rows.length === 0) return [];
+  const { rows } = await sql<{ name: string; timestamp: string }>`select name, timestamp from ${sql.table(
+    MIGRATION_TABLE,
+  )}`.execute(db);
+  return [...rows]
+    .sort((left, right) => {
+      const elapsed = new Date(left.timestamp).getTime() - new Date(right.timestamp).getTime();
+      return elapsed === 0 ? left.name.localeCompare(right.name) : elapsed;
+    })
+    .map((row) => row.name);
+}

package/src/migrations/capabilitySets.ts

@@ -0,0 +1,87 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { MigrationProvider } from "kysely/migration";
+import type { Capability } from "../capability/capability";
+import type { DatabaseSpec } from "../data/databases";
+import { InternalError } from "../error/pithyError";
+import { createMigrationRegistry, type NamespacedMigrations } from "./registry";
+
+/**
+ * **Where a capability's migrations become a registry's sets — one function, composed twice (#729).**
+ *
+ * `pithy migrate` and `pithy doctor` compose these sets from the project on disk; the Worker composes them
+ * from the capabilities it was built with, to answer `GET {basePath}/migrations`. It lived in the CLI until
+ * the Worker needed it too. It reads nothing but `Capability.databases`, so it belongs in core — and if
+ * the two sides composed with two functions, `pithy doctor` and the route could disagree about one
+ * environment with nothing to say which was wrong.
+ */
+
+/**
+ * A retained declaration must name a table this slice declares, beside the migrations that create it.
+ *
+ * A misspelled key would count a table that does not exist, find no rows, and let the `down` through —
+ * the refusal quietly off for the one table it was written for. And retention on a slice with no
+ * migrations has no `down` to be recorded on, so nothing would ever enforce it. Both are an author's mistake,
+ * caught where the declaration is read rather than discovered when a vault is empty (#588).
+ */
+function assertRetainedDeclared(capability: string, database: string, spec: DatabaseSpec): void {
+  const retained = spec.retained ?? [];
+  if (retained.length === 0) return;
+  const unknown = retained.filter((table) => !(table in spec.tables));
+  if (unknown.length > 0) {
+    throw new InternalError({
+      message: `Capability "${capability}" retains ${unknown.map((table) => `"${table}"`).join(", ")} in database "${database}", which its tables do not declare.`,
+      action: "Name tables from that database spec's tables in retained.",
+    });
+  }
+  if (!spec.migrations || Object.keys(spec.migrations).length === 0) {
+    throw new InternalError({
+      message: `Capability "${capability}" retains tables in database "${database}" but ships no migrations for it.`,
+      action: "Declare retained beside the migrations that create those tables.",
+    });
+  }
+}
+
+/**
+ * Every capability's per-database migration set (`DatabaseSpec.migrations`, namespaced by capability
+ * name), in composition order — the raw material {@link buildRegistryFromCapabilities}, the CLI's
+ * fan-out runner and the control-plane seam all build on. The runner needs the sets rather than a
+ * finished provider because two Workers can be bound to one physical D1: their sets merge into a single
+ * ordered provider so that database migrates once, with every Worker's capabilities in it. A Worker
+ * composes only its own, which is why the seam's `undeclared` is relative to that Worker. Migrations
+ * without a `migrationOrder` fail here, attributed to their capability.
+ */
+export function collectMigrationSets(capabilities: Capability[]): NamespacedMigrations[] {
+  const sets: NamespacedMigrations[] = [];
+  for (const capability of capabilities) {
+    for (const [database, spec] of Object.entries(capability.databases ?? {})) {
+      assertRetainedDeclared(capability.name, database, spec);
+      if (!spec.migrations) continue;
+      if (spec.migrationOrder === undefined) {
+        throw new InternalError({
+          message: `Capability "${capability.name}" has migrations for database "${database}" but no migrationOrder.`,
+          action: "Set migrationOrder on that database spec (core low, app high).",
+        });
+      }
+      sets.push({
+        database,
+        namespace: capability.name,
+        order: spec.migrationOrder,
+        migrations: spec.migrations,
+        ...(spec.retained && spec.retained.length > 0 ? { retained: spec.retained } : {}),
+      });
+    }
+  }
+  return sets;
+}
+
+/**
+ * Compose every capability's per-database migration sets (`DatabaseSpec.migrations`,
+ * namespaced by capability name) into one ordered provider per database. A database
+ * nobody migrates gets no provider; migrations without a `migrationOrder` fail here,
+ * attributed to their capability.
+ */
+export function buildRegistryFromCapabilities(capabilities: Capability[]): Record<string, MigrationProvider> {
+  return createMigrationRegistry(collectMigrationSets(capabilities));
+}