@pithy-sh/core 0.13.0 → 0.15.0

package/src/mcp/tools.ts

@@ -0,0 +1,220 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { AdminOperation } from "../controlPlane/discovery/adminRoute";
+import { inputOf } from "../controlPlane/discovery/routeInput";
+import { controlPlaneToolName } from "../controlPlane/discovery/toolName";
+import { ValidationError } from "../error/pithyError";
+import { type RouteSpec, routeSpecOf, type ToolEffect } from "../http/routeSpec";
+import type { RouteGroup } from "../openapi/document";
+import { isMiddlewareOnly, operationsOf } from "../openapi/operations";
+import { KIND_SENTENCES, kindAnnotations, type ToolAnnotations } from "./annotations";
+
+/**
+ * The app's own MCP tools, read off the composed router (`docs/AGENT-ACCESS.md` §4.1, §5).
+ *
+ * **The route declarations are already a tool list.** A route that opts in with `describeRoute({ tool })` carries
+ * everything a tool definition needs: the `summary` an agent chooses on, a `description` for what the schemas do not
+ * say, the `power` that gates it, the `scopes` a caller must carry, and an `operation` that names it. Its input is
+ * the route's own `validate(...)` schemas, in the same `{ path, query, body }` shape the control-plane server's tools
+ * take. Nothing is written twice: a route that changes its body, its power or its summary changes its tool on the
+ * same commit.
+ *
+ * **A tool inherits its route's power. That is the whole mapping**, and there is no tool-to-role table to maintain.
+ */
+
+/** One route, as a tool. */
+export interface AppTool {
+  /** `<capability>_<operation>`, through the control-plane server's normalizer. */
+  readonly name: string;
+  /** The capability that registered the route — the unit of consent. */
+  readonly capability: string;
+  /** The route's declared operation. */
+  readonly operation: string;
+  /** The HTTP method a call dispatches with. */
+  readonly method: string;
+  /** The mounted path a call dispatches to, Hono's spelling. */
+  readonly path: string;
+  /** The route's summary, in its capability's own words. What the consent screen lists. */
+  readonly summary: string;
+  /** What an agent reads: the summary, the route's description, and its effect said aloud. */
+  readonly description: string;
+  /** The route's input as JSON Schema. */
+  readonly inputSchema: Record<string, unknown>;
+  /** What the tool does beyond reading, or `null` for a read. */
+  readonly effect: ToolEffect | null;
+  /** The MCP annotations its effect sets. */
+  readonly annotations: ToolAnnotations;
+  /** The power the caller's role must hold, or `undefined` when the route declares none. */
+  readonly power: string | undefined;
+  /** The attestation scopes a caller must carry, from `describeRoute({ scopes })`. */
+  readonly scopes: readonly string[];
+}
+
+/** What each effect says in a tool's description and on the consent screen. One sentence each. */
+export const EFFECT_SENTENCES: Readonly<Record<ToolEffect, string>> = {
+  writes: KIND_SENTENCES.writes,
+  sends: KIND_SENTENCES.sends,
+  charges: KIND_SENTENCES.charges,
+  deletes: KIND_SENTENCES.deletes,
+};
+
+/** The MCP annotations for an effect. `null` is a read. */
+export function toolAnnotations(effect: ToolEffect | null): ToolAnnotations {
+  return kindAnnotations(effect ?? "reads");
+}
+
+/** One described route that opted in, before it is a tool. */
+interface Declared {
+  readonly capability: string;
+  readonly method: string;
+  readonly path: string;
+  readonly spec: RouteSpec;
+  readonly handlers: readonly unknown[];
+}
+
+/** Every described route in these groups, with the method it is mounted under. */
+function described(groups: readonly RouteGroup[]): Declared[] {
+  return groups.flatMap((group) =>
+    operationsOf(group.routes)
+      .filter((operation) => !isMiddlewareOnly(operation))
+      .flatMap((operation) => {
+        const spec = operation.handlers.map(routeSpecOf).find((candidate) => candidate !== undefined);
+        return spec === undefined
+          ? []
+          : [
+              {
+                capability: group.tag,
+                method: operation.method.toUpperCase(),
+                path: operation.path,
+                spec,
+                handlers: operation.handlers,
+              },
+            ];
+      }),
+  );
+}
+
+function refuse(message: string, detail: string): never {
+  throw new ValidationError({
+    message,
+    action:
+      "Fix the route's describeRoute({ operation, tool }). A GET opts in with `tool: true`; any other method declares `tool: { effect }`.",
+    detail,
+  });
+}
+
+/**
+ * Refuse a composition whose tool declarations are wrong, naming the route.
+ *
+ * **This is where "it does not compile" is enforced.** `describeRoute` cannot see the method it is mounted under, so
+ * a `POST` saying `tool: true` type-checks; `createBackend` calls this at assembly, so the Worker refuses to boot
+ * and the kit's own composition fails its tests. Five checks: a non-`GET` opting in without an effect, a `GET`
+ * declaring one, a tool with no operation, an operation outside the published alphabet, and two routes sharing an
+ * operation within a capability — or two capabilities whose names normalize to one tool.
+ */
+export function assertToolDeclarations(groups: readonly RouteGroup[]): void {
+  const operations = new Map<string, string>();
+  const names = new Map<string, string>();
+  for (const route of described(groups)) {
+    const where = `${route.method} ${route.path}`;
+    const { operation, tool } = route.spec;
+    if (operation !== undefined) {
+      if (!AdminOperation.safeParse(operation).success) {
+        refuse(
+          `The operation "${operation}" on ${where} is not a valid name.`,
+          `capability ${route.capability} route ${where} declares operation "${operation}"; an operation is lowercase words joined by ".", "_" or "-"`,
+        );
+      }
+      const key = `${route.capability} ${operation}`;
+      const earlier = operations.get(key);
+      if (earlier !== undefined) {
+        refuse(
+          `Two ${route.capability} routes declare the operation "${operation}".`,
+          `${earlier} and ${where} both declare operation "${operation}" in capability ${route.capability}`,
+        );
+      }
+      operations.set(key, where);
+    }
+    if (tool === undefined) continue;
+    if (operation === undefined) {
+      refuse(
+        `${where} opts in as a tool with no operation.`,
+        `capability ${route.capability} route ${where} declares tool but no operation, so its tool has no name`,
+      );
+    }
+    if (route.method !== "GET" && tool === true) {
+      refuse(
+        `${where} opts in as a tool without an effect.`,
+        `capability ${route.capability} route ${where} is not a GET, so it must declare tool: { effect } (writes, sends, charges or deletes)`,
+      );
+    }
+    if (route.method === "GET" && tool !== true) {
+      refuse(
+        `${where} is a read and declares an effect.`,
+        `capability ${route.capability} route ${where} is a GET; a GET opts in with tool: true`,
+      );
+    }
+    const name = controlPlaneToolName(route.capability, operation);
+    const clash = names.get(name);
+    if (clash !== undefined) {
+      refuse(`Two routes are both the tool ${name}.`, `${clash} and ${where} both normalize to the tool name ${name}`);
+    }
+    names.set(name, where);
+  }
+}
+
+/** The description an agent reads: the summary, the route's own description, and its effect. */
+function descriptionOf(spec: RouteSpec, effect: ToolEffect | null): string {
+  return [spec.summary, spec.description, effect === null ? undefined : EFFECT_SENTENCES[effect]]
+    .filter((part): part is string => part !== undefined && part.length > 0)
+    .join(" ");
+}
+
+/** Every tool these groups declare, in registration order. Refuses a wrong declaration first. */
+export function appTools(groups: readonly RouteGroup[]): AppTool[] {
+  assertToolDeclarations(groups);
+  return described(groups).flatMap((route): AppTool[] => {
+    const { spec } = route;
+    if (spec.tool === undefined || spec.operation === undefined) return [];
+    const effect = spec.tool === true ? null : spec.tool.effect;
+    return [
+      {
+        name: controlPlaneToolName(route.capability, spec.operation),
+        capability: route.capability,
+        operation: spec.operation,
+        method: route.method,
+        path: route.path,
+        summary: spec.summary,
+        description: descriptionOf(spec, effect),
+        inputSchema: inputOf(route.handlers),
+        effect,
+        annotations: toolAnnotations(effect),
+        power: spec.power,
+        scopes: spec.scopes ?? [],
+      },
+    ];
+  });
+}
+
+/** What a caller holds, for {@link offeredTools}. */
+export interface ToolCaller {
+  /** Whether the caller's role holds a power, or `null` when no organization is in force — nothing is held. */
+  readonly roleAllows: ((power: string) => boolean) | null;
+  /** The attestation scopes the caller carries. */
+  readonly scopes: readonly string[];
+}
+
+/** Whether this caller may call this tool, by exactly the checks its route makes. */
+export function mayCall(tool: AppTool, caller: ToolCaller): boolean {
+  if (tool.power !== undefined && (caller.roleAllows === null || !caller.roleAllows(tool.power))) return false;
+  return tool.scopes.every((scope) => caller.scopes.includes(scope));
+}
+
+/**
+ * The tools this caller may call. **A tool a role withholds is absent, not locked**: offering it discloses that it
+ * exists and spends a call to learn what the answer would be (`docs/AGENT-ACCESS.md` §4.1).
+ */
+export function offeredTools(tools: readonly AppTool[], caller: ToolCaller): AppTool[] {
+  return tools.filter((tool) => mayCall(tool, caller));
+}

