57 lines
1.9 KiB
Markdown
57 lines
1.9 KiB
Markdown
|
# 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.
|