@voltro/database 0.85.0 → 0.86.0

package/dist/dbMetrics.js

@@ -0,0 +1,65 @@
+import { Context as e, Metric as t } from "effect";
+//#region src/dbMetrics.ts
+var n = t.exponentialBoundaries({
+	start: 5e-4,
+	factor: 2,
+	count: 16
+}), r = t.counter("voltro_db_queries_total", { description: "Database operations executed, by dialect and operation kind." }), i = t.histogram("voltro_db_query_duration_seconds", {
+	boundaries: n,
+	description: "Database operation duration in seconds, by dialect and operation kind."
+}), a = t.counter("voltro_db_errors_total", { description: "Database operations that threw, by dialect and operation kind." }), o = t.gauge("voltro_db_operations_in_flight", { description: "Database operations currently executing, by dialect. An upper bound on connections the framework holds; NOT the driver pool's waiting count." }), s = t.counter("voltro_db_eager_fallback_total", { description: "Eager-load queries that degraded from the single-roundtrip JSON-agg path to the multi-query walker, by dialect and reason." }), c = e.empty(), l = /* @__PURE__ */ new Map(), u = /* @__PURE__ */ new Map(), d = /* @__PURE__ */ new Map(), f = (e, n) => {
+	let o = `${e}\u0000${n}`, s = l.get(o);
+	if (s !== void 0) return s;
+	let c = (r) => t.withAttributes(t.withAttributes(r, { dialect: e }), { op: n }), u = {
+		count: c(r),
+		duration: c(i),
+		errors: c(a)
+	};
+	return l.set(o, u), u;
+}, p = () => {
+	l.clear(), u.clear(), d.clear();
+}, m = () => l.size + u.size + d.size, h = /* @__PURE__ */ new Map(), g = (e, n) => {
+	let r = Math.max(0, (h.get(e) ?? 0) + n);
+	r === 0 ? h.delete(e) : h.set(e, r);
+	let i = u.get(e);
+	i === void 0 && (i = t.withAttributes(o, { dialect: e }), u.set(e, i)), i.updateUnsafe(r, c);
+}, _ = (e) => h.get(e) ?? 0, v = (e) => {
+	let t = f(String(e.dialect), e.op);
+	t.count.updateUnsafe(1, c), t.duration.updateUnsafe(e.durationMs / 1e3, c), e.status === "error" && t.errors.updateUnsafe(1, c);
+}, y = async (e, t, n) => {
+	let r = performance.now(), i = String(e);
+	g(i, 1);
+	let a = "ok";
+	try {
+		return await n();
+	} catch (e) {
+		throw a = "error", e;
+	} finally {
+		g(i, -1), v({
+			dialect: e,
+			op: t,
+			durationMs: performance.now() - r,
+			status: a
+		});
+	}
+}, b = 3e5, x = (e) => {
+	if (e == null || e === "") return;
+	let t = Number(e);
+	return Number.isFinite(t) && t >= 0 ? Math.floor(t) : void 0;
+}, S = (e, t = process.env) => x(t.VOLTRO_DB_EAGER_FALLBACK_WARN_INTERVAL_MS) ?? x(e) ?? 3e5, C = (e, n = {}) => {
+	let r = S(n.warnIntervalMs), i = n.now ?? (() => Date.now()), a = /* @__PURE__ */ new Map();
+	return (n) => {
+		let o = `${n.dialect} ${n.reason}`, l = d.get(o);
+		l === void 0 && (l = t.withAttributes(t.withAttributes(s, { dialect: String(n.dialect) }), { reason: n.reason }), d.set(o, l)), l.updateUnsafe(1, c);
+		let u = `${n.table}\u0000${n.reason}`, f = a.get(u), p = f === void 0 || r > 0 && i() - f >= r, m = {
+			table: n.table,
+			dialect: String(n.dialect),
+			reason: n.reason,
+			metric: "voltro_db_eager_fallback_total",
+			...n.error === void 0 ? {} : { err: n.error }
+		};
+		p ? (a.set(u, i()), e.warn(n.reason === "execute-failed" ? "eager-load JSON-agg statement FAILED and was re-run on the multi-query walker — this query pays both paths on every call. Counted as voltro_db_eager_fallback_total{reason=\"execute-failed\"}." : "eager-load could not be compiled to a single JSON-agg roundtrip and is running on the multi-query walker — one round trip per relation level, on every call. Counted as voltro_db_eager_fallback_total{reason=\"not-compilable\"}.", m)) : e.debug("eager-load is still running on the walker (rate-limited; the counter is not)", m);
+	};
+};
+//#endregion
+export { b as DEFAULT_EAGER_FALLBACK_WARN_INTERVAL_MS, m as dbMetricTagCacheSizeForTests, _ as dbOperationsInFlight, C as makeEagerFallbackReporter, y as observeDbOp, v as recordDbOp, p as resetDbMetricTagCacheForTests, S as resolveEagerFallbackWarnIntervalMs };

