Self-Ignorance Coverage Ledger

Known unknowns in the current surface

It answers one question: across declared Kind Atlas families, how many option-surface rows has the generated System Atlas not yet materialised? A navigation system that lists what it knows is easy to build. One that can state precisely what it has not yet covered is harder, and it is the more honest signal to a cold reader. This component answers a single question: for a declared set of Kind Atlas families, how many rows does the option surface expose that the generated System Atlas has not yet materialised?

Computed unknown-coverage debt vector

The answer is a computed debt vector: for each kind it subtracts materialised entities from the live row count and reports the difference as known coverage debt. The answer is a small debt vector, computed rather than asserted. For each selected kind the component recomputes the live Kind Atlas row count, counts the entities the System Atlas graph has actually materialised, and reports the difference as known coverage debt. It emits a metadata-only result record with the counts, the source references, and an explicit scope limit.

Refusing false completeness

Its unusual part is refusal: it rejects any claim that unknown-unknowns are exhaustive, treating known debt as a bounded count of visible gaps, never a completeness proof. The unusual part is what it refuses. It will not accept input that claims its unknown-unknowns are exhaustive, and it will not treat the absence of a row as proof that nothing is missing. Known debt is a bounded count of gaps it can see. It is never a completeness proof.

Purpose

The narrow middle between vague and overconfident

Systems overstate coverage either vaguely or overconfidently, so this component computes the finite gap between what the option surface exposes and what the graph materialised. Navigation systems overstate themselves in two opposite ways. A vague "coverage is incomplete" tells a cold reader nothing operational. A confident "nothing else is missing" is worse, because it converts absence of evidence into evidence of absence. This component occupies the narrow middle. For a declared finite domain of Kind Atlas families it computes the gap between what the option surface exposes and what the System Atlas graph has materialised, and it reports that gap as a number with its basis attached.

The negative output the checker must reject

Beside the bounded debt vector, the checker must reject exhaustive-coverage claims, hand-authored counts, substituted ids, stale baked ids, a tampered builder marker, or an understated debt floor. The positive output is a bounded debt vector. The negative output matters as much: the checker must reject input that claims exhaustive unknown-unknown coverage, hand-authored materialisation counts, substituted entity ids, stale baked ids used as authority, a tampered graph builder marker, or a coverage debt that understates the declared floor.

How it works

Entrypoints and the evaluate core

run and run_self_ignorance_bundle are the entrypoints, evaluate is the core over four bundle files, and evaluate_negative_case replays the semantic negatives. The runtime lives in src/microcosm_core/organs/self_ignorance_coverage_ledger.py. The command entrypoint is run; the exported-bundle entrypoint is run_self_ignorance_bundle; the core evaluator is evaluate; the semantic negative-case replayer is evaluate_negative_case. evaluate consumes four bundle files and runs the following order.

Binding the coverage scope and check result record

_projection_protocol_receipt checks the protocol against the expected scope and System Atlas check command, raising a mismatch when either the scope string or the result record status is wrong. First it loads kind_atlas_rows.json, materialized_entities.json, and projection_protocol.json. _projection_protocol_receipt checks the protocol against two constants: EXPECTED_COVERAGE_SCOPE and EXPECTED_SYSTEM_ATLAS_CHECK_COMMAND. A scope that is not the expected live-versus-generated string raises SELF_IGNORANCE_PROJECTION_PROTOCOL_SCOPE_MISMATCH. A check result record whose command is wrong, or whose status is outside ALLOWED_SYSTEM_ATLAS_CHECK_STATUSES (pass or a declared blocked refresh), raises SELF_IGNORANCE_SYSTEM_ATLAS_CHECK_RECEIPT_INVALID.

Recomputing live row counts through build_kind_atlas

_rows_with_live_kind_atlas_counts overwrites fixture counts with freshly built build_kind_atlas row counts, or falls back to declared counts at a lower realness rank when the builder is absent. Next _rows_with_live_kind_atlas_counts recomputes the live row counts. When the wider repository is present it imports build_kind_atlas from system.lib.kind_atlas and overwrites each fixture-declared count with the freshly built row_count. When the builder is not importable it records unavailable and falls back to the declared counts, which lowers the realness rank.

Materialised ids derived from the graph

_system_atlas_graph_materialization rejects an empty graph or wrong builder marker, then buckets entity ids by kind so the materialised set comes from the graph, not a declared number. Then _system_atlas_graph_materialization loads system_atlas_graph.json. It requires non-empty entity rows and rejects an empty graph with SELF_IGNORANCE_REAL_ATLAS_GRAPH_EMPTY. It requires the graph to carry the build_system_atlas.py builder marker; a different marker raises SELF_IGNORANCE_ATLAS_GRAPH_BUILDER_MISMATCH. _materialized_ids_by_kind_from_graph then buckets the entity ids by kind using MATERIALIZED_PREFIX_BY_KIND (concept_, mechanism_, pm_, std_, and so on), so the materialised set is derived from the graph rather than from a declared number.

Graph ids must resolve to real source files

_source_validate_expected_entity_ids requires each graph id to resolve to a real source file so the set cannot be inflated, and cross-checks the bundled slice against the live graph. _source_validate_expected_entity_ids checks that graph-derived ids for concepts, mechanisms, and standards resolve to real source files through _entity_source_exists. An id with no file behind it raises SELF_IGNORANCE_EXPECTED_ENTITY_ID_SOURCE_MISSING, so the materialised set cannot be inflated with names that do not exist. _live_system_atlas_graph_materialization cross-checks the bundled graph slice against the live System Atlas graph when it is available; a divergence raises SELF_IGNORANCE_LIVE_SYSTEM_ATLAS_GRAPH_MISMATCH.

