hikoutei 0.2.0

package/dist/adapter/persistence/providers/mikro-orm/storage/MikroOrmSqliteAdapter.d.ts

@@ -0,0 +1,78 @@
+import type { AnyEntity, EntityClass, EntitySchema } from "@mikro-orm/core";
+import { MikroORM, SqliteDriver } from "@mikro-orm/sql";
+import type { Options, SqlEntityManager } from "@mikro-orm/sql";
+import type { SqlExecutor, SqlStorageAdapter, SqlStorageContext } from "../../../contracts/sql.js";
+/** MikroORM entity-manager type used by the Node SQLite dialect. */
+export type MikroOrmSqliteEntityManager = SqlEntityManager<SqliteDriver>;
+/** MikroORM root instance configured with the generic Node SQLite driver. */
+export type MikroOrmSqlite = MikroORM<SqliteDriver, MikroOrmSqliteEntityManager>;
+/** Entity metadata accepted by the SQLite-backed MikroORM integration. */
+export type MikroOrmSqliteEntity = string | EntityClass<AnyEntity> | EntitySchema;
+/** Optional MikroORM settings owned by the host application. */
+export type MikroOrmSqliteConfiguration = Omit<Partial<Options<SqliteDriver>>, "dbName" | "driver" | "driverOptions" | "entities">;
+/** Inputs for creating the SQLite ORM instance that typed-sheets will use. */
+export interface InitializeMikroOrmSqliteAdapterOptions {
+    /** SQLite database path, URI, or `:memory:` database name. */
+    readonly dbName: string;
+    /** Application entities managed by the dedicated Sheets-side MikroORM instance. */
+    readonly entities: readonly MikroOrmSqliteEntity[];
+    /** Optional MikroORM settings that do not select a different database or driver. */
+    readonly configuration?: MikroOrmSqliteConfiguration;
+}
+/**
+ * Adapter-specific transaction context for code that intentionally needs
+ * MikroORM entity lifecycle operations alongside typed-sheets storage SQL.
+ *
+ * Core storage must use `sql`; `entityManager` is an explicit escape hatch for
+ * integration code and never appears in the adapter-neutral contract.
+ */
+export interface MikroOrmSqliteTransaction extends SqlStorageContext {
+    readonly entityManager: MikroOrmSqliteEntityManager;
+}
+/**
+ * Connects typed-sheets storage SQL to one MikroORM-managed SQLite database.
+ *
+ * The adapter never opens a second `node:sqlite` connection. Raw storage SQL
+ * and MikroORM entity changes therefore share the same transaction context.
+ */
+export declare class MikroOrmSqliteAdapter implements SqlStorageAdapter {
+    private readonly orm;
+    constructor(orm: MikroOrmSqlite);
+    /** Creates an isolated MikroORM manager for one typed-sheets EntityManager facade. */
+    forkEntityManager(): MikroOrmSqliteEntityManager;
+    /**
+     * Creates a SQL executor bound to the supplied manager's current transaction.
+     *
+     * This is adapter-specific plumbing for the typed-sheets ORM facade; callers
+     * should use the facade rather than mixing raw entity and sync writes.
+     */
+    createSqlExecutor(entityManager: MikroOrmSqliteEntityManager): SqlExecutor;
+    /** Runs a read through a fresh EntityManager to avoid stale identity-map state. */
+    read<T>(operation: (context: SqlStorageContext) => Promise<T>): Promise<T>;
+    /** Runs adapter-neutral storage work in one MikroORM transaction. */
+    transaction<T>(operation: (context: SqlStorageContext) => Promise<T>): Promise<T>;
+    /**
+     * Runs integration work that needs both the active MikroORM EntityManager and
+     * the transaction-bound storage SQL executor.
+     */
+    transactional<T>(operation: (context: MikroOrmSqliteTransaction) => Promise<T>): Promise<T>;
+    /** Closes the SQLite connection owned by this adapter. */
+    close(force?: boolean): Promise<void>;
+    /**
+     * Creates missing entity tables and applies only non-destructive entity-schema updates.
+     *
+     * This is intentionally explicit instead of running during adapter creation:
+     * a production process must opt into changing its SQLite schema at startup.
+     */
+    migrateEntitySchema(): Promise<void>;
+}
+/** Creates a typed-sheets storage adapter around an application-owned MikroORM instance. */
+export declare function createMikroOrmSqliteAdapter(orm: MikroOrmSqlite): MikroOrmSqliteAdapter;
+/**
+ * Opens the dedicated SQLite MikroORM instance used for Sheets-backed entities.
+ *
+ * This intentionally creates a separate ORM from any application-owned MySQL
+ * instance, so Sheet entities cannot accidentally write to the primary database.
+ */
+export declare function initializeMikroOrmSqliteAdapter(options: InitializeMikroOrmSqliteAdapterOptions): Promise<MikroOrmSqliteAdapter>;
+//# sourceMappingURL=MikroOrmSqliteAdapter.d.ts.map

