Skip to content

Commit 1eed37a

Browse files
claudeclaude
committed
docs: SoA three-tier model — zero-copy lifecycle, Kanban, OGIT/OGAR
Canonical architecture reference replacing any prior baton/emission framing. Three tiers: 1. MailboxSoA (primary): zero-copy in-place, creation → Lance tombstone. No emit(), no CollapseGateEmission, no inter-mailbox handoff type. last_active_cycle replaces last_emission_cycle (idempotency guard only). 2. KanbanColumn/Rubicon (sole secondary): Lance write → VersionScheduler (read-only) → KanbanMove → MailboxSoaOwner::advance_phase (sole mutator). Ractor (lance-graph-supervisor) provides actor-level meta-orchestration. 3. OGIT ontology + OGAR classes (inherited, O(1)): HHTL/NiblePath prefix → radix-trie codebook → class + schema + label inheritance (compile-time for known classes, JIT via lance-graph-planner for new ones). entity_type per-row may be redundant. surrealdb/kv-lance: BLOCKED(C). Includes full "what does NOT exist" table and six iron rules. https://claude.ai/code/session_0147hSzjmWZDuy2MSQNrhEK5
1 parent edf0a9d commit 1eed37a

1 file changed

Lines changed: 156 additions & 0 deletions

File tree

