Vatix Protocol

Monorepo for the Vatix Protocol. Package focus: vatix-backend.

Health vs. readiness probes

The backend exposes two distinct probe endpoints. They are intentionally separate so orchestrators (Kubernetes, ECS, Docker Compose) can distinguish a live-but-not-ready process from a dead one.

Endpoint	Semantics	Success	Failure
/health	Liveness. Returns 200 while the process is alive and the event loop is responsive. It does not check dependencies.	200	500 only if the process itself is wedged
/ready	Readiness. Returns 200 only when every critical dependency (DB, Redis, RPC) is reachable. Fails closed with 503 when any dependency is unavailable.	200	503

Readiness response contract

/ready returns a typed JSON body with a stable error code and a correlation id so operators can trace a failing probe without leaking secrets:

{
  "status": "unavailable",
  "code": "DEPENDENCY_UNAVAILABLE",
  "correlationId": "<uuid>",
  "checks": {
    "db": "ok",
    "redis": "unavailable",
    "rpc": "ok"
  }
}

Stable error codes:

• OK — all critical dependencies reachable.
• DEPENDENCY_UNAVAILABLE — at least one critical dependency is down.
• DEPENDENCY_TIMEOUT — a dependency check exceeded its deadline.

Security & observability

• Probe responses and logs never include connection strings, credentials, hostnames, or internal addresses — only the dependency name and a coarse status (ok / unavailable / timeout).
• Readiness is deny-by-default: an unknown or unconfigured dependency is treated as unavailable, so a misconfigured deploy fails closed rather than serving traffic.
• Probe outcomes are emitted as structured logs/metrics keyed by dependency name and status, with the correlation id for cross-referencing.

Orchestrator wiring

• Liveness probe: GET /health
• Readiness probe: GET /ready

Do not point a liveness probe at /ready (a dependency outage would restart a healthy process) and do not point a readiness probe at /health (traffic would be routed to a process that cannot serve it).

Docker Compose

See docs/docker-compose.md for local orchestration and probe configuration.

Security

See SECURITY.md for the deny-by-default policy, rate-limit governance, and probe safety invariants.