Spaces:
Paused
Paused
| # Brain-5D Documentation | |
| This directory contains both **current canonical documentation** and **historical/versioned records**. Historical Alpha, Sprint, Release and dated change documents remain traceability artifacts and must not be read as the current repository state. | |
| ## Source of truth | |
| When documents disagree, use this order: | |
| 1. code, configuration schemas and machine-readable contracts on `main`; | |
| 2. current CI and verification artifacts; | |
| 3. experiment `DATA/` and accepted `EVID` records; | |
| 4. the canonical documents listed below; | |
| 5. historical/versioned documents; | |
| 6. narrative or AI-generated interpretation. | |
| Passing tests prove engineering behavior covered by those tests; they do not automatically establish a scientific claim. | |
| ## Current baseline — 2026-09-07 | |
| - canonical branch: `main` | |
| - package version: `0.5.0a7` | |
| - latest verified Python suite: **825 passed, 5 skipped** | |
| - latest verified browser suite: **5 passed** with Chromium | |
| - Research Catalog / variable-projection-dimension merge: `85e7209509b348bf7912dde01d3d9ebb078a2e61` | |
| - latest fully completed pre-merge `main` CI baseline: **success** (run #598) | |
| - Python matrix: **3.11 / 3.12 / 3.13** | |
| - Black, Ruff, Pylint, Pre-Commit, Mypy, Pyright, Security, Scientific Integrity, wheel and Docker checks remain mandatory CI gates | |
| - post-merge CI is authoritative for the merged baseline; do not describe it as fully green until the corresponding `main` run completes | |
| - GitHub `main` is canonical; the configured Hugging Face mirror is synchronized from this branch after repository changes | |
| - Live dashboard Space: https://huggingface.co/spaces/superdigger/Brain-5D-Space | |
| - historical experiment DATA/EVID remains unchanged by documentation or registry cleanup | |
| Historical `EXP-GEN-0009` to `EXP-GEN-0012` artifacts remain untouched. They recorded zero observable activity under the older probe contract. Current instrumentation measures published spike IDs plus tick, neuron and synaptic-event activity and persists those fields in new experiment DATA. | |
| ## Canonical current documents | |
| | Area | Canonical document | | |
| | --- | --- | | |
| | Project overview | [`../README.md`](../README.md) | | |
| | Architecture | [`02-architecture/ARCHITECTURE.md`](02-architecture/ARCHITECTURE.md) | | |
| | Adaptive Wesen body view | [`02-architecture/WESEN_ADAPTIVE_BODY.md`](02-architecture/WESEN_ADAPTIVE_BODY.md) | | |
| | Neural Symbiosis / multi-network embodiment | [`02-architecture/NEURAL_SYMBIOSIS.md`](02-architecture/NEURAL_SYMBIOSIS.md) | | |
| | MSBA / modality-specific pathways and energy homeostasis | [`02-architecture/MSBA.md`](02-architecture/MSBA.md) | | |
| | Storage format | [`02-architecture/B5D_FORMAT.md`](02-architecture/B5D_FORMAT.md) | | |
| | Real-body embodiment | [`02-architecture/EMBODIMENT_REAL_BODY.md`](02-architecture/EMBODIMENT_REAL_BODY.md) | | |
| | Learning preparation | [`02-architecture/LEARNING_PREPARATION_STUDIO.md`](02-architecture/LEARNING_PREPARATION_STUDIO.md) | | |
| | Dashboard | [`03-dashboard/DASHBOARD.md`](03-dashboard/DASHBOARD.md) | | |
| | API reference | [`03-dashboard/API_REFERENCE.md`](03-dashboard/API_REFERENCE.md) | | |
| | Quality gate | [`05-quality/QUALITY_GATE.md`](05-quality/QUALITY_GATE.md) | | |
| | Research positioning & evidence program | [`06-research/RESEARCH_POSITIONING_AND_EVIDENCE_PROGRAM.md`](06-research/RESEARCH_POSITIONING_AND_EVIDENCE_PROGRAM.md) | | |
| | Development roadmap | [`08-roadmap/ROADMAP.md`](08-roadmap/ROADMAP.md) | | |
| | Current TODO | [`08-roadmap/TODO.md`](08-roadmap/TODO.md) | | |
| | Research roadmap | [`08-roadmap/RESEARCH_ROADMAP.md`](08-roadmap/RESEARCH_ROADMAP.md) | | |
| | Research/evidence system | [`../research/README.md`](../research/README.md) | | |
| | Security | [`../SECURITY.md`](../SECURITY.md) | | |
| | Contribution workflow | [`../CONTRIBUTING.md`](../CONTRIBUTING.md) | | |
| ## Current research-registry contract | |
| The normal research workflow loads canonical base registries plus deterministic fragments: | |
| - `research/registry/questions.yaml` | |
| - `research/registry/questions.*.yaml` | |
| - `research/registry/hypotheses.yaml` | |
| - `research/registry/hypotheses.*.yaml` | |
| Duplicate identifiers fail closed. MSBA questions/hypotheses are first-class entries rather than side documentation. The Experiment Workflow exposes them through a searchable Research Catalog and distinguishes questions with frozen/preregistered operational protocols from exploratory-only questions. Exploratory execution must not be confused with confirmatory evidence. | |
| The repository-wide RQ/H audit reports references that are not represented in the canonical registry without rewriting historical sources. | |
| ## Current dashboard terminology | |
| - **Overview** — summary/runtime context; | |
| - **Control** — explicit operator controls; | |
| - **Research** — research/evidence workflows and searchable Research Catalog; | |
| - **Settings** — configuration; | |
| - **Wesen** — adaptive read-only live machine-body visualization; | |
| - **Embodiment** — technical sensor/device/actuator/body-boundary surface; | |
| - **Neural Symbiosis** — read-only multi-network/virtual-pipeline view inside `Wesen`; | |
| - **MSBA** — modality-specific audio/vision/digital gateway contract plus resource/energy model inside Neural Symbiosis; | |
| - **Release/Gate** — footer-accessed release-readiness surface; | |
| - **Network** — no longer a primary user-facing workspace. | |
| `Wesen`, Neural Symbiosis and MSBA must never be described as proof of consciousness, self-awareness, causal tool use or learned sensor control. Reachability, recurrence, loopback, morphology, pipeline availability, energy allocation candidates and gateway candidates are engineering/observation state until a preregistered experiment produces reviewable DATA/EVID. | |
| ## Scientific boundary for Neural Symbiosis, MSBA and dimensions | |
| The multi-network layer is part of Embodiment, not a rewrite of the SNN core. Peripheral CNN/Transformer/RNN/GNN/memory/generative/custom networks and virtual systems such as logic or knowledge databases are connected only through explicit adapter/gateway contracts. | |
| MSBA specializes those gateway contracts by modality: | |
| - audio: temporal-coherence features and candidate phase-weighted t-STDP; | |
| - vision: spatial multiplexing, fixed sparse target degree and candidate locality/information/resource structural growth; | |
| - digital: exact immutable payload outside the SNN, deterministic population representation and candidate meta-gating only; | |
| - resource pressure: normalized energy accounting, explicit estimate-vs-measurement provenance and deterministic NORMAL/CONSERVE/CRITICAL/SURVIVAL protection states. | |
| Current dimension rule: | |
| - MSBA/external projection spaces may declare **1–32 dimensions**; | |
| - the productive persisted SNN core remains **5D** for compatibility; | |
| - productive core >5D requires a separately versioned neuron-ID/storage representation, generalized spatial indexing, `.b5d` migration, canonical state/equivalence tests and preregistered experiments; | |
| - increased-dimensional projection experiments must not be mislabeled as productive-core N-D evidence. | |
| Current gateway rules: | |
| - open-set `NetworkAreaAdapter` contract; | |
| - framework-neutral peripheral implementations; | |
| - pipeline templates are disabled until explicitly instantiated; | |
| - Neural-Symbiosis and MSBA gateway learning/growth/allocation are disabled by default; | |
| - gateway RNG belongs to an experiment runner and must be persisted; | |
| - endpoint reachability is not evidence of learned use; | |
| - fixed semantics are not imposed on the five Brain-5D axes; | |
| - measured joules are never inferred from normalized units without explicit calibration/provenance; | |
| - historical DATA/EVID is never rewritten to reflect new adapters. | |
| See [`02-architecture/NEURAL_SYMBIOSIS.md`](02-architecture/NEURAL_SYMBIOSIS.md) and [`02-architecture/MSBA.md`](02-architecture/MSBA.md). | |
| ## Experiment-data compacting rule | |
| Large experiment series preserve raw observations in immutable/compressed artifacts. Bounded projections such as `runs.json` and `analysis/ai_packet.json` exist for UI/review/small-model consumption and must carry provenance back to the raw record. Compact files are not replacements for scientific raw DATA. | |
| ## Directory map | |
| - `01-guides/` — operator/developer guides; | |
| - `02-architecture/` — architecture and subsystem contracts; | |
| - `03-dashboard/` — dashboard contracts and UI/API documentation; | |
| - `04-integration/` — integration notes and overlays; | |
| - `05-quality/` — quality and release-gate definitions; | |
| - `06-research/` — research notes and canonical research-positioning documents; | |
| - `07-changelog/` — dated change records; | |
| - `08-roadmap/` — current roadmap/TODO plus historical phase-specific roadmaps; | |
| - `09-sprints/` — time-boxed sprint records; | |
| - `10-releases/` — release checklists and notes; | |
| - `11-readme/` — historical README blocks; | |
| - `12-updates/` — update manifests and integration snapshots; | |
| - `99-archive/` — explicitly archived legacy material. | |
| ## Historical-document rule | |
| A filename containing a previous version, `ALPHA*`, `SPRINT*`, `V0*`, `UPDATE*`, `RELEASE_*`, or an entry under `99-archive/` is historical unless a canonical current document links to it as an active contract. Old test counts, commit hashes, milestones and implementation status in those files are not current project metadata. | |
| Historical experiment DATA must not be silently rewritten when instrumentation improves. Corrections belong in code, canonical documentation and new versioned experiments. | |
| ## Documentation maintenance | |
| Avoid copying fixed test counts or commit hashes into many current documents. Where a fixed number is useful, date it and treat it as a verified snapshot. Scientific conclusions must cite experiment/evidence artifacts, not README prose or dashboard state alone. | |
| **Current development policy:** `main` is canonical. Short-lived branches start from current `origin/main`, are verified before merge, and should be deleted after merge when repository tooling permits. A branch with no commits ahead of `main` contains nothing to integrate and must not be merged merely to make the branch list empty. | |