Computing debt and rejecting tampered counts

evaluate takes debt as live rows minus materialised, and raises errors when a declared count disagrees with the graph, understates the floor, or claims exhaustive absence. With those bound, evaluate computes the debt. For each kind it takes known_coverage_debt_count = max(live_kind_atlas_row_count - materialised_count, 0). _expected_entity_ids_source_backed decides whether declared ids may stand in for graph ids. A declared count that disagrees with the graph-derived count raises SELF_IGNORANCE_MATERIALIZATION_COUNT_NOT_GRAPH_DERIVED. A declared debt below the fixture floor raises SELF_IGNORANCE_COVERAGE_DEBT_MISMATCH. If absence_policy.claims_unknown_unknowns_exhaustive is true, it raises SELF_IGNORANCE_FORBIDDEN_ABSENCE_INFERENCE.

Result record and the realness rank ladder

The record reports status, per-kind debt, evidence, and scope limit, earning R4 only when every recompute and cross-check ran, else R3 or R2, with no source bodies inside. The result record reports status, the per-kind debt rows, the graph and live-graph evidence, the realness rank, and the scope limit from AUTHORITY_CEILING. The rank is R4 only when the debt was recomputed from live counts, the ids are source-backed, the Kind Atlas recompute ran, the protocol result record passed, and the live graph cross-check ran or the wider repository is absent. Otherwise it is R3 when a graph was supplied and R2 when it was not. No copied source bodies enter the record.

flowchart TD KA["kind_atlas_rows.json live row counts"] Graph["system_atlas_graph.json materialised ids by kind"] Proto["projection_protocol.json scope + check result record"] Src["concept / mechanism / standard source files"] Eval["evaluate()"] Debt["known debt vector per kind"] Rec["metadata-only result record counts, refs, scope limit"] KA --> Eval Graph --> Eval Proto --> Eval Src --> Eval Eval --> Debt Debt --> Rec

The current bundle's debt snapshot

The current bundle shows 503 live rows against 307 materialised for a known debt of 196, all snapshot facts to rerun after any Kind Atlas, System Atlas, or source-set move. For the current bundle the count vector is concepts 41 rows against 30 materialised (debt 11), mechanisms 36 against 28 (debt 8), paper modules 225 against 220 (debt 5), and standards 201 against 29 (debt 172). Total live rows 503, materialised 307, known debt 196. These are snapshot facts read from the bundle, not fixed constants. Rerun the check after Kind Atlas, System Atlas, or the source set moves.

Negative cases

Two negatives replayed from clean copies

evaluate_negative_case replays two named cases from fresh input, so an absence-inference claim or an understated debt is caught by the semantic evaluator even if it mislabels its own error code. The fixture declares two named negative cases in EXPECTED_NEGATIVE_CASES, and evaluate_negative_case replays each one against a fresh copy of the input rather than trusting a declared error label. forbidden_absence_inference sets claims_unknown_unknowns_exhaustive to true and must produce SELF_IGNORANCE_FORBIDDEN_ABSENCE_INFERENCE. coverage_debt_mismatch drops one materialised entity while raising the declared debt floor and must produce SELF_IGNORANCE_COVERAGE_DEBT_MISMATCH. Because the replay recomputes from clean copies, a case that lies about its own error code is still caught by the semantic evaluator.

Perturbation proves the count tracks the graph

Adding one source-backed standard entity moves known debt from 196 to 195, showing the count is coupled to the graph-derived set rather than a fixed number in prose. A perturbation check adds one real, source-backed standard entity to the graph and confirms the known debt moves from 196 to 195 while the result still passes. That shows the count is coupled to the graph-derived materialised set, not to a fixed number in prose.

Prior Art Grounding

Bounded coverage measurement as the analogue

The analogue is software coverage measurement like coverage.py and bounded checks like OpenSSF Scorecard, which give a useful signal over a declared set without claiming a complete proof. The nearest ordinary analogue is software coverage measurement. A coverage tool reports what was exercised or missed over a declared source set, not every possible missing behaviour. coverage.py is a useful reference for that bounded, observed-coverage pattern. The health-signal side is adjacent to bounded repository checks such as OpenSSF Scorecard, where a fixed set of checks yields a useful risk signal without becoming a complete proof. This component applies the same discipline to navigation coverage debt and keeps the scope limit in the same record as the count.

Validation Result record Path

From microcosm-substrate, run:

PYTHONPATH=src ../repo-python -m pytest -p no:cacheprovider tests/test_self_ignorance_coverage_ledger.py -q
PYTHONPATH=src ../repo-python scripts/build_doctrine_projection.py --check-paper-module-corpus
PYTHONPATH=src ../repo-python scripts/build_doctrine_projection.py --check

For a manual bundle run into a throwaway directory:

PYTHONPATH=src ../repo-python -m microcosm_core.organs.self_ignorance_coverage_ledger run-self-ignorance-bundle --input examples/self_ignorance_coverage_ledger/exported_self_ignorance_coverage_ledger_bundle --out /tmp/microcosm-self-ignorance-coverage-ledger/bundle --card

What a pass means for the snapshot

A pass means the bundle, manifest, two negative cases, and paper-module corpus are still coherent, and it proves no freshness beyond the checked snapshot. A pass means the declared bundle, the source-module manifest, the two negative cases, and the paper-module corpus are still coherent. It does not establish freshness beyond the checked snapshot.