package/dist/decimalComparison.js

@@ -0,0 +1,27 @@
+//#region src/decimalComparison.ts
+var e = (e) => {
+	if (typeof e != "string" || !/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/.test(e)) return null;
+	let [t = "", n = ""] = e.replace(/^[+-]/, "").split("."), r = t.replace(/^0+/, "") || "0";
+	return {
+		negative: e.startsWith("-") && /[1-9]/.test(r + n),
+		whole: r,
+		fraction: n
+	};
+}, t = (t, n) => {
+	let r = e(t), i = e(n);
+	if (!r || !i) return null;
+	if (r.negative !== i.negative) return r.negative ? -1 : 1;
+	let a = r.whole.length - i.whole.length;
+	if (a === 0 && (a = r.whole === i.whole ? 0 : r.whole > i.whole ? 1 : -1), a === 0) {
+		let e = Math.max(r.fraction.length, i.fraction.length), t = r.fraction.padEnd(e, "0"), n = i.fraction.padEnd(e, "0");
+		a = t === n ? 0 : t > n ? 1 : -1;
+	}
+	return a === 0 ? 0 : (a > 0 ? 1 : -1) * (r.negative ? -1 : 1);
+}, n = (t) => {
+	let n = e(t);
+	if (n === null) return null;
+	let r = n.fraction.replace(/0+$/, "");
+	return `${n.negative ? "-" : ""}${n.whole}${r ? "." + r : ""}`;
+};
+//#endregion
+export { t as compareDecimal, n as decimalEqualityKey };

package/dist/derivedRowId.js

@@ -0,0 +1,5 @@
+import { createHash as e } from "node:crypto";
+//#region src/derivedRowId.ts
+var t = 64, n = "\0", r = 32, i = (t, ...i) => `${t}_${e("sha256").update(i.map(String).join(n)).digest("hex").slice(0, r)}`, a = (e) => e.length + 1 + r;
+//#endregion
+export { t as ID_COLUMN_MAX_LENGTH, i as derivedRowId, a as derivedRowIdLength };

package/dist/dialect.js

@@ -0,0 +1,13 @@
+//#region src/dialect.ts
+var e = (e) => e === "sqlite" || e === "turso", t = (e) => e === "mysql" || e === "mariadb", n = (e, t) => {
+	switch (t) {
+		case "mysql":
+		case "mariadb": return `\`${e.replace(/`/g, "``")}\``;
+		case "mssql": return `[${e.replace(/\]/g, "]]")}]`;
+		case "postgres":
+		case "sqlite":
+		case "turso": return `"${e.replace(/"/g, "\"\"")}"`;
+	}
+}, r = 1e4;
+//#endregion
+export { r as DEFAULT_ACQUIRE_TIMEOUT_MS, t as isMysqlFamily, e as isSqliteFamily, n as quoteIdent };

package/dist/enumRenames.js

@@ -0,0 +1,14 @@
+//#region src/enumRenames.ts
+var e = /* @__PURE__ */ new Map(), t = (t, n) => {
+	if (n.from === n.to) throw Error(`declareEnumRename('${t}'): \`from\` and \`to\` are both '${n.from}' — a rename must change the value.`);
+	let r = e.get(t) ?? [];
+	for (let e of r) {
+		if (e.from === n.from && e.to === n.to) return;
+		if (e.from === n.from && e.to !== n.to) throw Error(`declareEnumRename('${t}'): value '${n.from}' is already declared as renamed to '${e.to}', cannot also rename it to '${n.to}'.`);
+	}
+	r.push(n), e.set(t, r);
+}, n = (t) => e.get(t) ?? [], r = () => e, i = () => {
+	e.clear();
+};
+//#endregion
+export { r as allEnumRenames, i as clearEnumRenames, t as declareEnumRename, n as getEnumRenames };

