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) besideunobserved(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.