refactor(time): fold the remaining duplicated time sites into dsh-util-time

- session-format-v0-to-v1 reads the shared canonical-instant profile
  through fourDigitYearEpoch instead of its own regular expression and
  round trip, with the accepted set pinned by a differential against the
  pre-change predicate (3,508 inputs, 0 divergences)
- localUtcOffsetSeconds holds the seconds-east conversion two clients had
  each written, so the offset a client reports has one home
- the Agent Note records the three sites that stay, and why each is not a
  copy of this vocabulary

.agents/notes/implemented/architecture/2026-09-24-shared-time-vocabulary.i18n.yaml

@@ -9,11 +9,11 @@
   en: abd0263d14861926
   zh: e1736cd08e87f795
 /agent-note-shared-time-vocabulary-for-wall-clock-selectors/decision:
-  en: 52b45f1ac62e65ab
-  zh: 7f83cd4fb8dd09a6
+  en: 7ec7e8c7885268ae
+  zh: b4c29b486a04b732
 /agent-note-shared-time-vocabulary-for-wall-clock-selectors/alternatives-considered:
   en: 1737484c099fab52
   zh: 303b144c52d167bd
 /agent-note-shared-time-vocabulary-for-wall-clock-selectors/consequences:
-  en: 6ec74e7ac065bd5e
-  zh: 04d029059dea732b
+  en: 6a9d594d9f2f7051
+  zh: 25c2e19c6eff8c8f

.agents/notes/implemented/architecture/2026-09-24-shared-time-vocabulary.md

