Skip to content

docs(.mermaid): architecture map of the DR / DT64 / mask-RISC stack (D-FOUNDRY-MAP-1) #1997

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AdaWorldAPI merged 1 commit into from
Nov 11, 2026
+2,236 −0
Merged

docs(.mermaid): architecture map of the DR / DT64 / mask-RISC stack (D-FOUNDRY-MAP-1) #1997

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
145 changes: 145 additions & 0 deletions .mermaid/01-stack-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,145 @@
# 01 — Stack overview

Status: describes what is in this checkout. Nothing here claims Foundry parity or a graphical low-code builder. Neither exists.

The stack is a set of layers. Each layer depends on the ones below it. Values stay in source-owned planes. Layers above the contract pass addresses, masks and witnesses.

Legend: green = in code on main, yellow = lab or probe crate (excluded from the root workspace), grey = another repository, red dashed = gap (not built).

## 1.1 Layers

An arrow from A to B means "A depends on B" in a `Cargo.toml` (see [02](02-crate-dependencies.md)). Dashed red boxes are work that no code does yet.

```mermaid
flowchart TB
classDef shipped fill:#d8f0d8,stroke:#2e7d32,color:#111
classDef lab fill:#fff3cd,stroke:#a67c00,color:#111
classDef ext fill:#eeeeee,stroke:#666,color:#111
classDef gap fill:#fadadd,stroke:#c62828,stroke-dasharray:5 3,color:#111

subgraph L0["contract: zero-dep types"]
CON["lance-graph-contract: ClassView, WideFieldMask, ScopeSpec, Marking"]:::shipped
end

subgraph L1["dt64: DR and DT64 binding"]
DT["lance-graph-dt64: BindStore, RouteLog, MapTable, FrameStore, LaneBinding"]:::shipped
end

subgraph L2["execution"]
MR["lance-graph-mask-risc: Program, MaskOp, execute"]:::shipped
QK["lance-graph-quack: Binder, Query, lower"]:::shipped
R2["lance-graph-r2il: FoldDialect, prepare, run"]:::shipped
XL["lance-graph-xlog: Cube, stage, commit"]:::shipped
RA["lance-graph-relalg: Rel, normalize, run"]:::lab
end

subgraph L3["authorization"]
RBAC["lance-graph-rbac: authorize_scoped"]:::shipped
OGA["OGAR: ogar-auth, ogar-rbac"]:::ext
end

subgraph L4["write and scenario"]
TG["thought-git-probe: commit_cycle, SlotPool, Receipt"]:::lab
end

subgraph L5["lab"]
LAB["foundry-parity-lab: 64-store read-only lab"]:::lab
end

G2["apply a decision to a binding, G2"]:::gap
G3["scenario overlay frame, G3"]:::gap
G4["write-back composed end to end, G4"]:::gap

DT --> CON
QK --> MR
QK --> CON
R2 --> MR
R2 --> DT
XL --> QK
XL --> DT
RA --> R2
RA --> MR
RBAC --> CON
OGA -->|git| RBAC
TG --> CON
LAB --> DT
LAB --> MR

RBAC -.-> G2
G2 -.-> DT
TG -.-> G3
G3 -.-> DT
R2 -.-> G4
XL -.-> G4
TG -.-> G4
```

Reading notes:

- The contract has no runtime dependencies. Every other layer builds on it.
- DT64 is the join. It ties a class, a route, a frame and a lane together and holds addresses only.
- The execution crates evaluate masks. `lance-graph-mask-risc` is the one bulk evaluator. Quack and r2il build programs for it. Quack's module doc says it may build a `Program` and must never evaluate one.
- Authorization is split. `lance-graph-rbac` has the generic kernel. OGAR supplies the login and the grant data, and calls that kernel.
- `thought-git-probe` is a probe. Its own doc says the full thought git API is a proposal and that it has no production land, rebase or persistence pipeline.
- `foundry-parity-lab` is read-only. Its doc says it has no write-back, no actions and no Foundry comparator.

Gaps in the diagram:

- **G2.** A `ScopedDecision` exists. Nothing applies it to a DT64 binding. See [04](04-read-path.md).
- **G3.** `SlotPool::branch` and `Cube::stage_closure` exist. A scenario overlay frame does not.
- **G4.** r2il can run an admitted method's effects through its fold dialect and returns a receipt. xlog has `stage` and `commit` for edges. thought-git has `commit_cycle`. No crate read here depends on more than one of the three. They are not composed into one write-back.

Sources:

