Skip to content

Commit 950f9fe

Browse files
mikolalysenkoclaude
andcommitted
Catalog where readers and modes disagree
docs/design/lock-model-divergences.md lists every question on which discovery, the inventory, hosted and vendored mode answer differently today, across all ecosystems, with the resolution under the principles and flags for false attestations and target-specific differences. Owner decisions recorded: the modes are ground truth over the readers; vendored mode's Maven profile and reactor support and its scala-cli wiring are back-ported to hosted as the planners merge (the JVM PR splits into readers, Maven planner, and Gradle/sbt/scala-cli). One call is pending: whether hosted keeps rewriting a shrinkwrap.yaml that pnpm never reads. Corrects the install-tree section: npm-shrinkwrap.json does not shadow package-lock.json; every consumer but the inventory already reads both. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 0006f14 commit 950f9fe

2 files changed

Lines changed: 157 additions & 8 deletions

File tree

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# Where the readers and modes disagree
2+
3+
Companion to [lock-model-unification.md](lock-model-unification.md). Each
4+
row is a question that discovery (VEX), the lock inventory, hosted mode and
5+
vendored mode answer differently today, with its resolution under that
6+
document's [principles](lock-model-unification.md#principles-owner-decisions-2026-11-04).
7+
Paths are relative to `crates/socket-patch-core/src/`. Line numbers are from
8+
the survey of 2026-11-04 and will drift.
9+
10+
Flags:
11+
12+
* **false attestation**: a reader attests a copy the install may not use
13+
today. Fixing these is a correctness priority.
14+
* **needs owner**: following hosted would be unsafe or would delete a
15+
working feature. Listed under "Calls that go against hosted" for the
16+
owner to decide.
17+
* **target-specific**: the difference comes from where the entry points
18+
(a Socket URL or a committed path) and stays.
19+
20+
## Calls that go against hosted (owner decided 2026-11-04)
21+
22+
Owner: the false Maven attestations get fixed, the modes are ground truth
23+
over the readers, and the vendored mode's profile, reactor and scala-cli
24+
support is back-ported so hosted gains it as the planners merge. P3 and P4
25+
follow from the install-tree decision.
26+
27+
| # | Question | Hosted today | Decision |
28+
|---|---|---|---|
29+
| J1 | Does a base-version Maven dependency declared in a `<profiles>` block block attestation? | Warns, still pins the top level and counts the package as redirected (`patch/redirect/mod.rs` ~8744) | Vendored's rule: any profile declaration at the base version makes the ref unattested (fixed now in discovery), and the merged planner rewrites profile declarations in both modes. |
30+
| J3 | Which Maven poms count? | Refuses a reactor root (~8572) | The reactor reader becomes the shared core, so hosted gains reactor support. |
31+
| J12 | scala-cli | Guidance only (`patch/redirect/scala_guidance.rs`) | Back-port: hosted wires scala-cli through the merged planner (a same-GAV Socket repository instead of a suffixed version). |
32+
| P3 | Is a shadowed `pdm.lock` rewritten? | Only when it governs (`pdm_drives`, ~564) | Rewrite it like every other tree, per the install-tree decision. |
33+
| P4 | Are `-r` includes of `requirements.txt` rewritten? | Root file only (`patch/redirect/requirements.rs` ~208) | Follow includes, per the install-tree decision. |
34+
| N11 | Is a `shrinkwrap.yaml` beside `pnpm-lock.yaml` rewritten? | Yes; its all-or-nothing gate covers both files | **Pending.** Proposed: treat it as shadowed (swept for stale identities, never written). pnpm never reads it, and an unparseable debris key in it can refuse the dependency in every lock. |
35+
36+
## JVM
37+
38+
| # | Question | Today | Resolution | Flag |
39+
|---|---|---|---|---|
40+
| J2 | Does an executable classifier variant (`tests`, native) of the patched package block attestation? | Hosted skips the dependency. Discovery marks it unattested. Vendored only warns, then `entry_wired_checked` attests (`vendor/jvm/maven_reactor.rs` ~1884, `vendor/jvm/apply.rs` ~1042). | Hosted | false attestation |
41+
| J4 | How are `${prop}` versions resolved, and does `.mvn/maven.config` win? | Discovery: one level of pom properties, no `-D` user properties. Hosted refuses `${…}`. Vendored: user properties, parent chain, profiles, depth 16. | One interpolator (vendored's). Hosted's refusal stays a writer policy. | false attestation |
42+
| J5 | Do Gradle lockfiles gate liveness? | Hosted and discovery check every lock. Vendored reads none (`vendor/jvm/gradle.rs` ~1227). | Hosted | false attestation |
43+
| J6 | Is sbt resolution evidence required before attesting? | Hosted: no integrity without verified evidence. Vendored: `wired_checked` only checks the owned-file row; discovery's `vendored_check` diagnostics are never consumed. | Hosted. One evidence route (`ResolutionDoc` + `gate::check_new`). | false attestation |
44+
| J7 | Another version of a mapped NuGet id is locked | Both writers refuse. Discovery emits a ref per locked version, keyed by raw text, not `normalize_nuget_version`. | Hosted: a diagnostic, no ref | false attestation |
45+
| J8 | What counts as "wired" for vendored Maven liveness and GC? | Vendored: substring match on masked text, so a suffix in `<build>`, a profile or `<properties>` counts. Discovery and hosted use the scoped `PomScope`. | Scoped reader | |
46+
| J9 | `checksums.sha256` and the `TRUSTED_CHECKSUMS_ON` switch | Four readers with different splitting and switch tests. Hosted's merge silently drops lines it can't split on two spaces. | One reader with the hosted grammar. The merge keeps lines it can't parse. | |
47+
| J10 | Gradle Socket index rows | Two parsers. Hosted validates the uuid, URL and hashes; vendored accepts any token and uses a raw `split('\t')`. Vendored checks only root settings; hosted checks every build. | One row grammar, hosted's validation | |
48+
| J11 | `verification-metadata.xml` | Two editors, no reader | One editor; a reader for the inventory | |
49+
| J13 | NuGet config scope | Writers read inherited parent configs; discovery doesn't. Discovery refuses a disabled Socket source; the writers don't check `<disabledPackageSources>`. | Shared inheritance read. The writers adopt the disabled-source refusal. | |
50+
| J14 | NuGet lock enumeration | In-memory views fall back to the root lock. The unwind bypasses the snapshot view (`governed_locks_on_disk`). | One enumeration over `ProjectView` | |
51+
| J15 | JVM liveness on a read error | `entry_wired` is `unwrap_or(true)` for `scan`/`vendor`; `vex` uses the checked variant | Fail closed everywhere | false attestation |
52+
53+
## Python
54+
55+
| # | Question | Today | Resolution | Flag |
56+
|---|---|---|---|---|
57+
| P1 | Which files count? | Hosted rewrites every file except a non-governing `pdm.lock`. Vendored picks one winner and warns that the rest stay unpatched. The inventory uses a chain. Discovery reads every lock with the cross-lock contest. `formats/governing_locks.rs` still gates four callers. | One tree per tool lock (owner decision). Vendored wires every tree. `governing_locks` goes. | |
58+
| P5 | Does the inventory list Socket entries? | It keeps hosted entries (with the patched artifact's URL and hash) but drops vendored uv path sources | Keep both, read as the package they replace. Check that vendor's pristine fetch and `repair` never take patched bytes from a hosted entry. | |
59+
| P6 | What counts as Socket wiring? | Discovery and the unwind use the host allowlist. The inventory accepts any host. Ledger liveness uses `resolved.contains(uuid)`. `poetry_lock::lock_wiring` uses `contains("/patch/pypi/")`. | The `origin` allowlist everywhere | false attestation (liveness substring) |
60+
| P7 | uv workspace roots | Hosted refuses members only. Vendored refuses roots too. | Vendored wires roots, after a test that a member's own `[tool.uv.sources]` can't override the root | |
61+
| P8 | `uv.lock` without `pyproject.toml` | Hosted edits the lock; discovery attests it. Vendored refuses. | Vendored proceeds | |
62+
| P9 | uv 0.2 `[[distribution]]` locks | Hosted rewrites. Vendored refuses (no portable path). The unwind refuses to restore them. | Vendored's refusal is target-specific and stays. The unwind must restore what hosted writes. | target-specific |
63+
| P13 | PDM `lock_version` | Writers use an allowlist; discovery a denylist; the inventory checks nothing | The allowlist everywhere | |
64+
| P14 | `pipfile-spec` | Writers require 6; discovery and the inventory accept any | 6 everywhere | |
65+
66+
## Cargo, Go, Ruby, Composer
67+
68+
| # | Question | Today | Resolution | Flag |
69+
|---|---|---|---|---|
70+
| G1 | Which `go.work` and members count? | Discovery: a root `go.work` and in-root members only, ignoring an ancestor `go.work`, `GOWORK` and `-modfile`. Hosted and vendored resolve the workspace go would use (`vendor/go_workspace.rs`). | `go_workspace::load` everywhere | false attestation |
71+
| G16 | Go inventory | Root `go.sum` only, lenient parse, lists `patch.socket.dev/gopatch/<uuid>` lines as packages | Discovery's model and workspace | |
72+
| C2 | Which manifests decide whether a Cargo lock entry is used? | Hosted pins root and member manifests; vendored reads members. Discovery reads only the root `Cargo.toml`. | Members everywhere | false attestation |
73+
| C11 | `cargo vendor` / local-registry source replacement | Hosted refuses; vendored and discovery ignore it | Stays | target-specific |
74+
| R10 | `gems.rb` / `gems.locked` | Hosted wires the pair bundler loads. Vendored refuses any `gems.rb`. | Vendored supports it | |
75+
| R15 | Malformed Gemfile.lock | Discovery reports it unparseable; the inventory lists what parsed | Discovery's rule everywhere | |
76+
| X12 | `composer.lock` with a BOM | Discovery strips it. The inventory drops the file. Vendored refuses to plan, errors on revert, and reports nothing stranded. | Strip one BOM everywhere. Check that GC never trusts the empty "stranded" answer. | |
77+
78+
## npm family
79+
80+
| # | Question | Today | Resolution | Flag |
81+
|---|---|---|---|---|
82+
| N1 | pnpm `gitBranchLockfile` with a branch lock present: is the root lock the install tree? | Hosted withholds the root locks and refuses (`hosted/engine.rs` ~930). Vendored refuses. Discovery and the inventory never check the setting. | Hosted | false attestation |
83+
| N2 | npm user patches (#711) and `bun patch` (#367) | Hosted skips that one dependency and records it as refused. Vendored refuses the whole npm v4 lock, or the one bun dependency. Discovery never reads `patchedDependencies` / `"patched"` and attests a pre-#711 hosted pin. | Hosted's per-dependency skip, in discovery too | false attestation |
84+
| N3 | A workspace member's stray npm/bun/vlt lock | Discovery treats it as absent. Hosted and vendored refuse. The inventory reads it as the project's lock. | The inventory ignores it | |
85+
| N4 | pnpm 11's env-lockfile document | See [Decisions](lock-model-unification.md#decisions-under-the-hosted-rule). `main_document` takes the text after the last `---`, so a crafted multi-document lock chooses its own "project". | Its own tree; documents identified by content, not position | |
86+
| N5 | What counts as Socket wiring | Discovery and the unwind use the allowlist. The inventory records hosted URLs on any host. `parse_vendor_path` accepts `.socket/vendor/` anywhere, so a `../.socket/vendor/…` entry from a sibling checkout is "ours" to the vendored writer and reverter. The hosted pnpm "vendored?" check is a substring heuristic. | The `origin` classifier everywhere | revert could rewrite another project's wiring |
87+
| N6 | `npm-shrinkwrap.json` and `package-lock.json` | Hosted, vendored and discovery read both, with a contest. The inventory reads the shrinkwrap only. | Both, everywhere | |
88+
| N7 | npm lockfileVersion | Hosted rewrites v1 and v4. Vendored accepts v2/v3 only. The inventory ignores v1. Discovery reads v1 and v2+. | Hosted, once vendored `file:` wiring under npm 6 and npm 12.1 v4 has fixtures | |
89+
| N8 | npm `file:` directory link identity (#1481) | Hosted and discovery give a versionless link its source directory's `name@version`. Vendored matches the entry's own version, wiring the registry copies with no warning. | Hosted | silent vendored success |
90+
| N9 | yarn classic blocks reached only through an alias | Hosted skips them. Vendored rewrites them. Discovery counts an alias block as an install of the real package. | Back-port: hosted rewrites alias blocks (vendored supports what hosted lacks) | |
91+
| N10 | Locks of several npm-family package managers in one project | Hosted rewrites every family; discovery reads every family with the contest. The inventory and vendored pick one family (vlt > bun > pnpm > yarn > npm). | Union (separate trees) | |
92+
| N11 | `shrinkwrap.yaml` beside `pnpm-lock.yaml` | Hosted reads and splices it, and its all-or-nothing gate covers both. Discovery sweeps it as ignored. The inventory reads it only as a fallback. Vendored never reads it. | Pending owner decision (see above) | needs owner |
93+
| N12 | Rush common and subspace locks | Hosted and discovery always read them. The inventory reads them only when there is no root lock (#2003 aligns the listing itself). Vendored refuses Rush. | Always read. Vendored's refusal stays. | target-specific (vendored) |
94+
| N13 | Plug'n'Play | Vendored refuses. The hosted berry preflight has no PnP gate. The inventory returns an error, so `scan` sees nothing in a project hosted pinned. | The inventory reads PnP locks. Vendored keeps its refusal. | target-specific (vendored) |
95+
| N14 | pnpm `lockfile=false` | Hosted refuses. Discovery withholds hosted refs, keeps vendored ones. Vendored proceeds. The inventory ignores the setting. | The modes stay as they are; the inventory follows discovery | target-specific |
96+
| N15 | CRLF `pnpm-lock.yaml` / `pnpm-workspace.yaml` | Vendored refuses; the rest handle it | Handle it everywhere | |
97+
| N16 | Lock versions | pnpm: vendored accepts only 5.4/6.0/9.0; hosted any but early shrinkwrap. vlt: vendored refuses a lock with no version; hosted rewrites and warns. | Hosted | |
98+
| N17 | Bun workspaces, yarn classic offline mirror | Refused differently by the two modes | Stays | target-specific |
99+
| N18 | An unparseable npm lock | Hosted warns and skips. Vendored refuses the primary lock. Discovery diagnoses. The inventory returns nothing silently. | Discovery's diagnostic, surfaced by every consumer | |
100+
| N19 | yarn.lock with a stray top-level line | Discovery rejects the file; hosted and the inventory scan its blocks | Discovery's rule | |
101+
| N20 | Yarn's last-block-wins (`live`) | Discovery respects it; the inventory and both hosted yarn rewriters don't | Respect it everywhere | |
102+
| N21 | Accepted npm-family integrity | The inventory records any string as SRI; discovery requires an SRI pin (`sha1-` included) | Discovery's check | |
103+
104+
## Fixes for false attestations on main
105+
106+
These are fixed directly against `main`, ahead of the stack, one PR each.
107+
The stack rebases over them.
108+
109+
| # | Fix |
110+
|---|---|
111+
| J1, J4 | Maven discovery: a profile declaration or a `.mvn/maven.config` user property that resolves the base version leaves the ref unattested |
112+
| J2, J8, J15 | Vendored Maven liveness: executable classifiers block, "wired" is read from scoped declarations, read errors fail closed |
113+
| J5 | Vendored Gradle liveness reads the lock files |
114+
| J6 | Vendored sbt attestation requires resolution evidence |
115+
| J7 | NuGet discovery: no ref for a version the writers refuse |
116+
| N1, N2, G1, C2, P6 | Next batch: pnpm `gitBranchLockfile`, npm/bun user patches, Go workspaces, Cargo members, the liveness substring match |
117+
118+
## Planner merges (hosted and vendored)
119+
120+
Estimated implementation lines removable by giving each format one planner
121+
whose only parameter is the target:
122+
123+
| Format | Today | Estimate |
124+
|---|---|---|
125+
| uv.lock | Vendored's text surgery in `vendor/pypi_uv.rs` duplicates hosted's `PythonLockSession` | 1,000–1,400 |
126+
| NuGet | `add_nuget_source` / `rewrite_nuget` against `vendor/nuget_feed.rs`'s config edit, which says it mirrors it | ~400 |
127+
| Gradle | Build discovery, apply-line helpers, index parse and merge, owned script, verification edits | 500–700 |
128+
| Maven | Hosted is a root-only subset of the reactor planner. Four pom parsers collapse to one (`maven_reactor::Doc` survives). | largest; split readers first |
129+
| sbt | Build-source refusals and per-pin decisions; one evidence route | 150–250 |
130+
| Python router | `detect_pypi_flavor` and hosted's fixed chain become one query over trees | ~300 |
131+
| requirements, Pipenv, Poetry, PDM | Shared lexers or rewriters already; preflight and matchers duplicated | a few hundred |
132+
| Cargo | Dependency-table walk, member enumeration, CRLF handling | a few hundred |
133+
| Go | Version-selected and in-graph checks | ~100 |
134+
| Gem | Pair selection and spec-block moves | a few hundred |
135+
| Composer | Regex splice against JSON re-serialization; one locator and one splice | ~300 |
136+
| Unwind | The hosted `upstream/*` modules mirror the vendored unplans and become one unplan per format | follows the planner merges |

‎docs/design/lock-model-unification.md‎

Lines changed: 21 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -57,10 +57,15 @@ the model, and the end state has fewer implementation lines than today.
5757
a rewired entry points (a Socket URL or a committed `.socket/vendor/`
5858
path). Everything else, from reading the lock to choosing entries and
5959
refusing unsafe states, is one implementation.
60-
3. **When in doubt, hosted semantics are correct.** Where the modes or
61-
readers disagree and the right answer isn't clear, the hosted mode's
62-
current behavior wins. Every such call is listed under
63-
[Decisions](#decisions-under-the-hosted-rule), so it can be overruled.
60+
3. **When in doubt, the modes are ground truth.** Where a reader (discovery,
61+
the inventory) disagrees with what hosted or vendored mode writes, the
62+
mode wins. Between the two modes, hosted's behavior wins, except where
63+
vendored supports something hosted lacks: then the support is
64+
back-ported to hosted as the planners merge (Maven profiles and reactors,
65+
scala-cli). Every call is listed under
66+
[Decisions](#decisions-under-the-hosted-rule) and in
67+
[lock-model-divergences.md](lock-model-divergences.md), so it can be
68+
overruled.
6469
4. **Behavior changes are allowed, and visible.** A PR that aligns behavior
6570
lists each change in its description, adds a test that pins the new
6671
behavior, and shows its golden diffs.
@@ -170,9 +175,15 @@ pub struct InstallTree {
170175

171176
Rule: **precedence within a tree, union across trees.**
172177

173-
* npm: `npm-shrinkwrap.json` governs and `package-lock.json` is shadowed.
174-
pnpm: `pnpm-lock.yaml` governs `shrinkwrap.yaml`. Bun: `bun.lock` governs
175-
`bun.lockb`, which `bun_text_lock_drives` already decides.
178+
* npm: `npm-shrinkwrap.json` and `package-lock.json` are both read, as
179+
hosted, vendored and discovery already do, with discovery's contest
180+
between the two. The inventory, which reads only the shrinkwrap today,
181+
follows. pnpm: `pnpm-lock.yaml` governs `shrinkwrap.yaml`. Bun: `bun.lock`
182+
governs `bun.lockb`, which `bun_text_lock_drives` already decides.
183+
* npm-family locks of different package managers in one project (for
184+
example `pnpm-lock.yaml` beside `yarn.lock`) are separate trees, as hosted
185+
and discovery treat them. The inventory and vendored mode stop picking one
186+
family.
176187
* **Python (owner decision):** each tool's lock is its own tree, because
177188
which lock is installed depends on which tool runs. uv.lock, poetry.lock,
178189
pdm.lock, Pipfile.lock, each pylock, each PEP 723 script lock, and
@@ -276,7 +287,9 @@ A format whose planner merge is large splits into two PRs, readers first.
276287
| 8 | `lock-model/8-cargo-go` | One `Cargo.toml` dependency-table walk. Go `replace` and `go.sum` records. |
277288
| 9 | `lock-model/9-gem-composer` | Gemfile.lock and composer.lock records. The inventory stops dropping BOM-prefixed `composer.lock` files. |
278289
| 10 | `lock-model/10-nuget` | NuGet records with the config join, `NugetContentHash`, and inventory entries |
279-
| 11 | `lock-model/11-jvm` | One `checksums.sha256` reader, one Gradle index parser, a `verification-metadata.xml` reader, then Gradle-lock and root-pom inventory entries and sbt's owned-file entries |
290+
| 11a | `lock-model/11a-jvm-readers` | One pom model (`maven_reactor::Doc`), one interpolator, one `checksums.sha256` reader, one Gradle index grammar, a `verification-metadata.xml` reader, then Gradle-lock and pom inventory entries and sbt's owned-file entries |
291+
| 11b | `lock-model/11b-maven-planner` | One Maven planner for both modes. Hosted gains reactor and profile support. |
292+
| 11c | `lock-model/11c-gradle-sbt-scala` | One Gradle and one sbt planner, one evidence route. Hosted gains scala-cli wiring. |
280293
| 12 | `lock-model/12-install-trees` | Install-tree selection across formats, Python trees, Deno governance, the single classifier for the inventory, liveness on `Origin`. Deletes the npm flavor router's lock choice, the Python precedence rules, `resolved_elsewhere` and the `UnwiredCopy` plumbing. |
281294
| 13 | `lock-model/13-cleanup` | Removes the raw-text liveness fallbacks if the model makes them redundant, plus whatever is left of `vendor/lock_inventory/`. Final budget. |
282295

0 commit comments

Comments
 (0)