ADR-069: Domain Concept Projection Contract — System of Record vs. In-Process Working State

Status: v0.2 (RATIFIED 2026-06-12) — Lead-Dev-authored from the #1207 implementation; Architect ratified the carve (memo ~19:35 “strong concur”) and the artifact (memo ~22:30 “v0.1 clean, ratified”). v0.2 folds in Arch’s three optional polish edits (D6 Intent-shape sketch · Source-incidents tracer · D5 negative-pattern made code-explicit).

Date: 2026-06-12

Authors: Lead Developer (implementation context from #1207)

Reviewers: Chief Architect (ratify — carve already concurred), CIO (methodology), CEO (xian)


Status


Context

A single domain concept can carry two responsibilities with different lifecycles: a durable system of record, and a transient in-process working state used to shape behavior. When those two are allowed to drift into two parallel implementations, the result is the #1207 failure mode:

This is ADR-005’s dual-implementation anti-pattern, one altitude up: not two repositories for one entity, but two aggregates for one concept — one masquerading as the durable record, the other as the working state, neither owning the boundary.

The concept generalizes. The next instance is almost certainly Intent (intent_service holds working state on top of the domain Intent aggregate — same shape, same trap waiting), and after that possibly Artifact (#952). Without an ADR-shaped artifact, each future application re-litigates the carve, and the projection-contract pattern stays implicit until the next trap surfaces.


Decision

When a domain concept has both a durable record responsibility and a transient working-state responsibility, split it into three layers with explicit contracts between them.

D1 — When does a domain concept need a projection?

Introduce a projection (a distinct working-state type) only when the working state has at least one of: a different lifecycle (in-process/per-session transient vs. durable), different update semantics (fields mutated by discourse/UX flow, not by domain events), or different invariants (the working state can be reconstructed from the domain state, but not vice-versa). If the working state has none of these — if it is just the domain entity in memory — do not create a projection; use the domain entity. (This guard prevents projection-proliferation: not every in-memory use of a domain object is a projection.)

The reconstructability test is the sharpest: working state is derivable from the system of record; the system of record is not derivable from working state. That asymmetry is what makes one durable and one disposable.

D2 — The three-layer carve (worked example: Conversation)

Layer Conversation instance Role Lifecycle
Domain Conversation + ConversationTurn (services/domain/models.py) System of record Durable (DB)
Application (mediation) ConversationManager (ADR-029) The single access path to persisted turns (get_recent_turns, save_conversation_turn) Per-request
In-process working state (projection) intent_service.ConversationContext Recent-turn window + lens stack + last offer + floor flags + provenance sidecar Per-session, in-process

The projection stays out of the mediation layer (folding it in re-creates the deleted anemic aggregate one altitude up) and its discourse-time fields stay out of the domain entity (mixing transient fields into the durable aggregate violates DDD invariant-protection — Architect Q1, both alternatives rejected).

D3 — Single mapping point invariant (one hydrate, one persist)

There is exactly one place that maps domain records → working state (the anti-corruption-layer seam) and exactly one outbound persist seam. For Conversation: hydrate_turns_from_db() (in) at the process_intent boundary, and save_conversation_turn (out) at the same boundary. New consumers extend the single mapping point; they do not add their own domain→projection mapping. The projection itself performs no I/O.

D4 — Single prompt-shaped reader invariant

There is exactly one place that reads working state into outputs (prompts, responses). For Conversation: build_recent_history(). The 7 hand-copied history-builder blocks that #1207 collapsed — two carrying a silent [:-1] bug — are the canonical evidence for why this invariant is load-bearing: copies drift, and a drifted copy is a behavior bug.

D5 — Guard pattern (mechanism over vigilance)

Pin D2–D4 with a guard test (m-41), so the dual implementation cannot silently regrow. The mechanism only works if its trigger conditions are concrete enough to actually pin — so name the trap in code shapes a contributor can recognize pre-PR, not post-incident:

For Conversation: tests/unit/services/conversation/test_context_unification_guard.py pins exactly these three.

D6 — Evolution (what we are hedging against)

The next domain concept with mixed responsibility applies D1–D5 without re-deriving them. Intent is the named next candidate: working state is already layered on the domain Intent aggregate, and an Intent projection would likely carry the current canonical intent + lens overrides + provisional slot-fills not yet committed to a workflow — none of which belong on the durable Intent record (they’re discourse-time, reconstructable from it). Artifact (#952) is a possible third, but honestly may not need a projection at all — the round-trip-lossless model doesn’t obviously call for one (D1’s gate, applied). When that work lands, the carve is a lookup, not a debate — which is the entire point of recording it.


Consequences

Positive

Negative / cost

Neutral


v0.2 — Lead Dev, 2026-06-12, from the #1207 implementation. Architect-RATIFIED (carve + artifact); v0.2 folds Arch’s three optional polish edits.