@pithy-sh/core 0.10.0 → 0.11.0

package/src/error/payload.ts

@@ -501,6 +501,28 @@ const TurnstileConfigPublic = z
   })
   .describe("The Turnstile middleware is misconfigured (500).");
 
+const TurnstileAnalyticsWindowPublic = z
+  .object({
+    code: z
+      .literal("turnstile/analytics_window")
+      .describe(
+        "The requested challenge window reaches past what Cloudflare keeps, or is wider than one read may ask for.",
+      ),
+    status: z.literal(400).describe("Bad Request — narrow the window or move it later."),
+    ...publicFields,
+  })
+  .describe("A Turnstile-analytics window outside Cloudflare's retention or range (400).");
+
+const TurnstileAnalyticsUnavailablePublic = z
+  .object({
+    code: z
+      .literal("turnstile/analytics_unavailable")
+      .describe("Cloudflare does not serve Turnstile analytics to this account, so no outcome can be read."),
+    status: z.literal(409).describe("Conflict — the account's configuration rules the read out."),
+    ...publicFields,
+  })
+  .describe("Turnstile analytics are not served to this account (409).");
+
 // --- @pithy-sh/audit: audit-trail recorder codes ---
 
 const AuditInvalidEventPublic = z
@@ -535,6 +557,18 @@ const MediaNotFoundPublic = z
   })
   .describe("A requested media record does not exist (404).");
 
+const MediaForbiddenPublic = z
+  .object({
+    code: z
+      .literal("media/forbidden")
+      .describe(
+        "The caller may read the media record but not change it: only its owner, acting for the record's organization, or a role holding `media:manage` there may edit, delete or re-scope it.",
+      ),
+    status: z.literal(403).describe("Forbidden."),
+    ...publicFields,
+  })
+  .describe("The caller may read the record but not change it (403).");
+
 const MediaUnsupportedPublic = z
   .object({
     code: z
@@ -565,6 +599,30 @@ const MediaEnrichmentFailedPublic = z
   })
   .describe("A media AI-enrichment step failed (500).");
 
+const MediaAnalyticsWindowPublic = z
+  .object({
+    code: z
+      .literal("media/analytics_window")
+      .describe(
+        "The requested delivery window reaches past what Cloudflare keeps, or is wider than one read may ask for.",
+      ),
+    status: z.literal(400).describe("Bad Request — narrow the window or move it later."),
+    ...publicFields,
+  })
+  .describe("A delivery-analytics window outside Cloudflare's retention or range (400).");
+
+const MediaAnalyticsUnavailablePublic = z
+  .object({
+    code: z
+      .literal("media/analytics_unavailable")
+      .describe(
+        "Cloudflare does not serve the delivery analytics this read needs to this account — a Customer Metadata Boundary outside the US carries none of them.",
+      ),
+    status: z.literal(409).describe("Conflict — the account's configuration rules the read out."),
+    ...publicFields,
+  })
+  .describe("Delivery analytics are not served to this account (409).");
+
 // --- @pithy-sh/leaderboard: optional ranking capability codes ---
 
 const LeaderboardBoardNotFoundPublic = z
@@ -931,7 +989,7 @@ const StorageNotFoundPublic = z
   .object({
     code: z
       .literal("storage/not_found")
-      .describe("No object row matches, or the object exists but is not visible to this caller."),
+      .describe("No object row matches, or the object exists but this caller may not read it."),
     status: z.literal(404).describe("Not Found."),
     ...publicFields,
   })
@@ -939,18 +997,22 @@ const StorageNotFoundPublic = z
 
 const StorageForbiddenPublic = z
   .object({
-    code: z.literal("storage/forbidden").describe("The caller does not own the object and the object is not public."),
+    code: z
+      .literal("storage/forbidden")
+      .describe(
+        "The caller may read the object but not change it: only its owner, acting for the object's organization, or a role holding `storage:manage` there may.",
+      ),
     status: z.literal(403).describe("Forbidden."),
     ...publicFields,
   })
