computer-science

​

Grain

​

Description

The level of resolution at which an entity is individuated — its identity-grain. Every named entity has a grain: a session has session-grain, a user has user-grain, a field has field-grain, a program has program-grain. Grain matters because decisions that look like single choices are often two entangled decisions — “what rule applies?” and “at what grain does it apply?” Confusing grains produces bugs with a characteristic signature: behavior that seems correct locally but breaks at the wrong level of aggregation or disaggregation. The grain-coupling move is the key diagnostic: when a decision behaves differently depending on the grain at which you inspect it, you’ve found grain-coupling. The move is to decouple the grains — identify that what looked like one decision was actually two, each operating at a different level of resolution. This is structurally analogous to separating orthogonal axes of variation in matrix decomposition: what appeared as a single blob has identifiable components.

​

Triggers

User-initiated: User is asking about granularity, resolution, or the “unit” of something. Also when a bug is described as “correct in some cases but wrong in aggregate” or “works for one X but breaks for multiple Xs.” Agent-initiated: Engine notices a rule or design decision that appears to operate at multiple levels simultaneously without explicit handling for the level mismatch. Candidate inference: “this decision is grain-coupled — what are the two (or more) distinct grains entangled here, and which grain is load-bearing for each sub-decision?” Vocabulary cues: “per-session,” “per-user,” “per-field,” “per-item,” “per-request,” “granularity,” “resolution,” “unit of X,” “what counts as one X,” “level of detail,” “aggregate,” “disaggregate.” Situation-shape signals: A rule that feels right at one level of inspection but wrong at another. A design decision where reasonable people disagree because they’re implicitly using different grains.

​

Exclusions

• Uniformly single-grained systems — a system where all decisions operate at a single, unambiguous grain has no grain-coupling to diagnose. The concept earns its keep when multiple grains are in play simultaneously.
• When “granularity” is just a detail choice — adjusting resolution along a dimension that doesn’t affect correctness (e.g., choosing how many decimal places to display) doesn’t require the grain frame. Grain matters when the resolution choice affects what rules apply or what counts as the same entity.
• Pure aggregation — when explicitly summing over a dimension (total users, total events), the grain is the aggregate itself and usually isn’t ambiguous.

​

Structure

​

Relationships

• stack-layer — composition relationship — grain and stack-layer often co-occur: layers in a stack operate at different grains, and grain mismatches across layers produce characteristic bugs. The grain diagnostic complements the load-bearing-layer diagnostic.
• load-bearing — composition relationship — “what is the grain of this decision?” is a load-bearing question: it determines which operations are valid at which level. A decision at the wrong grain is not load-bearing in the right place.
• uniformity-dividend — composition relationship — a uniformity dividend requires all instances to share the same grain. If grains differ, uniformity is illusory (the invariant doesn’t hold across the dimension being standardized).
• cadence — composition relationship — cadence choices are implicitly grain choices: “daily cadence” is day-grain; “per-event cadence” is event-grain. Cadence mismatches (process grain ≠ data grain) are a common source of accumulation error.
• doctrine — composition relationship — a doctrine applied at the wrong grain is ineffective or harmful. Doctrine entries should specify their grain explicitly: “when [condition] at [grain], apply [rule].”

​

Examples