- `crates/lance-graph-contract/Cargo.toml:10-17` (no runtime dependencies)
- `crates/lance-graph-dt64/src/lib.rs:1-30` (what DT64 binds and what it does not hold)
- `crates/lance-graph-mask-risc/src/lib.rs:1-20` (executor, oracle, tiled execution)
- `crates/lance-graph-quack/src/lib.rs:1-25` (operators lower to a `Program`; never evaluates)
- `crates/lance-graph-r2il/src/lib.rs:1-14` (fold reading of R2IL over mask-risc)
- `crates/lance-graph-xlog/src/lib.rs:1-20` (admitted chain query over Quack and mask-risc)
- `crates/lance-graph-relalg/src/lib.rs:1-27` (what it holds)
- `crates/lance-graph-rbac/src/authorize.rs:168-250` (`ScopedDecision`, `authorize_scoped`)
- `OGAR/crates/ogar-rbac/src/lib.rs:120-162` (`OgarRbac::authorize_user`)
- `crates/thought-git-probe/src/lib.rs:1-8` (probe status)
- `crates/foundry-parity-lab/src/lib.rs:1-26` (lab scope: read-only)
- `crates/lance-graph-xlog/src/cube.rs:856-945` (`stage`, `stage_closure`, `commit`)
- `crates/thought-git-probe/src/slots.rs:103-125` (`SlotPool::branch`)
- `crates/thought-git-probe/src/receipt.rs:153` (`commit_cycle`)
- `crates/lance-graph-r2il/src/binding.rs:1-20,321,377` (admitted effects, `prepare`, `run`)
- Cargo edges: see the sources of [02](02-crate-dependencies.md).

## 1.2 What each layer holds

| layer | crates | what it holds | what it does not do |
|---|---|---|---|
| contract | `lance-graph-contract` | Shared types: `ClassView`, `WideFieldMask`, `ScopeSpec`, `Marking`, set algebra | Run anything. It has no runtime dependencies |
| dt64 | `lance-graph-dt64` | Class schemas, method bindings (ON x WHEN x DO), the DR route log, the map table, frames, lane bindings | Hold values, evaluate, persist, or decide who may read |
| execution | `lance-graph-mask-risc`, `-quack`, `-r2il`, `-xlog`, `-relalg` | A flat program form, a name-to-number binder, an R2IL fold dialect, an admitted chain query, a relational rewrite | Loop over rows in the front ends. `mask-risc` is the only bulk engine |
| authorization | `lance-graph-rbac`, OGAR `ogar-auth` and `ogar-rbac` | Login to canonical user, grants by class, row scope, field mask | Reach the read path. G2 is open |
| write and scenario | `thought-git-probe` | Rubicon outcomes, a version-store stand-in, commit witnesses, receipts, a slot pool, squash gates | Run in production. It is a probe |
| lab | `foundry-parity-lab` | A 64-store fixture with an independent oracle, three arms (object, mask, INT8 cost) | Write, act, or compare against Foundry |

Sources:

- `crates/lance-graph-contract/src/class_view.rs:1057-1061` (`ClassView`)
- `crates/lance-graph-contract/src/rbac.rs:113-132` (`ScopeSpec`)
- `crates/lance-graph-dt64/src/lib.rs:24-30` (stored and not stored)
- `crates/lance-graph-quack/src/lib.rs:12-24` (the shapes it leaves out)
- `crates/lance-graph-r2il/src/lib.rs:1-14`
- `crates/lance-graph-xlog/src/lib.rs:1-26`
- `crates/lance-graph-relalg/src/lib.rs:1-27`
- `crates/thought-git-probe/src/receipt.rs:60-130` (`VersionStore`, `CommitWitness`, `CommitError`)
- `crates/thought-git-probe/src/fixtures.rs:28-40` (`Outcome`)
- `crates/thought-git-probe/src/squash.rs:96-100,290-300` (`squash_gate`, `protected_squash`)
- `crates/foundry-parity-lab/src/lib.rs:1-26`

## 1.3 Two limits worth knowing

- **No production issuer for execution permission.** `ExecPermit` in r2il is documented as a lab permission, not a production authorization. Who issues it is not decided. `BindStore::admit` succeeding is never a substitute for it.
- **Several records, no join drawn.** r2il returns a `Receipt` for a run. thought-git has its own `Receipt` and a `CommitWitness`. This overview draws no code that ties them to each other or to an authorization decision.

Sources:

- `crates/lance-graph-r2il/src/binding.rs:123-130` (`ExecPermit`)
- `crates/thought-git-probe/src/receipt.rs:80-100,366-380` (`CommitWitness`, `Receipt`)
- `crates/lance-graph-r2il/src/binding.rs:1-20,221-235` (r2il runs admitted effects; its `Receipt`)
180 changes: 180 additions & 0 deletions .mermaid/02-crate-dependencies.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,180 @@
# 02 — Crate dependencies

