hikoutei 0.5.0 → 0.5.2

package/dist/adapter/sheets/providers/google-sheets-api/GoogleSheetsApiSyncProvider.js

@@ -23,26 +23,16 @@
  * provisioning reads) and every `batchUpdate` acquires its class limiter and
  * emits one redacted telemetry event.
  */
-import { computeSyncVisibleHash, } from "../../../../application/sync/sheets/syncSheets.js";
 import { SYNC_SHEETS_ERROR_CODES, SyncSheetsContractError, } from "../../../../application/sync/sheets/errors.js";
-import { requireSyncSnapshotReadMode, } from "../../../../application/sync/sheets/validation.js";
-import { SYNC_FAST_APPEND_STATUSES, SYNC_POSTCONDITION_MODES, SYNC_PROJECTIONS, SYNC_SNAPSHOT_READ_MODES, } from "../../../../application/sync/sheets/constants.js";
-import { classifyTransportOutcome, } from "../../../../application/sync/sheets/transportOutcome.js";
-import { presentValue, absentValue } from "../../../../shared/state/index.js";
-import { isNormalizedCell } from "../../../../shared/encoding/index.js";
-import { GOOGLE_SHEETS_API_DEFAULTS, GOOGLE_SHEETS_API_EFFECT_REASONS, GOOGLE_SHEETS_API_ANCHOR_KEY, } from "./constants.js";
-import { invalidProviderRequest, invalidProviderState } from "./errors.js";
-import { identityFromNormalizedCell } from "./model/valueNormalization.js";
+import { GOOGLE_SHEETS_API_DEFAULTS, } from "./constants.js";
+import { invalidProviderRequest } from "./errors.js";
 import { GoogleSheetsApiHttpTransport, } from "./transport/googleSheetsApiTransport.js";
 import { RequestStartLimiter } from "./transport/rateLimiter.js";
