feat(remediation): bind immutable desired changes

[gnanirahulnutakki]

Summary

• add immutable opaque desired-change/v1 bound to one exact validated GitSourceSnapshot
• preserve one lowercase canonical transformer/version identity, exact bounded proposed UTF-8 bytes, and unique attached evidence
• reject forged snapshots, malformed transformer versions, no-op/invalid/oversized output, ambiguous evidence, alias mutation, and exported construction
• document the approved snapshot-plus-change decomposition and its security/cost boundary

Authority boundary

Construction is package-private until a concrete deterministic transformer or declarative renderer receives separate review. This PR adds no R2/R4 transformation policy, Brain/resolver/runtime wiring, PR metadata, handler binding, actor, intent, PEP call, approval, credential, network, persistence, dispatch, mutation, or execution. R2 and R4 remain advisory-only.

Verification

• GitHub-verified SSH-signed commit with DCO and GSTACK checkpoint
• focused race suite plus 50 consecutive DesiredChange repetitions
• 50,000 dedicated constructor fuzz executions
• full make ci: zero lint issues, no Go vulnerabilities, 94.8% remediation coverage
• PostgreSQL 18.4 forced-RLS integration plus both 50,000-case isolation fuzzers
• dual reproducible four-platform release builds, SPDX SBOMs, Homebrew formula, amd64/arm64 OCI
• disposable Kubernetes 1.36.1 two-cluster Kind gate in 295.351s; clean teardown
• independent CodeRabbit full-diff pass: zero findings after incorporating three review improvements
• README reviewed and updated

Closes #307

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f6033ec7-31ac-4ad7-8d72-335f6cfe24be

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch gnanirahulnutakki/desired-change-20260722

---

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

[gnanirahulnutakki]

Exact-head local verification for 5d229eda104d774388fa5883a04294aa582edf8e:

• Signed commit and GitHub verification: valid; DCO and GSTACK checkpoint present.
• make ci: passed with zero lint findings, no reachable Go vulnerabilities, and 94.8% remediation-package coverage.
• make e2e-isolation: passed against PostgreSQL 18.4 with forced RLS; both tenant fuzzers completed 50,000 executions.
• Dedicated DesiredChange fuzzing: 50,000 executions; repeated race coverage: 50 passes.
• make release-check: passed two reproducible four-platform builds, SPDX SBOM, Homebrew formula, and amd64/arm64 OCI checks.
• make e2e-kind: passed the Kubernetes 1.36.1 two-cluster gate in 295.351 seconds; cleanup confirmed no retained Kind cluster or isolated release builder.
• Final full six-file CodeRabbit CLI pass: zero findings after correcting three earlier findings. The hosted bot correctly skipped its automatic review because the target is the non-default dev branch.
• Worktree is clean; README and E2/E14 specification were checked and updated.

Scope remains deliberately narrow: immutable GitSourceSnapshot + DesiredChange contracts only. R2/R4 remain advisory-only; no transformer, renderer, resolver/runtime wiring, PEP/auth, credential, persistence, mutation, dispatch, or execution path is introduced. The external self-managed cluster was not needed and was not touched.

[gnanirahulnutakki]

Final exact committed-diff review completed after the included-review allowance reset: CodeRabbit reviewed all six changed files at 5d229eda104d774388fa5883a04294aa582edf8e and returned zero findings.