Assistant/architecture/ARCHITECTURE_CONSTITUTION.md

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.