@pithy-sh/core 0.11.0 → 0.13.0

package/package.json

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

package/src/audit/composed.ts

@@ -0,0 +1,30 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Capability } from "../capability/capability";
+import { type AuditEmit, noopEmit } from "./recorder";
+
+/**
+ * The audit recorder for code with no request — a Workflow step (#622).
+ *
+ * A route records through `c.var.emit`. A Workflow has no `c`: the runtime constructs it with `env` and nothing
+ * else. So it finds the composed capability that declares {@link Capability.auditRecorder} — `@pithy-sh/audit`
+ * — and records through that, built over this run's env. With none composed it is {@link noopEmit}, exactly as
+ * `c.var.emit` is in a Worker that composes no audit, so a step can always record without asking first.
+ *
+ * **Non-fatal, whatever the recorder does.** The contract says a recorder never throws; this holds a recorder
+ * to it rather than trusting it, because what a step records has already happened and a throw here would turn
+ * it into a retried step.
+ */
+export function composedAuditEmit(capabilities: readonly Capability[], env: Record<string, unknown>): AuditEmit {
+  const provider = capabilities.find((capability) => capability.auditRecorder !== undefined);
+  if (!provider?.auditRecorder) return noopEmit;
+  const record = provider.auditRecorder(env);
+  return async (event) => {
+    try {
+      await record(event);
+    } catch {
+      // The recorder broke its own contract. The event is lost, and the step it recorded stands.
+    }
+  };
+}

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. */
@@ -632,6 +633,17 @@ export interface Capability<
    * capability that declares one (e.g. `@pithy-sh/email`'s bounce/complaint handler).
    */
   email?: CapabilityEmailHandler;
+  /**
+   * The audit recorder this capability provides **for code that has no request** — a Workflow step, which the
+   * runtime constructs with `env` and nothing else (#622). `@pithy-sh/audit` declares it; nothing else does.
+   *
+   * A route records through `c.var.emit`, which the same capability's middleware fills, and keeps doing that.
+   * This is the other door, for the purge that erases a deleted account: it runs in a Workflow and still owes
+   * the trail its event. `../audit/composed.ts` finds it among the composed capabilities, so a capability that
+   * audits from a step imports no audit package — principle 4, the same reason `c.var.emit` is a seam. Built
+   * from the env per call, like the request recorder is built per request. Non-fatal by the same contract.
+   */
+  auditRecorder?: (env: Record<string, unknown>) => AuditEmit;
   /**
    * Named D1 databases this capability contributes tables to (database name → {@link DatabaseSpec}).
    * `createBackend` merges every capability's slices per database (via `composeDatabases`) and serves
@@ -658,6 +670,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 +723,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,187 @@
+// 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.
+ *
+ * ## The same contribution answers an export (#622)
+ *
+ * An access request arrives before an erasure, not after. So a contribution may also say what this capability
+ * holds about the subject, on the read side: `export` answers one JSON object, and the control plane's export
+ * route assembles one document from every composed contribution, in the same order the purge runs them. A
+ * contribution with no `export` is listed as holding rows it did not say how to export, which is the honest
+ * answer and the one an operator can act on.
+ *
+ * ## 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` joined with organization state (#623): a capability
+ * holding rows scoped to a tenant declares one for it, and the organization purge runs it.
+ */
+export const PurgeSubject = z
+  .enum(["user", "organization"])
+  .describe(
+    "The kind of subject a purge erases. `user` is one person's account in `@pithy-sh/auth`, identified by its user id. `organization` is one tenant in `@pithy-sh/organization`, identified by its organization 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>;
+  /**
+   * What this capability holds about the subject, as one JSON object — the read side of `erase` (#622). It
+   * answers an access request, so it carries the subject's own data and never a credential: no session token,
+   * no provider token, no push token. Optional: a contribution without one is listed in the export as rows it
+   * erases and did not say how to export. A throw costs this capability's entry, never the document.
+   */
+  readonly export?: (context: PurgeContext) => Promise<Record<string, unknown>>;
+}
+
+/** 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 (contribution.export !== undefined && typeof contribution.export !== "function") {
+      throw new ValidationError({
+        message: `The ${capability} capability's ${subject.data} purge has an export that is not a function.`,
+        action: "Give it an `export` that answers what this capability holds about the subject, or leave it out.",
+      });
+    }
+    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;
+}
+
+/** What one step's export answered: its data, that it declared none, or that it could not be read. */
+export type PurgeExportEntry =
+  | {
+      readonly capability: string;
+      readonly summary: string;
+      readonly state: "exported";
+      readonly data: Record<string, unknown>;
+    }
+  | { readonly capability: string; readonly summary: string; readonly state: "not_exported" }
+  | { readonly capability: string; readonly summary: string; readonly state: "unavailable" };
+
+/** Whether an export answered what the contract promises: one plain object. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Read every step's export for one subject — the export document's body, in step order (#622).
+ *
+ * **Each read is guarded on its own and they run concurrently**, the shape the user pane's sub-reads have
+ * (#380): one capability whose table will not read costs its own entry as `unavailable`, and the rest of the
+ * document still answers the request. What the read threw is not carried — it names a query and a table, and
+ * the document crosses a trust boundary. An answer that is not one object is `unavailable` too, because the
+ * document promises an object per capability and a client validates it.
+ */
+export async function purgeExports(steps: readonly PurgeStep[], context: PurgeContext): Promise<PurgeExportEntry[]> {
+  return Promise.all(
+    steps.map(async ({ step, contribution }): Promise<PurgeExportEntry> => {
+      const base = { capability: step, summary: contribution.summary };
+      const read = contribution.export;
+      if (read === undefined) return { ...base, state: "not_exported" };
+      try {
+        const data = await read(context);
+        return isRecord(data) ? { ...base, state: "exported", data } : { ...base, state: "unavailable" };
+      } catch {
+        return { ...base, state: "unavailable" };
+      }
+    }),
+  );
+}

package/src/cli/commandCatalog.generated.ts

@@ -899,6 +899,16 @@ export const COMMANDS = {
           "invite",
           "testerNudge",
           "passwordChanged",
+          "accountSuspended",
+          "accountReinstated",
+          "deletionScheduled",
+          "deletionComplete",
+          "organizationMemberAdded",
+          "organizationMemberRemoved",
+          "organizationOwnershipTransferred",
+          "organizationSuspended",
+          "organizationReinstated",
+          "organizationDeletionScheduled",
           "operationalNotice",
           "newsletter",
           "leadCapture",
@@ -1230,6 +1240,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 +1470,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 +2775,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/guard.ts

@@ -186,7 +186,21 @@ export function requireControlPlane(requirement: ControlPlaneRequirement): Middl
       },
       c.var.log,
     );
