@happyvertical/smrt-spreadsheets 0.0.0-stage → 0.61.1

package/AGENTS.md

@@ -0,0 +1,75 @@
+# @happyvertical/smrt-spreadsheets
+
+smrt's spreadsheet package, starting with import: the deterministic half of
+"build an app from a workbook" (#4969). A model, elsewhere and later, proposes an `ImportPlan`; this package validates it,
+checks it against the workbook, loads the data through an `ImportTarget`, and
+proves the result. Two products implement the target, so nothing here may
+name either. No `@smrt()` objects, no tables, no Svelte.
+
+`./export`, saved mapping and re-import are planned, not present.
+
+## Entries
+
+- Root (`.`): types only (`export type * from './import/index.js'`); no runtime
+  code or values. Keep it types only as new capabilities arrive.
+- `./import`: browser-safe and pure. Imports `@happyvertical/spreadsheets` and
+  `@happyvertical/sql/query` only, never the sql root or a `node:` built-in
+  (`browser-safe.test.ts` walks and bundles the graph).
+- `./testing`: Node-only `createSqliteReferenceTarget()`, real in-process SQLite
+  through `@happyvertical/sql`. Calculated fields are generated columns made
+  by `renderExpression`, so they run on database semantics. Never import it
+  from the root or import entry.
+
+## Source map
+
+Import implementation and tests live under `src/import/`; `src/import/index.ts`
+exports the import surface. `src/index.ts` is the type-only root, and
+`src/testing.ts` implements the Node-only target.
+
+- `src/import/plan.ts`: `validatePlan` (closed shapes, JSON-cloned input, limits),
+  `loadOrder`. Calculated expressions may read column fields only.
+- `src/import/coerce.ts`: `coerceCell`, the one typing rule. Nothing is guessed.
+- `src/import/evaluate.ts`: reads and types every table; shared by `checkPlan` and
+  `planLoad`. A row that fails never reaches a record.
+- `src/import/checks.ts`: `checkPlan` (before writing) and `checkLoaded` (after).
+- `src/import/load.ts`: `admit` (limits) and `planLoad` (ordered, batched records).
+- `src/import/run.ts`: `runImport`. Adapter errors propagate; it catches nothing.
+
+## Invariants
+
+- First import only: `runImport` refuses a target that has any planned table
+  (`target-not-empty`). Re-import matching is a later slice.
+- `checkPlan` errors stop the run before `describe()` is called; nothing is written.
+- `DEFAULT_MAX_CELLS` (250,000) is PROVISIONAL, owner decision pending; keep it
+  one constant. Per-table rows default to 10,000.
+- Money is integer minor units (`value * 10^scale`, within 1e-6 of an integer or
+  refused). Integer sums are exact (BigInt); number sums are compensated.
+- `distinct` tables skip the unmapped-column warning: they extract columns by design.
+- Work is bounded: evaluation visits occupied rows and mapped columns only, never
+  range width x height, and spends from `maxWork` (`DEFAULT_MAX_WORK`); over it,
+  `work-over-limit`. Row indexes live for one evaluation call, never across calls:
+  a workbook is mutable and is re-read every time.
+- Anything that does not depend on a row (field-by-key maps, reference key fields,
+  choice sets, column lists, insert SQL) is resolved once before rows are visited;
+  never `.find`/`.includes` over plan data inside a row or cell loop. Every
+  per-row, per-cell and per-reference unit is charged to one `WorkBudget` that
+  `runImport` shares across checking, planning and verifying. `work-over-limit`
+  is thrown before the first call on the target (`describe()` included) or never:
+  `runImport` plans every batch up front and reserves the read-back work
+  (`verificationWork`) before touching the target; read-back is bounded by planned
+  rows + 1, and extra rows are a `row-count-mismatch`, never a budget error.
+- `checkLoaded` value-checks every calculated integer, money and number field
+  (`calculated-invalid`: not a whole safe integer / not finite) with or without a
+  `cachedColumn`. Integer and money comparisons are exact; tolerance is for `number`.
+- `ok:false` after a load is a verdict, not a repair: the caller discards the draft
+  target. There is no rollback or recreation logic here.
+- Findings keep at most 20 examples per (code, table, field) with a total `count`.
+- Plan keys are `^[a-z][a-z0-9_]{0,62}$`; SQL keywords are fine, names that exist
+  on every object (`constructor`, `prototype`, ...) are refused. The reference
+  target quotes every identifier.
+
+## Validation
+
+`pnpm --filter @happyvertical/smrt-spreadsheets build|typecheck|test`.
+Tests build workbooks in code with the SDK's `createWorkbook`/`createSheet`;
+no binary fixtures, no containers.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,113 @@
-# Temporary Holding Version
+# @happyvertical/smrt-spreadsheets
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+smrt's spreadsheet package. Its first capability is import: turning a spreadsheet
+into records without guessing. A plan says which sheet
+range becomes which table, which column becomes which typed field, and which
+fields are calculated or point at another table. This package validates the
+plan, checks it against the workbook before anything is written, loads the data
+in batches through a target you provide, and then reads the target back to
+prove nothing was lost or changed.
+
+It does not decide what the plan is (a person or a model does that) and it does
+not know where the data goes (your target does). Nothing here is tied to a
+product, a database or an s-m-r-t model layer.
+
+## Installation
+
+```bash
+pnpm add @happyvertical/smrt-spreadsheets
+```
+
+## Entry points
+
+- `.`: type-only re-exports of the import surface; no runtime code or values.
+- `./import`: the browser-safe import API (`runImport`, plan validation, checks
+  and target contracts).
+- `./testing`: the Node-only SQLite reference target for tests.
+
+`./export`, saved mapping and re-import are planned capabilities, not present
+in this version. The root stays types only as new capabilities arrive.
+
+## Usage
+
+```ts
+import { getSpreadsheets } from '@happyvertical/spreadsheets';
+import { runImport } from '@happyvertical/smrt-spreadsheets/import';
+
+const workbook = await (await getSpreadsheets({ type: 'xlsx' })).read(bytes);
+
+const result = await runImport({
+  plan, // validated for you; a bad plan throws ImportPlanError
+  workbook,
+  target, // your ImportTarget
+});
+
+if (!result.ok) console.table(result.findings);
+```
+
+`runImport` validates the plan, refuses a workbook over the size limits, runs
+`checkPlan`, refuses a target that already holds a planned table, builds the
+structure, loads every batch, and runs `checkLoaded`. If `checkPlan` reports
+errors nothing is written. Errors thrown by your target are never caught.
+
+A row is blank only when every mapped column, reference column and calculated
+`cachedColumn` is blank. Calculated-only tables need at least one `cachedColumn`
+to establish their rows; otherwise `validatePlan` throws `no-row-source`.
+
+### Typing
+
+Every cell is typed by one rule (`coerceCell`) and refused when it does not fit:
+integers must be safe whole numbers, money must be an exact number of minor
+units, booleans accept true/false/yes/no/y/n/1/0, dates become `YYYY-MM-DD`,
+choices must match exactly, and error cells are always refused with their
+Excel text. Long digit strings and values with leading zeros in number fields
+are reported as `digits-as-number`: they are identifiers, so map them as text.
+
+### Checks
+
+`checkPlan` reports findings (`coerce-failed`, `digits-as-number`,
+`lookup-key-not-unique`, `lookup-key-blank`, `reference-unresolved`,
+`unmapped-column`, and structural ones) with the cell and row, at most 20
+examples per code, table and field plus a total `count`. It also returns facts:
+rows read, skipped and planned per table, and column sums.
+
+`checkLoaded` compares the target with those facts: row counts, column sums,
+and, for every calculated field with a `cachedColumn`, the target's value
+against the workbook's cached result, row by row. That is how a translated
+formula is proven.
+
+Integer and money sums use exact BigInt accumulation; only the final total
+must fit a safe integer. Number comparisons reject non-finite values before
+applying relative tolerance, including when comparing a calculated cache.
+
+If `ok` is false after a load, the target holds a draft that failed its proof:
+discard it. This package does not undo or recreate anything.
+
+### Targets
+
+Implement `ImportTarget` (`describe`, `applyStructure`, `load`, `count`, `sum`,
+`values`). `load` resolves references by lookup key and is all-or-nothing per
+batch. The target keeps each record's `sourceRow`.
+`sum` returns money in minor units and preserves unsafe integer/money totals as
+`bigint`, so verification reports a mismatch rather than losing precision.
+
+For tests there is a reference target on real in-process SQLite:
+
+```ts
+import { createSqliteReferenceTarget } from '@happyvertical/smrt-spreadsheets/testing';
+
+const target = await createSqliteReferenceTarget();
+```
+
+The `./testing` entry is Node-only; `.` and `./import` are browser-safe.
+
+### Limits
+
+Workbooks over 250,000 cells or tables over 10,000 rows are refused before any
+row is read (`admit`). The cell limit is provisional. Reading is bounded by
+occupied cells, not range size, and by a work budget (`maxWork`, refusal
+`work-over-limit`). That refusal comes before the first call on your target,
+`describe()` included, or not at all: `runImport` plans the whole load and reserves
+the work for reading it back before it writes anything. Plans are bounded too:
+200 tables, 500 fields per table, 2 MB of JSON; all can be raised through
+`validatePlan(plan, limits)`.

package/dist/chunks/plan-BAV2jEzl.js

@@ -0,0 +1,429 @@
+import { range } from "@happyvertical/spreadsheets";
+import { ExpressionError, renderExpression } from "@happyvertical/sql/query";
+//#region src/import/errors.ts
+var ImportPlanError = class extends Error {
+	code;
+	path;
+	constructor(code, path, message) {
+		super(`${path || "plan"}: ${message}`);
+		this.name = "ImportPlanError";
+		this.code = code;
+		this.path = path;
+	}
+};
+var ImportRunError = class extends Error {
+	code;
+	detail;
+	constructor(code, message, detail) {
+		super(message);
+		this.name = "ImportRunError";
+		this.code = code;
+		this.detail = detail;
+	}
+};
+//#endregion
+//#region src/import/plan.ts
+var IMPORT_FIELD_TYPES = Object.freeze([
+	"text",
+	"number",
+	"integer",
+	"boolean",
+	"date",
+	"money",
+	"choice",
+	"reference"
+]);
+var DEFAULT_PLAN_LIMITS = Object.freeze({
+	maxTables: 200,
+	maxFieldsPerTable: 500,
+	maxPlanBytes: 2 * 1024 * 1024,
+	maxReports: 200,
+	maxChoices: 1e3,
+	maxSkipRows: 1e5,
+	maxExpressionNodes: 1024
+});
+var PLAN_KEY_PATTERN = /^[a-z][a-z0-9_]{0,62}$/;
+var RESERVED_KEYS = /* @__PURE__ */ new Set([...Object.getOwnPropertyNames(Object.prototype), "prototype"]);
+var MAX_LABEL = 200;
+var MAX_COLUMN = 16384;
+var MAX_ROW = 1048576;
+function fail(code, path, message) {
+	throw new ImportPlanError(code, path, message);
+}
+function toPlainData(input, limits) {
+	let text;
+	try {
+		text = JSON.stringify(input, (_key, value) => {
+			const kind = typeof value;
+			if (kind === "function" || kind === "symbol" || kind === "bigint") throw new TypeError(`a ${kind} is not plain data`);
+			if (typeof value === "number" && !Number.isFinite(value)) throw new TypeError("a non-finite number is not plain data");
+			return value;
+		});
+	} catch (error) {
+		fail("plan-not-data", "", `a plan must be plain JSON data (${error instanceof Error ? error.message : "unserializable"})`);
+	}
+	if (text === void 0) fail("plan-not-data", "", "a plan must be plain JSON data");
+	if (text.length > limits.maxPlanBytes) fail("plan-too-large", "", `plan is ${text.length} bytes; the limit is ${limits.maxPlanBytes}`);
+	return JSON.parse(text);
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function closedObject(value, path, allowed) {
+	if (!isRecord(value)) fail("invalid-shape", path, "expected an object");
+	for (const key of Object.keys(value)) if (!allowed.includes(key)) fail("unknown-key", `${path}.${key}`, `unknown key "${key}"`);
+	return value;
+}
+function arrayOf(value, path, max) {
+	if (!Array.isArray(value)) fail("invalid-shape", path, "expected an array");
+	if (value.length > max) fail("limit-exceeded", path, `at most ${max} entries; got ${value.length}`);
+	return value;
+}
+function planKey(value, path) {
+	if (typeof value !== "string" || !PLAN_KEY_PATTERN.test(value)) fail("invalid-key", path, "a key matches ^[a-z][a-z0-9_]{0,62}$");
+	if (RESERVED_KEYS.has(value)) fail("reserved-key", path, `"${value}" is a reserved key`);
+	return value;
+}
+function label(value, path) {
+	if (typeof value !== "string" || value.trim().length === 0 || value.length > MAX_LABEL) fail("invalid-value", path, `a non-empty string of at most ${MAX_LABEL}`);
+	return value;
+}
+function positiveInt(value, path, max) {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1 || value > max) fail("invalid-value", path, `an integer from 1 to ${max}`);
+	return value;
+}
+function optionalBoolean(value, path) {
+	if (value === void 0) return void 0;
+	if (typeof value !== "boolean") fail("invalid-value", path, "a boolean");
+	return value;
+}
+function keyList(value, path, max) {
+	const list = arrayOf(value, path, max);
+	if (list.length === 0) fail("invalid-value", path, "at least one key");
+	const seen = /* @__PURE__ */ new Set();
+	return {
+		keys: list.map((item, index) => {
+			const key = planKey(item, `${path}[${index}]`);
+			if (seen.has(key)) fail("duplicate-key", `${path}[${index}]`, `"${key}"`);
+			seen.add(key);
+			return key;
+		}),
+		paths: list.map((_, index) => `${path}[${index}]`)
+	};
+}
+var FIELD_KEYS = [
+	"key",
+	"label",
+	"type",
+	"required",
+	"column",
+	"calculated",
+	"cachedColumn",
+	"reference",
+	"choices",
+	"money"
+];
+function validateField(value, path, limits) {
+	const raw = closedObject(value, path, FIELD_KEYS);
+	const key = planKey(raw.key, `${path}.key`);
+	const fieldLabel = label(raw.label, `${path}.label`);
+	if (typeof raw.type !== "string" || !IMPORT_FIELD_TYPES.includes(raw.type)) fail("invalid-value", `${path}.type`, `one of ${IMPORT_FIELD_TYPES.join(", ")}`);
+	const type = raw.type;
+	const field = {
+		key,
+		label: fieldLabel,
+		type
+	};
+	const required = optionalBoolean(raw.required, `${path}.required`);
+	if (required !== void 0) field.required = required;
+	const sources = [
+		"column",
+		"calculated",
+		"reference"
+	].filter((name) => raw[name] !== void 0);
+	if (sources.length !== 1) fail("field-source", path, `exactly one of column, calculated or reference is required; got ${sources.length}`);
+	const source = sources[0];
+	if (source === "column") field.column = positiveInt(raw.column, `${path}.column`, MAX_COLUMN);
+	if (source === "calculated") field.calculated = raw.calculated;
+	if (raw.cachedColumn !== void 0) {
+		if (source !== "calculated") fail("field-source", `${path}.cachedColumn`, "cachedColumn belongs to calculated fields");
+		field.cachedColumn = positiveInt(raw.cachedColumn, `${path}.cachedColumn`, MAX_COLUMN);
+	}
+	if (source === "reference") {
+		if (type !== "reference") fail("field-source", `${path}.type`, "a reference field has type reference");
+		const ref = closedObject(raw.reference, `${path}.reference`, [
+			"table",
+			"by",
+			"columns"
+		]);
+		const by = keyList(ref.by, `${path}.reference.by`, 16);
+		const columnList = arrayOf(ref.columns, `${path}.reference.columns`, 16);
+		if (columnList.length !== by.keys.length) fail("reference-mismatch", `${path}.reference.columns`, "columns must pair one-to-one with by");
+		field.reference = {
+			table: planKey(ref.table, `${path}.reference.table`),
+			by: by.keys,
+			columns: columnList.map((column, index) => positiveInt(column, `${path}.reference.columns[${index}]`, MAX_COLUMN))
+		};
+	} else if (type === "reference") fail("field-source", `${path}.type`, "type reference needs a reference");
+	if (type === "choice") {
+		if (raw.choices === void 0) fail("invalid-value", `${path}.choices`, "a choice field needs choices");
+		const list = arrayOf(raw.choices, `${path}.choices`, limits.maxChoices);
+		if (list.length === 0) fail("invalid-value", `${path}.choices`, "a choice field needs choices");
+		const seen = /* @__PURE__ */ new Set();
+		field.choices = list.map((item, index) => {
+			if (typeof item !== "string" || item.length === 0 || item.length > MAX_LABEL || item !== item.trim()) fail("invalid-value", `${path}.choices[${index}]`, "a trimmed, non-empty string");
+			if (seen.has(item)) fail("duplicate-key", `${path}.choices[${index}]`, `"${item}"`);
+			seen.add(item);
+			return item;
+		});
+	} else if (raw.choices !== void 0) fail("invalid-value", `${path}.choices`, "choices belong to choice fields");
+	if (type === "money") {
+		const money = closedObject(raw.money, `${path}.money`, ["currency", "scale"]);
+		if (typeof money.currency !== "string" || !/^[A-Z]{3}$/.test(money.currency)) fail("invalid-value", `${path}.money.currency`, "a three-letter upper-case currency code");
+		if (typeof money.scale !== "number" || !Number.isInteger(money.scale) || money.scale < 0 || money.scale > 6) fail("invalid-value", `${path}.money.scale`, "an integer from 0 to 6");
+		field.money = {
+			currency: money.currency,
+			scale: money.scale
+		};
+	} else if (raw.money !== void 0) fail("invalid-value", `${path}.money`, "money belongs to money fields");
+	return field;
+}
+var TABLE_KEYS = [
+	"key",
+	"label",
+	"source",
+	"fields",
+	"lookupKey",
+	"titleField"
+];
+var SOURCE_KEYS = [
+	"sheet",
+	"range",
+	"headerRow",
+	"skipRows",
+	"distinct"
+];
+function validateTable(value, path, limits) {
+	const raw = closedObject(value, path, TABLE_KEYS);
+	const key = planKey(raw.key, `${path}.key`);
+	const tableLabel = label(raw.label, `${path}.label`);
+	const src = closedObject(raw.source, `${path}.source`, SOURCE_KEYS);
+	if (typeof src.sheet !== "string" || src.sheet.length === 0 || src.sheet.length > 255) fail("invalid-source", `${path}.source.sheet`, "a sheet name");
+	if (typeof src.range !== "string") fail("invalid-source", `${path}.source.range`, "an A1 range");
+	try {
+		range(src.range);
+	} catch {
+		fail("invalid-source", `${path}.source.range`, `"${src.range}" is not A1`);
+	}
+	const source = {
+		sheet: src.sheet,
+		range: src.range,
+		headerRow: positiveInt(src.headerRow, `${path}.source.headerRow`, MAX_ROW)
+	};
+	if (src.skipRows !== void 0) {
+		const rows = arrayOf(src.skipRows, `${path}.source.skipRows`, limits.maxSkipRows);
+		const seen = /* @__PURE__ */ new Set();
+		source.skipRows = rows.map((row, index) => {
+			const n = positiveInt(row, `${path}.source.skipRows[${index}]`, MAX_ROW);
+			if (seen.has(n)) fail("duplicate-key", `${path}.source.skipRows[${index}]`, `row ${n}`);
+			seen.add(n);
+			return n;
+		});
+	}
+	const distinct = optionalBoolean(src.distinct, `${path}.source.distinct`);
+	if (distinct !== void 0) source.distinct = distinct;
+	const fieldList = arrayOf(raw.fields, `${path}.fields`, limits.maxFieldsPerTable);
+	if (fieldList.length === 0) fail("invalid-value", `${path}.fields`, "a table needs at least one field");
+	const fields = fieldList.map((item, index) => validateField(item, `${path}.fields[${index}]`, limits));
+	if (!fields.some((field) => field.column !== void 0 || field.reference !== void 0 || field.cachedColumn !== void 0)) fail("no-row-source", `${path}.fields`, "a table needs a column, reference column or cachedColumn to establish rows");
+	const byKey = /* @__PURE__ */ new Map();
+	fields.forEach((field, index) => {
+		if (byKey.has(field.key)) fail("duplicate-key", `${path}.fields[${index}].key`, `"${field.key}"`);
+		byKey.set(field.key, field);
+	});
+	const table = {
+		key,
+		label: tableLabel,
+		source,
+		fields
+	};
+	if (raw.lookupKey !== void 0) {
+		const list = keyList(raw.lookupKey, `${path}.lookupKey`, 16);
+		list.keys.forEach((fieldKey, index) => {
+			const field = byKey.get(fieldKey);
+			if (!field) fail("unknown-field", list.paths[index], `no field "${fieldKey}"`);
+			if (field.column === void 0) fail("field-source", list.paths[index], "a lookup key field takes its value from a column");
+		});
+		table.lookupKey = list.keys;
+	}
+	if (raw.titleField !== void 0) {
+		const title = planKey(raw.titleField, `${path}.titleField`);
+		if (!byKey.has(title)) fail("unknown-field", `${path}.titleField`, `no field "${title}"`);
+		table.titleField = title;
+	}
+	return table;
+}
+function expressionColumns(root, path, limits) {
+	const found = /* @__PURE__ */ new Set();
+	const stack = [root];
+	let nodes = 0;
+	while (stack.length > 0) {
+		const node = stack.pop();
+		if (Array.isArray(node)) {
+			for (const item of node) stack.push(item);
+			continue;
+		}
+		if (!isRecord(node)) continue;
+		if (++nodes > limits.maxExpressionNodes) fail("invalid-expression", path, `more than ${limits.maxExpressionNodes} nodes`);
+		if (Object.hasOwn(node, "col")) {
+			if (Object.keys(node).length !== 1 || typeof node.col !== "string") fail("invalid-expression", path, "a column node is { col: string }");
+			found.add(node.col);
+			continue;
+		}
+		for (const item of Object.values(node)) stack.push(item);
+	}
+	return [...found];
+}
+var EXPRESSION_COLUMN_TYPE = {
+	text: "text",
+	choice: "text",
+	number: "number",
+	integer: "number",
+	money: "number",
+	boolean: "boolean",
+	date: "date",
+	reference: "unknown"
+};
+var EXPECTED_RESULT = {
+	text: ["text"],
+	choice: ["text"],
+	number: ["number"],
+	integer: ["number"],
+	money: ["number"],
+	boolean: ["boolean"],
+	date: ["date"],
+	reference: []
+};
+function validateCalculated(table, tablePath, limits) {
+	const siblings = new Map(table.fields.map((field) => [field.key, field]));
+	table.fields.forEach((field, index) => {
+		if (field.calculated === void 0) return;
+		const path = `${tablePath}.fields[${index}].calculated`;
+		if (field.type === "reference") fail("field-source", path, "a calculated field cannot be a reference");
+		for (const column of expressionColumns(field.calculated, path, limits)) {
+			const sibling = siblings.get(column);
+			if (!sibling) fail("expression-column", path, `"${column}" is not a field of this table`);
+			if (sibling.column === void 0) fail("expression-column", path, `"${column}" is not a column field; a calculated field reads column fields only`);
+		}
+		try {
+			const result = renderExpression(field.calculated, {
+				dialect: "sqlite",
+				mode: "ddl",
+				resolveColumn: (name) => {
+					const sibling = siblings.get(name);
+					return {
+						name,
+						type: sibling ? EXPRESSION_COLUMN_TYPE[sibling.type] : "unknown"
+					};
+				}
+			}).resultType;
+			if (result !== "unknown" && result !== "null" && !EXPECTED_RESULT[field.type].includes(result)) fail("expression-type", path, `expression yields ${result}, but the field is ${field.type}`);
+		} catch (error) {
+			if (error instanceof ImportPlanError) throw error;
+			if (error instanceof ExpressionError) fail("invalid-expression", path, `${error.code}: ${error.message}`);
+			fail("invalid-expression", path, error instanceof Error ? error.message : String(error));
+		}
+	});
+}
+function validateReferences(plan) {
+	const tables = new Map(plan.tables.map((table) => [table.key, table]));
+	const edges = /* @__PURE__ */ new Map();
+	plan.tables.forEach((table, tableIndex) => {
+		const out = /* @__PURE__ */ new Set();
+		edges.set(table.key, out);
+		table.fields.forEach((field, fieldIndex) => {
+			if (!field.reference) return;
+			const path = `tables[${tableIndex}].fields[${fieldIndex}].reference`;
+			const target = tables.get(field.reference.table);
+			if (!target) fail("unknown-table", `${path}.table`, `no table "${field.reference.table}"`);
+			const lookup = target.lookupKey;
+			if (!lookup || lookup.length !== field.reference.by.length || lookup.some((key, i) => key !== field.reference?.by[i])) fail("reference-mismatch", `${path}.by`, `must equal the lookupKey of "${target.key}"`);
+			out.add(target.key);
+		});
+	});
+	const state = /* @__PURE__ */ new Map();
+	const visit = (key, trail) => {
+		if (state.get(key) === 2) return;
+		if (state.get(key) === 1) fail("reference-cycle", "tables", `references form a cycle: ${[...trail.slice(trail.indexOf(key)), key].join(" -> ")}`);
+		state.set(key, 1);
+		for (const next of edges.get(key) ?? []) visit(next, [...trail, key]);
+		state.set(key, 2);
+	};
+	for (const table of plan.tables) visit(table.key, []);
+}
+function validatePlan(input, overrides = {}) {
+	const limits = {
+		...DEFAULT_PLAN_LIMITS,
+		...overrides
+	};
+	const raw = closedObject(toPlainData(input, limits), "", [
+		"version",
+		"tables",
+		"reports"
+	]);
+	if (raw.version !== 1) fail("unsupported-version", "version", "this package reads plan version 1");
+	const tableList = arrayOf(raw.tables, "tables", limits.maxTables);
+	if (tableList.length === 0) fail("invalid-value", "tables", "a plan needs at least one table");
+	const tables = tableList.map((item, index) => validateTable(item, `tables[${index}]`, limits));
+	const seen = /* @__PURE__ */ new Set();
+	tables.forEach((table, index) => {
+		if (seen.has(table.key)) fail("duplicate-key", `tables[${index}].key`, `"${table.key}"`);
+		seen.add(table.key);
+	});
+	const plan = {
+		version: 1,
+		tables
+	};
+	if (raw.reports !== void 0) {
+		const list = arrayOf(raw.reports, "reports", limits.maxReports);
+		const keys = /* @__PURE__ */ new Set();
+		plan.reports = list.map((item, index) => {
+			const path = `reports[${index}]`;
+			const report = closedObject(item, path, [
+				"key",
+				"label",
+				"spec"
+			]);
+			const key = planKey(report.key, `${path}.key`);
+			if (keys.has(key)) fail("duplicate-key", `${path}.key`, `"${key}"`);
+			keys.add(key);
+			return {
+				key,
+				label: label(report.label, `${path}.label`),
+				spec: report.spec
+			};
+		});
+	}
+	validateReferences(plan);
+	for (const [index, table] of tables.entries()) validateCalculated(table, `tables[${index}]`, limits);
+	return plan;
+}
+function loadOrder(plan) {
+	const order = [];
+	const done = /* @__PURE__ */ new Set();
+	const tables = new Map(plan.tables.map((table) => [table.key, table]));
+	const visit = (key) => {
+		if (done.has(key)) return;
+		done.add(key);
+		const table = tables.get(key);
+		if (!table) return;
+		for (const field of table.fields) if (field.reference) visit(field.reference.table);
+		order.push(key);
+	};
+	for (const table of plan.tables) visit(table.key);
+	return order;
+}
+//#endregion
+export { validatePlan as a, loadOrder as i, IMPORT_FIELD_TYPES as n, ImportPlanError as o, PLAN_KEY_PATTERN as r, ImportRunError as s, DEFAULT_PLAN_LIMITS as t };
+
+//# sourceMappingURL=plan-BAV2jEzl.js.map