@mastra/libsql 1.26.0-alpha.2 → 1.26.0

package/dist/index.js

@@ -1,17 +1,360 @@
 import { createClient } from "@libsql/client";
 import { ErrorCategory, ErrorDomain, MastraError } from "@mastra/core/error";
-import { AGENTS_SCHEMA, AGENT_VERSIONS_SCHEMA, AgentsStorage, BackgroundTasksStorage, BlobStore, ChannelsStorage, DATASETS_SCHEMA, DATASET_ITEMS_SCHEMA, DATASET_VERSIONS_SCHEMA, DatasetsStorage, EXPERIMENTS_SCHEMA, EXPERIMENT_RESULTS_SCHEMA, ExperimentsStorage, FAVORITES_SCHEMA, FactoryStorage, FavoritesStorage, HarnessStorage, KNOWLEDGE_SEMANTIC_OUTBOX_SCHEMA, KnowledgeConflictError, KnowledgeNotFoundError, KnowledgeStorage, MCPClientsStorage, MCPServersStorage, MCP_CLIENTS_SCHEMA, MCP_CLIENT_VERSIONS_SCHEMA, MCP_SERVERS_SCHEMA, MCP_SERVER_VERSIONS_SCHEMA, MastraCompositeStore, MemoryStorage, NotificationsStorage, OBSERVATIONAL_MEMORY_TABLE_SCHEMA, ObservabilityStorage, PROMPT_BLOCKS_SCHEMA, PROMPT_BLOCK_VERSIONS_SCHEMA, PromptBlocksStorage, SCORERS_SCHEMA, SCORER_DEFINITIONS_SCHEMA, SCORER_DEFINITION_VERSIONS_SCHEMA, SKILLS_SCHEMA, SKILL_BLOBS_SCHEMA, SKILL_VERSIONS_SCHEMA, SPAN_SCHEMA, SchedulesStorage, ScorerDefinitionsStorage, ScoresStorage, SkillsStorage, TABLE_AGENTS, TABLE_AGENT_VERSIONS, TABLE_BACKGROUND_TASKS, TABLE_CHANNEL_CONFIG, TABLE_CHANNEL_INSTALLATIONS, TABLE_DATASETS, TABLE_DATASET_ITEMS, TABLE_DATASET_VERSIONS, TABLE_EXPERIMENTS, TABLE_EXPERIMENT_RESULTS, TABLE_FAVORITES, TABLE_HARNESS_SESSIONS, TABLE_KNOWLEDGE_ACTIVITY, TABLE_KNOWLEDGE_MENTIONS, TABLE_KNOWLEDGE_NODES, TABLE_KNOWLEDGE_RECORDS, TABLE_KNOWLEDGE_SEMANTIC_OUTBOX, TABLE_MCP_CLIENTS, TABLE_MCP_CLIENT_VERSIONS, TABLE_MCP_SERVERS, TABLE_MCP_SERVER_VERSIONS, TABLE_MESSAGES, TABLE_NOTIFICATIONS, TABLE_PROMPT_BLOCKS, TABLE_PROMPT_BLOCK_VERSIONS, TABLE_RESOURCES, TABLE_SCHEDULES, TABLE_SCHEDULE_TRIGGERS, TABLE_SCHEMAS, TABLE_SCORERS, TABLE_SCORER_DEFINITIONS, TABLE_SCORER_DEFINITION_VERSIONS, TABLE_SKILLS, TABLE_SKILL_BLOBS, TABLE_SKILL_VERSIONS, TABLE_SPANS, TABLE_THREADS, TABLE_THREAD_STATE, TABLE_TOOL_PROVIDER_CONNECTIONS, TABLE_WORKFLOW_DEFINITIONS, TABLE_WORKFLOW_SNAPSHOT, TABLE_WORKSPACES, TABLE_WORKSPACE_VERSIONS, THREAD_STATE_SCHEMA, TOOL_PROVIDER_CONNECTIONS_SCHEMA, ThreadStateStorage, ToolProviderConnectionsStorage, TraceStatus, UniqueViolationError, WORKSPACES_SCHEMA, WORKSPACE_VERSIONS_SCHEMA, WorkflowDefinitionsStorage, WorkflowsStorage, WorkspacesStorage, calculatePagination, canonicalizeKnowledgeScope, createKnowledgeUlid, createStorageErrorId, createVectorErrorId, ensureDate, executeRetentionPrune, getSqlType, hasErrorCode, isKnowledgeScopeVisible, knowledgeScopeKey, knowledgeSemanticDocumentId, knowledgeSemanticIdempotencyKey, listTracesArgsSchema, matchesExpectedWorkflowStatus, mergeWorkflowStepResult, normalizePerPage, normalizeScheduleTarget, parseKnowledgeNodeCursor, parseKnowledgeWikilinks, resolveListOrderBy, resolveRetentionTargets, retentionCutoffMs, runRetentionBatches, safelyParseJSON, toTraceSpans, transformScoreRow, validateStorageMetadataFilter } from "@mastra/core/storage";
+import { AGENTS_SCHEMA, AGENT_VERSIONS_SCHEMA, AgentsStorage, BackgroundTasksStorage, BlobStore, ChannelsStorage, DATASETS_SCHEMA, DATASET_ITEMS_SCHEMA, DATASET_VERSIONS_SCHEMA, DatasetsStorage, EXPERIMENTS_SCHEMA, EXPERIMENT_RESULTS_SCHEMA, ExperimentsStorage, FAVORITES_SCHEMA, FactoryStorage, FavoritesStorage, HarnessStorage, KNOWLEDGE_SEMANTIC_OUTBOX_SCHEMA, KnowledgeConflictError, KnowledgeNotFoundError, KnowledgeStorage, MCPClientsStorage, MCPServersStorage, MCP_CLIENTS_SCHEMA, MCP_CLIENT_VERSIONS_SCHEMA, MCP_SERVERS_SCHEMA, MCP_SERVER_VERSIONS_SCHEMA, MastraCompositeStore, MemoryStorage, NotificationsStorage, OBSERVATIONAL_MEMORY_TABLE_SCHEMA, ObservabilityStorage, PROMPT_BLOCKS_SCHEMA, PROMPT_BLOCK_VERSIONS_SCHEMA, PromptBlocksStorage, RUN_FENCING_TABLE_SCHEMAS, RunFenceConflictError, SCORERS_SCHEMA, SCORER_DEFINITIONS_SCHEMA, SCORER_DEFINITION_VERSIONS_SCHEMA, SKILLS_SCHEMA, SKILL_BLOBS_SCHEMA, SKILL_VERSIONS_SCHEMA, SPAN_SCHEMA, SchedulesStorage, ScorerDefinitionsStorage, ScoresStorage, SkillsStorage, TABLE_AGENTS, TABLE_AGENT_VERSIONS, TABLE_BACKGROUND_TASKS, TABLE_CHANNEL_CONFIG, TABLE_CHANNEL_INSTALLATIONS, TABLE_DATASETS, TABLE_DATASET_ITEMS, TABLE_DATASET_VERSIONS, TABLE_EXPERIMENTS, TABLE_EXPERIMENT_RESULTS, TABLE_FAVORITES, TABLE_HARNESS_SESSIONS, TABLE_KNOWLEDGE_ACTIVITY, TABLE_KNOWLEDGE_MENTIONS, TABLE_KNOWLEDGE_NODES, TABLE_KNOWLEDGE_RECORDS, TABLE_KNOWLEDGE_SEMANTIC_OUTBOX, TABLE_MCP_CLIENTS, TABLE_MCP_CLIENT_VERSIONS, TABLE_MCP_SERVERS, TABLE_MCP_SERVER_VERSIONS, TABLE_MEMORY_RUN_FENCES, TABLE_MESSAGES, TABLE_NOTIFICATIONS, TABLE_PROMPT_BLOCKS, TABLE_PROMPT_BLOCK_VERSIONS, TABLE_RESOURCES, TABLE_SCHEDULES, TABLE_SCHEDULE_TRIGGERS, TABLE_SCHEMAS, TABLE_SCORERS, TABLE_SCORER_DEFINITIONS, TABLE_SCORER_DEFINITION_VERSIONS, TABLE_SKILLS, TABLE_SKILL_BLOBS, TABLE_SKILL_VERSIONS, TABLE_SPANS, TABLE_THREADS, TABLE_THREAD_STATE, TABLE_TOOL_PROVIDER_CONNECTIONS, TABLE_WORKFLOW_DEFINITIONS, TABLE_WORKFLOW_RUN_OWNERS, TABLE_WORKFLOW_SNAPSHOT, TABLE_WORKSPACES, TABLE_WORKSPACE_VERSIONS, THREAD_STATE_SCHEMA, TOOL_PROVIDER_CONNECTIONS_SCHEMA, ThreadStateStorage, ToolProviderConnectionsStorage, TraceStatus, UniqueViolationError, WORKSPACES_SCHEMA, WORKSPACE_VERSIONS_SCHEMA, WorkflowDefinitionsStorage, WorkflowsStorage, WorkspacesStorage, calculatePagination, canonicalizeKnowledgeScope, createKnowledgeUlid, createStorageErrorId, createVectorErrorId, ensureDate, executeRetentionPrune, getSqlType, hasErrorCode, isKnowledgeScopeVisible, isRunFenceConflictError, knowledgeScopeKey, knowledgeSemanticDocumentId, knowledgeSemanticIdempotencyKey, listTracesArgsSchema, matchesExpectedWorkflowStatus, matchesRunFence, mergeWorkflowStepResult, normalizePerPage, normalizeScheduleTarget, parseKnowledgeNodeCursor, parseKnowledgeWikilinks, resolveListOrderBy, resolveRetentionTargets, resolveRunFence, retentionCutoffMs, runRetentionBatches, safelyParseJSON, toTraceSpans, transformScoreRow, validateStorageMetadataFilter } from "@mastra/core/storage";
 import { parseFieldKey, parseSqlIdentifier } from "@mastra/core/utils";
 import { MastraVector, validateTopK, validateUpsertInput } from "@mastra/core/vector";
