hikoutei 0.5.0 → 0.5.2

package/dist/adapter/sheets/providers/google-sheets-api/operations/provisioning.js

@@ -0,0 +1,256 @@
+/**
+ * Projection provisioning for the Google Sheets API sync provider.
+ *
+ * Creates missing tabs and their header rows, or verifies existing tabs, in
+ * ONE atomic batchUpdate. An existing tab with no content anywhere in its
+ * used grid gets its headers initialized; an existing tab with content must
+ * match the registered headers exactly (order, duplicates, width), otherwise
+ * provisioning fails closed BEFORE any mutation. The operation is idempotent:
+ * a retry after a lost response re-enumerates, sees the exact headers, and
+ * succeeds without rewriting anything.
+ */
+import { GOOGLE_SHEETS_API_PROVISION_ENUMERATION_FIELDS, GOOGLE_SHEETS_API_PROVISION_FIELDS, gridHeaderCells, parseSpreadsheetDocument, } from "../model/preflight.js";
+import { invalidProviderRequest, invalidProviderState } from "../errors.js";
+import { allocateSheetId } from "../model/sheetIdAllocator.js";
+import { columnLetters, parseRegisteredRange, quoteA1SheetName, } from "../model/valueNormalization.js";
+import { requireValidBatchUpdateReply, runRead, runWrite, } from "./shared.js";
+/**
+ * Creates missing tabs and their header rows, or verifies existing tabs,
+ * in ONE atomic batchUpdate. An existing tab with no content anywhere in
+ * its used grid gets its headers initialized; an existing tab with content
+ * must match the registered headers exactly (order, duplicates, width),
+ * otherwise provisioning fails closed BEFORE any mutation. The operation
+ * is idempotent: a retry after a lost response re-enumerates, sees the
+ * exact headers, and succeeds without rewriting anything.
+ */
+export async function provisionRegistry(deps, registrations) {
+    validateProvisionRegistrations(registrations);
+    // Enumerate every tab (no ranges, hidden included) with grid dimensions.
+    const enumerationRaw = await runRead(deps, () => deps.transport.getSpreadsheet({
+        spreadsheetId: deps.spreadsheetId,
+        ranges: [],
+        fields: GOOGLE_SHEETS_API_PROVISION_ENUMERATION_FIELDS,
+        timeoutMs: deps.readTimeoutMs,
+    }));
+    const sheets = parseSpreadsheetDocument(enumerationRaw, "provisioning enumeration");
+    const existingByTitle = new Map(sheets.sheets.map((sheet) => [sheet.title, sheet]));
+    // Read the full used grid of every existing registered tab (values plus
+    // formats). Missing tabs need no data read; they are created below.
+    const dataTargets = registrations.filter((registration) => existingByTitle.has(registration.sheetName));
+    const grids = new Map();
+    if (dataTargets.length > 0) {
+        const ranges = dataTargets.map((registration) => {
+            const existing = existingByTitle.get(registration.sheetName);
+            if (existing === undefined) {
+                invalidProviderState(`Registered sync sheet does not exist: ${registration.sheetName}`);
+            }
+            const endColumn = provisionGridEndColumn(registration, existing);
+            return `${quoteA1SheetName(registration.sheetName)}!A1:${columnLetters(endColumn)}1048576`;
+        });
+        const dataRaw = await runRead(deps, () => deps.transport.getSpreadsheet({
+            spreadsheetId: deps.spreadsheetId,
+            ranges,
+            fields: GOOGLE_SHEETS_API_PROVISION_FIELDS,
+            timeoutMs: deps.readTimeoutMs,
+        }));
+        const document = parseSpreadsheetDocument(dataRaw, "provisioning grid");
+        for (const registration of dataTargets) {
+            const existing = existingByTitle.get(registration.sheetName);
+            if (existing === undefined) {
+                invalidProviderState(`Registered sync sheet does not exist: ${registration.sheetName}`);
+            }
+            const grid = document.grids.get(existing.sheetId);
+            if (grid === undefined) {
+                invalidProviderState(`grid data is missing for sheet ${existing.sheetId}`);
+            }
+            grids.set(registration.sheetName, grid);
+        }
+    }
+    // Plan all mutations: addSheet + header writes for missing tabs, header
+    // writes for truly-empty tabs, exact-match verification for content tabs.
+    const requests = [];
+    const createdSheets = [];
+    const initializedHeaders = [];
+    const usedSheetIds = new Set(sheets.sheets.map((sheet) => sheet.sheetId));
+    for (const registration of registrations) {
+        const range = parseRegisteredRange(registration.registeredRange);
+        const existing = existingByTitle.get(registration.sheetName);
+        const headerCells = registration.headers.map((header) => ({
+            userEnteredValue: { stringValue: header },
+        }));
+        if (existing === undefined) {
+            const sheetId = allocateSheetId(usedSheetIds);
+            usedSheetIds.add(sheetId);
+            requests.push({ kind: "addSheet", title: registration.sheetName, sheetId });
+            requests.push({
+                kind: "updateCells",
+                sheetId,
+                startRowIndex: 0,
+                startColumnIndex: range.startColumn - 1,
+                rows: [headerCells],
+                fields: "userEnteredValue",
+            });
+            createdSheets.push(registration.sheetName);
+            initializedHeaders.push(registration.sheetName);
+            continue;
+        }
+        const grid = grids.get(registration.sheetName);
+        if (grid === undefined) {
+            invalidProviderState(`provisioning grid is missing for ${registration.sheetName}`);
+        }
+        if (!gridHasContent(grid)) {
+            // Truly empty tab: initialize the header row only.
+            requests.push({
+                kind: "updateCells",
+                sheetId: existing.sheetId,
+                startRowIndex: 0,
+                startColumnIndex: range.startColumn - 1,
+                rows: [headerCells],
+                fields: "userEnteredValue",
+            });
+            initializedHeaders.push(registration.sheetName);
+            continue;
+        }
+        // Content tab: the header row must match the registered schema exactly.
+        assertProvisioningHeaders(grid, registration);
+    }
+    if (requests.length > 0) {
+        const response = await runWrite(deps, () => deps.transport.batchUpdate({
+            spreadsheetId: deps.spreadsheetId,
+            requests,
+        }));
+        requireValidBatchUpdateReply(response, requests.length);
+    }
+    return {
+        registrations: registrations.map(({ headers: _headers, ...route }) => route),
+        createdSheets,
+        initializedHeaders,
+    };
+}
+/** Validates provisioning registrations before any transport call. */
+function validateProvisionRegistrations(registrations) {
+    if (registrations.length === 0) {
+        invalidProviderRequest("provisioning", "registrations must not be empty");
+    }
+    const tabNames = new Set();
+    for (const registration of registrations) {
+        if (registration.sheetName.trim() === "") {
+            invalidProviderRequest("provisioning", "sheetName must be non-empty");
+        }
+        if (tabNames.has(registration.sheetName)) {
+            invalidProviderRequest("provisioning", `cannot repeat a tab name: ${registration.sheetName}`);
+        }
+        tabNames.add(registration.sheetName);
+        const range = parseRegisteredRange(registration.registeredRange);
+        if (range.columnCount !== registration.headers.length) {
+            invalidProviderRequest("provisioning", `headers do not match registeredRange for ${registration.sheetName}`);
+        }
+        if (registration.headers.length === 0 ||
+            registration.headers.some((header) => header.trim() === "")) {
+            invalidProviderRequest("provisioning", `headers must contain non-empty names for ${registration.sheetName}`);
+        }
+        if (new Set(registration.headers).size !== registration.headers.length) {
+            invalidProviderRequest("provisioning", `headers must not contain duplicates for ${registration.sheetName}`);
+        }
+    }
+}
+/**
+ * Builds the provisioning data-read end column: the sheet's actual grid
+ * width when the enumeration supplied it (so content anywhere in the tab
+ * decides emptiness), otherwise the registered range's end column and
+ * emptiness is judged only from the returned grid.
+ */
+function provisionGridEndColumn(registration, existing) {
+    const parsed = parseRegisteredRange(registration.registeredRange);
+    const registeredEnd = parsed.startColumn + parsed.columnCount - 1;
+    const gridColumns = existing.gridProperties?.columnCount;
+    if (gridColumns === undefined)
+        return registeredEnd;
+    return Math.max(gridColumns, registeredEnd);
+}
+/**
+ * Returns whether a provisioning grid has any content anywhere.
+ *
+ * Only cells with an actual ENTERED value count (a userEnteredValue carrying
+ * stringValue/numberValue/boolValue/formulaValue). Blank `{}` cells and
+ * format-only cells (userEnteredFormat without a value) are ignored, matching
+ * the Apps Script `getLastRow()/getLastColumn()` semantics provisioning was
+ * ported from — a blank-but-formatted tab is still initialized, never judged
+ * as a content tab that must match headers.
+ */
+function gridHasContent(grid) {
+    for (const row of grid.rowData) {
+        for (const value of row.values) {
+            if (cellHasEnteredValue(value))
+                return true;
+        }
+    }
+    return false;
+}
+/** Returns whether one API cell carries a real entered value. */
+function cellHasEnteredValue(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const entered = value.userEnteredValue;
+    if (entered === null || typeof entered !== "object" || Array.isArray(entered))
+        return false;
+    const enteredRecord = entered;
+    return enteredRecord.stringValue !== undefined ||
+        enteredRecord.numberValue !== undefined ||
+        enteredRecord.boolValue !== undefined ||
+        enteredRecord.formulaValue !== undefined;
+}
+/**
+ * Verifies one content tab's header row against the registered schema:
+ * exact order, non-empty strings, no duplicates, and full registered-range
+ * coverage. Any drift fails closed BEFORE any mutation, mirroring the Apps
+ * Script "operational provisioning header mismatch" behavior (including a
+ * blank header row on a tab whose content lives outside the registered
+ * range).
+ */
+function assertProvisioningHeaders(grid, registration) {
+    const range = parseRegisteredRange(registration.registeredRange);
+    const headerValues = gridHeaderCells(grid, range);
+    const actual = headerValues.map((value, index) => {
+        const raw = provisioningHeaderString(value);
+        if (raw === null) {
+            invalidProviderState(`operational provisioning header mismatch: ${registration.sheetName}` +
+                ` (header is missing at column ${index + 1})`);
+        }
+        return raw;
+    });
+    if (new Set(actual).size !== actual.length) {
+        invalidProviderState(`operational provisioning header mismatch: ${registration.sheetName} (duplicate header)`);
+    }
+    if (actual.length !== registration.headers.length ||
+        actual.some((header, index) => header !== registration.headers[index])) {
+        invalidProviderState(`operational provisioning header mismatch: ${registration.sheetName}`);
+    }
+}
+/**
+ * Reads a provisioning header cell as its raw string: string values as-is,
+ * numbers and booleans stringified (the Apps Script source compares
+ * `String(actual) === String(expected)`), anything else treated as missing.
+ */
+function provisioningHeaderString(value) {
+    if (value === null || typeof value !== "object")
+        return null;
+    const record = value;
+    const entered = record.userEnteredValue;
+    if (entered === null || typeof entered !== "object")
+        return null;
+    const enteredRecord = entered;
+    if (enteredRecord.stringValue !== undefined) {
+        return typeof enteredRecord.stringValue === "string" ? enteredRecord.stringValue : null;
+    }
+    if (enteredRecord.numberValue !== undefined) {
+        return typeof enteredRecord.numberValue === "number" && Number.isFinite(enteredRecord.numberValue)
+            ? String(enteredRecord.numberValue)
+            : null;
+    }
+    if (enteredRecord.boolValue !== undefined) {
+        return typeof enteredRecord.boolValue === "boolean" ? String(enteredRecord.boolValue) : null;
+    }
+    return null;
+}
+//# sourceMappingURL=provisioning.js.map

