feat(operability): add People API health and readiness probes

[seonghobae]

Buyer-visible operability boundary

Protected develop@9e3e4847510e1e612b48474ba42b177b8ed824df has customer-facing People read/write/hire ASGI boundaries; this PR adds executable process liveness and owned-PostgreSQL readiness without folding Keyverse or any other dedicated-writer dependency into Orgmetra process health.

GET /health is dependency-free process liveness. GET /ready checks only the People API's owned PostgreSQL dependency through a read-only constant SELECT 1. Dependency failures are normalized to bounded 503 evidence without copying database exceptions, credentials, tenant identifiers, or HR values into customer-facing responses. Synchronous DB-API readiness work is executed away from the ASGI event loop while the complete connection-factory/connection/cursor/transaction/SELECT 1 call remains on one worker thread.

RED → root-cause repairs

• Initial RED fdd66c4f3386bf446bb520342a6b44efc0bf8024 proved the operability module was absent; root implementation 831de2302ccce6836870edc294afca2e572fe72c added PeopleOperabilityAsgiApp, ReadinessProbe, and PostgresReadinessProbe.
• Canonical OPERABILITY-document omission: RED ccd736da14aa185f81b6b26b8eac56850a6605dc → repair ec49aec82fff1439fe13f16dbbabb08069f5ffca; deterministic manifest/provenance was then refreshed rather than weakening validation.
• DB-API row-factory compatibility: test head 7a860810be754d3ee0f89ae62803c43ed31ebdd4 added mapping-row coverage → root repair f27420b89af4e4681b84d6d2e7f5289ab7c7e170 removed tuple-shape coupling while retaining fail-closed no-row behavior.
• Code-current traceability defect: RED 82c8ef9597e878d09812ba64c66beb0c0438aa7a made the stale tuple-only documentation contract fail in People API run 33183729417 / job 98891216600; the traceability contract was corrected and the addressed Devin thread resolved.
• ASGI concurrency defect: exact RED head 303133ec656a95ac397ca459e17631862e42e5a5 ran People API Quality 33192924170 / job 98922704282 and failed because /ready invoked the synchronous readiness probe on the event loop. Root repair ac7b947a15838453576d5d3f10c3bcd2ecde4da1 offloaded the complete probe using asyncio.to_thread. The regression was strengthened to a blocking synchronous probe that can complete only if an event-loop callback remains schedulable. The addressed Devin event-loop thread is resolved.

Exact-current-head evidence

Current exact head: 7d75e683b5bca2881f70e4447e69b3de80babd00.
Fresh live base: develop@9e3e4847510e1e612b48474ba42b177b8ed824df.
GitHub reports the PR open · non-draft · mergeable. Mergeability is not merge authorization.

Orgmetra-owned and target-local exact-head evidence is terminal GREEN, including:

• People API Quality 33193114176 / job 98923374415 — exact checkout, 157 tests passed, 1,456 statements / 468 branches at exact 100% coverage, clean checkout
• Recovery Rehearsal Quality 33193114155
• Job-Analysis API Quality 33193114206
• SAST Semgrep 33193114172
• Security Scan 33193114187
• Foundation/PostgreSQL integrity jobs on the same exact head
• required-workflow coverage-source-tree job 98923423916 — terminal success
• required-workflow coverage-evidence job 98923583444 — terminal success
• Noema job 98923349106 — terminal success with an actual same-head review run

The required OpenCode verifier is terminal failure on run 33193113714 / job 98923735602: exact-head and coverage validation complete, but the Reviews API contains no authenticated opencode-agent / opencode-agent[bot] APPROVED or CHANGES_REQUESTED verdict for 7d75e683…. This is not an Orgmetra source/coverage defect. The exact-head RED/remedy/GREEN canary is routed through the existing dedicated owner path ContextualWisdomLab/.github#624; no target-side shim or foreign mutation was introduced.

Required Strix run 33193113727 / job 98923347998 is terminal FAILURE on this same exact head. Trusted central source .github@e1b03eebc6dc5c85aed393e5928927c96376cf46, exact target/base materialization, workflow smoke, secret gating, contextual-orchestrator sidecar provisioning, and pinned Strix installation all succeeded. The first causal boundary is central route/provider handling: orchestrator/free admitted video/avatar/non-chat routes (alibaba/wan-3.0-prime, inclusionai/ling-3.0-flash-fin:free, alibaba/wan-3.0, heygen/avatar-iv) for a text/code security-review workload; sidecar evidence also recorded an earlier 413 request_too_large. Strix then made three bounded attempts and each failed before any authoritative vulnerability report with HTTP 500 internal_error / LLM CONNECTION FAILED (request IDs e18c27492ebf41469118953a9c351f3f, 0f29d14178f24c7cad86fdb66f705198, 8fae693e7af64aed905100efd1b11488). The job correctly failed closed as STRIX_PROVIDER_UNAVAILABLE; artifact 9694995275, SHA-256 af2a2167b5cdb0d81c30c946e2c9156c574059b5103082b46210e5287136b457, is diagnostic-only and not passing security evidence. The exact canary, first causal boundary, smallest owner remedy, and unchanged-head GREEN acceptance are routed through existing owner issue ContextualWisdomLab/.github#1327. No Orgmetra route override, status shim, gate weakening, or foreign source/ref/workflow/settings mutation was introduced.

Review state

The previously unresolved Devin event-loop observation is repaired test-first, answered with exact RED/GREEN evidence, and resolved. Fresh Devin review reports 0 new potential issues and all current inline threads are resolved. There is still no qualifying independent non-author APPROVED review, so approval policy is not satisfied.

Scope discipline

This branch does not mutate Keyverse, Naruon, contextual-orchestrator, central .github, or another dedicated-writer repository, and introduces no cross-service application-table SQL. Metrics, network-policy/Kubernetes manifests, startup-probe tuning, release provenance, release/version/tag work remain separate slices and are not claimed here.

Merge governance

This PR is not merge-ready while OpenCode or Strix is non-passing, or qualifying independent approval is absent. Immediately before any future merge, refetch exact head/base/reviews/threads/rules/checks and use expected-head protection. Do not self-approve, use administrator bypass, weaken a gate, manufacture evidence, or transfer predecessor checks/reviews.

[coderabbitai]

Warning

Review limit reached

Next included review available in 12 minutes.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 21d56216-4b7f-4622-9384-7bbd3682fcea

📥 Commits

Reviewing files that changed from the base of the PR and between 9e3e484 and 7d75e68.

📒 Files selected for processing (9)

• docs/OPERABILITY.md
• docs/doctoring/people-api-operability-references.md
• docs/traceability/people-api-operability.md
• manifest.json
• services/people-api/README.md
• services/people-api/src/orgmetra_people_api/__init__.py
• services/people-api/src/orgmetra_people_api/operability.py
• services/people-api/tests/test_operability_concurrency.py
• services/people-api/tests/test_operability_http.py

✨ 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 feat/people-operability-probes

---

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 0 new potential issues.