@voltro/database 0.86.0 → 0.88.0

package/dist/fieldEncryption.js

@@ -1,19 +1,23 @@
-//#region src/fieldEncryption.ts
-var e = "enc:v1:", t = "enc:v2:", n = (e, t, n) => {
+// src/fieldEncryption.ts
+var e = /^[a-z0-9][a-z0-9-]{0,15}$/, t = (t) => {
+	if (!c(t)) return;
+	let i = t.startsWith(r), a = t.slice(i ? r.length : n.length).split(":")[i ? 4 : 3];
+	return a !== void 0 && e.test(a) ? a : void 0;
+}, n = "enc:v1:", r = "enc:v2:", i = (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 {
+}, a = (e) => typeof e == "string" && e.startsWith("enc:v2:"), o = 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;
+		super(`column "${e.table}.${e.column}" is .encrypted() but could not be decrypted (${e.reason}) — the stored value was sealed under a key this process does not hold, or it is not where it was sealed: a value opens only at the table, column and row it was written for (a rename needs .renamedFrom(); an id changed outside the store leaves it bound to the old id)`), 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([
+}, s = (e) => typeof e == "object" && !!e && e._tag === "FieldDecryptionError", c = (e) => typeof e == "string" && (e.startsWith("enc:v1:") || e.startsWith("enc:v2:")), l = (e, t, n) => e.encrypt(JSON.stringify(t), n), u = /* @__PURE__ */ new Set([
 	"text",
 	"id",
 	"reference",
@@ -21,78 +25,96 @@ var e = "enc:v1:", t = "enc:v2:", n = (e, t, n) => {
 	"uuid",
 	"email",
 	"url"
-]), l = (e, t, n, r) => {
+]), d = (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) => {
+	return typeof a == "string" ? a : n === void 0 || u.has(n) ? i : a;
+}, f = (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;
+		return typeof JSON.parse(i) == "string" ? !1 : n === void 0 || u.has(n) ? !0 : void 0;
 	} catch {
 		return !0;
 	}
-}, d = (e, t) => e.fields[t]?.type, f = (e) => {
+}, p = (e, t) => e.fields[t]?.type, m = (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) => {
+}, h = "id", g = (e, t, n) => {
+	let r = e.tableName ?? "?", a = e.previousTableName, o = e.fields[t]?.renamedFrom, s = a === void 0 ? [r] : [r, a], c = o === void 0 ? [t] : [t, o];
+	return s.flatMap((e) => c.map((t) => i(e, t, n)));
+}, _ = (e, t, n, r) => {
+	let i;
+	for (let a of r) try {
+		return d(e, t, n, a);
+	} catch (e) {
+		i ??= e;
+	}
+	throw i;
+}, v = (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) => {
+	let i = m(t);
+	return i.length === 0 ? e : x(e, i, t.tableName ?? "?", n, r);
+}, y = (e, t, n) => {
+	if (t === void 0 || n == null) return;
+	let r = e[h];
+	if (r === void 0 || String(r) === String(n)) return;
+	let i = m(t);
+	if (i.length === 0) return;
+	let a = t.tableName ?? "?";
+	throw Error(`${a}: an update may not change the id of a row with .encrypted() columns (${i.join(", ")}) — each sealed value is bound to the id it was written under, so ${String(n)} → ${String(r)} would leave every one of them unreadable. Write the row under the new id (insert it, then delete the old one); the store seals its values there.`);
+}, b = (e, t, n) => {
 	if (t === void 0 || e.length === 0) return e;
-	let r = f(t);
+	let r = m(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 };
+	return e.map((e) => x(e, r, i, n));
+}, x = (e, t, n, r, a) => {
+	let o = a ?? e[h], s = { ...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));
+		let t = s[e];
+		if (!(t == null || c(t))) {
+			if (!r) throw Error(`column "${n}.${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`);
+			s[e] = l(r, t, i(n, e, o));
 		}
 	}
-	return l;
-}, _ = (e, t, r, a) => {
+	return s;
+}, S = (e, t, n, r) => {
 	if (!t) return e;
-	let s = f(t);
-	if (s.length === 0 || !r) return e;
-	let c = a?.onError ?? "throw", u = t.tableName ?? "?";
+	let i = m(t);
+	if (i.length === 0 || !n) return e;
+	let a = r?.onError ?? "throw", s = t.tableName ?? "?";
 	return e.map((e) => {
-		let f;
-		for (let m of s) {
-			let s = e[m];
-			if (o(s)) {
-				f ??= { ...e };
+		let l;
+		for (let u of i) {
+			let i = e[u];
+			if (c(i)) {
+				l ??= { ...e };
 				try {
-					f[m] = l(r, s, d(t, m), n(u, m, a?.rowId ?? e[p]));
+					l[u] = _(n, i, p(t, u), g(t, u, r?.rowId ?? e[h]));
 				} catch (e) {
 					let t = String(e?.message ?? e);
-					if (c === "null") {
-						f[m] = null, a?.warn?.({
-							table: u,
-							column: m,
+					if (a === "null") {
+						l[u] = null, r?.warn?.({
+							table: s,
+							column: u,
 							reason: t
 						});
 						continue;
 					}
-					throw new i({
-						table: u,
-						column: m,
+					throw new o({
+						table: s,
+						column: u,
 						reason: t
 					});
 				}
 			}
 		}
-		return f ?? e;
+		return l ?? 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 };
+export { r as BOUND_ENCRYPTED_PREFIX, n as ENCRYPTED_PREFIX, e as FIELD_KEY_ID_PATTERN, o as FieldDecryptionError, t as ciphertextKeyId, d as decodeFieldValue, S as decryptFieldsOnRead, l as encodeFieldValue, v as encryptFieldsForWrite, b as encryptFieldsForWriteBatch, m as encryptedColumnsOf, i as fieldBinding, g as fieldBindingsOf, a as isBoundCiphertext, c as isEncrypted, s as isFieldDecryptionError, f as isRawEncoding, y as refuseIdChangeOfSealedRow };

package/dist/frameworkTables.js

@@ -1,6 +1,6 @@
 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
+// src/frameworkTables.ts
 var o = a("_voltro_migrations", {
 	id: e({ prefix: "mig" }),
 	name: r(),
@@ -61,6 +61,7 @@ var o = a("_voltro_migrations", {
 	id: e({ prefix: "idem" }),
 	scope: r(),
 	key: r(),
+	inputHash: r().nullable(),
 	status: r(),
 	response: n().nullable(),
 	createdAt: i().default("now")
@@ -121,10 +122,21 @@ var o = a("_voltro_migrations", {
 	payload: r().nullable(),
 	reachableAt: r().maxLength(255).nullable(),
 	writtenAt: i().default("now").onUpdate("now")
-}).unique(["replicaId", "kind"]).index(["kind"]), _ = [
+}).unique(["replicaId", "kind"]).index(["kind"]), _ = a("_voltro_api_role_workload_buckets", {
+	id: e({ prefix: "arwb" }),
+	replicaId: r().maxLength(191),
+	startedAt: i(),
+	role: r().maxLength(2080),
+	bucketFrom: i(),
+	bucketUntil: i(),
+	payload: r()
+}).unique("_voltro_arwb_replica_bucket_uq", [
+	"replicaId",
+	"startedAt",
+	"bucketFrom"
+]).index(["bucketUntil"]), v = [
 	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 };
+export { h as _voltroApiKeysTable, _ as _voltroApiRoleWorkloadBucketsTable, 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, v as frameworkTables };

package/dist/ginIndex.js

@@ -1,4 +1,4 @@
-//#region src/ginIndex.ts
+// src/ginIndex.ts
 var e = (e) => {
 	let t = e?.gin?.opclass;
 	if (t !== void 0) {
@@ -6,5 +6,4 @@ var e = (e) => {
 		return t.toLowerCase().replace(/^public\./, "");
 	}
 };
-//#endregion
 export { e as resolveGinOpclass };

package/dist/hybridSearch.js

@@ -1,5 +1,5 @@
 import { resolveFullTextIndex as e } from "./queryBuilder.js";
-//#region src/hybridSearch.ts
+// 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}`);
@@ -28,5 +28,4 @@ var t = (t) => {
 		};
 	};
 };
-//#endregion
 export { t as hybridSearch };

package/dist/idGenerator.js

@@ -1,8 +1,8 @@
 import { validateTypeIdPrefix as e } from "./identifierLimits.js";
-import { generateSnowflake as t } from "./snowflake.js";
-import { typeid as n } from "typeid-js";
+import { typeId as t } from "./typeId.js";
+import { generateSnowflake as n } from "./snowflake.js";
 import { ulid as r } from "ulid";
-//#region src/idGenerator.ts
+// 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.`);
@@ -46,12 +46,11 @@ var i = (t) => {
 	}
 }, o = (e, i) => {
 	switch (e.kind) {
-		case "typeid": return n(e.prefix).toString();
+		case "typeid": return t(e.prefix);
 		case "ulid": return r();
 		case "numeric": return null;
-		case "snowflake": return t();
+		case "snowflake": return n();
 		case "custom": return e.generate(i);
 	}
 };
-//#endregion
 export { i as deriveTypeIdPrefix, o as generateId, a as resolveIdScheme };

package/dist/identifierLimits.js

@@ -1,4 +1,4 @@
-//#region src/identifierLimits.ts
+// src/identifierLimits.ts
 var e = 63, t = 60, n = /* @__PURE__ */ new Set(), r = (e) => {
 	n.add(e);
 }, i = () => {
@@ -28,5 +28,4 @@ var e = 63, t = 60, n = /* @__PURE__ */ new Set(), r = (e) => {
 	}
 	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

@@ -4,6 +4,7 @@ import { Duration } from 'effect/Duration';
 import { Effect } from 'effect';
 import { Exit } from 'effect';
 import { Layer } from 'effect';
+import { NonEmptyReadonlyArray } from 'effect/Array';
 import { Schedule } from 'effect';
 import { Schema } from 'effect';
 import { SqlClient } from 'effect/sql';
@@ -240,12 +241,9 @@ export declare interface AuditActor {
 export declare const auditAllTableIndexes: (tables: ReadonlyArray<Table<string, Record<string, ColumnDefinition<unknown>>, boolean, string>>) => ReadonlyArray<IndexAuditIssue>;
 
 /**
- * Find all index-overlap issues on a single table. Pure function; no
- * side effects. Returns an empty array when the schema is clean.
- *
- * Pair deduplication: each (a, b) collision is reported ONCE, never
- * (a, b) AND (b, a). For `duplicate-fields` we keep the lexicographic
- * lower name as `redundant` so the message is stable across re-runs.
+ * Find index-overlap issues on a single table. Each pair is reported once.
+ * When coverage holds in both directions, the lower name is redundant for
+ * stable output. Otherwise only the proven direction may recommend a drop.
  */
 export declare const auditTableIndexes: (table: Table<string, Record<string, ColumnDefinition<unknown>>, boolean, string>) => ReadonlyArray<IndexAuditIssue>;
 
@@ -293,7 +291,8 @@ export declare const AUTO_FILLED_COLUMNS: readonly ["id", "tenantId", "createdAt
 
 declare type AutoFilledColumn = (typeof AUTO_FILLED_COLUMNS)[number];
 
-export declare const avg: (column: string, alias?: string) => AggregateColumn;
+/** `AVG(column)` — always a `number` (a mean is not exact), `null` over no rows. */
+export declare const avg: (column: string, alias?: string) => AggregateColumn<number | null>;
 
 export declare const avgOver: (column: string, alias?: string) => WindowBuilder;
 
@@ -903,7 +902,25 @@ export declare const changeUpdate: (table: string, before: Row, after: Row, meta
  *
  * `undefined` limits (an unknown dialect) → one group, unchanged behaviour.
  */
-export declare const chunkRowsForInsert: <T extends Record<string, unknown>>(rows: ReadonlyArray<T>, limits: BulkInsertLimits | undefined) => ReadonlyArray<ReadonlyArray<T>>;
+export declare const chunkRowsForInsert: <T extends Record<string, unknown>>(rows: ReadonlyArray<T>, limits: BulkInsertLimits | undefined) => ReadonlyArray<NonEmptyReadonlyArray<T>>;
+
+/**
+ * The id of the key a ciphertext names, read off the value without any key —
+ * what lets a status count values per key instead of decrypting each one.
+ *
+ * The id is the LAST `:`-separated part of the envelope
+ * (`enc:v2:<r|c>:<iv>:<tag>:<ct>:<kid>`, `enc:v1:<iv>:<tag>:<ct>:<kid>`), after
+ * everything a release without key ids reads. That placement is deliberate:
+ * such a release takes the first parts and ignores the rest, so during a
+ * rolling deploy, and after a rollback, it still reads what the keyring wrote.
+ * The id is a lookup hint, not an authenticated field: a value whose id was
+ * altered still has to pass GCM under some key of the keyring, and a reader
+ * that verifies (the retire gate) decrypts rather than trusts it.
+ *
+ * `undefined` for a value written before ids, and for anything that is not a
+ * ciphertext.
+ */
+export declare const ciphertextKeyId: (value: unknown) => string | undefined;
 
 /**
  * Claim the attribution for an echo, or `undefined` if this write did not
@@ -2562,6 +2579,14 @@ export declare interface DataStore {
      * up, on `FluentStore.query`, which is what handlers actually call.
      */
     query(descriptor: QueryDescriptor): Promise<ReadonlyArray<Row>>;
+    /** Server-internal constraint/integrity read on this exact store view.
+     * Bypasses request row visibility only; preserves tenant, deletion/expiry
+     * scopes, codecs, physical namespace and in-flight transaction writes.
+     * Never use its rows as an application response or mutation authorization.
+     * Optional for custom stores: a consumer requiring complete coverage must
+     * refuse when absent, never fall back to an ordinary filtered query.
+     */
+    integrityQuery?(descriptor: QueryDescriptor): Promise<ReadonlyArray<Row>>;
     /** Insert a row. Emits an insert ChangeEvent (deferred if inside `transactional()`). */
     insert(table: string, row: Row): Promise<Row>;
     /**
@@ -2581,8 +2606,14 @@ export declare interface DataStore {
      *   - memory store:                       loop + per-row emit
      *
      * An empty `rows` array is a no-op that returns `[]` (no statement, no events).
+     *
+     * `{ returning: 'none' }` is for a caller that does not read the result: it
+     * resolves to `[]`. The rows are written, and their change events emitted,
+     * exactly as without it; the store reads the inserted rows back only when
+     * change events or an in-transaction recorder need them
+     * (`writeImagesObserved`). A wrapper store forwards `options` unchanged.
      */
-    insertMany(table: string, rows: ReadonlyArray<Row>): Promise<ReadonlyArray<Row>>;
+    insertMany(table: string, rows: ReadonlyArray<Row>, options?: InsertManyOptions): Promise<ReadonlyArray<Row>>;
     /**
      * In-place JSON merge: set `value` at `path` inside the JSON column
      * (`path` is the column name, optionally with a nested dot-path, e.g.
@@ -2978,12 +3009,13 @@ export declare interface DataStore {
      * not. Without a savepoint the two are incompatible, so `--atomic` simply
      * could not import such a bundle on those engines.
      *
-     * Only the TRANSACTIONAL views implement it, and only for the engines that
-     * need it: the mysql family and sqlite leave a transaction usable after a
-     * failed statement, so wrapping every row there would buy nothing and cost a
-     * round trip per row. Callers guard with `if (store.savepoint)` and run `fn`
-     * directly otherwise — which is also correct outside a transaction, where
-     * there is nothing to protect.
+     * Every shipped memory and SQL TRANSACTIONAL view implements it. Besides
+     * statement-abort recovery, it isolates a compound operation whose typed
+     * application error may be handled inside the outer transaction. Rollback
+     * discards that operation's buffered committed-change events as well as rows;
+     * earlier events and successful nesting remain intact. Root stores have no
+     * savepoint. Custom stores may omit it; operations requiring local atomicity
+     * must refuse rather than run without protection.
      *
      * Failures propagate: the savepoint is rolled back and the error rethrown, so
      * the caller's own error handling is unchanged.
@@ -3192,6 +3224,9 @@ export declare interface DbOpSample {
  */
 export declare const decimal: (precision: number, scale?: number) => ColumnBuilder<string, "decimal">;
 
+/** Equality key for exact fixed-point decimal strings; null for invalid input. */
+export declare const decimalEqualityKey: (value: unknown) => string | null;
+
 /**
  * Declare that an enum value was renamed. Place this NEXT TO the
  * `dbEnum(...)` declaration whose value array now carries the new label:
@@ -3276,6 +3311,12 @@ export declare const decodeRowsForTable: <T extends Record<string, unknown>>(row
  */
 export declare const decodeRowsFromSchema: <T extends Record<string, unknown>>(rows: ReadonlyArray<T>, tableName: string, dialect: DecoderDialectId, query?: QueryDescriptor) => ReadonlyArray<T>;
 
+/**
+ * Decode the rows of a SELECT: by the query's aggregations when it has them,
+ * by the table's columns otherwise. Every dialect store's read path calls this.
+ */
+export declare const decodeSelectRows: <T extends Record<string, unknown>>(rows: ReadonlyArray<T>, query: QueryDescriptor, dialect: DecoderDialectId) => ReadonlyArray<T>;
+
 /**
  * Decrypt every `.encrypted()` column's value on read. A value that
  * isn't a framework ciphertext (legacy plaintext, `null`) passes
@@ -3816,6 +3857,9 @@ export declare const encodeFieldValue: (cipher: FieldCipher, value: unknown, bin
  */
 export declare const encodeRowForSchema: <T extends Record<string, unknown>>(row: T, tableName: string, types?: ReadonlyArray<ColumnType>) => T;
 
+/** 16 bytes → the 26-character lowercase Crockford-base32 suffix of the spec. */
+export declare const encodeTypeIdSuffix: (src: Uint8Array) => string;
+
 /** The UNBOUND envelope: `enc:v1:<iv>:<tag>:<ct>`. */
 export declare const ENCRYPTED_PREFIX = "enc:v1:";
 
@@ -3975,6 +4019,13 @@ export declare interface FallbackLogger {
     readonly debug: (message: string, fields?: Record<string, unknown>) => void;
 }
 
+/**
+ * A key id: a short slug, so it can ride inside every envelope. Explicit ids
+ * are chosen by the operator (`VOLTRO_FIELD_ENCRYPTION_KEYS`); derived ids are
+ * `k` + 10 hex characters of a fingerprint that is not the key.
+ */
+export declare const FIELD_KEY_ID_PATTERN: RegExp;
+
 /**
  * Where a ciphertext BELONGS — the table, the column and, when the row's
  * identity is known at write time, the row. Fed to AES-GCM as additional
@@ -4008,6 +4059,16 @@ export declare interface FieldBinding {
  *  its string form and a read of the numeric column agree. */
 export declare const fieldBinding: (table: string, column: string, rowId?: unknown) => FieldBinding;
 
+/**
+ * Every address a column's values may have been sealed under: its own, and the
+ * names a DECLARED rename says it had — `table('new').renamedFrom('old')`, a
+ * column's `.renamedFrom('old')`. A rename is catalog-only, so the rows keep the
+ * bytes bound to the old name; without this every value of a renamed column
+ * stopped opening. Only declared names are added: a value moved anywhere else
+ * still refuses. The own address comes first — a re-key seals under it.
+ */
+export declare const fieldBindingsOf: (table: TableLike, column: string, rowId?: unknown) => ReadonlyArray<FieldBinding>;
+
 /** The cipher the store middleware injects. Operates on opaque strings. */
 export declare interface FieldCipher {
     /**
@@ -4030,6 +4091,15 @@ export declare interface FieldCipher {
      * a cipher with one key.
      */
     readonly sealedWithPreviousKey?: (ciphertext: string, binding?: FieldBinding) => boolean;
+    /** The id of the key new values are sealed under — a keyring's active key. */
+    readonly activeKeyId?: string;
+    /**
+     * The id of the key that opens this value: the one the value names when that
+     * key opens it, otherwise the key of the keyring that does (a value written
+     * before ciphertexts carried an id). `undefined` when no key of the keyring
+     * opens it.
+     */
+    readonly keyIdOf?: (ciphertext: string, binding?: FieldBinding) => string | undefined;
 }
 
 /**
@@ -4714,6 +4784,17 @@ export declare const insertIgnoreRowOutcome: <T extends AnyTable>(store: TypedIn
     readonly outcome: "inserted" | "ignored";
 }>;
 
+/** Options of {@link DataStore.insertMany}. */
+export declare interface InsertManyOptions {
+    /**
+     * `'rows'` (the default) resolves to the inserted rows as stored. `'none'`
+     * resolves to `[]`, so a store need not send the rows back: a bulk insert
+     * into a table no change event or recorder observes then costs one
+     * statement per chunk and no result rows.
+     */
+    readonly returning?: 'rows' | 'none';
+}
+
 /**
  * Insert MANY rows, typed against the table — `insertRow`'s batch, and nothing
  * else: it forwards to `store.insertMany` unchanged, so the chunking, the
@@ -4734,8 +4815,9 @@ export declare const insertIgnoreRowOutcome: <T extends AnyTable>(store: TypedIn
  *
  * An empty array is a legal no-op, so a caller does not have to guard the call
  * — `store.insertMany` decides what that means, and it means "insert nothing".
+ * `{ returning: 'none' }` is forwarded as well: it resolves to `[]`.
  */
-export declare const insertManyRows: <T extends AnyTable>(store: TypedInsertManyStore, table: T, rows: ReadonlyArray<InferInsertRow<T>>) => Promise<ReadonlyArray<InferRow<T>>>;
+export declare const insertManyRows: <T extends AnyTable>(store: TypedInsertManyStore, table: T, rows: ReadonlyArray<InferInsertRow<T>>, options?: InsertManyOptions) => Promise<ReadonlyArray<InferRow<T>>>;
 
 /**
  * Insert a row, typed against the table: the payload must carry every required
@@ -6181,6 +6263,10 @@ Joins extends JoinsMap = {}> {
      * on sqlite (its writers are serialised already).
      */
     forUpdate: () => Query<RowOf, IxNames, Joins>;
+    /** Hold a shared SQL row lock until transaction end; concurrent readers may
+     * proceed. SQLite-family stores retain their transaction isolation without
+     * row-lock SQL, and memory retains optimistic validation. */
+    forShare: () => Query<RowOf, IxNames, Joins>;
     /**
      * Cross-tenant: opt OUT of the runtime's automatic
      * `tenantId = <subject.tenantId>` scope on `tenant()` tables. Use for
@@ -6561,13 +6647,14 @@ export declare interface QueryDescriptor<R = Row> {
     readonly includeExpired?: boolean;
     /**
      * Lock the matched rows for the rest of the enclosing transaction — set by
-     * `.forUpdate()`. `SELECT … FOR UPDATE` on postgres / mysql / mariadb,
-     * `WITH (UPDLOCK, ROWLOCK)` on mssql; sqlite serialises writers already and
+     * `.forUpdate()` for exclusive intent, `.forShare()` for concurrent readers
+     * that must fence writers. SQL dialects retain the lock until transaction end;
+     * sqlite serialises writers already and
      * emits nothing. Outside a transaction the lock is released as the statement
      * ends, which is harmless and useless — the point is a read-modify-write
      * whose read and write share one transaction.
      */
-    readonly lock?: 'update';
+    readonly lock?: 'update' | 'share';
     /**
      * Opt OUT of the runtime's automatic tenant scope on `tenant()` tables.
      * Set by `.unscoped()`. Honored by the runtime, same as `includeDeleted`.
@@ -7063,6 +7150,15 @@ export declare interface ReferenceOptions {
     readonly column?: string;
 }
 
+/**
+ * Refuse an UPDATE that changes the id of a row with `.encrypted()` columns.
+ * Each sealed value is bound to its row's id: an update that moved the row to a
+ * new id left every sealed value in it bound to the old one, reported success,
+ * and from then on every read of the row failed. Move such a row by writing it
+ * under the new id (insert, then delete the old one) — the store seals it there.
+ */
+export declare const refuseIdChangeOfSealedRow: (patch: Row, table: TableLike | undefined, rowId: unknown) => void;
+
 /**
  * Build the error a dialect store throws when the framework refuses a write.
  *
@@ -7286,7 +7382,10 @@ export declare const resolveActorSnapshot: (store: ActorLookupStore, subjectId:
 export declare type ResolveAggregateResult<A, RowOf, Joins extends JoinsMap> = A extends {
     readonly op: 'min' | 'max';
     readonly column: infer C extends string;
-} ? ResolveJoinedSource<C, RowOf, Joins> | null : A extends AggregateColumn<infer T> ? T : never;
+} ? ResolveJoinedSource<C, RowOf, Joins> | null : A extends {
+    readonly op: 'sum';
+    readonly column: infer C extends string;
+} ? [NonNullable<ResolveJoinedSource<C, RowOf, Joins>>] extends [string] ? string | null : number | null : A extends AggregateColumn<infer T> ? T : never;
 
 /**
  * Pick the branch mechanism. Prioritises the Neon copy-on-write fast-path when
@@ -8385,7 +8484,13 @@ export declare interface SubqueryInPredicate {
  */
 export declare type SubqueryResults = Map< QueryDescriptor, Set<unknown> | number>;
 
-export declare const sum: (column: string, alias?: string) => AggregateColumn;
+/** `SUM(column)` — a `number` over `integer()` / `real()`, the exact decimal
+ *  STRING over `decimal()` / `bigint()` (the column's own type), `null` over no
+ *  rows. On a typed query the result type follows the column. */
+export declare const sum: <C extends string>(column: C, alias?: string) => AggregateColumn<number | null> & {
+    readonly op: "sum";
+    readonly column: C;
+};
 
 export declare const sumOver: (column: string, alias?: string) => WindowBuilder;
 
@@ -9277,7 +9382,7 @@ export declare interface TypedInsertIgnoreOutcomeStore {
 
 /** The minimal store surface `insertManyRows` needs. */
 export declare interface TypedInsertManyStore {
-    readonly insertMany: (table: string, rows: ReadonlyArray<Row>) => Promise<ReadonlyArray<Row>>;
+    readonly insertMany: (table: string, rows: ReadonlyArray<Row>, options?: InsertManyOptions) => Promise<ReadonlyArray<Row>>;
 }
 
 /** The minimal store surface `insertRow` needs — satisfied by `ctx.store`. */
@@ -9305,6 +9410,14 @@ export declare interface TypedUpsertStore {
     readonly upsert: (table: string, row: Row, options: UpsertOptions) => Promise<Row>;
 }
 
+/**
+ * A fresh TypeID for `prefix`: `user_01h455vb4pex5vsknk084sn02q`. This is what
+ * the `typeid` id scheme writes on insert; call it yourself when a row's id
+ * has to exist before the insert (a self-referencing `createdBy`, a child row
+ * written in the same flow).
+ */
+export declare const typeId: (prefix: string) => string;
+
 /**
  * `(SELECT ...) UNION (SELECT ...) ...` — dedup-merge. Q6.
  *
@@ -9460,6 +9573,9 @@ export declare const upsertUpdatePatch: (row: Row, existing: Row, options: Upser
 /** Shared driver lowering: omit undefined values and refuse identity rewrites. */
 export declare const upsertUpdateValues: (options: UpsertOptions) => Record<string, unknown>;
 
+/** The 16 bytes of a fresh UUIDv7 (RFC 9562), monotonic within this process. */
+export declare const uuidV7Bytes: (now?: number) => Uint8Array;
+
 /**
  * Validate one column-name key on a table's fields map. Throws on
  * empty / invalid characters / > 63 bytes. Records a WARN above 50.
@@ -9706,6 +9822,9 @@ export declare const VOLTRO_LOCAL_FIRST_MIXIN_ID: "voltro/localFirst";
  */
 export declare const _voltroApiKeysTable: SchemaTable;
 
+/** Finalized role-observation history survives graceful replica shutdown. */
+export declare const _voltroApiRoleWorkloadBucketsTable: SchemaTable;
+
 export declare const _voltroCdcOffsetsTable: TableLike;
 
 /**
@@ -10001,6 +10120,18 @@ export declare interface WriteAttribution {
     readonly via?: 'agent';
 }
 
+/**
+ * Does anything read the row images of a write to `table`? A set-based write
+ * (`updateMany` / `deleteMany`) answers with a count; the stores fetch its rows
+ * back — `RETURNING *`, `OUTPUT`, a SELECT first — only to hand them to change
+ * events and in-transaction recorders. A `.nonReactive()` table that no
+ * recorder watches has neither, and the rows then crossed the wire for nobody:
+ * every retired aggregate generation, `rowData` included, on every refresh.
+ *
+ * Asked per statement, not cached: recorders register and suspend at runtime.
+ */
+export declare const writeImagesObserved: (table: string) => boolean;
+
 export declare type WriteRecorder = (port: TxnRecorderPort, write: RecordedWrite) => Promise<void>;
 
 /** Are recorders suspended right here? Exported so a caller can SAY so. */