@mastra/pg 1.34.0-alpha.1 → 1.35.0-alpha.0

package/dist/index.js

@@ -1,6 +1,6 @@
 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_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, assertWorkflowStepGuard, calculatePagination, canonicalizeKnowledgeScope, computeTraceStatus, createKnowledgeUlid, createStorageErrorId, createVectorErrorId, ensureDate, executeRetentionPrune, getDefaultValue, getSqlType, getStringAttribute, hasErrorCode, isKnowledgeScopeVisible, isRunFenceConflictError, isWorkflowStepConflictError, 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 { 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, 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_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, assertWorkflowStepGuard, calculatePagination, computeTraceStatus, createKnowledgeUlid, createStorageErrorId, createVectorErrorId, ensureDate, executeRetentionPrune, getDefaultValue, getSqlType, getStringAttribute, hasErrorCode, isRunFenceConflictError, isWorkflowStepConflictError, listBranchesArgsSchema, listFeedbackArgsSchema, listLogsArgsSchema, listMetricsArgsSchema, listScoresArgsSchema, listTracesArgsSchema, matchesExpectedWorkflowStatus, matchesRunFence, mergeWorkflowStepResult, normalizePerPage, normalizeScheduleTarget, parseDuration, 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";
@@ -10,7 +10,7 @@ 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, randomUUID } from "crypto";
+import { createHash } from "crypto";
 import { setTimeout as setTimeout$1 } from "timers/promises";
 import { coreFeatures } from "@mastra/core/features";
 import { MessageList } from "@mastra/core/agent";
@@ -387,7 +387,7 @@ const FILTER_OPERATORS = {
 		return {
 			sql,
 			needsValue: true,
-			transformValue: () => Array.isArray(value) ? value.map(String) : typeof value === "string" ? escapeLikePattern$1(value) : value
+			transformValue: () => Array.isArray(value) ? value.map(String) : typeof value === "string" ? escapeLikePattern(value) : value
 		};
 	},
 	/**
@@ -411,7 +411,7 @@ const FILTER_OPERATORS = {
 const parseJsonPathKey = (key) => {
 	return (key !== "" ? parseFieldKey(key) : "").replace(/\./g, ",");
 };
-function escapeLikePattern$1(str) {
+function escapeLikePattern(str) {
 	return str.replace(/([%_\\])/g, "\\$1");
 }
 /**
@@ -1080,42 +1080,43 @@ var PgVector = class extends MastraVector {
 			const scoreExpr = ops.scoreExpr(distanceExpr);
 			const filterClause = filterQuery.trim().replace(/^WHERE\s+/i, "");
 			const hasFilter = filterClause.length > 0;
-			const useIndexedOrder = indexInfo.type === "hnsw" && !hasFilter && minScore <= 0;
 			const namespaceParam = filterValues.length + 1;
-			const query = useIndexedOrder ? `
+			const queryValues = [...filterValues, namespace];
+			const selectColumns = `vector_id as id, ${scoreExpr} as score, metadata${includeVector ? ", embedding" : ""}`;
+			const whereClause = `WHERE namespace = $${namespaceParam}${filterClause ? ` AND (${filterClause})` : ""}`;
+			const useIndexedOrder = indexInfo.type === "hnsw" && (!hasFilter || this.supportsIterativeScan());
+			let rows;
+			if (useIndexedOrder) {
+				const indexedQuery = `
         WITH vector_scores AS (
-          SELECT
-            vector_id as id,
-            ${scoreExpr} as score,
-            metadata
-            ${includeVector ? ", embedding" : ""}
+          SELECT ${selectColumns}
           FROM ${tableName}
-          WHERE namespace = $${namespaceParam}
+          ${whereClause}
           ORDER BY ${distanceExpr}
           LIMIT $2
         )
-        SELECT *
+        SELECT *, score > $1 AS above_min_score
         FROM vector_scores
-        WHERE score > $1
-        ORDER BY score DESC` : `
+        ORDER BY score DESC`;
+				const candidates = (await client.query(indexedQuery, queryValues)).rows;
+				if (candidates.length >= topK) rows = candidates.filter((row) => row.above_min_score);
+			}
+			if (!rows) {
+				const exactQuery = `
         WITH vector_scores AS (
-          SELECT
-            vector_id as id,
-            ${scoreExpr} as score,
-            metadata
-            ${includeVector ? ", embedding" : ""}
+          SELECT ${selectColumns}
           FROM ${tableName}
-          WHERE namespace = $${namespaceParam}
-          ${filterClause ? `AND (${filterClause})` : ""}
+          ${whereClause}
         )
         SELECT *
         FROM vector_scores
         WHERE score > $1
         ORDER BY score DESC
         LIMIT $2`;
-			const result = await client.query(query, [...filterValues, namespace]);
+				rows = (await client.query(exactQuery, queryValues)).rows;
+			}
 			await client.query("COMMIT");
-			return result.rows.map(({ id, score, metadata, embedding }) => ({
+			return rows.map(({ id, score, metadata, embedding }) => ({
 				id,
 				score,
 				metadata,
@@ -1382,7 +1383,7 @@ var PgVector = class extends MastraVector {
 					indexConfig,
 					vectorType
 				}, client);
-				if (metadataIndexes?.length) await this.createMetadataIndexes(tableName, indexName, metadataIndexes);
+				if (metadataIndexes?.length) await this.createMetadataIndexes(client, tableName, indexName, metadataIndexes);
 			} catch (error) {
 				this.createdIndexes.delete(indexName);
 				this.namespaceReadyIndexes.delete(indexName);
@@ -1532,13 +1533,13 @@ var PgVector = class extends MastraVector {
 			await client.query(indexSQL);
 		});
 	}
-	async createMetadataIndexes(tableName, indexName, metadataFields) {
+	async createMetadataIndexes(client, tableName, indexName, metadataFields) {
 		const hasher = await this.hasher;
 		for (const field of metadataFields) {
 			const fieldHash = hasher.h32(field).toString(16);
 			const metadataIdxName = `"${indexName.slice(0, 55 - fieldHash.length)}_md_${fieldHash}_idx"`;
 			const escapedField = field.replace(/'/g, "''");
-			await this.pool.query(`
+			await client.query(`
         CREATE INDEX CONCURRENTLY IF NOT EXISTS ${metadataIdxName}
         ON ${tableName} ((metadata->>'${escapedField}'))
       `);
@@ -8517,976 +8518,1403 @@ var FavoritesPG = class FavoritesPG extends FavoritesStorage {
 		}
 	}
 };
-// ../../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
+const KNOWLEDGE_TABLE_NAMES = [
+	"mastra_knowledge_nodes",
+	"mastra_knowledge_records",
+	"mastra_knowledge_mentions",
+	"mastra_knowledge_activity",
+	"mastra_knowledge_semantic_outbox",
+	"mastra_knowledge_node_scopes",
+	"mastra_knowledge_record_scopes",
+	"mastra_knowledge_scope_grants",
+	"mastra_knowledge_access_state",
+	"mastra_knowledge_scope_addresses",
+	"mastra_knowledge_node_addresses",
+	"mastra_knowledge_import_state",
+	"mastra_knowledge_import_runs",
+	"mastra_knowledge_proposals"
+];
+/** Knowledge v1 tables with no v2 equivalent; an explicit schema reset drops them. */
+const RETIRED_KNOWLEDGE_TABLE_NAMES = ["mastra_knowledge_cursors"];
+const KNOWLEDGE_PAGES_CORE_FEATURE = "knowledge-pages";
+const KNOWLEDGE_PAGES_TABLE_NAMES = [
+	"mastra_knowledge_pages",
+	"mastra_knowledge_notes",
+	"mastra_knowledge_note_stamps",
+	"mastra_knowledge_mentions",
+	"mastra_knowledge_pins",
+	"mastra_knowledge_activity",
+	"mastra_knowledge_access_state"
+];
+/** Every Knowledge table any schema version created. Reset drops these and nothing else. */
+const KNOWLEDGE_RESETTABLE_TABLE_NAMES = [.../* @__PURE__ */ new Set([
+	...KNOWLEDGE_PAGES_TABLE_NAMES,
+	...KNOWLEDGE_TABLE_NAMES,
+	...RETIRED_KNOWLEDGE_TABLE_NAMES
+])];
+/** Schema-1/2 tables whose presence means the store needs a reset before schema 4 can run. */
+const LEGACY_KNOWLEDGE_TABLE_NAMES = new Set([...KNOWLEDGE_TABLE_NAMES, ...RETIRED_KNOWLEDGE_TABLE_NAMES].filter((name) => !KNOWLEDGE_PAGES_TABLE_NAMES.includes(name)));
+/**
+* Classifies what an adapter found before creating schema-4 tables. `tableNames` is every
+* `mastra_knowledge_*` table present; `schemaVersion` is the state row's version, if any.
+*/
+function inspectKnowledgePagesSchema(snapshot) {
+	const legacy = snapshot.tableNames.filter((name) => LEGACY_KNOWLEDGE_TABLE_NAMES.has(name));
+	if (legacy.length > 0) return {
+		status: "incompatible-reset-required",
+		schemaVersion: snapshot.schemaVersion ?? null,
+		reason: `found Knowledge tables from an earlier schema (${legacy.join(", ")})`
 	};
-	let value;
-	try {
-		value = JSON.parse(decodeURIComponent(input.cursor));
-	} catch {
-		throw new Error("Invalid Knowledge scope node cursor.");
+	if (snapshot.schemaVersion === 4) return {
+		status: "compatible",
+		schemaVersion: 4
+	};
+	if (snapshot.schemaVersion === void 0) {
+		const present = snapshot.tableNames.filter((name) => KNOWLEDGE_PAGES_TABLE_NAMES.includes(name));
+		if (present.length === 0) return {
+			status: "uninitialized",
+			schemaVersion: null
+		};
+		return {
+			status: "incompatible-reset-required",
+			schemaVersion: null,
+			reason: `found Knowledge tables (${present.join(", ")}) without a schema version`
+		};
 	}
-	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
-		}
+		status: "incompatible-reset-required",
+		schemaVersion: snapshot.schemaVersion,
+		reason: `Knowledge schema version ${snapshot.schemaVersion} is not 4`
 	};
 }
-/** 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
+/** Schema-2 table names schema 4 reuses with a different shape. */
+const REUSED_KNOWLEDGE_TABLE_NAMES = KNOWLEDGE_TABLE_NAMES.filter((name) => KNOWLEDGE_PAGES_TABLE_NAMES.includes(name));
+/**
+* The old Knowledge tables an adapter drops on init, rows included: Knowledge before schema 4 was an
+* experimental store with no migration. Every schema-1/2-only table present is dropped. The table
+* names schema 4 reuses (mentions, activity, the state table) are dropped too, but only when an old
+* table is present and no schema-4 state row exists, so they are old-shaped. Schema-4-only tables
+* are never listed. On a schema-4 store this lists only tables an older process recreated during a
+* rolling deploy. Drop order is safe for adapters that enforce references.
+*/
+function legacyKnowledgeTablesToDrop(snapshot) {
+	const present = new Set(snapshot.tableNames);
+	const legacy = [...LEGACY_KNOWLEDGE_TABLE_NAMES].filter((name) => present.has(name));
+	if (legacy.length === 0) return [];
+	const reused = snapshot.schemaVersion === 4 ? [] : REUSED_KNOWLEDGE_TABLE_NAMES.filter((name) => present.has(name));
+	const drop = /* @__PURE__ */ new Set([...legacy, ...reused]);
+	return [...RETIRED_KNOWLEDGE_TABLE_NAMES, ...[...KNOWLEDGE_TABLE_NAMES].reverse()].filter((name) => drop.has(name));
+}
+/** Message for the error an adapter throws on `incompatible-reset-required`. */
+function knowledgePagesResetMessage(reason) {
+	return `Knowledge storage needs a reset before this version can use it: ${reason}. Knowledge data has no migration; run \`await storage.stores?.knowledge?.dangerouslyReset()\` to drop the Knowledge tables (Memory tables are untouched).`;
+}
+const KNOWLEDGE_PAGES_CORE_FUNCTIONS = [
+	"assertKnowledgePageDescriptionWithinBound",
+	"assertKnowledgeNoteTextWithinBound",
+	"canonicalKnowledgeName",
+	"knowledgePositionBetween",
+	"KnowledgeMoveTooLargeError",
+	"KnowledgePageDepthError",
+	"KnowledgePageHasChildrenError",
+	"KnowledgePageKeyConflictError"
+];
+const KNOWLEDGE_PAGES_CORE_NUMBERS = [
+	"MAX_KNOWLEDGE_MOVE_PAGES",
+	"MAX_KNOWLEDGE_PAGE_DEPTH",
+	"MAX_KNOWLEDGE_PAGE_LIST_LIMIT"
+];
+function resolveKnowledgePagesCore(storageModule) {
+	const module = typeof storageModule === "object" && storageModule !== null ? storageModule : {};
+	const missing = [...KNOWLEDGE_PAGES_CORE_FUNCTIONS.filter((name) => typeof module[name] !== "function"), ...KNOWLEDGE_PAGES_CORE_NUMBERS.filter((name) => typeof module[name] !== "number")];
+	if (missing.length > 0) throw new Error(`@mastra/core advertises Knowledge pages without the required storage API (missing ${missing.join(", ")})`);
+	return module;
+}
+/** Loads core's page-store runtime once, after checking core advertises `knowledge-pages`. */
+function createKnowledgePagesCoreLoader(features, loadStorageModule) {
+	let core;
+	return async () => {
+		if (!features.has("knowledge-pages")) throw new Error(`Knowledge requires a @mastra/core release with the "${KNOWLEDGE_PAGES_CORE_FEATURE}" feature. Upgrade @mastra/core to use Knowledge; other storage domains keep working on this version.`);
+		core ??= loadStorageModule().then(resolveKnowledgePagesCore).catch((error) => {
+			core = void 0;
+			throw error;
+		});
+		return core;
 	};
 }
