test: drive freeze's write path and its append-only guard

[thedavidmeister]

Closes #46 — audit findings cov-02 and cov-03.

freeze could only ever be pointed at the real src/generated/ record, so neither its write path nor its SnapshotAlreadyFrozen append-only guard could be driven from a test. grep -rn SnapshotAlreadyFrozen test/ returned nothing: the only protection on the immutability of src/generated/<tag>/ — the record consumers pin their bytecode against — had never been seen to fire.

The seam

freeze now takes the record root the rest of the library already takes, threaded through new root-aware dirForSnapshot / pathForSnapshot variants.

Four choices worth stating, because each has a cheaper alternative that is wrong:

1. The root is a REQUIRED parameter, not an overload with a defaulting wrapper. The issue proposed the overload. A freeze that can still be called without a root can still be tested only against the real record, and the real record is one a test must not leave a release in. frozenSnapshotPaths, recordPathsForContract and writeReleasedSuitesLib do not default their root either.

2. Paths go through the root-aware helpers, not hand-concatenation inside freeze. The issue's proposed patch concatenated string.concat(root, "/", CANDIDATE, ...) directly — which the issue's own verification block flagged as a defect, against pathForSnapshot's docstring: "Two spellings of one path is how a freeze silently reads nothing." The two spellings are equivalent only while LibFs.pathForContract stays src/generated/<name>.sol, so any later drift would be silent. testRootAwareSnapshotPathIsTheWritersAtTheRealRoot fuzzes the root-aware spelling against LibFs's at the real root, so there is one path and not two.

3. Fixture snapshot content is comment-only. forge test compiles everything under test/, and a fixture left behind by a failing test is source the next run has to compile. A realistic fixture — declarations, as a real snapshot holds — turns one red test into a repo that will not build until somebody deletes a directory by hand. Found by deleting the SnapshotAlreadyFrozen guard and watching the next run fail to compile rather than fail its assertions.

4. testFreezeCutsEveryNamedContract asserts each frozen file holds its OWN contract's bytes. Asserting only that a file per name exists is satisfied exactly by a write loop that stores records[0] for every i, and by a read loop truncated to the first contract. Mutants m6, m7 and m8 below are those three, and the weaker assertion killed none of them.

writeSnapshot's docstring gave "writing this repo's record somewhere else is not [a thing]" as the reason no writer takes a root; it is reconciled here. freeze COPIES within one tree — reading a rolling snapshot under the root it is handed and writing the frozen copy under that same root — which is not the same freedom as choosing where a snapshot is GENERATED.

Tests added

• testFreezeCopiesTheRegeneratedRollingSnapshot — the freeze copies the bytes the REGENERATION wrote, not the bytes on disk when it was called, and the copy lands where the record walk finds it.
• testFreezeCutsEveryNamedContract — a release naming several contracts freezes every one, each from its own rolling snapshot.
• testFreezeRefusesARecutRelease — a re-cut is refused naming the tag and the directory, and leaves the first cut byte for byte.
• testFreezeRefusesATagDirectoryThatIsEmpty — the refusal is about the directory existing, not its contents.
• testRootAwareSnapshotPathIsTheWritersAtTheRealRoot — the root-aware path and LibFs's are one path wherever both can spell it.

Suite

	tests	passed	failed
branch point 86f8d96	215	168	47
this branch 9f5327e	220	173	47

The 47 are identical on both sides and every one is vm.createSelectFork: environment variable *_RPC_URL not found — 38 in LibRainDeployTest, 7 in RainDeployVerifyChainTest, 2 in RainDeployVerifyChainCandidateTest. They are absent fork endpoints in the local environment, not results. Zero non-environmental failures on either side, and the 5 tests this branch adds all pass.

Mutation ledger

Nine mutants, one per behaviour the diff adds or changes. Run twice through independent harnesses — a per-mutant driver over the whole suite, and the org's mutation-probe over a suite narrowed to exclude the three fork contracts (their env failures make a baseline red, and the probe refuses to run on one). Both agree: 9 killed, 0 survived, 0 no-run, 0 harness errors.

