@voltro/database 0.85.0 → 0.86.0

package/dist/relations.js

@@ -0,0 +1,69 @@
+import { authoredError as e } from "./dbCause.js";
+//#region src/relations.ts
+var t = (e) => typeof e == "function" ? e : () => e, n = (e, n) => ({
+	kind: "one",
+	target: t(e),
+	...n?.foreignKey === void 0 ? {} : { foreignKey: n.foreignKey },
+	...n?.sourceKey === void 0 ? {} : { sourceKey: n.sourceKey }
+}), r = (e, n) => ({
+	kind: "many",
+	target: t(e),
+	...n?.foreignKey === void 0 ? {} : { foreignKey: n.foreignKey },
+	...n?.sourceKey === void 0 ? {} : { sourceKey: n.sourceKey }
+}), i = (e, n) => ({
+	kind: "manyToMany",
+	target: t(e),
+	through: t(n.through),
+	sourceKey: n.sourceKey,
+	targetKey: n.targetKey
+}), a = {
+	one: n,
+	many: r,
+	manyToMany: i
+}, o = (e, t) => {
+	let n = typeof e == "function" ? e : () => e;
+	return {
+		source: n,
+		relations: t(a, n())
+	};
+}, s = (e) => {
+	if (typeof e != "object" || !e) return !1;
+	let t = e;
+	return typeof t.source != "function" || typeof t.relations != "object" || t.relations === null ? !1 : Object.keys(t.relations).length === 0;
+}, c = (e) => {
+	if (typeof e != "object" || !e) return !1;
+	let t = e;
+	if (typeof t.source != "function" || typeof t.relations != "object" || t.relations === null) return !1;
+	let n = Object.values(t.relations);
+	return n.length !== 0 && n.every((e) => {
+		let t = e?.kind;
+		return t === "one" || t === "many" || t === "manyToMany";
+	});
+}, l = n, u = r, d = i, f = (t, n, r) => {
+	let i = [];
+	for (let [e, r] of Object.entries(t.fields)) r.type === "reference" && r.references?.()?.tableName === n && i.push(e);
+	if (i.length === 0) throw e(`relation '${r}': no reference() column on '${t.tableName}' points at '${n}'. Either add one or pass an explicit { foreignKey: '<column>' }.`);
+	if (i.length > 1) throw e(`relation '${r}': multiple reference() columns on '${t.tableName}' point at '${n}' (${i.join(", ")}). Pass an explicit { foreignKey: '<column>' } to disambiguate.`);
+	return i[0];
+}, p = (e) => Object.keys(e.fields), m = (e, t) => Object.prototype.hasOwnProperty.call(e.fields, t), h = (e) => {
+	let t = p(e);
+	return t.length === 0 ? "<none>" : t.join(", ");
+}, g = (t, n, r) => {
+	let i = `relation '${n}' on '${t.tableName}'`, a = r.target();
+	if (r.kind === "manyToMany") {
+		let n = r.through();
+		for (let [o, s] of [["sourceKey", r.sourceKey], ["targetKey", r.targetKey]]) if (!m(n, s)) throw e(`${i}: manyToMany ${o} '${s}' is not a column on the junction table '${n.tableName}'. Both keys name columns on the JUNCTION — ${o === "sourceKey" ? `sourceKey points at '${t.tableName}'` : `targetKey points at '${a.tableName}'`}. Columns on '${n.tableName}': ${h(n)}.`);
+	} else {
+		if (r.sourceKey !== void 0 && r.foreignKey !== void 0) throw e(`${i}: pass EITHER sourceKey OR foreignKey, not both. sourceKey '${r.sourceKey}' names a column on the source ('${t.tableName}') holding the target's id; foreignKey '${r.foreignKey}' names a column on the target ('${a.tableName}') holding the source's id. With both, foreignKey is ignored.`);
+		if (r.sourceKey !== void 0 && !m(t, r.sourceKey)) {
+			let n = m(a, r.sourceKey);
+			throw e(`${i}: sourceKey '${r.sourceKey}' is not a column on the source table '${t.tableName}'.` + (n ? ` It IS a column on the target '${a.tableName}' — you probably want { foreignKey: '${r.sourceKey}' }, which names the column on the TARGET that holds this table's id.` : ` Columns on '${t.tableName}': ${h(t)}.`));
+		}
+		if (r.foreignKey !== void 0 && !m(a, r.foreignKey)) {
+			let n = m(t, r.foreignKey);
+			throw e(`${i}: foreignKey '${r.foreignKey}' is not a column on the target table '${a.tableName}'.` + (n ? ` It IS a column on the source '${t.tableName}' — you want { sourceKey: '${r.foreignKey}' }. foreignKey names the column on the TARGET that points back at this table; sourceKey names the column on THIS table that holds the target's id.` : ` Columns on '${a.tableName}': ${h(a)}.`));
+		}
+	}
+};
+//#endregion
+export { f as inferForeignKey, s as isEmptyRelationsSpec, c as isRelationsSpec, u as many, d as manyToMany, l as one, o as relations, g as validateRelationConfig };

