Reports are durable read models

Declare the question beside the model

Report decorators describe dimensions, time buckets, and measures. The compiler produces a portable aggregate spec; the SDK query builder owns SQL generation.

@report({ source: Sale, refresh: 'incremental' })
class DailySalesReport extends SmrtReport {
  @timeBucket({ source: 'soldAt', unit: 'day' })
  day = new Date();

  @groupBy({ source: 'tenantId' })
  tenantId = '';

  @sum({ source: 'total' })
  revenue = 0.0;
}

Incremental refresh recomputes affected groups

A source watermark finds changed rows. s-m-r-t recomputes the groups those rows belong to and removes empty groups, avoiding the correctness traps of applying aggregate deltas blindly.

Operations are visible and recoverable

Runs, watermarks, locks, refresh tasks, and schedules are schema-managed system models. Cron and on-change refreshes use the existing jobs runtime rather than inventing a second queue.

• The reports.materialized recipe declares those bookkeeping tables. An application's own @report classes are not listed because they belong to the application.

Runtime reports are data, not code

A materialized report is stored rows, refreshed by jobs. A runtime report is the other trade. It is a declarative RuntimeReportSpec stored as a RuntimeReport row, compiled for the running principal on every run; result rows are never persisted. parseRuntimeReportSpec accepts a closed grammar with no SQL, expressions, joins, tables, or tenants. compileRuntimeReportSpec resolves it against a server-owned source allow-list, the field policy, the live permissions, and a fail-closed tenant predicate.

• The assistant tools for runtime reports, reports.runtime.*, live in smrt-chat; the materialized set is read through reports.query and reports.refresh from smrt-agents.
• A runtime report is saved only after a person confirms it.