@pithy-sh/core 0.12.0 → 0.14.0

package/dist/controlPlane/discovery/adminRoute.d.ts

@@ -1,6 +1,8 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 import { z } from "zod";
+import { ScopeKind } from "../scope/kind";
+import { ControlPlaneScope } from "../scope/scope";
 /**
  * What a capability tells a management client about its own admin surface.
  *
@@ -28,6 +30,24 @@ export declare const AdminRouteMethod: z.ZodEnum<{
     PUT: "PUT";
 }>;
 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 declare const AdminOperation: z.ZodString;
+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 declare const AdminRouteInput: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export type AdminRouteInput = z.infer<typeof AdminRouteInput>;
 /** One admin route a capability contributes behind the `control-plane` strategy. */
 export declare const AdminRoute: z.ZodObject<{
     method: z.ZodEnum<{
@@ -40,8 +60,29 @@ export declare const AdminRoute: z.ZodObject<{
     path: z.ZodString;
     scope: z.ZodNullable<z.ZodString>;
     summary: z.ZodString;
+    kind: z.ZodOptional<z.ZodEnum<{
+        charges: "charges";
+        credentials: "credentials";
+        deletes: "deletes";
+        reads: "reads";
+        sends: "sends";
+        writes: "writes";
+    }>>;
+    operation: z.ZodOptional<z.ZodString>;
+    input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 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.
  *
@@ -64,6 +105,16 @@ export declare const CapabilityDeclaration: z.ZodObject<{
         path: z.ZodString;
         scope: z.ZodNullable<z.ZodString>;
         summary: z.ZodString;
+        kind: z.ZodOptional<z.ZodEnum<{
+            charges: "charges";
+            credentials: "credentials";
+            deletes: "deletes";
+            reads: "reads";
+            sends: "sends";
+            writes: "writes";
+        }>>;
+        operation: z.ZodOptional<z.ZodString>;
+        input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>;
     healthKeys: z.ZodDefault<z.ZodArray<z.ZodObject<{
         key: z.ZodString;
@@ -89,6 +140,14 @@ export declare const CapabilityDeclaration: z.ZodObject<{
         summary: z.ZodString;
     }, z.core.$strip>>>;
     config: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    presenceRooms: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        scope: z.ZodString;
+        activities: z.ZodArray<z.ZodString>;
+        maxParticipants: z.ZodNumber;
+        sessionTicketPath: z.ZodNullable<z.ZodString>;
+        socketPath: z.ZodString;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type CapabilityDeclaration = z.infer<typeof CapabilityDeclaration>;
 export declare const CapabilityDescriptor: z.ZodCodec<z.ZodObject<{
@@ -106,6 +165,16 @@ export declare const CapabilityDescriptor: z.ZodCodec<z.ZodObject<{
         path: z.ZodString;
         scope: z.ZodNullable<z.ZodString>;
         summary: z.ZodString;
+        kind: z.ZodOptional<z.ZodEnum<{
+            charges: "charges";
+            credentials: "credentials";
+            deletes: "deletes";
+            reads: "reads";
+            sends: "sends";
+            writes: "writes";
+        }>>;
+        operation: z.ZodOptional<z.ZodString>;
+        input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>;
     healthKeys: z.ZodDefault<z.ZodArray<z.ZodObject<{
         key: z.ZodString;
@@ -131,6 +200,14 @@ export declare const CapabilityDescriptor: z.ZodCodec<z.ZodObject<{
         summary: z.ZodString;
     }, z.core.$strip>>>;
     config: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    presenceRooms: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        scope: z.ZodString;
+        activities: z.ZodArray<z.ZodString>;
+        maxParticipants: z.ZodNumber;
+        sessionTicketPath: z.ZodNullable<z.ZodString>;
+        socketPath: z.ZodString;
+    }, z.core.$strip>>>;
     health: z.ZodDefault<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>>;
     healthUnavailable: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>, z.ZodObject<{
@@ -148,6 +225,16 @@ export declare const CapabilityDescriptor: z.ZodCodec<z.ZodObject<{
         path: z.ZodString;
         scope: z.ZodNullable<z.ZodString>;
         summary: z.ZodString;
+        kind: z.ZodOptional<z.ZodEnum<{
+            charges: "charges";
+            credentials: "credentials";
+            deletes: "deletes";
+            reads: "reads";
+            sends: "sends";
+            writes: "writes";
+        }>>;
+        operation: z.ZodOptional<z.ZodString>;
+        input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>;
     healthKeys: z.ZodDefault<z.ZodArray<z.ZodObject<{
         key: z.ZodString;
@@ -173,6 +260,14 @@ export declare const CapabilityDescriptor: z.ZodCodec<z.ZodObject<{
         summary: z.ZodString;
     }, z.core.$strip>>>;
     config: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    presenceRooms: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        scope: z.ZodString;
+        activities: z.ZodArray<z.ZodString>;
+        maxParticipants: z.ZodNumber;
+        sessionTicketPath: z.ZodNullable<z.ZodString>;
+        socketPath: z.ZodString;
+    }, z.core.$strip>>>;
     health: z.ZodDiscriminatedUnion<[z.ZodObject<{
         state: z.ZodLiteral<"undeclared">;
     }, z.core.$strip>, z.ZodObject<{
@@ -193,7 +288,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.
@@ -207,7 +302,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
@@ -247,6 +342,38 @@ export declare const ControlPlaneManifest: z.ZodObject<{
             liveVersions: z.ZodNumber;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    retention: z.ZodOptional<z.ZodObject<{
+        purgeWindows: z.ZodArray<z.ZodObject<{
+            subject: z.ZodEnum<{
+                organization: "organization";
+                user: "user";
+            }>;
+            days: z.ZodNumber;
+            source: z.ZodEnum<{
+                capability: "capability";
+                floor: "floor";
+                policy: "policy";
+            }>;
+        }, z.core.$strip>>;
+        audit: z.ZodObject<{
+            defaultDays: z.ZodNullable<z.ZodNumber>;
+            floorDays: z.ZodNumber;
+            rules: z.ZodArray<z.ZodObject<{
+                prefix: z.ZodString;
+                days: z.ZodNumber;
+                source: z.ZodEnum<{
+                    capability: "capability";
+                    floor: "floor";
+                    policy: "policy";
+                }>;
+            }, z.core.$strip>>;
+            floored: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+        classAges: z.ZodArray<z.ZodObject<{
+            class: z.ZodString;
+            days: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
     capabilities: z.ZodArray<z.ZodCodec<z.ZodObject<{
         name: z.ZodString;
         version: z.ZodNullable<z.ZodString>;
@@ -262,6 +389,16 @@ export declare const ControlPlaneManifest: z.ZodObject<{
             path: z.ZodString;
             scope: z.ZodNullable<z.ZodString>;
             summary: z.ZodString;
+            kind: z.ZodOptional<z.ZodEnum<{
+                charges: "charges";
+                credentials: "credentials";
+                deletes: "deletes";
+                reads: "reads";
+                sends: "sends";
+                writes: "writes";
+            }>>;
+            operation: z.ZodOptional<z.ZodString>;
+            input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strip>>;
         healthKeys: z.ZodDefault<z.ZodArray<z.ZodObject<{
             key: z.ZodString;
@@ -287,6 +424,14 @@ export declare const ControlPlaneManifest: z.ZodObject<{
             summary: z.ZodString;
         }, z.core.$strip>>>;
         config: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        presenceRooms: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            kind: z.ZodString;
+            scope: z.ZodString;
+            activities: z.ZodArray<z.ZodString>;
+            maxParticipants: z.ZodNumber;
+            sessionTicketPath: z.ZodNullable<z.ZodString>;
+            socketPath: z.ZodString;
+        }, z.core.$strip>>>;
         health: z.ZodDefault<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>>;
         healthUnavailable: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>, z.ZodObject<{
@@ -304,6 +449,16 @@ export declare const ControlPlaneManifest: z.ZodObject<{
             path: z.ZodString;
             scope: z.ZodNullable<z.ZodString>;
             summary: z.ZodString;
+            kind: z.ZodOptional<z.ZodEnum<{
+                charges: "charges";
+                credentials: "credentials";
+                deletes: "deletes";
+                reads: "reads";
+                sends: "sends";
+                writes: "writes";
+            }>>;
+            operation: z.ZodOptional<z.ZodString>;
+            input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strip>>;
         healthKeys: z.ZodDefault<z.ZodArray<z.ZodObject<{
             key: z.ZodString;
@@ -329,6 +484,14 @@ export declare const ControlPlaneManifest: z.ZodObject<{
             summary: z.ZodString;
         }, z.core.$strip>>>;
         config: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        presenceRooms: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            kind: z.ZodString;
+            scope: z.ZodString;
+            activities: z.ZodArray<z.ZodString>;
+            maxParticipants: z.ZodNumber;
+            sessionTicketPath: z.ZodNullable<z.ZodString>;
+            socketPath: z.ZodString;
+        }, z.core.$strip>>>;
         health: z.ZodDiscriminatedUnion<[z.ZodObject<{
             state: z.ZodLiteral<"undeclared">;
         }, z.core.$strip>, z.ZodObject<{

package/dist/controlPlane/discovery/adminRoute.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adminRoute.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/discovery/adminRoute.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;;;;;;;;;;;;;;;;GAiBG;AAEH,+CAA+C;AAC/C,eAAO,MAAM,gBAAgB;;;;;;EAE8B,CAAC;AAC5D,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,oFAAoF;AACpF,eAAO,MAAM,UAAU;;;;;;;;;;;iBAmBpB,CAAC;AACJ,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqD/B,CAAC;AACJ,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAiD1E,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAsC9B,CAAC;AACJ,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiCkE,CAAC;AACpG,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE;;;;;;GAMG;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}
+{"version":3,"file":"adminRoute.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/discovery/adminRoute.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAInD;;;;;;;;;;;;;;;;;GAiBG;AAEH,+CAA+C;AAC/C,eAAO,MAAM,gBAAgB;;;;;;EAE8B,CAAC;AAC5D,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,aAOgE,CAAC;AAC5F,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,wCAE+D,CAAC;AAC5F,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,oFAAoF;AACpF,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;iBA+BpB,CAAC;AACJ,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,UAAU,EAAE,OAAO,GAAG,MAAM,CAAC,GACpE,CAAC;IAAE,KAAK,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,CAAC,CAAC;AAEtF;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6D/B,CAAC;AACJ,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAiD1E,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAsC9B,CAAC;AACJ,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoCkE,CAAC;AACpG,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE;;;;;;GAMG;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/controlPlane/discovery/adminRoute.js

@@ -1,8 +1,11 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 import { ControlPlaneScope } from "../scope/scope.js";
+import { PresenceRoomDescriptor } from "../../presence/http/responses.js";
+import { EffectiveRetention } from "../../retention/policy.js";
 import { CapabilityHealthReport, HealthSummary, HealthSummaryKey, healthReport, healthWire } from "./healthSummary.js";
 import { PrivacyPosture } from "../../privacy/posture.js";
+import { ScopeKind } from "../scope/kind.js";
 import { ManifestConfigKey, ManifestConfigValues } from "./configuration.js";
 import { z } from "zod";
 //#region src/controlPlane/discovery/adminRoute.ts
@@ -32,12 +35,31 @@ const AdminRouteMethod = z.enum([
 	"PATCH",
 	"DELETE"
 ]).describe("The HTTP method this admin route answers on.");
+/**
+* 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.
+*/
+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`.");
+/**
+* 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`.
+*/
+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.");
 /** One admin route a capability contributes behind the `control-plane` strategy. */
 const AdminRoute = z.object({
 	method: AdminRouteMethod.describe("The method to call this route with."),
 	path: z.string().min(1).describe("The **fully mounted** path, with the capability's configured `basePath` already applied — `/billing/entitlements/grant`, not `/entitlements/grant`. Built by the capability at assembly, so an adopter who moved the mount point is reflected here rather than silently breaking a client that assumed the default."),
 	scope: ControlPlaneScope.nullable().describe("The scope this route requires, or null when it needs only a verified caller (the seam's `ping`). A client compares it against the connection's granted scopes to know which operations it may actually offer, instead of discovering a 403 by trying."),
-	summary: z.string().min(1).describe("One line describing what the route does, for a management client to render beside it.")
+	summary: z.string().min(1).describe("One line describing what the route does, for a management client to render beside it."),
+	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."),
+	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.");
 /**
 * One composed capability's declaration — everything about it that is the same for every caller.
@@ -53,19 +75,20 @@ const CapabilityDeclaration = z.object({
 	adminRoutes: z.array(AdminRoute).describe("Every admin route this capability contributes, or empty when it contributes none. Most capabilities are empty: having no management surface is the normal case, and saying so explicitly is what lets a client render a capability it cannot act on."),
 	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."),
 	configKeys: z.array(ManifestConfigKey).default([]).describe("The configured facts this capability states, or empty when it states none — including when the Worker predates this field. Declared alongside the routes, because a fact is what a client needs to *call* one: `POST /billing/entitlements/grant` names a holder and never assumes it, so a client that cannot learn what this project bills can only guess — and a guess writes a row nothing reads."),
-	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.")
+	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."),
+	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.");
 /**
 * One composed capability's manifest entry **as it goes over the wire**.
 *
 * 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({
 	health: HealthSummary.nullable().default(null).describe("Every declared value this caller may see, or null when there is none to give — either nothing is declared, or this connection lacks the scope the value is behind, or producing it failed, or the Worker predates this field. **Null is never zero.**"),
@@ -114,7 +137,7 @@ const CapabilityDescriptor = z.codec(CapabilityDescriptorWire, CapabilityDescrip
 * 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.
@@ -128,7 +151,7 @@ const CapabilityDescriptor = z.codec(CapabilityDescriptorWire, CapabilityDescrip
 * 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
@@ -141,8 +164,9 @@ const ControlPlaneManifest = z.object({
 	version: z.string().nullable().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."),
+	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("Every capability composed into this Worker, in composition order with the adopter's own app last. A capability absent here has no data to show, which is a fact the client discovers rather than a setting anybody maintains."),
 	grantedScopes: z.array(ControlPlaneScope).describe("Every scope this connection holds. Together with each route's own `scope`, this is what tells a client which operations to offer and which to hide.")
 }).describe("What this Worker is, what it composes, and how to call the admin surface it exposes.");
 //#endregion
-export { AdminRoute, AdminRouteMethod, CapabilityDeclaration, CapabilityDescriptor, ControlPlaneManifest };
+export { AdminOperation, AdminRoute, AdminRouteInput, AdminRouteMethod, CapabilityDeclaration, CapabilityDescriptor, ControlPlaneManifest };

package/dist/controlPlane/discovery/routeInput.d.ts

@@ -0,0 +1,23 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { type RouteGroup } from "../../openapi/document";
+import type { AdminRouteInput, CapabilityDeclaration } from "./adminRoute";
+/**
+ * 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 declare function inputOf(handlers: readonly unknown[]): AdminRouteInput;
+/**
+ * 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 declare function routeInputs(groups: readonly RouteGroup[]): ReadonlyMap<string, AdminRouteInput>;
+/**
+ * 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 declare function withRouteInputs(declarations: readonly CapabilityDeclaration[], inputs: ReadonlyMap<string, AdminRouteInput> | undefined): CapabilityDeclaration[];
+//# sourceMappingURL=routeInput.d.ts.map

package/dist/controlPlane/discovery/routeInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routeInput.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/discovery/routeInput.ts"],"names":[],"mappings":"AAIA,OAAO,EAAc,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAErE,OAAO,KAAK,EAAc,eAAe,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAoBvF;;;GAGG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,eAAe,CAoBrE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,CAQ/F;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,SAAS,qBAAqB,EAAE,EAC9C,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,SAAS,GACvD,qBAAqB,EAAE,CASzB"}

package/dist/controlPlane/discovery/routeInput.js

@@ -0,0 +1,80 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { requestContractOf } from "../../http/validation.js";
+import { operationsOf } from "../../openapi/operations.js";
+import { jsonSchema } from "../../openapi/document.js";
+//#region src/controlPlane/discovery/routeInput.ts
+/**
+* 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"
+};
+/**
+* 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.
+*/
+function inputOf(handlers) {
+	const properties = {};
+	const required = [];
+	for (const handler of handlers) {
+		const contract = requestContractOf(handler);
+		if (contract === void 0) continue;
+		const part = PARTS[contract.target];
+		if (part === void 0) continue;
+		properties[part] = jsonSchema(contract.schema, "input");
+		const absent = part === "query" ? {} : void 0;
+		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.
+*/
+function routeInputs(groups) {
+	const inputs = /* @__PURE__ */ new Map();
+	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.
+*/
+function withRouteInputs(declarations, inputs) {
+	if (inputs === void 0) return [...declarations];
+	return declarations.map((declaration) => ({
+		...declaration,
+		adminRoutes: declaration.adminRoutes.map((route) => {
+			const input = inputs.get(`${route.method} ${route.path}`);
+			return input === void 0 ? route : {
+				...route,
+				input
+			};
+		})
+	}));
+}
+//#endregion
+export { inputOf, routeInputs, withRouteInputs };

package/dist/controlPlane/discovery/toolName.d.ts

@@ -0,0 +1,21 @@
+// 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 declare function controlPlaneToolName(capability: string, operation: string): string;
+//# sourceMappingURL=toolName.d.ts.map

package/dist/controlPlane/discovery/toolName.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolName.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/discovery/toolName.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAElF"}

package/dist/controlPlane/discovery/toolName.js

@@ -0,0 +1,25 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/controlPlane/discovery/toolName.ts
+/**
+* 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.
+*/
+function controlPlaneToolName(capability, operation) {
+	return `${capability}_${operation}`.toLowerCase().replace(/[^a-z0-9_-]/g, "_");
+}
+//#endregion
+export { controlPlaneToolName };

package/dist/controlPlane/erasure/attest.d.ts

@@ -0,0 +1,78 @@
+// 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, ErasurePeriodEntry } 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 declare const ERASURE_OVERDUE_AFTER_MS: number;
+/** The step a purge that has run nothing is named as having stopped at. */
+export declare const ERASURE_NOT_STARTED = "due";
+/** The rows of the deletion in force, or `null` when there is none — never deleted, or restored since. */
+export declare function deletionInForce(rows: readonly ErasureHistoryRow[]): ErasureHistoryRow[] | null;
+/** 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 declare function attest(input: AttestInput): ErasureAttestation | null;
+/** One attestation, summarized for the period read. */
+export declare function periodEntry(attestation: ErasureAttestation): ErasurePeriodEntry;
+/** The period's counts and the purges that need someone, from its entries. */
+export declare function summarize(entries: readonly ErasurePeriodEntry[]): {
+    counts: {
+        scheduled: number;
+        inProgress: number;
+        complete: number;
+        failed: number;
+        overdue: number;
+    };
+    attention: {
+        subject: {
+            type: "organization" | "user";
+            id: string;
+        };
+        state: "complete" | "failed" | "in_progress" | "scheduled";
+        overdue: boolean;
+        purgeAfter: string | null;
+        completedAt: string | null;
+        stoppedAt: string | null;
+    }[];
+};
+/** Every entry, oldest due first; a deletion recorded before #823 has no due instant and sorts last. */
+export declare function byDue(entries: readonly ErasurePeriodEntry[]): ErasurePeriodEntry[];
+//# sourceMappingURL=attest.d.ts.map

package/dist/controlPlane/erasure/attest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attest.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/erasure/attest.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACvF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EACV,kBAAkB,EAElB,kBAAkB,EAGnB,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,6FAA6F;AAC7F,eAAO,MAAM,wBAAwB,QAAiB,CAAC;AAEvD,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAEzC,0GAA0G;AAC1G,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,iBAAiB,EAAE,GAAG,iBAAiB,EAAE,GAAG,IAAI,CAQ9F;AAwBD,wDAAwD;AACxD,MAAM,WAAW,WAAW;IAC1B,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,cAAc;IACd,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC5C,uEAAuE;IACvE,QAAQ,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,GAAG,IAAI,CAAC;IACpD,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,WAAW;IACX,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;CACpB;AAED,6EAA6E;AAC7E,wBAAgB,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,kBAAkB,GAAG,IAAI,CA8DpE;AAiBD,uDAAuD;AACvD,wBAAgB,WAAW,CAAC,WAAW,EAAE,kBAAkB,GAAG,kBAAkB,CAS/E;AAED,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE;;;;;;;;;;;;;;;;;;;EAW/D;AAED,wGAAwG;AACxG,wBAAgB,KAAK,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,GAAG,kBAAkB,EAAE,CAIlF"}