qubu 0.0.0 → 0.3.3

package/dist/canonical-BbnqavJm.mjs

@@ -0,0 +1,972 @@
+//#region src/snapshot/types.ts
+/** The JSON object tag used by Qubu schema snapshots. */
+const schemaSnapshotFormat = "qubu-schema";
+/** The first canonical schema snapshot format version. */
+const schemaSnapshotVersion = 1;
+/** The first version of the dialect-extension envelope. */
+const schemaSnapshotDialectVersion = 1;
+/** The first version of the built-in naming-policy description. */
+const schemaSnapshotNamingPolicyVersion = 1;
+/** The neutral dialect used when no SQL engine adapter is selected. */
+const neutralSnapshotDialect = Object.freeze({
+	name: "neutral",
+	version: 1
+});
+//#endregion
+//#region src/snapshot/decode.ts
+/** Error raised by throwing snapshot APIs after collecting diagnostics. */
+var SnapshotValidationError = class extends TypeError {
+	name;
+	diagnostics;
+	issues;
+	constructor(diagnostics) {
+		const frozen = Object.freeze(diagnostics.map((diagnostic) => Object.freeze({
+			...diagnostic,
+			path: Object.freeze([...diagnostic.path]),
+			relatedPaths: diagnostic.relatedPaths ? Object.freeze(diagnostic.relatedPaths.map((path) => Object.freeze([...path]))) : void 0
+		})));
+		super(frozen.map((diagnostic) => diagnostic.message).join("\n"));
+		this.name = "SnapshotValidationError";
+		this.diagnostics = frozen;
+		this.issues = frozen;
+	}
+};
+/** Decode and strictly validate a JSON string or parsed snapshot value. */
+function decodeSchemaSnapshot(input) {
+	let value = input;
+	const diagnostics = [];
+	if (typeof input === "string") try {
+		value = JSON.parse(input);
+	} catch (error) {
+		return {
+			ok: false,
+			diagnostics: [diagnostic("invalid-snapshot", `Snapshot JSON could not be parsed: ${error instanceof Error ? error.message : String(error)}`, [])]
+		};
+	}
+	if (!isRecord(value)) return {
+		ok: false,
+		diagnostics: [diagnostic("invalid-snapshot", "Snapshot root must be an object", [])]
+	};
+	const snapshot = validateSnapshot(value, diagnostics);
+	if (diagnostics.length > 0 || snapshot === void 0) return {
+		ok: false,
+		diagnostics: Object.freeze(diagnostics)
+	};
+	return {
+		ok: true,
+		value: freezeSnapshot(snapshot)
+	};
+}
+/** Validate a snapshot and throw one structured error if it is malformed. */
+function assertSchemaSnapshot(input) {
+	const result = decodeSchemaSnapshot(input);
+	if (!result.ok) throw new SnapshotValidationError(result.diagnostics);
+	return result.value;
+}
+/** Return a fixed-order, deeply immutable copy of a valid snapshot. */
+function canonicalizeSchemaSnapshot(input) {
+	return assertSchemaSnapshot(input);
+}
+function validateSnapshot(value, diagnostics) {
+	requireKeys(value, [
+		"format",
+		"version",
+		"dialect",
+		"namingPolicy",
+		"namespace",
+		"tables"
+	], [], diagnostics, ["namespace"]);
+	if (value.format !== "qubu-schema") diagnostics.push(diagnostic("invalid-snapshot", `Snapshot format must be "${schemaSnapshotFormat}"`, ["format"]));
+	if (value.version !== 1) diagnostics.push(diagnostic(typeof value.version === "number" && value.version > 1 ? "future-version" : "invalid-snapshot", `Unsupported schema snapshot version: ${String(value.version)}`, ["version"]));
+	const dialect = validateDialect(value.dialect, ["dialect"], diagnostics);
+	const namingPolicy = validateNamingPolicy(value.namingPolicy, ["namingPolicy"], diagnostics);
+	if (value.namespace !== void 0) {
+		if (typeof value.namespace !== "string" || value.namespace.length === 0 || value.namespace !== value.namespace.trim() || /[.\\/\u0000-\u001f\u007f"']/u.test(value.namespace)) diagnostics.push(diagnostic("invalid-snapshot", "Snapshot namespace must be a non-empty identifier", ["namespace"]));
+	}
+	const tablesValue = value.tables;
+	const tables = [];
+	if (!Array.isArray(tablesValue)) diagnostics.push(diagnostic("invalid-snapshot", "Snapshot tables must be an array", ["tables"]));
+	else {
+		validateSortedIds(tablesValue, ["tables"], diagnostics);
+		for (const [index, table] of tablesValue.entries()) {
+			const validated = validateTable(table, ["tables", index], dialect?.name, diagnostics);
+			if (validated !== void 0) tables.push(validated);
+		}
+	}
+	if (dialect === void 0 || namingPolicy === void 0) return void 0;
+	validateCrossReferences(tables, diagnostics);
+	return {
+		format: schemaSnapshotFormat,
+		version: 1,
+		dialect,
+		namingPolicy,
+		...value.namespace !== void 0 ? { namespace: value.namespace } : {},
+		tables
+	};
+}
+function validateDialect(value, path, diagnostics) {
+	if (!isRecord(value)) {
+		diagnostics.push(diagnostic("invalid-snapshot", "Dialect must be an object", path));
+		return;
+	}
+	requireKeys(value, ["name", "version"], path, diagnostics);
+	if (typeof value.name !== "string" || value.name.length === 0) diagnostics.push(diagnostic("invalid-snapshot", "Dialect name must be non-empty", [...path, "name"]));
+	if (typeof value.version !== "number" || !Number.isSafeInteger(value.version) || value.version < 1) diagnostics.push(diagnostic("invalid-snapshot", "Dialect version must be a positive integer", [...path, "version"]));
+	else if (value.version > 1) diagnostics.push(diagnostic("future-version", `Unsupported dialect extension version: ${value.version}`, [...path, "version"]));
+	if (typeof value.name !== "string" || typeof value.version !== "number") return void 0;
+	return {
+		name: value.name,
+		version: value.version
+	};
+}
+function validateNamingPolicy(value, path, diagnostics) {
+	if (!isRecord(value)) {
+		diagnostics.push(diagnostic("invalid-snapshot", "Naming policy must be an object", path));
+		return;
+	}
+	requireKeys(value, ["name", "version"], path, diagnostics);
+	if (typeof value.name !== "string" || value.name.length === 0) diagnostics.push(diagnostic("invalid-snapshot", "Naming-policy name must be non-empty", [...path, "name"]));
+	if (value.version !== 1) diagnostics.push(diagnostic(typeof value.version === "number" && value.version > 1 ? "future-version" : "invalid-snapshot", `Unsupported naming-policy version: ${String(value.version)}`, [...path, "version"]));
+	if (typeof value.name !== "string" || typeof value.version !== "number") return void 0;
+	return {
+		name: value.name,
+		version: value.version
+	};
+}
+function validateTable(value, path, dialect, diagnostics) {
+	if (!isRecord(value)) {
+		diagnostics.push(diagnostic("invalid-snapshot", "Table must be an object", path));
+		return;
+	}
+	requireKeys(value, [
+		"id",
+		"physicalName",
+		"columns",
+		"constraints",
+		"indexes"
+	], path, diagnostics);
+	const id = validateId(value.id, [...path, "id"], diagnostics);
+	const physicalName = validateName(value.physicalName, [...path, "physicalName"], diagnostics);
+	const columns = validateArray(value.columns, [...path, "columns"], diagnostics, (item, itemPath) => validateColumn(item, itemPath, dialect, diagnostics));
+	const constraints = validateArray(value.constraints, [...path, "constraints"], diagnostics, (item, itemPath) => validateConstraint(item, itemPath, dialect, diagnostics));
+	const indexes = validateArray(value.indexes, [...path, "indexes"], diagnostics, (item, itemPath) => validateIndex(item, itemPath, dialect, diagnostics));
+	validateSortedIds(value.columns, [...path, "columns"], diagnostics);
+	validateSortedIds(value.constraints, [...path, "constraints"], diagnostics);
+	validateSortedIds(value.indexes, [...path, "indexes"], diagnostics);
+	if (id === void 0 || physicalName === void 0 || columns === void 0 || constraints === void 0 || indexes === void 0) return void 0;
+	return {
+		id,
+		physicalName,
+		columns,
+		constraints,
+		indexes
+	};
+}
+function validateColumn(value, path, dialect, diagnostics) {
+	if (!isRecord(value)) {
+		diagnostics.push(diagnostic("invalid-snapshot", "Column must be an object", path));
+		return;
+	}
+	requireKeys(value, [
+		"id",
+		"physicalName",
+		"nullable",
+		"hasDefault",
+		"generated",
+		"storage",
+		"default",
+		"generatedColumn",
+		"identity",
+		"onUpdate"
+	], path, diagnostics, [
+		"storage",
+		"default",
+		"generatedColumn",
+		"identity",
+		"onUpdate"
+	]);
+	const id = validateId(value.id, [...path, "id"], diagnostics);
+	const physicalName = validateName(value.physicalName, [...path, "physicalName"], diagnostics);
+	const nullable = validateBoolean(value.nullable, [...path, "nullable"], diagnostics);
+	const hasDefault = validateBoolean(value.hasDefault, [...path, "hasDefault"], diagnostics);
+	const generated = validateBoolean(value.generated, [...path, "generated"], diagnostics);
+	const storage = value.storage === void 0 ? void 0 : validateStorage(value.storage, [...path, "storage"], dialect, diagnostics);
+	const defaultValue = value.default === void 0 ? void 0 : validateDefault(value.default, [...path, "default"], dialect, diagnostics);
+	const generatedColumn = value.generatedColumn === void 0 ? void 0 : validateGenerated(value.generatedColumn, [...path, "generatedColumn"], dialect, diagnostics);
+	const identity = value.identity === void 0 ? void 0 : validateIdentity(value.identity, [...path, "identity"], dialect, diagnostics);
+	const onUpdate = value.onUpdate === void 0 ? void 0 : validateExpression(value.onUpdate, [...path, "onUpdate"], "default", dialect, diagnostics);
+	if (onUpdate !== void 0 && dialect !== "mysql") diagnostics.push(diagnostic("dialect-mismatch", "Column onUpdate metadata is only valid for MySQL snapshots", [...path, "onUpdate"]));
+	if (id === void 0 || physicalName === void 0 || nullable === void 0 || hasDefault === void 0 || generated === void 0) return void 0;
+	return {
+		id,
+		physicalName,
+		nullable,
+		hasDefault,
+		generated,
+		...storage === void 0 ? {} : { storage },
+		...defaultValue === void 0 ? {} : { default: defaultValue },
+		...generatedColumn === void 0 ? {} : { generatedColumn },
+		...identity === void 0 ? {} : { identity },
+		...onUpdate === void 0 ? {} : { onUpdate }
+	};
+}
+function validateStorage(value, path, snapshotDialect, diagnostics) {
+	if (!isRecord(value)) {
+		diagnostics.push(diagnostic("invalid-snapshot", "Storage must be an object", path));
+		return;
+	}
+	if (value.kind === "portable") {
+		requireKeys(value, ["kind", "type"], path, diagnostics);
+		const type = validateName(value.type, [...path, "type"], diagnostics);
+		return type === void 0 ? void 0 : {
+			kind: "portable",
+			type
+		};
+	}
+	if (value.kind === "native") {
+		requireKeys(value, [
+			"kind",
+			"dialect",
+			"type",
+			"affinity"
+		], path, diagnostics, ["affinity"]);
+		const storageDialect = validateName(value.dialect, [...path, "dialect"], diagnostics);
+		const type = validateName(value.type, [...path, "type"], diagnostics);
+		if (snapshotDialect !== void 0 && storageDialect !== void 0 && storageDialect !== snapshotDialect) diagnostics.push(diagnostic("dialect-mismatch", `Native storage belongs to "${storageDialect}" but snapshot dialect is "${snapshotDialect}"`, [...path, "dialect"]));
+		const affinityValue = value.affinity;
+		const affinity = affinityValue === void 0 || affinityValue === "blob" || affinityValue === "integer" || affinityValue === "numeric" || affinityValue === "real" || affinityValue === "text" ? affinityValue : void 0;
+		if (affinityValue !== void 0 && affinity === void 0) diagnostics.push(diagnostic("invalid-snapshot", "Storage affinity is invalid", [...path, "affinity"]));
+		if (affinity !== void 0 && snapshotDialect !== "sqlite") diagnostics.push(diagnostic("dialect-mismatch", "Storage affinity is only valid for SQLite snapshots", [...path, "affinity"]));
+		return storageDialect === void 0 || type === void 0 ? void 0 : {
+			kind: "native",
+			dialect: storageDialect,
+			type,
+			...affinity === void 0 ? {} : { affinity }
+		};
+	}
+	diagnostics.push(diagnostic("invalid-snapshot", "Storage kind must be portable or native", [...path, "kind"]));
+}
+function validateDefault(value, path, dialect, diagnostics) {
+	if (!isRecord(value)) {
+		diagnostics.push(diagnostic("invalid-snapshot", "Default must be an object", path));
+		return;
+	}
+	if (value.kind === "external") {
+		requireKeys(value, ["kind"], path, diagnostics);
+		return { kind: "external" };
+	}
+	if (value.kind === "literal") {
+		requireKeys(value, ["kind", "value"], path, diagnostics);
+		const literal = validateLiteral(value.value, [...path, "value"], diagnostics);
+		return literal === void 0 ? void 0 : {
+			kind: "literal",
+			value: literal
+		};
+	}
+	if (value.kind === "expression") {
+		requireKeys(value, ["kind", "expression"], path, diagnostics);
+		const expression = validateExpression(value.expression, [...path, "expression"], "default", dialect, diagnostics);
+		return expression === void 0 ? void 0 : {
+			kind: "expression",
+			expression
+		};
+	}
+	diagnostics.push(diagnostic("invalid-snapshot", "Default kind is invalid", [...path, "kind"]));
+}
+function validateGenerated(value, path, dialect, diagnostics) {
+	if (!isRecord(value)) {
+		diagnostics.push(diagnostic("invalid-snapshot", "Generated-column metadata must be an object", path));
+		return;
+	}
+	if (value.kind === "external") {
+		requireKeys(value, ["kind"], path, diagnostics);
+		return { kind: "external" };
+	}
+	if (value.kind === "expression") {
+		requireKeys(value, [
+			"kind",
+			"expression",
+			"mode"
+		], path, diagnostics);
+		const expression = validateExpression(value.expression, [...path, "expression"], "generated", dialect, diagnostics);
+		const mode = value.mode === "stored" || value.mode === "virtual" ? value.mode : void 0;
+		if (mode === void 0) diagnostics.push(diagnostic("invalid-snapshot", "Generated-column mode must be stored or virtual", [...path, "mode"]));
+		return expression === void 0 || mode === void 0 ? void 0 : {
+			kind: "expression",
+			expression,
+			mode
+		};
+	}
+	diagnostics.push(diagnostic("invalid-snapshot", "Generated-column kind is invalid", [...path, "kind"]));
+}
+function validateIdentity(value, path, dialect, diagnostics) {
+	if (!isRecord(value)) {
+		diagnostics.push(diagnostic("invalid-snapshot", "Identity must be an object", path));
+		return;
+	}
+	requireKeys(value, [
+		"kind",
+		"generation",
+		"dialect"
+	], path, diagnostics, ["dialect"]);
+	if (value.kind !== "identity") diagnostics.push(diagnostic("invalid-snapshot", "Identity kind must be identity", [...path, "kind"]));
+	if (value.generation !== "always" && value.generation !== "by-default") diagnostics.push(diagnostic("invalid-snapshot", "Identity generation is invalid", [...path, "generation"]));
+	if (value.kind !== "identity" || value.generation !== "always" && value.generation !== "by-default") return void 0;
+	const extension = validateExtension(value.dialect, [...path, "dialect"], dialect, diagnostics);
+	return {
+		kind: "identity",
+		generation: value.generation,
+		...extension === void 0 ? {} : { dialect: extension }
+	};
+}
+function validateConstraint(value, path, dialect, diagnostics) {
+	if (!isRecord(value)) {
+		diagnostics.push(diagnostic("invalid-snapshot", "Constraint must be an object", path));
+		return;
+	}
+	const common = validateConstraintCommon(value, path, diagnostics);
+	if (common === void 0) return void 0;
+	if (value.kind === "primary-key" || value.kind === "unique") {
+		requireKeys(value, [
+			"id",
+			"kind",
+			"physicalName",
+			"columns",
+			"deferrable",
+			"initially",
+			"dialect"
+		], path, diagnostics, [
+			"deferrable",
+			"initially",
+			"dialect"
+		]);
+		const columns = validateColumnIds(value.columns, [...path, "columns"], diagnostics);
+		const extra = validateConstraintTiming(value, path, diagnostics);
+		const extension = validateExtension(value.dialect, [...path, "dialect"], dialect, diagnostics);
+		if (columns === void 0 || extra === void 0) return void 0;
+		return {
+			...common,
+			kind: value.kind,
+			columns,
+			...extra,
+			...extension === void 0 ? {} : { dialect: extension }
+		};
+	}
+	if (value.kind === "unique-constraint") {
+		requireKeys(value, [
+			"id",
+			"kind",
+			"physicalName",
+			"columns",
+			"nulls",
+			"deferrable",
+			"initially",
+			"dialect"
+		], path, diagnostics, [
+			"deferrable",
+			"initially",
+			"dialect"
+		]);
+		const columns = validateColumnIds(value.columns, [...path, "columns"], diagnostics);
+		const extra = validateConstraintTiming(value, path, diagnostics);
+		const extension = validateExtension(value.dialect, [...path, "dialect"], dialect, diagnostics);
+		if (value.nulls !== "distinct" && value.nulls !== "not-distinct") diagnostics.push(diagnostic("invalid-snapshot", "Unique-constraint null semantics are invalid", [...path, "nulls"]));
+		if (columns === void 0 || extra === void 0 || value.nulls !== "distinct" && value.nulls !== "not-distinct") return void 0;
+		return {
+			...common,
+			kind: "unique-constraint",
+			columns,
+			nulls: value.nulls,
+			...extra,
+			...extension === void 0 ? {} : { dialect: extension }
+		};
+	}
+	if (value.kind === "foreign-key") {
+		requireKeys(value, [
+			"id",
+			"kind",
+			"physicalName",
+			"columns",
+			"target",
+			"onUpdate",
+			"onDelete",
+			"match",
+			"deferrable",
+			"initially",
+			"dialect"
+		], path, diagnostics, [
+			"onUpdate",
+			"onDelete",
+			"match",
+			"deferrable",
+			"initially",
+			"dialect"
+		]);
+		const columns = validateColumnIds(value.columns, [...path, "columns"], diagnostics);
+		const target = validateForeignKeyTarget(value.target, [...path, "target"], diagnostics);
+		const extra = validateForeignKeyOptions(value, path, diagnostics);
+		const extension = validateExtension(value.dialect, [...path, "dialect"], dialect, diagnostics);
+		if (columns === void 0 || target === void 0 || extra === void 0) return void 0;
+		return {
+			...common,
+			kind: "foreign-key",
+			columns,
+			target,
+			...extra,
+			...extension === void 0 ? {} : { dialect: extension }
+		};
+	}
+	if (value.kind === "check") {
+		requireKeys(value, [
+			"id",
+			"kind",
+			"physicalName",
+			"expression",
+			"deferrable",
+			"initially",
+			"dialect"
+		], path, diagnostics, [
+			"deferrable",
+			"initially",
+			"dialect"
+		]);
+		const expression = validateExpression(value.expression, [...path, "expression"], "check", dialect, diagnostics);
+		const extra = validateConstraintTiming(value, path, diagnostics);
+		const extension = validateExtension(value.dialect, [...path, "dialect"], dialect, diagnostics);
+		if (expression === void 0 || extra === void 0) return void 0;
+		return {
+			...common,
+			kind: "check",
+			expression,
+			...extra,
+			...extension === void 0 ? {} : { dialect: extension }
+		};
+	}
+	diagnostics.push(diagnostic("invalid-snapshot", `Unknown constraint kind: ${String(value.kind)}`, [...path, "kind"]));
+}
+function validateConstraintCommon(value, path, diagnostics) {
+	const id = validateId(value.id, [...path, "id"], diagnostics);
+	const physicalName = validateName(value.physicalName, [...path, "physicalName"], diagnostics);
+	if (id === void 0 || physicalName === void 0) return void 0;
+	return {
+		id,
+		kind: value.kind,
+		physicalName
+	};
+}
+function validateConstraintTiming(value, path, diagnostics) {
+	const deferrable = validateOptionalBoolean(value.deferrable, [...path, "deferrable"], diagnostics);
+	const initially = value.initially === void 0 ? void 0 : value.initially === "immediate" || value.initially === "deferred" ? value.initially : void 0;
+	if (value.initially !== void 0 && initially === void 0) diagnostics.push(diagnostic("invalid-snapshot", "Constraint timing is invalid", [...path, "initially"]));
+	if (deferrable === void 0 && value.deferrable !== void 0) return void 0;
+	if (value.initially !== void 0 && initially === void 0) return void 0;
+	return {
+		...deferrable === void 0 ? {} : { deferrable },
+		...initially === void 0 ? {} : { initially }
+	};
+}
+function validateForeignKeyOptions(value, path, diagnostics) {
+	const action = (key) => {
+		const candidate = value[key];
+		if (candidate === void 0) return void 0;
+		if (candidate === "no-action" || candidate === "restrict" || candidate === "cascade" || candidate === "set-null" || candidate === "set-default") return candidate;
+		diagnostics.push(diagnostic("invalid-snapshot", `Foreign-key ${key} action is invalid`, [...path, key]));
+	};
+	const onUpdate = action("onUpdate");
+	const onDelete = action("onDelete");
+	const match = value.match === void 0 ? void 0 : value.match === "simple" || value.match === "full" || value.match === "partial" ? value.match : void 0;
+	if (value.match !== void 0 && match === void 0) diagnostics.push(diagnostic("invalid-snapshot", "Foreign-key match mode is invalid", [...path, "match"]));
+	const timing = validateConstraintTiming(value, path, diagnostics);
+	if (timing === void 0 || value.onUpdate !== void 0 && onUpdate === void 0 || value.onDelete !== void 0 && onDelete === void 0 || value.match !== void 0 && match === void 0) return void 0;
+	return {
+		...onUpdate === void 0 ? {} : { onUpdate },
+		...onDelete === void 0 ? {} : { onDelete },
+		...match === void 0 ? {} : { match },
+		...timing
+	};
+}
+function validateForeignKeyTarget(value, path, diagnostics) {
+	if (!isRecord(value)) {
+		diagnostics.push(diagnostic("invalid-snapshot", "Foreign-key target must be an object", path));
+		return;
+	}
+	requireKeys(value, ["table", "columns"], path, diagnostics);
+	const table = validateId(value.table, [...path, "table"], diagnostics);
+	const columns = validateColumnIds(value.columns, [...path, "columns"], diagnostics);
+	return table === void 0 || columns === void 0 ? void 0 : {
+		table,
+		columns
+	};
+}
+function validateIndex(value, path, dialect, diagnostics) {
+	if (!isRecord(value)) {
+		diagnostics.push(diagnostic("invalid-snapshot", "Index must be an object", path));
+		return;
+	}
+	requireKeys(value, [
+		"id",
+		"kind",
+		"physicalName",
+		"terms",
+		"unique",
+		"candidateKey",
+		"predicate",
+		"includedColumns",
+		"dialect"
+	], path, diagnostics, [
+		"predicate",
+		"includedColumns",
+		"dialect"
+	]);
+	const id = validateId(value.id, [...path, "id"], diagnostics);
+	const physicalName = validateName(value.physicalName, [...path, "physicalName"], diagnostics);
+	if (value.kind !== "index") diagnostics.push(diagnostic("invalid-snapshot", "Index kind must be index", [...path, "kind"]));
+	const unique = validateBoolean(value.unique, [...path, "unique"], diagnostics);
+	const candidateKey = validateBoolean(value.candidateKey, [...path, "candidateKey"], diagnostics);
+	const terms = validateArray(value.terms, [...path, "terms"], diagnostics, (item, itemPath) => validateIndexTerm(item, itemPath, dialect, diagnostics));
+	const predicate = value.predicate === void 0 ? void 0 : validateExpression(value.predicate, [...path, "predicate"], "index", dialect, diagnostics);
+	const includedColumns = value.includedColumns === void 0 ? void 0 : validateColumnIds(value.includedColumns, [...path, "includedColumns"], diagnostics);
+	const extension = validateExtension(value.dialect, [...path, "dialect"], dialect, diagnostics);
+	if (id === void 0 || physicalName === void 0 || unique === void 0 || candidateKey === void 0 || terms === void 0 || value.kind !== "index" || terms.length === 0) return void 0;
+	return {
+		id,
+		kind: "index",
+		physicalName,
+		terms,
+		unique,
+		candidateKey,
+		...predicate === void 0 ? {} : { predicate },
+		...includedColumns === void 0 ? {} : { includedColumns },
+		...extension === void 0 ? {} : { dialect: extension }
+	};
+}
+function validateIndexTerm(value, path, dialect, diagnostics) {
+	if (!isRecord(value)) {
+		diagnostics.push(diagnostic("invalid-snapshot", "Index term must be an object", path));
+		return;
+	}
+	if (value.kind === "column") {
+		requireKeys(value, ["kind", "column"], path, diagnostics);
+		const column = validateId(value.column, [...path, "column"], diagnostics);
+		return column === void 0 ? void 0 : {
+			kind: "column",
+			column
+		};
+	}
+	if (value.kind === "expression") {
+		requireKeys(value, ["kind", "expression"], path, diagnostics);
+		const expression = validateExpression(value.expression, [...path, "expression"], "index", dialect, diagnostics);
+		return expression === void 0 ? void 0 : {
+			kind: "expression",
+			expression
+		};
+	}
+	if (value.kind === "order") {
+		requireKeys(value, [
+			"kind",
+			"expression",
+			"direction",
+			"nulls"
+		], path, diagnostics, ["direction", "nulls"]);
+		const expression = validateIndexTermExpression(value.expression, [...path, "expression"], dialect, diagnostics);
+		const direction = value.direction === void 0 ? void 0 : value.direction === "ASC" || value.direction === "DESC" ? value.direction : void 0;
+		const nulls = value.nulls === void 0 ? void 0 : value.nulls === "FIRST" || value.nulls === "LAST" ? value.nulls : void 0;
+		if (value.direction !== void 0 && direction === void 0) diagnostics.push(diagnostic("invalid-snapshot", "Index order direction is invalid", [...path, "direction"]));
+		if (value.nulls !== void 0 && nulls === void 0) diagnostics.push(diagnostic("invalid-snapshot", "Index NULL ordering is invalid", [...path, "nulls"]));
+		if (expression === void 0 || value.direction !== void 0 && direction === void 0 || value.nulls !== void 0 && nulls === void 0) return void 0;
+		return {
+			kind: "order",
+			expression,
+			...direction === void 0 ? {} : { direction },
+			...nulls === void 0 ? {} : { nulls }
+		};
+	}
+	diagnostics.push(diagnostic("invalid-snapshot", "Index term kind is invalid", [...path, "kind"]));
+}
+function validateIndexTermExpression(value, path, dialect, diagnostics) {
+	if (!isRecord(value)) {
+		diagnostics.push(diagnostic("invalid-snapshot", "Index expression must be an object", path));
+		return;
+	}
+	if (value.kind === "column") {
+		requireKeys(value, ["kind", "column"], path, diagnostics);
+		const column = validateId(value.column, [...path, "column"], diagnostics);
+		return column === void 0 ? void 0 : {
+			kind: "column",
+			column
+		};
+	}
+	if (value.kind === "expression") {
+		requireKeys(value, ["kind", "expression"], path, diagnostics);
+		const expression = validateExpression(value.expression, [...path, "expression"], "index", dialect, diagnostics);
+		return expression === void 0 ? void 0 : {
+			kind: "expression",
+			expression
+		};
+	}
+	diagnostics.push(diagnostic("invalid-snapshot", "Index expression kind is invalid", [...path, "kind"]));
+}
+function validateExpression(value, path, _mode, dialect, diagnostics) {
+	if (!isRecord(value)) {
+		diagnostics.push(diagnostic("invalid-snapshot", "Expression must be an object", path));
+		return;
+	}
+	requireKeys(value, [
+		"kind",
+		"expressionKind",
+		"sql",
+		"dialect"
+	], path, diagnostics, ["dialect"]);
+	const expressionKind = validateName(value.expressionKind, [...path, "expressionKind"], diagnostics);
+	const sql = typeof value.sql === "string" ? value.sql : void 0;
+	if (sql === void 0) diagnostics.push(diagnostic("invalid-snapshot", "Expression SQL must be a string", [...path, "sql"]));
+	if (value.kind !== "expression") diagnostics.push(diagnostic("invalid-snapshot", "Expression kind must be expression", [...path, "kind"]));
+	const expressionDialect = value.dialect === void 0 ? void 0 : validateName(value.dialect, [...path, "dialect"], diagnostics);
+	if (expressionDialect !== void 0 && dialect !== void 0 && expressionDialect !== dialect) diagnostics.push(diagnostic("dialect-mismatch", `Expression dialect "${expressionDialect}" does not match snapshot dialect "${dialect}"`, [...path, "dialect"]));
+	if (expressionDialect !== void 0 && value.expressionKind !== "unsafe") diagnostics.push(diagnostic("invalid-snapshot", "Only unsafe expressions may carry a dialect tag", [...path, "dialect"]));
+	if (expressionDialect === void 0 && value.expressionKind === "unsafe") diagnostics.push(diagnostic("invalid-snapshot", "Unsafe expressions must carry a dialect tag", [...path, "dialect"]));
+	if (sql !== void 0 && sql !== sql.replace(/\r\n?/g, "\n")) diagnostics.push(diagnostic("non-canonical", "Expression SQL must use LF line endings", [...path, "sql"]));
+	if (expressionKind === void 0 || sql === void 0 || value.kind !== "expression") return void 0;
+	return {
+		kind: "expression",
+		expressionKind,
+		sql,
+		...expressionDialect === void 0 ? {} : { dialect: expressionDialect }
+	};
+}
+function validateLiteral(value, path, diagnostics) {
+	if (!isRecord(value)) {
+		diagnostics.push(diagnostic("invalid-snapshot", "Literal must be an object", path));
+		return;
+	}
+	if (value.kind === "null") {
+		requireKeys(value, ["kind"], path, diagnostics);
+		return { kind: "null" };
+	}
+	if (value.kind === "boolean") {
+		requireKeys(value, ["kind", "value"], path, diagnostics);
+		if (typeof value.value !== "boolean") diagnostics.push(diagnostic("invalid-snapshot", "Boolean literal value must be boolean", [...path, "value"]));
+		return typeof value.value === "boolean" ? {
+			kind: "boolean",
+			value: value.value
+		} : void 0;
+	}
+	if (value.kind === "string") {
+		requireKeys(value, ["kind", "value"], path, diagnostics);
+		if (typeof value.value !== "string") diagnostics.push(diagnostic("invalid-snapshot", "String literal value must be string", [...path, "value"]));
+		return typeof value.value === "string" ? {
+			kind: "string",
+			value: value.value
+		} : void 0;
+	}
+	if (value.kind === "number" || value.kind === "bigint") {
+		requireKeys(value, ["kind", "value"], path, diagnostics);
+		if (typeof value.value !== "string" || !isCanonicalIntegerOrNumber(value.value, value.kind === "bigint")) diagnostics.push(diagnostic("invalid-snapshot", `${value.kind} literal value is not canonical`, [...path, "value"]));
+		return typeof value.value === "string" && isCanonicalIntegerOrNumber(value.value, value.kind === "bigint") ? {
+			kind: value.kind,
+			value: value.value
+		} : void 0;
+	}
+	diagnostics.push(diagnostic("invalid-snapshot", "Literal kind is invalid", [...path, "kind"]));
+}
+function validateExtension(value, path, dialect, diagnostics) {
+	if (value === void 0) return void 0;
+	if (!isRecord(value)) {
+		diagnostics.push(diagnostic("invalid-snapshot", "Dialect extension must be an object", path));
+		return;
+	}
+	requireKeys(value, [
+		"dialect",
+		"version",
+		"data"
+	], path, diagnostics);
+	const extensionDialect = validateName(value.dialect, [...path, "dialect"], diagnostics);
+	const version = value.version;
+	if (typeof version !== "number" || !Number.isSafeInteger(version) || version < 1) diagnostics.push(diagnostic("invalid-snapshot", "Dialect extension version must be a positive integer", [...path, "version"]));
+	else if (version > 1) diagnostics.push(diagnostic("future-version", `Unsupported dialect extension version: ${version}`, [...path, "version"]));
+	if (extensionDialect !== void 0 && dialect !== void 0 && extensionDialect !== dialect) diagnostics.push(diagnostic("dialect-mismatch", `Dialect extension belongs to "${extensionDialect}" but snapshot dialect is "${dialect}"`, [...path, "dialect"]));
+	const data = validateJsonValue(value.data, [...path, "data"], diagnostics);
+	if (extensionDialect === void 0 || typeof version !== "number" || data === void 0) return void 0;
+	return {
+		dialect: extensionDialect,
+		version,
+		data
+	};
+}
+function validateJsonValue(value, path, diagnostics, seen = /* @__PURE__ */ new WeakSet()) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) diagnostics.push(diagnostic("invalid-value", "Non-finite JSON numbers must use a tagged value", path));
+		return Number.isFinite(value) ? value : void 0;
+	}
+	if (typeof value !== "object") {
+		diagnostics.push(diagnostic("invalid-value", "Dialect data contains an unsupported value", path));
+		return;
+	}
+	if (seen.has(value)) {
+		diagnostics.push(diagnostic("invalid-value", "Dialect data cannot be cyclic", path));
+		return;
+	}
+	seen.add(value);
+	try {
+		if (Array.isArray(value)) return value.map((item, index) => validateJsonValue(item, [...path, index], diagnostics, seen));
+		if (!isRecord(value)) {
+			diagnostics.push(diagnostic("invalid-value", "Dialect data must use plain objects", path));
+			return;
+		}
+		if (Object.keys(value).length === 1 && "$bigint" in value) {
+			if (typeof value.$bigint !== "string" || /^-(0|[1-9]\d*)$/u.test(value.$bigint) === false && /^(0|[1-9]\d*)$/u.test(value.$bigint) === false) diagnostics.push(diagnostic("invalid-value", "Tagged bigint is not canonical", [...path, "$bigint"]));
+			return typeof value.$bigint === "string" ? { $bigint: value.$bigint } : void 0;
+		}
+		if (Object.keys(value).length === 1 && "$number" in value) {
+			if (value.$number !== "NaN" && value.$number !== "Infinity" && value.$number !== "-Infinity") diagnostics.push(diagnostic("invalid-value", "Tagged number is invalid", [...path, "$number"]));
+			return value.$number === "NaN" || value.$number === "Infinity" || value.$number === "-Infinity" ? { $number: value.$number } : void 0;
+		}
+		const result = {};
+		for (const key of Object.keys(value).sort()) {
+			const nested = validateJsonValue(value[key], [...path, key], diagnostics, seen);
+			if (nested !== void 0) result[key] = nested;
+		}
+		return result;
+	} finally {
+		seen.delete(value);
+	}
+}
+function validateCrossReferences(tables, diagnostics) {
+	const tableMap = new Map(tables.map((table) => [table.id, table]));
+	for (const [tableIndex, table] of tables.entries()) {
+		const columnSet = new Set(table.columns.map((column) => column.id));
+		for (const [constraintIndex, constraint] of table.constraints.entries()) {
+			if (constraint.kind !== "check") {
+				for (const [columnIndex, column] of constraint.columns.entries()) if (!columnSet.has(column)) diagnostics.push(diagnostic("invalid-cross-reference", `Constraint column "${column}" is not declared on table "${table.id}"`, [
+					"tables",
+					tableIndex,
+					"constraints",
+					constraintIndex,
+					"columns",
+					columnIndex
+				]));
+			}
+			if (constraint.kind === "foreign-key") {
+				const target = tableMap.get(constraint.target.table);
+				if (target === void 0) diagnostics.push(diagnostic("invalid-cross-reference", `Foreign-key target table "${constraint.target.table}" does not exist`, [
+					"tables",
+					tableIndex,
+					"constraints",
+					constraintIndex,
+					"target",
+					"table"
+				]));
+				else for (const [columnIndex, column] of constraint.target.columns.entries()) if (!target.columns.some((targetColumn) => targetColumn.id === column)) diagnostics.push(diagnostic("invalid-cross-reference", `Foreign-key target column "${column}" is not declared on table "${target.id}"`, [
+					"tables",
+					tableIndex,
+					"constraints",
+					constraintIndex,
+					"target",
+					"columns",
+					columnIndex
+				]));
+			}
+		}
+		for (const [indexIndex, index] of table.indexes.entries()) {
+			for (const [termIndex, term] of index.terms.entries()) {
+				const expression = term.kind === "order" ? term.expression : term;
+				if (expression.kind === "column" && !columnSet.has(expression.column)) diagnostics.push(diagnostic("invalid-cross-reference", `Index column "${expression.column}" is not declared on table "${table.id}"`, [
+					"tables",
+					tableIndex,
+					"indexes",
+					indexIndex,
+					"terms",
+					termIndex
+				]));
+			}
+			for (const [columnIndex, column] of (index.includedColumns ?? []).entries()) if (!columnSet.has(column)) diagnostics.push(diagnostic("invalid-cross-reference", `Included index column "${column}" is not declared on table "${table.id}"`, [
+				"tables",
+				tableIndex,
+				"indexes",
+				indexIndex,
+				"includedColumns",
+				columnIndex
+			]));
+		}
+	}
+}
+function validateColumnIds(value, path, diagnostics) {
+	if (!Array.isArray(value)) {
+		diagnostics.push(diagnostic("invalid-snapshot", "Column references must be an array", path));
+		return;
+	}
+	const result = [];
+	for (const [index, item] of value.entries()) {
+		const id = validateId(item, [...path, index], diagnostics);
+		if (id !== void 0) result.push(id);
+	}
+	if (result.length === 0) diagnostics.push(diagnostic("invalid-snapshot", "Column references cannot be empty", path));
+	return result;
+}
+function validateArray(value, path, diagnostics, validate) {
+	if (!Array.isArray(value)) {
+		diagnostics.push(diagnostic("invalid-snapshot", "Value must be an array", path));
+		return;
+	}
+	const result = [];
+	for (const [index, item] of value.entries()) {
+		const validated = validate(item, [...path, index]);
+		if (validated !== void 0) result.push(validated);
+	}
+	return result;
+}
+function validateSortedIds(value, path, diagnostics) {
+	if (!Array.isArray(value)) return;
+	let previous;
+	for (const [index, item] of value.entries()) {
+		if (!isRecord(item) || typeof item.id !== "string") continue;
+		if (previous !== void 0 && item.id <= previous) diagnostics.push(diagnostic("non-canonical", "Entities must be sorted by stable logical ID", [
+			...path,
+			index,
+			"id"
+		]));
+		previous = item.id;
+	}
+}
+function validateId(value, path, diagnostics) {
+	if (typeof value !== "string" || value.length === 0 || value !== value.trim() || /[.\\/\u0000-\u001f\u007f]/u.test(value)) {
+		diagnostics.push(diagnostic("invalid-snapshot", "Logical IDs must be non-empty identifiers", path));
+		return;
+	}
+	return value;
+}
+function validateName(value, path, diagnostics) {
+	if (typeof value !== "string" || value.length === 0 || value !== value.trim() || /[\u0000-\u001f\u007f]/u.test(value)) {
+		diagnostics.push(diagnostic("invalid-snapshot", "Physical names must be non-empty strings without control characters", path));
+		return;
+	}
+	return value;
+}
+function validateBoolean(value, path, diagnostics) {
+	if (typeof value !== "boolean") {
+		diagnostics.push(diagnostic("invalid-snapshot", "Value must be boolean", path));
+		return;
+	}
+	return value;
+}
+function validateOptionalBoolean(value, path, diagnostics) {
+	return value === void 0 ? void 0 : validateBoolean(value, path, diagnostics);
+}
+function isCanonicalIntegerOrNumber(value, integer) {
+	if (integer) return /^-(0|[1-9]\d*)$/u.test(value) || /^(0|[1-9]\d*)$/u.test(value);
+	if (value === "0") return true;
+	return /^-(0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?$/u.test(value) || /^(0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?$/u.test(value);
+}
+function requireKeys(value, required, path, diagnostics, optional = []) {
+	for (const key of required) if (!(key in value) && !optional.includes(key)) diagnostics.push(diagnostic("invalid-snapshot", `Missing required field "${key}"`, [...path, key]));
+	const allowed = /* @__PURE__ */ new Set([...required, ...optional]);
+	for (const key of Object.keys(value)) if (!allowed.has(key)) diagnostics.push(diagnostic("unknown-field", `Unknown snapshot field "${key}"`, [...path, key]));
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+}
+function diagnostic(code, message, path) {
+	return {
+		code,
+		message,
+		path: Object.freeze([...path])
+	};
+}
+function freezeSnapshot(snapshot) {
+	return deepFreeze(snapshot);
+}
+function deepFreeze(value) {
+	if (typeof value !== "object" || value === null || Object.isFrozen(value)) return value;
+	for (const nested of Object.values(value)) deepFreeze(nested);
+	return Object.freeze(value);
+}
+//#endregion
+//#region src/snapshot/canonical.ts
+/** Error raised when a value cannot cross the canonical JSON boundary. */
+var SnapshotCanonicalError = class extends TypeError {
+	path;
+	constructor(message, path = []) {
+		super(message);
+		this.name = "SnapshotCanonicalError";
+		this.path = Object.freeze([...path]);
+	}
+};
+/** Convert a JavaScript value to the explicit JSON-safe snapshot domain. */
+function toSnapshotJsonValue(value, path = [], seen = /* @__PURE__ */ new WeakSet()) {
+	if (value === null) return null;
+	switch (typeof value) {
+		case "string":
+		case "boolean": return value;
+		case "number":
+			if (Number.isNaN(value)) return { $number: "NaN" };
+			if (value === Infinity) return { $number: "Infinity" };
+			if (value === -Infinity) return { $number: "-Infinity" };
+			return Object.is(value, -0) ? 0 : value;
+		case "bigint": return { $bigint: value.toString() };
+		case "undefined":
+		case "function":
+		case "symbol": throw new SnapshotCanonicalError(`Snapshot values cannot contain ${typeof value}`, path);
+		case "object": break;
+		default: throw new SnapshotCanonicalError("Unsupported snapshot value", path);
+	}
+	if (seen.has(value)) throw new SnapshotCanonicalError("Snapshot values cannot be cyclic", path);
+	seen.add(value);
+	try {
+		if (Array.isArray(value)) return Object.freeze(value.map((item, index) => toSnapshotJsonValue(item, [...path, index], seen)));
+		const prototype = Object.getPrototypeOf(value);
+		if (prototype !== Object.prototype && prototype !== null) throw new SnapshotCanonicalError("Snapshot values must be plain objects, arrays, or scalar values", path);
+		const result = {};
+		for (const key of Object.keys(value).sort()) result[key] = toSnapshotJsonValue(value[key], [...path, key], seen);
+		return Object.freeze(result);
+	} finally {
+		seen.delete(value);
+	}
+}
+/** Render a JSON-safe value with deterministic scalar and object handling. */
+function canonicalJson(value) {
+	if (value === null) return "null";
+	if (typeof value === "string") return JSON.stringify(value);
+	if (typeof value === "boolean") return value ? "true" : "false";
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new SnapshotCanonicalError("Non-finite numbers must use a tagged snapshot number");
+		return Object.is(value, -0) ? "0" : JSON.stringify(value);
+	}
+	if (Array.isArray(value)) return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+	if (isSpecialNumber(value)) return `{"$number":${JSON.stringify(value.$number)}}`;
+	if (isBigInt(value)) return `{"$bigint":${JSON.stringify(value.$bigint)}}`;
+	const objectValue = value;
+	return `{${Object.keys(objectValue).map((key) => `${JSON.stringify(key)}:${canonicalJson(objectValue[key])}`).join(",")}}`;
+}
+/** Canonical JSON for a schema snapshot after fixed-order reconstruction. */
+function encodeCanonicalSnapshot(snapshot) {
+	return canonicalJson(snapshot);
+}
+/**
+* Compute a small deterministic content digest for cache keys and diagnostics.
+* It is deliberately not an entity identity, signature, or migration lineage.
+*/
+function schemaSnapshotDigest(snapshot) {
+	const source = encodeCanonicalSnapshot(assertSchemaSnapshot(snapshot));
+	let hash = 14695981039346656037n;
+	const prime = 1099511628211n;
+	const mask = 18446744073709551615n;
+	for (let index = 0; index < source.length; index += 1) {
+		const codePoint = source.codePointAt(index) ?? 0;
+		if (codePoint > 65535) index += 1;
+		const bytes = new TextEncoder().encode(String.fromCodePoint(codePoint));
+		for (const byte of bytes) {
+			hash ^= BigInt(byte);
+			hash = hash * prime & mask;
+		}
+	}
+	return `fnv1a64:${hash.toString(16).padStart(16, "0")}`;
+}
+function isSpecialNumber(value) {
+	return Object.keys(value).length === 1 && "$number" in value && value.$number !== void 0;
+}
+function isBigInt(value) {
+	return Object.keys(value).length === 1 && "$bigint" in value && typeof value.$bigint === "string";
+}
+//#endregion
+export { toSnapshotJsonValue as a, canonicalizeSchemaSnapshot as c, schemaSnapshotDialectVersion as d, schemaSnapshotFormat as f, schemaSnapshotDigest as i, decodeSchemaSnapshot as l, schemaSnapshotVersion as m, canonicalJson as n, SnapshotValidationError as o, schemaSnapshotNamingPolicyVersion as p, encodeCanonicalSnapshot as r, assertSchemaSnapshot as s, SnapshotCanonicalError as t, neutralSnapshotDialect as u };