Skip to content
Cognithamus
Create account
← Documentation

docs/perceptual-audit.md

Perceptual fidelity — first audit of the rendered world

Measured 2026-08-03 against the scene-graph object, by rendering the same WorldScene under two fact sets and diffing every built three.js object:

  • A — height 6, activity 0.1, blocked 0, health ok
  • B — height 20, activity 0.9, blocked 5, health fail

Result: 2 of 12 scene objects carry information

Count
Objects that changed between A and B 2
Objects identical under both 10

Ten of twelve built objects — ground plane, grid, three lights, district ring, containers — are invariant under every fact change tested. By condition 4's measurable lower bound they carry zero information.

That is not automatically a defect. A ground plane is a spatial reference, and reference frames legitimately carry no data. But it means all organizational reality currently reaches the observer through four channels, and the audit's value is in naming exactly which.

The four informative channels

Channel Encodes Observed
Mesh position.y building height 3.00 → 10.00
Mesh material.emissive accent, or alert 7bd57b → ff8a6b
Mesh material.emissiveIntensity activity 0.205 → 0.885
An added Mesh at y=46 blocked work absent → present, col=ff8a6b

Everything a viewer can learn about the organization arrives through these four.

Finding 1 — the emissive channel encodes two independent facts

Measured. Under A the building's emissive is 7bd57b, which is hueFor(identity). Under B it is ff8a6b, the ALERT constant. The same visual channel therefore carries:

  • identity when the building is healthy, and
  • operational state when it is failing.

An observer seeing a colour cannot know which question it is answering without being told the convention. That is precisely the condition-3 failure mode: the feature is noticed but does not let the viewer reconstruct which fact produced it.

It is also the standing Article I.3 violation — the renderer classifying operational state — now visible at the scene-graph object rather than inferred from source.

Not a collision in practice, and that is worth stating precisely. hueFor emits hsl(H, 52%, 66%); ALERT is roughly hsl(15, 100%, 71%), outside that saturation band. So no entity's identity colour can equal the alert colour. The defect is not ambiguity of value — it is ambiguity of meaning: the channel's semantics change depending on a fact the channel does not itself carry.

Finding 2 — the alert marker duplicates the emissive signal

Under B, both the emissive turns ff8a6b and a marker appears at y=46 in the same colour. Two channels carry one fact.

Redundancy is not automatically waste — it can aid perception. But by condition 4 it is currently unmeasured: nothing establishes that the duplicate improves understanding, and one of the two could be freed to carry a fact that presently has no channel at all.

Finding 3 — health has no dedicated channel

health is ok | warn | fail | unknown, four states. The scene distinguishes only fail-versus-not, via the emissive override. warn and unknown are not rendered at all.

unknown is the significant loss. It is the value that separates not measured from measured healthy — the same distinction the provenance work restored at the World boundary. It reaches the World and then disappears at the renderer, so a viewer cannot distinguish a healthy building from an unobserved one.

This is the sharpest perceptual-fidelity defect found, and it maps directly to the standing objective's example: "distinguishing missing observations from negative observations."

What this audit cannot establish

Nothing here measures understanding. Every result above concerns conditions 1, 2 and the measurable lower bound of 4. Condition 3 — that independent knowledgeable observers consistently infer the intended reality — requires an evaluation with people, and none has been run.

So the findings are ranked by information loss, which is measurable, and not by comprehension gain, which is not. A change that fixes finding 3 might still fail to help an observer; that would itself be a finding, and only an observer study could produce it.

Ranked targets

  1. Finding 3 — render unknown health. Highest measured information loss: a four-state fact rendered as two. Restores the missing/negative distinction the architecture treats as load-bearing everywhere else.
  2. Finding 1 — separate identity from state. Removes semantic ambiguity from the channel that carries the most. Blocked: the repair needs a Legend row and the Legend is constitutional.
  3. Finding 2 — the duplicated alert. Lowest priority, and the one most likely to need an observer study rather than a measurement, since redundancy may genuinely aid perception.