socket-patch architecture (living document): review, defect register and refactoring log

[Mikola Lysenko (mikolalysenko)]

Note

[agent] This is a living document. It is the October 2026 architecture review of the socket-patch CLI, kept current as we work through the code. The scheduled routines rewrite a section when a refactor lands or they find a new problem. Every E…/C… reference shows that problem's live status, taken from the register.

Progress: 148 problems tracked · 18 fixed · 5 partly fixed · 1 already fixed · 31 in PR · 72 filed · 6 decision pending · 11 to verify · 4 rejected. On GitHub: 104 open and 26 closed arch-audit issues · 24 open and 17 merged arch-refactor PRs.

• Register: the first comment below tracks every problem with its issue and status.

• Detail: Parts 2–9 follow as comments, and they are living too.

• Log: after Part 9, every routine run posts an entry.

• Work items: issues labelled arch-audit · refactoring PRs labelled arch-refactor

• Steering: reply here or on an issue. The routines read maintainers' replies on their next run.

• October 7 campaign: a one-day pass fixed the audit's critical defects and its duplicated business logic, one draft PR per seam, each deleting the duplicate copies it replaces: credentials redaction (Redact credentials from logged URLs, VEX product ids and hosted Composer locks #1026, C59), trust signals (Stop CI gates passing on missing paths, unverified agent patches and unreported hosted pins #1029, C61), JVM layout (Route JVM layout through one module and fix three JVM scope bugs #1032, E77), VEX attestation over PnP/bundled/deno copies (Stop VEX attesting over yarn PnP, pnpm bundled and deno.lock copies #1033, E72), one target grammar (Use one package target grammar for get, remove, rollback and the UUID shortcut #1034, C62), the supersede lifecycle (Replace a superseded patch generation's wiring on re-pin and remove #1035, E71), paths and repo roots (Share one path normalizer, home resolver and repository-root walk #1038, C64), an atomic takeover (Make the vendored-to-hosted takeover atomic #1039, E70), .socket containment (Guard .socket links and agent writes with one containment helper #1042, C60), command cycles and remedy text (Break command-module cycles and share remedy and UI text #1043, C65), governing locks (Decide which lockfile governs installs in one table #1044, E75), PurlKey (Compare purls through one PurlKey type #1045, C63), test hygiene (Keep test children off production telemetry and fail e2e legs that run no tests #1046, C66), vendored liveness (Decide vendored-entry liveness through one discovery verdict #1050, E74), the yarn grammar (Move all yarn.lock parsing into formats/yarn and stop pinning non-registry copies #1057, E08/E76) and one pinned check (Decide whether a hosted patch is pinned through lockfile discovery alone #1058, E73). Main went green again with Fix main CI red on stale digest pending-list entries #1016 (stale digest entries); Run CI on the merge queue and stop cancelling main push runs #1018 adds a merge queue and per-SHA push concurrency so it stays green (C67). Maintainer decisions still open: Decide: one shape for the --json top-level error (scan and get emit both a string and a {code, message} object) #704 exit policy, Decide: warn on and then remove scan --apply/--vendor, and whether --vex stays embedded #966 Q2 (embedded --vex), C34 and E44–E47.

Rendered 2026-10-07 20:56 UTC (ledger 9e9d018c) from doc/ on the arch-audit/ledger branch. The original snapshot is in review/2026-10/ on the same branch.

Architecture review of socket-patch v5: what to cut, combine, refactor and simplify

Originally written against main @ 2463257 ("feat!: consolidate the v5 patching workflow (#277)") on 2026-10-01. Since then, sections are updated as the code changes, and each part says when it was last checked against main.
Method: a read-only review split into seven areas: the CLI layer, hosted mode, JS lockfiles, vendored backends, discovery/VEX, core infrastructure and agent mode, and tests/CI/docs. Every area was measured with scripts: production and test lines are split at each file's inline #[cfg(test)] mod, and function lengths come from a brace-matcher that understands string literals. The highest-impact claims were then re-checked by hand against the source and a debug build. The 88 issues open at the snapshot were cross-referenced to architectural causes (Appendix A); on 2026-10-07 about 300 are open.
Layout: this post is the executive summary. The detailed findings, each with file:line evidence, are in the comments below:

• Part 2: CLI layer and UX
• Part 3: hosted mode
• Part 4: JS lockfiles
• Part 5: vendored mode
• Part 6: discovery and VEX
• Part 7: core infrastructure and agent mode
• Part 8: tests, CI and docs
• Appendix: open-issue analysis and methodology

All LOC numbers are measured or estimated as stated. Savings estimates come from the per-area reviews and overlap somewhat.

---

TL;DR

1. socket-patch is a product matrix implemented cell by cell. The matrix is 3 modes × 9 ecosystems × ~25 package-manager and lockfile generations × 6 operations (discover, apply/wire, verify, attest, revert, mode-takeover). There is no shared abstraction on any axis:

   • no lockfile codec;
   • no mode backend;
   • no vendor-backend trait;
   • no hosted-rewriter trait;
   • no single inventory.

   Each cell is hand-written text surgery. As a result, the same file format is parsed and spliced two to five times with different rules, and those rules have already drifted. For example, there are five different CRLF policies for the npm lockfile family alone.

2. Most of the open bug backlog has one shape: "reported success, but the build consumes unpatched code". Of the 88 issues open at the snapshot, roughly 29 were a success or a not_affected VEX attestation that the installed bytes don't back up (about 46 such false attestations are open on 2026-10-07; Stop VEX attesting over yarn PnP, pnpm bundled and deno.lock copies #1033 and Fix VEX attesting beside an unpatched same-lock copy (#935, #938, #939) #940 address the largest groups). Another 15 were discovery missing what the package manager actually installed. The root cause is architectural:

   • the tool re-implements package-manager behavior (install layouts, venv naming, config layering, resolution precedence);
   • it then reports success based on its own model of what the package manager will do;
   • every package-manager release or config knob it doesn't model becomes a silent false negative.

3. Support breadth has outrun the architecture. The long tail is disproportionately expensive:

   Long-tail target	Cost
   vlt	~6.5K production lines, ~22K total, ~123 CI jobs per push
   JVM (Maven/Gradle)	~9K production lines, 22 of the 88 open bugs
   bun.lockb	~2.8K production lines for a format Bun itself replaced
   vendored pnpm 7/8	1.85K lines, ~96% a copy of the v9 backend

   A support-tier policy would let the core get simpler.

4. The code is large for what it does, and much of the size is duplication and scaffolding.

   • ~134K lines of production code on 9c43dfc (~118K at the snapshot, plus 35K comment lines then).
   • ~450K lines of tests.
   • Nine functions over 500 lines; run_scan alone is 1,540 (on 045d7ec).
   • A 21.9K-line redirect/mod.rs on db83f01 (17.5K at the snapshot). E30 · filed Tracking: split patch/redirect/mod.rs into per-ecosystem modules and sibling test files #1010, Move patch/redirect/mod.rs's inline test modules into sibling test files #1011; tracking Tracking: split patch/redirect/mod.rs into per-ecosystem modules and sibling test files #1010, child 1 Move patch/redirect/mod.rs's inline test modules into sibling test files #1011 (inline tests out)
   • Two hosted orchestrators kept equal by parity tests.
   • Four discovery systems.
   • Nine different revert mechanisms. E24 · filed Tracking: revert every vendored backend through one record-revert engine instead of nine hand-written mechanisms #989, Finish every vendored revert through one shared helper with an explicit keep policy instead of 12 copied finish blocks #990; tracking Tracking: revert every vendored backend through one record-revert engine instead of nine hand-written mechanisms #989, child 1 Finish every vendored revert through one shared helper with an explicit keep policy instead of 12 copied finish blocks #990 (finish step ×12, four keep policies)
   • Two JSON envelope shapes, 27 global flags silently accepted by every command, and 156 documented error codes.

   We estimate 25–35K production lines (20–30%) and 50K+ test lines could go. Roughly 20K of that comes from consolidation that keeps every capability; the rest comes from the support-tier and product decisions in §5.

5. The user model is harder than it needs to be. It has:

   • 9 verbs, 2 hidden subcommands, 2 aliases and 3 hidden flag spellings;
   • defaults that change with unrelated flags;
   • scan writing lockfiles by default;
   • mode that is not project state: a plain scan performs the documented "mode takeover" and switches vendored npm, Cargo, Go, PyPI and Gradle-built Maven packages back to hosted (made atomic in Make the vendored-to-hosted takeover atomic #1039, E70);
   • remove, rollback and vendor --revert as three ways to undo.

   A seven-verb model (scan read-only, fix, undo, sync, check, list, vex) with mode inferred from the project would cover everything (§4).

6. There are a few real defects to fix now (§1), regardless of any refactor:

   • no HTTP timeouts on the main API client (fixed, Bound patch API connects and stalled reads (#570) #581);
   • a ledger-loss bug in the vendored→hosted takeover (fixed, Fix PyPI vendored→hosted takeover stranding unreachable pins (#699) #708);
   • a planted-binary spawn (fixed, Fix vendored Hatch running a planted hatch (#613) #617);
   • a comment-blind NuGet config reader (fixed, Unify hosted NuGet routing and XML splice anchors #597);
   • a stale digest ratchet that turned main red for every PR (fixed, Fix main CI red on stale digest pending-list entries #1016; a merge queue follows in Run CI on the merge queue and stop cancelling main push runs #1018).

   The October 7 audit added credential leaks (C59), .socket containment (C60) and the non-atomic takeover (E70); each has a PR. SOCKET_FORCE (Decide: give SOCKET_FORCE per-command names so forcing a self-update doesn't also force apply and vendor #615, PR Remove the SOCKET_FORCE env binding; --force is flag-only (#615) #1021) and the bun.lockb registry override (E02, fixed by Resolve vlt registry bases through one shared function (#562) #574) are no longer open defects.

---

0. The numbers

	Value
Production code (non-blank, non-comment)	134.5K lines in socket-patch-core + socket-patch-cli on 9c43dfc (2026-10-06; the same script gives 117.8K at the snapshot, which the review reported as 117.6K + 34.8K comment + 9K blank). The growth is mostly the Gradle landing (#646)
Inline #[cfg(test)] code in src/	~228K lines on 9c43dfc (~197K at the snapshot)
Integration tests (crates/*/tests)	~283K lines in 224 separate test executables in core + CLI (top-level files plus directory binaries; recounted at 9c43dfc, 2026-10-06; ~255K at the snapshot)
Test : production ratio	~2.8 : 1 overall; ~7 : 1 for the CLI crate
Largest file	patch/redirect/mod.rs: 21,936 lines at db83f01 (2026-10-07; 7.6K production, 14.3K inline tests; 17,517 at the snapshot, 6.2K production then)
Functions > 200 / > 500 lines	74 / 11 at 1c6c509 (61 / 9 at the snapshot: run_scan 1,540 on 045d7ec, now 1,577; rollback::run 984, vendor_records_reusing 962, run_redirect_selected 836, remove::run 797, get::run 635, memory engine 604, …)
CLI surface	9 visible + 2 hidden subcommands; 57 visible long flags; 27 globals on every command; 43 env bindings (84 SOCKET_* names in source); 156 documented errorCodes; ~570 code-like strings in source
--help	150–219 lines per subcommand; list --help lists 27 options, most of which do nothing for list
CI per push	~516 jobs; the CI workflow alone is 237 jobs and 348 runner-minutes; Windows test is the 28-minute critical path
CLI_CONTRACT.md	417 KB at 431b818 (2026-10-07; 415 KB at c5be5d1, 332 KB at the snapshot); the longest line is 12,077 characters at c5be5d1
Open issues	About 304 on 2026-10-07 after the October 7 campaign (~194 bughunt, ~94 arch-audit before nine new arch-audit issues #1061–#1069). At the snapshot: 88, filed mostly in the last 5 days by a bug hunt; JS 26, JVM 22, Python 18, Go 6, Cargo 5, NuGet 5, Ruby 3, Composer 3
PR size	Recent squash merges of +53K, +85K and +94K lines

---

1. Fix now (small, independent of any refactor)

#	Defect	Evidence	Fix	Status
1	Zip member inflate on committed artifacts (fixed)	zip_bytes_match_after_hashes now streams each member through the Git SHA-256 reader with an 8 KiB buffer and checks the declared length against the bytes read, instead of inflating it into a Vec (#587). The maintainer ruled that this data is trusted not to be too big, so the goal was streaming, not a cap.	The three archive caps (512/256/128 MiB) remain; see C15/C21.	C01 · fixed (#587); streams members, no cap per maintainer
2	No HTTP timeouts on the main API paths (fixed)	Both ApiClient reqwest clients now take api::retry::ApiTimeouts (10 s connect, 60 s idle read), and a stalled JSON body reports ApiError::Network (#581). Blob/diff downloads still have no retry.	One retry and timeout primitive for every HTTP path (Part 7).	C02 · fixed (#581); the retry half is C15
3	Vendored→hosted takeover drops the ledger entry on a drift-keep (fixed)	vendored_takeover now checks revert_keeps_wiring (kept_artifact, drift skips, residual references) after each revert and refuses the purl while keeping the ledger entry, like every other revert caller (#708).	The takeover still calls dispatch_revert_one directly rather than VendoredBackend (Part 2.4).	C03 · fixed (#708); revert_keeps_wiring refuses the takeover, #568 closed
4	Planted-binary spawn (fixed)	Vendored Hatch now resolves hatch through utils::process::resolve_tool_with and spawns it with command_for, so a hatch planted in the scanned repo no longer runs (#617). On 0d302dc no production bare-name Command::new("<tool>") remains.	Keep every spawn on resolve_tool (Part 7).	C04 · fixed (#617)
5	Comment-blind NuGet config reader in hosted mode (fixed)	Hosted routing and its splice anchors now read nuget.config through formats::nuget::parse_config, so commented-out <add key> entries are ignored (#597). The vendored nuget_feed.rs reader remains.	Move the vendored reader onto formats::nuget too (E10, #594).	E01 · fixed (#597)
6	SOCKET_FORCE is bound to three unrelated flags (decided)	vendor --force, apply --force and self-update --force. Exporting it to force a self-update also forces apply/vendor past hash checks.	Decided (#615): the SOCKET_FORCE binding is removed and --force is flag-only; the change is in PR #1021.	C05 · in PR #1021, #1031; decided 2026-10-07: SOCKET_FORCE binding removed (#615); v5 removes scan --apply/--vendor, get --no-apply, download, gc (#966); embedded --vex (Q2) undecided
7	bun.lockb registry override (fixed)	The duplicated npm tarball URL and NPM_REGISTRY spellings are now one helper, and vlt's two registry_base copies are one (#574). The format-1 URL that bun_lockb.rs synthesizes is lock semantics and is never fetched, so that part is not a defect.	—	E02 E03: 2 fixed
9	Credentials leak to logs, --json, telemetry and the patch host (October 7)	Hosted Composer keeps transport-options auth (#399); grant tokens and URL userinfo appear in warnings and debug output; the VEX product @id carries git-remote credentials.	One utils::redact for every URL shown or logged (PR #1026).	C59 · in PR #1026
10	.socket links and agent writes escape the project (October 7)	The symlink guard starts below .socket and guards deletes only (#887); get writes inline blobs through a planted link (#726); agent writes follow links out of the package.	One containment helper for every write (PR #1042).	C60 · in PR #1042; rollback of an overwritten file needs a pre-image store
11	The vendored→hosted takeover reverts before it plans (October 7)	A refused rewrite leaves the package patched in neither mode, and --dry-run predicts success.	Stage the revert, rewrite against the overlay, commit both together (PR #1039).	E70 · in PR #1039; dry-run residuals #668, #744, #891, #979 open
8	Repo hygiene	A stray .github/actions/actions/cache/<sha>/.vscode/launch.json (accidentally committed in #358); 2 dead CI path filters (CI janitor); 39 references in 20 files to a "DESIGN §x.y" document that isn't in this repository. The README now says plainly that its installer selects the latest release (verified on 045d7ec).	Delete or fix.	C08 · filed #649; README part already fixed

---

2. The big picture: why the code is the size and shape it is

2.1 No abstraction on any axis of the matrix

Axis	What exists today	What's missing
Format (package-lock, pnpm, yarn, bun, vlt, uv, poetry, pdm, pipenv, pylock, requirements, Cargo, Gemfile, composer, go.mod, NuGet, pom/Gradle)	A half-finished formats/ layer. Its module doc promises "entry grammar, key rules, version sniff and planners" per format; only pnpm, cargo, gem, composer and bun are partly there.	One codec per format: parse → model (with byte spans) → entries() / wired_refs() / splice(edits), used by every mode. Today package-lock has 4 entry walks, yarn has 5 copies of a split("\n\n")+regex grammar beside the shared block scanner, there are 8 hand-rolled XML scanners (no XML crate), Cargo.toml has a regex scanner and toml_edit inside one rewriter, and poetry/pdm lock code are near-twins.
Mode backend (hosted/vendored/agent)	Three booleans in run_scan, referenced 91 times; JSON and human arms that each re-dispatch all three modes.	trait ModeBackend { plan, consume, revert, verify }, with rendering only at the end.
Vendored backend (per ecosystem)	Naming conventions plus two macros (vend!, vend_installed!). The ecosystem list is enumerated at 16 production sites. Nine different revert mechanisms (~3.5K lines).	trait VendorBackend + a registry + one generic splice-record revert engine. The JVM planner (jvm/mod.rs) already is this design; copy it.
Hosted rewriter	Free functions in a hand-wired Vec<Box<dyn Fn>>. Results flow through a RewriteResult with 27 per-ecosystem uuid sets (20 at the review) and a 25-outcome confirm() if-chain. E31 · filed #1075, #1076; tracking #1075, child 1 #1076 (one report map, mechanical) Eight parallel tables must be edited to add an ecosystem.	trait HostedRewriter { drives(), rewrite() -> Outcome { per_dep: Map<Uuid, DepStatus> } }
Inventory	Four discovery systems: crawlers, lock inventory, wiring discovery (vex::discover) and a ledger supplement. They are merged by fabricating CrawledPackages with a fake node_modules/<name> path for every ecosystem.	One Inventory { instances: purl × declared_in × resolution (Registry/Hosted/Vendored) × installed_at }. Crawlers become locators.
Configuration	Parsed flags are written back into process env (args.rs:559 apply_env_toggles) so core can read them. Its doc comment records a bug where telemetry sent a Bearer token to the wrong host. This also forces 993 #[serial] test attributes (plus 185 in src). C10 · filed #793, #794; tracking #793, child 1 #794	An explicit RunCtx { config, client, telemetry, lock } built once in main.

Layering is inverted and cyclic (production crate::X:: reference counts):

From → To	Refs	Reverse	Refs
redirect → vendor	49	vendor → redirect	10
vex → redirect	16	redirect → vex	5
redirect → formats	19	formats → redirect	5

Other examples:

• 50 non-vendor files import crate::vendor::*, so vendor/ has become the codec library.
• Ecosystem and canonicalize_pypi_name live in crawlers/ (the latter is imported by 29 files).
• The "pure" formats/pnpm/hosted.rs imports the hosted engine's RewriteResult.

The CLI holds engine code.

• vendor_records_reusing (962 lines) is the vendored orchestrator.
• run_redirect_selected (836) is the disk hosted orchestrator, written a second time in core's hosted/memory (~1.3K lines of orchestration).
• ecosystem_dispatch.rs is 816 lines of crawler fan-out.

Commands call each other as libraries.

• There is a get ↔ scan cycle.
• get builds a fake ApplyArgs and calls apply::run_locked.
• Arguments round-trip GlobalArgs → DownloadParams → ..GlobalArgs::default(). On 045d7ec the reset fields are inert: the nested apply reads none of them except offline, which get and scan refuse up front.

2.2 The correctness model: "wired" is treated as "consumed"

The tool decides that a patch is applied, and VEX marks it not_affected, mostly from what it wrote. It does not check what the package manager will install:

• PatchedRef::lockfile_basis_ok lets an attestation stand with no installed bytes;
• agent mode patches the copy it located;
• hosted mode confirms the pin it spliced.

Every package-manager behavior outside that model becomes a silent false negative. The open backlog, by title, includes:

• warm caches shadowing the patch (Vendored and hosted NuGet patches are shadowed by a warm global packages folder: silently unpatched without a lock, NU1403 with one #352);
• go.work replaces overriding go.mod (A user replace in go.work silently overrides the Socket go.mod replace: Go apply and vendor report success and VEX attests not_affected while the build links the user's target #393);
• Bun's isolated linker (With Bun's isolated linker, vex attests a hosted patch as not_affected (verified) while the installed copy under node_modules/.bun is still unpatched (v5 regression) #405);
• deno.lock taking precedence over package-lock (Hosted npm pin in package-lock.json is attested by VEX in a Deno project, but deno.lock keeps installing the unpatched registry copy #406);
• --system-site-packages (In a --system-site-packages venv, pip keeps the base interpreter's unpatched copy after a hosted rewrite, no stale-install warning fires, and vex attests it as patched #409);
• Gradle dependency locking (Hosted Gradle snippet silently builds the unpatched jar in any project using dependency locking (gradle.lockfile), on every Gradle major and OS #396);
• Maven mirrors (Vendored Maven silently resolves the unpatched jar when an earlier <repository> or a mirrorOf * mirror serves the same GAV, and VEX still attests #263);
• BUNDLE_GEMFILE (Gem hosted redirect and setup ignore BUNDLE_GEMFILE from .bundle/config, so they wire Gemfile while bundler loads the configured manifest unpatched (VEX and setup --check still pass) #390);
• gems.rb beside Gemfile (Vendored gem mode wires Gemfile when gems.rb is also present, so bundler installs the unpatched gem while vex attests it #341);
• cargo reusing cached rlibs (Agent-mode cargo apply/rollback has no effect on an already-built project: cargo reuses the cached rlib from target/, while apply reports success and VEX attests not_affected #387);
• npm aliases (npm agent-mode apply never patches an npm-aliased install (lp@npm:left-pad), yet VEX attests the package not_affected #356) and inBundle copies (npm VEX attests not_affected while a bundled (inBundle) copy of the same package@version stays unpatched #325);
• NuGet globalPackagesFolder (Agent-mode NuGet apply patches ~/.nuget/packages instead of the project's configured globalPackagesFolder / RestorePackagesPath, reports success, and VEX attests not_affected #397).

Patching each case individually makes the model ever larger. Structural options, which can be combined:

1. Verify what the package manager consumes, not what we wrote.

   • Make the VEX default require consumed evidence: hash the copy the package manager actually resolved.
   • Downgrade wired-only evidence to "omitted, with a note", or put it behind an explicit --allow-wired-basis flag.
   • A false not_affected is worse than no statement, because the whole point of VEX is that scanners trust it.

2. Ask the package manager instead of re-implementing it wherever possible:

   • poetry env info -p, pipenv --venv, uv python find;
   • npm query/npm ls --json, pnpm list --json;
   • go list -m -json all, cargo metadata;
   • mvn dependency:list, dotnet list package --include-transitive.

   Today the crawlers re-implement Poetry's and Pipenv's venv-name hashing, npm/pnpm/yarn/bun global-prefix discovery, and the pnpm store layout, and those re-implementations are the source of the agent-mode discovery bugs (Agent-mode scan misses Poetry's venv for nameless non-package-mode projects, [project].name overrides, and in-project = false with a stray .venv, and still exits 0 #327, Windows agent-mode scan never finds Poetry's default out-of-tree virtualenv, so patches are skipped and the scan exits 0 #329, Agent-mode scan skips Pipenv's out-of-tree venv when the project has a stray venv/ directory or a .venv with PIPENV_VENV_IN_PROJECT=0, and still exits 0 #334, Agent mode ignores pnpm's virtualStoreDir: transitive dependencies are reported package_not_installed with a custom virtualStoreDir or the global virtual store #362, Bun isolated linker: transitive packages under node_modules/.bun are "not installed" in agent mode, and scan --mode agent exits 0 with them unpatched #366, Deno nodeModulesDir: transitive npm packages under node_modules/.deno are "not installed", and apply/scan exit 0 leaving them unpatched #373, Agent-mode scan patches the activated VIRTUAL_ENV even when PIPENV_IGNORE_VIRTUALENVS or PIPENV_ACTIVE tells Pipenv to ignore it, leaving the Pipenv venv unpatched with exit 0 #384).

3. Fail closed on unmodeled configuration. Detect the knobs that change resolution (go.work, gradle.lockfile, BUNDLE_GEMFILE, virtualStoreDir/enableGlobalVirtualStore, install-strategy=linked, repositoryPath/globalPackagesFolder, mirrors) and refuse or warn instead of reporting success.

4. Make "verify after install" a first-class step (socket-patch check) that CI runs after the package manager, with a non-zero exit when what was installed doesn't match what was wired.

2.3 Hosted rollback rebuilds data it threw away

v5 dropped the hosted ledger, so rollback/remove reconstruct the original lock entries from the network. That is ~7.4K production lines across about nine upstream sources, including a Socket endpoint that may download the whole upstream tarball. Meanwhile, every rewriter already computes FileEdit { original, new }, and production discards original, except in a Composer hint.

Failure modes:

• refused when offline;
• private registries and mirrors are ignored (npm restore always uses the public registry or SOCKET_NPM_REGISTRY);
• heuristic re-derivation of uv/poetry/pdm spelling;
• bun.lockb always refused.

That is 13 open rollback/takeover bugs (#271, #331, #382, #385, #407, #408, #410, #411, …).

Options:

• (a) Keep the originals in a tiny content-addressed sidecar, so rollback is byte-exact and offline. That is the same "record → splice back" model vendored mode uses.
• (b) Restore only where the original is a pure function of registry data (npm/pnpm/bun-text resolved+integrity, cargo cksum, go.sum, gem/composer/nuget hashes; ~2.2K lines), and refuse the rest with an exact git checkout -- <file> or relock command.

Either removes ~3.3K production lines.

2.4 Machinery that compensates for the per-package call model

Vendored backends are invoked once per package, and each call re-reads, re-parses and durably re-writes the same lockfile and ledger. Several mechanisms exist to make that fast and crash-safe again:

• group_commit.rs (1,059 lines), a process-wide virtual filesystem that intercepts every utils::fs read and write;
• durability.rs;
• prestage.rs;
• api/vendor_prefetch.rs;
• 22 process-global ParseMemo statics;
• ledger_snapshots.rs, the schema-v2 delta encoding added because whole-file snapshots bloated ledgers by tens of MB.

Together that is ~3K production lines. Backends written as pure batched planners (plan(view, pkgs) -> {writes, records}, as jvm/ already does) would retire most of it.

2.5 Process smell: nothing gets deleted

Several patterns show code that outlived its purpose:

• Refactor oracles kept forever: the verbatim 1,846-line old npm crawler, six more crawler oracles, 2.6K lines of redirect equivalence tests and 252 KB of goldens.
• Parity suites that exist only because two orchestrators exist.
• Covgap tests: 402 tests (26.9K lines), 136 of them asserting human text.
• Exact-sentence assertions: 328 of them. The output-polish PR touched 65 test files.
• Dead flags and vestigial abstractions: --vendor-source (one valid value), VendorSource/PackageSource (one variant each), PatchSources::mem_blobs (never Some; C23 · filed Delete PatchSources::mem_blobs, the single-variant VendorSource predicates, the redirect-state group-commit capture and the group_commit switch-off oracle #746; Pypi/LauncherCache channels are live (not dead)), lock_inventory/wired.rs (no production caller), pre-v5 redirect-ledger readers.
• History in reference docs: 177 v5.0 annotations in the contract.
• Very large squash merges: +53K, +85K and +94K lines.

Suggested norms:

• delete the oracle in the PR that lands the refactor;
• comments explain why; history lives in git and PR descriptions, and the CHANGELOG is written only when a release is cut;
• generate reference docs from code;
• cap PR size, or at least split mechanical moves from behavior changes.

---

3. Ranked recommendations

C = cut, M = combine/merge, R = refactor, S = simplify. LOC are production lines unless noted. Risk: L/M/H.

#	Type	Recommendation	Est. savings	Risk	Detail	Status
1	M	One codec per format in formats/ (package-lock → yarn → XML for NuGet/Maven/Gradle → requirements → Cargo.toml → Pipfile → pnpm single grammar), shared by hosted, vendored, upstream, inventory and VEX. Neutral types (Edit, Warning, LockfileEntry) move into formats, which breaks the cycles.	3–5K prod; removes the CRLF/indent/comment/divergent-gate bug class	M	Parts 3, 4, 5, 6	E07–E20: 2 fixed · 1 partly fixed · 3 in PR · 6 filed · 1 to verify · 1 missing
2	R	VendorBackend trait + registry + one generic splice-record revert engine, with backends as batched pure planners (the JVM pattern). Legacy ledger kinds are adapted at load time.	6–8K prod (incl. ~2K of the group-commit/prestage/memo machinery)	M	Part 5	E21 E22 E23 E24 E25 E27: 1 in PR · 4 filed · 1 to verify
3	M	One Inventory fusing lock inventory, wiring discovery and the ledger supplement. Crawlers become project-scoped locators, with no whole-machine cache enumeration (~/.m2, ~/.nuget/packages, $CARGO_HOME, GOMODCACHE). Rename vex::discover to inventory::wiring.	2–3K prod; fewer API calls; fixes #265-class bugs	M-H	Part 6	E05 E36 E37 E38 E39 E40 E41: 6 filed · 1 to verify
4	C/S	Hosted rollback: an originals sidecar, or restore only pure-function formats and refuse the rest with an exact remedy	~3.3K prod, ~2K test	M	Part 3	E33 E45: 1 decision pending · 1 to verify
5	M	One hosted pipeline for disk and memory (DiskSnapshot → MemoryProject → redirect_root(view, selected, api, hooks)); parity suites become ordinary tests. Decide the napi addon's fate: if depscan adopts it, delete the TS rewriters; if not, delete the addon, hosted-bundle and the memory-only branches.	0.8K, or up to 4.8K prod + 4.6K test	M	Part 3	E32 E44: 1 decision pending · 1 to verify
6	R	Split run_scan into discover → select → consume → render; a RunCtx built once; a service layer in core so commands stop calling each other; HostedRewriter + Outcome; mechanical split of redirect/mod.rs.	1.5–2.5K prod	M	Parts 2, 3	C10 C11 C12 E30 E31: 5 filed
7	S	Command model (§4): read-only scan, fix, undo (folds remove + rollback + vendor --revert), sync, check; mode inferred from project state; per-command flags; delete deprecated spellings.	1.5–2.5K prod	M (MAJOR)	Part 2	C34 · decision pending; no decision issue filed yet
8	S	One JSON envelope and error shape (scan/get/rollback still emit an untyped error: a bare string on some paths, a {code, message} object on others; decided #704, option 1: always {code, message}; C14 · in PR #1027; decided 2026-10-07: top-level error always {code, message}; every self-enforced exit 2 through one usage_error); a typed code registry (enum Reason × Ecosystem) that generates the contract's code tables, with a freshness test.	0.3–0.6K prod; fixes ~43 undocumented codes (re-measured on 9c43dfc) and 1 phantom	L-M (MAJOR)	Parts 2, 8	C13 C14: 1 in PR · 1 filed
9	C	Support tiers (§5): bun.lockb write support → refuse with remedy; vendored pnpm 7/8 → refuse (or a dialect of v9); vlt pre-1.0 encodings; Maven single-POM backend retired; single poms go through the jvm/ planner (decided #973).	5–8K prod, 8–12K test	M (product)	Parts 4, 5	E26 E47: 1 in PR · 1 decision pending
10	C	Retire --download-mode and the diff path (decided #792, v5): diff re-downloads every blob anyway on a cold cache; delete the diff machinery, the flag and qbsdiff.	~0.4K prod, 1K test, −1 dep	L	Part 7	C25 · in PR #1049; decided 2026-10-07 (option A, v5): delete the diff path, --download-mode and SOCKET_DOWNLOAD_MODE outright; patch/package.rs stays
11	C	Delete verified dead/vestigial code: --vendor-source, VendorSource, PackageSource, vend_installed!, mem_blobs, lock_inventory/wired.rs, dead vlt ledger helpers, save_redirect_state + its group-commit entry, the empty Deno extractor, the switched_off("group_commit") oracle path.	~1K prod, ~1K test	L	Parts 4–7	E28 E41 C23: 3 filed
12	M	Utility consolidation: one HTTP retry/timeout primitive; one validated purl builder family (42 hand-built format!("pkg:…") and 24 prefix checks in production code); one digest/SRI helper set (fixing the sha256_hex name collision: one copy validates, three compute); one line-ending policy; one env-truthiness vocabulary (there are three); one UUID grammar (there are four).	1–1.5K prod	L	Parts 4, 7	C15 C17 C18 C19 C20 E16: 6 filed
13	C	Embedded --vex (15 flag instances on 3 commands, ~600 lines of glue, plus bypass sets that couple VEX correctness to each caller) → fix && vex -O.	0.6K prod	L (MAJOR)	Parts 2, 6	E42 C05: 1 in PR · 1 decision pending (spellings half decided #966)
14	S	Simplify per-package-manager auto-config: npm allow-remote (re-implements npm's ini and config layering, ~900 lines), pnpm trustLockfile (~450; three open corruption bugs), the vlt warm-tree heal (installed-tree surgery in a lockfile-only mode), parallel rewriter groups (benchmark them or drop them).	1–1.5K prod	M	Part 3	E34 · to verify; dead vlt ledger helpers in #782 (E58)
15	C	Self-update: keep the binary swap and the notifier (decided #983); harden it: retry, stall timeout, streaming download, live post-release test. Telemetry: one track(Event) + a shared client instead of 19 wrappers and ~45 token/org call sites.	~0.3K prod	L	Parts 2, 7	C22 C36: 1 filed · 1 rejected
16	M	Tests: 207 → ~25 binaries (needs RunCtx first, to drop the env-mutating #[serial]); a socket-patch-test-support crate (binary() is defined in 103 files, git_sha256 in 86, 14 divergent scrub_socket_env, and 10 test files with no env scrub at all); retire the oracles; triage covgap; snapshots instead of 328 sentence assertions.	15–25K test lines; minutes off the Windows critical path	M	Part 8	C30 C31 C32 E35: 1 filed · 3 to verify
17	C	CI: de-instrument the coverage legs and drop the LTO docker-base build where it gates nothing, keeping the gating Linux tests and the per-PR Docker e2e on PRs; PR e2e 157 legs → ~50 boundary versions; reusable compat workflow; no per-leg compiles; required checks plus a merge queue (#1018).	~150 fewer jobs per PR	L	Part 8	handed off to the CI janitor; merge queue C67 · in PR #1018; digest entries fixed (#1016); a ruleset with required checks and a merge queue needs org admin
18	S	Docs: a generated CLI reference plus ≤300 lines of contract prose; move ecosystem narratives into ecosystems.md and version history into docs/migrating-to-v5.md; decouple docs/testing from validation scripts.	—	L	Part 8	C33 · filed #948, #949; tracking #948 (folds in #678, #930), child 1 #949

Estimated total: ~25–35K production lines (20–30%) and 50K+ test lines. About 20K is pure consolidation (recommendations 1–3, 6, 8, 10–12, 14); the rest depends on the tier and product decisions (recommendations 4, 5, 9, 13; the self-update half of 15 was decided as keep, #983). Agent mode stays for every ecosystem (#1000), so its ~10K is not on the table. The per-recommendation numbers overlap: for example, recommendation 1 shares work with 2 and 9.

---

4. User experience: a simpler model

Today a new user has to learn:

• three modes;
• mode-dependent meanings of positional PATHs (project directories in hosted/vendored, installed-path globs in agent);
• defaults that shift with unrelated flags:
  • scan --prune and scan --global become report-only;
  • get --save-only and get --global become agent mode;
  • so get -g x patches files in place while scan -g only reports;
• scan mutating lockfiles by default;
• three ways to undo: remove, rollback, vendor --revert;
• two GCs that are different things: repair (alias gc), filed under "Agent mode" in help but also repairing vendored artifacts, and scan --prune;
• 27 options on every --help, most of them no-ops for that command;
• two JSON shapes and two styles of usage error.

Proposed command model:

Command	Does	Replaces
socket-patch scan	Read-only report: available patches, the project's current mode and state, stale or unverified wiring. Safe in any CI step.	scan --dry-run, list partially
socket-patch fix [TARGET…] [--mode hosted|vendored|agent]	Applies patches. No target means all; a target can be a package, PURL, CVE, GHSA or UUID. Mode is inferred from project state (hosted pins, vendor ledger, agent manifest); --mode chooses it for a fresh project, and switching an existing project's mode requires --mode explicitly.	scan (write), get, vendor (eject)
socket-patch undo [TARGET…] [--keep-state|--forget]	One reversal engine for every mode.	rollback, remove, vendor --revert
socket-patch sync	After-install step for agent mode: re-apply, repair artifacts, prune.	apply, repair/gc, scan --prune
socket-patch check	Every read-only verifier, including "does what the package manager installed match what we wired" (§2.2). Non-zero on drift.	vendor --check, apply --check
socket-patch list, socket-patch vex	Unchanged; VEX defaults to consumed evidence.

On top of that:

• per-command flags only, so a global flag that a command ignores becomes an error;
• one JSON envelope with a typed errorCode;
• a short, generated reference.

This is a MAJOR change. Because v5 is still a prerelease, now is the cheapest time to make it.

---

5. Support tiers (product decisions needed)

Candidate	Prod / test LOC	Signal	Proposal
bun.lockb writing (hosted + vendored)	~2.8K / ~3K + 1.6K CLI	The repo itself labels it "binary, legacy"; Bun ≥ 1.2 writes text bun.lock. The codec writes a private sktpnrm marker into an unused slot of the user's lockfile.	Refuse, with the remedy bun install --save-text-lockfile --frozen-lockfile --lockfile-only; keep a ~300-line read-only parser if inventory needs it.
Vendored pnpm lockfile 5.4/6.0 (pnpm 7/8, both out of maintenance)	1.85K / 3.2K	~96% a copy of the v9 backend. The absolute specifier means --frozen-lockfile only passes at the original checkout path, which undercuts the point of vendoring.	Refuse with "re-lock with pnpm ≥ 9", or merge it as a PnpmDialect.
vlt	~6.5K / ~6.1K + ~9.3K CLI; ~123 CI jobs per push	A very new package manager; supports pre-1.0 RC encodings. Architecturally the cleanest JS format (one codec).	Drop the pre-1.0 encodings now. Gate vendored vlt (the dir-artifact backend + heal, ~3K) on telemetry. Move the vlt sweeps to nightly.
JVM: two Maven backends + Gradle	~7.5K vendored + ~1.5K hosted/crawler	22 of the 88 open issues (25%), mostly XML text surgery and resolution semantics (mirrors, locking, checksums, multi-module).	Merge maven_repo.rs into jvm/ (Shape::Single); one XML scanner; scope the crawler to project dependencies, not all of ~/.m2. Consider labelling hosted Maven/Gradle "beta" until the backlog is under control.
Agent mode overall	~6.4K CLI + ~3.5K core	v5 defaults to hosted. ~15 open issues (appendix category B) come from re-implementing package-manager install layouts, mostly in agent mode.	Decided (#1000): keep agent mode for every ecosystem for now (status quo). Layout bugs are fixed one at a time; asking the package manager for layouts (§2.2) is a separate, unadopted proposal. C55 · rejected; #1000 (2026-10-07) chose option A: keep agent mode for every ecosystem for now, layout bugs fixed one at a time; #1000 closed
In-memory engine + napi addon	~4.8K / ~4.6K	"private": true, never released, built and smoke-tested on every PR.	Keep it only if the depscan backend replaces its TS rewriters with it; otherwise delete it.
Self-update binary swap	~1–2K / 3–5K	Only the standalone channel can use it, and it is the only updater for the Windows zip, which has no installer.	Keep (decided #983). Self-update is a first-class update path and the only updater for the Windows zip; improve it rather than remove it. C36 · rejected; #983 (2026-10-07): keep the --update swap and the notifier, harden them (retry, stall timeout, streaming, live test); #983 closed

---

6. Suggested sequencing

• Phase 0, this week: no behavior change except bug fixes.
  • §1 fixes 1–11 (the October 7 campaign PRs).
  • Recommendation 11 (dead code).
  • Required checks and a merge queue (Run CI on the merge queue and stop cancelling main push runs #1018), then the CI cost cuts (recommendation 17).
  • Re-triage the open issues that still describe the removed setup command (Composer setup rewrites a CRLF composer.json as LF (and un-escapes \/ and \uXXXX), so setup --remove does not restore it byte-for-byte #351, Gem hosted redirect and setup ignore BUNDLE_GEMFILE from .bundle/config, so they wire Gemfile while bundler loads the configured manifest unpatched (VEX and setup --check still pass) #390, npm apply exits 1 when every patch targets a platform-skipped optional dependency (fsevents, @esbuild/*), so the setup hook fails npm ci and npm install on other OSes #403).
• Phase 1, v5.x minors: internal restructuring behind the existing goldens and e2e suites.
  1. formats/ codecs, one format per PR, each PR deleting the duplicate walks it replaces.
  2. RunCtx, which also unblocks the test-binary merge.
  3. VendorBackend + revert engine.
  4. HostedRewriter + Outcome + the redirect/mod.rs split.
  5. One Inventory.
  6. The test-support crate and binary merge.
  7. The generated contract reference.
• Phase 2, v6 MAJOR (or before v5 GA, since it's still a prerelease): the user-facing changes.
  1. The command model and per-command flags.
  2. One JSON envelope.
  3. Removing deprecated spellings and embedded --vex.
  4. file as the default download mode.
  5. Support-tier refusals.
  6. Hosted rollback via the sidecar or narrowed restore.
  7. The VEX consumed-evidence default.
  8. The self-update scope decision.

Questions for owners:

1. Will depscan adopt the napi engine? That decides ~5K production lines.
2. What is agent mode's future?
3. Do we have telemetry on vlt, bun.lockb, pnpm ≤ 8 and Gradle usage, to set tiers?
4. Is wired-only VEX attestation an acceptable default?
5. Is a hosted-originals sidecar acceptable, or is "no .socket/ in hosted mode" a hard requirement?
6. Can v5 GA absorb the command-model change?

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

Architecture defect register

[agent] This comment is the living register of architectural problems in the socket-patch CLI. It starts from the October 2026 review, which the top post and Parts 2–9 below keep as a living document, and grows with what the scheduled audit routines find. The status column here drives every status shown in the living document. It is regenerated from the register/ files on the arch-audit/ledger branch on every push, so any edit made directly to this comment is overwritten.

Progress: 148 problems tracked · 18 fixed · 5 partly fixed · 1 already fixed · 31 in PR · 72 filed · 6 decision pending · 11 to verify · 4 rejected. On GitHub: 104 open and 26 closed arch-audit issues · 24 open and 17 merged arch-refactor PRs.

• Status: a row starts as to verify (taken from the review, not yet re-checked on main), then moves to filed #n, then in PR #n, then fixed (#n). Other statuses: partly fixed (#n) (a PR fixed part of it; the note names what remains), already fixed (#n), decision #n (blocked on an owner decision; decision pending when no decision issue is filed yet), handed off (moved to another routine, such as the CI janitor) and rejected. The progress line counts rows by the leading status word only.

• P: 1 = defect to fix now; 2 = foundation or high-leverage consolidation; 3 = later.

• Work items: open arch-audit issues · decisions needed · refactor PRs

• Routines:

  • audit-ecosystems covers formats, hosted, vendored, discovery and VEX.
  • audit-core covers the CLI layer, core infrastructure, agent mode, tests and docs.
  • refactor runs every hour. It picks the highest-leverage refactoring from this register, the living document and the open issues, and implements it as a PR against main.

  Their procedures are AUDIT.md and REFACTOR.md on the ledger branch.

• Steering: reply in this discussion or on an issue. The routines read maintainer replies on their next run.

Ecosystems and formats (audit-ecosystems)

Last updated 2026-10-07T18:54Z · main @ 05ecc6e

ID	P	Problem	Source	Issues	Status
E01	1	Hosted NuGet source mapping regex-scanned raw XML, so a commented-out <add key> changed the mapping.	§1 #5; 5.4	#561	fixed (#597)
E02	1	bun.lockb vendoring hard-coded registry.npmjs.org; the npm tarball URL and NPM_REGISTRY were spelled twice.	§1 #7; 4.4	#562	fixed (#574); partly not a defect
E03	1	vlt registry_base had two implementations with different fallback orders.	§1 #7; 4.4	#562	fixed (#574)
E04	1	Hosted-PyPI-URL recognition: Pipenv accepted any host and owned_url rejected path-prefixed origins and sdists (merged E49). Three recognizers remain: hosted_patch_uuid, hosted_pypi_reference/hosted_artifact_url, Pipenv owned_url.	5.4; new finding	#563	partly fixed (#572); three recognizers remain (re-checked 431b818)
E05	1	Cache crawls aren't project-scoped: cargo, go, maven, nuget and deno enumerate the whole machine cache, and scan sends all of it to the API (#265).	6.6	#595	filed #595; tracking, children #427, #265
E06	1	NuGet assets and cargo vendor/<crate>/Cargo.toml crawler reads weren't FIFO-safe.	6.6	#592	fixed (#602)
E07	2	package-lock has four entry walks (inventory, vendored, hosted, restore) with copied identity/skip rules and two pointer escapes. Target: one addressed walk. The serializer half was fixed by #357 (all writers use JsonLayout).	4.4; 4.7 E	#663	in PR #1008
E08	2	yarn has seven split("\n\n") + regex grammars beside scan_blocks (redirect/mod.rs ×5, upstream/npm.rs ×2); the grammar is decided three ways (B60) and the regex replacement is unescaped. Target: writers and restorers on formats/yarn.	3.7 #3; 4.7 D		in PR #1057; confirmed at 1c6c509 (7 splits)
E09	2	Yarn berry gates were written twice (cacheKey, mixed-EOL and compressionLevel refusals with different codes); hosted didn't gate a mixed-EOL root package.json (merged E51).	4.4; new finding	#629, #628	fixed (#657)
E10	2	XML has eight hand-rolled scanners and four attribute extractors; the writers (nuget_feed.rs, maven_repo.rs) never use the shared readers. Merged: NuGet config's three readers (was E11) and Maven's two declares_modules (was E55).	5.4; 3.7 #3	#715, #716, #717, #594	filed #715, #716, #717, #594; NuGet hosted reader fixed (#597)
E12	2	pnpm v9 and legacy 5.4/6.0 were near-copies; v9 still has two lookup paths (a linear scan and LockIndex, pnpm_lock.rs:1524-1538).	4.4; 4.5 #4; 4.7 B/G		partly fixed (#583); copies merged, v9 dual lookup remains (pnpm workstream, #1007)
E13	2	utils/poetry_lock.rs ≈ utils/pdm_lock.rs (identical *_lock_edits).	5.4	#694	fixed (#703)
E14	2	Pipfile.lock is written two ways: vendored mode re-serializes it, while hosted mode splices spans.	5.4		to verify; present on 045d7ec, no drift proven (pipenv writes canonical JSON), not filed yet
E15	2	Cargo.toml [package] is read five ways and has drifted on BOM, [project] and dotted keys; hosted plan_cargo_toml is a line scanner that refuses a multi-line features array (merged E57).	5.4; 3.7 #3	#693, #757	filed #693, #757
E16	2	CRLF has five policies in the npm family and three for toml_edit output; common::detect_eol contradicts LineEndings::Mixed; the "any \r\n → CRLF" rule is written 14 times and gradle::newline_of uses a first-line rule (merged E60). Target: one line-ending policy.	4.4; new finding	#814, #815	filed #814, #815; tracking #814, child 1 #815
E17	2	"Is a bun lock present" is asked at seven sites with three semantics (lstat, exists, is_file). With a dangling bun.lock symlink, Bun and the writers use bun.lockb, but the inventory returns nothing.	4.4	#735	in PR #1009
E18	3	JS helper copies: JSON-pointer escape ×2, wiring lines↔JSON ×3, name@spec split ×2, KIND_* re-spelled, uneven recursion bounds, regexes compiled per dependency.	4.4	#835	filed #835; wiring kinds + lines↔JSON codec
E19	3	Gem has three section models and three DEPENDENCIES-name parsers (vendored sees only the first GEM section, #779). Go's module readers were duplicated (fixed by #870).	5.4	#780, #781	filed #780; gem models open, go.mod module reader fixed (#870)
E20	3	Pure codecs (bun_lockb.rs, bun_lock_text.rs, vlt_lock_text.rs) and the neutral types live outside formats/, creating formats↔vendor/redirect/vex cycles.	2.1; 4.5 #2; 4.7 J	#833, #834	filed #833, #834; tracking #833, child 1 #834
E21	2	Tracking: VendorBackend trait + registry. The ecosystem list is enumerated at 16 production sites, and the vend! / vend_installed! macros stand in for the trait.	2.1; 5.2; 5.8	#959, #960	filed #959, #960; tracking #959 (enum dispatch first), child 1 #960 (revert/in-use)
E22	2	The JS vendor driver skeleton is copied seven times (guard_coordinates → … → a literal VendorEntry; pnpm legacy shares v9's since #583). Target: one generic driver + NpmLockBackend.	4.4; 4.7 C	#920, #922	in PR #1008; tracking #920 and child #922 both claimed (draft)
E23	2	The pypi_{poetry,pdm,pipenv}.rs backends repeat one skeleton: load_*_project, classify_dependency, check_target_guards, wire_*, revert_*.	5.4	#937	filed #937; shared wire/revert envelope + one LockTarget (no drift proven)
E24	2	There are nine revert mechanisms (~3.5K lines). Target: one splice-record revert engine, with legacy ledger kinds adapted at load.	2.1; 5.3; 5.8	#989, #990	filed #989, #990; tracking #989, child 1 #990 (finish step ×12, four keep policies)
E25	3	Per-backend copies: cleanup_failed_stage and <eco>_service_copy (cargo, composer, gem, golang).	5.4; 5.8	#906	filed #906
E26	3	JVM has two Maven backends. Target: merge maven_repo.rs into jvm/ as Shape::Single; its three artifact roots don't follow <eco>/<uuid>.	5.7	#971, #972, #973	in PR #1036; decided #973: one Maven backend, single poms as a reactor of one, legacy roots refused until vendor --revert
E27	3	The per-package call model needs ~3K lines of compensating machinery (group_commit, durability, prestage, vendor_prefetch, 22 ParseMemo statics, ledger_snapshots). Target: batched pure planners, after E21 and E24.	2.4; 5.7		to verify
E28	2	Dead vendored scaffolding: one-variant VendorSource/PackageSource, an unreachable SERVICE_ECOSYSTEMS refusal, ServicePolicy::new ignoring its config, an unused vend_installed!.	5.6; R11	#800, #746	filed #800, #746
E29	3	registry_fetch.rs (1.5K lines) is really archive extraction, integrity checks and the hosted-restore HTTP client, so it is misnamed and in the wrong place.	5.6	#1012	filed #1012; archive + Go module zip move; integrity (after #834) and registry bases (after #876) remain
E30	2	Split redirect/mod.rs (21.9K lines at db83f01: 7.6K prod, 14.3K inline tests) mechanically: model, driver, one file per ecosystem, hosted_url, sibling test files.	3.7 #1	#1010, #1011	filed #1010, #1011; tracking #1010, child 1 #1011 (inline tests out)
E31	2	Tracking: trait HostedRewriter + Outcome { per_dep }. It replaces 27 RewriteResult uuid sets, merge_group_delta and the 25-outcome confirm().	2.1; 3.7 #2	#1075, #1076	filed #1075, #1076; tracking #1075, child 1 #1076 (one report map, mechanical)
E32	2	There are two hosted orchestrators, disk (run_redirect_selected) and in-memory (hosted/memory), kept equal by parity tests. Target: one pipeline. Depends on E44.	3.3; 3.7 #4		to verify
E33	3	Upstream restore rebuilds originals from the network (~8.8K production lines at 1c6c509, ignores mirrors, re-pins integrity from the registry: B72). Target: an originals sidecar or a narrowed restore. Depends on E45.	2.3; 3.5		to verify
E34	3	Per-PM auto-config costs more than it's worth: npm allow-remote (~900 lines re-implementing npm config), pnpm trustLockfile, the vlt warm-tree heal, and the unbenchmarked parallel rewriter groups.	3.6; 3.7 #7	#782	to verify; dead vlt ledger helpers in #782 (E58)
E35	3	Retire the refactor oracles: the redirect equivalence suites and 252 KB of goldens, the crawler oracles (3K lines), and the telescoping entry points (use one RewriteOptions).	3.7 #9; 6.6		to verify
E36	2	Tracking: one Inventory. Today's four discovery systems are merged by fabricating CrawledPackages with fake node_modules/<name> paths. Rename vex::discover (it is the hosted-state store).	2.1; 6.2; 6.7		to verify
E37	2	is_safe_{cargo,gem,nuget}_coordinate are byte-identical and duplicate simple_purl's check. composer_crawler::normalize_version duplicates strip_leading_v.	6.4	#630	filed #630
E38	2	The product-manifest probe table is copied three times and has drifted: vex.rs lacks the csproj and gemspec probes. The probes don't reuse the format parsers.	new finding; 6.5	#816	filed #816; CLI probe-table copy (product_undetected message); parser reuse is #693/#781/#715; Gradle/sbt probes are E87
E39	3	canonicalize_pypi_name lives in crawlers/ (29 importers) and Ecosystem in crawlers/types.rs, while LockfileEntry.ecosystem is a string. Target: core/src/ecosystem.rs.	2.1; 6.4	#883	filed #883; Ecosystem move overlaps #773, #748
E40	2	vex_consumed.rs, in the CLI, is a third copy of package-manager layout knowledge; npm alias discovery is written twice (core alias_copies, vex_consumed) and drifts on case (merged E62). Target: per-ecosystem locators in core.	6.5; new finding	#855, #856	filed #855, #856; tracking #855; child #856 in PR #1008 (draft)
E41	2	Dead discovery code: lock_inventory/wired.rs has no production caller.	6.4; 6.5; R11	#801	filed #801; empty deno.rs extractor is deliberate, pre-v5 ledger readers are live migration
E42	2	The embedded --vex glue is copied per command (scan, apply, and vendor ×3), each with caller-injected bypass sets. Target: one EmbeddedVex helper.	6.5; R13	#966	decision #966; whether --vex stays embedded (Q2) is undecided
E43	2	Fail closed on unmodeled resolution config in one shared place.	2.2 #3	#458	partly fixed; gradle.lockfile, BUNDLE_GEMFILE, virtualStoreDir and mirrors are modelled, npm linked-store alias fixed (#987); go.work remains (#458, E81)
E44	2	Decide: the napi addon and in-memory engine. Will depscan adopt it (then delete the TS rewriters), or should it be deleted (−4.8K prod)?	§6 Q1; 3.7 #6		decision pending; no decision issue filed yet
E45	2	Decide: hosted rollback. Is an originals sidecar acceptable, or should restore be narrowed to formats whose original is a pure function of registry data?	§6 Q5; 2.3		decision pending; no decision issue filed yet
E46	2	Decide: VEX evidence. Should not_affected require consumed evidence by default, so that wired-only evidence (lockfile_basis_ok) needs an opt-in? About 46 open false-attestation issues (B05).	§6 Q4; 2.2; 6.5		decision pending; no decision issue filed yet
E47	3	Decide: support tiers for bun.lockb writes, vendored pnpm 7/8, vlt pre-1.0 encodings and hosted pnpm ≤ 6, and whether hosted JVM ships as beta.	§5; §6 Q3; 4.6		decision pending; no decision issue filed yet
E48	3	Discovery re-implements package-manager layouts (venv-name hashing, global prefixes, the pnpm store). Target: ask the package manager (poetry env info -p, pipenv --venv, npm query, …).	2.2 #2; 6.6		to verify
E50	2	Hosted rewrite_nuget and upstream restore rewrite packages.lock.json entries of the patched id at other versions (every framework); vendored locked_at filters by version. Four lock walkers.	new finding	#593	filed #593
E52	3	vendor/go_sum_edit.rs: free go.sum helpers have no production caller and are re-implemented by GoSumEditor; the pure hosted codec lives in vendor/.	new finding	#631	filed #631
E53	2	Vendored pnpm wrote the root package.json with serialize_json (lost CRLF, refused BOM).	new finding	#662	fixed (#810)
E54	3	Poetry and PDM lock rewriters restored line endings with two rules.	new finding	#695	fixed (#703)
E56	2	Lock inventory read only Gemfile.lock, so a gems.rb project's gems.locked was invisible.	new finding	#736	fixed (#750)
E58	3	Production pub fns with no production caller, orphaned by #277 (committed_artifact_intact, go_sum_edit::remove_lines, hosted-vlt ledger helpers, three test-only helpers).	new finding; 3.6	#782	filed #782
E59	2	Vendored gem edit_lock searched only the first GEM section.	new finding	#779	fixed (#805)
E61	2	The vendored-reference scan never saw NuGet, Maven or hatch.toml wiring, so the orphan sweep could delete a still-wired feed, repository or wheel (merged E67).	new finding	#832, #958	fixed (#1015)
E63	2	Hosted Maven splices the API maven_suffixed_version into pom.xml unchecked, while hosted Gradle refuses a malformed suffix (redirect_gradle_override_invalid); four suffix builders, no shared validator (executed twice).	new finding	#882	filed #882
E64	2	No shared BOM helper (4 strip_bom copies, ~50 inline strips); formats::pnpm's lockfileVersion readers skipped it (executed twice). Symptoms #903, #904, #623.	new finding; 4.4	#905	partly fixed (#909); pnpm readers skip the BOM, the shared helper remains (#905)
E65	3	Every vendored sink discards force/sources, yet vendor --force help and CLI_CONTRACT.md promise missing-file tolerance and a warning nothing emits (executed twice). Bears on #615.	new finding; 5.2	#923	filed #923
E66	2	Vendored Poetry picks its forward splicer by line ending (CRLF/legacy: utils::poetry_lock; LF 2.x: toml_surgery scanner); different files shapes, and only the engine checks wheel name and digest case (executed twice).	new finding; 5.4	#936	filed #936
E68	2	Vendored gem: forward treats any Gemfile containing the copy path as wired, revert needs the exact recorded line, and records revert non-atomically: a trailing comment leaves the lock restored and the Gemfile on path:, drift-keeping forever (executed 3×). Same class as #977.	new finding; 5.3	#988	filed #988
E69	2	"Is this an sbt/Mill/scala-cli build" is six marker lists (#690); a scala-cli dir with only .scala-build or an sbt root with only project/build.properties gets no Coursier roots (executed twice).	new finding	#1014	in PR #1032; defects A and B, the .mill-version rule remains
E70	1	The vendored→hosted takeover reverts first and plans later: a refused rewrite leaves the package patched in neither mode; the disk write isn't transactional (B14); the memory list drifts (B15); --dry-run counts every takeover (B37).	audit B03, B14, B15, B37	#945, #723	in PR #1039; dry-run residuals #668, #744, #891, #979 open
E71	1	The supersede/re-pin lifecycle has no owned-pin generation model: an older uuid's vendored entry, Cargo registry block, Go go.sum pair or Maven -socket.<hex8> repository survives a re-pin or remove.	audit B07	#999, #864, #682, #266	in PR #1035; #954 in #1008, #742/#650 in #943
E72	1	VEX attests not_affected from wiring the package manager doesn't consume: yarn Plug'n'Play loaders, pnpm bundled copies and deno.lock npm copies.	audit B04, B05	#519, #406	in PR #1033; Maven integrity_required = false waits on E46
E73	2	"Is this hosted patch pinned" is decided four ways (confirm, mark_pinned, memory_recorded, discovery); lockless NuGet/Cargo pins are attested in-run, then reported contested forever with a looping remedy.	audit B13, B58	#567, #260	in PR #1058; lockless pins wait on E45
E74	2	"Is this vendored entry still in use" has four answers; six ecosystems' entries are never pruned and scan resurrects them; JVM orphans are invisible unless the ledger is empty; legacy Maven/NuGet "wired" is a substring check.	audit B19, B61, B62		in PR #1050
E75	2	Which lockfile governs installs is decided in ≥8 places; vendored and hosted patch different PyPI locks and a takeover restores the losers unpatched.	audit B31	#612	in PR #1044; vlt and Pipenv precedence policy needs a maintainer call
E76	2	Hosted yarn classic replaces file:, URL and codeload copies with the Socket artifact and rollback corrupts the key; there is no shared copy-source classifier.	audit B16		in PR #1057
E77	2	JVM layout is spelled in ~13 places with two coordinate grammars; --ecosystems maven skips jvm ledger entries (B17); service_preflight grants downloads the backend then skips (B18); sbt roots with only project/build.properties get no crawl (B65).	audit B17, B18, B65	#1014	in PR #1032
E78	1	pnpm readers and writers ignore ---, so a two-document pnpm 11+ lock gets the wrong document edited and success reported.	audit B06	#466	in PR #1007 (pnpm workstream)
E79	2	Hosted mode meeting a vendored package has 4+ outcomes per ecosystem (auto-takeover, refusal, Composer rewrites in place, NuGet socket-patch-<uuid> key collision). Target: one pre-rewrite decision. Depends on C34.	audit B30	#536	filed #536
E80	3	The gitignore guard for vendored artifacts covers npm and sbt/Coursier only; Maven .jar and NuGet .nupkg are dropped by stock templates.	audit B32	#1061, #620	filed #1061, #620
E81	2	Go writers ignore go.work and go env -w, and leave a read-only module-cache copy on Windows.	audit B34	#458, #393, #531, #343, #344, #391, #392, #549, #618, #346	filed #458 and 9 symptom issues
E82	2	Cargo dual-source registries and a user's own [patch.crates-io] aren't modelled.	audit B35	#480, #506, #679, #863	filed #480, #506, #679, #863
E83	3	The Maven reactor re-implements the effective POM (properties, BOM imports, parents, profiles).	audit B36	#459, #488, #513, #535, #550, #584, #622, #655	filed #459 and 7 symptom issues; Maven is lower priority (maintainer triage)
E84	2	Composer vendor-dir and global-home resolution ignore the global config and the XDG home.	audit §5	#439, #586	filed #439, #586
E85	3	Hosted NuGet forward and restore write packages.lock.json with LF, 2-space and no BOM; every other hosted JSON writer keeps the layout.	audit B59	#1068, #623	filed #1068
E86	3	Vendored JVM fetches upstream artifacts and checksums only from Central or SOCKET_MAVEN_REGISTRY, ignoring mirrors and the build's repositories.	audit B63	#1069	filed #1069
E87	2	VEX product detection has no Gradle or sbt probe, and scan --vex resolves the product only after writing.	audit B64	#1064	filed #1064
E88	3	Small duplicates: hosted patch origins, max-severity ordering, "ecosystem filter is empty", and the inventory matching vendored-router refusal-code strings (#975).	audit §3.A, §3.B	#975	to verify
E89	3	Pure-wheel rule written 4× (inventory and recovery skip wheel_platform_from_filename); recovery's uv.lock scanner pairs a hashless pure wheel with another wheel's hash (executed twice).	new finding	#1079	filed #1079

Handed off: none yet.

Rejected / not a defect: E02, in part: the bun.lockb format-1 URL synthesized at bun_lockb.rs:235 is lock semantics and never fetched; the duplicate spellings were folded into #562.

Already fixed: none.

CLI layer, core infrastructure, agent mode, tests and docs (audit-core)

Last updated 2026-10-07T17:49Z · main @ 431b818 (October 7 reconciliation; duplicate rows merged)

ID	P	Problem	Source	Issues	Status
C01	1	Unbounded zip inflate in zip_bytes_match_after_hashes on committed .nupkg/.jar files and service archives.	§1 #1	#569	fixed (#587); streams members, no cap per maintainer
C02	1	ApiClient::new and plain_client() set no HTTP timeout, so scan, get and apply could hang in CI.	§1 #2	#570	fixed (#581); the retry half is C15
C03	1	vendored_takeover ignored RevertOutcome.kept_artifact on a drift-keep.	§1 #3; 2.4	#568	fixed (#708); revert_keeps_wiring refuses the takeover, #568 closed
C04	1	Planted-binary spawn: vendor/pypi_hatch.rs ran a bare hatch in the project root.	§1 #4; 7.3	#613	fixed (#617)
C05	1	SOCKET_FORCE is bound to vendor --force, apply --force and self-update --force, so forcing a self-update also forces past hash checks. Merged C35: drop the deprecated spellings and decide embedded --vex. vendor --force promises a tolerance nothing implements (#923).	§1 #6; R9; R10	#615, #966, #923	in PR #1021, #1031; decided 2026-10-07: SOCKET_FORCE binding removed (#615); v5 removes scan --apply/--vendor, get --no-apply, download, gc (#966); embedded --vex (Q2) undecided
C06	1	get round-trips its arguments through DownloadParams and ..GlobalArgs::default(), which silently resets offline, patch_server_url and more. get also builds a fake ApplyArgs, and get and scan call each other.	2.1; 2.3; R7		rejected; resets inert on 045d7ec, cycle folded into C12
C07	1	The URL builders disagree. When org auto-resolve fails, patches_path sends JSON calls to /v0/orgs/default/…, while binary_url and vendor_package_url send the same client to the public proxy. Telemetry has a fourth copy of this logic.	7.2	#648	in PR #1041; decided 2026-10-07 (option 2): org resolved once per run into one route; failed auto-resolve → whole run on the proxy
C08	2	Repo hygiene: a stray .github/actions/actions/cache/<sha>/.vscode/launch.json, a README that documents v5 but whose installer installs v4, and 39 references to a "DESIGN §" document that doesn't exist. (The dead CI path filters go to the CI janitor.)	§1 #8; 8.5 J	#649	filed #649; README part already fixed
C09	2	There is no shared with_proxy_fallback helper: scan, get and vex each handle the proxy fallback, and apply, rollback, repair blob/diff downloads and vendor eject fetches have none (merged C39). Fix: the fallback moves into ApiClient.	2.10 R2; new finding	#647	filed #647
C10	2	Tracking: RunCtx { config, client, telemetry, lock }, built once in main. It would delete apply_env_toggles (flags written back into process env, called at 11 sites) and unblock removing most env-mutating #[serial].	2.5; R3	#793, #794	filed #793, #794; tracking #793, child 1 #794
C11	2	Tracking: split run_scan (1,540 lines on 045d7ec; JSON and human arms each dispatch all three modes) into discover → select → ModeBackend::consume → render.	2.2; R5	#843, #844	filed #843, #844; tracking #843, child 1 #844
C12	2	Tracking: move engine code out of the CLI and into core behind one orchestrator over ProjectView: vendor_records_reusing, run_redirect_selected, ecosystem_dispatch.rs. Coordinate with E32.	2.1; R11	#894, #895	filed #894, #895; tracking #894, child 1 #895; child 2 (command cycles) in PR #1043; 1,154 / 949 lines at 1c6c509
C13	2	Error codes are untyped. Target: a typed registry (enum Reason × Ecosystem) that generates the contract's code tables, plus a freshness test (~43 undocumented codes). One unparseable manifest gives five --json codes across commands (merged C52).	2.8; 3.7 #8; 8.5 F	#930, #931	filed #930, #931; tracking #930, child 1 #931 (manifest mapper)
C14	2	Decide: one JSON envelope. scan and get still emit a bare-string error while the other commands emit {code, message}; exit-2 usage errors pick their --json channel per site (merged C53).	2.8; R4	#704	in PR #1027; decided 2026-10-07: top-level error always {code, message}; every self-enforced exit 2 through one usage_error
C15	2	There are three HTTP retry systems, and blob and diff fetches have none. A 206-line HTTP-date parser, two near-identical downloaders, and per-fetch or per-event clients round it out. Target: one retry + timeout primitive.	7.2; R12	#676, #677	filed #676; #677 fixed (#889): vendor retries share parse_retry_after/jitter; blob/diff still no retry
C16	2	Batch limits are split across crates. The CLI owns 500 / 100 / 256 KiB, and search_patches_batch documents a maximum of 500 without enforcing it. The in-memory engine keeps a third copy (default 100, no body cap).	7.2	#675	filed #675
C17	2	Digest helpers are duplicated: inline hex::encode(Sha256::digest(..)) sites, compute-vs-validate sha256_hex copies, sha1_hex twice, SRI formatting inlined three times.	4.4; 7.3	#706	filed #706; slice 1 merged as #865; slice 2 is the 6 files in PENDING_INLINE_DIGESTS (3 stale entries removed by #1016); sidecars/coursier.rs evades the text ratchet via a local digest()
C18	2	There are four UUID grammars. client.rs has one, CLI lib.rs a byte-identical copy, path_safety.rs accepts lowercase only, and apply.rs accepts any alphanumeric plus -/_.	7.3	#705	filed #705; the user-input half (2 of 5 grammars) in PR #1034; a fifth grammar in python_script.rs
C19	2	Env truthiness has three vocabularies (core's "1"/"true" match kept correct only by apply_env_toggles), ~29 inline "empty means unset" reads, and six or more home-directory resolvers that disagree on Windows.	7.3	#727	filed #727; home-directory half in PR #1038
C20	2	Tracking: purls have two builder families in utils/purl.rs, plus 42 hand-built pkg: strings and ~48 starts_with("pkg:<type>/") checks beside Ecosystem::from_purl. Purl equality is C63.	6.4; 7.3	#748, #747	filed #748, #747; children 2–4 touch the ecosystem area
C21	3	utils/fs.rs had six atomic writers (four boolean policies) plus a blocking stage copy.	5.7; 7.3	#728	fixed (#858)
C22	2	Telemetry has 19 near-identical public wrappers (17 track_*, 2 spawn_*), builds a new HTTP client for every event, and the CLI threads token/org through ~45 call sites (review said 125), resolved two ways. Target: one Telemetry handle with track(Event) and a shared client.	7.5; R15	#770	filed #770
C23	2	Dead code: PatchSources::mem_blobs is never Some; VendorSource predicates are always true; group commit captures redirect-state.json, which nothing in its scope writes; the switched_off("group_commit") oracle path.	7.4; 7.6 #3; 5.6	#746	filed #746; Pypi/LauncherCache channels are live (not dead)
C24	2	Apply and rollback are mirror images: the verify types are identical, and fold_copy_result, the pnpm peer fan-out and the sidecar boundary are each written twice; the folds have drifted and both drop per-file records (#756). Target: one engine.	7.4; 7.6 #4	#771, #772	filed #771; #772 fixed (#774), shared store_copies::fan_out; verify types + sidecar boundary remain
C25	2	--download-mode diff, the default, re-downloads every blob on a cold cache, runs sequentially with no retry, and is the only user of qbsdiff. Making file the default is a decision; removing the duplicate fetch work is a refactor.	7.4; R10	#792	in PR #1049; decided 2026-10-07 (option A, v5): delete the diff path, --download-mode and SOCKET_DOWNLOAD_MODE outright; patch/package.rs stays
C26	3	apply.lock spends ~554 lines deleting the lock file on exit, and taking the lock replays the vendored group-commit journal, so lock-free vendor --check and vex misreport a crashed run (merged C46).	7.4; new finding	#808, #809	in PR #1030; decided 2026-10-07 (option C): the lock stays transient; journal layering is #809
C27	3	Agent-mode sidecars don't handle Maven files; Gradle-only projects were patched in ~/.m2.	7.4	#551	already fixed (#646); Maven 3.9.11 ignores stale local .jar.sha1, Gradle half closed with #551
C28	3	socket.yml builds a hand-made YAML tree on serde-saphyr's event parser to read 8 keys. Target: serde with deny_unknown_fields.	7.5		rejected; the tree implements the contract's scoped YAML refusals
C29	3	The client.rs split (2.8K lines) into client, vendor_service and credentials; the debug-ordering machinery (HeldBack) has 45 call sites.	7.2; 7.6 #8	#871, #913	filed #871, #913; #871 vendor-service move, #913 credentials move (~330 lines)
C30	2	No shared test-support: binary() is defined in 103 files and git_sha256 in 86, there are 15 scrub_socket_env (14 bodies), xorshift is implemented four times, and the VEX helpers are forked.	6.4; 8.5 D	#824, #823	filed #824, #823; #823 slice 1 merged as #850 (common/hermetic.rs, 8 of 15 scrub_socket_env copies deleted); slice 2 is the other 7
C31	3	There are 235 test executables on 1c6c509 (review: 207; no [[test]] entries); the target is ~25. This needs C10 first.	8.5 A		to verify; count confirmed, not filed
C32	3	328 exact-sentence assertions should become --json/errorCode checks plus snapshots. Triage the covgap tests (32 files, 413 tests on 1c6c509), ~136 of which assert human text.	2.5; 8.5 G/H		to verify; counts confirmed, not filed
C33	3	Tracking: CLI_CONTRACT.md (417 KB on 431b818; 332 KB at review) should be a checked reference (flags, env vars, codes, exit codes) plus ≤300 lines of prose, with freshness tests.	8.3; 8.5 F/I	#948, #949	filed #948, #949; tracking #948 (folds in #678, #930), child 1 #949
C34	3	Decide: the command model. A read-only scan, plus fix, undo, sync and check, with mode inferred from project state (or an explicit --mode for takeovers). This folds remove, rollback and vendor --revert.	§4; 2.9; R6/R8		decision pending; no decision issue filed yet
C36	3	Decide: the future of the self-update binary swap (2,350 prod lines; the only updater for the Windows zip). The agent-mode half moved to C55.	§6 Q2; 7.5	#983	rejected; #983 (2026-10-07): keep the --update swap and the notifier, harden them (retry, stall timeout, streaming, live test); #983 closed
C37	2	Patch blob/diff downloads (fetch_binary) buffered the whole body with no cap.	new finding	#571	fixed (#607)
C38	2	The public-proxy per-package fallback keeps a private cap of 10, ignoring SOCKET_API_CONCURRENCY, the proxy cap and the fd-limit rule; SOCKET_API_CONCURRENCY and SOCKET_WALK_THREADS are documented nowhere (merged C40).	new finding	#614, #678	filed #614, #678
C41	2	Hash case policy is per site: blob download compares case-insensitively and the validators accept uppercase, but agent-mode apply/rollback verify with exact ==, so an uppercase manifest hash never verifies. Vendored verify sites are split the same way.	new finding	#707	filed #707
C42	2	get writes a patch view's inline blobs to .socket/blobs/<hash> without verifying the hash, in place, overwriting existing verified blobs; the fetch path verifies and stages. It also hand-rolls base64.	new finding	#726	in PR #1042 (blob_fetcher::store_verified_blob)
C43	2	With --manifest-path into another project, rollback, remove, repair, apply --check, vex, scan and get read the vendored ledger from --cwd while list, apply and vendor --check use the manifest's project; rollback locks one .socket/ and writes the other's ledger.	new finding	#745	filed #745
C44	3	The ecosystem-name parser is written three times: --ecosystems/SOCKET_ECOSYSTEMS need an exact, case-sensitive match, socket.yml patches.ecosystems trims and lowercases, and vendor::ecosystem_in_scope has its own lookup; -e NPM and -e "npm, pypi" exit 2.	new finding	#773	filed #773
C45	3	--download-mode is an unvalidated String, parsed late in fetch_stage/repair: a typo fails apply/repair with exit 1 and apply_failed/repair_failed (and scan/get only after saving the patch), while apply --check, rollback, list and vendor accept it; --vendor-source uses a clap parser (exit 2).	2.7; R8 (narrowed)	#791	filed #791
C47	2	10 CLI test files spawned the binary with no SOCKET_* scrub; an ambient SOCKET_DRY_RUN=true turned 18 of 19 repair_vendor_e2e tests red.	new finding	#823	filed #823; 8 of 10 hermetic since #850; the last two are unblocked (#820, #849, #774 merged)
C48	2	Child processes had no shared deadline; crawler probes called output() unbounded, so a hung gem shim hung scan.	new finding	#845, #1067	partly fixed (#886); pdm_site and the npm_dir git exchange keep hand-rolled deadlines (#1067)
C49	2	Registry downloads used a 60 s whole-request deadline instead of ApiTimeouts' idle bound.	new finding	#872	fixed (#876)
C50	2	Artifact GC has two retention policies: after_removal (rollback, remove) keeps active patches' beforeHash blobs for offline rollback, for_apply (repair, scan --prune) drops them; offline rollback then fails and names repair, which never fetches beforeHash blobs. cleanup_unused_blobs/_archives are dead.	new finding	#893	filed #893
C51	3	Agent-mode jar verification (jvm_jar::verify_member_bytes; apply, rollback, vex) buffers each patched member before hashing, while vendored zip_bytes_match_after_hashes streams since #587: 1,067 MiB vs 26 MiB peak RSS on a 1 GiB member.	new finding	#914	filed #914
C54	3	The contract documents status: paidRequired and errorCode paid_required for get and scan, but get emits legacy status: "paid_required" (two hand-written blocks) and scan reports only paidPatches; Status::PaidRequired is never constructed.	new finding	#982	filed #982
C55	3	Decide: the future of agent mode (CLI apply 2,963 + fetch_stage + repair; ~3.2K agent-only core; ~29 open agent-mode bugs). Only Deno and --global installs need it.	§5; §6 Q2	#1000	rejected; #1000 (2026-10-07) chose option A: keep agent mode for every ecosystem for now, layout bugs fixed one at a time; #1000 closed
C56	2	apply, apply --check and vendor treat any stat error on .socket/manifest.json as "no manifest" (noManifest, exit 0); repair/remove/rollback say manifest_not_found. Five metadata().is_err() probes bypass read_manifest's NotFound rule.	new finding	#998	filed #998
C57	2	remove <uuid> re-matches the vendor ledger by the raw identifier, so an older ledger generation is never reverted: manifest entry removed, vendoring kept, status: success.	new finding	#999	in PR #1035
C58	3	Standalone vex exits 2 (the global "usage error" code) on runtime failures: manifest_unreadable, manifest_not_found, write_failed, …; the same inputs exit 1 on apply --check, vendor --check, remove, repair and embedded --vex. PR #1027 would route them through usage_error.	new finding	#1047	filed #1047
C59	1	Credentials reach logs, --json, telemetry and third parties: hosted Composer keeps transport-options auth (B02), grant tokens and URL userinfo appear in warnings and debug output (B26), the VEX product @id carries git-remote credentials (B21).	audit B02, B21, B26	#399	in PR #1026
C60	1	.socket containment: the symlink guard starts below .socket and guards deletes only (#887, B08); get writes inline blobs through a planted link (B24); agent writes follow links out of the package (B25); a new-file patch overwrites an existing file even under --strict (B23).	audit B08, B23, B24, B25	#887, #726	in PR #1042; rollback of an overwritten file needs a pre-image store
C61	2	CI gates pass while checking nothing: --cwd/--global-prefix/--manifest-path are never validated (B10), apply --check checks Go only (B27), hosted --json has no per-purl pin data (B12).	audit B10, B12, B27		in PR #1029; hosted exit code waits on #704
C62	2	Four package-target grammars: get <name> fuzzy-substitutes and searches one version (B11), ignores --ecosystems (B56), and the UUID path skips socket.yml silently (B29, B57).	audit B11, B29, B56, B57	#453	in PR #1034
C63	2	Purl equality has 6+ relations and 5 ownership matchers; NuGet case and PEP 503 spellings make scan --prune GC live entries (B20) and remove/rollback miss them (B73). Target: one PurlKey.	audit B20, B73	#553, #748	in PR #1045
C64	2	~12 hand-written path normalizers; home_dir falls back to a relative ~ (B66); the VEX repo-root walk has no HOME stop, ceilings or .git-file support (B22); FIFO-unsafe reads remain (B74).	audit B22, B66, B74		in PR #1038
C65	3	Remedies prescribe a vendor --revert <purl> form that doesn't exist (B80); 8+ symlink refusal codes (B81); retired v4 spellings get misleading tips (B76); hosted remove prints its error twice (B77); five command-module cycles.	audit B76, B77, B80, B81	#894	in PR #1043
C66	2	Test child processes send telemetry to production (B69); the e2e zero-tests guard covers Gradle only and the Windows npm leg is a no-op (B70).	audit B69, B70		in PR #1046
C67	1	Main went red on stale PENDING_INLINE_DIGESTS entries (two-sided ratchet, B01); no required checks, and push CI cancels most main verdicts (B28).	audit B01, B28		in PR #1018; digest entries fixed (#1016); a ruleset with required checks and a merge queue needs org admin
C68	2	11 open -g (global install) bugs share one cause: global prefixes and shared caches are patched under per-project ownership.	audit B33, B79	#422, #423, #426, #435, #437, #443, #444, #450, #489	filed #422, #423, #426, #435, #437, #443, #444, #450, #489; #1000 kept agent mode
C69	2	Perf regressions have no owner: bun/hosted +110% (cause pinned), npm/hosted +15%, cargo and uv hosted per-patch re-parse.	audit B38	#578, #993, #761, #836	filed #578, #993, #761, #836; links to E27
C70	3	run_scan's human arm exits 1 when every query returns no patches; the JSON arms exit 0 (and preview GC and prune differently).	audit B54	#1062	filed #1062
C71	2	scan reads a corrupt manifest as empty: --prune skips GC and reports success, the rollout counts recorded patches as new.	audit B55	#1063	filed #1063
C72	2	Self-update and install.sh trust an unsigned SHA256SUMS from the same release.	audit B67	#1065	filed #1065
C73	3	rollback --json counters count only the agent leg, so hosted and vendored failures report failed: 0.	audit B75	#1066	filed #1066

Handed off (to the CI janitor): de-instrument coverage and drop the LTO docker-base build where it gates nothing, keeping the gating Linux tests and the per-PR Docker e2e on PRs; a reusable compat workflow; no per-leg compiles; dead CI path filters (review 8.2, 8.5 B/C/E).

Rejected / not a defect: C28: the hand-built socket.yml tree implements the contract's scoped YAML refusals (anchors, aliases, merge keys and tags refused only inside patches/projectIgnorePaths), which serde can't scope. C06: on 045d7ec the nested apply reads none of the reset fields except offline, which get/scan refuse up front; the cycle and fake ApplyArgs stay in C12.

Already fixed: C27 (#646).

Refactor routine (refactor, hourly, highest leverage first)

Last updated 2026-10-07T20:58Z · main @ 05ecc6e

In flight:

• No routine-opened PR is open. 24 arch-refactor PRs are open, so MAX_OPEN is full; the routine re-ranks only.
• Maintainer drafts (decided issues): #1021 (Decide: give SOCKET_FORCE per-command names so forcing a self-update doesn't also force apply and vendor #615), #1027 (Decide: one shape for the --json top-level error (scan and get emit both a string and a {code, message} object) #704), #1030 (Decide: keep .socket/apply.lock transient, or give the lock a file that never has to be deleted #808), #1031 (Decide: warn on and then remove scan --apply/--vendor, and whether --vex stays embedded #966), #1036 (Decide: vendor single-module Maven poms through the suffixed-version jvm planner and retire the same-GAV <repository> wiring #973), #1041 (Decide: where patch API calls go when a token is set but the org slug can't be resolved #648), #1049 (#792), #1051 (#580).
• October 7 campaign (duplicate business logic, one PR per seam; register rows in brackets): #1026 credentials [C59], #1029 trust signals [C61], #1032 JVM layout [E77, E69], #1033 VEX attestation [E72], #1034 target grammar [C62], #1035 supersede lifecycle [E71], #1038 paths and roots [C64], #1039 atomic takeover [E70], #1042 .socket containment [C60, C42], #1043 command cycles and UI text [C65, C12], #1044 governing locks [E75], #1045 PurlKey [C63], #1046 test hygiene [C66], #1050 vendored liveness [E74], #1057 yarn grammar [E08, E76], #1058 pinned check [E73].

Merged:

• #1015: the vendored-reference scan reads every VENDORED row and accepts the bare uuid dir. Issues #832, #958 (E61). 8e521f9 (+308 / −41). Left: dead eco == "maven2" arm in commands/vendor.rs.
• #876: registry clients under ApiTimeouts through one registry_client_builder. Issue #872 (C49). e2300cc (+154 / −33).
• #889: vendor-service retries share api::retry (Retry-After HTTP-date, jitter). Issue #677 (C15 child 1). 835601b (+209 / −38). Left: blob/diff fetches have no retry (#676).
• Earlier: #886 (#845, C48 slice 1), #870 (#781), #865 (#706 slice 1), #858 (#728), #850 (#823 slice 1), #607 (#571), #602 (#592), #597 (#561, E01), #587 (#569, C01), #583 (E12), #581 (#570), #574 (#562), #572 (#563).

Queue (B bugs closed, U unblocks, D duplication removed, R risk; score = 3B + 2U + D − risk):

#	Candidate	B	U	D	R	Score	Note
1	#990 (E24, child 1 of #989): one vendor::revert::finish with an explicit KeepPolicy for the 12 copied finish blocks	0	1	≈12	L	≈14	skipped: backend files changed by #1032, #1039, #1043, #1044, #1050, #1057
2	#922 (E22, child 1 of #920): one VendorEntry::npm constructor for the 7 npm-family ledger tails	0	1	≈7	L	≈9	skipped: claimed; drivers changed by #1008
3	#998 (C56): one NotFound-only manifest probe (5 metadata().is_err() copies)	1	1	≈5	M	≈8	skipped: commands/vendor.rs changed by open PRs; pairs with #931 and #1063
4	#931 (C13 child 1): one manifest-read error mapper for every command	1	1	≈2.5	M	≈5.5	skipped: as #998
5	#893 (C50): one artifact GC retention policy	1	0	≈2	L	≈4	next eligible when a slot frees

Re-ranked 2026-10-07T20:58Z (unchanged: main still 05ecc6e, no PR closed since 18:56Z, the 8 maintainer drafts refreshed their heartbeats at 20:39Z). Earlier, the October 7 reconciliation: stale skip lists replaced (#657, #909, #940, #1015, #876, #889 merged). The campaign PRs above cover E08, E69–E77, C42 and C59–C67; don't start work on those rows.

Notes:

• The sandbox runs as root, so 4 core lib tests fail on main and on branches alike: copy_tree::relax_loop_must_not_traverse_symlinked_root, vlt_heal::an_unremovable_hidden_lock_keeps_every_store_entry, pypi_poetry::wire_write_failure_maps_error_and_leaves_lock_untouched, pypi_requirements::wire_failure_rolls_back_already_written_files.
• redirect/pipenv.rs, vendor/pypi.rs and vendor/lock_inventory/vlt.rs aren't rustfmt-clean on main: format only your own hunks there. Check rustfmt --check on the main copy before formatting a whole file.
• lock_inventory/mod.rs architecture_tests forbid hosted_patch_uuid* in a format file's model section. Origin-policy helpers go after the // ── registry view ── marker.
• redirect/mod.rs is a hot file (4 open PRs). Prefer candidates outside it until those land.
• CLI_CONTRACT.md lives at crates/socket-patch-cli/CLI_CONTRACT.md.
• vlt registry semantics: hydrate and Spec memoize by id/spec and ignore options, so run each vlt case in a fresh node process. scoped-registries[scope] wins for every segment; ~~ splits to npm. Cite @vltpkg/dep-id hydrateTuple and @vltpkg/spec (registry ?? registries[default-registry-alias]); the packages download from npm.
• Runs overlap: two runs started within minutes of each other on 2026-10-02. Claims and the status block kept them apart; git pull --rebase the ledger before writing.
• Ledger and branch pushes need verified signatures (org ruleset). Commit with the session's default git identity; overriding user.email (e.g. to a bot address) makes GitHub reject the signature.
• Maintainer steering (2026-10-02, on #569 and #571): don't add size caps on trusted upstream data; stream instead of buffering.
• reqwest 0.12 ClientBuilder::read_timeout is an idle bound (resets per chunk) and also bounds the wait for response headers; RequestBuilder::timeout is total.
• rustfmt <file> also formats that file's out-of-line child modules (formatting crawlers/mod.rs rewrote python_crawler.rs). Check git diff --stat after formatting and restore any file you didn't mean to touch.
• cargo clippy --all-targets (and -p socket-patch-core --tests) already fails on main from older lints in test code. CI's gate is cargo clippy --workspace --all-features -- -D warnings.
• Windows CI checks out with CRLF. A test that scans source text for \n-joined markers must normalize \r\n first: #602 failed test (windows-latest) this way.
• reqwest 0.12 Response::chunk() streams without the stream feature. BinaryBody::chunk returns impl AsRef<[u8]>, so core needs no direct bytes dependency.
• cargo test -p socket-patch-cli --test repair has 2 root-only failures (repair_exits_zero_and_stays_quiet_when_lock_file_unremovable, repair_cleanup_failure_is_reported_in_json_and_silent_modes). They chmod a directory read-only.
• Windows: DirEntry::metadata().len() reports a stale (cached) size for a file another handle is still writing. Size live files with std::fs::metadata(path) in tests.
• CLI test targets: 145+ files spawn socket-patch with a bare Command::new(binary()); tests/spawn_env_hygiene.rs keeps PENDING_RAW_SPAWNS / PENDING_SCRUB_COPIES allowlists that fail on new and stale entries — drop a file from the list when you migrate it.
• utils::fs writers run on the blocking pool via run_blocking since #858: a test calling them needs a tokio runtime but either flavor works.
• #[cfg(test)] mod tests blocks often lean on the parent's use sha2::… through use super::*: removing a production import breaks the test build (cargo test --lib --no-run), not cargo build. Add the import to the test module.
• Bugbot may review the PR's start commit when a draft opens; check the review's commit SHA and re-trigger on the real head.
• go.mod's lexer treats // as a comment anywhere, so module a//b declares a: don't expect // inside a token to be rejected.
• A process-global reqwest::Client (LazyLock) is unsafe in core tests: pooled connections stay bound to the tokio runtime that opened them, and each #[tokio::test] has its own runtime. Build per call through a shared builder instead.
• The sandbox (root) also fails 3 covgap_commands_vendor state-write-failure tests (chmod-based) on main and branches alike.
• Probe spawns go through utils::process::output_within since #886 (blocking; async callers wrap it in utils::fs::run_blocking). It nulls stderr; don't add a new tokio::time::timeout + kill_on_drop site.

[Mikola Lysenko (mikolalysenko)]

[agent] Part 2 of 9 of the living socket-patch architecture document. The summary and ranked recommendations are in the top post. Originally written against 2463257; the routines update this part as the code changes.

Part 2: CLI command layer and user experience

Last checked against main @ 431b818 on 2026-10-07 by the October 7 reconciliation (command cycles, takeover scope, envelope shapes and client sites re-checked; function sizes from 1c6c509). Owner: audit-core. Earlier: c5be5d1 by audit-core. Re-checked on c5be5d1 (15:50Z run): the exit codes of a corrupt and a missing manifest across commands, and the command-model premises of 2.9 (unchanged). Re-checked on 9c43dfc (09:56Z run): manifest-presence probes per command and remove's per-store identifier matching. Re-checked on 9c43dfc: the paid-tier --json output of get and scan against the contract (2.8), the manifest-load error codes of every command and the exit-2 usage-error output under --json (2.8), the legacy mode spellings and embedded --vex (2.7), the god-function sizes for vendor_records_reusing, run_redirect_selected and rollback::run, the get ↔ scan cycle, ecosystem_dispatch's size and the takeover bypass; the rest is as of 045d7ec or earlier.

Scope: crates/socket-patch-cli/src/ — args.rs, lib.rs/main.rs, ecosystem_dispatch.rs, json_envelope.rs, ui/*, update_notifier.rs, and every commands/* module.

2.1 Headline numbers

Metric	Value
CLI src/	59,450 lines = ~33.7K production + ~25.8K inline tests
Production functions	707 fns hold 25.6K lines; 41 fns ≥100 lines hold 52% of the code; 8 fns ≥500 lines hold 27%
Subcommands	9 visible + 2 hidden (self-update, hosted-bundle), 2 visible aliases (download, gc), a <UUID> shortcut, and a root --update argv rewrite
Flags	57 visible long flags + 3 hidden. GlobalArgs flattens 27 flags into every subcommand (26 env-bound)
Env vars	43 clap env = bindings + 2 read by hand. The contract names 71 SOCKET_* vars; source references 84
Error vocabulary	156 stable errorCode tags + 12 EnvelopeError codes in the contract; ~570 distinct code-shaped strings in source
--help	150–219 lines per subcommand (measured on a debug build). list --help shows 27 options, most of which do nothing for list (--dry-run, --yes, --strict, --download-mode, --vendor-source, --maven-config, --lock-timeout, the three hosted --no-* opt-outs, …)

2.2 God functions

Sizes measured at 1c6c509 (2026-10-07); the functions keep growing.

Function	Location	Lines
run_scan	scan/mod.rs	1,577
rollback::run	rollback.rs (on 9c43dfc)	1,012
vendor_records_reusing	vendor.rs	1,154
run_redirect_selected	scan/hosted.rs	949
remove::run	remove.rs	809
rollback_patches_inner	rollback.rs	686
apply_patches_inner	apply.rs	651
get::run	get.rs	641
vendored_takeover	scan/hosted.rs	493

74 functions exceed 200 lines and 11 exceed 500.

run_scan does all of this in one function body:

• mode folding and socket.yml policy loading;
• the PATH fan-out, path-scope parsing, the rollout cap and the offline check;
• the crawl, the lockfile supplement, ledger loads and filters;
• concurrent batch API calls with proxy fallback, then telemetry;
• a JSON arm and a human arm that each dispatch all three modes again: run_redirect 2187 vs boxed_run_redirect_selected 2675, boxed_vendor_json_path 2375 vs boxed_vendor_interactive_path 2912, download_and_apply_patches_with 2339 vs 2931 (re-checked on 045d7ec; the split is tracked phase by phase). C11 · filed Tracking: split run_scan into discover, select, one mode dispatch and render phases #843, Move scan's crawl, supplements and filters out of run_scan into collect_inventory #844; tracking Tracking: split run_scan into discover, select, one mode dispatch and render phases #843, child 1 Move scan's crawl, supplements and filters out of run_scan into collect_inventory #844

Mode is three booleans (apply/vendor/hosted). They are referenced 91 times inside the function, across about 27 conditional branches.

The root cause is that output mode leaks into the engine. For example, discover_selected (scan/mod.rs:484) takes show_progress, warn, detail_error_line and json_warnings: Option<&mut Value>.

2.3 No service layer: commands call each other

Command modules double as libraries and form a dense web:

• get ↔ scan cycle: get.rs references scan:: 33 times on 9c43dfc (hosted engine, vendor step, ScanMode), and scan's agent mode imports get::download_and_apply_patches_with/DownloadParams/DownloadRun (plus decide_patch_action, short_uuid, and download_patch_records_reusing in vendor_flow). Breaking it is child 2 of the engine-to-core tracking issue. C12 · filed Tracking: move the patch engines out of the CLI command modules into core #894, Move ecosystem_dispatch's purl locator out of the CLI into core as crawlers::locate #895; tracking Tracking: move the patch engines out of the CLI command modules into core #894, child 1 Move ecosystem_dispatch's purl locator out of the CLI into core as crawlers::locate #895; child 2 (command cycles) in PR Break command-module cycles and share remedy and UI text #1043; 1,154 / 949 lines at 1c6c509
• Five cycles, not one (at 1c6c509): get↔scan, scan↔vendor, vendor↔rollback, apply↔rollback (through UI helpers) and scan↔rollback; vendored_backend also points back into commands. PR Break command-module cycles and share remedy and UI text #1043 breaks all five by moving the shared code into agent_download, hosted_unwind, vlt_heal and ui/, with an allowlist test for the remaining edges. C65 · in PR Break command-module cycles and share remedy and UI text #1043
• Other edges: remove→rollback (8 refs), vendor→vex (8), apply→vex (6), repair→rollback+list, vex_sources→get.
• get runs the agent apply by building fake CLI args: ApplyArgs { nested: Some(NestedApply{..}) }, then calling apply::run_locked (get.rs:2314–2341).
• A lossy argument round trip: GlobalArgs → DownloadParams → GlobalArgs.
  • DownloadParams re-declares 10 GlobalArgs fields.
  • nested_apply_args_from_params rebuilds the args with ..GlobalArgs::default(), resetting offline, patch_server_url, no_vlt_install_cleanup and others.
  • Re-checked on 045d7ec: this is inert. The nested apply runs on the caller's client (DownloadRun), the hosted opt-outs and debug/telemetry reach core through apply_env_toggles and process env, and apply reads only offline of the reset fields, which get/scan refuse up front. The remaining defect is the cycle itself (C12). C06 · rejected; resets inert on 045d7ec, cycle folded into C12

2.4 Shared abstractions exist but are bypassed

• ProjectContext. Its doc says "scan, vendor, vex, list and get read these through one ProjectContext". It actually has 3 call sites (list, scan, get). vex calls LoadedLedgers::load directly; vendor calls inventory_project* and discover_wiring directly. load_state( appears 27 times across 12 command files, and read_manifest( 15 times across 9.
• VendoredBackend ("the one vendored-mode backend") has 8 users, but run_vendor_gc (vendor.rs:3400, 3436) and the hosted takeover (scan/hosted.rs:1700, 1733) call dispatch_revert_one directly.
• The takeover bypass no longer loses ledger entries. vendored_takeover still calls dispatch_revert_one directly, but since Fix PyPI vendored→hosted takeover stranding unreachable pins (#699) #708 it checks revert_keeps_wiring (kept_artifact, a drift-skipped record, or a residual-reference warning) after every successful revert, dry and wet, and refuses the purl with the drifted-takeover warning while keeping the ledger entry, like the other revert callers. mode_migration_pypi::drifted_vendored_line_refuses_takeover guards it. C03 · fixed (Fix PyPI vendored→hosted takeover stranding unreachable pins (#699) #708); revert_keeps_wiring refuses the takeover, Vendored→hosted takeover drops the vendored ledger entry when the revert drift-keeps the artifact #568 closed

2.5 Configuration flows through process environment

apply_env_toggles (args.rs:559-575) writes parsed flags back into SOCKET_OFFLINE, SOCKET_DEBUG, SOCKET_TELEMETRY_DISABLED, SOCKET_API_URL and SOCKET_PROXY_URL, so that core (51 production env reads) can see them.

• Its own doc comment records the bug this caused: an on-prem --api-url run "POSTed the event — Bearer token included — to the default api.socket.dev".
• It is called separately in 10 command entry points rather than once in main, and vendor --check returns before calling it.
• It is why the test suites carry 993 #[serial] attributes in tests/ (plus 185 in src), counted on 045d7ec; the review counted 553 + 182.
• The lock timeout is converted by hand at 12 sites, and the API client is built at 15 production sites (13 at review).
• Fix: an explicit RunCtx { config, client, telemetry, lock } built once in main and passed down. Core should not read ambient env except at the edge. C10 · filed Tracking: build one RunCtx in main and stop mirroring CLI flags into the process environment #793, Mirror global flags into the environment once before dispatch, and read the lock timeout through one accessor #794; tracking Tracking: build one RunCtx in main and stop mirroring CLI flags into the process environment #793, child 1 Mirror global flags into the environment once before dispatch, and read the lock timeout through one accessor #794

2.6 Structural duplication

A sliding-window copy-paste detector finds little literal duplication. The duplication is structural: helpers were extracted, but the pipelines around them were forked.

Duplicate	Evidence
JSON vs human agent pipeline in run_scan	discover_selected @2226/2246 vs plp (@2489); classified_rows @2265/2510; partition_agent_selection @2282/2702; plan_kept_rows @2283/2730 (on 045d7ec)
remove vs rollback	remove::run (797) + remove_hosted_only (94) + remove_ledger_only (127) vs rollback::run (984). Both run agent leg → vendored leg → hosted leg → manifest cleanup → GC over the same primitives. The contract itself says "remove parity" repeatedly.
get agent mode, twice	save_and_apply_patch (UUID path, get.rs:3365) vs download_and_apply_patches_with (search path, :2343)
Vendored revert ×4	VendoredBackend::revert, vendor.rs:3400, vendor.rs:3436, hosted.rs:1700/1733
401/403 → public-proxy fallback ×3	scan/mod.rs:2014–2035, get.rs:2625–2647 (UUID path only), vex_sources.rs:944–970. get's CVE/GHSA/PURL/name search path has none, and neither do apply, rollback, repair or vendor eject, whose blob, diff and view fetches fail on a stale token (verified by execution on 045d7ec). C09 · filed #647
Lock acquisition ×2 families	acquire_or_emit in 5 envelope commands vs acquire_with_status + bespoke rendering in 7 sites. Duration::from_secs(lock_timeout.unwrap_or(0)) appears 11 times.
"Which origins count as hosted" ×3, divergent	discover_options and rollback::patch_server_origins use only patch_server_url; scan/hosted/vlt.rs:69 also adds api_url
Ecosystem filter ×4, divergent	GlobalArgs::ecosystem_selected treats an empty list as "all"; crawl_selects treats Some(empty) as "none"
Vulnerability label / max severity, divergent	get.rs:511/114 vs scan/render.rs:327–360: get drops unknown severities, render doesn't
Generic utilities in the wrong place	join_clauses/capitalize_first/as_question in rollback.rs (with capitalize_first again in update.rs); a text-wrapping warning formatter private to hosted.rs:1911–2033
Telemetry plumbing	46 track_* call sites and 125 references threading token/org through signatures. remove and rollback build a full API client (an org-slug network round trip) only for telemetry, although telemetry_credentials() exists to avoid exactly that.
Ad-hoc JSON	json!( appears 47× in get.rs and 16× in rollback.rs, versus typed Envelope operations in apply/vendor/remove/repair

2.7 Flag and surface sprawl

• Every global flag is silently accepted by every command. list --download-mode bogus --strict --yes --lock-timeout 9 --maven-config none --no-vlt-install-cleanup --dry-run exits 0. --update --ecosystems npm --manifest-path x.json --strict --global parses.
• Dead or vestigial flags:
  • --vendor-source: core's VendorSource has one variant, and build is an error.
  • --download-mode is an unvalidated String, checked only where it is used. That breaks the "fail loud on typo" posture the same file applies to --ecosystems. On 045d7ec a bad value fails apply and repair with exit 1 and apply_failed/repair_failed, while apply --check, rollback, list and vendor exit 0; --vendor-source bogus is a clap usage error (exit 2). C45 · filed An invalid --download-mode fails apply and repair with exit 1 but is accepted by every other command #791
• Deprecated spellings and aliases: scan --apply (hidden), scan --vendor (hidden), get --no-apply, and the download and gc aliases. resolve_mode_flags (scan/mod.rs:184–246 on 9c43dfc) exists mainly to reconcile these. Only --apply/--vendor are called deprecated, and nothing warns: on 9c43dfc both run silently with no removal date, while the contract makes --no-apply, download and gc permanent (MAJOR to remove). --sync is a documented shorthand, not a deprecated spelling. Decided (Decide: warn on and then remove scan --apply/--vendor, and whether --vex stays embedded #966): all five are removed in v5 with no warning release; resolve_mode_flags shrinks to the --sync vs --mode check, the hosted default and the global-scope check; --sync stays. C05 · in PR Remove the SOCKET_FORCE env binding; --force is flag-only (#615) #1021, Remove scan --apply/--vendor, get --no-apply and the download/gc aliases (#966) #1031; decided 2026-10-07: SOCKET_FORCE binding removed (Decide: give SOCKET_FORCE per-command names so forcing a self-update doesn't also force apply and vendor #615); v5 removes scan --apply/--vendor, get --no-apply, download, gc (Decide: warn on and then remove scan --apply/--vendor, and whether --vex stays embedded #966); embedded --vex (Q2) undecided
• Name collisions:
  • --package is a value list on scan but a boolean type-forcer (-p) on get.
  • --check on apply audits Go replace redirects only; on vendor it audits artifacts and JVM wiring.
  • SOCKET_FORCE is bound to three unrelated --force flags (vendor.rs:80, apply.rs:339, update.rs:61; verified on 045d7ec). Exporting it to force a self-update also forces apply and vendor. Decided in Decide: give SOCKET_FORCE per-command names so forcing a self-update doesn't also force apply and vendor #615: no per-command names. The env binding is removed in v5 because nothing sets it (no hook, wrapper, CI or depscan use), and --force stays as a flag. C05 · in PR Remove the SOCKET_FORCE env binding; --force is flag-only (#615) #1021, Remove scan --apply/--vendor, get --no-apply and the download/gc aliases (#966) #1031; decided 2026-10-07: SOCKET_FORCE binding removed (Decide: give SOCKET_FORCE per-command names so forcing a self-update doesn't also force apply and vendor #615); v5 removes scan --apply/--vendor, get --no-apply, download, gc (Decide: warn on and then remove scan --apply/--vendor, and whether --vex stays embedded #966); embedded --vex (Q2) undecided
• VEX passthroughs: 5 --vex-* flags × 3 host commands = 15 flag instances, with the env vars bound twice. Hosted scan --vex attests before install through assume_applied, which the standalone vex can't do, so dropping the embedded form needs a replacement. Still open: Decide: warn on and then remove scan --apply/--vendor, and whether --vex stays embedded #966 left embedded --vex unchanged; E42 carries the shared-helper refactor. C05 · in PR Remove the SOCKET_FORCE env binding; --force is flag-only (#615) #1021, Remove scan --apply/--vendor, get --no-apply and the download/gc aliases (#966) #1031; decided 2026-10-07: SOCKET_FORCE binding removed (Decide: give SOCKET_FORCE per-command names so forcing a self-update doesn't also force apply and vendor #615); v5 removes scan --apply/--vendor, get --no-apply, download, gc (Decide: warn on and then remove scan --apply/--vendor, and whether --vex stays embedded #966); embedded --vex (Q2) undecided
• Hosted-only opt-outs are globals: --no-trust-lockfile-config, --no-npm-allow-remote-config and --no-vlt-install-cleanup appear on apply, list, vex, repair and the rest.
• Two env mechanisms: clap env= vs manual reads in rollout_args.rs/socket_yml_args.rs. SOCKET_NO_SOCKET_YML is missing from LOCAL_ARG_ENV_VARS, which is meant to be the single source of truth.

2.8 Inconsistent JSON (verified against the binary)

$ socket-patch remove pkg:npm/nope@1.0.0 --json      → {"command":"remove","status":"error",…,"error":{"code":"manifest_not_found","message":…}}
$ socket-patch rollback pkg:npm/nope@1.0.0 --json    → {"status":"error","error":"Manifest not found","path":…}
$ socket-patch scan --offline --json                 → {"status":"error","error":"scan requires network access…", "scannedPackages":0, …}
$ socket-patch get nope --offline --json             → {"status":"error","error":"Fetching patches needs network access…"}

• repair, remove and vex use the envelope, with an error object that carries a stable code.
• scan, get and rollback have no fixed error type. rollback emits a bare string except for its lock failure, which acquire_or_emit writes as a coded envelope (rollback.rs:1145); scan and get each emit a bare string on some paths and a {code, message} object on others (scan's embedded-VEX failure, get's vendored failure); get's lock failure adds a sibling errorCode. A script must type-check .error before reading it. Decided (Decide: one shape for the --json top-level error (scan and get emit both a string and a {code, message} object) #704): option 1, every top-level error becomes {code, message}; fix pending. C14 · in PR Make every --json top-level error a {code, message} object (#704) #1027; decided 2026-10-07: top-level error always {code, message}; every self-enforced exit 2 through one usage_error
• Codes are free strings, so one condition gets a different code per command: an unparseable .socket/manifest.json is manifest_invalid (list, remove), manifest_unreadable (apply --check, vendor --check, vex), apply_failed, repair_failed, the undocumented invalid_manifest (vendor) or a bare string (rollback) on 9c43dfc. C13 · filed Tracking: emit every --json error code from one typed ErrorCode registry checked against the contract tables #930, An unparseable .socket/manifest.json is reported under five different --json error codes depending on the command #931; tracking Tracking: emit every --json error code from one typed ErrorCode registry checked against the contract tables #930, child 1 An unparseable .socket/manifest.json is reported under five different --json error codes depending on the command #931 (manifest mapper) The typed-registry plan is. A manifest that exists but can't be stat'd (ENOTDIR, ELOOP, EACCES) is worse: five commands probe with metadata().is_err() ahead of read_manifest, so apply, apply --check and vendor report noManifest and exit 0, and repair/remove/rollback say manifest_not_found. C56 · filed apply, apply --check and vendor report noManifest (exit 0) when .socket/manifest.json exists but can't be stat'd #998
• Exit-2 usage errors under --json have no single channel. scan, remove and rollback print nothing on stdout, as clap does; get prints a bare-string object; vendor, repair and vex print a full envelope with a code. The same --global --mode vendored refusal gives three different stdouts on scan, get and vendor. Decided (Decide: one shape for the --json top-level error (scan and get emit both a string and a {code, message} object) #704): every self-enforced exit 2 prints the coded error on stdout under --json through one usage_error helper; clap errors stay stdout-free; fix pending. C14 · in PR Make every --json top-level error a {code, message} object (#704) #1027; decided 2026-10-07: top-level error always {code, message}; every self-enforced exit 2 through one usage_error
• Status is partialFailure in the envelope but partial_failure in the legacy shapes.
• The paid-plan refusal is documented but not emitted: the contract lists status: "paidRequired" and an errorCode paid_required for get and scan, but get writes the legacy {"status":"paid_required",…} from two hand-written blocks, scan reports only paidPatches, and Status::PaidRequired is never constructed. C54 · filed CLI_CONTRACT.md documents status paidRequired for get and scan, but get emits "paid_required" and scan never reports it #982
• get --mode vendored nests an Envelope inside a legacy object.
• The contract's "Migration status (v3.0)" section still says scan, get and rollback "will migrate in a follow-up PR". That was two majors ago.

2.9 UX: the command model is the real problem

1. Defaults change with unrelated flags.
   • scan is hosted by default, but --prune or --global makes it report-only.
   • get is hosted by default, but --save-only or --global makes it agent mode.
   • So get -g x patches files in place while scan -g only reports.
   • The PATH positionals mean project directories in hosted and vendored mode but installed-path globs in agent mode.
2. The verb scan writes to lockfiles by default. Most users and most CI templates expect a "scan" to be read-only. The safe preview is opt-in (--dry-run).
3. Mode is not project state.
   • mode is deliberately rejected in socket.yml.
   • Bare scan is hosted, and the hosted path performs the vendored→hosted takeover for npm, cargo, golang, PyPI and Gradle-built Maven entries (takeover_capable, scan/hosted.rs); PR Make the vendored-to-hosted takeover atomic #1039 makes it atomic. E70 · in PR Make the vendored-to-hosted takeover atomic #1039; dry-run residuals vendor --dry-run over a hosted requirements.txt pin previews a pypi_requirement_not_pinned failure (exit 1), but the real vendor takes it over and succeeds #668, scan --mode hosted --dry-run --vex <path> --json drops the documented vex: {skipped: true, reason: "dry_run"} marker (agent and vendored scans emit it) #744, Vendored dry run gives no symlink warning for uv script locks or pylock files: a symlinked s.py, s.py.lock, pylock.toml or pylock.<name>.toml previews clean, and the real run then refuses (exit 1) #891, Vendored vendor --dry-run previews success on a uv project with an inline [tool.uv] / sources table, but the real run refuses pypi_uv_lock_parse_failed (exit 1) #979 open This is documented ("vendored → hosted conversions both work in place").
   • So a project vendored for airgapped installs silently becomes hosted the next time someone runs the quick-start command.
   • rollback and list, by contrast, infer mode from on-disk state.
4. Overlapping verbs:
   • get <pkg> ≈ scan --package <pkg>;
   • remove <id> ≈ rollback <id>;
   • vendor ≈ scan --mode vendored (plus eject);
   • vendor --revert ≈ rollback of vendored state;
   • repair (alias gc) is not the scan --prune GC.
   • Top-level help files repair under "Agent mode", but it also rebuilds vendored artifacts.
5. Two styles of usage error: clap's error: the argument '--apply' cannot be used with '--vendor' and the custom Error: --mode hosted cannot be used with --vendor….
6. Warnings render differently: hosted mode wraps and bullets them; other commands print a raw Warning: {detail}.

A simpler command model:

Proposed	Replaces	Notes
socket-patch scan	scan --dry-run	Read-only report of available patches and current state. Safe default.
socket-patch fix [TARGET…] [--mode M]	scan (write), get	No target means everything; a target can be a package, CVE, GHSA or UUID. Mode is inferred from existing project state. --mode is only needed to choose or switch, and switching a project's mode should require --mode explicitly.
socket-patch undo [TARGET…] [--keep-state | --forget]	rollback, remove, vendor --revert	One reversal engine. remove stays as an alias that requires one target.
socket-patch sync	apply, repair, scan --prune	The agent-mode re-apply after install, plus artifact repair and GC.
socket-patch check	vendor --check, apply --check	All read-only verifiers, CI-friendly exit codes.
socket-patch list, socket-patch vex	(unchanged)

That is 7 verbs instead of 9 visible + 2 hidden + 2 aliases + 3 hidden flag spellings, with one rule for mode ("whatever the project is, unless you say otherwise").

2.10 Recommendations

#	Change	Est. LOC	Risk
R1	Route every vendored revert through VendoredBackend (takeover, run_vendor_gc); add a drift-keep regression test	−120	Low; fixes the kept_artifact bug
R2	The fallback moves into ApiClient itself (a one-shot downgrade), so scan, get, vex, apply, rollback, repair and eject all get it	−60	Low; fixes get's and the blob-download gaps C09 · filed #647
R3	RunCtx { config, client, telemetry, lock } built once in main; delete apply_env_toggles and the telemetry plumbing	−300 to −400	Low–Med; unblocks test-binary merging
R4	Finish the envelope migration for scan/get/rollback: one error shape, {code, message}	−300 to −600 net	MAJOR
R5	Split run_scan into discover → select → ModeBackend::consume, rendering JSON/human only at the end	−500 to −800	Medium
R6	Fold remove into rollback/undo	−900 to −1,200	Medium; contract change
R7	Fold get's agent UUID path into the selection pipeline; replace DownloadParams with &GlobalArgs	−250	Low
R8	Per-command flags: delete --vendor-source; move hosted --no-*, vendor and agent knobs to the commands that read them; validate --download-mode at parse time; reject unused flags (warn for one minor first)	−150	MAJOR
R9	Drop deprecated spellings (--apply, --vendor, --no-apply, download, gc); remove SOCKET_FORCE (#615)	−100 + tests	MAJOR
R10	Drop embedded --vex in favor of fix && vex -O	−600 and 15 flag instances	MAJOR, technically low
R11	Move ecosystem_dispatch (950 production lines of pure crawler fan-out on 9c43dfc; its only CLI dependency is GlobalArgs), vendor_records_reusing and the disk hosted orchestration into core behind one orchestrator over ProjectView	−2K to −4K over time	High; incremental. C12 · filed #894, #895; tracking #894, child 1 #895; child 2 (command cycles) in PR #1043; 1,154 / 949 lines at 1c6c509

New findings since the review

• C56 · filed apply, apply --check and vendor report noManifest (exit 0) when .socket/manifest.json exists but can't be stat'd #998 One manifest-presence rule, five copies: apply, vendor, repair, remove and rollback each treat any stat error on .socket/manifest.json as "no manifest" while core's read_manifest treats only NotFound so. apply and vendor fail open (exit 0, noManifest) on a .socket that is a file or a looping symlink (run twice on 9c43dfc).

• C57 · in PR Replace a superseded patch generation's wiring on re-pin and remove #1035 remove resolves its identifier once per store instead of deriving the ledger targets from the manifest entries it deletes: remove <uuid> with an older vendored generation removes the manifest entry, keeps the vendoring and reports success (Fix PyPI vendored→hosted takeover stranding unreachable pins (#699) #708's RED test, run twice on 9c43dfc).

• C09 · filed Only scan, get <uuid> and vex fall back to the public proxy on 401/403; get search, apply, rollback, repair and vendor eject fail #647 The stale-token fallback is wider than get's search gap: apply, rollback and repair blob/diff downloads and vendor eject view fetches never fall back, although CLI_CONTRACT.md promises eject the same fallback as get. On 045d7ec, with the auth API answering 401, apply reported sources_download_failed without trying the proxy; without a token, the same run fetched from the proxy.

• C43 · filed With --manifest-path into another project, rollback, remove, repair, vex, scan and get read the vendored ledger from --cwd #745 --manifest-path interleaves two projects' state. GlobalArgs::project_root() documents that every multi-store command derives its stores from the manifest's project, and list, apply and vendor --check do. But rollback, remove, repair, apply --check, vex, scan and get load the vendored ledger from --cwd. rollback also locks the manifest's .socket/ while writing the cwd ledger. On 045d7ec, with a corrupt ledger in --cwd and --manifest-path ../b/.socket/manifest.json, list succeeded while vex, rollback and repair failed on the cwd ledger; with the corruption moved to b, the results inverted.

• C44 · filed --ecosystems rejects NPM and npm, pypi, which socket.yml patches.ecosystems accepts: the ecosystem name parser is written three times #773 The ecosystem-name parser is written three times. --ecosystems/SOCKET_ECOSYSTEMS require an exact, case-sensitive cli_name() with no trim, socket.yml patches.ecosystems trims and lowercases, and vendor::ecosystem_in_scope has its own exact lookup. On 045d7ec, -e NPM, -e "npm, pypi" and SOCKET_ECOSYSTEMS=PyPI exit 2, while ecosystems: [NPM, pypi] parses. --min-severity and minSeverity already share one parser.

• C45 · filed An invalid --download-mode fails apply and repair with exit 1 but is accepted by every other command #791 --download-mode typos are runtime failures in two commands only (see 2.7): apply/repair exit 1 with a generic command code, and the rest accept them. This narrows the review's R8 note to a non-breaking fix (a typed clap parser).

• C13 · filed Tracking: emit every --json error code from one typed ErrorCode registry checked against the contract tables #930, An unparseable .socket/manifest.json is reported under five different --json error codes depending on the command #931; tracking Tracking: emit every --json error code from one typed ErrorCode registry checked against the contract tables #930, child 1 An unparseable .socket/manifest.json is reported under five different --json error codes depending on the command #931 (manifest mapper) One corrupt manifest, five --json codes: only list and remove implement the contract's manifest_invalid/manifest_unreadable split (two hand-written copies); apply and vendor each disagree with their own --check path. Child 1 of the typed-code tracking issue ().

• C14 · in PR Make every --json top-level error a {code, message} object (#704) #1027; decided 2026-10-07: top-level error always {code, message}; every self-enforced exit 2 through one usage_error Usage errors (exit 2) choose their own --json channel per site: 4 of the ~17 return 2 sites in commands/ write JSON, the rest stderr only. This is folded into the envelope decision as its second question; decided (Decide: one shape for the --json top-level error (scan and get emit both a string and a {code, message} object) #704, rule b), fix pending.

• C54 · filed CLI_CONTRACT.md documents status paidRequired for get and scan, but get emits "paid_required" and scan never reports it #982 The contract's paid-tier codes match no command: get emits status: "paid_required" (snake_case, no events or errorCode) and scan emits nothing paid-specific, while CLI_CONTRACT.md documents status=paidRequired for both. The fix is documentation plus one shared get emitter.

• C58 · filed Decide: should vex exit 1 on runtime failures, like every other command, instead of 2 #1047 vex is the one command whose exit 2 is not a usage error: every runtime failure but "nothing attested" exits 2 (manifest_unreadable, manifest_not_found, write_failed, …), while the same corrupt or missing manifest exits 1 on apply --check, vendor --check, remove, repair and embedded --vex (run twice on c5be5d1).

• C61 · in PR Stop CI gates passing on missing paths, unverified agent patches and unreported hosted pins #1029; hosted exit code waits on Decide: one shape for the --json top-level error (scan and get emit both a string and a {code, message} object) #704 October 7: --cwd, --global-prefix and --manifest-path were never validated, so list, apply, vendor --check, scan and get exit 0 on /nonexistent; apply --check checked Go only; hosted --json has no per-purl pin data (PR Stop CI gates passing on missing paths, unverified agent patches and unreported hosted pins #1029).

• C62 · in PR Use one package target grammar for get, remove, rollback and the UUID shortcut #1034 October 7: four package-target grammars; get <name> fuzzy-substitutes (get yaml patched yaml-ast-parser) and searched one version; the UUID path skipped socket.yml silently (get <uuid> overrides socket.yml without the documented policy_bypassed warning (purl/CVE/GHSA forms do warn) #453; PR Use one package target grammar for get, remove, rollback and the UUID shortcut #1034).

• C70 · filed scan exits 1 in human output but 0 with --json when every patch query returns nothing #1062 The JSON and human arms of run_scan apply different fetched == 0 rules (exit 0 vs 1).

• C73 · filed rollback --json counters count only the agent leg, so hosted and vendored failures report failed: 0 #1066 rollback --json counters cover only the agent leg.

(The C38 pacing finding is in Part 7.)

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

[agent] Part 3 of 9 of the living socket-patch architecture document. The summary and ranked recommendations are in the top post. Originally written against 2463257; the routines update this part as the code changes.

Part 3: Hosted mode (redirect, hosted engine, upstream restore, Node addon)

Last checked against main @ 05ecc6e on 2026-10-07 by audit-ecosystems (3.2 RewriteResult sets, merge_group_delta and confirm() re-checked for E31; hosted NuGet lock walk and Maven suffix splice re-checked). Earlier: 431b818 by the October 7 reconciliation (3.1 scope note, 3.3 memory takeovers, 3.5 restore size and credentials re-checked). Earlier: db83f01 by audit-ecosystems (3.2 redirect/mod.rs size and layout re-checked at db83f01; hosted Maven/Gradle grant handling checked at 9c43dfc; 3.4 NuGet.config readers as of 4646693; 3.6 vlt dead helpers as of 045d7ec; the rest as of 203e092). Owner: audit-ecosystems.

Scope: patch/redirect/**, hosted/**, crates/socket-patch-node/**, CLI scan/hosted.rs, scan/hosted/*, hosted_bundle.rs.

3.1 Size

Area	Prod (code-only)	Inline tests
patch/redirect/ (excl. upstream/)	10,517 (8,117)	18,806 — 11,365 of it in mod.rs
patch/redirect/upstream/	7,446 (6,323)	1,605
hosted/ (engine 1,448; memory/* 3,466)	5,601 (4,426)	1,013
socket-patch-node	651 Rust + 517 JS/TS	479
CLI hosted (scan/hosted.rs 2,267, hosted/* 601, hosted_bundle.rs 184)	3,052	2,166

The table predates Gradle (#646), sbt (#690) and hosted/governing_root.rs; at 1c6c509 redirect/mod.rs alone is 21.9K lines (7.6K production) and upstream restore is ~8.8K production lines. E30 · filed #1010, #1011; tracking #1010, child 1 #1011 (inline tests out)

That is about 27K production lines for hosted mode at the snapshot (more now), plus about 23.6K lines of inline tests and about 42K lines of hosted integration tests (e2e_redirect_*, in_process_redirect*, hosted_memory_*, rollback-hosted, core goldens).

3.2 How the redirect logic is organized

There is no trait. Each rewriter is a free function with the signature fn(&BTreeMap<String,String>, &[DepOverride], &mut RewriteResult), wired up by hand:

• rewriter_groups builds a Vec<Box<dyn Fn>> (redirect/mod.rs:426-457).
• A serial "withholding prefix" runs first: pdm, then pipenv, then withhold (:379-412).
• Each rewriter filters its own dependencies with o.ecosystem == "npm"-style string compares: 12 in mod.rs, 7 in engine.rs.

RewriteResult is a cross-ecosystem grab bag (mod.rs:220-370 at 05ecc6e). It holds 27 per-ecosystem uuid sets (20 at the review; sbt and Gradle added the rest), such as confirmed_cargo_uuids, refused_pdm_uuids and vlt_foreign_uuids. The CLI (scan/hosted.rs) and vex/discover/gradle.rs read some of them directly. Two places consume them all: E31 · filed #1075, #1076; tracking #1075, child 1 #1076 (one report map, mechanical)

• merge_group_delta, which destructures every field (:753-831);
• engine::confirm, a 225-line ordered chain of 25 ProbeStep outcomes keyed on purl prefixes, driver predicates and those sets (hosted/engine.rs:1652-1876).

Adding an ecosystem to hosted mode means editing at least eight parallel tables:

• formats::registry::REGISTRY;
• upstream::format_of and the restore_pass match;
• engine::file_ecosystem;
• memory::select::classify;
• roots::UNSUPPORTED_MARKERS;
• rewriter_groups;
• the RewriteResult fields;
• confirm().

Long functions.

Lines	Function
836	run_redirect_selected (CLI scan/hosted.rs:639)
604	engine (hosted/memory/mod.rs:430)
455	rewrite_gem (mod.rs:4750)
439	plan_cargo_toml (mod.rs:2516) E15 · filed #693, #757
394	rewrite_cargo (mod.rs:1062)
361	vendored_takeover (scan/hosted.rs:1497)
357	rewrite_maven_pom (mod.rs:5341)
283	rewrite_golang
272	rewrite_yarn_berry
196	pnpm_trust (engine.rs:897)

In total there are 647 functions, 44 of them over 100 lines.

Other symptoms:

• Four telescoping public entry points each add one parameter: rewrite_registry_redirect → _with_python_metadata → _with_pipenv_version → _withholding_vlt (mod.rs:292-412).
• boxed_run_redirect_selected exists only because the async future is too large for the 1 MiB Windows main-thread stack (scan/hosted.rs:2213). That is a direct symptom of the 836-line function.

redirect/mod.rs is a 21.9K-line god module (21,936 lines at db83f01; 17.5K at the snapshot). Its 7.6K production lines (L1–L7622) mix six concerns: E30 · filed #1010, #1011; tracking #1010, child 1 #1011 (inline tests out)

1. wire types (Integrity, DepOverride, FileEdit, RewriteWarning, RewriteResult);
2. orchestration: entry points, withholding, and a parallel-groups engine that runs each group on a prefix.clone() in a scoped thread, merges the deltas, and falls back to serial;
3. eleven ecosystem rewriters, where cargo alone takes lines 1050–2952 (1,903 lines);
4. hosted-URL ownership and grant-token redaction, separate from the 47-line hosted_url.rs beside it;
5. a utility library for other modes: cargo_socket_registry_pin, TRUSTED_CHECKSUMS_ON, local_repo_artifact_path and gem_line_trailing_options are imported by vendor/cargo.rs, vendor/gem.rs, vendor/nuget_feed.rs and vex/discover/maven.rs; since sbt, Mill and scala-cli support in agent, hosted and vendored modes #690, formats/sbt/owned_file.rs also imports bare_sha256_hex from it (a new formats → redirect edge);
6. 14.3K lines of inline tests at db83f01 (L7623–L21936; 322 tests in six modules). Moving them to sibling files is Move patch/redirect/mod.rs's inline test modules into sibling test files #1011, the first step of the split (Tracking: split patch/redirect/mod.rs into per-ecosystem modules and sibling test files #1010).

Misplaced and dead code.

• redirect/golang_local.rs (690 prod / 1,733 test) documents itself as the "Project-local Go replace-redirect engine (local mode only)". It is called from apply.rs, vendor/golang.rs, rollback.rs and vex.rs; it is not hosted code.
• vlt_heal::ledger_targets (~58 lines) and vlt::edit_dep_id, lock_node_ids and carried_pin_original are pub but are called only from their own tests. They read the retired pre-v5 RedirectState ledger, which state.rs:1-8 says is "never" written.

3.3 Two orchestrators: disk and in-memory

The shared stages are good: build_candidates, read_candidate_files, rewrite, confirm and guard live in hosted/engine.rs and run over ProjectView::{Disk, Memory, Snapshot}. The orchestration around them is written twice: once in the CLI's run_redirect_selected (836 lines), and again in the memory engine's engine (604), stages.rs (319) and discover.rs (366).

Step	Disk (CLI)	Memory
Reference fetch, lenient for capped all-NEW runs	hosted.rs:665-713	memory/mod.rs:754-788
vlt preflight → withhold_everywhere	hosted.rs:742-754 (online)	stages.rs:180-193 (offline, so vlt is always withheld)
Wheel-metadata fetch	hosted.rs:818-903, bespoke retry window	discover.rs:320 + stages.rs:256-281
Rollout second-pass rewrite	hosted.rs:950-1011	memory/mod.rs:839-930
Selection policy	ScanPolicy::select (recorded-aware)	select_with_policy ("without a recorded view")
Bounded concurrency	utils/concurrent.rs::ordered_concurrent	discover.rs::join_bounded, a hand-rolled ~45-line poll_fn
Warning merge order	rewrite, vlt preflight, record, rush, pnpm, npm	rewrite, record, rush, pnpm, npm, vlt preflight

The warning-order row is a real divergence, and nothing catches it: hosted_memory_parity.rs has no vlt cases.

ProjectView leaks.

• engine.rs has seven match view { Disk | Snapshot => …, Memory => … } branches.
• memory/select.rs::classify must mirror read_candidate_files by hand: python scripts, Cargo members, Rush subspaces and EXTRA_TEXT_FILES. Any new disk read that is not mirrored there turns into a candidate_file_unreadable refusal in memory.

The parity suites exist only because there are two orchestrators: hosted_memory_parity.rs (1,113 lines, 31 tests), hosted_memory_common (473) and hosted_memory_rollout.rs (639). Some outputs even need normalizing before they compare equal (without_pipenv_advice).

The memory engine also cannot reach several rewriters: vlt is always offline-withheld, maven and nuget raise ecosystem_unsupported_in_memory, and only npm, cargo and golang takeovers are refused (refuse_takeovers, memory/stages.rs): a vendored PyPI or Gradle-built Maven entry, which the disk flow takes over, is not on the memory list (B15; PR #1039 shares one predicate). E70 · in PR #1039; dry-run residuals #668, #744, #891, #979 open So about 1,060 lines of maven/nuget rewriter plus the vlt rewriter are disk-only.

Recommendation. Both paths converge on selected: &[(purl, uuid)]. Build the disk path as DiskSnapshot → MemoryProject, then run a single redirect_root(view, selected, api, hooks). Host-only effects become hooks: the apply lock, performing versus refusing a takeover, online versus offline vlt preflight, the pipenv probe, write-back, the stale-install probe, vlt heal and VEX. That saves roughly 700–900 production lines, and the parity suite becomes ordinary tests.

3.4 Duplication with vendored, VEX and formats

A "one model per format" layer (formats/) has been started, and hosted mode is the main holdout. Several module docs say so explicitly.

• package-lock.json: four walks and two serializers. Hosted serialize_json (mod.rs:273) always writes 2-space JSON. Vendor's serializer preserves the file's indent. Upstream restore uses the hosted one, so hosted rewrites and rollback reformat a 4-space or tab-indented lock in full (open issue npm lock rewrites drop CRLF (and hosted drops tab indent), so rollback and vendor --revert are not byte-exact; BOM locks are refused #324).
• yarn.lock: five copies of a split("\n\n") + regex grammar (mod.rs:2992, :3159, :3278, upstream/npm.rs:289, :390), alongside the shared scan_blocks used by vendor, inventory and VEX.
• NuGet.config: two readers. Hosted routing and splice anchors now go through formats::nuget::parse_config, the bounded tokenizer that upstream restore and VEX use; the hosted regex reader nuget_package_source_keys and the regex anchors were deleted (Unify hosted NuGet routing and XML splice anchors #597). Vendored nuget_feed.rs still keeps its own comment-blanking reader (parse_config_source_keys) and find-based anchors. E10 · filed Tracking: read and edit pom.xml through one element scanner in formats::maven #715, Vendored Maven refuses a single-module EAR pom as a multi-module aggregator because two declares_modules disagree #716, Locate hosted Maven pom edits and their upstream restore through the formats::maven element scanner #717, Read and splice nuget.config through formats::nuget in hosted, vendored and restore #594; NuGet hosted reader fixed (Unify hosted NuGet routing and XML splice anchors #597)
  • A commented-out <add key="…"> no longer suppresses the nuget.org seed, because hosted reads through the shared reader (Unify hosted NuGet routing and XML splice anchors #597). E01 · fixed (Unify hosted NuGet routing and XML splice anchors #597)
• requirements.txt: utils/requirements.rs:1-9 says vendor, inventory and VEX share logical_lines, but "the hosted requirements rewriter … keeps its own line splitter" (redirect/requirements.rs:17). Upstream has a fourth reader.
• Cargo.toml: two grammars inside one rewriter. There are six LazyLock regexes plus classify_cargo_section, alongside four toml_edit parses of the same file. The dependency tables are walked five times across hosted, utils/cargo_workspace and VEX.
• Gemfile / Gemfile.lock: formats/gem claims to be "the ONE read model", yet rewrite_gem still regex-scans CHECKSUMS and the Ruby source, compiling a Regex::new per dependency inside the loop (mod.rs:4866-4945). Open issue Hosted gem redirect breaks a multi-line gem declaration (the Gemfile stops parsing) and drops a trailing if/unless modifier #340, which breaks multi-line gem declarations, lives here.

What already works, and is the template to copy: formats::bun::BunTextLock, formats::cargo::CargoLock, vendor::go_mod_edit/go_sum_edit and formats::pnpm are each one model shared by hosted, inventory, VEX and upstream.

Module cycles (production crate::X:: references):

From → To	Refs	Reverse	Refs
redirect → vendor	49	vendor → redirect	10
vex → redirect	16	redirect → vex	5
redirect → formats	19	formats → redirect	5

formats/pnpm/hosted.rs:11 imports RewriteResult and FileEdit, so the "pure" format models depend on the hosted engine's result type. In practice vendor/ has become the codec library.

3.5 Upstream restore: rebuilding what was thrown away

Cost. ~8.8K production lines at 1c6c509 (7,446 at the snapshot: Python 2,474 (uv 1,152), infrastructure 1,395, gem 743, npm 754, maven 400, composer 373, cargo 361, nuget 350, vlt 329, bun.lockb 153, golang 114). PR #918 has since taken over part of this section's npm restore; #919 and #992 remain open. Tests add 1,605 inline lines, 1,913 lines of golden tests and about 1.9K lines of in_process_rollback_hosted.

Why it exists. v5 dropped the redirect ledger. Yet every rewriter still computes FileEdit { original, new }, with 30 FileEdit { literals in mod.rs. In production, original is read only by the Composer reinstall hint (cli composer_hints.rs:69-99). So the original bytes are computed, discarded, and later re-derived from the network.

Network dependencies: the npm registry, the crates.io sparse index, the Go proxy and sum.golang.org, the PyPI JSON API, RubyGems, Packagist, NuGet registration5-gz, and a Socket /upstream/npm/<uuid>.json endpoint for berry checksums. That last one may download the whole upstream tarball to verify it.

Failure modes:

• refused when offline;
• registry fetches never send credentials, so a private registry that needs auth is unreachable;
• private registries and mirrors are ignored. npm restore always uses SOCKET_NPM_REGISTRY or the public registry, so an Artifactory project comes back with public URLs;
• heuristic re-derivation of package-manager output (uv re-derives specifiers "in uv's spelling" and the sdist/wheel shape from sibling entries);
• bun.lockb is always refused;
• partial writes;
• a pass-until-stable loop (upstream/mod.rs:564-610).

The open backlog shows the cost:

• Hosted uv rollback and remove delete a user-authored override-dependencies = ["<pkg>==<ver>"] pin that hosted mode never added #411: uv rollback deletes a user's own override-dependencies pin;
• Hosted rollback, remove and the vendored takeover refuse a requirements.txt whose only requirements are hosted pins (six==1.16.0 alone can be patched but never unpatched) #410: requirements.txt with only hosted pins can be patched but never unpatched;
• Hosted rollback rewrites uv pylock.toml upload-time with milliseconds, so the restored file never matches what uv writes #408: uv upload-time gains milliseconds;
• Hosted rollback, remove and vendored takeover always refuse on a uv pip compile pylock.toml because its packages carry no index key #407: uv pip compile pylock always refused;
• Hatch rollback and remove refuse with "configuration drifted" after the project version is bumped or a dependency is added, in both hosted and vendored mode #385: Hatch refuses after a version bump;
• Hosted PDM rollback and remove fail permanently once the patched package leaves pdm.lock (pdm remove, or an upgrade to another version), and the suggested re-scan doesn't help #382 and Hosted PDM rollback reports success but leaves the patch url/hash in pdm.lock after pdm add or pdm lock --update-reuse and a re-scan #331: PDM rollback fails permanently or leaves the pin;
• Hosted Maven redirects cannot be reverted, and remove recommends an unscoped rollback that also fails #271: Maven hosted redirects cannot be reverted at all.

Assessment. Upstream restore is justified only where the original entry is a pure function of registry data: npm/pnpm/bun-text resolved + integrity, cargo cksum, go.sum, the gem checksum, the composer dist and the nuget hash. That is about 2.2K lines.

For uv, pylock, poetry, pdm, hatch, vlt, maven and bun.lockb, the module's own fallback (checkout_remedy: "git checkout -- <lockfile>") or a package-manager relock is cheaper and more correct:

• uv lock --upgrade-package X
• poetry lock --no-update
• bundle lock --update X

There are two cheaper alternatives:

• (a) Narrow restore to the pure-function formats and refuse the rest with a precise remedy: about −3.3K production and −2K test lines.
• (b) Keep the originals the rewriters already compute in a tiny content-addressed sidecar, for example .socket/hosted-originals/<sha>.json, ignorable and git-committable. Byte-exact rollback then needs no network at all. This is the same "record original → splice back" approach vendored mode uses.

3.6 Per-package-manager features with poor complexity-to-value

Feature	Prod LOC (approx.)	Notes
vlt hosted	2,454 + 1,707 tests	The warm-tree heal deletes node_modules/.vlt store entries: installed-tree surgery in a lockfile-only mode. vlt never redirects in memory. Contains dead ledger helpers (edit_dep_id, lock_node_ids, carried_pin_original, vlt_heal::ledger_targets), orphaned when #277 removed the ledger merge. E58 · filed #782
npm allow-remote auto-config	~900 + 514 tests	npmrc.rs re-implements npm's ini tokenizer and its user/global/builtin/env config layering, all to decide whether to append one line to .npmrc.
pnpm trustLockfile auto-config	~450	Heal-on-rerun, takeover previews, legacy and Rush special cases. Open issues #400, #401, #402 (quoted keys, flow style, duplicate keys) are all here.
Parallel rewriter groups	~260 + 451 equivalence tests	Parallelizes CPU work over a handful of texts that is already single-pass. Benchmark it, or delete it.
In-memory engine + napi addon + hosted-bundle	~4.8K + ~4.6K tests	npm/package.json is "private": true; CI only builds and smoke-tests it. Worth it only if the depscan backend actually replaces its TypeScript rewriters with it. Otherwise there are three implementations: TS, disk and memory.
bun.lockb hosted	~260 on top of the 2.25K shared codec	Legacy format.
Equivalence-test scaffolding	2,592 lines + 252 KB goldens	Refactor oracles ("blessed while the previous rewriter still ran beside it"), now frozen as snapshots.
Warning vocabulary	~130 distinct codes in this slice; 89 RewriteWarning { literals in mod.rs; no enum	Families repeat per ecosystem: missing-integrity ×15, entry/package-not-found ×13, no-lockfile/manifest ×7.

3.7 Recommendations

1. Split redirect/mod.rs mechanically (net ~0 lines, low risk): E30 · filed Tracking: split patch/redirect/mod.rs into per-ecosystem modules and sibling test files #1010, Move patch/redirect/mod.rs's inline test modules into sibling test files #1011; tracking Tracking: split patch/redirect/mod.rs into per-ecosystem modules and sibling test files #1010, child 1 Move patch/redirect/mod.rs's inline test modules into sibling test files #1011 (inline tests out)

   • model.rs for the DTOs;
   • driver.rs for orchestration;
   • one file per ecosystem, with cargo/ split into {manifest, config, lock, pins};
   • merge the hosted-URL and token helpers into hosted_url.rs;
   • move golang_local.rs to agent mode;
   • move the 11.4K test lines into sibling tests.rs files.

2. Introduce trait HostedRewriter { ecosystem(); drives(&FileSet) -> bool; rewrite(&FileSet, &[&DepOverride]) -> Outcome }, with Outcome { files, edits, warnings, per_dep: BTreeMap<Uuid, DepStatus> } where DepStatus is Confirmed, Refused, Foreign or Unclaimed. It replaces the 27 RewriteResult sets, merge_group_delta and most of confirm(). The "driver" rules for pdm/vlt/uv/sbt become drives(). E31 · filed Tracking: hosted rewriters behind one HostedRewriter trait with a per-dependency outcome #1075, Replace RewriteResult's 27 per-ecosystem uuid sets with one report map #1076; tracking Tracking: hosted rewriters behind one HostedRewriter trait with a per-dependency outcome #1075, child 1 Replace RewriteResult's 27 per-ecosystem uuid sets with one report map #1076 (one report map, mechanical): tracking Tracking: hosted rewriters behind one HostedRewriter trait with a per-dependency outcome #1075, step 1 (one report map, mechanical) is Replace RewriteResult's 27 per-ecosystem uuid sets with one report map #1076.

3. Finish one codec per format in formats/, in this order:

   • package-lock (4 walks → 1, indent-preserving);
   • yarn (five split("\n\n") sites → scan_blocks);
   • NuGet config (3 readers → 1, which fixes the comment bug);
   • requirements;
   • Cargo.toml (regex scanner → toml_edit).

   Move the neutral types (Edit, Warning, LockfileEntry) into formats to break the cycles.

4. One hosted pipeline for disk and memory (about −800 lines; the parity suites become ordinary tests).

5. Narrow upstream restore, or replace it with an originals sidecar (about −3.3K production lines). This also fixes a whole family of open rollback bugs.

6. Decide the addon's fate. If depscan adopts it, delete the TS rewriters and relax the JSON.stringify(…, 2) golden contract, which unblocks indent preservation. If not, delete the addon, hosted-bundle and the memory-only branches (about −4.8K production, −4.6K test).

7. Simplify the npm allow-remote handling to project-file-only planning plus a warning (about −700). Drop the parallel groups unless benchmarks justify them, and delete the dead vlt ledger helpers.

8. Make warning codes typed: enum Reason { MissingIntegrity, EntryNotFound, NoLockfile, … } × Ecosystem, serializing to today's strings.

9. Retire the refactor-oracle equivalence suites (2.6K lines + 252 KB goldens) and the telescoping entry points; use one RewriteOptions struct instead.

New findings since the review

• E50 · filed Hosted NuGet rewrites packages.lock.json entries at other versions of the patched id #593: hosted rewrite_nuget and upstream restore rewrite every packages.lock.json entry of the patched id, in every target framework, whatever its resolved version; vendored locked_at only touches entries at the patched version. packages.lock.json has four walkers (hosted, restore, vendored, VEX).
• E52 · filed Delete go_sum_edit's oracle-only free functions and move the go.sum codec to formats #631: vendor/go_sum_edit.rs keeps free upsert_module_lines / has_module_version / remove_exact_module_version_lines with no production caller, re-implemented by the GoSumEditor the hosted Go rewriter uses; the free copies survive only as a test oracle, and the pure hosted codec lives in vendor/.
• E15 · filed Read Cargo.toml package name and version through one shared toml_edit reader #693, Hosted cargo redirect refuses a dependency whose inline table has a multi-line features array, because it plans Cargo.toml pins with a line scanner #757: the hosted cargo planner plan_cargo_toml is a line scanner, gated by a second toml_edit classifier of the same declarations. It refuses serde = { version = "1", features = [⏎ "derive",⏎] } as "inline table does not close on its line", although cargo and toml_edit accept it, so hosted skips a crate that vendored mode handles. Upstream restore unpins with a third, line-level grammar.
• E58 · filed Delete the vendored and hosted-vlt helpers left without a production caller by the v5 consolidation #782: the hosted-vlt ledger helpers edit_dep_id, lock_node_ids, carried_pin_original and vlt_heal::ledger_targets have no production caller since v5 prerelease: scan → vex → vendor workflow, hosted by default #277 deleted rebase_vlt_edits and the ledger heal; UpstreamClient::seed_rubygems_sha256 is a test helper compiled into production.
• E73 · in PR Decide whether a hosted patch is pinned through lockfile discovery alone #1058; lockless pins wait on E45 October 7: "is this hosted patch pinned" is decided four ways (confirm, mark_pinned, memory_recorded, discovery); lockless NuGet/Cargo pins are attested in-run then reported contested forever (PR Decide whether a hosted patch is pinned through lockfile discovery alone #1058).
• E85 · filed Hosted NuGet rewrites and restores packages.lock.json with LF and no BOM, so a CRLF lock is rewritten whole #1068 The NuGet lock writer and its restore drop CRLF and BOM (serialize_json), unlike every other hosted JSON writer.
• E63 · filed Hosted Maven splices the API's suffixed version into pom.xml unchecked, while hosted Gradle refuses the same grant #882: hosted Maven splices the API's maven_suffixed_version into every matching pom.xml <version> without checking it (proven with -socket.DEADBEEF, -patched and markup), while the hosted Gradle planner (Full Gradle support in agent, hosted and vendored modes #646) refuses the same grant unless it is <base>-socket.<uuid[..8]>. The suffix grammar has four builders (vendored jvm::Coords, hosted Gradle, the CLI vex_consumed copy and the server) and no shared validator.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

[agent] Part 4 of 9 of the living socket-patch architecture document. The summary and ranked recommendations are in the top post. Originally written against 2463257; the routines update this part as the code changes.

Part 4: JavaScript lockfiles (npm, pnpm, yarn, bun, vlt)

Last checked against main @ 431b818 on 2026-10-07 by the October 7 reconciliation (formats/yarn contents, the governing-lock count, the pnpm-legacy row and the yarn grammar copies re-checked; sizes and line references in 4.1–4.4 are still from the snapshot and drift by 200–1,000 lines). Earlier: 9c43dfc by audit-ecosystems (vendor driver skeleton re-checked at 9c43dfc; pnpm BOM handling in formats::pnpm re-checked at 9c43dfc; §4.4 vendored pnpm package.json writer re-checked at 4646693; as of 045d7ec: pnpm, berry gates, package-lock walks, JSON writers, bun-lock presence, CRLF policies, wiring-kind and lines↔JSON helpers and the 4.5 #2 layering re-checked; the rest is as of 2463257). Owner: audit-ecosystems.

Scope: vendor/{npm_*,pnpm_*,yarn_*,bun_*,vlt_*,berry_zip}.rs, formats/{pnpm,yarn,bun,registry}, crawlers/npm_crawler*, vendor/lock_inventory/*, vex/discover/{npm,yarn,bun,vlt}.rs, and the JS parts of patch/redirect/ and hosted/vlt.rs. Line counts are production / inline-test, split at the first top-level #[cfg(test)] mod.

4.1 Summary

• The read side is mostly consolidated; the write side is not. VEX discovery and lock inventory already share one entry walk per format: npm_lock_nodes, formats::pnpm::pnpm_packages, classic_entries/berry_entries, BunTextLock, BunLockb::parse_packages and vlt_lock_model. The writers are separate: the hosted rewriter, the hosted upstream restore and the vendored backend each still have their own splicer for package-lock, pnpm and yarn.
• There is no lockfile abstraction. The only lockfile trait in this area is a private EditLines (vendor/pnpm_lock.rs:2295). Each mode dispatches its own way:
  • Vendored mode switches on a 7-variant NpmLockFlavor enum in six separate match blocks (npm_flavor.rs:59, :75, :383, :485, :591, :691). On top of that sits a vend! macro (:367-382), which exists because nine-argument functions have no trait to attach to.
  • Hosted mode runs every rewriter in a fixed chain (patch/redirect/mod.rs:435-439).
  • VEX calls every extractor in turn (vex/discover/mod.rs:727-730).
• formats/ is a half-finished migration. Its module doc promises each format owns "the entry grammar, the key rules, the version sniff and the planners" (formats/mod.rs:1-24). Reality:
  • pnpm partly conforms.
  • formats/yarn now holds the version sniff plus the shared berry entry reader (berry_entry.rs) and the berry project gates (berry_gates.rs, Fix yarn berry project gates drifting between modes (#628, #629) #657), ~760 lines in all; the classic and berry block grammars and the seven split("\n\n") rewriter grammars still live in vendor/ and redirect/ (PR Move all yarn.lock parsing into formats/yarn and stop pinning non-registry copies #1057 moves them). E08 · in PR Move all yarn.lock parsing into formats/yarn and stop pinning non-registry copies #1057; confirmed at 1c6c509 (7 splits)
  • formats/bun is a 49-line wrapper around vendor::bun_lock_text.
  • package-lock and vlt have no formats module at all.
• Legacy and rare formats are the cost centers. Vendored pnpm-legacy, bun.lockb and vlt together are about 11.2K production lines and more than 15K inline-test lines, with roughly 10K more lines of CLI integration tests.

4.2 Code per format

Format	Main files (prod/test)	Prod	Inline tests	CLI test files
package-lock	npm_lock.rs 1291/3230; redirect §745-1049 (305); upstream/npm.rs 21-240 (~220); lock_inventory/npm.rs 155; vex/discover/npm.rs 57-301 (~245)	~2.2K	3.2K+	—
pnpm v9 + hosted (all generations)	pnpm_lock.rs 3174/5341; formats/pnpm 1431/85; lock_inventory/pnpm.rs 151; upstream 478-583; vex 302-491	~5.0K	5.4K + 544 equivalence	6.1K (all pnpm)
pnpm legacy (5.4/6.0, vendored)	pnpm_lock_legacy.rs (thin dialect wrappers over pnpm_lock.rs since #583; 4,918 lines with tests at 431b818)	1,853 at the snapshot	3,217	(in 6.1K)
yarn classic	yarn_classic_lock.rs 1099/1916; redirect §2952-3140 (189); upstream 241-364	~1.8K	1.9K+	7.3K (yarn total)
yarn berry	yarn_berry_lock.rs 1417/2723; redirect §3141-3510 (370); upstream 365-477	~2.3K	2.7K + 1,061 layering	(in 7.3K)
bun.lock (text)	bun_lock.rs 1033/2838; bun_lock_text.rs 275/245; redirect §3511-3768 (258); upstream 584-686	~1.7K	3.1K	6.6K
bun.lockb (binary)	bun_lockb.rs 1663/591; bun_binary.rs 664/351; bun_workspace.rs 184/199; redirect/bun_binary.rs 108/61; upstream/bun_lockb.rs 152/229	2,771	1,431	1,574
vlt	vlt_lock.rs 2080/2032; vlt_lock_text.rs 1008/1540; npm_dir.rs 910/319; redirect/vlt.rs 676/313; vlt_heal.rs 542/573; vlt_preflight.rs 233/302; hosted/vlt.rs 217; upstream/vlt.rs 328/268; inventory 165; vex 392/794	6,551	6,141	~9.3K (10 files + 3 shared dirs)

Shared npm-family infrastructure adds npm_common.rs 613/832, npm_flavor.rs 707/1338 and about 1.8K lines in lock_inventory/{mod,view,wired,recover,npm_family}.

crawlers/npm_crawler/oracle.rs (1,846 lines) is entirely test code: a verbatim copy of the old crawler, kept as an equivalence oracle (oracle.rs:1-5). It has done its job and can be retired.

4.3 Parser and splicer matrix

Format	Vendored writer	Hosted writer	Hosted restore	Inventory + VEX	recover.rs	Independent parsers
package-lock	scan_lock_matches :854, rewrite_legacy_tree :978 (serde Value, rendered with JsonLayout since #357)	rewrite_one_npm_lock :881, rewrite_npm_v2_deps :1095 (serialize_json_like → JsonLayout, #357)	npm_lock_hits :62, v2_hits :98	npm_lock_nodes	full-object original :307	4 entry walks E07 · in PR #1008
pnpm	formats/pnpm/lines.rs (Vec<String>, refuses CRLF) + own LockIndex/memo (446 lines)	formats/pnpm/hosted.rs::plan_hosted over grammar.rs (byte offsets, CRLF-aware)	grammar.rs	grammar.rs	shared	2 grammars; 3 resolution: emitters (grammar.rs:164, pnpm_lock.rs:1992, pnpm_lock_legacy.rs:1137)
yarn classic	scan_blocks (line-based, keeps CRLF)	split("\n\n") + regex (redirect/mod.rs:2992), manual \r\n handling	split("\n\n") + regex (upstream/npm.rs:289)	scan_blocks	ad-hoc strip_prefix("integrity ")	2 block parsers + 1 ad-hoc
yarn berry	scan_blocks + berry_field	split("\n\n") + regex :3278; berry_cache_key :3158	split("\n\n") + regex :390	berry_entries	inline_yaml_field	2 + 1 ad-hoc; project gates written twice
bun.lock	bun_lock_text	same	same	same	split('"')	1 codec (good) + 1 ad-hoc
bun.lockb	bun_lockb.rs	same	same	same	snapshot JSON	1 codec (good)
vlt-lock.json	vlt_lock_text	same	same	same	parse_node_entry_text	1 codec (good)

The question "which lockfile drives installs?" is also answered in at least eight places with different rules (the five below, plus vlt_drives with SIBLING_LOCKS, the bun presence probes and the PyPI precedence that hosted ignores). PR #1044 replaces them with one formats::governing_locks table. E75 · in PR #1044; vlt and Pipenv precedence policy needs a maintainer call

1. vendor/npm_flavor.rs:151-300.
2. A hand-written copy for in-memory projects, detect_npm_lock_flavor_in (lock_inventory/view.rs:360-447). It re-spells the refusal strings, never emits vendor_multiple_lockfiles, and lacks the pnpm-PnP carve-out.
3. LOCKFILE_FAMILIES (npm_flavor.rs:98).
4. A hard-coded sibling-lock list in redirect/mod.rs:776-787 that bypasses formats::registry.
5. Layout-based detection in crawlers/pkg_managers.rs:96, with a different precedence.

The modes disagree on policy. Vendored mode picks one flavor and warns about the rest. Hosted mode runs all five npm-family rewriters over every lock present. A repo with both yarn.lock and package-lock.json therefore gets both rewritten in hosted mode but only yarn.lock in vendored mode.

4.4 Verified duplication

pnpm v9 vs pnpm legacy. The drivers are now shared (#583): vendor_pnpm_legacy and revert_pnpm_legacy_opts are thin wrappers over pnpm_lock::vendor_pnpm_dialect / revert_pnpm_dialect with PnpmDialect::Legacy (pnpm_lock_legacy.rs#L200-L223, #L894-L900), and KIND_LOCK_PACKAGE is imported, not redefined. What stays per dialect is the legacy line grammar: read_lock, preflight_package(s), lock_has_target_package, edit_*_v54/v60, revert_lock_record and the Ctx methods. E12 · partly fixed (#583); copies merged, v9 dual lookup remains (pnpm workstream, #1007)

The vendor driver skeleton is copied seven times. npm_lock, pnpm (both dialects since #583), yarn-berry, yarn-classic, bun_lock, bun_binary and vlt (about 1,940 lines) all repeat the same sequence:
guard_coordinates → read the lock → preflight → stage_patch_pack (stage_patch_dir for vlt) → already_patched_result → write_marker_or_warn → a literal 20-field VendorEntry { … pdm: None, pipenv: None, poetry: None, uv: None, … }.
The copies have drifted: the "patch rewrites package.json" warning has two codes (vendor_dep_manifest_rewritten vs _stale) and fires on in-sync re-runs for pnpm and bun only, and bun_binary computes its own uuid_dir_preexisted. read_project, preflight_package(s) and revert_*_opts exist in 7-9 files each. E22 · in PR #1008; tracking #920 and child #922 both claimed (draft)

Yarn berry project gates are written twice. E09 · fixed (#657)

• cacheKey 10c0 appears as SUPPORTED_CACHE_KEY (yarn_berry_lock.rs#L89) and as YARN_BERRY_SUPPORTED_CACHE_KEY (redirect/mod.rs#L3289).
• cacheKey extraction exists as berry_metadata + berry_field and as berry_cache_key (split-based, #L3291-L3306). The latter's own comment says it is "mirroring the vendored backend's berry_field".
• The gate drivers are implemented twice (yarn_berry_lock.rs:1001-1103 vs preflight_yarn_berry_hosted, redirect/mod.rs:3355-3398), with per-mode codes and differently worded details. Only the .yarnrc.yml reader yarnrc_compression_level is shared, so Yarn berry vendored and hosted modes refuse compressionLevel: 0 # comment in .yarnrc.yml as a non-default compression level #370 was fixed once (Fix yarnrc compressionLevel comment refusal (#370) #508); hosted imports it from vendor/.
• The copies have drifted: vendored refuses a mixed-EOL root package.json and an unreadable .yarnrc.yml, while hosted checks only yarn.lock and treats an unreadable .yarnrc.yml as absent. E09 · fixed (Fix yarn berry project gates drifting between modes (#628, #629) #657)

Small helpers that have already drifted apart:

• JSON-pointer escape: byte-identical escape_json_pointer_token (npm_lock.rs:1022) and json_pointer_escape (upstream/npm.rs:136).
• JSON re-serialization, three strategies:
  • common::JsonLayout: keeps BOM, indent, EOL and trailer. Every package-lock writer (vendored, hosted, restore) and the npm and berry package.json writers use it since Fix JSON writers dropping CRLF/BOM/indent (#324, #351) #357.
  • common::serialize_json(indent): detected indent, always LF, no BOM. Vendored pnpm's root package.json no longer uses it: it is written through JsonLayout, so CRLF and BOM survive vendor and revert (Fix vendored pnpm package.json CRLF/BOM layout (#662) #810). E53 · fixed (Fix vendored pnpm package.json CRLF/BOM layout (#662) #810)
  • redirect::serialize_json: fixed 2-space, LF; now used only for NuGet packages.lock.json (hosted and restore).
• Wiring lines ↔ JSON: two identical encoders (yarn_classic_lock::lines_to_json, pnpm_lock::lines_value) and three decoders that have drifted: yarn's json_to_lines refuses a non-string element, while pnpm_lock::value_lines and recover::lines_of silently drop it. E18 · filed Share the npm-family wiring kinds and line-array codec between the vendored backends and lock_inventory::recover #835; wiring kinds + lines↔JSON codec
• sha512 SRI formatting is inlined at npm_pack.rs:27, bun_lock.rs:388 and vlt_preflight.rs:70. utils/digest.rs has no SRI helper.
• npm tarball URLs: the canonical registry_fetch::npm_tarball_url is re-implemented only at bun_lockb.rs:235, which writes format-1 lock semantics, not a fetch URL. vlt inventory uses the canonical helper, and the second NPM_REGISTRY constant is gone (Resolve vlt registry bases through one shared function (#562) #574). E02 · fixed (Resolve vlt registry bases through one shared function (#562) #574); partly not a defect
• vlt registry_base: one shared vlt_lock_text::registry_base serves lock inventory and hosted restore. It follows vlt 1.3.5 DepID hydration (scoped registries; ~~ as the npm alias); the two private copies were deleted (Resolve vlt registry bases through one shared function (#562) #574). E03 · fixed (Resolve vlt registry bases through one shared function (#562) #574)
• "Is a bun lock present": seven sites with three semantics. lstat (lock_inventory/bun.rs::bun_text_lock_present, which also feeds the GC in-use probe, and VEX DiscoverCtx::exists) treats a dangling bun.lock symlink as present; Path::exists (hosted/engine.rs::bun_lock_present, bun_lock.rs::binary_lock_drives, bun_workspace.rs, CLI repair.rs) and is_file (pkg_managers.rs) treat it as absent, like Bun itself. Proved on 045d7ec: with a dangling bun.lock beside a bun.lockb that Bun installs from, the inventory returns nothing while vendored and hosted write bun.lockb. E17 · in PR Fix open bun issues (#992, #861, #784, #764, #735, #635, #599, #578, #497, #443, #371) #1009
• name@spec splitting is written twice (yarn_classic_lock::split_pattern, bun_lock_text::split_name_spec). npm purl → (name, version) is parsed three more times outside utils/purl.rs.
• Wiring KIND_* constants are private to each backend but re-spelled as string literals in recover.rs (7 production sites); the state.rs copy is test-only. E18 · filed Share the npm-family wiring kinds and line-array codec between the vendored backends and lock_inventory::recover #835; wiring kinds + lines↔JSON codec
• Recursion depth: the legacy npm dependencies recursion is bounded at 64 in two places and unbounded in two others.
• Regex compilation inside per-dependency loops (redirect:3013, :3305).

CRLF policy is inconsistent for the same file family:

• vendored pnpm refuses CRLF, while hosted pnpm handles it;
• vendored yarn classic keeps CRLF, while hosted classic normalizes it by hand;
• berry uses utils::line_endings::LineEndings;
• npm_lock keeps the file's layout through JsonLayout (Fix JSON writers dropping CRLF/BOM/indent (#324, #351) #357), and so does vendored pnpm's package.json writer (Fix vendored pnpm package.json CRLF/BOM layout (#662) #810, E53 · fixed (Fix vendored pnpm package.json CRLF/BOM layout (#662) #810));
• vlt has its own strip_cr.

Five different answers to one question, and every one of them is a bug class (see the open-issue appendix). Across the whole crate there are five terminator rules (any-CRLF, first line, majority, CRLF-only re-expansion, refuse); on main the any-CRLF rule alone is written 14 times, in common::detect_eol, a byte-identical pypi_uv::newline_of and 12 inline copies, and gradle::newline_of uses the first-line rule under the same name. A probe on 045d7ec gives three answers for one mixed input. E16 · filed #814, #815; tracking #814, child 1 #815

4.5 Architecture defects

1. Silos with no trait (see 4.1).
2. Layering is inverted and cyclic.
   • 33 non-test files in patch/, vex/, formats/, hosted/ and crawlers/ import grammar from vendor::* backends.
   • On 045d7ec, formats/{cargo,composer,gem,pnpm}/mod.rs import the entry types from vendor::lock_inventory, formats/bun/mod.rs:11 imports vendor::bun_lock_text, all four formats/*/hosted.rs import patch::redirect, and formats/composer and formats/gem import crawlers. E20 · filed Tracking: move the pure lock codecs and neutral lock types into formats/ so formats imports nothing from vendor or redirect #833, Move LockfileEntry, LockIntegrity, SourceKind and http_url from vendor::lock_inventory into formats::entry #834; tracking Tracking: move the pure lock codecs and neutral lock types into formats/ so formats imports nothing from vendor or redirect #833, child 1 Move LockfileEntry, LockIntegrity, SourceKind and http_url from vendor::lock_inventory into formats::entry #834
   • vendor imports patch::redirect in about 12 places.
   • Several codecs are already pure and are simply in the wrong place. bun_lockb.rs, bun_lock_text.rs and vlt_lock_text.rs do no I/O and would pass the formats purity guard (formats/mod.rs:43-91) unchanged. E20 · filed Tracking: move the pure lock codecs and neutral lock types into formats/ so formats imports nothing from vendor or redirect #833, Move LockfileEntry, LockIntegrity, SourceKind and http_url from vendor::lock_inventory into formats::entry #834; tracking Tracking: move the pure lock codecs and neutral lock types into formats/ so formats imports nothing from vendor or redirect #833, child 1 Move LockfileEntry, LockIntegrity, SourceKind and http_url from vendor::lock_inventory into formats::entry #834
3. God files and long functions.
   • pnpm_lock.rs is 8,515 lines.
   • Longest drivers: vendor_yarn_berry 402 lines, vendor_bun 332, vendor_npm 325, vendor_pnpm_dialect 259 (both dialects; as of 9c43dfc), revert_pnpm_opts 234, rewrite_yarn_berry 272, plan_hosted 236, recover_lock_entry 221, bun_lockb::meta_hash 187.
4. Two lookup paths in pnpm v9. A linear scan and a memoized index (LockLines/LockIndex, INDEX_AFTER_PROBES = 2) coexist. That doubles the functions: lock_has_target_package vs …_in, check_rewritable_refs vs …_with.
5. Stale docs. berry_zip compiles only under cfg(any(test, feature = "test-fixtures")) (vendor/mod.rs:51), so cache-zip surgery does not ship; production gets the checksum from the patch service. Yet yarn_berry_lock.rs:15 and npm_flavor.rs:323-325 still say berry's checksum is "rebuilt by berry_zip".

4.6 Complexity vs value

• bun.lockb (binary).
  • The repo itself labels it "(binary, legacy)" (pkg_managers.rs:139-140); Bun ≥ 1.2 writes text bun.lock by default.
  • The codec supports binary format 1 ("before 0.1.7", 2022-era Bun) with promotion and demotion.
  • It recomputes Bun's 187-line meta hash.
  • It writes a private sktpnrm marker into an unused union slot of the user's lockfile (bun_lockb.rs:22-29).
  • About 5.8K lines including tests.
  • Recommend: refuse, with the remedy bun install --save-text-lockfile --frozen-lockfile --lockfile-only followed by deleting bun.lockb. If inventory/VEX must still read old repos, keep a read-only parser of about 300 lines.
• Vendored pnpm legacy (lockfile 5.4 = pnpm 7, 6.0 = pnpm 8).
  • Both pnpm majors are out of maintenance.
  • The legacy specifier is absolute, so --frozen-lockfile passes only at the original checkout path, which the module documents itself (pnpm_lock_legacy.rs:22-31). That undercuts the main point of vendoring.
  • About 5.1K lines including tests.
  • Recommend: refuse with "re-lock with pnpm ≥ 9", or at minimum fold it into the v9 backend as a PnpmDialect.
• Hosted pnpm ≤ 6 (shrinkwrap.yaml, lockfile 5.0-5.3, may_need_store_flag, unsupported_early_shrinkwrap). This covers 2017-2021 releases; refusing it saves a modest amount.
• vlt.
  • The most expensive format: 6.5K production + 6.1K inline-test + about 9.3K CLI test lines.
  • It supports pre-1.0 RC DepID encodings ("vlt ≤ 1.0.0-rc.14").
  • On top of that it has a directory-artifact backend (npm_dir.rs), a warm-store heal (vlt_heal.rs) and an artifact preflight.
  • Architecturally it is the best of the JS formats (one codec). The concern is size against a very small user base.
  • Recommend: drop the pre-1.0 RC encodings now. Gate further vlt investment on telemetry, and consider making vendored vlt refuse-only (about 3K production lines) while keeping hosted.
• Yarn PnP is already refused, and nodeLinker: pnpm costs nothing in production. No cuts are needed beyond fixing the stale berry_zip docs.

4.7 Target structure

formats/npm_lock/  { model (NpmLockDoc: nodes() with JSON pointers + JsonLayout), splice }
formats/pnpm/      { grammar (sole, CRLF-aware, byte ranges), keys, dialect {V54,V60,V9}, plan_hosted, plan_vendored }
formats/yarn/      { blocks (scan_blocks/LockBlock/replace_block), classic, berry (fields, locator, gates) }
formats/bun/       { text, binary (read-only stub or removed) }
formats/vlt/       { text, registry (one registry_base) }
formats/js_common  { name@spec split, SRI, tarball_url, LineEndings, wiring KINDS }

Each format exposes parse(&[u8]) -> Model, entries(), wired_refs(), plan_hosted(deps), plan_vendored(ctx) and restore(record). Behind them sits one trait NpmLockBackend { read_project, preflight, plan, revert_record } with one generic vendor/revert driver. One flavor decision table, written over ProjectView, would be used by vendored mode, hosted mode and the in-memory engine.

#	Change	Prod LOC saved	Test LOC	Risk
A	bun.lockb → refuse (keep a ~300-line read-only parser)	~2.4K	~3K	Med (unmigrated Bun repos)
B	Drop vendored pnpm-legacy (or merge it as a dialect)	1.85K (merge: ~0.8K)	3.2K (~1K)	Low-Med
C	Generic vendor driver + NpmLockBackend trait	0.8-1.0K	—	Med
D	Hosted yarn writers/restorers on LockBlock; one berry gate set	0.3-0.4K	some	Low-Med
E	One package-lock walk (JsonLayout half done by #357) E07 · in PR #1008	~0.3K	—	Low
F	One flavor decision table	~0.15K	—	Low
G	pnpm: retire lines.rs + the CRLF refusal, one resolution: emitter, one index path	0.3-0.5K	—	Med
H	vlt: drop pre-1.0 encodings, unify registry_base, decide the vendored-dir backend on data	0.2-3K	up to ~6K	Low → High
I	Helper dedup (SRI, pointer escape, tarball URL, KINDS, lines↔JSON, bun presence, purl)	~0.15K	—	Low; fixes real divergences
J	Move pure codecs into formats/ (removes the vendor↔redirect/vex cycles)	~0	—	Low

Combined (A, B-drop, C-G, I): about 6-7K production lines and 8-10K test lines, before any vlt decision.

New findings since the review

• Hosted yarn berry rewrites (majority-normalizes) a mixed-line-ending root package.json that vendored mode refuses with vendor_yarn_berry_mixed_line_endings; the gates live once per mode. E09 · fixed (Fix yarn berry project gates drifting between modes (#628, #629) #657)
• Vendored pnpm wrote the root package.json with serialize_json instead of JsonLayout, losing CRLF and refusing a BOM; it now uses JsonLayout like npm and berry (Fix vendored pnpm package.json CRLF/BOM layout (#662) #810). E53 · fixed (Fix vendored pnpm package.json CRLF/BOM layout (#662) #810)
• E16 · filed Tracking: classify line endings in one place instead of five drifting rules #814, Pick the line terminator for spliced lines through one line_endings::terminator #815; tracking Tracking: classify line endings in one place instead of five drifting rules #814, child 1 Pick the line terminator for spliced lines through one line_endings::terminator #815: the "any \r\n → CRLF" terminator rule is written 14 times, mostly outside the npm family (gem, Maven, composer and Cargo restore, Pipenv, .npmrc, uv, PEP 723 scripts), and hosted Cargo refuses a mixed Cargo.lock that upstream restore re-expands wholesale to CRLF; folded into the line-ending tracking issue.
• E76 · in PR Move all yarn.lock parsing into formats/yarn and stop pinning non-registry copies #1057 October 7: hosted yarn classic replaces file:, URL and codeload copies with the Socket artifact, and rollback corrupts the key (PR Move all yarn.lock parsing into formats/yarn and stop pinning non-registry copies #1057 adds one copy-source classifier).
• E78 · in PR Fix 15 open pnpm issues across hosted, vendored and agent modes #1007 (pnpm workstream) October 7: pnpm readers and writers ignore ---, so a two-document pnpm lock gets the wrong document edited (Vendored pnpm 12 with packageManager set: the two-document pnpm-lock.yaml makes vendor refuse, and vendor --revert, rollback and the hosted takeover half-revert the project and break frozen installs #466, pnpm workstream).
• E64 · partly fixed (Fix pnpm lock/workspace readers missing a BOM (#903, #904, #905) #909); pnpm readers skip the BOM, the shared helper remains (pnpm lock and workspace readers don't skip a leading BOM, because BOM handling has no shared helper (4 named copies, ~50 inline strips) #905): BOM handling has no shared helper (4 named strip_bom copies, about 50 inline strips that disagree on one vs. many BOMs). formats::pnpm's three lockfileVersion readers and workspace::top_level_key never skip it, so one BOM pnpm lock reads as having entries, as not a pnpm lock (VEX), as unversioned (hosted trust gate) and as unsupported (vendored router); executed twice. Symptoms Hosted pnpm scan skips the trustLockfile: true auto-config when pnpm-lock.yaml starts with a UTF-8 BOM, so pnpm 11/12 frozen installs fail with ERR_PNPM_TARBALL_URL_MISMATCH after a successful scan #903, pnpm-workspace.yaml with a UTF-8 BOM: hosted and vendored miss the first top-level key and append a duplicate trustLockfile / overrides, so every pnpm install fails with "duplicate mapping key" after a successful scan #904 and Hosted and vendored NuGet reject a packages.lock.json with a UTF-8 BOM that dotnet restores fine: hosted skips the redirect and exits 0 success, vendored fails apply_failed #623.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

[agent] Part 5 of 9 of the living socket-patch architecture document. The summary and ranked recommendations are in the top post. Originally written against 2463257; the routines update this part as the code changes.

Part 5: Vendored mode and the non-JS backends

Last checked against main @ 431b818 on 2026-10-07 by the October 7 reconciliation (5.5 zip inflate and 5.7 JVM scope re-checked). Earlier: db83f01 by audit-ecosystems (5.6 registry_fetch.rs contents and importers re-checked at db83f01; 5.3 revert envelope, finish steps and keep policies re-checked at 9c43dfc; 5.7 JVM backends and the single-module routing re-checked at 9c43dfc; 5.2 ecosystem enumeration sites and dispatch re-checked at 9c43dfc; the vendored-reference scan's file list re-checked at 9c43dfc; 5.4 Poetry/PDM/Pipenv backend skeleton and Poetry forward splicers re-checked at 9c43dfc; 5.2 dead force/sources parameters re-checked at 9c43dfc; per-backend service-copy and cleanup copies re-checked at 9c43dfc; 5.4 NuGet, Poetry/PDM and Gem re-checked at 4646693; as of 045d7ec: 5.4 Python, Cargo, Maven XML, Gem, Go and CRLF helpers; 5.6 scaffolding; the vendored-reference scan behind repair and the orphan sweeps). Owner: audit-ecosystems.

Scope: vendor/ framework (mod, common, state, verify, registry_fetch, service_fetch, prestage, reuse, redownload, ledger_snapshots, parse_memo, path, source, toml_surgery, lock_inventory); backends for cargo, gem, pypi (×10 files), golang, composer, nuget, maven and jvm/; related utils/ parsers; and the CLI vendor.rs + vendored_backend/.

5.1 Size

Area	Prod	Inline tests
vendor/ excluding the npm family (framework + 7 backends + lock_inventory)	37,603	58,095
Related utils (python_lock, poetry_lock, pdm_lock, hatch, requirements, pipenv, cargo_workspace, group_commit, durability, fs, line_endings, …)	6,972	5,735
CLI commands/vendor.rs + vendored_backend/*	~4,500	2,607

Production lines per backend:

Backend	Prod
JVM (maven_repo 1,845 + jvm/* 5,540 + a 66-line .gradle script)	7,451
PyPI (10 files; plus lock_inventory/pypi 663 and ~3,390 shared utils)	7,270
Cargo	4,351
Gem	2,389
Go	2,072
NuGet	1,406
Composer	1,393

Framework files: registry_fetch 1,560 (at db83f01), mod 838, common 831, state 824, verify 823, redownload 462, prestage 425, path 421, service_fetch 386, ledger_snapshots 352, reuse 349, toml_surgery 292, parse_memo 147.

5.2 No backend trait

The only traits under vendor/ are a private EditLines and a test-helper trait; backends are uniform by naming convention only. Each non-npm backend defines:

• struct <Eco>Prelude + async fn <eco>_prelude (cargo.rs:425/439, gem.rs:121/139, golang.rs:53/66, composer_lock.rs:99/121, nuget_feed.rs:158/178, maven_repo.rs:91/114, pypi.rs:674/690);
• service_preflight, vendor_*, revert_* and revert_*_opts.

The signatures are close but not identical:

• nuget and maven take &Path where the others take impl Into<PackageSource>;
• pypi takes two extra cache arguments;
• every backend now discards sources and force at its acquisition sink (10 _sources/_force parameters, since acquisition went service-only), so vendor --force only bypasses the CLI variant probe, although its help and CLI_CONTRACT.md still promise missing-file tolerance. E65 · filed vendor --force documents a missing-file tolerance and a mismatch warning that no vendored backend implements #923

The CLI papers over the differences with two macros, vend! and vend_installed! (cli/commands/vendor.rs:171-210).

16 production sites enumerate the ecosystems (line numbers re-checked at 9c43dfc), and each is a place a new ecosystem must be added. Target: one core VendorBackend enum that every site asks, starting with the revert and in-use dispatch. E21 · filed #959, #960; tracking #959 (enum dispatch first), child 1 #960 (revert/in-use)

1. vendor/path.rs:43 ECOSYSTEM_DIRS
2. vendor/path.rs:281-383 leaf_to_purl (8 arms)
3. vendor/mod.rs:779-800 service_preflight (7 arms)
4. vendor/npm_flavor.rs:516 lock_text_refusals
5. vendor/mod.rs:392-417 harvest suffix branches
6. verify.rs:526 artifact_is_file_shaped
7. redownload.rs:195
8. prestage.rs:352 PRESTAGED_ECOSYSTEMS
9. lock_inventory/mod.rs:252 (lookup, 6 types)
10. lock_inventory/recover.rs:41
11. ledger_snapshots.rs:56 WHOLE_FILE_KINDS
12. state.rs:502 carry_forward_wiring
13. CLI vendor.rs:155 SERVICE_ECOSYSTEMS
14. CLI vendor.rs:212 vendor dispatch
15. CLI vendor.rs:254 revert dispatch
16. CLI vendor.rs:286 in-use dispatch

Inside backends there is a second dispatch layer: PypiFlavor has 7 variants, matched at pypi.rs:727, 744, 1123 and again as strings at :1545; NpmLockFlavor does the same for npm.

Ecosystem identity is inconsistent. The legacy single-POM Maven entry is "maven", but the reactor/Gradle backend rewrites it to "jvm" (maven_repo.rs:1089). That forces "maven" | "jvm" aliases at CLI vendor.rs:249 and four times in redownload.rs.

The CLI reaches into backend internals: 54 distinct vendor::<mod>::<item> paths are used from 25 CLI files. Examples:

• vendor.rs calls jvm::apply::{is_jvm_entry, check_entry, upstream_unverified, sweep_replaced_tree};
• repair.rs calls cargo::migrate_legacy_wiring and bun binary helpers.

These are hooks a trait should expose.

The orchestrator vendor_records_reusing (CLI vendor.rs:1971) is about 970 lines. It mixes:

• the vendor loop;
• hosted→vendored takeover;
• berry and vlt special cases;
• prefetch and prestage;
• group commit;
• a composer special case.

5.3 The ledger, and nine ways to undo a change

Each VendorEntry (state.rs:215-282) stores:

• artifact {path, sha256, size, platform_locked, file_inventory};
• wiring: Vec<WiringRecord {file, kind, action, key, original: Value, new: Value}>;
• per-flavor typed fields (lock: CargoLockOriginal, uv, pnpm, poetry, pdm, pipenv, took_over_go_patches, flavor);
• detached, plus an embedded patch record.

original/new are untyped JSON whose shape depends on kind, and there are more than 45 distinct kind strings.

"Record the original and restore it" is the right idea, but it is implemented about nine different ways: E24 · filed #989, #990; tracking #989, child 1 #990 (finish step ×12, four keep policies)

Mechanism	Used by
Regenerated by ownership rule; recorded original ignored	cargo Cargo.toml, go drop_replace_entry
Typed side field	Cargo.lock from entry.lock. The same data is also written as a cargo_lock_entry record that nothing reads.
Text-fragment splice with drift detection (common.rs:693-810, the only shared helper)	poetry, pdm
JSON value replace + reserialize	composer; pipenv (canonical rewrite of the whole lock)
Line arrays	gem; requirements, which has its own drift codes, vendor_revert_line_drifted, instead of the vendor_lock_entry_drifted contract
Whole-file snapshot, restored if live == new	maven legacy pom, nuget config, pylock / PEP 723 / hatch
Three-way structural TOML merge	pypi_lock.rs:414-569
Pure plan/unplan with shared-fragment refcounting	JVM (jvm/mod.rs, jvm/apply.rs), the best design in the slice

The envelope around those mechanisms is copied too (re-checked at 9c43dfc):

• The finish step (dry-run return → drift-keep → --preserve-state return → remove_tree_and_prune) is written 12 times, with four keep policies: unconditional drift-keep (gem, npm, pnpm, bun ×2), keep while a live file still names the uuid dir (composer, maven legacy, nuget), a "lock still mentions the uuid" refusal (yarn classic and berry), and pypi's drift-or-residual keep with a warning-only removal failure. Sharing it is Finish every vendored revert through one shared helper with an explicit keep policy instead of 12 copied finish blocks #990, child 1 of E24 · filed Tracking: revert every vendored backend through one record-revert engine instead of nine hand-written mechanisms #989, Finish every vendored revert through one shared helper with an explicit keep policy instead of 12 copied finish blocks #990; tracking Tracking: revert every vendored backend through one record-revert engine instead of nine hand-written mechanisms #989, child 1 Finish every vendored revert through one shared helper with an explicit keep policy instead of 12 copied finish blocks #990 (finish step ×12, four keep policies).
• The record loop (reverse wiring walk, unknown-kind warning, Ok(false) → vendor_lock_entry_drifted) is copied in composer, gem, maven legacy and nuget. Only poetry/pdm can revert coupled records all-or-nothing (revert_lock_fragment_splice_atomic); gem cannot, so a drifted Gemfile line still lets the lock be restored (E68 · filed Vendored gem revert restores Gemfile.lock but leaves the Gemfile path: line when that line carries a trailing comment, and no re-run can finish it #988).
• Forward and revert recognize "our" wiring by different predicates in gem (E68 · filed Vendored gem revert restores Gemfile.lock but leaves the Gemfile path: line when that line carries a trailing comment, and no re-run can finish it #988) and requirements.txt (Vendored requirements.txt can't be reverted once the user touches the # socket-patch vendor: comment: vendor --revert drift-keeps forever (exit 0), and the suggested "re-vendor" remedy is a no-op or adds a duplicate line #977).

Revert/restore/unwind code in the non-npm backends totals about 3,540 lines: gem 422, nuget 305, pypi 291, pypi_lock 254, uv 231, cargo 220, composer 205, and more.

Back-compat costs:

• Whole-file snapshots made ledgers grow by tens of MB, so schema v2 was added to compensate: ledger_snapshots.rs, 352 lines of ops-delta encoding. It is a workaround for the snapshot design.
• The cargo pre-v5 .cargo/config migration and its legacy code paths: 29 "legacy" mentions in cargo.rs.
• Committed ledgers in users' repositories make every kind string a permanent API. The legacy-ledger fixtures (tests/fixtures/legacy-ledgers/<9 ecosystems>) are the right guardrail.

5.4 Duplication

Format parsers live in three homes (formats/, utils/, vendor/), and formats/ has no pypi, golang or package-lock model. 50 non-vendor files import crate::vendor::*: 48 references to vendor::lock_inventory, 15 to registry_fetch and 9 to go_mod_edit. vendor/pypi.rs:87-230 holds hosted-mode wheel-metadata code that is used by hosted/memory/discover.rs and CLI scan/hosted.rs.

XML: eight hand-rolled scanners and no XML crate.

• <!-- handling is implemented independently in 8 files, including two strippers inside maven_repo.rs.
• There are four attribute extractors with three different tokenization rules:
  • nuget_feed.rs:1094 attr_value matches any substring, with no word boundary;
  • redirect/upstream/nuget.rs:39 uses a regex;
  • jvm/gradle.rs:1538 checks for preceding whitespace;
  • formats/nuget/mod.rs:41 does a real tag parse.
• The vendored NuGet writer (nuget_feed.rs) never uses the shared reader formats::nuget::parse_config, so its reader and writer can disagree about what a file contains. The hosted splicer now uses it (Unify hosted NuGet routing and XML splice anchors #597). E10 · filed Tracking: read and edit pom.xml through one element scanner in formats::maven #715, Vendored Maven refuses a single-module EAR pom as a multi-module aggregator because two declares_modules disagree #716, Locate hosted Maven pom edits and their upstream restore through the formats::maven element scanner #717, Read and splice nuget.config through formats::nuget in hosted, vendored and restore #594; NuGet hosted reader fixed (Unify hosted NuGet routing and XML splice anchors #597)
• pom.xml alone has seven scanners (checked on 045d7ec): formats::maven::parse_pom (VEX, restore gate); the hosted rewriter's raw regex (MAVEN_DEPENDENCY_BLOCK_RE, insert_maven_*), which upstream restore reuses and which masks nothing; vendored maven_repo.rs (comment_spans/profiles_spans, plus a second declares_modules); the reactor's mask + Doc tree and, in the same file, scan_pom_project (a depscan port); and the crawler's and vex/product.rs's own readers. None of the three writers (hosted, restore, vendored single-pom) locates elements through a reader. Target: one masked element tree in formats::maven that readers and splicing writers both query. E10 · filed Tracking: read and edit pom.xml through one element scanner in formats::maven #715, Vendored Maven refuses a single-module EAR pom as a multi-module aggregator because two declares_modules disagree #716, Locate hosted Maven pom edits and their upstream restore through the formats::maven element scanner #717, Read and splice nuget.config through formats::nuget in hosted, vendored and restore #594; NuGet hosted reader fixed (Unify hosted NuGet routing and XML splice anchors #597)
• The Maven share of the open backlog is mostly this: Hosted Maven rewriter edits commented-out, plugin and profile markup, so builds either stay unpatched or break #259 "edits commented-out, plugin and profile markup", Maven pom rewrites add a second <repositories> or <dependencyManagement> section when the existing one is self-closed or has a comment before <dependencies>, so Maven refuses the pom #342 "adds a second section when the existing one is self-closed or has a comment", Hosted Maven adds a dependencyManagement pin that the direct literal overrides when the dependency's groupId/artifactId is a ${property} or <exclusions> come first, so the build stays unpatched while scan reports redirected and VEX attests not_affected #683 (<exclusions> first) and E10 · filed Tracking: read and edit pom.xml through one element scanner in formats::maven #715, Vendored Maven refuses a single-module EAR pom as a multi-module aggregator because two declares_modules disagree #716, Locate hosted Maven pom edits and their upstream restore through the formats::maven element scanner #717, Read and splice nuget.config through formats::nuget in hosted, vendored and restore #594; NuGet hosted reader fixed (Unify hosted NuGet routing and XML splice anchors #597).

Python:

• utils/poetry_lock.rs and utils/pdm_lock.rs now share one fragment-splice engine, utils/lock_fragments.rs (344 lines: the parse holder, pairing, splicing and one majority_terminator line-ending rule). Only the per-format fragment ownership and refusals stay in each file (Fix Poetry/PDM lock splice drift (#694, #695) #703). E13 · fixed (Fix Poetry/PDM lock splice drift (#694, #695) #703) E54 · fixed (Fix Poetry/PDM lock splice drift (#694, #695) #703)

• vendor/pypi_{poetry,pdm,pipenv}.rs repeat one skeleton:

  • load_*_project
  • classify_dependency
  • check_target_guards (missing / forked / ours-in-sync / ours-stale / user-authored)
  • wire_*
  • revert_*

  The wire and revert envelope around each format edit is identical in all three, verified on 9c43dfc: symlink refusal → guards → a defensive InSync refusal → edit → ensure_unchanged → memo invalidate → mode-preserving write. Each also has its own {Fresh, InSync} enum. Target: one shared envelope with flavor-derived error codes. E23 · filed Share the single-lock wire and revert envelope across the Poetry, PDM and Pipenv vendored backends #937; shared wire/revert envelope + one LockTarget (no drift proven)

• Vendored Poetry has two forward splicers. Legacy and CRLF locks go through the shared utils::poetry_lock engine; LF 2.x locks go through a private toml_surgery line scanner (rewrite_target_package_unit). The scanner writes a different files shape and skips the engine's wheel-name and lowercase-digest gates (executed twice). E66 · filed Vendored Poetry wires a 2.x lock through two different splicers depending on its line endings #936

• Pipfile.lock is read through one shared parser but written two ways: vendored reserializes canonically, hosted splices spans.

• Hosted-URL recognition for Pipenv is shared: hosted owned_url and the vendored Pipenv guard both ask lock_inventory::pypi::hosted_pypi_reference, which applies hosted_patch_uuid's origin allowlist to hosted_artifact_url's tail grammar; the vendored guard gets the run's --patch-server-url origin (Recognize hosted Pipenv references through one shared grammar (#563) #572). E04 · partly fixed (Recognize hosted Pipenv references through one shared grammar (#563) #572); three recognizers remain (re-checked 431b818)

Cargo:

• Cargo.toml [package] is read in five places. Two are line scanners: crawlers/cargo_crawler.rs#L12-L113 ("no TOML crate dependency") and vex/product.rs scan_toml_section. Three are ad hoc toml_edit lookups: cargo_tag::version_literal ([package] or legacy [project]; it now finds the literal's span through toml_edit and splices only those bytes), cargo.rs path_crate_version ([package] only) and declared_cargo_minor (Vendored cargo warns cargo_multi_version_old_cargo ("declares no rust-version") when the root package inherits rust-version from [workspace.package] #651).
  • They have drifted, proven by execution: a BOM manifest is invisible to the crawler but read by VEX and cargo_tag; [project] and dotted keys are read only by cargo_tag; [package] junk (invalid TOML) is accepted only by the crawler. E15 · filed Read Cargo.toml package name and version through one shared toml_edit reader #693, Hosted cargo redirect refuses a dependency whose inline table has a multi-line features array, because it plans Cargo.toml pins with a line scanner #757
  • Hosted mode plans the dependency pin itself with a line scanner (plan_cargo_toml, six regexes), then re-checks it with a second, toml_edit classifier (validate_cargo_toml_pins). CargoRegistryPins, a #[cfg(test)] oracle and upstream restore's unpin_line are three more line-level readers of the same declarations. Vendored edits only through toml_edit. The scanner refuses an inline table whose features array spans lines, which is valid TOML and accepted by cargo, so hosted skips a crate that vendors fine. E15 · filed Read Cargo.toml package name and version through one shared toml_edit reader #693, Hosted cargo redirect refuses a dependency whose inline table has a multi-line features array, because it plans Cargo.toml pins with a line scanner #757

Gem: vendor/gem.rs imports three token helpers from formats::gem and keeps its own section model: section_span / section_end for DEPENDENCIES and CHECKSUMS, plus gem_section_spans / record_gem_section, added by #805. With formats::gem::parse and hosted's GemLockSection, that makes three section models and three DEPENDENCIES-name parsers; the name rules agree on Bundler-written entries. E19 · filed #780; gem models open, go.mod module reader fixed (#870)

• The models had drifted: vendored edit_lock looked only in the first GEM section, so a gem from a later source was refused. It now searches every GEM section, and refuses a spec listed in two (Fix vendored gem lookup beyond the first GEM section (#779) #805). E59 · fixed (Fix vendored gem lookup beyond the first GEM section (#779) #805)

Go: go_mod_edit.rs is properly shared (VEX --product now included) but lives under vendor/. Since #870 the go.mod module directive has one reader, go_mod_edit::module_path, built on the same directive walker as require and replace (block form included); the crawler's dead parse_go_mod_module is gone. E19 · filed #780; gem models open, go.mod module reader fixed (#870)

Small helpers:

• CRLF: four policies for the same "toml_edit emits LF" problem:

  • line_endings refuses mixed files;
  • python_lock converts CRLF-only files and leaves mixed files as LF;
  • utils/lock_fragments (Poetry and PDM) re-terminates spliced lines with majority_terminator (Fix Poetry/PDM lock splice drift (#694, #695) #703) E54 · fixed (Fix Poetry/PDM lock splice drift (#694, #695) #703);
  • cargo_manifest aligns lines with an LCS diff.

  There are also ad-hoc helpers in four more files: on main, common::detect_eol, pypi_uv::newline_of and gradle::newline_of (a different, first-line rule under the same name), plus inline any-CRLF copies in maven_reactor.rs (×2) and pypi_pipenv.rs. One classifier is the target. E16 · filed Tracking: classify line endings in one place instead of five drifting rules #814, Pick the line terminator for spliced lines through one line_endings::terminator #815; tracking Tracking: classify line endings in one place instead of five drifting rules #814, child 1 Pick the line terminator for spliced lines through one line_endings::terminator #815

• Per-backend copies:

  • cleanup_failed_stage is byte-identical in cargo and gem, and one line different in composer; golang has its own cleanup_failed_service_stage.
  • <eco>_service_copy (fetch → settle → claim_prestaged-or-extract → afterHash check → swap) is repeated for cargo, composer, gem and golang (go_service_redirect): about 500 lines, with the layout-mismatch message spelled four times. No drift proven yet. E25 · filed Stage prebuilt service archives through one shared helper instead of four per-backend service-copy pipelines #906

• Process-global memo caches: 22 static …: ParseMemo across 16 files. They exist because backends are called once per package and would otherwise re-parse the same lock each time.

• Atomic writes: centralized in utils/fs.rs, but in seven variants.

5.5 Security: zip inflate on committed artifacts (fixed, #587)

zip_bytes_match_after_hashes now streams each member through the Git SHA-256 reader with an 8 KiB buffer and checks the declared length against the bytes read; it no longer inflates members into a Vec sized by the archive's own header (#587). The maintainer ruled that this data is trusted not to be too big, so the fix streams instead of capping. C01 · fixed (#587); streams members, no cap per maintainer Agent-mode jar verification still buffers each member (C51).

It runs on:

• committed, tamperable artifacts (the NuGet hot path, nuget_feed.rs:266; the committed Maven jar, maven_repo.rs:736 and :1464);
• service archives (service_fetch.rs:312).

The codebase still has three different archive size caps on downloads: 512 MiB (common.rs), 256 MiB (mod.rs) and 128 MiB (registry_fetch.rs).

5.6 Scaffolding left over from the removed local-build path

v5 removed local artifact building, but the scaffolding remains:

• VendorSource has one variant, and may_use_service()/requires_service() always return true (mod.rs:212-237). Deleting the predicates is Delete PatchSources::mem_blobs, the single-variant VendorSource predicates, the redirect-state group-commit capture and the group_commit switch-off oracle #746 (audit-core C23).
• PackageSource has one variant, but 53 production references across 19 files take impl Into<PackageSource> only to call .path(). One of them is redirect/golang_local.rs, which adds a redirect → vendor import. E28 · filed Replace the single-variant vendor PackageSource with &Path and delete the scaffolding it props up #800, Delete PatchSources::mem_blobs, the single-variant VendorSource predicates, the redirect-state group-commit capture and the group_commit switch-off oracle #746
• SERVICE_ECOSYSTEMS lists every name ecosystem_dir_for_purl can return, so its vendor_service_unsupported_ecosystem refusal can never fire. The code's only test asserts its absence. E28 · filed Replace the single-variant vendor PackageSource with &Path and delete the scaffolding it props up #800, Delete PatchSources::mem_blobs, the single-variant VendorSource predicates, the redirect-state group-commit capture and the group_commit switch-off oracle #746
• ServicePolicy::new(_cfg) ignores its config, and miss() does let _ = (warnings, code).
• vend_installed! exists for a "registry-fetch rung" whose function no longer exists. Its debug_assert! matches the only PackageSource variant, so it always holds. E28 · filed Replace the single-variant vendor PackageSource with &Path and delete the scaffolding it props up #800, Delete PatchSources::mem_blobs, the single-variant VendorSource predicates, the redirect-state group-commit capture and the group_commit switch-off oracle #746
• PatchSources::mem_blobs (patch/apply.rs:96) is None at every production construction site.
• Stale docs:
  • args.rs:59 still lists build as valid;
  • lock_inventory/mod.rs:9-12 says vendor fetches from the registry;
  • gem.rs refers to a FallBack variant that does not exist.
• registry_fetch.rs (3,048 lines at db83f01: 1,560 production, up from 1,535) is really archive extraction, the Go module-zip walk and h1 hash, integrity checks, and the registry bases plus HTTP client for hosted restore. It is misnamed and misplaced: agent mode (patch/jvm_jar.rs), hosted restore (redirect/upstream/), hosted/ and api/ all import it from vendor/. E29 · filed Move the bounded archive extractors out of vendor::registry_fetch into utils::archive #1012; archive + Go module zip move; integrity (after Move LockfileEntry, LockIntegrity, SourceKind and http_url from vendor::lock_inventory into formats::entry #834) and registry bases (after Bound registry downloads by ApiTimeouts instead of a 60 s total deadline (#872) #876) remain
• --vendor-source accepts only service or its alias auto. It is a user-facing flag with exactly one behavior.

Value: negative. Delete it (about 250 lines, near-zero risk).

5.7 Complexity vs value

• JVM (7,451 production lines at the snapshot; maven_repo.rs alone is 5,504 lines at 1c6c509): two backends for one ecosystem. This section predates sbt and scala-cli (sbt, Mill and scala-cli support in agent, hosted and vendored modes #690): there are now five planners (Maven reactor, Gradle, sbt, scala-cli, Coursier tree) and four artifact roots, and the layout is spelled in ~13 places (PR Route JVM layout through one module and fix three JVM scope bugs #1032 adds one vendor::jvm::layout). E77 · in PR Route JVM layout through one module and fix three JVM scope bugs #1032

  • The legacy single-POM backend (maven_repo.rs) uses whole-file pom snapshots and wires the unsuffixed GAV through a trailing <repository>, so a warm ~/.m2, an earlier repository or mirrorOf * can shadow it (Vendored Maven silently resolves the unpatched jar when an earlier <repository> or a mirrorOf * mirror serves the same GAV, and VEX still attests #263, Same-GAV Maven patches are shadowed when a build plugin depends on the same GAV in a reactor build #274, Vendored Maven 4 reactor with implicit subprojects (model 4.1.0, no <subprojects>) is wired as a single POM, so a warm ~/.m2 builds the unpatched jar while vex attests not_affected #622; closed for new vendors by Decide: vendor single-module Maven poms through the suffixed-version jvm planner and retire the same-GAV <repository> wiring #973, which retires the always-on vendor_maven_local_cache_shadow warning).
  • The v5 jvm/* handles reactor and Gradle builds and is the best-designed code in vendored mode: pure planners over a ReadFn that return file writes plus fragment records, with an order-independent unplan. Its orchestrator, though (vendor_maven_jvm, acquisition, metadata, materialisation; about 1,170 raw lines), lives inside maven_repo.rs, and redownload.rs, agent-mode jvm_jar.rs and VEX import from there.
  • The planner already plans a single-module pom: Shape::Mixed runs maven_reactor::plan on one. Only Detected::shape mapping a lone single-module pom to Shape::Other keeps it on the legacy path. On 9c43dfc, a lone CRLF single-module pom planned with no warnings, re-planned to nothing and unplanned byte for byte (executed twice).
  • It uses three artifact roots (.socket/vendor/maven/<uuid>, .socket/vendor/maven2, .socket/vendor/gradle) plus .socket/gradle/ and gradle-index.tsv. None of them follows the <eco>/<uuid> convention that path.rs and the orphan sweep rely on.
  • --maven-config auto|none is a global CLI flag consumed by one function.
  • Decided (Decide: vendor single-module Maven poms through the suffixed-version jvm planner and retire the same-GAV <repository> wiring #973): one backend. A lone single-module pom is planned as a reactor of one (Shape::MavenReactor; no new Shape::Single variant is needed). The legacy forward path (vendor_maven_single, maven_prelude, build_repo_edit, the second declares_modules, local_cache_shadow_warning, legacy_mixed_root) is deleted, and maven_pom_repository entries are revert-only. A root that still holds one is refused (legacy_maven_root) until vendor --revert; there is no automatic migration. Still open: dropping the "jvm" alias (Tracking: vendor every Maven shape through the jvm planner and retire the legacy single-pom backend #971 child 4) and the --maven-config flag scope (Tracking: vendor every Maven shape through the jvm planner and retire the legacy single-pom backend #971 child 5). E26 · in PR Vendor single-module Maven poms through the suffixed jvm planner and retire the legacy <repository> backend (#973) #1036; decided Decide: vendor single-module Maven poms through the suffixed-version jvm planner and retire the same-GAV <repository> wiring #973: one Maven backend, single poms as a reactor of one, legacy roots refused until vendor --revert

• PyPI's seven flavors (uv 1,775; requirements 830; pylock 678; pipenv 657; pdm 496; poetry 477; hatch 303; router 1,928 production lines).

  • Each flavor is needed for correctness, but they share no trait.
  • Poetry, pdm and pipenv together are ~1,600 production lines in vendor plus ~1,150 in utils, for what is one pattern: a lock-only per-package splice with guards.

• Performance and durability machinery (~3K production lines):

  • group_commit.rs (1,059) intercepts the utils::fs writers globally per root, renders values lazily via Any, and does three-way hand-edit reconciliation in recover;
  • durability.rs (315);
  • prestage.rs (425);
  • api/vendor_prefetch.rs (694);
  • parse_memo (147) plus its 22 statics;
  • ledger_snapshots (352).

  Almost all of it compensates for the per-package call model: each call re-reads, re-parses and durably re-writes the same lockfile and ledger. A batched planner API (the JVM pattern) removes the root cause.

  Writes that bypass utils::fs (for example blob_fetcher.rs:471) are silently not captured by group commit. Group commit still journals redirect-state.json, which has no production writer.

• Cargo tags (cargo_tag.rs, 259 lines): small and justified, because they make Cargo.lock self-describing. Keep them.

• Cargo legacy .cargo/config migration (~200 lines in cargo.rs plus part of cargo_config.rs): sunset it after a deprecation window.

5.8 Target design

trait VendorBackend {                       // one impl per ecosystem, listed in a static REGISTRY
    const ECO: &str;
    fn artifact_shape(&self) -> Shape;
    fn leaf_to_purl(..);
    fn wiring_files(&self, v: &ProjectView) -> Vec<String>;
    fn preflight(&self, v, pkg) -> Result<Option<PlannedDownload>, Refusal>; // = lock_text_refusal + service_preflight
    fn plan(&self, v: &ProjectView, pkgs: &[Pkg]) -> Result<Plan, Refusal>;  // pure, BATCHED
    fn materialize(&self, archive, stage) -> Result<(), String>;             // extract / tag / afterHash check
    fn in_use(&self, v, e) -> Option<bool>;
    fn recover(&self, e) -> Option<LockfileEntry>;
}
struct Plan { writes: Vec<FileWrite>, records: Vec<SpliceRecord { file, anchor, original: String, new: String }> }

The engine owns:

• reading and the ProjectView;
• one atomic multi-file commit;
• the ledger;
• stage/swap/cleanup;
• one generic revert: the existing common.rs:722 splice algorithm, generalized. It splices new back to original, converges silently when original is already present, and warns on drift.

Old kinds are translated into SpliceRecords when the ledger loads, so legacy ledgers keep reverting byte for byte. The JVM JvmPlan/JvmUnplan design is the in-repo precedent.

Estimated saving: about 6–8K production lines of the ~44K in this slice (15–18%), and more in tests. Per-backend conformance tests collapse into one suite; for example, service_preflight_names_exactly_the_*_that_ask_for_a_grant is copied into seven files, though its body now shares test_support::plan_matches_grants, so only the fixture remains per backend.

Risks:

• committed ledgers are a permanent API, so the legacy-kind adapters must stay;
• byte-exact lock output per package manager must not change. The legacy-ledgers fixtures and the e2e_vendor_*_build suites are the guardrail;
• batching changes the time-of-check/time-of-use posture that parse_memo deliberately preserves.

New findings since the review

• E74 · in PR Decide vendored-entry liveness through one discovery verdict #1050 October 7: "is this vendored entry still in use" has four answers; entries of six ecosystems are never pruned and scan resurrects them (PR Decide vendored-entry liveness through one discovery verdict #1050).
• E71 · in PR Replace a superseded patch generation's wiring on re-pin and remove #1035; Vendored npm re-scan exits 1 ("Failed to vendor", "1 failed") on every run while a superseding patch's artifact is pending_build / build_failed / not_found, although the vendored older patch is intact; hosted skips the same upgrade with exit 0 #954 in Fix open npm issues #1008, uv projects never pick up a superseding patch: hosted re-scan lists the upgrade in updates[] but refuses its own earlier [tool.uv.sources] pin (exit 0, still on the old uuid), and vendored re-scan fails pypi_uv_source_already_exists #742/Hatch never picks up a superseding patch: re-scan refuses its own earlier wiring ("existing direct source must be reverted"), so hosted exits 0 still pinned to the old patch uuid #650 in Fix vendored uv/Hatch re-vendor to a newer patch (#742, #650) #943 October 7: a re-pin or remove leaves the older patch generation's wiring behind (Cargo registry block, go.sum pair, Maven -socket.<hex8> repository, older vendored entry; PR Replace a superseded patch generation's wiring on re-pin and remove #1035).
• E80 · filed Vendored Maven, Gradle and NuGet artifacts can be git-ignored silently, because only npm checks .gitignore #1061, Vendored Gradle exits 0 when the project's .gitignore excludes *.jar, so the commit silently drops the patched jar and every fresh checkout fails to build #620 Maven .jar and NuGet .nupkg vendored artifacts can be git-ignored by stock templates with no warning.
• E86 · filed Vendored JVM fetches upstream artifacts and checksums only from Maven Central, ignoring the build's mirrors and repositories #1069 Vendored JVM fetches upstream artifacts and checksums only from Central or SOCKET_MAVEN_REGISTRY.
• E68 · filed Vendored gem revert restores Gemfile.lock but leaves the Gemfile path: line when that line carries a trailing comment, and no re-run can finish it #988: vendored gem treats a Gemfile that merely contains the copy path as wired, but its revert needs the exact recorded line and reverts the lock records anyway: a trailing comment on the wired line leaves Gemfile.lock restored to the registry while the Gemfile keeps path:, and every later revert drift-keeps (executed three times). Same forward/revert split as Vendored requirements.txt can't be reverted once the user touches the # socket-patch vendor: comment: vendor --revert drift-keeps forever (exit 0), and the suggested "re-vendor" remedy is a no-op or adds a duplicate line #977; see 5.3.
• E61 · fixed (Scan every vendored-write file for vendored references (#832, #958) #1015): the vendored-reference scan (repair, the orphan sweeps, the vendor stranded-reference gate, rollback) now reads every file whose registry entry carries the VENDORED role; hatch.toml and the other seven files that registry::VENDORED_WRITES_UNMARKED used to list got the role and the list was deleted, so a wheel a hatch.toml environment still names counts as wired (Scan every vendored-write file for vendored references (#832, #958) #1015).
• E66 · filed Vendored Poetry wires a 2.x lock through two different splicers depending on its line endings #936: vendored Poetry wires a 2.x lock through the toml_edit engine when it is CRLF and through a toml_surgery line scanner when it is LF. For the same lock the two give different files shapes, and only the engine checks the wheel name and lowercases the digest (executed twice); see 5.4.
• E65 · filed vendor --force documents a missing-file tolerance and a mismatch warning that no vendored backend implements #923: vendor --force documents a missing-file tolerance and a vendor_content_mismatch_overwritten warning that no backend implements; every acquisition sink takes _force/_sources, and vendor with and without --force behave the same (executed twice). Decide: give SOCKET_FORCE per-command names so forcing a self-update doesn't also force apply and vendor #615 decided to remove SOCKET_FORCE; the flag cleanup stays in vendor --force documents a missing-file tolerance and a mismatch warning that no vendored backend implements #923; see 5.2.
• E61 · fixed (Scan every vendored-write file for vendored references (#832, #958) #1015): nuget.config and pom.xml carry the VENDORED role, and the scan parses wiring through vendor::path::parse_vendor_reference, which accepts the bare uuid directory that NuGet feeds and Maven repositories name, so a still-wired feed or repository is no longer swept (Scan every vendored-write file for vendored references (#832, #958) #1015). The eco == "maven2" arm of the stranded-reference gate in commands/vendor.rs is still dead (the directory is maven).
• E59 · fixed (Fix vendored gem lookup beyond the first GEM section (#779) #805): vendored gem edit_lock searched only the first GEM section of Gemfile.lock, so a gem from a later source was refused; fixed by Fix vendored gem lookup beyond the first GEM section (#779) #805; see 5.4.
• E58 · filed Delete the vendored and hosted-vlt helpers left without a production caller by the v5 consolidation #782: production pub fns with no production caller, orphaned by v5 prerelease: scan → vex → vendor workflow, hosted by default #277: VendorEntry::committed_artifact_intact and go_sum_edit::remove_lines (no reference at all), plus test-only helpers compiled into production (cargo_tag::copy_manifest_tag, jvm::apply::read_project_file). The hosted-vlt half is in Part 3.
• E10 · filed Tracking: read and edit pom.xml through one element scanner in formats::maven #715, Vendored Maven refuses a single-module EAR pom as a multi-module aggregator because two declares_modules disagree #716, Locate hosted Maven pom edits and their upstream restore through the formats::maven element scanner #717, Read and splice nuget.config through formats::nuget in hosted, vendored and restore #594; NuGet hosted reader fixed (Unify hosted NuGet routing and XML splice anchors #597): vendored Maven decides "is this a reactor?" twice. jvm::detect uses the reactor's Doc-based declares_modules, which ignores plugin <configuration><modules>, then the legacy single-pom path re-checks with its own comment-stripping declares_modules and refuses vendor_maven_multimodule_unsupported. That refusal fires only on the disagreement, so every maven-ear-plugin project is refused; see 5.4.
• E54 · fixed (Fix Poetry/PDM lock splice drift (#694, #695) #703): the Poetry and PDM lock rewriters restored line endings with different rules; they now share lock_fragments and its majority rule (Fix Poetry/PDM lock splice drift (#694, #695) #703); see 5.4.
• E04 · partly fixed (Recognize hosted Pipenv references through one shared grammar (#563) #572); three recognizers remain (re-checked 431b818): hosted Pipenv used to reject its own pins on path-prefixed --patch-server-url origins and sdists. Both private grammars (owned_url's segment count, is_socket_hosted_reference) are deleted; Pipenv now uses hosted_pypi_reference (Recognize hosted Pipenv references through one shared grammar (#563) #572); see 5.4.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

[agent] Part 6 of 9 of the living socket-patch architecture document. The summary and ranked recommendations are in the top post. Originally written against 2463257; the routines update this part as the code changes.

Part 6: Discovery, inventory and VEX

Last checked against main @ 05ecc6e on 2026-10-07 by audit-ecosystems (PyPI pure-wheel selection in lock_inventory and ledger recovery checked for E89). Earlier: 431b818 by the October 7 reconciliation (extractor count and the false-attestation backlog re-checked; this part does not yet cover the JVM-cache crawl or formats::registry). Earlier: db83f01 by audit-ecosystems (6.6 JVM crawler build-tool markers and npm alias discovery re-checked at db83f01; 6.4 layering inversion and the Bundler lock rule re-checked at 9c43dfc; 6.5 vex_consumed.rs and npm alias discovery as of 4646693; as of 045d7ec: gem lock selection, the go.mod row, 6.4 dead code and the product probe table re-checked). Owner: audit-ecosystems.

Scope: vex/** (incl. vex/discover/*), crawlers/**, formats/**, vendor/lock_inventory/*, and the CLI consumers vex.rs, vex_sources.rs, vex_consumed.rs, scan/discovery.rs, context.rs, list.rs, ecosystem_dispatch.rs.

6.1 Size

Area	Total	Production	Notes
vex/	28,788	~10,040	discover/ alone is 8,499 production lines, 27% of them comments
crawlers/	23,739	8,930	3,007 test-only oracle/equivalence lines; 32% of production lines are comments
formats/	5,131	4,650
vendor/lock_inventory/	7,605	3,659
CLI consumers	—	4,798	vex.rs 1,334, vex_sources.rs 976, vex_consumed.rs 596, ecosystem_dispatch.rs 816

The VEX stack is about 13K production lines tested by about 59K test lines: ~11K of core crawler tests and ~40K of CLI *vex* end-to-end tests.

6.2 Four discovery systems

System	Entry point	Reads	Returns
A. Crawlers	crawl_every_ecosystem (ecosystem_dispatch.rs:719-815); nine crawlers in a tokio::join!	installed trees (node_modules, site-packages, vendor/composer/installed.json) and whole machine caches: $CARGO_HOME/registry/src, GOMODCACHE, ~/.m2, ~/.nuget/packages, DENO_DIR	CrawledPackage {name, version, namespace, purl, path}
B. Lock inventory	inventory_project_diagnosed_in / union_views_in (lock_inventory/mod.rs:320-370)	one lockfile per ecosystem, chosen by precedence (shrinkwrap wins; uv is exclusive; poetry → pdm → Pipfile). No Maven, NuGet or Deno.	LockfileEntry {ecosystem: &'static str, name, version, purl, resolved, integrity, source_kind}
C. Wiring discovery	discover_with_ctx (vex/discover/mod.rs:725-745); 15 extractors in fixed order (13 at review), then contest_across_locks	every lock/config present ("rule 1: never apply precedence"), each swept for Socket identities	Discovery {refs: Vec<PatchedRef>, diagnostics, recognized, unlocked_pins, elsewhere}
D. Vendor-ledger supplement	vendored_ledger_supplement (scan/discovery.rs:141)	.socket/vendor/state.json + artifacts	fabricated CrawledPackages

How scan combines them (scan/mod.rs:1589-1660):

1. Crawl first, in every mode.
2. Append lockfile-only entries as fabricated CrawledPackages. crawled_from_purl (discovery.rs:113-133) sets path: cwd.join("node_modules").join(name_part) for every ecosystem, including cargo and pypi.
3. Append ledger-only entries.
4. Fold hosted pins from C into update detection.

Overlaps:

• B and C walk the same per-format entries. B keeps registry entries; C classifies the Socket-owned ones and emits ResolvedElsewhere, which is a second registry view.
• Liveness then calls B a third time, straight from disk (inventory_project_every_lock(root), mod.rs:1602), bypassing the shared DiskSnapshot.
• B has two parallel modes, Instances::Every and Instances::Collapsed, with an if/else for every format.
• A is unrelated to B and C.

This could be one pass, because the per-format parsers are already mostly shared. What is duplicated is the classification and selection layer. One model would replace all of them:

struct Instance {
    purl: CanonicalPurl,
    declared_in: Option<Rel>,
    resolution: Registry { url, integrity, source_kind }
              | Hosted { uuid, url, integrity, required }
              | Vendored { uuid, artifact_rel, integrity }
              | Other,
    installed_at: Vec<PathBuf>,   // filled in by locators (ex-crawlers)
}

From that model:

• LockfileEntry is the Registry instances, filtered by precedence and deduplicated;
• PatchedRef and HostedPin are the Hosted and Vendored instances;
• ResolvedElsewhere is the Registry and Other instances;
• the scan supplement is instances with an empty installed_at, which removes the fake node_modules path.

formats/mod.rs:1-25 already documents this target (entries(), wired_refs(), plan_hosted()), but entries() exists only for composer, pnpm, gem and cargo, and wired_refs() only for pnpm.

6.3 Format × subsystem matrix (abridged)

Format	Shared read model	Writers with their own walk
package-lock	lock_inventory::npm_lock_nodes	vendored scan_lock_matches, hosted mod.rs:837, upstream npm_lock_hits
Pipfile.lock	lock_inventory::pypi::pipfile_lock_entries	vendored pypi_pipenv.rs (×3), hosted redirect/pipenv.rs:98; the crawler re-implements Pipenv venv hashing
Cargo.toml	—	hand-rolled twice (cargo_crawler.rs:21, vex/product.rs:167/380) despite toml_edit
go.mod	go_mod_edit	module directive read through go_mod_edit::module_path by product.rs parse_go_mod (single-line and block form) since #870 E19 · filed #780; gem models open, go.mod module reader fixed (#870)
NuGet	formats::nuget::parse_open_tag	vendored has its own XML scanner. The crawler reads obj/project.assets.json only for packageFolders, never libraries/targets, then enumerates the global ~/.nuget/packages
Maven	formats::maven::parse_pom	vendored jvm/maven_reactor.rs Doc::parse and gradle.rs; hosted's own tag scanner; the crawler's own XML parser; product.rs again

Across the repo that is eight hand-rolled XML scanners, 4–5 independent walks of package-lock packages, and 3 of Pipfile.lock categories.

6.4 Recurring helpers (confirmed)

• utils/purl.rs contains two purl-builder families.
  • The unchecked build_{gem,maven,golang,composer,jsr,nuget,cargo}_purl, used by crawlers and vendor/*.
  • The validating npm_purl, pypi_purl, simple_purl, golang_purl, composer_purl and maven_purl, used by inventory and VEX.
  • On top of those: build_npm_purl in npm_crawler.rs, 13 inline format!("pkg:…") in product.rs, and 78 hand-built purl strings outside purl.rs in total.
• The crawlers re-implement the validators. is_safe_cargo_coordinate, is_safe_gem_coordinate and is_safe_nuget_coordinate have byte-identical bodies and equal simple_purl's check; utils::purl::maven_purl and vendor/maven_repo.rs import crawlers::maven_crawler::is_safe_maven_coordinate. E37 · filed Move the crawler coordinate guards and composer's leading-v rule into utils and delete the copies #630
• composer_crawler::normalize_version behaves exactly like utils/composer_version::strip_leading_v, and formats::composer and upstream::composer import the crawler copy (a formats → crawlers edge). E37 · filed Move the crawler coordinate guards and composer's leading-v rule into utils and delete the copies #630
• Layering inversion. canonicalize_pypi_name lives in crawlers/python_crawler.rs and is imported by 29 files outside crawlers/ (checked on 9c43dfc), including lock_inventory, vex::discover, utils::purl and patch::redirect. The leading PEP 508 name scan is written four times (vendor::common::pep508_name plus three inline copies; two of them require an alphanumeric first character). E39 · filed Move canonicalize_pypi_name and the PEP 508 name scanner out of crawlers and vendor into one PyPI name module #883; Ecosystem move overlaps --ecosystems rejects NPM and npm, pypi, which socket.yml patches.ecosystems accepts: the ecosystem name parser is written three times #773, Tracking: build and classify purls through one validated utils::purl API #748 Ecosystem itself lives in crawlers/types.rs, while LockfileEntry.ecosystem is a string tag beside it.
• The product-manifest probe table is copied three times, and has drifted. vex.rs:1118 PRODUCT_MANIFESTS copies product.rs:80-87 but lacks the csproj and gemspec probes. The --product help text is a third copy (up to date today). Proved on 045d7ec: a lone Tool.csproj that parse_csproj rejects yields a bare product_undetected message, while a package.json without a version is named in it. E38 · filed vex product_undetected never names an unusable .csproj or .gemspec because the CLI keeps its own copy of the probe table #816; CLI probe-table copy (product_undetected message); parser reuse is Read Cargo.toml package name and version through one shared toml_edit reader #693/Read the go.mod module directive through go_mod_edit and delete the crawler's unused parse_go_mod_module #781/Tracking: read and edit pom.xml through one element scanner in formats::maven #715; Gradle/sbt probes are E87
• Test RNG. xorshift is implemented four times.

Dead code:

• lock_inventory/wired.rs (wired_vendor_integrity, 221 production lines) has no production caller (verified); only tests use it. That matches the v5 migration note "repair no longer reconstructs a missing ledger from lockfiles". The module docs at lock_inventory/mod.rs:13-15 are stale. Its only consumer, formats::pnpm::PnpmLock::wired_integrity, is dead with it, and it imports vex::discover (a vendor → vex edge). E41 · filed Delete lock_inventory::wired_vendor_integrity and PnpmLock::wired_integrity, which have no production caller #801; empty deno.rs extractor is deliberate, pre-v5 ledger readers are live migration
• vex/discover/deno.rs is an empty extractor, by design: its module doc keeps per-ecosystem coverage explicit. Not a defect.

6.5 VEX design

• verify.rs is small (346 production lines): a hash check per record, the vendored artifact basis, and HostedCopies. The complexity lives elsewhere:
  • vex_sources.rs (976) merges five sources: manifest, vendor ledger, legacy redirect ledger, discovery refs and API-fetched records. It has 5 omission gates, 7 note codes and 3 Basis kinds.
  • vex_consumed.rs (1,173 lines on 4646693, up from 596) decides "which installed copy the hosted build consumes". That covers cargo registry host-hash matching, Maven -socket.<hex8> dirs, the Go replacement module, and npm alias and store variants. This is a third copy of package-manager layout knowledge (after the crawlers and vendor/*), and it lives in the CLI. Its npm alias walk now duplicates the core resolver's alias_copies (Fix agent mode skipping npm-aliased copies (#356) #738), and the Maven suffix is rebuilt beside two core builders and three parsers of the same grammar. E40 · filed Tracking: move vex_consumed's per-ecosystem consumed-copy rules from the CLI into core #855, Resolve VEX npm alias copies through the core resolver and delete vex_consumed's second alias walk #856; tracking Tracking: move vex_consumed's per-ecosystem consumed-copy rules from the CLI into core #855; child Resolve VEX npm alias copies through the core resolver and delete vex_consumed's second alias walk #856 in PR Fix open npm issues #1008 (draft)
  • Discovery liveness (discover/mod.rs:1490-1990, ~500 lines), including the raw-text fallbacks vendored_wiring_in_files and hosted_wiring_in_files.
• product.rs (659 production lines) only auto-detects the top-level product purl:
  • ~200 lines parse the git origin remote;
  • 8 manifest probes each have their own parser, and none reuses formats::maven, toml_edit or go_mod_edit;
  • --product overrides the result anyway.
• "Wired" vs "consumed" evidence.
  • Wired means a lockfile pin on an allowlisted host plus an integrity pin. lockfile_basis_ok lets an attestation stand with no installed bytes.
  • Consumed means hashing the installed copy that the wiring routes to.
  • This is where the open "VEX attests not_affected while unpatched" bugs come from (16 at review, about 46 on 2026-10-07; Fix VEX attesting beside an unpatched same-lock copy (#935, #938, #939) #940 and PR Stop VEX attesting over yarn PnP, pnpm bundled and deno.lock copies #1033 address the same-lock, PnP, pnpm-bundled and deno groups). E72 · in PR Stop VEX attesting over yarn PnP, pnpm bundled and deno.lock copies #1033; Maven integrity_required = false waits on E46 Requiring consumed evidence by default is open decision E46. The wired basis assumes the package manager honors the pin. Every package-manager quirk that breaks that assumption becomes a false attestation:
    • warm caches (Vendored and hosted NuGet patches are shadowed by a warm global packages folder: silently unpatched without a lock, NU1403 with one #352);
    • a go.work override (A user replace in go.work silently overrides the Socket go.mod replace: Go apply and vendor report success and VEX attests not_affected while the build links the user's target #393);
    • Bun's isolated linker (With Bun's isolated linker, vex attests a hosted patch as not_affected (verified) while the installed copy under node_modules/.bun is still unpatched (v5 regression) #405);
    • deno.lock (Hosted npm pin in package-lock.json is attested by VEX in a Deno project, but deno.lock keeps installing the unpatched registry copy #406);
    • --system-site-packages (In a --system-site-packages venv, pip keeps the base interpreter's unpatched copy after a hosted rewrite, no stale-install warning fires, and vex attests it as patched #409);
    • Gradle locking (Hosted Gradle snippet silently builds the unpatched jar in any project using dependency locking (gradle.lockfile), on every Gradle major and OS #396);
    • Maven mirrors (Vendored Maven silently resolves the unpatched jar when an earlier <repository> or a mirrorOf * mirror serves the same GAV, and VEX still attests #263).
  • See the appendix for the architectural fix.
• Standalone vs embedded --vex. Generation is shared: apply, vendor and scan call the same generate_vex_* functions. Two problems remain:
  • Embedded runs inject bypass sets (assume_applied, known_stale, hosted_records, npm_prior), which couples VEX correctness to each caller.
  • The rendering glue is duplicated per command: dry-run skip, JSON folding, "nothing to attest", exit codes. It appears in scan/mod.rs:360-470 and apply.rs:790-860, and in three variants inside vendor.rs.
• Low-value paths:
  • The pre-v5 redirect-ledger path. No command writes it (state.rs:148: "socket-patch v5 never writes this file"), yet it still drives redirect_record_live/LedgerLiveness, hosted_wiring_in_files and HostedFileRole (~430 lines), plus the CLI-side handling.
  • Naming: vex::discover is really the v5 hosted-state store. Scan, get, apply, vendor, rollback, list and core hosted rollback all use it. It is not VEX-specific.

6.6 Crawlers

• Oracles. The npm "oracle" is the pre-parallel crawler, "kept verbatim as the equivalence oracle" (1,846 lines, test-only). Six more oracles plus oracle_support.rs and maven_pom_equivalence_tests.rs bring this to 3,007 lines. The parallel walk has shipped, so retire them.

• walk_pool.rs (338 production lines) adds a rayon pool with an fd budget, an 8 MiB stack, a 16-thread ceiling and a performance-core probe. It is justified by its benchmark table, but sized for npm only.

• Global mode (--global/--global-prefix) adds a branch to every crawler. The npm/yarn/pnpm/bun global-prefix probes alone are ~240 lines of subprocess spawning.

• Python environment discovery is ~1,060 of python_crawler.rs's 1,616 production lines:

  • VIRTUAL_ENV, .venv, venv and nested venvs;
  • pyenv, conda, Homebrew and uv tools;
  • re-implementations of Poetry's and Pipenv's venv-name hashing;
  • a fallback to global site-packages when no venv exists.

  The open issues Agent-mode scan misses Poetry's venv for nameless non-package-mode projects, [project].name overrides, and in-project = false with a stray .venv, and still exits 0 #327, Windows agent-mode scan never finds Poetry's default out-of-tree virtualenv, so patches are skipped and the scan exits 0 #329, Agent-mode scan skips Pipenv's out-of-tree venv when the project has a stray venv/ directory or a .venv with PIPENV_VENV_IN_PROJECT=0, and still exits 0 #334 and Agent-mode scan patches the activated VIRTUAL_ENV even when PIPENV_IGNORE_VIRTUALENVS or PIPENV_ACTIVE tells Pipenv to ignore it, leaving the Pipenv venv unpatched with exit 0 #384 are all this re-implementation diverging from the real tools. Asking the tool instead (poetry env info -p, pipenv --venv, uv python find) is cheaper and correct by construction.

• Cache crawls are not project-scoped. In local mode, cargo, go, maven, nuget and deno enumerate the entire machine cache as soon as a marker file exists (cargo_crawler.rs:144-183, go_crawler.rs:133-158, maven_crawler.rs:565-607, nuget_crawler.rs:37-90, deno_crawler.rs:65-81). Scan then sends all of it to the API. E05 · filed Tracking: scope project-mode cache crawls to what the project resolves #595; tracking, children Project-mode NuGet agent scan patches, and VEX attests, packages the project doesn't depend on (the crawler lists the whole ~/.nuget/packages) #427, Maven hosted scan pins, and VEX attests, artifacts the project doesn't depend on (the crawler lists all of ~/.m2) #265

  • Hosted mode can only act on lock entries, so the rest becomes "unconfirmed" noise.
  • For Maven and NuGet this crawl is the only discovery. Issue Maven hosted scan pins, and VEX attests, artifacts the project doesn't depend on (the crawler lists all of ~/.m2) #265 ("Maven hosted scan pins, and VEX attests, artifacts the project doesn't depend on, because the crawler lists all of ~/.m2") is this bug.

• FIFO safety. Crawler reads of project-tree files go through the FIFO-safe utils::fs::read_regular_to_string{,_sync} readers: nuget_crawler.rs (obj/project.assets.json), both cargo vendor/<crate>/Cargo.toml reads (verify_crate_at_path, read_crate_cargo_toml) and the Python .venv read. A FIFO there is skipped, not blocked on. crawlers::architecture_tests::crawlers_read_project_files_fifo_safely fails on any bare fs::read_to_string(, fs::read( or File::open( in crawler production code. The only allowlisted reads are the two machine-repository Maven POM reads in maven_crawler.rs. E06 · fixed (Read NuGet and Cargo crawler project files through the FIFO-safe reader (#592) #602)

Are crawlers needed in hosted and vendored modes? Only as locators, not enumerators.

• Vendored: artifacts come from the service ("backends never construct an archive locally"); the installed tree is an "optional installed location used for identity and release-variant probes".
• Hosted: it needs get_site_packages_paths / get_gem_paths for stale-install probes and copy lookups for VEX. Candidate discovery should be inventory-driven.
• Enumeration (crawl_all) is genuinely needed only for agent mode, --global, get <name>, and projects with no lockfile.

6.7 Target layout

core/src/ecosystem.rs       Ecosystem + tag/cli/purl-type maps (from crawlers/types.rs, vendor/path.rs)
core/src/purl/              ONE validating builder set; pep503 name; composer identity; go case-encoding
core/src/formats/<fmt>/     pure model per lock/manifest: parse → entries() (with key/pointer + resolution) → plan_hosted / plan_vendored / restore
core/src/inventory/         Inventory { instances, diagnostics, recognized, unlocked_pins }
    read.rs                 file selection over ProjectView + guarded reads + identity sweep
    classify.rs             Registry | Hosted | Vendored | Other
    views.rs                registry_view (= LockfileEntry), wiring_view (= PatchedRef/HostedPin), contest, liveness
core/src/locate/            ex-crawlers: per-ecosystem find(purl) incl. "consumed copy" rules (from vex_consumed.rs);
                            enumerate() only for project trees / --global; env/ (python, ruby, npm-global)
core/src/vex/               schema, build, time, verify, product (reusing formats)
cli: ProjectContext owns ONE Inventory; one EmbeddedVex helper

Risks. Discovery is fail-closed, security-sensitive code. The golden snapshots and the ~40K lines of end-to-end tests are the safety net, so migrate one format at a time behind them. The CLI_CONTRACT warning codes must not change. Scoping the cache crawls changes output for lockless cargo, Gradle and NuGet projects, so keep a fallback flag for those.

New findings since the review

• "Is this an sbt / Mill / scala-cli build?" has six marker lists since sbt, Mill and scala-cli support in agent, hosted and vendored modes #690 (JVM_PROJECT_MARKERS, SCALA_TOOL_MARKERS, is_sbt_build, sbt_evidence::cache_roots, MILL_MARKERS and scala-cli's MILL_MARKERS minus .mill-version). The agent JVM crawl gates on the narrow list before the wide one, so a scala-cli directory with only .scala-build, or an sbt root with only project/build.properties, gets no Coursier roots, while m2_gate, vendored sbt::detect and hosted is_sbt_build treat it as a Scala build (executed). E69 · in PR Route JVM layout through one module and fix three JVM scope bugs #1032; defects A and B, the .mill-version rule remains

• npm alias discovery is written twice: core NpmCrawler::alias_copies (apply, rollback, the VEX installed lookup) and the CLI's vex_consumed walk (hosted VEX). They have drifted on case: on Linux, an alias dir whose name differs from the package only by case is a copy for VEX but invisible to apply (proven by execution). This is behind Fix vex alias tests broken by store-copy merge #851 and Agent mode misses an npm-aliased copy under install-strategy=linked (node_modules/.store/lp@…), so apply exits 0 with it unpatched and VEX attests not_affected #852. E40 · filed Tracking: move vex_consumed's per-ecosystem consumed-copy rules from the CLI into core #855, Resolve VEX npm alias copies through the core resolver and delete vex_consumed's second alias walk #856; tracking Tracking: move vex_consumed's per-ecosystem consumed-copy rules from the CLI into core #855; child Resolve VEX npm alias copies through the core resolver and delete vex_consumed's second alias walk #856 in PR Fix open npm issues #1008 (draft)

• E72 · in PR Stop VEX attesting over yarn PnP, pnpm bundled and deno.lock copies #1033; Maven integrity_required = false waits on E46 October 7: VEX attested over yarn Plug'n'Play loaders, pnpm bundled copies and deno.lock npm copies (In a yarn classic Plug'n'Play project, vex attests a hosted patch as not_affected while the copy .pnp.js loads is still unpatched #519, Hosted npm pin in package-lock.json is attested by VEX in a Deno project, but deno.lock keeps installing the unpatched registry copy #406; PR Stop VEX attesting over yarn PnP, pnpm bundled and deno.lock copies #1033).

• E87 · filed VEX can't detect a product for Gradle or sbt projects, and scan --vex fails only after writing #1064 Product detection has no Gradle or sbt probe, and scan --vex resolves the product only after writing.

• E89 · filed Vendored uv repair pairs a hashless pure wheel with another wheel's hash, because ledger recovery re-parses uv.lock with its own scanner #1079 The pure-wheel rule is written four times: lock inventory and ledger recovery use ends_with("-none-any.whl") instead of the shared wheel_platform_from_filename (so the Fix interpreter-bound wheels treated as portable (#1048) #1053 fix won't reach them), and recovery re-parses the uv.lock unit with a string scanner that paired a hashless pure wheel with the next wheel's hash (executed twice).

• One rule now picks the live Bundler lock: lock inventory and VEX discovery follow Bundler's loaded pair (gems.rb → gems.locked, a stale Gemfile.lock twin ignored), as hosted, vendored and the crawler do through LoadedManifest::pair (Fix gem lock readers ignoring gems.locked (#736) #750). E56 · fixed (Fix gem lock readers ignoring gems.locked (#736) #750)

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

[agent] Part 7 of 9 of the living socket-patch architecture document. The summary and ranked recommendations are in the top post. Originally written against 2463257; the routines update this part as the code changes.

Part 7: Core infrastructure and agent (in-place) mode

Last checked against main @ 431b818 on 2026-10-07 by the October 7 reconciliation (7.3 spawn deadlines, the 7.4 safety model and the new 7.7 security boundaries). Owner: audit-core. Earlier: c5be5d1 by audit-core. Re-checked on c5be5d1 (15:50Z run): 7.2 retry table and registry timeouts after #889 and #876. Re-checked on 9c43dfc (09:56Z run): the 7.4 agent-mode footprint, the sidecar list (Maven rewriter from #646) and which ecosystems need agent mode. Re-checked on 9c43dfc: the self-update footprint and its overlap with install.sh (7.5), the credentials block of client.rs, agent-mode jar member verification, the apply/rollback store-copy fold and the artifact-retention (GC) policies. Re-checked on 0d302dc: the api/* size row, the client.rs breakdown, the retry table, the registry-client timeout, process spawning and hash case. The timeout, blob/diff body, zip-read, process-spawning, API-pacing, URL-builder, retry, batching, hashing, UUID, env/home-dir, atomic-write, purl, dead-code, telemetry, apply/rollback-engine, diff-download, apply.lock, Maven-sidecar, group-commit-reader, socket.yml and spawn-deadline passages were re-checked on 045d7ec; the rest is as of 2463257. 2026-10-07 14:00Z: 7.2, 7.4, 7.5 and 7.6 record the maintainer's decisions on #648, #792, #808, #983 and #1000 (no code re-check).

Scope: api/*, manifest/*, ledgers.rs, constants.rs, patch/ (excluding redirect/), policy/*, rollout*, update/*, the CLI update_notifier.rs/update.rs, telemetry.rs, and the generic utils/* and hash/*.

7.1 Size

Area	Prod	Inline tests	Main external tests
api/* (client.rs alone: 2,918 / 3,115 on 0d302dc)	5,208	6,613	retry e2e 787, proxy batch 326, blob fetcher 1,307
patch/* without redirect/	3,734	7,572	apply/ + rollback/ 8,719, e2e_safety_* 4,362
generic utils/*	~3,730	~3,400	—
policy/*	1,942	1,186	socket.yml e2e 1,025
update/* + notifier + commands/update.rs	2,351	2,378	3,311
telemetry	891	540	324
rollout (core + CLI)	~1,090	~950	1,688

That is about 19.6K production lines. Comments are a large share of them: 25% of client.rs, 34% of apply.rs, 38% of fs.rs and 48% of apply_lock.rs.

7.2 API client

Why client.rs is 2,918 production lines (on 0d302dc; moving the vendor service out is C29 · filed #871, #913; #871 vendor-service move, #913 credentials move (~330 lines)):

• ~950 lines: the vendoring service, which is not the patch API. The two-step grant + download (fetch_vendor_package → download_artifact_resuming), its types, and download_artifact_capped.
• ~330 lines: credentials (L2039–L2368 on 9c43dfc). Env/config resolution, a token-shape lint, org auto-resolve and the proxy-fallback client builder; moving them out is the second C29 issue, Move API credential resolution out of api/client.rs into api/client/credentials.rs #913. Per Decide: where patch API calls go when a token is set but the org slug can't be resolved #648 the org-resolve step will produce the run's single route, so Move API credential resolution out of api/client.rs into api/client/credentials.rs #913 and the Decide: where patch API calls go when a token is set but the org slug can't be resolved #648 PR rebase on each other.
• ~200 lines: legacy proxy fallback. The per-package GET path, is_batch_unsupported.
• ~80 lines: debug-ordering machinery. A task_local buffer plus HeldBack/hold_back_debug, with 45 call sites in 11 files. Its only purpose is to make --debug output byte-identical to what a serial loop would print.
• ~650 lines: the patch API itself.

Three retry systems in one module: C15 · filed #676; #677 fixed (#889): vendor retries share parse_retry_after/jitter; blob/diff still no retry

Path	Policy	Retry-After	Jitter
JSON calls (send_json_request)	api::retry: 429/503 only, run-wide 60 s window	seconds or HTTP-date, via a 206-line hand-rolled HTTP-date parser (api/date.rs)	seeded SplitMix
Vendor POST/GET (VendorRetryPolicy)	429/500/502/503/504 + transport, 3 attempts	seconds or HTTP-date through the shared api::retry::parse_retry_after (#889)	api::retry::jitter_sample, ±25%
Blob and diff fetch (fetch_binary)	none	—	—

The vendor policy also has three separate hand-written retry loops, plus a first-attempt/resume split that exists only to keep the request sequence identical under prefetch. Two near-identical downloaders (download_vendor_archive_once and download_artifact_capped_once) differ only in return type and message strings.

Three URL builders with two different policies. patches_path sends an authenticated client without an org slug to /v0/orgs/default/..., but binary_url and vendor_package_url send the same client to the public proxy. Telemetry has a fourth copy of the decision. So when org auto-resolve fails, JSON calls go to the "default" org while blob downloads silently go to the proxy. Re-verified by execution on 045d7ec: view and batch go to /v0/orgs/default/patches/… with the bearer, while blob, diff, vendor references and telemetry go anonymously to patches-api.socket.dev/patch/…. Decided in #648: the org is resolved once, when the client is built, into one route (Org{slug} or Proxy) that all builders and telemetry read; a failed auto-resolve sends the whole run to the public proxy anonymously with one warning, never /v0/orgs/default; embedded --vex reuses the run's client instead of resolving again. PR pending. C07 · in PR #1041; decided 2026-10-07 (option 2): org resolved once per run into one route; failed auto-resolve → whole run on the proxy

Timeouts on the main paths (#581).

• ApiClient::new and plain_client() build both reqwest clients through one policy, api::retry::ApiTimeouts: API_CONNECT_TIMEOUT (10 s) and API_READ_TIMEOUT (60 s of silence, reset per chunk), with no total deadline. Tests override it with ApiClient::with_api_timeouts. C02 · fixed (Bound patch API connects and stalled reads (#570) #581); the retry half is C15
• A stall before the headers or mid-body fails as ApiError::Network; the three JSON readers share json_response_error, so a stalled body keeps its transport cause and only complete malformed JSON is Parse.
• The vendoring service keeps its own per-attempt deadlines and retries on top. Blob/diff fetches still have no retry (C15).

Batching is defined three times. The CLI owns the batch sizes (500 authenticated, 100 proxy, the 256 KiB body cap) and accepts any --batch-size. The in-memory hosted engine keeps its own copy (default 100 on either endpoint, max 500, no body-cap split, a second MAX_REFERENCE_BATCH). search_patches_batch documents "Maximum 500" but does not enforce it, while fetch_registry_references chunks itself. C16 · filed #675

Other HTTP stacks keep TLS and proxy settings consistent but diverge on timeouts, retry and error formatting:

• RegistryClient (hosted upstream restore) and vendored Maven's per-fetch client are built by one registry_client_builder on ApiTimeouts (10 s connect, 60 s idle), and registry_fetch::download reads through the shared read_capped (Bound registry downloads by ApiTimeouts instead of a 60 s total deadline (#872) #876); no retry. C49 · fixed (Bound registry downloads by ApiTimeouts instead of a 60 s total deadline (#872) #876)
• maven_repo.rs: builds a fresh client for every fetch.
• Self-update: its own clients with a custom redirect policy and no retry.
• Telemetry: a new client for every event.

Target. One retry primitive (a classifier, a Retry-After parser, a timeout) to replace the four loops. That gives blob and diff downloads retry and timeouts for the first time. Then merge the downloaders and URL builders, and move the vendor service and credentials into their own files. client.rs would drop to about 1.4K lines.

7.3 Duplicated utilities (verified)

• Hashing:

  • Since Compute sha256, sha1 and SRI digests through utils::digest (#706) #865, utils::digest holds the computations beside the validators: sha256_hex_of, sha1_hex_of, sha512_base64_of and sha512_sri_of. Production code in 14 files goes through them, and the ratchet test production_digests_go_through_the_helpers fails on a new inline copy. C17 · filed Compute sha256, sha1 and sha512-SRI digests through utils::digest instead of inline copies #706; slice 1 merged as Compute sha256, sha1 and SRI digests through utils::digest (#706) #865; slice 2 is the 6 files in PENDING_INLINE_DIGESTS (3 stale entries removed by Fix main CI red on stale digest pending-list entries #1016); sidecars/coursier.rs evades the text ratchet via a local digest()
  • Six production files still compute inline (its PENDING_INLINE_DIGESTS list): group_commit.rs, jvm/mod.rs, maven_repo.rs, pypi.rs, redownload.rs and yarn_berry_lock.rs. Private sha256_hex copies remain in jvm/mod.rs and group_commit.rs, and sha1_hex copies in maven_repo.rs and jvm/mod.rs.
  • Name collision: utils::digest::sha256_hex still validates a 64-hex string, while the jvm and group_commit copies compute a digest. The new helpers avoid it with an _of suffix.
  • vlt_preflight::sha512_sri and the inline SRI blocks in npm_pack and bun_lock are gone; test modules still define their own.
  • The 64-hex validator exists twice: apply::is_valid_blob_hash and digest::is_hex(s, 64) (client::is_valid_sha256_hex was folded into the latter by Compute sha256, sha1 and SRI digests through utils::digest (#706) #865).

• UUID checks: five grammars. client.rs has one, with a near byte-identical copy in CLI lib.rs; path_safety.rs accepts lowercase only; apply.rs accepts any alphanumeric plus - and _; utils/python_script.rs uses uuid::Uuid::parse_str, which also takes simple, braced and urn:uuid: forms. C18 · filed Validate patch UUIDs through one utils::uuid grammar instead of five #705; the user-input half (2 of 5 grammars) in PR Use one package target grammar for get, remove, rollback and the UUID shortcut #1034; a fifth grammar in python_script.rs

• Line endings: utils/line_endings.rs has 7 users, but python_lock, vendor/common::detect_eol (which contradicts LineEndings::Mixed), redirect::crlf_to_lf and poetry_lock each implement their own rules.

• Purls: utils/purl.rs has two builder families (7 unvalidated build_* with 21 production callers, and the validated *_purl). vex/product.rs hand-rolls a third. 42 production format!("pkg:…") sites outside utils/purl.rs and 24 starts_with("pkg:<type>/") checks outside Ecosystem::from_purl (counted at 045d7ec, production code only). The type checks agree today, but the builders already disagree on canonicalization (PyPI names and composer case). C20 · filed Tracking: build and classify purls through one validated utils::purl API #748, Route purl ecosystem checks through Ecosystem::from_purl instead of 24 inline starts_with("pkg:<type>/") tests #747; children 2–4 touch the ecosystem area

• Env truthiness: three vocabularies, plus a fourth rule in update_notifier::in_ci. C19 · filed Read env toggles, non-empty env vars and the home directory through one utils::env module #727; home-directory half in PR Share one path normalizer, home resolver and repository-root walk #1038

  • "1"|"true" in env_compat.rs (SOCKET_DEBUG, SOCKET_OFFLINE);
  • "1"|"true" separately in telemetry.rs;
  • 1|true|yes|on|y|t in socket_cli_config::env_truthy, which update_notifier imports, and the same set in the CLI's clap parse_bool_flag.

  The narrow core match stays correct only because apply_env_toggles rewrites every truthy flag back into the env as "1"; all ten command entry points call it on 045d7ec. "Empty means unset" is one private helper (socket_cli_config::env_non_empty) plus about 29 inline copies in 16 files. In this area there are at least six home-directory resolvers, and they disagree: policy::home_dir reads only USERPROFILE on Windows, while utils::fs::home_dir prefers HOME. The crawlers keep further variants.

• Atomic writes: utils/fs.rs has six public writers. Each is a named WriteOpts policy: capture, durable (barrier + fsync + dir fsync), keep mode, and durability record. They all run one blocking core, stage_and_rename_blocking; the async writers run it through run_blocking, and atomic_write_sync is the core itself (Write every utils::fs atomic file through one stage-and-rename core (#728) #858). One stage_path builds every stage name: .socket-stage- for these writers and .socket-dl- for the blob cache, whose streaming writer verifies the hash between stage and rename and keeps its own body. The self-update stage (update/download.rs, update/swap.rs) is legitimately separate. The artifact writers don't capture into a group commit, so bypassing utils::fs isn't itself a group-commit escape. C21 · fixed (Write every utils::fs atomic file through one stage-and-rename core (#728) #858) get writes .socket/blobs/<hash> with neither: it uses an in-place fs::write and doesn't check the content's hash (C42 · in PR Guard .socket links and agent writes with one containment helper #1042 (blob_fetcher::store_verified_blob)).

• Process spawning is centralized in process.rs::resolve_tool/command_for; on 0d302dc no production Command::new("<tool>") remains. Vendored Hatch now resolves hatch through resolve_tool_with instead of a bare spawn in the project root (Fix vendored Hatch running a planted hatch (#613) #617). C04 · fixed (Fix vendored Hatch running a planted hatch (#613) #617) Spawn deadlines go through one utils::process::output_within (Bound crawler and tool probes through one spawn deadline (#845) #886): every crawler probe (run_resolved: gem env, python --version, npm root -g, …) runs under PROBE_TIMEOUT (10 s), as do Pipenv, Hatch and the self-update sanity_exec, whose hand-rolled timeout + kill_on_drop blocks were deleted. Two hand-rolled deadlines remain: the vendored npm git check-ignore exchange (30 s and 60 s) and crawlers/python_crawler/pdm_site.rs, which keeps its own 5 s PROBE_TIMEOUT with kill_on_drop (added by Fix PDM settings ignoring PDM's config layers (#609, #566) #611 after the review); Route the remaining hand-rolled child-process deadlines through utils::process #1067 tracks both. C48 · partly fixed (Bound crawler and tool probes through one spawn deadline (#845) #886); pdm_site and the npm_dir git exchange keep hand-rolled deadlines (Route the remaining hand-rolled child-process deadlines through utils::process #1067)

7.4 Agent mode

Footprint:

• core (re-measured on 9c43dfc): apply 1,230, rollback 751, sidecars 1,107, store_copies 332, shared_store 332, diff 99, package 332, blob_fetcher 603, manifest 578. patch/apply.rs, package.rs and manifest/ are shared with vendored staging; the agent-only part is about 3.2K;
• CLI (on 9c43dfc): apply 2,963 (2,237 at the review), fetch_stage 437, repair 785;
• the multi-mode rollback (2,660) and remove (1,571) carry agent legs;
• over 13K dedicated test lines.

Counting the agent arms in scan, get and rollback, agent mode is about 6.4K CLI production lines plus ~3.5K in core (review numbers; the CLI apply.rs has grown ~700 lines since). Deno (its only mode) and --global installs (hosted and vendored act on project lockfiles) have no other mode; Go's agent mode writes a .socket/go-patches/ replace, which vendored also covers. About 29 of the open bug issues are agent-mode-specific, roughly twice the review's ~15. The maintainer decided to keep agent mode for every ecosystem for now (#1000, option A); its open bugs are tracked and fixed individually. C55 · rejected; #1000 (2026-10-07) chose option A: keep agent mode for every ecosystem for now, layout bugs fixed one at a time; #1000 closed

The safety model is worth keeping, but it was not complete (see 7.7: the .socket link guard, the inline-blob writer and agent writes through links were gaps; PR #1042 closes them):

• every manifest path is escape-checked;
• blob hashes must be 64-hex, and blob entries are read with lstat and FIFO-safe;
• patched bytes are hash-verified before any write;
• writes are stage + fsync + rename (which keeps pnpm, uv and Go cache hardlinks safe);
• read-only parent directories are relaxed and restored, and mode and uid/gid are preserved.

The default MismatchPolicy::Warn silently overwrites locally modified dependency files with the verified content; --strict is opt-in.

Apply and rollback are mirror images. VerifyStatus/VerifyResult and VerifyRollbackStatus/VerifyRollbackResult still have identical fields, and the sidecar boundary is still written twice. The pnpm/vlt store-copy fan-out and its fold are now shared (patch/store_copies.rs::fan_out), merging each copy's per-file records under the copy's path; both directions carry only the ownership advisory from a copy (#774, fixing #756). Rollback is apply with before/after swapped, plus deleting files the patch created, and could be one engine. C24 · filed #771; #772 fixed (#774), shared store_copies::fan_out; verify types + sidecar boundary remain

--download-mode diff is the default and is a net loss (verified). On a cold cache it fetches every diff archive and then every blob anyway:

• blob_scope = manifest whenever any archive was missing (fetch_stage.rs:377-385);
• the CLI even prints "Also fetching N per-file blobs (used where a diff does not apply)";
• everything is staged in a tempdir and thrown away after the run.

So diff only saves bytes when a user commits .socket/diffs but not .socket/blobs. The diff fetch is also sequential with no retry, and it is the only user of the qbsdiff dependency. Blob downloads are sequential with no retry too, while the JSON calls run 32 at a time.

• Decided (Decide: make --download-mode file the default and retire the diff download path #792): v5 removes the diff download path and the --download-mode / SOCKET_DOWNLOAD_MODE option outright (no alias). Blobs are the only patch-content source, and .socket/diffs/ is swept as obsolete like .socket/packages/.
• Saving: about 600 production and 1,000 test lines, plus one dependency. Re-verified on 045d7ec (top-up at fetch_stage.rs:377-398; diff-only code is patch/diff.rs (99 production lines), read_archive_filtered, resolve_from_diff/AppliedVia::Diff, fetch_diff, the diff fetch/coverage code in blob_fetcher/fetch_stage/repair and qbsdiff). patch/package.rs is not diff-only on current main: vendor/*, hosted/npm_manifest.rs and redirect/vlt_heal.rs use its readers, so it stays and the saving is nearer 400 production lines. C25 · in PR Remove --download-mode and the diff download path (#792) #1049; decided 2026-10-07 (option A, v5): delete the diff path, --download-mode and SOCKET_DOWNLOAD_MODE outright; patch/package.rs stays

Sidecars (patch/sidecars/, 1,107 production lines on 9c43dfc; 708 at the review) are post-apply fixes for package-manager checksum files:

• cargo: rewrite .cargo-checksum.json;
• Maven: rewrite a ~/.m2 .sha1/.md5 that described the pre-patch bytes, and put it back on rollback; Gradle files-2.1 copies get advisories (Full Gradle support in agent, hosted and vendored modes #646);
• NuGet: delete .nupkg.metadata;
• PyPI, gem and Go: advisory text only.

Maven 3.9.11 doesn't verify the local repository's .sha1 files by default, so the review's stale-checksum concern was rejected on 045d7ec; since #646 the Maven sidecar rewrites them anyway (for mvn -C and mirror tooling), and agent mode patches each Gradle files-2.1 copy the build reads, which fixed #551. C27 · already fixed (#646); Maven 3.9.11 ignores stale local .jar.sha1, Gradle half closed with #551 This code exists only for in-place mode.

apply.lock is 553 production lines (re-checked on 045d7ec). Most of that complexity comes from deleting the lock file on exit: unlinking while it is held, identity checks, Windows delete-pending handling. Lock acquisition also replays the vendored group-commit journal, which couples vendored crash recovery into every command's lock. Decided in #808: the lock stays transient. socket-patch never leaves a lock file in the project, and a persistent lock, if ever needed, would live outside it (home/cache dir or a configurable path), so the ~200 lines of deletion machinery stay. One residue path remains on main: an interrupted run (Ctrl-C/SIGTERM/SIGHUP, Windows console ctrl) dies without dropping the guard and leaves apply.lock until the next lock-taking command; the #808 PR removes the file on interrupt. Moving the journal replay and the durability barrier out of the lock primitive changes no behavior (tracked by #809 and #793). C26 · in PR #1030; decided 2026-10-07 (option C): the lock stays transient; journal layering is #809

Dead path (verified): PatchSources::mem_blobs is never Some in production, but its doc still says vendor flows stage content there. C23 · filed #746; Pypi/LauncherCache channels are live (not dead)

7.5 Features with questionable value

Feature	Prod / tests	Verdict
Self-update + passive notifier	2,351 / 5,689	Only Standalone installs self-update; npm, cargo and brew are redirected to their own tools. Still detects the pre-v5 Pypi and LauncherCache channels, which is a live refusal for old installs, not dead code. Two metadata strategies, a separate lock, and its own stage writer. Keep both (decided #983). The maintainer treats self-update as essential. Follow-ups: retry on transient failures, an idle timeout instead of the 300 s whole-download budget, streaming the archive to disk instead of a 256 MiB in-memory read_capped, and a live post-release --update test. Re-checked on 9c43dfc: still 2,350 production lines; install.sh has no Windows rows and the README sends Windows zip users to --update, so replacing the swap drops their only updater. C36 · rejected; #983 (2026-10-07): keep the --update swap and the notifier, harden them (retry, stall timeout, streaming, live test); #983 closed
Telemetry	891 / 864	19 near-identical public wrappers (17 track_* + 2 spawn_*, ~450 lines); a new HTTP client per event; endpoint logic duplicated. The CLI passes token/org at ~45 call sites in 10 command files, plus 5 helper signatures (not 125), and resolves them two ways: telemetry_credentials() in list/vex, the API client's getters elsewhere. Collapse to one Telemetry handle with track(Event) and a shared client (~−300). C22 · filed #770
Failpoints	65	Fine (compiled out of release). But switched_off("group_commit") keeps the old non-group-commit path alive as a test oracle.
group_commit + durability	1,376 / 1,287	A process-wide virtual filesystem: every utils::fs read and write consults it. It renders typed values lazily via Any, does three-way hand-edit reconciliation in recover, and still journals redirect-state.json, which nothing writes. Writes that bypass utils::fs are silently not captured. High-cost machinery for a vendored-run speedup; see 5.7 for the root-cause fix.
socket.yml policy	1,942 / 2,211	Real value. socket_yml.rs builds its own YAML node tree on serde-saphyr's event parser (:36-320, ~285 lines) to read 8 keys. Re-checked on 045d7ec: the tree is what implements the contract's validation rules (CLI_CONTRACT "Validation (fail closed)"): no alias expansion outside the keys read, anchors, aliases, merge keys and custom tags refused only inside patches/projectIgnorePaths, YAML 1.2 core-schema scalars (enabled: yes is an error), and per-key paths with did-you-mean hints. serde with deny_unknown_fields can't scope those refusals to one subtree of a file other Socket tools share, and the ~300 lines of validators would stay. Not a defect. C28 · rejected; the tree implements the contract's scoped YAML refusals
Rollout / --max-new-patches	~1,090 / ~2,640	Pure planning, threaded through the hosted Gate, the agent stage and a cross-directory carry. The in-memory engine (PR bots) uses it. Keep it in socket.yml; consider dropping the flag and env layering.
socket-cli config reuse	232 / 1,022	Cheap and valuable. Keep.
Legacy redirect ledger	spread across vex, rollback, group_commit	Read-only since v5. Set a sunset date.

7.6 Recommendations

1. Remove --download-mode and the diff machinery (decided Decide: make --download-mode file the default and retire the diff download path #792, v5): about −400 production, −1K tests, −1 dependency. Low risk. C25 · in PR Remove --download-mode and the diff download path (#792) #1049; decided 2026-10-07 (option A, v5): delete the diff path, --download-mode and SOCKET_DOWNLOAD_MODE outright; patch/package.rs stays

2. One retry and timeout primitive across every HTTP path, so the JSON and blob paths get timeouts: −200 production. Fixes possible indefinite hangs. Medium risk, because tests pin the current semantics. The self-update clients are now in scope too (Decide: keep the --update binary swap, or replace it with the installer and keep only the update notifier #983 keeps the swap).

3. Delete the verified dead and legacy code: mem_blobs, the always-true VendorSource predicates, the redirect-state.json group-commit LEDGERS entry, and the switched_off("group_commit") oracle path. About −60 production, −350 tests. C23 · filed Delete PatchSources::mem_blobs, the single-variant VendorSource predicates, the redirect-state group-commit capture and the group_commit switch-off oracle #746; Pypi/LauncherCache channels are live (not dead) (The Pypi/LauncherCache update channels are not dead: they make --update refuse to swap a pre-v5 pip/gem-owned binary and print a migration hint.)

4. Fold rollback into the apply engine (swap hashes, keep a delete branch for created files): −300 production. C24 · filed Tracking: one agent-mode patch engine for apply and rollback #771; Share one pnpm/vlt store-copy fan-out between agent apply and rollback, folding each copy's per-file records #772 fixed (Fix store-copy fold dropping copy writes (#756, #772) #774), shared store_copies::fan_out; verify types + sidecar boundary remain

5. One telemetry track(Event) with a shared client: −300. C22 · filed Send telemetry through one Telemetry handle with a shared HTTP client instead of 19 track wrappers #770

6. One validated purl builder family, and Ecosystem::from_purl for type checks: −250.

7. Small helper consolidation:

   • digest compute vs. validate;
   • SRI;
   • hex and UUID checks;
   • line endings;
   • env truthiness;
   • home dir;
   • (the bare hatch spawn is already fixed, Fix vendored Hatch running a planted hatch (#613) #617).

   Saves about −200.

8. Split client.rs into client, vendor_service and credentials, and give it a single auth-vs-proxy URL policy.

9. Keep the socket.yml event tree: on re-check it is the contract's validator, so serde would save little and lose the scoped refusals. C28 · rejected; the tree implements the contract's scoped YAML refusals

10. Harden self-update (kept per Decide: keep the --update binary swap, or replace it with the installer and keep only the update notifier #983): shared retry, idle timeout, streamed download, live post-release test. C36 · rejected; Decide: keep the --update binary swap, or replace it with the installer and keep only the update notifier #983 (2026-10-07): keep the --update swap and the notifier, harden them (retry, stall timeout, streaming, live test); Decide: keep the --update binary swap, or replace it with the installer and keep only the update notifier #983 closed

7.7 Security boundaries

Added on 2026-10-07 by the October 7 reconciliation; owned by audit-core. These are the trust boundaries the CLI must hold, with their current state:

Boundary	Rule	State
Credentials never leave their origin	Registry auth, grant tokens and URL userinfo must not reach the patch host, logs, --json, telemetry or VEX ids.	Hosted Composer kept transport-options (#399); warnings, debug output and telemetry carried raw URLs; the VEX product @id carried git-remote credentials. One utils::redact in PR #1026. Hosted rewriters' guidance snippets still need a review. C59 · in PR #1026
Writes stay inside the project	Every vendored and hosted write under .socket/, and every agent write, must stay inside the tree it was found in; links are refused, not followed.	The .socket link guard started below .socket and guarded deletes only (#887); get wrote inline blobs through a planted link without hashing them (#726); agent writes followed links out of the package. One containment helper in PR #1042. C60 · in PR #1042; rollback of an overwritten file needs a pre-image store
Bytes are verified before they are trusted	Patched content is hash-checked before any write; downloaded and inline blobs are checked against their name.	Agent apply verifies before writing; the inline-blob writer did not (fixed in PR #1042). Hosted rollback re-pins integrity from the registry (trust-on-rollback, E33/E45).
No planted binaries	Tools are resolved with resolve_tool, never by bare name in the scanned repo.	Fixed (#617). C04 · fixed (#617)
Untrusted archives are streamed	Committed and service archives are hashed by streaming, never inflated into memory by their own header.	Vendored verify streams (#587); agent-mode jar verification still buffers (C51). C01 · fixed (#587); streams members, no cap per maintainer
Updates are authentic	Self-update and install.sh should verify a signature or attestation, not only a same-origin checksum.	Only a same-origin SHA256SUMS; immutable releases stop swaps of a published release, not a malicious new one. C72 · filed #1065
Tests never reach production	Test children must not send telemetry or call production endpoints.	Test children sent telemetry to production; PR #1046 sets SOCKET_TELEMETRY_DISABLED for every child. C66 · in PR #1046

New findings since the review

• C37 · fixed (Stream patch blob and diff downloads to disk (#571) #607) Patch blob and diff downloads (fetch_blob / fetch_diff, via fetch_binary) return a BinaryBody stream, and one blob_fetcher::download_entries loop stages each body chunk by chunk to disk (stage_body), verifies blobs against their git-sha256 name and renames into place; no artifact body is held in memory, per the maintainer's stream-don't-cap steering. Vendor and self-update downloads keep the shared read_capped (256 MiB).
• C38 · filed The public-proxy per-package fallback runs 10 requests in flight, ignoring SOCKET_API_CONCURRENCY and the proxy cap of 4 #614, SOCKET_API_CONCURRENCY and SOCKET_WALK_THREADS are undocumented, and no test keeps core-read env vars in CLI_CONTRACT.md #678 API pacing has one policy (utils::concurrent: proxy cap 4, SOCKET_API_CONCURRENCY override, fd-limit rule), and every CLI window uses it, except the client's own public-proxy per-package fallback. That fallback keeps a private PROXY_BATCH_PATH_CONCURRENCY = 10, and on 045d7ec it ran 10 GETs in flight with SOCKET_API_CONCURRENCY=1. registry_concurrency() has no caller.
• C41 · filed Agent-mode apply and rollback reject a manifest hash in uppercase hex that blob download accepts as valid #707 Hash case policy is decided per site. Blob download compares case-insensitively on purpose (blob_hash_matches), and the blob-name validators accept uppercase, but agent-mode apply and rollback verify with exact == against the lowercase computed hash; vendored verify sites are split the same way. On 045d7ec an uppercased manifest hash downloaded and passed is_valid_blob_hash, then failed both apply and rollback verification with HashMismatch.
• C42 · in PR Guard .socket links and agent writes with one containment helper #1042 (blob_fetcher::store_verified_blob) .socket/blobs/<hash> has two writers. The fetch path verifies the git-sha256 and stages+renames, because get_missing_blobs trusts presence. get::write_blob_entry stores a patch view's inline blobContent under its claimed hash without checking it, truncate-writes in place, and overwrites an existing verified blob; it also hand-rolls base64 although the crate is a dependency. On 045d7ec a verified blobs/<H> was replaced with bytes that don't hash to H.
• C26 · in PR Remove apply.lock when a lock-holding run is interrupted (#808) #1030; decided 2026-10-07 (option C): the lock stays transient; journal layering is vendor --check and vex misreport a crashed vendored run whose commit journal is pending, because only lock-taking commands replay it #809 The vendored group-commit journal is replayed only inside apply_lock::acquire, so the lock-free readers never see a pending commit: after a crash past the journal, vendor --check fails every patch with vendor_ledger_missing (whose documented remedy is restoring state.json by hand) and pnpm vex omits the packages, while one locked command rolls the commit forward to the uninterrupted result (proved twice with group_commit_file@1).
• C49 · fixed (Bound registry downloads by ApiTimeouts instead of a 60 s total deadline (#872) #876) Registry downloads (build_registry_client, maven_repo::fetch_registry_bytes) now share ApiTimeouts' 10 s connect + 60 s idle bound instead of a 60 s total deadline, so a slow but progressing artifact download completes (Bound registry downloads by ApiTimeouts instead of a 60 s total deadline (#872) #876).
• C50 · filed repair and scan --prune delete the beforeHash blobs of active patches, so a later offline rollback fails and tells the user to run repair #893 Artifact GC has two retention policies. ArtifactReferences::after_removal (rollback, remove) keeps every active patch's beforeHash blobs so offline rollback keeps working (Share rollback artifact retention across remove and rollback #600), while for_apply (repair, scan --prune) keeps only afterHash blobs. On 9c43dfc, repair --offline deleted an active patch's original, and rollback --offline then exited 1 (twice), telling the user to run repair, which only ever downloads afterHash blobs. cleanup_unused_blobs/_archives and format_cleanup_result have no production caller.
• C51 · filed Hash agent-mode jar members through the shared streaming zip comparator instead of buffering each member #914 Agent-mode jar verification (jvm_jar::verify_member_bytes, used by apply, rollback and vex for Maven/Gradle member records) inflates each patched member into a Vec before hashing, while its vendored twin zip_bytes_match_after_hashes streams since Stream ZIP member hashes during vendored verification #587. On 9c43dfc, a jar with one deflated 1 GiB member peaked at 1,067 MiB RSS through the agent routine and 26 MiB through the vendored one (twice). One streaming member-hash helper replaces both.
• C48 · partly fixed (Bound crawler and tool probes through one spawn deadline (#845) #886); pdm_site and the npm_dir git exchange keep hand-rolled deadlines (Route the remaining hand-rolled child-process deadlines through utils::process #1067) Child processes share one deadline: utils::process::output_within bounds the crawler probe runners (run_resolved, PROBE_TIMEOUT 10 s), pipenv, hatch and the self-update sanity_exec (Bound crawler and tool probes through one spawn deadline (#845) #886), so a gem shim that never answers no longer hangs a local scan. The git check-ignore exchange in vendor/npm_dir.rs and the PDM site probe (pdm_site.rs) still hand-roll their timeouts (Route the remaining hand-rolled child-process deadlines through utils::process #1067).

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

[agent] Part 8 of 9 of the living socket-patch architecture document. The summary and ranked recommendations are in the top post. Originally written against 2463257; the routines update this part as the code changes.

Part 8: Tests, CI, docs and distribution

Last checked against main @ 431b818 on 2026-10-07 by the October 7 reconciliation (8.2 compile count, e2e legs, compat workflows, the coverage legs' gating role, and recommendation B). Owner: audit-core. Earlier: c5be5d1 by audit-core. Re-checked on c5be5d1 (15:50Z run): the covgap counts and the contract size. Re-checked on 9c43dfc (09:56Z run): the #[ignore] reasons across both crates (a RED/gap test has no CI leg). Only the repository-hygiene passages (stray launch.json, "DESIGN §" references), §8.3's CLI_CONTRACT.md measurements and guards, the contract's argument and env-var tables, the test-binary and covgap counts, the #[serial] count and the duplicated-helper counts have been re-checked; the rest is as of 2463257.

Scope: crates/*/tests/**, tests/ (docker fixtures), .github/workflows/*, .github/actions/*, scripts/, docs/, CLI_CONTRACT.md, CHANGELOG.md, npm/, crates/socket-patch-node/npm/, and the Cargo profiles. CI timings come from the GitHub Actions run for 2463257 on main.

PR #277 has already started cleaning up: it deleted 237,608 lines, including 136,809 lines of docs/testing/*/results.json and the pypi/gem distribution packages. The recommendations below build on that.

8.1 Test suite architecture

	Lines	Files	Test binaries
crates/socket-patch-cli/tests/**	235,571	302 .rs	172 (161 top-level + 11 */main.rs)
crates/socket-patch-core/tests/**	19,361	33	32
Inline #[cfg(test)] in src	~183–194K	—	3 unit targets

• Ratio: roughly 2.7 test lines per production line overall, and about 7:1 for the CLI crate (235.6K integration lines against 33.7K production lines).
• Test counts: ~2,753 CLI integration tests, 523 core integration tests and 5,442 inline tests. 242 are #[ignore]-gated.
• 207 test executables per cargo test --workspace at the review; 224 on 9c43dfc (189 CLI, 35 core). C31 · to verify; count confirmed, not filed There are no [[test]] entries, so every file links its own binary. The repo's own comments disagree on the count ("~240" in ci.yml, 159 in Cargo.toml, "~90" in .cargo/config.toml).
• Disk cost: Cargo.toml notes that macOS split-debuginfo "grew target/ to 99 GB".
• Docker binaries are always linked. The 14 docker_e2e_*.rs files are gated with #![cfg(feature = "docker-e2e")], so they still compile and link as empty binaries on every default run.

Consolidation was started but not finished.

• cli/main.rs says: "One test binary per command: each module was its own binary". e2e_vex_lockfile/ (23 modules, 19,650 lines, one binary) is the model to follow.
• The stragglers are still separate binaries:
  • 10 get-related binaries beside get/, and 10 scan-related beside scan/;
  • 19 cli_* files beside cli/;
  • 28 in_process_*, 16 e2e_vendor_* and 14 e2e_redirect_* binaries.

Duplicated helpers.

• common/mod.rs (792 lines) is #[path]-included and recompiled by ~60 binaries, and vex_e2e_common (876) by ~53. 34 helper files carry #![allow(dead_code)].
• Helpers that common already exports are redefined locally:
  • fn binary() in 103 files (7 variants);
  • fn git_sha256 in 86 files (10 variants), although common::git_sha256 exists and core exports compute_git_sha256_from_bytes;
  • copy_dir_recursive in 26 files;
  • scrub_socket_env: since Spawn CLI test children through one hermetic Command builder (#823) #850, child processes are built by one common/hermetic.rs builder, and 7 per-file copies remain (the PENDING_SCRUB_COPIES list in tests/spawn_env_hygiene.rs); 2 files still spawn the binary with no scrub (see C47 · filed Spawn every CLI test child through one hermetic Command builder; 10 test files inherit ambient SOCKET_* today #823; 8 of 10 hermetic since Spawn CLI test children through one hermetic Command builder (#823) #850; the last two are unblocked (Fix vlt 1.3 brotli lock nodes being refused (#372) #820, Fix vendored gem rewrite breaking positional args (#847) #849, Fix store-copy fold dropping copy writes (#756, #772) #774 merged)). C30 · filed Tracking: share CLI test helpers through one test-support module instead of 100+ per-file copies #824, Spawn every CLI test child through one hermetic Command builder; 10 test files inherit ambient SOCKET_* today #823; Spawn every CLI test child through one hermetic Command builder; 10 test files inherit ambient SOCKET_* today #823 slice 1 merged as Spawn CLI test children through one hermetic Command builder (#823) #850 (common/hermetic.rs, 8 of 15 scrub_socket_env copies deleted); slice 2 is the other 7
• vex_pdm_hatch_common and vex_pipenv_pip_common share 977 identical non-blank lines (78% similar).

Coverage-chasing tests.

• 32 covgap_*/coverage_fix_* files hold 27,570 lines and 415 tests (on c5be5d1; the review counted 26,916 and 402). C32 · to verify; counts confirmed, not filed 136 of those test names are about human output (human, message, prints, summary, …).
• 43 test files import socket_patch_cli::commands::* internals, which only works because lib.rs makes commands pub.
• The coverage job does not gate anything ("No threshold gating").
• In fairness, the sweep that produced them found 39 real bugs (Coverage audit: 39 bug fixes + test extension to 98.2% line coverage #236). Keep the regressions, rename them by behavior, and drop the rest.

Exact human-text assertions. 328 .contains("…") assertions pin sentences of four or more words, for example "[dry-run] Would download and vendor 0 of 1 patch (1 would be refused). No changes made.". The repo has no snapshot tooling. The output-polish PR (#248) had to touch 65 test files (4,346 lines).

Process-global env forces serialization. args.rs mirrors flags into process env (see Part 2.5), so in-process tests carry 993 #[serial] attributes (185 more in src, on 045d7ec; the review counted 553) and 29 test files call set_var. That is the main obstacle to merging binaries. CI uses no nextest, mold/lld or sccache.

8.2 CI cost

For 2463257 on main:

• CI workflow: 237 jobs and 348 runner-minutes over 31.9 minutes of wall time.
• Critical path: test (windows-latest) at 28.1 min (still about 28 min on 2026-10-07). Ubuntu took 14.0 and macOS 20.0. Give the CI test job 50 minutes so Windows can finish #278 raised the Windows timeout from 35 to 50 minutes.
• Repeated compiles: every PR compiled the full test tree 8 times at the snapshot: test ×3 (×2 on 2026-10-07), test-release, coverage, and e2e-build ×3 (with --all-features, which is another feature set).
• test also runs cargo build --workspace, which builds the napi addon on all three OSes for no test benefit.

About 516 jobs per push across all workflows:

Workflow	Jobs	Wall
CI	237	31.9 m
vlt	88	12.7 m
bun	52	24.1 m
pdm	44
poetry	30
pnpm	26
composer	18
npm	~11
go	~6
pipenv	~3

• The PR e2e matrix has 157 legs on 2026-10-07 (148 at the snapshot: 108 ubuntu, 23 macOS, 17 windows). They total 99 runner-minutes at about 40 seconds each, so scheduling overhead dominates. Most legs are version sweeps: vlt 35, bun 20, maven 17, ruby 14, uv 10. An e2e-full off-PR tier already exists.

• Coverage instrumentation runs on every PR, but the coverage legs are not only report-only: on 2026-10-07 the coverage job is where the gating Linux tests run (ci.yml:232-236, 425-431, 497-503), and coverage-docker is the only per-PR Docker e2e run (ci.yml:574-588; e2e-docker is nightly). Moving them off PRs would delete those gates.

  • coverage 11.7 min;
  • coverage-docker ×9, 56 min;
  • docker-base 5.3 min, which compiles a full-LTO binary that the PR consumer then overrides;
  • coverage-merge.

  That is ≈74 runner-minutes (21% of the run); the instrumentation overhead, not the tests, is the cost to cut.

• Nine *-compatibility.yml files at the snapshot (eleven on 2026-10-07; 2,041 lines then) re-implement the same shape: build, upload, download, install a pinned package manager, run.

  • The same inline Python "copy executables from cargo --message-format=json" snippet appears four times, and scripts/ci-e2e-bundle.py is a fifth copy.
  • go, composer and pipenv compile on every leg instead of building once: 25 per-leg compiles.

• Path filters: 204 hand-maintained patterns, two of them dead (they reference files deleted in v5 prerelease: scan → vex → vendor workflow, hosted by default #277).

• vlt is disproportionate:

  • about 123 jobs per push;
  • 6,079 lines of vlt-only workflows, scripts, docs and manifests, plus a watchdog workflow;
  • 15,943 lines of vlt tests and 727 fixture files.

  For comparison, npm compatibility is 11 jobs.

• Hygiene:

  • Toolchains and actions are well pinned (SHA-pinned actions, enforced by pin-check.yml).
  • But .github/actions/actions/cache/0057852b…/.vscode/launch.json is a stray Jest launch config from the actions/cache repo, accidentally committed in Keep Composer redirects and rollback consistent #358 and referenced by nothing. C08 · filed Delete the stray actions/cache launch.json and replace the 39 dangling "DESIGN §" citations #649; README part already fixed
  • scripts/ci-e2e-bundle.py imports a YAML parser from a test file.

8.3 Docs

CLI_CONTRACT.md is not maintainable as written.

• Size: 2,145 lines and 415 KB on c5be5d1 (1,638 and 332 KB at the review). 58 lines exceed 1,000 characters, 14 exceed 3,000, and the longest is 12,077 characters (line 166). C33 · filed Tracking: make CLI_CONTRACT.md a checked reference plus short prose #948, Pin CLI_CONTRACT.md's argument and env-var tables to Cli::command() with a freshness test #949; tracking Tracking: make CLI_CONTRACT.md a checked reference plus short prose #948 (folds in SOCKET_API_CONCURRENCY and SOCKET_WALK_THREADS are undocumented, and no test keeps core-read env vars in CLI_CONTRACT.md #678, Tracking: emit every --json error code from one typed ErrorCode registry checked against the contract tables #930), child 1 Pin CLI_CONTRACT.md's argument and env-var tables to Cli::command() with a freshness test #949
• History mixed into reference: 155 lines carry a v5.0 annotation and 29 a MAJOR/BREAKING marker (counted per line on 9c43dfc).
• Stale: "Migration status (v3.0)" still promises a follow-up PR.
• Misordered: "Vendored JVM support (v5)" sits after "How the contract is enforced".
• Drift from the code:
  • One documented code no longer exists in src: vendor_lock_checksums_unsupported.
  • Undocumented codes: on 9c43dfc, 43 code-shaped literals in emitting positions appear nowhere in the contract, among them rollback_not_installed, vendor_service_unsupported_ecosystem, hosted_restore_failed, invalid_manifest and the redirect_composer_*/redirect_pnpm_*/redirect_requirements_* families. C13 · filed Tracking: emit every --json error code from one typed ErrorCode registry checked against the contract tables #930, An unparseable .socket/manifest.json is reported under five different --json error codes depending on the command #931; tracking Tracking: emit every --json error code from one typed ErrorCode registry checked against the contract tables #930, child 1 An unparseable .socket/manifest.json is reported under five different --json error codes depending on the command #931 (manifest mapper)
  • Only the vlt codes (scripts/tests/test_vlt_coverage.py) and the Gradle/JVM codes (tests/contract_gradle_codes.rs) are checked mechanically. "How the contract is enforced" credits the cli_parse_* tests, which assert the parser, not the document.
  • The argument and env-var tables match --help on 9c43dfc, except that four SOCKET_VEX_* names are only abbreviated in the env table. Nothing pins them, and the scrub list LOCAL_ARG_ENV_VARS lacks SOCKET_NO_SOCKET_YML and SOCKET_MIN_SEVERITY. C33 · filed Tracking: make CLI_CONTRACT.md a checked reference plus short prose #948, Pin CLI_CONTRACT.md's argument and env-var tables to Cli::command() with a freshness test #949; tracking Tracking: make CLI_CONTRACT.md a checked reference plus short prose #948 (folds in SOCKET_API_CONCURRENCY and SOCKET_WALK_THREADS are undocumented, and no test keeps core-read env vars in CLI_CONTRACT.md #678, Tracking: emit every --json error code from one typed ErrorCode registry checked against the contract tables #930), child 1 Pin CLI_CONTRACT.md's argument and env-var tables to Cli::command() with a freshness test #949

User docs are lean, with rough spots.

• The good: README.md (6.7 KB) has a clear scan → install → vex flow, and usage.md, configuration.md and migrating-to-v5.md are well scoped.
• README.md documents the v5 prerelease while the one-line installer installs the latest release (v4.0.0). A note discloses this, but a new user can easily read about behavior they won't get.
• docs/ecosystems.md has single table cells of 1,382 and 1,827 characters, and vlt alone takes 138 of its 579 lines.
• 39 references in 20 files point to a "DESIGN §x.y" document that is not in this repository (recounted on 045d7ec). C08 · filed Delete the stray actions/cache launch.json and replace the 39 dangling "DESIGN §" citations #649; README part already fixed

docs/testing/* doubles as test input. vlt-compatibility.md tables are parsed by scripts/check-vlt-legs.py, which produces tests/vlt-leg-manifest.json, which a Python test checks against the doc. vlt-coverage.json maps codes to Rust test function names, so renaming a test breaks a Python test that reads a JSON file under docs/.

8.4 Scripts and distribution

• Scripts:
  • 12,349 lines of Python, 8,569 of them in six backtest-*.py harnesses with little shared code. backtest-uv.py (1,474 lines) and probe-uv-boundaries.py are run by no workflow.
  • 2,646 lines of TypeScript Claude-agent sweep harnesses. Three of them are referenced by no doc or workflow.
  • The perf harness (scripts/perf) is small, documented and valuable. Keep it.
• Distribution:
  • 14 per-platform npm packages plus the wrapper (15 in total), plus a private napi package that is built and smoke-tested on every PR (2.7 min) but never released.
  • The target list is repeated in at least 8 places: install.sh, release.yml, publish-npm.yml, the npm bin PLATFORMS, the wrapper's optionalDependencies, 14 package.json files, update/release.rs and commands/update.rs.
  • Release artifacts are never executed. 11 of the 14 targets never run a test anywhere.
  • scripts/version-sync.sh misses crates/socket-patch-node/npm/package.json.
  • The npm wrapper's zod manifest schema duplicates the Rust PatchManifest, lacks its setup field, and its test runs in no CI job.

8.5 Recommendations

#	Action	Impact	Risk
A	Merge 207 test executables into ~25. Finish the per-command directories; put the docker suites behind [[test]] required-features; group e2e by mode	Largest compile/link saving; shortens the 28-min Windows critical path; much smaller target/	Medium (the 553 #[serial] env tests must be fixed first; see Part 2.5)
B	De-instrument, don't move: keep the gating Linux tests and the per-PR Docker e2e on PRs, run them without coverage instrumentation, and collect coverage on main/nightly; drop the LTO docker-base build that the PR consumer overrides	most of ≈74 runner-min per run	Low
C	Cut the PR e2e tier from 157 to ~50 legs (boundary versions only); move the vlt/bun sweeps to nightly	Up to ~200 fewer jobs per PR	Low–Med
D	A socket-patch-test-support dev crate: delete the 102 binary(), 84 git_sha256 and 14 divergent env scrubbers; merge the forked VEX helpers	~3–6K lines; hermeticity	Low
E	A reusable compat workflow plus a setup-pm composite action; no per-leg compiles; fix the dead path filters	~2,041 → ~900 workflow lines	Medium
F	C33 · filed #948, #949; tracking #948 (folds in #678, #930), child 1 #949 Split CLI_CONTRACT.md: a generated reference (flags from Cli::command(), env vars, an errorCode registry in code, exit codes) plus 300 lines or less of prose, with a freshness test	Fixes the measured drift	Low
G	Replace the 328 sentence assertions with --json/errorCode checks plus a few insta snapshots	Copy edits stop touching dozens of files	Low
H	Triage the 402 covgap tests: keep the regressions, drop the ~136 output-text cases, stop importing pub internals	~8–12K lines	Medium
I	Decouple docs/testing from validation: data in tests/specs/, generate markdown from it; fix or remove the 39 "DESIGN §" refs	Lower coupling	Low
J	Hygiene: delete the stray .vscode; single targets table; --version smoke test on release artifacts; fix version-sync.sh; run or generate the zod schema test; move the agent-sweep scripts to tools/; path-filter the node-addon job	Prevents silent release drift	Low

New findings since the review

• C67 · in PR Run CI on the merge queue and stop cancelling main push runs #1018; digest entries fixed (Fix main CI red on stale digest pending-list entries #1016); a ruleset with required checks and a merge queue needs org admin October 7: main went red for every PR because three stale PENDING_INLINE_DIGESTS entries tripped a two-sided ratchet after a merge burst (fixed by Fix main CI red on stale digest pending-list entries #1016). Nothing required checks on main, and push CI cancelled about 87% of main verdicts; Run CI on the merge queue and stop cancelling main push runs #1018 runs CI on a merge queue with per-SHA push concurrency (the ruleset itself needs an org admin).

• C66 · in PR Keep test children off production telemetry and fail e2e legs that run no tests #1046 October 7: test children sent telemetry to production, the e2e zero-tests guard covered Gradle only, and the Windows npm leg ran nothing (PR Keep test children off production telemetry and fail e2e legs that run no tests #1046).

• C56 · filed apply, apply --check and vendor report noManifest (exit 0) when .socket/manifest.json exists but can't be stat'd #998 C57 · in PR Replace a superseded patch generation's wiring on re-pin and remove #1035 Known bugs are pinned as #[ignore = "RED: …"] tests with no issue and no CI leg: Fix PyPI vendored→hosted takeover stranding unreachable pins (#699) #708 added two (apply_with_unreadable_socket_dir_fails_closed, remove_by_uuid_reverts_vendoring_when_ledger_generation_is_older); both bugs reproduce on 9c43dfc and are now filed. A third ignored test, crawler_monorepo_gaps, documents a contract gap. A RED test should land with its issue number in the ignore reason.

• C47 · filed Spawn every CLI test child through one hermetic Command builder; 10 test files inherit ambient SOCKET_* today #823; 8 of 10 hermetic since Spawn CLI test children through one hermetic Command builder (#823) #850; the last two are unblocked (Fix vlt 1.3 brotli lock nodes being refused (#372) #820, Fix vendored gem rewrite breaking positional args (#847) #849, Fix store-copy fold dropping copy writes (#756, #772) #774 merged) Test files that spawned the CLI with no SOCKET_* scrub: on 045d7ec an ambient SOCKET_DRY_RUN=true or SOCKET_OFFLINE=true turned 18 of the 19 repair_vendor_e2e tests red. Since Spawn CLI test children through one hermetic Command builder (#823) #850, 8 of the 10 spawn through the hermetic common/hermetic.rs builder, and the spawn_env_hygiene ratchet fails on a new bare spawn. scan_invariants and in_process_npm_multicopy remain.

• C38 · filed The public-proxy per-package fallback runs 10 requests in flight, ignoring SOCKET_API_CONCURRENCY and the proxy cap of 4 #614, SOCKET_API_CONCURRENCY and SOCKET_WALK_THREADS are undocumented, and no test keeps core-read env vars in CLI_CONTRACT.md #678 Env vars that core reads directly have no documentation guard: SOCKET_API_CONCURRENCY (the operator throttle for the patch API) and SOCKET_WALK_THREADS appear in no doc. Only clap-bound vars are checked, through GLOBAL_ARG_ENV_VARS/LOCAL_ARG_ENV_VARS. It is the env-var slice of 8.5 F.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

[agent] Part 9 of 9 of the living socket-patch architecture document. The summary and ranked recommendations are in the top post. Originally written against 2463257; the routines update this part as the code changes.

Appendix A: The open-issue backlog, mapped to architecture

Last checked against main @ 431b818 on 2026-10-07 by the October 7 reconciliation (backlog shape only; the tables below are still the 2463257 snapshot). Owner: audit-core and audit-ecosystems.

Status on 2026-10-07: about 304 issues are open (~194 bughunt, ~94 arch-audit). 51 of the 88 issues below are now closed, and 162 of the 194 open bughunt issues are not mapped in this appendix. JVM now has 34 open Maven issues plus 2 Gradle. Priority labels follow the maintainers' ecosystem triage (Maven and NuGet below Composer, Go and Cargo), which is intended. The register rows E70–E88 and C59–C73 map the clusters the October 7 audit found.

The repository had 88 open issues when this review was written. Most were filed between 2026-09-26 and 2026-10-01 by a bug hunt (bughunt label). They are classified below by title into the architectural cause they point to. The classification is the reviewer's judgment and is approximate. Several issues fit more than one bucket; each is listed once, under its dominant cause.

By ecosystem

Ecosystem	Open	Share	Notes
JS (npm, pnpm, yarn, bun, vlt, deno)	26	30%
JVM (Maven, Gradle)	22	25%	Disproportionate to usage: JVM is ~9K production lines out of 118K
Python (pip, uv, pdm, pipenv, poetry, hatch)	18	20%
Go	6	7%
Cargo	5	6%
NuGet	5	6%
Ruby	3	3%
Composer	3	3%

By architectural cause

#	Cause	Count	Issues	Structural fix (see main post)
A	Success or not_affected claimed from what we wrote, not from what the package manager consumes	29	#409, #406, #405, #397, #396, #395, #394, #393, #392, #391, #390, #387, #367, #356, #352, #350, #341, #339, #338, #336, #335, #326, #325, #272, #265, #263, #261, #260, #258	§2.2: VEX requires consumed evidence by default; check after install; fail closed on configuration we don't model
B	Discovery re-implements the package manager's install layout or resolution and misses copies (exit 0, unpatched)	15	#412, #398, #384, #374, #373, #366, #362, #361, #359, #349, #334, #332, #329, #327, #264	§2.2: ask the package manager (poetry env info -p, pipenv --venv, pnpm list --json, npm query, …); project-scoped locators (Part 6)
C	Rewrites that break installs because package-manager semantics aren't modeled (including new lock-format revisions refused, e.g. #372)	16	#403, #386, #372, #371, #368, #364, #363, #360, #355, #354, #353, #347, #346, #344, #343, #333	Same as above, plus refusing on unmodeled configuration
D	Hand-rolled text surgery corrupts or reformats user files	12	#402, #400, #376, #370, #351, #348, #342, #340, #324, #273, #262, #259	Recommendation 1: one codec per format with byte spans and a single line-ending, indent and comment policy
E	Reversal and mode takeover (upstream restore, revert, re-pin)	13	#411, #410, #408, #407, #401, #385, #382, #369, #331, #328, #271, #266, #274	Recommendation 4: an originals sidecar or narrowed restore; recommendation 2: one revert engine
F	Credentials sent to the patch host	2	#404 (yarn berry sends the npm auth token), #399 (composer transport-options auth headers)	Hosted rewrites should strip or scope per-entry auth config. This is worth a dedicated security review of every hosted rewriter.
G	CI matrix gaps	1	#267	—

What the backlog says about the design:

• About two-thirds of the backlog (A + B + C = 60) is one problem: the tool's model of the package manager diverges from the package manager's behavior, and the tool trusts its model. More per-package-manager special cases make that model bigger, and every new special case is another place to diverge. The leverage is in (i) verifying outcomes against what the package manager actually consumes, and (ii) delegating layout and resolution questions to the package manager wherever it can answer them.
• D and E (25 issues) are what you get from parsing each format several times with different rules and from reconstructing originals instead of recording them. Both have direct structural fixes, listed above.
• Re-triage needed:
  • Composer setup rewrites a CRLF composer.json as LF (and un-escapes \/ and \uXXXX), so setup --remove does not restore it byte-for-byte #351, Gem hosted redirect and setup ignore BUNDLE_GEMFILE from .bundle/config, so they wire Gemfile while bundler loads the configured manifest unpatched (VEX and setup --check still pass) #390 and npm apply exits 1 when every patch targets a platform-skipped optional dependency (fsevents, @esbuild/*), so the setup hook fails npm ci and npm install on other OSes #403 describe the setup command and setup hooks, which v5 prerelease: scan → vex → vendor workflow, hosted by default #277 removed. Parts of them may be obsolete; the apply exit-code part of npm apply exits 1 when every patch targets a platform-skipped optional dependency (fsevents, @esbuild/*), so the setup hook fails npm ci and npm install on other OSes #403 probably is not.
  • Hosted Maven Trusted Checksums are silently inert on Maven 3.9.0–3.9.3 (docs and the test gate claim ≥3.9 enforces) #258–Same-GAV Maven patches are shadowed when a build plugin depends on the same GAV in a reactor build #274 predate v5 prerelease: scan → vex → vendor workflow, hosted by default #277 and should be re-checked against main.

---

Appendix B: Methodology and measurement notes

Sizing.

• Each .rs file was split into production and test code by lexing it (strings, chars and comments blanked so braces inside them are ignored). Every #[cfg(test)] item was masked, and files that are test-only by name were excluded: *_tests.rs, tests.rs, test_support*, testing/, golden.rs, test_rng.rs.
• Result: 117,630 code, 34,764 comment and 9,051 blank production lines; 4,369 production functions (median 13 lines; 201 over 100 lines; 61 over 200 lines; 27 over 300 lines).
• Per-area reviewers used the same "split at the first top-level #[cfg(test)] mod" convention, so their production numbers include comment lines.

Function lengths come from brace matching over that lexed text: start line to closing brace. They can be off by a few lines but are not affected by braces inside string literals.

Duplicates were found three ways:

1. Function names defined in several files (restore in 16 files, crawl_all/find_by_purls in 15, preflight_packages in 9, service_preflight in 8, read_project in 7, sha256_hex in 5).
2. A diff of the candidate pairs.
3. A sliding-window copy-paste detector, which found little literal duplication. The duplication in this codebase is structural (parallel pipelines over shared helpers), not copy-paste.

CLI surface was measured on a debug build: --help line counts per subcommand; JSON error shapes for remove, rollback, scan --offline, get --offline, repair and vex; silent acceptance of unused globals.

CI numbers are from the GitHub Actions run for 2463257 on main (CI workflow run 36798097960), plus the matrix definitions for workflows whose runs were not fetched.

Verified by hand (not just reported by an area reviewer):

• the unbounded zip inflate and its callers;
• no timeout on ApiClient/plain_client;
• the takeover ignoring kept_artifact;
• the bare hatch spawn and the project's own rule against it;
• the comment-blind nuget_package_source_keys;
• SOCKET_FORCE on three flags (removed per Decide: give SOCKET_FORCE per-command names so forcing a self-update doesn't also force apply and vendor #615);
• --download-mode diff re-fetching all blobs when any archive is missing;
• mem_blobs never Some in production;
• wired_vendor_integrity with no production caller;
• apply_env_toggles and its documented token-leak history;
• the inconsistent JSON error shapes (binary output);
• the global flags on list --help;
• severity_order delegation;
• the duplicated sha256_hex/sha1_hex helpers.

Not verified by execution: the per-area reviewers' "probable bug" readings beyond those listed (they are labelled as such in each part), and every LOC savings estimate. Those are engineering estimates, not measurements.

Read-only: no code was changed. The review text lives under docs/reviews/2026-10-architecture-review/ on branch claude/wonderful-bardeen-g5cw88.

---

Generated by Claude Code

[github-actions[bot]]

[agent] 2026-10-02: the architecture routines are set up

This discussion holds the October 2026 architecture review: the top post, plus Parts 2–9 above. It is also the running log of the refactoring work.

• Register: the first comment, regenerated from register/ on the arch-audit/ledger branch on every push. It is seeded from the review with 48 ecosystem rows (E01–E48) and 36 CLI/core rows (C01–C36). Every row stays to verify until a routine re-checks it on the current main.

• Routines (Claude Code routines, Opus 5.5):

  Routine	Schedule (UTC)	Does
  socket-patch architecture audit: ecosystems and formats	every 6 h at :40 (00, 06, 12, 18)	formats, hosted, vendored, discovery, VEX
  socket-patch architecture audit: CLI and core	every 6 h at :40 (03, 09, 15, 21)	CLI layer, core infrastructure, agent mode, tests, docs
  socket-patch architecture refactor	every 4 h at :45 (01, 05, …, 21)	implements refactor issues one small PR at a time, at most 3 open

• Audit runs: each run re-checks the next review items on main and files them as discrete issues labelled arch-audit plus refactor or bug. It also hunts for at least one new instance of duplicated or inconsistent logic, then posts an entry here.

• Decisions: questions for owners are filed as "Decide: …" issues labelled agent:needs-human.

• Existing routines: the hourly fixer may pick up the bug issues. The PR burn-down routine shepherds the refactor PRs once they are ready.

---

Generated by Claude Code

[github-actions[bot]]

[agent] 2026-10-02: architecture audit (ecosystems and formats)

main @ d63ae5f. This is the first audit run. No arch-audit issues existed yet, and the discussion had no maintainer input beyond the review itself.

Verified on main, each reproduced with a unit test run twice. The probe tests were not committed.

• E01 is still present. nuget_package_source_keys counts a commented-out <add key> as a source, so nuget.org is not seeded and * is mapped to an undefined key. formats::nuget::parse_config returns no sources for the same input. Filed Hosted NuGet mapping reads commented-out package sources #561 (bug, pm:nuget).
• E03 is still present. The two registry_base functions disagree: when both registry and registries.npm are set, the inventory picks registry and hosted restore picks registries.npm. For an unmapped alias the inventory returns None, while restore falls back to registry, then npmjs. Filed vlt lock inventory and hosted restore resolve a node's registry differently #562 (bug, pm:vlt), which also absorbs E02's duplicate tarball-URL and NPM_REGISTRY spellings. Cross-linked from vlt hosted rollback and remove rewrite slot [3] to a synthesized /<name>/-/<leaf>-<ver>.tgz URL instead of the registry's dist.tarball, so the next cold vlt ci 404s #521.
• E02 is partly not a defect. The bun.lockb format-1 URL is lock semantics and is never fetched, and SOCKET_NPM_REGISTRY is an undocumented knob of the restore client. The rest was folded into vlt lock inventory and hosted restore resolve a node's registry differently #562.
• E04 is still present. Vendored Pipenv's is_socket_hosted_reference accepts https://evil.example/patch/pypi/…, while hosted_patch_uuid rejects it. Filed with E49 as Pipenv recognizes hosted PyPI patch URLs with two private grammars that disagree with the shared one #563 (bug, pm:pipenv).

New finding: E49. There are four hosted-PyPI-URL grammars. Hosted Pipenv's owned_url requires exactly 8 path segments and a .whl leaf. On a path-prefixed --patch-server-url (https://host/socket/patch/pypi/…), owned_url rejects the URL it just wrote, and re-planning returns Conflict("Pipenv source for urllib3 already exists"). hosted_artifact_url, used by inventory and VEX, accepts the same URL. This is part of #563.

Searched without filing:

• parse_dir_name_version: cargo and ruby use legitimately different rules.
• url_host: hosted/guidance and upstream/uv differ only in case-folding, and no caller is affected.
• is_dev_version: composer upstream and VEX differ only on a #commit suffix that lock version fields don't carry.
• NuGet config file-name lists exist in 4 copies (redirect::NUGET_CONFIG_FILE_NAMES, vendor::nuget_config::CONFIG_NAMES, hosted/memory/roots.rs, formats/registry.rs). They have not drifted, so this goes to E11. nuget_crawler's case-insensitive gate is only a crawl gate.
• actual_integrity ×3 is test-only.

Next backlog rows: E05 (cache crawls not project-scoped), E06 (non-FIFO-safe crawler reads), E07 (package-lock walks), E08 (yarn grammars), E09 (berry gates).

---

Generated by Claude Code

[github-actions[bot]]

[agent] 2026-10-02: this discussion is now a living document

• Living text: the top post and Parts 2–9 are rendered from doc/ on the arch-audit/ledger branch on every push. They are kept true of current main: when a refactor lands or a new problem is found, the routines rewrite the passage it affects. Each part says when it was last checked against main and ends with a "New findings since the review" section. The original snapshot stays in review/2026-10/.
• Live statuses: every E…/C… reference in the text, including the new Status columns of the §1 fix-now and §3 recommendations tables, renders that problem's current status from the register. The progress line at the top counts the register and the open/closed issues and PRs on GitHub.
• Auditors: audit-ecosystems and audit-core now keep their parts of the living document current as well as their register rows.
• New hourly refactor routine: socket-patch architecture refactor: highest leverage (hourly) runs at :55 every hour until the backlog is burned down. Each run ranks every open register row and arch-audit/refactor issue by leverage: bugs closed, other work unblocked and duplicate code removed, weighed against risk and size. It implements the top item as a PR against main, keeps at most 3 PRs open, and records its ranking in the register. It replaces the earlier 4-hourly refactor routine, which is now disabled so the two don't compete for the same work.

---

Generated by Claude Code

[github-actions[bot]]

[agent] 2026-10-02: architecture audit (CLI and core)

main @ 1169ae6. This is the first audit-core run. There were no maintainer replies in the discussion beyond the review itself, and there were no open arch-audit issues in this area to reconcile.

Verified on main. Every bug below was reproduced twice by execution. The probes were not committed.

• C03 is still present. A real yarn classic install of left-pad@1.3.0 is vendored offline, and one recorded lock block is made to no longer exist, which is the drift-keep trigger. The control run, vendor --revert, keeps the ledger entry and the artifact and reports vendor_artifact_kept. scan --mode hosted instead drops the ledger entry, leaves .socket/vendor/npm/<uuid> behind, and reports redirect_takeover_reverted_vendored ("reverted … committed artifact"). Filed #568.
• C01 is still present. A 696 KiB zip holding a 700 MiB deflated entry raises peak RSS from 21 MiB to 726 MiB inside zip_bytes_match_after_hashes. Two capped copies of the same entry read exist in vendor/mod.rs, so the three copies have drifted. Filed #569. Unifying the 512/256/128 MiB archive caps is left to C15/C21.
• C02 is still present. Against a server that accepts and never answers, fetch_patch and fetch_blob were still pending after 120 s. Filed #570. Retry for blob/diff stays in C15.

New finding: C37. fetch_binary (blob and diff) reads the body with resp.bytes() and no cap, while the vendor-package, artifact and self-update downloads use the shared utils::http::read_capped. A 600 MiB blob response was buffered in full (Ok(len = 629145600)). Filed #571.

Searched without filing:

• The other zip/tar read_to_end sites in vendor/ (reuse.rs, verify.rs, mod.rs:1161) are already capped. berry_zip.rs:215 reads tar entries in the sibling's area and was not checked further.
• C04 (hatch bare-name spawn) is still at vendor/pypi_hatch.rs:118. Open PR Fix global PM probes spawning bare names from the project (#421, #434, #438, #440) #442 covers the global PM probes but not hatch. This is the next row to verify.

Living document: check lines set on Parts 2 and 7, tokens added for C02/C03, a C37 bullet under Part 7's new findings, and the cheap §0 numbers refreshed (209 test executables, redirect/mod.rs 18,154 lines, CLI_CONTRACT.md 340 KB, 156 open issues).

Next backlog rows: C04 (hatch spawn, vs #442), C05 (SOCKET_FORCE), C06 (get argument round-trip), C07 (URL builders disagree on org fallback), C08 (repo hygiene).

---

Generated by Claude Code

[github-actions[bot]]

[agent] 2026-10-02: architecture refactor run

main @ 1169ae6. This is the first refactor run. Nothing had merged yet, there was nothing to resume, and the discussion had no maintainer steering.

Ranking. #563 (E04, E49) won with a score of 5: B=1 (p1), D=2 (two private hosted-PyPI-URL grammars), risk L, and no file overlap with open PRs.

• #561 scored higher (6) but was skipped: it would change redirect/mod.rs, which four open PRs (Fix Gemfile rewrites duplicating gem declarations (#482, #548) #552, Fix npm overrides of git deps being refused (#490) #491, Fix berry mode takeover reverting before gates (#468, #369) #470, Fix yarn berry hosted pin leaking npm auth (#404) #465) also change.
• #562 tied on 5 but carries M risk, because restore has to fail closed with a new code.

The full top five is in the register's Queue.

PR. #572 adds lock_inventory::pypi::hosted_pypi_reference (the hosted_patch_url_uuids origin policy plus the hosted_artifact_url tail grammar).

• Hosted owned_url and the vendored Pipenv guard now use it, and the vendored guard gets the run's --patch-server-url origin.
• Both segment-count grammars are deleted: production +31 / −48.
• Red→green tests cover both former callers.
• Clippy is clean. The core lib suite and the Pipenv and hosted-memory CLI suites are green, apart from the 4 root-sandbox failures that also fail on main.
• State: ready. Bugbot has been requested, and the PR is handed to the burn-down routine.

Claimed: #563 (agent:claimed). Released: none.

Living document: added the {{E04}} token to Part 5.4. E04 and E49 are now in PR #572. The prose gets rewritten after the merge.

Lessons: the four root-only test failures, and the rustfmt state of the files touched (see Notes).

[github-actions[bot]]

[agent] 2026-10-02T16:27Z: architecture refactor run

• main: 1169ae6.
• Ranking: Hosted NuGet mapping reads commented-out package sources #561 scored highest (7) but would change crates/socket-patch-core/src/patch/redirect/mod.rs, which open fix PRs Fix Gemfile rewrites duplicating gem declarations (#482, #548) #552, Fix npm overrides of git deps being refused (#490) #491, Fix berry mode takeover reverting before gates (#468, #369) #470 and Fix yarn berry hosted pin leaking npm auth (#404) #465 change, so it was skipped. vlt lock inventory and hosted restore resolve a node's registry differently #562, zip_bytes_match_after_hashes inflates committed .nupkg/.jar entries with no size cap #569 and Patch blob and diff downloads buffer the whole response body with no size cap #571 tied at 4; vlt lock inventory and hosted restore resolve a node's registry differently #562 won on the oldest issue (p1, collapses two registry_base copies, an inline tarball URL and a second NPM_REGISTRY). Pipenv recognizes hosted PyPI patch URLs with two private grammars that disagree with the shared one #563 is already in #572, in progress by another run.
• PR: #574, "Resolve vlt registry bases through one shared function (vlt lock inventory and hosted restore resolve a node's registry differently #562)". It is ready for review, @bugbot review was requested, and the burn-down routine takes over. The shared function follows vlt's own DepID hydration (@vltpkg/dep-id 1.3.5 and @vltpkg/spec 1.3.5). One table test runs both former callers; both caller tests are red on main and green on the branch.
• Claimed: vlt lock inventory and hosted restore resolve a node's registry differently #562. Released: none.
• Merged: none. Living document: status tokens {{E03}} and {{E02}} added in Part 4.4. Register rows E02 and E03 are now → in PR #574.
• Lessons: restore only reaches registry_base for default-registry segments, so the issue's "refuse an unmapped alias" criterion was already met by the is_default_registry gate; the PR keeps an explicit fail-closed branch. scoped-registries (which vlt checks first) is read by neither copy, and is left for a later finding.

[github-actions[bot]]

[agent] 2026-10-07: architecture audit (ecosystems and formats)

main @ 9c43dfc, unchanged since the last run. There were no new maintainer replies in the discussion and no handovers for this routine.

Reconciled.

• No status changed: E09/E51 are still in Fix yarn berry project gates drifting between modes (#628, #629) #657 and E64 is still in Fix pnpm lock/workspace readers missing a BOM (#903, #904, #905) #909. Nothing in this area merged.
• With main unchanged, re-checking open issues would only repeat last run's permalinks, so I skipped it.

Verified and filed: E26 → #971 (tracking), with #972 (child 1) and #973 (child 2, decision), both linked as sub-issues.

• vendor_maven sends a lone single-module pom to the legacy same-GAV <repository> backend only because Detected::shape maps it to Shape::Other. Shape::Mixed already plans the same pom through maven_reactor::plan.
• Proof: a throwaway maven_reactor test, run twice on 9c43dfc, planned a lone CRLF single-module pom (detect = Other) with no warnings. Re-planning wrote nothing, and unplan restored pom.xml byte for byte and removed .mvn/maven.config.
• About 1,170 raw lines of maven_repo.rs (L693–L1866) are the v5 JVM orchestrator and the Maven download layer. redownload.rs, agent-mode jvm_jar.rs and VEX import them from there.
• The "jvm" ↔ "maven" alias is still special-cased at the CLI revert match, path.rs:92, redownload.rs (×5) and the hosted takeover's gradle_jvm_entry.
• Move the v5 JVM vendor orchestration and Maven acquisition out of maven_repo.rs into vendor/jvm #972 is a pure move into vendor/jvm/{vendor,fetch}.rs, to land after Bound registry downloads by ApiTimeouts instead of a 60 s total deadline (#872) #876. Decide: vendor single-module Maven poms through the suffixed-version jvm planner and retire the same-GAV <repository> wiring #973 asks whether new single-module vendors should use the suffixed planner, with legacy entries kept revert-only (recommended).
• I commented once on each symptom issue: #263, #274 and #622. Vendored Maven refuses a single-module EAR pom as a multi-module aggregator because two declares_modules disagree #716 (E55) is already an arch-audit issue and is listed in Tracking: vendor every Maven shape through the jvm planner and retire the legacy single-pom backend #971.

New finding: none met the bar this run. I searched:

• Hosted composer.lock locator: find_composer_entry / json_string_field match the literal "name": ", while vendored and inventory parse JSON. Composer always writes that spacing, and the module doc states the assumption, so there's no reachable drift.
• "Is this crates.io" predicates: the vendored lock_source_refusal uses exact equality on two strings, and formats::cargo uses substring contains (it only feeds VEX resolves_elsewhere). Hosted refuses other registries and git at the manifest. I found no reachable disagreement.
• Go: the module-path case encoding (encode_module_path) and goproxy_base are already shared by vendored and restore.
• NuGet: normalize_nuget_version is shared by vendored, restore and VEX. The lock-walk drift is already E50 (Hosted NuGet rewrites packages.lock.json entries at other versions of the patched id #593).
• VEX Maven: the JVM pin probe (jvm_tree) and maven_reactor::tree_dir build the same path (group.replace('.', "/")).
• --maven-config: clap validates auto|none.

False positives ruled out:

• I first suspected that vendor_dir_symlink for a "jvm" entry checks only .socket/vendor/maven/<uuid>. It also checks the maven2 and gradle trees (jvm::apply::VENDOR_TREES), so it isn't a gap.
• The local maven_repo::sha1_hex copy is Compute sha256, sha1 and sha512-SRI digests through utils::digest instead of inline copies #706 (audit-core).

Living document:

• Part 5 §5.7: the JVM bullet now says that the legacy backend wires an unsuffixed GAV, that the orchestrator lives in maven_repo.rs, and that the planner already handles single-module poms (executed). The merge bullet has {{E26}}.
• Part 5: the check line is updated.

Next backlog rows: E08 (yarn grammars; after #657), E14 (Pipfile.lock, still unproven), E24 (the nine revert mechanisms), E42 (embedded --vex glue; overlaps audit-core's decision #966, so it may become decision #966), E29 (registry_fetch.rs placement; overlaps #972's fetch.rs).

---

Generated by Claude Code

[github-actions[bot]]

[agent] 2026-10-07: architecture audit (CLI and core)

main @ 9c43dfc, unchanged since the previous five runs. There were no new maintainer comments in the discussion, and no handovers addressed to audit-core.

Reconciled: every register row holds its status. #876 (C49), #886 (C48) and #889 (#677, C15) are still open PRs, and nothing of ours merged. main hasn't moved, so I didn't re-check open issues against it.

Backlog decomposed:

• C36 → decision #983, "Decide: keep the --update binary swap, or replace it with the installer and keep only the update notifier". C36 is narrowed to self-update; the agent-mode half is the new row C55 (to verify).
  • Verified on 9c43dfc: self-update is 2,350 production lines (core update/ 1,579; commands/update.rs 416; update_notifier.rs 355), plus 2,369 inline and 2,634 external test lines. That matches the review's 2,351.
  • Only Standalone may swap. Release resolution has two strategies: a redirect probe, then the GitHub API. Download, SHA256SUMS check, stage, sanity-exec and atomic rename run under their own lock. This is the same trust model as install.sh.
  • What the review missed: install.sh has no Windows rows, and the README sends Windows zip users to --update. Replacing the swap with "re-run install.sh" therefore drops the Windows standalone channel's only updater. The issue recommends keeping the swap, with Tracking: one retry primitive for the patch API client (JSON, vendor service, blob and diff) #676 and Decide: give SOCKET_FORCE per-command names so forcing a self-update doesn't also force apply and vendor #615 carrying the engineering follow-ups.

New finding: C54 → #982 (bug, contract drift). The paid-plan refusal is documented but not emitted.

• CLI_CONTRACT.md lists status: "paidRequired" (L1092) and an errorCode row paid_required with action failed, status=paidRequired, for "get/scan" (L1163).
• get writes a legacy {"status":"paid_required","found",…} object from two hand-written blocks (search with nothing accessible; get <uuid> on the proxy), with no events and no errorCode.
• scan reports only the paidPatches/canAccessPaidPatches counts.
• Status::PaidRequired is constructed only in tests, and its doc comment already says nothing emits it.
• Proof: cargo test -p socket-patch-cli --test get paid ran twice: 4 passed both times. They pin status == "paid_required" and exit 0.

Searched without filing:

• CI detection: only update_notifier::in_ci.
• Telemetry disable gating: covered by C19 and C10.
• The self-update download's 300 s whole-request budget: the archive is small, so it isn't C49's practical failure. It is mentioned in Decide: keep the --update binary swap, or replace it with the installer and keep only the update notifier #983 as a Tracking: one retry primitive for the patch API client (JSON, vendor service, blob and diff) #676 follow-up.
• asset_name_for_target vs install.sh's platform table: they agree on every Unix triple. The binary keeps its compiled libc, so there is no musl drift.
• The tier filter: scan::select_accessible and get's filter are copies, but identical.

False positives ruled out:

• Status::NotFound and NoManifest looked unused too, but both have production callers (7 and 2).
• SOCKET_UPDATE_BASE_URL vs install.sh's SOCKET_PATCH_BASE_URL take different URL shapes, but docs/installer-hosting.md documents both. That's a documented difference, not a defect.

Living document:

• Summary: §0's open-issue row is refreshed for 2026-10-07 (319 open, 246 bug, 89 arch-audit). The other §0 numbers hold, since main is unchanged. §5's self-update row notes the Windows gap with {{C36}}, and the agent-mode row carries {{C55}}.
• Part 2: §2.8 has a paid-tier bullet, and {{C54}} is under new findings. The check line is dated 2026-10-07.
• Part 7: the 7.5 self-update row is re-measured, with the Windows note and {{C36}}. The check line is dated 2026-10-07.

Next backlog rows: C55 (agent-mode future decision), C34 (command-model decision; it assumes #966 is answered), then C31/C32 after #793.

---

Generated by Claude Code

[github-actions[bot]]

[agent] 2026-10-07: architecture audit (ecosystems and formats)

main @ 9c43dfc, unchanged since the last run. There were no new maintainer replies in the discussion and no handovers for this routine.

Reconciled.

• No status changed: E09/E51 are still in Fix yarn berry project gates drifting between modes (#628, #629) #657 and E64 is still in Fix pnpm lock/workspace readers missing a BOM (#903, #904, #905) #909. Nothing in this area merged.
• With main unchanged, re-checking open issues would only repeat last run's permalinks, so I skipped it.

Verified and filed: E24 → #989 (tracking) and #990 (child 1, linked as a sub-issue).

• Finish step: the dry-run → drift-keep → --preserve-state → remove_tree_and_prune sequence is written 12 times. It uses four keep policies, which CLI_CONTRACT.md documents:
  • unconditional drift-keep: gem, npm, pnpm, bun ×2;
  • keep while a live file still names the uuid dir: composer, maven legacy, nuget;
  • a post-revert "lock still mentions the uuid" refusal: yarn classic and berry;
  • pypi's drift-or-residual keep, with a warning-only removal failure.
• Record loop: the reverse wiring walk with its unknown-kind warning is copied in composer, gem, maven legacy and nuget.
• Atomic revert: only poetry and pdm have an all-or-nothing revert for coupled records.
• Other: requirements.txt speaks the undocumented vendor_revert_line_drifted, and cargo writes a cargo_lock_entry record that its revert never reads.
• Finish every vendored revert through one shared helper with an explicit keep policy instead of 12 copied finish blocks #990 replaces the 12 finish blocks with one helper that takes an explicit KeepPolicy. It is mechanical, with no policy or code change.
• I commented once on symptom #977.

New finding: E68, #988 (bug, pm:bundler).

• Vendored gem's forward hot path treats any Gemfile that contains the copy path as wired. revert_gemfile_record needs the exact recorded line. The gem records are reverted one by one, lock first.
• Proof: a throwaway vendor::gem test, run three times on 9c43dfc: vendor, then append # CVE fix, do not bump to the wired line.
  • Re-vendor reports in sync.
  • revert_gem returns success with vendor_lock_entry_drifted + vendor_artifact_kept.
  • Gemfile.lock is restored to the registry (the PATH section is gone), while the Gemfile keeps path:.
  • A second revert drift-keeps again.
• This is the same forward/revert recognizer split as Vendored requirements.txt can't be reverted once the user touches the # socket-patch vendor: comment: vendor --revert drift-keeps forever (exit 0), and the suggested "re-vendor" remedy is a no-op or adds a duplicate line #977, plus a half-revert. Fix uv vendored revert half-reverting after a relock (#806, #821) #822 fixed that half-revert class in uv.

Searched without filing:

• NuGet exact-id mapping tie: both writers (hosted add_nuget_source, vendored build_config_edit) append our exact-id pattern when another source already maps that id, while VEX's exclusive predicate (vex/discover/nuget.rs:127) treats the tie as dead. A throwaway test, run twice, confirmed both writers emit the tie with no warning. It is already open as Hosted/vendored NuGet mapping isn't exclusive when nuget.config already maps the exact package id to another source, so restore races the Socket feed against nuget.org (NU1403 with a lock, silently unpatched without one) #462, so not filed. A shared exclusivity predicate in formats::nuget would serve the writers and VEX alike.
• Go dirhash.Hash1: written twice, registry_fetch::go_h1_of_zip and upstream::client::go_mod_h1 (the single-file case). No drift, and too small to file alone.
• Composer leading-v rule: already E37 (Move the crawler coordinate guards and composer's leading-v rule into utils and delete the copies #630).

False positives ruled out:

• The four keep policies differ on purpose; CLI_CONTRACT.md documents each one. They are recorded as a later decision step in Tracking: revert every vendored backend through one record-revert engine instead of nine hand-written mechanisms #989 (checklist step 6), not as a bug.

Tooling note: the issue-write path wraps very long permalinks (about 150+ characters, e.g. yarn_classic_lock.rs#L…) in double backticks, which breaks the link (#971 shows the same thing). #989 was rewritten with short-SHA permalinks (/blob/9c43dfc/…), which GitHub resolves.

Living document:

• Part 5 §5.3: {{E24}} is next to the nine-mechanisms table, and a new bullet group covers the copied finish step and keep policies (Finish every vendored revert through one shared helper with an explicit keep policy instead of 12 copied finish blocks #990), the record loop and atomicity ({{E68}}), and the forward/revert recognizer split.
• Part 5: a new-findings bullet for {{E68}}; the check line is updated.
• Summary: {{E24}} is on the nine-revert-mechanisms line.
• The register files E24, adds E68, and trims the E62–E67 texts to stay under 20K characters.

Next backlog rows: E08 (yarn grammars; after #657), E14 (Pipfile.lock, still unproven), E42 (embedded --vex glue; may become decision #966), E29 (registry_fetch.rs placement; overlaps #972), E30 (mechanical redirect/mod.rs split).

---

Generated by Claude Code

[github-actions[bot]]

[agent] 2026-10-07: architecture audit (CLI and core)

main @ 9c43dfc, unchanged since the previous six runs. There were no new maintainer comments in the discussion, and no handovers addressed to audit-core.

Reconciled: every register row holds its status. #876 (C49), #886 (C48) and #889 (#677, C15) are still open PRs, and nothing of ours merged. main hasn't moved, so I didn't re-check open issues against it.

Backlog decomposed:

• C55 → decision #1000, "Decide: keep agent mode for every ecosystem, or limit it to Deno and --global installs". It recommends option B: keep the engine, and refuse project-scope --mode agent where hosted or vendored works.
  • Verified on 9c43dfc: every ecosystem except Deno has hosted and vendored support (docs/ecosystems.md matrix).
  • What the review missed: global installs are the other case only agent mode can serve. Go's agent mode is a .socket/go-patches/ replace, which vendored covers, so it isn't one of those cases.
  • About 29 open bug issues are agent-mode-specific, roughly double the review's ~15. CLI apply.rs is now 2,963 production lines (2,237 at the review), and the agent-only core is about 3.2K.
  • Correction to the living document: Part 7 said agent mode writes no Maven sidecar. Full Gradle support in agent, hosted and vendored modes #646 added sidecars/maven.rs, which rewrites .sha1/.md5, and the Gradle files-2.1 handling that fixed Agent-mode apply in a Gradle-only project patches the ~/.m2 copy Gradle never reads, reports success, and VEX attests not_affected while the build uses the unpatched ~/.gradle jar #551. Part 7.4 is rewritten accordingly.

New findings (both from #[ignore = "RED: …"] tests that #708 added with no issue and no CI leg):

• C56 → #998 (bug): five CLI commands probe the manifest with metadata().is_err() ahead of core's NotFound-only read_manifest.
  • apply, apply --check and vendor report noManifest with exit 0 when .socket is a file (ENOTDIR) or manifest.json is a looping symlink (ELOOP). repair, remove and rollback say manifest_not_found, while list and vendor --check say manifest_unreadable.
  • Proof: a debug build ran all ten command/fixture pairs twice under env -i, with identical results. The RED test's own fixture (chmod 000) self-skips as root, which is why I used these fixtures instead.
• C57 → #999 (bug): remove <uuid> matches the vendor ledger by the raw identifier, not by the manifest purls it deletes. With an older ledger generation, the manifest entry is removed, the vendoring stays and the status is success.
  • Proof: remove_by_uuid_reverts_vendoring_when_ledger_generation_is_older with --ignored failed twice on 9c43dfc. The by-purl control test passes.

Searched without filing:

• The --lock-timeout plumbing: every lock site honors it.
• File-lock primitives: two, apply_lock and the self-update lock, which is legitimately separate.
• Size caps in api//patch/: blob/diff bodies stream to disk since Stream patch blob and diff downloads to disk (#571) #607; diff archives cap entries at 16 MiB.
• --vendor-source: single-valued, already R8/C23.
• The identifier classifiers: remove/rollback compare a uuid case-sensitively while get accepts uppercase. That is the same family as Validate patch UUIDs through one utils::uuid grammar instead of five #705, so not filed separately.
• socket.yml loading: scan only, plus get's bypass warning, as the contract documents.
• vex -O writes in place without stage+rename. That's minor, and not filed.
• #[ignore] coverage: 2 RED tests and 1 gap test.

False positives ruled out:

• tests/<dir>/main.rs files looked like orphans, but they are cargo's directory test targets.
• Several #[ignore]d e2e suites looked unrun, but CI's e2e job runs -- --ignored by default and lists them in matrix suite strings. The ones that never run are a fixture generator (vendor_ledger_schema_e2e) and the RED and gap tests.

Living document:

• Part 7: 7.4's footprint is re-measured, the Maven/Gradle sidecar passage is corrected (Full Gradle support in agent, hosted and vendored modes #646, Agent-mode apply in a Gradle-only project patches the ~/.m2 copy Gradle never reads, reports success, and VEX attests not_affected while the build uses the unpatched ~/.gradle jar #551), {{C55}} is added, and the check line is dated today.
• Part 2: the §2.8 manifest-codes bullet notes the stat-error case with {{C56}}, and C56 and C57 are under new findings.
• Part 8: there's a new-findings bullet on RED-ignored tests without issues.
• Summary: §5's agent-mode row names Deno and --global as the cases that need it.

Next backlog rows: C34 (command-model decision; it should wait for #966 and #1000), then C31/C32 after #793.

---

Generated by Claude Code

[github-actions[bot]]

[agent] 2026-10-07: architecture audit (ecosystems and formats)

main @ db83f01. It moved from 9c43dfc by 33 commits, including #690 (sbt, Mill and scala-cli support, +59K lines across 958 files), #987 (npm linked-store aliases) and #886 (spawn deadline). There were no new maintainer replies in the discussion and no handovers for this routine.

Reconciled.

• Nothing in this area merged.
• New draft PRs claim our issues:
  • #1008 fixes Walk package-lock entries once for inventory, vendored, hosted and restore #663 (E07), Tracking: drive the seven npm-family vendor backends through one generic driver #920 and Build npm-family vendor ledger entries through one constructor instead of seven literal VendorEntry blocks #922 (E22), and Resolve VEX npm alias copies through the core resolver and delete vex_consumed's second alias walk #856 (E62, E40's child);
  • #1009 fixes Lock inventory ignores a bun.lockb that Bun installs from when bun.lock is a dangling symlink #735 (E17).
• The register now shows these as in PR. E09/E51 are still in Fix yarn berry project gates drifting between modes (#628, #629) #657, and E64 is still in Fix pnpm lock/workspace readers missing a BOM (#903, #904, #905) #909.
• Re-checked #856 after Fix npm linked-store alias copies left unpatched (#852) #987:
  • Fix npm linked-store alias copies left unpatched (#852) #987 extended only the core alias_copies (to npm linked-store entries), and added a third, exact-match alias test in the store fan-out.
  • The CLI's vex_consumed walk is unchanged and still compares exactly, so the case drift stands. I commented with fresh permalinks.

Verified and filed: E30 → #1010 (tracking) and #1011 (child 1, linked as a sub-issue).

• redirect/mod.rs is now 21,936 lines: 7.6K production (L1–L7622) and 14.3K inline tests (322 tests in six modules). It was 17.5K at the snapshot.
• The hosted-URL and grant-token grammar still sits in the middle of the gem section, not in hosted_url.rs.
• vendor/ and, since sbt, Mill and scala-cli support in agent, hosted and vendored modes #690, formats/sbt/owned_file.rs (bare_sha256_hex) import helpers from it.
• Move patch/redirect/mod.rs's inline test modules into sibling test files #1011 is a pure move of the six test modules into sibling files.
• The checklist orders the per-ecosystem moves behind the in-flight behavior PRs on the same sections (Hosted cargo redirect refuses a dependency whose inline table has a multi-line features array, because it plans Cargo.toml pins with a line scanner #757, Fix yarn berry project gates drifting between modes (#628, #629) #657, Read and splice nuget.config through formats::nuget in hosted, vendored and restore #594/Hosted NuGet rewrites packages.lock.json entries at other versions of the patched id #593, Read Gemfile.lock sections and DEPENDENCIES entries through formats::gem in hosted and vendored modes #780, Locate hosted Maven pom edits and their upstream restore through the formats::maven element scanner #717/Hosted Maven splices the API's suffixed version into pom.xml unchecked, while hosted Gradle refuses the same grant #882).

Verified and filed: E29 → #1012.

• registry_fetch.rs is now 3,048 lines (1,560 production). It holds archive extraction, the Go module zip walk and h1 hash, integrity checks, and the registry bases plus HTTP client.
• patch/jvm_jar.rs (agent mode), redirect/upstream/ (hosted restore), hosted/npm_manifest.rs and api/vendor_prefetch.rs import it from vendor/.
• Move the bounded archive extractors out of vendor::registry_fetch into utils::archive #1012 moves the archive and Go-module-zip families to utils::archive.
• Integrity waits for Move LockfileEntry, LockIntegrity, SourceKind and http_url from vendor::lock_inventory into formats::entry #834 (LockIntegrity). The registry bases and transport wait for PR Bound registry downloads by ApiTimeouts instead of a 60 s total deadline (#872) #876, so Move the bounded archive extractors out of vendor::registry_fetch into utils::archive #1012 doesn't conflict with it.
• The caps comment cites a common::read_zip_members twin that no longer exists.

New finding: E69, #1014 (bug).

• sbt, Mill and scala-cli support in agent, hosted and vendored modes #690 answers "is this an sbt / Mill / scala-cli build" with six marker lists.
• get_jvm_cache_roots_with returns early on JVM_PROJECT_MARKERS (L852) before its own SCALA_TOOL_MARKERS gate (L878). So the .scala-build and project/build.properties entries are dead for the crawl, while m2_gate honors them.
• Proof: a throwaway test in scala_cache_tests.rs, run twice on db83f01 with a populated COURSIER_CACHE:
  • a scala-cli dir with Main.scala + .scala-build/ (no project.scala) gets no roots, although has_scala_tool_marker is true;
  • an sbt root with only project/build.properties + project/Build.scala gets no roots, while vendored sbt::detect = Some(Sbt) and is_sbt_build = true;
  • adding project.scala (the control) finds the Coursier root.
• The .mill-version handling also differs between vendored sbt and vendored scala-cli (read, not executed).

Searched without filing (survey of the new JVM code):

• -D option parsing: coursier_cache::jvm_option_values splits on whitespace, while gradle::home::split_opts is quote-aware. They disagree on -Dcoursier.cache="/a b". Not filed: Gradle's launcher splits JAVA_OPTS like xargs and sbt's runner does not, so the two parsers may differ on purpose.
• sbt build-findings refusal chain: written three times (hosted build_refusal, vendored plan_with_digest, VEX evidence_blocker).
  • Vendored applies it only to new pins (if existing.is_none()), and hosted also refuses existing rows.
  • On re-plan, vendored still emits vendor_sbt_pin_unverifiable / vendor_sbt_override_shadowed through existing_advisories, so the outcome differs as a warning versus a refusal.
  • This needs an executed CLI comparison before filing. It is a candidate for next run.
• Coursier predicates: coursier_spelled vs JvmCacheLayout::classify disagree on host-level paths (…/https/host). A Maven repo under an http directory is read as Coursier, but the impact is only pom-only versions, so it is weak.
• Dead code: jvm_cache::project_dependency_set has an empty provider list, and GateWarning::MetaBuildOnly is never constructed. Both are small; I'll fold them into E58-style dead-code work later.

False positives ruled out:

• Coursier default-location resolution, Gradle user-home precedence and the files-2.1 sha1 are each single-sourced.
• The sbt dependency-literal parser is shared by hosted and vendored.

Living document:

• Part 3: the redirect/mod.rs size and test numbers are corrected, with {{E30}} on §3.2 and recommendation 1, and the new formats/sbt → redirect edge is noted.
• Part 5: the registry_fetch.rs size, contents and importers, with {{E29}}.
• Part 6: a new-findings bullet for {{E69}}.
• Summary: the redirect/mod.rs line and the "Largest file" row are updated.
• The check lines in Parts 3, 5 and 6 are updated.

Next backlog rows:

• E08 (yarn grammars; after Fix yarn berry project gates drifting between modes (#628, #629) #657);
• E14 (Pipfile.lock, still unproven);
• E42 (embedded --vex glue; may become decision #966);
• E31 (HostedRewriter tracking; after Move patch/redirect/mod.rs's inline test modules into sibling test files #1011);
• the sbt refusal-chain lead above.

---

Generated by Claude Code

[github-actions[bot]]

[agent] 20261007T1: maintainer triage decisions

The maintainer decided nine open decision issues on 2026-10-07. The register rows and living-document passages now record them.

• #1000 (C55): option A. Agent mode stays supported for every ecosystem, in projects and for --global, for now. No deprecation, warning or refusal of --mode agent. Agent-mode layout bugs stay open and are fixed one at a time; none closes as won't-fix on the strength of Decide: keep agent mode for every ecosystem, or limit it to Deno and --global installs #1000. Asking the package manager for layouts (§2.2) is not adopted. C34 can now assume agent mode survives in full as sync; it waits only on Decide: warn on and then remove scan --apply/--vendor, and whether --vex stays embedded #966. Closed.
• #983 (C36): keep the --update binary swap and the notifier. The review's "replace with re-run install.sh" is withdrawn. Hardening follow-ups: retry, stall/idle timeout, streamed download, live post-release test. Closed.
• #973 (E26): one Maven backend. A lone pom is planned as a reactor of one through the jvm/ planner; the legacy forward path is deleted and maven_pom_repository entries are revert-only. A root that still holds one is refused (legacy_maven_root) until vendor --revert. Breaking v5 change; lands before Move the v5 JVM vendor orchestration and Maven acquisition out of maven_repo.rs into vendor/jvm #972 and closes Vendored Maven silently resolves the unpatched jar when an earlier <repository> or a mirrorOf * mirror serves the same GAV, and VEX still attests #263, Same-GAV Maven patches are shadowed when a build plugin depends on the same GAV in a reactor build #274, Vendored Maven refuses a single-module EAR pom as a multi-module aggregator because two declares_modules disagree #716.
• #966 (C35): v5 removes scan --apply, scan --vendor, get --no-apply and the download/gc aliases, with no warning release. --sync stays. Embedded --vex (Q2) is still undecided; E42 is unaffected.
• #808 (C26): option C. apply.lock stays transient and is never left in the project. Fix: Ctrl-C/SIGTERM/SIGHUP (and Windows console ctrl) currently leave it behind. The layering half moves to vendor --check and vex misreport a crashed vendored run whose commit journal is pending, because only lock-taking commands replay it #809/Tracking: build one RunCtx in main and stop mirroring CLI flags into the process environment #793.
• #792 (C25): option A in v5. The diff download path, --download-mode and SOCKET_DOWNLOAD_MODE go, with no alias; .socket/diffs/ is swept as obsolete. patch/package.rs stays (vendored and hosted use its readers). Makes An invalid --download-mode fails apply and repair with exit 1 but is accepted by every other command #791 moot.
• #704 (C14, C53): option 1. Every top-level --json error becomes {code, message}, and errorCode siblings fold in. Self-enforced exit-2 errors print the coded error on stdout through one usage_error helper; clap errors stay stdout-free. Moving scan/get/rollback onto Envelope (option 3) stays open under C11.
• #648 (C07): option 2. The org is resolved once per run into one route (Org{slug} or Proxy); a failed auto-resolve sends the whole run to the public proxy with one warning. No default slug, no mid-run re-resolve. Only scan, get <uuid> and vex fall back to the public proxy on 401/403; get search, apply, rollback, repair and vendor eject fail #647's 401/403 swap should become a startup decision too.
• #615 (C05, C35): v5 removes the SOCKET_FORCE binding; --force stays as a flag on apply, vendor and --update. Nothing in or outside the repo sets the variable.

Also triaged: #580, the bun bench regression since #472. It is avoidable work (is_bundled_entry parses every entry's meta once per patch), not the cost of the fix. The fix belongs to #578 and draft PR #1009. No register row covers it.

Implementation PRs are pending for #973, #966, #808, #792, #704, #648, #615 and #580. #792 and #966 (and #615) edit the same migrating-to-v5.md table, so whichever lands second rebases.

---

Generated by Claude Code

[github-actions[bot]]

[agent] 2026-10-07: architecture refactor run

• main: db83f01.
• Merged since last entry: #886 (Crawler probes spawn gem, python and npm with no timeout, so a hung shim hangs scan forever #845, C48) as 6bba625. C48 set to fixed (#886); rewrote the two C48 passages in doc/07-infra-agent.md (process spawning bullet and the C48 finding) to describe utils::process::output_within on main.
• Ranking: 2 of 3 slots open (Bound registry downloads by ApiTimeouts instead of a 60 s total deadline (#872) #876, Honor HTTP-date Retry-After on vendor-service retries through api::retry (#677) #889 ready, burn-down merging main). The higher-scored queue rows (Finish every vendored revert through one shared helper with an explicit keep policy instead of 12 copied finish blocks #990, Build npm-family vendor ledger entries through one constructor instead of seven literal VendorEntry blocks #922, apply, apply --check and vendor report noManifest (exit 0) when .socket/manifest.json exists but can't be stat'd #998, An unparseable .socket/manifest.json is reported under five different --json error codes depending on the command #931, --ecosystems rejects NPM and npm, pypi, which socket.yml patches.ecosystems accepts: the ecosystem name parser is written three times #773) are still skipped on commands/vendor.rs (Fix gem takeover un-hosting a grouped gem (#775) #776, Fix yarn PnP detection ignoring nodeLinker (#975, #539) #978), backend files or claims. Best eligible: Vendored-reference scan never sees NuGet or Maven wiring, so the orphan sweep deletes a still-wired unit #832 + Vendored-reference scan never reads hatch.toml, so the orphan sweep deletes a wheel that a Hatch environment still installs #958 (E61, E67; B 2, U 0, D ≈1, R M, score ≈5): one root cause (the vendored-reference scan reads only VENDORED rows; NuGet/Maven reference the bare uuid dir). Next: repair and scan --prune delete the beforeHash blobs of active patches, so a later offline rollback fails and tells the user to run repair #893 (≈4).
• Opened: #1015, the eight VENDORED_WRITES_UNMARKED rows get the VENDORED role (list deleted, wiring_paths output unchanged); vendor::path::parse_vendor_reference accepts the bare uuid dir; the scan reads through it with < as a terminator. Production +41 / −41, tests +255. Red→green: repair_reports_missing_ledger_for_nuget_maven_and_hatch_wiring (empty on main).
• Claimed: Vendored-reference scan never sees NuGet or Maven wiring, so the orphan sweep deletes a still-wired unit #832, Vendored-reference scan never reads hatch.toml, so the orphan sweep deletes a wheel that a Hatch environment still installs #958 (Claim-ID 2026-10-07T12:56:20Z-90d5b6). E61, E67 set to in PR #1015.
• Left out: the dead eco == "maven2" arm of the vendor stranded-reference gate (commands/vendor.rs is changed by Fix gem takeover un-hosting a grouped gem (#775) #776 and Fix yarn PnP detection ignoring nodeLinker (#975, #539) #978).
• Lessons: covgap_commands_vendor has 3 chmod-based tests that fail as root in the sandbox. formats/registry.rs isn't rustfmt-clean on main (Fix yarn PnP detection ignoring nodeLinker (#975, #539) #978 reformats it): format only your own hunks.

[github-actions[bot]]

[agent] 2026-10-07: architecture refactor run

• main: 6fe81ad.
• Merged since last entry: none of ours (main gained Fix main CI red on stale digest pending-list entries #1016 only).
• Capacity: 5 arch-refactor/* PRs open: Bound registry downloads by ApiTimeouts instead of a 60 s total deadline (#872) #876, Honor HTTP-date Retry-After on vendor-service retries through api::retry (#677) #889, Scan every vendored-write file for vendored references (#832, #958) #1015 (ready, burn-down sweeping them; heartbeats fresh) and maintainer drafts Remove the SOCKET_FORCE env binding; --force is flag-only (#615) #1021 (Decide: give SOCKET_FORCE per-command names so forcing a self-update doesn't also force apply and vendor #615) and Make every --json top-level error a {code, message} object (#704) #1027 (Decide: one shape for the --json top-level error (scan and get emit both a string and a {code, message} object) #704). Over MAX_OPEN = 3, so no claim and no new PR.
• Ranking: queue unchanged; top five still skipped on busy files (Fix gem takeover un-hosting a grouped gem (#775) #776, Fix yarn PnP detection ignoring nodeLinker (#975, #539) #978 on commands/vendor.rs; backend fix PRs) or claims. Next eligible: repair and scan --prune delete the beforeHash blobs of active patches, so a later offline rollback fails and tells the user to run repair #893, Validate patch UUIDs through one utils::uuid grammar instead of five #705, Move the vendoring-service client out of api/client.rs into its own submodule #871 (after Honor HTTP-date Retry-After on vendor-service retries through api::retry (#677) #889).
• Lessons: maintainer-driven sessions also open arch-refactor/* drafts without a status block; count them toward MAX_OPEN but don't take them over.

[github-actions[bot]]

[agent] 2026-10-07: architecture audit (CLI and core)

main @ c5be5d1. It moved 44 commits from 9c43dfc, including #876, #886, #889 and #1016. There were no new maintainer comments; I applied the 14:00Z triage entry already in the register. There were no handovers addressed to audit-core.

Reconciled:

• Fixed: C49 → fixed (Bound registry downloads by ApiTimeouts instead of a 60 s total deadline (#872) #876): registry clients now use ApiTimeouts and the shared read_capped. C15's Vendor-service retries ignore an HTTP-date Retry-After: fold the vendor Retry-After parser and jitter onto api::retry #677 → fixed (Honor HTTP-date Retry-After on vendor-service retries through api::retry (#677) #889): vendor retries share parse_retry_after and the jitter sampler, but blob/diff fetches still have no retry, so Tracking: one retry primitive for the patch API client (JSON, vendor service, blob and diff) #676 stays open. C48 was already recorded as fixed (Bound crawler and tool probes through one spawn deadline (#845) #886).
• In PR, all opened today by the refactor routine:
  • C05 → Remove the SOCKET_FORCE env binding; --force is flag-only (#615) #1021;
  • C07 → Resolve the org once per run and route every API call through it (#648) #1041;
  • C14 and C53 → Make every --json top-level error a {code, message} object (#704) #1027;
  • C26 → Remove apply.lock when a lock-holding run is interrupted (#808) #1030;
  • C35 → Remove scan --apply/--vendor, get --no-apply and the download/gc aliases (#966) #1031;
  • C42 → Guard .socket links and agent writes with one containment helper #1042;
  • C57 → Replace a superseded patch generation's wiring on re-pin and remove #1035;
  • C12 child 2 (command cycles) → Break command-module cycles and share remedy and UI text #1043;
  • C18's user-input half → Use one package target grammar for get, remove, rollback and the UUID shortcut #1034 (2 of the 5 grammars; Validate patch UUIDs through one utils::uuid grammar instead of five #705 stays open for the on-disk ones).
• Re-checked #614 against main: it still holds (the proxy batch cap is 10, and registry_concurrency() has no caller). I commented with fresh permalinks. SOCKET_API_CONCURRENCY and SOCKET_WALK_THREADS are undocumented, and no test keeps core-read env vars in CLI_CONTRACT.md #678 also still holds: neither env var is in the contract or docs.

Backlog:

• C34 (the command-model decision) was re-verified on c5be5d1, and its premises hold:

  • scan is hosted by default, and report-only under --prune/-g;
  • get switches to agent mode under --save-only/-g;
  • vendored→hosted takeover still runs in place;
  • there are 27 GlobalArgs fields flattened into 11 commands.

  I didn't file it, because this run's one decision slot went to the time-sensitive C58 below. C34 is first in line next run.

• C32 was re-measured, not decomposed: 32 covgap/coverage_fix files, 27,570 lines, 415 tests.

• C31 still waits on Tracking: build one RunCtx in main and stop mirroring CLI flags into the process environment #793.

New finding: C58 → #1047 (decision). Standalone vex exits 2, the global "usage error" code, on every runtime failure except "nothing attested". Those failures include manifest_unreadable, manifest_not_found, vendor_ledger_corrupt, product_undetected, serialize_failed and write_failed, all through a catch-all _ => 2 arm.

• Proof: a debug build ran under env -i with --json --offline, twice, with identical results.
  • A {not json manifest gives vex -O exit 2 (manifest_unreadable), but apply --check and vendor --check exit 1 with the same code, and list, remove and rollback exit 1.
  • An empty project gives vex exit 2 (manifest_not_found), but remove and repair exit 1 with the same code.
  • Embedded --vex maps every failure to 1.
• Time-sensitive: open PR Make every --json top-level error a {code, message} object (#704) #1027 routes vex's exit-2 sites through the new usage_error helper, which would cement the conflation.
• The issue recommends option 1 for v5: runtime failures exit 1.

Searched without filing:

• repair -g: it runs the project's vendored phase, although the contract says "Global scope never touches the project's state". The contract also says commands that don't consume a global flag ignore it, so this isn't filed.
• --offline in remove: it is honored through the shared run_hosted_leg.
• User-Agent strings: one constant, plus Maven's deliberate CLI UA.
• The update notifier's version comparison: it uses release::is_newer (precedence) everywhere.
• Failpoints in release builds: gated by debug_assertions or the dev-only feature; resolver 2 and cargo build -p socket-patch-cli in release.yml keep them out.
• Manifest writes: write_manifest is atomic.
• The Coursier sidecars (new, sbt, Mill and scala-cli support in agent, hosted and vendored modes #690): apply and rollback share coursier::fixup. Its local digest() helper evades C17's text ratchet, which I noted on C17 instead of filing it.

False positives ruled out:

• pdm_site.rs .spawn() is bounded by read_runtime_site_dir's timeout.
• build_registry_client's reqwest::Client::new() fallback drops the timeouts, but only on a TLS-backend init failure. That's far-fetched.

Living document:

• Part 7: the 7.2 vendor-retry row and the registry-client bullet are rewritten for Honor HTTP-date Retry-After on vendor-service retries through api::retry (#677) #889 and Bound registry downloads by ApiTimeouts instead of a 60 s total deadline (#872) #876, the C49 new-finding bullet says fixed, and the check line is dated today.
• Part 2: C58 is under new findings, and the check line is dated today.
• Part 8 and the Summary: the contract size is now 415 KB, 2,145 lines, longest line 12,077 characters, and the covgap counts are updated.
• Register: fixed rows' problem text is shortened to stay under 20K.

Next backlog rows: C34 (command-model decision), C32 (decompose the covgap triage), then C31 after #793.

---

Generated by Claude Code

[github-actions[bot]]

[agent] 2026-10-07: architecture refactor run

• main @ c5be5d1.
• Merged since the last entry: #876 (Registry downloads give up after 60 s even while the body is still arriving #872, C49, e2300cc) and #889 (Vendor-service retries ignore an HTTP-date Retry-After: fold the vendor Retry-After parser and jitter onto api::retry #677, C15 child 1, 835601b). Register rows C49 and C15 and the doc/07-infra-agent.md 7.2 retry table and registry-timeout passages were already rewritten by audit-core's c5be5d1 reconcile; moved both PRs to Merged in register/90-refactor.md.
• Capacity: 7 arch-refactor/* PRs open (Scan every vendored-write file for vendored references (#832, #958) #1015 ours, ready; maintainer drafts Remove the SOCKET_FORCE env binding; --force is flag-only (#615) #1021, Make every --json top-level error a {code, message} object (#704) #1027, Remove apply.lock when a lock-holding run is interrupted (#808) #1030, Remove scan --apply/--vendor, get --no-apply and the download/gc aliases (#966) #1031, Vendor single-module Maven poms through the suffixed jvm planner and retire the legacy <repository> backend (#973) #1036, Resolve the org once per run and route every API call through it (#648) #1041), over MAX_OPEN = 3, so no claim or PR this run. No abandoned in-progress PR.
• Ranking unchanged: Finish every vendored revert through one shared helper with an explicit keep policy instead of 12 copied finish blocks #990 (≈14), Build npm-family vendor ledger entries through one constructor instead of seven literal VendorEntry blocks #922 (≈9), apply, apply --check and vendor report noManifest (exit 0) when .socket/manifest.json exists but can't be stat'd #998 (≈8), An unparseable .socket/manifest.json is reported under five different --json error codes depending on the command #931 (≈5.5), --ecosystems rejects NPM and npm, pypi, which socket.yml patches.ecosystems accepts: the ecosystem name parser is written three times #773 (≈5) all still skipped for file overlap with open PRs (commands/vendor.rs: Fix yarn PnP detection ignoring nodeLinker (#975, #539) #978, Remove the SOCKET_FORCE env binding; --force is flag-only (#615) #1021, Make every --json top-level error a {code, message} object (#704) #1027, Route JVM layout through one module and fix three JVM scope bugs #1032, Resolve the org once per run and route every API call through it (#648) #1041, Break command-module cycles and share remedy and UI text #1043, Compare purls through one PurlKey type #1045) or a live claim (Build npm-family vendor ledger entries through one constructor instead of seven literal VendorEntry blocks #922). Next eligible: repair and scan --prune delete the beforeHash blobs of active patches, so a later offline rollback fails and tells the user to run repair #893, Validate patch UUIDs through one utils::uuid grammar instead of five #705, Move the vendoring-service client out of api/client.rs into its own submodule #871.
• Issues claimed or released: none.

[github-actions[bot]]

[agent] 2026-10-07: architecture refactor run

• main @ 431b818.
• Merged since the last entry: #1015 (Vendored-reference scan never sees NuGet or Maven wiring, so the orphan sweep deletes a still-wired unit #832, Vendored-reference scan never reads hatch.toml, so the orphan sweep deletes a wheel that a Hatch environment still installs #958; E61, E67) as 8e521f9. Register rows E61 and E67 set to fixed (#1015); rewrote their two "New findings" passages in doc/05-vendored.md to describe main (the role-based scan, the deleted VENDORED_WRITES_UNMARKED, parse_vendor_reference), keeping the still-dead eco == "maven2" arm.
• Capacity: 8 arch-refactor/* PRs open, all maintainer drafts with heartbeats at 16:37Z (Remove the SOCKET_FORCE env binding; --force is flag-only (#615) #1021, Make every --json top-level error a {code, message} object (#704) #1027, Remove apply.lock when a lock-holding run is interrupted (#808) #1030, Remove scan --apply/--vendor, get --no-apply and the download/gc aliases (#966) #1031, Vendor single-module Maven poms through the suffixed jvm planner and retire the legacy <repository> backend (#973) #1036, Resolve the org once per run and route every API call through it (#648) #1041, Remove --download-mode and the diff download path (#792) #1049, Stop re-parsing bun lock entries for every patch in scan (#580) #1051). Nothing abandoned, no design questions on routine PRs. No new PR, no claims.
• Ranking: unchanged top five (Finish every vendored revert through one shared helper with an explicit keep policy instead of 12 copied finish blocks #990, Build npm-family vendor ledger entries through one constructor instead of seven literal VendorEntry blocks #922, apply, apply --check and vendor report noManifest (exit 0) when .socket/manifest.json exists but can't be stat'd #998, An unparseable .socket/manifest.json is reported under five different --json error codes depending on the command #931, --ecosystems rejects NPM and npm, pypi, which socket.yml patches.ecosystems accepts: the ecosystem name parser is written three times #773), all still skipped on busy files or an existing claim; next eligible when a slot frees: repair and scan --prune delete the beforeHash blobs of active patches, so a later offline rollback fails and tells the user to run repair #893, Validate patch UUIDs through one utils::uuid grammar instead of five #705, Move the vendoring-service client out of api/client.rs into its own submodule #871.
• Lessons: none new.

[github-actions[bot]]

[agent] 2026-10-07: October 7 reconciliation and campaign (maintainer)

Main: 431b818. This entry reconciles the ledger with a full architecture and UX audit of main @ 1c6c509 (14 audit lenses, every claim re-verified against the code, 39 claims refuted) and records the one-day campaign that followed it.

Campaign PRs (all draft, label arch-refactor; each deletes the duplicate copies it replaces):

PR	Seam	Register
#1026	one URL redactor; hosted Composer drops transport-options (#399); VEX product id without credentials	C59
#1029	path flags validated; apply --check covers every patch; per-purl hosted JSON	C61
#1032	one vendor::jvm::layout; --ecosystems maven covers jvm; preflight matches the backend	E77, E69
#1033	no VEX over yarn PnP (#519), pnpm bundled or deno.lock copies	E72
#1034	one package-target grammar for get, remove, rollback and the UUID shortcut (#453)	C62
#1035	one owned-pin generation model on re-pin and remove (#999, #864, #682, #266)	E71
#1038	one path normalizer, home resolver and repo-root walk	C64
#1039	atomic vendored→hosted takeover with a staged dry run	E70
#1042	one containment helper for .socket links and agent writes (#887, #726)	C60
#1043	five command-module cycles broken; shared remedy and UI text	C65
#1044	one governing-lock table	E75
#1045	one PurlKey for every purl comparison	C63
#1046	test children off production telemetry; zero-tests guard on every e2e leg	C66
#1050	one vendored-entry liveness verdict from discovery	E74
#1057	all yarn.lock parsing in formats/yarn; non-registry copies skipped	E08, E76
#1058	one pinned check through lockfile discovery (#567, #260)	E73

Main went green with #1016 (stale digest entries) and #1022 fixed the docs drift in the repo. #1018 runs CI on a merge queue with per-SHA push concurrency (C67); the ruleset with required checks needs an org admin. pnpm, npm and bun issues stay with #1007, #1008 and #1009.

Ledger changes:

• tools/mirror.py: statuses are classified by their leading word (the old substring match counted "filed …; … fixed" rows as fixed); a new ledger commit re-renders every post; entries already on the discussion are not posted again. New status partly fixed (#n); decision pending for decide rows with no issue.
• Register: merged duplicate rows E49→E04, E51→E09, E11/E55→E10, E57→E15, E60→E16, E62→E40, E67→E61, C39→C09, C52→C13, C53→C14, C35→C05, C46→C26, C40→C38 (doc tokens remapped). Corrected E04, E08, E09, E12, E31, E33, E42, E43, E44–E47, E64, E69, C02, C05, C10, C12, C17, C20, C27, C31–C34, C47, C48 against main. Added E70–E88 and C59–C73 for the untracked clusters, each linked to its campaign PR or issue. Footers, the legend (handed off, partly fixed) and the CI hand-off line fixed.
• Living document: §5.5 zip inflate marked fixed (Stream ZIP member hashes during vendored verification #587); Part 8 recommendation B now keeps the gating Linux tests and per-PR Docker e2e on PRs and only de-instruments them; the TL;DR "fix now" list no longer carries bun.lockb or SOCKET_FORCE; takeover scope (five ecosystems), cycle count, sizes and counts refreshed in Parts 2–9; new Part 7.7 "Security boundaries"; an October 7 campaign note in the summary.
• Priority by ecosystem (Maven and NuGet below Composer, Go and Cargo) is the maintainers' intended triage; no re-triage item was added.

Issues filed: #1061 (E80), #1062 (C70), #1063 (C71), #1064 (E87), #1065 (C72), #1066 (C73), #1067 (C48 remainder), #1068 (E85), #1069 (E86).

Still open for maintainers: #704 exit policy (hosted exit code on unpinned patches), #966 Q2 (embedded --vex), C34 (command model), E44–E47 (napi engine, hosted rollback originals, VEX consumed evidence, support tiers). None of these was decided here; the campaign PRs keep current behavior where a change would need one.

---

Generated by Claude Code

[github-actions[bot]]

[agent] 2026-10-07: architecture audit (ecosystems and formats)

main @ 05ecc6e. Since my last run (db83f01) main moved 19 commits, including #657 (berry gates), #1015 (vendored-reference scan), #1024 (PyPI name spellings), #876 and #1018. The October 7 reconciliation (431b818) already recorded the status changes they caused. There were no new maintainer replies in the discussion and no handovers for this routine.

Reconciled.

• No register status changed. No new PR claims an E-row issue beyond those already recorded, apart from Vendor single-module Maven poms through the suffixed jvm planner and retire the legacy <repository> backend (#973) #1036, which now also claims Vendored Maven refuses a single-module EAR pom as a multi-module aggregator because two declares_modules disagree #716 (part of E10).
• Re-checked two open issues against main, with fresh permalinks:
  • #593 (E50): hosted rewrite_nuget still matches by id alone in every framework.
  • #882 (E63): hosted Maven still splices maven_suffixed_version unchecked.

Verified and filed: E31 → #1075 (tracking) and #1076 (child 1, linked as a sub-issue).

• RewriteResult now has 27 per-ecosystem uuid sets (20 at the review). Each is one of four meanings: owned, confirmed, refused, foreign.
• merge_group_delta destructures all of them by hand.
• engine::confirm is 225 lines with 25 ProbeStep outcomes. Precedence lives only in the order of its ifs.
• The CLI scan/hosted.rs and vex/discover/gradle.rs read individual sets directly.
• Replace RewriteResult's 27 per-ecosystem uuid sets with one report map #1076 replaces the sets with one (Rewriter, Report) map behind accessors. It is mechanical (about 400–600 one-line substitutions) and rebases after Decide whether a hosted patch is pinned through lockfile discovery alone #1058, which edits confirm().
• The checklist orders the trait port behind Move patch/redirect/mod.rs's inline test modules into sibling test files #1011 and Tracking: split patch/redirect/mod.rs into per-ecosystem modules and sibling test files #1010.

New finding: E89, #1079 (bug, pm:uv).

• The pure-wheel rule is written four times. Only pypi_distribution::wheel_platform_from_filename is shared, by hosted and vendored. lock_inventory/pypi.rs (×2) and ledger recovery (recover.rs) use ends_with("-none-any.whl").
• Recovery also re-parses the uv.lock [[package]] unit with a string scanner, beside the toml_edit + package_artifacts reader the live inventory uses.
• Proof: a throwaway lock_inventory test, run twice on 05ecc6e. On a unit with a hashless py3-none-any wheel followed by a hashed manylinux wheel:
  • pure_wheel_from_uv_unit returns the pure URL paired with the manylinux digest;
  • python_lock_inventory returns no resolution.
• Impact: fail-closed (the fetch verifies the digest), but repair gives the wrong error. Open PR Fix interpreter-bound wheels treated as portable (#1048) #1053 changes only the shared classifier (cp311-none-any becomes non-portable), so inventory and recovery will drift from hosted and vendored when it lands.

Searched without filing:

• PEP 503 names: canonicalize_pypi_name is the only normalizer. remove and rollback don't PEP 503-normalise PyPI purl identifiers, so remove pkg:pypi/typing_extensions@4.7.1 exits 1 "No patch found" while get accepts the same identifier #1024 routes purl_eq through it, and there are no ad-hoc replace('_', "-") copies.
• Berry gates after Fix yarn berry project gates drifting between modes (#628, #629) #657: formats/yarn/berry_gates.rs is now the single gate, and I found no remaining copies.
• PyPI version equivalence in purl_eq (PEP 440 1.0 vs 1.0.0): not normalized, unlike Composer. That is purl utilities (audit-core, C63/Compare purls through one PurlKey type #1045), so I didn't file or hand it over.

False positives ruled out:

• wheel_platform_from_filename vs the suffix rule on main: they agree on every well-formed name, including six-none-any.whl (three parts, read as pure by both). The executed drift is the hash pairing; the portability drift needs Fix interpreter-bound wheels treated as portable (#1048) #1053.

Tooling note: the issue-write path drops the trailing footer from issue bodies (as on #1012); comments keep it.

Living document:

• Part 3 §3.2: 27 sets, merge_group_delta :753-831 and confirm() engine.rs:1652-1876 corrected, with {{E31}}. Recommendation 2 is updated to 27 sets and points to Tracking: hosted rewriters behind one HostedRewriter trait with a per-dependency outcome #1075/Replace RewriteResult's 27 per-ecosystem uuid sets with one report map #1076.
• Part 6: a new-findings bullet for {{E89}}.
• Summary: the hosted-rewriter row is updated to 27 sets and a 25-outcome confirm(), with {{E31}}.
• The check lines in Parts 3 and 6 are updated.
• Register: E31 is filed, E89 is added, and a few long rows were trimmed to stay under 20K characters.

Next backlog rows:

• E32 (two hosted orchestrators; after Replace RewriteResult's 27 per-ecosystem uuid sets with one report map #1076);
• E36 (one Inventory tracking);
• E14 (Pipfile.lock, still unproven);
• E88 (small duplicates, Yarn 4 node-modules / pnpm-linker projects migrated from Yarn 2 PnP keep a stale .pnp.js, and socket-patch refuses them as Plug'n'Play: agent and vendored exit 1, hosted warns "npm dependencies were NOT scanned" (regression since 3.3.0) #975);
• the sbt refusal-chain lead from the last run.

---

Generated by Claude Code

[github-actions[bot]]

[agent] 2026-10-07: architecture audit (ecosystems and formats)

main @ 05ecc6e. Since my last run (db83f01) main moved 19 commits, including #657 (berry gates), #1015 (vendored-reference scan), #1024 (PyPI name spellings), #876 and #1018. The October 7 reconciliation (431b818) already recorded the status changes they caused. There were no new maintainer replies in the discussion and no handovers for this routine.

Reconciled.

• No register status changed. No new PR claims an E-row issue beyond those already recorded, apart from Vendor single-module Maven poms through the suffixed jvm planner and retire the legacy <repository> backend (#973) #1036, which now also claims Vendored Maven refuses a single-module EAR pom as a multi-module aggregator because two declares_modules disagree #716 (part of E10).
• Re-checked two open issues against main, with fresh permalinks:
  • #593 (E50): hosted rewrite_nuget still matches by id alone in every framework.
  • #882 (E63): hosted Maven still splices maven_suffixed_version unchecked.

Verified and filed: E31 → #1075 (tracking) and #1076 (child 1, linked as a sub-issue).

• RewriteResult now has 27 per-ecosystem uuid sets (20 at the review). Each is one of four meanings: owned, confirmed, refused, foreign.
• merge_group_delta destructures all of them by hand.
• engine::confirm is 225 lines with 25 ProbeStep outcomes. Precedence lives only in the order of its ifs.
• The CLI scan/hosted.rs and vex/discover/gradle.rs read individual sets directly.
• Replace RewriteResult's 27 per-ecosystem uuid sets with one report map #1076 replaces the sets with one (Rewriter, Report) map behind accessors. It is mechanical (about 400–600 one-line substitutions) and rebases after Decide whether a hosted patch is pinned through lockfile discovery alone #1058, which edits confirm().
• The checklist orders the trait port behind Move patch/redirect/mod.rs's inline test modules into sibling test files #1011 and Tracking: split patch/redirect/mod.rs into per-ecosystem modules and sibling test files #1010.

New finding: E89, #1079 (bug, pm:uv).

• The pure-wheel rule is written four times. Only pypi_distribution::wheel_platform_from_filename is shared, by hosted and vendored. lock_inventory/pypi.rs (×2) and ledger recovery (recover.rs) use ends_with("-none-any.whl").
• Recovery also re-parses the uv.lock [[package]] unit with a string scanner, beside the toml_edit + package_artifacts reader the live inventory uses.
• Proof: a throwaway lock_inventory test, run twice on 05ecc6e. On a unit with a hashless py3-none-any wheel followed by a hashed manylinux wheel:
  • pure_wheel_from_uv_unit returns the pure URL paired with the manylinux digest;
  • python_lock_inventory returns no resolution.
• Impact: fail-closed (the fetch verifies the digest), but repair gives the wrong error. Open PR Fix interpreter-bound wheels treated as portable (#1048) #1053 changes only the shared classifier (cp311-none-any becomes non-portable), so inventory and recovery will drift from hosted and vendored when it lands.

Searched without filing:

• PEP 503 names: canonicalize_pypi_name is the only normalizer. remove and rollback don't PEP 503-normalise PyPI purl identifiers, so remove pkg:pypi/typing_extensions@4.7.1 exits 1 "No patch found" while get accepts the same identifier #1024 routes purl_eq through it, and there are no ad-hoc replace('_', "-") copies.
• Berry gates after Fix yarn berry project gates drifting between modes (#628, #629) #657: formats/yarn/berry_gates.rs is now the single gate, and I found no remaining copies.
• PyPI version equivalence in purl_eq (PEP 440 1.0 vs 1.0.0): not normalized, unlike Composer. That is purl utilities (audit-core, C63/Compare purls through one PurlKey type #1045), so I didn't file or hand it over.

False positives ruled out:

• wheel_platform_from_filename vs the suffix rule on main: they agree on every well-formed name, including six-none-any.whl (three parts, read as pure by both). The executed drift is the hash pairing; the portability drift needs Fix interpreter-bound wheels treated as portable (#1048) #1053.

Tooling note: the issue-write path drops the trailing footer from issue bodies (as on #1012); comments keep it.

Living document:

• Part 3 §3.2: 27 sets, merge_group_delta :753-831 and confirm() engine.rs:1652-1876 corrected, with {{E31}}. Recommendation 2 is updated to 27 sets and points to Tracking: hosted rewriters behind one HostedRewriter trait with a per-dependency outcome #1075/Replace RewriteResult's 27 per-ecosystem uuid sets with one report map #1076.
• Part 6: a new-findings bullet for {{E89}}.
• Summary: the hosted-rewriter row is updated to 27 sets and a 25-outcome confirm(), with {{E31}}.
• The check lines in Parts 3 and 6 are updated.
• Register: E31 is filed, E89 is added, and a few long rows were trimmed to stay under 20K characters.

Next backlog rows:

• E32 (two hosted orchestrators; after Replace RewriteResult's 27 per-ecosystem uuid sets with one report map #1076);
• E36 (one Inventory tracking);
• E14 (Pipfile.lock, still unproven);
• E88 (small duplicates, Yarn 4 node-modules / pnpm-linker projects migrated from Yarn 2 PnP keep a stale .pnp.js, and socket-patch refuses them as Plug'n'Play: agent and vendored exit 1, hosted warns "npm dependencies were NOT scanned" (regression since 3.3.0) #975);
• the sbt refusal-chain lead from the last run.

---

Generated by Claude Code

[github-actions[bot]]

[agent] 2026-10-07: architecture audit (ecosystems and formats)

main @ 05ecc6e. Since my last run (db83f01) main moved 19 commits, including #657 (berry gates), #1015 (vendored-reference scan), #1024 (PyPI name spellings), #876 and #1018. The October 7 reconciliation (431b818) already recorded the status changes they caused. There were no new maintainer replies in the discussion and no handovers for this routine.

Reconciled.

• No register status changed. No new PR claims an E-row issue beyond those already recorded, apart from Vendor single-module Maven poms through the suffixed jvm planner and retire the legacy <repository> backend (#973) #1036, which now also claims Vendored Maven refuses a single-module EAR pom as a multi-module aggregator because two declares_modules disagree #716 (part of E10).
• Re-checked two open issues against main, with fresh permalinks:
  • #593 (E50): hosted rewrite_nuget still matches by id alone in every framework.
  • #882 (E63): hosted Maven still splices maven_suffixed_version unchecked.

Verified and filed: E31 → #1075 (tracking) and #1076 (child 1, linked as a sub-issue).

• RewriteResult now has 27 per-ecosystem uuid sets (20 at the review). Each is one of four meanings: owned, confirmed, refused, foreign.
• merge_group_delta destructures all of them by hand.
• engine::confirm is 225 lines with 25 ProbeStep outcomes. Precedence lives only in the order of its ifs.
• The CLI scan/hosted.rs and vex/discover/gradle.rs read individual sets directly.
• Replace RewriteResult's 27 per-ecosystem uuid sets with one report map #1076 replaces the sets with one (Rewriter, Report) map behind accessors. It is mechanical (about 400–600 one-line substitutions) and rebases after Decide whether a hosted patch is pinned through lockfile discovery alone #1058, which edits confirm().
• The checklist orders the trait port behind Move patch/redirect/mod.rs's inline test modules into sibling test files #1011 and Tracking: split patch/redirect/mod.rs into per-ecosystem modules and sibling test files #1010.

New finding: E89, #1079 (bug, pm:uv).

• The pure-wheel rule is written four times. Only pypi_distribution::wheel_platform_from_filename is shared, by hosted and vendored. lock_inventory/pypi.rs (×2) and ledger recovery (recover.rs) use ends_with("-none-any.whl").
• Recovery also re-parses the uv.lock [[package]] unit with a string scanner, beside the toml_edit + package_artifacts reader the live inventory uses.
• Proof: a throwaway lock_inventory test, run twice on 05ecc6e. On a unit with a hashless py3-none-any wheel followed by a hashed manylinux wheel:
  • pure_wheel_from_uv_unit returns the pure URL paired with the manylinux digest;
  • python_lock_inventory returns no resolution.
• Impact: fail-closed (the fetch verifies the digest), but repair gives the wrong error. Open PR Fix interpreter-bound wheels treated as portable (#1048) #1053 changes only the shared classifier (cp311-none-any becomes non-portable), so inventory and recovery will drift from hosted and vendored when it lands.

Searched without filing:

• PEP 503 names: canonicalize_pypi_name is the only normalizer. remove and rollback don't PEP 503-normalise PyPI purl identifiers, so remove pkg:pypi/typing_extensions@4.7.1 exits 1 "No patch found" while get accepts the same identifier #1024 routes purl_eq through it, and there are no ad-hoc replace('_', "-") copies.
• Berry gates after Fix yarn berry project gates drifting between modes (#628, #629) #657: formats/yarn/berry_gates.rs is now the single gate, and I found no remaining copies.
• PyPI version equivalence in purl_eq (PEP 440 1.0 vs 1.0.0): not normalized, unlike Composer. That is purl utilities (audit-core, C63/Compare purls through one PurlKey type #1045), so I didn't file or hand it over.

False positives ruled out:

• wheel_platform_from_filename vs the suffix rule on main: they agree on every well-formed name, including six-none-any.whl (three parts, read as pure by both). The executed drift is the hash pairing; the portability drift needs Fix interpreter-bound wheels treated as portable (#1048) #1053.

Tooling note: the issue-write path drops the trailing footer from issue bodies (as on #1012); comments keep it.

Living document:

• Part 3 §3.2: 27 sets, merge_group_delta :753-831 and confirm() engine.rs:1652-1876 corrected, with {{E31}}. Recommendation 2 is updated to 27 sets and points to Tracking: hosted rewriters behind one HostedRewriter trait with a per-dependency outcome #1075/Replace RewriteResult's 27 per-ecosystem uuid sets with one report map #1076.
• Part 6: a new-findings bullet for {{E89}}.
• Summary: the hosted-rewriter row is updated to 27 sets and a 25-outcome confirm(), with {{E31}}.
• The check lines in Parts 3 and 6 are updated.
• Register: E31 is filed, E89 is added, and a few long rows were trimmed to stay under 20K characters.

Next backlog rows:

• E32 (two hosted orchestrators; after Replace RewriteResult's 27 per-ecosystem uuid sets with one report map #1076);
• E36 (one Inventory tracking);
• E14 (Pipfile.lock, still unproven);
• E88 (small duplicates, Yarn 4 node-modules / pnpm-linker projects migrated from Yarn 2 PnP keep a stale .pnp.js, and socket-patch refuses them as Plug'n'Play: agent and vendored exit 1, hosted warns "npm dependencies were NOT scanned" (regression since 3.3.0) #975);
• the sbt refusal-chain lead from the last run.

---

Generated by Claude Code