@mastra/mongodb 1.22.1-alpha.0 → 1.23.0

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-mongodb
 description: Documentation for @mastra/mongodb. Use when working with @mastra/mongodb APIs, configuration, or implementation.
 metadata:
   package: "@mastra/mongodb"
-  version: "1.22.1-alpha.0"
+  version: "1.23.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.22.1-alpha.0",
+  "version": "1.23.0",
   "package": "@mastra/mongodb",
   "exports": {},
   "modules": {}

package/dist/docs/references/reference-storage-retention.md

@@ -95,29 +95,32 @@ Set the `retention` field on the store config.
 
 Each domain specifies its age-prunable tables and the timestamp column that anchors comparison, chosen so `maxAge` matches the meaning of the data. Append-only logs use creation time, live state uses last activity, and jobs or runs use completion time so in-flight work isn't pruned.
 
-| Domain            | Table key          | Anchor column    | `maxAge` measures                                                |
-| ----------------- | ------------------ | ---------------- | ---------------------------------------------------------------- |
-| `memory`          | `threads`          | `createdAt`      | Thread age                                                       |
-| `memory`          | `messages`         | `createdAt`      | Message age                                                      |
-| `memory`          | `resources`        | `createdAt`      | Resource age                                                     |
-| `threadState`     | `threadState`      | `updatedAt`      | Inactivity: state for still-active threads survives              |
-| `observability`   | `spans`            | `startedAt`      | Span age                                                         |
-| `observability`   | `metrics`          | `timestamp`      | Metric event age (vNext only)                                    |
-| `observability`   | `logs`             | `timestamp`      | Log event age (vNext only)                                       |
-| `observability`   | `scores`           | `timestamp`      | Score event age (vNext only)                                     |
-| `observability`   | `feedback`         | `timestamp`      | Feedback event age (vNext only)                                  |
-| `scores`          | `scorers`          | `createdAt`      | Score record age                                                 |
-| `workflows`       | `workflowSnapshot` | `updatedAt`      | Inactivity, suspended or long-running workflows survive          |
-| `backgroundTasks` | `backgroundTasks`  | `completedAt`    | Time since completion, in-flight tasks (`NULL`) are never pruned |
-| `experiments`     | `experiments`      | `completedAt`    | Time since completion, running experiments are never pruned      |
-| `notifications`   | `notifications`    | `createdAt`      | Notification age                                                 |
-| `harness`         | `sessions`         | `createdAt`      | Session record age                                               |
-| `schedules`       | `triggers`         | `actual_fire_at` | Fire-history age (epoch-ms column)                               |
+| Domain            | Table key          | Anchor column    | `maxAge` measures                                                                                                                |
+| ----------------- | ------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `memory`          | `threads`          | `createdAt`      | Thread age                                                                                                                       |
+| `memory`          | `messages`         | `createdAt`      | Message age                                                                                                                      |
+| `memory`          | `resources`        | `createdAt`      | Resource age                                                                                                                     |
+| `memory`          | `runFences`        | `retiredAt`      | Time since the durable agent execution holding the fence settled. Fences of running executions (`NULL`) are never pruned         |
+| `threadState`     | `threadState`      | `updatedAt`      | Inactivity: state for still-active threads survives                                                                              |
+| `observability`   | `spans`            | `startedAt`      | Span age                                                                                                                         |
+| `observability`   | `metrics`          | `timestamp`      | Metric event age (vNext only)                                                                                                    |
+| `observability`   | `logs`             | `timestamp`      | Log event age (vNext only)                                                                                                       |
+| `observability`   | `scores`           | `timestamp`      | Score event age (vNext only)                                                                                                     |
+| `observability`   | `feedback`         | `timestamp`      | Feedback event age (vNext only)                                                                                                  |
+| `scores`          | `scorers`          | `createdAt`      | Score record age                                                                                                                 |
+| `workflows`       | `workflowSnapshot` | `updatedAt`      | Inactivity, suspended or long-running workflows survive                                                                          |
+| `workflows`       | `runOwnership`     | `updatedAt`      | Inactivity. A running durable agent execution renews its claim every 10 seconds, so keep `maxAge` well above its 30-second lease |
+| `backgroundTasks` | `backgroundTasks`  | `completedAt`    | Time since completion, in-flight tasks (`NULL`) are never pruned                                                                 |
+| `experiments`     | `experiments`      | `completedAt`    | Time since completion, running experiments are never pruned                                                                      |
+| `notifications`   | `notifications`    | `createdAt`      | Notification age                                                                                                                 |
+| `harness`         | `sessions`         | `createdAt`      | Session record age                                                                                                               |
+| `schedules`       | `triggers`         | `actual_fire_at` | Fire-history age (epoch-ms column)                                                                                               |
 
 > **Note:**
 >
 > - The memory `observational_memory` table has no timestamp anchor, so it can't be age-pruned and isn't a valid retention key.
 > - Experiments prune as whole units: an aged experiment's result rows are deleted together with it (results cascade with their parent), so a run is never left partially deleted. Retention doesn't have a separate `results` key.
