[jdalton]

What this PR does

This PR gives aube one supply-chain safety rule — a 7-day "soak" — and applies it everywhere a dependency or tool can enter the repo. The idea: when a new version of anything is published, we wait 7 days before adopting it. If that version turns out to be compromised (like the recent npm supply-chain attacks), the ecosystem usually finds out within days — and we never installed it.

It also adds core::hint::cold_path() branch hints to aube's hottest install loops (the perf work that kicked this off), pins every external tool we use by exact version + checksum, and routes CI installs through Socket Firewall.

The soak, explained (start here)

"Soak time" = the minimum age a release must reach before we install it. Ours is 7 days, defined once in scripts/soak/constants.mts (SOAK_DAYS = 7). Every other file derives from or is checked against that one constant, so the number can't quietly drift between config files:

Surface	File	What it controls
Rust toolchain	rust-toolchain.toml	We build with a dated nightly that was at least 7 days old when we adopted it
Rust crates	.cargo/config.toml	cargo's -Zmin-publish-age skips crate versions younger than 7 days
npm deps (docs/)	docs/pnpm-workspace.yaml	minimumReleaseAge: 10080 — same rule in minutes, read by aube itself
npm CLI parity	docs/.npmrc	min-release-age=7 for anyone using npm ≥ 11.17 directly
Version bumps	docs/taze.config.mts	taze (the dep updater) only suggests versions ≥ 7 days old
Renovate PRs	.github/renovate.json	minimumReleaseAge: "7 days", explicit in-repo (the shared preset already sets it, but preset drift would be silent) — Renovate commits updated lockfiles, and -Zmin-publish-age skips already-locked versions, so Renovate itself is the only place this path can be soaked

Fun part: aube ships minimumReleaseAge as a feature for its users — this PR makes aube's own repo use it (the docs deps install with aube itself).

The soak manager: scripts/soak/

• constants.mts — the one source of truth (SOAK_DAYS, plus the annotation rules below).
• paths.mts — every file path the scripts touch, declared exactly once ("1 path, 1 reference"). This is the only file that differs from nub's copy of these scripts.
• soak.mts --check — fails CI if any surface drifts from SOAK_DAYS. --fix rewrites them.
• update-deps.mts — bumps npm deps (via taze) and cargo deps, both under the soak. It refuses to run cargo update with a non-rustup cargo, because only rustup's cargo reads rust-toolchain.toml — a Homebrew cargo would silently skip the soak.
• external-tools.mts — installs the pinned external tools (below).
• .claude/skills/soak/SKILL.md — a repo skill so agent sessions pick up the procedures (change the window, opt out, add an exclusion, bump the nightly) without re-deriving them. Written to Anthropic's skill-authoring + prompting guidance, which it links; the skill documents the law, scripts/soak/ is the law.

Skipping the soak for one package is allowed but must be visible and temporary. A version-pinned entry in minimumReleaseAgeExclude requires a dated comment right above it:

# published: 2026-07-08 | removable: 2026-07-15
- 'typescript@7.0.2'

removable must equal published + 7 days. Once that date passes, the pin has soaked and --check fails until it's removed (--fix prunes it). Unannotated pins, impossible dates (2026-13-45), and flow-style [...] lists (which the parser can't validate) are all rejected.

Pinned external tools + Socket Firewall in CI

