@mastra/libsql 1.25.2-alpha.1 → 1.26.0-alpha.3

package/dist/index.js

@@ -1,15 +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_ACTIVITY_SCHEMA, KNOWLEDGE_CURSORS_SCHEMA, KNOWLEDGE_MENTIONS_SCHEMA, KNOWLEDGE_NODES_SCHEMA, KNOWLEDGE_RECORDS_SCHEMA, 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_CURSORS, 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, assertKnowledgeCeilingRaised, assertKnowledgeScopeWithinCeiling, 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.
@@ -518,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");
@@ -1109,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;
 /**
@@ -1201,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,
@@ -1361,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
@@ -1498,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
 		})));
@@ -1512,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}`);
@@ -1786,7 +2200,7 @@ var LibSQLDB = class extends MastraBase {
 	* @param args.tableName - The name of the table to create
 	* @param args.schema - The schema definition for the table columns
 	*/
-	async createTable({ tableName, schema, compositePrimaryKey }) {
+	async createTable({ tableName, schema, compositePrimaryKey, executor = this.client }) {
 		try {
 			const parsedTableName = parseSqlIdentifier(tableName, "table name");
 			if (compositePrimaryKey) {
@@ -1804,7 +2218,7 @@ var LibSQLDB = class extends MastraBase {
 			if (tableName === TABLE_WORKFLOW_SNAPSHOT) tableConstraints.push("UNIQUE (workflow_name, run_id)");
 			if (tableName === TABLE_SPANS) tableConstraints.push("UNIQUE (spanId, traceId)");
 			const sql = `CREATE TABLE IF NOT EXISTS ${parsedTableName} (\n  ${[...columnDefinitions, ...tableConstraints].join(",\n  ")}\n)`;
-			await this.client.execute(sql);
+			await executor.execute(sql);
 			this.logger.debug(`LibSQLDB: Created table ${tableName}`);
 			if (tableName === TABLE_SPANS) await this.migrateSpansTable();
 		} catch (error) {
@@ -6047,20 +6461,678 @@ var HarnessLibSQL = class HarnessLibSQL extends HarnessStorage {
 	}
 };
 //#endregion
+//#region ../../packages/_internal-core/dist/knowledge-compat/index.js
+const KNOWLEDGE_V2_CORE_FEATURE = "knowledge-v2";
+/** Hard cap on scope nodes returned by one `listScopeNodes` read. */
+const MAX_KNOWLEDGE_SCOPE_NODES = 1e3;
+function knowledgeScopeNodeFilterKey(input) {
+	return JSON.stringify([
+		input.withinAddress ?? null,
+		input.addresses ? [...input.addresses].sort() : null,
+		input.ids ? [...input.ids].sort() : null
+	]);
+}
+function createKnowledgeScopeNodeCursor(scope, input) {
+	return encodeURIComponent(JSON.stringify({
+		version: 1,
+		type: "scope",
+		name: scope.name,
+		id: scope.id,
+		filter: knowledgeScopeNodeFilterKey(input)
+	}));
+}
+/** Validates the page size and cursor of a `listScopeNodes` query; throws on a cursor from a different query. */
+function parseListKnowledgeScopeNodesInput(input = {}) {
+	const requested = Number.isFinite(input.limit) ? Math.trunc(input.limit) : MAX_KNOWLEDGE_SCOPE_NODES;
+	const limit = Math.min(Math.max(requested, 1), MAX_KNOWLEDGE_SCOPE_NODES);
+	if (!input.cursor) return {
+		limit,
+		after: null
+	};
+	let value;
+	try {
+		value = JSON.parse(decodeURIComponent(input.cursor));
+	} catch {
+		throw new Error("Invalid Knowledge scope node cursor.");
+	}
+	const parsed = value && typeof value === "object" ? value : {};
+	if (parsed.version !== 1 || parsed.type !== "scope" || typeof parsed.name !== "string" || typeof parsed.id !== "string" || parsed.filter !== knowledgeScopeNodeFilterKey(input)) throw new Error("Knowledge scope node cursor does not match this query.");
+	return {
+		limit,
+		after: {
+			name: parsed.name,
+			id: parsed.id
+		}
+	};
+}
+/** Builds a page from up to `limit + 1` name/id-ordered scope nodes. */
+function pageKnowledgeScopeNodes(rows, limit, input) {
+	const scopes = rows.slice(0, limit);
+	const last = scopes.at(-1);
+	return {
+		scopes,
+		nextCursor: rows.length > limit && last ? createKnowledgeScopeNodeCursor(last, input) : null
+	};
+}
+/** Clamps a requested member limit to 1–{@link MAX_KNOWLEDGE_SCOPE_MEMBERS_LIMIT}. */
+function knowledgeScopeMembersLimit(limit) {
+	if (limit === void 0 || !Number.isFinite(limit)) return 500;
+	return Math.min(Math.max(Math.trunc(limit), 1), 500);
+}
+/** Validates the page size and cursor of a `listScopeMembers` query; throws on a cursor from another scope. */
+function parseListKnowledgeScopeMembersInput(input) {
+	const limit = knowledgeScopeMembersLimit(input.limit);
+	if (!input.cursor) return {
+		limit,
+		after: null
+	};
+	let value;
+	try {
+		value = JSON.parse(decodeURIComponent(input.cursor));
+	} catch {
+		throw new Error("Invalid Knowledge scope member cursor.");
+	}
+	const parsed = value && typeof value === "object" ? value : {};
+	const updatedAt = typeof parsed.updatedAt === "string" ? new Date(parsed.updatedAt) : /* @__PURE__ */ new Date(NaN);
+	if (parsed.version !== 1 || parsed.type !== "scope-member" || parsed.scopeNodeId !== input.scopeNodeId || typeof parsed.name !== "string" || typeof parsed.id !== "string" || Number.isNaN(updatedAt.getTime())) throw new Error("Knowledge scope member cursor does not match this query.");
+	return {
+		limit,
+		after: {
+			updatedAt,
+			name: parsed.name,
+			id: parsed.id
+		}
+	};
+}
+/** Builds a page from up to `limit + 1` members in `listScopeMembers` order. */
+function pageKnowledgeScopeMembers(rows, limit, input) {
+	const members = rows.slice(0, limit);
+	const last = members.at(-1);
+	const hasMore = rows.length > limit;
+	return {
+		members,
+		hasMore,
+		nextCursor: hasMore && last ? encodeURIComponent(JSON.stringify({
+			version: 1,
+			type: "scope-member",
+			scopeNodeId: input.scopeNodeId,
+			updatedAt: last.updatedAt.toISOString(),
+			name: last.name,
+			id: last.id
+		})) : null
+	};
+}
+const TABLE_KNOWLEDGE_NODES$1 = "mastra_knowledge_nodes";
+const TABLE_KNOWLEDGE_RECORDS$1 = "mastra_knowledge_records";
+const TABLE_KNOWLEDGE_MENTIONS$1 = "mastra_knowledge_mentions";
+const TABLE_KNOWLEDGE_ACTIVITY$1 = "mastra_knowledge_activity";
+const TABLE_KNOWLEDGE_SEMANTIC_OUTBOX$1 = "mastra_knowledge_semantic_outbox";
+const TABLE_KNOWLEDGE_NODE_SCOPES = "mastra_knowledge_node_scopes";
+const TABLE_KNOWLEDGE_RECORD_SCOPES = "mastra_knowledge_record_scopes";
+const TABLE_KNOWLEDGE_SCOPE_GRANTS = "mastra_knowledge_scope_grants";
+const TABLE_KNOWLEDGE_ACCESS_STATE = "mastra_knowledge_access_state";
+const TABLE_KNOWLEDGE_SCOPE_ADDRESSES = "mastra_knowledge_scope_addresses";
+const TABLE_KNOWLEDGE_NODE_ADDRESSES = "mastra_knowledge_node_addresses";
+const TABLE_KNOWLEDGE_IMPORT_STATE = "mastra_knowledge_import_state";
+const TABLE_KNOWLEDGE_IMPORT_RUNS = "mastra_knowledge_import_runs";
+const TABLE_KNOWLEDGE_PROPOSALS = "mastra_knowledge_proposals";
+const KNOWLEDGE_TABLE_NAMES = [
+	TABLE_KNOWLEDGE_NODES$1,
+	TABLE_KNOWLEDGE_RECORDS$1,
+	TABLE_KNOWLEDGE_MENTIONS$1,
+	TABLE_KNOWLEDGE_ACTIVITY$1,
+	TABLE_KNOWLEDGE_SEMANTIC_OUTBOX$1,
+	TABLE_KNOWLEDGE_NODE_SCOPES,
+	TABLE_KNOWLEDGE_RECORD_SCOPES,
+	TABLE_KNOWLEDGE_SCOPE_GRANTS,
+	TABLE_KNOWLEDGE_ACCESS_STATE,
+	TABLE_KNOWLEDGE_SCOPE_ADDRESSES,
+	TABLE_KNOWLEDGE_NODE_ADDRESSES,
+	TABLE_KNOWLEDGE_IMPORT_STATE,
+	TABLE_KNOWLEDGE_IMPORT_RUNS,
+	TABLE_KNOWLEDGE_PROPOSALS
+];
+/** Knowledge v1 tables with no v2 equivalent; an explicit schema reset drops them. */
+const RETIRED_KNOWLEDGE_TABLE_NAMES = ["mastra_knowledge_cursors"];
+/** Tables and indexes published v1 adapters created for every app, whether or not it used Knowledge. */
+const PUBLISHED_KNOWLEDGE_V1_TABLE_NAMES = /* @__PURE__ */ new Set([
+	TABLE_KNOWLEDGE_NODES$1,
+	TABLE_KNOWLEDGE_RECORDS$1,
+	TABLE_KNOWLEDGE_MENTIONS$1,
+	TABLE_KNOWLEDGE_ACTIVITY$1,
+	TABLE_KNOWLEDGE_SEMANTIC_OUTBOX$1,
+	...RETIRED_KNOWLEDGE_TABLE_NAMES
+]);
+const PUBLISHED_KNOWLEDGE_V1_INDEX_NAMES = /* @__PURE__ */ new Set([
+	"idx_knowledge_nodes_identity",
+	"idx_knowledge_nodes_scope",
+	"idx_knowledge_records_node_latest",
+	"idx_knowledge_records_thread_latest",
+	"idx_knowledge_mentions_record",
+	"idx_knowledge_activity_latest",
+	"idx_knowledge_outbox_idempotency",
+	"idx_knowledge_outbox_claim"
+]);
+const KNOWLEDGE_V2_NODES_SCHEMA = {
+	id: {
+		type: "text",
+		nullable: false,
+		primaryKey: true
+	},
+	name: {
+		type: "text",
+		nullable: false
+	},
+	kind: {
+		type: "text",
+		nullable: true
+	},
+	isScope: {
+		type: "boolean",
+		nullable: false
+	},
+	metadata: {
+		type: "jsonb",
+		nullable: true
+	},
+	version: {
+		type: "integer",
+		nullable: false
+	},
+	createdAt: {
+		type: "timestamp",
+		nullable: false
+	},
+	updatedAt: {
+		type: "timestamp",
+		nullable: false
+	},
+	deletedAt: {
+		type: "timestamp",
+		nullable: true
+	},
+	deletedBy: {
+		type: "text",
+		nullable: true
+	},
+	type: {
+		type: "text",
+		nullable: true
+	},
+	canonicalName: {
+		type: "text",
+		nullable: true
+	},
+	content: {
+		type: "text",
+		nullable: true
+	},
+	description: {
+		type: "text",
+		nullable: true
+	},
+	scope: {
+		type: "jsonb",
+		nullable: true
+	},
+	scopeKey: {
+		type: "text",
+		nullable: true
+	},
+	mergedInto: {
+		type: "text",
+		nullable: true
+	}
+};
+const KNOWLEDGE_V2_RECORDS_SCHEMA = {
+	id: {
+		type: "text",
+		nullable: false,
+		primaryKey: true
+	},
+	node: {
+		type: "text",
+		nullable: false,
+		references: {
+			table: TABLE_KNOWLEDGE_NODES$1,
+			column: "id"
+		}
+	},
+	text: {
+		type: "text",
+		nullable: false
+	},
+	metadata: {
+		type: "jsonb",
+		nullable: true
+	},
+	version: {
+		type: "integer",
+		nullable: false
+	},
+	capturedAt: {
+		type: "timestamp",
+		nullable: false
+	},
+	updatedAt: {
+		type: "timestamp",
+		nullable: false
+	},
+	deletedAt: {
+		type: "timestamp",
+		nullable: true
+	},
+	deletedBy: {
+		type: "text",
+		nullable: true
+	},
+	scope: {
+		type: "jsonb",
+		nullable: true
+	},
+	scopeKey: {
+		type: "text",
+		nullable: true
+	},
+	sourceThreadId: {
+		type: "text",
+		nullable: true
+	},
+	when: {
+		type: "timestamp",
+		nullable: true
+	}
+};
+const KNOWLEDGE_V2_MENTIONS_SCHEMA = {
+	recordId: {
+		type: "text",
+		nullable: false,
+		references: {
+			table: TABLE_KNOWLEDGE_RECORDS$1,
+			column: "id"
+		}
+	},
+	targetNodeId: {
+		type: "text",
+		nullable: true,
+		references: {
+			table: TABLE_KNOWLEDGE_NODES$1,
+			column: "id"
+		}
+	},
+	sourceType: {
+		type: "text",
+		nullable: true
+	},
+	sourceId: {
+		type: "text",
+		nullable: true
+	}
+};
+const KNOWLEDGE_NODE_SCOPES_SCHEMA = {
+	nodeId: {
+		type: "text",
+		nullable: false,
+		references: {
+			table: TABLE_KNOWLEDGE_NODES$1,
+			column: "id"
+		}
+	},
+	scopeNodeId: {
+		type: "text",
+		nullable: false,
+		references: {
+			table: TABLE_KNOWLEDGE_NODES$1,
+			column: "id"
+		}
+	},
+	addedAt: {
+		type: "timestamp",
+		nullable: false
+	}
+};
+const KNOWLEDGE_RECORD_SCOPES_SCHEMA = {
+	recordId: {
+		type: "text",
+		nullable: false,
+		references: {
+			table: TABLE_KNOWLEDGE_RECORDS$1,
+			column: "id"
+		}
+	},
+	scopeNodeId: {
+		type: "text",
+		nullable: false,
+		references: {
+			table: TABLE_KNOWLEDGE_NODES$1,
+			column: "id"
+		}
+	},
+	addedAt: {
+		type: "timestamp",
+		nullable: false
+	}
+};
+const KNOWLEDGE_SCOPE_GRANTS_SCHEMA = {
+	scopeNodeId: {
+		type: "text",
+		nullable: false,
+		references: {
+			table: TABLE_KNOWLEDGE_NODES$1,
+			column: "id"
+		}
+	},
+	scopeRefId: {
+		type: "text",
+		nullable: false,
+		references: {
+			table: TABLE_KNOWLEDGE_NODES$1,
+			column: "id"
+		}
+	},
+	role: {
+		type: "text",
+		nullable: false
+	},
+	canSuggest: {
+		type: "boolean",
+		nullable: true
+	}
+};
+const KNOWLEDGE_ACCESS_STATE_SCHEMA = {
+	id: {
+		type: "text",
+		nullable: false,
+		primaryKey: true
+	},
+	epoch: {
+		type: "integer",
+		nullable: false
+	},
+	schemaVersion: {
+		type: "integer",
+		nullable: false
+	}
+};
+const KNOWLEDGE_SCOPE_ADDRESSES_SCHEMA = {
+	address: {
+		type: "text",
+		nullable: false,
+		primaryKey: true
+	},
+	scopeNodeId: {
+		type: "text",
+		nullable: false,
+		references: {
+			table: TABLE_KNOWLEDGE_NODES$1,
+			column: "id"
+		}
+	}
+};
+const KNOWLEDGE_NODE_ADDRESSES_SCHEMA = {
+	source: {
+		type: "text",
+		nullable: false
+	},
+	address: {
+		type: "text",
+		nullable: false
+	},
+	nodeId: {
+		type: "text",
+		nullable: false,
+		references: {
+			table: TABLE_KNOWLEDGE_NODES$1,
+			column: "id"
+		}
+	}
+};
+const KNOWLEDGE_IMPORT_STATE_SCHEMA = {
+	importerId: {
+		type: "text",
+		nullable: false
+	},
+	binding: {
+		type: "text",
+		nullable: false
+	},
+	key: {
+		type: "text",
+		nullable: false
+	},
+	value: {
+		type: "text",
+		nullable: false
+	}
+};
+const KNOWLEDGE_IMPORT_RUNS_SCHEMA = {
+	id: {
+		type: "text",
+		nullable: false,
+		primaryKey: true
+	},
+	importerId: {
+		type: "text",
+		nullable: false
+	},
+	binding: {
+		type: "text",
+		nullable: false
+	},
+	importKind: {
+		type: "text",
+		nullable: false
+	},
+	triggerKind: {
+		type: "text",
+		nullable: false
+	},
+	status: {
+		type: "text",
+		nullable: false
+	},
+	error: {
+		type: "text",
+		nullable: true
+	},
+	transcriptThreadId: {
+		type: "text",
+		nullable: true
+	},
+	traceId: {
+		type: "text",
+		nullable: true
+	},
+	queuedAt: {
+		type: "timestamp",
+		nullable: false
+	},
+	startedAt: {
+		type: "timestamp",
+		nullable: true
+	},
+	completedAt: {
+		type: "timestamp",
+		nullable: true
+	}
+};
+const KNOWLEDGE_V2_ACTIVITY_SCHEMA = {
+	id: {
+		type: "text",
+		nullable: false,
+		primaryKey: true
+	},
+	action: {
+		type: "text",
+		nullable: false
+	},
+	targetType: {
+		type: "text",
+		nullable: true
+	},
+	targetId: {
+		type: "text",
+		nullable: true
+	},
+	contextScopeId: {
+		type: "text",
+		nullable: true,
+		references: {
+			table: TABLE_KNOWLEDGE_NODES$1,
+			column: "id"
+		}
+	},
+	importRunId: {
+		type: "text",
+		nullable: true,
+		references: {
+			table: TABLE_KNOWLEDGE_IMPORT_RUNS,
+			column: "id"
+		}
+	},
+	details: {
+		type: "jsonb",
+		nullable: true
+	},
+	createdAt: {
+		type: "timestamp",
+		nullable: false
+	},
+	recordType: {
+		type: "text",
+		nullable: true
+	},
+	recordId: {
+		type: "text",
+		nullable: true
+	},
+	scope: {
+		type: "jsonb",
+		nullable: true
+	},
+	scopeKey: {
+		type: "text",
+		nullable: true
+	},
+	sourceThreadId: {
+		type: "text",
+		nullable: true
+	}
+};
+const KNOWLEDGE_PROPOSALS_SCHEMA = {
+	id: {
+		type: "text",
+		nullable: false,
+		primaryKey: true
+	},
+	targetType: {
+		type: "text",
+		nullable: false
+	},
+	targetId: {
+		type: "text",
+		nullable: false
+	},
+	action: {
+		type: "text",
+		nullable: false
+	},
+	changes: {
+		type: "jsonb",
+		nullable: false
+	},
+	reason: {
+		type: "text",
+		nullable: true
+	},
+	proposerContextScopeId: {
+		type: "text",
+		nullable: false
+	},
+	expectedVersion: {
+		type: "integer",
+		nullable: false
+	},
+	status: {
+		type: "text",
+		nullable: false
+	},
+	reviewerContextScopeId: {
+		type: "text",
+		nullable: true
+	},
+	reviewedAt: {
+		type: "timestamp",
+		nullable: true
+	},
+	createdAt: {
+		type: "timestamp",
+		nullable: false
+	}
+};
+function assertKnowledgeV2CoreSupport(features) {
+	if (!features.has("knowledge-v2")) throw new Error(`Knowledge v2 requires a @mastra/core release with the "${KNOWLEDGE_V2_CORE_FEATURE}" feature. Upgrade @mastra/core to use Knowledge; other storage domains keep working on this version.`);
+}
+function resolveKnowledgeV2Core(storageModule) {
+	if (typeof storageModule !== "object" || storageModule === null) throw new Error("@mastra/core advertises Knowledge v2 without the required storage API");
+	const { assertKnowledgeDescriptionWithinBound: assertDescription, assertKnowledgeRecordTextWithinBound: assertRecordText, assertKnowledgeSchemaCompatible: assertCompatible, inspectKnowledgeSchema: inspectSchema } = storageModule;
+	if (typeof assertDescription !== "function" || typeof assertRecordText !== "function" || typeof assertCompatible !== "function" || typeof inspectSchema !== "function") throw new Error("@mastra/core advertises Knowledge v2 without the required storage API");
+	return {
+		assertKnowledgeDescriptionWithinBound: (description) => assertDescription(description),
+		assertKnowledgeRecordTextWithinBound: (text) => assertRecordText(text),
+		assertKnowledgeSchemaCompatible: (inspection) => assertCompatible(inspection),
+		inspectKnowledgeSchema: (snapshot) => inspectSchema(snapshot)
+	};
+}
+function createKnowledgeV2CoreLoader(features, loadStorageModule) {
+	let knowledgeV2Core;
+	return async () => {
+		assertKnowledgeV2CoreSupport(features);
+		knowledgeV2Core ??= loadStorageModule().then(resolveKnowledgeV2Core).catch((error) => {
+			knowledgeV2Core = void 0;
+			throw error;
+		});
+		return knowledgeV2Core;
+	};
+}
+//#endregion
 //#region src/storage/domains/knowledge/index.ts
-let assertDescriptionWithinBound;
+const loadKnowledgeV2Core = createKnowledgeV2CoreLoader(coreFeatures, () => import("@mastra/core/storage"));
 async function assertKnowledgeDescriptionWithinBoundCompat(description) {
-	let assertWithinBound = assertDescriptionWithinBound;
-	if (!assertWithinBound) {
-		const resolvedAssert = (await import("@mastra/core/storage")).assertKnowledgeDescriptionWithinBound ?? ((value) => {
-			if (value !== void 0 && value.length > 400) throw new Error("Knowledge node description exceeds the 400 UTF-16 code unit limit");
-		});
-		assertDescriptionWithinBound = resolvedAssert;
-		assertWithinBound = resolvedAssert;
-	}
-	assertWithinBound(description);
+	const { assertKnowledgeDescriptionWithinBound } = await loadKnowledgeV2Core();
+	assertKnowledgeDescriptionWithinBound(description);
+}
+async function assertKnowledgeRecordTextWithinBoundCompat(text) {
+	const { assertKnowledgeRecordTextWithinBound } = await loadKnowledgeV2Core();
+	assertKnowledgeRecordTextWithinBound(text);
+}
+const reconcileChains = /* @__PURE__ */ new Map();
+const unidentifiedClientReconcileKey = {};
+function withReconcileLock(key, operation) {
+	const lockKey = typeof key === "string" ? key : unidentifiedClientReconcileKey;
+	const result = (reconcileChains.get(lockKey) ?? Promise.resolve()).then(operation, operation);
+	const tail = result.then(() => void 0, () => void 0);
+	reconcileChains.set(lockKey, tail);
+	tail.finally(() => {
+		if (reconcileChains.get(lockKey) === tail) reconcileChains.delete(lockKey);
+	});
+	return result;
 }
-const visibleSql = `(scopeKey = ? OR substr(?, 1, length(scopeKey) + 1) = scopeKey || char(31))`;
+/**
+* Scope keys visible to a caller holding `scope`: a row is visible when its scope is a subset of the
+* caller's (companion entries such as `resource:x:uncurated` make this more than a prefix match).
+* Matching rows by `scopeKey` keeps visibility filters on an index; a caller scope has only a few
+* entries, so the list stays small.
+*/
+function visibleScopeKeys(scope) {
+	const canonical = canonicalizeKnowledgeScope(scope);
+	const keys = /* @__PURE__ */ new Set();
+	for (let mask = 1; mask < 1 << canonical.length; mask++) try {
+		keys.add(knowledgeScopeKey(canonical.filter((_, index) => mask & 1 << index)));
+	} catch {}
+	return [...keys];
+}
+const visibleSql = (keys, scopeKeyColumn = "scopeKey") => `${scopeKeyColumn} IN (${keys.map(() => "?").join(",")})`;
 function parseJson$3(value) {
 	if (typeof value === "string") return JSON.parse(value);
 	if (value instanceof Uint8Array) return JSON.parse(new TextDecoder().decode(value));
@@ -6090,6 +7162,7 @@ function parseNode(row) {
 		kind: row.kind == null ? "" : String(row.kind),
 		content: row.content == null ? void 0 : String(row.content),
 		description: row.description == null ? void 0 : String(row.description),
+		isScope: row.isScope === true || row.isScope === 1 ? true : void 0,
 		scope: parseJson$3(row.scopeJson ?? row.scope),
 		version: Number(row.version),
 		mergedInto: row.mergedInto == null ? void 0 : String(row.mergedInto),
@@ -6106,7 +7179,6 @@ function parseKnowledge(row) {
 		sourceThreadId: String(row.sourceThreadId),
 		capturedAt: toDate(row.capturedAt),
 		when: optionalDate(row.when),
-		maxScope: row.maxScope == null ? void 0 : String(row.maxScope),
 		metadata: (row.metadataJson ?? row.metadata) == null ? void 0 : parseJson$3(row.metadataJson ?? row.metadata),
 		deletedAt: optionalDate(row.deletedAt),
 		deletedBy: row.deletedBy == null ? void 0 : String(row.deletedBy)
@@ -6129,100 +7201,458 @@ function parseOutbox(row) {
 		completedAt: optionalDate(row.completedAt)
 	};
 }
+const KNOWLEDGE_CURATION_CURSOR_REMOVED_MESSAGE = "Knowledge curation cursors were removed: observation-time curate is the only Knowledge writer and needs no cursor.";
+const knowledgeV2TableSchemas = /* @__PURE__ */ new Map([
+	[TABLE_KNOWLEDGE_NODES, KNOWLEDGE_V2_NODES_SCHEMA],
+	[TABLE_KNOWLEDGE_RECORDS, KNOWLEDGE_V2_RECORDS_SCHEMA],
+	[TABLE_KNOWLEDGE_MENTIONS, KNOWLEDGE_V2_MENTIONS_SCHEMA],
+	[TABLE_KNOWLEDGE_ACTIVITY, KNOWLEDGE_V2_ACTIVITY_SCHEMA],
+	[TABLE_KNOWLEDGE_SEMANTIC_OUTBOX, KNOWLEDGE_SEMANTIC_OUTBOX_SCHEMA],
+	[TABLE_KNOWLEDGE_NODE_SCOPES, KNOWLEDGE_NODE_SCOPES_SCHEMA],
+	[TABLE_KNOWLEDGE_RECORD_SCOPES, KNOWLEDGE_RECORD_SCOPES_SCHEMA],
+	[TABLE_KNOWLEDGE_SCOPE_GRANTS, KNOWLEDGE_SCOPE_GRANTS_SCHEMA],
+	[TABLE_KNOWLEDGE_ACCESS_STATE, KNOWLEDGE_ACCESS_STATE_SCHEMA],
+	[TABLE_KNOWLEDGE_SCOPE_ADDRESSES, KNOWLEDGE_SCOPE_ADDRESSES_SCHEMA],
+	[TABLE_KNOWLEDGE_NODE_ADDRESSES, KNOWLEDGE_NODE_ADDRESSES_SCHEMA],
+	[TABLE_KNOWLEDGE_IMPORT_STATE, KNOWLEDGE_IMPORT_STATE_SCHEMA],
+	[TABLE_KNOWLEDGE_IMPORT_RUNS, KNOWLEDGE_IMPORT_RUNS_SCHEMA],
+	[TABLE_KNOWLEDGE_PROPOSALS, KNOWLEDGE_PROPOSALS_SCHEMA]
+]);
+function canonicalizeLibSQLUrl(url) {
+	if (url.includes(":memory:")) return /[?&]cache=shared(?:&|$)/.test(url) ? "file::memory:?cache=shared" : void 0;
+	if (url.startsWith("file:")) {
+		const [path] = url.slice(5).split("?");
+		if (url.startsWith("file://")) {
+			const parsed = new URL(url);
+			const host = parsed.hostname.toLocaleLowerCase();
+			const filePath = host && host !== "localhost" ? `//${host}${parsed.pathname}` : parsed.pathname;
+			return `file:${resolve(decodeURIComponent(filePath))}`;
+		}
+		return `file:${resolve(decodeURIComponent(path))}`;
+	}
+	try {
+		const parsed = new URL(url);
+		const port = parsed.port || (parsed.protocol === "libsql:" || parsed.protocol === "https:" ? "443" : "80");
+		return `${parsed.protocol}//${parsed.hostname.toLocaleLowerCase()}:${port}${parsed.pathname}`;
+	} catch {
+		return url;
+	}
+}
+const unidentifiedClientIsolationKey = {};
+function getLibSQLKnowledgeIsolationKey(config, client) {
+	if (config.storageIsolationKey !== void 0) return config.storageIsolationKey;
+	if (!config.url) return unidentifiedClientIsolationKey;
+	const urlKey = canonicalizeLibSQLUrl(config.url);
+	return urlKey ? `libsql:${urlKey}` : client ?? config.client ?? config;
+}
 var KnowledgeLibSQL = class extends KnowledgeStorage {
 	#client;
 	#db;
 	constructor(config) {
-		super();
-		this.#client = resolveClient(config);
+		const client = resolveClient(config);
+		const storageIsolationKey = config.storageIsolationKey ?? getLibSQLKnowledgeIsolationKey(config, client);
+		super({ storageIsolationKey });
+		this.#client = client;
 		this.#db = new LibSQLDB({
 			client: this.#client,
 			maxRetries: config.maxRetries,
 			initialBackoffMs: config.initialBackoffMs
 		});
 	}
+	getCapabilities() {
+		return {
+			contractVersion: 2,
+			schemaVersion: 2,
+			supportsV2: true,
+			supportsSchemaInspection: true,
+			supportsExplicitReset: true
+		};
+	}
+	async inspectSchema() {
+		return this.#inspectSchema(this.#client);
+	}
+	async #inspectSchema(executor) {
+		const { inspectKnowledgeSchema } = await loadKnowledgeV2Core();
+		try {
+			const placeholders = KNOWLEDGE_TABLE_NAMES.map(() => "?").join(",");
+			const tableNames = (await executor.execute({
+				sql: `SELECT name FROM sqlite_master WHERE type = 'table' AND name IN (${placeholders})`,
+				args: [...KNOWLEDGE_TABLE_NAMES]
+			})).rows.map((row) => String(row.name));
+			if (tableNames.length === 0) return inspectKnowledgeSchema({
+				available: true,
+				tableNames
+			});
+			const missingTables = KNOWLEDGE_TABLE_NAMES.filter((table) => !tableNames.includes(table));
+			if (missingTables.length > 0) return inspectKnowledgeSchema({
+				available: true,
+				tableNames,
+				reason: `Missing Knowledge v2 tables: ${missingTables.join(", ")}`
+			});
+			for (const [table, schema] of knowledgeV2TableSchemas) {
+				const columns = await executor.execute(`PRAGMA table_info("${table}")`);
+				const actual = new Set(columns.rows.map((row) => String(row.name)));
+				const missing = Object.keys(schema).filter((column) => !actual.has(column));
+				if (missing.length > 0) return inspectKnowledgeSchema({
+					available: true,
+					tableNames,
+					reason: `Knowledge table ${table} is missing v2 columns: ${missing.join(", ")}`
+				});
+			}
+			const accessState = await executor.execute(`SELECT schemaVersion FROM "${TABLE_KNOWLEDGE_ACCESS_STATE}" WHERE id='global'`);
+			if (Number(accessState.rows[0]?.schemaVersion) !== 2) return inspectKnowledgeSchema({
+				available: true,
+				tableNames,
+				reason: "Knowledge schema version marker is missing or incompatible"
+			});
+			return inspectKnowledgeSchema({
+				available: true,
+				tableNames,
+				schemaVersion: 2
+			});
+		} catch (error) {
+			return inspectKnowledgeSchema({
+				available: false,
+				tableNames: [],
+				reason: error instanceof Error ? error.message : String(error)
+			});
+		}
+	}
 	async init() {
-		await this.#db.createTable({
-			tableName: TABLE_KNOWLEDGE_NODES,
-			schema: KNOWLEDGE_NODES_SCHEMA
+		await this.#transaction((tx) => this.#initializeSchema(tx));
+	}
+	async #initializeSchema(tx) {
+		const { assertKnowledgeSchemaCompatible } = await loadKnowledgeV2Core();
+		let inspection = await this.#inspectSchema(tx);
+		if (inspection.status === "incompatible-reset-required" && await this.#isPublishedV1Layout(tx)) {
+			for (const table of [...RETIRED_KNOWLEDGE_TABLE_NAMES, ...[...KNOWLEDGE_TABLE_NAMES].reverse()]) await tx.execute(`DROP TABLE IF EXISTS "${table}"`);
+			inspection = await this.#inspectSchema(tx);
+		}
+		assertKnowledgeSchemaCompatible(inspection);
+		const createTable = (input) => this.#db.createTable({
+			...input,
+			executor: tx
 		});
-		await this.#db.alterTable({
+		await createTable({
 			tableName: TABLE_KNOWLEDGE_NODES,
-			schema: KNOWLEDGE_NODES_SCHEMA,
-			ifNotExists: ["description"]
+			schema: KNOWLEDGE_V2_NODES_SCHEMA
 		});
-		await this.#db.createTable({
+		await createTable({
 			tableName: TABLE_KNOWLEDGE_RECORDS,
-			schema: KNOWLEDGE_RECORDS_SCHEMA
+			schema: KNOWLEDGE_V2_RECORDS_SCHEMA
 		});
-		await this.#db.createTable({
+		await createTable({
 			tableName: TABLE_KNOWLEDGE_MENTIONS,
-			schema: KNOWLEDGE_MENTIONS_SCHEMA,
+			schema: KNOWLEDGE_V2_MENTIONS_SCHEMA,
+			compositePrimaryKey: ["recordId", "sourceId"]
+		});
+		await createTable({
+			tableName: TABLE_KNOWLEDGE_NODE_SCOPES,
+			schema: KNOWLEDGE_NODE_SCOPES_SCHEMA,
+			compositePrimaryKey: ["nodeId", "scopeNodeId"]
+		});
+		await createTable({
+			tableName: TABLE_KNOWLEDGE_RECORD_SCOPES,
+			schema: KNOWLEDGE_RECORD_SCOPES_SCHEMA,
+			compositePrimaryKey: ["recordId", "scopeNodeId"]
+		});
+		await createTable({
+			tableName: TABLE_KNOWLEDGE_SCOPE_GRANTS,
+			schema: KNOWLEDGE_SCOPE_GRANTS_SCHEMA,
+			compositePrimaryKey: ["scopeNodeId", "scopeRefId"]
+		});
+		await createTable({
+			tableName: TABLE_KNOWLEDGE_ACCESS_STATE,
+			schema: KNOWLEDGE_ACCESS_STATE_SCHEMA
+		});
+		await createTable({
+			tableName: TABLE_KNOWLEDGE_SCOPE_ADDRESSES,
+			schema: KNOWLEDGE_SCOPE_ADDRESSES_SCHEMA
+		});
+		await createTable({
+			tableName: TABLE_KNOWLEDGE_NODE_ADDRESSES,
+			schema: KNOWLEDGE_NODE_ADDRESSES_SCHEMA,
+			compositePrimaryKey: ["source", "address"]
+		});
+		await createTable({
+			tableName: TABLE_KNOWLEDGE_IMPORT_STATE,
+			schema: KNOWLEDGE_IMPORT_STATE_SCHEMA,
 			compositePrimaryKey: [
-				"sourceType",
-				"sourceId",
-				"recordId"
+				"importerId",
+				"binding",
+				"key"
 			]
 		});
-		await this.#db.createTable({
-			tableName: TABLE_KNOWLEDGE_CURSORS,
-			schema: KNOWLEDGE_CURSORS_SCHEMA,
-			compositePrimaryKey: ["sourceThreadId", "agent"]
+		await createTable({
+			tableName: TABLE_KNOWLEDGE_IMPORT_RUNS,
+			schema: KNOWLEDGE_IMPORT_RUNS_SCHEMA
 		});
-		await this.#db.createTable({
-			tableName: TABLE_KNOWLEDGE_ACTIVITY,
-			schema: KNOWLEDGE_ACTIVITY_SCHEMA
+		await createTable({
+			tableName: TABLE_KNOWLEDGE_PROPOSALS,
+			schema: KNOWLEDGE_PROPOSALS_SCHEMA
 		});
-		await this.#db.createTable({
-			tableName: TABLE_KNOWLEDGE_SEMANTIC_OUTBOX,
-			schema: KNOWLEDGE_SEMANTIC_OUTBOX_SCHEMA
+		await createTable({
+			tableName: TABLE_KNOWLEDGE_ACTIVITY,
+			schema: KNOWLEDGE_V2_ACTIVITY_SCHEMA
 		});
-		await this.#client.batch([
-			{
-				sql: `CREATE UNIQUE INDEX IF NOT EXISTS idx_knowledge_nodes_identity ON "${TABLE_KNOWLEDGE_NODES}" (type, scopeKey, canonicalName)`,
-				args: []
-			},
-			{
-				sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_nodes_scope ON "${TABLE_KNOWLEDGE_NODES}" (scopeKey, type)`,
-				args: []
-			},
-			{
-				sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_records_node_latest ON "${TABLE_KNOWLEDGE_RECORDS}" (node, id DESC)`,
-				args: []
-			},
-			{
-				sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_records_thread_latest ON "${TABLE_KNOWLEDGE_RECORDS}" (sourceThreadId, id DESC)`,
-				args: []
-			},
-			{
-				sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_mentions_record ON "${TABLE_KNOWLEDGE_MENTIONS}" (recordId, sourceType, sourceId)`,
-				args: []
-			},
-			{
-				sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_activity_latest ON "${TABLE_KNOWLEDGE_ACTIVITY}" (id DESC)`,
-				args: []
-			},
-			{
-				sql: `CREATE UNIQUE INDEX IF NOT EXISTS idx_knowledge_outbox_idempotency ON "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" (idempotencyKey)`,
-				args: []
-			},
-			{
-				sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_outbox_claim ON "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" (status, availableAt, createdAt)`,
-				args: []
-			}
-		], "write");
+		await createTable({
+			tableName: TABLE_KNOWLEDGE_SEMANTIC_OUTBOX,
+			schema: KNOWLEDGE_SEMANTIC_OUTBOX_SCHEMA
+		});
+		for (const statement of [
+			`CREATE UNIQUE INDEX IF NOT EXISTS idx_knowledge_nodes_identity ON "${TABLE_KNOWLEDGE_NODES}" (type, scopeKey, canonicalName)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_nodes_scope ON "${TABLE_KNOWLEDGE_NODES}" (scopeKey, type)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_nodes_name ON "${TABLE_KNOWLEDGE_NODES}" (type, canonicalName)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_records_node_latest ON "${TABLE_KNOWLEDGE_RECORDS}" (node, id DESC)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_records_thread_latest ON "${TABLE_KNOWLEDGE_RECORDS}" (sourceThreadId, id DESC)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_mentions_record ON "${TABLE_KNOWLEDGE_MENTIONS}" (recordId, sourceType, sourceId)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_activity_latest ON "${TABLE_KNOWLEDGE_ACTIVITY}" (id DESC)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_records_scope ON "${TABLE_KNOWLEDGE_RECORDS}" (scopeKey, id)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_activity_scope ON "${TABLE_KNOWLEDGE_ACTIVITY}" (scopeKey, id DESC)`,
+			`CREATE UNIQUE INDEX IF NOT EXISTS idx_knowledge_outbox_idempotency ON "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" (idempotencyKey)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_outbox_claim ON "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" (status, availableAt, createdAt)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_node_scopes_scope ON "${TABLE_KNOWLEDGE_NODE_SCOPES}" (scopeNodeId, nodeId)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_record_scopes_scope ON "${TABLE_KNOWLEDGE_RECORD_SCOPES}" (scopeNodeId, recordId)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_scope_grants_ref ON "${TABLE_KNOWLEDGE_SCOPE_GRANTS}" (scopeRefId, scopeNodeId)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_node_addresses_node ON "${TABLE_KNOWLEDGE_NODE_ADDRESSES}" (nodeId)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_import_runs_lookup ON "${TABLE_KNOWLEDGE_IMPORT_RUNS}" (importerId, binding, queuedAt DESC)`,
+			`CREATE INDEX IF NOT EXISTS idx_knowledge_activity_import_run ON "${TABLE_KNOWLEDGE_ACTIVITY}" (importRunId, id DESC)`
+		]) await tx.execute(statement);
+		await tx.execute({
+			sql: `INSERT OR IGNORE INTO "${TABLE_KNOWLEDGE_ACCESS_STATE}" (id, epoch, schemaVersion) VALUES ('global', 0, ?)`,
+			args: [2]
+		});
+	}
+	/**
+	* True when the only Knowledge objects are the tables and indexes published v1 adapters created,
+	* with or without rows. Anything else (v2 tables, unknown tables, views, triggers) needs an
+	* explicit reset.
+	*/
+	async #isPublishedV1Layout(executor) {
+		const objects = await executor.execute("SELECT type, name FROM sqlite_master WHERE name LIKE 'mastra\\_knowledge\\_%' ESCAPE '\\' OR tbl_name LIKE 'mastra\\_knowledge\\_%' ESCAPE '\\' OR sql LIKE '%mastra\\_knowledge\\_%' ESCAPE '\\'");
+		for (const row of objects.rows) {
+			const type = String(row.type);
+			const name = String(row.name);
+			if (type === "table" && PUBLISHED_KNOWLEDGE_V1_TABLE_NAMES.has(name)) continue;
+			const knownIndex = PUBLISHED_KNOWLEDGE_V1_INDEX_NAMES.has(name) || name.startsWith("sqlite_autoindex_");
+			if (type !== "index" || !knownIndex) return false;
+		}
+		return true;
 	}
 	async dangerouslyClearAll() {
 		await this.#transaction(async (tx) => {
 			for (const table of [
+				TABLE_KNOWLEDGE_RECORD_SCOPES,
+				TABLE_KNOWLEDGE_NODE_SCOPES,
+				TABLE_KNOWLEDGE_SCOPE_GRANTS,
+				TABLE_KNOWLEDGE_SCOPE_ADDRESSES,
+				TABLE_KNOWLEDGE_NODE_ADDRESSES,
 				TABLE_KNOWLEDGE_MENTIONS,
-				TABLE_KNOWLEDGE_RECORDS,
-				TABLE_KNOWLEDGE_NODES,
-				TABLE_KNOWLEDGE_CURSORS,
+				TABLE_KNOWLEDGE_PROPOSALS,
 				TABLE_KNOWLEDGE_ACTIVITY,
-				TABLE_KNOWLEDGE_SEMANTIC_OUTBOX
+				TABLE_KNOWLEDGE_IMPORT_STATE,
+				TABLE_KNOWLEDGE_IMPORT_RUNS,
+				TABLE_KNOWLEDGE_SEMANTIC_OUTBOX,
+				TABLE_KNOWLEDGE_RECORDS,
+				TABLE_KNOWLEDGE_NODES
 			]) await tx.execute(`DELETE FROM "${table}"`);
+			await tx.execute(`UPDATE "${TABLE_KNOWLEDGE_ACCESS_STATE}" SET epoch = 0 WHERE id = 'global'`);
+		});
+	}
+	async dangerouslyReset() {
+		await withClientWriteLock(this.#client, async () => {
+			await this.#client.batch([...RETIRED_KNOWLEDGE_TABLE_NAMES, ...[...KNOWLEDGE_TABLE_NAMES].reverse()].map((table) => ({
+				sql: `DROP TABLE IF EXISTS "${table}"`,
+				args: []
+			})), "write");
+		});
+		await this.init();
+	}
+	async reconcileStructure(plan) {
+		return withReconcileLock(this.getStorageIsolationKey(), () => this.#transaction(async (tx) => {
+			await tx.execute(`UPDATE "${TABLE_KNOWLEDGE_ACCESS_STATE}" SET epoch=epoch WHERE id='global'`);
+			const scopes = {};
+			const createdScopeIds = [];
+			const createdAddresses = /* @__PURE__ */ new Set();
+			const retrofit = plan.retrofit ?? true;
+			let structureChanged = false;
+			const deletedScopeAddresses = /* @__PURE__ */ new Set();
+			const resolveAddress = async (address) => {
+				if (scopes[address]) return scopes[address];
+				const row = (await tx.execute({
+					sql: `SELECT a.scopeNodeId,n.isScope,n.deletedAt FROM "${TABLE_KNOWLEDGE_SCOPE_ADDRESSES}" a JOIN "${TABLE_KNOWLEDGE_NODES}" n ON n.id=a.scopeNodeId WHERE a.address=?`,
+					args: [address]
+				})).rows[0];
+				if (!row) return void 0;
+				if (!row.isScope) throw new Error(`Knowledge address ${address} does not reference a scope`);
+				if (row.deletedAt) deletedScopeAddresses.add(address);
+				scopes[address] = String(row.scopeNodeId);
+				return scopes[address];
+			};
+			for (const scope of plan.scopes) {
+				if (await resolveAddress(scope.address)) continue;
+				const id = randomUUID();
+				const now = (/* @__PURE__ */ new Date()).toISOString();
+				await tx.execute({
+					sql: `INSERT INTO "${TABLE_KNOWLEDGE_NODES}" (id,type,name,canonicalName,kind,description,isScope,metadata,version,createdAt,updatedAt) VALUES (?,'node',?,?,?,?,TRUE,jsonb(?),1,?,?)`,
+					args: [
+						id,
+						scope.name,
+						canonicalName(scope.name),
+						scope.kind ?? null,
+						scope.description ?? null,
+						scope.metadata ? JSON.stringify(scope.metadata) : null,
+						now,
+						now
+					]
+				});
+				await tx.execute({
+					sql: `INSERT INTO "${TABLE_KNOWLEDGE_SCOPE_ADDRESSES}" (address,scopeNodeId) VALUES (?,?)`,
+					args: [scope.address, id]
+				});
+				scopes[scope.address] = id;
+				createdAddresses.add(scope.address);
+				createdScopeIds.push(id);
+				structureChanged = true;
+			}
+			for (const scope of plan.scopes) {
+				if (!createdAddresses.has(scope.address) && (!retrofit || deletedScopeAddresses.has(scope.address))) continue;
+				const scopeNodeId = scopes[scope.address];
+				for (const parentAddress of scope.parentAddresses ?? []) {
+					const parentId = await resolveAddress(parentAddress);
+					if (!parentId || deletedScopeAddresses.has(parentAddress)) {
+						const deletedParentId = scopes[parentAddress];
+						if ((deletedParentId ? await tx.execute({
+							sql: `SELECT 1 FROM "mastra_knowledge_node_scopes" WHERE nodeId=? AND scopeNodeId=?`,
+							args: [scopeNodeId, deletedParentId]
+						}) : void 0)?.rows.length) continue;
+						throw new Error(`Knowledge parent scope does not exist: ${parentAddress}`);
+					}
+					if ((await tx.execute({
+						sql: `SELECT 1 FROM "mastra_knowledge_node_scopes" WHERE nodeId=? AND scopeNodeId=?`,
+						args: [scopeNodeId, parentId]
+					})).rows.length) continue;
+					if ((await tx.execute({
+						sql: `SELECT n.id FROM "mastra_knowledge_node_scopes" ns JOIN "${TABLE_KNOWLEDGE_NODES}" n ON n.id=ns.nodeId WHERE ns.scopeNodeId=? AND n.isScope AND n.canonicalName=? AND n.deletedAt IS NULL AND n.id<>? LIMIT 1`,
+						args: [
+							parentId,
+							canonicalName(scope.name),
+							scopeNodeId
+						]
+					})).rows.length) throw new Error(`Knowledge scope name ${scope.name} already exists under ${parentAddress}`);
+					const inserted = await tx.execute({
+						sql: `INSERT OR IGNORE INTO "${TABLE_KNOWLEDGE_NODE_SCOPES}" (nodeId,scopeNodeId,addedAt) VALUES (?,?,?)`,
+						args: [
+							scopeNodeId,
+							parentId,
+							(/* @__PURE__ */ new Date()).toISOString()
+						]
+					});
+					structureChanged ||= inserted.rowsAffected > 0;
+				}
+				for (const grant of scope.grants ?? []) {
+					const scopeRefId = await resolveAddress(grant.scopeRefAddress);
+					if (!scopeRefId || deletedScopeAddresses.has(grant.scopeRefAddress)) {
+						const deletedScopeRefId = scopes[grant.scopeRefAddress];
+						if ((deletedScopeRefId ? await tx.execute({
+							sql: `SELECT 1 FROM "mastra_knowledge_scope_grants" WHERE scopeNodeId=? AND scopeRefId=?`,
+							args: [scopeNodeId, deletedScopeRefId]
+						}) : void 0)?.rows.length) continue;
+						throw new Error(`Knowledge grant scope does not exist: ${grant.scopeRefAddress}`);
+					}
+					const inserted = await tx.execute({
+						sql: `INSERT OR IGNORE INTO "${TABLE_KNOWLEDGE_SCOPE_GRANTS}" (scopeNodeId,scopeRefId,role,canSuggest) VALUES (?,?,?,?)`,
+						args: [
+							scopeNodeId,
+							scopeRefId,
+							grant.role,
+							grant.canSuggest ?? null
+						]
+					});
+					structureChanged ||= inserted.rowsAffected > 0;
+				}
+			}
+			if (structureChanged) await tx.execute(`UPDATE "${TABLE_KNOWLEDGE_ACCESS_STATE}" SET epoch=epoch+1 WHERE id='global'`);
+			const state = await tx.execute(`SELECT epoch FROM "${TABLE_KNOWLEDGE_ACCESS_STATE}" WHERE id='global'`);
+			return {
+				scopes,
+				createdScopeIds,
+				deletedScopeAddresses: [...deletedScopeAddresses],
+				changed: structureChanged,
+				accessEpoch: Number(state.rows[0]?.epoch ?? 0)
+			};
+		}));
+	}
+	async listScopeNodes(input = {}) {
+		const { limit, after } = parseListKnowledgeScopeNodesInput(input);
+		if (input.addresses?.length === 0 || input.ids?.length === 0) return {
+			scopes: [],
+			nextCursor: null
+		};
+		const args = [];
+		const where = [`n.isScope`, `n.deletedAt IS NULL`];
+		let within = "";
+		if (input.withinAddress !== void 0) {
+			within = `WITH RECURSIVE within_scope(id) AS (SELECT r.id FROM "${TABLE_KNOWLEDGE_NODES}" r JOIN "${TABLE_KNOWLEDGE_SCOPE_ADDRESSES}" ra ON ra.scopeNodeId=r.id WHERE ra.address=? AND r.isScope AND r.deletedAt IS NULL UNION SELECT ns.nodeId FROM "${TABLE_KNOWLEDGE_NODE_SCOPES}" ns JOIN within_scope w ON ns.scopeNodeId=w.id JOIN "${TABLE_KNOWLEDGE_NODES}" c ON c.id=ns.nodeId WHERE c.isScope AND c.deletedAt IS NULL) `;
+			args.push(input.withinAddress);
+			where.push("n.id IN (SELECT id FROM within_scope)");
+		}
+		if (input.addresses) {
+			where.push(`a.address IN (${input.addresses.map(() => "?").join(",")})`);
+			args.push(...input.addresses);
+		}
+		if (input.ids) {
+			where.push(`n.id IN (${input.ids.map(() => "?").join(",")})`);
+			args.push(...input.ids);
+		}
+		if (after) {
+			where.push("(n.name > ? OR (n.name = ? AND n.id > ?))");
+			args.push(after.name, after.name, after.id);
+		}
+		args.push(limit + 1);
+		const rows = (await this.#client.execute({
+			sql: `${within}SELECT n.id,n.name,n.kind,n.description,a.address FROM "${TABLE_KNOWLEDGE_NODES}" n LEFT JOIN "${TABLE_KNOWLEDGE_SCOPE_ADDRESSES}" a ON a.scopeNodeId=n.id WHERE ${where.join(" AND ")} ORDER BY n.name, n.id LIMIT ?`,
+			args
+		})).rows;
+		if (rows.length === 0) return {
+			scopes: [],
+			nextCursor: null
+		};
+		const parents = await this.#client.execute({
+			sql: `SELECT ns.nodeId,ns.scopeNodeId FROM "${TABLE_KNOWLEDGE_NODE_SCOPES}" ns WHERE ns.nodeId IN (${rows.map(() => "?").join(",")}) ORDER BY ns.scopeNodeId`,
+			args: rows.map((row) => String(row.id))
 		});
