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

package/src/runner.ts

@@ -1,5 +1,6 @@
 import { join, relative, resolve, isAbsolute, dirname } from "node:path";
 import { warnMissingPromptGenerators } from "./prompt-generator-gate.js";
+import { runEmitsHonoRoutes, runEmitsUiTier, warnUnmarkedUiGenerators } from "./ui-tier-gate.js";
 import { warnRetiredCodegenAttrs } from "./retired-codegen-attrs.js";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -19,6 +20,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 +142,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 +182,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,13 +464,26 @@ 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,
   // surface it on every generator's ctx.config so api-docs documents the Hono
   // CRUD surface it actually emits (rather than silently omitting it).
-  const includeHonoRoutes = config.generators.some((g) => g.emitsHonoRoutes === true);
+  // The explicit config key WINS over the marker aggregation, at both doors. `meta docs`
+  // already read `loadedConfig?.includeHonoRoutes ?? …`, and the runner did not — so an
+  // adopter who set the key got the surface documented and not emitted, or the reverse.
+  // The key is settable because `MetaobjectsGenConfig extends Omit<ResolvedGenConfig,…>`,
+  // and it is the escape hatch for an owned generator whose name was changed; an escape
+  // hatch honoured by one of two doors is the defect these flags exist to close.
+  const includeHonoRoutes = config.includeHonoRoutes ?? runEmitsHonoRoutes(config.generators);
+
+  // Same auto-detection for the CLIENT UI tier. `agent/ui.md` describes forms, grids
+  // and the endpoints their hooks call; whether any of that is emitted is a generator
+  // fact, and the page's own gate could only see metadata. Run-scoped like
+  // includeHonoRoutes — the page asks "is this surface in the run?", never "does it
+  // land in my target?".
+  const includeUiTier = config.includeUiTier ?? runEmitsUiTier(config.generators);
 
   // §A6 — same auto-detection for the OPT-IN names generator. The entity tier may only
   // REFERENCE `<Entity>Names` when something in this run actually emits it; the names
@@ -441,6 +507,30 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   // this, said nothing — while `meta verify` reported the template "clean". See
   // prompt-generator-gate.ts. Self-extinguishing; warning only.
   warnMissingPromptGenerators(root, config.generators, (m) => warnings.push(m));
+  warnUnmarkedUiGenerators(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
@@ -455,6 +545,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
@@ -519,6 +613,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
         outputLayout: selfTarget.outputLayout,
         includeHonoRoutes,
         includeNames: namesTargets.has(selfTarget.name),
+        includeUiTier,
       },
       renderContext,
       ...(projectRoot !== undefined && { projectRoot }),
@@ -547,6 +642,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 +685,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[] = [];
@@ -614,10 +735,15 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
         `no codegen hash manifest — so 'meta gen' cannot tell your edits from its own ` +
         `stale output, and it will not guess. This is the expected first run for a ` +
         `project created before the manifest was committed. ` +
-        `ONE-TIME FIX: commit '.metaobjects/.gen-state/.hashes.json' (un-ignore it in ` +
-        `.metaobjects/.gitignore with '.gen-state/*' + '!.gen-state/.hashes.json'), ` +
-        `then re-run. To adopt fresh output and DISCARD any hand edits in these files ` +
-        `instead, re-run with --baseline=fresh. Files: ${names.join(", ")}${more}.`,
+        `ONE-TIME FIX: re-run with --baseline=adopt — it records the files you have as ` +
+        `the merge base and writes NOTHING — then commit ` +
+        `'.metaobjects/.gen-state/.hashes.json' (un-ignore it in .metaobjects/.gitignore ` +
+        `with '.gen-state/*' + '!.gen-state/.hashes.json') and run 'meta gen' again, where ` +
+        `the regeneration arrives as its own reviewable diff. Adopting DECLARES these files ` +
+        `to be generated output, so an edit already inside one of them is part of the ` +
+        `baseline and that regeneration will replace it — commit before you run it. ` +
+        `To write fresh output NOW and DISCARD any hand edits in these files, ` +
+        `--baseline=fresh does both in one step. Files: ${names.join(", ")}${more}.`,
       );
       return;
     }
@@ -657,6 +783,28 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
     );
   };
 
