Rules reference

A rule is one file, one check, and a sentence a reviewer would have written. The vocabulary below is fixed on purpose: a rule that cannot be written with it is a request to extend the list, with the rule as the evidence — not a request for an expression language.

The shape of a rule file

1schemaVersion: "1"
2type: "rule"
3id: "queue-missing-dlq"
4severity: "error"
5select:
6  node:
7    kind: "queue"
8when:
9  all:
10    - prop: "deadLetterQueue"
11      equals: false
12    - hasEdge:
13        direction: "in"
14        mode: "async"
15message: "Queue '{{node.id}}' receives async traffic but has no dead-letter queue."

The display name, the rationale and the description live in locales/en.yaml, keyed by the rule id, like everything else people read.

select

select chooses the subject, and the subject decides which predicates make sense.

The predicate vocabulary

Predicates compose with all, any and not. Everything else is a leaf.

Composition

1when:
2  all:
3    - prop: "replication"
4      equals: "none"
5    - not:
6        requirement: "availability.multiRegion"
7        equals: true

Node properties

1when:
2  prop: "evictionPolicy"
3  exists: false

The value tested is the effective value: the node's props, then the component's defaults, then the property definition's default. A property that resolves to nothing is omitted, so exists: false is true both for a property nobody set and for a name that is not a property of this node's kind at all.

Exactly one comparison applies per predicate, and they are tested in this order: exists, in, gt, lt, equals.

Edge fields

1select:
2  edge:
3    mode: "sync"
4when:
5  field: "timeoutMs"
6  exists: false

field reads one of mode, delivery, protocol, timeoutMs, retryPolicy, idempotent, circuitBreaker, fallback, batched, auth, and takes the same comparisons as prop.

Kind and provider

1select:
2  edge: {}
3when:
4  all:
5    - field: "auth"
6      in: ["api-key", "basic"]
7    - to:
8        provider: ["azure", "aws", "gcp"]

kind is true when the node's component is of that kind, provider when it comes from that provider; either may be a list. They read the node a rule is about, so on an edge they go under from or to. An unknown component matches neither.

Node NFRs

1when:
2  nfr: { rps: { gt: 10000 } }

Compares a node's nfr value. rps and latencyP95Ms are allowed. The comparison object takes exactly one of eq, gt or lt.

Design requirements

1when:
2  requirement: "availability.multiRegion"
3  equals: true

Available on every subject, because the requirement belongs to the design, not to the node. An absent requirement never equals anything.

Edges around a node

1when:
2  hasEdge:
3    direction: "in"
4    mode: "async"

hasEdge is true when at least one edge in that direction matches the filter.

1when:
2  hasEdge:
3    direction: "out"
4    mode: "sync"
5    peerCategory: "external"
6    count: { gt: 2 }

Nodes in the design

1when:
2  hasNode:
3    kind: "custom"

True when the design contains at least one node of that kind or category. Available on every subject.

Groups

1when:
2  inGroup:
3    kind: "region"
4    count: { lt: 2 }

inGroup counts the groups of that kind in the node's ancestry — its group, that group's parent, and so on. Without count, it means "at least one".

1select:
2  edge: {}
3when:
4  crossesGroup:
5    kind: "cell"

crossesGroup is an edge predicate: true when the two ends sit in different groups of that kind, or when one of them is in none.

Call depth

1when:
2  syncChainDepth: { gt: 3 }

The longest path of consecutive sync edges starting at this node. Cycles are cut at the first revisit, so the answer is always finite.

Reaching across an edge

1select:
2  edge:
3    mode: "sync"
4when:
5  all:
6    - to:
7        prop: "usedAsPrimaryStore"
8        equals: true
9    - field: "timeoutMs"
10      exists: false

from: and to: evaluate a node predicate against the edge's source or target. They are how an edge rule asks a question about the thing at the other end.

How "tripped by" works

Every rule ships with a reference design that trips it and one that does not.

designs/reference/<id>/design.yaml is the clean variant and must trip no rule. design.broken.yaml beside it is a deliberately incorrect copy whose header comment lists the rule ids it is expected to trip. The repository gate checks both directions: the clean design must stay clean, the broken one must trip exactly what it claims, and a rule that no design trips fails the gate.

That is why every rule's page lists the designs that trip it — the list is read out of those headers, not maintained by hand.

Severity

No rule finding ever blocks a save, whatever its severity. Only structural findings do that.

Every rule that ships

Generated from the catalogue this site is serving. Each id links to its own page, with the condition in plain English, the kinds and components it covers, and the designs that trip it.