Skip to content

Commit ad8a688

Browse files
authored
Update ARCHITECTURE.md (#461)
1 parent 74da08f commit ad8a688

File tree

1 file changed

+134
-136
lines changed

1 file changed

+134
-136
lines changed

docs/ARCHITECTURE.md

Lines changed: 134 additions & 136 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,16 @@
11
# Trinity S³AI DNA Architecture
22

3-
> **Trinity Identity**: `φ² + 1/φ² = 3`одно уравнение связывает математику, архитектуру мозга и язык Trinity.
3+
> **Trinity Identity**: `φ² + 1/φ² = 3`a single equation links mathematics, brain architecture, and the Trinity language.
44
55
## Overview
66

7-
Trinity S³AI (Science-Structure-System AI) строится на **трёх переплетённых Strand** — каждый критичен для системы, но не может существовать без других двух.
8-
9-
| Strand | Роль | Код | Связи |
10-
|--------|------|-----|--------|
11-
| **I: Mathematical Foundation** | `src/tri/math/` | Священные константы, формулы, VSA |
12-
| **II: Cognitive Architecture** | `src/brain/` | Нейроанатомическая карта, исполнительные функции |
13-
| **III: Language & Hardware Bridge** | `src/tri/` + `fpga/` | TRI-27 язык, FPGA бэкенды |
7+
Trinity S³AI (Science-Structure-System AI) is built on **three intertwined Strands** — each is critical to the system, but cannot exist without the other two.
148

9+
| Strand | Role | Code | Relationships |
10+
|--------|------|--------|
11+
| **I: Mathematical Foundation** | `src/tri/math/` | Sacred constants, formulas, VSA |
12+
| **II: Cognitive Architecture** | `src/brain/` | Neuroanatomical map, executive functions |
13+
| **III: Language & Hardware Bridge** | `src/tri/` + `fpga/` | TRI-27 language, FPGA backends |
1514
```
1615
Strand I (Math)
1716
@@ -26,198 +25,197 @@ Strand III (Language + Hardware)
2625
φ² + 1/φ² = 3 = TRINITY
2726
```
2827

29-
Эта формула — **архитектурный инвариант** Trinity:
30-
- Математика: `V = n × 3^k × π^m × φ^p × e^q` в `src/tri/math/formula.zig`
31-
- Константы: 75+ священных значений в `src/tri/math/constants.zig`
32-
- Governance: 8 принципов в `src/sacred/CHARTER.md`
33-
28+
This formula is an **architectural invariant** of Trinity:
29+
- Mathematics: `V = n × 3^k × π^m × φ^p × e^q` in `src/tri/math/formula.zig`
30+
- Constants: 75+ sacred values ​​in `src/tri/math/constants.zig`
31+
- Governance: 8 principles in `src/sacred/CHARTER.md`
3432
---
3533

3634
## TRI-27 Kernel — Central Execution Engine
3735

38-
**TRI-27 — тернарное вычислительное ядро**, которое выполняет все рабочие нагрузки Trinity:
36+
**TRI-27 is a ternary computing core** that executes all Trinity workloads:
3937

40-
| Компонент | Значение |
41-
|------------|---------|
42-
| **Регистры** | 27×32-bit (t0-t26) = 3 банка × 9 (коптский алфавит) |
43-
| **Опкоды** | 36 — арифметика, логика, управление, тернарные, священные |
44-
| **Память** | 64KB байтоадресуемая |
45-
| **Цели** | Zig эмулятор CPU + Verilog FPGA |
38+
| Component | Value |
39+
|-----------|---------|
40+
| **Registers** | 27 x 32-bit (t0-t26) = 3 banks x 9 (Coptic alphabet) |
41+
| **Opcodes** | 36 — arithmetic, logic, control, ternary, sacred |
42+
| **Memory** | 64KB byte-addressable |
43+
| **Targets** | Zig CPU emulator + Verilog FPGA |
4644

4745
```
48-
φ² + 1/φ² = 3 → 3^27 = 7.6 триллионов состояний (тернарная полнота)
46+
φ² + 1/φ² = 3 → 3^27 = 7.6 trillion states (ternary completeness)
4947
```
5048

51-
[Полная документация TRI-27](docs/tri27/README.md)
49+
[Full TRI-27 documentation](docs/tri27/README.md)
5250

5351
---
5452

5553
## Strand I — Mathematical Foundation
5654

57-
### Роль
55+
### Role
5856

59-
Священная математическая рамка, которая задаёт **числовую геометрию** Trinity.
57+
The sacred mathematical framework that defines the **numerical geometry** of the Trinity.
6058

61-
### Компоненты
59+
### Components
6260

63-
| Модуль | Назначение | Ключевые элементы |
61+
| Module | Purpose | Key Elements |
6462
|--------|----------|-----------------|
65-
| `src/tri/math/formula.zig` | Священная формула | V = n × 3^k × π^m × φ^p × e^q |
66-
| `src/tri/math/constants.zig` | Священные константы | φ, π, e, γ, χ, σ, ε (75+) |
67-
| `src/tri/math/identities.zig` | Идентичности | φ-distance, ternary resonance |
68-
| `src/tri/math/transcendental.zig` | Трансцендентные функции | π, e, ln, exp |
69-
| `src/sacred/CHARTER.md` | Governance | 8 принципов |
70-
| `src/vsa.zig` | VSA операции | bind, unbind, bundle, similarity |
63+
| `src/tri/math/formula.zig` | The sacred formula | V = n × 3^k × π^m × φ^p × e^q |
64+
| `src/tri/math/constants.zig` | Sacred Constants | φ, π, e, γ, χ, σ, ε (75+) |
65+
| `src/tri/math/identities.zig` | Identities | φ-distance, ternary resonance |
66+
| `src/tri/math/transcendental.zig` | Transcendental Functions | π, e, ln, exp |
67+
| `src/sacred/CHARTER.md` | Governance | 8 Principles |
68+
| `src/vsa.zig` | VSA Operations | bind, unbind, bundle, similarity |
7169

72-
### Связи
70+
### Connections
7371

74-
- **→ Strand II**: Мозговые модули используют `src/tri/math/` для sacred операций
75-
- **→ Strand III**: TRI-27 компилятор использует sacred константы
72+
- **→ Strand II**: Brain modules use `src/tri/math/` for sacred operations
73+
- **→ Strand III**: TRI-27 compiler uses sacred constants
7674

7775
---
7876

7977
## Strand II — Cognitive Architecture
8078

81-
### Роль
82-
83-
Нейроанатомически вдохновлённая архитектура **виртуального мозга** Trinity.
84-
85-
### Компоненты
86-
87-
| Регион | Файл | Назначение | LOC |
88-
|--------|-------|----------|-----|
89-
| Prefrontal Cortex | `prefrontal_cortex.zig` | Исполнительные функции | 717 |
90-
| Basal Ganglia | `basal_ganglia.zig` | Реестр задач | 889 |
91-
| Reticular Formation | `reticular_formation.zig` | Шина событий (10K) | 746 |
92-
| Locus Coeruleus | `locus_coeruleus.zig` | Регуляция возбуждения | 253 |
93-
| Amygdala | `amygdala.zig` | Эмоциональная значимость | 578 |
94-
| Persistence | `persistence.zig` | Журналирование JSONL | 804 |
95-
| Health History | `health_history.zig` | Снимки здоровья | 305 |
96-
| Cerebellum | `cerebellum.zig` | Моторное обучение | 1601 |
97-
| Thalamus | `thalamus_logs.zig` | Ретрансляция | 435 |
98-
| Telemetry | `telemetry.zig` | Временные ряды | 412 |
99-
| Corpus Callosum | `federation.zig` | Агрегация, CRDT | 2166 |
100-
| Microglia | `microglia.zig` | Иммунный мониторинг | 512 |
101-
| Alerts | `alerts.zig` | Критические уведомления | 1241 |
102-
| Metrics Dashboard | `metrics_dashboard.zig` | Управление метриками | 1884 |
103-
| Visual Cortex | `visualization.zig` | ASCII карты | 1302 |
104-
| Admin | `admin.zig` | Административный контроль | 1374 |
105-
| State Recovery | `state_recovery.zig` | Восстановление | 2037 |
106-
| Evolution Simulation | `evolution_simulation.zig` | Эволюция агентов | 1500+ |
79+
### Role
80+
81+
Neuroanatomically inspired architecture of the Trinity **virtual brain**.
82+
83+
### Components
84+
85+
| Region | File | Purpose | LOC |
86+
|--------|----------|---------|
87+
| Prefrontal Cortex | `prefrontal_cortex.zig` | Executive Functions | 717 |
88+
| Basal Ganglia | `basal_ganglia.zig` | Task Registry | 889 |
89+
| Reticular Formation | `reticular_formation.zig` | Event Bus (10K) | 746 |
90+
| Locus Coeruleus | `locus_coeruleus.zig` | Arousal Regulation | 253 |
91+
| Amygdala | `amygdala.zig` | Emotional Valence | 578 |
92+
| Persistence | `persistence.zig` | JSONL Logging | 804 |
93+
| Health History | `health_history.zig` | Health Snapshots | 305 |
94+
| Cerebellum | `cerebellum.zig` | Motor Learning | 1601 |
95+
| Thalamus | `thalamus_logs.zig` | Relay | 435 |
96+
| Telemetry | `telemetry.zig` | Time Series | 412 |
97+
| Corpus Callosum | `federation.zig` | Aggregation, CRDT | 2166 |
98+
| Microglia | `microglia.zig` | Immune Monitoring | 512 |
99+
| Alerts | `alerts.zig` | Critical Notifications | 1241 |
100+
| Metrics Dashboard | `metrics_dashboard.zig` | Metrics Management | 1884 |
101+
| Visual Cortex | `visualization.zig` | ASCII Maps | 1302 |
102+
| Admin | `admin.zig` | Administrative Control | 1374 |
103+
| State Recovery | `state_recovery.zig` | Recovery | 2037 |
104+
| Evolution Simulation | `evolution_simulation.zig` | Agent Evolution | 1500+ |
107105
| SEBO | `sebo.zig` | Sacred Bayesian Optimization | 800+ |
108-
| Integration Test | `integration_test.zig` | Межмодульные тесты | 600+ |
109-
| Performance Benchmarks | `benchmarks.zig`, `perf_*.zig` | Производительность | 1000+ |
106+
| Integration Test | `integration_test.zig` | Cross-Module Benchmarks | 600+ |
107+
| Performance Benchmarks | `benchmarks.zig`, `perf_*.zig` | Performance | 1000+ |
110108

111-
### Связи
109+
### Links
112110

113-
- **← Strand I**: Использует sacred математику из `src/tri/math/`
114-
- **→ Strand III**: Выполняет TRI-27 bytecode, компилируемый в Zig
111+
- **← Strand I**: Uses sacred math from `src/tri/math/`
112+
- **→ Strand III**: Executes TRI-27 bytecode compiled to Zig
115113

116114
---
117115

118116
## Strand III — Language & Hardware Bridge (TRI-27)
119117

120-
### Роль
118+
### Role
121119

122-
Связывает высокоуровневый язык **TRI-27** с двумя мирами исполнения: CPU (Zig) и FPGA (Verilog). TRI-27 — единственный язык высокого уровня, Zig/Verilog — бэкенды.
120+
Links the **TRI-27** high-level language to two execution worlds: CPU (Zig) and FPGA (Verilog). TRI-27 is the only high-level language; Zig/Verilog are the backends.
123121

124-
### Компоненты
122+
### Components
125123

126-
| Компонент | Файл | Назначение |
127-
|-----------|-------|----------|
128-
| TRI-27 Lexer | `src/tri/lexer.zig` | Токенизация |
124+
| Component | File | Purpose |
125+
|-----------|----------|----------|
126+
| TRI-27 Lexer | `src/tri/lexer.zig` | Tokenization |
129127
| TRI-27 Parser | `src/tri/parser.zig` | AST |
130-
| TRI-27 AST | `src/tri/ast.zig` | Узлы |
128+
| TRI-27 AST | `src/tri/ast.zig` | Nodes |
131129
| Zig Backend | `src/tri/emit_zig.zig` | CPU target |
132130
| Verilog Backend | `src/tri/emit_verilog.zig` | FPGA target |
133131
| VSA Operations | `src/vsa.zig` | bind, unbind, bundle, similarity |
134132
| Sacred ALU | `fpga/openxc7-synth/sacred_alu.v` | φ-mathematics |
135133
| TMU | `fpga/openxc7-synth/hslm_ternary_mac.v` | Ternary matrix |
136134

137-
### Цепочка компиляции
135+
### Compilation Chain
138136

139137
```
140138
.tri spec (Single Source of Truth)
141-
139+
142140
TRI-27 language (Ternary types, AST)
143-
144-
Zig Backend Verilog Backend
145-
(emit) (emit)
141+
142+
Zig Backend Verilog Backend
143+
(emit) (emit)
146144
```
147145

148-
**Важно**: Zig и Verilog — это **targets**, не source of truth. TRI-27 = source of truth.
146+
**Important**: Zig and Verilog are **targets**, not sources of truth. TRI-27 = source of truth.
149147

150-
### Связи
148+
### Links
151149

152-
- **← Strand II**: Компилируется в Zig для выполнения мозговых модулей
153-
- **← Strand I**: Использует sacred константы в FPGA Sacred ALU
150+
- **← Strand II**: Compiled to Zig for running brain modules
151+
- **← Strand I**: Uses sacred constants in the FPGA Sacred ALU
154152

155153
---
156154

157155
## Rigid Process Framework
158156

159-
**Расположение**: `src/tri/dev/`
157+
**Location**: `src/tri/dev/`
160158

161159
**State Machine**: `IDLE → ACTIVE → DIRTY → TESTED → COMMITTED → SHIPPED`
162160

163-
Все изменения кода проходят через этот pipeline, а не ручное редактирование.
161+
All code changes go through this pipeline, rather than manual editing.
164162

165163
---
166164

167165
## Tri Skill & Tri Cell
168166

169-
**Skill** — единица возможностей, определённая через `.claude/skills/*/SKILL.md`.
167+
**Skill** is a unit of capability defined in `.claude/skills/*/SKILL.md`.
170168

171-
**Tri Cell** — самовосстанавливающаяся ячейка Phoenix System, определённая в `cell.tri`.
169+
**Tri Cell** is a self-healing Phoenix System cell, defined in `cell.tri`.
172170

173-
Все новые возможности проходят через **Rigid Process** и фиксируются в опыте Trinity.
171+
All new capabilities are processed through the Rigid Process and are captured in the Trinity experience.
174172

175-
Принципы:
173+
Principles:
176174

177-
- `.tri`/TRI-27 спецификации — **единственный источник истины**
178-
- Codegen (Zig/Verilog) разрешён только через SKILL-ячейки и tri-CLI, под контролем state-machine
179-
- Phoenix / Tri Cell уровнем выше обеспечивает самовосстановление и долговечность колонии SKILL-клеток
175+
- .tri/TRI-27 specifications are the single source of truth
176+
- Codegen (Zig/Verilog) is only enabled through SKILL cells and tri-CLI, controlled by the state machine
177+
- Phoenix/Tri Cell, one level higher, ensures self-healing and longevity of the SKILL cell colony
180178

181179
---
182180

183-
## Trinity S³AI DNA — сведение трёх Strand
181+
## Trinity S³AI DNA — merging three Strands
184182

185-
Trinity становится целостной, когда три Strand синхронизированы:
183+
Trinity becomes complete when the three Strands are synchronized:
186184

187-
- Strand I задаёт **числовую геометрию** (φ, 3, 27, ternary).
188-
- Strand II размещает эту геометрию в **виртуальном мозге**.
189-
- Strand III обеспечивает **исполнение и материализацию**от TRI-27 до CPU/FPGA.
185+
- Strand I defines the numerical geometry (φ, 3, 27, ternary).
186+
- Strand II places this geometry in the virtual brain.
187+
- Strand III provides execution and materializationfrom TRI-27 to CPU/FPGA.
190188

191-
Всё новое знание, модуль или SKILL появляются только тогда, когда:
189+
Any new knowledge, module, or SKILL appears only when:
192190

193-
1. Их место описано в ARCHITECTURE (один из Strand).
194-
2. Есть `.tri`/TRI-27 спецификация.
195-
3. Они проведены через Rigid Process и зафиксированы в опыте Trinity.
191+
1. Their location is described in ARCHITECTURE (one of the Strands).
192+
2. There is a `.tri`/TRI-27 specification.
193+
3. They are implemented through the Rigid Process and captured in the Trinity experience.
196194

197195
---
198196

199-
## Аннотационные паттерны (для вставки в код)
197+
## Annotation Patterns (for insertion into code)
200198

201-
**Strand I (Math)**для всех файлов в `src/tri/math/*.zig`:
199+
**Strand I (Math)**for all files in `src/tri/math/*.zig`:
202200
```zig
203-
//! [Module Name] — [Brief description]
201+
//! [Module Name] — [Brief Description]
204202
//! Strand I: Mathematical Foundation
205203
//!
206204
```
207205

208-
**Strand II (Brain)**для всех файлов в `src/brain/*.zig`:
206+
**Strand II (Brain)**for all files in `src/brain/*.zig`:
209207
```zig
210-
//! [Module Name] — [Neuroanatomical function]
208+
//! [Module Name] — [Neuroanatomical Function]
211209
//! Strand II: Cognitive Architecture
212210
//!
213211
```
214212

215-
**Strand III (Language + Hardware)** — для:
213+
**Strand III (Language + Hardware)** - for:
216214
- `src/tri/token.zig`, `src/tri/lexer.zig`, `src/tri/ast.zig`, `src/tri/parser.zig`, `src/tri/emit_zig.zig`, `src/tri/emit_verilog.zig`, `src/vsa.zig`
217215
- `fpga/openxc7-synth/*.v`
218216

219217
```zig
220-
//! [Module Name] [TRI-27/FPGA component]
218+
//! [Module Name] - [TRI-27/FPGA component]
221219
//! Strand III: Language & Hardware Bridge
222220
//!
223221
```
@@ -226,46 +224,46 @@ Trinity становится целостной, когда три Strand син
226224

227225
## Queen Trinity Protocol
228226

229-
**Расположение**: `src/tri/queen_trinity.zig`
227+
**Location**: `src/tri/queen_trinity.zig`
230228

231-
**Роль**: Lotus Cycle Protocol для очистки impure событий от всех трёх Strand.
229+
**Role**: Lotus Cycle Protocol for clearing impure events from all three Strands.
232230

233231
**Lotus Cycle (φ² + 1/φ² = 3)**:
234232
```
235233
QUEUED → DIAGNOSING → REFINE → VERIFY → PURIFIED
236-
↑ ↓ ↑
237-
←────────────────── RESET ────────────────
234+
↑ ↓ ↑
235+
←────────────────── RESET ────────────────
238236
```
239237

240-
**Максимум 3 попытки** (архитектурный лимит Trinity).
238+
**Maximum 3 attempts** (Trinity architectural limit).
241239

242-
**Impure события** генерируются всеми Strand:
243-
- **Strand I (Math)**: `src/tri/math/` — sacred вычисления, формулы
244-
- **Strand II (Brain)**: `src/brain/`обучение, telemetry, checkpoint
245-
- **Strand III (Lang)**: `src/tri27/`, `fpga/`компиляции, синтез, верификация
240+
**Impure events** are generated by all Strands:
241+
- **Strand I (Math)**: `src/tri/math/` — sacred calculations, formulas
242+
- **Strand II (Brain)**: `src/brain/`training, telemetry, checkpoint
243+
- **Strand III (Lang)**: `src/tri27/`, `fpga/`compilation, synthesis, verification
246244

247-
**Типы событий**:
248-
| Тип | Код | Описание |
249-
|-----|------|----------|
250-
| BUILD_FAIL | `zig build` упал |
251-
| TEST_FAIL | `zig build test` не прошёл |
252-
| SPEC_MISMATCH | `.tri` spec не совпадает с кодом |
253-
| GEN_FAIL | GEN фаза упала |
254-
| VERIFY_FAIL | VERIFY фаза не прошла |
255-
| DEPLOY_FAIL | деплой не удался |
256-
| CHECKPOINT_FAIL | checkpoint не создан |
245+
**Event Types**:
246+
| Type | Code | Description |
247+
|-----|-------|----------|
248+
| BUILD_FAIL | `zig build` failed |
249+
| TEST_FAIL | `zig build test` failed |
250+
| SPEC_MISMATCH | `.tri` spec does not match code |
251+
| GEN_FAIL | GEN phase failed |
252+
| VERIFY_FAIL | VERIFY phase failed |
253+
| DEPLOY_FAIL | deployment failed |
254+
| CHECKPOINT_FAIL | checkpoint not created |
257255

258-
**Хранилище**: `.trinity/impure/*.json`
256+
**Repository**: `.trinity/impure/*.json`
259257

260-
**CLI команды**:
258+
**CLI commands**:
261259
```bash
262-
tri queen status # Показать очередь impure событий
263-
tri queen purify # Запустить Lotus Cycle на первом в очереди
264-
tri queen purify --all # Очистить все queued
265-
tri queen blocked # Показать события, где Queen не смогла
260+
tri queen status # Show impure event queue
261+
tri queen purify # Run Lotus Cycle on the first event in the queue
262+
tri queen purify --all # Clear all queued events
263+
tri queen blocked # Show events where Queen failed
266264
```
267265

268-
**Интеграция**:
269-
- Hook события записывают в `.trinity/impure/` автоматически
270-
- Queen CLI читает очередь и выполняет Lotus Cycle
271-
- Каждая фаза цикла (DIAGNOSING → VERIFY → PURIFY) записывает прогресс в событие
266+
**Integration**:
267+
- Hook events are written to `.trinity/impure/` automatically
268+
- Queen CLI reads the queue and executes Lotus Cycle
269+
- Each cycle phase (DIAGNOSING → VERIFY → PURIFY) records progress in an event

0 commit comments

Comments
 (0)