Spaces:
Paused
Paused
| # 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. | |