feat: expose governed People GET API

.github/workflows/foundation-ci.yml

@@ -4,6 +4,7 @@ on:
   pull_request:
     branches:
       - bootstrap
+      - develop
       - main
       - feat/foundation-product-baseline
   push:

.github/workflows/people-api-quality.yml

@@ -0,0 +1,57 @@
+name: People API Quality
+
+on:
+  pull_request:
+    branches:
+      - bootstrap
+      - develop
+      - main
+    paths:
+      - "services/people-api/**"
+      - "packages/keyverse-adapter/**"
+      - ".github/requirements/foundation-test.txt"
+      - ".github/workflows/people-api-quality.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: people-api-quality-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  unit:
+    name: People API contract and 100% coverage
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout exact candidate
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          persist-credentials: false
+      - name: Prove exact candidate checkout
+        env:
+          ORGMETRA_EXPECTED_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+        run: test "$(git rev-parse HEAD)" = "$ORGMETRA_EXPECTED_HEAD_SHA"
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14"
+          check-latest: false
+      - name: Install reviewed test toolchain
+        run: |
+          python -m pip install --require-hashes --no-deps --only-binary=:all: -r .github/requirements/foundation-test.txt
+          python -m pip check
+      - name: Compile People API boundary
+        run: python -m compileall -q services/people-api/src packages/keyverse-adapter/src services/people-api/tests
+      - name: Test governed People contracts with exact statement and branch coverage
+        env:
+          PYTHONPATH: services/people-api/src:packages/keyverse-adapter/src
+          COVERAGE_FILE: /tmp/orgmetra-people-api.coverage
+        run: python -m pytest -c services/people-api/pyproject.toml services/people-api/tests
+      - name: Require clean checkout
+        run: |
+          git diff --exit-code
+          test -z "$(git status --porcelain)"

services/people-api/README.md

@@ -0,0 +1,15 @@
+# Orgmetra People API
+
+This directory is the rebuilt customer-facing People API boundary on the current protected Orgmetra contracts. The historical PR implementation is retained in Git history but is not replayed because it carried a legacy tenant schema, mutable audit shape, duplicated domain kernel, and pre-governance candidate-worker link.
+
+The current bounded slice owns request-edge bearer-token parsing and an injected token-authentication protocol. It deliberately does **not** encode HR purpose grants in the authenticated principal. Protected field access is delegated to the integrated Orgmetra `orgmetra_keyverse_adapter` purpose-bound policy contract, which binds active tenant, actor tenant, resource tenant, exact opaque target reference, purpose, operation, operation-specific scope, and requested field set before protected HR values may be returned.
+
+The service exposes a governed hire-to-employment read contract. `read_worker_people_record()` authorizes the exact opaque `person_record` target **before** invoking the injected `PeopleReadPort`, so a denied purpose, scope, or field request never causes protected worker values to be retrieved. The returned `WorkerPeopleRecord` carries canonical candidate-conversion, person, and employment lineage; tenant/person mismatches returned by persistence fail closed; and the customer view serializes only fields explicitly authorized by the policy decision.
+
+`PostgresPeopleReadPort` is the production read-side adapter for that port. Deployment code supplies a DB-API-compatible connection factory (for example, a configured psycopg connection or pool boundary); the adapter then starts a read-only transaction, binds the exact tenant through transaction-local `orgmetra.tenant_record_id`, and issues only parameterized, fully-qualified SQL against Orgmetra-owned canonical tables. It resolves `candidate_worker_conversion_record`, `person_record`, `person_name_record`, `employment_record`, and `employment_record_version` using current recorded-time truth plus the requested business date. It fetches at most two rows and rejects duplicate current lineage instead of silently choosing one. Pooling, credentials, TLS and database-role selection remain deployment concerns rather than being embedded in the service package.
+
+`PeopleAsgiApp` exposes that governed read use case as a dependency-light ASGI route: `GET /v1/tenants/{tenant_record_id}/people/{person_record_id}?effective_on=YYYY-MM-DD&purpose=people_read&fields=...`. It validates the exact route and query shape before authentication, accepts exactly one ASCII Bearer credential, delegates authentication and purpose-bound authorization to injected contracts, and never reads protected worker values after a denied authorization decision. Successful responses contain only authorized fields; all HTTP responses use `Cache-Control: no-store` and `Vary: Authorization`. Authentication, authorization, missing-record, integrity-conflict, and unexpected-backend failures are mapped to stable non-disclosing responses with a useful next action, and bearer tokens are never returned in response text.
+
+The People API quality workflow is part of this contract and must run for pull requests to every supported protected/default integration branch, including `develop`. Its service tests enforce 100% owned statement and branch coverage and include regression coverage for the workflow dispatch boundary and HTTP security/transport behavior.
+
+The remaining customer-path work on this same canonical branch is the accepted-mutation path that persists authoritative HRIS facts and governed audit/outbox evidence atomically. The superseded persistence model must not be restored, and the service must not use direct cross-service application-table SQL.

