mz-adapter-guide

name

mz-adapter-guide

description

Correctness invariants + architecture: adapter, coordinator, pgwire, peek paths, timestamp oracle. Trigger: questions about these subsystems — "how does coordinator work", "what are read holds", "explain peek path", "how does timestamp selection work", "why does this query block". Also when editing OR reviewing code in src/adapter/, src/pgwire/, src/timestamp-oracle/ (reviewing a PR, diff, or commit that touches these paths counts).

Adapter Guide Skill

When working on or reviewing the adapter layer or related crates, always read and follow the guidance in doc/developer/guide-adapter.md. That document contains correctness invariants, architectural notes, a list of optimizations that have been tried and rejected for correctness reasons, and a checklist for reviewing adapter changes. Read it before making changes and before reviewing them.

Read doc/developer/guide-adapter.md now.

When working on the timestamp oracle (src/timestamp-oracle/), also read the module-level docs in src/timestamp-oracle/src/lib.rs and src/timestamp-oracle/src/batching_oracle.rs for the TimestampOracle trait contract and the batching/linearizability invariants.

When you or the user discover that an approach is incorrect or heading in a wrong direction, suggest distilling the learning into doc/developer/guide-adapter.md. Add it to whichever section fits best — a new correctness invariant, a new subsection under an existing invariant, a rejected optimization, or a new top-level section if needed. Describe what was tried, why it's wrong, and any relevant context. This keeps the guide up to date and prevents future re-discovery of the same pitfalls.