@mastra/spanner 0.0.0 → 1.0.0-alpha.0

package/dist/storage/db/index.d.ts

@@ -0,0 +1,344 @@
+import { Spanner } from '@google-cloud/spanner';
+import type { Database, Transaction } from '@google-cloud/spanner';
+import { MastraBase } from '@mastra/core/base';
+import type { StorageColumn, TABLE_NAMES, CreateIndexOptions, IndexInfo, StorageIndexStats } from '@mastra/core/storage';
+export type { CreateIndexOptions, IndexInfo, StorageIndexStats };
+/**
+ * Controls whether `init()` is allowed to apply schema changes.
+ *
+ * - `'sync'` (default): the adapter creates missing tables, columns, and
+ *   indexes during `init()`. This is the historical behavior.
+ * - `'validate'`: the adapter applies no DDL during `init()` and instead
+ *   verifies that every table, column (from `alterTable.ifNotExists`), and
+ *   default/custom index it would have created already exists. Missing
+ *   schema elements throw a typed user error.
+ *
+ * `'validate'` is intended for environments where another process (Terraform,
+ * Liquibase, a release pipeline, etc.) owns the schema and Mastra should only
+ * verify that the live database matches what the adapter expects.
+ */
+export type SpannerInitMode = 'sync' | 'validate';
+/**
+ * Configuration for standalone domain usage.
+ * Accepts either:
+ *   1. A pre-configured `database` (the domain reuses it as-is), or
+ *   2. Connection details from which the domain creates a Spanner client internally.
+ */
+export type SpannerDomainConfig = SpannerDomainDatabaseConfig | SpannerDomainConnectionConfig;
+/**
+ * Reuse an existing Spanner Database handle.
+ */
+export interface SpannerDomainDatabaseConfig {
+    database: Database;
+    /** Custom indexes to create for this domain's tables */
+    indexes?: CreateIndexOptions[];
+    /** When true, skips creation of default indexes */
+    skipDefaultIndexes?: boolean;
+    /** See {@link SpannerInitMode}. Defaults to `'sync'`. */
+    initMode?: SpannerInitMode;
+    /**
+     * When true, versioned domains (agents / skills / prompt-blocks /
+     * mcp-clients / mcp-servers / scorer-definitions) sweep orphaned draft
+     * thin-row records during `init()`  i.e. drafts whose paired version row
+     * was never written. Useful for cleaning up after process crashes that
+     * pre-date the transactional `create()` rewrite, or for environments
+     * where data integrity outweighs the small startup cost.
+     * @default false
+     */
+    cleanupStaleDraftsOnStartup?: boolean;
+    /**
+     * Maximum acceptable staleness (in milliseconds) for read-only dashboard
+     * queries in the observability domain (metrics list / aggregates /
+     * breakdowns / time-series / percentiles / discovery). When > 0, these
+     * reads are issued as single-use read-only transactions with
+     * `maxStaleness`, which lets Spanner serve them from any replica that has
+     * data at least that fresh — they stop contending with leader writes and
+     * can be routed to a closer replica.
+     *
+     * Default is 0 (strong reads) for backwards compatibility and to keep
+     * write-then-read paths in tests deterministic. For real dashboards,
+     * 10000 (10 s) is a common sweet spot.
+     * @default 0
+     */
+    dashboardStalenessMs?: number;
+    /**
+     * When true (the default), the observability domain's metric methods
+     * (`batchCreateMetrics`, `listMetrics`, `getMetricAggregate`, etc.) throw
+     * the base-class `*_NOT_IMPLEMENTED` errors and the metrics table is not
+     * created during `init()`. The `MastraStorageExporter` treats these
+     * errors as a signal to silently drop metric emissions, which is the
+     * recommended default for Spanner deployments: Spanner is row-oriented
+     * and OLTP-shaped, which makes it a poor fit for the high-volume,
+     * write-heavy, scan-heavy metrics workload. Pair Spanner spans with a
+     * dedicated OLAP store for metrics (BigQuery, DuckDB, ClickHouse) via a
+     * `MastraCompositeStore`-level wrapper that fans out by signal.
+     *
+     * Set to `false` to opt back in to the Spanner metrics implementation.
+     * It is correct and bounded at small scale (sustained < ~50 metrics/sec,
+     * < 1 yr retention), but past that you will hit hot-tail write
+     * contention on the leading-name index and analytical queries will start
+     * competing with span writes for node CPU.
+     * @default true
+     */
+    disableMetrics?: boolean;
+}
+/**
+ * Create a Spanner client internally from connection details.
+ */
+export interface SpannerDomainConnectionConfig {
+    projectId: string;
+    instanceId: string;
+    databaseId: string;
+    /** Optional pass-through to the Spanner client constructor (auth, servicePath, etc.) */
+    spannerOptions?: ConstructorParameters<typeof Spanner>[0];
+    /** Custom indexes to create for this domain's tables */
+    indexes?: CreateIndexOptions[];
+    /** When true, skips creation of default indexes */
+    skipDefaultIndexes?: boolean;
+    /** See {@link SpannerInitMode}. Defaults to `'sync'`. */
+    initMode?: SpannerInitMode;
+    /** See {@link SpannerDomainDatabaseConfig.cleanupStaleDraftsOnStartup}. Defaults to `false`. */
+    cleanupStaleDraftsOnStartup?: boolean;
+    /** See {@link SpannerDomainDatabaseConfig.dashboardStalenessMs}. Defaults to `0`. */
+    dashboardStalenessMs?: number;
+    /** See {@link SpannerDomainDatabaseConfig.disableMetrics}. Defaults to `true`. */
+    disableMetrics?: boolean;
+}
+/**
+ * Resolves a SpannerDomainConfig into a concrete Database handle plus options.
+ */
+export declare function resolveSpannerConfig(config: SpannerDomainConfig): {
+    database: Database;
+    indexes?: CreateIndexOptions[];
+    skipDefaultIndexes?: boolean;
+    initMode?: SpannerInitMode;
+    cleanupStaleDraftsOnStartup?: boolean;
+    dashboardStalenessMs?: number;
+    disableMetrics?: boolean;
+    ownsClient: boolean;
+};
+/**
+ * Internal helper that performs all GoogleSQL Spanner work for the various domain
+ * implementations (memory, workflows, scores, background-tasks).
+ */
+export declare class SpannerDB extends MastraBase {
+    database: Database;
+    skipDefaultIndexes?: boolean;
+    /** See {@link SpannerInitMode}. Public so domains can branch on it for
+     *  domain-specific schema work that doesn't go through this class
+     *  (e.g. the workflows snapshotStatus generated column). */
+    readonly initMode: SpannerInitMode;
+    /** Public so versioned domains can decide whether to call their
+     *  cleanupStaleDrafts() helper during init(). Default false. */
+    readonly cleanupStaleDraftsOnStartup: boolean;
+    /** Cache of actual table columns: tableName -> Set<columnName> */
+    private tableColumnsCache;
+    constructor({ database, skipDefaultIndexes, initMode, cleanupStaleDraftsOnStartup, }: {
+        database: Database;
+        skipDefaultIndexes?: boolean;
+        initMode?: SpannerInitMode;
+        cleanupStaleDraftsOnStartup?: boolean;
+    });
+    /**
+     * Builds a typed user-facing error for validate-mode schema mismatches so
+     * operators get a clear signal that the externally-managed schema is out
+     * of date relative to what the adapter expects.
+     */
+    private validateError;
+    /** Returns the set of column names that actually exist in the database table. */
+    private getTableColumns;
+    /** Returns true if the named table exists. */
+    private tableExists;
+    /** Returns true if `column` exists on `table`. */
+    hasColumn(table: string, column: string): Promise<boolean>;
+    /** Returns true if the named index exists. */
+    private indexExists;
+    /**
+     * Filter a record to only contain columns that exist in the live database table.
+     * Unknown columns are silently dropped to ensure forward compatibility with newer
+     * code writing columns the database hasn't been migrated to yet.
+     */
+    private filterRecordToKnownColumns;
+    protected getDefaultLiteral(type: StorageColumn['type']): string;
+    /** Build the column definition fragment for a CREATE TABLE statement. */
+    private buildColumnDefinition;
+    /** Apply DDL statements via `database.updateSchema` and wait for the operation. */
+    private runDdl;
+    /**
+     * Run a single DML statement either inside the provided transaction or by
+     * starting a new short-lived read-write transaction. Spanner's `Database`
+     * surface exposes only `run` (read-only); DML must always go through a
+     * transaction.
+     *
+     * Auto-retries on `ABORTED` (gRPC code 10)  Spanner aborts read-write
+     * transactions when they conflict with another, and the official guidance is
+     * to retry from the start. The emulator hits this much more often than
+     * managed Spanner because it serializes all read-write work.
+     */
+    runDml(request: {
+        sql: string;
+        params?: Record<string, any>;
+        types?: Record<string, any>;
+    }, transaction?: Transaction): Promise<number>;
+    /**
+     * Retries `fn` on Spanner ABORTED errors with exponential backoff.
+     * Caps at 5 attempts (~1.5s total backoff) before surfacing the error.
+     *
+     * Public so domain implementations can wrap their own
+     * `database.runTransactionAsync` calls when running concurrent writes.
+     */
+    runWithAbortRetry<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Determine the primary-key column list for a table. Some core tables (like
+     * `mastra_workflow_snapshot`) don't carry a single-column PK in the schema,
+     * so we hardcode known composite PKs here.
+     */
+    private getPrimaryKeyColumns;
+    private validateTableSchema;
+    createTable({ tableName, schema, }: {
+        tableName: TABLE_NAMES;
+        schema: Record<string, StorageColumn>;
+    }): Promise<void>;
+    /**
+     * Adds columns from `schema` that don't yet exist on the table.
+     * Useful for forward-compatible schema migrations.
+     */
+    alterTable({ tableName, schema, ifNotExists, }: {
+        tableName: TABLE_NAMES;
+        schema: Record<string, StorageColumn>;
+        ifNotExists: string[];
+    }): Promise<void>;
+    dropTable({ tableName }: {
+        tableName: TABLE_NAMES;
+    }): Promise<void>;
+    /** Spanner has no TRUNCATE  fall back to `DELETE WHERE TRUE`. */
+    clearTable({ tableName }: {
+        tableName: TABLE_NAMES;
+    }): Promise<void>;
+    /**
+     * Converts a JS value into the form Spanner expects for the column.
+     *  - jsonb: serialize to JSON string (caller must pass type 'json' in `types`).
+     *  - integer/bigint: pass through (numbers are accepted; Spanner will coerce).
+     *  - timestamp: ISO string when given a Date.
+     *  - boolean: pass through as boolean.
+     *  - text/uuid: stringify objects (legacy callers pass already-stringified JSON).
+     */
+    prepareValue(value: any, columnName: string, tableName: TABLE_NAMES): any;
+    /**
+     * Convert a value into the shape the Spanner Mutations API expects for the
+     * given column. Mutations encoding differs from DML in three places:
+     *
+     *  - JSON columns: the codec serializes plain JS objects with
+     *    `JSON.stringify`, but it encodes arrays as protobuf `list_value`,
+     *    which the server rejects for JSON-typed columns
+     *    ("Could not parse list_value … as JSON"). Pre-stringifying every
+     *    JSON value sidesteps that fork.
+     *  - FLOAT64 columns: whole-number JS values like `100` get either
+     *    INT64-inferred or string-encoded by the client when sent as a bare
+     *    number — the server then refuses them. `Spanner.float()` is the
+     *    documented escape hatch.
+     *  - TIMESTAMP columns: the codec already handles `Date` instances via
+     *    `.toJSON()`, so we pass them through as-is (DML's `prepareValue`
+     *    converts to an ISO string because DML wants `'timestamp'` type
+     *    hints; mutations don't take per-row hints).
+     *
+     * Everything else (text/uuid/bool/int) goes through `prepareValue` for
+     * parity with the DML path.
+     */
+    prepareValueForMutation(value: any, columnName: string, tableName: TABLE_NAMES): any;
+    insert({ tableName, record, transaction, }: {
+        tableName: TABLE_NAMES;
+        record: Record<string, any>;
+        transaction?: Transaction;
+    }): Promise<void>;
+    /**
+     * INSERT OR UPDATE upsert. Spanner cannot emit RETURNING-style results from
+     * INSERT OR UPDATE so callers must re-load the row when they need the post-write
+     * state.
+     */
+    upsert({ tableName, record, transaction, }: {
+        tableName: TABLE_NAMES;
+        record: Record<string, any>;
+        transaction?: Transaction;
+    }): Promise<void>;
+    update({ tableName, keys, data, transaction, }: {
+        tableName: TABLE_NAMES;
+        keys: Record<string, any>;
+        data: Record<string, any>;
+        transaction?: Transaction;
+    }): Promise<void>;
+    batchInsert({ tableName, records }: {
+        tableName: TABLE_NAMES;
+        records: Record<string, any>[];
+    }): Promise<void>;
+    batchUpdate({ tableName, updates, }: {
+        tableName: TABLE_NAMES;
+        updates: Array<{
+            keys: Record<string, any>;
+            data: Record<string, any>;
+        }>;
+    }): Promise<void>;
+    batchDelete({ tableName, keys }: {
+        tableName: TABLE_NAMES;
+        keys: Record<string, any>[];
+    }): Promise<void>;
+    /**
+     * Binds a single (column, value) pair into the SQL conditions/params/types
+     * accumulators and returns the next available parameter index.
+     *
+     * The previous version of this helper accepted `i` as a primitive argument
+     * and used `i++` internally, which only mutated the local copy  every
+     * call ended up emitting `@p0`. Returning the new counter value forces
+     * callers to thread the index forward and makes that footgun impossible.
+     */
+    private aggregateParams;
+    load<R>({ tableName, keys }: {
+        tableName: TABLE_NAMES;
+        keys: Record<string, any>;
+    }): Promise<R | null>;
+    /**
+     * Convert a raw Spanner JSON row into the storage layer's expected shape.
+     * Handles JSON-string values, timestamp strings, and bigint integers returned
+     * by the Spanner client.
+     */
+    transformRow<T = Record<string, any>>(tableName: TABLE_NAMES, row: Record<string, any>): T;
+    /**
+     * Build a parameterized WHERE fragment from a filter object.
+     * Supports `_gte`/`_gt`/`_lte`/`_lt` suffixes, `$in` operator, array-as-IN,
+     * and `null` IS NULL comparisons.
+     */
+    prepareWhereClause(filters: Record<string, any>, tableName?: TABLE_NAMES): {
+        sql: string;
+        params: Record<string, any>;
+        types: Record<string, any>;
+    };
+    /**
+     * Reads an index from INFORMATION_SCHEMA and compares its table, column list
+     * (with ordering), and unique flag against the expected definition. Throws a
+     * typed VALIDATE_FAILED error when anything diverges so the operator can
+     * reconcile their externally-managed schema.
+     */
+    private validateIndexDefinition;
+    createIndex(options: CreateIndexOptions): Promise<void>;
+    /**
+     * Creates a batch of indexes, swallowing per-index failures with a logger
+     * warning. Two classes of failure ALWAYS propagate:
+     *
+     *  - validate-mode mismatches, so the operator sees the missing-index
+     *    error instead of a silent no-op;
+     *  - failures on `unique: true` indexes, because a unique index encodes a
+     *    data-integrity invariant (e.g. duplicate-version prevention). If we
+     *    swallowed those failures the invariant would silently not be in
+     *    force, so we surface the error and let init() abort.
+     *
+     * Non-unique indexes are best-effort: domains use this for both default
+     * and custom index creation, and the swallow behavior keeps `init()`
+     * resilient to transient races (another process creating the same index
+     * concurrently, etc.).
+     */
+    createIndexes(indexes: CreateIndexOptions[]): Promise<void>;
+    dropIndex(indexName: string): Promise<void>;
+    listIndexes(tableName?: string): Promise<IndexInfo[]>;
+    describeIndex(indexName: string): Promise<StorageIndexStats>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/storage/db/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/storage/db/index.ts"],"names":[],"mappings":"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"}

package/dist/storage/db/utils.d.ts

@@ -0,0 +1,27 @@
+import type { StorageColumn, TABLE_NAMES } from '@mastra/core/storage';
+/**
+ * Quote a Spanner identifier with backticks. GoogleSQL uses backticks for
+ * identifiers that may collide with reserved keywords.
+ */
+export declare function quoteIdent(name: string, kind?: string): string;
+/**
+ * Returns the GoogleSQL type literal corresponding to a storage column type.
+ */
+export declare function getSpannerType(type: StorageColumn['type']): string;
+/**
+ * Returns the @google-cloud/spanner param type spec for a storage column type.
+ * Used when binding `null` values where Spanner needs an explicit type hint.
+ */
+export declare function getSpannerParamType(type: StorageColumn['type'] | undefined): string;
+/**
+ * Look up the storage column definition for a (table, column) pair.
+ * Returns undefined for columns not defined in the schema (e.g. internal columns).
+ */
+export declare function getColumnDef(table: TABLE_NAMES, column: string): StorageColumn | undefined;
+/**
+ * Returns true if the value is the `$in` operator object used by storage filters.
+ */
+export declare function isInOperator(value: unknown): value is {
+    $in: unknown[];
+};
+//# sourceMappingURL=utils.d.ts.map

package/dist/storage/db/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/storage/db/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAIvE;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,SAAe,GAAG,MAAM,CAGpE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,MAAM,CAqBlE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,GAAG,MAAM,CAkBnF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAE1F;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI;IAAE,GAAG,EAAE,OAAO,EAAE,CAAA;CAAE,CAIxE"}

package/dist/storage/domains/agents/index.d.ts

@@ -0,0 +1,44 @@
+import { AgentsStorage } from '@mastra/core/storage';
+import type { AgentVersion, CreateIndexOptions, CreateVersionInput, ListVersionsInput, ListVersionsOutput, StorageAgentType, StorageCreateAgentInput, StorageListAgentsInput, StorageListAgentsOutput, StorageUpdateAgentInput } from '@mastra/core/storage';
+import type { SpannerDomainConfig } from '../../db/index.js';
+export declare class AgentsSpanner extends AgentsStorage {
+    private database;
+    private db;
+    private readonly skipDefaultIndexes?;
+    private readonly indexes?;
+    static readonly MANAGED_TABLES: readonly ["mastra_agents", "mastra_agent_versions"];
+    constructor(config: SpannerDomainConfig);
+    init(): Promise<void>;
+    /**
+     * Sweeps orphaned draft thin-rows whose paired version row was never written.
+     * Skipped under `initMode: 'validate'` because that mode owns the schema and
+     * data externally and must never issue destructive DML.
+     */
+    private cleanupStaleDrafts;
+    getDefaultIndexDefinitions(): CreateIndexOptions[];
+    createDefaultIndexes(): Promise<void>;
+    createCustomIndexes(): Promise<void>;
+    dangerouslyClearAll(): Promise<void>;
+    private parseAgentRow;
+    /** Coerces stored instructions (string or JSON-stringified array of blocks) back to its API shape. */
+    private deserializeInstructions;
+    private serializeInstructions;
+    private parseVersionRow;
+    getById(id: string): Promise<StorageAgentType | null>;
+    create(input: {
+        agent: StorageCreateAgentInput;
+    }): Promise<StorageAgentType>;
+    update(input: StorageUpdateAgentInput): Promise<StorageAgentType>;
+    /** Removes an agent and all its versions atomically in a single transaction. */
+    delete(id: string): Promise<void>;
+    list(args?: StorageListAgentsInput): Promise<StorageListAgentsOutput>;
+    createVersion(input: CreateVersionInput): Promise<AgentVersion>;
+    getVersion(id: string): Promise<AgentVersion | null>;
+    getVersionByNumber(agentId: string, versionNumber: number): Promise<AgentVersion | null>;
+    getLatestVersion(agentId: string): Promise<AgentVersion | null>;
+    listVersions(input: ListVersionsInput): Promise<ListVersionsOutput>;
+    deleteVersion(id: string): Promise<void>;
+    deleteVersionsByParentId(entityId: string): Promise<void>;
+    countVersions(agentId: string): Promise<number>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/storage/domains/agents/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/storage/domains/agents/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,aAAa,EAQd,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAEV,YAAY,EACZ,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACxB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AA2BpD,qBAAa,aAAc,SAAQ,aAAa;IAC9C,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,EAAE,CAAY;IACtB,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAU;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAuB;IAEhD,MAAM,CAAC,QAAQ,CAAC,cAAc,sDAAiD;gBAEnE,MAAM,EAAE,mBAAmB;IAUjC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ3B;;;;OAIG;YACW,kBAAkB;IAmBhC,0BAA0B,IAAI,kBAAkB,EAAE;IAwB5C,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC;IAKrC,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAKpC,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAK1C,OAAO,CAAC,aAAa;IAsBrB,sGAAsG;IACtG,OAAO,CAAC,uBAAuB;IAc/B,OAAO,CAAC,qBAAqB;IAK7B,OAAO,CAAC,eAAe;IA8BjB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAuBrD,MAAM,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,uBAAuB,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA0F5E,MAAM,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAmDvE,gFAAgF;IAC1E,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqCjC,IAAI,CAAC,IAAI,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAgGrE,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC;IA0C/D,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAuBpD,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IA0BxF,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IA0B/D,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA+DnE,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBxC,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBzD,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAqBtD"}

package/dist/storage/domains/background-tasks/index.d.ts

@@ -0,0 +1,27 @@
+import type { BackgroundTask, TaskFilter, TaskListResult, UpdateBackgroundTask } from '@mastra/core/background-tasks';
+import type { CreateIndexOptions } from '@mastra/core/storage';
+import { BackgroundTasksStorage } from '@mastra/core/storage';
+import type { SpannerDomainConfig } from '../../db/index.js';
+export declare class BackgroundTasksSpanner extends BackgroundTasksStorage {
+    private database;
+    private db;
+    private skipDefaultIndexes?;
+    private indexes?;
+    static readonly MANAGED_TABLES: readonly ["mastra_background_tasks"];
+    constructor(config: SpannerDomainConfig);
+    init(): Promise<void>;
+    getDefaultIndexDefinitions(): CreateIndexOptions[];
+    createDefaultIndexes(): Promise<void>;
+    createCustomIndexes(): Promise<void>;
+    dangerouslyClearAll(): Promise<void>;
+    private tableName;
+    createTask(task: BackgroundTask): Promise<void>;
+    updateTask(taskId: string, update: UpdateBackgroundTask): Promise<void>;
+    getTask(taskId: string): Promise<BackgroundTask | null>;
+    listTasks(filter: TaskFilter): Promise<TaskListResult>;
+    deleteTask(taskId: string): Promise<void>;
+    deleteTasks(filter: TaskFilter): Promise<void>;
+    getRunningCount(): Promise<number>;
+    getRunningCountByAgent(agentId: string): Promise<number>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/storage/domains/background-tasks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/storage/domains/background-tasks/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,cAAc,EAEd,UAAU,EACV,cAAc,EACd,oBAAoB,EACrB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EACL,sBAAsB,EAIvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AA2EpD,qBAAa,sBAAuB,SAAQ,sBAAsB;IAChE,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,EAAE,CAAY;IACtB,OAAO,CAAC,kBAAkB,CAAC,CAAU;IACrC,OAAO,CAAC,OAAO,CAAC,CAAuB;IAEvC,MAAM,CAAC,QAAQ,CAAC,cAAc,uCAAqC;gBAEvD,MAAM,EAAE,mBAAmB;IAWjC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAS3B,0BAA0B,IAAI,kBAAkB,EAAE;IAiD5C,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC;IAKrC,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAKpC,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAI1C,OAAO,CAAC,SAAS;IAIX,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IA2B/C,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAcvE,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAWvD,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC;IAgItD,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOzC,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAsE9C,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC;IAQlC,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAQ/D"}

package/dist/storage/domains/blobs/index.d.ts

@@ -0,0 +1,36 @@
+import { BlobStore } from '@mastra/core/storage';
+import type { StorageBlobEntry } from '@mastra/core/storage';
+import type { SpannerDomainConfig } from '../../db/index.js';
+/**
+ * Content-addressable blob store backed by Spanner. Blobs are keyed by their
+ * SHA-256 hash; duplicate puts are no-ops thanks to `INSERT OR IGNORE`.
+ */
+export declare class BlobsSpanner extends BlobStore {
+    private database;
+    private db;
+    private readonly skipDefaultIndexes?;
+    private readonly indexes?;
+    static readonly MANAGED_TABLES: readonly ["mastra_skill_blobs"];
+    constructor(config: SpannerDomainConfig);
+    /** Creates the blobs table and any caller-supplied custom indexes. */
+    init(): Promise<void>;
+    /** Creates custom indexes routed to the blobs table; no-op when none supplied. */
+    createCustomIndexes(): Promise<void>;
+    /** Removes every row from the blobs table. Intended for tests. */
+    dangerouslyClearAll(): Promise<void>;
+    /** Decodes a raw Spanner row into the public `StorageBlobEntry` shape. */
+    private parseRow;
+    /** Stores a single blob keyed by its hash. Idempotent: a repeat hash is a no-op. */
+    put(entry: StorageBlobEntry): Promise<void>;
+    /** Fetches a blob by its hash, or `null` when no row matches. */
+    get(hash: string): Promise<StorageBlobEntry | null>;
+    /** Returns true when a blob with the given hash exists; cheaper than `get`. */
+    has(hash: string): Promise<boolean>;
+    /** Deletes the blob with the given hash. Returns true when a row was removed. */
+    delete(hash: string): Promise<boolean>;
+    /** Atomically stores a batch of blobs in a single Spanner transaction. */
+    putMany(entries: StorageBlobEntry[]): Promise<void>;
+    /** Fetches multiple blobs by hash in chunks of 500. Missing hashes are absent from the map. */
+    getMany(hashes: string[]): Promise<Map<string, StorageBlobEntry>>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/storage/domains/blobs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/storage/domains/blobs/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAA+D,MAAM,sBAAsB,CAAC;AAC9G,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAEjF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAIpD;;;GAGG;AACH,qBAAa,YAAa,SAAQ,SAAS;IACzC,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,EAAE,CAAY;IACtB,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAU;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAuB;IAEhD,MAAM,CAAC,QAAQ,CAAC,cAAc,kCAAgC;gBAElD,MAAM,EAAE,mBAAmB;IASvC,sEAAsE;IAChE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3B,kFAAkF;IAC5E,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAK1C,kEAAkE;IAC5D,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAI1C,0EAA0E;IAC1E,OAAO,CAAC,QAAQ;IAWhB,oFAAoF;IAC9E,GAAG,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAyCjD,iEAAiE;IAC3D,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAsBzD,+EAA+E;IACzE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAqBzC,iFAAiF;IAC3E,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAoB5C,0EAA0E;IACpE,OAAO,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAoDzD,+FAA+F;IACzF,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAgCxE"}

package/dist/storage/domains/mcp-clients/index.d.ts

@@ -0,0 +1,64 @@
+import { MCPClientsStorage } from '@mastra/core/storage';
+import type { CreateIndexOptions, StorageMCPClientType, StorageCreateMCPClientInput, StorageListMCPClientsInput, StorageListMCPClientsOutput, StorageUpdateMCPClientInput } from '@mastra/core/storage';
+import type { CreateMCPClientVersionInput, ListMCPClientVersionsInput, ListMCPClientVersionsOutput, MCPClientVersion } from '@mastra/core/storage/domains/mcp-clients';
+import type { SpannerDomainConfig } from '../../db/index.js';
+/**
+ * Spanner-backed storage for MCP-client definitions and their immutable versions.
+ * Mirrors the thin-record + versions pattern used by agents/skills/prompt-blocks.
+ */
+export declare class MCPClientsSpanner extends MCPClientsStorage {
+    private database;
+    private db;
+    private readonly skipDefaultIndexes?;
+    private readonly indexes?;
+    static readonly MANAGED_TABLES: readonly ["mastra_mcp_clients", "mastra_mcp_client_versions"];
+    constructor(config: SpannerDomainConfig);
+    /** Creates the MCP-client tables, indexes, and (when opted in) sweeps stale drafts. */
+    init(): Promise<void>;
+    /**
+     * Sweeps orphaned draft thin-rows whose paired version row was never written.
+     * Skipped under `initMode: 'validate'` (no destructive DML in validate mode).
+     */
+    private cleanupStaleDrafts;
+    /** Returns the default index set this domain creates during `init()`. */
+    getDefaultIndexDefinitions(): CreateIndexOptions[];
+    /** Creates the default indexes; no-op when `skipDefaultIndexes` was set. */
+    createDefaultIndexes(): Promise<void>;
+    /** Creates custom indexes routed to this domain's tables; no-op when none supplied. */
+    createCustomIndexes(): Promise<void>;
+    /** Removes every row from this domain's tables. Intended for tests. */
+    dangerouslyClearAll(): Promise<void>;
+    /** Decodes a raw Spanner thin-row into the public MCP-client shape. */
+    private parseClientRow;
+    /** Decodes a raw Spanner version row into the public version shape. */
+    private parseVersionRow;
+    /** Fetches the thin MCP-client record by id, or `null` when absent. */
+    getById(id: string): Promise<StorageMCPClientType | null>;
+    /** Atomically inserts a draft thin row + version 1 in a single Spanner transaction. */
+    create(input: {
+        mcpClient: StorageCreateMCPClientInput;
+    }): Promise<StorageMCPClientType>;
+    /** Updates thin-record fields (status, activeVersionId, authorId, metadata). */
+    update(input: StorageUpdateMCPClientInput): Promise<StorageMCPClientType>;
+    /** Removes an MCP client and all its versions atomically in a single transaction. */
+    delete(id: string): Promise<void>;
+    /** Paginated listing; defaults to `status='published'` so drafts never leak. */
+    list(args?: StorageListMCPClientsInput): Promise<StorageListMCPClientsOutput>;
+    /** Inserts a new immutable version row for an existing MCP client. */
+    createVersion(input: CreateMCPClientVersionInput): Promise<MCPClientVersion>;
+    /** Fetches a version row by its id, or `null` when absent. */
+    getVersion(id: string): Promise<MCPClientVersion | null>;
+    /** Fetches a specific version by `(mcpClientId, versionNumber)`. */
+    getVersionByNumber(mcpClientId: string, versionNumber: number): Promise<MCPClientVersion | null>;
+    /** Returns the highest-numbered version for an MCP client. */
+    getLatestVersion(mcpClientId: string): Promise<MCPClientVersion | null>;
+    /** Paginated listing of versions for a single MCP client. */
+    listVersions(input: ListMCPClientVersionsInput): Promise<ListMCPClientVersionsOutput>;
+    /** Deletes a single version row by id. */
+    deleteVersion(id: string): Promise<void>;
+    /** Deletes every version row belonging to the given MCP client. */
+    deleteVersionsByParentId(entityId: string): Promise<void>;
+    /** Returns the total number of version rows for the given MCP client. */
+    countVersions(mcpClientId: string): Promise<number>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/storage/domains/mcp-clients/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/storage/domains/mcp-clients/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,iBAAiB,EAMlB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,2BAA2B,EAC3B,0BAA0B,EAC1B,2BAA2B,EAC3B,2BAA2B,EAC5B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EACV,2BAA2B,EAC3B,0BAA0B,EAC1B,2BAA2B,EAC3B,gBAAgB,EACjB,MAAM,0CAA0C,CAAC;AAElD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAIpD;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,iBAAiB;IACtD,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,EAAE,CAAY;IACtB,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAU;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAuB;IAEhD,MAAM,CAAC,QAAQ,CAAC,cAAc,gEAA2D;gBAE7E,MAAM,EAAE,mBAAmB;IAUvC,uFAAuF;IACjF,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAS3B;;;OAGG;YACW,kBAAkB;IAmBhC,yEAAyE;IACzE,0BAA0B,IAAI,kBAAkB,EAAE;IAuBlD,4EAA4E;IACtE,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3C,uFAAuF;IACjF,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAK1C,uEAAuE;IACjE,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAK1C,uEAAuE;IACvE,OAAO,CAAC,cAAc;IAatB,uEAAuE;IACvE,OAAO,CAAC,eAAe;IAkBvB,uEAAuE;IACjE,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAuB/D,uFAAuF;IACjF,MAAM,CAAC,KAAK,EAAE;QAAE,SAAS,EAAE,2BAA2B,CAAA;KAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAiF9F,gFAAgF;IAC1E,MAAM,CAAC,KAAK,EAAE,2BAA2B,GAAG,OAAO,CAAC,oBAAoB,CAAC;IA+C/E,qFAAqF;IAC/E,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkCvC,gFAAgF;IAC1E,IAAI,CAAC,IAAI,CAAC,EAAE,0BAA0B,GAAG,OAAO,CAAC,2BAA2B,CAAC;IA6FnF,sEAAsE;IAChE,aAAa,CAAC,KAAK,EAAE,2BAA2B,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAgClF,8DAA8D;IACxD,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAuB9D,oEAAoE;IAC9D,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IA0BtG,8DAA8D;IACxD,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IA0B7E,6DAA6D;IACvD,YAAY,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,2BAA2B,CAAC;IA8D3F,0CAA0C;IACpC,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB9C,mEAAmE;IAC7D,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB/D,yEAAyE;IACnE,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAqB1D"}

package/dist/storage/domains/mcp-servers/index.d.ts

@@ -0,0 +1,64 @@
+import { MCPServersStorage } from '@mastra/core/storage';
+import type { CreateIndexOptions, StorageMCPServerType, StorageCreateMCPServerInput, StorageListMCPServersInput, StorageListMCPServersOutput, StorageUpdateMCPServerInput } from '@mastra/core/storage';
+import type { CreateMCPServerVersionInput, ListMCPServerVersionsInput, ListMCPServerVersionsOutput, MCPServerVersion } from '@mastra/core/storage/domains/mcp-servers';
+import type { SpannerDomainConfig } from '../../db/index.js';
+/**
+ * Spanner-backed storage for MCP-server definitions and their immutable versions.
+ * Mirrors the thin-record + versions pattern used by agents/skills/prompt-blocks.
+ */
+export declare class MCPServersSpanner extends MCPServersStorage {
+    private database;
+    private db;
+    private readonly skipDefaultIndexes?;
+    private readonly indexes?;
+    static readonly MANAGED_TABLES: readonly ["mastra_mcp_servers", "mastra_mcp_server_versions"];
+    constructor(config: SpannerDomainConfig);
+    /** Creates the MCP-server tables, indexes, and (when opted in) sweeps stale drafts. */
+    init(): Promise<void>;
+    /**
+     * Sweeps orphaned draft thin-rows whose paired version row was never written.
+     * Skipped under `initMode: 'validate'` (no destructive DML in validate mode).
+     */
+    private cleanupStaleDrafts;
+    /** Returns the default index set this domain creates during `init()`. */
+    getDefaultIndexDefinitions(): CreateIndexOptions[];
+    /** Creates the default indexes; no-op when `skipDefaultIndexes` was set. */
+    createDefaultIndexes(): Promise<void>;
+    /** Creates custom indexes routed to this domain's tables; no-op when none supplied. */
+    createCustomIndexes(): Promise<void>;
+    /** Removes every row from this domain's tables. Intended for tests. */
+    dangerouslyClearAll(): Promise<void>;
+    /** Decodes a raw Spanner thin-row into the public MCP-server shape. */
+    private parseServerRow;
+    /** Decodes a raw Spanner version row into the public version shape. */
+    private parseVersionRow;
+    /** Fetches the thin MCP-server record by id, or `null` when absent. */
+    getById(id: string): Promise<StorageMCPServerType | null>;
+    /** Atomically inserts a draft thin row + version 1 in a single Spanner transaction. */
+    create(input: {
+        mcpServer: StorageCreateMCPServerInput;
+    }): Promise<StorageMCPServerType>;
+    /** Updates thin-record fields (status, activeVersionId, authorId, metadata). */
+    update(input: StorageUpdateMCPServerInput): Promise<StorageMCPServerType>;
+    /** Removes an MCP server and all its versions atomically in a single transaction. */
+    delete(id: string): Promise<void>;
+    /** Paginated listing; defaults to `status='published'` so drafts never leak. */
+    list(args?: StorageListMCPServersInput): Promise<StorageListMCPServersOutput>;
+    /** Inserts a new immutable version row for an existing MCP server. */
+    createVersion(input: CreateMCPServerVersionInput): Promise<MCPServerVersion>;
+    /** Fetches a version row by its id, or `null` when absent. */
+    getVersion(id: string): Promise<MCPServerVersion | null>;
+    /** Fetches a specific version by `(mcpServerId, versionNumber)`. */
+    getVersionByNumber(mcpServerId: string, versionNumber: number): Promise<MCPServerVersion | null>;
+    /** Returns the highest-numbered version for an MCP server. */
+    getLatestVersion(mcpServerId: string): Promise<MCPServerVersion | null>;
+    /** Paginated listing of versions for a single MCP server. */
+    listVersions(input: ListMCPServerVersionsInput): Promise<ListMCPServerVersionsOutput>;
+    /** Deletes a single version row by id. */
+    deleteVersion(id: string): Promise<void>;
+    /** Deletes every version row belonging to the given MCP server. */
+    deleteVersionsByParentId(entityId: string): Promise<void>;
+    /** Returns the total number of version rows for the given MCP server. */
+    countVersions(mcpServerId: string): Promise<number>;
+}
+//# sourceMappingURL=index.d.ts.map