@mastra/convex 1.7.2 → 1.7.3-alpha.0

package/dist/_types/@internal_core/dist/memory/index.d.ts

@@ -0,0 +1,102 @@
+//#region src/memory/index.d.ts
+/**
+ * Shared rules for observational memory lifecycle writes. Every storage adapter applies
+ * these inside its own atomic section (lock, transaction, or conditional update), so the
+ * decisions are identical across adapters.
+ */
+/**
+ * Observational memory columns that lifecycle writes depend on. Storage adapters merge these
+ * into the table schema they get from `@mastra/core`, so the columns exist even when the
+ * installed core predates them.
+ */
+declare const OBSERVATIONAL_MEMORY_LIFECYCLE_COLUMNS: {
+  readonly supersededBy: {
+    readonly type: 'text';
+    readonly nullable: true;
+  };
+};
+/** `schema` plus {@link OBSERVATIONAL_MEMORY_LIFECYCLE_COLUMNS}; `undefined` when `schema` is. */
+declare function withObservationalMemoryLifecycleColumns<T extends object>(schema: T | undefined): (T & typeof OBSERVATIONAL_MEMORY_LIFECYCLE_COLUMNS) | undefined;
+/**
+ * Result of `commitActiveObservations`.
+ */
+interface UpdateActiveObservationsResult {
+  /** Whether the observations were written. */
+  applied: boolean;
+  /**
+   * Why nothing was written: `retired` — the target record was superseded by a newer
+   * generation; `conflict` — `expectedActiveObservations` no longer matches the stored text.
+   */
+  reason?: 'retired' | 'conflict';
+}
+/**
+ * Result of `appendBufferedObservations`.
+ *
+ * The append targets the head generation: when `input.id` was superseded, the chunk is
+ * appended to the current head instead. The append is skipped (`persisted: false`) when the
+ * head already holds a chunk with the same `cycleId`, or when the chunk is wholly covered by
+ * the head's cursor. Chunks carry `lastObservedAt = max message time + 1ms`, so a chunk is
+ * wholly covered iff `head.lastObservedAt >= chunk.lastObservedAt - 1ms`.
+ */
+interface UpdateBufferedObservationsResult {
+  /** Whether the chunk was stored. */
+  persisted: boolean;
+  /** The record the chunk was written to (or would have been written to). */
+  recordId: string;
+}
+/** The fields of an observational memory record that decide head order. */
+interface ObservationalMemoryHeadOrderFields {
+  generationCount: number;
+  createdAt: Date | string;
+  id: string;
+}
+/**
+ * Canonical head order: `generationCount DESC, createdAt ASC, id ASC`.
+ * Returns a negative number when `a` sorts before `b` (i.e. `a` is the better head candidate).
+ */
+declare function compareObservationalMemoryHeadOrder(a: ObservationalMemoryHeadOrderFields, b: ObservationalMemoryHeadOrderFields): number;
+/**
+ * A buffered chunk stores `lastObservedAt = max message time + 1ms`. It is wholly covered
+ * (every message it observed is already at or before the cursor) iff
+ * `cursor >= chunk.lastObservedAt - 1ms`.
+ */
+declare function isBufferedChunkCoveredByCursor(chunkLastObservedAt: Date | string, cursor: Date | string | null | undefined): boolean;
+/** The later of two cursors; `undefined` only when both are absent. */
+declare function maxObservationCursor(a: Date | string | null | undefined, b: Date | string | null | undefined): Date | undefined;
+interface ReflectionTextPlan {
+  /** `equal`: stored text equals the snapshot. `append`: observations were appended after the snapshot. */
+  mode: 'equal' | 'append';
+  observations: string;
+  tokenCount: number;
+}
+/**
+ * Decide the new generation's text when a reflection built from `snapshot` commits against
+ * the stored record.
+ *
+ * - Stored text equals the snapshot: the reflection replaces it.
+ * - Stored text extends the snapshot (activation only appends): the appended tail is kept
+ *   after the reflection, and its tokens are added.
+ * - Anything else (a non-append rewrite): `null` — the reflection must not be applied.
+ */
+declare function planReflectionGenerationText(input: {
+  storedObservations: string;
+  storedObservationTokenCount: number;
+  snapshotObservations: string;
+  snapshotObservationTokenCount: number;
+  reflection: string;
+  tokenCount: number;
+}): ReflectionTextPlan | null;
+/**
+ * Backs `updateActiveObservations` in adapters that implement `commitActiveObservations`.
+ * Callers of `updateActiveObservations` (which resolves `void`) can't see a commit result, so a
+ * write that was not applied throws instead of resolving as if it had committed.
+ */
+declare function assertActiveObservationsApplied(result: UpdateActiveObservationsResult, id: string): void;
+/**
+ * Whether the stored text can still accept a reflection built from `snapshot`
+ * (equal, or only appended to since).
+ */
+declare function isAppendOnlySince(storedObservations: string, snapshotObservations: string): boolean;
+//#endregion
+export { OBSERVATIONAL_MEMORY_LIFECYCLE_COLUMNS, ObservationalMemoryHeadOrderFields, ReflectionTextPlan, UpdateActiveObservationsResult, UpdateBufferedObservationsResult, assertActiveObservationsApplied, compareObservationalMemoryHeadOrder, isAppendOnlySince, isBufferedChunkCoveredByCursor, maxObservationCursor, planReflectionGenerationText, withObservationalMemoryLifecycleColumns };
+//# sourceMappingURL=index.d.ts.map