package/dist/adapter/persistence/providers/mikro-orm/storage/MikroOrmSqliteAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MikroOrmSqliteAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/adapter/persistence/providers/mikro-orm/storage/MikroOrmSqliteAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,WAAW,EACX,YAAY,EAEb,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,QAAQ,EAER,YAAY,EACb,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEhE,OAAO,KAAK,EACV,WAAW,EAIX,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,2BAA2B,CAAC;AAEnC,oEAAoE;AACpE,MAAM,MAAM,2BAA2B,GAAG,gBAAgB,CAAC,YAAY,CAAC,CAAC;AAEzE,6EAA6E;AAC7E,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,YAAY,EAAE,2BAA2B,CAAC,CAAC;AAEjF,0EAA0E;AAC1E,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC,GAAG,YAAY,CAAC;AAElF,gEAAgE;AAChE,MAAM,MAAM,2BAA2B,GAAG,IAAI,CAC5C,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,EAC9B,QAAQ,GAAG,QAAQ,GAAG,eAAe,GAAG,UAAU,CACnD,CAAC;AAEF,8EAA8E;AAC9E,MAAM,WAAW,sCAAsC;IACrD,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACnD,oFAAoF;IACpF,QAAQ,CAAC,aAAa,CAAC,EAAE,2BAA2B,CAAC;CACtD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,yBAA0B,SAAQ,iBAAiB;IAClE,QAAQ,CAAC,aAAa,EAAE,2BAA2B,CAAC;CACrD;AAED;;;;;GAKG;AACH,qBAAa,qBAAsB,YAAW,iBAAiB;IACjD,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,cAAc;IAEhD,sFAAsF;IACtF,iBAAiB,IAAI,2BAA2B;IAIhD;;;;;OAKG;IACH,iBAAiB,CAAC,aAAa,EAAE,2BAA2B,GAAG,WAAW;IAI1E,mFAAmF;IAC7E,IAAI,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAKhF,qEAAqE;IAC/D,WAAW,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAIvF;;;OAGG;IACG,aAAa,CAAC,CAAC,EACnB,SAAS,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,OAAO,CAAC,CAAC,CAAC,GAC5D,OAAO,CAAC,CAAC,CAAC;IAMb,0DAA0D;IACpD,KAAK,CAAC,KAAK,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzC;;;;;OAKG;IACG,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;CAM3C;AAED,4FAA4F;AAC5F,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,cAAc,GAAG,qBAAqB,CAEtF;AAED;;;;;GAKG;AACH,wBAAsB,+BAA+B,CACnD,OAAO,EAAE,sCAAsC,GAC9C,OAAO,CAAC,qBAAqB,CAAC,CAShC"}

package/dist/adapter/persistence/providers/mikro-orm/storage/MikroOrmSqliteAdapter.js

@@ -0,0 +1,121 @@
+import { MikroORM, NodeSqliteDialect, SqliteDriver, } from "@mikro-orm/sql";
+/**
+ * Connects typed-sheets storage SQL to one MikroORM-managed SQLite database.
+ *
+ * The adapter never opens a second `node:sqlite` connection. Raw storage SQL
+ * and MikroORM entity changes therefore share the same transaction context.
+ */
+export class MikroOrmSqliteAdapter {
+    orm;
+    constructor(orm) {
+        this.orm = orm;
+    }
+    /** Creates an isolated MikroORM manager for one typed-sheets EntityManager facade. */
+    forkEntityManager() {
+        return this.orm.em.fork();
+    }
+    /**
+     * Creates a SQL executor bound to the supplied manager's current transaction.
+     *
+     * This is adapter-specific plumbing for the typed-sheets ORM facade; callers
+     * should use the facade rather than mixing raw entity and sync writes.
+     */
+    createSqlExecutor(entityManager) {
+        return new MikroOrmSqlExecutor(entityManager);
+    }
+    /** Runs a read through a fresh EntityManager to avoid stale identity-map state. */
+    async read(operation) {
+        const entityManager = this.forkEntityManager();
+        return operation(createStorageContext(entityManager));
+    }
+    /** Runs adapter-neutral storage work in one MikroORM transaction. */
+    async transaction(operation) {
+        return this.transactional(async (context) => operation(context));
+    }
+    /**
+     * Runs integration work that needs both the active MikroORM EntityManager and
+     * the transaction-bound storage SQL executor.
+     */
+    async transactional(operation) {
+        return this.orm.em.transactional(async (entityManager) => {
+            return operation(createMikroOrmTransaction(entityManager));
+        });
+    }
+    /** Closes the SQLite connection owned by this adapter. */
+    async close(force = false) {
+        await this.orm.close(force);
+    }
+    /**
+     * Creates missing entity tables and applies only non-destructive entity-schema updates.
+     *
+     * This is intentionally explicit instead of running during adapter creation:
+     * a production process must opt into changing its SQLite schema at startup.
+     */
+    async migrateEntitySchema() {
+        await this.orm.schema.update({
+            safe: true,
+            dropTables: false,
+        });
+    }
+}
+/** Creates a typed-sheets storage adapter around an application-owned MikroORM instance. */
+export function createMikroOrmSqliteAdapter(orm) {
+    return new MikroOrmSqliteAdapter(orm);
+}
+/**
+ * Opens the dedicated SQLite MikroORM instance used for Sheets-backed entities.
+ *
+ * This intentionally creates a separate ORM from any application-owned MySQL
+ * instance, so Sheet entities cannot accidentally write to the primary database.
+ */
+export async function initializeMikroOrmSqliteAdapter(options) {
+    const orm = await MikroORM.init({
+        ...options.configuration,
+        driver: SqliteDriver,
+        dbName: options.dbName,
+        driverOptions: new NodeSqliteDialect(options.dbName),
+        entities: [...options.entities],
+    });
+    return new MikroOrmSqliteAdapter(orm);
+}
+function createStorageContext(entityManager) {
+    return { sql: new MikroOrmSqlExecutor(entityManager) };
+}
+function createMikroOrmTransaction(entityManager) {
+    return {
+        entityManager,
+        sql: new MikroOrmSqlExecutor(entityManager),
+    };
+}
+/** Maps the transaction-aware MikroORM raw-query API to the neutral SQL contract. */
+class MikroOrmSqlExecutor {
+    entityManager;
+    constructor(entityManager) {
+        this.entityManager = entityManager;
+    }
+    async all(sql, parameters = []) {
+        const rows = await this.entityManager.execute(sql, [...parameters], "all");
+        return rows;
+    }
+    async get(sql, parameters = []) {
+        const row = await this.entityManager.execute(sql, [...parameters], "get");
+        return row;
+    }
+    async run(sql, parameters = []) {
+        const result = await this.entityManager.execute(sql, [...parameters], "run");
+        return toSqlMutationResult(result);
+    }
+}
+function toSqlMutationResult(result) {
+    if (isSqlGeneratedId(result.insertId)) {
+        return {
+            changes: result.affectedRows,
+            lastInsertId: result.insertId,
+        };
+    }
+    return { changes: result.affectedRows };
+}
+function isSqlGeneratedId(value) {
+    return typeof value === "string" || typeof value === "number" || typeof value === "bigint";
+}
+//# sourceMappingURL=MikroOrmSqliteAdapter.js.map

