fix(people): protect governed mutation runtime types

CHANGELOG.md

@@ -53,6 +53,7 @@ All notable changes to Orgmetra will be documented in this file.
 - Made assignment coverage status-aware: `active` and `leave` remain staffable while `terminated` and other non-eligible employment statuses fail closed.
 - Made organization hierarchy reconstruction fail closed on a cycle at the requested tenant, effective day, and knowledge cutoff while ignoring future-recorded and foreign-tenant facts.
 - Build the outbox due-work index concurrently during migration 0008, requiring that index step to run outside an explicit transaction block so established queues do not block writers while the index is built; pre-index hardening and post-index privileged role setup use separate explicit transactions.
+- Active-PR People mutation commands now require exact built-in governance text and hire status values before digesting or persisting high-impact employment evidence.
 
 ### Security
 

services/people-api/src/orgmetra_people_api/hire.py

@@ -35,8 +35,8 @@ class HireDecisionIntegrityError(RuntimeError):
 
 
 def _validate_operational_uuid(field_name: str, value: object) -> None:
-    """Require a real UUID outside Orgmetra's reserved protocol sentinels."""
-    if not isinstance(value, UUID) or value.int in (0, _MAX_UUID_INT):
+    """Require an exact UUID outside Orgmetra's reserved protocol sentinels."""
+    if type(value) is not UUID or value.int in (0, _MAX_UUID_INT):
         raise ValueError(f"{field_name} must be an operational UUID.")
 
 
@@ -83,7 +83,7 @@ def __post_init__(self) -> None:
             _validate_operational_uuid(field_name, getattr(self, field_name))
         if type(self.effective_from) is not date:
             raise ValueError("effective_from must be a business date.")
-        if not isinstance(self.display_name, str):
+        if type(self.display_name) is not str:
             raise ValueError("display_name must be a string.")
         try:
             self.display_name.encode("utf-8")
@@ -95,7 +95,7 @@ def __post_init__(self) -> None:
             raise ValueError("display_name must not contain control characters.")
         validate_idempotency_key(self.idempotency_key)
         if (
-            not isinstance(self.employment_status_code, str)
+            type(self.employment_status_code) is not str
             or _STATUS_CODE_PATTERN.fullmatch(self.employment_status_code) is None
         ):
             raise ValueError("employment_status_code must be a lower snake_case code.")