package/dist/relationsRegistry.js

@@ -0,0 +1,38 @@
+import { getTable as e } from "./tableRegistry.js";
+import { isRelationsSpec as t, validateRelationConfig as n } from "./relations.js";
+//#region src/relationsRegistry.ts
+var r = Symbol.for("@voltro/database/relationsRegistry"), i = globalThis, a = i[r] ?? (i[r] = /* @__PURE__ */ new Map()), o = (e) => {
+	let t = e.source(), n = a.get(t.tableName);
+	if (n === void 0) a.set(t.tableName, new Map(Object.entries(e.relations)));
+	else for (let [r, i] of Object.entries(e.relations)) {
+		let e = n.get(r);
+		if (e !== i) {
+			if (e !== void 0) throw Error(`duplicate relation '${r}' on '${t.tableName}': two relations() blocks both declare it. Pick distinct names or merge them into one block.`);
+			n.set(r, i);
+		}
+	}
+}, s = (e) => {
+	let n = 0;
+	for (let r of Object.values(e)) t(r) && (o(r), n += 1);
+	return n;
+}, c = (e) => {
+	let t = a.get(e);
+	if (t !== void 0) return Object.fromEntries(t);
+}, l = (e, t) => a.get(e)?.get(t), u = () => {
+	let e = [];
+	for (let [t, n] of a) for (let [r, i] of n) e.push({
+		source: t,
+		name: r,
+		relation: i
+	});
+	return e;
+}, d = () => {
+	for (let [t, r] of a) {
+		let i = e(t);
+		if (i !== void 0) for (let [e, t] of r) n(i, e, t);
+	}
+}, f = () => {
+	a.clear();
+};
+//#endregion
+export { u as allRegisteredRelations, f as clearRelationsRegistry, l as getRelation, c as getRelations, s as registerDiscoveredRelations, o as registerRelations, d as validateRegisteredRelations };

package/dist/replaceInProgress.js

