@mastra/pg 1.31.0-alpha.2 → 1.31.0-alpha.4

package/dist/index.js

@@ -1,18 +1,18 @@
 import { ErrorCategory, ErrorDomain, MastraError } from "@mastra/core/error";
 import * as coreStorage from "@mastra/core/storage";
-import { AgentsStorage, BRANCH_SPAN_TYPES, BackgroundTasksStorage, BlobStore, ChannelsStorage, DATASETS_SCHEMA, DATASET_ITEMS_SCHEMA, DATASET_VERSIONS_SCHEMA, DatasetsStorage, EXPERIMENTS_SCHEMA, EXPERIMENT_RESULTS_SCHEMA, EntityType, ExperimentsStorage, FactoryStorage, FavoritesStorage, KNOWLEDGE_ACTIVITY_SCHEMA, KNOWLEDGE_CURSORS_SCHEMA, KNOWLEDGE_MENTIONS_SCHEMA, KNOWLEDGE_NODES_SCHEMA, KNOWLEDGE_RECORDS_SCHEMA, KNOWLEDGE_SEMANTIC_OUTBOX_SCHEMA, KnowledgeConflictError, KnowledgeNotFoundError, KnowledgeStorage, MCPClientsStorage, MCPServersStorage, METRIC_DISTINCT_COLUMNS, MastraCompositeStore, MemoryStorage, NotificationsStorage, OBSERVATIONAL_MEMORY_TABLE_SCHEMA, ObservabilityStorage, PromptBlocksStorage, SchedulesStorage, ScorerDefinitionsStorage, ScoresStorage, SkillsStorage, TABLE_AGENTS, TABLE_AGENT_VERSIONS, TABLE_BACKGROUND_TASKS, TABLE_CHANNEL_CONFIG, TABLE_CHANNEL_INSTALLATIONS, TABLE_CONFIGS, TABLE_DATASETS, TABLE_DATASET_ITEMS, TABLE_DATASET_VERSIONS, TABLE_EXPERIMENTS, TABLE_EXPERIMENT_RESULTS, TABLE_FAVORITES, 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, ThreadStateStorage, ToolProviderConnectionsStorage, TraceStatus, UniqueViolationError, WorkflowDefinitionsStorage, WorkflowsStorage, WorkspacesStorage, assertKnowledgeCeilingRaised, assertKnowledgeScopeWithinCeiling, calculatePagination, canonicalizeKnowledgeScope, createKnowledgeUlid, createStorageErrorId, createVectorErrorId, ensureDate, executeRetentionPrune, getDefaultValue, getSqlType, hasErrorCode, isKnowledgeScopeVisible, knowledgeScopeKey, knowledgeSemanticDocumentId, knowledgeSemanticIdempotencyKey, listBranchesArgsSchema, listFeedbackArgsSchema, listLogsArgsSchema, listMetricsArgsSchema, listScoresArgsSchema, listTracesArgsSchema, matchesExpectedWorkflowStatus, mergeWorkflowStepResult, normalizePerPage, normalizeScheduleTarget, parseDuration, parseKnowledgeNodeCursor, parseKnowledgeWikilinks, resolveListOrderBy, resolveRetentionTargets, retentionCutoffMs, runRetentionBatches, safelyParseJSON, storageMessageMatchesMetadataFilter, toTraceSpans, transformScoreRow, validateStorageMetadataFilter } from "@mastra/core/storage";
+import { AgentsStorage, BRANCH_SPAN_TYPES, BackgroundTasksStorage, BlobStore, ChannelsStorage, DATASETS_SCHEMA, DATASET_ITEMS_SCHEMA, DATASET_VERSIONS_SCHEMA, DatasetsStorage, EXPERIMENTS_SCHEMA, EXPERIMENT_RESULTS_SCHEMA, EntityType, ExperimentsStorage, FactoryStorage, FavoritesStorage, KNOWLEDGE_SEMANTIC_OUTBOX_SCHEMA, KnowledgeConflictError, KnowledgeNotFoundError, KnowledgeStorage, MCPClientsStorage, MCPServersStorage, METRIC_DISTINCT_COLUMNS, MastraCompositeStore, MemoryStorage, NotificationsStorage, OBSERVATIONAL_MEMORY_TABLE_SCHEMA, ObservabilityStorage, PromptBlocksStorage, RUN_FENCING_TABLE_SCHEMAS, RunFenceConflictError, SchedulesStorage, ScorerDefinitionsStorage, ScoresStorage, SkillsStorage, TABLE_AGENTS, TABLE_AGENT_VERSIONS, TABLE_BACKGROUND_TASKS, TABLE_CHANNEL_CONFIG, TABLE_CHANNEL_INSTALLATIONS, TABLE_CONFIGS, TABLE_DATASETS, TABLE_DATASET_ITEMS, TABLE_DATASET_VERSIONS, TABLE_EXPERIMENTS, TABLE_EXPERIMENT_RESULTS, TABLE_FAVORITES, 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, ThreadStateStorage, ToolProviderConnectionsStorage, TraceStatus, UniqueViolationError, WorkflowDefinitionsStorage, WorkflowsStorage, WorkspacesStorage, calculatePagination, canonicalizeKnowledgeScope, createKnowledgeUlid, createStorageErrorId, createVectorErrorId, ensureDate, executeRetentionPrune, getDefaultValue, getSqlType, hasErrorCode, isKnowledgeScopeVisible, isRunFenceConflictError, knowledgeScopeKey, knowledgeSemanticDocumentId, knowledgeSemanticIdempotencyKey, listBranchesArgsSchema, listFeedbackArgsSchema, listLogsArgsSchema, listMetricsArgsSchema, listScoresArgsSchema, listTracesArgsSchema, matchesExpectedWorkflowStatus, matchesRunFence, mergeWorkflowStepResult, normalizePerPage, normalizeScheduleTarget, parseDuration, parseKnowledgeNodeCursor, parseKnowledgeWikilinks, resolveListOrderBy, resolveRetentionTargets, resolveRunFence, retentionCutoffMs, runRetentionBatches, safelyParseJSON, storageMessageMatchesMetadataFilter, toTraceSpans, transformScoreRow, validateStorageMetadataFilter } from "@mastra/core/storage";
 import { parseFieldKey, parseSqlIdentifier } from "@mastra/core/utils";
 import { MastraVector, validateTopK, validateUpsertInput } from "@mastra/core/vector";
 import { Mutex } from "async-mutex";
 import * as pg$1 from "pg";
-import pg, { Pool } from "pg";
+import pg, { Pool, defaults } from "pg";
 import xxhash from "xxhash-wasm";
 import { parse } from "pg-connection-string";
 import { BaseFilterTranslator } from "@mastra/core/vector/filter";
 import { MastraBase } from "@mastra/core/base";
-import { createHash } from "crypto";
-import { MessageList } from "@mastra/core/agent";
+import { createHash, 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";
 import { isDeepStrictEqual } from "util";
@@ -3189,9 +3189,10 @@ var PgDB = class extends MastraBase {
 		}
 		await flush();
 	}
