Skip to content
Cognithamus
Create account
← Documentation

docs/representation-candidates.md

Four representations of the same repository

The control is the shipped layout. The rest are experiments, not replacements. Prototyped as SVG rather than through the 3-D scene, because the question is the spatial model and the shipped model carries one real dimension (layout-is-a-line) — a top-down view loses nothing it has.

node scripts/prototype-layouts.mjs regenerates all four from the live world.

A · CONTROL — the shipped embedding

  1. Claims 2-D distance approximates coupling distance; a plane; district rings enclose places.
  2. Stops claiming nothing.
  3. Immediately understandable that there are many files, and roughly how tall each is.
  4. Harder everything else. Three of its four claims are false: stress-1 1.029, r(x,z) = −1.000000, district mean span 39.5% with 18/28 extents overlapping.
  5. Uniquely improves no measured task.

B · TREEMAP — containment and magnitude

  1. Claims a cell's district is its directory (exact); area is proportional to bytes (exact, and the only candidate that states magnitude exactly rather than by height or width); nesting is containment.
  2. Stops claiming coupling, entirely. There is no position relation between any two files beyond sharing a parent.
  3. Immediately understandable the composition of the repository, at a glance and without zooming: src/lib and tests are the two dominant parts and are comparable; src/components is a clear third; src/app, tests/dom, scripts, src/core and the root are small. Every one of the 178 files is individually visible.
  4. Harder anything relational. Two files that always change together are placed apart if they sit in different directories, and nothing on screen suggests otherwise.
  5. Uniquely improves what is this repository made of — the first-contact question, answered better than any other candidate.

C · MAP — district blocks, coupling order inside

  1. Claims district = directory (exact); within a district, order follows coupling order (exact); districts ordered by first appearance in that order (exact). Block width is member count.
  2. Stops claiming distance, and the global coupling ordering — measured cost: 61.0% of immediate coupling neighbours preserved, 85.4% pairwise (Kendall).
  3. Immediately understandable the same size story as B, less precisely (width is member count, not bytes), plus which directories sit next to each other in coupling order.
  4. Harder exact magnitude, and cross-district coupling.
  5. Uniquely improves what belongs together — the only candidate that keeps the co-change relation in the geometry at all.

D · LINEAR — the true 1-D order, couplings as arcs

  1. Claims the coupling ordering, exactly and globally, plus the 120 strongest couplings as arcs.
  2. Stops claiming any second dimension. The only candidate that makes no spatial claim it cannot support.
  3. Immediately understandable that districts are banded along the coupling order — colour runs magenta → blue → green rather than shuffling, which is the 3.2×-above-chance path locality made visible.
  4. Harder the arcs are dense and mostly long-range — honest, since the couplings genuinely span the order, but unreadable individually. Nothing about relative size is legible.
  5. Uniquely improves understanding of the ordering itself. Most truthful; not the most comprehensible.

Reading

A correction first. An earlier draft of this file recommended C and dismissed B. B's implementation was broken at that point — it overflowed the frame and drew 4 of 8 districts — and I wrote that up as though the representation had been evaluated. It had not. Implemented properly (recursive binary split, longest side first), B is the strongest candidate on legibility and its claims are exact.

B and C answer different questions, and both beat the control.

  • B answers what is this made of better than anything else here, exactly. But everything it shows, a reader could also get from directory sizes. It communicates nothing the repository's own file tree does not already contain.
  • C is the only candidate that keeps co-change in the geometry — the one relation this system computes that a file tree cannot give you, and the one the city was still uniquely earning.

So the choice is not aesthetic. It is: should the spatial view show what is already knowable, beautifully, or what is only knowable here, less precisely?

The evidence favours C for the city and B for an overview, and they are not mutually exclusive — B is a legend for scale, C is a map of relation. Neither is the control.

Not yet done

  • C and B at other scales. zustand places 5 buildings and httpie places 0; both layouts must degrade truthfully rather than drawing a neighbourhood around one building.
  • Either in the 3-D scene, with before/after captures against the depth-2 city.
  • No human has read any of these. Every "immediately understandable" above is my reading of my own output, which condition 3 of the standing objective says cannot be self-certified.