@pithy-sh/core 0.12.0 → 0.14.0

package/src/error/payload.ts

@@ -213,6 +213,20 @@ const AuthAccountDeletedPublic = z
   })
   .describe("The account is deleted and awaiting its purge (403).");
 
+const AuthHandoffInvalidPublic = z
+  .object({
+    code: z
+      .literal("auth/handoff_invalid")
+      .describe(
+        "The one-time code a native app trades for its session after a redirect sign-in is spent, expired, was never issued, or came with the wrong verifier. One code for all four, so the answer says nothing about which codes exist or why a trade failed. The remedy is the same for each: sign in again.",
+      ),
+    status: z
+      .literal(400)
+      .describe("Bad Request — the code presented cannot be traded. Not 401: no credential was presented to refuse."),
+    ...publicFields,
+  })
+  .describe("A sign-in handoff code that is spent, expired, unknown or presented with the wrong verifier (400).");
+
 const NotFoundPublic = z
   .object({
     code: z.literal("core/not_found").describe("The requested resource does not exist."),
@@ -339,6 +353,30 @@ const WebhookUnverifiedPublic = z
   })
   .describe("An inbound webhook failed its signature check (401).");
 
+// --- @pithy-sh/core: presence rooms ---
+
+const PresenceTicketInvalidPublic = z
+  .object({
+    code: z
+      .literal("core/presence_ticket_invalid")
+      .describe(
+        "A presence socket was opened without a ticket this Worker accepts. Deliberately one code for every failing step — no ticket, a bad signature, an expired one, one already spent, or one minted for another room — so a caller holding a stolen ticket learns nothing about which check it tripped. `detail` names the step for the log, and the codec strips it.",
+      ),
+    status: z.literal(401).describe("Unauthorized — mint a fresh ticket and open the socket with it."),
+    ...publicFields,
+  })
+  .describe("A presence socket upgrade carried no valid ticket (401).");
+
+const PresenceRoomFullPublic = z
+  .object({
+    code: z
+      .literal("core/presence_room_full")
+      .describe("A presence room already holds as many participants as its room kind allows."),
+    status: z.literal(409).describe("Conflict — the room is at its participant cap. Try again when someone leaves."),
+    ...publicFields,
+  })
+  .describe("A presence room is at its participant cap (409).");
+
 // --- @pithy-sh/cloudflare: out-of-Worker CF REST client codes ---
 
 const CloudflareNotConfiguredPublic = z
@@ -855,6 +893,42 @@ const LedgerInvalidAmountPublic = z
   })
   .describe("An amount is not a positive integer (400).");
 
+const LedgerEntryNotFoundPublic = z
+  .object({
+    code: z
+      .literal("ledger/entry_not_found")
+      .describe(
+        "No ledger entry with that reference exists on the account named. An entry on another account is answered the same way, so a reversal can never reach past the account its path names.",
+      ),
+    status: z.literal(404).describe("Not Found."),
+    ...publicFields,
+  })
+  .describe("A referenced ledger entry does not exist on that account (404).");
+
+const LedgerEntryNotReversiblePublic = z
+  .object({
+    code: z
+      .literal("ledger/entry_not_reversible")
+      .describe(
+        "Only a credit or a debit reverses, and never one that is itself a reversal. A hold has release; a capture spends escrow and a transfer touches a second account, so both are refused. `params.kind` names the entry's kind, and `params.reverses` the entry a reversal reversed. Nothing was written.",
+      ),
+    status: z.literal(409).describe("Conflict — the entry's kind does not reverse."),
+    ...publicFields,
+  })
+  .describe("A ledger entry of a kind that does not reverse (409).");
+
+const LedgerRefConflictPublic = z
+  .object({
+    code: z
+      .literal("ledger/ref_conflict")
+      .describe(
+        "The ref a control-plane write would be written under is already held by a different entry, so the write cannot be recorded and is not a replay either: a credit's or a debit's key already used for another account, the other act, another amount or a hold, or the derived ref of a reversal or a hold's resolution held by an unrelated entry. Nothing moved; the entry stays unreversed, or the hold stays open.",
+      ),
+    status: z.literal(409).describe("Conflict — the ref belongs to another entry."),
+    ...publicFields,
+  })
+  .describe("A write whose ref another entry already holds (409).");
+
 // --- @pithy-sh/rating: skill-rating + experience tracker codes ---
 
 const RatingUnknownAlgorithmPublic = z
