@happyvertical/smrt-reports 0.42.6 → 0.42.7

package/dist/index.js

@@ -1,13 +1,916 @@
-import { bucketExpr, buildAggregate } from "./aggregate.js";
 import { aggregate, avg, count, day, getRuntimeReportOptions, groupBy, hour, max, min, minute, month, quarter, report, sum, week, year } from "./decorators.js";
 import { buildReportDefinition, compileReportDefinition, compileReportSpec, getReportGroupingColumns } from "./compiler.js";
 import { 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, assertReportTablesReady, scopeKeyForTenant } from "./state.js";
 import { refreshReport, reportRowIdentity } from "./refresh.js";
 import { ReportScheduleRunner, SmrtReportRefreshTask, enqueueReportRefresh, ensureReportRefreshSchedules, registerReportRefreshInterceptor } from "./scheduler.js";
-import { validateColumnName } from "@happyvertical/sql";
-import { ObjectRegistry, SmrtCollection, SmrtObject } from "@happyvertical/smrt-core";
+import { bucketExpr, buildAggregate } from "./aggregate.js";
+import { DataQueryValidationError, ObjectRegistry, SmrtCollection, SmrtObject, createDataQueryFingerprint, normalizeDataQueryRequest, normalizeDataQueryResult } from "@happyvertical/smrt-core";
 import { toSnakeCase } from "@happyvertical/smrt-core/utils";
