checkpoint: matrix-agent-validated (2026-04-25)

Architectural snapshot of the lakehouse codebase at the point where the
full matrix-driven agent loop with Mem0 versioning + deletion was
validated end-to-end.

WHAT THIS REPO IS
A clean single-commit snapshot of the lakehouse code. Heavy test data
(.parquet datasets, vector indexes) excluded — see REPLICATION.md for
regen path. Full lakehouse history at git.agentview.dev/profit/lakehouse.

WHAT WAS PROVEN
- Vector retrieval across multi-corpora matrix (chicago_permits + entity
  briefs + sec_tickers + distilled procedural + llm_team runs)
- Observer hand-review (cloud + heuristic fallback) gating each candidate
- Local-model agent loop (qwen3.5:latest) with tool use + scratchpad
- Playbook seal on success → next-iter retrieval surfaces it as preamble
- Mem0 versioning + deletion in pathway_memory:
    * UPSERT: ADD on new workflow, UPDATE bumps replay_count on identical
    * REVISE: chains versions, parent.superseded_at + superseded_by stamped
    * RETIRE: marks specific trace retired with reason, excluded from retrieval
    * HISTORY: walks chain root→tip, cycle-safe

KEY DIRECTORIES
- crates/vectord/src/pathway_memory.rs — Mem0 ops live here
- crates/vectord/src/playbook_memory.rs — original Mem0 reference
- tests/agent_test/ — local-model agent harness + PRD + session archives
- scripts/dump_raw_corpus.sh — MinIO bucket dump (raw test corpus)
- scripts/vectorize_raw_corpus.ts — corpus → vector indexes
- scripts/analyze_chicago_contracts.ts — real inference pipeline
- scripts/seal_agent_playbook.ts — Mem0 upsert from agent traces

Replication: see REPLICATION.md for Debian 13 clean install + cloud-only
adaptation (no local Ollama).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

justfile

@@ -0,0 +1,50 @@
+# Lakehouse task runner
+
+default:
+    @just --list
+
+# Build all crates
+build:
+    cargo build --workspace
+
+# Run all tests
+test:
+    cargo test --workspace
+
+# Run gateway
+run:
+    cargo run --bin gateway
+
+# Build UI (WASM)
+ui-build:
+    cd crates/ui && dx build --platform web
+
+# Serve UI (dev)
+ui-serve:
+    cd target/dx/ui/debug/web/public && python3 -m http.server 3300 --bind 0.0.0.0
+
+# Start sidecar
+sidecar:
+    cd sidecar && uvicorn sidecar.main:app --host 0.0.0.0 --port 3200
+
+# Start everything (gateway + sidecar + UI)
+up:
+    @echo "Starting gateway on :3100..."
+    @cargo run --bin gateway &
+    @echo "Starting sidecar on :3200..."
+    @cd sidecar && uvicorn sidecar.main:app --host 0.0.0.0 --port 3200 &
+    @echo "Starting UI on :3300..."
+    @cd target/dx/ui/debug/web/public && python3 -m http.server 3300 --bind 0.0.0.0 &
+    @echo "All services started."
+
+# Check without building
+check:
+    cargo check --workspace
+
+# Format all code
+fmt:
+    cargo fmt --all
+
+# Lint
+clippy:
+    cargo clippy --workspace -- -D warnings