Background

PkgIdWithPatchHash is a branded string type in upstream pnpm — type PkgIdWithPatchHash = string & { __brand: 'PkgIdWithPatchHash' }. Per CLAUDE.md's "Porting branded string types" section (rule 3 — non-validating brand → infallible newtype), pacquet should have a wrapper.

Today pacquet uses plain String for this value in:

• crates/package-manager/src/virtual_store_layout.rs (since feat: .modules.yaml #332 / earlier)
• crates/package-manager/src/hoisted_dep_graph.rs (since feat(package-manager): hoisted dep-graph type skeleton (#438 slice 4a) #478)

Both call sites need the same type, so introducing the newtype in just one is intra-pacquet inconsistency — Coderabbit flagged it on #478.

What to do

1. Add PkgIdWithPatchHash as a non-validating newtype (model on the existing pacquet_modules_yaml::DepPath: #[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize, From, Into)] #[serde(transparent)] pub struct PkgIdWithPatchHash(String);).
2. Decide its home crate. Candidates:
   • pacquet-lockfile — alongside the other branded types ported from @pnpm/types (PkgName, PkgNameVer, PkgNameVerPeer, PkgVer).
   • pacquet-modules-yaml — alongside DepPath, which is the closest existing peer.
   • A new shared "types" crate. Probably overkill until a third consumer appears.
3. Update crates/package-manager/src/virtual_store_layout.rs and crates/package-manager/src/hoisted_dep_graph.rs to use the newtype.
4. Audit the rest of the workspace (grep "pkg_id_with_patch_hash") and migrate any remaining String-typed slots.

Out of scope

• Renaming the underlying string format (still <pkg_id>:<integrity> or <pkg_id>:<resolution-hash> per createFullPkgId).
• Validating the input. Upstream doesn't, so the wrapper shouldn't either (matches CLAUDE.md rule 3).

Written by an agent (Claude Code, claude-opus-4-7).