Task: Round trip the ORE run document
Table of Contents
This page documents a task in the Model the ORE report configuration as entities story. It captures the goal, current status, acceptance, and any notes or results.
1. Goal
The run document is the one file the engine is handed, so it is the first file type whose whole path is proven: file to entities to file.
2. Status
| Field | Value |
|---|---|
| State | DONE |
| Parent story | Model the ORE report configuration as entities |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-09-27 |
3. Acceptance
- Every ore.xml in the vendored corpus imports without error, exports, and matches the original document.
- Setup parameters and analytic parameters are typed rows, not name and value pairs.
- The analytic list keeps its order and its types come from the seeded lookup.
4. Plan
(Implementation strategy. Written when work starts; key decisions
are distilled into the parent story's * Decisions at close, but the
plan itself stays — it is the historical record of what we did.)
5. Measurements
Every number this task claims about a tree, with the command that produced it
and the commit it was measured at. A number without both is not a measurement,
because a clean-up record describes a tree and trunk moves under a branch: a
consumer count, a gate's component count and a suite's size all change with no
code changing, and the reader of a bare number cannot tell which tree it came
from. Where the raw output matters, put it in an evidence/ file beside the
task and name that file in the Command column.
| What | Value | Command | Commit |
|---|---|---|---|
| Run documents in the corpus | 416 | compass test run -- -R ores.ore.core.tests |
e6f80a03bd |
| Setup parameters with no column | 0 | same, case ore_run_document_setup_round_trips_over_the_corpus |
e6f80a03bd |
| Analytic rows walked | 1874 | same, case ore_run_document_analytics_round_trip_over_the_corpus |
e6f80a03bd |
| Market bindings walked | 1915, across 413 documents | same, case ore_run_document_market_bindings_round_trip_over_the_corpus |
e6f80a03bd |
| Database round trip | passed | same, case run_document_roundtrips_through_the_database |
e6f80a03bd |
6. Notes
7. Test Scenarios
Manual QA scenarios (scaffolded via compass add test_scenario)
that verify this task. Link
new ones here as they're created; the scenario doc itself links back
via its "Verifies task" field.
| Scenario | State | Notes |
|---|---|---|
8. PRs
| PR | Title |
|---|---|
| #2383 | [reporting] Model the run document and the analytic list |
9. Review
| Comment summary | File | Decision | Notes |
|---|---|---|---|
10. Result
The acceptance is met, and was already met when this task was closed: the run document work landed some time ago and the state was simply stale. This task therefore records a proof that exists rather than a change it made.
Every ore.xml round trips. Three cases walk the same corpus and each asserts the population it walked rather than sampling it:
| Case | Files | Asserted |
|---|---|---|
ore_run_document_setup_round_trips_over_the_corpus |
416 | every Setup parameter survives, and none is dropped |
ore_run_document_analytics_round_trip_over_the_corpus |
416 | 1874 analytics, each keeping its display_order and its type |
ore_run_document_market_bindings_round_trip_over_the_corpus |
416 | 1915 bindings across 413 documents |
Each case counts what the export lost and then asserts the count. That is what
makes the first acceptance criterion more than a claim: a parameter the export
dropped would make exported.size() differ, and the test says so.
The parameters are typed rows. report_run_setup carries a column per Setup
parameter — base_currency, n_threads, log_mask and the rest — not a name
and a value pair. The walk counts the parameters that found no column and
asserts the count is zero, so a new parameter in the corpus fails the test
instead of being silently dropped. Analytic parameters are the other shape on
purpose: they are name and value rows against a seeded definition, because their
names are not known ahead of time.
Order and vocabulary. The analytics case asserts display_order = i + 1=,
so the ordered list is stored ordered, and it asserts each row's
analytic_type_code. A separate case asserts the seed carries a row for every
type the corpus needs, so the type is a lookup rather than free text.
Through the database. run_document_roundtrips_through_the_database writes
the setup, the analytics and the bindings to PostgreSQL and reads them back
before rebuilding the document, so this kind is proven through the store and not
only in memory.
What is not claimed. The corpus walk is in memory; only one document goes through the database. The in-memory walk proves the mapper over all 416 files, and the database case proves the tables hold what the mapper produces, which is the same split and the same limitation as every other kind in this story.