@mastra/mysql 0.15.0 → 0.16.0-alpha.0

package/dist/index.js

@@ -1,7 +1,8 @@
 import { ErrorCategory, ErrorDomain, MastraError } from "@mastra/core/error";
-import { AGENTS_SCHEMA, AGENT_VERSIONS_SCHEMA, AgentsStorage, BackgroundTasksStorage, BlobStore, ChannelsStorage, DATASETS_SCHEMA, DATASET_ITEMS_SCHEMA, DATASET_VERSIONS_SCHEMA, DatasetsStorage, EXPERIMENTS_SCHEMA, EXPERIMENT_RESULTS_SCHEMA, ExperimentsStorage, FAVORITES_SCHEMA, FavoritesStorage, KNOWLEDGE_ACTIVITY_SCHEMA, KNOWLEDGE_MENTIONS_SCHEMA, KNOWLEDGE_NODES_SCHEMA, KNOWLEDGE_RECORDS_SCHEMA, KNOWLEDGE_SEMANTIC_OUTBOX_SCHEMA, KnowledgeConflictError, KnowledgeNotFoundError, KnowledgeStorage, MCPClientsStorage, MCPServersStorage, MCP_CLIENTS_SCHEMA, MCP_CLIENT_VERSIONS_SCHEMA, MCP_SERVERS_SCHEMA, MCP_SERVER_VERSIONS_SCHEMA, MastraCompositeStore, MemoryStorage, OBSERVATIONAL_MEMORY_TABLE_SCHEMA, ObservabilityStorage, PROMPT_BLOCKS_SCHEMA, PROMPT_BLOCK_VERSIONS_SCHEMA, PromptBlocksStorage, RUN_FENCING_TABLE_SCHEMAS, RunFenceConflictError, SCORERS_SCHEMA, SCORER_DEFINITIONS_SCHEMA, SCORER_DEFINITION_VERSIONS_SCHEMA, SKILLS_SCHEMA, SKILL_BLOBS_SCHEMA, SKILL_VERSIONS_SCHEMA, SPAN_SCHEMA, SchedulesStorage, ScorerDefinitionsStorage, ScoresStorage, SkillsStorage, StoreOperations, 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_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_TOOL_PROVIDER_CONNECTIONS, TABLE_WORKFLOW_DEFINITIONS, TABLE_WORKFLOW_RUN_OWNERS, TABLE_WORKFLOW_SNAPSHOT, TABLE_WORKSPACES, TABLE_WORKSPACE_VERSIONS, TOOL_PROVIDER_CONNECTIONS_SCHEMA, ToolProviderConnectionsStorage, TraceStatus, WORKFLOW_DEFINITIONS_SCHEMA, WORKSPACES_SCHEMA, WORKSPACE_VERSIONS_SCHEMA, WorkflowDefinitionsStorage, WorkflowsStorage, WorkspacesStorage, calculatePagination, canonicalizeKnowledgeScope, createKnowledgeUlid, createStorageErrorId, executeRetentionPrune, hasErrorCode, isKnowledgeScopeVisible, isRunFenceConflictError, knowledgeScopeKey, knowledgeSemanticDocumentId, knowledgeSemanticIdempotencyKey, listTracesArgsSchema, matchesExpectedWorkflowStatus, matchesRunFence, normalizePerPage, normalizeScheduleTarget, parseKnowledgeNodeCursor, parseKnowledgeWikilinks, resolveListOrderBy, resolveRetentionTargets, resolveRunFence, retentionCutoffMs, toTraceSpans, validateStorageMetadataFilter } from "@mastra/core/storage";
+import { AGENTS_SCHEMA, AGENT_VERSIONS_SCHEMA, AgentsStorage, BackgroundTasksStorage, BlobStore, ChannelsStorage, DATASETS_SCHEMA, DATASET_ITEMS_SCHEMA, DATASET_VERSIONS_SCHEMA, DatasetsStorage, EXPERIMENTS_SCHEMA, EXPERIMENT_RESULTS_SCHEMA, ExperimentsStorage, FAVORITES_SCHEMA, FavoritesStorage, KnowledgeConflictError, KnowledgeNotFoundError, KnowledgeSchemaResetRequiredError, KnowledgeStorage, MCPClientsStorage, MCPServersStorage, MCP_CLIENTS_SCHEMA, MCP_CLIENT_VERSIONS_SCHEMA, MCP_SERVERS_SCHEMA, MCP_SERVER_VERSIONS_SCHEMA, MastraCompositeStore, MemoryStorage, OBSERVATIONAL_MEMORY_TABLE_SCHEMA, ObservabilityStorage, PROMPT_BLOCKS_SCHEMA, PROMPT_BLOCK_VERSIONS_SCHEMA, PromptBlocksStorage, RUN_FENCING_TABLE_SCHEMAS, RunFenceConflictError, SCORERS_SCHEMA, SCORER_DEFINITIONS_SCHEMA, SCORER_DEFINITION_VERSIONS_SCHEMA, SKILLS_SCHEMA, SKILL_BLOBS_SCHEMA, SKILL_VERSIONS_SCHEMA, SPAN_SCHEMA, SchedulesStorage, ScorerDefinitionsStorage, ScoresStorage, SkillsStorage, StoreOperations, 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_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_TOOL_PROVIDER_CONNECTIONS, TABLE_WORKFLOW_DEFINITIONS, TABLE_WORKFLOW_RUN_OWNERS, TABLE_WORKFLOW_SNAPSHOT, TABLE_WORKSPACES, TABLE_WORKSPACE_VERSIONS, TOOL_PROVIDER_CONNECTIONS_SCHEMA, ToolProviderConnectionsStorage, TraceStatus, WORKFLOW_DEFINITIONS_SCHEMA, WORKSPACES_SCHEMA, WORKSPACE_VERSIONS_SCHEMA, WorkflowDefinitionsStorage, WorkflowsStorage, WorkspacesStorage, calculatePagination, createKnowledgeUlid, createStorageErrorId, executeRetentionPrune, hasErrorCode, isRunFenceConflictError, listTracesArgsSchema, matchesExpectedWorkflowStatus, matchesRunFence, normalizePerPage, normalizeScheduleTarget, resolveListOrderBy, resolveRetentionTargets, resolveRunFence, retentionCutoffMs, toTraceSpans, validateStorageMetadataFilter } from "@mastra/core/storage";
 import { createPool } from "mysql2/promise";
 import { parseSqlIdentifier } from "@mastra/core/utils";
+import { coreFeatures } from "@mastra/core/features";
 import { createHash } from "crypto";
 import { MessageList } from "@mastra/core/agent";
 import { skillSnapshotFieldValuesEqual } from "@mastra/core/storage/domains/skills";
@@ -1375,7 +1376,7 @@ function serializeJson(v) {
 	if (typeof v === "object" && v != null) return JSON.stringify(v);
 	return v ?? null;
 }