-	async insert({ tableName, record }) {
+	/** `client` lets a caller run the insert inside its own transaction. */
+	async insert({ tableName, record }, client = this.client) {
 		try {
-			await this.executeInsert(this.client, {
+			await this.executeInsert(client, {
 				tableName,
 				record
 			});
@@ -4025,13 +4026,15 @@ MIGRATION REQUIRED: Duplicate spans detected in ${duplicateInfo.tableName}\n====
 			indexName: tableName,
 			schemaName: getSchemaName$6(this.schemaName)
 		});
+		const parsedColumn = `"${parseSqlIdentifier(column, "column name")}"`;
 		const sql = `
       DELETE FROM ${fullTableName}
       WHERE ctid IN (
         SELECT ctid FROM ${fullTableName}
-        WHERE ${`"${parseSqlIdentifier(column, "column name")}"`} < $1
+        WHERE ${parsedColumn} < $1
         LIMIT $2
       )
+      AND ${parsedColumn} < $1
     `;
 		return (await this.client.query(sql, [cutoff, limit])).rowCount ?? 0;
 	}
@@ -4494,6 +4497,7 @@ var AgentsPG = class AgentsPG extends AgentsStorage {
 	}
 	async create(input) {
 		const { agent } = input;
+		let draftInserted = false;
 		try {
 			const agentsTable = getTableName$5({
 				indexName: TABLE_AGENTS,
@@ -4520,6 +4524,7 @@ var AgentsPG = class AgentsPG extends AgentsStorage {
 				nowIso,
 				nowIso
 			]);
+			draftInserted = true;
 			const { id: _id, authorId: _authorId, visibility: _visibility, metadata: _metadata, ...snapshotConfig } = agent;
 			const versionId = crypto.randomUUID();
 			await this.createVersion({
@@ -4542,14 +4547,14 @@ var AgentsPG = class AgentsPG extends AgentsStorage {
 				updatedAt: now
 			};
 		} catch (error) {
-			if (error instanceof MastraError) throw error;
-			try {
+			if (draftInserted) try {
 				const agentsTable = getTableName$5({
 					indexName: TABLE_AGENTS,
 					schemaName: getSchemaName$5(this.#schema)
 				});
 				await this.#db.client.none(`DELETE FROM ${agentsTable} WHERE id = $1 AND status = 'draft' AND "activeVersionId" IS NULL`, [agent.id]);
 			} catch {}
+			if (error instanceof MastraError) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("PG", "CREATE_AGENT", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -8277,18 +8282,650 @@ var FavoritesPG = class FavoritesPG extends FavoritesStorage {
 	}
 };
 //#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 camelCaseColumns = [
 	"canonicalName",
@@ -8299,7 +8936,6 @@ const camelCaseColumns = [
 	"node",
 	"sourceThreadId",
 	"capturedAt",
-	"maxScope",
 	"deletedAt",
 	"deletedBy",
 	"sourceType",
@@ -8313,7 +8949,30 @@ const camelCaseColumns = [
 	"availableAt",
 	"claimedAt",
 	"claimedBy",
-	"completedAt"
+	"completedAt",
+	"isScope",
+	"nodeId",
+	"targetNodeId",
+	"scopeNodeId",
+	"scopeRefId",
+	"canSuggest",
+	"schemaVersion",
+	"importerId",
+	"importKind",
+	"triggerKind",
+	"transcriptThreadId",
+	"traceId",
+	"queuedAt",
+	"startedAt",
+	"targetType",
+	"targetId",
+	"contextScopeId",
+	"importRunId",
+	"proposerContextScopeId",
+	"expectedVersion",
+	"reviewerContextScopeId",
+	"reviewedAt",
+	"addedAt"
 ];
 function transformSqlCode(sql, transform) {
 	return sql.split(/('(?:''|[^'])*')/g).map((part, index) => index % 2 === 0 ? transform(part) : part).join("");
@@ -8328,14 +8987,7 @@ function postgresSql(sql, schemaName) {
 		const quotedSchema = `"${parseSchemaName(schemaName)}"`;
 		normalized = transformSqlCode(normalized, (code) => {
 			let transformed = code;
-			for (const table of [
-				TABLE_KNOWLEDGE_NODES,
-				TABLE_KNOWLEDGE_RECORDS,
-				TABLE_KNOWLEDGE_MENTIONS,
-				TABLE_KNOWLEDGE_CURSORS,
-				TABLE_KNOWLEDGE_ACTIVITY,
-				TABLE_KNOWLEDGE_SEMANTIC_OUTBOX
-			]) transformed = transformed.replaceAll(`"${table}"`, `${quotedSchema}."${table}"`);
+			for (const table of [...KNOWLEDGE_TABLE_NAMES, ...RETIRED_KNOWLEDGE_TABLE_NAMES]) transformed = transformed.replaceAll(`"${table}"`, `${quotedSchema}."${table}"`);
 			return transformed;
 		});
 	}
@@ -8343,17 +8995,35 @@ function postgresSql(sql, schemaName) {
 	return transformSqlCode(normalized, (code) => code.replace(/\?/g, () => `$${++index}`));
 }
 function createExecutor(client, schemaName) {
-	return { async execute(statement) {
+	const execute = async (statement, qualifyWithSchema) => {
 		const sql = typeof statement === "string" ? statement : statement.sql;
 		const args = typeof statement === "string" ? [] : statement.args ?? [];
-		const result = await client.query(postgresSql(sql, schemaName), args);
+		const result = await client.query(postgresSql(sql, qualifyWithSchema ? schemaName : void 0), args);
 		return {
 			rows: result.rows,
 			rowsAffected: result.rowCount ?? 0
 		};
-	} };
+	};
+	return {
+		execute: (statement) => execute(statement, true),
+		executeRaw: (statement) => execute(statement, false)
+	};
 }
-const visibleSql = `(scopeKey = ? OR LEFT(?, LENGTH(scopeKey) + 1) = scopeKey || chr(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$1(value) {
 	if (typeof value === "string") return JSON.parse(value);
 	if (value instanceof Uint8Array) return JSON.parse(new TextDecoder().decode(value));
@@ -8393,9 +9063,10 @@ function parseNode(row) {
 		id: String(row.id),
 		type: "node",
 		name: String(row.name),
-		kind: String(row.kind),
+		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$1(row.scopeJson ?? row.scope),
 		version: Number(row.version),
 		mergedInto: row.mergedInto == null ? void 0 : String(row.mergedInto),
@@ -8412,7 +9083,6 @@ function parseKnowledge(row) {
 		sourceThreadId: String(row.sourceThreadId),
 		capturedAt: toDate$1(row.capturedAt),
 		when: optionalDate(row.when),
-		maxScope: row.maxScope == null ? void 0 : String(row.maxScope),
 		metadata: row.metadata == null ? void 0 : parseJson$1(row.metadata),
 		deletedAt: optionalDate(row.deletedAt),
 		deletedBy: row.deletedBy == null ? void 0 : String(row.deletedBy)
@@ -8449,6 +9119,10 @@ function knowledgeIndexes(schemaName) {
 			name: "idx_knowledge_nodes_scope",
 			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_nodes_scope ON ${table(TABLE_KNOWLEDGE_NODES)} ("scopeKey", "type");`
 		},
+		{
+			name: "idx_knowledge_nodes_name",
+			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_nodes_name ON ${table(TABLE_KNOWLEDGE_NODES)} ("type", "canonicalName");`
+		},
 		{
 			name: "idx_knowledge_records_node_latest",
 			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_records_node_latest ON ${table(TABLE_KNOWLEDGE_RECORDS)} ("node", "id" DESC);`
@@ -8465,6 +9139,14 @@ function knowledgeIndexes(schemaName) {
 			name: "idx_knowledge_activity_latest",
 			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_activity_latest ON ${table(TABLE_KNOWLEDGE_ACTIVITY)} ("id" DESC);`
 		},
+		{
+			name: "idx_knowledge_records_scope",
+			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_records_scope ON ${table(TABLE_KNOWLEDGE_RECORDS)} ("scopeKey", "id");`
+		},
+		{
+			name: "idx_knowledge_activity_scope",
+			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_activity_scope ON ${table(TABLE_KNOWLEDGE_ACTIVITY)} ("scopeKey", "id" DESC);`
+		},
 		{
 			name: "idx_knowledge_outbox_idempotency",
 			sql: `CREATE UNIQUE INDEX IF NOT EXISTS idx_knowledge_outbox_idempotency ON ${table(TABLE_KNOWLEDGE_SEMANTIC_OUTBOX)} ("idempotencyKey");`
@@ -8472,67 +9154,152 @@ function knowledgeIndexes(schemaName) {
 		{
 			name: "idx_knowledge_outbox_claim",
 			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_outbox_claim ON ${table(TABLE_KNOWLEDGE_SEMANTIC_OUTBOX)} ("status", "availableAt", "createdAt");`
+		},
+		{
+			name: "idx_knowledge_node_scopes_scope",
+			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_node_scopes_scope ON ${table(TABLE_KNOWLEDGE_NODE_SCOPES)} ("scopeNodeId", "nodeId");`
+		},
+		{
+			name: "idx_knowledge_record_scopes_scope",
+			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_record_scopes_scope ON ${table(TABLE_KNOWLEDGE_RECORD_SCOPES)} ("scopeNodeId", "recordId");`
+		},
+		{
+			name: "idx_knowledge_scope_grants_ref",
+			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_scope_grants_ref ON ${table(TABLE_KNOWLEDGE_SCOPE_GRANTS)} ("scopeRefId", "scopeNodeId");`
+		},
+		{
+			name: "idx_knowledge_node_addresses_node",
+			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_node_addresses_node ON ${table(TABLE_KNOWLEDGE_NODE_ADDRESSES)} ("nodeId");`
+		},
+		{
+			name: "idx_knowledge_import_runs_lookup",
+			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_import_runs_lookup ON ${table(TABLE_KNOWLEDGE_IMPORT_RUNS)} ("importerId", "binding", "queuedAt" DESC);`
+		},
+		{
+			name: "idx_knowledge_activity_import_run",
+			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_activity_import_run ON ${table(TABLE_KNOWLEDGE_ACTIVITY)} ("importRunId", "id" DESC);`
 		}
 	];
 }
 function knowledgeIndexDDL(schemaName) {
 	return knowledgeIndexes(schemaName).map((index) => index.sql);
 }
+const KNOWLEDGE_CURATION_CURSOR_REMOVED_MESSAGE = "Knowledge curation cursors were removed: observation-time curate is the only Knowledge writer and needs no cursor.";
+const knowledgeTableDefinitions = [
+	{
+		tableName: TABLE_KNOWLEDGE_NODES,
+		schema: KNOWLEDGE_V2_NODES_SCHEMA
+	},
+	{
+		tableName: TABLE_KNOWLEDGE_RECORDS,
+		schema: KNOWLEDGE_V2_RECORDS_SCHEMA
+	},
+	{
+		tableName: TABLE_KNOWLEDGE_MENTIONS,
+		schema: KNOWLEDGE_V2_MENTIONS_SCHEMA,
+		compositePrimaryKey: ["recordId", "sourceId"]
+	},
+	{
+		tableName: TABLE_KNOWLEDGE_NODE_SCOPES,
+		schema: KNOWLEDGE_NODE_SCOPES_SCHEMA,
+		compositePrimaryKey: ["nodeId", "scopeNodeId"]
+	},
+	{
+		tableName: TABLE_KNOWLEDGE_RECORD_SCOPES,
+		schema: KNOWLEDGE_RECORD_SCOPES_SCHEMA,
+		compositePrimaryKey: ["recordId", "scopeNodeId"]
+	},
+	{
+		tableName: TABLE_KNOWLEDGE_SCOPE_GRANTS,
+		schema: KNOWLEDGE_SCOPE_GRANTS_SCHEMA,
+		compositePrimaryKey: ["scopeNodeId", "scopeRefId"]
+	},
+	{
+		tableName: TABLE_KNOWLEDGE_ACCESS_STATE,
+		schema: KNOWLEDGE_ACCESS_STATE_SCHEMA
+	},
+	{
+		tableName: TABLE_KNOWLEDGE_SCOPE_ADDRESSES,
+		schema: KNOWLEDGE_SCOPE_ADDRESSES_SCHEMA
+	},
+	{
+		tableName: TABLE_KNOWLEDGE_NODE_ADDRESSES,
+		schema: KNOWLEDGE_NODE_ADDRESSES_SCHEMA,
+		compositePrimaryKey: ["source", "address"]
+	},
+	{
+		tableName: TABLE_KNOWLEDGE_IMPORT_STATE,
+		schema: KNOWLEDGE_IMPORT_STATE_SCHEMA,
+		compositePrimaryKey: [
+			"importerId",
+			"binding",
+			"key"
+		]
+	},
+	{
+		tableName: TABLE_KNOWLEDGE_IMPORT_RUNS,
+		schema: KNOWLEDGE_IMPORT_RUNS_SCHEMA
+	},
+	{
+		tableName: TABLE_KNOWLEDGE_PROPOSALS,
+		schema: KNOWLEDGE_PROPOSALS_SCHEMA
+	},
+	{
+		tableName: TABLE_KNOWLEDGE_ACTIVITY,
+		schema: KNOWLEDGE_V2_ACTIVITY_SCHEMA
+	},
+	{
+		tableName: TABLE_KNOWLEDGE_SEMANTIC_OUTBOX,
+		schema: KNOWLEDGE_SEMANTIC_OUTBOX_SCHEMA
+	}
+];
+function pgSetting(config, key) {
+	const value = config[key] || process.env[`PG${key.toUpperCase()}`] || defaults[key];
+	return value === void 0 || value === null || value === "" ? void 0 : String(value);
+}
+function effectivePgTarget(config) {
+	const host = pgSetting(config, "host");
+	const database = pgSetting(config, "database") ?? pgSetting(config, "user");
+	if (!host || !database) return void 0;
+	return `${host.startsWith("/") ? host : host.toLocaleLowerCase()}:${pgSetting(config, "port") ?? "5432"}/${database}`;
+}
+function canonicalPgTarget(config) {
+	if (config.connectionString) try {
+		const parsed = new URL(config.connectionString);
+		return effectivePgTarget({
+			host: decodeURIComponent(parsed.hostname) || config.host,
+			port: parsed.port || config.port,
+			database: decodeURIComponent(parsed.pathname.slice(1)) || config.database,
+			user: decodeURIComponent(parsed.username) || config.user
+		});
+	} catch {
+		return config.connectionString;
+	}
+	return effectivePgTarget(config);
+}
+function pgSourceConfig(source) {
+	if (!source || !("options" in source)) return void 0;
+	return source.options;
+}
+function pgClientPool(client) {
+	if (!client || !("$pool" in client)) return void 0;
+	return client.$pool;
+}
+function getPgKnowledgeIsolationKey(config) {
+	const schema = config.schemaName ?? "public";
+	const poolConfig = pgSourceConfig(config.pool ?? pgClientPool(config.client));
+	const target = Boolean(config.connectionString || config.host || config.database) ? canonicalPgTarget(config) : poolConfig ? canonicalPgTarget(poolConfig) : void 0;
+	if (target) return `pg:${target}:schema:${schema}`;
+	return `pg:unidentified:schema:${schema}`;
+}
 var KnowledgePG = class extends KnowledgeStorage {
-	static MANAGED_TABLES = [
-		TABLE_KNOWLEDGE_NODES,
-		TABLE_KNOWLEDGE_RECORDS,
-		TABLE_KNOWLEDGE_MENTIONS,
-		TABLE_KNOWLEDGE_CURSORS,
-		TABLE_KNOWLEDGE_ACTIVITY,
-		TABLE_KNOWLEDGE_SEMANTIC_OUTBOX
-	];
+	static MANAGED_TABLES = KNOWLEDGE_TABLE_NAMES;
 	static getExportDDL(schemaName) {
-		return [
-			generateTableSQL({
-				tableName: TABLE_KNOWLEDGE_NODES,
-				schema: KNOWLEDGE_NODES_SCHEMA,
-				schemaName,
-				includeAllConstraints: true
-			}),
-			generateTableSQL({
-				tableName: TABLE_KNOWLEDGE_RECORDS,
-				schema: KNOWLEDGE_RECORDS_SCHEMA,
-				schemaName,
-				includeAllConstraints: true
-			}),
-			generateTableSQL({
-				tableName: TABLE_KNOWLEDGE_MENTIONS,
-				schema: KNOWLEDGE_MENTIONS_SCHEMA,
-				schemaName,
-				compositePrimaryKey: [
-					"sourceType",
-					"sourceId",
-					"recordId"
-				],
-				includeAllConstraints: true
-			}),
-			generateTableSQL({
-				tableName: TABLE_KNOWLEDGE_CURSORS,
-				schema: KNOWLEDGE_CURSORS_SCHEMA,
-				schemaName,
-				compositePrimaryKey: ["sourceThreadId", "agent"],
-				includeAllConstraints: true
-			}),
-			generateTableSQL({
-				tableName: TABLE_KNOWLEDGE_ACTIVITY,
-				schema: KNOWLEDGE_ACTIVITY_SCHEMA,
-				schemaName,
-				includeAllConstraints: true
-			}),
-			generateTableSQL({
-				tableName: TABLE_KNOWLEDGE_SEMANTIC_OUTBOX,
-				schema: KNOWLEDGE_SEMANTIC_OUTBOX_SCHEMA,
-				schemaName,
-				includeAllConstraints: true
-			}),
-			...knowledgeIndexDDL(schemaName)
-		];
+		return [...knowledgeTableDefinitions.map((definition) => generateTableSQL({
+			...definition,
+			schemaName,
+			includeAllConstraints: true
+		})), ...knowledgeIndexDDL(schemaName)];
 	}
 	#client;
 	#executor;
@@ -8541,7 +9308,7 @@ var KnowledgePG = class extends KnowledgeStorage {
 	#db;
 	#schemaName;
 	constructor(config) {
-		super();
+		super({ storageIsolationKey: config.storageIsolationKey ?? getPgKnowledgeIsolationKey(config) });
 		const { client, readClient, schemaName, skipDefaultIndexes } = resolvePgConfig(config);
 		this.#client = client;
 		this.#schemaName = schemaName;
@@ -8554,55 +9321,358 @@ var KnowledgePG = class extends KnowledgeStorage {
 			skipDefaultIndexes
 		});
 	}
-	async init() {
-		await this.#db.createTable({
-			tableName: TABLE_KNOWLEDGE_NODES,
-			schema: KNOWLEDGE_NODES_SCHEMA
-		});
-		await this.#db.alterTable({
-			tableName: TABLE_KNOWLEDGE_NODES,
-			schema: KNOWLEDGE_NODES_SCHEMA,
-			ifNotExists: ["description"]
+	getCapabilities() {
+		return {
+			contractVersion: 2,
+			schemaVersion: 2,
+			supportsV2: true,
+			supportsSchemaInspection: true,
+			supportsExplicitReset: true
+		};
+	}
+	async inspectSchema() {
+		const { inspectKnowledgeSchema } = await loadKnowledgeV2Core();
+		try {
+			const snapshot = getSchemaSnapshot(this.#client, this.#schemaName);
+			if (snapshot) {
+				const tableNames = KNOWLEDGE_TABLE_NAMES.filter((table) => snapshot.tables.has(table));
+				return this.#classifySchema(this.#executor, tableNames, snapshot.columns);
+			}
+			return this.#inspectSchemaWithExecutor(this.#executor);
+		} catch (error) {
+			return inspectKnowledgeSchema({
+				available: false,
+				tableNames: [],
+				reason: error instanceof Error ? error.message : String(error)
+			});
+		}
+	}
+	async #inspectSchemaWithExecutor(executor) {
+		const tableNames = (await executor.execute({
+			sql: `SELECT table_name FROM information_schema.tables WHERE table_schema = COALESCE(?, current_schema()) AND table_name = ANY(?::text[])`,
+			args: [this.#schemaName ?? null, [...KNOWLEDGE_TABLE_NAMES]]
+		})).rows.map((row) => String(row.table_name));
+		const columnResult = await executor.execute({
+			sql: `SELECT table_name, column_name FROM information_schema.columns WHERE table_schema = COALESCE(?, current_schema()) AND table_name = ANY(?::text[])`,
+			args: [this.#schemaName ?? null, [...KNOWLEDGE_TABLE_NAMES]]
+		});
+		const columns = /* @__PURE__ */ new Map();
+		for (const row of columnResult.rows) {
+			const table = String(row.table_name);
+			const names = columns.get(table) ?? /* @__PURE__ */ new Set();
+			names.add(String(row.column_name));
+			columns.set(table, names);
+		}
+		return this.#classifySchema(executor, tableNames, columns);
+	}
+	async #classifySchema(executor, tableNames, columns) {
+		const { inspectKnowledgeSchema } = await loadKnowledgeV2Core();
+		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 { tableName: table, schema } of knowledgeTableDefinitions) {
+			const actual = columns.get(table) ?? /* @__PURE__ */ new Set();
+			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
 		});
-		await this.#db.createTable({
-			tableName: TABLE_KNOWLEDGE_RECORDS,
-			schema: KNOWLEDGE_RECORDS_SCHEMA
+	}
+	async init() {
+		await this.#transaction(async (tx) => {
+			await tx.execute({
+				sql: "SELECT pg_advisory_xact_lock(hashtext(?))",
+				args: [`mastra-knowledge-v2:${this.#schemaName ?? "current_schema"}`]
+			});
+			const { assertKnowledgeSchemaCompatible } = await loadKnowledgeV2Core();
+			let inspection = await this.#inspectSchemaWithExecutor(tx);
+			if (inspection.status === "incompatible-reset-required" && await this.#isPublishedV1Layout(tx)) {
+				const tables = [...RETIRED_KNOWLEDGE_TABLE_NAMES, ...[...KNOWLEDGE_TABLE_NAMES].reverse()].map((table) => `"${table}"`).join(", ");
+				await tx.execute(`DROP TABLE IF EXISTS ${tables}`);
+				inspection = await this.#inspectSchemaWithExecutor(tx);
+			}
+			assertKnowledgeSchemaCompatible(inspection);
+			for (const definition of knowledgeTableDefinitions) await tx.executeRaw(generateTableSQL({
+				...definition,
+				schemaName: this.#schemaName,
+				includeAllConstraints: true
+			}));
+			for (const index of knowledgeIndexes(this.#schemaName)) await tx.executeRaw(index.sql);
+			await tx.execute({
+				sql: `INSERT INTO "${TABLE_KNOWLEDGE_ACCESS_STATE}" (id, epoch, schemaVersion) VALUES ('global', 0, ?) ON CONFLICT (id) DO NOTHING`,
+				args: [2]
+			});
 		});
-		await this.#db.createTable({
-			tableName: TABLE_KNOWLEDGE_MENTIONS,
-			schema: KNOWLEDGE_MENTIONS_SCHEMA,
-			compositePrimaryKey: [
-				"sourceType",
-				"sourceId",
-				"recordId"
+	}
+	/**
+	* 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, extra indexes)
+	* needs an explicit reset.
+	*/
+	async #isPublishedV1Layout(executor) {
+		const schema = this.#schemaName ?? null;
+		const relations = await executor.execute({
+			sql: `SELECT table_name, table_type FROM information_schema.tables WHERE table_schema = COALESCE(?, current_schema()) AND table_name LIKE 'mastra\\_knowledge\\_%'`,
+			args: [schema]
+		});
+		const tables = [];
+		for (const row of relations.rows) {
+			const name = String(row.table_name);
+			if (row.table_type !== "BASE TABLE" || !PUBLISHED_KNOWLEDGE_V1_TABLE_NAMES.has(name)) return false;
+			tables.push(name);
+		}
+		const indexes = await executor.execute({
+			sql: `SELECT indexname FROM pg_indexes WHERE schemaname = COALESCE(?, current_schema()) AND tablename = ANY(?::text[])`,
+			args: [schema, tables]
+		});
+		for (const row of indexes.rows) {
+			const name = String(row.indexname);
+			if (!PUBLISHED_KNOWLEDGE_V1_INDEX_NAMES.has(name) && !name.endsWith("_pkey")) return false;
+		}
+		if ((await executor.execute({
+			sql: `SELECT 1 FROM information_schema.view_table_usage WHERE table_schema = COALESCE(?, current_schema()) AND table_name = ANY(?::text[]) UNION ALL SELECT 1 FROM information_schema.triggers WHERE event_object_schema = COALESCE(?, current_schema()) AND event_object_table = ANY(?::text[]) LIMIT 1`,
+			args: [
+				schema,
+				tables,
+				schema,
+				tables
 			]
+		})).rows.length > 0) 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_PROPOSALS,
+				TABLE_KNOWLEDGE_ACTIVITY,
+				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'`);
 		});
-		await this.#db.createTable({
-			tableName: TABLE_KNOWLEDGE_CURSORS,
-			schema: KNOWLEDGE_CURSORS_SCHEMA,
-			compositePrimaryKey: ["sourceThreadId", "agent"]
-		});
-		await this.#db.createTable({
-			tableName: TABLE_KNOWLEDGE_ACTIVITY,
-			schema: KNOWLEDGE_ACTIVITY_SCHEMA
-		});
-		await this.#db.createTable({
-			tableName: TABLE_KNOWLEDGE_SEMANTIC_OUTBOX,
-			schema: KNOWLEDGE_SEMANTIC_OUTBOX_SCHEMA
+	}
+	async dangerouslyReset() {
+		const tables = [...RETIRED_KNOWLEDGE_TABLE_NAMES, ...[...KNOWLEDGE_TABLE_NAMES].reverse()].map((table) => `"${table}"`).join(", ");
+		await this.#executor.execute(`DROP TABLE IF EXISTS ${tables}`);
+		await this.init();
+	}
+	async reconcileStructure(plan) {
+		return this.#transaction(async (tx) => {
+			await tx.execute({
+				sql: `SELECT pg_advisory_xact_lock(hashtext(?))`,
+				args: [`mastra-knowledge-reconcile:${this.#schemaName}`]
+			});
+			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,?,1,?,?)`,
+					args: [
+						id,
+						scope.name,
+						canonicalName(scope.name),
+						scope.kind ?? null,
+						scope.description ?? null,
+						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 INTO "${TABLE_KNOWLEDGE_NODE_SCOPES}" ("nodeId","scopeNodeId","addedAt") VALUES (?,?,?) ON CONFLICT DO NOTHING`,
+						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 INTO "${TABLE_KNOWLEDGE_SCOPE_GRANTS}" ("scopeNodeId","scopeRefId",role,"canSuggest") VALUES (?,?,?,?) ON CONFLICT DO NOTHING`,
+						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)
+			};
 		});
-		await Promise.all(knowledgeIndexes(this.#schemaName).map((index) => this.#db.createIndexFromStatement(index.name, index.sql)));
 	}
-	async dangerouslyClearAll() {
-		await this.#transaction(async (tx) => {
-			for (const table of [
-				TABLE_KNOWLEDGE_MENTIONS,
-				TABLE_KNOWLEDGE_RECORDS,
-				TABLE_KNOWLEDGE_NODES,
-				TABLE_KNOWLEDGE_CURSORS,
-				TABLE_KNOWLEDGE_ACTIVITY,
-				TABLE_KNOWLEDGE_SEMANTIC_OUTBOX
-			]) await tx.execute(`DELETE FROM "${table}"`);
-		});
+	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 COLLATE \"C\" > ? OR (n.name = ? AND n.id > ?))");
+			args.push(after.name, after.name, after.id);
+		}
+		args.push(limit + 1);
+		const rows = (await this.#readExecutor.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 COLLATE "C", n.id LIMIT ?`,
+			args
+		})).rows;
+		if (rows.length === 0) return {
+			scopes: [],
+			nextCursor: null
+		};
+		const parents = await this.#readExecutor.execute({
+			sql: `SELECT ns."nodeId",ns."scopeNodeId" FROM "${TABLE_KNOWLEDGE_NODE_SCOPES}" ns WHERE ns."nodeId" IN (${rows.map(() => "?").join(",")}) ORDER BY ns."scopeNodeId" COLLATE "C"`,
+			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 = postgresTimestamp(after.updatedAt);
+			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.#readExecutor.execute({
+			sql: `SELECT *, 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);
@@ -8612,6 +9682,7 @@ var KnowledgePG = 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();
@@ -8628,7 +9699,7 @@ var KnowledgePG = 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",
@@ -8644,6 +9715,8 @@ var KnowledgePG = 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);
@@ -8660,13 +9733,13 @@ var KnowledgePG = class extends KnowledgeStorage {
 		return this.#resolveNode(this.#readExecutor, 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))}%`);