+  // `--baseline=adopt` — the counterpart of the aggregate above, and aggregated for the
+  // same reason: every adopted file has one cause and one next step. Reported even though
+  // nothing failed, because a run that writes nothing and exits 0 is otherwise
+  // indistinguishable from a no-op, and the file it DID produce (`.hashes.json`) is the
+  // one the adopter now has to commit.
+  const reportAdoptions = (): void => {
+    const adopted = writes.filter((w) => w.status === "adopted");
+    if (adopted.length === 0) return;
+    const names = adopted.slice(0, MAX_NAMED).map((w) => relativeForDisplay(w.path));
+    const more = adopted.length > MAX_NAMED ? `, and ${adopted.length - MAX_NAMED} more` : "";
+    warnings.push(
+      `Recorded ${adopted.length} existing file(s) as the codegen baseline and wrote ` +
+      `nothing. NEXT: commit '.metaobjects/.gen-state/.hashes.json' (un-ignore it in ` +
+      `.metaobjects/.gitignore with '.gen-state/*' + '!.gen-state/.hashes.json'), then run ` +
+      `'meta gen' — these files regenerate normally from here, as their own reviewable ` +
+      `diff. Adopting DECLARED them to be generated output: an edit already inside one is ` +
+      `part of the baseline and that regeneration will replace it, so check the diff ` +
+      `against git. Edits you make FROM NOW ON merge, because the base now exists. ` +
+      `Files: ${names.join(", ")}${more}.`,
+    );
+  };
+
   const sweep = (dryRun: boolean): void => {
     if (projectRoot === undefined || orphanJobs.length === 0) return;
 
@@ -758,6 +906,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
       });
     }
     reportRefusals();
+    reportAdoptions();
     // A preview that hides a pending deletion is worse than no preview at all, so
     // the sweep still runs — in decide-and-report mode, touching nothing.
     sweep(true);
@@ -791,6 +940,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   }
 
   reportRefusals();
+  reportAdoptions();
 
   // Sweep AFTER the writes: writing is the primary job, and a deletion that runs
   // first would be unrecoverable if a later write threw. Ordering cannot change

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");

package/src/templates/filter-shared.ts

@@ -1,10 +1,31 @@
-// Shared predicate for "is this field sortable?" — used by both filter-allowlist.ts
-// (SortAllowlist generation) and filter-type.ts (sort union generation).
-// Both must agree on which fields are sortable; keeping them in sync via this shared
-// helper prevents client/server mismatches.
+// Shared answers to "how does this entity sort?" — used by every tier that has to
+// answer it, so none of them can answer it differently.
+//
+// Two questions live here:
+//   WHICH fields sort   — isSortableField / sortableFields, read by the generated
+//                         <Entity>SortAllowlist (filter-allowlist.ts), the client
+//                         <Entity>Filter sort union (filter-type.ts) and the agent
+//                         UI page.
+//   WHICH WAY one sorts — declaredSortDefaultOrder / sortDefaultOrder /
+//                         resolveGridDefaultSort, read by the same allowlist, the
+//                         generated grid const + grid hook, and the agent UI page.
+//
+// Keeping both here is what prevents a client/server mismatch: a header the grid
+// renders clickable for a field the endpoint rejects, or a grid whose initial sort
+// runs the opposite way from the endpoint it queries.
 
