docs(fr-044): Plan 2 — report view lowering, relative dates, persistence reads in five ports

[dmealing]

What this is

The implementation plan that follows Plan 1 (reporting vocabulary and loader validation, #397, metamodel 1.1). One document, no code:

docs/superpowers/plans/2026-10-03-fr-044-plan-2-report-view-lowering.md

Plan 2 covers:

• TypeScript view lowering for object.report and for relative-date filter values, on Postgres, SQLite/D1 and MySQL;
• reading every fixture report through each port's persistence layer (TypeScript, C#, Java, Kotlin, Python);
• the reporting section of the metaobjects-authoring skill.

How to read it

• Contract tables (A to H): which reports lower, a report's derived fields, measure lowering per dialect, time-grain truncation, relative-date expressions, the view layout, the expected SQL for six canonical reports, and the fixture list. Table B is what all five ports implement; the SQL tables are TypeScript only.
• Tasks 1 to 16, with a dependency table saying which can run in parallel. Tasks 1 to 10 are the TypeScript critical path; C#, Java, Python and the skill fan out from Task 10, and Kotlin follows Java.
• No-churn and back-compat proof, as a table of claim and evidence.
• Unverified items and Open questions at the end.

How it was verified

Plan 1 was written from greps and several of its names were wrong. For this plan:

• Every cited path, function, test file and helper was read in the tree at the Plan 1 merge. A table near the top lists the Plan 1 names that differ from what landed.
• Every SQL expression in the dialect tables was run on Postgres 16.15, SQLite 3.37.2 and MySQL 8.4 (default ONLY_FULL_GROUP_BY) and returned the values shown.
• What could not be confirmed is marked UNVERIFIED in place and collected in one table, with the task whose first step is to confirm it.

Two things the read turned up that shaped the plan:

• MySQL is a code generation and runtime dialect only. meta migrate --dialect mysql is refused and the view emitter has no MySQL arm, so "lowering on MySQL" has no existing delivery path. The plan ships the SQL through a library function and the MySQL recipe (open question 2).
• A report declares no fields, and every port's runtime and generators read an object's field children. So a derived-field accessor is needed in all five ports before any port can read a report view. The plan gates it with one TypeScript-produced artifact.

Open questions for the maintainer

Seven, listed at the end of the plan. The two that change the plan's shape:

1. Does a report lower only when it declares a view source (what the plan assumes), or does every report lower with a derived default name?
2. Is MySQL SQL through a library function and the recipe enough, or is a command wanted?

The others confirm defaults: UTC bucketing, the existing join-type rule applied to report dimensions, C# and Kotlin generating a report's typed row in this plan, the docs surface, and the numeric contract.

Not in this PR

No implementation code, no fixtures, no skill edits. Plans 3 to 5 are out of scope.