-import { getTenantId } from "@happyvertical/smrt-tenancy";
+import { getTenantId, withSystemContext } from "@happyvertical/smrt-tenancy";
+import { tableExists, validateColumnName } from "@happyvertical/sql";
+//#region src/lifecycle.ts
+function registeredReport(reportCtor) {
+	return ObjectRegistry.getClassByConstructor(reportCtor) ?? ObjectRegistry.getClass(reportCtor.name);
+}
+function canonicalClassName(reportCtor) {
+	const registered = registeredReport(reportCtor);
+	return registered?.qualifiedName ?? registered?.name ?? reportCtor.name;
+}
+function reportTableName(reportCtor) {
+	const reportClassName = canonicalClassName(reportCtor);
+	const tableName = ObjectRegistry.getTableName(reportClassName);
+	if (!tableName) throw new Error(`No report table registered for ${reportCtor.name}`);
+	return validateColumnName(tableName);
+}
+async function reportColumnName(reportClassName, fieldName) {
+	const direct = (await ObjectRegistry.getAllFields(reportClassName)).get(fieldName);
+	return validateColumnName(direct?.columnName ?? direct?._meta?.columnName ?? fieldName.replace(/([A-Z])/g, "_$1").toLowerCase());
+}
+function toIso(value) {
+	if (!value) return void 0;
+	const date = value instanceof Date ? value : new Date(String(value));
+	return Number.isNaN(date.getTime()) ? void 0 : date.toISOString();
+}
+function latestIso(first, second) {
+	if (!first) return second;
+	if (!second) return first;
+	return new Date(first).getTime() >= new Date(second).getTime() ? first : second;
+}
+function lifecycleTenantId(reportCtor) {
+	return registeredReport(reportCtor)?.tenantScopedConfig ? getTenantId() ?? null : null;
+}
+function numberValue(value) {
+	const numeric = Number(value ?? 0);
+	return Number.isFinite(numeric) ? numeric : 0;
+}
+function rowWhere(reportClassName, scopeKey, tenantId) {
+	if (tenantId) return {
+		sql: "report_class = ? AND scope_key = ? AND tenant_id = ?",
+		values: [
+			reportClassName,
+			scopeKey,
+			tenantId
+		]
+	};
+	return {
+		sql: "report_class = ? AND scope_key = ? AND tenant_id IS NULL",
+		values: [reportClassName, scopeKey]
+	};
+}
+function runFromRow(row) {
+	if (!row || typeof row.id !== "string") return void 0;
+	const status = row.status;
+	if (status !== "running" && status !== "success" && status !== "failed" && status !== "skipped") return;
+	const mode = row.mode === "incremental" ? "incremental" : "rebuild";
+	const trigger = row.trigger === "schedule" || row.trigger === "change" || row.trigger === "ttl" || row.trigger === "job" ? row.trigger : "manual";
+	return {
+		id: row.id,
+		status,
+		mode,
+		trigger,
+		...toIso(row.started_at) ? { startedAt: toIso(row.started_at) } : {},
+		...toIso(row.completed_at) ? { completedAt: toIso(row.completed_at) } : {},
+		rowCount: numberValue(row.row_count),
+		changedGroupCount: numberValue(row.changed_group_count),
+		mayRetry: status === "failed"
+	};
+}
+function jobHandle(job) {
+	if (typeof job.id !== "string" || job.id.length === 0) throw new Error("Queued report refresh is missing its job id");
+	return {
+		jobId: job.id,
+		status: job.status,
+		attempts: job.attempts,
+		maxAttempts: job.maxAttempts,
+		pollAfterMs: 1e3
+	};
+}
+async function getReportLifecycle(reportCtor, options) {
+	await assertReportTablesReady(options.db, [REPORT_RUNS_TABLE, REPORT_LOCKS_TABLE]);
+	const definition = await buildReportDefinition(reportCtor);
+	const reportClassName = canonicalClassName(reportCtor);
+	const tenantId = lifecycleTenantId(reportCtor);
+	const where = rowWhere(reportClassName, scopeKeyForTenant(tenantId), tenantId);
+	const now = options.now ?? /* @__PURE__ */ new Date();
+	const [runResult, lockResult] = await Promise.all([options.db.query(`SELECT id, mode, trigger, status, started_at, completed_at, row_count, changed_group_count
+         FROM ${REPORT_RUNS_TABLE}
+        WHERE ${where.sql}
+        ORDER BY started_at DESC, created_at DESC, id DESC
+        LIMIT 1`, ...where.values), options.db.query(`SELECT expires_at
+         FROM ${REPORT_LOCKS_TABLE}
+        WHERE ${where.sql} AND expires_at > ?
+        LIMIT 1`, ...where.values, now.toISOString())]);
+	const tableName = reportTableName(reportCtor);
+	if (!await tableExists(options.db, tableName)) throw new Error(`Report table '${tableName}' does not exist for ${reportClassName}`);
+	const refreshedAtColumn = await reportColumnName(reportClassName, "refreshedAt");
+	const configuredTenantField = registeredReport(reportCtor)?.tenantScopedConfig?.field;
+	const tenantColumn = configuredTenantField ? await reportColumnName(reportClassName, configuredTenantField) : void 0;
+	const materialized = tenantColumn ? await options.db.query(`SELECT MAX(${refreshedAtColumn}) AS refreshed_at FROM ${tableName} WHERE ${tenantColumn} ${tenantId ? "= ?" : "IS NULL"}`, ...tenantId ? [tenantId] : []) : await options.db.query(`SELECT MAX(${refreshedAtColumn}) AS refreshed_at FROM ${tableName}`);
+	const run = runFromRow(runResult.rows[0]);
+	const refreshedAt = toIso(materialized.rows[0]?.refreshed_at);
+	const asOf = latestIso(refreshedAt, run?.status === "success" ? run.completedAt : void 0);
+	const ttlMs = definition.refresh?.ttl;
+	const isStale = !asOf || ttlMs !== void 0 && now.getTime() - new Date(asOf).getTime() > ttlMs;
+	const lockExpiresAt = toIso(lockResult.rows[0]?.expires_at);
+	const lockHeld = Boolean(lockExpiresAt);
+	return {
+		version: 1,
+		state: run?.status === "skipped" ? "lock-skipped" : lockHeld ? "refreshing" : run?.status === "failed" ? "failed" : run?.status === "running" ? "stale" : isStale ? "stale" : "current",
+		...asOf ? { asOf } : {},
+		...refreshedAt ? { refreshedAt } : {},
+		hasUsableRows: Boolean(refreshedAt),
+		mode: run?.mode ?? definition.refresh?.mode ?? "rebuild",
+		...run ? { run } : {},
+		...run?.status === "failed" ? { failure: {
+			code: "refresh_failed",
+			retryable: true
+		} } : {},
+		lock: {
+			held: lockHeld,
+			...lockExpiresAt ? { expiresAt: lockExpiresAt } : {}
+		}
+	};
+}
+function actionContext(reportCtor, phase, mode, refreshAction) {
+	return {
+		phase,
+		reportClassName: canonicalClassName(reportCtor),
+		tenantScope: "ambient",
+		mode,
+		requiredPermission: refreshAction?.requiredPermission && refreshAction.requiredPermission.trim().length > 0 ? refreshAction.requiredPermission : "reports.refresh"
+	};
+}
+async function actionMode(reportCtor, requested) {
+	if (requested) return 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);
+	await options.host.authorize(action);
+	await options.host.audit(action);
+	return {
+		phase: "preview",
+		lifecycle: await getReportLifecycle(reportCtor, options),
+		action,
+		execution: "background"
+	};
+}
+async function applyReportRefresh(reportCtor, options) {
+	const mode = await actionMode(reportCtor, options.mode);
+	const action = actionContext(reportCtor, "apply", mode, options.refreshAction);
+	await options.host.authorize(action);
+	await options.host.audit(action);
+	const tenantId = lifecycleTenantId(reportCtor);
+	const enqueue = () => enqueueReportRefresh({
+		db: options.db,
+		reportClass: canonicalClassName(reportCtor),
+		mode,
+		trigger: "manual",
+		tenantId,
+		queue: options.queue,
+		priority: options.priority,
+		timeout: options.timeout,
+		maxAttempts: options.maxAttempts,
+		tenantJobCap: options.tenantJobCap
+	});
+	return {
+		phase: "apply",
+		job: jobHandle(tenantId === null && getTenantId() ? await withSystemContext(enqueue) : await enqueue())
+	};
+}
+function reportRefreshOutcome(result) {
+	const scopes = result.tenantResults ?? [result];
+	const lockSkippedScopes = scopes.filter((scope) => scope.skipped).length;
+	const completedScopes = scopes.length - lockSkippedScopes;
+	return {
+		state: scopes.length > 1 && lockSkippedScopes > 0 ? "partial" : lockSkippedScopes > 0 ? "lock-skipped" : "current",
+		rowCount: result.rowCount,
+		changedGroupCount: result.changedGroupCount ?? 0,
+		completedScopes,
+		lockSkippedScopes,
+		mode: result.mode,
+		refreshedAt: result.refreshedAt.toISOString(),
+		...result.runId ? { runId: result.runId } : {}
+	};
+}
+//#endregion
+//#region src/adapter.ts
+var SENSITIVITIES = /* @__PURE__ */ new Set([
+	"public",
+	"personal",
+	"sensitive",
+	"secret"
+]);
+function registeredClass(ctor) {
+	return ObjectRegistry.getClassByConstructor(ctor) ?? ObjectRegistry.getClass(ctor.name);
+}
+function fieldPolicy(field) {
+	const meta = field?._meta ?? {};
+	const sensitivity = [field?.sensitivity, meta.sensitivity].find((value) => typeof value === "string");
+	return {
+		sensitive: field?.sensitive === true || meta.sensitive === true || sensitivity === "sensitive" || sensitivity === "secret",
+		readPermission: typeof field?.readPermission === "string" ? field.readPermission : typeof meta.readPermission === "string" ? meta.readPermission : void 0
+	};
+}
+function descriptorMetadata(field) {
+	const metadata = field?._meta ?? {};
+	const format = [field?.format, metadata.format].find((value) => typeof value === "string" && value.length > 0);
+	const rawSensitivity = [field?.sensitivity, metadata.sensitivity].find((value) => typeof value === "string" && SENSITIVITIES.has(value));
+	return {
+		...format ? { format } : {},
+		...rawSensitivity ? { sensitivity: rawSensitivity } : {}
+	};
+}
+function labelFor(fieldName) {
+	return fieldName.replace(/([a-z\d])([A-Z])/g, "$1 $2").replace(/[_-]+/g, " ").replace(/^./, (value) => value.toUpperCase());
+}
+function queryType(type) {
+	switch (type) {
+		case "integer":
+		case "decimal": return "number";
+		case "boolean": return "boolean";
+		case "datetime": return "datetime";
+		case "json": return "json";
+		default: return "string";
+	}
+}
+function configuredTenantField(configured) {
+	return configured ? toSnakeCase(configured) : void 0;
+}
+function isColumnBackedField(field) {
+	if (!field) return false;
+	if (field.transient === true || field._meta?.transient === true) return false;
+	return ![
+		"meta",
+		"oneToMany",
+		"manyToMany"
+	].includes(field.type ?? "");
+}
+function reportColumn(field, registryField) {
+	const policy = fieldPolicy(registryField);
+	if (policy.sensitive || policy.readPermission || !isColumnBackedField(registryField)) return;
+	const id = field.columnName ?? toSnakeCase(field.fieldName);
+	const report = field.report;
+	if (!report) return void 0;
+	const type = queryType(field.type ?? registryField?.type);
+	const filterOperators = filterOperatorsFor(type);
+	return {
+		id,
+		fieldName: field.fieldName,
+		label: registryField?.description || labelFor(field.fieldName),
+		kind: report.kind,
+		filterScope: report.kind === "aggregate" ? "having" : "where",
+		type,
+		projectable: true,
+		sortable: true,
+		facetable: report.kind !== "aggregate",
+		...filterOperators ? { filterOperators } : {},
+		capabilities: [
+			"project",
+			"read",
+			...filterOperators ? ["filter"] : [],
+			"sort",
+			...report.kind !== "aggregate" ? ["facet"] : [],
+			...report.kind === "aggregate" ? ["aggregate"] : report.kind === "group" ? ["group"] : []
+		],
+		...report.kind === "group" ? { sourceColumn: toSnakeCase(report.sourceColumn ?? field.fieldName) } : {},
+		...report.kind === "bucket" ? {
+			bucket: report.unit,
+			sourceColumn: toSnakeCase(report.sourceColumn)
+		} : {},
+		...report.kind === "aggregate" ? {
+			aggregate: report.fn,
+			...report.column ? { sourceColumn: toSnakeCase(report.column) } : {},
+			...report.distinct === void 0 ? {} : { distinct: report.distinct }
+		} : {},
+		...descriptorMetadata(registryField)
+	};
+}
+function identityColumn() {
+	return {
+		id: "id",
+		fieldName: "id",
+		label: "ID",
+		kind: "identity",
+		filterScope: "where",
+		type: "string",
+		projectable: true,
+		sortable: true,
+		facetable: false,
+		filterOperators: filterOperatorsFor("string"),
+		capabilities: [
+			"project",
+			"read",
+			"filter",
+			"sort"
+		]
+	};
+}
+function toQueryField(column) {
+	return {
+		id: column.id,
+		type: column.type,
+		...column.projectable === void 0 ? {} : { projectable: column.projectable },
+		sortable: column.sortable === true,
+		facetable: column.facetable === true,
+		...column.filterOperators === void 0 ? {} : { filterOperators: [...column.filterOperators] }
+	};
+}
+function filterOperatorsFor(type) {
+	switch (type) {
+		case "string": return [
+			"eq",
+			"ne",
+			"gt",
+			"gte",
+			"lt",
+			"lte",
+			"in",
+			"notIn",
+			"like"
+		];
+		case "number":
+		case "datetime": return [
+			"eq",
+			"ne",
+			"gt",
+			"gte",
+			"lt",
+			"lte",
+			"in",
+			"notIn"
+		];
+		case "boolean": return [
+			"eq",
+			"ne",
+			"in",
+			"notIn"
+		];
+		case "json": return;
+	}
+}
+function refreshDescriptor(refresh, refreshPermission = "reports.refresh") {
+	const config = refresh ?? {};
+	const triggers = /* @__PURE__ */ new Set(["manual"]);
+	if (!config.manual) {
+		const hasSchedule = Boolean(config.schedule || config.fullRebuildSchedule);
+		const hasChangeTrigger = Boolean(config.onChange?.length);
+		if (hasSchedule) triggers.add("schedule");
+		if (hasChangeTrigger) triggers.add("change");
+		if (config.ttl !== void 0 && config.ttl > 0) triggers.add("ttl");
+		if (hasSchedule || hasChangeTrigger) triggers.add("job");
+	}
+	return {
+		mode: config.mode ?? "rebuild",
+		mayRefreshOnRead: config.ttl !== void 0 && config.ttl > 0 && !config.manual,
+		...config.ttl === void 0 ? {} : { ttlMs: config.ttl },
+		triggers: [...triggers],
+		action: {
+			id: "refresh",
+			label: "Refresh report",
+			scope: "surface",
+			phases: ["preview", "apply"],
+			requiresPermission: true,
+			requiredPermission: refreshPermission.trim().length > 0 ? refreshPermission : "reports.refresh",
+			auditRequired: true
+		}
+	};
+}
+function resourceId(definition, scope) {
+	return `${definition.reportClassName}#${scope ?? "current"}`;
+}
+var VALUE_FORMAT_ALIASES = {
+	text: "text",
+	date: "date",
+	datetime: "datetime",
+	"date-time": "datetime",
+	percentage: "percentage",
+	percent: "percentage",
+	count: "count",
+	money: "money",
+	currency: "money",
+	number: "number",
+	decimal: "number",
+	integer: "number"
+};
+var VALUE_FORMATS = new Set(Object.values(VALUE_FORMAT_ALIASES));
+var COLUMN_ROLES = /* @__PURE__ */ new Set([
+	"data",
+	"status",
+	"action"
+]);
+var STRUCTURAL_ROW_KINDS = /* @__PURE__ */ new Set([
+	"summary",
+	"subtotal",
+	"aggregate",
+	"footer"
+]);
+function valueFormat(column) {
+	const configured = column.format?.trim().toLowerCase();
+	if (configured && Object.hasOwn(VALUE_FORMAT_ALIASES, configured)) return VALUE_FORMAT_ALIASES[configured];
+	if (column.kind === "bucket") return column.bucket === "minute" || column.bucket === "hour" ? "datetime" : "date";
+	if (column.kind === "aggregate" && column.aggregate === "count") return "count";
+	if (column.type === "datetime") return "datetime";
+	if (column.type === "number") return "number";
+	return "text";
+}
+function headerPath(column) {
+	if (column.kind === "aggregate") return [{
+		id: "measures",
+		label: "Measures"
+	}, {
+		id: `aggregate:${column.aggregate ?? "value"}`,
+		label: labelFor(column.aggregate ?? "value")
+	}];
+	if (column.kind === "bucket") return [{
+		id: "dimensions",
+		label: "Dimensions"
+	}, {
+		id: "time",
+		label: "Time"
+	}];
+	if (column.kind === "group") return [{
+		id: "dimensions",
+		label: "Dimensions"
+	}, {
+		id: "groups",
+		label: "Groups"
+	}];
+	return [{
+		id: "dimensions",
+		label: "Dimensions"
+	}];
+}
+function responsive(column) {
+	if (column.kind === "group" || column.kind === "bucket") return {
+		priority: 100,
+		keepVisible: true
+	};
+	if (column.kind === "identity") return { priority: 80 };
+	return { priority: 20 };
+}
+function assertHeaderPath(columnId, path) {
+	if (!Array.isArray(path)) throw new TypeError(`Report DataTable headerPath for ${columnId} must be an array`);
+	return path.map((segment) => {
+		if (!segment || typeof segment.id !== "string" || segment.id.trim().length === 0 || typeof segment.label !== "string" || segment.label.trim().length === 0) throw new TypeError(`Report DataTable headerPath entries for ${columnId} require non-empty id and label`);
+		return {
+			id: segment.id,
+			label: segment.label
+		};
+	});
+}
+function dataTableColumn(column, override) {
+	const format = override?.valueFormat ?? valueFormat(column);
+	const path = override?.headerPath ?? headerPath(column);
+	if (!VALUE_FORMATS.has(format)) throw new TypeError(`Report DataTable valueFormat for ${column.id} is not supported: ${String(format)}`);
+	if (override?.role !== void 0 && !COLUMN_ROLES.has(override.role)) throw new TypeError(`Report DataTable role for ${column.id} is not supported: ${String(override.role)}`);
+	if (override?.label !== void 0 && (typeof override.label !== "string" || override.label.trim().length === 0)) throw new TypeError(`Report DataTable label for ${column.id} must not be empty`);
+	if (override?.align !== void 0 && override.align !== "left" && override.align !== "right") throw new TypeError(`Report DataTable align for ${column.id} is not supported: ${String(override.align)}`);
+	if (override?.responsive?.priority !== void 0 && (!Number.isFinite(override.responsive.priority) || override.responsive.priority < 0)) throw new TypeError(`Report DataTable responsive priority for ${column.id} must be a non-negative finite number`);
+	if (override?.responsive?.keepVisible !== void 0 && typeof override.responsive.keepVisible !== "boolean") throw new TypeError(`Report DataTable keepVisible for ${column.id} must be a boolean`);
+	return {
+		id: column.id,
+		label: override?.label ?? column.label,
+		accessor: column.id,
+		sortable: column.sortable === true,
+		searchable: false,
+		filterable: column.filterOperators !== void 0,
+		headerPath: assertHeaderPath(column.id, path),
+		valueFormat: format,
+		align: override?.align ?? ([
+			"count",
+			"money",
+			"number",
+			"percentage"
+		].includes(format) ? "right" : "left"),
+		role: override?.role ?? "data",
+		responsive: {
+			...responsive(column),
+			...override?.responsive
+		}
+	};
+}
+function structuralRows(columnIds, rows = []) {
+	const ids = /* @__PURE__ */ new Set();
+	return rows.map((row) => {
+		if (!row || typeof row.id !== "string" || row.id.trim().length === 0 || typeof row.label !== "string" || row.label.trim().length === 0) throw new TypeError("Report structural rows require non-empty id and label values");
+		if (ids.has(row.id)) throw new TypeError(`Report structural row id must be unique: ${row.id}`);
+		if (!STRUCTURAL_ROW_KINDS.has(row.kind)) throw new TypeError(`Report structural row kind is not supported: ${String(row.kind)}`);
+		if (row.labelColumnId !== void 0) {
+			if (typeof row.labelColumnId !== "string" || row.labelColumnId.trim().length === 0 || !columnIds.has(row.labelColumnId)) throw new TypeError(`Report structural row labelColumnId must name an adapter column: ${String(row.labelColumnId)}`);
+		}
+		if (row.values !== void 0 && (typeof row.values !== "object" || row.values === null || Array.isArray(row.values))) throw new TypeError("Report structural row values must be an object");
+		if (row.values && Object.keys(row.values).some((columnId) => !columnIds.has(columnId))) throw new TypeError("Report structural row values must use adapter column ids");
+		ids.add(row.id);
+		return {
+			id: row.id,
+			kind: row.kind,
+			label: row.label,
+			...row.values !== void 0 ? { values: jsonSafeValue(row.values) } : {},
+			...row.labelColumnId !== void 0 ? { labelColumnId: row.labelColumnId } : {},
+			selection: "excluded",
+			actions: "excluded"
+		};
+	});
+}
+function drilldownDescriptor(columns, sourceClassName) {
+	return {
+		id: "drilldown",
+		sourceClassName,
+		fields: columns.filter((column) => (column.kind === "group" || column.kind === "bucket") && typeof column.sourceColumn === "string").map((column) => ({
+			id: column.id,
+			sourceColumn: column.sourceColumn,
+			kind: column.kind,
+			...column.kind === "bucket" && column.bucket ? { bucket: column.bucket } : {}
+		})),
+		inherits: [
+			"principal",
+			"tenant",
+			"report-definition",
+			"field-policy"
+		]
+	};
+}
+async function buildReportAdapterDescriptor(reportCtor, options = {}) {
+	const definition = await buildReportDefinition(reportCtor);
+	const registered = registeredClass(reportCtor);
+	const fields = await ObjectRegistry.getAllFields(definition.reportClassName);
+	const tenantField = configuredTenantField(registered?.tenantScopedConfig?.field);
+	const columns = [identityColumn(), ...definition.fields.map((field) => reportColumn(field, fields.get(field.fieldName))).filter((field) => Boolean(field))].sort((left, right) => left.id.localeCompare(right.id));
+	const schema = {
+		version: 1,
+		identityField: "id",
+		fields: columns.map(toQueryField),
+		defaultSort: [{
+			field: "id",
+			direction: "asc"
+		}],
+		supports: {
+			cursorPagination: false,
+			consistency: false,
+			facets: true
+		}
+	};
+	const dataTable = {
+		rowKey: "id",
+		manualPagination: true,
+		manualSorting: true,
+		enableFiltering: true,
+		enableSearch: false,
+		columns: columns.map((column) => dataTableColumn(column, options.dataTable?.columns?.[column.id])),
+		structuralRows: structuralRows(new Set(columns.map((column) => column.id)), options.dataTable?.structuralRows)
+	};
+	return {
+		version: 1,
+		resourceId: resourceId(definition, options.tenantScope),
+		reportClassName: definition.reportClassName,
+		sourceClassName: definition.sourceClassName,
+		tenantScoped: Boolean(registered?.tenantScopedConfig),
+		...tenantField ? { tenantField } : {},
+		identityField: "id",
+		columns,
+		schema,
+		queryExecution: {
+			modes: [
+				"visible",
+				"background",
+				"silent"
+			],
+			visible: { delivery: "result" },
+			background: {
+				delivery: "queued",
+				requiresHost: true
+			},
+			silent: {
+				delivery: "result",
+				mutatesVisibleSurface: false
+			}
+		},
+		dataTable,
+		drilldown: drilldownDescriptor(columns, definition.sourceClassName),
+		refresh: refreshDescriptor(definition.refresh, options.refreshPermission)
+	};
+}
+function publicFieldMap(descriptor) {
+	return new Map(descriptor.columns.map((column) => [column.id, column.fieldName]));
+}
+async function buildReportDrilldownQuery(reportCtor, row, options = {}) {
+	const descriptor = await buildReportAdapterDescriptor(reportCtor, options);
+	const constraints = descriptor.drilldown.fields.map((field) => {
+		if (!Object.hasOwn(row, field.id)) throw new DataQueryValidationError(`Report drilldown row is missing grouping field: ${field.id}`, "DATA_QUERY_RESULT_INVALID");
+		return {
+			id: field.id,
+			sourceColumn: field.sourceColumn,
+			kind: field.kind,
+			value: jsonSafeValue(row[field.id]),
+			...field.bucket ? { bucket: field.bucket } : {}
+		};
+	});
+	return {
+		version: 1,
+		resourceId: descriptor.resourceId,
+		reportClassName: descriptor.reportClassName,
+		sourceClassName: descriptor.drilldown.sourceClassName,
+		constraints,
+		inherits: [...descriptor.drilldown.inherits]
+	};
+}
+var MAX_REPORT_FILTER_OR_GROUPS = 128;
+function reportFilterError(message) {
+	throw new DataQueryValidationError(message, "DATA_QUERY_UNSUPPORTED");
+}
+function crossProductWhere(left, right) {
+	if (left.length * right.length > MAX_REPORT_FILTER_OR_GROUPS) return reportFilterError(`Report filter expands beyond ${MAX_REPORT_FILTER_OR_GROUPS} OR groups`);
+	return left.flatMap((leftGroup) => right.map((rightGroup) => [...leftGroup, ...rightGroup]));
+}
+function inverseOperator(operator) {
+	switch (operator) {
+		case "eq": return "ne";
+		case "ne": return "eq";
+		case "gt": return "lte";
+		case "gte": return "lt";
+		case "lt": return "gte";
+		case "lte": return "gt";
+		case "in": return "notIn";
+		case "notIn": return "in";
+		case "like": return reportFilterError("Report filters do not support negating a LIKE predicate");
+	}
+}
+function collectionCondition(field, operator, value) {
+	const keyFor = (suffix2) => suffix2 ? `${field} ${suffix2}` : field;
+	const scalar = (key, scalarValue) => [[{ [key]: scalarValue }]];
+	if (operator === "in") {
+		const values = value;
+		const nonNull = values.filter((entry) => entry !== null);
+		if (nonNull.length === 0) return scalar(field, null);
+		if (nonNull.length === values.length) return scalar(keyFor("in"), nonNull);
+		return [[{ [field]: null }], [{ [keyFor("in")]: nonNull }]];
+	}
+	if (operator === "notIn") return [value.map((entry) => ({ [keyFor("!=")]: entry }))];
+	return scalar(keyFor({
+		eq: "",
+		ne: "!=",
+		gt: ">",
+		gte: ">=",
+		lt: "<",
+		lte: "<=",
+		like: "like"
+	}[operator]), value);
+}
+function materializedWhereForFilter(filter, fields, negate = false) {
+	if (filter.kind === "condition") {
+		const field = fields.get(filter.field);
+		if (!field) return reportFilterError(`Report filter field is not declared: ${filter.field}`);
+		return collectionCondition(field, negate ? inverseOperator(filter.operator) : filter.operator, filter.value);
+	}
+	if (filter.kind === "not") return materializedWhereForFilter(filter.filter, fields, !negate);
+	if (filter.kind === "all" && !negate || filter.kind === "any" && negate) return filter.filters.reduce((combined, child) => crossProductWhere(combined, materializedWhereForFilter(child, fields, negate)), [[]]);
+	const groups = filter.filters.flatMap((child) => materializedWhereForFilter(child, fields, negate));
+	if (groups.length > MAX_REPORT_FILTER_OR_GROUPS) return reportFilterError(`Report filter expands beyond ${MAX_REPORT_FILTER_OR_GROUPS} OR groups`);
+	return groups;
+}
+function materializedWhere(filter, fields) {
+	return filter ? materializedWhereForFilter(filter, fields) : void 0;
+}
+function filterScopeForColumn(column) {
+	return column.filterScope;
+}
+function splitReportFilterScopes(descriptor, filter) {
+	if (!filter) return {};
+	const columns = new Map(descriptor.columns.map((column) => [column.id, column]));
+	const combineAll = (filters) => {
+		const flattened = filters.flatMap((candidate) => candidate.kind === "all" ? candidate.filters : [candidate]);
+		return flattened.length === 0 ? void 0 : flattened.length === 1 ? flattened[0] : {
+			kind: "all",
+			filters: flattened
+		};
+	};
+	const split = (candidate) => {
+		if (candidate.kind === "condition") {
+			const column = columns.get(candidate.field);
+			if (!column) reportFilterError(`Report filter field is not declared: ${candidate.field}`);
+			return filterScopeForColumn(column) === "where" ? { where: candidate } : { having: candidate };
+		}
+		if (candidate.kind === "all") {
+			const children2 = candidate.filters.map(split);
+			const where = combineAll(children2.flatMap((child) => child.where ? [child.where] : []));
+			const having = combineAll(children2.flatMap((child) => child.having ? [child.having] : []));
+			return {
+				...where ? { where } : {},
+				...having ? { having } : {}
+			};
+		}
+		const children = candidate.kind === "not" ? [split(candidate.filter)] : candidate.filters.map(split);
+		const scopes = new Set(children.flatMap((child) => [...child.where ? ["where"] : [], ...child.having ? ["having"] : []]));
+		if (scopes.size !== 1) reportFilterError("Report WHERE and HAVING filters cannot be mixed inside one OR or NOT expression");
+		const scope = scopes.has("where") ? "where" : "having";
+		const filters = children.flatMap((child) => {
+			const filter2 = scope === "where" ? child.where : child.having;
+			return filter2 ? [filter2] : [];
+		});
+		if (candidate.kind === "not") {
+			const [filter2] = filters;
+			if (!filter2) reportFilterError("Report NOT expressions must contain one filter");
+			return scope === "where" ? { where: {
+				kind: "not",
+				filter: filter2
+			} } : { having: {
+				kind: "not",
+				filter: filter2
+			} };
+		}
+		return scope === "where" ? { where: {
+			kind: "any",
+			filters
+		} } : { having: {
+			kind: "any",
+			filters
+		} };
+	};
+	return split(filter);
+}
+function jsonSafeValue(value, ancestors = /* @__PURE__ */ new WeakSet()) {
+	if (value instanceof Date) return value.toISOString();
+	if (typeof value === "bigint") {
+		const numeric = Number(value);
+		if (!Number.isSafeInteger(numeric)) throw new RangeError("Materialized bigint values must be safely representable as numbers");
+		return numeric;
+	}
+	if (value && typeof value === "object") {
+		if (ancestors.has(value)) throw new TypeError("Values must not contain circular references");
+		ancestors.add(value);
+		try {
+			if (Array.isArray(value)) return value.map((entry) => jsonSafeValue(entry, ancestors));
+			return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, jsonSafeValue(entry, ancestors)]));
+		} finally {
+			ancestors.delete(value);
+		}
+	}
+	return value;
+}
+function mapMaterializedRow(row, projection, fieldMap) {
+	const mapped = {};
+	for (const id of projection) {
+		const sourceField = fieldMap.get(id) ?? id;
+		if (sourceField in row) mapped[id] = jsonSafeValue(row[sourceField]);
+	}
+	return mapped;
+}
+function queryFreshness(lifecycle) {
+	switch (lifecycle.state) {
+		case "current": return {
+			state: "fresh",
+			...lifecycle.asOf ? { asOf: lifecycle.asOf } : {}
+		};
+		case "stale":
+		case "lock-skipped":
+		case "failed": return {
+			state: "stale",
+			...lifecycle.asOf ? { asOf: lifecycle.asOf } : {}
+		};
+		case "refreshing": return lifecycle.hasUsableRows ? {
+			state: "stale",
+			...lifecycle.asOf ? { asOf: lifecycle.asOf } : {}
+		} : { state: "unknown" };
+	}
+}
+async function queryReportMaterializedRows(reportCtor, input, options = {}) {
+	const descriptor = await buildReportAdapterDescriptor(reportCtor);
+	const request = normalizeDataQueryRequest(input, descriptor.schema);
+	splitReportFilterScopes(descriptor, request.filter);
+	const queryFingerprint = createDataQueryFingerprint(request, descriptor.schema);
+	if (options.execution === "background") {
+		const queued = await options.enqueueBackgroundQuery({
+			version: 1,
+			execution: "background",
+			resourceId: descriptor.resourceId,
+			reportClassName: descriptor.reportClassName,
+			request,
+			inherits: [
+				"principal",
+				"tenant",
+				"report-definition",
+				"field-policy"
+			]
+		});
+		if (typeof queued.taskId !== "string" || queued.taskId.length === 0) throw new Error("Background report query hosts must return a task id");
+		return {
+			version: 1,
+			execution: "background",
+			status: "queued",
+			taskId: queued.taskId,
+			queryFingerprint
+		};
+	}
+	const execution = options.execution ?? "visible";
+	const lifecycleDb = options.db;
+	if (options.lifecycle && !lifecycleDb) throw new Error("Report lifecycle disclosure requires a database handle");
+	const lifecycleOptions = options.lifecycle && lifecycleDb ? {
+		db: lifecycleDb,
+		...options.lifecycle
+	} : void 0;
+	const lifecycleBefore = lifecycleOptions ? await getReportLifecycle(reportCtor, lifecycleOptions) : void 0;
+	const fieldMap = publicFieldMap(descriptor);
+	const where = materializedWhere(request.filter, fieldMap);
+	const collection = options.collection ?? await ObjectRegistry.getCollection(descriptor.reportClassName, { db: options.db });
+	let rows = [];
+	let page;
+	let total;
+	let facets;
+	if (request.mode === "rows") {
+		const projection = request.projection ?? [descriptor.identityField];
+		const select = projection.map((id) => fieldMap.get(id) ?? id);
+		const offset = request.page?.kind === "offset" ? request.page.offset : 0;
+		const limit = request.page?.limit ?? 50;
+		const orderBy = request.sort?.map(({ field, direction }) => `${fieldMap.get(field) ?? field} ${direction.toUpperCase()}`);
+		rows = (await collection.list({
+			select,
+			offset,
+			limit,
+			orderBy: orderBy?.length === 1 ? orderBy[0] : orderBy,
+			...where === void 0 ? {} : { where }
+		})).map((row) => mapMaterializedRow(row, projection, fieldMap));
+		rows.forEach((row) => {
+			if (typeof row.id !== "string" || row.id.length === 0) throw new Error("Materialized report rows require a non-empty string id");
+		});
+		total = await collection.count(where === void 0 ? void 0 : { where });
+		page = {
+			kind: "offset",
+			offset,
+			limit,
+			hasMore: offset + rows.length < total
+		};
+	} else {
+		await collection.list({
+			select: ["id"],
+			offset: 0,
+			limit: 1,
+			orderBy: "id ASC",
+			...where === void 0 ? {} : { where }
+		});
+		total = await collection.count(where === void 0 ? void 0 : { where });
+		if (request.mode === "facets") {
+			if (!collection.facets) throw new Error("Report materialized facet reads require a collection facets() implementation");
+			const requested = request.facets ?? [];
+			const sourceFacets = await collection.facets({
+				fields: requested.map((facet) => ({
+					field: fieldMap.get(facet.field) ?? facet.field,
+					limit: facet.limit
+				})),
+				...where === void 0 ? {} : { where }
+			});
+			const byField = new Map(sourceFacets.map((facet) => [facet.field, facet]));
+			facets = requested.map((facet) => {
+				const sourceField = fieldMap.get(facet.field) ?? facet.field;
+				const values = byField.get(sourceField)?.values ?? [];
+				return {
+					field: facet.field,
+					values: values.map((value) => ({
+						value: value.value,
+						count: value.count
+					})),
+					truncated: values.length >= facet.limit
+				};
+			});
+		}
+	}
+	const normalized = normalizeDataQueryResult({
+		version: 1,
+		requestId: request.requestId,
+		queryFingerprint,
+		identityField: descriptor.identityField,
+		rows,
+		...page ? { page } : {},
+		total: {
+			kind: "exact",
+			value: total
+		},
+		...facets === void 0 ? {} : { facets },
+		freshness: { state: "unknown" },
+		warnings: [],
+		truncated: false
+	}, request, descriptor.schema);
+	if (!lifecycleBefore || !lifecycleOptions) return {
+		...normalized,
+		execution
+	};
+	const lifecycleAfter = await getReportLifecycle(reportCtor, lifecycleOptions);
+	return {
+		...normalized,
+		execution,
+		freshness: queryFreshness(lifecycleAfter),
+		reportLifecycle: {
+			snapshot: lifecycleAfter,
+			read: lifecycleBefore.state !== "current" && lifecycleAfter.state === "current" ? "refresh-triggered" : lifecycleAfter.state === "current" ? "current" : "stale"
+		}
+	};
+}
+function reportMaterializedRowKey(row) {
+	const id = row.id;
+	if (typeof id !== "string" || id.length === 0) throw new Error("Materialized report rows require a non-empty string id");
+	return id;
+}
+//#endregion
 //#region src/report.ts
 function registryColumnName(fieldName, field) {
 	return validateColumnName(field?.columnName ?? field?._meta?.columnName ?? toSnakeCase(fieldName));
@@ -85,6 +988,6 @@ 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, assertReportTablesReady, avg, bucketExpr, buildAggregate, buildReportDefinition, compileReportDefinition, compileReportSpec, count, day, enqueueReportRefresh, ensureReportRefreshSchedules, getReportGroupingColumns, getRuntimeReportOptions, groupBy, hour, max, min, minute, month, quarter, refreshReport, registerReportRefreshInterceptor, report, reportRowIdentity, scopeKeyForTenant, sum, week, year };
+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 };
 
 //# sourceMappingURL=index.js.map