-/** 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);
+/**
+* Keyword-search words: the query split on whitespace, lowercased, deduplicated. Every word must
+* appear (as a case-insensitive substring) in a hit; an empty list means the search returns nothing.
+*/
+function knowledgeSearchWords(query) {
+	return [...new Set(query.toLowerCase().split(/\s+/).filter(Boolean))];
 }
-/** 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.");
+/**
+* Why `key` can't be a Knowledge page key, or undefined when it can. Keys are one path segment:
+* non-empty, with no `/` (path separator), `#` (scope/path separator) or `%` (escape character).
+*/
+function knowledgePageKeyProblem(key) {
+	if (!key) return "Knowledge page key must not be empty";
+	if (/[/#%]/.test(key)) return `Knowledge page key "${key}" must not contain "/", "#" or "%"`;
+}
+// src/storage/domains/knowledge/pages.ts
+const loadPagesCore = createKnowledgePagesCoreLoader(coreFeatures, () => import("@mastra/core/storage"));
+const DEFAULT_LIST_LIMIT = 50;
+const PG_UNIQUE_VIOLATION$1 = "23505";
+const PG_KNOWLEDGE_PAGES_TABLES = {
+	pages: "mastra_knowledge_pages",
+	notes: "mastra_knowledge_notes",
+	stamps: "mastra_knowledge_note_stamps",
+	mentions: "mastra_knowledge_mentions",
+	pins: "mastra_knowledge_pins",
+	activity: "mastra_knowledge_activity",
+	state: "mastra_knowledge_access_state"
+};
+/**
+* Schema-4 DDL. `COLLATE "C"` on every column that is ordered, prefix-matched or compared for
+* equality makes Postgres compare bytes, not locale rules, so address prefixes are case-sensitive and
+* names/positions sort in binary order regardless of the database's default collation.
+*/
+function pgKnowledgePagesDDL(schemaName) {
+	const q = qualifier(schemaName);
+	const t = PG_KNOWLEDGE_PAGES_TABLES;
+	const index = (name, table, columns, where = "", unique = false) => `CREATE ${unique ? "UNIQUE " : ""}INDEX IF NOT EXISTS "${name}" ON ${q(table)} (${columns})${where ? ` WHERE ${where}` : ""}`;
+	return [
+		`CREATE TABLE IF NOT EXISTS ${q(t.pages)} (
+      "id" text PRIMARY KEY,
+      "scopeId" text NOT NULL,
+      "parentId" text,
+      "isScope" boolean NOT NULL,
+      "address" text COLLATE "C",
+      "declaration" text COLLATE "C",
+      "key" text COLLATE "C",
+      "position" text COLLATE "C" NOT NULL,
+      "name" text COLLATE "C" NOT NULL,
+      "canonicalName" text COLLATE "C" NOT NULL,
+      "description" text,
+      "body" text,
+      "depth" integer NOT NULL,
+      "version" integer NOT NULL,
+      "mergedInto" text,
+      "createdBy" jsonb NOT NULL,
+      "updatedBy" jsonb NOT NULL,
+      "createdAt" timestamptz NOT NULL,
+      "updatedAt" timestamptz NOT NULL,
+      "deletedAt" timestamptz,
+      "deletedBy" text
+    )`,
+		`CREATE TABLE IF NOT EXISTS ${q(t.notes)} (
+      "id" text PRIMARY KEY,
+      "pageId" text NOT NULL REFERENCES ${q(t.pages)} ("id"),
+      "text" text NOT NULL,
+      "when" timestamptz,
+      "provenance" jsonb NOT NULL,
+      "version" integer NOT NULL,
+      "createdAt" timestamptz NOT NULL,
+      "updatedAt" timestamptz NOT NULL,
+      "deletedAt" timestamptz,
+      "deletedBy" text
+    )`,
+		`CREATE TABLE IF NOT EXISTS ${q(t.stamps)} (
+      "noteId" text NOT NULL REFERENCES ${q(t.notes)} ("id"),
+      "scopeId" text NOT NULL REFERENCES ${q(t.pages)} ("id"),
+      PRIMARY KEY ("noteId", "scopeId")
+    )`,
+		`CREATE TABLE IF NOT EXISTS ${q(t.mentions)} (
+      "noteId" text NOT NULL REFERENCES ${q(t.notes)} ("id"),
+      "pageId" text NOT NULL REFERENCES ${q(t.pages)} ("id"),
+      PRIMARY KEY ("noteId", "pageId")
+    )`,
+		`CREATE TABLE IF NOT EXISTS ${q(t.pins)} (
+      "id" text PRIMARY KEY,
+      "pageId" text NOT NULL UNIQUE REFERENCES ${q(t.pages)} ("id"),
+      "audience" text[] NOT NULL,
+      "createdBy" text NOT NULL,
+      "createdAt" timestamptz NOT NULL,
+      "updatedAt" timestamptz NOT NULL
+    )`,
+		`CREATE TABLE IF NOT EXISTS ${q(t.activity)} (
+      "id" text PRIMARY KEY,
+      "action" text NOT NULL,
+      "scopeId" text NOT NULL,
+      "pageId" text NOT NULL,
+      "noteId" text,
+      "provenance" jsonb NOT NULL,
+      "createdAt" timestamptz NOT NULL
+    )`,
+		`CREATE TABLE IF NOT EXISTS ${q(t.state)} (
+      "id" text PRIMARY KEY,
+      "schemaVersion" integer NOT NULL
+    )`,
+		index("mastra_knowledge_pages_address_uq", t.pages, "\"address\"", "\"isScope\"", true),
+		`DROP INDEX IF EXISTS ${q("mastra_knowledge_pages_key_uq")}`,
+		index("mastra_knowledge_pages_parent_key_uq", t.pages, "\"parentId\",\"key\"", "\"key\" IS NOT NULL AND \"deletedAt\" IS NULL", true),
+		index("mastra_knowledge_pages_scope_decl_parent_idx", t.pages, "\"declaration\",\"parentId\"", "\"isScope\""),
+		index("mastra_knowledge_pages_parent_idx", t.pages, "\"parentId\",\"position\",\"id\""),
+		index("mastra_knowledge_pages_scope_name_idx", t.pages, "\"scopeId\",\"name\",\"id\"", "\"deletedAt\" IS NULL"),
+		index("mastra_knowledge_pages_name_idx", t.pages, "\"name\",\"id\"", "\"deletedAt\" IS NULL AND NOT \"isScope\""),
+		index("mastra_knowledge_pages_canonical_idx", t.pages, "\"canonicalName\"", "\"deletedAt\" IS NULL"),
+		index("mastra_knowledge_notes_page_idx", t.notes, "\"pageId\",\"createdAt\",\"id\""),
+		index("mastra_knowledge_stamps_scope_idx", t.stamps, "\"scopeId\""),
+		index("mastra_knowledge_mentions_page_idx", t.mentions, "\"pageId\""),
+		`CREATE INDEX IF NOT EXISTS "mastra_knowledge_pins_audience_gin" ON ${q(t.pins)} USING gin ("audience")`,
+		index("mastra_knowledge_pins_created_idx", t.pins, "\"createdAt\",\"id\""),
+		index("mastra_knowledge_activity_page_idx", t.activity, "\"pageId\",\"createdAt\",\"id\""),
+		index("mastra_knowledge_activity_created_idx", t.activity, "\"createdAt\",\"id\"")
+	];
+}
+function qualifier(schemaName) {
+	return (table) => schemaName ? `"${schemaName}"."${table}"` : `"${table}"`;
+}
+/** Collects bind parameters and hands back their `$n` placeholders. */
+var Params = class {
+	values = [];
+	add(value) {
+		this.values.push(value);
+		return `$${this.values.length}`;
+	}
+};
+/**
+* The read scope as bound arrays, registered once per query so the same `$n` is reused for every
+* check in it. A large frontier travels as a handful of array parameters (`= ANY($n::text[])`,
+* `unnest`), never as a long `IN (...)` list.
+*/
+var ReadFilter = class {
+	#all;
+	#pages;
+	#addresses;
+	#prefixes;
+	#openPrefixes;
+	#children;
+	constructor(read, params, pages) {
+		this.#all = read === "all";
+		this.#pages = pages;
+		if (read === "all") return;
+		if (read.addresses.length) this.#addresses = `${params.add(read.addresses)}::text[]`;
+		const bounded = read.prefixes.filter((entry) => prefixUpperBound(entry.prefix) !== null);
+		const open = read.prefixes.filter((entry) => prefixUpperBound(entry.prefix) === null);
+		if (bounded.length) this.#prefixes = [
+			`${params.add(bounded.map((entry) => entry.declaration))}::text[]`,
+			`${params.add(bounded.map((entry) => entry.prefix))}::text[]`,
+			`${params.add(bounded.map((entry) => prefixUpperBound(entry.prefix)))}::text[]`
+		];
+		if (open.length) this.#openPrefixes = [`${params.add(open.map((entry) => entry.declaration))}::text[]`, `${params.add(open.map((entry) => entry.prefix))}::text[]`];
+		if (read.children.length) this.#children = [`${params.add(read.children.map((entry) => entry.declaration))}::text[]`, `${params.add(read.children.map((entry) => entry.parentId))}::text[]`];
+	}
+	/** Whether the filter admits every scope (no restriction to apply). */
+	get all() {
+		return this.#all;
+	}
+	/**
+	* The ids of every readable scope page, resolved through indexes: exact addresses hit the
+	* address index, prefixes become a binary range on it (`address >= prefix AND address < upper`,
+	* rechecked with `starts_with`; a prefix with no finite upper bound uses `>=` alone; the declaration test is `IS NOT DISTINCT FROM` on purpose so the
+	* planner walks the address range instead of every scope of that declaration, so `_` and `%` stay literal and matching stays case-sensitive),
+	* and one-hop children hit `(declaration, parentId)`.
+	*/
+	readableIds() {
+		if (this.#all) return `SELECT "id" FROM ${this.#pages} WHERE "isScope"`;
+		const branches = [];
+		if (this.#addresses) branches.push(`SELECT "id" FROM ${this.#pages} WHERE "isScope" AND "address" = ANY(${this.#addresses})`);
+		if (this.#prefixes) branches.push(`SELECT ps."id" FROM unnest(${this.#prefixes[0]}, ${this.#prefixes[1]}, ${this.#prefixes[2]}) AS pr("declaration", "prefix", "upper") JOIN ${this.#pages} ps ON ps."isScope" AND ps."address" >= pr."prefix" AND ps."address" < pr."upper" AND ps."declaration" IS NOT DISTINCT FROM pr."declaration" AND starts_with(ps."address", pr."prefix")`);
+		if (this.#openPrefixes) branches.push(`SELECT os."id" FROM unnest(${this.#openPrefixes[0]}, ${this.#openPrefixes[1]}) AS po("declaration", "prefix") JOIN ${this.#pages} os ON os."isScope" AND os."address" >= po."prefix" AND os."declaration" IS NOT DISTINCT FROM po."declaration" AND starts_with(os."address", po."prefix")`);
+		if (this.#children) branches.push(`SELECT cs."id" FROM unnest(${this.#children[0]}, ${this.#children[1]}) AS ch("declaration", "parentId") JOIN ${this.#pages} cs ON cs."isScope" AND cs."declaration" = ch."declaration" AND cs."parentId" = ch."parentId"`);
+		return branches.length ? branches.join(" UNION ") : `SELECT "id" FROM ${this.#pages} WHERE FALSE`;
 	}
-	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.");
+	/** True when a scope page aliased `scope` is readable. Matching is binary and case-sensitive. */
+	readable(scope) {
+		if (this.#all) return "TRUE";
+		return `${scope}."id" IN (${this.readableIds()})`;
+	}
+};
+/** Smallest string greater than every string starting with `prefix`, or null when none exists. */
+function prefixUpperBound(prefix) {
+	const points = Array.from(prefix);
+	const last = points.pop()?.codePointAt(0);
+	if (last === void 0 || last >= 1114111 || last >= 55295 && last < 57344) return null;
+	return points.join("") + String.fromCodePoint(last + 1);
+}
+function encodeCursor(parts) {
+	return Buffer.from(JSON.stringify(parts)).toString("base64url");
+}
+function decodeCursor(cursor, arity) {
+	try {
+		const parts = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+		if (Array.isArray(parts) && parts.length === arity && parts.every((part) => typeof part === "string")) return parts;
+	} catch {}
+	throw new Error("Invalid Knowledge cursor");
+}
+function clampLimit(limit, max) {
+	const value = limit ?? DEFAULT_LIST_LIMIT;
+	if (!Number.isInteger(value) || value < 1) throw new Error("Knowledge list limit must be a positive integer");
+	return Math.min(value, max);
+}
+function iso(value) {
+	return value.toISOString();
+}
+function optionalDate(value) {
+	return value == null ? void 0 : new Date(value);
+}
+function parseJson$1(value) {
+	return typeof value === "string" ? JSON.parse(value) : value;
+}
+function toPage(row) {
 	return {
-		limit,
-		after: {
-			updatedAt,
-			name: parsed.name,
-			id: parsed.id
-		}
+		id: String(row.id),
+		scopeId: String(row.scopeId),
+		parentId: row.parentId == null ? null : String(row.parentId),
+		isScope: row.isScope === true,
+		...row.address == null ? {} : { address: String(row.address) },
+		...row.declaration == null ? {} : { declaration: String(row.declaration) },
+		...row.key == null ? {} : { key: String(row.key) },
+		position: String(row.position),
+		name: String(row.name),
+		...row.description == null ? {} : { description: String(row.description) },
+		...row.body == null ? {} : { body: String(row.body) },
+		version: Number(row.version),
+		...row.mergedInto == null ? {} : { mergedInto: String(row.mergedInto) },
+		createdBy: parseJson$1(row.createdBy),
+		updatedBy: parseJson$1(row.updatedBy),
+		createdAt: new Date(row.createdAt),
+		updatedAt: new Date(row.updatedAt),
+		...row.deletedAt == null ? {} : { deletedAt: new Date(row.deletedAt) },
+		...row.deletedBy == null ? {} : { deletedBy: String(row.deletedBy) }
 	};
 }
-/** 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;
+function toNote(row) {
+	const when = optionalDate(row.when);
+	const deletedAt = optionalDate(row.deletedAt);
 	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
+		id: String(row.id),
+		pageId: String(row.pageId),
+		text: String(row.text),
+		...when ? { when } : {},
+		stampScopeIds: row.stampScopeIds ?? [],
+		mentions: row.mentions ?? [],
+		provenance: parseJson$1(row.provenance),
+		version: Number(row.version),
+		createdAt: new Date(row.createdAt),
+		updatedAt: new Date(row.updatedAt),
+		...deletedAt ? { deletedAt } : {},
+		...row.deletedBy == null ? {} : { deletedBy: String(row.deletedBy) }
 	};
 }
-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
+function toPin(row) {
+	return {
+		id: String(row.id),
+		pageId: String(row.pageId),
+		audience: row.audience ?? [],
+		createdBy: String(row.createdBy),
+		createdAt: new Date(row.createdAt),
+		updatedAt: new Date(row.updatedAt)
+	};
+}
+function toListedPin(row) {
+	return {
+		...toPin(row),
+		pageName: String(row.pageName)
+	};
+}
+function escapeLike(term) {
+	return term.replace(/[\\%_]/g, (match) => `\\${match}`);
+}
+function isUniqueViolation$1(error) {
+	return typeof error === "object" && error !== null && error.code === PG_UNIQUE_VIOLATION$1;
+}
+/**
+* Postgres implementation of the schema-4 {@link KnowledgePageStore}.
+*
+* Visibility is computed with live joins (a note's page home scope, its stamps, its mentioned pages'
+* current home scopes), so a move or merge, which rewrites `scopeId` on the moved pages in the same
+* transaction, can never leave a stale denormalized copy.
+*/
+var PgKnowledgePages = class {
+	#client;
+	#schemaName;
+	#bounds;
+	#q;
+	constructor(options) {
+		this.#client = options.client;
+		this.#schemaName = options.schemaName;
+		this.#bounds = options.bounds;
+		this.#q = qualifier(options.schemaName);
+	}
+	get #pages() {
+		return this.#q(PG_KNOWLEDGE_PAGES_TABLES.pages);
+	}
+	get #notes() {
+		return this.#q(PG_KNOWLEDGE_PAGES_TABLES.notes);
+	}
+	get #stamps() {
+		return this.#q(PG_KNOWLEDGE_PAGES_TABLES.stamps);
+	}
+	get #mentions() {
+		return this.#q(PG_KNOWLEDGE_PAGES_TABLES.mentions);
+	}
+	get #pins() {
+		return this.#q(PG_KNOWLEDGE_PAGES_TABLES.pins);
+	}
+	get #activity() {
+		return this.#q(PG_KNOWLEDGE_PAGES_TABLES.activity);
+	}
+	async #rows(db, sql, params = []) {
+		return (await db.query(sql, params)).rows;
+	}
+	#tx(operation) {
+		return this.#client.tx(operation);
+	}
+	/** The read-side `FROM` for notes: the note, its page, and the page's home scope. */
+	#visibleNotes(filter, alias = "n") {
+		return `${this.#notes} ${alias}
+      JOIN ${this.#pages} np ON np."id" = ${alias}."pageId"
+      JOIN ${this.#pages} nps ON nps."id" = np."scopeId"
+      WHERE ${filter.readable("nps")}
+        AND EXISTS (SELECT 1 FROM ${this.#stamps} st JOIN ${this.#pages} sts ON sts."id" = st."scopeId" WHERE st."noteId" = ${alias}."id" AND ${filter.readable("sts")})
+        AND NOT EXISTS (SELECT 1 FROM ${this.#mentions} mn JOIN ${this.#pages} mp ON mp."id" = mn."pageId" JOIN ${this.#pages} mps ON mps."id" = mp."scopeId" WHERE mn."noteId" = ${alias}."id" AND NOT ${filter.readable("mps")})`;
+	}
+	/** Same note visibility as a bare predicate, for filters that start from another table. */
+	#noteVisible(filter, noteIdColumn) {
+		return `EXISTS (SELECT 1 FROM ${this.#notes} vn JOIN ${this.#pages} vp ON vp."id" = vn."pageId" JOIN ${this.#pages} vps ON vps."id" = vp."scopeId"
+        WHERE vn."id" = ${noteIdColumn} AND ${filter.readable("vps")}
+        AND EXISTS (SELECT 1 FROM ${this.#stamps} vst JOIN ${this.#pages} vsts ON vsts."id" = vst."scopeId" WHERE vst."noteId" = vn."id" AND ${filter.readable("vsts")})
+        AND NOT EXISTS (SELECT 1 FROM ${this.#mentions} vmn JOIN ${this.#pages} vmp ON vmp."id" = vmn."pageId" JOIN ${this.#pages} vmps ON vmps."id" = vmp."scopeId" WHERE vmn."noteId" = vn."id" AND NOT ${filter.readable("vmps")}))`;
+	}
+	#noteColumns(alias = "n") {
+		return `${alias}.*,
+      ARRAY(SELECT st."scopeId" FROM ${this.#stamps} st WHERE st."noteId" = ${alias}."id" ORDER BY st."scopeId") AS "stampScopeIds",
+      ARRAY(SELECT mn."pageId" FROM ${this.#mentions} mn WHERE mn."noteId" = ${alias}."id" ORDER BY mn."pageId") AS "mentions"`;
+	}
+	async #logActivity(db, event) {
+		await db.query(`INSERT INTO ${this.#activity} ("id","action","scopeId","pageId","noteId","provenance","createdAt") VALUES ($1,$2,$3,$4,$5,$6::jsonb,$7)`, [
+			createKnowledgeUlid(),
+			event.action,
+			event.scopeId,
+			event.pageId,
+			event.noteId ?? null,
+			JSON.stringify(event.provenance),
+			iso(event.at)
+		]);
 	}