-import { MetaField, MetaObject } from "@metaobjectsdev/metadata";
-import { FIELD_ATTR_FILTERABLE, FIELD_ATTR_SORTABLE } from "@metaobjectsdev/metadata";
+import { MetaField, MetaObject, type MetaData } from "@metaobjectsdev/metadata";
+import {
+  FIELD_ATTR_FILTERABLE,
+  FIELD_ATTR_SORTABLE,
+  FIELD_ATTR_SORTABLE_DEFAULT_ORDER,
+  LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_FIELD,
+  LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_ORDER,
+} from "@metaobjectsdev/metadata";
+
+/** A resolved sort direction. Never widened to `string`: every door below either
+ *  returns one of these two or says it has no answer. */
+export type SortOrder = "asc" | "desc";
 
 /**
  * Returns true if the given field should be included in sort operations.
@@ -28,3 +49,67 @@ export function sortableFields(entity: MetaObject): MetaField[] {
   // fields() returns effective fields, so inherited fields (from extends:/super:) are included in sort ops.
   return entity.fields().filter(isSortableField);
 }
+
+/**
+ * The direction `@sortableDefaultOrder` DECLARES on this field, or undefined when
+ * the field declares none.
+ *
+ * The declared value is what the generated `<Entity>SortAllowlist` carries, so an
+ * undeclared field stays `{}` there and the runtime's own `?? "asc"` remains the
+ * single place the fallback is spelled. Callers that need a concrete direction
+ * rather than a declaration use `sortDefaultOrder`.
+ *
+ * ADR-0039: resolving — `@sortableDefaultOrder` may be inherited via `extends`.
+ */
+export function declaredSortDefaultOrder(field: MetaField): SortOrder | undefined {
+  const v = field.attr(FIELD_ATTR_SORTABLE_DEFAULT_ORDER);
+  return v === "asc" || v === "desc" ? v : undefined;
+}
+
+/** The direction a sort runs when it names this field without giving one. */
+export function sortDefaultOrder(field: MetaField): SortOrder {
+  return declaredSortDefaultOrder(field) ?? "asc";
+}
+
+/** A grid's initial sort: the field it runs on and the direction it runs. */
+export interface GridDefaultSort {
+  field: string;
+  order: SortOrder;
+}
+
+/**
+ * A `layout.dataGrid`'s initial sort, resolved once for every tier that renders it.
+ *
+ * `@defaultSortOrder` wins when the layout declares one. When it does not, the
+ * NAMED FIELD's `@sortableDefaultOrder` applies — that is what the attribute has
+ * always been registered to mean ("the direction a sort takes when it names this
+ * field but omits the order"), and it is the same rule the runtime applies to
+ * `?sort=<field>` with no `:order`. Without this the two ends of one declaration
+ * disagree: the endpoint returns the field's declared order while the grid that
+ * queries it renders the opposite.
+ *
+ * Returns undefined when the layout names no field — a grid with no initial sort.
+ *
+ * The field lookup cannot miss on a LOADED model: `validateDataGridSortFields`
+ * refuses `@defaultSortField` naming a field the entity does not have
+ * (`ERR_BAD_DEFAULT_SORT_FIELD`). "asc" is the answer for a hand-built node that
+ * never went through the loader, so codegen degrades rather than throwing.
+ */
+// `layout` is typed as the base MetaData rather than MetaLayout because the three
+// call sites hold the node at different static types (`entity.layouts()` gives
+// MetaLayout, the agent page's own `dataGrids()` gives MetaData) and this reads
+// nothing but `attr()`, which is declared there. Widening beats a cast per caller.
+export function resolveGridDefaultSort(
+  entity: MetaObject,
+  layout: MetaData,
+): GridDefaultSort | undefined {
+  // ADR-0039: resolving — a layout may inherit its grid attrs via extends.
+  const fieldName = layout.attr(LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_FIELD);
+  if (typeof fieldName !== "string" || fieldName === "") return undefined;
+
+  const declared = layout.attr(LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_ORDER);
+  if (declared === "asc" || declared === "desc") return { field: fieldName, order: declared };
+
+  const field = entity.fields().find((f) => f.name === fieldName);
+  return { field: fieldName, order: field === undefined ? "asc" : sortDefaultOrder(field) };
+}

package/src/templates/inferred-types.ts

@@ -42,6 +42,7 @@ import { renderDocsFor } from "./jsdoc.js";
 import { sharedEnumForField } from "../enum-shared.js";
 import { sharedEnumImportSpecifier, providedEnumImportSpecifier } from "../enum-import.js";
 import { fieldDeclaringPackage, type RenderContext } from "../render-context.js";
