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: 95 problems tracked · 5 fixed · 1 already fixed · 9 in PR · 19 filed · 3 decision pending · 57 to verify · 1 rejected. On GitHub: 31 open and 3 closed arch-audit issues · 4 open and 4 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.

Rendered 2026-10-03 15:51 UTC (ledger 84e4dbd2) 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 open issues were cross-referenced to architectural causes.
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 88 open issues, roughly 29 are a success or a not_affected VEX attestation that the installed bytes don't back up. Another 15 are 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.

   • ~118K lines of production code plus 35K comment lines.
   • ~450K lines of tests.
   • Nine functions over 500 lines; run_scan alone is 1,499.
   • A 17.5K-line redirect/mod.rs.
   • Two hosted orchestrators kept equal by parity tests.
   • Four discovery systems.
   • Nine different revert mechanisms.
   • 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 and Go packages back to hosted;
   • 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;
   • a ledger-loss bug in the vendored→hosted takeover;
   • a planted-binary spawn;
   • a comment-blind NuGet config reader;
   • SOCKET_FORCE bound to three unrelated --force flags.

---

0. The numbers

	Value
Production code (non-blank, non-comment)	117.6K lines + 34.8K comment lines + 9K blank
Inline #[cfg(test)] code in src/	~194K lines
Integration tests (crates/*/tests)	~255K lines in 212 separate test executables (201 top-level files + 11 directory binaries; recounted at 045d7ec, 2026-10-03)
Test : production ratio	~2.8 : 1 overall; ~7 : 1 for the CLI crate
Largest file	patch/redirect/mod.rs: 19,571 lines at 045d7ec (2026-10-03; 17,517 at the snapshot, 6.2K production then)
Functions > 200 / > 500 lines	61 / 9 (run_scan 1,499, 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	343 KB; the longest line is 10,530 characters (at 045d7ec, 2026-10-03; 332 KB / 9,320 at the snapshot)
Open issues	176 on 2026-10-03 (166 labelled bug). 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)
3	Vendored→hosted takeover drops the ledger entry on a drift-keep	RevertOutcome.kept_artifact says callers "must ALSO keep the state.json entry" (core/vendor/mod.rs:664-673). vendored_takeover (cli/scan/hosted.rs:1732-1790) never reads it, deletes the entry, and tells the user that the "committed artifact" was reverted. Every other revert caller honors the flag.	Route takeover through VendoredBackend, and add a regression test.	C03 · filed #568
4	Planted-binary spawn	vendor/pypi_hatch.rs:118 runs Command::new("hatch").current_dir(root). That is exactly the pattern utils/process.rs:23-33 documents as unsafe: a relative PATH entry executes a hatch planted in the scanned repo. It is the only production bare-name spawn. Reproduced on 045d7ec: with PATH=.:…, a planted hatch runs and its fake version passes the >=1.2 gate.	Use process::resolve_tool.	C04 · in PR #617
5	Comment-blind NuGet config reader in hosted mode	redirect/mod.rs:4302 nuget_package_source_keys regex-scans raw XML without masking <!-- -->. A commented-out <add key> changes which sources get mapped. The vendored and formats::nuget readers both mask comments.	Use formats::nuget::parse_config.	E01 · in PR #597
6	SOCKET_FORCE is bound to three unrelated flags	vendor --force, apply --force and --update --force (vendor.rs:80, apply.rs:339, update.rs:61 at 045d7ec). Exporting it to force a self-update also forces apply/vendor past hash checks.	Per-command env names.	C05 · decision #615
7	bun.lockb ignores the registry override	vendor/bun_lockb.rs:235 hard-codes registry.npmjs.org instead of registry_fetch::npm_tarball_url, ignoring SOCKET_NPM_REGISTRY. vlt has two divergent registry_base implementations.	Use the shared helpers.	E02 E03: 2 in PR
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 20 per-ecosystem uuid sets and a 16-rule confirm() if-chain. 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 553 #[serial] test attributes.	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), 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 and history goes in the CHANGELOG;
• 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: 1 fixed · 2 in PR · 3 filed · 8 to verify
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: 6 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: 2 filed · 5 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: 2 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: 2 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 to verify
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 · to verify
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; C14 · decision #704); a typed code registry (enum Reason × Ecosystem) that generates the contract's code tables, with a freshness test.	0.3–0.6K prod; fixes ~65 undocumented and 1 phantom code	L-M (MAJOR)	Parts 2, 8	C13 C14: 1 decision pending · 1 to verify
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 merged into jvm/.	5–8K prod, 8–12K test	M (product)	Parts 4, 5	E26 E47: 2 to verify
10	C	--download-mode default file: diff re-downloads every blob anyway on a cold cache (fetch_stage.rs:377); delete the diff machinery and qbsdiff.	0.6K prod, 1K test, −1 dep	L	Part 7	C25 · to verify
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, Pypi/LauncherCache update channels, the empty Deno extractor, the switched_off("group_commit") oracle path.	~1K prod, ~1K test	L	Parts 4–7	E28 E41 C23: 3 to verify
12	M	Utility consolidation: one HTTP retry/timeout primitive; one validated purl builder family (78 hand-built format!("pkg:…"), 58 prefix checks); 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: 3 filed · 3 to verify
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 C35: 2 to verify
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
15	C	Self-update: keep the notifier; replace the binary swap with "re-run install.sh" (only the standalone channel can self-update). Telemetry: one track(Event) + a shared client instead of 17 wrappers and 125 token/org plumbing sites.	1.3–2.3K prod, 3K+ test	L-M (product)	Parts 2, 7	C22 C36: 2 to verify
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 102 files, git_sha256 in 84, and 14 divergent scrub_socket_env); 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: 4 to verify
17	C	CI: report-only coverage + LTO docker-base off PRs (≈74 runner-min/run); PR e2e 148 legs → ~50 boundary versions; reusable compat workflow; no per-leg compiles.	~200 fewer jobs per PR	L	Part 8	handed off to the CI janitor
18	S	Docs: a generated CLI reference plus ≤300 lines of contract prose; move ecosystem narratives into ecosystems.md and history into the CHANGELOG; decouple docs/testing from validation scripts.	—	L	Part 8	C33 · to verify

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, 15). That is before any decision to deprecate agent mode, which would remove another ~10K. 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.	Decide: freeze agent mode to the ecosystems that need it (Deno; Go's local replace), or keep it and ask the package manager for layouts (§2.2).
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.	Keep the notifier; make --update print or run the installer one-liner.

---

6. Suggested sequencing

• Phase 0, this week: no behavior change except bug fixes.
  • §1 fixes 1–8.
  • Recommendation 11 (dead code).
  • 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: 95 problems tracked · 5 fixed · 1 already fixed · 9 in PR · 19 filed · 3 decision pending · 57 to verify · 1 rejected. On GitHub: 31 open and 3 closed arch-audit issues · 4 open and 4 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: already fixed (#n), decision #n (blocked on an owner decision) and rejected.

• 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-03T12:52Z · main @ 045d7ec

ID	P	Problem	Source	Issues	Status
E01	1	Hosted NuGet source mapping (nuget_package_source_keys) regex-scans raw XML, so a commented-out <add key> changes which sources get mapped. The vendored reader and formats::nuget both mask comments.	§1 #5; 5.4	#561	in PR #597
E02	1	bun.lockb vendoring hard-codes registry.npmjs.org and ignores SOCKET_NPM_REGISTRY. The npm tarball URL is re-implemented in lock_inventory/vlt.rs, and there are two NPM_REGISTRY constants.	§1 #7; 4.4	#562	in PR #574; partly not a defect
E03	1	vlt registry_base has two implementations (upstream/vlt.rs, lock_inventory/vlt.rs) with different fallback orders and different unknown-alias behavior.	§1 #7; 4.4	#562	in PR #574
E04	1	Pipenv hosted-URL recognition accepts any host (pypi_pipenv.rs), but redirect hosted_patch_uuid uses an origin allowlist.	5.4	#563	fixed (#572)
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	Some crawler reads aren't FIFO-safe: nuget_crawler.rs (obj/project.assets.json) and the cargo vendor/<crate>/Cargo.toml reads use a plain read_to_string on project-tree files. The Python .venv read is guarded.	6.6	#592	in PR #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	filed #663
E08	2	yarn has five split("\n\n") + regex grammars beside scan_blocks. Target: hosted yarn writers and restorers built on LockBlock.	3.7 #3; 4.7 D		to verify
E09	2	Yarn berry gates are written twice: the cacheKey constant, cacheKey extraction, and the mixed-EOL and compressionLevel refusals, which use different codes. #370 needs fixing twice.	4.4	#629, #628	in PR #657; compressionLevel reader already shared (#508)
E10	2	XML has eight hand-rolled scanners and four attribute extractors with three tokenization rules. The writers (nuget_feed.rs, maven_repo.rs) never use the shared readers, so reader and writer can disagree.	5.4		to verify
E11	2	NuGet config has three readers. Target: formats::nuget::parse_config everywhere. Fixing E01 is the first step.	3.7 #3; 5.4	#594	filed #594; hosted part in PR #597
E12	2	pnpm v9 and legacy 5.4/6.0 are near-copies (revert_*_opts, vendor_pnpm*, read_project, edit_overrides, dep_field_lines, the KIND constant), and v9 has two lookup paths (a linear scan and LockIndex).	4.4; 4.5 #4; 4.7 B/G	#583	fixed (#583)
E13	2	utils/poetry_lock.rs ≈ utils/pdm_lock.rs: the *_lock_edits functions are identical, and the pair_* functions differ by one shape check (unreachable for Poetry; see #694).	5.4	#694	filed #694
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: line scanners in cargo_crawler.rs and vex/product.rs, plus three ad hoc toml_edit lookups (cargo_tag, which also accepts [project]; path_crate_version; declared_cargo_minor). They have drifted on BOM, [project] and dotted keys. plan_cargo_toml uses a regex scanner and toml_edit in one rewriter.	5.4; 3.7 #3	#693	filed #693; [package] readers. The hosted plan_cargo_toml regex scanner is not filed yet
E16	2	CRLF has five policies in the npm family and three for toml_edit output, and common::detect_eol contradicts LineEndings::Mixed. Target: one line-ending policy.	4.4; 5.4; 7.3		to verify
E17	2	"Is a bun lock present" has four predicates with different symlink semantics, so a dangling bun.lock symlink is present to one of them and absent to the others.	4.4		to verify
E18	3	JS helper copies: JSON-pointer escape ×2, wiring lines↔JSON ×3, name@spec split ×2, KIND_* re-spelled as literals, uneven recursion bounds, and regexes compiled inside per-dependency loops.	4.4		to verify
E19	3	Gem has three section models and two DEPENDENCIES-name parsers with different rules. Go's go_mod_edit.rs lives in vendor/, and go_crawler.rs has its own parse_go_mod_module.	5.4		to verify
E20	3	Pure codecs (bun_lockb.rs, bun_lock_text.rs, vlt_lock_text.rs) and the neutral types (Edit, Warning, LockfileEntry) live outside formats/, which creates formats↔vendor/redirect/vex cycles.	2.1; 4.5 #2; 4.7 J		to verify
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		to verify
E22	2	The JS vendor driver skeleton is copied eight times (guard_coordinates → … → a literal VendorEntry). Target: one generic driver + NpmLockBackend.	4.4; 4.7 C		to verify
E23	2	The pypi_{poetry,pdm,pipenv}.rs backends repeat one skeleton: load_*_project, classify_dependency, check_target_guards, wire_*, revert_*.	5.4		to verify
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		to verify
E25	3	Per-backend copies: cleanup_failed_stage, <eco>_service_copy (cargo, composer, gem, golang), and the service_preflight_names_exactly_* test copied seven times.	5.4; 5.8		to verify
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		to verify
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: VendorSource / PackageSource have one variant each, the SERVICE_ECOSYSTEMS refusal can never fire, ServicePolicy::new ignores its config, vend_installed! has no target, and several docs are stale.	5.6; R11		to verify
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		to verify
E30	2	Split redirect/mod.rs (17.5K lines) mechanically: model, driver, one file per ecosystem, hosted_url, and sibling test files.	3.7 #1		to verify
E31	2	Tracking: trait HostedRewriter + Outcome { per_dep }. It replaces the 20 uuid sets in RewriteResult, merge_group_delta, the 16-rule confirm() and eight parallel tables.	2.1; 3.7 #2		to verify
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 (~7.4K lines, ignores mirrors, 13 open bugs). 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		to verify
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.	6.4; 6.5		to verify
E39	3	canonicalize_pypi_name lives in crawlers/ (29 importers), and Ecosystem lives in crawlers/types.rs while LockfileEntry.ecosystem is a string. Target: core/src/ecosystem.rs.	2.1; 6.4		to verify
E40	2	vex_consumed.rs, in the CLI, is a third copy of package-manager layout knowledge. Target: move it into per-ecosystem locators in core.	6.5		to verify
E41	2	Dead discovery code: lock_inventory/wired.rs has no production caller, vex/discover/deno.rs is an empty extractor, and the pre-v5 redirect-ledger readers (~430 lines) remain.	6.4; 6.5; R11		to verify
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		to verify
E43	2	Fail closed on unmodeled resolution config in one shared place: go.work, gradle.lockfile, BUNDLE_GEMFILE, virtualStoreDir, install-strategy=linked, globalPackagesFolder, mirrors.	2.2 #3		to verify
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		to verify
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		to verify
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? This is behind 29 open issues.	§6 Q4; 2.2; 6.5		to verify
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		to verify
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
E49	2	Hosted Pipenv owned_url rejects path-prefixed --patch-server-url origins and sdists, so it refuses to rotate its own pin; there are four hosted-PyPI-URL grammars (hosted_patch_uuid, hosted_artifact_url, owned_url, is_socket_hosted_reference).	new finding	#563	fixed (#572)
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
E51	2	Yarn berry: vendored refuses a mixed-EOL root package.json (vendor_yarn_berry_mixed_line_endings); hosted's gate checks only yarn.lock and silently majority-normalizes the manifest via JsonLayout.	new finding	#628	in PR #657
E52	3	vendor/go_sum_edit.rs: free upsert_module_lines / has_module_version / remove_exact_module_version_lines have no production caller and are re-implemented by GoSumEditor (kept only as a test oracle); the pure hosted codec lives in vendor/.	new finding	#631	filed #631
E53	2	Vendored pnpm writes the root package.json with serialize_json (LF, no BOM) instead of JsonLayout: a CRLF file stays LF after vendor --revert; a BOM file is refused as "not a JSON object". npm and berry keep the layout.	new finding	#662	filed #662
E54	3	Poetry and PDM lock rewriters restore line endings with two rules (Poetry: any CRLF → all CRLF; PDM: preserve_line_endings, CRLF-only), so a mixed-EOL lock's edited unit flips to CRLF in one and LF in the other.	new finding	#695	filed #695

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 (format 1 stores no URL, so Bun resolves against its configured registry). It is never fetched, and SOCKET_NPM_REGISTRY is an undocumented knob of the restore client. The duplicated tarball and NPM_REGISTRY spellings are folded into #562.

Already fixed: none yet (E12 was fixed by #583 after it was filed, so it stays in the table).

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

Last updated 2026-10-03T15:50Z · main @ 045d7ec

ID	P	Problem	Source	Issues	Status
C01	1	Unbounded zip inflate on tamperable input. zip_bytes_match_after_hashes pre-allocates from the archive's declared size and reads with no cap, and it runs on committed .nupkg/.jar files and service archives. There are three archive caps (512/256/128 MiB).	§1 #1	#569	fixed (#587); streams members, no cap per maintainer
C02	1	ApiClient::new and plain_client() set no HTTP timeout, and blob and diff fetches have no retry, so scan, get and apply can hang in CI.	§1 #2	#570	fixed (#581)
C03	1	vendored_takeover ignores RevertOutcome.kept_artifact. It deletes the ledger entry and reports the artifact as reverted on a drift-keep, while every other revert caller honors the flag.	§1 #3; 2.4	#568	filed #568
C04	1	Planted-binary spawn: vendor/pypi_hatch.rs runs Command::new("hatch").current_dir(root) instead of process::resolve_tool. #442 didn't cover it.	§1 #4; 7.3	#613	in PR #617
C05	1	SOCKET_FORCE is bound to vendor --force, apply --force and --update --force, so forcing a self-update also forces past hash checks.	§1 #6	#615	decision #615
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	decision #648
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 (both paths) and vex each handle the proxy fallback themselves, and get's handling has a gap.	2.10 R2	#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, which has a documented token-leak history) and unblock removing 553 #[serial].	2.5; R3		to verify
C11	2	Tracking: split run_scan (1,499 lines; mode booleans referenced 91 times) into discover → select → ModeBackend::consume → render.	2.2; R5		to verify
C12	2	Tracking: move engine code out of the CLI and into core behind one orchestrator over ProjectView. That covers vendor_records_reusing (962 lines), run_redirect_selected (836) and ecosystem_dispatch.rs (816). Coordinate with E32.	2.1; R11		to verify
C13	2	Error codes are untyped. Target: a typed registry (enum Reason × Ecosystem) that generates the contract's code tables, plus a freshness test. Today ~65 codes are undocumented and 1 is phantom.	2.8; 3.7 #8; 8.5 F		to verify
C14	2	Decide: one JSON envelope. scan, get and rollback still emit a bare-string error, while the other commands emit {code, message}.	2.8; R4	#704	decision #704
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
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: ~30 inline hex::encode(Sha256::digest(..)) sites, and sha256_hex copies that compute beside a utils::digest::sha256_hex that validates. sha1_hex exists twice, and SRI formatting is inlined three times.	4.4; 7.3	#706	filed #706
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; a fifth grammar (Uuid::parse_str in python_script.rs)
C19	2	Env truthiness has three vocabularies, and there are 37 inline "empty means unset" reads and four home-directory resolvers.	7.3		to verify
C20	2	Purls have two builder families in utils/purl.rs, plus 78 hand-built pkg: strings and 58 starts_with("pkg:<type>/") checks that bypass Ecosystem::from_purl.	6.4; 7.3		to verify
C21	3	utils/fs.rs has six atomic writers, and separate stage + rename code lives in blob_fetcher and update/. Writes that bypass utils::fs (blob_fetcher.rs) escape group commit.	5.7; 7.3		to verify
C22	2	Telemetry has 17 near-identical track_* wrappers, builds a new HTTP client for every event, and threads the token and org through 125 signatures. Target: one track(Event) with a shared client.	7.5; R15		to verify
C23	2	Dead code: PatchSources::mem_blobs is never Some. save_redirect_state and its group-commit entry journal a file that nothing writes. The switched_off("group_commit") oracle path, the Pypi/LauncherCache update channels and --vendor-source (one value) also remain.	7.4; 7.6 #3; 5.6		to verify
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. Target: one engine.	7.4; 7.6 #4		to verify
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		to verify
C26	3	apply.lock spends ~554 lines deleting the lock file on exit, and taking the lock replays the vendored group-commit journal, coupling vendored crash recovery to every command.	7.4		to verify
C27	3	Agent-mode sidecars don't handle Maven files at all. Verify whether in-place Maven patches leave stale checksum files behind.	7.4		to verify
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		to verify
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		to verify
C30	2	No socket-patch-test-support crate: binary() is defined in 102 files and git_sha256 in 84, there are 14 divergent scrub_socket_env, xorshift is implemented four times, and the VEX helpers are forked.	6.4; 8.5 D		to verify
C31	3	There are 207 test executables; the target is ~25. This needs C10 first.	8.5 A		to verify
C32	3	328 exact-sentence assertions should become --json/errorCode checks plus snapshots. Triage the 402 covgap tests, 136 of which assert human text.	2.5; 8.5 G/H		to verify
C33	3	CLI_CONTRACT.md (332 KB) should be a generated reference (flags, env vars, codes, exit codes) plus ≤300 lines of prose, with a freshness test. Also decouple docs/testing from the validation scripts.	8.3; 8.5 F/I		to verify
C34	3	Decide: the command model. A read-only scan, plus fix, undo, sync and check, with mode inferred from project state. This folds remove, rollback and vendor --revert, and per-command flags replace the 27 globals.	§4; 2.9; R6/R8		to verify
C35	3	Decide: drop the deprecated spellings and embedded --vex, and give SOCKET_FORCE per-command names.	R9; R10		to verify; SOCKET_FORCE part is #615
C36	3	Decide: the futures of agent mode and of the self-update binary swap.	§6 Q2; 7.5		to verify
C37	2	Patch blob/diff downloads (fetch_binary) buffer the whole body with no size cap; vendor and self-update use the shared read_capped.	new finding	#571	in PR #607
C38	2	The public-proxy per-package fallback keeps a private cap of 10, ignoring SOCKET_API_CONCURRENCY, the proxy cap of 4 and the fd-limit rule; registry_concurrency() has no caller.	new finding	#614	filed #614
C39	2	The 401/403 proxy fallback is missing beyond get search: apply, rollback and repair blob/diff downloads and vendor eject view fetches fail on a stale token, although the contract promises eject get's fallback. Fix: the fallback moves into ApiClient.	new finding	#647	filed #647
C40	3	SOCKET_API_CONCURRENCY and SOCKET_WALK_THREADS are read by core but documented nowhere; only clap-bound env vars have a guard test.	new finding	#678	filed #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

Handed off (to the CI janitor): report-only coverage and LTO docker-base off PRs; e2e from 148 to ~50 legs; a reusable compat workflow; no per-leg compiles; dead CI path filters (review 8.2, 8.5 B/C/E).

Rejected / not a defect: C06. On 045d7ec, the nested apply reads none of the fields ..GlobalArgs::default() resets except offline, which get/scan refuse up front; the hosted opt-outs reach core through process env. The get ↔ scan cycle and the fake ApplyArgs stay in C12.

Already fixed: none yet.

Refactor routine (refactor, hourly, highest leverage first)

Last updated 2026-10-03T16:05Z · main @ 045d7ec

In flight:

• #574: one vlt registry_base following vlt's DepID hydration. Issues vlt lock inventory and hosted restore resolve a node's registry differently #562 (E02, E03). State: ready (Ready for review). It awaits human approval.
• #602: crawler project-tree reads go through utils::fs::read_regular_*, plus a crawlers::architecture_tests guard against bare reads. Issue NuGet and Cargo crawlers hang on a FIFO at obj/project.assets.json or vendor/<crate>/Cargo.toml #592 (E06). State: ready, handed to the PR burn-down.
• #607: blob and diff downloads stream to disk through BinaryBody; one download_entries loop replaces the blob and diff copies. Issue Patch blob and diff downloads buffer the whole response body with no size cap #571 (C37). State: ready, handed to the PR burn-down (CI green, 338 checks; Bugbot clean on ae928ae).

Merged:

• #572: one hosted-PyPI-URL recognizer for hosted and vendored Pipenv. Issues Pipenv recognizes hosted PyPI patch URLs with two private grammars that disagree with the shared one #563 (E04, E49). Production +31 / −48, tests +174 / −37 (approx.).
• #581: one ApiTimeouts policy (10 s connect, 60 s idle read) on both ApiClient reqwest clients. Issue The patch API client has no request timeout, so scan, get and apply hang forever on a stalled server #570 (C02).

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

#	Candidate	B	U	D	R	Score	Note
1	#706 (C17): one utils::digest compute API (sha256_hex, sha1_hex, sha512_sri); delete the jvm, ledger_snapshots, group_commit, maven_repo, npm_pack and bun_lock copies	0	1	5	L	7	skipped: jvm/mod.rs, maven_repo.rs, group_commit.rs changed by open PRs #690 and #646, bun_lock.rs by #689; unblocks #707 being fixed in one place
2	#693 (E15): one toml_edit Cargo.toml package reader for crawler, VEX, cargo_tag and path_crate_version; delete the crawler's line scanner	1	0	3	L	6	skipped: cargo_crawler.rs changed by open PR #602, vendor/cargo.rs by #598
3	#707 (C41): one case-insensitive hash comparison for agent-mode apply/rollback and vendored verify	1	0	2	L	5	skipped: patch/apply.rs/patch/rollback.rs changed by open PRs #634, #646 and #690; simpler after #706
4	#663 (E07): one addressed package-lock entry walk for inventory, vendored, hosted and restore	0	1	4.5	M	4.5	skipped: npm_lock.rs/lock_inventory/npm.rs changed by open PRs #589, #660 and #689, redirect/mod.rs/upstream/npm.rs by #657 and #597
5	#568 (C03): takeover honors kept_artifact via vendored_backend's revert step	1	0	1	L	4	skipped: scan/hosted.rs changed by open PRs #598, #646, #657, #684 and #690

At capacity (3 open, all ready, all reviewed "ready to merge") on 2026-10-03T01:05Z; re-ranked with the new issues #628–#631, no new work started (blockers #597, #598, #602, #607, #610 still open). Next: #631 (E52, go.sum oracle delete + move to formats/golang), score 3.5 (D3.5 R L), skipped while #597 changes redirect/mod.rs. Dropped C07 from the queue: needs an owner decision on the fallback route. Taken: #571 (C37) in #607, score 2 (B1 D1 R M). Re-ranked 2026-10-03T04:00Z with #647 (C09/C39) and #649 (C08, hygiene, score ≈1); still at capacity, no new work. #614 (C38, score 4) drops to sixth. #648 is a decision. Re-ranked hourly 2026-10-03T05:58Z–11:58Z: no change except #662 (E53) and #663 (E07) entering; #628/#629 left the queue (fixer PR #657 references them); #675 (C16), #676/#677 (C15) and #678 (C40) score ≤2.5 and stay outside the top five (api/client.rs held by #607 and #610). Bughunt #685 may share #593's XML-walker root cause. Re-ranked 2026-10-03T13:05Z with #693 (E15), #694 (E13) and #695 (E54, Poetry/PDM line-ending drift; B1 D0.5 R L, score 3.5, simpler after #694): still at capacity, nothing merged, no steering. #694 narrows E13 to the shared engine (format walkers stay per format), so it replaces the earlier set-aside. #630 and #662 drop to sixth and seventh. Re-ranked 2026-10-03T13:56Z: no new arch-audit/refactor issues (#696 and #697 are bughunt bugs outside the queue), nothing merged, no steering, blockers #597, #598 and #602 still open; queue unchanged. Re-ranked 2026-10-03T15:00Z: still at capacity (#574, #602, #607 ready, awaiting human merge), no new arch-audit/refactor issues (#699, #701 are bughunt bugs), nothing merged, no steering; queue unchanged. #694 stays next when capacity frees. Re-ranked 2026-10-03T16:05Z: still at capacity (#574, #602, #607 ready, awaiting human merge), nothing merged, no steering. #694 and #695 left the queue: fixer PR #703 claims both. New #706 (C17) ranks first, #707 (C41) third; #705 (C18, B0 U0 D4 R M, score 2) sits outside the top five (api/client.rs held by #607/#610, apply.rs by #634/#646/#690). #704 is a decision. #593 (score 4) drops to sixth.

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.
• Maintainer steering (2026-10-02, on 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): 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: Read NuGet and Cargo crawler project files through the FIFO-safe reader (#592) #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.

[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 @ 045d7ec on 2026-10-03 by audit-core. Owner: audit-core.

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

Function	Location	Lines
run_scan	scan/mod.rs:1436–2934	1,499
rollback::run	rollback.rs:1069–2052	984
vendor_records_reusing	vendor.rs:1971–2932	962
run_redirect_selected	scan/hosted.rs:639–1474	836
remove::run	remove.rs:315–1111	797
get::run	get.rs:2507–3141	635
rollback_patches_inner	rollback.rs:2059–2658	600
apply_patches_inner	apply.rs:1633–2205	573

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 2153 vs boxed_run_redirect_selected 2641, boxed_vendor_json_path Nick (@2341) vs boxed_vendor_interactive_path 2878, download_and_apply_patches_with 2305 vs 2897.

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:491) 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 super::scan:: 28 times (hosted engine, vendor step, ScanMode), and scan's agent mode imports get::download_and_apply_patches_with/DownloadParams/DownloadRun.
• Other edges: remove→rollback (8 refs), vendor→vex (8), apply→vex (6), vendor↔rollback, 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.
• A bug caused by the bypass (verified by reading).
  • Core's RevertOutcome.kept_artifact (core/vendor/mod.rs:664–673) says that after a drift-keep, callers "must ALSO keep the state.json entry".
  • vendored_takeover (scan/hosted.rs:1732–1790) never reads kept_artifact. On success it drops the ledger entry, saves, and emits redirect_takeover_reverted_vendored ("reverted its vendored wiring, ledger entry, and committed artifact"). Reproduced on 1169ae6: after the takeover the ledger entry is gone and the artifact dir is still there. C03 · filed Vendored→hosted takeover drops the vendored ledger entry when the revert drift-keeps the artifact #568
  • On a drifted lock this orphans the artifact and loses the only recorded originals.
  • Every other revert caller handles the flag (vendor.rs ×6, gc.rs, vendored_backend).
  • Needs a regression test.

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 553 #[serial] attributes (plus 182 in src).
• 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.

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 @2192/2212 vs 2455; classified_rows @2231/2476; partition_agent_selection @2248/2668; plan_kept_rows @2249/2696
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 C39 · 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.
• Deprecated spellings and aliases: scan --apply (hidden), scan --vendor (hidden), --sync, get --no-apply, and the download and gc aliases. resolve_mode_flags (scan/mod.rs:205–255) exists mainly to reconcile these.
• 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. C05 · decision Decide: give SOCKET_FORCE per-command names so forcing a self-update doesn't also force apply and vendor #615
• VEX passthroughs: 5 --vex-* flags × 3 host commands = 15 flag instances, with the env vars bound twice.
• 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 always emits a bare string, but 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. C14 · decision Decide: one shape for the --json top-level error (scan and get emit both a string and a {code, message} object) #704
• Status is partialFailure in the envelope but partial_failure in the legacy shapes.
• 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 and golang. 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); give SOCKET_FORCE per-command names	−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 (816 production lines of pure crawler fan-out), vendor_records_reusing and the disk hosted orchestration into core behind one orchestrator over ProjectView	−2K to −4K over time	High; incremental

New findings since the review

• C39 · 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.

(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 @ 203e092 on 2026-10-02 by audit-ecosystems. 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

That is about 27K production lines for hosted mode, 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:200-260). It holds 20 per-ecosystem uuid sets, such as confirmed_cargo_uuids, refused_pdm_uuids and vlt_foreign_uuids. Two places consume them:

• merge_group_delta, which destructures every field (:503-557);
• engine::confirm, an ordered if-chain of about 16 per-ecosystem rules keyed on purl prefixes and those sets (hosted/engine.rs:1239-1315).

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)
440	plan_cargo_toml (mod.rs:2409)
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 17.5K-line god module. Its 6.2K production lines mix six concerns:

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;
6. 11.4K lines of tests (262 tests, 80 of them for cargo).

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 takeovers are refused. 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: three readers. Hosted uses regexes (mod.rs:4942-4975), and its splice anchors (insert_nuget_source, nuget_mapping_open_end) are comment-blind regexes too (Hosted NuGet splices the Socket source (and mapping) into a commented-out &lt;packageSources&gt; / &lt;packageSourceMapping&gt; block, so every restore fails NU1100 while scan reports success and its in-run VEX attests not_affected #585); vendor's nuget_feed.rs blanks comments and then scans; formats::nuget::parse_config is a bounded tokenizer used by upstream and VEX. Hosted restore's remove_source adds a fourth regex reader. E11 · filed Read and splice nuget.config through formats::nuget in hosted, vendored and restore #594; hosted part in PR Unify hosted NuGet routing and XML splice anchors #597
  • Likely bug (verified by reading the code): hosted nuget_package_source_keys (mod.rs:4956) runs its regex over raw text without masking <!-- -->. A commented-out <add key="…"> therefore suppresses the nuget.org seed. E01 · in PR 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. 7,446 production lines: 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. 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;
• 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.
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):

   • 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 20 RewriteResult sets, merge_group_delta and most of confirm(). The "driver" rules for pdm/vlt/uv become drives().

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/.

---

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 @ 045d7ec on 2026-10-03 by audit-ecosystems (§4.4 pnpm, berry gates, package-lock walks and JSON writers 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 is only the version sniff (58 production lines), and its doc says the grammars "are still read through their current homes" (formats/yarn/mod.rs:4-6).
  • 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	1,853	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 · filed #663
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 five places with different rules:

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 · fixed (#583)

The vendor driver skeleton is copied eight times. npm_lock, pnpm, pnpm-legacy, yarn-berry, yarn-classic, bun_lock, bun_binary and vlt all repeat the same sequence:
guard_coordinates → read_project → stage_patch_pack (×2) → already_patched_result → write_marker_or_warn → a literal VendorEntry { … pdm: None, pipenv: None, poetry: None, uv: None, … }.
Each shares 55-67 distinct lines with vendor_pnpm. read_project, preflight_package(s) and revert_*_opts exist in 7-9 files each. E12 · fixed (#583)

Yarn berry project gates are written twice. E09 · in PR #657; compressionLevel reader already shared (#508)

• 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. E51 · in PR 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. It still writes vendored pnpm's root package.json on vendor and revert (pnpm_lock.rs#L326-L327), which is parsed without BOM support, so a CRLF package.json comes back LF after vendor --revert. E53 · filed Vendored pnpm rewrites a CRLF package.json as LF, and vendor --revert does not restore it #662
  • redirect::serialize_json: fixed 2-space, LF; now used only for NuGet packages.lock.json (hosted and restore).
• Wiring lines ↔ JSON: three copies with different handling of malformed input (pnpm_lock.rs:3162, yarn_classic_lock.rs:1088, recover.rs::lines_of).
• 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 at lock_inventory/vlt.rs:141 and bun_lockb.rs:235. The latter hard-codes registry.npmjs.org and ignores SOCKET_NPM_REGISTRY. There are two NPM_REGISTRY constants, one with a trailing slash and one without. E02 · in PR Resolve vlt registry bases through one shared function (#562) #574; partly not a defect
• vlt registry_base: two divergent implementations (upstream/vlt.rs:55 vs lock_inventory/vlt.rs:104) with different fallback orders and unknown-alias behavior. E03 · in PR Resolve vlt registry bases through one shared function (#562) #574
• "Is a bun lock present": four predicates with different symlink semantics (lock_inventory/bun.rs:40 uses lstat; hosted/engine.rs:255, hosted/vlt.rs:53 and bun_lock.rs:623 follow symlinks). A dangling bun.lock symlink is "present" to one and "absent" to the others.
• 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 sites), state.rs and bun_lock.rs.
• 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), but vendored pnpm's package.json writer still normalizes to LF (E53 · filed Vendored pnpm rewrites a CRLF package.json as LF, and vendor --revert does not restore it #662);
• 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).

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.
   • formats/pnpm/mod.rs:36-37 and formats/bun/mod.rs:11 import from vendor, and formats/pnpm/hosted.rs imports patch::redirect.
   • 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.
3. God files and long functions.
   • pnpm_lock.rs is 8,515 lines.
   • Longest drivers: vendor_yarn_berry 396 lines, vendor_npm 314, vendor_bun 304, vendor_pnpm_legacy 290, vendor_pnpm 251, 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 · filed #663	~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. E51 · in PR Fix yarn berry project gates drifting between modes (#628, #629) #657
• Vendored pnpm writes the root package.json with serialize_json instead of JsonLayout: a CRLF file is rewritten LF and stays LF after vendor --revert, and a BOM file is refused as "not a JSON object". npm and berry keep the layout. E53 · filed Vendored pnpm rewrites a CRLF package.json as LF, and vendor --revert does not restore it #662

---

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 @ 045d7ec on 2026-10-03 by audit-ecosystems (5.4 Python and Cargo only). 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,535, 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;
• cargo, golang and composer ignore three of their parameters (_sources, _force, let _pristine_src = …into() at cargo.rs:768-779).

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

16 production sites enumerate the ecosystems, and each is a place a new ecosystem must be added:

1. vendor/path.rs:43 ECOSYSTEM_DIRS
2. vendor/path.rs:233-320 leaf_to_purl (8 arms)
3. vendor/mod.rs:754-772 service_preflight (7 arms)
4. vendor/mod.rs lock_text_refusals
5. vendor/mod.rs:~395-410 harvest suffix branches
6. verify.rs:526 artifact_is_file_shaped
7. redownload.rs:166-302
8. prestage.rs:350 PRESTAGED_ECOSYSTEMS
9. lock_inventory/mod.rs:250
10. lock_inventory/recover.rs:42-144
11. ledger_snapshots.rs:55 WHOLE_FILE_KINDS
12. state.rs:439+ carry_forward_wiring
13. CLI vendor.rs:137 SERVICE_ECOSYSTEMS
14. CLI vendor.rs:194 vendor dispatch
15. CLI vendor.rs:241 revert dispatch
16. CLI vendor.rs:261 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:

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

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 writers (nuget_feed.rs, maven_repo.rs) never use the shared readers (formats::nuget::parse_config, formats::maven::parse_pom) that VEX and redirect use, so reader and writer can disagree about what a file contains. E11 · filed Read and splice nuget.config through formats::nuget in hosted, vendored and restore #594; hosted part in PR Unify hosted NuGet routing and XML splice anchors #597
• The Maven/Gradle share of the open backlog (22 of 88 issues, for example 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") is mostly this.

Python:

• utils/poetry_lock.rs and utils/pdm_lock.rs are near-twins with mirrored function sets (rewrite_*_lock, *_with_edits, plan_*_rewrite, *_lock_edits, *_lock_fragments, extend_span, pair_*).
  • After renaming, poetry_lock_edits and pdm_lock_edits are identical.
  • pair_* differs by three lines: pdm has a shape check that poetry lacks. For Poetry this is unreachable, because a rewrite pairs fragments of one document before and after its own edit, so the fragment count cannot change.
  • next_header_end, the rewrite struct with edits(), the parse holder and the finish step (render → reparse → pair → splice) are also copied. The finish steps differ only in their line-ending rule, which is a real drift: on a mixed-line-ending lock, Poetry turns the edited unit CRLF and PDM turns it LF (poetry_lock.rs#L366-L369, pdm_lock.rs#L268). E13 · filed Share the poetry.lock and pdm.lock fragment-splice engine instead of keeping two copies #694 E54 · filed Poetry and PDM lock rewrites flip a mixed-line-ending lock's edited unit in opposite directions #695
• 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_*
• 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 · fixed (Recognize hosted Pipenv references through one shared grammar (#563) #572)

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; [package] readers. The hosted plan_cargo_toml regex scanner is not filed yet

Gem: vendor/gem.rs imports three token helpers from formats::gem and keeps its own section model. formats/gem itself has two section models, and there are two DEPENDENCIES-name parsers with different rules.

Go: go_mod_edit.rs is properly shared (9 users) but lives under vendor/. crawlers/go_crawler.rs:63 still has its own parse_go_mod_module.

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;
  • poetry_lock has its own inline rule: any CRLF turns the whole rendering CRLF, which disagrees with python_lock on mixed files E54 · filed Poetry and PDM lock rewrites flip a mixed-line-ending lock's edited unit in opposite directions #695;
  • cargo_manifest aligns lines with an LCS diff.

  There are also ad-hoc helpers in four more files.

• Per-backend copies:

  • cleanup_failed_stage is byte-identical in cargo and gem, and one line different in composer.
  • <eco>_service_copy (fetch → settle → claim_prestaged-or-extract → afterHash check → swap) is repeated for cargo, composer, gem and golang.

• 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: unbounded zip inflate (verified)

vendor/common.rs:305-330 zip_bytes_match_after_hashes decompresses archive members with no size cap. It also pre-allocates Vec::with_capacity(entry.size() as usize) from the archive's own declared size.

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).

Its twin vendor/mod.rs:526 capped() explicitly guards against zip bombs with a 64 MiB cap. The codebase also has three different archive size caps: 512 MiB (common.rs:278), 256 MiB (mod.rs:342) and 128 MiB (registry_fetch.rs:22).

A malicious PR that commits a crafted .nupkg can make CI's vendor --check / vex allocate without bound. Fix: route every zip read through one capped reader with one cap constant.

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).
• PackageSource has one variant.
• SERVICE_ECOSYSTEMS lists every ecosystem, so its refusal can never fire.
• 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.
• 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 (1,535 lines) is now really archive extraction plus integrity checks plus the hosted-restore HTTP client. It is misnamed and misplaced.
• --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; ~6,300 inline tests; ~1.7K CLI e2e): two backends for one ecosystem.

  • The legacy single-POM backend (maven_repo.rs) uses whole-file pom snapshots.
  • 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.
  • 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.
  • Merge the two backends into one planner with a Shape::Single variant, drop the "jvm" alias, and make --maven-config a vendor/scan --mode vendored flag.

• 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.

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

• E54 · filed Poetry and PDM lock rewrites flip a mixed-line-ending lock's edited unit in opposite directions #695: the Poetry and PDM lock rewriters restore line endings with different rules, so a mixed-line-ending lock's edited unit becomes CRLF under Poetry and LF under PDM; see 5.4.
• E49 · fixed (Recognize hosted Pipenv references through one shared grammar (#563) #572): 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 @ 045d7ec on 2026-10-03 by audit-ecosystems. 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); 13 extractors in fixed order, 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 parsed again at go_crawler.rs:63 and product.rs:175
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, including lock_inventory, vex::discover, utils::purl and patch::redirect. 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.
• 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.
• vex/discover/deno.rs is an empty extractor.

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 (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.
  • 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 16 open "VEX attests not_affected while unpatched" bugs come from. 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. Three project-tree reads predate the FIFO-safe read discipline and hang on a planted FIFO (verified by execution): nuget_crawler.rs:506 (obj/project.assets.json) and the cargo vendor/<crate>/Cargo.toml reads at cargo_crawler.rs:289 and :401. The Python .venv read is guarded by is_file(). E06 · in PR 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

None yet.

---

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 @ 045d7ec on 2026-10-03 by audit-core. Owner: audit-core. Only the timeout, blob/diff body, zip-read, process-spawning, API-pacing, URL-builder, retry, batching, hashing and UUID passages have been re-checked; the rest is as of 2463257.

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,839 / 3,038)	5,028	6,434	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,839 production 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.
• ~320 lines: credentials. Env/config resolution, a token-shape lint, org auto-resolve.
• ~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

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 only (an HTTP-date is ignored, shown by execution on 045d7ec)	a second 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/…. C07 · decision #648

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)
• 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: 60 s timeout, no retry.
• 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:

  • About 23 production sites inline hex::encode(Sha256::digest(..)), and 3 inline hex::encode(Sha1::digest(..)). C17 · filed Compute sha256, sha1 and sha512-SRI digests through utils::digest instead of inline copies #706
  • Private sha256_hex copies exist in ledger_snapshots.rs, 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 validates that a string is 64-hex, while the copies compute a digest. Same name, different meaning.
  • sha512_sri is public in redirect/vlt_preflight.rs, yet two vendor files re-inline it, and six test modules each define their own.
  • The 64-hex validator exists three times: apply::is_valid_blob_hash, client::is_valid_sha256_hex and digest::is_hex(s, 64).

• 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; a fifth grammar (Uuid::parse_str 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 (unvalidated build_* and validated *_purl). vex/product.rs hand-rolls a third. 48 production format!("pkg:…") sites and 58 starts_with("pkg:<type>/") checks bypass Ecosystem::from_purl.

• Env truthiness: three vocabularies.

  • "1"|"true" in env_compat.rs;
  • "1"|"true" separately in telemetry.rs;
  • 1|true|yes|on|y|t in socket_cli_config::env_truthy, which update_notifier imports.

  There are also 37 inline "empty means unset" reads in 22 files and at least four home-directory resolvers.

• Atomic writes: utils/fs.rs has six writers. atomic_write_sync re-implements stage_and_rename + commit_stage in blocking form. Separate stage+rename code also exists in blob_fetcher, update/download.rs and update/swap.rs.

• Process spawning is well centralized in process.rs::resolve_tool/command_for, with one exception: vendor/pypi_hatch.rs:118 runs Command::new("hatch").current_dir(root) (verified by execution on 045d7ec). C04 · in PR Fix vendored Hatch running a planted hatch (#613) #617 That is exactly the planted-binary pattern process.rs:23-33 documents as unsafe: "a bare Command::new("git") would execute a git planted in the repository being scanned".

7.4 Agent mode

Footprint:

• core: apply 1,132, rollback 617, sidecars 708, diff 100, package 333, blob_fetcher 603, manifest 507;
• CLI: apply 2,237, fetch_stage 440, repair 784;
• 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.

The safety model is sound and worth keeping:

• 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 have identical fields. fold_copy_result, the pnpm peer-copy fan-out and the sidecar boundary are each written twice. Rollback is apply with before/after swapped, plus deleting files the patch created, and could be one engine.

--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.

• Recommendation: make file the default (keep diff as an alias for one major), then delete patch/diff.rs, the diff branches in blob_fetcher/fetch_stage/repair, and qbsdiff.
• Saving: about 600 production and 1,000 test lines, plus one dependency.

Sidecars (patch/sidecars/, 708 production / 1,312 test lines) are post-apply fixes for package-manager checksum files:

• cargo: rewrite .cargo-checksum.json;
• NuGet: delete .nupkg.metadata;
• PyPI, gem and Go: advisory text only.

Maven sidecars are not handled at all. This code exists only for in-place mode.

apply.lock is 554 production lines. 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. Leaving a gitignored lock file on disk (the convention every package manager uses) would cut about 150 lines.

Dead path (verified): PatchSources::mem_blobs is never Some in production, but its doc still says vendor flows stage content there.

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 Pypi and LauncherCache channels that v5 no longer publishes. Two metadata strategies, a separate lock, and its own stage writer. Keep the notifier; replace --update with "re-run install.sh" (or keep a much thinner swap). Up to −1K production and −3K test lines.
Telemetry	891 / 864	17 near-identical track_* wrappers (~450 lines); a new HTTP client per event; endpoint logic duplicated; the CLI threads token/org through 125 signature sites. Collapse to one track(Event) with a shared client (~−300).
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. But socket_yml.rs builds its own YAML node tree on serde-saphyr's event parser (:36-320) to read 8 keys, with edit-distance "did you mean" hints and repository-ownership trust checks. The deserialize feature is enabled, but nothing uses it through serde. Replace with serde + deny_unknown_fields plus a small strictness check (~−500).
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. Make file the default download mode and delete the diff machinery: −600 production, −1K tests, −1 dependency. Low risk.

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.

3. Delete the verified dead and legacy code: mem_blobs, save_redirect_state and its group-commit LEDGERS entry, the Pypi/LauncherCache update channels, and the switched_off("group_commit") oracle path. −150 production, −300 tests.

4. Fold rollback into the apply engine (swap hashes, keep a delete branch for created files): −300 production.

5. One telemetry track(Event) with a shared client: −300.

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;
   • fix the bare hatch spawn.

   Saves about −200.

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

9. Replace the hand-rolled socket.yml tree with serde: −500.

10. Re-scope self-update: keep the notifier, consider dropping the binary swap.

New findings since the review

• C37 · in PR Stream patch blob and diff downloads to disk (#571) #607 Patch blob and diff downloads (fetch_binary) buffer the whole body with resp.bytes(), while the vendor and self-update downloads use the shared read_capped (256 MiB). On 1169ae6 a 600 MiB blob response was buffered in full.
• C38 · filed The public-proxy per-package fallback runs 10 requests in flight, ignoring SOCKET_API_CONCURRENCY and the proxy cap of 4 #614 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.

---

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 @ 045d7ec on 2026-10-03 by audit-core. Owner: audit-core. Only the repository-hygiene passages (stray launch.json, "DESIGN §" references) and the contract's env-var tables 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. 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 102 files (6 variants);
  • fn git_sha256 in 84 files (9 variants), although core exports compute_git_sha256_from_bytes;
  • copy_dir_recursive in 26 files;
  • scrub_socket_env in 15 files with 14 different bodies, which directly undermines hermeticity.
• 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 26,916 lines and 402 tests. 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 553 #[serial] attributes 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. 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 compiles the full test tree 8 times: test ×3, 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 148 legs (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.

• Report-only coverage still runs on every PR:

  • 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) that gate nothing.

• Nine *-compatibility.yml files (2,041 lines) 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: 1,638 lines and 332 KB. 48 lines exceed 1,000 characters, 12 exceed 3,000, and the longest is 9,320 characters (line 164).
• History mixed into reference: 177 v5.0 annotations and 40 MAJOR/BREAKING markers.
• 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.
  • About 65 redirect_* codes that src emits are undocumented, e.g. redirect_cargo_missing_cksum.
  • Only the vlt codes are checked mechanically.

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	Move report-only coverage and docker-base off PRs	≈74 runner-min and 12 jobs per run	Low
C	Cut the PR e2e tier from 148 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	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

• C40 · filed 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: not yet re-checked; the content is as of 2463257. Owner: audit-core and audit-ecosystems.

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;
• --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-02: architecture refactor run

• main: 203e092
• At capacity: Recognize hosted Pipenv references through one shared grammar (#563) #572, Resolve vlt registry bases through one shared function (#562) #574, Bound patch API connects and stalled reads (#570) #581 open, all state: ready, no maintainer questions, none blocked. No new work started.
• Re-ranked: Hosted NuGet mapping reads commented-out package sources #561 (E01) still top but blocked by open PR Fix Gemfile rewrites duplicating gem declarations (#482, #548) #552 on redirect/mod.rs; Vendored→hosted takeover drops the vendored ledger entry when the revert drift-keeps the artifact #568 (C03) blocked by open PR Fix PyPI vendored to hosted takeover being refused (#328) #503 on scan/hosted.rs; E37 next when a slot frees (its vendor/gem.rs copy is also touched by Fix Gemfile rewrites duplicating gem declarations (#482, #548) #552).
• Claimed/released: none. Merged: none.

[github-actions[bot]]

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

main @ 203e092. There were no new maintainer replies in the discussion. The open arch-audit issues in this area are #561 (E01), #562 (E02/E03, in PR #574) and #563 (E04/E49, in PR #572); none had merged.

Reconciled.

• E12 is now in PR #583, a refactor-labelled PR that shares pnpm vendoring and revert across the v9 and legacy dialects. It has no issue.
• Hosted NuGet mapping reads commented-out package sources #561 was re-checked and is still present. The code moved about 600 lines, so I posted fresh permalinks.

Verified on main and filed. Every bug below was reproduced with a unit test run twice. The probes were not committed.

• E06 is still present, and it is wider than the review said. A FIFO at obj/project.assets.json hangs NuGetCrawler::get_nuget_package_paths. A FIFO at vendor/<crate>/Cargo.toml hangs both CargoCrawler::crawl_all and find_by_purls. Each was still pending after 3 s. The review's Python example (.venv) is guarded by is_file(), so it isn't a hang. Filed #592 (bug).
• E05 is still present: cargo, go, maven, nuget and deno all return the whole machine cache in project mode once a marker file exists. Filed tracking issue #595. Its first two children are the existing bugs Project-mode NuGet agent scan patches, and VEX attests, packages the project doesn't depend on (the crawler lists the whole ~/.nuget/packages) #427 (NuGet) and Maven hosted scan pins, and VEX attests, artifacts the project doesn't depend on (the crawler lists all of ~/.m2) #265 (Maven), which got cross-link comments.
• E11 is still present. nuget.config is handled by six private paths: three key readers, two regex anchor/remover sets, and a vendored blank-and-find writer. There are also four copies of the config-name list. Filed #594 (refactor, pm:nuget). Its symptoms are Hosted NuGet mapping reads commented-out package sources #561 and Hosted NuGet splices the Socket source (and mapping) into a commented-out &lt;packageSources&gt; / &lt;packageSourceMapping&gt; block, so every restore fails NU1100 while scan reports success and its in-run VEX attests not_affected #585, and Hosted NuGet splices the Socket source (and mapping) into a commented-out &lt;packageSources&gt; / &lt;packageSourceMapping&gt; block, so every restore fails NU1100 while scan reports success and its in-run VEX attests not_affected #585 got a cross-link comment.

New finding: E50. Hosted rewrite_nuget rewrites 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, and its own test says so. In the repro, a net6.0 entry at 12.0.3 became resolved: 13.0.3 with the patched hash in hosted mode, and was left untouched by vendored edit_lock. Upstream restore is version-blind as well, so it can't put the 12.0.3 pin back. There are four lock walkers in total. Filed #593 (bug, pm:nuget).

Searched without filing:

• Maven POM reads in maven_crawler.rs (L498, L813) read the machine repository, not the project tree, so they are left out of NuGet and Cargo crawlers hang on a FIFO at obj/project.assets.json or vendor/<crate>/Cargo.toml #592.
• normalize_nuget_version has one definition with three callers, so there is no duplication.
• Hosted mapping to a source listed in disabledPackageSources is harmless.

Living document: check lines set on Parts 3 and 6. Tokens added for E05 and E06 (Part 6.6), E11 (Parts 3.4 and 5.4) and E12 (Part 4.4). Moved line numbers were corrected, and an E50 bullet was added under Part 3's new findings.

Next backlog rows: E37 (byte-identical is_safe_*_coordinate; the refactor queue wants it), E07 (package-lock walks), E08 (yarn grammars), E09 (berry gates), E10 (Maven/Gradle XML half).

---

Generated by Claude Code

[github-actions[bot]]

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

• main: 203e092
• At capacity: Recognize hosted Pipenv references through one shared grammar (#563) #572 and Bound patch API connects and stalled reads (#570) #581 are state: ready. Resolve vlt registry bases through one shared function (#562) #574 is blocked; a reviewer asked to make the ~~ / legacy ·· correction themselves, so hands off.
• Re-ranked: the new Read and splice nuget.config through formats::nuget in hosted, vendored and restore #594 (E11, one nuget.config reader, fixes Hosted NuGet mapping reads commented-out package sources #561 and Hosted NuGet splices the Socket source (and mapping) into a commented-out &lt;packageSources&gt; / &lt;packageSourceMapping&gt; block, so every restore fails NU1100 while scan reports success and its in-run VEX attests not_affected #585) is now top at score 11, but redirect/mod.rs is changed by open PR Fix Gemfile rewrites duplicating gem declarations (#482, #548) #552. Vendored→hosted takeover drops the vendored ledger entry when the revert drift-keeps the artifact #568 is still blocked by Fix PyPI vendored to hosted takeover being refused (#328) #503, and the new Hosted NuGet rewrites packages.lock.json entries at other versions of the patched id #593 by Fix Gemfile rewrites duplicating gem declarations (#482, #548) #552. NuGet and Cargo crawlers hang on a FIFO at obj/project.assets.json or vendor/<crate>/Cargo.toml #592 (E06, FIFO-safe crawler reads) is the first eligible one. zip_bytes_match_after_hashes inflates committed .nupkg/.jar entries with no size cap #569 dropped because it has open PR Stream ZIP member hashes during vendored verification #587.
• Claimed/released: none. Merged: none.

[github-actions[bot]]

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

Merged: #572 (merge 950bfc5), fixing #563. Hosted and vendored Pipenv now share lock_inventory::pypi::hosted_pypi_reference, and both private hosted-PyPI-URL grammars are gone.

Register: E04 and E49 are now fixed (#572).

Living document: Part 5.4 (doc/05-vendored.md) rewrote two passages line-locally so they describe main: the "Hosted-URL recognition is duplicated" bullet and the E49 new-findings bullet.

CI notes from the PR: it got 3 transient failures, and each passed on its one re-run:

• the PDM platform-windows hosted cell;
• the vlt rc.14 hosted-optional cell, plus lock-diff downstream of it;
• e2e_safety_pnpm, after a connection reset from patches-api.

CodeQL flagged a test assert message that printed the refusal detail; that was fixed in ff3ef3e.

[github-actions[bot]]

[agent] 2026-10-02T20:05Z: architecture refactor run

Merged: #581 (merge 045d7ec), fixing #570. Both ApiClient reqwest clients take one ApiTimeouts policy (10 s connect, 60 s idle read). In review, the reviewer added a fix: a stalled JSON body now reports ApiError::Network. The PR also carried the yarn-berry bench fixture correction from #587, after the new scan performance gate went red on main (#485 landed before #465).

Register: C02 is now fixed (#581).

Living document: rewrote the C02 row in doc/01-summary.md and the "No timeouts on the main paths" passage in Part 7 (doc/07-infra-agent.md) so they describe main. Blob/diff retry (C15) is still open.

Lessons: Response::json turns a body-read timeout into a decode-shaped error, so a timeout test must also stall after the headers.

[github-actions[bot]]

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

• main: b1f9818 (Fix Gemfile rewrites duplicating gem declarations (#482, #548) #552, Fix npm crawler oracle flake from symlink-cycle trees #582, Share pnpm vendoring and revert across lockfile dialects #583, Stream ZIP member hashes during vendored verification #587 and Fix PyPI vendored to hosted takeover being refused (#328) #503 merged since the last run).

• Capacity: 2 of 3 open (Resolve vlt registry bases through one shared function (#562) #574 and Bound patch API connects and stalled reads (#570) #581 are both ready). There was nothing to resume.

• Ranking: Read and splice nuget.config through formats::nuget in hosted, vendored and restore #594 (E11) dropped out because open PR Unify hosted NuGet routing and XML splice anchors #597 (from another agent) fixes Hosted NuGet mapping reads commented-out package sources #561 and Hosted NuGet splices the Socket source (and mapping) into a commented-out &lt;packageSources&gt; / &lt;packageSourceMapping&gt; block, so every restore fails NU1100 while scan reports success and its in-run VEX attests not_affected #585. The next three are each blocked by an open PR that changes the same file:

  • Vendored→hosted takeover drops the vendored ledger entry when the revert drift-keeps the artifact #568, by Fix hosted scan from a workspace member pinning nothing or the wrong files (#590, #417) #598 (scan/hosted.rs);
  • Hosted NuGet rewrites packages.lock.json entries at other versions of the patched id #593, by Unify hosted NuGet routing and XML splice anchors #597 (redirect/mod.rs);
  • E37, by Fix hosted scan from a workspace member pinning nothing or the wrong files (#590, #417) #598 (vendor/cargo.rs).

  That left NuGet and Cargo crawlers hang on a FIFO at obj/project.assets.json or vendor/<crate>/Cargo.toml #592 (E06, score 3) as the top eligible candidate.

• Opened #602:

  • the NuGet project.assets.json read, both Cargo crate-manifest reads and the Pipenv .venv read now go through utils::fs::read_regular_*;
  • a new crawlers::architecture_tests guard bans bare reads in crawler production code (the 2 machine-repo Maven reads are allowlisted);
  • production +4 / −4, tests +223. Red→green shown for all three tests.

  State: ready, handed to the burn-down.

• Claimed: NuGet and Cargo crawlers hang on a FIFO at obj/project.assets.json or vendor/<crate>/Cargo.toml #592. Released: none. Merged: none.

• Register: E06 is now in PR #602. The living document already carries {{E06}} in Part 6.6.

• Lessons: rustfmt <file> formats that file's child modules too. clippy --all-targets is red on main from test-code lints.

[github-actions[bot]]

[agent] 2026-10-02T21:25Z: architecture refactor run

main: 045d7ec.

Ranking: 2 of 3 slots were in use (#574, #602). The top three candidates (#568, #593, E37) change files that open PRs #598, #597 and #602 change. C07 was verified on main: with no org slug, the JSON routes use /v0/orgs/default while blob and vendor downloads use the public proxy. Unifying them needs an owner decision on which route wins (covgap_api_client pins default), so it was set aside. The best eligible candidate was #571 (C37): B 1, D 1 (the duplicate blob and diff download loops), R M, score 2.

PR: #607, "Stream patch blob and diff downloads to disk (#571)". It is ready for review, with CI and Bugbot pending.

• fetch_blob / fetch_diff return a BinaryBody stream.
• stream_cache_entry_atomic stages each body chunk by chunk, hashes blobs from the staged file, and removes any cache directories it created when it fails.
• One download_entries loop replaces the two.
• The new streaming test fails on main and passes on the branch.

Claimed: #571 (Claim-ID 20261002T205951Z-acffe9).

Merged / living document: #581 was recorded by the previous run. This run removed it from In flight in the register. C37 is now in PR #607, and its {{C37}} token is already in doc/07-infra-agent.md.

Lessons: The skip rule holds even when another PR's hunks are far from the code you'd change (#598 edits scan/hosted.rs line ~731, while vendored_takeover is at ~1567). That candidate waits.

[github-actions[bot]]

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

main @ 045d7ec. There were no new maintainer comments in the discussion. The maintainer's steering on #569 (stream rather than cap trusted upstream data) is already reflected.

Reconciled:

• C01 is now fixed (#587). zip_bytes_match_after_hashes streams each member through the Git SHA-256 reader. The summary §1 row and §6 list are rewritten.
• C02 was already fixed (#581); the refactor run recorded it.
• C03 / #568 was re-checked and is still present. vendored_takeover moved to hosted.rs:1567, so I posted a fresh permalink.
• C37 is unchanged (in PR #607).

Backlog verified and decomposed:

• C04 → #613 (bug, pm:hatch). require_environment_context_support still spawns bare hatch from the project root. I proved it by execution, twice, with a temporary unit test: with PATH=.:$PATH, a planted root/hatch ran (marker file created), and its fake 1.13.0 passed the version gate. On the same PATH, resolve_tool("hatch") returns None. Fix global PM probes spawning bare names from the project (#421, #434, #438, #440) #442 didn't cover this spawn.

• C05 → #615 (decision, agent:needs-human). SOCKET_FORCE still binds apply --force (beforeHash bypass), vendor --force and --update --force. Renaming the variable is a contract change, so the issue offers three options and recommends option 1 (split, with a one-release deprecation fallback). It also covers the SOCKET_FORCE part of C35.

• C06 is rejected. The fields that ..GlobalArgs::default() resets in nested_apply_args_from_params are inert on main:

  • the nested apply runs on the caller's client (DownloadRun);
  • the hosted opt-outs, debug and telemetry reach core through apply_env_toggles and process env;
  • of the reset fields, apply reads only offline, and get/scan refuse --offline up front.

  The get ↔ scan cycle and the fake ApplyArgs stay under C12.

New finding: C38 → #614. Every CLI patch-API window paces through utils::concurrent (proxy cap 4, the SOCKET_API_CONCURRENCY override, the fd-limit rule). The API client's public-proxy per-package fallback is the exception: it keeps a private PROXY_BATCH_PATH_CONCURRENCY = 10. With a 400 from /patch/batch and SOCKET_API_CONCURRENCY=1, a temporary wiremock test measured 10 by-package GETs in flight while api_concurrency(true) returned 1 (run twice). registry_concurrency() also has no caller.

Searched without filing:

• Duplicate fn names across CLI and core api/utils/patch/update:
  • severity_order already delegates to api::ranking;
  • the three url_host copies are minor and one sits in the sibling's redirect/upstream/uv.rs;
  • read_manifest and from_env are unrelated same-name functions.
• Credential leakage of a userinfo-bearing --api-url into errors is a false positive: reqwest strips userinfo from the request URL before any error captures it, and the client's own GET {url} labels go only to debug.
• Other Command::new(<var>) spawns (npm_dir, vlt_preflight, the self-tests in fs.rs/update/download.rs) all spawn resolved paths or the test binary.
• §0 numbers were refreshed earlier today, so I didn't redo them.

Living document:

• Part 2 and Part 7 check lines are now at 045d7ec.
• Tokens added: {{C04}} (Part 7.3), {{C05}} and {{C06}} (Part 2.4/2.3).
• The C38 bullet is under Part 7's new findings.
• Rewrote the C01 row in the summary and the DownloadParams passages in the summary and Part 2.3.

Next backlog rows: C07 (URL builders on org fallback; needs a decision, see the refactor run's verification), C08 (repo hygiene), C09 (with_proxy_fallback), C10 (RunCtx tracking), C13 (typed error codes).

---

Generated by Claude Code

[github-actions[bot]]

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

• main @ 045d7ec.
• Capacity reached: Resolve vlt registry bases through one shared function (#562) #574 (ready), Read NuGet and Cargo crawler project files through the FIFO-safe reader (#592) #602 (ready), Stream patch blob and diff downloads to disk (#571) #607 (in-progress, heartbeat 21:19Z, live; another run owns it). No new work started.
• Nothing merged since the previous entry; no claims taken or released.
• Re-ranked: The public-proxy per-package fallback runs 10 requests in flight, ignoring SOCKET_API_CONCURRENCY and the proxy cap of 4 #614 (C38, duplicate proxy fallback pacing constant) enters the queue at score 4, skipped while Stream patch blob and diff downloads to disk (#571) #607 and Retry patch API connections reset mid-handshake #610 change api/client.rs. Vendored→hosted takeover drops the vendored ledger entry when the revert drift-keeps the artifact #568, Hosted NuGet rewrites packages.lock.json entries at other versions of the patched id #593 remain blocked by open PRs Fix hosted scan from a workspace member pinning nothing or the wrong files (#590, #417) #598 and Unify hosted NuGet routing and XML splice anchors #597. C18 dropped out of the top five.

[github-actions[bot]]

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

main @ 045d7ec. There were no new maintainer replies in the discussion. Nothing addressed to this routine was handed over.

Reconciled.

• E12 is now fixed (#583). The pnpm v9 and legacy drivers share vendor_pnpm_dialect and revert_pnpm_dialect, and Part 4.4 was rewritten to match.
• E01 is in PR #597. That PR also covers the hosted part of Read and splice nuget.config through formats::nuget in hosted, vendored and restore #594 (E11).
• E02/E03 are still in Resolve vlt registry bases through one shared function (#562) #574, and E06 is still in Read NuGet and Cargo crawler project files through the FIFO-safe reader (#592) #602.

Verified and filed:

• E09 (berry gates written twice) is still present on main. The cacheKey constant, the extractor and the gate drivers exist once per mode. Only 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). The copies have also drifted, which is the new finding below. Filed #629 (refactor, pm:yarn-berry): one pure formats/yarn/berry_gates.rs, with per-mode codes kept.
• E37 is still present. The three is_safe_{cargo,gem,nuget}_coordinate guards are byte-identical and duplicate simple_purl. normalize_version equals strip_leading_v. This also turned up two layering edges: formats::composer → crawlers, and utils::purl::maven_purl → crawlers::maven_crawler. Filed #630 (refactor). It should land after Read NuGet and Cargo crawler project files through the FIFO-safe reader (#592) #602.

New finding: E51 (proved by execution, a unit probe run twice, not committed). Take a yarn berry project whose root package.json mixes CRLF and LF.

• Vendored mode refuses it with vendor_yarn_berry_mixed_line_endings, which is documented in CLI_CONTRACT.md. The existing test mixed_line_endings_refuse_before_any_write pins this.
• Hosted rewrite_yarn_berry and preflight_yarn_berry_hosted accept it. They write the lock and re-render the manifest all-CRLF through JsonLayout's majority terminator, and they emit no warning.

Filed #628 (bug, pm:yarn-berry). The recommended fix is that hosted mode refuses this too, from the shared gate.

New finding: E52. In vendor/go_sum_edit.rs, the free upsert_module_lines, has_module_version and remove_exact_module_version_lines (about 90 lines) have no production caller anywhere in the workspace. GoSumEditor, which the hosted Go rewriter uses, re-implements them, and the free copies survive only as a test oracle. The pure codec also sits in vendor/, although redirect, restore, VEX and inventory all import it. Filed #631 (refactor, pm:go).

Searched without filing:

• The composer is_dev_version copies (upstream/composer.rs, vex/discover/composer.rs) differ: VEX normalizes first and strips #commit. Composer locks spell dev versions as dev-*/*-dev already, so I found no realistic divergence.
• The hand-rolled URL-host splitters (hosted/guidance.rs, upstream/uv.rs, python_lock.rs, hosted_url.rs) number five. They are small, have not drifted, and belong to core utilities if anywhere.
• Hosted berry berry_cache_key and vendored berry_field agree on every realistic __metadata spelling I tried by reading the code.
• Yarn also reads ancestor and home .yarnrc.yml files and YARN_COMPRESSION_LEVEL, and both modes ignore them. That is consistent between the modes and is E43 territory (unmodeled resolution config). It was not filed, because it needs a real-yarn run to prove.
• In-memory hosted refuses a symlinked .yarnrc.yml read, while disk mode follows it. This is deliberate memory/disk behavior (parity-tested), so it is not a defect.

Living document:

• Part 4: check line set, the §4.4 pnpm paragraph rewritten for Share pnpm vendoring and revert across lockfile dialects #583, the berry-gates paragraph refreshed (permalinks, Fix yarnrc compressionLevel comment refusal (#370) #508) with {{E09}}/{{E51}}, and an E51 bullet added under its new findings.
• Part 6: check line set, plus {{E37}} tokens and the layering edges.
• Part 3: an {{E01}} token and the E52 bullet.

Next backlog rows: E07 (package-lock walks), E08 (yarn grammars, now pairs with #629), E10 (XML scanners, Maven/Gradle half), E14 (Pipfile.lock two writers), E15 (Cargo.toml parsers).

---

Generated by Claude Code

[github-actions[bot]]

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

main @ 045d7ec, unchanged since the previous run. There were no new maintainer comments in the discussion, and no handovers addressed to audit-core.

Reconciled:

• C04 is now in PR #617 (it fixes Vendored Hatch runs a hatch executable planted in the scanned project #613).
• C03 (Vendored→hosted takeover drops the vendored ledger entry when the revert drift-keeps the artifact #568), C37 (in PR Stream patch blob and diff downloads to disk (#571) #607), C38 (The public-proxy per-package fallback runs 10 requests in flight, ignoring SOCKET_API_CONCURRENCY and the proxy cap of 4 #614) and C05 (Decide: give SOCKET_FORCE per-command names so forcing a self-update doesn't also force apply and vendor #615) are unchanged. main hasn't moved, so I didn't re-check open issues against it again.
• The C01–C03 register rows were missing their Source cell; I filled it in (§1 Remove tsc from npm prepare script #1–Update CLI documentation and package name #3).

Backlog verified and decomposed:

• C07 → #648 (decision, agent:needs-human). With a token set and the org unresolved, one client sends JSON calls to /v0/orgs/default/patches/… with the bearer, while blob, diff, vendor references and telemetry go anonymously to the public proxy. I proved this with a temporary unit test (run twice, not committed). The options are fail fast, downgrade the whole client to the proxy (recommended), or default everywhere. Every option resolves the route once, as one value.
• C08 → #649 (refactor). The stray actions/cache launch.json is still there; it came in with Keep Composer redirects and rollback consistent #358, not fix(scan): surface yarn PnP refusal instead of silent success-0 across all modes #201 as the review said. The "DESIGN §" references number 39 in 20 files. The README/installer part is already fixed: the README now says plainly that the installer selects the latest release.
• C09 → #647 (bug). I proved get's search-path gap by CLI execution, twice: against an auth server answering 401, get CVE-…, get GHSA-… and get pkg:… error with Unauthorized and never try the proxy, while get <uuid> falls back.

New finding: C39, filed together with C09 as #647. The command-level fallback misses more than get search. With the same stale token, apply --download-mode file on a missing afterHash blob hit only the auth route and reported sources_download_failed (exit 1), twice; the no-token control reached the proxy. rollback, repair and vendor eject have no fallback code either. CLI_CONTRACT.md line 552 promises eject "the same … public-proxy fallback as get". The fix moves the downgrade into ApiClient, which deletes the three CLI copies.

Searched without filing:

• --api-url/--proxy-url reaching telemetry: a false positive. apply_env_toggles mirrors both flags into SOCKET_API_URL/SOCKET_PROXY_URL, which telemetry's resolver reads.
• The update notifier's offline gate uses common.offline, and that flag is already mirrored into SOCKET_OFFLINE. Its env vocabulary belongs to C19.
• The three debug_log copies (client, telemetry, notifier): telemetry's copy skips the HeldBack deferral, which is cosmetic (C29 territory).
• Telemetry builds its own client for every event: already C22.

Living document:

• Check lines set on Parts 2, 7 and 8. Part 8 was re-checked for the first time, for the hygiene passages only.
• Tokens added: {{C07}} in Part 7.2; {{C09}}/{{C39}} in the Part 2.6 table and R2; {{C08}} in Part 8.
• The C39 bullet is under Part 2's new findings.
• The summary's §0 numbers are refreshed for 2026-10-03: 212 test executables, redirect/mod.rs at 19,571 lines, CLI_CONTRACT.md at 343 KB with a longest line of 10,530 characters, and 176 open issues (166 bug). The §1 Add search-then-download workflow for patch CLI #8 hygiene row was corrected.

Next backlog rows: C10 (RunCtx tracking), C13 (typed error codes), C14 (envelope decision; one decision per run), C15 (retry primitive), C16 (batch limits).

---

Generated by Claude Code

[github-actions[bot]]

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

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

Reconciled.

• E09 and E51 are now in PR #657, which shares the berry gates between modes (Share the yarn berry project gates between hosted and vendored modes #629, Hosted yarn berry rewrites a mixed-line-ending package.json that vendored mode refuses #628).
• E01 (Unify hosted NuGet routing and XML splice anchors #597), E02/E03 (Resolve vlt registry bases through one shared function (#562) #574) and E06 (Read NuGet and Cargo crawler project files through the FIFO-safe reader (#592) #602) are still in their PRs. Nothing in this area merged, so no open issue needed re-checking against a moved main.

Verified and filed:

• E07 is still present, but only half of it. Fix JSON writers dropping CRLF/BOM/indent (#324, #351) #357 moved every package-lock writer (vendored, hosted, restore) onto JsonLayout, so the "three serializers" part is fixed. The four entry walks remain: inventory/VEX walk_npm_lock, vendored scan_lock_matches + rewrite_legacy_tree, hosted package_ids + rewrite_npm_v2_deps, and restore npm_lock_hits + v2_hits. Each has its own copy of the name-field-else-key identity rule and the skip rules, plus two byte-identical JSON-pointer escapes. They've drifted only on the recursion bounds (64 vs none, and serde's parse limit covers it) and on the legacy-alias warning (vendored only). Filed #663 (refactor, pm:npm), one addressed walk. It should land after Fix npm/Bun VEX attesting a patch a same-lock copy skips (#588) #589, Unify hosted NuGet routing and XML splice anchors #597, Fix yarn berry project gates drifting between modes (#628, #629) #657 and Fix npm v1 lock losing a hosted patch on takeover (#659) #660.
• E14 is still present. Hosted redirect/pipenv.rs splices spans with its own JSON property tokenizer, while vendored pypi_pipenv.rs parses the lock and re-serializes it canonically (sorted keys, 4-space indent, CRLF re-applied). Pipenv always writes canonical JSON, so I proved no user-visible drift. I didn't file it; the row stays to verify with a note.

New finding: E53 (proved by execution, a unit probe run twice, not committed). Vendored pnpm still writes the root package.json with detect_indent + common::serialize_json, on both vendor (pnpm_lock.rs:326) and revert (:946). It also parses it with a plain serde_json::from_slice. #357 missed this writer.

• A CRLF package.json comes out all-LF after vendoring, and revert_pnpm leaves it LF, so the revert isn't byte-exact.
• A BOM package.json is refused as vendor_pkg_json_unsupported: package.json is not a JSON object.

npm and yarn berry keep the layout through JsonLayout. Filed #662 (bug, pm:pnpm).

Searched without filing:

• common::serialize_json's other callers: composer re-applies line endings, and Pipenv re-applies CRLF (E14).
• redirect::serialize_json (fixed 2-space, LF) is now used only for NuGet packages.lock.json, in hosted and restore. NuGet writes CRLF on Windows, so this may convert a CRLF lock to LF. It's left for Hosted NuGet rewrites packages.lock.json entries at other versions of the patched id #593's version-aware walker, and I didn't prove it against real NuGet.
• The hosted legacy-tree alias ("x": {"version":"npm:real@v"}) is not hijacked by a name collision, because the versions differ.

Living document: Part 4's check line is refreshed. The package-lock row of the walk table has new line numbers and #357 notes, plus {{E07}}. The JSON-serializer bullet is rewritten for current main (#357, {{E53}}), the stale "npm_lock normalizes to LF" claim in the CRLF list is corrected, the §4.7 E row is updated, and an E53 bullet is added under new findings.

Next backlog rows: E08 (yarn grammars; after #657 lands), E10 (XML scanners, Maven/Gradle half; #646 is adding Gradle), E15 (Cargo.toml parsers), E13 (poetry/pdm; the refactor routine notes the walkers really differ), E16 (CRLF policies).

---

Generated by Claude Code

[github-actions[bot]]

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

main @ 045d7ec, unchanged since the previous run. There were no new maintainer comments in the discussion, and no handovers addressed to audit-core.

Reconciled: all register rows hold their statuses: C03 #568, C04 in PR #617, C05 #615, C07 #648, C08 #649, C09/C39 #647, C37 in PR #607 and C38 #614. main hasn't moved, so I didn't re-check open issues again.

Backlog verified and decomposed:

• C16 → #675 (refactor). The batch limits exist three times:

  • CLI scan: 500/100 with a 256 KiB body split, and any --batch-size accepted;
  • the in-memory hosted engine: default 100 on either endpoint, max 500, no body split, and a second MAX_REFERENCE_BATCH;
  • ApiClient::search_patches_batch documents "Maximum 500" but never chunks, whereas fetch_registry_references chunks itself.

  Target: api::batch with one chunker. Clamping --batch-size is a contract change and stays out.

• C15 → tracking #676, child #677 (linked as a sub-issue). A temporary unit test, run twice and not committed, showed the vendor path's retry_after_secs returns None for an HTTP-date Retry-After where api::retry::parse_retry_after returns 62 s. It also showed 500, 502 and 504 are retryable on vendor calls but final on JSON calls. The vendor path has its own RandomState jitter, and fetch_binary still has no retry. Child 1 folds the vendor Retry-After parser and jitter onto api::retry. Children 2–4 (one loop; blob/diff retry, blocked by Stream patch blob and diff downloads to disk (#571) #607; one downloader) are listed but not filed. PR Retry patch API connections reset mid-handshake #610 (ci-janitor) adds connect-reset retry to the JSON path and is noted as a dependency.

New finding: C40 → #678. I checked every "SOCKET_*" literal in core and CLI src against CLI_CONTRACT.md, twice: 84 names, 16 missing. Two are operator-facing and documented nowhere: SOCKET_API_CONCURRENCY (the patch-API throttle) and SOCKET_WALK_THREADS. The other 14 are test hooks or build-time env!. The reverse check found no phantoms, only the documented v5.0 removals. The guard tests cover only clap-bound vars, so core-read knobs drift. I commented on #614, which is about the knob nobody can find.

Searched without filing:

• Duplicate fn names across CLI and core: stdout_vt/stderr_vt and swap_binary_inner are cfg(unix)/cfg(windows) pairs, and is_real_dir/child_dirs are trait impls. No defects.
• The five reqwest client builders (update/{download,release}, RegistryClient, maven_repo, telemetry) differ in timeout, User-Agent (telemetry sets none) and redirect policy. That is already covered by Part 7.2 "Other HTTP stacks", C15 and C22, so I filed nothing new.
• vendor_prefetch re-chunking references at MAX_REFERENCE_BATCH: it calls the vendor-service endpoint, which isn't ApiClient's chunking path, so it's legitimate. The constant moves under Chunk patch batch searches through one core helper with one set of batch limits #675.

Living document:

• Part 7.2: added the {{C15}} token, noted the HTTP-date gap in the retry table, and rewrote the batching passage as "defined three times" with {{C16}}. The check line now covers retry and batching.
• Part 8: added the {{C40}} bullet under new findings, and the check line now covers the env tables.
• §0 numbers were already refreshed today.

Next backlog rows: C10 (RunCtx tracking), C13 (typed error codes), C14 (envelope decision), C17 (digest helpers), C18 (UUID grammars).

---

Generated by Claude Code

[github-actions[bot]]

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

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

Reconciled. No status changed in this area: E01 (#597), E02/E03 (#574), E06 (#602) and E09/E51 (#657) are still in their PRs, and nothing in scope merged. Because main did not move, no open issue needed re-checking.

Verified and filed:

• E15 is still present, and wider than the review said. Cargo.toml [package] is read in five places: line scanners in cargo_crawler.rs and vex/product.rs (scan_toml_section), plus ad hoc toml_edit lookups in cargo_tag::version_literal, path_crate_version and declared_cargo_minor. The review's "cargo_tag finds the version textually" is out of date: it now locates the span through toml_edit. A probe, run twice and not committed, proved drift:

  • a BOM manifest is invisible to the crawler, but VEX and cargo_tag read it;
  • [project] and dotted keys are read only by cargo_tag;
  • invalid [package] junk is accepted only by the crawler.

  Filed #693 (refactor, pm:cargo): one formats/cargo [package] reader that models workspace inheritance. I commented on Vendored cargo warns cargo_multi_version_old_cargo ("declares no rust-version") when the root package inherits rust-version from [workspace.package] #651, which is a symptom. The hosted plan_cargo_toml regex scanner is the rest of E15 and is not filed yet.

• E13 is still present. next_header_end, *_lock_edits, the rewrite struct, the parse holder and the finish step are copied; pair_* differs by the shape check. The review's "latent bug" is not reachable, because a Poetry rewrite pairs fragments of one document, so the fragment count cannot change. Filed #694 (refactor): a mechanical share with byte-identical output.

New finding: E54 (proved by execution, run twice). The finish steps of #694 differ in their line-ending rule. Poetry turns the whole rendering CRLF if the input has any CRLF; PDM uses preserve_line_endings, which converts CRLF-only inputs. Take a fixture lock converted to CRLF with one LF line in the patched unit: Poetry's output is 24 CRLF / 0 LF lines, while PDM's is 12 CRLF / 8 LF lines, a block of LF lines in a CRLF file. Rollback stays byte-exact in both. Filed #695 (bug, low severity): one per-fragment rule.

Searched without filing:

• Composer version identity: hosted, restore and vendored match with composer_versions_equivalent, while VEX, formats::composer and restore's pick_version use normalize_version. Packagist and lock versions are both pretty strings, and purls come from the crawler's normalize_version, so I found no realistic divergence.
• NuGet version spelling: vendored and restore use normalize_nuget_version, the crawler lowercases, and VEX keeps resolved raw. NuGet writes resolved normalized; this is left to Hosted NuGet rewrites packages.lock.json entries at other versions of the patched id #593's walker.
• Cargo.lock and tagged versions: VEX, inventory, formats::cargo and vendored all route through cargo_tag, so this is consistent. One layering edge, formats::cargo → vendor::cargo_tag, is E20's.
• Hosted plan_cargo_toml's line scanner: [[bin]] keeps the previous dependency section open, but only crate names equal to a bin/example key (name, path, test, …) could be misread, and the toml_edit post-check fails closed. Not filed.

Living document: Part 5's check line is refreshed (5.4 Python and Cargo). The poetry/pdm bullet is rewritten with {{E13}}/{{E54}}, the Cargo bullets are rewritten for current main with {{E15}}, the CRLF list now names four policies, and an E54 bullet is added under new findings.

Next backlog rows: E15b (hosted plan_cargo_toml scanner), E10 (XML scanners, Maven/Gradle half; after #646/#597), E16 (CRLF policies), E17 (bun lock presence), E08 (yarn grammars; after #657).

---

Generated by Claude Code

[github-actions[bot]]

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

main @ 045d7ec, unchanged since the previous run. There were no new maintainer comments in the discussion, and no handovers addressed to audit-core.

Reconciled: all register rows hold their statuses. That covers C03 #568, C04 in PR #617, C05 #615, C07 #648, C08 #649, C09/C39 #647, C15 #676/#677, C16 #675, C37 in PR #607, C38 #614 and C40 #678. main hasn't moved, so I didn't re-check open issues against it again.

Backlog verified and decomposed:

• C14 → #704 (decision, agent:needs-human). This is worse than the review said. rollback emits a bare-string error, but scan and get each mix shapes:

  • scan uses a string for discovery and offline failures and a {code, message} object for its embedded-VEX failure;
  • get uses a string, a string plus a sibling errorCode (lock failure) and an object (vendored failure).

  Options: always {code, message} (recommended), string + errorCode, or finish the move to Envelope.

• C18 → #705 (refactor). There are now five UUID grammars; the fifth is uuid::Uuid::parse_str in utils/python_script.rs (uv grant segments), which accepts simple, braced and urn:uuid: forms. Drift: uppercase passes the API client but fails vendored paths, and ABC_1 is a valid archive stem that fetch_diff rejects. Target: utils::uuid::{is_patch_uuid, looks_like_uuid}, deleting three copies.

• C17 → #706 (refactor, mechanical). In production code:

  • 3 private sha256_hex compute copies, plus file_sha256_hex and ServiceFetch::sha256_hex;
  • 2 sha1_hex copies;
  • 3 sha512-SRI copies, one of them public in redirect::vlt_preflight, which vendor would have to import against the layering;
  • about 23 inline hex::encode(Sha256::digest) and 3 inline Sha1;
  • 3 64-hex validators.

  No output drift yet; the hazard is the sha256_hex validate/compute name clash. The review's "~30" inline count is corrected to ~23 production sites.

New finding: C41 → #707 (bug). The hash case policy is decided per site:

• blob_fetcher::blob_hash_matches deliberately compares case-insensitively, with a regression test, and the blob-name validators accept uppercase.
• Agent-mode verify_file_patch, the patched-bytes check and verify_file_rollback compare with exact == against the lowercase computed hash.

A temporary core integration test (run twice, not committed) uppercased a manifest's hashes. is_valid_blob_hash stayed true, and both apply and rollback verify returned HashMismatch; the lowercase control applied. The vendored verify sites are split the same way: verify.rs/pypi.rs ignore case, while redownload.rs, bun_workspace.rs and bun_binary.rs don't.

Searched without filing:

• Severity ladders (api::ranking, policy, socket_yml, rollout, CLI get, scan/discovery, scan/render, ui): already consolidated. Every parser delegates to ranking::severity_order. What's left is two inverse label maps (policy::severity_name, rollout::severity_label, which differ only in None vs "unknown") and ui's color map. Not worth an issue.
• Dead-code scan of utils, api, agent patch, telemetry, update and policy: policy::find_repo_root and utils::purl::purl_name_version have test-only callers, and purl_name_version's doc comment names a production caller that no longer uses it. Too small to file; noted for C20 (purls).
• Root finders: policy::find_repo_root_with_warnings and args::project_root serve different roles (git root vs .socket parent). Not a duplicate.

Living document:

• Part 2's envelope bullet is corrected: the error types are mixed within commands. Added {{C14}}.
• Part 7.3 hashing: the count is corrected and the triple validator added, with {{C17}}. UUID: five grammars, {{C18}}. The {{C41}} bullet is under new findings. The check line now covers hashing and UUIDs.
• Summary recommendation 8 is corrected the same way as Part 2, with {{C14}}. The §0 numbers were already refreshed today.

Next backlog rows: C10 (RunCtx tracking), C13 (typed error codes; after #704), C19 (env truthiness and home dirs), C20 (purl builders), C21 (atomic writers).

---

Generated by Claude Code