#	mutation	verdict	killed by
m1	dirForSnapshot(root, dir) ignores the root it was handed	KILLED	testSnapshotPathsAgreeWithTheWriter, and all five freeze tests
m2	pathForSnapshot(root, …) drops the .sol extension	KILLED	testRootAwareSnapshotPathIsTheWritersAtTheRealRoot, testSnapshotPathsAgreeWithTheWriter, testFreezeLeavesNothingBehindWhenThereIsNothingToFreeze
m3	pathForSnapshot(root, …) ignores the root, so reader and writer drift	KILLED	testSnapshotPathsAgreeWithTheWriter, testFreezeCopiesTheRegeneratedRollingSnapshot, testFreezeCutsEveryNamedContract, testFreezeRefusesARecutRelease
m4	the SnapshotAlreadyFrozen guard is deleted outright	KILLED	testFreezeRefusesARecutRelease, testFreezeRefusesATagDirectoryThatIsEmpty
m5	regenerate() runs AFTER the reads, freezing a stale candidate	KILLED	testFreezeCopiesTheRegeneratedRollingSnapshot
m6	every frozen file gets the FIRST contract's record	KILLED	testFreezeCutsEveryNamedContract
m7	the read loop stops after the first contract	KILLED	testFreezeCutsEveryNamedContract
m8	the write loop stops after the first contract	KILLED	testFreezeCutsEveryNamedContract
m9	the cut is written back into the candidate, leaving the tag empty	KILLED	testFreezeCopiesTheRegeneratedRollingSnapshot, testFreezeCutsEveryNamedContract, testFreezeRefusesARecutRelease

m4 and m5 are the two the issue was filed about. m4 — the append-only guard — had no test at all before this branch and survived the entire suite. m5 is the ordering: with noRegeneration as the only regeneration any test passed, a freeze that read before it regenerated passed every existing test.

Evidence each suite actually ran

A killed mutant and a mutant that never compiled both make forge test exit non-zero, and this repo's suite is red at baseline from the missing RPC endpoints, so neither exit code nor "it went red" is evidence. Per mutant, LibRainDeploySnapshotTest ran all 25 of its tests (25 pass / 0 fail at baseline) and the compile logged Compiler run successful:

#	LibRainDeploySnapshotTest	whole suite
m1	25 ran — 18 passed, 7 failed	166 passed, 54 failed
m2	25 ran — 22 passed, 3 failed	170 passed, 50 failed
m3	25 ran — 21 passed, 4 failed	169 passed, 51 failed
m4	25 ran — 23 passed, 2 failed	171 passed, 49 failed
m5	25 ran — 24 passed, 1 failed	172 passed, 48 failed
m6	25 ran — 24 passed, 1 failed	172 passed, 48 failed
m7	25 ran — 24 passed, 1 failed	172 passed, 48 failed
m8	25 ran — 24 passed, 1 failed	172 passed, 48 failed
m9	25 ran — 22 passed, 3 failed	170 passed, 50 failed

Every whole-suite figure is 47 environmental + N real, and every N is accounted for by the named tests above.

Two harness traps were hit and fixed rather than reported through:

• Fixture residue faking kills. A mutant that breaks the freeze leaves its fixture record on disk, because the tests only remove fixtures once they get far enough to do so. A leftover test/generated-recut/<tag>/ makes the NEXT mutant revert SnapshotAlreadyFrozen for a reason that has nothing to do with that mutant. Clearing residue is part of the suite command, before each run.
• A mutant that ignores the record root writes into the REAL record, both an untracked cut and untracked rolling files beside the two real ones — so cleanup restores src/generated as well.

QA

