Engine Room Derived Fact Provider Engine

System claims things

A system that claims things about itself needs a disciplined way to fetch the numbers behind them, since any document that hard-codes them goes stale as the repository changes. A system that makes claims about itself needs a disciplined way to fetch the numbers behind those claims. How many files match a pattern. How many rows a registry holds. How many files git is tracking. Those are facts about the current state of the repository, and a document that hard-codes them goes stale the moment the repository changes.

For each authored fact row the engine reads how the row declares it resolves and produces the value now, emitting one record with a ledger, failure audit, cache, and content hash. This component answers one narrow question. For each authored fact row, what value does it resolve to against a supplied root, right now? A row declares how it resolves rather than what it equals, and the engine reads the declaration and produces the value. The output is a single result record carrying a ledger of resolved facts, an audit list of any provider failures, a small navigation cache, and a content hash.

Is provider engine

It is the provider engine, not a truth auditor: a clean record means the declared rows resolved against the supplied root, not that the underlying claims are true. It is the provider engine, not a truth auditor. A clean record means the declared rows resolved against the supplied root. It does not mean the underlying claims are true.

Purpose

A row declares how it resolves, not what it equals

A fact row carries a provider_type and its provider's fields, whether json_pointer, glob_count, or callable, and states no answer, so the value is derived on every evaluation. A fact row is a small object with a provider_type and the fields that provider needs. A json_pointer row names a source file and a pointer into it. A glob_count row names a file pattern to count. A callable row names one of a fixed set of git-backed computations. Nothing in a row states the answer. The answer is derived on every evaluation.

A failed row degrades to one repairable row

Rather than raise on the first unresolvable row, the engine turns it into a row carrying an error_class, message, and required_next_action, leaving the others resolved and the ledger degraded. The hard design choice is what happens when a row cannot resolve, for example because its source file is missing or its provider name is unknown. A loose engine would raise on the first bad row and abandon the rest. This one does not. A failed row becomes an ordinary row that carries an error_class, a human-readable message, and a required_next_action such as restoring the named source path. One broken fact degrades to one repairable row. The other rows still resolve, and the ledger reports degraded rather than dying with a stack trace.

How it works

Source file is

The source file is src/microcosm_core/engine_room/derived_fact_provider_engine.py. Evaluation runs bottom-up: one row, then the whole registry, then a directory of fixture cases.

resolve_json_pointer walks by pointer token

resolve_json_pointer splits a pointer with _json_pointer_tokens, unescapes ~1 and ~0, descends token by token, and raises KeyError on an absent token, which becomes an error row upstream. resolve_json_pointer walks a decoded document by pointer. It splits the pointer into tokens with _json_pointer_tokens, which requires a leading /, drops a leading #, and unescapes ~1 to / and ~0 to ~. It then descends token by token, indexing into lists by integer and into mappings by key, and raises KeyError when a token is absent. That KeyError is what turns a bad pointer into an error row upstream.

evaluate_provider branches on provider_type

evaluate_provider builds a base record then branches: json_pointer resolves a file pointer, glob_count counts and samples matches, and callable dispatches three git-backed names through _callable_value. evaluate_provider is the core. It takes one row and a root path and builds a base record with the row's id, title, tags, and provider fields, provisionally marked ok. Inside a try block it branches on provider_type. A json_pointer branch reads the named JSON file under the root and resolves the pointer. A glob_count branch globs the pattern under the root, drops any match whose relative path starts with a listed exclude prefix, keeps only files, sorts them, sets the value to the count, and stores the first twenty paths as sample_matches so a reader can see what was counted. A callable branch dispatches through _callable_value, which knows exactly three names: git_tracked_file_count and git_tracked_python_count shell through git ls-files, and tracked_fact_registry_count reads fact_registry.json under the root and counts its facts. Any other name raises. The resolved value is coerced by value_type and a string form is stored in value_repr.

The except block is the error-as-data path

The except block catches every exception, flips status to error, nulls the value, and on a missing source sets source_status to missing with a required_next_action, so nothing escapes. The except block is the error-as-data path. It catches every exception, flips provider_status and status to error, records error_class and a message, and nulls the value. When the failure is a missing source file, it sets source_status to missing and fills required_next_action from _source_repair_command. No exception escapes evaluate_provider.

evaluate_registry aggregates and hashes