package/dist/adapter/persistence/providers/mikro-orm/storage/MikroOrmSqliteAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MikroOrmSqliteAdapter.js","sourceRoot":"","sources":["../../../../../../src/adapter/persistence/providers/mikro-orm/storage/MikroOrmSqliteAdapter.ts"],"names":[],"mappings":"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"}

package/dist/adapter/persistence/providers/mikro-orm/storage/MikroOrmSqliteSchema.d.ts

@@ -0,0 +1,20 @@
+import type { SqlStorageAdapter } from "../../../contracts/sql.js";
+import type { MikroOrmSqliteAdapter } from "./MikroOrmSqliteAdapter.js";
+import { type SchemaMigrationResult } from "../../../../../infrastructure/storage/sqlite/schema.js";
+/**
+ * Migrates typed-sheets sync tables through the application-owned MikroORM
+ * SQLite connection.
+ *
+ * This preserves the existing `PRAGMA user_version` migration contract while
+ * ensuring DDL and later entity/outbox writes use one ORM-owned connection.
+ */
+export declare function migrateMikroOrmSqliteSchema(storage: SqlStorageAdapter): Promise<SchemaMigrationResult>;
+/**
+ * Applies the dedicated MikroORM entity schema and typed-sheets sync schema.
+ *
+ * Entity changes use MikroORM's non-destructive schema update; sync tables
+ * retain the explicit `PRAGMA user_version` migration sequence. The two schema
+ * systems are intentionally run in this order and are independently idempotent.
+ */
+export declare function migrateMikroOrmSqliteStorageSchema(storage: MikroOrmSqliteAdapter): Promise<SchemaMigrationResult>;
+//# sourceMappingURL=MikroOrmSqliteSchema.d.ts.map

package/dist/adapter/persistence/providers/mikro-orm/storage/MikroOrmSqliteSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MikroOrmSqliteSchema.d.ts","sourceRoot":"","sources":["../../../../../../src/adapter/persistence/providers/mikro-orm/storage/MikroOrmSqliteSchema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAChF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAExE,OAAO,EAOL,KAAK,qBAAqB,EAC3B,MAAM,wDAAwD,CAAC;AAOhE;;;;;;GAMG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,qBAAqB,CAAC,CAwDhC;AAED;;;;;;GAMG;AACH,wBAAsB,kCAAkC,CACtD,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,qBAAqB,CAAC,CAGhC"}

package/dist/adapter/persistence/providers/mikro-orm/storage/MikroOrmSqliteSchema.js

