@happyvertical/smrt-reports 0.42.6 → 0.42.7

package/AGENTS.md

@@ -13,6 +13,39 @@ Materialized aggregate report models for SMRT.
 | refresh | Rebuild and incremental refresh engine with run tracking, watermarks, locks, and tenant scoping |
 | state | Internal `_smrt_report_*` system models for runs, watermarks, locks, schedules, and refresh tasks |
 | scheduler | Cron schedule runner, durable refresh job enqueueing, and `onChange` interceptor registration |
+| adapter | Transport-neutral report descriptor, canonical materialized-row reads, and stable `id` row identity |
+| lifecycle | Tenant-safe freshness, run, lock, failure, and manual refresh preview/apply surfaces |
+
+## Adapter contract
+
+- `buildReportAdapterDescriptor()` returns deterministic, serializable metadata
+  for a report surface: a stable resource id, typed persisted report columns,
+  the canonical `DataQuerySchema`, and UI-neutral DataTable hints. It must not
+  import `smrt-ui` or expose a report-domain class to the consumer.
+- `queryReportMaterializedRows()` owns only the bounded read slice for rows that
+  are already materialized. It supports projection, offset/limit paging,
+  validated filters, deterministic multi-sort with an `id` tie-breaker, exact
+  totals, and dimension facets. At source-query compilation,
+  dimension and bucket filters compile to `WHERE`, aggregate-measure filters
+  compile to `HAVING`, and mixed `OR`/`NOT` filter scopes fail closed.
+- `id` is the only row identity. It must be a non-empty persisted string and is
+  never replaced by a display index or page position.
+- The descriptor is an exposure boundary. Sensitive/secret fields, fields with
+  `readPermission`, and transient, system, or non-column fields fail closed and
+  do not become public columns when no principal is available.
+- `tenantScoped`/`tenantField` reflect actual registered tenant metadata. A
+  `tenantScope` option only contributes to the stable resource id; it is not
+  authorization. The default query path resolves the registered collection via
+  `ObjectRegistry`, so normal collection tenancy interceptors apply. An injected
+  collection is application-owned and must preserve the same boundary.
+- `refresh` is a declaration, not execution. It describes configured mode,
+  triggers, positive-TTL stale-read behavior, and a permissioned/audited action
+  with preview/apply phases. The adapter remains read-only, while
+  `getReportLifecycle()` provides an explicit, tenant-safe lifecycle snapshot
+  and `previewReportRefresh()` / `applyReportRefresh()` delegate authorization,
+  audit, and queueing through an application action host. Only a registered
+  `SmrtReportCollection` may synchronously refresh stale reads, when its TTL is
+  positive and the report is not manual.
 
 ## Conventions
 

package/README.md

