@voltro/database 0.85.0 → 0.87.0

package/dist/idGenerator.js

@@ -0,0 +1,57 @@
+import { validateTypeIdPrefix as e } from "./identifierLimits.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
+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 t(e.prefix);
+		case "ulid": return r();
+		case "numeric": return null;
+		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

@@ -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. */
@@ -293,7 +293,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;
 
@@ -905,6 +906,24 @@ export declare const changeUpdate: (table: string, before: Row, after: Row, meta
  */
 export declare const chunkRowsForInsert: <T extends Record<string, unknown>>(rows: ReadonlyArray<T>, limits: BulkInsertLimits | undefined) => ReadonlyArray<ReadonlyArray<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
  * originate here.
@@ -2562,6 +2581,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 +2608,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 +3011,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 +3226,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 +3313,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 +3859,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 +4021,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 +4061,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 +4093,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;
 }
 
 /**
@@ -4567,11 +4639,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;
@@ -4708,6 +4786,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
@@ -4728,8 +4817,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
@@ -6175,6 +6265,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
@@ -6534,6 +6628,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;
@@ -6550,13 +6649,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`.
@@ -7052,6 +7152,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.
  *
@@ -7275,7 +7384,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
@@ -7470,12 +7582,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]>;
@@ -8374,7 +8486,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;
 
@@ -8914,8 +9032,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;
     /**
@@ -9266,7 +9384,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`. */
@@ -9294,6 +9412,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.
  *
@@ -9449,6 +9575,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.
@@ -9695,6 +9824,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;
 
 /**
@@ -9990,6 +10122,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. */