+> - `runOwnership` and `runFences` hold the run fencing records of durable agents, one small record per run in each. If the `runOwnership` `maxAge` is too short, a running execution can lose its run, but an execution that lost a run still can't write. A fence is retired only when its execution settles, so the fence of a run that crashed and was never recovered is never pruned.
 > - For `schedules`, the growth table is the fire history (`schedule_triggers`, one row per fire): schedule definitions are config and aren't pruned.
 > - On PostgreSQL, timestamp anchors use the timezone-aware mirror columns (for example `createdAtZ`, `completedAtZ`).
 > - DuckDB observability stores append-only events for all five signals. Its `spans` policy uses the event `timestamp` column rather than `startedAt`.

package/dist/index.cjs

@@ -9,7 +9,7 @@ let _mastra_core_agent = require("@mastra/core/agent");
 let _mastra_core_evals = require("@mastra/core/evals");
 let _mastra_core_storage_domains_skills = require("@mastra/core/storage/domains/skills");
 //#region package.json
-var version = "1.22.1-alpha.0";
+var version = "1.23.0";
 //#endregion
 //#region src/vector/filter.ts
 /**
@@ -4764,13 +4764,26 @@ async function assertKnowledgeDescriptionWithinBoundCompat(description) {
 	}
 	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);
+}
 const cloneScope = (scope) => [...scope];
 const canonicalName = (name) => name.trim().toLocaleLowerCase();
 const nodeReferenceId = (node) => typeof node === "string" ? node : node.id;
 const sessionOptions = (session) => session ? { session } : {};
 function visibleScopeKeys(scope) {
 	const canonical = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(scope);
-	return canonical.map((_, index) => (0, _mastra_core_storage.knowledgeScopeKey)(canonical.slice(0, index + 1)));
+	const subsets = [[]];
+	for (const entry of canonical) subsets.push(...subsets.map((subset) => [...subset, entry]));
+	const keys = /* @__PURE__ */ new Set();
+	for (const subset of subsets.slice(1)) try {
+		keys.add((0, _mastra_core_storage.knowledgeScopeKey)(subset));
+	} catch {}
+	return [...keys];
 }
 function recordCursorFilter(cursor, expected) {
 	const parsed = (0, _mastra_core_storage.parseKnowledgeNodeCursor)(cursor, expected);
@@ -4806,7 +4819,6 @@ function recordFromDocument(row) {
 		sourceThreadId: String(row.sourceThreadId),
 		capturedAt: new Date(row.capturedAt),
 		when: row.when ? new Date(row.when) : void 0,
-		maxScope: row.maxScope ?? void 0,
 		metadata: row.metadata ?? void 0,
 		deletedAt: row.deletedAt ? new Date(row.deletedAt) : void 0,
 		deletedBy: row.deletedBy ?? void 0
@@ -4829,12 +4841,12 @@ function outboxFromDocument(row) {
 		completedAt: row.completedAt ? new Date(row.completedAt) : void 0
 	};
 }
+const KNOWLEDGE_CURATION_CURSOR_REMOVED_MESSAGE = "Knowledge curation cursors were removed: observation-time curate is the only Knowledge writer and needs no cursor.";
 var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.KnowledgeStorage {
 	static MANAGED_COLLECTIONS = [
 		_mastra_core_storage.TABLE_KNOWLEDGE_NODES,
 		_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS,
 		_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS,
-		_mastra_core_storage.TABLE_KNOWLEDGE_CURSORS,
 		_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY,
 		_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX
 	];
@@ -4847,7 +4859,6 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 		const nodes = await this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_NODES);
 		const knowledge = await this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS);
 		const mentions = await this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS);