Status: every edge below was read from a `Cargo.toml`. Dev-only edges are listed in the table and left off the diagrams.

Legend: green = workspace member of the root `Cargo.toml`. Yellow = excluded from the root workspace (the crate is its own workspace root, or is a lab crate). Grey = another repository.

## 2.1 Edges inside lance-graph

Solid edges are path dependencies. Edges marked `git` use a git coordinate.

```mermaid
flowchart LR
classDef member fill:#d9f2d9,stroke:#2d7a2d,color:#111
classDef excl fill:#fff3cd,stroke:#a67c00,color:#111
classDef ext fill:#eeeeee,stroke:#666,color:#111

subgraph MEM["workspace members"]
CON["lance-graph-contract"]:::member
DT["lance-graph-dt64"]:::member
MR["lance-graph-mask-risc"]:::member
QK["lance-graph-quack"]:::member
R2["lance-graph-r2il"]:::member
XL["lance-graph-xlog"]:::member
RB["lance-graph-rbac"]:::member
end

subgraph EXC["excluded, own workspace root"]
RA["lance-graph-relalg"]:::excl
TG["thought-git-probe"]:::excl
LAB["foundry-parity-lab"]:::excl
end

ND["ndarray, git master"]:::ext
OGL["ogar-loco, OGAR git main"]:::ext
OGR["ogar-r2il, OGAR git main"]:::ext

DT --> CON
RB --> CON
MR -->|git| ND
QK --> MR
QK --> CON
R2 --> MR
R2 --> DT
R2 --> CON
R2 -->|git| OGL
R2 -->|git| OGR
XL --> QK
XL --> MR
XL --> DT
XL --> CON
XL -->|git| ND
RA --> MR
RA --> R2
RA --> CON
RA -->|git| OGL
RA -->|git| OGR
TG --> CON
LAB --> DT
LAB --> MR
LAB --> CON
LAB -->|git| ND
```

Reading notes:

- `lance-graph-contract` has an empty `[dependencies]` table. It has one build-dependency, `serde_yaml`, used only by `build.rs`.
- `lance-graph-dt64` and `lance-graph-rbac` depend on the contract and nothing else.
- `lance-graph-mask-risc`, `lance-graph-xlog` and `foundry-parity-lab` name ndarray directly. All three use the same git coordinate. The root `[patch]` points that coordinate at the sibling checkout, so the graph holds one ndarray package.
- `lance-graph-r2il` is a workspace member and still depends on two OGAR crates by git. `lance-graph-relalg` does the same and is excluded.
- `thought-git-probe` depends on the contract only.
- In this checkout `foundry-parity-lab` does not depend on `lance-graph-relalg`.

Sources:

- `Cargo.toml:6-37` (workspace members: contract line 7, mask-risc 8, quack 9, r2il 15, xlog 21, dt64 24, rbac 35)
- `Cargo.toml:133` (`lance-graph-relalg` in `exclude`)
- `Cargo.toml:221` (`thought-git-probe` in `exclude`)
- `Cargo.toml:240` (`foundry-parity-lab` in `exclude`)
- `Cargo.toml:500-515` (root `[patch]` for the contract and ndarray)
- `crates/lance-graph-contract/Cargo.toml:10-24` (empty dependencies, build-dependencies)
- `crates/lance-graph-dt64/Cargo.toml:8-10`
- `crates/lance-graph-mask-risc/Cargo.toml:19-20`
- `crates/lance-graph-quack/Cargo.toml:12-18`
- `crates/lance-graph-r2il/Cargo.toml:17-30`
- `crates/lance-graph-xlog/Cargo.toml:8-17`
- `crates/lance-graph-rbac/Cargo.toml:7-8`
- `crates/lance-graph-relalg/Cargo.toml:11-28`
- `crates/thought-git-probe/Cargo.toml:10-13`
- `crates/foundry-parity-lab/Cargo.toml:18-27`

## 2.2 Edges that cross into OGAR and back

lance-graph depends on OGAR through the r2il crates. OGAR depends on lance-graph through the contract and the rbac crate. Both directions use a git coordinate.