+import { basename, dirname, isAbsolute, join, resolve } from "path";
+import { AsyncLocalStorage } from "async_hooks";
 import { BaseFilterTranslator } from "@mastra/core/vector/filter";
 import { realpath } from "fs/promises";
-import { basename, dirname, isAbsolute, join, resolve } from "path";
 import { MastraBase } from "@mastra/core/base";
 import { randomUUID } from "crypto";
 import { coreFeatures } from "@mastra/core/features";
 import { MessageList } from "@mastra/core/agent";
 import { saveScorePayloadSchema } from "@mastra/core/evals";
 import { skillSnapshotFieldValuesEqual } from "@mastra/core/storage/domains/skills";
+//#region src/shared/file-transaction-gate.ts
+/** Interactive transactions open in this process, per database file. */
+const openTransactions = /* @__PURE__ */ new Map();
+/** The database file a local `file:` url points at, or `undefined` for anything else. */
+function localDatabaseFileKey(url) {
+	if (!url.startsWith("file:") || url.includes(":memory:")) return void 0;
+	const path = url.slice(5).split("?")[0];
+	return path ? resolve(path.replace(/^\/\/(?=\/)/, "")) : void 0;
+}
+/**
+* Wraps a local `file:` client so its calls wait for interactive transactions
+* that other clients in this process hold open on the same database file,
+* instead of blocking the thread.
+*
+* `@libsql/client` runs local statements synchronously. When one client holds
+* a write transaction open across an `await` and another client writes the same
+* file, SQLite's busy handler spins on the event loop's only thread for
+* `busy_timeout`, so the transaction holding the lock can't resume and the write
+* fails with `SQLITE_BUSY`. Waiting lets the transaction finish first.
+*
+* Only calls on other clients wait; a client already orders its own writes
+* behind its transactions (see `withClientWriteLock`). A call waits at most
+* `maxWaitMs` (the busy timeout), then goes ahead as it would without the gate,
+* so code that awaits another client from inside its own transaction can't hang.
+* Clients in other processes are unaffected and still rely on `busy_timeout`.
+*/
+function gateLocalFileClient(client, key, { maxWaitMs = 5e3 } = {}) {
+	let gated;
+	const othersOpen = () => [...openTransactions.get(key) ?? []].filter((open) => open.owner !== gated);
+	const waitForOthers = () => {
+		if (othersOpen().length === 0) return;
+		return (async () => {
+			let timer;
+			const gaveUp = new Promise((r) => timer = setTimeout(r, maxWaitMs, "timeout"));
+			try {
+				for (let open = othersOpen(); open.length > 0; open = othersOpen()) if (await Promise.race([Promise.all(open.map((o) => o.done)), gaveUp]) === "timeout") return false;
+				return true;
+			} finally {
+				clearTimeout(timer);
+			}
+		})();
+	};
+	const call = (run) => {
+		const waiting = waitForOthers();
+		return waiting ? waiting.then(run) : run();
+	};
+	const transaction = async (open, mode) => {
+		const deadline = Date.now() + maxWaitMs;
+		for (let waiting = waitForOthers(); waiting; waiting = Date.now() < deadline ? waitForOthers() : void 0) if (!await waiting) break;
+		let finish;
+		const entry = {
+			owner: gated,
+			done: new Promise((r) => finish = r)
+		};
+		let set = openTransactions.get(key);
+		if (!set) openTransactions.set(key, set = /* @__PURE__ */ new Set());
+		set.add(entry);
+		const end = () => {
+			if (!set.delete(entry)) return;
+			if (set.size === 0 && openTransactions.get(key) === set) openTransactions.delete(key);
+			finish();
+		};
+		let tx;
+		try {
+			tx = await open(mode);
+		} catch (error) {
+			end();
+			throw error;
+		}
+		return new Proxy(tx, { get(target, prop) {
+			switch (prop) {
+				case "execute":
+				case "batch":
+				case "executeMultiple": {
+					const method = Reflect.get(target, prop);
+					return async (...args) => {
+						try {
+							return await method.apply(target, args);
+						} finally {
+							if (target.closed) end();
+						}
+					};
+				}
+				case "commit":
+				case "rollback": {
+					const method = Reflect.get(target, prop);
+					return async () => {
+						try {
+							await method.call(target);
+						} finally {
+							end();
+						}
+					};
+				}
+				case "close": {
+					const method = Reflect.get(target, prop);
+					return () => {
+						try {
+							method.call(target);
+						} finally {
+							end();
+						}
+					};
+				}
+				default: {
+					const value = Reflect.get(target, prop);
+					return typeof value === "function" ? value.bind(target) : value;
+				}
+			}
+		} });
+	};
+	gated = new Proxy(client, { get(target, prop) {
+		switch (prop) {
+			case "transaction": {
+				const open = Reflect.get(target, prop);
+				return (mode) => transaction(open.bind(target), mode);
+			}
+			case "execute":
+			case "batch":
+			case "executeMultiple":
+			case "migrate": {
+				const method = Reflect.get(target, prop);
+				return (...args) => call(() => method.apply(target, args));
+			}
+			default: {
+				const value = Reflect.get(target, prop);
+				return typeof value === "function" ? value.bind(target) : value;
+			}
+		}
+	} });
+	return gated;
+}
+/** Applies {@link gateLocalFileClient} when `url` is a local database file; returns `client` otherwise. */
+function gateIfLocalFile(client, url, options) {
+	const key = localDatabaseFileKey(url);
+	return key ? gateLocalFileClient(client, key, options) : client;
+}
+//#endregion
+//#region src/shared/reset-after-busy-client.ts
+function isBusy(error) {
+	return error?.code === "SQLITE_BUSY";
+}
+function firstOpen(hold) {
+	while (hold && !hold.open) hold = hold.outer;
+	return hold;
+}
+/**
+* Wraps a pooled local `file:` client so a statement refused with `SQLITE_BUSY`
+* doesn't leave its connection unusable.
+*
+* libsql leaves a write statement whose run failed busy in progress until it is
+* garbage collected (tursodatabase/libsql-js#237). Until then no transaction on
+* that connection can commit ("cannot commit transaction - SQL statements in
+* progress"), and an autocommit write on it stays uncommitted while holding the
+* database's write lock. The pool hands the same connection out again, so
+* retrying the write doesn't help.
+*
+* After a busy failure the wrapper reopens the client's connections, which
+* finalizes the stuck statement. Reopening closes every connection, including
+* borrowed ones, so it waits until no call or transaction made through the
+* wrapper is in flight. New calls wait for the reset rather than join the calls
+* it waits for, so a client that is never idle still gets reset. A call made
+* while its caller holds an open transaction, or from inside another call,
+* doesn't wait: the reset waits for what its caller holds, so waiting would
+* deadlock. Reopened connections start from the pool's connection options,
+* so `afterReset` runs right after to restore any per-connection settings
+* applied after opening, and calls that waited for the reset go on once it
+* settles, even if it fails. A call waits at most `maxWaitMs` (default 5s, the
+* busy timeout) so a long-held transaction can't stall every later call; after
+* that it goes ahead on the current pool. A transaction SQLite rolled back on its
+* own is released as soon as the failing call returns. It must use the client it was given, not the
+* wrapper: calls through the wrapper would wait for the reset it is part of.
+* Every other member passes through untouched.
+*/
+function resetConnectionsAfterBusy(client, { afterReset, maxWaitMs = 5e3 } = {}) {
+	let inFlight = 0;
+	let pendingReset;
+	const holds = new AsyncLocalStorage();
+	const finishReset = () => {
+		const reset = pendingReset;
+		pendingReset = void 0;
+		reset?.finish();
+	};
+	const settle = () => {
+		inFlight--;
+		if (client.closed) return finishReset();
+		if (!pendingReset || inFlight > 0) return;
+		client.reconnect();
+		if (!afterReset) return finishReset();
+		const reset = pendingReset;
+		Promise.resolve().then(afterReset).catch(() => {}).finally(() => {
+			if (pendingReset === reset) finishReset();
+		});
+	};
+	const noteBusy = (error) => {
+		if (!isBusy(error) || pendingReset) return;
+		let finish;
+		pendingReset = {
+			done: new Promise((resolve) => finish = resolve),
+			finish
+		};
+	};
+	const enter = (callerHolds) => {
+		if (!pendingReset || callerHolds || client.closed) {
+			inFlight++;
+			return;
+		}
+		return (async () => {
+			let timer;
+			const gaveUp = new Promise((resolve) => timer = setTimeout(resolve, maxWaitMs, "timeout"));
+			try {
+				while (pendingReset && !client.closed) if (await Promise.race([pendingReset.done, gaveUp]) === "timeout") break;
+			} finally {
+				clearTimeout(timer);
+			}
+			inFlight++;
+		})();
+	};
+	const run = async (call) => {
+		const hold = {
+			open: true,
+			outer: firstOpen(holds.getStore())
+		};
+		const waiting = enter(hold.outer !== void 0);
+		if (waiting) await waiting;
+		try {
+			return await holds.run(hold, call);
+		} catch (error) {
+			noteBusy(error);
+			throw error;
+		} finally {
+			hold.open = false;
+			settle();
+		}
+	};
+	const transaction = (open, mode) => {
+		const hold = {
+			open: true,
+			outer: firstOpen(holds.getStore())
+		};
+		const waiting = enter(hold.outer !== void 0);
+		holds.enterWith(hold);
+		return openTransaction(open, mode, hold, waiting);
+	};
+	const openTransaction = async (open, mode, hold, waiting) => {
+		let tx;
+		try {
+			if (waiting) await waiting;
+			tx = await open(mode);
+		} catch (error) {
+			hold.open = false;
+			noteBusy(error);
+			settle();
+			throw error;
+		}
+		const end = () => {
+			if (!hold.open) return;
+			hold.open = false;
+			settle();
+		};
+		return new Proxy(tx, { get(target, prop) {
+			switch (prop) {
+				case "execute":
+				case "batch":
+				case "executeMultiple": {
+					const method = Reflect.get(target, prop);
+					return async (...args) => {
+						try {
+							return await method.apply(target, args);
+						} catch (error) {
+							noteBusy(error);
+							if (target.closed) try {
+								target.close();
+							} finally {
+								end();
+							}
+							throw error;
+						}
+					};
+				}
+				case "commit":
+				case "rollback": {
+					const method = Reflect.get(target, prop);
+					return async () => {
+						try {
+							await method.call(target);
+						} catch (error) {
+							noteBusy(error);
+							throw error;
+						} finally {
+							end();
+						}
+					};
+				}
+				case "close": {
+					const method = Reflect.get(target, prop);
+					return () => {
+						try {
+							method.call(target);
+						} finally {
+							end();
+						}
+					};
+				}
+				default: {
+					const value = Reflect.get(target, prop);
+					return typeof value === "function" ? value.bind(target) : value;
+				}
+			}
+		} });
+	};
+	return new Proxy(client, { get(target, prop) {
+		switch (prop) {
+			case "transaction": {
+				const open = Reflect.get(target, prop);
+				return (mode) => transaction(open.bind(target), mode);
+			}
+			case "execute":
+			case "batch":
+			case "executeMultiple":
+			case "migrate": {
+				const method = Reflect.get(target, prop);
+				return (...args) => run(() => method.apply(target, args));
+			}
+			case "close": {
+				const method = Reflect.get(target, prop);
+				return () => {
+					try {
+						method.call(target);
+					} finally {
+						finishReset();
+					}
+				};
+			}
+			default: {
+				const value = Reflect.get(target, prop);
+				return typeof value === "function" ? value.bind(target) : value;
+			}
+		}
+	} });
+}
+//#endregion
 //#region src/shared/single-connection-client.ts
 /**
 * Whether `@libsql/client` backs this database with exactly one connection.
@@ -520,7 +863,7 @@ var LibSQLVector = class extends MastraVector {
 		this.turso = isSingleConnectionDatabase({
 			url,
 			syncUrl
-		}) ? gateSingleConnectionClient(client) : client;
+		}) ? gateSingleConnectionClient(client) : isLocalDb ? gateIfLocalFile(resetConnectionsAfterBusy(client, { maxWaitMs: 5e3 }), url, { maxWaitMs: 5e3 }) : client;
 		this.maxRetries = maxRetries;
 		this.initialBackoffMs = initialBackoffMs;
 		if (!Number.isInteger(vectorTopKOverFetchMultiplier) || vectorTopKOverFetchMultiplier < 1) throw new Error("vectorTopKOverFetchMultiplier must be a positive integer");
@@ -1111,6 +1454,110 @@ var LibSQLVector = class extends MastraVector {
 	}
 };
 //#endregion
+//#region src/storage/db/write-lock.ts
+/**
+* Per-client write serialization.
+*
+* `@libsql/client` >= 0.18.0 pools connections for local `file:` databases, but
+* SQLite still admits one writer at a time: an interactive
+* `client.transaction('write')` holds `BEGIN` open across every
+* `await tx.execute(...)`, and any other write on the same database in that
+* window contends on the file lock and can fail with `SQLITE_BUSY` once
+* `busy_timeout` expires.
+*
+* This is dormant under the default engine but the evented engine runs many
+* concurrent workflow snapshot writes per agent run, so a write issued by an
+* unrelated domain (e.g. creating a dataset experiment) can fail spuriously.
+*
+* Serializing every write on a given client closes that window: writes — both
+* autocommit statements and full interactive transactions — run one at a time,
+* so none can interleave with an open transaction. Reads are intentionally not
+* gated; WAL readers never observe a partial write and must not queue behind a
+* long-running writer.
+*
+* `:memory:` databases and embedded replicas get a single pooled connection
+* instead; see `shared/single-connection-client.ts`, which gates *all* calls
+* (reads included) behind open transactions for those clients.
+*/
+const clientWriteChains = /* @__PURE__ */ new WeakMap();
+/**
+* Runs `fn` after every previously-enqueued write on `client` has settled, and
+* returns its result. The chain advances regardless of whether `fn` resolves or
+* rejects, so one failed write never wedges the queue.
+*/
+function withClientWriteLock(client, fn) {
+	const result = (clientWriteChains.get(client) ?? Promise.resolve()).then(fn, fn);
+	clientWriteChains.set(client, result.then(() => void 0, () => void 0));
+	return result;
+}
+//#endregion
+//#region src/storage/db/run-fencing.ts
+/**
+* Epoch milliseconds on the database clock. `julianday('now')` rather than
+* `unixepoch('subsec')`, which needs SQLite 3.42 on the server.
+*/
+const DB_NOW_MS = `CAST(ROUND((julianday('now') - 2440587.5) * 86400000) AS INTEGER)`;
+/**
+* Runs `fn` in a write transaction, behind every other write on `client`.
+* `'write'` opens the transaction with `BEGIN IMMEDIATE`, which takes the
+* database's write lock up front, so nothing written between a read and a
+* write inside `fn` can come from another connection.
+*/
+function inWriteTransaction(client, fn) {
+	return withClientWriteLock(client, async () => {
+		const tx = await client.transaction("write");
+		try {
+			const result = await fn(tx);
+			await tx.commit();
+			return result;
+		} catch (error) {
+			if (!tx.closed) await tx.rollback();
+			throw error;
+		} finally {
+			if (!tx.closed) tx.close();
+		}
+	});
+}
+/**
+* The check half of a fenced write; call it first inside the write's
+* transaction. The transaction already holds the database's write lock, so
+* a claim can't commit between this check and the write.
+*/
+async function assertRunFence(tx, { claimsTable, fence, operation }) {
+	const row = (await tx.execute({
+		sql: `SELECT generation, ownerId FROM ${claimsTable} WHERE runId = ?`,
+		args: [fence.runId]
+	})).rows[0];
+	if (!matchesRunFence(row ? {
+		generation: Number(row.generation),
+		ownerId: String(row.ownerId)
+	} : null, fence)) throw new RunFenceConflictError(fence, operation);
+}
+/**
+* Runs `write` behind the client's write lock: directly when there is no
+* fence to check, or in a write transaction behind the check when there is.
+* `write` must issue every statement through the writer it is given; on a
+* single-connection client, a call on the client itself would wait for the
+* open transaction forever.
+*/
+function withRunFence(client, check, write) {
+	if (!check) return withClientWriteLock(client, () => write({
+		execute: (statement) => client.execute(statement),
+		batch: (statements) => client.batch(statements, "write")
+	}));
+	return inWriteTransaction(client, async (tx) => {
+		await assertRunFence(tx, check);
+		return write({
+			execute: (statement) => tx.execute(statement),
+			batch: async (statements) => {
+				const results = [];
+				for (const statement of statements) results.push(await tx.execute(statement));
+				return results;
+			}
+		});
+	});
+}
+//#endregion
 //#region src/storage/db/utils.ts
 const MAX_DEPTH = 100;
 /**
@@ -1203,6 +1650,7 @@ function createExecuteWriteOperationWithRetry({ logger, maxRetries, initialBacko
 		while (attempts < maxRetries) try {
 			return await operationFn();
 		} catch (error) {
+			if (isRunFenceConflictError(error)) throw error;
 			logger.debug(`LibSQLStore: Error caught in retry loop for ${operationDescription}`, {
 				errorType: error.constructor.name,
 				errorCode: error.code,
@@ -1363,43 +1811,6 @@ function transformFromSqlRow({ tableName, sqlRow }) {
 	return result;
 }
 //#endregion
-//#region src/storage/db/write-lock.ts
-/**
-* Per-client write serialization.
-*
-* `@libsql/client` >= 0.18.0 pools connections for local `file:` databases, but
-* SQLite still admits one writer at a time: an interactive
-* `client.transaction('write')` holds `BEGIN` open across every
-* `await tx.execute(...)`, and any other write on the same database in that
-* window contends on the file lock and can fail with `SQLITE_BUSY` once
-* `busy_timeout` expires.
-*
-* This is dormant under the default engine but the evented engine runs many
-* concurrent workflow snapshot writes per agent run, so a write issued by an
-* unrelated domain (e.g. creating a dataset experiment) can fail spuriously.
-*
-* Serializing every write on a given client closes that window: writes — both
-* autocommit statements and full interactive transactions — run one at a time,
-* so none can interleave with an open transaction. Reads are intentionally not
-* gated; WAL readers never observe a partial write and must not queue behind a
-* long-running writer.
-*
-* `:memory:` databases and embedded replicas get a single pooled connection
-* instead; see `shared/single-connection-client.ts`, which gates *all* calls
-* (reads included) behind open transactions for those clients.
-*/
-const clientWriteChains = /* @__PURE__ */ new WeakMap();
-/**
-* Runs `fn` after every previously-enqueued write on `client` has settled, and
-* returns its result. The chain advances regardless of whether `fn` resolves or
-* rejects, so one failed write never wedges the queue.
-*/
-function withClientWriteLock(client, fn) {
-	const result = (clientWriteChains.get(client) ?? Promise.resolve()).then(fn, fn);
-	clientWriteChains.set(client, result.then(() => void 0, () => void 0));
-	return result;
-}
-//#endregion
 //#region src/storage/db/index.ts
 /**
 * Default SQLite `busy_timeout` (ms) for local LibSQL connections. Chosen to
@@ -1500,10 +1911,10 @@ var LibSQLDB = class extends MastraBase {
 	/**
 	* Internal insert implementation without retry logic.
 	*/
