@metaobjectsdev/runtime-ts 1.0.13 → 1.1.1-rc.1

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

@@ -15,7 +15,8 @@ import {
   ANY_TEMPORAL_EXPECTED, FORMAT_EXPECTED, PLUS_OFFSET_HINT,
   looksLikeUnencodedPlusOffset, matchesAnyTemporal, matchesFormat, utcIsoIfZoned, utcIsoInstant,
 } from "./filter-value-format.js";
-import { FIELD_SUBTYPE_TIMESTAMP } from "@metaobjectsdev/metadata";
+import { FIELD_SUBTYPE_DECIMAL, FIELD_SUBTYPE_TIMESTAMP } from "@metaobjectsdev/metadata";
+import { canonicalDecimal } from "../decimal-wire.js";
 
 // biome-ignore lint/suspicious/noExplicitAny: dynamic dispatch over user's Drizzle table
 type AnyTable = any;
@@ -215,14 +216,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, 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 "eq":  return eq(col as any, coerce(value, rule, col, field, op, dialect));
+    case "ne":  return ne(col as any, coerce(value, rule, col, field, op, dialect));
+    case "gt":  return gt(col as any, coerce(value, rule, col, field, op, dialect));
+    case "gte": return gte(col as any, coerce(value, rule, col, field, op, dialect));
+    case "lt":  return lt(col as any, coerce(value, rule, col, field, op, dialect));
+    case "lte": return lte(col as any, coerce(value, rule, col, field, op, dialect));
     case "in": {
-      const list = String(value).split(",").map((v) => coerce(v.trim(), rule, col, field, op));
+      const list = String(value).split(",").map((v) => coerce(v.trim(), rule, col, field, op, dialect));
       if (list.length > maxInList) {
         throw new FilterParseError("filter.in_too_large", `In-list size ${list.length} exceeds limit ${maxInList}.`, { field, limit: maxInList });
       }
@@ -327,10 +328,22 @@ function assertWellFormed(s: string, rule: FilterFieldRule, col: unknown, field:
 }
 
 /** 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 {
+function coerce(value: unknown, rule: FilterFieldRule, col: unknown, field: string, op: string, dialect: SqlDialect): unknown {
   if (value === null || value === undefined) return null;
   const s = typeof value === "string" ? value : String(value);
   assertWellFormed(s, rule, col, field, op);
+  // A decimal operand is exact text, never a number (ADR-0019 Amendment 1, W2): parsed with
+  // the JSON-number grammar and bound as its canonical string. MySQL compares a DECIMAL column
+  // with a string operand as DOUBLES, so there the operand is cast to a wide DECIMAL first.
+  // SQLite and D1 hold a decimal as a double (W4) and order every number before any text, so a
+  // text operand against a computed column (a view's sum or average has no NUMERIC affinity)
+  // would compare false in the wrong direction: the operand is bound as the number it is, exact
+  // to the 15 digits W4 promises.
+  if (rule.format === FIELD_SUBTYPE_DECIMAL) {
+    const canonical = canonicalDecimal(s) as string;
+    if (dialect === "mysql") return sql`CAST(${canonical} AS DECIMAL(65,30))`;
+    return dialect === "sqlite" ? Number(canonical) : canonical;
+  }
   // A timestamp bound is compared in the same UTC spelling the generated schemas store:
   // on SQLite/D1 the column is TEXT and compares as text. An instant field (`instant`, i.e.
   // not @localTime) reads a zoneless or date-only bound as UTC, as its write schema does —

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

@@ -13,11 +13,13 @@
 
 import {
   FIELD_SUBTYPE_DATE,
+  FIELD_SUBTYPE_DECIMAL,
   FIELD_SUBTYPE_TIME,
   FIELD_SUBTYPE_TIMESTAMP,
   FIELD_SUBTYPE_UUID,
 } from "@metaobjectsdev/metadata";
 import type { FilterValueFormat } from "./filter-allowlist.js";
+import { canonicalDecimal } from "../decimal-wire.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})?)?$/;
@@ -45,6 +47,7 @@ const CHECKS: Readonly<Record<FilterValueFormat, (s: string) => boolean>> = {
   [FIELD_SUBTYPE_TIME]: (s) => TIME_RE.test(s),
   [FIELD_SUBTYPE_TIMESTAMP]: isTimestamp,
   [FIELD_SUBTYPE_UUID]: (s) => UUID_RE.test(s),
+  [FIELD_SUBTYPE_DECIMAL]: (s) => canonicalDecimal(s) !== undefined,
 };
 
 /** The `expected` member of the `invalid_filter_value` envelope, per format. */
@@ -53,6 +56,7 @@ export const FORMAT_EXPECTED: Readonly<Record<FilterValueFormat, string>> = {
   [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)",
+  [FIELD_SUBTYPE_DECIMAL]: "decimal number (digits, optional fraction, optional exponent)",
 };
 
 /** `expected` for a temporal rule that does not say WHICH temporal format it is. */

package/src/drizzle-fastify/index.ts

@@ -29,11 +29,13 @@ export type { FilterAllowlist, SortAllowlist } from "./filter-allowlist.js";
 import { parseFilterParams, parsePageBound, FilterParseError } from "./filter-parser.js";
 import { isTruthyFlag, contractErrorCode, coerceIdForColumn, firstRow, extractRowCount } from "./util.js";
 import { timestampWire } from "../timestamp-wire.js";
+import { withDecimals } from "../decimal-wire.js";
 import { supportsReturning, type SqlDialect } from "../sql-dialect.js";
 import { withContractErrorHandler } from "./route-error-handler.js";
 import { validationErrorBody } from "../route-errors.js";
 export { isTruthyFlag, contractErrorCode, parseId, coerceIdForColumn } from "./util.js";
 export { timestampWire, canonicalTimestamp } from "../timestamp-wire.js";
+export { decimalWire, withDecimals, canonicalDecimal, parseDecimalInput, parseDecimalOperand } from "../decimal-wire.js";
 
 // ---------------------------------------------------------------------------
 // Loose types — we don't bind to a specific Drizzle backend so the helper
@@ -84,6 +86,13 @@ export interface CrudRoutesOptions {
   updateMethod?: "patch" | "put";
   filterAllowlist?: FilterAllowlist;
   sortAllowlist?:   SortAllowlist;
+  /**
+   * The names of the entity's `field.decimal` fields. A decimal is a canonical string on the
+   * wire on every dialect (ADR-0019 Amendment 1): Postgres and MySQL return the column's scale
+   * (`"100.5000"`) and SQLite hands back a number, so each row the routes send is rewritten
+   * under these keys. The generated route passes them; absent, rows are sent as read.
+   */
+  decimalColumns?: readonly string[];
   /** Dialect — required if filterAllowlist or sortAllowlist is set (for dialect-specific `like` lowering: SQLite lowers to GLOB to stay case-sensitive; ADR-0049). */
   dialect?: SqlDialect;
   /**
@@ -122,7 +131,7 @@ function readSource(opts: VerbOptions): AnyTable {
  * non-timestamp of the same name.
  */
 function readWire(opts: VerbOptions): (row: unknown) => unknown {
-  return timestampWire(readSource(opts));
+  return withDecimals(timestampWire(readSource(opts)), opts.decimalColumns);
 }
 
 /**
@@ -131,7 +140,7 @@ function readWire(opts: VerbOptions): (row: unknown) => unknown {
  * against the union of both sources.
  */
 function echoWire(opts: VerbOptions): (row: unknown) => unknown {
-  return timestampWire(opts.table, opts.readView);
+  return withDecimals(timestampWire(opts.table, opts.readView), opts.decimalColumns);
 }
 
 /** #214 — after a write to the base table, re-read the row THROUGH the replica

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 { withDecimals } from "../decimal-wire.js";
 import { withContractErrorHandler } from "./route-error-handler.js";
 
 // Loose Drizzle types — the helper works across libsql / better-sqlite3 / pg.
@@ -60,6 +61,8 @@ export interface M2mRouteOptions {
   targetColumn: string;
   /** Target entity PK column (physical column name, e.g. "id"). Defaults to "id". */
   targetPkColumn?: string;
+  /** The names of the TARGET entity's `field.decimal` fields, sent as canonical strings (ADR-0019 Amendment 1). */
+  decimalColumns?: readonly string[];
   /** Undirected self-join: union both junction FK columns on read. */
   symmetric: boolean;
   /**
@@ -87,7 +90,7 @@ export function mountM2mRoute(opts: M2mRouteOptions): void {
   const route = `${opts.path}/:id/${opts.relationName}`;
   // Route-scoped contract error handler — see route-error-handler.ts.
   const ro = withContractErrorHandler(opts.routeOptions);
-  const toWire = timestampWire(opts.targetTable);
+  const toWire = withDecimals(timestampWire(opts.targetTable), opts.decimalColumns);
 
   opts.fastify.get(route, ro, async (req, reply) => {
     const { id } = req.params as { id: string };

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

@@ -6,6 +6,7 @@ import { parseFilterParams, parsePageBound, RAW_VIEW_MAX_LIMIT, FilterParseError
 import type { FilterAllowlist, SortAllowlist } from "./filter-allowlist.js";
 import { isTruthyFlag, contractErrorCode, coerceIdForColumn, rawIdLiteral, viewBaseConfig } from "./util.js";
 import { timestampWire } from "../timestamp-wire.js";
+import { withDecimals } from "../decimal-wire.js";
 import { withContractErrorHandler } from "./route-error-handler.js";
 
 // biome-ignore lint/suspicious/noExplicitAny: dynamic dispatch over user-supplied views
@@ -20,7 +21,15 @@ export interface MountReadOnlyOptions {
   readonly filterAllowlist: FilterAllowlist;
   readonly sortAllowlist: SortAllowlist;
   readonly dialect: SqlDialect;
-  /** Override default ID column name (defaults to "id"). */
+  /**
+   * The column `GET /:id` addresses a row by: the KEY of that column in the Drizzle view
+   * (the field name), not its physical name. Defaults to "id". For a view declared with
+   * no columns (the raw-SQL path) it is the physical column name instead, because there
+   * is no key to look up.
+   *
+   * A view that declares columns and has none under this key has no row to address, so
+   * `GET /:id` answers `404 not_found` for every id.
+   */
   readonly idColumn?: string;
   /**
    * Fastify route-level hooks applied to every route this mounts — the same option
@@ -33,15 +42,31 @@ export interface MountReadOnlyOptions {
    * mount from an enclosing plugin scope works here too, and needs no option at all.)
    */
   readonly routeOptions?: RouteShorthandOptions;
+  /**
+   * False for an object with no single-column primary identity: an `object.report`, or
+   * a keyless projection. Mounts the list route and the collection POST refusal only,
+   * and no `/:id` route of any verb. Default true, which is today's behaviour.
+   */
+  readonly itemRoutes?: boolean;
+  /** The noun in the 405 message, which is free prose. Default "projection". */
+  readonly resource?: "projection" | "report";
+  /**
+   * The names of the view's `field.decimal` fields. A decimal is a canonical string on the wire
+   * on every dialect (ADR-0019 Amendment 1): Postgres and MySQL return the column's scale
+   * (`"100.5000"`), and SQLite hands back a number, a REAL for a computed one (a report's ratio,
+   * average or sum). Each row is rewritten under these keys. The generated route passes them;
+   * absent, rows are sent as read. Default none.
+   */
+  readonly decimalColumns?: readonly string[];
 }
 
-const REJECT_MUTATION = async (
+const rejectMutation = (resource: string) => async (
   request: { method: string },
   reply: { code: (n: number) => { send: (b: unknown) => unknown } },
 ) => {
   reply
     .code(405)
-    .send({ error: "method_not_allowed", message: `${request.method} is not supported on a projection (read-only).` });
+    .send({ error: "method_not_allowed", message: `${request.method} is not supported on a ${resource} (read-only).` });
 };
 
 function resolveViewName(view: AnyView): string | undefined {
@@ -128,11 +153,14 @@ export function mountReadOnlyCrudRoutes(opts: MountReadOnlyOptions): void {
   // 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 reject = rejectMutation(opts.resource ?? "projection");
+  const itemRoutes = opts.itemRoutes !== false;
 
   const viewName = resolveViewName(view);
   const useRawSql = isEmptyColumnView(view) && !!viewName;
   // The raw-SQL branch has no declared columns, so nothing names a timestamp there.
-  const toWire = timestampWire(view);
+  const timestamps = timestampWire(view);
+  const toWire = withDecimals(timestamps, opts.decimalColumns);
 
   // ── List ──────────────────────────────────────────────────────────────────
   fastify.get(path, ro, async (req, reply) => {
@@ -205,37 +233,46 @@ export function mountReadOnlyCrudRoutes(opts: MountReadOnlyOptions): void {
     }
   });
 
-  // ── Get by ID ─────────────────────────────────────────────────────────────
-  fastify.get(`${path}/:id`, ro, async (req, reply) => {
-    const { id } = req.params as { id: string };
-    if (useRawSql) {
-      // biome-ignore lint/suspicious/noExplicitAny: dynamic raw result
-      const rows = await rawRows(db, dialect, sql.raw(`SELECT * FROM ${quoteIdent(dialect, viewName)} WHERE ${quoteIdent(dialect, idCol)} = ${rawIdLiteral(id)} LIMIT 1`)) as any[];
-      const row = rows[0] ? camelizeRow(rows[0]) : undefined;
-      return row ?? reply.code(404).send({ error: "not_found" });
-    }
-    // biome-ignore lint/suspicious/noExplicitAny: Drizzle table/view column ref
-    const colRef = (view as any)[idCol];
-    // Compare against the PK's real type — a uuid/text key must NOT go through Number().
-    const idValue = coerceIdForColumn(colRef, id);
-    if (idValue === undefined) {
-      return reply.code(400).send({ error: "invalid_id" });
-    }
-    // Await + first row rather than `.get()` (libsql/better-sqlite3-only).
-    const rows = await db.select().from(view).where(
-      colRef !== undefined ? eq(colRef, idValue) : undefined
-    ).limit(1);
-    const row = (rows as unknown[])[0];
-    return row ? toWire(row) : reply.code(404).send({ error: "not_found" });
-  });
+  // A keyless object (`itemRoutes: false`) has nothing to address by id: no `/:id` route
+  // of any verb, so the framework's own 404 answers.
+  if (itemRoutes) {
+    // ── Get by ID ─────────────────────────────────────────────────────────────
+    fastify.get(`${path}/:id`, ro, async (req, reply) => {
+      const { id } = req.params as { id: string };
+      if (useRawSql) {
+        // biome-ignore lint/suspicious/noExplicitAny: dynamic raw result
+        const rows = await rawRows(db, dialect, sql.raw(`SELECT * FROM ${quoteIdent(dialect, viewName)} WHERE ${quoteIdent(dialect, idCol)} = ${rawIdLiteral(id)} LIMIT 1`)) as any[];
+        const row = rows[0] ? camelizeRow(rows[0]) : undefined;
+        return row ?? reply.code(404).send({ error: "not_found" });
+      }
+      // biome-ignore lint/suspicious/noExplicitAny: Drizzle table/view column ref
+      const colRef = (view as any)[idCol];
+      // No column under `idColumn`: there is nothing to compare the id against, and a query
+      // with no WHERE would answer with the view's first row. No row is addressable.
+      if (colRef === undefined) {
+        return reply.code(404).send({ error: "not_found" });
+      }
+      // Compare against the PK's real type — a uuid/text key must NOT go through Number().
+      const idValue = coerceIdForColumn(colRef, id);
+      if (idValue === undefined) {
+        return reply.code(400).send({ error: "invalid_id" });
+      }
+      // Await + first row rather than `.get()` (libsql/better-sqlite3-only).
+      const rows = await db.select().from(view).where(eq(colRef, idValue)).limit(1);
+      const row = (rows as unknown[])[0];
+      return row ? toWire(row) : reply.code(404).send({ error: "not_found" });
+    });
+  }
 
   // ── Mutations explicitly rejected (405) ───────────────────────────────────
   // PUT is here because the WRITABLE mount serves it (an alias of PATCH), so a
   // projection must reject it the same way the other three are rejected. Omitting it
   // left `PUT /<collection>/:id` falling through to Fastify's 404 — telling a caller
   // the resource does not exist when it plainly does and answers GET.
-  fastify.post(path, ro, REJECT_MUTATION);
-  fastify.patch(`${path}/:id`, ro, REJECT_MUTATION);
-  fastify.put(`${path}/:id`, ro, REJECT_MUTATION);
-  fastify.delete(`${path}/:id`, ro, REJECT_MUTATION);
+  fastify.post(path, ro, reject);
+  if (itemRoutes) {
+    fastify.patch(`${path}/:id`, ro, reject);
+    fastify.put(`${path}/:id`, ro, reject);
+    fastify.delete(`${path}/:id`, ro, reject);
+  }
 }

package/src/extract-object.ts

@@ -30,7 +30,7 @@ import {
   isMetaRoot,
   type MetaData,
   TYPE_OBJECT,
-  resolveObjectRef,
+  refTarget,
   FIELD_SUBTYPE_ENUM,
   FIELD_SUBTYPE_OBJECT,
   FIELD_SUBTYPE_STRING,
@@ -378,10 +378,9 @@ function attrString(node: MetaData, attr: string): string | null {
 }
 
 /**
- * Resolve a field's `@objectRef` to its MetaObject via the canonical ADR-0042 package-local
- * resolver (`resolveObjectRef` from `@metaobjectsdev/metadata`): an FQN ref (contains `::`)
- * matches EXACTLY on `resolutionKey()`; a bare ref resolves in the field's OWN declaring
- * package (`field.parent?.package ?? field.parent?.fileDefaultPackage`), else root-level.
+ * Resolve a field's `@objectRef` to its MetaObject: the target the loader bound
+ * (`refTarget` from `@metaobjectsdev/metadata`, ADR-0059 R7), resolved in the package of
+ * the node that declared the attribute, never by short name.
  *
  * #228: this previously called `MetaRoot.findObject(name)` directly — a bare-`name`-only
  * lookup — and, for an FQN ref (which never matches any object's bare `.name`), fell back to
@@ -404,8 +403,7 @@ function resolveFieldObjectRef(field: MetaField): MetaObject | undefined {
   // class check fails for a real root, so every field.object @objectRef falls to
   // the opaque-leaf guard and extraction silently stops descending.
   if (!isMetaRoot(root)) return undefined;
-  const referrerPkg = field.parent?.package ?? field.parent?.fileDefaultPackage ?? "";
-  const { node } = resolveObjectRef(root, ref, referrerPkg);
+  const node = refTarget(field, FIELD_ATTR_OBJECT_REF);
   return node !== undefined && node.type === TYPE_OBJECT ? (node as MetaObject) : undefined;
 }
 

package/src/hono/index.ts

@@ -45,6 +45,7 @@ export type {
 import { isTruthyFlag, coerceIdForColumn, firstRow, extractRowCount } from "../drizzle-fastify/util.js";
 import { supportsReturning, type SqlDialect } from "../sql-dialect.js";
 import { timestampWire } from "../timestamp-wire.js";
+import { withDecimals } from "../decimal-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" }`).
@@ -53,6 +54,7 @@ import { guardRoute, readJsonBody } from "./route-guard.js";
 // shared (deprecated) helper so the three adapters can't silently diverge.
 export { parseId } from "../drizzle-fastify/util.js";
 export { timestampWire, canonicalTimestamp } from "../timestamp-wire.js";
+export { decimalWire, withDecimals, canonicalDecimal, parseDecimalInput, parseDecimalOperand } from "../decimal-wire.js";
 
 // ---------------------------------------------------------------------------
 // Loose types — we don't bind to a specific Drizzle backend so the helper
@@ -104,6 +106,13 @@ export interface CrudRoutesOptions {
   updateMethod?: "patch" | "put";
   filterAllowlist?: FilterAllowlist;
   sortAllowlist?:   SortAllowlist;
+  /**
+   * The names of the entity's `field.decimal` fields. A decimal is a canonical string on the
+   * wire on every dialect (ADR-0019 Amendment 1): Postgres and MySQL return the column's scale
+   * (`"100.5000"`) and SQLite hands back a number, so each row the routes send is rewritten
+   * under these keys. The generated route passes them; absent, rows are sent as read.
+   */
+  decimalColumns?: readonly string[];
   /** Dialect — required if filterAllowlist or sortAllowlist is set (for dialect-specific `like` lowering: SQLite lowers to GLOB to stay case-sensitive; ADR-0049). */
   dialect?: SqlDialect;
 }
@@ -150,7 +159,7 @@ function readSource(opts: VerbOptions): AnyTable {
  * non-timestamp of the same name.
  */
 function readWire(opts: VerbOptions): (row: unknown) => unknown {
-  return timestampWire(readSource(opts));
+  return withDecimals(timestampWire(readSource(opts)), opts.decimalColumns);
 }
 
 /**
@@ -159,7 +168,7 @@ function readWire(opts: VerbOptions): (row: unknown) => unknown {
  * against the union of both sources.
  */
 function echoWire(opts: VerbOptions): (row: unknown) => unknown {
-  return timestampWire(opts.table, opts.readView);
+  return withDecimals(timestampWire(opts.table, opts.readView), opts.decimalColumns);
 }
 
 /** Re-read a just-written row through the replica view so the response carries the

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

@@ -13,6 +13,7 @@ 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";
+import { withDecimals } from "../decimal-wire.js";
 // An unexpected error on a mounted route answers `500 { error: "internal" }`.
 import { guardRoute } from "./route-guard.js";
 
@@ -30,8 +31,32 @@ export interface MountReadOnlyOptions {
   readonly filterAllowlist: FilterAllowlist;
   readonly sortAllowlist: SortAllowlist;
   readonly dialect: SqlDialect;
-  /** Override default ID column name (defaults to "id"). */
+  /**
+   * The column `GET /:id` addresses a row by: the KEY of that column in the Drizzle view
+   * (the field name), not its physical name. Defaults to "id". For a view declared with
+   * no columns (the raw-SQL path) it is the physical column name instead, because there
+   * is no key to look up.
+   *
+   * A view that declares columns and has none under this key has no row to address, so
+   * `GET /:id` answers `404 not_found` for every id.
+   */
   readonly idColumn?: string;
+  /**
+   * False for an object with no single-column primary identity: an `object.report`, or
+   * a keyless projection. Mounts the list route and the collection POST refusal only,
+   * and no `/:id` route of any verb. Default true, which is today's behaviour.
+   */
+  readonly itemRoutes?: boolean;
+  /** The noun in the 405 message, which is free prose. Default "projection". */
+  readonly resource?: "projection" | "report";
+  /**
+   * The names of the view's `field.decimal` fields. A decimal is a canonical string on the wire
+   * on every dialect (ADR-0019 Amendment 1): Postgres and MySQL return the column's scale
+   * (`"100.5000"`), and SQLite hands back a number, a REAL for a computed one (a report's ratio,
+   * average or sum). Each row is rewritten under these keys. The generated route passes them;
+   * absent, rows are sent as read. Default none.
+   */
+  readonly decimalColumns?: readonly string[];
 }
 
 function resolveViewName(view: AnyView): string | undefined {
@@ -108,11 +133,13 @@ async function rawRows(db: any, dialect: string | undefined, query: unknown): Pr
 export function mountReadOnlyCrudRoutes(opts: MountReadOnlyOptions): void {
   const { app, path, db, view, filterAllowlist, sortAllowlist, dialect } = opts;
   const idCol = opts.idColumn ?? "id";
+  const itemRoutes = opts.itemRoutes !== false;
 
   const viewName = resolveViewName(view);
   const useRawSql = isEmptyColumnView(view) && !!viewName;
   // The raw-SQL branch has no declared columns, so nothing names a timestamp there.
-  const toWire = timestampWire(view);
+  const timestamps = timestampWire(view);
+  const toWire = withDecimals(timestamps, opts.decimalColumns);
 
   // ── List ──────────────────────────────────────────────────────────────────
   app.get(path, guardRoute(async (c) => {
@@ -180,47 +207,59 @@ export function mountReadOnlyCrudRoutes(opts: MountReadOnlyOptions): void {
     }
   }));
 
-  // ── Get by ID ─────────────────────────────────────────────────────────────
-  app.get(`${path}/:id`, guardRoute(async (c) => {
-    const id = c.req.param("id") ?? "";
-    if (useRawSql) {
-      // biome-ignore lint/suspicious/noExplicitAny: dynamic raw result
-      const rows = (await rawRows(db, dialect, sql.raw(`SELECT * FROM ${quoteIdent(dialect, viewName)} WHERE ${quoteIdent(dialect, idCol)} = ${rawIdLiteral(id)} LIMIT 1`))) as any[];
-      const row = rows[0] ? camelizeRow(rows[0]) : undefined;
-      return row ? c.json(row) : c.json({ error: "not_found" }, 404);
-    }
-    // biome-ignore lint/suspicious/noExplicitAny: Drizzle view column ref
-    const colRef = (view as any)[idCol];
-    // Compare against the PK's real type — a uuid/text key must NOT go through Number().
-    const idValue = coerceIdForColumn(colRef, id);
-    if (idValue === undefined) {
-      return c.json({ error: "invalid_id" }, 400);
-    }
-    // `.get()` is likewise libsql/better-sqlite3-only; `.limit(1)` + await + [0]
-    // is the portable single-row read (#286).
-    const rows = await db
-      .select()
-      .from(view)
-      .where(colRef !== undefined ? eq(colRef, idValue) : undefined)
-      .limit(1);
-    const row = (rows as unknown[])[0];
-    return row ? c.json(toWire(row)) : c.json({ error: "not_found" }, 404);
-  }));
+  // A keyless object (`itemRoutes: false`) has nothing to address by id: no `/:id` route
+  // of any verb, so the framework's own 404 answers.
+  if (itemRoutes) {
+    // ── Get by ID ─────────────────────────────────────────────────────────────
+    app.get(`${path}/:id`, guardRoute(async (c) => {
+      const id = c.req.param("id") ?? "";
+      if (useRawSql) {
+        // biome-ignore lint/suspicious/noExplicitAny: dynamic raw result
+        const rows = (await rawRows(db, dialect, sql.raw(`SELECT * FROM ${quoteIdent(dialect, viewName)} WHERE ${quoteIdent(dialect, idCol)} = ${rawIdLiteral(id)} LIMIT 1`))) as any[];
+        const row = rows[0] ? camelizeRow(rows[0]) : undefined;
+        return row ? c.json(row) : c.json({ error: "not_found" }, 404);
+      }
+      // biome-ignore lint/suspicious/noExplicitAny: Drizzle view column ref
+      const colRef = (view as any)[idCol];
+      // No column under `idColumn`: there is nothing to compare the id against, and a query
+      // with no WHERE would answer with the view's first row. No row is addressable.
+      if (colRef === undefined) {
+        return c.json({ error: "not_found" }, 404);
+      }
+      // Compare against the PK's real type — a uuid/text key must NOT go through Number().
+      const idValue = coerceIdForColumn(colRef, id);
+      if (idValue === undefined) {
+        return c.json({ error: "invalid_id" }, 400);
+      }
+      // `.get()` is likewise libsql/better-sqlite3-only; `.limit(1)` + await + [0]
+      // is the portable single-row read (#286).
+      const rows = await db
+        .select()
+        .from(view)
+        .where(eq(colRef, idValue))
+        .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 resource = opts.resource ?? "projection";
   const reject = (c: { req: { method: string }; json: (body: unknown, status: number) => unknown }) =>
     c.json(
-      { error: "method_not_allowed", message: `${c.req.method} is not supported on a projection (read-only).` },
+      { error: "method_not_allowed", message: `${c.req.method} is not supported on a ${resource} (read-only).` },
       405,
     );
   // biome-ignore lint/suspicious/noExplicitAny: cross-version Hono typing
   app.post(path, reject as any);
-  // biome-ignore lint/suspicious/noExplicitAny: cross-version Hono typing
-  app.patch(`${path}/:id`, reject as any);
-  // PUT too — the writable mount serves it, so a projection must reject it rather
-  // than 404, which would deny a resource that answers GET on the same path.
-  // biome-ignore lint/suspicious/noExplicitAny: cross-version Hono typing
-  app.put(`${path}/:id`, reject as any);
-  // biome-ignore lint/suspicious/noExplicitAny: cross-version Hono typing
-  app.delete(`${path}/:id`, reject as any);
+  if (itemRoutes) {
+    // biome-ignore lint/suspicious/noExplicitAny: cross-version Hono typing
+    app.patch(`${path}/:id`, reject as any);
+    // PUT too — the writable mount serves it, so a projection must reject it rather
+    // than 404, which would deny a resource that answers GET on the same path.
+    // biome-ignore lint/suspicious/noExplicitAny: cross-version Hono typing
+    app.put(`${path}/:id`, reject as any);
+    // biome-ignore lint/suspicious/noExplicitAny: cross-version Hono typing
+    app.delete(`${path}/:id`, reject as any);
+  }
 }

package/src/index.ts

@@ -12,7 +12,8 @@ export type { Filter, FilterValue, QueryOpts } from "./query-builder.js";
 
 export type { FieldViewSpec, EntityViewSpec } from "./view.js";
 
-export type { ValidationResult } from "./validator-runner.js";
+export { runValidators } from "./validator-runner.js";
+export type { ValidationResult, RunValidatorsOpts } from "./validator-runner.js";
 export type { ValidationFailure } from "./errors.js";
 export {
   RuntimeError,

package/src/n2m-resolver.ts

@@ -22,6 +22,7 @@ import type { ColumnNamingStrategy, MetaData, MetaObject, MetaRoot } from "@meta
 import {
   TYPE_OBJECT, TYPE_FIELD, TYPE_RELATIONSHIP,
   RELATIONSHIP_ATTR_CARDINALITY, RELATIONSHIP_ATTR_OBJECT_REF, RELATIONSHIP_ATTR_THROUGH,
+  refTarget,
   CARDINALITY_MANY,
   DEFAULT_COLUMN_NAMING_STRATEGY,
   resolveColumnName,
@@ -68,8 +69,9 @@ export function resolveN2mDescriptor(
     if (child.attr(RELATIONSHIP_ATTR_THROUGH) === undefined) continue; // 1:N many — not M:N.
 
     const rel = child as MetaRelationship;
-    const targetEntityName = rel.attr(RELATIONSHIP_ATTR_OBJECT_REF) as string | undefined;
-    const joinEntityName = rel.attr(RELATIONSHIP_ATTR_THROUGH) as string | undefined;
+    // ADR-0059 R7: the loader bound @objectRef/@through once; read those targets.
+    const targetEntityName = refTarget(rel, RELATIONSHIP_ATTR_OBJECT_REF)?.name;
+    const joinEntityName = refTarget(rel, RELATIONSHIP_ATTR_THROUGH)?.name;
     if (!targetEntityName || !joinEntityName) {
       throw new MetadataError(
         `M:N relationship '${relationName}' on '${sourceEntity.name}' requires @objectRef + @through`,

package/src/net-format.ts

@@ -0,0 +1,37 @@
+// Run-time format checks for `field.uri` and `field.inet` (#234, ADR-0037 — Contract A).
+//
+// These are deliberately explicit, engine-neutral rules rather than `new URL()` or a
+// platform IP parser: the Python `run_validators` runner applies the SAME patterns, so the
+// two run-time runners agree on every input and not only on the pinned
+// validation-conformance probe set.
+
+// The IPv4 and IPv6 literal patterns the generated Zod schema uses
+// (`codegen-ts/src/templates/net-regex.ts`) — no hostnames, no CIDR, no padding, no
+// leading-zero octet; IPv6 includes the embedded-IPv4 tails.
+const IPV4_RE =
+  /^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$/;
+const IPV6_RE =
+  /^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|::(ffff(:0{1,4})?:)?((25[0-5]|(2[0-4]|1?[0-9])?[0-9])\.){3}(25[0-5]|(2[0-4]|1?[0-9])?[0-9])|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|(2[0-4]|1?[0-9])?[0-9])\.){3}(25[0-5]|(2[0-4]|1?[0-9])?[0-9]))$/;
+
+/** True when `value` is an IPv4 or IPv6 literal. */
+export function isInetLiteral(value: string): boolean {
+  return IPV4_RE.test(value) || IPV6_RE.test(value);
+}
+
+// Leading/trailing C0 controls and spaces, which a URL parser strips before parsing.
+const URI_PAD_RE = /^[\u0000- ]+|[\u0000- ]+$/g;
+// scheme ":" remainder — the remainder may hold anything, including a newline.
+const URI_SCHEME_RE = /^[A-Za-z][A-Za-z0-9+.-]*:([\s\S]*)$/;
+const URI_AUTHORITY_END_RE = /[/?#]/;
+
+/**
+ * True when `value` is an absolute URI: a scheme, a non-empty remainder and — when the
+ * remainder opens an authority with `//` — a non-empty authority. Padding is stripped first.
+ */
+export function isAbsoluteUri(value: string): boolean {
+  const rest = URI_SCHEME_RE.exec(value.replace(URI_PAD_RE, ""))?.[1];
+  if (rest === undefined || rest.length === 0) return false;
+  if (!rest.startsWith("//")) return true;
+  const authority = rest.slice(2).split(URI_AUTHORITY_END_RE)[0] ?? "";
+  return authority.length > 0;
+}