@@ -8718,6 +9791,7 @@ var KnowledgePG = 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)) {
@@ -8772,8 +9846,12 @@ var KnowledgePG = 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=?)`,
@@ -8813,10 +9891,10 @@ var KnowledgePG = 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 parent = await this.#resolveTerminalNode(tx, nodeReferenceId(input.node));
 			if (!parent) throw new KnowledgeNotFoundError("node", nodeReferenceId(input.node));
@@ -8829,11 +9907,10 @@ var KnowledgePG = 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,
@@ -8843,10 +9920,12 @@ var KnowledgePG = class extends KnowledgeStorage {
 					record.sourceThreadId,
 					record.capturedAt.toISOString(),
 					record.when?.toISOString() ?? null,
-					record.maxScope ?? null,
-					metadataJson
+					metadataJson,
+					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);
@@ -8873,17 +9952,13 @@ var KnowledgePG = 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.#readExecutor.execute({
-			sql: `SELECT *,scope AS "scopeJson" 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 *,scope AS "scopeJson" 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 {
@@ -8898,10 +9973,11 @@ var KnowledgePG = 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
 				]
 			});
@@ -8920,8 +9996,8 @@ var KnowledgePG = 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);
@@ -8937,15 +10013,17 @@ var KnowledgePG = 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);
@@ -8955,33 +10033,16 @@ var KnowledgePG = 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 scope = canonicalizeKnowledgeScope(input.scope);
-		const key = knowledgeScopeKey(scope);
+		const keys = visibleScopeKeys(scope);
 		const normalizedQuery = input.query.trim().toLocaleLowerCase();
 		if (!normalizedQuery) return [];
 		const query = `%${escapeLikePattern(normalizedQuery)}%`;
 		const results = (await this.#readExecutor.execute({
-			sql: `SELECT *,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 *,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,
@@ -9002,10 +10063,9 @@ var KnowledgePG = class extends KnowledgeStorage {
 		}));
 		if (results.length < (input.limit ?? 20)) {
 			const records = await this.#readExecutor.execute({
-				sql: `SELECT f.*,f.scope AS "scopeJson",r.name,r.scope AS "parentScopeJson" FROM "${TABLE_KNOWLEDGE_RECORDS}" f JOIN "${TABLE_KNOWLEDGE_NODES}" r ON r.id=f.node AND r.type='node' AND r.mergedInto IS NULL WHERE f.deletedAt IS NULL AND ${visibleSql.replaceAll("scopeKey", "f.scopeKey")} AND lower(f.text) LIKE ? ESCAPE '=' ORDER BY f.id DESC LIMIT ?`,
+				sql: `SELECT f.*,f.scope AS "scopeJson",r.name,r.scope AS "parentScopeJson" FROM "${TABLE_KNOWLEDGE_RECORDS}" f JOIN "${TABLE_KNOWLEDGE_NODES}" r ON r.id=f.node AND r.type='node' AND r.mergedInto IS NULL WHERE f.deletedAt IS NULL AND ${visibleSql(keys, "f.scopeKey")} AND lower(f.text) LIKE ? ESCAPE '=' ORDER BY f.id DESC LIMIT ?`,
 				args: [
-					key,
-					key,
+					...keys,
 					query,
 					(input.limit ?? 20) - results.length
 				]
@@ -9015,7 +10075,7 @@ var KnowledgePG = class extends KnowledgeStorage {
 				return {
 					type: "record",
 					id: String(row.id),
-					recordId: String(row.node),
+					recordId: parentVisible ? String(row.node) : String(row.id),
 					name: parentVisible ? String(row.name) : "(private node)",
 					text: String(row.text),
 					scope: parseJson$1(row.scopeJson)
@@ -9024,41 +10084,26 @@ var KnowledgePG = class extends KnowledgeStorage {
 		}
 		return results;
 	}
-	async getCurationCursor(input) {
-		const row = (await this.#executor.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$1(row.updatedAt)
-		} : null;
-	}
-	async advanceCurationCursor(input) {
-		const updatedAt = /* @__PURE__ */ new Date();
-		if ((await this.#executor.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()
-			]
-		})).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.#readExecutor.execute({
-			sql: `SELECT *,scope AS "scopeJson" FROM "${TABLE_KNOWLEDGE_ACTIVITY}" WHERE ${visibleSql}${input.after ? " AND id < ?" : ""} ORDER BY id DESC LIMIT ?`,
+			sql: `SELECT *,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
 			]