@@ -0,0 +1,125 @@
+import { STORAGE_ERROR_CODES, StorageError } from "../../../../../infrastructure/storage/errors.js";
+import { CURRENT_SCHEMA_VERSION, REQUIRED_V2_COLUMNS, REQUIRED_V3_COLUMNS, SQLITE_CONNECTION_PRAGMAS, syncSchemaIndexesDdl, syncSchemaTablesDdl, } from "../../../../../infrastructure/storage/sqlite/schema.js";
+import { executeSqlScript } from "../../../../../infrastructure/storage/sqlite/sqlScript.js";
+/**
+ * Migrates typed-sheets sync tables through the application-owned MikroORM
+ * SQLite connection.
+ *
+ * This preserves the existing `PRAGMA user_version` migration contract while
+ * ensuring DDL and later entity/outbox writes use one ORM-owned connection.
+ */
+export async function migrateMikroOrmSqliteSchema(storage) {
+    // `journal_mode` must be configured before the write transaction begins.
+    await storage.read(async ({ sql }) => executeSqlScript(sql, SQLITE_CONNECTION_PRAGMAS));
+    return storage.transaction(async ({ sql }) => {
+        const fromVersion = await readSchemaVersion(sql);
+        if (fromVersion > CURRENT_SCHEMA_VERSION) {
+            throw new StorageError(STORAGE_ERROR_CODES.SCHEMA_VERSION_TOO_NEW, `SQLite schema version ${fromVersion} is newer than supported version ${CURRENT_SCHEMA_VERSION}.`);
+        }
+        const hasSchema = await tableExists(sql, "sheet_registry");
+        if (fromVersion === 0 && !hasSchema) {
+            await executeSqlScript(sql, syncSchemaTablesDdl());
+            await verifyRequiredColumns(sql);
+            await executeSqlScript(sql, syncSchemaIndexesDdl());
+            await writeSchemaVersion(sql, CURRENT_SCHEMA_VERSION);
+            await verifyCurrentSchema(sql);
+            return {
+                fromVersion,
+                toVersion: CURRENT_SCHEMA_VERSION,
+                appliedVersions: [CURRENT_SCHEMA_VERSION],
+            };
+        }
+        if (!hasSchema) {
+            throw new StorageError(STORAGE_ERROR_CODES.SCHEMA_TABLE_MISSING, "SQLite schema is missing sheet_registry and cannot be migrated safely.");
+        }
+        await executeSqlScript(sql, syncSchemaTablesDdl());
+        const appliedVersions = [];
+        if (fromVersion < 2) {
+            await applyVersion2CandidateEpochMigration(sql);
+            await writeSchemaVersion(sql, 2);
+            appliedVersions.push(2);
+        }
+        if (fromVersion < 3) {
+            await applyVersion3EffectTimestampMigration(sql);
+            await writeSchemaVersion(sql, 3);
+            appliedVersions.push(3);
+        }
+        await verifyRequiredColumns(sql);
+        await executeSqlScript(sql, syncSchemaIndexesDdl());
+        await verifyCurrentSchema(sql);
+        return {
+            fromVersion,
+            toVersion: CURRENT_SCHEMA_VERSION,
+            appliedVersions,
+        };
+    });
+}
+/**
+ * Applies the dedicated MikroORM entity schema and typed-sheets sync schema.
+ *
+ * Entity changes use MikroORM's non-destructive schema update; sync tables
+ * retain the explicit `PRAGMA user_version` migration sequence. The two schema
+ * systems are intentionally run in this order and are independently idempotent.
+ */
+export async function migrateMikroOrmSqliteStorageSchema(storage) {
+    await storage.migrateEntitySchema();
+    return migrateMikroOrmSqliteSchema(storage);
+}
+async function applyVersion2CandidateEpochMigration(sql) {
+    await addColumnIfMissing(sql, "sync_conflict", "candidate_epoch", "INTEGER NOT NULL DEFAULT 0");
+    await addColumnIfMissing(sql, "resolution_command", "expected_candidate_epoch", "INTEGER NOT NULL DEFAULT 0");
+}
+async function applyVersion3EffectTimestampMigration(sql) {
+    await addColumnIfMissing(sql, "sheet_effect_outbox", "created_at", "INTEGER NOT NULL DEFAULT 0");
+}
+async function verifyCurrentSchema(sql) {
+    await verifyRequiredColumns(sql);
+    if (!(await indexExists(sql, "sync_conflict_candidate_attempt_uq"))) {
+        throw new StorageError(STORAGE_ERROR_CODES.SCHEMA_INDEX_MISSING, "SQLite schema is missing sync_conflict_candidate_attempt_uq.");
+    }
+}
+async function verifyRequiredColumns(sql) {
+    for (const [tableName, requiredColumns] of Object.entries(REQUIRED_V2_COLUMNS)) {
+        await verifyTableColumns(sql, tableName, requiredColumns);
+    }
+    for (const [tableName, requiredColumns] of Object.entries(REQUIRED_V3_COLUMNS)) {
+        await verifyTableColumns(sql, tableName, requiredColumns);
+    }
+}
+async function verifyTableColumns(sql, tableName, requiredColumns) {
+    if (!(await tableExists(sql, tableName))) {
+        throw new StorageError(STORAGE_ERROR_CODES.SCHEMA_TABLE_MISSING, `SQLite schema is missing ${tableName}; refusing an unsafe migration marker.`);
+    }
+    for (const columnName of requiredColumns) {
+        if (!(await columnExists(sql, tableName, columnName))) {
+            throw new StorageError(STORAGE_ERROR_CODES.SCHEMA_COLUMN_MISSING, `SQLite schema is missing ${tableName}.${columnName}; refusing an unsafe migration marker.`);
+        }
+    }
+}
+async function addColumnIfMissing(sql, tableName, columnName, definition) {
+    if (await columnExists(sql, tableName, columnName))
+        return;
+    await sql.run(`ALTER TABLE ${tableName} ADD COLUMN ${columnName} ${definition}`);
+}
+async function readSchemaVersion(sql) {
+    const row = await sql.get("PRAGMA user_version");
+    const version = row?.user_version;
+    if (typeof version !== "number" || !Number.isSafeInteger(version) || version < 0) {
+        throw new StorageError(STORAGE_ERROR_CODES.SCHEMA_VERSION_INVALID, "SQLite user_version must be a non-negative safe integer.");
+    }
+    return version;
+}
+async function writeSchemaVersion(sql, version) {
+    await sql.run(`PRAGMA user_version = ${version}`);
+}
+async function tableExists(sql, tableName) {
+    return (await sql.get("SELECT 1 AS present FROM sqlite_master WHERE type = 'table' AND name = ?", [tableName])) !== undefined;
+}
+async function columnExists(sql, tableName, columnName) {
+    const rows = await sql.all(`PRAGMA table_info(${tableName})`);
+    return rows.some((row) => row.name === columnName);
+}
+async function indexExists(sql, indexName) {
+    return (await sql.get("SELECT 1 AS present FROM sqlite_master WHERE type = 'index' AND name = ?", [indexName])) !== undefined;
+}
+//# sourceMappingURL=MikroOrmSqliteSchema.js.map

package/dist/adapter/persistence/providers/mikro-orm/storage/MikroOrmSqliteSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MikroOrmSqliteSchema.js","sourceRoot":"","sources":["../../../../../../src/adapter/persistence/providers/mikro-orm/storage/MikroOrmSqliteSchema.ts"],"names":[],"mappings":"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"}

package/dist/adapter/sheets/providers/apps-script-gateway/errors.d.ts

