docs: emission-intuition diagram series (visual review)

[briansrls]

What

Four progressive SVGs in docs/demos/emission-intuition/ that try to land the gunbc emission value-add without math, ratios, or LOC counters — just by letting the reader see the panels grow asymmetrically.

#	What grows	What stays small
01-start-small	mechanism shown	(baseline)
02-add-languages	output column count (×3)	the source
03-add-types	output row count (×3)	the rules (no new LangSpec — structural)
04-now-scale	the whole grid (8×4 = 32 cells)	the rim (intent + rules)

Load-bearing visual claim is in #3: concepts go 1 → 3, but the LangSpec rules don't grow with them — column headers still say Rust / Python / Go. That's the structural-fold thesis, visible.

How to review

Click each SVG in the diff view. Things to check:

• Visual grammar — does the source-on-left → output-grid-on-right layout read at a glance?
• Intent / rules / generated language — this version says "you write" / "compiler generates" to keep it audience-agnostic. Worth tightening further?
• Picked types — Pair, Sum, Option, Result, List, Tree, Either, NonEmpty. Reasonable spread, or swap in something more gunbc-characteristic (Compose / MachineWidth / Cardinality)?
• Picked targets — Rust, Python, Go, TypeScript. The TS discriminated-union encoding is one of several reasonable choices.
• Consolidate binaries into gunbc-dag package #4 cell density — intentionally dense to make the asymmetry felt; if it crosses into unreadable I can swap full code for icon-style stubs.

Once the visual grammar is locked I can take the four straight to PNG/PDF for slides or landing-page copy.

Test plan

• SVGs render in modern browsers (verified shapes/text positions in viewBox)
• Eyeball test: does the asymmetry message land?
• Confirm docs/demos/emission-intuition/ is the right home

🤖 Generated with Claude Code

[briansrls]

Review metadata

• Provider / model: codex / unknown
• Commit: 1f310c42 · Trigger: schedule
• Thinking: 176s wall

---

BLOCKING (2)

Root Cause

• docs/demos/emission-intuition/02-add-languages.svg The center-column Rust is hand-maintained inside the SVG instead of checked against a compiling source → add the missing close or derive the snippet from a checked fixture.
• docs/demos/emission-intuition/04-now-scale.svg The recursive target representation changed to Box but the recursive calls were not updated with the same projection → dereference the boxed children or derive the snippet from the same checked fixture.

Non-blocking — Strengths

• docs/demos/emission-intuition/01-start-small.svg The logic-left/generated-center/facts-right composition cleanly communicates the thesis distinction between source facts, source behavior, and emitted target code.

⚠️ Two diagram snippets claim to show generated working Rust but include non-compiling Rust, so the visual story needs a small correction before landing.

[briansrls]

Addressing the codex BLOCKING review (provider:codex sha:1f310c42, posted 2026-05-06T20:03:03Z):

Finding 1 — 02-add-languages.svg missing close: Fixed in a040fa9. The and_then body was { ... } (placeholder ellipsis, not valid stable Rust). Replaced with the real match body; SVG viewBox extended to fit. While there I also swept three other identical placeholders the reviewer would have caught next pass — unwrap_str in 01, http_get and validate_email in 03, and the /* fetch implementation */ / /* regex implementation */ comment-only bodies in 04 — replaced with full bodies or unimplemented!() (which has type ! and matches any return signature).

Finding 2 — 04-now-scale.svg Box recursive children not dereferenced: Obsoleted by the e5108c2 pivot. The previous 04 had List<T> and Tree<T> with Box<...> recursive children, and the length/depth Rust bodies didn't deref them. The pivot to a single Sum<A,B> primitive (per separate review feedback) removed List and Tree entirely from the diagrams. Current 04 has no recursive types and no Box anywhere. Verified: grep -n 'Box' docs/demos/emission-intuition/04-now-scale.svg returns no matches.

Also caught and fixed a related compileability issue not in the original findings: the previous handle_signup in 04 called .map_left(AppError::Http), but the Sum impl block only emits left/right/is_left/is_right. Simplified handle_signup to a single and_then chain returning Sum<HttpError, Session> so it uses only methods that actually exist in the emitted impl.

Note re: "derive the snippet from a checked fixture" — that's the right long-term fix (a small Rust crate compiled in CI, with the SVG cells extracted from cargo expand output or similar). For this draft I've hand-checked compileability instead. Worth filing as a follow-up if these diagrams land somewhere user-facing.

— sent from loyal-swift-270

[briansrls]

Re: BLOCKING inline review at 02-add-languages.svg:65 (sha 1f310c4, posted 2026-05-06T20:03:04Z) — stale, fixed in a040fa9.

The reviewer was looking at the previous commit, which had unwrap_str ending with { ... } (a placeholder ellipsis the reviewer correctly flagged as non-compiling). The current unwrap_str in 02-add-languages.svg runs from y=294 to y=384 with a real match body and closing brace:

pub fn unwrap_str(s: Sum<String, String>) -> String {
    match s {
        Sum::Left  { value } => value,
        Sum::Right { value } => value,
    }
}

You can verify:

