@pithy-sh/core 0.13.0 → 0.15.0

package/src/controlPlane/discovery/adminRoute.ts

@@ -2,7 +2,10 @@
 // SPDX-License-Identifier: MIT
 
 import { z } from "zod";
+import { PresenceRoomDescriptor } from "../../presence/http/responses";
 import { PrivacyPosture } from "../../privacy/posture";
+import { EffectiveRetention } from "../../retention/policy";
+import { ScopeKind } from "../scope/kind";
 import { ControlPlaneScope } from "../scope/scope";
 import { ManifestConfigKey, ManifestConfigValues } from "./configuration";
 import { CapabilityHealthReport, HealthSummary, HealthSummaryKey, healthReport, healthWire } from "./healthSummary";
@@ -32,6 +35,35 @@ export const AdminRouteMethod = z
   .describe("The HTTP method this admin route answers on.");
 export type AdminRouteMethod = z.infer<typeof AdminRouteMethod>;
 
+/**
+ * An admin route's operation id (`docs/AGENT-ACCESS.md` §5): lowercase words joined by `.`, `_` or `-`.
+ *
+ * **Permanent once published.** An agent names a tool in prompts, saved workflows and its own record of what
+ * worked, so a renamed operation breaks callers silently — the same class of rule as a role name. Unique within
+ * its capability; `packages/cli/src/ci/adminOperations.test.ts` holds every kit capability's to a table.
+ */
+export const AdminOperation = z
+  .string()
+  .max(64)
+  .regex(
+    /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/,
+    "An operation is lowercase words joined by `.`, `_` or `-`, e.g. `threads.reply`.",
+  )
+  .describe("An admin route's permanent name within its capability, e.g. `threads.reply`.");
+export type AdminOperation = z.infer<typeof AdminOperation>;
+
+/**
+ * An admin route's input as JSON Schema: an object whose `path`, `query` and `body` properties are each
+ * the JSON Schema of the validator the route runs on that part of the request.
+ *
+ * A record rather than a modeled schema, because it is JSON Schema — a vocabulary this manifest relays, never
+ * one it defines — and an MCP client publishes it verbatim as a tool's `inputSchema`.
+ */
+export const AdminRouteInput = z
+  .record(z.string().describe("A JSON Schema keyword."), z.unknown().describe("Its value."))
+  .describe("A JSON Schema object describing the route's path parameters, query and body.");
+export type AdminRouteInput = z.infer<typeof AdminRouteInput>;
+
 /** One admin route a capability contributes behind the `control-plane` strategy. */
 export const AdminRoute = z
   .object({
@@ -49,12 +81,31 @@ export const AdminRoute = z
       .string()
       .min(1)
       .describe("One line describing what the route does, for a management client to render beside it."),
+    // Optional on the wire: a client reading a Worker that states no kind treats the route as the most restrictive.
+    kind: ScopeKind.optional().describe(
+      "What kind of operation the route's scope grants — `reads`, `writes`, `sends`, `charges`, `deletes` or `credentials` — declared by the capability that owns the scope. Every route sharing a scope declares the same kind, so a management client maps its own roles onto kinds rather than onto scopes. Absent for a route with no scope, and from an older Worker, which a client treats as `credentials`, the most restrictive.",
+    ),
+    // Optional: absent says *this Worker predates operations*, and a client that names tools from them offers no
+    // tool for such a route rather than guessing a name.
+    operation: AdminOperation.optional().describe(
+      "The route's permanent name within its capability — `threads.reply`, `users.suspend` — declared beside the route by the capability that owns it. Never derived from the path, which moves when an adopter moves a `basePath`, and never from the scope, which several routes share. An MCP tool is named `<capability>_<operation>`. Absent from a Worker that predates #723.",
+    ),
+    input: AdminRouteInput.optional().describe(
+      "What the route takes, as one JSON Schema object with up to three properties — `path`, `query` and `body` — generated from the Zod schemas the route validates with, so it cannot drift from what the route accepts. Filled in by the seam from the composed router, never declared by hand. Absent from a Worker that predates #723.",
+    ),
   })
   .describe(
     "One admin route, described well enough for a management client to call it without holding any capability-specific knowledge.",
   );
 export type AdminRoute = z.infer<typeof AdminRoute>;
 