+import { effectivePackage } from "../docs-paths.js";
 
 /**
  * Emit Drizzle's InferSelectModel / InferInsertModel aliases for an entity.
@@ -179,7 +180,7 @@ export function renderEnumTypeAliases(entity: MetaObject, ctx?: RenderContext):
     // configured external module; never redeclare the union here.
     const spec = shared.provided
       ? providedEnumImportSpecifier(ctx!, shared.name)
-      : sharedEnumImportSpecifier(ctx!, entity.package);
+      : sharedEnumImportSpecifier(ctx!, effectivePackage(entity));
     // Re-export the runtime constant beside the type for a MATERIALIZED shared enum, so a
     // consumer reaches its members the same way it reaches an inline enum's, without having
     // to know which kind it is or which module the shared one landed in.
@@ -305,9 +306,10 @@ function valueObjectFieldType(entity: MetaObject, field: MetaField, ctx?: Render
       // layout/package/extStyle-aware helper (the SAME one the Zod schema +
       // Drizzle .$type<> use) so all three agree. Without a ctx (bare unit-test
       // calls) fall back to the bare name + flat same-dir specifier.
-      const refName = ctx ? ctx.resolveValueObjectName(ref, fieldDeclaringPackage(field, entity.package)) : stripPackage(ref);
+      const entityPkg = effectivePackage(entity);
+      const refName = ctx ? ctx.resolveValueObjectName(ref, fieldDeclaringPackage(field, entityPkg)) : stripPackage(ref);
       const moduleSpec = ctx
-        ? valueObjectModuleSpecifier(refName, ctx.packageOf, entity.package, ctx.outputLayout, ctx.extStyle)
+        ? valueObjectModuleSpecifier(refName, ctx.packageOf, entityPkg, ctx.outputLayout, ctx.extStyle)
         : `./${refName}.js`;
       const refImp = imp(`${refName}@${moduleSpec}`);
       return field.resolvedIsArray() ? code`${refImp}[]` : code`${refImp}`;
@@ -319,9 +321,10 @@ function valueObjectFieldType(entity: MetaObject, field: MetaField, ctx?: Render
   if (field.subType === FIELD_SUBTYPE_MAP) {
     const ref = field.attr(FIELD_ATTR_OBJECT_REF);
     if (typeof ref === "string" && ref.length > 0) {
-      const refName = ctx ? ctx.resolveValueObjectName(ref, fieldDeclaringPackage(field, entity.package)) : stripPackage(ref);
+      const entityPkg = effectivePackage(entity);
+      const refName = ctx ? ctx.resolveValueObjectName(ref, fieldDeclaringPackage(field, entityPkg)) : stripPackage(ref);
       const moduleSpec = ctx
-        ? valueObjectModuleSpecifier(refName, ctx.packageOf, entity.package, ctx.outputLayout, ctx.extStyle)
+        ? valueObjectModuleSpecifier(refName, ctx.packageOf, entityPkg, ctx.outputLayout, ctx.extStyle)
         : `./${refName}.js`;
       const refImp = imp(`${refName}@${moduleSpec}`);
       return code`Record<string, ${refImp}>`;
@@ -349,7 +352,7 @@ function valueObjectFieldType(entity: MetaObject, field: MetaField, ctx?: Render
         if (shared !== undefined) {
           const spec = shared.provided
             ? providedEnumImportSpecifier(ctx, shared.name)
-            : sharedEnumImportSpecifier(ctx, entity.package);
+            : sharedEnumImportSpecifier(ctx, effectivePackage(entity));
           const sym = imp(`t:${shared.name}@${spec}`);
           return field.resolvedIsArray() ? code`${sym}[]` : code`${sym}`;
         }

package/src/templates/projection-decl.ts

@@ -23,6 +23,7 @@ import { renderFilterType } from "./filter-type.js";
 import { buildUiFieldDescriptor, resourcePath } from "./entity-ui-descriptor.js";
 import { renderExistingViewDecl, renderViewReadZodObject } from "./view-decl.js";
 import { primaryIdentityFieldNames } from "./zod-validators.js";
+import { effectivePackage } from "../docs-paths.js";
 
 // ---------------------------------------------------------------------------
 // Public interface
@@ -103,14 +104,15 @@ export function renderProjectionDecl(
   // package-qualified on a cross-package short-name collision, so the projection's
   // VO import matches the entity's. Layout/package/extStyle-aware when a render
   // context is present, else a flat same-dir import (zodFieldExpr's fallback).
+  const projectionPkg = effectivePackage(projection);
   const voRef = (field: MetaField): { name: string; module: string } => {
     const ref = field.attr(FIELD_ATTR_OBJECT_REF);
     const rawRef = typeof ref === "string" ? ref : "";
     const name = ctx
-      ? ctx.resolveValueObjectName(rawRef, fieldDeclaringPackage(field, projection.package))
+      ? ctx.resolveValueObjectName(rawRef, fieldDeclaringPackage(field, projectionPkg))
       : stripPackage(rawRef);
     const module = ctx
-      ? valueObjectModuleSpecifier(name, ctx.packageOf, projection.package, ctx.outputLayout, ctx.extStyle)
+      ? valueObjectModuleSpecifier(name, ctx.packageOf, projectionPkg, ctx.outputLayout, ctx.extStyle)
       : `./${name}.js`;
     return { name, module };
   };