services/people-api/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools==82.0.1"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "orgmetra-people-api"
+version = "0.1.0"
+description = "Purpose-bound customer API boundary for authoritative Orgmetra HR records."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+authors = [{ name = "ContextualWisdomLab" }]
+dependencies = ["orgmetra-keyverse-adapter==0.1.0"]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+orgmetra_people_api = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = [
+  "--cov=orgmetra_people_api",
+  "--cov-branch",
+  "--cov-report=term-missing",
+  "--cov-fail-under=100",
+]
+
+[tool.coverage.run]
+branch = true
+source = ["orgmetra_people_api"]
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true

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

@@ -0,0 +1,35 @@
+"""Request-edge and governed read contracts for the Orgmetra People API."""
+
+from orgmetra_people_api.auth import (
+    AuthenticatedPrincipal,
+    AuthenticationFailed,
+    TokenAuthenticator,
+    extract_bearer_token,
+)
+from orgmetra_people_api.authorization import authorize_resource_fields
+from orgmetra_people_api.http import PeopleAsgiApp
+from orgmetra_people_api.people import (
+    AuthorizedWorkerPeopleView,
+    PeopleReadPort,
+    PeopleRecordIntegrityError,
+    PeopleRecordNotFound,
+    WorkerPeopleRecord,
+    read_worker_people_record,
+)
+from orgmetra_people_api.postgres import PostgresPeopleReadPort
+
+__all__ = [
+    "AuthenticatedPrincipal",
+    "AuthenticationFailed",
+    "AuthorizedWorkerPeopleView",
+    "PeopleAsgiApp",
+    "PeopleReadPort",
+    "PeopleRecordIntegrityError",
+    "PeopleRecordNotFound",
+    "PostgresPeopleReadPort",
+    "TokenAuthenticator",
+    "WorkerPeopleRecord",
+    "authorize_resource_fields",
+    "extract_bearer_token",
+    "read_worker_people_record",
+]

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