-    await next();
+    // A handler can refuse a call the gate's requirement let through — an operator roster write that
+    // would move the owning role is refused `controlplane/insufficient_scope`, naming the ownership route,
+    // even on a connection granted `organization:ownership:transfer`, because a token exercises the one
+    // scope it was minted for — and it refuses it itself, past this gate. That refusal is still a blocked attempt, and the trail must
+    // say so: `call_allowed` alone would hide a credential probing for the grant it lacks.
+    //
+    // Both paths, as the organization routes' refusal recorder reads them: a throw that reaches here, and
+    // `c.error`, which is where Hono's `compose` leaves a downstream throw it rendered through `onError`.
+    try {
+      await next();
+    } catch (error) {
+      await auditHandlerDenial(c, requirement, context, error);
+      throw error;
+    }
+    await auditHandlerDenial(c, requirement, context, c.error);
   };
   (guard as unknown as Record<symbol, unknown>)[CONTROL_PLANE_GUARD] = true;
   return guard;
@@ -245,6 +259,51 @@ async function auditDenial(
   );
 }
 
+/**
+ * Record a scope refusal a handler raised after the gate let the call in.
+ *
+ * Only `controlplane/insufficient_scope`: every other refusal past the gate is the handler's own to
+ * record, and a 404 or a validation error is not a credential reaching beyond its grant. The same row as
+ * {@link auditDenial}, with two differences that follow from the call having been verified: the actor is
+ * the proven subject and its connection, and `refusedBy` says the gate passed it — `required` is the
+ * gate's requirement, which this call met; what it lacked is in the log, with the rest of `detail`.
+ */
+async function auditHandlerDenial(
+  c: Parameters<MiddlewareHandler<PithyHonoEnv>>[0],
+  requirement: ControlPlaneRequirement,
+  context: ControlPlaneContext,
+  cause: unknown,
+): Promise<void> {
+  // Read by its code, not `instanceof`: a capability that throws it may hold its own copy of this module,
+  // and a refusal that slipped past a class check would be exactly the unaudited attempt this exists for.
+  const code = (cause as { payload?: { code?: unknown } } | null)?.payload?.code;
+  if (code !== "controlplane/insufficient_scope") return;
+  await safeEmit(
+    c.var.emit,
+    {
+      action: ControlPlaneAuditActions.callDenied,
+      outcome: "denied",
+      severity: "warning",
+      actorType: "control-plane",
+      actorId: context.subject,
+      resourceType: "controlplane_connection",
+      resourceId: context.connectionId,
+      requestId: c.req.header("cf-ray"),
+      ip: c.req.header("cf-connecting-ip"),
+      userAgent: c.req.header("user-agent"),
+      metadata: {
+        reason: code,
+        required: String(requirement),
+        refusedBy: "handler",
+        connectionId: context.connectionId,
+        method: c.req.method,
+        path: c.req.path,
+      },
+    },
+    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).

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