fix(pm): identity-gate descriptor resolution (compat.zlib CI flake)

[Sunrisepeak]

Problem

compat.zlib intermittently failed on fresh CI with index entry has no mcpp field while passing locally — same binary, same descriptor bytes.

Root cause is not parsing. read_xpkg_lua locates a package descriptor by generating candidate filenames (xpkg_lua_candidates) and returning the first filesystem hit across an unordered directory_iterator scan of every index dir, with no check that the file it found is actually the requested package.

A bare zlib.lua exists in xim-pkgindex (declares name="zlib", no namespace, no mcpp block) as an unrelated upstream package. Its filename matches the zlib.lua compat fallback candidate for a compat.zlib request. Whenever the filesystem visits xim-pkgindex before mcpplibs, that blockless file is returned → extract_mcpp_field finds nothing → "index entry has no mcpp field". Directory-iteration order is unspecified and differs between a warm local checkout and a fresh CI runner — hence local-pass / CI-fail.

Only zlib is hit: it's the only one of the four compression libs whose bare name collides with a package in a directly-scanned index dir.

Essence

A non-unique filename was used as the identity key. The fix makes identity what it should be: the descriptor's declared package.{namespace,name}. The filename is only a location hint; the declared identity is the proof.

Change

• mcpp::manifest::xpkg_lua_identity_matches() — shared identity gate comparing a descriptor's declared (ns,name) against the requested coordinate. Empty-namespace requests stay discovery-lenient (used by mcpp new / scaffold, which derive the namespace from the file).
• All three read_xpkg_lua* readers route through the gate: a candidate-filename hit is accepted only when the file actually declares the requested package; otherwise scanning continues. Correct independent of directory order.
• Deterministic, sorted index-dir iteration.
• De-dup: prepare.cppm's xpkgLuaMatchesCandidate now delegates to the shared gate (single source of truth).

compat.zlib.lua (declares (compat, compat.zlib)) matches; foreign bare zlib.lua (declares (_, zlib)) is rejected for a compat.zlib request.

Tests

• test_manifest.cpp — identity-gate truth table (compat match, foreign-bare rejection, declared-namespace exclusivity, lenient no-name, default-ns legacy-bare flag, empty-ns discovery).
• test_pm_package_fetcher.cpp — cross-index collision regression: stages compat.zlib.lua + a foreign bare zlib.lua and asserts read_xpkg_lua_from_project_data returns the compat descriptor regardless of dir order; and that a foreign bare zlib alone does not satisfy a compat request.

Local verification: mcpp test 21/21 binaries green (8 new tests). Targeted e2e green: dep-resolution (27/31/62/63), scaffold (02), custom/local index (42/52), path dep (09), preinstall (58).

Scope / follow-ups

This PR delivers the load-bearing subset — the identity gate at descriptor-read sites + determinism — that closes the incident. Deliberately deferred (tracked in the design doc): payload-locator gating, index-owned-namespace totalization ((xim, zlib) for no-namespace descriptors), the identity-indexed slow path, and the unified PackageLocator choke point.

Full analysis & design: .agents/docs/2026-06-20-package-resolution-architecture.md.

[Sunrisepeak]

Identity-match matrix — filename × declared namespace × declared name vs the request

Key idea: the filename only decides which files are probed (the candidate list); it never decides identity. The match is purely declared (package.namespace, package.name) vs the request coordinate. The request coordinate comes from the TOML declaration.

How a TOML declaration becomes a request coordinate

TOML in mcpp.toml	request ns	request shortName	qname
zlib = "x" (bare, [dependencies]/[dev-dependencies])	mcpplibs (default)	zlib	mcpplibs.zlib
[dependencies.compat] → zlib = "x"	compat	zlib	compat.zlib
"mcpplibs.cmdline" = "x" (legacy dotted key)	mcpplibs	cmdline	mcpplibs.cmdline
[dependencies.xim] → zlib = "x" (non-default / custom)	xim	zlib	xim.zlib
mcpp new --template zlib (scaffold)	"" (discovery)	zlib	—

Match matrix (request → descriptor), shortName = zlib

Rows = the descriptor on disk (its filename, declared ns, declared name). Columns = the request coordinate. ∅ = field absent.

#	filename	declared ns	declared name	(mcpplibs, zlib) bare/default	(compat, zlib)	(xim, zlib) non-default	("", zlib) discovery
D1	compat.zlib.lua	compat	compat.zlib	✅ (compat alias)	✅	❌	✅
D2	zlib.lua	∅	zlib	✅ †	❌ ★	❌ ‡	✅
D3	zlib.lua	mcpplibs	zlib	✅	❌	❌	✅
D4	mcpplibs.zlib.lua	mcpplibs	mcpplibs.zlib	✅ (=qname)	❌	❌	✅
D5	zlib.lua	xim	zlib	❌	❌	✅	✅
D6	(any)	∅	∅	✅ (lenient)	✅ (lenient)	✅ (lenient)	✅ (lenient)

★ = the bug this PR fixes. (compat, zlib) request vs the upstream bare zlib.lua (D2, declares no namespace, no mcpp block) → rejected. Before this PR it was accepted whenever directory iteration hit xim-pkgindex before mcpplibs, producing index entry has no mcpp field.

D1 × (mcpplibs, zlib) = the gtest case. A bare/default-namespace request accepts its compat.<short> alias (the dev-dep gtest → compat.gtest). This is the second commit's fix.

Footnotes:

• † (mcpplibs, zlib) × D2 (no-ns bare name) is gated by allowLegacyBareDefault: ✅ on the read path (read_xpkg_lua, flag defaults true, preserves legacy bare-named default-ns packages); ❌ during multi-candidate disambiguation (selectDependencyCandidate, flag false). This is the pre-existing default-namespace ambiguity noted as a follow-up — not introduced here.
• ‡ (xim, zlib) × D2 is ❌ today because the content-only gate can't know a no-namespace file's owning index. The §4.1 follow-up (index-owned namespace → attribute a bare xim-pkgindex/.../zlib.lua as (xim, zlib)) would flip this to ✅. Not needed for this incident, and xim packages are toolchains resolved by the install path, not by [dependencies] descriptor reads.
• Discovery ("") is intentionally lenient — match by short name (bare or qualified tail), accepting any declared namespace — because scaffold derives the real (ns, name) from the descriptor afterwards.
• D6 (no declared name) is accepted everywhere: identity can't be verified, so the gate stays lenient rather than reject (no regression vs the old no-check read).

Which filenames are even probed (the "filename" dimension)

The filename only governs candidacy, not the match. Candidate lists (xpkg_lua_candidates, canonical first):

request	candidate filenames searched (in order)
(mcpplibs, zlib)	zlib.lua, mcpplibs.zlib.lua, compat.zlib.lua
(compat, zlib)	compat.zlib.lua, zlib.lua
(xim, zlib)	xim.zlib.lua, zlib.lua, compat.xim.zlib.lua, compat.zlib.lua
("", zlib)	zlib.lua, compat.zlib.lua

A file is considered if it exists under one of these names; it is accepted only if it also passes the identity column above. So (compat, zlib) probes zlib.lua (row D2) but the identity gate rejects it — closing the collision regardless of directory order.