metaobjects 0.19.7__tar.gz → 0.19.9__tar.gz

{metaobjects-0.19.7 → metaobjects-0.19.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metaobjects
-Version: 0.19.7
+Version: 0.19.9
 Summary: Cross-language metadata standard: declare typed entities once, generate idiomatic drift-checked code across languages — Python port.
 Project-URL: Homepage, https://metaobjects.dev
 Project-URL: Repository, https://github.com/metaobjectsdev/metaobjects

{metaobjects-0.19.7 → metaobjects-0.19.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metaobjects"
-version = "0.19.7"
+version = "0.19.9"
 description = "Cross-language metadata standard: declare typed entities once, generate idiomatic drift-checked code across languages — Python port."
 readme = "README.md"
 requires-python = ">=3.11"

{metaobjects-0.19.7 → metaobjects-0.19.9}/src/metaobjects/apidocs/builder.py

@@ -55,11 +55,24 @@ from metaobjects.meta.meta_data import MetaData
 from metaobjects.meta.persistence.source.source_constants import SOURCE_KIND_TABLE
 from metaobjects.meta.template import template_constants as tc
 from metaobjects.shared.base_types import TYPE_OBJECT, TYPE_TEMPLATE
+from metaobjects.shared.separators import PACKAGE_SEP
 
 # Structured formats that get an output-format prompt + a tolerant extractor.
 _STRUCTURED_FORMATS = frozenset({tc.TEMPLATE_FORMAT_JSON, tc.TEMPLATE_FORMAT_XML})
 
 
+def _pkg_of(node: MetaData) -> str:
+    """The effective package of a node — its ``resolution_key()`` minus the
+    trailing ``::<name>`` ("" for a root-level node). Duplicated (not imported) to
+    match the existing per-generator convention. Used to derive a template's
+    referrer package for ``resolve_payload_vo`` (#228) — see that function's
+    docstring for why this ancestor-walk-aware form is used instead of the
+    loader's bare ``tpl.package or tpl.file_default_package or ""``."""
+    key = node.resolution_key()
+    i = key.rfind(PACKAGE_SEP)
+    return "" if i == -1 else key[:i]
+
+
 # ---------------------------------------------------------------------------
 # Applies-predicates — each REUSES the matching generator's own gate helpers, so
 # inclusion can never drift from emission. (The Python generators gate inline;
@@ -95,7 +108,9 @@ def _payload_resolves(tmpl: MetaData, root: MetaData) -> MetaObject | None:
     payload_ref = tmpl.get_meta_attr(tc.TEMPLATE_ATTR_PAYLOAD_REF)  # ADR-0039: template attr resolves via extends (not origin; templates CAN extend)
     if not isinstance(payload_ref, str) or not payload_ref:
         return None
-    return resolve_payload_vo(root, payload_ref)
+    # ADR-0042 (#228): the referrer is THIS template — a bare @payloadRef resolves
+    # in ITS OWN package first.
+    return resolve_payload_vo(root, payload_ref, _pkg_of(tmpl))
 
 
 def _is_email_kind(tmpl: MetaData) -> bool:

{metaobjects-0.19.7 → metaobjects-0.19.9}/src/metaobjects/cli.py

@@ -84,6 +84,17 @@ from metaobjects.render.verify import (
     verify as render_verify,
 )
 from metaobjects.shared.base_types import TYPE_TEMPLATE
+from metaobjects.shared.separators import PACKAGE_SEP
+
+
+def _pkg_of(node: MetaData) -> str:
+    """The effective package of a node — its ``resolution_key()`` minus the
+    trailing ``::<name>`` ("" for a root-level node). Duplicated (not imported) to
+    match the existing per-generator convention. Used to derive a template's
+    referrer package for ``_resolve_payload_vo`` (#228)."""
+    key = node.resolution_key()
+    i = key.rfind(PACKAGE_SEP)
+    return "" if i == -1 else key[:i]
 
 
 def _default_generators() -> list[Generator]:
@@ -642,7 +653,9 @@ def _verify_templates(args: argparse.Namespace) -> int:
             print(f"error: [{tmpl.name}] missing @payloadRef.", file=sys.stderr)
             error_count += 1
             continue
-        vo = _resolve_payload_vo(root, payload_ref)
+        # ADR-0042 (#228): the referrer is THIS template — a bare @payloadRef
+        # resolves in ITS OWN package first.
+        vo = _resolve_payload_vo(root, payload_ref, _pkg_of(tmpl))
         if vo is None:
             print(
                 f"error: [{tmpl.name}] @payloadRef '{payload_ref}' did not "

metaobjects-0.19.9/src/metaobjects/codegen/collision_names.py

@@ -0,0 +1,110 @@
+"""ADR-0044 — collision-scoped nested-VO name assignment (shared).
+
+Promoted out of ``payload_vo_generator.py`` (formerly the module-private
+``_package_qualified_name`` / ``_assign_nested_names``) so every Python generator that
+walks a payload's nested-value-object closure derives IDENTICAL emitted names for an
+IDENTICAL closure. Today that's the payload-record tier (``payload_vo_generator.py``)
+AND the extract/output-parser tier (``extract_delegate_emitter.py`` /
+``extractor_generator.py`` / ``output_parser_generator.py``) — a nested class an
+extractor module IMPORTS from the sibling payload module must be spelled exactly the
+way the payload module itself emitted it, so both tiers MUST share one naming
+function rather than re-derive a second (and possibly-diverging) copy (issue #228).
+
+:func:`assign_nested_names` returns BASE names only — a bare short name when it is
+unique across the closure, else its package-qualified derived form
+(``acme::alpha`` + ``Note`` → ``AcmeAlphaNote``). It never bakes in a suffix; each
+caller applies its OWN transform on top of the shared base (the payload tier:
+``payload_class_name(base)`` → ``...Payload``; the extract tier: ``f"{base}Extracted"``
+for the mirror dataclass, ``f"_to_strict_{snake(base)}"`` / ``f"_from_{snake(base)}
+_extracted"`` for the mapper function names) — one pure function of the closure feeds
+every naming scheme that must agree on the same base.
+"""
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+
+from metaobjects.errors import ErrorCode
+from metaobjects.meta.meta_data import MetaData
+from metaobjects.shared.separators import PACKAGE_SEP
+
+#: ADR-0044 backstop error code — REUSED (never redefined) from the shared cross-port
+#: error-code ledger (``metaobjects.errors.ErrorCode``), which already carries it.
+ERR_PAYLOAD_NAME_COLLISION = ErrorCode.ERR_PAYLOAD_NAME_COLLISION.value
+
+
+def pascal_segment(name: str) -> str:
+    """``priority`` → ``Priority`` (leading char upper-cased only; no snake-splitting)
+    — matches the cross-port rule for PascalCasing a bare field/package segment."""
+    return name[:1].upper() + name[1:] if name else name
+
+
+def package_qualified_name(pkg: str, short_name: str) -> str:
+    """PascalCase each ``::``-segment of *pkg*, concatenate, append the bare
+    *short_name* (``acme::alpha`` + ``Note`` → ``AcmeAlphaNote``). A root-level
+    (empty-package) node keeps its bare short name — the loader's own-package
+    uniqueness already precludes two root-level nodes sharing a name, so this can't
+    silently under-qualify."""
+    if pkg == "":
+        return short_name
+    return "".join(pascal_segment(seg) for seg in pkg.split(PACKAGE_SEP)) + short_name
+
+
+def _pkg_of(node: MetaData) -> str:
+    """The effective package of an object — its ``resolution_key()`` minus the
+    trailing ``::<name>`` ("" for a root-level object). Derived from the resolution
+    key so it is correct for BOTH loaded trees (file_default_package) and
+    programmatically-built trees (package only on the root)."""
+    key = node.resolution_key()
+    i = key.rfind(PACKAGE_SEP)
+    return "" if i == -1 else key[:i]
+
+
+def assign_nested_names(
+    closure: Mapping[str, MetaData],
+    class_name_fn: Callable[[str], str] | None = None,
+) -> dict[str, str]:
+    """ADR-0044 pass 2 — ``resolution_key()`` → emitted name. A PURE function of the
+    closure's ``(key, short-name, package)`` triples, never of traversal order: a bare
+    short name unique in the closure emits its bare form (byte-identical to
+    pre-ADR-0044 output); a short-name collision emits EVERY member under its
+    package-qualified derived form. If two distinct keys still derive the same name,
+    fails loud with ``ERR_PAYLOAD_NAME_COLLISION`` — never silently collides a second
+    time.
+
+    *class_name_fn*, when supplied, transforms each derived BASE name (bare or
+    package-qualified) into the caller's final emitted name — e.g.
+    ``payload_vo_generator`` passes ``payload_class_name`` (bare ``"Note"`` →
+    ``"NotePayload"``) so its own collision backstop message names the actual emitted
+    class. Omitted (``None``, the default) → identity, returning bare BASE names — the
+    extract tier's callers apply their OWN suffix/transform on top (see module
+    docstring) so every naming scheme derives from ONE shared base-assignment pass.
+    """
+    name_fn: Callable[[str], str] = class_name_fn if class_name_fn is not None else (lambda base: base)
+
+    by_short: dict[str, list[str]] = {}
+    for key, node in closure.items():
+        by_short.setdefault(node.name, []).append(key)
+
+    name_map: dict[str, str] = {}
+    for short, keys in by_short.items():
+        if len(keys) == 1:
+            name_map[keys[0]] = name_fn(short)
+            continue
+        for key in keys:
+            node = closure[key]
+            name_map[key] = name_fn(package_qualified_name(_pkg_of(node), short))
+
+    # Backstop — sorted by key so both the emptiness of the colliding set and the
+    # pair named in the message are a pure function of the closure, not dict order.
+    owner: dict[str, str] = {}
+    for key in sorted(name_map):
+        emitted = name_map[key]
+        existing = owner.get(emitted)
+        if existing is not None and existing != key:
+            raise ValueError(
+                f"{ERR_PAYLOAD_NAME_COLLISION}: payload record name collision: "
+                f'"{emitted}" derives from both "{existing}" and "{key}" — rename one '
+                "value-object or move it to a package that derives a distinct name"
+            )
+        owner[emitted] = key
+    return name_map

{metaobjects-0.19.7 → metaobjects-0.19.9}/src/metaobjects/codegen/extract_delegate_emitter.py

@@ -24,43 +24,55 @@ emitted code stays self-sufficient and reflection-free.
 
 Bounded by the cross-port ``MAX_NEST_DEPTH`` via the runtime — codegen here only mirrors
 the runtime's resolved object graph, so depth/cycle guarding lives in ``object_extract``.
-The emitter dedupes mirrors/mappers by VO simple name (cycle-safe).
+The emitter dedupes mirrors/mappers by ``resolution_key()`` (the package-qualified FQN,
+cycle-safe) — NOT the bare VO ``name``, which would silently collapse two same-short-name
+value-objects from different packages into one (ADR-0044, #228). A bare-name collision
+resolves to a package-qualified emitted name via the shared
+:func:`~metaobjects.codegen.collision_names.assign_nested_names` pass (see
+:func:`build_name_map`) — the SAME naming pass the payload-record tier
+(``payload_vo_generator``) runs, so this tier's names never diverge from the payload
+module's own.
 """
 from __future__ import annotations
 
 from metaobjects.codegen import fr010_field_mapping as fm
+from metaobjects.codegen.collision_names import assign_nested_names
 from metaobjects.meta.core.field import field_constants as fc
 from metaobjects.meta.meta_data import MetaData
-from metaobjects.shared.base_types import TYPE_OBJECT
+from metaobjects.naming_refs import resolve_object_ref
 from metaobjects.shared.separators import PACKAGE_SEP
 
 
-def _find_object(root: MetaData, name: str) -> MetaData | None:
-    """The top-level ``object.*`` node named *name*, or ``None``.
-
-    ADR-0039 sanctioned own: top-level object lookup on the loader ROOT
-    (metadata.root is never extended, so own == effective) — mirrors the TS
-    reference (``root.ownChildren()``).
-    """
-    for c in root.own_children():
-        if c.type == TYPE_OBJECT and c.name == name:
-            return c
-    return None
+def _pkg_of(node: MetaData) -> str:
+    """The effective package of an object — its ``resolution_key()`` minus the
+    trailing ``::<name>`` ("" for a root-level object). Duplicated (not imported) to
+    match the existing per-generator convention — ``payload_vo_generator.py`` and
+    ``render_helper_generator.py`` each carry their own identical copy."""
+    key = node.resolution_key()
+    i = key.rfind(PACKAGE_SEP)
+    return "" if i == -1 else key[:i]
 
 
 def ref_vo(field: MetaData, root: MetaData) -> MetaData | None:
     """The ``@objectRef`` target VO for a nested-object field, or ``None`` when
-    unresolvable. Matches first on the full ref, then the trailing simple-name
-    segment (mirrors the runtime ``_resolve_object_ref`` short-name fallback)."""
+    unresolvable.
+
+    ADR-0042 (#228) — resolves via the canonical `resolve_object_ref` package-local
+    contract: an FQN ref resolves EXACTLY; a bare ref resolves in the DECLARING
+    field's own package first, else a root-level object. NO bare-tail short-name
+    fallback — that pattern (matching an FQN ref by its trailing simple-name segment
+    against ANY same-named object root-wide) is the #219/ADR-0042-banned "wrong
+    node" bug: under a cross-package short-name collision it silently binds
+    whichever same-named object happens to load first, regardless of which package
+    the ref actually pointed at. *referrer_pkg* is the field's OWN declaring
+    package (which differs from the VO's when the field is inherited via `extends`
+    from an abstract VO in another package) — mirrors payload_vo_generator's
+    `_resolve_object_field_type`."""
     ref = field.attrs().get(fc.FIELD_ATTR_OBJECT_REF)
     if not isinstance(ref, str) or not ref:
         return None
-    direct = _find_object(root, ref)
-    if direct is not None:
-        return direct
-    if PACKAGE_SEP in ref:
-        return _find_object(root, ref.rsplit(PACKAGE_SEP, 1)[-1])
-    return None
+    referrer_pkg = _pkg_of(field.parent) if field.parent is not None else ""
+    return resolve_object_ref(root, ref, referrer_pkg)
 
 
 def _is_object_field(field: MetaData) -> bool:
@@ -69,14 +81,20 @@ def _is_object_field(field: MetaData) -> bool:
     return field.sub_type == fc.FIELD_SUBTYPE_OBJECT
 
 
-def mirror_name(vo: MetaData) -> str:
-    """The extracted-mirror dataclass name for a value-object (``<Name>Extracted``)."""
-    return f"{vo.name}Extracted"
+def mirror_name(vo: MetaData, name_map: dict[str, str]) -> str:
+    """The extracted-mirror dataclass name for a value-object
+    (``<Base>Extracted``) — ADR-0044 (#228) collision-scoped: *base* is the bare
+    ``vo.name`` unless a cross-package bare-name collision requires the
+    package-qualified derived form (see :func:`build_name_map`)."""
+    base = name_map.get(vo.resolution_key(), vo.name)
+    return f"{base}Extracted"
 
 
-def _mapper_name(vo: MetaData) -> str:
-    """The mapper function name for a value-object (``_from_<name>_extracted``)."""
-    return f"_from_{_snake(vo.name)}_extracted"
+def _mapper_name(vo: MetaData, name_map: dict[str, str]) -> str:
+    """The mapper function name for a value-object (``_from_<base_snake>_extracted``)
+    — *base* per :func:`mirror_name`."""
+    base = name_map.get(vo.resolution_key(), vo.name)
+    return f"_from_{_snake(base)}_extracted"
 
 
 def root_mapper_name(template_name: str) -> str:
@@ -101,12 +119,12 @@ def _snake(name: str) -> str:
 # =============================================================================
 
 
-def _nested_mirror_type(field: MetaData, root: MetaData) -> str:
+def _nested_mirror_type(field: MetaData, root: MetaData, name_map: dict[str, str]) -> str:
     """The nullable mirror annotation for one field — nested-aware (nested objects
     become ``<Nested>Extracted``; array-of-objects become ``list[...]``)."""
     if _is_object_field(field):
         target = ref_vo(field, root)
-        base = f'"{mirror_name(target)}"' if target is not None else "object"
+        base = f'"{mirror_name(target, name_map)}"' if target is not None else "object"
         elem = f"{base} | None"
         return f"list[{elem}] | None" if fm.is_array(field) else elem
     if fm.is_array(field):
@@ -130,20 +148,29 @@ def _nested_mirror_type(field: MetaData, root: MetaData) -> str:
 
 def reachable_vos(vo: MetaData, root: MetaData) -> list[MetaData]:
     """``vo`` + every value-object reachable through nested ``@objectRef`` fields, in
-    stable BFS order, deduped by simple name (cycle-safe)."""
+    stable BFS order, deduped by ``resolution_key()`` (cycle-safe).
+
+    ADR-0044 (#228) — deduping by the bare ``name`` (pre-fix) silently DROPPED a
+    second cross-package value-object sharing the first one's bare short name (e.g.
+    ``acme::alpha::Note`` + ``acme::beta::Note``): once the first ``Note`` was seen,
+    the second's bare name matched ``seen`` and it was never queued/emitted — a
+    silent shape loss, not merely a naming cosmetic. ``resolution_key()`` is the
+    package-qualified FQN, so two same-short-name VOs from different packages are
+    two distinct keys and both survive the walk."""
     out: list[MetaData] = []
     seen: set[str] = set()
     queue: list[MetaData] = [vo]
     while queue:
         cur = queue.pop(0)
-        if cur.name in seen:
+        key = cur.resolution_key()
+        if key in seen:
             continue
-        seen.add(cur.name)
+        seen.add(key)
         out.append(cur)
         for f in fm.fields(cur):
             if _is_object_field(f):
                 target = ref_vo(f, root)
-                if target is not None and target.name not in seen:
+                if target is not None and target.resolution_key() not in seen:
                     queue.append(target)
     return out
 
@@ -156,30 +183,55 @@ def has_nested(vo: MetaData, root: MetaData) -> bool:
     return False
 
 
+def build_name_map(vo: MetaData, root: MetaData) -> dict[str, str]:
+    """ADR-0044 (#228) — the collision-scoped BASE name map for ``vo``'s reachable
+    nested-VO closure, keyed by ``resolution_key()``. ``vo`` itself (the PRIMARY —
+    named after the enclosing template/payload, never its own bare name) is
+    excluded from the collision domain, mirroring payload_vo_generator's
+    `_collect_nested_closure` (which seeds ``seen`` with the primary's own key for
+    the identical reason).
+
+    Reuses the SAME shared :func:`~metaobjects.codegen.collision_names.assign_nested_names`
+    pass the payload-record tier runs, so a nested VO's derived BASE here agrees
+    exactly with the payload module's own emitted class name (modulo the
+    ``Payload``/``Extracted`` suffix each tier applies on top) — the extractor's
+    imports and the payload module's declarations can never diverge."""
+    primary_key = vo.resolution_key()
+    closure: dict[str, MetaData] = {
+        cur.resolution_key(): cur
+        for cur in reachable_vos(vo, root)
+        if cur.resolution_key() != primary_key
+    }
+    return assign_nested_names(closure)
+
+
 # =============================================================================
 # Nested-aware mirror dataclasses
 # =============================================================================
 
 
 def nested_mirror_dataclasses(
-    vo: MetaData, root: MetaData, payload_mirror: str
+    vo: MetaData, root: MetaData, payload_mirror: str, name_map: dict[str, str]
 ) -> list[str]:
     """Emit the nested-aware mirror dataclass for ``vo`` and every reachable nested VO
     (deduped). The payload mirror keeps the canonical ``<Template>Extracted`` name
     (``payload_mirror``) so the existing self-contained ``extract_<name>()`` initializer
     and the delegating path share ONE mirror type. The nested mirrors carry their own
-    ``<VO>Extracted`` name. Returns source lines (blank-line separated)."""
+    ADR-0044 (#228) collision-scoped ``<Base>Extracted`` name (*name_map*, from
+    :func:`build_name_map`). Returns source lines (blank-line separated)."""
     lines: list[str] = []
     for i, cur in enumerate(reachable_vos(vo, root)):
         if i > 0:
             lines.append("")
             lines.append("")
-        name = payload_mirror if i == 0 else mirror_name(cur)
-        lines.extend(_one_mirror(cur, root, name))
+        name = payload_mirror if i == 0 else mirror_name(cur, name_map)
+        lines.extend(_one_mirror(cur, root, name, name_map))
     return lines
 
 
-def _one_mirror(vo: MetaData, root: MetaData, record_name: str) -> list[str]:
+def _one_mirror(
+    vo: MetaData, root: MetaData, record_name: str, name_map: dict[str, str]
+) -> list[str]:
     base = (
         record_name[: -len("Extracted")]
         if record_name.endswith("Extracted")
@@ -192,7 +244,8 @@ def _one_mirror(vo: MetaData, root: MetaData, record_name: str) -> list[str]:
         '    (``None`` where the value was lost or malformed)."""',
     ]
     field_lines = [
-        f"    {f.name}: {_nested_mirror_type(f, root)} = None" for f in fm.fields(vo)
+        f"    {f.name}: {_nested_mirror_type(f, root, name_map)} = None"
+        for f in fm.fields(vo)
     ]
     lines.extend(field_lines or ["    pass"])
     return lines
@@ -204,26 +257,31 @@ def _one_mirror(vo: MetaData, root: MetaData, record_name: str) -> list[str]:
 
 
 def nested_mappers(
-    vo: MetaData, root: MetaData, root_mapper_fn: str, root_mirror: str
+    vo: MetaData,
+    root: MetaData,
+    root_mapper_fn: str,
+    root_mirror: str,
+    name_map: dict[str, str],
 ) -> list[str]:
-    """Emit one ``_from_<vo>_extracted(o)`` mapper per reachable VO (payload + nested,
-    deduped). The ROOT mapper is overridden to the template-derived ``root_mapper_fn`` /
-    ``root_mirror`` so it returns the canonically-named root mirror. Returns source
-    lines (blank-line separated)."""
+    """Emit one ``_from_<base>_extracted(o)`` mapper per reachable VO (payload +
+    nested, deduped). The ROOT mapper is overridden to the template-derived
+    ``root_mapper_fn`` / ``root_mirror`` so it returns the canonically-named root
+    mirror. Nested mappers use the ADR-0044 (#228) collision-scoped *name_map* (from
+    :func:`build_name_map`). Returns source lines (blank-line separated)."""
     lines: list[str] = []
     vos = reachable_vos(vo, root)
     for i, cur in enumerate(vos):
         if i > 0:
             lines.append("")
             lines.append("")
-        fn = root_mapper_fn if i == 0 else _mapper_name(cur)
-        mir = root_mirror if i == 0 else mirror_name(cur)
-        lines.extend(_one_mapper(cur, root, fn, mir))
+        fn = root_mapper_fn if i == 0 else _mapper_name(cur, name_map)
+        mir = root_mirror if i == 0 else mirror_name(cur, name_map)
+        lines.extend(_one_mapper(cur, root, fn, mir, name_map))
     return lines
 
 
 def _one_mapper(
-    vo: MetaData, root: MetaData, fn: str, mirror: str
+    vo: MetaData, root: MetaData, fn: str, mirror: str, name_map: dict[str, str]
 ) -> list[str]:
     lines: list[str] = [
         f'def {fn}(o: object | None) -> "{mirror} | None":',
@@ -234,19 +292,19 @@ def _one_mapper(
         f"    return {mirror}(",
     ]
     for f in fm.fields(vo):
-        lines.append(f"        {f.name}={_mapper_arg(f, root)},")
+        lines.append(f"        {f.name}={_mapper_arg(f, root, name_map)},")
     lines.append("    )")
     return lines
 
 
-def _mapper_arg(field: MetaData, root: MetaData) -> str:
+def _mapper_arg(field: MetaData, root: MetaData, name_map: dict[str, str]) -> str:
     """The mirror-field initializer that reads ``field`` from the assembled object ``o``."""
     key = f'"{field.name}"'
     if _is_object_field(field):
         target = ref_vo(field, root)
         if target is None:
             return "None  # unresolved @objectRef"
-        fn = _mapper_name(target)
+        fn = _mapper_name(target, name_map)
         if fm.is_array(field):
             return f"_map_object_list(_read_prop(o, {key}), {fn})"
         return f"{fn}(_read_prop(o, {key}))"

{metaobjects-0.19.7 → metaobjects-0.19.9}/src/metaobjects/codegen/generators/extractor_generator.py

@@ -52,6 +52,7 @@ from metaobjects.meta.core.object.meta_object import MetaObject
 from metaobjects.meta.meta_data import MetaData
 from metaobjects.meta.template import template_constants as tc
 from metaobjects.shared.base_types import TYPE_TEMPLATE
+from metaobjects.shared.separators import PACKAGE_SEP
 
 _GENERATOR_NAME = "extractor-generator"
 
@@ -59,21 +60,45 @@ _GENERATOR_NAME = "extractor-generator"
 _EXTRACT_FORMATS = frozenset({tc.TEMPLATE_FORMAT_JSON, tc.TEMPLATE_FORMAT_XML})
 
 
-def _strict_class(vo: MetaData, root_vo: MetaData, template_name: str) -> str:
-    """The strict Pydantic class name for a value-object. The ROOT payload VO maps to
-    the template-named ``<Template>Payload`` (payload_vo emits the primary class under
-    the template name); every nested VO maps to ``<Vo>Payload``."""
-    if vo.name == root_vo.name:
+def _pkg_of(node: MetaData) -> str:
+    """The effective package of a node — its ``resolution_key()`` minus the
+    trailing ``::<name>`` ("" for a root-level node). Duplicated (not imported) to
+    match the existing per-generator convention. Used to derive a template's
+    referrer package for ``resolve_payload_vo`` (#228) — see that function's
+    docstring for why this ancestor-walk-aware form is used instead of the
+    loader's bare ``tpl.package or tpl.file_default_package or ""``."""
+    key = node.resolution_key()
+    i = key.rfind(PACKAGE_SEP)
+    return "" if i == -1 else key[:i]
+
+
+def _strict_class(
+    vo: MetaData, root_vo: MetaData, template_name: str, name_map: dict[str, str]
+) -> str:
+    """The strict Pydantic class name for a value-object. The ROOT payload VO
+    (matched by ``resolution_key()`` — NOT bare ``name``, so a nested VO that
+    happens to share the root's bare name across packages is never mistaken for
+    the root) maps to the template-named ``<Template>Payload`` (payload_vo emits
+    the primary class under the template name); every OTHER (nested) VO maps to
+    its ADR-0044 (#228) *name_map* base + ``Payload`` — bare when unique in the
+    payload's nested-VO closure, package-qualified on a cross-package short-name
+    collision (see :func:`~metaobjects.codegen.extract_delegate_emitter.build_name_map`,
+    which reuses the SAME naming pass ``payload_vo_generator`` runs, so this name
+    always matches the payload module's own emitted class)."""
+    if vo.resolution_key() == root_vo.resolution_key():
         return payload_class_name(template_name)
-    return payload_class_name(vo.name)
+    base = name_map.get(vo.resolution_key(), vo.name)
+    return payload_class_name(base)
 
 
-def _mapper_name(vo: MetaData) -> str:
-    """``_to_strict_<vo_snake>`` — the recursive mirror→strict mapper for a VO."""
-    return f"_to_strict_{_snake_case(vo.name)}"
+def _mapper_name(vo: MetaData, name_map: dict[str, str]) -> str:
+    """``_to_strict_<base_snake>`` — the recursive mirror→strict mapper for a VO,
+    *base* per the ADR-0044 (#228) *name_map* (see :func:`_strict_class`)."""
+    base = name_map.get(vo.resolution_key(), vo.name)
+    return f"_to_strict_{_snake_case(base)}"
 
 
-def _strict_arg(field: MetaData, root: MetaData) -> str:
+def _strict_arg(field: MetaData, root: MetaData, name_map: dict[str, str]) -> str:
     """The strict-payload initializer expression for one field, reading the mirror
     member ``m.<name>`` and mapping it onto the strict payload's exact optionality
     (``is_field_required`` — shared with payload_vo so there is no skew).
@@ -93,7 +118,7 @@ def _strict_arg(field: MetaData, root: MetaData) -> str:
         target = rde.ref_vo(field, root)
         if target is None:
             return f"m.{name}"  # unresolved @objectRef — pass the mirror value through
-        fn = _mapper_name(target)
+        fn = _mapper_name(target, name_map)
         if fm.is_array(field):
             # Required or optional array-of-objects: map present elements (drop Nones).
             return f"[{fn}(e) for e in (m.{name} or [])]" if required else (
@@ -119,11 +144,17 @@ def _strict_arg(field: MetaData, root: MetaData) -> str:
     return f"m.{name}"
 
 
-def _emit_mapper(vo: MetaData, root: MetaData, root_vo: MetaData, template_name: str) -> list[str]:
-    """One ``_to_strict_<vo>(m) -> <Strict>`` mapper, one-shot-constructing the strict
+def _emit_mapper(
+    vo: MetaData,
+    root: MetaData,
+    root_vo: MetaData,
+    template_name: str,
+    name_map: dict[str, str],
+) -> list[str]:
+    """One ``_to_strict_<base>(m) -> <Strict>`` mapper, one-shot-constructing the strict
     Pydantic model from the mirror ``m``."""
-    fn = _mapper_name(vo)
-    strict = _strict_class(vo, root_vo, template_name)
+    fn = _mapper_name(vo, name_map)
+    strict = _strict_class(vo, root_vo, template_name, name_map)
     lines: list[str] = [
         f"def {fn}(m) -> {strict}:",
         f'    """Map the all-nullable extracted mirror onto the strict ``{strict}``.',
@@ -131,7 +162,7 @@ def _emit_mapper(vo: MetaData, root: MetaData, root_vo: MetaData, template_name:
         f"    return {strict}(",
     ]
     for f in fm.fields(vo):
-        lines.append(f"        {f.name}={_strict_arg(f, root)},")
+        lines.append(f"        {f.name}={_strict_arg(f, root, name_map)},")
     lines.append("    )")
     return lines
 
@@ -154,7 +185,9 @@ def render_extractor(
     payload_ref = template.get_meta_attr(tc.TEMPLATE_ATTR_PAYLOAD_REF)  # ADR-0039: template attr resolves via extends (not origin; templates CAN extend)
     if not isinstance(payload_ref, str) or not payload_ref:
         return None
-    payload = resolve_payload_vo(root, payload_ref)
+    # ADR-0042 (#228): the referrer is THIS template — a bare @payloadRef resolves
+    # in ITS OWN package first.
+    payload = resolve_payload_vo(root, payload_ref, _pkg_of(template))
     if payload is None:
         return None
 
@@ -171,18 +204,22 @@ def render_extractor(
     extract_lenient_fn = f"extract_lenient_{snake}"
     extract_fn = f"extract_{snake}"
     root_strict = payload_class_name(template_name)
-    root_mapper = _mapper_name(payload)
 
     fqn = f"{payload.package}::{template_name}" if payload.package else template_name
 
     # The strict payload graph: root payload class (template-named) + every nested
-    # VO's ``<Vo>Payload`` (reachable through @objectRef, deduped/cycle-safe — the SAME
-    # walk payload_vo emits the nested classes for, so each import resolves).
+    # VO's ADR-0044 (#228) collision-scoped ``<Base>Payload`` (reachable through
+    # @objectRef, deduped/cycle-safe — the SAME walk + the SAME shared name-map
+    # payload_vo emits the nested classes for, so each import resolves to the exact
+    # class payload_vo_generator declared).
     vos = rde.reachable_vos(payload, root)
+    name_map = rde.build_name_map(payload, root)
+    root_mapper = _mapper_name(payload, name_map)
     strict_imports = {root_strict}
     for vo in vos:
-        if vo.name != payload.name:
-            strict_imports.add(payload_class_name(vo.name))
+        if vo.resolution_key() != payload.resolution_key():
+            base = name_map.get(vo.resolution_key(), vo.name)
+            strict_imports.add(payload_class_name(base))
 
     lines: list[str] = [
         generated_header(template_name, fqn),
@@ -233,7 +270,7 @@ def render_extractor(
         if i > 0:
             lines.append("")
             lines.append("")
-        lines.extend(emit_mapper(vo, root, payload, template_name))
+        lines.extend(emit_mapper(vo, root, payload, template_name, name_map))
 
     lines.append("")
     lines.append("")
@@ -257,12 +294,14 @@ class ExtractorGenerator:
         root: MetaData,
         root_vo: MetaData,
         template_name: str,
+        name_map: dict[str, str],
     ) -> list[str]:
-        """EXTENSION SEAM — one ``_to_strict_<vo>(m) -> <Strict>`` mirror→strict
+        """EXTENSION SEAM — one ``_to_strict_<base>(m) -> <Strict>`` mirror→strict
         mapper block. Defaults to the module-level :func:`_emit_mapper`; override to
         customize how the extracted mirror graph is mapped onto the strict Pydantic
-        payload (e.g. coercion, post-validation, default-filling)."""
-        return _emit_mapper(vo, root, root_vo, template_name)
+        payload (e.g. coercion, post-validation, default-filling). *name_map* is the
+        ADR-0044 (#228) collision-scoped name map (see :func:`_strict_class`)."""
+        return _emit_mapper(vo, root, root_vo, template_name, name_map)
 
     def _render_module(self, template: MetaData, root: MetaData) -> str | None:
         """EXTENSION SEAM — render the whole extractor module for one