@@ -20,6 +20,8 @@ Schedule consumes it and keeps every domain decision. `canonicalizeTimeZone`, `d
 
 `Duration` holds one span as a single millisecond count, and it is a class rather than a branded number because TypeScript's arithmetic erases a brand: adding two differently branded numbers answers an unbranded `number`, so a brand cannot stop seconds and milliseconds from being mixed, while an instance can. The unit is milliseconds because every producer and consumer in this repository already uses it (`Date.now()`, `SessionEvent.time`, the session log, the client), and because a double holds every millisecond of the whole `Date` range exactly, so no precision is spent on the unit. Instances are frozen, no coercion hook is overridden, and a span is bounded by the exactly representable millisecond range, which is what makes the split exact. The published surface is `fromMilliseconds` and a whole-part `decompose()`, the two entries the migrated consumer calls.
 
+The last copy of the canonical instant profile moves too. `packages/session/session-format-v0-to-v1/src/payload-validation.ts` validated a stored schedule instant with its own regular expression and round trip; the shared `fourDigitYearEpoch` owns that same profile, so the migration now asks it and keeps its own error type and message. Because that migration reads released logs, its accepted set is pinned by a differential over the canonical form, the four-digit-year bounds, and the strings a regular expression alone would admit (`2026-02-30`, a four-digit fraction, a numeric offset, surrounding whitespace). The UTC offset a client reports as metadata had also been written twice, so `localUtcOffsetSeconds` holds that conversion: the platform reports minutes west of UTC and both callers needed whole seconds east.
+
 The maintained `@js-temporal/polyfill` 0.5.1 becomes a runtime dependency of `dsh-util-time` as well as of `dsh-schedule`. Local resolution continues to use it, so the Host's IANA data still decides gaps and overlaps and no caller owns offset sampling. `util/time`'s own description and README drop the `zero-dependency` phrase as ambiguous: the group's charter forbids harness dependencies so any group may depend on util, and does not ban external packages, which is why `packages/README.md` and the `util/` line in `AGENTS.md` keep the phrase while `packages/util/README.md` and this package's own description name what it loads.
 
 Observable behavior does not change. Every accepted input resolves to the same epoch, every refused input raises the same `ScheduleInputError` or `ScheduleLogError` code and the same message, and the stored `scheduledAt` profile is unchanged, so no durable record and no recorded snapshot is re-recorded. Schedule's suites assert error codes and a few unrelated message substrings, so the assertion this change adds to `packages/schedule/schedule/tests/domain.spec.ts` is the only place that pins the three local-calendar message strings. `packages/util/time/tests/instant.spec.ts` covers the new entries directly, per-file 100% included.
@@ -48,4 +50,4 @@ A value type publishes what its consumers call, so the span exposes the construc
 
 The elapsed reading keeps its split in the library and its wording in the consumer: `dsh-time-context` still decides that a backward clock reading clamps to zero and how the compact line reads, while `Duration.decompose()` answers the whole parts. That swap is byte-identical for every finite sample, measured over more than eight thousand inputs including negatives, fractions, and values past a year. That measurement is not a committed test: the consumer's own suite pins the readings it renders (`1d 1h 1m 1s`, `1m 1s`, `4m 2s`, and the clamped zero). Two samples do change: `NaN` rendered `NaNs` and `+Infinity` rendered `Infinityd NaNs`, and both now throw from the span constructor, so a reading that is not a finite number fails where it is produced instead of rendering text. A `-Infinity` sample is unchanged, because the consumer clamps it to zero before the span is built.
 
-Time-context keeps the two policies this change did not touch: its ISO-shaped timestamp rendering in `packages/context/time-context/src/timestamp.ts`, which is that package's durable reading format, and the elapsed-duration wording in its own plugin. The browser client keeps its own localized date rendering and its own UTC-offset reading, which serve a different purpose (a reader's locale) from a boundary value; unifying those means deciding whether the shared library should also own display formatting, and which package then owns the durable reading format. `packages/session/session-format-v0-to-v1/src/payload-validation.ts` also validates the canonical four-digit-year UTC instant with its own regular expression and round trip, which is a remaining copy of the instant profile this change did not touch.
+Time-context keeps the two policies this change did not touch: its ISO-shaped timestamp rendering in `packages/context/time-context/src/timestamp.ts`, which is that package's durable reading format, and the elapsed-duration wording in its own plugin. The browser client keeps its own localized date rendering and its own offset reading for display, which serve a different purpose (a reader's locale) from a boundary value; unifying those means deciding whether the shared library should also own display formatting, and which package then owns the durable reading format. Three time sites keep their own code, each for a different reason. `packages/experimental/tool-session-query/src/input.ts` parses a wider profile than the shared entry — seconds optional, any number of fractional digits, and the digits below the millisecond kept so two instants can be compared exactly — so substituting the shared parser would narrow what it accepts, and moving that profile into the library is a design step of its own. The `Date.parse(record.scheduledAt)` reads in `dsh-schedule` parse a value the write path already validated, so a discriminated decode would add a rejection branch that cannot occur in practice and change what a corrupt record reports. The `everySeconds`, `afterSeconds`, and `refreshMarginSeconds` multiplications each sit beside a validation that raises the package's own error, so routing them through a constructor that throws its own type would change the failure a caller sees.

.agents/notes/implemented/architecture/2026-09-24-shared-time-vocabulary.zh.md

@@ -20,6 +20,8 @@ Schedule 消费它，并保留全部域内决策。`canonicalizeTimeZone`、`dec
 
 `Duration` 以单一毫秒计数保存一段时间；它做成类而不是 branded number，是因为 TypeScript 的算术会抹掉 brand：两个不同品牌的数字相加得到的是无品牌的 `number`，所以 brand 挡不住秒与毫秒的混用，而实例可以。单位选毫秒，是因为本仓库的每个生产者与消费者本来就用它（`Date.now()`、`SessionEvent.time`、Session 日志、客户端），也因为 double 能精确表示 `Date` 全范围内的每一个毫秒，这个单位不消耗任何精度。实例被冻结，不覆盖任何强制转换钩子，且时间段受可精确表示的毫秒范围约束——这正是拆分精确的前提。公开面就是 `fromMilliseconds` 与整数量拆解 `decompose()`，即已迁移消费方所调用的两个入口。
 
