@metaobjectsdev/codegen-ts 0.10.0 → 0.11.0-rc.1

package/src/generators/docs-data-builder.ts

@@ -82,7 +82,7 @@ export interface BuildDocDataOpts {
  *  the documented model-field optionality. Exported so the field-shape builder
  *  reuses the EXACT same rule rather than re-deriving it. */
 export function isFieldRequired(field: MetaField): boolean {
-  if (field.ownAttr(FIELD_ATTR_REQUIRED) === true) return true;
+  if (field.attr(FIELD_ATTR_REQUIRED) === true) return true;
   return field.validators().some((v) => v.subType === VALIDATOR_SUBTYPE_REQUIRED);
 }
 
@@ -104,7 +104,7 @@ interface ValidatorParts {
 }
 
 function collectValidatorParts(field: MetaField): ValidatorParts {
-  const maxLenAttr = field.ownAttr(FIELD_ATTR_MAX_LENGTH);
+  const maxLenAttr = field.attr(FIELD_ATTR_MAX_LENGTH);
   const regexParts: string[] = [];
   const lengthParts: string[] = [];
   const numericParts: string[] = [];
@@ -143,7 +143,7 @@ function collectValidatorParts(field: MetaField): ValidatorParts {
 export function neutralTypeStr(field: MetaField): string {
   let base: string;
   if (field.subType === FIELD_SUBTYPE_OBJECT) {
-    const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
+    const ref = field.attr(FIELD_ATTR_OBJECT_REF);
     base = typeof ref === "string" && ref.length > 0 ? stripPackage(ref) : "object";
   } else {
     base = field.subType;
@@ -165,7 +165,7 @@ function neutralTypeCell(field: MetaField): string {
  *  uses. Deliberately does NOT derive ANSI/ORM SQL so it can't drift vs the
  *  migrate engine or re-introduce language-specific DDL. Wrapped in backticks. */
 function storageTypeCell(field: MetaField): string {
-  const dbColumnType = field.ownAttr(FIELD_ATTR_DB_COLUMN_TYPE);
+  const dbColumnType = field.attr(FIELD_ATTR_DB_COLUMN_TYPE);
   if (typeof dbColumnType === "string" && dbColumnType.length > 0) {
     return `\`${dbColumnType.toUpperCase()}\``;
   }
@@ -190,7 +190,7 @@ function buildConstraintRow(
   const rules: string[] = [];
 
   if (isPk) rules.push("primary key");
-  if (field.ownAttr(FIELD_ATTR_UNIQUE) === true) rules.push("unique");
+  if (field.attr(FIELD_ATTR_UNIQUE) === true) rules.push("unique");
 
   if (field.subType === FIELD_SUBTYPE_ENUM && !field.isArray) {
     const values = enumValues(field);
@@ -212,7 +212,7 @@ function buildConstraintRow(
     rules.push(`references \`${fk.targetEntity}.${fk.targetField}\``);
   }
 
-  const def = field.ownAttr(FIELD_ATTR_DEFAULT);
+  const def = field.attr(FIELD_ATTR_DEFAULT);
   if (def !== undefined) rules.push(`default: \`${String(def)}\``);
 
   const sup = field.resolveSuper();
@@ -271,7 +271,7 @@ function buildFieldRow(
   // Otherwise empty. Keeps the column noise-free for the 90% case where
   // field name and column name agree.
   const columnName = field.column;
-  const dbColumnType = field.ownAttr(FIELD_ATTR_DB_COLUMN_TYPE);
+  const dbColumnType = field.attr(FIELD_ATTR_DB_COLUMN_TYPE);
   const columnDiffers = typeof columnName === "string" && columnName !== field.name;
   const hasPhysicalOverride = typeof dbColumnType === "string" && dbColumnType.length > 0;
   let storageCell = "";
@@ -287,7 +287,7 @@ function buildFieldRow(
   // column, plus the maxLength/length/numeric limits that used to live in
   // the separate Limits cell (collapsed in to keep the table to 5 columns).
   const rules: string[] = [];
-  if (field.ownAttr(FIELD_ATTR_UNIQUE) === true) rules.push("unique");
+  if (field.attr(FIELD_ATTR_UNIQUE) === true) rules.push("unique");
 
   if (field.subType === FIELD_SUBTYPE_ENUM && !field.isArray) {
     const values = enumValues(field);
@@ -303,7 +303,7 @@ function buildFieldRow(
   rules.push(...lengthParts, ...numericParts);
 
   // The FK reference is already encoded in typeCell — don't repeat it in rules.
-  const def = field.ownAttr(FIELD_ATTR_DEFAULT);
+  const def = field.attr(FIELD_ATTR_DEFAULT);
   if (def !== undefined) rules.push(`default: \`${String(def)}\``);
 
   const sup = field.resolveSuper();
@@ -340,10 +340,10 @@ function buildFieldDetail(
   const hasSummary = typeof summary === "string" && summary.length > 0;
   const sup = field.resolveSuper();
   const fk = fkMap.get(field.name);
-  const def = field.ownAttr(FIELD_ATTR_DEFAULT);
+  const def = field.attr(FIELD_ATTR_DEFAULT);
   const columnName = field.column;
-  const dbColumnType = field.ownAttr(FIELD_ATTR_DB_COLUMN_TYPE);
-  const isUnique = field.ownAttr(FIELD_ATTR_UNIQUE) === true;
+  const dbColumnType = field.attr(FIELD_ATTR_DB_COLUMN_TYPE);
+  const isUnique = field.attr(FIELD_ATTR_UNIQUE) === true;
   const isEnum = field.subType === FIELD_SUBTYPE_ENUM && !field.isArray;
   const enumVals = isEnum ? enumValues(field) : undefined;
   const validators = field.validators();
@@ -352,7 +352,7 @@ function buildFieldDetail(
       || v.subType === VALIDATOR_SUBTYPE_REGEX
       || v.subType === VALIDATOR_SUBTYPE_NUMERIC,
   );
-  const maxLenAttr = field.ownAttr(FIELD_ATTR_MAX_LENGTH);
+  const maxLenAttr = field.attr(FIELD_ATTR_MAX_LENGTH);
 
   // "Interesting enough to render a detail block" predicate. Plain typed
   // fields with no authored annotations get skipped — the at-a-glance Fields
@@ -503,7 +503,7 @@ function describeIdentity(id: MetaIdentity): string {
     : `(${fields.map((f) => `\`${f}\``).join(", ")})`;
 
   if (id.subType === IDENTITY_SUBTYPE_PRIMARY) {
-    const gen = id.ownAttr(IDENTITY_ATTR_GENERATION);
+    const gen = id.attr(IDENTITY_ATTR_GENERATION);
     const genSuffix = typeof gen === "string" ? ` — generation: \`${gen}\`` : "";
     return `**Primary key:** ${fieldList}${genSuffix}`;
   }

package/src/generators/template-payload-tree.ts

@@ -58,7 +58,7 @@ export function buildEnrichedPayloadTree(
       required: isFieldRequired(f),
     };
     if (f.subType === FIELD_SUBTYPE_OBJECT) {
-      const ref = f.ownAttr(FIELD_ATTR_OBJECT_REF);
+      const ref = f.attr(FIELD_ATTR_OBJECT_REF);
       if (typeof ref === "string" && ref.length > 0) {
         // Owner switches to the nested VO for its fields (the recursion below
         // re-derives `owner` from the resolved VO's own name).

package/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(

package/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",

package/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);
 }
 
 // ---------------------------------------------------------------------------

package/src/payload-codegen.ts

@@ -65,7 +65,7 @@ function fieldTsType(
   ownerName: string,
 ): { type: string; refVo?: string; enumAlias?: { name: string; decl: string } } {
   if (field.subType === FIELD_SUBTYPE_OBJECT) {
-    const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
+    const ref = field.attr(FIELD_ATTR_OBJECT_REF);
     const refName = typeof ref === "string" ? ref : "unknown";
     // isArray is a structural property on MetaData, not an attr.
     const isArray = field.isArray;
@@ -96,7 +96,7 @@ function fieldTsType(
 
 /** True iff the field's @required is explicitly set to true. */
 function isFieldRequired(field: MetaData): boolean {
-  return field.ownAttr(FIELD_ATTR_REQUIRED) === true;
+  return field.attr(FIELD_ATTR_REQUIRED) === true;
 }
 
 function emitInterface(

package/src/pk-resolver.ts

@@ -30,7 +30,9 @@ export function buildPkMap(root: MetaRoot): Map<string, PkInfo> {
     // primaryIdentity() resolves the primary identity across the super-chain.
     const primary = obj.primaryIdentity();
     if (!primary) continue;
-    const fields = primary.ownAttr(IDENTITY_ATTR_FIELDS);
+    // attr() (effective) not ownAttr() — @fields/@generation can be inherited when the
+    // identity node-level `extends` a base identity without restating them (#56).
+    const fields = primary.attr(IDENTITY_ATTR_FIELDS);
     if (!Array.isArray(fields) && typeof fields !== "string") continue;
     const fieldsList = Array.isArray(fields) ? fields : [fields];
     if (fieldsList.length === 0) continue;
@@ -38,7 +40,7 @@ export function buildPkMap(root: MetaRoot): Map<string, PkInfo> {
     // findField() resolves the field across the super-chain (handles extends:).
     const pkField = obj.findField(pkFieldName);
     const fieldSubType = pkField?.subType ?? FIELD_SUBTYPE_LONG; // sane default
-    const generation = primary.ownAttr(IDENTITY_ATTR_GENERATION);
+    const generation = primary.attr(IDENTITY_ATTR_GENERATION);
     const info: PkInfo = { fieldName: pkFieldName, fieldSubType };
     if (typeof generation === "string") info.generation = generation;
     result.set(obj.name, info);

package/src/projection/extract-view-spec.ts

@@ -135,7 +135,7 @@ function sourceColumnNameFor(
   entityField: MetaData,
   ctx: ExtractContext,
 ): string {
-  const col = entityField.ownAttr(FIELD_ATTR_COLUMN);
+  const col = entityField.attr(FIELD_ATTR_COLUMN);
   if (typeof col === "string" && col !== "") return col;
   return columnNameFromField(entityField.name, ctx.columnNamingStrategy);
 }

package/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),
   };
 }

package/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,

package/src/templates/drizzle-schema.ts

@@ -3,7 +3,7 @@
 // plus the relations() block auto-emitted at the end.
 
 import { code, imp, joinCode, type Code } from "ts-poet";
-import { MetaObject, MetaField } from "@metaobjectsdev/metadata";
+import { MetaObject, MetaField, stripPackage } from "@metaobjectsdev/metadata";
 import {
   IDENTITY_SUBTYPE_SECONDARY, FIELD_SUBTYPE_LONG,
   IDENTITY_ATTR_FIELDS, IDENTITY_ATTR_GENERATION, IDENTITY_ATTR_UNIQUE,
@@ -11,9 +11,9 @@ import {
   FIELD_ATTR_AUTO_SET,
 } from "@metaobjectsdev/metadata";
 import { type RenderContext } from "../render-context.js";
-import { crossEntitySpecifier } from "../import-path.js";
+import { crossEntitySpecifier, valueObjectModuleSpecifier } from "../import-path.js";
 import { mapColumnType, type ColumnSpec } from "../column-mapper.js";
-import { tableNameFromEntity, variableNameFromEntity, columnNameFromField } from "../naming.js";
+import { tableNameFromEntity, columnNameFromField } from "../naming.js";
 import { renderRelationsBlock } from "./relations-block.js";
 import { renderDocsFor } from "./jsdoc.js";
 import { collectTphSubtypeFields } from "./tph-discriminator.js";
@@ -33,17 +33,17 @@ export function renderDrizzleSchema(obj: MetaObject, ctx: RenderContext): Code {
   const tableFnSym = imp(`${tableFn}@${importModule}`);
 
   const tableName = obj.dbTable ?? tableNameFromEntity(obj.name, ctx.columnNamingStrategy);
-  const varName = variableNameFromEntity(obj.name);
+  const varName = ctx.collectionName(obj.name);
 
   const primary = obj.primaryIdentity();
-  const rawPkFields = primary?.ownAttr(IDENTITY_ATTR_FIELDS);
+  const rawPkFields = primary?.attr(IDENTITY_ATTR_FIELDS);
   const pkFieldsList: string[] = Array.isArray(rawPkFields)
     ? rawPkFields as string[]
     : typeof rawPkFields === "string"
       ? rawPkFields.split(",").map((f) => f.trim()).filter(Boolean)
       : [];
   const pkFieldNames = new Set<string>(pkFieldsList);
-  const pkGeneration = primary?.ownAttr(IDENTITY_ATTR_GENERATION) as string | undefined;
+  const pkGeneration = primary?.attr(IDENTITY_ATTR_GENERATION) as string | undefined;
 
   const fkMap = buildFkMapForEntity(obj, ctx);
 
@@ -56,9 +56,9 @@ export function renderDrizzleSchema(obj: MetaObject, ctx: RenderContext): Code {
   const secondaryIdentities = obj.secondaryIdentities();
   const uniqueFieldNames = new Set<string>();
   for (const sec of secondaryIdentities) {
-    const uniqueAttr = sec.ownAttr(IDENTITY_ATTR_UNIQUE);
+    const uniqueAttr = sec.attr(IDENTITY_ATTR_UNIQUE);
     if (uniqueAttr === false) continue; // explicit non-unique → don't mark column
-    const fields = sec.ownAttr(IDENTITY_ATTR_FIELDS) as string[] | undefined;
+    const fields = sec.attr(IDENTITY_ATTR_FIELDS) as string[] | undefined;
     if (!Array.isArray(fields) || fields.length !== 1) continue; // multi-col uniques use a callback index, not a column flag
     uniqueFieldNames.add(fields[0]!);
   }
@@ -72,9 +72,9 @@ export function renderDrizzleSchema(obj: MetaObject, ctx: RenderContext): Code {
     const fkInfo = fkMap.get(child.name);
     // Compute the column spec once per field and reuse it for both the column
     // line and the CHECK collection.
-    const spec = mapColumnType(child, ctx.dialect, ctx.columnNamingStrategy);
+    const spec = mapColumnType(child, ctx.dialect, ctx.columnNamingStrategy, ctx.timestampMode);
     const fieldDocs = renderDocsFor(child);
-    const columnLine = renderColumn(spec, child, ctx, isPk, pkGeneration, fkInfo, isComposite, isUnique, obj.package);
+    const columnLine = renderColumn(spec, child, ctx, isPk, pkGeneration, fkInfo, isComposite, isUnique, obj.package, obj.name);
     columnLines.push(fieldDocs ? code`  ${fieldDocs}\n${columnLine}` : columnLine);
     if (spec.checkConstraint !== undefined) {
       checkConstraints.push({
@@ -91,10 +91,10 @@ export function renderDrizzleSchema(obj: MetaObject, ctx: RenderContext): Code {
   // stamp onto other-subtype inserts), regardless of the field's @required.
   // Subtype entities emit no table of their own (the value-object path).
   for (const child of collectTphSubtypeFields(obj, ctx.loadedRoot)) {
-    const spec = mapColumnType(child, ctx.dialect, ctx.columnNamingStrategy);
+    const spec = mapColumnType(child, ctx.dialect, ctx.columnNamingStrategy, ctx.timestampMode);
     const fieldDocs = renderDocsFor(child);
     const columnLine = renderColumn(
-      spec, child, ctx, false, undefined, fkMap.get(child.name), isComposite, false, obj.package, true,
+      spec, child, ctx, false, undefined, fkMap.get(child.name), isComposite, false, obj.package, obj.name, true,
     );
     columnLines.push(fieldDocs ? code`  ${fieldDocs}\n${columnLine}` : columnLine);
     // Enum CHECK constraints stay valid under TPH: `NULL IN (...)` is NULL
@@ -115,13 +115,13 @@ export function renderDrizzleSchema(obj: MetaObject, ctx: RenderContext): Code {
   }
 
   for (const sec of secondaryIdentities) {
-    const fields = sec.ownAttr(IDENTITY_ATTR_FIELDS) as string[] | undefined;
+    const fields = sec.attr(IDENTITY_ATTR_FIELDS) as string[] | undefined;
     if (!Array.isArray(fields) || fields.length === 0) continue;
     const indexName = `idx_${tableName}_${fields.map((f) => columnNameFromField(f, ctx.columnNamingStrategy)).join("_")}`;
     // @unique on the identity defaults to true (preserves back-compat with
     // foundations fixtures that assumed secondary identities were always
     // unique). Explicit @unique: false → ordinary non-unique index.
-    const uniqueAttr = sec.ownAttr(IDENTITY_ATTR_UNIQUE);
+    const uniqueAttr = sec.attr(IDENTITY_ATTR_UNIQUE);
     const isUnique = uniqueAttr !== false;
     const indexFn = isUnique ? "uniqueIndex" : "index";
     const indexSym = imp(`${indexFn}@${importModule}`);
@@ -184,11 +184,15 @@ function buildFkMapForEntity(obj: MetaObject, ctx: RenderContext): Map<string, F
     const fkField = fkFieldNames[0]!;
     const targetName = ref.targetEntity;
     if (!targetName) continue;
-    const targetObj = ctx.loadedRoot.findObject(targetName);
+    // @references may be authored bare OR package-qualified, and the loader can
+    // resolve it to an FQN (e.g. the YAML front-end qualifies it). Strip the
+    // package so the lookup matches the object's bare name — mirrors the
+    // relation-resolver, which already does this.
+    const targetObj = ctx.loadedRoot.findObject(stripPackage(targetName));
     if (!targetObj) continue;
     const targetPkField = ref.resolvedTargetPkField(ctx.loadedRoot) ?? "id";
     result.set(fkField, {
-      targetVarName: variableNameFromEntity(targetObj.name),
+      targetVarName: ctx.collectionName(targetObj.name),
       targetEntityName: targetObj.name,
       targetPkField,
     });
@@ -236,6 +240,9 @@ function renderColumn(
   isComposite: boolean,
   isUnique: boolean = false,
   entityPackage: string | undefined = undefined,
+  // Name of the entity this column belongs to — used to detect a self-referential
+  // FK (target entity === this entity), which Drizzle emits without a self-import.
+  currentEntityName: string = "",
   // FR-017 Tier 2 — TPH subtype-only column: force nullable (drop .notNull())
   // and suppress any DB default (other-subtype rows must stay NULL here).
   forceNullable: boolean = false,
@@ -319,21 +326,30 @@ function renderColumn(
   // FK .references() uses imp() so ts-poet tracks the cross-entity import.
   let fkRefSegment: Code | null = null;
   if (fkInfo !== undefined && !isPk) {
-    const targetSpec = crossEntitySpecifier(
-      ctx.outputLayout,
-      entityPackage,
-      ctx.packageOf.get(fkInfo.targetEntityName),
-      fkInfo.targetEntityName,
-      ctx.extStyle,
-    );
-    const targetVarSym = imp(`${fkInfo.targetVarName}@${targetSpec}`);
-    fkRefSegment = code`.references(() => ${targetVarSym}.${fkInfo.targetPkField})`;
+    if (fkInfo.targetEntityName === currentEntityName) {
+      // Self-referential FK (e.g. createdBy → this same table). Drizzle requires
+      // referencing the local table const directly — NOT a self-import — with an
+      // explicit `Any*Column` return type to break the circular type inference.
+      const anyColType = ctx.dialect === "sqlite" ? "AnySQLiteColumn" : "AnyPgColumn";
+      const anyColSym = imp(`${anyColType}@${spec.importModule}`);
+      fkRefSegment = code`.references((): ${anyColSym} => ${fkInfo.targetVarName}.${fkInfo.targetPkField})`;
+    } else {
+      const targetSpec = crossEntitySpecifier(
+        ctx.outputLayout,
+        entityPackage,
+        ctx.packageOf.get(fkInfo.targetEntityName),
+        fkInfo.targetEntityName,
+        ctx.extStyle,
+      );
+      const targetVarSym = imp(`${fkInfo.targetVarName}@${targetSpec}`);
+      fkRefSegment = code`.references(() => ${targetVarSym}.${fkInfo.targetPkField})`;
+    }
   }
 
   // @autoSet fields: emit .$defaultFn(() => new Date().toISOString()) so Drizzle
   // inserts stamp the server-side timestamp automatically. This means callers don't
   // need to supply createdAt / updatedAt in INSERT calls — Drizzle fills them in.
-  const autoSet = field.ownAttr(FIELD_ATTR_AUTO_SET);
+  const autoSet = field.attr(FIELD_ATTR_AUTO_SET);
   const autoSetSuffix = (autoSet === "onCreate" || autoSet === "onUpdate")
     ? `.$defaultFn(() => new Date().toISOString())`
     : "";
@@ -346,11 +362,17 @@ function renderColumn(
   let dollarTypeSegment: Code | string = "";
   if (spec.dollarTypeRef !== undefined) {
     const ref = spec.dollarTypeRef;
+    const suffix = ref.array ? "[]" : "";
     if (ref.kind === "scalar") {
-      dollarTypeSegment = `.$type<${ref.tsType}[]>()`;
+      dollarTypeSegment = `.$type<${ref.tsType}${suffix}>()`;
     } else {
-      const refSym = imp(`${ref.name}@${ref.module}`);
-      dollarTypeSegment = code`.$type<${refSym}[]>()`;
+      // Resolve the VO module through the shared layout/package/extStyle-aware
+      // helper so the .$type<VO> import matches the field's TS type + Zod schema.
+      const moduleSpec = valueObjectModuleSpecifier(
+        ref.name, ctx.packageOf, entityPackage, ctx.outputLayout, ctx.extStyle,
+      );
+      const refSym = imp(`${ref.name}@${moduleSpec}`);
+      dollarTypeSegment = ref.array ? code`.$type<${refSym}[]>()` : code`.$type<${refSym}>()`;
     }
   }
 

package/src/templates/entity-constants.ts

@@ -160,12 +160,12 @@ function renderFieldRules(field: MetaField): string | undefined {
   }
 
   // Field-level @required attr (if not already covered by validator).
-  if (!hasRequired && field.ownAttr(FIELD_ATTR_REQUIRED) === true) {
+  if (!hasRequired && field.attr(FIELD_ATTR_REQUIRED) === true) {
     ruleParts.push(`required: ${JSON.stringify(`${humanize(field.name)} is required`)}`);
   }
 
   // Field-level @maxLength attr (if not already covered).
-  const maxLenAttr = field.ownAttr(FIELD_ATTR_MAX_LENGTH);
+  const maxLenAttr = field.attr(FIELD_ATTR_MAX_LENGTH);
   if (!hasMaxLength && typeof maxLenAttr === "number") {
     ruleParts.push(
       `maxLength: { value: ${maxLenAttr}, message: ${JSON.stringify(`Must be ${maxLenAttr} characters or fewer`)} }`,

package/src/templates/entity-file.ts

@@ -89,7 +89,7 @@ export function renderEntityFile(
   const tphBase = tphBlock !== null && isTphDiscriminatorBase(entity, ctx.loadedRoot);
   const sections: Code[] = [
     renderDrizzleSchema(entity, ctx),
-    renderInferredTypes(entity, tphBase),
+    renderInferredTypes(entity, tphBase, ctx),
     ...(enumAliases !== null ? [enumAliases] : []),
     renderZodValidators(entity, ctx),
     renderEntityConstants(entity, ctx.apiPrefix),

package/src/templates/extract-delegate-emitter.ts

@@ -37,7 +37,7 @@ function findObject(root: MetaData, name: string): MetaData | undefined {
 
 /** The @objectRef target VO for a nested-object field, or undefined when unresolvable. */
 function refVo(field: MetaData, root: MetaData): MetaData | undefined {
-  const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
+  const ref = field.attr(FIELD_ATTR_OBJECT_REF);
   if (typeof ref !== "string") return undefined;
   const direct = findObject(root, ref);
   if (direct !== undefined) return direct;

package/src/templates/extractor.ts

@@ -50,7 +50,7 @@ function findTemplate(root: MetaData, name: string): MetaData | undefined {
 
 /** The @objectRef target VO for a nested-object field, or undefined when unresolvable. */
 function refVo(field: MetaData, root: MetaData): MetaData | undefined {
-  const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
+  const ref = field.attr(FIELD_ATTR_OBJECT_REF);
   if (typeof ref !== "string") return undefined;
   const direct = findObject(root, ref);
   if (direct !== undefined) return direct;
@@ -85,7 +85,7 @@ function enumAlias(field: MetaData, ownerName: string): string | undefined {
  * required test (boolean `true` only) so the two never skew.
  */
 function isFieldRequired(field: MetaData): boolean {
-  return field.ownAttr(FIELD_ATTR_REQUIRED) === true;
+  return field.attr(FIELD_ATTR_REQUIRED) === true;
 }
 
 /** The mirror→strict mapper name for a value-object (`toStrict<Name>`). */

package/src/templates/field-meta.ts

@@ -114,7 +114,7 @@ export function zodTypeFor(field: MetaField): string {
 export function currencyMetaFor(field: MetaField): { currency: string; locale: string } | null {
   if (field.subType !== FIELD_SUBTYPE_CURRENCY) return null;
   const currency =
-    (field.ownAttr(FIELD_ATTR_CURRENCY) as string | undefined) ?? FIELD_ATTR_CURRENCY_DEFAULT;
+    (field.attr(FIELD_ATTR_CURRENCY) as string | undefined) ?? FIELD_ATTR_CURRENCY_DEFAULT;
   const viewChild = field.views().find((c) => c.subType === VIEW_SUBTYPE_CURRENCY);
   const locale =
     (viewChild?.ownAttr(VIEW_CURRENCY_ATTR_LOCALE) as string | undefined) ??