@metaobjectsdev/codegen-ts 1.0.0-rc.4 → 1.0.0-rc.5

package/src/overwrite-policy.ts

@@ -45,20 +45,30 @@ import { spawnSync } from "node:child_process";
 import { tmpdir } from "node:os";
 import { createHash, randomBytes } from "node:crypto";
 
-export type WriteStatus =
-  | "new"
-  | "unchanged"
-  | "overwrite"
-  | "merged"
-  | "conflict"
-  | "refused"
-  | "skipped"
+/**
+ * Every outcome a write decision can have. An `as const` array rather than a bare
+ * union so a consumer that MAPS these — the CLI's reporting layer does — can be
+ * gated against the full set instead of against a second list of its own. The CLI
+ * silently folded "overwrite" into "new" for exactly as long as no test could
+ * enumerate what it was folding.
+ */
+export const WRITE_STATUSES = [
+  "new",
+  "unchanged",
+  "overwrite",
+  "merged",
+  "conflict",
+  "refused",
+  "skipped",
   /** FR-038 §8 — deleted because it was generated by a previous run, is no longer
    *  generated, and was never edited by hand. Reported as a file outcome rather
    *  than a warning because a deletion is exactly as consequential as a write,
    *  and a run summary that lists writes but hides deletions is how a silent
    *  deletion happens. */
-  | "removed";
+  "removed",
+] as const;
+
+export type WriteStatus = (typeof WRITE_STATUSES)[number];
 
 /**
  * "overwrite" — default; three-way merge if .gen-state exists, else write-if-

package/src/reference/barrel.ts

@@ -26,6 +26,7 @@ import {
   barrelModuleSpecifier,
   formatTs,
   GENERATED_HEADER,
+  effectivePackage,
 } from "@metaobjectsdev/codegen-ts";
 
 interface BarrelEntry {
@@ -63,7 +64,7 @@ export const barrel = function barrel(opts?: BarrelOpts): Generator {
         path: "index.ts",
         content: await formatTs(
           renderBarrel(
-            entities.map((e) => ({ name: rc.valueObjectEmittedName(e), package: e.package })),
+            entities.map((e) => ({ name: rc.valueObjectEmittedName(e), package: effectivePackage(e) })),
             rc.extStyle,
             rc.selfTarget,
             rc.entityModuleTarget,

package/src/reference/entity.ts

@@ -32,7 +32,7 @@
 // primitives below, or (with a globally-installed / linked CLI, where the project and
 // the CLI resolve ts-poet to different physical copies) every section renders
 // standalone with its own duplicate import header.
-import { joinCode, type Code } from "@metaobjectsdev/codegen-ts";
+import { joinCode, type Code, effectivePackage } from "@metaobjectsdev/codegen-ts";
 import type { MetaObject } from "@metaobjectsdev/metadata";
 import {
   perEntity,
@@ -164,7 +164,7 @@ export const entityFile = function entityFile(opts?: EntityFileOpts): Generator
       return [];
     }
     return {
-      path: entityOutputPath(ctx.config.outputLayout ?? "flat", entity.package, `${entity.name}.ts`),
+      path: entityOutputPath(ctx.config.outputLayout ?? "flat", effectivePackage(entity), `${entity.name}.ts`),
       content: await formatTs(renderEntity(entity, ctx.renderContext, { allowlists })),
     };
   });

package/src/reference/names.ts

@@ -39,11 +39,26 @@ import {
   type EmittedFile,
   type GenContext,
   type Generator,
+  effectivePackage,
 } from "@metaobjectsdev/codegen-ts";
 import type { MetaObject } from "@metaobjectsdev/metadata";
 
-export function namesFile(): Generator {
-  return {
+export interface NamesFileOpts {
+  /**
+   * Narrow which objects get a names artifact. ANDed with the generator's own
+   * gates, so it can only narrow — the abstract bases a MATCHED object extends
+   * are still emitted, because the matched object's artifact `extends` them.
+   *
+   * A multi-package model is why this exists: one metadata tree can drive several
+   * consumers, and only some of its objects belong to the tier being generated.
+   */
+  filter?: (entity: MetaObject) => boolean;
+  /** Named output target, as on every other generator. */
+  target?: string;
+}
+
+export function namesFile(opts?: NamesFileOpts): Generator {
+  const generator: Generator = {
     name: "names",
     // §A6 — the marker the runner aggregates into ResolvedGenConfig.includeNames, so the
     // entity generator can tell whether this artifact will exist. Exactly the mechanism
@@ -63,13 +78,13 @@ export function namesFile(): Generator {
         // its entity sits at <pkg>/<Entity>.ts — an unresolvable import, and a hard
         // conflicting-duplicate-path failure as soon as two packages declare a
         // same-bare-named entity.
-        entityOutputPath(layout, obj.package, `${obj.name}.names.ts`);
+        entityOutputPath(layout, effectivePackage(obj), `${obj.name}.names.ts`);
 
       const superSpecifierFor = (obj: MetaObject): string | undefined => {
         const sup = namesArtifactSuperOf(obj);
         return sup === undefined
           ? undefined
-          : crossEntitySpecifier(layout, obj.package, sup.package, `${sup.name}.names`, extStyle);
+          : crossEntitySpecifier(layout, effectivePackage(obj), effectivePackage(sup), `${sup.name}.names`, extStyle);
       };
 
       const out: EmittedFile[] = [];
@@ -122,4 +137,11 @@ export function namesFile(): Generator {
       return out;
     },
   };
+  if (opts?.filter) {
+    generator.filter = opts.filter;
+  }
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
 }

package/src/reference/queries.ts

@@ -30,7 +30,7 @@
 // primitives below, or (with a globally-installed / linked CLI, where the project and
 // the CLI resolve ts-poet to different physical copies) every section renders
 // standalone with its own duplicate import header.
-import { code, joinCode, type Code } from "@metaobjectsdev/codegen-ts";
+import { code, joinCode, type Code, effectivePackage } from "@metaobjectsdev/codegen-ts";
 import type { MetaObject } from "@metaobjectsdev/metadata";
 import {
   perEntity,
@@ -71,7 +71,7 @@ function renderQueries(obj: MetaObject, ctx: RenderContext): string {
   const entityFileName = entityModuleSpecifier(
     ctx.selfTarget,
     ctx.entityModuleTarget,
-    obj.package,
+    effectivePackage(obj),
     entityName,
     ctx.extStyle,
   );
@@ -162,7 +162,7 @@ export const queriesFile = function queriesFile(opts?: QueriesFileOpts): Generat
         throw new Error("queries-file: renderContext is required (provided by runGen)");
       }
       return {
-        path: entityOutputPath(ctx.config.outputLayout ?? "flat", entity.package, `${entity.name}.queries.ts`),
+        path: entityOutputPath(ctx.config.outputLayout ?? "flat", effectivePackage(entity), `${entity.name}.queries.ts`),
         content: await formatTs(renderQueries(entity, ctx.renderContext)),
       };
     }),