-};
-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
+	async #lockPage(db, id) {
+		const rows = await this.#rows(db, `SELECT * FROM ${this.#pages} WHERE "id" = $1 FOR UPDATE`, [id]);
+		return rows[0] ? toPage(rows[0]) : null;
+	}
+	async #requireLivePage(db, id, lock = true) {
+		const rows = await this.#rows(db, `SELECT * FROM ${this.#pages} WHERE "id" = $1${lock ? " FOR UPDATE" : ""}`, [id]);
+		const page = rows[0] ? toPage(rows[0]) : null;
+		if (!page || page.deletedAt) throw new KnowledgeNotFoundError("page", id);
+		return page;
+	}
+	/** Position after the last live child of `parentId`. */
+	async #lastPosition(db, parentId) {
+		const rows = await this.#rows(db, parentId === null ? `SELECT "position" FROM ${this.#pages} WHERE "parentId" IS NULL AND "deletedAt" IS NULL ORDER BY "position" DESC LIMIT 1` : `SELECT "position" FROM ${this.#pages} WHERE "parentId" = $1 AND "deletedAt" IS NULL ORDER BY "position" DESC LIMIT 1`, parentId === null ? [] : [parentId]);
+		return rows[0] ? String(rows[0].position) : void 0;
+	}
+	/** Ordinary descendants of `rootId` (excluding it), as a recursive CTE named `sub`. */
+	#subtree(rootParam) {
+		return `WITH RECURSIVE sub("id") AS (
+      SELECT c."id" FROM ${this.#pages} c WHERE c."parentId" = ${rootParam} AND NOT c."isScope"
+      UNION ALL
+      SELECT c."id" FROM ${this.#pages} c JOIN sub ON c."parentId" = sub."id" WHERE NOT c."isScope"
+    )`;
 	}
