@happyvertical/smrt-reports 0.43.0 → 0.43.2

package/dist/index.js

@@ -8,6 +8,7 @@ import { DataQueryValidationError, ObjectRegistry, SmrtCollection, SmrtObject, c
 import { toSnakeCase } from "@happyvertical/smrt-core/utils";
 import { getTenantId, withSystemContext } from "@happyvertical/smrt-tenancy";
 import { tableExists, validateColumnName } from "@happyvertical/sql";
+import { createHash } from "node:crypto";
 //#region src/lifecycle.ts
 function registeredReport(reportCtor) {
 	return ObjectRegistry.getClassByConstructor(reportCtor) ?? ObjectRegistry.getClass(reportCtor.name);
@@ -131,7 +132,7 @@ async function getReportLifecycle(reportCtor, options) {
 		}
 	};
 }
-function actionContext(reportCtor, phase, mode, refreshAction) {
+function actionContext$1(reportCtor, phase, mode, refreshAction) {
 	return {
 		phase,
 		reportClassName: canonicalClassName(reportCtor),
@@ -145,7 +146,7 @@ async function actionMode(reportCtor, requested) {
 	return (await buildReportDefinition(reportCtor)).refresh?.mode ?? "rebuild";
 }
 async function previewReportRefresh(reportCtor, options) {
-	const action = actionContext(reportCtor, "preview", await actionMode(reportCtor, options.mode), options.refreshAction);
+	const action = actionContext$1(reportCtor, "preview", await actionMode(reportCtor, options.mode), options.refreshAction);
 	await options.host.authorize(action);
 	await options.host.audit(action);
 	return {
@@ -157,7 +158,7 @@ async function previewReportRefresh(reportCtor, options) {
 }
 async function applyReportRefresh(reportCtor, options) {
 	const mode = await actionMode(reportCtor, options.mode);
-	const action = actionContext(reportCtor, "apply", mode, options.refreshAction);
+	const action = actionContext$1(reportCtor, "apply", mode, options.refreshAction);
 	await options.host.authorize(action);
 	await options.host.audit(action);
 	const tenantId = lifecycleTenantId(reportCtor);
@@ -988,6 +989,526 @@ var SmrtReportCollection = class extends SmrtCollection {
 	}
 };
 //#endregion
-export { REPORT_LOCKS_TABLE, REPORT_REFRESH_TASKS_TABLE, REPORT_RUNS_TABLE, REPORT_RUNTIME_TABLES, REPORT_SCHEDULER_TABLES, REPORT_SCHEDULES_TABLE, REPORT_WATERMARKS_TABLE, ReportScheduleRunner, SmrtReport, SmrtReportCollection, SmrtReportLock, SmrtReportLockCollection, SmrtReportRefreshTask, SmrtReportRun, SmrtReportRunCollection, SmrtReportSchedule, SmrtReportScheduleCollection, SmrtReportWatermark, SmrtReportWatermarkCollection, aggregate, applyReportRefresh, assertReportTablesReady, avg, bucketExpr, buildAggregate, buildReportAdapterDescriptor, buildReportDefinition, buildReportDrilldownQuery, compileReportDefinition, compileReportSpec, count, day, enqueueReportRefresh, ensureReportRefreshSchedules, getReportGroupingColumns, getReportLifecycle, getRuntimeReportOptions, groupBy, hour, max, min, minute, month, previewReportRefresh, quarter, queryReportMaterializedRows, refreshReport, registerReportRefreshInterceptor, report, reportMaterializedRowKey, reportRefreshOutcome, reportRowIdentity, scopeKeyForTenant, splitReportFilterScopes, sum, week, year };
+//#region src/views.ts
+var INHERITED_REPORT_SCOPE = [
+	"principal",
+	"tenant",
+	"report-definition",
+	"field-policy"
+];
+var EXPORT_FORMATS = /* @__PURE__ */ new Set(["csv", "json"]);
+var PINNED_COLUMN_SIDES = /* @__PURE__ */ new Set(["start", "end"]);
+var DISPLAY_DENSITIES = /* @__PURE__ */ new Set(["compact", "comfortable"]);
+var RFC_3339_INSTANT = /^(\d{4})-(\d{2})-(\d{2})T([01]\d|2[0-3]):([0-5]\d):([0-5]\d)(?:\.\d{1,9})?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/;
+var DEFAULT_EXPORT_LIMITS = {
+	maxRows: 1e5,
+	maxBytes: 25e6,
+	deadlineMs: 6e4,
+	foregroundRowLimit: 1e3
+};
+var MAX_EXPORT_LIMITS = {
+	maxRows: 1e6,
+	maxBytes: 1e8,
+	deadlineMs: 3e5,
+	foregroundRowLimit: 1e5
+};
+var ReportSurfaceValidationError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ReportSurfaceValidationError";
+	}
+};
+function fail(message) {
+	throw new ReportSurfaceValidationError(message);
+}
+function plainObject(value, label) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return fail(`${label} must be a plain object`);
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) return fail(`${label} must be a plain object`);
+	return value;
+}
+function exactKeys(value, allowed, label) {
+	for (const key of Object.keys(value)) if (!allowed.includes(key)) fail(`${label} contains an unsupported field: ${key}`);
+}
+function requiredString(value, label, maxLength = 256) {
+	if (typeof value !== "string") return fail(`${label} must be a string`);
+	const normalized = value.trim();
+	if (!normalized) return fail(`${label} cannot be empty`);
+	if (normalized.length > maxLength) return fail(`${label} cannot exceed ${String(maxLength)} characters`);
+	return normalized;
+}
+function optionalBoolean(value, label) {
+	if (value === void 0) return void 0;
+	if (typeof value !== "boolean") return fail(`${label} must be a boolean`);
+	return value;
+}
+function boundedInteger(value, label, minimum, maximum) {
+	if (!Number.isInteger(value) || value < minimum) return fail(`${label} must be an integer of at least ${String(minimum)}`);
+	if (value > maximum) return fail(`${label} cannot exceed ${String(maximum)}`);
+	return value;
+}
+function normalizeIso(value, label) {
+	const text = requiredString(value, label, 64);
+	const match = RFC_3339_INSTANT.exec(text);
+	if (!match) return fail(`${label} must be an RFC 3339 instant`);
+	const [year, month, day] = match.slice(1, 4).map(Number);
+	const calendar = /* @__PURE__ */ new Date(0);
+	calendar.setUTCFullYear(year, month - 1, day);
+	calendar.setUTCHours(0, 0, 0, 0);
+	if (calendar.getUTCFullYear() !== year || calendar.getUTCMonth() !== month - 1 || calendar.getUTCDate() !== day) return fail(`${label} must be an RFC 3339 instant`);
+	const parsed = new Date(text);
+	if (Number.isNaN(parsed.getTime())) return fail(`${label} must be an RFC 3339 instant`);
+	return parsed.toISOString();
+}
+function normalizeSnapshotBinding(value) {
+	const input = plainObject(value, "Report export snapshot binding");
+	exactKeys(input, ["id"], "Report export snapshot binding");
+	return { id: requiredString(input.id, "Report export snapshot binding id") };
+}
+function stable(value) {
+	if (value === null || typeof value === "boolean" || typeof value === "number") return JSON.stringify(value);
+	if (typeof value === "string") return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map(stable).join(",")}]`;
+	const object = plainObject(value, "Report surface value");
+	return "{" + Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stable(object[key])}`).join(",") + "}";
+}
+function reportDefinitionFingerprint(descriptor) {
+	const definition = {
+		resourceId: descriptor.resourceId,
+		reportClassName: descriptor.reportClassName,
+		sourceClassName: descriptor.sourceClassName,
+		tenantScoped: descriptor.tenantScoped,
+		tenantField: descriptor.tenantField ?? null,
+		identityField: descriptor.identityField,
+		columns: descriptor.columns.map((column) => ({
+			id: column.id,
+			fieldName: column.fieldName,
+			kind: column.kind,
+			filterScope: column.filterScope,
+			type: column.type,
+			projectable: column.projectable === true,
+			sortable: column.sortable === true,
+			facetable: column.facetable === true,
+			filterOperators: column.filterOperators ?? [],
+			capabilities: [...column.capabilities].sort(),
+			sensitivity: column.sensitivity ?? null,
+			sourceColumn: column.sourceColumn ?? null,
+			bucket: column.bucket ?? null,
+			aggregate: column.aggregate ?? null,
+			distinct: column.distinct ?? null
+		})),
+		schema: descriptor.schema
+	};
+	return "rv1_" + createHash("sha256").update(stable(definition), "utf8").digest("base64url");
+}
+function columnMap(descriptor) {
+	return new Map(descriptor.columns.map((column) => [column.id, column]));
+}
+function requireColumnCapability(descriptor, id, capability, label) {
+	const columnId = requiredString(id, label);
+	if (!columnMap(descriptor).get(columnId)?.capabilities.includes(capability)) return fail(`${label} is not available under the current report policy`);
+	return columnId;
+}
+function normalizeColumns(descriptor, value) {
+	if (value === void 0) return descriptor.columns.filter((column) => column.capabilities.includes("project")).map((column) => ({ id: column.id }));
+	if (!Array.isArray(value)) return fail("Saved report view columns must be an array");
+	if (value.length > descriptor.columns.length) return fail("Saved report view columns cannot repeat or exceed exposed columns");
+	const ids = /* @__PURE__ */ new Set();
+	return value.map((entry, index) => {
+		const input = plainObject(entry, `Saved report view columns[${String(index)}]`);
+		const id = requireColumnCapability(descriptor, input.id, "project", `Saved report view columns[${String(index)}].id`);
+		if (ids.has(id)) return fail("Saved report view columns cannot repeat ids");
+		ids.add(id);
+		const width = input.width === void 0 ? void 0 : boundedInteger(input.width, `Saved report view columns[${String(index)}].width`, 40, 2e3);
+		const pinned = input.pinned === void 0 ? void 0 : requiredString(input.pinned, `Saved report view columns[${String(index)}].pinned`, 16);
+		if (pinned !== void 0 && !PINNED_COLUMN_SIDES.has(pinned)) return fail(`Saved report view columns[${String(index)}].pinned is invalid`);
+		return {
+			id,
+			...width === void 0 ? {} : { width },
+			...pinned === void 0 ? {} : { pinned }
+		};
+	});
+}
+function normalizeGrouping(descriptor, value) {
+	if (value === void 0) return void 0;
+	const input = plainObject(value, "Saved report view grouping");
+	if (!Array.isArray(input.fields)) return fail("Saved report view grouping.fields must be an array");
+	const fields = input.fields.map((field, index) => requireColumnCapability(descriptor, field, "group", `Saved report view grouping.fields[${String(index)}]`));
+	if (new Set(fields).size !== fields.length) return fail("Saved report view grouping.fields cannot repeat ids");
+	const expanded = optionalBoolean(input.expanded, "Saved report view grouping.expanded");
+	return {
+		fields,
+		...expanded === void 0 ? {} : { expanded }
+	};
+}
+function normalizeDisplay(value) {
+	if (value === void 0) return void 0;
+	const input = plainObject(value, "Saved report view display");
+	const density = requiredString(input.density, "Saved report view display.density", 16);
+	if (!DISPLAY_DENSITIES.has(density)) return fail("Saved report view display.density is invalid");
+	const showTotals = optionalBoolean(input.showTotals, "Saved report view display.showTotals");
+	return {
+		density,
+		...showTotals === void 0 ? {} : { showTotals }
+	};
+}
+function migrateReportSavedView(value) {
+	const input = plainObject(value, "Saved report view");
+	if (input.version === void 0 || input.version === 0) return {
+		...input,
+		version: 1
+	};
+	if (input.version === 1) return input;
+	return fail("Saved report view version is unsupported");
+}
+function normalizeReportSavedView(descriptor, value) {
+	const input = migrateReportSavedView(value);
+	const fingerprint = reportDefinitionFingerprint(descriptor);
+	if (input.resourceId !== void 0 && input.resourceId !== descriptor.resourceId) return fail("Saved report view belongs to a different report resource");
+	if (input.reportClassName !== void 0 && input.reportClassName !== descriptor.reportClassName) return fail("Saved report view belongs to a different report class");
+	if (input.definitionFingerprint !== void 0 && input.definitionFingerprint !== fingerprint) return fail("Saved report view definition has changed");
+	const query = normalizeDataQueryRequest(input.query, descriptor.schema);
+	if (query.mode !== "rows") return fail("Saved report views must use a rows query");
+	splitReportFilterScopes(descriptor, query.filter);
+	const columns = normalizeColumns(descriptor, input.columns);
+	const grouping = normalizeGrouping(descriptor, input.grouping);
+	const display = normalizeDisplay(input.display);
+	return {
+		version: 1,
+		id: requiredString(input.id, "Saved report view id"),
+		title: requiredString(input.title, "Saved report view title", 240),
+		resourceId: descriptor.resourceId,
+		reportClassName: descriptor.reportClassName,
+		definitionFingerprint: fingerprint,
+		query,
+		columns,
+		...grouping === void 0 ? {} : { grouping },
+		...display === void 0 ? {} : { display }
+	};
+}
+function restoreReportSavedView(descriptor, savedView) {
+	return normalizeReportSavedView(descriptor, savedView);
+}
+function createReportExportSnapshot(descriptor, input, result, binding) {
+	const request = normalizeDataQueryRequest(input, descriptor.schema);
+	if (request.mode !== "rows") return fail("Report export snapshots require a rows query");
+	const queryFingerprint = createDataQueryFingerprint(request, descriptor.schema);
+	if (result.queryFingerprint !== queryFingerprint) return fail("Report export result does not match the requested query fingerprint");
+	if (result.identityField !== descriptor.identityField) return fail("Report export result has an unexpected row identity field");
+	if (result.total.kind !== "exact") return fail("Report export snapshots require an exact row count");
+	if (!Number.isSafeInteger(result.total.value) || result.total.value < 0) return fail("Report export snapshots require a safe non-negative row count");
+	if (result.truncated) return fail("Report export snapshots cannot use a truncated query result");
+	if (result.freshness.state === "unknown") return fail("Report export snapshots require lifecycle freshness");
+	const lifecycleAsOf = result.reportLifecycle?.snapshot.asOf;
+	const freshnessAsOf = result.freshness.asOf;
+	const normalizedLifecycleAsOf = lifecycleAsOf ? normalizeIso(lifecycleAsOf, "Report export lifecycle snapshot asOf") : void 0;
+	const normalizedFreshnessAsOf = freshnessAsOf ? normalizeIso(freshnessAsOf, "Report export freshness asOf") : void 0;
+	if (normalizedLifecycleAsOf !== void 0 && normalizedFreshnessAsOf !== void 0 && normalizedLifecycleAsOf !== normalizedFreshnessAsOf) return fail("Report export lifecycle freshness does not match its snapshot");
+	const normalizedAsOf = normalizedLifecycleAsOf ?? normalizedFreshnessAsOf;
+	if (!normalizedAsOf) return fail("Report export snapshots require an as-of materialization instant");
+	const refreshedAt = result.reportLifecycle?.snapshot.refreshedAt;
+	return {
+		version: 1,
+		resourceId: descriptor.resourceId,
+		reportClassName: descriptor.reportClassName,
+		definitionFingerprint: reportDefinitionFingerprint(descriptor),
+		binding: normalizeSnapshotBinding(binding),
+		request,
+		queryFingerprint,
+		projection: [...request.projection ?? [descriptor.identityField]],
+		sort: [...request.sort ?? descriptor.schema.defaultSort ?? [{
+			field: descriptor.identityField,
+			direction: "asc"
+		}]],
+		freshness: {
+			state: result.freshness.state,
+			asOf: normalizedAsOf
+		},
+		snapshot: {
+			asOf: normalizedAsOf,
+			...refreshedAt ? { refreshedAt: normalizeIso(refreshedAt, "Report export snapshot refreshedAt") } : {},
+			stale: result.freshness.state === "stale"
+		},
+		total: {
+			kind: "exact",
+			value: result.total.value
+		},
+		inherits: [...INHERITED_REPORT_SCOPE]
+	};
+}
+function verifyReportExportSnapshot(descriptor, snapshot) {
+	exactKeys(plainObject(snapshot, "Report export snapshot"), [
+		"version",
+		"resourceId",
+		"reportClassName",
+		"definitionFingerprint",
+		"binding",
+		"request",
+		"queryFingerprint",
+		"projection",
+		"sort",
+		"freshness",
+		"snapshot",
+		"total",
+		"inherits"
+	], "Report export snapshot");
+	if (snapshot.version !== 1) return fail("Report export snapshot version is unsupported");
+	if (snapshot.resourceId !== descriptor.resourceId || snapshot.reportClassName !== descriptor.reportClassName) return fail("Report export snapshot belongs to a different report");
+	if (snapshot.definitionFingerprint !== reportDefinitionFingerprint(descriptor)) return fail("Report export definition has changed");
+	const binding = normalizeSnapshotBinding(snapshot.binding);
+	const normalized = normalizeDataQueryRequest(snapshot.request, descriptor.schema);
+	if (normalized.mode !== "rows") return fail("Report export snapshot query must remain a rows query");
+	if (createDataQueryFingerprint(normalized, descriptor.schema) !== snapshot.queryFingerprint) return fail("Report export snapshot query fingerprint is invalid");
+	const expectedProjection = normalized.projection ?? [descriptor.identityField];
+	const expectedSort = normalized.sort ?? descriptor.schema.defaultSort ?? [{
+		field: descriptor.identityField,
+		direction: "asc"
+	}];
+	if (!Array.isArray(snapshot.projection) || snapshot.projection.some((field) => typeof field !== "string")) return fail("Report export snapshot projection is invalid");
+	if (snapshot.projection.length !== expectedProjection.length || snapshot.projection.some((field, index) => field !== expectedProjection[index])) return fail("Report export snapshot projection or sort has changed");
+	if (!Array.isArray(snapshot.sort)) return fail("Report export snapshot sort is invalid");
+	if (stable(snapshot.sort.map((value) => {
+		const sortInput = plainObject(value, "Report export snapshot sort");
+		exactKeys(sortInput, ["field", "direction"], "Report export snapshot sort");
+		return {
+			field: requiredString(sortInput.field, "Report export snapshot sort field"),
+			direction: requiredString(sortInput.direction, "Report export snapshot sort direction")
+		};
+	})) !== stable(expectedSort)) return fail("Report export snapshot projection or sort has changed");
+	const freshness = plainObject(snapshot.freshness, "Report export snapshot freshness");
+	exactKeys(freshness, ["state", "asOf"], "Report export snapshot freshness");
+	const materialization = plainObject(snapshot.snapshot, "Report export snapshot materialization");
+	exactKeys(materialization, [
+		"asOf",
+		"refreshedAt",
+		"stale"
+	], "Report export snapshot materialization");
+	const total = plainObject(snapshot.total, "Report export snapshot total");
+	exactKeys(total, ["kind", "value"], "Report export snapshot total");
+	const totalValue = total.value;
+	const asOf = normalizeIso(materialization.asOf, "Report export snapshot asOf");
+	if (freshness.state !== "fresh" && freshness.state !== "stale") return fail("Report export snapshot freshness state is invalid");
+	const freshnessAsOf = normalizeIso(freshness.asOf, "Report export snapshot freshness asOf");
+	if (freshnessAsOf !== asOf) return fail("Report export snapshot freshness does not match its as-of instant");
+	const refreshedAt = materialization.refreshedAt ? normalizeIso(materialization.refreshedAt, "Report export snapshot refreshedAt") : void 0;
+	if (materialization.stale !== (freshness.state === "stale")) return fail("Report export snapshot stale state is invalid");
+	if (total.kind !== "exact" || typeof totalValue !== "number" || !Number.isSafeInteger(totalValue) || totalValue < 0) return fail("Report export snapshot row count is invalid");
+	if (!Array.isArray(snapshot.inherits) || snapshot.inherits.some((value) => typeof value !== "string") || snapshot.inherits.length !== INHERITED_REPORT_SCOPE.length || snapshot.inherits.some((value, index) => value !== INHERITED_REPORT_SCOPE[index])) return fail("Report export snapshot inheritance contract is invalid");
+	return {
+		version: 1,
+		resourceId: descriptor.resourceId,
+		reportClassName: descriptor.reportClassName,
+		definitionFingerprint: reportDefinitionFingerprint(descriptor),
+		binding,
+		request: normalized,
+		queryFingerprint: createDataQueryFingerprint(normalized, descriptor.schema),
+		projection: [...expectedProjection],
+		sort: expectedSort.map(({ field, direction }) => ({
+			field,
+			direction
+		})),
+		freshness: {
+			state: freshness.state,
+			asOf: freshnessAsOf
+		},
+		snapshot: {
+			asOf,
+			stale: materialization.stale,
+			...refreshedAt === void 0 ? {} : { refreshedAt }
+		},
+		total: {
+			kind: "exact",
+			value: totalValue
+		},
+		inherits: [...INHERITED_REPORT_SCOPE]
+	};
+}
+function normalizeExportLimits(value) {
+	if (value === void 0) return { ...DEFAULT_EXPORT_LIMITS };
+	const input = plainObject(value, "Report export limits");
+	const maxRows = boundedInteger(input.maxRows ?? DEFAULT_EXPORT_LIMITS.maxRows, "Report export limits.maxRows", 1, MAX_EXPORT_LIMITS.maxRows);
+	return {
+		maxRows,
+		maxBytes: boundedInteger(input.maxBytes ?? DEFAULT_EXPORT_LIMITS.maxBytes, "Report export limits.maxBytes", 1, MAX_EXPORT_LIMITS.maxBytes),
+		deadlineMs: boundedInteger(input.deadlineMs ?? DEFAULT_EXPORT_LIMITS.deadlineMs, "Report export limits.deadlineMs", 1, MAX_EXPORT_LIMITS.deadlineMs),
+		foregroundRowLimit: boundedInteger(input.foregroundRowLimit ?? Math.min(DEFAULT_EXPORT_LIMITS.foregroundRowLimit, maxRows), "Report export limits.foregroundRowLimit", 1, Math.min(maxRows, MAX_EXPORT_LIMITS.foregroundRowLimit))
+	};
+}
+function hasSensitiveProjection(descriptor, snapshot) {
+	const columns = columnMap(descriptor);
+	return snapshot.projection.some((id) => {
+		const sensitivity = columns.get(id)?.sensitivity;
+		return sensitivity === "personal" || sensitivity === "sensitive" || sensitivity === "secret";
+	});
+}
+function createReadPlan(descriptor, snapshot, limits) {
+	return {
+		snapshotId: snapshot.binding.id,
+		queryFingerprint: snapshot.queryFingerprint,
+		asOf: snapshot.snapshot.asOf,
+		page: {
+			kind: "offset",
+			offset: 0,
+			limit: Math.min(limits.maxRows, descriptor.schema.maxPageLimit ?? DEFAULT_EXPORT_LIMITS.foregroundRowLimit)
+		}
+	};
+}
+function createReportExportRequest(descriptor, snapshot, value) {
+	const input = plainObject(value, "Report export request");
+	const verified = verifyReportExportSnapshot(descriptor, snapshot);
+	const format = requiredString(input.format, "Report export format", 16);
+	if (!EXPORT_FORMATS.has(format)) return fail("Report export format is unsupported");
+	const limits = normalizeExportLimits(input.limits);
+	const rowCount = Math.min(verified.total.value, limits.maxRows);
+	const confirmationRequired = hasSensitiveProjection(descriptor, verified);
+	return {
+		version: 1,
+		format,
+		execution: verified.total.value > limits.foregroundRowLimit ? "background" : "stream",
+		snapshot: verified,
+		limits,
+		read: createReadPlan(descriptor, verified, limits),
+		rowCount,
+		truncated: verified.total.value > limits.maxRows,
+		action: {
+			id: "export",
+			requiredPermission: "reports.export",
+			auditRequired: true,
+			confirmationRequired
+		}
+	};
+}
+function validateReportExportRequest(descriptor, request) {
+	const expected = createReportExportRequest(descriptor, request.snapshot, {
+		format: request.format,
+		limits: request.limits
+	});
+	if (stable(request) !== stable(expected)) return fail("Report export request does not match current policy");
+	return expected;
+}
+function createReportExportPageRequest(descriptor, request, offset) {
+	const verified = validateReportExportRequest(descriptor, request);
+	if (!Number.isSafeInteger(offset) || offset < 0 || offset >= verified.rowCount) return fail("Report export page offset is outside the bounded export");
+	const limit = Math.min(verified.read.page.limit, verified.rowCount - offset);
+	return normalizeDataQueryRequest({
+		...verified.snapshot.request,
+		page: {
+			kind: "offset",
+			offset,
+			limit
+		}
+	}, descriptor.schema);
+}
+function actionContext(phase, request) {
+	return {
+		phase,
+		reportClassName: request.snapshot.reportClassName,
+		resourceId: request.snapshot.resourceId,
+		requiredPermission: request.action.requiredPermission,
+		confirmationRequired: request.action.confirmationRequired,
+		execution: request.execution,
+		queryFingerprint: request.snapshot.queryFingerprint,
+		definitionFingerprint: request.snapshot.definitionFingerprint,
+		snapshotId: request.read.snapshotId,
+		asOf: request.read.asOf,
+		pageSize: request.read.page.limit
+	};
+}
+function snapshotContext(request) {
+	return {
+		bindingId: request.snapshot.binding.id,
+		resourceId: request.snapshot.resourceId,
+		reportClassName: request.snapshot.reportClassName,
+		definitionFingerprint: request.snapshot.definitionFingerprint,
+		queryFingerprint: request.snapshot.queryFingerprint,
+		asOf: request.snapshot.snapshot.asOf
+	};
+}
+async function validateReportExportExecution(descriptor, request, host) {
+	const verified = validateReportExportRequest(descriptor, request);
+	await host.assertSnapshot(snapshotContext(verified));
+	return verified;
+}
+async function previewReportExport(descriptor, request, host) {
+	const initial = validateReportExportRequest(descriptor, request);
+	const action = actionContext("preview", initial);
+	await host.authorize(action);
+	const verified = await validateReportExportExecution(descriptor, initial, host);
+	await host.audit(action);
+	return {
+		phase: "preview",
+		action,
+		request: verified
+	};
+}
+async function applyReportExport(descriptor, request, host, options = {}) {
+	const initial = validateReportExportRequest(descriptor, request);
+	if (initial.action.confirmationRequired && options.confirmed !== true) return fail("Sensitive report exports require explicit confirmation");
+	const action = actionContext("apply", initial);
+	await host.authorize(action);
+	const verified = await validateReportExportExecution(descriptor, initial, host);
+	await host.audit(action);
+	if (verified.execution === "stream") return {
+		phase: "apply",
+		execution: "stream",
+		status: "ready",
+		request: verified
+	};
+	if (!host.enqueue) return fail("Background report exports require an application queue host");
+	const queued = await host.enqueue({
+		version: 1,
+		execution: "background",
+		request: verified,
+		inherits: [...INHERITED_REPORT_SCOPE]
+	});
+	if (typeof queued.taskId !== "string" || queued.taskId.trim().length === 0) return fail("Background report export hosts must return a task id");
+	return {
+		phase: "apply",
+		execution: "background",
+		status: "queued",
+		taskId: queued.taskId,
+		request: verified
+	};
+}
+function validateReportExportArtifact(descriptor, artifact, now = /* @__PURE__ */ new Date()) {
+	exactKeys(plainObject(artifact, "Report export artifact"), [
+		"id",
+		"request",
+		"progress",
+		"expiresAt"
+	], "Report export artifact");
+	const request = validateReportExportRequest(descriptor, artifact.request);
+	const id = requiredString(artifact.id, "Report export artifact id");
+	const expiresAt = normalizeIso(artifact.expiresAt, "Report export artifact expiresAt");
+	if (new Date(expiresAt).getTime() <= now.getTime()) return fail("Report export artifact has expired");
+	const progress = plainObject(artifact.progress, "Report export artifact progress");
+	exactKeys(progress, [
+		"state",
+		"rowCount",
+		"byteCount",
+		"truncated"
+	], "Report export artifact progress");
+	const state = progress.state;
+	if (state !== "queued" && state !== "running" && state !== "completed" && state !== "failed") return fail("Report export artifact progress state is invalid");
+	const rowCount = boundedInteger(progress.rowCount, "Report export artifact rowCount", 0, request.rowCount);
+	const byteCount = boundedInteger(progress.byteCount, "Report export artifact byteCount", 0, request.limits.maxBytes);
+	const truncated = progress.truncated;
+	if (typeof truncated !== "boolean") return fail("Report export artifact truncated must be a boolean");
+	if (state === "completed" && rowCount !== request.rowCount) return fail("Completed report export artifacts must contain the requested row count");
+	if (state === "completed" && truncated !== request.truncated) return fail("Completed report export artifacts must match the requested truncation state");
+	return {
+		id,
+		request,
+		expiresAt,
+		progress: {
+			state,
+			rowCount,
+			byteCount,
+			truncated
+		}
+	};
+}
+//#endregion
+export { REPORT_LOCKS_TABLE, REPORT_REFRESH_TASKS_TABLE, REPORT_RUNS_TABLE, REPORT_RUNTIME_TABLES, REPORT_SCHEDULER_TABLES, REPORT_SCHEDULES_TABLE, REPORT_WATERMARKS_TABLE, ReportScheduleRunner, ReportSurfaceValidationError, SmrtReport, SmrtReportCollection, SmrtReportLock, SmrtReportLockCollection, SmrtReportRefreshTask, SmrtReportRun, SmrtReportRunCollection, SmrtReportSchedule, SmrtReportScheduleCollection, SmrtReportWatermark, SmrtReportWatermarkCollection, aggregate, applyReportExport, applyReportRefresh, assertReportTablesReady, avg, bucketExpr, buildAggregate, buildReportAdapterDescriptor, buildReportDefinition, buildReportDrilldownQuery, compileReportDefinition, compileReportSpec, count, createReportExportPageRequest, createReportExportRequest, createReportExportSnapshot, day, enqueueReportRefresh, ensureReportRefreshSchedules, getReportGroupingColumns, getReportLifecycle, getRuntimeReportOptions, groupBy, hour, max, migrateReportSavedView, min, minute, month, normalizeReportSavedView, previewReportExport, previewReportRefresh, quarter, queryReportMaterializedRows, refreshReport, registerReportRefreshInterceptor, report, reportDefinitionFingerprint, reportMaterializedRowKey, reportRefreshOutcome, reportRowIdentity, restoreReportSavedView, scopeKeyForTenant, splitReportFilterScopes, sum, validateReportExportArtifact, validateReportExportExecution, validateReportExportRequest, verifyReportExportSnapshot, week, year };
 
 //# sourceMappingURL=index.js.map