evaluate_registry evaluates every row, counts by type and status, builds a degraded-or-ok ledger, collects error rows and a navigation cache, and hashes the content into receipt_sha256. evaluate_registry runs evaluate_provider over every row in the registry's facts list and aggregates. It counts rows by provider type and by status, builds the ledger whose status is degraded when any row errored and ok otherwise, collects the error rows into audit.provider_findings, projects a compact navigation_cache of id, title, value, and status per row, and hashes the summary, facts, and findings into receipt_sha256. That hash is over the evaluation content, so an unchanged registry against an unchanged root hashes the same.

evaluate_case and evaluate_fixture_dir replay tests

evaluate_case writes declared files into a temporary directory, optionally runs git init and git add, evaluates, and checks expectations, while evaluate_fixture_dir passes only when every case met its expectation. evaluate_case and evaluate_fixture_dir wrap the registry evaluator for replayable tests. A case writes its declared files into a fresh temporary directory, optionally runs git init and git add through _prepare_git_index so the callable providers have a real index to read, evaluates the registry there, then compares observed values and error ids against the case's expectations and reports expectation_met. evaluate_fixture_dir reads every *.json case in an input directory in sorted order, evaluates each, and reports pass only when every case met its expectation. build_parser and main expose two CLI commands, evaluate-registry and evaluate-fixtures, that print the record as JSON or a one-line status.

flowchart TD Row["fact row provider_type + fields"] Provider["evaluate_provider select branch"] Json["json_pointer read file, resolve pointer"] Glob["glob_count count files, keep 20 samples"] Call["callable git-backed count"] Ok["resolved row value + value_repr"] Err["error row error_class + required_next_action"] Reg["evaluate_registry ledger + audit + cache + sha256"] Row --> Provider Provider --> Json Provider --> Glob Provider --> Call Json --> Ok Glob --> Ok Call --> Ok Json -. on failure .-> Err Glob -. on failure .-> Err Call -. on failure .-> Err Ok --> Reg Err --> Reg

Negative cases

Public fixture set

The public fixture set in fixtures/first_wave/engine_room_derived_fact_provider_engine/input pins both the happy path and the failures. The public fixture set in fixtures/first_wave/engine_room_derived_fact_provider_engine/input pins both the happy path and the failures.

Two error-as-data cases and two passes

provider_error_as_data and unknown_provider_negative require bad rows to error into degraded data, while json_pointer_and_glob_count and git_callable_tracked_files resolve their rows to ok. The provider_error_as_data case declares two rows that must fail as data, not as a crash. demo.missing_source points into a JSON file that is not written, and demo.bad_callable names a callable that does not exist. The case expects status degraded and expects exactly demo.missing_source and demo.bad_callable to carry error rows. The unknown_provider_negative case declares one row, demo.unknown_provider, with provider_type set to imaginary_provider, and expects that single row to error while the ledger reports degraded. The two passing cases confirm the other side: json_pointer_and_glob_count resolves demo.fact_count and demo.markdown_count to ok, and git_callable_tracked_files resolves demo.tracked_files and demo.tracked_python against a real git index to ok.

Prior Art Grounding

Lineage in registered-provider data platforms

The design borrows data platforms' registered-provider and lineage-accounting shape, producing derived facts from declared sources carried with metadata rather than copied by hand. The pattern is the registered-provider and lineage-accounting shape from data platforms, where derived facts are produced from declared sources and carried with metadata rather than copied by hand.

• PostgreSQL materialized views, where a stored relation is derived from a query and refreshed from source data.
• OpenLineage, an open model for recording jobs, datasets, and run metadata across data systems.

Shape borrowed, lineage graph and verifier refused

This component borrows the shape and adds error-as-data rows with repair hints, adopting no full lineage graph and acting as no semantic claim verifier. This component borrows the shape and adds error-as-data rows with repair hints. It does not adopt a full lineage graph, and it is not a semantic claim verifier.

Validation Result record Path

PYTHONPATH=src ./repo-pytest tests/test_engine_room_derived_fact_provider_engine.py -q
cd microcosm-substrate && PYTHONPATH=src ../repo-python scripts/build_doctrine_projection.py --check-paper-module-corpus

What passing both commands proves

The first command replays the fixtures across pointer escaping, glob samples, git callables, and error rows, the second checks the page matches source, and passing both proves reproducibility. The first command replays the fixture cases and checks JSON pointer escaping, glob-count samples, git-backed callables, the error rows, and the CLI record. The second checks that this page still matches its source row. Passing both proves the fixture behavior and the projection are reproducible. It does not admit an component or include launch operations.

You can also run the CLI over the public fixtures directly:

PYTHONPATH=src python3 -m microcosm_core.engine_room.derived_fact_provider_engine evaluate-fixtures \
  --input fixtures/first_wave/engine_room_derived_fact_provider_engine/input \
  --json