package/src/reference/routes-hono.ts

@@ -38,6 +38,7 @@ import {
   hasAnyRdbSource,
   formatTs,
   entityOutputPath,
+  effectivePackage,
 } from "@metaobjectsdev/codegen-ts";
 
 export interface RoutesFileHonoOpts {
@@ -100,7 +101,7 @@ export const routesFileHono = function routesFileHono(opts?: RoutesFileHonoOpts)
       return {
         path: entityOutputPath(
           ctx.config.outputLayout ?? "flat",
-          entity.package,
+          effectivePackage(entity),
           `${entity.name}.routes.hono.ts`,
         ),
         content: await formatTs(renderRoutesFileHono(entity, ctx.renderContext, resolveExpose(entity, opts?.expose))),

package/src/reference/routes.ts

@@ -46,6 +46,7 @@ import {
   hasAnyRdbSource,
   formatTs,
   entityOutputPath,
+  effectivePackage,
 } from "@metaobjectsdev/codegen-ts";
 
 export interface RoutesFileOpts {
@@ -79,7 +80,7 @@ export const routesFile = function routesFile(opts?: RoutesFileOpts): Generator
         throw new Error("routes-file: renderContext is required (provided by runGen)");
       }
       return {
-        path: entityOutputPath(ctx.config.outputLayout ?? "flat", entity.package, `${entity.name}.routes.ts`),
+        path: entityOutputPath(ctx.config.outputLayout ?? "flat", effectivePackage(entity), `${entity.name}.routes.ts`),
         content: await formatTs(renderRoutesFile(entity, ctx.renderContext, resolveExpose(entity, opts?.expose))),
       };
     }),

