OpenParable
Skip to content
← Back to skills

Mz Adapter Guide

Development
mz-adapter-guide

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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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.