@mastra/oracledb 0.5.2-alpha.0 → 0.5.2

package/dist/index.js

@@ -2,7 +2,7 @@ import { MastraVector, validateTopK, validateUpsertInput } from "@mastra/core/ve
 import oracledb from "oracledb";
 import { ErrorCategory, ErrorDomain, MastraError } from "@mastra/core/error";
 import { createHash } from "crypto";
-import { AgentsStorage, MCPClientsStorage, MastraCompositeStore, MemoryStorage, ObservabilityStorage, ScorerDefinitionsStorage, ScoresStorage, TABLE_AGENTS, TABLE_AGENT_VERSIONS, TABLE_MCP_CLIENTS, TABLE_MCP_CLIENT_VERSIONS, TABLE_MESSAGES, TABLE_OBSERVATIONAL_MEMORY, TABLE_RESOURCES, TABLE_SCHEMAS, TABLE_SCORERS, TABLE_SCORER_DEFINITIONS, TABLE_SCORER_DEFINITION_VERSIONS, TABLE_SPANS, TABLE_THREADS, TABLE_WORKFLOW_SNAPSHOT, TraceStatus, WorkflowsStorage, calculatePagination, createStorageErrorId, createVectorErrorId, executeRetentionPrune, listLogsArgsSchema, listScoresArgsSchema, listTracesArgsSchema, matchesExpectedWorkflowStatus, normalizePerPage, resolveRetentionTargets, retentionCutoffMs, storageMessageMatchesMetadataFilter, toTraceSpans, transformScoreRow, validateStorageMetadataFilter } from "@mastra/core/storage";
+import { AgentsStorage, MCPClientsStorage, MastraCompositeStore, MemoryStorage, ObservabilityStorage, RUN_FENCING_TABLE_SCHEMAS, RunFenceConflictError, ScorerDefinitionsStorage, ScoresStorage, TABLE_AGENTS, TABLE_AGENT_VERSIONS, TABLE_MCP_CLIENTS, TABLE_MCP_CLIENT_VERSIONS, TABLE_MEMORY_RUN_FENCES, TABLE_MESSAGES, TABLE_OBSERVATIONAL_MEMORY, TABLE_RESOURCES, TABLE_SCHEMAS, TABLE_SCORERS, TABLE_SCORER_DEFINITIONS, TABLE_SCORER_DEFINITION_VERSIONS, TABLE_SPANS, TABLE_THREADS, TABLE_WORKFLOW_RUN_OWNERS, TABLE_WORKFLOW_SNAPSHOT, TraceStatus, WorkflowsStorage, calculatePagination, createStorageErrorId, createVectorErrorId, executeRetentionPrune, isRunFenceConflictError, listLogsArgsSchema, listScoresArgsSchema, listTracesArgsSchema, matchesExpectedWorkflowStatus, matchesRunFence, normalizePerPage, resolveRetentionTargets, resolveRunFence, retentionCutoffMs, storageMessageMatchesMetadataFilter, toTraceSpans, transformScoreRow, validateStorageMetadataFilter } from "@mastra/core/storage";
 import { MessageList } from "@mastra/core/agent";
 import { saveScorePayloadSchema } from "@mastra/core/evals";
 //#region src/shared/connection.ts
@@ -3410,6 +3410,59 @@ function isAppendOnlySince(storedObservations, snapshotObservations) {
 	return stored === snapshot || stored.startsWith(snapshot);
 }
 //#endregion
