Skip to content

Commit 7bc6fee

Browse files
neuron7xLabneuron7x
neuron7xLab
and
neuron7x
authored
docs(exocortex): elevate research-provenance layer to audit-grade (#221)
Adds three new index documents and rewrites the two existing ones so the .exocortex/ directory functions as a self-contained, fact-checked audit trail from a passing test back to a falsifiable physical claim: - README.md (new) — directory index + authority hierarchy - METHODOLOGY.md — full role + 5-gate spec, escalation rules, 'why adversarial' - RESEARCH_TIMELINE.md — corrected counts (60 invariants, not 57; 8.8k tests across 844 files), consistent gamma notation, source-cited table form - GLOSSARY.md (new) — precise defs of gamma, INV-*, TACL, MFN, BN-Syn, ECS, OMS - INVARIANTS_INDEX.md (new) — all 60 invariants by category and priority, cross-linked to .claude/physics/ theory docs and physics_contracts/ catalog - VALIDATION.md (new) — exact commands for each gate, including the shallow-fetch failure recipe seen on dependabot rebases All claims verified against current repo state (.claude/physics/INVARIANTS.yaml, physics_contracts/catalog.yaml, Makefile targets). No speculative content. Co-authored-by: Yaroslav Vasylenko <neuron7x@users.noreply.github.com>
1 parent d677907 commit 7bc6fee

6 files changed

Lines changed: 361 additions & 29 deletions

File tree

‎.exocortex/GLOSSARY.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Glossary
2+
3+
Definitions of in-house terms used across [`CLAUDE.md`](../CLAUDE.md), the
4+
`.claude/physics/` documents, and this directory. Terms defined elsewhere in
5+
mainstream literature (e.g. *Lyapunov exponent*, *Ricci curvature*) are
6+
referenced rather than redefined here; see the cited sources.
7+
8+
## Notation
9+
10+
| Symbol | Meaning |
11+
| --- | --- |
12+
| `γ` (gamma) | Metastable-computation scaling exponent. Hypothesized to be ≈ 1 across substrates with critical neural-like dynamics. See [`RESEARCH_TIMELINE.md`](./RESEARCH_TIMELINE.md). |
13+
| `R(t)` | Kuramoto order parameter at time *t*: `\| (1/N) Σ_j exp(i θ_j(t)) \|`. Bounded in `[0, 1]`. See [`.claude/physics/KURAMOTO_THEORY.md`](../.claude/physics/KURAMOTO_THEORY.md). |
14+
| `K_c` | Critical coupling for Kuramoto synchrony onset. `K_c = 2 / (π · g(0))` for unimodal `g`. |
15+
| `INV-*` | Stable identifier for a physics invariant. Listed in [`INVARIANTS_INDEX.md`](./INVARIANTS_INDEX.md). |
16+
17+
## Acronyms
18+
19+
| Term | Expansion | Where it lives |
20+
| --- | --- | --- |
21+
| **TACL** | Tonic-Adaptive Coupling Layer — neuromodulator-gated coupling matrix used by the GeoSync neural controller | [`src/geosync/neural_controller/`](../src/geosync/neural_controller/) |
22+
| **MFN** | Mycelium-Fractal-Net — fractal-routing substrate inspired by hyphal-network growth | [`src/mycelium_fractal_net/`](../src/mycelium_fractal_net/) |
23+
| **BN-Syn** | Biophysical-Network Synthetic — spiking-network simulator (external repo); first place `γ ≈ 1` was observed | external |
24+
| **NFI** | Neuro-Fractal-Inference platform composing ML-SDM, CA1-LAM, BN-Syn, MFN+ | external |
25+
| **ML-SDM** | Multi-Layer Sparse Distributed Memory | external (NFI) |
26+
| **CA1-LAM** | CA1-inspired Local Associative Memory | external (NFI) |
27+
| **ECS** | Energy-Constraint System — Lyapunov-bounded controller used to keep strategies inside a free-energy budget | [`src/geosync/`](../src/geosync/) |
28+
| **OMS** | Order-Management System | [`src/geosync/`](../src/geosync/), invariants under `oms.*` |
29+
30+
## Roles (see [`METHODOLOGY.md`](./METHODOLOGY.md))
31+
32+
| Role | Authority |
33+
| --- | --- |
34+
| **Creator** | Proposes a change. Cannot self-approve. |
35+
| **Critic** | Challenges the change. May block on physics or architectural grounds. |
36+
| **Auditor** | Confirms the gates passed. Signs CI status. |
37+
| **Verifier** | Confirms reproducibility. Signs the release tag. |
38+
| **Human** | Central decision node. Only signer of the merge commit. |
39+
40+
## Priority levels for invariants
41+
42+
| Priority | Meaning | CI behavior |
43+
| --- | --- | --- |
44+
| **P0** | Universal invariant. Violation = bug, not numerical artefact. | Block release. |
45+
| **P1** | Asymptotic / regime-dependent invariant. Violation under documented conditions = bug. | Block release. |
46+
| **P2** | Soft invariant. Violation = warning + tracked regression budget. | Report-only by default; can be promoted to P1. |

‎.exocortex/INVARIANTS_INDEX.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Invariants Index
2+
3+
Authoritative source: [`.claude/physics/INVARIANTS.yaml`](../.claude/physics/INVARIANTS.yaml).
4+
This file is a derived overview; if it disagrees with the YAML, the YAML wins.
5+
6+
## Summary
7+
8+
| Total | P0 | P1 | P2 | Categories |
9+
| ---: | ---: | ---: | ---: | ---: |
10+
| **60** | 40 | 17 | 3 | 16 |
11+
12+
Regenerate this summary via `python .claude/physics/validate_tests.py --summary`
13+
(see [`VALIDATION.md`](./VALIDATION.md)).
14+
15+
## By category
16+
17+
| Category | Theory doc | P0 | P1 | P2 | IDs |
18+
| --- | --- | ---: | ---: | ---: | --- |
19+
| **kuramoto** | [KURAMOTO_THEORY.md](../.claude/physics/KURAMOTO_THEORY.md) | 3 | 3 | 1 | INV-K1 … INV-K7 |
20+
| **explosive_sync** | [KURAMOTO_THEORY.md](../.claude/physics/KURAMOTO_THEORY.md) | 1 | 1 | 0 | INV-ES1, INV-ES2 |
21+
| **serotonin** | [SEROTONIN_THEORY.md](../.claude/physics/SEROTONIN_THEORY.md) | 5 | 2 | 0 | INV-5HT1 … INV-5HT7 |
22+
| **dopamine** | [DOPAMINE_THEORY.md](../.claude/physics/DOPAMINE_THEORY.md) | 3 | 3 | 1 | INV-DA1 … INV-DA7 |
23+
| **gaba** | [GABA_THEORY.md](../.claude/physics/GABA_THEORY.md) | 3 | 2 | 0 | INV-GABA1 … INV-GABA5 |
24+
| **free_energy** | — | 2 | 0 | 0 | INV-FE1, INV-FE2 |
25+
| **thermodynamics** | — | 0 | 2 | 0 | INV-TH1, INV-TH2 |
26+
| **ricci** | — | 1 | 1 | 1 | INV-RC1 … INV-RC3 |
27+
| **kelly** | — | 2 | 1 | 0 | INV-KELLY1 … INV-KELLY3 |
28+
| **oms** | — | 3 | 0 | 0 | INV-OMS1, INV-OMS2, INV-OMS3 |
29+
| **signalbus** | — | 2 | 0 | 0 | INV-SB1, INV-SB2 |
30+
| **hpc** | — | 2 | 0 | 0 | INV-HPC1, INV-HPC2 |
31+
| **cryptobiosis** | [CRYPTOBIOSIS_THEORY.md](../.claude/physics/CRYPTOBIOSIS_THEORY.md) | 6 | 2 | 0 | INV-CB1 … INV-CB8 |
32+
| **lyapunov_exponent** | [LYAPUNOV_EXPONENT_THEORY.md](../.claude/physics/LYAPUNOV_EXPONENT_THEORY.md) | 2 | 0 | 0 | INV-LE1, INV-LE2 |
33+
| **spectral_gap** | — | 2 | 0 | 0 | INV-SG1, INV-SG2 |
34+
| **ott_antonsen** | — | 3 | 0 | 0 | INV-OA1, INV-OA2, INV-OA3 |
35+
36+
## Parallel layer: `physics_contracts/`
37+
38+
The `.claude/physics/` registry above is the *theory-anchored* layer. A second,
39+
*module-anchored* layer lives in
40+
[`physics_contracts/catalog.yaml`](../physics_contracts/catalog.yaml) and
41+
currently contains **26 laws**. The two layers serve different purposes:
42+
43+
| Layer | Anchor | Audience | Test reference |
44+
| --- | --- | --- | --- |
45+
| `.claude/physics/INVARIANTS.yaml` | Physical theory (Kuramoto 1975, Ott-Antonsen 2008, …) | Theorists, reviewers | `INV-*` IDs in test docstrings |
46+
| `physics_contracts/catalog.yaml` | Module of origin (`kuramoto.*`, `oms.*`, …) | Module owners, integrators | dotted IDs in test markers |
47+
48+
Both must stay in sync; mass-deleting either is forbidden (see
49+
`feedback_geosync_physics_layers` in the contributor playbook).
50+
51+
## How to add a new invariant
52+
53+
1. Append the entry to `.claude/physics/INVARIANTS.yaml` with `id`, `type`,
54+
`statement`, `falsification`, `priority`, and (where relevant) `parameters`
55+
and `common_mistake`.
56+
2. If the invariant is module-anchored, add the matching law to
57+
`physics_contracts/catalog.yaml` with the same numeric tolerance derivation.
58+
3. Add at least one witness test that references the new `INV-*` ID.
59+
4. Update this file's category row.
60+
5. Re-run `python .claude/physics/validate_tests.py` and the `pytest` heavy
61+
gate to confirm the witness fires under falsification inputs.
62+
63+
A new invariant lands only when steps 1–5 are complete in the same PR.

‎.exocortex/METHODOLOGY.md‎

Lines changed: 67 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,71 @@
1-
# Adversarial Orchestration
1+
# Adversarial Orchestration Methodology
22

3-
Creator -> Critic -> Auditor -> Verifier
4-
Human = central decision node. No agent has autonomous authority.
3+
GeoSync development uses an **adversarial multi-role workflow**. Every change
4+
passes through four roles before it can land. No role has autonomous authority:
5+
the human contributor is the central decision node and the only signer.
56

6-
Physics Kernel (CLAUDE.md + .claude/physics/) = embedded Critic.
7-
57 invariants. Every test references INV-*. Every threshold derived from theory.
7+
## Roles
88

9-
## Validation layers
9+
| Role | Responsibility | Concrete artifact |
10+
| --- | --- | --- |
11+
| **Creator** | Proposes the change — code, test, doc | The diff |
12+
| **Critic** | Challenges the change against physical and architectural constraints | Inline review comments + the embedded physics kernel (see below) |
13+
| **Auditor** | Verifies that the change does not break invariants or contracts | CI gate output, `validate_tests.py` report |
14+
| **Verifier** | Confirms the artifact is reproducible bit-for-bit | `MANIFEST.sha256` diff + signed tag |
1015

11-
1. **AST validator** — `python .claude/physics/validate_tests.py` — structural
12-
2. **mypy --strict** — type-level soundness
13-
3. **ruff format + check** — style determinism
14-
4. **pytest** — runtime correctness
15-
5. **MANIFEST.sha256** — reproducibility seal
16+
The Critic role is partially **embedded in the repository**, not in the
17+
contributor's head: [`CLAUDE.md`](../CLAUDE.md) and the documents under
18+
[`.claude/physics/`](../.claude/physics/) state the rules a Critic must apply,
19+
so any reviewer (human or automated) reaches the same verdict.
20+
21+
## The five validation gates
22+
23+
Every PR must pass these gates **in this order**. Failure at any gate halts the
24+
pipeline; the failure does not get masked or skipped.
25+
26+
1. **AST validator** — `python .claude/physics/validate_tests.py`
27+
- Parses every test, checks that assertions reference an `INV-*` ID, and
28+
that numeric tolerances derive from a documented formula rather than a
29+
magic literal.
30+
2. **`mypy --strict`** — type-level soundness on the entire `src/` tree.
31+
3. **`ruff format --check` + `ruff check`** — style and lint determinism.
32+
4. **`pytest`** — runtime correctness, including the property-based
33+
(Hypothesis) suites.
34+
5. **`MANIFEST.sha256`** — reproducibility seal: regeneration must produce
35+
byte-identical artifacts.
36+
37+
The exact commands for each gate live in [`VALIDATION.md`](./VALIDATION.md).
38+
39+
## Invariant references in tests
40+
41+
Each test is required to declare which invariant it witnesses. The minimum form is:
42+
43+
```python
44+
def test_kuramoto_order_parameter_bounded() -> None:
45+
"""Witness for INV-K1: 0 ≤ R(t) ≤ 1 for all t."""
46+
...
47+
```
48+
49+
The AST validator (gate 1) rejects tests whose docstring or marker does not
50+
contain an `INV-*` token from [`INVARIANTS_INDEX.md`](./INVARIANTS_INDEX.md).
51+
This makes coverage of the physics layer **structurally measurable**, not a
52+
matter of opinion.
53+
54+
## Escalation
55+
56+
A failing gate is never "patched around" by relaxing the invariant. If a test
57+
genuinely cannot pass:
58+
59+
1. Document the falsification attempt (input, observed output, expected bound).
60+
2. Open an issue tagged `physics-falsification`.
61+
3. Either the implementation is wrong (fix the code) or the invariant was
62+
wrong (amend `INVARIANTS.yaml` with a dated changelog entry and a citation).
63+
64+
Both branches produce a permanent audit trail; neither lets the failing test
65+
silently pass.
66+
67+
## Why adversarial, not consensus
68+
69+
A consensus workflow optimizes for agreement; an adversarial workflow optimizes
70+
for finding the case that breaks the claim. Physical systems do not care about
71+
agreement, so neither does this codebase.

‎.exocortex/README.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# `.exocortex/` — Provenance & Methodology Index
2+
3+
This directory is the **research-provenance layer** of GeoSync: the small set of
4+
documents required to reconstruct *why* the codebase looks the way it does and
5+
*how* it stays correct. It is not API documentation. It is the trail an external
6+
auditor follows from a passing test back to a falsifiable physical claim.
7+
8+
## Contents
9+
10+
| File | Purpose | Audience |
11+
| --- | --- | --- |
12+
| [`METHODOLOGY.md`](./METHODOLOGY.md) | Adversarial-orchestration roles, validation gates, escalation rules | Contributors, reviewers |
13+
| [`RESEARCH_TIMELINE.md`](./RESEARCH_TIMELINE.md) | Chronology of substrates, models, and milestones the codebase rests on | Auditors, scientific reviewers |
14+
| [`GLOSSARY.md`](./GLOSSARY.md) | Precise definitions of γ, INV, TACL, MFN, BN-Syn, and other in-house terms | New contributors |
15+
| [`INVARIANTS_INDEX.md`](./INVARIANTS_INDEX.md) | Map of the 60 physics invariants in [`.claude/physics/INVARIANTS.yaml`](../.claude/physics/INVARIANTS.yaml) by category and priority | Test authors, CI gatekeepers |
16+
| [`VALIDATION.md`](./VALIDATION.md) | Exact commands for the five validation gates, in order | Contributors, CI engineers |
17+
18+
## Authority hierarchy
19+
20+
When two artifacts disagree, the right one to trust is the one closer to the
21+
top of this list:
22+
23+
1. [`.claude/physics/INVARIANTS.yaml`](../.claude/physics/INVARIANTS.yaml) — machine-readable physics constraints
24+
2. [`physics_contracts/catalog.yaml`](../physics_contracts/catalog.yaml) — module-anchored law catalog (parallel layer)
25+
3. The Python tests under [`tests/`](../tests/) that reference `INV-*` IDs
26+
4. The narrative documents in this directory
27+
5. Anything else
28+
29+
If a doc here contradicts the YAML, fix the doc. If a test contradicts the YAML,
30+
fix the test or escalate the invariant — never weaken the assertion.
31+
32+
## Scope boundary
33+
34+
`.exocortex/` documents claims that are **provable from the repository** or
35+
**published in cited literature**. It does not contain hypotheses that have not
36+
yet been falsified. Speculative work lives under [`docs/`](../docs/) or in
37+
external research notes — not here.

‎.exocortex/RESEARCH_TIMELINE.md‎

Lines changed: 52 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,63 @@
11
# Research Timeline
22

3+
This timeline records the substrate-level results and architectural milestones
4+
that the GeoSync codebase rests on. Numbers are stated as of the last commit
5+
to this file (see `git log`); when in doubt, re-derive from the source of
6+
truth shown in the **Source** column.
7+
8+
> Convention: `γ` denotes the metastable-computation scaling exponent
9+
> hypothesized in this research line. See [`GLOSSARY.md`](./GLOSSARY.md).
10+
311
## 2022
4-
- Self-directed computational neuroscience study
5-
- First experiments with neural dynamics simulation
12+
13+
| Milestone | Source |
14+
| --- | --- |
15+
| Self-directed computational neuroscience study begins | — |
16+
| First experiments with neural-dynamics simulation | — |
617

718
## 2023
8-
- Mycelium-fractal-net (MFN) initial codebase
9-
- gamma observation in BN-Syn spiking network simulations
10-
- GeoSync repository — Kuramoto synchronization + market microstructure
11-
- Adversarial Orchestration methodology formalized
19+
20+
| Milestone | Source |
21+
| --- | --- |
22+
| Mycelium-Fractal-Net (MFN) initial codebase | [`src/mycelium_fractal_net/`](../src/mycelium_fractal_net/) |
23+
| `γ ≈ 1.0` first observed in BN-Syn spiking-network simulations | external repo `BN-Syn` |
24+
| GeoSync repository created — Kuramoto synchronization × market microstructure | this repo |
25+
| Adversarial Orchestration methodology formalized | [`METHODOLOGY.md`](./METHODOLOGY.md) |
1226

1327
## 2024
14-
- gamma~1.0 hypothesis: metastable computation invariant across substrates
15-
- NFI architecture: ML-SDM, CA1-LAM, BN-Syn, MFN+
16-
- 6-substrate validation: zebrafish 0.967, Gray-Scott 1.000, Kuramoto 1.081,
17-
BN-Syn 0.959, NFI unified 0.8993, CNS-AI 1.059 (mean 0.994 +/- 0.077)
18-
- NeoSynaptex monorepo
19-
- GeoSync neuromodulation: serotonin ODE, dopamine TD, GABA gate, ECS Lyapunov
28+
29+
| Milestone | Source |
30+
| --- | --- |
31+
| `γ ≈ 1.0` hypothesis: metastable computation invariant across substrates | external research notes |
32+
| NFI architecture defined: ML-SDM, CA1-LAM, BN-Syn, MFN+ | external `NFI` repo |
33+
| 6-substrate validation, mean γ = 0.994 ± 0.077 (zebrafish 0.967, Gray-Scott 1.000, Kuramoto 1.081, BN-Syn 0.959, NFI unified 0.8993, CNS-AI 1.059) | external substrate logs |
34+
| NeoSynaptex monorepo created | external `NeoSynaptex` repo |
35+
| GeoSync neuromodulation layer: serotonin ODE, dopamine TD, GABA gate, ECS Lyapunov | [`src/geosync/`](../src/geosync/) |
2036

2137
## 2025
22-
- NeoSynaptex: 232 tests, 13 scientific gaps closed, Protocol 7X
23-
- GeoSync: HPC Active Inference v4, 9759+ tests
24-
- Physics Kernel: 57 invariants, AST-based 7-level validator
38+
39+
| Milestone | Source |
40+
| --- | --- |
41+
| NeoSynaptex: 232 tests, 13 scientific gaps closed, Protocol 7X | external `NeoSynaptex` repo |
42+
| GeoSync: HPC Active Inference v4 | [`src/geosync/`](../src/geosync/) |
43+
| Physics Kernel formalized: AST-based validator + invariant registry | [`.claude/physics/`](../.claude/physics/) |
2544

2645
## 2026-Q2
27-
- Cryptobiosis module (tardigrade-inspired phase-transition survival)
28-
- Ontology of Gradient (INV-YV1)
29-
- GeoSync v0.1.0 public release candidate
46+
47+
| Milestone | Source |
48+
| --- | --- |
49+
| Cryptobiosis module (tardigrade-inspired phase-transition survival) | [`.claude/physics/CRYPTOBIOSIS_THEORY.md`](../.claude/physics/CRYPTOBIOSIS_THEORY.md) |
50+
| Ontology of Gradient — invariant `INV-YV1` | [`.claude/physics/INVARIANTS.yaml`](../.claude/physics/INVARIANTS.yaml) |
51+
| GeoSync v0.1.0 public release candidate | repository tag |
52+
| Physics Kernel: **60 invariants** across 16 categories (40 P0 / 17 P1 / 3 P2) | derived from [`.claude/physics/INVARIANTS.yaml`](../.claude/physics/INVARIANTS.yaml) |
53+
| Parallel `physics_contracts/` law catalog: **26 module-anchored laws** | [`physics_contracts/catalog.yaml`](../physics_contracts/catalog.yaml) |
54+
| pytest suite size on `main`: ≈8.8k test functions across 844 files | derive via `grep -rh "^def test_" tests/ \| wc -l` |
55+
56+
## How to update this file
57+
58+
1. State the milestone in one line.
59+
2. Cite a source the reader can open today.
60+
3. If the milestone is a numeric claim, name the script that re-derives it,
61+
not the value. Numbers drift; commands stay valid until the schema changes.
62+
4. Any change to the substrate-validation block (2024) must be co-signed by a
63+
commit that also updates the underlying logs in the originating repo.

0 commit comments

Comments
 (0)