+最后一份规范时刻剖面副本也一并迁移。`packages/session/session-format-v0-to-v1/src/payload-validation.ts` 原本用自己的一段正则与往返比对校验持久记录里的调度时刻；共享的 `fourDigitYearEpoch` 拥有同一剖面，因此该迁移改为询问它，并保留自己的错误类型与文案。由于这个迁移要读取已发布的日志，其接受集由一份差分固定：覆盖规范形式、四位年份两端，以及只靠正则会被放进来的字符串（`2026-02-30`、四位小数、数字偏移、首尾空白）。客户端作为元数据上报的 UTC 偏移也写了两遍，因此 `localUtcOffsetSeconds` 持有这段换算：平台报告的是 UTC 以西的分钟数，而两个调用方都需要 UTC 以东的整秒。
+
 受维护的 `@js-temporal/polyfill` 0.5.1 在成为 `dsh-schedule` 运行时依赖之外，也成为 `dsh-util-time` 的运行时依赖。本地解析继续使用它，因此缺口与重叠仍由宿主 IANA 数据决定，也没有调用方需要自己实现偏移采样。`util/time` 自身的描述与 README 去掉了 `zero-dependency` 这一说法，因为它容易被误读：该组的约定禁止的是 harness 依赖（以便任何组都能依赖 util），并不禁止外部包；因此 `packages/README.md` 与 `AGENTS.md` 里的 `util/` 一行保留该说法，而 `packages/util/README.md` 与本包自己的描述写明它加载了什么。
 
 可观察行为不变。每个被接受的输入解析出相同的纪元值，每个被拒绝的输入抛出相同的 `ScheduleInputError` 或 `ScheduleLogError` 错误码与相同的消息，存储的 `scheduledAt` 剖面不变，因此没有持久记录或录制快照需要重录。Schedule 的测试断言错误码以及少量无关的消息子串，因此本次在 `packages/schedule/schedule/tests/domain.spec.ts` 新增的断言是唯一固定这三条本地日历消息的地方。`packages/util/time/tests/instant.spec.ts` 直接覆盖新增入口，包含逐文件 100% 覆盖。
