@happyvertical/smrt-reports 0.55.7 → 0.55.9

package/AGENTS.md

@@ -16,6 +16,7 @@ Materialized aggregate report models for SMRT.
 | 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 |
 | views | Policy-revalidated saved views, snapshot-bound exports, bounded job handoff, and artifact metadata validation |
+| runtime reports | Declarative `RuntimeReportSpec` stored as data (`RuntimeReport`), compiled per principal with field-policy, RBAC and tenant checks; see [agents/runtime-reports.md](agents/runtime-reports.md) |
 
 ## Adapter contract
 
@@ -64,6 +65,39 @@ Materialized aggregate report models for SMRT.
   assertion; application hosts own authorization, audit records, durable
   storage, download tokens, and queue execution.
 
+## Runtime reports (#3711)
+
+A runtime report is data, not code: `parseRuntimeReportSpec()` accepts a closed
+grammar (no SQL, expressions, joins, tables, or tenants), and
+`compileRuntimeReportSpec()` resolves it against a server-owned source
+allow-list, the ObjectRegistry field policy, the live principal's permissions,
+and an explicit fail-closed tenant predicate. Stored `RuntimeReport` specs are
+re-compiled for the running principal on every run, and result rows are never
+persisted. Assistant tools are in `@happyvertical/smrt-chat`. The full
+contract, authority model, and deferred work are in
+[agents/runtime-reports.md](agents/runtime-reports.md).
+
+## Recipes (#3719)
+
+`src/recipes.ts` declares `reports.materialized` (`MaterializedReportsRecipe`),
+emitted into the built `manifest.json` and `smrt-knowledge.json` `recipes`. It
+brings only the internal refresh bookkeeping tables (runs, watermarks, locks,
+schedules, refresh tasks); an app's own `@report` classes are not listed because
+they belong to the app. Those tables have no REST or MCP surface, so the recipe
+has no `nav`. It declares `runtime: 'server'` (SQL aggregation, jobs) and no
+`surfaces`: this package ships no Svelte components, and declaring one that does
+not exist is a scan-time lie. Do not add a surface until a real export exists.
+
+User-facing help is `src/materialized.recipe.md` (#3591). It explains how the
+assistant reads declared reports (`data.discover`/`data.inspect` and
+`reports.query`/`reports.refresh` from `@happyvertical/smrt-agents`) and how
+runtime reports (`reports.runtime.*` in `@happyvertical/smrt-chat`) differ: live,
+never stored, saved only after a person confirms. Keep that split accurate when
+either tool set changes. `{field:...}` references need a `@field({ description })`
+on `state.ts` so the glossary can explain them. `src/__tests__/recipes.test.ts`
+runs the real scan, manifest and generation passes in memory and renders the help.
+See [core recipes](../core/agents/recipes.md).
+
 ## Conventions
 
 - Report cache tables are normal `@smrt()` tables. Runtime refresh must not create schema.

package/README.md

@@ -276,6 +276,22 @@ download token; before serving it, call `validateReportExportArtifact()` to
 reject expiry, definition drift, and out-of-bounds progress, then apply the
 host's current authorization and snapshot validation again.
 
+## Runtime reports
+
+A report can also be defined at runtime as data. `RuntimeReportSpec` is a closed,
+versioned structure (source id, dimensions, measures, filters, having, sort,
+chart hint) with no free-form query text. `compileRuntimeReportSpec()` checks it
+against a server-owned source allow-list, field policy (sensitive and
+permission-gated fields are not nameable), the caller's permissions, and tenant
+isolation, then targets the same aggregate plan as declared reports.
+`RuntimeReport` stores validated specs per tenant, and a stored spec is
+re-compiled for the running user on every run. Result rows are not stored. A row
+can only be inserted, or have its spec changed, through `saveRuntimeReport()`
+with the spec hash a human confirmed; the model layer refuses every other write. The
+chat package offers matching assistant tools that propose a spec, preview it,
+and save only after a human confirms. See
+[`agents/runtime-reports.md`](./agents/runtime-reports.md).
+
 ## Development
 
 ```bash

package/dist/index.d.ts

@@ -5,8 +5,15 @@ export { buildReportDefinition, compileReportDefinition, compileReportSpec, getR
 export { aggregate, avg, count, day, getRuntimeReportOptions, groupBy, hour, max, min, minute, month, quarter, report, sum, week, year, } from './decorators.js';
 export type { AppliedReportRefresh, ApplyReportRefreshOptions, PreviewReportRefreshOptions, ReportLifecycleOptions, ReportLifecycleRun, ReportLifecycleSnapshot, ReportLifecycleState, ReportRefreshActionContext, ReportRefreshActionHost, ReportRefreshJobHandle, ReportRefreshOutcome, ReportRefreshPreview, } from './lifecycle.js';
 export { applyReportRefresh, getReportLifecycle, previewReportRefresh, reportRefreshOutcome, } from './lifecycle.js';
+export { MaterializedReportsRecipe } from './recipes.js';
 export { refreshReport, reportRowIdentity, } from './refresh.js';
 export { SmrtReport, SmrtReportCollection } from './report.js';
+export type { CompiledRuntimeReport, RunRuntimeReportOptions, RuntimeReportColumn, RuntimeReportColumnType, RuntimeReportCompileContext, RuntimeReportResult, RuntimeReportSourceDefinition, RuntimeReportSourceDescription, } from './runtime-compiler.js';
+export { compileRuntimeReportSpec, describeRuntimeReportSource, runRuntimeReport, } from './runtime-compiler.js';
+export type { RuntimeReportStatus, RuntimeReportStoreOptions, SaveRuntimeReportOptions, } from './runtime-report.js';
+export { archiveRuntimeReport, getRuntimeReport, listRuntimeReports, RuntimeReport, RuntimeReportCollection, runStoredRuntimeReport, saveRuntimeReport, } from './runtime-report.js';
+export type { RuntimeReportBucket, RuntimeReportChart, RuntimeReportChartType, RuntimeReportDimension, RuntimeReportErrorCode, RuntimeReportFilter, RuntimeReportFilterOp, RuntimeReportHaving, RuntimeReportHavingOp, RuntimeReportMeasure, RuntimeReportMeasureFn, RuntimeReportScalar, RuntimeReportSort, RuntimeReportSpec, } from './runtime-spec.js';
+export { parseRuntimeReportSpec, RUNTIME_REPORT_BUCKETS, RUNTIME_REPORT_CHART_TYPES, RUNTIME_REPORT_FILTER_OPS, RUNTIME_REPORT_HAVING_OPS, RUNTIME_REPORT_LIMITS, RUNTIME_REPORT_MEASURE_FNS, RUNTIME_REPORT_SPEC_VERSION, RuntimeReportError, runtimeReportSpecHash, serializeRuntimeReportSpec, } from './runtime-spec.js';
 export type { EnqueueReportRefreshOptions, EnsureReportSchedulesOptions, ReportExecutionPrincipalReference, ReportRefreshExecutionAuditEvent, ReportRefreshExecutionAuthority, ReportRefreshExecutionAuthorityContext, ReportRefreshExecutionAuthorityHost, ReportRefreshInterceptorOptions, ReportRefreshJobArgs, ReportScheduleInfo, ReportScheduleRunnerConfig, ReportScheduleRunnerEvents, } from './scheduler.js';
 export { enqueueReportRefresh, ensureReportRefreshSchedules, ReportScheduleRunner, registerReportRefreshExecutionAuthorityHost, registerReportRefreshInterceptor, registerReportRefreshJobIntegritySigner, SmrtPrincipalReportRefreshTask, SmrtReportRefreshTask, } from './scheduler.js';
 export { assertReportTablesReady, REPORT_LOCKS_TABLE, REPORT_REFRESH_TASKS_TABLE, REPORT_RUNS_TABLE, REPORT_RUNTIME_TABLES, REPORT_SCHEDULER_TABLES, REPORT_SCHEDULES_TABLE, REPORT_WATERMARKS_TABLE, SmrtReportLock, SmrtReportLockCollection, SmrtReportRun, SmrtReportRunCollection, SmrtReportSchedule, SmrtReportScheduleCollection, SmrtReportWatermark, SmrtReportWatermarkCollection, scopeKeyForTenant, } from './state.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}