Merge branch 'worktree-agent-a61a1c156ca160adf'

Author: dmealing

docs/features/api-contract.md

@@ -146,7 +146,7 @@ or use the TS-only `?search` extension, which IS case-insensitive.
 
 ### TS-only filter extensions (not part of the cross-port contract)
 
-The TypeScript runtime parser ships six filter behaviors beyond the nine
+The TypeScript runtime parser ships seven filter behaviors beyond the nine
 operators. They are **NOT part of the cross-port REST contract** — the other
 ports (Java, Kotlin, Python, C#) do not implement them, and a relying adopter
 must not assume them on a non-TS backend. They are deliberately deferred until
@@ -160,6 +160,7 @@ added cross-port later as a purely additive, non-breaking change):
 | leading-wildcard gating | a `like` pattern starting with `%` → HTTP 400 (`filter.leading_wildcard_disallowed`) |
 | filter nesting-depth cap | rejects deeply-nested `or`/`and` (tied to the combinators) |
 | bare filterable-field parameter | `?priority=low` where `priority` is in the allowlist → HTTP 400 `{ "error": "filter.bare_field", "field": "priority", "expected": "filter[priority][eq]=low" }` instead of silently returning every row. Any other unknown parameter (a cache-buster, a tracking tag) is still ignored, and the reserved list parameters (`filter`, `sort`, `limit`, `offset`, `search`, `withCount`) are never claimed |
+| filter-value format check | a comparison value (`eq`/`ne`/`gt`/`gte`/`lt`/`lte`, and every element of an `in` list) that cannot be the field's type → HTTP 400 `{ "error": "invalid_filter_value", "field": "publishedOn", "op": "gte", "expected": "date (YYYY-MM-DD)" }` instead of reaching SQL, where SQLite compared the text and silently returned `[]` and Postgres failed the cast. Checked per field: `field.date` (a real calendar day), `field.time` (`HH:MM[:SS[.fff]]`), `field.timestamp` (a date, optionally with a time and a `Z`/offset), `field.uuid` (`8-4-4-4-12` hex), `field.enum` (a declared member — the response adds `allowed`), numbers (an empty value is not `0`) and booleans. The generated `<Entity>FilterAllowlist` carries the `format` / `enumValues` this needs; an allowlist generated before them still has a temporal value checked against all three temporal formats and an enum checked against the Drizzle column's own members. The envelope is the cross-port one; what is TS-only is refusing a malformed comparison value — the other ports pass it through to the database and only the `isNull` value is corpus-gated |
 
 **Leading-wildcard gating is fail-closed with no metadata opt-in.** The
 generated `<Entity>FilterAllowlist` hardcodes `leadingWildcard: false` on every
@@ -178,6 +179,29 @@ safety limit, not a feature — TS enforces it, the other ports currently do not
 Unifying that cap cross-port is the one item here worth doing regardless of
 feature demand (it is a consistency/safety divergence, not a capability).
 