-};
-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
+	/** Live descendants, capped, and the deepest live level. */
+	async #subtreeStats(db, rootId) {
+		const core = await loadPagesCore();
+		const rows = await this.#rows(db, `${this.#subtree("$1")}
+       SELECT (SELECT count(*) FROM (SELECT 1 FROM sub JOIN ${this.#pages} p ON p."id" = sub."id" WHERE p."deletedAt" IS NULL LIMIT ${core.MAX_KNOWLEDGE_MOVE_PAGES + 1}) l) AS live,
+              (SELECT COALESCE(max(p."depth"), 0) FROM sub JOIN ${this.#pages} p ON p."id" = sub."id" WHERE p."deletedAt" IS NULL) AS "maxDepth"`, [rootId]);
+		return {
+			live: Number(rows[0]?.live ?? 0),
+			maxDepth: Number(rows[0]?.maxDepth ?? 0)
+		};
 	}
-};
-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
+	/**
+	* Refuses before any write when a live page arriving under `parentId` has a key a live child of
+	* `parentId` already uses: the moved root itself, or, for a merge, the source's live children.
+	*/
+	async #assertNoKeyConflicts(db, arriving, parentId, exceptId) {
+		const core = await loadPagesCore();
+		const arrivingWhere = arriving.rootId ? `c."id" = $1` : `c."parentId" = $1 AND NOT c."isScope"`;
+		const rows = await this.#rows(db, `SELECT c."key" FROM ${this.#pages} c
+       JOIN ${this.#pages} t ON t."parentId" = $2 AND t."key" = c."key" AND t."deletedAt" IS NULL AND t."id" <> c."id" AND t."id" IS DISTINCT FROM $3::text
+       WHERE ${arrivingWhere} AND c."key" IS NOT NULL AND c."deletedAt" IS NULL
+       LIMIT 1`, [
+			arriving.rootId ?? arriving.childrenOf,
+			parentId,
+			exceptId ?? null
+		]);
+		if (rows[0]) throw new core.KnowledgePageKeyConflictError(String(rows[0].key), parentId);
+	}
+	async #isInSubtree(db, rootId, candidateId) {
+		return (await this.#rows(db, `${this.#subtree("$1")} SELECT 1 FROM sub WHERE "id" = $2 LIMIT 1`, [rootId, candidateId])).length > 0;
+	}
+	async materializeScope(input) {
+		const bounds = await this.#bounds();
+		bounds.assertKnowledgePageDescriptionWithinBound(input.description);
+		for (const child of input.children ?? []) bounds.assertKnowledgePageDescriptionWithinBound(child.description);
+		const checkTemplates = (templates) => {
+			for (const template of templates) {
+				bounds.assertKnowledgePageDescriptionWithinBound(template.description);
+				checkTemplates(template.pages ?? []);
+			}
+		};
+		checkTemplates(input.pages ?? []);
+		return this.#tx(async (tx) => {
+			await tx.query("SELECT pg_advisory_xact_lock(hashtext($1))", [`mastra-knowledge-scope:${this.#schemaName ?? ""}:${input.address}`]);
+			const now = /* @__PURE__ */ new Date();
+			let scope = await this.#scopeByAddress(tx, input.address);
+			let created = false;
+			let parentConflict;
+			if (!scope) {
+				if (input.parentId) await this.#requireLivePage(tx, input.parentId, false);
+				scope = await this.#insertScope(tx, {
+					address: input.address,
+					declaration: input.declaration,
+					name: input.name,
+					description: input.description,
+					parentId: input.parentId ?? null,
+					provenance: input.provenance,
+					at: now
+				});
+				created = true;
+			} else if (input.parentId && scope.parentId === null) {
+				await this.#requireLivePage(tx, input.parentId, false);
+				scope = toPage((await this.#rows(tx, `UPDATE ${this.#pages} SET "parentId" = $2 WHERE "id" = $1 AND "parentId" IS NULL RETURNING *`, [scope.id, input.parentId]))[0]);
+			} else if (input.parentId !== void 0 && (input.parentId ?? null) !== scope.parentId) parentConflict = {
+				existingParentId: scope.parentId,
+				requestedParentId: input.parentId ?? null
+			};
+			for (const child of input.children ?? []) {
+				await tx.query("SELECT pg_advisory_xact_lock(hashtext($1))", [`mastra-knowledge-scope:${this.#schemaName ?? ""}:${child.address}`]);
+				if (await this.#scopeByAddress(tx, child.address)) continue;
+				await this.#insertScope(tx, {
+					address: child.address,
+					declaration: child.declaration,
+					name: child.name,
+					description: child.description,
+					parentId: scope.id,
+					provenance: input.provenance,
+					at: now
+				});
+			}
+			await this.#materializeTemplates(tx, scope, input.pages ?? [], input.provenance, now);
+			return {
+				scope,
+				created,
+				...parentConflict ? { parentConflict } : {}
+			};
+		});
 	}
-};
-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
+	async #materializeTemplates(db, parent, templates, provenance, at) {
+		await loadPagesCore();
+		for (const template of templates) {
+			const problem = knowledgePageKeyProblem(template.key);
+			if (problem) throw new Error(problem);
+			const rows = await this.#rows(db, `SELECT * FROM ${this.#pages} WHERE "parentId" = $1 AND "key" = $2 AND "deletedAt" IS NULL`, [parent.id, template.key]);
+			const page = rows[0] === void 0 ? await this.#insertPage(db, {
+				parent,
+				key: template.key,
+				name: template.name,
+				description: template.description,
+				provenance,
+				at
+			}) : toPage(rows[0]);
+			if (template.pages?.length) await this.#materializeTemplates(db, page, template.pages, provenance, at);
+		}
+	}
+	async #scopeByAddress(db, address) {
+		const rows = await this.#rows(db, `SELECT * FROM ${this.#pages} WHERE "isScope" AND "address" = $1`, [address]);
+		return rows[0] ? toPage(rows[0]) : null;
+	}
+	async #insertScope(db, input) {
+		const core = await loadPagesCore();
+		const id = createKnowledgeUlid();
+		const position = core.knowledgePositionBetween(await this.#lastPosition(db, input.parentId));
+		const rows = await this.#rows(db, `INSERT INTO ${this.#pages} ("id","scopeId","parentId","isScope","address","declaration","position","name","canonicalName","description","depth","version","createdBy","updatedBy","createdAt","updatedAt")
+       VALUES ($1,$1,$2,TRUE,$3,$4,$5,$6,$7,$8,0,1,$9::jsonb,$9::jsonb,$10,$10) RETURNING *`, [
+			id,
+			input.parentId,
+			input.address,
+			input.declaration,
+			position,
+			input.name,
+			core.canonicalKnowledgeName(input.name),
+			input.description ?? null,
+			JSON.stringify(input.provenance),
+			iso(input.at)
+		]);
+		await this.#logActivity(db, {
+			action: "scope-created",
+			scopeId: id,
+			pageId: id,
+			provenance: input.provenance,
+			at: input.at
+		});
+		return toPage(rows[0]);
+	}
+	async getScopesByAddress(addresses) {
+		if (addresses.length === 0) return [];
+		const rows = await this.#rows(this.#client, `SELECT * FROM ${this.#pages} WHERE "isScope" AND "address" = ANY($1::text[])`, [addresses]);
+		const byAddress = new Map(rows.map((row) => [String(row.address), toPage(row)]));
+		return [...new Set(addresses)].flatMap((address) => byAddress.get(address) ?? []);
+	}
+	async listScopeDeclarations() {
+		return (await this.#rows(this.#client, `SELECT "declaration", COUNT(*)::int AS "scopes" FROM ${this.#pages}
+       WHERE "isScope" AND "declaration" IS NOT NULL
+       GROUP BY "declaration" ORDER BY "declaration" COLLATE "C"`, [])).map((row) => ({
+			declaration: String(row.declaration),
+			scopes: Number(row.scopes)
+		}));
 	}
-};
-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"
+	async renameScopeDeclaration(input) {
+		return this.#tx(async (tx) => {
+			const rows = await this.#rows(tx, `SELECT "id", "address", "declaration" FROM ${this.#pages}
+         WHERE "isScope" AND ("declaration" = $1 OR starts_with("declaration", $2))
+         ORDER BY "id" FOR UPDATE`, [input.from, `${input.from}/`]);
+			if (rows.length === 0) return 0;
+			const renames = rows.map((row) => ({
+				address: String(row.address),
+				from: String(row.declaration),
+				to: input.to + String(row.declaration).slice(input.from.length)
+			}));
+			input.check(renames);
+			await tx.query(`UPDATE ${this.#pages} p SET "declaration" = r."to"
+         FROM unnest($1::text[], $2::text[]) AS r("id", "to") WHERE p."id" = r."id"`, [rows.map((row) => String(row.id)), renames.map((rename) => rename.to)]);
+			return rows.length;
+		});
+	}
+	async listChildScopes(input) {
+		const core = await loadPagesCore();
+		const limit = clampLimit(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
+		const params = new Params();
+		const where = [`"isScope"`, `"deletedAt" IS NULL`];
+		where.push(input.parentId === null ? `"parentId" IS NULL` : `"parentId" = ${params.add(input.parentId)}`);
+		if (input.cursor) {
+			const [position, id] = decodeCursor(input.cursor, 2);
+			where.push(`("position", "id") > (${params.add(position)}, ${params.add(id)})`);
 		}
-	},
-	role: {
-		type: "text",
-		nullable: false
-	},
-	canSuggest: {
-		type: "boolean",
-		nullable: true
+		const rows = await this.#rows(this.#client, `SELECT * FROM ${this.#pages} WHERE ${where.join(" AND ")} ORDER BY "position", "id" LIMIT ${limit + 1}`, params.values);
+		return this.#pageOutput(rows, limit, (page) => [page.position, page.id]);
 	}
-};
-const KNOWLEDGE_ACCESS_STATE_SCHEMA = {
-	id: {
-		type: "text",
-		nullable: false,
-		primaryKey: true
-	},
-	epoch: {
-		type: "integer",
-		nullable: false
-	},
-	schemaVersion: {
-		type: "integer",
-		nullable: false
+	#pageOutput(rows, limit, cursorOf) {
+		const pages = rows.slice(0, limit).map(toPage);
+		const last = pages[pages.length - 1];
+		return {
+			pages,
+			...rows.length > limit && last ? { nextCursor: encodeCursor(cursorOf(last)) } : {}
+		};
 	}
-};
-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"
-		}
+	async getPage(input) {
+		const params = new Params();
+		const id = params.add(input.id);
+		const filter = new ReadFilter(input.read, params, this.#pages);
+		const rows = await this.#rows(this.#client, `SELECT p.* FROM ${this.#pages} p JOIN ${this.#pages} s ON s."id" = p."scopeId" WHERE p."id" = ${id} AND ${filter.readable("s")}`, params.values);
+		return rows[0] ? toPage(rows[0]) : null;
+	}
+	async getPageByPath(input) {
+		if (!input.path.length) return null;
+		let page;
+		let parentId = input.scopeId;
+		for (const key of input.path) {
+			const params = new Params();
+			const filter = new ReadFilter(input.read, params, this.#pages);
+			const rows = await this.#rows(this.#client, `SELECT p.* FROM ${this.#pages} p JOIN ${this.#pages} s ON s."id" = p."scopeId"
+         WHERE p."parentId" = ${params.add(parentId)} AND p."key" = ${params.add(key)} AND p."deletedAt" IS NULL AND NOT p."isScope" AND ${filter.readable("s")}`, params.values);
+			if (!rows[0]) return null;
+			page = toPage(rows[0]);
+			parentId = page.id;
+		}
+		return page ?? null;
+	}
+	async findPagesByName(input) {
+		const core = await loadPagesCore();
+		const limit = clampLimit(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
+		const params = new Params();
+		const where = [`p."canonicalName" = ${params.add(core.canonicalKnowledgeName(input.name))}`, `p."deletedAt" IS NULL`];
+		if (input.scopeId) where.push(`p."scopeId" = ${params.add(input.scopeId)}`);
+		const filter = new ReadFilter(input.read, params, this.#pages);
+		where.push(filter.readable("s"));
+		return (await this.#rows(this.#client, `SELECT p.* FROM ${this.#pages} p JOIN ${this.#pages} s ON s."id" = p."scopeId"
+       WHERE ${where.join(" AND ")} ORDER BY p."createdAt" DESC, p."id" DESC LIMIT ${limit}`, params.values)).map(toPage);
+	}
+	async listChildPages(input) {
+		const core = await loadPagesCore();
+		const limit = clampLimit(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
+		const params = new Params();
+		const where = [
+			`p."parentId" = ${params.add(input.parentId)}`,
+			`NOT p."isScope"`,
+			`p."deletedAt" IS NULL`
+		];
+		const filter = new ReadFilter(input.read, params, this.#pages);
+		where.push(filter.readable("s"));
+		if (input.cursor) {
+			const [position, id] = decodeCursor(input.cursor, 2);
+			where.push(`(p."position", p."id") > (${params.add(position)}, ${params.add(id)})`);
+		}
+		const rows = await this.#rows(this.#client, `SELECT p.* FROM ${this.#pages} p JOIN ${this.#pages} s ON s."id" = p."scopeId"
+       WHERE ${where.join(" AND ")} ORDER BY p."position", p."id" LIMIT ${limit + 1}`, params.values);
+		return this.#pageOutput(rows, limit, (page) => [page.position, page.id]);
+	}
+	async listPages(input) {
+		const core = await loadPagesCore();
+		const limit = clampLimit(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
+		const params = new Params();
+		const filter = new ReadFilter(input.read, params, this.#pages);
+		const where = [
+			`p."scopeId" = r."id"`,
+			`NOT p."isScope"`,
+			`p."deletedAt" IS NULL`
+		];
+		if (input.namePrefix) where.push(`starts_with(p."canonicalName", ${params.add(core.canonicalKnowledgeName(input.namePrefix))})`);
+		if (input.cursor) {
+			const [name, id] = decodeCursor(input.cursor, 2);
+			where.push(`(p."name", p."id") > (${params.add(name)}, ${params.add(id)})`);
+		}
+		if (filter.all) {
+			const direct = where.slice(1);
+			if (input.scopeId) direct.unshift(`p."scopeId" = ${params.add(input.scopeId)}`);
+			const rows = await this.#rows(this.#client, `SELECT p.* FROM ${this.#pages} p WHERE ${direct.join(" AND ")} ORDER BY p."name", p."id" LIMIT ${limit + 1}`, params.values);
+			return this.#pageOutput(rows, limit, (page) => [page.name, page.id]);
+		}
+		const scopes = input.scopeId ? `SELECT "id" FROM (${filter.readableIds()}) ri WHERE "id" = ${params.add(input.scopeId)}` : filter.readableIds();
+		const rows = await this.#rows(this.#client, `SELECT x.* FROM (${scopes}) r CROSS JOIN LATERAL (
+         SELECT p.* FROM ${this.#pages} p WHERE ${where.join(" AND ")} ORDER BY p."name", p."id" LIMIT ${limit + 1}
+       ) x ORDER BY x."name", x."id" LIMIT ${limit + 1}`, params.values);
+		return this.#pageOutput(rows, limit, (page) => [page.name, page.id]);
+	}
+	async createPage(input) {
+		(await this.#bounds()).assertKnowledgePageDescriptionWithinBound(input.description);
+		await loadPagesCore();
+		if (input.key !== void 0) {
+			const problem = knowledgePageKeyProblem(input.key);
+			if (problem) throw new Error(problem);
+		}
+		return this.#tx(async (tx) => {
+			const parent = await this.#requireLivePage(tx, input.parentId);
+			return this.#insertPage(tx, {
+				id: input.id,
+				parent,
+				key: input.key,
+				name: input.name,
+				description: input.description,
+				body: input.body,
+				position: input.position,
+				provenance: input.provenance,
+				at: /* @__PURE__ */ new Date()
+			});
+		});
 	}
-};
-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"
+	async #insertPage(db, input) {
+		const core = await loadPagesCore();
+		const id = input.id ?? createKnowledgeUlid();
+		const scopeId = input.parent.isScope ? input.parent.id : input.parent.scopeId;
+		const depth = input.parent.isScope ? 1 : await this.#depthOf(db, input.parent.id) + 1;
+		if (depth > core.MAX_KNOWLEDGE_PAGE_DEPTH) throw new core.KnowledgePageDepthError(id);
+		const position = input.position ?? core.knowledgePositionBetween(await this.#lastPosition(db, input.parent.id));
+		try {
+			const rows = await this.#rows(db, `INSERT INTO ${this.#pages} ("id","scopeId","parentId","isScope","key","position","name","canonicalName","description","body","depth","version","createdBy","updatedBy","createdAt","updatedAt")
+         VALUES ($1,$2,$3,FALSE,$4,$5,$6,$7,$8,$9,$10,1,$11::jsonb,$11::jsonb,$12,$12) RETURNING *`, [
+				id,
+				scopeId,
+				input.parent.id,
+				input.key ?? null,
+				position,
+				input.name,
+				core.canonicalKnowledgeName(input.name),
+				input.description ?? null,
+				input.body ?? null,
+				depth,
+				JSON.stringify(input.provenance),
+				iso(input.at)
+			]);
+			await this.#logActivity(db, {
+				action: "page-created",
+				scopeId,
+				pageId: id,
+				provenance: input.provenance,
+				at: input.at
+			});
+			return toPage(rows[0]);
+		} catch (error) {
+			if (isUniqueViolation$1(error)) {
+				if (input.key) throw new core.KnowledgePageKeyConflictError(input.key, input.parent.id);
+				throw new KnowledgeConflictError(id);
+			}
+			throw error;
 		}
 	}
-};
-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
+	async #depthOf(db, id) {
+		const rows = await this.#rows(db, `SELECT "depth" FROM ${this.#pages} WHERE "id" = $1`, [id]);
+		return Number(rows[0]?.depth ?? 0);
 	}
-};
-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
+	async updatePage(input) {
+		const core = await loadPagesCore();
+		(await this.#bounds()).assertKnowledgePageDescriptionWithinBound(input.description);
+		return this.#tx(async (tx) => {
+			const page = await this.#requireLivePage(tx, input.id);
+			if (page.version !== input.expectedVersion) throw new KnowledgeConflictError(input.id);
+			const now = /* @__PURE__ */ new Date();
+			const sets = [
+				`"version" = "version" + 1`,
+				`"updatedAt" = $2`,
+				`"updatedBy" = $3::jsonb`
+			];
+			const params = new Params();
+			params.add(input.id);
+			params.add(iso(now));
+			params.add(JSON.stringify(input.provenance));
+			if (input.name !== void 0) sets.push(`"name" = ${params.add(input.name)}`, `"canonicalName" = ${params.add(core.canonicalKnowledgeName(input.name))}`);
+			if (input.description !== void 0) sets.push(`"description" = ${params.add(input.description === "" ? null : input.description)}`);
+			if (input.body !== void 0) sets.push(`"body" = ${params.add(input.body)}`);
+			const rows = await this.#rows(tx, `UPDATE ${this.#pages} SET ${sets.join(", ")} WHERE "id" = $1 RETURNING *`, params.values);
+			await this.#logActivity(tx, {
+				action: "page-updated",
+				scopeId: page.scopeId,
+				pageId: page.id,
+				provenance: input.provenance,
+				at: now
+			});
+			return toPage(rows[0]);
+		});
+	}
+	async movePage(input) {
+		const core = await loadPagesCore();
+		return this.#tx(async (tx) => {
+			const page = await this.#requireLivePage(tx, input.id);
+			if (page.version !== input.expectedVersion) throw new KnowledgeConflictError(input.id);
+			if (page.isScope) throw new Error(`Knowledge scope page ${input.id} can't be moved`);
+			if (input.parentId === input.id || await this.#isInSubtree(tx, input.id, input.parentId)) throw new Error(`Knowledge page ${input.id} can't move under itself or its own subtree`);
+			const parent = await this.#requireLivePage(tx, input.parentId);
+			const stats = await this.#subtreeStats(tx, input.id);
+			if (stats.live + 1 > core.MAX_KNOWLEDGE_MOVE_PAGES) throw new core.KnowledgeMoveTooLargeError(input.id, stats.live + 1);
+			const newScopeId = parent.isScope ? parent.id : parent.scopeId;
+			const newDepth = parent.isScope ? 1 : await this.#depthOf(tx, parent.id) + 1;
+			const delta = newDepth - await this.#depthOf(tx, page.id);
+			await this.#assertNoKeyConflicts(tx, { rootId: input.id }, parent.id);
+			if (stats.maxDepth + delta > core.MAX_KNOWLEDGE_PAGE_DEPTH || newDepth > core.MAX_KNOWLEDGE_PAGE_DEPTH) throw new core.KnowledgePageDepthError(input.id);
+			const position = input.position ?? core.knowledgePositionBetween(await this.#lastPosition(tx, parent.id));
+			const now = /* @__PURE__ */ new Date();
+			try {
+				await tx.query(`${this.#subtree("$1")} UPDATE ${this.#pages} SET "scopeId" = $2, "depth" = "depth" + $3 WHERE "id" IN (SELECT "id" FROM sub)`, [
+					input.id,
+					newScopeId,
+					delta
+				]);
+				const rows = await this.#rows(tx, `UPDATE ${this.#pages} SET "parentId" = $2, "scopeId" = $3, "depth" = $4, "position" = $5, "version" = "version" + 1, "updatedAt" = $6, "updatedBy" = $7::jsonb WHERE "id" = $1 RETURNING *`, [
+					input.id,
+					parent.id,
+					newScopeId,
+					newDepth,
+					position,
+					iso(now),
+					JSON.stringify(input.provenance)
+				]);
+				await this.#logActivity(tx, {
+					action: "page-moved",
+					scopeId: newScopeId,
+					pageId: input.id,
+					provenance: input.provenance,
+					at: now
+				});
+				return toPage(rows[0]);
+			} catch (error) {
+				if (isUniqueViolation$1(error)) throw new KnowledgeConflictError(page.key ? `${newScopeId}#${page.key}` : input.id);
+				throw error;
+			}
+		});
 	}
-};
-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"
+	async mergePages(input) {
+		const core = await loadPagesCore();
+		return this.#tx(async (tx) => {
+			if (input.sourceId === input.targetId) throw new Error(`Knowledge page ${input.sourceId} can't merge into itself or its own subtree`);
+			const [firstId, secondId] = [input.sourceId, input.targetId].sort();
+			await this.#lockPage(tx, firstId);
+			await this.#lockPage(tx, secondId);
+			const source = await this.#requireLivePage(tx, input.sourceId, false);
+			const target = await this.#requireLivePage(tx, input.targetId, false);
+			if (source.version !== input.sourceVersion) throw new KnowledgeConflictError(input.sourceId);
+			if (source.isScope || target.isScope) throw new Error("Knowledge scope pages can't be merged");
+			if (await this.#isInSubtree(tx, source.id, target.id)) throw new Error(`Knowledge page ${source.id} can't merge into itself or its own subtree`);
+			const stats = await this.#subtreeStats(tx, source.id);
+			if (stats.live > core.MAX_KNOWLEDGE_MOVE_PAGES) throw new core.KnowledgeMoveTooLargeError(source.id, stats.live);
+			const delta = await this.#depthOf(tx, target.id) - await this.#depthOf(tx, source.id);
+			await this.#assertNoKeyConflicts(tx, { childrenOf: source.id }, target.id, source.id);
+			if (stats.maxDepth > 0 && stats.maxDepth + delta > core.MAX_KNOWLEDGE_PAGE_DEPTH) throw new core.KnowledgePageDepthError(source.id);
+			const now = /* @__PURE__ */ new Date();
+			await tx.query(`UPDATE ${this.#pages} SET "deletedAt" = $2, "deletedBy" = $3, "mergedInto" = $4, "scopeId" = $6, "version" = "version" + 1, "updatedAt" = $2, "updatedBy" = $5::jsonb WHERE "id" = $1`, [
+				source.id,
+				iso(now),
+				input.provenance.author,
+				target.id,
+				JSON.stringify(input.provenance),
+				target.scopeId
+			]);
+			try {
+				await tx.query(`${this.#subtree("$1")} UPDATE ${this.#pages} SET "scopeId" = $2, "depth" = "depth" + $3 WHERE "id" IN (SELECT "id" FROM sub)`, [
+					source.id,
+					target.scopeId,
+					delta
+				]);
+				await tx.query(`UPDATE ${this.#pages} SET "parentId" = $2 WHERE "parentId" = $1 AND NOT "isScope"`, [source.id, target.id]);
+			} catch (error) {
+				if (isUniqueViolation$1(error)) throw new KnowledgeConflictError(source.id);
+				throw error;
+			}
+			await tx.query(`UPDATE ${this.#notes} SET "pageId" = $2 WHERE "pageId" = $1`, [source.id, target.id]);
+			await tx.query(`DELETE FROM ${this.#mentions} m WHERE m."pageId" = $1 AND EXISTS (SELECT 1 FROM ${this.#mentions} t WHERE t."noteId" = m."noteId" AND t."pageId" = $2)`, [source.id, target.id]);
+			await tx.query(`UPDATE ${this.#mentions} SET "pageId" = $2 WHERE "pageId" = $1`, [source.id, target.id]);
+			const sourcePin = (await this.#rows(tx, `SELECT * FROM ${this.#pins} WHERE "pageId" = $1 FOR UPDATE`, [source.id]))[0];
+			if (sourcePin) {
+				await this.#upsertPinAudience(tx, target.id, sourcePin.audience ?? [], String(sourcePin.createdBy), now);
+				await tx.query(`DELETE FROM ${this.#pins} WHERE "id" = $1`, [String(sourcePin.id)]);
+			}
+			const rows = await this.#rows(tx, `SELECT * FROM ${this.#pages} WHERE "id" = $1`, [target.id]);
+			await this.#logActivity(tx, {
+				action: "page-merged",
+				scopeId: target.scopeId,
+				pageId: source.id,
+				provenance: input.provenance,
+				at: now
+			});
+			return toPage(rows[0]);
+		});
+	}
+	async deletePage(input) {
+		const core = await loadPagesCore();
+		return this.#tx(async (tx) => {
+			const page = await this.#requireLivePage(tx, input.id);
+			if (page.version !== input.expectedVersion) throw new KnowledgeConflictError(input.id);
+			if (page.isScope) throw new Error(`Knowledge scope page ${input.id} can't be deleted`);
+			if ((await this.#rows(tx, `SELECT 1 FROM ${this.#pages} WHERE "parentId" = $1 AND "deletedAt" IS NULL LIMIT 1`, [input.id])).length) throw new core.KnowledgePageHasChildrenError(input.id);
+			const now = /* @__PURE__ */ new Date();
+			const rows = await this.#rows(tx, `UPDATE ${this.#pages} SET "deletedAt" = $2, "deletedBy" = $3, "version" = "version" + 1, "updatedAt" = $2, "updatedBy" = $4::jsonb WHERE "id" = $1 RETURNING *`, [
+				input.id,
+				iso(now),
+				input.deletedBy,
+				JSON.stringify({ author: input.deletedBy })
+			]);
+			await tx.query(`DELETE FROM ${this.#pins} WHERE "pageId" = $1`, [input.id]);
+			await this.#logActivity(tx, {
+				action: "page-deleted",
+				scopeId: page.scopeId,
+				pageId: page.id,
+				provenance: { author: input.deletedBy },
+				at: now
+			});
+			return toPage(rows[0]);
+		});
+	}
+	async getNote(input) {
+		const params = new Params();
+		const id = params.add(input.id);
+		const filter = new ReadFilter(input.read, params, this.#pages);
+		const rows = await this.#rows(this.#client, `SELECT ${this.#noteColumns()} FROM ${this.#visibleNotes(filter)} AND n."id" = ${id}${input.includeDeleted ? "" : " AND n.\"deletedAt\" IS NULL"}`, params.values);
+		return rows[0] ? toNote(rows[0]) : null;
+	}
+	async listNotes(input) {
+		const core = await loadPagesCore();
+		const limit = clampLimit(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
+		const params = new Params();
+		const filter = new ReadFilter(input.read, params, this.#pages);
+		const extra = [`n."pageId" = ${params.add(input.pageId)}`];
+		if (!input.includeDeleted) extra.push(`n."deletedAt" IS NULL`);
+		if (input.cursor) {
+			const [createdAt, id] = decodeCursor(input.cursor, 2);
+			extra.push(`(n."createdAt", n."id") > (${params.add(createdAt)}::timestamptz, ${params.add(id)})`);
+		}
+		const rows = await this.#rows(this.#client, `SELECT ${this.#noteColumns()} FROM ${this.#visibleNotes(filter)} AND ${extra.join(" AND ")} ORDER BY n."createdAt", n."id" LIMIT ${limit + 1}`, params.values);
+		return this.#noteOutput(rows, limit);
+	}
+	async countNotes(input) {
+		const ids = [...new Set(input.pageIds)];
+		const counts = Object.fromEntries(ids.map((id) => [id, 0]));
+		if (!ids.length) return counts;
+		const params = new Params();
+		const filter = new ReadFilter(input.read, params, this.#pages);
+		const rows = await this.#rows(this.#client, `SELECT n."pageId" AS "pageId", count(*)::int AS "count" FROM ${this.#visibleNotes(filter)} AND n."deletedAt" IS NULL AND n."pageId" = ANY(${params.add(ids)}::text[]) GROUP BY n."pageId"`, params.values);
+		for (const row of rows) counts[row.pageId] = Number(row.count);
+		return counts;
+	}
+	async listNotesMentioning(input) {
+		const core = await loadPagesCore();
+		const limit = clampLimit(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
+		const params = new Params();
+		const filter = new ReadFilter(input.read, params, this.#pages);
+		const pageParam = params.add(input.pageId);
+		const extra = [
+			`n."deletedAt" IS NULL`,
+			`n."pageId" <> ${pageParam}`,
+			`np."deletedAt" IS NULL`,
+			`EXISTS (SELECT 1 FROM ${this.#mentions} tm WHERE tm."noteId" = n."id" AND tm."pageId" = ${pageParam})`
+		];
+		if (input.cursor) {
+			const [createdAt, id] = decodeCursor(input.cursor, 2);
+			extra.push(`(n."createdAt", n."id") < (${params.add(createdAt)}::timestamptz, ${params.add(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 rows = await this.#rows(this.#client, `SELECT ${this.#noteColumns()} FROM ${this.#visibleNotes(filter)} AND ${extra.join(" AND ")} ORDER BY n."createdAt" DESC, n."id" DESC LIMIT ${limit + 1}`, params.values);
+		return this.#noteOutput(rows, limit);
 	}
-};
-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
+	#noteOutput(rows, limit) {
+		const notes = rows.slice(0, limit).map(toNote);
+		const last = notes[notes.length - 1];
+		return {
+			notes,
+			...rows.length > limit && last ? { nextCursor: encodeCursor([iso(last.createdAt), last.id]) } : {}
+		};
 	}
-};
-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;
-	};
-}
-// src/storage/domains/knowledge/index.ts
-const loadKnowledgeV2Core = createKnowledgeV2CoreLoader(coreFeatures, () => import("@mastra/core/storage"));
-async function assertKnowledgeDescriptionWithinBoundCompat(description) {
-	const { assertKnowledgeDescriptionWithinBound } = await loadKnowledgeV2Core();
-	assertKnowledgeDescriptionWithinBound(description);
-}
-async function assertKnowledgeRecordTextWithinBoundCompat(text) {
-	const { assertKnowledgeRecordTextWithinBound } = await loadKnowledgeV2Core();
-	assertKnowledgeRecordTextWithinBound(text);
-}
-const camelCaseColumns = [
-	"canonicalName",
-	"scopeKey",
-	"mergedInto",
-	"createdAt",
-	"updatedAt",
-	"node",
-	"sourceThreadId",
-	"capturedAt",
-	"deletedAt",
-	"deletedBy",
-	"sourceType",
-	"sourceId",
-	"recordId",
-	"lastKnowledgeId",
-	"recordType",
-	"idempotencyKey",
-	"documentId",
-	"documentType",
-	"availableAt",
-	"claimedAt",
-	"claimedBy",
-	"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("");
-}
-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 = `"${parseSchemaName(schemaName)}"`;
-		normalized = transformSqlCode(normalized, (code) => {
-			let transformed = code;
-			for (const table of [...KNOWLEDGE_TABLE_NAMES, ...RETIRED_KNOWLEDGE_TABLE_NAMES]) transformed = transformed.replaceAll(`"${table}"`, `${quotedSchema}."${table}"`);
-			return transformed;
+	async addNote(input) {
+		(await this.#bounds()).assertKnowledgeNoteTextWithinBound(input.text);
+		if (input.stampScopeIds.length === 0) throw new Error("A Knowledge note needs at least one stamp scope");
+		return this.#tx(async (tx) => {
+			const page = await this.#requireLivePage(tx, input.pageId, false);
+			const stampIds = [...new Set(input.stampScopeIds)];
+			await this.#assertScopePages(tx, stampIds);
+			const mentionIds = [...new Set(input.mentions)];
+			if (mentionIds.length) {
+				const found = await this.#rows(tx, `SELECT "id" FROM ${this.#pages} WHERE "id" = ANY($1::text[])`, [mentionIds]);
+				const missing = mentionIds.find((id) => !found.some((row) => row.id === id));
+				if (missing) throw new KnowledgeNotFoundError("page", missing);
+			}
+			const id = input.id ?? createKnowledgeUlid();
+			const now = /* @__PURE__ */ new Date();
+			await tx.query(`INSERT INTO ${this.#notes} ("id","pageId","text","when","provenance","version","createdAt","updatedAt") VALUES ($1,$2,$3,$4,$5::jsonb,1,$6,$6)`, [
+				id,
+				page.id,
+				input.text,
+				input.when ? iso(input.when) : null,
+				JSON.stringify(input.provenance),
+				iso(now)
+			]);
+			await tx.query(`INSERT INTO ${this.#stamps} ("noteId","scopeId") SELECT $1, unnest($2::text[])`, [id, stampIds]);
+			if (mentionIds.length) await tx.query(`INSERT INTO ${this.#mentions} ("noteId","pageId") SELECT $1, unnest($2::text[])`, [id, mentionIds]);
+			await this.#logActivity(tx, {
+				action: "note-added",
+				scopeId: page.scopeId,
+				pageId: page.id,
+				noteId: id,
+				provenance: input.provenance,
+				at: now
+			});
+			return this.#noteById(tx, id);
+		});
+	}
+	async #assertScopePages(db, ids) {
+		const rows = await this.#rows(db, `SELECT "id" FROM ${this.#pages} WHERE "id" = ANY($1::text[]) AND "isScope"`, [ids]);
+		const missing = ids.find((id) => !rows.some((row) => row.id === id));
+		if (missing) throw new Error(`Knowledge note stamp ${missing} is not a scope page`);
+	}
+	async #noteById(db, id, lock = false) {
+		const rows = await this.#rows(db, `SELECT ${this.#noteColumns()} FROM ${this.#notes} n WHERE n."id" = $1${lock ? " FOR UPDATE" : ""}`, [id]);
+		if (!rows[0]) throw new KnowledgeNotFoundError("note", id);
+		return toNote(rows[0]);
+	}
+	async restampNote(input) {
+		if (input.stampScopeIds.length === 0) throw new Error("A Knowledge note needs at least one stamp scope");
+		return this.#tx(async (tx) => {
+			const note = (await this.#rows(tx, `SELECT * FROM ${this.#notes} WHERE "id" = $1 FOR UPDATE`, [input.id]))[0];
+			if (!note || note.deletedAt) throw new KnowledgeNotFoundError("note", input.id);
+			if (Number(note.version) !== input.expectedVersion) throw new KnowledgeConflictError(input.id);
+			const stampIds = [...new Set(input.stampScopeIds)];
+			await this.#assertScopePages(tx, stampIds);
+			const now = /* @__PURE__ */ new Date();
+			await tx.query(`DELETE FROM ${this.#stamps} WHERE "noteId" = $1`, [input.id]);
+			await tx.query(`INSERT INTO ${this.#stamps} ("noteId","scopeId") SELECT $1, unnest($2::text[])`, [input.id, stampIds]);
+			await tx.query(`UPDATE ${this.#notes} SET "version" = "version" + 1, "updatedAt" = $2 WHERE "id" = $1`, [input.id, iso(now)]);
+			const page = await this.#pageScope(tx, String(note.pageId));
+			await this.#logActivity(tx, {
+				action: "note-restamped",
+				scopeId: page,
+				pageId: String(note.pageId),
+				noteId: input.id,
+				provenance: input.provenance,
+				at: now
+			});
+			return this.#noteById(tx, input.id);
+		});
+	}
+	async #pageScope(db, pageId) {
+		const rows = await this.#rows(db, `SELECT "scopeId" FROM ${this.#pages} WHERE "id" = $1`, [pageId]);
+		return String(rows[0]?.scopeId);
+	}
+	async removeNote(input) {
+		return this.#tx(async (tx) => {
+			const note = await this.#noteById(tx, input.id, true);
+			if (note.deletedAt) return note;
+			const now = /* @__PURE__ */ new Date();
+			await tx.query(`UPDATE ${this.#notes} SET "deletedAt" = $2, "deletedBy" = $3, "version" = "version" + 1, "updatedAt" = $2 WHERE "id" = $1`, [
+				input.id,
+				iso(now),
+				input.deletedBy
+			]);
+			await this.#logActivity(tx, {
+				action: "note-removed",
+				scopeId: await this.#pageScope(tx, note.pageId),
+				pageId: note.pageId,
+				noteId: input.id,
+				provenance: input.provenance,
+				at: now
+			});
+			return this.#noteById(tx, input.id);
 		});
 	}
