fix(people): protect governed mutation runtime types

CHANGELOG.md

@@ -18,7 +18,7 @@ All notable changes to Orgmetra will be documented in this file.
 - `employment_record_version.employment_concurrency_code` constrained to `exclusive` or `concurrent`.
 - ADR 0005 for exclusive employment and staffable seats.
 - `orgmetra_hris_kernel` 0.3.0 with identity-scoped bitemporal resolution, assignment-employment coverage, allocation-portfolio checks, and a Memorial Hospital RN correction case at 100% statement and branch coverage.
-- `employment_record_version` and `position_record_version` so employment and position identity stay stable across retroactive corrections.
+- `employment_record_version` and `position_record_version` so corrections no longer mint a new employment or position identifier.
 - `assignment_record.employment_record_id` bound to the same person as the covering employment.
 - `orgmetra_keyverse_adapter` that binds an opaque Keyverse subject to a person and rejects passwords, passkeys, and tokens.
 - Design tokens for the repeating HR actions: approve, review, correct, request evidence, compare, export, and escalate.
@@ -54,6 +54,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
 

manifest.json

@@ -29,9 +29,9 @@
     },
     {
       "path": "CHANGELOG.md",
-      "sha256": "f2d2e0b488c0440533effa821808f2f17e37d92f8fb586174c2fdb594f760ca5",
-      "bytes": 17539,
-      "lines": 77
+      "sha256": "9ad6dad273c94c30741522ca87205ff24eb92c53becc8b53739d93acb28126f9",
+      "bytes": 17697,
+      "lines": 78
     },
     {
       "path": "CLAUDE.md",
@@ -353,8 +353,8 @@
     },
     {
       "path": "schemas/openapi.yaml",
-      "sha256": "09c1e43486779198574fe31b8bcabbd1c1f74beec7bf86245ae578061619838f",
-      "bytes": 29503,
+      "sha256": "c37522504d1f6ac6410eaac833dddbf09aacc85572da38a1cf7539541833ea8e",
+      "bytes": 29511,
       "lines": 1020
     },
     {

schemas/openapi.yaml

@@ -641,7 +641,7 @@ components:
           format: uuid
         allocation_ratio:
           type: string
-          pattern: '^(0\.[0-9]{4}|1\.0000)$'
+          pattern: '^(0\.(?!0000)[0-9]{4}|1\.0000)$'
         effective_from:
           type: string
           format: date

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

@@ -8,7 +8,7 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from datetime import date
 import re
 from typing import Protocol, runtime_checkable
@@ -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,8 +147,14 @@ 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")
+    command = replace(command)
+    expected_person_record_id = UUID(int=command.person_record_id.int)
+    expected_employment_record_id = UUID(int=command.employment_record_id.int)
+    expected_conversion_record_id = UUID(
+        int=command.candidate_worker_conversion_record_id.int
+    )
     if not isinstance(mutation_port, HireAcceptancePort):
         raise TypeError("mutation_port must implement HireAcceptancePort")
 
@@ -164,6 +170,13 @@ 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")
+    HireAcceptanceResult.__post_init__(result)
+    if (
+        result.person_record_id != expected_person_record_id
+        or result.employment_record_id != expected_employment_record_id
+        or result.candidate_worker_conversion_record_id != expected_conversion_record_id
+    ):
+        raise HireDecisionIntegrityError("hire result identity does not match command")
     return result

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

@@ -10,7 +10,7 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from datetime import date
 from decimal import Decimal
 from hashlib import sha256
@@ -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,10 @@ 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:
+        EmploymentMutationCommand.__post_init__(command)
         route = "employment-records"
         semantic_command: dict[str, object] = {
             "confirmation_reference": command.confirmation_reference,
@@ -127,7 +129,8 @@ 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:
+        PositionMutationCommand.__post_init__(command)
         route = "position-records"
         semantic_command = {
             "confirmation_reference": command.confirmation_reference,
@@ -137,7 +140,8 @@ 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:
+        AssignmentMutationCommand.__post_init__(command)
         route = "assignment-records"
         semantic_command = {
             "allocation_ratio": _canonical_allocation_ratio(command.allocation_ratio),
@@ -191,10 +195,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 +238,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 +276,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,8 +367,10 @@ 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")
+    command = replace(command)
+    expected_employment_record_id = UUID(int=command.employment_record_id.int)
     port = _require_port(mutation_port)
     authorization = authorize_resource_fields(
         principal=principal,
@@ -378,8 +384,11 @@ 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")
+    EmploymentMutationResult.__post_init__(result)
+    if result.employment_record_id != expected_employment_record_id:
+        raise PeopleMutationIntegrityError("employment result identity does not match command")
     return result
 
 
@@ -392,8 +401,10 @@ 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")
+    command = replace(command)
+    expected_position_record_id = UUID(int=command.position_record_id.int)
     port = _require_port(mutation_port)
     authorization = authorize_resource_fields(
         principal=principal,
@@ -407,8 +418,11 @@ 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")
+    PositionMutationResult.__post_init__(result)
+    if result.position_record_id != expected_position_record_id:
+        raise PeopleMutationIntegrityError("position result identity does not match command")
     return result
 
 
@@ -421,8 +435,10 @@ 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")
+    command = replace(command)
+    expected_assignment_record_id = UUID(int=command.assignment_record_id.int)
     port = _require_port(mutation_port)
     authorization = authorize_resource_fields(
         principal=principal,
@@ -436,13 +452,16 @@ 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")
+    AssignmentMutationResult.__post_init__(result)
+    if result.assignment_record_id != expected_assignment_record_id:
+        raise PeopleMutationIntegrityError("assignment result identity does not match command")
     return result
 
 
 def parse_allocation_ratio(raw_value: object) -> Decimal:
     """Parse the OpenAPI allocation token into an exact four-decimal ratio."""
-    if not isinstance(raw_value, str) or re.fullmatch(r"^(0\.[0-9]{4}|1\.0000)$", raw_value) is None:
+    if type(raw_value) is not str or re.fullmatch(r"^(0\.(?!0000)[0-9]{4}|1\.0000)$", raw_value) is None:
         raise ValueError("allocation_ratio must match 0.0001-1.0000 four-decimal form.")
     return Decimal(raw_value)