-  .describe("The caller is not the owner and the object is not public (403).");
+  .describe("The caller may read the object but not change it (403).");
 
 const StorageQuotaExceededPublic = z
   .object({
     code: z
       .literal("storage/quota_exceeded")
       .describe(
-        "The declared upload size would push the owner past their byte quota. Checked at init against pending and stored rows together, so concurrent inits cannot race past the limit.",
+        "The declared upload size would push the owner past the configured `bytesPerOwner` quota. Checked at init against pending and stored rows together, so concurrent inits cannot race past the limit. Where the `storageBytes` meter is enforced, the same refusal is `payments/quota_exceeded` (402).",
       ),
     status: z.literal(413).describe("Content Too Large."),
     ...publicFields,
@@ -1257,6 +1319,30 @@ const PaymentsSubscriptionChangeRefusedPublic = z
   })
   .describe("A subscription's state forbids the change asked of it (409).");
 
+const PaymentsOverrideStalePublic = z
+  .object({
+    code: z
+      .literal("payments/override_stale")
+      .describe(
+        "A control-plane override write named a version behind the subject's override row. Two operators share one customer: both opened the same allowance, and the second would silently overwrite the first while the first believed they had succeeded. So the write is refused and nothing is written. 409, because the request is well-formed and the same request against the version it now holds would be accepted — the caller re-reads, and tries again.",
+      ),
+    status: z.literal(409).describe("Conflict — the override changed since the caller read it."),
+    ...publicFields,
+  })
+  .describe("An override write named a stale version (409).");
+
+const PaymentsQuotaExceededPublic = z
+  .object({
+    code: z
+      .literal("payments/quota_exceeded")
+      .describe(
+        "An enforced kit meter — emails enqueued, bytes stored, media items held — would pass the subject's effective quota for the period. Nothing was written. 402 Payment Required, because it is the honest status: the plan does not allow more and the remedy is a purchase, a bigger tier, or a number pinned for this subject from the control plane. A meter refuses and never bills — the kit does not sell overage.",
+      ),
+    status: z.literal(402).describe("Payment Required — the plan's allowance for this period is used up."),
+    ...publicFields,
+  })
+  .describe("An enforced meter is at its quota for this period (402).");
+
 // --- @pithy-sh/core: the `control-plane` verification strategy ---
 //
 // NOT Cloudflare's control plane. Everywhere else in this repo "control plane" means the Cloudflare
@@ -1407,6 +1493,68 @@ const OrganizationNominationInvalidPublic = z
   })
   .describe("No standing ownership offer this caller may accept (400).");
 
+// --- @pithy-sh/artifacts: Git repositories, ownership, grants and short-lived tokens ---
+
+const ArtifactsNotFoundPublic = z
+  .object({
+    code: z
+      .literal("artifacts/not_found")
+      .describe(
+        "No such repository, **or** one the caller holds no grant on and does not own. One code for both, byte for byte: a repository's name is in its clone URL, and a refusal that told the two apart would hand it over. Also what the credential route answers for a repository with remote access off. Which it was survives in `detail`, which the HTTP codec strips.",
+      ),
+    status: z.literal(404).describe("Not Found."),
+    ...publicFields,
+  })
+  .describe("No such repository, or none this caller may see — the same answer for both (404).");
+
+const ArtifactsForbiddenPublic = z
+  .object({
+    code: z
+      .literal("artifacts/forbidden")
+      .describe(
+        "The caller can see the repository and may not do this to it: a grant holder asking for what only an owner may do, or a member of an organization whose role lacks the configured `managePower`. A 403 rather than the 404 above, because by then the caller already knows the repository exists.",
+      ),
+    status: z.literal(403).describe("Forbidden."),
+    ...publicFields,
+  })
+  .describe("The caller may see this repository and may not do this (403).");
+
+const ArtifactsInvalidNamePublic = z
+  .object({
+    code: z
+      .literal("artifacts/invalid_name")
+      .describe(
+        "A supplied repository name is outside Cloudflare's charset or the 2-to-63 cap. Refused and never shortened: a name somebody chose is in every clone URL, and a silently different one is a repository nobody can find.",
+      ),
+    status: z.literal(400).describe("Bad Request."),
+    ...publicFields,
+  })
+  .describe("A repository name breaks the naming rule (400).");
+
+const ArtifactsNameTakenPublic = z
+  .object({
+    code: z
+      .literal("artifacts/name_taken")
+      .describe(
+        "The owner already holds a repository with that display name, or a supplied physical name is already in the namespace. The second happens only where the adopter supplies names, so uniqueness is theirs.",
+      ),
+    status: z.literal(409).describe("Conflict."),
+    ...publicFields,
+  })
+  .describe("That repository name is already in use (409).");
+
+const ArtifactsInvalidConfigPublic = z
+  .object({
+    code: z
+      .literal("artifacts/invalid_config")
+      .describe(
+        "The capability's configuration cannot be honored: a `tokenTtlSeconds` above the ceiling, or `organization` composed with no `managePower` named. Raised at boot, so a mistake fails on deploy rather than at the first mint.",
+      ),
+    status: z.literal(400).describe("Bad Request — the configuration is malformed."),
+    ...publicFields,
+  })
+  .describe("The artifacts configuration is invalid (400).");
+
 // --- @pithy-sh/support: inbound inbox, taxonomy, and classification codes ---
 
 const SupportNotFoundPublic = z