+/**
+ * An admin route as a capability declares it: a scoped route states its kind, and a route with no scope has none.
+ * `Capability.adminRoutes` takes this, so a scoped route without a kind does not compile.
+ */
+export type AdminRouteDeclaration = Omit<AdminRoute, "scope" | "kind"> &
+  ({ scope: ControlPlaneScope; kind: ScopeKind } | { scope: null; kind?: undefined });
+
 /**
  * One composed capability's declaration — everything about it that is the same for every caller.
  *
@@ -75,7 +126,7 @@ export const CapabilityDeclaration = z
         "The npm version of the package supplying this capability, or null where there is none — the adopter's own `app` capability has a name and no package. Reported per capability and never aggregated: a project composes some capabilities and not others, so only the intersection of what it composes and what changed is worth reporting. Joined against a release feed on the `package` beside it, never on `name` — the two are different kinds of thing.",
       ),
     // **Defaulted, like every field added after the first manifest shipped**, and for the reason written
-    // out below against `healthKeys`: a Worker deployed before #626 sends no package, and a required
+    // out below against `healthKeys`: an older Worker sends no package, and a required
     // field would cost that client the whole manifest rather than the one key it did not get.
     package: z
       .string()
@@ -93,14 +144,14 @@ export const CapabilityDeclaration = z
     // version on purpose — a client dispatches on what the Worker declares right now — so absence is the
     // only way a new field can ship without breaking every Worker deployed before it. A required one fails
     // at the object level, which costs the client the *whole* manifest rather than the part it did not
-    // know about, and every pane goes dark for an adopter whose only mistake was not upgrading yet (#352).
+    // know about, and every pane goes dark for an adopter whose only mistake was not upgrading yet.
     healthKeys: z
       .array(HealthSummaryKey)
       .default([])
       .describe(
         "The closed vocabulary of scalars this capability may report about its own state, or empty when it reports none — including when the Worker predates this field and says nothing at all. Declared alongside the routes so a client can render a key it has never heard of from what the Worker says about it — and so a *withheld* number is visible as a key with no value, rather than as silence.",
       ),
-    // Both defaulted, for the reason stated above `healthKeys` and with the same force (#422). The two
+    // Both defaulted, for the reason stated above `healthKeys` and with the same force. The two
     // arrived together and travel together: a declaration with no value is a control with nothing behind
     // it, and a value with no declaration is a fact a client can only guess the meaning of.
     configKeys: z
@@ -112,6 +163,14 @@ export const CapabilityDeclaration = z
     config: ManifestConfigValues.default({}).describe(
       "What each declared fact resolved to for this deployment. The same answer for every caller, read off the capability's parsed config at assembly: there is no producer here, so no failure state, no per-request cost, and no staleness beyond the manifest itself.",
     ),
+    // Optional rather than defaulted: absent says *this Worker predates presence rooms*, which a client must not
+    // read as *this capability has none*.
+    presenceRooms: z
+      .array(PresenceRoomDescriptor)
+      .optional()
+      .describe(
+        "The presence room kinds this capability serves — who else has one of its records open, live — or empty when it serves none. Absent from a Worker that predates presence rooms. Mint a ticket into one at `POST /control-plane/presence/tickets` with the kind's own `scope`.",
+      ),
   })
   .describe(
     "One capability this Worker composes, the package and version it is at, the admin surface it exposes, the summary it may report, and the configured facts a client must respect to call any of it.",
@@ -123,12 +182,12 @@ export type CapabilityDeclaration = z.infer<typeof CapabilityDeclaration>;
  *
  * Two flat fields, and neither is what a consumer reads: {@link CapabilityDescriptor} decodes them into
  * one value that says which of the four states it is in. They are flat here because the wire has an
- * older half to keep working. A Worker deployed before #350 sends no `healthUnavailable` and a Worker
- * deployed before #317 sends neither field, and both must still parse; and a client pinned to a build
+ * older half to keep working. An older Worker may send no `healthUnavailable`, or neither
+ * field, and both must still parse; and a client pinned to a build
  * older than the Worker it is reading strips the field it has never heard of and lands on `health:
  * null`, which renders as silence rather than as a zero. Putting the fourth state *inside* `health`
  * would have cost that client the whole manifest for one capability's bad afternoon, which is the
- * failure #352 is about.
+ * failure the defaults above exist to prevent.
  */
 const CapabilityDescriptorWire = CapabilityDeclaration.extend({
   // Defaulted for the same reason as `healthKeys` above, and it lands on the meaning it already had: a
@@ -185,7 +244,7 @@ export const CapabilityDescriptor = z
       // had: a capability that declares no summary, and one that states no configured fact.
       //
       // **The `map` is load-bearing for the compiler and inert at run time, and both halves are the
-      // point (#471).** `HealthSummaryKey.nominal` is `.default(null)`, so the key's input type has it
+      // point.** `HealthSummaryKey.nominal` is `.default(null)`, so the key's input type has it
       // optional and its output type has it present — and this encode sits exactly on that seam, so
       // spreading the keys through unchanged does not compile.
       //
@@ -214,7 +273,7 @@ export type CapabilityDescriptor = z.infer<typeof CapabilityDescriptor>;
  * now — so a capability that changed its paths or its scopes reports the change directly, and a schema
  * version would be a second source of truth to keep in sync with the first. That reasoning is unchanged.
  *
- * **And `capabilities[].version` travels with the package it belongs to** (#626). A version is only
+ * **And `capabilities[].version` travels with the package it belongs to**. A version is only
  * actionable joined against a release feed, a feed is keyed by package name, and a capability name is
  * not one — `controlplane` ships inside `@pithy-sh/core`. Reporting the version alone left every client
  * guessing the key, and the guess failed silently on the most frequently released package there is.
@@ -228,7 +287,7 @@ export type CapabilityDescriptor = z.infer<typeof CapabilityDescriptor>;
  * we just fixed", and "does this project predate the capability a pane needs". Reporting only one leaves
  * half the questions unanswerable, and they are the halves people actually ask.
  *
- * **And each entry carries a third thing: the configured facts that capability states** (#422). Knowing
+ * **And each entry carries a third thing: the configured facts that capability states**. Knowing
  * where a route is and which scope it needs is not always enough to call it — `POST
  * {base}/entitlements/grant` names a holder, and whether this project's holders are people or
  * organizations is a decision the adopter made in config. A client that cannot read the decision guesses
@@ -257,6 +316,9 @@ export const ControlPlaneManifest = z
     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.",
     ),
+    retention: EffectiveRetention.optional().describe(
+      "How long this Worker keeps deleted accounts, the audit trail and each class of personal data, as its `retention` block takes effect: every window in days and where it came from. Absent from an older Worker.",
+    ),
     capabilities: z
       .array(CapabilityDescriptor)
       .describe(

package/src/controlPlane/discovery/routeInput.ts

@@ -0,0 +1,86 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { requestContractOf } from "../../http/validation";
+import { jsonSchema, type RouteGroup } from "../../openapi/document";
+import { operationsOf } from "../../openapi/operations";
+import type { AdminRoute, AdminRouteInput, CapabilityDeclaration } from "./adminRoute";
+
+/**
+ * What each admin route takes, read off the composed router (#723, `docs/AGENT-ACCESS.md` §3).
+ *
+ * **Generated, never declared.** A route already states what it accepts on its own line — `validate("param",
+ * …)`, `validate("query", …)`, `validate("json", …)` — and that is the schema the request is actually parsed
+ * with. So the manifest's `input` is that schema, converted once, rather than a second description a capability
+ * would have to keep in step with the first. A route that changes its body changes its tool on the same commit.
+ *
+ * **One object, three parts.** An MCP tool takes one argument object, and a route reads three places, so the
+ * input is an object with a `path`, a `query` and a `body` property — each present only when the route
+ * validates that part. A client splits the arguments back out along the same three keys. A route that
+ * validates nothing still gets an input: an empty object, which says *this takes nothing* rather than *this
+ * Worker cannot say*.
+ */
+
+/** The three parts of a request an admin route's input may carry, and the validator target each comes from. */
+const PARTS = { param: "path", query: "query", json: "body" } as const;
+
+/**
+ * The JSON Schema of one route's input, built from the request contracts on its handlers. The app's own MCP tools
+ * (`../../mcp/tools.ts`) take their input from here too, so a tool on either server has one shape.
+ */
+export function inputOf(handlers: readonly unknown[]): AdminRouteInput {
+  const properties: Record<string, unknown> = {};
+  const required: string[] = [];
+  for (const handler of handlers) {
+    const contract = requestContractOf(handler);
+    if (contract === undefined) continue;
+    const part = PARTS[contract.target as keyof typeof PARTS];
+    if (part === undefined) continue;
+    properties[part] = jsonSchema(contract.schema, "input");
+    // A path parameter is always present. A query arrives as an object even when the URL carries none, so it is
+    // required only when its schema refuses an empty one; a body is required when its schema refuses none at all.
+    const absent = part === "query" ? {} : undefined;
+    if (part === "path" || !contract.schema.safeParse(absent).success) required.push(part);
+  }
+  return {
+    type: "object",
+    properties,
+    ...(required.length > 0 ? { required } : {}),
+    additionalProperties: false,
+  };
+}
+
+/**
+ * Every routed operation's input, keyed `METHOD path` as the manifest's admin routes are. Routes the groups do
+ * not hold are simply absent — an admin route the router does not serve is `missingAdminRoutes`'s finding, not
+ * this module's.
+ */
+export function routeInputs(groups: readonly RouteGroup[]): ReadonlyMap<string, AdminRouteInput> {
+  const inputs = new Map<string, AdminRouteInput>();
+  for (const group of groups) {
+    for (const operation of operationsOf(group.routes)) {
+      inputs.set(`${operation.method.toUpperCase()} ${operation.path}`, inputOf(operation.handlers));
+    }
+  }
+  return inputs;
+}
+
+/**
+ * The declarations with each admin route's `input` filled in from the router.
+ *
+ * Without route groups — an app `createBackend` did not assemble — the declarations go out as they are, and a
+ * client offers no tool for a route it was told nothing about. That is the same answer an older Worker gets.
+ */
+export function withRouteInputs(
+  declarations: readonly CapabilityDeclaration[],
+  inputs: ReadonlyMap<string, AdminRouteInput> | undefined,
+): CapabilityDeclaration[] {
+  if (inputs === undefined) return [...declarations];
+  return declarations.map((declaration) => ({
+    ...declaration,
+    adminRoutes: declaration.adminRoutes.map((route): AdminRoute => {
+      const input = inputs.get(`${route.method} ${route.path}`);
+      return input === undefined ? route : { ...route, input };
+    }),
+  }));
+}

package/src/controlPlane/discovery/toolName.ts

@@ -0,0 +1,23 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The one place an MCP tool name is made (`docs/AGENT-ACCESS.md` §5) — for the control-plane server's tools, and
+ * for the app's own MCP endpoint's (`../../mcp/tools.ts`), so one rule names both servers' tools.
+ *
+ * **Derived, never hand-written.** A tool is `<capability>_<operation>`: the capability's name, which already
+ * partitions migrations, tables and error codes, and the operation the capability declared beside the route. Two
+ * capabilities both exposing `threads.list` cannot collide, and nothing about the route's path or scope — both of
+ * which move or are shared — reaches the name.
+ *
+ * **Neither existing separator survives.** MCP names conventionally allow `[a-z0-9_-]`, so a scope's `:`, an
+ * audit action's `/` and an operation's `.` all become `_`. Anything else outside that alphabet does too, so a
+ * name is always one a client accepts — but a kit operation never needs it, and `AdminOperation` refuses one that
+ * would.
+ *
+ * **Once published, a tool name is permanent.** An agent references it in prompts and saved workflows, so this
+ * function's output for a given pair must never change. `toolName.test.ts` pins it.
+ */
+export function controlPlaneToolName(capability: string, operation: string): string {
+  return `${capability}_${operation}`.toLowerCase().replace(/[^a-z0-9_-]/g, "_");
+}

package/src/controlPlane/erasure/attest.ts

@@ -0,0 +1,205 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { AuditCitation } from "../../audit/citations";
+import type { ErasureAuditActions, ErasureHistoryRow } from "../../capability/erasure";
+import type { PurgeSubject } from "../../capability/purge";
+import type {
+  ErasureAttestation,
+  ErasureCitation,
+  ErasurePeriodEntry,
+  ErasureState,
+  ErasureStepView,
+} from "../http/responses";
+
+/**
+ * **The erasure attestation, assembled (#823)** — pure functions over a subject's lifecycle rows and the audit events
+ * that name it, so every rule here is tested without a database.
+ *
+ * ## Which deletion
+ *
+ * A subject can be deleted, restored, and deleted again. The attestation is about the **deletion in force**: the
+ * first `deleted` row after the last `restored`. A subject whose last act was a restore has no erasure to attest.
+ * A hard deletion that brought a soft one forward writes a second `deleted` row in the same cycle, so the deletion
+ * reads as `hard` and comes due when the later row says.
+ *
+ * ## Where the purge stands
+ *
+ * `complete` once a `purged` row is written. `failed` when the last thing the purge wrote was its failure — a later
+ * pass that runs a step again puts it back `in_progress`. `scheduled` while nothing has run and the window is still
+ * open. `in_progress` otherwise. **Overdue** is not a state: a purge not complete two days after it came due has
+ * missed a daily pass, whatever it last wrote, and is named with the step it stopped at.
+ *
+ * ## A step run twice
+ *
+ * The daily pass is the purge's outer retry, so a failed purge's steps run again the next day and record again.
+ * Each capability is shown once, in the order it first ran, as it last finished.
+ */
+
+/** How long after coming due a purge that has not completed is overdue: two daily passes. */
+export const ERASURE_OVERDUE_AFTER_MS = 2 * 86_400_000;
+
+/** The step a purge that has run nothing is named as having stopped at. */
+export const ERASURE_NOT_STARTED = "due";
+
+/** The rows of the deletion in force, or `null` when there is none — never deleted, or restored since. */
+export function deletionInForce(rows: readonly ErasureHistoryRow[]): ErasureHistoryRow[] | null {
+  let start = -1;
+  for (let index = 0; index < rows.length; index += 1) {
+    const row = rows[index];
+    if (row?.action === "restored") start = -1;
+    else if (row?.action === "deleted" && start === -1) start = index;
+  }
+  return start === -1 ? null : rows.slice(start);
+}
+
+/** A citation as the wire carries it. */
+function cited(citation: AuditCitation | undefined): ErasureCitation | null {
+  if (!citation) return null;
+  return {
+    eventId: citation.eventId,
+    action: citation.action,
+    occurredAt: citation.occurredAt.toISOString(),
+    tenant: citation.tenant,
+    seq: citation.seq,
+    hash: citation.hash,
+  };
+}
+
+/** The newest citation matching, or undefined. */
+function latest(citations: readonly AuditCitation[], match: (citation: AuditCitation) => boolean) {
+  let found: AuditCitation | undefined;
+  for (const citation of citations) {
+    if (match(citation) && (!found || citation.occurredAt.getTime() >= found.occurredAt.getTime())) found = citation;
+  }
+  return found;
+}
+
+/** What one subject's attestation is assembled from. */
+export interface AttestInput {
+  /** The kind of subject. */
+  readonly subject: PurgeSubject;
+  /** Its id. */
+  readonly subjectId: string;
+  /** Its lifecycle rows, oldest first. */
+  readonly rows: readonly ErasureHistoryRow[];
+  /** The audit events naming it, or `null` when no audit is composed. */
+  readonly citations: readonly AuditCitation[] | null;
+  /** The actions its purge records. */
+  readonly actions: ErasureAuditActions;
+  /** Now. */
+  readonly now: Date;
+}
+
+/** One subject's attestation, or `null` when it has no deletion in force. */
+export function attest(input: AttestInput): ErasureAttestation | null {
+  const cycle = deletionInForce(input.rows);
+  const deletion = cycle?.[0];
+  if (!cycle || !deletion) return null;
+  const deletions = cycle.filter((row) => row.action === "deleted");
+  const hard = deletions.some((row) => row.mode === "hard");
+  const mode = hard ? "hard" : (deletion.mode ?? null);
+  const purgeAfter = [...deletions].reverse().find((row) => row.purgeAfter)?.purgeAfter ?? null;
+
+  // Only events recorded since this deletion: an earlier cycle's events are about a deletion that was undone.
+  const citations = (input.citations ?? []).filter((each) => each.occurredAt.getTime() >= deletion.at.getTime());
+  const steps = new Map<string, ErasureHistoryRow>();
+  let activity: ErasureHistoryRow | undefined;
+  let purged: ErasureHistoryRow | undefined;
+  for (const row of cycle) {
+    if (row.action === "purge_step" || row.action === "purge_retained") {
+      // Re-inserting would move a re-run step to the end; setting keeps its first place with its last row.
+      steps.set(row.step ?? "", row);
+      activity = row;
+    } else if (row.action === "purge_failed") activity = row;
+    else if (row.action === "purged") purged = row;
+  }
+
+  const state = stateOf({ purged, activity, purgeAfter, now: input.now });
+  const overdue =
+    (state === "in_progress" || state === "failed") &&
+    purgeAfter !== null &&
+    input.now.getTime() - purgeAfter.getTime() > ERASURE_OVERDUE_AFTER_MS;
+  const stoppedAt = state === "failed" || overdue ? (activity?.step ?? ERASURE_NOT_STARTED) : null;
+
+  const views: ErasureStepView[] = [...steps.values()].map((row) => {
+    const capability = row.step ?? "";
+    const retained = row.action === "purge_retained";
+    return {
+      capability,
+      disposition: retained ? "retained" : "erased",
+      reason: retained ? row.reason : null,
+      summary: retained ? null : row.reason,
+      completedAt: row.at.toISOString(),
+      audit: cited(latest(citations, (each) => each.action === input.actions.step && each.step === capability)),
+    };
+  });
+
+  return {
+    subject: { type: input.subject, id: input.subjectId },
+    deletion: {
+      at: deletion.at.toISOString(),
+      actorType: deletion.actorType,
+      reason: deletion.reason,
+      mode,
+      purgeAfter: purgeAfter ? purgeAfter.toISOString() : null,
+      audit: cited(citations.find((each) => input.actions.deleted.includes(each.action))),
+    },
+    state,
+    overdue,
+    stoppedAt,
+    steps: views,
+    completedAt: purged ? purged.at.toISOString() : null,
+    completion: purged ? cited(latest(citations, (each) => each.action === input.actions.purged)) : null,
+    failure: state === "failed" ? cited(latest(citations, (each) => each.action === input.actions.failed)) : null,
+    trail: input.citations === null ? "absent" : "recorded",
+  };
+}
+
+/** Where a purge stands, from its last activity. See the file header. */
+function stateOf(input: {
+  purged: ErasureHistoryRow | undefined;
+  activity: ErasureHistoryRow | undefined;
+  purgeAfter: Date | null;
+  now: Date;
+}): ErasureState {
+  if (input.purged) return "complete";
+  if (input.activity?.action === "purge_failed") return "failed";
+  if (!input.activity && (input.purgeAfter === null || input.purgeAfter.getTime() > input.now.getTime())) {
+    return "scheduled";
+  }
+  return "in_progress";
+}
+
+/** One attestation, summarized for the period read. */
+export function periodEntry(attestation: ErasureAttestation): ErasurePeriodEntry {
+  return {
+    subject: attestation.subject,
+    state: attestation.state,
+    overdue: attestation.overdue,
+    purgeAfter: attestation.deletion.purgeAfter,
+    completedAt: attestation.completedAt,
+    stoppedAt: attestation.stoppedAt,
+  };
+}
+
+/** The period's counts and the purges that need someone, from its entries. */
+export function summarize(entries: readonly ErasurePeriodEntry[]) {
+  const counts = { scheduled: 0, inProgress: 0, complete: 0, failed: 0, overdue: 0 };
+  for (const entry of entries) {
+    if (entry.state === "scheduled") counts.scheduled += 1;
+    else if (entry.state === "in_progress") counts.inProgress += 1;
+    else if (entry.state === "complete") counts.complete += 1;
+    else counts.failed += 1;
+    if (entry.overdue) counts.overdue += 1;
+  }
+  const attention = entries.filter((entry) => entry.state === "failed" || entry.overdue);
+  return { counts, attention };
+}
+
+/** Every entry, oldest due first; a deletion recorded before #823 has no due instant and sorts last. */
+export function byDue(entries: readonly ErasurePeriodEntry[]): ErasurePeriodEntry[] {
+  const key = (entry: ErasurePeriodEntry) =>
+    entry.purgeAfter ? Date.parse(entry.purgeAfter) : Number.MAX_SAFE_INTEGER;
+  return [...entries].sort((a, b) => key(a) - key(b) || a.subject.id.localeCompare(b.subject.id));
+}

package/src/controlPlane/erasure/read.ts

@@ -0,0 +1,169 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { type AuditCitation, composedAuditCitations } from "../../audit/citations";
+import type { Capability } from "../../capability/capability";
+import type { ErasureRecords } from "../../capability/erasure";
+import type { PurgeSubject } from "../../capability/purge";
+import { NotFoundError, ValidationError } from "../../error/pithyError";
+import type {
+  ControlPlaneErasurePeriodResponse,
+  ControlPlaneErasureSubjectResponse,
+  ErasurePeriodEntry,
+} from "../http/responses";
+import type { ErasurePeriodQuery } from "../http/schemas";
+import { attest, byDue, periodEntry, summarize } from "./attest";
+
+/**
+ * **The two erasure reads (#823), over whatever this Worker composes.**
+ *
+ * The rows live in the capability that owns each subject — auth for a user, organization for an organization —
+ * and are read through the {@link ErasureRecords} each declares. The events live in the audit trail and are read
+ * through the citation reader `@pithy-sh/audit` declares. Neither is imported: both are found among the composed
+ * capabilities, so a Worker with no organization attests users only and says so, and one with no audit attests from
+ * the lifecycle rows and says the trail is absent.
+ */
+
+/** The default window: a quarter. */
+export const ERASURE_DEFAULT_WINDOW_MS = 90 * 86_400_000;
+
+/** The longest window one read covers: a year and a day, so a year's audit is one call. */
+export const ERASURE_MAX_WINDOW_MS = 366 * 86_400_000;
+
+/** How many subjects one history or citation read names at once — inside D1's bound-parameter limit. */
+const CHUNK = 50;
+
+/** What the reads need from the seam. */
+export interface ErasureReadDeps {
+  /** Every composed capability. */
+  readonly composition: () => readonly Capability[];
+  /** The clock. */
+  readonly now: () => Date;
+}
+
+/** The capability recording each subject's purges, first declared wins. */
+export function erasureProviders(capabilities: readonly Capability[]): Map<PurgeSubject, ErasureRecords> {
+  const providers = new Map<PurgeSubject, ErasureRecords>();
+  for (const capability of capabilities) {
+    const records = capability.erasureRecords;
+    if (records && !providers.has(records.subject)) providers.set(records.subject, records);
+  }
+  return providers;
+}
+
+/** The window a period read covers, defaulted and bounded. */
+export function erasureWindow(query: ErasurePeriodQuery, now: Date): { since: Date; until: Date } {
+  const until = query.until ? new Date(query.until) : now;
+  const since = query.since ? new Date(query.since) : new Date(until.getTime() - ERASURE_DEFAULT_WINDOW_MS);
+  if (since.getTime() > until.getTime()) {
+    throw new ValidationError({
+      message: "`since` is after `until`.",
+      detail: `erasure window ${since.toISOString()} to ${until.toISOString()}`,
+    });
+  }
+  if (until.getTime() - since.getTime() > ERASURE_MAX_WINDOW_MS) {
+    throw new ValidationError({
+      message: "An erasure window is at most 366 days. Ask for a shorter one.",
+      detail: `erasure window ${since.toISOString()} to ${until.toISOString()}`,
+    });
+  }
+  return { since, until };
+}
+
+/** Every value in chunks of {@link CHUNK}. */
+function chunks<T>(values: readonly T[]): T[][] {
+  const out: T[][] = [];
+  for (let index = 0; index < values.length; index += CHUNK) out.push(values.slice(index, index + CHUNK));
+  return out;
+}
+
+/** The audit events a subject's purge records, for these ids, or `null` with no audit composed. */
+async function citationsFor(
+  capabilities: readonly Capability[],
+  env: Record<string, unknown>,
+  records: ErasureRecords,
+  ids: readonly string[],
+): Promise<AuditCitation[] | null> {
+  const reader = composedAuditCitations(capabilities, env);
+  if (!reader) return null;
+  const { deleted, step, failed, purged } = records.auditActions;
+  const actions = [...deleted, step, failed, purged];
+  const found: AuditCitation[] = [];
+  for (const resourceIds of chunks(ids)) {
+    found.push(...(await reader({ resourceType: records.resourceType, resourceIds, actions })));
+  }
+  return found;
+}
+
+/** `GET /control-plane/erasure/:subjectType/:subjectId`. */
+export async function readErasureSubject(
+  env: Record<string, unknown>,
+  deps: ErasureReadDeps,
+  subject: PurgeSubject,
+  subjectId: string,
+): Promise<ControlPlaneErasureSubjectResponse> {
+  const capabilities = deps.composition();
+  const records = erasureProviders(capabilities).get(subject);
+  if (!records) {
+    throw new NotFoundError({
+      message: `This Worker records no erasures for ${subject === "user" ? "a user" : "an organization"}.`,
+      action: `Compose the capability that owns ${subject} purges in this Worker, then ask again.`,
+      detail: `no composed capability declares erasureRecords for ${subject}`,
+    });
+  }
+  const now = deps.now();
+  const rows = await records.read(env).history([subjectId]);
+  const citations = rows.length === 0 ? null : await citationsFor(capabilities, env, records, [subjectId]);
+  const attestation =
+    rows.length === 0 ? null : attest({ subject, subjectId, rows, citations, actions: records.auditActions, now });
+  if (!attestation) {
+    throw new NotFoundError({
+      message: "No erasure on record for this subject.",
+      action: "It was never deleted, or it was restored. Nothing has been erased.",
+      detail: `no deletion in force for ${subject} ${subjectId}`,
+    });
+  }
+  return { generatedAt: now.toISOString(), attestation };
+}
+
+/** `GET /control-plane/erasure?since&until`. */
+export async function readErasurePeriod(
+  env: Record<string, unknown>,
+  deps: ErasureReadDeps,
+  query: ErasurePeriodQuery,
+): Promise<ControlPlaneErasurePeriodResponse> {
+  const now = deps.now();
+  const { since, until } = erasureWindow(query, now);
+  const providers = erasureProviders(deps.composition());
+  const entries: ErasurePeriodEntry[] = [];
+  for (const [subject, records] of providers) {
+    const reader = records.read(env);
+    const ids = await reader.subjectsIn(since, until);
+    for (const batch of chunks(ids)) {
+      const rows = await reader.history(batch);
+      for (const subjectId of batch) {
+        const attestation = attest({
+          subject,
+          subjectId,
+          rows: rows.filter((row) => row.subjectId === subjectId),
+          // The period read counts and names; the citations are the subject read's.
+          citations: null,
+          actions: records.auditActions,
+          now,
+        });
+        if (attestation) entries.push(periodEntry(attestation));
+      }
+    }
+  }
+  const purges = byDue(entries);
+  const { counts, attention } = summarize(purges);
+  return {
+    generatedAt: now.toISOString(),
+    since: since.toISOString(),
+    until: until.toISOString(),
+    subjects: [...providers.keys()],
+    counts,
+    attention,
+    purges,
+  };
+}