@pithy-sh/core 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pithy-sh/core",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/audit/recorder.ts

@@ -1,7 +1,8 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 
-import type { AuditEventInput } from "./auditEvent";
+import type { Loggable } from "../privacy/types";
+import type { AuditEventInput, AuditMetadata } from "./auditEvent";
 
 /**
  * The recorder seam. `emit()` on the request context (`c.var.emit`) takes one {@link AuditEventInput}
@@ -12,8 +13,15 @@ import type { AuditEventInput } from "./auditEvent";
  * `emit()` is **non-fatal by contract**: it never throws and never rejects, so an audited action is
  * never broken by an audit write. The real recorder swallows and logs its own failures; the no-op
  * simply resolves.
+ *
+ * **`metadata` refuses a value marked with a privacy class** (#132). The trail is the longest-lived internal
+ * surface there is — a row in the adopter's D1 with no retention window — so a `pii()`/`phi()`/`secret()`/
+ * `pci()` value in it, or inside an object in it, is a compile error, by the same `Loggable` rule the logger
+ * applies. `AuditMetadata` the schema stays permissive: a stored row still parses.
  */
-export type AuditEmit = (event: AuditEventInput) => Promise<void>;
+export type AuditEmit = <M extends AuditMetadata = AuditMetadata>(
+  event: Omit<AuditEventInput, "metadata"> & { metadata?: (M & Loggable<M>) | null | undefined },
+) => Promise<void>;
 
 /**
  * The default recorder when no audit capability is composed: accept the event and drop it. Resolves

package/src/capability/capability.ts

@@ -26,6 +26,7 @@ import type { SeedSet } from "../seed/seed";
 import type { WorkflowSpecMap } from "../workflow/spec";
 import { BindingSpec, type BindingSpecInput } from "./bindings";
 import type { ClientProjection, ClientProjectionContext } from "./client";
+import { assertPurgeContributions, type PurgeContribution } from "./purge";
 import type { CapabilitySettings } from "./settings";
 
 /** Hono `Variables` every capability's routes are typed against. `createBackend` seeds these per request. */
@@ -658,6 +659,17 @@ export interface Capability<
    * time, and read by `pithy doctor`.
    */
   extensions?: readonly CapabilityExtension[];
