fix: #278 package identity convergence — index side + dependency side (0.0.105)

[Sunrisepeak]

Fixes #278

The incident

mcpp-index changed chriskohlhoff.asio's name from "chriskohlhoff.asio" to "asio" (namespace untouched). Lint went green; all three platform workspace jobs died after 20–58 minutes with E_NOT_FOUND. The descriptor parsed, passed mcpp's own identity gate, and no consumer spelling could install it.

Root cause — one split, two sides

Index side. Identity normalization treats (ns="a", name="b") and (ns="a", name="a.b") as equivalent; install-target construction hard-assumes the latter. Verified against libxpkg: build_index is called with no namespace, so the index is a flat key space keyed by the literal package.name, looked up with exact entries.find(). mcpp addresses packages as <ns>.<short>. The two never meet.

Dependency side. The bare-name ladder's discovery rung was specified as "match by name across the precedence path" but implemented as "try two more filenames" — and a total miss fell through to candidates.front() silently, so mcpp continued with a namespace it had invented and the user met the failure much later, wrapped around that invented name.

Both contracts existed only as prose comments (prepare.cppm:1714, :1456, and the gate's "the caller derives the namespace"). They are now predicates.

What this changes

INV-NAME (index side) — package.name must BE the fully-qualified name whenever package.namespace is declared. One predicate, two call sites: mcpp xpkg parse (index CI, seconds) and the install path (catches descriptors that never passed lint; zero extra I/O — the descriptor is already in memory). Lint and runtime cannot drift.

The predicate is deliberately narrow. Written as the general "literal name != derived fqname" comparison it would flag the working compat-alias path — a bare gtest request derives gtest while the literal is compat.gtest — and break every bare dependency. CompatAliasIsClean locks that.

INV-RESOLVE (dependency side) — a bare name resolves in exactly three places: mcpplibs, compat, no-namespace upstream. Everything else must be written out.

Global short-name search was considered and rejected: it makes resolution depend on which indices happen to be present, so adding an index could silently retarget an existing dependency; same-short-name collisions would be settled by an index ordering that has no total order across user [indices]. Reproducibility beats convenience.

The index-wide scan survives only as a did-you-mean on the already-failed path — result goes into error text, never back into resolution (three constraints documented at Fetcher::scan_fqns_with_short_name).

Generator fix — mcpp emit xpkg wrote a bare name and no namespace at all, so filing a package into a namespaced index meant hand-adding namespace = "<org>", and that edit is what created the split form. aimol.tensorvia-cpu was born exactly this way (still carries the "AUTO-GENERATED, do not edit by hand" banner). Prescribed in the 2026-06-26 design §4.5; never landed until now.

⚠️ Breaking

Bare names no longer reach third-party namespaces. Migration needs no docs — the failure prints the two lines to write:

error: dependency 'asio': no package found under the namespaces mcpp searched
  tried: (mcpplibs, asio), (no namespace, asio)
  a package with this name exists under another namespace:
    chriskohlhoff.asio
  bare names only resolve to the `mcpplibs` / `compat` namespaces. write it out:
    [dependencies]
    "chriskohlhoff.asio" = "1.38.1"
  or:
    [dependencies.chriskohlhoff]
    asio = "1.38.1"

Verified: the suggested spelling downloads and compiles asio end-to-end.

Scope correction found during implementation

The design's "2 violations in 62 descriptors" figure covered only the mcpplibs index. Running the predicate over the full registry (200+) surfaced 30 split-form descriptors — and all 28 extra ones are legitimate: in xlings-native indices (xim-pkgindex, -scode) package.namespace is an install-dir category (config, scode, awesome), the index is keyed by the bare name, and the split spelling is correct there. All 30 lack an mcpp segment and never reach mcpp's dependency path.

Hence mcpp xpkg parse --allow-split-name for xlings-native trees. No xim repo runs mcpp xpkg parse today (checked their .github/), and mcpp-index's CI does — so enforce-by-default is right.

Verification

• Unit — 8 new XpkgNameForm cases incl. the CompatAliasIsClean regression lock; 37/37 unit binaries green.
• e2e 161 — lint rejects split form with the exact fix line, --json carries it, --allow-split-name opts out, runtime fail-fast fires before any download.
• e2e 162 — bare third-party name fails with did-you-mean; both documented spellings resolve the same package; bare gtest → compat.gtest still works.
• Full-index regression — all 49/49 mcpplibs descriptors parse clean, 0 INV-NAME violations (zero false positives).
• Live check — bare gtest builds; "chriskohlhoff.asio" downloads + compiles.

Ecosystem

mcpp-index already carries both fixes upstream (chriskohlhoff.asio and aimol.tensorvia-cpu are FQN; #116's check_package_name.lua landed) — that guard is now redundant with mcpp xpkg parse but harmless.

Design: .agents/docs/2026-07-25-issue278-descriptor-name-form-canonicalization-design.md
Plan: .agents/docs/2026-07-25-issue278-implementation-plan.md