plex-playlist/docs/adr/ADR003-deployable_runtime_image_contract.md

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.