+		const parentsByScopeId = /* @__PURE__ */ new Map();
+		for (const row of parents.rows) {
+			const scopeId = String(row.nodeId);
+			const parentId = String(row.scopeNodeId);
+			const existing = parentsByScopeId.get(scopeId);
+			if (existing) existing.push(parentId);
+			else parentsByScopeId.set(scopeId, [parentId]);
+		}
+		return pageKnowledgeScopeNodes(rows.map((row) => ({
+			id: String(row.id),
+			address: String(row.address),
+			name: String(row.name),
+			...row.kind == null ? {} : { kind: String(row.kind) },
+			...row.description == null ? {} : { description: String(row.description) },
+			parentIds: parentsByScopeId.get(String(row.id)) ?? []
+		})), limit, input);
+	}
+	async listScopeMembers(input) {
+		const { limit, after } = parseListKnowledgeScopeMembersInput(input);
+		const args = [input.scopeNodeId];
+		let keyset = "";
+		if (after) {
+			const updatedAt = after.updatedAt.toISOString();
+			keyset = ` AND (n.updatedAt < ? OR (n.updatedAt = ? AND (n.name > ? OR (n.name = ? AND n.id > ?))))`;
+			args.push(updatedAt, updatedAt, after.name, after.name, after.id);
+		}
+		args.push(limit + 1);
+		return pageKnowledgeScopeMembers((await this.#client.execute({
+			sql: `SELECT *, json(scope) AS scopeJson FROM "${TABLE_KNOWLEDGE_NODES}" n WHERE EXISTS (SELECT 1 FROM "${TABLE_KNOWLEDGE_NODE_SCOPES}" ns WHERE ns.nodeId=n.id AND ns.scopeNodeId=?) AND n.deletedAt IS NULL AND n.mergedInto IS NULL${keyset} ORDER BY n.updatedAt DESC, n.name ASC, n.id ASC LIMIT ?`,
+			args
+		})).rows.map(parseNode), limit, input);
 	}
 	async createNode(input) {
 		await assertKnowledgeDescriptionWithinBoundCompat(input.description);
@@ -6232,6 +7662,7 @@ var KnowledgeLibSQL = class extends KnowledgeStorage {
 			if (existing) {
 				const terminal = await this.#resolveTerminalNode(tx, existing.id);
 				if (!isKnowledgeScopeVisible(terminal.scope, scope)) throw new Error(`Merged knowledge node is not visible from scope: ${input.name}`);
+				await this.#placeNodeInScopes(tx, terminal.id, input.scopeAddresses, /* @__PURE__ */ new Date());
 				return terminal;
 			}
 			const now = /* @__PURE__ */ new Date();
@@ -6248,7 +7679,7 @@ var KnowledgeLibSQL = class extends KnowledgeStorage {
 				updatedAt: now
 			};
 			await tx.execute({
-				sql: `INSERT INTO "${TABLE_KNOWLEDGE_NODES}" (id,type,name,canonicalName,kind,content,description,scope,scopeKey,version,mergedInto,createdAt,updatedAt) VALUES (?,?,?,?,?,?,?,jsonb(?),?,?,NULL,?,?)`,
+				sql: `INSERT INTO "${TABLE_KNOWLEDGE_NODES}" (id,type,name,canonicalName,kind,content,description,isScope,scope,scopeKey,version,mergedInto,createdAt,updatedAt) VALUES (?,?,?,?,?,?,?,FALSE,jsonb(?),?,?,NULL,?,?)`,
 				args: [
 					node.id,
 					"node",
@@ -6264,6 +7695,8 @@ var KnowledgeLibSQL = class extends KnowledgeStorage {
 					now.toISOString()
 				]
 			});
+			await this.#replaceNodeScopes(tx, node.id, scope, now);
+			await this.#placeNodeInScopes(tx, node.id, input.scopeAddresses, now);
 			await this.#replaceMentions(tx, "node", node.id, node.content ?? "", input.resolutionScope ?? scope, scope);
 			await this.#activity(tx, "node-created", "node", node.id, scope);
 			await this.#outbox(tx, "node", node.id, "upsert", node.version, scope);
@@ -6280,13 +7713,13 @@ var KnowledgeLibSQL = class extends KnowledgeStorage {
 		return this.#resolveNode(this.#client, input.name, canonicalizeKnowledgeScope(input.scope));
 	}
 	async listNodes(input) {
-		const key = knowledgeScopeKey(canonicalizeKnowledgeScope(input.scope));
+		const keys = visibleScopeKeys(canonicalizeKnowledgeScope(input.scope));
 		const clauses = [
 			`type = 'node'`,
 			"mergedInto IS NULL",
-			visibleSql
+			visibleSql(keys)
 		];
-		const args = [key, key];
+		const args = [...keys];
 		if (input.namePrefix) {
 			clauses.push("canonicalName LIKE ? ESCAPE '='");
 			args.push(`${escapeLikePattern(canonicalName(input.namePrefix))}%`);
@@ -6338,6 +7771,7 @@ var KnowledgeLibSQL = class extends KnowledgeStorage {
 					input.version
 				]
 			})).rowsAffected === 0) throw new KnowledgeConflictError(input.id);
+			if (knowledgeScopeKey(existing.scope) !== knowledgeScopeKey(scope)) await this.#swapIdentityScopes(tx, input.id, existing.scope, scope, now);
 			if (input.content !== void 0 || input.name !== void 0 || input.scope !== void 0) await this.#replaceMentions(tx, "node", input.id, content ?? "", input.resolutionScope ?? scope, scope);
 			await this.#activity(tx, "node-updated", "node", input.id, scope);
 			if (knowledgeScopeKey(existing.scope) !== knowledgeScopeKey(scope)) {
@@ -6392,8 +7826,12 @@ var KnowledgeLibSQL = class extends KnowledgeStorage {
 				]
 			})).rowsAffected === 0) throw new KnowledgeConflictError(source.id);
 			await tx.execute({
-				sql: `UPDATE "${TABLE_KNOWLEDGE_RECORDS}" SET node=? WHERE node=?`,
-				args: [target.id, source.id]
+				sql: `UPDATE "${TABLE_KNOWLEDGE_RECORDS}" SET node=?,version=version+1,updatedAt=? WHERE node=?`,
+				args: [
+					target.id,
+					(/* @__PURE__ */ new Date()).toISOString(),
+					source.id
+				]
 			});
 			await tx.execute({
 				sql: `DELETE FROM "${TABLE_KNOWLEDGE_MENTIONS}" WHERE recordId=? AND EXISTS (SELECT 1 FROM "${TABLE_KNOWLEDGE_MENTIONS}" target WHERE target.sourceType="${TABLE_KNOWLEDGE_MENTIONS}".sourceType AND target.sourceId="${TABLE_KNOWLEDGE_MENTIONS}".sourceId AND target.recordId=?)`,
@@ -6433,10 +7871,10 @@ var KnowledgeLibSQL = class extends KnowledgeStorage {
 		});
 	}
 	async appendKnowledge(input) {
+		await assertKnowledgeRecordTextWithinBoundCompat(input.text);
 		const scope = canonicalizeKnowledgeScope(input.scope);
 		const resolutionScope = canonicalizeKnowledgeScope(input.resolutionScope);
 		const defaultScope = canonicalizeKnowledgeScope(input.defaultScope);
-		assertKnowledgeScopeWithinCeiling(scope, input.maxScope);
 		return this.#transaction(async (tx) => {
 			const node = nodeReferenceId(input.node);
 			const parent = await this.#resolveTerminalNode(tx, node);
@@ -6449,11 +7887,10 @@ var KnowledgeLibSQL = class extends KnowledgeStorage {
 				sourceThreadId: input.sourceThreadId,
 				capturedAt: /* @__PURE__ */ new Date(),
 				when: input.when ? new Date(input.when) : void 0,
-				maxScope: input.maxScope,
 				metadata: input.metadata
 			};
 			await tx.execute({
-				sql: `INSERT INTO "${TABLE_KNOWLEDGE_RECORDS}" (id,node,text,scope,scopeKey,sourceThreadId,capturedAt,"when",maxScope,metadata,deletedAt,deletedBy) VALUES (?,?,?,jsonb(?),?,?,?,?,?,jsonb(?),NULL,NULL)`,
+				sql: `INSERT INTO "${TABLE_KNOWLEDGE_RECORDS}" (id,node,text,scope,scopeKey,sourceThreadId,capturedAt,"when",metadata,version,updatedAt,deletedAt,deletedBy) VALUES (?,?,?,jsonb(?),?,?,?,?,jsonb(?),?,?,NULL,NULL)`,
 				args: [
 					record.id,
 					record.node,
@@ -6463,10 +7900,12 @@ var KnowledgeLibSQL = class extends KnowledgeStorage {
 					record.sourceThreadId,
 					record.capturedAt.toISOString(),
 					record.when?.toISOString() ?? null,
-					record.maxScope ?? null,
-					record.metadata ? JSON.stringify(record.metadata) : null
+					record.metadata ? JSON.stringify(record.metadata) : null,
+					1,
+					record.capturedAt.toISOString()
 				]
 			});
+			await this.#replaceRecordScopes(tx, record.id, scope, record.capturedAt);
 			await this.#replaceMentions(tx, "record", record.id, record.text, resolutionScope, defaultScope);
 			await this.#activity(tx, "record-created", "record", record.id, scope, record.sourceThreadId);
 			await this.#outbox(tx, "record", record.id, "upsert", record.id, scope);
@@ -6490,17 +7929,13 @@ var KnowledgeLibSQL = class extends KnowledgeStorage {
 		return this.#queryKnowledge(input, "related");
 	}
 	async knowledgeBySource(input) {
-		const key = knowledgeScopeKey(canonicalizeKnowledgeScope(input.scope));
-		const args = [
-			input.sourceThreadId,
-			key,
-			key
-		];
+		const keys = visibleScopeKeys(canonicalizeKnowledgeScope(input.scope));
+		const args = [input.sourceThreadId, ...keys];
 		if (input.after) args.push(input.after);
 		const limit = input.limit ?? 100;
 		args.push(limit + 1);
 		const records = (await this.#client.execute({
-			sql: `SELECT *,json(scope) AS scopeJson,json(metadata) AS metadataJson FROM "${TABLE_KNOWLEDGE_RECORDS}" WHERE sourceThreadId=? AND ${visibleSql}${input.includeDeleted ? "" : " AND deletedAt IS NULL"}${input.after ? " AND id > ?" : ""} ORDER BY id ASC LIMIT ?`,
+			sql: `SELECT *,json(scope) AS scopeJson,json(metadata) AS metadataJson FROM "${TABLE_KNOWLEDGE_RECORDS}" WHERE sourceThreadId=? AND ${visibleSql(keys)}${input.includeDeleted ? "" : " AND deletedAt IS NULL"}${input.after ? " AND id > ?" : ""} ORDER BY id ASC LIMIT ?`,
 			args
 		})).rows.map(parseKnowledge);
 		return {
@@ -6515,10 +7950,11 @@ var KnowledgeLibSQL = class extends KnowledgeStorage {
 			if (record.deletedAt) return record;
 			const deletedAt = /* @__PURE__ */ new Date();
 			await tx.execute({
-				sql: `UPDATE "${TABLE_KNOWLEDGE_RECORDS}" SET deletedAt=?,deletedBy=? WHERE id=? AND deletedAt IS NULL`,
+				sql: `UPDATE "${TABLE_KNOWLEDGE_RECORDS}" SET deletedAt=?,deletedBy=?,version=version+1,updatedAt=? WHERE id=? AND deletedAt IS NULL`,
 				args: [
 					deletedAt.toISOString(),
 					input.deletedBy,
+					deletedAt.toISOString(),
 					input.id
 				]
 			});
@@ -6537,8 +7973,8 @@ var KnowledgeLibSQL = class extends KnowledgeStorage {
 			if (!record) throw new KnowledgeNotFoundError("record", input.id);
 			if (!record.deletedAt) return record;
 			await tx.execute({
-				sql: `UPDATE "${TABLE_KNOWLEDGE_RECORDS}" SET deletedAt=NULL,deletedBy=NULL WHERE id=?`,
-				args: [input.id]
+				sql: `UPDATE "${TABLE_KNOWLEDGE_RECORDS}" SET deletedAt=NULL,deletedBy=NULL,version=version+1,updatedAt=? WHERE id=?`,
+				args: [(/* @__PURE__ */ new Date()).toISOString(), input.id]
 			});
 			await this.#activity(tx, "record-restored", "record", input.id, record.scope, record.sourceThreadId);
 			await this.#outbox(tx, "record", input.id, "upsert", createKnowledgeUlid(), record.scope);
@@ -6554,15 +7990,17 @@ var KnowledgeLibSQL = class extends KnowledgeStorage {
 		return this.#transaction(async (tx) => {
 			const record = await this.#getKnowledge(tx, input.id, true);
 			if (!record) throw new KnowledgeNotFoundError("record", input.id);
-			assertKnowledgeScopeWithinCeiling(scope, record.maxScope);
+			const updatedAt = /* @__PURE__ */ new Date();
 			await tx.execute({
-				sql: `UPDATE "${TABLE_KNOWLEDGE_RECORDS}" SET scope=jsonb(?),scopeKey=? WHERE id=?`,
+				sql: `UPDATE "${TABLE_KNOWLEDGE_RECORDS}" SET scope=jsonb(?),scopeKey=?,version=version+1,updatedAt=? WHERE id=?`,
 				args: [
 					JSON.stringify(scope),
 					knowledgeScopeKey(scope),
+					updatedAt.toISOString(),
 					input.id
 				]
 			});
+			await this.#replaceRecordScopes(tx, input.id, scope, updatedAt);
 			await this.#activity(tx, "record-rescoped", "record", input.id, scope, record.sourceThreadId);
 			if (knowledgeScopeKey(record.scope) !== knowledgeScopeKey(scope)) await this.#outbox(tx, "record", input.id, "delete", createKnowledgeUlid(), record.scope);
 			if (!record.deletedAt) await this.#outbox(tx, "record", input.id, "upsert", createKnowledgeUlid(), scope);
@@ -6572,32 +8010,16 @@ var KnowledgeLibSQL = class extends KnowledgeStorage {
 			};
 		});
 	}
-	async raiseKnowledgeCeiling(input) {
-		return this.#transaction(async (tx) => {
-			const record = await this.#getKnowledge(tx, input.id, true);
-			if (!record) throw new KnowledgeNotFoundError("record", input.id);
-			assertKnowledgeScopeWithinCeiling(record.scope, input.maxScope);
-			assertKnowledgeCeilingRaised(record.maxScope, input.maxScope);
-			await tx.execute({
-				sql: `UPDATE "${TABLE_KNOWLEDGE_RECORDS}" SET maxScope=? WHERE id=?`,
-				args: [input.maxScope ?? null, input.id]
-			});
-			return {
-				...record,
-				maxScope: input.maxScope
-			};
-		});
-	}
 	async search(input) {
-		const key = knowledgeScopeKey(canonicalizeKnowledgeScope(input.scope));
+		const scope = canonicalizeKnowledgeScope(input.scope);
+		const keys = visibleScopeKeys(scope);
 		const normalizedQuery = input.query.trim().toLocaleLowerCase();
 		if (!normalizedQuery) return [];
 		const query = `%${escapeLikePattern(normalizedQuery)}%`;
 		const results = (await this.#client.execute({
-			sql: `SELECT *,json(scope) AS scopeJson FROM "${TABLE_KNOWLEDGE_NODES}" WHERE mergedInto IS NULL AND ${visibleSql} AND (canonicalName LIKE ? ESCAPE '=' OR lower(COALESCE(kind,'')) LIKE ? ESCAPE '=' OR lower(COALESCE(content,'')) LIKE ? ESCAPE '=' OR lower(COALESCE(description,'')) LIKE ? ESCAPE '=') ORDER BY updatedAt DESC LIMIT ?`,
+			sql: `SELECT *,json(scope) AS scopeJson FROM "${TABLE_KNOWLEDGE_NODES}" WHERE mergedInto IS NULL AND ${visibleSql(keys)} AND (canonicalName LIKE ? ESCAPE '=' OR lower(COALESCE(kind,'')) LIKE ? ESCAPE '=' OR lower(COALESCE(content,'')) LIKE ? ESCAPE '=' OR lower(COALESCE(description,'')) LIKE ? ESCAPE '=') ORDER BY updatedAt DESC LIMIT ?`,
 			args: [
-				key,
-				key,
+				...keys,
 				query,
 				query,
 				query,
@@ -6618,60 +8040,47 @@ var KnowledgeLibSQL = class extends KnowledgeStorage {
 		}));
 		if (results.length < (input.limit ?? 20)) {
 			const knowledge = await this.#client.execute({
-				sql: `SELECT k.*,json(k.scope) AS scopeJson,json(k.metadata) AS metadataJson,n.name FROM "${TABLE_KNOWLEDGE_RECORDS}" k JOIN "${TABLE_KNOWLEDGE_NODES}" n ON n.id=k.node AND n.type='node' AND n.mergedInto IS NULL WHERE k.deletedAt IS NULL AND ${visibleSql.replaceAll("scopeKey", "k.scopeKey")} AND lower(k.text) LIKE ? ESCAPE '=' ORDER BY k.id DESC LIMIT ?`,
+				sql: `SELECT k.*,json(k.scope) AS scopeJson,json(k.metadata) AS metadataJson,n.name,json(n.scope) AS parentScopeJson FROM "${TABLE_KNOWLEDGE_RECORDS}" k CROSS JOIN "${TABLE_KNOWLEDGE_NODES}" n ON n.id=k.node AND n.type='node' AND n.mergedInto IS NULL WHERE k.deletedAt IS NULL AND ${visibleSql(keys, "k.scopeKey")} AND lower(k.text) LIKE ? ESCAPE '=' ORDER BY k.id DESC LIMIT ?`,
 				args: [
-					key,
-					key,
+					...keys,
 					query,
 					(input.limit ?? 20) - results.length
 				]
 			});
