@mastra/libsql 1.16.0-alpha.0 → 1.16.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # @mastra/libsql
 
+## 1.16.0
+
+### Minor Changes
+
+- Added atomic caller-defined dataset IDs for idempotent dataset creation across built-in storage adapters. Supplying `id` to `mastra.datasets.create()` now creates the dataset once and resolves compatible retries to the persisted record; incompatible immutable identity fields throw `DATASET_ID_CONFLICT`. ([#19370](https://github.com/mastra-ai/mastra/pull/19370))
+
+- Added `LibSQLVector.close()` to release the underlying libsql client. For local file databases it checkpoints the WAL and switches back to `journal_mode=DELETE` before closing (mirroring `LibSQLStore.close()`), so the `-wal`/`-shm` sidecar files and OS handles are released promptly. Safe to call more than once. ([#19059](https://github.com/mastra-ai/mastra/pull/19059))
+
+- Added caller-defined dataset item identities for safe retries across all dataset storage adapters. ([#19384](https://github.com/mastra-ai/mastra/pull/19384))
+
+  Dataset items can now include an `externalId` when calling `addItem` or `addItems`:
+
+  ```ts
+  await dataset.addItem({
+    externalId: 'source-item-123',
+    input: { prompt: 'Hello' },
+  });
+  ```
+
+  Retrying with the same identity and payload returns the existing item. Reusing an identity with different content returns a typed conflict, including during concurrent writes. Updates and deletes preserve the identity, Spanner retries transactions without changing the outcome, and MySQL batch writes now preserve every supported dataset item field.
+
+### Patch Changes
+
+- Raised the `@mastra/core` peer dependency floor to `>=1.51.0-0` so the dataset item identity helpers used by the storage adapters are available at runtime. ([#19384](https://github.com/mastra-ai/mastra/pull/19384))
+
+- Updated dependencies [[`bd6d240`](https://github.com/mastra-ai/mastra/commit/bd6d2402db93dddaef0721667e7e8a030e7c6e16), [`0111486`](https://github.com/mastra-ai/mastra/commit/01114867612593eef5cfa2fda6a1194dfedda841), [`96a3749`](https://github.com/mastra-ai/mastra/commit/96a37492235f5b8076b3e3177d83ed5a5e44a640), [`fe1bda0`](https://github.com/mastra-ai/mastra/commit/fe1bda06f6af92a694a51712db747cda1e7185f0), [`25e7c12`](https://github.com/mastra-ai/mastra/commit/25e7c126a770069ae7fb7ecf1d2adb40e017b009), [`1ce5121`](https://github.com/mastra-ai/mastra/commit/1ce512155d122bb21f47d98383e82ffbf84b39e8), [`fb8aea3`](https://github.com/mastra-ai/mastra/commit/fb8aea384291e77311be3a64ee1717320d5c3c73), [`4adc391`](https://github.com/mastra-ai/mastra/commit/4adc3911075249c352bb4832d2471922826344de), [`a5c6337`](https://github.com/mastra-ai/mastra/commit/a5c6337d23c7686c81a32ce62f550f610543a240), [`3cfc47a`](https://github.com/mastra-ai/mastra/commit/3cfc47a6b89940aadd0f46fb01ae9624a73a865d), [`2bb7817`](https://github.com/mastra-ai/mastra/commit/2bb78176112fde628483de2830528f7eee911e56), [`51d9870`](https://github.com/mastra-ai/mastra/commit/51d987032c689c2855374d0f244f5d654da809d1), [`5cab274`](https://github.com/mastra-ai/mastra/commit/5cab2744250e22d12fefa7b32637dce224233cee), [`7fa27d3`](https://github.com/mastra-ai/mastra/commit/7fa27d3b6f5ed68cd34e454a4d3ad9c482a0cfbc), [`8b97958`](https://github.com/mastra-ai/mastra/commit/8b979589f9aa59ba67cac565949475f2ffeb4ac3), [`8410541`](https://github.com/mastra-ai/mastra/commit/84105412c60ecd3bb33a9838146f59c4b588228f), [`a58dcbb`](https://github.com/mastra-ai/mastra/commit/a58dcbb546d7e1d65ebdc1f39e55f0908fcd9391), [`aa38805`](https://github.com/mastra-ai/mastra/commit/aa38805b878b827403be785eb90688d7172f5a40), [`153bd3b`](https://github.com/mastra-ai/mastra/commit/153bd3b396bdfed6b74cf43de12db8fd2d83c04a), [`45a8e65`](https://github.com/mastra-ai/mastra/commit/45a8e65e1556d1362cb3f25187023c36de26661d), [`e955965`](https://github.com/mastra-ai/mastra/commit/e955965dce575a903e37cf054d28ea99aa48785e), [`2d22570`](https://github.com/mastra-ai/mastra/commit/2d22570c7dfdd02123d0ecc529efb05ccba2d9fc), [`07bb863`](https://github.com/mastra-ai/mastra/commit/07bb8631919c6f7cf377dccd45b096e0f17fbed0), [`c8ed116`](https://github.com/mastra-ai/mastra/commit/c8ed11699f62bcac70102ab4ec84d80d20541da6), [`01b338c`](https://github.com/mastra-ai/mastra/commit/01b338c56271f0219606710e3e8b26dee27ac6c2), [`a99eae8`](https://github.com/mastra-ai/mastra/commit/a99eae8908e500c1b2d12f9d277be616b98617a5), [`860ef7e`](https://github.com/mastra-ai/mastra/commit/860ef7e77d92b63469cbe5857aa1e626197e43e9), [`17e818c`](https://github.com/mastra-ai/mastra/commit/17e818c51a958ba90641b1a959dc38faf8c034e9), [`edce8d2`](https://github.com/mastra-ai/mastra/commit/edce8d2769f19e27a05737c627af2d765472a4f8), [`8a586ec`](https://github.com/mastra-ai/mastra/commit/8a586eca9a4914f31dff6140d0d45ac375b00669), [`4451dfe`](https://github.com/mastra-ai/mastra/commit/4451dfe857428e7abcc0261a507a2e186dae6d47), [`8b7361d`](https://github.com/mastra-ai/mastra/commit/8b7361d35de68b80d05d30a74e0c69e7218fd612), [`1d39058`](https://github.com/mastra-ai/mastra/commit/1d39058e548efd691799985d5c8af2737f1c3bd2), [`3927473`](https://github.com/mastra-ai/mastra/commit/392747323ddb10c643d12be7b9ae913159dfaeed), [`dce50dc`](https://github.com/mastra-ai/mastra/commit/dce50dc9a1c1fcd0f427bb5f6250ec74910cb04b), [`fd13f8e`](https://github.com/mastra-ai/mastra/commit/fd13f8e21990f9904c3eedba3a626bb4a929cdb8), [`634caff`](https://github.com/mastra-ai/mastra/commit/634caff29a9200ad058b67d53f96d9e5832fb8a2), [`f703f87`](https://github.com/mastra-ai/mastra/commit/f703f878de072d51fda557f9c50867d8252bef05), [`3e26c87`](https://github.com/mastra-ai/mastra/commit/3e26c87de0c5bc2583b795ce6ca5889b6b161acb), [`33f2b88`](https://github.com/mastra-ai/mastra/commit/33f2b88842c09a567f906fac4cb61cd5277ced59), [`177010f`](https://github.com/mastra-ai/mastra/commit/177010ff096d2e4b28d89803be5b1a4cad2a0d6b), [`0ad646f`](https://github.com/mastra-ai/mastra/commit/0ad646f71a530f2454664299e5e01bfd13fa12e5), [`b486abf`](https://github.com/mastra-ai/mastra/commit/b486abfa2a7528c6f527e4015c819ea9fa54aaad), [`54a51e0`](https://github.com/mastra-ai/mastra/commit/54a51e0a484fe1ebad3fb1f7ef5282a075709eb7), [`c43f3a9`](https://github.com/mastra-ai/mastra/commit/c43f3a9d1efde99b38789364ba4d0ba670f430e3), [`a5008f2`](https://github.com/mastra-ai/mastra/commit/a5008f22ae710ad9402ea9f2547d8c02f74d384b), [`e2d5f37`](https://github.com/mastra-ai/mastra/commit/e2d5f373bd289be534d5f8694d34465010533df6), [`4ce0163`](https://github.com/mastra-ai/mastra/commit/4ce0163dc86e675a86809685c8ce6c49f1aeb87e), [`4378341`](https://github.com/mastra-ai/mastra/commit/43783412df5ea3dd35f5b1f6e4851e79c346fc89)]:
+  - @mastra/core@1.51.0
+
+## 1.16.0-alpha.1
+
+### Minor Changes
+
+- Added atomic caller-defined dataset IDs for idempotent dataset creation across built-in storage adapters. Supplying `id` to `mastra.datasets.create()` now creates the dataset once and resolves compatible retries to the persisted record; incompatible immutable identity fields throw `DATASET_ID_CONFLICT`. ([#19370](https://github.com/mastra-ai/mastra/pull/19370))
+
+- Added caller-defined dataset item identities for safe retries across all dataset storage adapters. ([#19384](https://github.com/mastra-ai/mastra/pull/19384))
+
+  Dataset items can now include an `externalId` when calling `addItem` or `addItems`:
+
+  ```ts
+  await dataset.addItem({
+    externalId: 'source-item-123',
+    input: { prompt: 'Hello' },
+  });
+  ```
+
+  Retrying with the same identity and payload returns the existing item. Reusing an identity with different content returns a typed conflict, including during concurrent writes. Updates and deletes preserve the identity, Spanner retries transactions without changing the outcome, and MySQL batch writes now preserve every supported dataset item field.
+
+### Patch Changes
+
+- Raised the `@mastra/core` peer dependency floor to `>=1.51.0-0` so the dataset item identity helpers used by the storage adapters are available at runtime. ([#19384](https://github.com/mastra-ai/mastra/pull/19384))
+
+- Updated dependencies [[`a99eae8`](https://github.com/mastra-ai/mastra/commit/a99eae8908e500c1b2d12f9d277be616b98617a5), [`fd13f8e`](https://github.com/mastra-ai/mastra/commit/fd13f8e21990f9904c3eedba3a626bb4a929cdb8), [`f703f87`](https://github.com/mastra-ai/mastra/commit/f703f878de072d51fda557f9c50867d8252bef05), [`0ad646f`](https://github.com/mastra-ai/mastra/commit/0ad646f71a530f2454664299e5e01bfd13fa12e5)]:
+  - @mastra/core@1.51.0-alpha.13
+
 ## 1.16.0-alpha.0
 
 ### Minor Changes

package/dist/docs/SKILL.md

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

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.16.0-alpha.0",
+  "version": "1.16.0",
   "package": "@mastra/libsql",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-memory-overview.md

@@ -77,7 +77,7 @@ Use memory when your agent needs to maintain multi-turn conversations that refer
    bun add @mastra/libsql@latest
    ```
 
-   > **Note:** For more details on available providers and how storage works in Mastra, visit the [storage](https://mastra.ai/docs/storage/overview) documentation.
+   For more details on available providers and how storage works in Mastra, visit the [storage](https://mastra.ai/docs/storage/overview) documentation.
 
 3. Add the storage provider to your main Mastra instance to enable memory across all configured agents.
 
@@ -110,7 +110,7 @@ Use memory when your agent needs to maintain multi-turn conversations that refer
    })
    ```
 
-   > **Note:** Visit [Memory Class](https://mastra.ai/reference/memory/memory-class) for a full list of configuration options.
+   Visit [Memory Class](https://mastra.ai/reference/memory/memory-class) for a full list of configuration options.
 
 5. Call your agent, for example in [Studio](https://mastra.ai/docs/studio/overview). Inside Studio, start a new chat with your agent and take a look at the right sidebar. It'll now display various memory-related information.
 
@@ -166,7 +166,7 @@ export const memoryAgent = new Agent({
 })
 ```
 
-> **Note:** See [Observational Memory](https://mastra.ai/docs/memory/observational-memory) for details on how observations and reflections work, and [the reference](https://mastra.ai/reference/memory/observational-memory) for all configuration options.
+See [Observational Memory](https://mastra.ai/docs/memory/observational-memory) for details on how observations and reflections work, and [the reference](https://mastra.ai/reference/memory/observational-memory) for all configuration options.
 
 ## Memory in multi-agent systems
 
@@ -238,7 +238,7 @@ export const memoryAgent = new Agent({
 })
 ```
 
-> **Note:** Visit [Request Context](https://mastra.ai/docs/server/request-context) for more information.
+Visit [Request Context](https://mastra.ai/docs/server/request-context) for more information.
 
 ## Related
 

package/dist/index.cjs

@@ -1597,6 +1597,19 @@ var LibSQLDB = class extends base.MastraBase {
   insert(args) {
     return this.executeWriteOperationWithRetry(() => this.doInsert(args), `insert into table ${args.tableName}`);
   }
+  /** Inserts a record without replacing an existing primary key. */
+  insertOnly(args) {
+    return this.executeWriteOperationWithRetry(async () => {
+      const filteredRecord = await this.filterRecordToKnownColumns(args.tableName, args.record);
+      if (Object.keys(filteredRecord).length === 0) return;
+      const statement = prepareStatement({ tableName: args.tableName, record: filteredRecord });
+      if (!statement.sql.startsWith("INSERT OR REPLACE")) {
+        throw new Error(`Unexpected insert statement generated for table ${args.tableName}`);
+      }
+      statement.sql = statement.sql.replace("INSERT OR REPLACE", "INSERT");
+      await withClientWriteLock(this.client, () => this.client.execute(statement));
+    }, `insert into table ${args.tableName}`);
+  }
   /**
    * Internal update implementation without retry logic.
    */
@@ -3906,6 +3919,7 @@ var DatasetsLibSQL = class extends storage.DatasetsStorage {
     await this.#addColumnIfNotExists(storage.TABLE_DATASET_ITEMS, "organizationId", "TEXT");
     await this.#addColumnIfNotExists(storage.TABLE_DATASET_ITEMS, "projectId", "TEXT");
     await this.#addColumnIfNotExists(storage.TABLE_DATASET_ITEMS, "toolMocks", "TEXT");
+    await this.#addColumnIfNotExists(storage.TABLE_DATASET_ITEMS, "externalId", "TEXT");
     await this.#client.batch(
       [
         {
@@ -3916,6 +3930,10 @@ var DatasetsLibSQL = class extends storage.DatasetsStorage {
           sql: `CREATE INDEX IF NOT EXISTS idx_dataset_items_dataset_version ON "${storage.TABLE_DATASET_ITEMS}" ("datasetId", "datasetVersion")`,
           args: []
         },
+        {
+          sql: `CREATE INDEX IF NOT EXISTS idx_dataset_items_dataset_externalid_version ON "${storage.TABLE_DATASET_ITEMS}" ("datasetId", "externalId", "datasetVersion")`,
+          args: []
+        },
         {
           sql: `CREATE INDEX IF NOT EXISTS idx_dataset_items_dataset_validto_deleted ON "${storage.TABLE_DATASET_ITEMS}" ("datasetId", "validTo", "isDeleted")`,
           args: []
@@ -3995,6 +4013,7 @@ var DatasetsLibSQL = class extends storage.DatasetsStorage {
       id: row.id,
       datasetId: row.datasetId,
       datasetVersion: row.datasetVersion,
+      externalId: row.externalId ?? null,
       organizationId: row.organizationId ?? null,
       projectId: row.projectId ?? null,
       input: storage.safelyParseJSON(row.input),
@@ -4013,6 +4032,7 @@ var DatasetsLibSQL = class extends storage.DatasetsStorage {
       id: row.id,
       datasetId: row.datasetId,
       datasetVersion: row.datasetVersion,
+      externalId: row.externalId ?? null,
       organizationId: row.organizationId ?? null,
       projectId: row.projectId ?? null,
       validTo: row.validTo,
@@ -4039,10 +4059,11 @@ var DatasetsLibSQL = class extends storage.DatasetsStorage {
   // --- Dataset CRUD ---
   async createDataset(input) {
     try {
-      const id = crypto.randomUUID();
+      const id = input.id ?? crypto.randomUUID();
+      if (input.id !== void 0) this.validateCallerDefinedDatasetId(input.id);
       const now = /* @__PURE__ */ new Date();
       const nowIso = now.toISOString();
-      await this.#db.insert({
+      await this.#db.insertOnly({
         tableName: storage.TABLE_DATASETS,
         record: {
           id,
@@ -4084,6 +4105,11 @@ var DatasetsLibSQL = class extends storage.DatasetsStorage {
         updatedAt: now
       };
     } catch (error$1) {
+      if (input.id !== void 0 && storage.hasErrorCode(error$1, /* @__PURE__ */ new Set(["SQLITE_CONSTRAINT", "SQLITE_CONSTRAINT_PRIMARYKEY", "SQLITE_CONSTRAINT_UNIQUE"]))) {
+        const existing = await this.getDatasetById({ id: input.id });
+        if (existing) return this.resolveExistingDataset(existing, { ...input, id: input.id });
+      }
+      if (error$1 instanceof error.MastraError) throw error$1;
       throw new error.MastraError(
         {
           id: storage.createStorageErrorId("LIBSQL", "CREATE_DATASET", "FAILED"),
@@ -4329,11 +4355,12 @@ var DatasetsLibSQL = class extends storage.DatasetsStorage {
             args: [args.datasetId]
           },
           {
-            sql: `INSERT INTO ${storage.TABLE_DATASET_ITEMS} (id, datasetId, datasetVersion, organizationId, projectId, validTo, isDeleted, input, groundTruth, expectedTrajectory, toolMocks, requestContext, metadata, source, createdAt, updatedAt) VALUES (?, ?, (SELECT version FROM ${storage.TABLE_DATASETS} WHERE id = ?), (SELECT organizationId FROM ${storage.TABLE_DATASETS} WHERE id = ?), (SELECT projectId FROM ${storage.TABLE_DATASETS} WHERE id = ?), NULL, 0, jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), ?, ?)`,
+            sql: `INSERT INTO ${storage.TABLE_DATASET_ITEMS} (id, datasetId, datasetVersion, externalId, organizationId, projectId, validTo, isDeleted, input, groundTruth, expectedTrajectory, toolMocks, requestContext, metadata, source, createdAt, updatedAt) VALUES (?, ?, (SELECT version FROM ${storage.TABLE_DATASETS} WHERE id = ?), ?, (SELECT organizationId FROM ${storage.TABLE_DATASETS} WHERE id = ?), (SELECT projectId FROM ${storage.TABLE_DATASETS} WHERE id = ?), NULL, 0, jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), ?, ?)`,
             args: [
               id,
               args.datasetId,
               args.datasetId,
+              args.externalId ?? null,
               args.datasetId,
               args.datasetId,
               jsonbArg(args.input),
@@ -4359,6 +4386,7 @@ var DatasetsLibSQL = class extends storage.DatasetsStorage {
         id,
         datasetId: args.datasetId,
         datasetVersion: newVersion,
+        externalId: args.externalId ?? null,
         organizationId: dataset?.organizationId ?? null,
         projectId: dataset?.projectId ?? null,
         input: args.input,
@@ -4424,11 +4452,12 @@ var DatasetsLibSQL = class extends storage.DatasetsStorage {
             args: [args.datasetId, args.id]
           },
           {
-            sql: `INSERT INTO ${storage.TABLE_DATASET_ITEMS} (id, datasetId, datasetVersion, organizationId, projectId, validTo, isDeleted, input, groundTruth, expectedTrajectory, toolMocks, requestContext, metadata, source, createdAt, updatedAt) VALUES (?, ?, (SELECT version FROM ${storage.TABLE_DATASETS} WHERE id = ?), (SELECT organizationId FROM ${storage.TABLE_DATASETS} WHERE id = ?), (SELECT projectId FROM ${storage.TABLE_DATASETS} WHERE id = ?), NULL, 0, jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), ?, ?)`,
+            sql: `INSERT INTO ${storage.TABLE_DATASET_ITEMS} (id, datasetId, datasetVersion, externalId, organizationId, projectId, validTo, isDeleted, input, groundTruth, expectedTrajectory, toolMocks, requestContext, metadata, source, createdAt, updatedAt) VALUES (?, ?, (SELECT version FROM ${storage.TABLE_DATASETS} WHERE id = ?), ?, (SELECT organizationId FROM ${storage.TABLE_DATASETS} WHERE id = ?), (SELECT projectId FROM ${storage.TABLE_DATASETS} WHERE id = ?), NULL, 0, jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), ?, ?)`,
             args: [
               args.id,
               args.datasetId,
               args.datasetId,
+              existing.externalId ?? null,
               args.datasetId,
               args.datasetId,
               jsonbArg(mergedInput),
@@ -4501,11 +4530,12 @@ var DatasetsLibSQL = class extends storage.DatasetsStorage {
             args: [datasetId, id]
           },
           {
-            sql: `INSERT INTO ${storage.TABLE_DATASET_ITEMS} (id, datasetId, datasetVersion, organizationId, projectId, validTo, isDeleted, input, groundTruth, expectedTrajectory, toolMocks, requestContext, metadata, source, createdAt, updatedAt) VALUES (?, ?, (SELECT version FROM ${storage.TABLE_DATASETS} WHERE id = ?), (SELECT organizationId FROM ${storage.TABLE_DATASETS} WHERE id = ?), (SELECT projectId FROM ${storage.TABLE_DATASETS} WHERE id = ?), NULL, 1, jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), ?, ?)`,
+            sql: `INSERT INTO ${storage.TABLE_DATASET_ITEMS} (id, datasetId, datasetVersion, externalId, organizationId, projectId, validTo, isDeleted, input, groundTruth, expectedTrajectory, toolMocks, requestContext, metadata, source, createdAt, updatedAt) VALUES (?, ?, (SELECT version FROM ${storage.TABLE_DATASETS} WHERE id = ?), ?, (SELECT organizationId FROM ${storage.TABLE_DATASETS} WHERE id = ?), (SELECT projectId FROM ${storage.TABLE_DATASETS} WHERE id = ?), NULL, 1, jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), ?, ?)`,
             args: [
               id,
               datasetId,
               datasetId,
+              existing.externalId ?? null,
               datasetId,
               datasetId,
               jsonbArg(existing.input),
@@ -4787,70 +4817,94 @@ var DatasetsLibSQL = class extends storage.DatasetsStorage {
   // --- Bulk operations (SCD-2 internally) ---
   async _doBatchInsertItems(input) {
     try {
-      const dataset = await this.getDatasetById({ id: input.datasetId });
-      if (!dataset) {
-        throw new error.MastraError({
-          id: storage.createStorageErrorId("LIBSQL", "BULK_ADD_ITEMS", "DATASET_NOT_FOUND"),
-          domain: error.ErrorDomain.STORAGE,
-          category: error.ErrorCategory.USER,
-          details: { datasetId: input.datasetId }
-        });
-      }
-      const now = /* @__PURE__ */ new Date();
-      const nowIso = now.toISOString();
-      const versionId = crypto.randomUUID();
-      const statements = [
-        {
-          sql: `UPDATE ${storage.TABLE_DATASETS} SET version = version + 1 WHERE id = ? RETURNING version`,
-          args: [input.datasetId]
+      if (input.items.length === 0) return [];
+      return await withClientWriteLock(this.#client, async () => {
+        const tx = await this.#client.transaction("write");
+        try {
+          const datasetResult = await tx.execute({
+            sql: `SELECT version, organizationId, projectId FROM ${storage.TABLE_DATASETS} WHERE id = ?`,
+            args: [input.datasetId]
+          });
+          const dataset = datasetResult.rows[0];
+          if (!dataset)
+            throw new error.MastraError({
+              id: storage.createStorageErrorId("LIBSQL", "BULK_ADD_ITEMS", "DATASET_NOT_FOUND"),
+              domain: error.ErrorDomain.STORAGE,
+              category: error.ErrorCategory.USER,
+              details: { datasetId: input.datasetId }
+            });
+          const externalIds = [...new Set(input.items.flatMap((item) => item.externalId ? [item.externalId] : []))];
+          const historyResult = externalIds.length ? await tx.execute({
+            sql: `SELECT id, datasetId, datasetVersion, externalId, organizationId, projectId, validTo, isDeleted, json(input) AS input, json(groundTruth) AS groundTruth, json(expectedTrajectory) AS expectedTrajectory, json(toolMocks) AS toolMocks, json(requestContext) AS requestContext, json(metadata) AS metadata, json(source) AS source, createdAt, updatedAt FROM ${storage.TABLE_DATASET_ITEMS} WHERE datasetId = ? AND externalId IN (${externalIds.map(() => "?").join(",")}) ORDER BY datasetVersion`,
+            args: [input.datasetId, ...externalIds]
+          }) : { rows: [] };
+          const plan = this.planDatasetItemBatch(
+            input.items,
+            historyResult.rows.map((row) => this.transformItemRowFull(row)),
+            () => crypto.randomUUID()
+          );
+          const resolved = new Map(
+            [...plan.existingCurrentItems].map(([id, row]) => [id, this.datasetItemFromRow(row)])
+          );
+          if (plan.inserts.length > 0) {
+            const newVersion = Number(dataset.version) + 1;
+            const now = /* @__PURE__ */ new Date();
+            const nowIso = now.toISOString();
+            await tx.execute({
+              sql: `UPDATE ${storage.TABLE_DATASETS} SET version = ? WHERE id = ?`,
+              args: [newVersion, input.datasetId]
+            });
+            for (const { id, item } of plan.inserts) {
+              await tx.execute({
+                sql: `INSERT INTO ${storage.TABLE_DATASET_ITEMS} (id, datasetId, datasetVersion, externalId, organizationId, projectId, validTo, isDeleted, input, groundTruth, expectedTrajectory, toolMocks, requestContext, metadata, source, createdAt, updatedAt) VALUES (?, ?, ?, ?, ?, ?, NULL, 0, jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), ?, ?)`,
+                args: [
+                  id,
+                  input.datasetId,
+                  newVersion,
+                  item.externalId ?? null,
+                  dataset.organizationId ?? null,
+                  dataset.projectId ?? null,
+                  jsonbArg(item.input),
+                  jsonbArg(item.groundTruth),
+                  jsonbArg(item.expectedTrajectory),
+                  jsonbArg(item.toolMocks),
+                  jsonbArg(item.requestContext),
+                  jsonbArg(item.metadata),
+                  jsonbArg(item.source),
+                  nowIso,
+                  nowIso
+                ]
+              });
+              resolved.set(id, {
+                id,
+                datasetId: input.datasetId,
+                datasetVersion: newVersion,
+                externalId: item.externalId ?? null,
+                organizationId: dataset.organizationId,
+                projectId: dataset.projectId,
+                input: item.input,
+                groundTruth: item.groundTruth,
+                expectedTrajectory: item.expectedTrajectory,
+                toolMocks: item.toolMocks,
+                requestContext: item.requestContext,
+                metadata: item.metadata,
+                source: item.source,
+                createdAt: now,
+                updatedAt: now
+              });
+            }
+            await tx.execute({
+              sql: `INSERT INTO ${storage.TABLE_DATASET_VERSIONS} (id, datasetId, version, createdAt) VALUES (?, ?, ?, ?)`,
+              args: [crypto.randomUUID(), input.datasetId, newVersion, nowIso]
+            });
+          }
+          await tx.commit();
+          return plan.resolvedIds.map((id) => resolved.get(id));
+        } catch (error) {
+          if (!tx.closed) await tx.rollback();
+          throw error;
         }
-      ];
-      const items = [];
-      for (const itemInput of input.items) {
-        const id = crypto.randomUUID();
-        items.push({ id, input: itemInput });
-        statements.push({
-          sql: `INSERT INTO ${storage.TABLE_DATASET_ITEMS} (id, datasetId, datasetVersion, organizationId, projectId, validTo, isDeleted, input, groundTruth, expectedTrajectory, toolMocks, requestContext, metadata, source, createdAt, updatedAt) VALUES (?, ?, (SELECT version FROM ${storage.TABLE_DATASETS} WHERE id = ?), ?, ?, NULL, 0, jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), ?, ?)`,
-          args: [
-            id,
-            input.datasetId,
-            input.datasetId,
-            dataset.organizationId ?? null,
-            dataset.projectId ?? null,
-            jsonbArg(itemInput.input),
-            jsonbArg(itemInput.groundTruth),
-            jsonbArg(itemInput.expectedTrajectory),
-            jsonbArg(itemInput.toolMocks),
-            jsonbArg(itemInput.requestContext),
-            jsonbArg(itemInput.metadata),
-            jsonbArg(itemInput.source),
-            nowIso,
-            nowIso
-          ]
-        });
-      }
-      statements.push({
-        sql: `INSERT INTO ${storage.TABLE_DATASET_VERSIONS} (id, datasetId, version, createdAt) VALUES (?, ?, (SELECT version FROM ${storage.TABLE_DATASETS} WHERE id = ?), ?)`,
-        args: [versionId, input.datasetId, input.datasetId, nowIso]
       });
-      const results = await this.#client.batch(statements, "write");
-      const newVersion = Number(results[0].rows[0].version);
-      return items.map(({ id, input: itemInput }) => ({
-        id,
-        datasetId: input.datasetId,
-        datasetVersion: newVersion,
-        organizationId: dataset.organizationId ?? null,
-        projectId: dataset.projectId ?? null,
-        input: itemInput.input,
-        groundTruth: itemInput.groundTruth,
-        expectedTrajectory: itemInput.expectedTrajectory,
-        toolMocks: itemInput.toolMocks,
-        requestContext: itemInput.requestContext,
-        metadata: itemInput.metadata,
-        source: itemInput.source,
-        createdAt: now,
-        updatedAt: now
-      }));
     } catch (error$1) {
       if (error$1 instanceof error.MastraError) throw error$1;
       throw new error.MastraError(
@@ -4896,11 +4950,12 @@ var DatasetsLibSQL = class extends storage.DatasetsStorage {
           args: [input.datasetId, item.id]
         });
         statements.push({
-          sql: `INSERT INTO ${storage.TABLE_DATASET_ITEMS} (id, datasetId, datasetVersion, organizationId, projectId, validTo, isDeleted, input, groundTruth, expectedTrajectory, toolMocks, requestContext, metadata, source, createdAt, updatedAt) VALUES (?, ?, (SELECT version FROM ${storage.TABLE_DATASETS} WHERE id = ?), ?, ?, NULL, 1, jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), ?, ?)`,
+          sql: `INSERT INTO ${storage.TABLE_DATASET_ITEMS} (id, datasetId, datasetVersion, externalId, organizationId, projectId, validTo, isDeleted, input, groundTruth, expectedTrajectory, toolMocks, requestContext, metadata, source, createdAt, updatedAt) VALUES (?, ?, (SELECT version FROM ${storage.TABLE_DATASETS} WHERE id = ?), ?, ?, ?, NULL, 1, jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), jsonb(?), ?, ?)`,
           args: [
             item.id,
             input.datasetId,
             input.datasetId,
+            item.externalId ?? null,
             dataset.organizationId ?? null,
             dataset.projectId ?? null,
             jsonbArg(item.input),