@metaobjectsdev/runtime-ts 1.0.9-rc.1 → 1.0.9-rc.3

package/src/drizzle-fastify/filter-value-format.ts

@@ -0,0 +1,68 @@
+/**
+ * Well-formedness checks for filter values, keyed by the wire format a field's values
+ * take (docs/features/api-contract.md, "Type encodings"). The filter parser runs these
+ * before a value reaches SQL, so a malformed value is a 400 naming the format rather than
+ * a silent empty result (SQLite compares the text and matches nothing) or a driver error
+ * (Postgres refuses the cast).
+ *
+ * Deliberately a little more lenient than the RESPONSE encoding, because a filter bound
+ * is written by a person: a time may omit seconds, a timestamp may omit its time part
+ * (a day bound) or carry any UTC offset, and fractional seconds may have any precision.
+ * What is refused is a value that is not that kind of thing at all.
+ */
+
+import {
+  FIELD_SUBTYPE_DATE,
+  FIELD_SUBTYPE_TIME,
+  FIELD_SUBTYPE_TIMESTAMP,
+  FIELD_SUBTYPE_UUID,
+} from "@metaobjectsdev/metadata";
+import type { FilterValueFormat } from "./filter-allowlist.js";
+
+const DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const TIME_RE = /^(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d{1,9})?)?$/;
+// Date, then optionally a `T`/space time, then optionally `Z` or a ±HH[:]MM offset.
+const TIMESTAMP_RE =
+  /^(\d{4}-\d{2}-\d{2})(?:[T ]((?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d{1,9})?)?)(?:Z|[+-](?:[01]\d|2[0-3]):?[0-5]\d)?)?$/i;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** A `YYYY-MM-DD` that names a real calendar day (2026-02-30 does not). */
+function isCalendarDate(s: string): boolean {
+  const m = DATE_RE.exec(s);
+  if (!m) return false;
+  const [y, mo, d] = [Number(m[1]), Number(m[2]), Number(m[3])];
+  const probe = new Date(Date.UTC(y, mo - 1, d));
+  return probe.getUTCFullYear() === y && probe.getUTCMonth() === mo - 1 && probe.getUTCDate() === d;
+}
+
+function isTimestamp(s: string): boolean {
+  const m = TIMESTAMP_RE.exec(s);
+  return m !== null && isCalendarDate(m[1] ?? "");
+}
+
+const CHECKS: Readonly<Record<FilterValueFormat, (s: string) => boolean>> = {
+  [FIELD_SUBTYPE_DATE]: isCalendarDate,
+  [FIELD_SUBTYPE_TIME]: (s) => TIME_RE.test(s),
+  [FIELD_SUBTYPE_TIMESTAMP]: isTimestamp,
+  [FIELD_SUBTYPE_UUID]: (s) => UUID_RE.test(s),
+};
+
+/** The `expected` member of the `invalid_filter_value` envelope, per format. */
+export const FORMAT_EXPECTED: Readonly<Record<FilterValueFormat, string>> = {
+  [FIELD_SUBTYPE_DATE]: "date (YYYY-MM-DD)",
+  [FIELD_SUBTYPE_TIME]: "time (HH:MM[:SS[.fff]])",
+  [FIELD_SUBTYPE_TIMESTAMP]: "timestamp (YYYY-MM-DD[THH:MM[:SS[.fff]]][Z|±HH:MM])",
+  [FIELD_SUBTYPE_UUID]: "uuid (8-4-4-4-12 hex)",
+};
+
+/** `expected` for a temporal rule that does not say WHICH temporal format it is. */
+export const ANY_TEMPORAL_EXPECTED = "date, time or timestamp (ISO 8601)";
+
+export function matchesFormat(format: FilterValueFormat, s: string): boolean {
+  return CHECKS[format](s);
+}
+
+/** For a `datetime` rule with no `format` (generated before it existed): any of the three. */
+export function matchesAnyTemporal(s: string): boolean {
+  return isCalendarDate(s) || CHECKS[FIELD_SUBTYPE_TIME](s) || isTimestamp(s);
+}

package/src/drizzle-fastify/index.ts

