@happyvertical/smrt-reports 0.43.0 → 0.43.1

package/dist/manifest.json

@@ -2,7 +2,7 @@
   "version": "1.0.0",
   "timestamp": 0,
   "packageName": "@happyvertical/smrt-reports",
-  "packageVersion": "0.43.0",
+  "packageVersion": "0.43.1",
   "objects": {
     "@happyvertical/smrt-reports:SmrtReport": {
       "name": "smrtreport",

package/dist/smrt-knowledge.json

@@ -3,13 +3,13 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-reports",
-  "packageVersion": "0.43.0",
+  "packageVersion": "0.43.1",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "7d0a0905d3c403de0f7424e986070d505a049e77634426b03c0d76aada3ea8ef",
-    "packageJson": "fdbb5324c7ab556fc2943c81a96c5e43a47762284936804252e3bf0bf5ea217d",
-    "agents": "3c4350e771c33aa34107f6b27ad9c8d1a90f11f290f839a07e7bb3fad7b6ae01"
+    "manifest": "bf489768d3e011d1fdb916175b797d36fa709797b82e694a936c13c7c4a5f96b",
+    "packageJson": "3fc955fbbf6f89014159ef591ba501aac71fe8957e3615e3d8c8c3db878f1d98",
+    "agents": "e288d9c64353e34d26174ed1dbfd653ac0391afdc4f8ce1df43b3d38798589e6"
   },
   "exports": [
     ".",
@@ -814,5 +814,5 @@
     "polymorphicAssociations": 0,
     "uuidColumns": 14
   },
-  "agentDoc": "# @happyvertical/smrt-reports\n\nMaterialized aggregate report models for SMRT.\n\n## Key Pieces\n\n| Module | Purpose |\n| --- | --- |\n| `SmrtReport` | Abstract report row base with `refreshedAt`, `isStale()`, and manual `refresh()` |\n| decorators | `@report`, grouping decorators, time buckets, and aggregate measure decorators |\n| compiler | Pure `ReportDefinition -> AggregateSpec` compiler and ObjectRegistry adapter |\n| aggregate | Compatibility re-export of the SDK aggregate query builder |\n| refresh | Rebuild and incremental refresh engine with run tracking, watermarks, locks, and tenant scoping |\n| state | Internal `_smrt_report_*` system models for runs, watermarks, locks, schedules, and refresh tasks |\n| scheduler | Cron schedule runner, durable refresh job enqueueing, and `onChange` interceptor registration |\n| adapter | Transport-neutral report descriptor, canonical materialized-row reads, and stable `id` row identity |\n| lifecycle | Tenant-safe freshness, run, lock, failure, and manual refresh preview/apply surfaces |\n\n## Adapter contract\n\n- `buildReportAdapterDescriptor()` returns deterministic, serializable metadata\n  for a report surface: a stable resource id, typed persisted report columns,\n  the canonical `DataQuerySchema`, and UI-neutral DataTable hints. It must not\n  import `smrt-ui` or expose a report-domain class to the consumer.\n- `queryReportMaterializedRows()` owns only the bounded read slice for rows that\n  are already materialized. It supports projection, offset/limit paging,\n  validated filters, deterministic multi-sort with an `id` tie-breaker, exact\n  totals, and dimension facets. At source-query compilation,\n  dimension and bucket filters compile to `WHERE`, aggregate-measure filters\n  compile to `HAVING`, and mixed `OR`/`NOT` filter scopes fail closed.\n- `id` is the only row identity. It must be a non-empty persisted string and is\n  never replaced by a display index or page position.\n- The descriptor is an exposure boundary. Sensitive/secret fields, fields with\n  `readPermission`, and transient, system, or non-column fields fail closed and\n  do not become public columns when no principal is available.\n- `tenantScoped`/`tenantField` reflect actual registered tenant metadata. A\n  `tenantScope` option only contributes to the stable resource id; it is not\n  authorization. The default query path resolves the registered collection via\n  `ObjectRegistry`, so normal collection tenancy interceptors apply. An injected\n  collection is application-owned and must preserve the same boundary.\n- `refresh` is a declaration, not execution. It describes configured mode,\n  triggers, positive-TTL stale-read behavior, and a permissioned/audited action\n  with preview/apply phases. The adapter remains read-only, while\n  `getReportLifecycle()` provides an explicit, tenant-safe lifecycle snapshot\n  and `previewReportRefresh()` / `applyReportRefresh()` delegate authorization,\n  audit, and queueing through an application action host. Only a registered\n  `SmrtReportCollection` may synchronously refresh stale reads, when its TTL is\n  positive and the report is not manual.\n\n## Conventions\n\n- Report cache tables are normal `@smrt()` tables. Runtime refresh must not create schema.\n- Store report metadata under field `_meta.__report`; scanner and runtime decorators must stay aligned.\n- Keep SQL generation portable. Use the SDK `buildAggregate()`/`bucketExpr()` helpers for time buckets and `$N` placeholders.\n- Do not add a local aggregate SQL builder here; the implementation lives in `@happyvertical/sql`.\n- Refresh runtime tables are schema-managed. Runtime refresh must fail clearly when `_smrt_report_runs`, `_smrt_report_watermarks`, or `_smrt_report_locks` have not been migrated.\n- Incremental refresh requires a source watermark column (default `updatedAt`) and soft-delete column (default `deletedAt`); it recomputes affected groups and deletes empty report groups instead of applying aggregate deltas.\n- Raw aggregate refreshes must explicitly filter `tenant_id`; the tenancy interceptor only protects normal collection reads.\n- Scheduled/on-change refreshes enqueue `SmrtReportRefreshTask.run()` through `@happyvertical/smrt-jobs`; do not add a separate report queue.\n"
+  "agentDoc": "# @happyvertical/smrt-reports\n\nMaterialized aggregate report models for SMRT.\n\n## Key Pieces\n\n| Module | Purpose |\n| --- | --- |\n| `SmrtReport` | Abstract report row base with `refreshedAt`, `isStale()`, and manual `refresh()` |\n| decorators | `@report`, grouping decorators, time buckets, and aggregate measure decorators |\n| compiler | Pure `ReportDefinition -> AggregateSpec` compiler and ObjectRegistry adapter |\n| aggregate | Compatibility re-export of the SDK aggregate query builder |\n| refresh | Rebuild and incremental refresh engine with run tracking, watermarks, locks, and tenant scoping |\n| state | Internal `_smrt_report_*` system models for runs, watermarks, locks, schedules, and refresh tasks |\n| scheduler | Cron schedule runner, durable refresh job enqueueing, and `onChange` interceptor registration |\n| adapter | Transport-neutral report descriptor, canonical materialized-row reads, and stable `id` row identity |\n| lifecycle | Tenant-safe freshness, run, lock, failure, and manual refresh preview/apply surfaces |\n| views | Policy-revalidated saved views, snapshot-bound exports, bounded job handoff, and artifact metadata validation |\n\n## Adapter contract\n\n- `buildReportAdapterDescriptor()` returns deterministic, serializable metadata\n  for a report surface: a stable resource id, typed persisted report columns,\n  the canonical `DataQuerySchema`, and UI-neutral DataTable hints. It must not\n  import `smrt-ui` or expose a report-domain class to the consumer.\n- `queryReportMaterializedRows()` owns only the bounded read slice for rows that\n  are already materialized. It supports projection, offset/limit paging,\n  validated filters, deterministic multi-sort with an `id` tie-breaker, exact\n  totals, and dimension facets. At source-query compilation,\n  dimension and bucket filters compile to `WHERE`, aggregate-measure filters\n  compile to `HAVING`, and mixed `OR`/`NOT` filter scopes fail closed.\n- `id` is the only row identity. It must be a non-empty persisted string and is\n  never replaced by a display index or page position.\n- The descriptor is an exposure boundary. Sensitive/secret fields, fields with\n  `readPermission`, and transient, system, or non-column fields fail closed and\n  do not become public columns when no principal is available.\n- `tenantScoped`/`tenantField` reflect actual registered tenant metadata. A\n  `tenantScope` option only contributes to the stable resource id; it is not\n  authorization. The default query path resolves the registered collection via\n  `ObjectRegistry`, so normal collection tenancy interceptors apply. An injected\n  collection is application-owned and must preserve the same boundary.\n- `refresh` is a declaration, not execution. It describes configured mode,\n  triggers, positive-TTL stale-read behavior, and a permissioned/audited action\n  with preview/apply phases. The adapter remains read-only, while\n  `getReportLifecycle()` provides an explicit, tenant-safe lifecycle snapshot\n  and `previewReportRefresh()` / `applyReportRefresh()` delegate authorization,\n  audit, and queueing through an application action host. Only a registered\n  `SmrtReportCollection` may synchronously refresh stale reads, when its TTL is\n  positive and the report is not manual.\n- `views` accepts no authority. Persisted views must be normalized again through\n  the current descriptor before restoring them, so changed column policy or a\n  changed report definition fails closed. Treat unversioned persisted layouts as\n  legacy v0 and migrate them to v1 before normalization; unknown versions must\n  fail rather than being inferred. Export snapshots retain the canonical\n  query fingerprint, projection, sort, as-of/freshness state, exact row count,\n  and the fixed principal/tenant/report-definition/field-policy inheritance\n  contract. A snapshot needs an application-host-issued opaque binding and an\n  explicit offset-page read plan: workers advance it from offset zero instead\n  of reusing a visible page. Preview, apply, worker, and artifact-serving\n  boundaries must call the validators, including the host's immutable-snapshot\n  assertion; application hosts own authorization, audit records, durable\n  storage, download tokens, and queue execution.\n\n## Conventions\n\n- Report cache tables are normal `@smrt()` tables. Runtime refresh must not create schema.\n- Store report metadata under field `_meta.__report`; scanner and runtime decorators must stay aligned.\n- Keep SQL generation portable. Use the SDK `buildAggregate()`/`bucketExpr()` helpers for time buckets and `$N` placeholders.\n- Do not add a local aggregate SQL builder here; the implementation lives in `@happyvertical/sql`.\n- Refresh runtime tables are schema-managed. Runtime refresh must fail clearly when `_smrt_report_runs`, `_smrt_report_watermarks`, or `_smrt_report_locks` have not been migrated.\n- Incremental refresh requires a source watermark column (default `updatedAt`) and soft-delete column (default `deletedAt`); it recomputes affected groups and deletes empty report groups instead of applying aggregate deltas.\n- Raw aggregate refreshes must explicitly filter `tenant_id`; the tenancy interceptor only protects normal collection reads.\n- Scheduled/on-change refreshes enqueue `SmrtReportRefreshTask.run()` through `@happyvertical/smrt-jobs`; do not add a separate report queue.\n"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-reports",
-  "version": "0.43.0",
+  "version": "0.43.1",
   "description": "Materialized aggregate report models for SMRT",
   "type": "module",
   "main": "./dist/index.js",
@@ -44,17 +44,17 @@
   },
   "dependencies": {
     "@happyvertical/sql": "^0.88.0",
-    "@happyvertical/smrt-core": "0.43.0",
-    "@happyvertical/smrt-types": "0.43.0",
-    "@happyvertical/smrt-jobs": "0.43.0",
-    "@happyvertical/smrt-tenancy": "0.43.0"
+    "@happyvertical/smrt-core": "0.43.1",
+    "@happyvertical/smrt-jobs": "0.43.1",
+    "@happyvertical/smrt-types": "0.43.1",
+    "@happyvertical/smrt-tenancy": "0.43.1"
   },
   "devDependencies": {
     "@types/node": "24.13.2",
     "typescript": "5.9.3",
     "vite": "8.1.4",
     "vitest": "4.1.10",
-    "@happyvertical/smrt-vitest": "0.43.0"
+    "@happyvertical/smrt-vitest": "0.43.1"
   },
   "keywords": [
     "ai",