@pithy-sh/core 0.10.0 → 0.11.0

package/dist/controlPlane/http/guard.d.ts

@@ -1,8 +1,10 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 import type { MiddlewareHandler } from "hono";
+import type { AuditEmit } from "../../audit/recorder";
 import type { PithyHonoEnv } from "../../capability/capability";
 import type { ControlPlaneContext } from "../context";
+import type { ControlPlaneActorKind } from "../data/connection";
 import type { ControlPlaneRequirement } from "../scope/scope";
 import { type ControlPlaneVerifyDeps } from "./verify";
 /**
@@ -76,4 +78,13 @@ export declare const CONTROL_PLANE_GUARD: unique symbol;
 /** Whether a mounted handler is a control-plane gate. */
 export declare function isControlPlaneGuard(handler: unknown): boolean;
 export declare function requireControlPlane(requirement: ControlPlaneRequirement): MiddlewareHandler<PithyHonoEnv>;
+/**
+ * The recorder a verified call's handlers write through: the request's own, with the connection's actor
+ * kind added to every `control-plane` event that does not already carry one.
+ *
+ * Only `control-plane` events, because the kind describes a management client and nothing else — a
+ * handler recording what happened to a user is recording a user. An event that states a kind keeps it.
+ * A connection with no recorded kind adds nothing, so its rows read exactly as they did before.
+ */
+export declare function stampActorKind(emit: AuditEmit, actorKind: ControlPlaneActorKind | null): AuditEmit;
 //# sourceMappingURL=guard.d.ts.map

package/dist/controlPlane/http/guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/http/guard.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAMhE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAE9D,OAAO,EAAE,KAAK,sBAAsB,EAA0B,MAAM,UAAU,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,CACjC,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,uBAAuB,KACjC,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAElC;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,sBAAsB,GAAG,oBAAoB,CAgB7F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMzE;AAED;;;;;;GAMG;AACH;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,eAAwC,CAAC;AAEzE,yDAAyD;AACzD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAE7D;AAED,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,uBAAuB,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAkEzG"}
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/http/guard.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAMhE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAEhE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAE9D,OAAO,EAAE,KAAK,sBAAsB,EAA0B,MAAM,UAAU,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,CACjC,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,uBAAuB,KACjC,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAElC;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,sBAAsB,GAAG,oBAAoB,CAgB7F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMzE;AAED;;;;;;GAMG;AACH;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,eAAwC,CAAC;AAEzE,yDAAyD;AACzD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAE7D;AAED,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,uBAAuB,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAuEzG;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,qBAAqB,GAAG,IAAI,GAAG,SAAS,CAIlG"}

package/dist/controlPlane/http/guard.js

@@ -85,6 +85,7 @@ function requireControlPlane(requirement) {
 			throw cause;
 		}
 		c.set("controlPlane", context);
