1 files changed, 134 insertions, 0 deletions
diff --git a/ocaml/SOLID_BOOT_FLOW.md b/ocaml/SOLID_BOOT_FLOW.md
new file mode 100644
index 0000000..d188bd9
--- /dev/null
+++ b/ocaml/SOLID_BOOT_FLOW.md
@@ -0,0 +1,134 @@
+# Solid Pill Boot Flow (C Vere)
+
+## Investigation Summary
+
+Tracked the solid pill boot flow through C Vere to understand how `-B solid.pill` works.
+
+## Call Chain
+
+```
+1. king.c:_boothack_doom()
+   ↓ Creates boot command: [%boot bot pill_spec path]
+
+2. king.c:_king_doom()
+   ↓ Routes to _king_fake() for fake ships
+
+3. king.c:_king_fake()
+   ↓ Creates message: [%boot pill vent props]
+   ↓ Calls u3_lord_boot() with jammed message
+
+4. lord.c:u3_lord_boot()
+   ↓ Spawns worker process with "boot" protocol
+   ↓ Jams and sends boot message to worker
+
+5. main.c:_cw_boot()
+   ↓ Worker process receives boot message
+   ↓ Sets up u3_mars_boot as message handler
+
+6. mars.c:u3_mars_boot()
+   ↓ Cues the boot message
+   ↓ Calls _mars_boot_make() to prepare events
+
+7. mars.c:_mars_boot_make()
+   ↓ Calls _mars_sift_pill() to parse pill
+   ↓ Builds timestamped event list
+   ↓ Writes events to disk
+
+8. mars.c:_mars_sift_pill()  <-- KEY FUNCTION
+   ↓ Parses pill structure
+
+9. mars.c:_mars_do_boot()
+   ↓ Reads events from disk
+   ↓ Calls u3v_boot(eve)
+
+10. vortex.c:u3v_boot()
+    ↓ Calls u3v_life(eve)
+
+11. vortex.c:u3v_life()
+    ↓ Runs lifecycle formula [2 [0 3] [0 2]]
+```
+
+## Pill Structure
+
+### Ivory Pill
+```
+[%ivory core]
+```
+- Tag: %ivory
+- Content: The compiled kernel core directly
+
+### Solid Pill
+```
+[%pill %solid bot mod use]
+```
+Which expands to:
+```
+[%pill [%solid [bot [mod [use nil]]]]]
+```
+
+From `mars.c:1629`:
+```c
+if ( c3n == u3r_qual(dat, &typ, bot, mod, use) ) {
+```
+
+Where `dat` is the second element after %pill tag, containing `[%solid bot mod use]`.
+
+## Event List Construction
+
+From `mars.c:1832-1866`, the event list is built as:
+
+1. **Bot events** (3 events): NO timestamp, bare events
+2. **Mod events** (0 in pill + 4 synthesized): WITH timestamps
+   - Synthesized events added at lines 1758-1774:
+     - `wack`: entropy (16 random words)
+     - `whom`: ship identity
+     - `verb`: verbose flag
+     - Version negotiation card
+3. **Use events** (3-5 depending on pill): WITH timestamps
+
+The final structure passed to `u3v_boot(eve)`:
+```
+[bare_bot_1 bare_bot_2 bare_bot_3 [ts mod_1] [ts mod_2] ... [ts use_1] ...]
+```
+
+A MIXED list: some bare events, some timestamped pairs!
+
+## Key Findings
+
+1. **Ivory rejection**: `_mars_sift_pill` line 1608-1611 REJECTS ivory pills:
+   ```c
+   if ( c3y == u3r_sing_c("ivory", tag) ) {
+     fprintf(stderr, "boot: failed: unable to boot from ivory pill\r\n");
+     return c3n;
+   }
+   ```
+
+2. **Pill tag value**: `c3__pill` = 0x6c6c6970 = 1819044208 (NOT 1819633778!)
+
+3. **u3v_life formula**: `[2 [0 3] [0 2]]` is applied to the ENTIRE event list
+   - Works on the full mixed list (bot + mod + use)
+   - NOT just bot events!
+
+4. **My solid.pill has**:
+   - Bot: 3 events (bare)
+   - Mod: 0 events (empty list in pill)
+   - Use: 5 events
+   - Total: 8 events
+   - But C Vere adds 4 synthetic mod events → 12 total
+
+## Current Problem
+
+The lifecycle formula `[2 [0 3] [0 2]]` is failing on my 8-event list with `Nock.Exit`.
+
+This formula means:
+- `[0 2]`: get slot 2 (head) = first event/formula
+- `[0 3]`: get slot 3 (tail) = rest of events
+- `[2 formula subject]`: nock(subject formula)
+
+So it's trying to: `nock(rest-of-events first-event)`
+
+The first event should be a FORMULA (executable code), but my bot events might just be data!
+
+## Next Steps
+
+Need to understand what the bot events actually contain - are they formulas or data?