fix(migration): harden governed handoff runtime integrity

docs/doctoring/migration-handoff-references.md

@@ -2,18 +2,19 @@
 
 ## Status
 
-Active-PR evidence only. Protected `develop` does not ship this migration handoff until the owning PR integrates.
+Protected `develop` ships the governed migration-handoff boundary. PR #71 records an Orgmetra-local runtime-integrity hardening of that boundary. Foreign owner code remains read-only: MHTML ETL Gateway is bound to an immutable published release, while the reviewed mightyETL snapshot is not yet a released production dependency and remains an explicit acceptance prerequisite in Orgmetra #256.
 
 ## Exact dependency contracts
 
-- ContextualWisdomLab. (2026). *MHTML ETL Gateway API contract* [Source code]. `ContextualWisdomLab/mhtml-etl-gateway`, revision `779254927abb1e7cee80fd949907ccd03f9fc7be`. GitHub. https://github.com/ContextualWisdomLab/mhtml-etl-gateway/commit/779254927abb1e7cee80fd949907ccd03f9fc7be. The reviewed `0.4.0` API exposes source SHA-256 identity and value-free schema/handoff contracts without database writes, network transport, authentication, or raw source values.
-- ContextualWisdomLab. (2026). *MHTML ETL Gateway value-free schema proposal contract* [Source code]. `ContextualWisdomLab/mhtml-etl-gateway`, revision `779254927abb1e7cee80fd949907ccd03f9fc7be`. GitHub. https://github.com/ContextualWisdomLab/mhtml-etl-gateway/commit/779254927abb1e7cee80fd949907ccd03f9fc7be. The reviewed proposal contract exposes `schema_proposal_id`, `source_hash_sha256`, and `table_fingerprint_sha256` while excluding raw headers and values.
-- ContextualWisdomLab. (2026). *mightyETL bounded atomic batch contract* [Source code]. `ContextualWisdomLab/mightyETL`, revision `ba8911f50ed20a39927a0d51c0cf20f9b7c91820`. GitHub. https://github.com/ContextualWisdomLab/mightyETL/commit/ba8911f50ed20a39927a0d51c0cf20f9b7c91820. The reviewed contract prevalidates one bounded request before database writes and executes accepted writes inside one transaction; Orgmetra does not copy or extend its runtime semantics in this slice.
+- ContextualWisdomLab. (2026). *MHTML ETL Gateway v0.4.0* [Software release]. `ContextualWisdomLab/mhtml-etl-gateway`, immutable release `v0.4.0`, target revision `779254927abb1e7cee80fd949907ccd03f9fc7be`. GitHub. https://github.com/ContextualWisdomLab/mhtml-etl-gateway/releases/tag/v0.4.0. The released API exposes source SHA-256 identity and value-free schema/handoff contracts without database writes, network transport, authentication, or raw source values.
+- ContextualWisdomLab. (2026). *MHTML ETL Gateway value-free schema proposal contract* [Source code in immutable release]. `ContextualWisdomLab/mhtml-etl-gateway`, release `v0.4.0`, target revision `779254927abb1e7cee80fd949907ccd03f9fc7be`. GitHub. https://github.com/ContextualWisdomLab/mhtml-etl-gateway/commit/779254927abb1e7cee80fd949907ccd03f9fc7be. The released proposal contract exposes `schema_proposal_id`, `source_hash_sha256`, and `table_fingerprint_sha256` while excluding raw headers and values.
+- ContextualWisdomLab. (2026). *mightyETL bounded atomic batch contract* [Unreleased source snapshot]. `ContextualWisdomLab/mightyETL`, reviewed revision `ba8911f50ed20a39927a0d51c0cf20f9b7c91820`. GitHub. https://github.com/ContextualWisdomLab/mightyETL/commit/ba8911f50ed20a39927a0d51c0cf20f9b7c91820. The reviewed snapshot prevalidates one bounded request before database writes and executes accepted writes inside one transaction. It is design/proposal evidence only until the canonical owner publishes an immutable release binding that contract; Orgmetra #256 tracks that prerequisite.
 
-## Authoritative standards
+## Authoritative standards and language semantics
 