@@ -9080,9 +10125,9 @@ var KnowledgePG = 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.#executor.execute({
@@ -9101,9 +10146,9 @@ var KnowledgePG = 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({
@@ -9170,12 +10215,14 @@ var KnowledgePG = 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 *,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;
 	}
@@ -9200,17 +10247,16 @@ var KnowledgePG = class extends KnowledgeStorage {
 		const scope = canonicalizeKnowledgeScope(input.scope);
 		const node = await this.#resolveTerminalNode(this.#readExecutor, nodeReferenceId(input.node));
 		if (!node) return { records: [] };
-		const key = knowledgeScopeKey(scope);
+		const keys = visibleScopeKeys(scope);
 		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 records = (await this.#readExecutor.execute({
-			sql: `SELECT DISTINCT f.*,f.scope AS "scopeJson" FROM "${TABLE_KNOWLEDGE_RECORDS}" f${relationship === "about" ? "" : ` LEFT JOIN "${TABLE_KNOWLEDGE_MENTIONS}" m ON m.sourceType='record' AND m.sourceId=f.id`} WHERE ${relationship === "about" ? "f.node=?" : relationship === "mentioning" ? "m.recordId=?" : "(f.node=? OR m.recordId=?)"} AND ${visibleSql.replaceAll("scopeKey", "f.scopeKey")}${input.includeDeleted ? "" : " AND f.deletedAt IS NULL"}${input.after ? " AND f.id < ?" : ""} ORDER BY f.id DESC LIMIT ?`,
+			sql: `SELECT DISTINCT f.*,f.scope AS "scopeJson" FROM "${TABLE_KNOWLEDGE_RECORDS}" f${relationship === "about" ? "" : ` LEFT JOIN "${TABLE_KNOWLEDGE_MENTIONS}" m ON m.sourceType='record' AND m.sourceId=f.id`} WHERE ${relationship === "about" ? "f.node=?" : relationship === "mentioning" ? "m.recordId=?" : "(f.node=? OR m.recordId=?)"} AND ${visibleSql(keys, "f.scopeKey")}${input.includeDeleted ? "" : " AND f.deletedAt IS NULL"}${input.after ? " AND f.id < ?" : ""} ORDER BY f.id DESC LIMIT ?`,
 			args
 		})).rows.map(parseKnowledge);
 		const limit = input.limit ?? 100;