-import { enumerateSheetProperties, readPreflightData, GOOGLE_SHEETS_API_PROVISION_ENUMERATION_FIELDS, GOOGLE_SHEETS_API_PROVISION_FIELDS, GOOGLE_SHEETS_API_VALUES_FIELDS, GOOGLE_SHEETS_API_OBSERVATION_FIELDS, GOOGLE_SHEETS_API_LIGHTWEIGHT_OBSERVATION_FIELDS, parseSpreadsheetDocument, gridHeaderCells, } from "./model/preflight.js";
-import { planEffectBatch, encodeOutcomeResult, encodeSchemaErrorResult, withDeferredPostcondition, currentHash, } from "./model/planner.js";
-import { buildApplyBatchRequests, buildAppendBatchRequests, resolveApplyBatchBudget, resolveAppendBudget, } from "./model/batchBuilder.js";
-import { classifyPostcondition } from "./model/postcondition.js";
-import { buildSnapshotFromTab, planRowAnchors, readTabGrids, } from "./model/observation.js";
-import { buildTableRowsFromGrid } from "./model/tableRead.js";
-import { allocateSheetId } from "./model/sheetIdAllocator.js";
-import { columnLetters, parseRegisteredRange, quoteA1SheetName, } from "./model/valueNormalization.js";
+import { fastAppendRows, } from "./operations/fastAppend.js";
+import { applyEffects, readEffectPostcondition, readEffectPostconditions, } from "./operations/applyEffects.js";
+import { observeSnapshot, observeSnapshots, readRows, readRowsBatch, readSnapshot, } from "./operations/readRows.js";
+import { ensureRowAnchors, } from "./operations/anchors.js";
+import { provisionRegistry, } from "./operations/provisioning.js";
 /**
  * Full sync provider over the Sheets REST API: outbound effects, provisioning,
  * table reads, anchors, and snapshots behind the shared provider contracts.
@@ -52,6 +42,9 @@ import { columnLetters, parseRegisteredRange, quoteA1SheetName, } from "./model/
  * bootstrap's bulk worker options. Provisioning runs at startup before the
  * worker, and observation anchors are the only metadata mutations outside
  * effect batches.
+ *
+ * The class is a thin facade: every method body lives in an operation module
+ * under `operations/` and receives the immutable wiring from `this.deps`.
  */
 export class GoogleSheetsApiSyncProvider {
     spreadsheetId;
@@ -64,6 +57,7 @@ export class GoogleSheetsApiSyncProvider {
     writeLimiter;
     now;
     onRequest;
+    deps;
     constructor(options) {
         if (options.definitions.length === 0) {
             throw new SyncSheetsContractError(SYNC_SHEETS_ERROR_CODES.INVALID_PROVISIONING_DEFINITIONS, "Google Sheets API sync provider requires a projection definition");
@@ -108,6 +102,17 @@ export class GoogleSheetsApiSyncProvider {
             ...(options.sleep === undefined ? {} : { sleep: options.sleep }),
         });
         this.onRequest = options.onRequest;
+        this.deps = {
+            spreadsheetId: this.spreadsheetId,
+            definitions: this.definitions,
+            transport: this.transport,
+            readTimeoutMs: this.readTimeoutMs,
+            maxBatchBytes: this.maxBatchBytes,
+            readLimiter: this.readLimiter,
+            writeLimiter: this.writeLimiter,
+            now: this.now,
+            onRequest: this.onRequest,
+        };
     }
     /** Exposes the configured outbound timeout (used by lease-headroom checks). */
     get timeoutMs() {
@@ -118,251 +123,19 @@ export class GoogleSheetsApiSyncProvider {
     // -------------------------------------------------------------------------
     /** Appends rows through one idempotent, atomic target+receipt batch. */
     async fastAppendRows(request) {
-        const definition = this.definitionForPhysicalSheet(request.physicalSheetId);
-        validateRoute(request, definition);
-        const routeOptions = effectRouteOptions(definition);
-        if (routeOptions.identityField.kind !== "present") {
-            // The fast path never materializes anchor metadata, so a route without
-            // a registered identity cannot locate or guard its rows on replay.
-            throw new SyncSheetsContractError(SYNC_SHEETS_ERROR_CODES.INVALID_EFFECT_PAYLOAD, "fast append requires a registered identityField for route " + request.physicalSheetId);
-        }
-        if (request.rows.length === 0) {
-            invalidProviderRequest("fast append", "rows must not be empty");
-        }
-        const bounded = request.rows.slice(0, GOOGLE_SHEETS_API_DEFAULTS.MAX_APPEND_ROWS_PER_REQUEST);
-        validateAppendRows(bounded);
-        const context = await this.readPreflight(request, definition, routeOptions);
-        validateAppendRowsAgainstHeaders(bounded, context.headers);
-        const identityField = routeOptions.identityField.value;
-        // Replay rows are recognized through the receipt tab and verified against
-        // the visible identity; pending rows go through the identity preflight.
-        const pending = [];
-        const resultsById = new Map();
-        const pendingReceipts = [];
-        for (const row of bounded) {
-            // The worker always supplies the outbox payload hash; fail closed when
-            // it is absent instead of silently falling back to the effect ID.
-            const payloadHash = row.payloadHash;
-            if (payloadHash === undefined || payloadHash.length === 0) {
-                invalidProviderRequest("fast append", `payloadHash is required for effectId: ${row.effectId}`);
-            }
-            const existing = context.receipts.get(row.effectId);
-            if (existing !== undefined) {
-                if (existing.payloadHash !== payloadHash) {
-                    invalidProviderRequest("fast append", `effect ID cannot be reused with another payload: ${row.effectId}`);
-                }
-                const identity = appendIdentity(row, identityField);
-                const existingRow = findRowByIdentity(context, identity);
-                if (existingRow === undefined) {
-                    invalidProviderRequest("fast append", `receipt postcondition row is unavailable for effectId: ${row.effectId}`);
-                }
-                if (computeSyncVisibleHash(existingRow.cells) !== existing.visibleHash) {
-                    invalidProviderRequest("fast append", `receipt postcondition changed for effectId: ${row.effectId}`);
-                }
-                resultsById.set(row.effectId, {
-                    effectId: row.effectId,
-                    status: SYNC_FAST_APPEND_STATUSES.APPLIED,
-                    visibleHash: existing.visibleHash,
-                    visibleRevision: existing.visibleRevision,
-                });
-                continue;
-            }
-            pending.push(row);
-            pendingReceipts.push(makeAppendReceipt(row.effectId, payloadHash, computeSyncVisibleHash(row.fields)));
-        }
-        // Mirror the built-in append identity preflight: the registered identity
-        // must exist and be unique across the sheet and the pending batch; replay
-        // entries are exempt exactly like the real provider.
-        let deferredSuffix = false;
-        if (pending.length > 0) {
-            assertAppendIdentityAvailability(context, identityField, pending);
-            const pendingRows = pending.map((row, index) => toAppendWorkingRow(row, context.nextAppendRow + index));
-            const updatedAt = new Date(this.now()).toISOString();
-            const resolution = resolveAppendBudget(pendingRows, (count) => buildAppendBatchRequests(context, pendingRows.slice(0, count), pendingReceipts.slice(0, count), { updatedAt }), this.maxBatchBytes);
-            deferredSuffix = resolution.includeCount < pending.length;
-            if (resolution.includeCount > 0) {
-                const batch = buildAppendBatchRequests(context, pendingRows.slice(0, resolution.includeCount), pendingReceipts.slice(0, resolution.includeCount), { updatedAt });
-                const response = await this.runWrite(() => this.transport.batchUpdate({
-                    spreadsheetId: this.spreadsheetId,
-                    requests: batch.requests,
-                }));
-                requireValidBatchUpdateReply(response, batch.requests.length);
-                pendingReceipts.slice(0, resolution.includeCount).forEach((receipt) => {
-                    resultsById.set(receipt.effectId, {
-                        effectId: receipt.effectId,
-                        status: SYNC_FAST_APPEND_STATUSES.APPLIED,
-                        visibleHash: receipt.visibleHash,
-                        visibleRevision: receipt.visibleRevision,
-                    });
-                });
-            }
-        }
-        // A byte-budget deferral commits only a prefix of the pending rows, so
-        // results cover exactly the processed rows: receipt-matched replays plus
-        // the included prefix. Rows beyond the included prefix are intentionally
-        // absent from results; the worker releases them (releaseUnprocessedEffect)
-        // for the next pass when hasMore is true.
-        const results = [];
-        for (const row of bounded) {
-            const result = resultsById.get(row.effectId);
-            if (result === undefined)
-                continue;
-            results.push(result);
-        }
-        return {
-            results,
-            hasMore: bounded.length < request.rows.length || deferredSuffix,
-        };
+        return fastAppendRows(this.deps, request);
     }
     /** Applies regular update/delete/create effects through one atomic batch. */
     async applyEffects(request) {
-        const definition = this.definitionForPhysicalSheet(request.physicalSheetId);
-        validateRoute(request, definition);
-        if (request.effects.length === 0) {
-            invalidProviderRequest("apply effects", "effects must not be empty");
-        }
-        const bounded = request.effects.slice(0, GOOGLE_SHEETS_API_DEFAULTS.MAX_EFFECTS_PER_REQUEST);
-        const postconditionMode = request.postconditionMode ?? SYNC_POSTCONDITION_MODES.INLINE;
-        if (postconditionMode !== SYNC_POSTCONDITION_MODES.INLINE &&
-            postconditionMode !== SYNC_POSTCONDITION_MODES.DEFERRED) {
-            invalidProviderRequest("apply effects", "postconditionMode must be inline or deferred");
-        }
-        const routeOptions = effectRouteOptions(definition);
-        const context = await this.readPreflight(request, definition, routeOptions);
-        const plans = planEffectBatch({ ...request, effects: bounded }, context);
-        const includeReceipts = postconditionMode === SYNC_POSTCONDITION_MODES.DEFERRED;
-        const updatedAt = new Date(this.now()).toISOString();
-        const resolution = resolveApplyBatchBudget(context, plans, {
-            maxBatchBytes: this.maxBatchBytes,
-            includeReceipts,
-            updatedAt,
-        });
-        const schemaErrorIndices = new Set(resolution.schemaErrorIndices);
-        // Schema-error effects sit BEFORE the included run; the batch only carries
-        // the plans after them, up to the resolved include count. The included
-        // effects are re-planned so appended rows start at the sheet's first free
-        // row (the full-plan row numbers would leave blank gaps for excluded
-        // effects). The planner is deterministic over the unchanged context, so
-        // outcomes and receipts are identical to the budget-resolution plans.
-        const includedStart = resolution.schemaErrorIndices.length;
-        const includedEffects = bounded.slice(includedStart, resolution.includeCount);
-        const included = planEffectBatch({ ...request, effects: includedEffects }, context);
-        if (included.length > 0) {
-            const batch = buildApplyBatchRequests(context, included, { updatedAt, includeReceipts });
-            // Rejected plans (guard/schema/repair outcomes) contribute no requests;
-            // never send an empty batchUpdate for an all-rejected prefix.
-            if (batch.requests.length > 0) {
-                const response = await this.runWrite(() => this.transport.batchUpdate({
-                    spreadsheetId: this.spreadsheetId,
-                    requests: batch.requests,
-                }));
-                requireValidBatchUpdateReply(response, batch.requests.length);
-            }
-        }
-        // Inline verification reads the written rows back and demotes any hash
-        // mismatch to retryable_error, mirroring the Apps Script inline path. The
-        // worker always uses deferred mode, where the atomic batch already carries
-        // target mutations and receipts together.
-        const verified = new Set();
-        if (postconditionMode === SYNC_POSTCONDITION_MODES.INLINE && included.length > 0) {
-            const verifyContext = await this.readPreflight(request, definition, routeOptions);
-            included.forEach((plan, index) => {
-                if (!plan.verify || plan.mutation === undefined || plan.mutation.kind === "delete")
-                    return;
-                const row = findProbeRowInContext(verifyContext, plan);
-                const current = row === undefined ? undefined : currentHash(row, plan.outcome.effect.payload.fields);
-                if (current === plan.outcome.effect.payload.targetVisibleHash) {
-                    verified.add(index);
-                }
-            });
-            const verifyReceipts = [];
-            included.forEach((plan, index) => {
-                if (plan.receipt === undefined)
-                    return;
-                // Replay receipts are already stored in the sheet; never rewrite them.
-                if (context.receipts.has(plan.receipt.effectId))
-                    return;
-                if (plan.outcome.kind === "applied" && !plan.outcome.deletion && !verified.has(index))
-                    return;
-                verifyReceipts.push(plan.receipt);
-            });
-            if (verifyReceipts.length > 0) {
-                const receiptBatch = buildAppendBatchRequests(context, [], verifyReceipts, { updatedAt });
-                const response = await this.runWrite(() => this.transport.batchUpdate({
-                    spreadsheetId: this.spreadsheetId,
-                    requests: receiptBatch.requests,
-                }));
-                requireValidBatchUpdateReply(response, receiptBatch.requests.length);
-            }
-        }
-        const results = [];
-        let includedCursor = 0;
-        bounded.forEach((effect, index) => {
-            if (schemaErrorIndices.has(index)) {
-                results.push(encodeSchemaErrorResult(effect, GOOGLE_SHEETS_API_EFFECT_REASONS.EFFECT_PAYLOAD_TOO_LARGE));
-                return;
-            }
-            if (index >= resolution.includeCount)
-                return;
-            const planIndex = includedCursor;
-            includedCursor += 1;
-            const plan = included[planIndex];
-            if (plan === undefined)
-                return;
-            let result = encodeOutcomeResult(plan.outcome);
-            if (postconditionMode === SYNC_POSTCONDITION_MODES.INLINE &&
-                plan.outcome.kind === "applied" &&
-                !plan.outcome.deletion &&
-                !verified.has(planIndex)) {
-                result = {
-                    ...result,
-                    status: "retryable_error",
-                    visibleRevision: absentValue(),
-                    visibleHash: absentValue(),
-                    reason: presentValue(GOOGLE_SHEETS_API_EFFECT_REASONS.POSTCONDITION_HASH_MISMATCH),
-                    postcondition: "unavailable",
-                };
-            }
-            else if (postconditionMode === SYNC_POSTCONDITION_MODES.DEFERRED) {
-                result = withDeferredPostcondition(result);
-            }
-            results.push(result);
-        });
-        return {
-            results,
-            snapshotHash: absentValue(),
-            hasMore: bounded.length < request.effects.length || results.length < bounded.length,
-        };
+        return applyEffects(this.deps, request);
     }
     /** Classifies one response-loss effect through a fresh target+receipt read. */
     async readEffectPostcondition(effect) {
-        const [result] = await this.readEffectPostconditions({
-            physicalSheetId: effect.physicalSheetId,
-            sheetName: effect.payload.sheetName,
-            registeredRange: effect.payload.registeredRange,
-            projection: effect.projection,
-            schemaVersion: effect.payload.schemaVersion,
-            effects: [effect],
-        });
-        if (result === undefined) {
-            invalidProviderState("postcondition read returned no result");
-        }
-        return result.postcondition;
+        return readEffectPostcondition(this.deps, effect);
     }
     /** Classifies a recovery batch with one shared target+receipt read. */
     async readEffectPostconditions(request) {
-        const definition = this.definitionForPhysicalSheet(request.physicalSheetId);
-        validateRoute(request, definition);
-        if (request.effects.length === 0) {
-            invalidProviderRequest("postcondition reads", "effects must not be empty");
-        }
-        const routeOptions = effectRouteOptions(definition);
-        const context = await this.readPreflight(request, definition, routeOptions);
-        return request.effects.map((effect) => ({
-            effectId: effect.effectId,
-            payloadHash: effect.payloadHash,
-            postcondition: classifyPostcondition(context, effect, context.receipts),
-        }));
+        return readEffectPostconditions(this.deps, request);
     }
     // -------------------------------------------------------------------------
     // Projection provisioning (SyncSheetsProvisioner)
@@ -377,119 +150,14 @@ export class GoogleSheetsApiSyncProvider {
      * exact headers, and succeeds without rewriting anything.
      */
     async provisionRegistry(registrations) {
-        validateProvisionRegistrations(registrations);
-        // Enumerate every tab (no ranges, hidden included) with grid dimensions.
-        const enumerationRaw = await this.runRead(() => this.transport.getSpreadsheet({
-            spreadsheetId: this.spreadsheetId,
-            ranges: [],
-            fields: GOOGLE_SHEETS_API_PROVISION_ENUMERATION_FIELDS,
-            timeoutMs: this.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 this.runRead(() => this.transport.getSpreadsheet({
-                spreadsheetId: this.spreadsheetId,
-                ranges,
-                fields: GOOGLE_SHEETS_API_PROVISION_FIELDS,
-                timeoutMs: this.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 this.runWrite(() => this.transport.batchUpdate({
-                spreadsheetId: this.spreadsheetId,
-                requests,
-            }));
-            requireValidBatchUpdateReply(response, requests.length);
-        }
-        return {
-            registrations: registrations.map(({ headers: _headers, ...route }) => route),
-            createdSheets,
-            initializedHeaders,
-        };
+        return provisionRegistry(this.deps, registrations);
     }
     // -------------------------------------------------------------------------
     // Values-only table reads (readRows / readRowsBatch)
     // -------------------------------------------------------------------------
     /** Reads one registered table's literal values with one REST read. */
     async readRows(request) {
-        const [result] = await this.readRowsBatch([request]);
-        if (result === undefined) {
-            invalidProviderState("table read returned no result");
-        }
-        return result;
+        return readRows(this.deps, request);
     }
     /**
      * Reads several registered tables through ONE `spreadsheets.get` call.
@@ -497,48 +165,7 @@ export class GoogleSheetsApiSyncProvider {
      * malformed payload fails closed before any result is produced.
      */
     async readRowsBatch(requests) {
-        if (requests.length === 0)
-            return [];
-        const routes = requests.map((request) => {
-            const definition = this.definitionForPhysicalSheet(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 this.runRead(() => this.transport.getSpreadsheet({
-            spreadsheetId: this.spreadsheetId,
-            ranges: routes.map(({ request }) => `${quoteA1SheetName(request.sheetName)}!A1:${rangeEndColumnLetters(request.registeredRange)}1048576`),
-            fields: GOOGLE_SHEETS_API_VALUES_FIELDS,
-            timeoutMs: this.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;
+        return readRowsBatch(this.deps, requests);
     }
     // -------------------------------------------------------------------------
     // Observation (anchors + snapshots)
@@ -550,44 +177,15 @@ export class GoogleSheetsApiSyncProvider {
      * anchors across rows are reported as evidence. No re-read is performed.
      */
     async ensureRowAnchors(request) {
-        const definition = this.definitionForPhysicalSheet(request.physicalSheetId);
-        validateRoute(request, definition);
-        const tabs = await this.readObservedTabs([request]);
-        const tab = tabs.get(request.sheetName);
-        if (tab === undefined) {
-            invalidProviderState(`Registered sync sheet does not exist: ${request.sheetName}`);
-        }
-        const plan = planRowAnchors(tab, {
-            registeredRange: request.registeredRange,
-            headers: definition.headers,
-            checkboxHeaders: definition.checkboxHeaders ?? [],
-        });
-        if (plan.planned.length > 0) {
-            await this.writeAnchors(tab, plan);
-        }
-        return {
-            assigned: plan.assigned,
-            existing: plan.existing,
-            duplicateAnchors: plan.duplicateAnchors,
-        };
+        return ensureRowAnchors(this.deps, request);
     }
     /** Reads one full snapshot without any mutation (lock-free). */
     async readSnapshot(request) {
-        const target = this.observationTargetFor(request);
-        const tabs = await this.readObservedTabs([request]);
-        const tab = tabs.get(request.sheetName);
-        if (tab === undefined) {
-            invalidProviderState(`Registered sync sheet does not exist: ${request.sheetName}`);
-        }
-        return buildSnapshotFromTab(tab, target);
+        return readSnapshot(this.deps, request);
     }
     /** Combines anchor assignment and one snapshot read under one request. */
     async observeSnapshot(request) {
-        const [observed] = await this.observeSnapshots([request]);
-        if (observed === undefined) {
-            invalidProviderState("observation returned no result");
-        }
-        return observed;
+        return observeSnapshot(this.deps, request);
     }
     /**
      * Observes several projections with ONE grid read, ONE anchor write (when
@@ -596,517 +194,7 @@ export class GoogleSheetsApiSyncProvider {
      * already holds every involved mutation lane before this call.
      */
     async observeSnapshots(requests) {
-        if (requests.length === 0)
-            return [];
-        const targets = requests.map((request) => this.observationTargetFor(request));
-        const tabs = await this.readObservedTabs(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 this.runWrite(() => this.transport.batchUpdate({
-                spreadsheetId: this.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 this.readObservedTabs(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),
-        }));
-    }
-    // -------------------------------------------------------------------------
-    // Internal helpers
-    // -------------------------------------------------------------------------
-    /** Reads the target grids of one or more observation requests (one call). */
-    async readObservedTabs(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 this.runRead(() => readTabGrids(this.transport, this.spreadsheetId, requests.map((request) => ({
-            sheetName: request.sheetName,
-            registeredRange: request.registeredRange,
-        })), fields, this.readTimeoutMs));
-    }
-    /** Writes every planned anchor of one tab in one atomic batch. */
-    async writeAnchors(tab, plan) {
-        const requests = plan.planned.map((planned) => ({
-            kind: "createDeveloperMetadata",
-            sheetId: tab.sheetId,
-            rowIndex: planned.rowIndex,
-            key: GOOGLE_SHEETS_API_ANCHOR_KEY,
-            value: planned.anchor,
-        }));
-        const response = await this.runWrite(() => this.transport.batchUpdate({
-            spreadsheetId: this.spreadsheetId,
-            requests,
-        }));
-        requireValidBatchUpdateReply(response, requests.length);
-    }
-    /** Validates one observation request and derives its snapshot target. */
-    observationTargetFor(request) {
-        const definition = this.definitionForPhysicalSheet(request.physicalSheetId);
-        validateRoute(request, definition);
-        // Fail closed on unknown readMode strings (same shared guard as the Apps
-        // Script observation operation) instead of silently reading in full mode.
-        const readMode = request.readMode === undefined
-            ? SYNC_SNAPSHOT_READ_MODES.FULL
-            : requireSyncSnapshotReadMode(request.readMode, "Google Sheets API observation readMode", SYNC_SHEETS_ERROR_CODES.INVALID_EFFECT_PAYLOAD);
-        if (readMode === SYNC_SNAPSHOT_READ_MODES.USER_INPUT &&
-            request.projection !== SYNC_PROJECTIONS.USER_INPUT) {
-            invalidProviderRequest("observation", "user_input readMode requires the user_input projection");
-        }
-        return {
-            sheetName: request.sheetName,
-            registeredRange: request.registeredRange,
-            projection: request.projection,
-            schemaVersion: request.schemaVersion,
-            headers: definition.headers,
-            checkboxHeaders: definition.checkboxHeaders ?? [],
-            readMode,
-        };
-    }
-    /** Reads the target and receipt tabs for one route through the read lane. */
-    async readPreflight(request, definition, routeOptions) {
-        // Each preflight performs two paced transport calls: a range-less sheet
-        // enumeration (hidden receipt tab discovery) plus one ranged data read.
-        const sheets = await this.runRead(() => enumerateSheetProperties(this.transport, this.spreadsheetId, this.readTimeoutMs));
-        return this.runRead(() => readPreflightData(this.transport, {
-            spreadsheetId: this.spreadsheetId,
-            sheetName: request.sheetName,
-            registeredRange: request.registeredRange,
-            headers: definition.headers,
-            identityField: routeOptions.identityField,
-            checkboxHeaders: routeOptions.checkboxHeaders,
-        }, sheets, this.readTimeoutMs));
-    }
-    /** Paces ONE `getSpreadsheet` transport call and emits one read event. */
-    async runRead(task) {
-        await this.readLimiter.waitForSlot();
-        const startedAt = this.now();
-        try {
-            const result = await task();
-            this.emitRequest("getSpreadsheet", 1, startedAt, true, absentValue(), absentValue());
-            return result;
-        }
-        catch (error) {
-            const outcome = classifyTransportOutcome(error);
-            this.emitRequest("getSpreadsheet", 1, startedAt, false, outcome.httpStatus, outcome.code);
-            throw error;
-        }
-    }
-    /** Paces ONE `batchUpdate` transport call and emits one write event. */
-    async runWrite(task) {
-        await this.writeLimiter.waitForSlot();
-        const startedAt = this.now();
-        try {
-            const result = await task();
-            this.emitRequest("batchUpdate", 1, startedAt, true, absentValue(), absentValue());
-            return result;
-        }
-        catch (error) {
-            const outcome = classifyTransportOutcome(error);
-            this.emitRequest("batchUpdate", 1, startedAt, false, outcome.httpStatus, outcome.code);
-            throw error;
-        }
-    }
-    emitRequest(operation, operationCount, startedAt, ok, httpStatus, code) {
-        try {
-            this.onRequest?.({
-                operation,
-                operationCount,
-                startedAt,
-                durationMs: Math.max(0, this.now() - startedAt),
-                ok,
-                httpStatus,
-                code,
-            });
-        }
-        catch {
-            // Diagnostics must never change a remote result.
-        }
-    }
-    definitionForPhysicalSheet(physicalSheetId) {
-        const definition = this.definitions.find((candidate) => candidate.sheet.physicalSheetId === physicalSheetId);
-        if (definition === undefined) {
-            throw new SyncSheetsContractError(SYNC_SHEETS_ERROR_CODES.INVALID_PROVISIONING_DEFINITIONS, "no projection definition exists for " + physicalSheetId);
-        }
-        return definition;
-    }
-}
-// ---------------------------------------------------------------------------
-// Outbound helpers (ported from the Apps Script effect operations)
-// ---------------------------------------------------------------------------
-/** Builds the fixed-shape receipt record used by the fast-append path. */
-function makeAppendReceipt(effectId, payloadHash, visibleHash) {
-    return {
-        effectId,
-        payloadHash,
-        status: "applied",
-        visibleHash,
-        visibleRevision: 1,
-    };
-}
-/** Validates the append rows before any remote read or write. */
-function validateAppendRows(rows) {
-    const seenEffectIds = new Set();
-    for (const row of rows) {
-        if (row.effectId.length === 0 || seenEffectIds.has(row.effectId)) {
-            invalidProviderRequest("fast append", "effectIds must be non-empty and unique");
-        }
-        seenEffectIds.add(row.effectId);
-        const payloadHash = row.payloadHash;
-        if (payloadHash === undefined || payloadHash.length === 0) {
-            invalidProviderRequest("fast append", "payloadHash is required");
-        }
-        if (row.anchor !== undefined && row.anchor.length === 0) {
-            invalidProviderRequest("fast append", "row anchor must be non-empty");
-        }
-        const fields = row.fields;
-        if (fields === null || typeof fields !== "object" || Array.isArray(fields)) {
-            invalidProviderRequest("fast append", "row fields must be an object");
-        }
-        if (Object.keys(fields).length === 0) {
-            invalidProviderRequest("fast append", "row fields are required");
-        }
-        for (const value of Object.values(fields)) {
-            if (!isNormalizedCell(value)) {
-                invalidProviderRequest("fast append", "row fields contain an invalid normalized cell");
-            }
-        }
-    }
-}
-/** Append rows must cover exactly the registered headers (batch append rule). */
-function validateAppendRowsAgainstHeaders(rows, headers) {
-    const expected = [...headers].sort();
-    for (const row of rows) {
-        const actual = Object.keys(row.fields).sort();
-        if (actual.length !== expected.length ||
-            actual.some((field, index) => field !== expected[index])) {
-            invalidProviderRequest("fast append", "rows must contain exactly the registered headers");
-        }
-    }
-}
-/**
- * Derives the append identity from the row's identity field cell, using the
- * canonical identity rule (non-empty string or finite number) shared with
- * the append/replay paths.
- */
-function appendIdentity(row, identityField) {
-    const cell = row.fields[identityField] ?? null;
-    const identity = identityFromNormalizedCell(cell);
-    if (identity === null) {
-        invalidProviderRequest("fast append", `sync identity is required for append: ${identityField}`);
-    }
-    return identity;
-}
-/** Finds a preflight row by its visible identity (single match or fail closed). */
-function findRowByIdentity(context, identity) {
-    const matches = context.rows.filter((row) => row.identity.kind === "present" && row.identity.value === identity);
-    if (matches.length > 1) {
-        invalidProviderState(`sync identity is duplicated: ${identity}`);
-    }
-    return matches[0];
-}
-/**
- * Mirrors the built-in append identity preflight: every existing data row
- * needs a unique identity, and every pending non-replay row needs a fresh,
- * non-empty identity.
- */
-function assertAppendIdentityAvailability(context, identityField, pending) {
-    const existing = new Map();
-    context.rows.forEach((row) => {
-        if (row.identity.kind !== "present") {
-            invalidProviderState(`sync identity is missing at row ${row.rowNumber}`);
-        }
-        const location = existing.get(row.identity.value);
-        if (location !== undefined) {
-            invalidProviderState(`sync identity is duplicated: ${row.identity.value} at rows ${location} and ${row.rowNumber}`);
-        }
-        existing.set(row.identity.value, String(row.rowNumber));
-    });
-    for (const row of pending) {
-        const identity = appendIdentity(row, identityField);
-        const location = existing.get(identity);
-        if (location !== undefined) {
-            invalidProviderState(`sync identity already exists: ${identity} at ${location}`);
-        }
-        existing.set(identity, "pending");
-    }
-}
-/** Builds a working row for one pending append at its reserved position. */
-function toAppendWorkingRow(row, rowNumber) {
-    // The fast path never materializes anchor metadata (the Apps Script batch
-    // append path ignores the advisory row anchor); the row replays by identity.
-    return {
-        rowNumber,
-        anchor: absentValue(),
-        cells: { ...row.fields },
-        identity: absentValue(),
-        appended: true,
-        deleted: false,
-        writeFields: {},
-    };
-}
-/** Locates one planned write's row in a fresh verification context. */
-function findProbeRowInContext(context, plan) {
-    const mutation = plan.mutation;
-    if (mutation === undefined)
-        return undefined;
-    if (mutation.kind === "append") {
-        return context.rows.find((row) => row.rowNumber === mutation.row.rowNumber);
-    }
-    const anchor = mutation.row.anchor;
-    if (anchor.kind === "present") {
-        return context.rows.find((row) => row.physicalAnchor.kind === "present" && row.physicalAnchor.value === anchor.value);
-    }
-    const identity = mutation.row.identity;
-    if (identity.kind === "present") {
-        return context.rows.find((row) => row.identity.kind === "present" && row.identity.value === identity.value);
-    }
-    return undefined;
-}
-/**
- * Route validation against the registered definition (mirrors
- * `validateRoute` in the Apps Script operation provider).
- */
-function validateRoute(request, definition) {
-    if (request.sheetName !== definition.sheet.tabName ||
-        request.registeredRange !== definition.sheet.registeredRange ||
-        request.projection !== definition.sheet.projection ||
-        request.schemaVersion !== definition.sheet.schemaVersion) {
-        throw new SyncSheetsContractError(SYNC_SHEETS_ERROR_CODES.INVALID_EFFECT_PAYLOAD, "sync provider request does not match the registered projection " +
-            definition.sheet.physicalSheetId);
-    }
-}
-/** Derives the per-route effect options exactly like the Apps Script provider. */
-function effectRouteOptions(definition) {
-    const identityField = definition.sheet.projection === "system_state"
-        ? definition.sheet.businessKeyField
-        : definition.sheet.projection === "sync_conflicts"
-            ? "Conflict_ID"
-            : undefined;
-    return {
-        identityField: identityField === undefined
-            ? absentValue()
-            : presentValue(identityField),
-        checkboxHeaders: definition.checkboxHeaders ?? [],
-    };
-}
-/**
- * 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.
- */
-function requireValidBatchUpdateReply(value, requestCount) {
-    if (value === null || typeof value !== "object" || Array.isArray(value)) {
-        invalidProviderState("batchUpdate response must be an object");
-    }
-    const record = value;
-    if (!Array.isArray(record.replies) || record.replies.length !== requestCount) {
-        invalidProviderState(`batchUpdate reply count does not match ${requestCount} requests`);
-    }
-    record.replies.forEach((reply, index) => {
-        if (reply === null || typeof reply !== "object" || Array.isArray(reply)) {
-            invalidProviderState(`batchUpdate reply[${index}] must be an object`);
-        }
-        const replyRecord = reply;
-        const addSheet = replyRecord.addSheet;
-        if (addSheet === undefined)
-            return;
-        if (addSheet === null || typeof addSheet !== "object" || Array.isArray(addSheet)) {
-            invalidProviderState(`batchUpdate reply[${index}].addSheet is invalid`);
-        }
-        const properties = addSheet.properties;
-        if (properties === null || typeof properties !== "object" || Array.isArray(properties)) {
-            invalidProviderState(`batchUpdate reply[${index}].addSheet.properties is invalid`);
-        }
-        if (typeof properties.sheetId !== "number") {
-            invalidProviderState(`batchUpdate reply[${index}].addSheet.properties.sheetId is invalid`);
-        }
-    });
-}
-// ---------------------------------------------------------------------------
-// Provisioning helpers
-// ---------------------------------------------------------------------------
-/** 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);
-}
-/** Builds the A1 range end letters for one registered range. */
-function rangeEndColumnLetters(registeredRange) {
-    const range = parseRegisteredRange(registeredRange);
-    return columnLetters(range.startColumn + range.columnCount - 1);
-}
-/**
- * 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 observeSnapshots(this.deps, requests);
     }
-    return null;
 }
 //# sourceMappingURL=GoogleSheetsApiSyncProvider.js.map