+		c.set("emit", stampActorKind(c.var.emit, context.actorKind));
 		await safeEmit(c.var.emit, {
 			action: ControlPlaneAuditActions.callAllowed,
 			outcome: "success",
@@ -110,6 +111,21 @@ function requireControlPlane(requirement) {
 	return guard;
 }
 /**
+* The recorder a verified call's handlers write through: the request's own, with the connection's actor
+* kind added to every `control-plane` event that does not already carry one.
+*
+* Only `control-plane` events, because the kind describes a management client and nothing else — a
+* handler recording what happened to a user is recording a user. An event that states a kind keeps it.
+* A connection with no recorded kind adds nothing, so its rows read exactly as they did before.
+*/
+function stampActorKind(emit, actorKind) {
+	if (actorKind === null) return emit;
+	return (event) => emit(event.actorType === "control-plane" && event.actorKind == null ? {
+		...event,
+		actorKind
+	} : event);
+}
+/**
 * Record a refused call.
 *
 * **Denials are audited, not only successes.** `denied` is a first-class outcome precisely for this, and
@@ -151,4 +167,4 @@ function connectStep(env) {
 	return remedy("dashboard connect", { flags: { "--env": env } }, { runtime: true }).say((command) => `run ${command}`);
 }
 //#endregion
-export { CONTROL_PLANE_GUARD, createControlPlaneVerifier, isControlPlaneGuard, requireControlPlane, workerVersionHeaders };
+export { CONTROL_PLANE_GUARD, createControlPlaneVerifier, isControlPlaneGuard, requireControlPlane, stampActorKind, workerVersionHeaders };

package/dist/controlPlane/http/handlers.d.ts

@@ -6,6 +6,7 @@ import type { ControlPlaneConfig } from "../config/config";
 import { type ControlPlaneDatabase } from "../data/tables";
 import type { CapabilityDeclaration } from "../discovery/adminRoute";
 import { type CapabilityHealthSource } from "../discovery/health";
+import { type ComposedMigrationDatabase } from "../migrationState/migrationState";
 import type { ExpireKeyParams, ExpireKeyRequest, RegisterKeyRequest } from "./schemas";
 /** The pieces of the composed capability a handler needs. Passed in, so nothing reaches for a global. */
 export interface ControlPlaneHandlerDeps {
@@ -31,6 +32,11 @@ export interface ControlPlaneHandlerDeps {
      * value is not: the numbers are resolved per request, behind the scope each one is declared under.
      */
     composedHealth: () => ReadonlyMap<string, CapabilityHealthSource>;
+    /**
+     * Every database this Worker binds, with the provider this build composes for it — captured by the same
+     * `compose` hook through `collectMigrationSets`, the function `pithy migrate` composes with (#729).
+     */
+    composedMigrations: () => readonly ComposedMigrationDatabase[];
     /** The clock, injected so a test can stand at any instant. */
     now: () => Date;
 }
@@ -108,6 +114,57 @@ export declare function manifestHandler(deps: ControlPlaneHandlerDeps): (c: Cont
     }[];
     grantedScopes: string[];
 }, import("hono/utils/http-status").ContentfulStatusCode, "json">>;
+/**
+ * `GET /control-plane/migrations` — where each database this Worker binds stands (#729).
+ *
+ * Read-only: it reports, and nothing over the seam runs, reverses or resets a migration.
+ *
+ * **One unreadable ledger costs one database its answer.** Each read catches its own failure and lands on
+ * `unreadable`, so `Promise.all` still resolves and the route answers 200 with what it has. The cause is
+ * logged here, for the operator, and never projected: a D1 error can name a table or a query.
+ */
+export declare function migrationsHandler(deps: ControlPlaneHandlerDeps): (c: Context<PithyHonoEnv>) => Promise<Response & import("hono").TypedResponse<{
+    environment: string;
+    databases: ({
+        state: "readable";
+        database: string;
+        binding: string;
+        applied: {
+            name: string;
+            namespace: string | null;
+        }[];
+        pending: {
+            name: string;
+            namespace: string | null;
+        }[];
+        undeclared: {
+            name: string;
+            namespace: string | null;
+        }[];
+        lastGroup: {
+            group: string;
+            appliedAt: string;
+            migrations: {
+                name: string;
+                namespace: string | null;
+            }[];
+            position: {
+                state: "top";
+            } | {
+                state: "buried";
+                above: string[];
+                ungrouped: {
+                    name: string;
+                    namespace: string | null;
+                }[];
+            };
+        } | null;
+    } | {
+        state: "unreadable";
+        database: string;
+        binding: string;
+    })[];
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">>;
 /** `GET /control-plane/keys` — the registration state, so a client can surface a stale key. */
 export declare function listKeysHandler(deps: ControlPlaneHandlerDeps): (c: Context<PithyHonoEnv>) => Promise<Response & import("hono").TypedResponse<{
     connectionId: string;
@@ -123,6 +180,9 @@ export declare function listKeysHandler(deps: ControlPlaneHandlerDeps): (c: Cont
         validUntil: string | null;
         revokedAt: string | null;
     }[];
+    authorizedBy: string | null;
+    actorKind: "agent" | "dashboard" | "script" | null;
+    purpose: string | null;
 }, import("hono/utils/http-status").ContentfulStatusCode, "json">>;
 /**
  * `POST /control-plane/keys` — register a new public key, authenticated by the key it succeeds.

package/dist/controlPlane/http/handlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/http/handlers.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAGhE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAI3D,OAAO,EAAmC,KAAK,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC5F,OAAO,KAAK,EAAE,qBAAqB,EAA4B,MAAM,yBAAyB,CAAC;AAC/F,OAAO,EAAE,KAAK,sBAAsB,EAAwB,MAAM,qBAAqB,CAAC;AAUxF,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAuBvF,yGAAyG;AACzG,MAAM,WAAW,uBAAuB;IACtC,yDAAyD;IACzD,MAAM,EAAE,kBAAkB,CAAC;IAC3B,oEAAoE;IACpE,QAAQ,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,oBAAoB,CAAC;IAC7D;;;;;;;;OAQG;IACH,oBAAoB,EAAE,MAAM,SAAS,qBAAqB,EAAE,CAAC;IAC7D;;;;;;OAMG;IACH,cAAc,EAAE,MAAM,WAAW,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAClE,8DAA8D;IAC9D,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB;AAgED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,uBAAuB,OAC5C,OAAO,CAAC,YAAY,CAAC;;;;;;kEAUjC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,uBAAuB,OAC1C,OAAO,CAAC,YAAY,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mEAyBvC;AAED,+FAA+F;AAC/F,wBAAgB,eAAe,CAAC,IAAI,EAAE,uBAAuB,OAC1C,OAAO,CAAC,YAAY,CAAC;;;;;;;;;;;;;;mEASvC;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,uBAAuB,OAC7C,OAAO,CAAC,YAAY,CAAC,QAAQ,kBAAkB;;;;;;;;;;;;;;iBAoDjE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,uBAAuB,OAC3C,OAAO,CAAC,YAAY,CAAC,UAAU,eAAe,QAAQ,gBAAgB;;;;;;;;;;;;;;mEA8CxF"}
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/http/handlers.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAIhE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAI3D,OAAO,EAAmC,KAAK,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC5F,OAAO,KAAK,EAAE,qBAAqB,EAA4B,MAAM,yBAAyB,CAAC;AAC/F,OAAO,EAAE,KAAK,sBAAsB,EAAwB,MAAM,qBAAqB,CAAC;AAGxF,OAAO,EAAE,KAAK,yBAAyB,EAA0B,MAAM,kCAAkC,CAAC;AAS1G,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAuBvF,yGAAyG;AACzG,MAAM,WAAW,uBAAuB;IACtC,yDAAyD;IACzD,MAAM,EAAE,kBAAkB,CAAC;IAC3B,oEAAoE;IACpE,QAAQ,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,oBAAoB,CAAC;IAC7D;;;;;;;;OAQG;IACH,oBAAoB,EAAE,MAAM,SAAS,qBAAqB,EAAE,CAAC;IAC7D;;;;;;OAMG;IACH,cAAc,EAAE,MAAM,WAAW,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAClE;;;OAGG;IACH,kBAAkB,EAAE,MAAM,SAAS,yBAAyB,EAAE,CAAC;IAC/D,8DAA8D;IAC9D,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB;AAgED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,uBAAuB,OAC5C,OAAO,CAAC,YAAY,CAAC;;;;;;kEAUjC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,uBAAuB,OAC1C,OAAO,CAAC,YAAY,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mEAyBvC;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,uBAAuB,OAC5C,OAAO,CAAC,YAAY,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mEAgBvC;AAED,+FAA+F;AAC/F,wBAAgB,eAAe,CAAC,IAAI,EAAE,uBAAuB,OAC1C,OAAO,CAAC,YAAY,CAAC;;;;;;;;;;;;;;;;;mEAcvC;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,uBAAuB,OAC7C,OAAO,CAAC,YAAY,CAAC,QAAQ,kBAAkB;;;;;;;;;;;;;;iBAoDjE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,uBAAuB,OAC3C,OAAO,CAAC,YAAY,CAAC,UAAU,eAAe,QAAQ,gBAAgB;;;;;;;;;;;;;;mEA8CxF"}

package/dist/controlPlane/http/handlers.js

@@ -8,6 +8,8 @@ import { readCapabilityHealth } from "../discovery/health.js";
 import { ControlPlaneAuditActions, safeEmit } from "../audit/actions.js";
 import { ControlPlaneInvalidCredentialError, ControlPlaneKeyConflictError } from "../error/errors.js";
 import { appendKey, expireKey, pruneKeys } from "../data/keyLifecycle.js";
+import { causeMessage } from "../../error/cause.js";
+import { readDatabaseMigrations } from "../migrationState/migrationState.js";
 //#region src/controlPlane/http/handlers.ts
 /**
 * The seam's own route handlers.
@@ -121,6 +123,30 @@ function manifestHandler(deps) {
 		});
 	};
 }
+/**
+* `GET /control-plane/migrations` — where each database this Worker binds stands (#729).
+*
+* Read-only: it reports, and nothing over the seam runs, reverses or resets a migration.
+*
+* **One unreadable ledger costs one database its answer.** Each read catches its own failure and lands on
+* `unreadable`, so `Promise.all` still resolves and the route answers 200 with what it has. The cause is
+* logged here, for the operator, and never projected: a D1 error can name a table or a query.
+*/
+function migrationsHandler(deps) {
+	return async (c) => {
+		const context = caller(c);
+		const env = c.env;
+		const databases = await Promise.all(deps.composedMigrations().map((entry) => readDatabaseMigrations(env, entry, (failed, cause) => c.var.log.warn("migration ledger unreadable", {
+			database: failed.database,
+			binding: failed.binding,
+			reason: causeMessage(cause) ?? String(cause)
+		}))));
+		return c.json({
+			environment: context.environment,
+			databases
+		});
+	};
+}
 /** `GET /control-plane/keys` — the registration state, so a client can surface a stale key. */
 function listKeysHandler(deps) {
 	return async (c) => {
@@ -129,7 +155,10 @@ function listKeysHandler(deps) {
 		return c.json({
 			connectionId: connection.id,
 			environment: connection.environment,
-			keys: connection.keys.map(publicKeyView)
+			keys: connection.keys.map(publicKeyView),
+			authorizedBy: connection.authorizedBy,
+			actorKind: connection.actorKind,
+			purpose: connection.purpose
 		});
 	};
 }
@@ -244,4 +273,4 @@ function expireKeyHandler(deps) {
 	};
 }
 //#endregion
-export { expireKeyHandler, listKeysHandler, manifestHandler, pingHandler, registerKeyHandler };
+export { expireKeyHandler, listKeysHandler, manifestHandler, migrationsHandler, pingHandler, registerKeyHandler };

package/dist/controlPlane/http/readiness.d.ts

@@ -0,0 +1,33 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Hono } from "hono";
+import type { PithyHonoEnv, PithyReadinessGuard } from "../../capability/capability";
+/**
+ * Mount every capability's readiness guard, exempting the admin surface.
+ *
+ * **The control plane answers whatever else is wrong with the Worker.** It is the diagnostic surface: a
+ * management client reads the manifest, migration state and drift through it. A guard that refuses every
+ * request because an index drifted would take that surface down on exactly the fault it exists to report,
+ * and the client could not tell drift from a Worker that is simply down.
+ *
+ * **The exemption is the guard, not the middleware.** The seam itself runs on capability middleware —
+ * `controlplane()` publishes the verifier and `audit()` publishes `emit` — so skipping middleware on a
+ * seam request would trade a 500 for a seam that denies everything, or one that stops auditing without a
+ * word. Readiness guards are the only middleware that refuses because the Worker is broken, so they are
+ * the only thing skipped.
+ *
+ * **Hono decides what is on the surface, not a matcher written here.** One `app.use` per admin path marks
+ * the request, so a `:segment` matches exactly as it does for the route and the CORS layer, and a literal
+ * path never matches what is beneath it. The surface is the one `corsSurface(all)` computes, which
+ * `routeContract.test.ts` already holds to the registered routes, so there is no second list to drift.
+ *
+ * The mark is a `WeakSet` over the raw `Request`, closed over here. A context variable would put an
+ * internal flag on `PithyVars`, where every capability could read it and one could set it.
+ *
+ * Call after every capability's `middleware` and before any capability's `routes`. Before the routes,
+ * because a terminal handler never calls `next()` and a guard mounted after it never runs.
+ */
+export declare function registerReadinessGuards(app: Hono<PithyHonoEnv>, surface: readonly {
+    path: string;
+}[], guards: readonly PithyReadinessGuard[]): void;
+//# sourceMappingURL=readiness.d.ts.map

package/dist/controlPlane/http/readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/http/readiness.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACjC,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,EACvB,OAAO,EAAE,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,EACpC,MAAM,EAAE,SAAS,mBAAmB,EAAE,GACrC,IAAI,CAcN"}

package/dist/controlPlane/http/readiness.js

@@ -0,0 +1,39 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/controlPlane/http/readiness.ts
+/**
+* Mount every capability's readiness guard, exempting the admin surface.
+*
+* **The control plane answers whatever else is wrong with the Worker.** It is the diagnostic surface: a
+* management client reads the manifest, migration state and drift through it. A guard that refuses every
+* request because an index drifted would take that surface down on exactly the fault it exists to report,
+* and the client could not tell drift from a Worker that is simply down.
+*
+* **The exemption is the guard, not the middleware.** The seam itself runs on capability middleware —
+* `controlplane()` publishes the verifier and `audit()` publishes `emit` — so skipping middleware on a
+* seam request would trade a 500 for a seam that denies everything, or one that stops auditing without a
+* word. Readiness guards are the only middleware that refuses because the Worker is broken, so they are
+* the only thing skipped.
+*
+* **Hono decides what is on the surface, not a matcher written here.** One `app.use` per admin path marks
+* the request, so a `:segment` matches exactly as it does for the route and the CORS layer, and a literal
+* path never matches what is beneath it. The surface is the one `corsSurface(all)` computes, which
+* `routeContract.test.ts` already holds to the registered routes, so there is no second list to drift.
+*
+* The mark is a `WeakSet` over the raw `Request`, closed over here. A context variable would put an
+* internal flag on `PithyVars`, where every capability could read it and one could set it.
+*
+* Call after every capability's `middleware` and before any capability's `routes`. Before the routes,
+* because a terminal handler never calls `next()` and a guard mounted after it never runs.
+*/
+function registerReadinessGuards(app, surface, guards) {
+	if (guards.length === 0) return;
+	const onSurface = /* @__PURE__ */ new WeakSet();
+	for (const path of new Set(surface.map((entry) => entry.path))) app.use(path, async (c, next) => {
+		onSurface.add(c.req.raw);
+		await next();
+	});
+	for (const guard of guards) app.use("*", (c, next) => onSurface.has(c.req.raw) ? next() : guard(c, next));
+}
+//#endregion
+export { registerReadinessGuards };

package/dist/controlPlane/http/responses.d.ts

@@ -62,6 +62,13 @@ export declare const ControlPlaneKeysResponse: z.ZodObject<{
         validUntil: z.ZodNullable<z.ZodISODateTime>;
         revokedAt: z.ZodNullable<z.ZodISODateTime>;
     }, z.core.$strip>>;
+    authorizedBy: z.ZodOptional<z.ZodNullable<z.ZodEmail>>;
+    actorKind: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        agent: "agent";
+        dashboard: "dashboard";
+        script: "script";
+    }>>>;
+    purpose: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 export type ControlPlaneKeysResponse = z.output<typeof ControlPlaneKeysResponse>;
 /** `POST /control-plane/keys` — the appended key, and the set as it now stands. */
@@ -98,4 +105,144 @@ export declare const ExpireKeyResponse: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type ExpireKeyResponse = z.output<typeof ExpireKeyResponse>;
+/**
+ * One migration as `GET {basePath}/migrations` reports it: its composed name, and whose it is.
+ *
+ * The namespace is a capability's name, which the manifest already reports in `capabilities[]`. So a
+ * client tells an adopter's own migrations from a composed capability's by comparing the two — no
+ * convention, and no list kept anywhere.
+ */
+export declare const MigrationView: z.ZodObject<{
+    name: z.ZodString;
+    namespace: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type MigrationView = z.output<typeof MigrationView>;
+/** Whether the last group is still reversible by name, or what is in its way. */
+export declare const MigrationGroupPositionView: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    state: z.ZodLiteral<"top">;
+}, z.core.$strip>, z.ZodObject<{
+    state: z.ZodLiteral<"buried">;
+    above: z.ZodArray<z.ZodString>;
+    ungrouped: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        namespace: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>], "state">;
+export type MigrationGroupPositionView = z.output<typeof MigrationGroupPositionView>;
+/** The run that last moved a database, and whether it can still be taken back. */
+export declare const MigrationGroupView: z.ZodObject<{
+    group: z.ZodString;
+    appliedAt: z.ZodISODateTime;
+    migrations: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        namespace: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    position: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        state: z.ZodLiteral<"top">;
+    }, z.core.$strip>, z.ZodObject<{
+        state: z.ZodLiteral<"buried">;
+        above: z.ZodArray<z.ZodString>;
+        ungrouped: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            namespace: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>], "state">;
+}, z.core.$strip>;
+export type MigrationGroupView = z.output<typeof MigrationGroupView>;
+/**
+ * One database this Worker binds, read or not.
+ *
+ * **An unreadable database carries no list at all**, never empty ones. `pending: []` reads as up to date,
+ * and a database nobody read is not that. The state is on the value, so a client reaches a list only by
+ * narrowing.
+ */
+export declare const MigrationDatabaseView: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    state: z.ZodLiteral<"readable">;
+    database: z.ZodString;
+    binding: z.ZodString;
+    applied: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        namespace: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    pending: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        namespace: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    undeclared: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        namespace: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    lastGroup: z.ZodNullable<z.ZodObject<{
+        group: z.ZodString;
+        appliedAt: z.ZodISODateTime;
+        migrations: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            namespace: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+        position: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            state: z.ZodLiteral<"top">;
+        }, z.core.$strip>, z.ZodObject<{
+            state: z.ZodLiteral<"buried">;
+            above: z.ZodArray<z.ZodString>;
+            ungrouped: z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                namespace: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>], "state">;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    state: z.ZodLiteral<"unreadable">;
+    database: z.ZodString;
+    binding: z.ZodString;
+}, z.core.$strip>], "state">;
+export type MigrationDatabaseView = z.output<typeof MigrationDatabaseView>;
+/**
+ * `GET /control-plane/migrations` — where every database this Worker binds stands.
+ *
+ * Asked of the Worker because the Worker *is* the deployed build. `pithy doctor` reads the project on disk,
+ * which is what the operator has and not necessarily what is deployed.
+ */
+export declare const ControlPlaneMigrationsResponse: z.ZodObject<{
+    environment: z.ZodString;
+    databases: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        state: z.ZodLiteral<"readable">;
+        database: z.ZodString;
+        binding: z.ZodString;
+        applied: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            namespace: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+        pending: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            namespace: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+        undeclared: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            namespace: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+        lastGroup: z.ZodNullable<z.ZodObject<{
+            group: z.ZodString;
+            appliedAt: z.ZodISODateTime;
+            migrations: z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                namespace: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>>;
+            position: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                state: z.ZodLiteral<"top">;
+            }, z.core.$strip>, z.ZodObject<{
+                state: z.ZodLiteral<"buried">;
+                above: z.ZodArray<z.ZodString>;
+                ungrouped: z.ZodArray<z.ZodObject<{
+                    name: z.ZodString;
+                    namespace: z.ZodNullable<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>], "state">;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        state: z.ZodLiteral<"unreadable">;
+        database: z.ZodString;
+        binding: z.ZodString;
+    }, z.core.$strip>], "state">>;
+}, z.core.$strip>;
+export type ControlPlaneMigrationsResponse = z.output<typeof ControlPlaneMigrationsResponse>;
 //# sourceMappingURL=responses.d.ts.map

