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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/codegen-ts",
-  "version": "0.9.0",
+  "version": "0.11.0-rc.1",
   "description": "TypeScript codegen engine for MetaObjects — emits Drizzle, Zod, and Fastify artifacts.",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,9 +20,70 @@
       "bun": "./src/templates/zod-validators.ts",
       "types": "./dist/templates/zod-validators.d.ts",
       "default": "./dist/templates/zod-validators.js"
+    },
+    "./templates/entity-file": {
+      "bun": "./src/templates/entity-file.ts",
+      "types": "./dist/templates/entity-file.d.ts",
+      "default": "./dist/templates/entity-file.js"
+    },
+    "./templates/drizzle-schema": {
+      "bun": "./src/templates/drizzle-schema.ts",
+      "types": "./dist/templates/drizzle-schema.d.ts",
+      "default": "./dist/templates/drizzle-schema.js"
+    },
+    "./templates/inferred-types": {
+      "bun": "./src/templates/inferred-types.ts",
+      "types": "./dist/templates/inferred-types.d.ts",
+      "default": "./dist/templates/inferred-types.js"
+    },
+    "./templates/barrel": {
+      "bun": "./src/templates/barrel.ts",
+      "types": "./dist/templates/barrel.d.ts",
+      "default": "./dist/templates/barrel.js"
+    },
+    "./templates/filter-type": {
+      "bun": "./src/templates/filter-type.ts",
+      "types": "./dist/templates/filter-type.d.ts",
+      "default": "./dist/templates/filter-type.js"
+    },
+    "./templates/filter-allowlist": {
+      "bun": "./src/templates/filter-allowlist.ts",
+      "types": "./dist/templates/filter-allowlist.d.ts",
+      "default": "./dist/templates/filter-allowlist.js"
+    },
+    "./templates/entity-constants": {
+      "bun": "./src/templates/entity-constants.ts",
+      "types": "./dist/templates/entity-constants.d.ts",
+      "default": "./dist/templates/entity-constants.js"
+    },
+    "./templates/queries-file": {
+      "bun": "./src/templates/queries-file.ts",
+      "types": "./dist/templates/queries-file.d.ts",
+      "default": "./dist/templates/queries-file.js"
+    },
+    "./templates/routes-file": {
+      "bun": "./src/templates/routes-file.ts",
+      "types": "./dist/templates/routes-file.d.ts",
+      "default": "./dist/templates/routes-file.js"
+    },
+    "./templates/value-object-file": {
+      "bun": "./src/templates/value-object-file.ts",
+      "types": "./dist/templates/value-object-file.d.ts",
+      "default": "./dist/templates/value-object-file.js"
+    },
+    "./templates/projection-decl": {
+      "bun": "./src/templates/projection-decl.ts",
+      "types": "./dist/templates/projection-decl.d.ts",
+      "default": "./dist/templates/projection-decl.js"
     }
   },