-	let index = 0;
-	return transformSqlCode(normalized, (code) => code.replace(/\?/g, () => `$${++index}`));
-}
-function createExecutor(client, schemaName) {
-	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, qualifyWithSchema ? schemaName : void 0), args);
-		return {
-			rows: result.rows,
-			rowsAffected: result.rowCount ?? 0
-		};
-	};
-	return {
-		execute: (statement) => execute(statement, true),
-		executeRaw: (statement) => execute(statement, false)
-	};
-}
-/**
-* 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));
-	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: 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),
-		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),
-		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 ? `"${parseSchemaName(schemaName)}".${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_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);`
-		},
-		{
-			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_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");`
-		},
-		{
-			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");`
-		},
+	async restoreNote(input) {
+		return this.#tx(async (tx) => {
+			const note = await this.#noteById(tx, input.id, true);
+			if (!note.deletedAt) return note;
+			const now = /* @__PURE__ */ new Date();
+			await tx.query(`UPDATE ${this.#notes} SET "deletedAt" = NULL, "deletedBy" = NULL, "version" = "version" + 1, "updatedAt" = $2 WHERE "id" = $1`, [input.id, iso(now)]);
+			await this.#logActivity(tx, {
+				action: "note-restored",
+				scopeId: await this.#pageScope(tx, note.pageId),
+				pageId: note.pageId,
+				noteId: input.id,
+				provenance: input.provenance,
+				at: now
+			});
+			return this.#noteById(tx, input.id);
+		});
+	}
+	async searchPages(input) {
+		const core = await loadPagesCore();
+		const limit = clampLimit(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
+		const words = knowledgeSearchWords(input.query);
+		if (!words.length) return [];
+		const phrase = input.query.trim().toLowerCase().replace(/\s+/g, " ");
+		const hits = [];
 		{
-			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);`
-		},
+			const params = new Params();
+			const filter = new ReadFilter(input.read, params, this.#pages);
+			const patterns = words.map((word) => params.add(`%${escapeLike(word)}%`));
+			const phrasePattern = params.add(`%${escapeLike(phrase)}%`);
+			const where = [
+				`p."deletedAt" IS NULL`,
+				`NOT p."isScope"`,
+				filter.readable("s")
+			];
+			if (input.scopeIds?.length) where.push(`p."scopeId" = ANY(${params.add(input.scopeIds)}::text[])`);
+			for (const pattern of patterns) where.push(`(p."name" ILIKE ${pattern} OR p."description" ILIKE ${pattern} OR p."body" ILIKE ${pattern})`);
+			const tier = `CASE WHEN p."canonicalName" LIKE ${phrasePattern} THEN 0 WHEN ${patterns.map((pattern) => `p."name" ILIKE ${pattern}`).join(" AND ")} THEN 1 ELSE 2 END`;
+			const rows = await this.#rows(this.#client, `SELECT p.* FROM ${this.#pages} p JOIN ${this.#pages} s ON s."id" = p."scopeId" WHERE ${where.join(" AND ")} ORDER BY ${tier}, p."updatedAt" DESC, p."id" ASC LIMIT ${limit}`, params.values);
+			for (const row of rows) hits.push({
+				type: "page",
+				page: toPage(row)
+			});
+		}
+		if (hits.length >= limit) return hits;
 		{
-			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);`
+			const params = new Params();
+			const filter = new ReadFilter(input.read, params, this.#pages);
+			const extra = [`n."deletedAt" IS NULL`, `np."deletedAt" IS NULL`];
+			if (input.scopeIds?.length) extra.push(`np."scopeId" = ANY(${params.add(input.scopeIds)}::text[])`);
+			for (const word of words) extra.push(`n."text" ILIKE ${params.add(`%${escapeLike(word)}%`)}`);
+			const rows = await this.#rows(this.#client, `SELECT ${this.#noteColumns()}, row_to_json(np) AS "pageJson" FROM ${this.#visibleNotes(filter)} AND ${extra.join(" AND ")} ORDER BY n."updatedAt" DESC, n."id" DESC LIMIT ${limit - hits.length}`, params.values);
+			for (const row of rows) hits.push({
+				type: "note",
+				note: toNote(row),
+				page: toPage(parseJson$1(row.pageJson))
+			});
+		}
+		return hits;
+	}
+	async listPageActivity(input) {
+		const core = await loadPagesCore();
+		const limit = clampLimit(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
+		const params = new Params();
+		const filter = new ReadFilter(input.read, params, this.#pages);
+		const where = [filter.readable("s"), `(a."noteId" IS NULL OR ${this.#noteVisible(filter, "a.\"noteId\"")})`];
+		if (input.scopeId) where.push(`s."id" = ${params.add(input.scopeId)}`);
+		if (input.pageId) where.push(`a."pageId" = ${params.add(input.pageId)}`);
+		if (input.cursor) {
+			const [createdAt, id] = decodeCursor(input.cursor, 2);
+			where.push(`(a."createdAt", a."id") < (${params.add(createdAt)}::timestamptz, ${params.add(id)})`);
 		}
-	];
+		const rows = await this.#rows(this.#client, `SELECT a.* FROM ${this.#activity} a JOIN ${this.#pages} p ON p."id" = a."pageId" JOIN ${this.#pages} s ON s."id" = p."scopeId"
+       WHERE ${where.join(" AND ")} ORDER BY a."createdAt" DESC, a."id" DESC LIMIT ${limit + 1}`, params.values);
+		const events = rows.slice(0, limit).map((row) => ({
+			id: String(row.id),
+			action: String(row.action),
+			scopeId: String(row.scopeId),
+			pageId: String(row.pageId),
+			...row.noteId == null ? {} : { noteId: String(row.noteId) },
+			provenance: parseJson$1(row.provenance),
+			createdAt: new Date(row.createdAt)
+		}));
+		const last = events[events.length - 1];
+		return {
+			events,
+			...rows.length > limit && last ? { nextCursor: encodeCursor([iso(last.createdAt), last.id]) } : {}
+		};
+	}
+	async addPinAudience(input) {
+		return this.#tx(async (tx) => {
+			const page = await this.#requireLivePage(tx, input.pageId, false);
+			const now = /* @__PURE__ */ new Date();
+			const { pin, changed } = await this.#upsertPinAudience(tx, page.id, input.audience, input.createdBy, now);
+			if (changed) await this.#logActivity(tx, {
+				action: "pin-added",
+				scopeId: page.scopeId,
+				pageId: page.id,
+				provenance: { author: input.createdBy },
+				at: now
+			});
+			return pin;
+		});
+	}
+	async #upsertPinAudience(db, pageId, audience, createdBy, now) {
+		const existing = (await this.#rows(db, `SELECT * FROM ${this.#pins} WHERE "pageId" = $1 FOR UPDATE`, [pageId]))[0];
+		if (!existing) return {
+			pin: toPin((await this.#rows(db, `INSERT INTO ${this.#pins} ("id","pageId","audience","createdBy","createdAt","updatedAt") VALUES ($1,$2,$3::text[],$4,$5,$5) RETURNING *`, [
+				createKnowledgeUlid(),
+				pageId,
+				[...new Set(audience)],
+				createdBy,
+				iso(now)
+			]))[0]),
+			changed: true
+		};
+		const current = existing.audience ?? [];
+		const merged = [.../* @__PURE__ */ new Set([...current, ...audience])];
+		if (merged.length === current.length) return {
+			pin: toPin(existing),
+			changed: false
+		};
+		return {
+			pin: toPin((await this.#rows(db, `UPDATE ${this.#pins} SET "audience" = $2::text[], "updatedAt" = $3 WHERE "id" = $1 RETURNING *`, [
+				String(existing.id),
+				merged,
+				iso(now)
+			]))[0]),
+			changed: true
+		};
+	}
+	async removePinAudience(input) {
+		return this.#tx(async (tx) => {
+			const existing = (await this.#rows(tx, `SELECT * FROM ${this.#pins} WHERE "pageId" = $1 FOR UPDATE`, [input.pageId]))[0];
+			if (!existing) return null;
+			const current = existing.audience ?? [];
+			const remaining = current.filter((entry) => !input.audience.includes(entry));
+			if (remaining.length === current.length) return toPin(existing);
+			const now = /* @__PURE__ */ new Date();
+			let pin = null;
+			if (remaining.length === 0) await tx.query(`DELETE FROM ${this.#pins} WHERE "id" = $1`, [String(existing.id)]);
+			else pin = toPin((await this.#rows(tx, `UPDATE ${this.#pins} SET "audience" = $2::text[], "updatedAt" = $3 WHERE "id" = $1 RETURNING *`, [
+				String(existing.id),
+				remaining,
+				iso(now)
+			]))[0]);
+			await this.#logActivity(tx, {
+				action: "pin-removed",
+				scopeId: await this.#pageScope(tx, input.pageId),
+				pageId: input.pageId,
+				provenance: { author: input.removedBy },
+				at: now
+			});
+			return pin;
+		});
+	}
+	/** Deletes every row but keeps the tables and the schema-version marker. */
+	async clearAll() {
+		const t = PG_KNOWLEDGE_PAGES_TABLES;
+		const tables = [
+			t.activity,
+			t.pins,
+			t.mentions,
+			t.stamps,
+			t.notes,
+			t.pages
+		].map((name) => this.#q(name)).join(", ");
+		await this.#client.query(`TRUNCATE ${tables}`);
+	}
+	async getPages(input) {
+		if (!input.ids.length) return [];
+		const params = new Params();
+		const ids = params.add([...new Set(input.ids)]);
+		const filter = new ReadFilter(input.read, params, this.#pages);
+		return (await this.#rows(this.#client, `SELECT p.* FROM ${this.#pages} p JOIN ${this.#pages} s ON s."id" = p."scopeId"
+       WHERE p."id" = ANY(${ids}::text[]) AND p."deletedAt" IS NULL AND ${filter.readable("s")}`, params.values)).map(toPage);
+	}
+	async listPins(input) {
+		const core = await loadPagesCore();
+		const limit = clampLimit(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
+		const params = new Params();
+		const where = [`p."deletedAt" IS NULL`, new ReadFilter(input.read, params, this.#pages).readable("s")];
+		if (input.audience !== "all") where.push(`pn."audience" && ${params.add(input.audience)}::text[]`);
+		if (input.pageIds) where.push(`pn."pageId" = ANY(${params.add(input.pageIds)}::text[])`);
+		if (input.excludePageIds?.length) where.push(`pn."pageId" <> ALL(${params.add(input.excludePageIds)}::text[])`);
+		if (input.withBody) where.push(`p."body" ~ '\\S'`);
+		const from = `FROM ${this.#pins} pn JOIN ${this.#pages} p ON p."id" = pn."pageId" JOIN ${this.#pages} s ON s."id" = p."scopeId"`;
+		const totalWhere = where.join(" AND ");
+		if (input.cursor) {
+			const [createdAt, id] = decodeCursor(input.cursor, 2);
+			where.push(`(pn."createdAt", pn."id") < (${params.add(createdAt)}::timestamptz, ${params.add(id)})`);
+		}
+		const rows = await this.#rows(this.#client, `SELECT pn.*, p."name" AS "pageName" ${from}
+       WHERE ${where.join(" AND ")} ORDER BY pn."createdAt" DESC, pn."id" DESC LIMIT ${limit + 1}`, params.values);
+		let total;
+		if (input.count) {
+			const counted = await this.#rows(this.#client, `SELECT count(*)::int AS "total" ${from} WHERE ${totalWhere}`, params.values.slice(0, params.values.length - (input.cursor ? 2 : 0)));
+			total = Number(counted[0]?.total ?? 0);
+		}
+		const pins = rows.slice(0, limit).map(toListedPin);
+		const last = pins[pins.length - 1];
+		return {
+			pins,
+			...rows.length > limit && last ? { nextCursor: encodeCursor([iso(last.createdAt), last.id]) } : {},
+			...total === void 0 ? {} : { total }
+		};
+	}
+};
+// src/storage/domains/knowledge/pages-schema.ts
+const qualify = (schemaName, table) => schemaName ? `"${schemaName}"."${table}"` : `"${table}"`;
+/** Thrown when existing Knowledge tables can't be used as schema 4 without a reset. */
+var PgKnowledgeResetRequiredError = class extends Error {
+	inspection;
+	constructor(inspection) {
+		super(knowledgePagesResetMessage(inspection.reason));
+		this.name = "KnowledgeSchemaResetRequiredError";
+		this.inspection = inspection;
+	}
+};
+/** Looks at every `mastra_knowledge_*` table and the version row without changing anything. */
+async function inspectPgKnowledgePagesSchema(db, schemaName) {
+	return inspectKnowledgePagesSchema(await pgKnowledgeSnapshot(db, schemaName));
+}
+/** Creates the schema-4 tables, refusing (with the reset message) over anything older. */
+async function initPgKnowledgePagesSchema(client, schemaName) {
+	await client.tx(async (tx) => {
+		await tx.query("SELECT pg_advisory_xact_lock(hashtext($1))", [`mastra-knowledge-schema:${schemaName ?? ""}`]);
+		const drop = legacyKnowledgeTablesToDrop(await pgKnowledgeSnapshot(tx, schemaName));
+		if (drop.length > 0) await tx.query(`DROP TABLE IF EXISTS ${drop.map((table) => qualify(schemaName, table)).join(", ")} CASCADE`);
+		const inspection = await inspectPgKnowledgePagesSchema(tx, schemaName);
+		if (inspection.status === "incompatible-reset-required") throw new PgKnowledgeResetRequiredError(inspection);
+		for (const statement of pgKnowledgePagesDDL(schemaName)) await tx.query(statement);
+		await tx.query(`INSERT INTO ${qualify(schemaName, PG_KNOWLEDGE_PAGES_TABLES.state)} ("id","schemaVersion") VALUES ('knowledge', $1) ON CONFLICT ("id") DO NOTHING`, [4]);
+	});
 }
-function knowledgeIndexDDL(schemaName) {
-	return knowledgeIndexes(schemaName).map((index) => index.sql);
+/**
+* Every `mastra_knowledge_*` table and the schema-4 version, if any. The state table is read as
+* whole rows because schema 2 used the same name with a different shape, and a failed query would
+* abort the init transaction.
+*/
+async function pgKnowledgeSnapshot(db, schemaName) {
+	const tableNames = (await db.query(`SELECT table_name FROM information_schema.tables WHERE table_schema = COALESCE($1, current_schema()) AND table_name LIKE 'mastra\\_knowledge\\_%'`, [schemaName ?? null])).rows.map((row) => String(row.table_name));
+	if (!tableNames.includes(PG_KNOWLEDGE_PAGES_TABLES.state)) return { tableNames };
+	const row = (await db.query(`SELECT to_jsonb(s) AS row FROM ${qualify(schemaName, PG_KNOWLEDGE_PAGES_TABLES.state)} s`)).rows.map((r) => r.row).find((r) => r.id === "knowledge");
+	return {
+		tableNames,
+		schemaVersion: typeof row?.schemaVersion === "number" ? row.schemaVersion : void 0
+	};
 }
-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
-	}
-];
+/** Drops exactly the Knowledge tables (never Memory's) and recreates schema 4. */
+async function resetPgKnowledgePagesSchema(client, schemaName) {
+	const tables = KNOWLEDGE_RESETTABLE_TABLE_NAMES.map((table) => qualify(schemaName, table)).join(", ");
+	await client.query(`DROP TABLE IF EXISTS ${tables} CASCADE`);
+	await initPgKnowledgePagesSchema(client, schemaName);
+}
+// src/storage/domains/knowledge/index.ts
+const loadKnowledgePagesCore = createKnowledgePagesCoreLoader(coreFeatures, () => import("@mastra/core/storage"));
 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);
@@ -9526,1153 +9954,137 @@ function getPgKnowledgeIsolationKey(config) {
 	if (target) return `pg:${target}:schema:${schema}`;
 	return `pg:unidentified:schema:${schema}`;
 }
+/** @experimental Knowledge APIs are experimental and may change without notice. */
 var KnowledgePG = class extends KnowledgeStorage {
-	static MANAGED_TABLES = KNOWLEDGE_TABLE_NAMES;
 	static getExportDDL(schemaName) {
-		return [...knowledgeTableDefinitions.map((definition) => generateTableSQL({
-			...definition,
-			schemaName,
-			includeAllConstraints: true
-		})), ...knowledgeIndexDDL(schemaName)];
+		return pgKnowledgePagesDDL(schemaName).map((statement) => `${statement};`);
 	}
 	#client;
-	#executor;
-	/** Reader-backed executor for standalone reads; mutations and read-modify-write stay on #executor. */
-	#readExecutor;
-	#db;
 	#schemaName;
+	#pages;
 	constructor(config) {
 		super({ storageIsolationKey: config.storageIsolationKey ?? getPgKnowledgeIsolationKey(config) });
-		const { client, readClient, schemaName, skipDefaultIndexes } = resolvePgConfig(config);
+		const { client, schemaName } = resolvePgConfig(config);
 		this.#client = client;
 		this.#schemaName = schemaName;
-		this.#executor = createExecutor(client, schemaName);
-		this.#readExecutor = createExecutor(readClient, schemaName);
-		this.#db = new PgDB({
+		this.#pages = new PgKnowledgePages({
 			client,
-			readClient,
 			schemaName,
-			skipDefaultIndexes
+			bounds: async () => {
+				const core = await loadKnowledgePagesCore();
+				return {
+					assertKnowledgePageDescriptionWithinBound: core.assertKnowledgePageDescriptionWithinBound,
+					assertKnowledgeNoteTextWithinBound: core.assertKnowledgeNoteTextWithinBound
+				};
+			}
 		});
 	}
 	getCapabilities() {
 		return {
-			contractVersion: 2,
-			schemaVersion: 2,
-			supportsV2: true,
+			...super.getCapabilities(),
+			schemaVersion: 4,
 			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
-		});
-	}
 	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]
-			});
-		});
-	}
-	/**
-	* 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;
+		await initPgKnowledgePagesSchema(this.#client, this.#schemaName);
 	}
-	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'`);
-		});
+	async inspectSchema() {
+		return inspectPgKnowledgePagesSchema(this.#client, this.#schemaName);
 	}
 	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)
-			};
-		});
-	}
-	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);
-		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}`);
-				await this.#placeNodeInScopes(tx, terminal.id, input.scopeAddresses, /* @__PURE__ */ new Date());
-				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,
-				description: input.description,
-				scope,
-				version: 1,
-				createdAt: now,
-				updatedAt: now
-			};
-			await tx.execute({
-				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",
-					node.name,
-					canonicalName(node.name),
-					node.kind,
-					node.content ?? null,
-					node.description ?? null,
-					JSON.stringify(scope),
-					knowledgeScopeKey(scope),
-					node.version,
-					now.toISOString(),
-					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);
-			return node;
-		});
-	}
-	async getNode(id) {
-		return this.#getNode(this.#readExecutor, id);
-	}
-	async getNodeByName(input) {
-		return this.#getNodeByName(this.#readExecutor, input.name, canonicalizeKnowledgeScope(input.scope));
-	}
-	async resolveNode(input) {
-		return this.#resolveNode(this.#readExecutor, input.name, canonicalizeKnowledgeScope(input.scope));
-	}
-	async listNodes(input) {
-		const keys = visibleScopeKeys(canonicalizeKnowledgeScope(input.scope));
-		const clauses = [
-			`type = 'node'`,
-			"mergedInto IS NULL",
-			visibleSql(keys)
-		];
-		const args = [...keys];
-		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.#readExecutor.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) {
-		await assertKnowledgeDescriptionWithinBoundCompat(input.description);
-		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 description = input.description ?? existing.description;
-			const now = /* @__PURE__ */ new Date();
-			if ((await tx.execute({
-				sql: `UPDATE "${TABLE_KNOWLEDGE_NODES}" SET name=?,canonicalName=?,kind=?,content=?,description=?,scope=jsonb(?),scopeKey=?,version=version+1,updatedAt=? WHERE id=? AND type='node' AND version=?`,
-				args: [
-					name,
-					canonicalName(name),
-					input.kind ?? existing.kind,
-					content ?? null,
-					description ?? null,
-					JSON.stringify(scope),
-					knowledgeScopeKey(scope),
-					now.toISOString(),
-					input.id,
-					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)) {
-				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,
-				description,
-				scope,
-				version: input.version + 1,
-				updatedAt: now
-			};
-		});
+		await resetPgKnowledgePagesSchema(this.#client, this.#schemaName);
 	}
-	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=?,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=?)`,
-				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));
-			let mergedTarget = target;
-			if (target.description === void 0 && source.description) {
-				const adoptedAt = /* @__PURE__ */ new Date();
-				if ((await tx.execute({
-					sql: `UPDATE "${TABLE_KNOWLEDGE_NODES}" SET description=?,version=version+1,updatedAt=? WHERE id=? AND type='node' AND version=? AND description IS NULL`,
-					args: [
-						source.description,
-						adoptedAt.toISOString(),
-						target.id,
-						target.version
-					]
-				})).rowsAffected > 0) {
-					mergedTarget = {
-						...target,
-						description: source.description,
-						version: target.version + 1,
-						updatedAt: adoptedAt
-					};
-					await this.#activity(tx, "node-updated", "node", target.id, target.scope);
-				}
-			}
-			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(), mergedTarget.scope);
-			return mergedTarget;
-		});
-	}
-	async appendKnowledge(input) {
-		await assertKnowledgeRecordTextWithinBoundCompat(input.text);
-		const scope = canonicalizeKnowledgeScope(input.scope);
-		const resolutionScope = canonicalizeKnowledgeScope(input.resolutionScope);
-		const defaultScope = canonicalizeKnowledgeScope(input.defaultScope);
-		return this.#transaction(async (tx) => {
-			const parent = await this.#resolveTerminalNode(tx, nodeReferenceId(input.node));
-			if (!parent) throw new KnowledgeNotFoundError("node", nodeReferenceId(input.node));
-			const metadataJson = input.metadata ? toPgJson(input.metadata) : null;
-			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,
-				metadata: input.metadata
-			};
-			await tx.execute({
-				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,
-					record.text,
-					JSON.stringify(scope),
-					knowledgeScopeKey(scope),
-					record.sourceThreadId,
-					record.capturedAt.toISOString(),
-					record.when?.toISOString() ?? null,
-					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);
-			return metadataJson ? {
-				...record,
-				metadata: JSON.parse(metadataJson)
-			} : record;
-		});
+	async dangerouslyClearAll() {
+		await this.#pages.clearAll();
 	}
