fix(rest): read an offset-free import cell in the business timezone

[qq9340100]

Fixes#8485

A spreadsheet cell like 2026-08-01 06:00:00 carries no offset, so it is a wall clock, not an instant — and parseDateCell ended in new Date(s), which resolves that form against the processTZ. The stored instant was therefore a property of the deployment host:

TZ=Asia/Shanghai → 2026-07-31T22:00:00.000Z
TZ=UTC → 2026-08-01T06:00:00.000Z

Same file, same tenant, same cell — eight hours apart, decided by a setting nobody authoring the spreadsheet can see, and never consulting the business timezone the route had already resolved one frame up (ExecutionContext.timezone).

Since the export renders datetime cells in that business timezone (#8373), the advertised export → edit → re-import round trip was lossless only where the host TZ happened to equal the business zone. import-coerce.ts opens by calling itself "the inverse of export-format.ts"; it now is one.

What changed

• @objectstack/core gains zonedWallClockToUtcMs — the general wall clock → instant direction. zonedDateStartToUtcMs becomes its midnight special case, so one DST-safe implementation (Intl offsets from the platform tz database, never hand-rolled) serves both. Generalising the existing primitive rather than hand-rolling a second one in rest is what keeps the two halves of this seam from drifting apart again.
• parseDateCell takes the caller's timezone and reads a naive datetime cell in it; coerceFieldValue / coerceRow thread it through CoerceContext.timezone, and import-runner.ts reads it off the same resolved context the export route reads its timezone from.
• A naive cell landing in a date or time field takes the typed components verbatim. Those branches also read the process clock, so a host east of the cell stored the previous calendar day for a date column.
• An xlsx date cell now flattens to the sheet's own offset-free wall clock instead of toISOString() stamping a Z the file never had. That fabricated offset previously outranked the business timezone by the honoured-offset carve-out below, so every real date cell in a user-authored workbook imported as UTC whatever the tenant's zone.

The three rulings, honoured

1. An explicit offset is honoured exactly as written.…Z and …+08:00 already name one instant; the NAIVE_DATE_TIME pattern is anchored at both ends so it cannot match them. This change affects naive cells only.
2. The date-only fast path stays UTC.YYYY-MM-DD is UTC per ECMAScript and a date is a timezone-naive calendar day (ADR-0053). Not swept into the zoned handling.
3. No zone resolves ⇒ UTC, never the process clock — pinned, and the reason is stated: this is the fallback the export's own cell path takes (wallClock = zonedWallClock(...) ?? utcWallClock(...)), so the round trip stays exact for deployments that configure no zone. A process-TZ fallback would have preserved the defect for exactly the deployments that cannot see it. An explicitly resolved 'UTC' is a resolved zone, not a missing one.

One behaviour change for existing deployments follows from ruling 3: a host with a non-UTC TZ and no resolved business timezone previously read naive cells in the host clock and now reads them as UTC.

Degenerate DST readings

Two wall clocks are not a bijection with instants. Both degenerate cases resolve to the earlier candidate instant — measured, and pinned including the local clock each lands on:

• gap (02:30 on a US spring-forward day, which never happens) settles on the post-transition offset and lands just before the gap, at 01:30 EST — the opposite of Temporal's 'compatible' disambiguation, which pushes forward;
• ambiguous (01:30 on a US fall-back day, which happens twice) resolves to its first occurrence, 01:30 EDT.

A cell naming a clock its zone never had is ambiguous by construction; what an import needs is an answer that is deterministic and host-independent, which both are.

Tests

Verified at HEAD 1f0ee1791.

The acceptance criterion is inverse-ness of the pair, so it is asserted on the pair, and every fixture runs under a host TZ deliberately different from the business timezone — the configuration where the old code is wrong, and the only one where these can fail. Every datetime fixture straddles a month boundary, because a mid-day instant survives most wrong implementations untouched.

• parseDateCell: the reported cell lands in the tenant's month on all four hosts; a companion assertion measures that the process-clock reading really does produce four different instants, so the host-independence claim is not vacuous.
• export → import identity across every zone × every host × six instants, including both DST edges, plus a guard that the export cell really is offset-free (otherwise the round trip would pass through the honoured-offset branch and stop covering this).
• Route level: the real export route feeding the real import route over a real engine on sqlite :memory:; only resolveExecCtx is stubbed. storedInstant refuses an offset-free stored value rather than letting new Date() re-read the host clock.
• xlsx: both an ExcelJS-encoded Date and a raw Excel serial + numFmt — what a user-authored file actually stores — the latter added here so the fixture does not depend on ExcelJS's encode and decode being wrong symmetrically.

Reverse verification (predicted red, observed red): ablating the naive-datetime branch turns 15 tests red, including the route-level round trip and the raw-serial xlsx case; restored from the commit afterwards.

run	result
@objectstack/core test	34 files, 831 passed
@objectstack/rest test	117 files, 1942 passed
@objectstack/service-analytics test	75 files, 1675 passed
@objectstack/rest typecheck	pass
full workspace build	70/70

service-analytics is the one out-of-package consumer of zonedDateStartToUtcMs, run because that function is widely consumed and the merge queue runs the full suite. zonedDateStartToUtcMs keeps its exact contract — still date-only (a datetime argument is still NaN, pinned), and its equivalence to the generalised form is pinned across seven zone/date pairs.

Gates re-derived at final HEAD with scripts/pm/dispatch-gates.mjs against the actual changed paths and all green: check:nul-bytes, check:changeset-gate-self-tests, check:cross-package-test-inputs, check:error-code-casing, check:kernel-hook-pairs, check:objectui-changeset, check:test-source-alias, check:query-options-erasure, check:type-check-coverage, check:type-check-debt --re-measure, plus check-adr-0087-registration, check-changeset-no-major, check-cross-package-test-inputs, check-empty-changeset. Nothing refused to run.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 15, 2026 1:24am

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/core, @objectstack/rest.

25 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/ai/actions-as-tools.mdx(via @objectstack/core)
• content/docs/ai/connect-mcp.mdx(via @objectstack/rest)
• content/docs/ai/knowledge-rag.mdx(via @objectstack/core)
• content/docs/ai/natural-language-queries.mdx(via @objectstack/core)
• content/docs/api/error-handling-server.mdx(via @objectstack/rest)
• content/docs/api/index.mdx(via @objectstack/rest)
• content/docs/automation/webhooks.mdx(via @objectstack/core)
• content/docs/concepts/north-star.mdx(via packages/core)
• content/docs/deployment/migration-from-objectql.mdx(via @objectstack/core)
• content/docs/kernel/contracts/index.mdx(via @objectstack/core)
• content/docs/kernel/runtime-services/examples.mdx(via @objectstack/core)
• content/docs/kernel/services-checklist.mdx(via @objectstack/core)
• content/docs/kernel/services.mdx(via @objectstack/core)
• content/docs/permissions/authentication.mdx(via @objectstack/core, @objectstack/rest)
• content/docs/permissions/authorization.mdx(via packages/core)
• content/docs/permissions/system-context.mdx(via packages/rest)
• content/docs/plugins/anatomy.mdx(via @objectstack/core)
• content/docs/plugins/development.mdx(via @objectstack/core)
• content/docs/plugins/index.mdx(via @objectstack/core, @objectstack/rest)
• content/docs/plugins/packages.mdx(via @objectstack/core, @objectstack/rest)
• content/docs/protocol/kernel/http-protocol.mdx(via @objectstack/rest)
• content/docs/protocol/kernel/i18n-standard.mdx(via packages/rest)
• content/docs/protocol/kernel/index.mdx(via @objectstack/core)
• content/docs/protocol/kernel/lifecycle.mdx(via @objectstack/core)
• content/docs/protocol/kernel/plugin-spec.mdx(via @objectstack/core)

⛔ 4 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx(via @objectstack/core, @objectstack/rest)
• content/docs/releases/v12.mdx(via @objectstack/core, @objectstack/rest)
• content/docs/releases/v15.mdx(via @objectstack/core)
• content/docs/releases/v17.mdx(via @objectstack/core, @objectstack/rest)

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.

[qq9340100]

ACCEPT — PM review, domain:cli seat

This card was resumed after a container restart killed its first agent. That agent's commit survived unpushed in its worktree and was recovered rather than redone — the right handling, and it is why this landed as one coherent commit instead of a second attempt.

All three rulings verified from the diff, not from the PR body.

Ruling 3 — the fallback is a deliberate stated choice: VERIFIED, and this was the one I could not decide for you.zonedWallClockToUtcMs reads if (!tz || tz === 'UTC' || Number.isNaN(wallAsUtc)) return wallAsUtc where wallAsUtc = Date.UTC(...). So no-zone ⇒ UTC, never the process clock. The reasoning given is the right one and is better than the alternative I floated: it matches the export's own cell-path fallback, so the round trip stays exact for deployments that configure no zone — whereas a process-TZ fallback would have preserved the defect for precisely the deployments that cannot see it. The resulting behaviour change for a non-UTC host with no resolved business timezone is stated plainly in the PR and carried in the changeset rather than buried.

Ruling 1 — explicit offsets untouched: VERIFIED. The NAIVE_DATE_TIME pattern is anchored at both ends, so …Z and …+08:00 cannot match it.

Ruling 2 — date-only fast path stays UTC: VERIFIED.zonedDateStartToUtcMs keeps its exact ^(\d{4})-(\d{2})-(\d{2})$ regex and its NaN return for anything else, now delegating to the general form. The contract is preserved and the duplication is gone — the "generalise, don't hand-roll a second one" outcome, with the equivalence pinned across seven zone/date pairs.

Scope grew past the headline, and each step is justified rather than creep. The date/time branches read the same process clock (a host east of the cell stored the previous calendar day), and the xlsx fix is not optional: ExcelJS stamped a Z the file never had, and under ruling 1 that fabricated offset would have outranked the business timezone — so without it the fix would not have worked on the most common real input. Everything stayed inside the declared surface; the diff is exactly core/utils/datetime.*, rest/import-*, and one new test file.

A real defect was caught while generalising, and documented at the site:formatToParts resolves no finer than a second, so a sub-second wall clock would leak its milliseconds into the computed offset. Invisible in the date-only form where ms is always 0, live the moment the primitive generalises.

The tests are built so they can actually fail. Every fixture runs under a host TZ deliberately different from the business timezone — the only configuration where the old code is wrong — and every datetime fixture straddles a month boundary rather than a mid-day instant. Two touches raise this above the usual: a companion assertion measures that the process-clock reading really does produce four different instants, so the host-independence claim is not vacuous; and a guard asserts the export cell really is offset-free, without which the round trip would slip through the honoured-offset branch and stop covering the thing under test. Reverse verification predicted red and measured 15 red, including the route-level round trip and the raw-Excel-serial case.

The raw serial + numFmt fixture is the right instinct — it removes the dependence on ExcelJS's encode and decode being wrong symmetrically, which is exactly how a round-trip test can pass over a broken implementation.

Both DST degenerate cases resolve to the earlier candidate instant, measured and pinned including the local clock each lands on, with the divergence from Temporal's 'compatible' disambiguation named rather than glossed. Determinism and host-independence are the properties an import needs, and the PR argues that rather than asserting it.

service-analytics was run as the out-of-package consumer of zonedDateStartToUtcMs — the affected-subset-vs-full-suite gap handled before queueing, not after a kick.

⛔ Flip held until every gate job concludes success on its own reading. Nothing refused to run locally, which is the answer I want on a card that touches a widely-consumed core primitive.

---

Generated by Claude Code