package/dist/controlPlane/http/responses.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/http/responses.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;;;;;;GAkBG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,aAAa;;;;;;;;;;iBAcmF,CAAC;AAC9G,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;iBAQwB,CAAC;AAC9D,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEjF,+FAA+F;AAC/F,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;iBAMwC,CAAC;AAC9E,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEjF,mFAAmF;AACnF,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;iBAQyB,CAAC;AAC1D,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE,gGAAgG;AAChG,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;iBAM6B,CAAC;AAC5D,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC"}
+{"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/http/responses.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;;;;;;GAkBG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,aAAa;;;;;;;;;;iBAcmF,CAAC;AAC9G,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;iBAQwB,CAAC;AAC9D,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEjF,+FAA+F;AAC/F,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;iBAuBwE,CAAC;AAC9G,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEjF,mFAAmF;AACnF,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;iBAQyB,CAAC;AAC1D,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE,gGAAgG;AAChG,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;iBAM6B,CAAC;AAC5D,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;;iBAU+C,CAAC;AAC1E,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D,iFAAiF;AACjF,eAAO,MAAM,0BAA0B;;;;;;;;;4BAyBkE,CAAC;AAC1G,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAErF,kFAAkF;AAClF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;iBAW8C,CAAC;AAC9E,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAErE;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BA+BwE,CAAC;AAC3G,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE3E;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAO+D,CAAC;AAC3G,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,8BAA8B,CAAC,CAAC"}