@@ -9219,6 +10265,90 @@ var KnowledgePG = class extends KnowledgeStorage {
 			nextCursor: records.length > limit ? records[limit - 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 INTO "${TABLE_KNOWLEDGE_NODE_SCOPES}" (nodeId,scopeNodeId,addedAt) VALUES (?,?,?) ON CONFLICT DO NOTHING`,
+			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 INTO "${TABLE_KNOWLEDGE_NODE_SCOPES}" (nodeId,scopeNodeId,addedAt) VALUES (?,?,?) ON CONFLICT DO NOTHING`,
+			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 INTO "${TABLE_KNOWLEDGE_NODE_SCOPES}" ("nodeId","scopeNodeId","addedAt") VALUES (?,?,?) ON CONFLICT DO NOTHING`,
+				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 INTO "${TABLE_KNOWLEDGE_RECORD_SCOPES}" (recordId,scopeNodeId,addedAt) VALUES (?,?,?) ON CONFLICT DO NOTHING`,
+			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=?`,
@@ -9242,7 +10372,7 @@ var KnowledgePG = 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",
@@ -9256,6 +10386,7 @@ var KnowledgePG = 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);
 				}
@@ -9272,13 +10403,17 @@ var KnowledgePG = 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,
@@ -9415,6 +10550,7 @@ var MCPClientsPG = class MCPClientsPG extends MCPClientsStorage {
 	}
 	async create(input) {
 		const { mcpClient } = input;
+		let draftInserted = false;
 		try {
 			const tableName = getTableName$5({
 				indexName: TABLE_MCP_CLIENTS,
@@ -9437,6 +10573,7 @@ var MCPClientsPG = class MCPClientsPG extends MCPClientsStorage {
 				nowIso,
 				nowIso
 			]);
+			draftInserted = true;
 			const { id: _id, authorId: _authorId, metadata: _metadata, ...snapshotConfig } = mcpClient;
 			const versionId = crypto.randomUUID();
 			await this.createVersion({
@@ -9457,7 +10594,7 @@ var MCPClientsPG = class MCPClientsPG extends MCPClientsStorage {
 				updatedAt: now
 			};
 		} catch (error) {
-			try {
+			if (draftInserted) try {
 				const tableName = getTableName$5({
 					indexName: TABLE_MCP_CLIENTS,
 					schemaName: getSchemaName$5(this.#schema)
@@ -9983,6 +11120,7 @@ var MCPServersPG = class MCPServersPG extends MCPServersStorage {
 	}
 	async create(input) {
 		const { mcpServer } = input;
+		let draftInserted = false;
 		try {
 			const tableName = getTableName$5({
 				indexName: TABLE_MCP_SERVERS,
@@ -10004,6 +11142,7 @@ var MCPServersPG = class MCPServersPG extends MCPServersStorage {
 				nowIso,
 				nowIso
 			]);
+			draftInserted = true;
 			const { id: _id, authorId: _authorId, metadata: _metadata, ...snapshotConfig } = mcpServer;
 			const versionId = crypto.randomUUID();
 			await this.createVersion({
@@ -10024,7 +11163,7 @@ var MCPServersPG = class MCPServersPG extends MCPServersStorage {
 				updatedAt: now
 			};
 		} catch (error) {
-			try {
+			if (draftInserted) try {
 				const tableName = getTableName$5({
 					indexName: TABLE_MCP_SERVERS,
 					schemaName: getSchemaName$5(this.#schema)
@@ -10448,6 +11587,38 @@ var MCPServersPG = class MCPServersPG extends MCPServersStorage {
 	}
 };
 //#endregion
+//#region src/storage/db/run-fencing.ts
+/**
+* Epoch milliseconds on the database clock. `clock_timestamp()` rather than
+* `now()`: a statement can wait on a row lock, and lease math must use the
+* time it actually runs, not when its transaction started.
+*/
+const DB_NOW_MS = `(EXTRACT(EPOCH FROM clock_timestamp()) * 1000)::bigint`;
+/**
+* The check half of a fenced write; call it first inside the write's
+* transaction. `FOR SHARE` holds the claim row until commit, so a claim that
+* updates the row waits for the write to finish, and every later write sees
+* the new claim.
+*/
+async function assertRunFence(t, claimsTable, fence, operation) {
+	const row = await t.oneOrNone(`SELECT generation, "ownerId" FROM ${claimsTable} WHERE "runId" = $1 FOR SHARE`, [fence.runId]);
+	if (!matchesRunFence(row && {
+		generation: Number(row.generation),
+		ownerId: row.ownerId
+	}, fence)) throw new RunFenceConflictError(fence, operation);
+}
+/**
+* Runs `write` directly when it carries no fence, or in a transaction behind
+* the fence check when it does.
+*/
+function withRunFence(client, claimsTable, fence, operation, write) {
+	if (!fence) return write(client);
+	return client.tx(async (t) => {
+		await assertRunFence(t, claimsTable, fence, operation);
+		return write(t);
+	});
+}
+//#endregion
 //#region src/storage/domains/memory/index.ts
 /**
 * Local constant for the observational memory table name.
@@ -10548,6 +11719,10 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 	* and are indexed for fast batched deletes. Cascade order is enforced in
 	* `prune()` (children before threads), not here. Observational memory has no
 	* timestamp anchor and is deliberately excluded.
+	*
+	* 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: {
@@ -10564,6 +11739,12 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 			table: TABLE_THREADS,
 			column: "createdAtZ",
 			indexed: true
+		},
+		runFences: {
+			table: TABLE_MEMORY_RUN_FENCES,
+			column: "retiredAt",
+			indexed: true,
+			anchorType: "epoch-ms"
 		}
 	};
 	#db;
@@ -10627,6 +11808,10 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 			});
 			await this.#db.createIndexFromStatement("idx_om_lookup_key", `CREATE INDEX IF NOT EXISTS idx_om_lookup_key ON ${omTableName} ("lookupKey")`);
 		}
+		await this.#db.createTable({
+			tableName: TABLE_MEMORY_RUN_FENCES,
+			schema: RUN_FENCING_TABLE_SCHEMAS[TABLE_MEMORY_RUN_FENCES]
+		});
 		await this.createDefaultIndexes();
 		await this.createCustomIndexes();
 	}
@@ -10704,6 +11889,12 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 			statements.push(`CREATE INDEX IF NOT EXISTS "${idxPrefix}idx_om_lookup_key" ON ${fullOmTableName} ("lookupKey");`);
 		}
 		for (const idx of MemoryPG.getDefaultIndexDefs(schemaPrefix)) statements.push(generateIndexSQL(idx, schemaName));
+		statements.push(generateTableSQL({
+			tableName: TABLE_MEMORY_RUN_FENCES,
+			schema: RUN_FENCING_TABLE_SCHEMAS[TABLE_MEMORY_RUN_FENCES],
+			schemaName,
+			includeAllConstraints: true
+		}));
 		return statements;
 	}
 	/**
@@ -10739,6 +11930,61 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 		await this.#db.clearTable({ tableName: TABLE_MESSAGES });
 		await this.#db.clearTable({ tableName: TABLE_THREADS });
 		await this.#db.clearTable({ tableName: TABLE_RESOURCES });
+		await this.#db.clearTable({ tableName: TABLE_MEMORY_RUN_FENCES });
+	}
+	supportsRunFencing() {
+		return true;
+	}
+	#runFencesTable() {
+		return getTableName$3({
+			indexName: TABLE_MEMORY_RUN_FENCES,
+			schemaName: getSchemaName$3(this.#schema)
+		});
+	}
+	/** Runs `write` behind the run's fence check when it carries a fence. */
+	#fenced(fence, operation, write) {
+		return withRunFence(this.#db.client, this.#runFencesTable(), resolveRunFence(this, fence), operation, write);
+	}
+	async raiseRunFence(fence) {
+		try {
+			return await this.#db.client.oneOrNone(`INSERT INTO ${this.#runFencesTable()} AS f ("runId", generation, "ownerId")
+         VALUES ($1, $2, $3)
+         ON CONFLICT ("runId") DO UPDATE
+           SET generation = EXCLUDED.generation, "ownerId" = EXCLUDED."ownerId", "retiredAt" = NULL
+         WHERE f.generation < EXCLUDED.generation
+            OR (f.generation = EXCLUDED.generation AND f."ownerId" = EXCLUDED."ownerId")
+         RETURNING "runId"`, [
+				fence.runId,
+				fence.generation,
+				fence.ownerId
+			]) !== null;
+		} catch (error) {
+			throw new MastraError({
+				id: createStorageErrorId("PG", "RAISE_RUN_FENCE", "FAILED"),
+				domain: ErrorDomain.STORAGE,
+				category: ErrorCategory.THIRD_PARTY,
+				details: { runId: fence.runId }
+			}, error);
+		}
+	}
+	async retireRunFence(fence) {
+		try {
+			return await this.#db.client.oneOrNone(`UPDATE ${this.#runFencesTable()}
+         SET "retiredAt" = ${DB_NOW_MS}
+         WHERE "runId" = $1 AND generation = $2 AND "ownerId" = $3
+         RETURNING "runId"`, [
+				fence.runId,
+				fence.generation,
+				fence.ownerId
+			]) !== null;
+		} catch (error) {
+			throw new MastraError({
+				id: createStorageErrorId("PG", "RETIRE_RUN_FENCE", "FAILED"),
+				domain: ErrorDomain.STORAGE,
+				category: ErrorCategory.THIRD_PARTY,
+				details: { runId: fence.runId }
+			}, error);
+		}
 	}
 	/**
 	* Deletes rows older than the configured `maxAge` per table, in bounded,
@@ -10759,7 +12005,8 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 			order: [
 				"messages",
 				"resources",
-				"threads"
+				"threads",
+				"runFences"
 			]
 		});
 		const results = await runPrune({
@@ -11017,7 +12264,7 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 			throw mastraError;
 		}
 	}
-	async saveThread({ thread }) {
+	async saveThread({ thread, fence }) {
 		try {
 			const tableName = getTableName$3({
 				indexName: TABLE_THREADS,
@@ -11026,7 +12273,7 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 			const createdAt = toUtcISOString(thread.createdAt);
 			const updatedAt = toUtcISOString(thread.updatedAt);
 			const metadataJson = thread.metadata ? toPgJson(thread.metadata) : null;
-			await this.#db.client.none(`INSERT INTO ${tableName} (
+			await this.#fenced(fence, "saveThread", (q) => q.none(`INSERT INTO ${tableName} (
           id,
           "resourceId",
           title,
@@ -11052,12 +12299,13 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 				createdAt,
 				updatedAt,
 				updatedAt
-			]);
+			]));
 			return {
 				...thread,
 				metadata: metadataJson ? JSON.parse(metadataJson) : thread.metadata
 			};
 		} catch (error) {
+			if (isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("PG", "SAVE_THREAD", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -11066,29 +12314,30 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 			}, error);
 		}
 	}