-function parseJson$2(val) {
+function parseJson$1(val) {
 	if (val == null) return void 0;
 	if (typeof val === "string") try {
 		return JSON.parse(val);
@@ -1390,14 +1391,14 @@ function rowToTask(row) {
 		status: String(row.status),
 		toolName: String(row.tool_name),
 		toolCallId: String(row.tool_call_id),
-		args: parseJson$2(row.args) ?? {},
+		args: parseJson$1(row.args) ?? {},
 		agentId: String(row.agent_id),
 		threadId: row.thread_id != null ? String(row.thread_id) : void 0,
 		resourceId: row.resource_id != null ? String(row.resource_id) : void 0,
 		runId: String(row.run_id),
-		result: parseJson$2(row.result),
-		error: parseJson$2(row.error),
-		suspendPayload: parseJson$2(row.suspend_payload),
+		result: parseJson$1(row.result),
+		error: parseJson$1(row.error),
+		suspendPayload: parseJson$1(row.suspend_payload),
 		retryCount: Number(row.retry_count),
 		maxRetries: Number(row.max_retries),
 		timeoutMs: Number(row.timeout_ms),
@@ -1408,7 +1409,7 @@ function rowToTask(row) {
 		ownerId: row.ownerId != null ? String(row.ownerId) : void 0,
 		leaseExpiresAt: parseDateTime(row.leaseExpiresAt),
 		expiresAt: parseDateTime(row.expiresAt),
-		metadata: parseJson$2(row.metadata)
+		metadata: parseJson$1(row.metadata)
 	};
 }
 var BackgroundTasksMySQL = class BackgroundTasksMySQL extends BackgroundTasksStorage {
@@ -4186,899 +4187,1645 @@ var FavoritesMySQL = class FavoritesMySQL extends FavoritesStorage {
 		}
 	}
 };
-// src/storage/domains/knowledge/index.ts
-let assertDescriptionWithinBound;
-async function assertKnowledgeDescriptionWithinBoundCompat(description) {
-	let assertWithinBound = assertDescriptionWithinBound;
-	if (!assertWithinBound) {
-		const resolvedAssert = (await import("@mastra/core/storage")).assertKnowledgeDescriptionWithinBound ?? ((value) => {
-			if (value !== void 0 && value.length > 400) throw new Error("Knowledge node description exceeds the 400 UTF-16 code unit limit");
-		});
-		assertDescriptionWithinBound = resolvedAssert;
-		assertWithinBound = resolvedAssert;
-	}
-	assertWithinBound(description);
-}
-let assertRecordTextWithinBound;
-async function assertKnowledgeRecordTextWithinBoundCompat(text) {
-	if (!assertRecordTextWithinBound) assertRecordTextWithinBound = (await import("@mastra/core/storage")).assertKnowledgeRecordTextWithinBound ?? ((value) => {
-		if (value.length > 1e3) throw new Error("Knowledge record text exceeds the 1000 UTF-16 code unit limit; split it into separate facts or summarize it");
-	});
-	assertRecordTextWithinBound(text);
-}
-function mysqlSql(sql) {
-	return sql.replaceAll("jsonb(?)", "CAST(? AS JSON)").replaceAll("INSERT OR IGNORE", "INSERT IGNORE").replaceAll("\"", "`");
-}
-function createExecutor(client) {
-	return { async execute(statement) {
-		const sql = typeof statement === "string" ? statement : statement.sql;
-		const args = (typeof statement === "string" ? [] : statement.args ?? []).map((value) => typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value) ? value.replace("T", " ").replace("Z", "") : value);
-		const [result] = await client.query(mysqlSql(sql), args);
-		if (Array.isArray(result)) return {
-			rows: result,
-			rowsAffected: 0
+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 TABLE_KNOWLEDGE_PAGES = "mastra_knowledge_pages";
+const TABLE_KNOWLEDGE_NOTES = "mastra_knowledge_notes";
+const TABLE_KNOWLEDGE_NOTE_STAMPS = "mastra_knowledge_note_stamps";
+/** Same name as the schema-2 table; schema 4 re-keys it to note → page. */
+const TABLE_KNOWLEDGE_PAGE_MENTIONS = "mastra_knowledge_mentions";
+const TABLE_KNOWLEDGE_PINS = "mastra_knowledge_pins";
+/** Same name as schema 2; schema 4 re-keys it to scope/page/note. */
+const TABLE_KNOWLEDGE_PAGE_ACTIVITY = "mastra_knowledge_activity";
+/** Holds `{ id: 'knowledge', schemaVersion: 4 }`, written when the schema-4 tables are created. */
+const TABLE_KNOWLEDGE_PAGES_STATE = "mastra_knowledge_access_state";
+const KNOWLEDGE_PAGES_TABLE_NAMES = [
+	TABLE_KNOWLEDGE_PAGES,
+	TABLE_KNOWLEDGE_NOTES,
+	TABLE_KNOWLEDGE_NOTE_STAMPS,
+	TABLE_KNOWLEDGE_PAGE_MENTIONS,
+	TABLE_KNOWLEDGE_PINS,
+	TABLE_KNOWLEDGE_PAGE_ACTIVITY,
+	TABLE_KNOWLEDGE_PAGES_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(", ")})`
+	};
+	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 {
-			rows: [],
-			rowsAffected: result.affectedRows
+			status: "incompatible-reset-required",
+			schemaVersion: null,
+			reason: `found Knowledge tables (${present.join(", ")}) without a schema version`
 		};
-	} };
+	}
+	return {
+		status: "incompatible-reset-required",
+		schemaVersion: snapshot.schemaVersion,
+		reason: `Knowledge schema version ${snapshot.schemaVersion} is not 4`
+	};
 }
+/** 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));
 /**
-* 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.
+* 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 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];
+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));
 }
-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;
+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;
 }
-function toDate(value) {
-	return value instanceof Date ? new Date(value) : new Date(String(value));
+/** 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;
+	};
 }
-function optionalDate(value) {
-	return value == null ? void 0 : toDate(value);
+/**
+* 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))];
 }
-function databaseTimestamp(value) {
-	const pad = (part, width = 2) => String(part).padStart(width, "0");
-	return `${value.getFullYear()}-${pad(value.getMonth() + 1)}-${pad(value.getDate())} ${pad(value.getHours())}:${pad(value.getMinutes())}:${pad(value.getSeconds())}.${pad(value.getMilliseconds(), 3)}`;
+/**
+* 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 "%"`;
 }
-function canonicalName(name) {
-	return name.trim().toLocaleLowerCase();
+// src/storage/domains/knowledge/pages.ts
+const loadPagesCore = createKnowledgePagesCoreLoader(coreFeatures, () => import("@mastra/core/storage"));
+const assertKnowledgePageDescriptionWithinBound = async (description) => (await loadPagesCore()).assertKnowledgePageDescriptionWithinBound(description);
+const assertKnowledgeNoteTextWithinBound = async (text) => (await loadPagesCore()).assertKnowledgeNoteTextWithinBound(text);
+const T = {
+	pages: "`mastra_knowledge_pages`",
+	notes: "`mastra_knowledge_notes`",
+	stamps: "`mastra_knowledge_note_stamps`",
+	mentions: "`mastra_knowledge_mentions`",
+	pins: "`mastra_knowledge_pins`",
+	pinAudiences: "`mastra_knowledge_pin_audiences`",
+	activity: "`mastra_knowledge_activity`"
+};
+const KEY = "`key`";
+const WHEN = "`when`";
+const BIN = "CHARACTER SET utf8mb4 COLLATE utf8mb4_bin";
+const JV = `(SELECT jv.v FROM JSON_TABLE(?, '$[*]' COLUMNS (v VARCHAR(512) ${BIN} PATH '$')) jv)`;
+/** Live sibling keys are unique per parent; NULL for deleted pages and pages without a key. */
+const LIVE_KEY_COLUMN = `VARCHAR(768) ${BIN} AS (IF(deletedAt IS NULL AND \`key\` IS NOT NULL, CONCAT(parentId, '#', \`key\`), NULL)) STORED`;
+const MISSING_PAGE_INDEX = `SELECT 1 FROM DUAL WHERE NOT EXISTS (SELECT 1 FROM information_schema.statistics WHERE table_schema = DATABASE() AND table_name = 'mastra_knowledge_pages' AND index_name = ?)`;
+/** Upgrades for Knowledge databases created by an earlier alpha build; `needed` returns a row when `apply` must run. */
+const KNOWLEDGE_PAGE_UPGRADES = [
+	{
+		needed: `SELECT 1 FROM information_schema.columns WHERE table_schema = DATABASE() AND table_name = 'mastra_knowledge_pages' AND column_name = 'liveKey' AND generation_expression LIKE '%scopeId%'`,
+		args: [],
+		apply: [`ALTER TABLE \`mastra_knowledge_pages\` DROP INDEX idx_kpages_live_key, DROP COLUMN liveKey, ADD COLUMN liveKey ${LIVE_KEY_COLUMN}, ADD UNIQUE KEY idx_kpages_live_key (liveKey)`]
+	},
+	{
+		needed: `SELECT 1 FROM information_schema.columns WHERE table_schema = DATABASE() AND table_name = 'mastra_knowledge_pin_audiences' AND column_name = 'audience' AND character_maximum_length < 512`,
+		args: [],
+		apply: [`ALTER TABLE \`mastra_knowledge_pin_audiences\` MODIFY audience VARCHAR(512) ${BIN} NOT NULL`]
+	},
+	{
+		needed: MISSING_PAGE_INDEX,
+		args: ["idx_kpages_path"],
+		apply: ["ALTER TABLE `mastra_knowledge_pages` ADD KEY idx_kpages_path (path(255))"]
+	},
+	{
+		needed: MISSING_PAGE_INDEX,
+		args: ["idx_kpages_declaration_parent"],
+		apply: ["ALTER TABLE `mastra_knowledge_pages` ADD KEY idx_kpages_declaration_parent (declaration, parentId)"]
+	},
+	{
+		needed: `SELECT 1 FROM DUAL WHERE EXISTS (SELECT 1 FROM mastra_knowledge_pins pin, JSON_TABLE(pin.audience, '$[*]' COLUMNS (v VARCHAR(512) ${BIN} PATH '$')) jv WHERE NOT EXISTS (SELECT 1 FROM mastra_knowledge_pin_audiences pa WHERE pa.pinId = pin.id AND pa.audience = jv.v))`,
+		args: [],
+		apply: [`INSERT IGNORE INTO mastra_knowledge_pin_audiences (audience, pinId) SELECT jv.v, pin.id FROM mastra_knowledge_pins pin, JSON_TABLE(pin.audience, '$[*]' COLUMNS (v VARCHAR(512) ${BIN} PATH '$')) jv`]
+	}
+];
+/** DDL for the schema-4 page tables, in creation order. Every statement is idempotent. */
+const KNOWLEDGE_PAGE_DDL = [
+	`CREATE TABLE IF NOT EXISTS \`mastra_knowledge_access_state\` (
+    id VARCHAR(64) ${BIN} NOT NULL PRIMARY KEY,
+    schemaVersion INT NOT NULL
+  )`,
+	`CREATE TABLE IF NOT EXISTS ${T.pages} (
+    id VARCHAR(255) ${BIN} NOT NULL PRIMARY KEY,
+    scopeId VARCHAR(255) ${BIN} NOT NULL,
+    isScope TINYINT NOT NULL,
+    address VARCHAR(512) ${BIN} NULL,
+    declaration VARCHAR(255) ${BIN} NULL,
+    \`key\` VARCHAR(255) ${BIN} NULL,
+    parentId VARCHAR(255) ${BIN} NULL,
+    position VARCHAR(255) ${BIN} NOT NULL,
+    path VARCHAR(2048) ${BIN} NOT NULL,
+    depth INT NOT NULL,
+    name VARCHAR(512) ${BIN} NOT NULL,
+    canonicalName VARCHAR(512) ${BIN} NOT NULL,
+    description TEXT NULL,
+    body LONGTEXT NULL,
+    version INT NOT NULL,
+    mergedInto VARCHAR(255) ${BIN} NULL,
+    createdBy TEXT NOT NULL,
+    updatedBy TEXT NOT NULL,
+    createdAt VARCHAR(32) NOT NULL,
+    updatedAt VARCHAR(32) NOT NULL,
+    deletedAt VARCHAR(32) NULL,
+    deletedBy VARCHAR(255) NULL,
+    liveKey ${LIVE_KEY_COLUMN},
+    UNIQUE KEY idx_kpages_address (address),
+    UNIQUE KEY idx_kpages_live_key (liveKey),
+    KEY idx_kpages_scope (scopeId),
+    KEY idx_kpages_parent (parentId, position, id),
+    KEY idx_kpages_path (path(255)),
+    KEY idx_kpages_declaration_parent (declaration, parentId),
+    KEY idx_kpages_canonical (canonicalName(255))
+  )`,
+	`CREATE TABLE IF NOT EXISTS ${T.notes} (
+    id VARCHAR(255) ${BIN} NOT NULL PRIMARY KEY,
+    pageId VARCHAR(255) ${BIN} NOT NULL,
+    text LONGTEXT NOT NULL,
+    \`when\` VARCHAR(32) NULL,
+    provenance TEXT NOT NULL,
+    version INT NOT NULL,
+    createdAt VARCHAR(32) NOT NULL,
+    updatedAt VARCHAR(32) NOT NULL,
+    deletedAt VARCHAR(32) NULL,
+    deletedBy VARCHAR(255) NULL,
+    KEY idx_knotes_page (pageId, createdAt, id)
+  )`,
+	`CREATE TABLE IF NOT EXISTS ${T.stamps} (
+    noteId VARCHAR(255) ${BIN} NOT NULL,
+    scopeId VARCHAR(255) ${BIN} NOT NULL,
+    PRIMARY KEY (noteId, scopeId),
+    KEY idx_kstamps_scope (scopeId)
+  )`,
+	`CREATE TABLE IF NOT EXISTS ${T.mentions} (
+    noteId VARCHAR(255) ${BIN} NOT NULL,
+    pageId VARCHAR(255) ${BIN} NOT NULL,
+    PRIMARY KEY (noteId, pageId),
+    KEY idx_kmentions_page (pageId)
+  )`,
+	`CREATE TABLE IF NOT EXISTS ${T.pins} (
+    id VARCHAR(255) ${BIN} NOT NULL PRIMARY KEY,
+    pageId VARCHAR(255) ${BIN} NOT NULL,
+    audience JSON NOT NULL,
+    createdBy VARCHAR(255) NOT NULL,
+    createdAt VARCHAR(32) NOT NULL,
+    updatedAt VARCHAR(32) NOT NULL,
+    UNIQUE KEY idx_kpins_page (pageId)
+  )`,
+	`CREATE TABLE IF NOT EXISTS ${T.pinAudiences} (
+    audience VARCHAR(512) ${BIN} NOT NULL,
+    pinId VARCHAR(255) ${BIN} NOT NULL,
+    PRIMARY KEY (audience, pinId),
+    KEY idx_kpin_audiences_pin (pinId)
+  )`,
+	`CREATE TABLE IF NOT EXISTS ${T.activity} (
+    id VARCHAR(255) ${BIN} NOT NULL PRIMARY KEY,
+    action VARCHAR(64) NOT NULL,
+    scopeId VARCHAR(255) ${BIN} NOT NULL,
+    pageId VARCHAR(255) ${BIN} NOT NULL,
+    noteId VARCHAR(255) ${BIN} NULL,
+    provenance TEXT NOT NULL,
+    createdAt VARCHAR(32) NOT NULL,
+    KEY idx_kactivity_page (pageId, id)
+  )`
+];
+function str(value) {
+	return value === null || value === void 0 ? void 0 : String(value);
 }
-function nodeReferenceId(node) {
-	return typeof node === "string" ? node : node.id;
+function date(value) {
+	return value === null || value === void 0 ? void 0 : new Date(String(value));
 }
-function escapeLikePattern(value) {
-	return value.replaceAll("=", "==").replaceAll("%", "=%").replaceAll("_", "=_");
+function provenance(raw) {
+	return JSON.parse(String(raw));
 }
-function parseNode(row) {
+function toPage(row) {
 	return {
 		id: String(row.id),
-		type: "node",
+		scopeId: String(row.scopeId),
+		parentId: str(row.parentId) ?? null,
+		isScope: Number(row.isScope) === 1,
+		...row.address !== null && row.address !== void 0 ? { address: String(row.address) } : {},
+		...row.declaration !== null && row.declaration !== void 0 ? { declaration: String(row.declaration) } : {},
+		...row.key !== null && row.key !== void 0 ? { key: String(row.key) } : {},
+		position: String(row.position),
 		name: String(row.name),
-		kind: String(row.kind),
-		content: row.content == null ? void 0 : String(row.content),
-		description: row.description == null ? void 0 : String(row.description),
-		scope: parseJson$1(row.scopeJson ?? row.scope),
+		...row.description !== null && row.description !== void 0 ? { description: String(row.description) } : {},
+		...row.body !== null && row.body !== void 0 ? { body: String(row.body) } : {},
 		version: Number(row.version),
-		mergedInto: row.mergedInto == null ? void 0 : String(row.mergedInto),
-		createdAt: toDate(row.createdAt),
-		updatedAt: toDate(row.updatedAt)
+		...row.mergedInto !== null && row.mergedInto !== void 0 ? { mergedInto: String(row.mergedInto) } : {},
+		createdBy: provenance(row.createdBy),
+		updatedBy: provenance(row.updatedBy),
+		createdAt: new Date(String(row.createdAt)),
+		updatedAt: new Date(String(row.updatedAt)),
+		...row.deletedAt ? { deletedAt: new Date(String(row.deletedAt)) } : {},
+		...row.deletedBy ? { deletedBy: String(row.deletedBy) } : {}
 	};
 }
-function parseKnowledge(row) {
+function toNote(row, stamps, mentions) {
+	const when = date(row.when);
 	return {
 		id: String(row.id),
-		node: String(row.node),
+		pageId: String(row.pageId),
 		text: String(row.text),
-		scope: parseJson$1(row.scopeJson ?? row.scope),
-		sourceThreadId: String(row.sourceThreadId),
-		capturedAt: toDate(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)
+		...when ? { when } : {},
+		stampScopeIds: stamps,
+		mentions,
+		provenance: provenance(row.provenance),
+		version: Number(row.version),
+		createdAt: new Date(String(row.createdAt)),
+		updatedAt: new Date(String(row.updatedAt)),
+		...row.deletedAt ? { deletedAt: new Date(String(row.deletedAt)) } : {},
+		...row.deletedBy ? { deletedBy: String(row.deletedBy) } : {}
 	};
 }
-function parseOutbox(row) {
+function toPin(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(row.availableAt),
-		claimedAt: optionalDate(row.claimedAt),
-		claimedBy: row.claimedBy == null ? void 0 : String(row.claimedBy),
-		createdAt: toDate(row.createdAt),
-		completedAt: optionalDate(row.completedAt)
+		pageId: String(row.pageId),
+		audience: parseJsonList(row.audience),
+		createdBy: String(row.createdBy),
+		createdAt: new Date(String(row.createdAt)),
+		updatedAt: new Date(String(row.updatedAt))
 	};
 }
-const KNOWLEDGE_INDEX_DDL = [
-	`CREATE UNIQUE INDEX idx_knowledge_nodes_identity ON "${TABLE_KNOWLEDGE_NODES}" (type(32), scopeKey(255), canonicalName(255))`,
-	`CREATE INDEX idx_knowledge_nodes_scope ON "${TABLE_KNOWLEDGE_NODES}" (scopeKey(255), type(32))`,
-	`CREATE INDEX idx_knowledge_nodes_name ON "${TABLE_KNOWLEDGE_NODES}" (type(32), canonicalName(255))`,
-	`CREATE INDEX idx_knowledge_records_node_latest ON "${TABLE_KNOWLEDGE_RECORDS}" (node(191), id(26) DESC)`,
-	`CREATE INDEX idx_knowledge_records_thread_latest ON "${TABLE_KNOWLEDGE_RECORDS}" (sourceThreadId(191), id(26) DESC)`,
-	`CREATE INDEX idx_knowledge_mentions_record ON "${TABLE_KNOWLEDGE_MENTIONS}" (recordId(191), sourceType(32), sourceId(191))`,
-	`CREATE INDEX idx_knowledge_activity_latest ON "${TABLE_KNOWLEDGE_ACTIVITY}" (id(26) DESC)`,
-	`CREATE INDEX idx_knowledge_records_scope ON "${TABLE_KNOWLEDGE_RECORDS}" (scopeKey(255), id(26))`,
-	`CREATE INDEX idx_knowledge_activity_scope ON "${TABLE_KNOWLEDGE_ACTIVITY}" (scopeKey(255), id(26) DESC)`,
-	`CREATE UNIQUE INDEX idx_knowledge_outbox_idempotency ON "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" (idempotencyKey(255))`,
-	`CREATE INDEX idx_knowledge_outbox_claim ON "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" (status(32), availableAt, createdAt)`
-];
-const KNOWLEDGE_CURATION_CURSOR_REMOVED_MESSAGE = "Knowledge curation cursors were removed: observation-time curate is the only Knowledge writer and needs no cursor.";
-var KnowledgeMySQL = class extends KnowledgeStorage {
-	static getExportDDL() {
-		return [
-			generateTableSQL({
-				tableName: TABLE_KNOWLEDGE_NODES,
-				schema: KNOWLEDGE_NODES_SCHEMA
-			}),
-			generateTableSQL({
-				tableName: TABLE_KNOWLEDGE_RECORDS,
-				schema: KNOWLEDGE_RECORDS_SCHEMA
-			}),
-			generateTableSQL({
-				tableName: TABLE_KNOWLEDGE_MENTIONS,
-				schema: KNOWLEDGE_MENTIONS_SCHEMA,
-				compositePrimaryKey: [
-					"sourceType",
-					"sourceId",
-					"recordId"
-				]
-			}),
-			generateTableSQL({
-				tableName: TABLE_KNOWLEDGE_ACTIVITY,
-				schema: KNOWLEDGE_ACTIVITY_SCHEMA
-			}),
-			generateTableSQL({
-				tableName: TABLE_KNOWLEDGE_SEMANTIC_OUTBOX,
-				schema: KNOWLEDGE_SEMANTIC_OUTBOX_SCHEMA
-			}),
-			...KNOWLEDGE_INDEX_DDL.map(mysqlSql)
-		];
-	}
-	#pool;
-	#client;
-	#operations;
-	constructor({ pool, operations }) {
-		super();
-		this.#pool = pool;
-		this.#client = createExecutor(pool);
-		this.#operations = operations;
+function toListedPin(row) {
+	return {
+		...toPin(row),
+		pageName: String(row.pageName)
+	};
+}
+function limitOf(limit, max) {
+	return Math.max(1, Math.min(limit ?? max, max));
+}
+function encodeCursor(value) {
+	return Buffer.from(JSON.stringify(value)).toString("base64url");
+}
+function decodeCursor(cursor, length) {
+	if (cursor === void 0) return void 0;
+	try {
+		const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+		if (Array.isArray(parsed) && parsed.length === length && parsed.every((item) => typeof item === "string")) return parsed;
+	} catch {}
+	throw new Error("Invalid Knowledge cursor");
+}
+function isRetryableRace(error) {
+	for (let current = error; current && typeof current === "object"; current = current.cause) {
+		const { code, errno } = current;
+		if (code === "ER_DUP_ENTRY" || errno === 1062 || code === "ER_LOCK_DEADLOCK" || errno === 1213) return true;
 	}
-	async init() {
-		await this.#operations.createTable({
-			tableName: TABLE_KNOWLEDGE_NODES,
-			schema: KNOWLEDGE_NODES_SCHEMA
-		});
-		await this.#operations.alterTable({
-			tableName: TABLE_KNOWLEDGE_NODES,
-			schema: KNOWLEDGE_NODES_SCHEMA,
-			ifNotExists: ["description"]
-		});
-		await this.#operations.createTable({
-			tableName: TABLE_KNOWLEDGE_RECORDS,
-			schema: KNOWLEDGE_RECORDS_SCHEMA
-		});
-		await this.#operations.createTable({
-			tableName: TABLE_KNOWLEDGE_MENTIONS,
-			schema: KNOWLEDGE_MENTIONS_SCHEMA
-		});
-		await this.#operations.createTable({
-			tableName: TABLE_KNOWLEDGE_ACTIVITY,
-			schema: KNOWLEDGE_ACTIVITY_SCHEMA
-		});
-		await this.#operations.createTable({
-			tableName: TABLE_KNOWLEDGE_SEMANTIC_OUTBOX,
-			schema: KNOWLEDGE_SEMANTIC_OUTBOX_SCHEMA
-		});
-		for (const sql of KNOWLEDGE_INDEX_DDL) try {
-			await this.#client.execute(sql);
-		} catch (error) {
-			if (error.code !== "ER_DUP_KEYNAME") throw error;
+	return false;
+}
+function escapeLike(value) {
+	return value.replace(/[=%_]/g, (match) => `=${match}`);
+}
+/**
+* A string above every string that starts with `prefix`, comparing by code point (which is how
+* `utf8mb4_bin` orders). `column >= prefix AND column < bound` is an exact, case-sensitive prefix
+* match that an index range scan can serve, where `LEFT(column, CHAR_LENGTH(prefix)) = prefix`
+* cannot. When the last code point cannot be raised (an empty prefix, or one made only of
+* U+10FFFF), the bound is the prefix plus more U+10FFFF than an address column can hold (512).
+*/
+function prefixUpperBound(prefix) {
+	const points = Array.from(prefix);
+	while (points.length > 0) {
+		const last = points.pop().codePointAt(0);
+		if (last < 1114111) {
+			const next = last === 55295 ? 57344 : last + 1;
+			return points.join("") + String.fromCodePoint(next);
 		}
 	}
-	async dangerouslyClearAll() {
+	return prefix + "􏿿".repeat(600);
+}
+/**
+* `utf8mb4_bin` is PAD SPACE: a value compares as if padded with spaces, so `p:a\t` sorts below `p:a`.
+* Starting the range at the prefix plus U+0000 keeps every value that begins with the prefix, whatever
+* code point follows. (Values equal to the prefix plus trailing spaces still match, as they always have.)
+*/
+function prefixLowerBound(prefix) {
+	return prefix + "\0";
+}
+/** `column` starts with `prefix`, as an index-friendly range. */
+function prefixRange(column, prefix) {
+	return {
+		sql: `(${column} >= ? AND ${column} < ?)`,
+		args: [prefixLowerBound(prefix), prefixUpperBound(prefix)]
+	};
+}
+/**
+* The readable scope page ids as a subquery. The caller's addresses, prefixes and children go in as
+* JSON arrays so a large read scope never hits a bind-parameter limit. Each kind is its own index
+* lookup (address equality, address range for a prefix, `(declaration, parentId)` for children),
+* unioned, so the cost follows the caller's reach rather than the number of scopes in the store.
+*/
+function readableScopes(read) {
+	if (read === "all") return {
+		sql: `SELECT id FROM ${T.pages} WHERE isScope = 1`,
+		args: []
+	};
+	const parts = [];
+	const args = [];
+	if (read.addresses.length > 0) {
+		parts.push(`SELECT id FROM ${T.pages} WHERE isScope = 1 AND address IN ${JV}`);
+		args.push(JSON.stringify(read.addresses));
+	}
+	if (read.prefixes.length > 0) {
+		parts.push(`SELECT sp.id FROM JSON_TABLE(?, '$[*]' COLUMNS (d VARCHAR(255) ${BIN} PATH '$.declaration', lo VARCHAR(512) ${BIN} PATH '$.lo', hi VARCHAR(1200) ${BIN} PATH '$.hi')) j STRAIGHT_JOIN ${T.pages} sp USE INDEX (idx_kpages_address) ON sp.address >= j.lo AND sp.address < j.hi AND sp.isScope = 1 AND sp.declaration = j.d`);
+		args.push(JSON.stringify(read.prefixes.map((entry) => ({
+			declaration: entry.declaration,
+			lo: prefixLowerBound(entry.prefix),
+			hi: prefixUpperBound(entry.prefix)
+		}))));
+	}
+	if (read.children.length > 0) {
+		parts.push(`SELECT sp.id FROM JSON_TABLE(?, '$[*]' COLUMNS (d VARCHAR(255) ${BIN} PATH '$.declaration', pid VARCHAR(255) ${BIN} PATH '$.parentId' NULL ON EMPTY)) j STRAIGHT_JOIN ${T.pages} sp ON sp.isScope = 1 AND sp.declaration = j.d AND sp.parentId <=> j.pid`);
+		args.push(JSON.stringify(read.children));
+	}
+	if (parts.length === 0) return {
+		sql: `SELECT id FROM ${T.pages} WHERE 0`,
+		args: []
+	};
+	return {
+		sql: parts.join(" UNION "),
+		args
+	};
+}
+/**
+* `FROM` clause that reads the readable scopes first and then each one's pages through `idx_kpages_scope`.
+* MySQL otherwise tends to scan every page in the store and test its scope, which touches other
+* tenants' rows. The `alias` pages are in readable scopes; add the page filters in `WHERE`.
+*/
+function pagesInReadableScopes(alias, read) {
+	const scopes = readableScopes(read);
+	return {
+		sql: `FROM (${scopes.sql}) rs STRAIGHT_JOIN ${T.pages} ${alias} FORCE INDEX (idx_kpages_scope) ON ${alias}.scopeId = rs.id`,
+		args: scopes.args
+	};
+}
+/** `alias.scopeId` is readable. */
+function pageReadable(alias, read) {
+	const scopes = readableScopes(read);
+	return {
+		sql: `${alias}.scopeId IN (SELECT rs.id FROM (${scopes.sql}) rs)`,
+		args: scopes.args
+	};
+}
+/**
+* Note `alias` is visible: its page's scope is readable, a stamp is readable, and every resolved
+* mention's page sits in a readable scope.
+*/
+function noteReadable(alias, read) {
+	const scopes = readableScopes(read);
+	return {
+		sql: `EXISTS (SELECT 1 FROM ${T.pages} vp WHERE vp.id = ${alias}.pageId AND vp.scopeId IN (${scopes.sql}))
+      AND EXISTS (SELECT 1 FROM ${T.stamps} vs WHERE vs.noteId = ${alias}.id AND vs.scopeId IN (${scopes.sql}))
+      AND NOT EXISTS (SELECT 1 FROM ${T.mentions} vm JOIN ${T.pages} vmp ON vmp.id = vm.pageId WHERE vm.noteId = ${alias}.id AND vmp.scopeId NOT IN (${scopes.sql}))`,
+		args: [
+			...scopes.args,
+			...scopes.args,
+			...scopes.args
+		]
+	};
+}
+function jsonList(values) {
+	return JSON.stringify(values);
+}
+var MySQLKnowledgePages = class {
+	#read;
+	#transaction;
+	constructor(config) {
+		this.#read = config.read;
+		this.#transaction = config.transaction;
+	}
+	/** Deletes every row from the page tables (scopes, pages, notes, pins, activity). */
+	async clearAll() {
 		await this.#transaction(async (tx) => {
 			for (const table of [
-				TABLE_KNOWLEDGE_MENTIONS,
-				TABLE_KNOWLEDGE_RECORDS,
-				TABLE_KNOWLEDGE_NODES,
-				TABLE_KNOWLEDGE_ACTIVITY,
-				TABLE_KNOWLEDGE_SEMANTIC_OUTBOX
-			]) await tx.execute(`DELETE FROM "${table}"`);
+				T.activity,
+				T.pinAudiences,
+				T.pins,
+				T.mentions,
+				T.stamps,
+				T.notes,
+				T.pages
+			]) await tx.execute({
+				sql: `DELETE FROM ${table}`,
+				args: []
+			});
 		});
 	}
