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)
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:
ConversationContext (one in services/intent_service/conversation_context.py, one in services/conversation/conversation_manager.py) with different field names (message/response vs user_message/assistant_response).ConversationManager, #563) never flowed back into the other (the in-memory registry the floor read), so antecedent resolution saw empty history (#1122) and persistence felt “hinky.”except: pass.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.
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.
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.
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).
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.
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.
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:
ConversationManager.ConversationContext aggregate — assert the module doesn’t redefine it).for turn in <ctx>.turns[...] working-state iteration in consumers (the 7-copy history-builder shape — assert consumers call the single reader instead).For Conversation: tests/unit/services/conversation/test_context_unification_guard.py pins exactly these three.
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.
Positive
Intent, Artifact) inherit a vetted carve + guard shape.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.