@@ -921,6 +995,96 @@ const RatingRecordForbiddenPublic = z
   })
   .describe("The caller lacks the scope to record a rated outcome (403).");
 
+// --- @pithy-sh/consent: purposes, grants and withdrawals ---
+
+const ConsentUnknownPurposePublic = z
+  .object({
+    code: z
+      .literal("consent/unknown_purpose")
+      .describe("No consent purpose with that id is declared by a composed capability or in `consent({ purposes })`."),
+    status: z.literal(404).describe("Not Found."),
+    ...publicFields,
+  })
+  .describe("A consent purpose that is not declared (404).");
+
+const ConsentStaleNoticePublic = z
+  .object({
+    code: z
+      .literal("consent/stale_notice")
+      .describe(
+        "The grant names a notice version that is not the purpose's current one. A person agrees to the notice in force, so the screen showing an older one has to be reloaded.",
+      ),
+    status: z.literal(409).describe("Conflict — the notice has moved on."),
+    ...publicFields,
+  })
+  .describe("A grant against a notice version that is not current (409).");
+
+const ConsentMethodBelowMinimumPublic = z
+  .object({
+    code: z
+      .literal("consent/method_below_minimum")
+      .describe(
+        "The grant was given by a method below the purpose's minimum — a click where the purpose needs a typed name, a drawn signature or a provider's envelope.",
+      ),
+    status: z.literal(400).describe("Bad Request — the method is below the purpose's minimum."),
+    ...publicFields,
+  })
+  .describe("A grant below the purpose's minimum method (400).");
+
+const ConsentWithdrawalBelowGrantPublic = z
+  .object({
+    code: z
+      .literal("consent/withdrawal_below_grant")
+      .describe(
+        "The purpose requires a withdrawal at least at the grade of the grant it withdraws, as a HIPAA revocation must be in writing, and this one is below it.",
+      ),
+    status: z.literal(400).describe("Bad Request — the withdrawal is below the grant's method."),
+    ...publicFields,
+  })
+  .describe("A withdrawal below the grade its purpose requires (400).");
+
+const ConsentEvidenceMissingPublic = z
+  .object({
+    code: z
+      .literal("consent/evidence_missing")
+      .describe(
+        "The method names evidence the request did not carry: a typed name for `typed`, a drawn image for `drawn`, a provider and envelope for `provider`, or the document a signed grant is given against.",
+      ),
+    status: z.literal(400).describe("Bad Request — the evidence for the method is missing."),
+    ...publicFields,
+  })
+  .describe("A grant or withdrawal missing the evidence its method needs (400).");
+
+const ConsentExpiryPassedPublic = z
+  .object({
+    code: z
+      .literal("consent/expiry_passed")
+      .describe("The grant's expiry is not in the future, so it would answer no from the moment it was recorded."),
+    status: z.literal(400).describe("Bad Request — the expiry has already passed."),
+    ...publicFields,
+  })
+  .describe("A grant whose expiry has already passed (400).");
+
+const ConsentDocumentNotFoundPublic = z
+  .object({
+    code: z.literal("consent/document_not_found").describe("No signed document with that content hash is kept."),
+    status: z.literal(404).describe("Not Found."),
+    ...publicFields,
+  })
+  .describe("A signed document that is not kept (404).");
+
+const ConsentEvidenceStoreMissingPublic = z
+  .object({
+    code: z
+      .literal("consent/evidence_store_missing")
+      .describe(
+        "A drawn signature or a provider's certificate is stored in R2, and the Worker has no `CONSENT_EVIDENCE` bucket bound. A binding we never got, so the answer is in this Worker's wiring.",
+      ),
+    status: z.literal(500).describe("Internal Server Error — the evidence bucket is not bound."),
+    ...publicFields,
+  })
+  .describe("The evidence bucket is not bound (500).");
+
 // --- @pithy-sh/matchmaking: pairing + presence capability codes ---
 
 const MatchmakingRoomNotFoundPublic = z