package/src/openapi/document.ts

@@ -9,6 +9,7 @@ import { pathParams } from "../http/routeContract";
 import { type DocumentedMethod, type RouteResponse, type RouteSpec, routeSpecOf } from "../http/routeSpec";
 import { type RequestContract, requestContractOf } from "../http/validation";
 import type { VerificationStrategy } from "../http/verification";
+import { isMiddlewareOnly, type Operation, operationsOf } from "./operations";
 
 /**
  * **The OpenAPI contract, read off a composed app.**
@@ -76,7 +77,8 @@ const SECURITY_SCHEMES: Record<string, unknown> = {
   bearer: {
     type: "http",
     scheme: "bearer",
-    description: "A short-lived access token from `@pithy-sh/auth`, sent as `Authorization: Bearer <token>`.",
+    description:
+      "A session token from `@pithy-sh/auth`, sent as `Authorization: Bearer <token>`: the one sign-in returns, then the `refreshToken` each `/token/rotate` answers with. The rotation's `accessToken` is a JWT for services outside the Worker, and these routes refuse it.",
   },
   session: {
     type: "apiKey",
@@ -134,33 +136,6 @@ export function jsonSchema(schema: z.ZodType, io: "input" | "output"): JsonSchem
   return rest;
 }
 
-/** One route's handlers, grouped by method and path the way Hono stores them: one entry per handler. */
-interface Operation {
-  readonly method: string;
-  readonly path: string;
-  readonly handlers: unknown[];
-}
-
-function operationsOf(routes: readonly RouterRoute[]): Operation[] {
-  const byKey = new Map<string, Operation>();
-  for (const route of routes) {
-    const key = `${route.method} ${route.path}`;
-    const entry = byKey.get(key) ?? { method: route.method, path: route.path, handlers: [] };
-    entry.handlers.push(route.handler);
-    byKey.set(key, entry);
-  }
-  return [...byKey.values()];
-}
-
-/**
- * An `ALL` entry with no spec is `app.use` — middleware, not a route — because Hono records both as
- * `ALL`. An `app.all` route that forgot its `describeRoute` is therefore invisible to the coverage
- * check, which is the one blind spot here; the kit has one such route and it is described.
- */
-function isMiddlewareOnly(operation: Operation): boolean {
-  return operation.method === "ALL" && !operation.handlers.some((handler) => routeSpecOf(handler));
-}
-
 /** Every route in these groups that registered no `describeRoute`. Empty is the contract being met. */
 export function undescribedRoutes(groups: readonly RouteGroup[]): UndescribedRoute[] {
   return groups.flatMap((group) =>
@@ -274,6 +249,11 @@ function operationOf(tag: string, method: string, operation: Operation, spec: Ro
     responses,
     ...(strategies.length === 0 ? {} : { security, "x-pithy-verification": strategies }),
     ...(spec.scopes === undefined || spec.scopes.length === 0 ? {} : { "x-pithy-scopes": spec.scopes }),
+    // What the route declared for the app's MCP endpoint: the power its gate installs, its permanent name,
+    // and its effect when it is a tool. A client generated from the contract reads the gate it will meet.
+    ...(spec.power === undefined ? {} : { "x-pithy-power": spec.power }),
+    ...(spec.operation === undefined ? {} : { "x-pithy-operation": spec.operation }),
+    ...(spec.tool === undefined ? {} : { "x-pithy-tool": spec.tool === true ? { effect: null } : spec.tool }),
   };
 }
 

package/src/openapi/operations.ts

@@ -0,0 +1,62 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { type RouteSpec, routeSpecOf } from "../http/routeSpec";
+import type { RouteGroup, RouterRoute } from "./document";
+
+/**
+ * The composed route table as operations: one per method and path, with the spec its `describeRoute` declared.
+ *
+ * Hono keeps one entry per handler, so a route with a `describeRoute` ahead of its handler appears twice in
+ * `app.routes`. Two readers need the grouped view: the OpenAPI document, which turns each operation into a path
+ * item, and the evidence pack (#821), which counts how every route verifies its caller. They group the same way
+ * because they group here, and the pack never loads the JSON Schema conversion the document needs.
+ */
+
+/** One route's handlers, grouped by method and path the way Hono stores them: one entry per handler. */
+export interface Operation {
+  readonly method: string;
+  readonly path: string;
+  readonly handlers: unknown[];
+}
+
+/** Group a route table into operations, in registration order. */
+export function operationsOf(routes: readonly RouterRoute[]): Operation[] {
+  const byKey = new Map<string, Operation>();
+  for (const route of routes) {
+    const key = `${route.method} ${route.path}`;
+    const entry = byKey.get(key) ?? { method: route.method, path: route.path, handlers: [] };
+    entry.handlers.push(route.handler);
+    byKey.set(key, entry);
+  }
+  return [...byKey.values()];
+}
+
+/**
+ * An `ALL` entry with no spec is `app.use` — middleware, not a route — because Hono records both as
+ * `ALL`. An `app.all` route that forgot its `describeRoute` is therefore invisible to the coverage
+ * check, which is the one blind spot here; the kit has one such route and it is described.
+ */
+export function isMiddlewareOnly(operation: Operation): boolean {
+  return operation.method === "ALL" && !operation.handlers.some((handler) => routeSpecOf(handler));
+}
+
+/** One route, and the spec it declared — `undefined` for a route that registered no `describeRoute`. */
+export interface DescribedOperation {
+  readonly method: string;
+  readonly path: string;
+  readonly spec: RouteSpec | undefined;
+}
+
+/** Every route in these groups, middleware left out, each with the spec it declared or `undefined`. */
+export function describedOperations(groups: readonly RouteGroup[]): DescribedOperation[] {
+  return groups.flatMap((group) =>
+    operationsOf(group.routes)
+      .filter((operation) => !isMiddlewareOnly(operation))
+      .map((operation) => ({
+        method: operation.method,
+        path: operation.path,
+        spec: operation.handlers.map(routeSpecOf).find((candidate) => candidate !== undefined),
+      })),
+  );
+}

package/src/presence/channel.ts

@@ -0,0 +1,46 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { SocketChannel } from "../http/socket";
+import { type PresenceDeclaration, presenceSocketPath } from "./declaration";
+import {
+  PRESENCE_ROOM_VERSIONS,
+  PresenceActivityFrame,
+  PresenceJoinedFrame,
+  PresenceLeftFrame,
+  PresenceRoomErrorFrame,
+  PresenceRoomInitFrame,
+  PresenceRoomPing,
+  PresenceRoomPong,
+  PresenceSetActivityFrame,
+} from "./frames";
+import { PresenceRoomParams } from "./http/schemas";
+
+/**
+ * A capability's presence room socket, declared for the AsyncAPI contract. `defineCapability` adds it to the
+ * capability's `sockets` whenever it declares room kinds, from the same `basePath` the routes mount on, so a
+ * declared socket and a mounted one cannot be two different things.
+ */
+export function presenceRoomsSocket(capability: string, presence: PresenceDeclaration): SocketChannel {
+  return {
+    name: `${capability}PresenceRooms`,
+    path: presenceSocketPath(presence.basePath),
+    summary: `Who else has a ${capability} record open, and what they are doing, live.`,
+    description: `Mint a ticket first — \`POST /control-plane/presence/tickets\` for a management client, \`POST ${presence.basePath}/presence/tickets\` for a signed-in user — then offer \`pithy.presence.v1\` and \`pithy.ticket.<ticket>\` in \`Sec-WebSocket-Protocol\`. The ticket is the credential: single use, 60 seconds, this room only. The room sends \`init\` first, then \`joined\`, \`left\` and \`activity\` as they happen. Send \`set_activity\` to announce one of the kind's declared activities, and \`ping\` as plain text to get \`pong\`. Room kinds: ${presence.rooms.map((room) => `\`${room.kind}\``).join(", ")}.`,
+    verification: "public",
+    params: PresenceRoomParams,
+    versions: PRESENCE_ROOM_VERSIONS,
+    send: [
+      { name: "init", summary: "Everyone in the room, sent once on connect.", schema: PresenceRoomInitFrame },
+      { name: "joined", summary: "Another participant joined.", schema: PresenceJoinedFrame },
+      { name: "left", summary: "Another participant left, or their socket dropped.", schema: PresenceLeftFrame },
+      { name: "activity", summary: "Another participant changed what they are doing.", schema: PresenceActivityFrame },
+      { name: "error", summary: "A frame the room could not accept.", schema: PresenceRoomErrorFrame },
+      { name: "pong", summary: "The answer to `ping`, as plain text.", text: PresenceRoomPong.value },
+    ],
+    receive: [
+      { name: "set_activity", summary: "Announce a declared activity.", schema: PresenceSetActivityFrame },
+      { name: "ping", summary: "The keepalive, as plain text.", text: PresenceRoomPing.value },
+    ],
+  };
+}

package/src/presence/declaration.ts

@@ -0,0 +1,283 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Context } from "hono";
+import type { BindingSpecInput } from "../capability/bindings";
+import type { PithyHonoEnv } from "../capability/capability";
+import { remedy } from "../cli/command";
+import { ControlPlaneScope } from "../controlPlane/scope/scope";
+import { InternalError } from "../error/pithyError";
+import { PRESENCE_PARTICIPANT_NAME_MAX } from "./frames";
+import { PresenceActivity, PresenceRoomKindName } from "./names";
+
+/**
+ * **Presence rooms: who else has a record open, live, from the adopter's own Worker.**
+ *
+ * A capability declares the room kinds it serves beside its admin routes, on {@link Capability.presence}: a
+ * name (`support.thread`), the control-plane scope that reads the record (`support:threads:read`), and the
+ * activities a participant may announce (`viewing`, `replying`). A room is one kind plus one record id, and
+ * it lives in one hibernating Durable Object, `PresenceRoom`, that holds nothing but who is in it.
+ *
+ * Joining takes a **ticket**, because a browser's `WebSocket` sets no headers and so cannot carry either the
+ * control-plane token or, cross-origin, a session cookie. A ticket is minted by one of two routes — the
+ * control-plane one behind the kind's scope, or the capability's own session one behind its own read
+ * permission — and presented once, in the subprotocol offer, within 60 seconds.
+ *
+ * **Presence adds no scope of its own.** Anyone who may read a record may see who else has it open, so the
+ * room kind names the scope that already reads the record and the session gate the capability already has.
+ *
+ * This module is pure: zod, types and constants. The routes are in `./http/routes.ts`, the Durable Object in
+ * `./durableObject.ts`, and nothing here imports either.
+ */
+
+/** The Durable Object binding every room lives behind. One namespace for every room kind in a Worker. */
+export const PRESENCE_ROOMS_BINDING = "PRESENCE_ROOMS";
+
+/** The class that backs {@link PRESENCE_ROOMS_BINDING}, and the module the Worker's entry re-exports it from. */
+export const PRESENCE_ROOM_CLASS = "PresenceRoom";
+
+/** Its own module, never a package entry point, so `pithy.config.ts` can load the capability in Node. */
+export const PRESENCE_ROOM_MODULE = "@pithy-sh/core/src/presence/durableObject";
+
+/**
+ * The binding a capability that declares room kinds requires. `defineCapability` adds it, so a capability
+ * never spells it; a kit capability's `pithy.manifest.json` names it exactly as written here, which is what
+ * `pithy add` and `pithy upgrade` wire through the Durable Object path (#428).
+ */
+export const PRESENCE_ROOMS_BINDING_SPEC: BindingSpecInput = {
+  type: "durable_object",
+  name: PRESENCE_ROOMS_BINDING,
+  className: PRESENCE_ROOM_CLASS,
+  classModule: PRESENCE_ROOM_MODULE,
+};
+
+/**
+ * The secret tickets are signed with: one per Worker environment, generated, never typed. A capability that
+ * declares room kinds declares this name in its `@pithy-sh/secrets` registry with {@link
+ * PRESENCE_TICKET_KEY_ENTRY} and reads it through `secretsStore`, and its manifest lists it under
+ * `devSecrets` so `pithy add` mints the local value. The name is the join key, so every capability that
+ * declares rooms in one Worker signs and verifies with the one key.
+ */
+export const PRESENCE_TICKET_KEY_SECRET = "presence-ticket-key";
+
+/**
+ * The registry entry for {@link PRESENCE_TICKET_KEY_SECRET}, in the shape `defineSecretRegistry` takes. Its
+ * value is arbitrary — nothing outside the Worker has to agree with it — so it is `devValue: "random"`, and
+ * rotatable because {@link PresenceTicketKey} accepts every version still honored.
+ */
+export const PRESENCE_TICKET_KEY_ENTRY = {
+  backend: "d1",
+  scope: "environment",
+  rotatable: true,
+  valueType: "text",
+  devValue: "random",
+} as const;
+
+/** How long a minted ticket is honored, in seconds. Long enough to open a socket, short enough to be useless later. */
+export const PRESENCE_TICKET_TTL_SECONDS = 60;
+
+/** The participant cap a room kind gets when it declares none. */
+export const DEFAULT_PRESENCE_PARTICIPANTS = 25;
+
+/** The most participants any room kind may declare. A room is one Durable Object, and every frame fans out to all of them. */
+export const MAX_PRESENCE_PARTICIPANTS = 100;
+
+/** The largest frame a room accepts from a client, in bytes. The one frame a client sends is an activity name. */
+export const PRESENCE_MAX_FRAME_BYTES = 1024;
+
+/** The most activities one room kind may declare. */
+export const MAX_PRESENCE_ACTIVITIES = 16;
+
+/** What the session gate grants: the participant's display name, or the user id when it names none. */
+export interface PresenceSessionGrant {
+  /**
+   * How other participants see this user. Trimmed and cut to 80 characters; the user id when it is missing
+   * or blank, so a gate can pass a stored display name through as it is.
+   */
+  readonly name?: string;
+}
+
+/**
+ * The name a session participant joins under: the gate's, trimmed and cut to fit, or the user id when the
+ * gate names none or a blank one. Always a name a ticket accepts — a display name is the user's own data, and
+ * one too long or empty must not lock them out of every room.
+ */
+export function sessionParticipantName(name: string | undefined, userId: string): string {
+  return fitName(name ?? "") || fitName(userId) || "Participant";
+}
+
+/** Trim, then cut to {@link PRESENCE_PARTICIPANT_NAME_MAX} code units without splitting a character. */
+function fitName(raw: string): string {
+  let fitted = "";
+  for (const char of raw.trim()) {
+    if (fitted.length + char.length > PRESENCE_PARTICIPANT_NAME_MAX) break;
+    fitted += char;
+  }
+  return fitted.trim();
+}
+
+/**
+ * The capability's own permission for reading one record, for a signed-in user of the app. Answer a grant
+ * to admit, `null` to refuse. `c.var.auth` is already set when it runs; it is the capability's job to say
+ * whether that user may read `recordId`, exactly as its own read route would.
+ */
+export type PresenceSessionGate = (
+  c: Context<PithyHonoEnv>,
+  recordId: string,
+) => PresenceSessionGrant | null | Promise<PresenceSessionGrant | null>;
+
+/** One room kind a capability serves. */
+export interface PresenceRoomKind {
+  /** The kind's name — `support.thread`. Its first segment must be the declaring capability's name. */
+  readonly kind: string;
+  /** The control-plane scope that reads the record. A management client joins with exactly this scope. */
+  readonly scope: string;
+  /** The activities a participant may announce. The first is what a participant starts as. */
+  readonly activities: readonly [string, ...string[]];
+  /** The participant cap. Defaults to {@link DEFAULT_PRESENCE_PARTICIPANTS}, at most {@link MAX_PRESENCE_PARTICIPANTS}. */
+  readonly maxParticipants?: number;
+  /**
+   * Who of the app's own signed-in users may join: the capability's read permission for the record. Absent,
+   * the kind admits management clients only and the session ticket route refuses it.
+   */
+  readonly session?: PresenceSessionGate;
+}
+
+/**
+ * The secret tickets are signed with: the value, every value still honored during a rotation (the first
+ * signs), or a resolver reading it from the Worker env per request — which is the only form a secret read
+ * through `@pithy-sh/secrets` can take, since `env` exists only per request.
+ */
+export type PresenceTicketKey =
+  | string
+  | readonly string[]
+  | ((env: Record<string, unknown>) => string | readonly string[] | Promise<string | readonly string[]>);
+
+/** A capability's presence declaration — see {@link Capability.presence}. */
+export interface PresenceDeclaration {
+  /**
+   * Where this capability mounts its presence routes: `{basePath}/presence/tickets` and
+   * `{basePath}/presence/rooms/:kind/:recordId`. The capability's own resolved `basePath`, never its default.
+   */
+  readonly basePath: string;
+  /** The room kinds it serves. */
+  readonly rooms: readonly PresenceRoomKind[];
+  /** The ticket signing key — {@link PRESENCE_TICKET_KEY_SECRET}, read through the capability's own secrets reader. */
+  readonly ticketKey: PresenceTicketKey;
+}
+
+/** The session ticket route, under a capability's base path. */
+export function presenceTicketPath(basePath: string): string {
+  return `${basePath}/presence/tickets`;
+}
+
+/** The socket route, under a capability's base path, as Hono registers it. */
+export function presenceSocketPath(basePath: string): string {
+  return `${basePath}/presence/rooms/:kind/:recordId`;
+}
+
+/** The socket path for one room, ready to open. */
+export function presenceRoomPath(basePath: string, kind: string, recordId: string): string {
+  return `${basePath}/presence/rooms/${encodeURIComponent(kind)}/${encodeURIComponent(recordId)}`;
+}
+
+/** The participant cap a room kind runs with. */
+export function participantCap(room: PresenceRoomKind): number {
+  return room.maxParticipants ?? DEFAULT_PRESENCE_PARTICIPANTS;
+}
+
+/** One of the capability's own admin routes, as far as the scope rule reads it: its method and the scope it requires. */
+export interface PresenceGatingRoute {
+  method: string;
+  scope: string | null;
+}
+
+/**
+ * Refuse a declaration no room could be served from, where it is written and naming the capability: a kind
+ * outside the capability's own name, a duplicate, a scope that is not one, an activity that is not one, a
+ * cap out of range. A declaration that reached a request would be refused there, by a caller, in a way only
+ * the operator can fix.
+ *
+ * **A room kind's scope is one the capability's own admin routes already require, and only `GET`s require
+ * it** — compared against `adminRoutes`, the same artifact `capabilityHealthSources` polices health keys
+ * with, and for the same reason. `pithy dashboard connect` offers the scopes it reads off `adminRoutes`, so
+ * a scope no route requires — one of presence's own, a near-miss, another capability's — is never offered
+ * and never in the default grant, and the room is unjoinable from every management client with no error to
+ * say why. And a scope that also gates a write would make joining a room need a mutation grant, which
+ * inverts the read rule `grant.ts` applies.
+ */
+export function assertPresenceDeclaration(
+  capability: string,
+  presence: PresenceDeclaration,
+  adminRoutes: readonly PresenceGatingRoute[],
+): void {
+  const refuse = (detail: string): never => {
+    throw new InternalError({
+      message: `${capability} declares presence rooms this Worker cannot serve.`,
+      action: `Fix the presence declaration on the ${capability} capability.`,
+      detail,
+    });
+  };
+  if (!presence.basePath.startsWith("/") || presence.basePath.endsWith("/")) {
+    refuse(`presence basePath "${presence.basePath}" must start with "/" and not end with one`);
+  }
+  const seen = new Set<string>();
+  for (const room of presence.rooms) {
+    if (!PresenceRoomKindName.safeParse(room.kind).success) refuse(`room kind "${room.kind}" is not a kind name`);
+    if (!room.kind.startsWith(`${capability}.`)) {
+      refuse(
+        `room kind "${room.kind}" must start with "${capability}." — a capability declares kinds under its own name`,
+      );
+    }
+    if (seen.has(room.kind)) refuse(`room kind "${room.kind}" is declared twice`);
+    seen.add(room.kind);
+    if (!ControlPlaneScope.safeParse(room.scope).success)
+      refuse(`room kind "${room.kind}" scope "${room.scope}" is not a scope`);
+    // Inherited, never invented: the scope a room joins with is one this capability already gates a read with.
+    const gating = adminRoutes.filter((route) => route.scope === room.scope);
+    if (gating.length === 0) {
+      refuse(
+        `room kind "${room.kind}" scope "${room.scope}": no admin route of ${capability} requires it, so no grant would ever offer it`,
+      );
+    }
+    const write = gating.find((route) => route.method !== "GET");
+    if (write) {
+      refuse(
+        `room kind "${room.kind}" scope "${room.scope}" gates a ${write.method}; a room joins with a read scope, one only GET routes require`,
+      );
+    }
+    if (room.activities.length === 0 || room.activities.length > MAX_PRESENCE_ACTIVITIES) {
+      refuse(
+        `room kind "${room.kind}" declares ${room.activities.length} activities; it needs 1 to ${MAX_PRESENCE_ACTIVITIES}`,
+      );
+    }
+    if (new Set(room.activities).size !== room.activities.length) {
+      refuse(`room kind "${room.kind}" declares an activity twice`);
+    }
+    for (const activity of room.activities) {
+      if (!PresenceActivity.safeParse(activity).success)
+        refuse(`room kind "${room.kind}" activity "${activity}" is not one word`);
+    }
+    const cap = participantCap(room);
+    if (!Number.isInteger(cap) || cap < 1 || cap > MAX_PRESENCE_PARTICIPANTS) {
+      refuse(`room kind "${room.kind}" maxParticipants ${cap} is outside 1 to ${MAX_PRESENCE_PARTICIPANTS}`);
+    }
+  }
+}
+
+/**
+ * The ticket signing keys, resolved and non-empty — the first signs, every one verifies. A blank entry is
+ * dropped rather than tried, since WebCrypto refuses a zero-length key with an error that names nothing.
+ */
+export async function resolveTicketKeys(key: PresenceTicketKey, env: Record<string, unknown>): Promise<string[]> {
+  const resolved = typeof key === "function" ? await key(env) : key;
+  const keys = (typeof resolved === "string" ? [resolved] : [...resolved]).filter((value) => value.length > 0);
+  if (keys.length === 0) {
+    throw new InternalError({
+      message: "Presence is not available right now.",
+      action: `Set ${PRESENCE_TICKET_KEY_SECRET}. ${remedy("secrets provision", {}, { runtime: true }).say((command) => `${command} mints it for each environment.`)}`,
+      detail: `${PRESENCE_TICKET_KEY_SECRET} resolved to no usable value`,
+    });
+  }
+  return keys;
+}