Skip to main content

ADR-0015: Content Document v1 And Runtime Lifecycle

Status​

Accepted

Date​

2026-03-07

Context​

Evalium already has live localized-content behavior for passages, localized question payload projection, passage version pinning, and submission snapshots. But the canonical authored-content contract was not frozen in one place.

That created risk of:

  • per-surface schema drift between passages, questions, and future rich authoring fields
  • capability drift (content.* vs existing authoring caps)
  • preview/publish/submission lifecycle drift that would break forensic replay

Decision​

We will freeze a single authored-content contract in docs/architecture/CONTENT-DOCUMENT-V1-CONTRACT.md.

The decision is:

  1. ContentDocument v1 is the canonical authored rich-content contract name.
  2. The v1 per-locale schema discriminator remains passage-rich-content/v1 for compatibility with the live backend.
  3. v1 reuses existing capabilities (questions.*, evaluations.*, media.manage, locales.manage) and does not introduce content.* capabilities.
  4. Preview is non-durable; publish compiles immutable content facts; submission pins immutable runtime truth.
  5. Historical runtime/reporting reads must use snapshot facts and pinned content refs, not live authoring state.

Scope​

Applies to:

  • passage content and passage versioning
  • localized question payload projection
  • evaluation preview content projection
  • submission snapshot and pinned passage replay semantics
  • future authored rich-content fields

Does not by itself add new public endpoints or change current role bundles.

Consequences​

  • Positive:
    • Packages B/C now have one concrete contract to implement against
    • prevents schema/capability/lifecycle forks
    • keeps replay semantics aligned with existing immutable snapshot rules
  • Tradeoff:
    • future content schema or capability changes now require touching the contract doc and likely a new ADR