Skip to content

Commit e471f7c

Browse files
AdaWorldAPIAdaWorldAPI
committed
docs: substrate-endgame runtime view (mirror of OGAR master)
Tailored cross-repo view onto the substrate-b endgame architecture from lance-graph's runtime-side perspective. Master doc lives in AdaWorldAPI/OGAR/docs/SUBSTRATE-ENDGAME.md (five-rooms forward-looking architecture, 1345 lines). This view focuses on: - Room 1: lance-graph-contract, lance-graph-ontology, callcenter (commit_event sibling — PR #467, merged), planner::temporal (PR #468), supervisor, cognitive-shader-driver - Room 2: Kanban polyglot work-item trait, HTTP-sidecar bridge, §14 oracle harness, optional BEAM bridge - Room 3: callcenter actors per OGAR Class, version_watcher push stream, RubiconWriter Phase 2 dynamic regeneration for OP's Workflow table - Room 4: OpenTelemetry exposition, cognitive-event-row stream for sexy-tier viz, actor-tree topology API - Room 5: stable public API + SemVer, runtime getting-started, reference deployment Plus cross-references to OGAR's ADR doc (ADR-008 commit_event, ADR-009 temporal two-axis, ADR-018 Kanban polyglot are lance-graph- touching decisions) + companion runtime references + open items lance-graph owns + compact priority map. Pure docs; navigation aid for runtime sessions picking up the endgame architecture without re-reading the full OGAR master. https://claude.ai/code/session_01PBTGaPCSnnt6u3pjXpbLwY
1 parent 73ac9b0 commit e471f7c

1 file changed

Lines changed: 295 additions & 0 deletions

File tree

‎docs/SUBSTRATE-ENDGAME-RUNTIME-VIEW.md‎