+- Python Software Foundation. (2026). *Data model — Python 3.14 documentation*. Python documentation. https://docs.python.org/3.14/reference/datamodel.html. Python's data model defines rich comparison special methods such as `__eq__`, `__ne__`, `__le__`, and `__gt__`, and defines `__hash__` as the hook used by hashed collections including sets and dictionaries. Because user-defined subclasses can provide these methods, caller-controlled subclasses must not be allowed to determine reviewed equality, membership, or bounds at an immutable governance-evidence boundary.
 - World Wide Web Consortium. (2013, April 30). *PROV-DM: The PROV data model* (W3C Recommendation). https://www.w3.org/TR/2013/REC-prov-dm-20130430/
 - National Institute of Standards and Technology. (2020). *Security and privacy controls for information systems and organizations* (NIST Special Publication 800-53, Revision 5). https://doi.org/10.6028/NIST.SP.800-53r5
 - National Institute of Standards and Technology. (2025, August 27). *NIST releases revision to SP 800-53 security and privacy controls* (Release 5.2.0 notice). https://csrc.nist.gov/news/2025/nist-releases-revision-to-sp-800-53-controls
 
-NIST's official CSRC publication page and release notice identify Release 5.2.0 as the finalized August 27, 2025 update. Orgmetra uses the public information-integrity and provenance principles as design traceability only and does not claim NIST, ISO, SOC 2, or other certification from this package.
+NIST's official CSRC publication page and release notice identify Release 5.2.0 as the finalized August 27, 2025 update. Orgmetra uses the public information-integrity and provenance principles as design traceability only and does not claim NIST, ISO, SOC 2, or other certification from this package. The Python language reference is used narrowly to justify exact built-in primitive requirements at the Orgmetra trust boundary. None of these references elevates the unreleased mightyETL source snapshot into a published dependency contract.

docs/traceability/migration-handoff.md

@@ -2,20 +2,23 @@
 
 ## Status
 
-Active-PR only. This evidence does not describe protected-`develop` product truth until the owning PR integrates.
+Protected-parent adoption snapshot `develop@eb9757f8649aaad026a9865508d9aad50c1a7a4f` contains the governed migration-handoff boundary and protected #161 repository-quality consolidation. PR #71 hardens only Orgmetra-owned runtime evidence integrity on top of that snapshot; it does not mutate MHTML ETL Gateway, mightyETL, or any other dedicated-writer dependency. The protected branch must be re-read before merge rather than treating this snapshot as perpetual current truth.
 
 | Requirement | Decision / owner contract | Production implementation | Executable evidence |
 |---|---|---|---|
-| Bind the immutable source without copying source values | MHTML ETL Gateway revision `779254927abb1e7cee80fd949907ccd03f9fc7be`; ADR 0012 | `MigrationHandoffInput.source_sha256`, `source_size_bytes`, value-free proposal identity/fingerprint | deterministic handoff and malformed-digest regressions |
-| Preserve accountable migration governance | ADR 0012 | tenant UUID, migration-batch reference, actor, approval, `hris_data_migration` purpose, reason, strict human confirmation | malformed context and non-boolean confirmation matrix |
-| Revalidate foreign contract drift rather than silently adapting | ADR 0012; exact owner revisions | `MHTML_ETL_GATEWAY_REVISION`, `MIGHTY_ETL_REVISION` | stale-revision regressions |
-| Keep the handoff bounded | mightyETL reviewed bounded-atomic-batch contract; ADR 0012 | `MAXIMUM_BATCH_RECORDS = 1000`; positive non-boolean record count | zero/bool/over-bound regressions |
-| Restrict import targets to authoritative HRIS core | Orgmetra core model; ADR 0001; ADR 0012 | allowlist for `person_record`, `employment_record`, `organization_unit`, `job_profile`, `position_record`, `assignment_record` | all-core-family success plus unsupported/duplicate target rejection |
+| Bind the immutable source without copying source values | MHTML ETL Gateway immutable release `v0.4.0`, target revision `779254927abb1e7cee80fd949907ccd03f9fc7be`; ADR 0012 | `MigrationHandoffInput.source_sha256`, `source_size_bytes`, value-free proposal identity/fingerprint | deterministic handoff and malformed-digest regressions |
+| Preserve accountable migration governance | ADR 0012 | tenant UUID, migration-batch reference, actor, approval, `hris_data_migration` purpose, reason, strict human confirmation | malformed context, non-boolean confirmation, and hostile runtime-subclass regressions |
+| Prevent runtime objects from forging reviewed evidence | Python data-model semantics; PR #71 | exact built-in `str`, `int`, and `tuple` primitives at trust-bearing validation/equality/hash/comparison boundaries | `test_runtime_evidence_integrity.py` purpose, dependency-revision, target allow-list, batch-bound, and envelope-mode adversarial regressions |
+| Revalidate foreign contract drift rather than silently adapting | ADR 0012; released MHTML identity plus reviewed mightyETL snapshot | `MHTML_ETL_GATEWAY_REVISION`; proposal-only `MIGHTY_ETL_REVISION`, each requiring exact built-in text before equality | stale-revision plus hostile revision-subclass regressions; release binding tracked by #256 |
+| Keep the handoff bounded | mightyETL bounded-atomic-batch design snapshot; ADR 0012 | `MAXIMUM_BATCH_RECORDS = 1000`; exact built-in positive integer record count | zero/bool/over-bound plus hostile integer-subclass regression; production dependency acceptance blocked by #256 |
+| Restrict import targets to authoritative HRIS core | Orgmetra core model; ADR 0001; ADR 0012 | exact built-in tuple and string elements followed by allow-list validation for `person_record`, `employment_record`, `organization_unit`, `job_profile`, `position_record`, `assignment_record` | all-core-family success plus unsupported/duplicate/hostile-subclass target rejection |
 | Prevent raw-value/credential shadow stores | MHTML value-free contract; ADR 0012 | package input/output has no raw header, source value, credential, connection or SQL field | serialized-envelope non-disclosure regression and public API review |
 | Make pre-write evidence reproducible | W3C PROV-DM design traceability; ADR 0012 | sorted target codes, canonical JSON, SHA-256 digest | reversed-order equivalence plus exact `hashlib.sha256(canonical_json)` assertion |
