@voltro/database 0.67.0 → 0.69.0

package/dist/index.d.ts

@@ -2345,6 +2345,28 @@ export declare interface DataStore {
      *   - memory store:       linear scan + match-by-conflict-columns
      */
     upsert(table: string, row: Row, options: UpsertOptions): Promise<Row>;
+    /**
+     * `upsert`, plus the one thing it cannot report: whether the row was INSERTED
+     * or UPDATED.
+     *
+     * An app that needs to know does the read itself today — look for the row,
+     * then upsert — which costs a round trip AND opens a window in which the
+     * answer stops being true. It does not have to: the framework's store wrapper
+     * mints the id before the statement, and on the conflict path every dialect
+     * hands back the EXISTING row's id. Two ids that differ ARE the answer, for
+     * free.
+     *
+     * Optional, and provided by the framework's wrapper rather than by a dialect
+     * store — the outcome is decided from what the wrapper already knows, so no
+     * dialect implements anything. It is present on `ctx.store` in a handler; a
+     * hand-written `DataStore` need not have it. The typed helper is
+     * `upsertRowOutcome`.
+     *
+     * `'inserted'` is exact, never a default for "could not tell": where the free
+     * comparison cannot answer (the caller supplied the id, or the table's id is
+     * database-assigned) the destination is read first.
+     */
+    upsertWithOutcome?(table: string, row: Row, options: UpsertOptions): Promise<UpsertResult>;
     /**
      * Insert-or-ignore: INSERT a row, but if it conflicts on
      * `conflictColumns`, leave the existing row UNCHANGED and skip the
@@ -4049,6 +4071,29 @@ export declare type InferViewRow<V> = V extends View<string, infer F> ? InferRow
  */
 export declare const INITIAL_VERSION = 1;
 
+/**
+ * Insert MANY rows, typed against the table — `insertRow`'s batch, and nothing
+ * else: it forwards to `store.insertMany` unchanged, so the chunking, the
+ * dialect behaviour and the conflict semantics are exactly what the untyped
+ * call already does. What it adds is the one thing the string-keyed form cannot
+ * have: every element is checked against `InferInsertRow<T>`, so a row that
+ * omits a required column, misspells one, or passes a `number` where the column
+ * is a timestamp is a compile error at the call site instead of a dialect error
+ * somewhere inside the batch.
+ *
+ * That last shape is why the batch form needs its own helper rather than a loop
+ * over `insertRow`: a batch is usually MAPPED from something (a parsed import,
+ * an API page), and a mapping is exactly where a `Date`-vs-`number` mismatch
+ * survives review — the loop body's inferred element type is only as good as
+ * whatever produced the array.
+ *
+ *     await insertManyRows(ctx.store, roadmapEpicStats, rows)
+ *
+ * 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".
+ */
+export declare const insertManyRows: <T extends AnyTable>(store: TypedInsertManyStore, table: T, rows: ReadonlyArray<InferInsertRow<T>>) => Promise<ReadonlyArray<InferRow<T>>>;
+
 /**
  * Insert a row, typed against the table: the payload must carry every required
  * column (NOT NULL, no default, not auto-filled) or it is a compile error.
@@ -8122,6 +8167,11 @@ export declare interface TxnRecorderPort {
     readonly maxOf: TxnMaxOf;
 }
 
+/** The minimal store surface `insertManyRows` needs. */
+export declare interface TypedInsertManyStore {
+    readonly insertMany: (table: string, rows: ReadonlyArray<Row>) => Promise<ReadonlyArray<Row>>;
+}
+
 /** The minimal store surface `insertRow` needs — satisfied by `ctx.store`. */
 export declare interface TypedInsertStore {
     readonly insert: (table: string, row: Row) => Promise<Row>;
@@ -8134,6 +8184,14 @@ export declare interface TypedUpdateManyStore {
     }) => Promise<number>;
 }
 
