packages: recover binary index identity from archive manifests

.github/actions/detect-change-scope/ci-scope-paths.sh

@@ -14,7 +14,7 @@ package_archive_changed_files() {
     -e '^sdk/(activate\.sh|config\.site|package(-lock)?\.json|tsconfig\.json)$' \
     -e '^sdk/(bin|kandelo|src)/' \
     -e '^tools/xtask/Cargo\.toml$' \
-    -e '^tools/xtask/src/(archive_stage|archive_stage_cli|build_deps|host_tool_probe|main|pkg_manifest|source_extract|util)\.rs$' \
+    -e '^tools/xtask/src/(archive_stage|archive_stage_cli|build_deps|host_tool_probe|main|package_archive_name|pkg_manifest|source_extract|util)\.rs$' \
     -e '^tools/mkrootfs/(bin|src)/' \
     -e '^tools/mkrootfs/(package(-lock)?\.json|tsconfig\.json)$' \
     -e '^crates/fork-instrument/(Cargo\.toml|src/)' \
@@ -49,7 +49,7 @@ package_publish_flow_changed_files() {
     -e '^\.github/actions/detect-change-scope/(ci-scope-paths|test-ci-scope-paths)\.sh$' \
     -e '^\.github/workflows/(staging-build|prepare-merge|activate-merge-candidate|recover-rejected-merge-candidate|staging-cleanup|force-rebuild|reusable-package-source-publish)\.yml$' \
     -e '^\.github/scripts/(activate-merge-candidate|cleanup-merge-candidates|clone-rejected-merge-candidate|compose-staging-release-snapshots|download-verified-release-asset|fetch-canonical-index|github-api-get|init-merge-candidate|latest-merge-gate-status|mark-merge-candidate-ready|reconcile-merge-candidates|recover-canonical-indexes|require-exact-head-approval|select-package-archive-source|state-lock|test-activate-merge-candidate|test-cleanup-merge-candidates|test-clone-rejected-merge-candidate|test-download-verified-release-asset|test-fetch-canonical-index|test-init-merge-candidate|test-latest-merge-gate-status|test-merge-candidate-workflows|test-reconcile-merge-candidates|test-recover-canonical-indexes|test-require-exact-head-approval|test-select-package-archive-source|test-state-lock|test-validate-staging-release|test-verify-merge-candidate|validate-staging-release|verify-merge-candidate)\.sh$' \
-    -e '^tools/xtask/src/(build_index|bundle_program|index_candidate|index_toml|index_update|staging_reuse|update_pkg_manifest)\.rs$' \
+    -e '^tools/xtask/src/(build_index|bundle_program|index_candidate|index_toml|index_update|package_archive_name|staging_reuse|update_pkg_manifest)\.rs$' \
     -e '^scripts/(compose-initial-index|index-has-current-entry|index-update|prepare-sdk-package|publish-package-source|release-index-state|sync-package-source)\.sh$' \
     -e '^tests/scripts/(index-update|package-publish-flow|release-index-state)\.sh$' \
     || true

.github/actions/detect-change-scope/test-ci-scope-paths.sh

@@ -40,6 +40,9 @@ assert_not_matches() {
 assert_matches package_archive_changed_files \
   "tools/xtask/src/build_deps.rs" \
   "tools/xtask/src/build_deps.rs"
+assert_matches package_archive_changed_files \
+  "tools/xtask/src/package_archive_name.rs" \
+  "tools/xtask/src/package_archive_name.rs"
 assert_not_matches package_archive_changed_files \
   "tools/xtask/src/remote_fetch.rs" \
   "tools/xtask/src/remote_fetch.rs"
@@ -105,6 +108,9 @@ assert_matches package_publish_flow_changed_files \
 assert_matches package_publish_flow_changed_files \
   "tools/xtask/src/index_candidate.rs" \
   "tools/xtask/src/index_candidate.rs"
+assert_matches package_publish_flow_changed_files \
+  "tools/xtask/src/package_archive_name.rs" \
+  "tools/xtask/src/package_archive_name.rs"
 assert_matches package_publish_flow_changed_files \
   "tests/scripts/index-update.sh" \
   "tests/scripts/index-update.sh"

docs/binary-releases.md

@@ -392,6 +392,15 @@ sha for that manifest. Two archives with the same `(name, version,
 revision, arch)` but different transitive deps get distinct shas
 and thus distinct names.
 
+The filename is a transport label, not a parseable identity record:
+package names and versions may both contain `-`, so the boundary between
+them is ambiguous in the string alone. Index composition reads `name`,
+`version`, `revision`, architecture, ABI compatibility, and cache key from
+the archive's validated `manifest.toml`, then requires the filename to equal
+the canonical string reconstructed from those fields. Archive creation and
+index recovery call the same renderer so the producer and validator cannot
+drift to different filename grammars.
+
 ### Archive interior layout
 
 Each `.tar.zst` carries exactly two top-level entries:
@@ -637,10 +646,16 @@ checklist.
 When migrating a release from the legacy schema (or recovering after
 a corrupted index), `scripts/compose-initial-index.sh
 <target-tag> <abi>` downloads every `.tar.zst` from the release,
-extracts each archive's internal `manifest.toml` to recover
-`cache_key_sha` + `build_timestamp`, and uploads a freshly composed
-`index.toml`. The script acquires the same state-lock as the
-matrix-build path, so it serializes against any active CI rebuilds.
+extracts each archive's internal `manifest.toml` as the authoritative
+package identity and compatibility record, verifies that the archive's
+filename is the canonical rendering of those fields, and uploads a freshly
+composed `index.toml`. The script acquires the same state-lock as the
+matrix-build path, so it serializes against any active CI rebuilds. It does
+not infer the package name or version by splitting the archive filename. If
+the downloaded inventory contains more than one archive for the same package
+name and target architecture, composition fails and reports both filenames,
+cache keys, and archive hashes. Recovery must select one explicit immutable
+archive rather than depend on directory traversal order.
 
 Day-to-day publishes don't use this script — they go through
 `scripts/index-update.sh` per-matrix-entry. compose-initial-index is

scripts/compose-initial-index.sh

@@ -9,9 +9,10 @@
 #
 #   1. Downloads every *.tar.zst archive from the release.
 #   2. Runs `xtask build-index` against the downloaded set, which
-#      decompresses each archive, parses its internal manifest.toml's
-#      [compatibility] block, and emits a Success entry per
-#      (package, arch).
+#      decompresses each archive, uses its internal manifest.toml as
+#      the package identity, verifies the canonical transport filename,
+#      rejects ambiguous duplicate (package, arch) archives, and emits a
+#      Success entry per unique identity.
 #   3. Publishes the composed index through the crash-recoverable canonical
 #      release-index transaction.
 #

tools/xtask/src/archive_stage_cli.rs

@@ -122,7 +122,7 @@ pub fn run(args: Vec<String>) -> Result<(), String> {
     fs::create_dir_all(&parsed.out_dir)
         .map_err(|e| format!("mkdir {}: {e}", parsed.out_dir.display()))?;
 
-    // Filename convention (single source of truth for archive naming):
+    // Filename convention (rendered by package_archive_name):
     //   <name>-<v>-rev<N>-abi<N>-<arch>-<short8>.tar.zst
     // The `<short8>` suffix is the first 8 hex chars of the cache_key
     // sha so a freshly-published archive is content-addressable from
@@ -190,29 +190,19 @@ pub fn run(args: Vec<String>) -> Result<(), String> {
 }
 
 /// Compute the canonical archive filename + path for a (manifest, arch,
-/// abi) triple under `out_dir`. The shape (`<name>-<version>-rev<N>-
-/// abi<N>-<arch>-<short8>.tar.zst`) is parsed by `build_index` to
-/// recover `(name, version, revision, abi, arch, short_sha)` when
-/// regenerating `index.toml`, so the formatter and parser MUST stay
-/// aligned.
+/// abi) triple under `out_dir`. `build_index` recovers identity from the
+/// archive's structured manifest and validates the transport filename with
+/// the same renderer; it never reverses an ambiguous `<name>-<version>` string.
 fn archive_path_for_sha(
     out_dir: &Path,
     manifest: &DepsManifest,
     arch: TargetArch,
     abi: u32,
     sha_hex: &str,
 ) -> PathBuf {
-    let short = &sha_hex[..8];
-    let archive_name = format!(
-        "{}-{}-rev{}-abi{}-{}-{}.tar.zst",
-        manifest.name,
-        manifest.version,
-        manifest.revision,
-        abi,
-        arch.as_str(),
-        short,
-    );
-    out_dir.join(archive_name)
+    out_dir.join(crate::package_archive_name::render(
+        manifest, arch, abi, sha_hex,
+    ))
 }
 
 /// Compute the cache-key sha for a manifest as a 64-char lowercase hex
@@ -626,6 +616,34 @@ index_url = "file:///tmp/wpk-nonexistent-binaries-abi-v{{abi}}/index.toml"
         assert!(short
             .chars()
             .all(|c| c.is_ascii_hexdigit() && !c.is_uppercase()));
+
+        let index_path = dir.join("index.toml");
+        crate::build_index::run(vec![
+            "--abi".into(),
+            shared::ABI_VERSION.to_string(),
+            "--generator".into(),
+            "archive-stage integration test".into(),
+            "--archives-dir".into(),
+            out_dir.display().to_string(),
+            "--out".into(),
+            index_path.display().to_string(),
+            "--generated-at".into(),
+            "2026-05-05T00:00:00Z".into(),
+        ])
+        .expect("build-index must accept archive-stage's canonical filename");
+        let index = crate::index_toml::IndexToml::parse(
+            &fs::read_to_string(index_path).expect("read composed index"),
+        )
+        .expect("parse composed index");
+        assert_eq!(index.packages.len(), 1);
+        assert_eq!(index.packages[0].name, "z");
+        assert_eq!(index.packages[0].version, "1.0.0");
+        assert_eq!(
+            index.packages[0].binary[&TargetArch::Wasm32]
+                .archive_url
+                .as_deref(),
+            Some(name.as_str())
+        );
     }
 
     #[test]