external-tools.json pins every external tool to an exact version with a sha512 SRI (a checksum: if the downloaded bytes don't hash to the pinned value, the install fails). Pinned: pnpm 11.8.0, npm 12.0.0, sfw (Socket Firewall, free + enterprise tiers), zizmor, agentshield, skillspector.

external-tools.mts --install <name> downloads, verifies the checksum, and installs into a local "rack" ($XDG_DATA_HOME/aube/dev-tools/rack/<tool>/<version>/) with a symlink in a bin/ dir you put on PATH. npm-packaged tools get their own deps installed by aube itself (dogfooding), prod-only with lifecycle scripts skipped.

--shims writes tiny bash wrappers named npm, pnpm, cargo, etc. that route the real command through sfw — so every package install in CI passes through the firewall. When the command itself is one of our pinned PMs, the shim executes the pinned binary, not whatever PATH happens to find.

About the secret: SOCKET_SECURITY_KEY is the only credential env var. It isn't set in this repo yet — that's fine, because sfw's free tier needs no key. When the secret lands, the same code automatically selects the enterprise tier.

One thing that deliberately does NOT auto-update: npm 12.0.0 is younger than 7 days, so its pin carries a soakBypass annotation with the same published/removable dates — and --check fails once that window passes without the annotation being removed.

Buildkite image: smaller and pin-checked

The CI agent image now installs its three Rust toolchains with --profile minimal (the default profile ships rust-docs — roughly 600 MB per toolchain we never read in CI), and pre-bakes sfw + its shims so jobs don't download them every run.

The catch: the image builds from .buildkite/ alone, so its Dockerfile cannot read external-tools.json or rust-toolchain.toml — it has to embed copies of the version + checksums. Copies drift. So external-tools.mts --check (run in CI) decodes the checksums and fails if the Dockerfile's copies stop matching the tracked pins. Same trick the soak uses for .npmrc: when a file can't import the constant, a check asserts it matches.

The cold-path hints (the original perf work)

core::hint::cold_path() (stable since Rust 1.95 — hence the MSRV bump 1.93 → 1.95) tells the optimizer "this branch almost never runs", so it moves that code out of the hot instruction stream. Applied to the rare arms of four hot loops: the per-file linker materialize loop (reflink→hardlink→copy fallbacks), the pnpm-lockfile byte parser's bail-out paths, the semver cache misses, and the tar-extraction validation errors.

Why bother when we have PGO? Only x86_64 Linux release builds get PGO+BOLT — macOS, arm64, and Windows ship plain builds where these hints are the only branch-layout signal. The toolchain itself is pinned to nightly-2026-07-04 (the newest nightly ≥ 7 days old when adopted; nightly is required for -Zmin-publish-age), while rust-version = "1.95" stays the declared stable floor.

How it's tested

• 55 node:test unit tests cover the checkers, fixers, parsers, and CLIs (mise run test:scripts; also part of the CI gate) — ~82% line coverage overall. Review findings live on as regression cases (impossible calendar dates, expired bypasses, flow-style lists, trailing comments, catalog drift, the --npm --cargo selector bug), and the security-relevant paths are pinned by tests: the downloader sends GITHUB_TOKEN to github.com only and rejects any checksum mismatch, the sfw flavor flips on SOCKET_SECURITY_KEY, every Dockerfile-prebake drift class fires against a synthetic image, and both CLIs round-trip end-to-end through their entrypoints.
• clippy -D warnings + fmt clean on the pinned nightly; cargo unit tests green (6 pre-existing registry-mock failures on the dev machine come from a local TLS proxy, not this PR).
• The soak proven live: cargo update --dry-run holds back ~25 too-fresh versions with "published N days ago" notes; taze only proposes soaked versions.
• The tool installer proven end-to-end: zizmor downloaded, checksum-verified, racked — then used to lint this PR's own workflow edits (clean). pnpm/npm round-trip through the shims (11.8.0 / 12.0.0), and CI asserts that on every run.
• Review-bot findings (coderabbit, greptile) were each fixed, replied to, and resolved — including a genuinely great catch where writing a shim through its symlink overwrote the pinned binary with the shim script, making it execute itself forever.

This PR was generated by Claude.

Post-open additions

• Windows tool handles: installed-tool handles forward to the absolute rack target via .cmd + bash shims (a copied handle strands pnpm's SEA launcher from its dist/ siblings), extraction uses System32 bsdtar cwd-relative, and the handle base strips .exe so pwsh never tries to execute a bash forwarder as a PE binary.
• Renovate soak surface: soak.mts now parity-checks .github/renovate.json minimumReleaseAge against SOAK_DAYS (with --fix), closing the one dependency path the local surfaces can't gate.
• Remote map as code: scripts/soak/remotes.mts declares where PRs live vs where branches push (--check/--fix/--print + mise run remotes:check), so tooling reads it instead of rediscovering it.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The repository raises its Rust MSRV to 1.95, pins nightly-2026-07-04, adds seven-day soak enforcement across Cargo and documentation tooling, manages pinned external tools and firewall shims, and marks selected branches as cold.

Changes

Toolchain, supply-chain soak, and external tooling

Layer / File(s)	Summary
Rust toolchain and cold-path updates .rules, Cargo.toml, rust-toolchain.toml, .cargo/config.toml, .buildkite/*, crates/*	Rust 1.95 and the dated nightly are configured across metadata and build images; selected linker, parser, cache, and tarball branches call core::hint::cold_path().
Seven-day soak validation and updates scripts/soak/*, mise.toml	Shared constants, surface checks, repair operations, and dependency-update commands enforce the seven-day release-age policy.
Pinned external tools and firewall shims external-tools.json, scripts/soak/external-tools.mts, .buildkite/sfw-shim-template.sh	External tool pins are validated and installed with integrity checks, while package-manager shims route commands through the socket firewall without recursion.
Documentation workspace soak surface docs/*	The docs workspace adds taze, its pinned lockfile graph, npm release-age configuration, and taze maturity settings.
CI soak and firewall enforcement .github/workflows/ci.yml, .rules	Linux CI runs soak and external-tool checks, installs firewall shims, and receives socket credentials.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CI
  participant SoakManager
  participant ExternalTools
  participant SocketFirewall
  participant PackageManager
  CI->>SoakManager: Run --check
  SoakManager->>SoakManager: Validate seven-day policy surfaces
  CI->>ExternalTools: Install sfw with shims
  ExternalTools->>SocketFirewall: Download and verify pinned binary
  ExternalTools->>CI: Expose shim bin directory
  CI->>PackageManager: Run dependency/install command
  PackageManager->>SocketFirewall: Route command through sfw

Loading

Possibly related PRs

• jdx/aube#912: Overlaps with the pnpm subset parser cold-path annotations and fallback behavior.

Poem

I’m a rabbit with a Rusty tune,
Seven-day carrots beneath the moon.
Cold paths nap where errors creep,
Pinned tools hop in guarded sleep.
The soak gate keeps watch!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 6.90% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately captures the main changes: a 7-day soak policy, cold-path hints, and pinned tooling.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.rules:
- Line 6: Align the Buildkite PGO toolchain with the repository pin by updating
.buildkite/linux-agent.Dockerfile to use Rust 1.95.0 and install
llvm-tools-preview instead of bootstrapping stable or installing 1.93.0. Update
the corresponding toolchain references in .rules at lines 6 and 190 to
consistently specify the pinned 1.95.0 toolchain; both .rules sites require
direct updates.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 71b34b35-cb83-4587-80d7-1b022f0a9f51

📥 Commits

Reviewing files that changed from the base of the PR and between 207f57e and c99106d.

📒 Files selected for processing (7)

• .rules
• Cargo.toml
• crates/aube-linker/src/materialize.rs
• crates/aube-lockfile/src/pnpm/subset.rs
• crates/aube-resolver/src/semver_util.rs
• crates/aube-store/src/tarball.rs
• rust-toolchain.toml

[greptile-apps]

Greptile Summary

This PR introduces a 7-day "soak" supply-chain safety window across every dependency surface in the repo (cargo crates, npm packages, the pinned Rust nightly, renovate), plus core::hint::cold_path() hints on rare branches in four hot install loops, a MSRV bump to 1.95, and a hardened Buildkite agent image with pre-baked sfw + minimal toolchain profiles.

• Soak system (scripts/soak/): single SOAK_DAYS constant in constants.mts; soak.mts asserts every data surface matches it and enforces dated # published: | removable: annotations on version-pinned excludes; external-tools.mts downloads, SRI-verifies (sha512), and installs pinned external tools into an isolated rack with sfw shims for all package-manager commands.
• Cold-path hints: core::hint::cold_path() added to error/fallback arms of the linker materialize loop, pnpm subset parser, semver cache, and tarball validator — correctly targeting rare branches only, consistent with the existing performance guidance in CLAUDE.md.
• Buildkite image: switches to --profile minimal (saves ~600 MB per toolchain), pre-bakes sfw + shims, and adds a checkDockerPrebake parity gate that fails CI if the Dockerfile's embedded sfw version/checksums drift from external-tools.json.

Confidence Score: 5/5

Safe to merge — all changed paths are additive (new scripts, new config files, new cold-path hints) with no behavioural regressions in the install pipeline.

The Rust changes are minimal and non-behavioural: cold_path() hints in error-only arms and a single refactor in source.rs that is semantically identical to the original. The soak system is pure additive infrastructure, covered by 47 unit tests that were expanded specifically to lock in every edge case caught during review. Previously flagged Windows .zip handling issues were addressed. The npm 12.0.0 soakBypass is correctly dated (removable 2026-07-16) and the CI gate will auto-enforce removal once that date passes.

No files require special attention. scripts/soak/external-tools.mts has a pre-existing Windows .exe idempotency gap on the early-exit path that was flagged in a previous review cycle; it is tracked and does not affect POSIX CI.

Important Files Changed

Filename	Overview
scripts/soak/external-tools.mts	Core installer: download, SRI-verify, extract, and rack pinned tools. Windows .zip fix (resolving .exe before throwing) is present; idempotency early-exit still only checks existsSync(destBin) without .exe fallback (previously flagged). linkHandle correctly strips .exe via name.replace(/\.exe$/, ''). Logic for shim writing, rackRealFor, npm-tarball install, and the --install argv loop all look correct.
scripts/soak/soak.mts	Parity gate and fixer for all six soak surfaces. Annotation parsing, expiry checks, date arithmetic (ISO string comparisons), flow-style rejection, and fixers all look correct. checkToolchainSoak correctly uses strict > so exact 7-day adoption passes.
scripts/soak/constants.mts	Single source of truth for SOAK_DAYS=7 and derived SOAK_MINUTES. isValidIsoDate correctly round-trips through Date to reject impossible dates; addDaysIso uses UTC to avoid DST issues.
crates/aube-lockfile/src/pnpm/subset.rs	Adds cold_path() to all bail-out/unknown-key branches in the fast pnpm lockfile parser. Placement is correct — these arms fire only on malformed/extended future lockfile keys, making them genuinely cold relative to the hot parse loop.
crates/aube-store/src/tarball.rs	cold_path() on four tarball validation error arms: entry cap exceeded, disallowed entry type, oversized entry, and size-declared-zero-but-non-empty. All are security/safety guards that should never fire on well-formed tarballs.
.buildkite/linux-agent.Dockerfile	Switches all three toolchains to --profile minimal, pre-bakes sfw-free 1.13.1 with sha512sum verification, and generates sfw shims from the template. The COPY/sed substitution approach keeps the shim template single-sourced. checkDockerPrebake in CI validates the embedded version/checksums against external-tools.json.
.github/workflows/ci.yml	Adds soak/tools:check/test:scripts gates, installs pinned pnpm/npm/sfw, and sets SFW_SHIM_ACTIVE_CARGO=1 to prevent the cargo shim from routing local registry test traffic through the sfw proxy — correctly documented in the inline comment.
external-tools.json	Pins pnpm 11.8.0, npm 12.0.0 (with soakBypass published:2026-07-09/removable:2026-07-16), sfw-free/enterprise 1.13.1, zizmor 1.26.1, agentshield 1.4.0, and skillspector git-SHA. All sha512 SRIs present and in the correct format. The soakBypass dates are mathematically valid (removable = published + 7d).
rust-toolchain.toml	Pins nightly-2026-07-04 with adopted:2026-07-11 — exactly 7 days, passing the strict > gate in checkToolchainSoak. Components include llvm-tools-preview for the PGO flow.
Cargo.toml	MSRV bump 1.93 → 1.95 to match the core::hint::cold_path() stabilization. Correct.

_{Reviews (22): Last reviewed commit: "fix(deps): close the renovate soak bypas..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (1)

scripts/soak/paths.mts (1)

52-56: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Reuse EXTERNAL_TOOLS_JSON instead of re-deriving the literal.

Line 53 rebuilds path.join(REPO_ROOT, 'external-tools.json'), which is exactly EXTERNAL_TOOLS_JSON (Line 45). This duplicates the path literal that this module's own header (Lines 2-6) says should be declared exactly once.

♻️ Proposed refactor

 export function assertRepoRoot(): void {
-  if (!existsSync(path.join(REPO_ROOT, 'external-tools.json'))) {
+  if (!existsSync(EXTERNAL_TOOLS_JSON)) {
     throw new Error(`repo root not found at ${REPO_ROOT}`)
   }
 }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/soak/paths.mts` around lines 52 - 56, Update assertRepoRoot to pass
the existing EXTERNAL_TOOLS_JSON constant to existsSync instead of rebuilding
the path with REPO_ROOT and the 'external-tools.json' literal. Leave the error
behavior unchanged.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.buildkite/linux-agent.Dockerfile:
- Around line 34-58: Keep the sfw-free version, architecture-specific assets,
and SHA512 values in sync with external-tools.json by adding a build-time
validation step around the sfw-free installation in the Dockerfile. Have it
parse the manifest’s corresponding 1.13.1 pin and checksums, compare them with
the values used by the asset selection and sha512sum verification, and fail on
any mismatch; avoid maintaining an independently editable duplicate.

In `@docs/taze.config.mts`:
- Around line 8-14: Update the dry-run argument selection in update-deps so dry
runs explicitly pass --no-write and cannot modify package.json, while preserving
--write for normal runs; ensure this override is consistent with the write
setting in docs/taze.config.mts.

In `@scripts/soak/external-tools.mts`:
- Around line 110-125: Update the fetch call in download to include signal:
AbortSignal.timeout(30_000), preserving the existing headers and redirect
options so stalled downloads fail after 30 seconds.

In `@scripts/soak/update-deps.mts`:
- Around line 67-74: Update the status handling in the function containing the
onlyCargo and onlyNpm branches so updateNpm(dryRun) and updateCargo(dryRun) are
both invoked whenever their ecosystems are enabled, regardless of the other
result. Aggregate each returned status after execution while preserving the
existing flag behavior and final status return.

---

Nitpick comments:
In `@scripts/soak/paths.mts`:
- Around line 52-56: Update assertRepoRoot to pass the existing
EXTERNAL_TOOLS_JSON constant to existsSync instead of rebuilding the path with
REPO_ROOT and the 'external-tools.json' literal. Leave the error behavior
unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: f3f961f9-1b63-4bbe-a139-c2f5fa29d0f3

📥 Commits

Reviewing files that changed from the base of the PR and between 8e4684d and 19abecd.

📒 Files selected for processing (17)

• .buildkite/linux-agent.Dockerfile
• .buildkite/sfw-shim-template.sh
• .github/workflows/ci.yml
• .rules
• docs/.gitignore
• docs/.npmrc
• docs/aube-lock.yaml
• docs/package.json
• docs/pnpm-workspace.yaml
• docs/taze.config.mts
• external-tools.json
• mise.toml
• scripts/soak/constants.mts
• scripts/soak/external-tools.mts
• scripts/soak/paths.mts
• scripts/soak/soak.mts
• scripts/soak/update-deps.mts

💤 Files with no reviewable changes (1)

• docs/.gitignore

✅ Files skipped from review due to trivial changes (3)

• docs/.npmrc
• docs/pnpm-workspace.yaml
• .rules

[github-actions]

This PR currently has failing checks. If this continues for 7 days, it will be closed automatically.

This is warning day 1 of 7.

Please update the PR when you have a chance. Feel free to reopen or create a new PR if it is closed and you'd like to continue working on it.

This comment was generated by an automated workflow.