@@ -0,0 +1,53 @@
+import { boolean as e, id as t, text as n, timestamp as r } from "./columns.js";
+import { table as i } from "./table.js";
+//#region src/replaceInProgress.ts
+var a = "_voltro_replace_in_progress", o = i(a, {
+	id: t({ prefix: "repl" }),
+	startedAt: r().default("now"),
+	kind: n().default("replace"),
+	tables: n().nullable(),
+	capture: n().nullable(),
+	via: n(),
+	staging: n().nullable(),
+	heartbeatAt: r().nullable(),
+	resumable: e().nullable()
+}).nonReactive(), s = 30, c = (e, t) => {
+	let n = typeof t == "number" && Number.isFinite(t) && t > 0 ? t : 30, r = Number(e.VOLTRO_STAGING_STALE_MINUTES);
+	return (Number.isFinite(r) && r > 0 ? r : n) * 6e4;
+}, l = (e) => e == null || String(e).length === 0 ? [] : String(e).split(",").map((e) => e.trim()).filter((e) => e.length > 0), u = (e) => {
+	let t = e.filter((e) => e.kind !== "staging");
+	if (t.length !== 0) return `refusing to start: a destructive data operation did not finish.
+${t.map((e) => {
+		let t = Number.isFinite(e.startedAt.getTime()) ? `${Math.max(0, Math.round((Date.now() - e.startedAt.getTime()) / 6e4))} minute(s) ago` : "at an unknown time";
+		if (e.kind === "restore") return `  - a native \`restore\` over ${e.via} began loading an artefact over this database ${t}\n    and never reported finishing.\n` + (e.capture === null ? "    The artefact it was loading was not recorded. Re-run the restore from your backup\n    directory, or restore from another backup." : `    The artefact it was loading:\n      ${e.capture}\n    Re-run it to completion with:  voltro data restore ${e.capture} --allow-live`);
+		let n = e.tables === null ? "this database" : `${e.tables} table(s)`;
+		return `  - a \`replace\` over ${e.via} began emptying ${n} ${t} and never reported finishing.\n` + (e.capture === null ? "    NO capture was taken for that run, so the previous rows are not recoverable from here.\n    Restore from your own backup." : `    The target's previous rows were captured first:\n      ${e.capture}\n    Restore them with:  voltro data import ${e.capture} --mode replace`);
+	}).join("\n")}\n
+  A half-replaced database is indistinguishable from an empty one from the inside — every table
+  exists, every constraint holds, and every query returns nothing without erroring. That is why
+  this is a refusal and not a warning.
+
+  When the data is back, or you have decided the current state is correct, clear the marker:
+      voltro data clear-replace-marker --yes`;
+}, d = (e, t, n) => {
+	let r = e.filter((e) => e.kind === "staging");
+	return {
+		all: r,
+		droppable: r.filter((e) => {
+			if (e.resumable) return !1;
+			let r = (e.heartbeatAt ?? e.startedAt).getTime();
+			return Number.isFinite(r) ? t - r >= n : !1;
+		})
+	};
+}, f = (e, t) => {
+	if (e.all.length === 0) return;
+	let n = new Set(e.droppable.map((e) => e.id));
+	return `staged data-import leftovers:
+${e.all.map((e) => {
+		let r = e.heartbeatAt ?? e.startedAt, i = Number.isFinite(r.getTime()) ? `${Math.max(0, Math.round((t - r.getTime()) / 6e4))} minute(s) ago` : "at an unknown time", a = `${e.staging.length} staging table(s) from a \`replace\` over ${e.via}, last active ${i}`;
+		return n.has(e.id) ? `  - ${a} — DROPPED: the run is not resumable and has been silent long enough that nothing is loading into them.` : e.resumable ? `  - ${a} — KEPT: the run was started \`--no-atomic\`, so these ARE its resume point. Re-run the same\n    bundle to continue from them, or drop them with: voltro data clear-staging --yes` : `  - ${a} — KEPT: still beating, so an import is loading into them right now.`;
+	}).join("\n")}\n  The target of a staged \`replace\` is untouched until one short swap at the end, so none of this is
+  a reason to refuse the boot — it is a reason to know the disk is holding a copy of a bundle.`;
+};
+//#endregion
+export { a as REPLACE_IN_PROGRESS_TABLE, s as STAGING_STALE_MINUTES, o as _voltroReplaceInProgressTable, u as interruptedReplaceRefusal, f as stagingLeftoverReport, d as stagingLeftovers, l as stagingNamesOf, c as stagingStaleAfterMs };

package/dist/requiredColumns.js

@@ -0,0 +1,26 @@
+//#region src/requiredColumns.ts
+var e = (e, t) => {
+	let n = [], r = t;
+	for (let [t, i] of Object.entries(e.fields)) {
+		let e = i;
+		e.nullable || e.hasDefault || e.idScheme !== void 0 || e.generatedAs !== void 0 || (r[t] === void 0 || r[t] === null) && n.push(t);
+	}
+	return n;
+}, t = (e, t, n) => {
+	let r = n, i = /* @__PURE__ */ new Set();
+	if (e !== void 0) {
+		let n = e.fields;
+		for (let e of new Set(t)) Object.getOwnPropertyDescriptor(n, e)?.enumerable && n[e]?.generatedAs !== void 0 && i.add(e);
+	}
+	let a = [];
+	for (let e of t) i.has(e) || (r[e] === void 0 ? a.push({
+		column: e,
+		reason: "absent"
+	}) : r[e] === null && a.push({
+		column: e,
+		reason: "null"
+	}));
+	return a;
+};
+//#endregion
+export { t as missingConflictColumns, e as missingRequiredColumns };

package/dist/residency.js

