docs/01-guides/DeveloperGuide.md

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

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:

Snapshot + State Delta Journal + Structural Journal + Runtime Checkpoint

Restore order is deliberately defined:

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

.\.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:

.\.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:

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.