package/dist/adapter/sheets/providers/google-sheets-api/operations/provisioning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provisioning.js","sourceRoot":"","sources":["../../../../../../src/adapter/sheets/providers/google-sheets-api/operations/provisioning.ts"],"names":[],"mappings":"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"}

package/dist/adapter/sheets/providers/google-sheets-api/operations/readRows.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Values-only table reads and observation snapshots for the Google Sheets
+ * API sync provider.
+ *
+ * `readRowsBatch` serves several registered tables through ONE
+ * `spreadsheets.get` call (fail-closed on missing tabs, header drift, or
+ * malformed payloads). The snapshot operations share one grid read per
+ * batch, write missing row anchors in ONE atomic batch, and re-read once so
+ * committed anchors appear in every snapshot.
+ */
+import type { ReadSyncSnapshotRequest, ReadSyncTableRowsRequest, SyncObservedSnapshot, SyncSheetsSnapshot, SyncTableRowsResult } from "../../../../../application/sync/sheets/syncSheets.js";
+import { type SyncSnapshotReadMode } from "../../../../../application/sync/sheets/constants.js";
+import { type ObservedTab } from "../model/observation.js";
+import { type GoogleSheetsApiProviderDeps } from "./shared.js";
+/** Reads one registered table's literal values with one REST read. */
+export declare function readRows(deps: GoogleSheetsApiProviderDeps, request: ReadSyncTableRowsRequest): Promise<SyncTableRowsResult>;
+/**
+ * Reads several registered tables through ONE `spreadsheets.get` call.
+ * Results are returned in request order; a missing tab, header drift, or
+ * malformed payload fails closed before any result is produced.
+ */
+export declare function readRowsBatch(deps: GoogleSheetsApiProviderDeps, requests: readonly ReadSyncTableRowsRequest[]): Promise<readonly SyncTableRowsResult[]>;
+/** Reads one full snapshot without any mutation (lock-free). */
+export declare function readSnapshot(deps: GoogleSheetsApiProviderDeps, request: ReadSyncSnapshotRequest): Promise<SyncSheetsSnapshot>;
+/** Combines anchor assignment and one snapshot read under one request. */
+export declare function observeSnapshot(deps: GoogleSheetsApiProviderDeps, request: ReadSyncSnapshotRequest): Promise<SyncObservedSnapshot>;
+/**
+ * Observes several projections with ONE grid read, ONE anchor write (when
+ * any anchor is missing), and ONE re-read (when anchors were written), so
+ * the committed anchors are reflected in every snapshot. The coordinator
+ * already holds every involved mutation lane before this call.
+ */
+export declare function observeSnapshots(deps: GoogleSheetsApiProviderDeps, requests: readonly ReadSyncSnapshotRequest[]): Promise<readonly SyncObservedSnapshot[]>;
+/** Reads the target grids of one or more observation requests (one call). */
+export declare function readObservedTabs(deps: GoogleSheetsApiProviderDeps, requests: readonly {
+    readonly sheetName: string;
+    readonly registeredRange: string;
+    readonly readMode?: SyncSnapshotReadMode;
+}[]): Promise<ReadonlyMap<string, ObservedTab>>;
+//# sourceMappingURL=readRows.d.ts.map

