Skip to content
← Documentation

docs/two-worlds.md


Two worlds: the observed, and the observation

Statements about the repository and statements about the observation are different kinds of claim, and they may not share a visual carrier.

A confidence statement must never masquerade as a repository fact. A repository fact must never inherit uncertainty that belongs only to the observation.

The audit

Every statement the product makes, classified by its subject.

statement subject class
repo/bytes, commits-touching, authors-touching the file repository
containment / district the file repository
coupling, and the order derived from it the files repository
fact change the file repository
normalisation change the display's reference display
projection change the layout solver display
frame residual beside a position claim the alignment display
unplaced — observed, never co-changed the file repository
unplaced — no commit observed the window observation
unobserved (by extension) the connector's vocabulary observation
refusals the ontology observation
unattributable what was retained observation
window.truncated the clone observation

Three classes, not two: the display's own machinery is a third subject, and it is neither the repository nor the observation.

The collision that was there

Five causes rendered through one carrier with a single real: boolean. "The solver moved it" and "we could not tell" both read as not a change in the repository — true of each, and a merger of a display claim with an observation claim. They are not interchangeable: one is noise a reader should ignore, the other is a gap in what was measured and should stop them trusting the mark at all.

Now each class has its own tone and its own aside:

class tone aside
repository full contrast none — the claim stands alone
display muted "not a change in the repository"
observation amber "a limit of what we measured, not a finding"

Guarded by three tests: a repository fact carries no observation caveat, a display artifact and an observation limit never share wording, and a refusal is never labelled a display artifact.

Why this is not just another fact family

The second class cannot be expressed as facts about subjects, because its subject is the observer. Everything in it was added after a measured failure:

  • a Python repository rendering an empty city beside an empty refusal list
  • a shallow clone fabricating a commit that touched every file
  • an omission that never left acquisition
  • 1925 subjects across two repositories told they never co-changed when their history had simply not been read

None was a false statement about a file. Each was a true statement about a file standing in for a missing statement about the observation.

Standing rule

Before adding any statement to a surface, name its subject. If the subject is the observer rather than the world, it may not use a repository carrier.

Open

  • The absence panel lists unplaced (which is now two classes — repository and observation) beside unobserved (observation). The list is correct per-entry but the panel still groups across classes.
  • No human has read any of this. Whether the three tones are actually distinguishable is condition 3, and cannot be self-certified.