@pithy-sh/core 0.10.0 → 0.12.0

package/src/controlPlane/error/errors.ts

@@ -4,6 +4,7 @@
 import { commandName } from "../../cli/command";
 import { PithyError } from "../../error/pithyError";
 import type { MessageParams } from "../../i18n/catalog";
+import type { UnmarkedString } from "../../privacy/types";
 
 /**
  * The `control-plane` strategy's throw sugar. The `controlplane/*` codes live in core's closed
@@ -20,9 +21,9 @@ import type { MessageParams } from "../../i18n/catalog";
  */
 
 interface ControlPlaneErrorArgs {
-  message?: string;
-  action?: string;
-  detail?: string;
+  message?: UnmarkedString;
+  action?: UnmarkedString;
+  detail?: UnmarkedString;
   /**
    * Values a translating client interpolates into its own wording for this code. Client-facing, so —
    * unlike `action` and `detail` — these cross the boundary with `message`.

package/src/controlPlane/http/cors.ts

@@ -217,10 +217,10 @@ export function corsMiddleware(
 /**
  * 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/src/controlPlane/http/guard.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import type { MiddlewareHandler } from "hono";
+import type { AuditEmit } from "../../audit/recorder";
 import type { PithyHonoEnv } from "../../capability/capability";
 import { commandName, remedy } from "../../cli/command";
 import { type AmbientEnv, compositionEnvironment } from "../../env/ambient";
@@ -9,6 +10,7 @@ import { PithyError } from "../../error/pithyError";
 import { workerVersionMetadata } from "../../worker/identity";
 import { ControlPlaneAuditActions, safeEmit } from "../audit/actions";
 import type { ControlPlaneContext } from "../context";
+import type { ControlPlaneActorKind } from "../data/connection";
 import { ControlPlaneNotConnectedError } from "../error/errors";
 import type { ControlPlaneRequirement } from "../scope/scope";
 import { CONTROL_PLANE_HEADER, CONTROL_PLANE_VERSION_CREATED_HEADER, CONTROL_PLANE_VERSION_HEADER } from "../wire";
@@ -156,6 +158,11 @@ export function requireControlPlane(requirement: ControlPlaneRequirement): Middl
     }
 
     c.set("controlPlane", context);
+    // Every control-plane row this call writes says which kind of client wrote it (#721). Stamped here,
+    // once, rather than at each of the dozens of emit sites across the capabilities, because a rule kept
+    // at the call sites regrows the moment someone adds one — and `actorType` alone names an agent, the
+    // dashboard and a script identically.
+    c.set("emit", stampActorKind(c.var.emit, context.actorKind));
     await safeEmit(
       c.var.emit,
       {
@@ -185,6 +192,20 @@ export function requireControlPlane(requirement: ControlPlaneRequirement): Middl
   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.
+ */
+export function stampActorKind(emit: AuditEmit, actorKind: ControlPlaneActorKind | null): AuditEmit {
+  if (actorKind === null) return emit;
+  return (event) =>
+    emit(event.actorType === "control-plane" && event.actorKind == null ? { ...event, actorKind } : event);
+}
+
 /**
  * Record a refused call.
  *

package/src/controlPlane/http/handlers.ts

@@ -3,7 +3,11 @@
 
 import type { Context } from "hono";
 import type { PithyHonoEnv } from "../../capability/capability";
-import { workerVersion } from "../../worker/identity";
+import { causeMessage } from "../../error/cause";
+import { privacyAttestation, privacyPosture } from "../../privacy/posture";
+import type { PrivacyInventory } from "../../privacy/report";
+import type { RetirementVerdict } from "../../privacy/retirement";
+import { workerVersionMetadata } from "../../worker/identity";
 import { ControlPlaneAuditActions, safeEmit } from "../audit/actions";
 import type { ControlPlaneConfig } from "../config/config";
 import type { ControlPlaneContext } from "../context";
@@ -14,9 +18,12 @@ import type { CapabilityDeclaration, ControlPlaneManifestWire } from "../discove
 import { type CapabilityHealthSource, readCapabilityHealth } from "../discovery/health";
 import { healthWire } from "../discovery/healthSummary";
 import { ControlPlaneInvalidCredentialError, ControlPlaneKeyConflictError } from "../error/errors";
+import { type ComposedMigrationDatabase, readDatabaseMigrations } from "../migrationState/migrationState";
 import type {
   ControlPlaneKeysResponse,
+  ControlPlaneMigrationsResponse,
   ControlPlanePingResponse,
+  ControlPlanePrivacyResponse,
   ExpireKeyResponse,
   PublicKeyView,
   RegisterKeyResponse,
@@ -68,6 +75,21 @@ 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 privacy inventory of every storage schema this Worker composed (#132), walked on the first call and
+   * cached for the isolate. A thunk, so a Worker whose control plane is never called never walks.
+   */
+  privacyInventory: () => PrivacyInventory;
+  /**
+   * The field key's retirement verdict (#390): the guard over this Worker's encrypted columns, read through its own
+   * bindings. Never throws: whatever it cannot read is incomplete coverage.
+   */
+  retirement: (env: Record<string, unknown>) => Promise<RetirementVerdict>;
   /** The clock, injected so a test can stand at any instant. */
   now: () => Date;
 }