+  /**
+   * How this capability erases one subject's rows when that subject is purged — see `./purge.ts`. Omit it
+   * when this capability holds nothing keyed to a person, which is the ordinary case.
+   *
+   * **The purge Workflow runs each composed contribution as its own step**, named for this capability, so a
+   * failure retries this capability alone and the steps that finished are not re-run. That is why there is
+   * at most one per subject here, and why `erase` must succeed when there is nothing left to erase.
+   * `defineCapability` refuses a contribution for a subject the kit does not know. An adopter declares one
+   * on their own `app` capability for their own tables, with the same types.
+   */
+  purge?: readonly PurgeContribution[];
   /**
    * The role powers this capability's own routes gate on, through the acting-organization seam —
    * `media:manage`, `storage:manage`. Omit it when a capability asks no power, which is the normal case.
@@ -700,6 +712,9 @@ export function defineCapability<
   for (const spec of Object.values(input.databases ?? {})) {
     if (spec.migrations && spec.retained) declareRetained(spec.migrations, spec.retained);
   }
+  // A purge contribution no purge could run — a subject the kit does not know, or two for one — is refused
+  // where it is written, naming the capability, rather than on the day somebody is erased.
+  if (input.purge) assertPurgeContributions(input.name, input.purge);
   return {
     ...input,
     requiredBindings: input.requiredBindings.map((binding) => BindingSpec.parse(binding)),

package/src/capability/purge.ts

@@ -0,0 +1,124 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { ValidationError } from "../error/pithyError";
+
+/**
+ * How a capability says what erasing one subject means for its own rows — the purge contribution.
+ *
+ * ## Why a contribution, and not a cascade
+ *
+ * A hard delete has to reach rows that `@pithy-sh/media`, `@pithy-sh/support`, `@pithy-sh/testers` and the
+ * adopter's own tables hold, and no foreign key reaches across capabilities: each owns its tables, and none
+ * references another's. So the only party that knows how one person's rows are erased — deleted outright,
+ * or anonymized because a ledger must still add up — is the capability that owns them. It says so here,
+ * the way it states its migrations and its seeds, and the purge runs what was composed.
+ *
+ * ## One capability, one step
+ *
+ * The purge Workflow (#622) runs every composed contribution as **its own step**, named for the
+ * capability. A step that fails retries alone, and the ones that finished are not re-run — which is why a
+ * capability may declare at most one contribution per subject, and why every `erase` must be idempotent:
+ * a step is retried after a failure that may have come after its rows were already gone, and erasing
+ * nothing must then succeed.
+ *
+ * ## An adopter declares one too
+ *
+ * On their own `app` capability, for their own tables, with the same types. The contract is exported for
+ * exactly that, and nothing distinguishes a kit contribution from theirs.
+ */
+
+/**
+ * The kinds of subject a purge erases. Closed, so a typo is refused where it is written rather than becoming
+ * a contribution no purge ever asks for. `organization` joins when organization state does (#623).
+ */
+export const PurgeSubject = z
+  .enum(["user"])
+  .describe(
+    "The kind of subject a purge erases. `user` is one person's account in `@pithy-sh/auth`, identified by its user id.",
+  );
+export type PurgeSubject = z.output<typeof PurgeSubject>;
+
+/** What one step is handed: who is being erased, and this run's bindings. */
+export interface PurgeContext {
+  /** The subject being erased — its kind, and its id in that kind's own table. */
+  readonly subject: { readonly type: PurgeSubject; readonly id: string };
+  /** The Worker's bindings for this run, from which the contribution opens its own database. */
+  readonly env: Record<string, unknown>;
+}
+
+/** One capability's answer to "how are this subject's rows erased". */
+export interface PurgeContribution {
+  /** The kind of subject this erases. */
+  readonly subject: PurgeSubject;
+  /**
+   * One sentence on what is erased or anonymized — `Deletes the user's uploads and their stored bytes.`
+   * Recorded with the step that ran it, so the trail says what a purge did and not only that it ran.
+   */
+  readonly summary: string;
+  /**
+   * Erase or anonymize this subject's rows. **Idempotent**: run again after it succeeded, or after a failure
+   * that came once the rows were gone, it must succeed having found nothing to do. Throwing fails this step
+   * and only this step.
+   */
+  readonly erase: (context: PurgeContext) => Promise<void>;
+}
+
+/** One step of a purge: which capability it runs, and the contribution that capability declared. */
+export interface PurgeStep {
+  /** The step's name — the capability's, so a retried step names who failed. */
+  readonly step: string;
+  /** The contribution this step runs. */
+  readonly contribution: PurgeContribution;
+}
+
+/**
+ * Refuse a capability's purge contributions that no purge could run as declared: an unknown subject, two for
+ * one subject, or one with nothing to record. Called by `defineCapability`, so the refusal names the capability
+ * where it is written rather than surfacing in a Workflow on the day somebody is deleted.
+ */
+export function assertPurgeContributions(capability: string, contributions: readonly PurgeContribution[]): void {
+  const seen = new Set<string>();
+  for (const contribution of contributions) {
+    const subject = PurgeSubject.safeParse(contribution.subject);
+    if (!subject.success) {
+      throw new ValidationError({
+        message: `The ${capability} capability declares a purge for "${String(contribution.subject)}", which is not a subject a purge erases.`,
+        action: `Declare it for one of: ${PurgeSubject.options.join(", ")}.`,
+      });
+    }
+    if (seen.has(subject.data)) {
+      throw new ValidationError({
+        message: `The ${capability} capability declares two purge contributions for ${subject.data}.`,
+        action: "Fold them into one: each capability is one step of the purge, and a retried step re-runs all of it.",
+      });
+    }
+    seen.add(subject.data);
+    if (contribution.summary.trim() === "") {
+      throw new ValidationError({
+        message: `The ${capability} capability's ${subject.data} purge has no summary.`,
+        action: "Say in one sentence what it erases. The purge records it with the step.",
+      });
+    }
+    if (typeof contribution.erase !== "function") {
+      throw new ValidationError({
+        message: `The ${capability} capability's ${subject.data} purge has no erase function.`,
+        action: "Give it an `erase` that removes or anonymizes the subject's rows.",
+      });
+    }
+  }
+}
+
+/** The steps a purge of `subject` runs, in composition order — libraries first, the adopter's `app` last. */
+export function purgeSteps(
+  capabilities: readonly { readonly name: string; readonly purge?: readonly PurgeContribution[] }[],
+  subject: PurgeSubject,
+): PurgeStep[] {
+  const steps: PurgeStep[] = [];
+  for (const capability of capabilities) {
+    const contribution = capability.purge?.find((candidate) => candidate.subject === subject);
+    if (contribution) steps.push({ step: capability.name, contribution });
+  }
+  return steps;
+}