+//#region src/storage/db/run-fencing.ts
+const SINCE_EPOCH = `(SYS_EXTRACT_UTC(SYSTIMESTAMP) - TIMESTAMP '1970-01-01 00:00:00')`;
+/**
+* Epoch milliseconds on the database clock. Oracle evaluates `SYSTIMESTAMP`
+* once per statement, so every reference here reads the same instant, and a
+* statement that waits on a lock compares against the time it started. That
+* error only makes an existing lease look longer and a new lease shorter.
+*/
+const DB_NOW_MS = `(EXTRACT(DAY FROM ${SINCE_EPOCH}) * 86400000 + EXTRACT(HOUR FROM ${SINCE_EPOCH}) * 3600000 + EXTRACT(MINUTE FROM ${SINCE_EPOCH}) * 60000 + FLOOR(EXTRACT(SECOND FROM ${SINCE_EPOCH}) * 1000))`;
+const ORA_UNIQUE_CONSTRAINT = -1;
+const ORA_DEADLOCK = -60;
+const MAX_CLAIM_ATTEMPTS = 5;
+/**
+* The check half of a fenced write; call it first inside the write's
+* transaction. Oracle has no shared row lock, so this takes the claim row
+* `FOR UPDATE`: a claim that updates the row waits for the write to commit,
+* and a write queued behind a claim re-reads the row once the claim commits
+* and sees the new generation. Writes from one run serialize on its row,
+* which they mostly do anyway.
+*/
+async function assertRunFence(client, claimsTable, fence, operation) {
+	const row = await client.oneOrNone(`SELECT generation AS "generation", "ownerId" FROM ${claimsTable} WHERE "runId" = :runId FOR UPDATE`, { runId: fence.runId });
+	if (!matchesRunFence(row ? {
+		generation: Number(row.generation),
+		ownerId: String(row.ownerId)
+	} : null, fence)) throw new RunFenceConflictError(fence, operation);
+}
+/**
+* Runs `write` in a transaction, behind the fence check when it carries a
+* fence.
+*/
+function withRunFence(db, claimsTable, fence, operation, write) {
+	return db.tx(async (client) => {
+		if (fence) await assertRunFence(client, claimsTable, fence, operation);
+		return write(client);
+	});
+}
+/**
+* Runs a transaction that creates or updates a run's claim row, retrying when
+* two first claims race to insert it. `FOR UPDATE` locks nothing while the row
+* is missing, so racing first claims both insert; the second waits on the
+* primary key and fails once the first commits. On retry the row exists and
+* the claim serializes behind its row lock. A deadlock is retried too.
+*/
+async function claimTransaction(db, fn) {
+	for (let attempt = 1;; attempt++) try {
+		return await db.tx((client) => fn(client));
+	} catch (error) {
+		const retryable = isOracleErrorCode(error, [ORA_UNIQUE_CONSTRAINT, ORA_DEADLOCK]);
+		if (attempt >= MAX_CLAIM_ATTEMPTS || !retryable) throw error;
+	}
+}
+//#endregion
 //#region src/storage/domains/memory/utils.ts
 const STORE_NAME$5 = "ORACLEDB";
 const EMPTY_STRING_SENTINEL = "__MASTRA_ORACLE_EMPTY_STRING__";
@@ -3417,6 +3470,14 @@ const STRING_SENTINEL_ESCAPE_PREFIX = "__MASTRA_ORACLE_ESCAPED__";
 function table(ctx, tableName) {
 	return qualifyName(tableName, ctx.schemaName);
 }
+/**
+* The fence check for a memory write; call it first inside the write's
+* transaction. `fence` is the one `MemoryOracle` already resolved against the
+* run fence scope, so an unfenced write skips the check.
+*/
+async function assertMemoryFence(ctx, client, fence, operation) {
+	if (fence) await assertRunFence(client, table(ctx, TABLE_MEMORY_RUN_FENCES), fence, operation);
+}
 function storageError$1(operation, reason, details, cause, category = ErrorCategory.THIRD_PARTY) {
 	return createOracleStorageError({
 		storeName: STORE_NAME$5,
@@ -3974,7 +4035,7 @@ async function listMessagesByResourceId(ctx, args) {
 		orderBy
 	});
 }
-async function saveMessages(ctx, { messages }) {
+async function saveMessages(ctx, { messages, fence }) {
 	if (messages.length === 0) return { messages: [] };
 	const threadIds = /* @__PURE__ */ new Set();
 	try {
@@ -3984,6 +4045,7 @@ async function saveMessages(ctx, { messages }) {
 		}
 		for (const threadId of threadIds) if (!await ctx.getThreadById({ threadId })) throw storageError$1("SAVE_MESSAGES", "FAILED", { threadId }, /* @__PURE__ */ new Error(`Thread ${threadId} not found`), ErrorCategory.USER);
 		await ctx.db.tx(async (client) => {
+			await assertMemoryFence(ctx, client, fence, "saveMessages");
 			await insertMessageBatch(ctx, client, messages);
 		});
 		return { messages: new MessageList().add(messages, "memory").get.all.db() };
@@ -4061,7 +4123,7 @@ async function insertMessageBatch(ctx, client, messages) {
 		threadId: messageThreadId
 	})));
 }
