feat(conformance): #37 Python — flattened kitchen-sink byte-match + effective-serialization gating

Surfaced + fixed a latent Python super-resolution divergence: a cross-package
fully-qualified `extends` (e.g. `acme::catalog::Product extends
acme::common::BaseEntity`) failed to resolve over the MERGED tree because the
FQN index keyed only on bare `fqn()` and the referrer's effective package was
derived from the threaded walk context (objects carry no own package
post-merge). Now each node captures `file_default_package` at parse time; the
super-resolve index also keys on `<file_default_package>::<name>` and the
referrer uses it as the effective package — mirroring the TS `findInTree`
matcher (own `fqn()` OR `resolutionKey()`). This eliminated four false-positive
"no primary identity" warnings (the inherited `identity.primary` from
BaseEntity was invisible) and made `expected.json` byte-match.

Wired `expected-effective.json` gating: fixture discovery detects the file,
the adapter exposes `canonical_serialize_effective` (children()/attrs() —
inherited members inlined, extends still emitted), and the runner byte-compares
(newline-normalized) when present. New serializer threads an `effective` flag.
Kitchen-sink byte-matches BOTH expected.json + expected-effective.json.

Conformance 234 passed; full Python suite 1108 passed.

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

Author: dmealing

server/python/src/metaobjects/meta/meta_data.py

@@ -17,6 +17,14 @@ def __init__(self, type_: str, sub_type: str, name: str) -> None:
         self.sub_type = sub_type
         self.name = name
         self.package: Optional[str] = None
+        # The file-default package captured at PARSE time (the package declared
+        # on the owning file's root). Distinct from ``package`` (which an object
+        # node leaves unset — the parser does not fold the file-default package
+        # onto an object's own package). Used by super-resolution to match a
+        # cross-package fully-qualified ``extends`` over the MERGED tree, where
+        # per-file root packages are no longer reachable via the parent chain.
+        # Mirrors TS ``MetaData.fileDefaultPackage`` / ``resolutionKey()``.
+        self.file_default_package: Optional[str] = None
         self.super_ref: Optional[str] = None
         self.super_data: Optional[MetaData] = None
         self.is_abstract = False

server/python/src/metaobjects/parser.py