@@ -101,6 +101,126 @@ helpers:
 @happyvertical/smrt-reports/aggregate
 ```
 
+## Report adapter
+
+The package also exports a transport-neutral adapter for report surfaces:
+
+```ts
+import {
+  buildReportAdapterDescriptor,
+  buildReportDrilldownQuery,
+  queryReportMaterializedRows,
+  reportMaterializedRowKey,
+  splitReportFilterScopes,
+} from '@happyvertical/smrt-reports';
+
+const descriptor = await buildReportAdapterDescriptor(MonthlyRevenue, {
+  tenantScope: 'current',
+});
+const reports = await MonthlyRevenueCollection.create({ db: 'app.db' });
+const result = await queryReportMaterializedRows(
+  MonthlyRevenue,
+  {
+    version: 1,
+    requestId: 'monthly-revenue-first-page',
+    mode: 'rows',
+    projection: ['id', 'customer_id', 'revenue'],
+    filter: {
+      kind: 'all',
+      filters: [
+        {
+          kind: 'condition',
+          field: 'customer_id',
+          operator: 'eq',
+          value: 'customer-42',
+        },
+        {
+          kind: 'condition',
+          field: 'revenue',
+          operator: 'gte',
+          value: 1000,
+        },
+      ],
+    },
+    page: { kind: 'offset', offset: 0, limit: 25 },
+    sort: [{ field: 'revenue', direction: 'desc' }],
+  },
+  { collection: reports },
+);
+const rowKey = reportMaterializedRowKey(result.rows[0]);
+const drilldown = await buildReportDrilldownQuery(MonthlyRevenue, result.rows[0]);
+```
+
+`ReportAdapterDescriptor` is deterministic JSON with a stable resource id,
+`id` as the identity field, typed report columns, a canonical `DataQuerySchema`,
+and structural DataTable hints. The hints are deliberately not a `smrt-ui`
+dependency. Consumers may map the descriptor to their own presentation layer.
+The adapter exposes only persisted report columns and the primary key: transient,
+system, and non-column fields are not surfaced. Sensitive/secret fields and
+fields with a `readPermission` are excluded without a principal, so the
+descriptor fails closed.
+
+The `dataTable.columns` entries carry neutral `headerPath`, `valueFormat`,
+alignment, role, and responsive hints. Grouping fields, time buckets, and
+aggregate measures receive deterministic multi-level header ancestry; a
+consumer can override any column by stable id with
+`buildReportAdapterDescriptor(..., { dataTable: { columns: { ... } } })`.
+`valueFormat` is an instruction for the rendering boundary only: rows returned
+by `queryReportMaterializedRows()` retain their raw JSON-safe values for
+sorting, exports, and agents. Use `dataTable.structuralRows` for a computed
+summary, subtotal, aggregate, or footer. Each is marked `selection: 'excluded'`
+and `actions: 'excluded'`, and must be passed to the consumer table's structural
+row surface rather than its selectable data rows.
+
+`queryReportMaterializedRows()` is the bounded read slice for already-materialized
+rows. It supports projection, offset/limit paging (default limit 50),
+deterministic multi-sort (with `id` as the final tie-break), typed filters, and
+database-backed dimension facets. A descriptor marks group/time fields as
+`filterScope: 'where'` and aggregate measures as `filterScope: 'having'`; use
+`splitReportFilterScopes()` when constructing a live source query. An AND may
+combine the two scopes, but an OR or NOT cannot mix them, because moving either
+side across a source `WHERE`/`HAVING` boundary would change its meaning.
+
+The materialized collection executes the normalized, allowlisted predicate as
+parameterized SQL and applies it identically to rows, totals, and facets. It
+never accepts raw SQL, source field paths, tenant ids, or principal ids.
+The descriptor's `queryExecution` contract declares three delivery choices:
+`visible` (the default) returns rows for an already-authorized surface,
+`silent` returns the same bounded result while making no visible-surface change,
+and `background` delegates a normalized, authority-free task to the application's
+`enqueueBackgroundQuery` host. A background result is only a queue handle, never
+materialized rows. The host retains the authenticated principal, tenant, report
+definition, field policy, database, and eventual job execution; none can be
+supplied in a query request or background task.
+`buildReportDrilldownQuery()` carries only the row's declared groups/buckets
+and a fixed inheritance contract for the current principal, tenant, report
+definition, and field policy; an authenticated source adapter must enforce that
+contract before it reads source records. Time buckets remain declarative so the
+source adapter keeps the report's database/timezone semantics. Every returned
+row must have a non-empty string `id`; use that value, never a display or page
+index, for row identity.
+
+When no collection is injected, reads resolve the registered report collection
+through `ObjectRegistry`, allowing normal s-m-r-t collection interceptors to enforce
+tenant filtering. `tenantScoped` and `tenantField` in the descriptor are true
+only when the report is actually registered with tenant metadata; a scope string
+alone is not an authority boundary. An injected collection is application-owned
+and must provide the equivalent tenant boundary. Raw aggregate refreshes still
+need explicit tenant predicates as described above.
+
+The descriptor's `refresh` section declares mode, triggers, stale-read behavior,
+and a permissioned, audited `refresh` action with `preview` and `apply` phases.
+The adapter itself stays read-only. Call `getReportLifecycle()` for a tenant-safe
+snapshot of current, stale, refreshing, lock-skipped, or failed materialization
+state; it redacts lock owners, raw errors, and tenant-fanout identifiers. Pass a
+`lifecycle` option to `queryReportMaterializedRows()` only when a consumer needs
+that context; the result then distinguishes a current, stale, or read-triggered
+refresh. `previewReportRefresh()` and `applyReportRefresh()` require an
+application action host to authorize and audit the caller before a durable
+report-refresh job is queued. Only a registered `SmrtReportCollection` can
+synchronously refresh a stale read, and only when its TTL policy is positive and
+not manual.
+
 ## Development
 
 ```bash