feat(codegen-ts): jsonb value-object typing + collection-name control + shared VO module resolver (#49)

Three independent codegen-ts adoption fixes that share the same render
pipeline (so they land together to avoid intermingled-file rebases), plus a
timestamp-mode config knob.

1. Postgres jsonb value objects
   - field.object no longer emits a native .array() — an object array lives in
     ONE jsonb column, not jsonb[]. Suppressed when subType === object.
   - jsonb object columns now carry .$type<VO>() / .$type<VO[]>() (the previous
     .$type path was sqlite-only, so Postgres object columns inferred `unknown`).
     Added an `array` flag to ColumnSpec.dollarTypeRef so the renderer picks the
     single vs collection form. Applies to single objects too, not just arrays.

2. Collection (table) variable naming control
   - New codegen config: `pluralizeCollections` (default true) and
     `collectionNameOverrides` (per-entity exact names). Surfaced as a single
     `ctx.collectionName(entity)` resolver used by every template that emits or
     references a table var (schema, queries, routes, relations, inferred types),
     so the declaration and all references stay consistent. Naming is a per-port
     codegen concern, so this is config — not a metadata attribute — and carries
     no cross-port conformance cost.

3. Shared value-object module resolver (consistency fix)
   - New `valueObjectModuleSpecifier()` is the single source of truth feeding all
     three places that reference a VO module — the field's TS type, its Zod
     schema, and the Drizzle .$type<>(). Previously each hardcoded `./<VO>.js`,
     which was wrong under package layout + cross-package refs and ignored
     extStyle. Now layout/package/extStyle-aware (matching FK-reference
     resolution); proven by a two-package end-to-end fixture.

4. `timestampMode` config ("date" | "string", default "string") applied
   uniformly to the plain timestamp + timestamptz override branches, keeping the
   Drizzle column aligned with the generated Zod + the cross-port wire contract.

Default config reproduces byte-identical output, so all golden/conformance
fixtures are unchanged. New coverage: jsonb-VO column cases, the
pluralize/override resolver, the VO module resolver (flat/same-pkg/cross-pkg/
extStyle), and an end-to-end cross-package VO fixture asserting all three
references resolve identically.

Tests: codegen-ts 799/0, codegen-ts-react/angular/tanstack + conformance 134/0,
migrate-ts 488/0, cli 277/0.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: dmealing

server/typescript/packages/codegen-ts/src/column-mapper.ts

@@ -134,15 +134,20 @@ export interface ColumnSpec {
   checkConstraint?: string;
   /**
    * Optional `.$type<...>()` chain target. Renderer (drizzle-schema.ts) emits
-   * `.$type<TS[]>()` ahead of the modifiers chain, using ts-poet `imp()` for
-   * objectRef variants so the cross-module type import auto-hoists.
+   * it ahead of the modifiers chain, using ts-poet `imp()` for objectRef
+   * variants so the cross-module type import auto-hoists. `array` controls the
+   * `[]` suffix: a single value (`VO`) vs a collection (`VO[]`).
    * `kind: "scalar"` covers string[]/number[]/boolean[] — no import needed.
-   * `kind: "objectRef"` covers SourceLens[]/Dissent[]/etc. — `module` is the
-   * relative import path to that entity's emitted module.
+   * `kind: "objectRef"` covers SourceLens/Dissent/etc. — only the bare VO `name`
+   * is carried; the renderer resolves the import MODULE via the shared
+   * `valueObjectModuleSpecifier` (layout/package/extStyle-aware, identical to the
+   * field's TS type + Zod schema). A single Postgres jsonb object column
+   * (`array: false`) gets `.$type<VO>()`; an array of VOs held in one jsonb
+   * column gets `.$type<VO[]>()`.
    */
   dollarTypeRef?:
-    | { kind: "scalar"; tsType: "string" | "number" | "boolean" }
-    | { kind: "objectRef"; name: string; module: string };
+    | { kind: "scalar"; tsType: "string" | "number" | "boolean"; array: boolean }
+    | { kind: "objectRef"; name: string; array: boolean };
 }
 
 /**
@@ -163,6 +168,7 @@ export interface ColumnSpec {
  */
 function pgColumnTypeOverride(
   field: MetaField,
+  timestampMode: "date" | "string" = "string",
 ): { fnName: string; fnOptions?: Record<string, unknown> } | undefined {
   const dbColumnType = field.ownAttr(FIELD_ATTR_DB_COLUMN_TYPE);
   if (typeof dbColumnType !== "string") return undefined;
@@ -173,9 +179,10 @@ function pgColumnTypeOverride(
       return { fnName: "jsonb" };
     case DB_COLUMN_TYPE_TIMESTAMP_WITH_TZ:
       // Drizzle pg-core: timestamp(col, { withTimezone: true }) → timestamptz.
-      // mode:"string" for the same reason as the plain-timestamp branch — the
-      // schema + wire contract carry timestamps as strings.
-      return { fnName: "timestamp", fnOptions: { mode: "string", withTimezone: true } };
+      // mode defaults to "string" (ISO-8601 wire contract, matching the generated
+      // Zod); a consumer can opt into "date" (drizzle's native mode) via
+      // codegen.timestampMode when its hand-written code works with JS Dates.
+      return { fnName: "timestamp", fnOptions: { mode: timestampMode, withTimezone: true } };
     default:
       return undefined;
   }
@@ -202,10 +209,20 @@ function isRequired(field: MetaField): boolean {
   return field.validators().some((child) => child.subType === VALIDATOR_SUBTYPE_REQUIRED);
 }
 
+/** The bare (package-stripped) @objectRef name on a field.object, or undefined
+ *  when unset. Used as the `.$type<VO>()` target + its sibling-module import.
+ *  A fully-qualified ref (acme::ai::SourceLens) strips to the short name. */
+function objectRefBaseName(field: MetaField): string | undefined {
+  const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
+  if (typeof ref === "string" && ref.length > 0) return stripPackage(ref);
+  return undefined;
+}
+
 export function mapColumnType(
   field: MetaField,
   dialect: Dialect,
   strategy: ColumnNamingStrategy = DEFAULT_COLUMN_NAMING_STRATEGY,
+  timestampMode: "date" | "string" = "string",
 ): ColumnSpec {
   const dbName = field.column ?? columnNameFromField(field.name, strategy);
   const importModule = dialect === "sqlite" ? "drizzle-orm/sqlite-core" : "drizzle-orm/pg-core";
@@ -271,7 +288,7 @@ export function mapColumnType(
     // A physical @dbColumnType override wins over the subtype default (Postgres
     // only; SQLite has no native analogue and falls through above). Resolved
     // first so the override-precedence matches migrate-ts's expected-schema.
-    const override = pgColumnTypeOverride(field);
+    const override = pgColumnTypeOverride(field, timestampMode);
     if (override !== undefined) {
       // Override fully determines the physical type; skip the subtype switch.
       fnName = override.fnName;
@@ -310,7 +327,7 @@ export function mapColumnType(
           // inconsistent with the string-typed schema + wire contract and
           // throws on a string write. See SP-B api-contract-generated lane.
           fnName = "timestamp";
-          fnOptions = { mode: "string" };
+          fnOptions = { mode: timestampMode };
           break;
         case FIELD_SUBTYPE_UUID:
           // Postgres native uuid column; native TS binding stays `string`.
@@ -374,7 +391,11 @@ export function mapColumnType(
 
   const modifiers: string[] = [];
 
-  if (dialect === "postgres" && isArray) {
+  // Postgres native arrays (text[]/integer[]/…) apply to SCALAR array fields
+  // only. An object-typed field is stored as a single jsonb column holding the
+  // JSON array (storage jsonb/subdocument), so it gets NO native .array() — the
+  // array-ness is carried by the .$type<VO[]>() annotation computed below.
+  if (dialect === "postgres" && isArray && subType !== FIELD_SUBTYPE_OBJECT) {
     modifiers.push(".array()");
   }
 
@@ -421,24 +442,33 @@ export function mapColumnType(
     }
   }
 
-  // SQLite isArray columns route through {mode:"json"} above; compute the
-  // $type<E[]>() target so the renderer can hoist any cross-module imports.
+  // jsonb / JSON-in-text columns infer as `unknown` in Drizzle without a
+  // .$type<>() annotation. Carry the logical TS type so the column is typed:
+  //  - SQLite isArray: arrays serialize as JSON-in-text → .$type<E[]>() (scalar
+  //    element type, or the @objectRef VO for object arrays).
+  //  - Postgres field.object: a single jsonb column → .$type<VO>(), or
+  //    .$type<VO[]>() when isArray (the JSON array lives in the one column; no
+  //    native .array() is emitted for object storage — see modifiers above).
+  //    Scalar Postgres arrays use native .array() (already element-typed by
+  //    Drizzle) so they need no $type.
   let dollarTypeRef: ColumnSpec["dollarTypeRef"];
   if (dialect === "sqlite" && isArray) {
     if (subType === FIELD_SUBTYPE_OBJECT) {
-      const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
-      if (typeof ref === "string" && ref.length > 0) {
-        // @objectRef may be authored fully-qualified or bare — the $type<E[]>()
-        // target interface + its sibling module use the BARE short name.
-        const base = stripPackage(ref);
-        dollarTypeRef = { kind: "objectRef", name: base, module: `./${base}.js` };
+      const base = objectRefBaseName(field);
+      if (base !== undefined) {
+        dollarTypeRef = { kind: "objectRef", name: base, array: true };
       }
     } else {
       const scalar = sqliteJsonArrayElementTsType(subType);
       if (scalar !== undefined) {
-        dollarTypeRef = { kind: "scalar", tsType: scalar as "string" | "number" | "boolean" };
+        dollarTypeRef = { kind: "scalar", tsType: scalar as "string" | "number" | "boolean", array: true };
       }
     }
+  } else if (dialect === "postgres" && subType === FIELD_SUBTYPE_OBJECT) {
+    const base = objectRefBaseName(field);
+    if (base !== undefined) {
+      dollarTypeRef = { kind: "objectRef", name: base, array: isArray };
+    }
   }
 
   const result: ColumnSpec = {

server/typescript/packages/codegen-ts/src/import-path.ts

@@ -49,6 +49,34 @@ export function crossEntitySpecifier(
   return withExt(`${prefix}${toEntity}`, extStyle);
 }
 
+/**
+ * Module specifier to import a value-object's emitted module (`<VO>.ts`) from a
+ * file that lives in `fromPkg`. Value objects are emitted by the entity-file
+ * generator into the SAME target as entities, so this is the same same-target,
+ * package- + extStyle-aware resolution that FK references use.
+ *
+ * This is the SINGLE source of truth shared by the three places that reference a
+ * VO — the field's TS type (inferred-types), its runtime Zod schema
+ * (zod-validators), and its Drizzle `.$type<>()` (drizzle-schema). They MUST
+ * resolve a given VO to the identical module or they would import two distinct
+ * symbols; routing all three through this function makes divergence impossible.
+ *
+ * `voPkg` is looked up from `packageOf` (which includes `object.value` nodes —
+ * `root.objects()` returns every `TYPE_OBJECT` child). An unknown VO falls back
+ * to `fromPkg`, yielding a same-dir `./<VO>` specifier (correct for flat layout
+ * and for a same-package reference).
+ */
+export function valueObjectModuleSpecifier(
+  voName: string,
+  packageOf: ReadonlyMap<string, string | undefined>,
+  fromPkg: string | undefined,
+  layout: OutputLayout,
+  extStyle: ExtStyle,
+): string {
+  const voPkg = packageOf.has(voName) ? packageOf.get(voName) : fromPkg;
+  return crossEntitySpecifier(layout, fromPkg, voPkg, voName, extStyle);
+}
+
 /** Barrel (at outDir root) re-export specifier for an entity.
  *  Equivalent to crossEntitySpecifier with fromPkg=undefined (barrel is always at root). */
 export function barrelEntrySpecifier(

server/typescript/packages/codegen-ts/src/metaobjects-config.ts

@@ -68,6 +68,29 @@ export interface MetaobjectsGenConfig extends ResolvedGenConfig {
   generators: GeneratorSpec[];
   /** How field names map to DB column names when @dbColumn is omitted. Defaults to "snake_case". */
   columnNamingStrategy?: ColumnNamingStrategy;
+  /**
+   * Auto-pluralize the Drizzle collection (table) variable name derived from
+   * each entity (`AgentConfig` → `agentConfigs`). Defaults to `true`. Set
+   * `false` to keep collection vars singular. Per-entity exceptions go in
+   * {@link collectionNameOverrides}. Naming is a per-port codegen concern
+   * (ADR-0001), so this is config — not a metadata attribute — and carries no
+   * cross-port conformance cost.
+   */
+  pluralizeCollections?: boolean;
+  /**
+   * Per-entity exact collection-var-name overrides, keyed by the bare entity
+   * name. Wins over {@link pluralizeCollections} — the escape hatch for the
+   * handful of tables a global rule gets wrong
+   * (e.g. `{ AuditLog: "auditLog", LlmTierConfig: "llmTierConfig" }`).
+   */
+  collectionNameOverrides?: Record<string, string>;
+  /**
+   * Drizzle timestamp column mode. "string" (default) types timestamp columns as
+   * ISO-8601 strings (matches the generated Zod + cross-port wire contract); "date"
+   * uses drizzle's native JS-Date mode (for consumers whose hand-written code works
+   * with `Date`).
+   */
+  timestampMode?: "date" | "string";
   /** Path prefix applied to generated route registrations + hook fetch URLs. Defaults to "". */
   apiPrefix?: string;
   /**
@@ -102,6 +125,9 @@ export interface NormalizedMetaobjectsGenConfig extends Omit<MetaobjectsGenConfi
   /** Fully resolved — every string spec has been mapped to its factory result. */
   generators: Generator[];
   columnNamingStrategy: ColumnNamingStrategy;
+  pluralizeCollections: boolean;
+  collectionNameOverrides: Record<string, string>;
+  timestampMode: "date" | "string";
   apiPrefix: string;
   emitAbstractShapes: boolean;
   outputLayout: OutputLayout;
@@ -222,6 +248,9 @@ export function normalizeConfig(config: MetaobjectsGenConfig): NormalizedMetaobj
     ...config,
     generators: resolveGenerators(config.generators),
     columnNamingStrategy: config.columnNamingStrategy ?? DEFAULT_COLUMN_NAMING_STRATEGY,
+    pluralizeCollections: config.pluralizeCollections ?? true,
+    collectionNameOverrides: config.collectionNameOverrides ?? {},
+    timestampMode: config.timestampMode ?? "string",
     apiPrefix: config.apiPrefix ?? "",
     emitAbstractShapes: config.emitAbstractShapes ?? true,
     outputLayout: config.outputLayout ?? "flat",

server/typescript/packages/codegen-ts/src/naming.ts

@@ -58,9 +58,31 @@ export function viewNameFromProjection(
   return "v" + sep + applyColumnNamingStrategy(projectionName, strategy);
 }
 
-/** PascalCase entity → camelCase plural for the Drizzle table variable. */
-export function variableNameFromEntity(entityName: string): string {
-  return pluralize(toCamelCase(entityName.charAt(0).toLowerCase() + entityName.slice(1)));
+/** Codegen control over how an entity name lowers to its collection (table)
+ *  variable name. Both knobs are project-level codegen config (ADR-0001 —
+ *  naming is a per-port codegen concern, NOT a metadata attribute), so they
+ *  carry no cross-port conformance cost. */
+export interface CollectionNameOptions {
+  /** Auto-pluralize the camelCase entity name. Default `true` (e.g.
+   *  `AgentConfig` → `agentConfigs`). Set `false` to keep it singular
+   *  (`agentConfig`). */
+  pluralize?: boolean;
+  /** Per-entity exact var-name overrides, keyed by the bare entity name. Wins
+   *  over `pluralize` — the escape hatch for the handful of tables a global
+   *  rule gets wrong (e.g. `{ AuditLog: "auditLog", LlmTierConfig: "llmTierConfig" }`). */
+  overrides?: Record<string, string>;
+}
+
+/** PascalCase entity → camelCase Drizzle table variable. Auto-pluralizes by
+ *  default; `opts` lets a project turn pluralization off globally and/or pin
+ *  exact names per entity. With no `opts` the behavior is the historical
+ *  always-pluralize (callers like the relation-resolver that only need the
+ *  cosmetic query-API member name pass nothing). */
+export function variableNameFromEntity(entityName: string, opts?: CollectionNameOptions): string {
+  const override = opts?.overrides?.[entityName];
+  if (override !== undefined && override.length > 0) return override;
+  const camel = toCamelCase(entityName.charAt(0).toLowerCase() + entityName.slice(1));
+  return opts?.pluralize === false ? camel : pluralize(camel);
 }
 
 // ---------------------------------------------------------------------------

server/typescript/packages/codegen-ts/src/render-context.ts

@@ -6,6 +6,7 @@ import type { PkInfo } from "./pk-resolver.js";
 import type { RelationMap } from "./relation-resolver.js";
 import type { ColumnNamingStrategy } from "./metaobjects-config.js";
 import type { OutputLayout, ResolvedTarget } from "./import-path.js";
+import { variableNameFromEntity } from "./naming.js";
 
 /**
  * How to format cross-entity import specifiers in generated files.
@@ -37,12 +38,26 @@ export interface RenderContext {
   extStyle: ExtStyle;
   /** Column naming strategy: how field names map to DB column names. Defaults to "snake_case". */
   columnNamingStrategy: ColumnNamingStrategy;
+  /**
+   * Drizzle timestamp column mode. "string" (default) types timestamp columns as
+   * ISO-8601 strings (matching the generated Zod + cross-port wire contract);
+   * "date" uses drizzle's native JS-Date mode (for consumers whose hand-written
+   * code works with `Date`). Opt in via `codegen.timestampMode`.
+   */
+  timestampMode: "date" | "string";
   /** Path prefix applied to generated route registrations + hook fetch URLs. Defaults to "". */
   apiPrefix: string;
   /** Whether abstract entities emit their shape artifact (type-only interface / value-object file). Defaults to true. Instance/write artifacts are never emitted for abstract entities regardless. */
   emitAbstractShapes: boolean;
   /** Output layout mode: "flat" (default) — all files in outDir; "package" — sub-paths from entity metadata package. */
   outputLayout: OutputLayout;
+  /**
+   * Resolve an entity name to its Drizzle collection (table) variable name,
+   * applying the project's pluralization config + per-entity overrides. Every
+   * template that emits or references a table var goes through this so the
+   * declaration and all references agree. Defaults to always-pluralize.
+   */
+  collectionName: (entityName: string) => string;
   /** The target THIS generator emits to (drives path layout + same-target imports). */
   selfTarget: ResolvedTarget;
   /** Where entity files live (drives cross-target entity imports). */
@@ -58,17 +73,22 @@ export interface RenderContext {
   providedEnumModule?: string;
 }
 
-/** Optional shape — `extStyle`, `omImport`, `columnNamingStrategy`, `apiPrefix`, `outputLayout`, and `packageOf` default if omitted. `packageOf` defaults to an empty Map (correct for flat layout; `runGen` always provides the real map). */
-export type RenderContextInput = Omit<RenderContext, "extStyle" | "omImport" | "columnNamingStrategy" | "apiPrefix" | "emitAbstractShapes" | "outputLayout" | "packageOf" | "selfTarget" | "entityModuleTarget"> & {
+/** Optional shape — `extStyle`, `omImport`, `columnNamingStrategy`, `apiPrefix`, `outputLayout`, and `packageOf` default if omitted. `packageOf` defaults to an empty Map (correct for flat layout; `runGen` always provides the real map). `collectionName` is built from `pluralizeCollections` + `collectionNameOverrides` (both default to always-pluralize). */
+export type RenderContextInput = Omit<RenderContext, "extStyle" | "omImport" | "columnNamingStrategy" | "timestampMode" | "apiPrefix" | "emitAbstractShapes" | "outputLayout" | "packageOf" | "selfTarget" | "entityModuleTarget" | "collectionName"> & {
   extStyle?: ExtStyle;
   omImport?: string;
   columnNamingStrategy?: ColumnNamingStrategy;
+  timestampMode?: "date" | "string";
   apiPrefix?: string;
   emitAbstractShapes?: boolean;
   outputLayout?: OutputLayout;
   packageOf?: Map<string, string | undefined>;
   selfTarget?: ResolvedTarget;
   entityModuleTarget?: ResolvedTarget;
+  /** Auto-pluralize collection (table) variable names. Default true. */
+  pluralizeCollections?: boolean;
+  /** Per-entity exact collection-var-name overrides, keyed by bare entity name. */
+  collectionNameOverrides?: Record<string, string>;
 };
 
 /** Append the configured extension to a cross-entity module specifier. */
@@ -86,16 +106,22 @@ export function makeRenderContext(opts: RenderContextInput): RenderContext {
     outputLayout,
     dbImport: opts.dbImport,
   };
+  const collectionNameOpts = {
+    pluralize: opts.pluralizeCollections ?? true,
+    overrides: opts.collectionNameOverrides ?? {},
+  };
   return {
     ...opts,
     extStyle: opts.extStyle ?? "none",
     omImport: opts.omImport ?? "../index",
     columnNamingStrategy: opts.columnNamingStrategy ?? "snake_case",
+    timestampMode: opts.timestampMode ?? "string",
     apiPrefix: opts.apiPrefix ?? "",
     emitAbstractShapes: opts.emitAbstractShapes ?? true,
     outputLayout,
     packageOf: opts.packageOf ?? new Map(),
     selfTarget: defaultTarget,
     entityModuleTarget: opts.entityModuleTarget ?? defaultTarget,
+    collectionName: (entityName: string) => variableNameFromEntity(entityName, collectionNameOpts),
   };
 }

server/typescript/packages/codegen-ts/src/runner.ts

@@ -173,6 +173,9 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
       dbImport: selfTarget.dbImport,
       extStyle: config.extStyle,
       columnNamingStrategy: config.columnNamingStrategy,
+      pluralizeCollections: config.pluralizeCollections,
+      collectionNameOverrides: config.collectionNameOverrides,
+      timestampMode: config.timestampMode,
       apiPrefix: config.apiPrefix,
       emitAbstractShapes: config.emitAbstractShapes,
       outputLayout: selfTarget.outputLayout,