@@ -26,9 +26,10 @@ import { eq, count, and, asc } from "drizzle-orm";
 import qs from "qs";
 import type { FilterAllowlist, SortAllowlist } from "./filter-allowlist.js";
 export type { FilterAllowlist, SortAllowlist } from "./filter-allowlist.js";
-import { parseFilterParams, FilterParseError } from "./filter-parser.js";
+import { parseFilterParams, parsePageBound, FilterParseError } from "./filter-parser.js";
 import { isTruthyFlag, contractErrorCode, coerceIdForColumn, firstRow } from "./util.js";
 import { timestampWire } from "../timestamp-wire.js";
+import { withContractErrorHandler } from "./route-error-handler.js";
 export { isTruthyFlag, contractErrorCode, parseId, coerceIdForColumn } from "./util.js";
 export { timestampWire, canonicalTimestamp } from "../timestamp-wire.js";
 
@@ -161,8 +162,11 @@ export function mountCrudRoutes(opts: CrudRoutesOptions): void {
 
 type VerbOptions = Omit<CrudRoutesOptions, "expose">;
 
+/** The adopter's route options plus the route-scoped contract error handler (an
+ *  unexpected error answers `500 { error: "internal" }`, a malformed JSON body
+ *  `400 { error: "invalid_json" }`) — see route-error-handler.ts. */
 function routeOpts(opts: VerbOptions): RouteShorthandOptions {
-  return opts.routeOptions ?? {};
+  return withContractErrorHandler(opts.routeOptions);
 }
 
 export function mountListRoute(opts: VerbOptions): void {
@@ -211,11 +215,12 @@ export function mountListRoute(opts: VerbOptions): void {
       } else {
         // Legacy path — no allowlists configured. Only limit/offset (+ the TPH
         // discriminator predicate when subtype-scoped).
-        const { limit, offset } = req.query as { limit?: string; offset?: string };
+        const limit = parsePageBound(qsParsed, "limit");
+        const offset = parsePageBound(qsParsed, "offset");
         if (discCond) { q = q.where(discCond); where = discCond; }
         if (src.id !== undefined) q = q.orderBy(asc(src.id));
-        if (limit  !== undefined) q = q.limit(Number(limit));
-        if (offset !== undefined) q = q.offset(Number(offset));
+        if (limit  !== undefined) q = q.limit(limit);
+        if (offset !== undefined) q = q.offset(offset);
       }
 
       // Await the query directly rather than calling `.all()`: the

package/src/drizzle-fastify/list-params.ts

@@ -0,0 +1,50 @@
+/**
+ * List-query parameter checks shared by every mount — the Drizzle mounts (Fastify and
+ * Hono) and the ObjectManager Fastify mount. Deliberately free of drizzle-orm (an
+ * OPTIONAL peer): the ObjectManager mount must not pull it in.
+ */
+
+export class FilterParseError extends Error {
+  constructor(public readonly code: string, message: string, public readonly details?: Record<string, unknown>) {
+    super(message);
+    this.name = "FilterParseError";
+  }
+}
+
+/** The page-size ceiling of a raw-SQL (column-less `.existing()`) view list, which has
+ *  no allowlist to page through and returns at most this many rows. */
+export const RAW_VIEW_MAX_LIMIT = 1000;
+
+/** The `expected` member of a `pagination.invalid_value` answer with no upper bound. */
+export const PAGINATION_EXPECTED = "a non-negative integer (0 or more)";
+
+/**
+ * Read `?limit=` / `?offset=` as a non-negative integer, or refuse it. Before, a value
+ * that was not a finite number (`?limit=abc`) was dropped — every row came back — and a
+ * negative or fractional one reached SQL. `max` is the ceiling a mount clamps to, when it
+ * has one: a bound above it is refused rather than silently lowered. TS-only (no corpus
+ * scenario sends a malformed page bound): see docs/features/api-contract.md, "TS-only
+ * error responses".
+ */
+export function parsePageBound(
+  query: Record<string, unknown>,
+  param: "limit" | "offset",
+  max?: number,
+): number | undefined {
+  const raw = query[param];
+  if (raw === undefined) return undefined;
+  const s = typeof raw === "string" ? raw : String(raw);
+  const n = /^\d+$/.test(s) ? Number(s) : Number.NaN;
+  if (!Number.isSafeInteger(n) || (max !== undefined && n > max)) {
+    const expected = max === undefined ? PAGINATION_EXPECTED : `an integer from 0 to ${max}`;
+    throw new FilterParseError(
+      "pagination.invalid_value",
+      `?${param}= must be ${expected}, got "${s}".`,
+      { param, value: s, expected },
+    );
+  }
+  return n;
+}
+
+/** The `expected` member of an `invalid_sort` answer — the one spelling `?sort` takes. */
+export const SORT_EXPECTED = "sort=<field>:asc|desc";

package/src/drizzle-fastify/mount-m2m.ts

@@ -34,6 +34,7 @@ import type { FastifyInstance, RouteShorthandOptions } from "fastify";
 import { and, eq, or, inArray } from "drizzle-orm";
 import { coerceIdForColumn } from "./util.js";
 import { timestampWire } from "../timestamp-wire.js";
+import { withContractErrorHandler } from "./route-error-handler.js";
 
 // Loose Drizzle types — the helper works across libsql / better-sqlite3 / pg.
 // biome-ignore lint/suspicious/noExplicitAny: dynamic dispatch over user's Drizzle instance
@@ -84,7 +85,8 @@ export interface M2mRouteOptions {
 export function mountM2mRoute(opts: M2mRouteOptions): void {
   const targetPk = opts.targetPkColumn ?? "id";
   const route = `${opts.path}/:id/${opts.relationName}`;
-  const ro = opts.routeOptions ?? {};
+  // Route-scoped contract error handler — see route-error-handler.ts.
+  const ro = withContractErrorHandler(opts.routeOptions);
   const toWire = timestampWire(opts.targetTable);
 
   opts.fastify.get(route, ro, async (req, reply) => {

package/src/drizzle-fastify/mount-read-only.ts

@@ -1,10 +1,11 @@
 import type { FastifyInstance, RouteShorthandOptions } from "fastify";
 import { sql, eq, and, count } from "drizzle-orm";
 import qs from "qs";
-import { parseFilterParams, FilterParseError } from "./filter-parser.js";
+import { parseFilterParams, parsePageBound, RAW_VIEW_MAX_LIMIT, FilterParseError } from "./filter-parser.js";
 import type { FilterAllowlist, SortAllowlist } from "./filter-allowlist.js";
 import { isTruthyFlag, contractErrorCode, coerceIdForColumn, rawIdLiteral, viewBaseConfig } from "./util.js";
 import { timestampWire } from "../timestamp-wire.js";
+import { withContractErrorHandler } from "./route-error-handler.js";
 
 // biome-ignore lint/suspicious/noExplicitAny: dynamic dispatch over user-supplied views
 type AnyView = any;
@@ -118,7 +119,9 @@ async function rawRows(db: any, dialect: string | undefined, query: unknown): Pr
 export function mountReadOnlyCrudRoutes(opts: MountReadOnlyOptions): void {
   const { fastify, path, db, view, filterAllowlist, sortAllowlist, dialect } = opts;
   const idCol = opts.idColumn ?? "id";
-  const ro = opts.routeOptions ?? {};
+  // Route-scoped contract error handler: an unexpected error answers
+  // `500 { error: "internal" }` rather than Fastify's default (which echoes the SQL).
+  const ro = withContractErrorHandler(opts.routeOptions);
 
   const viewName = resolveViewName(view);
   const useRawSql = isEmptyColumnView(view) && !!viewName;
@@ -137,8 +140,9 @@ export function mountReadOnlyCrudRoutes(opts: MountReadOnlyOptions): void {
         const qIdx = url.indexOf("?");
         const queryString = qIdx >= 0 ? url.slice(qIdx + 1) : "";
         const parsed = qs.parse(queryString) as Record<string, unknown>;
-        const limitVal = Math.min(1000, Math.max(1, Number(typeof parsed["limit"] === "string" ? parsed["limit"] : 1000)));
-        const offsetVal = Math.max(0, Number(typeof parsed["offset"] === "string" ? parsed["offset"] : 0));
+        // A bound that is not an integer in range is a 400, not silently clamped.
+        const limitVal = parsePageBound(parsed, "limit", RAW_VIEW_MAX_LIMIT) ?? RAW_VIEW_MAX_LIMIT;
+        const offsetVal = parsePageBound(parsed, "offset") ?? 0;
         const withCount = isTruthyFlag(parsed["withCount"]);
         // biome-ignore lint/suspicious/noExplicitAny: dynamic raw result
         const rows = await rawRows(db, dialect, sql.raw(`SELECT * FROM "${viewName}" LIMIT ${limitVal} OFFSET ${offsetVal}`)) as any[];

package/src/drizzle-fastify/route-error-handler.ts

@@ -0,0 +1,54 @@
+/**
+ * The route-level Fastify error handler every mount helper installs on the routes IT
+ * mounts (drizzle-fastify and the ObjectManager fastify adapter share it).
+ *
+ * Why route-level: Fastify's `errorHandler` route option is scoped to exactly that route
+ * (it overrides the scope's `setErrorHandler` for requests to it, and nothing else). A
+ * `setErrorHandler` call from inside a mount would instead change how every OTHER route
+ * in the adopter's scope answers — and the generated route files hand the mounts a plain
+ * plugin instance, so the helpers cannot know how wide that scope is. A scoped content-type
+ * parser was the other option; it would fix only the malformed-body half and would replace
+ * the adopter's own JSON parser for the whole scope.
+ *
+ * What it answers:
+ *  - a body Fastify's JSON parser refused → `400 { "error": "invalid_json" }`;
+ *  - any other deliberate 4xx (an auth hook's 401, schema validation, 413, 415) → rethrown,
+ *    so the enclosing scope's handler — the adopter's, or Fastify's default — answers it
+ *    exactly as it did before the mount existed;
+ *  - anything else → logged server-side, then `500 { "error": "internal" }`, with no SQL,
+ *    table, column or parameter in the body.
+ *
+ * An adopter who passes `routeOptions.errorHandler` keeps it: theirs wins, untouched.
+ */
+
+import type { FastifyReply, FastifyRequest, RouteShorthandOptions } from "fastify";
+import {
+  HTTP_STATUS_BAD_REQUEST,
+  HTTP_STATUS_INTERNAL,
+  INTERNAL_ERROR_BODY,
+  INVALID_JSON_BODY,
+  isDeliberateClientError,
+  isMalformedJsonBodyError,
+  logUnexpectedError,
+} from "../route-errors.js";
+
+export function contractRouteErrorHandler(
+  error: unknown,
+  _request: FastifyRequest,
+  reply: FastifyReply,
+): FastifyReply {
+  if (isMalformedJsonBodyError(error)) {
+    return reply.code(HTTP_STATUS_BAD_REQUEST).send(INVALID_JSON_BODY);
+  }
+  // Throwing from a route-level handler hands the error to the enclosing scope's handler.
+  if (isDeliberateClientError(error)) throw error;
+  logUnexpectedError(error);
+  return reply.code(HTTP_STATUS_INTERNAL).send(INTERNAL_ERROR_BODY);
+}
+
+/** The adopter's route options plus the contract error handler — unless they set their own. */
+export function withContractErrorHandler(ro: RouteShorthandOptions | undefined): RouteShorthandOptions {
+  const base = ro ?? {};
+  if (base.errorHandler !== undefined) return base;
+  return { ...base, errorHandler: contractRouteErrorHandler };
+}

package/src/fastify/index.ts

@@ -26,6 +26,8 @@ import type { RouteShorthandOptions } from "fastify";
 import type { SortAllowlist } from "../drizzle-fastify/filter-allowlist.js";
 import { sortOrderSpec } from "../drizzle-fastify/filter-allowlist.js";
 import { isTruthyFlag, contractErrorCode } from "../drizzle-fastify/util.js";
+import { parsePageBound, FilterParseError, SORT_EXPECTED } from "../drizzle-fastify/list-params.js";
+import { withContractErrorHandler } from "../drizzle-fastify/route-error-handler.js";
 
 // ---------------------------------------------------------------------------
 // Public surface
@@ -107,12 +109,14 @@ export function mountCrudRoutes(opts: CrudRoutesOptions): void {
 type SingleVerbOptions = Omit<CrudRoutesOptions, "expose">;
 
 /**
- * Build the route options Fastify wants. Just the consumer's routeOptions
- * (typed loosely to avoid Fastify's elaborate route-options union here).
- * Returns an empty object if nothing was provided.
+ * Build the route options Fastify wants: the consumer's routeOptions plus the
+ * route-scoped contract error handler shared with drizzle-fastify (an unexpected
+ * error answers `500 { error: "internal" }` instead of Fastify's default, which
+ * echoes the driver message; a malformed JSON body answers
+ * `400 { error: "invalid_json" }`). A consumer-supplied `errorHandler` wins.
  */
 function routeOpts(opts: SingleVerbOptions): RouteShorthandOptions {
-  return opts.routeOptions ?? {};
+  return withContractErrorHandler(opts.routeOptions);
 }
 
 export function mountListRoute(opts: SingleVerbOptions): void {
@@ -126,9 +130,15 @@ export function mountListRoute(opts: SingleVerbOptions): void {
     const withCount = isTruthyFlag(parsed["withCount"]);
 
     const readOpts: { limit?: number; offset?: number; orderBy?: [string, "asc" | "desc"] } = {};
-    const { limit, offset } = req.query as { limit?: string; offset?: string };
-    if (limit !== undefined) readOpts.limit = Number(limit);
-    if (offset !== undefined) readOpts.offset = Number(offset);
+    try {
+      const limit = parsePageBound(parsed, "limit");
+      const offset = parsePageBound(parsed, "offset");
+      if (limit !== undefined) readOpts.limit = limit;
+      if (offset !== undefined) readOpts.offset = offset;
+    } catch (err) {
+      if (err instanceof FilterParseError) return reply.code(400).send({ error: err.code, ...(err.details ?? {}) });
+      throw err;
+    }
 
     // Sort allowlist gate (cross-port REST contract). Only enforced when a
     // sortAllowlist is configured; absent → ?sort is ignored (back-compat).
@@ -137,7 +147,12 @@ export function mountListRoute(opts: SingleVerbOptions): void {
       if (sortParse.error) {
         // `field` is REQUIRED on the invalid_sort envelope cross-port (F20 ruling) —
         // it names the offending sort field instead of making the caller guess.
-        return reply.code(400).send({ error: contractErrorCode(sortParse.error), field: sortParse.field });
+        return reply.code(400).send({
+          error: contractErrorCode(sortParse.error),
+          field: sortParse.field,
+          expected: SORT_EXPECTED,
+          allowed: Object.keys(opts.sortAllowlist),
+        });
       }
       if (sortParse.orderBy) readOpts.orderBy = sortParse.orderBy;
     }
@@ -304,7 +319,7 @@ export interface MetaRouteOptions {
  */
 export function mountMetaRoute(opts: MetaRouteOptions): void {
   const path = `${opts.prefix ?? ""}${META_ROUTE_PATH}`;
-  opts.fastify.get(path, async (_req, reply) => {
+  opts.fastify.get(path, withContractErrorHandler(undefined), async (_req, reply) => {
     return reply
       .code(200)
       .header("content-type", META_CONTENT_TYPE)

package/src/hono/index.ts

@@ -29,6 +29,7 @@ import qs from "qs";
 import { contractErrorCode } from "../drizzle-fastify/util.js";
 import {
   parseFilterParams,
+  parsePageBound,
   FilterParseError,
   type ParseFilterResult,
 } from "../drizzle-fastify/filter-parser.js";
@@ -42,6 +43,10 @@ export type {
 } from "../drizzle-fastify/filter-allowlist.js";
 import { isTruthyFlag, coerceIdForColumn, firstRow } from "../drizzle-fastify/util.js";
 import { timestampWire } from "../timestamp-wire.js";
+// Every handler below is wrapped in guardRoute (an unexpected error answers
+// `500 { error: "internal" }`, logged server-side) and reads its body through
+// readJsonBody (a malformed body answers `400 { error: "invalid_json" }`).
+import { guardRoute, readJsonBody } from "./route-guard.js";
 // Back-compat re-export — the unsafe local copy was consolidated onto the one
 // shared (deprecated) helper so the three adapters can't silently diverge.
 export { parseId } from "../drizzle-fastify/util.js";
@@ -175,7 +180,7 @@ async function reReadThroughView(
 
 export function mountListRoute(opts: VerbOptions): void {
   const toWire = readWire(opts);
-  opts.app.get(opts.path, async (c) => {
+  opts.app.get(opts.path, guardRoute(async (c) => {
     try {
       const listSrc = readSource(opts);
       let q = opts.db.select().from(listSrc).$dynamic();
@@ -200,9 +205,10 @@ export function mountListRoute(opts: VerbOptions): void {
         if (parsed.offset !== undefined) q = q.offset(parsed.offset);
       } else {
         // No allowlists configured. Only limit/offset.
-        const flat = c.req.query();
-        if (flat.limit  !== undefined) q = q.limit(Number(flat.limit));
-        if (flat.offset !== undefined) q = q.offset(Number(flat.offset));
+        const limit = parsePageBound(qsParsed, "limit");
+        const offset = parsePageBound(qsParsed, "offset");
+        if (limit  !== undefined) q = q.limit(limit);
+        if (offset !== undefined) q = q.offset(offset);
       }
 
       // Await the query directly rather than calling `.all()`: the drizzle-orm
@@ -230,12 +236,12 @@ export function mountListRoute(opts: VerbOptions): void {
       }
       throw err;
     }
-  });
+  }));
 }
 
 export function mountGetRoute(opts: VerbOptions): void {
   const toWire = readWire(opts);
-  opts.app.get(`${opts.path}/:id`, async (c) => {
+  opts.app.get(`${opts.path}/:id`, guardRoute(async (c) => {
     const id = c.req.param("id") ?? "";
     // Compare against the PK's real type — a numeric-LOOKING id on a TEXT pk
     // must stay a string ('0123' ≠ '123'), or affinity matches the WRONG row.
@@ -244,14 +250,15 @@ export function mountGetRoute(opts: VerbOptions): void {
     if (idValue === undefined) return c.json({ error: "invalid_id" }, 400);
     const row = await firstRow(opts.db, getSrc, eq(getSrc.id, idValue));
     return row ? c.json(toWire(row)) : c.json({ error: "not_found" }, 404);
-  });
+  }));
 }
 
 export function mountCreateRoute(opts: VerbOptions): void {
   const toWire = echoWire(opts);
-  opts.app.post(opts.path, async (c) => {
-    const body = await c.req.json().catch(() => undefined);
-    const parsed = opts.insertSchema.safeParse(body);
+  opts.app.post(opts.path, guardRoute(async (c) => {
+    const read = await readJsonBody(c);
+    if (!read.ok) return read.response;
+    const parsed = opts.insertSchema.safeParse(read.body);
     if (!parsed.success) {
       return c.json({ error: "validation", issues: parsed.error.issues }, 400);
     }
@@ -269,15 +276,16 @@ export function mountCreateRoute(opts: VerbOptions): void {
     const row = (result as unknown[])[0];
     // Echo the row through the replica view so derived columns are present (#214).
     return c.json(toWire(await reReadThroughView(opts, row)), 201);
-  });
+  }));
 }
 
 export function mountUpdateRoute(opts: VerbOptions): void {
   const toWire = echoWire(opts);
-  const handler = async (c: Context) => {
+  const handler = guardRoute(async (c: Context) => {
     const id = c.req.param("id") ?? "";
-    const body = await c.req.json().catch(() => undefined);
-    const parsed = opts.updateSchema.safeParse(body);
+    const read = await readJsonBody(c);
+    if (!read.ok) return read.response;
+    const parsed = opts.updateSchema.safeParse(read.body);
     if (!parsed.success) {
       return c.json({ error: "validation", issues: parsed.error.issues }, 400);
     }
@@ -308,7 +316,7 @@ export function mountUpdateRoute(opts: VerbOptions): void {
     }
     const row = (result as unknown[])[0];
     return row ? c.json(toWire(await reReadThroughView(opts, row))) : c.json({ error: "not_found" }, 404);
-  };
+  });
   const path = `${opts.path}/:id`;
   // Cross-port REST contract (FR-008): the update verb is reachable via BOTH PATCH
   // and PUT, each routed to the same handler — as the drizzle-fastify flavor and
@@ -325,7 +333,7 @@ export function mountUpdateRoute(opts: VerbOptions): void {
 }
 
 export function mountDeleteRoute(opts: VerbOptions): void {
-  opts.app.delete(`${opts.path}/:id`, async (c) => {
+  opts.app.delete(`${opts.path}/:id`, guardRoute(async (c) => {
     const id = c.req.param("id") ?? "";
     // Compare against the PK's real type (see mountGetRoute) — a numeric-
     // LOOKING id on a TEXT pk would otherwise DELETE the wrong row (data loss).
@@ -346,7 +354,7 @@ export function mountDeleteRoute(opts: VerbOptions): void {
       return c.body(null, 204);
     }
     return c.json({ error: "not_found" }, 404);
-  });
+  }));
 }
 
 function extractRowCount(result: unknown): number {
@@ -387,7 +395,7 @@ export interface HonoMetaRouteOptions {
  */
 export function mountMetaRouteHono(opts: HonoMetaRouteOptions): void {
   const path = `${opts.prefix ?? ""}${META_ROUTE_PATH}`;
-  opts.app.get(path, (c) =>
+  opts.app.get(path, guardRoute((c) =>
     c.body(metaJson(opts.root), 200, { "content-type": META_CONTENT_TYPE }),
-  );
+  ));
 }

package/src/hono/mount-read-only.ts

@@ -5,13 +5,15 @@
 import type { Hono } from "hono";
 import { sql, eq, and, count } from "drizzle-orm";
 import qs from "qs";
-import { parseFilterParams, FilterParseError } from "../drizzle-fastify/filter-parser.js";
+import { parseFilterParams, parsePageBound, RAW_VIEW_MAX_LIMIT, FilterParseError } from "../drizzle-fastify/filter-parser.js";
 import type {
   FilterAllowlist,
   SortAllowlist,
 } from "../drizzle-fastify/filter-allowlist.js";
 import { isTruthyFlag, coerceIdForColumn, rawIdLiteral, contractErrorCode, viewBaseConfig } from "../drizzle-fastify/util.js";
 import { timestampWire } from "../timestamp-wire.js";
+// An unexpected error on a mounted route answers `500 { error: "internal" }`.
+import { guardRoute } from "./route-guard.js";
 
 // biome-ignore lint/suspicious/noExplicitAny: dynamic dispatch over user-supplied views
 type AnyView = any;
@@ -107,21 +109,16 @@ export function mountReadOnlyCrudRoutes(opts: MountReadOnlyOptions): void {
   const toWire = timestampWire(view);
 
   // ── List ──────────────────────────────────────────────────────────────────
-  app.get(path, async (c) => {
+  app.get(path, guardRoute(async (c) => {
     try {
       if (useRawSql) {
         const url = c.req.url;
         const qIdx = url.indexOf("?");
         const queryString = qIdx >= 0 ? url.slice(qIdx + 1) : "";
         const parsed = qs.parse(queryString) as Record<string, unknown>;
-        const limitVal = Math.min(
-          1000,
-          Math.max(1, Number(typeof parsed["limit"] === "string" ? parsed["limit"] : 1000)),
-        );
-        const offsetVal = Math.max(
-          0,
-          Number(typeof parsed["offset"] === "string" ? parsed["offset"] : 0),
-        );
+        // A bound that is not an integer in range is a 400, not silently clamped.
+        const limitVal = parsePageBound(parsed, "limit", RAW_VIEW_MAX_LIMIT) ?? RAW_VIEW_MAX_LIMIT;
+        const offsetVal = parsePageBound(parsed, "offset") ?? 0;
         const withCount = isTruthyFlag(parsed["withCount"]);
         // biome-ignore lint/suspicious/noExplicitAny: dynamic raw result
         const rows = (await rawRows(db, dialect, sql.raw(`SELECT * FROM "${viewName}" LIMIT ${limitVal} OFFSET ${offsetVal}`))) as any[];
@@ -175,10 +172,10 @@ export function mountReadOnlyCrudRoutes(opts: MountReadOnlyOptions): void {
       }
       throw err;
     }
-  });
+  }));
 
   // ── Get by ID ─────────────────────────────────────────────────────────────
-  app.get(`${path}/:id`, async (c) => {
+  app.get(`${path}/:id`, guardRoute(async (c) => {
     const id = c.req.param("id") ?? "";
     if (useRawSql) {
       // biome-ignore lint/suspicious/noExplicitAny: dynamic raw result
@@ -202,7 +199,7 @@ export function mountReadOnlyCrudRoutes(opts: MountReadOnlyOptions): void {
       .limit(1);
     const row = (rows as unknown[])[0];
     return row ? c.json(toWire(row)) : c.json({ error: "not_found" }, 404);
-  });
+  }));
 
   // ── Mutations explicitly rejected (405) ───────────────────────────────────
   const reject = (c: { req: { method: string }; json: (body: unknown, status: number) => unknown }) =>

package/src/hono/route-guard.ts

@@ -0,0 +1,58 @@
+/**
+ * Per-handler error guard for the Hono mount helpers — the Hono twin of
+ * drizzle-fastify's route-scoped error handler (route-error-handler.ts).
+ *
+ * Hono has no per-route error handler: `app.onError` is app-wide, so installing one from
+ * a mount would change how the adopter's OTHER routes answer. Wrapping each handler the
+ * mount registers keeps the change to exactly the routes it owns.
+ *
+ * An unexpected error is logged server-side and answered `500 { "error": "internal" }`.
+ * Hono's default would answer a bare-text `Internal Server Error` — no leak, but not the
+ * contract's JSON envelope, and different from the Fastify flavor this adapter promises
+ * to match on the wire. An `HTTPException` (anything carrying `getResponse`) was thrown
+ * on purpose and is rethrown to the adopter's `onError` / Hono's default untouched.
+ */
+
+import type { Context } from "hono";
+import {
+  HTTP_STATUS_BAD_REQUEST,
+  HTTP_STATUS_INTERNAL,
+  INTERNAL_ERROR_BODY,
+  INVALID_JSON_BODY,
+  logUnexpectedError,
+} from "../route-errors.js";
+
+type RouteHandler = (c: Context) => Promise<Response> | Response;
+
+function isHttpException(err: unknown): boolean {
+  return typeof (err as { getResponse?: unknown } | null)?.getResponse === "function";
+}
+
+export function guardRoute(handler: RouteHandler): RouteHandler {
+  return async (c: Context) => {
+    try {
+      return await handler(c);
+    } catch (err) {
+      if (isHttpException(err)) throw err;
+      logUnexpectedError(err);
+      return c.json(INTERNAL_ERROR_BODY, HTTP_STATUS_INTERNAL);
+    }
+  };
+}
+
+/** The outcome of reading a JSON request body: the value, or the 400 to answer. */
+export type JsonBodyRead = { ok: true; body: unknown } | { ok: false; response: Response };
+
+/**
+ * Read the request body as JSON. A body that does not parse — including an empty one —
+ * answers `400 { "error": "invalid_json" }`, matching the Fastify flavor. Before, the
+ * parse failure was swallowed into `undefined` and surfaced as a Zod `validation` error
+ * complaining that the body was not an object, which named the wrong problem.
+ */
+export async function readJsonBody(c: Context): Promise<JsonBodyRead> {
+  try {
+    return { ok: true, body: await c.req.json() };
+  } catch {
+    return { ok: false, response: c.json(INVALID_JSON_BODY, HTTP_STATUS_BAD_REQUEST) };
+  }
+}