@@ -1639,12 +1787,17 @@ export const KitPublicErrorPayload = z
     TurnstileMissingTokenPublic,
     TurnstileFailedPublic,
     TurnstileConfigPublic,
+    TurnstileAnalyticsWindowPublic,
+    TurnstileAnalyticsUnavailablePublic,
     AuditInvalidEventPublic,
     AuditWriteFailedPublic,
     MediaNotFoundPublic,
+    MediaForbiddenPublic,
     MediaUnsupportedPublic,
     MediaStorageFailedPublic,
     MediaEnrichmentFailedPublic,
+    MediaAnalyticsWindowPublic,
+    MediaAnalyticsUnavailablePublic,
     LeaderboardBoardNotFoundPublic,
     LeaderboardEntryNotFoundPublic,
     LeaderboardScoreRejectedPublic,
@@ -1707,6 +1860,8 @@ export const KitPublicErrorPayload = z
     PaymentsEntitlementNotInCatalogPublic,
     PaymentsSubjectUnresolvedPublic,
     PaymentsSubscriptionChangeRefusedPublic,
+    PaymentsOverrideStalePublic,
+    PaymentsQuotaExceededPublic,
     ControlPlaneNotConnectedPublic,
     ControlPlaneInvalidCredentialPublic,
     ControlPlaneInsufficientScopePublic,
@@ -1719,6 +1874,11 @@ export const KitPublicErrorPayload = z
     OrganizationLastAdministratorPublic,
     OrganizationSlugTakenPublic,
     OrganizationNominationInvalidPublic,
+    ArtifactsNotFoundPublic,
+    ArtifactsForbiddenPublic,
+    ArtifactsInvalidNamePublic,
+    ArtifactsNameTakenPublic,
+    ArtifactsInvalidConfigPublic,
     SupportNotFoundPublic,
     SupportInvalidCategoryPublic,
     SupportUnparseableMessagePublic,
@@ -1815,6 +1975,12 @@ const TurnstileMissingToken = TurnstileMissingTokenPublic.extend(internalFields)
 );
 const TurnstileFailed = TurnstileFailedPublic.extend(internalFields).describe(TurnstileFailedPublic.description ?? "");
 const TurnstileConfig = TurnstileConfigPublic.extend(internalFields).describe(TurnstileConfigPublic.description ?? "");
+const TurnstileAnalyticsWindow = TurnstileAnalyticsWindowPublic.extend(internalFields).describe(
+  TurnstileAnalyticsWindowPublic.description ?? "",
+);
+const TurnstileAnalyticsUnavailable = TurnstileAnalyticsUnavailablePublic.extend(internalFields).describe(
+  TurnstileAnalyticsUnavailablePublic.description ?? "",
+);
 const AuditInvalidEvent = AuditInvalidEventPublic.extend(internalFields).describe(
   AuditInvalidEventPublic.description ?? "",
 );