@@ -1525,6 +1689,54 @@ const OrganizationNominationInvalidPublic = z
   })
   .describe("No standing ownership offer this caller may accept (400).");
 
+const OrganizationLastOwnerPublic = z
+  .object({
+    code: z
+      .literal("organization/last_owner")
+      .describe(
+        "An operator write would leave the account with nobody holding the role a transfer of ownership confers: removing or demoting its only owner. An account with no owner is the unadministrable state membership administration exists to get out of, so the way out is to force ownership onto somebody else first, which `params.ownershipRoute` names.",
+      ),
+    status: z.literal(409).describe("Conflict — an account nobody owns is not a state to arrive at."),
+    ...publicFields,
+  })
+  .describe("The last owner cannot be removed or demoted (409).");
+
+const OrganizationAlreadyMemberPublic = z
+  .object({
+    code: z
+      .literal("organization/already_member")
+      .describe(
+        "An operator tried to add somebody who already holds a membership in the account. One membership per person per organization, so this is a refusal rather than a second row — and `params.role` names the role they already hold, because the next step is a role change rather than an add.",
+      ),
+    status: z.literal(409).describe("Conflict."),
+    ...publicFields,
+  })
+  .describe("That person is already a member (409).");
+
+const OrganizationSeatLimitReachedPublic = z
+  .object({
+    code: z
+      .literal("organization/seat_limit_reached")
+      .describe(
+        "The account holds as many members as its seat limit allows, so another one would exceed it. `params.seatLimit` names the limit. An operator add may override it, and the override is recorded; an invitation accepted against a full account is refused until a seat frees.",
+      ),
+    status: z.literal(409).describe("Conflict."),
+    ...publicFields,
+  })
+  .describe("The account has no free seat (409).");
+
+const OrganizationSuspendedPublic = z
+  .object({
+    code: z
+      .literal("organization/organization_suspended")
+      .describe(
+        "The organization this request acts in is suspended by an operator, so nobody can act in it until it is reinstated (#623). The caller's own account is not affected, and their other organizations are not either. `params.suspendedUntil`, when present, is when the suspension ends by itself, ISO-8601. Not `organization/forbidden`, because no role would let them, and not `organization/not_found`, because the caller is a proved member and already knows the organization exists.",
+      ),
+    status: z.literal(403).describe("Forbidden — the organization may not be acted in, whoever asks."),
+    ...publicFields,
+  })
+  .describe("The organization is suspended (403).");
+
 // --- @pithy-sh/artifacts: Git repositories, ownership, grants and short-lived tokens ---
 
 const ArtifactsNotFoundPublic = z
@@ -1792,6 +2004,7 @@ export const KitPublicErrorPayload = z
     AuthSessionNotFreshPublic,
     AuthAccountSuspendedPublic,
     AuthAccountDeletedPublic,
+    AuthHandoffInvalidPublic,
     NotFoundPublic,
     ConflictPublic,
     RateLimitPublic,
@@ -1803,6 +2016,8 @@ export const KitPublicErrorPayload = z
     UnknownWorkflowPublic,
     WorkflowFailedPublic,
     WebhookUnverifiedPublic,
+    PresenceTicketInvalidPublic,
+    PresenceRoomFullPublic,
     CloudflareNotConfiguredPublic,
     CloudflareRequestFailedPublic,
     CloudflareInvalidResponsePublic,
@@ -1850,12 +2065,23 @@ export const KitPublicErrorPayload = z
     LedgerInsufficientFundsPublic,
     LedgerHoldNotOpenPublic,
     LedgerInvalidAmountPublic,