-async function updateMessages(ctx, { messages }) {
+async function updateMessages(ctx, { messages, fence }) {
 	if (messages.length === 0) return [];
 	const messageIds = messages.map((message) => message.id);
 	const existingMessages = (await ctx.listMessagesById({ messageIds })).messages;
@@ -4070,6 +4132,7 @@ async function updateMessages(ctx, { messages }) {
 	const threadIdsToUpdate = /* @__PURE__ */ new Set();
 	try {
 		await ctx.db.tx(async (client) => {
+			await assertMemoryFence(ctx, client, fence, "updateMessages");
 			const semanticRecallMessageIds = [];
 			for (const updatePayload of messages) {
 				const existing = existingById.get(updatePayload.id);
@@ -4116,13 +4179,15 @@ async function updateMessages(ctx, { messages }) {
 		});
 		return (await ctx.listMessagesById({ messageIds })).messages;
 	} catch (error) {
+		if (error instanceof MastraError) throw error;
 		throw storageError$1("UPDATE_MESSAGES", "FAILED", { messageIds: messageIds.join(",") }, error);
 	}
 }
-async function deleteMessages(ctx, messageIds) {
+async function deleteMessages(ctx, messageIds, fence) {
 	if (!messageIds.length) return;
 	try {
 		await ctx.db.tx(async (client) => {
+			await assertMemoryFence(ctx, client, fence, "deleteMessages");
 			const threadIds = /* @__PURE__ */ new Set();
 			for (const [chunkIndex, chunk] of chunkValues(messageIds).entries()) {
 				const { sql, binds } = inClause(`messageId${chunkIndex}`, chunk);
@@ -4138,6 +4203,7 @@ async function deleteMessages(ctx, messageIds) {
 			})));
 		});
 	} catch (error) {
+		if (error instanceof MastraError) throw error;
 		throw storageError$1("DELETE_MESSAGES", "FAILED", { messageIds: messageIds.join(",") }, error);
 	}
 }
@@ -4519,9 +4585,10 @@ async function insertObservationalMemoryRecord(ctx, record) {
 		}, error);
 	}
 }
