@@ -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;
+}
@@ -0,0 +1,95 @@
+// FR-019 — shared + externally-provided enum resolution.
+//
+// A reusable enum is a ROOT/package-level abstract `field.enum` (a sibling of
+// object.entity) that concrete entity fields `extends`. Per ADR-0026 such a
+// declaration is materialized ONCE per port and referenced, instead of being
+// redeclared inline in every consuming entity file.
+//
+// Two cases on the abstract declaration:
+//   • non-@provided → metaobjects MATERIALIZES the type once (a shared module),
+//     and consuming fields reference it.
+//   • @provided: true → metaobjects emits NOTHING for the type; consuming fields
+//     reference an existing hand-written/third-party type, resolved via per-port
+//     codegen config (the namespace/module never lives in metadata — ADR-0001).
+//
+// The common inline case (a concrete `field.enum` with @values declared directly,
+// no root-extends) is UNCHANGED — it stays a per-entity `<Entity><Field>` union.
+
+import type { MetaField, MetaRoot } from "@metaobjectsdev/metadata";
+import {
+  FIELD_SUBTYPE_ENUM,
+  FIELD_ATTR_PROVIDED,
+  TYPE_METADATA,
+} from "@metaobjectsdev/metadata";
+import { toPascalCase } from "./naming.js";
+import { enumValues } from "./enum-meta.js";
+
+/** A shared (root-level abstract) enum declaration the codegen must reason about. */
+export interface SharedEnum {
+  /** The materialized type name — the abstract declaration's PascalCase name (cross-port identity). */
+  readonly name: string;
+  /** Member symbols (the @values SSOT). */
+  readonly values: string[];
+  /** True when the declaration carries `@provided: true` (reference, don't materialize). */
+  readonly provided: boolean;
+}
+
+/**
+ * The root-level abstract `field.enum` a concrete enum field resolves to via
+ * `extends`, or undefined when the field is an inline enum (no root-abstract
+ * super). A super qualifies only when it is (a) an abstract field, AND (b) a
+ * direct child of the metadata root (a package-level declaration) — NOT an
+ * abstract field nested inside another object.
+ */
+export function resolveSharedEnumDecl(field: MetaField): MetaField | undefined {
+  if (field.subType !== FIELD_SUBTYPE_ENUM) return undefined;
+  const sup = field.resolveSuper();
+  if (sup === undefined) return undefined;
+  if (!sup.isAbstract) return undefined;
+  // The declaration must sit at the package/root level (sibling of object.entity),
+  // i.e. its parent node is the metadata root.
+  const parent = sup.parent;
+  if (parent === undefined || parent.type !== TYPE_METADATA) return undefined;
+  return sup;
+}
+
+/** The shared-enum descriptor a field resolves to, or undefined for inline enums. */
+export function sharedEnumForField(field: MetaField): SharedEnum | undefined {
+  const decl = resolveSharedEnumDecl(field);
+  if (decl === undefined) return undefined;
+  const values = enumValues(field);
+  if (values === undefined) return undefined;
+  return {
+    name: toPascalCase(decl.name),
+    values,
+    provided: decl.ownAttr(FIELD_ATTR_PROVIDED) === true,
+  };
+}
+
+/**
+ * All shared (root-level abstract) enum declarations in the loaded root that are
+ * actually CONSUMED by at least one concrete entity field — keyed by the
+ * materialized type name. A declaration nobody extends is not materialized (no
+ * dangling type). Deterministic order: first-consumption order across entities.
+ */
+export function collectSharedEnums(root: MetaRoot): Map<string, SharedEnum> {
+  const out = new Map<string, SharedEnum>();
+  for (const entity of root.objects()) {
+    for (const field of entity.fields()) {
+      const shared = sharedEnumForField(field);
+      if (shared === undefined) continue;
+      if (!out.has(shared.name)) out.set(shared.name, shared);
+    }
+  }
+  return out;
+}
+
+/** The shared enums that metaobjects MATERIALIZES (non-@provided, consumed). */
+export function materializedSharedEnums(root: MetaRoot): SharedEnum[] {
+  return [...collectSharedEnums(root).values()].filter((e) => !e.provided);
+}
+
+/** Whether any shared enum (materialized or provided) is consumed in the model. */
+export function hasSharedEnums(root: MetaRoot): boolean {
+  return collectSharedEnums(root).size > 0;
+}
@@ -1,6 +1,7 @@
 import type { MetaObject } from "@metaobjectsdev/metadata";