-	async createNode(input) {
-		await assertKnowledgeDescriptionWithinBoundCompat(input.description);
-		if (input.scopeAddresses?.length) {
-			const error = /* @__PURE__ */ new Error("This Knowledge storage adapter does not expose structural scope placement.");
-			error.name = "KnowledgeUnsupportedCapabilityError";
-			throw error;
+	async #query(executor, sql, args = []) {
+		return (await executor.execute({
+			sql,
+			args
+		})).rows;
+	}
+	async #pageRow(executor, id) {
+		return (await this.#query(executor, `SELECT * FROM ${T.pages} WHERE id = ?`, [id]))[0];
+	}
+	async #livePage(executor, id) {
+		const row = await this.#pageRow(executor, id);
+		if (!row || row.deletedAt) throw new KnowledgeNotFoundError("page", id);
+		return row;
+	}
+	async #logActivity(tx, action, event, now) {
+		await tx.execute({
+			sql: `INSERT INTO ${T.activity} (id, action, scopeId, pageId, noteId, provenance, createdAt) VALUES (?, ?, ?, ?, ?, ?, ?)`,
+			args: [
+				createKnowledgeUlid(),
+				action,
+				event.scopeId,
+				event.pageId,
+				event.noteId ?? null,
+				JSON.stringify(event.provenance),
+				now
+			]
+		});
+	}
+	async #lastPosition(tx, parentId, scopesOnly) {
+		const rows = await this.#query(tx, `SELECT position FROM ${T.pages} WHERE parentId <=> ? AND isScope = ? AND deletedAt IS NULL ORDER BY position DESC, id DESC LIMIT 1`, [parentId, scopesOnly ? 1 : 0]);
+		return rows[0] ? String(rows[0].position) : void 0;
+	}
+	async materializeScope(input) {
+		for (let attempt = 1;; attempt++) try {
+			return await this.#materializeScopeOnce(input);
+		} catch (error) {
+			if (attempt >= 5 || !isRetryableRace(error)) throw error;
 		}
-		const scope = canonicalizeKnowledgeScope(input.scope);
+	}
+	async #materializeScopeOnce(input) {
+		const core = await loadPagesCore();
+		await assertKnowledgePageDescriptionWithinBound(input.description);
 		return this.#transaction(async (tx) => {
