Skip to content

Commit e0e016d

Browse files
committed
docs: dispatch escape hatch, Kanban owns thinking styles, SurrealDB codegen path
Three corrections to the three-tier model: 1. Tool dispatch default = compile-time trait impl (zero-cost); classes that need runtime dispatch opt in via a dispatcher class escape hatch attached to a register — not the default, not in the substrate. 2. Thinking styles are owned by the Kanban (Tier 2), not the OGAR class (Tier 3). They are an O(1) lookup over I4-32D = 2^128 distinct addresses. The Rubicon phase selects the style; the class supplies schema + tools only. MappingRow.thinking_style is the wrong home. 3. SurrealDB AST resolves masked class selections as Elixir-syntax templates — a second codegen surface over the same build-known vs JIT-new (JITson/Cranelift/lance-graph-planner) split as Askama/Jinja. Two syntaxes, one backend, same two-track compilation model. https://claude.ai/code/session_0147hSzjmWZDuy2MSQNrhEK5
1 parent 69c3b12 commit e0e016d

1 file changed

Lines changed: 25 additions & 3 deletions

File tree

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

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -101,12 +101,20 @@ OGIT radix-trie codebook (O(1) for known classes at compile time)
101101
102102
├─ class identity string ("ogit-op/WorkPackage")
103103
├─ 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 ⚠)
104+
└─ label inheritance (parent, mixins, STI)
106105
107106
For new/runtime classes: JIT via lance-graph-planner (JITson / Cranelift)
108107
```
109108

109+
**Thinking style is owned by the Kanban (Tier 2), not the class.** The class
110+
does not dispatch a thinking style — the Kanban column does. Thinking styles
111+
are an **O(1) lookup over an I4-32D address space** (32 nibbles × 4 bits =
112+
128 bits = 2^128 distinct style addresses). The Rubicon phase the Kanban
113+
assigns selects the style; the OGAR class supplies schema + tools, not the
114+
style. (`MappingRow.thinking_style` as a per-class field is therefore the wrong
115+
home — the style belongs to the Kanban lifecycle state, addressed O(1) in the
116+
I4-32D space, not stored per ontology class.)
117+
110118
**MailboxId IS the NiblePath.** The `u32 mailbox_id` field in `MailboxSoA` is not
111119
a handle into a separate lookup — it IS the NiblePath key that the HHTL radix trie
112120
walks. No separate prefix field survives. This makes `entity_type: u16` in every
@@ -209,12 +217,18 @@ means. A class is:
209217
(`MappingRow`); never duplicated into SoA rows.
210218
- **Tools** — the methods / adapters that operate on the register. These are
211219
inherited from the class hierarchy (HHTL prefix ancestry = class ancestry).
212-
A subclass inherits all parent tools without restating them. The dispatch
220+
A subclass inherits all parent tools without restating them. The default
213221
mechanism is **compile-time Rust trait impls**: one `impl Tool for ClassFoo`
214222
per class, monomorphized at build time from the HHTL inheritance chain.
215223
Zero-cost — no vtable, no `dyn`, no runtime dispatch. "Cheap inherited
216224
registers" in the architecture doc is literal: the trait impl IS the register,
217225
and the compiler erases it to a direct call.
226+
227+
**Dispatch escape hatch.** Runtime dispatch is *not* the default and is not
228+
baked into the substrate. If a class genuinely needs runtime dispatch, it adds
229+
a **dispatcher class** as an escape hatch attached to a register — an opt-in,
230+
per-class override. The base case stays monomorphized and zero-cost; only the
231+
classes that ask for dispatch pay for it.
218232
- **Codegen templates** — Askama/Jinja `Class<Template>` views (see below).
219233
- **Active record** — the class instance wraps a slice of the register bank
220234
and provides the domain API. Methods come from the class hierarchy; data
@@ -253,6 +267,14 @@ struct by the Askama/Jinja template engine.
253267
(Cranelift backend). The template is instantiated at first encounter and
254268
compiled to native code. Same masked-selection semantics, deferred to first use.
255269

270+
**The template engine is not the only codegen front-end.** The SurrealDB AST can
271+
resolve the same masked selection as **Elixir-syntax templates**, but it is
272+
compiled through the *same* runtime split — known classes compiled at build time,
273+
new classes via JIT Cranelift / JITson in `lance-graph-planner`. Askama/Jinja and
274+
the SurrealQL/Elixir-template path are two surface syntaxes over one codegen
275+
backend; both bottom out at the build-known vs JIT-new split, never at runtime
276+
interpretation.
277+
256278
```
257279
OGAR Class { field_a, field_b, field_c, tool_x, tool_y, template_T }
258280

0 commit comments

Comments
 (0)