package/src/runner.ts

@@ -19,6 +19,7 @@ import { buildRelationMap } from "./relation-resolver.js";
 import { makeRenderContext } from "./render-context.js";
 import { sweepOrphans, type OrphanJob } from "./orphan-sweep.js";
 import { refusedOrphanMessage } from "./reconcile-orphans.js";
+import { effectivePackage } from "./docs-paths.js";
 import {
   decideAndWrite,
   previewWriteStatus,
@@ -140,6 +141,20 @@ function orderable(v: string | undefined): [number, number, number] | undefined
   return m === null ? undefined : [Number(m[1]), Number(m[2]), Number(m[3])];
 }
 
+/** True when `a` sorts strictly before `b` under `[major, minor, patch]` order. The
+ *  shared comparison the two "did we just cross a release boundary" predicates below
+ *  reduce to once both sides are `orderable()` — their SILENCE rules (what makes a
+ *  boundary crossing worth noting at all) stay separate; only this pure ordering is
+ *  common between them. */
+function versionBefore(a: readonly [number, number, number], b: readonly [number, number, number]): boolean {
+  for (let i = 0; i < 3; i++) {
+    const ai = a[i] as number;
+    const bi = b[i] as number;
+    if (ai !== bi) return ai < bi;
+  }
+  return false;
+}
+
 /**
  * True exactly on the FIRST gen after upgrading past the release that moved the API base
  * URL out of the entity descriptor, and only for a project that actually had a prefix to
@@ -166,12 +181,49 @@ export function shouldNoteBaseUrlMove(
   const was = orderable(recordedEngine);
   const move = orderable(moveVersion);
   if (was === undefined || move === undefined) return false;
-  for (let i = 0; i < 3; i++) {
-    const a = was[i] as number;
-    const b = move[i] as number;
-    if (a !== b) return a < b;
-  }
-  return false;
+  return versionBefore(was, move);
+}
+
+/** The release in which `<Entity>Names` became the way a physical name is spelled once. */
+const NAMES_ARTIFACT_VERSION = "1.0.0";
+
+/**
+ * True exactly on the FIRST gen after crossing into the release that made
+ * `<Entity>Names` the doctrine, for a project that has DB-backed objects and has not
+ * wired `namesFile()`. Exported for test.
+ *
+ * The problem it addresses was reported from three separate adopter estates: on
+ * TypeScript `generators: [...]` IS the complete suite — there is no default set to
+ * inherit — so an EXISTING project emits no names artifact until the line is added, and
+ * `meta gen` said nothing about it. One estate carried ~200 physical names as string
+ * literals in hand-written SQL and the whole run contained zero occurrences of the word
+ * "names". `meta init` scaffolds the generator, so the gap is only ever for projects that
+ * already exist — which is exactly the population that cannot be reached by a scaffold.
+ *
+ * Keyed on the #232 engine stamp for the same reason `shouldNoteBaseUrlMove` is: whether
+ * an adopter has DECIDED against the artifact is not something `meta gen` can see, so a
+ * condition-only trigger would nag for ever with no way to satisfy it — the cry-wolf
+ * failure that got the `timestampMode` warning deleted from this file. Crossing the
+ * version boundary is an event that happens once.
+ *
+ * Silence is the default for an absent or unorderable recorded version, matching
+ * `shouldNoteBaseUrlMove`: no gen history means nothing has been generated the old way,
+ * and a project generating for the first time under 1.0 is not migrating.
+ */
+export function shouldNoteNamesArtifactAbsent(
+  namesWired: boolean,
+  hasDbBackedObject: boolean,
+  recordedEngine: string | undefined,
+  sinceVersion: string = NAMES_ARTIFACT_VERSION,
+): boolean {
+  if (namesWired) return false;
+  // Nothing with a physical name to spell — an all-value / sourceless model has no
+  // artifact to miss, and saying so would be noise rather than a finding.
+  if (!hasDbBackedObject) return false;
+  const was = orderable(recordedEngine);
+  const since = orderable(sinceVersion);
+  if (was === undefined || since === undefined) return false;
+  return versionBefore(was, since);
 }
 
 export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