+### TS-only error responses (not part of the cross-port contract)
+
+The TypeScript mount helpers (`@metaobjectsdev/runtime-ts/drizzle-fastify`,
+`/fastify` and `/hono`) pin two responses the contract leaves open — HTTP 5xx is
+implementation-defined below, and no corpus scenario sends a malformed body. Both
+use the contract's `{ "error": "<code>" }` envelope, and both are scoped to the
+routes the helpers mount: an adopter's own routes, and a Fastify `setErrorHandler`
+or Hono `onError` the adopter installed, answer exactly as they did before.
+
+| Response | When |
+|---|---|
+| malformed JSON body | a `POST`/`PATCH`/`PUT` body that does not parse as JSON (an empty body sent as `application/json` included) → HTTP 400 `{ "error": "invalid_json" }`. Before, Fastify answered its own `{ "statusCode": 400, "code": "FST_ERR_CTP_INVALID_JSON_BODY", … }` and Hono a Zod `validation` error about a missing object |
+| unexpected server error | anything that is not a filter, validation, not-found or constraint answer — a query against a column the database no longer has, a driver failure → HTTP 500 `{ "error": "internal" }`, the code the cross-port reference servers already use. The body names no SQL, table, column or bound parameter; the full error goes to the server log (`console.error`). Before, Fastify's default handler echoed the driver message, which for Drizzle is the query text and its parameter values |
+
+How each framework scopes it: on Fastify, the helpers pass a **route-level**
+`errorHandler` in the options of each route they register (Fastify applies it to
+that route only). A deliberate 4xx raised on such a route — an auth `preHandler`'s
+401, schema validation, 413, 415 — is rethrown to the enclosing scope's handler
+untouched, and an `errorHandler` you pass in `routeOptions` replaces the helpers'
+own. Hono has no per-route handler (`app.onError` is app-wide), so the helpers wrap
+each handler they register instead; an `HTTPException` is rethrown to your
+`onError`.
+
 ### Sort + pagination
 
 - `sort=<field>:asc|desc` — single sort key (multi-sort not in the
@@ -300,7 +324,8 @@ Non-2xx responses MUST return:
 - HTTP 400 — validation and filter/sort-parser errors.
 - HTTP 404 — `{ "error": "not_found" }`.
 - HTTP 409 — a declared constraint conflicting with existing state (a uniqueness or referential violation); a constraint rejecting the request's own value stays a 400.
-- HTTP 5xx — implementation-defined.
+- HTTP 5xx — implementation-defined (the TS mount helpers answer
+  `{ "error": "internal" }` and nothing more — see "TS-only error responses").
 
 #### Filter and sort errors name the field
 
@@ -491,9 +516,10 @@ codegen status" above and "Verified by" below, and
 
 What's still genuinely open:
 
-- The six **TS-only filter extensions** (`?search=`, `filter[or]` /
+- The seven **TS-only filter extensions** (`?search=`, `filter[or]` /
   `filter[and]` nesting, leading-wildcard gating, the nesting-depth cap,
-  the `in`-list size cap, and the bare filterable-field 400) — see "TS-only filter extensions" above.
+  the `in`-list size cap, the bare filterable-field 400, and the
+  filter-value format check) — see "TS-only filter extensions" above.
   None touch the metamodel vocabulary, so any of them can be promoted
   cross-port later as a purely additive, non-breaking change if real
   consumer demand shows up.

server/typescript/packages/codegen-ts/src/templates/filter-allowlist.ts

@@ -12,8 +12,11 @@ import {
   FIELD_SUBTYPE_TIME,
   FIELD_SUBTYPE_TIMESTAMP,
   FIELD_SUBTYPE_CURRENCY,
+  FIELD_SUBTYPE_UUID,
+  FIELD_SUBTYPE_ENUM,
   opsForField,
 } from "@metaobjectsdev/metadata";
+import { enumValues } from "../enum-meta.js";
 import { sortableFields, declaredSortDefaultOrder } from "./filter-shared.js";
 import type { RenderContext } from "../render-context.js";
 
@@ -41,6 +44,38 @@ function filterSubTypeFor(fieldSubType: string): "string" | "number" | "boolean"
   return "string";
 }
 
