@metaobjectsdev/runtime-ts 1.0.4 → 1.0.5-rc.10

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

@@ -261,7 +261,11 @@ function ensureArray(v: unknown, key: string): unknown[] {
   }
   // Defensive — qs.parse normally produces an object/array; this branch is
   // only reachable if a caller hand-constructs a malformed query object.
-  throw new FilterParseError("filter.invalid_value", `Expected array for "${key}".`, { key });
+  //
+  // `field` (not `key`) because this maps to the cross-port `invalid_filter_value`
+  // envelope, which REQUIRES `field` naming the offending filter key — here the
+  // `or`/`and` connector that was handed a non-array.
+  throw new FilterParseError("filter.invalid_value", `Expected array for "${key}".`, { field: key });
 }
 
 function parseSort(spec: string, table: AnyTable, sortAllowlist: SortAllowlist): SQLWrapper[] {
@@ -290,7 +294,7 @@ function parseSort(spec: string, table: AnyTable, sortAllowlist: SortAllowlist):
   );
   const order = orderRaw.toLowerCase();
   if (order !== "asc" && order !== "desc") {
-    throw new FilterParseError("sort.invalid_order", `Sort order must be asc|desc, got "${orderRaw}".`, { expected: "asc | desc" });
+    throw new FilterParseError("sort.invalid_order", `Sort order must be asc|desc, got "${orderRaw}".`, { field, expected: "asc | desc" });
   }
   const col = table[field];
   return [order === "asc" ? asc(col as any) : desc(col as any)];

package/src/drizzle-fastify/index.ts

@@ -22,8 +22,10 @@ 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 { isTruthyFlag, contractErrorCode, coerceIdForColumn } from "./util.js";
+import { isTruthyFlag, contractErrorCode, coerceIdForColumn, firstRow } from "./util.js";
+import { timestampWire } from "../timestamp-wire.js";
 export { isTruthyFlag, contractErrorCode, parseId, coerceIdForColumn } from "./util.js";
+export { timestampWire, canonicalTimestamp } from "../timestamp-wire.js";
 
 // ---------------------------------------------------------------------------
 // Loose types — we don't bind to a specific Drizzle backend so the helper
