| 1 | # Engineering knowledge base (evidence) v1 |
| 2 | |
| 3 | **Назначение:** база хранит знания, а не книги. Факты, эвристики и задачи внедрения с атрибуцией источника; источники — для цитирования и опционального углублённого чтения. |
| 4 | |
| 5 | **Формат записи:** Fact, Heuristic, First adoption task, Success criterion, Confidence; в конце — *Source* (и дата). |
| 6 | |
| 7 | --- |
| 8 | |
| 9 | ## Language and runtime |
| 10 | |
| 11 | - **Fact:** C# 14 introduces extension members, null-conditional assignment, field-backed properties, enhanced span conversions, and partial constructors/events. |
| 12 | - **Heuristic:** treat language features as selective leverage; adopt only where they reduce complexity or runtime overhead in active code. |
| 13 | - **First adoption task:** evaluate `field`-backed property and null-conditional assignment opportunities in actively edited domain models/view models. |
| 14 | - **Success criterion:** reduced boilerplate without added ambiguity in code review. |
| 15 | - **Confidence:** medium |
| 16 | - *Source:* Microsoft Learn - What's new in C# 14 (`https://learn.microsoft.com/dotnet/csharp/whats-new/csharp-14`) (2026-02-25) |
| 17 | |
| 18 | - **Fact:** C# 14 is supported on .NET 10+; compiler defaults are TFM-aligned; using newer-than-TFM language combinations is unsupported. |
| 19 | - **Heuristic:** keep language policy deterministic and framework-compatible to avoid machine-specific breakage. |
| 20 | - **First adoption task:** verify solution-wide TFM and LangVersion policy in shared build config. |
| 21 | - **Success criterion:** no unsupported language/runtime combinations across projects. |
| 22 | - **Confidence:** high |
| 23 | - *Source:* Microsoft Learn - C# language versioning (`https://learn.microsoft.com/dotnet/csharp/language-reference/language-versioning`) (2026-02-25) |
| 24 | |
| 25 | - **Fact:** .NET 10 (LTS) includes runtime, SDK, testing platform, and libraries improvements relevant to performance and delivery workflows. |
| 26 | - **Heuristic:** upgrade decisions should be driven by measurable gains (build/test/debug/latency), not by novelty. |
| 27 | - **First adoption task:** define a small before/after benchmark set for representative workloads. |
| 28 | - **Success criterion:** evidence-backed upgrade value on local project metrics. |
| 29 | - **Confidence:** medium |
| 30 | - *Source:* Microsoft Learn - What's new in .NET 10 (`https://learn.microsoft.com/dotnet/core/whats-new/dotnet-10/overview`) (2026-02-25) |
| 31 | |
| 32 | --- |
| 33 | |
| 34 | ## .NET Framework history and compatibility (1.0 → 4.x) |
| 35 | |
| 36 | - **Fact:** .NET Framework 1.0, 1.1, 2.0, 3.0 и 3.5 исторически шли как цепочка надстроек: 2.0/3.0/3.5 разделяют один CLR 2.0, а установленный .NET Framework 3.5 SP1 поддерживает запуск приложений, нацеленных на версии 1.0–3.5; ветка 4.x (4.0–4.8.1) имеет отдельный CLR 4.0 и ставится параллельно с 3.5, но сама 4.x — in‑place обновления (на машине одновременно может быть только одна 4.x). |
| 37 | - **Heuristic:** при разборе и модернизации старых приложений различать «ветку 2.0/3.5» и «ветку 4.x» как два параллельных рантайма: 3.5 SP1 закрывает хвост 1.0–3.5, а конкретный установленный 4.x определяет доступные возможности и поведение для всех .NET Framework 4‑приложений на машине. |
| 38 | - **First adoption task:** для любого наследуемого .NET Framework-приложения явным образом зафиксировать его целевой TFM (например, `v2.0.50727`, `v3.5`, `v4.0`, `v4.7.2`) и сопоставить с фактически установленными версиями .NET Framework на целевых серверах. |
| 39 | - **Success criterion:** нет «мистических» расхождений поведения между окружениями, объясняемых разными установленными версиями 3.5/4.x. |
| 40 | - **Confidence:** medium |
| 41 | - *Source:* Microsoft Learn - .NET Framework versions and dependencies (`https://learn.microsoft.com/dotnet/framework/install/versions-and-dependencies#version-information`) + Install .NET Framework on Windows and Windows Server (`https://learn.microsoft.com/dotnet/framework/install/on-windows-and-server`) (2026-03-10) |
| 42 | |
| 43 | - **Fact:** ранние версии .NET Framework (1.0, 1.1, 2.0, 3.0, 3.5, ранние 4.x) живут по фиксированному жизненному циклу, завязанному на версию Windows; многие из них уже вышли из поддержки (например, 1.0/1.1 — в 2013/2015, часть 4.x — в 2022 из‑за ухода от SHA‑1). |
| 44 | - **Heuristic:** новые приложения не должны таргетировать ничего ниже поддерживаемых сегодня минимальных версий (практически — 4.6.2+/4.7.2+/4.8.x или .NET 8/10); эксплуатация старых фреймворков допустима только как временный этап миграции с явной оценкой рисков по безопасности и поддержке. |
| 45 | - **First adoption task:** для каждого .NET Framework-наследника составить мини‑ADR: текущая целевая версия, статус поддержки по документации, план минимального upgrade‑шага (например, 4.0→4.8 или 3.5→.NET 8) с основными блокерами. |
| 46 | - **Success criterion:** нет активной новой разработки на неподдерживаемых версиях .NET Framework; для всех «legacy» есть зафиксированный план миграции. |
| 47 | - **Confidence:** medium |
| 48 | - *Source:* Microsoft Learn - Lifecycle FAQ - .NET Framework (`https://learn.microsoft.com/lifecycle/faq/dotnet-framework`) + Releases and support for .NET (`https://learn.microsoft.com/dotnet/core/releases-and-support`) (2026-03-10) |
| 49 | |
| 50 | - **Fact:** .NET (Core) 1.0–10 и .NET Framework — разные продуктовые линии: .NET Framework остаётся Windows‑компонентом с фиксированным жизненным циклом, а .NET 5+ (включая 8/9/10) использует modern lifecycle и кроссплатформенную модель поставки. |
| 51 | - **Heuristic:** при модернизации «толстых» .NET Framework‑систем целесообразно разделять «что остаётся на Full Framework (например, глубоко интегрированный WinForms/WPF/COM)» и «что может быть вынесено/переписано на .NET 8/10»; это уменьшает lock‑in и открывает путь к современным возможностям рантайма. |
| 52 | - **First adoption task:** для одного крупного .NET Framework‑решения построить карту: какие подсистемы принципиально завязаны на Full Framework/Windows‑API, а какие уже сейчас могут быть вынесены в .NET 8/10‑сервисы/библиотеки. |
| 53 | - **Success criterion:** понятный целевой «мост» между старой и новой линиями .NET без попытки «переписать всё за раз». |
| 54 | - **Confidence:** medium |
| 55 | - *Source:* Microsoft Learn - .NET Framework Lifecycle (`https://learn.microsoft.com/lifecycle/products/microsoft-net-framework`) + Releases and support for .NET (`https://learn.microsoft.com/dotnet/core/releases-and-support`) (2026-03-10) |
| 56 | |
| 57 | |
| 58 | ## Testing and diagnostics |
| 59 | |
| 60 | - **Fact:** resilient tests are fast, isolated, repeatable, and readable; avoid infrastructure in unit tests; prefer AAA and one Act per test. |
| 61 | - **Heuristic:** test quality is constrained more by design and readability than by raw coverage percentage. |
| 62 | - **First adoption task:** enforce naming/AAA/one-Act conventions in newly added tests and refactor flaky patterns. |
| 63 | - **Success criterion:** lower flaky test rate and faster root-cause detection in CI/local runs. |
| 64 | - **Confidence:** high |
| 65 | - *Source:* Microsoft Learn - Unit testing best practices for .NET (`https://learn.microsoft.com/dotnet/core/testing/unit-testing-best-practices`) (2026-02-25) |
| 66 | |
| 67 | - **Fact:** xUnit Test Patterns рассматривает тестовый код как полноправный объект дизайна: в нём есть свои повторяющиеся запахи (Obscure Test, Fragile Test, Conditional Test Logic, Mystery Guest и др.) и каталог паттернов их устранения. |
| 68 | - **Heuristic:** относиться к обнаружению «test smells» как к сигналу для рефакторинга тестов, а не как к косметике; цель — маленькие, читаемые, цельные тесты с явным намерением, а не большие сценарные дампы. |
| 69 | - **First adoption task:** выбрать одну существующую тестовую сборку и классифицировать 3–5 самых неприятных тестов по запахам из xUnit Test Patterns; для каждого запаха подобрать и применить один-двa паттерна рефакторинга (например, Extract Fixture, Assertion Message, Inline Conditional). |
| 70 | - **Success criterion:** уменьшение длины и условной логики в тестах, более понятные имена и структура, меньше хрупких тестов при изменении реализации. |
| 71 | - **Confidence:** high |
| 72 | - *Source:* Gerard Meszaros — *xUnit Test Patterns: Refactoring Test Code*, вводные главы и оглавление паттернов (2007; издание на руках в локальной библиотеке, OCR страниц 1–20 через локальный A/V MCP) (2026-03-05) |
| 73 | |
| 74 | - **Fact:** integration tests should cover critical infrastructure boundaries (DB/files/network/request pipeline), while broad permutation coverage remains in unit tests for speed. |
| 75 | - **Heuristic:** reserve integration tests for high-risk seams and use `WebApplicationFactory` + `TestServer` as the standard host pattern. |
| 76 | - **First adoption task:** define a minimal integration suite for critical HTTP flows, persistence boundary, and auth boundary. |
| 77 | - **Success criterion:** critical path regressions are caught without major slowdown in feedback cycle. |
| 78 | - **Confidence:** high |
| 79 | - *Source:* Microsoft Learn - Integration tests in ASP.NET Core (`https://learn.microsoft.com/aspnet/core/test/integration-tests?view=aspnetcore-10.0`) (2026-02-25) |
| 80 | |
| 81 | - **Fact:** first-line diagnosis should start with counters/stacks/traces (`dotnet-counters`, `dotnet-stack`, `dotnet-trace`) before deep dump analysis. |
| 82 | - **Heuristic:** use staged diagnostics escalation (health signals -> trace -> dump) to reduce time-to-root-cause. |
| 83 | - **First adoption task:** create a lightweight diagnostics runbook mapping common symptoms to first tool choice. |
| 84 | - **Success criterion:** lower mean time to identify root cause in CPU/memory/thread incidents. |
| 85 | - **Confidence:** high |
| 86 | - *Source:* Microsoft Learn - .NET diagnostic tools overview (`https://learn.microsoft.com/dotnet/core/diagnostics/tools-overview`) (2026-02-25) |
| 87 | |
| 88 | - **Fact:** .NET 10 introduces Microsoft.Testing.Platform mode for `dotnet test`; mixed VSTest/MTP usage is discouraged. |
| 89 | - **Heuristic:** keep one consistent test runner model solution-wide to avoid silent option mismatches and unsupported configurations. |
| 90 | - **First adoption task:** decide and document single runner mode for active solutions (`global.json` + shared props policy). |
| 91 | - **Success criterion:** deterministic local/CI test behavior without mode-dependent surprises. |
| 92 | - **Confidence:** medium |
| 93 | - *Source:* Microsoft Learn - Testing with `dotnet test` (`https://learn.microsoft.com/dotnet/core/testing/unit-testing-with-dotnet-test`) (2026-02-25) |
| 94 | |
| 95 | |
| 96 | ## Async and reliability |
| 97 | |
| 98 | - **Fact:** xUnit creates a new test class instance per test; shared setup should use fixtures (`IClassFixture`, `ICollectionFixture`, assembly fixtures) deliberately. |
| 99 | - **Heuristic:** default to isolated tests and introduce shared fixtures only for expensive immutable context. |
| 100 | - **First adoption task:** audit existing test classes for hidden shared mutable state and migrate to explicit fixture patterns where needed. |
| 101 | - **Success criterion:** reduced flakiness and clearer test lifecycle semantics. |
| 102 | - **Confidence:** high |
| 103 | - *Source:* xUnit docs via Context7 (`/xunit/xunit.net`) - shared context and fixtures guidance (2026-02-25) |
| 104 | |
| 105 | - **Fact:** reliability and throughput depend on async end-to-end paths, avoiding sync-over-async, reducing LOH pressure, and keeping hot paths minimal. |
| 106 | - **Heuristic:** treat thread-pool starvation and allocation spikes as first-class regressions, not incidental performance noise. |
| 107 | - **First adoption task:** create a concise checklist for controller/middleware reviews (async I/O, pagination, HttpClientFactory, no captured HttpContext in background tasks). |
| 108 | - **Success criterion:** fewer starvation-related incidents and lower p95 latency variance. |
| 109 | - **Confidence:** high |
| 110 | - *Source:* Microsoft Learn - ASP.NET Core Best Practices (`https://learn.microsoft.com/aspnet/core/fundamentals/best-practices?view=aspnetcore-10.0`) (2026-02-25) |
| 111 | |
| 112 | - **Fact:** choose async strategy by workload type (I/O-bound vs CPU-bound), use `Task.WhenAll/WhenAny`, avoid blocking waits (`Wait/Result`), and force immediate LINQ task materialization (`ToArray/ToList`). |
| 113 | - **Heuristic:** async correctness is mostly about preserving non-blocking flow and explicit concurrency boundaries. |
| 114 | - **First adoption task:** audit existing async code for blocking calls and deferred LINQ task pitfalls. |
| 115 | - **Success criterion:** no deadlock-prone patterns in newly touched modules. |
| 116 | - **Confidence:** high |
| 117 | - *Source:* Microsoft Learn - Asynchronous programming scenarios (`https://learn.microsoft.com/dotnet/csharp/asynchronous-programming/async-scenarios`) (2026-02-25) |
| 118 | |
| 119 | |
| 120 | ## Platform and data layer |
| 121 | |
| 122 | - **Fact:** low-overhead operational telemetry can be established with `EventSource/EventCounter` plus `dotnet-counters monitor/collect`. |
| 123 | - **Heuristic:** instrument first, optimize second; track trend over time instead of single-point snapshots. |
| 124 | - **First adoption task:** define a minimal counter set for active services (`requests/sec`, request latency metric, `cpu-usage`) and capture baseline traces. |
| 125 | - **Success criterion:** at least one reproducible before/after performance baseline per optimization cycle. |
| 126 | - **Confidence:** medium |
| 127 | - *Source:* Microsoft Learn - EventCounters tutorial (`https://learn.microsoft.com/dotnet/core/diagnostics/event-counter-perf`) (2026-02-25) |
| 128 | |
| 129 | - **Fact:** .NET 10 runtime improves JIT codegen/inlining/devirtualization, broadens stack allocation scenarios, and reduces abstraction overhead in common patterns. |
| 130 | - **Heuristic:** performance work should prioritize shape-friendly code that the JIT can optimize (tight loops, predictable allocations, clear call paths). |
| 131 | - **First adoption task:** identify one hot path and test whether minor code-shape changes produce measurable JIT wins in Release mode. |
| 132 | - **Success criterion:** observable CPU or latency improvement with no semantic regression. |
| 133 | - **Confidence:** medium |
| 134 | - *Source:* Microsoft Learn - What's new in .NET 10 runtime (`https://learn.microsoft.com/dotnet/core/whats-new/dotnet-10/runtime`) (2026-02-25) |
| 135 | |
| 136 | - **Fact:** ASP.NET Core 10 introduces meaningful behavior changes (for example, streaming defaults in some client paths) and template/runtime-level UX/security updates. |
| 137 | - **Heuristic:** release upgrades require explicit audit of behavioral defaults, not only API compilation success. |
| 138 | - **First adoption task:** create upgrade checklist item for runtime behavior deltas impacting networking/streaming/security-sensitive flows. |
| 139 | - **Success criterion:** no unexpected post-upgrade runtime behavior in critical scenarios. |
| 140 | - **Confidence:** medium |
| 141 | - *Source:* Microsoft Learn - What's new in ASP.NET Core 10 (`https://learn.microsoft.com/aspnet/core/release-notes/aspnetcore-10.0?view=aspnetcore-10.0`) (2026-02-25) |
| 142 | |
| 143 | - **Fact:** EF Core 10 adds major capabilities (JSON/vector support, named filters, richer translation controls, improved bulk update ergonomics) and updates SQL generation strategies. |
| 144 | - **Heuristic:** treat ORM upgrades as query-planning events; verify generated SQL and plan behavior on representative workloads. |
| 145 | - **First adoption task:** select 2-3 high-impact queries and compare generated SQL/plans before and after EF10 adoption. |
| 146 | - **Success criterion:** neutral or improved query stability and performance under production-like data shapes. |
| 147 | - **Confidence:** medium |
| 148 | - *Source:* Microsoft Learn - What's new in EF Core 10 (`https://learn.microsoft.com/ef/core/what-is-new/ef-core-10.0/whatsnew`) (2026-02-25) |
| 149 | |
| 150 | - **Fact:** MTP emphasizes deterministic, hostable, low-dependency test execution and aligns with .NET 10 `dotnet test` evolution. |
| 151 | - **Heuristic:** prefer one deterministic test execution model per repo to avoid mode split and inconsistent tooling behavior. |
| 152 | - **First adoption task:** define repository-wide test runner stance and codify it in `global.json` + shared test project policy. |
| 153 | - **Success criterion:** identical local and CI test semantics for the same commit. |
| 154 | - **Confidence:** high |
| 155 | - *Source:* Microsoft Learn - Microsoft.Testing.Platform intro (`https://learn.microsoft.com/dotnet/core/testing/microsoft-testing-platform-intro`) (2026-02-25) |
| 156 | |
| 157 | - **Fact:** C# 14 support is bound to .NET 10+ targets; mismatched language/runtime combinations are unsupported and risk subtle failures. |
| 158 | - **Heuristic:** pin language-policy by TFM and avoid machine-dependent compiler behavior for shared codebases. |
| 159 | - **First adoption task:** validate that active projects target `.NET 10` where C# 14 features are expected, and enforce explicit fallback for older targets. |
| 160 | - **Success criterion:** no unsupported language-version combinations in build matrix. |
| 161 | - **Confidence:** high |
| 162 | - *Source:* Microsoft Learn - C# language versioning + C# 14 (`https://learn.microsoft.com/dotnet/csharp/language-reference/language-versioning`, `https://learn.microsoft.com/dotnet/csharp/whats-new/csharp-14`) (2026-02-25) |
| 163 | |
| 164 | |
| 165 | ## Diagnostics and query efficiency |
| 166 | |
| 167 | - **Fact:** .NET 10 differentiates VSTest mode and MTP mode with concrete migration steps; mixed assumptions can silently ignore options. |
| 168 | - **Heuristic:** command-line compatibility must be treated as contract and verified in CI scripts after runner migration. |
| 169 | - **First adoption task:** add CI smoke command set that validates expected test runner options and exit behavior. |
| 170 | - **Success criterion:** no silently ignored critical test arguments in CI. |
| 171 | - **Confidence:** medium |
| 172 | - *Source:* Microsoft Learn - Testing with `dotnet test` in .NET 10 (`https://learn.microsoft.com/dotnet/core/testing/unit-testing-with-dotnet-test`) (2026-02-25) |
| 173 | |
| 174 | - **Fact:** high-CPU investigation is most effective with staged workflow: verify counters, capture trace, inspect call stacks/hot methods. |
| 175 | - **Heuristic:** always separate symptom confirmation (`dotnet-counters`) from causal analysis (`dotnet-trace` + stack/call-tree tools). |
| 176 | - **First adoption task:** standardize a high-CPU playbook for active services with fixed capture duration and artifact naming. |
| 177 | - **Success criterion:** repeatable hotspot identification in one diagnostic cycle. |
| 178 | - **Confidence:** high |
| 179 | - *Source:* Microsoft Learn - Debug high CPU usage (`https://learn.microsoft.com/dotnet/core/diagnostics/debug-highcpu`) (2026-02-25) |
| 180 | |
| 181 | - **Fact:** leak diagnosis requires both growth confirmation over time and heap root analysis from dumps, not only working-set observation. |
| 182 | - **Heuristic:** use object-root chains (`gcroot`) to find ownership leaks rather than guessing from type counts alone. |
| 183 | - **First adoption task:** add memory-leak checklist (baseline -> load -> counters -> dump -> root analysis). |
| 184 | - **Success criterion:** identified retaining owner for major leaked object classes. |
| 185 | - **Confidence:** high |
| 186 | - *Source:* Microsoft Learn - Debug a memory leak (`https://learn.microsoft.com/dotnet/core/diagnostics/debug-memory-leak`) (2026-02-25) |
| 187 | |
| 188 | - **Fact:** starvation is strongly indicated by sustained thread count growth with low CPU saturation and blocking stacks on ThreadPool workers. |
| 189 | - **Heuristic:** treat sync-over-async (`.Result/.Wait`) as critical risk in request paths and enforce async end-to-end. |
| 190 | - **First adoption task:** run static/targeted audit for blocking waits in request handlers and service hot paths. |
| 191 | - **Success criterion:** no blocking wait pattern in newly changed high-traffic paths. |
| 192 | - **Confidence:** high |
| 193 | - *Source:* Microsoft Learn - Debug ThreadPool starvation (`https://learn.microsoft.com/dotnet/core/diagnostics/debug-threadpool-starvation`) (2026-02-25) |
| 194 | |
| 195 | - **Fact:** `dotnet-trace` provides cross-platform EventPipe-based traces with tunable providers/profiles and controlled duration for production-safe capture. |
| 196 | - **Heuristic:** keep trace collection scope narrow (providers + duration) to reduce noise and dropped events. |
| 197 | - **First adoption task:** define default trace presets for CPU, contention, and GC investigations. |
| 198 | - **Success criterion:** actionable traces with low event-loss and clear analysis target. |
| 199 | - **Confidence:** medium |
| 200 | - *Source:* Microsoft Learn - dotnet-trace utility (`https://learn.microsoft.com/dotnet/core/diagnostics/dotnet-trace`) (2026-02-25) |
| 201 | |
| 202 | - **Fact:** coverage metrics are useful as feedback signals but not as standalone quality proxy; tooling should feed branch-level insight into review workflow. |
| 203 | - **Heuristic:** optimize for meaningful test behavior coverage, not maximal percentage. |
| 204 | - **First adoption task:** publish baseline coverage report generation path (`coverlet` + report generator) for CI/local parity. |
| 205 | - **Success criterion:** stable and readable coverage artifacts per test run. |
| 206 | - **Confidence:** medium |
| 207 | - *Source:* Microsoft Learn - Unit testing code coverage (`https://learn.microsoft.com/dotnet/core/testing/unit-testing-code-coverage`) (2026-02-25) |
| 208 | |
| 209 | |
| 210 | ## Architecture and testing |
| 211 | |
| 212 | - **Fact:** major EF perf wins come from indexing alignment, selective projection, controlled result size, eager/split loading strategy, and tracking-mode choice. |
| 213 | - **Heuristic:** query performance is primarily data-shape and SQL-plan driven; ORM API choices should be evaluated by generated SQL and execution plans. |
| 214 | - **First adoption task:** audit top read queries for over-projection, missing pagination, and unnecessary tracking. |
| 215 | - **Success criterion:** reduced query latency and allocation for selected hot queries. |
| 216 | - **Confidence:** high |
| 217 | - *Source:* Microsoft Learn - EF Core efficient querying (`https://learn.microsoft.com/ef/core/performance/efficient-querying`) (2026-02-25) |
| 218 | |
| 219 | - **Fact:** smell taxonomy (bloaters, couplers, dispensables, change preventers, OOP abusers) provides a practical lens for refactoring prioritization. |
| 220 | - **Heuristic:** classify before changing; choose refactoring moves by smell class rather than ad-hoc stylistic edits. |
| 221 | - **First adoption task:** add lightweight PR-review smell tags (`duplicate code`, `long method`, `feature envy`, `shotgun surgery`) for changed files. |
| 222 | - **Success criterion:** recurring refactoring decisions become faster and more consistent. |
| 223 | - **Confidence:** medium |
| 224 | - *Source:* Refactoring.Guru - Code Smells (`https://refactoring.guru/refactoring/smells`) (2026-02-25) |
| 225 | |
| 226 | - **Fact:** pattern selection remains most effective when mapped to change pressure (creation flexibility, composition constraints, behavior variability). |
| 227 | - **Heuristic:** treat patterns as response to concrete forces, not as architecture defaults. |
| 228 | - **First adoption task:** for each new abstraction, require one-sentence force statement before introducing a pattern. |
| 229 | - **Success criterion:** lower accidental complexity from unnecessary abstractions. |
| 230 | - **Confidence:** medium |
| 231 | - *Source:* Refactoring.Guru - Design Patterns Catalog (`https://refactoring.guru/design-patterns/catalog`) (2026-02-25) |
| 232 | |
| 233 | - **Fact:** enterprise systems benefit from explicit pattern choices around domain logic, mapping, transactional boundaries, and integration seams. |
| 234 | - **Heuristic:** make data-access and domain-boundary patterns explicit in architecture docs to avoid hidden coupling drift. |
| 235 | - **First adoption task:** map current persistence strategy to EAA vocabulary (`Repository`, `Unit of Work`, `Data Mapper`) and document intent. |
| 236 | - **Success criterion:** clearer architectural communication and fewer contradictory implementations. |
| 237 | - **Confidence:** high |
| 238 | - *Source:* Martin Fowler - Patterns of Enterprise Application Architecture catalog (`https://martinfowler.com/eaaCatalog/`) (2026-02-25) |
| 239 | |
| 240 | - **Fact:** effective test portfolios prioritize many fast low-level tests, fewer integration tests, and very limited end-to-end tests. |
| 241 | - **Heuristic:** optimize for feedback speed and maintainability; avoid test-suite shape drift toward slow end-to-end-heavy layers. |
| 242 | - **First adoption task:** categorize existing tests by pyramid layer and identify overrepresented expensive layers. |
| 243 | - **Success criterion:** reduced end-to-end dependence and faster median CI cycle. |
| 244 | - **Confidence:** high |
| 245 | - *Source:* Martin Fowler - The Practical Test Pyramid (`https://martinfowler.com/articles/practical-test-pyramid.html`) (2026-02-25) |
| 246 | |
| 247 | --- |
| 248 | |
| 249 | ## C++ fundamentals for systems / numerical work |
| 250 | |
| 251 | - **Fact:** The C++ Core Guidelines codify modern C++ practices around RAII, value semantics, resource ownership, and type safety, and are explicitly written for C++11 and newer. |
| 252 | - **Heuristic:** treat the Core Guidelines as a *constraint set* for new C++ code: prefer value types and RAII (`std::unique_ptr`, `std::shared_ptr`) over raw `new/delete`, and keep exceptions for exceptional flow only. |
| 253 | - **First adoption task:** for any new C++ subsystem, pin a minimal subset of Core Guidelines (ownership, resource management, error-handling) as non-negotiable and document them next to the project. |
| 254 | - **Success criterion:** no raw `new/delete` in high-level code; clear ownership and lifetime semantics even for someone reading the code fresh. |
| 255 | - **Confidence:** medium |
| 256 | - *Source:* C++ Core Guidelines (`https://github.com/isocpp/CppCoreGuidelines`) (2026-03-10) |
| 257 | |
| 258 | - **Fact:** for numerical and systems code, layout and ownership of contiguous data (`std::vector`, `std::array`, plain buffers) matter more for performance than high-level container/API variety. |
| 259 | - **Heuristic:** design data structures for cache-friendliness first (SoA/packed arrays where appropriate), then add thin convenience APIs; avoid deep pointer graphs and polymorphic trees in hot numeric loops. |
| 260 | - **First adoption task:** in the first C++ numeric prototype, explicitly choose between AoS and SoA for the primary fields and document the choice with a short rationale. |
| 261 | - **Success criterion:** stable performance under profiling, no surprise regressions from allocator or container changes. |
| 262 | - **Confidence:** medium |
| 263 | - *Source:* engineering practice + NVIDIA and Intel optimization guides (consolidated reading, 2026-03-10) |
| 264 | |
| 265 | --- |
| 266 | |
| 267 | ## CUDA / GPU fundamentals |
| 268 | |
| 269 | - **Fact:** CUDA’s programming model is explicitly hierarchical: grids → blocks → threads, with a layered memory model (global, shared, local, constant, texture) and strong impact of memory access patterns on performance. |
| 270 | - **Heuristic:** always think in terms of *tiles* and *coalesced memory access* when designing kernels; choose block sizes and memory layouts that keep accesses aligned and contiguous per warp. |
| 271 | - **First adoption task:** for the first stencil / PDE kernel, design a simple tiling scheme on paper (block size, halo/ghost cells, shared memory usage) before writing code, and verify it against the CUDA C++ Programming Guide. |
| 272 | - **Success criterion:** no obvious bank-conflict or non-coalesced access patterns in the first working kernel when inspected with Nsight / profiler. |
| 273 | - **Confidence:** medium |
| 274 | - *Source:* NVIDIA CUDA C++ Programming Guide (`https://docs.nvidia.com/cuda/cuda-c-programming-guide/`) (2026-03-10) |
| 275 | |
| 276 | - **Fact:** branch divergence within a warp (threads taking different control paths) can severely reduce effective throughput; stencil-style kernels often admit branch-free or branch-minimized formulations. |
| 277 | - **Heuristic:** structure kernels so that interior vs boundary/BC handling is either separated into different kernels or guarded in ways that minimise divergence inside warps. |
| 278 | - **First adoption task:** in early GPU prototypes, keep one “interior-only” kernel (no branches) and a separate, slower BC kernel; compare their profiles and only merge if divergence cost is negligible. |
| 279 | - **Success criterion:** main compute kernel has minimal divergent branches per warp under profiler. |
| 280 | - **Confidence:** medium |
| 281 | - *Source:* NVIDIA CUDA C++ Programming Guide, sections on SIMT execution and control flow (2026-03-10) |
| 282 | |
| 283 | --- |
| 284 | |
| 285 | ## .NET ↔ GPU integration |
| 286 | |
| 287 | - **Fact:** .NET can target GPUs either via interop with native CUDA libraries (P/Invoke, C++/CLI wrappers) or via managed GPU frameworks such as ILGPU (JIT to CUDA/OpenCL) and similar libraries. |
| 288 | - **Heuristic:** for long-lived, performance-critical kernels, prefer native CUDA (C++/CUDA) with a thin, stable interop surface; use managed GPU frameworks primarily for rapid prototyping and where deployment constraints favour pure .NET. |
| 289 | - **First adoption task:** for the first GPU-backed project, define a clear split: IR/orchestration in .NET, kernels in a native CUDA library with a small, versioned C API. |
| 290 | - **Success criterion:** .NET side can evolve independently of kernel implementation details; GPU code is testable and profileable in isolation. |
| 291 | - **Confidence:** medium |
| 292 | - *Source:* vendor docs (ILGPU, ManagedCUDA) + engineering surveys (2026-03-10) |
| 293 | |
| 294 | --- |
| 295 | |
| 296 | ## GPU simulations playbook (preview) |
| 297 | |
| 298 | - **Fact:** successful GPU simulation projects treat “IR → kernel” as a compiled boundary with explicit invariants, rather than inlining math directly into kernels ad hoc. |
| 299 | - **Heuristic:** keep a clean separation between (1) problem description / IR, (2) rule / kernel generation, and (3) execution and profiling; each layer should be testable on its own. |
| 300 | - **First adoption task:** for the equation→CA→CUDA R&D project, write down a one-page IR contract and a list of invariants (e.g. conservation properties) before implementing the first kernel. |
| 301 | - **Success criterion:** ability to validate kernels against IR/invariants without re-deriving the math from the code every time. |
| 302 | - **Confidence:** medium |
| 303 | - *Source:* internal R&D planning for equation-to-ca-cuda (2026-03-10) |
| 304 | |
| 305 | - **Fact:** CQRS is situational; it can help in complex/high-scale bounded contexts but often introduces harmful complexity when applied broadly. |
| 306 | - **Heuristic:** apply CQRS only where read/write model divergence is proven by domain or scaling constraints. |
| 307 | - **First adoption task:** introduce architecture decision check requiring explicit bounded-context and complexity tradeoff when proposing CQRS. |
| 308 | - **Success criterion:** fewer premature split-model designs with weak justification. |
| 309 | - **Confidence:** high |
| 310 | - *Source:* Martin Fowler - CQRS (`https://martinfowler.com/bliki/CQRS.html`) (2026-02-25) |
| 311 | |
| 312 | |
| 313 | ## Data stores and resilience |
| 314 | |
| 315 | - **Fact:** deployment resilience and portability improve with strict config separation, stateless processes, and dev/prod parity discipline. |
| 316 | - **Heuristic:** delivery robustness should be encoded into runtime/process contracts, not left to operator convention. |
| 317 | - **First adoption task:** evaluate active services against 12-factor checklist and log highest-risk gaps. |
| 318 | - **Success criterion:** reduced environment-specific failures across local/stage/prod. |
| 319 | - **Confidence:** medium |
| 320 | - *Source:* Twelve-Factor App (`https://12factor.net/`) (2026-02-25) |
| 321 | |
| 322 | - **Fact:** index value comes from selectivity and planner statistics; indexing adds write overhead and must be justified by query workload. |
| 323 | - **Heuristic:** treat every index as a read/write tradeoff decision with maintenance cost. |
| 324 | - **First adoption task:** inventory frequently used indexes and remove low-value prefixes/duplicates. |
| 325 | - **Success criterion:** stable or improved query latency with no unnecessary index maintenance burden. |
| 326 | - **Confidence:** high |
| 327 | - *Source:* PostgreSQL docs - Index introduction (`https://www.postgresql.org/docs/current/indexes-intro.html`) (2026-02-25) |
| 328 | |
| 329 | - **Fact:** plan analysis requires comparing estimates vs actuals (`EXPLAIN ANALYZE`) and understanding join/scan node composition. |
| 330 | - **Heuristic:** SQL tuning should begin with plan literacy, not blind query rewrites. |
| 331 | - **First adoption task:** introduce plan-review template for critical queries (node type, row estimate error, dominant cost). |
| 332 | - **Success criterion:** faster root-cause isolation for slow query incidents. |
| 333 | - **Confidence:** high |
| 334 | - *Source:* PostgreSQL docs - Using EXPLAIN (`https://www.postgresql.org/docs/current/using-explain.html`) (2026-02-25) |
| 335 | |
| 336 | - **Fact:** multi-column and covering indexes materially reduce lookup/sort cost; index order strongly shapes planner effectiveness. |
| 337 | - **Heuristic:** index design must mirror real filter and ordering patterns. |
| 338 | - **First adoption task:** validate that mobile/embedded query patterns align with left-prefix and covering-index opportunities. |
| 339 | - **Success criterion:** lower scan/sort overhead in representative SQLite workloads. |
| 340 | - **Confidence:** medium |
| 341 | - *Source:* SQLite docs - Query planner (`https://sqlite.org/queryplanner.html`) (2026-02-25) |
| 342 | |
| 343 | - **Fact:** Redis latency spikes often originate from environment/OS constraints (intrinsic latency, THP, fork, swap, slow commands), not Redis core command cost alone. |
| 344 | - **Heuristic:** troubleshoot from infrastructure baseline upward before optimizing command-level logic. |
| 345 | - **First adoption task:** create Redis latency checklist (intrinsic latency, slowlog, THP, fork time, swap, AOF/fsync profile). |
| 346 | - **Success criterion:** quicker discrimination between infra-induced and workload-induced latency. |
| 347 | - **Confidence:** high |
| 348 | - *Source:* Redis docs - Diagnosing latency (`https://redis.io/docs/latest/operate/oss_and_stack/management/optimization/latency/`) (2026-02-25) |
| 349 | |
| 350 | - **Fact:** CQRS can improve scalability and boundary clarity but introduces synchronization and eventual-consistency complexity. |
| 351 | - **Heuristic:** adopt CQRS only with clear asymmetry in read/write requirements or explicit bounded-context complexity. |
| 352 | - **First adoption task:** require ADR section for consistency model and synchronization strategy in CQRS proposals. |
| 353 | - **Success criterion:** fewer architecture reversals caused by underestimated complexity. |
| 354 | - **Confidence:** high |
| 355 | - *Source:* Azure Architecture Center - CQRS pattern (`https://learn.microsoft.com/azure/architecture/patterns/cqrs`) (2026-02-25) |
| 356 | |
| 357 | |
| 358 | ## Architecture and fault isolation |
| 359 | |
| 360 | - **Fact:** robust retries depend on transient-fault classification, backoff strategy, idempotency guarantees, and bounded attempts. |
| 361 | - **Heuristic:** retries are reliability controls, not universal error handling. |
| 362 | - **First adoption task:** define per-dependency retry profiles (attempts, backoff, timeout, circuit-breaker interplay). |
| 363 | - **Success criterion:** fewer cascading failures and reduced tail-latency amplification under partial outages. |
| 364 | - **Confidence:** high |
| 365 | - *Source:* Azure Architecture Center - Retry pattern (`https://learn.microsoft.com/azure/architecture/patterns/retry`) (2026-02-25) |
| 366 | |
| 367 | - **Fact:** maintainable systems consistently rely on separation of concerns, encapsulation, dependency inversion, explicit dependencies, and bounded contexts. |
| 368 | - **Heuristic:** architecture quality improves when dependencies point toward abstractions and domain logic remains isolated from infrastructure/UI. |
| 369 | - **First adoption task:** add architecture review checklist for new modules (SoC, DIP, explicit dependencies, bounded context boundary). |
| 370 | - **Success criterion:** fewer cross-layer leaks and easier testability of business logic. |
| 371 | - **Confidence:** high |
| 372 | - *Source:* Microsoft Learn - Architectural principles (`https://learn.microsoft.com/dotnet/architecture/modern-web-apps-azure/architectural-principles`) (2026-02-25) |
| 373 | |
| 374 | - **Fact:** aggregate/domain invariants must be enforced in domain behavior, not delegated only to UI binding or persistence metadata. |
| 375 | - **Heuristic:** domain entities should be invalid-state resistant by construction and mutation methods. |
| 376 | - **First adoption task:** review aggregate roots for invariant enforcement in constructors/mutators and close annotation-only validation gaps. |
| 377 | - **Success criterion:** invalid domain state cannot be persisted through normal code paths. |
| 378 | - **Confidence:** high |
| 379 | - *Source:* Microsoft Learn - Domain model validations (`https://learn.microsoft.com/dotnet/architecture/microservices/microservice-ddd-cqrs-patterns/domain-model-layer-validations`) (2026-02-25) |
| 380 | |
| 381 | - **Fact:** circuit breakers mitigate persistent or slow-recovery dependencies through closed/open/half-open state transitions and controlled probes. |
| 382 | - **Heuristic:** retries should be bounded by breaker state; fallback behavior must be explicit for degraded mode. |
| 383 | - **First adoption task:** define breaker policy per critical dependency (trip threshold, open duration, half-open probe count, fallback contract). |
| 384 | - **Success criterion:** reduced cascading failure during dependency outages. |
| 385 | - **Confidence:** high |
| 386 | - *Source:* Azure Architecture Center - Circuit Breaker (`https://learn.microsoft.com/azure/architecture/patterns/circuit-breaker`) (2026-02-25) |
| 387 | |
| 388 | - **Fact:** unit tests are fundamentally about fast feedback on small scopes; sociable vs solitary style is contextual, but speed and frequency are key. |
| 389 | - **Heuristic:** tune test suites for feedback cadence (compile suite and commit suite) rather than ideological purity. |
| 390 | - **First adoption task:** define runtime budget targets for local and CI test suites and classify tests by intended feedback loop. |
| 391 | - **Success criterion:** developers run tests frequently without friction and detect regressions earlier. |
| 392 | - **Confidence:** high |
| 393 | - *Source:* Martin Fowler - Unit Test (`https://martinfowler.com/bliki/UnitTest.html`) (2026-02-25) |
| 394 | |
| 395 | - **Fact:** behavior-verification mocks and state-verification doubles serve different purposes; misuse increases coupling or obscures failures. |
| 396 | - **Heuristic:** choose doubles intentionally by collaboration risk (determinism, speed, boundary awkwardness), not by framework habit. |
| 397 | - **First adoption task:** add test review guidance distinguishing mock/stub/fake usage and expected verification mode. |
| 398 | - **Success criterion:** lower test brittleness and clearer failure diagnostics. |
| 399 | - **Confidence:** medium |
| 400 | - *Source:* Martin Fowler - Mocks Aren't Stubs (`https://martinfowler.com/articles/mocksArentStubs.html`) (2026-02-25) |
| 401 | |
| 402 | |
| 403 | ## Algorithms, reliability, security |
| 404 | |
| 405 | - **Fact:** speculative features impose build cost, delay cost, and carry cost; only malleable codebases can safely defer features. |
| 406 | - **Heuristic:** avoid presumptive abstractions unless immediate value is clear and complexity is near-zero. |
| 407 | - **First adoption task:** require explicit justification for "future-proofing" code in PRs/ADRs. |
| 408 | - **Success criterion:** reduced accidental complexity and faster delivery of current-value features. |
| 409 | - **Confidence:** high |
| 410 | - *Source:* Martin Fowler - YAGNI (`https://martinfowler.com/bliki/Yagni.html`) (2026-02-25) |
| 411 | |
| 412 | - **Fact:** practical algorithm competence depends on fluency across core chapters: fundamentals, sorting, searching, graphs, strings, and context-driven applications. |
| 413 | - **Heuristic:** treat DS/A as an operational toolkit; map each production bottleneck to one or two candidate algorithm families before optimizing code. |
| 414 | - **First adoption task:** add "algorithm choice" section to performance investigations (data shape, operation complexity, memory tradeoff, expected scale). |
| 415 | - **Success criterion:** fewer ad-hoc optimizations and clearer complexity reasoning in design reviews. |
| 416 | - **Confidence:** high |
| 417 | - *Source:* Sedgewick/Wayne Algorithms, 4th edition site (`https://algs4.cs.princeton.edu/home/`) (2026-02-25) |
| 418 | |
| 419 | - **Fact:** strong algorithm engineering links mathematical modeling, asymptotic analysis, and implementation constraints in one loop. |
| 420 | - **Heuristic:** validate algorithmic decisions with both proof-level complexity expectations and empirical benchmarks on realistic workloads. |
| 421 | - **First adoption task:** include one theoretical bound and one measured benchmark for each non-trivial algorithmic change. |
| 422 | - **Success criterion:** architecture decisions retain both analytical justification and runtime evidence. |
| 423 | - **Confidence:** high |
| 424 | - *Source:* MIT OCW 6.006 Introduction to Algorithms (`https://ocw.mit.edu/courses/6-006-introduction-to-algorithms-spring-2020/`) (2026-02-25) |
| 425 | |
| 426 | - **Fact:** indexing is fundamentally a development-time concern; query shape, predicate form, and pagination strategy dominate SQL performance outcomes. |
| 427 | - **Heuristic:** design indexes from real query patterns (filter + sort + join), then verify plan behavior instead of relying on default ORM generation. |
| 428 | - **First adoption task:** capture top query patterns and align index strategy (covering/composite/partial) with execution plans. |
| 429 | - **Success criterion:** improved p95 query latency with controlled write overhead. |
| 430 | - **Confidence:** high |
| 431 | - *Source:* Use The Index, Luke (`https://use-the-index-luke.com/`) (2026-02-25) |
| 432 | |
| 433 | - **Fact:** reliability at scale is a coherent practice stack (SLOs, alerting, on-call, incident response, postmortems, toil reduction, release engineering). |
| 434 | - **Heuristic:** treat reliability as a product loop, not as isolated incident handling. |
| 435 | - **First adoption task:** define minimal reliability operating model for active services (SLO, alert policy, incident template, postmortem cadence). |
| 436 | - **Success criterion:** clearer operational ownership and faster recovery cycles. |
| 437 | - **Confidence:** medium |
| 438 | - *Source:* Google SRE Book TOC (`https://sre.google/sre-book/table-of-contents/`) (2026-02-25) |
| 439 | |
| 440 | - **Fact:** OWASP Top 10 remains a baseline security awareness standard; current reference line points to 2025 update with structured data-driven process. |
| 441 | - **Heuristic:** secure coding baselines should be integrated into development workflow (threat review, code review, dependency and input handling checks). |
| 442 | - **First adoption task:** establish Top-10-mapped secure coding checklist for PR review and test scenarios. |
| 443 | - **Success criterion:** earlier detection of common web security risk classes before release. |
| 444 | - **Confidence:** medium |
| 445 | - *Source:* OWASP Top 10 project (`https://owasp.org/www-project-top-ten/`) (2026-02-25) |
| 446 | |
| 447 | |
| 448 | ## Reliability and delivery |
| 449 | |
| 450 | - **Fact:** debt is useful as a decision metaphor only when teams explicitly reason about interest vs principal and pay down high-interest hotspots progressively. |
| 451 | - **Heuristic:** prioritize debt repayment in high-change areas where interest compounds fastest. |
| 452 | - **First adoption task:** add technical debt annotation to backlog items with "interest signal" (change frequency, cycle delay, defect amplification). |
| 453 | - **Success criterion:** reduced delivery slowdown in frequently modified modules. |
| 454 | - **Confidence:** high |
| 455 | - *Source:* Martin Fowler - Technical Debt (`https://martinfowler.com/bliki/TechnicalDebt.html`) (2026-02-25) |
| 456 | |
| 457 | - **Fact:** reliability can be operationalized as a concrete control loop: flow criticality, failure-mode analysis, target metrics, resiliency tests, BCDR, and monitoring strategy. |
| 458 | - **Heuristic:** treat reliability as a checklist-backed engineering discipline, not an ad-hoc incident reaction. |
| 459 | - **First adoption task:** run RE:01-RE:08 checklist against one active service and record gaps as prioritized backlog items. |
| 460 | - **Success criterion:** visible reduction of unknown failure modes and clearer recovery playbooks. |
| 461 | - **Confidence:** high |
| 462 | - *Source:* Azure Well-Architected - Reliability checklist (`https://learn.microsoft.com/power-platform/well-architected/reliability/checklist#checklist`) (2026-02-25) |
| 463 | |
| 464 | - **Fact:** stable delivery quality is driven by standardized development practices, IaC, automated supply chain, observability, and structured incident management. |
| 465 | - **Heuristic:** optimize process reliability through explicit standards and automation-first execution. |
| 466 | - **First adoption task:** introduce OE checklist review for pipeline/tooling decisions (OE:01..OE:08). |
| 467 | - **Success criterion:** fewer release surprises and faster incident triage under change. |
| 468 | - **Confidence:** high |
| 469 | - *Source:* Azure Well-Architected - Operational Excellence checklist (`https://learn.microsoft.com/azure/well-architected/operational-excellence/checklist#checklist`) (2026-02-25) |
| 470 | |
| 471 | - **Fact:** .NET observability architecture is natively aligned around ILogger + Meter + ActivitySource, with OTel SDK used for collection/export and vendor-neutral telemetry flow. |
| 472 | - **Heuristic:** instrument once using platform APIs and keep backend choice decoupled through OTel exporters/protocols. |
| 473 | - **First adoption task:** standardize application instrumentation baseline (logs/metrics/traces) for all new services. |
| 474 | - **Success criterion:** consistent cross-service diagnostics with minimal vendor lock-in. |
| 475 | - **Confidence:** high |
| 476 | - *Source:* .NET observability with OpenTelemetry (`https://learn.microsoft.com/dotnet/core/diagnostics/observability-with-otel`) (2026-02-25) |
| 477 | |
| 478 | - **Fact:** liveness/readiness separation, dependency probes, and orchestrator-integrated endpoints are core to reliable service operation. |
| 479 | - **Heuristic:** health endpoints should represent operational truth (startup readiness, dependency health, degraded behavior) rather than a single binary ping. |
| 480 | - **First adoption task:** define `/healthz` + readiness endpoint policy and dependency probe tags for active APIs. |
| 481 | - **Success criterion:** fewer false-positive restarts and more accurate traffic routing during partial failures. |
| 482 | - **Confidence:** high |
| 483 | - *Source:* ASP.NET Core health checks (`https://learn.microsoft.com/aspnet/core/host-and-deploy/health-checks?view=aspnetcore-10.0`) (2026-02-25) |
| 484 | |
| 485 | - **Fact:** repeatable CI in .NET should center on workflow files with setup-dotnet + restore/build/test stages and explicit secret handling. |
| 486 | - **Heuristic:** pipeline quality depends on deterministic workflow composition, not just successful ad-hoc command runs. |
| 487 | - **First adoption task:** validate each .NET repo has a minimal build+test workflow with pinned SDK strategy and status badge. |
| 488 | - **Success criterion:** reliable CI signal for every PR and lower integration regressions. |
| 489 | - **Confidence:** high |
| 490 | - *Source:* GitHub Actions and .NET (`https://learn.microsoft.com/dotnet/devops/github-actions-overview`) + build/test quickstart (`https://learn.microsoft.com/dotnet/devops/dotnet-test-github-action`) (2026-02-25) |
| 491 | |
| 492 | |
| 493 | ## Compilers and language tooling |
| 494 | |
| 495 | - **Fact:** delivery improvement should be measured with outcome metrics such as lead time, deployment frequency, change fail rate, and time to restore service. |
| 496 | - **Heuristic:** use DORA-like metrics as feedback on engineering system health, not as isolated team scorekeeping. |
| 497 | - **First adoption task:** define baseline collection for 4 delivery metrics across at least one primary product stream. |
| 498 | - **Success criterion:** measurable trend visibility for delivery reliability and recovery performance. |
| 499 | - **Confidence:** medium |
| 500 | - *Source:* Platform Engineering planning guidance (DORA metrics mention) (`https://learn.microsoft.com/platform-engineering/plan#measure-success-and-proving-value`) (2026-02-25) |
| 501 | |
| 502 | - **Fact:** Dragon Book remains the canonical reference for the full compiler chain: lexical analysis, parsing, semantic analysis, intermediate representation, optimization, and code generation. |
| 503 | - **Heuristic:** treat compiler construction as a pipeline with explicit contracts between stages, not as a monolithic parser task. |
| 504 | - **First adoption task:** maintain a stage-by-stage architecture template for any language tooling project (tokens -> AST -> typed AST -> IR -> optimized IR -> target code). |
| 505 | - **Success criterion:** easier debugging and replacement of individual compiler stages without global rewrites. |
| 506 | - **Confidence:** medium |
| 507 | - *Source:* Dragon Book overview (`https://en.wikipedia.org/wiki/Compilers:_Principles,_Techniques,_and_Tools`) (2026-02-25) |
| 508 | |
| 509 | - **Fact:** companion resources (errata, appendix source code, course links like Stanford CS143/MIT 6.035) are essential for grounding textbook theory in implementable artifacts. |
| 510 | - **Heuristic:** pair foundational texts with verified companion artifacts to avoid conceptual drift and outdated interpretations. |
| 511 | - **First adoption task:** create a compiler-study checklist that requires "theory chapter + companion artifact + runnable micro-implementation". |
| 512 | - **Success criterion:** reduced gap between conceptual understanding and executable implementation. |
| 513 | - **Confidence:** high |
| 514 | - *Source:* Dragon Book companion site (`https://suif.stanford.edu/dragonbook/`) (2026-02-25) |
| 515 | |
| 516 | - **Fact:** modern compiler workflows are effectively IR-first; early transition to LLVM IR enables optimization/JIT/object generation with reusable backend infrastructure. |
| 517 | - **Heuristic:** when building DSL/tooling, minimize custom backend work by targeting a mature IR ecosystem as early as possible. |
| 518 | - **First adoption task:** prototype one minimal expression language that emits LLVM IR before adding advanced syntax. |
| 519 | - **Success criterion:** working end-to-end prototype with measurable compile/execute loop and extensible backend path. |
| 520 | - **Confidence:** high |
| 521 | - *Source:* LLVM Kaleidoscope tutorial (`https://llvm.org/docs/tutorial/`) (2026-02-25) |
| 522 | |
| 523 | - **Fact:** language engineering competence requires both interpreter path (tree-walk clarity) and VM path (bytecode/runtime performance and GC realities). |
| 524 | - **Heuristic:** sequence learning and implementation in two passes: semantic clarity first, runtime efficiency second. |
| 525 | - **First adoption task:** for new language experiments, implement interpreter baseline before introducing bytecode/VM optimizations. |
| 526 | - **Success criterion:** faster correctness convergence and fewer premature performance abstractions. |
| 527 | - **Confidence:** high |
| 528 | - *Source:* Crafting Interpreters contents (`https://craftinginterpreters.com/contents.html`) (2026-02-25) |
| 529 | |
| 530 | - **Fact:** the strongest practical model is a three-layer lens: formal compiler theory (Dragon), industrial IR/toolchain integration (LLVM), and runtime ergonomics (Crafting Interpreters). |
| 531 | - **Heuristic:** evaluate design decisions by asking three questions: is it formally sound, is it toolchain-compatible, and is it runtime-maintainable? |
| 532 | - **First adoption task:** introduce this 3-lens review as a mandatory section in language-tooling ADRs. |
| 533 | - **Success criterion:** fewer dead-end architecture choices in parser/IR/runtime evolution. |
| 534 | - **Confidence:** medium |
| 535 | - *Source:* Dragon Book + LLVM + Crafting Interpreters synthesis (2026-02-25) |
| 536 | |
| 537 | |
| 538 | ## F# and interop |
| 539 | |
| 540 | - **Fact:** Dragon Book is foundational but dense; retention improves when each chapter is converted into one executable artifact and one "error-class map". |
| 541 | - **Heuristic:** convert each studied compiler topic into "buildable toy + failure taxonomy" rather than passive notes. |
| 542 | - **First adoption task:** start chapter-to-artifact backlog (lexer DFA, precedence parser, type checker, SSA transform, local optimizer, codegen pass). |
| 543 | - **Success criterion:** ability to answer design questions with concrete prototypes instead of abstract recollection. |
| 544 | - **Confidence:** high |
| 545 | - *Source:* Dragon Book learning adoption note (2026-02-25) |
| 546 | |
| 547 | |
| 548 | ## OS and runtime environments |
| 549 | |
| 550 | - **Fact:** large-scale F# remains maintainable when code is organized with explicit namespace/module boundaries, restrained point-free style, and interoperability-aware API shape. |
| 551 | - **Heuristic:** optimize for readability/tooling/debuggability first; compactness is valuable only when it preserves clarity. |
| 552 | - **First adoption task:** define team-level F# conventions (namespace-first organization, RequireQualifiedAccess policy, public API naming and argument labels). |
| 553 | - **Success criterion:** reduced onboarding/debug friction for mixed-skill teams. |
| 554 | - **Confidence:** high |
| 555 | - *Source:* F# style guide (`https://learn.microsoft.com/dotnet/fsharp/style-guide/`) + coding conventions (`https://learn.microsoft.com/dotnet/fsharp/style-guide/conventions`) (2026-02-25) |
| 556 | |
| 557 | - **Fact:** core OS guarantees are built around process isolation, virtual memory, scheduling policy, and explicit synchronization contracts; most production failures map to one of these boundaries. |
| 558 | - **Heuristic:** classify environment incidents by boundary first (process/memory/scheduler/IO/sync) before selecting tools. |
| 559 | - **First adoption task:** add boundary tag to every OS-related incident note in active projects. |
| 560 | - **Success criterion:** faster root-cause triage and fewer tool-selection detours. |
| 561 | - **Confidence:** medium |
| 562 | - *Source:* Operating System Concepts (Silberschatz/Galvin/Gagne) (2026-03-01) |
| 563 | |
| 564 | - **Fact:** different OS families optimize different tradeoffs (throughput, fairness, latency, isolation), so observed behavior can differ even with identical app code. |
| 565 | - **Heuristic:** treat cross-platform divergence as expected architectural variance, not as random anomaly. |
| 566 | - **First adoption task:** extend troubleshooting checklists with explicit OS-tradeoff questions (latency vs throughput vs isolation). |
| 567 | - **Success criterion:** fewer "mystery" discrepancies between Windows and Linux runs. |
| 568 | - **Confidence:** medium |
| 569 | - *Source:* Modern Operating Systems (Tanenbaum/Bos) (2026-03-01) |
| 570 | |
| 571 | - **Fact:** Linux runtime reliability depends on correct assumptions about file descriptors, signals, process groups, and resource limits. |
| 572 | - **Heuristic:** verify descriptor/signal/limit state early in Linux incidents before deep app-level debugging. |
| 573 | - **First adoption task:** add a standard Linux incident probe set (process tree, open files, limits, signal behavior). |
| 574 | - **Success criterion:** reduced time-to-first-valid-cause in Linux production incidents. |
| 575 | - **Confidence:** medium |
| 576 | - *Source:* The Linux Programming Interface (Kerrisk) (2026-03-01) |
| 577 | |
| 578 | - **Fact:** robust process supervision and IPC behavior require explicit lifecycle contracts; implicit assumptions around forks/exec/waits often cause unstable orchestration. |
| 579 | - **Heuristic:** model service startup/shutdown and child-process ownership explicitly in ops-sensitive components. |
| 580 | - **First adoption task:** audit one worker/service path for lifecycle ownership and shutdown correctness. |
| 581 | - **Success criterion:** deterministic stop/restart behavior with no orphaned subprocesses. |
| 582 | - **Confidence:** medium |
| 583 | - *Source:* Advanced Programming in the UNIX Environment (Stevens/Rago) (2026-03-01) |
| 584 | |
| 585 | - **Fact:** Windows behavior in services/security/performance incidents is strongly shaped by token/ACL/session mechanics and kernel object semantics. |
| 586 | - **Heuristic:** in Windows incidents, verify account/token/ACL context before application logic assumptions. |
| 587 | - **First adoption task:** add a Windows service-context checklist (identity, ACL, policy, startup account permissions). |
| 588 | - **Success criterion:** fewer false diagnoses caused by hidden security-context mismatch. |
| 589 | - **Confidence:** medium |
| 590 | - *Source:* Windows Internals (Russinovich et al.) (2026-03-01) |
| 591 | |
| 592 | - **Fact:** environment reliability is maintained by explicit operational contracts (service definitions, logging routes, backup/recovery routines, change discipline), not by ad-hoc admin actions. |
| 593 | - **Heuristic:** promote "ops as documented contract" for all recurring environment procedures. |
| 594 | - **First adoption task:** convert one recurring environment fix into a repeatable runbook entry with validation criteria. |
| 595 | - **Success criterion:** same issue resolved consistently by different operators/agents. |
| 596 | - **Confidence:** high |
| 597 | - *Source:* UNIX and Linux System Administration Handbook (Nemeth et al.) (2026-03-01) |
| 598 | |
| 599 | - **Fact:** for cross-language APIs, F# internals can be idiomatic while public boundaries should feel natural to C# (.NET method shape, stable DTO types, avoid exposing curried signatures and opaque unions directly). |
| 600 | - **Heuristic:** design .NET-facing contracts in C#-friendly form and keep F# expressiveness behind the boundary. |
| 601 | - **First adoption task:** adopt "interop boundary" rule: public contracts verified from C# usage examples before acceptance. |
| 602 | - **Success criterion:** predictable consumption from C# with fewer adapter layers. |
| 603 | - **Confidence:** high |
| 604 | - *Source:* F# component design guidelines (`https://learn.microsoft.com/dotnet/fsharp/style-guide/component-design-guidelines`) (2026-02-25) |
| 605 | |
| 606 | - **Fact:** F# async workflows are compositional and concise; task expressions are preferred at heavy .NET Task interop boundaries and can directly await Task/ValueTask/Async. |
| 607 | - **Heuristic:** default to `async` for internal orchestration, use `task` at API edges where C#/.NET task semantics are the primary contract. |
| 608 | - **First adoption task:** codify async policy in architecture docs (internal async model vs external task model, conversion points via AwaitTask/StartAsTask). |
| 609 | - **Success criterion:** fewer async interop bugs and clearer cancellation/await behavior. |
| 610 | - **Confidence:** high |
| 611 | - *Source:* Async programming in F# (`https://learn.microsoft.com/dotnet/fsharp/tutorials/async`) + async expressions (`https://learn.microsoft.com/dotnet/fsharp/language-reference/async-expressions`) + task expressions (`https://learn.microsoft.com/dotnet/fsharp/language-reference/task-expressions`) (2026-02-25) |
| 612 | |
| 613 | - **Fact:** type providers enable schema-driven, strongly typed integration for external structured data; this is highly aligned with portal/IM ingestion layers. |
| 614 | - **Heuristic:** use type providers for exploratory or adapter layers where schema fidelity is critical; isolate provider usage behind stable domain transformations. |
| 615 | - **First adoption task:** pilot one ingestion adapter (e.g., CSV/XML/JSON) using FSharp.Data type provider mapped to canonical domain records. |
| 616 | - **Success criterion:** lower runtime parsing failures and faster evolution with schema changes. |
| 617 | - **Confidence:** medium |
| 618 | - *Source:* Type providers overview (`https://learn.microsoft.com/dotnet/fsharp/tutorials/type-providers/`) + FSharp.Data docs via Context7 (`/fsprojects/fsharp.data`) (2026-02-25) |
| 619 | |
| 620 | |
| 621 | ## Cloud, economics, scale |
| 622 | |
| 623 | - **Fact:** Microsoft positions F# as robust, performant, and interoperable with C# in mixed-language solutions, with active community/compiler evolution. |
| 624 | - **Heuristic:** for complex domain transformation and validation pipelines, F# + C# hybrid architecture is a strategic fit, not an edge-case compromise. |
| 625 | - **First adoption task:** define language ownership map per service layer (F# for domain transformation/validation passes, C# for mainstream host/API/UI integration). |
| 626 | - **Success criterion:** better leverage of each language without architectural fragmentation. |
| 627 | - **Confidence:** high |
| 628 | - *Source:* .NET language strategy - F# (`https://learn.microsoft.com/dotnet/fundamentals/languages#f`) (2026-02-25) |
| 629 | |
| 630 | - **Fact:** delivery performance and reliability should be evaluated together (throughput + stability), with evolving interpretation of restoration/rework dimensions. |
| 631 | - **Heuristic:** avoid single-metric optimization; make release decisions on a balanced reliability-speed profile. |
| 632 | - **First adoption task:** add DORA-style dashboard slice to active delivery stream reviews. |
| 633 | - **Success criterion:** fewer conflicting decisions between speed and stability goals. |
| 634 | - **Confidence:** medium |
| 635 | - *Source:* DORA 2024 report (`https://dora.dev/research/2024/dora-report/`) (2026-03-01) |
| 636 | |
| 637 | - **Fact:** cloud governance matures when spend is mapped to business units and operated as continuous collaboration loop. |
| 638 | - **Heuristic:** architecture economics should be tracked per business capability, not only as aggregate infrastructure cost. |
| 639 | - **First adoption task:** define one unit-economics metric for a critical capability and publish ownership. |
| 640 | - **Success criterion:** cost changes become interpretable in business terms. |
| 641 | - **Confidence:** high |
| 642 | - *Source:* FinOps Framework overview + unit economics (`https://learn.microsoft.com/en-us/cloud-computing/finops/framework/finops-framework`, `https://www.finops.org/framework/capabilities/unit-economics/`) (2026-03-01) |
| 643 | |
| 644 | - **Fact:** sustainable reliability requires toil budgeting and burn-rate-based SLO alerting rather than ad-hoc threshold paging. |
| 645 | - **Heuristic:** protect engineering capacity by converting repetitive operational load into automation backlog. |
| 646 | - **First adoption task:** classify top repetitive ops tickets and create first automation candidates. |
| 647 | - **Success criterion:** measurable reduction in repetitive manual incidents. |
| 648 | - **Confidence:** high |
| 649 | - *Source:* Google SRE workbook - eliminating toil + alerting on SLOs (`https://sre.google/workbook/eliminating-toil/`, `https://sre.google/workbook/alerting-on-slos/`) (2026-03-01) |
| 650 | |
| 651 | - **Fact:** cost optimization is design-time discipline (consumption model, attribution, efficiency measurement), not post-hoc trimming. |
| 652 | - **Heuristic:** require cost impact notes in architecture options before implementation. |
| 653 | - **First adoption task:** include cost design principles section in ADR template. |
| 654 | - **Success criterion:** fewer expensive architecture reversals. |
| 655 | - **Confidence:** high |
| 656 | - *Source:* AWS Well-Architected Cost Optimization principles (`https://docs.aws.amazon.com/wellarchitected/2023-04-10/framework/cost-dp.html`) (2026-03-01) |
| 657 | |
| 658 | - **Fact:** platform reliability is enforceable through measurable control points (component SLIs, disruption budgets). |
| 659 | - **Heuristic:** separate platform-level objectives from application-level objectives to avoid blurred accountability. |
| 660 | - **First adoption task:** document one workload disruption budget with expected availability impact. |
| 661 | - **Success criterion:** fewer avoidable outages during maintenance/rollouts. |
| 662 | - **Confidence:** medium |
| 663 | - *Source:* Kubernetes SLI metrics + disruption budgets (`https://kubernetes.io/docs/reference/instrumentation/slis/`, `https://v1-32.docs.kubernetes.io/docs/tasks/run-application/configure-pdb`) (2026-03-01) |
| 664 | |
| 665 | - **Fact:** observability quality and cost are strongly influenced by cardinality controls and view-level aggregation choices. |
| 666 | - **Heuristic:** design telemetry with signal budget constraints from day one. |
| 667 | - **First adoption task:** define forbidden high-cardinality metric attributes for default instrumentation. |
| 668 | - **Success criterion:** stable telemetry cost with preserved incident diagnosability. |
| 669 | - **Confidence:** medium |
| 670 | - *Source:* OpenTelemetry metrics SDK spec (`https://opentelemetry.io/docs/specs/otel/metrics/sdk`) (2026-03-01) |
| 671 | |
| 672 | |
| 673 | |