+/**
+ * Field subtypes whose filter values have an exact wire format the coarse FilterSubType
+ * cannot express ("datetime" is three formats; a uuid is a "string"). The emitted
+ * `format` value IS the subtype name — runtime-ts keys its checks on the same constants.
+ */
+const VALUE_FORMAT_SUBTYPES = new Set<string>([
+  FIELD_SUBTYPE_DATE,
+  FIELD_SUBTYPE_TIME,
+  FIELD_SUBTYPE_TIMESTAMP,
+  FIELD_SUBTYPE_UUID,
+]);
+
+/**
+ * The `format` / `enumValues` members of a rule, so runtime-ts's filter parser can refuse
+ * a value that cannot be the field's type (`invalid_filter_value`) instead of binding it —
+ * a malformed date compared as text on SQLite and silently matched nothing. Scalar fields
+ * only: an array field's filter value is not one element of the declared type.
+ */
+function valueShape(f: MetaField): string {
+  if (f.resolvedIsArray()) return "";
+  if (VALUE_FORMAT_SUBTYPES.has(f.subType)) return `, format: ${JSON.stringify(f.subType)} as const`;
+  if (f.subType === FIELD_SUBTYPE_ENUM) {
+    // Member SYMBOLS for string- and int-backed enums alike: an int-backed column's codec
+    // maps the symbol to its integer when the value is bound.
+    const members = enumValues(f);
+    if (members !== undefined && members.length > 0) {
+      return `, enumValues: [${members.map((m) => JSON.stringify(m)).join(", ")}] as const`;
+    }
+  }
+  return "";
+}
+
 function filterableFields(entity: MetaObject, exclude?: string): MetaField[] {
   // fields() returns effective fields, so inherited fields (from extends:/super:) are included in allowlists.
   return entity
@@ -80,7 +115,7 @@ export const ${entity.name}FilterAllowlist = {} as const satisfies FilterAllowli
       const dateValues = ctx?.timestampMode === "date" && f.subType === FIELD_SUBTYPE_TIMESTAMP
         ? ", dateValues: true as const"
         : "";
-      return `  ${f.name}: { ops: [${ops}] as const, subType: ${JSON.stringify(sub)} as const, leadingWildcard: false${dateValues} }`;
+      return `  ${f.name}: { ops: [${ops}] as const, subType: ${JSON.stringify(sub)} as const, leadingWildcard: false${dateValues}${valueShape(f)} }`;
     })
     .join(",\n");
   return code`

server/typescript/packages/codegen-ts/test/fixtures/filter-fixture.json

@@ -35,6 +35,30 @@
             { "identity.primary": { "name": "id", "@fields": "id" } }
           ]
         }
+      },
+      {
+        "object.entity": {
+          "name": "Book",
+          "children": [
+            { "source.rdb": { "@table": "books" } },
+            { "field.long": { "name": "id" } },
+            { "field.date": { "name": "publishedOn", "@filterable": true } },
+            { "field.time": { "name": "opensAt", "@filterable": true } },
+            { "field.timestamp": { "name": "updatedAt", "@filterable": true } },
+            { "field.uuid": { "name": "externalId", "@filterable": true } },
+            { "field.enum": { "name": "genre", "@filterable": true, "@values": ["fiction", "poetry"] } },
+            {
+              "field.enum": {
+                "name": "priority",
+                "@filterable": true,
+                "@values": ["low", "high"],
+                "@intValueMap": { "low": 1, "high": 2 }
+              }
+            },
+            { "field.string": { "name": "title", "@filterable": true } },
+            { "identity.primary": { "name": "id", "@fields": "id" } }
+          ]
+        }
       }
     ]
   }

server/typescript/packages/codegen-ts/test/templates/filter-allowlist.test.ts

@@ -37,6 +37,24 @@ describe("renderFilterAllowlist", () => {
     expect(out).not.toContain("internalNote");
   });
 
+  // The coarse subType ("datetime", "string") cannot tell the runtime a date from a
+  // time, or a uuid or enum from free text — so a malformed bound reached SQL and
+  // matched nothing. The rule now carries the exact wire format / enum members, and
+  // runtime-ts's parser answers `invalid_filter_value` for a value that does not fit
+  // (runtime-ts test/drizzle-fastify/filter-value-format.test.ts pins that half).
+  test("carries the wire format for date/time/timestamp/uuid and the members of an enum", async () => {
+    const out = renderFilterAllowlist(await loadEntity("Book")).toString();
+    expect(out).toMatch(/publishedOn:\s*\{[^}]*format: "date"/);
+    expect(out).toMatch(/opensAt:\s*\{[^}]*format: "time"/);
+    expect(out).toMatch(/updatedAt:\s*\{[^}]*format: "timestamp"/);
+    expect(out).toMatch(/externalId:\s*\{[^}]*format: "uuid"/);
+    expect(out).toMatch(/genre:\s*\{[^}]*enumValues: \["fiction", "poetry"\]/);
+    // An int-backed enum is filtered by MEMBER name too (the column codec maps it).
+    expect(out).toMatch(/priority:\s*\{[^}]*enumValues: \["low", "high"\]/);
+    // A plain string carries neither.
+    expect(out).not.toMatch(/title:\s*\{[^}]*(format|enumValues)/);
+  });
+
   test("entity with no filterable fields emits empty allowlist", async () => {
     const { root } = await new MetaDataLoader().load([new FileSource(FIXTURE)]);
     const subscriber = root.objects().find((c) => c.name === "Subscriber")!;

server/typescript/packages/runtime-ts/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>>;

server/typescript/packages/runtime-ts/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;
@@ -184,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 });
       }
@@ -216,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));
     }
   }
@@ -243,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) {
@@ -254,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" });
       }