fix(migration): harden governed handoff runtime integrity

[seonghobae]

Buyer-visible scope

This Orgmetra-only migration-adapter repair prevents caller-controlled runtime subclasses from forging governed handoff evidence before an HRIS migration is executed. It owns only Orgmetra's value-free pre-write governance envelope; it does not copy MHTML ETL Gateway or mightyETL runtime behavior, mutate either repository, or introduce cross-service application-table SQL.

RED → causal repair retained

• RED 8d794f1394f99bee4086da59a208bb46a6cad9b1 added adversarial regressions for forged governance text, dependency revisions, target-object allow-list membership, numeric bounds, and fixed envelope state.
• 54bcef13194e7f9bbe38c9d7a916fd0825f0ae4f requires exact built-in trust primitives before reviewed equality, membership, bounds, UUID parsing, regex validation, or canonical evidence serialization.
• 1d7ed5bbfb18b35d589c69a6e8d93754ba299589 narrows UUID parsing failure handling to the actual ValueError contract.

Protected-parent adoption and dependency authority

Protected-parent adoption snapshot is develop@eb9757f8649aaad026a9865508d9aad50c1a7a4f. GitHub's synthetic merge df043ec75c783beb7bfe98b323bec1018228fa05 was inspected before adoption; its exact workflow inventory contained only canonical foundation-ci.yml and recovery-rehearsal-quality.yml. The branch advanced without force to two-parent successor d636ac4abb4b61a8f3ab9f217a9b843eb1562ece.

A follow-up release/traceability sweep found a separate dependency-authority defect. MHTML ETL Gateway revision 779254927abb1e7cee80fd949907ccd03f9fc7be is bound to immutable release v0.4.0. The reviewed mightyETL revision ba8911f50ed20a39927a0d51c0cf20f9b7c91820 still has no published owner release. Orgmetra may retain it as reviewed proposal evidence while Draft but must not describe it as a published production dependency or complete release acceptance against it. Issue #256 owns the owner-release → consumer version/provenance binding sequence, with ContextualWisdomLab/mightyETL#165 as canonical release/provenance owner.

Ordinary successor 883c4bc9dc62b712de5f2a355251d405d2810957 repairs only that authority/traceability surface. Runtime validation, record bounds, target allow-list, envelope schema and migration semantics are unchanged.

Current exact-head acceptance — 2026-09-06

GitHub records exact 883c4bc9dc62b712de5f2a355251d405d2810957 with base develop@eb9757f...; the PR remains open · Draft · mechanically mergeable.

• Foundation 34018193669: terminal SUCCESS.
• SAST 34018193647: terminal SUCCESS.
• Security 34018193696: terminal SUCCESS.
• CodeQL 34018193653: terminal FAILURE only after both Python and Actions compatibility shards successfully request current-head dispatch and then fail Release runner or enforce current-head CodeQL verdict. This wrapper failure does not establish an Orgmetra source/SARIF defect.

The current Orgmetra source/security acceptance is therefore materially stronger than the previous queued snapshot, but merge/release remains blocked by the central CodeQL verdict handoff, qualifying independent approval, and #256's immutable mightyETL owner-release binding. Fresh mightyETL release inventory on 2026-09-06 is still empty, and mightyETL #165 remains planned with licensing/source-identity/non-vacuous-coverage/security/protected-head prerequisites.

Do not self-approve, use routine administrator bypass, synthesize missing verdicts, promote a bare foreign commit to released-contract status, no-op retrigger, force-push/destructively rebase, or Close the valid migration-integrity delta.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: bc85d6ee-4c7f-4542-8598-4246be99f203

📥 Commits

Reviewing files that changed from the base of the PR and between 299d671 and 1d7ed5b.

📒 Files selected for processing (1)

• packages/migration-adapter/src/orgmetra_migration_adapter/handoff.py

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

---

📝 Walkthrough

Walkthrough

마이그레이션 핸드오프가 정확한 내장 타입을 요구하도록 변경되었습니다. 사용자 정의 서브클래스의 위조 동작을 거부하는 회귀 테스트와 검증 기준 문서가 추가되었습니다.

Changes

런타임 증거 무결성

Layer / File(s)	Summary
검증 기준과 추적성 문서 docs/doctoring/migration-handoff-references.md, docs/traceability/migration-handoff.md	보호된 develop 기준, Python 데이터 모델 의미론, 정확한 내장 타입 검증, 외부 계약 불변 범위를 기록했습니다.
정확한 내장 타입 검증 packages/migration-adapter/src/orgmetra_migration_adapter/handoff.py, packages/migration-adapter/README.md	핸드오프의 문자열, 양의 정수, 대상 코드 및 컬렉션 검증을 정확한 내장 타입 검사로 변경했습니다. README에 fail-closed 동작을 설명했습니다.
서브클래스 위조 회귀 검증 packages/migration-adapter/tests/test_runtime_evidence_integrity.py	사용자 정의 문자열 및 정수 서브클래스가 동등성, 해시, 비교 연산으로 검증을 우회하는 경우를 ContractViolation으로 거부하는 테스트를 추가했습니다.

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

Merge Risk: ⚪ Minimal · up to 1d7ed

This change hardens migration handoff runtime validation without introducing a supported merge-readiness concern; no actionable merge-blocking risk remains beyond normal checks and review.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 22 functions across 2 files.
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	제목은 마이그레이션 핸드오프의 런타임 무결성 강화를 정확하고 간결하게 설명하며, 변경 범위와 주요 목적을 반영합니다.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/migration-handoff-runtime-integrity

---

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

[seonghobae]

@opencode-agent Please review the current unchanged head against protected develop. Local exact-head verification: all owned package suites pass at 100% statement/branch coverage.

[devin-ai-integration]

Devin Review found 1 new potential issue.