@mastra/convex 0.0.0-new-button-export-20251219133013 → 0.0.0-salesman-20260127182805

package/dist/chunk-FTVDAP6U.cjs

@@ -0,0 +1,113 @@
+'use strict';
+
+var constants = require('@mastra/core/storage/constants');
+var server = require('convex/server');
+var values = require('convex/values');
+
+// src/schema.ts
+function columnToValidator(column) {
+  let validator;
+  switch (column.type) {
+    case "text":
+      validator = values.v.string();
+      break;
+    case "integer":
+    case "float":
+      validator = values.v.number();
+      break;
+    case "bigint":
+      validator = values.v.int64();
+      break;
+    case "boolean":
+      validator = values.v.boolean();
+      break;
+    case "timestamp":
+      validator = values.v.string();
+      break;
+    case "jsonb":
+    case "json":
+      validator = values.v.any();
+      break;
+    default:
+      validator = values.v.any();
+  }
+  return column.nullable ? values.v.optional(validator) : validator;
+}
+function buildTableFromSchema(schema) {
+  const fields = {};
+  for (const [key, column] of Object.entries(schema)) {
+    fields[key] = columnToValidator(column);
+  }
+  return fields;
+}
+var mastraThreadsTable = server.defineTable(buildTableFromSchema(constants.TABLE_SCHEMAS[constants.TABLE_THREADS])).index("by_record_id", ["id"]).index("by_resource", ["resourceId"]).index("by_created", ["createdAt"]).index("by_updated", ["updatedAt"]);
+var mastraMessagesTable = server.defineTable(buildTableFromSchema(constants.TABLE_SCHEMAS[constants.TABLE_MESSAGES])).index("by_record_id", ["id"]).index("by_thread", ["thread_id"]).index("by_thread_created", ["thread_id", "createdAt"]).index("by_resource", ["resourceId"]);
+var mastraResourcesTable = server.defineTable(buildTableFromSchema(constants.TABLE_SCHEMAS[constants.TABLE_RESOURCES])).index("by_record_id", ["id"]).index("by_updated", ["updatedAt"]);
+var mastraWorkflowSnapshotsTable = server.defineTable({
+  id: values.v.optional(values.v.string()),
+  // Synthetic ID for Convex index, generated at runtime
+  workflow_name: values.v.string(),
+  run_id: values.v.string(),
+  resourceId: values.v.optional(values.v.string()),
+  snapshot: values.v.any(),
+  createdAt: values.v.string(),
+  updatedAt: values.v.string()
+}).index("by_record_id", ["id"]).index("by_workflow_run", ["workflow_name", "run_id"]).index("by_workflow", ["workflow_name"]).index("by_resource", ["resourceId"]).index("by_created", ["createdAt"]);
+var mastraScoresTable = server.defineTable(buildTableFromSchema(constants.TABLE_SCHEMAS[constants.TABLE_SCORERS])).index("by_record_id", ["id"]).index("by_scorer", ["scorerId"]).index("by_entity", ["entityId", "entityType"]).index("by_run", ["runId"]).index("by_created", ["createdAt"]);
+var mastraVectorIndexesTable = server.defineTable({
+  id: values.v.string(),
+  // Mastra record ID (same as indexName)
+  indexName: values.v.string(),
+  dimension: values.v.number(),
+  metric: values.v.string(),
+  createdAt: values.v.string()
+}).index("by_record_id", ["id"]).index("by_name", ["indexName"]);
+var mastraVectorsTable = server.defineTable({
+  id: values.v.string(),
+  // Mastra record ID
+  indexName: values.v.string(),
+  embedding: values.v.array(values.v.float64()),
+  metadata: values.v.optional(values.v.any())
+}).index("by_index_id", ["indexName", "id"]).index("by_index", ["indexName"]);
+var mastraDocumentsTable = server.defineTable({
+  table: values.v.string(),
+  primaryKey: values.v.string(),
+  record: values.v.any()
+}).index("by_table", ["table"]).index("by_table_primary", ["table", "primaryKey"]);
+var TABLE_VECTOR_INDEXES = "mastra_vector_indexes";
+var TABLE_VECTORS = "mastra_vectors";
+var TABLE_DOCUMENTS = "mastra_documents";
+
+Object.defineProperty(exports, "TABLE_MESSAGES", {
+  enumerable: true,
+  get: function () { return constants.TABLE_MESSAGES; }
+});
+Object.defineProperty(exports, "TABLE_RESOURCES", {
+  enumerable: true,
+  get: function () { return constants.TABLE_RESOURCES; }
+});
+Object.defineProperty(exports, "TABLE_SCORERS", {
+  enumerable: true,
+  get: function () { return constants.TABLE_SCORERS; }
+});
+Object.defineProperty(exports, "TABLE_THREADS", {
+  enumerable: true,
+  get: function () { return constants.TABLE_THREADS; }
+});
+Object.defineProperty(exports, "TABLE_WORKFLOW_SNAPSHOT", {
+  enumerable: true,
+  get: function () { return constants.TABLE_WORKFLOW_SNAPSHOT; }
+});
+exports.TABLE_DOCUMENTS = TABLE_DOCUMENTS;
+exports.TABLE_VECTORS = TABLE_VECTORS;
+exports.TABLE_VECTOR_INDEXES = TABLE_VECTOR_INDEXES;
+exports.mastraDocumentsTable = mastraDocumentsTable;
+exports.mastraMessagesTable = mastraMessagesTable;
+exports.mastraResourcesTable = mastraResourcesTable;
+exports.mastraScoresTable = mastraScoresTable;
+exports.mastraThreadsTable = mastraThreadsTable;
+exports.mastraVectorIndexesTable = mastraVectorIndexesTable;
+exports.mastraVectorsTable = mastraVectorsTable;
+exports.mastraWorkflowSnapshotsTable = mastraWorkflowSnapshotsTable;
+//# sourceMappingURL=chunk-FTVDAP6U.cjs.map
+//# sourceMappingURL=chunk-FTVDAP6U.cjs.map

