feat(remediation): define immutable Git source snapshot

[gnanirahulnutakki]

Summary

• add the immutable observed-only git-source-snapshot/v1 contract approved on E14
• bind one workspace and affected resource to one canonical GitHub source/repository, configured non-symbolic base ref, exact resolved commit, one safe path, exact current bytes, and a matching Git blob identity
• copy and canonically order attached evidence, bound validity to five minutes, and classify future/fresh/stale observations against trusted time
• lock the public/private shape and keep I/O, policy, persistence, Brain, connector-runtime, authority, mutation, and execution imports absent

Approved separation

This PR implements GitSourceSnapshot first. DesiredChange is deliberately absent and remains a later separately reviewed transformer/renderer. The snapshot is not wired into the existing resolver, Brain, PEP, connector runtime, or Hub. R2 and R4 remain advisory-only.

Owner decision: #46 (comment)

Consistency and failure boundaries

• recompute the exact Git blob identity over blob <byte-count>\0<current-content>
• require commit and blob identities to use the same 40-hex SHA-1 or 64-hex SHA-256 object format
• reject symbolic/full/option-shaped/object-shaped/malformed refs, unsafe paths, invalid or oversized content, invalid validity windows, ambiguous source identity, missing/duplicate/unattached evidence, and forged snapshots
• preserve exact empty, LF, CRLF, Unicode, whitespace, and tab bytes without normalization
• keep all validated snapshot fields private and expose only Version and pure Freshness

Proof

• focused remediation race tests and 50 repeated snapshot runs
• snapshot fuzz: 50,000 executions
• full make ci: format, vet, zero-issue lint, current govulncheck, every race test, tooling policies, nine Prometheus rules, performance, binary E2E, build
• make e2e-isolation: PostgreSQL 18.4 plus two 50,000-execution tenant fuzzers
• make release-check: dual reproducible four-platform builds, SPDX SBOMs, formula, amd64/arm64 OCI
• pinned Kubernetes 1.36.1 two-cluster Kind gate in 242.424s
• final teardown: no Kind clusters or isolated release builder
• independent CodeRabbit final pass: zero findings across all six changed files
• GitHub-verified SSH-signed DCO/GSTACK commit: 142ddd180c63a2a847f0db06dd4c35c1dd1bcc71

Independent finding

A repeated isolation run exposed a pre-existing approval-expiry test fixture clock race. Production remains PostgreSQL-clock authoritative; the test-only repair is isolated in #304 and is not mixed into this snapshot PR.

Security and cost

This contract is pure and offline. It contains no desired bytes, PR metadata, handler binding, actor, intent, policy decision, approval, credential, endpoint, persistence, dispatch, mutation, or execution state. It adds no API request, egress, storage, cloud resource, telemetry cardinality, or recurring cost.

A later live adapter separately owns least-privilege contents-read credentials, GitHub rate limits, egress, and remote freshness.

Closes #303

Does not close #46 or F14.6.

[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: 1f07f574-7f09-41b6-bdb1-ea327abcfda7

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/git-source-snapshot-20260722

---

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

[gnanirahulnutakki]

Independent local CodeRabbit review completed against exact head 9f39758c75ce561dfdbcd5107a4fcd2f24b49b90.

• First pass: 0 critical, 0 warning, 2 minor suggestions.
• Accepted: corrected the mutation-isolation test to inspect the canonical subject-evidence slot; full make ci passed afterward.
• Declined: allowing NUL bytes, because P1 F14.6c1: define immutable observed Git source snapshot #303 explicitly defines a bounded textual non-NUL UTF-8 snapshot and arbitrary binary Git blobs are outside this slice.
• Second full pass: 0 findings across all six changed files.

R2/R4 remain advisory-only; this PR introduces no DesiredChange, policy/execution authority, I/O, persistence, mutation, or runtime wiring.