@pithy-sh/core 0.9.0 → 0.11.0

package/dist/controlPlane/error/errors.js

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 import { PithyError } from "../../error/pithyError.js";
+import { commandName } from "../../cli/command.js";
 //#region src/controlPlane/error/errors.ts
 /**
 * No connection is registered for this environment. The shipped default of a Worker that composes the
@@ -12,7 +13,7 @@ var ControlPlaneNotConnectedError = class extends PithyError {
 			code: "controlplane/not_connected",
 			status: 403,
 			message: args.message ?? "No management client is connected to this environment.",
-			action: args.action ?? "Run pithy dashboard connect --env <environment> to register one.",
+			action: args.action ?? `Register one for this environment with ${commandName("dashboard connect")}, naming it with --env.`,
 			detail: args.detail,
 			params: args.params
 		}, options);
@@ -28,7 +29,7 @@ var ControlPlaneInvalidCredentialError = class extends PithyError {
 			code: "controlplane/invalid_credential",
 			status: 401,
 			message: args.message ?? "That credential is not valid here.",
-			action: args.action ?? "Rotate the connection's key, or re-run pithy dashboard connect --update.",
+			action: args.action ?? `Rotate the connection's key, or update this environment's connection with ${commandName("dashboard connect")} and its --update flag.`,
 			detail: args.detail,
 			params: args.params
 		}, options);
@@ -41,7 +42,7 @@ var ControlPlaneInsufficientScopeError = class extends PithyError {
 			code: "controlplane/insufficient_scope",
 			status: 403,
 			message: args.message ?? "This connection is not scoped for that operation.",
-			action: args.action ?? "Re-run pithy dashboard connect --update and grant the scope this call needs.",
+			action: args.action ?? `Update this environment's connection with ${commandName("dashboard connect")} and its --update flag, granting the scope this call needs.`,
 			detail: args.detail,
 			params: args.params
 		}, options);

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

@@ -93,10 +93,10 @@ export declare function corsMiddleware(entry: CorsSurfaceEntry, origins: Readonl
 /**
  * Mount one `app.use(path, …)` per entry.
  *
- * **Called from the capability's `middleware` hook, never its `routes` hook, and that is load-bearing.**
- * `createBackend` runs every capability's `middleware` hook before **any** capability's `routes` hook
- * (`createBackend.ts:262-267`), which is what makes this independent of the order an adopter happens to
- * list their capabilities in.
+ * **Called from `createBackend` ahead of every capability's `middleware`, never from a `routes` hook,
+ * and that is load-bearing.** Registered there, it is independent of the order an adopter happens to
+ * list their capabilities in, and it can put a header on whatever a capability's middleware or a
+ * readiness guard short-circuits.
  *
  * From `routes` it looks like it works and does not. The preflight still answers — an `OPTIONS` has no
  * route handler to lose to, so this `use` is the only thing that matches it — but a capability composed

package/dist/controlPlane/http/cors.js

@@ -170,10 +170,10 @@ function corsMiddleware(entry, origins, maxAgeSeconds) {
 /**
 * Mount one `app.use(path, …)` per entry.
 *
-* **Called from the capability's `middleware` hook, never its `routes` hook, and that is load-bearing.**
-* `createBackend` runs every capability's `middleware` hook before **any** capability's `routes` hook
-* (`createBackend.ts:262-267`), which is what makes this independent of the order an adopter happens to
-* list their capabilities in.
+* **Called from `createBackend` ahead of every capability's `middleware`, never from a `routes` hook,
+* and that is load-bearing.** Registered there, it is independent of the order an adopter happens to
+* list their capabilities in, and it can put a header on whatever a capability's middleware or a
+* readiness guard short-circuits.
 *
 * From `routes` it looks like it works and does not. The preflight still answers — an `OPTIONS` has no
 * route handler to lose to, so this `use` is the only thing that matches it — but a capability composed

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;AAIhE,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

@@ -1,7 +1,9 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 import { PithyError } from "../../error/pithyError.js";
+import { commandName, remedy } from "../../cli/command.js";
 import { workerVersionMetadata } from "../../worker/identity.js";
+import { compositionEnvironment } from "../../env/ambient.js";
 import { ControlPlaneAuditActions, safeEmit } from "../audit/actions.js";
 import { ControlPlaneNotConnectedError } from "../error/errors.js";
 import { CONTROL_PLANE_VERSION_CREATED_HEADER, CONTROL_PLANE_VERSION_HEADER } from "../wire.js";
@@ -69,7 +71,7 @@ function requireControlPlane(requirement) {
 		if (!verify) {
 			const denial = new ControlPlaneNotConnectedError({
 				message: "This deployment does not accept management-client calls.",
-				action: "Add `controlplane()` to this Worker's pithy.config.ts, then run pithy dashboard connect.",
+				action: `Add \`controlplane()\` to this Worker's pithy.config.ts, then ${connectStep(compositionEnvironment(c.env))}.`,
 				detail: "no control-plane verifier on the request — the controlplane capability is not composed"
 			});
 			await auditDenial(c, requirement, denial);
@@ -83,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",
@@ -108,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
@@ -140,5 +158,13 @@ async function auditDenial(c, requirement, cause) {
 		}
 	}, c.var.log);
 }
+/**
+* The step that connects a management client, as this deployed Worker can name it: with its own environment when
+* it knows it, and never with a Worker — it cannot know the `apps/` directory that provisioned it (#711).
+*/
+function connectStep(env) {
+	if (env === void 0) return `connect one with ${commandName("dashboard connect")}, naming this environment with --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"}