[Mikola Lysenko (mikolalysenko)]

Stack: PR 2a of the lock-model stack, based on #2002.

What changed

Every pnpm lock reader now reads entries through one walk, formats::pnpm::PnpmLock, and the readers and modes agree on four questions where they disagreed (lock-model divergences N4, N5 pnpm part, N12, N14).

• One entry walk. PnpmLock reads every document of the lock and tags each entry with its PnpmDocument (Project or Env), by its key line. InstalledPackages::from_lock_text (the store crawler's current-lockfile reader) is rebuilt on it, through a key-only walk (PnpmLock::parse_keys, no resolution parse) for the crawler's hot path. It keeps its last-wins name: / version: rule and its None cases. The vendored-uuid set is lazy (OnceLock). The hosted unwind's tarball evidence (patch/redirect/upstream/npm.rs) reads PnpmLock::parse(text).packages_of(Project). It keeps "project documents only" because the env document records bare resolutions whatever the setting. pnpm_packages is now private.

• Documents identified by position and content (N4). grammar::main_document (the text after the last ---) is removed. grammar::documents splits at column-0 --- lines. In a lock with two or more documents, the first document is the env document when its importers: carry only configDependencies / packageManagerDependencies (at least one). That is pnpm's own position rule, and the one split_project_document in the vendored planners uses. Every other document, including an env-shaped later one, is a project document, so an extra document can't hide entries or opt out of the project tree's contests. lock_text_has_member_importers and pnpm_settings_major use the same split.

• The env document is its own install tree (owner decision, N4). The inventory lists env-document packages (LockfileEntry::pnpm_env), and discovery emits refs for Socket wiring in it. Both vendored in-use checks read both documents: the v9 check already read the whole text, and the legacy check now does through PnpmLock. Discovery records carry an explicit TreePart (File or PnpmEnv) beside the real lock path (PatchedRef, ResolvedElsewhere, UnpatchedCopy, UnwiredCopy scope), so no pseudo path ever exists. The contests compare it:

  • the env document's refs and the project document's registry entries, file: copies and bundled copies never contest each other;
  • env wiring doesn't exempt the project document from contesting another lock;
  • contest_across_locks skips the env tree in both directions, like PEP 723 script locks, because config dependencies install outside every node_modules.

  An env ref that the same file's project document also wires (same purl, uuid and mode) is dropped in finalize, so the two never both survive. Diagnostics name the env document <lock> (env lockfile).

• Rush locks always read (N12). The inventory reads Rush's common and subspace locks whenever rush.json exists, beside whatever lock the flavor router chose (inventory_npm_trees_raw_in). Before, it read them only when the root had no lock. The routed lock keeps its flavor alone, since Rush trees are no flavor's, and rush.json is stat'd once through the view. The Rush listing code is unchanged (Skip unsafe Rush subspace locks in the lock inventory #2003 aligns it separately).

• lockfile=false (N14). Discovery keeps a hosted ref from a lock pnpm won't read but withholds its lock pin. The inventory now does the same: under lockfile_disabled (not under Rush, as in discovery), it keeps a Socket-hosted pnpm entry (coordinates and hosted URL, which ledger liveness reads) and drops its integrity. Nothing then fetches or verifies against a pin the install doesn't use. Registry entries keep their integrity, because a registry release's hash verifies its content whether pnpm reads the lock or not. "Hosted" means the default Socket host here, since the inventory has no per-run origin list yet (PR 12).

• Hosted "vendored?" check uses origin::vendor_ref (N5, pnpm part). The hosted planner used a substring test over every line to tell a vendored dep from a missing one. It now reads the rekeyed packages entries (v9 <name>@file:<path>, or legacy bare file:<path> + name:, each with its version:) and checks <path> with crate::origin::vendor_ref. Both the name and the version must match the dep. The set is built once per lock. vendor_ref is pure path grammar, and the formats architecture test bans only I/O and hosted_patch_uuid*. It's the same rule discovery uses for vendored pnpm keys.

• Architecture guard. formats::pnpm::architecture_tests fails on any production use of grammar::entries / pnpm_packages / a hand-rolled packages: line walk outside formats/pnpm. It drops only #[cfg(test)] items (a mod x; line, or an inline item through its closing brace, counted outside comments and literals), so files that declare test modules early are scanned to their end. Writers that splice by position are allowlisted with a label and a use count:

  • patch/redirect/upstream/npm.rs ×2: the hosted unwind's resolution splices;
  • vendor/pnpm_lock.rs ×3: the v9 vendored planner;
  • vendor/pnpm_lock_legacy.rs ×6: the 5.4 / 6.0 vendored planner.

None of these changes reads a file outside the project root (owner decision on the repository root). lockfile_disabled reads the project's pnpm-workspace.yaml, .npmrc, node_modules/.modules.yaml, package.json and lock through the view; Rush locks are under common/.

Behavior changes

Each was checked to fail on the previous production code and pass here, except where noted. The formats::pnpm env/document tests and the finding 4 and 6 tests use APIs this PR adds, so on the base they fail to compile; their assertions encode the old behavior being reversed.

1. The env document's packages are read: inventory entries(), resolves() (get's pnpm-PnP narrowing in hosted mode), the legacy vendored in-use check, and InstalledPackages. Pinned by formats::pnpm::tests::env_document_is_read_as_its_own_tree, which replaces env_document_is_not_in_the_inventory (it pinned PnpmLock::parse inventories a pnpm 11 env-lockfile document's configDependencies as project packages, while InstalledPackages and the upstream evidence reader drop it #1949's skip, which the owner decision reverses).