package/dist/adapter/sheets/providers/google-sheets-api/operations/readRows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readRows.d.ts","sourceRoot":"","sources":["../../../../../../src/adapter/sheets/providers/google-sheets-api/operations/readRows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,uBAAuB,EACvB,wBAAwB,EACxB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,sDAAsD,CAAC;AAK9D,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,qDAAqD,CAAC;AAW7D,OAAO,EAKL,KAAK,WAAW,EAEjB,MAAM,yBAAyB,CAAC;AAOjC,OAAO,EAML,KAAK,2BAA2B,EACjC,MAAM,aAAa,CAAC;AAGrB,sEAAsE;AACtE,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,2BAA2B,EACjC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,mBAAmB,CAAC,CAM9B;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,2BAA2B,EACjC,QAAQ,EAAE,SAAS,wBAAwB,EAAE,GAC5C,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC,CAiDzC;AAED,gEAAgE;AAChE,wBAAsB,YAAY,CAChC,IAAI,EAAE,2BAA2B,EACjC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,kBAAkB,CAAC,CAQ7B;AAED,0EAA0E;AAC1E,wBAAsB,eAAe,CACnC,IAAI,EAAE,2BAA2B,EACjC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,oBAAoB,CAAC,CAM/B;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,2BAA2B,EACjC,QAAQ,EAAE,SAAS,uBAAuB,EAAE,GAC3C,OAAO,CAAC,SAAS,oBAAoB,EAAE,CAAC,CAwE1C;AAED,6EAA6E;AAC7E,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,2BAA2B,EACjC,QAAQ,EAAE,SAAS;IACjB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,CAAC;CAC1C,EAAE,GACF,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAqB3C"}