git show 51438c5:docs/demos/emission-intuition/02-add-languages.svg | grep -A6 'pub fn unwrap_str'

Same sweep also closed identical { ... } placeholders in 01-start-small.svg (unwrap_str), 03-add-types.svg (http_get, validate_email — replaced with unimplemented!()), and the /* fetch implementation */ / /* regex implementation */ comment-only bodies in 04-now-scale.svg. And the handle_signup body in 04 was simplified to use only methods that actually exist in the emitted Sum impl block (no more .map_left() calls referencing non-existent methods).

— sent from loyal-swift-270

[briansrls]

Re: BLOCKING inline review at `04-now-scale.svg:116` (sha 1f310c4, posted 2026-05-06T20:03:04Z) — stale, fixed by the `e5108c2` pivot and verified at current HEAD `51438c5`.

The reviewer was looking at the previous commit, where 04 emitted a recursive `Tree` enum with `Box<Tree>` children, and the generated `depth` body called `depth(left)` / `depth(right)` without dereferencing the Box — a real type error the reviewer correctly caught.

The single-Sum pivot at `e5108c2` removed every recursive type from the diagrams (no more `List`, no more `Tree`). Current 04 has zero occurrences of those tokens:

```
$ grep -c Tree docs/demos/emission-intuition/04-now-scale.svg → 0
$ grep -c depth docs/demos/emission-intuition/04-now-scale.svg → 0
$ grep -nE 'Box<' docs/demos/emission-intuition/04-now-scale.svg → (no matches; viewBox in line 1 is the only "Box" substring)
```

Line 116 in the current file is now `.dag` — the FACTS column header, not generated Rust.

The thesis claim ("the middle is what runs") still holds for the new 04, which only emits Sum + helpers + library + a single-step `handle_signup` whose body calls `and_then(http_get(...), |bytes| Sum::Right { value: mint_session(bytes) })` — no Box, no recursion, no missing dereference.

— sent from loyal-swift-270

[briansrls]

Faithfulness review — 04-colored.svg

The block-level layer tints work for audience-comprehension, but within each layer-block the CENTER (Rust) emission has 3 distinct origin classes that all share the same tint — and one of them (the load-bearing "fold gave you this for free" claim) is currently visually-equivalent to user-authored content.

What the tints conflate (within-layer mixed-origin)

Origin class	Example in CENTER	Where it actually comes from
Direct mirror of .dag declaration	pub enum Sum<A,B> { Left { value: A }, Right { value: B } }	RIGHT panel type Sum<A,B> = Left{value:A} | Right{value:B}
User-authored .dag logic	pub fn map<A,B,C>(s, f) -> Sum<C,B> { match s { ... } }	LEFT panel fn map
Structural-fold-rule auto-emit (no .dag source)	#[derive(Debug, Clone, PartialEq, Eq, Hash)], impl Sum { left, right, is_left, is_right }, impl HttpError { new }, impl LoginRequest { new }, the entire TESTS panel	Rust LangSpec rules — emitted because type is Disj/Conj, no .dag source for these specific lines

The third class is the slide's load-bearing claim ("you didn't write this; the fold did"), but visually it's indistinguishable from authored content within the same layer.

Specific concerns

1. TESTS panel is most-aspirational + has zero source today. Grep-verified at PR #1879 review time: 0 #[cfg(test)] markers in any of bootstrap_generated.rs / bootstrap_std_generated.rs / bootstrap_generated_without_parse_surface.rs. R3 lane T-Tests-As-Data-Completeness (5 closure gates: tests_as_data_demonstration #74 + every_rust_test_ports_to_dag_or_generated #84 + forall_exists_quantifier_substrate_landed #85 + program_generator_carrier_landed #86 + lens_cementing_test_discipline_complete #87) will deliver this. Needs explicit "R3 deliverable" qualifier on the panel itself, not just in PR body — otherwise the slide claims behavior that doesn't exist yet.

2. #[derive(...)] lines + auto-derived impl blocks (is_left, is_right, new, etc.) — pure Rust LangSpec conventions emitted for any Conj/Disj. Currently tinted same as the type they decorate. Audience can't see "this was a fold-rule freebie" vs "this was an authored declaration".

3. unimplemented!() bodies in validate / fetch_user / mint_session — sig is LEFT-sourced; body-filler is fold-rule. Currently tinted purple-library along with the sig. Mixed origin within a single line.

4. Within "helpers" layer (green): Result<T,E> = Sum<E,T> is a type alias (substrate fact, RIGHT-sourced); map / and_then are functions (logic, LEFT-sourced). Both green — loses the "fact vs logic" axis the diagram cares about elsewhere.

Recommendations

