| 1 | <!-- English translation of adr/0098-semantic-first-document-as-projection.md. Canonical Russian: ../../adr/0098-semantic-first-document-as-projection.md --> |
| 2 | |
| 3 | # ADR 0098: Semantics first; document and repository as projections (Semantic-First) |
| 4 | |
| 5 | **Status:** Proposed |
| 6 | **Date:** 2026-04-24 |
| 7 | |
| 8 | ## Related ADRs |
| 9 | |
| 10 | | ADR | Role | |
| 11 | |-----|------| |
| 12 | | [0039](0039-workspace-navigation-affordances.md) | navigation, **semantic map**, MCP subgraph | |
| 13 | | [0065](0065-instrument-categories-domain-taxonomy.md) | instrument categories and graph types (orthogonal to slot and `instrument_id`) | |
| 14 | | [0053](0053-semantic-map-control-flow-pfd.md) | intent map and control flow on PFD | |
| 15 | | [0056](0056-semantic-map-pipeline-adoption.md) | intent map as product graph | |
| 16 | | [0067](0067-graph-backed-surfaces-contract.md) | graph-backed surfaces | |
| 17 | | [0036](0036-cds-channel-compositor-surface-pipeline.md) | CDS, cockpit channel | |
| 18 | | [0094](0094-ingestion-bus-afdx-analogy-and-threading-channels.md) | delivery bus | |
| 19 | | [0097](0097-cockpit-compute-units-transport-to-channel-dto.md) | CCU — collapse to channel DTO | |
| 20 | | [0068](0068-deck-row-payload-and-presentation-projection.md) | payload vs presentation projection | |
| 21 | | [0079](0079-ide-display-system-ids-overlay-pipeline.md) | IDS | |
| 22 | | [0084](0084-agent-edits-editor-source-of-truth-presence-channel.md) | editor text — source of truth **for edit session**; see [§2.4](#adr0098-alignment-0084) | |
| 23 | | [0095](0095-workspace-solution-ide-health-stratification.md) | three Health levels, `stratum` | |
| 24 | | [0045](0045-agent-chat-persistence-event-log-and-projections.md) | events + projections | |
| 25 | | [0009](0009-strangler-migration-and-exceptions.md) | strangler | |
| 26 | |
| 27 | ## Summary |
| 28 | |
| 29 | - **Semantic-first:** meaning map is primary; code/docs/git are projections. |
| 30 | - Aligned with edit session ([0084](0084-agent-edits-editor-source-of-truth-presence-channel.md)). |
| 31 | |
| 32 | --- |
| 33 | |
| 34 | <a id="adr0098-context"></a> |
| 35 | |
| 36 | ## 1. Context |
| 37 | |
| 38 | In classic “IDE as file editor” **buffer text and repo tree are primary**: architecture, dependencies, and intent are **derived from** artifacts (C#, csproj, ADR, configs). Semantics is derivative, often out of sync with what the human *meant*. |
| 39 | |
| 40 | Cascade already has **meaning-oriented** pieces: **intent map** ([0053](0053-semantic-map-control-flow-pfd.md), [0056](0056-semantic-map-pipeline-adoption.md)), **graph-backed** contract ([0067](0067-graph-backed-surfaces-contract.md)), navigation emphasizing graph and MCP ([0039](0039-workspace-navigation-affordances.md)). Bus, Health, and CCU ([0094](0094-ingestion-bus-afdx-analogy-and-threading-channels.md), [0095](0095-workspace-solution-ide-health-stratification.md), [0097](0097-cockpit-compute-units-transport-to-channel-dto.md)) operate on **normalized meaning** after delivery, not raw “unaddressed stream.” |
| 41 | |
| 42 | This ADR states **north star**: move away from purely **document-centric** model toward **semantic-first** — without requiring immediate full product rewrite. |
| 43 | |
| 44 | --- |
| 45 | |
| 46 | <a id="adr0098-decision"></a> |
| 47 | |
| 48 | ## 2. Decision (invariants) |
| 49 | |
| 50 | <a id="adr0098-semantic-map"></a> |
| 51 | |
| 52 | ### 2.1 Semantic map is primary |
| 53 | |
| 54 | - **Meaning model** (intent, boundaries, relations, states, suitable for attention routing and instruments) is **primary** system design layer. |
| 55 | - **Source code**, **text documents** (ADR, TOML, Markdown), and **git artifacts** are **projections and packaging**: deterministic or semi-deterministic **representations** versionable, diffable, feedable to LSP, CI, and agent. |
| 56 | |
| 57 | <a id="adr0098-cds-ids-instruments"></a> |
| 58 | |
| 59 | ### 2.2 Cockpit channel, IDS, vector/graph instruments |
| 60 | |
| 61 | - **CDS channel** ([0036](0036-cds-channel-compositor-surface-pipeline.md)), **CCU** ([0097](0097-cockpit-compute-units-transport-to-channel-dto.md)), **IDS** ([0079](0079-ide-display-system-ids-overlay-pipeline.md)), instruments and deck rest on **agreed meaning** (DTO, snapshots, `stratum`, etc.), not “whatever one-file parser guessed” as sole source. |
| 62 | - **Forward** (code editor) stays **powerful input channel** into this map, but **not** absolute long-term truth of the whole system. |
| 63 | - For **semantic map**, CCU is **input snapshot** layer (source normalization, version/freshness, derived fields), not graph UX home. Traversal, layout, selection, interaction stay in graph-backed surface ([0067](0067-graph-backed-surfaces-contract.md), [0097 §6 — CCU candidates](0097-cockpit-compute-units-transport-to-channel-dto.md#adr0097-candidates-next)). |
| 64 | |
| 65 | <a id="adr0098-coexistence"></a> |
| 66 | |
| 67 | ### 2.3 Coexistence: two truths where strangler needs it |
| 68 | |
| 69 | - Transitional **two-layer** scenarios allowed: “truth in git for release” + “truth in map for cockpit/agent”, with explicit **sync** and conflict priority. Goal — **converge** to one primary semantics, not eternal split. |
| 70 | |
| 71 | <a id="adr0098-alignment-0084"></a> |
| 72 | |
| 73 | ### 2.4 Alignment with [0084](0084-agent-edits-editor-source-of-truth-presence-channel.md) |
| 74 | |
| 75 | - [0084](0084-agent-edits-editor-source-of-truth-presence-channel.md) fixes **operational** invariant: during joint work **one buffer text** is canon **for applied edit** (human/agent parity, presence, no “second truth in chat”). |
| 76 | - **0098** does not cancel 0084: at edit moment **text projection** remains **input canon** for that session. Long-term **semantic map** is canon of **architecture meaning**; 0084 describes **how** to write safely into projection while round-trip **to/from** map is not one automaton. |
| 77 | |
| 78 | --- |
| 79 | |
| 80 | <a id="adr0098-non-goals"></a> |
| 81 | |
| 82 | ## 3. Non-goals (explicit) |
| 83 | |
| 84 | - **Not** “throw away git”, **not** “no diffs”, **not** “everything in one DB without files.” |
| 85 | - **Not** require full **semantic ↔ repo round-trip** in v1 of this ADR: **direction** and **invariants**; migration — strangler ([0009](0009-strangler-migration-and-exceptions.md)). |
| 86 | - **Not** duplicate full **Semantic Map field ontology** here — separate ADRs/contracts as introduced. |
| 87 | - **Not** equate semantic-first with **up-front complete** semantic or symbolic **tree of entire solution**. **Partial** snapshots, **lazy** map growth (active document, navigation/MCP subgraph, Roslyn/LSP **on demand**) allowed; **CCU** remains **input snapshot** layer ([0097](0097-cockpit-compute-units-transport-to-channel-dto.md)), not sole store of “all truth” before graph ready. |
| 88 | - **Not** mix **product priority of meaning** (this ADR) with **completeness** of compiler instrument graph: Roslyn/compile fullness **pulled where needed** (analysis, navigation, refactor), not **global precondition** for every IDE function. |
| 89 | |
| 90 | --- |
| 91 | |
| 92 | <a id="adr0098-consequences"></a> |
| 93 | |
| 94 | ## 4. Consequences and risks |
| 95 | |
| 96 | - **Plus:** single axis for CCU, channels, agent, cockpit — **same** addressable semantics; less silent file/pixel drift. |
| 97 | - **Risk:** **sync** complexity between projection and map; need discipline, tools, consistency tests. |
| 98 | - **Determinism risk:** code/doc generation from map — reproducibility and stable ordering when needed. |
| 99 | |
| 100 | --- |
| 101 | |
| 102 | <a id="adr0098-link-0100"></a> |
| 103 | |
| 104 | ## 5. Link to future ADR 0100 (hint) |
| 105 | |
| 106 | - Next “center” ADR (agent subjectivity, integrated meaning environment, operator role) naturally builds on **0098** as **primacy-of-meaning north star**; 0100 need not repeat this ADR — may shift focus to **subject/ecosystem**. |
| 107 | |
| 108 | --- |
| 109 | |
| 110 | <a id="adr0098-rejected"></a> |
| 111 | |
| 112 | ## 6. Rejected alternative (brief) |
| 113 | |
| 114 | - **Full document-centrism** as sole truth: simpler for v0, but **does not scale** to cockpit, Health aggregates, intent graphs, coherent UX ([0063](0063-instrument-deck-named-composition-one-anchor.md)–[0068](0068-deck-row-payload-and-presentation-projection.md)) without constant “catch-up” mapping. |
| 115 | |
| 116 | --- |
| 117 | |
| 118 | <a id="adr0098-adoption-status"></a> |
| 119 | |
| 120 | ## 7. Adoption status |
| 121 | |
| 122 | - **Proposed** — normative **intent** and boundaries; concrete modules, map storage, timelines — follow-up ADR and roadmap. |
| 123 | |
| 124 | --- |
| 125 | |
| 126 | <a id="adr0098-faq"></a> |
| 127 | |
| 128 | ## 8. FAQ |
| 129 | |
| 130 | **With semantic-first, must we build full semantic tree of solution up front?** |
| 131 | **No** ([§3 last bullets](#adr0098-non-goals)). ADR invariant is **role** of meaning layer and agreed snapshots, not mandatory **a priori completeness** of graph. Practical semantics may grow **incrementally** and **by scope** (file, project, Language Service request), alongside file projection, while strangler applies. |
| 132 | |