@@ -147,7 +147,7 @@ def accept_confirmed_hire(
     ``materialize_worker`` operation and ``candidate_worker_conversion`` field;
     possession of an identity token or purpose string alone is insufficient.
     """
-    if not isinstance(command, HireAcceptanceCommand):
+    if type(command) is not HireAcceptanceCommand:
         raise TypeError("command must be a HireAcceptanceCommand")
     if not isinstance(mutation_port, HireAcceptancePort):
         raise TypeError("mutation_port must implement HireAcceptancePort")
@@ -164,6 +164,6 @@ def accept_confirmed_hire(
         policy=policy,
     )
     result = mutation_port.accept_hire(command=command, authorization=authorization)
-    if not isinstance(result, HireAcceptanceResult):
+    if type(result) is not HireAcceptanceResult:
         raise TypeError("mutation_port must return HireAcceptanceResult")
     return result

services/people-api/src/orgmetra_people_api/mutations.py

@@ -47,26 +47,26 @@ class PeopleMutationIntegrityError(RuntimeError):
 
 
 def _validate_operational_uuid(field_name: str, value: object) -> None:
-    """Require a real UUID outside Orgmetra's reserved protocol sentinels."""
-    if not isinstance(value, UUID) or value.int in (0, _MAX_UUID_INT):
+    """Require an exact UUID outside Orgmetra's reserved protocol sentinels."""
+    if type(value) is not UUID or value.int in (0, _MAX_UUID_INT):
         raise ValueError(f"{field_name} must be an operational UUID.")
 
 
 def _validate_confirmation(value: object) -> None:
     """Require one namespaced human-confirmation reference."""
-    if not isinstance(value, str) or _REFERENCE_PATTERN.fullmatch(value) is None:
+    if type(value) is not str or _REFERENCE_PATTERN.fullmatch(value) is None:
         raise ValueError("confirmation_reference must be a namespaced opaque reference.")
 
 
 def _validate_evidence_version(value: object) -> None:
     """Require one whitespace-free evidence version token."""
-    if not isinstance(value, str) or _VERSION_PATTERN.fullmatch(value) is None:
+    if type(value) is not str or _VERSION_PATTERN.fullmatch(value) is None:
         raise ValueError("evidence_version_code must be a whitespace-free version token.")
 
 
 def validate_idempotency_key(value: object) -> str:
     """Require the same visible-ASCII Idempotency-Key contract as the HTTP boundary."""
-    if not isinstance(value, str) or not (_IDEMPOTENCY_MIN <= len(value) <= _IDEMPOTENCY_MAX):
+    if type(value) is not str or not (_IDEMPOTENCY_MIN <= len(value) <= _IDEMPOTENCY_MAX):
         raise ValueError("idempotency_key must be 16 to 200 visible ASCII characters.")
     if any(ord(character) < 0x21 or ord(character) > 0x7E for character in value):
         raise ValueError("idempotency_key must be 16 to 200 visible ASCII characters.")
@@ -83,11 +83,11 @@ def command_route(
     command: EmploymentMutationCommand | PositionMutationCommand | AssignmentMutationCommand,
 ) -> str:
     """Return the durable route that scopes one People mutation idempotency key."""
-    if isinstance(command, EmploymentMutationCommand):
+    if type(command) is EmploymentMutationCommand:
         return "employment-records"
-    if isinstance(command, PositionMutationCommand):
+    if type(command) is PositionMutationCommand:
         return "position-records"
-    if isinstance(command, AssignmentMutationCommand):
+    if type(command) is AssignmentMutationCommand:
         return "assignment-records"
     raise TypeError("command must be a governed People mutation command")
 
@@ -99,6 +99,7 @@ def idempotency_record_id(
     idempotency_key: str,
 ) -> UUID:
     """Derive a stable operational identity for one tenant/route/key binding."""
+    _validate_operational_uuid("tenant_record_id", tenant_record_id)
     return uuid5(
         _IDEMPOTENCY_NAMESPACE,
         f"{tenant_record_id}:{command_route_value}:{idempotency_key}",
@@ -115,9 +116,9 @@ def mutation_command_digest(
     Generated record identifiers are excluded so a retry that allocates fresh
     UUIDs still matches the first committed command.
     """
-    if not isinstance(authorization, AuthorizationDecision):
+    if type(authorization) is not AuthorizationDecision:
         raise TypeError("authorization must be an AuthorizationDecision")
-    if isinstance(command, EmploymentMutationCommand):
+    if type(command) is EmploymentMutationCommand:
         route = "employment-records"
         semantic_command: dict[str, object] = {
             "confirmation_reference": command.confirmation_reference,
@@ -127,7 +128,7 @@ def mutation_command_digest(
             "evidence_version_code": command.evidence_version_code,
             "person_record_id": str(command.person_record_id),
         }
-    elif isinstance(command, PositionMutationCommand):
+    elif type(command) is PositionMutationCommand:
         route = "position-records"
         semantic_command = {
             "confirmation_reference": command.confirmation_reference,
@@ -137,7 +138,7 @@ def mutation_command_digest(
             "organization_unit_id": str(command.organization_unit_id),
             "position_status_code": command.position_status_code,
         }
-    elif isinstance(command, AssignmentMutationCommand):
+    elif type(command) is AssignmentMutationCommand:
         route = "assignment-records"
         semantic_command = {
             "allocation_ratio": _canonical_allocation_ratio(command.allocation_ratio),
@@ -191,10 +192,10 @@ def __post_init__(self) -> None:
             _validate_operational_uuid(field_name, getattr(self, field_name))
         if type(self.effective_from) is not date:
             raise ValueError("effective_from must be a business date.")
-        if not isinstance(self.employment_status_code, str) or self.employment_status_code not in _EMPLOYMENT_STATUSES:
+        if type(self.employment_status_code) is not str or self.employment_status_code not in _EMPLOYMENT_STATUSES:
             raise ValueError("employment_status_code must be active, leave, or terminated.")
         if (
-            not isinstance(self.employment_concurrency_code, str)
+            type(self.employment_concurrency_code) is not str
             or self.employment_concurrency_code not in _CONCURRENCY_CODES
         ):
             raise ValueError("employment_concurrency_code must be exclusive or concurrent.")
@@ -234,7 +235,7 @@ def __post_init__(self) -> None:
             _validate_operational_uuid(field_name, getattr(self, field_name))
         if type(self.effective_from) is not date:
             raise ValueError("effective_from must be a business date.")
-        if not isinstance(self.position_status_code, str) or self.position_status_code not in _POSITION_STATUSES:
+        if type(self.position_status_code) is not str or self.position_status_code not in _POSITION_STATUSES:
             raise ValueError("position_status_code must be a staffable or closed seat status.")
         _validate_confirmation(self.confirmation_reference)
         _validate_evidence_version(self.evidence_version_code)
@@ -272,7 +273,7 @@ def __post_init__(self) -> None:
             _validate_operational_uuid(field_name, getattr(self, field_name))
         if type(self.effective_from) is not date:
             raise ValueError("effective_from must be a business date.")
-        if not isinstance(self.allocation_ratio, Decimal):
+        if type(self.allocation_ratio) is not Decimal:
             raise ValueError("allocation_ratio must be a Decimal.")
         if not self.allocation_ratio.is_finite():
             raise ValueError("allocation_ratio must be finite.")
@@ -363,7 +364,7 @@ def create_employment_record(
     mutation_port: PeopleMutationPort,
 ) -> EmploymentMutationResult:
     """Authorize the exact employment target before persisting worker employment truth."""
-    if not isinstance(command, EmploymentMutationCommand):
+    if type(command) is not EmploymentMutationCommand:
         raise TypeError("command must be an EmploymentMutationCommand")
     port = _require_port(mutation_port)
     authorization = authorize_resource_fields(
@@ -378,7 +379,7 @@ def create_employment_record(
         policy=policy,
     )
     result = port.create_employment(command=command, authorization=authorization)
-    if not isinstance(result, EmploymentMutationResult):
+    if type(result) is not EmploymentMutationResult:
         raise TypeError("mutation_port must return EmploymentMutationResult")
     return result
 
@@ -392,7 +393,7 @@ def create_position_record(
     mutation_port: PeopleMutationPort,
 ) -> PositionMutationResult:
     """Authorize the exact position target before persisting a staffable seat."""
-    if not isinstance(command, PositionMutationCommand):
+    if type(command) is not PositionMutationCommand:
         raise TypeError("command must be a PositionMutationCommand")
     port = _require_port(mutation_port)
     authorization = authorize_resource_fields(
@@ -407,7 +408,7 @@ def create_position_record(
         policy=policy,
     )
     result = port.create_position(command=command, authorization=authorization)
-    if not isinstance(result, PositionMutationResult):
+    if type(result) is not PositionMutationResult:
         raise TypeError("mutation_port must return PositionMutationResult")
     return result
 
@@ -421,7 +422,7 @@ def create_assignment_record(
     mutation_port: PeopleMutationPort,
 ) -> AssignmentMutationResult:
     """Authorize the exact assignment target before persisting seat allocation."""
-    if not isinstance(command, AssignmentMutationCommand):
+    if type(command) is not AssignmentMutationCommand:
         raise TypeError("command must be an AssignmentMutationCommand")
     port = _require_port(mutation_port)
     authorization = authorize_resource_fields(
@@ -436,7 +437,7 @@ def create_assignment_record(
         policy=policy,
     )
     result = port.create_assignment(command=command, authorization=authorization)
-    if not isinstance(result, AssignmentMutationResult):
+    if type(result) is not AssignmentMutationResult:
         raise TypeError("mutation_port must return AssignmentMutationResult")
     return result
 

services/people-api/src/orgmetra_people_api/postgres_hire.py

@@ -176,7 +176,7 @@ def _is_aware_datetime(value: object) -> bool:
 def _validate_authorization(command: HireAcceptanceCommand, authorization: object) -> AuthorizationDecision:
     """Require an exact allow decision for this immutable selection decision."""
     expected_reference = f"selection_decision:{command.selection_decision_id.hex}"
-    if not isinstance(authorization, AuthorizationDecision):
+    if type(authorization) is not AuthorizationDecision:
         raise HireDecisionIntegrityError("hire mutation requires a typed authorization decision")
     if (
         not authorization.allowed
@@ -304,7 +304,7 @@ def accept_hire(
         authority. Tenant/route/key advisory serialization prevents concurrent
         retries from racing the unique idempotency binding.
         """
-        if not isinstance(command, HireAcceptanceCommand):
+        if type(command) is not HireAcceptanceCommand:
             raise TypeError("command must be a HireAcceptanceCommand")
         decision = _validate_authorization(command, authorization)
 
@@ -453,4 +453,4 @@ def accept_hire(
             person_record_id=command.person_record_id,
             employment_record_id=command.employment_record_id,
             candidate_worker_conversion_record_id=command.candidate_worker_conversion_record_id,
-        )
+        )

services/people-api/src/orgmetra_people_api/postgres_mutations.py

@@ -322,7 +322,7 @@ def _require_authorization(
     requested_fields: frozenset[str],
 ) -> AuthorizationDecision:
     """Require an exact allow decision for the intended mutation target."""
-    if not isinstance(authorization, AuthorizationDecision):
+    if type(authorization) is not AuthorizationDecision:
         raise PeopleMutationIntegrityError("people mutation requires a typed authorization decision")
     if (
         not authorization.allowed
@@ -534,7 +534,7 @@ def create_employment(
         authorization: AuthorizationDecision,
     ) -> EmploymentMutationResult:
         """Persist one employment after conversion and exclusivity checks."""
-        if not isinstance(command, EmploymentMutationCommand):
+        if type(command) is not EmploymentMutationCommand:
             raise TypeError("command must be an EmploymentMutationCommand")
         decision = _require_authorization(
             authorization=authorization,
@@ -637,7 +637,7 @@ def create_position(
         authorization: AuthorizationDecision,
     ) -> PositionMutationResult:
         """Persist one position after organization and job parent checks."""
-        if not isinstance(command, PositionMutationCommand):
+        if type(command) is not PositionMutationCommand:
             raise TypeError("command must be a PositionMutationCommand")
         decision = _require_authorization(
             authorization=authorization,
@@ -727,7 +727,7 @@ def create_assignment(
         authorization: AuthorizationDecision,
     ) -> AssignmentMutationResult:
         """Persist one assignment after conversion and kernel coverage checks."""
-        if not isinstance(command, AssignmentMutationCommand):
+        if type(command) is not AssignmentMutationCommand:
             raise TypeError("command must be an AssignmentMutationCommand")
         decision = _require_authorization(
             authorization=authorization,