Cell formatting semantics: scoped `format` wire field (comment stays excluded)

[hhimanshu]

Scope amended 2026-07-25

Original scope ("cell formatting semantics" — format/comment reserved-but-rejected) was post-v1/tracking-only per 2026-06-07-workbook-v1-scope.md Decision 2. That row is now superseded by 2026-07-25-amend-workbook-v1-scope-arrayformula-format.md (Decision 2), owner-approved via truecalc/distributions#64.

Approved, in scope now: a scoped format wire field on Cell — numberFormat (reusing the TEXT() pattern grammar, which needs extracting into a shared module first — a prerequisite refactor), font (bold/italic/color/family/size), fill (color), border (top/right/bottom/left, each {style, color}). Canonical hex-color casing and enum spellings must be pinned for byte-identical JCS round-trip. An empty format object is rejected. Schema version bumps "1" → "2".

Design requirement: a set_format()-style API must NOT add the touched address to the edited list passed to Workbook::recalc_incremental (crates/workbook/src/recalc.rs:232) — a formatting-only edit must not spuriously dirty dependents or appear in the Vec<Change> the way a value/formula edit does.

Open architectural question for this issue to resolve: inline-per-cell format risks blowing the 100 MiB / ~50–100 bytes-per-cell resource-limit math (original ADR Decision 5) on real-world styled sheets at the 1M-cell cap. A workbook-level shared-style table (referenced by index — the data-structure pattern only, not xlsx import/export, which stays excluded) is the likely fix; this issue should resolve it, possibly with a follow-up Decision-5 amendment.

comment stays excluded — separate from format, still post-v1, pending its own follow-on decision (author/timestamp questions collide with the RecalcContext no-ambient-clock rule).

Blocked on fixtures. Today's GAS pipeline extracts evaluated values, not userEnteredFormat/notes — format ground truth needs a materially different Sheets API extraction path. A fixtures-pipeline design addendum is a precondition for any format fixture row, not an afterthought. This is being sequenced together with other fixtures-needing issues; do not start core work ahead of that landing.

[hhimanshu]

Scoping notes:

• comment should stay out of scope until a team/collaboration plan exists — comments are inherently multi-user and don't make sense without that tier.
• format is currently a reserved key with zero defined content shape (rejected outright, not partially built). Example of what the eventual content schema would need, modeled on Sheets per-cell formatting:

"format": {
  "numberFormat": "#,##0.00",
  "font": { "bold": true, "italic": false, "underline": false, "strikethrough": false,
            "family": "Arial", "size": 10, "color": "#000000" },
  "backgroundColor": "#FFFF00",
  "borders": { "top": {}, "bottom": {}, "left": {}, "right": {} },
  "textAlign": "center",
  "verticalAlign": "middle",
  "wrapStrategy": "wrap"
}

Open design questions before this can be built:

• Per-cell inline format vs. an indexed style table (Sheets dedupes repeated formats internally).
• Conditional formatting is a separate concern and shouldn't be absorbed into static format.
• Canonicalization/round-trip rule for "format present but equal to default" (store vs. omit) to preserve byte-identity guarantees.

[hhimanshu]

Plain-language summary of what's actually approved here:

This is about the engine actually remembering cell formatting (bold, colors, borders, number formats like $1,234.00) instead of just calculating values. Today the engine's file format flat-out rejects any formatting info sent to it — this issue teaches it to accept and store a fixed, defined set of formatting fields (font, fill color, borders, number format). Free-form stuff like comments/notes stays excluded for now — that's a separate, harder decision (comments raise "who wrote it, when" questions that clash with how the engine guarantees identical results every time).

This one doesn't carry the same "could silently change existing behavior" risk that part of #551 does — it's purely additive storage, not a change to how any calculation works.

Why this is blocked on fixtures: TrueCalc's whole pitch is "we match Google Sheets exactly," proven by checking against real answers pulled from real Google Sheets. The pipeline that does that pulling has only ever captured calculated values (e.g. "cell A1 equals 42") — it's never captured formatting at all. That's a different kind of question to ask Google Sheets, and the plumbing for it doesn't exist yet. So this needs new plumbing built before there's anything to verify formatting against, which is why it's queued for next week's fixtures batch rather than starting immediately.