fix(python): complete the dotted @references head-parse in router_generator and M:N derivation

[dmealing]

Summary

Three follow-ups found while reviewing #368, plus one stale count. Stacked on fix/368-assoc-ref-disambiguation (#371) — it introduces the canonical helper both code fixes reuse.

@references on an identity.reference may use a dotted form naming an explicit field set — Team.id, acme::sport::Team.id, Program.fieldA,fieldB — where the entity name is the segment before the first . after the last ::. That form is normative (spec/metamodel/identity.json). #371 found Python diverging from the other three ports on it and added reference_target_entity(). These are the two remaining Python sites with the same blindness.

router_generator — corrupted ReverseFk.target_entity

reverse_fks_for stripped the package but not the dotted tail, so acme::sport::Team.id yielded target_entity = "Team.id" instead of Team.

The generated finder names were never affected — they derive from fk_field, not this value — so the symptom is narrower than it first looks: it is a wrong value in a documented return field (ReverseFk.target_entity, "the bare target entity (T)") that existing tests already assert on directly. A second test pins that the emitted router source is unchanged, rather than overclaiming impact.

derive_m2m_fields — the gap #371 deliberately parked

_ref_target_entity had the identical defect, and carried a KNOWN GAP comment naming the exact one-line repair. #371 left it alone because changing it alters M:N derivation behaviour and that branch was already large.

Applied here: a junction whose identity.reference uses the dotted form now resolves its target instead of raising M2MDerivationError. No existing test or shared fixture changed outcome.

Not consolidating the two head-parses

Python has two implementations of this rule: the new reference_target_entity and the pre-existing private naming_refs._split_child_tail. They are left separate and cross-referenced by docstring, because they differ on three axes — pipeline phase (pre-resolution raw-string desugar vs. post-resolution accessor), visibility (private internal vs. public), and scope (five ref-bearing attribute kinds carrying the tail forward vs. one @references case discarding it). Merging them would mean either promoting a desugar internal to public API or having the lower-level module depend on a higher-level one, for a two-line coincidental match rather than a shared contract.

README.md corpus count

README.md:204 said 314 metamodel fixtures; the real count is 329. Pre-existing drift — already wrong before #368, and outside the five spots scripts/site/counts.test.ts enforces. The neighbouring "22 corpora" claim was checked and is correct.

Verification

Python 2151 passed (baseline 2148 + 3 new tests), identical across two runs. scripts/ci-local.sh --quick passes. metamodelVersion and expected-registry.json untouched. Python and README.md only.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Lfd8nat1WcSpXffd8YetiC

[dmealing]

Merge-order note — interacts with #373.

#373 (M:N self-join declaring-entity fix, also stacked on #371) touches the function immediately below _ref_target_entity in derive_m2m_fields.py, and makes it delegate to the same canonical reference_target_entity head-parse this PR adopts.

Without that, merging these two in either order would have produced a semantic half-merge: one side of the same if handling dotted @references and the other not, so a dotted junction reference would resolve on the target side and fail on the source side. #373 removes that — both sides now go through the canonical parse.

What remains is a textual conflict only: the two PRs edit adjacent hunks of the same file. Whichever merges second will need a trivial resolution, and the correct result is that both functions delegate to reference_target_entity.

One consequence worth knowing when reviewing #373 in light of this one: with both landed, a Python junction authored with dotted @references derives M:N fields where it previously threw — measured as @references: "Post.id" / "Tag.id" going from must declare one identity.reference to "Post" and one to "Tag" to (postId, tagId).