2. Discovery emits env-document refs as their own tree, with no contest against the project document or another lock in either direction. Env wiring doesn't exempt the project document, and an env twin of a project ref is dropped. Pinned by vex::discover::npm::tests::pnpm_env_document_is_its_own_install_tree (LF and CRLF). On the base: refs: [].

3. Documents. A lock with several non-env documents reads all of them as project documents (before: only the last). Only the first document can be the env one. An entry is tagged by its key line. Pinned by formats::pnpm::tests::documents_are_identified_by_position_and_content, …::an_entry_with_an_empty_body_keeps_its_document and patch::redirect::upstream::npm::tests::pnpm_include_tarball_ignores_the_env_lockfile_document.

4. The hosted "vendored?" diagnosis. Each of these now gets redirect_pnpm_entry_not_found instead of redirect_pnpm_entry_vendored:

   • a file: path with no canonical uuid dir;
   • a path under another ecosystem's vendor dir;
   • an overrides: line with no rekeyed entry behind it;
   • another version of the package vendored.

   The backends' real v9 and legacy shapes stay "vendored". Pinned by patch::redirect::tests::pnpm_vendored_diagnosis_reads_the_rekeyed_entry_through_origin.

5. Rush locks are read beside a root lock and beside another family's lock. Pinned by vendor::lock_inventory::tests::rush_locks_are_read_beside_the_root_lock, which replaces root_pnpm_lock_wins_over_rush_fallback (it pinned the old shadowing).

6. lockfile=false drops a hosted pnpm entry's integrity in the inventory (.npmrc or pnpm-workspace.yaml; not under Rush). Pinned by vendor::lock_inventory::tests::pnpm_lockfile_off_withholds_hosted_pins.

7. The collapsed inventory never lets an env-document instance displace a project instance; the every-instance view keeps both. Pinned by vendor::lock_inventory::tests::env_document_instances_never_displace_project_instances.

8. Architecture guard. Pinned by formats::pnpm::architecture_tests::{pnpm_entries_are_read_through_the_model, production_drops_only_test_gated_items}.

Golden diffs

• vex-discover-golden corpus (committed_fixture_corpus_matches_golden): no change. No committed fixture has an env document. The renderer prints a ref's part only when it isn't File.
• tests/equivalence/pnpm_depscan_sized.golden: re-blessed.

  -0 782731128c8cd746 f3e10497dfc8fec6
  +0 b120df27c737dd90 1ab3b36d03d3b3f8
  

  The generated fixture's vendored entry was vendored-pkg@file:.socket/vendor/npm/vendored-pkg-1.0.0.tgz, with no uuid dir and no version: line, a shape the backend never writes. It now carries both, so the input digest changes, and the output digest changes with it because the output contains that text. Checked: the previous planner run on the new fixture produces the same blessed digests, so the planner's output on this fixture is unchanged.

Restack (2026-11-06)

Merge 097a538 brings in #2002's review fixes and #2001's later counter fixes. OriginPolicy is now imported from crate::origin, the patch::redirect re-export of the hosted-URL rule is gone, and the extractor, formats and lock_inventory guards are stricter. Nothing in this PR's code needed changing.

The merge also restores crates/socket-patch-core/src/origin.rs to the lock-readers group. The earlier routine merge had dropped it, inherited from #2002's 4242ebc. Counted with the fixed counter:

