proposal: a report may declare its own user-set parameters

[delchev]

Proposal document for #53. Adds proposals/0021-report-parameters.md; touches nothing under versions/.

The gap

A report is read for a period, for amounts above a threshold, for a counterparty whose name someone half-remembers. filter is fixed when the report is generated, and per-column filtering can only reach the columns the report already displays - so a period becomes one report per period, and the interesting filter (a field the report does not show) forces a column nobody wanted.

The balance report already escapes this by hardwiring its own From/To window, because its opening/period/closing shape cannot be specified without one. That is the argument the mechanism belongs to reports in general.

The shape

parameters:
  - { name: fromDate, target: date, op: ge }
  - { name: minTotal, target: total, op: ge, initial: "0" }
  - { name: customer, target: customer.name, op: like }

target uses the vocabulary a dimension already resolves (a field, or a one-hop relation.field that joins like a dimension does - which is what lets a report be filtered by a field it does not display).

What the normative half turns on

A parameter is bound on every read. Everything else follows: a predicate that vanishes while its input is empty makes the query shape depend on which inputs the reader touched, and a report like that is one no surface can present, cache or explain. So the unset case is carried by a value - initial - which makes it the value the untouched report shows, and it is required unless the comparison has a neutral default (a date bound; a like search).

Two consequences worth reading in the file, because each is a way for a report to be quietly wrong:

• an untouched parameter must not change which rows the report contains, including rows holding no value in the target column - a plain comparison drops those before the reader does anything;
• a timestamp target compares by date, or a le bound excludes the chosen day's own rows.

The ## Notes section records what is deliberately excluded and why: a relation-valued parameter (a picker over another entity's rows - a different construct), gt/lt/ne (no neutral form), and a translated label (one question for every generated caption).

The proposal carries Specification text, both anchors and the Appendix A row, so a release can fold it without reconstructing the discussion.

Reference implementation: eclipse-dirigible/dirigible#6911 (eclipse-dirigible/dirigible#6357). Site page: IntentFile/intentfile.github.io#41.

Left open for discussion.

🤖 Generated with Claude Code