@pithy-sh/core 0.8.0 → 0.10.0

package/dist/http/oidcWebhook.js

@@ -234,8 +234,8 @@ async function verifyOidcToken(token, options) {
 	return claims;
 }
 /**
-* 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
 *
@@ -271,7 +271,7 @@ async function verifyOidcToken(token, options) {
 * 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.
 */
 function requireOidcWebhook(options) {

package/dist/http/routeContract.js

@@ -35,7 +35,7 @@ function probeContext(record) {
 		set: () => {}
 	};
 }
-/** 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) {
 	let read = false;
 	try {

package/dist/http/routeSpec.d.ts

@@ -0,0 +1,66 @@
+// 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 declare const ROUTE_SPEC: unique symbol;
+/** 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 declare function describeRoute(spec: RouteSpec): MiddlewareHandler;
+/** The spec a {@link describeRoute} middleware carries, or `undefined` for any other handler. */
+export declare function routeSpecOf(handler: unknown): RouteSpec | undefined;
+//# sourceMappingURL=routeSpec.d.ts.map

package/dist/http/routeSpec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routeSpec.d.ts","sourceRoot":"","sources":["../../src/http/routeSpec.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,8GAA8G;AAC9G,eAAO,MAAM,UAAU,eAAgC,CAAC;AAExD,yGAAyG;AACzG,MAAM,WAAW,aAAa;IAC5B,iDAAiD;IACjD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kGAAkG;IAClG,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;IAC5B,gGAAgG;IAChG,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,4FAA4F;AAC5F,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAEhG,4EAA4E;AAC5E,MAAM,WAAW,SAAS;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,oBAAoB,GAAG,SAAS,oBAAoB,EAAE,CAAC;IAC9E,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,aAAa,CAAC,CAAC,CAAC;IACxE,uEAAuE;IACvE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAChD;AAED,2GAA2G;AAC3G,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,iBAAiB,CAKhE;AAED,iGAAiG;AACjG,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAGnE"}

package/dist/http/routeSpec.js

