@happyvertical/smrt-reports 0.43.0 → 0.43.2

package/AGENTS.md

@@ -15,6 +15,7 @@ Materialized aggregate report models for SMRT.
 | 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 |
+| views | Policy-revalidated saved views, snapshot-bound exports, bounded job handoff, and artifact metadata validation |
 
 ## Adapter contract
 
@@ -46,6 +47,19 @@ Materialized aggregate report models for SMRT.
   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.
+- `views` accepts no authority. Persisted views must be normalized again through
+  the current descriptor before restoring them, so changed column policy or a
+  changed report definition fails closed. Treat unversioned persisted layouts as
+  legacy v0 and migrate them to v1 before normalization; unknown versions must
+  fail rather than being inferred. Export snapshots retain the canonical
+  query fingerprint, projection, sort, as-of/freshness state, exact row count,
+  and the fixed principal/tenant/report-definition/field-policy inheritance
+  contract. A snapshot needs an application-host-issued opaque binding and an
+  explicit offset-page read plan: workers advance it from offset zero instead
+  of reusing a visible page. Preview, apply, worker, and artifact-serving
+  boundaries must call the validators, including the host's immutable-snapshot
+  assertion; application hosts own authorization, audit records, durable
+  storage, download tokens, and queue execution.
 
 ## Conventions
 

package/README.md

@@ -221,6 +221,44 @@ 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.
 
