Mz Adapter Guide
Developmentmz-adapter-guideMz Adapter Guide is an Agent Skill for development published in the MaterializeInc/materialize repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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).
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/MaterializeInc/materialize/blob/HEAD/.agents/skills/mz-adapter-guide/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/mz-adapter-guide, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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.