@@ -68,7 +68,7 @@ PyPI has had no product change since `0.25.0` — nothing is broken.
 - **Kotlin** — `codegen-kotlin` (KotlinPoet on JVM): entity + Exposed table + Spring controller + payload + relations + filter allowlist + validator + stored-proc + output-parser generators. `integration-tests-kotlin` runs the persistence-conformance corpus through Exposed against Testcontainers Postgres.
 
 **Cross-port conformance corpora** (every port runs the shared corpus):
-- Metamodel: `fixtures/conformance/` (328 fixtures; 22 shared corpora in total — per-corpus counts + the corpus x port matrix live in `docs/CONFORMANCE.md`). TS / C# / Java / Python all green.
+- Metamodel: `fixtures/conformance/` (329 fixtures; 22 shared corpora in total — per-corpus counts + the corpus x port matrix live in `docs/CONFORMANCE.md`). TS / C# / Java / Python all green.
 - Render: `fixtures/render-conformance/`. TS / C# / Java / Kotlin / Python byte-identical.
 - Persistence: `fixtures/persistence-conformance/`. **Query** scenarios run on every port (TS / C# / Java / Kotlin / Python), each provisioning its test DB by executing the committed, TS-produced `canonical/schema.postgres.sql` (Postgres only — Derby dropped for the cross-port query corpus, ADR-0015). The **migration** scenarios are exercised by **TS only** (TS owns schema migrations). **The corpus now gates WRITES, not just reads (SP-H):** an `op: roundtrip` scenario type INSERTs through each port's runtime/ORM write codec (NOT raw SQL), reads the row back, and asserts the wire-normalized value. The `AllTypes` entity (`roundtrip-all-types.yaml`) carries one field of **every** persistable `field.*` subtype — string/int/long/double/float/decimal/boolean/date/time/timestamp(+tz)/currency/enum/uuid/object — plus an **array-of-VO** `field.object @isArray @storage:jsonb` column (`labels`, written as 2-element / empty-`[]` / single-element arrays across the three rows) — so every subtype write+read (incl. the array-of-value-object jsonb codec) round-trips through every port against Testcontainers PG. (`field.byte`/`field.short`/`field.class` were cut as non-functional registration-only stubs — the matrix tracks only genuinely-supported subtypes; see `fixtures/registry-conformance/README.md` → "Per-subtype write-round-trip matrix".)
 - API-contract: `fixtures/api-contract-conformance/`. TS / C# / Java / Kotlin / Python all green — each port runs **two lanes**: a hand-rolled reference server AND its **generated** API artifact booted over HTTP (the deployed controller/routes; TS+C# full-stack vs Testcontainers PG, Java/Kotlin/Python generated controller + in-memory repo behind the consumer seam). The generated fan-out found 10 real deployment bugs golden snapshots missed.
 
@@ -25,7 +25,7 @@ regenerate with `ls -d fixtures/<corpus>/*/ | wc -l`.
 
 | Corpus | Fixtures | TS | Java | Kotlin | C# | Python |
 |---|---|---|---|---|---|---|
-| [`fixtures/conformance/`](../fixtures/conformance/) (metamodel) | 328 | ✓ | ✓ | inherits via `metadata-ktx` | ✓ | ✓ |
+| [`fixtures/conformance/`](../fixtures/conformance/) (metamodel) | 329 | ✓ | ✓ | inherits via `metadata-ktx` | ✓ | ✓ |
 | [`fixtures/yaml-conformance/`](../fixtures/yaml-conformance/) | 16 | 16 / 16 | 15 / 16 (1 ledgered: `yaml-quoted-leading-zero` — Java pipeline strips quotes off `"007"`) | inherits via Java | 15 / 16 (1 ledgered: `error-yaml-coerced-hex-in-string` — YamlDotNet doesn't coerce `0xFF`) | 16 / 16 |
 | [`fixtures/verify-conformance/`](../fixtures/verify-conformance/) | 31 | ✓ | ✓ | inherits via Java | ✓ | ✓ |
 | [`fixtures/verify-strict-conformance/`](../fixtures/verify-strict-conformance/) | 1 | ✓ | — | — | — | ✓ |
@@ -119,7 +119,7 @@ unit-test runners (`bun test`, `dotnet test`, `pytest`, `mvn test`) pull Docker.
 
 ## Fixture-to-doc mapping
 
-### `fixtures/conformance/` — metamodel loader + canonical serializer (328)
+### `fixtures/conformance/` — metamodel loader + canonical serializer (329)
 
 | Fixture prefix | Feature doc |
 |---|---|
@@ -271,7 +271,7 @@ Phase 1a is TypeScript + Python only; those three ports arrive in Phase 2.
 
 ## Orphaned fixtures (tested but not yet documented)
 
-The fixtures in the nine corpora mapped above (metamodel 328 + yaml 16 + verify 31
+The fixtures in the nine corpora mapped above (metamodel 329 + yaml 16 + verify 31
 + render 15 + persistence 33 + api-contract 41 + source-resolution 25 + scope 10 +
 dependency 23) each map to a feature doc. None are orphaned today. The remaining
 corpora in the totals table gate tooling contracts (registry manifests, provider
 
@@ -7,7 +7,7 @@
     "metamodel": "1.0"
   },
   "counts": {
-    "fixtures": 328,
+    "fixtures": 329,
     "corpora": 22,
     "baseTypes": 14
   },
 
@@ -0,0 +1,91 @@
+{
+  "metadata.root": {
+    "package": "acme::sport",
+    "children": [
+      {
+        "object.entity": {
+          "name": "Team",
+          "children": [
+            {
+              "field.long": {
+                "name": "id"
+              }
+            },
+            {
+              "identity.primary": {
+                "name": "id",
+                "@fields": [
+                  "id"
+                ]
+              }
+            }
+          ]
+        }
+      },
+      {
+        "object.entity": {
+          "name": "Match",
+          "children": [
+            {
+              "field.long": {
+                "name": "id"
+              }
+            },
+            {
+              "field.long": {
+                "name": "alphaFk"
+              }
+            },
+            {
+              "field.long": {
+                "name": "betaFk"
+              }
+            },
+            {
+              "identity.primary": {
+                "name": "id",
+                "@fields": [
+                  "id"
+                ]
+              }
+            },
+            {
+              "identity.reference": {
+                "name": "alphaRef",
+                "@fields": [
+                  "alphaFk"
+                ],
+                "@references": "acme::sport::Team.id"
+              }
+            },
+            {
+              "identity.reference": {
+                "name": "betaRef",
+                "@fields": [
+                  "betaFk"
+                ],
+                "@references": "acme::sport::Team.id"
+              }
+            },
+            {
+              "relationship.association": {
+                "name": "winner",
+                "@cardinality": "one",
+                "@objectRef": "acme::sport::Team",
+                "@sourceRefField": "alphaFk"
+              }
+            },
+            {
+              "relationship.association": {
+                "name": "loser",
+                "@cardinality": "one",
+                "@objectRef": "acme::sport::Team",
+                "@sourceRefField": "betaFk"
+              }
+            }
+          ]
+        }
+      }
+    ]
+  }
+}
@@ -0,0 +1,31 @@
+{
+  "metadata.root": {
+    "package": "acme::sport",
+    "children": [
+      {
+        "object.entity": {
+          "name": "Team",
+          "children": [
+            { "field.long": { "name": "id" } },
+            { "identity.primary": { "name": "id", "@fields": "id" } }
+          ]
+        }
+      },
+      {
+        "object.entity": {
+          "name": "Match",
+          "children": [
+            { "field.long": { "name": "id" } },
+            { "field.long": { "name": "alphaFk" } },
+            { "field.long": { "name": "betaFk" } },
+            { "identity.primary": { "name": "id", "@fields": "id" } },
+            { "identity.reference": { "name": "alphaRef", "@fields": "alphaFk", "@references": "acme::sport::Team.id" } },
+            { "identity.reference": { "name": "betaRef", "@fields": "betaFk", "@references": "acme::sport::Team.id" } },
+            { "relationship.association": { "name": "winner", "@cardinality": "one", "@objectRef": "acme::sport::Team", "@sourceRefField": "alphaFk" } },
+            { "relationship.association": { "name": "loser", "@cardinality": "one", "@objectRef": "acme::sport::Team", "@sourceRefField": "betaFk" } }
+          ]
+        }
+      }
+    ]
+  }
+}
@@ -78,7 +78,18 @@ def _ref_fk_field(ref: MetaData) -> str | None:
 
 
 def _ref_target_entity(ref: MetaData) -> str | None:
-    """The @references target-entity name of a reference (bare, package-stripped)."""
+    """The @references target-entity name of a reference (bare, package-stripped).
+
+    KNOWN GAP (pre-dates #368, deliberately NOT fixed here): this compares the
+    WHOLE @references value, so the dotted ``Entity.field`` form ("Team.id")
+    never matches a bare entity name — a junction whose references are authored
+    dotted derives no M:N fields on this port, where TS's derive-m2m-fields.ts
+    (which reads ``ref.targetEntity``) resolves them. The one-line repair is to
+    delegate to ``relationship_references.reference_target_entity``; it is left
+    alone because it would change M:N derivation behaviour, which is outside the
+    #368 fix. Tracked separately from the rule-(e) ladder, whose copy of this
+    blind spot IS fixed.
+    """
     v = ref.get_meta_attr(IDENTITY_REFERENCE_ATTR_REFERENCES)  # ADR-0039: resolving (identity attr)
     return _strip_package(v) if isinstance(v, str) and v else None
 
 
@@ -19,6 +19,7 @@
 from ...meta_data import MetaData
 from ....naming import strip_package
 from ....shared.base_types import TYPE_IDENTITY
+from ....shared.separators import PACKAGE_SEP
 from ..identity.identity_constants import (
     IDENTITY_ATTR_FIELDS,
     IDENTITY_REFERENCE_ATTR_REFERENCES,
@@ -53,6 +54,31 @@ def reference_fields(ref: MetaData) -> list[str]:
     return []
 
 
+def reference_target_entity(ref: MetaData) -> str | None:
+    """The TARGET-ENTITY half of an ``identity.reference``'s ``@references``.
+
+    ``@references`` is either a bare entity name (``Team`` / ``acme::sport::Team``,
+    meaning "the target's primary identity") or the dotted ``Entity.field`` /
+    ``Entity.fieldA,fieldB`` form (``Team.id``) naming explicit target fields.
+    Both forms name the same entity, so the entity half is the segment BEFORE the
+    first ``.`` — mirroring the other three ports' ``targetEntity`` accessor
+    (TS ``MetaReferenceIdentity.targetEntity``, C# ``MetaReferenceIdentity.TargetEntity``,
+    Java ``ReferenceIdentity.getTargetEntity()``), which is the authoritative shape.
+    Python has no MetaReferenceIdentity subclass to hang it on, so it lives here.
+
+    The dot is searched only AFTER the last package separator so a ``::``-qualified
+    name can never have a package segment mistaken for the field separator. Returns
+    None when the attr is absent or empty.
+    """
+    raw = ref.get_meta_attr(IDENTITY_REFERENCE_ATTR_REFERENCES)  # ADR-0039: resolving.
+    if not isinstance(raw, str) or not raw:
+        return None
+    sep = raw.rfind(PACKAGE_SEP)
+    start = sep + len(PACKAGE_SEP) if sep >= 0 else 0
+    dot = raw.find(".", start)
+    return raw if dot == -1 else raw[:dot]
+
+
 def _first_fk_field(ref: MetaData) -> str | None:
     """The FK field a reference is anchored on (first field; composite FKs
     pair on their first column)."""
@@ -80,16 +106,17 @@ def _add(value: str | None) -> None:
 def reference_candidates_for(holder: MetaData, target_entity: str) -> list[MetaData]:
     """Every identity.reference on ``holder`` whose @references targets
     ``target_entity``. Package-insensitive on both sides: @references and
-    @objectRef may each be bare or fully qualified.
+    @objectRef may each be bare or fully qualified, and @references may use the
+    dotted ``Entity.field`` form (see :func:`reference_target_entity`).
     """
     target = strip_package(target_entity)
     candidates: list[MetaData] = []
     # ADR-0039: resolving -- children() honors references inherited via extends.
     for child in holder.children():
         if child.type != TYPE_IDENTITY or child.sub_type != IDENTITY_SUBTYPE_REFERENCE:
             continue
-        references = child.get_meta_attr(IDENTITY_REFERENCE_ATTR_REFERENCES)
-        if not isinstance(references, str) or not references:
+        references = reference_target_entity(child)
+        if references is None:
             continue
         if strip_package(references) != target:
             continue
 
@@ -137,3 +137,67 @@ def test_suffix_stripping_never_applies_to_the_relationship_name() -> None:
     assert [e.code.value for e in result.errors] == ["ERR_INVALID_RELATIONSHIP"]
     match = _find_object(result.root, "Match")
     assert resolve_relationship_reference(match, "valid", "Team") is None
+
+
+# ---------------------------------------------------------------------------
+# The dotted `@references` form — "Team.id" names the same target entity as a
+# bare "Team" (spec/metamodel/identity.json documents it). This port used to
+# compare the WHOLE attr value, so a dotted reference matched no target: a valid
+# dotted model was refused (zero candidates made a declared @sourceRefField look
+# unsatisfiable) and a genuinely ambiguous dotted model loaded clean. The other
+# three ports head-parse at the first "." and always agreed; only Python did not.
+# ---------------------------------------------------------------------------
+
+def _dotted_model(relationship: dict) -> dict:
+    return {"metadata.root": {"package": "repro", "children": [
+        {"object.entity": {"name": "Team", "children": [
+            {"field.long": {"name": "id"}},
+            {"identity.primary": {"name": "id", "@fields": ["id"]}},
+        ]}},
+        {"object.entity": {"name": "Match", "children": [
+            {"field.long": {"name": "id"}},
+            {"field.long": {"name": "alphaFk"}},
+            {"field.long": {"name": "betaFk"}},
+            {"identity.primary": {"name": "id", "@fields": ["id"]}},
+            {"identity.reference": {"name": "alphaRef", "@fields": ["alphaFk"],
+                                    "@references": "Team.id"}},
+            {"identity.reference": {"name": "betaRef", "@fields": ["betaFk"],
+                                    "@references": "repro::Team.id"}},
+            {"relationship.association": relationship},
+        ]}},
+    ]}}
+
+
+def test_dotted_references_are_enumerated_as_candidates() -> None:
+    doc = _dotted_model({"name": "winner", "@objectRef": "Team",
+                         "@cardinality": "one", "@sourceRefField": "alphaFk"})
+    match = _load_object(doc, "Match")
+    # Both the bare-dotted "Team.id" and the FQN-dotted "repro::Team.id" forms
+    # resolve to the entity "Team" — the package separator is never mistaken
+    # for the field separator.
+    assert [c.name for c in reference_candidates_for(match, "Team")] == ["alphaRef", "betaRef"]
+    assert [c.name for c in reference_candidates_for(match, "repro::Team")] == ["alphaRef", "betaRef"]
+
+
+def test_dotted_references_resolve_through_source_ref_field() -> None:
+    doc = _dotted_model({"name": "winner", "@objectRef": "Team",
+                         "@cardinality": "one", "@sourceRefField": "betaFk"})
+    # Loads clean: the declared FK names a real candidate. Before the head-parse
+    # this raised ERR_INVALID_RELATIONSHIP ("names no identity.reference
+    # targeting Team. Candidates: .") on a model TypeScript accepted.
+    match = _load_object(doc, "Match")
+    resolved = resolve_relationship_reference(match, "winner", "Team", "betaFk")
+    assert resolved is not None and resolved.name == "betaRef"
+
+
+def test_dotted_references_are_still_ambiguous_without_disambiguation() -> None:
+    # The other direction: "winner" pairs with neither candidate, so the load
+    # must FAIL. Before the head-parse there were zero candidates, rule (e)'s
+    # `len(candidates) <= 1` skipped, and the model loaded clean while
+    # TypeScript refused it.
+    doc = _dotted_model({"name": "winner", "@objectRef": "Team", "@cardinality": "one"})
+    result = MetaDataLoader().load([InMemoryStringSource(json.dumps(doc))])
+    assert [e.code.value for e in result.errors] == ["ERR_INVALID_RELATIONSHIP"]
+    assert "alphaRef(alphaFk), betaRef(betaFk)" in result.errors[0].message
+    match = _find_object(result.root, "Match")
+    assert resolve_relationship_reference(match, "winner", "Team") is None