package/dist/chunk-FTVDAP6U.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema.ts"],"names":["v","defineTable","TABLE_SCHEMAS","TABLE_THREADS","TABLE_MESSAGES","TABLE_RESOURCES","TABLE_SCORERS"],"mappings":"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","file":"chunk-FTVDAP6U.cjs","sourcesContent":["/**\n * Convex schema definitions for Mastra tables.\n *\n * This file dynamically builds Convex table definitions from the canonical\n * TABLE_SCHEMAS in @mastra/core/storage/constants to ensure they stay in sync.\n *\n * The import path @mastra/core/storage/constants is specifically designed to\n * avoid pulling in Node.js dependencies, making it safe to use in Convex's\n * sandboxed schema evaluation environment.\n */\nimport {\n  TABLE_SCHEMAS,\n  TABLE_WORKFLOW_SNAPSHOT,\n  TABLE_MESSAGES,\n  TABLE_THREADS,\n  TABLE_RESOURCES,\n  TABLE_SCORERS,\n} from '@mastra/core/storage/constants';\nimport { defineTable } from 'convex/server';\nimport { v } from 'convex/values';\n\n/**\n * Helper to convert Mastra StorageColumn type to Convex validator\n */\nfunction columnToValidator(column: { type: string; nullable?: boolean }) {\n  let validator;\n  switch (column.type) {\n    case 'text':\n      validator = v.string();\n      break;\n    case 'integer':\n    case 'float':\n      validator = v.number();\n      break;\n    case 'bigint':\n      validator = v.int64();\n      break;\n    case 'boolean':\n      validator = v.boolean();\n      break;\n    case 'timestamp':\n      validator = v.string(); // Store as ISO string\n      break;\n    case 'jsonb':\n    case 'json':\n      validator = v.any();\n      break;\n    default:\n      validator = v.any();\n  }\n  return column.nullable ? v.optional(validator) : validator;\n}\n\n/**\n * Build Convex table definition from Mastra schema.\n * Includes the `id` field as a regular field (Convex auto-generates _id).\n */\nfunction buildTableFromSchema(schema: Record<string, { type: string; nullable?: boolean; primaryKey?: boolean }>) {\n  const fields: Record<string, any> = {};\n  for (const [key, column] of Object.entries(schema)) {\n    fields[key] = columnToValidator(column);\n  }\n  return fields;\n}\n\n// ============================================================================\n// Table Definitions - Built from @mastra/core TABLE_SCHEMAS\n// ============================================================================\n\n/**\n * Threads table - stores conversation threads\n * Schema: TABLE_SCHEMAS[TABLE_THREADS]\n */\nexport const mastraThreadsTable = defineTable(buildTableFromSchema(TABLE_SCHEMAS[TABLE_THREADS]))\n  .index('by_record_id', ['id'])\n  .index('by_resource', ['resourceId'])\n  .index('by_created', ['createdAt'])\n  .index('by_updated', ['updatedAt']);\n\n/**\n * Messages table - stores conversation messages\n * Schema: TABLE_SCHEMAS[TABLE_MESSAGES]\n */\nexport const mastraMessagesTable = defineTable(buildTableFromSchema(TABLE_SCHEMAS[TABLE_MESSAGES]))\n  .index('by_record_id', ['id'])\n  .index('by_thread', ['thread_id'])\n  .index('by_thread_created', ['thread_id', 'createdAt'])\n  .index('by_resource', ['resourceId']);\n\n/**\n * Resources table - stores resource/user working memory\n * Schema: TABLE_SCHEMAS[TABLE_RESOURCES]\n */\nexport const mastraResourcesTable = defineTable(buildTableFromSchema(TABLE_SCHEMAS[TABLE_RESOURCES]))\n  .index('by_record_id', ['id'])\n  .index('by_updated', ['updatedAt']);\n\n/**\n * Workflow snapshots table - stores workflow execution state\n * Schema: TABLE_SCHEMAS[TABLE_WORKFLOW_SNAPSHOT]\n *\n * Note: The `id` field is added explicitly for Convex's by_record_id index.\n * The core schema uses (workflow_name, run_id) as a composite key, but Convex\n * requires a single-column index. The id value is generated at runtime as\n * `${workflow_name}-${run_id}` by the Convex storage adapter's normalizeRecord().\n *\n * Fields are defined explicitly (not using buildTableFromSchema) because TypeScript's\n * type inference doesn't work well with spread operators in Convex's defineTable.\n */\nexport const mastraWorkflowSnapshotsTable = defineTable({\n  id: v.optional(v.string()), // Synthetic ID for Convex index, generated at runtime\n  workflow_name: v.string(),\n  run_id: v.string(),\n  resourceId: v.optional(v.string()),\n  snapshot: v.any(),\n  createdAt: v.string(),\n  updatedAt: v.string(),\n})\n  .index('by_record_id', ['id'])\n  .index('by_workflow_run', ['workflow_name', 'run_id'])\n  .index('by_workflow', ['workflow_name'])\n  .index('by_resource', ['resourceId'])\n  .index('by_created', ['createdAt']);\n\n/**\n * Scores table - stores evaluation scores\n * Schema: TABLE_SCHEMAS[TABLE_SCORERS]\n */\nexport const mastraScoresTable = defineTable(buildTableFromSchema(TABLE_SCHEMAS[TABLE_SCORERS]))\n  .index('by_record_id', ['id'])\n  .index('by_scorer', ['scorerId'])\n  .index('by_entity', ['entityId', 'entityType'])\n  .index('by_run', ['runId'])\n  .index('by_created', ['createdAt']);\n\n// ============================================================================\n// Vector Tables - Not in core schemas (vector-specific)\n// ============================================================================\n\n/**\n * Vector indexes table - stores metadata about vector indexes\n */\nexport const mastraVectorIndexesTable = defineTable({\n  id: v.string(), // Mastra record ID (same as indexName)\n  indexName: v.string(),\n  dimension: v.number(),\n  metric: v.string(),\n  createdAt: v.string(),\n})\n  .index('by_record_id', ['id'])\n  .index('by_name', ['indexName']);\n\n/**\n * Vectors table - stores vector embeddings\n * Uses indexName field to support multiple indexes with different dimensions\n */\nexport const mastraVectorsTable = defineTable({\n  id: v.string(), // Mastra record ID\n  indexName: v.string(),\n  embedding: v.array(v.float64()),\n  metadata: v.optional(v.any()),\n})\n  .index('by_index_id', ['indexName', 'id']) // Composite for scoped lookups per index\n  .index('by_index', ['indexName']);\n\n// ============================================================================\n// Fallback Table - For unknown/custom tables\n// ============================================================================\n\n/**\n * Generic documents table - fallback for unknown table types\n */\nexport const mastraDocumentsTable = defineTable({\n  table: v.string(),\n  primaryKey: v.string(),\n  record: v.any(),\n})\n  .index('by_table', ['table'])\n  .index('by_table_primary', ['table', 'primaryKey']);\n\n// ============================================================================\n// Re-export table name constants for convenience\n// ============================================================================\n\nexport { TABLE_WORKFLOW_SNAPSHOT, TABLE_MESSAGES, TABLE_THREADS, TABLE_RESOURCES, TABLE_SCORERS };\n\n// Additional table name constants for vector tables (not in core)\nexport const TABLE_VECTOR_INDEXES = 'mastra_vector_indexes';\nexport const TABLE_VECTORS = 'mastra_vectors';\nexport const TABLE_DOCUMENTS = 'mastra_documents';\n"]}

package/dist/chunk-G5FLGAPE.js

@@ -0,0 +1,82 @@
+import { TABLE_SCHEMAS, TABLE_THREADS, TABLE_MESSAGES, TABLE_RESOURCES, TABLE_SCORERS } from '@mastra/core/storage/constants';
+export { TABLE_MESSAGES, TABLE_RESOURCES, TABLE_SCORERS, TABLE_THREADS, TABLE_WORKFLOW_SNAPSHOT } from '@mastra/core/storage/constants';
+import { defineTable } from 'convex/server';
+import { v } from 'convex/values';
+
+// src/schema.ts
+function columnToValidator(column) {
+  let validator;
+  switch (column.type) {
+    case "text":
+      validator = v.string();
+      break;
+    case "integer":
+    case "float":
+      validator = v.number();
+      break;
+    case "bigint":
+      validator = v.int64();
+      break;
+    case "boolean":
+      validator = v.boolean();
+      break;
+    case "timestamp":
+      validator = v.string();
+      break;
+    case "jsonb":
+    case "json":
+      validator = v.any();
+      break;
+    default:
+      validator = v.any();
+  }
+  return column.nullable ? v.optional(validator) : validator;
+}
+function buildTableFromSchema(schema) {
+  const fields = {};
+  for (const [key, column] of Object.entries(schema)) {
+    fields[key] = columnToValidator(column);
+  }
+  return fields;
+}
+var mastraThreadsTable = defineTable(buildTableFromSchema(TABLE_SCHEMAS[TABLE_THREADS])).index("by_record_id", ["id"]).index("by_resource", ["resourceId"]).index("by_created", ["createdAt"]).index("by_updated", ["updatedAt"]);
+var mastraMessagesTable = defineTable(buildTableFromSchema(TABLE_SCHEMAS[TABLE_MESSAGES])).index("by_record_id", ["id"]).index("by_thread", ["thread_id"]).index("by_thread_created", ["thread_id", "createdAt"]).index("by_resource", ["resourceId"]);
+var mastraResourcesTable = defineTable(buildTableFromSchema(TABLE_SCHEMAS[TABLE_RESOURCES])).index("by_record_id", ["id"]).index("by_updated", ["updatedAt"]);
+var mastraWorkflowSnapshotsTable = defineTable({
+  id: v.optional(v.string()),
+  // Synthetic ID for Convex index, generated at runtime
+  workflow_name: v.string(),
+  run_id: v.string(),
+  resourceId: v.optional(v.string()),
+  snapshot: v.any(),
+  createdAt: v.string(),
+  updatedAt: v.string()
+}).index("by_record_id", ["id"]).index("by_workflow_run", ["workflow_name", "run_id"]).index("by_workflow", ["workflow_name"]).index("by_resource", ["resourceId"]).index("by_created", ["createdAt"]);
+var mastraScoresTable = defineTable(buildTableFromSchema(TABLE_SCHEMAS[TABLE_SCORERS])).index("by_record_id", ["id"]).index("by_scorer", ["scorerId"]).index("by_entity", ["entityId", "entityType"]).index("by_run", ["runId"]).index("by_created", ["createdAt"]);
+var mastraVectorIndexesTable = defineTable({
+  id: v.string(),
+  // Mastra record ID (same as indexName)
+  indexName: v.string(),
+  dimension: v.number(),
+  metric: v.string(),
+  createdAt: v.string()
+}).index("by_record_id", ["id"]).index("by_name", ["indexName"]);
+var mastraVectorsTable = defineTable({
+  id: v.string(),
+  // Mastra record ID
+  indexName: v.string(),
+  embedding: v.array(v.float64()),
+  metadata: v.optional(v.any())
+}).index("by_index_id", ["indexName", "id"]).index("by_index", ["indexName"]);
+var mastraDocumentsTable = defineTable({
+  table: v.string(),
+  primaryKey: v.string(),
+  record: v.any()
+}).index("by_table", ["table"]).index("by_table_primary", ["table", "primaryKey"]);
+var TABLE_VECTOR_INDEXES = "mastra_vector_indexes";
+var TABLE_VECTORS = "mastra_vectors";
+var TABLE_DOCUMENTS = "mastra_documents";
+
+export { TABLE_DOCUMENTS, TABLE_VECTORS, TABLE_VECTOR_INDEXES, mastraDocumentsTable, mastraMessagesTable, mastraResourcesTable, mastraScoresTable, mastraThreadsTable, mastraVectorIndexesTable, mastraVectorsTable, mastraWorkflowSnapshotsTable };
+//# sourceMappingURL=chunk-G5FLGAPE.js.map
+//# sourceMappingURL=chunk-G5FLGAPE.js.map

package/dist/chunk-G5FLGAPE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema.ts"],"names":[],"mappings":"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","file":"chunk-G5FLGAPE.js","sourcesContent":["/**\n * Convex schema definitions for Mastra tables.\n *\n * This file dynamically builds Convex table definitions from the canonical\n * TABLE_SCHEMAS in @mastra/core/storage/constants to ensure they stay in sync.\n *\n * The import path @mastra/core/storage/constants is specifically designed to\n * avoid pulling in Node.js dependencies, making it safe to use in Convex's\n * sandboxed schema evaluation environment.\n */\nimport {\n  TABLE_SCHEMAS,\n  TABLE_WORKFLOW_SNAPSHOT,\n  TABLE_MESSAGES,\n  TABLE_THREADS,\n  TABLE_RESOURCES,\n  TABLE_SCORERS,\n} from '@mastra/core/storage/constants';\nimport { defineTable } from 'convex/server';\nimport { v } from 'convex/values';\n\n/**\n * Helper to convert Mastra StorageColumn type to Convex validator\n */\nfunction columnToValidator(column: { type: string; nullable?: boolean }) {\n  let validator;\n  switch (column.type) {\n    case 'text':\n      validator = v.string();\n      break;\n    case 'integer':\n    case 'float':\n      validator = v.number();\n      break;\n    case 'bigint':\n      validator = v.int64();\n      break;\n    case 'boolean':\n      validator = v.boolean();\n      break;\n    case 'timestamp':\n      validator = v.string(); // Store as ISO string\n      break;\n    case 'jsonb':\n    case 'json':\n      validator = v.any();\n      break;\n    default:\n      validator = v.any();\n  }\n  return column.nullable ? v.optional(validator) : validator;\n}\n\n/**\n * Build Convex table definition from Mastra schema.\n * Includes the `id` field as a regular field (Convex auto-generates _id).\n */\nfunction buildTableFromSchema(schema: Record<string, { type: string; nullable?: boolean; primaryKey?: boolean }>) {\n  const fields: Record<string, any> = {};\n  for (const [key, column] of Object.entries(schema)) {\n    fields[key] = columnToValidator(column);\n  }\n  return fields;\n}\n\n// ============================================================================\n// Table Definitions - Built from @mastra/core TABLE_SCHEMAS\n// ============================================================================\n\n/**\n * Threads table - stores conversation threads\n * Schema: TABLE_SCHEMAS[TABLE_THREADS]\n */\nexport const mastraThreadsTable = defineTable(buildTableFromSchema(TABLE_SCHEMAS[TABLE_THREADS]))\n  .index('by_record_id', ['id'])\n  .index('by_resource', ['resourceId'])\n  .index('by_created', ['createdAt'])\n  .index('by_updated', ['updatedAt']);\n\n/**\n * Messages table - stores conversation messages\n * Schema: TABLE_SCHEMAS[TABLE_MESSAGES]\n */\nexport const mastraMessagesTable = defineTable(buildTableFromSchema(TABLE_SCHEMAS[TABLE_MESSAGES]))\n  .index('by_record_id', ['id'])\n  .index('by_thread', ['thread_id'])\n  .index('by_thread_created', ['thread_id', 'createdAt'])\n  .index('by_resource', ['resourceId']);\n\n/**\n * Resources table - stores resource/user working memory\n * Schema: TABLE_SCHEMAS[TABLE_RESOURCES]\n */\nexport const mastraResourcesTable = defineTable(buildTableFromSchema(TABLE_SCHEMAS[TABLE_RESOURCES]))\n  .index('by_record_id', ['id'])\n  .index('by_updated', ['updatedAt']);\n\n/**\n * Workflow snapshots table - stores workflow execution state\n * Schema: TABLE_SCHEMAS[TABLE_WORKFLOW_SNAPSHOT]\n *\n * Note: The `id` field is added explicitly for Convex's by_record_id index.\n * The core schema uses (workflow_name, run_id) as a composite key, but Convex\n * requires a single-column index. The id value is generated at runtime as\n * `${workflow_name}-${run_id}` by the Convex storage adapter's normalizeRecord().\n *\n * Fields are defined explicitly (not using buildTableFromSchema) because TypeScript's\n * type inference doesn't work well with spread operators in Convex's defineTable.\n */\nexport const mastraWorkflowSnapshotsTable = defineTable({\n  id: v.optional(v.string()), // Synthetic ID for Convex index, generated at runtime\n  workflow_name: v.string(),\n  run_id: v.string(),\n  resourceId: v.optional(v.string()),\n  snapshot: v.any(),\n  createdAt: v.string(),\n  updatedAt: v.string(),\n})\n  .index('by_record_id', ['id'])\n  .index('by_workflow_run', ['workflow_name', 'run_id'])\n  .index('by_workflow', ['workflow_name'])\n  .index('by_resource', ['resourceId'])\n  .index('by_created', ['createdAt']);\n\n/**\n * Scores table - stores evaluation scores\n * Schema: TABLE_SCHEMAS[TABLE_SCORERS]\n */\nexport const mastraScoresTable = defineTable(buildTableFromSchema(TABLE_SCHEMAS[TABLE_SCORERS]))\n  .index('by_record_id', ['id'])\n  .index('by_scorer', ['scorerId'])\n  .index('by_entity', ['entityId', 'entityType'])\n  .index('by_run', ['runId'])\n  .index('by_created', ['createdAt']);\n\n// ============================================================================\n// Vector Tables - Not in core schemas (vector-specific)\n// ============================================================================\n\n/**\n * Vector indexes table - stores metadata about vector indexes\n */\nexport const mastraVectorIndexesTable = defineTable({\n  id: v.string(), // Mastra record ID (same as indexName)\n  indexName: v.string(),\n  dimension: v.number(),\n  metric: v.string(),\n  createdAt: v.string(),\n})\n  .index('by_record_id', ['id'])\n  .index('by_name', ['indexName']);\n\n/**\n * Vectors table - stores vector embeddings\n * Uses indexName field to support multiple indexes with different dimensions\n */\nexport const mastraVectorsTable = defineTable({\n  id: v.string(), // Mastra record ID\n  indexName: v.string(),\n  embedding: v.array(v.float64()),\n  metadata: v.optional(v.any()),\n})\n  .index('by_index_id', ['indexName', 'id']) // Composite for scoped lookups per index\n  .index('by_index', ['indexName']);\n\n// ============================================================================\n// Fallback Table - For unknown/custom tables\n// ============================================================================\n\n/**\n * Generic documents table - fallback for unknown table types\n */\nexport const mastraDocumentsTable = defineTable({\n  table: v.string(),\n  primaryKey: v.string(),\n  record: v.any(),\n})\n  .index('by_table', ['table'])\n  .index('by_table_primary', ['table', 'primaryKey']);\n\n// ============================================================================\n// Re-export table name constants for convenience\n// ============================================================================\n\nexport { TABLE_WORKFLOW_SNAPSHOT, TABLE_MESSAGES, TABLE_THREADS, TABLE_RESOURCES, TABLE_SCORERS };\n\n// Additional table name constants for vector tables (not in core)\nexport const TABLE_VECTOR_INDEXES = 'mastra_vector_indexes';\nexport const TABLE_VECTORS = 'mastra_vectors';\nexport const TABLE_DOCUMENTS = 'mastra_documents';\n"]}

package/dist/docs/README.md

@@ -0,0 +1,32 @@
+# @mastra/convex Documentation
+
+> Embedded documentation for coding agents
+
+## Quick Start
+
+```bash
+# Read the skill overview
+cat docs/SKILL.md
+
+# Get the source map
+cat docs/SOURCE_MAP.json
+
+# Read topic documentation
+cat docs/<topic>/01-overview.md
+```
+
+## Structure
+
+```
+docs/
+├── SKILL.md           # Entry point
+├── README.md          # This file
+├── SOURCE_MAP.json    # Export index
+├── storage/ (1 files)
+├── vectors/ (1 files)
+```
+
+## Version
+
+Package: @mastra/convex
+Version: 1.0.0

package/dist/docs/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: mastra-convex-docs
+description: Documentation for @mastra/convex. Includes links to type definitions and readable implementation code in dist/.
+---
+
+# @mastra/convex Documentation
+
+> **Version**: 1.0.0
+> **Package**: @mastra/convex
+
+## Quick Navigation
+
+Use SOURCE_MAP.json to find any export:
+
+```bash
+cat docs/SOURCE_MAP.json
+```
+
+Each export maps to:
+- **types**: `.d.ts` file with JSDoc and API signatures
+- **implementation**: `.js` chunk file with readable source
+- **docs**: Conceptual documentation in `docs/`
+
+## Top Exports
+
+  - mastraStorage: dist/index.d.ts
+  - TABLE_MESSAGES: dist/index.d.ts
+  - TABLE_RESOURCES: dist/index.d.ts
+  - TABLE_SCORERS: dist/index.d.ts
+  - TABLE_THREADS: dist/index.d.ts
+  - TABLE_WORKFLOW_SNAPSHOT: dist/index.d.ts
+  - mastraDocumentsTable: dist/index.d.ts
+  - mastraMessagesTable: dist/index.d.ts
+  - mastraResourcesTable: dist/index.d.ts
+  - mastraScoresTable: dist/index.d.ts
+  - mastraThreadsTable: dist/index.d.ts
+  - mastraVectorIndexesTable: dist/index.d.ts
+  - mastraVectorsTable: dist/index.d.ts
+  - mastraWorkflowSnapshotsTable: dist/index.d.ts
+
+See SOURCE_MAP.json for the complete list.
+
+## Available Topics
+
+- [Storage](storage/) - 1 file(s)
+- [Vectors](vectors/) - 1 file(s)

package/dist/docs/SOURCE_MAP.json

@@ -0,0 +1,63 @@
+{
+  "version": "1.0.0",
+  "package": "@mastra/convex",
+  "exports": {
+    "mastraStorage": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-KSAPIIEJ.js"
+    },
+    "TABLE_MESSAGES": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-G5FLGAPE.js"
+    },
+    "TABLE_RESOURCES": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-G5FLGAPE.js"
+    },
+    "TABLE_SCORERS": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-G5FLGAPE.js"
+    },
+    "TABLE_THREADS": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-G5FLGAPE.js"
+    },
+    "TABLE_WORKFLOW_SNAPSHOT": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-G5FLGAPE.js"
+    },
+    "mastraDocumentsTable": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-G5FLGAPE.js"
+    },
+    "mastraMessagesTable": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-G5FLGAPE.js"
+    },
+    "mastraResourcesTable": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-G5FLGAPE.js"
+    },
+    "mastraScoresTable": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-G5FLGAPE.js"
+    },
+    "mastraThreadsTable": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-G5FLGAPE.js"
+    },
+    "mastraVectorIndexesTable": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-G5FLGAPE.js"
+    },
+    "mastraVectorsTable": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-G5FLGAPE.js"
+    },
+    "mastraWorkflowSnapshotsTable": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-G5FLGAPE.js"
+    }
+  },
+  "modules": {}
+}

