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.

Emacs 29.3 (Org mode 9.6.15)