Repository navigation
id(world-manifest): module_hash documentation names a blake3:<hex> form that validate rejects — a world.toml written per the docs fails to parse #2166
Description
Summary
pkgs/id world manifest: the only documented format for module_hash is rejected by the manifest's own validation. The field's rustdoc says the hash is written blake3:<hex>, but WorldManifest::validate accepts only 1–64 hex digits — a blake3:-prefixed value is 71 characters for a real 32-byte hash and contains non-hex characters (:, and the letters in blake3 beyond a–f), so any world.toml written by following the documentation fails to parse, and id world diff / id world apply refuse it.
Evidence (main c58507a3, verified this run)
pkgs/id/src/world_manifest.rs:29— field doc: "A content hash of an already-installed module (blake3:<hex>)."pkgs/id/src/world_manifest.rs:182-189— validation:!hash.is_empty() && hash.len() <= MAX_NAME_BYTES && hash.bytes().all(|b| b.is_ascii_hexdigit()), with the error "module hash must be 1 to 64 hex digits".MAX_NAME_BYTES = 64(pkgs/id/src/world_caps.rs:60).- The live producer is plain hex with no prefix:
pkgs/id/src/world_session/mod.rs:657-659module_hash()isiroh_blobs::Hash::new(wasm).to_string()(64 hex chars), and the world-fixture doc also describesmodule_hashas"<hex>"(pkgs/id/docs/2026-10-17T09-00-00Z_feature_world_fixtures/…md:20). Theblake3:form appears nowhere else insrc/or the docs. - Verbatim-predicate probe (the exact
validexpression fromvalidate, compiled and run on the laptop,~/git/fleet/probe-2026-10-29-manifesthash/):- plain 64-hex (the live form):
valid=true - documented
blake3:<64 hex>(71 chars):valid=false blake3:abc123(short):valid=false
- plain 64-hex (the live form):
So the documented form fails on both independent grounds: length (71 > 64) and charset.
Why it matters
world.toml is the declarative interface for reconciling a live world (id world apply / id world diff, pkgs/id/src/cli.rs:1730-1759). An operator who copies the documented hash form into a manifest gets a parse failure before any step is planned, with an error that contradicts the documentation they followed. One of the two sides is wrong, and until they agree, the documented interface is unusable as written.
Acceptance criteria
- Triage pins the canonical form (the evidence points to plain hex: the live producer, the fixture doc, and the existing tests in
world_manifest.rsall use bare hex; accepting/stripping ablake3:prefix is the alternative). - The rustdoc on
WorldManifest::module_hashandvalidate's rule/error message agree on exactly one accepted form. - A test in
world_manifest.rscovers the pinned form: the documented example parses (or, if the doc is corrected, a regression test shows the previously documentedblake3:form's behaviour is the intended one and the doc no longer names it). - No change to plan/apply semantics for manifests that already parse.
Dedup
Searched open + closed for world_manifest, manifest module_hash, world.toml, blake3 prefix: #1517 (closed) was the empty-string case of the same validator and is fixed on main; #817/#1519 are plan/diff semantics. None covers the documented-prefix mismatch.
Activity
developing-today commentedon Oct 29, 2026
CODE-1059
dezren39 commentedon Oct 29, 2026
🤖 Agent note · filed
blake3:<hex>module_hash form fails WorldManifest::validate on both length (71 > 64) and charset, while the plain 64-hex form the live producer emits passes. NOT self-solved: which side is canonical (fix the rustdoc vs accept/strip the prefix) is triage's pin.6 remaining items
dezren39 commentedon Nov 1, 2026
🤖 Agent note · picked up
WorldManifest::module_hashrustdoc to plain hex and add parsing regression coverage for valid 64-hex and rejected prefixed forms.id(world-manifest): document module_hash as plain hex, not blake3:<hex>
dezren39 commentedon Nov 1, 2026
🤖 Agent note · done
WorldManifest::module_hashnow names the plain-hex canonical form (1 to 64 hex digits, noblake3:prefix); regression testmodule_hash_uses_plain_hex_without_a_blake3_prefixpins it (64-hex parses;blake3:abc123and 71-char prefixed values rejected). validate/producer/plan semantics unchanged.cargo test --lib world_manifest(pkgs/id) — 18 passed, 0 failed; Codex review on PR head ecd8b2f completed with no findings.