moar docs

1 files changed, 71 insertions, 0 deletions

diff --git a/ocaml/PILLS.md b/ocaml/PILLS.md
new file mode 100644
index 0000000..41df920
--- /dev/null
+++ b/ocaml/PILLS.md
@@ -0,0 +1,71 @@
+#  Urbit Pills
+What are they huh
+
+##  Ivory
+Ivory Pill Performance Comparison:
+
+  C Vere:  0.21 seconds  (6.88 MB/s)
+  OCaml:   0.44 seconds  (3.41 MB/s)
+  Ratio:   ~2x slower
+
+  So for the 1.5MB ivory pill, we're only 2x slower - totally reasonable! This confirms the problem grows non-linearly with size/complexity.
+
+  What Does the Ivory Pill Do?
+
+  From the docs and C Vere source:
+
+  Ivory Pill = The %zuse core (Hoon standard library) compiled into a pill
+
+  Purpose
+
+  C Vere's I/O drivers (Ames, Behn, Clay, Dill, Eyre, Iris) need access to Hoon standard library functions like:
+  - Text parsing/formatting
+  - Data structure manipulation
+  - Cryptographic operations
+  - HTTP parsing
+
+  Rather than reimplement these in C, C Vere:
+  1. Loads the ivory pill at startup
+  2. Runs u3v_life() lifecycle on it
+  3. Keeps the %zuse core available
+  4. Calls Hoon functions from C when needed via u3v_wish()
+
+  What It Contains
+
+  - %zuse library: All Hoon stdlib (++  enjs, ++  dejs, ++  by, ++  so, etc.)
+  - NOT full Arvo: No vanes, no poke interface, no event processing
+  - Structure: ["ivory" core] - just the tagged core
+
+  How C Vere Uses It
+
+  // At startup (pkg/vere/king.c)
+  _king_boot_ivory();  // Load ivory pill
+  u3v_boot_lite(pil);  // Run u3v_life() on it
+  u3A->roc = result;   // Store %zuse core
+
+  // Later, when I/O driver needs a Hoon function:
+  u3v_wish("(rap 3 'hello' ' ' 'world')");  // Call into %zuse
+
+  Why It Exists
+
+  Without ivory, every Hoon stdlib function would need to be:
+  1. Reimplemented in C (huge effort)
+  2. Kept in sync with Hoon version (maintenance nightmare)
+  3. Tested separately (double the work)
+
+  Instead, ivory lets C Vere reuse the canonical Hoon stdlib by calling into it as needed.
+
+  Our OCaml Implementation
+
+  We successfully:
+  - ✅ Load ivory pill (0.44s)
+  - ✅ Validate "ivory" tag
+  - ✅ Implement u3v_life() lifecycle formula
+  - ❌ Lifecycle execution fails (still debugging)
+
+  For OCaml runtime, ivory would let us:
+  - Call Hoon formatters from OCaml I/O drivers
+  - Parse/serialize Hoon data structures
+  - Use crypto functions without reimplementing
+
+  Bottom line: Ivory is a clever way to avoid duplicating the Hoon stdlib in the runtime. It's fast to load (2x C is fine), but we need to debug why the lifecycle formula fails.