feat(OMN-14438): clean-ref deploy source + vendored-SHA assertion (RT-1/RT-2)

[jonahgabriel]

OMN-14438 — RT-1/RT-2: clean-ref deploy source + vendored-SHA assertion

Closes OMN-14438 (Train 1 / WS-RT, mechanical-release-trains plan §3).

Problem (instance #3, verified in the plan)

stage_workspace.sh rsyncs each sibling from the ambient ${OMNI_HOME}/<repo> working copy on .201 — routinely detached, behind, and dirty — so merging a PR never changes what gets built and every "deployed" claim is unfalsifiable. A vendored-SHA manifest (sibling-vcs-provenance.json) is emitted but nobody asserts it equals the intended ref, so a behind/dirty clone silently leaks a stale SHA into the image (taxonomy Class 6 — the unreliable-narrator tree).

Fix

• scripts/runtime_build/deploy_source_ref.py (new, stdlib-only):
  • checkout — before staging, brings each sibling clone to a clean checkout of a named ref (git fetch --prune + checkout + reset --hard + clean -ffdx) and writes an expected-refs manifest. Fails closed (exit 3) if the ref is unresolvable or the checkout does not land at the ref / leaves a dirty tree.
  • assert — HARD-ASSERTS the vendored-SHA manifest equals that ref for every sibling. Fails closed (exit 4) on a stale/wrong SHA or an unlabelled dirty tree.
• scripts/runtime_build/stage_workspace.sh — runs checkout before the pin preflight/staging (when DEPLOY_REF set / DEPLOY_HOTPATCH=1) and assert after the VCS-provenance manifest is written. Unset DEPLOY_REF ⇒ legacy ambient build, loudly stamped unpinned + unasserted (incremental rollout; cut-lab-ref always engages RT-1).
• scripts/runtime_build/cut-lab-ref.sh (RT-2, new) — one-command lab deploy wrapper: --ref <branch|tag|sha>, --hotpatch, --cut-tag (cuts lab/<lane>/<utc>-<shortsha>), dev + stability-test lanes; prod refused (Train 2, grant-gated). --hotpatch deploys a dirty tree deliberately, LABELLED (hotpatch:true + dirty:true), never laundered.

Seams (field-by-field)

• expected-refs manifest workspace/deploy-source-refs.json: { ref_pinned: bool, repos: { <repo>: { path, ref, expected_sha (40-hex), head_sha, dirty: bool, hotpatch: bool } } } — written by checkout, read by assert.
• vendored VCS provenance workspace/sibling-vcs-provenance.json (existing, unchanged shape): { siblings: { <repo>: { vcs_ref (40-hex), vcs_dirty: bool, vcs_branch } } }. The assertion joins siblings[repo].vcs_ref == repos[repo].expected_sha and siblings[repo].vcs_dirty ⇒ repos[repo].hotpatch.
• env seam consumed by stage_workspace.sh: DEPLOY_REF (str, uniform ref), DEPLOY_HOTPATCH (0/1). cut-lab-ref.sh exports these + BUILD_SOURCE=workspace + OMNIBASE_INFRA_COMPOSE_PROJECT into deploy-runtime.sh (which propagates the exported env to the stage_workspace.sh subshell). Cross-boundary coverage: tests/scripts/test_stage_workspace_deploy_ref.py drives the real stage_workspace.sh → deploy_source_ref.py seam end-to-end.
• exit-code seam: stage_workspace.sh maps every RT-1 failure (checkout or assert) to exit 4.

dod_evidence

proof_class: code-only (build/CI green + real-git-tree tests; runtime readback is RT-4/RT-6, separate tickets).

• RED against EXISTS-but-WRONG (load-bearing, not green-on-absence):
  • test_assert_red_on_exists_but_wrong_stale_sha — a real sibling clone that EXISTS and is a valid git tree but is BEHIND the intended ref (HEAD at an older commit); its actual HEAD SHA (read via git rev-parse, not a hand-typed fake) is fed to the assertion → DeploySourceRefError(exit 4), and the stale SHA is named in the failure.
  • test_stage_assert_command_goes_red_on_poisoned_provenance — the exact command stage_workspace.sh runs (deploy_source_ref.py assert) is invoked on real staged artifacts with the vendored SHA poisoned to the real behind commit → exit 4.
  • test_unresolvable_deploy_ref_fails_build_closed — stage_workspace.sh exits 4 and writes no provenance manifest.
  • test_assert_red_on_unlabelled_dirty_tree — vendored SHA matches ref but tree is dirty and not a hot-patch → exit 4.
• GREEN = manifest SHA == ref for every sibling:
  • test_clean_checkout_converts_wrong_tree_then_asserts_green — real clean_checkout converts the behind+dirty clone to the intended ref (untracked file removed), then assertion passes.
  • test_deploy_ref_checks_out_behind_clone_and_asserts_green (e2e) — starting from a BEHIND clone, stage_workspace.sh with DEPLOY_REF=dev vendors the NEW ref SHA (a no-op would have vendored the stale SHA), in-script assertion passes.
• --hotpatch labels dirty: test_hotpatch_labels_dirty_and_passes — the patch is NOT laundered away, the manifest carries hotpatch:true + dirty:true, and the labelled dirty tree passes the assertion.
• Suite: 16 new tests pass; full tests/scripts/ (287) green; ruff + mypy + shellcheck + pre-commit run clean.

Not in scope (owed, separate tickets)

RT-3 (trigger fail-closed), RT-4/RT-6 (deploy readback), the bus-trigger wiring. This PR is the deploy-source root fix only.

OCC companion: required for the omnibase_infra dev receipt-gate; per feedback_no_self_authored_evidence it is authored by the independent verifier, not this implementer.

Evidence-Source: OCC#4046
Evidence-Commit: ffa6f1cc00bfb1aa989b3aba858f5f04c4dac084
Evidence-Ticket: OMN-14438

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 56 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 54267cff-9f04-4771-a8ad-9ab0beb73635

📥 Commits

Reviewing files that changed from the base of the PR and between e811995 and 90ba233.

📒 Files selected for processing (6)

• scripts/runtime_build/cut-lab-ref.sh
• scripts/runtime_build/deploy_source_ref.py
• scripts/runtime_build/stage_workspace.sh
• tests/scripts/test_cut_lab_ref.py
• tests/scripts/test_deploy_source_ref.py
• tests/scripts/test_stage_workspace_deploy_ref.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch jonah/omn-14438-deploy-source-clean-ref

---

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