package/dist/_types/@internal_core/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/dist/docs/SKILL.md

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

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.7.2",
+  "version": "1.7.3-alpha.0",
   "package": "@mastra/convex",
   "exports": {},
   "modules": {}

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_server = require("./server-D_scBUwi.cjs");
+const require_server = require("./server-cdXFJzWz.cjs");
 const require_schema = require("./schema.cjs");
 let _mastra_core_cache = require("@mastra/core/cache");
 let _mastra_core_storage = require("@mastra/core/storage");
@@ -489,15 +489,43 @@ var ConvexDB = class extends _mastra_core_base.MastraBase {
 			...args
 		});
 	}
-	async omUpdateActive(args) {
+	async omInitialize(record) {
+		return this.client.callStorage({
+			op: "omInitialize",
+			tableName: TABLE_OBSERVATIONAL_MEMORY$1,
+			record
+		});
+	}
+	async omCreateReflectionGeneration(args) {
+		return this.client.callStorage({
+			op: "omCreateReflectionGeneration",
+			tableName: TABLE_OBSERVATIONAL_MEMORY$1,
+			...args
+		});
+	}
+	async omSetPendingMessageTokens(args) {
+		await this.client.callStorage({
+			op: "omSetPendingMessageTokens",
+			tableName: TABLE_OBSERVATIONAL_MEMORY$1,
+			...args
+		});
+	}
+	async omSetBufferingObservationFlag(args) {
 		await this.client.callStorage({
+			op: "omSetBufferingObservationFlag",
+			tableName: TABLE_OBSERVATIONAL_MEMORY$1,
+			...args
+		});
+	}
+	async omUpdateActive(args) {
+		return this.client.callStorage({
 			op: "omUpdateActive",
 			tableName: TABLE_OBSERVATIONAL_MEMORY$1,
 			...args
 		});
 	}
 	async omAppendBufferedChunk(args) {
-		await this.client.callStorage({
+		return this.client.callStorage({
 			op: "omAppendBufferedChunk",
 			tableName: TABLE_OBSERVATIONAL_MEMORY$1,
 			...args
@@ -902,6 +930,17 @@ var ChannelsConvex = class extends _mastra_core_storage.ChannelsStorage {
 	}
 };
 //#endregion
+//#region ../../packages/_internal-core/dist/memory/index.js
+/**
+* Backs `updateActiveObservations` in adapters that implement `commitActiveObservations`.
+* Callers of `updateActiveObservations` (which resolves `void`) can't see a commit result, so a
+* write that was not applied throws instead of resolving as if it had committed.
+*/
+function assertActiveObservationsApplied(result, id) {
+	if (result.applied) return;
+	throw new Error(result.reason === "retired" ? `Observational memory record ${id} was superseded by a newer generation; observations were not written` : `Observational memory record ${id} changed since the observations were composed; observations were not written`);
+}
+//#endregion
 //#region src/storage/domains/memory/index.ts
 function parseStoredThread(row) {
 	return {
@@ -977,7 +1016,8 @@ function parseStoredOMRecord(doc) {
 		config: config ?? {},
 		metadata: metadata ?? void 0,
 		observedMessageIds: doc.observedMessageIds || void 0,
-		observedTimezone: doc.observedTimezone || void 0
+		observedTimezone: doc.observedTimezone || void 0,
+		supersededBy: doc.supersededBy ?? null
 	};
 }
 var MemoryConvex = class extends _mastra_core_storage.MemoryStorage {
@@ -1465,9 +1505,9 @@ var MemoryConvex = class extends _mastra_core_storage.MemoryStorage {
 		})).map((doc) => parseStoredOMRecord(doc));
 	}
 	async initializeObservationalMemory(input) {
-		const id = crypto.randomUUID();
 		const now = /* @__PURE__ */ new Date();
 		const lookupKey = this.getOMKey(input.threadId, input.resourceId);
+		const id = crypto.randomUUID();
 		const record = {
 			id,
 			scope: input.scope,
@@ -1489,38 +1529,36 @@ var MemoryConvex = class extends _mastra_core_storage.MemoryStorage {
 			lastBufferedAtTokens: 0,
 			lastBufferedAtTime: null,
 			config: input.config,
-			observedTimezone: input.observedTimezone
+			observedTimezone: input.observedTimezone,
+			supersededBy: null
 		};
-		await this.#db.insert({
-			tableName: TABLE_OBSERVATIONAL_MEMORY$1,
-			record: {
-				id,
-				lookupKey,
-				scope: input.scope,
-				resourceId: input.resourceId,
-				threadId: input.threadId || null,
-				activeObservations: "",
-				activeObservationsPendingUpdate: null,
-				originType: "initial",
-				config: JSON.stringify(input.config ?? {}),
-				generationCount: 0,
-				lastObservedAt: null,
-				lastReflectionAt: null,
-				pendingMessageTokens: 0,
-				totalTokensObserved: 0,
-				observationTokenCount: 0,
-				isObserving: false,
-				isReflecting: false,
-				isBufferingObservation: false,
-				isBufferingReflection: false,
-				lastBufferedAtTokens: 0,
-				lastBufferedAtTime: null,
-				observedTimezone: input.observedTimezone || null,
-				createdAt: now.toISOString(),
-				updatedAt: now.toISOString()
-			}
+		const doc = await this.#db.omInitialize({
+			id,
+			lookupKey,
+			scope: input.scope,
+			resourceId: input.resourceId,
+			threadId: input.threadId || null,
+			activeObservations: "",
+			activeObservationsPendingUpdate: null,
+			originType: "initial",
+			config: JSON.stringify(input.config ?? {}),
+			generationCount: 0,
+			lastObservedAt: null,
+			lastReflectionAt: null,
+			pendingMessageTokens: 0,
+			totalTokensObserved: 0,
+			observationTokenCount: 0,
+			isObserving: false,
+			isReflecting: false,
+			isBufferingObservation: false,
+			isBufferingReflection: false,
+			lastBufferedAtTokens: 0,
+			lastBufferedAtTime: null,
+			observedTimezone: input.observedTimezone || null,
+			createdAt: now.toISOString(),
+			updatedAt: now.toISOString()
 		});
-		return record;
+		return doc ? parseStoredOMRecord(doc) : record;
 	}
 	async insertObservationalMemoryRecord(record) {
 		const lookupKey = this.getOMKey(record.threadId, record.resourceId);
@@ -1556,22 +1594,30 @@ var MemoryConvex = class extends _mastra_core_storage.MemoryStorage {
 				lastBufferedAtTime: record.lastBufferedAtTime ? toISO(record.lastBufferedAtTime) : null,
 				observedTimezone: record.observedTimezone || null,
 				metadata: record.metadata ? JSON.stringify(record.metadata) : null,
+				supersededBy: record.supersededBy ?? null,
 				createdAt: toISO(record.createdAt),
 				updatedAt: toISO(record.updatedAt)
 			}
 		});
 	}
 	async updateActiveObservations(input) {
-		await this.#db.omUpdateActive({
+		assertActiveObservationsApplied(await this.commitActiveObservations(input), input.id);
+	}
+	async commitActiveObservations(input) {
+		return await this.#db.omUpdateActive({
 			id: input.id,
 			observations: input.observations,
 			tokenCount: input.tokenCount,
 			lastObservedAt: toISO(input.lastObservedAt),
 			observedMessageIds: input.observedMessageIds ?? null,
-			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-		});
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			...input.expectedActiveObservations !== void 0 ? { expectedActiveObservations: input.expectedActiveObservations } : {}
+		}) ?? { applied: true };
 	}
 	async updateBufferedObservations(input) {
+		await this.appendBufferedObservations(input);
+	}
+	async appendBufferedObservations(input) {
 		const chunk = {
 			id: `ombuf-${crypto.randomUUID()}`,
 			cycleId: input.chunk.cycleId,
@@ -1587,12 +1633,15 @@ var MemoryConvex = class extends _mastra_core_storage.MemoryStorage {
 			extractedValues: input.chunk.extractedValues,
 			extractionFailures: input.chunk.extractionFailures
 		};
-		await this.#db.omAppendBufferedChunk({
+		return await this.#db.omAppendBufferedChunk({
 			id: input.id,
 			chunk,
 			lastBufferedAtTime: input.lastBufferedAtTime ? toISO(input.lastBufferedAtTime) : void 0,
 			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-		});