-	async getKnowledge(input) {
-		const result = await this.#readExecutor.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;
+	materializeScope(input) {
+		return this.#pages.materializeScope(input);
 	}
-	async listKnowledgeAbout(input) {
-		return this.#queryKnowledge(input, "about");
+	getScopesByAddress(input) {
+		return this.#pages.getScopesByAddress(input);
 	}
-	async listKnowledgeMentioning(input) {
-		return this.#queryKnowledge(input, "mentioning");
+	listScopeDeclarations() {
+		return this.#pages.listScopeDeclarations();
 	}
-	async listKnowledgeRelatedTo(input) {
-		return this.#queryKnowledge(input, "related");
+	renameScopeDeclaration(input) {
+		return this.#pages.renameScopeDeclaration(input);
 	}
-	async knowledgeBySource(input) {
-		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(keys)}${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
-		};
+	listChildScopes(input) {
+		return this.#pages.listChildScopes(input);
 	}
-	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=?,version=version+1,updatedAt=? WHERE id=? AND deletedAt IS NULL`,
-				args: [
-					deletedAt.toISOString(),
-					input.deletedBy,
-					deletedAt.toISOString(),
-					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
-			};
-		});
+	getPages(input) {
+		return this.#pages.getPages(input);
 	}
-	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,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);
-			return {
-				...record,
-				deletedAt: void 0,
-				deletedBy: void 0
-			};
-		});
+	getPage(input) {
+		return this.#pages.getPage(input);
 	}
-	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);
-			const updatedAt = /* @__PURE__ */ new Date();
-			await tx.execute({
-				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);
-			return {
-				...record,
-				scope
-			};
-		});
+	getPageByPath(input) {
+		return this.#pages.getPageByPath(input);
 	}
-	async search(input) {
-		const scope = canonicalizeKnowledgeScope(input.scope);
-		const keys = visibleScopeKeys(scope);
-		const normalizedQuery = input.query.trim().toLocaleLowerCase();
-		if (!normalizedQuery) return [];
-		const query = `%${escapeLikePattern(normalizedQuery)}%`;
-		const results = (await this.#readExecutor.execute({
-			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: [
-				...keys,
-				query,
-				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: [
-				String(row.name),
-				...row.description ? [String(row.description)] : [],
-				...row.content ? [String(row.content)] : []
-			].join("\n"),
-			scope: parseJson$1(row.scopeJson)
-		}));
-		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(keys, "f.scopeKey")} AND lower(f.text) LIKE ? ESCAPE '=' ORDER BY f.id DESC LIMIT ?`,
-				args: [
-					...keys,
-					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: parentVisible ? String(row.node) : String(row.id),
-					name: parentVisible ? String(row.name) : "(private node)",
-					text: String(row.text),
-					scope: parseJson$1(row.scopeJson)
-				};
-			}));
-		}
-		return results;
+	findPagesByName(input) {
+		return this.#pages.findPagesByName(input);
 	}
