feat(codegen-python): FR-019 Python — shared + @provided enums

Brings FR-019 (ADR-0026) to the Python port, gated by the shared
fixtures/codegen-conformance/shared-provided-enum oracle:

- Metamodel: register @provided (optional boolean) on field.enum (core_types +
  field_constants) — a non-boolean value is rejected at load with
  ERR_BAD_ATTR_VALUE via the boolean AttrSchema. Inert on a concrete field.
- Shared-materialize: a package-level abstract field.enum consumed by >=1 entity
  field is emitted ONCE as a module-level `class <Name>(str, Enum)` in a shared
  `enums.py`; consuming models reference it (`from .enums import <Name>`) instead
  of inlining `Literal[...]`. New fr019_shared_enum helper (Python port of the
  TS/C#/Java/Kotlin reference).
- @provided: emit nothing for the type; consuming models import it from a
  per-port-configured module — GenConfig.provided_enum_packages (package->module)
  then the provided_enum_namespace fallback (ADR-0001). Unresolved package =>
  codegen error naming the enum + package.
- Inline enums (own @values) stay `Literal[...]` — byte-identical default; the
  shared enums.py is only emitted when a materialized shared enum exists.
- registry_manifest: carve @provided out of the canonical manifest (new
  PILOT_VOCAB reason, mirrors C#/Java) until Task 4 graduates it.
- Tests: new test_fr019_shared_provided_conformance (materialize-once /
  provided-import / missing-config-error); test_enum_conformance updated (Priority
  now materialized + referenced, not inlined).

codegen + unit + conformance suites: 810 passed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dmealing

server/python/src/metaobjects/codegen/config.py

@@ -1,11 +1,18 @@
 """Codegen run configuration (the run_gen surface)."""
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 
 
 @dataclass
 class GenConfig:
     out_dir: str
     output_layout: str = "flat"  # "flat" only in sub-project A
     emit_abstract_shapes: bool = True  # Python concretes subclass the abstract base model
+    # FR-019 (ADR-0026): per-port resolution of a @provided enum's import module. The module
+    # never lives in metadata (ADR-0001) — it is codegen config. ``provided_enum_packages``
+    # maps a declaring metadata package ("acme::shop") to the Python import module; with a
+    # single ``provided_enum_namespace`` fallback for the one-module case. A referenced
+    # @provided enum whose package resolves to no module is a codegen-time error.
+    provided_enum_namespace: str | None = None
+    provided_enum_packages: dict[str, str] = field(default_factory=dict)

server/python/src/metaobjects/codegen/generators/entity_model.py

@@ -7,10 +7,12 @@
 from metaobjects.meta.core.validator import validator_constants as vc
 from metaobjects.shared.base_types import TYPE_VALIDATOR
 from metaobjects.shared.separators import PACKAGE_SEP
+from metaobjects.codegen.config import GenConfig
 from metaobjects.codegen.constants import generated_header
-from metaobjects.codegen.type_map import py_type_for
+from metaobjects.codegen.type_map import field_is_array, py_type_for
 from metaobjects.codegen.format import ruff_format
 from metaobjects.codegen.generator import EmittedFile, GenContext, Generator, per_entity
+from metaobjects.codegen.generators import fr019_shared_enum as fr019
 from metaobjects.codegen.generators.m2m_codegen import (
     build_object_index,
     resolve_m2m_descriptors,
@@ -89,10 +91,24 @@ def _validator_constraints(field: MetaField) -> dict[str, object]:
     return kwargs
 
 
-def _field_line(field: MetaField, imports: set[str]) -> tuple[str, bool]:
+def _field_line(field: MetaField, imports: set[str], config: GenConfig) -> tuple[str, bool]:
     """Return (source line, uses_field). Collects required imports into *imports*."""
-    pt = py_type_for(field)
-    imports.update(pt.imports)
+    # FR-019: a field resolving to a package-level shared enum is typed by the materialized
+    # standalone class (imported from the shared `enums` module) or — when @provided — an
+    # external module from per-port config; inline enums keep their `Literal[...]` (py_type_for).
+    shared = (
+        fr019.shared_enum_for_field(field)
+        if field.sub_type == fc.FIELD_SUBTYPE_ENUM
+        else None
+    )
+    if shared is not None:
+        type_name, import_line = fr019.enum_type_and_import(shared, config)
+        imports.add(import_line)
+        type_expr = f"list[{type_name}]" if field_is_array(field) else type_name
+    else:
+        pt = py_type_for(field)
+        imports.update(pt.imports)
+        type_expr = pt.expr
     if field.sub_type == fc.FIELD_SUBTYPE_OBJECT:
         ref = field.attr(fc.FIELD_ATTR_OBJECT_REF)
         if ref:
@@ -105,7 +121,7 @@ def _field_line(field: MetaField, imports: set[str]) -> tuple[str, bool]:
     parts = [f"{k}={constraints[k]!r}" for k in _order if k in constraints]
     uses_field = bool(parts)
 
-    annotation = pt.expr if required else f"{pt.expr} | None"
+    annotation = type_expr if required else f"{type_expr} | None"
     if required and uses_field:
         assignment = f" = Field({', '.join(parts)})"
     elif required:
@@ -158,16 +174,19 @@ def _emit_field_lines(
         entity: MetaObject,
         imports: set[str],
         object_index: dict[str, MetaObject] | None,
+        config: GenConfig | None = None,
     ) -> tuple[list[str], bool]:
         """The model body: one line per own field, then M:N nested collections when
         *object_index* is supplied. Returns ``(lines, uses_field)`` where
         ``uses_field`` is True iff any line used a pydantic ``Field(...)`` (so the
         caller knows to import ``Field``). Required imports are collected into
-        *imports*. Override to add/transform body lines."""
+        *imports*. *config* carries the FR-019 @provided-enum resolution. Override to
+        add/transform body lines."""
+        cfg = config if config is not None else GenConfig(out_dir="")
         uses_field = False
         lines: list[str] = []
         for f in entity.own_fields():
-            line, used = _field_line(f, imports)
+            line, used = _field_line(f, imports, cfg)
             uses_field = uses_field or used
             lines.append(line)
 
@@ -184,22 +203,26 @@ def _emit_field_lines(
         return lines, uses_field
 
     def render_entity_model(
-        self, entity: MetaObject, object_index: dict[str, MetaObject] | None = None
+        self,
+        entity: MetaObject,
+        object_index: dict[str, MetaObject] | None = None,
+        config: GenConfig | None = None,
     ) -> str:
         """Render an entity as a Pydantic v2 model (pre-format; the generator runs ruff).
 
         When *object_index* is supplied, M:N navigations (``relationship.*``
         ``@cardinality:"many" + @through``) are emitted as nested Pydantic
         collections (``tags: list[Tag] = []``); a self-join uses a forward-ref string
         (``following: list["Person"] = []``). Without an index, only scalar/object
-        fields are emitted (back-compat)."""
+        fields are emitted (back-compat). *config* carries the FR-019 @provided-enum
+        resolution; when omitted, only the non-provided shared-materialize path is reachable."""
         imports: set[str] = set()
         base_class = "BaseModel"
         if entity.super_data is not None:
             base_class = entity.super_data.name
             imports.add(f"from .{base_class} import {base_class}")
 
-        lines, uses_field = self._emit_field_lines(entity, imports, object_index)
+        lines, uses_field = self._emit_field_lines(entity, imports, object_index, config)
 
         # FR-017 TPH: a concrete subtype pins the inherited discriminator field to its
         # own value (Literal) so the Pydantic model rejects a foreign-subtype tag —
@@ -237,23 +260,51 @@ def render_entity_model(
         parts += ["", self._emit_class_header(entity, base_class), *body, ""]
         return "\n".join(parts)
 
+    def _render_shared_enums_module(self, entities: list[MetaObject]) -> EmittedFile | None:
+        """FR-019: the shared ``enums.py`` module — one module-level
+        ``class <Name>(str, Enum)`` per materialized (package-level abstract, non-``@provided``,
+        consumed) enum. ``None`` when the model has no materialized shared enum, so the inline
+        default output is byte-identical (no spurious empty module)."""
+        shared = fr019.materialized_shared_enums(entities)
+        if not shared:
+            return None
+        parts: list[str] = [
+            generated_header("enums", "enums"),
+            "from __future__ import annotations",
+            "",
+            "from enum import Enum",
+            "",
+        ]
+        for e in shared:
+            parts += ["", f"class {e.name}(str, Enum):"]
+            parts += [f'    {m} = "{m}"' for m in e.values]
+        parts.append("")
+        return EmittedFile(path="enums.py", content=ruff_format("\n".join(parts)))
+
     def generate(self, ctx: GenContext) -> list[EmittedFile]:
         index = build_object_index(ctx.entities)
-        return per_entity(
+        files = per_entity(
             lambda e, _c: EmittedFile(
                 path=f"{e.name}.py",
-                content=ruff_format(self.render_entity_model(e, index)),
+                content=ruff_format(self.render_entity_model(e, index, ctx.config)),
             )
         )(ctx)
+        matched = [e for e in ctx.entities if ctx.matches(e)]
+        enums_module = self._render_shared_enums_module(matched)
+        if enums_module is not None:
+            files.append(enums_module)
+        return files
 
 
 def render_entity_model(
-    entity: MetaObject, object_index: dict[str, MetaObject] | None = None
+    entity: MetaObject,
+    object_index: dict[str, MetaObject] | None = None,
+    config: GenConfig | None = None,
 ) -> str:
     """Module-level back-compat wrapper. Delegates to a default
     :class:`EntityModelGenerator` instance so existing callers (and the golden
     tests) are unaffected. Subclass :class:`EntityModelGenerator` to customize."""
-    return EntityModelGenerator().render_entity_model(entity, object_index)
+    return EntityModelGenerator().render_entity_model(entity, object_index, config)
 
 
 def entity_model() -> Generator:

server/python/src/metaobjects/codegen/generators/fr019_shared_enum.py

@@ -0,0 +1,135 @@
+"""FR-019 — shared + externally-provided enum resolution (Python port of the TS reference
+``enum-shared.ts`` and the C#/Java/Kotlin ``Fr019SharedEnum``).
+
+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 as a module-level ``class <Name>(str, Enum)`` and referenced, instead of redeclaring the
+members inline (a per-entity ``Literal[...]``) in every consumer.
+
+Two cases on the abstract declaration:
+
+* non-``@provided`` → metaobjects MATERIALIZES the type once (a shared ``enums.py`` module), and
+  consuming fields reference it (``from .enums import <Name>``).
+* ``@provided: true`` → metaobjects emits NOTHING for the type; consuming fields import an existing
+  type from a per-port-configured module (``GenConfig.provided_enum_packages`` keyed by the enum's
+  declaring metadata package, then the ``provided_enum_namespace`` fallback). The module never lives
+  in metadata (ADR-0001); a missing config for a referenced provided enum is a codegen-time error
+  naming the enum + its package.
+
+The common inline case (a concrete ``field.enum`` with own ``@values``, no root-extends) is
+UNCHANGED — it stays a per-entity ``Literal[...]`` (byte-identical default).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from metaobjects.meta.core.field.meta_field import MetaField
+from metaobjects.meta.core.field import field_constants as fc
+from metaobjects.meta.meta_data import MetaData
+from metaobjects.shared.base_types import TYPE_METADATA
+from metaobjects.shared.separators import PACKAGE_SEP
+from metaobjects.codegen import type_map
+from metaobjects.codegen.config import GenConfig
+
+
+@dataclass(frozen=True)
+class SharedEnum:
+    """A shared (package-level abstract) enum declaration codegen reasons about."""
+
+    name: str            #: materialized type name — the decl's PascalCase short name (cross-port id)
+    values: list[str]    #: member symbols (the @values SSOT), verbatim
+    provided: bool       #: True when the decl carries @provided: true (reference, don't materialize)
+    meta_package: str    #: declaring metadata package in "::" form (the provided-config key)
+
+
+def _pascal(name: str) -> str:
+    """``priority`` → ``Priority`` (leading char only; no snake-splitting — cross-port rule)."""
+    return name[:1].upper() + name[1:] if name else name
+
+
+def resolve_shared_enum_decl(field: MetaField) -> MetaData | None:
+    """The package-level abstract ``field.enum`` *field* resolves to via ``extends``, or ``None``
+    for an inline enum. Qualifies only when the immediate super is (a) a ``field.enum``,
+    (b) abstract, AND (c) a direct child of the metadata root — a sibling of ``object.entity``,
+    not an abstract field nested inside an object."""
+    if field.sub_type != fc.FIELD_SUBTYPE_ENUM:
+        return None
+    sup = field.super_data
+    if sup is None or sup.sub_type != fc.FIELD_SUBTYPE_ENUM:
+        return None
+    if not getattr(sup, "is_abstract", False):
+        return None
+    parent = sup.parent
+    if parent is None or parent.type != TYPE_METADATA:
+        return None
+    return sup
+
+
+def is_provided(decl: MetaData) -> bool:
+    """Own ``@provided`` truth of an enum declaration."""
+    return decl.attr(fc.FIELD_ATTR_PROVIDED) is True
+
+
+def _meta_package_of(decl: MetaData) -> str:
+    """The decl's metadata package in ``::`` form (its resolution key minus the trailing name)."""
+    key = decl.resolution_key()
+    idx = key.rfind(PACKAGE_SEP)
+    return key[:idx] if idx >= 0 else ""
+
+
+def shared_enum_for_field(field: MetaField) -> SharedEnum | None:
+    """The shared-enum descriptor *field* resolves to, or ``None`` for inline enums."""
+    decl = resolve_shared_enum_decl(field)
+    if decl is None:
+        return None
+    values = type_map.effective_enum_values(field)
+    if not values:
+        return None
+    return SharedEnum(
+        name=_pascal(decl.name),
+        values=values,
+        provided=is_provided(decl),
+        meta_package=_meta_package_of(decl),
+    )
+
+
+def collect_shared_enums(entities: list) -> list[SharedEnum]:
+    """All shared (package-level abstract) enum decls CONSUMED by at least one entity field,
+    keyed by materialized type name, sorted by name (deterministic). A decl nobody extends is
+    not materialized (no dangling type)."""
+    out: dict[str, SharedEnum] = {}
+    for entity in entities:
+        for f in entity.own_fields():
+            shared = shared_enum_for_field(f)
+            if shared is None:
+                continue
+            out.setdefault(shared.name, shared)
+    return sorted(out.values(), key=lambda e: e.name)
+
+
+def materialized_shared_enums(entities: list) -> list[SharedEnum]:
+    """The shared enums metaobjects MATERIALIZES (non-``@provided``, consumed)."""
+    return [e for e in collect_shared_enums(entities) if not e.provided]
+
+
+def enum_type_and_import(shared: SharedEnum, config: GenConfig) -> tuple[str, str]:
+    """The ``(type_name, import_line)`` a consuming field emits for a shared/provided enum:
+
+    * materialized → ``("<Name>", "from .enums import <Name>")`` (the shared module).
+    * ``@provided`` → ``("<Name>", "from <module> import <Name>")``, *module* resolved from
+      ``config.provided_enum_packages`` (keyed by the enum's metadata package) then the single
+      ``config.provided_enum_namespace`` fallback. A missing config is a codegen-time ``ValueError``
+      naming the enum + its package (ADR-0026 / ADR-0001)."""
+    name = shared.name
+    if not shared.provided:
+        return name, f"from .enums import {name}"
+    module = config.provided_enum_packages.get(shared.meta_package) or config.provided_enum_namespace
+    if not module:
+        raise ValueError(
+            f'provided enum "{name}" (declared in package "{shared.meta_package}") is marked '
+            f"@provided but no Python import module is configured to reference it from. Map its "
+            f'package in GenConfig.provided_enum_packages["{shared.meta_package}"] = '
+            f'"your_app.enums", or set the single provided_enum_namespace fallback, so the '
+            f'generated code can import "{name}".'
+        )
+    return name, f"from {module} import {name}"

server/python/src/metaobjects/core_types.py

@@ -23,6 +23,7 @@
     FIELD_ATTR_CURRENCY,
     FIELD_ATTR_DEFAULT,
     FIELD_ATTR_ENUM_ALIAS,
+    FIELD_ATTR_PROVIDED,
     FIELD_ATTR_ENUM_DOC,
     FIELD_ATTR_EXAMPLE,
     FIELD_ATTR_FILTERABLE,
@@ -372,6 +373,14 @@ def _register_subtypes(
                 value_type=ATTR_SUBTYPE_PROPERTIES,
                 required=False,
             ),
+            # FR-019 (ADR-0026): @provided boolean — marks an abstract package-level enum
+            # as externally provided (codegen references it instead of materializing). The
+            # boolean AttrSchema rejects a non-boolean value (ERR_BAD_ATTR_VALUE).
+            AttrSchema(
+                name=FIELD_ATTR_PROVIDED,
+                value_type=ATTR_SUBTYPE_BOOLEAN,
+                required=False,
+            ),
             AttrSchema(
                 name=FIELD_ATTR_ENUM_DOC,
                 value_type=ATTR_SUBTYPE_PROPERTIES,

server/python/src/metaobjects/meta/core/field/field_constants.py

@@ -68,6 +68,12 @@
 #   @enumDoc:   member -> human-readable description (shown per-member in the 'guide' prompt).
 FIELD_ATTR_ENUM_ALIAS = "enumAlias"
 FIELD_ATTR_ENUM_DOC = "enumDoc"
+# FR-019 (ADR-0026): @provided boolean, own-only on an ABSTRACT package-level field.enum
+# declaration. When true, codegen does NOT materialize the enum type; consuming fields
+# reference an existing hand-written/third-party type resolved via per-port codegen config
+# (never an FQN in metadata — ADR-0001). Default false. Inert on a concrete consuming field.
+# Non-boolean → ERR_BAD_ATTR_VALUE (the boolean AttrSchema).
+FIELD_ATTR_PROVIDED = "provided"
 # FR-011 enum extract-hardening attrs (field.enum only).
 #   @coerceDefault: present-but-uncoercible extract fallback member → DEFAULTED.
 #       Member-validated against the effective @values (own or inherited).

server/python/src/metaobjects/registry_manifest.py

@@ -25,6 +25,7 @@
 from enum import Enum
 
 from .documentation.doc_constants import DOC_ATTR_DESCRIPTION
+from .meta.core.field.field_constants import FIELD_ATTR_PROVIDED
 from .meta.core.attr.attr_constants import (
     ATTR_SUBTYPE_STRING,
     ATTR_SUBTYPE_STRINGARRAY,
@@ -61,6 +62,11 @@ class ExclusionReason(str, Enum):
     INHERITANCE_ANCHOR = "inheritance-anchor"
     #: TS-web-presentation-only facet (the generic ``view.*`` controls).
     PRESENTATION_ONLY = "presentation-only"
+    #: A pilot/not-yet-graduated cross-port attr: registered + functional here but held out of
+    #: the canonical manifest until every port registers it (then it graduates into
+    #: expected-registry.json and the carve-out is removed). Currently FR-019 ``@provided``
+    #: (ADR-0026). Mirrors the C# ``ExclusionReason.PilotVocab`` / Java ``PILOT_VOCAB``.
+    PILOT_VOCAB = "pilot-vocab"
 
 
 _ATTR_NAME_IS_ABSTRACT = "isAbstract"
@@ -84,6 +90,10 @@ class ExclusionReason(str, Enum):
     _ATTR_NAME_OBJECT: ExclusionReason.NATIVE_BINDING,
     _ATTR_NAME_OBJECT_ADAPTER: ExclusionReason.NATIVE_BINDING,
     DOC_ATTR_DESCRIPTION: ExclusionReason.COMMON_ATTR_DUP,
+    # FR-019 @provided (ADR-0026): registered + functional on field.enum, held out of the
+    # canonical manifest until all five ports register it (Task 4 graduates it into
+    # expected-registry.json and removes this carve-out). Mirrors C#/Java.
+    FIELD_ATTR_PROVIDED: ExclusionReason.PILOT_VOCAB,
 }