package/dist/expiresMixin.js

@@ -0,0 +1,10 @@
+import { timestamp as e } from "./columns.js";
+import { defineMixin as t } from "./mixins.js";
+//#region src/expiresMixin.ts
+var n = "voltro/expires", r = () => t({
+	id: n,
+	fields: { expiresAt: e().nullable() },
+	behaviors: { defaultWhere: () => "expiresAt IS NULL OR expiresAt > now()" }
+});
+//#endregion
+export { n as VOLTRO_EXPIRES_MIXIN_ID, r as expires };

package/dist/fieldEncryption.js

@@ -0,0 +1,98 @@
+//#region src/fieldEncryption.ts
+var e = "enc:v1:", t = "enc:v2:", n = (e, t, n) => {
+	let r = `${e}:${t}`, i = n == null || n === "" ? void 0 : String(n);
+	return i === void 0 ? { column: r } : {
+		column: r,
+		row: `${r}:${i}`
+	};
+}, r = (e) => typeof e == "string" && e.startsWith("enc:v2:"), i = class extends Error {
+	_tag = "FieldDecryptionError";
+	table;
+	column;
+	reason;
+	constructor(e) {
+		super(`column "${e.table}.${e.column}" is .encrypted() but could not be decrypted (${e.reason}) — the stored value was most likely encrypted under a different key`), this.name = "FieldDecryptionError", this.table = e.table, this.column = e.column, this.reason = e.reason;
+	}
+}, a = (e) => typeof e == "object" && !!e && e._tag === "FieldDecryptionError", o = (e) => typeof e == "string" && (e.startsWith("enc:v1:") || e.startsWith("enc:v2:")), s = (e, t, n) => e.encrypt(JSON.stringify(t), n), c = /* @__PURE__ */ new Set([
+	"text",
+	"id",
+	"reference",
+	"enum",
+	"uuid",
+	"email",
+	"url"
+]), l = (e, t, n, r) => {
+	let i = e.decrypt(t, r), a;
+	try {
+		a = JSON.parse(i);
+	} catch {
+		return i;
+	}
+	return typeof a == "string" ? a : n === void 0 || c.has(n) ? i : a;
+}, u = (e, t, n, r) => {
+	let i = e.decrypt(t, r);
+	try {
+		return typeof JSON.parse(i) == "string" ? !1 : n === void 0 || c.has(n) ? !0 : void 0;
+	} catch {
+		return !0;
+	}
+}, d = (e, t) => e.fields[t]?.type, f = (e) => {
+	let t = [];
+	for (let [n, r] of Object.entries(e.fields)) r.encrypted === !0 && t.push(n);
+	return t;
+}, p = "id", m = (e, t, n, r) => {
+	if (!t) return e;
+	let i = f(t);
+	return i.length === 0 ? e : g(e, i, t.tableName ?? "?", n, r);
+}, h = (e, t, n) => {
+	if (t === void 0 || e.length === 0) return e;
+	let r = f(t);
+	if (r.length === 0) return e;
+	let i = t.tableName ?? "?";
+	return e.map((e) => g(e, r, i, n));
+}, g = (e, t, r, i, a) => {
+	let c = a ?? e[p], l = { ...e };
+	for (let e of t) {
+		let t = l[e];
+		if (!(t == null || o(t))) {
+			if (!i) throw Error(`column "${r}.${e}" is .encrypted() but no field cipher is registered — set VOLTRO_FIELD_ENCRYPTION_KEY (\`voltro dev\` mints one; \`voltro serve\` refuses to boot without it); in a test, pass \`fieldEncryptionKey\` to makeTestContext`);
+			l[e] = s(i, t, n(r, e, c));
+		}
+	}
+	return l;
+}, _ = (e, t, r, a) => {
+	if (!t) return e;
+	let s = f(t);
+	if (s.length === 0 || !r) return e;
+	let c = a?.onError ?? "throw", u = t.tableName ?? "?";
+	return e.map((e) => {
+		let f;
+		for (let m of s) {
+			let s = e[m];
+			if (o(s)) {
+				f ??= { ...e };
+				try {
+					f[m] = l(r, s, d(t, m), n(u, m, a?.rowId ?? e[p]));
+				} catch (e) {
+					let t = String(e?.message ?? e);
+					if (c === "null") {
+						f[m] = null, a?.warn?.({
+							table: u,
+							column: m,
+							reason: t
+						});
+						continue;
+					}
+					throw new i({
+						table: u,
+						column: m,
+						reason: t
+					});
+				}
+			}
+		}
+		return f ?? e;
+	});
+};
+//#endregion
+export { t as BOUND_ENCRYPTED_PREFIX, e as ENCRYPTED_PREFIX, i as FieldDecryptionError, l as decodeFieldValue, _ as decryptFieldsOnRead, s as encodeFieldValue, m as encryptFieldsForWrite, h as encryptFieldsForWriteBatch, f as encryptedColumnsOf, n as fieldBinding, r as isBoundCiphertext, o as isEncrypted, a as isFieldDecryptionError, u as isRawEncoding };