‎docs/architecture/soa-three-tier-model.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# SoA Three-Tier Model — Mailbox Lifecycle, Kanban, and Ontology
2+
3+
> **Branch:** `claude/stoic-turing-M0Eiq`
4+
> **Date:** 2026-06-06
5+
> **Authority:** Supersedes any prior baton/emission/CollapseGateEmission framing.
6+
7+
---
8+
9+
## The invariant
10+
11+
**Every SoA envelope is zero-copy from creation to Lance tombstone.**
12+
13+
There is no baton. There is no emission. There is no inter-mailbox handoff type.
14+
No bytes leave the backing store until Lance's own columnar I/O writes them to
15+
disk — and even then the in-memory store is unchanged, not serialized and
16+
freed.
17+
18+
---
19+
20+
## Tier 1 — MailboxSoA (primary, owned, zero-copy)
21+
22+
The `MailboxSoA<const N>` is the single thought envelope. One mailbox owns one
23+
SoA. The columns (`energy [f32;N]`, `plasticity [u8;N]`, `last_active_cycle [u32;N]`,
24+
`edges [CausalEdge64;N]`, `qualia [QualiaI4_16D;N]`, `meta [MetaWord;N]`,
25+
`entity_type [u16;N]`) are allocated once at mailbox creation and released at
26+
Lance tombstone.
27+
28+
```
29+
creation
30+
│
31+
▼
32+
MailboxSoA<N> (backing store in-place; column LE contract = MultiLaneColumn)
33+
│ (envelope LE contract = SoaEnvelope trait)
34+
│
35+
▼ Lance write on each version tick (LE bytes → columnar store)
36+
DatasetVersion(v) → DatasetVersion(v+1) → ...
37+
│
38+
▼
39+
Lance soft-delete (tombstone) ← sole lifecycle event that ends the store
40+
```
41+
42+
**Access contract:**
43+
- `MailboxSoaView`: read-only, `&[T]` borrows, `edges_raw() -> &[u64]`
44+
- `MailboxSoaOwner`: `advance_phase(&mut self, to: KanbanPhase)` — sole mutator
45+
46+
**Idempotency guard:** `last_active_cycle [u32;N]` marks the cycle a row was
47+
last written. It is a same-cycle guard, not a history column. (Rename from
48+
`last_emission_cycle` in source — the emission framing is wrong.)
49+
50+
**`MailboxSoA::emit()` and `CollapseGateEmission` in source are code artifacts
51+
from a superseded design and must be removed.** There is no inter-mailbox
52+
handoff type.
53+
54+
---
55+
56+
## Tier 2 — KanbanColumn / Rubicon lifecycle (sole secondary data)
57+
58+
The only data that is *secondary* to the SoA backing store is the Kanban
59+
phase. This is triggered by the Lance writer, not by the SoA itself.
60+
61+
```
62+
Lance writer → VersionScheduler::on_version(&view, at, exec)
63+
│ read-only &V: never mutates
64+
▼
65+
Option<KanbanMove> { mailbox, from→to, libet_offset_us }
66+
│ caller applies
67+
▼
68+
MailboxSoaOwner::advance_phase(to) ← SOLE mutator
69+
70+
KanbanPhase lifecycle (6 states):
71+
Planning → CognitiveWork → Evaluation → Commit → Plan → Prune
72+
```
73+
74+
Above the SoA mailboxes, ractor (`lance-graph-supervisor`, ractor 0.14,
75+
`supervisor` + `supervisor-lifecycle-audit` features) provides actor-level
76+
meta-orchestration. Each mailbox is a ractor actor. The single-owner invariant
77+
(no virtual ownership pointer needed) is enforced by Rust move semantics through
78+
ractor's message-passing model.
79+
80+
The Kanban column is the only data outside the SoA backing store that reflects
81+
SoA lifecycle. There is no baton, no emission stream, no secondary truth column.
82+
83+
---
84+
85+
## Tier 3 — OGAR classes + OGIT ontology (inherited, O(1))
86+
87+
The identity of a mailbox SoA resolves O(1) to its OGAR class and OGIT
88+
ontology schema. This is Tier 3 because it is *inherited*, not stored per-row.
89+
90+
**Resolution chain:**
91+
92+
```
93+
mailbox address (MailboxId + family prefix)
94+
│
95+
▼ HHTL / NiblePath prefix lookup
96+
│ NiblePath::is_ancestor_of:
97+
│ (other.path >> (4*(other.depth-self.depth))) == self.path
98+
│ = prefix ancestry = class ancestry (Confirmed)
99+
▼
100+
OGIT radix-trie codebook (O(1) for known classes at compile time)
101+
│
102+
├─ class identity string ("ogit-op/WorkPackage")
103+
├─ schema (fields, assoc, enums, attributes) — stored ONCE per class in OntologyRegistry
104+
├─ label inheritance (parent, mixins, STI)
105+
└─ thinking style (MappingRow.thinking_style — stored, currently unused at dispatch ⚠)
106+
107+
For new/runtime classes: JIT via lance-graph-planner (JITson / Cranelift)
108+
```
109+
110+
**`entity_type: u16` in SoA may be redundant.** If the ontology resolves O(1)
111+
from address, hardcoding a handle in every row violates SoC and defeats
112+
radix-trie cheapness. The current linear scan in `OntologyRegistry::
113+
enumerate_first_with_entity_type_id` is a defect — it should be an O(1)
114+
`Vec` index keyed by the 1-based ordinal.
115+
116+
**OGAR active record / DLL AST adapter:** OGAR classes get pragmatic mapping
117+
to inherited tools at compile time. These are cheap inherited registers, not
118+
per-instance data in the SoA. The `Adapter::map` static identity transform in
119+
OGAR + `KnowableFromStore` trait at the lance-graph boundary is the seam.
120+
121+
**surrealdb / kv-lance:** OGAR's DLL AST → SurrealQL path (`ogar-adapter-surrealql`)
122+
requires surrealdb with the `kv-lance` feature. This is BLOCKED(C) — the
123+
`kv-lance` feature is only in the AdaWorldAPI surrealdb fork, coordinates
124+
(git URL, branch) unknown. `surreal_container/Cargo.toml` dep is commented
125+
out pending resolution. **Do not fall back to crates.io surrealdb.**
126+
127+
---
128+
129+
## What does NOT exist (and must not be invented)
130+
131+
| Concept | Status |
132+
|---|---|
133+
| `CollapseGateEmission` as cross-mailbox carrier | **WRONG** — remove from source |
134+
| `MailboxSoA::emit()` | **WRONG** — remove from source |
135+
| "Baton" as inter-mailbox handoff | **WRONG** — superseded |
136+
| `wire_cost_bytes() = 13 + 10·baton_count` | **WRONG** — from CLAUDE.md E-BATON-1, now superseded |
137+
| `Vsa16kF32` as a cross-mailbox carrier | **WRONG** — deprecated, lives only as legacy `cycle` column in `BindSpace` |
138+
| Secondary data beyond KanbanColumn | **WRONG** — Kanban is the only secondary tier |
139+
| BindSpace as the envelope | **MIGRATION IN PROGRESS** — BindSpace is the global legacy; MailboxSoA is the target |
140+
141+
---
142+
143+
## Iron rules that fall out of this model
144+
145+
1. `MailboxSoA` backing store is never copied, never serialized, never transmitted.
146+
Lance writes LE bytes from it; the store itself stays in place.
147+
2. `VersionScheduler` is read-only (`&V`). It proposes; `MailboxSoaOwner` disposes.
148+
3. `MailboxSoA::emit()` and `CollapseGateEmission` are removed in the next
149+
pass — they are not part of the correct design.
150+
4. ractor provides the single-owner invariant for mailbox actors — no virtual
151+
ownership pointer is needed.
152+
5. Ontology resolution is O(1) HHTL prefix lookup for known classes. JITson
153+
for new ones. The `entity_type: u16` per-row handle may be eliminated once
154+
the O(1) lookup is the sole path.
155+
6. surrealdb requires the AdaWorldAPI fork with `kv-lance`. Never fall back to
156+
crates.io. BLOCKED(C) until fork coordinates are provided.

0 commit comments

Comments
 (0)