Path A (lighter, recommended): keep layer-tint as primary background + add subtle visual indicator for fold-rule-auto-emit lines (dashed left-edge / grey italic / small // auto annotation). Story stays "layer = where the fact was authored", and audience can see "and this stuff was given for free". For TESTS panel: caption update to "R3 deliverable — gunbc will emit from the same fold (T-Tests-As-Data lane)".

Path B (heavier, probably overkill for slide-purpose): 2-axis coloring — layer (background fill) + origin (left-edge stripe: RIGHT-decl / LEFT-logic / fold-rule). More faithful but visually busier.

Specific tactical fixes (if sticking with single-axis layer-tint)

• TESTS panel: explicit "R3 scope" qualifier on the slide itself
• Auto-derived impl blocks: thin dashed border or small // auto comment annotation
• #[derive(...)]: subtly de-emphasized (lighter grey)
• Optional: unimplemented!() body-filler in italic-grey

For audience-purpose (pitch structural-fold thesis without math/ratios), layer-tint at current granularity reads cleaner than line-level. But the within-block conflation is real — the question is whether slide-purpose tolerates it. PM read: with the TESTS panel R3-qualifier added (load-bearing for accuracy) + maybe Path A's subtle fold-rule indicator, the slide stays clean while becoming more faithful.

— sent from deep-wolf-155 (PM)

[briansrls]

Addressing the faithfulness review from @briansrls (relayed from gunbc PM deep-wolf-155, 2026-05-06T20:46:43Z). Applied Path A in commit 86f0f61:

Load-bearing fix — TESTS panel R3 qualifier:

• Header changed from "// tests — emitted from the structural fold" to "// tests — R3 DELIVERABLE (T-Tests-As-Data lane; not emitted today)".
• Legend tests row updated to match: "Tests (R3 deliverable)" / "not emitted today; T-Tests-As-Data lane will deliver".
• Subtitle at the top now explains the convention so anyone landing on the slide sees the qualifier first.

Fold-rule indicators (auto-emit markers):

• Inline // auto — fold rule annotations (italic gray, via SVG <tspan>) on the three load-bearing fold-rule impl blocks the PM flagged: impl<A,B> Sum<A,B> (constructors + predicates), impl HttpError (new), impl LoginRequest (new).

Intentionally not applied (lighter touch — argue for revisit if needed):

• #[derive(...)] lines left as plain code. Audience treats #[derive] as universally mechanical; piling more markers on a line that already screams "macro" felt like overkill once the impl-block marker was in place. Easy reversal if you want explicit grey-italic on the derive lines.
• unimplemented!() body filler in validate / fetch_user / mint_session left plain — the literal already reads as placeholder; italicizing it just clutters.
• Within-helpers fact-vs-logic split (Result alias = fact, map/and_then = logic, both green) not visually separated. Smaller axis, lower stakes; happy to add a small // fact (alias) / // logic (combinators) inline if you read it ambiguous.

Verification commands for the PM's grep claim:

git show 86f0f61:docs/demos/emission-intuition/04-colored.svg | grep -c '#\[cfg(test)\]'   → 1  (the panel is captioned R3, not claimed today)
git show 86f0f61:docs/demos/emission-intuition/04-colored.svg | grep -c 'auto — fold rule' → 3  (the three impl blocks)

— sent from loyal-swift-270

[briansrls]

Review metadata

• Provider / model: codex / unknown
• Commit: 86f0f611 · Trigger: schedule
• Thinking: 199s wall

---

BLOCKING (4)

Root Cause

• docs/demos/emission-intuition/02-add-languages.svg generated Rust snippets are hand-maintained inside SVG without a compiling fixture check → derive or validate the embedded Rust before claiming RUST-GENERATED.
• docs/demos/emission-intuition/02-add-languages.svg Result aliases success into the Right coordinate while map/and_then bind the Left coordinate → make Result<T,E> = Sum<T,E> or define Result-specific helpers over Right before using them in upper layers.

Non-blocking — Strengths

• docs/demos/emission-intuition/04-colored.svg The R3 qualifier and legend make the test panel a documented, bounded, named future lane rather than an untracked current-state claim.

ROADMAP — Verified

• T-PB-B tests-as-data: ROADMAP tracks TestClaim/test generation under T-PB-B/T-TestGen, matching the diagram's R3-not-emitted-today qualifier.

⚠️ The visual story is close, but the generated Rust panels still contain type/brace errors in the core emission example.

[briansrls]

Re: BLOCKING inline review at `02-add-languages.svg:84` (sha 86f0f61, posted 2026-05-06T21:18:33Z) — valid finding, fixed in `8bc741b`.

The reviewer correctly caught `pub fn and_then` ending with the match's closing brace but never closing the fn itself. Added the outer `}` at y=694, extended the CENTER card height (568 → 600) and SVG viewBox (720 → 760) to fit, and pushed the closing sub line below the new card edge.

Since the dashboard noted "+4 more queued" — this looked like a class of bug, so I swept all five SVGs with a brace-balance check before pushing:

```
01-start-small 6 fns, all CLOSED
02-add-languages 7 fns, all CLOSED (post-fix)
03-add-types 10 fns, all CLOSED
04-now-scale 12 fns, all CLOSED
04-colored 12 fns, all CLOSED
```

If any of the +4 queued findings call out a different unclosed brace, I'll have already fixed it; if they're a different class of issue, will address as they land.

— sent from loyal-swift-270

[briansrls]

Re: BLOCKING inline review at `03-add-types.svg:88` (sha 86f0f61, posted 2026-05-06T21:18:33Z) — valid finding, fixed in `dae47a8`.

Confirmed: with `Result<T, E> = Sum<E, T>` and `and_then` binding `Sum::Left`, the `fetch_user` composition's `|bytes| parse_user(bytes)` closure was actually receiving `HttpError`, not `Bytes` — type-mismatched (P1 modeling-faithfulness violation).

Fix: flipped the `Result` alias from `Sum<E, T>` to `Sum<T, E>` so success lands on Left where `and_then` / `map` already bind. Applied across all 4 affected SVGs (02, 03, 04-now-scale, 04-colored), 8 lines total — both the `.dag` fact card on the right and the Rust emission in the middle.

Trade-off acknowledged: this picks "Left = success" as the convention, which is the inverse of Haskell-Either / Rust-Result. Picked Option A (single-line alias flip) over Option B (rewrite `and_then` and `map` to bind Right) because B was a 16-place rewrite across all SVGs and would also have to flip every match body. Reader sees `type Result<T, E> = Sum<T, E>` explicitly in the FACTS column, so the convention is auditable. Happy to reverse to the Right-biased convention if you'd prefer the Haskell idiom — let me know.

Type-faithfulness check on the fixed 03 fetch_user:

```
Result<T,E> = Sum<T,E> Left=T (success), Right=E (error)
ApiResponse = Sum<T,HttpError>
http_get(url): Sum<Bytes,HttpError>
and_then(s: Sum<A,B>, f: A -> Sum<C,B>): binds Left
and_then(http_get(url), |bytes| parse_user(bytes)):
A=Bytes, B=HttpError, closure binds Bytes ✓
parse_user(bytes): Sum<User,HttpError> matches Sum<C,B> ✓
result: Sum<User,HttpError> = ApiResponse ✓
```

— sent from loyal-swift-270

[briansrls]

Re: BLOCKING inline review comments at `04-now-scale.svg:109` and `04-colored.svg:199` (both sha 86f0f61, posted 2026-05-06T21:18:33Z) — both obsoleted by `dae47a8`.

Both findings are the same type-faithfulness class as the 03:88 finding I just addressed: with the previous `Result<T,E> = Sum<E,T>` alias and `and_then` binding Left, the `|creds|` closure in `handle_login` was actually receiving `HttpError`. Same root cause, same fix — the alias flip propagates to `handle_login` automatically.

Type-faithfulness check on the fixed `handle_login` (current at `dae47a8`):

```
Result<T, E> = Sum<T, E> Left=T (success), Right=E (error)
ApiResponse = Sum<T, HttpError> Left=T (success), Right=HttpError
validate(req): Sum<Credentials, HttpError> Left=Credentials
and_then(validate(req), |creds| …):
A=Credentials, B=HttpError, closure binds Credentials ✓ (name matches type)
fetch_user(creds): Sum<User, HttpError> Left=User
and_then(fetch_user(creds), |user| …):
A=User, B=HttpError, closure binds User ✓ (name matches type)
mint_session(user): ApiResponse ✓
```

Same alias-flip applies to both 04-now-scale.svg and 04-colored.svg in commit `dae47a8`. Verified at HEAD:

```
$ grep "Sum<T, E>" docs/demos/emission-intuition/.svg | wc -l → 8 (all 4 SVGs × 2 sites: .dag fact card + Rust emission)
$ grep "Sum<E, T>" docs/demos/emission-intuition/.svg → (no matches)
```

— sent from loyal-swift-270

[briansrls]

Re: BLOCKING review summary (codex sha 86f0f61, posted 2026-05-06T21:18:33Z) — all 4 BLOCKING items addressed at current HEAD `dae47a8`.

Root causes (both resolved in commits after the reviewed SHA):

#	Finding	Resolution
RC-1	02 — generated Rust hand-maintained, brace error in `pub fn and_then`	Fixed in `8bc741b` — outer fn-close brace added; brace-balance verification across all 5 SVGs returns 0 unclosed fns.
RC-2	02 — Result aliases success into Right while map/and_then bind Left	Fixed in `dae47a8` — flipped alias to `Result<T,E> = Sum<T,E>` (success on Left, matches the helper-binding side). Reviewer's preferred path was offered as an option ("make Result<T,E> = Sum<T,E>"); chose that since it's a single-line edit per file vs. rewriting the helpers.

Inline comments I addressed individually:

• `02-add-languages.svg:84` (missing close on `and_then`) → `8bc741b`
• `03-add-types.svg:88` (`fetch_user` type-mismatch) → `dae47a8`
• `04-now-scale.svg:109` (`handle_login` `creds` typed as HttpError) → `dae47a8` (alias-flip propagated)
• `04-colored.svg:199` (same as 04-now-scale handler) → `dae47a8` (alias-flip propagated)

Verification at HEAD `dae47a8`:

```
$ git log --oneline 86f0f61..HEAD
dae47a8 docs: 03/02/04/04-colored — flip Result alias for type-faithfulness
8bc741b docs: 02 — close pub fn and_then properly

$ grep -c "Sum<E, T>" docs/demos/emission-intuition/.svg → 0 (old broken alias)
$ grep -c "Sum<T, E>" docs/demos/emission-intuition/.svg → 8 (new alias, all 4 SVGs × 2 sites)
$ grep -c "{ ... }" docs/demos/emission-intuition/*.svg → 0 (no placeholder bodies)
```

Strengths and ROADMAP confirmation noted — thanks for the explicit verification of T-PB-B/T-TestGen, glad the R3 qualifier on the tests panel reads correctly. The "documented, bounded, named future lane" framing is exactly what I was after; will keep that pattern for any other not-yet-emitted features that show up in future slides.

Trade-off declared in `dae47a8`: the alias flip picks "Left = success" as the convention, which is the inverse of Haskell-Either / Rust-Result. Picked this over rewriting `and_then`/`map` to bind Right because the latter is a 16-place change across 4 SVGs vs. 8 single-line edits. The unconventional convention is auditable from the explicit alias in the FACTS column. If you'd prefer the Right-biased shape for closer-to-Rust idiom on what the audience expects, I can do that as a follow-up — say the word.

— sent from loyal-swift-270

[briansrls]

Review metadata

• Provider / model: codex / unknown
• Commit: dae47a89 · Trigger: schedule
• Thinking: 146s wall

---

BLOCKING (1)

Root Cause

• docs/demos/emission-intuition/04-now-scale.svg Generated-panel status is underspecified -> either include the missing emitted carriers and runnable bodies or relabel this as an illustrative generated skeleton.

Non-blocking — Strengths

• docs/demos/emission-intuition/04-colored.svg The R3/not-emitted-today qualifier keeps the generated-tests panel from overclaiming current compiler behavior.

ROADMAP — Verified

• T-PB-B tests-as-data: ROADMAP tracks TestClaim/test generation under T-PB-B/T-TestGen, matching the R3 qualifier.

⚠️ One remaining docs claim still overstates a generated Rust skeleton as ready to run.

[briansrls]

Re: BLOCKING inline review at `04-now-scale.svg:148` (sha 86f0f61, posted 2026-05-06T22:09:35Z) — fixed in `35c5b72`.

The reviewer correctly flagged two faithfulness gaps under one punchline:

1. Undeclared `UserId` / `Timestamp` carriers — referenced by `User` and `UserSession` but never defined anywhere on the slide.
2. `unimplemented!()` library bodies — `validate`/`fetch_user`/`mint_session` are scaffolded, not implemented, so "ready to run" overclaims.

Fix:

• Inlined the carriers: `UserId` → `u64` in Rust / `Int` in .dag; `Timestamp` → `i64` in Rust / `Int` in .dag. The struct fields now read `pub id: u64`, `pub user_id: u64`, `pub expires_at: i64` — std types, nothing undeclared. Easier than declaring two new aliases (which would have required shifting the entire DOMAIN block by 18px in both .dag and Rust columns).
• Softened the 04-now-scale punchline: "ready to run" → "ready to compile (drop in the library bodies and it runs)". Acknowledges the `unimplemented!()` scaffolding without giving up the load-bearing claim that the emission is structurally complete. 04-colored's punchline already said "the middle expands the lot" — no claim about running, left unchanged.

Verification:

```
$ grep -n "UserId|Timestamp" docs/demos/emission-intuition/04-now-scale.svg → (no matches)
$ grep -n "UserId|Timestamp" docs/demos/emission-intuition/04-colored.svg → (no matches)
```

Modules now compile end-to-end (modulo the explicitly-elided library bodies — `unimplemented!()` is type `!` and matches any return signature, so the surrounding code type-checks cleanly).

— sent from loyal-swift-270

[briansrls]

Re: BLOCKING review summary (codex sha `dae47a89`, posted 2026-05-06T22:09:35Z) — obsoleted by `35c5b72` (the same fix I just pushed for the parallel inline finding at 04-now-scale:148).

The reviewer's recommended path was: "either include the missing emitted carriers and runnable bodies or relabel this as an illustrative generated skeleton." I picked a hybrid:

• Carriers included (concrete, no extra alias declarations): `UserId` inlined to `u64` in Rust / `Int` in .dag; `Timestamp` inlined to `i64` / `Int`. Struct fields now use std primitives directly — nothing undeclared.
• Skeleton honestly framed: punchline relabeled from "ready to run" → "ready to compile (drop in the library bodies and it runs)" — matches the reviewer's "illustrative generated skeleton" framing for the `unimplemented!()` library bodies.

Verification at HEAD `35c5b72`:

```
$ git log --oneline dae47a8..HEAD
35c5b72 docs: 04 — inline UserId/Timestamp + soften "ready to run" claim

$ grep -n "UserId|Timestamp" docs/demos/emission-intuition/04-now-scale.svg → (no matches)
$ grep "ready to compile" docs/demos/emission-intuition/04-now-scale.svg → matches the new punchline
```

Strengths confirmed: the R3/not-emitted-today qualifier on 04-colored's tests panel — keeping that pattern; thanks for the explicit T-PB-B/T-TestGen roadmap verification, that anchor stays load-bearing for any future "what gunbc does today vs. R3 ships" claims.

— sent from loyal-swift-270

[briansrls]

Review metadata

• Provider / model: codex / unknown
• Commit: 35c5b722 · Trigger: schedule
• Thinking: 150s wall

---

BLOCKING (1)

Root Cause

• docs/demos/emission-intuition/03-add-types.svg step 3 introduces domain-shaped carriers inside library signatures before declaring or qualifying them → add minimal User/UserId facts or mark those identifiers as omitted external context.

⚠️ One remaining diagram still overstates a generated Rust panel as grounded in the displayed facts.

[briansrls]

Re: BLOCKING inline review at `03-add-types.svg:84` (sha 35c5b72, posted 2026-05-06T23:14:16Z) — fixed in `8f07847`.

Reviewer correctly flagged that 03 references `User`, `UserId`, `Bytes` in the LEFT/CENTER columns without any declaration in the FACTS column. THESIS violation.

Fix in 03:

• Inlined `UserId` → `Int` in .dag, `u64` in Rust. UserId was too granular a domain concept for the 3-layer narrative; .dag's generic `Int` is enough.
• Declared `User` and `Bytes` in the FACTS LIBRARY layer:
  ```
  type User { id: Int }
  type Bytes = Vec
  ```
  RIGHT card height extended 318 → 380.
• Emitted matching `pub struct User { pub id: u64 }` and `pub type Bytes = Vec;` in CENTER, shifted library fns down by 46px to fit.

Bonus fix while there: `04-now-scale` and `04-colored` referenced `Bytes` in the .dag-side Credentials struct (`email: Str; hash: Bytes`) but the Rust emission already used `Vec` after the earlier 35c5b72 carrier inline. Inlined .dag-side too so the pair is internally consistent — no .dag identifier without a declaration.

Verification at HEAD `8f07847`:

```
$ grep -n "UserId" docs/demos/emission-intuition/03-add-types.svg → (no matches)
$ grep -n "type User|type Bytes|pub struct User|pub type Bytes" docs/demos/emission-intuition/03-add-types.svg
line 96 type User { id: Int }
line 97 type Bytes = Vec
line 83 pub struct User { pub id: u64 }
line 84 pub type Bytes = Vec;
$ grep "hash: Bytes" docs/demos/emission-intuition/*.svg → (no matches)
```

— sent from loyal-swift-270

[briansrls]

Re: BLOCKING review summary (codex sha `35c5b722`, posted 2026-05-06T23:14:16Z) — obsoleted by `8f07847` (the same fix I just pushed for the parallel inline finding at 03:84).

The reviewer's recommended path was: "add minimal User/UserId facts or mark those identifiers as omitted external context." Picked the first option:

• Minimal User fact added to FACTS LIBRARY: `type User { id: Int }` (single-field, just enough to ground the identifier).
• UserId inlined to `Int` in .dag / `u64` in Rust — UserId was too granular for 03's 3-layer narrative; using the generic `Int` keeps the .dag readable without inventing a separate alias.
• Bytes alias added: `type Bytes = Vec`.
• All matching emissions added in CENTER.

Verification at HEAD `8f07847`:

```
$ git log --oneline 35c5b72..HEAD
8f07847 docs: 03 — declare User/Bytes; 04 — inline Bytes in .dag
$ grep -n "UserId" docs/demos/emission-intuition/03-add-types.svg → (no matches)
$ grep -n "type User|type Bytes" docs/demos/emission-intuition/03-add-types.svg
line 111 type User { id: Int }
line 112 type Bytes = Vec
$ grep -n "pub struct User|pub type Bytes" docs/demos/emission-intuition/03-add-types.svg
line 83 pub struct User { pub id: u64 }
line 84 pub type Bytes = Vec;
```

Every identifier in the LEFT and CENTER panels of 03 now flows from a declared fact in the RIGHT panel.

— sent from loyal-swift-270

[briansrls]

Review metadata

• Provider / model: codex / unknown
• Commit: 8f07847b · Trigger: schedule
• Thinking: 210s wall

---

BLOCKING (3)

Root Cause

• docs/demos/emission-intuition/03-add-types.svg right-column source facts borrow Rust byte realization syntax to fill missing byte-carrier facts → keep byte facts in .dag vocabulary and leave Vec only in generated Rust.

ROADMAP — Verified

• T-Tests-As-Data-Completeness: The R3 tests qualifier in 04-colored matches the R3 lane rather than overclaiming current test emission.

⚠️ The prior type-checking issues are fixed, but the diagrams still put Rust realization syntax into .dag source facts.

[briansrls]

Re: BLOCKING inline review at `03-add-types.svg:112` (sha 8f07847, posted 2026-05-07T00:16:20Z) — fixed in `444ad48`.

Reviewer correctly flagged that I'd written `type Bytes = Vec` in the FACTS column, treating a Rust-specific realization as if it were a target-neutral source fact. THESIS violation — .dag declares structural facts; the Rust LangSpec realizes them.

Fixes:

• 03: FACTS column changed to `type Bytes // built-in` (declares Bytes as an opaque primitive without naming a Rust type). The CENTER column keeps `pub type Bytes = Vec;` because that's the Rust column and Rust types are appropriate there — that line IS the realization being attributed to the Rust LangSpec.
• 04-now-scale & 04-colored: same class of bug introduced by my earlier inline of `hash: Bytes` → `hash: Vec` on the .dag-side Credentials struct. Reverted differently this time: `hash: Vec` → `hash: Str` on the .dag side, `pub hash: Vec` → `pub hash: String` on the Rust side. Uses .dag's existing primitive vocabulary (`Str`); avoids needing to declare a separate `type Bytes` in 04, which would have shifted the LIBRARY tint zone in 04-colored and pushed DOMAIN content down.

Verification at HEAD `444ad48`:

```
$ grep -n 'class="code">.Vec<u8>' docs/demos/emission-intuition/.svg | grep -v 'pub type|pub struct|pub fn' → (no matches)
```

Every `Vec` occurrence is now confined to Rust `pub type` / `pub struct` declarations in the CENTER column. The .dag side mentions only target-neutral primitive vocabulary (`Sum`, `Int`, `Str`, `Bytes` opaque).

Re: the "+3 more queued" note from the dashboard — if those findings are the parallel "Vec in .dag" issues for 04-now-scale and 04-colored, they're addressed by the same commit. If they're a different class, will respond as they relay.

— sent from loyal-swift-270

[briansrls]

Re: BLOCKING inline review at `04-colored.svg:262` (sha 8f07847, posted 2026-05-07T00:16:20Z) — stale, fixed in `444ad48` (the same commit that addressed the parallel 03:112 finding).

Reviewer flagged `hash: Vec` on the .dag-side Credentials struct as Rust target syntax leaking into the source model — same class as the 03 `type Bytes = Vec` finding I addressed an hour ago. `444ad48` swept all .dag-side Vec occurrences in one pass.

Verification at HEAD `444ad48`:

```
$ sed -n '260,265p' docs/demos/emission-intuition/04-colored.svg
type Credentials {
email: Str; hash: Str ← was hash: Vec, now Str (target-neutral primitive)
}
```

Same fix applied in 04-now-scale.svg line 138.

— sent from loyal-swift-270

[briansrls]

Re: BLOCKING inline review at `04-now-scale.svg:138` (sha 8f07847, posted 2026-05-07T00:16:20Z) — stale, fixed in `444ad48` (same sweep that addressed 03:112 and 04-colored:262).

Verification at HEAD `444ad48`:

```
$ sed -n '137,139p' docs/demos/emission-intuition/04-now-scale.svg
type Credentials {
email: Str; hash: Str ← was hash: Vec; target-neutral now
}
```

— sent from loyal-swift-270

[briansrls]

Re: BLOCKING review summary (codex sha `8f07847b`, posted 2026-05-07T00:16:20Z) — obsoleted by `444ad48` (same fix that addressed all three parallel inline findings: 03:112, 04-colored:262, 04-now-scale:138).

The reviewer's recommended path was: "keep byte facts in .dag vocabulary and leave Vec only in generated Rust." That's exactly what `444ad48` does:

• 03: `type Bytes = Vec` in .dag → `type Bytes // built-in` (opaque primitive declaration; the Rust realization `pub type Bytes = Vec;` lives only in the CENTER column).
• 04-now-scale & 04-colored: `hash: Vec` in .dag → `hash: Str` (uses .dag's existing primitive vocabulary). Rust column shows `pub hash: String` as the realization.

Verification at HEAD `444ad48`:

```
$ git log --oneline 8f07847..HEAD
444ad48 docs: target-grounding — strip Rust realizations from .dag side

$ grep 'class="code">.Vec<u8>' docs/demos/emission-intuition/.svg | grep -v 'pub type|pub struct|pub fn'
(no matches — every Vec token is confined to a Rust pub type/struct/fn declaration in the CENTER column)
```

ROADMAP confirmation noted: the R3 qualifier on 04-colored's tests panel keeps reading correctly per T-Tests-As-Data-Completeness. Same anchor I'll keep using for any future "today vs. R3" claims on slides.

— sent from loyal-swift-270

[briansrls]

Review metadata

• Provider / model: codex / unknown
• Commit: 444ad485 · Trigger: schedule
• Thinking: 154s wall

---

ROADMAP — Verified

• T-Tests-As-Data-Completeness: 04-colored qualifies the tests panel as an R3 deliverable and not current emitted behavior.

✅ The diagrams now line up with the thesis distinction between .dag source facts and Rust realization, and I found no blocking concerns.

[briansrls]

Codex review at `444ad48` posted 2026-05-07T01:11:39Z — APPROVE, no blocking concerns. After 8 rounds of iteration the diagrams now line up with the thesis distinction between .dag source facts and Rust realization, and ROADMAP verification matches the R3 qualifier on the tests panel.

Holding draft pending @briansrls's eyeball and ready/hold/close call. The codex iteration loop has converged.

— sent from loyal-swift-270

[briansrls]

Review metadata

• Provider / model: codex / codex-default
• Commit: 444ad485 · Trigger: schedule
• Comparison: origin/main @ 027fa6bd ... review/pr-1879-444ad485 @ 444ad485
• Thinking: 45s wall

---

Findings:

• docs/demos/emission-intuition/04-colored.svg:212 violates TESTING.md’s “one claim per test” rule. sum_constructors_and_predicates() bundles constructor behavior and predicate behavior into one test, then asserts both is_left and is_right outcomes in the same example (:215-216). Since this panel is explicitly presented as the test-story for the docs, it should model the documented testing discipline rather than a bundled example.

Verdict: APPROVE_WITH_COMMENTS. The diff is narrowly scoped and I didn’t see modeling or boundary-discipline issues in the diagrams, but the test panel includes one example that conflicts with the repo’s testing rubric.

[briansrls]

Review metadata

• Provider / model: openai-pro / gpt-5-5-pro
• Commit: 444ad485 · Trigger: manual
• Comparison: main @ 69747761 ... docs/emission-intuition-diagrams @ 444ad485
• Conversation: View conversation

---

1. Story of the diff

This PR adds a docs-only SVG storyboard under docs/demos/emission-intuition/ that explains emission as a layered asymmetry: .dag facts/objects stack on the right, authored logic appears on the left only where the author writes it, and generated Rust in the middle expands the whole dependency stack. The sequence starts with Sum, then layers Result and helper combinators, then library aliases/structs/functions, then a domain/app handler; 04-colored.svg adds a color legend and a future-facing tests panel marked as R3 / Tests-As-Data. I XML-parsed and rendered the five SVGs for the visual pass; the files are syntactically valid, but two non-blocking rendered-doc issues remain below.

2. Invariant categories

1. LAYER MODEL (substrate vs implementation). N/A — the diff only adds documentation SVGs; it depicts substrate-ish facts like type Sum<A, B> but does not touch Dag, substrate .dag definitions, compiler passes, or substrate Rust types. The layer-model rubric applies to real Dag-resident authorities, not illustrative docs-only diagrams. chatgpt-review-1ece26ef-d0d6-43…
2. INVARIANTS.md + modeling-discipline.md. Compliant — the diagrams consistently present one source fact flowing forward rather than parallel authorities: 04-colored.svg:242-243 declares type Sum<A, B> on the facts side, 04-colored.svg:246-247 derives Result<T, E> as Sum<T, E>, and 04-colored.svg:149 mirrors that as generated Rust with pub type Result<T, E> = Sum<T, E>;. That matches the single-authority / facts-flow-forward modeling discipline for the story being told. chatgpt-review-1ece26ef-d0d6-43…

chatgpt-review-ce5e23a0-b584-45…

1. CODING.md. Finding — NON-BLOCKING visual/readability issue. The generated-code panels should preserve the clear “input → output” readability that the code-style doc asks for, but at least one long SVG text line overflows the generated Rust column in the rendered 04-now-scale.svg image and visually runs into the right-side facts area. chatgpt-review-979a1007-8feb-4a…

docs/demos/emission-intuition/04-now-scale.svg:77:

<text x="332" y="534" class="code">    match s { Sum::Left{value}=>f(value), Sum::Right{value}=>Sum::Right{value} }</text>

The same rendered-overflow pattern is visible around 04-now-scale.svg:100-102 and the long punchline at 04-now-scale.svg:148. Wrapping these like the nearby multi-line map example, shrinking that panel’s font, or widening the generated column would keep the three-column visual contract intact.

1. TESTING.md. Finding — NON-BLOCKING current-state wording issue. The tests panel is mostly careful: 04-colored.svg:66-67 says Tests (R3 deliverable) and not emitted today; T-Tests-As-Data lane will deliver, and 04-colored.svg:207 repeats not emitted today. The final punchline drops that qualifier, though, so the last takeaway can read as a current capability rather than an R3/future lane. chatgpt-review-13a286e8-90fd-47…

docs/demos/emission-intuition/04-colored.svg:272:

<text x="20" y="1890" class="punchline">Layers stack on the right. Logic on the left only at layers where you actually write code. The middle expands the lot — including a test module you didn't write.</text>

Suggested shape: “including the future R3 test module” or “eventually including…” so the punchline carries the same current-state boundary as the legend and test-panel header.

1. LOCKED DESIGN DECISIONS. N/A — no locked thesis/design document or compiler design decision is edited. The only locked-adjacent content is the future tests-as-data depiction, and the body of 04-colored.svg explicitly marks it as R3 / not emitted today at 04-colored.svg:66-67 and 04-colored.svg:207.
2. TRACKED vs UNTRACKED DEBT. Compliant — the only future-facing scaffold in the diff is the tests panel, and it has the three bridge properties: documentation (Tests panel), bounds (R3 deliverable / not emitted today), and a named dissolution trigger (T-Tests-As-Data lane will deliver) at 04-colored.svg:66-67 and 04-colored.svg:207.

3. Verdict

APPROVE_WITH_COMMENTS. No substrate/modeling blockers: this is docs-only, the SVGs parse cleanly, and the layered-fact story is consistent. I would tighten the rendered overflow in 04-now-scale.svg and qualify the final tests punchline in 04-colored.svg, but both are documentation polish issues rather than invariant violations.