-		const cursors = await this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_CURSORS);
 		const activity = await this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY);
 		const outbox = await this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX);
 		await Promise.all([
@@ -4860,6 +4871,10 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 				scopeKey: 1,
 				type: 1
 			}),
+			nodes.createIndex({
+				type: 1,
+				canonicalName: 1
+			}),
 			knowledge.createIndex({
 				node: 1,
 				id: -1
@@ -4868,6 +4883,10 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 				sourceThreadId: 1,
 				id: -1
 			}),
+			knowledge.createIndex({
+				scopeKey: 1,
+				id: -1
+			}),
 			mentions.createIndex({
 				sourceType: 1,
 				sourceId: 1,
@@ -4878,11 +4897,11 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 				sourceType: 1,
 				sourceId: 1
 			}),
-			cursors.createIndex({
-				sourceThreadId: 1,
-				agent: 1
-			}, { unique: true }),
 			activity.createIndex({ id: -1 }),
+			activity.createIndex({
+				scopeKey: 1,
+				id: -1
+			}),
 			outbox.createIndex({ idempotencyKey: 1 }, { unique: true }),
 			outbox.createIndex({
 				status: 1,
@@ -4898,6 +4917,11 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 	}
 	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;
+		}
 		const scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope);
 		return this.#connector.withTransaction(async (session) => {
 			const existing = await this.#getNodeByName(input.name, scope, session);
@@ -5090,9 +5114,9 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 		});
 	}
 	async appendKnowledge(input) {
+		await assertKnowledgeRecordTextWithinBoundCompat(input.text);
 		const scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope);
 		const defaultScope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.defaultScope);
-		(0, _mastra_core_storage.assertKnowledgeScopeWithinCeiling)(scope, input.maxScope);
 		return this.#connector.withTransaction(async (session) => {
 			const parent = await this.#resolveTerminalNode(nodeReferenceId(input.node), session);
 			if (!parent) throw new _mastra_core_storage.KnowledgeNotFoundError("node", nodeReferenceId(input.node));
@@ -5107,14 +5131,12 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 				sourceThreadId: input.sourceThreadId,
 				capturedAt: /* @__PURE__ */ new Date(),
 				when: input.when,
-				maxScope: input.maxScope,
 				metadata: input.metadata
 			};
 			await (await this.#knowledge()).insertOne({
 				...record,
 				scopeKey: (0, _mastra_core_storage.knowledgeScopeKey)(scope),
 				when: record.when ?? null,
-				maxScope: record.maxScope ?? null,
 				deletedAt: null,
 				deletedBy: null
 			}, sessionOptions(session));
@@ -5199,7 +5221,6 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 		return this.#connector.withTransaction(async (session) => {
 			const record = await this.#getKnowledge(input.id, true, session);
 			if (!record) throw new _mastra_core_storage.KnowledgeNotFoundError("record", input.id);
-			(0, _mastra_core_storage.assertKnowledgeScopeWithinCeiling)(scope, record.maxScope);
 			await (await this.#knowledge()).updateOne({ id: input.id }, { $set: {
 				scope,
 				scopeKey: (0, _mastra_core_storage.knowledgeScopeKey)(scope)
@@ -5213,17 +5234,6 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 			};
 		});
 	}