@@ -0,0 +1,52 @@
+import { resolveTenantNamespace as e } from "./namespace.js";
+//#region src/residency.ts
+var t = class extends Error {
+	_tag = "TenantResidencyUnresolved";
+	constructor(e) {
+		super(e), this.name = "TenantResidencyUnresolved";
+	}
+}, n = class extends Error {
+	region;
+	_tag = "TenantRegionUnavailable";
+	constructor(e, t) {
+		super(t), this.region = e, this.name = "TenantRegionUnavailable";
+	}
+}, r, i = (e) => {
+	if (e.homes === void 0) throw Error("setResidencyConfig: `homes` is required");
+	if (e.servableRegions === void 0 || e.servableRegions.length === 0) throw Error("setResidencyConfig: `servableRegions` must be non-empty (which regions this deployment serves)");
+	let t = /* @__PURE__ */ new Map();
+	for (let n of e.homes) {
+		let e = t.get(n.tenantId);
+		if (e !== void 0 && e !== n.region) throw Error(`residency: tenant '${n.tenantId}' is mapped to two regions ('${e}' and '${n.region}')`);
+		t.set(n.tenantId, n.region);
+	}
+	return r = e, e;
+}, a = () => r, o = () => {
+	r = void 0;
+}, s = (e, n) => {
+	if (e == null || e === "") throw new t("residency is on but the request has no resolvable tenant — refusing to bind a store");
+	let r = n.homes.find((t) => t.tenantId === e);
+	if (r === void 0) throw new t(`no residency home is mapped for tenant '${e}' — refusing to fall back to a default store (would be a residency violation)`);
+	return r;
+}, c = (e, t) => t.servableRegions.includes(e), l = (t, n) => {
+	let r = s(t.tenantId, n), i = e(r.tenantId);
+	return {
+		region: r.region,
+		namespace: i,
+		...r.connectionKey === void 0 ? {} : { connectionKey: r.connectionKey }
+	};
+}, u = (e, t, r) => {
+	let i = l(e, t);
+	if (!c(i.region, t)) throw new n(i.region, `tenant homed in region '${i.region}', which this deployment does not serve — route to the home region`);
+	let a = r.get(i.region);
+	if (a === void 0) throw new n(i.region, `no store handle for home region '${i.region}' (declared servable but not wired) — failing closed`);
+	return {
+		store: a,
+		placement: i
+	};
+}, d = async (e, t, n, r) => {
+	let { store: i, placement: a } = u(e, t, n);
+	return await r(i, a), a;
+};
+//#endregion
+export { n as TenantRegionUnavailable, t as TenantResidencyUnresolved, u as bindResidentStore, o as clearResidencyConfig, a as getResidencyConfig, c as isRegionServable, d as provisionResidentTenant, l as residentPlacement, s as resolveTenantHome, i as setResidencyConfig };

package/dist/retention.js

@@ -0,0 +1,62 @@
+import { and as e, isNull as t, lt as n, or as r } from "./predicate.js";
+import { Effect as i, Metric as a } from "effect";
+//#region src/retention.ts
+var o = {
+	app: 3,
+	plugin: 2,
+	framework: 1
+}, s = /* @__PURE__ */ new Map(), c = [], l = () => [...c], u = (e) => {
+	if (!e.table || !e.timeColumn) throw Error("registerRetention: table + timeColumn are required");
+	if (!Number.isFinite(e.ttlMs) || e.ttlMs <= 0) throw Error(`registerRetention(${e.table}): ttlMs must be a positive number`);
+	let t = e.source ?? "app", n = s.get(e.table);
+	if (n !== void 0) {
+		let r = n.source ?? "app", i = n.ttlMs !== e.ttlMs || n.timeColumn !== e.timeColumn || JSON.stringify(n.activityColumns ?? []) !== JSON.stringify(e.activityColumns ?? []) || JSON.stringify(n.where) !== JSON.stringify(e.where);
+		if (o[t] < o[r]) {
+			i && c.push({
+				table: e.table,
+				kept: {
+					source: r,
+					ttlMs: n.ttlMs
+				},
+				dropped: {
+					source: t,
+					ttlMs: e.ttlMs
+				}
+			});
+			return;
+		}
+		i && r !== t && c.push({
+			table: e.table,
+			kept: {
+				source: t,
+				ttlMs: e.ttlMs
+			},
+			dropped: {
+				source: r,
+				ttlMs: n.ttlMs
+			}
+		});
+	}
+	s.set(e.table, {
+		...e,
+		source: t
+	});
+}, d = () => [...s.values()], f = () => {
+	s.clear(), c.length = 0;
+}, p = async (o, s, c, l = 2e4) => {
+	let u = new Date(s - o.ttlMs), d = (o.activityColumns ?? []).map((e) => r(t(e), n(e, u))), f = d.length === 0 ? o.where : e(...o.where === void 0 ? [] : [o.where], ...d), p = 0;
+	try {
+		for (;;) {
+			let e = await c(o.table, o.timeColumn, u, l, f);
+			if (p += e, e < l) break;
+		}
+	} catch (e) {
+		throw i.runSync(a.update(a.withAttributes(h, { table: o.table }), 1)), e;
+	}
+	return p > 0 && i.runSync(a.update(a.withAttributes(m, { table: o.table }), p)), p;
+}, m = a.counter("voltro_retention_swept_rows_total"), h = a.counter("voltro_retention_sweep_errors_total"), g = (e, t) => {
+	let n = Number(e ?? String(t));
+	return (Number.isFinite(n) && n > 0 ? n : t) * 36e5;
+};
+//#endregion
+export { f as clearRetentions, l as listRetentionConflicts, d as listRetentions, u as registerRetention, g as retentionTtlMsFromEnv, p as sweepRetention };