+		}) ?? {
+			persisted: true,
+			recordId: input.id
+		};
 	}
 	async swapBufferedToActive(input) {
 		return this.#db.omSwapBuffered({
@@ -1606,65 +1655,33 @@ var MemoryConvex = class extends _mastra_core_storage.MemoryStorage {
 			now: (/* @__PURE__ */ new Date()).toISOString()
 		});
 	}
-	async createReflectionGeneration(input) {
-		const id = crypto.randomUUID();
-		const now = /* @__PURE__ */ new Date();
-		const lookupKey = this.getOMKey(input.currentRecord.threadId, input.currentRecord.resourceId);
-		const record = {
-			id,
-			scope: input.currentRecord.scope,
-			threadId: input.currentRecord.threadId,
-			resourceId: input.currentRecord.resourceId,
-			createdAt: now,
-			updatedAt: now,
-			lastObservedAt: input.currentRecord.lastObservedAt,
-			originType: "reflection",
-			generationCount: input.currentRecord.generationCount + 1,
-			activeObservations: input.reflection,
-			totalTokensObserved: input.currentRecord.totalTokensObserved,
-			observationTokenCount: input.tokenCount,
-			pendingMessageTokens: 0,
-			isReflecting: false,
-			isObserving: false,
-			isBufferingObservation: false,
-			isBufferingReflection: false,
-			lastBufferedAtTokens: 0,
-			lastBufferedAtTime: null,
-			config: input.currentRecord.config,
-			metadata: input.currentRecord.metadata,
-			observedTimezone: input.currentRecord.observedTimezone
+	/** The caller's snapshot as the server's rollover ops expect it. */
+	#serializeCurrentRecord(currentRecord) {
+		return {
+			id: currentRecord.id,
+			lookupKey: this.getOMKey(currentRecord.threadId, currentRecord.resourceId),
+			scope: currentRecord.scope,
+			threadId: currentRecord.threadId || null,
+			resourceId: currentRecord.resourceId,
+			config: JSON.stringify(currentRecord.config ?? {}),
+			metadata: currentRecord.metadata ? JSON.stringify(currentRecord.metadata) : null,
+			observedTimezone: currentRecord.observedTimezone || null,
+			lastObservedAt: currentRecord.lastObservedAt ? toISO(currentRecord.lastObservedAt) : null,
+			totalTokensObserved: currentRecord.totalTokensObserved,
+			generationCount: currentRecord.generationCount,
+			activeObservations: currentRecord.activeObservations ?? "",
+			observationTokenCount: currentRecord.observationTokenCount ?? 0
 		};
-		await this.#db.insert({
-			tableName: TABLE_OBSERVATIONAL_MEMORY$1,
-			record: {
-				id,
-				lookupKey,
-				scope: record.scope,
-				resourceId: record.resourceId,
-				threadId: record.threadId || null,
-				activeObservations: input.reflection,
-				activeObservationsPendingUpdate: null,
-				originType: "reflection",
-				config: JSON.stringify(record.config ?? {}),
-				generationCount: record.generationCount,
-				lastObservedAt: record.lastObservedAt ? toISO(record.lastObservedAt) : null,
-				lastReflectionAt: now.toISOString(),
-				pendingMessageTokens: 0,
-				totalTokensObserved: record.totalTokensObserved,
-				observationTokenCount: record.observationTokenCount,
-				isObserving: false,
-				isReflecting: false,
-				isBufferingObservation: false,
-				isBufferingReflection: false,
-				lastBufferedAtTokens: 0,
-				lastBufferedAtTime: null,
-				observedTimezone: record.observedTimezone || null,
-				metadata: record.metadata ? JSON.stringify(record.metadata) : null,
-				createdAt: now.toISOString(),
-				updatedAt: now.toISOString()
-			}
+	}
+	async createReflectionGeneration(input) {
+		const doc = await this.#db.omCreateReflectionGeneration({
+			currentRecord: this.#serializeCurrentRecord(input.currentRecord),
+			newId: input.newRecordId ?? crypto.randomUUID(),
+			reflection: input.reflection,
+			tokenCount: input.tokenCount,
+			now: (/* @__PURE__ */ new Date()).toISOString()
 		});
