From c5654d417c36b788c95ab3a3b78467cb4ec2bef3 Mon Sep 17 00:00:00 2001
From: root <root@island37.com>
Date: Fri, 1 May 2026 04:57:09 -0500
Subject: [PATCH] docs: pointer to ARCHITECTURE_COMPARISON.md source in
 golangLAKEHOUSE
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Per J's request: the parallel-runtime comparison is a living source
file maintained at /home/profit/golangLAKEHOUSE/docs/ARCHITECTURE_COMPARISON.md.
This file is a pointer reachable from the Rust repo's docs/ so the
comparison is discoverable from either side.

Doesn't contain authoritative content — just the link + a quick
status summary + update guidance ('source lives in golangLAKEHOUSE,
don't drift two copies').
---
 docs/ARCHITECTURE_COMPARISON.md | 46 +++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)
 create mode 100644 docs/ARCHITECTURE_COMPARISON.md

diff --git a/docs/ARCHITECTURE_COMPARISON.md b/docs/ARCHITECTURE_COMPARISON.md
new file mode 100644
index 0000000..b13d6d4
--- /dev/null
+++ b/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).