# ADR003: Deployable Runtime Image Contract Boundaries

- Status: Accepted
- Date: 2026-06-19

## Context

The repository has both deployable runtime artifacts and CI/development tooling
artifacts. Without an explicit boundary, non-runtime concerns can drift into
deployable images, making runtime behavior less predictable and increasing
artifact complexity.

Issue PP-58 requires a clear, approved contract for minimal backend and frontend
deployable images, including health and startup behavior and explicit exclusion
of non-runtime tooling classes.

## Decision

Adopt a canonical deployable runtime contract at:

- `docs/DEPLOYABLE_RUNTIME_CONTRACT.md`

The contract defines, for backend and frontend deployable images:

1. Runtime artifact boundaries (final image intent and payload).
2. Runtime entrypoint and exposed ports.
3. Runtime health and startup behavior expectations.
4. Runtime environment variable contract.
5. Disallowed non-runtime tooling classes in final deployable images.

Scope guardrails for PP-58:

- Documentation and architectural decision codification only.
- No CI workflow rewiring in this issue.
- No test execution redesign in this issue.
- Enforcement automation deferred to follow-up work under epic #66.

## Consequences

Positive:

- Deployable image intent is explicit and auditable.
- Future tickets can implement automated checks against a stable policy.
- Reduced ambiguity between runtime artifacts and CI/development environments.

Negative:

- Requires ongoing documentation maintenance when runtime contracts evolve.
- Drift can still occur if future changes bypass policy review.

## Alternatives Considered

- Rely on Dockerfiles only as implicit contract.
  - Rejected: too easy for intent drift and inconsistent interpretation.
- Enforce contract immediately in CI without documentation-first baseline.
  - Rejected: increases implementation risk without agreed policy language.