@@ -0,0 +1,42 @@
+import { CoreErrorException } from "../../../../domain/errors/index.js";
+import type { Presence } from "../../../../shared/state/index.js";
+/** Stable error categories emitted by the signed gateway protocol. */
+export declare const SYNC_GATEWAY_PROTOCOL_ERROR_CODES: {
+    readonly INVALID_OPERATION: "invalid_sync_gateway_operation";
+    readonly INVALID_SECRET: "invalid_sync_gateway_secret";
+    readonly INVALID_ISSUED_AT: "invalid_sync_gateway_issued_at";
+    readonly INVALID_EXPIRY: "invalid_sync_gateway_expiry";
+    readonly INVALID_SHEET_ID: "invalid_sync_gateway_sheet_id";
+    readonly INVALID_ACTOR_ID: "invalid_sync_gateway_actor_id";
+    readonly INVALID_KEY_ID: "invalid_sync_gateway_key_id";
+    readonly INVALID_REQUEST_ID: "invalid_sync_gateway_request_id";
+    readonly INVALID_CLIENT_OPTIONS: "invalid_sync_gateway_client_options";
+    readonly INVALID_OPERATION_SOURCE: "invalid_sync_gateway_operation_source";
+    readonly INVALID_JSON_VALUE: "invalid_sync_gateway_json_value";
+    readonly NON_FINITE_NUMBER: "non_finite_sync_gateway_number";
+};
+export type SyncGatewayProtocolErrorCode = (typeof SYNC_GATEWAY_PROTOCOL_ERROR_CODES)[keyof typeof SYNC_GATEWAY_PROTOCOL_ERROR_CODES];
+/** Structured error for invalid protocol inputs and payload values. */
+export declare class SyncGatewayProtocolError extends CoreErrorException<"adapter.sync_gateway", SyncGatewayProtocolErrorCode> {
+    constructor(code: SyncGatewayProtocolErrorCode, message: string);
+}
+/** Stable errors emitted by the Node-side Apps Script transport client. */
+export declare const SYNC_GATEWAY_CLIENT_ERROR_CODES: {
+    readonly HTTP_ERROR: "sync_gateway_http_error";
+    readonly INVALID_RESPONSE: "invalid_sync_gateway_response";
+    readonly NETWORK_ERROR: "sync_gateway_network_error";
+    readonly REMOTE_ERROR: "sync_gateway_remote_error";
+    readonly TIMEOUT: "sync_gateway_timeout";
+};
+export type SyncGatewayClientErrorCode = (typeof SYNC_GATEWAY_CLIENT_ERROR_CODES)[keyof typeof SYNC_GATEWAY_CLIENT_ERROR_CODES];
+/** Structured transport error with explicit HTTP-status and remote-code presence. */
+export declare class AppsScriptSyncGatewayError extends CoreErrorException<"adapter.sync_gateway", SyncGatewayClientErrorCode> {
+    readonly status: Presence<number>;
+    readonly remoteCode: Presence<string>;
+    constructor(code: SyncGatewayClientErrorCode, message: string, status: Presence<number>, remoteCode?: Presence<string>);
+}
+/** Throws the shared contract error used when an operation request is invalid. */
+export declare function invalidOperationRequest(operationLabel: string, message: string): never;
+/** Throws the shared contract error used when an operation response is invalid. */
+export declare function invalidOperationResponse(operationLabel: string, message: string): never;
+//# sourceMappingURL=errors.d.ts.map

package/dist/adapter/sheets/providers/apps-script-gateway/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../../src/adapter/sheets/providers/apps-script-gateway/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAExE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAMlE,sEAAsE;AACtE,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;CAapC,CAAC;AAEX,MAAM,MAAM,4BAA4B,GACtC,CAAC,OAAO,iCAAiC,CAAC,CAAC,MAAM,OAAO,iCAAiC,CAAC,CAAC;AAE7F,uEAAuE;AACvE,qBAAa,wBAAyB,SAAQ,kBAAkB,CAC9D,sBAAsB,EACtB,4BAA4B,CAC7B;gBACa,IAAI,EAAE,4BAA4B,EAAE,OAAO,EAAE,MAAM;CAGhE;AAED,2EAA2E;AAC3E,eAAO,MAAM,+BAA+B;;;;;;CAMlC,CAAC;AAEX,MAAM,MAAM,0BAA0B,GACpC,CAAC,OAAO,+BAA+B,CAAC,CAAC,MAAM,OAAO,+BAA+B,CAAC,CAAC;AAEzF,qFAAqF;AACrF,qBAAa,0BAA2B,SAAQ,kBAAkB,CAChE,sBAAsB,EACtB,0BAA0B,CAC3B;IACC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;gBAGpC,IAAI,EAAE,0BAA0B,EAChC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,EACxB,UAAU,GAAE,QAAQ,CAAC,MAAM,CAAmC;CAMjE;AAED,kFAAkF;AAClF,wBAAgB,uBAAuB,CACrC,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,GACd,KAAK,CAKP;AAED,mFAAmF;AACnF,wBAAgB,wBAAwB,CACtC,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,GACd,KAAK,CAKP"}

package/dist/adapter/sheets/providers/apps-script-gateway/errors.js

@@ -0,0 +1,51 @@
+import { CoreErrorException } from "../../../../domain/errors/index.js";
+import { PRESENCE_KINDS } from "../../../../shared/state/index.js";
+import { SYNC_GATEWAY_ERROR_CODES, SyncGatewayContractError, } from "../../../../application/sync/gateway/errors.js";
+/** Stable error categories emitted by the signed gateway protocol. */
+export const SYNC_GATEWAY_PROTOCOL_ERROR_CODES = {
+    INVALID_OPERATION: "invalid_sync_gateway_operation",
+    INVALID_SECRET: "invalid_sync_gateway_secret",
+    INVALID_ISSUED_AT: "invalid_sync_gateway_issued_at",
+    INVALID_EXPIRY: "invalid_sync_gateway_expiry",
+    INVALID_SHEET_ID: "invalid_sync_gateway_sheet_id",
+    INVALID_ACTOR_ID: "invalid_sync_gateway_actor_id",
+    INVALID_KEY_ID: "invalid_sync_gateway_key_id",
+    INVALID_REQUEST_ID: "invalid_sync_gateway_request_id",
+    INVALID_CLIENT_OPTIONS: "invalid_sync_gateway_client_options",
+    INVALID_OPERATION_SOURCE: "invalid_sync_gateway_operation_source",
+    INVALID_JSON_VALUE: "invalid_sync_gateway_json_value",
+    NON_FINITE_NUMBER: "non_finite_sync_gateway_number",
+};
+/** Structured error for invalid protocol inputs and payload values. */
+export class SyncGatewayProtocolError extends CoreErrorException {
+    constructor(code, message) {
+        super("adapter.sync_gateway", code, message);
+    }
+}
+/** Stable errors emitted by the Node-side Apps Script transport client. */
+export const SYNC_GATEWAY_CLIENT_ERROR_CODES = {
+    HTTP_ERROR: "sync_gateway_http_error",
+    INVALID_RESPONSE: "invalid_sync_gateway_response",
+    NETWORK_ERROR: "sync_gateway_network_error",
+    REMOTE_ERROR: "sync_gateway_remote_error",
+    TIMEOUT: "sync_gateway_timeout",
+};
+/** Structured transport error with explicit HTTP-status and remote-code presence. */
+export class AppsScriptSyncGatewayError extends CoreErrorException {
+    status;
+    remoteCode;
+    constructor(code, message, status, remoteCode = { kind: PRESENCE_KINDS.ABSENT }) {
+        super("adapter.sync_gateway", code, message);
+        this.status = status;
+        this.remoteCode = remoteCode;
+    }
+}
+/** Throws the shared contract error used when an operation request is invalid. */
+export function invalidOperationRequest(operationLabel, message) {
+    throw new SyncGatewayContractError(SYNC_GATEWAY_ERROR_CODES.INVALID_EFFECT_PAYLOAD, `${operationLabel} request is invalid: ${message}`);
+}
+/** Throws the shared contract error used when an operation response is invalid. */
+export function invalidOperationResponse(operationLabel, message) {
+    throw new SyncGatewayContractError(SYNC_GATEWAY_ERROR_CODES.INVALID_GATEWAY_RESPONSE, `${operationLabel} response is invalid: ${message}`);
+}
+//# sourceMappingURL=errors.js.map