+    LedgerEntryNotFoundPublic,
+    LedgerEntryNotReversiblePublic,
+    LedgerRefConflictPublic,
     RatingUnknownAlgorithmPublic,
     RatingUnsupportedPlayerCountPublic,
     RatingInvalidParamsPublic,
     RatingGameNotFoundPublic,
     RatingPoolNotFoundPublic,
     RatingRecordForbiddenPublic,
+    ConsentUnknownPurposePublic,
+    ConsentStaleNoticePublic,
+    ConsentMethodBelowMinimumPublic,
+    ConsentWithdrawalBelowGrantPublic,
+    ConsentEvidenceMissingPublic,
+    ConsentExpiryPassedPublic,
+    ConsentDocumentNotFoundPublic,
+    ConsentEvidenceStoreMissingPublic,
     MatchmakingRoomNotFoundPublic,
     MatchmakingRoomFullPublic,
     MatchmakingInvalidCodePublic,
@@ -1908,6 +2134,10 @@ export const KitPublicErrorPayload = z
     OrganizationLastAdministratorPublic,
     OrganizationSlugTakenPublic,
     OrganizationNominationInvalidPublic,
+    OrganizationLastOwnerPublic,
+    OrganizationAlreadyMemberPublic,
+    OrganizationSeatLimitReachedPublic,
+    OrganizationSuspendedPublic,
     ArtifactsNotFoundPublic,
     ArtifactsForbiddenPublic,
     ArtifactsInvalidNamePublic,
@@ -1954,6 +2184,9 @@ const AuthAccountSuspended = AuthAccountSuspendedPublic.extend(internalFields).d
 const AuthAccountDeleted = AuthAccountDeletedPublic.extend(internalFields).describe(
   AuthAccountDeletedPublic.description ?? "",
 );
+const AuthHandoffInvalid = AuthHandoffInvalidPublic.extend(internalFields).describe(
+  AuthHandoffInvalidPublic.description ?? "",
+);
 const NotFound = NotFoundPublic.extend(internalFields).describe(NotFoundPublic.description ?? "");
 const Conflict = ConflictPublic.extend(internalFields).describe(ConflictPublic.description ?? "");
 const RateLimit = RateLimitPublic.extend(internalFields).describe(RateLimitPublic.description ?? "");