+### Saved views and snapshot exports
+
+`normalizeReportSavedView()` and `restoreReportSavedView()` provide the
+serializable view boundary. A storage host owns the saved view's tenant and
+owner; on every restore it must pass the stored payload through the current
+descriptor. That reapplies field, projection, sorting, grouping, and definition
+policy, so a stale view cannot reveal a field that is no longer allowed.
+`migrateReportSavedView()` upgrades the original unversioned (or explicit v0)
+layout to v1 before that current-policy validation; unsupported future versions
+fail clearly rather than being guessed.
+
+Build an export from a completed materialized-row read with
+`createReportExportSnapshot()`, supplying an opaque binding from the
+application's immutable materialization-snapshot host, then call
+`createReportExportRequest()`. The snapshot fixes the canonical query
+fingerprint, normalized projection and sort, exact row count, `asOf`,
+`refreshedAt`, stale state, and definition fingerprint. Every request also
+contains a deterministic offset-page read plan; a renderer begins at offset zero
+and advances by its validated page size until the exact bounded row count is
+reached. Use `createReportExportPageRequest()` for each page; it preserves the
+frozen query semantics while replacing only visible pagination.
+
+Every request is bounded by rows, bytes, and deadline; exports over the
+foreground row limit become an authority-free background handoff. Use
+`previewReportExport()` and `applyReportExport()` with the same application
+action host for human and agent callers. The host authorizes and audits the
+fixed `reports.export` action; exports containing personal, sensitive, or secret
+columns require explicit confirmation.
+
+Preview, apply, and every worker call `validateReportExportExecution()`, which
+requires the host to prove that the opaque binding still resolves to the exact
+immutable materialization snapshot under its current principal, tenant, report
+definition, and field policy. If it cannot, the operation fails rather than
+relabelling newer rows with an old `asOf`. Artifact metadata has no URL or
+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.
+
 ## Development
 
 ```bash

package/dist/index.d.ts

@@ -8,9 +8,11 @@ import { buildAggregate } from '@happyvertical/sql';
 import { DatabaseInterface } from '@happyvertical/sql';
 import { DataQueryFieldDescriptor } from '@happyvertical/smrt-types';
 import { DataQueryFilter } from '@happyvertical/smrt-types';
+import { DataQueryFreshness } from '@happyvertical/smrt-types';
 import { DataQueryRequest } from '@happyvertical/smrt-types';
 import { DataQueryResult } from '@happyvertical/smrt-types';
 import { DataQuerySchema } from '@happyvertical/smrt-types';
+import { DataQuerySort } from '@happyvertical/smrt-types';
 import { EventEmitter } from 'node:events';
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { SmrtJob } from '@happyvertical/smrt-jobs';
@@ -33,11 +35,33 @@ export { AggregateSelectExpr }
 
 export { AggregateSpec }
 
+export declare type AppliedReportExport = {
+    phase: 'apply';
+    execution: 'stream';
+    status: 'ready';
+    request: ReportExportRequest;
+} | {
+    phase: 'apply';
+    execution: 'background';
+    status: 'queued';
+    taskId: string;
+    request: ReportExportRequest;
+};
+
 export declare interface AppliedReportRefresh {
     phase: 'apply';
     job: ReportRefreshJobHandle;
 }
 
+/**
+ * Queue large exports without embedding rows in a browser/agent response.
+ * A host must verify current principal, tenant, report definition, and field
+ * policy again before it renders or serves the artifact.
+ */
+export declare function applyReportExport(descriptor: ReportAdapterDescriptor, request: ReportExportRequest, host: ReportExportActionHost, options?: {
+    confirmed?: boolean;
+}): Promise<AppliedReportExport>;
+
 /** Queue a manual refresh only after the action host authorizes and audits it. */
 export declare function applyReportRefresh(reportCtor: ReportCtor, options: ApplyReportRefreshOptions): Promise<AppliedReportRefresh>;
 
@@ -85,6 +109,27 @@ export declare function count(options: {
     distinct?: boolean;
 }): PropertyDecorator;
 
+/**
+ * Build one bounded page of the immutable export read. The host applies the
+ * opaque snapshot binding separately; this function preserves the frozen
+ * projection, predicate, and deterministic sort while replacing only visible
+ * pagination. A zero-row export therefore has no pages to execute.
+ */
+export declare function createReportExportPageRequest(descriptor: ReportAdapterDescriptor, request: ReportExportRequest, offset: number): DataQueryRequest;
+
+/**
+ * Build one common request for both agent and human export clients. The
+ * resulting request carries no actor, tenant, storage location, or token.
+ */
+export declare function createReportExportRequest(descriptor: ReportAdapterDescriptor, snapshot: ReportExportSnapshot, value: unknown): ReportExportRequest;
+
+/**
+ * Freeze a previously executed materialized read for export. The caller must
+ * supply the exact request and a result that exposes lifecycle freshness; an
+ * export never invents an as-of value or accepts a caller-supplied tenant.
+ */
+export declare function createReportExportSnapshot(descriptor: ReportAdapterDescriptor, input: unknown, result: Pick<DataQueryResult, 'queryFingerprint' | 'identityField' | 'total' | 'freshness' | 'truncated'> & Pick<ReportDataQueryResult, 'reportLifecycle'>, binding: unknown): ReportExportSnapshot;
+
 export declare const day: (sourceColumn: string) => PropertyDecorator;
 
 export declare function enqueueReportRefresh(options: EnqueueReportRefreshOptions): Promise<SmrtJob>;
@@ -126,10 +171,19 @@ export declare function groupBy(sourceColumn?: string): PropertyDecorator;
 
 export declare const hour: (sourceColumn: string) => PropertyDecorator;
 
+declare const INHERITED_REPORT_SCOPE: readonly ["principal", "tenant", "report-definition", "field-policy"];
+
 export declare const max: (column?: string, options?: {
     distinct?: boolean;
 }) => PropertyDecorator;
 
+/**
+ * Version 0 is the original unversioned persisted layout shape. It contains
+ * the same allowlisted fields as v1, so the migration only records the schema
+ * version; current descriptor normalization still revalidates every field.
+ */
+export declare function migrateReportSavedView(value: unknown): SavedViewInput;
+
 export declare const min: (column?: string, options?: {
     distinct?: boolean;
 }) => PropertyDecorator;
@@ -138,6 +192,15 @@ export declare const minute: (sourceColumn: string) => PropertyDecorator;
 
 export declare const month: (sourceColumn: string) => PropertyDecorator;
 
+/**
+ * Normalize a view both when it is saved and when it is restored. Re-running
+ * this against the live descriptor is what prevents a former field/action
+ * grant from surviving a policy or definition change.
+ */
+export declare function normalizeReportSavedView(descriptor: ReportAdapterDescriptor, value: unknown): ReportSavedView;
+
+export declare function previewReportExport(descriptor: ReportAdapterDescriptor, request: ReportExportRequest, host: ReportExportActionHost): Promise<ReportExportPreview>;
+
 /** Preview only declares a separately authorized and audited refresh request. */
 export declare function previewReportRefresh(reportCtor: ReportCtor, options: PreviewReportRefreshOptions): Promise<ReportRefreshPreview>;
 
@@ -222,6 +285,18 @@ export declare interface ReportAggregateFieldMetadata {
 
 export declare type ReportAggregateFn = AggregateFunction;
 
+/**
+ * An authority-free job handoff. The queue must re-enter the bound principal
+ * and tenant, resolve the current report definition/field policy, and verify
+ * this snapshot before materializing an artifact.
+ */
+export declare interface ReportBackgroundExportTask {
+    version: 1;
+    execution: 'background';
+    request: ReportExportRequest;
+    inherits: Array<(typeof INHERITED_REPORT_SCOPE)[number]>;
+}
+
 /** Background execution is possible only through an application-owned queue host. */
 export declare interface ReportBackgroundQueryOptions extends ReportQueryCommonOptions {
     execution: 'background';
@@ -396,6 +471,12 @@ export declare interface ReportDefinition {
     refresh?: ReportRefreshConfig;
 }
 
+/**
+ * A change to report fields, their capabilities, schema, scope, or source
+ * invalidates a stored view/export snapshot rather than silently widening it.
+ */
+export declare function reportDefinitionFingerprint(descriptor: ReportAdapterDescriptor): string;
+
 export declare interface ReportDrilldownConstraint {
     id: string;
     sourceColumn: string;
@@ -436,6 +517,148 @@ export declare interface ReportDrilldownQuery {
     inherits: Array<'principal' | 'tenant' | 'report-definition' | 'field-policy'>;
 }
 
+export declare interface ReportExportActionContext {
+    phase: 'preview' | 'apply';
+    reportClassName: string;
+    resourceId: string;
+    requiredPermission: string;
+    confirmationRequired: boolean;
+    execution: 'stream' | 'background';
+    queryFingerprint: string;
+    definitionFingerprint: string;
+    snapshotId: string;
+    asOf: string;
+    pageSize: number;
+}
+
+/** The same host is used by human and agent callers. */
+export declare interface ReportExportActionHost {
+    /**
+     * Prove that this opaque binding still resolves to the exact immutable
+     * materialization snapshot under the host's current principal and tenant.
+     * The background worker must call `validateReportExportExecution()` again
+     * before reading or serving any rows.
+     */
+    assertSnapshot(context: ReportExportSnapshotContext): Promise<void> | void;
+    authorize(context: ReportExportActionContext): Promise<void> | void;
+    audit(context: ReportExportActionContext): Promise<void> | void;
+    enqueue?(task: ReportBackgroundExportTask): Promise<{
+        taskId: string;
+    }> | {
+        taskId: string;
+    };
+}
+
+/**
+ * Artifact metadata is deliberately URL- and token-free. An application-owned
+ * serving boundary must authorize every download using the caller's current
+ * principal and tenant before it reveals any artifact location.
+ */
+export declare interface ReportExportArtifact {
+    id: string;
+    request: ReportExportRequest;
+    progress: ReportExportProgress;
+    expiresAt: string;
+}
+
+export declare type ReportExportFormat = 'csv' | 'json';
+
+/** Every export is bounded before it is streamed or delegated to a worker. */
+export declare interface ReportExportLimits {
+    maxRows: number;
+    maxBytes: number;
+    deadlineMs: number;
+    /** Exports above this exact row count must use the application queue. */
+    foregroundRowLimit: number;
+}
+
+export declare interface ReportExportPreview {
+    phase: 'preview';
+    action: ReportExportActionContext;
+    request: ReportExportRequest;
+}
+
+export declare interface ReportExportProgress {
+    state: 'queued' | 'running' | 'completed' | 'failed';
+    rowCount: number;
+    byteCount: number;
+    truncated: boolean;
+}
+
+/**
+ * A deterministic offset-page plan over the immutable host snapshot. A worker
+ * starts at offset zero and advances by `page.limit` until `rowCount` rows have
+ * been produced or the byte/deadline limits are reached.
+ */
+export declare interface ReportExportReadPlan {
+    snapshotId: string;
+    queryFingerprint: string;
+    asOf: string;
+    page: {
+        kind: 'offset';
+        offset: 0;
+        limit: number;
+    };
+}
+
+export declare interface ReportExportRequest {
+    version: 1;
+    format: ReportExportFormat;
+    execution: 'stream' | 'background';
+    snapshot: ReportExportSnapshot;
+    limits: ReportExportLimits;
+    read: ReportExportReadPlan;
+    rowCount: number;
+    truncated: boolean;
+    action: {
+        id: 'export';
+        requiredPermission: string;
+        auditRequired: true;
+        confirmationRequired: boolean;
+    };
+}
+
+export declare interface ReportExportSnapshot {
+    version: 1;
+    resourceId: string;
+    reportClassName: string;
+    definitionFingerprint: string;
+    binding: ReportExportSnapshotBinding;
+    request: DataQueryRequest;
+    queryFingerprint: string;
+    projection: string[];
+    sort: DataQuerySort[];
+    freshness: DataQueryFreshness;
+    snapshot: {
+        asOf: string;
+        refreshedAt?: string;
+        stale: boolean;
+    };
+    total: {
+        kind: 'exact';
+        value: number;
+    };
+    inherits: Array<(typeof INHERITED_REPORT_SCOPE)[number]>;
+}
+
+/**
+ * Opaque identity of a host-captured materialization snapshot. The application
+ * creates and verifies it while bound to its principal and tenant; callers
+ * cannot turn an `asOf` label into a snapshot by supplying this id alone.
+ */
+export declare interface ReportExportSnapshotBinding {
+    id: string;
+}
+
+export declare interface ReportExportSnapshotContext {
+    bindingId: string;
+    resourceId: string;
+    reportClassName: string;
+    definitionFingerprint: string;
+    queryFingerprint: string;
+    asOf: string;
+}
+
 export declare interface ReportFieldDefinition {
     fieldName: string;
     columnName?: string;
@@ -714,6 +937,42 @@ export declare function reportRowIdentity(row: Record<string, any>, definition:
 
 declare type ReportRunStatus = 'running' | 'success' | 'failed' | 'skipped';
 
+/**
+ * A normalized, policy-neutral stored view. The storage host associates it
+ * with its owner and tenant; neither identity is accepted here.
+ */
+export declare interface ReportSavedView {
+    version: 1;
+    id: string;
+    title: string;
+    resourceId: string;
+    reportClassName: string;
+    definitionFingerprint: string;
+    query: DataQueryRequest;
+    columns: ReportSavedViewColumn[];
+    grouping?: ReportSavedViewGrouping;
+    display?: ReportSavedViewDisplay;
+}
+
+/** A view's column order is its array order; ids are always adapter-defined. */
+export declare interface ReportSavedViewColumn {
+    id: string;
+    width?: number;
+    pinned?: ReportSavedViewPinnedSide;
+}
+
+export declare interface ReportSavedViewDisplay {
+    density: 'compact' | 'comfortable';
+    showTotals?: boolean;
+}
+
+export declare interface ReportSavedViewGrouping {
+    fields: string[];
+    expanded?: boolean;
+}
+
+export declare type ReportSavedViewPinnedSide = 'start' | 'end';
+
 export declare interface ReportScheduleInfo {
     id: string;
     reportClass: string;
@@ -759,8 +1018,28 @@ declare type ReportScheduleStatus = 'active' | 'paused' | 'disabled' | 'error';
 
 export declare type ReportSource = string | (new (...args: any[]) => SmrtObject) | (abstract new (...args: any[]) => SmrtObject);
 
+export declare class ReportSurfaceValidationError extends Error {
+    constructor(message: string);
+}
+
 export declare type ReportTimeBucketUnit = AggregateTimeBucketUnit;
 
+/** Restore through current policy rather than trusting a stored JSON record. */
+export declare function restoreReportSavedView(descriptor: ReportAdapterDescriptor, savedView: ReportSavedView): ReportSavedView;
+
+declare interface SavedViewInput {
+    version?: unknown;
+    id: unknown;
+    title: unknown;
+    resourceId?: unknown;
+    reportClassName?: unknown;
+    definitionFingerprint?: unknown;
+    query: unknown;
+    columns?: unknown;
+    grouping?: unknown;
+    display?: unknown;
+}
+
 export declare function scopeKeyForTenant(tenantId: string | null | undefined): string;
 
 export declare class SmrtReport extends SmrtObject {
@@ -879,6 +1158,29 @@ export declare const sum: (column?: string, options?: {
     distinct?: boolean;
 }) => PropertyDecorator;
 
+/**
+ * Validate artifact metadata before a host serves it. Download locations and
+ * tokens stay application-private; expired artifacts fail before that boundary.
+ */
+export declare function validateReportExportArtifact(descriptor: ReportAdapterDescriptor, artifact: ReportExportArtifact, now?: Date): ReportExportArtifact;
+
+/**
+ * Revalidate the request and prove the opaque snapshot binding through the
+ * application host. Preview, apply, and every background worker use this same
+ * operation before reading or serving export data.
+ */
+export declare function validateReportExportExecution(descriptor: ReportAdapterDescriptor, request: ReportExportRequest, host: Pick<ReportExportActionHost, 'assertSnapshot'>): Promise<ReportExportRequest>;
+
+/**
+ * Recreate the deterministic request from its current descriptor and frozen
+ * snapshot. Preview, apply, queue, and serving hosts call this instead of
+ * trusting browser- or agent-supplied action metadata.
+ */
+export declare function validateReportExportRequest(descriptor: ReportAdapterDescriptor, request: ReportExportRequest): ReportExportRequest;
+
+/** Reject definitions/policies that changed after a snapshot was frozen. */
+export declare function verifyReportExportSnapshot(descriptor: ReportAdapterDescriptor, snapshot: ReportExportSnapshot): ReportExportSnapshot;
+
 export declare const week: (sourceColumn: string) => PropertyDecorator;
 
 export declare const year: (sourceColumn: string) => PropertyDecorator;