@@ -67,8 +69,9 @@ export interface CrudRoutesOptions {
    */
   routeOptions?: RouteShorthandOptions;
   /**
-   * HTTP method for the update verb. Defaults to "patch". Set to "put" to
-   * preserve a legacy API contract that already uses PUT for updates.
+   * Restrict the update verb to ONE HTTP method. Absent (the default) mounts
+   * the update handler on both PATCH and PUT, as the cross-port REST contract
+   * requires.
    */
   updateMethod?: "patch" | "put";
   filterAllowlist?: FilterAllowlist;
@@ -105,6 +108,24 @@ function readSource(opts: VerbOptions): AnyTable {
   return opts.readView ?? opts.table;
 }
 
+/**
+ * Wire mapper for rows READ through `readSource` — canonicalized against
+ * exactly that source, since a view may shadow a table column with a
+ * non-timestamp of the same name.
+ */
+function readWire(opts: VerbOptions): (row: unknown) => unknown {
+  return timestampWire(readSource(opts));
+}
+
+/**
+ * Wire mapper for a WRITE ECHO: `reReadThroughView` answers with the replica
+ * view's row but falls back to the table row, so the echo is canonicalized
+ * against the union of both sources.
+ */
+function echoWire(opts: VerbOptions): (row: unknown) => unknown {
+  return timestampWire(opts.table, opts.readView);
+}
+
 /** #214 — after a write to the base table, re-read the row THROUGH the replica
  *  view by PK so the response carries derived (origin.passthrough) columns. When
  *  there is no `readView`, return the write row unchanged (current behaviour). */
@@ -140,6 +161,7 @@ function routeOpts(opts: VerbOptions): RouteShorthandOptions {
 }
 
 export function mountListRoute(opts: VerbOptions): void {
+  const toWire = readWire(opts);
   opts.fastify.get(opts.path, routeOpts(opts), async (req, reply) => {
     try {
       // #214 — a write-through entity reads through its replica view.
@@ -195,7 +217,7 @@ export function mountListRoute(opts: VerbOptions): void {
       // drizzle-orm node-postgres query builder is thenable but has no `.all()`
       // method (that is a libsql/better-sqlite3-only API). Awaiting works on
       // both dialects and is what makes this helper genuinely Postgres-capable.
-      const rows = await q;
+      const rows = (await q as unknown[]).map(toWire);
 
       if (!withCount) return rows;
 
@@ -215,6 +237,7 @@ export function mountListRoute(opts: VerbOptions): void {
 }
 
 export function mountGetRoute(opts: VerbOptions): void {
+  const toWire = readWire(opts);
   opts.fastify.get(`${opts.path}/:id`, routeOpts(opts), async (req, reply) => {
     const { id } = req.params as { id: string };
     const discCond = discriminatorCond(opts);
@@ -227,20 +250,13 @@ export function mountGetRoute(opts: VerbOptions): void {
       return reply.code(400).send({ error: "invalid_id" });
     }
     const idCond = eq(src.id, idValue);
-    // Await + take the first row rather than `.get()` — `.get()` is a
-    // libsql/better-sqlite3-only method; the node-postgres builder is thenable
-    // but has no `.get()`. Awaiting works on both dialects.
-    const rows = await opts.db
-      .select()
-      .from(src)
-      .where(discCond ? and(idCond, discCond) : idCond)
-      .limit(1);
-    const row = (rows as unknown[])[0];
-    return row ?? reply.code(404).send({ error: "not_found" });
+    const row = await firstRow(opts.db, src, discCond ? and(idCond, discCond) : idCond);
+    return row ? toWire(row) : reply.code(404).send({ error: "not_found" });
   });
 }
 
 export function mountCreateRoute(opts: VerbOptions): void {
+  const toWire = echoWire(opts);
   opts.fastify.post(opts.path, routeOpts(opts), async (req, reply) => {
     const parsed = opts.insertSchema.safeParse(req.body);
     if (!parsed.success) {
@@ -264,11 +280,12 @@ export function mountCreateRoute(opts: VerbOptions): void {
     const row = (result as unknown[])[0];
     // #214 — read-your-writes: re-read through the replica view so the response
     // carries derived (origin.passthrough) columns the base table excludes.
-    return reply.code(201).send(await reReadThroughView(opts, row));
+    return reply.code(201).send(toWire(await reReadThroughView(opts, row)));
   });
 }
 
 export function mountUpdateRoute(opts: VerbOptions): void {
+  const toWire = echoWire(opts);
   const handler = async (
     req: { params: unknown; body: unknown },
     reply: { code: (n: number) => { send: (b: unknown) => unknown } },
@@ -286,6 +303,26 @@ export function mountUpdateRoute(opts: VerbOptions): void {
       const { [opts.discriminator.column]: _omit, ...rest } = data;
       data = rest;
     }
+    // A patch that strips to NOTHING is a no-op update, not a failure, and it
+    // must never reach the driver. Drizzle's `.set({})` throws `No values to
+    // set`; that throw IS caught below, and `classifyConstraintError` rightly
+    // declines it — an empty update is a programming error, not a constraint
+    // violation — so it took the redact path and answered 500 `database error`.
+    // The strip above is precisely what produces the empty object, so a body
+    // naming only the discriminator (the one key a client is most likely to
+    // send at a TPH subtype route) was a guaranteed 500. Answer as a READ does,
+    // including the 404: a no-op patch must not become a hole through which one
+    // subtype's route reports another subtype's row.
+    if (Object.keys(data).length === 0) {
+      const src = readSource(opts);
+      const noopId = coerceIdForColumn(src.id, id);
+      if (noopId === undefined) {
+        return reply.code(400).send({ error: "invalid_id" });
+      }
+      const noopCond = eq(src.id, noopId);
+      const row = await firstRow(opts.db, src, discCond ? and(noopCond, discCond) : noopCond);
+      return row ? toWire(row) : reply.code(404).send({ error: "not_found" });
+    }
     // Compare against the PK's real type (see mountGetRoute) — a numeric-
     // LOOKING id on a TEXT pk would otherwise UPDATE the wrong row.
     const idValue = coerceIdForColumn(opts.table.id, id);
@@ -308,7 +345,7 @@ export function mountUpdateRoute(opts: VerbOptions): void {
     const row = (result as unknown[])[0];
     if (row == null) return reply.code(404).send({ error: "not_found" });
     // #214 — re-read through the replica view so the response carries derived columns.
-    return await reReadThroughView(opts, row);
+    return toWire(await reReadThroughView(opts, row));
   };
   const path = `${opts.path}/:id`;
   const ro = routeOpts(opts);

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

@@ -18,10 +18,22 @@
 //      the source side (via @sourceRefField) → sourceColumn/targetColumn.
 //   3. Symmetric self-join: junction WHERE sourceCol = :id OR targetCol = :id;
 //      per row the related id is whichever column is NOT the source id.
+//
+// A target that is a TPH SUBTYPE lives in its discriminator base's table, and the
+// junction FK can only point at that base table — so it can hold the id of a row of
+// another subtype. `targetDiscriminator` ANDs the subtype predicate into stage 2 so
+// only rows of the declared target come back.
+//
+// The SOURCE has the mirror problem. An M:N declared ON a subtype mounts under that
+// subtype's segment (`/auths/bridge/:id/linkedAuths`), but the junction FK still points
+// at the shared base table, so a SIBLING subtype's id traverses it just as well and the
+// subtype segment in the path would be decorative. `sourceDiscriminator` adds a stage 0
+// that checks the source row's own discriminator first.
 
 import type { FastifyInstance, RouteShorthandOptions } from "fastify";
-import { eq, or, inArray } from "drizzle-orm";
+import { and, eq, or, inArray } from "drizzle-orm";
 import { coerceIdForColumn } from "./util.js";
+import { timestampWire } from "../timestamp-wire.js";
 
 // Loose Drizzle types — the helper works across libsql / better-sqlite3 / pg.
 // biome-ignore lint/suspicious/noExplicitAny: dynamic dispatch over user's Drizzle instance
@@ -49,6 +61,22 @@ export interface M2mRouteOptions {
   targetPkColumn?: string;
   /** Undirected self-join: union both junction FK columns on read. */
   symmetric: boolean;
+  /**
+   * The target is a TPH subtype: `targetTable` is its discriminator base's table, and
+   * stage 2 keeps only rows whose discriminator `column` (physical name) equals `value`.
+   * Absent → every related row is returned, behaviour unchanged.
+   */
+  targetDiscriminator?: { column: string; value: string };
+  /**
+   * The SOURCE is a TPH subtype: this route is mounted under the subtype's path segment,
+   * but the junction FK addresses the shared base table, so an id belonging to a SIBLING
+   * subtype would traverse it successfully and return that sibling's relations. Stage 0
+   * reads the source row's discriminator from `table` (the base table the row lives in)
+   * and yields an empty list when it is not `value` — the id names no row of THIS
+   * subtype, so it has no relations, which is a 200 with `[]` rather than an error.
+   * Absent → no source check, behaviour unchanged.
+   */
+  sourceDiscriminator?: { table: AnyTable; pkColumn: string; column: string; value: string };
   /** Fastify route-level hooks (auth, etc.). */
   routeOptions?: RouteShorthandOptions;
 }
@@ -57,6 +85,7 @@ export function mountM2mRoute(opts: M2mRouteOptions): void {
   const targetPk = opts.targetPkColumn ?? "id";
   const route = `${opts.path}/:id/${opts.relationName}`;
   const ro = opts.routeOptions ?? {};
+  const toWire = timestampWire(opts.targetTable);
 
   opts.fastify.get(route, ro, async (req, reply) => {
     const { id } = req.params as { id: string };
@@ -72,6 +101,24 @@ export function mountM2mRoute(opts: M2mRouteOptions): void {
       return reply.code(400).send({ error: "invalid_id" });
     }
 
+    // Stage 0 — the source id must name a row of THIS subtype. Skipping it would let
+    // `/auths/bridge/{a Copay's id}/linkedAuths` return that Copay's relations, because
+    // the junction FK cannot tell the subtypes apart: it points at the shared base table.
+    const srcDisc = opts.sourceDiscriminator;
+    if (srcDisc !== undefined) {
+      const srcPk = columnRef(srcDisc.table, srcDisc.pkColumn);
+      const ownId = coerceIdForColumn(srcPk, id);
+      if (ownId === undefined) {
+        return reply.code(400).send({ error: "invalid_id" });
+      }
+      const owner = await opts.db
+        .select({ d: columnRef(srcDisc.table, srcDisc.column) })
+        .from(srcDisc.table)
+        .where(eq(srcPk, ownId))
+        .limit(1);
+      if (owner.length === 0 || String(owner[0]?.d) !== srcDisc.value) return [];
+    }
+
     // Stage 1 — junction rows for this source id.
     const joinWhere = opts.symmetric
       ? or(eq(srcCol, sourceId), eq(tgtCol, sourceId))
@@ -101,10 +148,13 @@ export function mountM2mRoute(opts: M2mRouteOptions): void {
 
     // Stage 2 — load the target rows.
     const pkCol = columnRef(opts.targetTable, targetPk);
-    return await opts.db
+    const byPk = inArray(pkCol, [...relatedIds]);
+    const disc = opts.targetDiscriminator;
+    const rows = await opts.db
       .select()
       .from(opts.targetTable)
-      .where(inArray(pkCol, [...relatedIds]));
+      .where(disc ? and(byPk, eq(columnRef(opts.targetTable, disc.column), disc.value)) : byPk);
+    return (rows as unknown[]).map(toWire);
   });
 }
 

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

@@ -3,19 +3,12 @@ import { sql, eq, and, count } from "drizzle-orm";
 import qs from "qs";
 import { parseFilterParams, FilterParseError } from "./filter-parser.js";
 import type { FilterAllowlist, SortAllowlist } from "./filter-allowlist.js";
-import { isTruthyFlag, contractErrorCode, coerceIdForColumn, rawIdLiteral } from "./util.js";
+import { isTruthyFlag, contractErrorCode, coerceIdForColumn, rawIdLiteral, viewBaseConfig } from "./util.js";
+import { timestampWire } from "../timestamp-wire.js";
 
 // biome-ignore lint/suspicious/noExplicitAny: dynamic dispatch over user-supplied views
 type AnyView = any;
 
-/**
- * Drizzle v0.45 stores view config under this well-known Symbol.
- * Accessing `view._` on a proxy-wrapped view (empty-column .existing()) throws
- * because the proxy tries to spread `subquery._.selectedFields` which is undefined.
- * Using the symbol bypasses the proxy entirely.
- */
-const VIEW_BASE_CONFIG = Symbol.for("drizzle:ViewBaseConfig");
-
 export interface MountReadOnlyOptions {
   readonly fastify: FastifyInstance;
   readonly path: string;
@@ -49,18 +42,8 @@ const REJECT_MUTATION = async (
     .send({ error: "method_not_allowed", message: `${request.method} is not supported on a projection (read-only).` });
 };
 
-function getViewConfig(view: AnyView): Record<string, unknown> | undefined {
-  try {
-    const cfg = (view as Record<symbol, unknown>)[VIEW_BASE_CONFIG];
-    if (cfg && typeof cfg === "object") return cfg as Record<string, unknown>;
-  } catch {
-    // ignore — proxy handler may throw on unexpected shapes
-  }
-  return undefined;
-}
-
 function resolveViewName(view: AnyView): string | undefined {
-  const cfg = getViewConfig(view);
+  const cfg = viewBaseConfig(view);
   if (cfg) {
     if (typeof cfg["name"] === "string") return cfg["name"] as string;
   }
@@ -78,7 +61,7 @@ function resolveViewName(view: AnyView): string | undefined {
  * `SELECT  FROM ...` (invalid SQL), and we must fall back to raw SQL.
  */
 function isEmptyColumnView(view: AnyView): boolean {
-  const cfg = getViewConfig(view);
+  const cfg = viewBaseConfig(view);
   if (cfg) {
     const fields = cfg["selectedFields"] as Record<string, unknown> | undefined;
     return fields !== undefined && Object.keys(fields).length === 0;
@@ -139,6 +122,8 @@ export function mountReadOnlyCrudRoutes(opts: MountReadOnlyOptions): void {
 
   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);
 
   // ── List ──────────────────────────────────────────────────────────────────
   fastify.get(path, ro, async (req, reply) => {
@@ -189,7 +174,7 @@ export function mountReadOnlyCrudRoutes(opts: MountReadOnlyOptions): void {
       // node-postgres builder is thenable. (The useRawSql branch above keeps
       // db.all(sql.raw(...)) because that is the libsql raw-exec API, only
       // reachable for `.existing()` empty-column views which are sqlite-only.)
-      const rows = await q;
+      const rows = (await q as unknown[]).map(toWire);
 
       if (!withCount) return rows;
 
@@ -201,7 +186,9 @@ export function mountReadOnlyCrudRoutes(opts: MountReadOnlyOptions): void {
       return { rows, total };
     } catch (err) {
       if (err instanceof FilterParseError) {
-        reply.code(400).send({ error: contractErrorCode(err.code), message: err.message });
+        // Spread the details so the cross-port-required `field` reaches the wire on a
+        // projection route too (F20) — the writable mount already does this.
+        reply.code(400).send({ error: contractErrorCode(err.code), message: err.message, ...(err.details ?? {}) });
         return;
       }
       throw err;
@@ -229,11 +216,16 @@ export function mountReadOnlyCrudRoutes(opts: MountReadOnlyOptions): void {
       colRef !== undefined ? eq(colRef, idValue) : undefined
     ).limit(1);
     const row = (rows as unknown[])[0];
-    return row ?? reply.code(404).send({ error: "not_found" });
+    return row ? toWire(row) : reply.code(404).send({ error: "not_found" });
   });
 
   // ── Mutations explicitly rejected (405) ───────────────────────────────────
+  // PUT is here because the WRITABLE mount serves it (a full-replace update), 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);
 }

package/src/drizzle-fastify/util.ts

@@ -81,3 +81,36 @@ export function contractErrorCode(internal: string): string {
       return internal;
   }
 }
+
+/**
+ * Drizzle v0.45 stores view config under this well-known Symbol. Accessing
+ * `view._` on a proxy-wrapped view (empty-column `.existing()`) throws because
+ * the proxy tries to spread `subquery._.selectedFields` which is undefined; the
+ * symbol read bypasses the proxy. The proxy handler can still throw on
+ * unexpected shapes, so the read is guarded. One reader for the private shape —
+ * the two read-only mounts and the timestamp-wire column lookup share it.
+ */
+const VIEW_BASE_CONFIG = Symbol.for("drizzle:ViewBaseConfig");
+
+export function viewBaseConfig(view: unknown): Record<string, unknown> | undefined {
+  try {
+    const cfg = (view as Record<symbol, unknown>)[VIEW_BASE_CONFIG];
+    if (cfg && typeof cfg === "object") return cfg as Record<string, unknown>;
+  } catch {
+    // ignore — proxy handler may throw on unexpected shapes
+  }
+  return undefined;
+}
+
+/**
+ * The portable one-row read: `.limit(1)` + await + first element. Awaiting is
+ * what makes this work on both dialects — the node-postgres query builder is
+ * thenable but has no `.get()` (that is a libsql/better-sqlite3-only API, #286).
+ * The caller builds the WHERE (including any TPH discriminator), so the
+ * condition stays with the mount that owns it.
+ */
+export async function firstRow(db: unknown, src: unknown, cond: unknown): Promise<unknown> {
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic dispatch over the user's Drizzle client
+  const rows: unknown = await (db as any).select().from(src).where(cond).limit(1);
+  return (rows as unknown[])[0];
+}

package/src/fastify/index.ts

@@ -59,9 +59,9 @@ export interface CrudRoutesOptions {
    */
   routeOptions?: RouteShorthandOptions;
   /**
-   * HTTP method for the update verb. Defaults to "patch" (semantic partial-
-   * update). Set to "put" to preserve a legacy API contract that already
-   * uses PUT for updates.
+   * Restrict the update verb to ONE HTTP method. Absent (the default) mounts
+   * the update handler on both PATCH and PUT, as the cross-port REST contract
+   * requires.
    */
   updateMethod?: "patch" | "put";
   /**
@@ -130,7 +130,9 @@ export function mountListRoute(opts: SingleVerbOptions): void {
     if (opts.sortAllowlist && typeof parsed["sort"] === "string") {
       const sortParse = parseSort(parsed["sort"], opts.sortAllowlist);
       if (sortParse.error) {
-        return reply.code(400).send({ error: contractErrorCode(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 });
       }
       if (sortParse.orderBy) readOpts.orderBy = sortParse.orderBy;
     }
@@ -153,15 +155,15 @@ export function mountListRoute(opts: SingleVerbOptions): void {
 function parseSort(
   spec: string,
   sortAllowlist: SortAllowlist,
-): { orderBy?: [string, "asc" | "desc"]; error?: string } {
+): { orderBy?: [string, "asc" | "desc"]; error?: string; field?: string } {
   const [field, orderRaw] = spec.split(":");
-  if (!field || !sortAllowlist[field]) return { error: "sort.unknown_field" };
+  if (!field || !sortAllowlist[field]) return { error: "sort.unknown_field", field: field ?? "" };
   // Precedence (caller order > declared @sortableDefaultOrder > asc) comes from the
   // shared sortOrderSpec, so this mount cannot answer one declaration differently from
   // the drizzle mount again. Validation stays here because this mount reports a bad
   // order as an error CODE rather than a thrown FilterParseError.
   const order = sortOrderSpec(sortAllowlist, field, orderRaw).toLowerCase();
-  if (order !== "asc" && order !== "desc") return { error: "sort.invalid_order" };
+  if (order !== "asc" && order !== "desc") return { error: "sort.invalid_order", field };
   return { orderBy: [field, order] };
 }
 
@@ -225,11 +227,19 @@ export function mountUpdateRoute(opts: SingleVerbOptions): void {
   };
   const path = `${opts.path}/:id`;
   const ro = routeOpts(opts);
+  // 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
+  // every other port's controller do. `updateMethod` stays an explicit single-verb
+  // override for a consumer that wants to restrict the surface.
   // biome-ignore lint/suspicious/noExplicitAny: handler signature is generic by design
+  const h = handler as any;
   if (opts.updateMethod === "put") {
-    opts.fastify.put(path, ro, handler as any);
+    opts.fastify.put(path, ro, h);
+  } else if (opts.updateMethod === "patch") {
+    opts.fastify.patch(path, ro, h);
   } else {
-    opts.fastify.patch(path, ro, handler as any);
+    opts.fastify.patch(path, ro, h);
+    opts.fastify.put(path, ro, h);
   }
 }
 
@@ -256,3 +266,43 @@ export function mountDeleteRoute(opts: SingleVerbOptions): void {
 // shared (deprecated) helper so the three adapters can't silently diverge.
 // The mounts above no longer use it: ObjectManager coerces ids per metadata.
 export { parseId } from "../drizzle-fastify/util.js";
+
+// ---------------------------------------------------------------------------
+// Metadata endpoint
+// ---------------------------------------------------------------------------
+
+import type { MetaData } from "@metaobjectsdev/metadata";
+import { META_ROUTE_PATH, META_CONTENT_TYPE, metaJson } from "../meta-endpoint.js";
+
+export interface MetaRouteOptions {
+  fastify: FastifyInstance;
+  /** The loaded model root. */
+  root: MetaData;
+  /** Mounted under this prefix; defaults to "" (the bare `/_meta`). */
+  prefix?: string;
+}
+
+/**
+ * Mount `GET {prefix}/_meta`, serving the model as effective canonical JSON.
+ *
+ * Opt-in by design. `/_meta` publishes the SHAPE of the model — entity and field
+ * names, types, validators, layouts — though no row data. Guard it with your own
+ * middleware exactly as you would the generated routes (#367):
+ *
+ *     app.register(async (s) => {
+ *       s.addHook("preHandler", requireAuth);
+ *       mountMetaRoute({ fastify: s, root, prefix: "/api" });
+ *     });
+ *
+ * The body is serialized once per call. If that ever matters, cache it in the
+ * host — the model is immutable after load.
+ */
+export function mountMetaRoute(opts: MetaRouteOptions): void {
+  const path = `${opts.prefix ?? ""}${META_ROUTE_PATH}`;
+  opts.fastify.get(path, async (_req, reply) => {
+    return reply
+      .code(200)
+      .header("content-type", META_CONTENT_TYPE)
+      .send(metaJson(opts.root));
+  });
+}