-async function updateActiveObservations(ctx, input) {
+async function updateActiveObservations(ctx, input, fence) {
 	try {
-		return await ctx.db.tx(async (_client, connection) => {
+		return await ctx.db.tx(async (client, connection) => {
+			await assertMemoryFence(ctx, client, fence, "commitActiveObservations");
 			const row = await lockOMRow(ctx, connection, input.id, "UPDATE_ACTIVE_OBSERVATIONS");
 			if (row.supersededBy) return {
 				applied: false,
@@ -4558,10 +4625,11 @@ async function updateActiveObservations(ctx, input) {
 		throw storageError$1("UPDATE_ACTIVE_OBSERVATIONS", "FAILED", { id: input.id }, error);
 	}
 }
-async function createReflectionGeneration(ctx, input) {
+async function createReflectionGeneration(ctx, input, fence) {
 	const { currentRecord } = input;
 	try {
-		return await ctx.db.tx(async (_client, connection) => {
+		return await ctx.db.tx(async (client, connection) => {
+			await assertMemoryFence(ctx, client, fence, "createReflectionGeneration");
 			const row = await findOMRowForUpdate(ctx, connection, currentRecord.id);
 			if (!row) return currentRecord;
 			if (row.supersededBy) return parseOMRow(await resolveLiveOMRow(ctx, connection, row));
@@ -4969,9 +5037,10 @@ async function resolveLiveOMRow(ctx, connection, row) {
 }
 //#endregion
 //#region src/storage/domains/memory/observational-buffering.ts
-async function updateBufferedObservations(ctx, input) {
+async function updateBufferedObservations(ctx, input, fence) {
 	try {
-		return await ctx.db.tx(async (_client, connection) => {
+		return await ctx.db.tx(async (client, connection) => {
+			await assertMemoryFence(ctx, client, fence, "appendBufferedObservations");
 			const row = await resolveLiveOMRow(ctx, connection, await lockOMRow(ctx, connection, input.id, "UPDATE_BUFFERED_OBSERVATIONS"));
 			const existingChunks = parseBufferedChunks(row.bufferedObservationChunks);
 			if (existingChunks.some((existing) => existing.cycleId === input.chunk.cycleId) || isBufferedChunkCoveredByCursor(input.chunk.lastObservedAt, row.lastObservedAt)) return {
@@ -5014,9 +5083,10 @@ async function updateBufferedObservations(ctx, input) {
 		throw storageError$1("UPDATE_BUFFERED_OBSERVATIONS", "FAILED", { id: input.id }, error);
 	}
 }
-async function swapBufferedToActive(ctx, input) {
+async function swapBufferedToActive(ctx, input, fence) {
 	try {
-		return await ctx.db.tx(async (_client, connection) => {
+		return await ctx.db.tx(async (client, connection) => {
+			await assertMemoryFence(ctx, client, fence, "swapBufferedToActive");
 			const row = await lockOMRow(ctx, connection, input.id, "SWAP_BUFFERED_TO_ACTIVE");
 			if (row.supersededBy) return {
 				...emptySwapResult(),
@@ -5061,9 +5131,10 @@ async function swapBufferedToActive(ctx, input) {
 		throw storageError$1("SWAP_BUFFERED_TO_ACTIVE", "FAILED", { id: input.id }, error);
 	}
 }
-async function updateBufferedReflection(ctx, input) {
+async function updateBufferedReflection(ctx, input, fence) {
 	try {
-		await ctx.db.tx(async (_client, connection) => {
+		await ctx.db.tx(async (client, connection) => {
+			await assertMemoryFence(ctx, client, fence, "updateBufferedReflection");
 			assertRowsAffected((await connection.execute(`UPDATE ${table(ctx, TABLE_OBSERVATIONAL_MEMORY)}
            SET ${OM_BUFFERED_REFLECTION} = CASE
                  WHEN ${OM_BUFFERED_REFLECTION} IS NOT NULL AND DBMS_LOB.GETLENGTH(${OM_BUFFERED_REFLECTION}) > 0
@@ -5088,10 +5159,11 @@ async function updateBufferedReflection(ctx, input) {
 		throw storageError$1("UPDATE_BUFFERED_REFLECTION", "FAILED", { id: input.id }, error);
 	}
 }
-async function swapBufferedReflectionToActive(ctx, input) {
+async function swapBufferedReflectionToActive(ctx, input, fence) {
 	const { currentRecord } = input;
 	try {
-		return await ctx.db.tx(async (_client, connection) => {
+		return await ctx.db.tx(async (client, connection) => {
+			await assertMemoryFence(ctx, client, fence, "swapBufferedReflectionToActive");
 			const row = await findOMRowForUpdate(ctx, connection, currentRecord.id);
 			if (!row) return currentRecord;
 			if (row.supersededBy) return parseOMRow(await resolveLiveOMRow(ctx, connection, row));
@@ -5244,17 +5316,24 @@ async function saveResource(ctx, { resource }) {
 		throw storageError$1("SAVE_RESOURCE", "FAILED", { resourceId: resource.id }, error);
 	}
 }
-async function updateResource(ctx, { resourceId, workingMemory, metadata }) {
+async function updateResource(ctx, { resourceId, workingMemory, metadata, fence }) {
 	const existing = await ctx.getResourceById({ resourceId });
-	if (!existing) return ctx.saveResource({ resource: {
+	const newResource = () => ({
 		id: resourceId,
 		workingMemory,
 		metadata: metadata ?? {},
 		createdAt: /* @__PURE__ */ new Date(),
 		updatedAt: /* @__PURE__ */ new Date()
-	} });
+	});
+	if (!existing && !fence) return ctx.saveResource({ resource: newResource() });
 	try {
-		return await ctx.db.tx(async (_client, connection) => {
+		return await ctx.db.tx(async (client, connection) => {
+			await assertMemoryFence(ctx, client, fence, "updateResource");
+			if (!existing) {
+				const resource = newResource();
+				await mergeResourceRow(ctx, connection, resource);
+				return resource;
+			}
 			const row = rows(await connection.execute(`${resourceSelect()} FROM ${table(ctx, TABLE_RESOURCES)} WHERE id = :resourceId FOR UPDATE`, { resourceId }, executeOptions()))[0];
 			const locked = row ? parseResource(row) : existing;
 			const updated = {
@@ -5348,11 +5427,15 @@ async function getThreadById(ctx, { threadId, resourceId }) {
 		throw storageError$1("GET_THREAD_BY_ID", "FAILED", { threadId }, error);
 	}
 }
-async function saveThread(ctx, { thread }) {
+async function saveThread(ctx, { thread, fence }) {
 	try {
-		await mergeThreadRow(ctx, ctx.db, thread);
+		await ctx.db.tx(async (client) => {
+			await assertMemoryFence(ctx, client, fence, "saveThread");
+			await mergeThreadRow(ctx, client, thread);
+		});
 		return thread;
 	} catch (error) {
+		if (error instanceof MastraError) throw error;
 		throw storageError$1("SAVE_THREAD", "FAILED", { threadId: thread.id }, error);
 	}
 }
@@ -5437,7 +5520,7 @@ async function insertThreadRow(ctx, client, thread) {
 		updatedAt: thread.updatedAt ?? /* @__PURE__ */ new Date()
 	});
 }
-async function updateThread(ctx, { id, title, metadata }) {
+async function updateThread(ctx, { id, title, metadata, fence }) {
 	const existingThread = await ctx.getThreadById({ threadId: id });
 	if (!existingThread) throw storageError$1("UPDATE_THREAD", "FAILED", {
 		threadId: id,
@@ -5449,16 +5532,19 @@ async function updateThread(ctx, { id, title, metadata }) {
 	};
 	const updatedAt = /* @__PURE__ */ new Date();
 	try {
-		await ctx.db.none(`
-          UPDATE ${table(ctx, TABLE_THREADS)}
-          SET title = COALESCE(:title, title),
-              metadata = :metadata,
-              ${THREAD_UPDATED_AT} = :updatedAt
-          WHERE id = :id`, {
-			id,
-			title: optionalStringBind(title),
-			metadata: jsonBind(mergedMetadata),
-			updatedAt
+		await ctx.db.tx(async (client) => {
+			await assertMemoryFence(ctx, client, fence, "updateThread");
+			await client.none(`
+            UPDATE ${table(ctx, TABLE_THREADS)}
+            SET title = COALESCE(:title, title),
+                metadata = :metadata,
+                ${THREAD_UPDATED_AT} = :updatedAt
+            WHERE id = :id`, {
+				id,
+				title: optionalStringBind(title),
+				metadata: jsonBind(mergedMetadata),
+				updatedAt
+			});
 		});
 		const updatedThread = await ctx.getThreadById({ threadId: id });
 		if (!updatedThread) throw storageError$1("UPDATE_THREAD", "FAILED", {
@@ -5610,7 +5696,8 @@ var MemoryOracle = class MemoryOracle extends MemoryStorage {
 		TABLE_THREADS,
 		TABLE_MESSAGES,
 		TABLE_RESOURCES,
-		TABLE_OBSERVATIONAL_MEMORY
+		TABLE_OBSERVATIONAL_MEMORY,
+		TABLE_MEMORY_RUN_FENCES
 	];
 	db;
 	schemaName;
@@ -5648,6 +5735,10 @@ var MemoryOracle = class MemoryOracle extends MemoryStorage {
 	}
 	async init() {
 		await initMemorySchema(this.ctx);
+		await this.db.createTable({
+			tableName: TABLE_MEMORY_RUN_FENCES,
+			schema: RUN_FENCING_TABLE_SCHEMAS[TABLE_MEMORY_RUN_FENCES]
+		});
 	}
 	/**
 	* Mark observational memory rows that are not their key's canonical head as superseded.
@@ -5660,15 +5751,61 @@ var MemoryOracle = class MemoryOracle extends MemoryStorage {
 	}
 	async dangerouslyClearAll() {
 		await clearAllMemoryTables(this.ctx);
+		await this.db.clearTable(TABLE_MEMORY_RUN_FENCES);
+	}
+	supportsRunFencing() {
+		return true;
+	}
+	async raiseRunFence(fence) {
+		const fences = table(this.ctx, TABLE_MEMORY_RUN_FENCES);
+		try {
+			return await claimTransaction(this.db, async (client) => {
+				const row = await client.oneOrNone(`SELECT generation AS "generation", "ownerId" FROM ${fences} WHERE "runId" = :runId FOR UPDATE`, { runId: fence.runId });
+				const binds = {
+					runId: fence.runId,
+					generation: fence.generation,
+					ownerId: fence.ownerId
+				};
+				if (!row) {
+					await client.none(`INSERT INTO ${fences} ("runId", generation, "ownerId") VALUES (:runId, :generation, :ownerId)`, binds);
+					return true;
+				}
+				const generation = Number(row.generation);
+				if (!(generation < fence.generation) && !(generation === fence.generation && String(row.ownerId) === fence.ownerId)) return false;
+				await client.none(`UPDATE ${fences} SET generation = :generation, "ownerId" = :ownerId, "retiredAt" = NULL WHERE "runId" = :runId`, binds);
+				return true;
+			});
+		} catch (error) {
+			throw storageError$1("RAISE_RUN_FENCE", "FAILED", { runId: fence.runId }, error);
+		}
+	}
+	async retireRunFence(fence) {
+		const fences = table(this.ctx, TABLE_MEMORY_RUN_FENCES);
+		try {
+			return await this.db.tx(async (client) => {
+				const row = await client.oneOrNone(`SELECT generation AS "generation", "ownerId" FROM ${fences} WHERE "runId" = :runId FOR UPDATE`, { runId: fence.runId });
+				if (!row || Number(row.generation) !== fence.generation || String(row.ownerId) !== fence.ownerId) return false;
+				await client.none(`UPDATE ${fences} SET "retiredAt" = ${DB_NOW_MS} WHERE "runId" = :runId`, { runId: fence.runId });
+				return true;
+			});
+		} catch (error) {
+			throw storageError$1("RETIRE_RUN_FENCE", "FAILED", { runId: fence.runId }, error);
+		}
 	}
 	async getThreadById(args) {
 		return getThreadById(this.ctx, args);
 	}
-	async saveThread(args) {
-		return saveThread(this.ctx, args);
+	async saveThread({ fence, ...args }) {
+		return saveThread(this.ctx, {
+			...args,
+			fence: resolveRunFence(this, fence)
+		});
 	}
-	async updateThread(args) {
-		return updateThread(this.ctx, args);
+	async updateThread({ fence, ...args }) {
+		return updateThread(this.ctx, {
+			...args,
+			fence: resolveRunFence(this, fence)
+		});
 	}
 	async deleteThread(args) {
 		return deleteThread(this.ctx, args);
@@ -5688,14 +5825,20 @@ var MemoryOracle = class MemoryOracle extends MemoryStorage {
 	async listMessagesByResourceId(args) {
 		return listMessagesByResourceId(this.ctx, args);
 	}
-	async saveMessages(args) {
-		return saveMessages(this.ctx, args);
+	async saveMessages({ fence, ...args }) {
+		return saveMessages(this.ctx, {
+			...args,
+			fence: resolveRunFence(this, fence)
+		});
 	}
-	async updateMessages(args) {
-		return updateMessages(this.ctx, args);
+	async updateMessages({ fence, ...args }) {
+		return updateMessages(this.ctx, {
+			...args,
+			fence: resolveRunFence(this, fence)
+		});
 	}
-	async deleteMessages(messageIds) {
-		return deleteMessages(this.ctx, messageIds);
+	async deleteMessages(messageIds, options) {
+		return deleteMessages(this.ctx, messageIds, resolveRunFence(this, options?.fence));
 	}
 	async getResourceById(args) {
 		return getResourceById(this.ctx, args);
@@ -5703,8 +5846,11 @@ var MemoryOracle = class MemoryOracle extends MemoryStorage {
 	async saveResource(args) {
 		return saveResource(this.ctx, args);
 	}
-	async updateResource(args) {
-		return updateResource(this.ctx, args);
+	async updateResource({ fence, ...args }) {
+		return updateResource(this.ctx, {
+			...args,
+			fence: resolveRunFence(this, fence)
+		});
 	}
 	async cloneThread(args) {
 		const sourceThread = await this.getThreadById({ threadId: args.sourceThreadId });
@@ -5797,10 +5943,10 @@ var MemoryOracle = class MemoryOracle extends MemoryStorage {
 		assertActiveObservationsApplied(await this.commitActiveObservations(input), input.id);
 	}
 	async commitActiveObservations(input) {
-		return updateActiveObservations(this.ctx, input);
+		return updateActiveObservations(this.ctx, input, resolveRunFence(this, void 0));
 	}
 	async createReflectionGeneration(input) {
-		return createReflectionGeneration(this.ctx, input);
+		return createReflectionGeneration(this.ctx, input, resolveRunFence(this, void 0));
 	}
 	async setReflectingFlag(id, isReflecting) {
 		return setReflectingFlag(this.ctx, id, isReflecting);
@@ -5827,16 +5973,16 @@ var MemoryOracle = class MemoryOracle extends MemoryStorage {
 		await this.appendBufferedObservations(input);
 	}
 	async appendBufferedObservations(input) {
-		return updateBufferedObservations(this.ctx, input);
+		return updateBufferedObservations(this.ctx, input, resolveRunFence(this, void 0));
 	}
 	async swapBufferedToActive(input) {
-		return swapBufferedToActive(this.ctx, input);
+		return swapBufferedToActive(this.ctx, input, resolveRunFence(this, void 0));
 	}
 	async updateBufferedReflection(input) {
-		return updateBufferedReflection(this.ctx, input);
+		return updateBufferedReflection(this.ctx, input, resolveRunFence(this, void 0));
 	}
 	async swapBufferedReflectionToActive(input) {
-		return swapBufferedReflectionToActive(this.ctx, input);
+		return swapBufferedReflectionToActive(this.ctx, input, resolveRunFence(this, void 0));
 	}
 };
 //#endregion
@@ -8181,8 +8327,19 @@ const STORE_NAME$1 = "ORACLEDB";
 const WORKFLOW_CREATED_AT = "\"createdAt\"";
 const WORKFLOW_UPDATED_AT = "\"updatedAt\"";
 const WORKFLOW_RESOURCE_ID = "\"resourceId\"";
+const RUN_OWNER_COLUMNS = `generation AS "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 WorkflowsOracle = class WorkflowsOracle extends WorkflowsStorage {
-	static MANAGED_TABLES = [TABLE_WORKFLOW_SNAPSHOT];
+	static MANAGED_TABLES = [TABLE_WORKFLOW_SNAPSHOT, TABLE_WORKFLOW_RUN_OWNERS];
 	db;
 	schemaName;
 	skipDefaultIndexes;
@@ -8203,10 +8360,114 @@ var WorkflowsOracle = class WorkflowsOracle extends WorkflowsStorage {
 	}
 	async dangerouslyClearAll() {
 		await this.db.clearTable(TABLE_WORKFLOW_SNAPSHOT);
+		await this.db.clearTable(TABLE_WORKFLOW_RUN_OWNERS);
+	}
+	supportsRunFencing() {
+		return true;
+	}
+	async claimRunOwnership({ runId, ownerId, leaseMs, force, expectedGeneration }) {
+		const table = this.runOwnersTable();
+		try {
+			return await claimTransaction(this.db, async (client) => {
+				const existing = await client.oneOrNone(`SELECT generation AS "generation" FROM ${table} WHERE "runId" = :runId FOR UPDATE`, { runId });
+				if (!existing) {
+					if (expectedGeneration !== void 0 && expectedGeneration !== 0) return {
+						acquired: false,
+						record: null
+					};
+					await client.none(`INSERT INTO ${table} ("runId", generation, "ownerId", "leaseExpiresAt", "updatedAt")
+             VALUES (:runId, ${DB_NOW_MS}, :ownerId, ${DB_NOW_MS} + :leaseMs, ${DB_NOW_MS})`, {
+						runId,
+						ownerId,
+						leaseMs
+					});
+					return {
+						acquired: true,
+						record: await this.readRunOwner(client, runId)
+					};
+				}
+				await client.none(`UPDATE ${table}
+           SET generation = generation + 1, "ownerId" = :ownerId, "leaseExpiresAt" = ${DB_NOW_MS} + :leaseMs,
+               "updatedAt" = ${DB_NOW_MS}
+           WHERE "runId" = :runId
+             AND (:expectedGeneration IS NULL OR generation = :expectedGeneration)
+             AND (:force = 1 OR "leaseExpiresAt" IS NULL OR "leaseExpiresAt" <= ${DB_NOW_MS})`, {
+					runId,
+					ownerId,
+					leaseMs,
+					expectedGeneration: expectedGeneration ?? null,
+					force: force === true ? 1 : 0
+				});
+				const record = await this.readRunOwner(client, runId);
+				return record && record.generation === Number(existing.generation) + 1 ? {
+					acquired: true,
+					record
+				} : {
+					acquired: false,
+					record
+				};
+			});
+		} catch (error) {
+			throw this.storageError("CLAIM_RUN_OWNERSHIP", "FAILED", { runId }, error);
+		}
+	}
+	async renewRunOwnership({ leaseMs, ...fence }) {
+		try {
+			return await this.db.tx(async (client) => {
+				await client.none(`UPDATE ${this.runOwnersTable()}
+           SET "leaseExpiresAt" = ${DB_NOW_MS} + :leaseMs, "updatedAt" = ${DB_NOW_MS}
+           WHERE "runId" = :runId AND generation = :generation AND "ownerId" = :ownerId
+             AND "leaseExpiresAt" IS NOT NULL`, {
+					runId: fence.runId,
+					generation: fence.generation,
+					ownerId: fence.ownerId,
+					leaseMs
+				});
+				const record = await this.readRunOwner(client, fence.runId);
+				return record !== null && record.generation === fence.generation && record.ownerId === fence.ownerId && record.leaseExpiresAt !== null ? {
+					renewed: true,
+					record
+				} : {
+					renewed: false,
+					record
+				};
+			});
+		} catch (error) {
+			throw this.storageError("RENEW_RUN_OWNERSHIP", "FAILED", { runId: fence.runId }, error);
+		}
 	}
-	async updateWorkflowResults({ workflowName, runId, stepId, result, requestContext, state }) {
+	async releaseRunOwnership(fence) {
 		try {
 			return await this.db.tx(async (client) => {
+				await client.none(`UPDATE ${this.runOwnersTable()} SET "leaseExpiresAt" = NULL, "updatedAt" = ${DB_NOW_MS}
+           WHERE "runId" = :runId AND generation = :generation AND "ownerId" = :ownerId`, {
+					runId: fence.runId,
+					generation: fence.generation,
+					ownerId: fence.ownerId
+				});
+				const record = await this.readRunOwner(client, fence.runId);
+				return record !== null && record.generation === fence.generation && record.ownerId === fence.ownerId;
+			});
+		} catch (error) {
+			throw this.storageError("RELEASE_RUN_OWNERSHIP", "FAILED", { runId: fence.runId }, error);
+		}
+	}
+	async getRunOwnership({ runId }) {
+		try {
+			return await this.readRunOwner(this.db, runId);
+		} catch (error) {
+			throw this.storageError("GET_RUN_OWNERSHIP", "FAILED", { runId }, error);
+		}
+	}
+	async readRunOwner(client, runId) {
+		const row = await client.oneOrNone(`SELECT ${RUN_OWNER_COLUMNS} FROM ${this.runOwnersTable()} WHERE "runId" = :runId`, { runId });
+		return row ? toRunOwnershipRecord(runId, row) : null;
+	}
+	async updateWorkflowResults({ workflowName, runId, stepId, result, requestContext, state, fence: explicitFence }) {
+		const fence = resolveRunFence(this, explicitFence, runId);
+		try {
+			return await this.db.tx(async (client) => {
+				if (fence) await assertRunFence(client, this.runOwnersTable(), fence, "updateWorkflowResults");
 				await this.ensureWorkflowRunRow(client, workflowName, runId);
 				const existing = await client.one(`SELECT snapshot AS "snapshot", ${WORKFLOW_RESOURCE_ID} AS "resourceId" FROM ${this.table()} WHERE workflow_name = :workflowName AND run_id = :runId FOR UPDATE`, {
 					workflowName,
@@ -8230,6 +8491,7 @@ var WorkflowsOracle = class WorkflowsOracle extends WorkflowsStorage {
 				return snapshot.context;
 			});
 		} catch (error) {
+			if (isRunFenceConflictError(error)) throw error;
 			throw this.storageError("UPDATE_WORKFLOW_RESULTS", "FAILED", {
 				workflowName,
 				runId,
@@ -8237,9 +8499,11 @@ var WorkflowsOracle = class WorkflowsOracle extends WorkflowsStorage {
 			}, error);
 		}
 	}
-	async updateWorkflowState({ workflowName, runId, opts }) {
+	async updateWorkflowState({ workflowName, runId, opts, fence: explicitFence }) {
+		const fence = resolveRunFence(this, explicitFence, runId);
 		try {
 			return await this.db.tx(async (client) => {
+				if (fence) await assertRunFence(client, this.runOwnersTable(), fence, "updateWorkflowState");
 				const existing = await client.oneOrNone(`SELECT snapshot AS "snapshot" FROM ${this.table()} WHERE workflow_name = :workflowName AND run_id = :runId FOR UPDATE`, {
 					workflowName,
 					runId
@@ -8262,24 +8526,26 @@ var WorkflowsOracle = class WorkflowsOracle extends WorkflowsStorage {
 				return updatedSnapshot;
 			});
 		} catch (error) {
+			if (isRunFenceConflictError(error)) throw error;
 			throw this.storageError("UPDATE_WORKFLOW_STATE", "FAILED", {
 				workflowName,
 				runId
 			}, error);
 		}
 	}
-	async persistWorkflowSnapshot({ workflowName, runId, resourceId, snapshot, createdAt, updatedAt }) {
+	async persistWorkflowSnapshot({ workflowName, runId, resourceId, snapshot, createdAt, updatedAt, fence }) {
 		try {
 			const now = /* @__PURE__ */ new Date();
-			await this.db.none(this.workflowMergeSql(), {
+			await withRunFence(this.db, this.runOwnersTable(), resolveRunFence(this, fence, runId), "persistWorkflowSnapshot", (client) => client.none(this.workflowMergeSql(), {
 				workflowName,
 				runId,
 				resourceId: resourceId ?? null,
 				snapshot: jsonBind(snapshot),
 				createdAt: createdAt ?? now,
 				updatedAt: updatedAt ?? now
-			});
+			}));
 		} catch (error) {
+			if (isRunFenceConflictError(error)) throw error;
 			throw this.storageError("PERSIST_WORKFLOW_SNAPSHOT", "FAILED", {
 				workflowName,
 				runId
@@ -8343,13 +8609,14 @@ var WorkflowsOracle = class WorkflowsOracle extends WorkflowsStorage {
 			}, error);
 		}
 	}
-	async deleteWorkflowRunById({ runId, workflowName }) {
+	async deleteWorkflowRunById({ runId, workflowName, fence }) {
 		try {
-			await this.db.none(`DELETE FROM ${this.table()} WHERE workflow_name = :workflowName AND run_id = :runId`, {
+			await withRunFence(this.db, this.runOwnersTable(), resolveRunFence(this, fence, runId), "deleteWorkflowRunById", (client) => client.none(`DELETE FROM ${this.table()} WHERE workflow_name = :workflowName AND run_id = :runId`, {
 				workflowName,
 				runId
-			});
+			}));
 		} catch (error) {
+			if (isRunFenceConflictError(error)) throw error;
 			throw this.storageError("DELETE_WORKFLOW_RUN_BY_ID", "FAILED", {
 				runId,
 				workflowName
@@ -8368,6 +8635,10 @@ var WorkflowsOracle = class WorkflowsOracle extends WorkflowsStorage {
         CONSTRAINT ${this.constraint("MASTRA_WORKFLOW_SNAPSHOT_PK")} PRIMARY KEY (workflow_name, run_id)
       )`, [-955]);
 		await this.db.executeDdl(`ALTER TABLE ${this.table()} ADD (${WORKFLOW_RESOURCE_ID} VARCHAR2(512))`, [-1430]);
+		await this.db.createTable({
+			tableName: TABLE_WORKFLOW_RUN_OWNERS,
+			schema: RUN_FENCING_TABLE_SCHEMAS[TABLE_WORKFLOW_RUN_OWNERS]
+		});
 	}
 	async createIndexes() {
 		await this.db.withConnection(async (connection) => {
@@ -8505,6 +8776,9 @@ var WorkflowsOracle = class WorkflowsOracle extends WorkflowsStorage {
 	table() {
 		return qualifyName(TABLE_WORKFLOW_SNAPSHOT, this.schemaName);
 	}
+	runOwnersTable() {
+		return qualifyName(TABLE_WORKFLOW_RUN_OWNERS, this.schemaName);
+	}
 	indexName(indexName) {
 		return indexNameForTable(indexName, "IDX");
 	}