feat(sheets): extend the persisted batch primitive to structural spreadsheets.batchUpdate commands (batch-update covers values only)

[sebsnyk]

What already exists, and what it does not cover

Two separate things are both called batching in gog, and only one of them is on Sheets.

gog sheets batch-update --data-json wraps spreadsheets.values.batchUpdate. It writes values to several ranges in one request. That is useful and shipped.

gog batch begin/list/show/end/abort/prune plus --batch=<id> on the mutating docs commands wraps the accumulate-then-submit pattern against documents.batchUpdate. Sheets has the same endpoint shape in spreadsheets.batchUpdate, and none of the structural gog sheets commands can reach it in a batch. gog batch begin takes --doc only.

The commands that are one call each

Every one of these is a spreadsheets.batchUpdate request type, and every one is its own process and its own API call on v0.39.0:

Command	Request
sheets format	RepeatCell / UpdateCells
sheets number-format	RepeatCell
sheets conditional-format add / clear	AddConditionalFormatRule / DeleteConditionalFormatRule
sheets validation	SetDataValidation
sheets banding	AddBanding / UpdateBanding / DeleteBanding
sheets filter	SetBasicFilter / ClearBasicFilter
sheets merge / unmerge	MergeCells / UnmergeCells
sheets freeze	UpdateSheetProperties
sheets resize-columns / resize-rows	UpdateDimensionProperties
sheets insert / delete-dimension	InsertDimension / DeleteDimension
sheets copy-paste	CopyPaste
sheets update-note	RepeatCell on the note field
sheets links	UpdateCells with textFormatRuns
sheets named-ranges	AddNamedRange / DeleteNamedRange
sheets table	AddTable / UpdateTable
sheets chart	AddChart / UpdateChartSpec / DeleteEmbeddedObject
sheets add-tab / rename-tab / delete-tab / reorder-tab	AddSheet / UpdateSheetProperties / DeleteSheet
sheets find-replace	FindReplace

The cost