package/dist/adapter/sheets/providers/google-sheets-api/operations/readRows.js

@@ -0,0 +1,186 @@
+/**
+ * Values-only table reads and observation snapshots for the Google Sheets
+ * API sync provider.
+ *
+ * `readRowsBatch` serves several registered tables through ONE
+ * `spreadsheets.get` call (fail-closed on missing tabs, header drift, or
+ * malformed payloads). The snapshot operations share one grid read per
+ * batch, write missing row anchors in ONE atomic batch, and re-read once so
+ * committed anchors appear in every snapshot.
+ */
+import { SYNC_SHEETS_ERROR_CODES, SyncSheetsContractError, } from "../../../../../application/sync/sheets/errors.js";
+import { SYNC_SNAPSHOT_READ_MODES, } from "../../../../../application/sync/sheets/constants.js";
+import { GOOGLE_SHEETS_API_LIGHTWEIGHT_OBSERVATION_FIELDS, GOOGLE_SHEETS_API_OBSERVATION_FIELDS, GOOGLE_SHEETS_API_VALUES_FIELDS, parseSpreadsheetDocument, } from "../model/preflight.js";
+import { GOOGLE_SHEETS_API_ANCHOR_KEY } from "../constants.js";
+import { invalidProviderState } from "../errors.js";
+import { buildSnapshotFromTab, planRowAnchors, readTabGrids, } from "../model/observation.js";
+import { buildTableRowsFromGrid } from "../model/tableRead.js";
+import { columnLetters, parseRegisteredRange, quoteA1SheetName, } from "../model/valueNormalization.js";
+import { definitionForPhysicalSheet, requireValidBatchUpdateReply, runRead, runWrite, validateRoute, } from "./shared.js";
+import { observationTargetFor } from "./preflightOp.js";
+/** Reads one registered table's literal values with one REST read. */
+export async function readRows(deps, request) {
+    const [result] = await readRowsBatch(deps, [request]);
+    if (result === undefined) {
+        invalidProviderState("table read returned no result");
+    }
+    return result;
+}
+/**
+ * Reads several registered tables through ONE `spreadsheets.get` call.
+ * Results are returned in request order; a missing tab, header drift, or
+ * malformed payload fails closed before any result is produced.
+ */
+export async function readRowsBatch(deps, requests) {
+    if (requests.length === 0)
+        return [];
+    const routes = requests.map((request) => {
+        const definition = definitionForPhysicalSheet(deps, request.physicalSheetId);
+        validateRoute(request, definition);
+        if (request.headers.length !== definition.headers.length ||
+            request.headers.some((header, index) => header !== definition.headers[index])) {
+            throw new SyncSheetsContractError(SYNC_SHEETS_ERROR_CODES.INVALID_EFFECT_PAYLOAD, "sync provider table read headers do not match the registered projection " +
+                definition.sheet.physicalSheetId);
+        }
+        return { request, definition };
+    });
+    const raw = await runRead(deps, () => deps.transport.getSpreadsheet({
+        spreadsheetId: deps.spreadsheetId,
+        ranges: routes.map(({ request }) => `${quoteA1SheetName(request.sheetName)}!A1:${rangeEndColumnLetters(request.registeredRange)}1048576`),
+        fields: GOOGLE_SHEETS_API_VALUES_FIELDS,
+        timeoutMs: deps.readTimeoutMs,
+    }));
+    const document = parseSpreadsheetDocument(raw, "table read");
+    const results = [];
+    for (const { request, definition } of routes) {
+        const sheet = document.sheets.find((candidate) => candidate.title === request.sheetName);
+        if (sheet === undefined) {
+            invalidProviderState(`Registered sync sheet does not exist: ${request.sheetName}`);
+        }
+        const grid = document.grids.get(sheet.sheetId);
+        if (grid === undefined) {
+            invalidProviderState(`grid data is missing for sheet ${sheet.sheetId}`);
+        }
+        const rows = buildTableRowsFromGrid(grid, {
+            registeredRange: request.registeredRange,
+            headers: definition.headers,
+            checkboxHeaders: definition.checkboxHeaders ?? [],
+        });
+        results.push({
+            sheetName: request.sheetName,
+            registeredRange: request.registeredRange,
+            headers: [...definition.headers],
+            rows,
+        });
+    }
+    return results;
+}
+/** Reads one full snapshot without any mutation (lock-free). */
+export async function readSnapshot(deps, request) {
+    const target = observationTargetFor(deps, request);
+    const tabs = await readObservedTabs(deps, [request]);
+    const tab = tabs.get(request.sheetName);
+    if (tab === undefined) {
+        invalidProviderState(`Registered sync sheet does not exist: ${request.sheetName}`);
+    }
+    return buildSnapshotFromTab(tab, target);
+}
+/** Combines anchor assignment and one snapshot read under one request. */
+export async function observeSnapshot(deps, request) {
+    const [observed] = await observeSnapshots(deps, [request]);
+    if (observed === undefined) {
+        invalidProviderState("observation returned no result");
+    }
+    return observed;
+}
+/**
+ * Observes several projections with ONE grid read, ONE anchor write (when
+ * any anchor is missing), and ONE re-read (when anchors were written), so
+ * the committed anchors are reflected in every snapshot. The coordinator
+ * already holds every involved mutation lane before this call.
+ */
+export async function observeSnapshots(deps, requests) {
+    if (requests.length === 0)
+        return [];
+    const targets = requests.map((request) => observationTargetFor(deps, request));
+    const tabs = await readObservedTabs(deps, requests);
+    const plans = [];
+    let assignedTotal = 0;
+    for (let index = 0; index < requests.length; index += 1) {
+        const request = requests[index];
+        const target = targets[index];
+        if (request === undefined || target === undefined) {
+            invalidProviderState("observation request is unavailable");
+        }
+        const tab = tabs.get(request.sheetName);
+        if (tab === undefined) {
+            invalidProviderState(`Registered sync sheet does not exist: ${request.sheetName}`);
+        }
+        const anchors = planRowAnchors(tab, {
+            registeredRange: request.registeredRange,
+            headers: target.headers,
+            checkboxHeaders: target.checkboxHeaders,
+        });
+        assignedTotal += anchors.assigned;
+        plans.push({ request, target, tab, anchors });
+    }
+    if (assignedTotal > 0) {
+        // One atomic write for every planned anchor across all requested tabs.
+        const anchorRequests = [];
+        for (const entry of plans) {
+            for (const planned of entry.anchors.planned) {
+                anchorRequests.push({
+                    kind: "createDeveloperMetadata",
+                    sheetId: entry.tab.sheetId,
+                    rowIndex: planned.rowIndex,
+                    key: GOOGLE_SHEETS_API_ANCHOR_KEY,
+                    value: planned.anchor,
+                });
+            }
+        }
+        const response = await runWrite(deps, () => deps.transport.batchUpdate({
+            spreadsheetId: deps.spreadsheetId,
+            requests: anchorRequests,
+        }));
+        requireValidBatchUpdateReply(response, anchorRequests.length);
+        // One shared re-read so the committed anchors appear in the snapshots
+        // (mirrors the Apps Script flush-while-locked behavior).
+        const refreshed = await readObservedTabs(deps, requests);
+        for (const entry of plans) {
+            const tab = refreshed.get(entry.request.sheetName);
+            if (tab === undefined) {
+                invalidProviderState(`Registered sync sheet does not exist: ${entry.request.sheetName}`);
+            }
+            entry.tab = tab;
+        }
+    }
+    return plans.map((entry) => ({
+        anchors: {
+            assigned: entry.anchors.assigned,
+            existing: entry.anchors.existing,
+            duplicateAnchors: entry.anchors.duplicateAnchors,
+        },
+        snapshot: buildSnapshotFromTab(entry.tab, entry.target),
+    }));
+}
+/** Reads the target grids of one or more observation requests (one call). */
+export async function readObservedTabs(deps, requests) {
+    // One getSpreadsheet call serves the whole batch with ONE mask: the
+    // lighter user_input mask only when every request is lightweight (the
+    // lightweight branch never consults merges or dataValidation; the full
+    // mask is still correct for a mixed batch).
+    const lightweight = requests.length > 0 && requests.every((request) => request.readMode === SYNC_SNAPSHOT_READ_MODES.USER_INPUT);
+    const fields = lightweight
+        ? GOOGLE_SHEETS_API_LIGHTWEIGHT_OBSERVATION_FIELDS
+        : GOOGLE_SHEETS_API_OBSERVATION_FIELDS;
+    return runRead(deps, () => readTabGrids(deps.transport, deps.spreadsheetId, requests.map((request) => ({
+        sheetName: request.sheetName,
+        registeredRange: request.registeredRange,
+    })), fields, deps.readTimeoutMs));
+}
+/** Builds the A1 range end letters for one registered range. */
+function rangeEndColumnLetters(registeredRange) {
+    const range = parseRegisteredRange(registeredRange);
+    return columnLetters(range.startColumn + range.columnCount - 1);
+}
+//# sourceMappingURL=readRows.js.map