+/** The minimal store surface `upsertRowOutcome` needs. */
+export declare interface TypedUpsertOutcomeStore {
+    readonly upsertWithOutcome?: (table: string, row: Row, options: UpsertOptions) => Promise<{
+        readonly row: Row;
+        readonly outcome: 'inserted' | 'updated';
+    }>;
+}
+
 /** The minimal store surface `upsertRow` needs. */
 export declare interface TypedUpsertStore {
     readonly upsert: (table: string, row: Row, options: UpsertOptions) => Promise<Row>;
@@ -8243,6 +8301,13 @@ export declare interface UpsertOptions {
     readonly updateValues?: Readonly<Record<string, unknown>>;
 }
 
+/** What an `upsertWithOutcome` did, beside the row it wrote. */
+export declare interface UpsertResult {
+    readonly row: Row;
+    /** `'updated'` means the statement landed on a row that already existed. */
+    readonly outcome: 'inserted' | 'updated';
+}
+
 /**
  * Upsert a row, typed the same way. `conflictColumns` is constrained to the
  * table's own column names, so a typo'd conflict key is a compile error too.
@@ -8253,6 +8318,34 @@ export declare const upsertRow: <T extends AnyTable>(store: TypedUpsertStore, ta
     readonly updateValues?: Readonly<Partial<Omit<InferRow<T>, "id">>>;
 }) => Promise<InferRow<T>>;
 
+/**
+ * `upsertRow`, plus whether the row was INSERTED or UPDATED.
+ *
+ * The reason this exists is one an app measured: to report "created" it had to
+ * run a second query before every upsert — a round trip per row, and a window
+ * in which another writer makes the answer wrong. The store already knows: it
+ * mints the id before the statement, and on the conflict path every dialect
+ * returns the EXISTING row's id.
+ *
+ *     const { row, outcome } = await upsertRowOutcome(ctx.store, players, player, {
+ *       conflictColumns: ['tenantId', 'externalId'],
+ *       update: ['name', 'score'],
+ *     })
+ *     if (outcome === 'inserted') await notifyNewPlayer(row)
+ *
+ * `'inserted'` is never a stand-in for "could not tell". Where the id cannot
+ * decide it — the caller supplied one, or the table's id is database-assigned —
+ * the store reads the destination first and answers exactly.
+ */
+export declare const upsertRowOutcome: <T extends AnyTable>(store: TypedUpsertOutcomeStore, table: T, row: InferInsertRow<T>, options: {
+    readonly conflictColumns: ReadonlyArray<keyof InferRow<T> & string>;
+    readonly update?: ReadonlyArray<keyof InferRow<T> & string> | ((existing: InferRow<T>) => Readonly<Partial<InferRow<T>>>);
+    readonly updateValues?: Readonly<Partial<Omit<InferRow<T>, "id">>>;
+}) => Promise<{
+    readonly row: InferRow<T>;
+    readonly outcome: "inserted" | "updated";
+}>;
+
 /** Conflict patch for stores/callback paths that already have the existing row. */
 export declare const upsertUpdatePatch: (row: Row, existing: Row, options: UpsertOptions) => Row;
 

package/dist/index.js

@@ -2670,29 +2670,36 @@ ${e.all.map((e) => {
 		reason: "null"
 	}));
 	return a;
-}, ml = (e, t, n) => e.insert(t.tableName, n), hl = (e, t, n, r) => e.upsert(t.tableName, n, {
+}, ml = (e, t, n) => e.insert(t.tableName, n), hl = (e, t, n) => e.insertMany(t.tableName, n), gl = (e, t, n, r) => e.upsert(t.tableName, n, {
 	conflictColumns: r.conflictColumns,
 	...r.update === void 0 ? {} : { update: r.update },
 	...r.updateValues === void 0 ? {} : { updateValues: r.updateValues }
-}), gl = (e, t, n, r) => e.updateMany(t.tableName, n, { where: r.where }), _l = 512, vl = (e) => {
+}), _l = async (e, t, n, r) => {
+	if (e.upsertWithOutcome === void 0) throw Error("upsertRowOutcome: this store does not implement `upsertWithOutcome`. It is provided by the framework's store wrapper, so `ctx.store` has it; a hand-written DataStore must add it.");
+	return e.upsertWithOutcome(t.tableName, n, {
+		conflictColumns: r.conflictColumns,
+		...r.update === void 0 ? {} : { update: r.update },
+		...r.updateValues === void 0 ? {} : { updateValues: r.updateValues }
+	});
+}, vl = (e, t, n, r) => e.updateMany(t.tableName, n, { where: r.where }), yl = 512, bl = (e) => {
 	e.setMaxListeners(512);
-}, yl = (e, t, n) => ({
+}, xl = (e, t, n) => ({
 	_tag: "PrimaryKeyConflictError",
 	table: e,
 	key: t,
 	cause: n
-}), bl = (e) => typeof e == "object" && !!e && e._tag === "PrimaryKeyConflictError", xl = {
+}), Sl = (e) => typeof e == "object" && !!e && e._tag === "PrimaryKeyConflictError", Cl = {
 	postgres: 5432,
 	mysql: 3306,
 	mariadb: 3306,
 	mssql: 1433
-}, Sl = /* @__PURE__ */ new Set([
+}, wl = /* @__PURE__ */ new Set([
 	"localhost",
 	"127.0.0.1",
 	"::1",
 	"[::1]",
 	"0.0.0.0"
-]), Cl = (e) => {
+]), Tl = (e) => {
 	let t = e.host, n = e.port, r = e.database;
 	if (e.url !== void 0 && e.url !== "") try {
 		let i = new URL(e.url);
@@ -2701,29 +2708,29 @@ ${e.all.map((e) => {
 		return;
 	}
 	if (t === void 0 || t === "" || r === void 0 || r === "") return;
-	let i = n ?? xl[(e.dialect ?? "").toLowerCase()];
+	let i = n ?? Cl[(e.dialect ?? "").toLowerCase()];
 	if (i === void 0 || !Number.isFinite(i)) return;
 	let a = t.toLowerCase();
 	return {
-		host: Sl.has(a) ? "localhost" : a,
+		host: wl.has(a) ? "localhost" : a,
 		port: i,
 		database: r.toLowerCase()
 	};
-}, wl = (e) => {
-	let t = Cl(e);
+}, El = (e) => {
+	let t = Tl(e);
 	if (t !== void 0) return qt("sha256").update(`${t.host}\u0000${t.port}\u0000${t.database}`).digest("hex").slice(0, 32);
-}, Tl = (e, t) => e === void 0 || t === void 0 ? "unknown" : e === t ? "same" : "different", El = {
+}, Dl = (e, t) => e === void 0 || t === void 0 ? "unknown" : e === t ? "same" : "different", Ol = {
 	app: 3,
 	plugin: 2,
 	framework: 1
-}, Dl = /* @__PURE__ */ new Map(), Ol = [], kl = () => [...Ol], Al = (e) => {
+}, kl = /* @__PURE__ */ new Map(), Al = [], jl = () => [...Al], Ml = (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 = Dl.get(e.table);
+	let t = e.source ?? "app", n = kl.get(e.table);
 	if (n !== void 0) {
 		let r = n.source ?? "app", i = n.ttlMs !== e.ttlMs || n.where !== void 0 != (e.where !== void 0);
-		if (El[t] < El[r]) {
-			i && Ol.push({
+		if (Ol[t] < Ol[r]) {
+			i && Al.push({
 				table: e.table,
 				kept: {
 					source: r,
@@ -2736,7 +2743,7 @@ ${e.all.map((e) => {
 			});
 			return;
 		}
-		i && r !== t && Ol.push({
+		i && r !== t && Al.push({
 			table: e.table,
 			kept: {
 				source: t,
@@ -2748,13 +2755,13 @@ ${e.all.map((e) => {
 			}
 		});
 	}
-	Dl.set(e.table, {
+	kl.set(e.table, {
 		...e,
 		source: t
 	});
-}, jl = () => [...Dl.values()], Ml = () => {
-	Dl.clear(), Ol.length = 0;
-}, Nl = async (e, t, n, r = 2e4) => {
+}, Nl = () => [...kl.values()], Pl = () => {
+	kl.clear(), Al.length = 0;
+}, Fl = async (e, t, n, r = 2e4) => {
 	let i = new Date(t - e.ttlMs), a = 0;
 	try {
 		for (;;) {
@@ -2762,26 +2769,26 @@ ${e.all.map((e) => {
 			if (a += t, t < r) break;
 		}
 	} catch (t) {
-		throw k.runSync(A.increment(A.tagged(Fl, "table", e.table))), t;
+		throw k.runSync(A.increment(A.tagged(Ll, "table", e.table))), t;
 	}
-	return a > 0 && k.runSync(A.incrementBy(A.tagged(Pl, "table", e.table), a)), a;
-}, Pl = A.counter("voltro_retention_swept_rows_total"), Fl = A.counter("voltro_retention_sweep_errors_total"), Il = (e, t) => {
+	return a > 0 && k.runSync(A.incrementBy(A.tagged(Il, "table", e.table), a)), a;
+}, Il = A.counter("voltro_retention_swept_rows_total"), Ll = A.counter("voltro_retention_sweep_errors_total"), Rl = (e, t) => {
 	let n = Number(e ?? String(t));
 	return (Number.isFinite(n) && n > 0 ? n : t) * 36e5;
-}, Ll = "_voltro_cdc_offsets", Rl = T(Ll, {
+}, zl = "_voltro_cdc_offsets", Bl = T(zl, {
 	id: D({ prefix: "cdcoff" }),
 	replicaId: w(),
 	streamName: w(),
 	binlogFile: w(),
 	binlogPosition: w(),
 	updatedAt: E()
-}).index(["replicaId"]), zl = T(Ll, {
+}).index(["replicaId"]), Vl = T(zl, {
 	id: D({ prefix: "cdcoff" }),
 	replicaId: w(),
 	streamName: w(),
 	ctVersion: w(),
 	updatedAt: E()
-}).index(["replicaId"]), Bl = "_voltro_data_transfers", Vl = T(Bl, {
+}).index(["replicaId"]), Hl = "_voltro_data_transfers", Ul = T(Hl, {
 	id: D({ prefix: "dimp" }),
 	startedAt: E().default("now"),
 	finishedAt: E().nullable(),
@@ -2794,13 +2801,13 @@ ${e.all.map((e) => {
 	rowsWritten: y().default(0),
 	failure: w().nullable(),
 	staged: p().nullable()
-}).renamedFrom("_voltro_data_imports").nonReactive(), Hl = (e) => {
+}).renamedFrom("_voltro_data_imports").nonReactive(), Wl = (e) => {
 	let t = Number.isFinite(e.startedAt.getTime()) ? e.startedAt.toISOString() : "an unknown time", n = e.direction === "import" ? e.mode : `${e.direction} ${e.mode}`, r = e.failure === null ? e.finishedAt === null ? `${n} — started and never reported finishing` : e.direction === "backup" || e.direction === "restore" ? `${n} — finished${e.rowsWritten > 0 ? ` (${e.rowsWritten} blob(s))` : ""}` : `${n} — ${e.rowsWritten} row(s) across ${e.tablesWritten} table(s)` : `FAILED ${n} — ${e.failure}`, i = e.staged === null ? "" : e.staged ? " · staged (target untouched until the swap)" : " · NOT staged (target emptied first)";
 	return `${t} · ${r} · via ${e.via}${i}` + (e.bundle === null ? "" : ` · from ${e.bundle}`) + (e.sourceFingerprint === null ? "" : ` · source schema ${e.sourceFingerprint}`);
-}, Ul = 255, Wl = (e) => e == null ? "null" : typeof e == "string" || typeof e == "number" || typeof e == "boolean" ? JSON.stringify(e) : Array.isArray(e) ? `[${e.map(Wl).join(",")}]` : typeof e == "object" ? `{${Object.entries(e).filter(([, e]) => e !== void 0).sort(([e], [t]) => e < t ? -1 : +(e > t)).map(([e, t]) => `${JSON.stringify(e)}:${Wl(t)}`).join(",")}}` : JSON.stringify(String(e)), Gl = (e) => {
+}, Gl = 255, Kl = (e) => e == null ? "null" : typeof e == "string" || typeof e == "number" || typeof e == "boolean" ? JSON.stringify(e) : Array.isArray(e) ? `[${e.map(Kl).join(",")}]` : typeof e == "object" ? `{${Object.entries(e).filter(([, e]) => e !== void 0).sort(([e], [t]) => e < t ? -1 : +(e > t)).map(([e, t]) => `${JSON.stringify(e)}:${Kl(t)}`).join(",")}}` : JSON.stringify(String(e)), ql = (e) => {
 	if (e == null) return null;
-	let t = typeof e == "string" ? e : Wl(e);
+	let t = typeof e == "string" ? e : Kl(e);
 	return t.length > 255 ? t.slice(0, 255) : t;
-}, Kl = "postgres";
+}, Jl = "postgres";
 //#endregion
-export { ct as AUTO_FILLED_COLUMNS, an as BOUND_ENCRYPTED_PREFIX, cl as BULK_INSERT_LIMITS, Y as BranchNameInvalid, tc as BranchTransitionInvalid, Ll as CDC_OFFSETS_TABLE, _o as CHANGE_CLAIM_TTL_ENV, _l as CHANGE_LISTENER_CEILING, Ze as ColumnBuilder, Bl as DATA_TRANSFERS_TABLE, ot as DEFAULT_ACQUIRE_TIMEOUT_MS, vo as DEFAULT_CHANGE_CLAIM_TTL_HOURS, ys as DEFAULT_EAGER_FALLBACK_WARN_INTERVAL_MS, vt as DEFAULT_SOFT_DROP_RETENTION_DAYS, pr as DEFAULT_SUBJECT_GRAPH_DEPTH, rn as ENCRYPTED_PREFIX, Kl as ENGINE, Br as EagerCardinalityError, xt as FILE_MIGRATION_PATTERN, it as FRAMEWORK_LIVE_TABLES, cn as FieldDecryptionError, Vo as ID_COLUMN_MAX_LENGTH, It as INITIAL_VERSION, Ha as MATCHES_NO_ROWS, wt as MAX_IDENTIFIER_LENGTH, As as MSSQL_TRANSIENT_NUMBERS, Os as MYSQL_TRANSIENT_CODES, go as OccurrenceCounter, ks as POSTGRES_TRANSIENT_STATES, Zc as REPLACE_IN_PROGRESS_TABLE, Ul as SCOPE_KEY_MAX_LENGTH, ae as SELF_REFERENCE_TARGET, js as SQLITE_TRANSIENT_CODES, $c as STAGING_STALE_MINUTES, ft as STAGING_TABLE_PREFIX, Xt as SqlClient, Ms as TURSO_TRANSIENT_MESSAGE, Us as TableStreamError, ei as TenantNamespaceInvalid, $r as TenantNamespaceUnresolved, bc as TenantRegionUnavailable, yc as TenantResidencyUnresolved, Ls as VOLTRO_EXPIRES_MIXIN_ID, zs as VOLTRO_LOCAL_FIRST_MIXIN_ID, Nt as VersionConflict, kt as WARN_IDENTIFIER_LENGTH, Jc as _voltroApiKeysTable, Rl as _voltroCdcOffsetsTable, Vl as _voltroDataTransfersTable, Kc as _voltroIdempotencyTable, qc as _voltroKvTable, Gc as _voltroMigrationPlansTable, Uc as _voltroMigrationsTable, zl as _voltroMssqlCdcOffsetsTable, Qc as _voltroReplaceInProgressTable, Yc as _voltroReplicaObservationsTable, Wc as _voltroSeedsTable, Oa as actorsTable, mc as admitBranch, qe as agedSoftDropSnapshots, ye as allEnumRenames, ur as allRegisteredRelations, te as allRegisteredTables, Ka as and, Rr as applyJsonPatch, se as array, za as arrayContains, Va as arrayHas, Ba as arrayOverlaps, Hr as attachEagerLoads, Co as attributionFields, Do as attributionKey, Pc as auditAllTableIndexes, Nc as auditTableIndexes, Tt as avg, ve as avgOver, Io as beginLocalWrite, de as bigint, Oc as bindResidentStore, p as boolean, Qs as branchNamespaceName, ll as bulkInsertLimitsFor, ee as bytes, xn as causeBranches, lo as changeDelete, po as changeDigest, so as changeInsert, uo as changeSoftDelete, co as changeUpdate, dl as chunkRowsForInsert, Ao as claimPendingAttribution, jn as classifyConstraintViolation, d as clearEnumRenames, zo as clearPendingAttribution, fr as clearRelationsRegistry, wc as clearResidencyConfig, Ml as clearRetentions, De as clearTableRegistry, Jo as clearWriteRecorders, W as coercePredicateForSqlite, ci as coercePredicateValue, li as coercePredicateValues, ba as coerceValueForSqlite, io as collectSubqueries, u as column, Bn as columnSchema, ul as columnsPerRow, Ci as compileEagerJson, zr as compileJsonPatch, L as compilePredicate, ui as compileRawFragment, Si as compileSelect, mo as composeChangeKey, Js as computeEmbedding, wl as connectionIdentity, La as contains, c as count, ce as countDistinct, ie as crdtDoc, he as crdtManagedColumns, jt as crdtManagedColumnsOf, a as crdtText, So as currentWriteAttribution, Qe as databaseHandle, Ce as date, _ as dbEnum, ps as dbMetricTagCacheSizeForTests, gs as dbOperationsInFlight, xe as decimal, l as declareEnumRename, pn as decodeFieldValue, Dr as decodeRowsFromSchema, yn as decryptFieldsOnRead, Vc as defineMigration, St as defineMixin, lt as defineSeed, n as denseRank, br as deriveSubjectGraph, ut as deriveTypeIdPrefix, Wo as derivedRowId, Go as derivedRowIdLength, Me as describeAgedSoftDropSnapshots, Pn as describeDriverError, Fn as describeRowBindings, Hl as describeTransferRun, nn as deserializeArraysOnRead, Fe as drainIdentifierWarnings, Te as dropped, dn as encodeFieldValue, kr as encodeRowForSchema, vn as encryptFieldsForWrite, gn as encryptedColumnsOf, Lo as endLocalWrite, dc as enforceBranchLimits, Ee as ensureTableRegistered, ka as eq, di as escapeLike, ro as evaluatePredicate, Xe as except, $a as exists, Rs as expires, oo as externalChangeEvent, wn as extractDbCause, on as fieldBinding, nt as fireSchemaChangeSeeds, Ge as fireTenantCreateSeeds, zc as formatIndexAuditIssue, xr as formatSubjectGraph, Xc as frameworkTables, rt as generateId, We as generateSnowflake, h as geography, re as geometry, le as getEnumRenames, lr as getRelation, cr as getRelations, Cc as getResidencyConfig, C as getTable, ja as gt, Ma as gte, Qr as hasEagerLoads, qs as hybridSearch, D as id, Fa as inSet, Za as inSubquery, $n as inferForeignKey, ml as insertRow, y as integer, nl as interruptedReplaceRefusal, x as intersect, Oe as interval, sn as isBoundCiphertext, $s as isBranchNamespace, Pr as isCompositeRowKey, Jn as isEmptyRelationsSpec, un as isEncrypted, ln as isFieldDecryptionError, Le as isFileMigration, Mn as isForeignKeyViolation, st as isFrameworkOwnedLiveTable, Vs as isLocalFirst, Hc as isMigrationDefinition, mt as isMysqlFamily, ac as isNeonConnection, Wa as isNotNull, Ua as isNull, bl as isPrimaryKeyConflictError, Nn as isQueryTimeout, mn as isRawEncoding, Ec as isRegionServable, Yn as isRelationsSpec, Ue as isSeedDefinition, ht as isSoftDropSnapshotName, Ye as isSqliteFamily, Ie as isStagingTableName, fe as isTableReactive, Fs as isTransientContention, Pe as isView, S as json, Ya as jsonField, _t as jsonIndex, Fr as jsonPatchAssignments, oe as lag, ue as lead, kl as listRetentionConflicts, jl as listRetentions, Bs as localFirst, Hs as localFirstTables, Na as lt, Pa as lte, Ss as makeEagerFallbackReporter, vc as makeNamespaceBranchExecutor, Zn as many, Qn as manyToMany, ke as materializeFields, f as max, Ve as migration, v as min, pl as missingConflictColumns, fl as missingRequiredColumns, Re as mixin, Aa as neq, nc as nextBranchState, Cl as normaliseTarget, Lr as normalizeJsonPatchValue, Ja as not, eo as notExists, Ia as notInSet, Qa as notInSubquery, pe as numeric, vs as observeDbOp, yo as occurrenceWindowMs, Xn as one, Vr as oneCardinalityMessage, qa as or, b as orderClausesOf, me as paginateBy, At as paginateById, ho as parseChangeKey, Bo as pendingAttributionCount, lc as planBranch, rc as planBranchProvision, ic as planBranchTeardown, uc as planBranchTeardownFor, sc as planNeonBranchProvision, cc as planNeonBranchTeardown, Mt as planVersionedUpdate, $e as pluginRef, r as pluginRefSpecOf, yl as primaryKeyConflictError, fc as provisionBranch, kc as provisionResidentTenant, ai as qualifyTable, i as queryFor, Dt as queryForView, Ne as quoteIdent, vl as raiseChangeListenerCeiling, Se as rank, t as raw, ze as readableByColumns, yt as real, _s as recordDbOp, $o as recordsTable, at as reference, Rn as refuseWrite, wa as registerCoreTables, sr as registerDiscoveredRelations, ko as registerPendingAttribution, or as registerRelations, Al as registerRetention, e as registerTable, Ko as registerWriteRecorder, qn as relations, Ea as requireActors, Be as requireTable, Da as requireTenants, fs as resetDbMetricTagCacheForTests, je as resetSnowflake, Dc as residentPlacement, Qt as resolveActorSnapshot, oc as resolveBranchMechanism, xs as resolveEagerFallbackWarnIntervalMs, Ro as resolveEchoAttribution, g as resolveFullTextIndex, Ke as resolveIdScheme, He as resolveMixinGraph, Tc as resolveTenantHome, ii as resolveTenantNamespace, Il as retentionTtlMsFromEnv, Mr as rowKeyColumns, Nr as rowKeyIdentity, be as rowNumber, Vn as rowSchema, Es as runRetryingTransaction, Ds as runStoreTransaction, xo as runWithWriteAttribution, es as runWriteRecorders, Tl as sameDatabase, ri as sanitizeIdentifierFragment, Gl as scopeKeyOf, pt as selfReference, tn as serializeArraysForWrite, Je as serverOnlyColumns, Sc as setResidencyConfig, Ae as setSchemaChangeSeedHook, Ct as setTenantCreateSeedHook, Cs as settleTransactionExit, Ft as settleVersionedUpdate, et as softDropSnapshotStamp, Ga as spatialPredicate, il as stagingLeftoverReport, rl as stagingLeftovers, tl as stagingNamesOf, el as stagingStaleAfterMs, ol as stampGeneratedId, sl as stampGeneratedIds, Ra as startsWith, zn as storeRefusalOf, Ks as streamTable, we as sum, m as sumOver, Xo as suspendWriteRecorders, Zo as suspendWriteRecordersEffect, Nl as sweepRetention, T as table, pc as teardownBranch, w as text, E as timestamp, Rt as timestampMs, Pt as timestampMsOrNull, ne as union, dt as unionAll, bt as unregisterTable, qo as unregisterWriteRecorder, gl as updateManyRow, hl as upsertRow, jr as upsertUpdatePatch, Ar as upsertUpdateValues, Ot as validateColumnName, _e as validateIndexName, dr as validateRegisteredRelations, rr as validateRelationConfig, s as validateTableName, Et as validateTypeIdPrefix, gt as vector, tt as vectorDistanceToOpclass, Ys as vectorEmbedding, Lt as versionColumnOf, ge as view, o as viewSql, ao as walkLeaves, Tn as wireSafeCause, wo as withCapturedAttribution, Qo as writeRecordersSuspended };
+export { ct as AUTO_FILLED_COLUMNS, an as BOUND_ENCRYPTED_PREFIX, cl as BULK_INSERT_LIMITS, Y as BranchNameInvalid, tc as BranchTransitionInvalid, zl as CDC_OFFSETS_TABLE, _o as CHANGE_CLAIM_TTL_ENV, yl as CHANGE_LISTENER_CEILING, Ze as ColumnBuilder, Hl as DATA_TRANSFERS_TABLE, ot as DEFAULT_ACQUIRE_TIMEOUT_MS, vo as DEFAULT_CHANGE_CLAIM_TTL_HOURS, ys as DEFAULT_EAGER_FALLBACK_WARN_INTERVAL_MS, vt as DEFAULT_SOFT_DROP_RETENTION_DAYS, pr as DEFAULT_SUBJECT_GRAPH_DEPTH, rn as ENCRYPTED_PREFIX, Jl as ENGINE, Br as EagerCardinalityError, xt as FILE_MIGRATION_PATTERN, it as FRAMEWORK_LIVE_TABLES, cn as FieldDecryptionError, Vo as ID_COLUMN_MAX_LENGTH, It as INITIAL_VERSION, Ha as MATCHES_NO_ROWS, wt as MAX_IDENTIFIER_LENGTH, As as MSSQL_TRANSIENT_NUMBERS, Os as MYSQL_TRANSIENT_CODES, go as OccurrenceCounter, ks as POSTGRES_TRANSIENT_STATES, Zc as REPLACE_IN_PROGRESS_TABLE, Gl as SCOPE_KEY_MAX_LENGTH, ae as SELF_REFERENCE_TARGET, js as SQLITE_TRANSIENT_CODES, $c as STAGING_STALE_MINUTES, ft as STAGING_TABLE_PREFIX, Xt as SqlClient, Ms as TURSO_TRANSIENT_MESSAGE, Us as TableStreamError, ei as TenantNamespaceInvalid, $r as TenantNamespaceUnresolved, bc as TenantRegionUnavailable, yc as TenantResidencyUnresolved, Ls as VOLTRO_EXPIRES_MIXIN_ID, zs as VOLTRO_LOCAL_FIRST_MIXIN_ID, Nt as VersionConflict, kt as WARN_IDENTIFIER_LENGTH, Jc as _voltroApiKeysTable, Bl as _voltroCdcOffsetsTable, Ul as _voltroDataTransfersTable, Kc as _voltroIdempotencyTable, qc as _voltroKvTable, Gc as _voltroMigrationPlansTable, Uc as _voltroMigrationsTable, Vl as _voltroMssqlCdcOffsetsTable, Qc as _voltroReplaceInProgressTable, Yc as _voltroReplicaObservationsTable, Wc as _voltroSeedsTable, Oa as actorsTable, mc as admitBranch, qe as agedSoftDropSnapshots, ye as allEnumRenames, ur as allRegisteredRelations, te as allRegisteredTables, Ka as and, Rr as applyJsonPatch, se as array, za as arrayContains, Va as arrayHas, Ba as arrayOverlaps, Hr as attachEagerLoads, Co as attributionFields, Do as attributionKey, Pc as auditAllTableIndexes, Nc as auditTableIndexes, Tt as avg, ve as avgOver, Io as beginLocalWrite, de as bigint, Oc as bindResidentStore, p as boolean, Qs as branchNamespaceName, ll as bulkInsertLimitsFor, ee as bytes, xn as causeBranches, lo as changeDelete, po as changeDigest, so as changeInsert, uo as changeSoftDelete, co as changeUpdate, dl as chunkRowsForInsert, Ao as claimPendingAttribution, jn as classifyConstraintViolation, d as clearEnumRenames, zo as clearPendingAttribution, fr as clearRelationsRegistry, wc as clearResidencyConfig, Pl as clearRetentions, De as clearTableRegistry, Jo as clearWriteRecorders, W as coercePredicateForSqlite, ci as coercePredicateValue, li as coercePredicateValues, ba as coerceValueForSqlite, io as collectSubqueries, u as column, Bn as columnSchema, ul as columnsPerRow, Ci as compileEagerJson, zr as compileJsonPatch, L as compilePredicate, ui as compileRawFragment, Si as compileSelect, mo as composeChangeKey, Js as computeEmbedding, El as connectionIdentity, La as contains, c as count, ce as countDistinct, ie as crdtDoc, he as crdtManagedColumns, jt as crdtManagedColumnsOf, a as crdtText, So as currentWriteAttribution, Qe as databaseHandle, Ce as date, _ as dbEnum, ps as dbMetricTagCacheSizeForTests, gs as dbOperationsInFlight, xe as decimal, l as declareEnumRename, pn as decodeFieldValue, Dr as decodeRowsFromSchema, yn as decryptFieldsOnRead, Vc as defineMigration, St as defineMixin, lt as defineSeed, n as denseRank, br as deriveSubjectGraph, ut as deriveTypeIdPrefix, Wo as derivedRowId, Go as derivedRowIdLength, Me as describeAgedSoftDropSnapshots, Pn as describeDriverError, Fn as describeRowBindings, Wl as describeTransferRun, nn as deserializeArraysOnRead, Fe as drainIdentifierWarnings, Te as dropped, dn as encodeFieldValue, kr as encodeRowForSchema, vn as encryptFieldsForWrite, gn as encryptedColumnsOf, Lo as endLocalWrite, dc as enforceBranchLimits, Ee as ensureTableRegistered, ka as eq, di as escapeLike, ro as evaluatePredicate, Xe as except, $a as exists, Rs as expires, oo as externalChangeEvent, wn as extractDbCause, on as fieldBinding, nt as fireSchemaChangeSeeds, Ge as fireTenantCreateSeeds, zc as formatIndexAuditIssue, xr as formatSubjectGraph, Xc as frameworkTables, rt as generateId, We as generateSnowflake, h as geography, re as geometry, le as getEnumRenames, lr as getRelation, cr as getRelations, Cc as getResidencyConfig, C as getTable, ja as gt, Ma as gte, Qr as hasEagerLoads, qs as hybridSearch, D as id, Fa as inSet, Za as inSubquery, $n as inferForeignKey, hl as insertManyRows, ml as insertRow, y as integer, nl as interruptedReplaceRefusal, x as intersect, Oe as interval, sn as isBoundCiphertext, $s as isBranchNamespace, Pr as isCompositeRowKey, Jn as isEmptyRelationsSpec, un as isEncrypted, ln as isFieldDecryptionError, Le as isFileMigration, Mn as isForeignKeyViolation, st as isFrameworkOwnedLiveTable, Vs as isLocalFirst, Hc as isMigrationDefinition, mt as isMysqlFamily, ac as isNeonConnection, Wa as isNotNull, Ua as isNull, Sl as isPrimaryKeyConflictError, Nn as isQueryTimeout, mn as isRawEncoding, Ec as isRegionServable, Yn as isRelationsSpec, Ue as isSeedDefinition, ht as isSoftDropSnapshotName, Ye as isSqliteFamily, Ie as isStagingTableName, fe as isTableReactive, Fs as isTransientContention, Pe as isView, S as json, Ya as jsonField, _t as jsonIndex, Fr as jsonPatchAssignments, oe as lag, ue as lead, jl as listRetentionConflicts, Nl as listRetentions, Bs as localFirst, Hs as localFirstTables, Na as lt, Pa as lte, Ss as makeEagerFallbackReporter, vc as makeNamespaceBranchExecutor, Zn as many, Qn as manyToMany, ke as materializeFields, f as max, Ve as migration, v as min, pl as missingConflictColumns, fl as missingRequiredColumns, Re as mixin, Aa as neq, nc as nextBranchState, Tl as normaliseTarget, Lr as normalizeJsonPatchValue, Ja as not, eo as notExists, Ia as notInSet, Qa as notInSubquery, pe as numeric, vs as observeDbOp, yo as occurrenceWindowMs, Xn as one, Vr as oneCardinalityMessage, qa as or, b as orderClausesOf, me as paginateBy, At as paginateById, ho as parseChangeKey, Bo as pendingAttributionCount, lc as planBranch, rc as planBranchProvision, ic as planBranchTeardown, uc as planBranchTeardownFor, sc as planNeonBranchProvision, cc as planNeonBranchTeardown, Mt as planVersionedUpdate, $e as pluginRef, r as pluginRefSpecOf, xl as primaryKeyConflictError, fc as provisionBranch, kc as provisionResidentTenant, ai as qualifyTable, i as queryFor, Dt as queryForView, Ne as quoteIdent, bl as raiseChangeListenerCeiling, Se as rank, t as raw, ze as readableByColumns, yt as real, _s as recordDbOp, $o as recordsTable, at as reference, Rn as refuseWrite, wa as registerCoreTables, sr as registerDiscoveredRelations, ko as registerPendingAttribution, or as registerRelations, Ml as registerRetention, e as registerTable, Ko as registerWriteRecorder, qn as relations, Ea as requireActors, Be as requireTable, Da as requireTenants, fs as resetDbMetricTagCacheForTests, je as resetSnowflake, Dc as residentPlacement, Qt as resolveActorSnapshot, oc as resolveBranchMechanism, xs as resolveEagerFallbackWarnIntervalMs, Ro as resolveEchoAttribution, g as resolveFullTextIndex, Ke as resolveIdScheme, He as resolveMixinGraph, Tc as resolveTenantHome, ii as resolveTenantNamespace, Rl as retentionTtlMsFromEnv, Mr as rowKeyColumns, Nr as rowKeyIdentity, be as rowNumber, Vn as rowSchema, Es as runRetryingTransaction, Ds as runStoreTransaction, xo as runWithWriteAttribution, es as runWriteRecorders, Dl as sameDatabase, ri as sanitizeIdentifierFragment, ql as scopeKeyOf, pt as selfReference, tn as serializeArraysForWrite, Je as serverOnlyColumns, Sc as setResidencyConfig, Ae as setSchemaChangeSeedHook, Ct as setTenantCreateSeedHook, Cs as settleTransactionExit, Ft as settleVersionedUpdate, et as softDropSnapshotStamp, Ga as spatialPredicate, il as stagingLeftoverReport, rl as stagingLeftovers, tl as stagingNamesOf, el as stagingStaleAfterMs, ol as stampGeneratedId, sl as stampGeneratedIds, Ra as startsWith, zn as storeRefusalOf, Ks as streamTable, we as sum, m as sumOver, Xo as suspendWriteRecorders, Zo as suspendWriteRecordersEffect, Fl as sweepRetention, T as table, pc as teardownBranch, w as text, E as timestamp, Rt as timestampMs, Pt as timestampMsOrNull, ne as union, dt as unionAll, bt as unregisterTable, qo as unregisterWriteRecorder, vl as updateManyRow, gl as upsertRow, _l as upsertRowOutcome, jr as upsertUpdatePatch, Ar as upsertUpdateValues, Ot as validateColumnName, _e as validateIndexName, dr as validateRegisteredRelations, rr as validateRelationConfig, s as validateTableName, Et as validateTypeIdPrefix, gt as vector, tt as vectorDistanceToOpclass, Ys as vectorEmbedding, Lt as versionColumnOf, ge as view, o as viewSql, ao as walkLeaves, Tn as wireSafeCause, wo as withCapturedAttribution, Qo as writeRecordersSuspended };

package/dist/sql.d.ts

@@ -7,7 +7,7 @@ import { SqlError } from '@effect/sql';
 import { SqlError as SqlError_2 } from '@effect/sql/SqlError';
 import { Statement } from '@effect/sql';
 
-export declare const acquireMigrationLock: (sql: SqlClient.SqlClient, scope?: MigrationLockScope) => Effect.Effect<void, SqlError_2>;
+export declare const acquireMigrationLock: (sql: SqlClient.SqlClient, scope?: MigrationLockScope) => Effect.Effect<HeldMigrationLock, SqlError_2>;
 
 declare interface AggregateColumn<TResult = number | Date | null> {
     readonly op: 'count' | 'sum' | 'avg' | 'min' | 'max' | 'count-distinct' | 'window-row-number' | 'window-rank' | 'window-dense-rank' | 'window-lag' | 'window-lead' | 'window-sum-over' | 'window-avg-over' | 'column';
@@ -126,6 +126,14 @@ export declare interface AppliedOp {
  */
 export declare const applyNamespacedSchema: (tables: ReadonlyArray<AnyTable>, namespace: string, dialect?: DialectId, options?: SchemaApplyOptions) => Effect.Effect<void, never, SqlClient.SqlClient>;
 
+/**
+ * Apply a plan, holding the migration lock for the whole of it.
+ *
+ * `acquireUseRelease` rather than a `try/finally` in the body: Effect's own
+ * bracket runs its release on success, on failure, on a defect AND on
+ * interruption, which is exactly the set a JS `finally` inside `Effect.gen`
+ * does not cover.
+ */
 export declare const applyPlan: (sql: SqlClient.SqlClient, plan: MigrationPlan, ctx: ApplyPlanCtx) => Effect.Effect<AppliedMigration, SqlError_2, SqlClient.SqlClient>;
 
 export declare interface ApplyPlanCtx {
@@ -1344,6 +1352,22 @@ export declare const formatBranchRehearsal: (report: BranchRehearsalReport) => s
 /** Human report, or `undefined` when the database and the schema agree. */
 export declare const formatReactiveTriggerDrift: (drift: ReactiveTriggerDrift) => string | undefined;
 
+/**
+ * A lock that is being HELD, and the only way to let it go.
+ *
+ * The reserved connection lives inside this handle: `release` gives the lock
+ * back and closes the reservation, in that order. Returning it as a value
+ * rather than exposing a free `releaseMigrationLock(sql, scope)` is deliberate
+ * — a free release cannot know WHICH connection took the lock, and on every
+ * session-scoped dialect a release on the wrong connection is a no-op that
+ * reports success.
+ */
+export declare interface HeldMigrationLock {
+    /** Release the lock and return its connection to the pool. Idempotent only
+     *  in the sense that the dialect statements are; call it once. */
+    readonly release: Effect.Effect<void, SqlError_2>;
+}
+
 /**
  * Fully-resolved scheme stored on the `id` column definition AFTER
  * `table()` walks the fields. For `typeid`, the prefix is always
@@ -2555,8 +2579,6 @@ export declare const rehearsedOperation: (planned: PlannedOperation) => Rehearse
  */
 export declare const rehearseMigrationOnBranch: (ops: BranchRehearsalOps) => Promise<BranchRehearsalReport>;
 
-export declare const releaseMigrationLock: (sql: SqlClient.SqlClient, scope?: MigrationLockScope) => Effect.Effect<void, SqlError_2>;
-
 export declare const renderColumnMysql: (col: ColumnSnapshot) => string;
 
 export declare const renderColumnPg: (col: ColumnSnapshot) => string;
@@ -3570,12 +3592,6 @@ declare interface WindowSpec {
     }>;
 }
 
-/**
- * Convenience wrapper: acquire → run `work` → release. Releases even
- * on failure via `Effect.ensuring`, but a process crash mid-work
- * leaves the postgres lock held until that connection closes (which
- * the pooled SqlClient does on Effect scope cleanup).
- */
 export declare const withMigrationLock: <A, E, R = never>(sql: SqlClient.SqlClient, work: Effect.Effect<A, E, R>, scope?: MigrationLockScope) => Effect.Effect<A, E | SqlError_2, R>;
 
 /** Tree of relations to eager-load. */