@happyvertical/smrt-reports 0.55.6 → 0.55.8

package/dist/index.js

@@ -1,12 +1,12 @@
 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 { adapterTypeFromDb, refreshReport, reportRowIdentity, tenantColumn } from "./refresh.js";
 import { ReportScheduleRunner, SmrtPrincipalReportRefreshTask, SmrtReportRefreshTask, enqueueReportRefresh, ensureReportRefreshSchedules, registerReportRefreshExecutionAuthorityHost, registerReportRefreshInterceptor, registerReportRefreshJobIntegritySigner } from "./scheduler.js";
 import { bucketExpr, buildAggregate } from "./aggregate.js";
-import { DataQueryValidationError, ObjectRegistry, SmrtCollection, SmrtObject, createDataQueryFingerprint, normalizeDataQueryRequest, normalizeDataQueryResult } from "@happyvertical/smrt-core";
+import { DataQueryValidationError, ObjectRegistry, SmrtCollection, SmrtObject, SmrtRecipe, createDataQueryFingerprint, field, normalizeDataQueryRequest, normalizeDataQueryResult, smrt } from "@happyvertical/smrt-core";
 import { toSnakeCase } from "@happyvertical/smrt-core/utils";
-import { getTenantId, withSystemContext } from "@happyvertical/smrt-tenancy";
+import { TenantScoped, getTenantId, isTenancyEnabled, isTenantScopedClass, tenantId, withSystemContext } from "@happyvertical/smrt-tenancy";
 import { tableExists, validateColumnName } from "@happyvertical/sql";
 import { createHash } from "node:crypto";
 //#region src/lifecycle.ts
@@ -918,6 +918,32 @@ function reportMaterializedRowKey(row) {
 	return id;
 }
 //#endregion
+//#region src/recipes.ts
+var MaterializedReportsRecipe = class extends SmrtRecipe {
+	static id = "reports.materialized";
+	static help = "./materialized.recipe.md";
+	static label = "Reports";
+	static summary = "Keep totals and trends ready to read, refreshed on a schedule and open to the assistant.";
+	static synonyms = [
+		"reports",
+		"totals",
+		"summaries",
+		"rollups",
+		"kpis",
+		"trends",
+		"dashboards"
+	];
+	static models = [
+		SmrtReportRun,
+		SmrtReportWatermark,
+		SmrtReportLock,
+		SmrtReportSchedule,
+		SmrtReportRefreshTask,
+		SmrtPrincipalReportRefreshTask
+	];
+	static runtime = "server";
+};
+//#endregion
 //#region src/report.ts
 function registryColumnName(fieldName, field) {
 	return validateColumnName(field?.columnName ?? field?._meta?.columnName ?? toSnakeCase(fieldName));
@@ -995,6 +1021,971 @@ var SmrtReportCollection = class extends SmrtCollection {
 	}
 };
 //#endregion
