Skip to main content
  1. concepts/

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.