Task: Model the run document and the analytic list
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
A report definition's run is configured by typed entities for its setup, its market bindings and its ordered analytic list, so the engine's run document is built from the database.
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
- report_run_setup carries the setup parameters as typed columns.
- report_analytic holds one row per analytic, keyed to a seeded lookup of the thirty-five analytic types.
- An analytic's parameters are held as values keyed to a parameter definition, so adding a parameter adds a lookup row and never a column on the report definition. The plan said a table per analytic type; the work changed that and the reason is in the notes.
- The superseded columns on risk_report_config are still there. Retiring them is not this task: they are the run configuration the report definition carries, and the story scopes their replacement with the report kind classification in Classify report kinds and bind each to a workflow, which is where the columns' consumers are decided.
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 |
|---|---|---|---|
| Analytic types a run can ask for | 35 in the corpus, seeded | psql -f projects/ores.sql/populate/reporting/reporting_analytic_types_populate.sql |
86dacf950d |
| Setup parameters in use | 40, of which asofDate, inputPath, outputPath and logFile appear in all 416 run documents | python3 census over external/ore/examples/ |
69f11695db |
| Run documents in the corpus | 416 | the same | 69f11695db |
| Analytics the corpus runs | 1874 rows across the 416 documents, in all 35 types, each carrying an active flag | python3 census over external/ore/examples/ |
9b8a773a50 |
| Run documents whose Setup block round trips | 416 of 416 | ores.ore.core.tests "[run_document]" |
17070aeae7 |
| Analytics that round trip | 1874 of 1874, across the same 416 documents | the same | 64a9838858 |
| Market bindings that round trip | 1915 of 1915, in 413 documents, across 8 roles | the same | c75073ec27 |
| Run document through the database | setup, analytics and market bindings written, read back and exported, agreeing with the original | ores.ore.core.tests "[database][roundtrip]" |
64f1377dcc |
| Analytic parameter definitions | 365, one per analytic type and parameter name, across all 35 types; domains 200 string, 118 boolean, 22 integer, 22 double, 3 date | applied in a scratch database, because the reporting tables are owned by postgres here | ce21236a38 |
| Analytic parameters through the database | each analytic's parameters written as values keyed to a definition, read back, resolved to names and compared with the document | ores.ore.core.tests "[database][roundtrip]", and the CI tests job, which recreates the database |
15078c2b55 |
6. Notes
- The plan said each analytic type would own a typed parameter table. The work
changed that, and the reason is on the record: thirty-five tables, one of them
around seventy columns wide, is not a shape to maintain, and the reporting
registry already solved this exact problem when it modelled a configuration's
parameters – a definition lookup, a value domain, and a row per value. The
run's analytics use that pattern too, so a parameter is added as a lookup row
and never as a column, which is the acceptance's own test. One table replaces
the plan's thirty-five. The decision is stated in
ores.reporting.report_analytic_parameter's model prose for review.
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. The run document is five parameter lists, and four of them are modelled: the setup block as forty-three typed columns, the ordered analytic list as a row per analytic keyed to a seeded lookup of the thirty-five types, the analytics' parameters as values keyed to a parameter definition, and the market bindings as a role and the configuration set it names. Logging and Restore are not modelled and no shipped document's round trip depends on them.
All four map both ways and round trip: the setup block and the analytic list over all four hundred and sixteen run documents, the market bindings over the four hundred and thirteen that carry them, and the whole document through PostgreSQL, with the parameters resolved back to names on the way out.
Three decisions the work settled:
- An analytic's parameters are rows keyed to a definition, not a table per analytic type. The plan said a table per type; thirty-five tables, one of them around seventy columns wide, is not a shape to maintain, and the reporting registry had already solved this exact problem the same way. Adding a parameter is a lookup row, which is the acceptance's own test, and the vocabulary is seeded from the corpus: three hundred and sixty-five definitions across the thirty-five types.
- The setup values are held as ORE spells them. The flags are not all booleans – the fixing and cashflow flags are Y or N, the model flags are true or false, and accrualDate may be the literal ASOF – so the mapping is a rename and not a conversion.
- The mapper refuses what it cannot represent: a setup parameter the entity has no column for, or a value the column cannot hold, is an error rather than a silent drop. A name that appears twice is read from its last occurrence, which three shipped documents need.
What is left is not this task's: risk_report_config still carries the run parameters it held before, and retiring them belongs with the classification of report kinds, where their consumers are decided.