@@ -213,6 +213,13 @@ def _build(
     node.set_source(_current_envelope(source, builder, yaml_position))
 
     pkg = body_dict.get(KEY_PACKAGE)
+    # Capture the file-default package at PARSE time so cross-package
+    # fully-qualified ``extends`` resolves over the MERGED tree (where per-file
+    # root packages are no longer reachable via the parent chain). The node's
+    # own ``package`` if declared, else the inherited context package (the
+    # file's root package). Mirrors TS ``MetaData.fileDefaultPackage``.
+    node.file_default_package = (str(pkg) if pkg else None) or (ctx_pkg or None)
+
     if pkg:
         node.package = str(pkg)
     elif type_ == TYPE_FIELD and parent_type != TYPE_OBJECT and ctx_pkg:

server/python/src/metaobjects/serializer_json.py

@@ -26,7 +26,24 @@
 
 
 def canonical_serialize(node: MetaData) -> str:
-    parsed = _to_canonical(node)
+    return _serialize(node, effective=False)
+
+
+def canonical_serialize_effective(node: MetaData) -> str:
+    """Like :func:`canonical_serialize`, but emits the EFFECTIVE tree —
+    ``children()`` + ``attrs()`` at every node (own + inherited via the super
+    chain), so the super-chain merge is materialized in the output.
+
+    Used by the conformance harness's ``expected-effective.json`` fixtures.
+    Mirrors the TS reference ``canonicalSerializeEffective``: ``extends`` is
+    still emitted on every node (the ref stays in the body), but inherited
+    members are inlined rather than referenced.
+    """
+    return _serialize(node, effective=True)
+
+
+def _serialize(node: MetaData, effective: bool) -> str:
+    parsed = _to_canonical(node, effective)
     # FR-016 / ADR-0018 — rewrite legacy @table → kind-matching alias on
     # source.rdb wrappers; run before serialization so the rewritten key sorts
     # naturally with the rest of the body (alphabetical at our depth).
@@ -35,11 +52,11 @@ def canonical_serialize(node: MetaData) -> str:
     return text + "\n"
 
 
-def _to_canonical(node: MetaData) -> dict[str, object]:
-    return {f"{node.type}{FUSED_KEY_SEP}{node.sub_type}": _body(node)}
+def _to_canonical(node: MetaData, effective: bool = False) -> dict[str, object]:
+    return {f"{node.type}{FUSED_KEY_SEP}{node.sub_type}": _body(node, effective)}
 
 
-def _body(node: MetaData) -> dict[str, object]:
+def _body(node: MetaData, effective: bool = False) -> dict[str, object]:
     body: dict[str, object] = {}
     if node.name:
         body[KEY_NAME] = node.name
@@ -52,12 +69,18 @@ def _body(node: MetaData) -> dict[str, object]:
     if node.is_array:
         body[KEY_IS_ARRAY] = True
 
-    for attr in sorted(node.own_meta_attrs(), key=lambda a: a.name):
-        body[f"{ATTR_PREFIX}{attr.name}"] = _normalize(getattr(attr, "value", None))
+    # In effective mode use attrs()/children() (own + inherited via the super
+    # chain); in own mode use own_meta_attrs()/own_children() (declared here).
+    if effective:
+        for name in sorted(node.attrs()):
+            body[f"{ATTR_PREFIX}{name}"] = _normalize(node.attrs()[name])
+    else:
+        for attr in sorted(node.own_meta_attrs(), key=lambda a: a.name):
+            body[f"{ATTR_PREFIX}{attr.name}"] = _normalize(getattr(attr, "value", None))
 
-    children = node.own_children()
+    children = node.children() if effective else node.own_children()
     if children:
-        body[KEY_CHILDREN] = [_to_canonical(c) for c in children]
+        body[KEY_CHILDREN] = [_to_canonical(c, effective) for c in children]
     return body
 
 

server/python/src/metaobjects/super_resolve.py

@@ -33,7 +33,15 @@ def _walk(
 ) -> None:
     """Visit *node* then recurse over own_children(), carrying an inherited context package."""
     if node.super_ref and node.super_data is None:
-        effective_pkg = node.package or ctx_pkg or None
+        # 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
         target = _resolve(node.super_ref, effective_pkg, index)
         if target is None:
             # FR5d / ADR-0009: emit a ResolvedSource envelope carrying the
@@ -56,7 +64,16 @@ def _walk(
 
 
 def _build_index(root: MetaData) -> dict[str, MetaData]:
-    """Build a fqn() → node index over the whole merged tree (own_children walk)."""
+    """Build a lookup index over the whole merged tree (own_children walk).
+
+    Each named node is registered under its own ``fqn()`` AND — when it has no
+    own ``package`` but a file-default package was captured at parse time —
+    under the package-folded key ``<file_default_package>::<name>``. The second
+    key is what makes a cross-package fully-qualified ``extends`` resolve over
+    the merged tree (object ``fqn()`` stays bare because the parser does not
+    fold the file-default package onto the object's own package). Mirrors the
+    TS ``findInTree`` matcher (own ``fqn()`` OR ``resolutionKey()``).
+    """
     idx: dict[str, MetaData] = {}
     _index_walk(root, idx)
     return idx
@@ -65,6 +82,9 @@ def _build_index(root: MetaData) -> dict[str, MetaData]:
 def _index_walk(node: MetaData, idx: dict[str, MetaData]) -> None:
     if node.name:
         idx.setdefault(node.fqn(), node)
+        if not node.package and node.file_default_package:
+            folded = f"{node.file_default_package}{PACKAGE_SEP}{node.name}"
+            idx.setdefault(folded, node)
     for child in node.own_children():
         _index_walk(child, idx)
 

server/python/tests/conformance/conformance_adapter.py

@@ -13,7 +13,10 @@
 from metaobjects.meta.template.meta_template import MetaTemplate
 from metaobjects.provider import Provider
 from metaobjects.registry import AttrSchema, ChildRule, TypeDefinition
-from metaobjects.serializer_json import canonical_serialize
+from metaobjects.serializer_json import (
+    canonical_serialize,
+    canonical_serialize_effective,
+)
 from metaobjects.shared.base_types import TYPE_ATTR
 from metaobjects.source.error_source import (
     CodeSource,
@@ -266,3 +269,23 @@ def load_fixture_result(
     """
     providers = _resolve_providers(provider_ids)
     return MetaDataLoader.from_directory(input_dir, providers=providers)
+
+
+def load_fixture_effective(
+    input_dir: Path,
+    provider_ids: Optional[Iterable[str]] = None,
+) -> str:
+    """Return the EFFECTIVE canonical serialization (extends resolved —
+    inherited members inlined) of the loaded fixture root.
+
+    Mirrors the TS adapter's ``canonicalSerializeEffective(tree)``. Gated by a
+    fixture's ``expected-effective.json`` (see the conformance runner). On a
+    composition failure (no tree), returns ``""`` — same shape the canonical
+    path uses, so the runner's byte-compare surfaces the mismatch.
+    """
+    providers = _resolve_providers(provider_ids)
+    result, compose_code = _load_or_capture_compose_error(input_dir, providers)
+    if compose_code is not None:
+        return ""
+    assert result is not None
+    return canonical_serialize_effective(result.root)

server/python/tests/conformance/fixture_discovery.py

@@ -17,6 +17,7 @@ class Fixture:
     input_dir: Path
     providers: tuple[str, ...]
     has_expected: bool
+    has_expected_effective: bool
     has_expected_errors: bool
     has_expected_warnings: bool
     has_script: bool
@@ -50,6 +51,7 @@ def discover_fixtures(corpus: Path) -> list[Fixture]:
                 input_dir=input_dir,
                 providers=providers,
                 has_expected=(entry / "expected.json").is_file(),
+                has_expected_effective=(entry / "expected-effective.json").is_file(),
                 has_expected_errors=(entry / "expected-errors.json").is_file(),
                 has_expected_warnings=(entry / "expected-warnings.json").is_file(),
                 has_script=(entry / "script.json").is_file(),

server/python/tests/conformance/test_conformance.py

@@ -6,7 +6,11 @@
 import pytest
 
 from .capabilities import invoke
-from .conformance_adapter import load_fixture_result, load_fixture_with_envelopes
+from .conformance_adapter import (
+    load_fixture_effective,
+    load_fixture_result,
+    load_fixture_with_envelopes,
+)
 from .corpus import corpus_root
 from .expected_failures import classify
 from .fixture_discovery import Fixture, discover_fixtures
@@ -172,6 +176,17 @@ def _run_checks(fix: Fixture) -> tuple[bool, str]:
         if want_tree != got_tree:
             failures.append("canonical serialization mismatch")
 
+    # Effective-tree check — run whenever expected-effective.json exists,
+    # matching the TS reference runner (hasExpectedEffective). Emits the
+    # EFFECTIVE canonical serialization (extends resolved — inherited members
+    # inlined) and byte-compares newline-normalized text. Asserted only when
+    # the fixture declares it.
+    if fix.has_expected_effective:
+        want_eff = (fix.dir / "expected-effective.json").read_text()
+        got_eff = load_fixture_effective(fix.input_dir, provider_ids=fix.providers)
+        if want_eff.strip() != got_eff.strip():
+            failures.append("effective serialization mismatch")
+
     if fix.has_expected_warnings:
         want_w = sorted(json.loads((fix.dir / "expected-warnings.json").read_text()))
         if want_w != sorted(warnings):

server/python/tests/unit/test_super_resolve.py

@@ -188,3 +188,40 @@ def test_resolve_over_deep_relative_ref_emits_error() -> None:
     assert len(errors) == 1
     assert errors[0].code == ErrorCode.ERR_UNRESOLVED_SUPER
     assert sub.super_data is None
+
+
+# ---------------------------------------------------------------------------
+# (h) cross-PACKAGE fully-qualified ref over a MERGED tree (#37)
+# ---------------------------------------------------------------------------
+
+def test_resolve_cross_package_fq_ref_via_file_default_package() -> None:
+    """A fully-qualified cross-package ``extends`` resolves over the merged tree.
+
+    After merge, every object lives under one root and carries NO own
+    ``package`` (the package was declared on each *file's* root). The
+    file-default package is captured at parse time as ``file_default_package``;
+    resolution must index both the bare ``fqn()`` AND the package-folded
+    ``<file_default_package>::<name>`` so an ``extends: "acme::common::Base"``
+    from a node whose file-default package is ``acme::catalog`` resolves to the
+    Base declared under file-default package ``acme::common``.
+
+    Mirrors the TS reference (``findInTree`` matching ``resolutionKey()``).
+    """
+    root = MetaRoot(TYPE_METADATA, SUBTYPE_ROOT, "")  # merged root: no package
+
+    # Base — declared in file with package acme::common; no own package post-merge.
+    base = _node("object", "entity", "Base")
+    base.file_default_package = "acme::common"
+    root.add_child(base)
+
+    # Sub — declared in file with package acme::catalog; FQ cross-package ref.
+    sub = _node("object", "entity", "Sub")
+    sub.file_default_package = "acme::catalog"
+    sub.super_ref = "acme::common::Base"
+    root.add_child(sub)
+
+    errors: list[MetaError] = []
+    resolve_supers(root, errors)
+
+    assert errors == [], f"expected no errors, got {errors}"
+    assert sub.super_data is base