package/dist/rowDecoder.js

@@ -0,0 +1,123 @@
+import { getTable as e } from "./tableRegistry.js";
+import { decodeSqliteDecimal as t, encodeSqliteDecimal as n } from "./sqliteDecimal.js";
+import { sqliteDecimalStorageShape as r } from "./sqliteDecimalStorage.js";
+import { projectedColumn as i } from "./projectedColumn.js";
+import { hasEncodedSqliteDecimalSource as a } from "./sqliteDecimalQueryPlan.js";
+import { sqliteDecimalOutputs as o } from "./sqliteDecimalOutputs.js";
+import { resolveSqliteDecimalSources as s } from "./sqliteDecimalCte.js";
+//#region src/rowDecoder.ts
+var c = (e) => e == null || typeof e == "boolean" ? e : typeof e == "number" ? e !== 0 : typeof e == "bigint" ? e !== 0n : typeof e == "string" ? e === "1" || e.toLowerCase() === "true" : e, l = (e) => {
+	if (e == null || typeof e != "string") return e;
+	let t = e.trim();
+	if (t.length === 0) return e;
+	let n = t.charAt(0);
+	if (n !== "{" && n !== "[" && n !== "\"" && n !== "t" && n !== "f" && n !== "n" && (n < "0" || n > "9") && n !== "-") return e;
+	try {
+		return JSON.parse(t);
+	} catch {
+		return e;
+	}
+}, u = (e) => e == null || typeof e == "string" ? e : typeof e == "number" || typeof e == "bigint" ? String(e) : e, d = (e) => {
+	if (e == null) return e;
+	let t = typeof e == "number" ? e : Number(e);
+	if (!Number.isSafeInteger(t)) throw RangeError("Numeric id must be a safe integer; use a string id scheme for larger identities");
+	return t;
+}, f = (e) => e.type === "id" && e.idScheme?.kind === "numeric" || e.type === "reference" && e.referenceStorage === "numeric", p = (e) => {
+	if (e == null || e instanceof Date) return e;
+	if (typeof e == "string" || typeof e == "number") {
+		let t = new Date(e);
+		return isNaN(t.getTime()) ? e : t;
+	}
+	return e;
+}, m = (e, t, n) => {
+	if (e == null) return e;
+	switch (t) {
+		case "boolean": return n === "postgres" ? e : c(e);
+		case "vector": return n === "postgres" ? l(e) : e;
+		case "json": return n === "postgres" || n === "mysql" || n === "mariadb" ? e : l(e);
+		case "array": return n === "postgres" ? e : l(e);
+		case "timestamp":
+		case "date": return n === "sqlite" || n === "turso" ? p(e) : e;
+		case "decimal":
+			if ((n === "sqlite" || n === "turso") && typeof e == "string" && /^D\d+$/.test(e)) throw TypeError("Decimal storage representation does not match the application schema; stop access and complete the verified storage migration before reading this column");
+			return u(e);
+		case "bigint": return u(e);
+		default: return e;
+	}
+}, h = (e, t) => {
+	switch (e) {
+		case "boolean": return t !== "postgres";
+		case "vector": return t === "postgres";
+		case "json": return t !== "postgres" && t !== "mysql" && t !== "mariadb";
+		case "array": return t !== "postgres";
+		case "timestamp":
+		case "date": return t === "sqlite" || t === "turso";
+		case "decimal":
+		case "bigint": return !0;
+		default: return !1;
+	}
+}, g = (t, n, r, c) => {
+	if (t.length === 0) return t;
+	if (c && (r === "sqlite" || r === "turso") && a(c)) {
+		let e = o(s(c, void 0), void 0);
+		return t.map((t) => {
+			let n = { ...t };
+			for (let t of e) {
+				let e = t.decimal ? "decimal" : t.definition?.type;
+				e && t.name in n && (n[t.name] = m(n[t.name], e, r));
+			}
+			return n;
+		});
+	}
+	if (c?.joinedProjection?.length) {
+		let e = c.joinedProjection.map((e) => ({
+			outputKey: e.outputKey,
+			definition: i(e.source, c)
+		}));
+		return t.map((t) => {
+			let n = { ...t };
+			for (let { outputKey: t, definition: i } of e) i && t in n && (n[t] = f(i) ? d(n[t]) : m(n[t], i.type, r));
+			return n;
+		});
+	}
+	let l = c?.sourceTable?.tableName === n ? c.sourceTable : e(n);
+	return l === void 0 ? t : _(t, l, r);
+}, _ = (e, n, i) => {
+	if (e.length === 0) return e;
+	let a = n.fields, o = [];
+	for (let [e, t] of Object.entries(a)) {
+		let n = i === "sqlite" || i === "turso" ? r(t) : void 0, a = t.type, s = f(t);
+		(s || n || h(a, i) || e in Object.prototype) && o.push({
+			key: e,
+			type: a,
+			...s ? { numericId: !0 } : {},
+			...n ? { decimalShape: n } : {}
+		});
+	}
+	return e.map((e) => {
+		let n = { ...e };
+		for (let { key: e, type: r, decimalShape: a, numericId: s } of o) e in n && (n[e] = s ? d(n[e]) : a && n[e] !== null && n[e] !== void 0 ? t(n[e], a) : m(n[e], r, i));
+		return n;
+	});
+}, v = (e, t) => {
+	if (e == null) return e;
+	switch (t) {
+		case "json": return JSON.stringify(e);
+		case "array":
+		case "vector": return typeof e == "string" ? e : JSON.stringify(e);
+		default: return e;
+	}
+}, y = (t, i, a = ["json", "array"]) => {
+	let o = e(i);
+	if (o === void 0) return t;
+	let s = o.fields, c = null;
+	for (let [e, i] of Object.entries(s)) if (a.includes(i.type) && e in t) {
+		let a = i.type === "decimal" ? r(i) : void 0, o = t[e];
+		if (a && o != null && typeof o != "string") throw TypeError("Encoded decimal writes require exact decimal strings");
+		let s = a && typeof o == "string" ? n(o, a) : v(o, i.type);
+		s !== t[e] && (c === null && (c = { ...t }), c[e] = s);
+	}
+	return c ?? t;
+};
+//#endregion
+export { m as decodeCell, _ as decodeRowsForTable, g as decodeRowsFromSchema, y as encodeRowForSchema };