@@ -1822,6 +1988,7 @@ const AuditWriteFailed = AuditWriteFailedPublic.extend(internalFields).describe(
   AuditWriteFailedPublic.description ?? "",
 );
 const MediaNotFound = MediaNotFoundPublic.extend(internalFields).describe(MediaNotFoundPublic.description ?? "");
+const MediaForbidden = MediaForbiddenPublic.extend(internalFields).describe(MediaForbiddenPublic.description ?? "");
 const MediaUnsupported = MediaUnsupportedPublic.extend(internalFields).describe(
   MediaUnsupportedPublic.description ?? "",
 );
@@ -1831,6 +1998,12 @@ const MediaStorageFailed = MediaStorageFailedPublic.extend(internalFields).descr
 const MediaEnrichmentFailed = MediaEnrichmentFailedPublic.extend(internalFields).describe(
   MediaEnrichmentFailedPublic.description ?? "",
 );
+const MediaAnalyticsWindow = MediaAnalyticsWindowPublic.extend(internalFields).describe(
+  MediaAnalyticsWindowPublic.description ?? "",
+);
+const MediaAnalyticsUnavailable = MediaAnalyticsUnavailablePublic.extend(internalFields).describe(
+  MediaAnalyticsUnavailablePublic.description ?? "",
+);
 const LeaderboardBoardNotFound = LeaderboardBoardNotFoundPublic.extend(internalFields).describe(
   LeaderboardBoardNotFoundPublic.description ?? "",
 );
@@ -2016,6 +2189,12 @@ const PaymentsSubjectUnresolved = PaymentsSubjectUnresolvedPublic.extend(interna
 const PaymentsSubscriptionChangeRefused = PaymentsSubscriptionChangeRefusedPublic.extend(internalFields).describe(
   PaymentsSubscriptionChangeRefusedPublic.description ?? "",
 );
+const PaymentsOverrideStale = PaymentsOverrideStalePublic.extend(internalFields).describe(
+  PaymentsOverrideStalePublic.description ?? "",
+);
+const PaymentsQuotaExceeded = PaymentsQuotaExceededPublic.extend(internalFields).describe(
+  PaymentsQuotaExceededPublic.description ?? "",
+);
 const ControlPlaneNotConnected = ControlPlaneNotConnectedPublic.extend(internalFields).describe(
   ControlPlaneNotConnectedPublic.description ?? "",
 );
@@ -2086,6 +2265,22 @@ const OrganizationNominationInvalid = OrganizationNominationInvalidPublic.extend
   OrganizationNominationInvalidPublic.description ?? "",
 );
 
+const ArtifactsNotFound = ArtifactsNotFoundPublic.extend(internalFields).describe(
+  ArtifactsNotFoundPublic.description ?? "",
+);
+const ArtifactsForbidden = ArtifactsForbiddenPublic.extend(internalFields).describe(
+  ArtifactsForbiddenPublic.description ?? "",
+);
+const ArtifactsInvalidName = ArtifactsInvalidNamePublic.extend(internalFields).describe(
+  ArtifactsInvalidNamePublic.description ?? "",
+);
+const ArtifactsNameTaken = ArtifactsNameTakenPublic.extend(internalFields).describe(
+  ArtifactsNameTakenPublic.description ?? "",
+);
+const ArtifactsInvalidConfig = ArtifactsInvalidConfigPublic.extend(internalFields).describe(
+  ArtifactsInvalidConfigPublic.description ?? "",
+);
+
 const SupportNotFound = SupportNotFoundPublic.extend(internalFields).describe(SupportNotFoundPublic.description ?? "");
 const SupportInvalidCategory = SupportInvalidCategoryPublic.extend(internalFields).describe(
   SupportInvalidCategoryPublic.description ?? "",
@@ -2145,12 +2340,17 @@ export const KitErrorPayload = z
     TurnstileMissingToken,
     TurnstileFailed,
     TurnstileConfig,
+    TurnstileAnalyticsWindow,
+    TurnstileAnalyticsUnavailable,
     AuditInvalidEvent,
     AuditWriteFailed,
     MediaNotFound,
+    MediaForbidden,
     MediaUnsupported,
     MediaStorageFailed,
     MediaEnrichmentFailed,
+    MediaAnalyticsWindow,
+    MediaAnalyticsUnavailable,
     LeaderboardBoardNotFound,
     LeaderboardEntryNotFound,
     LeaderboardScoreRejected,
@@ -2213,6 +2413,8 @@ export const KitErrorPayload = z
     PaymentsEntitlementNotInCatalog,
     PaymentsSubjectUnresolved,
     PaymentsSubscriptionChangeRefused,
+    PaymentsOverrideStale,
+    PaymentsQuotaExceeded,
     ControlPlaneNotConnected,
     ControlPlaneInvalidCredential,
     ControlPlaneInsufficientScope,
@@ -2225,6 +2427,11 @@ export const KitErrorPayload = z
     OrganizationLastAdministrator,
     OrganizationSlugTaken,
     OrganizationNominationInvalid,
+    ArtifactsNotFound,
+    ArtifactsForbidden,
+    ArtifactsInvalidName,
+    ArtifactsNameTaken,
+    ArtifactsInvalidConfig,
     SupportNotFound,
     SupportInvalidCategory,
     SupportUnparseableMessage,

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/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/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/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));
+}