package/dist/controlPlane/http/responses.js

@@ -1,6 +1,6 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
-import { Ed25519PublicJwk } from "../data/connection.js";
+import { ConnectionPrincipal, ConnectionPurpose, ControlPlaneActorKind, Ed25519PublicJwk } from "../data/connection.js";
 import { z } from "zod";
 //#region src/controlPlane/http/responses.ts
 /**
@@ -47,8 +47,11 @@ const ControlPlanePingResponse = z.object({
 const ControlPlaneKeysResponse = z.object({
 	connectionId: z.string().describe("The connection these keys belong to."),
 	environment: z.string().describe("The environment that connection is bound to."),
-	keys: z.array(PublicKeyView).describe("Every registered key, expired and revoked ones included.")
-}).describe("Every key registered against this connection, with its window.");
+	keys: z.array(PublicKeyView).describe("Every registered key, expired and revoked ones included."),
+	authorizedBy: ConnectionPrincipal.nullable().optional().describe("Who sanctioned this connection — the signed-in session's email at registration. Null for a connection registered before principals were recorded; absent from a Worker older than the field."),
+	actorKind: ControlPlaneActorKind.nullable().optional().describe("What kind of client this connection is for: `agent`, `dashboard` or `script`. Null for a connection registered before it was recorded; absent from an older Worker."),
+	purpose: ConnectionPurpose.nullable().optional().describe("What the client is for, in the registering operator's words. Untrusted text: render it escaped. Null for a connection registered before it was recorded; absent from an older Worker.")
+}).describe("Every key registered against this connection, with its window, and who authorized it for what.");
 /** `POST /control-plane/keys` — the appended key, and the set as it now stands. */
 const RegisterKeyResponse = z.object({
 	keyId: z.string().describe("The key just registered."),
@@ -61,5 +64,59 @@ const ExpireKeyResponse = z.object({
 	validUntil: z.iso.datetime().describe("When its window closed, ISO-8601 — now, by construction."),
 	keys: z.array(PublicKeyView).describe("The connection's keys after the expiry.")
 }).describe("The expired key, and the set it left behind.");
+/**
+* One migration as `GET {basePath}/migrations` reports it: its composed name, and whose it is.
+*
+* The namespace is a capability's name, which the manifest already reports in `capabilities[]`. So a
+* client tells an adopter's own migrations from a composed capability's by comparing the two — no
+* convention, and no list kept anywhere.
+*/
+const MigrationView = z.object({
+	name: z.string().describe("The composed migration name, exactly as the ledger records it: `0250_audit_0001_init`."),
+	namespace: z.string().nullable().describe("The capability this migration belongs to — its name, as `capabilities[]` in the manifest reports it. Null only for an undeclared migration whose name no Pithy registry could have composed.")
+}).describe("One migration, and the capability namespace it belongs to.");
+/** Whether the last group is still reversible by name, or what is in its way. */
+const MigrationGroupPositionView = z.discriminatedUnion("state", [z.object({ state: z.literal("top").describe("The group's migrations are the contiguous tip of this database's chain. Not a promise that `pithy migrate --rollback --group <value>` runs: the CLI also refuses an undeclared migration in the ledger, and keeps back or refuses a database another environment binds.") }).describe("A group nothing on this database's ledger sits over."), z.object({
+	state: z.literal("buried").describe("Something sits over the group or inside it, so reversing it by name is refused."),
+	above: z.array(z.string()).describe("The groups in the way, newest first."),
+	ungrouped: z.array(MigrationView).describe("The migrations in the way that no group claims, newest first. Nothing can be reversed by group while one of them is at the tip.")
+}).describe("A group with something in its way, and what that is.")]).describe("Where the last group sits in this database's chain: the top, or buried under named things.");
+/** The run that last moved a database, and whether it can still be taken back. */
+const MigrationGroupView = z.object({
+	group: z.string().describe("The group's value: the `--group` the run was given, or the ISO-8601 timestamp it generated."),
+	appliedAt: z.iso.datetime().describe("When this group last applied something here, ISO-8601."),
+	migrations: z.array(MigrationView).describe("What this group applied in this database and is still applied, in application order."),
+	position: MigrationGroupPositionView.describe("Whether the group is the top of the chain, or what is in its way.")
+}).describe("The newest group with anything still applied in this database.");
+/**
+* One database this Worker binds, read or not.
+*
+* **An unreadable database carries no list at all**, never empty ones. `pending: []` reads as up to date,
+* and a database nobody read is not that. The state is on the value, so a client reaches a list only by
+* narrowing.
+*/
+const MigrationDatabaseView = z.discriminatedUnion("state", [z.object({
+	state: z.literal("readable").describe("This database's ledger was read."),
+	database: z.string().describe("The database name, as capabilities declare it in `databases`."),
+	binding: z.string().describe("The D1 binding it is read through, as `wrangler.jsonc` declares it."),
+	applied: z.array(MigrationView).describe("Every applied migration, in the order the ledger applied them."),
+	pending: z.array(MigrationView).describe("Declared by this build and not applied here, in the order they would run."),
+	undeclared: z.array(MigrationView).describe("Applied here and not declared by this Worker, sorted. Relative to this Worker: a database shared with another Worker lists that Worker's migrations here. Otherwise Kysely reads one as a corrupted chain and applies nothing."),
+	lastGroup: MigrationGroupView.nullable().describe("The newest group with anything applied here, or null when nothing applied here was ever grouped.")
+}).describe("A database whose ledger was read."), z.object({
+	state: z.literal("unreadable").describe("This database's ledger could not be read on this call."),
+	database: z.string().describe("The database name, as capabilities declare it in `databases`."),
+	binding: z.string().describe("The D1 binding it would be read through.")
+}).describe("A database that could not be read. No lists, so nothing about it reads as zero. The other databases still answer.")]).describe("One database this Worker binds: its migration state, or the fact that it could not be read.");
+/**
+* `GET /control-plane/migrations` — where every database this Worker binds stands.
+*
+* Asked of the Worker because the Worker *is* the deployed build. `pithy doctor` reads the project on disk,
+* which is what the operator has and not necessarily what is deployed.
+*/
+const ControlPlaneMigrationsResponse = z.object({
+	environment: z.string().describe("The environment this Worker answers for."),
+	databases: z.array(MigrationDatabaseView).describe("One entry per database this Worker binds, sorted by database name. One unreadable costs only itself.")
+}).describe("What is applied, pending and undeclared in each bound database, and which run put it there.");
 //#endregion
-export { ControlPlaneKeysResponse, ControlPlanePingResponse, ExpireKeyResponse, PublicKeyView, RegisterKeyResponse };
+export { ControlPlaneKeysResponse, ControlPlaneMigrationsResponse, ControlPlanePingResponse, ExpireKeyResponse, MigrationDatabaseView, MigrationGroupPositionView, MigrationGroupView, MigrationView, PublicKeyView, RegisterKeyResponse };

package/dist/controlPlane/http/routes.d.ts

@@ -12,6 +12,7 @@ import { type ControlPlaneHandlerDeps } from "./handlers";
  *   GET  /control-plane/keys                  → the registration state       (keys:rotate)
  *   POST /control-plane/keys                  → register a key               (keys:rotate)
  *   POST /control-plane/keys/:keyId/expire    → retire a superseded key      (keys:rotate)
+ *   GET  /control-plane/migrations            → where each database stands   (migrations:read)
  *
  * Every one is `control-plane` and default-denied — with no connection registered they all answer 403,
  * and that is the shipped state of a Worker nobody has connected.

package/dist/controlPlane/http/routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/http/routes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAGhE,OAAO,EAAE,KAAK,UAAU,EAAwB,MAAM,yBAAyB,CAAC;AAGhF,OAAO,EACL,KAAK,uBAAuB,EAM7B,MAAM,YAAY,CAAC;AASpB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,EAAE,CAiC3E;AAED,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,EACvB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,uBAAuB,GAC5B,IAAI,CA+DN"}
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/http/routes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAGhE,OAAO,EAAE,KAAK,UAAU,EAAwB,MAAM,yBAAyB,CAAC;AAGhF,OAAO,EACL,KAAK,uBAAuB,EAO7B,MAAM,YAAY,CAAC;AAUpB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,EAAE,CAwC3E;AAED,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,EACvB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,uBAAuB,GAC5B,IAAI,CA6EN"}

package/dist/controlPlane/http/routes.js

@@ -1,12 +1,12 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
-import { ANY_VERIFIED_CALLER, KEYS_ROTATE_SCOPE, MANIFEST_READ_SCOPE } from "../scope/scope.js";
+import { ANY_VERIFIED_CALLER, KEYS_ROTATE_SCOPE, MANIFEST_READ_SCOPE, MIGRATIONS_READ_SCOPE } from "../scope/scope.js";
 import { requireControlPlane } from "./guard.js";
 import { describeRoute } from "../../http/routeSpec.js";
 import { validate } from "../../http/validation.js";
 import { ControlPlaneManifest } from "../discovery/adminRoute.js";
-import { expireKeyHandler, listKeysHandler, manifestHandler, pingHandler, registerKeyHandler } from "./handlers.js";
-import { ControlPlaneKeysResponse, ControlPlanePingResponse, ExpireKeyResponse, RegisterKeyResponse } from "./responses.js";
+import { expireKeyHandler, listKeysHandler, manifestHandler, migrationsHandler, pingHandler, registerKeyHandler } from "./handlers.js";
+import { ControlPlaneKeysResponse, ControlPlaneMigrationsResponse, ControlPlanePingResponse, ExpireKeyResponse, RegisterKeyResponse } from "./responses.js";
 import { ExpireKeyParams, ExpireKeyRequest, RegisterKeyRequest } from "./schemas.js";
 //#region src/controlPlane/http/routes.ts
 /**
@@ -17,6 +17,7 @@ import { ExpireKeyParams, ExpireKeyRequest, RegisterKeyRequest } from "./schemas
 *   GET  /control-plane/keys                  → the registration state       (keys:rotate)
 *   POST /control-plane/keys                  → register a key               (keys:rotate)
 *   POST /control-plane/keys/:keyId/expire    → retire a superseded key      (keys:rotate)
+*   GET  /control-plane/migrations            → where each database stands   (migrations:read)
 *
 * Every one is `control-plane` and default-denied — with no connection registered they all answer 403,
 * and that is the shipped state of a Worker nobody has connected.
@@ -73,6 +74,12 @@ function controlPlaneRouteDescriptors(basePath) {
 			path: `${basePath}/keys/:keyId/expire`,
 			scope: KEYS_ROTATE_SCOPE,
 			summary: "Retire a superseded key. Must be signed with the successor it names as proven."
+		},
+		{
+			method: "GET",
+			path: `${basePath}/migrations`,
+			scope: MIGRATIONS_READ_SCOPE,
+			summary: "What each bound database has applied, what is pending, what is undeclared, and which run put it there. Undeclared is relative to this Worker."
 		}
 	];
 }
@@ -107,6 +114,13 @@ function registerControlPlaneRoutes(app, basePath, deps) {
 		scopes: [KEYS_ROTATE_SCOPE],
 		responses: { 200: ExpireKeyResponse }
 	}), requireControlPlane(KEYS_ROTATE_SCOPE), validate("param", ExpireKeyParams), validate("json", ExpireKeyRequest), (c) => expireKeyHandler(deps)(c, c.req.valid("param"), c.req.valid("json")));
+	app.get(`${basePath}/migrations`, describeRoute({
+		summary: "Report where each database this Worker binds stands.",
+		description: "Applied, pending and undeclared migrations per database, each naming its namespace, and the last group with whether it is still reversible. Undeclared is relative to this Worker: a database shared with another Worker lists that Worker's migrations there. Read-only.",
+		verification: "control-plane",
+		scopes: [MIGRATIONS_READ_SCOPE],
+		responses: { 200: ControlPlaneMigrationsResponse }
+	}), requireControlPlane(MIGRATIONS_READ_SCOPE), migrationsHandler(deps));
 }
 //#endregion
 export { controlPlaneRouteDescriptors, registerControlPlaneRoutes };

package/dist/controlPlane/http/verify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/http/verify.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAOjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,KAAK,uBAAuB,EAAe,MAAM,gBAAgB,CAAC;AAI3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;;;;;;;GASG;AACH,OAAO,EAAE,oBAAoB,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAC;AAE7E,0GAA0G;AAC1G,MAAM,WAAW,sBAAsB;IACrC,8FAA8F;IAC9F,cAAc,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAAC;IACjF;;;;;OAKG;IACH,gBAAgB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC,sCAAsC;IACtC,MAAM,EAAE,WAAW,CAAC;IACpB,wEAAwE;IACxE,WAAW,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,MAAM,EAAE,kBAAkB,CAAC;IAC3B,8DAA8D;IAC9D,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB;AAED,qEAAqE;AACrE,MAAM,WAAW,gBAAgB;IAC/B,iGAAiG;IACjG,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,4EAA4E;IAC5E,IAAI,EAAE,UAAU,CAAC;IACjB,4EAA4E;IAC5E,WAAW,EAAE,uBAAuB,CAAC;CACtC;AAOD;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,gBAAgB,EACtB,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,mBAAmB,CAAC,CA2E9B"}
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/http/verify.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAOjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,KAAK,uBAAuB,EAAe,MAAM,gBAAgB,CAAC;AAI3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;;;;;;;GASG;AACH,OAAO,EAAE,oBAAoB,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAC;AAE7E,0GAA0G;AAC1G,MAAM,WAAW,sBAAsB;IACrC,8FAA8F;IAC9F,cAAc,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAAC;IACjF;;;;;OAKG;IACH,gBAAgB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC,sCAAsC;IACtC,MAAM,EAAE,WAAW,CAAC;IACpB,wEAAwE;IACxE,WAAW,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,MAAM,EAAE,kBAAkB,CAAC;IAC3B,8DAA8D;IAC9D,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB;AAED,qEAAqE;AACrE,MAAM,WAAW,gBAAgB;IAC/B,iGAAiG;IACjG,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,4EAA4E;IAC5E,IAAI,EAAE,UAAU,CAAC;IACjB,4EAA4E;IAC5E,WAAW,EAAE,uBAAuB,CAAC;CACtC;AAOD;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,gBAAgB,EACtB,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,mBAAmB,CAAC,CA6E9B"}

package/dist/controlPlane/http/verify.js

@@ -47,7 +47,8 @@ async function verifyControlPlaneCall(call, deps) {
 		scope: claims.scope,
 		grantedScopes: connection.scopes,
 		keyId: key.keyId,
-		tokenId: claims.jti
+		tokenId: claims.jti,
+		actorKind: connection.actorKind
 	});
 }
 /**