-			const existing = await this.#getNodeByName(tx, input.name, scope);
-			if (existing) {
-				const terminal = await this.#resolveTerminalNode(tx, existing.id);
-				if (!isKnowledgeScopeVisible(terminal.scope, scope)) throw new Error(`Merged knowledge node is not visible from scope: ${input.name}`);
-				return terminal;
+			const now = (/* @__PURE__ */ new Date()).toISOString();
+			const ensureScope = async (spec, parentId) => {
+				await assertKnowledgePageDescriptionWithinBound(spec.description);
+				const existing = (await this.#query(tx, `SELECT * FROM ${T.pages} WHERE isScope = 1 AND address = ?`, [spec.address]))[0];
+				if (existing) return {
+					row: existing,
+					created: false
+				};
+				if (parentId !== null) await this.#livePage(tx, parentId);
+				const id = createKnowledgeUlid();
+				const position = core.knowledgePositionBetween(await this.#lastPosition(tx, parentId, true));
+				const who = JSON.stringify(input.provenance);
+				await tx.execute({
+					sql: `INSERT INTO ${T.pages} (id, scopeId, isScope, address, declaration, parentId, position, path, depth, name, canonicalName, description, version, createdBy, updatedBy, createdAt, updatedAt) VALUES (?, ?, 1, ?, ?, ?, ?, ?, 0, ?, ?, ?, 1, ?, ?, ?, ?)`,
+					args: [
+						id,
+						id,
+						spec.address,
+						spec.declaration,
+						parentId,
+						position,
+						`/${id}/`,
+						spec.name,
+						core.canonicalKnowledgeName(spec.name),
+						spec.description ?? null,
+						who,
+						who,
+						now,
+						now
+					]
+				});
+				await this.#logActivity(tx, "scope-created", {
+					scopeId: id,
+					pageId: id,
+					provenance: input.provenance
+				}, now);
+				return {
+					row: await this.#pageRow(tx, id),
+					created: true
+				};
+			};
+			const ensured = await ensureScope(input, input.parentId ?? null);
+			let row = ensured.row;
+			const created = ensured.created;
+			const scopeId = String(row.id);
+			if (!created && input.parentId != null && str(row.parentId) === void 0) {
+				await this.#livePage(tx, input.parentId);
+				if (input.parentId === scopeId) throw new Error(`Scope ${scopeId} cannot be its own parent`);
+				let ancestor = input.parentId;
+				while (ancestor) {
+					const up = await this.#pageRow(tx, ancestor);
+					if (String(up.id) === scopeId) throw new Error(`Scope ${scopeId} cannot be linked under its own descendant`);
+					ancestor = str(up.parentId);
+				}
+				await tx.execute({
+					sql: `UPDATE ${T.pages} SET parentId = ?, position = ?, version = version + 1, updatedAt = ? WHERE id = ? AND parentId IS NULL`,
+					args: [
+						input.parentId,
+						core.knowledgePositionBetween(await this.#lastPosition(tx, input.parentId, true)),
+						now,
+						scopeId
+					]
+				});
+				row = await this.#pageRow(tx, scopeId);
 			}
-			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
+			let parentConflict;
+			if (!created && input.parentId !== void 0 && (str(row.parentId) ?? null) !== input.parentId) parentConflict = {
+				existingParentId: str(row.parentId) ?? null,
+				requestedParentId: input.parentId
+			};
+			for (const child of input.children ?? []) await ensureScope(child, scopeId);
+			const ensureTemplates = async (templates, parentId) => {
+				for (const template of templates) {
+					const problem = knowledgePageKeyProblem(template.key);
+					if (problem) throw new Error(problem);
+					const existing = (await this.#query(tx, `SELECT id FROM ${T.pages} WHERE parentId = ? AND isScope = 0 AND ${KEY} = ? AND deletedAt IS NULL`, [parentId, template.key]))[0];
+					const id = existing ? String(existing.id) : (await this.#insertPage(tx, {
+						parentId,
+						key: template.key,
+						name: template.name,
+						description: template.description,
+						provenance: input.provenance
+					})).id;
+					if (template.pages?.length) await ensureTemplates(template.pages, id);
+				}
+			};
+			await ensureTemplates(input.pages ?? [], scopeId);
+			return {
+				scope: toPage(await this.#pageRow(tx, scopeId)),
+				created,
+				...parentConflict ? { parentConflict } : {}
 			};
-			await tx.execute({
-				sql: `INSERT INTO "${TABLE_KNOWLEDGE_NODES}" (id,type,name,canonicalName,kind,content,description,scope,scopeKey,version,mergedInto,createdAt,updatedAt) VALUES (?,?,?,?,?,?,?,jsonb(?),?,?,NULL,?,?)`,
-				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.#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.#client, id);
+	async listScopeDeclarations() {
+		return (await this.#query(this.#read, `SELECT declaration, COUNT(*) AS scopes FROM ${T.pages} WHERE isScope = 1 AND declaration IS NOT NULL GROUP BY declaration ORDER BY declaration`)).map((row) => ({
+			declaration: String(row.declaration),
+			scopes: Number(row.scopes)
+		}));
 	}
-	async getNodeByName(input) {
-		return this.#getNodeByName(this.#client, input.name, canonicalizeKnowledgeScope(input.scope));
+	async renameScopeDeclaration(input) {
+		return this.#transaction(async (tx) => {
+			const within = prefixRange("declaration", `${input.from}/`);
+			const affected = (await this.#query(tx, `SELECT id, address, declaration FROM ${T.pages} WHERE isScope = 1 AND (declaration = ? OR ${within.sql}) FOR UPDATE`, [input.from, ...within.args])).map((row) => ({
+				id: String(row.id),
+				address: String(row.address),
+				from: String(row.declaration)
+			})).filter((row) => row.from === input.from || row.from.startsWith(`${input.from}/`)).map((row) => ({
+				...row,
+				to: input.to + row.from.slice(input.from.length)
+			}));
+			input.check(affected.map(({ address, from, to }) => ({
+				address,
+				from,
+				to
+			})));
+			for (const row of affected) await tx.execute({
+				sql: `UPDATE ${T.pages} SET declaration = ? WHERE id = ?`,
+				args: [row.to, row.id]
+			});
+			return affected.length;
+		});
 	}
