# 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).