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

package/src/generators/names-file.ts

@@ -1,8 +1,10 @@
 import type { Generator, GenContext, EmittedFile } from "../generator.js";
 import { entityOutputPath, crossEntitySpecifier } from "../import-path.js";
+import { NAMES_FILE_SUFFIX } from "../constants.js";
 import { renderNamesDecl } from "../templates/names-decl.js";
 import { namesArtifactSuperOf, resolveObjectNames } from "../names.js";
 import type { MetaObject } from "@metaobjectsdev/metadata";
+import { effectivePackage } from "../docs-paths.js";
 
 /**
  * §A1/§A2/§A6 — `<Entity>Names`: the physical database names for one object, as constants a
@@ -18,8 +20,29 @@ import type { MetaObject } from "@metaobjectsdev/metadata";
  * artifact is a MINOR under docs/compatibility-policy.md and adds zero bytes to existing
  * files, where a flag would move every $table-carrying golden for the same functionality.
  */
-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.
+   *
+   * A multi-package model is the reason this exists: one metadata tree can drive
+   * several consumers (a TypeScript data layer, a wire protocol, a JVM rail), and
+   * only some of those objects belong to the tier being generated. Without a
+   * filter, wiring this generator emitted an artifact for every persistable object
+   * in the tree — including the ones another rail owns — while every sibling
+   * generator carried `filter` and narrowed correctly.
+   *
+   * Note the abstract bases a MATCHED object extends are still emitted, filter or
+   * not: the matched object's own artifact `extends` them, so excluding them would
+   * emit an artifact whose import does not resolve.
+   */
+  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
@@ -39,13 +62,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_FILE_SUFFIX}`);
 
       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[] = [];
@@ -95,4 +118,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/generators/queries-file.ts

@@ -5,6 +5,7 @@ import { isTphSubtype } from "../templates/zod-validators.js";
 import { hasAnyRdbSource } from "../source-detect.js";
 import { formatTs } from "../format.js";
 import { entityOutputPath } from "../import-path.js";
+import { effectivePackage } from "../docs-paths.js";
 
 export interface QueriesFileOpts {
   filter?: (entity: MetaObject) => boolean;
@@ -40,7 +41,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(renderQueriesFile(entity, ctx.renderContext)),
       };
     }),

package/src/generators/render-helper-file.ts

@@ -64,7 +64,7 @@ export const renderHelper = function renderHelper(opts?: RenderHelperOpts): Gene
           // renderRenderHelper THROWS (fails codegen) on a mustache↔VO drift —
           // intentionally NOT caught: a drifted template is a build error.
           path: `${dirPrefix}${t.name}.render.ts`,
-          content: renderRenderHelper(root, t.name, provider),
+          content: renderRenderHelper(root, t.name, provider, ctx.config.extStyle ?? "js"),
         });
       }
       return files;

package/src/generators/requirements-markdown.ts

@@ -47,10 +47,37 @@ function heading(depth: number): string {
  */
 function headingLine(r: RequirementRow): string {
   const title = r.title?.replace(/\s+/g, " ").trim();
-  const label = title === undefined || title === "" ? "" : ` — ${title}`;
+  const label =
+    title === undefined || title === "" || titleRestatesLeaf(r.path, title)
+      ? ""
+      : ` — ${title}`;
   return `${heading(r.depth)} ${r.path}${label}`;
 }
 
+/**
+ * True when the title says nothing the path's LEAF SEGMENT does not already say.
+ *
+ * Measured on a hand-curated 262-entry ledger: **64 headings (24%)** read
+ * `## security — Security`, `### security.integrity — Integrity`. That is not bad
+ * authoring — `title` is chartered as "a short display label", and for a node called
+ * `integrity` the honest label IS "Integrity". The redundancy is in the RENDER, so
+ * the render is what changes.
+ *
+ * Only the LEAF is compared, never the whole path: a node `security.integrity`
+ * titled "Data Integrity" keeps its title, and one titled "Integrity" loses it. And
+ * the path always survives — dropping the path instead would break the two
+ * properties the heading is built on (it is unique by construction, so anchors
+ * cannot collide, and every sibling surface names a requirement by it).
+ *
+ * Comparison is case- and separator-insensitive so `data-integrity` / "Data
+ * Integrity" / "data integrity" all count as the same word.
+ */
+function titleRestatesLeaf(path: string, title: string): boolean {
+  const normalize = (s: string): string => s.toLowerCase().replace(/[^a-z0-9]/g, "");
+  const leaf = path.slice(path.lastIndexOf(".") + 1);
+  return normalize(leaf) === normalize(title);
+}
+
 /** The one-line fact bar: the attrs that are scannable rather than readable. */
 function facts(r: RequirementRow): string {
   const parts: string[] = [`\`${r.subType}\``];

package/src/generators/routes-file-hono.ts

@@ -6,6 +6,7 @@ import { formatTs } from "../format.js";
 import { entityOutputPath } from "../import-path.js";
 import { isTphSubtype } from "../templates/zod-validators.js";
 import { resolveExpose, type ExposeOption } from "../routes-expose.js";
+import { effectivePackage } from "../docs-paths.js";
 
 export interface RoutesFileHonoOpts {
   filter?: (entity: MetaObject) => boolean;
@@ -87,7 +88,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/generators/routes-file.ts

@@ -6,6 +6,7 @@ import { hasAnyRdbSource } from "../source-detect.js";
 import { formatTs } from "../format.js";
 import { entityOutputPath } from "../import-path.js";
 import { resolveExpose, type ExposeOption } from "../routes-expose.js";
+import { effectivePackage } from "../docs-paths.js";
 
 export interface RoutesFileOpts {
   filter?: (entity: MetaObject) => boolean;
@@ -49,7 +50,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/index.ts

@@ -8,6 +8,10 @@ export type { RunGenOpts, RunGenResult } from "./runner.js";
 
 export type { Generator, GenContext, EmittedFile, GeneratorFactory } from "./generator.js";
 export { perEntity, perPackage, perModel, oncePerRun } from "./generator.js";
+// The one aggregation of the UI-tier markers. Exported because `meta docs` is the
+// SECOND door onto `agent/ui.md` and must answer "does this run emit a UI tier?"
+// with the same function the gen runner uses, not a second derivation of it.
+export { runEmitsUiTier, runEmitsHonoRoutes, UI_TIER_GENERATOR_NAMES } from "./ui-tier-gate.js";
 
 // SP-1 declarative Mustache template-codegen — scope walks, neutral data dict,
 // output-pattern, and the JSON template-spec the CLI ports reuse.
@@ -42,7 +46,7 @@ export { defineConfig, normalizeConfig, resolveGenerators, resolveDocsConfig } f
 // The dialect every generator falls back to when a config declares none. Exported because
 // `meta docs` must apply the SAME default `normalizeConfig` does — a command that resolved
 // the dialect differently would document a schema the toolchain does not produce.
-export { DEFAULT_DIALECT } from "./metaobjects-config.js";
+export { DEFAULT_DIALECT, DEFAULT_DOCS_DIR } from "./metaobjects-config.js";
 // The runner's own "does this model need a dialect?" guard. `meta docs` must ask it rather
 // than defaulting, because DEFAULT_DIALECT is inert and a DB project with no dialect is one
 // `meta gen` REFUSES — documenting it as sqlite states an answer the toolchain never gave.
@@ -50,7 +54,7 @@ export { dbEmittingObjects, missingDialectMessage } from "./db-emitting.js";
 export { apiLabel } from "./generators/api-label.js";
 
 export type { ColumnSpec, DefaultExpr } from "./column-mapper.js";
-export { mapColumnType } from "./column-mapper.js";
+export { mapColumnType, PG_IDENTITY_CAPABLE_FNS } from "./column-mapper.js";
 
 export type { PkInfo } from "./pk-resolver.js";
 export { buildPkMap } from "./pk-resolver.js";
@@ -68,7 +72,7 @@ export type {
   BaselineMode,
   DecideAndWriteOpts,
 } from "./overwrite-policy.js";
-export { decideAndWrite, GitMissingError } from "./overwrite-policy.js";
+export { decideAndWrite, GitMissingError, WRITE_STATUSES } from "./overwrite-policy.js";
 // The committed half of `.gen-state`. Exported for `verify --codegen`, which needs
 // the same "is this still exactly what the generator wrote?" evidence the write path
 // uses — without it the gate cannot tell a preserved hand edit from stale output.
@@ -78,12 +82,17 @@ export { decideAndWrite, GitMissingError } from "./overwrite-policy.js";
 export { contentHash, readGeneratedHash, listGeneratedPaths } from "./overwrite-policy.js";
 
 export { CodegenError } from "./errors.js";
-export { GENERATED_HEADER, DEFAULT_OUT_DIR, RETIRED_CODEGEN_ATTRS, type RetiredCodegenAttr } from "./constants.js";
+export { GENERATED_HEADER, NAMES_FILE_SUFFIX, DEFAULT_OUT_DIR, RETIRED_CODEGEN_ATTRS, type RetiredCodegenAttr } from "./constants.js";
 export { warnRetiredCodegenAttrs } from "./retired-codegen-attrs.js";
 
 export { formatTs } from "./format.js";
 
-export { pluralize, columnNameFromField, tableNameFromEntity, viewNameFromProjection } from "./naming.js";
+export { pluralize, columnNameFromField, tableNameFromEntity, viewNameFromProjection, routesHandlerName } from "./naming.js";
+// routesHandlerName is public for the same reason the routes-expose members below are: the
+// routes reference template tells an adopter retargeting to another HTTP framework to copy
+// `renderRoutesFile`'s body out of the package source, and that body names this. See the
+// owned-composition-imports gate in test/ — it derives the required set from that body rather
+// than trusting this list to stay complete.
 
 export { packageToPath, entityOutputPath, crossEntitySpecifier, barrelEntrySpecifier, relativeModuleSpecifier, entityModuleSpecifier, siblingSpecifier, barrelModuleSpecifier } from "./import-path.js";
 export type { OutputLayout, ResolvedTarget } from "./import-path.js";
@@ -122,7 +131,14 @@ export { isTphSubtype, tphDiscriminatorBase, tphDiscriminatorPin } from "./templ
 // emitter, say) marks a column sortable by ASKING the server's rule rather than
 // reimplementing its three branches out of tree. A hand-copied predicate is how the
 // grid came to offer headers the allowlist rejects (#352/#354).
-export { isSortableField, sortableFields } from "./templates/filter-shared.js";
+export {
+  isSortableField,
+  sortableFields,
+  declaredSortDefaultOrder,
+  sortDefaultOrder,
+  resolveGridDefaultSort,
+} from "./templates/filter-shared.js";
+export type { SortOrder, GridDefaultSort } from "./templates/filter-shared.js";
 
 // ADR-0034 reference-template composition helpers. Promoted to the public engine
 // surface so a COPIED reference generator (src/reference/*.ts → consumer's
@@ -194,7 +210,7 @@ export { renderEntityConstants, resourcePath } from "./templates/entity-constant
 export { renderQueriesFile } from "./templates/queries-file.js";
 // #348 — which CRUD verbs a generated routes file mounts. Public because an OWNED
 // routes generator (ADR-0034) composes the same render call and needs the same option.
-export { CRUD_VERBS, resolveExpose, intersectExpose, exposeLine } from "./routes-expose.js";
+export { CRUD_VERBS, TPH_POLYMORPHIC_VERBS, resolveExpose, intersectExpose, exposeLine } from "./routes-expose.js";
 export type { CrudVerb, ExposeOption } from "./routes-expose.js";
 export { renderRoutesFile } from "./templates/routes-file.js";
 export { renderRoutesFileHono } from "./templates/routes-file-hono.js";

package/src/metaobjects-config.ts

@@ -63,6 +63,11 @@ export interface ResolvedGenConfig {
    *  Undefined ⇒ false. Templates read the same fact off `RenderContext.includeNames`,
    *  which the runner sets from this same aggregation. */
   includeNames?: boolean;
+  /** Whether any CLIENT UI generator (form, hook, grid, columns) is active in the
+   *  run — aggregated by the runner from the suite's `emitsUiTier` markers.
+   *  `agent/ui.md` reads this to decide whether a UI tier exists to describe;
+   *  a metadata predicate can only say a UI *could* be generated. Undefined ⇒ false. */
+  includeUiTier?: boolean;
   /**
    * FR-019 / ADR-0026: the module specifier from which an externally-PROVIDED
    * shared enum (`@provided: true` on an abstract package-level `field.enum`) is
@@ -289,13 +294,27 @@ export interface ResolvedDocsConfig {
 /** Merge the config `docs:` block with CLI overrides over documented defaults.
  *  `fallbackLayout` is the project's `outputLayout` so docs default to the same
  *  page placement as codegen when `docs.layout` is unset. */
+/**
+ * Where `meta docs` writes when nothing says otherwise. A SUB-directory on purpose: the
+ * generated pages are MetaObjects' to own and overwrite, and `docs/` as a whole is not.
+ */
+export const DEFAULT_DOCS_DIR = "./docs/generated";
+
 export function resolveDocsConfig(
   block: DocsConfig | undefined,
   cli: Partial<ResolvedDocsConfig>,
   fallbackLayout: OutputLayout,
 ): ResolvedDocsConfig {
   return {
-    outDir: cli.outDir ?? block?.outDir ?? "./docs",
+    // F57 — NOT "./docs". `docs/` is the human documentation folder in most repos: one
+    // estate's held a business-strategy .docx, product screenshots, email drafts and an
+    // analytics roadmap, and a bare `meta docs` scattered 29 generated pages through it
+    // and wanted to own `docs/README.md`. The gate's own design language is right —
+    // "docs.outDir is a directory, not a namespace MetaObjects owns" — and that is
+    // precisely the argument for not defaulting into the most-owned directory name in
+    // the ecosystem. `meta init` scaffolds this key explicitly so a new project's choice
+    // is visible rather than implied.
+    outDir: cli.outDir ?? block?.outDir ?? DEFAULT_DOCS_DIR,
     layout: cli.layout ?? block?.layout ?? fallbackLayout,
     baseUrl: cli.baseUrl ?? block?.baseUrl ?? "",
     // `requirements` defaults ON. Safe ONLY because requirementsFile() emits ZERO

package/src/names.ts

@@ -26,6 +26,7 @@ import {
 import { code, imp, type Code } from "ts-poet";
 import { crossEntitySpecifier } from "./import-path.js";
 import type { RenderContext } from "./render-context.js";
+import { effectivePackage } from "./docs-paths.js";
 
 export interface FieldNames { readonly name: string; readonly column: string; }
 
@@ -335,7 +336,7 @@ export function resolveObjectNames(
   const superObj = namesArtifactSuperOf(obj);
   const superNames: SuperNames | undefined = superObj === undefined
     ? undefined
-    : { name: superObj.name, package: superObj.package };
+    : { name: superObj.name, package: effectivePackage(superObj) };
   // Identity of the resolved source NODE, not equality of the resolved strings: a
   // divergence guard is exactly what this codebase forbids here, and the question being
   // asked is structural — did this object declare a source, or is it using its parent's?
@@ -438,7 +439,7 @@ export function resolveSuperFragmentNames(
     ownIndexes: keysOf(obj.ownLookupIndexes()),
     superNames: superObj === undefined
       ? undefined
-      : { name: superObj.name, package: superObj.package },
+      : { name: superObj.name, package: effectivePackage(superObj) },
     inheritsSource: false,
   };
 }
@@ -466,7 +467,7 @@ export function resolveSuperFragmentNames(
 export function namesRef(
   obj: MetaObject,
   ctx: RenderContext,
-  fromPackage: string | undefined = obj.package,
+  fromPackage: string | undefined = effectivePackage(obj),
 ): { readonly resolved: ObjectNames; readonly symbol: Code } | undefined {
   if (!ctx.includeNames) return undefined;
   const resolved = resolveObjectNames(obj, ctx.columnNamingStrategy);
@@ -475,7 +476,7 @@ export function namesRef(
     `${obj.name}Names@${crossEntitySpecifier(
       ctx.selfTarget.outputLayout,
       fromPackage,
-      obj.package,
+      effectivePackage(obj),
       `${obj.name}.names`,
       ctx.extStyle,
     )}`,

package/src/overwrite-policy.ts

@@ -45,20 +45,36 @@ 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",
+  /** `--baseline=adopt` — the file WOULD have been refused, and instead its current
+   *  content was recorded as the merge base. Nothing was written. Its own status
+   *  rather than "unchanged" or "skipped" because the run's whole product is the
+   *  manifest it just created: a summary that reported these as unchanged would
+   *  hide the one thing the adopter has to commit. */
+  "adopted",
   /** 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-
@@ -71,8 +87,20 @@ export type MergeStrategy = "overwrite" | "skip-existing";
 /** "default" — the standard three-way merge flow described in the file header.
  *  "fresh" — opt-in via `meta gen --baseline=fresh`. When .gen-state is absent
  *  but the file exists, OVERWRITE with fresh content and seed .gen-state from
- *  the fresh content (caveat 3 escape hatch). */
-export type BaselineMode = "default" | "fresh";
+ *  the fresh content (caveat 3 escape hatch).
+ *  "adopt" — opt-in via `meta gen --baseline=adopt`. Same population, opposite
+ *  half: where the run would REFUSE, record the file's CURRENT content as the
+ *  merge base and write nothing. It exists because the refusal's leading remedy
+ *  ("commit .hashes.json") could not be performed by the population it named —
+ *  nothing writes a manifest until a gen succeeds, and gen refuses until one
+ *  exists. `adopt` is the run that produces the file to commit.
+ *
+ *  What it is NOT: protection for an edit already inside one of those files. The
+ *  base becomes the edited text, so base == ours and the next regen's three-way
+ *  merge takes fresh output wholesale. It protects edits made FROM THEN ON, and
+ *  it guarantees that establishing the baseline writes nothing — which is what
+ *  lets the content change land as its own reviewable diff afterwards. */
+export type BaselineMode = "default" | "fresh" | "adopt";
 
 export interface DecideAndWriteOpts {
   strategy?: MergeStrategy;
@@ -458,6 +486,7 @@ type WriteCase =
   | { kind: "no-snapshot-unchanged" }
   | { kind: "no-snapshot-pristine-overwrite" }
   | { kind: "no-snapshot-refused"; hasRecord: boolean }
+  | { kind: "no-snapshot-adopt"; currentText: string }
   | { kind: "snapshot-unchanged" }
   | { kind: "snapshot-merge-required"; snapshotText: string };
 
@@ -511,6 +540,18 @@ function classifyWrite(
 
     // Either somebody edited it (hash mismatch) or we have no record of writing
     // it at all (no hash). Both are unprovable, so fail closed.
+    //
+    // …unless the caller has explicitly adopted what is on disk. `adopt` is placed
+    // HERE, at the refusal, rather than at the top of the no-snapshot branch, and
+    // that placement is the design: it means adopting can only ever convert a
+    // refusal into a recorded baseline. Everything else — unchanged, and the
+    // pristine-file overwrite a fresh clone depends on — keeps behaving exactly as
+    // it does without the flag, so a project cannot accidentally freeze its
+    // regeneration by passing it.
+    if ((opts.baseline ?? "default") === "adopt") {
+      return { kind: "no-snapshot-adopt", currentText: current };
+    }
+
     return {
       kind: "no-snapshot-refused",
       hasRecord: readGeneratedHash(genStateDir, relPath) !== undefined,
@@ -560,6 +601,8 @@ export function previewWriteStatus(
       return "overwrite";
     case "no-snapshot-refused":
       return "refused";
+    case "no-snapshot-adopt":
+      return "adopted";
     case "snapshot-merge-required":
       return "overwrite";
   }
@@ -631,6 +674,14 @@ export function decideAndWrite(
             "--baseline=fresh to overwrite it and adopt fresh output as the baseline.",
       };
 
+    case "no-snapshot-adopt":
+      // Record what is ON DISK — deliberately `kase.currentText`, never `content`.
+      // Recording fresh output would claim we wrote a file we did not, and the next
+      // run would then read the adopter's file as edited-since-generated and refuse
+      // all over again, which is the loop this mode exists to end.
+      advanceSnapshot(genStateDir, relPath, kase.currentText);
+      return { path, status: "adopted" };
+
     case "snapshot-unchanged":
       return { path, status: "unchanged" };
 

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

@@ -36,14 +36,30 @@ import {
   namesArtifactSuperOf,
   renderNamesDecl,
   resolveObjectNames,
+  NAMES_FILE_SUFFIX,
   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 +79,16 @@ 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`);
+        // NAMES_FILE_SUFFIX, not a literal: `meta verify --codegen` treats this artifact as
+        // fail-closed (a hand edit in it IS drift, unlike every other generated file) and
+        // recognises it BY THIS SUFFIX. Rename it and you opt out of that protection.
+        entityOutputPath(layout, effectivePackage(obj), `${obj.name}${NAMES_FILE_SUFFIX}`);
 
       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 +141,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))),
       };
     }),