Skip to content

Commit d3d3495

Browse files
dmealingclaude
dmealing
and
claude
authored
feat: cross-package reference resolution contract (ADR-0041) — all 5 ports + conformance matrix (#173)
* feat(metadata): cross-package reference resolution contract (TS reference) + conformance matrix (ADR-0041) Every reference that names another object (@objectref, @references, origin @from/@of/@via, extends, @through, template refs) may cross package boundaries, but the ports had no shared, tested contract for name collisions across packages and ZERO cross-package conformance fixtures — which hid a real cross-port bug (Java resolves an explicit FQN to the wrong same-named package; investigation this session). Contract (ADR-0041): an FQN reference resolves EXACTLY to its package (never a bare-tail fallback); a BARE reference prefers the referrer's own package, else a unique object of that name anywhere, else ERR_AMBIGUOUS_REF (new). Preserves every unique-name case; only collisions change — from silent, arbitrary, port-divergent mis-binding to same-package preference or a loud, portable error. TS reference implementation: - `resolveObjectRef(root, ref, referrerPkg)` (naming-refs.ts) — the single object-ref resolver: FQN-exact; bare prefers referrer pkg, else unique, else ambiguous. - `validateCrossPackageRefs` loader pass emits ERR_AMBIGUOUS_REF for a bare ref that names an object in >1 package with none in the referrer's package (covers every REF_BEARING_ATTR_NAMES attr; strips origin dotted `.child` tails to the owner). extends stays FQN-strict via its own FR-032 super-resolver (bare cross-package extends → ERR_UNRESOLVED_SUPER). - ERR_AMBIGUOUS_REF registered in errors.ts + fixtures/conformance/ERROR-CODES.json. Conformance matrix (fixtures/conformance/xpkg-*, error-xpkg-*): every ref-bearing attr cross-package (unique-name working cases) + the collision contract (FQN-exact-across-collision via extends effective serialization — the fixture that catches the Java FQN-discard bug; bare same-package preference; bare-ambiguous → error). TS green: metadata 2111, codegen-ts 909, cli/render, typecheck clean. Residual (follow-up): codegen-ts resolution (relation-resolver/import-path) still bare-name first-match on a same-name collision — loader now guards it, codegen same-package preference is a separate pass. Port fan-out (Java/Python/C#/Kotlin) next, all conformance-gated against this matrix. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ew1XfYSbEAezxjs9opynAe * feat(java,kotlin,python,csharp): port cross-package reference resolution contract (ADR-0041) Fan-out of the TS reference (60bd97d). All 5 ports now pass the shared cross-package conformance matrix byte-identically. - Java (the confirmed bug): SymbolTable.nameMatches / ValidationPhase.nameMatches matched the ref's bare TAIL before the exact-FQN check, so an explicit FQN `xpkg::vendor::Customer` silently bound `xpkg::crm::Customer` (wrong package / wrong FK table). Now: an FQN ref (`ref.contains("::")`) resolves EXACTLY (`ref.equals(child.getName())`), never a bare-tail fallback; bare refs match the short name. Fixes xpkg-collision-extends-fqn (effective serialization now inherits from the correct package). - All ports: ERR_AMBIGUOUS_REF registered + a validateCrossPackageRefs pass emitting it for a bare object-ref that names an object in >1 package with none in the referrer's own package (mirrors the TS validateCrossPackageRefs). Python and C# already resolved FQNs exactly (no matcher bug), so they only added the ambiguity pass + resolver helper. - Codegen touched where it shared the bare-match bug (codegen-spring SpringM2mSupport, codegen-kotlin render helper); codegen same-package target-selection remains a follow-up (matching the TS residual note). Verified: Java ConformanceTest 420/0 + Kotlin conformance green; Python 323/0; C# 710/0. All emit ERR_AMBIGUOUS_REF on the ambiguity fixture and resolve the FQN-collision fixture to the correct package. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ew1XfYSbEAezxjs9opynAe --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
1 parent aad21fe commit d3d3495

55 files changed

Lines changed: 2248 additions & 24 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎fixtures/conformance/ERROR-CODES.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@
2929
"ERR_MALFORMED_YAML": "The YAML metadata input is not valid YAML, or cannot be desugared into canonical metadata.",
3030
"ERR_INVALID_ORIGIN": "A field origin (passthrough/aggregate) declares an invalid path or attribute.",
3131
"ERR_AMBIGUOUS_PATH": "FR-024 (ADR-0029): an implicit (omitted-@via) origin path is ambiguous — more than one single-hop relationship leads from the base entity to the @from/@of entity (the error names the candidates), or a projection's base entity cannot be derived because its fields extend multiple entities and no extended identity anchors the base.",
32+
"ERR_AMBIGUOUS_REF": "Cross-package reference contract — a BARE reference (no `::`) names an object that exists in more than one package and none is in the referrer's own package. The reference is ambiguous; qualify it with the package (FQN). Applies to every object-ref-bearing attribute (@objectRef, @references, @from/@of/@via heads, extends, @payloadRef/@responseRef, @through).",
3233
"ERR_ORIGIN_CARDINALITY": "FR-024 (ADR-0029): origin cardinality contract broken — a passthrough @via path crosses a to-many hop (row-multiplying passthrough — you meant aggregate), or an aggregate @via path is to-one at every hop (aggregating over a to-one path — you meant passthrough). Checked on explicit AND inferred paths.",
3334
"ERR_EXTENDS_ORIGIN_MISMATCH": "FR-024 (ADR-0029 decision 7): a field declares both an entity-nested extends (shape lineage) and an origin.passthrough @from (data lineage) and they disagree — the resolved @from target is not the field's resolved extends target (nor anywhere on its extends chain). Host-agnostic (projections, entities, values). origin.aggregate is never judged (it computes something new); a top-level abstract extends target is never judged (shape-only reuse makes no lineage claim).",
3435
"ERR_DERIVED_FIELD_NO_READ_SOURCE": "FR-024 (spec §7): an object.entity field carrying an origin.* child is derived (read-only) and must be providable — the entity must declare at least one source with a read-only @kind (view/materializedView/storedProc/tableFunction, e.g. a @role replica view beside the table primary). Table-only or source-less entities with origin-bearing fields error on the field. Projections and object.value hosts are exempt. Until the Phase-E B4b cutover removes view-primary entities, a read-only-kind PRIMARY source also counts as providable (legacy spelling).",

‎fixtures/conformance/error-xpkg-ambiguous-objectref/expected-errors.json‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"errors": [
3+
{
4+
"code": "ERR_AMBIGUOUS_REF",
5+
"source": {
6+
"format": "resolved",
7+
"files": [
8+
"meta.sales.json"
9+
],
10+
"jsonPath": "$['metadata.root'].children[0]['object.entity'].children[4]['relationship.association']",
11+
"referrer": "Order",
12+
"target": "Customer"
13+
}
14+
}
15+
],
16+
"warnings": []
17+
}

‎fixtures/conformance/error-xpkg-ambiguous-objectref/input/meta.crm.json‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
{
2+
"metadata.root": {
3+
"package": "xpkg::crm",
4+
"children": [
5+
{
6+
"object.entity": {
7+
"name": "Customer",
8+
"children": [
9+
{
10+
"source.rdb": {
11+
"@table": "crm_customers"
12+
}
13+
},
14+
{
15+
"field.long": {
16+
"name": "id"
17+
}
18+
},
19+
{
20+
"identity.primary": {
21+
"name": "pk",
22+
"@fields": [
23+
"id"
24+
]
25+
}
26+
}
27+
]
28+
}
29+
}
30+
]
31+
}
32+
}

‎fixtures/conformance/error-xpkg-ambiguous-objectref/input/meta.sales.json‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
{
2+
"metadata.root": {
3+
"package": "xpkg::sales",
4+
"children": [
5+
{
6+
"object.entity": {
7+
"name": "Order",
8+
"children": [
9+
{
10+
"source.rdb": {
11+
"@table": "orders"
12+
}
13+
},
14+
{
15+
"field.long": {
16+
"name": "id"
17+
}
18+
},
19+
{
20+
"field.long": {
21+
"name": "customerId"
22+
}
23+
},
24+
{
25+
"identity.primary": {
26+
"name": "pk",
27+
"@fields": [
28+
"id"
29+
]
30+
}
31+
},
32+
{
33+
"relationship.association": {
34+
"name": "customer",
35+
"@cardinality": "one",
36+
"@objectRef": "Customer"
37+
}
38+
}
39+
]
40+
}
41+
}
42+
]
43+
}
44+
}

‎fixtures/conformance/error-xpkg-ambiguous-objectref/input/meta.vendor.json‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
{
2+
"metadata.root": {
3+
"package": "xpkg::vendor",
4+
"children": [
5+
{
6+
"object.entity": {
7+
"name": "Customer",
8+
"children": [
9+
{
10+
"source.rdb": {
11+
"@table": "vendor_customers"
12+
}
13+
},
14+
{
15+
"field.long": {
16+
"name": "id"
17+
}
18+
},
19+
{
20+
"identity.primary": {
21+
"name": "pk",
22+
"@fields": [
23+
"id"
24+
]
25+
}
26+
}
27+
]
28+
}
29+
}
30+
]
31+
}
32+
}

‎fixtures/conformance/error-xpkg-ambiguous-objectref/providers.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
["metaobjects-core-types","metaobjects-db"]

‎fixtures/conformance/xpkg-collision-bare-same-package/expected-effective.json‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
{
2+
"metadata.root": {
3+
"package": "xpkg::home",
4+
"children": [
5+
{
6+
"object.entity": {
7+
"name": "Base",
8+
"abstract": true,
9+
"children": [
10+
{
11+
"field.long": {
12+
"name": "id"
13+
}
14+
},
15+
{
16+
"field.string": {
17+
"name": "homeOnly"
18+
}
19+
}
20+
]
21+
}
22+
},
23+
{
24+
"object.entity": {
25+
"name": "Gadget",
26+
"extends": "Base",
27+
"children": [
28+
{
29+
"field.long": {
30+
"name": "id"
31+
}
32+
},
33+
{
34+
"field.string": {
35+
"name": "homeOnly"
36+
}
37+
},
38+
{
39+
"source.rdb": {
40+
"@table": "gadgets"
41+
}
42+
},
43+
{
44+
"field.string": {
45+
"name": "label"
46+
}
47+
},
48+
{
49+
"identity.primary": {
50+
"name": "pk",
51+
"@fields": [
52+
"id"
53+
]
54+
}
55+
}
56+
]
57+
}
58+
},
59+
{
60+
"object.entity": {
61+
"name": "Base",
62+
"abstract": true,
63+
"children": [
64+
{
65+
"field.long": {
66+
"name": "id"
67+
}
68+
},
69+
{
70+
"field.string": {
71+
"name": "otherOnly"
72+
}
73+
}
74+
]
75+
}
76+
}
77+
]
78+
}
79+
}
80+

‎fixtures/conformance/xpkg-collision-bare-same-package/expected.json‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
{
2+
"metadata.root": {
3+
"package": "xpkg::home",
4+
"children": [
5+
{
6+
"object.entity": {
7+
"name": "Base",
8+
"abstract": true,
9+
"children": [
10+
{
11+
"field.long": {
12+
"name": "id"
13+
}
14+
},
15+
{
16+
"field.string": {
17+
"name": "homeOnly"
18+
}
19+
}
20+
]
21+
}
22+
},
23+
{
24+
"object.entity": {
25+
"name": "Gadget",
26+
"extends": "Base",
27+
"children": [
28+
{
29+
"source.rdb": {
30+
"@table": "gadgets"
31+
}
32+
},
33+
{
34+
"field.string": {
35+
"name": "label"
36+
}
37+
},
38+
{
39+
"identity.primary": {
40+
"name": "pk",
41+
"@fields": [
42+
"id"
43+
]
44+
}
45+
}
46+
]
47+
}
48+
},
49+
{
50+
"object.entity": {
51+
"name": "Base",
52+
"abstract": true,
53+
"children": [
54+
{
55+
"field.long": {
56+
"name": "id"
57+
}
58+
},
59+
{
60+
"field.string": {
61+
"name": "otherOnly"
62+
}
63+
}
64+
]
65+
}
66+
}
67+
]
68+
}
69+
}
70+

‎fixtures/conformance/xpkg-collision-bare-same-package/input/meta.home.json‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
{
2+
"metadata.root": {
3+
"package": "xpkg::home",
4+
"children": [
5+
{
6+
"object.entity": {
7+
"name": "Base",
8+
"abstract": true,
9+
"children": [
10+
{
11+
"field.long": {
12+
"name": "id"
13+
}
14+
},
15+
{
16+
"field.string": {
17+
"name": "homeOnly"
18+
}
19+
}
20+
]
21+
}
22+
},
23+
{
24+
"object.entity": {
25+
"name": "Gadget",
26+
"extends": "Base",
27+
"children": [
28+
{
29+
"source.rdb": {
30+
"@table": "gadgets"
31+
}
32+
},
33+
{
34+
"field.string": {
35+
"name": "label"
36+
}
37+
},
38+
{
39+
"identity.primary": {
40+
"name": "pk",
41+
"@fields": [
42+
"id"
43+
]
44+
}
45+
}
46+
]
47+
}
48+
}
49+
]
50+
}
51+
}

‎fixtures/conformance/xpkg-collision-bare-same-package/input/meta.other.json‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
{
2+
"metadata.root": {
3+
"package": "xpkg::other",
4+
"children": [
5+
{
6+
"object.entity": {
7+
"name": "Base",
8+
"abstract": true,
9+
"children": [
10+
{
11+
"field.long": {
12+
"name": "id"
13+
}
14+
},
15+
{
16+
"field.string": {
17+
"name": "otherOnly"
18+
}
19+
}
20+
]
21+
}
22+
}
23+
]
24+
}
25+
}

0 commit comments

Comments
 (0)