docs/ARCHITECTURE_COMPARISON.md

@@ -0,0 +1,46 @@
+# Lakehouse: Rust vs Go architecture comparison
+
+> **Source of truth lives in the golangLAKEHOUSE repo:**
+> [`/home/profit/golangLAKEHOUSE/docs/ARCHITECTURE_COMPARISON.md`](file:///home/profit/golangLAKEHOUSE/docs/ARCHITECTURE_COMPARISON.md)
+>
+> J's living document — pulled from there into this repo's docs as
+> a pointer so the comparison is reachable from either side.
+
+## Why the source lives in golangLAKEHOUSE
+
+The Go rewrite was the trigger for the comparison. The doc updates as
+J ships fixes on either side, and most of the open backlog items
+(materializer port, replay port, validators network surface) land in
+the Go repo. Keeping the source there means PR auditing on Go
+commits also catches doc drift.
+
+## When to update from this side
+
+If a fix lands in the Rust repo that changes a comparison value
+(e.g. embed cache change, sidecar drop, new validator), update both:
+
+1. The source at `/home/profit/golangLAKEHOUSE/docs/ARCHITECTURE_COMPARISON.md`
+2. The change log section at the bottom of the same file
+
+This file is a pointer — **do not put authoritative content here.**
+Drift between two copies wastes the discipline.
+
+## Quick links
+
+- **Decisions tracker** — section near the top of the source file.
+  Lists actioned items + open backlog with LOC estimates.
+- **Performance numbers** — Python dependency section. Updated each
+  time a load test is rerun.
+- **Distillation porting status** — table of phase-by-phase port
+  state across runtimes.
+- **Recommendation** — current working hypothesis on Go-primary vs
+  Rust-primary. Subject to change as fixes ship.
+
+## Last known state
+
+- **2026-05-01**: Rust embed cache shipped (`150cc3b`), 236× RPS gain.
+- **2026-05-01**: Go validator port shipped (`b03521a`), production
+  safety net now on Go side.
+- **Open**: Drop Rust Python sidecar (~200 LOC, universal-win).
+- **Open**: Port Rust materializer to Go (~500-800 LOC, unblocks
+  Go-only end-to-end pipeline).