metaobjects 0.15.8__tar.gz → 0.15.10__tar.gz

{metaobjects-0.15.8 → metaobjects-0.15.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metaobjects
-Version: 0.15.8
+Version: 0.15.10
 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.15.8 → metaobjects-0.15.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metaobjects"
-version = "0.15.8"
+version = "0.15.10"
 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.15.8 → metaobjects-0.15.10}/src/metaobjects/codegen/generators/render_helper_generator.py

@@ -26,10 +26,10 @@ build fail when a mustache references a field the payload VO doesn't declare.
 Reuse, not reimplementation: ``render`` (the emitted runtime call), ``verify`` (the
 build-time gate), ``FilesystemProvider`` (build-time ref resolution), and
 ``EmailDocument`` (email return type). The payload field tree is walked from the VO
-the same way the other generators walk it — but a nested ``field.object``'s
-``@objectRef`` is resolved by BARE short-name (cross-port render-helper consensus:
-TS ``findObject`` / Java ``resolveNestedObjectRef`` / C# ``ResolveNestedObjectRef``),
-only recursing into ``object.value`` targets, cycle-guarded.
+the same way the other generators walk it — a nested ``field.object``'s ``@objectRef``
+is resolved FQN-exact when fully-qualified (ADR-0041) else by short name (cross-port
+render-helper consensus: TS ``refMatchesObject`` / Java+Kotlin ``resolveNestedObjectRef``
+/ C# ``ResolveNestedObjectRef``), only recursing into ``object.value`` targets, cycle-guarded.
 
 Python divergence vs TS / Java / C#: Python's ``RenderRequest`` has NO ``verify``
 field — the Python render engine does not run a runtime drift pass — so the emitted
@@ -75,19 +75,24 @@ def _py_str(s: str) -> str:
 
 
 # ---------------------------------------------------------------------------
-# Payload field-tree walk — nested @objectRef resolved by BARE short-name
-# (cross-port render-helper consensus). Object-ref fields recurse into their
-# target object.value (SUBTYPE_VALUE only); a `seen` set guards reference cycles.
+# Payload field-tree walk — nested @objectRef resolved FQN-exact (ADR-0041).
+# Object-ref fields recurse into their target object.value (SUBTYPE_VALUE only);
+# a `seen` set guards reference cycles.
 # ---------------------------------------------------------------------------
 
 
 def _resolve_nested_object_ref(root: MetaData, reference: str) -> MetaObject | None:
-    """Resolve a ``field.object``'s ``@objectRef`` to its target ``object.value`` by BARE
-    short-name — mirroring the C# ``ResolveNestedObjectRef`` / TS ``findObject`` / Java
-    ``resolveNestedObjectRef``. If the ref carries a package, only the segment after the
-    last ``::`` is compared, against each ``object.value``'s own short name."""
+    """Resolve a ``field.object``'s ``@objectRef`` to its target ``object.value``.
+
+    ADR-0041: a FULLY-QUALIFIED ref (contains ``::``) resolves EXACTLY on the
+    package-qualified name (``resolution_key()``/``fqn()``) — never a bare-tail
+    fallback that would bind a same-named ``object.value`` in the WRONG package on a
+    cross-package short-name collision. A bare ref still matches by short name
+    (first-wins). Mirrors the Java/Kotlin ``resolveNestedObjectRef`` + TS
+    ``refMatchesObject``."""
     if not reference:
         return None
+    fqn = PACKAGE_SEP in reference
     ref_short = reference.rsplit(PACKAGE_SEP, 1)[-1]
     # ADR-0039 sanctioned own: top-level scan on the loader ROOT (never extended, own == effective)
     for child in root.own_children():
@@ -95,7 +100,10 @@ def _resolve_nested_object_ref(root: MetaData, reference: str) -> MetaObject | N
             continue
         if child.sub_type != OBJECT_SUBTYPE_VALUE:
             continue
-        if child.name.rsplit(PACKAGE_SEP, 1)[-1] == ref_short:
+        if fqn:
+            if child.resolution_key() == reference or child.fqn() == reference:
+                return child
+        elif child.name.rsplit(PACKAGE_SEP, 1)[-1] == ref_short:
             return child
     return None
 
@@ -107,9 +115,9 @@ def _derive_payload_field_tree(
     resolvable ``@objectRef`` to an ``object.value`` becomes a context-pushing node whose
     children are the target VO's tree (recursed, cycle-guarded). Every other field is a
     leaf."""
-    if vo is None or vo.name in seen:
+    if vo is None or vo.resolution_key() in seen:
         return []
-    next_seen = seen | {vo.name}
+    next_seen = seen | {vo.resolution_key()}
     fields: list[PayloadField] = []
     for f in vo.children():
         if f.type != TYPE_FIELD or not isinstance(f, MetaField):

{metaobjects-0.15.8 → metaobjects-0.15.10}/src/metaobjects/core_types.py

@@ -35,7 +35,6 @@ from .meta.core.field.field_constants import (
 )
 from .meta.core.field.meta_field import MetaField
 from .meta.persistence.db.db_constants import (
-    FIELD_ATTR_DB_COLUMN_TYPE,
     FIELD_ATTR_DB_INDEXED,
 )
 from .meta.core.identity.identity_constants import (
@@ -49,7 +48,7 @@ from .meta.core.identity.identity_constants import (
     IDENTITY_SUBTYPE_SECONDARY,
 )
 from .meta.core.identity.meta_identity import MetaIdentity
-from .meta.core.index.index_constants import INDEX_ATTR_FIELDS, INDEX_SUBTYPE_LOOKUP, INDEX_SUBTYPES
+from .meta.core.index.index_constants import INDEX_ATTR_FIELDS, INDEX_SUBTYPES
 from .meta.core.index.meta_index import MetaIndex
 from .meta.core.object.meta_object import MetaObject
 from .meta.core.object.object_constants import (
@@ -57,7 +56,6 @@ from .meta.core.object.object_constants import (
     OBJECT_ATTR_DISCRIMINATOR_VALUE,
     OBJECT_SUBTYPE_ENTITY,
     OBJECT_SUBTYPE_PROJECTION,
-    OBJECT_SUBTYPE_VALUE,
     OBJECT_SUBTYPES,
 )
 from .meta.core.relationship.meta_relationship import MetaRelationship
@@ -77,6 +75,7 @@ from .meta.meta_root import MetaRoot
 from .meta.persistence.origin.meta_origin import MetaOrigin
 from .meta.persistence.origin.origin_constants import (
     ORIGIN_ATTR_AGG,
+    ORIGIN_ATTR_CONVERT,
     ORIGIN_ATTR_FROM,
     ORIGIN_ATTR_OF,
     ORIGIN_ATTR_VIA,
@@ -595,7 +594,7 @@ core_provider.add(
     )
 )
 
-# origin.passthrough — @from required, @via optional
+# origin.passthrough — @from required, @via optional, @convert optional (#185).
 core_provider.add(
     TypeDefinition(
         type=TYPE_ORIGIN,
@@ -604,6 +603,8 @@ core_provider.add(
         attrs=[
             AttrSchema(name=ORIGIN_ATTR_FROM, value_type=ATTR_SUBTYPE_STRING, required=True),
             AttrSchema(name=ORIGIN_ATTR_VIA, value_type=ATTR_SUBTYPE_STRING, required=False),
+            # #185 — opt out of the type-preserving ERR_PASSTHROUGH_TYPE_MISMATCH check.
+            AttrSchema(name=ORIGIN_ATTR_CONVERT, value_type=ATTR_SUBTYPE_BOOLEAN, required=False),
         ],
         child_rules=[ChildRule(TYPE_ATTR, "*")],
     )

{metaobjects-0.15.8 → metaobjects-0.15.10}/src/metaobjects/errors.py

@@ -102,7 +102,13 @@ class ErrorCode(str, Enum):
     ERR_PARAMETER_REF_UNRESOLVED = "ERR_PARAMETER_REF_UNRESOLVED"
     ERR_PARAMETER_REF_NOT_VALUE_OBJECT = "ERR_PARAMETER_REF_NOT_VALUE_OBJECT"
     ERR_PARAMETER_REF_ON_NON_CALLABLE_KIND = "ERR_PARAMETER_REF_ON_NON_CALLABLE_KIND"
-    ERR_PARAMETER_REF_PASSTHROUGH_TYPE_MISMATCH = "ERR_PARAMETER_REF_PASSTHROUGH_TYPE_MISMATCH"
+    # #185 — a field forwarding another field's value via origin.passthrough must
+    # declare the SAME field.<subType> and array-ness as its resolved @from source
+    # (a passthrough forwards the value unchanged). A differing subType or array-ness
+    # → this error, unless @convert: true acknowledges a deliberate type change. This
+    # GENERALIZES and RETIRES the FR-015-narrow ERR_PARAMETER_REF_PASSTHROUGH_TYPE_
+    # MISMATCH (the origin-paths pass runs over every object, value hosts included).
+    ERR_PASSTHROUGH_TYPE_MISMATCH = "ERR_PASSTHROUGH_TYPE_MISMATCH"
     # FR-014 — TPH discriminator cross-attribute validation. Cross-language
     # vocabulary; Python loader does not emit these yet.
     ERR_DISCRIMINATOR_FIELD_NOT_FOUND = "ERR_DISCRIMINATOR_FIELD_NOT_FOUND"

{metaobjects-0.15.8 → metaobjects-0.15.10}/src/metaobjects/loader/validate_source_parameter_ref.py

@@ -8,9 +8,13 @@ Codes:
       object.
     * ``ERR_PARAMETER_REF_NOT_VALUE_OBJECT`` — ``@parameterRef`` points at an
       object that is not an ``object.value``.
-    * ``ERR_PARAMETER_REF_PASSTHROUGH_TYPE_MISMATCH`` — a parameter field uses
-      ``origin.passthrough @from: "Entity.field"`` but its subtype does not match
-      the referenced field's subtype.
+
+Note (#185): the parameter-field passthrough type-match check formerly emitted
+here (``ERR_PARAMETER_REF_PASSTHROUGH_TYPE_MISMATCH``) is RETIRED. It is subsumed
+by the universal ``ERR_PASSTHROUGH_TYPE_MISMATCH`` in ``validation_passes.py``,
+whose origin-paths pass runs over every object — value hosts (parameter shapes)
+included — so a parameter field's ``origin.passthrough`` type mismatch is now
+caught there (with the ``@convert: true`` opt-out).
 
 Mirrors the TS reference
 ``packages/metadata/src/persistence/source/validate-source-parameter-ref.ts``.
@@ -30,11 +34,7 @@ from ..meta.core.object.object_constants import (
     OBJECT_SUBTYPE_ENTITY,
     OBJECT_SUBTYPE_VALUE,
 )
-from ..meta.persistence.origin.origin_constants import (
-    ORIGIN_ATTR_FROM,
-    ORIGIN_SUBTYPE_PASSTHROUGH,
-)
-from ..shared.base_types import TYPE_FIELD, TYPE_OBJECT, TYPE_ORIGIN, TYPE_SOURCE
+from ..shared.base_types import TYPE_OBJECT, TYPE_SOURCE
 from ..shared.separators import PACKAGE_SEP
 
 _CALLABLE_KINDS = frozenset({SOURCE_KIND_STORED_PROC, SOURCE_KIND_TABLE_FUNCTION})
@@ -122,60 +122,7 @@ def validate_source_parameter_ref(root: MetaData, errors: list[MetaError]) -> No
                 )
                 continue
 
-            # ERR_PARAMETER_REF_PASSTHROUGH_TYPE_MISMATCH — each parameter field
-            # with origin.passthrough must match the referenced field's subtype.
-            # ADR-0039: resolving — the parameter value-object's fields may be
-            # inherited via extends (mirrors the TS `target.children()` —
-            # validate-source-parameter-ref.ts:122).
-            for param_field in target.children():
-                if param_field.type != TYPE_FIELD:
-                    continue
-                # ADR-0039 own: origin.* never inherits (ADR-0029); the origin child
-                # is read own (mirrors the TS `paramField.ownChildren()`).
-                passthrough = next(
-                    (
-                        c
-                        for c in param_field.own_children()
-                        if c.type == TYPE_ORIGIN
-                        and c.sub_type == ORIGIN_SUBTYPE_PASSTHROUGH
-                    ),
-                    None,
-                )
-                if passthrough is None:
-                    continue
-                frm = passthrough.attr(ORIGIN_ATTR_FROM)  # ADR-0039 sanctioned own: origin.* never inherits (ADR-0029)
-                if not isinstance(frm, str) or frm == "":
-                    continue
-                dot = frm.find(".")
-                if dot < 0:
-                    continue
-                target_entity_name = frm[:dot]
-                target_field_name = frm[dot + 1:]
-                target_entity = object_index.get(target_entity_name)
-                if target_entity is None:
-                    continue  # origin-paths pass surfaces this
-                # ADR-0039: resolving — the referenced entity's field may be
-                # inherited via extends (mirrors the TS `targetEntity.children()` —
-                # validate-source-parameter-ref.ts:139).
-                target_field = next(
-                    (
-                        c
-                        for c in target_entity.children()
-                        if c.type == TYPE_FIELD and c.name == target_field_name
-                    ),
-                    None,
-                )
-                if target_field is None:
-                    continue
-                if param_field.sub_type != target_field.sub_type:
-                    errors.append(
-                        MetaError(
-                            f'parameter field "{param_field.name}" '
-                            f"(field.{param_field.sub_type}) on @parameterRef "
-                            f'"{ref}" uses origin.passthrough @from: "{frm}", but '
-                            f"{target_entity.name}.{target_field_name} is "
-                            f"field.{target_field.sub_type}; types must match",
-                            ErrorCode.ERR_PARAMETER_REF_PASSTHROUGH_TYPE_MISMATCH,
-                            envelope=param_field.source,
-                        )
-                    )
+            # #185 — the parameter-field passthrough type-match check formerly here
+            # (ERR_PARAMETER_REF_PASSTHROUGH_TYPE_MISMATCH) is RETIRED; the universal
+            # ERR_PASSTHROUGH_TYPE_MISMATCH in validation_passes.py now covers it
+            # (its origin-paths pass runs over every object, value hosts included).

{metaobjects-0.15.8 → metaobjects-0.15.10}/src/metaobjects/loader/validation_passes.py

@@ -78,6 +78,7 @@ from ..meta.presentation.layout.layout_constants import (
     LAYOUT_SUBTYPE_DATA_GRID,
 )
 from ..meta.persistence.origin.origin_constants import (
+    ORIGIN_ATTR_CONVERT,
     ORIGIN_ATTR_FROM,
     ORIGIN_ATTR_OF,
     ORIGIN_ATTR_VIA,
@@ -94,7 +95,6 @@ from ..meta.core.relationship.relationship_constants import (
     RELATIONSHIP_ATTR_THROUGH,
 )
 from ..meta.core.identity.identity_constants import (
-    IDENTITY_SUBTYPE_PRIMARY,
     IDENTITY_SUBTYPE_REFERENCE,
     IDENTITY_REFERENCE_ATTR_REFERENCES,
 )
@@ -1476,6 +1476,54 @@ def _check_extends_origin_agreement(
     )
 
 
+def _check_passthrough_type(
+    field: MetaData,
+    from_field: MetaData,
+    from_attr: str,
+    convert: bool,
+    obj: MetaData,
+    origin_source: object,
+    referrer: str,
+    errors: list[MetaError],
+) -> None:
+    """#185 — a passthrough is type-preserving. A field forwarding another field's
+    value via origin.passthrough must declare the SAME field.<subType> and the same
+    array-ness as its resolved @from source — otherwise the projected type silently
+    diverges from its source (e.g. a field.uuid surfaced as field.string, forcing
+    hand-written String<->UUID bridging).
+
+    Compares the RESOLVING/effective subType + isArray (ADR-0039), so a field
+    inheriting its shape via ``extends`` is judged on its effective type. Nullability
+    is deliberately NOT judged: a view over an outer join legitimately widens a NOT
+    NULL source column to nullable.
+
+    Escape hatch: ``@convert: true`` on the origin.passthrough acknowledges a
+    deliberate type change and suppresses the error (it does NOT emit a cast — the
+    consumer owns any coercion; real converting projections are #159's
+    origin.expression). Host-agnostic (projections, entities, values, and the
+    FR-015 stored-proc parameter refs the retired ERR_PARAMETER_REF_PASSTHROUGH_
+    TYPE_MISMATCH used to cover). Mirrors the TS reference ``_checkPassthroughType``.
+    """
+    if convert:
+        return  # deliberate type change acknowledged
+    # Compare both axes at once via the type-label: subtype names never contain
+    # "[]", so equal labels <=> same subType AND same array-ness.
+    declared = f"field.{field.sub_type}{'[]' if field.resolved_is_array() else ''}"
+    source = f"field.{from_field.sub_type}{'[]' if from_field.resolved_is_array() else ''}"
+    if declared == source:
+        return
+    errors.append(
+        MetaError(
+            f"origin.passthrough on {obj.name}.{field.name}: field is {declared} but its "
+            f"@from source '{from_attr}' is {source} — a passthrough forwards the value "
+            f"unchanged, so the types must match. Declare {source}, or set @convert: true "
+            f"to acknowledge a deliberate type change.",
+            ErrorCode.ERR_PASSTHROUGH_TYPE_MISMATCH,
+            envelope=resolved_source(origin_source, referrer, from_attr),
+        )
+    )
+
+
 def _validate_origin_paths(
     root: MetaData,
     errors: list[MetaError],
@@ -1533,6 +1581,12 @@ def _validate_origin_paths(
                     _check_extends_origin_agreement(
                         node, from_target[1], from_ref, obj, origin.source, referrer, errors
                     )
+                    # #185 — passthrough is type-preserving unless @convert acknowledges
+                    # a change. ADR-0039 sanctioned own: origin.* never inherits (ADR-0029).
+                    convert = origin.attr(ORIGIN_ATTR_CONVERT) is True
+                    _check_passthrough_type(
+                        node, from_target[1], from_ref, convert, obj, origin.source, referrer, errors
+                    )
                 via = origin.attr(ORIGIN_ATTR_VIA)
                 if isinstance(via, str) and via:
                     hops = _validate_via_path(via, ctx, object_index, errors, origin, referrer)

{metaobjects-0.15.8 → metaobjects-0.15.10}/src/metaobjects/meta/persistence/origin/origin_constants.py

@@ -14,6 +14,10 @@ ORIGIN_SUBTYPES = (
 # passthrough attrs
 ORIGIN_ATTR_FROM = "from"
 ORIGIN_ATTR_VIA = "via"
+# #185 — acknowledges a deliberate type change on origin.passthrough (opt out of
+# the type-preserving ERR_PASSTHROUGH_TYPE_MISMATCH check). Mirrors the TS
+# ORIGIN_PASSTHROUGH_ATTR_CONVERT.
+ORIGIN_ATTR_CONVERT = "convert"
 
 # aggregate attrs
 ORIGIN_ATTR_AGG = "agg"

{metaobjects-0.15.8 → metaobjects-0.15.10}/src/metaobjects/runtime/object_manager.py

@@ -27,6 +27,7 @@ from __future__ import annotations
 
 import datetime as _dt
 import decimal as _decimal
+import json as _json
 import uuid as _uuid
 from collections.abc import Iterable
 from typing import Any, Protocol
@@ -693,9 +694,24 @@ def _coerce_write_value(field: MetaField, value: Any) -> Any:
         is_tz = field.get_meta_attr(dbc.FIELD_ATTR_LOCAL_TIME) is not True  # ADR-0039 resolving: @localTime may be inherited
         return _parse_datetime(str(value), tz_aware=is_tz)
 
-    # field.object (jsonb storage): a dict/list passes through — pg8000 binds it
-    # to the jsonb column natively (no manual JSON.stringify, unlike node-pg).
-    # A field.string pinned to a jsonb column behaves the same way.
+    # field.object / field.map stored as a single jsonb column: serialize to a
+    # JSON text string so pg8000 sends it as jsonb text (PG assignment-casts text
+    # → jsonb). pg8000 binds a native *dict* to jsonb natively, but a native
+    # *list* (array-of-VO, isArray:true) it adapts as a Postgres ARRAY literal
+    # `{...,...}` which the JSONB column rejects with 22P02 'invalid input syntax
+    # for type json' — so we cannot rely on driver magic for the list form.
+    # Serializing both shapes to a JSON string is the explicit codec every other
+    # port has (Java/Gson, C#/System.Text.Json, TS/JSON.stringify, Kotlin/Jackson)
+    # and handles dict (single VO), list (array-of-VO), and [] uniformly.
+    #
+    # Scope: only jsonb-storage field.object/field.map. A *flattened* field.object
+    # is expanded to separate scalar columns (never reaches here as the object
+    # node) and must not be touched; a field.string pinned to a jsonb column via
+    # @dbColumnType already carries a string value and is left alone above.
+    if sub in (fc.FIELD_SUBTYPE_OBJECT, fc.FIELD_SUBTYPE_MAP):
+        storage = field.get_meta_attr(fc.FIELD_ATTR_STORAGE)  # ADR-0039 resolving
+        if storage != "flattened":  # None / "jsonb" / "subdocument" → single jsonb column
+            return _json.dumps(value)
     # Everything else (string / int / long / double / float / boolean / enum)
     # is already the native type pg8000 binds directly.
     return value

{metaobjects-0.15.8 → metaobjects-0.15.10}/src/metaobjects/spec_metamodel/origin.json

@@ -13,7 +13,8 @@
       "whenToUse": "A projection field just surfaces a field from a related entity. Declare the cross-entity passthrough instead of re-joining and re-selecting it by hand.",
       "children": [
         { "type": "attr", "subType": "string", "name": "from", "min": 1, "max": 1, "description": "Dotted Entity.field reference identifying the source value this projection field passes through (e.g. 'Program.title')." },
-        { "type": "attr", "subType": "string", "name": "via", "min": 0, "max": 1, "description": "Optional dotted relationship path used to reach the source entity (e.g. 'Program.weeks')." }
+        { "type": "attr", "subType": "string", "name": "via", "min": 0, "max": 1, "description": "Optional dotted relationship path used to reach the source entity (e.g. 'Program.weeks')." },
+        { "type": "attr", "subType": "boolean", "name": "convert", "min": 0, "max": 1, "description": "Acknowledges that this field's declared type deliberately differs from its @from source field's type (#185). Absent/false (the default), a passthrough is type-preserving — a differing field.<subType> or array-ness fails with ERR_PASSTHROUGH_TYPE_MISMATCH. Set true to opt out. This is an acknowledgement only: it does NOT generate a cast — the value flows through unchanged and the consumer owns any coercion. Real type-converting projections are origin.expression's job (#159)." }
       ]
     },
     {

{metaobjects-0.15.8 → metaobjects-0.15.10}/src/metaobjects/super_resolve.py

@@ -1,10 +1,11 @@
 """Deferred super/extends resolution over the merged tree (2nd pass, pre-freeze).
 
 Mirrors TS ``resolveDeferredSupers`` in super-resolve.ts:
-- Walk the tree over own_children(), tracking an inherited context package.
-- Build the FQN index keyed by node.fqn() (own).
-- For each node with an unresolved super_ref, resolve using
-  ``effective_pkg = node.package or inherited_context_pkg``.
+- Build the FQN index keyed by node.fqn() (own), over the whole merged tree.
+- Collect every node carrying an unresolved super_ref, tracking each node's
+  inherited context package.
+- Resolve supers ON DEMAND with memoization + cycle detection (#188), NOT in a
+  single physical-declaration-order pass — so resolution is order-independent.
 """
 from __future__ import annotations
 
@@ -15,34 +16,78 @@ from .source import resolved_source
 
 
 def resolve_supers(root: MetaData, errors: list[MetaError]) -> None:
-    """Walk every node in the merged tree; for each unresolved super_ref, resolve it.
+    """Resolve every unresolved super_ref in the merged tree, order-independently.
 
     Resolved → sets node.super_data.
     Unresolved → appends ERR_UNRESOLVED_SUPER to errors.
+    Dotted target type/subtype mismatch → appends ERR_EXTENDS_TARGET_MISMATCH.
     Already-resolved nodes (super_data is not None) are skipped (idempotent).
+
+    #188: super-resolution must be ORDER-INDEPENDENT. A pre-order walk resolved
+    each node's super_ref in physical-declaration (= load) order, so a dotted ref
+    to an INHERITED member (``extends: Owner.member`` where Owner inherits
+    ``member`` via its OWN ``extends``) only succeeded when the owner's extends
+    chain happened to be wired first — green under one readdir order, throwing
+    ERR_UNRESOLVED_SUPER under another. Instead resolve ON DEMAND with
+    memoization + cycle detection: before a dotted ref reads ``owner.children()``
+    (EFFECTIVE children — inherited members appear only once the owner's OWN
+    super is resolved), resolve the owner's whole chain first. The result is a
+    pure function of the source SET, independent of enumeration order. Mirrors
+    the TS reference (#188).
     """
     index = _build_index(root)
-    _walk(root, "", index, errors)
 
+    # Every node carrying a super_ref, over the PHYSICAL declaration tree, with
+    # the inherited context package captured at that node's walk position (the
+    # effective_pkg the original pre-order walk computed — kept byte-identical so
+    # every existing fixture resolves the same way).
+    pending: list[MetaData] = []
+    pkg_of: dict[MetaData, str | None] = {}
+    _collect(root, "", pending, pkg_of)
 
-def _walk(
-    node: MetaData,
-    ctx_pkg: str,
-    index: dict[str, MetaData],
-    errors: list[MetaError],
-) -> None:
-    """Visit *node* then recurse over own_children(), carrying an inherited context package."""
-    if node.super_ref and node.super_data is None:
+    # Nodes already attempted this pass. On-demand resolution can reach a node
+    # via the ``pending`` loop AND via owner/target recursion — ``attempted``
+    # makes each node resolve (and, on failure, report) EXACTLY ONCE, restoring
+    # the single-visit walk's no-duplicate-failures guarantee (a successful node
+    # is deduped by ``super_data``; this also covers the FAILURE path, which
+    # sets no marker). It is also the cycle guard: ``attempted`` is never
+    # removed, so a genuine super cycle (A→B→A) terminates on re-entry to the
+    # already-attempted node rather than recursing forever. Mirrors the TS
+    # reference (#188).
+    attempted: set[MetaData] = set()
+
+    def resolve_node(node: MetaData) -> None:
+        if not node.super_ref or node.super_data is not None:
+            return
+        if node in attempted:
+            return  # already resolved-or-failed this pass — never re-report
+        attempted.add(node)
         # Referrer context package: own ``package`` if declared, else the
-        # file-default package captured at parse time, else the inherited
-        # walk context. Using file_default_package (not just the threaded
-        # ctx_pkg) is what lets a bare / same-package / cross-package
-        # ``extends`` resolve over the MERGED tree, where object nodes carry
-        # no own package and the parent chain no longer reaches the per-file
-        # root. Mirrors TS ``resolveDeferredSupers``
-        # (``node.package ?? node.fileDefaultPackage``).
-        effective_pkg = node.package or node.file_default_package or ctx_pkg or None
+        # file-default package captured at parse time, else the inherited walk
+        # context. Captured during _collect (mirrors the original ``_walk``
+        # effective_pkg). Using file_default_package (not just the threaded
+        # ctx_pkg) is what lets a bare / same-package / cross-package ``extends``
+        # resolve over the MERGED tree.
+        effective_pkg = pkg_of[node] if node in pkg_of else (
+            node.package or node.file_default_package or None
+        )
+
+        # For a dotted child-targeting ref, ``_resolve`` reads the OWNER's
+        # effective ``children()`` — which only includes inherited members once
+        # the owner's own extends chain is resolved. So resolve the owner node's
+        # chain FIRST (memoized), regardless of load order (#188).
+        if _is_child_targeting_ref(node.super_ref):
+            owner_ref = _owner_ref(node.super_ref)
+            if owner_ref is not None:
+                owner = _resolve(owner_ref, effective_pkg, index)
+                if owner is not None:
+                    resolve_node(owner)
+
+        # FR-024: thread the referrer's type so dotted ``Entity.child`` refs
+        # resolve type-scoped (a field ref selects fields; an identity ref
+        # identities).
         target = _resolve(node.super_ref, effective_pkg, index, referrer_type=node.type)
+
         if target is None:
             # FR5d / ADR-0009: emit a ResolvedSource envelope carrying the
             # referrer's files / json_path plus the referrer FQN + unresolved
@@ -71,13 +116,43 @@ def _walk(
             ))
         else:
             node.super_data = target
+            # Ensure the target's OWN chain is resolved too, so a later
+            # ``children()`` read on *node* (codegen/validation) sees the full
+            # multi-level inherited set (e.g. Base extends AbstractRoot).
+            # Memoized — no re-work.
+            resolve_node(target)
+
+    for node in pending:
+        resolve_node(node)
+
+
+def _collect(
+    node: MetaData,
+    ctx_pkg: str,
+    pending: list[MetaData],
+    pkg_of: dict[MetaData, str | None],
+) -> None:
+    """Pre-order walk: record every node carrying a super_ref plus the effective
+    context package at its walk position, then recurse over own_children().
+
+    Mirrors the referrer-context computation of the original ``_walk`` so the
+    on-demand resolver uses exactly the same effective_pkg the pre-order walk
+    did — resolution stays byte-identical for every existing fixture; only the
+    ORDER in which supers are wired changes (now order-independent, #188).
+    """
+    if node.super_ref:
+        # own ``package`` if declared, else the file-default package captured at
+        # parse time, else the inherited walk context.
+        pkg_of[node] = node.package or node.file_default_package or ctx_pkg or None
+        pending.append(node)
 
     # The context package for children is this node's own package, if set, else inherit.
     next_ctx = node.package or ctx_pkg
-    # ADR-0039 sanctioned own: this IS the super-resolution walk — it runs BEFORE
-    # extends is resolved (it sets super_data), so it must iterate own children.
+    # ADR-0039 sanctioned own: this IS the super-resolution collection walk — it
+    # runs BEFORE extends is resolved (resolution sets super_data), so it must
+    # iterate own children.
     for child in node.own_children():
-        _walk(child, next_ctx, index, errors)
+        _collect(child, next_ctx, pending, pkg_of)
 
 
 def _build_index(root: MetaData) -> dict[str, MetaData]:
@@ -118,6 +193,20 @@ def _is_child_targeting_ref(ref: str) -> bool:
     return "." in last_segment
 
 
+def _owner_ref(ref: str) -> str | None:
+    """The OWNER portion of a dotted child-targeting ref (``Owner.child`` →
+    ``Owner``, ``pkg::Owner.child.grandchild`` → ``pkg::Owner``): the package
+    prefix plus the first dotted segment. ``None`` for a degenerate ref (fewer
+    than two segments or any empty segment). Mirrors the TS
+    ``parseChildTargetingRef().ownerRef``."""
+    last_sep = ref.rfind(PACKAGE_SEP)
+    seg_start = 0 if last_sep < 0 else last_sep + len(PACKAGE_SEP)
+    parts = ref[seg_start:].split(".")
+    if len(parts) < 2 or any(not p for p in parts):
+        return None
+    return ref[:seg_start] + parts[0]
+
+
 def _resolve(
     ref: str,
     context_pkg: str | None,

{metaobjects-0.15.8 → metaobjects-0.15.10}/tests/codegen/test_render_helper_conformance.py

@@ -27,7 +27,7 @@ from pathlib import Path
 import pytest
 
 import metaobjects.core_types  # noqa: F401  — side-effect: registers attr classes
-from metaobjects import MetaDataLoader
+from metaobjects import InMemoryStringSource, MetaDataLoader
 from metaobjects.codegen.config import GenConfig
 from metaobjects.codegen.generator import GenContext
 from metaobjects.codegen.generators.render_helper_generator import RenderHelperGenerator
@@ -45,6 +45,15 @@ def _load_root(meta_json: Path):
     return res.root
 
 
+def _load_root_from_files(*meta_jsons: Path):
+    # Multi-file (multi-package) load — one InMemoryStringSource per file, merged into a
+    # single root (mirrors fixtures/conformance/loader-same-name-distinct-packages).
+    sources = [InMemoryStringSource(p.read_text()) for p in meta_jsons]
+    res = MetaDataLoader().load(sources)
+    assert res.errors == [], res.errors
+    return res.root
+
+
 def _ctx(root) -> GenContext:
     return GenContext(
         entities=[],
@@ -156,6 +165,35 @@ def test_email_order_email_renders_nested_array_loop_and_partial(tmp_path) -> No
     assert "<hr/>Sent by Acme" in doc.html_body
 
 
+# ---------------------------------------------------------------------------
+# xpkg-collision/ — cross-package short-name collision (ADR-0041). Two packages
+# each declare an object.value `Note` (alpha: alphaText, beta: betaText); the
+# payload `Digest` references BOTH by FULLY-QUALIFIED @objectRef. A bare-tail
+# resolver binds both refs to whichever Note loads first → one field lands on the
+# wrong element type → the drift gate raises. FQN-exact resolution renders both.
+# ---------------------------------------------------------------------------
+
+
+def test_document_digest_doc_resolves_fqn_nested_object_ref_across_collision(tmp_path) -> None:
+    dir_root = CORPUS / "xpkg-collision"
+    root = _load_root_from_files(
+        dir_root / "meta.alpha.json",
+        dir_root / "meta.beta.json",
+        dir_root / "meta.app.json",
+    )
+    templates = str(CORPUS / "templates")
+    # Must NOT raise: the FQN refs resolve to their own package's Note.
+    files = [f for f in RenderHelperGenerator(templates).generate(_ctx(root))
+             if f.path == "digest_doc_render_helper.py"]
+    assert len(files) == 1
+    _materialize_and_import(files, tmp_path)
+    helper = import_module("_rh_conf_pkg.digest_doc_render_helper")
+
+    payload = {"fromAlpha": {"alphaText": "AA"}, "fromBeta": {"betaText": "BB"}}
+    out = helper.render_digest_doc(payload, FilesystemProvider(templates))
+    assert out == "Alpha=AA Beta=BB"
+
+
 # ---------------------------------------------------------------------------
 # drift/ → codegen FAILS (ValueError) with ERR_VAR_NOT_ON_PAYLOAD.
 # ---------------------------------------------------------------------------

{metaobjects-0.15.8 → metaobjects-0.15.10}/uv.lock

@@ -250,7 +250,7 @@ wheels = [
 
 [[package]]
 name = "metaobjects"
-version = "0.15.6"
+version = "0.15.9"
 source = { editable = "." }
 dependencies = [
     { name = "pyyaml" },