@metaobjectsdev/runtime-ts 1.0.5-rc.1 → 1.0.5-rc.11

package/src/hono/index.ts

@@ -7,8 +7,8 @@
 //   GET    {path}      list with ?filter / ?sort / ?limit / ?offset / ?withCount=1
 //   GET    {path}/:id  findById, 404 if missing
 //   POST   {path}      create, 400 on Zod validation error, 201 on success
-//   PATCH  {path}/:id  update (default), 400 / 404 envelopes
-//   PUT    {path}/:id  update (when updateMethod === "put")
+//   PATCH  {path}/:id  update, 400 / 404 envelopes
+//   PUT    {path}/:id  update — the same handler (restrict with updateMethod)
 //   DELETE {path}/:id  delete, 204 on success, 404 if missing
 //
 // Filter / sort / withCount semantics are shared with drizzle-fastify via
@@ -21,6 +21,7 @@ import { classifyConstraintError, RedactedDatabaseError, logAndRedact } from "..
 import type { ZodTypeAny } from "zod";
 import { eq, count, and } from "drizzle-orm";
 import qs from "qs";
+import { contractErrorCode } from "../drizzle-fastify/util.js";
 import {
   parseFilterParams,
   FilterParseError,
@@ -34,10 +35,12 @@ export type {
   FilterAllowlist,
   SortAllowlist,
 } from "../drizzle-fastify/filter-allowlist.js";
-import { isTruthyFlag, coerceIdForColumn } from "../drizzle-fastify/util.js";
+import { isTruthyFlag, coerceIdForColumn, firstRow } from "../drizzle-fastify/util.js";
+import { timestampWire } from "../timestamp-wire.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";
+export { timestampWire, canonicalTimestamp } from "../timestamp-wire.js";
 
 // ---------------------------------------------------------------------------
 // Loose types — we don't bind to a specific Drizzle backend so the helper
@@ -82,8 +85,9 @@ export interface CrudRoutesOptions {
   /** Limit which verbs are mounted. Defaults to all five. */
   expose?: readonly CrudVerb[];
   /**
-   * 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;
@@ -128,6 +132,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);
+}
+
 /** Re-read a just-written row through the replica view so the response carries the
  *  derived columns. Writes always target the TABLE; only the echo changes. With no
  *  `readView`, returns the write row unchanged. */
@@ -147,6 +169,7 @@ async function reReadThroughView(
 }
 
 export function mountListRoute(opts: VerbOptions): void {
+  const toWire = readWire(opts);
   opts.app.get(opts.path, async (c) => {
     try {
       const listSrc = readSource(opts);
@@ -182,7 +205,7 @@ export function mountListRoute(opts: VerbOptions): void {
       // better-sqlite3-only API). Awaiting works on BOTH dialects — this is what
       // makes the Hono helpers genuinely Postgres-capable, matching the Fastify
       // adapter, which carried this fix while Hono did not (#286).
-      const rows = await q;
+      const rows = (await q as unknown[]).map(toWire);
 
       if (!withCount) return c.json(rows);
 
@@ -194,7 +217,11 @@ export function mountListRoute(opts: VerbOptions): void {
       return c.json({ rows, total });
     } catch (err) {
       if (err instanceof FilterParseError) {
-        return c.json({ error: err.code, ...(err.details ?? {}) }, 400);
+        // Map to the cross-port wire code, exactly as the Fastify mount does. Emitting
+        // the INTERNAL dotted code here made the two flavors answer differently for the
+        // same metadata (`filter.unknown_field` vs `invalid_filter_field`), contradicting
+        // this package's own "byte-identical on the wire" contract.
+        return c.json({ error: contractErrorCode(err.code), ...(err.details ?? {}) }, 400);
       }
       throw err;
     }
@@ -202,6 +229,7 @@ export function mountListRoute(opts: VerbOptions): void {
 }
 
 export function mountGetRoute(opts: VerbOptions): void {
+  const toWire = readWire(opts);
   opts.app.get(`${opts.path}/:id`, async (c) => {
     const id = c.req.param("id") ?? "";
     // Compare against the PK's real type — a numeric-LOOKING id on a TEXT pk
@@ -209,19 +237,13 @@ export function mountGetRoute(opts: VerbOptions): void {
     const getSrc = readSource(opts);
     const idValue = coerceIdForColumn(getSrc.id, 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 opts.db
-      .select()
-      .from(getSrc)
-      .where(eq(getSrc.id, idValue))
-      .limit(1);
-    const row = (rows as unknown[])[0];
-    return row ? c.json(row) : c.json({ error: "not_found" }, 404);
+    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);
@@ -241,11 +263,12 @@ 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(await reReadThroughView(opts, row), 201);
+    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 id = c.req.param("id") ?? "";
     const body = await c.req.json().catch(() => undefined);
@@ -253,6 +276,15 @@ export function mountUpdateRoute(opts: VerbOptions): void {
     if (!parsed.success) {
       return c.json({ error: "validation", issues: parsed.error.issues }, 400);
     }
+    // An empty patch is a no-op update, answered as a read — the Fastify mount's
+    // rule; its block in drizzle-fastify/index.ts carries the full rationale.
+    if (Object.keys(parsed.data as Record<string, unknown>).length === 0) {
+      const src = readSource(opts);
+      const noopId = coerceIdForColumn(src.id, id);
+      if (noopId === undefined) return c.json({ error: "invalid_id" }, 400);
+      const row = await firstRow(opts.db, src, eq(src.id, noopId));
+      return row ? c.json(toWire(row)) : c.json({ error: "not_found" }, 404);
+    }
     // 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);
@@ -270,13 +302,20 @@ export function mountUpdateRoute(opts: VerbOptions): void {
       return c.json(f.body, f.status as 400 | 409);
     }
     const row = (result as unknown[])[0];
-    return row ? c.json(await reReadThroughView(opts, row)) : c.json({ error: "not_found" }, 404);
+    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
+  // every other port's controller do. `updateMethod` stays an explicit single-verb
+  // override for a consumer that wants to restrict the surface.
   if (opts.updateMethod === "put") {
     opts.app.put(path, handler);
+  } else if (opts.updateMethod === "patch") {
+    opts.app.patch(path, handler);
   } else {
     opts.app.patch(path, handler);
+    opts.app.put(path, handler);
   }
 }
 
@@ -320,3 +359,30 @@ function extractRowCount(result: unknown): number {
 }
 
 export { mountReadOnlyCrudRoutes, type MountReadOnlyOptions } from "./mount-read-only.js";
+
+// ---------------------------------------------------------------------------
+// Metadata endpoint
+// ---------------------------------------------------------------------------
+
+import type { MetaData } from "@metaobjectsdev/metadata";
+import { META_ROUTE_PATH, META_CONTENT_TYPE, metaJson } from "../meta-endpoint.js";
+
+export interface HonoMetaRouteOptions {
+  app: AnyHono;
+  root: MetaData;
+  prefix?: string;
+}
+
+/**
+ * Mount `GET {prefix}/_meta` on Hono. Same contract and same opt-in caveat as
+ * the Fastify twin; guard the mount path with middleware before calling this:
+ *
+ *     app.use(`/api${META_ROUTE_PATH}`, requireAuth);
+ *     mountMetaRouteHono({ app, root, prefix: "/api" });
+ */
+export function mountMetaRouteHono(opts: HonoMetaRouteOptions): void {
+  const path = `${opts.prefix ?? ""}${META_ROUTE_PATH}`;
+  opts.app.get(path, (c) =>
+    c.body(metaJson(opts.root), 200, { "content-type": META_CONTENT_TYPE }),
+  );
+}

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

@@ -1,5 +1,5 @@
 // Hono read-only mount — projection (view-backed) entities. GET list +
-// GET :id only. POST/PATCH/DELETE return 405. Mirrors the drizzle-fastify
+// GET :id only. POST/PATCH/PUT/DELETE return 405. Mirrors the drizzle-fastify
 // equivalent so the cross-port API contract holds for projection endpoints.
 
 import type { Hono } from "hono";
@@ -10,20 +10,14 @@ import type {
   FilterAllowlist,
   SortAllowlist,
 } from "../drizzle-fastify/filter-allowlist.js";
-import { isTruthyFlag, coerceIdForColumn, rawIdLiteral } from "../drizzle-fastify/util.js";
+import { isTruthyFlag, coerceIdForColumn, rawIdLiteral, contractErrorCode, viewBaseConfig } from "../drizzle-fastify/util.js";
+import { timestampWire } from "../timestamp-wire.js";
 
 // biome-ignore lint/suspicious/noExplicitAny: dynamic dispatch over user-supplied views
 type AnyView = any;
 // biome-ignore lint/suspicious/noExplicitAny: generic Hono app
 type AnyHono = Hono<any, any, any>;
 
-/**
- * Drizzle v0.45 stores view config under this well-known Symbol. Mirrors
- * the same workaround the Fastify mount uses — accessing `view._` on a
- * proxy-wrapped view throws.
- */
-const VIEW_BASE_CONFIG = Symbol.for("drizzle:ViewBaseConfig");
-
 export interface MountReadOnlyOptions {
   readonly app: AnyHono;
   readonly path: string;
@@ -37,18 +31,8 @@ export interface MountReadOnlyOptions {
   readonly idColumn?: string;
 }
 
-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;
   }
@@ -60,7 +44,7 @@ function resolveViewName(view: AnyView): string | undefined {
 }
 
 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;
@@ -119,6 +103,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 ──────────────────────────────────────────────────────────────────
   app.get(path, async (c) => {
@@ -172,7 +158,7 @@ export function mountReadOnlyCrudRoutes(opts: MountReadOnlyOptions): void {
       // better-sqlite3-only API). Awaiting works on BOTH dialects — this is what
       // makes the Hono helpers genuinely Postgres-capable, matching the Fastify
       // adapter, which carried this fix while Hono did not (#286).
-      const rows = await q;
+      const rows = (await q as unknown[]).map(toWire);
 
       if (!withCount) return c.json(rows);
 
@@ -183,7 +169,9 @@ export function mountReadOnlyCrudRoutes(opts: MountReadOnlyOptions): void {
       return c.json({ rows, total });
     } catch (err) {
       if (err instanceof FilterParseError) {
-        return c.json({ error: err.code, message: err.message }, 400);
+        // Wire code + the details (so the cross-port-required `field` is present),
+        // matching the Fastify projection mount.
+        return c.json({ error: contractErrorCode(err.code), message: err.message, ...(err.details ?? {}) }, 400);
       }
       throw err;
     }
@@ -213,7 +201,7 @@ export function mountReadOnlyCrudRoutes(opts: MountReadOnlyOptions): void {
       .where(colRef !== undefined ? eq(colRef, idValue) : undefined)
       .limit(1);
     const row = (rows as unknown[])[0];
-    return row ? c.json(row) : c.json({ error: "not_found" }, 404);
+    return row ? c.json(toWire(row)) : c.json({ error: "not_found" }, 404);
   });
 
   // ── Mutations explicitly rejected (405) ───────────────────────────────────
@@ -226,6 +214,10 @@ export function mountReadOnlyCrudRoutes(opts: MountReadOnlyOptions): void {
   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);
 }

package/src/identity-strategy.ts

@@ -13,7 +13,8 @@ import {
 import { MetadataError, ValidationError } from "./errors.js";
 
 export type IdentityResolution =
-  | { kind: "driver-generated"; values: Record<string, unknown> }
+  /** `fields` are the PK fields the store fills on insert — absent from `values` by design. */
+  | { kind: "driver-generated"; values: Record<string, unknown>; fields: readonly string[] }
   | { kind: "preset"; values: Record<string, unknown> };
 
 export function resolveIdentity(entity: MetaData, data: Record<string, unknown>): IdentityResolution {
@@ -67,7 +68,7 @@ export function resolveIdentity(entity: MetaData, data: Record<string, unknown>)
       for (const f of pkFields) values[f] = data[f];
       return { kind: "preset", values };
     }
-    return { kind: "driver-generated", values: {} };
+    return { kind: "driver-generated", values: {}, fields: pkFields };
   }
 
   if (generation === GENERATION_UUID) {

package/src/index.ts

@@ -48,3 +48,6 @@ export {
   type ConstraintKind,
   type ConstraintFailure,
 } from "./constraint-errors.js";
+
+// UI-1 — metadata API contract for the browser read-model.
+export { META_ROUTE_PATH, META_CONTENT_TYPE, metaJson } from "./meta-endpoint.js";

package/src/meta-endpoint.ts

@@ -0,0 +1,35 @@
+// UI-1 — the metadata API contract. Framework-free on purpose: only TypeScript
+// has a web-bound runtime home, so every other port ships this function and lets
+// the host mount it. The durable deliverable is the path + the serialization.
+import { canonicalSerializeEffective, type MetaData } from "@metaobjectsdev/metadata";
+
+/**
+ * The metadata endpoint's path, mounted under the host's `apiPrefix`.
+ * A cross-port contract value — one browser read-model has to work against
+ * every backend, so this string is not per-port configurable.
+ */
+export const META_ROUTE_PATH = "/_meta";
+
+/**
+ * The `GET {apiPrefix}/_meta` response content-type header.
+ * A TypeScript-local detail, not a cross-port contract: only this port ships
+ * HTTP mounts, so this value only has to stay byte-identical across TypeScript's
+ * own `mountMetaRoute` (Fastify) and `mountMetaRouteHono` (Hono). Another port's
+ * hand-mounted route is free to emit a different content-type
+ * (see docs/features/metadata-api.md).
+ */
+export const META_CONTENT_TYPE = "application/json; charset=utf-8";
+
+/**
+ * The `GET {apiPrefix}/_meta` response body: the loaded model as EFFECTIVE
+ * canonical JSON.
+ *
+ * Effective, not raw (spec §3.2): the effective form materializes the
+ * super-chain merge, so a browser reading it never resolves `extends` itself.
+ * Per ADR-0039 an own-vs-resolving mistake there would silently drop inherited
+ * `@columns` / `@pageSize` / `@sortableDefaultOrder` — exactly the attrs a
+ * runtime grid reads — and read as "unset" rather than failing.
+ */
+export function metaJson(root: MetaData): string {
+  return canonicalSerializeEffective(root);
+}

package/src/object-manager.ts

@@ -21,7 +21,7 @@ import {
 import { coerceRowOnRead, coerceRowOnWrite } from "./type-coercer.js";
 import { decodeRef, encodeRef } from "./ref-codec.js";
 import { runValidators } from "./validator-runner.js";
-import { resolveIdentity } from "./identity-strategy.js";
+import { resolveIdentity, type IdentityResolution } from "./identity-strategy.js";
 import {
   viewFieldNames,
   fieldViewSpec, entityViewSpec,
@@ -185,7 +185,7 @@ export class ObjectManager {
     const ident = resolveIdentity(entity, restricted);
     const merged: Row = { ...restricted, ...ident.values };
 
-    const validation = runValidators(entity, merged);
+    const validation = runValidators(entity, merged, storeFilledOpts(ident));
     if (!validation.ok) {
       throw new ValidationError(formatValidationMessage(entityName, validation.errors), { entity: entityName, errors: validation.errors });
     }
@@ -252,7 +252,7 @@ export class ObjectManager {
       const restricted = this.applyViewRestriction(entity, data, opts.view);
       const ident = resolveIdentity(entity, restricted);
       const merged: Row = { ...restricted, ...ident.values };
-      const v = runValidators(entity, merged);
+      const v = runValidators(entity, merged, storeFilledOpts(ident));
       if (!v.ok) {
         throw new ValidationError(formatValidationMessage(entityName, v.errors), { entity: entityName, errors: v.errors });
       }
@@ -502,6 +502,11 @@ function requireNonEmptyFilter(
   return where;
 }
 
+/** A driver-generated key is filled by the store on insert, so an absent one is not a required failure. */
+function storeFilledOpts(ident: IdentityResolution): { storeFilled?: readonly string[] } {
+  return ident.kind === "driver-generated" ? { storeFilled: ident.fields } : {};
+}
+
 function formatValidationMessage(entityName: string, errors: { field: string; rule: string }[]): string {
   const summary = errors.map((e) => `${e.field}: ${e.rule}`).join("; ");
   return `Validation failed for ${entityName} (${summary})`;

package/src/timestamp-wire.ts

@@ -0,0 +1,152 @@
+// The wire spelling of a field.timestamp, applied where the Drizzle-direct
+// mounts SEND rows.
+//
+// The spelling is the contract file's, not a comment's:
+// `fixtures/persistence-conformance/normalization.md` says what a tz-aware and
+// an `@localTime` field.timestamp look like on the wire (and
+// `docs/features/api-contract.md` defers to it); this module implements it.
+//
+// Nothing upstream of here produces that. Codegen maps a Postgres field.timestamp
+// to `timestamp(…, { mode: "string" })`, and in string mode Drizzle returns the
+// text node-postgres received — Postgres' OUTPUT format, `2026-09-20 12:00:00+00`,
+// rendered in whatever time zone the SESSION runs in. A strict ISO 8601 parser
+// rejects the space, and the other four ports answer the same row as
+// `2026-09-20T12:00:00Z`. Under `timestampMode: "date"` the column yields a Date,
+// whose JSON form pads `.000`. Both are canonicalized here, at the HTTP boundary
+// (ADR-0019's place for wire canonicalization), so the generated routes — which all
+// delegate to these mounts — answer correctly without a regen.
+//
+// Two doors do NOT pass through here. The ObjectManager-driven `./fastify` mount
+// sends what ObjectManager returns and no generated route uses it. A hand-written
+// route that sends a row itself is its author's to map, through `timestampWire`
+// (the codegen comment at the `mode: "string"` decision says so).
+// `packages/integration-tests/src/temporal-parsers.ts` implements the same spelling
+// for the persistence-conformance runner; a change to the rules here must be checked
+// against it.
+//
+// Which keys are timestamps comes from the Drizzle column objects themselves
+// (`columnType` + `withTimezone`), never from the shape of a value: a text column
+// holding timestamp-shaped text is data. A dialect whose columns do not say so —
+// SQLite stores a field.timestamp in a plain `text()` column — is left as it is.
+
+import { viewBaseConfig } from "./drizzle-fastify/util.js";
+
+// biome-ignore lint/suspicious/noExplicitAny: a Drizzle table or view, structurally typed
+type AnySource = any;
+
+/** The symbol drizzle-orm itself reads for a table's columns — a `Symbol.for` read is
+ *  cross-copy-safe, so this works with two physical copies of drizzle-orm loaded. */
+const DRIZZLE_COLUMNS = Symbol.for("drizzle:Columns");
+
+/** pg-core's two timestamp column classes: `mode: "string"` and `mode: "date"`. */
+const TIMESTAMP_COLUMN_TYPES: ReadonlySet<string> = new Set(["PgTimestampString", "PgTimestamp"]);
+
+/** `YYYY-MM-DD[ T]HH:MM:SS[.f…][Z|±HH[:MM[:SS]]]` — Postgres' output format and ISO 8601 both. */
+const TIMESTAMP_TEXT =
+  /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?(Z|([+-])(\d{2})(?::?(\d{2}))?(?::?(\d{2}))?)?$/;
+
+const pad2 = (n: number): string => n.toString().padStart(2, "0");
+
+/** ".fff" with trailing zeros stripped; "" when the millisecond count is zero. */
+function msSuffix(ms: number): string {
+  return ms === 0 ? "" : `.${ms.toString().padStart(3, "0").replace(/0+$/, "")}`;
+}
+
+function format(
+  y: number, mo: number, d: number, h: number, mi: number, s: number, ms: number, withTimezone: boolean,
+): string {
+  return `${y.toString().padStart(4, "0")}-${pad2(mo)}-${pad2(d)}` +
+    `T${pad2(h)}:${pad2(mi)}:${pad2(s)}${msSuffix(ms)}${withTimezone ? "Z" : ""}`;
+}
+
+function formatUtcFields(date: Date, withTimezone: boolean): string | undefined {
+  const y = date.getUTCFullYear();
+  // NaN is an Invalid Date's year; out-of-range years have no `YYYY` spelling.
+  if (!Number.isInteger(y) || y < 0 || y > 9999) return undefined;
+  return format(
+    y, date.getUTCMonth() + 1, date.getUTCDate(),
+    date.getUTCHours(), date.getUTCMinutes(), date.getUTCSeconds(), date.getUTCMilliseconds(),
+    withTimezone,
+  );
+}
+
+/**
+ * One timestamp value in its canonical wire spelling. `withTimezone` is the column's:
+ * true for a default (instant) field.timestamp, false for `@localTime`. Anything it
+ * cannot read — `infinity`, a BC date, a non-string, an `@localTime` value that carries
+ * an offset — is returned unchanged.
+ */
+export function canonicalTimestamp(value: unknown, withTimezone: boolean): unknown {
+  if (value instanceof Date) {
+    // Drizzle's PgTimestamp builds a naive value's Date by appending +0000, so the UTC
+    // fields ARE the wall clock for @localTime as well as the instant for tz-aware.
+    // An Invalid Date fails formatUtcFields' integer-year guard and passes through.
+    return formatUtcFields(value, withTimezone) ?? value;
+  }
+  if (typeof value !== "string") return value;
+  const m = TIMESTAMP_TEXT.exec(value);
+  if (m === null) return value;
+  const [, y, mo, d, h, mi, s, frac, zone, sign, oh, om, os] = m;
+  // Truncate to milliseconds (Postgres keeps microseconds; the contract is ms).
+  const ms = frac === undefined ? 0 : Number.parseInt(frac.slice(0, 3).padEnd(3, "0"), 10);
+  const fields = [y, mo, d, h, mi, s].map(Number) as [number, number, number, number, number, number];
+  // An @localTime value is a wall clock. One that carries an offset names two candidate
+  // wall clocks, and dropping the offset would silently pick one, so it passes through.
+  if (!withTimezone) return zone === undefined ? format(...fields, ms, false) : value;
+  // No offset to apply: a value already in UTC, or one with no zone at all (read as UTC —
+  // the only reading that means the same instant on every host).
+  if (zone === undefined || zone === "Z") return format(...fields, ms, true);
+  // Date.parse on an explicit four-digit ISO year avoids Date.UTC's 0–99 → 19xx mapping.
+  const local = Date.parse(`${y}-${mo}-${d}T${h}:${mi}:${s}Z`);
+  if (Number.isNaN(local)) return value;
+  const offsetSeconds = (Number(oh) * 3600 + Number(om ?? 0) * 60 + Number(os ?? 0)) * (sign === "-" ? -1 : 1);
+  const utc = formatUtcFields(new Date(local - offsetSeconds * 1000 + ms), true);
+  return utc ?? value;
+}
+
+/** The Drizzle column objects of a table or view, keyed by the JS property a row uses. */
+function columnsOf(source: AnySource): Record<string, unknown> {
+  if (source === undefined || source === null) return {};
+  try {
+    const cols = source[DRIZZLE_COLUMNS];
+    if (cols && typeof cols === "object") return cols as Record<string, unknown>;
+  } catch {
+    // A view is a proxy whose handler may throw on an unexpected key — try the view shape.
+  }
+  const fields = viewBaseConfig(source)?.["selectedFields"];
+  if (fields && typeof fields === "object") return fields as Record<string, unknown>;
+  return {};
+}
+
+/** Returned for a source with no timestamp columns — rows pass through as they are. */
+const IDENTITY: (row: unknown) => unknown = (row) => row;
+
+/**
+ * A function that returns a row with every timestamp column in its wire spelling. The
+ * keys are read once, from the Drizzle `sources` the rows were selected from (several
+ * when a response can come from either, as a write-through entity's does). A source
+ * with no timestamp columns yields the identity, so an untouched row costs nothing.
+ */
+export function timestampWire(...sources: AnySource[]): (row: unknown) => unknown {
+  const keys = new Map<string, boolean>();
+  for (const source of sources) {
+    for (const [key, col] of Object.entries(columnsOf(source))) {
+      const c = col as { columnType?: unknown; withTimezone?: unknown } | null;
+      if (c && typeof c.columnType === "string" && TIMESTAMP_COLUMN_TYPES.has(c.columnType)) {
+        keys.set(key, c.withTimezone === true);
+      }
+    }
+  }
+  if (keys.size === 0) return IDENTITY;
+  // Freeze the mount-time decision into a plain array; the row closure runs once
+  // per row per request and iterating an array beats re-walking the Map.
+  const columns: readonly [string, boolean][] = [...keys];
+  return (row) => {
+    if (row === null || typeof row !== "object") return row;
+    const out: Record<string, unknown> = { ...(row as Record<string, unknown>) };
+    for (const [key, withTimezone] of columns) {
+      if (key in out) out[key] = canonicalTimestamp(out[key], withTimezone);
+    }
+    return out;
+  };
+}

package/src/validator-runner.ts

@@ -41,6 +41,13 @@ const INT64_STRING_RE = /^-?\d+$/;
 export interface RunValidatorsOpts {
   /** Partial-update mode: required-checks only fire for fields whose key is present in `data`. */
   partial?: boolean;
+  /**
+   * Fields the store fills on insert — a driver-generated primary key. Exempt from
+   * required-on-insert when ABSENT, exactly like a `@default` column: `@required` on a
+   * server-generated key is a true statement about the ROW, not a demand on the caller.
+   * A present null is still a required failure.
+   */
+  storeFilled?: readonly string[];
 }
 
 export function runValidators(
@@ -70,6 +77,7 @@ export function runValidators(
       // EXPLICIT present null — nulling a required field is a deliberate clear the
       // default cannot cover (FR-035 PATCH-2: present-null on @required → error).
       if (hasDefault && !present) continue;
+      if (!present && opts.storeFilled?.includes(field.name)) continue;
       errors.push({
         field: field.name,
         rule: "required",