77 lines
6.5 KiB
Markdown
77 lines
6.5 KiB
Markdown
# 1. ARCHITECTURE_CONSTITUTION.md
|
||
|
||
## 1.1 Назначение
|
||
|
||
Этот документ — краткий набор законов репозитория и production-архитектуры. Он выше обычных task packets, примеров и локальных README. Codex не является архитектурным authority: он реализует только то, на что выдана task authority.
|
||
|
||
## 1.2 Иерархия архитектурной власти
|
||
|
||
1. Architecture Constitution.
|
||
2. Accepted ADR / Foundation Decision.
|
||
3. Machine-readable Architecture Registry.
|
||
4. Versioned semantic contracts and state machines.
|
||
5. Module architecture specification.
|
||
6. Codex Task Packet.
|
||
7. Implementation and examples.
|
||
|
||
Если нижний уровень противоречит верхнему, нижний считается ошибочным. Существующий код является evidence of implementation, но не authority to redefine architecture.
|
||
|
||
## 1.3 Неприкосновенные инварианты V1
|
||
|
||
1. LLM/model/provider не является Assistant.
|
||
2. Capability не означает Authority.
|
||
3. Observation, Claim, Belief, Prediction, Action и Outcome — разные семантические классы.
|
||
4. Model output никогда напрямую не мутирует canonical semantic state и не выполняет external mutation.
|
||
5. Любая реальная мутация проходит Proposal → semantic owner validation → Authority/Integrity checks → Commit → Executor → Outcome/Verification.
|
||
6. Любая executable activity имеет live justification path к действующей Goal, Commitment, Responsibility или Policy.
|
||
7. Отмена/суперсессия justification должна распространяться до зависимых работ перед следующим commit.
|
||
8. Canonical owner — один на конкретный mutable semantic state в конкретной semantic generation.
|
||
9. Другие модули не пишут canonical storage владельца напрямую.
|
||
10. Cross-owner SQL writes, cross-owner FK и скрытая cross-owner trigger logic запрещены по умолчанию.
|
||
11. Derived projections/caches/indexes не являются source of truth и должны быть rebuildable либо явно classified otherwise.
|
||
12. Temporal/NATS/Redis/vector index/model memory не являются единственным местом хранения commitments, authority, semantic history или future obligations.
|
||
13. Durable future obligations живут в canonical prospective state независимо от workflow/scheduler engine.
|
||
14. External side effect должен быть idempotent/reconcilable; timeout не равен failure; UNKNOWN_OUTCOME — first-class state.
|
||
15. No correctness property may depend on a shared in-process lock across bounded modules.
|
||
16. Semantic topology, process topology, storage topology и model topology независимы и меняются отдельно.
|
||
17. Co-location — deployment optimization, не архитектурная привилегия.
|
||
18. Major bounded contracts должны быть serializable и не зависеть от Go pointers, shared memory, global variables или ambient process state.
|
||
19. Core/domain не импортирует PostgreSQL/NATS/Temporal/MCP/model-provider packages.
|
||
20. Никакого giant `common/shared` domain package; technical shared mechanisms допускаются только в `platform` и не владеют domain semantics.
|
||
21. Semantic duplication предпочтительнее ложной абстракции.
|
||
22. Event-driven взаимодействие используется ради temporal decoupling/history, а не потому, что два модуля разные.
|
||
23. Public query не должен скрыто изменять canonical state.
|
||
24. Durable background responsibility не реализуется unmanaged goroutine/timer.
|
||
25. `context.Context` не переносит скрытый user/scope/authority/task state; это явные typed fields.
|
||
26. Unknown/Conflict/NotApplicable/NotObserved не схлопываются в nil/false/default.
|
||
27. Type system, package visibility, DB ACL и CI должны делать критические ошибки невозможными там, где это возможно.
|
||
28. Architecture guardrails themselves are protected and cannot validate their own weakening alone.
|
||
29. Codex ordinary feature task не меняет Constitution, Architecture Registry, public semantic topology, guardrails или canonical ownership без отдельного approved change.
|
||
30. Codex может завершить задачу typed gap (`BLOCKED_BY_SPEC_GAP`, `BLOCKED_BY_ARCHITECTURE_GAP`) вместо архитектурного обхода.
|
||
31. Every persistent thing has lifecycle, owner/justification, stop/retirement path and recovery semantics appropriate to criticality.
|
||
32. Historical meaning is not rewritten by current interpretation; corrections/supersessions are appended/versioned.
|
||
33. Newer/stronger model never automatically receives broader authority.
|
||
34. More intelligence, more code, more services or more automations are not goals themselves.
|
||
35. KEEP/WAIT/DO_NOTHING are valid decisions.
|
||
36. The system must remain recoverable, exportable and replaceable.
|
||
|
||
## 1.4 Codex-specific hard prohibitions
|
||
|
||
- No direct cross-module DB access “temporarily”.
|
||
- No cross-schema JOIN as application dependency between canonical owners.
|
||
- No direct provider/model call outside Cognitive Gateway/adapters.
|
||
- No external mutation outside Commit/Executor path.
|
||
- No generic `SaveEntity(any)`, `Invoke(any)`, global Service Locator or God Context.
|
||
- No semantic side effects in Go package `init()`.
|
||
- No semantic durable timers using `time.After`/sleep in request process.
|
||
- No production semantic behavior hidden only in middleware, SQL trigger or YAML DSL.
|
||
- No silent retry of ambiguous external mutation.
|
||
- No weakening of architecture/security tests inside unrelated feature task.
|
||
- No new third-party dependency, canonical table, integration contract or privileged secret access without declared change classification.
|
||
|
||
## 1.5 Core change rule
|
||
|
||
Change the lowest layer that eliminates the causal class of the problem. Escalate only when necessary:
|
||
|
||
`data/config → local implementation → skill/strategy → module contract → ownership/schema → architecture → constitutional invariant`.
|