@@ -191,18 +213,57 @@ export function manifestHandler(deps: ControlPlaneHandlerDeps) {
         ),
       })),
     );
+    // The build answering this call. Read per request rather than captured at assembly: it is the same
+    // binding every log record and audit event reads, and there is one reader for it.
+    const build = workerVersionMetadata(c.env);
     return c.json({
       environment: context.environment,
       connectionId: context.connectionId,
-      // The build answering this call. Read per request rather than captured at assembly: it is the
-      // same binding every log record and audit event reads, and there is one reader for it.
-      version: workerVersion(c.env),
+      version: build.id,
+      // Beside the id, because the id alone cannot tell a deploy from a rollback (#132): a rollback
+      // reactivates a version already seen, and this is the one field that moves backwards when it does.
+      versionCreatedAt: build.createdAt,
+      // Classes and counts, never field names — those are `GET /privacy`'s, behind their own scope. A project
+      // that declared nothing walks nothing; otherwise the walk is the isolate's cached one.
+      // The retirement verdict beside it (#390), so a dashboard reads the guard rather than inferring it.
+      privacy: {
+        ...privacyPosture(privacyAttestation(c.env), deps.privacyInventory),
+        retirement: await deps.retirement(c.env as Record<string, unknown>),
+      },
       capabilities,
       grantedScopes: [...context.grantedScopes],
     } satisfies ControlPlaneManifestWire);
   };
 }
 
+/**
+ * `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 function migrationsHandler(deps: ControlPlaneHandlerDeps) {
+  return async (c: Context<PithyHonoEnv>) => {
+    const context = caller(c);
+    const env = c.env as Record<string, unknown>;
+    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 } satisfies ControlPlaneMigrationsResponse);
+  };
+}
+
 /** `GET /control-plane/keys` — the registration state, so a client can surface a stale key. */
 export function listKeysHandler(deps: ControlPlaneHandlerDeps) {
   return async (c: Context<PithyHonoEnv>) => {
@@ -212,6 +273,11 @@ export function listKeysHandler(deps: ControlPlaneHandlerDeps) {
       connectionId: connection.id,
       environment: connection.environment,
       keys: connection.keys.map(publicKeyView),
+      // The review a credential listing exists for needs these, and it is the adopter's to perform —
+      // on their own side, from their own row (#721).
+      authorizedBy: connection.authorizedBy,
+      actorKind: connection.actorKind,
+      purpose: connection.purpose,
     } satisfies ControlPlaneKeysResponse);
   };
 }
@@ -344,3 +410,31 @@ export function expireKeyHandler(deps: ControlPlaneHandlerDeps) {
     } satisfies ExpireKeyResponse);
   };
 }
+
+/**
+ * `GET /control-plane/privacy` — the full privacy inventory (#132).
+ *
+ * Every storage schema this Worker composed that holds a marked field, each field's path and class, and where it
+ * is stored — derived from the running code, so unmarking a field removes it on the next deploy with nothing in
+ * between. Behind `privacy:read`, because field names are the kind of thing an adopter may withhold from a client
+ * that has no business seeing them. Read-only.
+ */
+export function privacyHandler(deps: ControlPlaneHandlerDeps) {
+  return async (c: Context<PithyHonoEnv>) => {
+    const context = caller(c);
+    const inventory = deps.privacyInventory();
+    return c.json({
+      environment: context.environment,
+      posture: {
+        ...privacyPosture(privacyAttestation(c.env), () => inventory),
+        retirement: await deps.retirement(c.env as Record<string, unknown>),
+      },
+      schemasWalked: inventory.schemasWalked,
+      schemas: inventory.schemas.map((schema) => ({
+        ...schema,
+        fields: schema.fields.map((field) => ({ ...field })),
+        encrypted: schema.encrypted.map((field) => ({ ...field })),
+      })),
+    } satisfies ControlPlanePrivacyResponse);
+  };
+}

package/src/controlPlane/http/readiness.ts