package/dist/adapter/sheets/providers/apps-script-gateway/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../../../src/adapter/sheets/providers/apps-script-gateway/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAEnE,OAAO,EACL,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,gDAAgD,CAAC;AAExD,sEAAsE;AACtE,MAAM,CAAC,MAAM,iCAAiC,GAAG;IAC/C,iBAAiB,EAAE,gCAAgC;IACnD,cAAc,EAAE,6BAA6B;IAC7C,iBAAiB,EAAE,gCAAgC;IACnD,cAAc,EAAE,6BAA6B;IAC7C,gBAAgB,EAAE,+BAA+B;IACjD,gBAAgB,EAAE,+BAA+B;IACjD,cAAc,EAAE,6BAA6B;IAC7C,kBAAkB,EAAE,iCAAiC;IACrD,sBAAsB,EAAE,qCAAqC;IAC7D,wBAAwB,EAAE,uCAAuC;IACjE,kBAAkB,EAAE,iCAAiC;IACrD,iBAAiB,EAAE,gCAAgC;CAC3C,CAAC;AAKX,uEAAuE;AACvE,MAAM,OAAO,wBAAyB,SAAQ,kBAG7C;IACC,YAAY,IAAkC,EAAE,OAAe;QAC7D,KAAK,CAAC,sBAAsB,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAC/C,CAAC;CACF;AAED,2EAA2E;AAC3E,MAAM,CAAC,MAAM,+BAA+B,GAAG;IAC7C,UAAU,EAAE,yBAAyB;IACrC,gBAAgB,EAAE,+BAA+B;IACjD,aAAa,EAAE,4BAA4B;IAC3C,YAAY,EAAE,2BAA2B;IACzC,OAAO,EAAE,sBAAsB;CACvB,CAAC;AAKX,qFAAqF;AACrF,MAAM,OAAO,0BAA2B,SAAQ,kBAG/C;IACU,MAAM,CAAmB;IACzB,UAAU,CAAmB;IAEtC,YACE,IAAgC,EAChC,OAAe,EACf,MAAwB,EACxB,aAA+B,EAAE,IAAI,EAAE,cAAc,CAAC,MAAM,EAAE;QAE9D,KAAK,CAAC,sBAAsB,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QAC7C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED,kFAAkF;AAClF,MAAM,UAAU,uBAAuB,CACrC,cAAsB,EACtB,OAAe;IAEf,MAAM,IAAI,wBAAwB,CAChC,wBAAwB,CAAC,sBAAsB,EAC/C,GAAG,cAAc,wBAAwB,OAAO,EAAE,CACnD,CAAC;AACJ,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,wBAAwB,CACtC,cAAsB,EACtB,OAAe;IAEf,MAAM,IAAI,wBAAwB,CAChC,wBAAwB,CAAC,wBAAwB,EACjD,GAAG,cAAc,yBAAyB,OAAO,EAAE,CACpD,CAAC;AACJ,CAAC"}

package/dist/adapter/sheets/providers/apps-script-gateway/index.d.ts

