feat(pnpm): pnpm 7-12 vendor+hosted support — legacy grammars, zero-touch trustLockfile, takeover reconciliation, revert guards

[Mikola Lysenko (mikolalysenko)]

Closes the pnpm support gap end to end: every pnpm major since 7 now works in vendor and hosted mode, pnpm 11/12 hosted installs are zero-touch (no flags, no CI changes), and the conversion/revert/repair lifecycle around them is fail-closed. Everything here was built spike-first and verified against real corepack-pinned pnpm 7.33.5 / 8.15.9 / 9.15.9 / 10.34.5 / 11.22.0 / 12.0.0-rc.7 in the 2026-08-18 e2e campaign (54 matrix/probe legs), then adversarially reviewed (10 verified findings, all remediated in this diff, each RED-verified).

Stacked on #203 (lock-inventory legacy grammars — this diff extends the same file). Three test hunks overlap #204/#208 with identical content (env-var mirrors for the new global flag); merge those first and this rebases clean.

Hosted mode

• pnpm 7/8 locks are rewritten, not refused: every instance key of a dep is spliced (v5 /name/ver + _peer-suffixed, v6 parenthesized-peer; each key owns its own resolution:), one revert-ledger edit per instance. A post-splice residual detector refuses the dep set-wide if any instance shape the splice cannot claim remains — no partial rewrites (review finding: nested-paren suffixes provably unmatchable by the regex are now a refusal, not a silent skip). Proven: frozen installs from empty stores land patched bytes on real pnpm 7/8; tamper fails ERR_PNPM_TARBALL_INTEGRITY.
• Zero-touch pnpm 11/12: rewriting a v9 root lock auto-writes trustLockfile: true into pnpm-workspace.yaml (create-with-scaffold or byte-preserving merge; ledger edit redirect_pnpm_workspace_trust; --no-trust-lockfile-config opt-out). Hardened per review: only ErrorKind::NotFound creates (an unreadable existing file gets a warning, never an overwrite), and re-scans heal a missing config on already-redirected locks. Verified: pnpm 11.22 + 12-rc frozen installs succeed with no flags; 9/10 ignore the key; the sha512 pin still fails closed under trust. The warning names the actual spliced host (userinfo stripped, only spliced-lock hosts), both per-major error codes, and pre-empts pnpm 12's own pnpm clean --lockfile advice that silently unpatches; legacy locks get legacy-correct guidance (pnpm 7/8 reject --trust-lockfile).

Vendor mode

• New pnpm-legacy backend for 5.4/6.0 locks (flavor-stamped so older binaries fail closed on revert): package.json pnpm.overrides + lock surgery emitting byte-exactly what those majors serialize (idempotent under pnpm's own re-lock; byte-identical revert). Discovered + documented inherent limit: pnpm ≤ 8 absolutizes file: specifiers, so frozen installs are path-bound — surfaced as vendor_pnpm_legacy_absolute_specifier; a moved checkout runs one pnpm install --offline (marker bytes verified). Windows-shaped canonical paths normalized (verbatim prefix stripped, forward slashes; synthetic-input unit tests — a Windows CI leg should confirm pnpm's own emission spelling).
• Version allowlist keeps future lock versions refusing with version-aware remedies; vendor hints now name pnpm-workspace.yaml among committables and tell users to reinstall (the live tree keeps pre-vendor bytes by design).

Conversions, revert safety, repair

• Takeover reconciliation for npm-family (was cargo-only): vendoring over a hosted-redirected purl drops that purl's redirect-ledger halves — artifact-uuid-anchored matching (version-exact; v5 underscore instance keys claimed; degraded record-less ledgers keep edits fail-closed rather than risk destroying a sibling version's revert originals) — and vendor_supersedes_redirect fires exactly once. vendor --revert byte-restores the hosted lock from the wiring originals.
• Revert-brick fix (was silent data loss): all six npm-family backends now refuse to delete an artifact the live lock still references when a repair-reconstructed entry has no wiring (vendor_wiring_unknown_revert_blocked, recovery guidance included); repair stamps detected flavors so the right guard fires, and preserves corrupt artifacts when no rebuild source exists (forensics over ENOENT).
• Legacy-era diagnostics: shrinkwrap.yaml projects (pnpm ≤ 2) get pnpm-flavored no-lockfile guidance and join scan's lockfile-only supplement; a vendored lock entry gets redirect_pnpm_entry_vendored instead of a misleading entry-not-found; --mode redirect parses as the legacy alias of hosted.

Tests

• New e2e_redirect_pnpm_build.rs — the hosted capstone pnpm never had (npm/yarn/bun did): real corepack pnpm 7/8/9/10/11 legs (the pnpm 11 leg is the zero-touch proof + opt-out control), tamper negative, hermetic v5/v6 splice legs. 14/14 green locally including all gated legs.
• e2e_vendor_pnpm_build.rs ladder: Anson (@10) primary, @9/Doug Rudolph (@11) opportunistic, real pnpm 7/8 full-lifecycle legs (same-path frozen+offline proof, moved-checkout recovery, byte-identical revert).
• Reconciliation, residual-detector, trust-hardening, revert-guard, and flavor-stamping suites — RED-verified where behavior changed. Golden redirect fixtures byte-identical (shared with the TS backend, untouched).
• CLI_CONTRACT.md (new flag, warning codes, hosted pnpm contract, marker records) and docs/ecosystems.md updated.

Review status

Two adversarial review rounds ran over this campaign's diffs (10 + 10 verified findings); all are fixed here or in the sibling PRs #202/#203/#204/#208. Known accepted residuals are documented in code/PR-body where they live (rollback fan-out of patch-added files in store twins fails toward patched bytes; pnpm ≤ 3 custom non-registry.* hosts; Windows emission spelling needs a Windows CI leg).

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes lockfile and workspace mutation paths, redirect/vendor ledger persistence, and install-time pnpm trust behavior—high impact for CI installs but heavily covered by new e2e and contract tests.

Overview
pnpm hosted (scan --mode hosted) now rewrites lockfileVersion 5.4/6.0/9.0 grammars (not only v9), with pnpm-specific no-lockfile diagnostics and clearer warnings when a lock entry is already vendored. For root v9 locks, the CLI can auto-write trustLockfile: true into pnpm-workspace.yaml (ledger edit redirect_pnpm_workspace_trust), with heal-on-rerun when the lock was already redirected, safe handling of unreadable workspace files, and opt-out via new global --no-trust-lockfile-config / SOCKET_NO_TRUST_LOCKFILE_CONFIG. Legacy locks get guidance that does not recommend --trust-lockfile on pnpm 7/8.

Vendor / repair / mode switches: Documents and implements pnpm-legacy vendor flavor for 5.4/6.0 locks; post-vendor human hints name pnpm-workspace.yaml for pnpm ≥11 and suggest reinstall commands so node_modules catches rewired locks. When vendoring supersedes hosted redirects, npm-family purls can automatically drop matching halves from redirect-state.json (with reconciled vs manual warning text). repair stamps reconstructed ledger entries with the npm lock flavor from the referencing lockfile, moves vendor_wiring_unknown to run-level warnings[], and defers deleting corrupt vendor artifacts until a rebuild source exists.

Contracts & tests: CLI_CONTRACT.md and rollback JSON semantics (package_not_installed marker records) are updated; new e2e_redirect_pnpm_build.rs and expanded CLI/apply invariant tests pin trust config, splice grammars, and unmatched-purl exit behavior.

^{Reviewed by Cursor Bugbot for commit 2d49af0. Configure here.}