@@ -0,0 +1,40 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/http/routeSpec.ts
+/**
+* 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. */
+const ROUTE_SPEC = Symbol.for("pithy.routeSpec");
+/** Declare what a route is for, how its caller is verified, and what it returns. See {@link RouteSpec}. */
+function describeRoute(spec) {
+	const middleware = 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. */
+function routeSpecOf(handler) {
+	if (typeof handler !== "function") return void 0;
+	return handler[ROUTE_SPEC];
+}
+//#endregion
+export { ROUTE_SPEC, describeRoute, routeSpecOf };

package/dist/http/sameOrigin.d.ts

@@ -40,7 +40,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/dist/http/sameOrigin.js

@@ -6,7 +6,7 @@ import { ForbiddenError } from "../error/pithyError.js";
 * 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/dist/http/signedWebhook.d.ts

@@ -139,8 +139,8 @@ export declare function checkSignedWebhook(body: string, header: string | null,
  */
 export declare function verifySignedWebhook(body: string, header: string | null, options: VerifySignedWebhookOptions): Promise<void>;
 /**
- * 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
  *
@@ -164,7 +164,7 @@ export declare function verifySignedWebhook(body: string, header: string | null,
  * `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 declare function requireSignedWebhook(options: SignedWebhookGuardOptions): MiddlewareHandler<PithyHonoEnv>;

package/dist/http/signedWebhook.js

@@ -206,8 +206,8 @@ async function verifySignedWebhook(body, header, options) {
 	if (refusal !== void 0) throw webhookRefusal(refusal, options);
 }
 /**
-* 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
 *
@@ -231,7 +231,7 @@ async function verifySignedWebhook(body, header, options) {
 * `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.
 */
 function requireSignedWebhook(options) {

package/dist/http/socket.d.ts

@@ -0,0 +1,52 @@
+// 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>>;
+}
+//# sourceMappingURL=socket.d.ts.map

package/dist/http/socket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket.d.ts","sourceRoot":"","sources":["../../src/http/socket.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE3D;;;;;;;;;;;GAWG;AAEH,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;IAC5B,4GAA4G;IAC5G,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,yCAAyC;AACzC,MAAM,WAAW,aAAa;IAC5B,uGAAuG;IACvG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,2CAA2C;IAC3C,QAAQ,CAAC,YAAY,EAAE,oBAAoB,GAAG,SAAS,oBAAoB,EAAE,CAAC;IAC9E,wFAAwF;IACxF,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;IAC5B,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,aAAa,EAAE,CAAC;IACxC,+GAA+G;IAC/G,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAC3C,gGAAgG;IAChG,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;CACxD"}

package/dist/http/socket.js

@@ -0,0 +1,2 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT

package/dist/http/subprotocol.d.ts

@@ -0,0 +1,29 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+/**
+ * **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 declare 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 declare function negotiateSubprotocol(offered: string | null | undefined, versions: SocketVersions): string | null;
+//# sourceMappingURL=subprotocol.d.ts.map

package/dist/http/subprotocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subprotocol.d.ts","sourceRoot":"","sources":["../../src/http/subprotocol.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AAEH,gGAAgG;AAChG,eAAO,MAAM,kBAAkB,2BAA2B,CAAC;AAE3D,gHAAgH;AAChH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,QAAQ,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI,CAahH"}

package/dist/http/subprotocol.js

@@ -0,0 +1,37 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { ValidationError } from "../error/pithyError.js";
+//#region src/http/subprotocol.ts
+/**
+* **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. */
+const SUBPROTOCOL_HEADER = "Sec-WebSocket-Protocol";
+/**
+* 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.
+*/
+function negotiateSubprotocol(offered, versions) {
+	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}.`
+	});
+}
+//#endregion
+export { SUBPROTOCOL_HEADER, negotiateSubprotocol };

package/dist/http/validation.d.ts

@@ -1,5 +1,6 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
+import type { ValidationTargets } from "hono";
 import type { z } from "zod";
 /**
  * How a route declares what it accepts. Its sibling {@link ./verification.VerificationStrategy}
@@ -7,15 +8,21 @@ import type { z } from "zod";
  * 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.
  */
 /**
  * The outcome `@hono/zod-validator` hands a hook. Declared structurally rather than by importing
@@ -36,4 +43,29 @@ export type ValidationOutcome = {
  * validation is declared, not what a caller sees when it fails.
  */
 export declare function validationHook(outcome: ValidationOutcome): void;
+/** The key a {@link validate} middleware carries its contract under. Global, so two copies of core agree. */
+export declare const REQUEST_CONTRACT: unique symbol;
+/** 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 declare function validate<Target extends keyof ValidationTargets, Schema extends z.ZodType>(target: Target, schema: Schema): import("hono").MiddlewareHandler<import("hono").Env, string, {
+    in: (undefined extends (Schema extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<Schema> : Schema extends z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> ? z.core.input<Schema> : never) ? true : false) extends true ? { [K in Target]?: ([Schema extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<Schema> : Schema extends z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> ? z.core.input<Schema> : never] extends [ValidationTargets[K]] ? ValidationTargets[K] & (Schema extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<Schema> : Schema extends z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> ? z.core.input<Schema> : never) : import("hono/validator").InferInput<Schema extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<Schema> : Schema extends z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> ? z.core.input<Schema> : never, K, import("hono/types").ParsedFormValue>) | undefined; } : { [K in Target]: [Schema extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<Schema> : Schema extends z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> ? z.core.input<Schema> : never] extends [ValidationTargets[K]] ? ValidationTargets[K] & (Schema extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<Schema> : Schema extends z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> ? z.core.input<Schema> : never) : import("hono/validator").InferInput<Schema extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<Schema> : Schema extends z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> ? z.core.input<Schema> : never, K, import("hono/types").ParsedFormValue>; };
+    out: { [K in Target]: Schema extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").output<Schema> : Schema extends z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> ? z.infer<Schema> : never; };
+}, never> & {
+    [REQUEST_CONTRACT]: RequestContract;
+};
+/** The contract a {@link validate} middleware carries, or `undefined` for any other handler. */
+export declare function requestContractOf(handler: unknown): RequestContract | undefined;
 //# sourceMappingURL=validation.d.ts.map

package/dist/http/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/http/validation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAG7B;;;;;;;;;;;;;;;GAeG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS,CAAA;CAAE,CAAC;AAEhG;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAG/D"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/http/validation.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAG7B;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS,CAAA;CAAE,CAAC;AAEhG;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAG/D;AAED,6GAA6G;AAC7G,eAAO,MAAM,gBAAgB,eAAsC,CAAC;AAEpE,4GAA4G;AAC5G,MAAM,WAAW,eAAe;IAC9B,kGAAkG;IAClG,QAAQ,CAAC,MAAM,EAAE,MAAM,iBAAiB,CAAC;IACzC,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,MAAM,SAAS,MAAM,iBAAiB,EAAE,MAAM,SAAS,CAAC,CAAC,OAAO,EACvF,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM;;;;;EAKf;AAED,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,eAAe,GAAG,SAAS,CAG/E"}

package/dist/http/validation.js

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 import { fromZodError } from "../error/pithyError.js";
+import { zValidator } from "@hono/zod-validator";
 //#region src/http/validation.ts
 /**
 * The one validation-failure hook every provided route passes to `zValidator`. Maps the `ZodError`
@@ -12,5 +13,28 @@ function validationHook(outcome) {
 	if (outcome.success) return;
 	throw fromZodError(outcome.error);
 }
+/** The key a {@link validate} middleware carries its contract under. Global, so two copies of core agree. */
+const REQUEST_CONTRACT = Symbol.for("pithy.requestContract");
+/**
+* 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);
+* ```
+*/
+function validate(target, schema) {
+	const middleware = zValidator(target, schema, validationHook);
+	const contract = {
+		target,
+		schema
+	};
+	return Object.assign(middleware, { [REQUEST_CONTRACT]: contract });
+}
+/** The contract a {@link validate} middleware carries, or `undefined` for any other handler. */
+function requestContractOf(handler) {
+	if (typeof handler !== "function") return void 0;
+	return handler[REQUEST_CONTRACT];
+}
 //#endregion
-export { validationHook };
+export { REQUEST_CONTRACT, requestContractOf, validate, validationHook };

package/dist/index.js

@@ -10,10 +10,10 @@ import { ControlPlaneAuditActions } from "./controlPlane/audit/actions.js";
 import { CONTROL_PLANE_HEADER, CONTROL_PLANE_VERSION_CREATED_HEADER, CONTROL_PLANE_VERSION_HEADER, workerBuildChanged } from "./controlPlane/wire.js";
 import { ControlPlaneContext } from "./controlPlane/context.js";
 import { requireControlPlane } from "./controlPlane/http/guard.js";
-import { CONTROL_PLANE_KV_BINDING } from "./controlPlane/replay/kvGuard.js";
-import { CONTROLPLANE_MIGRATION_ORDER, controlplane, isControlPlaneCapability } from "./controlPlane/capability.js";
 import { ManifestConfigKey, ManifestConfigValue, ManifestConfigValues, defineManifestConfig, namedConfigValues } from "./controlPlane/discovery/configuration.js";
 import { AdminRoute, CapabilityDeclaration, CapabilityDescriptor, ControlPlaneManifest } from "./controlPlane/discovery/adminRoute.js";
+import { CONTROL_PLANE_KV_BINDING } from "./controlPlane/replay/kvGuard.js";
+import { CONTROLPLANE_MIGRATION_ORDER, controlplane, isControlPlaneCapability } from "./controlPlane/capability.js";
 import { missingAdminRoutes } from "./controlPlane/discovery/drift.js";
 import { exportPublicJwk, mintControlPlaneToken } from "./controlPlane/token/mint.js";
 export { ANY_VERIFIED_CALLER, AdminRoute, CONTROLPLANE_MIGRATION_ORDER, CONTROL_PLANE_CONNECTIONS_TABLE, CONTROL_PLANE_HEADER, CONTROL_PLANE_KV_BINDING, CONTROL_PLANE_VERSION_CREATED_HEADER, CONTROL_PLANE_VERSION_HEADER, CapabilityDeclaration, CapabilityDescriptor, CapabilityHealthReport, ControlPlaneAuditActions, ControlPlaneConfig, ControlPlaneConnection, ControlPlaneContext, ControlPlaneManifest, ControlPlaneScope, Ed25519PublicJwk, HealthCountNominal, HealthNominal, HealthSummary, HealthSummaryKey, HealthSummaryValue, HealthValueCost, HealthValueKind, KEYS_ROTATE_SCOPE, MANIFEST_READ_SCOPE, ManifestConfigKey, ManifestConfigValue, ManifestConfigValues, RegisteredKey, SEAM_SCOPES, capabilityHealthSources, controlPlaneDatabase, controlplane, defineCapabilityHealth, defineManifestConfig, exportPublicJwk, healthAttention, healthReport, healthWire, isControlPlaneCapability, mintControlPlaneToken, missingAdminRoutes, namedConfigValues, namedHealthValues, readCapabilityHealth, requireControlPlane, standingOf, workerBuildChanged };

package/dist/logger/record.d.ts

@@ -56,6 +56,29 @@ export declare const LogRecord: z.ZodObject<{
             message: z.ZodString;
             code: z.ZodString;
         }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"input/required">;
+        status: z.ZodLiteral<400>;
+        flag: z.ZodNullable<z.ZodString>;
+        choices: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"core/precondition_failed">;
+        status: z.ZodLiteral<412>;
+    }, z.core.$strip>, z.ZodObject<{
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        action: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        code: z.ZodLiteral<"core/person_required">;
+        status: z.ZodLiteral<403>;
     }, z.core.$strip>, z.ZodObject<{
         message: z.ZodString;
         params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;

package/dist/logger/record.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/logger/record.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;GAKG;AAEH,4GAA4G;AAC5G,eAAO,MAAM,QAAQ;;;;;EAE4F,CAAC;AAClH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAgD,CAAC;AAEtG;;;;GAIG;AACH,eAAO,MAAM,SAAS,wCAEsF,CAAC;AAC7G,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAW+E,CAAC;AACtG,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAmBnD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAMzD"}
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/logger/record.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;GAKG;AAEH,4GAA4G;AAC5G,eAAO,MAAM,QAAQ;;;;;EAE4F,CAAC;AAClH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAgD,CAAC;AAEtG;;;;GAIG;AACH,eAAO,MAAM,SAAS,wCAEsF,CAAC;AAC7G,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAW+E,CAAC;AACtG,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAmBnD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAMzD"}

package/dist/migrations/bookkeeping.d.ts

@@ -17,10 +17,31 @@ export declare const MIGRATION_LOCK_TABLE = "pithy_migrations_lock";
  * migration, so a rollback or a full reset must not remove it, and no capability has to ship it.
  */
 export declare 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 declare const MIGRATION_GROUP_TABLE = "pithy_migrations_groups";
 /** The D1 dialect Pithy migrates through: stock kysely-d1, with the `sqlite_master`-only introspector. */
 export declare class D1MigrationDialect extends D1Dialect {
     createIntrospector(db: Kysely<unknown>): DatabaseIntrospector;
 }
 /** A Kysely over one D1 binding, with Pithy's dialect and `CamelCasePlugin` — the one way in. */
 export declare function migrationKysely<DB = unknown>(database: D1Database): Kysely<DB>;
+/**
+ * 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 declare function appliedMigrationChain<DB>(db: Kysely<DB>): Promise<string[]>;
 //# sourceMappingURL=bookkeeping.d.ts.map

package/dist/migrations/bookkeeping.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bookkeeping.d.ts","sourceRoot":"","sources":["../../src/migrations/bookkeeping.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,oBAAoB,EAA0D,MAAM,QAAQ,CAAC;AAC3G,OAAO,EAAmB,MAAM,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAsBtC;;;GAGG;AACH,eAAO,MAAM,eAAe,qBAAqB,CAAC;AAElD,oGAAoG;AACpG,eAAO,MAAM,oBAAoB,0BAA0B,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,2BAA2B,CAAC;AAgC9D,0GAA0G;AAC1G,qBAAa,kBAAmB,SAAQ,SAAS;IACtC,kBAAkB,CAAC,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,oBAAoB,CAErE;CACF;AAED,iGAAiG;AACjG,wBAAgB,eAAe,CAAC,EAAE,GAAG,OAAO,EAAE,QAAQ,EAAE,UAAU,GAAG,MAAM,CAAC,EAAE,CAAC,CAE9E"}
+{"version":3,"file":"bookkeeping.d.ts","sourceRoot":"","sources":["../../src/migrations/bookkeeping.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,oBAAoB,EAA0D,MAAM,QAAQ,CAAC;AAC3G,OAAO,EAAmB,MAAM,EAAO,MAAM,QAAQ,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAsBtC;;;GAGG;AACH,eAAO,MAAM,eAAe,qBAAqB,CAAC;AAElD,oGAAoG;AACpG,eAAO,MAAM,oBAAoB,0BAA0B,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,2BAA2B,CAAC;AAE9D;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAgC/D,0GAA0G;AAC1G,qBAAa,kBAAmB,SAAQ,SAAS;IACtC,kBAAkB,CAAC,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,oBAAoB,CAErE;CACF;AAED,iGAAiG;AACjG,wBAAgB,eAAe,CAAC,EAAE,GAAG,OAAO,EAAE,QAAQ,EAAE,UAAU,GAAG,MAAM,CAAC,EAAE,CAAC,CAE9E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,qBAAqB,CAAC,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAcjF"}

package/dist/migrations/bookkeeping.js

@@ -1,6 +1,6 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
-import { CamelCasePlugin, Kysely } from "kysely";
+import { CamelCasePlugin, Kysely, sql } from "kysely";
 import { D1Dialect } from "kysely-d1";
 //#region src/migrations/bookkeeping.ts
 /**
@@ -16,11 +16,20 @@ const MIGRATION_LOCK_TABLE = "pithy_migrations_lock";
 * migration, so a rollback or a full reset must not remove it, and no capability has to ship it.
 */
 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.
+*/
+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
+	MIGRATION_OWNER_TABLE,
+	MIGRATION_GROUP_TABLE
 ];
 /** Table names from `sqlite_master` only — no pragma joins, no column metadata. */
 var D1Introspector = class {
@@ -55,5 +64,25 @@ function migrationKysely(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".
+*/
+async function appliedMigrationChain(db) {
+	if ((await sql`select name from sqlite_master where type = 'table' and name = ${"pithy_migrations"}`.execute(db)).rows.length === 0) return [];
+	const { rows } = await sql`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);
+}
 //#endregion
-export { D1MigrationDialect, MIGRATION_LOCK_TABLE, MIGRATION_OWNER_TABLE, MIGRATION_TABLE, migrationKysely };
+export { D1MigrationDialect, MIGRATION_GROUP_TABLE, MIGRATION_LOCK_TABLE, MIGRATION_OWNER_TABLE, MIGRATION_TABLE, appliedMigrationChain, migrationKysely };