-			results.push(...knowledge.rows.map((row) => ({
-				type: "record",
-				id: String(row.id),
-				recordId: String(row.node),
-				name: String(row.name),
-				text: String(row.text),
-				scope: parseJson$3(row.scopeJson)
-			})));
+			results.push(...knowledge.rows.map((row) => {
+				const parentVisible = isKnowledgeScopeVisible(parseJson$3(row.parentScopeJson), scope);
+				return {
+					type: "record",
+					id: String(row.id),
+					recordId: parentVisible ? String(row.node) : String(row.id),
+					name: parentVisible ? String(row.name) : "(private node)",
+					text: String(row.text),
+					scope: parseJson$3(row.scopeJson)
+				};
+			}));
 		}
 		return results;
 	}
-	async getCurationCursor(input) {
-		const row = (await this.#client.execute({
-			sql: `SELECT * FROM "${TABLE_KNOWLEDGE_CURSORS}" WHERE sourceThreadId=? AND agent=?`,
-			args: [input.sourceThreadId, input.agent]
-		})).rows[0];
-		return row ? {
-			sourceThreadId: String(row.sourceThreadId),
-			agent: String(row.agent),
-			lastKnowledgeId: String(row.lastKnowledgeId),
-			updatedAt: toDate(row.updatedAt)
-		} : null;
-	}
-	async advanceCurationCursor(input) {
-		const updatedAt = /* @__PURE__ */ new Date();
-		if ((await this.#db.executeWriteOperationWithRetry(() => withClientWriteLock(this.#client, () => this.#client.execute({
-			sql: `INSERT INTO "${TABLE_KNOWLEDGE_CURSORS}" (sourceThreadId,agent,lastKnowledgeId,updatedAt) VALUES (?,?,?,?) ON CONFLICT(sourceThreadId,agent) DO UPDATE SET lastKnowledgeId=excluded.lastKnowledgeId,updatedAt=excluded.updatedAt WHERE excluded.lastKnowledgeId >= "${TABLE_KNOWLEDGE_CURSORS}".lastKnowledgeId`,
-			args: [
-				input.sourceThreadId,
-				input.agent,
-				input.lastKnowledgeId,
-				updatedAt.toISOString()
-			]
-		})), "advance knowledge curation cursor")).rowsAffected === 0) throw new Error("Knowledge curation cursor cannot move backwards");
-		return {
-			...input,
-			updatedAt
-		};
+	/**
+	* @deprecated Curation cursors were removed. Observation-time curate is the only Knowledge writer and needs no
+	* cursor. Always throws.
+	*/
+	async getCurationCursor(_input) {
+		throw new Error(KNOWLEDGE_CURATION_CURSOR_REMOVED_MESSAGE);
+	}
+	/**
+	* @deprecated Curation cursors were removed. Observation-time curate is the only Knowledge writer and needs no
+	* cursor. Always throws.
+	*/
+	async advanceCurationCursor(_input) {
+		throw new Error(KNOWLEDGE_CURATION_CURSOR_REMOVED_MESSAGE);
 	}
 	async listActivity(input) {
-		const key = knowledgeScopeKey(canonicalizeKnowledgeScope(input.scope));
+		const keys = visibleScopeKeys(canonicalizeKnowledgeScope(input.scope));
 		return (await this.#client.execute({
-			sql: `SELECT *,json(scope) AS scopeJson FROM "${TABLE_KNOWLEDGE_ACTIVITY}" WHERE ${visibleSql}${input.after ? " AND id < ?" : ""} ORDER BY id DESC LIMIT ?`,
+			sql: `SELECT *,json(scope) AS scopeJson FROM "${TABLE_KNOWLEDGE_ACTIVITY}" WHERE ${visibleSql(keys)}${input.after ? " AND id < ?" : ""} ORDER BY id DESC LIMIT ?`,
 			args: [
-				key,
-				key,
+				...keys,
 				...input.after ? [input.after] : [],
 				input.limit ?? 100
 			]
@@ -6693,9 +8102,9 @@ var KnowledgeLibSQL = class extends KnowledgeStorage {
 			args.push(input.status);
 		}
 		if (input.scope) {
-			const key = knowledgeScopeKey(canonicalizeKnowledgeScope(input.scope));
-			clauses.push(visibleSql);
-			args.push(key, key);
+			const keys = visibleScopeKeys(input.scope);
+			clauses.push(visibleSql(keys));
+			args.push(...keys);
 		}
 		args.push(input.limit ?? 100);
 		return (await this.#client.execute({
@@ -6714,9 +8123,9 @@ var KnowledgeLibSQL = class extends KnowledgeStorage {
 			];
 			const args = [now.toISOString(), stale.toISOString()];
 			if (input.scope) {
-				const key = knowledgeScopeKey(canonicalizeKnowledgeScope(input.scope));
-				clauses.push(visibleSql);
-				args.push(key, key);
+				const keys = visibleScopeKeys(input.scope);
+				clauses.push(visibleSql(keys));
+				args.push(...keys);
 			}
 			args.push(input.limit ?? 100);
 			const ids = (await tx.execute({
@@ -6793,12 +8202,14 @@ var KnowledgeLibSQL = class extends KnowledgeStorage {
 		return result.rows[0] ? parseNode(result.rows[0]) : null;
 	}
 	async #resolveNode(executor, name, scope) {
-		for (let length = scope.length; length > 0; length--) {
-			const node = await this.#getNodeByName(executor, name, scope.slice(0, length));
-			if (node) {
-				const terminal = await this.#resolveTerminalNode(executor, node.id);
-				if (terminal && isKnowledgeScopeVisible(terminal.scope, scope)) return terminal;
-			}
+		const keys = visibleScopeKeys(scope);
+		const candidates = (await executor.execute({
+			sql: `SELECT *,json(scope) AS scopeJson FROM "${TABLE_KNOWLEDGE_NODES}" WHERE type='node' AND canonicalName=? AND (scopeKey IN (${keys.map(() => "?").join(",")}) OR mergedInto IS NOT NULL)`,
+			args: [canonicalName(name), ...keys]
+		})).rows.map(parseNode).sort((left, right) => right.scope.length - left.scope.length);
+		for (const candidate of candidates) {
+			const terminal = await this.#resolveTerminalNode(executor, candidate.id);
+			if (terminal && isKnowledgeScopeVisible(terminal.scope, scope)) return terminal;
 		}
 		return null;
 	}
@@ -6823,19 +8234,18 @@ var KnowledgeLibSQL = class extends KnowledgeStorage {
 		const scope = canonicalizeKnowledgeScope(input.scope);
 		const node = await this.#resolveTerminalNode(this.#client, nodeReferenceId(input.node));
 		if (!node) return { records: [] };
-		const key = knowledgeScopeKey(scope);
+		const keys = visibleScopeKeys(scope);
 		const includesMentions = relationship !== "about";
 		const relationSql = relationship === "about" ? "k.node=?" : relationship === "mentioning" ? "m.recordId=?" : "(k.node=? OR m.recordId=?)";
 		const args = [
 			node.id,
 			...relationship === "related" ? [node.id] : [],
-			key,
-			key
+			...keys
 		];
 		if (input.after) args.push(input.after);
 		args.push((input.limit ?? 100) + 1);
 		const result = await this.#client.execute({
-			sql: `SELECT DISTINCT k.*,json(k.scope) AS scopeJson,json(k.metadata) AS metadataJson FROM "${TABLE_KNOWLEDGE_RECORDS}" k${includesMentions ? ` LEFT JOIN "${TABLE_KNOWLEDGE_MENTIONS}" m ON m.sourceType='record' AND m.sourceId=k.id` : ""} WHERE ${relationSql} AND ${visibleSql.replaceAll("scopeKey", "k.scopeKey")}${input.includeDeleted ? "" : " AND k.deletedAt IS NULL"}${input.after ? " AND k.id < ?" : ""} ORDER BY k.id DESC LIMIT ?`,
+			sql: `SELECT DISTINCT k.*,json(k.scope) AS scopeJson,json(k.metadata) AS metadataJson FROM "${TABLE_KNOWLEDGE_RECORDS}" k${includesMentions ? ` LEFT JOIN "${TABLE_KNOWLEDGE_MENTIONS}" m ON m.sourceType='record' AND m.sourceId=k.id` : ""} WHERE ${relationSql} AND ${visibleSql(keys, "k.scopeKey")}${input.includeDeleted ? "" : " AND k.deletedAt IS NULL"}${input.after ? " AND k.id < ?" : ""} ORDER BY k.id DESC LIMIT ?`,
 			args
 		});
 		const limit = input.limit ?? 100;
@@ -6845,6 +8255,90 @@ var KnowledgeLibSQL = class extends KnowledgeStorage {
 			nextCursor: result.rows.length > limit ? String(rows.at(-1)?.id) : void 0
 		};
 	}
+	async #resolveScopeNodeIds(executor, addresses) {
+		const scopeNodeIds = /* @__PURE__ */ new Set();
+		for (const address of addresses) {
+			const result = await executor.execute({
+				sql: `SELECT scopeNodeId FROM "${TABLE_KNOWLEDGE_SCOPE_ADDRESSES}" WHERE address=?`,
+				args: [address]
+			});
+			if (result.rows[0]?.scopeNodeId != null) scopeNodeIds.add(String(result.rows[0].scopeNodeId));
+		}
+		return [...scopeNodeIds];
+	}
+	async #replaceNodeScopes(executor, nodeId, addresses, addedAt) {
+		await executor.execute({
+			sql: `DELETE FROM "${TABLE_KNOWLEDGE_NODE_SCOPES}" WHERE nodeId=?`,
+			args: [nodeId]
+		});
+		for (const scopeNodeId of await this.#resolveScopeNodeIds(executor, addresses)) await executor.execute({
+			sql: `INSERT OR IGNORE INTO "${TABLE_KNOWLEDGE_NODE_SCOPES}" (nodeId,scopeNodeId,addedAt) VALUES (?,?,?)`,
+			args: [
+				nodeId,
+				scopeNodeId,
+				addedAt.toISOString()
+			]
+		});
+	}
+	/**
+	* Move a node's identity memberships from `from` to `to` without touching structural
+	* placements added by `#placeNodeInScopes`, which a scope change must not erase.
+	*/
+	async #swapIdentityScopes(executor, nodeId, from, to, addedAt) {
+		const next = await this.#resolveScopeNodeIds(executor, to);
+		for (const scopeNodeId of await this.#resolveScopeNodeIds(executor, from)) {
+			if (next.includes(scopeNodeId)) continue;
+			await executor.execute({
+				sql: `DELETE FROM "${TABLE_KNOWLEDGE_NODE_SCOPES}" WHERE nodeId=? AND scopeNodeId=?`,
+				args: [nodeId, scopeNodeId]
+			});
+		}
+		for (const scopeNodeId of next) await executor.execute({
+			sql: `INSERT OR IGNORE INTO "${TABLE_KNOWLEDGE_NODE_SCOPES}" (nodeId,scopeNodeId,addedAt) VALUES (?,?,?)`,
+			args: [
+				nodeId,
+				scopeNodeId,
+				addedAt.toISOString()
+			]
+		});
+	}
+	/**
+	* Additive structural placement: every address must resolve to a live scope node
+	* (unlike identity membership, an unknown address is a caller error, not a lazy
+	* materialization miss). Runs inside the caller's transaction, so a throw aborts
+	* the whole mutation.
+	*/
+	async #placeNodeInScopes(executor, nodeId, addresses, addedAt) {
+		for (const address of addresses ?? []) {
+			const scopeNodeId = (await executor.execute({
+				sql: `SELECT sa.scopeNodeId AS scopeNodeId FROM "${TABLE_KNOWLEDGE_SCOPE_ADDRESSES}" sa JOIN "${TABLE_KNOWLEDGE_NODES}" n ON n.id=sa.scopeNodeId WHERE sa.address=? AND n.isScope AND n.deletedAt IS NULL`,
+				args: [address]
+			})).rows[0]?.scopeNodeId;
+			if (scopeNodeId == null) throw new KnowledgeNotFoundError("scope", address);
+			await executor.execute({
+				sql: `INSERT OR IGNORE INTO "${TABLE_KNOWLEDGE_NODE_SCOPES}" (nodeId,scopeNodeId,addedAt) VALUES (?,?,?)`,
+				args: [
+					nodeId,
+					String(scopeNodeId),
+					addedAt.toISOString()
+				]
+			});
+		}
+	}
+	async #replaceRecordScopes(executor, recordId, addresses, addedAt) {
+		await executor.execute({
+			sql: `DELETE FROM "${TABLE_KNOWLEDGE_RECORD_SCOPES}" WHERE recordId=?`,
+			args: [recordId]
+		});
+		for (const scopeNodeId of await this.#resolveScopeNodeIds(executor, addresses)) await executor.execute({
+			sql: `INSERT OR IGNORE INTO "${TABLE_KNOWLEDGE_RECORD_SCOPES}" (recordId,scopeNodeId,addedAt) VALUES (?,?,?)`,
+			args: [
+				recordId,
+				scopeNodeId,
+				addedAt.toISOString()
+			]
+		});
+	}
 	async #replaceMentions(tx, sourceType, sourceId, text, resolutionScope, defaultScope) {
 		await tx.execute({
 			sql: `DELETE FROM "${TABLE_KNOWLEDGE_MENTIONS}" WHERE sourceType=? AND sourceId=?`,
@@ -6868,7 +8362,7 @@ var KnowledgeLibSQL = class extends KnowledgeStorage {
 						updatedAt: now
 					};
 					await tx.execute({
-						sql: `INSERT INTO "${TABLE_KNOWLEDGE_NODES}" (id,type,name,canonicalName,kind,content,scope,scopeKey,version,mergedInto,createdAt,updatedAt) VALUES (?,?,?,?,?,NULL,jsonb(?),?,?,NULL,?,?)`,
+						sql: `INSERT INTO "${TABLE_KNOWLEDGE_NODES}" (id,type,name,canonicalName,kind,content,isScope,scope,scopeKey,version,mergedInto,createdAt,updatedAt) VALUES (?,?,?,?,?,NULL,FALSE,jsonb(?),?,?,NULL,?,?)`,
 						args: [
 							node.id,
 							"node",
@@ -6882,6 +8376,7 @@ var KnowledgeLibSQL = class extends KnowledgeStorage {
 							now.toISOString()
 						]
 					});
+					await this.#replaceNodeScopes(tx, node.id, defaultScope, now);
 					await this.#activity(tx, "node-created", "node", node.id, defaultScope);
 					await this.#outbox(tx, "node", node.id, "upsert", 1, defaultScope);
 				}
@@ -6898,13 +8393,17 @@ var KnowledgeLibSQL = class extends KnowledgeStorage {
 	}
 	async #activity(executor, action, recordType, recordId, scope, sourceThreadId) {
 		const now = /* @__PURE__ */ new Date();
+		const [contextScopeId] = await this.#resolveScopeNodeIds(executor, scope);
 		await executor.execute({
-			sql: `INSERT INTO "${TABLE_KNOWLEDGE_ACTIVITY}" (id,action,recordType,recordId,scope,scopeKey,sourceThreadId,createdAt) VALUES (?,?,?,?,jsonb(?),?,?,?)`,
+			sql: `INSERT INTO "${TABLE_KNOWLEDGE_ACTIVITY}" (id,action,targetType,targetId,contextScopeId,recordType,recordId,scope,scopeKey,sourceThreadId,createdAt) VALUES (?,?,?,?,?,?,?,jsonb(?),?,?,?)`,
 			args: [
 				createKnowledgeUlid(),
 				action,
 				recordType,
 				recordId,
+				contextScopeId ?? null,
+				recordType,
+				recordId,
 				JSON.stringify(scope),
 				knowledgeScopeKey(scope),
 				sourceThreadId ?? null,
@@ -7831,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: {
@@ -7847,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;
@@ -7869,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,
@@ -7882,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({
@@ -7933,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.
@@ -7948,7 +9532,8 @@ var MemoryLibSQL = class MemoryLibSQL extends MemoryStorage {
 			order: [
 				"messages",
 				"resources",
-				"threads"
+				"threads",
+				"runFences"
 			]
 		});
 		return runPrune({
@@ -8330,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;
@@ -8368,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,
@@ -8382,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));
@@ -8438,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,
@@ -8503,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 = {
@@ -8519,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,
@@ -8543,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
 		}));
@@ -8747,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,
@@ -8766,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"),
@@ -8789,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,
@@ -8800,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,
@@ -9210,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" = ?,
@@ -9248,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;
@@ -9587,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]
@@ -9668,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]
@@ -9817,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" != ''
@@ -9857,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]
@@ -13359,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;
@@ -13420,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
+		};
+	}
+	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);
+		}
 	}
