fix(pm): identity-first candidate selection — resolve custom-ns pkgs filed under non-canonical filenames (v0.0.67) (#176)

A dependency with a namespace prefix whose package declares the split form
(`name="tensorvia-cpu"`, `namespace="aimol"`) and is filed under a non-canonical
filename in a shared index (`pkgs/t/tensorvia-cpu.lua`, not the canonical
`pkgs/a/aimol.tensorvia-cpu.lua`) failed to resolve:

    error: dependency 'aimol.tensorvia-cpu': index entry not found in local clone

while the bare form `tensorvia-cpu` resolved and installed correctly. Root cause:
`selectDependencyCandidate` disambiguated the dotted-selector candidate ladder
[(mcpplibs.aimol, tensorvia-cpu), (aimol, tensorvia-cpu)] by probing whether each
candidate's CANONICAL FILENAME `<ns>.<short>.lua` exists on disk. The descriptor's
bytes live under a non-canonical name, so the correct peer-root candidate
(aimol, tensorvia-cpu) was invisible, the request stayed pinned to the wrong front
candidate (mcpplibs.aimol, …), and the load-path identity gate rejected it.

Fix: candidate selection is now identity-first. It locates each candidate via the
same identity-verified readers the load path uses (`read_xpkg_lua*`), which key on
the descriptor's DECLARED (ns, name) and already cover non-canonical filenames — so
selection and loading can never disagree. The canonical-filename-only strict reader
(`readStrictLuaFromPkgsDir` / `canonicalXpkgLuaFilename`) is removed; the filename is
no longer an identity key.

This is Step 0 of the identity-first architecture; the §5 PackageLocator/IdentityIndex
choke-point consolidation remains follow-up. Design + research + the complete
(ns,name) matching-rules table + test-coverage-gap analysis:
.agents/docs/2026-06-26-identity-first-resolution-no-filename.md

Tests:
- unit PmPackageFetcher.ResolvesCustomNamespaceDescriptorUnderNonCanonicalFilename
  (locks the read-layer identity-not-filename invariant)
- e2e 76_qualified_custom_ns_noncanonical_filename.sh (the full repro: builtin index
  × non-canonical filename × qualified request; asserts resolve + lock ns="aimol" +
  clean not-found for a genuinely wrong namespace)

Author: Sunrisepeak

.agents/docs/2026-06-26-identity-first-resolution-no-filename.md

@@ -3,6 +3,22 @@
 > 本文件追踪 `mcpp-community/mcpp` 公开仓的版本演进。
 > 格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [0.0.67] — 2026-06-26
+
+### 修复
+
+- **带命名空间前缀的依赖解析失败 `index entry not found in local clone`(自定义 ns + 非规范文件名)**:
+  当一个包以「裸 `name` + 独立 `namespace` 字段」形态声明(如 `aimol.tensorvia-cpu`:
+  `name="tensorvia-cpu"`、`namespace="aimol"`),并以**非规范文件名**落盘在共享索引里
+  (`pkgs/t/tensorvia-cpu.lua` 而非 `pkgs/a/aimol.tensorvia-cpu.lua`)时,限定请求
+  `aimol.tensorvia-cpu` 报「索引条目缺失」,而裸名 `tensorvia-cpu` 却能解析。根因是
+  **候选消歧 `selectDependencyCandidate` 用「规范文件名 `<ns>.<short>.lua` 是否存在」当身份
+  判据**——描述符以非规范文件名落盘时,正确的 peer-root 候选 `(aimol, tensorvia-cpu)` 对消歧
+  器隐形,请求被钉死在错误的首选候选 `(mcpplibs.aimol, …)` 上并被身份门拒绝。修复:候选消歧
+  改为**身份优先**,经由加载路径同款的身份校验读取器(`read_xpkg_lua*`)按描述符**声明的
+  `(ns, name)`** 定位候选,文件名不再参与身份判定——选择层与加载层从此不可能对同一候选产生
+  分歧。详见 `.agents/docs/2026-06-26-identity-first-resolution-no-filename.md`。
+
 ## [0.0.66] — 2026-06-26
 
 ### 修复

CHANGELOG.md

@@ -1,6 +1,6 @@
 [package]
 name        = "mcpp"
-version     = "0.0.66"
+version     = "0.0.67"
 description = "Modern C++ build & package management tool"
 license     = "Apache-2.0"
 authors     = ["mcpp-community"]

mcpp.toml

@@ -899,32 +899,20 @@ prepare_build(bool print_fingerprint,
         return nullptr;
     };
 
-    auto canonicalXpkgLuaFilename =
-        [](std::string_view ns, std::string_view shortName) {
-            if (ns.empty() || ns == mcpp::pm::kDefaultNamespace) {
-                return std::string(shortName) + ".lua";
-            }
-            return std::format("{}.{}.lua", ns, shortName);
-        };
-
-    auto readStrictLuaFromPkgsDir =
-        [&](const std::filesystem::path& pkgsDir,
-            std::string_view ns,
-            std::string_view shortName) -> std::optional<std::string>
-    {
-        auto fname = canonicalXpkgLuaFilename(ns, shortName);
-        if (fname.empty()) return std::nullopt;
-        char first = static_cast<char>(std::tolower(
-            static_cast<unsigned char>(fname.front())));
-        auto candidate = pkgsDir / std::string(1, first) / fname;
-        if (!std::filesystem::exists(candidate)) return std::nullopt;
-
-        std::ifstream is(candidate);
-        std::stringstream ss;
-        ss << is.rdbuf();
-        return ss.str();
-    };
-
+    // Identity-first candidate probe. A candidate is located by the DECLARED
+    // (namespace, name) of whatever descriptor the index holds — never by whether
+    // a canonically-named file `<ns>.<short>.lua` happens to exist on disk. It
+    // routes through the same identity-verified readers the load path uses
+    // (`read_xpkg_lua*`, which gate every hit on the descriptor's declared
+    // identity and already cover non-canonical filenames), so candidate selection
+    // and loading can never disagree about what a candidate resolves to.
+    //
+    // Before this, selection probed the canonical filename only, so a descriptor
+    // filed under a non-canonical name (e.g. `aimol.tensorvia-cpu` declared in the
+    // mcpplibs index as bare `pkgs/t/tensorvia-cpu.lua`) was invisible to its own
+    // peer-root candidate `(aimol, tensorvia-cpu)`, leaving the request pinned to
+    // the wrong front candidate `(mcpplibs.aimol, …)`. See
+    // .agents/docs/2026-06-26-identity-first-resolution-no-filename.md.
     auto readStrictLuaForCandidate =
         [&](const mcpp::pm::DependencyCoordinate& coord)
             -> std::optional<std::string>
@@ -935,38 +923,15 @@ prepare_build(bool print_fingerprint,
         auto* idxSpec = findIndexForNs(coord.namespace_);
         if (idxSpec && idxSpec->is_local()) {
             auto indexPath = mcpp::config::resolve_project_index_path(*root, *idxSpec);
-            return readStrictLuaFromPkgsDir(indexPath / "pkgs",
-                                            coord.namespace_,
-                                            coord.shortName);
+            return mcpp::fetcher::Fetcher::read_xpkg_lua_from_path(
+                indexPath, coord.namespace_, coord.shortName);
         }
         if (idxSpec && !idxSpec->is_builtin()) {
-            std::error_code ec;
-            for (auto& data : mcpp::config::project_xlings_data_roots(*root)) {
-                if (!std::filesystem::exists(data)) continue;
-                for (auto& entry : std::filesystem::directory_iterator(data, ec)) {
-                    if (!entry.is_directory()) continue;
-                    auto pkgsDir = entry.path() / "pkgs";
-                    if (auto lua = readStrictLuaFromPkgsDir(
-                            pkgsDir, coord.namespace_, coord.shortName)) {
-                        return lua;
-                    }
-                }
-            }
-            return std::nullopt;
-        }
-
-        auto data = (*cfg)->xlingsHome() / "data";
-        if (!std::filesystem::exists(data)) return std::nullopt;
-        std::error_code ec;
-        for (auto& entry : std::filesystem::directory_iterator(data, ec)) {
-            if (!entry.is_directory()) continue;
-            auto pkgsDir = entry.path() / "pkgs";
-            if (auto lua = readStrictLuaFromPkgsDir(
-                    pkgsDir, coord.namespace_, coord.shortName)) {
-                return lua;
-            }
+            return mcpp::fetcher::Fetcher::read_xpkg_lua_from_project_data(
+                *root, coord.namespace_, coord.shortName);
         }
-        return std::nullopt;
+        mcpp::fetcher::Fetcher fetcher(**cfg);
+        return fetcher.read_xpkg_lua(coord.namespace_, coord.shortName);
     };
 
     auto xpkgLuaMatchesCandidate =

src/build/prepare.cppm

@@ -18,7 +18,7 @@ import mcpp.toolchain.detect;
 
 export namespace mcpp::toolchain {
 
-inline constexpr std::string_view MCPP_VERSION = "0.0.66";
+inline constexpr std::string_view MCPP_VERSION = "0.0.67";
 
 struct FingerprintInputs {
     Toolchain                       toolchain;

src/toolchain/fingerprint.cppm

@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+# requires: gcc fresh-sandbox
+# Regression for the identity-first resolution gap
+# (.agents/docs/2026-06-26-identity-first-resolution-no-filename.md).
+#
+# Production trigger: package `aimol.tensorvia-cpu` declares
+#   namespace = "aimol", name = "tensorvia-cpu"
+# and is hosted in the BUILTIN mcpplibs index (NOT a [indices] entry), filed under
+# the NON-canonical bare filename `pkgs/t/tensorvia-cpu.lua` (canonical would be
+# `pkgs/a/aimol.tensorvia-cpu.lua`). A qualified request `aimol.tensorvia-cpu`
+# must resolve by the descriptor's DECLARED (ns, name) — the filename is not a key.
+#
+# This is the exact intersection the prior suite never crossed at once:
+#   builtin index  ×  non-canonical filename  ×  qualified multi-candidate request.
+# Fixed by making selectDependencyCandidate identity-first (it now locates each
+# candidate by the descriptor's declared (ns, name) via read_xpkg_lua* instead of
+# probing the canonical filename `<ns>.<short>.lua`).
+set -e
+
+TMP=$(mktemp -d)
+trap "rm -rf $TMP" EXIT
+
+export MCPP_HOME="$TMP/mcpp-home"
+source "$(dirname "$0")/_inherit_toolchain.sh"
+
+INDEX_DIR="$MCPP_HOME/registry/data/mcpplibs"
+# Observed real install layout is <ns>-x-<short>: aimol-x-tensorvia-cpu.
+PKG_ROOT="$MCPP_HOME/registry/data/xpkgs/aimol-x-tensorvia-cpu/0.1.1"
+mkdir -p "$INDEX_DIR/pkgs/t" "$PKG_ROOT/src"
+printf 'ok\n' > "$INDEX_DIR/.mcpp-index-updated"
+
+# Custom namespace "aimol", bare name "tensorvia-cpu", filed under the BARE
+# filename in the mcpplibs index — filename does not encode the namespace.
+cat > "$INDEX_DIR/pkgs/t/tensorvia-cpu.lua" <<'EOF'
+package = {
+    spec = "1",
+    namespace = "aimol",
+    name = "tensorvia-cpu",
+    description = "Custom-namespace package filed under a non-canonical filename",
+    licenses = {"MIT"},
+    type = "package",
+    xpm = {
+        linux = {
+            ["0.1.1"] = {
+                url = "https://example.invalid/tensorvia-cpu-0.1.1.tar.gz",
+                sha256 = "0000000000000000000000000000000000000000000000000000000000000000",
+            },
+        },
+    },
+    mcpp = {
+        language = "c++23",
+        import_std = false,
+        sources = { "src/tensorvia.cppm" },
+        targets = { ["tensorvia-cpu"] = { kind = "lib" } },
+        deps = {},
+    },
+}
+EOF
+
+cat > "$PKG_ROOT/src/tensorvia.cppm" <<'EOF'
+export module tensorvia.cpu;
+
+export int tensorvia_value() {
+    return 42;
+}
+EOF
+printf 'ok\n' > "$PKG_ROOT/.mcpp_ok"
+
+mkdir -p "$TMP/project/app/src"
+cd "$TMP/project/app"
+
+cat > src/main.cpp <<'EOF'
+import tensorvia.cpu;
+
+int main() {
+    return tensorvia_value() == 42 ? 0 : 1;
+}
+EOF
+
+cat > mcpp.toml <<'EOF'
+[package]
+name = "app"
+version = "0.1.0"
+
+[dependencies]
+aimol.tensorvia-cpu = "0.1.1"
+
+[targets.app]
+kind = "bin"
+main = "src/main.cpp"
+EOF
+
+# (1) Qualified custom-ns request must resolve despite the non-canonical filename.
+"$MCPP" build > build.log 2>&1 || {
+    echo "FAIL: aimol.tensorvia-cpu did not resolve (identity-first regression)"
+    cat build.log
+    exit 1
+}
+"$MCPP" run > run.log 2>&1 || { cat run.log; exit 1; }
+
+# (2) The resolved identity must record the declared namespace, not mcpplibs.aimol.
+grep -q 'namespace = "aimol"' mcpp.lock || {
+    cat mcpp.lock
+    echo "FAIL: lock must record resolved namespace aimol"
+    exit 1
+}
+if grep -q 'mcpplibs.aimol' mcpp.lock; then
+    cat mcpp.lock
+    echo "FAIL: front candidate mcpplibs.aimol leaked into the lock"
+    exit 1
+fi
+
+# (3) A genuinely wrong namespace must be a clean not-found, not a silent match.
+cat > mcpp.toml <<'EOF'
+[package]
+name = "app"
+version = "0.1.0"
+
+[dependencies]
+mcpplibs.tensorvia-cpu = "0.1.1"
+
+[targets.app]
+kind = "bin"
+main = "src/main.cpp"
+EOF
+rm -f mcpp.lock
+if "$MCPP" build > wrong.log 2>&1; then
+    echo "FAIL: mcpplibs.tensorvia-cpu must NOT resolve (package is aimol-namespaced)"
+    cat wrong.log
+    exit 1
+fi
+
+echo "OK"

tests/e2e/76_qualified_custom_ns_noncanonical_filename.sh

@@ -133,3 +133,45 @@ TEST(PmPackageFetcher, LocalPathIndexAttributesOwnNamespaceToNoNsDescriptor) {
 
     std::filesystem::remove_all(index);
 }
+
+// Coverage gap closed: a custom-namespace descriptor filed under a NON-canonical
+// filename must still resolve for a qualified request, because identity is the
+// declared (namespace, name) — never the filename (design doc
+// 2026-06-26-identity-first-resolution-no-filename.md, P0/P2).
+//
+// Real-world trigger: `aimol.tensorvia-cpu` declares namespace="aimol",
+// name="tensorvia-cpu" but is filed in the mcpplibs index as the BARE
+// `pkgs/t/tensorvia-cpu.lua` (canonical would be `pkgs/a/aimol.tensorvia-cpu.lua`).
+// Every prior fetcher fixture sat at its canonical path, so this seam was untested.
+// `read_xpkg_lua*` already keys on declared identity, so this asserts the READ
+// layer is correct and the production failure is isolated to candidate SELECTION
+// (`selectDependencyCandidate`'s canonical-filename-only strict reader).
+TEST(PmPackageFetcher, ResolvesCustomNamespaceDescriptorUnderNonCanonicalFilename) {
+    auto project = make_tempdir("mcpp-noncanonical-filename");
+    auto dataRoot = project / ".mcpp" / "data";
+
+    // Declared identity (aimol, tensorvia-cpu), but filed under the bare short
+    // name in the mcpplibs index — filename does NOT encode the namespace.
+    write_file(dataRoot / "mcpplibs" / "pkgs" / "t" / "tensorvia-cpu.lua",
+               R"(package = {
+                      namespace = "aimol",
+                      name      = "tensorvia-cpu",
+                      version   = "0.1.1",
+                      mcpp = { sources = { "*.cppm" } },
+                  })");
+
+    // Qualified request for the custom namespace must resolve, filename be damned.
+    auto hit = mcpp::pm::Fetcher::read_xpkg_lua_from_project_data(
+        project, "aimol", "tensorvia-cpu");
+    ASSERT_TRUE(hit.has_value())
+        << "declared (aimol, tensorvia-cpu) must resolve regardless of filename";
+    EXPECT_NE(hit->find("tensorvia-cpu"), std::string::npos);
+
+    // A foreign namespace for the same short name must NOT match it.
+    auto wrongNs = mcpp::pm::Fetcher::read_xpkg_lua_from_project_data(
+        project, "mcpplibs", "tensorvia-cpu");
+    EXPECT_FALSE(wrongNs.has_value())
+        << "the descriptor is (aimol, …), so a (mcpplibs, …) request must miss";
+
+    std::filesystem::remove_all(project);
+}