-	async raiseKnowledgeCeiling(input) {
-		const record = await this.#getKnowledge(input.id, true);
-		if (!record) throw new _mastra_core_storage.KnowledgeNotFoundError("record", input.id);
-		(0, _mastra_core_storage.assertKnowledgeScopeWithinCeiling)(record.scope, input.maxScope);
-		(0, _mastra_core_storage.assertKnowledgeCeilingRaised)(record.maxScope, input.maxScope);
-		await (await this.#knowledge()).updateOne({ id: input.id }, { $set: { maxScope: input.maxScope ?? null } });
-		return {
-			...record,
-			maxScope: input.maxScope
-		};
-	}
 	async search(input) {
 		const scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope);
 		const query = input.query.trim();
@@ -5263,7 +5273,7 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 				results.push({
 					type: "record",
 					id: record.id,
-					recordId: record.node,
+					recordId: parentVisible ? record.node : record.id,
 					name: parentVisible ? parent.name : "(private node)",
 					text: record.text,
 					scope: cloneScope(record.scope)
@@ -5272,36 +5282,19 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 		}
 		return results.slice(0, limit);
 	}
-	async getCurationCursor(input) {
-		const row = await (await this.#cursors()).findOne(input);
-		return row ? {
-			sourceThreadId: row.sourceThreadId,
-			agent: row.agent,
-			lastKnowledgeId: row.lastKnowledgeId,
-			updatedAt: new Date(row.updatedAt)
-		} : null;
-	}
-	async advanceCurationCursor(input) {
-		const row = await (await this.#cursors()).findOneAndUpdate({
-			sourceThreadId: input.sourceThreadId,
-			agent: input.agent
-		}, {
-			$max: { lastKnowledgeId: input.lastKnowledgeId },
-			$set: { updatedAt: /* @__PURE__ */ new Date() },
-			$setOnInsert: {
-				sourceThreadId: input.sourceThreadId,
-				agent: input.agent
-			}
-		}, {
-			upsert: true,
-			returnDocument: "after"
-		});
-		return {
-			sourceThreadId: row.sourceThreadId,
-			agent: row.agent,
-			lastKnowledgeId: row.lastKnowledgeId,
-			updatedAt: new Date(row.updatedAt)
-		};
+	/**
+	* @deprecated Curation cursors were removed. Observation-time curate is the only Knowledge writer and needs no
+	* cursor. Always throws.
+	*/
+	async getCurationCursor(_input) {
+		throw new Error(KNOWLEDGE_CURATION_CURSOR_REMOVED_MESSAGE);
+	}
+	/**
+	* @deprecated Curation cursors were removed. Observation-time curate is the only Knowledge writer and needs no
+	* cursor. Always throws.
+	*/
+	async advanceCurationCursor(_input) {
+		throw new Error(KNOWLEDGE_CURATION_CURSOR_REMOVED_MESSAGE);
 	}
 	async listActivity(input) {
 		const scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope);
@@ -5422,9 +5415,6 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 	#mentions() {
 		return this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS);
 	}
-	#cursors() {
-		return this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_CURSORS);
-	}
 	#activityCollection() {
 		return this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY);
 	}
@@ -5447,12 +5437,14 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 		return row ? nodeFromDocument(row) : null;
 	}
 	async #resolveNode(name, scope, session) {
-		for (let length = scope.length; length > 0; length--) {
-			const node = await this.#getNodeByName(name, scope.slice(0, length), session);
-			if (node) {
-				const terminal = await this.#resolveTerminalNode(node.id, session);
-				if (terminal && (0, _mastra_core_storage.isKnowledgeScopeVisible)(terminal.scope, scope)) return terminal;
-			}
+		const candidates = (await (await this.#nodes()).find({
+			type: "node",
+			canonicalName: canonicalName(name),
+			$or: [{ scopeKey: { $in: visibleScopeKeys(scope) } }, { mergedInto: { $ne: null } }]
+		}, sessionOptions(session)).toArray()).map(nodeFromDocument).sort((left, right) => right.scope.length - left.scope.length);
+		for (const candidate of candidates) {
+			const terminal = await this.#resolveTerminalNode(candidate.id, session);
+			if (terminal && (0, _mastra_core_storage.isKnowledgeScopeVisible)(terminal.scope, scope)) return terminal;
 		}
 		return null;
 	}