@@ -1971,6 +2204,12 @@ const WorkflowFailed = WorkflowFailedPublic.extend(internalFields).describe(Work
 const WebhookUnverified = WebhookUnverifiedPublic.extend(internalFields).describe(
   WebhookUnverifiedPublic.description ?? "",
 );
+const PresenceTicketInvalid = PresenceTicketInvalidPublic.extend(internalFields).describe(
+  PresenceTicketInvalidPublic.description ?? "",
+);
+const PresenceRoomFull = PresenceRoomFullPublic.extend(internalFields).describe(
+  PresenceRoomFullPublic.description ?? "",
+);
 const CloudflareNotConfigured = CloudflareNotConfiguredPublic.extend(internalFields).describe(
   CloudflareNotConfiguredPublic.description ?? "",
 );
@@ -2098,6 +2337,15 @@ const LedgerHoldNotOpen = LedgerHoldNotOpenPublic.extend(internalFields).describ
 const LedgerInvalidAmount = LedgerInvalidAmountPublic.extend(internalFields).describe(
   LedgerInvalidAmountPublic.description ?? "",
 );
+const LedgerEntryNotFound = LedgerEntryNotFoundPublic.extend(internalFields).describe(
+  LedgerEntryNotFoundPublic.description ?? "",
+);
+const LedgerEntryNotReversible = LedgerEntryNotReversiblePublic.extend(internalFields).describe(
+  LedgerEntryNotReversiblePublic.description ?? "",
+);
+const LedgerRefConflict = LedgerRefConflictPublic.extend(internalFields).describe(
+  LedgerRefConflictPublic.description ?? "",
+);
 const RatingUnknownAlgorithm = RatingUnknownAlgorithmPublic.extend(internalFields).describe(
   RatingUnknownAlgorithmPublic.description ?? "",
 );
@@ -2116,6 +2364,30 @@ const RatingPoolNotFound = RatingPoolNotFoundPublic.extend(internalFields).descr
 const RatingRecordForbidden = RatingRecordForbiddenPublic.extend(internalFields).describe(
   RatingRecordForbiddenPublic.description ?? "",
 );
+const ConsentUnknownPurpose = ConsentUnknownPurposePublic.extend(internalFields).describe(
+  ConsentUnknownPurposePublic.description ?? "",
+);
+const ConsentStaleNotice = ConsentStaleNoticePublic.extend(internalFields).describe(
+  ConsentStaleNoticePublic.description ?? "",
+);
+const ConsentMethodBelowMinimum = ConsentMethodBelowMinimumPublic.extend(internalFields).describe(
+  ConsentMethodBelowMinimumPublic.description ?? "",
+);
+const ConsentWithdrawalBelowGrant = ConsentWithdrawalBelowGrantPublic.extend(internalFields).describe(
+  ConsentWithdrawalBelowGrantPublic.description ?? "",
+);
+const ConsentEvidenceMissing = ConsentEvidenceMissingPublic.extend(internalFields).describe(
+  ConsentEvidenceMissingPublic.description ?? "",
+);
+const ConsentExpiryPassed = ConsentExpiryPassedPublic.extend(internalFields).describe(
+  ConsentExpiryPassedPublic.description ?? "",
+);
+const ConsentDocumentNotFound = ConsentDocumentNotFoundPublic.extend(internalFields).describe(
+  ConsentDocumentNotFoundPublic.description ?? "",
+);
+const ConsentEvidenceStoreMissing = ConsentEvidenceStoreMissingPublic.extend(internalFields).describe(
+  ConsentEvidenceStoreMissingPublic.description ?? "",
+);
 const MatchmakingRoomNotFound = MatchmakingRoomNotFoundPublic.extend(internalFields).describe(
   MatchmakingRoomNotFoundPublic.description ?? "",
 );
@@ -2304,6 +2576,18 @@ const OrganizationSlugTaken = OrganizationSlugTakenPublic.extend(internalFields)
 const OrganizationNominationInvalid = OrganizationNominationInvalidPublic.extend(internalFields).describe(
   OrganizationNominationInvalidPublic.description ?? "",
 );
+const OrganizationLastOwner = OrganizationLastOwnerPublic.extend(internalFields).describe(
+  OrganizationLastOwnerPublic.description ?? "",
+);
+const OrganizationAlreadyMember = OrganizationAlreadyMemberPublic.extend(internalFields).describe(
+  OrganizationAlreadyMemberPublic.description ?? "",
+);
+const OrganizationSeatLimitReached = OrganizationSeatLimitReachedPublic.extend(internalFields).describe(
+  OrganizationSeatLimitReachedPublic.description ?? "",
+);
+const OrganizationSuspended = OrganizationSuspendedPublic.extend(internalFields).describe(
+  OrganizationSuspendedPublic.description ?? "",
+);
 
 const ArtifactsNotFound = ArtifactsNotFoundPublic.extend(internalFields).describe(
   ArtifactsNotFoundPublic.description ?? "",
@@ -2353,6 +2637,7 @@ export const KitErrorPayload = z
     AuthSessionNotFresh,
     AuthAccountSuspended,
     AuthAccountDeleted,
+    AuthHandoffInvalid,
     NotFound,
     Conflict,
     RateLimit,
@@ -2364,6 +2649,8 @@ export const KitErrorPayload = z
     UnknownWorkflow,
     WorkflowFailed,
     WebhookUnverified,
+    PresenceTicketInvalid,
+    PresenceRoomFull,
     CloudflareNotConfigured,
     CloudflareRequestFailed,
     CloudflareInvalidResponse,
@@ -2411,12 +2698,23 @@ export const KitErrorPayload = z
     LedgerInsufficientFunds,
     LedgerHoldNotOpen,
     LedgerInvalidAmount,
+    LedgerEntryNotFound,
+    LedgerEntryNotReversible,
+    LedgerRefConflict,
     RatingUnknownAlgorithm,
     RatingUnsupportedPlayerCount,
     RatingInvalidParams,
     RatingGameNotFound,
     RatingPoolNotFound,
     RatingRecordForbidden,
+    ConsentUnknownPurpose,
+    ConsentStaleNotice,
+    ConsentMethodBelowMinimum,
+    ConsentWithdrawalBelowGrant,
+    ConsentEvidenceMissing,
+    ConsentExpiryPassed,
+    ConsentDocumentNotFound,
+    ConsentEvidenceStoreMissing,
     MatchmakingRoomNotFound,
     MatchmakingRoomFull,
     MatchmakingInvalidCode,
@@ -2469,6 +2767,10 @@ export const KitErrorPayload = z
     OrganizationLastAdministrator,
     OrganizationSlugTaken,
     OrganizationNominationInvalid,
+    OrganizationLastOwner,
+    OrganizationAlreadyMember,
+    OrganizationSeatLimitReached,
+    OrganizationSuspended,
     ArtifactsNotFound,
     ArtifactsForbidden,
     ArtifactsInvalidName,

package/src/error/pithyError.ts

@@ -192,6 +192,48 @@ export class WebhookUnverifiedError extends PithyError {
   }
 }
 
+/**
+ * One code for every way a presence socket's ticket fails — missing, forged, expired, spent, or minted for
+ * another room. The step goes in `detail`, which the codec strips: a caller holding somebody else's ticket
+ * learns only that it no longer works.
+ */
+export class PresenceTicketInvalidError extends PithyError {
+  declare readonly payload: Extract<ErrorPayload, { code: "core/presence_ticket_invalid" }>;
+
+  constructor(args: ErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "core/presence_ticket_invalid",
+        status: 401,
+        message: args.message ?? "That presence ticket is not valid.",
+        action: args.action ?? "Mint a fresh ticket and open the socket within 60 seconds.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/** A presence room is at the participant cap its room kind declares. */
+export class PresenceRoomFullError extends PithyError {
+  declare readonly payload: Extract<ErrorPayload, { code: "core/presence_room_full" }>;
+
+  constructor(args: ErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "core/presence_room_full",
+        status: 409,
+        message: args.message ?? "That room is full.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
 export class ForbiddenError extends PithyError {
   declare readonly payload: Extract<ErrorPayload, { code: "auth/forbidden" }>;
 

package/src/http/routeSpec.ts

@@ -3,6 +3,8 @@
 
 import type { MiddlewareHandler } from "hono";
 import type { z } from "zod";
+import type { PithyHonoEnv } from "../capability/capability";
+import { ForbiddenError, UnauthorizedError } from "../error/pithyError";
 import type { VerificationStrategy } from "./verification";
 
 /**
@@ -43,6 +45,24 @@ export interface RouteResponse {
 /** The HTTP methods an `app.all` route is documented under. OpenAPI has no "any method". */
 export type DocumentedMethod = "get" | "post" | "put" | "patch" | "delete" | "head" | "options";
 
+/**
+ * What a tool does beyond reading, which every non-`GET` tool must say (`docs/AGENT-ACCESS.md` §4).
+ *
+ * **A route is a tool only when it says so, and a non-`GET` says so louder.** One that sends mail, charges a card or
+ * deletes something is a tool an agent can call in a loop, so the effect is not inferred from the method: it is
+ * declared, it sets the tool's MCP annotations, it is written into the tool's description, and it is counted on the
+ * consent screen beside its capability.
+ */
+export const TOOL_EFFECTS = ["writes", "sends", "charges", "deletes"] as const;
+export type ToolEffect = (typeof TOOL_EFFECTS)[number];
+
+/**
+ * A route's opt-in to the app's MCP endpoint. `true` is a read, and only a `GET` may say it; anything else declares
+ * its {@link ToolEffect}. `createBackend` refuses a composition where either half is wrong — `describeRoute` cannot
+ * see the method it is mounted under, so the composition is the first place the pair can be checked.
+ */
+export type RouteTool = true | { readonly effect: ToolEffect };
+
 /** What a route is for, how its caller is verified, and what it returns. */
 export interface RouteSpec {
   /** One sentence, in the brand voice. The operation's title in the contract. */
@@ -64,14 +84,64 @@ export interface RouteSpec {
   readonly responses: Readonly<Record<number, z.ZodType | RouteResponse>>;
   /** For an `app.all` route only: the methods it is documented under. */
   readonly methods?: readonly DocumentedMethod[];
+  /**
+   * The power a caller's role must hold to reach this route at all. **Declaring it installs the gate**: the
+   * same middleware that carries this spec refuses a caller whose acting organization's role does not hold it, so
+   * what the MCP endpoint filters `tools/list` on and what the route enforces are one value and cannot drift.
+   *
+   * A route whose access depends on the record — its owner may, a manager may — declares the power that lets a
+   * member reach it at all, and keeps its in-handler check. Absent, the route is gated by its other guards alone,
+   * and a tool for it is offered to every signed-in user the endpoint admits.
+   */
+  readonly power?: string;
+  /**
+   * The route's permanent name within its capability, e.g. `threads.reply`. Its MCP tool is
+   * `<capability>_<operation>`, through the one normalizer the control-plane server's tools use. Unique within a
+   * capability, and never renamed once published: an agent references a tool by name.
+   */
+  readonly operation?: string;
+  /**
+   * The route's opt-in to the app's MCP endpoint. Absent, the route is not a tool. See {@link RouteTool}.
+   */
+  readonly tool?: RouteTool;
 }
 
-/** Declare what a route is for, how its caller is verified, and what it returns. See {@link RouteSpec}. */
+/**
+ * Declare what a route is for, how its caller is verified, and what it returns. See {@link RouteSpec}.
+ *
+ * With a {@link RouteSpec.power} it is also the route's power gate, read off the acting-organization seam the way
+ * every capability outside tenancy asks it. It sits first on the route line, so it answers an anonymous caller
+ * itself rather than assuming a guard below it will: a 401, because signing in might help, where a role that does
+ * not hold the power is a 403.
+ */
 export function describeRoute(spec: RouteSpec): MiddlewareHandler {
-  const middleware: MiddlewareHandler = async (_c, next) => {
-    await next();
-  };
-  return Object.assign(middleware, { [ROUTE_SPEC]: spec });
+  const { power } = spec;
+  const middleware: MiddlewareHandler<PithyHonoEnv> =
+    power === undefined
+      ? async (_c, next) => {
+          await next();
+        }
+      : async (c, next) => {
+          if (!c.var.auth) {
+            throw new UnauthorizedError({
+              message: "Authentication required.",
+              action: "Sign in and retry with a valid session or bearer token.",
+              detail: `describeRoute(power: ${power}) ran with no signed-in caller`,
+            });
+          }
+          const acting = await c.var.actingOrganization();
+          if (acting === null || !acting.roleAllows(power)) {
+            throw new ForbiddenError({
+              message: `Your role does not allow \`${power}\`.`,
+              detail:
+                acting === null
+                  ? `no organization is in force for user ${c.var.auth.userId}, so ${power} is not held`
+                  : `the role in organization ${acting.organizationId} does not hold ${power}`,
+            });
+          }
+          await next();
+        };
+  return Object.assign(middleware as MiddlewareHandler, { [ROUTE_SPEC]: spec });
 }
 
 /** The spec a {@link describeRoute} middleware carries, or `undefined` for any other handler. */

package/src/http/validation.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import { zValidator } from "@hono/zod-validator";
-import type { ValidationTargets } from "hono";
+import type { Context, MiddlewareHandler, ValidationTargets } from "hono";
 import type { z } from "zod";
 import { fromZodError } from "../error/pithyError";
 
@@ -70,12 +70,44 @@ export interface RequestContract {
 export function validate<Target extends keyof ValidationTargets, Schema extends z.ZodType>(
   target: Target,
   schema: Schema,
+  onInvalid?: InvalidRequestListener,
 ) {
-  const middleware = zValidator(target, schema, validationHook);
   const contract: RequestContract = { target, schema };
-  return Object.assign(middleware, { [REQUEST_CONTRACT]: contract });
+  if (!onInvalid) return Object.assign(zValidator(target, schema, validationHook), { [REQUEST_CONTRACT]: contract });
+  // What each refused request sent, keyed by its context, so the listener is handed the input without
+  // reading the request raw — which no route may do.
+  const refusedInput = new WeakMap<Context, unknown>();
+  const middleware = zValidator(target, schema, (outcome: ValidationOutcome & { data?: unknown }, c: Context) => {
+    if (!outcome.success) refusedInput.set(c, outcome.data);
+    validationHook(outcome);
+  });
+  // Only a throw from the validator itself is a refusal of the request. Once `next` runs, a throw is the
+  // handler's, and is the handler's to record.
+  const listened: MiddlewareHandler = async (c, next) => {
+    let reached = false;
+    try {
+      return await middleware(c, async () => {
+        reached = true;
+        await next();
+      });
+    } catch (error) {
+      if (!reached) await onInvalid(c, error, refusedInput.get(c));
+      throw error;
+    }
+  };
+  return Object.assign(listened as typeof middleware, { [REQUEST_CONTRACT]: contract });
 }
 
+/**
+ * Told when {@link validate} refuses a request — a body that does not parse, or one that fails the schema —
+ * before the refusal is thrown. A route whose every attempt must be on the audit trail records the refusal
+ * here. It cannot turn the refusal into anything else: the error is thrown after it returns, and a listener
+ * that throws replaces it. `input` is what the request sent for the validated part, as it arrived; it is
+ * `undefined` when there was nothing to read, as for a body that is not JSON. Input validated by an earlier
+ * {@link validate} on the same route is readable with `c.req.valid(target)`.
+ */
+export type InvalidRequestListener = (c: Context, error: unknown, input: unknown) => Promise<void> | void;
+
 /** The contract a {@link validate} middleware carries, or `undefined` for any other handler. */
 export function requestContractOf(handler: unknown): RequestContract | undefined {
   if (typeof handler !== "function") return undefined;

package/src/http/verification.ts

@@ -11,7 +11,9 @@ import { z } from "zod";
  */
 export const VerificationStrategy = z
   .union([
-    z.literal("bearer").describe("Short-lived access token via Authorization: Bearer; validated by @pithy-sh/auth."),
+    z
+      .literal("bearer")
+      .describe("A session token via Authorization: Bearer, rotated before it expires; validated by @pithy-sh/auth."),
     z.literal("session").describe("Cookie-based web session, CSRF-protected; validated by @pithy-sh/auth."),
     z
       .literal("signed-webhook")

package/src/i18n/translator.ts

@@ -90,7 +90,8 @@ export interface TranslatorInput {
   readonly formattingLocale?: string;
   /**
    * The catalogs to walk, most-specific first. `@pithy-sh/i18n` passes adopter-locale, adopter-default,
-   * kit-locale, kit-default; a copied screen passes its own baked English and nothing else.
+   * kit-locale, composed-locale, composed-default, composed English; a copied screen passes its own baked
+   * English and nothing else.
    */
   readonly layers: readonly (MessageCatalog | undefined)[];
 }

package/src/index.ts

@@ -99,6 +99,8 @@ export {
   ANY_VERIFIED_CALLER,
   type ControlPlaneRequirement,
   ControlPlaneScope,
+  ERASURE_READ_SCOPE,
+  EVIDENCE_READ_SCOPE,
   KEYS_ROTATE_SCOPE,
   MANIFEST_READ_SCOPE,
   MIGRATIONS_READ_SCOPE,