package/dist/frameworkTables.js

@@ -0,0 +1,130 @@
+import { id as e, integer as t, json as n, text as r, timestamp as i } from "./columns.js";
+import { table as a } from "./table.js";
+//#region src/frameworkTables.ts
+var o = a("_voltro_migrations", {
+	id: e({ prefix: "mig" }),
+	name: r(),
+	hash: r(),
+	status: r(),
+	appliedAt: i().nullable(),
+	durationMs: t().nullable(),
+	errorMessage: r().nullable(),
+	errorStack: r().nullable(),
+	workflowRunId: r().nullable(),
+	createdAt: i().default("now"),
+	updatedAt: i().default("now").onUpdate("now")
+}).index(["status"]), s = a("_voltro_seeds", {
+	id: e({ prefix: "seed" }),
+	name: r(),
+	lifecycle: r(),
+	fingerprint: r(),
+	cronSchedule: r().nullable(),
+	watchedTables: n().nullable(),
+	nextRunAt: i().nullable(),
+	lastRunStatus: r().nullable(),
+	lastRunAt: i().nullable(),
+	lastRunDurationMs: t().nullable(),
+	lastRunRowsTouched: t().nullable(),
+	lastError: r().nullable(),
+	workflowRunId: r().nullable(),
+	createdAt: i().default("now"),
+	updatedAt: i().default("now").onUpdate("now")
+}).index(["lifecycle"]).index(["nextRunAt"]), c = a("_voltro_schema_owner", {
+	id: e({ prefix: "own" }),
+	appName: r(),
+	projectName: r().nullable(),
+	frameworkVersion: r().nullable(),
+	claimedAt: i().default("now")
+}), l = a("_voltro_plugin_migrations", {
+	id: e({ prefix: "plm" }),
+	plugin_name: r(),
+	migration_id: r(),
+	description: r().nullable(),
+	applied_at: r()
+}), u = a("_voltro_migration_plans", {
+	id: e({ prefix: "plan" }),
+	fingerprint: r(),
+	liveFingerprint: r().nullable(),
+	operations: n(),
+	rollbackPlan: n().nullable(),
+	appliedBy: r(),
+	environment: r(),
+	source: r(),
+	onlineStrategy: r().nullable(),
+	durationMs: t(),
+	notes: r().nullable(),
+	squashedAt: i().nullable(),
+	appliedAt: i().default("now"),
+	createdAt: i().default("now"),
+	updatedAt: i().default("now").onUpdate("now")
+}).index(["fingerprint"]).index(["environment"]), d = a("_voltro_idempotency", {
+	id: e({ prefix: "idem" }),
+	scope: r(),
+	key: r(),
+	status: r(),
+	response: n().nullable(),
+	createdAt: i().default("now")
+}).unique(["scope", "key"]).index(["createdAt"]), f = a("_voltro_devices", {
+	id: e({ prefix: "device" }),
+	tenantId: r(),
+	name: r(),
+	scopes: n().nullable(),
+	pairingHash: r().maxLength(64).nullable(),
+	pairingExpiresAt: i().nullable(),
+	accessHash: r().maxLength(64).nullable(),
+	accessExpiresAt: i().nullable(),
+	refreshHash: r().maxLength(64).nullable(),
+	refreshExpiresAt: i().nullable(),
+	previousRefreshHash: r().maxLength(64).nullable(),
+	generation: t().default(0),
+	pairedAt: i().nullable(),
+	lastSeenAt: i().nullable(),
+	revokedAt: i().nullable(),
+	revokedReason: r().nullable(),
+	createdBy: r().nullable(),
+	metadata: n().nullable(),
+	createdAt: i()
+}).index(["tenantId"]).index(["pairingHash"]).index(["accessHash"]).index(["refreshHash"]).index(["previousRefreshHash"]), p = a("_voltro_tenant_selections", {
+	id: e({ prefix: "tsel" }),
+	subjectType: r().maxLength(32),
+	subjectId: r(),
+	tenantId: r(),
+	selectedAt: i()
+}).primaryKey(["id"]).nonReactive(), m = a("_voltro_kv", {
+	id: e({ prefix: "kv" }),
+	key: r().unique(),
+	value: r().nullable(),
+	expiresAt: i().nullable(),
+	createdAt: i().default("now"),
+	updatedAt: i().default("now").onUpdate("now")
+}).index(["expiresAt"]), h = a("_voltro_api_keys", {
+	id: e({ prefix: "apikey" }),
+	tenantId: r().nullable(),
+	name: r(),
+	hashedKey: r().maxLength(64).unique(),
+	keyPrefix: r(),
+	scopes: n().nullable(),
+	lastUsedAt: i().nullable(),
+	requestCount: t().default(0),
+	expiresAt: i().nullable(),
+	revokedAt: i().nullable(),
+	createdBy: r().nullable(),
+	onBehalfOf: r().nullable(),
+	metadata: n().nullable(),
+	createdAt: i().default("now")
+}).index("byApiKeyTenant", ["tenantId"]), g = a("_voltro_replica_observations", {
+	id: e({ prefix: "robs" }),
+	replicaId: r().maxLength(191),
+	startedAt: i(),
+	version: r().maxLength(64).nullable(),
+	kind: r().maxLength(64),
+	payload: r().nullable(),
+	reachableAt: r().maxLength(255).nullable(),
+	writtenAt: i().default("now").onUpdate("now")
+}).unique(["replicaId", "kind"]).index(["kind"]), _ = [
+	o,
+	s,
+	u
+];
+//#endregion
+export { h as _voltroApiKeysTable, f as _voltroDevicesTable, d as _voltroIdempotencyTable, m as _voltroKvTable, u as _voltroMigrationPlansTable, o as _voltroMigrationsTable, l as _voltroPluginMigrationsTable, g as _voltroReplicaObservationsTable, c as _voltroSchemaOwnerTable, s as _voltroSeedsTable, p as _voltroTenantSelectionsTable, _ as frameworkTables };

