The representation calculus

representability.md derived fidelity for channels. This derives it for representation classes — and the result is stronger than a catalogue, because one law explains six of seven.

src/lib/grammar/representations.ts, tests/representations.test.ts.

---

1. The signature

A representation class is characterised by three things, and the middle one is what a channel-level grammar cannot see:

preserves	the algebras it carries faithfully
asserts	claims it makes structurally, whether or not the data licenses them
requires	preconditions; violate one and the drawing does not degrade, it lies

2. The seven

Class	Preserves	Asserts	Requires
table	categorical, ordered	axis order; adjacency = similarity	—
matrix	categorical, ordered, directed, symmetric	order on both axes; adjacency = similarity	binary
timeline	ordered	axis order; lane order; empty = nothing happened	temporal
tree	categorical	axis order; single parent	functional parent, acyclic
heat map	ordered	order on both axes; perceptual uniformity	binary
Sankey	directed, ordered	conservation at nodes; layer order	acyclic, conserving
force layout	nothing	adjacency = similarity	deterministic

What each false claim actually is

• table — values are written literally, so nothing about them distorts. Row position is still an ordering claim on data that may have no order.
• matrix — lossless for the relation. Cell (i,j) is the fact, and direction survives because the matrix is not symmetric. This corrects representability.md, which called the matrix lossless without qualification: it is lossless for the relation and its axis ordering is a separate, unlicensed claim unless seriated.
• timeline — a stretch with no marks reads as "nothing happened" when it may mean "nobody was looking." That is the missing-versus-zero rule, made structural to a representation rather than to a channel.
• tree — carries containment only where the parent relation is a function. Given a DAG it must duplicate the shared node — asserting two things where there is one — or drop a parent. Both are false, and the choice is invisible to a reader.
• heat map — colour is perceptually non-uniform, so equal numeric steps read as unequal. The drawing distorts an ordering the data states exactly.
• Sankey — the sharpest. Width-in equals width-out because it is drawn that way. A flow with unmeasured leakage renders as balanced: the diagram fabricates the invariant it appears to demonstrate.
• force layout — preserves nothing, and seeded randomly it is a function of (data, seed). Two renders of unchanged data differ, so a reader comparing them sees change that did not occur.

3. The law that generalises R2

R2 said a categorical space on a spatial channel invents proximity. Measured across the catalogue, the general form is:

Every positional axis asserts an ordering on what it places. If those values are categorical, the ordering is a false claim unless a metric or a derived seriation licenses it.

unlicensed axis ordering refused by:
  table, matrix, timeline, tree, heat map, Sankey diagram

Six of seven classes, one law. R2 was a single instance of it, and the escape is the same: declare a metric.

4. Two laws that do not come from position

• Determinism. A representation must be a function of the data. This is functionality (dimension-algebra.md) applied at the representation layer, and it refuses the force layout regardless of the data — the only refusal in the calculus that never consults the structure.
• Absence. A region with no mark must not read as "nothing happened" when it means "nothing observed."

Neither is about axes, which is why a purely spatial account would have missed both.

5. It answers the question the reconstruction asked

The repository refused 38 import dependencies: a persistent, directed, binary relation, cyclic, with multiple parents.

import dependency is carried without a false claim by: table, matrix, heat map

Tree is refused (multiple parents), Sankey is refused (cycles), force layout is refused (determinism), timeline is refused (no temporal extent). The calculus selects the representation rather than leaving it to taste — and it names the matrix, which is what representability.md argued from a different direction.

---

Two defects I introduced and had to fix

Both are the shape this project keeps finding, committed inside the instrument built to catch it.

Unstated preconditions passed silently. s.acyclic === undefined was treated as satisfied, so a structure that simply did not say whether it had cycles was handed a Sankey. That is missing-versus-zero inside the calculus — absence of a claim read as evidence of adequacy. Now an unstated precondition is its own inadequacy: "unstated is not satisfied."

Declared assertions with no check. perceptual-uniformity and adjacency-means-similarity were in the signatures and consulted nowhere, so the signature promised more than the calculus delivered — decorative, by this project's own definition. perceptual-uniformity is now checked; adjacency is subsumed by the axis-ordering law.

Both were caught by one output line reading timeline, heat map for a structure with no temporal extent. The result was wrong before the tests were.

---

Standing

Question	Answer
Does every class have a derived preservation law?	yes — seven, each with its false-claim mode
Is there a general law?	yes — positional axes assert order; 6 of 7
Are there laws outside it?	yes — determinism and absence
Does the calculus select representations?	yes — adequateFor(structure)
Was anything tuned to an observation?	no — the two fixes close holes, not thresholds

What is still not established

• Seven classes is not a closed set. Scatter plots, chord diagrams, treemaps, node-link diagrams and small multiples are absent, and nothing here says the seven are a basis rather than a sample.
• preserves is declared, not verified. Nothing checks that a matrix really carries a directed relation; the signature is asserted from argument.
• The calculus consults structural properties only. Two matrices with the same signature and wildly different legibility score identically — density, scale and label collision are invisible to it.
• The instead lists are argued, not measured. No test renders a matrix and confirms it carries what the calculus says it does.

180 → 188 tests, tsc clean.