@@ -411,7 +463,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
     const key = o.subType === OBJECT_SUBTYPE_VALUE
       ? (valueObjectNames.get(o.resolutionKey()) ?? o.name)
       : o.name;
-    packageOf.set(key, o.package);
+    packageOf.set(key, effectivePackage(o));
   }
 
   // Auto-detect: is the OPT-IN Hono routes generator in the active suite? If so,
@@ -442,6 +494,29 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   // prompt-generator-gate.ts. Self-extinguishing; warning only.
   warnMissingPromptGenerators(root, config.generators, (m) => warnings.push(m));
 
+  // <Entity>Names is opt-in on TypeScript and an existing project gets no signal that
+  // it exists. Fires ONCE, on the first gen after crossing the release that made it the
+  // doctrine — see shouldNoteNamesArtifactAbsent for why it is keyed on the engine stamp
+  // rather than on the condition alone.
+  if (
+    shouldNoteNamesArtifactAbsent(
+      namesTargets.size > 0,
+      safeEntities.some((e) => hasAnyRdbSource(e)),
+      recordedEngine,
+    )
+  ) {
+    warnings.push(
+      `no <Entity>Names artifact: namesFile() is not in this run's generators, so every ` +
+        `physical table/column name your hand-written SQL, upserts and fixtures spell is a ` +
+        `string literal that nothing checks against the metadata. Add it — ` +
+        `import { namesFile } from "@metaobjectsdev/codegen-ts/generators" (or the copy ` +
+        `'meta eject names' writes) — then reference <Entity>Names instead of the literals. ` +
+        `A typed ORM handle already in a name position is CORRECT and should stay; the ` +
+        `constants are for where no handle exists (raw SQL, excluded.<column>). ` +
+        `This note appears once.`,
+    );
+  }
+
   // A retired `@emit*` codegen flag still sitting in the metadata suppresses nothing now.
   // Named here rather than left to be discovered as a file that reappeared. Scoped to
   // the run's own entity set (the same set every generator sees), so `meta gen <entity>`
@@ -455,6 +530,10 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   // directory their policy's relative paths are measured from. Collected here
   // because `writeOutDir` is resolved per generator inside this loop.
   const orphanJobs: OrphanJob[] = [];
+  // Generators that ran and produced no file. See the note at the `files.length === 0`
+  // check below. A Set because a generator may run once per target.
+  const emptyGenerators = new Set<string>();
+
   for (const generator of config.generators) {
     // ADR-0025: `meta docs` is the single docs door. A `meta gen` config that
     // still lists a deprecated doc generator is warned + skipped, not run — the
@@ -547,6 +626,17 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
     let files: EmittedFile[];
     try {
       files = await generator.generate(ctx);
+      // A generator the author DELIBERATELY WIRED that matched nothing is a fact
+      // worth one line. `namesFile()` on a model with no DB-backed object emitted
+      // zero files with no line, no count and no warning, and an adopter could not
+      // tell that from a run that had done the work. 0.21.4 gave `tanstackGrid()`
+      // a self-extinguishing warning for exactly this shape.
+      //
+      // Collected rather than warned per generator: one aggregated line names every
+      // silent generator, so a suite with several inapplicable ones costs one line,
+      // not five. Emitting nothing is often CORRECT — a form generator on a model
+      // with no forms — so this reports, it never fails.
+      if (files.length === 0) emptyGenerators.add(generator.name);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       // `cause` preserves the original throw. Without it a `runGen` caller sees a
@@ -579,6 +669,21 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
     }
   }
 
+  // One line for every wired generator that matched nothing — see the note at the
+  // collection site. Deliberately AFTER the loop so the message is a single line
+  // naming all of them, and deliberately a warning: emitting nothing is frequently
+  // the correct outcome, and a gate that failed on it would be wrong more often
+  // than right.
+  if (emptyGenerators.size > 0) {
+    const names = [...emptyGenerators].sort();
+    warnings.push(
+      `${names.length} wired generator(s) matched nothing and wrote no file: ` +
+        `${names.join(", ")}. That is often correct — a generator whose metadata this ` +
+        `model does not declare has nothing to emit. It is reported because a run that ` +
+        `emitted nothing and a run that did the work otherwise look identical.`,
+    );
+  }
+
   // 5. Write phase.
   const writes: WriteResult[] = [];
   const conflicts: WriteResult[] = [];