• lock-readers: 30,544 (Move the Socket origin classifier into one module #2002) → 30,767.
• lock-writers: 88,315 → 88,315.

The numbers in the Budget section below are from the old counter.

Tests after the restack:

• cargo test -p socket-patch-core --lib -- origin:: vex:: formats:: vendor::lock_inventory:: vendor::pnpm patch::redirect:: hosted::: 2,527 passed. That includes the golden test.
• clippy (workspace, all features): clean. fmt: clean.
• test_loc_budget.py: OK.

Budget

python3 scripts/loc-budget.py:

• lock-readers 30,976 → 31,207 (+231, raised by hand):
  • vex/discover/mod.rs +76: TreePart, its _in helpers, contest checks, env-twin drop
  • formats/pnpm/grammar.rs +52: content- and position-based documents / is_env_document, replacing main_document
  • vex/discover/npm.rs +35: one pass per document, PnpmTree
  • vendor/lock_inventory/npm_family.rs +31: Rush trees beside the routed lock, lockfile=false withholding
  • formats/pnpm/mod.rs +12: tagging, key-only walk
  • formats/pnpm/hosted.rs +6: the vendored check and its cache
  • pnpm_env: false in 21 LockfileEntry literals (+16)
  • vex/discover/testing/golden.rs +7
  • formats/pnpm/workspace.rs +6, lines.rs +1
  • vendor/lock_inventory/pnpm.rs −9 (no second rush.json stat), mod.rs −2
• lock-writers 88,314 → 88,314: −1 in the unwind, +1 in hosted/engine.rs (compares the tree part).

Tests run

• cargo test -p socket-patch-core --lib -- formats::pnpm vendor::lock_inventory:: vex::discover:: crawlers::npm_crawler patch::redirect:: vendor::pnpm hosted::: 2056 passed, 0 failed. This includes the discovery golden corpus and the pnpm equivalence goldens.
• cargo test -p socket-patch-core --lib -- vex::discover::testing::golden::tests::committed_fixture_corpus_matches_golden formats:: utils::pnpm_workspace vendor::yarn_layering_tests: 322 passed.
• cargo test -p socket-patch-cli --test in_process_redirect_pnpm --test in_process_vendor_pnpm_takeover: 41 + 15 passed. There is no pnpm_hosted test target; these are the in-process pnpm hosted and takeover suites.
• cargo clippy --locked --workspace --all-features -- -D warnings: clean. cargo fmt --all -- --check: clean. python3 scripts/loc-budget.py --check: ok.

Review findings (/code-review high)

1. Guard blind spot (fixed). production() cut each file at its first #[cfg(test)] mod, so files declaring out-of-line test modules near the top went mostly unscanned. It now drops only test-gated items. A self-test checks a violation deep in such a file, and that late production code of crawlers/npm_crawler.rs, patch/redirect/mod.rs and vendor/mod.rs is scanned. The fixed guard's count is unchanged.
2. Env document by content only (fixed). It must also be the first document. An env-shaped later document is a project one, and pnpm_settings_major no longer reports 11 for it. Both pinned; the crafted-extra-document case still reads every document.
3. Name-only vendored match (fixed). Name and version must match. Note: the removed check matched v9 keys by name only and the legacy overrides: line by name@version, so this tightens both.
4. Env instance displacing a project instance in the collapse (fixed) via LockfileEntry::pnpm_env and a project-first rank in dedup_prefer_integrity; inventory_project_every_lock keeps both.
5. Tagging by body offset (fixed). Entries are now tagged by their key line.
6. Pseudo-path tree key (fixed with an explicit key, not the exhaustive remap). TreePart is carried beside the real file on every record the contests read. The finalize remap is gone. An env ref twin of a project ref with the same purl/uuid/mode is dropped (the project one is the one an installed node_modules copy is verified against), so env/project refs no longer both survive with the same source_file. Not remapped because nothing ever holds a pseudo path: unlocked_pins, read, recognized, diagnostics. unidentified_copies are file-level (no pnpm extractor records one) and match File refs only.
7. InstalledPackages perf (fixed). Key-only walk, no resolution parse.
8. Hosted re-parse per unmatched dep (fixed). The vendored set is built once per lock and dropped when materialize replaces the text. The planner no longer materializes every lock for the check: a splice never touches keys or name: / version: lines.
9. Rush flavor label, double stat, shadowing (fixed). The routed lock keeps its own flavor (only tests read it; inventory_project ignores it). Rush trees are unioned beside it by inventory_npm_trees_raw_in. rush.json is stat'd once through the view, and the Rush reader no longer re-checks it.

Notes for review

• InstalledPackages reads every document. pnpm writes node_modules/.pnpm/lock.yaml as the project lock alone, and config dependencies install into node_modules/.pnpm-config, not the virtual store, so an env document isn't expected there. If one appears, its entries keep their store entries, which never hides an installed package.
• Listing env packages in the inventory means scan / get see config dependencies (and, under pnpm 12, the pnpm / @pnpm/exe.* package-manager entries) as lockfile-only packages at a would-be node_modules/<name> path. A Socket patch for a config dependency then shows as not installed in agent mode. This follows from the owner decision; whether the supplement should skip the env tree is a question for the install-tree PR.

Out of scope (later PRs): merging the hosted and vendored pnpm planners, shrinkwrap.yaml (N11, pending), gitBranchLockfile, vendored CRLF / lock-version support (N15, N16).

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

Burn-down agent: merged lock-model/1-origin (4242ebc) into this branch at 1d27a20 to clear conflicts (no force-push).

• docs/design/lock-model-divergences.md: kept this PR's "Resolved in PR 2a" detail for N4, N5, N12, N14 (now tagged Read pnpm locks through one walk (lock-model 2a) #2009) plus the base's PR links; N11 takes the base's owner decision (shadowed).
• scripts/loc-budget.json: the base's counter fix re-measured lock-readers at 30259; this PR grows it, so the max is raised to the new measured count, 30482.
• cargo check -p socket-patch-core --all-targets clean; cargo test -p socket-patch-core: 7126 passed, 4 failed. The 4 rely on unwritable files or symlinks and fail only because the container runs as root. The merge didn't touch them.

---

Generated by Claude Code