package/dist/rowKey.js

@@ -0,0 +1,8 @@
+//#region src/rowKey.ts
+var e = (e) => typeof e == "string" || typeof e == "number" ? [["id", e]] : Object.entries(e).map(([e, t]) => [e, t]), t = (e) => {
+	if (typeof e == "string" || typeof e == "number") return String(e);
+	let t = Object.entries(e);
+	return t.length === 1 ? String(t[0][1]) : t.slice().sort(([e], [t]) => e < t ? -1 : +(e > t)).map(([e, t]) => `${e}=${String(t)}`).join("\0");
+}, n = (e) => typeof e == "object";
+//#endregion
+export { n as isCompositeRowKey, e as rowKeyColumns, t as rowKeyIdentity };

package/dist/rowSchema.js

@@ -0,0 +1,31 @@
+import { timestampMs as e } from "./wire.js";
+import { Schema as t } from "effect";
+//#region src/rowSchema.ts
+var n = (n) => {
+	let r = (() => {
+		switch (n.type) {
+			case "id": return n.idScheme?.kind === "numeric" ? t.Number : t.String;
+			case "text":
+			case "enum": return t.String;
+			case "reference": return n.referenceStorage === "numeric" ? t.Number : t.String;
+			case "integer":
+			case "real":
+			case "decimal": return t.Number;
+			case "boolean": return t.Boolean;
+			case "timestamp":
+			case "date": return e;
+			case "bigint": return t.BigIntFromString;
+			case "bytes": return t.Uint8ArrayFromBase64;
+			case "array": return t.Array(t.Unknown);
+			case "interval": return t.String;
+			default: return t.Unknown;
+		}
+	})();
+	return n.nullable === !0 ? t.NullOr(r) : r;
+}, r = (e, r) => {
+	let i = new Set(r?.omit ?? []), a = {};
+	for (let [t, r] of Object.entries(e.fields)) i.has(t) || (a[t] = n(r));
+	return t.Struct(a);
+};
+//#endregion
+export { n as columnSchema, r as rowSchema };