-  "files": ["dist", "src", "templates", "README.md", "LICENSE"],
+  "files": [
+    "dist",
+    "src",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
     "build": "tsc -p .",
     "typecheck": "tsc -p tsconfig.typecheck.json"
@@ -31,36 +92,44 @@
   "author": "Doug Mealing <doug@dougmealing.com>",
   "homepage": "https://metaobjects.dev",
   "bugs": {
-  "url": "https://github.com/metaobjectsdev/metaobjects/issues"
-},
-"repository": {
-  "type": "git",
-  "url": "https://github.com/metaobjectsdev/metaobjects.git",
-  "directory": "server/typescript/packages/codegen-ts"
-},
-"keywords": ["metaobjects", "codegen", "drizzle", "zod", "fastify", "typescript"],
-"publishConfig": {
-"access": "public"
-},
-"dependencies": {
-  "@metaobjectsdev/metadata": "0.9.0",
-  "@metaobjectsdev/render": "0.9.0",
-  "@biomejs/js-api": "^0.7.0",
-  "@biomejs/wasm-nodejs": "^1.9.4",
-  "ts-poet": "^6.10.0"
-},
-"peerDependencies": {
-  "drizzle-orm": ">=0.36.0",
-  "zod": ">=3.23.0"
-},
-"devDependencies": {
-  "@biomejs/biome": "^1.9.0",
-  "@metaobjectsdev/codegen-ts-react": "0.9.0",
-  "@metaobjectsdev/runtime-ts": "0.9.0",
-  "bun-types": "latest",
-  "drizzle-orm": "^0.36.0",
-  "hono": "^4.6.0",
-  "typescript": "^5.6.0",
-  "zod": "^3.23.0"
-}
+    "url": "https://github.com/metaobjectsdev/metaobjects/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/metaobjectsdev/metaobjects.git",
+    "directory": "server/typescript/packages/codegen-ts"
+  },
+  "keywords": [
+    "metaobjects",
+    "codegen",
+    "drizzle",
+    "zod",
+    "fastify",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@metaobjectsdev/metadata": "0.11.0-rc.1",
+    "@metaobjectsdev/render": "0.11.0-rc.1",
+    "@biomejs/js-api": "^0.7.0",
+    "@biomejs/wasm-nodejs": "^1.9.4",
+    "ts-poet": "^6.10.0"
+  },
+  "peerDependencies": {
+    "drizzle-orm": ">=0.36.0",
+    "zod": ">=3.23.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "@metaobjectsdev/codegen-ts-react": "0.11.0-rc.1",
+    "@metaobjectsdev/migrate-ts": "0.11.0-rc.1",
+    "@metaobjectsdev/runtime-ts": "0.11.0-rc.1",
+    "bun-types": "latest",
+    "drizzle-orm": "^0.36.0",
+    "hono": "^4.6.0",
+    "typescript": "^5.6.0",
+    "zod": "^3.23.0"
+  }
 }

package/src/column-mapper.ts