@@ -0,0 +1,77 @@
+"""Fail-closed request-edge authentication contracts for the People API.
+
+Authentication proves who the caller is and which operation scopes were issued by
+the identity boundary. HR purpose and field authorization are intentionally not
+stored on this principal; Orgmetra evaluates those attributes through its
+purpose-bound policy contract after the target resource has been resolved.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import re
+from typing import Protocol, runtime_checkable
+from uuid import UUID
+
+_MAX_UUID_INT = (1 << 128) - 1
+_REFERENCE_PATTERN = re.compile(r"^[a-z][a-z0-9_]*:[A-Za-z0-9][A-Za-z0-9._~-]*$")
+_SCOPE_PATTERN = re.compile(r"^orgmetra(?:\.[a-z][a-z0-9_]*){2,}$")
+
+
+class AuthenticationFailed(RuntimeError):
+    """Indicate that bearer authentication evidence is absent or malformed."""
+
+
+@dataclass(frozen=True, slots=True)
+class AuthenticatedPrincipal:
+    """Identity attributes that may be trusted only after token authentication.
+
+    ``tenant_record_id`` binds the authenticated actor to one Orgmetra tenant.
+    ``actor_reference`` is opaque audit correlation rather than a person record
+    identifier. ``granted_scope_codes`` carries explicit operation capabilities;
+    it never carries an HR purpose decision.
+    """
+
+    tenant_record_id: UUID
+    actor_reference: str
+    granted_scope_codes: frozenset[str]
+
+    def __post_init__(self) -> None:
+        """Reject sentinel identities, mutable grants, wildcards, and bad references."""
+        if not isinstance(self.tenant_record_id, UUID):
+            raise ValueError("tenant_record_id must be a UUID.")
+        if self.tenant_record_id.int in (0, _MAX_UUID_INT):
+            raise ValueError("tenant_record_id must not use a reserved UUID sentinel.")
+        if not isinstance(self.actor_reference, str) or _REFERENCE_PATTERN.fullmatch(self.actor_reference) is None:
+            raise ValueError("actor_reference must be a namespaced opaque reference.")
+        if not isinstance(self.granted_scope_codes, frozenset) or not self.granted_scope_codes:
+            raise ValueError("granted_scope_codes must be a non-empty frozenset.")
+        if any(not isinstance(scope, str) or _SCOPE_PATTERN.fullmatch(scope) is None for scope in self.granted_scope_codes):
+            raise ValueError("granted_scope_codes must contain explicit Orgmetra scopes.")
+
+
+@runtime_checkable
+class TokenAuthenticator(Protocol):
+    """Authenticate one bearer token without making an HR authorization decision."""
+
+    async def authenticate(self, bearer_token: str) -> AuthenticatedPrincipal:
+        """Return authenticated identity/scope attributes or raise a stable error."""
+
+
+def extract_bearer_token(authorization_header: str | None) -> str:
+    """Return one bounded printable bearer token without logging its value.
+
+    Splitting only on the first ASCII space keeps C0 separators visible so they
+    are rejected rather than silently treated as whitespace by ``str.split``.
+    """
+    if authorization_header is None:
+        raise AuthenticationFailed("bearer authentication is required")
+    parts = authorization_header.split(" ", 1)
+    if len(parts) != 2 or parts[0].casefold() != "bearer":
+        raise AuthenticationFailed("authorization must use the Bearer scheme")
+    token = parts[1]
+    if not token or len(token) > 8192:
+        raise AuthenticationFailed("bearer token length is invalid")
+    if any(ord(character) < 0x21 or ord(character) > 0x7E for character in token):
+        raise AuthenticationFailed("bearer token contains invalid characters")
+    return token

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

@@ -0,0 +1,47 @@
+"""Delegate People API field access to Orgmetra's integrated policy evaluator."""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from orgmetra_keyverse_adapter import (
+    AuthorizationDecision,
+    PurposeBoundAccessPolicy,
+    PurposeBoundAccessRequest,
+    require_purpose_bound_access,
+)
+
+from orgmetra_people_api.auth import AuthenticatedPrincipal
+
+
+def authorize_resource_fields(
+    *,
+    principal: AuthenticatedPrincipal,
+    tenant_record_id: UUID,
+    resource_tenant_record_id: UUID,
+    resource_reference: str,
+    purpose_code: str,
+    operation_code: str,
+    resource_kind: str,
+    requested_fields: frozenset[str],
+    policy: PurposeBoundAccessPolicy,
+) -> AuthorizationDecision:
+    """Authorize one exact HR resource without duplicating Keyverse policy logic.
+
+    The People API contributes only request-edge identity/scope attributes and the
+    resolved target. The integrated Orgmetra adapter remains the single owner of
+    tenant/resource/purpose/operation/scope/field evaluation and denial evidence.
+    """
+    request = PurposeBoundAccessRequest(
+        tenant_record_id=tenant_record_id,
+        actor_tenant_record_id=principal.tenant_record_id,
+        resource_tenant_record_id=resource_tenant_record_id,
+        actor_reference=principal.actor_reference,
+        resource_reference=resource_reference,
+        purpose_code=purpose_code,
+        operation_code=operation_code,
+        resource_kind=resource_kind,
+        requested_fields=requested_fields,
+        granted_scope_codes=principal.granted_scope_codes,
+    )
+    return require_purpose_bound_access(request=request, policy=policy)