-| Keep requested execution semantics separate from observed outcomes | mightyETL owner contract; ADR 0012 | `execution_mode="bounded_atomic_batch"` records only the requested/contracted subsequent execution mode; it is not proof of writes, completion, or observed atomicity | direct-constructor canonical-mode rejection plus documentation contract |
-| Do not confuse handoff with migration completion | ADR 0012 | `requires_reconciliation=True` plus actionable `next_action` | direct-constructor bypass rejection and deterministic handoff regression |
+| Keep requested execution semantics separate from observed outcomes | reviewed mightyETL design snapshot; ADR 0012 | exact built-in `execution_mode="bounded_atomic_batch"` records only the requested subsequent execution mode; it is not proof of writes, completion, or observed atomicity | direct-constructor canonical-mode and hostile-subclass rejection plus documentation contract |
+| Do not confuse handoff with migration completion | ADR 0012 | `requires_reconciliation=True` plus exact built-in actionable `next_action` | direct-constructor bypass rejection and deterministic handoff regression |
 | Preserve dedicated-writer ownership | ADR 0002; ADR 0012 | no MHTML/mightyETL source mutation, no network call, no cross-service SQL | package dependency surface and code review |
-| Keep owned behavior fully covered | Orgmetra quality policy | exact-head migration quality workflow | 100% statement and branch coverage gate |
+| Keep owned behavior fully covered | Orgmetra quality policy | canonical Foundation CI runs the migration-adapter package contract | 100% statement and branch coverage gate |
 
-A consumer MUST obtain separate execution-outcome evidence from the configured owner boundary and reconcile it before asserting migration completion or atomic execution. The pre-write envelope alone is never completion evidence.
+A consumer MUST obtain separate execution-outcome evidence from the configured owner boundary and reconcile it before asserting migration completion or atomic execution. The pre-write envelope alone is never completion evidence. PR #71 changes only the local validation trust boundary: Python user-defined subclasses can override rich comparison and hashing behavior, so trust-bearing primitives are normalized by rejection to exact built-in runtime types before reviewed equality, membership, bounds, or canonical serialization are evaluated.
+
+The MHTML dependency is release-bound through immutable `v0.4.0`. The mightyETL revision remains reviewed design evidence only because the canonical owner has no published release at this point. Issue #256 is therefore a merge/release prerequisite: Orgmetra must bind the consumer contract to an immutable mightyETL owner release before claiming that execution boundary as a released production dependency.

packages/migration-adapter/README.md

@@ -4,6 +4,8 @@ This package creates **value-free, fail-closed migration handoff evidence** befo
 
 Use it when an operator has already inspected a source through the published MHTML ETL Gateway contract and has an approved mapping for one bounded Orgmetra HRIS batch. The package binds that evidence to an Orgmetra tenant, accountable actor, approval, purpose, mapping digest, source digest, target HRIS object families, and exact reviewed dependency revisions.
 
+Trust-bearing primitive fields are fail-closed runtime evidence. The adapter accepts exact built-in strings for identifiers, references, codes, digests, dependency revisions, and fixed envelope states; exact built-in integers for bounded counts and sizes; and an exact tuple of exact string target codes. Caller-defined subclasses are rejected before reviewed equality, hashed allow-list membership, numeric bounds, or canonical JSON serialization can run, so custom Python comparison/hash methods cannot make accepted governance differ from the immutable evidence that is recorded.
+
 It deliberately does **not**:
 
 - parse MHTML or copy the MHTML ETL Gateway implementation;