package/dist/adapter/sheets/providers/google-sheets-api/operations/readRows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readRows.js","sourceRoot":"","sources":["../../../../../../src/adapter/sheets/providers/google-sheets-api/operations/readRows.ts"],"names":[],"mappings":"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"}

package/dist/adapter/sheets/providers/google-sheets-api/operations/shared.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Shared wiring and pacing helpers for the Google Sheets API provider
+ * operations.
+ *
+ * The provider class hands one immutable `GoogleSheetsApiProviderDeps` object
+ * to every operation function so the class stays a thin facade. Pacing
+ * (read/write request-start limiters), redacted telemetry, route validation
+ * against the registered definition, and batchUpdate reply validation live
+ * here because every operation shares them.
+ */
+import type { RegisteredSyncProjectionDefinition } from "../../../../../application/sync/sheets/sheetsProvisioning.js";
+import { type Presence } from "../../../../../shared/state/index.js";
+import type { GoogleSheetsApiRequestEvent } from "../GoogleSheetsApiSyncProvider.js";
+import type { GoogleSheetsApiTransport } from "../transport/googleSheetsApiTransport.js";
+import { RequestStartLimiter } from "../transport/rateLimiter.js";
+/** Immutable wiring every operation function receives from the provider. */
+export interface GoogleSheetsApiProviderDeps {
+    readonly spreadsheetId: string;
+    readonly definitions: readonly RegisteredSyncProjectionDefinition[];
+    readonly transport: GoogleSheetsApiTransport;
+    readonly readTimeoutMs: number;
+    readonly maxBatchBytes: number;
+    readonly readLimiter: RequestStartLimiter;
+    readonly writeLimiter: RequestStartLimiter;
+    readonly now: () => number;
+    readonly onRequest: ((event: GoogleSheetsApiRequestEvent) => void) | undefined;
+}
+/** Paces ONE `getSpreadsheet` transport call and emits one read event. */
+export declare function runRead<T>(deps: GoogleSheetsApiProviderDeps, task: () => Promise<T>): Promise<T>;
+/** Paces ONE `batchUpdate` transport call and emits one write event. */
+export declare function runWrite<T>(deps: GoogleSheetsApiProviderDeps, task: () => Promise<T>): Promise<T>;
+/** Emits one redacted telemetry event; diagnostics must never throw. */
+export declare function emitRequest(deps: GoogleSheetsApiProviderDeps, operation: "getSpreadsheet" | "batchUpdate", operationCount: number, startedAt: number, ok: boolean, httpStatus: Presence<number>, code: Presence<string>): void;
+/** Resolves the registered projection definition for one physical sheet. */
+export declare function definitionForPhysicalSheet(deps: GoogleSheetsApiProviderDeps, physicalSheetId: string): RegisteredSyncProjectionDefinition;
+/**
+ * Route validation against the registered definition (mirrors
+ * `validateRoute` in the Apps Script operation provider).
+ */
+export declare function validateRoute(request: {
+    readonly sheetName: string;
+    readonly registeredRange: string;
+    readonly projection: string;
+    readonly schemaVersion: number;
+}, definition: RegisteredSyncProjectionDefinition): void;
+/** Derives the per-route effect options exactly like the Apps Script provider. */
+export declare function effectRouteOptions(definition: RegisteredSyncProjectionDefinition): {
+    readonly identityField: Presence<string>;
+    readonly checkboxHeaders: readonly string[];
+};
+/**
+ * Validates a batchUpdate reply shape: one reply per request, with the
+ * addSheet reply carrying the created sheet id. A malformed 2xx response must
+ * not close effects, so this throws a delivery-uncertain state error.
+ */
+export declare function requireValidBatchUpdateReply(value: unknown, requestCount: number): void;
+//# sourceMappingURL=shared.d.ts.map