@@ -0,0 +1,50 @@
+// 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 function registerReadinessGuards(
+  app: Hono<PithyHonoEnv>,
+  surface: readonly { path: string }[],
+  guards: readonly PithyReadinessGuard[],
+): void {
+  if (guards.length === 0) return;
+
+  const onSurface = new WeakSet<Request>();
+  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)));
+  }
+}

package/src/controlPlane/http/responses.ts

@@ -2,7 +2,9 @@
 // SPDX-License-Identifier: MIT
 
 import { z } from "zod";
-import { Ed25519PublicJwk } from "../data/connection";
+import { PrivacyPosture } from "../../privacy/posture";
+import { PRIVACY_SOURCES } from "../../privacy/report";
+import { ConnectionPrincipal, ConnectionPurpose, ControlPlaneActorKind, Ed25519PublicJwk } from "../data/connection";
 
 /**
  * What the seam's own routes return, as Zod objects a management client can validate against.
@@ -65,8 +67,25 @@ export const ControlPlaneKeysResponse = z
     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."),
+    // Added (#721), so `.optional()` as well as `.nullable()`: a client validating against a Worker that
+    // predates the three columns receives none of them, and must still parse the answer.
+    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.");
+  .describe("Every key registered against this connection, with its window, and who authorized it for what.");
 export type ControlPlaneKeysResponse = z.output<typeof ControlPlaneKeysResponse>;
 
 /** `POST /control-plane/keys` — the appended key, and the set as it now stands. */
@@ -90,3 +109,222 @@ export const ExpireKeyResponse = z
   })
   .describe("The expired key, and the set it left behind.");
 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 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.");
+export type MigrationView = z.output<typeof MigrationView>;
+
+/** Whether the last group is still reversible by name, or what is in its way. */
+export 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.");
+export type MigrationGroupPositionView = z.output<typeof MigrationGroupPositionView>;
+
+/** The run that last moved a database, and whether it can still be taken back. */
+export 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.");
+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 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.");
+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 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.");
+export type ControlPlaneMigrationsResponse = z.output<typeof ControlPlaneMigrationsResponse>;
+
+/**
+ * One marked field, as `GET {basePath}/privacy` reports it (#132).
+ *
+ * **The per-field record.** Since #390 it says whether the field rests encrypted beside `class`, so "which of
+ * your PHI fields are encrypted" is a derivation over this list rather than a second inventory to keep.
+ */
+export const PrivacyFieldView = z
+  .object({
+    path: z
+      .string()
+      .describe(
+        "Where the field sits. A D1 column path (`email`, `address.line1`, `profile.phone` inside a JSON column), or a KV entry's part first (`key.email`, `value.token`, `metadata.ip`, or `value` for a whole marked value). An array element is `[]`, a record's value `*`.",
+      ),
+    class: z
+      .string()
+      .describe("The privacy class it is marked with: `secret`, `pii`, `phi`, `pci`, or an adopter's own."),
+    truncated: z
+      .literal(true)
+      .optional()
+      .describe(
+        "Set where the class is assumed rather than found: a read ran out of its budget there, or the schema could not be read at all, so any class may be marked below it. Absent where the schema was read to the end.",
+      ),
+    sameAs: z
+      .string()
+      .optional()
+      .describe(
+        "Set on a reference: the path this field's position was first listed under, once the list reached its cap on paths. The class is marked somewhere beneath both, and the paths beneath this one are those beneath that one.",
+      ),
+    encryptedAtRest: z
+      .boolean()
+      .optional()
+      .describe(
+        "Whether the field rests encrypted (#390). Absent where the core cannot say — an assumed class, a reference, or a core older than encrypted fields — and never defaulted to false.",
+      ),
+    unrotatable: z
+      .literal(true)
+      .optional()
+      .describe(
+        "Set on an encrypted field whose storage is not D1: it can never be rotated, and it blocks retirement.",
+      ),
+  })
+  .describe("One marked field and its class.");
+export type PrivacyFieldView = z.output<typeof PrivacyFieldView>;
+
+/** One storage schema holding at least one marked field. */
+export const PrivacySchemaView = z
+  .object({
+    capability: z
+      .string()
+      .describe("The capability that declared the schema, as the manifest's `capabilities[]` names it."),
+    storage: z.enum(PRIVACY_SOURCES).describe("Where it is stored: a `d1` table or a `kv` store."),
+    container: z.string().describe("The D1 database name or the KV namespace name it lives in."),
+    name: z.string().describe("The table name, or the KV store name."),
+    fields: z.array(PrivacyFieldView).describe("Every marked field in it, in schema order."),
+    encrypted: z
+      .array(
+        z
+          .object({
+            path: z.string().describe("Where the encrypted field sits, on the same paths as `fields[].path`."),
+            unrotatable: z
+              .literal(true)
+              .optional()
+              .describe("Set where the storage is not D1, so the field can never be rotated."),
+          })
+          .describe("One encrypted field."),
+      )
+      .optional()
+      .describe(
+        "Every field marked encrypted at rest, classed or not (#390). Absent on a Worker whose core predates encrypted fields.",
+      ),
+  })
+  .describe("One storage schema and the marked fields it holds.");
+export type PrivacySchemaView = z.output<typeof PrivacySchemaView>;
+
+/**
+ * `GET /control-plane/privacy` — the full inventory, behind `privacy:read` (#132).
+ *
+ * Derived at runtime from the schemas this Worker composed, walked once per isolate. The manifest's `privacy`
+ * block is the headline; this is the detail, and it names fields, which is why it has a scope of its own.
+ */
+export const ControlPlanePrivacyResponse = z
+  .object({
+    environment: z.string().describe("The environment this Worker answers for."),
+    posture: PrivacyPosture.describe("The declared and observed classes, the delta, and the console gate."),
+    schemasWalked: z
+      .number()
+      .int()
+      .nonnegative()
+      .describe("How many storage schemas were walked, marked or not, across the sources `posture.sources` names."),
+    schemas: z
+      .array(PrivacySchemaView)
+      .describe("Every schema holding a marked field, in composition order. A schema with none is not listed."),
+  })
+  .describe(
+    "Every schema this Worker stores that holds a marked field, each field's path and class, and where it lives.",
+  );
+export type ControlPlanePrivacyResponse = z.output<typeof ControlPlanePrivacyResponse>;