-	async updateThread({ id, title, metadata }) {
+	async updateThread({ id, title, metadata, fence }) {
 		const threadTableName = getTableName$3({
 			indexName: TABLE_THREADS,
 			schemaName: getSchemaName$3(this.#schema)
 		});
-		const existingThread = await this.#getThreadById(this.#db.client, { threadId: id });
-		if (!existingThread) throw new MastraError({
-			id: createStorageErrorId("PG", "UPDATE_THREAD", "FAILED"),
-			domain: ErrorDomain.STORAGE,
-			category: ErrorCategory.USER,
-			text: `Thread ${id} not found`,
-			details: {
-				threadId: id,
-				title: title ?? null
-			}
-		});
-		const mergedMetadata = {
-			...existingThread.metadata,
-			...metadata
-		};
 		try {
-			const nowStr = toUtcISOString(/* @__PURE__ */ new Date());
-			const thread = await this.#db.client.one(`UPDATE ${threadTableName}
+			return await this.#fenced(fence, "updateThread", async (q) => {
+				const existingThread = await this.#getThreadById(q, { threadId: id });
+				if (!existingThread) throw new MastraError({
+					id: createStorageErrorId("PG", "UPDATE_THREAD", "FAILED"),
+					domain: ErrorDomain.STORAGE,
+					category: ErrorCategory.USER,
+					text: `Thread ${id} not found`,
+					details: {
+						threadId: id,
+						title: title ?? null
+					}
+				});
+				const mergedMetadata = {
+					...existingThread.metadata,
+					...metadata
+				};
+				const nowStr = toUtcISOString(/* @__PURE__ */ new Date());
+				const thread = await q.one(`UPDATE ${threadTableName}
                     SET
                         title = COALESCE($1, title),
                         metadata = $2,
@@ -11097,21 +12346,23 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
                     WHERE id = $5
                     RETURNING *
                 `, [
-				title ?? null,
-				mergedMetadata,
-				nowStr,
-				nowStr,
-				id
-			]);
-			return {
-				id: thread.id,
-				resourceId: thread.resourceId,
-				title: thread.title,
-				metadata: typeof thread.metadata === "string" ? JSON.parse(thread.metadata) : thread.metadata,
-				createdAt: thread.createdAtZ || thread.createdAt,
-				updatedAt: thread.updatedAtZ || thread.updatedAt
-			};
+					title ?? null,
+					mergedMetadata,
+					nowStr,
+					nowStr,
+					id
+				]);
+				return {
+					id: thread.id,
+					resourceId: thread.resourceId,
+					title: thread.title,
+					metadata: typeof thread.metadata === "string" ? JSON.parse(thread.metadata) : thread.metadata,
+					createdAt: thread.createdAtZ || thread.createdAt,
+					updatedAt: thread.updatedAtZ || thread.updatedAt
+				};
+			});
 		} catch (error) {
+			if (error instanceof MastraError || isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("PG", "UPDATE_THREAD", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -11664,8 +12915,9 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 			throw mastraError;
 		}
 	}
-	async saveMessages({ messages }) {
+	async saveMessages({ messages, fence: explicitFence }) {
 		if (messages.length === 0) return { messages: [] };
+		const fence = resolveRunFence(this, explicitFence);
 		const threadId = messages[0]?.threadId;
 		if (!threadId) throw new MastraError({
 			id: createStorageErrorId("PG", "SAVE_MESSAGES", "FAILED"),
@@ -11693,6 +12945,7 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 			});
 			const messagesToSave = dedupeMessagesForSave(messages);
 			await this.#db.client.tx(async (t) => {
+				if (fence) await assertRunFence(t, this.#runFencesTable(), fence, "saveMessages");
 				for (let offset = 0; offset < messagesToSave.length; offset += MAX_MESSAGES_PER_INSERT) {
 					const batch = messagesToSave.slice(offset, offset + MAX_MESSAGES_PER_INSERT);
 					const values = [];
@@ -11739,7 +12992,7 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 			});
 			return { messages: new MessageList().add(messagesWithParsedContent, "memory").get.all.db() };
 		} catch (error) {
-			if (error instanceof MastraError) throw error;
+			if (error instanceof MastraError || isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("PG", "SAVE_MESSAGES", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -11748,8 +13001,9 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 			}, error);
 		}
 	}
-	async updateMessages({ messages }) {
+	async updateMessages({ messages, fence: explicitFence }) {
 		if (messages.length === 0) return [];
+		const fence = resolveRunFence(this, explicitFence);
 		const messageIds = messages.map((m) => m.id);
 		const selectQuery = `SELECT id, content, role, type, "createdAt", "createdAtZ", thread_id AS "threadId", "resourceId" FROM ${getTableName$3({
 			indexName: TABLE_MESSAGES,
@@ -11765,6 +13019,7 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 		});
 		const threadIdsToUpdate = /* @__PURE__ */ new Set();
 		await this.#db.client.tx(async (t) => {
+			if (fence) await assertRunFence(t, this.#runFencesTable(), fence, "updateMessages");
 			const queries = [];
 			const columnMapping = { threadId: "thread_id" };
 			for (const existingMessage of existingMessages) {
@@ -11825,8 +13080,9 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 			return message;
 		});
 	}
-	async deleteMessages(messageIds) {
+	async deleteMessages(messageIds, options) {
 		if (!messageIds || messageIds.length === 0) return;
+		const fence = resolveRunFence(this, options?.fence);
 		try {
 			const messageTableName = getTableName$3({
 				indexName: TABLE_MESSAGES,
@@ -11837,12 +13093,14 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 				schemaName: getSchemaName$3(this.#schema)
 			});
 			await this.#db.client.tx(async (t) => {
+				if (fence) await assertRunFence(t, this.#runFencesTable(), fence, "deleteMessages");
 				const placeholders = messageIds.map((_, idx) => `$${idx + 1}`).join(",");
 				const threadIds = (await t.manyOrNone(`SELECT DISTINCT thread_id FROM ${messageTableName} WHERE id IN (${placeholders})`, messageIds))?.map((msg) => msg.thread_id).filter(Boolean) || [];
 				await t.none(`DELETE FROM ${messageTableName} WHERE id IN (${placeholders})`, messageIds);
 				if (threadIds.length > 0) await t.none(`UPDATE ${threadTableName} SET "updatedAt" = NOW(), "updatedAtZ" = NOW() WHERE id IN (${inPlaceholders(threadIds.length)})`, threadIds);
 			});
 		} catch (error) {
+			if (isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("PG", "DELETE_MESSAGES", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -11870,6 +13128,9 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 		};
 	}
 	async saveResource({ resource }) {
+		return this.#insertResource(this.#db.client, resource);
+	}
+	async #insertResource(q, resource) {
 		const createdAt = toUtcISOString(resource.createdAt);
 		const updatedAt = toUtcISOString(resource.updatedAt);
 		const metadataJson = toPgJson(resource.metadata);
@@ -11881,7 +13142,7 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 				createdAt,
 				updatedAt
 			}
-		});
+		}, q);
 		return {
 			...resource,
 			metadata: metadataJson ? JSON.parse(metadataJson) : resource.metadata
@@ -11892,9 +13153,11 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 			indexName: TABLE_RESOURCES,
 			schemaName: getSchemaName$3(this.#schema)
 		});
+		const fence = resolveRunFence(this, void 0);
 		const callbackError = {};
 		try {
 			return await this.#db.client.tx(async (t) => {
+				if (fence) await assertRunFence(t, this.#runFencesTable(), fence, "mergeResourceWorkingMemory");
 				const now = (/* @__PURE__ */ new Date()).toISOString();
 				await t.none(`INSERT INTO ${tableName} (id, metadata, "createdAt", "createdAtZ", "updatedAt", "updatedAtZ")
          VALUES ($1, $2, $3, $4, $5, $6) ON CONFLICT (id) DO NOTHING`, [
@@ -11938,8 +13201,15 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 			}, error);
 		}
 	}
-	async updateResource({ resourceId, workingMemory, metadata }) {
-		const existingResource = await this.#getResourceById(this.#db.client, resourceId);
+	async updateResource({ resourceId, workingMemory, metadata, fence }) {
+		return this.#fenced(fence, "updateResource", (q) => this.#updateResource(q, {
+			resourceId,
+			workingMemory,
+			metadata
+		}));
+	}
+	async #updateResource(q, { resourceId, workingMemory, metadata }) {
+		const existingResource = await this.#getResourceById(q, resourceId);
 		if (!existingResource) {
 			const newResource = {
 				id: resourceId,
@@ -11948,7 +13218,7 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 				createdAt: /* @__PURE__ */ new Date(),
 				updatedAt: /* @__PURE__ */ new Date()
 			};
-			return this.saveResource({ resource: newResource });
+			return this.#insertResource(q, newResource);
 		}
 		const updatedResource = {
 			...existingResource,
@@ -11984,7 +13254,7 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 		updates.push(`"updatedAtZ" = $${paramIndex++}`);
 		values.push(updatedAtStr);
 		values.push(resourceId);
-		await this.#db.client.none(`UPDATE ${tableName} SET ${updates.join(", ")} WHERE id = $${paramIndex}`, values);
+		await q.none(`UPDATE ${tableName} SET ${updates.join(", ")} WHERE id = $${paramIndex}`, values);
 		return metadataJson ? {
 			...updatedResource,
 			metadata: JSON.parse(metadataJson)
@@ -12123,9 +13393,11 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 	* serializes generation creation across processes instead. It is
 	* transaction-scoped so it also works behind transaction-pooling proxies.
 	*/
-	async #withOMLookupKeyLock(tableName, lookupKey, fn) {
+	async #withOMLookupKeyLock(tableName, lookupKey, fn, fencedOperation) {
+		const fence = fencedOperation ? resolveRunFence(this, void 0) : void 0;
 		return this.#db.client.tx(async (t) => {
 			await t.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [`${tableName}:${lookupKey}`]);
+			if (fence && fencedOperation) await assertRunFence(t, this.#runFencesTable(), fence, fencedOperation);
 			return fn(t);
 		});
 	}
@@ -12422,7 +13694,7 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 			const lastObservedAtStr = input.lastObservedAt.toISOString();
 			const nowStr = now.toISOString();
 			const observedMessageIdsJson = input.observedMessageIds ? toPgJson(input.observedMessageIds) : null;
-			if ((await this.#db.client.query(`UPDATE ${tableName} SET
+			if ((await this.#fenced(void 0, "updateActiveObservations", (q) => q.query(`UPDATE ${tableName} SET
           "activeObservations" = $1,
           "lastObservedAt" = $2,
           "lastObservedAtZ" = $3,
@@ -12442,7 +13714,7 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 				nowStr,
 				nowStr,
 				input.id
-			])).rowCount === 0) throw new MastraError({
+			]))).rowCount === 0) throw new MastraError({
 				id: createStorageErrorId("PG", "UPDATE_ACTIVE_OBSERVATIONS", "NOT_FOUND"),
 				text: `Observational memory record not found: ${input.id}`,
 				domain: ErrorDomain.STORAGE,
@@ -12450,7 +13722,7 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 				details: { id: input.id }
 			});
 		} catch (error) {
-			if (error instanceof MastraError) throw error;
+			if (error instanceof MastraError || isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("PG", "UPDATE_ACTIVE_OBSERVATIONS", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -12470,8 +13742,9 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 				const newer = await this.#getNewerOMGeneration(t, tableName, lookupKey, input.currentRecord.generationCount);
 				if (newer) return newer;
 				return this.#insertReflectionGeneration(t, tableName, lookupKey, input);
-			});
+			}, "createReflectionGeneration");
 		} catch (error) {
+			if (isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("PG", "CREATE_REFLECTION_GENERATION", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -12831,7 +14104,7 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 				extractionFailures: input.chunk.extractionFailures
 			};
 			const lastBufferedAtTime = input.lastBufferedAtTime ? input.lastBufferedAtTime.toISOString() : null;
-			if ((await this.#db.client.query(`UPDATE ${tableName} SET
+			if ((await this.#fenced(void 0, "updateBufferedObservations", (q) => q.query(`UPDATE ${tableName} SET
           "bufferedObservationChunks" = CASE
             WHEN EXISTS (
               SELECT 1
@@ -12850,7 +14123,7 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 				nowStr,
 				nowStr,
 				input.id
-			])).rowCount === 0) throw new MastraError({
+			]))).rowCount === 0) throw new MastraError({
 				id: createStorageErrorId("PG", "UPDATE_BUFFERED_OBSERVATIONS", "NOT_FOUND"),
 				text: `Observational memory record not found: ${input.id}`,
 				domain: ErrorDomain.STORAGE,
@@ -12858,7 +14131,7 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 				details: { id: input.id }
 			});
 		} catch (error) {
-			if (error instanceof MastraError) throw error;
+			if (error instanceof MastraError || isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("PG", "UPDATE_BUFFERED_OBSERVATIONS", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -12940,7 +14213,7 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 			const lastObservedAt = input.lastObservedAt ?? (latestChunk?.lastObservedAt ? new Date(latestChunk.lastObservedAt) : /* @__PURE__ */ new Date());
 			const lastObservedAtStr = lastObservedAt.toISOString();
 			const boundary = `\n\n--- message boundary (${lastObservedAt.toISOString()}) ---\n\n`;
-			if ((await this.#db.client.query(`UPDATE ${tableName} SET
+			if ((await this.#fenced(void 0, "swapBufferedToActive", (q) => q.query(`UPDATE ${tableName} SET
           "activeObservations" = CASE
             WHEN "activeObservations" IS NOT NULL AND "activeObservations" != ''
             THEN "activeObservations" || $10 || $1
@@ -12966,7 +14239,7 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 				nowStr,
 				input.id,
 				boundary
-			])).rowCount === 0) return {
+			]))).rowCount === 0) return {
 				chunksActivated: 0,
 				messageTokensActivated: 0,
 				observationTokensActivated: 0,
@@ -12994,7 +14267,7 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 				currentTask: latestChunkHints?.currentTask ?? void 0
 			};
 		} catch (error) {
-			if (error instanceof MastraError) throw error;
+			if (error instanceof MastraError || isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("PG", "SWAP_BUFFERED_TO_ACTIVE", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -13010,7 +14283,7 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 				schemaName: getSchemaName$3(this.#schema)
 			});
 			const nowStr = (/* @__PURE__ */ new Date()).toISOString();
-			if ((await this.#db.client.query(`UPDATE ${tableName} SET
+			if ((await this.#fenced(void 0, "updateBufferedReflection", (q) => q.query(`UPDATE ${tableName} SET
           "bufferedReflection" = CASE 
             WHEN "bufferedReflection" IS NOT NULL AND "bufferedReflection" != '' 
             THEN "bufferedReflection" || E'\\n\\n' || $1
@@ -13029,7 +14302,7 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 				nowStr,
 				nowStr,
 				input.id
-			])).rowCount === 0) throw new MastraError({
+			]))).rowCount === 0) throw new MastraError({
 				id: createStorageErrorId("PG", "UPDATE_BUFFERED_REFLECTION", "NOT_FOUND"),
 				text: `Observational memory record not found: ${input.id}`,
 				domain: ErrorDomain.STORAGE,
@@ -13037,7 +14310,7 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 				details: { id: input.id }
 			});
 		} catch (error) {
-			if (error instanceof MastraError) throw error;
+			if (error instanceof MastraError || isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("PG", "UPDATE_BUFFERED_REFLECTION", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -13094,9 +14367,9 @@ var MemoryPG = class MemoryPG extends MemoryStorage {
 					input.currentRecord.id
 				]);
 				return newRecord;
-			});
+			}, "swapBufferedReflectionToActive");
 		} catch (error) {
-			if (error instanceof MastraError) throw error;
+			if (error instanceof MastraError || isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("PG", "SWAP_BUFFERED_REFLECTION_TO_ACTIVE", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -20092,6 +21365,7 @@ var PromptBlocksPG = class PromptBlocksPG extends PromptBlocksStorage {
 	}
 	async create(input) {
 		const { promptBlock } = input;
+		let draftInserted = false;
 		try {
 			const tableName = getTableName$5({
 				indexName: TABLE_PROMPT_BLOCKS,
@@ -20113,6 +21387,7 @@ var PromptBlocksPG = class PromptBlocksPG extends PromptBlocksStorage {
 				nowIso,
 				nowIso
 			]);
+			draftInserted = true;
 			const { id: _id, authorId: _authorId, metadata: _metadata, ...snapshotConfig } = promptBlock;
 			const versionId = crypto.randomUUID();
 			await this.createVersion({
@@ -20133,14 +21408,14 @@ var PromptBlocksPG = class PromptBlocksPG extends PromptBlocksStorage {
 				updatedAt: now
 			};
 		} catch (error) {
-			if (error instanceof MastraError) throw error;
-			try {
+			if (draftInserted) try {
 				const tableName = getTableName$5({
 					indexName: TABLE_PROMPT_BLOCKS,
 					schemaName: getSchemaName$5(this.#schema)
 				});
 				await this.#db.client.none(`DELETE FROM ${tableName} WHERE id = $1 AND status = 'draft' AND "activeVersionId" IS NULL`, [promptBlock.id]);
 			} catch {}
+			if (error instanceof MastraError) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("PG", "CREATE_PROMPT_BLOCK", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -21036,6 +22311,7 @@ var ScorerDefinitionsPG = class ScorerDefinitionsPG extends ScorerDefinitionsSto
 	}
 	async create(input) {
 		const { scorerDefinition } = input;
+		let draftInserted = false;
 		try {
 			const tableName = getTableName$5({
 				indexName: TABLE_SCORER_DEFINITIONS,
@@ -21059,6 +22335,7 @@ var ScorerDefinitionsPG = class ScorerDefinitionsPG extends ScorerDefinitionsSto
 				nowIso,
 				nowIso
 			]);
+			draftInserted = true;
 			const { id: _id, authorId: _authorId, organizationId: _organizationId, projectId: _projectId, metadata: _metadata, ...snapshotConfig } = scorerDefinition;
 			const versionId = crypto.randomUUID();
 			await this.createVersion({
@@ -21081,7 +22358,7 @@ var ScorerDefinitionsPG = class ScorerDefinitionsPG extends ScorerDefinitionsSto
 				updatedAt: now
 			};
 		} catch (error) {
-			try {
+			if (draftInserted) try {
 				const tableName = getTableName$5({
 					indexName: TABLE_SCORER_DEFINITIONS,
 					schemaName: getSchemaName$5(this.#schema)
@@ -22099,6 +23376,7 @@ var SkillsPG = class SkillsPG extends SkillsStorage {
 	}
 	async create(input) {
 		const { skill } = input;
+		let draftInserted = false;
 		try {
 			const tableName = getTableName$5({
 				indexName: TABLE_SKILLS,
@@ -22122,6 +23400,7 @@ var SkillsPG = class SkillsPG extends SkillsStorage {
 				nowIso,
 				nowIso
 			]);
+			draftInserted = true;
 			const { id: _id, authorId: _authorId, visibility: _visibility, ...snapshotConfig } = skill;
 			const versionId = crypto.randomUUID();
 			await this.createVersion({
@@ -22143,7 +23422,7 @@ var SkillsPG = class SkillsPG extends SkillsStorage {
 				updatedAt: now
 			};
 		} catch (error) {
-			try {
+			if (draftInserted) try {
 				const tableName = getTableName$5({
 					indexName: TABLE_SKILLS,
 					schemaName: getSchemaName$5(this.#schema)
@@ -23288,6 +24567,17 @@ function getTableName({ indexName, schemaName }) {
 	const quotedIndexName = `"${indexName}"`;
 	return schemaName ? `${schemaName}.${quotedIndexName}` : quotedIndexName;
 }
+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: row.ownerId,
+		leaseExpiresAt: leaseExpiresAt === null ? null : new Date(leaseExpiresAt),
+		live: leaseExpiresAt !== null && leaseExpiresAt > Number(row.nowMs)
+	};
+}
 /** Base name (before any schema prefix) of the expression index backing the status filter. */
 const WORKFLOW_SNAPSHOT_STATUS_INDEX = "mastra_workflow_snapshot_name_status_createdat_idx";
 /**
@@ -23372,12 +24662,24 @@ var WorkflowsPG = class WorkflowsPG extends WorkflowsStorage {
 	* Workflow run snapshots accumulate as runs execute. Anchored on the
 	* timezone-aware `updatedAtZ` mirror column (last activity) so suspended or
 	* 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: "updatedAtZ",
-		indexed: true
-	} };
+	static retentionTables = {
+		workflowSnapshot: {
+			table: TABLE_WORKFLOW_SNAPSHOT,
+			column: "updatedAtZ",
+			indexed: true
+		},
+		runOwnership: {
+			table: TABLE_WORKFLOW_RUN_OWNERS,
+			column: "updatedAt",
+			indexed: true,
+			anchorType: "epoch-ms"
+		}
+	};
 	constructor(config) {
 		super();
 		const { client, readClient, schemaName, skipDefaultIndexes, indexes } = resolvePgConfig(config);
@@ -23434,6 +24736,12 @@ var WorkflowsPG = class WorkflowsPG extends WorkflowsStorage {
 		for (const idx of WorkflowsPG.getDefaultIndexDefs(schemaPrefix)) statements.push(generateIndexSQL(idx, schemaName));
 		statements.push(`${workflowSnapshotStatusIndexSQL(workflowSnapshotStatusIndexName(parsedSchema), schemaName)};`);
 		statements.push(`${workflowSnapshotThreadIdIndexSQL(workflowSnapshotThreadIdIndexName(parsedSchema), schemaName)};`);
+		statements.push(generateTableSQL({
+			tableName: TABLE_WORKFLOW_RUN_OWNERS,
+			schema: RUN_FENCING_TABLE_SCHEMAS[TABLE_WORKFLOW_RUN_OWNERS],
+			schemaName,
+			includeAllConstraints: true
+		}));
 		return statements;
 	}
 	/**
@@ -23477,6 +24785,10 @@ var WorkflowsPG = class WorkflowsPG extends WorkflowsStorage {
 			schema: TABLE_SCHEMAS[TABLE_WORKFLOW_SNAPSHOT],
 			ifNotExists: ["resourceId"]
 		});
+		await this.#db.createTable({
+			tableName: TABLE_WORKFLOW_RUN_OWNERS,
+			schema: RUN_FENCING_TABLE_SCHEMAS[TABLE_WORKFLOW_RUN_OWNERS]
+		});
 		await this.createDefaultIndexes();
 		await this.createCustomIndexes();
 	}
@@ -23504,13 +24816,13 @@ var WorkflowsPG = class WorkflowsPG extends WorkflowsStorage {
 			}
 		}
 	}
-	/** Delete workflow run snapshots older than the `workflowSnapshot` policy's `maxAge`, batched. */
+	/** Delete workflow run snapshots and run ownership rows older than their policy's `maxAge`, batched. */
 	async prune(policies, options) {
 		await this.ensureRetentionIndexes(policies);
 		const targets = resolveTargets({
 			policies,
 			descriptor: WorkflowsPG.retentionTables,
-			order: ["workflowSnapshot"]
+			order: ["workflowSnapshot", "runOwnership"]
 		});
 		return runPrune({
 			db: this.#db,
@@ -23532,10 +24844,126 @@ var WorkflowsPG = class WorkflowsPG extends WorkflowsStorage {
 	}
 	async dangerouslyClearAll() {
 		await this.#db.clearTable({ tableName: TABLE_WORKFLOW_SNAPSHOT });
+		await this.#db.clearTable({ tableName: TABLE_WORKFLOW_RUN_OWNERS });
+	}
+	supportsRunFencing() {
+		return true;
+	}
+	#runOwnersTable() {
+		return getTableName({
+			indexName: TABLE_WORKFLOW_RUN_OWNERS,
+			schemaName: getSchemaName(this.#schema)
+		});
+	}
+	async #readRunOwner(q, runId) {
+		const row = await q.oneOrNone(`SELECT ${RUN_OWNER_COLUMNS} FROM ${this.#runOwnersTable()} WHERE "runId" = $1`, [runId]);
+		return row ? toRunOwnershipRecord(runId, row) : null;
+	}
+	#ownershipError(operation, runId, error) {
+		return new MastraError({
+			id: createStorageErrorId("PG", operation, "FAILED"),
+			domain: ErrorDomain.STORAGE,
+			category: ErrorCategory.THIRD_PARTY,
+			details: { runId }
+		}, error);
+	}
+	async claimRunOwnership({ runId, ownerId, leaseMs, force, expectedGeneration }) {
+		const table = this.#runOwnersTable();
+		try {
+			return await this.#db.client.tx(async (t) => {
+				if (!await t.oneOrNone(`SELECT 1 FROM ${table} WHERE "runId" = $1 FOR UPDATE`, [runId])) {
+					if (expectedGeneration !== void 0 && expectedGeneration !== 0) return {
+						acquired: false,
+						record: null
+					};
+					const inserted = await t.oneOrNone(`INSERT INTO ${table} ("runId", generation, "ownerId", "leaseExpiresAt", "updatedAt")
+             VALUES ($1, GREATEST(1, ${DB_NOW_MS}), $2, ${DB_NOW_MS} + $3, ${DB_NOW_MS})
+             ON CONFLICT ("runId") DO NOTHING
+             RETURNING ${RUN_OWNER_COLUMNS}`, [
+						runId,
+						ownerId,
+						leaseMs
+					]);
+					if (inserted) return {
+						acquired: true,
+						record: toRunOwnershipRecord(runId, inserted)
+					};
+				}
+				const claimed = await t.oneOrNone(`UPDATE ${table}
+           SET generation = generation + 1, "ownerId" = $2, "leaseExpiresAt" = ${DB_NOW_MS} + $3,
+               "updatedAt" = ${DB_NOW_MS}
+           WHERE "runId" = $1
+             AND ($4::bigint IS NULL OR generation = $4)
+             AND ($5::boolean OR "leaseExpiresAt" IS NULL OR "leaseExpiresAt" <= ${DB_NOW_MS})
+           RETURNING ${RUN_OWNER_COLUMNS}`, [
+					runId,
+					ownerId,
+					leaseMs,
+					expectedGeneration ?? null,
+					force === true
+				]);
+				if (claimed) return {
+					acquired: true,
+					record: toRunOwnershipRecord(runId, claimed)
+				};
+				return {
+					acquired: false,
+					record: await this.#readRunOwner(t, runId)
+				};
+			});
+		} catch (error) {
+			throw this.#ownershipError("CLAIM_RUN_OWNERSHIP", runId, error);
+		}
+	}
+	async renewRunOwnership({ leaseMs, ...fence }) {
+		try {
+			const renewed = await this.#db.client.oneOrNone(`UPDATE ${this.#runOwnersTable()}
+         SET "leaseExpiresAt" = ${DB_NOW_MS} + $4, "updatedAt" = ${DB_NOW_MS}
+         WHERE "runId" = $1 AND generation = $2 AND "ownerId" = $3 AND "leaseExpiresAt" IS NOT NULL
+         RETURNING ${RUN_OWNER_COLUMNS}`, [
+				fence.runId,
+				fence.generation,
+				fence.ownerId,
+				leaseMs
+			]);
+			if (renewed) return {
+				renewed: true,
+				record: toRunOwnershipRecord(fence.runId, renewed)
+			};
+			return {
+				renewed: false,
+				record: await this.#readRunOwner(this.#db.client, fence.runId)
+			};
+		} catch (error) {
+			throw this.#ownershipError("RENEW_RUN_OWNERSHIP", fence.runId, error);
+		}
+	}
+	async releaseRunOwnership(fence) {
+		try {
+			return await this.#db.client.oneOrNone(`UPDATE ${this.#runOwnersTable()}
+         SET "leaseExpiresAt" = NULL, "updatedAt" = ${DB_NOW_MS}
+         WHERE "runId" = $1 AND generation = $2 AND "ownerId" = $3
+         RETURNING "runId"`, [
+				fence.runId,
+				fence.generation,
+				fence.ownerId
+			]) !== null;
+		} catch (error) {
+			throw this.#ownershipError("RELEASE_RUN_OWNERSHIP", fence.runId, error);
+		}
+	}
+	async getRunOwnership({ runId }) {
+		try {
+			return await this.#readRunOwner(this.#db.client, runId);
+		} catch (error) {
+			throw this.#ownershipError("GET_RUN_OWNERSHIP", runId, error);
+		}
 	}
-	async updateWorkflowResults({ workflowName, runId, stepId, result, requestContext, state }) {
+	async updateWorkflowResults({ workflowName, runId, stepId, result, requestContext, state, fence: explicitFence }) {
+		const fence = resolveRunFence(this, explicitFence, runId);
 		try {
 			return await this.#db.client.tx(async (t) => {
+				if (fence) await assertRunFence(t, this.#runOwnersTable(), fence, "updateWorkflowResults");
 				const tableName = getTableName({
 					indexName: TABLE_WORKFLOW_SNAPSHOT,
 					schemaName: getSchemaName(this.#schema)
@@ -23585,6 +25013,7 @@ var WorkflowsPG = class WorkflowsPG extends WorkflowsStorage {
 				return snapshot.context;
 			});
 		} catch (error) {
+			if (isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("PG", "UPDATE_WORKFLOW_RESULTS", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -23597,9 +25026,11 @@ var WorkflowsPG = class WorkflowsPG 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.client.tx(async (t) => {
+				if (fence) await assertRunFence(t, this.#runOwnersTable(), fence, "updateWorkflowState");
 				const tableName = getTableName({
 					indexName: TABLE_WORKFLOW_SNAPSHOT,
 					schemaName: getSchemaName(this.#schema)
@@ -23629,6 +25060,7 @@ var WorkflowsPG = class WorkflowsPG extends WorkflowsStorage {
 				return updatedSnapshot;
 			});
 		} catch (error) {
+			if (isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("PG", "UPDATE_WORKFLOW_STATE", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -23640,13 +25072,13 @@ var WorkflowsPG = class WorkflowsPG extends WorkflowsStorage {
 			}, error);
 		}
 	}
-	async persistWorkflowSnapshot({ workflowName, runId, resourceId, snapshot, createdAt, updatedAt }) {
+	async persistWorkflowSnapshot({ workflowName, runId, resourceId, snapshot, createdAt, updatedAt, fence }) {
 		try {
 			const now = /* @__PURE__ */ new Date();
 			const createdAtValue = createdAt ? createdAt : now;
 			const updatedAtValue = updatedAt ? updatedAt : now;
 			const sanitizedSnapshot = toPgJson(snapshot);
-			await this.#db.client.none(`INSERT INTO ${getTableName({
+			await withRunFence(this.#db.client, this.#runOwnersTable(), resolveRunFence(this, fence, runId), "persistWorkflowSnapshot", (q) => q.none(`INSERT INTO ${getTableName({
 				indexName: TABLE_WORKFLOW_SNAPSHOT,
 				schemaName: getSchemaName(this.#schema)
 			})} AS t
@@ -23662,8 +25094,9 @@ var WorkflowsPG = class WorkflowsPG extends WorkflowsStorage {
 				updatedAtValue,
 				createdAtValue,
 				updatedAtValue
-			]);
+			]));
 		} catch (error) {
+			if (isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("PG", "PERSIST_WORKFLOW_SNAPSHOT", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -23729,13 +25162,14 @@ var WorkflowsPG = class WorkflowsPG extends WorkflowsStorage {
 			}, error);
 		}
 	}
-	async deleteWorkflowRunById({ runId, workflowName }) {
+	async deleteWorkflowRunById({ runId, workflowName, fence }) {
 		try {
-			await this.#db.client.none(`DELETE FROM ${getTableName({
+			await withRunFence(this.#db.client, this.#runOwnersTable(), resolveRunFence(this, fence, runId), "deleteWorkflowRunById", (q) => q.none(`DELETE FROM ${getTableName({
 				indexName: TABLE_WORKFLOW_SNAPSHOT,
 				schemaName: getSchemaName(this.#schema)
-			})} WHERE run_id = $1 AND workflow_name = $2`, [runId, workflowName]);
+			})} WHERE run_id = $1 AND workflow_name = $2`, [runId, workflowName]));
 		} catch (error) {
+			if (isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("PG", "DELETE_WORKFLOW_RUN_BY_ID", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -23947,6 +25381,7 @@ var WorkspacesPG = class WorkspacesPG extends WorkspacesStorage {
 	}
 	async create(input) {
 		const { workspace } = input;
+		let draftInserted = false;
 		try {
 			const tableName = getTableName$5({
 				indexName: TABLE_WORKSPACES,
@@ -23968,6 +25403,7 @@ var WorkspacesPG = class WorkspacesPG extends WorkspacesStorage {
 				nowIso,
 				nowIso
 			]);
+			draftInserted = true;
 			const { id: _id, authorId: _authorId, metadata: _metadata, ...snapshotConfig } = workspace;
 			const versionId = crypto.randomUUID();
 			await this.createVersion({
@@ -23988,7 +25424,7 @@ var WorkspacesPG = class WorkspacesPG extends WorkspacesStorage {
 				updatedAt: now
 			};
 		} catch (error) {
-			try {
+			if (draftInserted) try {
 				const tableName = getTableName$5({
 					indexName: TABLE_WORKSPACES,
 					schemaName: getSchemaName$5(this.#schema)
@@ -25038,7 +26474,10 @@ var PostgresStore = class extends MastraCompositeStore {
 				workflows: new WorkflowsPG(domainConfig),
 				workflowDefinitions: new WorkflowDefinitionsPG(domainConfig),
 				memory: new MemoryPG(domainConfig),
-				knowledge: new KnowledgePG(domainConfig),
+				knowledge: new KnowledgePG({
+					...domainConfig,
+					storageIsolationKey: config.storageIsolationKey ?? getPgKnowledgeIsolationKey(config)
+				}),
 				notifications: new NotificationsPG(domainConfig),
 				observability: new ObservabilityPG(domainConfig),
 				agents: new AgentsPG(domainConfig),
@@ -25092,7 +26531,7 @@ var PostgresStore = class extends MastraCompositeStore {
 			const pinned = new PinnedClientAdapter(this.#writePool, pinnedClient);
 			this.#db.pin(pinned);
 			this.#db.setSchemaSnapshot(await loadSchemaSnapshot(pinned, this.schema));
-			await super.init();
+			await Promise.all(Object.entries(this.stores).filter(([name, store]) => name !== "knowledge" && store).map(([, store]) => store.init()));
 			this.isInitialized = true;
 		} catch (error) {
 			this.#initPromise = null;