v5: socket.yml patch rollout config and filtering

[Mikola Lysenko (mikolalysenko)]

Work item A of the v5 staged-rollout design (#290, docs/design/staged-rollout.md §9.1). scan reads the repo root's socket.yml and uses it to narrow what it patches. This covers hosted, vendored and agent mode (--dry-run included) and the in-memory engine behind the autopatch bot. The per-run cap (--max-new-patches, work item B) builds on the shared types this PR adds.

What users get

A patches block in the root socket.yml. Keep version: 2 so the scanner and socket-cli keep working; they strip or ignore the block.

# Critical first: widen by editing one line
version: 2
patches:
  minSeverity: critical   # later: high, then low, then remove the key

# One directory of a monorepo first
version: 2
patches:
  includePaths:
    - "/services/payments/"

# One ecosystem, hold one package
version: 2
patches:
  ecosystems: [npm]
  ignorePackages: ["pkg:npm/left-pad"]

# Pause: report only, existing patches stay in place
version: 2
patches:
  enabled: false

• Keys: enabled, includePaths, ignorePaths, ecosystems, packages, ignorePackages, minSeverity (critical|high|medium|moderate|low) and maxNewPatches. maxNewPatches is validated here and enforced by B.
• Paths: gitignore patterns with npm ignore semantics, matched against each project's lockfiles. A golden fixture generated from the npm package pins this.
• Existing scanner key: projectIgnorePaths is now honored too.
• Test/fixture defaults: test/ tests/ fixtures/ __fixtures__/ testdata/ are skipped by default for discovered roots (scan 'services/*', in-memory detection). This replaces the hard-coded list in the in-memory engine. Re-include one with ignorePaths: ["!/e2e/tests/"], on disk and in memory. A directory you name yourself is always scanned.
• Flags only narrow further. New --min-severity <level|none> / SOCKET_MIN_SEVERITY beats the file's floor. New --no-socket-yml / SOCKET_NO_SOCKET_YML ignores the file.
• Narrowing never removes a patch. A package that already has a recorded patch (manifest > hosted pins > vendor ledger) and is now filtered is left byte-identical. It is listed in policy.retained[] with upgradeAvailable. A recorded merged patch below a new floor is kept.
• Fails closed. A broken file fails scan before any request or write: exit 1, errorCode: socket_yml_invalid (or socket_yml_ambiguous when socket.yml and socket.yaml disagree). The message names the key path, gives a did-you-mean hint, and suggests --no-socket-yml. Example: socket.yml: patches.minSeverty: unknown key (did you mean minSeverity?) ….
• Reporting. Every successful scan --json gains a top-level policy block:

  "policy": {"source": "file", "path": "socket.yml", "sha256": "…", "enabled": true,
             "minSeverity": {"value": "high", "source": "file"},
             "counts": {"filtered": 3, "retained": 1},
             "filtered": [{"purl": "pkg:npm/qs@6.5.2", "uuid": null, "project": "services/legacy",
                           "reason": "policy_path_excluded", "detail": "/legacy/ (patches.ignorePaths)"}],
             "retained": [{"purl": "pkg:npm/lodash@4.17.20", "project": "", "recordedUuid": "…",
                           "reason": "policy_package_ignored", "detail": "…", "upgradeAvailable": true}]}

  Human output adds Policy (socket.yml): N skipped by filters, M patched packages held. and always names skipped critical/high patches.
• Commands: get ignores the policy and warns policy_bypassed. A hosted/vendored PATH outside the repo root is exit 2. --global reads no file.
• In-memory engine: two-phase selection (§7.2).
  • The host fetches the root socket.yml / socket.yaml first and passes it to selectHostedScanPaths as policyFiles: [{path, text} | {path, missing: true}], plus noSocketYml.
  • Selection applies the full path policy, negations included. It returns policyPaths, policySha256 and policyError. An excluded root goes into ignoredSample with its policy_* reason and is not streamed.
  • The session takes noSocketYml, minSeverity, policyPaths and policySha256. It fails socket_yml_invalid if the policy it reads differs from what selection read.
  • The result carries policy, or policyError with no root processed and no file changed.
  • hosted-bundle and index.d.ts have the new fields.

Trust boundary (CLI_CONTRACT.md): socket.yml may narrow or pace, never widen. Keys like apiUrl, apiToken, org, mode or downloadMode are unknown keys and fail validation.

Layout

• crates/socket-patch-core/src/policy/ holds the frozen §9.0 contract:

  • SelectionPolicy, PolicySource, FilterReason, PolicyError, PolicyFs, Root, Offers;
  • package_spec_matches, moved from the CLI;
  • find_repo_root, repo_relative.

  It also holds the strict parser (socket_yml.rs) and the top-down gitignore matcher (paths.rs).

• commands/scan/policy.rs, commands/scan/socket_yml_args.rs: disk glue and flags. discover_selected now returns Offers.

• hosted_memory/select.rs: two-phase policy selection.

• New deps, exact-pinned: serde-saphyr =1.3.0 and ignore =0.4.33.

• CI: the test-release timeout goes from 40 to 50 minutes. A docs-only change already takes about 38 minutes, and this PR adds two crates and a test binary.

Decisions where the plan left a gap

These are recorded in docs/design/staged-rollout.md §9.4:

1. YAML parsing: serde-saphyr's event parser, so aliases are never expanded, and anchors/aliases/merge keys are refused only inside patches/projectIgnorePaths. serde_norway can't refuse them per subtree.
2. Disk markers match the in-memory lock markers; manifests are not markers. This keeps both engines' path results identical.
3. Floor vs recorded patch: a ranking-based "keep recorded" rule stands in until B's search_result_supersedes.
4. enabled: false: recorded packages go to retained[], the rest to filtered[].
5. In-memory gaps until B's recorded view: there is no retained[] yet, and policy.filtered[] lists only the roots the session received.
6. Two-phase handshake: §7.2 doesn't say how the session learns what selection saw. It is policySha256, returned by selection and passed to the session; a session that reads a policy file without it fails closed. policyFiles.text must be a lossless decode (Node buffer.toString('utf8'); TextDecoder drops a BOM).
7. README recipes: R1/R5 (which depend on the cap) are left for B.

Tests

• Core unit tests:
  • every §4.4 row;
  • BOM/CRLF/UTF-16/NUL, empty and absent files, alias bomb, depth, the both-files rules;
  • lookup with a .git dir, file or none, GIT_CEILING_DIRECTORIES and a foreign owner;
  • symlink inside/outside, directory, FIFO, oversize;
  • the 1377-case npm ignore golden fixture, and this repo's own socket.yml.
• Disk e2e (tests/e2e_socket_yml_policy.rs, real binary, wiremock catalog, monorepo with npm roots and a gem):
  • filtering by path, ecosystem, package and severity in hosted, dry-run, agent and vendored mode;
  • PATH-glob defaults vs literal PATHs, includePaths, projectIgnorePaths;
  • invalid and ambiguous files (exit 1, no request, no bytes changed), --no-socket-yml;
  • flag/env precedence;
  • retained pins byte-identical in hosted and agent mode;
  • recorded merged patch kept, enabled: false, PATH outside the repo, and get's warning.
• Parity (hosted_memory_parity.rs, through the real two-phase flow):
  • the same roots and packages are filtered on disk and in memory, and severity floors match;
  • a negation re-includes a default-ignored root, which is fetched and patched byte-identically to disk;
  • a withheld, changed, digest-less, invalid or half-bypassed policy gives policyError;
  • selection fails closed on a missing, symlinked or invalid policy file, and option precedence holds.
• Parser contract: cli_parse_scan.rs rows for both flags and env vars.
• Checks: cargo clippy --workspace --all-features --all-targets -D warnings is clean. The policy, in-memory, parity, scan and get suites pass locally.

CI failures inherited from the base (not this PR's)

• vlt compatibility, 0.0.0-1 / 0.0.0-11: three hosted-rollback tests fail. The base's own run on 28cebf7 fails the same way.
• yarn-classic 1.0.2 / 1.6.0 / 1.7.0 / 1.9.4: mode_migration_npm expects an integrity line that old yarn 1.x doesn't write. ci: pin TLS-verified patch hosts on macOS compat legs (fix hosted DNS flake) #295 fails the same legs.

🤖 Generated with Claude Code

---

Generated by Claude Code

---

Note

Medium Risk
Changes what scan patches in all modes and CI, but policy only narrows behavior with fail-closed validation and extensive e2e/parity tests.

Overview
scan now honors repo-root socket.yml to narrow patching across hosted, vendored, agent, dry-run, and the in-memory autopatch engine. A patches block (plus existing projectIgnorePaths) can disable writes, scope by gitignore-style paths/ecosystems/packages, and set a severity floor; existing recorded patches are never removed—filtered packages land in policy.retained[] with reporting via a new top-level policy JSON block and human Policy (socket.yml): … line.

CLI: --min-severity / SOCKET_MIN_SEVERITY and --no-socket-yml / SOCKET_NO_SOCKET_YML; invalid or ambiguous YAML fails scan before network or disk writes (exit 1, socket_yml_invalid / socket_yml_ambiguous). Discovered roots skip test/, tests/, fixtures/, etc. by default (negation supported); get bypasses policy with policy_bypassed warnings. Policy logic lives in new socket-patch-core policy (serde-saphyr, ignore); in-memory flow is two-phase (selectHostedScanPaths → session with policySha256). CI test-release timeout raised 40→50 minutes.

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

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	cargo/​ignore@​0.4.33
	cargo/​serde-saphyr@​1.3.0

View full report

[socket-security-staging]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	cargo/​ignore@​0.4.33
	cargo/​serde-saphyr@​1.3.0

View full report

[Mikola Lysenko (mikolalysenko)]

[agent] CI note: vlt patch compatibility / install-proof (…, vlt 0.0.0-*) fails the same way on both 48f2e78 and faa6ffc. The failing suite is e2e_redirect_vlt_build, with 5 hosted rollback tests:

• hosted_crlf_lock
• hosted_idempotence
• hosted_resave_crlf_rollback
• hosted_resave_install_rollback
• hosted_rollback_byte_exact

In each, rollback exits 1 with hosted_wiring_contested / patched_ref_unattributable for a vlt-lock.json that has no lockfileVersion.

This is not caused by this PR. rollback never reads the socket.yml policy, and this diff doesn't touch the rollback or vlt code. The same 5 tests fail identically on #282 (run 36430532691), which only merged the current base (#283), and #279/#281 go red on this workflow too after the same merge.

I don't know of a fix to port yet. I'll re-run the failed jobs once when this run finishes.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

[agent] CI note: Poetry patch compatibility / native (macos-latest, 1.8.5) failed on faa6ffc, and failed again on its one re-run.

Which cases fail. Only the hosted cases fail:

• direct hosted: ERROR, where poetry's own install raises SSLError → ConnectionError "Cannot install urllib3" while fetching from patch.socket.dev.
• crlf hosted: poetryInstallExit0 and the install checks that depend on it.

The socket-patch side of those cases is fine: the relock keeps the patch, check --lock exits 0, and the VEX run emits 1 statement. The other cases in that job pass.

Why I don't think this PR causes it.

• In the same run, the same faa6ffc binary passes 27 of the 28 poetry legs. That includes ubuntu-latest, 1.8.5 and every other macOS poetry version.
• The failing step is poetry 1.8.5's HTTPS download on the macOS runner, and this diff doesn't touch the hosted rewriters or any URL.
• The same leg passed on 48f2e78 20 minutes earlier.

I can't pull the capture artifact from this sandbox, so I can't prove it further. The re-run is used; I'll keep watching and look again if it shows up on the next push.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

[agent] test (windows-latest) fails in one target, -p socket-patch-cli --test covgap_commands_scan_mod. This PR does not change that test file.

This failure comes from the base branch:

• Base PR WS5: one VendoredBackend for vendored apply/revert/repair; cut repair's ledger rebuild #283 (06437d2, now in release/v5-prerelease) failed the same Windows target on its own last CI run: job 108911094705, on 9d46742.
• Plan PR v5 design: staged patch rollout (socket.yml + scan limit) #290 changes only docs, and it fails the same target on Windows twice, including one rerun (job 108972851206).
• Ubuntu and macOS pass this target.

No fix exists yet, so I haven't ported one. The job logs cut off before the failing test's name, so I can't propose a patch from here. I won't rerun this job, because the same failure on the base branch already rules out a flake.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

[agent] Merged release/v5-prerelease after #290 landed, and implemented the plan's late change to §7.2 (commit 82f5b00: two-phase in-memory selection).

What changed

• Two-phase selection: selectHostedScanPaths now takes policyFiles: [{path, text} | {path, missing: true}] and noSocketYml, and applies the full socket.yml path policy, negations included. So ignorePaths: ["!/e2e/tests/"] selects, fetches and patches that tree in memory exactly as on disk, which a new parity test checks against disk.
• Fail closed at selection: a listed policy file that isn't passed, is passed missing, is symlinked or is invalid returns policyError, and nothing is selected.

Gap decisions (recorded in staged-rollout.md §9.4, item 9)

• How the session learns what the selector saw: §7.2 doesn't say. Selection returns policySha256 (null with no file, an empty file, or noSocketYml), and the session takes it as an option. A session that reads a policy file with a different digest, or with none, fails socket_yml_invalid. So does a bypassed session that is given a digest.
• Excluded roots: a root the selector excludes is not streamed. It is reported in ignoredSample with its policy_* reason, so in memory policy.filtered[] lists only the roots the session received. Streaming presence-only markers instead would count every fixture lockfile against maxFiles.
• Decoding: policyFiles.text must decode losslessly. Use Node's buffer.toString('utf8'); TextDecoder drops a BOM, and the session then sees different content.

Other changes

• Test job timeout: test-release passed in about 39 minutes on b975913 under the new 50-minute limit.
• Windows failure: the base-branch failure in covgap_commands_scan_mod should clear now that v5 fix: unblock the e2e tier on the v5 base #288's fix is merged in.

Checks run locally: clippy (--all-features --all-targets) is clean, and the in-memory, parity, socket.yml end-to-end and CLI parse tests pass. The full workspace run has 19 local-only failures: write-failure tests that don't fail as root, and one peak-memory check. None is in code this PR changes.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

[agent] Update on the vlt compatibility failures, now at 4b71112 (base 28cebf7 is merged in):

• Failing now: three install-proof legs, vlt 0.0.0-1 and 0.0.0-11 (plus the 0.0.0-1 / Node 22.0.0 leg). They fail three tests in e2e_redirect_vlt_build.rs: vlt_pinned_matrix_hosted_crlf_lock, vlt_pinned_matrix_hosted_idempotence and vlt_pinned_matrix_hosted_rollback_byte_exact. Rollback exits 0 but doesn't restore the lock byte for byte.
• Why this isn't this PR's: the base's own dispatched vlt run on 28cebf7 (run 36454568301) fails exactly these three tests on the same legs. This PR doesn't touch the rollback or vlt code.
• Fixes merged so far:
  • 28cebf7 (vlt pin attribution in rollback) is merged here, and so is v5 fix: unblock the e2e tier on the v5 base #288.
  • Together they took the failures from five tests on every leg down to these three tests on the oldest vlt releases.
• Remaining fix: none exists for the last three tests yet. I'll merge it here as soon as it lands on the base.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

[agent] The yarn-classic legs (1.0.2, 1.7.0, 1.9.4, …) fail in the mode_migration_npm suite. This PR didn't cause it:

• Cause: mount_registry_from_classic_lock (tests/mode_migration_npm.rs:407) panics with "no integrity in …". Old yarn 1.x releases write a yarn.lock with only resolved and no integrity line. I reproduced it locally with yarn 1.7.0, and it passes with 1.22.22.
• Not this PR's: this PR doesn't touch that test or scripts/yarn-classic-vex-matrix.sh. PR ci: pin TLS-verified patch hosts on macOS compat legs (fix hosted DNS flake) #295, on the same base with only CI changes, fails the same legs (1.0.2, 1.6.0, 1.7.0, 1.9.4) in run 36455144314. These legs seem to have started running after v5 fix: unblock the e2e tier on the v5 base #288's CI tier change.
• Fix: none exists yet. The fix belongs in the test helper, which would fall back to the tarball's sha1 from the resolved URL fragment when there's no integrity line. I'm not widening this PR to include it.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

#281 landed on release/v5-prerelease as 73c0c4f; please merge origin/release/v5-prerelease again, resolve conflicts, get green, and keep it ready.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

#279 landed on release/v5-prerelease as f6bdad5; please merge origin/release/v5-prerelease again, resolve conflicts, get green, and keep it ready.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

[agent] ready to land

Head f680990 is merged up to release/v5-prerelease at f6bdad5 (#279) with no conflicts outstanding. CI results on this head:

• All workflows pass except the legs the base branch already fails on:
  • CI: 233 jobs; only yarn-classic 1.0.2 / 1.6.0 / 1.7.0 / 1.9.4 fail.
  • vlt: 87 jobs; only the 0.0.0-1 / 0.0.0-11 install-proof legs fail, on the three hosted-rollback tests.
• f680990 fixes the coverage/test failure on the previous head. v5: remove setup (WS7) + patch UI streamlining (WS8) #279's new help_text_hygiene test caps scan -h at about 8 options, so --no-socket-yml and --min-severity now appear only in scan --help.

---

Generated by Claude Code

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

^{Bugbot Autofix is ON. A cloud agent has been kicked off to fix the reported issues.}

Comment @cursor review or bugbot run to trigger another review on this PR

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

[Mikola Lysenko (mikolalysenko)]

#282 landed on release/v5-prerelease as 14a9cb0; please merge origin/release/v5-prerelease again, resolve conflicts, get green, and keep it ready.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

[agent] ready to land

Head 0881dedd merges release/v5-prerelease at 14a9cb07 (#282), with conflicts resolved.

What the merge changed. #282 moved the in-memory engine into socket-patch-core, and the two-phase policy selection moved with it.

• The helpers for the shared policy block (policy_block, FilteredEntry, RetainedEntry, canon) now live in socket_patch_core::policy. The core engine and disk scans render the block from that one place.
• scan now reads the ledgers and wiring through v5 WS4/WS6: one hosted engine for disk + memory; unified Ledgers view #282's ProjectContext.

This head also includes 65ef71fd, which fixes both Bugbot findings. Those threads are resolved.

CI on 0881dedd. Every workflow is green except the legs the base branch already fails on:

• CI: 233 jobs; only yarn-classic 1.0.2 / 1.6.0 / 1.7.0 / 1.9.4 fail.
• vlt: 87 jobs; only the 0.0.0-1 / 0.0.0-11 install-proof legs fail. These are the same three hosted-rollback tests as before v5 WS4/WS6: one hosted engine for disk + memory; unified Ledgers view #282.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

#291 landed on release/v5-prerelease as f9cb7e1; please merge origin/release/v5-prerelease again, resolve conflicts, get green, and keep it ready.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

[agent] ready to land

Head 997a6f50 merges release/v5-prerelease at f9cb7e13 (#291).

• Conflict: only the test-release timeout. I took the base's 40 minutes, because v5 CI: build e2e binaries once and tier the PM matrix #291 removed the second feature-set build that the 50 minutes here was sized for. test-release now finishes in about 16 minutes on this head.
• CI on 997a6f50: every workflow passes except the jobs the base branch also fails:
  • CI: 182 jobs; only yarn-classic 1.0.2 / 1.6.0 / 1.7.0 / 1.9.4 fail.
  • vlt: 87 jobs; only the 0.0.0-1 / 0.0.0-11 install-proof legs fail.
• Reviews: no new review findings. Both Bugbot threads are resolved.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

#292 landed on release/v5-prerelease as a7b0d00; please merge origin/release/v5-prerelease again, resolve conflicts, get green, and keep it ready.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

[agent] ready to land

Head 0c5a8cd4 merges release/v5-prerelease at a7b0d00e (#292).

• Merge: clean, with no conflicts. Clippy passes, as do the policy, in-memory, parity, e2e policy, parser and help suites.
• CI on 0c5a8cd4: every workflow passes except the legs the base branch also fails:
  • CI: 182 jobs; only yarn-classic 1.0.2 / 1.6.0 / 1.7.0 / 1.9.4 fail.
  • vlt: 87 jobs; only the 0.0.0-1 / 0.0.0-11 install-proof legs fail.
• Reviews: no new review findings.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

#296 landed on release/v5-prerelease as 1e3ace6; please merge origin/release/v5-prerelease again, resolve conflicts, get green, and keep it ready.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

[agent] test (windows-latest) failed on d9dd0ff in update_notifier_e2e, and every other target passed. The e2e matrix was skipped because it depends on this job. This PR doesn't touch the notifier test or the update code, all 39 notifier tests pass locally on this head, and the job passed on this PR's earlier heads with the same notifier code. It looks like a Windows timing failure (the test has wall-clock budgets, e.g. grace_budget_bounds_command_latency). The failing assertion isn't in the API's 5,000-line log tail, so I can't confirm which test. I've re-run the failed jobs once. If it fails again I'll treat it as real and look into it.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

[agent] ready to land

Head d9dd0ff merges #296 (base 1e3ace6) with conflicts resolved. CI has finished on this head:

• The re-run of test (windows-latest) passed, so the earlier update_notifier_e2e failure was a one-off. All three test legs are green, and the e2e matrix ran.
• The only failures are legs that also fail on the base: yarn-classic 1.0.2/1.6.0/1.7.0/1.9.4, and vlt install-proof ubuntu 0.0.0-1 (Node 22 and default), ubuntu 0.0.0-11 and windows 0.0.0-11.
• No review threads are open. The PR is not a draft.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

#297 landed on release/v5-prerelease as b97a1c2; please merge origin/release/v5-prerelease again, resolve conflicts, get green, and keep it ready.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

[agent] ready to land

Head 29674bb merges #297 (base b97a1c2) with no conflicts. CI has finished on this head:

• CI, vlt, Bun, PDM, pnpm, Poetry, npm and Pipenv all completed. All three test legs and the e2e matrix pass.
• The only failures are legs that also fail on the base: yarn-classic 1.0.2/1.6.0/1.7.0/1.9.4, and vlt install-proof ubuntu 0.0.0-1 (Node 22 and default), ubuntu 0.0.0-11 and windows 0.0.0-11.
• No review threads are open. The PR is not a draft.

---

Generated by Claude Code