-	async resolveNode(input) {
-		return this.#resolveNode(this.#client, input.name, canonicalizeKnowledgeScope(input.scope));
+	async getScopesByAddress(addresses) {
+		if (addresses.length === 0) return [];
+		return (await this.#query(this.#read, `SELECT * FROM ${T.pages} WHERE isScope = 1 AND address IN ${JV}`, [jsonList(addresses)])).map(toPage);
 	}
-	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 = databaseTimestamp(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.#client.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 listChildScopes(input) {
+		const core = await loadPagesCore();
+		const limit = limitOf(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
+		const cursor = decodeCursor(input.cursor, 2);
+		const args = [input.parentId];
+		let after = "";
+		if (cursor) {
+			after = ` AND (position > ? OR (position = ? AND id > ?))`;
+			args.push(cursor[0], cursor[0], cursor[1]);
+		}
+		args.push(limit + 1);
+		const rows = await this.#query(this.#read, `SELECT * FROM ${T.pages} WHERE isScope = 1 AND parentId <=> ?${after} ORDER BY position, id LIMIT ?`, args);
+		return this.#pageOutput(rows, limit, (row) => [String(row.position), String(row.id)]);
+	}
+	#pageOutput(rows, limit, cursorOf) {
+		const page = rows.slice(0, limit);
+		return {
+			pages: page.map(toPage),
+			...rows.length > limit ? { nextCursor: encodeCursor(cursorOf(page[page.length - 1])) } : {}
+		};
 	}
-	async updateNode(input) {
-		await assertKnowledgeDescriptionWithinBoundCompat(input.description);
+	async getPage(input) {
+		const readable = pageReadable("p", input.read);
+		const rows = await this.#query(this.#read, `SELECT p.* FROM ${T.pages} p WHERE p.id = ? AND ${readable.sql}`, [input.id, ...readable.args]);
+		return rows[0] ? toPage(rows[0]) : null;
+	}
+	async getPages(input) {
+		const ids = [...new Set(input.ids)];
+		if (ids.length === 0) return [];
+		const readable = pageReadable("p", input.read);
+		return (await this.#query(this.#read, `SELECT p.* FROM ${T.pages} p WHERE p.deletedAt IS NULL AND p.id IN ${JV} AND ${readable.sql}`, [jsonList(ids), ...readable.args])).map(toPage);
+	}
+	async getPageByPath(input) {
+		const readable = pageReadable("p", input.read);
+		let parentId = input.scopeId;
+		let row;
+		for (const key of input.path) {
+			row = (await this.#query(this.#read, `SELECT p.* FROM ${T.pages} p WHERE p.parentId = ? AND p.isScope = 0 AND p.${KEY} = ? AND p.deletedAt IS NULL AND ${readable.sql}`, [
+				parentId,
+				key,
+				...readable.args
+			]))[0];
+			if (!row) return null;
+			parentId = String(row.id);
+		}
+		return row ? toPage(row) : null;
+	}
+	async findPagesByName(input) {
+		const core = await loadPagesCore();
+		const readable = pageReadable("p", input.read);
+		const args = [core.canonicalKnowledgeName(input.name), ...readable.args];
+		let scope = "";
+		if (input.scopeId !== void 0) {
+			scope = ` AND p.scopeId = ?`;
+			args.push(input.scopeId);
+		}
+		args.push(limitOf(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT));
+		return (await this.#query(this.#read, `SELECT p.* FROM ${T.pages} p WHERE p.canonicalName = ? AND p.deletedAt IS NULL AND ${readable.sql}${scope} ORDER BY p.createdAt DESC, p.id DESC LIMIT ?`, args)).map(toPage);
+	}
+	async listChildPages(input) {
+		const core = await loadPagesCore();
+		const limit = limitOf(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
+		const cursor = decodeCursor(input.cursor, 2);
+		const readable = pageReadable("p", input.read);
+		const args = [input.parentId, ...readable.args];
+		let after = "";
+		if (cursor) {
+			after = ` AND (p.position > ? OR (p.position = ? AND p.id > ?))`;
+			args.push(cursor[0], cursor[0], cursor[1]);
+		}
+		args.push(limit + 1);
+		const rows = await this.#query(this.#read, `SELECT p.* FROM ${T.pages} p WHERE p.parentId = ? AND p.isScope = 0 AND p.deletedAt IS NULL AND ${readable.sql}${after} ORDER BY p.position, p.id LIMIT ?`, args);
+		return this.#pageOutput(rows, limit, (row) => [String(row.position), String(row.id)]);
+	}
+	async listPages(input) {
+		const core = await loadPagesCore();
+		const limit = limitOf(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
+		const cursor = decodeCursor(input.cursor, 2);
+		const readable = pagesInReadableScopes("p", input.read);
+		const args = [...readable.args];
+		let filters = "";
+		if (input.scopeId !== void 0) {
+			filters += ` AND p.scopeId = ?`;
+			args.push(input.scopeId);
+		}
+		if (input.namePrefix) {
+			const prefix = core.canonicalKnowledgeName(input.namePrefix);
+			filters += ` AND LEFT(p.canonicalName, CHAR_LENGTH(?)) = ?`;
+			args.push(prefix, prefix);
+		}
+		if (cursor) {
+			filters += ` AND (p.name > ? OR (p.name = ? AND p.id > ?))`;
+			args.push(cursor[0], cursor[0], cursor[1]);
+		}
+		args.push(limit + 1);
+		const rows = await this.#query(this.#read, `SELECT p.* ${readable.sql} WHERE p.isScope = 0 AND p.deletedAt IS NULL${filters} ORDER BY p.name, p.id LIMIT ?`, args);
+		return this.#pageOutput(rows, limit, (row) => [String(row.name), String(row.id)]);
+	}
+	async #insertPage(tx, input) {
+		const core = await loadPagesCore();
+		await assertKnowledgePageDescriptionWithinBound(input.description);
+		const parent = await this.#livePage(tx, input.parentId);
+		const isScopeParent = Number(parent.isScope) === 1;
+		const scopeId = isScopeParent ? String(parent.id) : String(parent.scopeId);
+		const depth = isScopeParent ? 1 : Number(parent.depth) + 1;
+		if (depth > core.MAX_KNOWLEDGE_PAGE_DEPTH) throw new core.KnowledgePageDepthError(input.parentId);
+		const id = input.id ?? createKnowledgeUlid();
+		if (await this.#pageRow(tx, id)) throw new KnowledgeConflictError(id);
+		if (input.key !== void 0) {
+			const problem = knowledgePageKeyProblem(input.key);
+			if (problem) throw new Error(problem);
+			if ((await this.#query(tx, `SELECT id FROM ${T.pages} WHERE parentId = ? AND isScope = 0 AND ${KEY} = ? AND deletedAt IS NULL`, [String(parent.id), input.key])).length > 0) throw new core.KnowledgePageKeyConflictError(input.key, String(parent.id));
+		}
+		const position = input.position ?? core.knowledgePositionBetween(await this.#lastPosition(tx, String(parent.id), false));
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		const who = JSON.stringify(input.provenance);
+		await tx.execute({
+			sql: `INSERT INTO ${T.pages} (id, scopeId, isScope, ${KEY}, parentId, position, path, depth, name, canonicalName, description, body, version, createdBy, updatedBy, createdAt, updatedAt) VALUES (?, ?, 0, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, ?, ?, ?)`,
+			args: [
+				id,
+				scopeId,
+				input.key ?? null,
+				String(parent.id),
+				position,
+				`${String(parent.path)}${id}/`,
+				depth,
+				input.name,
+				core.canonicalKnowledgeName(input.name),
+				input.description || null,
+				input.body ?? null,
+				who,
+				who,
+				now,
+				now
+			]
+		});
+		await this.#logActivity(tx, "page-created", {
+			scopeId,
+			pageId: id,
+			provenance: input.provenance
+		}, now);
+		return toPage(await this.#pageRow(tx, id));
+	}
+	async createPage(input) {
+		await assertKnowledgePageDescriptionWithinBound(input.description);
+		return this.#transaction((tx) => this.#insertPage(tx, input));
+	}
+	async updatePage(input) {
+		const core = await loadPagesCore();
+		await assertKnowledgePageDescriptionWithinBound(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=?`,
+			const row = await this.#livePage(tx, input.id);
+			if (Number(row.version) !== input.expectedVersion) throw new KnowledgeConflictError(input.id);
+			const now = (/* @__PURE__ */ new Date()).toISOString();
+			const name = input.name ?? String(row.name);
+			const description = input.description === void 0 ? row.description ?? null : input.description || null;
+			const body = input.body === void 0 ? row.body ?? null : input.body;
+			await tx.execute({
+				sql: `UPDATE ${T.pages} SET name = ?, canonicalName = ?, description = ?, body = ?, version = version + 1, updatedBy = ?, updatedAt = ? WHERE id = ?`,
 				args: [
 					name,
-					canonicalName(name),
-					input.kind ?? existing.kind,
-					content ?? null,
-					description ?? null,
-					JSON.stringify(scope),
-					knowledgeScopeKey(scope),
-					now.toISOString(),
-					input.id,
-					input.version
+					core.canonicalKnowledgeName(name),
+					description,
+					body,
+					JSON.stringify(input.provenance),
+					now,
+					input.id
 				]
-			})).rowsAffected === 0) throw new KnowledgeConflictError(input.id);
-			if (input.content !== void 0 || input.name !== void 0 || input.scope !== void 0) await this.#replaceMentions(tx, "node", input.id, content ?? "", input.resolutionScope ?? scope, scope);
-			await this.#activity(tx, "node-updated", "node", input.id, scope);
-			if (knowledgeScopeKey(existing.scope) !== knowledgeScopeKey(scope)) {
-				await this.#outbox(tx, "node", input.id, "delete", createKnowledgeUlid(), existing.scope);
-				const records = await tx.execute({
-					sql: `SELECT id,scope AS scopeJson,deletedAt FROM "${TABLE_KNOWLEDGE_RECORDS}" WHERE node=?`,
-					args: [input.id]
-				});
-				for (const row of records.rows) {
-					const factScope = parseJson$1(row.scopeJson);
-					await this.#outbox(tx, "record", String(row.id), "delete", createKnowledgeUlid(), factScope);
-					if (row.deletedAt == null) await this.#outbox(tx, "record", String(row.id), "upsert", createKnowledgeUlid(), factScope);
-				}
-			}
-			await this.#outbox(tx, "node", input.id, "upsert", input.version + 1, scope);
-			return {
-				...existing,
-				name,
-				kind: input.kind ?? existing.kind,
-				content,
-				description,
-				scope,
-				version: input.version + 1,
-				updatedAt: now
-			};
+			});
+			await this.#logActivity(tx, "page-updated", {
+				scopeId: String(row.scopeId),
+				pageId: input.id,
+				provenance: input.provenance
+			}, now);
+			return toPage(await this.#pageRow(tx, input.id));
 		});
 	}
-	async mergeNodes(input) {
-		if (input.sourceId === input.targetId) throw new Error("Cannot merge a knowledge node into itself");
+	/**
+	* Rehomes `root` (and its subtree) under `parent`: new path prefix, scope and depth in one go.
+	* Throws when the subtree is too large, too deep, or the root's key clashes with a live child of `parent`.
+	*/
+	async #rehome(tx, root, parent, options) {
+		const core = await loadPagesCore();
+		const isScopeParent = Number(parent.isScope) === 1;
+		const newScopeId = isScopeParent ? String(parent.id) : String(parent.scopeId);
+		const newDepth = isScopeParent ? 1 : Number(parent.depth) + 1;
+		const oldPath = String(root.path);
+		const within = prefixRange("path", oldPath);
+		const live = (await this.#query(tx, `SELECT id, ${KEY}, depth, deletedAt FROM ${T.pages} WHERE ${within.sql}`, within.args)).filter((row) => !row.deletedAt);
+		if (live.length > core.MAX_KNOWLEDGE_MOVE_PAGES) throw new core.KnowledgeMoveTooLargeError(options.countLimitId, live.length);
+		const shift = newDepth - Number(root.depth);
+		if (Math.max(...live.map((row) => Number(row.depth))) + shift > core.MAX_KNOWLEDGE_PAGE_DEPTH) throw new core.KnowledgePageDepthError(String(root.id));
+		if (!root.deletedAt && root.key !== null) {
+			if ((await this.#query(tx, `SELECT id FROM ${T.pages} WHERE parentId = ? AND isScope = 0 AND ${KEY} = ? AND deletedAt IS NULL AND id <> ?`, [
+				String(parent.id),
+				String(root.key),
+				String(root.id)
+			])).length > 0) throw new core.KnowledgePageKeyConflictError(String(root.key), String(parent.id));
+		}
+		const newPath = `${String(parent.path)}${String(root.id)}/`;
+		const position = options.position ?? core.knowledgePositionBetween(await this.#lastPosition(tx, String(parent.id), false));
+		await tx.execute({
+			sql: `UPDATE ${T.pages} SET path = CONCAT(?, SUBSTRING(path, CHAR_LENGTH(?) + 1)), depth = depth + ?, scopeId = ? WHERE ${within.sql}`,
+			args: [
+				newPath,
+				oldPath,
+				shift,
+				newScopeId,
+				...within.args
+			]
+		});
+		await tx.execute({
+			sql: `UPDATE ${T.pages} SET parentId = ?, position = ? WHERE id = ?`,
+			args: [
+				String(parent.id),
+				position,
+				String(root.id)
+			]
+		});
+		return {
+			moved: live.length,
+			scopeId: newScopeId
+		};
+	}
+	movePage(input) {
 		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`,
+			const row = await this.#livePage(tx, input.id);
+			if (Number(row.isScope) === 1) throw new Error(`Cannot move ${input.id}: it is a scope page`);
+			if (Number(row.version) !== input.expectedVersion) throw new KnowledgeConflictError(input.id);
+			const parent = await this.#livePage(tx, input.parentId);
+			const path = String(row.path);
+			if (String(parent.id) === input.id || String(parent.path).startsWith(path)) throw new Error(`Cannot move ${input.id} into its own subtree`);
+			const now = (/* @__PURE__ */ new Date()).toISOString();
+			const { scopeId } = await this.#rehome(tx, row, parent, {
+				position: input.position,
+				countLimitId: input.id
+			});
+			await tx.execute({
+				sql: `UPDATE ${T.pages} SET version = version + 1, updatedBy = ?, updatedAt = ? WHERE id = ?`,
 				args: [
-					target.id,
-					(/* @__PURE__ */ new Date()).toISOString(),
-					source.id,
-					input.sourceVersion
+					JSON.stringify(input.provenance),
+					now,
+					input.id
 				]
-			})).rowsAffected === 0) throw new KnowledgeConflictError(source.id);
+			});
+			await this.#logActivity(tx, "page-moved", {
+				scopeId,
+				pageId: input.id,
+				provenance: input.provenance
+			}, now);
+			return toPage(await this.#pageRow(tx, input.id));
+		});
+	}
+	async mergePages(input) {
+		const core = await loadPagesCore();
+		return this.#transaction(async (tx) => {
+			const source = await this.#livePage(tx, input.sourceId);
+			const target = await this.#livePage(tx, input.targetId);
+			if (Number(source.isScope) === 1 || Number(target.isScope) === 1) throw new Error("Cannot merge a scope page: merging applies to non-scope pages only");
+			if (Number(source.version) !== input.sourceVersion) throw new KnowledgeConflictError(input.sourceId);
+			const sourcePath = String(source.path);
+			if (input.sourceId === input.targetId || String(target.path).startsWith(sourcePath)) throw new Error(`Page ${input.targetId} is inside page ${input.sourceId}; it cannot be the merge target (subtree)`);
+			const within = prefixRange("path", sourcePath);
+			const carried = await this.#query(tx, `SELECT COUNT(*) AS n FROM ${T.pages} WHERE ${within.sql} AND id <> ? AND deletedAt IS NULL`, [...within.args, input.sourceId]);
+			if (Number(carried[0].n) > core.MAX_KNOWLEDGE_MOVE_PAGES) throw new core.KnowledgeMoveTooLargeError(input.sourceId, Number(carried[0].n));
+			const now = (/* @__PURE__ */ new Date()).toISOString();
 			await tx.execute({
-				sql: `UPDATE "${TABLE_KNOWLEDGE_RECORDS}" SET node=? WHERE node=?`,
-				args: [target.id, source.id]
+				sql: `UPDATE ${T.pages} SET deletedAt = ?, deletedBy = ?, mergedInto = ?, scopeId = ?, version = version + 1, updatedBy = ?, updatedAt = ? WHERE id = ?`,
+				args: [
+					now,
+					input.provenance.author,
+					input.targetId,
+					String(target.scopeId),
+					JSON.stringify(input.provenance),
+					now,
+					input.sourceId
+				]
+			});
+			const children = await this.#query(tx, `SELECT * FROM ${T.pages} WHERE parentId = ? AND isScope = 0`, [input.sourceId]);
+			for (const child of children) await this.#rehome(tx, child, target, {
+				position: String(child.position),
+				countLimitId: input.sourceId
 			});
 			await tx.execute({
-				sql: `DELETE source FROM "${TABLE_KNOWLEDGE_MENTIONS}" source JOIN "${TABLE_KNOWLEDGE_MENTIONS}" target ON target.sourceType=source.sourceType AND target.sourceId=source.sourceId WHERE source.recordId=? AND target.recordId=?`,
-				args: [source.id, target.id]
+				sql: `UPDATE ${T.notes} SET pageId = ? WHERE pageId = ?`,
+				args: [input.targetId, input.sourceId]
 			});
 			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`,
+				sql: `UPDATE IGNORE ${T.mentions} SET pageId = ? WHERE pageId = ?`,
+				args: [input.targetId, input.sourceId]
+			});
+			await tx.execute({
+				sql: `DELETE FROM ${T.mentions} WHERE pageId = ?`,
+				args: [input.sourceId]
+			});
+			const pins = await this.#query(tx, `SELECT * FROM ${T.pins} WHERE pageId IN (?, ?)`, [input.sourceId, input.targetId]);
+			const sourcePin = pins.find((pin) => String(pin.pageId) === input.sourceId);
+			if (sourcePin) {
+				const targetPin = pins.find((pin) => String(pin.pageId) === input.targetId);
+				const audience = parseJsonList(sourcePin.audience);
+				if (targetPin) {
+					const merged = [.../* @__PURE__ */ new Set([...parseJsonList(targetPin.audience), ...audience])];
+					await tx.execute({
+						sql: `UPDATE ${T.pins} SET audience = ?, updatedAt = ? WHERE id = ?`,
+						args: [
+							JSON.stringify(merged),
+							now,
+							String(targetPin.id)
+						]
+					});
+					await this.#indexAudience(tx, String(targetPin.id), merged);
+					await this.#indexAudience(tx, String(sourcePin.id), []);
+					await tx.execute({
+						sql: `DELETE FROM ${T.pins} WHERE id = ?`,
+						args: [String(sourcePin.id)]
+					});
+				} else await tx.execute({
+					sql: `UPDATE ${T.pins} SET pageId = ?, updatedAt = ? WHERE id = ?`,
 					args: [
-						source.description,
-						adoptedAt.toISOString(),
-						target.id,
-						target.version
+						input.targetId,
+						now,
+						String(sourcePin.id)
 					]
-				})).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;
+			await this.#logActivity(tx, "page-merged", {
+				scopeId: String(target.scopeId),
+				pageId: input.sourceId,
+				provenance: input.provenance
+			}, now);
+			return toPage(await this.#pageRow(tx, input.targetId));
 		});
 	}
-	async appendKnowledge(input) {
-		await assertKnowledgeRecordTextWithinBoundCompat(input.text);
-		const scope = canonicalizeKnowledgeScope(input.scope);
-		const resolutionScope = canonicalizeKnowledgeScope(input.resolutionScope);
-		const defaultScope = canonicalizeKnowledgeScope(input.defaultScope);
+	async deletePage(input) {
+		const core = await loadPagesCore();
 		return this.#transaction(async (tx) => {
-			const parent = await this.#resolveTerminalNode(tx, nodeReferenceId(input.node));
-			if (!parent) throw new KnowledgeNotFoundError("node", nodeReferenceId(input.node));
-			const record = {
-				id: input.id ?? createKnowledgeUlid(),
-				node: parent.id,
-				text: input.text,
-				scope,
-				sourceThreadId: input.sourceThreadId,
-				capturedAt: /* @__PURE__ */ new Date(),
-				when: input.when ? new Date(input.when) : void 0,
-				metadata: input.metadata
-			};
+			const row = await this.#livePage(tx, input.id);
+			if (Number(row.isScope) === 1) throw new Error(`Cannot delete ${input.id}: it is a scope page`);
+			if (Number(row.version) !== input.expectedVersion) throw new KnowledgeConflictError(input.id);
+			if ((await this.#query(tx, `SELECT 1 FROM ${T.pages} WHERE parentId = ? AND deletedAt IS NULL LIMIT 1`, [input.id])).length > 0) throw new core.KnowledgePageHasChildrenError(input.id);
+			const now = (/* @__PURE__ */ new Date()).toISOString();
 			await tx.execute({
-				sql: `INSERT INTO "${TABLE_KNOWLEDGE_RECORDS}" (id,node,text,scope,scopeKey,sourceThreadId,capturedAt,"when",metadata,deletedAt,deletedBy) VALUES (?,?,?,jsonb(?),?,?,?,?,jsonb(?),NULL,NULL)`,
+				sql: `UPDATE ${T.pages} SET deletedAt = ?, deletedBy = ?, version = version + 1, updatedBy = ?, updatedAt = ? WHERE id = ?`,
 				args: [
-					record.id,
-					record.node,
-					record.text,
-					JSON.stringify(scope),
-					knowledgeScopeKey(scope),
-					record.sourceThreadId,
-					record.capturedAt.toISOString(),
-					record.when?.toISOString() ?? null,
-					record.metadata ? JSON.stringify(record.metadata) : null
+					now,
+					input.deletedBy,
+					JSON.stringify({ author: input.deletedBy }),
+					now,
+					input.id
 				]
 			});
-			await this.#replaceMentions(tx, "record", record.id, record.text, resolutionScope, defaultScope);
-			await this.#activity(tx, "record-created", "record", record.id, scope, record.sourceThreadId);
-			await this.#outbox(tx, "record", record.id, "upsert", record.id, scope);
-			return record;
-		});
-	}
-	async getKnowledge(input) {
-		const result = await this.#client.execute({
-			sql: `SELECT *,scope AS scopeJson FROM "${TABLE_KNOWLEDGE_RECORDS}" WHERE id=?${input.includeDeleted ? "" : " AND deletedAt IS NULL"}`,
-			args: [input.id]
+			await tx.execute({
+				sql: `DELETE FROM ${T.pinAudiences} WHERE pinId IN (SELECT id FROM ${T.pins} WHERE pageId = ?)`,
+				args: [input.id]
+			});
+			await tx.execute({
+				sql: `DELETE FROM ${T.pins} WHERE pageId = ?`,
+				args: [input.id]
+			});
+			await this.#logActivity(tx, "page-deleted", {
+				scopeId: String(row.scopeId),
+				pageId: input.id,
+				provenance: { author: input.deletedBy }
+			}, now);
+			return toPage(await this.#pageRow(tx, input.id));
 		});
-		return result.rows[0] ? parseKnowledge(result.rows[0]) : null;
-	}
-	async listKnowledgeAbout(input) {
-		return this.#queryKnowledge(input, "about");
-	}
-	async listKnowledgeMentioning(input) {
-		return this.#queryKnowledge(input, "mentioning");
 	}
-	async listKnowledgeRelatedTo(input) {
-		return this.#queryKnowledge(input, "related");
-	}
-	async knowledgeBySource(input) {
-		const keys = visibleScopeKeys(canonicalizeKnowledgeScope(input.scope));
-		const args = [input.sourceThreadId, ...keys];
-		if (input.after) args.push(input.after);
-		const limit = input.limit ?? 100;
+	async #hydrateNotes(executor, rows) {
+		if (rows.length === 0) return [];
+		const ids = jsonList(rows.map((row) => String(row.id)));
+		const stamps = await this.#query(executor, `SELECT noteId, scopeId FROM ${T.stamps} WHERE noteId IN ${JV} ORDER BY scopeId`, [ids]);
+		const mentions = await this.#query(executor, `SELECT noteId, pageId FROM ${T.mentions} WHERE noteId IN ${JV} ORDER BY pageId`, [ids]);
+		return rows.map((row) => toNote(row, stamps.filter((stamp) => String(stamp.noteId) === String(row.id)).map((stamp) => String(stamp.scopeId)), mentions.filter((mention) => String(mention.noteId) === String(row.id)).map((mention) => String(mention.pageId))));
+	}
+	async #noteById(executor, id) {
+		const rows = await this.#query(executor, `SELECT * FROM ${T.notes} WHERE id = ?`, [id]);
+		return (await this.#hydrateNotes(executor, rows))[0] ?? null;
+	}
+	async getNote(input) {
+		const readable = noteReadable("n", input.read);
+		const rows = await this.#query(this.#read, `SELECT n.* FROM ${T.notes} n WHERE n.id = ?${input.includeDeleted ? "" : " AND n.deletedAt IS NULL"} AND ${readable.sql}`, [input.id, ...readable.args]);
+		return (await this.#hydrateNotes(this.#read, rows))[0] ?? null;
+	}
+	async listNotes(input) {
+		const core = await loadPagesCore();
+		const limit = limitOf(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
+		const cursor = decodeCursor(input.cursor, 2);
+		const readable = noteReadable("n", input.read);
+		const args = [input.pageId, ...readable.args];
+		let after = "";
+		if (cursor) {
+			after = ` AND (n.createdAt > ? OR (n.createdAt = ? AND n.id > ?))`;
+			args.push(cursor[0], cursor[0], cursor[1]);
+		}
 		args.push(limit + 1);
-		const records = (await this.#client.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);
+		const rows = await this.#query(this.#read, `SELECT n.* FROM ${T.notes} n WHERE n.pageId = ?${input.includeDeleted ? "" : " AND n.deletedAt IS NULL"} AND ${readable.sql}${after} ORDER BY n.createdAt, n.id LIMIT ?`, args);
+		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 === 0) return counts;
+		const readable = noteReadable("n", input.read);
+		const rows = await this.#query(this.#read, `SELECT n.pageId AS pageId, COUNT(*) AS total FROM ${T.notes} n WHERE n.pageId IN ${JV} AND n.deletedAt IS NULL AND ${readable.sql} GROUP BY n.pageId`, [jsonList(ids), ...readable.args]);
+		for (const row of rows) counts[String(row.pageId)] = Number(row.total);
+		return counts;
+	}
+	async listNotesMentioning(input) {
+		const core = await loadPagesCore();
+		const limit = limitOf(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
+		const cursor = decodeCursor(input.cursor, 2);
+		const readable = noteReadable("n", input.read);
+		const args = [
+			input.pageId,
+			input.pageId,
+			...readable.args
+		];
+		let after = "";
+		if (cursor) {
+			after = ` AND (n.createdAt < ? OR (n.createdAt = ? AND n.id < ?))`;
+			args.push(cursor[0], cursor[0], cursor[1]);
+		}
+		args.push(limit + 1);
+		const rows = await this.#query(this.#read, `SELECT n.* FROM ${T.notes} n WHERE n.pageId <> ? AND n.deletedAt IS NULL AND EXISTS (SELECT 1 FROM ${T.mentions} m WHERE m.noteId = n.id AND m.pageId = ?) AND ${readable.sql}${after} ORDER BY n.createdAt DESC, n.id DESC LIMIT ?`, args);
+		return this.#noteOutput(rows, limit);
+	}
+	async #noteOutput(rows, limit) {
+		const page = rows.slice(0, limit);
 		return {
-			records: records.slice(0, limit),
-			nextCursor: records.length > limit ? records[limit - 1]?.id : void 0
+			notes: await this.#hydrateNotes(this.#read, page),
+			...rows.length > limit ? { nextCursor: encodeCursor([String(page[page.length - 1].createdAt), String(page[page.length - 1].id)]) } : {}
 		};
 	}
-	async removeKnowledge(input) {
+	async #assertScopes(tx, ids) {
+		if (ids.length === 0) throw new Error("A note needs at least one stamp scope");
+		const found = await this.#query(tx, `SELECT id FROM ${T.pages} WHERE isScope = 1 AND id IN ${JV}`, [jsonList(ids)]);
+		const known = new Set(found.map((row) => String(row.id)));
+		const missing = ids.find((id) => !known.has(id));
+		if (missing) throw new Error(`Note stamp ${missing} is not a scope page`);
+	}
+	async addNote(input) {
+		await assertKnowledgeNoteTextWithinBound(input.text);
 		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();
+			const page = await this.#livePage(tx, input.pageId);
+			const stamps = [...new Set(input.stampScopeIds)];
+			await this.#assertScopes(tx, stamps);
+			const mentions = [...new Set(input.mentions)];
+			for (const mention of mentions) await this.#livePage(tx, mention);
+			const id = input.id ?? createKnowledgeUlid();
+			if ((await this.#query(tx, `SELECT 1 FROM ${T.notes} WHERE id = ?`, [id])).length > 0) throw new KnowledgeConflictError(id);
+			const now = (/* @__PURE__ */ new Date()).toISOString();
 			await tx.execute({
-				sql: `UPDATE "${TABLE_KNOWLEDGE_RECORDS}" SET deletedAt=?,deletedBy=? WHERE id=? AND deletedAt IS NULL`,
+				sql: `INSERT INTO ${T.notes} (id, pageId, text, ${WHEN}, provenance, version, createdAt, updatedAt) VALUES (?, ?, ?, ?, ?, 1, ?, ?)`,
 				args: [
-					deletedAt.toISOString(),
-					input.deletedBy,
-					input.id
+					id,
+					input.pageId,
+					input.text,
+					input.when ? input.when.toISOString() : null,
+					JSON.stringify(input.provenance),
+					now,
+					now
 				]
 			});
-			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
-			};
+			for (const stamp of stamps) await tx.execute({
+				sql: `INSERT INTO ${T.stamps} (noteId, scopeId) VALUES (?, ?)`,
+				args: [id, stamp]
+			});
+			for (const mention of mentions) await tx.execute({
+				sql: `INSERT INTO ${T.mentions} (noteId, pageId) VALUES (?, ?)`,
+				args: [id, mention]
+			});
+			await this.#logActivity(tx, "note-added", {
+				scopeId: String(page.scopeId),
+				pageId: input.pageId,
+				noteId: id,
+				provenance: input.provenance
+			}, now);
+			return await this.#noteById(tx, id);
 		});
 	}
-	async restoreKnowledge(input) {
+	async #noteWithPage(tx, id) {
+		const note = (await this.#query(tx, `SELECT * FROM ${T.notes} WHERE id = ?`, [id]))[0];
+		if (!note) throw new KnowledgeNotFoundError("note", id);
+		const page = await this.#pageRow(tx, String(note.pageId));
+		if (!page) throw new KnowledgeNotFoundError("page", String(note.pageId));
+		return {
+			note,
+			page
+		};
+	}
+	restampNote(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 { note, page } = await this.#noteWithPage(tx, input.id);
+			if (note.deletedAt) throw new KnowledgeNotFoundError("note", input.id);
+			if (Number(note.version) !== input.expectedVersion) throw new KnowledgeConflictError(input.id);
+			const stamps = [...new Set(input.stampScopeIds)];
+			await this.#assertScopes(tx, stamps);
+			const now = (/* @__PURE__ */ new Date()).toISOString();
 			await tx.execute({
-				sql: `UPDATE "${TABLE_KNOWLEDGE_RECORDS}" SET deletedAt=NULL,deletedBy=NULL WHERE id=?`,
+				sql: `DELETE FROM ${T.stamps} WHERE noteId = ?`,
 				args: [input.id]
 			});
-			await this.#activity(tx, "record-restored", "record", input.id, record.scope, record.sourceThreadId);
-			await this.#outbox(tx, "record", input.id, "upsert", createKnowledgeUlid(), record.scope);
-			return {
-				...record,
-				deletedAt: void 0,
-				deletedBy: void 0
-			};
+			for (const stamp of stamps) await tx.execute({
+				sql: `INSERT INTO ${T.stamps} (noteId, scopeId) VALUES (?, ?)`,
+				args: [input.id, stamp]
+			});
+			await tx.execute({
+				sql: `UPDATE ${T.notes} SET version = version + 1, updatedAt = ? WHERE id = ?`,
+				args: [now, input.id]
+			});
+			await this.#logActivity(tx, "note-restamped", {
+				scopeId: String(page.scopeId),
+				pageId: String(page.id),
+				noteId: input.id,
+				provenance: input.provenance
+			}, now);
+			return await this.#noteById(tx, input.id);
 		});
 	}
-	async rescopeKnowledge(input) {
-		const scope = canonicalizeKnowledgeScope(input.scope);
+	removeNote(input) {
 		return this.#transaction(async (tx) => {
-			const record = await this.#getKnowledge(tx, input.id, true);
-			if (!record) throw new KnowledgeNotFoundError("record", input.id);
+			const { note, page } = await this.#noteWithPage(tx, input.id);
+			if (note.deletedAt) throw new KnowledgeNotFoundError("note", input.id);
+			const now = (/* @__PURE__ */ new Date()).toISOString();
 			await tx.execute({
-				sql: `UPDATE "${TABLE_KNOWLEDGE_RECORDS}" SET scope=jsonb(?),scopeKey=? WHERE id=?`,
+				sql: `UPDATE ${T.notes} SET deletedAt = ?, deletedBy = ?, version = version + 1, updatedAt = ? WHERE id = ?`,
 				args: [
-					JSON.stringify(scope),
-					knowledgeScopeKey(scope),
+					now,
+					input.deletedBy,
+					now,
 					input.id
 				]
 			});
-			await this.#activity(tx, "record-rescoped", "record", input.id, scope, record.sourceThreadId);
-			if (knowledgeScopeKey(record.scope) !== knowledgeScopeKey(scope)) await this.#outbox(tx, "record", input.id, "delete", createKnowledgeUlid(), record.scope);
-			if (!record.deletedAt) await this.#outbox(tx, "record", input.id, "upsert", createKnowledgeUlid(), scope);
-			return {
-				...record,
-				scope
-			};
+			await this.#logActivity(tx, "note-removed", {
+				scopeId: String(page.scopeId),
+				pageId: String(page.id),
+				noteId: input.id,
+				provenance: input.provenance
+			}, now);
+			return await this.#noteById(tx, input.id);
 		});
 	}
-	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.#client.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.#client.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;
-	}
-	/**
-	* @deprecated Curation cursors were removed. Observation-time curate is the only Knowledge writer and needs no
-	* cursor. Always throws.
-	*/
-	async getCurationCursor(_input) {
-		throw new Error(KNOWLEDGE_CURATION_CURSOR_REMOVED_MESSAGE);
-	}
-	/**
-	* @deprecated Curation cursors were removed. Observation-time curate is the only Knowledge writer and needs no
-	* cursor. Always throws.
-	*/
-	async advanceCurationCursor(_input) {
-		throw new Error(KNOWLEDGE_CURATION_CURSOR_REMOVED_MESSAGE);
+	restoreNote(input) {
+		return this.#transaction(async (tx) => {
+			const { note, page } = await this.#noteWithPage(tx, input.id);
+			if (!note.deletedAt) throw new KnowledgeNotFoundError("note", input.id);
+			const now = (/* @__PURE__ */ new Date()).toISOString();
+			await tx.execute({
+				sql: `UPDATE ${T.notes} SET deletedAt = NULL, deletedBy = NULL, version = version + 1, updatedAt = ? WHERE id = ?`,
+				args: [now, input.id]
+			});
+			await this.#logActivity(tx, "note-restored", {
+				scopeId: String(page.scopeId),
+				pageId: String(page.id),
+				noteId: input.id,
+				provenance: input.provenance
+			}, now);
+			return await this.#noteById(tx, input.id);
+		});
 	}
-	async listActivity(input) {
-		const keys = visibleScopeKeys(canonicalizeKnowledgeScope(input.scope));
-		return (await this.#client.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(row.createdAt)
+	async searchPages(input) {
+		const words = knowledgeSearchWords(input.query);
+		if (!words.length) return [];
+		const phrase = input.query.trim().toLowerCase().replace(/\s+/g, " ");
+		const limit = Math.max(1, input.limit ?? 20);
+		const likes = words.map((word) => `%${escapeLike(word)}%`);
+		const readable = pagesInReadableScopes("p", input.read);
+		const scopeFilter = input.scopeIds ? ` AND p.scopeId IN ${JV}` : "";
+		const scopeArgs = input.scopeIds ? [jsonList(input.scopeIds)] : [];
+		const pageMatch = words.map(() => `(LOWER(p.name) LIKE ? ESCAPE '=' OR LOWER(COALESCE(p.description, '')) LIKE ? ESCAPE '=' OR LOWER(COALESCE(p.body, '')) LIKE ? ESCAPE '=')`).join(" AND ");
+		const nameMatch = words.map(() => `LOWER(p.name) LIKE ? ESCAPE '='`).join(" AND ");
+		const hits = (await this.#query(this.#read, `SELECT p.* ${readable.sql} WHERE p.deletedAt IS NULL AND p.isScope = 0${scopeFilter} AND ${pageMatch} ORDER BY CASE WHEN LOCATE(?, p.canonicalName) > 0 THEN 0 WHEN ${nameMatch} THEN 1 ELSE 2 END, p.updatedAt DESC, p.id ASC LIMIT ?`, [
+			...readable.args,
+			...scopeArgs,
+			...likes.flatMap((like) => [
+				like,
+				like,
+				like
+			]),
+			phrase,
+			...likes,
+			limit
+		])).map((row) => ({
+			type: "page",
+			page: toPage(row)
 		}));
+		if (hits.length >= limit) return hits;
+		const noteVisible = noteReadable("n", input.read);
+		const noteMatch = words.map(() => `LOWER(n.text) LIKE ? ESCAPE '='`).join(" AND ");
+		const noteRows = await this.#query(this.#read, `SELECT n.* FROM ${T.notes} n JOIN ${T.pages} p ON p.id = n.pageId WHERE n.deletedAt IS NULL AND p.deletedAt IS NULL${scopeFilter} AND ${noteMatch} AND ${noteVisible.sql} ORDER BY n.updatedAt DESC, n.id DESC LIMIT ?`, [
+			...scopeArgs,
+			...likes,
+			...noteVisible.args,
+			limit - hits.length
+		]);
+		const notes = await this.#hydrateNotes(this.#read, noteRows);
+		for (const note of notes) {
+			const page = await this.#pageRow(this.#read, note.pageId);
+			if (page) hits.push({
+				type: "note",
+				note,
+				page: toPage(page)
+			});
+		}
+		return hits;
+	}
+	async listPageActivity(input) {
+		const core = await loadPagesCore();
+		const limit = limitOf(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
+		const cursor = decodeCursor(input.cursor, 1);
+		const readable = pageReadable("p", input.read);
+		const noteVisible = noteReadable("n", input.read);
+		const args = [...readable.args];
+		let filters = "";
+		if (input.scopeId !== void 0) {
+			filters += ` AND p.scopeId = ?`;
+			args.push(input.scopeId);
+		}
+		if (input.pageId !== void 0) {
+			filters += ` AND e.pageId = ?`;
+			args.push(input.pageId);
+		}
+		if (cursor) {
+			filters += ` AND e.id < ?`;
+			args.push(cursor[0]);
+		}
+		args.push(...noteVisible.args, limit + 1);
+		const rows = await this.#query(this.#read, `SELECT e.* FROM ${T.activity} e JOIN ${T.pages} p ON p.id = e.pageId WHERE ${readable.sql}${filters} AND (e.noteId IS NULL OR EXISTS (SELECT 1 FROM ${T.notes} n WHERE n.id = e.noteId AND ${noteVisible.sql})) ORDER BY e.id DESC LIMIT ?`, args);
+		const page = rows.slice(0, limit);
+		return {
+			events: page.map((row) => ({
+				id: String(row.id),
+				action: String(row.action),
+				scopeId: String(row.scopeId),
+				pageId: String(row.pageId),
+				...row.noteId ? { noteId: String(row.noteId) } : {},
+				provenance: provenance(row.provenance),
+				createdAt: new Date(String(row.createdAt))
+			})),
+			...rows.length > limit ? { nextCursor: encodeCursor([String(page[page.length - 1].id)]) } : {}
+		};
 	}
-	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.#client.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);
+	/** Rewrites the audience index rows of one pin to match `audience`. */
+	async #indexAudience(tx, pinId, audience) {
+		await tx.execute({
+			sql: `DELETE FROM ${T.pinAudiences} WHERE pinId = ?`,
+			args: [pinId]
+		});
+		for (const entry of audience) await tx.execute({
+			sql: `INSERT IGNORE INTO ${T.pinAudiences} (audience, pinId) VALUES (?, ?)`,
+			args: [entry, pinId]
+		});
 	}
-	async claimSemanticOutbox(input) {
-		const now = input.now ?? /* @__PURE__ */ new Date();
-		const stale = new Date(now.getTime() - (input.claimTimeoutMs ?? 6e4));
+	addPinAudience(input) {
 		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);
+			const page = await this.#livePage(tx, input.pageId);
+			const now = (/* @__PURE__ */ new Date()).toISOString();
+			const existing = (await this.#query(tx, `SELECT * FROM ${T.pins} WHERE pageId = ?`, [input.pageId]))[0];
+			if (!existing) {
+				const id = createKnowledgeUlid();
+				await tx.execute({
+					sql: `INSERT INTO ${T.pins} (id, pageId, audience, createdBy, createdAt, updatedAt) VALUES (?, ?, ?, ?, ?, ?)`,
+					args: [
+						id,
+						input.pageId,
+						JSON.stringify([...new Set(input.audience)]),
+						input.createdBy,
+						now,
+						now
+					]
+				});
+				await this.#indexAudience(tx, id, [...new Set(input.audience)]);
+				await this.#logActivity(tx, "pin-added", {
+					scopeId: String(page.scopeId),
+					pageId: input.pageId,
+					provenance: { author: input.createdBy }
+				}, now);
+				return toPin((await this.#query(tx, `SELECT * FROM ${T.pins} WHERE id = ?`, [id]))[0]);
+			}
+			const current = parseJsonList(existing.audience);
+			const merged = [.../* @__PURE__ */ new Set([...current, ...input.audience])];
+			if (merged.length !== current.length) {
+				await tx.execute({
+					sql: `UPDATE ${T.pins} SET audience = ?, updatedAt = ? WHERE id = ?`,
+					args: [
+						JSON.stringify(merged),
+						now,
+						String(existing.id)
+					]
+				});
+				await this.#indexAudience(tx, String(existing.id), merged);
+				await this.#logActivity(tx, "pin-added", {
+					scopeId: String(page.scopeId),
+					pageId: input.pageId,
+					provenance: { author: input.createdBy }
+				}, now);
+			}
+			return toPin((await this.#query(tx, `SELECT * FROM ${T.pins} WHERE id = ?`, [String(existing.id)]))[0]);
 		});
 	}
-	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=?`,
+	removePinAudience(input) {
+		return this.#transaction(async (tx) => {
+			const existing = (await this.#query(tx, `SELECT * FROM ${T.pins} WHERE pageId = ?`, [input.pageId]))[0];
+			if (!existing) return null;
+			const current = parseJsonList(existing.audience);
+			const remove = new Set(input.audience);
+			const remaining = current.filter((entry) => !remove.has(entry));
+			if (remaining.length === current.length) return toPin(existing);
+			const page = await this.#pageRow(tx, input.pageId);
+			const now = (/* @__PURE__ */ new Date()).toISOString();
+			if (page) await this.#logActivity(tx, "pin-removed", {
+				scopeId: String(page.scopeId),
+				pageId: input.pageId,
+				provenance: { author: input.removedBy }
+			}, now);
+			if (remaining.length === 0) {
+				await this.#indexAudience(tx, String(existing.id), []);
+				await tx.execute({
+					sql: `DELETE FROM ${T.pins} WHERE id = ?`,
+					args: [String(existing.id)]
+				});
+				return null;
+			}
+			await tx.execute({
+				sql: `UPDATE ${T.pins} SET audience = ?, updatedAt = ? WHERE id = ?`,
 				args: [
+					JSON.stringify(remaining),
 					now,
-					id,
-					input.workerId
+					String(existing.id)
 				]
 			});