package/src/templates/callable-file.ts

@@ -35,6 +35,7 @@ import { GENERATED_HEADER } from "../constants.js";
 import { crossEntitySpecifier } from "../import-path.js";
 import { resolveObjectNames } from "../names.js";
 import type { RenderContext } from "../render-context.js";
+import { effectivePackage } from "../docs-paths.js";
 
 const CALLABLE_KINDS: ReadonlySet<string> = new Set([
   SOURCE_KIND_STORED_PROC,
@@ -128,7 +129,7 @@ export function renderCallableFile(entity: MetaObject, ctx?: RenderContext): str
   const namesImport = namesConst === undefined
     ? ""
     : `import { ${namesConst} } from "${crossEntitySpecifier(
-        ctx!.selfTarget.outputLayout, entity.package, entity.package,
+        ctx!.selfTarget.outputLayout, effectivePackage(entity), effectivePackage(entity),
         `${entity.name}.names`, ctx!.extStyle,
       )}";\n`;
   // The identifier must stay an IDENTIFIER. A bare interpolation into drizzle's `sql` tag

package/src/templates/drizzle-schema.ts

@@ -5,7 +5,6 @@
 import { code, imp, joinCode, type Code } from "ts-poet";
 import { MetaObject, MetaField, MetaIndex, isMetaObject, stripPackage } from "@metaobjectsdev/metadata";
 import {
-  FIELD_SUBTYPE_LONG,
   IDENTITY_ATTR_FIELDS, IDENTITY_ATTR_GENERATION,
   IDENTITY_ATTR_EXPR, IDENTITY_ATTR_USING, IDENTITY_ATTR_ORDERS, IDENTITY_ATTR_WHERE,
   GENERATION_INCREMENT, GENERATION_UUID,
@@ -14,7 +13,10 @@ import {
 } from "@metaobjectsdev/metadata";
 import { fieldDeclaringPackage, type RenderContext } from "../render-context.js";
 import { crossEntitySpecifier, valueObjectModuleSpecifier } from "../import-path.js";
-import { mapColumnType, type ColumnSpec, type EnumIntCustomType } from "../column-mapper.js";
+import {
+  mapColumnType, PG_IDENTITY_CAPABLE_FNS,
+  type ColumnSpec, type EnumIntCustomType,
+} from "../column-mapper.js";
 import { tableNameFromEntity } from "../naming.js";
 import {
   namesRef, physicalNameExpr, sourceSchemaExpr, indexNameExpr, columnExpr,
@@ -23,6 +25,7 @@ import { resolveTableSchema } from "@metaobjectsdev/metadata";
 import { renderRelationsBlock } from "./relations-block.js";
 import { renderDocsFor } from "./jsdoc.js";
 import { collectTphSubtypeFields } from "./tph-discriminator.js";
+import { effectivePackage } from "../docs-paths.js";
 
 /**
  * Render the Drizzle table definition for one entity, including:
@@ -102,6 +105,10 @@ export function renderDrizzleSchema(obj: MetaObject, ctx: RenderContext): Code {
   // `isMetaObject`, never `instanceof`: two physical copies of @metaobjectsdev/metadata in
   // one process give the class object and the instance different identities, so the check
   // would return false for a real node — silently.
+  // `obj` never changes across this function, so its effective package is computed once
+  // and reused everywhere below (the `fromPackage` passed to `namesRef` here, and the
+  // per-field `renderColumn` calls in both the own-field and TPH-subtype-fold loops).
+  const pkg = effectivePackage(obj);
   const columnNameExpr = (field: MetaField, dbName: string): Code => {
     if (names === undefined || names.resolved.fields[field.name] !== undefined) {
       return columnExpr(names, field.name, dbName);
@@ -111,7 +118,7 @@ export function renderDrizzleSchema(obj: MetaObject, ctx: RenderContext): Code {
     // base's), not to the subtype's own package.
     const ownerNames =
       owner !== undefined && isMetaObject(owner) && owner !== obj
-        ? namesRef(owner, ctx, obj.package)
+        ? namesRef(owner, ctx, pkg)
         : undefined;
     return columnExpr(ownerNames, field.name, dbName);
   };
@@ -202,7 +209,7 @@ export function renderDrizzleSchema(obj: MetaObject, ctx: RenderContext): Code {
       enumIntTypes.set(spec.enumIntCustomType.fnConstName, spec.enumIntCustomType);
     }
     const fieldDocs = renderDocsFor(child);
-    const columnLine = renderColumn(spec, columnNameExpr(child, spec.dbName), child, ctx, isPk, pkGeneration, fkInfo, isComposite, obj.package, obj.name);
+    const columnLine = renderColumn(spec, columnNameExpr(child, spec.dbName), child, ctx, isPk, pkGeneration, fkInfo, isComposite, pkg, obj.name);
     columnLines.push(fieldDocs ? code`  ${fieldDocs}\n${columnLine}` : columnLine);
     if (spec.checkConstraint !== undefined) checkConstraints.push(checkEntry(child, spec));
   }
@@ -222,7 +229,7 @@ export function renderDrizzleSchema(obj: MetaObject, ctx: RenderContext): Code {
     }
     const fieldDocs = renderDocsFor(child);
     const columnLine = renderColumn(
-      spec, columnNameExpr(child, spec.dbName), child, ctx, false, undefined, fkMap.get(child.name), isComposite, obj.package, obj.name, true,
+      spec, columnNameExpr(child, spec.dbName), child, ctx, false, undefined, fkMap.get(child.name), isComposite, pkg, obj.name, true,
     );
     columnLines.push(fieldDocs ? code`  ${fieldDocs}\n${columnLine}` : columnLine);
     // Enum CHECK constraints stay valid under TPH: `NULL IN (...)` is NULL
@@ -532,15 +539,38 @@ function renderColumn(
         // Composite PKs don't use .primaryKey() per-column; table callback owns it.
         pkSuffix = isComposite ? "" : ".primaryKey({ autoIncrement: true })";
       } else {
-        // Postgres: bigserial for long (8-byte), serial for int (4-byte).
-        if (field.subType === FIELD_SUBTYPE_LONG) {
-          const bigserialSym = imp(`bigserial@${spec.importModule}`);
-          baseCall = code`${bigserialSym}(${dbNameExpr}, { mode: "number" })`;
-        } else {
-          const serialSym = imp(`serial@${spec.importModule}`);
-          baseCall = code`${serialSym}(${dbNameExpr})`;
-        }
+        // Postgres: the column KEEPS the type the column-mapper derived and
+        // GAINS the identity clause. It does not get a second spelling.
+        //
+        // This used to substitute `serial`/`bigserial` for the mapped
+        // `integer`/`bigint`, and that was the 1.0 defect wearing another hat:
+        // migrate emits `… GENERATED BY DEFAULT AS IDENTITY` (emit/postgres.ts
+        // renderColumn) for the same field, and `serial` is NOT that column.
+        // `serial` is historical sugar for integer + an owned sequence + a
+        // genuine DEFAULT nextval(...); an identity column carries neither a
+        // default nor a droppable sequence. So the generated Drizzle schema
+        // misrepresented the live PK of every integer-keyed table migrate had
+        // created — one question, two doors, two answers, and nothing compared
+        // them. migrate owns the DDL (ADR-0015), so codegen is what changes —
+        // the same call #293 made when the two named a CHECK constraint
+        // differently.
+        //
+        // The clause is gated on the MAPPED column function rather than on the
+        // field subtype, so the two cannot drift apart again: only Drizzle's
+        // int family (integer/bigint/smallint, via PgIntColumnBaseBuilder)
+        // carries .generatedByDefaultAsIdentity(). A subtype outside that
+        // family with @generation:"increment" is a combination Postgres cannot
+        // express at all — migrate emits `TEXT GENERATED BY DEFAULT AS
+        // IDENTITY` and fails at apply — and the honest thing here is to leave
+        // the declared type alone and let that failure be loud, rather than
+        // silently substituting an integer column for the declared one.
         pkSuffix = isComposite ? "" : ".primaryKey()";
+        if (
+          spec.enumIntCustomType === undefined &&
+          PG_IDENTITY_CAPABLE_FNS.has(spec.fnName)
+        ) {
+          pkSuffix += ".generatedByDefaultAsIdentity()";
+        }
       }
     } else if (pkGeneration === GENERATION_UUID) {
       pkSuffix = isComposite

package/src/templates/entity-file.ts

@@ -30,6 +30,7 @@ import { namesRef, namesConstArg, physicalNameExpr, sourceSchemaExpr } from "../
 import { hasWritableRdbSource } from "../source-detect.js";
 import { renderValueObjectFile } from "./value-object-file.js";
 import { isAbstract } from "../instance-artifacts.js";
+import { effectivePackage } from "../docs-paths.js";
 
 /**
  * Render-time options for the entity-file composer.
@@ -139,14 +140,15 @@ export function renderEntityFile(
   if (writeThrough) {
     const camel = entity.name.charAt(0).toLowerCase() + entity.name.slice(1);
     const fields = entity.fields();
+    const entityPkg = effectivePackage(entity);
     // ADR-0044/#228 — resolve a view column's `@objectRef` to the value object's
     // EMITTED name + module TOGETHER (lock-step), so the read-view artifact imports
     // `AcmeAlphaNote` from `./AcmeAlphaNote.js` (not a bare `Note` → `./Note.js`)
     // under a cross-package short-name collision.
     const voRef = (field: MetaField): { name: string; module: string } => {
       const ref = field.attr(FIELD_ATTR_OBJECT_REF);
-      const name = ctx.resolveValueObjectName(typeof ref === "string" ? ref : "", fieldDeclaringPackage(field, entity.package));
-      const module = valueObjectModuleSpecifier(name, ctx.packageOf, entity.package, ctx.outputLayout, ctx.extStyle);
+      const name = ctx.resolveValueObjectName(typeof ref === "string" ? ref : "", fieldDeclaringPackage(field, entityPkg));
+      const module = valueObjectModuleSpecifier(name, ctx.packageOf, entityPkg, ctx.outputLayout, ctx.extStyle);
       return { name, module };
     };
     // ONE selection of the replica source: `projectionViewName` names it, and this is the

package/src/templates/filter-allowlist.ts

@@ -2,7 +2,6 @@ import { code, type Code } from "ts-poet";
 import { MetaField, MetaObject } from "@metaobjectsdev/metadata";
 import {
   FIELD_ATTR_FILTERABLE,
-  FIELD_ATTR_SORTABLE_DEFAULT_ORDER,
   FIELD_SUBTYPE_BOOLEAN,
   FIELD_SUBTYPE_INT,
   FIELD_SUBTYPE_LONG,
@@ -15,7 +14,7 @@ import {
   FIELD_SUBTYPE_CURRENCY,
   opsForField,
 } from "@metaobjectsdev/metadata";
-import { sortableFields } from "./filter-shared.js";
+import { sortableFields, declaredSortDefaultOrder } from "./filter-shared.js";
 import type { RenderContext } from "../render-context.js";
 
 const NUMBER_SUBTYPES = new Set<string>([
@@ -108,11 +107,15 @@ export const ${entity.name}SortAllowlist = {} as const satisfies SortAllowlist;
   }
   const rows = sortable
     .map((f) => {
-      const defaultOrder = f.attr(FIELD_ATTR_SORTABLE_DEFAULT_ORDER) as string | undefined;
+      // The DECLARED order only — an undeclared field stays `{}` so the runtime's own
+      // `?? "asc"` remains the single place the fallback is spelled. Read through the
+      // shared resolver, never off the attr here, so this allowlist and the grid tier
+      // cannot answer one declaration two ways.
+      const defaultOrder = declaredSortDefaultOrder(f);
       const rule =
-        defaultOrder === "asc" || defaultOrder === "desc"
-          ? `{ defaultOrder: ${JSON.stringify(defaultOrder)} as const }`
-          : `{}`;
+        defaultOrder === undefined
+          ? `{}`
+          : `{ defaultOrder: ${JSON.stringify(defaultOrder)} as const }`;
       return `  ${f.name}: ${rule}`;
     })
     .join(",\n");