@pithy-sh/core 0.8.0 → 0.10.0

package/src/error/wire.ts

@@ -0,0 +1,40 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+// Its own module, importing nothing but zod, so a browser and a socket's frame schemas can name the error
+// shape without reaching the HTTP codec or Hono. The OpenAPI and AsyncAPI documents both describe it here.
+
+/**
+ * The wire body of every error a route returns, whatever its status: `pithyErrorHandler` renders
+ * `{ error: clientError(payload) }`, and a socket's error frame carries the same `error` object. The payload's own schema is a union over every kit code, which
+ * would put several hundred variants into each operation, so the contract describes the envelope and
+ * names the code list's home instead.
+ */
+export const ErrorBody = z
+  .object({
+    error: z
+      .object({
+        code: z
+          .string()
+          .describe(
+            "Namespaced `domain/reason`, e.g. `auth/invalid_token`. Stable: a client switches on it. The full list is `pithy schema --json`'s `errorCodes`.",
+          ),
+        status: z.number().int().describe("The HTTP status, repeated in the body."),
+        message: z
+          .string()
+          .describe("English, for a person. A client that translates renders its own wording for `code` instead."),
+        params: z
+          .record(z.string(), z.unknown())
+          .optional()
+          .describe("Values a translating client interpolates into its own wording for `code`."),
+        issues: z
+          .array(z.unknown())
+          .optional()
+          .describe("For `validation/invalid_input`: one entry per field that failed, with its path."),
+      })
+      .describe("The public error payload. Never carries the operator's remedy or internal detail."),
+  })
+  .describe("The body of every error response.");
+export type ErrorBody = z.infer<typeof ErrorBody>;

package/src/http/oidcWebhook.ts

