Spaces:
Paused
Paused
File size: 4,928 Bytes
5e0b58b | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 | # Brain-5D Developer Guide
## 1. Architecture
Brain-5D is organized around explicit boundaries:
1. `src/core/` — neural network, neurons, synapses, spatial indexing.
2. `src/learning/` — STDP, eligibility traces, reward learning.
3. `src/homeostasis/` — rate, threshold and energy regulation.
4. `src/self_organization/` — structural policy, proposals, coordination,
approval and undo.
5. `src/manipulation/` — controlled network mutation boundary.
6. `src/storage/` — `.b5d`, delta journal, structural journal, recovery,
checkpoints.
7. `src/dashboard/` — typed HTTP/operator-facing surface.
8. `src/controller/` and `src/runtime/` — interactive execution and safe runtime
control.
9. `src/visualization/` — observability and structural/homeostasis projections.
10. `src/embodiment/` — typed interfaces for later sensor/actuator integration.
## 2. Alpha.5 structural path
```text
HomeostasisEngine
-> HomeostasisSignal
-> SelfOrganizationPolicy
-> StructuralProposal
-> SelfOrganizationCoordinator
-> ApprovalDecision
-> StructuralPlasticityEngine
-> Manipulator
-> NeuralNetwork
-> StructuralChangeRecord
-> StructuralJournal
```
The coordinator does not mutate the network directly.
The dashboard does not reach into private network or engine attributes.
## 3. Persistence contract
The active persistence layers are:
```text
Snapshot + State Delta Journal + Structural Journal + Runtime Checkpoint
```
Restore order is deliberately defined:
```text
snapshot -> state deltas -> structural replay -> runtime checkpoint -> validate
```
Do not reorder these stages without updating deterministic restore tests.
## 4. Type safety
New code must avoid the Pylance/Pyright error classes that were previously
observed in the project.
Rules:
- no bare `dict`, `list`, `set`, `tuple` containers;
- avoid `Any` as a repair mechanism;
- parse external JSON/YAML to `object`, then validate and narrow;
- do not expand `dict[str, object]` into strictly typed subprocess kwargs;
- subprocess commands should be explicit `list[str]`;
- keep config TypedDicts complete;
- do not reference undeclared TypedDict keys;
- avoid dynamic runtime attributes;
- use `assert_never` for exhaustive enums where appropriate;
- keep Protocol properties read-only when mutation is not required;
- no broad `type: ignore` / `pyright: ignore` for new code.
## 5. Testing strategy
- isolated unit tests for component behavior;
- integration tests for subsystem boundaries;
- restore/continue tests for persistence;
- opt-in slow tests for long-running behavior;
- focused alpha release verifiers.
When fixing a regression, reproduce it with the smallest failing test before
changing production code.
## 6. Quality commands
```powershell
.\.venv\Scripts\python.exe -m pytest -v -m "not slow"
.\.venv\Scripts\python.exe -m mypy src
.\.venv\Scripts\python.exe -m black --check src tests scripts
.\.venv\Scripts\python.exe -m pylint --fail-under=9.0 src
git diff --check
```
Alpha.5 strict Pyright production scope:
```powershell
.\.venv\Scripts\python.exe -m pyright `
src/storage/structural_journal.py `
src/storage/structural_recovery.py `
src/storage/core_restore.py `
src/self_organization/approval.py `
src/self_organization/undo.py `
src/self_organization/plasticity.py `
src/self_organization/coordinator.py `
src/dashboard/structural_api.py `
src/dashboard/operator_bridge.py `
src/dashboard/server.py `
src/runtime/control.py `
src/controller/runtime.py `
src/visualization/structural_heatmap.py
```
Repository-wide strict Pyright currently includes legacy findings outside this
scope. Do not hide them with global suppressions and do not add new debt.
## 7. Dashboard development
HTTP handlers must validate request fields explicitly.
Do not add endpoints that accept arbitrary command strings or shell fragments.
Preferred direction:
```text
DashboardRequestHandler
-> OperatorBridge
-> Coordinator / Runtime Controller
-> Plasticity / Manipulator
-> Core
```
## 8. Structural journal development
Structural records are immutable events.
Undo appends a new inverse record. Never delete a previous committed record as
an undo mechanism.
Corrupted committed records must fail loudly. Recoverable uncommitted tails
must not be treated as committed data.
## 9. Adding a feature
1. Define an observable problem and exit criterion.
2. Choose the correct architectural boundary.
3. Add typed models/contracts.
4. Add focused tests.
5. Implement the smallest working slice.
6. Run focused tests.
7. Run static gates.
8. Run the full fast suite.
9. Update README/UserGuide/DeveloperGuide as required.
## 10. Release work
Update at minimum:
- `pyproject.toml`;
- `CHANGELOG.md`;
- README status;
- roadmap/release notes;
- release verifier.
Do not tag a release while deterministic restore, Black, Mypy or required test
gates are failing.
|