package/dist/docs/storage/01-reference.md

@@ -0,0 +1,143 @@
+# Storage API Reference
+
+> API reference for storage - 1 entries
+
+
+---
+
+## Reference: Convex Storage
+
+> Documentation for the Convex storage implementation in Mastra.
+
+The Convex storage implementation provides a serverless storage solution using [Convex](https://convex.dev), a full-stack TypeScript development platform with real-time sync and automatic caching.
+
+> **Observability Not Supported**
+Convex storage **does not support the observability domain**. Traces from the `DefaultExporter` cannot be persisted to Convex, and Mastra Studio's observability features won't work with Convex as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite#specialized-storage-for-observability-recommended-for-production) to route observability data to a supported provider like ClickHouse or PostgreSQL.
+
+## Installation
+
+```bash npm2yarn
+npm install @mastra/convex@latest
+```
+
+## Convex Setup
+
+Before using `ConvexStore`, you need to set up the Convex schema and storage handler in your Convex project.
+
+### 1. Set up Convex Schema
+
+In `convex/schema.ts`:
+
+```typescript
+import { defineSchema } from 'convex/server';
+import {
+  mastraThreadsTable,
+  mastraMessagesTable,
+  mastraResourcesTable,
+  mastraWorkflowSnapshotsTable,
+  mastraScoresTable,
+  mastraVectorIndexesTable,
+  mastraVectorsTable,
+  mastraDocumentsTable,
+} from '@mastra/convex/schema';
+
+export default defineSchema({
+  mastra_threads: mastraThreadsTable,
+  mastra_messages: mastraMessagesTable,
+  mastra_resources: mastraResourcesTable,
+  mastra_workflow_snapshots: mastraWorkflowSnapshotsTable,
+  mastra_scorers: mastraScoresTable,
+  mastra_vector_indexes: mastraVectorIndexesTable,
+  mastra_vectors: mastraVectorsTable,
+  mastra_documents: mastraDocumentsTable,
+});
+```
+
+### 2. Create the Storage Handler
+
+In `convex/mastra/storage.ts`:
+
+```typescript
+import { mastraStorage } from '@mastra/convex/server';
+
+export const handle = mastraStorage;
+```
+
+### 3. Deploy to Convex
+
+```bash
+npx convex dev
+# or for production
+npx convex deploy
+```
+
+## Usage
+
+```typescript
+import { ConvexStore } from "@mastra/convex";
+
+const storage = new ConvexStore({
+  id: 'convex-storage',
+  deploymentUrl: process.env.CONVEX_URL!,
+  adminAuthToken: process.env.CONVEX_ADMIN_KEY!,
+});
+```
+
+## Parameters
+
+## Constructor Examples
+
+```ts
+import { ConvexStore } from "@mastra/convex";
+
+// Basic configuration
+const store = new ConvexStore({
+  id: 'convex-storage',
+  deploymentUrl: "https://your-project.convex.cloud",
+  adminAuthToken: "your-admin-token",
+});
+
+// With custom storage function path
+const storeCustom = new ConvexStore({
+  id: 'convex-storage',
+  deploymentUrl: "https://your-project.convex.cloud",
+  adminAuthToken: "your-admin-token",
+  storageFunction: "custom/path:handler",
+});
+```
+
+## Additional Notes
+
+### Schema Management
+
+The storage implementation uses typed Convex tables for each Mastra domain:
+
+| Domain         | Convex Table                | Purpose              |
+| -------------- | --------------------------- | -------------------- |
+| Threads        | `mastra_threads`            | Conversation threads |
+| Messages       | `mastra_messages`           | Chat messages        |
+| Resources      | `mastra_resources`          | User working memory  |
+| Workflows      | `mastra_workflow_snapshots` | Workflow state       |
+| Scorers        | `mastra_scorers`            | Evaluation data      |
+| Fallback       | `mastra_documents`          | Unknown tables       |
+
+### Architecture
+
+All typed tables include:
+
+- An `id` field for Mastra's record ID (distinct from Convex's auto-generated `_id`)
+- A `by_record_id` index for efficient lookups by Mastra ID
+
+This design ensures compatibility with Mastra's storage contract while leveraging Convex's automatic indexing and real-time capabilities.
+
+### Environment Variables
+
+Set these environment variables for your deployment:
+
+- `CONVEX_URL` – Your Convex deployment URL
+- `CONVEX_ADMIN_KEY` – Admin authentication token (get from Convex dashboard)
+
+## Related
+
+- [Convex Vector Store](../vectors/convex)
+- [Convex Documentation](https://docs.convex.dev/)