# Mz Adapter Guide

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

- Skill: `materializeinc/mz-adapter-guide` (Agent Skill)
- Install (CLI): `npx skillmds@latest add materializeinc/mz-adapter-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/materializeinc/mz-adapter-guide/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: materializeinc (https://skillmd.com/u/materializeinc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/materializeinc/mz-adapter-guide

---


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