@fusebase/fusebase-gate-sdk 2.2.2-sdk.26 → 2.2.2-sdk.28

package/dist/apis/IsolatedStoresApi.d.ts

@@ -11,7 +11,7 @@ export declare class IsolatedStoresApi {
     constructor(client: Client);
     /**
      * Apply SQL migrations
-     * Applies pending postgres migrations from an ordered migration bundle into the selected stage database. For prod, gate creates a checkpoint automatically before applying pending migrations. Applied history must match the bundle prefix exactly; drifted stages are rejected. Never change name, checksum, or sql for migrations already in the journal — ship fixes as new higher versions (see MCP prompt isolatedSqlMigrationDiscipline). MCP clients often cap tool_call JSON body size (on the order of a few thousand characters); the request includes full SQL text for every bundle version cumulatively, so large bundles may fail or truncate in chat-only MCP. Keep canonical SQL plus a manifest for apply from SDK, CLI, or any non-MCP caller without a tight body-size limit.
+     * Workflow: call `getIsolatedStoreSqlMigrationStatus` with the **same** bundle, confirm `canApply` and expected `pendingCount`, then apply. Applies pending postgres migrations from an ordered bundle into the selected stage database. For prod, gate creates a checkpoint automatically before applying pending migrations. Applied history must match the bundle prefix exactly; drift returns HTTP 409 with `data.issues` (version/name/checksum, journal vs bundle). Optional `dryRun: true` performs the same prefix + optimistic-lock checks as apply but does not run SQL or write the journal (returns `dryRun: true` and the computed status). Optional `expectedLastAppliedVersion` / `expectedLastAppliedChecksum` reject with HTTP 409 before migrations run when the journal tail changed since the client's last status snapshot. Never change name, checksum, or sql for migrations already in the journal — ship fixes as new higher versions (see MCP prompt isolatedSqlMigrationDiscipline). MCP clients often cap tool_call JSON body size (on the order of a few thousand characters); the request includes full SQL text for every bundle version cumulatively, so large bundles may fail or truncate in chat-only MCP. Keep canonical SQL plus a manifest for apply from SDK, CLI, or any non-MCP caller without a tight body-size limit.
      */
     applyIsolatedStoreSqlMigrations(params: {
         path: {
@@ -216,7 +216,7 @@ export declare class IsolatedStoresApi {
     }): Promise<IsolatedStoreNoSqlStatsResponseContract>;
     /**
      * Get SQL migration status
-     * Compares an ordered SQL migration bundle with the migration journal stored inside the selected postgres stage database. Returns applied migrations, pending migrations, and drift issues when the applied history no longer matches the bundle prefix. Load MCP prompt isolatedSqlMigrationDiscipline (required with isolatedSql/isolated groups) before interpreting drift — do not edit applied migration metadata or the journal to force a match.
+     * Compares an ordered SQL migration bundle with the migration journal stored inside the selected postgres stage database. Returns applied migrations, pending migrations, drift issues when the applied history no longer matches the bundle prefix, and `canApply` / `structuredIssues` for automation. Prefer calling this immediately before `applyIsolatedStoreSqlMigrations` with the same bundle. Optional request fields `expectedLastAppliedVersion` / `expectedLastAppliedChecksum` (same semantics as apply) reject with HTTP 409 when the live journal tail disagrees — useful as a cheap preflight without sending `dryRun` on apply. Load MCP prompt isolatedSqlMigrationDiscipline (required with isolatedSql/isolated groups) before interpreting drift — do not edit applied migration metadata or the journal to force a match.
      */
     getIsolatedStoreSqlMigrationStatus(params: {
         path: {

package/dist/apis/IsolatedStoresApi.js

@@ -13,7 +13,7 @@ class IsolatedStoresApi {
     }
     /**
      * Apply SQL migrations
-     * Applies pending postgres migrations from an ordered migration bundle into the selected stage database. For prod, gate creates a checkpoint automatically before applying pending migrations. Applied history must match the bundle prefix exactly; drifted stages are rejected. Never change name, checksum, or sql for migrations already in the journal — ship fixes as new higher versions (see MCP prompt isolatedSqlMigrationDiscipline). MCP clients often cap tool_call JSON body size (on the order of a few thousand characters); the request includes full SQL text for every bundle version cumulatively, so large bundles may fail or truncate in chat-only MCP. Keep canonical SQL plus a manifest for apply from SDK, CLI, or any non-MCP caller without a tight body-size limit.
+     * Workflow: call `getIsolatedStoreSqlMigrationStatus` with the **same** bundle, confirm `canApply` and expected `pendingCount`, then apply. Applies pending postgres migrations from an ordered bundle into the selected stage database. For prod, gate creates a checkpoint automatically before applying pending migrations. Applied history must match the bundle prefix exactly; drift returns HTTP 409 with `data.issues` (version/name/checksum, journal vs bundle). Optional `dryRun: true` performs the same prefix + optimistic-lock checks as apply but does not run SQL or write the journal (returns `dryRun: true` and the computed status). Optional `expectedLastAppliedVersion` / `expectedLastAppliedChecksum` reject with HTTP 409 before migrations run when the journal tail changed since the client's last status snapshot. Never change name, checksum, or sql for migrations already in the journal — ship fixes as new higher versions (see MCP prompt isolatedSqlMigrationDiscipline). MCP clients often cap tool_call JSON body size (on the order of a few thousand characters); the request includes full SQL text for every bundle version cumulatively, so large bundles may fail or truncate in chat-only MCP. Keep canonical SQL plus a manifest for apply from SDK, CLI, or any non-MCP caller without a tight body-size limit.
      */
     async applyIsolatedStoreSqlMigrations(params) {
         return this.client.request({
@@ -247,7 +247,7 @@ class IsolatedStoresApi {
     }
     /**
      * Get SQL migration status
-     * Compares an ordered SQL migration bundle with the migration journal stored inside the selected postgres stage database. Returns applied migrations, pending migrations, and drift issues when the applied history no longer matches the bundle prefix. Load MCP prompt isolatedSqlMigrationDiscipline (required with isolatedSql/isolated groups) before interpreting drift — do not edit applied migration metadata or the journal to force a match.
+     * Compares an ordered SQL migration bundle with the migration journal stored inside the selected postgres stage database. Returns applied migrations, pending migrations, drift issues when the applied history no longer matches the bundle prefix, and `canApply` / `structuredIssues` for automation. Prefer calling this immediately before `applyIsolatedStoreSqlMigrations` with the same bundle. Optional request fields `expectedLastAppliedVersion` / `expectedLastAppliedChecksum` (same semantics as apply) reject with HTTP 409 when the live journal tail disagrees — useful as a cheap preflight without sending `dryRun` on apply. Load MCP prompt isolatedSqlMigrationDiscipline (required with isolatedSql/isolated groups) before interpreting drift — do not edit applied migration metadata or the journal to force a match.
      */
     async getIsolatedStoreSqlMigrationStatus(params) {
         return this.client.request({

package/dist/types/isolated-store/isolated-store.d.ts

@@ -133,6 +133,37 @@ export interface IsolatedStoreSqlAppliedMigrationContract {
     appliedAt: string;
     appliedBy: string;
 }
+export type IsolatedStoreSqlMigrationIssueCodeContract = "isolated_sql_journal_longer_than_bundle" | "isolated_sql_version_mismatch" | "isolated_sql_name_mismatch" | "isolated_sql_checksum_mismatch" | "isolated_sql_journal_head_mismatch";
+export type IsolatedStoreSqlMigrationIssueFieldContract = "history_length" | "version" | "name" | "checksum" | "journal_head";
+/** Machine-readable drift detail; omits raw SQL (only safe fingerprints). */
+export interface IsolatedStoreSqlMigrationIssueContract {
+    code: IsolatedStoreSqlMigrationIssueCodeContract;
+    message: string;
+    /** Bundle migration version at the comparison index when relevant. */
+    version?: number | null;
+    field?: IsolatedStoreSqlMigrationIssueFieldContract;
+    /** Value from the migration journal (applied history). */
+    expected?: string | number | null;
+    /** Value from the submitted bundle. */
+    actual?: string | number | null;
+    journal?: {
+        version: number;
+        name: string;
+        checksum: string;
+    } | null;
+    bundle?: {
+        version: number;
+        name: string;
+        checksum: string;
+    } | null;
+    /** SHA-256 of the bundle entry SQL UTF-8 bytes (diagnostic; not raw SQL). */
+    bundleSqlContentSha256?: string | null;
+    /** Set when `expectedLastApplied*` optimistic locks fail (apply/status preflight). */
+    expectedLastAppliedVersion?: number | null;
+    actualLastAppliedVersion?: number | null;
+    expectedLastAppliedChecksum?: string | null;
+    actualLastAppliedChecksum?: string | null;
+}
 export interface IsolatedStoreSqlMigrationStatusContract {
     databaseName: string;
     schemaName: string;
@@ -142,23 +173,56 @@ export interface IsolatedStoreSqlMigrationStatusContract {
     appliedCount: number;
     pendingCount: number;
     isDrifted: boolean;
+    /** True when the bundle prefix matches the journal and pending migrations may run. */
+    canApply: boolean;
     issues: string[];
+    structuredIssues: IsolatedStoreSqlMigrationIssueContract[];
     appliedMigrations: IsolatedStoreSqlAppliedMigrationContract[];
     pendingMigrations: IsolatedStoreSqlMigrationBundleEntryContract[];
 }
 export interface GetIsolatedStoreSqlMigrationStatusRequestContract {
     schemaName?: IsolatedStoreSqlSchemaNameInQueryOptional;
     bundle: IsolatedStoreSqlMigrationBundleContract;
+    /** Same optimistic-lock semantics as `applyIsolatedStoreSqlMigrations`; HTTP 409 when the journal tail disagrees. */
+    expectedLastAppliedVersion?: number | null;
+    expectedLastAppliedChecksum?: string | null;
 }
 export interface ApplyIsolatedStoreSqlMigrationsRequestContract {
     schemaName?: IsolatedStoreSqlSchemaNameInQueryOptional;
     bundle: IsolatedStoreSqlMigrationBundleContract;
+    /**
+     * When true, runs the same journal/bundle prefix checks as apply (including optional
+     * expected-head validation) but does not execute SQL or write the journal.
+     */
+    dryRun?: boolean | null;
+    /**
+     * Optimistic lock: last applied migration version on the server must match.
+     * Omit to skip. Use `null` to require an empty journal (no rows applied).
+     */
+    expectedLastAppliedVersion?: number | null;
+    /**
+     * Optimistic lock: checksum of the last applied journal row must match.
+     * Omit to skip. Use `null` only together with an empty journal expectation.
+     */
+    expectedLastAppliedChecksum?: string | null;
 }
 export interface ApplyIsolatedStoreSqlMigrationsResponseContract {
     appliedCount: number;
     appliedVersions: number[];
     checkpointRevision?: IsolatedStoreRevisionContract | null;
     status: IsolatedStoreSqlMigrationStatusContract;
+    /** Present and true when the request used `dryRun` and no migrations were executed. */
+    dryRun?: boolean | null;
+}
+/** Documented shape of JSON error responses for migration state conflicts (HTTP 409). */
+export interface IsolatedStoreSqlMigrationConflictErrorBodyContract {
+    success: false;
+    message: string;
+    data: {
+        code: string;
+        errorCode: string;
+        issues?: IsolatedStoreSqlMigrationIssueContract[];
+    };
 }
 export interface IsolatedStoreSqlListTablesResponseContract {
     tables: IsolatedStoreSqlTableContract[];
@@ -455,6 +519,20 @@ export declare const IsolatedStoreScopeTypeContract: {
     readonly ParentRow: "parent_row";
     readonly ParentTable: "parent_table";
 };
+export declare const IsolatedStoreSqlMigrationIssueCodeContract: {
+    readonly IsolatedSqlJournalLongerThanBundle: "isolated_sql_journal_longer_than_bundle";
+    readonly IsolatedSqlVersionMismatch: "isolated_sql_version_mismatch";
+    readonly IsolatedSqlNameMismatch: "isolated_sql_name_mismatch";
+    readonly IsolatedSqlChecksumMismatch: "isolated_sql_checksum_mismatch";
+    readonly IsolatedSqlJournalHeadMismatch: "isolated_sql_journal_head_mismatch";
+};
+export declare const IsolatedStoreSqlMigrationIssueFieldContract: {
+    readonly HistoryLength: "history_length";
+    readonly Version: "version";
+    readonly Name: "name";
+    readonly Checksum: "checksum";
+    readonly JournalHead: "journal_head";
+};
 export declare const IsolatedStoreSqlFilterOperatorContract: {
     readonly Eq: "eq";
     readonly Ne: "ne";

package/dist/types/isolated-store/isolated-store.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IsolatedStoreNoSqlImportModeContract = exports.IsolatedStoreNoSqlSortDirectionContract = exports.IsolatedStoreNoSqlFilterOperatorContract = exports.IsolatedStoreSqlImportFormatContract = exports.IsolatedStoreSqlSortDirectionContract = exports.IsolatedStoreSqlFilterOperatorContract = exports.IsolatedStoreScopeTypeContract = exports.IsolatedStoreRevisionKindContract = exports.IsolatedStoreStageStatusContract = exports.IsolatedStoreStatusContract = exports.IsolatedStoreEngineContract = exports.IsolatedStoreTypeContract = void 0;
+exports.IsolatedStoreNoSqlImportModeContract = exports.IsolatedStoreNoSqlSortDirectionContract = exports.IsolatedStoreNoSqlFilterOperatorContract = exports.IsolatedStoreSqlImportFormatContract = exports.IsolatedStoreSqlSortDirectionContract = exports.IsolatedStoreSqlFilterOperatorContract = exports.IsolatedStoreSqlMigrationIssueFieldContract = exports.IsolatedStoreSqlMigrationIssueCodeContract = exports.IsolatedStoreScopeTypeContract = exports.IsolatedStoreRevisionKindContract = exports.IsolatedStoreStageStatusContract = exports.IsolatedStoreStatusContract = exports.IsolatedStoreEngineContract = exports.IsolatedStoreTypeContract = void 0;
 exports.IsolatedStoreTypeContract = {
     Sql: "sql",
     Nosql: "nosql"
@@ -34,6 +34,20 @@ exports.IsolatedStoreScopeTypeContract = {
     ParentRow: "parent_row",
     ParentTable: "parent_table"
 };
+exports.IsolatedStoreSqlMigrationIssueCodeContract = {
+    IsolatedSqlJournalLongerThanBundle: "isolated_sql_journal_longer_than_bundle",
+    IsolatedSqlVersionMismatch: "isolated_sql_version_mismatch",
+    IsolatedSqlNameMismatch: "isolated_sql_name_mismatch",
+    IsolatedSqlChecksumMismatch: "isolated_sql_checksum_mismatch",
+    IsolatedSqlJournalHeadMismatch: "isolated_sql_journal_head_mismatch"
+};
+exports.IsolatedStoreSqlMigrationIssueFieldContract = {
+    HistoryLength: "history_length",
+    Version: "version",
+    Name: "name",
+    Checksum: "checksum",
+    JournalHead: "journal_head"
+};
 exports.IsolatedStoreSqlFilterOperatorContract = {
     Eq: "eq",
     Ne: "ne",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fusebase/fusebase-gate-sdk",
-  "version": "2.2.2-sdk.26",
+  "version": "2.2.2-sdk.28",
   "description": "TypeScript SDK for Fusebase Gate APIs - Generated from contract introspection",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/release-notes/2.2.2-sdk.28.md

@@ -0,0 +1,9 @@
+# Release Notes 2.2.2-sdk.28
+
+- Current ref: `HEAD`
+- Previous tag: `v2.2.2-sdk.28`
+- Generated at: 2026-04-05T05:10:27.150Z
+
+## Included Drafts
+
+- None

package/release-notes/latest.md

@@ -1,8 +1,8 @@
-# Release Notes 2.2.2-sdk.26
+# Release Notes 2.2.2-sdk.28
 
 - Current ref: `HEAD`
-- Previous tag: `v2.2.2-sdk.26`
-- Generated at: 2026-04-05T04:29:27.130Z
+- Previous tag: `v2.2.2-sdk.28`
+- Generated at: 2026-04-05T05:10:27.150Z
 
 ## Included Drafts
 

package/release-notes/2.2.2-sdk.26.md

@@ -1,9 +0,0 @@
-# Release Notes 2.2.2-sdk.26
-
-- Current ref: `HEAD`
-- Previous tag: `v2.2.2-sdk.26`
-- Generated at: 2026-04-05T04:29:27.130Z
-
-## Included Drafts
-
-- None