-	/** Delete workflow snapshots older than the `workflowSnapshot` policy's `maxAge`, batched. */
+	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,
@@ -13459,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]
@@ -13515,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]
@@ -13559,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();
@@ -13567,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)
@@ -13623,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,
@@ -14500,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() {
@@ -14666,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;
@@ -14682,7 +16435,10 @@ var LibSQLStore = class extends MastraCompositeStore {
 		const workflows = new WorkflowsLibSQL(domainConfig);
 		const workflowDefinitions = new WorkflowDefinitionsLibSQL(domainConfig);
 		const memory = new MemoryLibSQL(domainConfig);
-		const knowledge = new KnowledgeLibSQL(domainConfig);
+		const knowledge = new KnowledgeLibSQL({
+			...domainConfig,
+			storageIsolationKey: config.storageIsolationKey ?? getLibSQLKnowledgeIsolationKey(config, this.client)
+		});
 		const observability = new ObservabilityLibSQL(domainConfig);
 		const agents = new AgentsLibSQL(domainConfig);
 		const channels = new ChannelsLibSQL(domainConfig);
@@ -14729,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};`],
@@ -14739,14 +16495,14 @@ 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);
 		}
 	}
 	getStoresToInit() {
-		return Object.values(this.stores).filter(Boolean);
+		return Object.entries(this.stores).filter(([name]) => name !== "knowledge").map(([, store]) => store).filter(Boolean);
 	}
 	async initDomainsSequentially() {
 		for (const store of this.getStoresToInit()) await store.init();