package/dist/scopeKey.js

@@ -0,0 +1,8 @@
+//#region src/scopeKey.ts
+var e = 255, t = (e) => e == null ? "null" : typeof e == "string" || typeof e == "number" || typeof e == "boolean" ? JSON.stringify(e) : Array.isArray(e) ? `[${e.map(t).join(",")}]` : typeof e == "object" ? `{${Object.entries(e).filter(([, e]) => e !== void 0).sort(([e], [t]) => e < t ? -1 : +(e > t)).map(([e, n]) => `${JSON.stringify(e)}:${t(n)}`).join(",")}}` : JSON.stringify(String(e)), n = (e) => {
+	if (e == null) return null;
+	let n = typeof e == "string" ? e : t(e);
+	return n.length > 255 ? n.slice(0, 255) : n;
+};
+//#endregion
+export { e as SCOPE_KEY_MAX_LENGTH, n as scopeKeyOf };

package/dist/seed.js

@@ -0,0 +1,33 @@
+//#region src/seed.ts
+var e = (e, t) => ({
+	name: e,
+	body: t
+}), t = (t) => {
+	if (t.lifecycle === "cron" && !t.cron) throw Error(`seed "${t.id}": lifecycle 'cron' requires a 'cron' field`);
+	if (t.lifecycle === "onSchemaChange" && (!t.watchedTables || t.watchedTables.length === 0)) throw Error(`seed "${t.id}": lifecycle 'onSchemaChange' requires at least one entry in 'watchedTables'`);
+	let n = t.steps({ step: e });
+	if (n.length === 0) throw Error(`seed "${t.id}": at least one step is required`);
+	return {
+		__seed: !0,
+		id: t.id,
+		name: t.name,
+		lifecycle: t.lifecycle,
+		...t.cron === void 0 ? {} : { cron: t.cron },
+		...t.timezone === void 0 ? {} : { timezone: t.timezone },
+		...t.watchedTables === void 0 ? {} : { watchedTables: t.watchedTables },
+		...t.fingerprint === void 0 ? {} : { fingerprint: t.fingerprint },
+		steps: n
+	};
+}, n = (e) => typeof e == "object" && !!e && "__seed" in e && e.__seed === !0, r = null, i = null, a = (e) => {
+	r = e;
+}, o = (e) => {
+	i = e;
+}, s = async (e) => {
+	let t = r;
+	t !== null && await t(e);
+}, c = async (e) => {
+	let t = i;
+	t !== null && e.changedTables.length !== 0 && await t(e);
+};
+//#endregion
+export { t as defineSeed, c as fireSchemaChangeSeeds, s as fireTenantCreateSeeds, n as isSeedDefinition, o as setSchemaChangeSeedHook, a as setTenantCreateSeedHook };

package/dist/snowflake.js

@@ -0,0 +1,26 @@
+//#region src/snowflake.ts
+var e = 10n, t = 12n, n = (1n << e) - 1n, r = (1n << t) - 1n, i = t, a = 22n, o = () => {
+	let e = process.env.SNOWFLAKE_MACHINE_ID;
+	if (e === void 0 || e === "") return 0n;
+	let t = BigInt(e);
+	if (t < 0n || t > n) throw Error(`SNOWFLAKE_MACHINE_ID out of range: ${e}. Must be 0..${n}.`);
+	return t;
+}, s = () => ({
+	lastMs: 0n,
+	sequence: 0n,
+	machineId: o()
+}), c, l = () => (c === void 0 && (c = s()), c), u = () => {
+	c = s();
+}, d = () => BigInt(Date.now()), f = (e) => {
+	let t = d();
+	for (; t <= e;) t = d();
+	return t;
+}, p = () => {
+	let e = l(), t = d();
+	t === e.lastMs ? (e.sequence = e.sequence + 1n & r, e.sequence === 0n && (t = f(e.lastMs), e.lastMs = t)) : (e.sequence = 0n, e.lastMs = t);
+	let n = t - 1704067200000n;
+	if (n < 0n) throw Error("Snowflake timestamp before configured epoch (2024-01-01). System clock is wrong.");
+	return (n << a | e.machineId << i | e.sequence).toString();
+};
+//#endregion
+export { p as generateSnowflake, u as resetSnowflake };

package/dist/sql.d.ts