```mermaid
flowchart LR
classDef member fill:#d9f2d9,stroke:#2d7a2d,color:#111
classDef ext fill:#eeeeee,stroke:#666,color:#111

subgraph LG["lance-graph"]
CON["lance-graph-contract"]:::member
RB["lance-graph-rbac"]:::member
R2["lance-graph-r2il"]:::member
end

subgraph OG["OGAR"]
LOCO["ogar-loco"]:::ext
OR2["ogar-r2il"]:::ext
AUTH["ogar-auth"]:::ext
ORB["ogar-rbac"]:::ext
ENC["ogar-encryption"]:::ext
VOC["ogar-vocab"]:::ext
DIR["ogar-dir-core"]:::ext
end

R2 -->|git| LOCO
R2 -->|git| OR2
OR2 -->|path| LOCO
LOCO -->|git| CON
AUTH -->|path| ENC
AUTH -->|git| CON
ORB -->|path| AUTH
ORB -->|path| VOC
ORB -->|path| DIR
ORB -->|git| CON
ORB -->|git| RB
```

Reading notes:

- The root `[patch]` maps the git coordinate of `lance-graph-contract` to the workspace member. That keeps one contract package in the graph when OGAR crates pull it by git.
- There is no such patch for `lance-graph-rbac`. `ogar-rbac` fetches it from git `main`.
- `ogar-r2il` also lists `lance-graph-contract` by git, as a dev-dependency. It is not drawn.

Sources:

- `crates/lance-graph-r2il/Cargo.toml:25-26` (`ogar-loco`, `ogar-r2il` by git)
- `Cargo.toml:500-504` (`[patch."https://github.com/AdaWorldAPI/lance-graph"]`)
- `OGAR/crates/ogar-loco/Cargo.toml:26` (contract by git)
- `OGAR/crates/ogar-r2il/Cargo.toml:11-19` (`ogar-loco` by path; contract by git under `[dev-dependencies]`)
- `OGAR/crates/ogar-auth/Cargo.toml:13,20` (`ogar-encryption` by path, contract by git)
- `OGAR/crates/ogar-rbac/Cargo.toml:14,19,24,29,33` (`ogar-auth`, `ogar-vocab`, contract, `lance-graph-rbac`, `ogar-dir-core`)

## 2.3 Dependency table

"Dev" lists dev-dependencies, which are left off the diagrams.

| crate | in root workspace | direct dependencies | dev-dependencies |
|---|---|---|---|
| lance-graph-contract | member | none (runtime) | serde_yaml, serde, criterion (and `serde_yaml` as a build-dependency) |
| lance-graph-dt64 | member | contract | none |
| lance-graph-mask-risc | member | ndarray (git master) | causal-edge, contract |
| lance-graph-quack | member | mask-risc, contract | lance-graph-arm-discovery, causal-edge, deepnsm-v2 |
| lance-graph-r2il | member | mask-risc, dt64, contract, ogar-loco (git), ogar-r2il (git) | quack |
| lance-graph-xlog | member | quack, mask-risc, dt64, contract, ndarray (git master) | lance-graph-onnx |
| lance-graph-rbac | member | contract | none |
| lance-graph-relalg | excluded, own `[workspace]` | mask-risc, r2il, contract, ogar-loco (git), ogar-r2il (git) | none |
| thought-git-probe | excluded, own `[workspace]` | contract | none |
| foundry-parity-lab | excluded, own `[workspace]` | dt64, mask-risc, contract, ndarray (git master) | none |
| ogar-auth | OGAR | ogar-encryption, contract (git), crypto crates | not read |
| ogar-rbac | OGAR | ogar-auth, ogar-vocab, ogar-dir-core, contract (git), lance-graph-rbac (git) | not read |

How to build the excluded crates:

- `relalg`: `cargo test --manifest-path crates/lance-graph-relalg/Cargo.toml`.
- `thought-git-probe`: run from its own directory.
- `foundry-parity-lab`: `cargo test --release --manifest-path crates/foundry-parity-lab/Cargo.toml`.

Sources:

- `crates/lance-graph-quack/Cargo.toml:20-30` (dev-dependencies)
- `crates/lance-graph-r2il/Cargo.toml:32-36` (dev: quack)
- `crates/lance-graph-mask-risc/Cargo.toml:32-37` (dev-dependencies)
- `crates/lance-graph-xlog/Cargo.toml:19-21` (dev: onnx)
- `crates/lance-graph-contract/Cargo.toml:26-32` (dev-dependencies)
- `crates/lance-graph-relalg/Cargo.toml:8-11` (own workspace root)
- `crates/thought-git-probe/Cargo.toml:9-10` (own workspace root, run from its directory)
- `crates/foundry-parity-lab/Cargo.toml:6-7,18` (run commands, own workspace root)
- `OGAR/crates/ogar-auth/Cargo.toml:9-45` (dependencies)
- `OGAR/crates/ogar-rbac/Cargo.toml:9-33` (dependencies)
Loading