@@ -48,4 +50,4 @@ Schedule 消费它，并保留全部域内决策。`canonicalizeTimeZone`、`dec
 
 耗时读数的拆分上收到库、措辞留在一侧：`dsh-time-context` 仍然决定回退的时钟读数钳到零、以及那行紧凑文本怎么写，而 `Duration.decompose()` 回答整数量。这次替换对每个有限样本都逐字不变，用一份覆盖八千多个输入（含负数、小数与一年以上的值）的差分测得。该测量不是提交进仓库的测试：消费方自己那套测试固定了它渲染出的读数（`1d 1h 1m 1s`、`1m 1s`、`4m 2s`，以及被钳到零的那次）。有两个样本会变：`NaN` 原本渲染出 `NaNs`、`+Infinity` 原本渲染出 `Infinityd NaNs`，现在两者都由时间段构造函数抛出，于是非有限的读数在产生它的地方失败，而不是渲染出一段文本。`-Infinity` 样本不变，因为消费方在构造时间段之前已把它钳到零。
 
-本次未触及、仍归 time-context 的两项：`packages/context/time-context/src/timestamp.ts` 中的 ISO 形状时间戳渲染（那是该包的持久读数字格式），以及其插件内的耗时措辞。浏览器客户端也保留自己的本地化日期渲染与自己的 UTC 偏移读取——它们服务的目的（读者的区域设置）与边界值不同；统一它们意味着先决定共享库是否也要拥有展示格式化，以及届时由谁拥有持久读数字格式。`packages/session/session-format-v0-to-v1/src/payload-validation.ts` 也用自己的一段正则与往返比对校验规范的四位年份 UTC 时刻，这是本次未触及、仍然存在的时刻剖面副本。
+本次未触及、仍归 time-context 的两项：`packages/context/time-context/src/timestamp.ts` 中的 ISO 形状时间戳渲染（那是该包的持久读数字格式），以及其插件内的耗时措辞。浏览器客户端也保留自己的本地化日期渲染与用于展示的偏移读取——它们服务的目的（读者的区域设置）与边界值不同；统一它们意味着先决定共享库是否也要拥有展示格式化，以及届时由谁拥有持久读数字格式。有三处时间代码各自保留实现，原因各不相同。`packages/experimental/tool-session-query/src/input.ts` 解析的剖面比共享入口更宽——秒可省略、小数位不限、并保留下毫秒数字以便精确比较两个时刻——因此换成共享解析器会收窄它接受的输入，而把那条剖面搬进本库是另一项独立的设计。`dsh-schedule` 里的 `Date.parse(record.scheduledAt)` 读的是写入路径已经校验过的值，换成带判别值的解码会在每个读取点新增一个实际不可能发生的拒绝分支，并改变损坏记录的报告方式。`everySeconds`、`afterSeconds` 与 `refreshMarginSeconds` 三处乘法旁边都紧跟一条抛本包自有错误的校验，因此把它们改走会抛自身错误类型的构造函数，会改变调用方看到的失败。

apps/desktop/package.json

@@ -47,6 +47,7 @@
     "semver": "^7.8.5",
     "ws": "^8.21.3",
     "@deepseek-ai/dsh-api-gateway": "workspace:*",
+    "@deepseek-ai/dsh-util-time": "workspace:*",
     "@deepseek-ai/cordis": "workspace:~"
   },
   "devDependencies": {

apps/desktop/src/client-metadata.ts

@@ -1,4 +1,5 @@
 /** Desktop client identity for one Platform account call. */
+import { localUtcOffsetSeconds } from '@deepseek-ai/dsh-util-time'
 import type { AccountClientMetadata } from '@deepseek-ai/dsh-deepseek-account/types'
 
 /**
@@ -23,7 +24,6 @@ export function desktopClientMetadata(locale: string): AccountClientMetadata {
   return {
     version: desktopClientVersion(),
     locale,
-    // Date.getTimezoneOffset reports minutes west of UTC; Platform wants seconds east.
-    timezoneOffsetSeconds: -new Date().getTimezoneOffset() * 60,
+    timezoneOffsetSeconds: localUtcOffsetSeconds(Date.now()),
   }
 }

apps/desktop/tsconfig.host.json

@@ -31,6 +31,9 @@
     },
     {
       "path": "../../packages/client/product-analytics/tsconfig.host.json"
+    },
+    {
+      "path": "../../packages/util/time"
     }
   ],
   "exclude": [

packages/client/ui-settings-account/package.json

@@ -62,6 +62,7 @@
     "@deepseek-ai/dsh-client-ui-theme": "workspace:*",
     "@deepseek-ai/dsh-deepseek-account": "workspace:*",
     "@deepseek-ai/dsh-settings": "workspace:*",
+    "@deepseek-ai/dsh-util-time": "workspace:*",
     "@testing-library/react": "^16.3.3",
     "@types/big.js": "^6.2.2",
     "react": "^18.2.0",

packages/client/ui-settings-account/src/client/client-metadata.ts

@@ -4,6 +4,7 @@
  * the local UTC offset rather than any credential.
  * @module @deepseek-ai/dsh-client-ui-settings-account/src/client/client-metadata
  */
+import { localUtcOffsetSeconds } from '@deepseek-ai/dsh-util-time'
 import type { AccountClientMetadata } from '@deepseek-ai/dsh-deepseek-account/types'
 
 /**
@@ -18,7 +19,6 @@ export function accountClientMetadata(locale: string, version: string | undefine
   return {
     version,
     locale,
-    // Date.getTimezoneOffset reports minutes west of UTC; Platform wants seconds east.
-    timezoneOffsetSeconds: -new Date().getTimezoneOffset() * 60,
+    timezoneOffsetSeconds: localUtcOffsetSeconds(Date.now()),
   }
 }

packages/client/ui-settings-account/tsconfig.json

@@ -58,6 +58,9 @@
     },
     {
       "path": "../product-analytics/tsconfig.client.json"
+    },
+    {
+      "path": "../../util/time"
     }
   ]
 }

packages/session/session-format-v0-to-v1/package.json

@@ -40,6 +40,7 @@
   },
   "dependencies": {
     "@deepseek-ai/dsh-session-format": "workspace:*",
+    "@deepseek-ai/dsh-util-time": "workspace:*",
     "@deepseek-ai/dsh-util-values": "workspace:*"
   },
   "peerDependencies": {
@@ -47,6 +48,7 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "workspace:~",
-    "@deepseek-ai/dsh-session": "workspace:*"
+    "@deepseek-ai/dsh-session": "workspace:*",
+    "@deepseek-ai/dsh-util-time": "workspace:*"
   }
 }

packages/session/session-format-v0-to-v1/src/payload-validation.ts

@@ -1,4 +1,5 @@
 import { SessionFormatError, sessionFormatCount, sessionFormatSafeInteger } from '@deepseek-ai/dsh-session-format'
+import { fourDigitYearEpoch } from '@deepseek-ai/dsh-util-time'
 import { deepEqualJson } from '@deepseek-ai/dsh-util-values'
 import type {
   SessionFormatEvent,
@@ -926,10 +927,7 @@ function scheduleIdValue(value: SessionFormatJsonValue | undefined, label: strin
 }
 
 function instantValue(value: SessionFormatJsonValue | undefined, label: string): void {
-  if (typeof value !== 'string'
-    || !/^(?!0000)\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d\.\d{3}Z$/u.test(value)
-    || !Number.isFinite(Date.parse(value))
-    || new Date(Date.parse(value)).toISOString() !== value) {
+  if (typeof value !== 'string' || fourDigitYearEpoch(value).kind !== 'accepted') {
     throw new SessionFormatError(`${label} must be a canonical UTC instant`)
   }
 }

packages/session/session-format-v0-to-v1/tsconfig.json

@@ -20,6 +20,9 @@
     {
       "path": "../session-format"
     },
+    {
+      "path": "../../util/time"
+    },
     {
       "path": "../../util/values"
     }

packages/util/time/README.i18n.yaml

@@ -24,8 +24,8 @@
   en: 7ca7ddebcb6af6be
   zh: 4702a29079d6b8a7
 /dsh-util-time/understand-the-implementation:
-  en: 14595019b72aa45f
-  zh: cfea261931019621
+  en: a0295d549381012b
+  zh: 95aa9ddec689ad78
 /dsh-util-time/further-exploration:
   en: 8aa95ebdfd1f323e
   zh: c6879eac9fa6e087

packages/util/time/README.md

@@ -73,6 +73,7 @@ The strict parsers match a fixed regular expression before constructing any date
 | `isFourDigitYearInstant` | The same range, as a predicate, so a caller that only needs the bound does not re-derive it. |
 | `resolveLocalInstant` | Exact calendar fields of a real date, or an already-built `Temporal.PlainDateTime`, plus an already-canonical zone. |
 | `Duration` | One finite millisecond count inside the exactly representable range, and its split into whole days, hours, minutes, seconds, and the remaining fraction. |
+| `localUtcOffsetSeconds` | An epoch to read the host zone's offset at; answers whole seconds east of UTC. |
 
 </details>
 

packages/util/time/README.zh.md

@@ -73,6 +73,7 @@ Duration.fromMilliseconds(1_500).decompose() // { days: 0, hours: 0, minutes: 0,
 | `isFourDigitYearInstant` | 同一范围的谓词形式，只判断范围边界的调用方无需自行推导。 |
 | `resolveLocalInstant` | 真实日期的精确日历字段，或已构造好的 `Temporal.PlainDateTime`，外加已规范化的时区。 |
 | `Duration` | 一个落在可精确表示范围内的毫秒计数，以及它拆出的整日、整时、整分、整秒与不足一秒的余数。 |
+| `localUtcOffsetSeconds` | 传入要读取宿主时区偏移的时刻；回答 UTC 以东的整秒数。 |
 
 </details>
 

packages/util/time/src/index.ts

@@ -16,6 +16,7 @@
 import { canonicalizeTimeZone } from './instant.ts'
 
 export { Duration } from './duration.ts'
+export { localUtcOffsetSeconds } from './local-offset.ts'
 export {
   MAX_FOUR_DIGIT_YEAR_MS,
   MIN_FOUR_DIGIT_YEAR_MS,

packages/util/time/src/local-offset.ts

@@ -0,0 +1,20 @@
+/**
+ * The host's current UTC offset, for the metadata a client reports about itself.
+ * @module @deepseek-ai/dsh-util-time
+ */
+
+const SECONDS_PER_MINUTE = 60
+
+/**
+ * The host zone's offset from UTC at one instant, in seconds east of UTC.
+ *
+ * `Date.getTimezoneOffset` reports minutes west of UTC, so the sign and the unit
+ * both change here; a caller that reports an offset to another process needs the
+ * east-positive second count, and two callers had each written that conversion.
+ * @param at - Epoch milliseconds whose offset to read, because an offset depends
+ * on the instant for a zone that observes daylight saving.
+ * @returns Whole seconds east of UTC, from -43,200 (UTC-12) through 50,400 (UTC+14).
+ */
+export function localUtcOffsetSeconds(at: number): number {
+  return -new Date(at).getTimezoneOffset() * SECONDS_PER_MINUTE
+}

packages/util/time/tests/local-offset.spec.ts

@@ -0,0 +1,43 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { localUtcOffsetSeconds } from '@deepseek-ai/dsh-util-time'
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('localUtcOffsetSeconds', () => {
+  it('answers seconds east of UTC for a zone west of it', () => {
+    // The platform reports minutes west of UTC, so a western zone is a positive
+    // minute count that must come back negative.
+    vi.spyOn(Date.prototype, 'getTimezoneOffset').mockReturnValue(480)
+    expect(localUtcOffsetSeconds(0)).toBe(-28_800)
+  })
+
+  it('answers seconds east of UTC for a zone east of it', () => {
+    vi.spyOn(Date.prototype, 'getTimezoneOffset').mockReturnValue(-480)
+    expect(localUtcOffsetSeconds(0)).toBe(28_800)
+  })
+
+  it('keeps the half-hour zones exact', () => {
+    // Asia/Kolkata is UTC+05:30; the 30 minutes must survive as 1,800 seconds.
+    vi.spyOn(Date.prototype, 'getTimezoneOffset').mockReturnValue(-330)
+    expect(localUtcOffsetSeconds(1_700_000_000_000)).toBe(19_800)
+  })
+
+  it('reads the offset for the instant it is given, not for the current clock', () => {
+    const seen: number[] = []
+    vi.spyOn(Date.prototype, 'getTimezoneOffset').mockImplementation(function (this: Date): number {
+      seen.push(this.getTime())
+      return -60
+    })
+    localUtcOffsetSeconds(1_700_000_000_000)
+    expect(seen).toEqual([1_700_000_000_000])
+  })
+
+  it('stays inside the offsets real zones use', () => {
+    const offset = localUtcOffsetSeconds(Date.now())
+    expect(Number.isInteger(offset)).toBe(true)
+    expect(offset).toBeGreaterThanOrEqual(-43_200)
+    expect(offset).toBeLessThanOrEqual(50_400)
+  })
+})

pnpm-lock.yaml

@@ -679,6 +679,9 @@ importers:
       '@deepseek-ai/dsh-api-gateway':
         specifier: workspace:*
         version: link:../../packages/api/gateway
+      '@deepseek-ai/dsh-util-time':
+        specifier: workspace:*
+        version: link:../../packages/util/time
       electron-updater:
         specifier: ^6.8.9
         version: 6.8.9([email protected])
@@ -5156,6 +5159,9 @@ importers:
       '@deepseek-ai/dsh-settings':
         specifier: workspace:*
         version: link:../../settings/settings
+      '@deepseek-ai/dsh-util-time':
+        specifier: workspace:*
+        version: link:../../util/time
       '@testing-library/react':
         specifier: ^16.3.3
         version: 16.3.3(@testing-library/[email protected])(@types/[email protected](@types/[email protected]))(@types/[email protected])([email protected]([email protected]))([email protected])
@@ -12455,6 +12461,9 @@ importers:
       '@deepseek-ai/dsh-session-format':
         specifier: workspace:*
         version: link:../session-format
+      '@deepseek-ai/dsh-util-time':
+        specifier: workspace:*
+        version: link:../../util/time
       '@deepseek-ai/dsh-util-values':
         specifier: workspace:*
         version: link:../../util/values