-	async doInsert({ tableName, record }) {
+	async doInsert({ tableName, record, check }) {
 		const filteredRecord = await this.filterRecordToKnownColumns(tableName, record);
 		if (Object.keys(filteredRecord).length === 0) return;
-		await withClientWriteLock(this.client, () => this.client.execute(prepareStatement({
+		await withRunFence(this.client, check, (writer) => writer.execute(prepareStatement({
 			tableName,
 			record: filteredRecord
 		})));
@@ -1514,6 +1925,7 @@ var LibSQLDB = class extends MastraBase {
 	* @param args - The insert arguments
 	* @param args.tableName - The name of the table to insert into
 	* @param args.record - The record to insert (key-value pairs)
+	* @param args.check - The run fence the insert must carry, if any
 	*/
 	insert(args) {
 		return this.executeWriteOperationWithRetry(() => this.doInsert(args), `insert into table ${args.tableName}`);
@@ -8918,6 +9330,10 @@ var MemoryLibSQL = class MemoryLibSQL extends MemoryStorage {
 	* Retention-eligible tables. `threads`, `messages`, and `resources` all anchor
 	* on `createdAt` and are indexed for fast batched deletes. Cascade order is
 	* enforced in `prune()` (children before threads), not here.
+	*
+	* Run fences anchor on `retiredAt` (epoch ms), which stays NULL until the
+	* execution holding the fence settles, so a running execution's fence is
+	* never pruned.
 	*/
 	static retentionTables = {
 		messages: {
@@ -8934,6 +9350,12 @@ var MemoryLibSQL = class MemoryLibSQL extends MemoryStorage {
 			table: TABLE_THREADS,
 			column: "createdAt",
 			indexed: true
+		},
+		runFences: {
+			table: TABLE_MEMORY_RUN_FENCES,
+			column: "retiredAt",
+			indexed: true,
+			anchorType: "epoch-ms"
 		}
 	};
 	#client;
@@ -8956,6 +9378,13 @@ var MemoryLibSQL = class MemoryLibSQL extends MemoryStorage {
 	#write(operation, fn) {
 		return this.#db.executeWriteOperationWithRetry(() => withClientWriteLock(this.#client, fn), operation);
 	}
+	/**
+	* `#write` for a write that may carry a run fence: with a check, it runs in a write
+	* transaction behind the check, and a retry reruns the whole transaction.
+	*/
+	#fencedWrite(operation, check, write) {
+		return this.#db.executeWriteOperationWithRetry(() => withRunFence(this.#client, check, write), operation);
+	}
 	async init() {
 		await this.#db.createTable({
 			tableName: TABLE_THREADS,
@@ -8969,6 +9398,10 @@ var MemoryLibSQL = class MemoryLibSQL extends MemoryStorage {
 			tableName: TABLE_RESOURCES,
 			schema: TABLE_SCHEMAS[TABLE_RESOURCES]
 		});
+		await this.#db.createTable({
+			tableName: TABLE_MEMORY_RUN_FENCES,
+			schema: RUN_FENCING_TABLE_SCHEMAS[TABLE_MEMORY_RUN_FENCES]
+		});
 		const omSchema = OBSERVATIONAL_MEMORY_TABLE_SCHEMA?.[OM_TABLE];
 		if (omSchema) {
 			await this.#db.createTable({
@@ -9020,6 +9453,70 @@ var MemoryLibSQL = class MemoryLibSQL extends MemoryStorage {
 		await this.#db.deleteData({ tableName: TABLE_THREADS });
 		await this.#db.deleteData({ tableName: TABLE_RESOURCES });
 		await this.#db.deleteData({ tableName: OM_TABLE });
+		await this.#db.deleteData({ tableName: TABLE_MEMORY_RUN_FENCES });
+	}
+	supportsRunFencing() {
+		return true;
+	}
+	async raiseRunFence(fence) {
+		try {
+			return await this.#db.executeWriteOperationWithRetry(() => inWriteTransaction(this.#client, async (tx) => {
+				const row = (await tx.execute({
+					sql: `SELECT generation, ownerId FROM ${TABLE_MEMORY_RUN_FENCES} WHERE runId = ?`,
+					args: [fence.runId]
+				})).rows[0];
+				const generation = row ? Number(row.generation) : void 0;
+				const raises = generation === void 0 || generation < fence.generation;
+				const reaffirms = generation === fence.generation && String(row.ownerId) === fence.ownerId;
+				if (!raises && !reaffirms) return false;
+				await tx.execute({
+					sql: `INSERT INTO ${TABLE_MEMORY_RUN_FENCES} (runId, generation, ownerId) VALUES (?, ?, ?)
+                ON CONFLICT(runId) DO UPDATE SET generation = excluded.generation, ownerId = excluded.ownerId, retiredAt = NULL`,
+					args: [
+						fence.runId,
+						fence.generation,
+						fence.ownerId
+					]
+				});
+				return true;
+			}), "raiseRunFence");
+		} catch (error) {
+			throw new MastraError({
+				id: createStorageErrorId("LIBSQL", "RAISE_RUN_FENCE", "FAILED"),
+				domain: ErrorDomain.STORAGE,
+				category: ErrorCategory.THIRD_PARTY,
+				details: { runId: fence.runId }
+			}, error);
+		}
+	}
+	async retireRunFence(fence) {
+		try {
+			return (await this.#db.executeWriteOperationWithRetry(() => withClientWriteLock(this.#client, () => this.#client.execute({
+				sql: `UPDATE ${TABLE_MEMORY_RUN_FENCES} SET retiredAt = ${DB_NOW_MS}
+                WHERE runId = ? AND generation = ? AND ownerId = ?`,
+				args: [
+					fence.runId,
+					fence.generation,
+					fence.ownerId
+				]
+			})), "retireRunFence")).rowsAffected > 0;
+		} catch (error) {
+			throw new MastraError({
+				id: createStorageErrorId("LIBSQL", "RETIRE_RUN_FENCE", "FAILED"),
+				domain: ErrorDomain.STORAGE,
+				category: ErrorCategory.THIRD_PARTY,
+				details: { runId: fence.runId }
+			}, error);
+		}
+	}
+	/** The check a write must pass: its own fence, otherwise the one in scope. */
+	#runFenceCheck(fence, operation) {
+		const resolved = resolveRunFence(this, fence);
+		return resolved && {
+			claimsTable: TABLE_MEMORY_RUN_FENCES,
+			fence: resolved,
+			operation
+		};
 	}
 	/**
 	* Delete rows older than each policy's `maxAge`, batched and cancellable.
@@ -9035,7 +9532,8 @@ var MemoryLibSQL = class MemoryLibSQL extends MemoryStorage {
 			order: [
 				"messages",
 				"resources",
-				"threads"
+				"threads",
+				"runFences"
 			]
 		});
 		return runPrune({
@@ -9417,7 +9915,7 @@ var MemoryLibSQL = class MemoryLibSQL extends MemoryStorage {
 			throw mastraError;
 		}
 	}
-	async saveMessages({ messages }) {
+	async saveMessages({ messages, fence }) {
 		if (messages.length === 0) return { messages };
 		try {
 			const threadId = messages[0]?.threadId;
@@ -9455,13 +9953,16 @@ var MemoryLibSQL = class MemoryLibSQL extends MemoryStorage {
 			const BATCH_SIZE = 50;
 			const messageStatements = batchStatements.slice(0, -1);
 			const threadUpdateStatement = batchStatements[batchStatements.length - 1];
-			for (let i = 0; i < messageStatements.length; i += BATCH_SIZE) {
-				const batch = messageStatements.slice(i, i + BATCH_SIZE);
-				if (batch.length > 0) await this.#write("saveMessages", () => this.#client.batch(batch, "write"));
-			}
-			if (threadUpdateStatement) await this.#write("saveMessages", () => this.#client.execute(threadUpdateStatement));
+			await this.#fencedWrite("saveMessages", this.#runFenceCheck(fence, "saveMessages"), async (writer) => {
+				for (let i = 0; i < messageStatements.length; i += BATCH_SIZE) {
+					const batch = messageStatements.slice(i, i + BATCH_SIZE);
+					if (batch.length > 0) await writer.batch(batch);
+				}
+				if (threadUpdateStatement) await writer.execute(threadUpdateStatement);
+			});
 			return { messages: new MessageList().add(messages, "memory").get.all.db() };
 		} catch (error) {
+			if (isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("LIBSQL", "SAVE_MESSAGES", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -9469,11 +9970,14 @@ var MemoryLibSQL = class MemoryLibSQL extends MemoryStorage {
 			}, error);
 		}
 	}
-	async updateMessages({ messages }) {
+	async updateMessages({ messages, fence }) {
 		if (messages.length === 0) return [];
+		return this.#fencedWrite("updateMessages", this.#runFenceCheck(fence, "updateMessages"), (writer) => this.#updateMessages(writer, messages));
+	}
+	async #updateMessages(writer, messages) {
 		const messageIds = messages.map((m) => m.id);
 		const selectSql = `SELECT * FROM ${TABLE_MESSAGES} WHERE id IN (${messageIds.map(() => "?").join(",")})`;
-		const existingMessages = (await this.#client.execute({
+		const existingMessages = (await writer.execute({
 			sql: selectSql,
 			args: messageIds
 		})).rows.map((row) => this.parseRow(row));
@@ -9525,48 +10029,44 @@ var MemoryLibSQL = class MemoryLibSQL extends MemoryStorage {
 			sql: `UPDATE ${TABLE_THREADS} SET updatedAt = ? WHERE id = ?`,
 			args: [now, threadId]
 		});
-		await this.#write("updateMessages", () => this.#client.batch(batchStatements, "write"));
-		return (await this.#client.execute({
+		await writer.batch(batchStatements);
+		return (await writer.execute({
 			sql: selectSql,
 			args: messageIds
 		})).rows.map((row) => this.parseRow(row));
 	}
-	async deleteMessages(messageIds) {
+	async deleteMessages(messageIds, options) {
 		if (!messageIds || messageIds.length === 0) return;
 		try {
 			const BATCH_SIZE = 100;
-			await this.#write("deleteMessages", async () => {
+			const check = this.#runFenceCheck(options?.fence, "deleteMessages");
+			await this.#db.executeWriteOperationWithRetry(() => inWriteTransaction(this.#client, async (tx) => {
+				if (check) await assertRunFence(tx, check);
 				const threadIds = /* @__PURE__ */ new Set();