package/src/controlPlane/http/routes.ts

@@ -6,19 +6,29 @@ import type { PithyHonoEnv } from "../../capability/capability";
 import { describeRoute } from "../../http/routeSpec";
 import { validate } from "../../http/validation";
 import { type AdminRoute, ControlPlaneManifest } from "../discovery/adminRoute";
-import { ANY_VERIFIED_CALLER, KEYS_ROTATE_SCOPE, MANIFEST_READ_SCOPE } from "../scope/scope";
+import {
+  ANY_VERIFIED_CALLER,
+  KEYS_ROTATE_SCOPE,
+  MANIFEST_READ_SCOPE,
+  MIGRATIONS_READ_SCOPE,
+  PRIVACY_READ_SCOPE,
+} from "../scope/scope";
 import { requireControlPlane } from "./guard";
 import {
   type ControlPlaneHandlerDeps,
   expireKeyHandler,
   listKeysHandler,
   manifestHandler,
+  migrationsHandler,
   pingHandler,
+  privacyHandler,
   registerKeyHandler,
 } from "./handlers";
 import {
   ControlPlaneKeysResponse,
+  ControlPlaneMigrationsResponse,
   ControlPlanePingResponse,
+  ControlPlanePrivacyResponse,
   ExpireKeyResponse,
   RegisterKeyResponse,
 } from "./responses";
@@ -32,6 +42,8 @@ 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)
+ *   GET  /control-plane/privacy               → what each schema holds        (privacy: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.
@@ -90,6 +102,20 @@ export function controlPlaneRouteDescriptors(basePath: string): AdminRoute[] {
       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.",
+    },
+    {
+      method: "GET",
+      path: `${basePath}/privacy`,
+      scope: PRIVACY_READ_SCOPE,
+      summary:
+        "Every stored schema holding a privacy-marked field, each field's path and class, and where it lives. Derived from the running code.",
+    },
   ];
 }
 
@@ -160,4 +186,32 @@ export function registerControlPlaneRoutes(
     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),
+  );
+
+  app.get(
+    `${basePath}/privacy`,
+    describeRoute({
+      summary: "Report every stored field marked with a privacy class.",
+      description:
+        "Every D1 table and KV store this Worker composed that holds a privacy-marked field, with each field's path, its class and where it is stored, beside the declared-and-observed posture. Derived at runtime from the deployed schemas. Read-only.",
+      verification: "control-plane",
+      scopes: [PRIVACY_READ_SCOPE],
+      responses: { 200: ControlPlanePrivacyResponse },
+    }),
+    requireControlPlane(PRIVACY_READ_SCOPE),
+    privacyHandler(deps),
+  );
 }

package/src/controlPlane/http/verify.ts

@@ -178,6 +178,8 @@ export async function verifyControlPlaneCall(
     grantedScopes: connection.scopes,
     keyId: key.keyId,
     tokenId: claims.jti,
+    // From the adopter's row, never the token: a client does not get to say what kind of client it is.
+    actorKind: connection.actorKind,
   });
 }