@@ -0,0 +1,22 @@
+/** Signed adapter tools for the registry-bound Apps Script sync gateway. */
+export { APPS_SCRIPT_OPERATION_NAMES, } from "./protocol/constants.js";
+export type { AppsScriptOperationName } from "./protocol/constants.js";
+export { canonicalSyncJson, syncSha256Hex, } from "./protocol/syncProtocol.js";
+export type { SyncJsonValue, } from "./protocol/syncProtocol.js";
+export { AppsScriptSyncGatewayError, SYNC_GATEWAY_CLIENT_ERROR_CODES, } from "./errors.js";
+export type { SyncGatewayClientErrorCode } from "./errors.js";
+export { APPS_SCRIPT_OPERATION_PROTOCOL_VERSION, appsScriptOperationSigningInput, signAppsScriptOperationEnvelope, createAppsScriptOperationEnvelope, } from "./protocol/codeGsProtocol.js";
+export type { AppsScriptOperationWire, AppsScriptOperationPayload, AppsScriptOperationSigningFields, AppsScriptOperationEnvelope, CreateAppsScriptOperationEnvelopeOptions, } from "./protocol/codeGsProtocol.js";
+export { AppsScriptOperationClient } from "./transport/operationClient.js";
+export { createFastAppendRowsOperation } from "./operations/write/fastAppendOperation.js";
+export { createReadTableRowsOperation } from "./operations/read/tableReadOperation.js";
+export { createApplyEffectsOperation, createReadEffectPostconditionOperation, createReadEffectPostconditionsOperation, } from "./operations/effect/effectOperation.js";
+export { createEnsureRowAnchorsOperation, createObserveSnapshotOperation, createReadSnapshotOperation, } from "./operations/observation/observationOperation.js";
+export { AppsScriptOperationSyncGateway } from "./transport/operationSyncGateway.js";
+export type { AppsScriptOperationDefinition, AnyAppsScriptOperationDefinition, AppsScriptOperationGateway, AppsScriptOperationResult, AppsScriptOperationResults, AppsScriptOperationClientOptions, AppsScriptOperationRequestEvent, } from "./transport/operationClient.js";
+export type { AppsScriptFastAppendOperationArgs, AppsScriptFastAppendOperationRequest, AppsScriptFastAppendOperation, } from "./operations/write/fastAppendOperation.js";
+export type { AppsScriptApplyEffectsOperationArgs, AppsScriptApplyEffectsOperationRequest, AppsScriptReadEffectPostconditionOperationArgs, AppsScriptReadEffectPostconditionsOperationArgs, } from "./operations/effect/effectOperation.js";
+export type { AppsScriptEnsureRowAnchorsOperationArgs, AppsScriptObserveSnapshotOperationArgs, AppsScriptReadSnapshotOperationArgs, } from "./operations/observation/observationOperation.js";
+export type { AppsScriptReadTableRowsRequest, } from "./operations/read/tableReadOperation.js";
+export type { AppsScriptOperationProjectionStatus, AppsScriptOperationSyncGatewayOptions, } from "./transport/operationSyncGateway.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/adapter/sheets/providers/apps-script-gateway/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/adapter/sheets/providers/apps-script-gateway/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAE5E,OAAO,EACL,2BAA2B,GAC5B,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAEvE,OAAO,EACL,iBAAiB,EACjB,aAAa,GACd,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACV,aAAa,GACd,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,0BAA0B,EAC1B,+BAA+B,GAChC,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EACL,sCAAsC,EACtC,+BAA+B,EAC/B,+BAA+B,EAC/B,iCAAiC,GAClC,MAAM,8BAA8B,CAAC;AACtC,YAAY,EACV,uBAAuB,EACvB,0BAA0B,EAC1B,gCAAgC,EAChC,2BAA2B,EAC3B,wCAAwC,GACzC,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,6BAA6B,EAAE,MAAM,2CAA2C,CAAC;AAC1F,OAAO,EAAE,4BAA4B,EAAE,MAAM,yCAAyC,CAAC;AACvF,OAAO,EACL,2BAA2B,EAC3B,sCAAsC,EACtC,uCAAuC,GACxC,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,+BAA+B,EAC/B,8BAA8B,EAC9B,2BAA2B,GAC5B,MAAM,kDAAkD,CAAC;AAC1D,OAAO,EAAE,8BAA8B,EAAE,MAAM,qCAAqC,CAAC;AACrF,YAAY,EACV,6BAA6B,EAC7B,gCAAgC,EAChC,0BAA0B,EAC1B,yBAAyB,EACzB,0BAA0B,EAC1B,gCAAgC,EAChC,+BAA+B,GAChC,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACV,iCAAiC,EACjC,oCAAoC,EACpC,6BAA6B,GAC9B,MAAM,2CAA2C,CAAC;AACnD,YAAY,EACV,mCAAmC,EACnC,sCAAsC,EACtC,8CAA8C,EAC9C,+CAA+C,GAChD,MAAM,wCAAwC,CAAC;AAChD,YAAY,EACV,uCAAuC,EACvC,sCAAsC,EACtC,mCAAmC,GACpC,MAAM,kDAAkD,CAAC;AAC1D,YAAY,EACV,8BAA8B,GAC/B,MAAM,yCAAyC,CAAC;AACjD,YAAY,EACV,mCAAmC,EACnC,qCAAqC,GACtC,MAAM,qCAAqC,CAAC"}

package/dist/adapter/sheets/providers/apps-script-gateway/index.js

@@ -0,0 +1,12 @@
+/** Signed adapter tools for the registry-bound Apps Script sync gateway. */
+export { APPS_SCRIPT_OPERATION_NAMES, } from "./protocol/constants.js";
+export { canonicalSyncJson, syncSha256Hex, } from "./protocol/syncProtocol.js";
+export { AppsScriptSyncGatewayError, SYNC_GATEWAY_CLIENT_ERROR_CODES, } from "./errors.js";
+export { APPS_SCRIPT_OPERATION_PROTOCOL_VERSION, appsScriptOperationSigningInput, signAppsScriptOperationEnvelope, createAppsScriptOperationEnvelope, } from "./protocol/codeGsProtocol.js";
+export { AppsScriptOperationClient } from "./transport/operationClient.js";
+export { createFastAppendRowsOperation } from "./operations/write/fastAppendOperation.js";
+export { createReadTableRowsOperation } from "./operations/read/tableReadOperation.js";
+export { createApplyEffectsOperation, createReadEffectPostconditionOperation, createReadEffectPostconditionsOperation, } from "./operations/effect/effectOperation.js";
+export { createEnsureRowAnchorsOperation, createObserveSnapshotOperation, createReadSnapshotOperation, } from "./operations/observation/observationOperation.js";
+export { AppsScriptOperationSyncGateway } from "./transport/operationSyncGateway.js";
+//# sourceMappingURL=index.js.map

package/dist/adapter/sheets/providers/apps-script-gateway/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/adapter/sheets/providers/apps-script-gateway/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAE5E,OAAO,EACL,2BAA2B,GAC5B,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,iBAAiB,EACjB,aAAa,GACd,MAAM,4BAA4B,CAAC;AAIpC,OAAO,EACL,0BAA0B,EAC1B,+BAA+B,GAChC,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,sCAAsC,EACtC,+BAA+B,EAC/B,+BAA+B,EAC/B,iCAAiC,GAClC,MAAM,8BAA8B,CAAC;AAQtC,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,6BAA6B,EAAE,MAAM,2CAA2C,CAAC;AAC1F,OAAO,EAAE,4BAA4B,EAAE,MAAM,yCAAyC,CAAC;AACvF,OAAO,EACL,2BAA2B,EAC3B,sCAAsC,EACtC,uCAAuC,GACxC,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,+BAA+B,EAC/B,8BAA8B,EAC9B,2BAA2B,GAC5B,MAAM,kDAAkD,CAAC;AAC1D,OAAO,EAAE,8BAA8B,EAAE,MAAM,qCAAqC,CAAC"}