+//#region src/runtime-spec.ts
+var RUNTIME_REPORT_SPEC_VERSION = 1;
+var RUNTIME_REPORT_LIMITS = Object.freeze({
+	maxTitleLength: 120,
+	maxDescriptionLength: 500,
+	maxDimensions: 4,
+	maxMeasures: 6,
+	maxFilters: 12,
+	maxHaving: 4,
+	maxSort: 3,
+	maxInValues: 100,
+	maxStringValueLength: 256,
+	defaultRowLimit: 100,
+	maxRowLimit: 1e3,
+	maxAliasLength: 40,
+	maxFieldNameLength: 64,
+	maxSourceIdLength: 120
+});
+var RUNTIME_REPORT_BUCKETS = [
+	"minute",
+	"hour",
+	"day",
+	"week",
+	"month",
+	"quarter",
+	"year"
+];
+var RUNTIME_REPORT_MEASURE_FNS = [
+	"count",
+	"countDistinct",
+	"sum",
+	"avg",
+	"min",
+	"max"
+];
+var RUNTIME_REPORT_FILTER_OPS = [
+	"eq",
+	"ne",
+	"gt",
+	"gte",
+	"lt",
+	"lte",
+	"in",
+	"notIn",
+	"contains",
+	"isNull",
+	"isNotNull"
+];
+var RUNTIME_REPORT_HAVING_OPS = [
+	"eq",
+	"ne",
+	"gt",
+	"gte",
+	"lt",
+	"lte"
+];
+var RUNTIME_REPORT_CHART_TYPES = [
+	"table",
+	"bar",
+	"line",
+	"pie",
+	"stat"
+];
+var RuntimeReportError = class extends Error {
+	code;
+	path;
+	/**
+	* HTTP-style status so tool loops classify it: 4xx input problems are
+	* repairable by the caller, `tenant_required` and `confirmation_required`
+	* are denials, results that cannot be represented are server errors.
+	*/
+	status;
+	constructor(code, path, message) {
+		super(path ? `${path}: ${message}` : message);
+		this.name = "RuntimeReportError";
+		this.code = code;
+		this.path = path;
+		this.status = code === "tenant_required" || code === "confirmation_required" ? 403 : code === "invalid_result" ? 500 : 422;
+	}
+};
+function fail$1(path, message) {
+	throw new RuntimeReportError("invalid_spec", path, message);
+}
+var RESERVED_ALIASES = /* @__PURE__ */ new Set([
+	"all",
+	"and",
+	"as",
+	"asc",
+	"between",
+	"by",
+	"case",
+	"cast",
+	"check",
+	"column",
+	"constraint",
+	"create",
+	"cross",
+	"default",
+	"delete",
+	"desc",
+	"distinct",
+	"drop",
+	"else",
+	"end",
+	"except",
+	"exists",
+	"false",
+	"for",
+	"foreign",
+	"from",
+	"full",
+	"group",
+	"having",
+	"in",
+	"inner",
+	"insert",
+	"intersect",
+	"into",
+	"is",
+	"join",
+	"left",
+	"like",
+	"limit",
+	"natural",
+	"not",
+	"null",
+	"offset",
+	"on",
+	"or",
+	"order",
+	"outer",
+	"primary",
+	"references",
+	"right",
+	"select",
+	"set",
+	"table",
+	"then",
+	"to",
+	"true",
+	"union",
+	"unique",
+	"update",
+	"user",
+	"using",
+	"values",
+	"when",
+	"where",
+	"with"
+]);
+var ALIAS_PATTERN = /^[a-z][a-z0-9_]*$/;
+var FIELD_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/;
+var SOURCE_PATTERN = /^[A-Za-z@][A-Za-z0-9_@./:-]*$/;
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+}
+function strictObject(value, path, allowed) {
+	if (!isRecord(value)) fail$1(path, "must be an object");
+	for (const key of Object.keys(value)) if (!allowed.includes(key)) fail$1(`${path}.${key}`, "is not a known key");
+	return value;
+}
+function strictArray(value, path, max, min = 0) {
+	if (value === void 0) return [];
+	if (!Array.isArray(value)) fail$1(path, "must be an array");
+	if (value.length > max) fail$1(path, `must have at most ${max} entries`);
+	if (value.length < min) fail$1(path, `must have at least ${min} entries`);
+	return value;
+}
+function text(value, path, max, options = {}) {
+	if (typeof value !== "string") {
+		if (options.optional && value === void 0) return "";
+		fail$1(path, "must be a string");
+	}
+	const trimmed = value.trim();
+	if (trimmed.length === 0 && !options.optional) fail$1(path, "must not be empty");
+	if (trimmed.length > max) fail$1(path, `must be at most ${max} characters`);
+	if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(trimmed)) fail$1(path, "must not contain control characters");
+	return trimmed;
+}
+function oneOf(value, path, allowed) {
+	if (typeof value !== "string" || !allowed.includes(value)) fail$1(path, `must be one of: ${allowed.join(", ")}`);
+	return value;
+}
+function fieldName(value, path) {
+	if (typeof value !== "string") fail$1(path, "must be a string");
+	if (value.length === 0 || value.length > RUNTIME_REPORT_LIMITS.maxFieldNameLength || !FIELD_PATTERN.test(value)) fail$1(path, "must be a plain field name (letters, digits, underscore)");
+	return value;
+}
+function alias(value, path) {
+	if (typeof value !== "string") fail$1(path, "must be a string");
+	if (value.length === 0 || value.length > RUNTIME_REPORT_LIMITS.maxAliasLength || !ALIAS_PATTERN.test(value)) fail$1(path, `must be a lowercase identifier of at most ${RUNTIME_REPORT_LIMITS.maxAliasLength} characters (a-z, 0-9, underscore)`);
+	if (RESERVED_ALIASES.has(value)) fail$1(path, `'${value}' is a reserved word`);
+	return value;
+}
+function scalar(value, path) {
+	if (typeof value === "string") {
+		if (value.length > RUNTIME_REPORT_LIMITS.maxStringValueLength) fail$1(path, `must be at most ${RUNTIME_REPORT_LIMITS.maxStringValueLength} characters`);
+		if (value.includes("\0")) fail$1(path, "must not contain NUL");
+		return value;
+	}
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) fail$1(path, "must be a finite number");
+		return value;
+	}
+	if (typeof value === "boolean") return value;
+	return fail$1(path, "must be a string, number or boolean");
+}
+function snake(name) {
+	return name.replace(/([a-z\d])([A-Z])/g, "$1_$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2").toLowerCase();
+}
+function parseDimension(value, path) {
+	const raw = strictObject(value, path, [
+		"field",
+		"as",
+		"bucket"
+	]);
+	const field = fieldName(raw.field, `${path}.field`);
+	const bucket = raw.bucket === void 0 ? void 0 : oneOf(raw.bucket, `${path}.bucket`, RUNTIME_REPORT_BUCKETS);
+	return {
+		field,
+		as: raw.as === void 0 ? alias(bucket ? `${snake(field)}_${bucket}` : snake(field), `${path}.as`) : alias(raw.as, `${path}.as`),
+		...bucket ? { bucket } : {}
+	};
+}
+function parseMeasure(value, path) {
+	const raw = strictObject(value, path, [
+		"fn",
+		"field",
+		"as"
+	]);
+	const fn = oneOf(raw.fn, `${path}.fn`, RUNTIME_REPORT_MEASURE_FNS);
+	const field = raw.field === void 0 ? void 0 : fieldName(raw.field, `${path}.field`);
+	if (!field && fn !== "count") fail$1(`${path}.field`, `is required for ${fn}`);
+	const as = raw.as === void 0 ? alias(field ? `${snake(fn)}_${snake(field)}` : "row_count", `${path}.as`) : alias(raw.as, `${path}.as`);
+	return {
+		fn,
+		...field ? { field } : {},
+		as
+	};
+}
+function parseFilter(value, path) {
+	const raw = strictObject(value, path, [
+		"field",
+		"op",
+		"value"
+	]);
+	const field = fieldName(raw.field, `${path}.field`);
+	const op = oneOf(raw.op, `${path}.op`, RUNTIME_REPORT_FILTER_OPS);
+	if (op === "isNull" || op === "isNotNull") {
+		if (raw.value !== void 0) fail$1(`${path}.value`, `must be omitted for ${op}`);
+		return {
+			field,
+			op
+		};
+	}
+	if (raw.value === void 0) fail$1(`${path}.value`, `is required for ${op}`);
+	if (op === "in" || op === "notIn") return {
+		field,
+		op,
+		value: strictArray(raw.value, `${path}.value`, RUNTIME_REPORT_LIMITS.maxInValues, 1).map((entry, index) => scalar(entry, `${path}.value[${index}]`))
+	};
+	if (Array.isArray(raw.value)) fail$1(`${path}.value`, `must be a scalar for ${op}`);
+	const parsed = scalar(raw.value, `${path}.value`);
+	if (op === "contains" && typeof parsed !== "string") fail$1(`${path}.value`, "must be a string for contains");
+	return {
+		field,
+		op,
+		value: parsed
+	};
+}
+function parseHaving(value, path) {
+	const raw = strictObject(value, path, [
+		"measure",
+		"op",
+		"value"
+	]);
+	const measure = alias(raw.measure, `${path}.measure`);
+	const op = oneOf(raw.op, `${path}.op`, RUNTIME_REPORT_HAVING_OPS);
+	if (typeof raw.value !== "number" || !Number.isFinite(raw.value)) fail$1(`${path}.value`, "must be a finite number");
+	return {
+		measure,
+		op,
+		value: raw.value
+	};
+}
+function parseSort(value, path) {
+	const raw = strictObject(value, path, ["by", "direction"]);
+	return {
+		by: alias(raw.by, `${path}.by`),
+		direction: raw.direction === void 0 ? "asc" : oneOf(raw.direction, `${path}.direction`, ["asc", "desc"])
+	};
+}
+function parseRuntimeReportSpec(input) {
+	let candidate = input;
+	if (typeof input === "string") {
+		if (input.length > 64 * 1024) fail$1("", "spec JSON is too large");
+		try {
+			candidate = JSON.parse(input);
+		} catch {
+			fail$1("", "spec is not valid JSON");
+		}
+	}
+	const raw = strictObject(candidate, "spec", [
+		"version",
+		"title",
+		"description",
+		"source",
+		"dimensions",
+		"measures",
+		"filters",
+		"having",
+		"sort",
+		"limit",
+		"chart"
+	]);
+	if (raw.version !== void 0 && raw.version !== 1) fail$1("spec.version", `unsupported version (expected 1)`);
+	const title = text(raw.title, "spec.title", RUNTIME_REPORT_LIMITS.maxTitleLength);
+	const description = text(raw.description, "spec.description", RUNTIME_REPORT_LIMITS.maxDescriptionLength, { optional: true });
+	if (typeof raw.source !== "string" || raw.source.length === 0 || raw.source.length > RUNTIME_REPORT_LIMITS.maxSourceIdLength || !SOURCE_PATTERN.test(raw.source)) fail$1("spec.source", "must be a source id");
+	const dimensions = strictArray(raw.dimensions, "spec.dimensions", RUNTIME_REPORT_LIMITS.maxDimensions).map((entry, index) => parseDimension(entry, `spec.dimensions[${index}]`));
+	const measures = strictArray(raw.measures, "spec.measures", RUNTIME_REPORT_LIMITS.maxMeasures, 1).map((entry, index) => parseMeasure(entry, `spec.measures[${index}]`));
+	const filters = strictArray(raw.filters, "spec.filters", RUNTIME_REPORT_LIMITS.maxFilters).map((entry, index) => parseFilter(entry, `spec.filters[${index}]`));
+	const having = strictArray(raw.having, "spec.having", RUNTIME_REPORT_LIMITS.maxHaving).map((entry, index) => parseHaving(entry, `spec.having[${index}]`));
+	const sort = strictArray(raw.sort, "spec.sort", RUNTIME_REPORT_LIMITS.maxSort).map((entry, index) => parseSort(entry, `spec.sort[${index}]`));
+	const dimensionAliases = /* @__PURE__ */ new Set();
+	const measureAliases = /* @__PURE__ */ new Set();
+	const seen = /* @__PURE__ */ new Set();
+	for (const [index, dimension] of dimensions.entries()) {
+		if (seen.has(dimension.as)) fail$1(`spec.dimensions[${index}].as`, `duplicate alias '${dimension.as}'`);
+		seen.add(dimension.as);
+		dimensionAliases.add(dimension.as);
+	}
+	for (const [index, measure] of measures.entries()) {
+		if (seen.has(measure.as)) fail$1(`spec.measures[${index}].as`, `duplicate alias '${measure.as}'`);
+		seen.add(measure.as);
+		measureAliases.add(measure.as);
+	}
+	for (const [index, entry] of having.entries()) if (!measureAliases.has(entry.measure)) fail$1(`spec.having[${index}].measure`, "must be a declared measure alias");
+	for (const [index, entry] of sort.entries()) if (!seen.has(entry.by)) fail$1(`spec.sort[${index}].by`, "must be a declared dimension or measure alias");
+	let limit = RUNTIME_REPORT_LIMITS.defaultRowLimit;
+	if (raw.limit !== void 0) {
+		if (typeof raw.limit !== "number" || !Number.isSafeInteger(raw.limit) || raw.limit < 1 || raw.limit > RUNTIME_REPORT_LIMITS.maxRowLimit) fail$1("spec.limit", `must be an integer between 1 and ${RUNTIME_REPORT_LIMITS.maxRowLimit}`);
+		limit = raw.limit;
+	}
+	let chart = { type: "table" };
+	if (raw.chart !== void 0) {
+		const rawChart = strictObject(raw.chart, "spec.chart", [
+			"type",
+			"x",
+			"y"
+		]);
+		const type = oneOf(rawChart.type, "spec.chart.type", RUNTIME_REPORT_CHART_TYPES);
+		const x = rawChart.x === void 0 ? void 0 : alias(rawChart.x, "spec.chart.x");
+		if (x !== void 0 && !dimensionAliases.has(x)) fail$1("spec.chart.x", "must be a declared dimension alias");
+		const y = strictArray(rawChart.y, "spec.chart.y", RUNTIME_REPORT_LIMITS.maxMeasures).map((entry, index) => alias(entry, `spec.chart.y[${index}]`));
+		for (const [index, name] of y.entries()) if (!measureAliases.has(name)) fail$1(`spec.chart.y[${index}]`, "must be a declared measure alias");
+		chart = {
+			type,
+			...x ? { x } : {},
+			...y.length > 0 ? { y } : {}
+		};
+	}
+	return {
+		version: 1,
+		title,
+		...description ? { description } : {},
+		source: raw.source,
+		dimensions,
+		measures,
+		filters,
+		having,
+		sort,
+		limit,
+		chart
+	};
+}
+function canonicalize(value) {
+	if (Array.isArray(value)) return value.map(canonicalize);
+	if (isRecord(value)) return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]));
+	return value;
+}
+function runtimeReportSpecHash(spec) {
+	return createHash("sha256").update(JSON.stringify(canonicalize(spec))).digest("hex");
+}
+function serializeRuntimeReportSpec(spec) {
+	return JSON.stringify(canonicalize(spec));
+}
+//#endregion
+//#region src/runtime-compiler.ts
+var ALIAS_PREFIX = "r_";
+var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function humanize(name) {
+	return name.replace(/([a-z\d])([A-Z])/g, "$1 $2").replace(/[_-]+/g, " ").replace(/^./, (value) => value.toUpperCase());
+}
+function columnTypeFor(type) {
+	switch (type) {
+		case "text": return "string";
+		case "integer": return "integer";
+		case "decimal": return "decimal";
+		case "boolean": return "boolean";
+		case "datetime": return "datetime";
+		case "foreignKey":
+		case "crossPackageRef": return "id";
+		default: return null;
+	}
+}
+function explicitColumn(field) {
+	const metaColumn = field._meta?.columnName;
+	if (typeof field.columnName === "string") return field.columnName;
+	return typeof metaColumn === "string" ? metaColumn : void 0;
+}
+function strictFormat(field) {
+	return [field.format, field._meta?.format].find((value) => typeof value === "string" && value.length > 0);
+}
+var BASE_FIELDS = {
+	id: "id",
+	slug: "string",
+	createdAt: "datetime",
+	updatedAt: "datetime"
+};
+function isExcluded(name, field, tenantField, permissions) {
+	if (name.startsWith("_")) return true;
+	const meta = field._meta ?? {};
+	if (field.transient === true || meta.transient === true) return true;
+	const sensitivity = [field.sensitivity, meta.sensitivity].find((value) => typeof value === "string");
+	if (field.sensitive === true || meta.sensitive === true || sensitivity === "sensitive" || sensitivity === "secret") return true;
+	const readPermission = typeof field.readPermission === "string" ? field.readPermission : typeof meta.readPermission === "string" ? meta.readPermission : void 0;
+	if (readPermission && !permissions.has(readPermission)) return true;
+	if (meta.__tenancy?.isTenantIdField === true) return true;
+	if (name === "tenantId" || name === "tenant_id") return true;
+	if (tenantField && toSnakeCase(name) === tenantField) return true;
+	return false;
+}
+async function loadSourceFields(qualifiedName, tenantField, permissions) {
+	const registered = await ObjectRegistry.getAllFields(qualifiedName);
+	const fields = /* @__PURE__ */ new Map();
+	for (const [name, field] of registered) {
+		if (isExcluded(name, field, tenantField, permissions)) continue;
+		const type = columnTypeFor(field.type);
+		if (!type) continue;
+		const format = strictFormat(field);
+		fields.set(name, {
+			name,
+			column: toSnakeCase(explicitColumn(field) ?? name),
+			type,
+			...format ? { format } : {},
+			label: typeof field.description === "string" && field.description.length > 0 ? field.description : humanize(name)
+		});
+	}
+	for (const [name, type] of Object.entries(BASE_FIELDS)) {
+		if (fields.has(name) || registered.has(name)) continue;
+		fields.set(name, {
+			name,
+			column: toSnakeCase(name),
+			type,
+			label: humanize(name)
+		});
+	}
+	return fields;
+}
+function unknownField(path, name) {
+	throw new RuntimeReportError("unknown_field", path, `'${name}' is not a field available on this source`);
+}
+function badOperation(path, message) {
+	throw new RuntimeReportError("invalid_operation", path, message);
+}
+function badValue(path, message) {
+	throw new RuntimeReportError("invalid_value", path, message);
+}
+var OPERATORS_BY_TYPE = {
+	string: [
+		"eq",
+		"ne",
+		"gt",
+		"gte",
+		"lt",
+		"lte",
+		"in",
+		"notIn",
+		"contains",
+		"isNull",
+		"isNotNull"
+	],
+	integer: [
+		"eq",
+		"ne",
+		"gt",
+		"gte",
+		"lt",
+		"lte",
+		"in",
+		"notIn",
+		"isNull",
+		"isNotNull"
+	],
+	decimal: [
+		"eq",
+		"ne",
+		"gt",
+		"gte",
+		"lt",
+		"lte",
+		"in",
+		"notIn",
+		"isNull",
+		"isNotNull"
+	],
+	datetime: [
+		"eq",
+		"ne",
+		"gt",
+		"gte",
+		"lt",
+		"lte",
+		"in",
+		"notIn",
+		"isNull",
+		"isNotNull"
+	],
+	boolean: [
+		"eq",
+		"ne",
+		"isNull",
+		"isNotNull"
+	],
+	id: [
+		"eq",
+		"ne",
+		"in",
+		"notIn",
+		"isNull",
+		"isNotNull"
+	]
+};
+function coerceValue(type, value, path) {
+	switch (type) {
+		case "string":
+			if (typeof value !== "string") badValue(path, "must be a string");
+			return value;
+		case "integer":
+			if (typeof value !== "number" || !Number.isSafeInteger(value)) badValue(path, "must be a safe integer");
+			return value;
+		case "decimal":
+			if (typeof value !== "number" || !Number.isFinite(value)) badValue(path, "must be a finite number");
+			return value;
+		case "boolean":
+			if (typeof value !== "boolean") badValue(path, "must be true or false");
+			return value;
+		case "datetime": {
+			if (typeof value !== "string") badValue(path, "must be an ISO-8601 string");
+			const parsed = new Date(value);
+			if (Number.isNaN(parsed.getTime()) || !/^\d{4}-\d{2}-\d{2}/.test(value)) badValue(path, "must be an ISO-8601 date or timestamp");
+			return parsed;
+		}
+		case "id":
+			if (typeof value !== "string" || !UUID_PATTERN.test(value)) badValue(path, "must be a UUID");
+			return value.toLowerCase();
+	}
+}
+function filterCondition(filter, field, path) {
+	if (!OPERATORS_BY_TYPE[field.type].includes(filter.op)) badOperation(`${path}.op`, `'${filter.op}' is not valid for ${field.type} fields`);
+	const column = field.column;
+	switch (filter.op) {
+		case "isNull": return { [column]: null };
+		case "isNotNull": return { [`${column} !=`]: null };
+		case "in":
+		case "notIn": {
+			const values = filter.value.map((entry, index) => coerceValue(field.type, entry, `${path}.value[${index}]`));
+			return { [`${column} ${filter.op === "in" ? "in" : "not in"}`]: values };
+		}
+		case "contains": return { [`${column} contains`]: coerceValue(field.type, filter.value, `${path}.value`) };
+		default: return { [`${column}${{
+			eq: "",
+			ne: " !=",
+			gt: " >",
+			gte: " >=",
+			lt: " <",
+			lte: " <="
+		}[filter.op]}`]: coerceValue(field.type, filter.value, `${path}.value`) };
+	}
+}
+function measureColumnType(fn, field) {
+	if (fn === "count" || fn === "countDistinct") return "integer";
+	if (fn === "avg") return "decimal";
+	return field?.type ?? "decimal";
+}
+function resolveSource(context, id) {
+	const source = context.sources.find((candidate) => candidate.id === id);
+	if (!source) throw new RuntimeReportError("unknown_source", "spec.source", `'${id}' is not an available report source`);
+	return source;
+}
+async function prepareSource(context, id) {
+	const source = resolveSource(context, id);
+	await context.authorizeSource?.(source);
+	const registered = ObjectRegistry.getClass(source.className);
+	if (!registered) throw new RuntimeReportError("unknown_source", "spec.source", `'${id}' is not an available report source`);
+	const qualifiedName = registered.qualifiedName ?? registered.name;
+	const table = ObjectRegistry.getTableName(qualifiedName);
+	if (!table) throw new RuntimeReportError("unsupported_source", "spec.source", "this source has no registered table");
+	const tenantCol = await tenantColumn(qualifiedName);
+	if (isTenantScopedClass(qualifiedName) && !tenantCol) throw new RuntimeReportError("unsupported_source", "spec.source", "this tenant-scoped source does not expose a tenant column");
+	const fields = await loadSourceFields(qualifiedName, tenantCol, new Set(context.permissions ?? []));
+	return {
+		source,
+		registeredName: registered.name,
+		qualifiedName,
+		table,
+		tenantCol,
+		fields
+	};
+}
+async function describeRuntimeReportSource(context, sourceId) {
+	const prepared = await prepareSource(context, sourceId);
+	return {
+		id: prepared.source.id,
+		label: prepared.source.label ?? humanize(prepared.registeredName),
+		...prepared.source.description ? { description: prepared.source.description } : {},
+		fields: [...prepared.fields.values()].map((field) => ({
+			name: field.name,
+			label: field.label,
+			type: field.type,
+			...field.format ? { format: field.format } : {},
+			filterOperators: OPERATORS_BY_TYPE[field.type],
+			aggregates: aggregatesFor(field.type)
+		}))
+	};
+}
+function aggregatesFor(type) {
+	if (type === "integer" || type === "decimal") return [
+		"count",
+		"countDistinct",
+		"sum",
+		"avg",
+		"min",
+		"max"
+	];
+	if (type === "datetime") return [
+		"count",
+		"countDistinct",
+		"min",
+		"max"
+	];
+	return ["count", "countDistinct"];
+}
+async function compileRuntimeReportSpec(spec, context) {
+	const { source, registeredName, qualifiedName, table, tenantCol, fields } = await prepareSource(context, spec.source);
+	const lookup = (name, path) => {
+		const field = fields.get(name);
+		if (!field) unknownField(path, name);
+		return field;
+	};
+	const columns = [];
+	const select = [];
+	const groupBy = [];
+	for (const [index, dimension] of spec.dimensions.entries()) {
+		const path = `spec.dimensions[${index}]`;
+		const field = lookup(dimension.field, `${path}.field`);
+		if (dimension.bucket && field.type !== "datetime") badOperation(`${path}.bucket`, "buckets are only valid on datetime fields");
+		const sqlAlias = `${ALIAS_PREFIX}${dimension.as}`;
+		if (dimension.bucket) select.push({
+			bucket: dimension.bucket,
+			column: field.column,
+			as: sqlAlias
+		});
+		else select.push({
+			column: field.column,
+			as: sqlAlias
+		});
+		groupBy.push(sqlAlias);
+		columns.push({
+			id: dimension.as,
+			label: humanize(dimension.as),
+			role: "dimension",
+			type: dimension.bucket ? "datetime" : field.type,
+			field: field.name,
+			...dimension.bucket ? { bucket: dimension.bucket } : {},
+			...field.format && !dimension.bucket ? { format: field.format } : {}
+		});
+	}
+	for (const [index, measure] of spec.measures.entries()) {
+		const path = `spec.measures[${index}]`;
+		const field = measure.field ? lookup(measure.field, `${path}.field`) : void 0;
+		if ((measure.fn === "sum" || measure.fn === "avg") && field?.type !== "integer" && field?.type !== "decimal") badOperation(`${path}.fn`, `${measure.fn} requires a numeric field`);
+		if ((measure.fn === "min" || measure.fn === "max") && field?.type !== "integer" && field?.type !== "decimal" && field?.type !== "datetime") badOperation(`${path}.fn`, `${measure.fn} requires a numeric or datetime field`);
+		const sqlAlias = `${ALIAS_PREFIX}${measure.as}`;
+		select.push({
+			fn: measure.fn === "countDistinct" ? "count" : measure.fn,
+			...field ? { column: field.column } : {},
+			as: sqlAlias,
+			...measure.fn === "countDistinct" ? { distinct: true } : {}
+		});
+		const keepsFormat = field?.format && (measure.fn === "sum" || measure.fn === "min" || measure.fn === "max" || measure.fn === "avg");
+		columns.push({
+			id: measure.as,
+			label: humanize(measure.as),
+			role: "measure",
+			type: measureColumnType(measure.fn, field),
+			...field ? { field: field.name } : {},
+			fn: measure.fn,
+			...keepsFormat ? { format: field?.format } : {}
+		});
+	}
+	const conditions = [];
+	const tenantId = context.tenantId !== void 0 ? context.tenantId : getTenantId() ?? null;
+	if (tenantCol) {
+		if (tenantId) conditions.push({ [tenantCol]: tenantId });
+		else if (isTenancyEnabled() || isTenantScopedClass(qualifiedName)) conditions.push({ [tenantCol]: null });
+	}
+	if ((await ObjectRegistry.getAllFields(qualifiedName)).has("deletedAt")) conditions.push({ deleted_at: null });
+	if (ObjectRegistry.getTableStrategy(qualifiedName) === "sti") {
+		const base = ObjectRegistry.getSTIBase(qualifiedName);
+		if (base !== null && base !== qualifiedName) conditions.push({ _meta_type: qualifiedName });
+	}
+	for (const [index, filter] of spec.filters.entries()) {
+		const path = `spec.filters[${index}]`;
+		const field = lookup(filter.field, `${path}.field`);
+		conditions.push(filterCondition(filter, field, path));
+	}
+	const having = spec.having.map((entry) => {
+		const suffix = {
+			eq: "",
+			ne: " !=",
+			gt: " >",
+			gte: " >=",
+			lt: " <",
+			lte: " <="
+		}[entry.op];
+		return { [`${ALIAS_PREFIX}${entry.measure}${suffix}`]: entry.value };
+	});
+	const orderBy = spec.sort.map((entry) => `${ALIAS_PREFIX}${entry.by} ${entry.direction === "desc" ? "DESC" : "ASC"}`);
+	if (orderBy.length === 0 && spec.dimensions.length > 0) orderBy.push(`${ALIAS_PREFIX}${spec.dimensions[0].as} ASC`);
+	const aggregate = {
+		from: table,
+		select,
+		groupBy,
+		...conditions.length > 0 ? { where: [conditions] } : {},
+		...having.length > 0 ? { having: [having] } : {},
+		...orderBy.length > 0 ? { orderBy } : {},
+		limit: Math.min(spec.limit, RUNTIME_REPORT_LIMITS.maxRowLimit) + 1
+	};
+	return {
+		version: 1,
+		specHash: runtimeReportSpecHash(spec),
+		spec,
+		source: {
+			id: source.id,
+			className: qualifiedName,
+			label: source.label ?? humanize(registeredName),
+			table
+		},
+		columns,
+		aggregate,
+		limit: spec.limit,
+		tenant: {
+			scoped: Boolean(tenantCol),
+			tenantId: tenantCol ? tenantId : null
+		}
+	};
+}
+function adaptWhere(where, adapterType) {
+	if (!where || !Array.isArray(where)) return where;
+	const adapt = (value) => adapterType === "sqlite" && typeof value === "boolean" ? value ? 1 : 0 : value;
+	return where.map((group) => group.map((condition) => Object.fromEntries(Object.entries(condition).map(([key, value]) => [key, Array.isArray(value) ? value.map(adapt) : adapt(value)]))));
+}
+function normalizeCell(column, value) {
+	if (value === null || value === void 0) return null;
+	if (value instanceof Date) return value.toISOString();
+	if (typeof value === "bigint") {
+		const asNumber = Number(value);
+		if (!Number.isSafeInteger(asNumber)) throw new RuntimeReportError("invalid_result", column.id, "integer result exceeds the JavaScript safe range");
+		return asNumber;
+	}
+	if (column.type === "boolean") {
+		if (value === 1 || value === "1" || value === "true" || value === true) return true;
+		if (value === 0 || value === "0" || value === "false" || value === false) return false;
+	}
+	if (column.type === "integer" || column.type === "decimal") {
+		const numeric = typeof value === "number" ? value : Number(value);
+		if (!Number.isFinite(numeric)) throw new RuntimeReportError("invalid_result", column.id, "numeric result is not finite");
+		if (column.type === "integer" && !Number.isSafeInteger(numeric)) throw new RuntimeReportError("invalid_result", column.id, "integer result exceeds the JavaScript safe range");
+		return numeric;
+	}
+	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+	return String(value);
+}
+async function runRuntimeReport(compiled, options) {
+	const adapterType = adapterTypeFromDb(options.db, options.adapterType);
+	const aggregate = buildAggregate({
+		...compiled.aggregate,
+		where: adaptWhere(compiled.aggregate.where, adapterType)
+	}, 1, adapterType);
+	const rawRows = (await options.db.query(aggregate.sql, ...aggregate.values)).rows ?? [];
+	const limit = Math.min(compiled.limit, options.maxRows ?? RUNTIME_REPORT_LIMITS.maxRowLimit);
+	const truncated = rawRows.length > limit;
+	const rows = rawRows.slice(0, limit).map((row) => {
+		const out = {};
+		for (const column of compiled.columns) out[column.id] = normalizeCell(column, row[`${ALIAS_PREFIX}${column.id}`]);
+		return out;
+	});
+	return {
+		version: 1,
+		specHash: compiled.specHash,
+		title: compiled.spec.title,
+		columns: compiled.columns,
+		rows,
+		rowCount: rows.length,
+		truncated,
+		ranAt: (options.now?.() ?? /* @__PURE__ */ new Date()).toISOString(),
+		chart: compiled.spec.chart
+	};
+}
+//#endregion
+//#region src/runtime-report.ts
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, {
+	enumerable: true,
+	configurable: true,
+	writable: true,
+	value
+}) : obj[key] = value;
+var __decorateClass = (decorators, target, key, kind) => {
+	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+	for (var i = decorators.length - 1, decorator; i >= 0; i--) if (decorator = decorators[i]) result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+	if (kind && result) __defProp(target, key, result);
+	return result;
+};
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+var CONFIRMED_SAVE = /* @__PURE__ */ Symbol("smrt-reports.runtimeReport.confirmedSave");
+var confirmedSaves = /* @__PURE__ */ new WeakMap();
+var RuntimeReport = class extends SmrtObject {
+	tenantId = "";
+	title = "";
+	description = "";
+	sourceId = "";
+	spec = "";
+	specHash = "";
+	status = "active";
+	createdByUserId = "";
+	constructor(options = {}) {
+		super(options);
+		const proof = options[CONFIRMED_SAVE];
+		if (typeof proof === "string") confirmedSaves.set(this, proof);
+	}
+	/** Re-parse the stored JSON; never trust the column without validation. */
+	getSpec() {
+		const parsed = parseRuntimeReportSpec(this.spec);
+		if (runtimeReportSpecHash(parsed) !== this.specHash) throw new RuntimeReportError("invalid_spec", "spec", "stored spec does not match its recorded hash");
+		return parsed;
+	}
+	setSpec(spec) {
+		const normalized = parseRuntimeReportSpec(spec);
+		this.spec = serializeRuntimeReportSpec(normalized);
+		this.specHash = runtimeReportSpecHash(normalized);
+		this.title = normalized.title;
+		this.description = normalized.description ?? "";
+		this.sourceId = normalized.source;
+	}
+	async validateBeforeSave() {
+		await super.validateBeforeSave();
+		const parsed = parseRuntimeReportSpec(this.spec);
+		await this.assertConfirmedWrite(parsed);
+		this.setSpec(parsed);
+		if (this.status !== "active" && this.status !== "archived") throw new RuntimeReportError("invalid_spec", "status", "is invalid");
+	}
+	/**
+	* Invariant: a RuntimeReport row is inserted, or has its spec/title/source/
+	* description/author changed, only by the confirmed-save path. Anything else
+	* (REST `create` body, manifest tool args, `new RuntimeReport().save()`,
+	* `collection.update()` of the spec) is refused here. A save that leaves those
+	* columns as stored (an archive/unarchive status change) needs no proof.
+	*/
+	async assertConfirmedWrite(parsed) {
+		const hash = runtimeReportSpecHash(parsed);
+		const proof = confirmedSaves.get(this);
+		if (proof !== void 0) {
+			confirmedSaves.delete(this);
+			if (proof === hash) return;
+		} else if (this.isPersisted && this.id) {
+			const stored = await this.db.get(this.tableName, { id: this.id });
+			if (stored && stored.spec_hash === hash && (stored.title ?? "") === parsed.title && (stored.description ?? "") === (parsed.description ?? "") && (stored.source_id ?? "") === parsed.source && (stored.created_by_user_id ?? "") === (this.createdByUserId ?? "")) return;
+		}
+		throw new RuntimeReportError("confirmation_required", "spec", "a runtime report can only be created or changed through the confirmed save of reports.runtime.define; the write was refused");
+	}
+};
+__publicField(RuntimeReport, "__smrtPackage__", "@happyvertical/smrt-reports");
+__decorateClass([tenantId()], RuntimeReport.prototype, "tenantId", 2);
+__decorateClass([field({ type: "text" })], RuntimeReport.prototype, "title", 2);
+__decorateClass([field({ type: "text" })], RuntimeReport.prototype, "description", 2);
+__decorateClass([field({ type: "text" })], RuntimeReport.prototype, "sourceId", 2);
+__decorateClass([field({
+	type: "text",
+	required: true
+})], RuntimeReport.prototype, "spec", 2);
+__decorateClass([field({ type: "text" })], RuntimeReport.prototype, "specHash", 2);
+__decorateClass([field({
+	type: "text",
+	required: true
+})], RuntimeReport.prototype, "status", 2);
+__decorateClass([field({ type: "text" })], RuntimeReport.prototype, "createdByUserId", 2);
+RuntimeReport = __decorateClass([TenantScoped({ mode: "required" }), smrt({
+	tableName: "runtime_reports",
+	api: { include: [
+		"list",
+		"get",
+		"create"
+	] },
+	mcp: { include: ["list", "get"] },
+	cli: { include: ["list", "get"] }
+})], RuntimeReport);
+var RuntimeReportCollection = class extends SmrtCollection {
+	static _itemClass = RuntimeReport;
+};
+async function collectionFor(db) {
+	return RuntimeReportCollection.create({ db });
+}
+async function saveRuntimeReport(options) {
+	const tenant = options.tenantId ?? options.compiled.tenant.tenantId ?? getTenantId() ?? "";
+	if (!tenant) throw new RuntimeReportError("tenant_required", "", "a tenant is required to save a runtime report");
+	const spec = parseRuntimeReportSpec(options.compiled.spec);
+	const specHash = runtimeReportSpecHash(spec);
+	if (specHash !== options.compiled.specHash) throw new RuntimeReportError("invalid_spec", "spec", "compiled plan does not match its spec");
+	if (options.confirmedSpecHash !== specHash) throw new RuntimeReportError("confirmation_required", "specHash", "the confirmed spec hash does not match the spec; the report was not saved");
+	return (await collectionFor(options.db)).create({
+		tenantId: tenant,
+		title: spec.title,
+		description: spec.description ?? "",
+		sourceId: spec.source,
+		spec: serializeRuntimeReportSpec(spec),
+		specHash,
+		status: "active",
+		createdByUserId: options.createdByUserId,
+		[CONFIRMED_SAVE]: specHash
+	});
+}
+async function getRuntimeReport(options) {
+	const report = await (await collectionFor(options.db)).get(options.ref);
+	if (report && options.tenantId && report.tenantId !== options.tenantId) return null;
+	return report;
+}
+async function listRuntimeReports(options) {
+	return (await collectionFor(options.db)).list({
+		where: {
+			status: options.status ?? "active",
+			...options.tenantId ? { tenantId: options.tenantId } : {}
+		},
+		orderBy: "created_at DESC",
+		limit: Math.min(Math.max(options.limit ?? 50, 1), 200)
+	});
+}
+async function archiveRuntimeReport(options) {
+	const report = await getRuntimeReport(options);
+	if (!report) return null;
+	report.status = "archived";
+	await report.save();
+	return report;
+}
+async function runStoredRuntimeReport(options) {
+	if (options.report.status !== "active") throw new RuntimeReportError("invalid_spec", "status", "report is archived");
+	return runRuntimeReport(await compileRuntimeReportSpec(options.report.getSpec(), options.context), {
+		db: options.db,
+		maxRows: options.maxRows
+	});
+}
+//#endregion
 //#region src/views.ts
 var INHERITED_REPORT_SCOPE = [
 	"principal",
@@ -1515,6 +2506,6 @@ function validateReportExportArtifact(descriptor, artifact, now = /* @__PURE__ *
 	};
 }
 //#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, SmrtPrincipalReportRefreshTask, 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, registerReportRefreshExecutionAuthorityHost, registerReportRefreshInterceptor, registerReportRefreshJobIntegritySigner, report, reportDefinitionFingerprint, reportMaterializedRowKey, reportRefreshOutcome, reportRowIdentity, restoreReportSavedView, scopeKeyForTenant, splitReportFilterScopes, sum, validateReportExportArtifact, validateReportExportExecution, validateReportExportRequest, verifyReportExportSnapshot, week, year };
+export { MaterializedReportsRecipe, REPORT_LOCKS_TABLE, REPORT_REFRESH_TASKS_TABLE, REPORT_RUNS_TABLE, REPORT_RUNTIME_TABLES, REPORT_SCHEDULER_TABLES, REPORT_SCHEDULES_TABLE, REPORT_WATERMARKS_TABLE, RUNTIME_REPORT_BUCKETS, RUNTIME_REPORT_CHART_TYPES, RUNTIME_REPORT_FILTER_OPS, RUNTIME_REPORT_HAVING_OPS, RUNTIME_REPORT_LIMITS, RUNTIME_REPORT_MEASURE_FNS, RUNTIME_REPORT_SPEC_VERSION, ReportScheduleRunner, ReportSurfaceValidationError, RuntimeReport, RuntimeReportCollection, RuntimeReportError, SmrtPrincipalReportRefreshTask, SmrtReport, SmrtReportCollection, SmrtReportLock, SmrtReportLockCollection, SmrtReportRefreshTask, SmrtReportRun, SmrtReportRunCollection, SmrtReportSchedule, SmrtReportScheduleCollection, SmrtReportWatermark, SmrtReportWatermarkCollection, aggregate, applyReportExport, applyReportRefresh, archiveRuntimeReport, assertReportTablesReady, avg, bucketExpr, buildAggregate, buildReportAdapterDescriptor, buildReportDefinition, buildReportDrilldownQuery, compileReportDefinition, compileReportSpec, compileRuntimeReportSpec, count, createReportExportPageRequest, createReportExportRequest, createReportExportSnapshot, day, describeRuntimeReportSource, enqueueReportRefresh, ensureReportRefreshSchedules, getReportGroupingColumns, getReportLifecycle, getRuntimeReport, getRuntimeReportOptions, groupBy, hour, listRuntimeReports, max, migrateReportSavedView, min, minute, month, normalizeReportSavedView, parseRuntimeReportSpec, previewReportExport, previewReportRefresh, quarter, queryReportMaterializedRows, refreshReport, registerReportRefreshExecutionAuthorityHost, registerReportRefreshInterceptor, registerReportRefreshJobIntegritySigner, report, reportDefinitionFingerprint, reportMaterializedRowKey, reportRefreshOutcome, reportRowIdentity, restoreReportSavedView, runRuntimeReport, runStoredRuntimeReport, runtimeReportSpecHash, saveRuntimeReport, scopeKeyForTenant, serializeRuntimeReportSpec, splitReportFilterScopes, sum, validateReportExportArtifact, validateReportExportExecution, validateReportExportRequest, verifyReportExportSnapshot, week, year };
 
 //# sourceMappingURL=index.js.map