@@ -491,8 +491,8 @@ export async function verifyOidcToken(token: string, options: VerifyOidcTokenOpt
 }
 
 /**
- * The OIDC gate, as a route wears it: `app.post(path, requireOidcWebhook({…}), zValidator("json", Body,
- * validationHook), handler)`.
+ * The OIDC gate, as a route wears it: `app.post(path, requireOidcWebhook({…}), validate("json", Body),
+ * handler)`.
  *
  * ## Why the header is read before anything else
  *
@@ -528,7 +528,7 @@ export async function verifyOidcToken(token: string, options: VerifyOidcTokenOpt
  * null-check.
  *
  * The body is never read here — unlike the HMAC gate, whose proof covers the bytes. An OIDC token proves who
- * sent the request and says nothing about what they sent, so the route's `zValidator` is the only thing that
+ * sent the request and says nothing about what they sent, so the route's `validate` is the only thing that
  * touches the body, and it sees an untouched stream.
  */
 export function requireOidcWebhook(options: OidcWebhookGuardOptions): MiddlewareHandler<PithyHonoEnv> {

package/src/http/routeContract.ts

@@ -65,7 +65,7 @@ function probeContext(record: () => void) {
   return { req, env: {}, var: {}, get: () => undefined, set: () => {} } as unknown as Context;
 }
 
-/** Does this middleware read `c.req.param()` — i.e. is it a `zValidator("param", …)`? */
+/** Does this middleware read `c.req.param()` — i.e. is it a `validate("param", …)`? */
 async function readsPathParams(handler: (c: Context, next: Next) => unknown): Promise<boolean> {
   let read = false;
   try {

package/src/http/routeSpec.ts

@@ -0,0 +1,81 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { MiddlewareHandler } from "hono";
+import type { z } from "zod";
+import type { VerificationStrategy } from "./verification";
+
+/**
+ * The third half of a route declaration. `validate` says what a caller may send and the guards say who
+ * may send it; this says what the route is for, how its caller is verified, and what comes back. It is
+ * the part the OpenAPI contract (`../openapi/document.ts`) cannot read from anywhere else: a guard is an
+ * anonymous closure, and a handler's `c.json(… satisfies Response)` is a compile-time check that leaves
+ * nothing behind at runtime.
+ *
+ * It sits first on the route line, ahead of the guards, and does nothing when it runs but call `next`.
+ * Its whole value is the spec it carries under {@link ROUTE_SPEC}, which a reader of the composed app
+ * finds by walking `app.routes`.
+ *
+ * ```ts
+ * app.get(
+ *   `${base}/:board/top`,
+ *   describeRoute({ summary: "Read the top of a board.", verification: ["bearer", "session"], responses: { 200: TopPage } }),
+ *   requireAuth(),
+ *   validate("param", BoardParam),
+ *   handler,
+ * );
+ * ```
+ */
+
+/** The key a {@link describeRoute} middleware carries its spec under. Global, so two copies of core agree. */
+export const ROUTE_SPEC = Symbol.for("pithy.routeSpec");
+
+/** One response a route can give that is not a JSON body: bytes, a redirect, HTML, or nothing at all. */
+export interface RouteResponse {
+  /** What this response means, in one sentence. */
+  readonly description: string;
+  /** The JSON body, when there is one. Its input side is the wire: what a client parses with it. */
+  readonly schema?: z.ZodType;
+  /** The media type when the body is not JSON, e.g. `text/html` or `application/octet-stream`. */
+  readonly contentType?: string;
+}
+
+/** 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 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. */
+  readonly summary: string;
+  /** Anything a client author must know that the schemas do not say. */
+  readonly description?: string;
+  /**
+   * How the caller is verified. A list when the route takes more than one — `requireAuth()` accepts a
+   * bearer token or a session, so most authenticated routes declare both.
+   */
+  readonly verification: VerificationStrategy | readonly VerificationStrategy[];
+  /** Scopes the caller's credential must carry, beyond being verified. */
+  readonly scopes?: readonly string[];
+  /**
+   * Every success response, by status. A Zod schema is a JSON body described by the schema itself; a
+   * {@link RouteResponse} covers everything else. Errors are not listed: every route can answer with the
+   * one `PithyError` body, and the contract says so once.
+   */
+  readonly responses: Readonly<Record<number, z.ZodType | RouteResponse>>;
+  /** For an `app.all` route only: the methods it is documented under. */
+  readonly methods?: readonly DocumentedMethod[];
+}
+
+/** Declare what a route is for, how its caller is verified, and what it returns. See {@link RouteSpec}. */
+export function describeRoute(spec: RouteSpec): MiddlewareHandler {
+  const middleware: MiddlewareHandler = async (_c, next) => {
+    await next();
+  };
+  return Object.assign(middleware, { [ROUTE_SPEC]: spec });
+}
+
+/** The spec a {@link describeRoute} middleware carries, or `undefined` for any other handler. */
+export function routeSpecOf(handler: unknown): RouteSpec | undefined {
+  if (typeof handler !== "function") return undefined;
+  return (handler as { [ROUTE_SPEC]?: RouteSpec })[ROUTE_SPEC];
+}

package/src/http/sameOrigin.ts

@@ -45,7 +45,7 @@ export type SameOriginGate = MiddlewareHandler<PithyHonoEnv>;
  * Require this request to come from an origin the Worker trusts — the CSRF gate a cookie-authenticated
  * mutating route wears, beside the strategy that says who the caller is.
  *
- *   app.post("/organizations", requireAuth(), requireSameOrigin(), zValidator(…), handler)
+ *   app.post("/organizations", requireAuth(), requireSameOrigin(), validate(…), handler)
  *
  * A bearer request carries no ambient credential and is CSRF-exempt; that exemption belongs to the
  * published gate, since the capability that owns the credential model is the one that knows.

package/src/http/signedWebhook.ts

@@ -377,8 +377,8 @@ export async function verifySignedWebhook(
 }
 
 /**
- * The `signed-webhook` gate, as a route wears it: `app.post(path, requireSignedWebhook({…}), zValidator("json",
- * Body, validationHook), handler)`.
+ * The `signed-webhook` gate, as a route wears it: `app.post(path, requireSignedWebhook({…}), validate("json",
+ * Body), handler)`.
  *
  * ## Why the header is read before anything else
  *
@@ -402,7 +402,7 @@ export async function verifySignedWebhook(
  * `c.req.text()` is not.
  *
  * `c.req.text()` rather than `c.req.raw.text()`, and the distinction is load-bearing. Hono caches its own
- * body reads and serves `c.req.json()` out of the cached text, so a `zValidator("json", …)` after this gate
+ * body reads and serves `c.req.json()` out of the cached text, so a `validate("json", …)` after this gate
  * parses identical bytes. Reading `c.req.raw` would consume the stream and leave the validator with nothing.
  */
 export function requireSignedWebhook(options: SignedWebhookGuardOptions): MiddlewareHandler<PithyHonoEnv> {

package/src/http/socket.ts

@@ -0,0 +1,55 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { z } from "zod";
+import type { SocketVersions } from "./subprotocol";
+import type { VerificationStrategy } from "./verification";
+
+/**
+ * **A WebSocket, described for the AsyncAPI contract.** The socket's counterpart of `describeRoute`.
+ *
+ * OpenAPI cannot describe a socket: after the upgrade there are no requests, only frames each way. So a
+ * capability that serves one declares it on its `sockets` contribution, built from its resolved config —
+ * the path it mounted, how a caller is verified, the versions it serves, and a Zod schema for every frame
+ * each side may send. `../asyncapi/document.ts` reads the declarations into an AsyncAPI document, the way
+ * `../openapi/document.ts` reads the route table into OpenAPI.
+ *
+ * The schemas are the ones the socket parses with, never a copy: a frame the Worker receives is parsed with
+ * the schema declared here, so the document and the socket cannot disagree about what is accepted.
+ */
+
+/** One frame one side of a socket may send. */
+export interface SocketMessage {
+  /** The frame's name, unique within its socket: `state`, `error`, `action`. */
+  readonly name: string;
+  /** What the frame is, in one sentence. */
+  readonly summary: string;
+  /** The frame's JSON body. Absent for a plain-text frame. */
+  readonly schema?: z.ZodType;
+  /** A plain-text frame's exact text — `ping`, `pong`. The one exception to JSON frames, stated per frame. */
+  readonly text?: string;
+}
+
+/** One WebSocket a capability serves. */
+export interface SocketChannel {
+  /** A stable name for the socket, unique in the Worker: `multiplayerSession`, `matchmakingPresence`. */
+  readonly name: string;
+  /** The upgrade path, as Hono registered it: `/multiplayer/sessions/:id/socket`. */
+  readonly path: string;
+  /** What the socket is for, in one sentence. */
+  readonly summary: string;
+  /** Anything a client author must know that the schemas do not say. */
+  readonly description?: string;
+  /** How the upgrade request is verified. */
+  readonly verification: VerificationStrategy | readonly VerificationStrategy[];
+  /** The path parameters' schema — the same one the upgrade route validates them with. */
+  readonly params?: z.ZodType;
+  /** The subprotocol versions this socket serves. */
+  readonly versions: SocketVersions;
+  /** Every frame the Worker sends. */
+  readonly send: readonly SocketMessage[];
+  /** Every frame the Worker accepts. Anything else is answered with a `validation/invalid_input` error frame. */
+  readonly receive: readonly SocketMessage[];
+  /** Further named schemas a client needs, such as each configured game's `action` and `view`. */
+  readonly schemas?: Readonly<Record<string, z.ZodType>>;
+}

package/src/http/subprotocol.ts

@@ -0,0 +1,47 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { ValidationError } from "../error/pithyError";
+
+/**
+ * **A socket's version is negotiated at the upgrade, and the Worker serves two.**
+ *
+ * An app store client lags its Worker by months — the same version boundary an admin response crosses
+ * (CLAUDE.md §HTTP). So a socket's frames change the way a response does: a field added to a frame is
+ * optional, and a client ignores a `type` and a key it does not know. A change no client could ignore is a
+ * new subprotocol, offered in `Sec-WebSocket-Protocol` (`pithy.multiplayer.v1`), and the Worker keeps
+ * serving the one before it, so a client released before the change keeps playing.
+ *
+ * The first versioned protocol's previous version is the unversioned one: a client that offers no
+ * subprotocol at all, which is every client written before versions existed. `previous: null` names it.
+ */
+
+/** The header a client offers subprotocols in, and the server answers with the one it chose. */
+export const SUBPROTOCOL_HEADER = "Sec-WebSocket-Protocol";
+
+/** The versions one socket serves: the current one, and the one before it — `null` when that is unversioned. */
+export interface SocketVersions {
+  readonly current: string;
+  readonly previous: string | null;
+}
+
+/**
+ * The version this upgrade speaks: the current one when the client offers it, else the previous one when
+ * the client offers that, else `null` for an unversioned client where the previous version is unversioned.
+ * A client that offers only versions this Worker does not serve is refused with a 400 naming the ones it
+ * does — a socket that opened anyway would speak frames the client cannot read.
+ */
+export function negotiateSubprotocol(offered: string | null | undefined, versions: SocketVersions): string | null {
+  const asked = (offered ?? "")
+    .split(",")
+    .map((protocol) => protocol.trim())
+    .filter((protocol) => protocol.length > 0);
+  if (asked.length === 0 && versions.previous === null) return null;
+  if (asked.includes(versions.current)) return versions.current;
+  if (versions.previous !== null && asked.includes(versions.previous)) return versions.previous;
+  const served = [versions.current, ...(versions.previous === null ? [] : [versions.previous])].join(", ");
+  throw new ValidationError({
+    message: `This socket speaks ${served}${versions.previous === null ? ", or no subprotocol" : ""}. The client offered ${asked.length === 0 ? "none" : asked.join(", ")}.`,
+    action: `Offer ${versions.current} in ${SUBPROTOCOL_HEADER}.`,
+  });
+}

package/src/http/validation.ts

@@ -1,6 +1,8 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 
+import { zValidator } from "@hono/zod-validator";
+import type { ValidationTargets } from "hono";
 import type { z } from "zod";
 import { fromZodError } from "../error/pithyError";
 
@@ -10,15 +12,21 @@ import { fromZodError } from "../error/pithyError";
  * mandatory, and both belong on the route line — reading a route tells you what it takes without
  * opening the handler.
  *
- * Routes use `zValidator(target, Schema, validationHook)` from `@hono/zod-validator`. The library
- * owns the middleware and the `c.req.valid(target)` typing; this file owns exactly one thing —
- * what happens when the parse fails. Without the hook, zod-validator answers with its own JSON
- * body, which is neither a `PithyError` payload nor routed through `pithyErrorHandler`. With it,
- * a malformed request is indistinguishable from every other failure the app can produce.
+ * Routes use `validate(target, Schema)`. `@hono/zod-validator` owns the middleware and the
+ * `c.req.valid(target)` typing; this file owns two things — what happens when the parse fails, and
+ * leaving the schema readable on the middleware afterwards.
  *
- * The hook is deliberately not a wrapper around `zValidator`. A wrapper would be a second name for
- * a library we do not re-export (CLAUDE.md §Toolchain), and it would hide the target from the route
- * line — the one thing the migration exists to make visible.
+ * The failure: without {@link validationHook}, zod-validator answers with its own JSON body, which is
+ * neither a `PithyError` payload nor routed through `pithyErrorHandler`. With it, a malformed request
+ * is indistinguishable from every other failure the app can produce.
+ *
+ * The schema: `zValidator` returns the same anonymous closure whatever it validates, so once a route is
+ * registered nothing can tell which schema it holds. That was tolerable while the only reader was the
+ * route line. The OpenAPI contract (`../openapi/document.ts`) is a second reader, and it reads the
+ * composed app, so the schema has to survive registration. `validate` is `zValidator` with the hook
+ * applied and the `{ target, schema }` pair attached under {@link REQUEST_CONTRACT}. It was once kept
+ * out of here on purpose, as a second name for a library; it earns the name now by carrying the one
+ * thing the library drops. The target stays the first argument, so the route line reads as before.
  */
 
 /**
@@ -39,3 +47,37 @@ export function validationHook(outcome: ValidationOutcome): void {
   if (outcome.success) return;
   throw fromZodError(outcome.error as z.ZodError);
 }
+
+/** The key a {@link validate} middleware carries its contract under. Global, so two copies of core agree. */
+export const REQUEST_CONTRACT = Symbol.for("pithy.requestContract");
+
+/** What one validator declares: the part of the request it reads, and the schema that part must satisfy. */
+export interface RequestContract {
+  /** The request part, as Hono names it: `json`, `query`, `param`, `header`, `cookie` or `form`. */
+  readonly target: keyof ValidationTargets;
+  /** The schema the part is parsed with. Its input side is what a caller sends. */
+  readonly schema: z.ZodType;
+}
+
+/**
+ * Declare what a route accepts in one part of the request, and fail a malformed one as a
+ * `validation/invalid_input` 400. The handler reads the parsed value with `c.req.valid(target)`.
+ *
+ * ```ts
+ * app.post(path, requireAuth(), validate("param", BoardParam), validate("json", SubmitScoreBody), handler);
+ * ```
+ */
+export function validate<Target extends keyof ValidationTargets, Schema extends z.ZodType>(
+  target: Target,
+  schema: Schema,
+) {
+  const middleware = zValidator(target, schema, validationHook);
+  const contract: RequestContract = { target, schema };
+  return Object.assign(middleware, { [REQUEST_CONTRACT]: contract });
+}
+
+/** 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;
+  return (handler as { [REQUEST_CONTRACT]?: RequestContract })[REQUEST_CONTRACT];
+}

package/src/migrations/bookkeeping.ts

@@ -3,7 +3,7 @@
 
 import type { D1Database } from "@cloudflare/workers-types";
 import type { DatabaseIntrospector, DatabaseMetadataOptions, SchemaMetadata, TableMetadata } from "kysely";
-import { CamelCasePlugin, Kysely } from "kysely";
+import { CamelCasePlugin, Kysely, sql } from "kysely";
 import { D1Dialect } from "kysely-d1";
 
 /**
@@ -42,8 +42,17 @@ export const MIGRATION_LOCK_TABLE = "pithy_migrations_lock";
  */
 export const MIGRATION_OWNER_TABLE = "pithy_migrations_owner";
 
+/**
+ * Which run applied each migration — one row per applied migration, written by the runner from the
+ * `MigrationResult[]` Kysely hands back (`./groups`). Beside the ledger for the same reason the owner
+ * stamp is: Kysely creates `pithy_migrations` and its insert sets `name` and `timestamp` only, so there
+ * is nowhere in it to put a group — and a group is not a migration, so a rollback or a full reset must
+ * not remove the table. A reversed group's own rows go; the table stays.
+ */
+export const MIGRATION_GROUP_TABLE = "pithy_migrations_groups";
+
 /** Pithy's bookkeeping tables — hidden by the introspector the way Kysely hides its own defaults. */
-const INTERNAL_TABLES = [MIGRATION_TABLE, MIGRATION_LOCK_TABLE, MIGRATION_OWNER_TABLE];
+const INTERNAL_TABLES = [MIGRATION_TABLE, MIGRATION_LOCK_TABLE, MIGRATION_OWNER_TABLE, MIGRATION_GROUP_TABLE];
 
 /** Table names from `sqlite_master` only — no pragma joins, no column metadata. */
 class D1Introspector implements DatabaseIntrospector {
@@ -83,3 +92,31 @@ export class D1MigrationDialect extends D1Dialect {
 export function migrationKysely<DB = unknown>(database: D1Database): Kysely<DB> {
   return new Kysely<DB>({ dialect: new D1MigrationDialect({ database }), plugins: [new CamelCasePlugin()] });
 }
+
+/**
+ * The applied migrations, **in the order Kysely steps down from them** — oldest first, tip last.
+ *
+ * Kysely's `Migrator` sorts the ledger by `timestamp`, breaks a tie on the name, and reverses that list to
+ * decide what the next `migrateDown()` reverses. So anything that asks *is this the top of the chain* has
+ * to read the same order: concluding it from the order some other table was written in answers a different
+ * question, and the answer only differs in the cases that matter (`./groups`, #694).
+ *
+ * Empty when the ledger table does not exist — a database nothing has migrated. Existence is checked
+ * against `sqlite_master`, a plain select D1 permits, rather than by catching the read's error, so a
+ * genuine read failure surfaces instead of being read as "nothing applied".
+ */
+export async function appliedMigrationChain<DB>(db: Kysely<DB>): Promise<string[]> {
+  const present = await sql<{
+    name: string;
+  }>`select name from sqlite_master where type = 'table' and name = ${MIGRATION_TABLE}`.execute(db);
+  if (present.rows.length === 0) return [];
+  const { rows } = await sql<{ name: string; timestamp: string }>`select name, timestamp from ${sql.table(
+    MIGRATION_TABLE,
+  )}`.execute(db);
+  return [...rows]
+    .sort((left, right) => {
+      const elapsed = new Date(left.timestamp).getTime() - new Date(right.timestamp).getTime();
+      return elapsed === 0 ? left.name.localeCompare(right.name) : elapsed;
+    })
+    .map((row) => row.name);
+}