• Discriminating tests: testFreezeCopiesTheRegeneratedRollingSnapshot, testFreezeCutsEveryNamedContract, testFreezeRefusesARecutRelease, testFreezeRefusesATagDirectoryThatIsEmpty, testRootAwareSnapshotPathIsTheWritersAtTheRealRoot — none can run against base at all: on 86f8d96 freeze takes no record root, so a success-path test could only cut into the real src/generated/, which testEveryFrozenSnapshotIsReleased fails on from contracts forge runs in parallel. That untestability IS finding cov-02, so "fails on base" is verified the only way it can be — by restoring each base behaviour as a mutation and confirming the test fails: m4 restores base's absent append-only guard (base had no test for it; it survived the whole suite), and m5 restores the read-before-regenerate ordering that base's noRegeneration-only tests could not observe. Both are killed below.
• Mutations applied: 9/9 killed, 0 survived, 0 no-run, 0 harness errors, cross-checked through two independent harnesses.
  • dirForSnapshot string.concat(root, …) -> string.concat(LIB_FS_ROOT, …) -> testSnapshotPathsAgreeWithTheWriter + all five freeze tests
  • pathForSnapshot drop ".sol" -> testRootAwareSnapshotPathIsTheWritersAtTheRealRoot, testSnapshotPathsAgreeWithTheWriter
  • pathForSnapshot dirForSnapshot(root, dir) -> dirForSnapshot(LIB_FS_ROOT, dir) -> testSnapshotPathsAgreeWithTheWriter, testFreezeCopiesTheRegeneratedRollingSnapshot, testFreezeCutsEveryNamedContract, testFreezeRefusesARecutRelease
  • freeze delete if (vm.exists(frozenDir)) revert SnapshotAlreadyFrozen(...) -> testFreezeRefusesARecutRelease, testFreezeRefusesATagDirectoryThatIsEmpty
  • freeze move regenerate(); below the read loop -> testFreezeCopiesTheRegeneratedRollingSnapshot
  • freeze write records[0] for every i -> testFreezeCutsEveryNamedContract
  • freeze read loop i < contractNames.length -> i < 1 -> testFreezeCutsEveryNamedContract
  • freeze write loop i < contractNames.length -> i < 1 -> testFreezeCutsEveryNamedContract
  • freeze write to pathForSnapshot(root, tag, …) -> pathForSnapshot(root, CANDIDATE, …) -> testFreezeCopiesTheRegeneratedRollingSnapshot, testFreezeCutsEveryNamedContract, testFreezeRefusesARecutRelease