-				const tx = await this.#client.transaction("write");
-				try {
-					for (let i = 0; i < messageIds.length; i += BATCH_SIZE) {
-						const batch = messageIds.slice(i, i + BATCH_SIZE);
-						const placeholders = batch.map(() => "?").join(",");
-						(await tx.execute({
-							sql: `SELECT DISTINCT thread_id FROM "${TABLE_MESSAGES}" WHERE id IN (${placeholders})`,
-							args: batch
-						})).rows?.forEach((row) => {
-							if (row.thread_id) threadIds.add(row.thread_id);
-						});
-						await tx.execute({
-							sql: `DELETE FROM "${TABLE_MESSAGES}" WHERE id IN (${placeholders})`,
-							args: batch
-						});
-					}
-					if (threadIds.size > 0) {
-						const now = (/* @__PURE__ */ new Date()).toISOString();
-						for (const threadId of threadIds) await tx.execute({
-							sql: `UPDATE "${TABLE_THREADS}" SET "updatedAt" = ? WHERE id = ?`,
-							args: [now, threadId]
-						});
-					}
-					await tx.commit();
-				} catch (error) {
-					await tx.rollback();
-					throw error;
+				for (let i = 0; i < messageIds.length; i += BATCH_SIZE) {
+					const batch = messageIds.slice(i, i + BATCH_SIZE);
+					const placeholders = batch.map(() => "?").join(",");
+					(await tx.execute({
+						sql: `SELECT DISTINCT thread_id FROM "${TABLE_MESSAGES}" WHERE id IN (${placeholders})`,
+						args: batch
+					})).rows?.forEach((row) => {
+						if (row.thread_id) threadIds.add(row.thread_id);
+					});
+					await tx.execute({
+						sql: `DELETE FROM "${TABLE_MESSAGES}" WHERE id IN (${placeholders})`,
+						args: batch
+					});
 				}
-			});
+				if (threadIds.size > 0) {
+					const now = (/* @__PURE__ */ new Date()).toISOString();
+					for (const threadId of threadIds) await tx.execute({
+						sql: `UPDATE "${TABLE_THREADS}" SET "updatedAt" = ? WHERE id = ?`,
+						args: [now, threadId]
+					});
+				}
+			}), "deleteMessages");
 		} catch (error) {
+			if (isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("LIBSQL", "DELETE_MESSAGES", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -9590,13 +10090,18 @@ var MemoryLibSQL = class MemoryLibSQL extends MemoryStorage {
 		};
 	}
 	async saveResource({ resource }) {
+		return this.#insertResource(resource, void 0);
+	}
+	async #insertResource(resource, check) {
 		await this.#db.insert({
 			tableName: TABLE_RESOURCES,
-			record: { ...resource }
+			record: { ...resource },
+			check
 		});
 		return resource;
 	}