package/dist/ginIndex.js

@@ -0,0 +1,10 @@
+//#region src/ginIndex.ts
+var e = (e) => {
+	let t = e?.gin?.opclass;
+	if (t !== void 0) {
+		if (!/^[a-z_][a-z0-9_$]*(?:\.[a-z_][a-z0-9_$]*)?$/i.test(t)) throw Error("GIN opclass must be an unquoted, optionally schema-qualified identifier");
+		return t.toLowerCase().replace(/^public\./, "");
+	}
+};
+//#endregion
+export { e as resolveGinOpclass };

package/dist/hybridSearch.js

@@ -0,0 +1,32 @@
+import { resolveFullTextIndex as e } from "./queryBuilder.js";
+//#region src/hybridSearch.ts
+var t = (t) => {
+	let n = t.alpha ?? .5;
+	if (n < 0 || n > 1) throw Error(`hybridSearch: alpha must be in [0, 1], got ${n}`);
+	return (r) => {
+		let i = Array.isArray(t.vector.query) ? {
+			column: t.vector.col,
+			queryVector: t.vector.query,
+			distance: t.vector.distance ?? "cosine",
+			alpha: n
+		} : {
+			column: t.vector.col,
+			queryText: t.vector.query,
+			distance: t.vector.distance ?? "cosine",
+			alpha: n
+		}, a = e(r.table, t.fts.indexName, r.fullTextIndexes);
+		return {
+			...r,
+			annClause: i,
+			fullTextSearch: {
+				indexName: t.fts.indexName,
+				query: t.fts.query,
+				columns: a.columns,
+				...a.config === void 0 ? {} : { config: a.config },
+				...a.weights === void 0 ? {} : { weights: a.weights }
+			}
+		};
+	};
+};
+//#endregion
+export { t as hybridSearch };