• Oracle: the properties are stated in the issue and in the library's own NatSpec independently of the code — the regeneration runs FIRST, a release is cut ONCE, a snapshot path has ONE spelling — and expected values are never read back from the code under test. Each frozen file is compared against the fixture bytes the test itself wrote (rollingFor(contractName), distinct per contract), and the freshness assertion compares against freshRolling() while asserting assertNotEq against staleRolling(), so a freeze that copied the wrong source cannot satisfy it. testRootAwareSnapshotPathIsTheWritersAtTheRealRoot's oracle is the independent LibFs writer, fuzzed rather than pinned to a chosen name.
• Category check: the issue asks for two findings — cov-02 (freeze's write path: the regeneration ordering, the copied bytes, the cut being a release the record walk finds, and a multi-contract release) and cov-03 (the SnapshotAlreadyFrozen append-only guard, including the empty-<tag>/ case). Covered: ordering testFreezeCopiesTheRegeneratedRollingSnapshot; multi-contract testFreezeCutsEveryNamedContract; re-cut refusal and the original record left intact testFreezeRefusesARecutRelease; empty tag directory testFreezeRefusesATagDirectoryThatIsEmpty. The issue's examples are not treated as exhaustive: the seam they both need is covered as a property in its own right by testRootAwareSnapshotPathIsTheWritersAtTheRealRoot, and the read/write loop truncations (m7, m8) are covered though the issue names neither.

Checks run locally

forge fmt --check clean; pre-commit run --all-files all green (deadnix, denofmt, nil, nixfmt, prettier-rainix, statix, taplo, yamlfmt).

Summary by CodeRabbit

• Bug Fixes

  • Improved release snapshot handling to consistently use the specified record location.
  • Prevented invalid release cuts, including recuts, missing tag directories, and incorrect snapshot ordering.

• Enhancements

  • Added support for generating and freezing snapshots at alternate record locations.
  • Improved handling of refreshed rolling snapshots and releases containing multiple contracts.

• Tests

  • Expanded coverage for custom snapshot locations, regeneration behavior, release validation, and multi-contract freezes.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: fc3af476-506a-4e2b-8675-1e55c8f01f7d

📥 Commits

Reviewing files that changed from the base of the PR and between 1a6fd85 and 026ad15.

📒 Files selected for processing (3)

• script/Build.sol
• src/lib/LibRainDeploySnapshot.sol
• test/src/lib/LibRainDeploySnapshot.t.sol

Included review availability: Your plan includes up to 1 review per rolling hour; 0 remain after this review.

---

Walkthrough

LibRainDeploySnapshot now supports explicit record roots for path construction and release freezing. cutRelease() passes the default root. Tests cover regeneration, multi-contract freezes, recut protection, empty tag directories, and release-order validation.

Changes

Snapshot freeze flow

Layer / File(s)	Summary
Root-aware snapshot paths src/lib/LibRainDeploySnapshot.sol, test/src/lib/LibRainDeploySnapshot.t.sol	Path helpers accept explicit roots and retain default-root overloads. Tests verify equivalent default and explicit paths.
Explicit-root freeze integration src/lib/LibRainDeploySnapshot.sol, script/Build.sol, test/src/lib/LibRainDeploySnapshot.t.sol	freeze uses the supplied root for validation, candidate reads, and frozen writes. cutRelease() supplies LIB_FS_ROOT.
Freeze behavior validation test/src/lib/LibRainDeploySnapshot.t.sol	Tests cover regeneration ordering, multi-contract copying, recut rejection, empty tag directories, and release-order validation.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: ⚪ Minimal · up to 026ad

This change adds root-aware snapshot freezing and append-only protection with focused coverage; no actionable merge-blocking risk remains after normal checks and review.

Possibly related issues

• rainlanguage/rain.deploy issue 81: The explicit record-root handling addresses root mismatches during snapshot validation and record walks.

Possibly related PRs

• rainlanguage/rain.deploy#26: Both changes update LibRainDeploySnapshot.freeze and its callers to use an explicit snapshot root.

Sequence Diagram(s)

sequenceDiagram
  participant cutRelease
  participant LibRainDeploySnapshot
  participant regenerate
  participant RecordRoot
  cutRelease->>LibRainDeploySnapshot: Call freeze with LIB_FS_ROOT
  LibRainDeploySnapshot->>regenerate: Regenerate candidate snapshots
  LibRainDeploySnapshot->>RecordRoot: Read candidates and validate release order
  LibRainDeploySnapshot->>RecordRoot: Write frozen contract snapshots

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the freeze write-path and append-only guard changes covered by the pull request.
Linked Issues check	✅ Passed	The changes implement the root-aware freeze seam and add coverage for regeneration, copying, contract discovery, recut rejection, and snapshot preservation required by issue #46.
Out of Scope Changes check	✅ Passed	All production, library, and test changes support the root-aware freeze behavior and append-only release requirements.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 2026-08-15-issue-46-freeze-tests

---

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

[thedavidmeister]

Reviewed 026ad15: ready — Closes #46.

Drives freeze's write path and its append-only guard. 256 tests pass on the merge commit and forge fmt --check is clean.

Two conflicts with main had to be resolved by hand, and both are the shape where a clean auto-merge produces broken code:

#96's guard read the wrong record. It added checkReleaseFollowsRecord(vm, LIB_FS_ROOT, tag) inside freeze while freeze had no root parameter; this branch gives freeze a root. Git merged both happily and left the guard reading the real record while the append landed in the caller's tree. Fixed to read root, with testFreezeChecksTheRecordItIsAppendingTo added — and proven by mutation rather than argued: reverting the argument to LIB_FS_ROOT fails only that new test, and survived every pre-existing one.

#113 deleted the helper this branch calls. It moved the shared test helpers into test/lib/LibStringSet.sol and removed the local holdsPath definitions; this branch added a new call to holdsPath while that was in flight. One side deletes a definition, the other adds a call, neither touches the other's lines — so the merge was clean and the tree did not compile. Both branches were green on their own CI. Routed through LibStringSet.holds, which is where the other membership assertions in that file already point.

#114's invariant survives: exactly one occurrence of the literal "src/generated" in LibRainDeploySnapshot.sol, at the LIB_FS_ROOT definition.

All three rainix jobs green — including static, which this PR could not pass before #130 trimmed CLAUDE.md under the 4096-byte cap. CodeRabbit actually reviewed this one — Review completed rather than the rate-limit banner most of today's PRs carried — with 0 unresolved threads, so that zero is coverage.