A Rust library for embodied agents: typed shared-memory arenas, crash-safe evidence logs, session
storage, a JEPA model runtime with evidence-gated promotion, and the CUDA/Metal compute backends the
kernels run on. The layered sensing, belief and action programs in runners/ are built on it.
The workspace builds on Windows, macOS and Linux. Kernels are developed and verified on an RTX 4090,
with the Jetson Orin Nano (8 GB of VRAM, sm_87) as the deployment target.
| Module | Crates | What it provides |
|---|---|---|
| Foundations | types, shm, ipc |
Shared types, the typed shared-memory arena, and process-to-process transport. |
| State sync | sync-types |
Versioned sync envelopes and the CRDT merges that fold them. |
| Evidence | mcap-log |
Crash-safe MCAP segments; partial writes quarantine instead of being lost. |
| Sessions | session-store |
SQLite-backed sessions, epochs, missions and their parameters. |
| Models | jepa, jepa-dataset, jepa-model |
The JEPA runtime: dataset manifests and integrity gates, evaluation, planning. |
| Promotion | jepa-registry |
Candidate generation, evidence gates, and the atomic pointer swap. |
| Compute | cuda, metal |
Kernels behind feature flags, each with a CPU fallback that runs anywhere. |
| Streaming | rerun-bridge |
Rerun streams for recorded sessions. |
| Runners | runners/* |
The sensing, belief, action and operations programs built on the library. |
epics.mmd — the ticket dependency graph. Arrows point from blocker to blocked.
flowchart LR
subgraph E1["Publish"]
T01
T02
T03
end
subgraph E2["Fixtures the tests stand on"]
T04
T05
end
subgraph E3["The connectome prior"]
T06
T07
T08
T09
end
subgraph E4["The belief matrices take the prior"]
T10
T11
T12
T13
end
subgraph E5["The circuit simulator, behind a flag"]
T14
T15
end
subgraph E6["Perception and action kernels on the 4090, then the Orin"]
T16
T17
T18
end
subgraph E7["Missions, memory and self-healing braided"]
T19
T20
T21
T22
end
subgraph E8["Exploration first, governed by the fly"]
T23
T24
T24b
end
subgraph E9["Self-improvement: the agent in the loop"]
T30
T31
T32
end
subgraph E10["The harness front end, rebuilt in the open"]
T25
T26
T27
end
subgraph E11["The neuro-symbolic seam and the healing ladder"]
T33
T34
T35
T36
end
subgraph E12["The public record"]
T37
T37b
T38
end
subgraph E13["The mark and the high-definition journal"]
T39
T40
T41
T42
T43
end
subgraph E14["The operating model: GitHub as state, mage as evidence, subagent swarms"]
T44
T45
T46
T47
T48
end
subgraph E15["Verify on the 4090, then the Nano"]
T28
T29
end
T01 --> T02
T01 --> T03
T01 --> T04
T04 --> T05
T05 --> T06
T06 --> T07
T07 --> T08
T08 --> T09
T05 --> T10
T10 --> T11
T11 --> T12
T12 --> T13
T09 --> T14
T14 --> T15
T05 --> T16
T16 --> T17
T17 --> T18
T05 --> T19
T19 --> T20
T19 --> T21
T20 --> T22
T19 --> T23
T23 --> T24
T24 --> T24b
T44 --> T25
T45 --> T25
T25 --> T26
T26 --> T27
T27 --> T28
T32 --> T28
T36 --> T28
T43 --> T28
T48 --> T28
T28 --> T29
T22 --> T30
T30 --> T31
T31 --> T32
T22 --> T33
T19 --> T34
T34 --> T35
T35 --> T36
T45 --> T37
T37 --> T37b
T37 --> T38
T39 --> T40
T40 --> T41
T40 --> T42
T42 --> T43
T01 --> T44
T44 --> T45
T44 --> T46
T45 --> T47
T44 --> T48
agents.mmd — the operating loop, including the failure edge.
flowchart TD
A[read epic issue] --> B[list status:ready tickets]
B --> C[claim: assignee + braid comment + status:claimed]
C --> D[work: tests first]
D --> E[open PR, description starts with braid block]
E --> F[comment breadcrumb: state review]
F --> G{three reviewers approve?}
G -- yes --> H[merge, close ticket, status:done]
G -- no --> D
C -. "agent dies" .-> X[label resume]
D -. "agent dies" .-> X
X --> Y[a later agent reads the last braid block]
Y --> D
B -. "blocked" .-> Z[status:blocked + blocked_on]
Z --> Y
states.mmd — the ticket state machine over the status:* labels.
stateDiagram-v2
[*] --> ready
ready --> claimed: claim (assignee + braid comment)
claimed --> working: first breadcrumb state: working
working --> review: PR opened
review --> done: merge + Closes #n
review --> claimed: review request-changes
working --> blocked: blocked_on filled
claimed --> blocked: blocked_on filled
blocked --> ready: unblock
claimed --> ready: claim stale > 4h (relabel resume)
working --> ready: claim stale > 4h (relabel resume)
done --> [*]
journal.mmd — the publishing pipeline.
flowchart LR
SRC[sources: epic issue, ticket comments, braid breadcrumbs,\ndocs/evidence captures, git log] --> WR[writer agent\nprimary sources only]
WR --> DRAFT[draft PR\n<!-- ASK: --> for anything unsupported]
DRAFT --> ACC[accuracy editor]
DRAFT --> TEA[teaching editor]
DRAFT --> STY[style editor]
ACC -- "request-changes" --> WR
TEA -- "request-changes" --> WR
STY -- "request-changes" --> WR
ACC -- "approve" --> GATE{all three approve?}
TEA -- "approve" --> GATE
STY -- "approve" --> GATE
GATE -- yes --> MERGE[merge]
MERGE --> LIVE[live URL + figures return 200]
LIVE --> EPIC[epic ## Journal line filled]
The .mmd files under docs/architecture/ are the source; the blocks above are
copies of them.
GitHub is the state. An epic is an issue, a ticket is an issue, a claim is an assignee plus a
handoff comment, and any later agent can parse the breadcrumb. See
docs/agents.md, docs/waves.md, and
docs/decisions.md.
Entries are written as their tickets land, not reconstructed afterwards.
| Entry | Epic |
|---|---|
| the licence and the snapshot | EPIC-01 |
| the connectome as a prior | EPIC-02, EPIC-03 |
| the fly in the belief matrices | EPIC-04, EPIC-05, EPIC-06 |
| the fly brain on the robot | EPIC-06 |
| the agent in the loop | EPIC-07, EPIC-08, EPIC-08B |
| the front end, rebuilt from lessons | EPIC-09 |
| the ladder | EPIC-08C |
| the public record | EPIC-09B |
| the mark | EPIC-11 |
| the operating model | EPIC-12 |
| the 4090 and the Nano | EPIC-10 |
Apache-2.0. See LICENSE and NOTICE. This repository is a clean-room rewrite:
no file is copied from any private repository.