# v4 architecture audit — 2026-05-10

> Cross-model architecture review of the v4 foundation surfaces (`tier_memory`,
> `block_kinds`, `cognitive_kernel`, `surprise_retrieval`). Sourced from a
> structured review prompt; synthesis below.

## Summary

| Dimension | Consensus |
|-----------|-----------|
| Architecture grade | **7.5–8/10** (mean ~7.9 across the review panel) |
| Verdict | Unanimous: **ship v4 on this scaffold**, don't restart |
| Top blind spot | **Unanimous: read-after-write consistency for tier promotions** |
| Top improvements (cross-model agreement) | (1) pre-computed kernel candidates, (2) vector quantization, (3) multi-label kinds, (4) HNSW kind index |

## Cross-model improvement matrix

| Improvement | Agreement |
|-------------|-----------|
| Pre-compute kernel candidates on write | **unanimous** |
| Vector quantization (PQ M=32, 8-bit) | **unanimous** |
| Multi-label `block_kinds` (entity AND code) | **majority** |
| HNSW index on kind column (M=16, efc=200) | **majority** |
| Read-after-write consistency / CAS | **unanimous (blind spot)** |
| Write-time consolidation worker | split |
| Per-kind global summaries (GraphRAG) | minority |
| Self-editing on recall (MemGPT) | split |

## Cited prior art

| System | Pattern worth borrowing |
|--------|-------------------------|
| **MemGPT / Letta** | Write-time memory consolidation + self-editing on recall |
| **ChromaDB** | `where` clause as inverted index on metadata (kind→block_id) |
| **GraphRAG (MSR 2024)** | Per-kind global summaries precomputed on write |
| **Pinecone** | HNSW for kernel graph-walk |
| **Jina DocArray** | Subindexing per modality |

## Action items

### Fixed in this commit (highest leverage, correctness first)

1. **Tier-memory CAS** (closes the unanimous blind spot)
   - Add `block_version INTEGER NOT NULL DEFAULT 0` column to
     `block_recall_tier`.
   - Add `expected_version` parameter to all tier-write functions
     (lands when promotion writes are added).
   - Reject stale writes with `StaleVersionError`.
2. **Multi-label `block_kinds`** (majority agreement)
   - Add additive `block_kind_tags(block_id, kind, PRIMARY KEY(block_id, kind))`
     junction table.
   - Single-label callers keep working via the `blocks.kind` column.
   - Multi-label callers use `set_block_kinds` / `get_block_kind_tags`.

### Deferred (need separate tracks, not foundation work)

3. **Pre-computed kernel candidates** — wait until actual kernel
   strategies (surprise_weighted / lineage_first / graph_walk) land;
   the materialised view design depends on what those strategies
   actually filter on.
4. **Vector quantization (PQ)** — orthogonal to foundation; ties to
   the embedding backend choice (sqlite-vec vs pgvector) and is a
   storage-layer optimisation, not a v4 surface concern.
5. **HNSW kind index (M=16, efc=200)** — depends on ANN backend
   selection; sqlite-vec already exposes HNSW, pgvector route differs.
   Track separately.
6. **Write-time consolidation worker (MemGPT pattern)** — needs the
   surprise-weighted clustering primitive, which depends on
   :func:`surprise_retrieval.centroid` being wired through the
   recall log — wait for that wiring.

### Also deferred for later

7. **Per-kind global summaries (GraphRAG)** — `kind_summary(kind,
   embedding, entity_count)` precomputed on write, fused into DEFAULT
   kernel. Worth doing once the fusion module lands.
8. **Self-editing on recall (MemGPT)** — `edit_block_on_recall(block_id,
   delta)` triggered by contradicts_first kernel; integrates with the
   v3.x propose/approve governance flow rather than going around it.
   Defer until v4 governance UX lands.

## Provenance

Raw review responses were kept locally at review time rather than committed
(the prompts and responses are not load-bearing for the codebase). The
panel produced enough cross-model signal to identify the unanimous blind
spots and the highest-agreement improvements above.