package/dist/idGenerator.js

@@ -0,0 +1,57 @@
+import { validateTypeIdPrefix as e } from "./identifierLimits.js";
+import { generateSnowflake as t } from "./snowflake.js";
+import { typeid as n } from "typeid-js";
+import { ulid as r } from "ulid";
+//#region src/idGenerator.ts
+var i = (t) => {
+	let n = t.toLowerCase();
+	if (n.startsWith("_")) throw Error(`cannot derive a typeid prefix for table '${t}' (table names starting with '_' are not valid typeid prefixes). Pick an explicit prefix via id({ prefix: '...' }) or use a different scheme like id({ scheme: 'numeric' }) for internal tables.`);
+	if (!/^[a-z][a-z0-9_]*$/.test(n)) throw Error(`cannot derive a typeid prefix from table name '${t}' (must match [a-z][a-z0-9_]*). Pick an explicit prefix via id({ prefix: '...' }).`);
+	let r = n.endsWith("ies") && n.length > 3 ? n.slice(0, -3) + "y" : n.endsWith("ses") || n.endsWith("xes") || n.endsWith("zes") || n.endsWith("shes") || n.endsWith("ches") ? n.slice(0, -2) : n.endsWith("s") && n.length > 1 ? n.slice(0, -1) : n;
+	return e(r, {
+		kind: "derived",
+		tableName: t
+	}), r;
+}, a = (t, n) => {
+	if (t === void 0) return {
+		kind: "typeid",
+		prefix: i(n)
+	};
+	if ("prefix" in t && !("scheme" in t)) return e(t.prefix, {
+		kind: "explicit",
+		tableName: n
+	}), {
+		kind: "typeid",
+		prefix: t.prefix
+	};
+	if (!("scheme" in t)) throw Error("invalid id() options: no scheme or prefix");
+	switch (t.scheme) {
+		case "typeid": {
+			let r = t.prefix ?? i(n);
+			return t.prefix !== void 0 && e(t.prefix, {
+				kind: "explicit",
+				tableName: n
+			}), {
+				kind: "typeid",
+				prefix: r
+			};
+		}
+		case "ulid": return { kind: "ulid" };
+		case "numeric": return { kind: "numeric" };
+		case "snowflake": return { kind: "snowflake" };
+		case "custom": return {
+			kind: "custom",
+			generate: t.generate
+		};
+	}
+}, o = (e, i) => {
+	switch (e.kind) {
+		case "typeid": return n(e.prefix).toString();
+		case "ulid": return r();
+		case "numeric": return null;
+		case "snowflake": return t();
+		case "custom": return e.generate(i);
+	}
+};
+//#endregion
+export { i as deriveTypeIdPrefix, o as generateId, a as resolveIdScheme };

package/dist/identifierLimits.js