-	/**
-	* @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);
+	listChildPages(input) {
+		return this.#pages.listChildPages(input);
 	}
-	/**
-	* @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 keys = visibleScopeKeys(canonicalizeKnowledgeScope(input.scope));
-		return (await this.#readExecutor.execute({
-			sql: `SELECT *,scope AS "scopeJson" FROM "${TABLE_KNOWLEDGE_ACTIVITY}" WHERE ${visibleSql(keys)}${input.after ? " AND id < ?" : ""} ORDER BY id DESC LIMIT ?`,
-			args: [
-				...keys,
-				...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)
-		}));
+	listPages(input) {
+		return this.#pages.listPages(input);
 	}
-	async listSemanticOutbox(input = {}) {
-		const clauses = [];
-		const args = [];
-		if (input.status) {
-			clauses.push("status=?");
-			args.push(input.status);
-		}
-		if (input.scope) {
-			const keys = visibleScopeKeys(input.scope);
-			clauses.push(visibleSql(keys));
-			args.push(...keys);
-		}
-		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 keys = visibleScopeKeys(input.scope);
-				clauses.push(visibleSql(keys));
-				args.push(...keys);
-			}
-			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);
-		});
+	createPage(input) {
+		return this.#pages.createPage(input);
 	}
-	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
-				]
-			});
-		});
+	updatePage(input) {
+		return this.#pages.updatePage(input);
 	}
-	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
-				]
-			});
-		});
+	movePage(input) {
+		return this.#pages.movePage(input);
 	}
-	async #transaction(operation) {
-		return this.#client.tx((tx) => operation(createExecutor(tx, this.#schemaName)));
+	mergePages(input) {
+		return this.#pages.mergePages(input);
 	}
-	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;
+	deletePage(input) {
+		return this.#pages.deletePage(input);
 	}
-	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;
+	getNote(input) {
+		return this.#pages.getNote(input);
 	}
-	async #resolveNode(executor, name, scope) {
-		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;
+	listNotes(input) {
+		return this.#pages.listNotes(input);
 	}
-	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;
+	countNotes(input) {
+		return this.#pages.countNotes(input);
 	}
-	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;
+	listNotesMentioning(input) {
+		return this.#pages.listNotesMentioning(input);
 	}
-	async #queryKnowledge(input, relationship) {
-		const scope = canonicalizeKnowledgeScope(input.scope);
-		const node = await this.#resolveTerminalNode(this.#readExecutor, nodeReferenceId(input.node));
-		if (!node) return { records: [] };
-		const keys = visibleScopeKeys(scope);
-		const args = [
-			node.id,
-			...relationship === "related" ? [node.id] : [],
-			...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(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;
-		return {
-			records: records.slice(0, limit),
-			nextCursor: records.length > limit ? records[limit - 1]?.id : void 0
-		};
+	addNote(input) {
+		return this.#pages.addNote(input);
 	}
-	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];
+	restampNote(input) {
+		return this.#pages.restampNote(input);
 	}
-	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()
-			]
-		});
+	removeNote(input) {
+		return this.#pages.removeNote(input);
 	}
-	/**
-	* 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()
-			]
-		});
+	restoreNote(input) {
+		return this.#pages.restoreNote(input);
 	}
-	/**
-	* 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()
-				]
-			});
-		}
+	searchPages(input) {
+		return this.#pages.searchPages(input);
 	}
-	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()
-			]
-		});
+	listPageActivity(input) {
+		return this.#pages.listPageActivity(input);
 	}
-	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,isScope,scope,scopeKey,version,mergedInto,createdAt,updatedAt) VALUES (?,?,?,?,?,NULL,FALSE,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.#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);
-				}
-			}
-			await tx.execute({
-				sql: `INSERT INTO "${TABLE_KNOWLEDGE_MENTIONS}" (sourceType,sourceId,recordId) VALUES (?,?,?) ON CONFLICT DO NOTHING`,
-				args: [
-					sourceType,
-					sourceId,
-					node.id
-				]
-			});
-		}
+	addPinAudience(input) {
+		return this.#pages.addPinAudience(input);
 	}
-	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,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,
-				now.toISOString()
-			]
-		});
+	removePinAudience(input) {
+		return this.#pages.removePinAudience(input);
 	}
-	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()
-			]
-		});
+	listPins(input) {
+		return this.#pages.listPins(input);
 	}
 };
 // src/storage/domains/mcp-clients/index.ts