package/dist/adapter/sheets/providers/apps-script-gateway/operations/effect/effectOperation.d.ts

@@ -0,0 +1,42 @@
+/** Thin-Gateway operations for regular projection effects and recovery reads. */
+import type { ApplySyncEffectsRequest, ApplySyncEffectsResult, SyncEffectPostcondition, SyncGatewayEffect, SyncGatewayEffectPostconditionResult } from "../../../../../../application/sync/gateway/syncGateway.js";
+import type { AppsScriptOperationDefinition } from "../../transport/operationClient.js";
+declare const EFFECT_OPERATION_MODES: {
+    readonly APPLY: "applyEffects";
+    readonly READ_ONE: "readEffectPostcondition";
+    readonly READ_BATCH: "readEffectPostconditions";
+};
+interface EffectOperationRouteOptions {
+    readonly identityField?: string;
+    readonly checkboxHeaders?: readonly string[];
+}
+export type AppsScriptApplyEffectsOperationRequest = ApplySyncEffectsRequest & EffectOperationRouteOptions;
+export type AppsScriptApplyEffectsOperationArgs = {
+    readonly mode: typeof EFFECT_OPERATION_MODES.APPLY;
+} & AppsScriptApplyEffectsOperationRequest;
+export type AppsScriptReadEffectPostconditionOperationArgs = {
+    readonly mode: typeof EFFECT_OPERATION_MODES.READ_ONE;
+    readonly physicalSheetId: string;
+    readonly sheetName: string;
+    readonly registeredRange: string;
+    readonly projection: ApplySyncEffectsRequest["projection"];
+    readonly schemaVersion: number;
+    readonly effect: SyncGatewayEffect;
+} & EffectOperationRouteOptions;
+export type AppsScriptReadEffectPostconditionsOperationArgs = {
+    readonly mode: typeof EFFECT_OPERATION_MODES.READ_BATCH;
+    readonly physicalSheetId: string;
+    readonly sheetName: string;
+    readonly registeredRange: string;
+    readonly projection: ApplySyncEffectsRequest["projection"];
+    readonly schemaVersion: number;
+    readonly effects: readonly SyncGatewayEffect[];
+} & EffectOperationRouteOptions;
+/** Builds the regular update/delete operation executed by the thin Gateway. */
+export declare function createApplyEffectsOperation(request: AppsScriptApplyEffectsOperationRequest): AppsScriptOperationDefinition<AppsScriptApplyEffectsOperationArgs, ApplySyncEffectsResult>;
+/** Builds the single-effect response-loss probe. */
+export declare function createReadEffectPostconditionOperation(request: Omit<AppsScriptReadEffectPostconditionOperationArgs, "mode">): AppsScriptOperationDefinition<AppsScriptReadEffectPostconditionOperationArgs, SyncEffectPostcondition>;
+/** Builds the batched response-loss probe used by the worker. */
+export declare function createReadEffectPostconditionsOperation(request: Omit<AppsScriptReadEffectPostconditionsOperationArgs, "mode">): AppsScriptOperationDefinition<AppsScriptReadEffectPostconditionsOperationArgs, readonly SyncGatewayEffectPostconditionResult[]>;
+export {};
+//# sourceMappingURL=effectOperation.d.ts.map

package/dist/adapter/sheets/providers/apps-script-gateway/operations/effect/effectOperation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effectOperation.d.ts","sourceRoot":"","sources":["../../../../../../../src/adapter/sheets/providers/apps-script-gateway/operations/effect/effectOperation.ts"],"names":[],"mappings":"AAAA,iFAAiF;AAEjF,OAAO,KAAK,EACV,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,iBAAiB,EACjB,oCAAoC,EAErC,MAAM,2DAA2D,CAAC;AAiBnE,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,oCAAoC,CAAC;AAQxF,QAAA,MAAM,sBAAsB;;;;CAIlB,CAAC;AAEX,UAAU,2BAA2B;IACnC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED,MAAM,MAAM,sCAAsC,GAAG,uBAAuB,GAC1E,2BAA2B,CAAC;AAE9B,MAAM,MAAM,mCAAmC,GAAG;IAChD,QAAQ,CAAC,IAAI,EAAE,OAAO,sBAAsB,CAAC,KAAK,CAAC;CACpD,GAAG,sCAAsC,CAAC;AAE3C,MAAM,MAAM,8CAA8C,GAAG;IAC3D,QAAQ,CAAC,IAAI,EAAE,OAAO,sBAAsB,CAAC,QAAQ,CAAC;IACtD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,uBAAuB,CAAC,YAAY,CAAC,CAAC;IAC3D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;CACpC,GAAG,2BAA2B,CAAC;AAEhC,MAAM,MAAM,+CAA+C,GAAG;IAC5D,QAAQ,CAAC,IAAI,EAAE,OAAO,sBAAsB,CAAC,UAAU,CAAC;IACxD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,uBAAuB,CAAC,YAAY,CAAC,CAAC;IAC3D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAChD,GAAG,2BAA2B,CAAC;AAEhC,+EAA+E;AAC/E,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,sCAAsC,GAC9C,6BAA6B,CAAC,mCAAmC,EAAE,sBAAsB,CAAC,CAO5F;AAED,oDAAoD;AACpD,wBAAgB,sCAAsC,CACpD,OAAO,EAAE,IAAI,CAAC,8CAA8C,EAAE,MAAM,CAAC,GACpE,6BAA6B,CAC9B,8CAA8C,EAC9C,uBAAuB,CACxB,CAOA;AAED,iEAAiE;AACjE,wBAAgB,uCAAuC,CACrD,OAAO,EAAE,IAAI,CAAC,+CAA+C,EAAE,MAAM,CAAC,GACrE,6BAA6B,CAC9B,+CAA+C,EAC/C,SAAS,oCAAoC,EAAE,CAChD,CAOA"}