-		return record;
+		return doc ? parseStoredOMRecord(doc) : input.currentRecord;
 	}
 	async updateBufferedReflection(input) {
 		await this.#db.omUpdateBufferedReflection({
@@ -1677,26 +1694,13 @@ var MemoryConvex = class extends _mastra_core_storage.MemoryStorage {
 		});
 	}
 	async swapBufferedReflectionToActive(input) {
-		const { currentRecord } = input;
-		const serializedCurrentRecord = {
-			id: currentRecord.id,
-			lookupKey: this.getOMKey(currentRecord.threadId, currentRecord.resourceId),
-			scope: currentRecord.scope,
-			threadId: currentRecord.threadId || null,
-			resourceId: currentRecord.resourceId,
-			config: JSON.stringify(currentRecord.config ?? {}),
-			metadata: currentRecord.metadata ? JSON.stringify(currentRecord.metadata) : null,
-			observedTimezone: currentRecord.observedTimezone || null,
-			lastObservedAt: currentRecord.lastObservedAt ? toISO(currentRecord.lastObservedAt) : null,
-			totalTokensObserved: currentRecord.totalTokensObserved,
-			generationCount: currentRecord.generationCount
-		};
-		return parseStoredOMRecord(await this.#db.omSwapBufferedReflection({
-			currentRecord: serializedCurrentRecord,
-			newId: crypto.randomUUID(),
+		const doc = await this.#db.omSwapBufferedReflection({
+			currentRecord: this.#serializeCurrentRecord(input.currentRecord),
+			newId: input.newRecordId ?? crypto.randomUUID(),
 			tokenCount: input.tokenCount,
 			now: (/* @__PURE__ */ new Date()).toISOString()
-		}));
+		});
+		return doc ? parseStoredOMRecord(doc) : input.currentRecord;
 	}
 	async setReflectingFlag(id, isReflecting) {
 		if (!await this.#db.patch({
@@ -1719,15 +1723,12 @@ var MemoryConvex = class extends _mastra_core_storage.MemoryStorage {
 		})) throw this.omRecordNotFound("SET_OBSERVING_FLAG", id);
 	}
 	async setBufferingObservationFlag(id, isBuffering, lastBufferedAtTokens) {
-		if (!await this.#db.patch({
-			tableName: "mastra_observational_memory",
+		await this.#db.omSetBufferingObservationFlag({
 			id,
-			record: {
-				isBufferingObservation: isBuffering,
-				...lastBufferedAtTokens !== void 0 ? { lastBufferedAtTokens } : {},
-				updatedAt: /* @__PURE__ */ new Date()
-			}
-		})) throw this.omRecordNotFound("SET_BUFFERING_OBSERVATION_FLAG", id);
+			isBuffering,
+			...lastBufferedAtTokens !== void 0 ? { lastBufferedAtTokens } : {},
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
 	}
 	async setBufferingReflectionFlag(id, isBuffering) {
 		if (!await this.#db.patch({
@@ -1750,14 +1751,11 @@ var MemoryConvex = class extends _mastra_core_storage.MemoryStorage {
 				tokenCount
 			}
 		});
-		if (!await this.#db.patch({
-			tableName: "mastra_observational_memory",
+		await this.#db.omSetPendingMessageTokens({
 			id,
-			record: {
-				pendingMessageTokens: tokenCount,
-				updatedAt: /* @__PURE__ */ new Date()
-			}
-		})) throw this.omRecordNotFound("SET_PENDING_MESSAGE_TOKENS", id);
+			tokenCount,
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
 	}
 	async clearObservationalMemory(threadId, resourceId) {
 		const lookupKey = this.getOMKey(threadId, resourceId);