-	async updateResource({ resourceId, workingMemory, metadata }) {
+	async updateResource({ resourceId, workingMemory, metadata, fence }) {
+		const check = this.#runFenceCheck(fence, "updateResource");
 		const existingResource = await this.getResourceById({ resourceId });
 		if (!existingResource) {
 			const newResource = {
@@ -9606,7 +10111,7 @@ var MemoryLibSQL = class MemoryLibSQL extends MemoryStorage {
 				createdAt: /* @__PURE__ */ new Date(),
 				updatedAt: /* @__PURE__ */ new Date()
 			};
-			return this.saveResource({ resource: newResource });
+			return this.#insertResource(newResource, check);
 		}
 		const updatedResource = {
 			...existingResource,
@@ -9630,7 +10135,7 @@ var MemoryLibSQL = class MemoryLibSQL extends MemoryStorage {
 		updates.push("updatedAt = ?");
 		values.push(updatedResource.updatedAt.toISOString());
 		values.push(resourceId);
-		await this.#write("updateResource", () => this.#client.execute({
+		await this.#fencedWrite("updateResource", check, (writer) => writer.execute({
 			sql: `UPDATE ${TABLE_RESOURCES} SET ${updates.join(", ")} WHERE id = ?`,
 			args: values
 		}));
@@ -9834,14 +10339,16 @@ var MemoryLibSQL = class MemoryLibSQL extends MemoryStorage {
 			throw mastraError;
 		}
 	}
-	async saveThread({ thread }) {
+	async saveThread({ thread, fence }) {
 		try {
 			await this.#db.insert({
 				tableName: TABLE_THREADS,
-				record: { ...thread }
+				record: { ...thread },
+				check: this.#runFenceCheck(fence, "saveThread")
 			});
 			return thread;
 		} catch (error) {
+			if (isRunFenceConflictError(error)) throw error;
 			const mastraError = new MastraError({
 				id: createStorageErrorId("LIBSQL", "SAVE_THREAD", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -9853,7 +10360,8 @@ var MemoryLibSQL = class MemoryLibSQL extends MemoryStorage {
 			throw mastraError;
 		}
 	}
-	async updateThread({ id, title, metadata }) {
+	async updateThread({ id, title, metadata, fence }) {
+		const check = this.#runFenceCheck(fence, "updateThread");
 		const thread = await this.getThreadById({ threadId: id });
 		if (!thread) throw new MastraError({
 			id: createStorageErrorId("LIBSQL", "UPDATE_THREAD", "NOT_FOUND"),
@@ -9876,7 +10384,7 @@ var MemoryLibSQL = class MemoryLibSQL extends MemoryStorage {
 			updatedAt: now
 		};
 		try {
-			await this.#write("updateThread", () => this.#client.execute({
+			await this.#fencedWrite("updateThread", check, (writer) => writer.execute({
 				sql: `UPDATE ${TABLE_THREADS} SET title = COALESCE(?, title), metadata = jsonb(?), updatedAt = ? WHERE id = ?`,
 				args: [
 					title ?? null,
@@ -9887,6 +10395,7 @@ var MemoryLibSQL = class MemoryLibSQL extends MemoryStorage {
 			}));
 			return updatedThread;
 		} catch (error) {
+			if (isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("LIBSQL", "UPDATE_THREAD", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -10297,7 +10806,7 @@ var MemoryLibSQL = class MemoryLibSQL extends MemoryStorage {
 		try {
 			const now = /* @__PURE__ */ new Date();
 			const observedMessageIdsJson = input.observedMessageIds ? JSON.stringify(input.observedMessageIds) : null;
-			if ((await this.#write("updateActiveObservations", () => this.#client.execute({
+			if ((await this.#fencedWrite("updateActiveObservations", this.#runFenceCheck(void 0, "updateActiveObservations"), (writer) => writer.execute({
 				sql: `UPDATE "${OM_TABLE}" SET
             "activeObservations" = ?,
             "lastObservedAt" = ?,
@@ -10335,9 +10844,11 @@ var MemoryLibSQL = class MemoryLibSQL extends MemoryStorage {
 	}
 	async createReflectionGeneration(input) {
 		try {
+			const check = this.#runFenceCheck(void 0, "createReflectionGeneration");
 			return await this.#write("createReflectionGeneration", async () => {
 				const tx = await this.#client.transaction("write");
 				try {
+					if (check) await assertRunFence(tx, check);
 					const record = await this.#insertReflectionGeneration(tx, input);
 					await tx.commit();
 					return record;
@@ -10674,9 +11185,11 @@ var MemoryLibSQL = class MemoryLibSQL extends MemoryStorage {
 	async updateBufferedObservations(input) {
 		try {
 			const nowStr = (/* @__PURE__ */ new Date()).toISOString();
+			const check = this.#runFenceCheck(void 0, "updateBufferedObservations");
 			await this.#write("updateBufferedObservations", async () => {
 				const tx = await this.#client.transaction("write");
 				try {
+					if (check) await assertRunFence(tx, check);
 					const current = await tx.execute({
 						sql: `SELECT "bufferedObservationChunks" FROM "${OM_TABLE}" WHERE id = ?`,
 						args: [input.id]
@@ -10755,9 +11268,11 @@ var MemoryLibSQL = class MemoryLibSQL extends MemoryStorage {
 	async swapBufferedToActive(input) {
 		try {
 			const nowStr = (/* @__PURE__ */ new Date()).toISOString();
+			const check = this.#runFenceCheck(void 0, "swapBufferedToActive");
 			return await this.#write("swapBufferedToActive", async () => {
 				const tx = await this.#client.transaction("write");
 				try {
+					if (check) await assertRunFence(tx, check);
 					const current = await tx.execute({
 						sql: `SELECT * FROM "${OM_TABLE}" WHERE id = ?`,
 						args: [input.id]
@@ -10904,7 +11419,7 @@ var MemoryLibSQL = class MemoryLibSQL extends MemoryStorage {
 	async updateBufferedReflection(input) {
 		try {
 			const nowStr = (/* @__PURE__ */ new Date()).toISOString();
-			if ((await this.#write("updateBufferedReflection", () => this.#client.execute({
+			if ((await this.#fencedWrite("updateBufferedReflection", this.#runFenceCheck(void 0, "updateBufferedReflection"), (writer) => writer.execute({
 				sql: `UPDATE "${OM_TABLE}" SET
             "bufferedReflection" = CASE
               WHEN "bufferedReflection" IS NOT NULL AND "bufferedReflection" != ''
@@ -10944,9 +11459,11 @@ var MemoryLibSQL = class MemoryLibSQL extends MemoryStorage {
 	}
 	async swapBufferedReflectionToActive(input) {
 		try {
+			const check = this.#runFenceCheck(void 0, "swapBufferedReflectionToActive");
 			return await this.#write("swapBufferedReflectionToActive", async () => {
 				const tx = await this.#client.transaction("write");
 				try {
+					if (check) await assertRunFence(tx, check);
 					const current = await tx.execute({
 						sql: `SELECT * FROM "${OM_TABLE}" WHERE id = ?`,
 						args: [input.currentRecord.id]
@@ -14446,16 +14963,39 @@ var WorkflowDefinitionsLibSQL = class extends WorkflowDefinitionsStorage {
 };
 //#endregion
 //#region src/storage/domains/workflows/index.ts
+const RUN_OWNER_COLUMNS = `generation, ownerId, leaseExpiresAt, ${DB_NOW_MS} AS nowMs`;
+function toRunOwnershipRecord(runId, row) {
+	const leaseExpiresAt = row.leaseExpiresAt === null ? null : Number(row.leaseExpiresAt);
+	return {
+		runId,
+		generation: Number(row.generation),
+		ownerId: String(row.ownerId),
+		leaseExpiresAt: leaseExpiresAt === null ? null : new Date(leaseExpiresAt),
+		live: leaseExpiresAt !== null && leaseExpiresAt > Number(row.nowMs)
+	};
+}
 var WorkflowsLibSQL = class WorkflowsLibSQL extends WorkflowsStorage {
 	/**
 	* Workflow run snapshots accumulate as runs execute. Anchored on `updatedAt`
 	* (last activity) so suspended/long-running runs are not pruned by start age.
+	*
+	* Run ownership rows are anchored on `updatedAt` (epoch ms), which every
+	* claim, renewal and release refreshes, so a live execution's row is never
+	* older than its renew interval.
 	*/
-	static retentionTables = { workflowSnapshot: {
-		table: TABLE_WORKFLOW_SNAPSHOT,
-		column: "updatedAt",
-		indexed: true
-	} };
+	static retentionTables = {
+		workflowSnapshot: {
+			table: TABLE_WORKFLOW_SNAPSHOT,
+			column: "updatedAt",
+			indexed: true
+		},
+		runOwnership: {
+			table: TABLE_WORKFLOW_RUN_OWNERS,
+			column: "updatedAt",
+			indexed: true,
+			anchorType: "epoch-ms"
+		}
+	};
 	#db;
 	#client;
 	executeWithRetry;
@@ -14507,16 +15047,132 @@ var WorkflowsLibSQL = class WorkflowsLibSQL extends WorkflowsStorage {
 			schema,
 			ifNotExists: ["resourceId"]
 		});
+		await this.#db.createTable({
+			tableName: TABLE_WORKFLOW_RUN_OWNERS,
+			schema: RUN_FENCING_TABLE_SCHEMAS[TABLE_WORKFLOW_RUN_OWNERS]
+		});
 	}
 	async dangerouslyClearAll() {
 		await this.#db.deleteData({ tableName: TABLE_WORKFLOW_SNAPSHOT });
+		await this.#db.deleteData({ tableName: TABLE_WORKFLOW_RUN_OWNERS });
+	}
+	supportsRunFencing() {
+		return true;
+	}
+	#runFenceCheck(fence, runId, operation) {
+		const resolved = resolveRunFence(this, fence, runId);
+		return resolved && {
+			claimsTable: TABLE_WORKFLOW_RUN_OWNERS,
+			fence: resolved,
+			operation
+		};
 	}
-	/** Delete workflow snapshots older than the `workflowSnapshot` policy's `maxAge`, batched. */
+	async #readRunOwner(q, runId) {
+		const row = (await q.execute({
+			sql: `SELECT ${RUN_OWNER_COLUMNS} FROM ${TABLE_WORKFLOW_RUN_OWNERS} WHERE runId = ?`,
+			args: [runId]
+		})).rows[0];
+		return row ? toRunOwnershipRecord(runId, row) : null;
+	}
+	#ownershipError(operation, runId, error) {
+		return new MastraError({
+			id: createStorageErrorId("LIBSQL", operation, "FAILED"),
+			domain: ErrorDomain.STORAGE,
+			category: ErrorCategory.THIRD_PARTY,
+			details: { runId }
+		}, error);
+	}
+	async claimRunOwnership({ runId, ownerId, leaseMs, force, expectedGeneration }) {
+		try {
+			return await this.executeWithRetry(() => inWriteTransaction(this.#client, async (tx) => {
+				const current = await this.#readRunOwner(tx, runId);
+				const generation = current?.generation ?? 0;
+				if (expectedGeneration !== void 0 && expectedGeneration !== generation) return {
+					acquired: false,
+					record: current
+				};
+				if (current?.live && !force) return {
+					acquired: false,
+					record: current
+				};
+				await tx.execute({
+					sql: `INSERT INTO ${TABLE_WORKFLOW_RUN_OWNERS} (runId, generation, ownerId, leaseExpiresAt, updatedAt)
+                VALUES (?, COALESCE(?, MAX(1, ${DB_NOW_MS})), ?, ${DB_NOW_MS} + ?, ${DB_NOW_MS})
+                ON CONFLICT(runId) DO UPDATE SET
+                  generation = excluded.generation,
+                  ownerId = excluded.ownerId,
+                  leaseExpiresAt = excluded.leaseExpiresAt,
+                  updatedAt = excluded.updatedAt`,
+					args: [
+						runId,
+						current ? generation + 1 : null,
+						ownerId,
+						leaseMs
+					]
+				});
+				return {
+					acquired: true,
+					record: await this.#readRunOwner(tx, runId)
+				};
+			}), "claimRunOwnership");
+		} catch (error) {
+			throw this.#ownershipError("CLAIM_RUN_OWNERSHIP", runId, error);
+		}
+	}
+	async renewRunOwnership({ leaseMs, ...fence }) {
+		try {
+			return await this.executeWithRetry(() => inWriteTransaction(this.#client, async (tx) => {
+				const renewed = await tx.execute({
+					sql: `UPDATE ${TABLE_WORKFLOW_RUN_OWNERS} SET leaseExpiresAt = ${DB_NOW_MS} + ?, updatedAt = ${DB_NOW_MS}
+                WHERE runId = ? AND generation = ? AND ownerId = ? AND leaseExpiresAt IS NOT NULL`,
+					args: [
+						leaseMs,
+						fence.runId,
+						fence.generation,
+						fence.ownerId
+					]
+				});
+				const record = await this.#readRunOwner(tx, fence.runId);
+				return renewed.rowsAffected > 0 ? {
+					renewed: true,
+					record
+				} : {
+					renewed: false,
+					record
+				};
+			}), "renewRunOwnership");
+		} catch (error) {
+			throw this.#ownershipError("RENEW_RUN_OWNERSHIP", fence.runId, error);
+		}
+	}
+	async releaseRunOwnership(fence) {
+		try {
+			return (await this.executeWithRetry(() => withClientWriteLock(this.#client, () => this.#client.execute({
+				sql: `UPDATE ${TABLE_WORKFLOW_RUN_OWNERS} SET leaseExpiresAt = NULL, updatedAt = ${DB_NOW_MS}
+                WHERE runId = ? AND generation = ? AND ownerId = ?`,
+				args: [
+					fence.runId,
+					fence.generation,
+					fence.ownerId
+				]
+			})), "releaseRunOwnership")).rowsAffected > 0;
+		} catch (error) {
+			throw this.#ownershipError("RELEASE_RUN_OWNERSHIP", fence.runId, error);
+		}
+	}
+	async getRunOwnership({ runId }) {
+		try {
+			return await this.#readRunOwner(this.#client, runId);
+		} catch (error) {
+			throw this.#ownershipError("GET_RUN_OWNERSHIP", runId, error);
+		}
+	}
+	/** Delete workflow run snapshots and run ownership rows older than their policy's `maxAge`, batched. */
 	async prune(policies, options) {
 		const targets = resolveTargets({
 			policies,
 			descriptor: WorkflowsLibSQL.retentionTables,
-			order: ["workflowSnapshot"]
+			order: ["workflowSnapshot", "runOwnership"]
 		});
 		return runPrune({
 			db: this.#db,
@@ -14546,10 +15202,12 @@ var WorkflowsLibSQL = class WorkflowsLibSQL extends WorkflowsStorage {
 			this.logger.warn("LibSQL Workflows: Failed to set PRAGMA settings.", err);
 		}
 	}
-	async updateWorkflowResults({ workflowName, runId, stepId, result, requestContext, state }) {
+	async updateWorkflowResults({ workflowName, runId, stepId, result, requestContext, state, fence: explicitFence }) {
+		const check = this.#runFenceCheck(explicitFence, runId, "updateWorkflowResults");
 		return this.executeWithRetry(() => withClientWriteLock(this.#client, async () => {
 			const tx = await this.#client.transaction("write");
 			try {
+				if (check) await assertRunFence(tx, check);
 				const existingSnapshotResult = await tx.execute({
 					sql: `SELECT json(snapshot) as snapshot FROM ${TABLE_WORKFLOW_SNAPSHOT} WHERE workflow_name = ? AND run_id = ?`,
 					args: [workflowName, runId]
@@ -14602,10 +15260,12 @@ var WorkflowsLibSQL = class WorkflowsLibSQL extends WorkflowsStorage {
 			}
 		}), "updateWorkflowResults");
 	}
-	async updateWorkflowState({ workflowName, runId, opts }) {
+	async updateWorkflowState({ workflowName, runId, opts, fence: explicitFence }) {
+		const check = this.#runFenceCheck(explicitFence, runId, "updateWorkflowState");
 		return this.executeWithRetry(() => withClientWriteLock(this.#client, async () => {
 			const tx = await this.#client.transaction("write");
 			try {
+				if (check) await assertRunFence(tx, check);
 				const existingSnapshotResult = await tx.execute({
 					sql: `SELECT json(snapshot) as snapshot FROM ${TABLE_WORKFLOW_SNAPSHOT} WHERE workflow_name = ? AND run_id = ?`,
 					args: [workflowName, runId]
@@ -14646,7 +15306,7 @@ var WorkflowsLibSQL = class WorkflowsLibSQL extends WorkflowsStorage {
 			}
 		}), "updateWorkflowState");
 	}
-	async persistWorkflowSnapshot({ workflowName, runId, resourceId, snapshot, createdAt, updatedAt }) {
+	async persistWorkflowSnapshot({ workflowName, runId, resourceId, snapshot, createdAt, updatedAt, fence }) {
 		const now = /* @__PURE__ */ new Date();
 		const createdAtValue = (createdAt ?? now).toISOString();
 		const updatedAtValue = (updatedAt ?? now).toISOString();
@@ -14654,7 +15314,8 @@ var WorkflowsLibSQL = class WorkflowsLibSQL extends WorkflowsStorage {
 			workflowName,
 			runId
 		});
-		await this.executeWithRetry(() => withClientWriteLock(this.#client, () => this.#client.execute({
+		const check = this.#runFenceCheck(fence, runId, "persistWorkflowSnapshot");
+		await this.executeWithRetry(() => withRunFence(this.#client, check, (writer) => writer.execute({
 			sql: `INSERT INTO ${TABLE_WORKFLOW_SNAPSHOT} (workflow_name, run_id, resourceId, snapshot, createdAt, updatedAt)
                 VALUES (?, ?, ?, jsonb(?), ?, ?)
                 ON CONFLICT(workflow_name, run_id)
@@ -14710,14 +15371,16 @@ var WorkflowsLibSQL = class WorkflowsLibSQL extends WorkflowsStorage {
 			}, error);
 		}
 	}
-	async deleteWorkflowRunById({ runId, workflowName }) {
+	async deleteWorkflowRunById({ runId, workflowName, fence }) {
+		const check = this.#runFenceCheck(fence, runId, "deleteWorkflowRunById");
 		return this.executeWithRetry(async () => {
 			try {
-				await this.#client.execute({
+				await withRunFence(this.#client, check, (writer) => writer.execute({
 					sql: `DELETE FROM ${TABLE_WORKFLOW_SNAPSHOT} WHERE workflow_name = ? AND run_id = ?`,
 					args: [workflowName, runId]
-				});
+				}));
 			} catch (error) {
+				if (isRunFenceConflictError(error)) throw error;
 				throw new MastraError({
 					id: createStorageErrorId("LIBSQL", "DELETE_WORKFLOW_RUN_BY_ID", "FAILED"),
 					domain: ErrorDomain.STORAGE,
@@ -15587,7 +16250,7 @@ var LibSQLFactoryStorage = class extends FactoryStorage {
 			...config.authToken ? { authToken: config.authToken } : {},
 			...isLocalDb ? { timeout: DEFAULT_CONNECTION_TIMEOUT_MS } : {}
 		});
-		this.#client = isSingleConnectionDatabase(config) ? gateSingleConnectionClient(client) : client;
+		this.#client = isSingleConnectionDatabase(config) ? gateSingleConnectionClient(client) : isLocalDb ? gateIfLocalFile(resetConnectionsAfterBusy(client, { maxWaitMs: DEFAULT_CONNECTION_TIMEOUT_MS }), config.url, { maxWaitMs: DEFAULT_CONNECTION_TIMEOUT_MS }) : client;
 		this.ops = new LibSQLFactoryStorageOps(this.#client, this.#schemas, (fn) => withClientWriteLock(this.#client, fn));
 	}
 	getMastraStorage() {
@@ -15753,7 +16416,10 @@ var LibSQLStore = class extends MastraCompositeStore {
 				...config.syncInterval !== void 0 ? { syncInterval: config.syncInterval } : {},
 				...this.isLocalDb ? { timeout: this.connectionTimeoutMs } : {}
 			});
-			this.client = isSingleConnectionDatabase(config) ? gateSingleConnectionClient(client) : client;
+			this.client = isSingleConnectionDatabase(config) ? gateSingleConnectionClient(client) : this.isLocalDb ? gateIfLocalFile(resetConnectionsAfterBusy(client, {
+				afterReset: () => this.applyLocalPragmas(client),
+				maxWaitMs: this.connectionTimeoutMs
+			}), config.url, { maxWaitMs: this.connectionTimeoutMs }) : client;
 			this.pragmasReady = this.isLocalDb ? this.applyLocalPragmas() : Promise.resolve();
 		} else {
 			this.client = config.client;
@@ -15819,7 +16485,7 @@ var LibSQLStore = class extends MastraCompositeStore {
 			threadState
 		};
 	}
-	async applyLocalPragmas() {
+	async applyLocalPragmas(client = this.client) {
 		const pragmas = [
 			["journal_mode=WAL", "PRAGMA journal_mode=WAL;"],
 			[`busy_timeout=${this.connectionTimeoutMs}`, `PRAGMA busy_timeout=${this.connectionTimeoutMs};`],
@@ -15829,7 +16495,7 @@ var LibSQLStore = class extends MastraCompositeStore {
 			[`mmap_size=${this.localPragmas.mmapSize}`, `PRAGMA mmap_size=${this.localPragmas.mmapSize};`]
 		];
 		for (const [label, sql] of pragmas) try {
-			await this.client.execute(sql);
+			await client.execute(sql);
 			this.logger.debug(`LibSQLStore: PRAGMA ${label} set.`);
 		} catch (err) {
 			this.logger.warn(`LibSQLStore: Failed to set PRAGMA ${label}.`, err);