package/src/cli/commandCatalog.generated.ts

@@ -899,6 +899,10 @@ export const COMMANDS = {
           "invite",
           "testerNudge",
           "passwordChanged",
+          "accountSuspended",
+          "accountReinstated",
+          "deletionScheduled",
+          "deletionComplete",
           "operationalNotice",
           "newsletter",
           "leadCapture",
@@ -1230,6 +1234,33 @@ export const COMMANDS = {
     },
     "groups": []
   },
+  "privacy enable": {
+    "positionals": [],
+    "flags": {
+      "--class": {
+        "type": "string",
+        "required": false,
+        "repeatable": true
+      },
+      "--json": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      }
+    },
+    "groups": []
+  },
+  "privacy scan": {
+    "positionals": [],
+    "flags": {
+      "--json": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      }
+    },
+    "groups": []
+  },
   "provision": {
     "positionals": [],
     "flags": {
@@ -1433,6 +1464,33 @@ export const COMMANDS = {
     },
     "groups": []
   },
+  "secrets retire-version": {
+    "positionals": [
+      {
+        "name": "version",
+        "required": true,
+        "variadic": false
+      }
+    ],
+    "flags": {
+      "--env": {
+        "type": "string",
+        "required": false,
+        "repeatable": false
+      },
+      "--past-guard": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      },
+      "--json": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      }
+    },
+    "groups": []
+  },
   "secrets rm": {
     "positionals": [
       {
@@ -2711,6 +2769,7 @@ export const GROUPS = [
   "feature",
   "media",
   "payments",
+  "privacy",
   "secrets",
   "storage",
   "support",

package/src/cli/commandFacts.ts

@@ -105,6 +105,7 @@ export const DESTRUCTIVE_COMMANDS = {
   "media deprovision": "the media Worker, and with --storage its bucket",
   remove: "a capability's wiring",
   "secrets deprovision": "the secrets manager, and with --keys the store's keys",
+  "secrets retire-version": "a field-key version, and every ciphertext still sealed under it",
   "secrets rm": "a stored secret",
   "storage deprovision": "the storage Worker, and with --storage its bucket",
   "support deprovision": "the support Workers, and with --storage its attachments",

package/src/controlPlane/capability.ts

@@ -7,6 +7,8 @@ import type { BindingSpecInput } from "../capability/bindings";
 import { type Capability, defineCapability, type PithyHonoEnv } from "../capability/capability";
 import type { DatabaseSpecMap } from "../data/databases";
 import type { KvNamespaceSpecMap, KvRegistry } from "../kv/namespaces";
+import { readRetirement } from "../privacy/fieldRotation";
+import { lazyPrivacyInventory } from "../privacy/inventory";
 import { PACKAGE_NAME, PACKAGE_VERSION } from "../version.generated";
 import { ENVIRONMENT_VAR } from "../worker/identity";
 import { ControlPlaneConfig, type ControlPlaneConfigInput } from "./config/config";
@@ -146,6 +148,12 @@ export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCap
   // Worker's sets and this Worker holds only its own, so `pending` and `undeclared` can differ there.
   let migrationDatabases: readonly ComposedMigrationDatabase[] = [];
 
+  // Every capability this Worker composed, kept so the privacy inventory can walk their storage schemas
+  // (#132) — lazily, on the first control-plane read, and once for the isolate. Capturing the list costs
+  // nothing; walking it is deferred, so a Worker whose control plane is never called never walks.
+  let composedCapabilities: readonly Capability[] = [];
+  const privacy = lazyPrivacyInventory(() => composedCapabilities);
+
   const capability = defineCapability({
     name: "controlplane",
     // `@pithy-sh/core`'s version, stamped by `scripts/stampVersions.ts` — a Worker cannot read its own
@@ -209,6 +217,7 @@ export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCap
       }));
       health = capabilityHealthSources(capabilities);
       migrationDatabases = composeMigrationDatabases(capabilities);
+      composedCapabilities = [...capabilities];
     },
     middleware: [
       (app) => {
@@ -252,6 +261,8 @@ export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCap
         composedCapabilities: () => composed,
         composedHealth: () => health,
         composedMigrations: () => migrationDatabases,
+        privacyInventory: privacy,
+        retirement: (env) => readRetirement(env, composedCapabilities),
         now,
       });
     },

package/src/controlPlane/discovery/adminRoute.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import { z } from "zod";
+import { PrivacyPosture } from "../../privacy/posture";
 import { ControlPlaneScope } from "../scope/scope";
 import { ManifestConfigKey, ManifestConfigValues } from "./configuration";
 import { CapabilityHealthReport, HealthSummary, HealthSummaryKey, healthReport, healthWire } from "./healthSummary";
@@ -246,6 +247,16 @@ export const ControlPlaneManifest = z
       .describe(
         "The Cloudflare version id of the build answering this call, from the `CF_VERSION_METADATA` binding, or null where the binding is absent. Opaque and per-deploy: it identifies which build is running, never which features it has. Null is honest — a Worker scaffolded before the binding was declared genuinely cannot say.",
       ),
+    versionCreatedAt: z.iso
+      .datetime()
+      .nullable()
+      .optional()
+      .describe(
+        "When the version answering this call was uploaded, ISO-8601, from the same `CF_VERSION_METADATA` binding as `version` — or null where the binding is absent. The id alone cannot tell a deploy from a rollback: a rollback reactivates an existing version, so the id returns to one already seen while this moves backwards. Relayed, never interpreted. Absent from a Worker older than #132.",
+      ),
+    privacy: PrivacyPosture.optional().describe(
+      "What this project declares about privacy and what its running code holds: classes and counts, never field names (`GET /control-plane/privacy` has those, behind `privacy:read`). Present on every Worker from #132, `declared` explicitly empty when nothing was declared; absent from an older Worker.",
+    ),
     capabilities: z
       .array(CapabilityDescriptor)
       .describe(

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/handlers.ts

@@ -4,7 +4,10 @@
 import type { Context } from "hono";
 import type { PithyHonoEnv } from "../../capability/capability";
 import { causeMessage } from "../../error/cause";
-import { workerVersion } from "../../worker/identity";
+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";
@@ -20,6 +23,7 @@ import type {
   ControlPlaneKeysResponse,
   ControlPlaneMigrationsResponse,
   ControlPlanePingResponse,
+  ControlPlanePrivacyResponse,
   ExpireKeyResponse,
   PublicKeyView,
   RegisterKeyResponse,
@@ -76,6 +80,16 @@ export interface ControlPlaneHandlerDeps {
    * `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;
 }
@@ -199,12 +213,23 @@ 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);
@@ -385,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/responses.ts

@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: MIT
 
 import { z } from "zod";
+import { PrivacyPosture } from "../../privacy/posture";
+import { PRIVACY_SOURCES } from "../../privacy/report";
 import { ConnectionPrincipal, ConnectionPurpose, ControlPlaneActorKind, Ed25519PublicJwk } from "../data/connection";
 
 /**
@@ -228,3 +230,101 @@ export const ControlPlaneMigrationsResponse = z
   })
   .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,7 +6,13 @@ 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, MIGRATIONS_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,
@@ -15,12 +21,14 @@ import {
   manifestHandler,
   migrationsHandler,
   pingHandler,
+  privacyHandler,
   registerKeyHandler,
 } from "./handlers";
 import {
   ControlPlaneKeysResponse,
   ControlPlaneMigrationsResponse,
   ControlPlanePingResponse,
+  ControlPlanePrivacyResponse,
   ExpireKeyResponse,
   RegisterKeyResponse,
 } from "./responses";
@@ -35,6 +43,7 @@ import { ExpireKeyParams, ExpireKeyRequest, RegisterKeyRequest } from "./schemas
  *   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.
@@ -100,6 +109,13 @@ export function controlPlaneRouteDescriptors(basePath: string): AdminRoute[] {
       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.",
+    },
   ];
 }
 
@@ -184,4 +200,18 @@ export function registerControlPlaneRoutes(
     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),
+  );
 }