@@ -359,7 +359,12 @@ export declare interface ApplyPlanCtx {
      * migration was a framework bug. `voltro db apply` did exactly that for two
      * releases while `voltro dev`'s boot diff, which uses this parameter, did not.
      */
-    readonly replan: (sql: SqlClient.SqlClient) => Effect.Effect<MigrationPlan, SqlError, SqlClient.SqlClient>;
+    /** The applier supplies `execution` for every pre-execution replan (including
+     * interrupted-run reconciliation), and `convergence` only after planned work.
+     * Review-bound callers must validate full content in the execution phase before
+     * projecting their transactional/online subsets. Ordinary auto-diff callers
+     * can ignore the phase and adapt to the current schema as before. */
+    readonly replan: (sql: SqlClient.SqlClient, phase?: 'execution' | 'convergence') => Effect.Effect<MigrationPlan, SqlError, SqlClient.SqlClient>;
     /**
      * The declared store charset — the one `replan` plans with. Here only for
      * the resume ledger this creates before the first statement: nothing declares
@@ -3581,11 +3586,17 @@ declare type IndexField = string | {
 declare type IndexKind = 'btree' | 'gist' | 'gin' | 'brin' | 'hnsw';
 
 /**
- * Per-kind tuning options. Today only `hnsw` carries knobs (the pgvector
- * build-time params). `m` controls graph connectivity (default 16),
+ * Per-kind tuning options. GIN supports a single-column operator class;
+ * HNSW supports pgvector build-time parameters. `m` controls graph connectivity (default 16),
  * `efConstruction` the build-time candidate-list size (default 64).
  */
 declare interface IndexKindOptions {
+    /** PostgreSQL GIN operator class for a single plain column.
+     * `gin_trgm_ops` installs pg_trgm and accelerates contains/ILIKE searches.
+     */
+    readonly gin?: {
+        readonly opclass: string;
+    };
     readonly hnsw?: {
         readonly m?: number;
         readonly efConstruction?: number;
@@ -4780,6 +4791,11 @@ export declare const publishSqliteDecimalStage: (sql: SqlClient.SqlClient, reque
 declare interface QueryDescriptor<R = Row> {
     readonly table: string;
     readonly predicate: Predicate | undefined;
+    /** Additional reactive invalidation sources, independent of SQL row selection.
+     * The runtime merges a query handler's declared `source` tables here. Changes
+     * to these tables recheck subscription authority even when SQL rows do not
+     * change. They add no joins, predicates or cross-tenant access. */
+    readonly dependentTables?: ReadonlyArray<string>;
     /** Phantom — carries the row type through to `store.query()`. Never set at
      *  runtime; erased entirely by the compiler. */
     readonly __row?: R;
@@ -5070,6 +5086,11 @@ declare interface QueryDescriptor<R = Row> {
 declare interface QueryDescriptor_2<R = Row_2> {
     readonly table: string;
     readonly predicate: Predicate_2 | undefined;
+    /** Additional reactive invalidation sources, independent of SQL row selection.
+     * The runtime merges a query handler's declared `source` tables here. Changes
+     * to these tables recheck subscription authority even when SQL rows do not
+     * change. They add no joins, predicates or cross-tenant access. */
+    readonly dependentTables?: ReadonlyArray<string>;
     /** Phantom — carries the row type through to `store.query()`. Never set at
      *  runtime; erased entirely by the compiler. */
     readonly __row?: R;
@@ -5688,7 +5709,7 @@ declare type Row = Readonly<Record<string, unknown>>;
 declare type Row_2 = Readonly<Record<string, unknown>>;
 
 /** Addresses one row: its `id`, or the columns of an explicit primary key. */
-declare type RowKey = string | Readonly<Record<string, unknown>>;
+declare type RowKey = string | number | Readonly<Record<string, unknown>>;
 
 /** The context a rule predicate is evaluated with. */
 declare interface RuleContext {
@@ -6868,8 +6889,8 @@ declare interface TableIndex {
      */
     readonly kind?: IndexKind;
     /**
-     * Per-kind tuning knobs. Today only `hnsw` (`kindOptions.hnsw.{m,
-     * efConstruction, opclass}`). Ignored for kinds that don't read it.
+     * Per-kind tuning: `gin.opclass` or `hnsw.{m, efConstruction, opclass}`.
+     * Ignored for kinds that do not read the corresponding options.
      */
     readonly kindOptions?: IndexKindOptions;
     /**