@pithy-sh/core 0.13.0 → 0.14.0

package/src/capability/bindings.ts

@@ -229,6 +229,45 @@ const TARGET = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
  */
 const NAMED_RESOURCE_KINDS = new Set<string>(FEATURE_RESOURCE_KINDS);
 
+/**
+ * **How a Worker consumes a queue it also produces to (#824).**
+ *
+ * A consumer is half of the queue's own configuration — Cloudflare reads it off the `queues.consumers` entry, not
+ * off the code — so it is declared beside the producer binding and written with it, by the same writer. The
+ * dead-letter queue is named by **binding**, never by queue name: the name is `<project>-<env>-<thing>`, composed
+ * per environment by the same namer that names the producer's, so a spec that stated it would be one environment's.
+ *
+ * `maxRetries` is bounded by what Cloudflare Queues accepts (0 to 100), and the capability's handler reads the same
+ * number to know a message's last attempt, which is the moment it can count one as dead-lettered.
+ */
+export const QueueConsumerSpec = z
+  .object({
+    deadLetter: z
+      .string()
+      .min(1)
+      // A binding name, and narrowed to one: a manifest is third-party data, and this string is composed into the
+      // dead-letter queue's name in the adopter's `wrangler.jsonc`.
+      .regex(/^[A-Za-z_][A-Za-z0-9_]*$/, "A dead-letter queue is named by its binding: letters, digits and `_`.")
+      .describe(
+        "The binding of the queue a message goes to once its retries are spent. Declared as a `queue` binding of its own, so `pithy provision` creates it; its queue name is composed the same way as this one's.",
+      ),
+    maxRetries: z
+      .number()
+      .int()
+      .min(0)
+      .max(100)
+      .describe("How many times a failed message is retried before it is dead-lettered. Cloudflare allows 0 to 100."),
+    maxBatchSize: z
+      .number()
+      .int()
+      .min(1)
+      .max(100)
+      .optional()
+      .describe("The most messages one invocation of the handler receives. Absent leaves Cloudflare's default."),
+  })
+  .describe("How a Worker consumes a queue it produces to: where exhausted messages go, and how often one is retried.");
+export type QueueConsumerSpec = z.infer<typeof QueueConsumerSpec>;
+
 /**
  * Declares a Cloudflare binding a capability requires in the Worker env. The authoring
  * shape lets `optional` be omitted (defaults false); `createBackend` normalizes via parse.
@@ -308,6 +347,9 @@ export const BindingSpec = z
       .describe(
         "The `<thing>` segment of this resource's name, when it is not the kebabbed binding name. Absent is the ordinary case and means the binding name is the segment (`EMAIL_SUPPRESSIONS` → `email-suppressions`). Declare it where the two must differ: `SUPPORT_BUCKET` backs `<project>-global-support`, because the binding keeps `_BUCKET` for whoever reads `env.SUPPORT_BUCKET` in a Worker while the resource drops it — `r2` is already the composed name's kind, so the suffix repeats it. Meaningful only for a `d1`, `kv`, `r2` or `queue` binding.",
       ),
+    consumer: QueueConsumerSpec.optional().describe(
+      "That this Worker also **consumes** the queue it produces to, and how: the queue its exhausted messages go to and how many times one is retried first. Written as the `queues.consumers` entry beside the producer, so the queue's handler is the Worker's own `queue` export (`Capability.queue`). Absent, the Worker only sends. Meaningful only for a `queue` binding.",
+    ),
   })
   .describe("Declares a Cloudflare binding a capability requires in the Worker env.")
   .check((ctx) => {
@@ -376,6 +418,25 @@ export const BindingSpec = z
         message: `Binding "${ctx.value.name}" needs a target — the ${ctx.value.type} resource it addresses, written as \`${target.field}\`.`,
       });
     }
+    // A consumer is the queue's configuration, so on any other kind it describes nothing a writer emits.
+    const consumer = ctx.value.consumer;
+    if (consumer !== undefined && ctx.value.type !== "queue") {
+      ctx.issues.push({
+        code: "custom",
+        input: ctx.value,
+        path: ["consumer"],
+        message: `Binding "${ctx.value.name}" declares a consumer, which only a queue binding has — this one is a ${ctx.value.type}.`,
+      });
+    }
+    // Dead-lettering into the queue a message just failed out of is a retry loop with no end, so it is refused.
+    if (consumer !== undefined && consumer.deadLetter === ctx.value.name) {
+      ctx.issues.push({
+        code: "custom",
+        input: ctx.value,
+        path: ["consumer", "deadLetter"],
+        message: `Queue "${ctx.value.name}" names itself as its dead-letter queue. Declare a second queue binding for it.`,
+      });
+    }
     if (target === undefined && ctx.value.target !== undefined) {
       ctx.issues.push({
         code: "custom",

package/src/capability/capability.ts

@@ -5,9 +5,12 @@ import type { ExecutionContext, ForwardableEmailMessage } from "@cloudflare/work
 import type { Hono, MiddlewareHandler } from "hono";
 import type { z } from "zod";
 import type { ActingOrganizationResolver } from "../access/acting";
+import type { AuditCitationReader } from "../audit/citations";
 import type { AuditEmit } from "../audit/recorder";
+import { type ConsentPurpose, parseConsentPurposes } from "../consent/purpose";
+import type { ConsentGrantedListener, ConsentReader, ConsentWithdrawnListener } from "../consent/reader";
 import type { ControlPlaneContext } from "../controlPlane/context";
-import type { AdminRoute } from "../controlPlane/discovery/adminRoute";
+import type { AdminRouteDeclaration } from "../controlPlane/discovery/adminRoute";
 import type { CapabilityManifestConfig } from "../controlPlane/discovery/configuration";
 import type { CapabilityHealth } from "../controlPlane/discovery/health";
 import type { ControlPlaneVerifier } from "../controlPlane/http/guard";
@@ -22,12 +25,28 @@ import type { Translator } from "../i18n/translator";
 import type { KvNamespaceSpecMap } from "../kv/namespaces";
 import type { Logger } from "../logger/logger";
 import { declareRetained } from "../migrations/retainedDeclaration";
+import { presenceRoomsSocket } from "../presence/channel";
+import {
+  assertPresenceDeclaration,
+  PRESENCE_ROOMS_BINDING_SPEC,
+  type PresenceDeclaration,
+} from "../presence/declaration";
+import {
+  type ProcessingActivity,
+  type ProcessingActivityInput,
+  parseProcessingActivities,
+} from "../processing/activity";
+import type { CapabilityQueueHandler } from "../queue/consumer";
+import type { PurgeWindowDefault } from "../retention/policy";
 import type { SeedSet } from "../seed/seed";
+import type { SessionRotatedListener } from "../session/rotated";
 import type { WorkflowSpecMap } from "../workflow/spec";
 import { BindingSpec, type BindingSpecInput } from "./bindings";
 import type { ClientProjection, ClientProjectionContext } from "./client";
+import type { ErasureRecords } from "./erasure";
 import { assertPurgeContributions, type PurgeContribution } from "./purge";
 import type { CapabilitySettings } from "./settings";
+import { assertVectorIndexContributions, type VectorIndexContribution } from "./vectorIndex";
 
 /** Hono `Variables` every capability's routes are typed against. `createBackend` seeds these per request. */
 export interface PithyVars {
@@ -180,7 +199,7 @@ export interface SecretRegistryEntrySeam {
   readonly devValue?: string;
   /**
    * The Worker binding this value exists to reach, or absent when it reaches none — the constant half
-   * of *can this composition use this secret* (#541).
+   * of *can this composition use this secret*.
    *
    * Read here and never interpreted, exactly like {@link devValue}: the CLI joins it against a Worker's
    * `declinedBindings` so a credential whose bucket the project declined stops being listed as
@@ -206,7 +225,7 @@ export type SecretRegistrySeam = Record<string, SecretRegistryEntrySeam>;
  * **It is declared, not matched by name.** `PaymentsRailToggles.paddle` and
  * `PaymentsProviderCredentials.paddle` happen to be spelled the same today, and a CLI that keyed off
  * that would be right by coincidence: nothing makes a config flag and a schema key the same thing, and
- * two of them one line apart cannot be told apart by convention (#513). The capability already knows
+ * two of them one line apart cannot be told apart by convention. The capability already knows
  * the answer at construction — it has both halves in hand — so it states it, and the CLI reads a fact
  * instead of inferring one.
  *
@@ -228,8 +247,8 @@ export type SecretBranchSeam = Record<string, readonly string[]>;
  * The neighbor of {@link SecretBranchSeam}, one level up. That one says which *blocks* of a bundle
  * apply when the bundle itself does; this says that a whole secret does not. `@pithy-sh/auth` declares
  * one credential per OAuth provider, so a project running Google and GitHub has two secrets that no
- * code path will ever read — and until #541 `pithy doctor` listed both as outstanding work under
- * *"fine to leave until you need it"*, which is not true of a credential the configuration has refused.
+ * code path will ever read, and `pithy doctor` does not list them as outstanding work: the configuration
+ * has refused them.
  *
  * **Declared, never inferred**, for {@link SecretBranchSeam}'s reason: `auth-apple-credentials` and
  * `providers.apple` are spelled alike today and nothing makes a secret name and a config key the same
@@ -307,7 +326,7 @@ export interface CapabilityComposeContext {
  * message (an untouched message is dropped by the runtime).
  *
  * **`ForwardableEmailMessage` and `ExecutionContext` are imported rather than assumed ambient**, and
- * that is the whole of #315's second half. This module is reachable from a client: a browser program
+ * that is deliberate. This module is reachable from a client: a browser program
  * that names a control-plane scope through a capability's guards lands here, and a browser program
  * has no Workers globals. Read off the global scope, the two names resolved only for a consumer that
  * had `@cloudflare/workers-types` in its `types` — so an adopter's DOM program failed on two errors
@@ -400,7 +419,7 @@ export interface Capability<
    * The CF permissions this capability's **deployed Workers** call Cloudflare with, as short catalog keys
    * (`secrets:write`, `images:write`, `analytics:read`). The runtime counterpart of {@link ciPermissions}.
    *
-   * **A deployed application holds one Cloudflare API token, and this is the only way into it (#728).**
+   * **A deployed application holds one Cloudflare API token, and this is the only way into it.**
    * Every composed capability's keys union into the project-level `runtime` profile, minted per
    * environment into the Secrets Store and read by every Worker of that environment through one binding,
    * the way every capability's `ciPermissions` union into the one `ci-system` token. A capability cannot
@@ -427,10 +446,10 @@ export interface Capability<
    * the router that actually mounted; a stale declaration is worse than none, because a client
    * believes it.
    */
-  adminRoutes?: readonly AdminRoute[];
+  adminRoutes?: readonly AdminRouteDeclaration[];
   /**
    * The bounded health summary this capability contributes to its own manifest entry — a small, fixed
-   * set of scalars a management client can render beside a rail without a second round trip (#317).
+   * set of scalars a management client can render beside a rail without a second round trip.
    * Omit it when a capability has nothing to say, which is the normal case.
    *
    * **Declared alongside the routes, and only through `defineCapabilityHealth`.** The type is branded,
@@ -446,7 +465,7 @@ export interface Capability<
   health?: CapabilityHealth;
   /**
    * The configured facts this capability states into its own manifest entry — the decisions an adopter
-   * already made that a management client has to respect to call anything (#422). Omit it when nothing
+   * already made that a management client has to respect to call anything. Omit it when nothing
    * this capability is configured with changes how a client calls it, which is the normal case.
    *
    * **A third field, because the two obvious names are taken and neither is this.**
@@ -467,7 +486,7 @@ export interface Capability<
   manifestConfig?: CapabilityManifestConfig;
   /**
    * How this capability checks that its own **settings work**, as opposed to being merely present — the
-   * seam `pithy doctor` runs for every capability every Worker composes (#411). Omit it when a capability
+   * seam `pithy doctor` runs for every capability every Worker composes. Omit it when a capability
    * has nothing worth checking, which is the normal case and is silent rather than a fault.
    *
    * Declared here, on the instance, and **never keyed off `pithy.manifest.json`**: `@pithy-sh/matchmaking`
@@ -505,7 +524,7 @@ export interface Capability<
    * The npm **package** that supplies this capability, or `null` where there is none.
    *
    * The join key {@link Capability.version} is useless without. A version joins against a release feed
-   * by package name, and this manifest reported the version alone until #626 — so a client had to guess
+   * by package name, and without this a client has to guess
    * `@pithy-sh/${name}`, which is right for most capabilities and wrong for the one that matters:
    * `controlplane` ships inside `@pithy-sh/core`, so the guess reaches a package that has never been
    * published and the join comes back empty, which is indistinguishable from "up to date".
@@ -544,7 +563,7 @@ export interface Capability<
    * *load*, because the adopter's own toolchain has to keep working on the project while they fix it.
    * `@pithy-sh/payments` is the case it exists for: `pithy add` scaffolds an unimplemented
    * `resolveSubject`, every CLI command keeps loading that config, and the Worker refuses to boot until
-   * the adopter has written it (#500). A check that can be made at composition still belongs at
+   * the adopter has written it. A check that can be made at composition still belongs at
    * composition — earlier is better, and a refusal the CLI can raise is a refusal an adopter sees sooner.
    */
   boot?: (context: CapabilityComposeContext) => void;
@@ -556,6 +575,18 @@ export interface Capability<
    * parsed with. A capability with no socket leaves it unset.
    */
   sockets?: readonly SocketChannel[];
+  /**
+   * The presence room kinds this capability serves (`../presence/declaration.ts`): who else has one of its
+   * records open, live. Omit it when a capability has no record more than one person acts on, which is the
+   * normal case.
+   *
+   * **Declaring it is the whole of the wiring.** `defineCapability` adds the `PRESENCE_ROOMS` Durable Object
+   * binding and the room socket to this capability's {@link requiredBindings} and {@link sockets};
+   * `createBackend` mounts `{basePath}/presence/tickets` and `{basePath}/presence/rooms/:kind/:recordId`
+   * beside its routes; the control-plane seam answers `POST /control-plane/presence/tickets` for every kind
+   * and lists them in the manifest. Build it from the resolved config, like {@link adminRoutes}.
+   */
+  presence?: PresenceDeclaration;
   /**
    * Composable middleware (e.g. turnstile(), requireAuth()). Runs on every request, the control-plane
    * surface included. A refusal that protects a route — a rate limit, authentication, a CSRF check —
@@ -594,7 +625,7 @@ export interface Capability<
   /**
    * Whether this capability fills `AuthContext.scopes` — whether anything will ever put a string in the
    * array the scope gates read. `@pithy-sh/auth` declares it when an adopter supplies `resolveScopes`, and
-   * not otherwise (#560).
+   * not otherwise.
    *
    * The same reason {@link providesEntitlements} exists, one seam over. Every scope gate fails closed, so a
    * Worker composing `leaderboard` with no resolver is not broken: it refuses every caller on the gated
@@ -633,9 +664,16 @@ export interface Capability<
    * capability that declares one (e.g. `@pithy-sh/email`'s bounce/complaint handler).
    */
   email?: CapabilityEmailHandler;
+  /**
+   * Queue consumer. The entrypoint (`createEntrypoint`) exposes the Worker's one `queue` export when any
+   * capability declares one, and hands each the messages of a batch whose body names it — see
+   * `../queue/consumer.ts` for why the body, not the queue name, decides. The queue itself is declared as a
+   * `queue` binding with a `consumer`, which is what writes the `queues.consumers` entry that delivers here.
+   */
+  queue?: CapabilityQueueHandler;
   /**
    * 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.
+   * runtime constructs with `env` and nothing else. `@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
@@ -644,6 +682,59 @@ export interface Capability<
    * 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;
+  /**
+   * The trail's citation reader: which recorded events name a resource, and where each sits in its chain.
+   * `@pithy-sh/audit` declares it; nothing else does. The erasure attestation cites a purge's events through it,
+   * found among the composed capabilities by `../audit/citations.ts`, so the control plane imports no audit package.
+   */
+  auditCitations?: (env: Record<string, unknown>) => AuditCitationReader;
+  /**
+   * The purposes this capability processes under consent — `@pithy-sh/email` declares `email.marketing`
+   * and `email.tracking`. Omit it when nothing here needs consent, which is the ordinary case.
+   *
+   * **Only under this capability's own `name`**, as `<name>.<purpose>`: `defineCapability` refuses anything else,
+   * the rule tables and error codes follow. The consent capability composes every declaration into the catalog its
+   * `hasConsent` answers from, and `pithy doctor` names a composition that declares purposes and records no consent.
+   */
+  consentPurposes?: readonly ConsentPurpose[];
+  /**
+   * The processing activities this capability performs on personal data — `@pithy-sh/auth` declares `auth.account`.
+   * Each names a purpose, the data classes it uses and, where the capability can say, a default legal basis. Only
+   * under this capability's own `name`, as `<name>.<activity>`. `GET /control-plane/processing` derives the GDPR
+   * Article 30 record from them; see `../processing/activity.ts`. Build it from the resolved config, so a recipient
+   * that is switched off is not named.
+   */
+  processing?: readonly ProcessingActivity[];
+  /**
+   * The consent seam's provider: a reader built over this run's env. `@pithy-sh/consent` declares it;
+   * nothing else does. A capability asks it through `composedConsent` in `../consent/reader.ts`, never by
+   * importing the consent package.
+   */
+  consentReader?: (env: Record<string, unknown>) => ConsentReader;
+  /**
+   * Hear of a withdrawal from one of this capability's own purposes, to keep its own state in step — email
+   * suppresses an address for marketing when `email.marketing` is withdrawn. The consent capability calls
+   * it after the withdrawal is recorded, only for purposes under this capability's name.
+   */
+  consentWithdrawn?: ConsentWithdrawnListener;
+  /**
+   * Hear of a grant to one of this capability's own purposes once it stands — the other half of
+   * {@link Capability.consentWithdrawn}. Email lifts the marketing suppression a withdrawal wrote when
+   * `email.marketing` is granted again, so the suppression list and the record never disagree either way.
+   */
+  consentGranted?: ConsentGrantedListener;
+  /**
+   * Hear of a session replaced by its successor, to carry state keyed on the old session id to the new one —
+   * `@pithy-sh/organization` moves the acting selection. The capability that owns sessions announces it through
+   * `announceSessionRotated` in `../session/rotated.ts`, so neither side imports the other.
+   */
+  sessionRotated?: SessionRotatedListener;
+  /**
+   * An account's email address, by user id, or `null` when it has none — the capability that owns accounts
+   * declares it (`@pithy-sh/auth`), so a capability holding state by address finds one without importing auth.
+   * Read on demand, never carried.
+   */
+  addressOf?: (env: Record<string, unknown>, userId: string) => Promise<string | null>;
   /**
    * Named D1 databases this capability contributes tables to (database name → {@link DatabaseSpec}).
    * `createBackend` merges every capability's slices per database (via `composeDatabases`) and serves
@@ -681,6 +772,24 @@ export interface Capability<
    * on their own `app` capability for their own tables, with the same types.
    */
   purge?: readonly PurgeContribution[];
+  /**
+   * How this capability's record of a purge is read back — declared by the capability that owns a purge
+   * subject and runs its purge: `@pithy-sh/auth` for a user, `@pithy-sh/organization` for an organization. The
+   * control plane's erasure attestation reads it. See `./erasure.ts`.
+   */
+  erasureRecords?: ErasureRecords;
+  /**
+   * This capability's own soft-delete window — declared by the capability that owns a deletion, from its
+   * own `retention.purgeAfterDays`. A Worker's `retention` block may replace it; `GET /control-plane/manifest`
+   * and `pithy doctor` report which window takes effect and where it came from. See `../retention/policy.ts`.
+   */
+  purgeWindow?: PurgeWindowDefault;
+  /**
+   * The audit actions that record this capability's lifecycle transitions beyond its erasure — a suspension, a
+   * reinstatement, a restore. The retention floor covers each, beside the actions `erasureRecords` names, so an
+   * operator lifting a suspension is kept as long as the deletion it reversed. See `../retention/policy.ts`.
+   */
+  lifecycleAuditActions?: readonly string[];
   /**
    * 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.
@@ -692,6 +801,12 @@ export interface Capability<
    * importing any of them.
    */
   powers?: readonly string[];
+  /**
+   * The Vectorize indexes this capability owns and re-embeds in a Workflow of its own — see `./vectorIndex.ts`.
+   * `pithy vector reprocess` reads them beside `vector()`'s own indexes, so one command re-embeds every
+   * index in the project. Omit it when a capability owns no index, which is the ordinary case.
+   */
+  vectorIndexes?: readonly VectorIndexContribution[];
   /** Bindings this capability needs in the env (normalized — `optional` is always set). */
   requiredBindings: BindingSpec[];
 }
@@ -702,8 +817,9 @@ export type CapabilityInput<
   Namespaces extends KvNamespaceSpecMap = Record<never, never>,
   Name extends string = string,
   Workflows extends WorkflowSpecMap = Record<never, never>,
-> = Omit<Capability<Databases, Namespaces, Name, Workflows>, "requiredBindings"> & {
+> = Omit<Capability<Databases, Namespaces, Name, Workflows>, "requiredBindings" | "processing"> & {
   requiredBindings: BindingSpecInput[];
+  processing?: readonly ProcessingActivityInput[];
 };
 
 /**
@@ -719,16 +835,37 @@ export function defineCapability<
   const Workflows extends WorkflowSpecMap = Record<never, never>,
 >(input: CapabilityInput<Databases, Namespaces, Name, Workflows>): Capability<Databases, Namespaces, Name, Workflows> {
   // A retained table is declared on the `down`s that could drop it the moment the capability exists, so a
-  // migration the runner is handed carries it however its provider was built (#588).
+  // migration the runner is handed carries it however its provider was built.
   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);
+  // An index no reprocess could re-embed is refused the same way, naming the capability.
+  if (input.vectorIndexes) {
+    assertVectorIndexContributions(input.name, input.vectorIndexes, Object.keys(input.workflows ?? {}));
+  }
+  // A consent purpose outside the capability's own domain, or declared twice, is refused where it is written.
+  const consentPurposes = input.consentPurposes
+    ? parseConsentPurposes(input.name, input.consentPurposes, input.name)
+    : undefined;
+  const processing = input.processing ? parseProcessingActivities(input.name, input.processing, input.name) : undefined;
+  // A capability that declares room kinds needs the room's binding and serves the room's socket, so both are
+  // added here, once, rather than spelled by every capability that declares one and drifting from it.
+  const presence = input.presence && input.presence.rooms.length > 0 ? input.presence : undefined;
+  if (presence) assertPresenceDeclaration(input.name, presence, input.adminRoutes ?? []);
+  const requiredBindings =
+    presence && !input.requiredBindings.some((binding) => binding.name === PRESENCE_ROOMS_BINDING_SPEC.name)
+      ? [...input.requiredBindings, PRESENCE_ROOMS_BINDING_SPEC]
+      : input.requiredBindings;
+  const { processing: _declared, ...declared } = input;
   return {
-    ...input,
-    requiredBindings: input.requiredBindings.map((binding) => BindingSpec.parse(binding)),
+    ...declared,
+    ...(consentPurposes ? { consentPurposes } : {}),
+    ...(processing ? { processing } : {}),
+    ...(presence ? { sockets: [...(input.sockets ?? []), presenceRoomsSocket(input.name, presence)] } : {}),
+    requiredBindings: requiredBindings.map((binding) => BindingSpec.parse(binding)),
   };
 }
 

package/src/capability/erasure.ts

@@ -0,0 +1,82 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PurgeSubject } from "./purge";
+
+/**
+ * **The erasure record (#823): what a capability that runs a purge kept about it, read back.**
+ *
+ * A purge (#620, #623) records its progress in the lifecycle table of the capability that owns the subject:
+ * `pithy_auth_user_lifecycle` for a user, `pithy_organization_lifecycle` for an organization. Each holds the
+ * deletion, one row per step (erased, or retained with its basis under #814), a failure when the purge gave up, and
+ * the `purged` row at the end, keyed by the subject's id and nothing else.
+ *
+ * The control plane's erasure attestation assembles those rows into a record an auditor can be handed. It cannot
+ * import auth or organization (principle 4), so the capability that owns a subject declares how its rows are read,
+ * here, and which audit actions its purge records — so the attestation can cite them in the chain (#822).
+ *
+ * **Nothing about the person crosses this seam** beyond the id the trail already keeps: no address, no name.
+ */
+
+/** What happened, as the lifecycle tables name it. Only the rows an erasure is made of. */
+export type ErasureHistoryAction = "deleted" | "restored" | "purge_step" | "purge_retained" | "purge_failed" | "purged";
+
+/** How a deletion was asked for: with a window (`soft`) or none (`hard`). */
+export type ErasureDeletionMode = "soft" | "hard";
+
+/** One row of a subject's lifecycle, as the attestation reads it. Oldest first, in the order it was written. */
+export interface ErasureHistoryRow {
+  /** The subject's id. */
+  readonly subjectId: string;
+  /** What happened. */
+  readonly action: ErasureHistoryAction;
+  /** Who did it: `control-plane`, `user` or `system`. */
+  readonly actorType: string;
+  /** Why, in whoever acted's words. A step's summary, a retained step's basis. Null when nobody had to say. */
+  readonly reason: string | null;
+  /** The purge step a step, retained or failed row names — the capability, or the purge's own step. */
+  readonly step: string | null;
+  /** On a `deleted` row written since #823, how the deletion was asked for. Null before. */
+  readonly mode: ErasureDeletionMode | null;
+  /** On a `deleted` row written since #823, when its purge comes due. Null before. */
+  readonly purgeAfter: Date | null;
+  /** When it happened. */
+  readonly at: Date;
+}
+
+/** The audit actions one subject's purge records, so the attestation cites them. */
+export interface ErasureAuditActions {
+  /** Every action a deletion of the subject is recorded under — soft, hard, by its owner. */
+  readonly deleted: readonly string[];
+  /** One purge step: erased or retained, its `metadata.step` naming which. */
+  readonly step: string;
+  /** The purge giving up, its `metadata.step` naming where. */
+  readonly failed: string;
+  /** The purge finishing. */
+  readonly purged: string;
+}
+
+/** Reading one kind of subject's erasure rows, over one env. */
+export interface ErasureHistoryReader {
+  /** Every erasure row for these subjects, oldest first. A subject with none is absent. */
+  history(subjectIds: readonly string[]): Promise<ErasureHistoryRow[]>;
+  /**
+   * Every subject with a purge in the window: a step, a failure or a completion written in it, a deletion whose
+   * purge came due in it, or one still outstanding in it — due by its end (or recorded before a due instant was) and
+   * neither purged nor restored before it opened. The last is the purge that came due earlier and has written nothing
+   * since, which is the one a period read exists to name. Inclusive at both ends.
+   */
+  subjectsIn(since: Date, until: Date): Promise<string[]>;
+}
+
+/** What a capability that owns a purge subject declares: which subject, its trail, and how its rows are read. */
+export interface ErasureRecords {
+  /** The subject this capability's purge erases. One capability per subject. */
+  readonly subject: PurgeSubject;
+  /** The `resourceType` its audit events are recorded against. */
+  readonly resourceType: string;
+  /** The audit actions its purge records. */
+  readonly auditActions: ErasureAuditActions;
+  /** The reader, over one env. */
+  readonly read: (env: Record<string, unknown>) => ErasureHistoryReader;
+}

package/src/capability/personColumns.ts

@@ -0,0 +1,83 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { z } from "zod";
+import type { DatabaseSpecMap } from "../data/databases";
+
+/**
+ * **Every capability that holds rows about a person answers for them** — erases them on a purge, or keeps them and
+ * says why, and in both cases exports them (#814). This is the check that holds a capability to it, from its own
+ * schema rather than from a list somebody maintains.
+ *
+ * A table carries a row about a person when a column names one: an id (`userId`, `ownerId`, `subjectId`, `actorId`,
+ * any `…UserId`, the two sides of an invite or a friendship) or an address (`email`, `recipient`, any `…Address`).
+ * A capability whose schema carries one must declare a `user` purge contribution with an `export`. `retain` requires
+ * one already; an erasing contribution may omit it, and for an adopter's own capability that is the honest
+ * `not_exported` — but no kit capability may.
+ *
+ * Over-reaching is cheap here and under-reaching is the defect: a column that names an operator or a sender rather
+ * than the person still costs only a contribution that finds nothing, while a person column the rule missed is rows
+ * an access request never answers for.
+ */
+
+/** Column names that name a person outright. */
+const PERSON_COLUMNS: ReadonlySet<string> = new Set([
+  "userId",
+  "ownerId",
+  "subjectId",
+  "actorId",
+  "inviterId",
+  "inviteeId",
+  "userA",
+  "userB",
+  "email",
+  "recipient",
+]);
+
+/** Whether a column, by its camelCase name, names a person: an id of one, or an address. */
+export function isPersonColumn(column: string): boolean {
+  return PERSON_COLUMNS.has(column) || column.endsWith("UserId") || column.endsWith("Address");
+}
+
+/** What the check reads off a capability — its name, its tables and its purge contributions. */
+export interface PersonRowsSubject {
+  readonly name: string;
+  readonly databases?: DatabaseSpecMap;
+  readonly purge?: readonly { readonly subject: string; readonly export?: unknown }[];
+}
+
+/** One capability that holds rows about a person and does not answer for them. */
+export interface PersonRowGap {
+  /** The capability. */
+  readonly capability: string;
+  /** Its person columns, as `table.column`. */
+  readonly columns: readonly string[];
+  /** `no_contribution` — no `user` purge contribution at all; `no_export` — one that does not export. */
+  readonly gap: "no_contribution" | "no_export";
+}
+
+/** Every person column in a capability's tables, as `table.column`, in declaration order. */
+export function personColumnsOf(capability: PersonRowsSubject): string[] {
+  const found: string[] = [];
+  for (const spec of Object.values(capability.databases ?? {})) {
+    for (const [table, schema] of Object.entries(spec.tables)) {
+      const shape = (schema as z.ZodObject).shape ?? {};
+      for (const column of Object.keys(shape)) if (isPersonColumn(column)) found.push(`${table}.${column}`);
+    }
+  }
+  return found;
+}
+
+/** Every capability among `capabilities` that holds rows about a person and does not answer for them. */
+export function personRowGaps(capabilities: readonly PersonRowsSubject[]): PersonRowGap[] {
+  const gaps: PersonRowGap[] = [];
+  for (const capability of capabilities) {
+    const columns = personColumnsOf(capability);
+    if (columns.length === 0) continue;
+    const contribution = capability.purge?.find((candidate) => candidate.subject === "user");
+    if (!contribution) gaps.push({ capability: capability.name, columns, gap: "no_contribution" });
+    else if (typeof contribution.export !== "function")
+      gaps.push({ capability: capability.name, columns, gap: "no_export" });
+  }
+  return gaps;
+}