Document and test readiness dependency boundaries

[ashrafee-dev]

OBS-10 · Operations and observability

Difficulty: intermediate · Status: design-needed

This is a design proposal, not an approved runtime change or a beginner implementation task. Discuss the scope and compatibility with a maintainer first; it may be closed as not planned.

Why this is useful

The old readiness issue is implemented but acceptance needs a precise contract

Start here

Source audit: 9d8ac3e01df1. Read these files on current main too, because paths may change after the audit:

• app/main.py
• app/services/risk.py
• app/services/rate_limit.py
• scripts/serve.sh

Scope and intended output

First deliver a scoped design note at docs/decisions/observability/health-probe-policy.md covering the stated decision. Runtime or infrastructure implementation is not approved until maintainers accept the approach.

Acceptance criteria

• Verify Redis readiness and configuration startup validation
• Document that probes do not call DeepSeek or transcribe
• Test failures without paid checks

Verification

git diff --check

This command checks patch hygiene only, not design correctness. Review each decision criterion with a maintainer; validate any proposed config locally before it becomes an implementation task.

Dependencies

None. Keep the PR based on current upstream main.

Out of scope

• Unrelated refactors, broad formatting, endpoint renames, or extra dependencies without agreement.
• Live cloud provisioning, paid model calls, real private messages, or credentials in fixtures/logs.
• Implementing neighboring roadmap issues in the same PR.

Getting help and submitting

Comment with your intended approach and ask when expected behavior is unclear. Check for an existing PR before starting; there is no deadline for a volunteer contribution. A useful reproduction or partial finding is welcome.

Use the issue's criteria as the review checklist. Include the commands actually run and any limitations. Link the issue; use Fixes only when its entire agreed scope is complete. If CONTRIBUTING.md is not yet on main, the contributor-roadmap PR provides the onboarding guide.

Original issue before the source audit (historical context)

Goal

Distinguish a running process from an API instance that can actually analyze requests.

Acceptance criteria

• Add a readiness endpoint or documented readiness behavior separate from the liveness check.
• Define how Redis, the API key, and audio dependencies are handled.
• Avoid making expensive DeepSeek or Whisper calls on every probe.