+			await this.#indexAudience(tx, String(existing.id), remaining);
+			return toPin((await this.#query(tx, `SELECT * FROM ${T.pins} WHERE id = ?`, [String(existing.id)]))[0]);
 		});
 	}
-	async releaseSemanticOutbox(input) {
-		if (!input.ids.length) return;
-		await this.#transaction(async (tx) => {
-			for (const id of input.ids) await tx.execute({
-				sql: `UPDATE "${TABLE_KNOWLEDGE_SEMANTIC_OUTBOX}" SET status='pending',availableAt=?,claimedAt=NULL,claimedBy=NULL WHERE id=? AND status='processing' AND claimedBy=?`,
-				args: [
-					(input.retryAt ?? /* @__PURE__ */ new Date()).toISOString(),
-					id,
-					input.workerId
-				]
-			});
+	async listPins(input) {
+		const core = await loadPagesCore();
+		const limit = limitOf(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
+		const cursor = decodeCursor(input.cursor, 2);
+		const readable = pageReadable("p", input.read);
+		const args = [...readable.args];
+		let filters = "";
+		if (input.audience !== "all") {
+			filters += ` AND pin.id IN (SELECT pa.pinId FROM (SELECT jv.v FROM JSON_TABLE(?, '$[*]' COLUMNS (v VARCHAR(512) ${BIN} PATH '$')) jv) aud STRAIGHT_JOIN ${T.pinAudiences} pa ON pa.audience = aud.v)`;
+			args.push(jsonList(input.audience));
+		}
+		if (input.pageIds) {
+			filters += ` AND pin.pageId IN ${JV}`;
+			args.push(jsonList(input.pageIds));
+		}
+		if (input.excludePageIds?.length) {
+			filters += ` AND pin.pageId NOT IN ${JV}`;
+			args.push(jsonList(input.excludePageIds));
+		}
+		if (input.withBody) filters += ` AND REGEXP_LIKE(p.body, '[^[:space:]]')`;
+		const from = `FROM ${T.pins} pin JOIN ${T.pages} p ON p.id = pin.pageId WHERE p.deletedAt IS NULL AND ${readable.sql}${filters}`;
+		let total;
+		if (input.count) total = Number((await this.#query(this.#read, `SELECT COUNT(*) AS n ${from}`, args))[0].n);
+		const pageArgs = [...args];
+		let cursorFilter = "";
+		if (cursor) {
+			cursorFilter = ` AND (pin.createdAt < ? OR (pin.createdAt = ? AND pin.id < ?))`;
+			pageArgs.push(cursor[0], cursor[0], cursor[1]);
+		}
+		pageArgs.push(limit + 1);
+		const rows = await this.#query(this.#read, `SELECT pin.*, p.name AS pageName ${from}${cursorFilter} ORDER BY pin.createdAt DESC, pin.id DESC LIMIT ?`, pageArgs);
+		const page = rows.slice(0, limit);
+		return {
+			pins: page.map(toListedPin),
+			...rows.length > limit ? { nextCursor: encodeCursor([String(page[page.length - 1].createdAt), String(page[page.length - 1].id)]) } : {},
+			...total === void 0 ? {} : { total }
+		};
+	}
+};
+/** mysql2 returns JSON columns already parsed; accept the raw string form too. */
+function parseJsonList(value) {
+	return typeof value === "string" ? JSON.parse(value) : value;
+}
+// src/storage/domains/knowledge/index.ts
+var KnowledgeMySQL = class extends KnowledgeStorage {
+	static getExportDDL() {
+		return KNOWLEDGE_PAGE_DDL.map((statement) => `${statement};`);
+	}
+	#pool;
+	#pages;
+	constructor({ pool }) {
+		super();
+		this.#pool = pool;
+		const rawExecutor = (client) => ({ async execute(statement) {
+			const [result] = await client.query(statement.sql, statement.args ?? []);
+			return { rows: Array.isArray(result) ? result : [] };
+		} });
+		this.#pages = new MySQLKnowledgePages({
+			read: rawExecutor(pool),
+			transaction: async (operation) => {
+				const connection = await pool.getConnection();
+				try {
+					await connection.beginTransaction();
+					const result = await operation(rawExecutor(connection));
+					await connection.commit();
+					return result;
+				} catch (error) {
+					await connection.rollback();
+					throw error;
+				} finally {
+					connection.release();
+				}
+			}
 		});
 	}
-	async #transaction(operation) {
+	getCapabilities() {
+		return {
+			contractVersion: 4,
+			schemaVersion: 4,
+			supportsSchemaInspection: true,
+			supportsExplicitReset: true
+		};
+	}
+	async #inspectPages(client = this.#pool) {
+		return inspectKnowledgePagesSchema(await this.#pagesSnapshot(client));
+	}
+	async #pagesSnapshot(client) {
+		const exec = async (sql) => {
+			const [rows] = await client.query(sql);
+			return rows;
+		};
+		const tableNames = (await exec("SELECT table_name AS name FROM information_schema.tables WHERE table_schema = DATABASE() AND table_name LIKE 'mastra\\_knowledge\\_%'")).map((row) => String(row.name));
+		let schemaVersion;
+		if (tableNames.includes("mastra_knowledge_access_state")) {
+			const state = await exec(`SELECT schemaVersion FROM \`${TABLE_KNOWLEDGE_PAGES_STATE}\` WHERE id = 'knowledge'`);
+			if (state[0]) schemaVersion = Number(state[0].schemaVersion);
+		}
+		return {
+			tableNames,
+			schemaVersion
+		};
+	}
+	async inspectSchema() {
+		return this.#inspectPages();
+	}
+	/** Runs the earlier-alpha upgrades under a named lock so processes starting together don't race their ALTERs. */
+	async #upgrade() {
 		const connection = await this.#pool.getConnection();
 		try {
-			await connection.beginTransaction();
-			const result = await operation(createExecutor(connection));
-			await connection.commit();
-			return result;
-		} catch (error) {
-			await connection.rollback();
-			throw error;
+			await connection.query("SELECT GET_LOCK('mastra_knowledge_upgrade', 60)");
+			for (const upgrade of KNOWLEDGE_PAGE_UPGRADES) {
+				const [rows] = await connection.query(upgrade.needed, upgrade.args);
+				if (rows.length > 0) for (const statement of upgrade.apply) await connection.query(statement);
+			}
 		} finally {
+			await connection.query("SELECT RELEASE_LOCK('mastra_knowledge_upgrade')").catch(() => {});
 			connection.release();
 		}
 	}
