docs(fr-044): plan 4, the Cube exporter (cube-model reference generator)

[dmealing]

Intent

Build the Cube exporter for FR-044 reporting (Plan 4 of the reporting work) so that 1.1.0 ships reporting to the bar its own design sets: "I don't want a half baked 1.1 and then have to do a 1.2 right away".
The design (spec R6 and section 7) asks for a cube-model reference helper, TypeScript first: it emits Cube model/cubes/*.yml, one cube per entity that declares dimensions or measures, with joins from to-one relationships, measures, dimensions (time dimensions with their granularities) and segments. It is a reference helper, not core: listed by meta gen --list, ejectable with meta eject, its output drift-checked by meta verify --codegen, and it carries no runtime. The mapping is lossless for the core vocabulary by construction: the spec's section 5 mapping table is a contract, each row backed by a golden fixture. Live check: a real Cube instance loads the exporter's output against the persistence-conformance Postgres database, and a measure query through Cube is compared to the report view's result for the same data; this runs in an integration lane, not the unit gate.
The dbt MetricFlow exporter is not part of this: it is built on first adopter demand (decision D5). Other ports' exporters only on adopter demand; the exported files are language-neutral.

What Changed

• Added comprehensive implementation plan for the cube-model reference helper generator, converting MetaObjects reporting vocabulary to Cube data model YAML files
• Plan defines 12 sequential tasks covering: SQL helper extraction, model building, YAML rendering, corpus fixtures, live integration validation against a real Cube instance, and documentation
• Includes 10 contract tables (A-J) specifying exact input-to-output mappings: cubes, joins, dimensions (with support for @via reaches), measures (count, sum, avg, min, max, ratios), segments, time grains, rollups per served report, and Cube views for @spine reports
• Live lane validates the exporter by loading its output into cubejs/cube:v1.7.43 against postgres:16-alpine and comparing Cube query results with report view SQL for six canonical reports (Table I)
• Covers error cases (unmappable field types, invalid names, collisions) and handling of relative-date filters (skips rollup generation since "now" is frozen at build time)
• Defers dbt MetricFlow exporter and other-language implementations to adopter demand; specifies Postgres + MySQL output with live check on Postgres only

Risk Assessment

✅ Low: Change adds only a planning document (no source, test, or config code); it is internally consistent, matches stated intent (TS-only reference helper, no runtime, D5 exclusion for MetricFlow, drift-checked, live lane separate), and introduces no executable behavior to review for bugs.

Testing

• ⏭️ Test - skipped

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

⏭️ **Test** - skipped

Step was skipped.

⏭️ **Document** - skipped

Step was skipped.

⏭️ **Lint** - skipped

Step was skipped.

✅ **Push** - passed

✅ No issues found.