@@ -0,0 +1,32 @@
+//#region src/identifierLimits.ts
+var e = 63, t = 60, n = /* @__PURE__ */ new Set(), r = (e) => {
+	n.add(e);
+}, i = () => {
+	let e = [...n];
+	return n.clear(), e;
+}, a = /^[a-zA-Z_][a-zA-Z0-9_]*$/, o = (e, t) => {
+	if (t.length === 0) throw Error(`${e} cannot be empty.`);
+	if (!a.test(t)) throw Error(`${e} '${t}' contains characters outside [A-Za-z0-9_] or starts with a digit. Dialect-portable identifiers must match /^[a-zA-Z_][a-zA-Z0-9_]*$/.`);
+}, s = (e) => {
+	if (o("table name", e), e.length > 63) throw Error(`table name '${e}' is ${e.length} chars — exceeds the 63-byte cross-dialect limit (Postgres floor). Shorten the name; long table names also cascade into auto-named indexes and FK constraints that would themselves exceed the limit.`);
+	e.length > 60 && r(`table name '${e}' is ${e.length} chars — ${63 - e.length} from the Postgres 63-byte limit. Auto-named indexes on this table will run out of room fast.`);
+}, c = (e, t) => {
+	if (o("column name", t), t.length > 63) throw Error(`column '${t}' on table '${e}' is ${t.length} chars — exceeds the 63-byte cross-dialect limit (Postgres floor). Rename it.`);
+	t.length > 60 && r(`column '${t}' on table '${e}' is ${t.length} chars — close to the 63-byte limit.`);
+}, l = (e, t, n, i) => {
+	if (o("index name", t), t.length > 63) throw Error(n ? `auto-named index '${t}' on table '${e}' is ${t.length} chars — exceeds the 63-byte cross-dialect limit (Postgres floor). Supply an explicit short name: .index('<shortName>', ${JSON.stringify([...i])}).` : `index name '${t}' on table '${e}' is ${t.length} chars — exceeds the 63-byte cross-dialect limit (Postgres floor). Shorten it.`);
+	t.length > 60 && r(`index '${t}' on table '${e}' is ${t.length} chars — ${63 - t.length} from the 63-byte limit. ${n ? `Consider .index('<shortName>', ${JSON.stringify([...i])}) before it grows.` : ""}`);
+}, u = (e, t) => {
+	if (e.length === 0) throw Error(`typeid prefix on table '${t.tableName}' cannot be empty.`);
+	if (!/^[a-z][a-z0-9_]*$/.test(e)) {
+		let n = t.kind === "derived" ? "the derived prefix doesn't match typeid's required shape — supply an explicit one via id({ prefix: '...' })." : "the prefix must match typeid's required shape /^[a-z][a-z0-9_]*$/.";
+		throw Error(`typeid prefix '${e}' on table '${t.tableName}' is invalid — ${n}`);
+	}
+	if (e.length > 63) {
+		let n = t.kind === "derived" ? "shorten the table name, or supply an explicit short prefix via id({ prefix: '...' })." : "pick a shorter prefix.";
+		throw Error(`typeid prefix '${e}' on table '${t.tableName}' is ${e.length} chars — exceeds the 63-byte limit; ${n}`);
+	}
+	e.length > 60 && r(`typeid prefix '${e}' on table '${t.tableName}' is ${e.length} chars — close to the 63-byte limit. Generated ids will be even longer (prefix + '_' + 26).`);
+};
+//#endregion
+export { e as MAX_IDENTIFIER_LENGTH, t as WARN_IDENTIFIER_LENGTH, i as drainIdentifierWarnings, c as validateColumnName, l as validateIndexName, s as validateTableName, u as validateTypeIdPrefix };

package/dist/index.d.ts

@@ -17,7 +17,7 @@ import { YieldableError } from 'effect/Cause';
 
 /** The store shape this needs — a read, nothing more. */
 export declare interface ActorLookupStore {
-    query: (descriptor: unknown) => Promise<ReadonlyArray<Record<string, unknown>>>;
+    query: (descriptor: QueryDescriptor) => Promise<ReadonlyArray<Record<string, unknown>>>;
 }
 
 /** The framework's built-in `actors` core table. */
@@ -4567,11 +4567,17 @@ export declare type IndexField = string | {
 export 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).
  */
 export 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;
@@ -6534,6 +6540,11 @@ Joins extends JoinsMap = {}> {
 export 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;
@@ -7470,12 +7481,12 @@ declare type Row_2 = Readonly<Record<string, unknown>>;
 declare type Row_3 = Readonly<Record<string, unknown>>;
 
 /** Addresses one row: its `id`, or the columns of an explicit primary key. */
-export declare type RowKey = string | Readonly<Record<string, unknown>>;
+export declare type RowKey = string | number | Readonly<Record<string, unknown>>;
 
 /**
  * The `(column, value)` pairs a key addresses, in declaration order.
  *
- * A string is the `id` column — that is the contract every existing caller
+ * A scalar is the `id` column — that is the contract every existing caller
  * relies on, and widening it must not change what a string means.
  */
 export declare const rowKeyColumns: (key: RowKey) => ReadonlyArray<readonly [string, unknown]>;
@@ -8914,8 +8925,8 @@ export 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;
     /**