fix(loader): package-qualify root-level same-name merge matching (TS/C#/Python) (#156)

Two files declaring the same (type, name) at root level under DIFFERENT
packages were silently treated as one node by the TS, C#, and Python
loaders: the merge lookup keyed on bare (type, name) only. Identical
twins merged silently; twins differing in an @attr (e.g. @objectref
pointing at each package's own nested view) failed the load with
ERR_MERGE_CONFLICT. The Java parser is the gold standard here — it
searches root children by "pkg::name" — so a downstream consumer's
metadata that loads fine on the JVM failed in the Node CLI.

Root-level merge lookups now compare the package-qualified identity
(own package, expanded against the file context, else the file-default
package) on both sides — mirroring Java. Nested children stay bare-name
matched: they are scoped by their parent, and packages don't
disambiguate siblings inside a node. Same-package cross-file overlay
merging is unchanged.

New cross-port conformance fixture loader-same-name-distinct-packages
covers both twin shapes (identical bodies + differing @objectref);
expected.json generated by the TS reference implementation, Java passes
it unchanged.

Co-authored-by: Doug Mealing <noreply@anthropic.com>

Author: dmealing

CHANGELOG.md

@@ -7,6 +7,9 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Fixed
+- **Loader — root-level same-name nodes in different packages were wrongly merged (TS/C#/Python).** Two files declaring the same (type, name) at root level under different packages collapsed into one node: identical twins merged silently, and twins differing in an `@attr` (e.g. each package's `@objectRef` pointing at its own nested view) failed the load with `ERR_MERGE_CONFLICT`. Root-level merge matching now compares the package-qualified identity (own `package` else the file-default package) — mirroring the Java parser, which was already correct. Nested children stay bare-name matched; same-package cross-file overlay merging unchanged. New cross-port conformance fixture `loader-same-name-distinct-packages` (Java passes it unchanged). (#155)
+
 ## [0.15.3] — 2026-07-03
 
 _npm `0.15.3` (full lockstep across all 13 `@metaobjectsdev/*` publish candidates)._

fixtures/conformance/loader-same-name-distinct-packages/expected.json

@@ -0,0 +1,69 @@
+{
+  "metadata.root": {
+    "package": "acme::alpha",
+    "children": [
+      {
+        "object.value": {
+          "name": "ItemView",
+          "children": [
+            {
+              "field.string": {
+                "name": "value"
+              }
+            }
+          ]
+        }
+      },
+      {
+        "object.value": {
+          "name": "SituationView",
+          "children": [
+            {
+              "field.object": {
+                "name": "items",
+                "isArray": true,
+                "@objectRef": "acme::alpha::ItemView"
+              }
+            },
+            {
+              "field.string": {
+                "name": "alphaOnly"
+              }
+            }
+          ]
+        }
+      },
+      {
+        "object.value": {
+          "name": "ItemView",
+          "children": [
+            {
+              "field.string": {
+                "name": "value"
+              }
+            }
+          ]
+        }
+      },
+      {
+        "object.value": {
+          "name": "SituationView",
+          "children": [
+            {
+              "field.object": {
+                "name": "items",
+                "isArray": true,
+                "@objectRef": "acme::beta::ItemView"
+              }
+            },
+            {
+              "field.string": {
+                "name": "betaOnly"
+              }
+            }
+          ]
+        }
+      }
+    ]
+  }
+}

fixtures/conformance/loader-same-name-distinct-packages/input/meta.alpha.json

@@ -0,0 +1,24 @@
+{
+  "metadata.root": {
+    "package": "acme::alpha",
+    "children": [
+      {
+        "object.value": {
+          "name": "ItemView",
+          "children": [
+            { "field.string": { "name": "value" } }
+          ]
+        }
+      },
+      {
+        "object.value": {
+          "name": "SituationView",
+          "children": [
+            { "field.object": { "name": "items", "isArray": true, "@objectRef": "acme::alpha::ItemView" } },
+            { "field.string": { "name": "alphaOnly" } }
+          ]
+        }
+      }
+    ]
+  }
+}

fixtures/conformance/loader-same-name-distinct-packages/input/meta.beta.json

@@ -0,0 +1,24 @@
+{
+  "metadata.root": {
+    "package": "acme::beta",
+    "children": [
+      {
+        "object.value": {
+          "name": "ItemView",
+          "children": [
+            { "field.string": { "name": "value" } }
+          ]
+        }
+      },
+      {
+        "object.value": {
+          "name": "SituationView",
+          "children": [
+            { "field.object": { "name": "items", "isArray": true, "@objectRef": "acme::beta::ItemView" } },
+            { "field.string": { "name": "betaOnly" } }
+          ]
+        }
+      }
+    ]
+  }
+}

server/csharp/MetaObjects/Parser.cs

@@ -325,6 +325,25 @@ private static string ExpandPackageForPath(string basePkg, string pkgPath)
         return basePkg + pkgPath;
     }
 
+    /// <summary>
+    /// The resolution key a ROOT-LEVEL declaration would carry once parsed:
+    /// <c>&lt;pkg&gt;::&lt;name&gt;</c> where pkg is the node's own <c>package</c>
+    /// (expanded against the file context, same as ApplyReservedKeys) when
+    /// declared, else the file's context package. Bare name when neither exists.
+    /// Matches <see cref="MetaData.ResolutionKey"/> on the already-parsed side,
+    /// so the root-level merge lookup can compare identity BEFORE the new node
+    /// is constructed.
+    /// </summary>
+    private static string RootChildResolutionKey(
+        JsonElement nodeData, string inheritedContextPkg, string name)
+    {
+        string? rawPkg = TryGetString(nodeData, RESERVED_KEY_PACKAGE);
+        string pkg = !string.IsNullOrEmpty(rawPkg)
+            ? ExpandPackageForPath(inheritedContextPkg, rawPkg)
+            : inheritedContextPkg;
+        return pkg.Length != 0 ? $"{pkg}{PACKAGE_SEPARATOR}{name}" : name;
+    }
+
     // -----------------------------------------------------------------------
     // buildTree — the shared registry-driven tree-builder.
     //
@@ -889,9 +908,27 @@ private static string FormatAttrForMsg(object? v)
 
         // Look up an existing child with (type, name). Skip unnamed nodes —
         // they are always distinct (e.g. inline validators, anonymous attrs).
+        //
+        // ROOT-LEVEL lookups are PACKAGE-QUALIFIED: two files declaring the same
+        // (type, name) under different packages are DISTINCT root nodes, never a
+        // merge pair (mirrors the Java parser, which searches root children by
+        // "pkg::name"). Nested children stay bare-name matched — they are scoped
+        // by their parent, and packages don't disambiguate siblings inside a node.
         MetaData? existing = name != ""
             ? parent.OwnChildByTypeAndName(type, name)
             : null;
+        if (existing is not null && parent is MetaRoot)
+        {
+            string candidateKey = RootChildResolutionKey(nodeData, inheritedContextPkg, name);
+            if (existing.ResolutionKey() != candidateKey)
+            {
+                // The first same-name hit is a different package — scan for an
+                // exact package-qualified match (several packages may declare
+                // this name).
+                existing = parent.OwnChildren().FirstOrDefault(
+                    c => c.Type == type && c.Name == name && c.ResolutionKey() == candidateKey);
+            }
+        }
 
         if (isOverlayNode)
         {

server/python/src/metaobjects/loader/merge.py

@@ -34,6 +34,7 @@
 from ..errors import ErrorCode, MetaError
 from ..meta.meta_data import MetaData
 from ..serializer_json import canonical_serialize
+from ..shared.separators import PACKAGE_SEP
 from ..source import (
     Contributor,
     ErrorSource,
@@ -191,6 +192,20 @@ def _detect_attr_merge_conflicts(
         )
 
 
+def _root_child_key(node: MetaData) -> str:
+    """The package-qualified identity of a ROOT-LEVEL child for merge matching.
+
+    ``<pkg>::<name>`` where pkg is the node's own ``package`` when declared,
+    else its ``file_default_package`` (the declaring file's root package
+    captured at parse time). Bare name when neither exists. Deliberately does
+    NOT use :meth:`MetaData.resolution_key` — its ancestor-walk fallback would
+    fold the MERGED root's (first file's) package onto a package-less child,
+    skewing identity for later files in the merge sequence.
+    """
+    pkg = node.package or node.file_default_package
+    return f"{pkg}{PACKAGE_SEP}{node.name}" if pkg else node.name
+
+
 def _merge_into(
     target: MetaData,
     src: MetaData,
@@ -224,10 +239,22 @@ def _merge_into(
     # attrs: source overwrites target (last-writer-wins)
     for attr in src.own_meta_attrs():
         target.set_attr(attr.name, getattr(attr, "value", None), sub_type=attr.sub_type)
-    # children: merge by (type, name), else append
+    # children: merge by (type, name), else append.
+    #
+    # ROOT-LEVEL matches are PACKAGE-QUALIFIED: two files declaring the same
+    # (type, name) under different packages are DISTINCT root nodes, never a
+    # merge pair (mirrors the Java parser, which searches root children by
+    # "pkg::name"). Nested children stay bare-name matched — they are scoped
+    # by their parent, and packages don't disambiguate siblings inside a node.
     for sc in src.own_children():
         tc = next(
-            (c for c in target.own_children() if c.type == sc.type and c.name == sc.name),
+            (
+                c
+                for c in target.own_children()
+                if c.type == sc.type
+                and c.name == sc.name
+                and (not is_root or _root_child_key(c) == _root_child_key(sc))
+            ),
             None,
         )
         if tc is not None:

server/typescript/packages/metadata/src/parser-core.ts

@@ -254,6 +254,27 @@ function expandPackageForPath(basePkg: string, pkgPath: string): string {
   return basePkg + pkgPath;
 }
 
+/**
+ * The resolution key a ROOT-LEVEL declaration would carry once parsed:
+ * `<pkg>::<name>` where pkg is the node's own `package` (expanded against the
+ * file context, same as applyReservedKeys) when declared, else the file's
+ * context package. Bare name when neither exists. Matches
+ * `MetaData.resolutionKey()` on the already-parsed side, so the root-level
+ * merge lookup can compare identity BEFORE the new node is constructed.
+ */
+function rootChildResolutionKey(
+  nodeData: Record<string, unknown>,
+  inheritedContextPkg: string,
+  name: string,
+): string {
+  const rawPkg = nodeData[RESERVED_KEY_PACKAGE];
+  const pkg =
+    typeof rawPkg === "string" && rawPkg !== ""
+      ? expandPackageForPath(inheritedContextPkg, rawPkg)
+      : inheritedContextPkg;
+  return pkg !== "" ? `${pkg}${PACKAGE_SEPARATOR}${name}` : name;
+}
+
 // ---------------------------------------------------------------------------
 // Main entry point
 // ---------------------------------------------------------------------------
@@ -901,7 +922,23 @@ function createOrFindMetaData(
   // are always distinct (e.g. inline validators, anonymous attrs).
   // ADR-0039: own — overlay/merge lookup on the AUTHORED declaration layer
   // (an overlay targets a same-file/same-node own child, pre super-resolution).
-  const existing = name !== "" ? parent.ownChildByTypeAndName(type, name) : undefined;
+  //
+  // ROOT-LEVEL lookups are PACKAGE-QUALIFIED: two files declaring the same
+  // (type, name) under different packages are DISTINCT root nodes, never a
+  // merge pair (mirrors the Java parser, which searches root children by
+  // "pkg::name"). Nested children stay bare-name matched — they are scoped
+  // by their parent, and packages don't disambiguate siblings inside a node.
+  let existing = name !== "" ? parent.ownChildByTypeAndName(type, name) : undefined;
+  if (existing !== undefined && parent instanceof MetaRoot) {
+    const candidateKey = rootChildResolutionKey(nodeData, inheritedContextPkg, name);
+    if (existing.resolutionKey() !== candidateKey) {
+      // The first same-name hit is a different package — scan for an exact
+      // package-qualified match (several packages may declare this name).
+      existing = parent
+        .ownChildren()
+        .find((c) => c.type === type && c.name === name && c.resolutionKey() === candidateKey);
+    }
+  }
 
   if (isOverlayNode) {
     if (existing === undefined) {