@metaobjectsdev/runtime-ts 1.0.8 → 1.0.9-rc.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/runtime-ts",
-  "version": "1.0.8",
+  "version": "1.0.9-rc.2",
   "description": "Node-side runtime helpers for MetaObjects: Fastify route builders, Drizzle filter/sort integration, Kysely drivers.",
   "type": "module",
   "main": "./dist/index.js",
@@ -64,8 +64,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@metaobjectsdev/metadata": "1.0.8",
-    "@metaobjectsdev/render": "1.0.8",
+    "@metaobjectsdev/metadata": "1.0.9-rc.2",
+    "@metaobjectsdev/render": "1.0.9-rc.2",
     "qs": "^6.13.0"
   },
   "peerDependencies": {

package/src/drizzle-fastify/filter-allowlist.ts

@@ -10,12 +10,30 @@ import {
   FILTER_OPS,
   OPS_BY_SUBTYPE,
   opsForSubType,
+  FIELD_SUBTYPE_DATE,
+  FIELD_SUBTYPE_TIME,
+  FIELD_SUBTYPE_TIMESTAMP,
+  FIELD_SUBTYPE_UUID,
   type FilterOp,
 } from "@metaobjectsdev/metadata";
 export { FILTER_OPS, OPS_BY_SUBTYPE, opsForSubType, type FilterOp };
 
 export type FilterSubType = "string" | "number" | "boolean" | "datetime";
 
+/**
+ * The wire formats a filter value can be checked against, beyond the coarse
+ * `FilterSubType`. Each is the `field.*` subtype whose Tier-1 wire encoding
+ * (docs/features/api-contract.md, "Type encodings") the value must match — so the
+ * values ARE the metamodel subtype names, not a second vocabulary.
+ */
+export const FILTER_VALUE_FORMATS = [
+  FIELD_SUBTYPE_DATE,
+  FIELD_SUBTYPE_TIME,
+  FIELD_SUBTYPE_TIMESTAMP,
+  FIELD_SUBTYPE_UUID,
+] as const;
+export type FilterValueFormat = (typeof FILTER_VALUE_FORMATS)[number];
+
 export interface FilterFieldRule {
   readonly ops: readonly FilterOp[];
   readonly subType: FilterSubType;
@@ -32,6 +50,21 @@ export interface FilterFieldRule {
    * both as strings under every dialect, so they are not governed by `timestampMode`.
    */
   readonly dateValues?: boolean;
+  /**
+   * The field's exact wire format, set by codegen for `field.date` / `field.time` /
+   * `field.timestamp` / `field.uuid`. The filter parser rejects a value that does not
+   * match it with `invalid_filter_value` instead of binding it — on SQLite a malformed
+   * date compared as text and silently matched nothing; on Postgres it was a driver
+   * error. Absent (an allowlist generated before this existed), a `datetime` value is
+   * still checked against the union of the three temporal formats.
+   */
+  readonly format?: FilterValueFormat;
+  /**
+   * The declared members of a `field.enum` (`@values`), set by codegen. A value that is
+   * not a member is rejected with `invalid_filter_value`. Absent, the parser falls back
+   * to the Drizzle column's own `enumValues` when it has them.
+   */
+  readonly enumValues?: readonly string[];
 }
 
 export type FilterAllowlist = Readonly<Record<string, FilterFieldRule>>;

package/src/drizzle-fastify/filter-parser.ts

@@ -4,6 +4,7 @@ import {
 } from "drizzle-orm";
 import type { FilterAllowlist, FilterOp, FilterFieldRule, SortAllowlist } from "./filter-allowlist.js";
 import { sortOrderSpec } from "./filter-allowlist.js";
+import { ANY_TEMPORAL_EXPECTED, FORMAT_EXPECTED, matchesAnyTemporal, matchesFormat } from "./filter-value-format.js";
 
 // biome-ignore lint/suspicious/noExplicitAny: dynamic dispatch over user's Drizzle table
 type AnyTable = any;
@@ -37,7 +38,37 @@ export class FilterParseError extends Error {
 const DEFAULT_MAX_NESTING = 5;
 const DEFAULT_MAX_IN_LIST = 100;
 
+/** Top-level list-query parameters this parser (or the mount around it) reads. A
+ *  filterable field that happens to share one of these names is addressed only through
+ *  `filter[<name>]`, so the bare-field check below never claims them. */
+const RESERVED_LIST_PARAMS: ReadonlySet<string> = new Set([
+  "filter", "sort", "limit", "offset", "search", "withCount",
+]);
+
+/**
+ * `?priority=low` on a list whose allowlist has `priority` is almost always a caller who
+ * meant `?filter[priority][eq]=low` — and silently ignoring it returns EVERY row, which
+ * reads as "the filter matched everything". Refuse it, naming the syntax that works.
+ *
+ * Only a bare name that IS a filterable field is refused. Any other unknown parameter —
+ * a cache-buster, a tracking tag, a param some proxy appends — is left alone, as before.
+ * TS-only (the other ports ignore unknown parameters): see docs/features/api-contract.md,
+ * "TS-only filter extensions".
+ */
+function rejectBareFieldParams(query: Record<string, unknown>, allowlist: FilterAllowlist): void {
+  for (const [key, value] of Object.entries(query)) {
+    if (RESERVED_LIST_PARAMS.has(key) || !Object.hasOwn(allowlist, key)) continue;
+    const shown = typeof value === "string" ? value : "<value>";
+    throw new FilterParseError(
+      "filter.bare_field",
+      `"${key}" is a filterable field, but a bare ?${key}= parameter is not a filter. Use filter[${key}][eq]=${shown}.`,
+      { field: key, expected: `filter[${key}][eq]=${shown}` },
+    );
+  }
+}
+
 export function parseFilterParams(opts: ParseFilterOpts): ParseFilterResult {
+  rejectBareFieldParams(opts.query, opts.allowlist);
   const result: ParseFilterResult = {};
 
   const limit = opts.query.limit;
@@ -154,14 +185,14 @@ function compileOp(
     throw new FilterParseError("filter.unsupported_op", `Op "${op}" not supported for field "${field}".`, { field, op, allowed: rule.ops });
   }
   switch (op as FilterOp) {
-    case "eq":  return eq(col as any, coerce(value, rule.subType, field, op, rule.dateValues));
-    case "ne":  return ne(col as any, coerce(value, rule.subType, field, op, rule.dateValues));
-    case "gt":  return gt(col as any, coerce(value, rule.subType, field, op, rule.dateValues));
-    case "gte": return gte(col as any, coerce(value, rule.subType, field, op, rule.dateValues));
-    case "lt":  return lt(col as any, coerce(value, rule.subType, field, op, rule.dateValues));
-    case "lte": return lte(col as any, coerce(value, rule.subType, field, op, rule.dateValues));
+    case "eq":  return eq(col as any, coerce(value, rule, col, field, op));
+    case "ne":  return ne(col as any, coerce(value, rule, col, field, op));
+    case "gt":  return gt(col as any, coerce(value, rule, col, field, op));
+    case "gte": return gte(col as any, coerce(value, rule, col, field, op));
+    case "lt":  return lt(col as any, coerce(value, rule, col, field, op));
+    case "lte": return lte(col as any, coerce(value, rule, col, field, op));
     case "in": {
-      const list = String(value).split(",").map((v) => coerce(v.trim(), rule.subType, field, op, rule.dateValues));
+      const list = String(value).split(",").map((v) => coerce(v.trim(), rule, col, field, op));
       if (list.length > maxInList) {
         throw new FilterParseError("filter.in_too_large", `In-list size ${list.length} exceeds limit ${maxInList}.`, { field, limit: maxInList });
       }
@@ -186,7 +217,7 @@ function compileOp(
       // isNull's value is always coerced as boolean (true/false), regardless of the
       // field's declared subType — the operator is "is the value null?", not "is X
       // equal to null?". Field subtype is irrelevant.
-      const b = coerce(value, "boolean", field, op) as boolean;
+      const b = coerceAs(value, "boolean", field, op) as boolean;
       return b ? isNull(col as any) : not(isNull(col as any));
     }
   }
@@ -213,7 +244,54 @@ export function likePatternToGlob(pattern: string): string {
   return out;
 }
 
-function coerce(value: unknown, subType: string, field: string, op: string, dateValues?: boolean): unknown {
+function invalidValue(
+  field: string,
+  op: string,
+  s: string,
+  expected: string,
+  extra: Record<string, unknown> = {},
+): FilterParseError {
+  return new FilterParseError(
+    "filter.invalid_value",
+    `Field "${field}" op "${op}" requires ${expected}, got "${s}".`,
+    { field, op, expected, ...extra },
+  );
+}
+
+/** A Drizzle column's own enum members (`text(..., { enum })`, `pgEnum`), if it has them. */
+function columnEnumValues(col: unknown): readonly string[] | undefined {
+  const v = (col as { enumValues?: unknown } | null | undefined)?.enumValues;
+  return Array.isArray(v) && v.length > 0 && v.every((m) => typeof m === "string") ? (v as string[]) : undefined;
+}
+
+/**
+ * Refuse a value that cannot be the field's type BEFORE it is bound. Without this a
+ * malformed date on SQLite compared as text and silently matched nothing (200 `[]`),
+ * and on Postgres the driver refused the cast (a 500) — either way the caller could not
+ * tell a typo from an empty result. The envelope is the cross-port `invalid_filter_value`,
+ * carrying `op` and `expected` as the number/boolean checks already did.
+ */
+function assertWellFormed(s: string, rule: FilterFieldRule, col: unknown, field: string, op: string): void {
+  const members = rule.enumValues ?? columnEnumValues(col);
+  if (members !== undefined && !members.includes(s)) {
+    throw invalidValue(field, op, s, `one of: ${members.join(", ")}`, { allowed: [...members] });
+  }
+  if (rule.format !== undefined) {
+    if (!matchesFormat(rule.format, s)) throw invalidValue(field, op, s, FORMAT_EXPECTED[rule.format]);
+  } else if (rule.subType === "datetime" && !matchesAnyTemporal(s)) {
+    throw invalidValue(field, op, s, ANY_TEMPORAL_EXPECTED);
+  }
+}
+
+/** Check a comparison value against the field's rule, then coerce it for binding. */
+function coerce(value: unknown, rule: FilterFieldRule, col: unknown, field: string, op: string): unknown {
+  if (value === null || value === undefined) return null;
+  const s = typeof value === "string" ? value : String(value);
+  assertWellFormed(s, rule, col, field, op);
+  return coerceAs(s, rule.subType, field, op, rule.dateValues);
+}
+
+function coerceAs(value: unknown, subType: string, field: string, op: string, dateValues?: boolean): unknown {
   if (value === null || value === undefined) return null;
   const s = typeof value === "string" ? value : String(value);
   switch (subType) {
@@ -224,7 +302,8 @@ function coerce(value: unknown, subType: string, field: string, op: string, date
       throw new FilterParseError("filter.invalid_value", `Field "${field}" op "${op}" requires boolean, got "${s}".`, { field, op, expected: "boolean" });
     }
     case "number":   {
-      const n = Number(s);
+      // `Number("")` and `Number(" ")` are 0 — an empty bound is not the number zero.
+      const n = s.trim() === "" ? Number.NaN : Number(s);
       if (!Number.isFinite(n)) {
         throw new FilterParseError("filter.invalid_value", `Field "${field}" op "${op}" requires number, got "${s}".`, { field, op, expected: "number" });
       }

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

@@ -29,6 +29,7 @@ export type { FilterAllowlist, SortAllowlist } from "./filter-allowlist.js";
 import { parseFilterParams, 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 {

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

@@ -5,6 +5,7 @@ import { parseFilterParams, 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;

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,7 @@ 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 { withContractErrorHandler } from "../drizzle-fastify/route-error-handler.js";
 
 // ---------------------------------------------------------------------------
 // Public surface
@@ -107,12 +108,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 {
@@ -304,7 +307,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

@@ -42,6 +42,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 +179,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();
@@ -230,12 +234,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 +248,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 +274,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 +314,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 +331,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 +352,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 +393,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

@@ -12,6 +12,8 @@ import type {
 } 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,7 +109,7 @@ 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;
@@ -175,10 +177,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 +204,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) };
+  }
+}