Engine Room Demo

Engine room is

The Engine Room is fourteen public capabilities staged as components, and engine_room_demo is the one that checks all of them together. The Engine Room is fourteen separate capabilities staged as public components: four Lean proof-search targets, a metabolism runtime with its reconciler, command singleflight, a generated-projection drift gate, a derived-fact engine, a public-projection leak gate, an egress self-compliance gate, a navigation-fitness benchmark, a bridge-campaign DAG, and a knowledge router over the reference library. engine_room_demo is the component that checks all of them together.

Asks whether ten

It asks whether the ten staged bundles cover the fourteen requested targets, each still owns its files, and each fixture still runs, not whether any bundle is finished. It answers one question. Do the ten staged bundles cover the fourteen targets the controller asked for, does each bundle still own its full set of files, and does each fixture still run? A pass means the set is complete and every fixture executed. It does not mean that any single bundle is finished or correct.

Reads fixtures runs

It reads fixtures, runs the shared audit, and writes four metadata-only records, reading the shared registry and generated atlas but never writing to them. The component reads fixtures, runs the shared audit, and writes four metadata-only result records: a result, a board, a validation record, and an optional fixture sign-off record. It reads the shared component registry and the generated atlas but never writes to them.

Purpose

A stored list would drift and mislead

Without this component a reader trusts fourteen claims one at a time, and a stored list of target names would go stale the moment the bundle set changed and start agreeing with a wrong answer. Without this component a reader has to trust fourteen claims one at a time and hope the set is complete. A loose check would compare the covered targets against a stored list of the fourteen names. That list goes stale the moment the bundle set changes, and a stale list can start agreeing with a wrong answer.

Coverage recomputed from EXPECTED_JEWEL_TARGETS

engine_room_demo keeps no stored list: the fourteen names live in the frozen EXPECTED_JEWEL_TARGETS, and coverage is recomputed from the bundles every run, so nothing drifts out of sync. engine_room_demo keeps no stored list. The fourteen expected names live in one frozen constant, EXPECTED_JEWEL_TARGETS, and the covered set is recomputed from the bundles on every run. Coverage is the union of what the bundles declare, checked against that constant. There is nothing to drift out of sync.

Six files per bundle mark ownership

A bundle owns its surface only when six files exist for it, module source, fixture input, manifest, paper module, standard, and test, and the audit names any that are missing. A bundle counts as owning its surface only when six files exist for it: module source, fixture input directory, fixture manifest, paper module, standard, and test. The audit checks all six per bundle and names any that are missing.

How it works

Wrapper is src

The wrapper is src/microcosm_core/organs/engine_room_demo.py. The staged runner it calls is src/microcosm_core/engine_room/demo.py. Execution runs in this order.

build_result folds cases into one status

build_result loads every JSON case, runs _evaluate_case on each, and passes only with at least one positive case, all positives passing, and every negative observed to fail. build_result is the entry point. It calls _fixture_cases to load every JSON case under the input path, runs _evaluate_case on each one, then folds the rows into a status. The run passes only when there is at least one positive case, every positive case passed, and every negative case was observed to fail.

_evaluate_case routes by case_type

_evaluate_case sends a positive case to audit_controller_coverage, a negative case to _target_override_case, and any other type to a fail row coded ENGINE_ROOM_UNKNOWN_CASE_TYPE. _evaluate_case dispatches on case_type. A positive case calls audit_controller_coverage. A negative case calls _target_override_case. Any other type returns a fail row with the code ENGINE_ROOM_UNKNOWN_CASE_TYPE.

audit_controller_coverage unions targets both ways

audit_controller_coverage runs the six-file check per bundle, unions declared targets, subtracts EXPECTED_JEWEL_TARGETS both ways for missing and unexpected, and reads shared surfaces for visibility only. audit_controller_coverage is the audit. It walks the ten entries in CAPSULES, builds a _capsule_surface_row for each (the six-file check), and unions their declared targets. It subtracts EXPECTED_JEWEL_TARGETS both ways to find missing and unexpected targets. When asked, it calls run_demo to execute the fixtures. It reads the shared registry, the accepted-component list, and the atlas through _shared_surface_ids for visibility only, and always returns shared_registry_mutated: false. The staged pass needs no missing targets, no unexpected targets, no bundle missing a file, and a passing fixture run.

run_demo calls each bundle's evaluator

run_demo is the execution spine: for each bundle it imports the module and calls evaluate_fixture_dir or validate_fixture_dir, passing only when every selected fixture ran and passed. run_demo is the execution spine. For each bundle it calls run_capsule, which imports the bundle module and calls its declared evaluator, either evaluate_fixture_dir or validate_fixture_dir. It records a compact per-bundle status and the covered target list. A pass here means every selected bundle fixture ran and passed.

run writes four metadata-only records

The wrapper's run writes four records through write_json_atomic, a result, a board, a validation result record, and an optional sign-off record, each carrying body_in_receipt: false. The wrapper's run writes the four records with write_json_atomic: engine_room_demo_result.json, engine_room_demo_board.json, engine_room_demo_validation_receipt.json, and, when an sign-off path is given, engine_room_demo_fixture_acceptance.json. Every record carries body_in_receipt: false.

flowchart TD A["fixture cases"] --> B["build_result"] B --> C["_evaluate_case"] C --> D["positive: audit_controller_coverage"] C --> E["negative: _target_override_case"] D --> F["_capsule_surface_row x10 bundles"] D --> G["run_demo --> run_capsule"] D --> H["shared surfaces read-only"] B --> I["run writes 4 metadata-only records"]

Negative cases

The negative case must be observed to fail

One positive and one negative fixture run, and _target_override_case recomputes coverage live so the missing-target negative fails, since a silently passing negative would fail the whole run. The fixture set names one positive case, positive_controller_audit.json, and one negative case, missing_expected_target_negative.json. The negative case names an expected target that is not in the covered set. _target_override_case recomputes the covered targets live, finds the named target missing, and returns a fail row with the code ENGINE_ROOM_EXPECTED_TARGET_MISSING. The run passes only when that negative case is observed to fail, so a negative case that silently passed would fail the whole run. There is no frozen answer key for the negative check to drift toward.

Prior Art Grounding

Lineage in integration testing and CI composition

This is ordinary integration-testing and CI-composition practice, anchored by integration testing, pytest fixtures, and staged status checks, without turning fixture evidence into a launch claim. This is ordinary integration-testing and CI-composition practice: several component checks are assembled into one demo path, negative fixtures prove refusal behaviour, and the records summarise what ran without turning fixture evidence into a launch claim. Reasonable public anchors are IBM's integration testing overview, which frames the question as whether composed modules interact as intended, pytest fixtures as a common shape for reusable synthetic inputs, and GitHub Actions as a widely used surface for composing staged checks with explicit status.

Validation Result record Path

Run component and

What a pass proves here

A pass means the fixtures ran, the ten bundles covered the fourteen targets with no file missing, the negative failed, and this Markdown matches its generated structured source record. A pass means the fixtures ran, the ten bundles covered the fourteen expected targets with no file missing, the negative case was observed to fail, and this Markdown still matches its generated structured source record. It is not evidence of anything past that.