AGENTS.md #
Operating contract for agents using this corpus (25 files: 24 canonical blocks + _index.md). Read this file completely before touching the corpus.
What this corpus is #
A closed system of distributed-systems design knowledge:
24 blocks, each owning ONE set of mechanisms
1 capstone (_index.md) owning the meta-layer:
- 3 enemies (the primitive failure classes)
- 23 stars (* = per-block technical bottlenecks)
- 1 ^o (Termination: no recipe exists — FLP)
- 9 strength ladders under one gradient (hope → proof)
- the gap/overlap dial (8 sites)
- the topological design order (11 steps)
Every mechanism is defined in exactly ONE file. Cross-references are
written as → file.md or (→ file.md axis N). An arrow means:
do not restate; load and cite.
Entry protocol #
1. ALWAYS load _index.md first. It is the router.
2. NEVER load more than: the owning block + its direct arrows.
Files are context-cheap individually; the ownership graph makes
selective loading CORRECT, not lossy.
3. If two files seem to cover one topic, _index.md's treaty decides
the owner. Load the owner.
Task routing #
TASK: "design X"
→ walk _index.md Part III (the 11-step topological order).
Each step names which blocks to load and which interrogations to
answer BEFORE proceeding. Do not skip steps; do not reorder.
Exit criterion per step: the step's interrogations have answers
specific to X, not generic ones.
TASK: review a design doc / PR
→ identify which blocks the change touches (_index.md Part IV,
column 1).
→ load those blocks; run their axis interrogations VERBATIM as
review questions against the artifact.
→ scan the doc for the blocks' Deep Lesson confusion pairs; each
pair found is a flag, cited as block + axis.
TASK: incident / bug triage
→ map the symptom to a star via _index.md Part IV (the dispatch
table) or Part I (the enemy roster).
→ load the owning block; apply the star's recipe list in order.
→ duplicate effects → retry_idempotency (atomicity domain).
stale/zombie writer → lease_fencing (paused holder).
missing results → index (silent incompleteness) or snapshot (torn).
overload spiral → backpressure (goodput).
resurrection → garbage_collection (tombstone phase 2).
TASK: "explain system X" / "compare X and Y"
→ find X's row in the relevant block's Named Configurations table.
The row is a VECTOR on the block's axes. Expand the vector;
derive failure modes from axis positions rather than reciting them.
→ for comparisons: diff the vectors, axis by axis.
TASK: generate new design content
→ follow the write rules below.
Notation semantics (operational) #
X* technical bottleneck: essential, exactly one recipe family.
When encountered: the recipes are listed at the star's
definition; apply them in the order given (they are ordered
by escalation or completeness).
X^o no workable recipe exists (only Termination^o; semantic gap*
is near-^o). NEVER claim to solve these; state the bet being
made instead (partial synchrony; naming discipline).
ladder a strength gradient, hope at the bottom, proof at the top.
When a design sits on a low rung, ask what forces the climb;
when it pays for a high rung, ask what would let it descend.
the dial gap-vs-overlap at any handoff. There is no "neither."
Require the design to name its choice and its payment
(availability for gap; fenced idempotency for overlap).
one door atomic publication. Any view assembled from two separately
fetched parts is flagged as torn-visibility risk.
→ load-and-cite. Restating an arrowed mechanism is an error.
Write rules (when producing design content) #
1. ONE OWNER: never re-derive a mechanism another file owns.
Reference: "(→ lease_fencing.md: downstream fencing)".
2. NEW MATERIAL must declare: its structural cleave (the one axis that
changes interface shape), its star or its arrows, and its position
in the tier lattice.
3. INTERROGATIONS ANSWERED become the document's structure: a design
doc section per Part III step, each containing that step's answered
questions. A question without an answer is written as an open risk,
not omitted.
4. CITE by block + axis ("cache.md axis 4"), never by vibes.
5. ONE-LINERS (Part IV column 5) may be quoted as summaries; they are
mnemonics, not proofs.
Epistemic limits (read carefully) #
1. This corpus is a REASONING SCAFFOLD, not ground truth about any
specific system. Vector rows describe canonical study objects
(SQS, Kafka, Iceberg) as of their writing; verify against the
actual system's current behavior before asserting.
2. Do NOT assume shape implies semantics: a thing called a queue is
not SQS-shaped until its retention/ack/lease vector is confirmed
from its docs or code.
3. One-liners are PRIORS. "Ack ≠ effect" tells you where to look,
not what you found.
4. The topological order is a dependency of MEANINGFULNESS, not a
waterfall: real designs iterate. Back-edges from evaluation
(capacity, telemetry) into earlier steps are expected and correct.
5. If a question falls outside the corpus (UI, ML modeling, specific
vendor pricing), say so; do not stretch a block to cover it.
Output conventions #
reviews: findings as {block, axis, interrogation, evidence-in-diff,
severity}. Confusion-pair matches cite the Deep Lesson row.
designs: structured by Part III steps; each step lists blocks
loaded, questions answered, and stars acknowledged with
chosen recipes.
triage: {symptom → enemy → star → owning block → recipe applied →
what would confirm/refute}.
always: distinguish corpus-derived claims (cite block+axis) from
system-specific claims (cite code/docs/observation).
File map (load targets) #
TIER 0 identity.md
ROOT quorum.md
TIER 1 queue.md scheduler.md boundary.md policy_capability.md
cache.md log.md replication.md shard.md
TIER 2 state_machine.md checkpoint_replay.md backpressure.md
garbage_collection.md lease_fencing.md retry_idempotency.md
snapshot.md versioning.md
FACES index_structures.md materialized.md routing.md
EVAL capacity.md telemetry.md
CAPSTONE _index.md (also transaction.md sits TIER 1/2 seam:
consistency boundary + atomicity-domain factory)
The corpus’s own value structure, for orientation: _index.md is the strategic entry point — all routing flows through it; the interrogation lists are the recipes the system exists to deliver; the treaty (one owner per mechanism) is what makes selective context-loading sound. Honor the treaty and the corpus stays cheap; violate it and every answer becomes a restatement risk.