@@ -15,7 +15,6 @@ import {
   FIELD_SUBTYPE_TIME,
   FIELD_SUBTYPE_TIMESTAMP,
   FIELD_SUBTYPE_OBJECT,
-  FIELD_SUBTYPE_CLASS,
   FIELD_SUBTYPE_ENUM,
   FIELD_SUBTYPE_UUID,
   VALIDATOR_SUBTYPE_REQUIRED,
@@ -27,6 +26,8 @@ import {
   FIELD_ATTR_UNIQUE,
   FIELD_ATTR_DEFAULT,
   FIELD_ATTR_OBJECT_REF,
+  FIELD_ATTR_STORAGE,
+  STORAGE_JSONB,
   VALIDATOR_ATTR_MAX,
   FIELD_ATTR_DB_COLUMN_TYPE,
   DB_COLUMN_TYPE_UUID,
@@ -35,7 +36,7 @@ import {
 } from "@metaobjectsdev/metadata";
 import { columnNameFromField } from "./naming.js";
 import { enumValues } from "./enum-meta.js";
-import { DEFAULT_COLUMN_NAMING_STRATEGY } from "@metaobjectsdev/metadata";
+import { DEFAULT_COLUMN_NAMING_STRATEGY, stripPackage } from "@metaobjectsdev/metadata";
 import type { Dialect, ColumnNamingStrategy } from "./metaobjects-config.js";
 
 export type { Dialect };
@@ -82,7 +83,6 @@ function sqliteJsonArrayElementTsType(subType: string): string | undefined {
   switch (subType) {
     case FIELD_SUBTYPE_STRING:
     case FIELD_SUBTYPE_ENUM:
-    case FIELD_SUBTYPE_CLASS:
     case FIELD_SUBTYPE_UUID:
     case FIELD_SUBTYPE_DATE:
     case FIELD_SUBTYPE_TIME:
@@ -134,15 +134,20 @@ export interface ColumnSpec {
   checkConstraint?: string;
   /**
    * Optional `.$type<...>()` chain target. Renderer (drizzle-schema.ts) emits
-   * `.$type<TS[]>()` ahead of the modifiers chain, using ts-poet `imp()` for
-   * objectRef variants so the cross-module type import auto-hoists.
+   * it ahead of the modifiers chain, using ts-poet `imp()` for objectRef
+   * variants so the cross-module type import auto-hoists. `array` controls the
+   * `[]` suffix: a single value (`VO`) vs a collection (`VO[]`).
    * `kind: "scalar"` covers string[]/number[]/boolean[] — no import needed.
-   * `kind: "objectRef"` covers SourceLens[]/Dissent[]/etc. — `module` is the
-   * relative import path to that entity's emitted module.
+   * `kind: "objectRef"` covers SourceLens/Dissent/etc. — only the bare VO `name`
+   * is carried; the renderer resolves the import MODULE via the shared
+   * `valueObjectModuleSpecifier` (layout/package/extStyle-aware, identical to the
+   * field's TS type + Zod schema). A single Postgres jsonb object column
+   * (`array: false`) gets `.$type<VO>()`; an array of VOs held in one jsonb
+   * column gets `.$type<VO[]>()`.
    */
   dollarTypeRef?:
-    | { kind: "scalar"; tsType: "string" | "number" | "boolean" }
-    | { kind: "objectRef"; name: string; module: string };
+    | { kind: "scalar"; tsType: "string" | "number" | "boolean"; array: boolean }
+    | { kind: "objectRef"; name: string; array: boolean };
 }
 
 /**
@@ -163,8 +168,9 @@ export interface ColumnSpec {
  */
 function pgColumnTypeOverride(
   field: MetaField,
+  timestampMode: "date" | "string" = "string",
 ): { fnName: string; fnOptions?: Record<string, unknown> } | undefined {
-  const dbColumnType = field.ownAttr(FIELD_ATTR_DB_COLUMN_TYPE);
+  const dbColumnType = field.attr(FIELD_ATTR_DB_COLUMN_TYPE);
   if (typeof dbColumnType !== "string") return undefined;
   switch (dbColumnType) {
     case DB_COLUMN_TYPE_UUID:
@@ -173,9 +179,10 @@ function pgColumnTypeOverride(
       return { fnName: "jsonb" };
     case DB_COLUMN_TYPE_TIMESTAMP_WITH_TZ:
       // Drizzle pg-core: timestamp(col, { withTimezone: true }) → timestamptz.
-      // mode:"string" for the same reason as the plain-timestamp branch — the
-      // schema + wire contract carry timestamps as strings.
-      return { fnName: "timestamp", fnOptions: { mode: "string", withTimezone: true } };
+      // mode defaults to "string" (ISO-8601 wire contract, matching the generated
+      // Zod); a consumer can opt into "date" (drizzle's native mode) via
+      // codegen.timestampMode when its hand-written code works with JS Dates.
+      return { fnName: "timestamp", fnOptions: { mode: timestampMode, withTimezone: true } };
     default:
       return undefined;
   }
@@ -184,7 +191,7 @@ function pgColumnTypeOverride(
 /** Resolve max length from validator.length child or @maxLength attr.
  *  Uses field.validators() (effective) so inherited validators are seen. */
 function getMaxLength(field: MetaField): number | undefined {
-  const lenAttr = field.ownAttr(FIELD_ATTR_MAX_LENGTH);
+  const lenAttr = field.attr(FIELD_ATTR_MAX_LENGTH);
   if (typeof lenAttr === "number") return lenAttr;
   for (const child of field.validators()) {
     if (child.subType === VALIDATOR_SUBTYPE_LENGTH) {
@@ -198,14 +205,24 @@ function getMaxLength(field: MetaField): number | undefined {
 /** Check for validator.required child OR @required attr.
  *  Uses field.validators() (effective) so inherited validators are seen. */
 function isRequired(field: MetaField): boolean {
-  if (field.ownAttr(FIELD_ATTR_REQUIRED) === true) return true;
+  if (field.attr(FIELD_ATTR_REQUIRED) === true) return true;
   return field.validators().some((child) => child.subType === VALIDATOR_SUBTYPE_REQUIRED);
 }
 
+/** The bare (package-stripped) @objectRef name on a field.object, or undefined
+ *  when unset. Used as the `.$type<VO>()` target + its sibling-module import.
+ *  A fully-qualified ref (acme::ai::SourceLens) strips to the short name. */
+function objectRefBaseName(field: MetaField): string | undefined {
+  const ref = field.attr(FIELD_ATTR_OBJECT_REF);
+  if (typeof ref === "string" && ref.length > 0) return stripPackage(ref);
+  return undefined;
+}
+
 export function mapColumnType(
   field: MetaField,
   dialect: Dialect,
   strategy: ColumnNamingStrategy = DEFAULT_COLUMN_NAMING_STRATEGY,
+  timestampMode: "date" | "string" = "string",
 ): ColumnSpec {
   const dbName = field.column ?? columnNameFromField(field.name, strategy);
   const importModule = dialect === "sqlite" ? "drizzle-orm/sqlite-core" : "drizzle-orm/pg-core";
@@ -243,13 +260,21 @@ export function mapColumnType(
           // isn't a silent rounding hazard.
           leadingComment = "TODO: SQLite has no decimal type; stored as text. Convert at the application boundary or migrate to Postgres for native numeric.";
           break;
+        case FIELD_SUBTYPE_OBJECT:
+          // A nested object is stored as a single JSON column (the default
+          // single-jsonb-column storage). SQLite has no native jsonb, so the
+          // idiomatic Drizzle form is text(..., { mode: "json" }) — agreeing with
+          // migrate-ts/expected-schema, which maps field.object → { kind: "json" }
+          // (JSON on SQLite). @storage flattened expansion is a separate codegen
+          // gap; the column TYPE here is the single-column JSON representation.
+          fnName = "text";
+          fnOptions = { mode: "json" };
+          break;
         case FIELD_SUBTYPE_DATE:
         case FIELD_SUBTYPE_TIME:
         case FIELD_SUBTYPE_TIMESTAMP:
         case FIELD_SUBTYPE_STRING:
         case FIELD_SUBTYPE_ENUM:
-        case FIELD_SUBTYPE_CLASS:
-        case FIELD_SUBTYPE_OBJECT:
         case FIELD_SUBTYPE_UUID:
           // SQLite has no native uuid type; store as TEXT (string native binding).
           fnName = "text";
@@ -263,7 +288,7 @@ export function mapColumnType(
     // A physical @dbColumnType override wins over the subtype default (Postgres
     // only; SQLite has no native analogue and falls through above). Resolved
     // first so the override-precedence matches migrate-ts's expected-schema.
-    const override = pgColumnTypeOverride(field);
+    const override = pgColumnTypeOverride(field, timestampMode);
     if (override !== undefined) {
       // Override fully determines the physical type; skip the subtype switch.
       fnName = override.fnName;
@@ -302,7 +327,7 @@ export function mapColumnType(
           // inconsistent with the string-typed schema + wire contract and
           // throws on a string write. See SP-B api-contract-generated lane.
           fnName = "timestamp";
-          fnOptions = { mode: "string" };
+          fnOptions = { mode: timestampMode };
           break;
         case FIELD_SUBTYPE_UUID:
           // Postgres native uuid column; native TS binding stays `string`.
@@ -314,8 +339,8 @@ export function mapColumnType(
           // declared @precision/@scale (mirroring migrate-ts/expected-schema so
           // codegen and the DDL agree), falling back to a sane default.
           fnName = "numeric";
-          const precision = field.ownAttr(FIELD_ATTR_PRECISION);
-          const scale = field.ownAttr(FIELD_ATTR_SCALE);
+          const precision = field.attr(FIELD_ATTR_PRECISION);
+          const scale = field.attr(FIELD_ATTR_SCALE);
           if (typeof precision === "number" && typeof scale === "number") {
             fnOptions = { precision, scale };
           } else if (typeof precision === "number") {
@@ -335,9 +360,15 @@ export function mapColumnType(
           }
           break;
         }
-        case FIELD_SUBTYPE_ENUM:
-        case FIELD_SUBTYPE_CLASS:
         case FIELD_SUBTYPE_OBJECT:
+          // A nested object is stored as a single jsonb column (the default
+          // single-jsonb-column storage), matching migrate-ts/expected-schema,
+          // which maps field.object → { kind: "json" } → JSONB on Postgres.
+          // @storage flattened expansion is a separate codegen gap; the column
+          // TYPE here is the single-column jsonb representation.
+          fnName = "jsonb";
+          break;
+        case FIELD_SUBTYPE_ENUM:
         default:
           fnName = "text";
           break;
@@ -360,7 +391,11 @@ export function mapColumnType(
 
   const modifiers: string[] = [];
 
-  if (dialect === "postgres" && isArray) {
+  // Postgres native arrays (text[]/integer[]/…) apply to SCALAR array fields
+  // only. An object-typed field is stored as a single jsonb column holding the
+  // JSON array (storage jsonb/subdocument), so it gets NO native .array() — the
+  // array-ness is carried by the .$type<VO[]>() annotation computed below.
+  if (dialect === "postgres" && isArray && subType !== FIELD_SUBTYPE_OBJECT) {
     modifiers.push(".array()");
   }
 
@@ -379,12 +414,12 @@ export function mapColumnType(
     modifiers.push(".notNull()");
   }
 
-  if (field.ownAttr(FIELD_ATTR_UNIQUE) === true) {
+  if (field.attr(FIELD_ATTR_UNIQUE) === true) {
     modifiers.push(".unique()");
   }
 
   let defaultExpr: DefaultExpr | undefined;
-  const defaultAttr = field.ownAttr(FIELD_ATTR_DEFAULT);
+  const defaultAttr = field.attr(FIELD_ATTR_DEFAULT);
   if (defaultAttr !== undefined) {
     // SQL-expression detection runs on the raw string value — a string like
     // "CURRENT_TIMESTAMP" or "now" must be emitted as sql`...`, not a literal.
@@ -407,21 +442,33 @@ export function mapColumnType(
     }
   }
 
-  // SQLite isArray columns route through {mode:"json"} above; compute the
-  // $type<E[]>() target so the renderer can hoist any cross-module imports.
+  // jsonb / JSON-in-text columns infer as `unknown` in Drizzle without a
+  // .$type<>() annotation. Carry the logical TS type so the column is typed:
+  //  - SQLite isArray: arrays serialize as JSON-in-text → .$type<E[]>() (scalar
+  //    element type, or the @objectRef VO for object arrays).
+  //  - Postgres field.object: a single jsonb column → .$type<VO>(), or
+  //    .$type<VO[]>() when isArray (the JSON array lives in the one column; no
+  //    native .array() is emitted for object storage — see modifiers above).
+  //    Scalar Postgres arrays use native .array() (already element-typed by
+  //    Drizzle) so they need no $type.
   let dollarTypeRef: ColumnSpec["dollarTypeRef"];
   if (dialect === "sqlite" && isArray) {
     if (subType === FIELD_SUBTYPE_OBJECT) {
-      const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
-      if (typeof ref === "string" && ref.length > 0) {
-        dollarTypeRef = { kind: "objectRef", name: ref, module: `./${ref}.js` };
+      const base = objectRefBaseName(field);
+      if (base !== undefined) {
+        dollarTypeRef = { kind: "objectRef", name: base, array: true };
       }
     } else {
       const scalar = sqliteJsonArrayElementTsType(subType);
       if (scalar !== undefined) {
-        dollarTypeRef = { kind: "scalar", tsType: scalar as "string" | "number" | "boolean" };
+        dollarTypeRef = { kind: "scalar", tsType: scalar as "string" | "number" | "boolean", array: true };
       }
     }
+  } else if (dialect === "postgres" && subType === FIELD_SUBTYPE_OBJECT) {
+    const base = objectRefBaseName(field);
+    if (base !== undefined) {
+      dollarTypeRef = { kind: "objectRef", name: base, array: isArray };
+    }
   }
 
   const result: ColumnSpec = {

package/src/constants.ts

@@ -8,3 +8,21 @@ export const EXTRA_SUFFIX = ".extra";
 
 /** Default outDir used by tests + as a sane default for generate(). */
 export const DEFAULT_OUT_DIR = "./src/db/entities";
+
+// ---------------------------------------------------------------------------
+// Codegen-control attributes.
+//
+// These are per-entity opt-in/opt-out flags read by generators (NOT metamodel
+// vocabulary — they tune codegen, not the model). Named here so the literals
+// aren't scattered as magic strings across the generator packages (compile-time
+// typo safety), matching the metadata package's constants discipline.
+// ---------------------------------------------------------------------------
+
+/** `@emitTanstack: false` — skip the TanStack hooks + grid generators for an entity. */
+export const CODEGEN_ATTR_EMIT_TANSTACK = "emitTanstack";
+/** `@emitGrid: true` — opt a TPH subtype IN to its own per-subtype grid (default: the polymorphic base grid is the single source). */
+export const CODEGEN_ATTR_EMIT_GRID = "emitGrid";
+/** `@emitForm: false` — skip the React form generator for an entity. */
+export const CODEGEN_ATTR_EMIT_FORM = "emitForm";
+/** `@emitRoutes: false` — skip the Fastify routes generator for an entity. */
+export const CODEGEN_ATTR_EMIT_ROUTES = "emitRoutes";

package/src/docs-paths.ts

@@ -0,0 +1,128 @@
+// docs-paths.ts — the SINGLE source of truth for where a docs page is written
+// AND how one page links to another. The file location and every inbound link
+// href are derived from the SAME functions here, so they can never diverge.
+//
+// Why this matters: pages are placed by short name. In "flat" layout two nodes
+// that share a short name across different packages (e.g. `acme::sales::Order`
+// and `acme::billing::Order`) would both want `Order.md` and one would silently
+// overwrite the other. `assertNoDuplicateDocPaths()` is the hard backstop that
+// turns that data-loss into a clear error; "package" layout folds pages under
+// package-path subdirs (`acme/sales/Order.md`) so multi-package models work.
+
+import { PACKAGE_SEPARATOR } from "@metaobjectsdev/metadata";
+import { relative as posixRelative } from "node:path/posix";
+import { packageToPath, type OutputLayout } from "./import-path.js";
+
+/** The minimal shape needed to place a docs page / compute a link to it: a
+ *  short name and its EFFECTIVE package. Build one from a metadata node via
+ *  `docPageNode()`. */
+export interface DocPageNode {
+  readonly name: string;
+  readonly package?: string | undefined;
+}
+
+/** A metadata node enough to derive page placement. `resolutionKey()` carries
+ *  the EFFECTIVE package (own package OR the file-default captured at parse
+ *  time) folded as `<pkg>::<name>` — `.package` alone is often undefined for
+ *  objects (FR5d keeps object fqn() bare), so we read placement off the
+ *  resolution key instead. */
+interface PlaceableNode {
+  readonly name: string;
+  resolutionKey(): string;
+}
+
+/** Effective package of a placeable node: the prefix of `resolutionKey()`
+ *  before the trailing `::<name>`, or undefined when the node is package-less. */
+export function effectivePackage(node: PlaceableNode): string | undefined {
+  const key = node.resolutionKey();
+  const suffix = `${PACKAGE_SEPARATOR}${node.name}`;
+  if (key === node.name) return undefined;
+  if (key.endsWith(suffix)) {
+    const pkg = key.slice(0, key.length - suffix.length);
+    return pkg === "" ? undefined : pkg;
+  }
+  return undefined;
+}
+
+/** Build a placement node ({name, effective package}) from a metadata node. The
+ *  single bridge from a loaded node to the path/href helpers — so file location
+ *  and link href derive from the SAME effective package. */
+export function docPageNode(node: PlaceableNode): DocPageNode {
+  return { name: node.name, package: effectivePackage(node) };
+}
+
+/** Output path (relative to the docs out dir) for a node's `.md` page.
+ *  Flat → `<name>.md` (today's value, byte-identical). Package → folded under
+ *  the package path (`acme/sales/Order.md`); a package-less node stays at root. */
+export function docPageOutputPath(layout: OutputLayout, node: DocPageNode): string {
+  const filename = `${node.name}.md`;
+  if (layout === "flat") return filename;
+  const dir = packageToPath(node.package);
+  return dir === "" ? filename : `${dir}/${filename}`;
+}
+
+/** Relative href FROM `fromNode`'s page TO `toNode`'s page. Derived from the
+ *  same `docPageOutputPath()` placement, so a link always points at the file's
+ *  real location in BOTH layouts. Flat → `./<to>.md`; package → a correct
+ *  relative path (e.g. `../comms/OrderEmail.md`). */
+export function docPageHref(
+  layout: OutputLayout,
+  fromNode: DocPageNode,
+  toNode: DocPageNode,
+): string {
+  const toPath = docPageOutputPath(layout, toNode);
+  if (layout === "flat") return `./${toPath}`;
+  // Relative path from the FROM page's directory to the TO page — the same
+  // raw-path rule surfaceCrossHref uses, so the two can never diverge.
+  return surfaceCrossHref(docPageOutputPath(layout, fromNode), toPath);
+}
+
+/** Relative href between two doc pages whose output paths (relative to the shared
+ *  docs outDir) may sit under different surface sub-roots — e.g. model `Order.md`
+ *  and api `api/Order.md`. The shared relative-path rule, over raw paths;
+ *  docPageHref delegates its package-layout branch here. */
+export function surfaceCrossHref(fromOutputPath: string, toOutputPath: string): string {
+  const fromDir = fromOutputPath.includes("/") ? fromOutputPath.slice(0, fromOutputPath.lastIndexOf("/")) : "";
+  const rel = posixRelative(fromDir, toOutputPath);
+  return rel.startsWith(".") ? rel : `./${rel}`;
+}
+
+/** Href FROM a page (at `fromOutputPath`, relative to the docs root) TO a page
+ *  (`page`, relative to the surface's own root) in an api surface. Relative via
+ *  `surfaceCrossHref` when the surface is in the same tree; absolute `baseUrl/page`
+ *  when the surface declares a baseUrl (federated / separate repo). */
+export function apiSurfaceHref(
+  fromOutputPath: string,
+  surface: { subDir: string; baseUrl?: string },
+  page: string,
+): string {
+  if (surface.baseUrl !== undefined && surface.baseUrl !== "") {
+    return `${surface.baseUrl.replace(/\/$/, "")}/${page}`;
+  }
+  return surfaceCrossHref(fromOutputPath, `${surface.subDir}/${page}`);
+}
+
+/** A page about to be emitted, paired with the FQN of the node that produced it
+ *  (for a precise collision diagnostic). */
+export interface DocPagePlacement {
+  path: string;
+  fqn: string;
+}
+
+/** Hard backstop against silent overwrite (ALL layouts): if two placements
+ *  resolve to the SAME output path, THROW naming both colliding node FQNs and
+ *  the path. Guarantees a docs run never silently drops a page. */
+export function assertNoDuplicateDocPaths(placements: DocPagePlacement[]): void {
+  const seen = new Map<string, string>();
+  for (const { path, fqn } of placements) {
+    const prior = seen.get(path);
+    if (prior !== undefined) {
+      throw new Error(
+        `docs: duplicate output path "${path}" from nodes ${prior} and ${fqn} — ` +
+          `use package layout (outputLayout: "package" / meta docs --layout package) ` +
+          `to disambiguate.`,
+      );
+    }
+    seen.set(path, fqn);
+  }
+}

package/src/enum-import.ts

@@ -0,0 +1,43 @@
+// FR-019 — import-specifier resolution for shared + provided enums.
+//
+// A consuming entity file references a shared enum `E` by importing it:
+//   • materialized (non-@provided) → from the generated shared enums module
+//     (`./enums`, at the entity-module target root, package-layout-aware).
+//   • @provided                    → from the per-port-configured module
+//     (`ctx.providedEnumModule`). Missing config ⇒ a codegen-time error naming
+//     the enum + the config key (ADR-0026: namespace is config, not metadata).
+
+import { withExt } from "./render-context.js";
+import type { RenderContext } from "./render-context.js";
+import { relativeModuleSpecifier } from "./import-path.js";
+import { SHARED_ENUMS_BASENAME } from "./templates/enums-file.js";
+
+/**
+ * Specifier to import a MATERIALIZED shared enum into an entity file in
+ * `entityPkg`. The shared module sits at the entity-module target root; in
+ * package layout the entity may be nested, so the `./enums` base is adjusted by
+ * package depth.
+ */
+export function sharedEnumImportSpecifier(
+  ctx: RenderContext,
+  entityPkg: string | undefined,
+): string {
+  const base = withExt(`./${SHARED_ENUMS_BASENAME}`, ctx.extStyle);
+  return relativeModuleSpecifier(ctx.selfTarget.outputLayout, entityPkg, base);
+}
+
+/**
+ * Specifier to import an externally-PROVIDED enum. Resolved from codegen config
+ * (`providedEnumModule`); throws a clear codegen-time error when unset.
+ */
+export function providedEnumImportSpecifier(ctx: RenderContext, enumName: string): string {
+  const mod = ctx.providedEnumModule;
+  if (mod === undefined || mod === "") {
+    throw new Error(
+      `provided enum "${enumName}" is marked @provided but no module is configured ` +
+      `to import it from. Set "providedEnumModule" in your codegen config (e.g. ` +
+      `providedEnumModule: "@your-app/enums") so the generated code can reference "${enumName}".`,
+    );
+  }
+  return mod;
+}