Fix stale docs and comments, and the npm wrapper's schema and exit code

[Mikola Lysenko (mikolalysenko)]

Problem

The architecture audit (report §6.3, §7 item 17, and B71) found docs and code comments that no longer match the code, plus three defects in the npm wrapper package:

• CLI_CONTRACT.md:907 says a declined rollback prompt prints Rollback cancelled.. The code prints the shared ui::CANCELLED text, Cancelled; no changes made. (rollback.rs:1430).
• CLI_CONTRACT.md:1136 says tests/cli_parse_*.rs are "snapshot tests that lock the shape" of the JSON envelope. Those tests pin the parsed clap *Args structs. The envelope shape is pinned by json_envelope.rs's unit tests and by each command's e2e tests.
• Comments about the deleted hosted ledger and replay: CLI scan/hosted.rs, core hosted/engine.rs and patch/redirect/staged.rs still describe a redirect-ledger load, a merge-then-persist, a ledger-record fallback, replay.rs, super::ledger, super::takeover, super::replay, and edit ordering for a "whole-ledger replay". None of these exist in v5.
• vex/discover/pypi_other.rs:20 names vendor::pypi_pipenv::is_socket_hosted_reference as an any-host twin. Recognize hosted Pipenv references through one shared grammar (#563) #572 deleted that function.
• update/release.rs:15-17 says the API client has a "no-timeout posture". That has been false since Bound patch API connects and stalled reads (#570) #581 added ApiTimeouts.
• scan/policy.rs:70-72 says "manifests are not markers". dir_markers falls back to manifests whenever a directory has no lock marker.
• B71 (npm wrapper):
  • The zod PatchManifestSchema lacks the legacy setup block that the Rust manifest still parses and keeps, so validating a pre-v5 manifest strips it.
  • The schema tests never run in CI, and the test script calls pnpm in an npm-locked package.
  • A binary killed by a signal is reported as exit 1.
  • With no files list, the tarball ships src/, the tsconfig and the compiled tests.

Change

• Fixed both CLI_CONTRACT lines.
• Rewrote the stale comments to describe what the code does now:
  • Hosted mode keeps no ledger. The vendored ledger is the only one the hosted flow loads.
  • The gem stale-install probe judges only this run's fetched records, and its test helper and uuid-matching test now say so.
  • staged.rs serves the hosted → upstream restore.
  • Self-update uses whole-request deadlines, while ApiTimeouts uses connect and per-read bounds.
  • The pypi twin is hosted_pypi_reference.
  • dir_markers falls back to manifests, and the in-memory engine does not.
• npm wrapper:
  • Added SetupConfigSchema (optional exclude/manual string lists, mirroring SetupConfig in core manifest/schema.rs) to PatchManifestSchema.
  • A signal death now exits with 128 + the signal number (SIGINT 130, SIGTERM 143), as a shell reports it.
  • Added a files list: the wrapper, any bundled bin/socket-patch-* binaries, and the compiled schema .js/.d.ts.
  • The test script now uses npm, and the dispatch-tests CI job runs it.

Every change is to docs, comments or the npm/socket-patch package, plus one added step in the CI dispatch-tests job. No Rust behavior changes. Duplicate copies deleted: none (this workstream consolidates no code).

Testing

• node --test npm/socket-patch/bin/socket-patch.test.mjs: 23 pass, 1 skipped (the Linux-only musl fallback). Four of these are new and failed first: three signal-exit tests, and the npm pack --dry-run contents test. Once dist/schema is built, the contents test also requires both dist/schema/manifest-schema.js and .d.ts in the pack list. CI re-runs it with --test-name-pattern="npm package contents" right after npm test builds dist/.
• npm test in npm/socket-patch (tsc + zod tests): 10 pass. The three new setup tests failed first, at compile time.
• cargo build -p socket-patch-cli: OK.
• cargo test -p socket-patch-core --lib filtered to hosted::engine, update::release, vex::discover::pypi_other and patch::redirect: 166 pass.
• cargo test -p socket-patch-cli --lib -- scan::hosted scan::policy: 61 pass, re-run after the review fixes. That includes the renamed gem_stale_probe_matches_records_by_uuid_not_purl_key.
• cargo clippy -p socket-patch-cli --all-targets -- -D warnings on macOS:
  • One pre-existing error on main: unused unix_default at core crawlers/python_crawler.rs:2734, a cfg-dependent macOS-only warning in a file this PR does not touch.
  • With that lint allowed (-A unused_variables), every remaining lint is in crates/socket-patch-cli/tests/** integration-test files this PR does not touch. There are none in src/.
  • Linux clippy is left to CI.
• I checked every --flag, subcommand and --mode/--vendor-source value in README.md and docs/*.md against the built binary's --help. I found no drift: every unmatched flag belongs to another tool (cargo, git, gh, gradle, dotnet).
• All commands ran through the shared heavy-job.sh limiter with -j4 and CARGO_INCREMENTAL=0.

Deferred

• Coordination with Run CI on the merge queue and stop cancelling main push runs #1018 (CI merge queue): it also edits ci.yml and lists dispatch-tests in a needs aggregate. This PR only adds steps inside the dispatch-tests job, a different hunk, but whichever PR lands second needs a rebase check.
• The pack-contents test landed one commit before the files list (333acc4 fails node --test by itself). It is left as is because the PR will be squash-merged.
• ci.yml's "REQUIRED status check" and "always finish" comments are left to Run CI on the merge queue and stop cancelling main push runs #1018 (CI merge queue), which rewrites that block.
• CHANGELOG.md:12-21 is not touched, per AGENTS.md.
• The ledger-doc (Discussion socket-patch architecture (living document): review, defect register and refactoring log #560) drift in §6.3 Parts 2–9 is ledger work, not a repo change.
• The vex.rs RedirectState used as an in-memory carrier for hosted records is a code change (proposed typed HostedRecords), not a comment fix.
• Other "redirect ledger" mentions in vex/discover and the vendor backends describe the pre-v5 migration read, which still exists, so they are kept.
• The cancel-exit inconsistency across commands (update exits 1, others exit 0) belongs to the Decide: one shape for the --json top-level error (scan and get emit both a string and a {code, message} object) #704 exit-policy decision. This PR does not decide it.

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation and npm wrapper packaging/exit-code behavior only; Rust CLI logic is unchanged aside from comment edits.

Overview
Aligns CLI_CONTRACT and scattered Rust comments with v5 behavior (no hosted redirect ledger, shared cancel text, where JSON envelope tests live, dir_markers manifest fallback, self-update timeouts, PyPI hosted URL parsing). No Rust runtime changes.

The @socketsecurity/socket-patch npm package gets substantive fixes: optional legacy setup block on the Zod manifest schema (parity with Rust), shell-style exit codes on signal death, an explicit files whitelist so publishes ship only the wrapper and compiled schema, npm test instead of pnpm, and new tests (signals, npm pack contents, setup round-trip). CI dispatch-tests now runs schema build/tests and re-runs the pack-contents check after dist/ exists.

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

[Mikola Lysenko (mikolalysenko)]

Filtered Rust tests for the touched modules pass on macOS:

• cargo test -p socket-patch-core --lib -- hosted::engine update::release vex::discover::pypi_other patch::redirect::upstream: 166 passed
• cargo test -p socket-patch-cli --lib -- scan::policy scan::hosted: 61 passed