-import { perEntity, type Generator, type GeneratorFactory } from "../generator.js";
+import { perEntity, type EmittedFile, type GenContext, type Generator, type GeneratorFactory } from "../generator.js";
 import { renderEntityFile } from "../templates/entity-file.js";
+import { renderSharedEnumsFile, SHARED_ENUMS_BASENAME } from "../templates/enums-file.js";
 import { formatTs } from "../format.js";
 import { entityOutputPath } from "../import-path.js";
 import { isAbstract } from "../instance-artifacts.js";
@@ -27,24 +28,39 @@ export interface EntityFileOpts {
 
 export const entityFile = function entityFile(opts?: EntityFileOpts): Generator {
   const allowlists = opts?.allowlists ?? true;
+  const perEntityEmit = perEntity(async (entity, ctx) => {
+    if (!ctx.renderContext) {
+      throw new Error("entity-file: renderContext is required (provided by runGen)");
+    }
+    // Abstract entities contribute shape only. When emitAbstractShapes is off
+    // (cross-port knob; default on) the entity-file generator emits nothing for
+    // them. Instance/write generators skip abstract unconditionally elsewhere.
+    if (isAbstract(entity) && !ctx.renderContext.emitAbstractShapes) {
+      return [];
+    }
+    return {
+      path: entityOutputPath(ctx.config.outputLayout ?? "flat", entity.package, `${entity.name}.ts`),
+      content: await formatTs(renderEntityFile(entity, ctx.renderContext, { allowlists })),
+    };
+  });
+
   const generator: Generator = {
     name: "entity-file",
     emitsEntityModule: true,
-    generate: perEntity(async (entity, ctx) => {
-      if (!ctx.renderContext) {
-        throw new Error("entity-file: renderContext is required (provided by runGen)");
-      }
-      // Abstract entities contribute shape only. When emitAbstractShapes is off
-      // (cross-port knob; default on) the entity-file generator emits nothing for
-      // them. Instance/write generators skip abstract unconditionally elsewhere.
-      if (isAbstract(entity) && !ctx.renderContext.emitAbstractShapes) {
-        return [];
+    generate: async (ctx: GenContext): Promise<EmittedFile[]> => {
+      const files = await perEntityEmit(ctx);
+      // FR-019: emit the shared-enums module ONCE per run, into the entity-module
+      // target root. Returns null (no file) when the model uses no materialized
+      // shared enums — keeping the inline-enum default byte-identical (no new file).
+      const sharedEnums = renderSharedEnumsFile(ctx.loadedRoot);
+      if (sharedEnums !== null) {
+        files.push({
+          path: `${SHARED_ENUMS_BASENAME}.ts`,
+          content: await formatTs(sharedEnums),
+        });
       }
-      return {
-        path: entityOutputPath(ctx.config.outputLayout ?? "flat", entity.package, `${entity.name}.ts`),
-        content: await formatTs(renderEntityFile(entity, ctx.renderContext, { allowlists })),
-      };
-    }),
+      return files;
+    },
   };
   if (opts?.filter) {
     generator.filter = opts.filter;
 
@@ -47,6 +47,15 @@ export interface ResolvedGenConfig {
    *  api-docs reads this to AUTO-DETECT whether to document the Hono CRUD surface
    *  (it otherwise mirrors the default Fastify-only suite). Undefined ⇒ false. */
   includeHonoRoutes?: 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
+   * imported. metaobjects emits NO type for a provided enum — consuming entity
+   * files `import { <EnumName> } from "<providedEnumModule>"`. The per-port
+   * namespace/module is codegen config, never a metadata attr (ADR-0001). A model
+   * that references a provided enum without this set is a codegen-time error.
+   */
+  providedEnumModule?: string;
 }
 
 export interface MetaobjectsGenConfig extends ResolvedGenConfig {
 
@@ -52,6 +52,10 @@ export interface RenderContext {
   relationMap: RelationMap;
   /** Entity name → its metadata package (undefined if the entity has no package). Built once per run. */
   packageOf: Map<string, string | undefined>;
+  /** FR-019: module specifier to import externally-PROVIDED shared enums from
+   *  (`@provided: true` declarations). Undefined when unset — referencing a
+   *  provided enum without it is a codegen-time error. */
+  providedEnumModule?: string;
 }
 
 /** Optional shape — `extStyle`, `omImport`, `columnNamingStrategy`, `apiPrefix`, `outputLayout`, and `packageOf` default if omitted. `packageOf` defaults to an empty Map (correct for flat layout; `runGen` always provides the real map). */
 
@@ -181,6 +181,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
       packageOf,
       selfTarget,
       entityModuleTarget,
+      ...(config.providedEnumModule !== undefined && { providedEnumModule: config.providedEnumModule }),
     });
     const ctx: GenContext = {
       entities: safeEntities,
 
@@ -54,7 +54,7 @@ export function renderEntityFile(
   // it. The entity-file generator suppresses this entirely when
   // emitAbstractShapes is off; here we only guarantee "shape, never table".
   if (isAbstract(entity)) {
-    return renderValueObjectFile(entity, ctx.apiPrefix);
+    return renderValueObjectFile(entity, ctx.apiPrefix, ctx);
   }
 
   // --- Projection path (read-only: view-backed entity with no table source) ---
@@ -73,11 +73,11 @@ export function renderEntityFile(
   // the shape (LLM tool_use input_schema, REST body parsing) use the Zod
   // schema; consumers that need the type use the interface.
   if (!hasWritableRdbSource(entity)) {
-    return renderValueObjectFile(entity, ctx.apiPrefix);
+    return renderValueObjectFile(entity, ctx.apiPrefix, ctx);
   }
 
   // --- Vanilla / write-through entity path ---
-  const enumAliases = renderEnumTypeAliases(entity);
+  const enumAliases = renderEnumTypeAliases(entity, ctx);
   // FR-017 Tier 1: when this entity carries @discriminator AND has concrete
   // subtypes, append the discriminated-union type alias, type guards, and
   // the parse<Base>(row) dispatcher. Returns null otherwise (no subtypes, or
@@ -91,7 +91,7 @@ export function renderEntityFile(
     renderDrizzleSchema(entity, ctx),
     renderInferredTypes(entity, tphBase),
     ...(enumAliases !== null ? [enumAliases] : []),
-    renderZodValidators(entity),
+    renderZodValidators(entity, ctx),
     renderEntityConstants(entity, ctx.apiPrefix),
     ...(allowlists ? [renderFilterAllowlist(entity), renderSortAllowlist(entity)] : []),
     renderFilterType(entity),
 
@@ -0,0 +1,50 @@
+// FR-019 — shared enums module.
+//
+// Emits, ONCE per run, the materialized (non-@provided) shared enum types that
+// at least one concrete entity field references via `extends` of a root-level
+// abstract `field.enum`. Each enum yields:
+//   • `export type <E> = "A" | "B";`   — the cross-port type identity
+//   • `export const <E>Enum = z.enum(["A","B"]);` — the shared Zod validator
+//
+// Consuming entity files import these instead of redeclaring the union inline.
+// @provided enums are NEVER materialized here (they live in hand-written code,
+// imported from the configured providedEnumModule).
+
+import { code, imp, joinCode, type Code } from "ts-poet";
+import type { MetaRoot } from "@metaobjectsdev/metadata";
+import { GENERATED_HEADER } from "../constants.js";
+import { materializedSharedEnums, type SharedEnum } from "../enum-shared.js";
+import { enumUnionString } from "./inferred-types.js";
+
+/** Basename (no extension) of the shared-enums module emitted at the entity-module target root. */
+export const SHARED_ENUMS_BASENAME = "enums";
+
+/** The exported Zod-constant name for a shared enum (`<E>Enum`). */
+export function sharedEnumZodConstName(enumName: string): string {
+  return `${enumName}Enum`;
+}
+
+/** One enum's two declarations (type alias + shared z.enum const). */
+function renderOneSharedEnum(e: SharedEnum): Code {
+  const z = imp("z@zod");
+  const members = e.values.map((v) => JSON.stringify(v)).join(", ");
+  return code`
+export type ${e.name} = ${enumUnionString(e.values)};
+export const ${sharedEnumZodConstName(e.name)} = ${z}.enum([${members}]);
+`;
+}
+
+/**
+ * The full shared-enums module body, or null when the model has no materialized
+ * shared enums (so the generator emits no file at all).
+ */
+export function renderSharedEnumsFile(root: MetaRoot): string | null {
+  const enums = materializedSharedEnums(root);
+  if (enums.length === 0) return null;
+
+  const body = joinCode(enums.map(renderOneSharedEnum), { on: "\n" }).toString();
+  const header =
+    `// ${GENERATED_HEADER} — DO NOT EDIT.\n` +
+    `// Shared enum types (FR-019): one declaration per reused package-level enum.\n`;
+  return header + body;
+}