@mastra/pg 1.20.1-alpha.2 → 1.21.0-alpha.4

package/dist/index.js

@@ -1,5 +1,5 @@
 import { ErrorCategory, ErrorDomain, MastraError } from "@mastra/core/error";
-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, 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_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, calculatePagination, createStorageErrorId, createVectorErrorId, ensureDate, getDefaultValue, getSqlType, hasErrorCode, listBranchesArgsSchema, listFeedbackArgsSchema, listLogsArgsSchema, listMetricsArgsSchema, listScoresArgsSchema, listTracesArgsSchema, mergeWorkflowStepResult, normalizePerPage, normalizeScheduleTarget, parseDuration, 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_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, getDefaultValue, getSqlType, hasErrorCode, isKnowledgeScopeVisible, knowledgeScopeKey, knowledgeSemanticDocumentId, knowledgeSemanticIdempotencyKey, listBranchesArgsSchema, listFeedbackArgsSchema, listLogsArgsSchema, listMetricsArgsSchema, listScoresArgsSchema, listTracesArgsSchema, mergeWorkflowStepResult, normalizePerPage, normalizeScheduleTarget, parseDuration, parseKnowledgeNodeCursor, parseKnowledgeWikilinks, 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";
@@ -327,7 +327,7 @@ const FILTER_OPERATORS = {
 		return {
 			sql,
 			needsValue: true,
-			transformValue: () => Array.isArray(value) ? value.map(String) : typeof value === "string" ? escapeLikePattern(value) : value
+			transformValue: () => Array.isArray(value) ? value.map(String) : typeof value === "string" ? escapeLikePattern$1(value) : value
 		};
 	},
 	/**
@@ -351,7 +351,7 @@ const FILTER_OPERATORS = {
 const parseJsonPathKey = (key) => {
 	return (key !== "" ? parseFieldKey(key) : "").replace(/\./g, ",");
 };
-function escapeLikePattern(str) {
+function escapeLikePattern$1(str) {
 	return str.replace(/([%_\\])/g, "\\$1");
 }
 /**
@@ -4688,7 +4688,7 @@ function serializeJson(v) {
 	if (typeof v === "object" && v != null) return JSON.stringify(v);
 	return v ?? null;
 }
-function parseJson$1(v) {
+function parseJson$2(v) {
 	if (typeof v === "string") try {
 		return JSON.parse(v);
 	} catch {
@@ -4707,14 +4707,14 @@ function rowToTask(row) {
 		status: row.status,
 		toolName: row.tool_name,
 		toolCallId: row.tool_call_id,
-		args: parseJson$1(row.args),
+		args: parseJson$2(row.args),
 		agentId: row.agent_id,
 		threadId: row.thread_id ?? void 0,
 		resourceId: row.resource_id ?? void 0,
 		runId: row.run_id,
-		result: parseJson$1(row.result),
-		error: parseJson$1(row.error),
-		suspendPayload: parseJson$1(row.suspend_payload),
+		result: parseJson$2(row.result),
+		error: parseJson$2(row.error),
+		suspendPayload: parseJson$2(row.suspend_payload),
 		retryCount: Number(row.retry_count),
 		maxRetries: Number(row.max_retries),
 		timeoutMs: Number(row.timeout_ms),
@@ -7584,6 +7584,977 @@ var FavoritesPG = class FavoritesPG extends FavoritesStorage {
 	}
 };
 //#endregion
+//#region src/storage/domains/knowledge/index.ts
+const camelCaseColumns = [
+	"canonicalName",
+	"scopeKey",
+	"mergedInto",
+	"createdAt",
+	"updatedAt",
+	"node",
+	"sourceThreadId",
+	"capturedAt",
+	"maxScope",
+	"deletedAt",
+	"deletedBy",
+	"sourceType",
+	"sourceId",
+	"recordId",
+	"lastKnowledgeId",
+	"recordType",
+	"idempotencyKey",
+	"documentId",
+	"documentType",
+	"availableAt",
+	"claimedAt",
+	"claimedBy",
+	"completedAt"
+];
+function transformSqlCode(sql, transform) {
+	return sql.split(/('(?:''|[^'])*')/g).map((part, index) => index % 2 === 0 ? transform(part) : part).join("");
+}
+function postgresSql(sql, schemaName) {
+	let normalized = transformSqlCode(sql, (code) => {
+		let transformed = code.replace(/jsonb\(\?\)/g, "?::jsonb");
+		for (const column of camelCaseColumns) transformed = transformed.replace(new RegExp(`(?<!")\\b${column}\\b(?!")`, "g"), `"${column}"`);
+		return transformed;
+	});
+	if (schemaName) {
+		const quotedSchema = `"${parseSqlIdentifier(schemaName, "schema name")}"`;
+		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}"`);
+			return transformed;
+		});
+	}
+	let index = 0;
+	return transformSqlCode(normalized, (code) => code.replace(/\?/g, () => `$${++index}`));
+}
+function createExecutor(client, schemaName) {
+	return { async execute(statement) {
+		const sql = typeof statement === "string" ? statement : statement.sql;
+		const args = typeof statement === "string" ? [] : statement.args ?? [];
+		const result = await client.query(postgresSql(sql, schemaName), args);
+		return {
+			rows: result.rows,
+			rowsAffected: result.rowCount ?? 0
+		};
+	} };
+}
+const visibleSql = `(scopeKey = ? OR LEFT(?, LENGTH(scopeKey) + 1) = scopeKey || chr(31))`;
+function parseJson$1(value) {
+	if (typeof value === "string") return JSON.parse(value);
+	if (value instanceof Uint8Array) return JSON.parse(new TextDecoder().decode(value));
+	if (value instanceof ArrayBuffer) return JSON.parse(new TextDecoder().decode(value));
+	return value;
+}
+/**
+* Knowledge timestamps are written as UTC digits into timezone-naive columns
+* ({@link postgresTimestamp} and the ISO strings passed to inserts), but the
+* driver parses naive columns in the process-local timezone. Reinterpret the
+* parsed components as UTC so reads return the digits that were stored.
+*/
+function toDate$1(value) {
+	if (value instanceof Date) return new Date(Date.UTC(value.getFullYear(), value.getMonth(), value.getDate(), value.getHours(), value.getMinutes(), value.getSeconds(), value.getMilliseconds()));
+	const text = String(value);
+	if (/(Z|[+-]\d{2}(:?\d{2})?)$/.test(text)) return new Date(text);
+	return /* @__PURE__ */ new Date(`${text.replace(" ", "T")}Z`);
+}
+function optionalDate(value) {
+	return value == null ? void 0 : toDate$1(value);
+}
+function postgresTimestamp(value) {
+	const pad = (part, width = 2) => String(part).padStart(width, "0");
+	return `${value.getUTCFullYear()}-${pad(value.getUTCMonth() + 1)}-${pad(value.getUTCDate())} ${pad(value.getUTCHours())}:${pad(value.getUTCMinutes())}:${pad(value.getUTCSeconds())}.${pad(value.getUTCMilliseconds(), 3)}`;
+}
+function canonicalName(name) {
+	return name.trim().toLocaleLowerCase();
+}
+function nodeReferenceId(node) {
+	return typeof node === "string" ? node : node.id;
+}
+function escapeLikePattern(value) {
+	return value.replaceAll("=", "==").replaceAll("%", "=%").replaceAll("_", "=_");
+}
+function parseNode(row) {
+	return {
+		id: String(row.id),
+		type: "node",
+		name: String(row.name),
+		kind: String(row.kind),
+		content: row.content == null ? void 0 : String(row.content),
+		scope: parseJson$1(row.scopeJson ?? row.scope),
+		version: Number(row.version),
+		mergedInto: row.mergedInto == null ? void 0 : String(row.mergedInto),
+		createdAt: toDate$1(row.createdAt),
+		updatedAt: toDate$1(row.updatedAt)
+	};
+}
+function parseKnowledge(row) {
+	return {
+		id: String(row.id),
+		node: String(row.node),
+		text: String(row.text),
+		scope: parseJson$1(row.scopeJson ?? row.scope),
+		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)
+	};
+}
+function parseOutbox(row) {
+	return {
+		id: String(row.id),
+		idempotencyKey: String(row.idempotencyKey),
+		documentId: String(row.documentId),
+		documentType: String(row.documentType),
+		operation: String(row.operation),
+		scope: parseJson$1(row.scopeJson ?? row.scope),
+		status: String(row.status),
+		attempts: Number(row.attempts),
+		availableAt: toDate$1(row.availableAt),
+		claimedAt: optionalDate(row.claimedAt),
+		claimedBy: row.claimedBy == null ? void 0 : String(row.claimedBy),
+		createdAt: toDate$1(row.createdAt),
+		completedAt: optionalDate(row.completedAt)
+	};
+}
+function knowledgeIndexes(schemaName) {
+	const table = (name) => {
+		const quotedName = `"${parseSqlIdentifier(name, "table name")}"`;
+		return schemaName ? `"${parseSqlIdentifier(schemaName, "schema name")}".${quotedName}` : quotedName;
+	};
+	return [
+		{
+			name: "idx_knowledge_nodes_identity",
+			sql: `CREATE UNIQUE INDEX IF NOT EXISTS idx_knowledge_nodes_identity ON ${table(TABLE_KNOWLEDGE_NODES)} ("type", "scopeKey", "canonicalName");`
+		},
+		{
+			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_records_node_latest",
+			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_records_node_latest ON ${table(TABLE_KNOWLEDGE_RECORDS)} ("node", "id" DESC);`
+		},
+		{
+			name: "idx_knowledge_records_thread_latest",
+			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_records_thread_latest ON ${table(TABLE_KNOWLEDGE_RECORDS)} ("sourceThreadId", "id" DESC);`
+		},
+		{
+			name: "idx_knowledge_mentions_record",
+			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_mentions_record ON ${table(TABLE_KNOWLEDGE_MENTIONS)} ("recordId", "sourceType", "sourceId");`
+		},
+		{
+			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_outbox_idempotency",
+			sql: `CREATE UNIQUE INDEX IF NOT EXISTS idx_knowledge_outbox_idempotency ON ${table(TABLE_KNOWLEDGE_SEMANTIC_OUTBOX)} ("idempotencyKey");`
+		},
+		{
+			name: "idx_knowledge_outbox_claim",
+			sql: `CREATE INDEX IF NOT EXISTS idx_knowledge_outbox_claim ON ${table(TABLE_KNOWLEDGE_SEMANTIC_OUTBOX)} ("status", "availableAt", "createdAt");`
+		}
+	];
+}
+function knowledgeIndexDDL(schemaName) {
+	return knowledgeIndexes(schemaName).map((index) => index.sql);
+}
+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 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)
+		];
+	}
+	#client;
+	#executor;
+	#db;
+	#schemaName;
+	constructor(config) {
+		super();
+		const { client, schemaName, skipDefaultIndexes } = resolvePgConfig(config);
+		this.#client = client;
+		this.#schemaName = schemaName;
+		this.#executor = createExecutor(client, schemaName);
+		this.#db = new PgDB({
+			client,
+			schemaName,
+			skipDefaultIndexes
+		});
+	}
+	async init() {
+		await this.#db.createTable({
+			tableName: TABLE_KNOWLEDGE_NODES,
+			schema: KNOWLEDGE_NODES_SCHEMA
+		});
+		await this.#db.createTable({
+			tableName: TABLE_KNOWLEDGE_RECORDS,
+			schema: KNOWLEDGE_RECORDS_SCHEMA
+		});
+		await this.#db.createTable({
+			tableName: TABLE_KNOWLEDGE_MENTIONS,
+			schema: KNOWLEDGE_MENTIONS_SCHEMA,
+			compositePrimaryKey: [
+				"sourceType",
+				"sourceId",
+				"recordId"
+			]
+		});
+		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
+		});
+		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 createNode(input) {
+		const scope = canonicalizeKnowledgeScope(input.scope);
+		return this.#transaction(async (tx) => {
+			const existing = await this.#getNodeByName(tx, input.name, scope);
+			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}`);
+				return terminal;
+			}
+			const now = /* @__PURE__ */ new Date();
+			const node = {
+				id: input.id ?? crypto.randomUUID(),
+				type: "node",
+				name: input.name.trim(),
+				kind: input.kind,
+				content: input.content,
+				scope,
+				version: 1,
+				createdAt: now,
+				updatedAt: now
+			};
+			await tx.execute({
+				sql: `INSERT INTO "${TABLE_KNOWLEDGE_NODES}" (id,type,name,canonicalName,kind,content,scope,scopeKey,version,mergedInto,createdAt,updatedAt) VALUES (?,?,?,?,?,?,jsonb(?),?,?,NULL,?,?)`,
+				args: [
+					node.id,
+					"node",
+					node.name,
+					canonicalName(node.name),
+					node.kind,
+					node.content ?? null,
+					JSON.stringify(scope),
+					knowledgeScopeKey(scope),
+					node.version,
+					now.toISOString(),
+					now.toISOString()
+				]
+			});
+			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);
+			return node;
+		});
+	}
+	async getNode(id) {
+		return this.#getNode(this.#executor, id);
+	}
+	async getNodeByName(input) {
+		return this.#getNodeByName(this.#executor, input.name, canonicalizeKnowledgeScope(input.scope));
+	}
+	async resolveNode(input) {
+		return this.#resolveNode(this.#executor, input.name, canonicalizeKnowledgeScope(input.scope));
+	}
+	async listNodes(input) {
+		const key = knowledgeScopeKey(canonicalizeKnowledgeScope(input.scope));
+		const clauses = [
+			`type = 'node'`,
+			"mergedInto IS NULL",
+			visibleSql
+		];
+		const args = [key, key];
+		if (input.namePrefix) {
+			clauses.push("canonicalName LIKE ? ESCAPE '='");
+			args.push(`${escapeLikePattern(canonicalName(input.namePrefix))}%`);
+		}
+		if (input.kind) {
+			clauses.push("kind = ?");
+			args.push(input.kind);
+		}
+		if (input.hasContent !== void 0) clauses.push(input.hasContent ? "content IS NOT NULL AND content <> ''" : "(content IS NULL OR content = '')");
+		if (input.cursor) {
+			const cursor = parseKnowledgeNodeCursor(input.cursor, {
+				namePrefix: input.namePrefix,
+				kind: input.kind,
+				hasContent: input.hasContent
+			});
+			const updatedAt = postgresTimestamp(cursor.updatedAt);
+			clauses.push("(updatedAt < ? OR (updatedAt = ? AND (name > ? OR (name = ? AND id > ?))))");
+			args.push(updatedAt, updatedAt, cursor.name, cursor.name, cursor.id);
+		}
+		args.push(input.limit ?? 100);
+		return (await this.#executor.execute({
+			sql: `SELECT *, scope AS "scopeJson" FROM "${TABLE_KNOWLEDGE_NODES}" WHERE ${clauses.join(" AND ")} ORDER BY updatedAt DESC, name ASC, id ASC LIMIT ?`,
+			args
+		})).rows.map(parseNode);
+	}
+	async updateNode(input) {
+		return this.#transaction(async (tx) => {
+			const existing = await this.#getNode(tx, input.id);
+			if (!existing) throw new KnowledgeNotFoundError("node", input.id);
+			if (existing.mergedInto) throw new Error(`Cannot update merged knowledge node: ${input.id}`);
+			const scope = canonicalizeKnowledgeScope(input.scope ?? existing.scope);
+			const name = (input.name ?? existing.name).trim();
+			const content = input.content ?? existing.content;
+			const now = /* @__PURE__ */ new Date();
+			if ((await tx.execute({
+				sql: `UPDATE "${TABLE_KNOWLEDGE_NODES}" SET name=?,canonicalName=?,kind=?,content=?,scope=jsonb(?),scopeKey=?,version=version+1,updatedAt=? WHERE id=? AND type='node' AND version=?`,
+				args: [
+					name,
+					canonicalName(name),
+					input.kind ?? existing.kind,
+					content ?? null,
+					JSON.stringify(scope),
+					knowledgeScopeKey(scope),
+					now.toISOString(),
+					input.id,
+					input.version
+				]
+			})).rowsAffected === 0) throw new KnowledgeConflictError(input.id);
+			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)) {
+				await this.#outbox(tx, "node", input.id, "delete", createKnowledgeUlid(), existing.scope);
+				const records = await tx.execute({
+					sql: `SELECT id,scope AS "scopeJson",deletedAt FROM "${TABLE_KNOWLEDGE_RECORDS}" WHERE node=?`,
+					args: [input.id]
+				});
+				for (const row of records.rows) {
+					const factScope = parseJson$1(row.scopeJson);
+					await this.#outbox(tx, "record", String(row.id), "delete", createKnowledgeUlid(), factScope);
+					if (row.deletedAt == null) await this.#outbox(tx, "record", String(row.id), "upsert", createKnowledgeUlid(), factScope);
+				}
+			}
+			await this.#outbox(tx, "node", input.id, "upsert", input.version + 1, scope);
+			return {
+				...existing,
+				name,
+				kind: input.kind ?? existing.kind,
+				content,
+				scope,
+				version: input.version + 1,
+				updatedAt: now
+			};
+		});
+	}
+	async mergeNodes(input) {
+		if (input.sourceId === input.targetId) throw new Error("Cannot merge a knowledge node into itself");
+		return this.#transaction(async (tx) => {
+			const source = await this.#getNode(tx, input.sourceId);
+			if (!source) throw new KnowledgeNotFoundError("node", input.sourceId);
+			const target = await this.#resolveTerminalNode(tx, input.targetId);
+			if (!target) throw new KnowledgeNotFoundError("node", input.targetId);
+			if (target.id === source.id) throw new Error("Cannot create a knowledge merge cycle");
+			if (!isKnowledgeScopeVisible(target.scope, source.scope)) throw new Error("Cannot merge a knowledge node into a target that is narrower than its source scope");
+			const affected = await tx.execute({
+				sql: `SELECT DISTINCT m.sourceType,m.sourceId,COALESCE(f.scope,r.scope) AS "scopeJson",CASE WHEN f.deletedAt IS NULL THEN 0 ELSE 1 END AS deleted FROM "${TABLE_KNOWLEDGE_MENTIONS}" m LEFT JOIN "${TABLE_KNOWLEDGE_RECORDS}" f ON m.sourceType='record' AND f.id=m.sourceId LEFT JOIN "${TABLE_KNOWLEDGE_NODES}" r ON m.sourceType='node' AND r.id=m.sourceId WHERE m.recordId=?`,
+				args: [source.id]
+			});
+			const movedFacts = await tx.execute({
+				sql: `SELECT id,scope AS "scopeJson",deletedAt FROM "${TABLE_KNOWLEDGE_RECORDS}" WHERE node=?`,
+				args: [source.id]
+			});
+			if ((await tx.execute({
+				sql: `UPDATE "${TABLE_KNOWLEDGE_NODES}" SET mergedInto=?,version=version+1,updatedAt=? WHERE id=? AND type='node' AND version=? AND mergedInto IS NULL`,
+				args: [
+					target.id,
+					(/* @__PURE__ */ new Date()).toISOString(),
+					source.id,
+					input.sourceVersion
+				]
+			})).rowsAffected === 0) throw new KnowledgeConflictError(source.id);
+			await tx.execute({
+				sql: `UPDATE "${TABLE_KNOWLEDGE_RECORDS}" SET node=? WHERE node=?`,
+				args: [target.id, 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=?)`,
+				args: [source.id, target.id]
+			});
+			await tx.execute({
+				sql: `UPDATE "${TABLE_KNOWLEDGE_MENTIONS}" SET recordId=? WHERE recordId=?`,
+				args: [target.id, source.id]
+			});
+			for (const row of movedFacts.rows) await this.#outbox(tx, "record", String(row.id), row.deletedAt == null ? "upsert" : "delete", createKnowledgeUlid(), parseJson$1(row.scopeJson));
+			for (const row of affected.rows) await this.#outbox(tx, String(row.sourceType), String(row.sourceId), Number(row.deleted) ? "delete" : "upsert", createKnowledgeUlid(), parseJson$1(row.scopeJson));
+			await this.#activity(tx, "node-merged", "node", source.id, source.scope);
+			await this.#outbox(tx, "node", source.id, "delete", input.sourceVersion + 1, source.scope);
+			await this.#outbox(tx, "node", target.id, "upsert", createKnowledgeUlid(), target.scope);
+			return target;
+		});
+	}
+	async appendKnowledge(input) {
+		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));
+			const record = {
+				id: input.id ?? createKnowledgeUlid(),
+				node: parent.id,
+				text: input.text,
+				scope,
+				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)`,
+				args: [
+					record.id,
+					record.node,
+					record.text,
+					JSON.stringify(scope),
+					knowledgeScopeKey(scope),
+					record.sourceThreadId,
+					record.capturedAt.toISOString(),
+					record.when?.toISOString() ?? null,
+					record.maxScope ?? null,
+					record.metadata ? JSON.stringify(record.metadata) : null
+				]
+			});
+			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);
+			return record;
+		});
+	}
+	async getKnowledge(input) {
+		const result = await this.#executor.execute({
+			sql: `SELECT *,scope AS "scopeJson" FROM "${TABLE_KNOWLEDGE_RECORDS}" WHERE id=?${input.includeDeleted ? "" : " AND deletedAt IS NULL"}`,
+			args: [input.id]
+		});
+		return result.rows[0] ? parseKnowledge(result.rows[0]) : null;
+	}
+	async listKnowledgeAbout(input) {
+		return this.#queryKnowledge(input, "about");
+	}
+	async listKnowledgeMentioning(input) {
+		return this.#queryKnowledge(input, "mentioning");
+	}
+	async listKnowledgeRelatedTo(input) {
+		return this.#queryKnowledge(input, "related");
+	}
+	async knowledgeBySource(input) {
+		const key = knowledgeScopeKey(canonicalizeKnowledgeScope(input.scope));
+		const args = [
+			input.sourceThreadId,
+			key,
+			key
+		];
+		if (input.after) args.push(input.after);
+		const limit = input.limit ?? 100;
+		args.push(limit + 1);
+		const records = (await this.#executor.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 ?`,
+			args
+		})).rows.map(parseKnowledge);
+		return {
+			records: records.slice(0, limit),
+			nextCursor: records.length > limit ? records[limit - 1]?.id : void 0
+		};
+	}
+	async removeKnowledge(input) {
+		return this.#transaction(async (tx) => {
+			const record = await this.#getKnowledge(tx, input.id, true);
+			if (!record) throw new KnowledgeNotFoundError("record", input.id);
+			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`,
+				args: [
+					deletedAt.toISOString(),
+					input.deletedBy,
+					input.id
+				]
+			});
+			await this.#activity(tx, "record-deleted", "record", input.id, record.scope, record.sourceThreadId);
+			await this.#outbox(tx, "record", input.id, "delete", deletedAt.toISOString(), record.scope);
+			return {
+				...record,
+				deletedAt,
+				deletedBy: input.deletedBy
+			};
+		});
+	}
+	async restoreKnowledge(input) {
+		return this.#transaction(async (tx) => {
+			const record = await this.#getKnowledge(tx, input.id, true);
+			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]
+			});
+			await this.#activity(tx, "record-restored", "record", input.id, record.scope, record.sourceThreadId);
+			await this.#outbox(tx, "record", input.id, "upsert", createKnowledgeUlid(), record.scope);
+			return {
+				...record,
+				deletedAt: void 0,
+				deletedBy: void 0
+			};
+		});
+	}
+	async rescopeKnowledge(input) {
+		const scope = canonicalizeKnowledgeScope(input.scope);
+		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);
+			await tx.execute({
+				sql: `UPDATE "${TABLE_KNOWLEDGE_RECORDS}" SET scope=jsonb(?),scopeKey=? WHERE id=?`,
+				args: [
+					JSON.stringify(scope),
+					knowledgeScopeKey(scope),
+					input.id
+				]
+			});
+			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);
+			return {
+				...record,
+				scope
+			};
+		});
+	}
+	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 normalizedQuery = input.query.trim().toLocaleLowerCase();
+		if (!normalizedQuery) return [];
+		const query = `%${escapeLikePattern(normalizedQuery)}%`;
+		const results = (await this.#executor.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 '=') ORDER BY updatedAt DESC LIMIT ?`,
+			args: [
+				key,
+				key,
+				query,
+				query,
+				query,
+				input.limit ?? 20
+			]
+		})).rows.map((row) => ({
+			type: String(row.type),
+			id: String(row.id),
+			recordId: String(row.id),
+			name: String(row.name),
+			text: row.content ? `${String(row.name)}\n${String(row.content)}` : String(row.name),
+			scope: parseJson$1(row.scopeJson)
+		}));
+		if (results.length < (input.limit ?? 20)) {
+			const records = await this.#executor.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 ?`,
+				args: [
+					key,
+					key,
+					query,
+					(input.limit ?? 20) - results.length
+				]
+			});
+			results.push(...records.rows.map((row) => {
+				const parentVisible = isKnowledgeScopeVisible(parseJson$1(row.parentScopeJson), scope);
+				return {
+					type: "record",
+					id: String(row.id),
+					recordId: String(row.node),
+					name: parentVisible ? String(row.name) : "(private node)",
+					text: String(row.text),
+					scope: parseJson$1(row.scopeJson)
+				};
+			}));
+		}
+		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
+		};
+	}
+	async listActivity(input) {
+		const key = knowledgeScopeKey(canonicalizeKnowledgeScope(input.scope));
+		return (await this.#executor.execute({
+			sql: `SELECT *,scope AS "scopeJson" FROM "${TABLE_KNOWLEDGE_ACTIVITY}" WHERE ${visibleSql}${input.after ? " AND id < ?" : ""} ORDER BY id DESC LIMIT ?`,
+			args: [
+				key,
+				key,
+				...input.after ? [input.after] : [],
+				input.limit ?? 100
+			]
+		})).rows.map((row) => ({
+			id: String(row.id),
+			action: String(row.action),
+			recordType: String(row.recordType),
+			recordId: String(row.recordId),
+			scope: parseJson$1(row.scopeJson),
+			sourceThreadId: row.sourceThreadId == null ? void 0 : String(row.sourceThreadId),
+			createdAt: toDate$1(row.createdAt)
+		}));
+	}
+	async listSemanticOutbox(input = {}) {
+		const clauses = [];
+		const args = [];
+		if (input.status) {
+			clauses.push("status=?");
+			args.push(input.status);
+		}
+		if (input.scope) {
+			const key = knowledgeScopeKey(canonicalizeKnowledgeScope(input.scope));
+			clauses.push(visibleSql);
+			args.push(key, key);
+		}
+		args.push(input.limit ?? 100);
+		return (await this.#executor.execute({
+			sql: `SELECT *,scope AS "scopeJson" FROM "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}"${clauses.length ? ` WHERE ${clauses.join(" AND ")}` : ""} ORDER BY createdAt ASC,id ASC LIMIT ?`,
+			args
+		})).rows.map(parseOutbox);
+	}
+	async claimSemanticOutbox(input) {
+		const now = input.now ?? /* @__PURE__ */ new Date();
+		const stale = new Date(now.getTime() - (input.claimTimeoutMs ?? 6e4));
+		return this.#transaction(async (tx) => {
+			const clauses = [
+				`availableAt <= ?`,
+				`(status='pending' OR (status='processing' AND claimedAt <= ?))`,
+				`NOT EXISTS (SELECT 1 FROM "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" AS earlier WHERE earlier.documentId = "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}".documentId AND earlier.status != 'completed' AND (earlier.createdAt < "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}".createdAt OR (earlier.createdAt = "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}".createdAt AND earlier.id < "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}".id)))`
+			];
+			const args = [now.toISOString(), stale.toISOString()];
+			if (input.scope) {
+				const key = knowledgeScopeKey(canonicalizeKnowledgeScope(input.scope));
+				clauses.push(visibleSql);
+				args.push(key, key);
+			}
+			args.push(input.limit ?? 100);
+			const ids = (await tx.execute({
+				sql: `SELECT id FROM "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" WHERE ${clauses.join(" AND ")} ORDER BY createdAt ASC,id ASC LIMIT ? FOR UPDATE SKIP LOCKED`,
+				args
+			})).rows.map((row) => String(row.id));
+			for (const id of ids) await tx.execute({
+				sql: `UPDATE "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" SET status='processing',attempts=attempts+1,claimedAt=?,claimedBy=? WHERE id=?`,
+				args: [
+					now.toISOString(),
+					input.workerId,
+					id
+				]
+			});
+			if (!ids.length) return [];
+			return (await tx.execute({
+				sql: `SELECT *,scope AS "scopeJson" FROM "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" WHERE id IN (${ids.map(() => "?").join(",")}) ORDER BY createdAt ASC,id ASC`,
+				args: ids
+			})).rows.map(parseOutbox);
+		});
+	}
+	async completeSemanticOutbox(input) {
+		if (!input.ids.length) return;
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		await this.#transaction(async (tx) => {
+			for (const id of input.ids) await tx.execute({
+				sql: `UPDATE "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" SET status='completed',completedAt=? WHERE id=? AND status='processing' AND claimedBy=?`,
+				args: [
+					now,
+					id,
+					input.workerId
+				]
+			});
+		});
+	}
+	async releaseSemanticOutbox(input) {
+		if (!input.ids.length) return;
+		await this.#transaction(async (tx) => {
+			for (const id of input.ids) await tx.execute({
+				sql: `UPDATE "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" SET status='pending',availableAt=?,claimedAt=NULL,claimedBy=NULL WHERE id=? AND status='processing' AND claimedBy=?`,
+				args: [
+					(input.retryAt ?? /* @__PURE__ */ new Date()).toISOString(),
+					id,
+					input.workerId
+				]
+			});
+		});
+	}
+	async #transaction(operation) {
+		return this.#client.tx((tx) => operation(createExecutor(tx, this.#schemaName)));
+	}
+	async #getNode(executor, id) {
+		const result = await executor.execute({
+			sql: `SELECT *,scope AS "scopeJson" FROM "${TABLE_KNOWLEDGE_NODES}" WHERE id=? AND type='node'`,
+			args: [id]
+		});
+		return result.rows[0] ? parseNode(result.rows[0]) : null;
+	}
+	async #getNodeByName(executor, name, scope) {
+		const result = await executor.execute({
+			sql: `SELECT *,scope AS "scopeJson" FROM "${TABLE_KNOWLEDGE_NODES}" WHERE type='node' AND scopeKey=? AND canonicalName=?`,
+			args: [knowledgeScopeKey(scope), canonicalName(name)]
+		});
+		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;
+			}
+		}
+		return null;
+	}
+	async #resolveTerminalNode(executor, id) {
+		let node = await this.#getNode(executor, id);
+		const seen = /* @__PURE__ */ new Set();
+		while (node?.mergedInto) {
+			if (seen.has(node.id)) throw new Error(`Knowledge merge cycle detected at ${node.id}`);
+			seen.add(node.id);
+			node = await this.#getNode(executor, node.mergedInto);
+		}
+		return node;
+	}
+	async #getKnowledge(executor, id, includeDeleted) {
+		const result = await executor.execute({
+			sql: `SELECT *,scope AS "scopeJson" FROM "${TABLE_KNOWLEDGE_RECORDS}" WHERE id=?${includeDeleted ? "" : " AND deletedAt IS NULL"}`,
+			args: [id]
+		});
+		return result.rows[0] ? parseKnowledge(result.rows[0]) : null;
+	}
+	async #queryKnowledge(input, relationship) {
+		const scope = canonicalizeKnowledgeScope(input.scope);
+		const node = await this.#resolveTerminalNode(this.#executor, nodeReferenceId(input.node));
+		if (!node) return { records: [] };
+		const key = knowledgeScopeKey(scope);
+		const args = [
+			node.id,
+			...relationship === "related" ? [node.id] : [],
+			key,
+			key
+		];
+		if (input.after) args.push(input.after);
+		args.push((input.limit ?? 100) + 1);
+		const records = (await this.#executor.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 ?`,
+			args
+		})).rows.map(parseKnowledge);
+		const limit = input.limit ?? 100;
+		return {
+			records: records.slice(0, limit),
+			nextCursor: records.length > limit ? records[limit - 1]?.id : void 0
+		};
+	}
+	async #replaceMentions(tx, sourceType, sourceId, text, resolutionScope, defaultScope) {
+		await tx.execute({
+			sql: `DELETE FROM "${TABLE_KNOWLEDGE_MENTIONS}" WHERE sourceType=? AND sourceId=?`,
+			args: [sourceType, sourceId]
+		});
+		for (const name of parseKnowledgeWikilinks(text)) {
+			let node = await this.#resolveNode(tx, name, resolutionScope);
+			if (!node) {
+				node = await this.#getNodeByName(tx, name, defaultScope);
+				if (node) node = await this.#resolveTerminalNode(tx, node.id);
+				if (!node) {
+					const now = /* @__PURE__ */ new Date();
+					node = {
+						id: crypto.randomUUID(),
+						type: "node",
+						name,
+						kind: "node",
+						scope: defaultScope,
+						version: 1,
+						createdAt: now,
+						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,?,?)`,
+						args: [
+							node.id,
+							"node",
+							node.name,
+							canonicalName(node.name),
+							node.kind,
+							JSON.stringify(defaultScope),
+							knowledgeScopeKey(defaultScope),
+							1,
+							now.toISOString(),
+							now.toISOString()
+						]
+					});
+					await this.#activity(tx, "node-created", "node", node.id, defaultScope);
+					await this.#outbox(tx, "node", node.id, "upsert", 1, defaultScope);
+				}
+			}
+			await tx.execute({
+				sql: `INSERT INTO "${TABLE_KNOWLEDGE_MENTIONS}" (sourceType,sourceId,recordId) VALUES (?,?,?) ON CONFLICT DO NOTHING`,
+				args: [
+					sourceType,
+					sourceId,
+					node.id
+				]
+			});
+		}
+	}
+	async #activity(executor, action, recordType, recordId, scope, sourceThreadId) {
+		const now = /* @__PURE__ */ new Date();
+		await executor.execute({
+			sql: `INSERT INTO "${TABLE_KNOWLEDGE_ACTIVITY}" (id,action,recordType,recordId,scope,scopeKey,sourceThreadId,createdAt) VALUES (?,?,?,?,jsonb(?),?,?,?)`,
+			args: [
+				createKnowledgeUlid(),
+				action,
+				recordType,
+				recordId,
+				JSON.stringify(scope),
+				knowledgeScopeKey(scope),
+				sourceThreadId ?? null,
+				now.toISOString()
+			]
+		});
+	}
+	async #outbox(executor, documentType, id, operation, version, scope) {
+		const documentId = knowledgeSemanticDocumentId(documentType, id);
+		const idempotencyKey = knowledgeSemanticIdempotencyKey(documentId, operation, version);
+		const now = /* @__PURE__ */ new Date();
+		await executor.execute({
+			sql: `INSERT INTO "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" (id,idempotencyKey,documentId,documentType,operation,scope,scopeKey,status,attempts,availableAt,claimedAt,claimedBy,createdAt,completedAt) VALUES (?,?,?,?,?,jsonb(?),?,'pending',0,?,NULL,NULL,?,NULL) ON CONFLICT DO NOTHING`,
+			args: [
+				createKnowledgeUlid(),
+				idempotencyKey,
+				documentId,
+				documentType,
+				operation,
+				JSON.stringify(scope),
+				knowledgeScopeKey(scope),
+				now.toISOString(),
+				now.toISOString()
+			]
+		});
+	}
+};
+//#endregion
 //#region src/storage/domains/mcp-clients/index.ts
 const SNAPSHOT_FIELDS$5 = [
 	"name",
@@ -20750,6 +21721,38 @@ var PgFactoryStorageOps = class {
 * Supports serializable app-table transactions for cross-replica invariant
 * enforcement and `authDatabase()` exposing the shared pool.
 */
+/**
+* A pool-level `error` listener only covers *idle* clients: pg hands ownership
+* of a client to the borrower for the duration of a checkout and takes its own
+* listener off. So a backend restart or network blip that lands on a client
+* mid-transaction reaches an emitter with no listener, and Node escalates that
+* to an uncaughtException that kills the process — the pool handler logs the
+* idle siblings and the borrowed one still brings everything down.
+*
+* Attach a listener once per physical connection instead. `connect` fires when
+* the pool establishes a client, so the client stays covered for its whole life
+* and there is nothing to remove on release.
+*
+* That listener outlives the checkout, so it also sees the failures the pool is
+* already reporting through its own idle listener. Follow `acquire`/`release`
+* to tell the two apart and stay quiet while the client is idle — otherwise one
+* dropped connection is announced twice, the second time as the wrong thing.
+*
+* The pool still discards the failed connection; this only keeps the failure
+* reportable instead of fatal.
+*/
+function guardCheckedOutClientErrors(pool, warn = console.warn) {
+	const borrowed = /* @__PURE__ */ new WeakSet();
+	pool.on("connect", (client) => {
+		borrowed.add(client);
+		client.on("error", (err) => {
+			if (!borrowed.has(client)) return;
+			warn(`PgFactoryStorage: client error while checked out (the pool discards this connection): ${err instanceof Error ? err.message : String(err)}`);
+		});
+	});
+	pool.on("acquire", (client) => borrowed.add(client));
+	pool.on("release", (_err, client) => borrowed.delete(client));
+}
 var PgFactoryStorage = class extends FactoryStorage {
 	ops;
 	#pool;
@@ -20770,6 +21773,7 @@ var PgFactoryStorage = class extends FactoryStorage {
 			this.#pool.on("error", (err) => {
 				console.warn(`PgFactoryStorage: idle pool client error (pool discards the client and reconnects on next checkout): ${err instanceof Error ? err.message : String(err)}`);
 			});
+			guardCheckedOutClientErrors(this.#pool);
 		}
 		this.ops = new PgFactoryStorageOps(this.#pool, this.#schemas);
 	}
@@ -20899,6 +21903,7 @@ function createHostPool(config) {
 */
 const ALL_DOMAINS = [
 	MemoryPG,
+	KnowledgePG,
 	NotificationsPG,
 	ObservabilityPG,
 	ScoresPG,
@@ -20997,6 +22002,7 @@ var PostgresStore = class extends MastraCompositeStore {
 				workflows: new WorkflowsPG(domainConfig),
 				workflowDefinitions: new WorkflowDefinitionsPG(domainConfig),
 				memory: new MemoryPG(domainConfig),
+				knowledge: new KnowledgePG(domainConfig),
 				notifications: new NotificationsPG(domainConfig),
 				observability: new ObservabilityPG(domainConfig),
 				agents: new AgentsPG(domainConfig),
@@ -21321,6 +22327,6 @@ Example Complex Query:
   ]
 }`;
 //#endregion
-export { AgentsPG, BackgroundTasksPG, BlobsPG, ChannelsPG, DatasetsPG, ExperimentsPG, FavoritesPG, MCPClientsPG, MCPServersPG, MemoryPG, NotificationsPG, ObservabilityPG, ObservabilityStoragePostgresVNext, PGVECTOR_PROMPT, PgFactoryStorage, PgVector, PoolAdapter, PostgresStore, PostgresStoreVNext, PromptBlocksPG, SchedulesPG, ScorerDefinitionsPG, ScoresPG, SkillsPG, ThreadStatePG, ToolProviderConnectionsPG, WorkflowDefinitionsPG, WorkflowsPG, WorkspacesPG, exportSchemas };
+export { AgentsPG, BackgroundTasksPG, BlobsPG, ChannelsPG, DatasetsPG, ExperimentsPG, FavoritesPG, KnowledgePG, MCPClientsPG, MCPServersPG, MemoryPG, NotificationsPG, ObservabilityPG, ObservabilityStoragePostgresVNext, PGVECTOR_PROMPT, PgFactoryStorage, PgVector, PoolAdapter, PostgresStore, PostgresStoreVNext, PromptBlocksPG, SchedulesPG, ScorerDefinitionsPG, ScoresPG, SkillsPG, ThreadStatePG, ToolProviderConnectionsPG, WorkflowDefinitionsPG, WorkflowsPG, WorkspacesPG, exportSchemas };
 
 //# sourceMappingURL=index.js.map