The documented Sheets quota is 60 write requests per minute per user per project (https://developers.google.com/workspace/sheets/api/limits), the same ceiling as Docs and Slides.

A formatting pass on a report sheet is not an exotic workload. Header row bold and filled, five column widths, a frozen header, a basic filter, three conditional-format rules, two number formats over separate ranges, a banded range, and two merges is 15 calls for a single tab. Repeat that across eight tabs and the run is 120 calls against a 60-per-minute ceiling, and half of it 429s. Batched, it is one spreadsheets.batchUpdate, far inside the request cap.

spreadsheets.batchUpdate is also the only way to get certain orderings right. Adding a chart that references a named range added in the same pass currently requires two calls with an implicit ordering the caller has to know about, where a single batch expresses it directly.

What a caller has to do today

Insert sleeps between calls, or drop to a Google API client library for the structural pass and keep gog for values. Splitting one spreadsheet's write path across two auth mechanisms is the outcome nobody wants.

Proposed surface

Same shape as the shipped Docs batch, so there is nothing new to learn:

gog batch begin --spreadsheet=<id> [--name=<label>]
gog sheets format            --batch=<id> ...
gog sheets conditional-format add --batch=<id> ...
gog sheets merge             --batch=<id> ...
gog sheets resize-columns    --batch=<id> ...
gog sheets chart add         --batch=<id> ...
gog batch end <id>

--dry-run, --continue-on-error, --auto-split and the revision lock behave as they do for Docs. spreadsheets.batchUpdate is atomic, so strict-atomic-by-default carries over unchanged.

Out of scope for a batch: get, read-format, notes, metadata, raw, export are reads; update and append go through the values endpoint rather than spreadsheets.batchUpdate and are already served by batch-update; create and copy create the file.

If gog batch begin grows one target flag per service the flags multiply, so a single --target <service>:<id> may age better than --doc / --presentation / --spreadsheet side by side. Either way the existing --doc should keep working.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed September 9, 2026, 9:30 AM ET / 13:30 UTC.

Summary
The requested Sheets capability remains absent from main and v0.39.1. The existing Docs implementation was intentionally scoped to Docs; extending it is useful, but Sheets concurrency guarantees and supported command scope need a product decision.

Reproducibility: not applicable. as a bug reproduction: this requests a new batching mode. Current source confirms the capability gap; no live quota-failure run was performed.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Share version, platform, channel/provider, and relevant config details.

Maintainer decision needed

Question	Recommendation
Should Sheets batching initially support only independently composable structural edits, with atomic submission but explicitly no Docs-style revision lock?	Stage a composable Sheets subset: Approve an additive Sheets target and a bounded initial command set with documented concurrency limits, preserving existing Docs state and flags.

Why: The requested cross-command scope and revision parity cannot be inherited unchanged from Docs, and pending-object resolution would materially expand the implementation.

Next step
Choose the initial Sheets command scope and concurrency contract before implementation; this is a cross-command feature rather than a bounded existing-behavior repair.

Review details

Best possible solution:

Extend the existing batch lifecycle incrementally, preserve Docs compatibility, and define Sheets-specific concurrency and dependency semantics before enabling composable structural commands.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug reproduction: this requests a new batching mode. Current source confirms the capability gap; no live quota-failure run was performed.

Is this the best way to solve the issue?

Partly: reusing the persisted lifecycle is appropriate, but copying Docs revision locking and supporting every structural command unchanged is not justified by the Sheets contract.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• Promising Docs-equivalent revision locking would exceed the documented Sheets batchUpdate contract.
• Commands resolving live tabs, named ranges, or indexes cannot automatically resolve objects created only in queued requests.
• Generalizing persisted state must preserve existing Docs batches, account/client binding, and explicit non-atomic recovery semantics.

Codex review notes: model internal, reasoning medium; reviewed against 29a5adfb3e90.

Label changes

Label changes:

• add P2: This is a concrete automation improvement for existing Sheets workflows, without evidence of an urgent regression.
• add impact:other: Repeated structural submissions increase API request consumption and orchestration overhead.
• add issue-rating: 🌊 off-meta tidepool: Current issue advisory state selects this label.
• add clawsweeper:no-new-fix-pr: Current issue advisory state selects this label.
• add clawsweeper:needs-maintainer-review: Current issue advisory state selects this label.
• add clawsweeper:needs-product-decision: Current issue advisory state selects this label.

Label justifications:

• P2: This is a concrete automation improvement for existing Sheets workflows, without evidence of an urgent regression.
• impact:other: Repeated structural submissions increase API request consumption and orchestration overhead.

Evidence reviewed

What I checked:

• Current persisted batches remain Docs-only: The checkout matches fetched main. BatchBeginCmd restricts service to docs and requires --doc; submission constructs a documents endpoint and Docs writeControl. (internal/cmd/batch.go:27, 29a5adfb3e90)
• Values batching does not cover structural requests: SheetsBatchUpdateCmd builds BatchUpdateValuesRequest and calls Spreadsheets.Values.BatchUpdate. The corresponding documentation explicitly describes value ranges. (internal/cmd/sheets.go:432, 29a5adfb3e90)
• Structural mutations submit immediately: Merge resolves sheet IDs and submits through applySheetsBatchUpdate, which directly invokes the Sheets API. Format independently resolves live metadata and submits directly; neither command exposes --batch. (internal/cmd/sheets_mutation_helpers.go:121, 29a5adfb3e90)
• Latest-release comparison: The batch command, Sheets command definitions, and persisted repository have no differences between v0.39.1 and current main. Reading the release's batch command confirms its Docs-only service restriction. (internal/cmd/batch.go:27, 6895139ab1b4)
• Earlier implementation deliberately limited its scope: Merged feat(batch): add persisted Docs request batches #755 describes a Docs-only foundation. In feat(gog): add batch begin / batch end primitive with --batch flag on edit commands #698, steipete's closeout confirms that scope and excludes operations requiring intermediate reads or side effects. This supports treating the Sheets request as remaining work rather than already delivered behavior. (1d2246317f44)
• Sheets atomicity is not Docs revision locking: The proposal depends directly on the Sheets API contract. Google's batchUpdate reference guarantees atomic application but warns about concurrent collaborator changes; its request schema exposes no Docs-style writeControl or requiredRevisionId.

Likely related people:

• steipete: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[sebsnyk]

@steipete wdyt? Could we look at thisone?

[steipete]

Fixed on main by #1168, merged as f30249e. Thanks @sebsnyk.

batch begin --spreadsheet now supports 26 typed structural commands and lossless raw sheets batch-request payloads. Typed queues reuse one immutable metadata snapshot; submission is atomic by default, with explicit permission/confirmation checks and retained state on failure. The documented raw path handles dependencies on queued structural changes.

Local CI, independent review, and final-head hosted CI/CodeQL passed. Live Google Sheets proof verified 16 ordered requests, no edits before submission, and an invalid atomic batch applying nothing while retaining its queue. The synthetic spreadsheet was trashed and cleanup verified. Full commands, CI links, integration limits, and landing verification are in the PR proof.