package/src/migrations/registry.ts

@@ -62,6 +62,51 @@ function assertValidLocalKey(localKey: string, namespace: string): void {
   }
 }
 
+/**
+ * The composed key for one of a set's migrations: `NNNN_<namespace>_<localKey>`. The one place the shape is
+ * written, so the registry and anything naming a declared migration's namespace build the same string.
+ */
+export function composedMigrationKey(set: Pick<NamespacedMigrations, "order" | "namespace">, localKey: string): string {
+  return `${String(set.order).padStart(ORDER_DIGITS, "0")}_${set.namespace}_${localKey}`;
+}
+
+/** A composed key taken back apart: the three parts {@link createMigrationRegistry} joined. */
+export interface ComposedMigrationKey {
+  /** The capability's `migrationOrder` — the zero-padded prefix, as a number. */
+  order: number;
+  /** The capability namespace — its `name`, which the manifest reports beside every capability. */
+  namespace: string;
+  /** The capability's own stable key, e.g. `0001_init`. */
+  localKey: string;
+}
+
+/**
+ * The composed key shape, anchored at both ends: the order prefix, a namespace (which admits no separator,
+ * so the first underscore after it is the boundary), then a local key, which may hold any number.
+ */
+const COMPOSED_KEY_PATTERN = new RegExp(
+  `^(\\d{${ORDER_DIGITS}})_(${NAMESPACE_PATTERN.source.slice(1, -1)})_(${LOCAL_KEY_PATTERN.source.slice(1, -1)})$`,
+);
+
+/**
+ * Take a composed key back apart — the inverse of the composition below.
+ *
+ * A declared migration's namespace is known from the set it came from. An **undeclared** one — applied in
+ * the database, carried by no provider this build composes — has nothing but its key, so this is the only
+ * way to say whose it was. **Null for a key no registry could have composed**, a migration written by hand
+ * or by another tool: guessing a namespace for it would be inventing one.
+ *
+ * The patterns are the same constants the composition enforces, so the two cannot disagree about what a
+ * key looks like.
+ */
+export function decomposeMigrationKey(key: string): ComposedMigrationKey | null {
+  const match = COMPOSED_KEY_PATTERN.exec(key);
+  if (!match) return null;
+  const [, order, namespace, localKey] = match;
+  if (order === undefined || namespace === undefined || localKey === undefined) return null;
+  return { order: Number(order), namespace, localKey };
+}
+
 /** Merge one database's sets into a provider, enforcing the per-database invariants. */
 function composeDatabase(database: string, sets: NamespacedMigrations[]): MigrationProvider {
   const seenOrders = new Set<number>();
@@ -85,10 +130,9 @@ function composeDatabase(database: string, sets: NamespacedMigrations[]): Migrat
 
   const composed: Record<string, Migration> = {};
   for (const set of [...sets].sort((a, b) => a.order - b.order)) {
-    const prefix = String(set.order).padStart(ORDER_DIGITS, "0");
     for (const localKey of Object.keys(set.migrations).sort()) {
       const migration = set.migrations[localKey];
-      if (migration) composed[`${prefix}_${set.namespace}_${localKey}`] = migration;
+      if (migration) composed[composedMigrationKey(set, localKey)] = migration;
     }
   }
 

package/src/migrations/state.ts

@@ -0,0 +1,94 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import type { MigrationProvider } from "kysely/migration";
+import { appliedMigrationChain, migrationKysely } from "./bookkeeping";
+import { readGroupPosition, readMigrationGroups } from "./groups";
+import { readMigrationLedger } from "./runner";
+
+/**
+ * **Where one database stands, read in one place (#729).**
+ *
+ * The control-plane seam answers `GET {basePath}/migrations` from this: what is applied, what this build
+ * declares and the database lacks, what the database holds and this build no longer declares, and which
+ * run put it there. Each half already had a reader — {@link readMigrationLedger} for both directions,
+ * {@link readMigrationGroups} and {@link readGroupPosition} for the group (#694) — and this composes them
+ * rather than reading either table a second way.
+ *
+ * Read-only. It applies nothing, creates nothing, and reverses nothing: a screen somebody opened to *ask*
+ * must not be the thing that changes the schema.
+ */
+
+/** Whether the last group can still be taken back by name — {@link readGroupPosition}, minus `absent`. */
+export type MigrationGroupStanding =
+  | {
+      /** The group's migrations are the contiguous tip of this ledger. The CLI's rollback has refusals of its own. */
+      state: "top";
+    }
+  | {
+      /** Something sits over the group or inside it, so reversing it by name is refused. */
+      state: "buried";
+      /** The groups in the way, newest first. */
+      above: string[];
+      /** The migrations in the way that no group claims, newest first. */
+      ungrouped: string[];
+    };
+
+/** The newest group with anything still applied here, and whether it is still reversible. */
+export interface MigrationLastGroup {
+  /** The group's value — what `--rollback --group` takes. */
+  group: string;
+  /** When it last applied something here. */
+  appliedAt: Date;
+  /** What it applied here and is still applied, in application order. */
+  migrations: string[];
+  /** Whether it is the tip of the chain, or what is in its way. */
+  position: MigrationGroupStanding;
+}
+
+/** One database's migration state. */
+export interface MigrationState {
+  /** Every applied migration, in the order the ledger applied them. */
+  applied: string[];
+  /** Declared and not yet applied, in the order they would run. */
+  pending: string[];
+  /** Applied and not declared by this build, sorted. Kysely refuses the whole chain on any one of these. */
+  undeclared: string[];
+  /** The newest group with anything applied here, or null when nothing applied here was ever grouped. */
+  lastGroup: MigrationLastGroup | null;
+}
+
+/**
+ * Read one database's migration state against the provider this build composes for it.
+ *
+ * **The last group is the newest one with something still applied.** Group rows are forgotten as their
+ * migrations come down, so this is ordinarily the newest group recorded. A group whose rows outlived their
+ * ledger rows reads as `absent` and is passed over: naming it as where the environment stands would name a
+ * release that is no longer in the database.
+ */
+export async function readMigrationState(database: D1Database, provider: MigrationProvider): Promise<MigrationState> {
+  const { pending, undeclared } = await readMigrationLedger(database, provider);
+  const applied = await appliedMigrationChain(migrationKysely(database));
+  return { applied, pending, undeclared, lastGroup: await lastGroupOf(database, applied) };
+}
+
+/** Walk the groups newest first and stop at the first one this database still holds any of. */
+async function lastGroupOf(database: D1Database, applied: readonly string[]): Promise<MigrationLastGroup | null> {
+  const held = new Set(applied);
+  const groups = await readMigrationGroups(database);
+  for (const group of [...groups].reverse()) {
+    const position = await readGroupPosition(database, group.group);
+    if (position.state === "absent") continue;
+    return {
+      group: group.group,
+      appliedAt: group.appliedAt,
+      migrations: group.migrations.filter((name) => held.has(name)),
+      position:
+        position.state === "top"
+          ? { state: "top" }
+          : { state: "buried", above: position.above, ungrouped: position.ungrouped },
+    };
+  }
+  return null;
+}