Lines changed: 295 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,295 @@
1+
# Substrate Endgame — runtime view (lance-graph slice)
2+
3+
> **Purpose.** Tailored view onto the substrate-b endgame architecture
4+
> from `AdaWorldAPI/lance-graph`'s perspective. The master doc lives in
5+
> `AdaWorldAPI/OGAR/docs/SUBSTRATE-ENDGAME.md` (full five-rooms map);
6+
> this doc highlights the runtime-side slice and cross-references the PRs
7+
> in this repo that land each room's runtime dependencies.
8+
>
9+
> **Why a tailored view.** The endgame architecture spans four repos
10+
> (OGAR, lance-graph, ractor_actors, openproject-nexgen-rs) plus the
11+
> ruff fork producers and the surrealdb fork DDL builders. The master
12+
> doc in OGAR is comprehensive but spans all of it. This view lets a
13+
> lance-graph session pick up the runtime-side concerns without reading
14+
> the full master (which they should still read for context).
15+
>
16+
> Companion: `OGAR/docs/ARCHITECTURAL-DECISIONS-2026-06-04.md` (ADR-style
17+
> backward-looking session capture). ADR-008 (`commit_event` sibling)
18+
> and ADR-009 (`temporal` two-axis engine) are the lance-graph-owned
19+
> decisions; ADR-018 (Kanban polyglot dispatcher) is the runtime-side
20+
> architecture this view foregrounds.
21+
>
22+
> Status: **CARVED v0** (2026-06-05). Mirror of `OGAR/docs/SUBSTRATE-
23+
> ENDGAME.md` for runtime-side concerns. Master doc is authoritative;
24+
> this view stays consistent with it on per-quarter review.
25+
26+
## 0. Five-rooms map — what lance-graph owns
27+
28+
```
29+
ROOM 1 (TODAY) What lance-graph ships
30+
───────────────────── ─────────────────────────────────────────
31+
substrate primitives ──► lance-graph-contract (canonical types)
32+
lance-graph-ontology (OntologyRegistry,
33+
MappingProposal, SchemaSource, TTL
34+
hydrators incl. wikidata_hhtl)
35+
lance-graph-callcenter (LanceMembrane +
36+
commit_event sibling — PR #467, merged)
37+
lance-graph-planner::temporal (classify +
38+
deinterlace + EpistemicMode + HLC-aware
39+
QueryReference + DependsClosure trait
40+
— PR #468, open)
41+
lance-graph-supervisor (ractor-supervised
42+
callcenter actor tree)
43+
cognitive-shader-driver (CognitiveEventRow,
44+
Markov ±5 trajectory)
45+
46+
ROOM 2 (MIGRATION SCAFFOLD) What lance-graph adds
47+
───────────────────────── ─────────────────────────────────────
48+
Kanban polyglot interface ──► formalize the work-item trait that admits
49+
multiple executable forms (native ractor
50+
handler / BEAM call / interpreter / HTTP
51+
sidecar / CRuby / reflection-dump)
52+
— Kanban primitive in SOA-IMPLEMENTATION §5.2
53+
— new work-item-form-registration trait
54+
55+
§14 oracle harness ──► record-replay protocol for per-actor
56+
graduation verification:
57+
record(migration form) -> tape ->
58+
replay(native candidate) -> verdict
59+
bucket (PASS / DIVERGENT-RECONCILABLE /
60+
DIVERGENT-FAULTY / INDETERMINATE)
61+
62+
HTTP-sidecar bridge ──► Rust HTTP client issuing per-action POSTs
63+
to a Rails Puma sidecar; decoding responses
64+
to Transition<State> + commit row
65+
66+
BEAM bridge (optional) ──► Erlang Port or NIF for HIRO/Bardioc-side
67+
migration; alternative: tiny Elixir AST
68+
interpreter crate
69+
70+
ROOM 3 (OP-AS-OPERATOR-PANE) What lance-graph enables
71+
───────────────────────── ─────────────────────────────────────
72+
OP hosted on substrate ──► callcenter actors per OGAR Class
73+
(WorkPackage, Project, Status, etc.)
74+
Hotwire / version_watcher push stream
75+
for live UI updates
76+
77+
Workflow → live Rubicon ──► RubiconWriter Phase 2 supports dynamic
78+
regeneration when Workflow table rows
79+
change (operator admin UI edits propagate
80+
to in-process Rubicon machines without
81+
restart)
82+
83+
ROOM 4 (VISUALIZATION) What lance-graph emits
84+
───────────────────── ─────────────────────────────────────
85+
OpenTelemetry exposition ──► Lance commits/sec, ractor mailbox depth,
86+
Rubicon transition counters, temporal
87+
classify ratios (CONTEMPORARY /
88+
ANACHRONISTIC / SPOILER), HLC drift,
89+
§14 verdict ratios — standard Prometheus
90+
metric exposition
91+
92+
Substrate event stream ──► version_watcher → WebSocket / SSE for
93+
live operator-UI updates; cognitive-event-
94+
row stream for sexy-tier visualizations
95+
96+
ROOM 5 (SDK ENDGAME) What lance-graph contributes
97+
───────────────────── ─────────────────────────────────────
98+
Stable public API ──► SemVer-pin lance-graph-contract /
99+
lance-graph-ontology / lance-graph-planner /
100+
lance-graph-callcenter (each ratchets to 1.0
101+
on their own timeline)
102+
103+
Runtime documentation ──► getting-started for substrate runtime
104+
consumers (separate from OGAR's
105+
producer-side getting-started)
106+
107+
Reference deployment ──► substrate-b hosting OP in production;
108+
prove the runtime side end-to-end
109+
```
110+
111+
## 1. What lance-graph owns in each room (detail)
112+
113+
### 1.1 Room 1 — current floor (shipped on `main`)
114+
115+
- **`lance-graph-contract`** — zero-dep canonical types
116+
(`Schema`, `LinkSpec`, `SemanticType`, `Marking`, `PropertySpec`,
117+
`Cardinality`, `CodecRoute`, `ExternalMembrane`). Implementation
118+
crates depend on this; this crate depends on nothing. Status: stable.
119+
- **`lance-graph-ontology`** — `OntologyRegistry` + `MappingProposal`
120+
+ `SchemaSource` trait + TTL hydrators (SKOS, PROV-O, schema.org,
121+
FIBO, Odoo, ZUGFeRD, SKR03/04, **`wikidata_hhtl`**) + 47KB Lance
122+
dictionary cache. `odoo_blueprint` provides 15-lane typed
123+
`OdooEntity` consts (OGAR's runtime-IR equivalent for Odoo source).
124+
Status: stable; `lance-bind` Sprint-5b is the receiver of OGAR-side
125+
`MappingProposal` flow.
126+
- **`lance-graph-callcenter`** — `ExternalMembrane` impl;
127+
`LanceMembrane::commit_event(row: CognitiveEventRow) -> u64`
128+
sibling shipped in **PR #467, merged**. Pairs with
129+
`ExternalMembrane::project()` (cognitive-cycle path). Action-commit
130+
path skips `ShaderBus`. Per ADR-008.
131+
- **`lance-graph-planner::temporal`** — the deinterlace engine, in
132+
**PR #468 (open as of 2026-06-04 → may be merged by future
133+
sessions)**. Surface: `EpistemicMode {Strict, Aware, Retro}` +
134+
`QueryReference {server_id, ref_version, hlc_tick: Option<u64>,
135+
mode, rung}` + `classify(row_version, knowable_from, v_ref) ->
136+
Classification` + `deinterlace(rows, v_ref, deps)` +
137+
`DependsClosure` trait (TIME-causal `hlc_tick` + DATA-causal
138+
`DependsClosure` axes). Per ADR-009.
139+
- **`lance-graph-supervisor`** — ractor-supervised callcenter actor
140+
tree (PR-G2 / TD-RACTOR-SUPERVISOR-5).
141+
- **`cognitive-shader-driver`** — cognitive-cycle row producer
142+
(the substrate's other write path; co-located with Lance).
143+
144+
### 1.2 Room 2 — migration-scaffold runtime side
145+
146+
Three pieces lance-graph adds for the Kanban-as-polyglot-dispatcher
147+
pattern (per ADR-018):
148+
149+
1. **Work-item-form trait** — the Kanban dispatcher's interface that
150+
admits multiple executable forms (native ractor handler / BEAM
151+
call / interpreter / HTTP RPC / CRuby FFI / reflection-dump-only).
152+
Probably lives in `lance-graph-callcenter` next to the existing
153+
actor registration. Architecture pinned in OGAR PR #20
154+
(`SUBSTRATE-ENDGAME.md §2`); implementation pending.
155+
156+
2. **HTTP-sidecar bridge** — Rust client issuing `POST /api/v3/...`
157+
to a Rails Puma deployment, decoding JSON responses to
158+
`Transition<State>` + commit row. Engineering: standard HTTP
159+
client + retry/auth/telemetry; new crate or module in callcenter.
160+
161+
3. **§14 oracle harness** — record-replay infrastructure for
162+
per-actor graduation verification. Per `SUBSTRATE-ENDGAME.md §2.4`:
163+
record tape against migration form, replay against native
164+
candidate, compare provenance-normalized, emit verdict bucket.
165+
166+
Optional fourth: **BEAM bridge** (Erlang Port or NIF) for HIRO/Bardioc
167+
migration. Alternative: tiny Elixir AST interpreter crate.
168+
169+
### 1.3 Room 3 — OP-as-operator-pane runtime side
170+
171+
When OP graduates onto substrate-b per Room 2:
172+
173+
- **Callcenter actors per OGAR Class** — OP's WorkPackage, Project,
174+
Status, User, Role, Workflow each get a ractor actor in the
175+
substrate's supervision tree.
176+
- **Hotwire / version_watcher push stream** — OP's existing
177+
WebSocket / Hotwire stream wires through to
178+
`lance-graph-callcenter::version_watcher` so the UI updates from
179+
substrate state directly.
180+
- **RubiconWriter Phase 2 dynamic regeneration** — when OP's
181+
Workflow table rows change (operator admin UI), the in-process
182+
Rubicon machine for the affected class regenerates without
183+
restart. Requires Rubicon-from-OGAR codegen to support dynamic
184+
emission; runtime session's Phase 2 work.
185+
186+
### 1.4 Room 4 — visualization tier-stack runtime side
187+
188+
The substrate is observable by design; runtime exposes the metrics:
189+
190+
- **OpenTelemetry / Prometheus exposition** from existing
191+
instrumentation crates. Standard `tracing-opentelemetry` setup;
192+
emit per-actor and per-class metrics, Lance-dataset stats,
193+
deinterlace ratios.
194+
- **Cognitive-event-row stream** for sexy-tier visualizations.
195+
Existing `cognitive-shader-driver` row producer; expose via
196+
WebSocket / SSE for the four-frame deinterlace visualizer + the
197+
cognitive trajectory animation.
198+
- **Actor-tree topology API** — runtime endpoint exposing the live
199+
supervision tree shape for 3D-topology visualizations
200+
(CytoscapeJS / three.js).
201+
202+
### 1.5 Room 5 — SDK endgame runtime side
203+
204+
- **Stable public API across lance-graph crates** — each crate
205+
ratchets to 1.0 on its own timeline; SemVer pinning; deprecation
206+
paths documented; cross-crate version compatibility matrix.
207+
- **Runtime getting-started doc** — for substrate consumers
208+
(separate from OGAR's producer-side getting-started). Cover:
209+
setting up a Lance dataset, registering classes via SchemaSource,
210+
dispatching work-items through callcenter, reading via temporal
211+
classify, etc.
212+
- **Reference deployment** — substrate-b hosting OP in production;
213+
the visible run-time validation point.
214+
215+
## 2. Cross-references
216+
217+
### 2.1 Master doc (OGAR)
218+
219+
- `AdaWorldAPI/OGAR/docs/SUBSTRATE-ENDGAME.md` — the comprehensive
220+
five-rooms architecture; this view is the runtime slice.
221+
- `AdaWorldAPI/OGAR/docs/ARCHITECTURAL-DECISIONS-2026-06-04.md` —
222+
ADR-style backward-looking session capture; ADR-008 (commit_event),
223+
ADR-009 (temporal two-axis), ADR-018 (Kanban polyglot) are the
224+
lance-graph-touching decisions.
225+
- `AdaWorldAPI/OGAR/docs/OGAR-AST-CONTRACT.md` — the typed surface
226+
callcenter actors lower onto; §3 binding references temporal +
227+
CommitHook + commit_event.
228+
- `AdaWorldAPI/OGAR/docs/SURREAL-AST-AS-ADAPTER.md` — structural-vs-
229+
behavioral decision (ADR-016); §6 covers migration scaffold
230+
counterpoint.
231+
232+
### 2.2 Companion runtime references
233+
234+
- `AdaWorldAPI/ractor_actors` — `feat/state-machine-actor @ 38a71a4`
235+
is the canonical `StateMachine` crate Rubicon-from-OGAR binds onto
236+
(per ADR-007).
237+
- `AdaWorldAPI/lance-graph/PR #467` — `LanceMembrane::commit_event`
238+
sibling (merged).
239+
- `AdaWorldAPI/lance-graph/PR #468` — `temporal::classify` +
240+
`deinterlace` + `DependsClosure` (open as of 2026-06-04).
241+
- `AdaWorldAPI/bardioc/CROSS_SESSION_COORDINATION.md` — the
242+
authoritative cross-session coord doc (runtime-session-owned).
243+
`knowable_from` meet-point pin (per ADR-010) mirrors from
244+
`OGAR/docs/OPENPROJECT-TRANSCODING.md §10.3`.
245+
246+
## 3. Open items lance-graph owns
247+
248+
In addition to the in-flight items listed in OGAR's master doc:
249+
250+
- **Cross-server HLC merge policy** — `QueryReference.hlc_tick: Option<u64>`
251+
is HLC-aware in signature; cross-server merge policy is deferred
252+
body work. Lands when peer-Raft / cluster bus comes online.
253+
- **`temporal::deinterlace` postpone-replay-ordering test at scale** —
254+
single-actor FIFO is verified; multi-actor concurrent postpone-
255+
queue interaction at scale is the harder property.
256+
- **Work-item-form trait + per-actor registration table** — Room 2
257+
primary lance-graph work item.
258+
- **§14 oracle harness** — record-replay infrastructure. Pairs with
259+
the OGAR-side producer; runtime owns the storage + replay layer.
260+
- **RubiconWriter Phase 2** (Rubicon's durable home + `KvLanceWriter`
261+
backend) — pairs with `LanceMembraneWriter`; both share the same
262+
Lance 7.0.0 commit contract.
263+
264+
## 4. Doc lifecycle
265+
266+
- **Author:** OGAR session 2026-06-04 (placed cross-repo 2026-06-05).
267+
- **Status:** Mirror view; master in OGAR.
268+
- **Update cadence:** when the master doc (`OGAR/docs/SUBSTRATE-
269+
ENDGAME.md`) updates, mirror relevant changes here. When
270+
lance-graph-side items graduate (e.g. Room 2 work-item trait
271+
lands), add a one-line update to the relevant section.
272+
- **Authority:** master in OGAR. This view is for navigation;
273+
decisions cite OGAR docs.
274+
275+
## 5. Compact map — runtime-side dependencies
276+
277+
For the runtime session to pick up where this view leaves off, in
278+
approximate priority order:
279+
280+
1. **`lance-graph PR #468` lands `temporal` on main** — unblocks
281+
downstream consumers (Rubicon's repointing from local placeholder
282+
to the canonical `temporal::classify`).
283+
2. **Rubicon's durable home + Phase 2** — `RubiconWriter` two
284+
backends (`LanceMembraneWriter` + `KvLanceWriter`).
285+
3. **Work-item-form trait in callcenter** — enables Room 2.
286+
4. **HTTP-sidecar bridge** — first migration scaffold variant.
287+
5. **§14 oracle harness** — verifies graduation.
288+
6. **First OP per-actor graduation end-to-end** — `WorkPackage#save`
289+
via HTTP sidecar → native ractor handler.
290+
7. **OpenTelemetry exposition + Grafana panels** — Boring tier
291+
visualization.
292+
8. **Stable public API + SemVer pinning** — Room 5 prep.
293+
294+
Each unlocks the next; total timeline per master doc §6.7 is
295+
12-24 months from Room 1 to demonstrable Room 5.

0 commit comments

Comments
 (0)