-	async #getNode(executor, id) {
-		const result = await executor.execute({
-			sql: `SELECT *,scope AS scopeJson FROM "${TABLE_KNOWLEDGE_NODES}" WHERE id=? AND type='node'`,
-			args: [id]
-		});
-		return result.rows[0] ? parseNode(result.rows[0]) : null;
-	}
-	async #getNodeByName(executor, name, scope) {
-		const result = await executor.execute({
-			sql: `SELECT *,scope AS scopeJson FROM "${TABLE_KNOWLEDGE_NODES}" WHERE type='node' AND scopeKey=? AND canonicalName=?`,
-			args: [knowledgeScopeKey(scope), canonicalName(name)]
-		});
-		return result.rows[0] ? parseNode(result.rows[0]) : null;
-	}
-	async #resolveNode(executor, name, scope) {
-		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;
+	async init() {
+		const connection = await this.#pool.getConnection();
+		try {
+			const [locked] = await connection.query("SELECT GET_LOCK('mastra_knowledge_init', 60) AS ok");
+			if (Number(locked[0]?.ok) !== 1) throw new Error("Timed out waiting for the Knowledge schema lock");
+			for (const table of legacyKnowledgeTablesToDrop(await this.#pagesSnapshot(connection))) await connection.query(`DROP TABLE IF EXISTS \`${table}\``);
+			const inspection = await this.#inspectPages(connection);
+			if (inspection.status === "incompatible-reset-required") throw new KnowledgeSchemaResetRequiredError(inspection);
+			for (const statement of KNOWLEDGE_PAGE_DDL) await connection.query(statement);
+			await connection.query(`INSERT IGNORE INTO \`${TABLE_KNOWLEDGE_PAGES_STATE}\` (id, schemaVersion) VALUES ('knowledge', ?)`, [4]);
+		} finally {
+			await connection.query("SELECT RELEASE_LOCK('mastra_knowledge_init')").catch(() => {});
+			connection.release();
 		}
-		return null;
+		await this.#upgrade();
 	}
-	async #resolveTerminalNode(executor, id) {
-		let node = await this.#getNode(executor, id);
-		const seen = /* @__PURE__ */ new Set();
-		while (node?.mergedInto) {
-			if (seen.has(node.id)) throw new Error(`Knowledge merge cycle detected at ${node.id}`);
-			seen.add(node.id);
-			node = await this.#getNode(executor, node.mergedInto);
-		}
-		return node;
+	async dangerouslyReset() {
+		for (const table of [...KNOWLEDGE_RESETTABLE_TABLE_NAMES, "mastra_knowledge_pin_audiences"]) await this.#pool.query(`DROP TABLE IF EXISTS \`${table}\``);
+		await this.init();
 	}
-	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;
+	materializeScope(input) {
+		return this.#pages.materializeScope(input);
 	}
-	async #queryKnowledge(input, relationship) {
-		const scope = canonicalizeKnowledgeScope(input.scope);
-		const node = await this.#resolveTerminalNode(this.#client, 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.#client.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
-		};
+	listScopeDeclarations() {
+		return this.#pages.listScopeDeclarations();
 	}
-	async #replaceMentions(tx, sourceType, sourceId, text, resolutionScope, defaultScope) {
-		await tx.execute({
-			sql: `DELETE FROM "${TABLE_KNOWLEDGE_MENTIONS}" WHERE sourceType=? AND sourceId=?`,
-			args: [sourceType, sourceId]
-		});
-		for (const name of parseKnowledgeWikilinks(text)) {
-			let node = await this.#resolveNode(tx, name, resolutionScope);
-			if (!node) {
-				node = await this.#getNodeByName(tx, name, defaultScope);
-				if (node) node = await this.#resolveTerminalNode(tx, node.id);
-				if (!node) {
-					const now = /* @__PURE__ */ new Date();
-					node = {
-						id: crypto.randomUUID(),
-						type: "node",
-						name,
-						kind: "node",
-						scope: defaultScope,
-						version: 1,
-						createdAt: now,
-						updatedAt: now
-					};
-					await tx.execute({
-						sql: `INSERT INTO "${TABLE_KNOWLEDGE_NODES}" (id,type,name,canonicalName,kind,content,scope,scopeKey,version,mergedInto,createdAt,updatedAt) VALUES (?,?,?,?,?,NULL,jsonb(?),?,?,NULL,?,?)`,
-						args: [
-							node.id,
-							"node",
-							node.name,
-							canonicalName(node.name),
-							node.kind,
-							JSON.stringify(defaultScope),
-							knowledgeScopeKey(defaultScope),
-							1,
-							now.toISOString()
-						]
-					});
-					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 OR IGNORE INTO "${TABLE_KNOWLEDGE_MENTIONS}" (sourceType,sourceId,recordId) VALUES (?,?,?)`,
-				args: [
-					sourceType,
-					sourceId,
-					node.id
-				]
-			});
-		}
+	renameScopeDeclaration(input) {
+		return this.#pages.renameScopeDeclaration(input);
 	}
-	async #activity(executor, action, recordType, recordId, scope, sourceThreadId) {
-		const now = /* @__PURE__ */ new Date();
-		await executor.execute({
-			sql: `INSERT INTO "${TABLE_KNOWLEDGE_ACTIVITY}" (id,action,recordType,recordId,scope,scopeKey,sourceThreadId,createdAt) VALUES (?,?,?,?,jsonb(?),?,?,?)`,
-			args: [
-				createKnowledgeUlid(),
-				action,
-				recordType,
-				recordId,
-				JSON.stringify(scope),
-				knowledgeScopeKey(scope),
-				sourceThreadId ?? null,
-				now.toISOString()
-			]
-		});
+	getScopesByAddress(input) {
+		return this.#pages.getScopesByAddress(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 OR IGNORE 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)`,
-			args: [
-				createKnowledgeUlid(),
-				idempotencyKey,
-				documentId,
-				documentType,
-				operation,
-				JSON.stringify(scope),
-				knowledgeScopeKey(scope),
-				now.toISOString(),
-				now.toISOString()
-			]
-		});
+	listChildScopes(input) {
+		return this.#pages.listChildScopes(input);
+	}
+	getPage(input) {
+		return this.#pages.getPage(input);
+	}
+	getPageByPath(input) {
+		return this.#pages.getPageByPath(input);
+	}
+	findPagesByName(input) {
+		return this.#pages.findPagesByName(input);
+	}
+	listChildPages(input) {
+		return this.#pages.listChildPages(input);
+	}
+	listPages(input) {
+		return this.#pages.listPages(input);
+	}
+	createPage(input) {
+		return this.#pages.createPage(input);
+	}
+	updatePage(input) {
+		return this.#pages.updatePage(input);
+	}
+	movePage(input) {
+		return this.#pages.movePage(input);
+	}
+	mergePages(input) {
+		return this.#pages.mergePages(input);
+	}
+	deletePage(input) {
+		return this.#pages.deletePage(input);
+	}
+	getNote(input) {
+		return this.#pages.getNote(input);
+	}
+	listNotes(input) {
+		return this.#pages.listNotes(input);
+	}
+	countNotes(input) {
+		return this.#pages.countNotes(input);
+	}
+	listNotesMentioning(input) {
+		return this.#pages.listNotesMentioning(input);
+	}
+	addNote(input) {
+		return this.#pages.addNote(input);
+	}
+	restampNote(input) {
+		return this.#pages.restampNote(input);
+	}
+	removeNote(input) {
+		return this.#pages.removeNote(input);
+	}
+	restoreNote(input) {
+		return this.#pages.restoreNote(input);
+	}
+	searchPages(input) {
+		return this.#pages.searchPages(input);
+	}
+	listPageActivity(input) {
+		return this.#pages.listPageActivity(input);
+	}
+	addPinAudience(input) {
+		return this.#pages.addPinAudience(input);
+	}
+	removePinAudience(input) {
+		return this.#pages.removePinAudience(input);
+	}
+	getPages(input) {
+		return this.#pages.getPages(input);
+	}
+	listPins(input) {
+		return this.#pages.listPins(input);
+	}
+	async dangerouslyClearAll() {
+		await this.#pages.clearAll();
 	}
 };
 // src/storage/domains/mcp-clients/index.ts