Skip to content
← Documentation

docs/fact-visibility.md


Which canonical facts deserve to be visible

tests/fact-carriers.test.ts

The question deliberately inverted: not which channel carries change — that was answered and the answer was "none unconditionally" (change-channels) — but which facts have earned a carrier at all.

The governing constraint is prior to the ranking. A dormant channel is a fact about the channel. It is not evidence that the ontology is incomplete, and inventing a fact to fill one inverts the derivation discipline. So only facts the system already produces are eligible here.

The inventory

Everything the repository adapter emits, on this repository at b99546a:

canonical fact n distinct values carrier
repo/bytes 171 170 box height
repo/commits-touching 171 16 box emissive intensity
repo/authors-touching 171 1 none
placement (directory) 171 30 district
exchange (co-change) 477 links, position
condition stalled 0 none — and dropped, see below
import dependency refused (113)

Ranking the two invisible candidates

repo/authors-touching — rejected on evidence

criterion measurement
frequency present on all 171 subjects
explanatory value zero — 1 distinct value, range 1..1
stability subject-scoped; would be clean
existing carrier none, but hue or beacon could take it

The repository has one author in its entire history. The measurement is a constant. Giving a channel to a constant is the definition of decoration by docs/README.md's own criterion: a visual property that never varies with the facts carries zero information.

This is a fact about this repository, not about the metric. On a multi-author repository it would vary — and that is exactly why it is rejected now rather than dismissed: the evidence to justify a channel does not exist yet, so the channel is not justified yet.

stalled — a real carrier gap, still not a licence

The gap is measured, not hypothetical. worldFromFacts reads measure, placement and exchange; there is no condition branch. A generated fixture with commits from 2024 emits 4 stalled facts and 0 survive — every building reports health: "unknown". Asserted in tests/fact-carriers.test.ts, which fails when a carrier is added.

That is a carrier gap, not an ontology gap: the fact is canonical, already emitted, and already carries its declared warrant.

But the ranking still says no:

criterion measurement
frequency 0 of 171 subjects — and 0 at every threshold from 7d to 365d
explanatory value a convention, not evidence — 90 days is stipulated
stability subject-scoped (per-file last commit); clean by the corrected law
existing carrier yes — "alert beacon and label colour", dormant

The threshold sweep is the decisive number. File age here is p50 1.5 days, max 7.0 days: the whole repository was written inside one week. stalled does not fire at 90 days, and it would not fire at 7 either. The declared threshold is not mis-tuned — the fact has no discriminative power on this data at any setting.

It is also convention-warranted. Rendering it through a beacon whose ledger claim is "this subject is failing" would present a stipulation as an observation unless the threshold travels with it, which is the collapse warrant-audit.md exists to prevent.

Conclusion

No dormant channel should be filled on the available evidence. Both candidates fail the same way — not for want of a carrier, but for want of variance. One is a literal constant; the other never fires.

That is a stronger result than a ranking with a winner. It says the four dormant channels are dormant for the right reason: the repository substrate genuinely has three varying quantities, and three are already carried. There is no suppressed signal waiting for a channel.

Two things follow, and neither is "add a fact":

  1. The condition carrier gap is a defect and is recorded as one. Even though nothing here would flow through it, a repository with old files would have its conditions silently dropped. Fixing it is a carrier change, not an ontology change.
  2. The largest genuinely-missing signal is one the system already refuses. 113 import dependencies, refused because exchange is an occurrence and a dependency is a persistent relation. That refusal is a vocabulary question and remains where it was left — recorded, not retried.

Method note

repo/authors-touching illustrates why the reduction discipline must run on evidence rather than plausibility. "How many people touch this file" is an obviously useful organisational signal, and the argument for rendering it is easy to make in the abstract. On the actual substrate it is the number 1, repeated 171 times.