package/dist/adapter/sheets/providers/google-sheets-api/operations/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../../../../src/adapter/sheets/providers/google-sheets-api/operations/shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,kCAAkC,EAAE,MAAM,8DAA8D,CAAC;AAMvH,OAAO,EAA6B,KAAK,QAAQ,EAAE,MAAM,sCAAsC,CAAC;AAChG,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,mCAAmC,CAAC;AACrF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AACzF,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAGlE,4EAA4E;AAC5E,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,SAAS,kCAAkC,EAAE,CAAC;IACpE,QAAQ,CAAC,SAAS,EAAE,wBAAwB,CAAC;IAC7C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;IAC1C,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE,2BAA2B,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CAChF;AAED,0EAA0E;AAC1E,wBAAsB,OAAO,CAAC,CAAC,EAC7B,IAAI,EAAE,2BAA2B,EACjC,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,CAAC,CAAC,CAYZ;AAED,wEAAwE;AACxE,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,IAAI,EAAE,2BAA2B,EACjC,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,CAAC,CAAC,CAYZ;AAED,wEAAwE;AACxE,wBAAgB,WAAW,CACzB,IAAI,EAAE,2BAA2B,EACjC,SAAS,EAAE,gBAAgB,GAAG,aAAa,EAC3C,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,OAAO,EACX,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,EAC5B,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,GACrB,IAAI,CAcN;AAED,4EAA4E;AAC5E,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,2BAA2B,EACjC,eAAe,EAAE,MAAM,GACtB,kCAAkC,CAWpC;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE;IACP,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC,EACD,UAAU,EAAE,kCAAkC,GAC7C,IAAI,CAaN;AAED,kFAAkF;AAClF,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,kCAAkC,GAC7C;IACD,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACzC,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C,CAYA;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CA4BvF"}