refactor(workspace): store record timestamps in the shared instant profile

createdAt and updatedAt were written with the platform's toISOString, which
truncates a fractional epoch and writes an extended year past 9999, so a
durable record could hold an instant the four-digit-year profile every
other boundary reads refuses. The writes now go through
formatFourDigitYearInstant and a local storedInstant that raises a
RangeError for the two inputs the profile cannot represent, which are
unreachable from Date.now() and from a SessionHeader epoch. Every
representable epoch renders byte-identically.
This commit is contained in:
Chinesezjc committed 2026-10-19 17:49:30 +08:00
1 parent 617f2a2a8c
commit f7fbff4672
13 files changed
+77 -11

No files matched your search

@@ -9,8 +9,8 @@
en: abd0263d14861926
zh: e1736cd08e87f795
/agent-note-shared-time-vocabulary-for-wall-clock-selectors/decision:
en: c7a9a6dd3549f0e7
zh: 52bd82bb66aab30c
en: 5aba60ad25d7b9d3
zh: e44c05ab4ed7848c
/agent-note-shared-time-vocabulary-for-wall-clock-selectors/alternatives-considered:
en: 1737484c099fab52
zh: 303b144c52d167bd
@@ -22,6 +22,8 @@ Schedule consumes it and keeps every domain decision. `canonicalizeTimeZone`, `d
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).
Workspace record timestamps adopt the same profile. `dsh-workspace` wrote `createdAt` and `updatedAt` with the platform's `toISOString`, which truncates a fractional epoch and writes an extended year past 9999; those strings are durable, so a record could hold an instant the four-digit-year profile every other boundary reads refuses. The writes now go through `formatFourDigitYearInstant` and a local `storedInstant` that raises a `RangeError` for the two inputs the profile cannot represent, which are unreachable from `Date.now()` and from a `SessionHeader` epoch. The rendered string is byte-identical for every representable epoch.
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.
@@ -22,6 +22,8 @@ Schedule 消费它,并保留全部域内决策。`canonicalizeTimeZone`、`dec
最后一份规范时刻剖面副本也一并迁移。`packages/session/session-format-v0-to-v1/src/payload-validation.ts` 原本用自己的一段正则与往返比对校验持久记录里的调度时刻;共享的 `fourDigitYearEpoch` 拥有同一剖面,因此该迁移改为询问它,并保留自己的错误类型与文案。由于这个迁移要读取已发布的日志,其接受集由一份差分固定:覆盖规范形式、四位年份两端,以及只靠正则会被放进来的字符串(`2026-02-30`、四位小数、数字偏移、首尾空白)。
Workspace 记录的时间戳采用同一剖面。`dsh-workspace` 原先用平台的 `toISOString` 写 `createdAt` 与 `updatedAt`——它会把小数纪元截断,并在 9999 之后写成扩展年份;这些字符串是持久的,于是记录里可能存下其它边界都会拒绝的四位年份剖面之外的时刻。现在写入经由 `formatFourDigitYearInstant` 与一个本地 `storedInstant`,后者对该剖面无法表示的两种输入抛 `RangeError`;这两种输入从 `Date.now()` 与 `SessionHeader` 的纪元出发都不可达。对每个可表示的纪元,渲染结果逐字节不变。
受维护的 `@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,8 +48,8 @@
en: 6899c50041c3d1ef
zh: ea70fda89cc50465
/deepseek-ai-dsh-workspace/understand-the-implementation/durable-shape:
en: 056a266f4a15b29d
zh: e1589f5750662887
en: 6c0a57d935744c85
zh: f4f392bde4e549bd
/deepseek-ai-dsh-workspace/understand-the-implementation/lifecycle:
en: e41db10d48acbf9a
zh: 457d329fe37ba33c
+1 -1
View File
@@ -114,7 +114,7 @@ Archive admission is a capability seam over two Host events this package declare
### Durable shape
The registry opens the `workspace` domain (version 2): a `workspaces` table keyed by `WorkspaceId` plus one global state holding `workspaceIds` (the authoritative display order), `archivedSessionIds`, `pinnedSessionIds`, the optional `defaultWorkspaceId` first-use identity, and the optional `pendingMutation` marker. Archive and pin sets contain Session id strings, default to empty, and carry no per-entry objects or timestamps; the pin array keeps the most recently pinned id first. Archiving clears the pin in the same global-state write without changing Workspace membership. Unarchive runs no session-existence probe, because dropping an id from the set cannot introduce an unknown one, while archive verifies the session before adding it.
The registry opens the `workspace` domain (version 2): a `workspaces` table keyed by `WorkspaceId` plus one global state holding `workspaceIds` (the authoritative display order), `archivedSessionIds`, `pinnedSessionIds`, the optional `defaultWorkspaceId` first-use identity, and the optional `pendingMutation` marker. `createdAt` and `updatedAt` carry the canonical four-digit-year UTC instant that every other durable boundary reads, and a write refuses an epoch that profile cannot represent instead of truncating it or writing an extended year. Archive and pin sets contain Session id strings, default to empty, and carry no per-entry objects or timestamps; the pin array keeps the most recently pinned id first. Archiving clears the pin in the same global-state write without changing Workspace membership. Unarchive runs no session-existence probe, because dropping an id from the set cannot introduce an unknown one, while archive verifies the session before adding it.
### Lifecycle
+1 -1
View File
@@ -115,7 +115,7 @@ Workspace 注册不意味着拥有其目录。未来的破坏性文件系统操
### 持久形态
注册表打开 `workspace` 领域(版本 2):一张以 `WorkspaceId` 为键的 `workspaces` 表,加上一个持有 `workspaceIds`(权威显示顺序)、`archivedSessionIds`、`pinnedSessionIds`、可选的首次使用身份 `defaultWorkspaceId` 与可选 `pendingMutation` 标记的全局状态。归档与置顶集合存储会话 id 字符串,默认值为空,不包含逐项对象或时间戳;置顶数组把最近置顶的 id 放在前面。归档在同一次全局状态写入中清除置顶,但不改变 Workspace 成员关系。取消归档不做会话存在性探测,因为从集合中移除 id 不可能引入未知 id,而归档会在加入前校验会话。
注册表打开 `workspace` 领域(版本 2):一张以 `WorkspaceId` 为键的 `workspaces` 表,加上一个持有 `workspaceIds`(权威显示顺序)、`archivedSessionIds`、`pinnedSessionIds`、可选的首次使用身份 `defaultWorkspaceId` 与可选 `pendingMutation` 标记的全局状态。`createdAt` 与 `updatedAt` 携带的是其它所有持久边界都会读取的规范四位年份 UTC 时刻;写入会拒绝该剖面无法表示的纪元,而不是把它截断或写成扩展年份。归档与置顶集合存储会话 id 字符串,默认值为空,不包含逐项对象或时间戳;置顶数组把最近置顶的 id 放在前面。归档在同一次全局状态写入中清除置顶,但不改变 Workspace 成员关系。取消归档不做会话存在性探测,因为从集合中移除 id 不可能引入未知 id,而归档会在加入前校验会话。
### 生命周期
+3 -1
View File
@@ -39,10 +39,12 @@
"@deepseek-ai/dsh-session-persistence": "workspace:*",
"@deepseek-ai/dsh-storage": "workspace:*",
"@deepseek-ai/dsh-storage-domain": "workspace:*",
"@deepseek-ai/dsh-typert-protocol": "workspace:*"
"@deepseek-ai/dsh-typert-protocol": "workspace:*",
"@deepseek-ai/dsh-util-time": "workspace:*"
},
"dependencies": {
"@deepseek-ai/dsh-brand": "workspace:*",
"@deepseek-ai/dsh-util-time": "workspace:*",
"zod": "4.4.3"
},
"devDependencies": {
+2 -1
View File
@@ -14,6 +14,7 @@ import type { KvTable } from '@deepseek-ai/dsh-storage-domain'
import type { WorkspaceRecord } from './spec.ts'
import type { Workspace, WorkspaceId } from './types.ts'
import { realpathNormalize } from './paths.ts'
import { storedInstant } from './stored-instant.ts'
/** An insertSessionBefore request named a session or anchor not on the account (storage failures stay plain errors). */
export class WorkspaceMoveInvalidError extends Error {
@@ -211,7 +212,7 @@ export class WorkspaceEntity implements Workspace {
if (changed === current && sessionIds.length === current.sessionIds.length) {
throw unchangedSentinel
}
return { ...changed, sessionIds, updatedAt: new Date().toISOString() }
return { ...changed, sessionIds, updatedAt: storedInstant(Date.now()) }
})
} catch (error) {
if (error === unchangedSentinel) return
+4 -3
View File
@@ -19,6 +19,7 @@ import { defaultWorkspaceTitle, fullyQualifiedWorkspacePath, realpathNormalize }
import { workspaceDomainSpec } from './spec.ts'
import type { WorkspaceDomainState, WorkspaceRecord } from './spec.ts'
import type { SessionActivity, Workspace, WorkspaceId as WorkspaceIdBrand } from './types.ts'
import { storedInstant } from './stored-instant.ts'
export type {
SessionActivity, SessionActivityItem, SessionActivityKind, SessionActivityKindMap, Workspace,
@@ -516,7 +517,7 @@ export class WorkspaceRegistry extends Service {
const table = this.requireTable()
const state = this.requireState()
const id = WorkspaceId(randomUUID())
const now = new Date().toISOString()
const now = storedInstant(Date.now())
const record: WorkspaceRecord = {
path: canonical,
title: workspaceName,
@@ -680,7 +681,7 @@ export class WorkspaceRegistry extends Service {
.filter(sessionId => !accounted.has(sessionId))
if (sessionIds.length === 0) continue
id = WorkspaceId(randomUUID())
const createdAt = new Date(group.newestAt).toISOString()
const createdAt = storedInstant(group.newestAt)
const record: WorkspaceRecord = {
path: group.path,
title: defaultWorkspaceTitle(group.path),
@@ -707,7 +708,7 @@ export class WorkspaceRegistry extends Service {
await table.update(id, record => ({
...record,
sessionIds,
updatedAt: new Date().toISOString(),
updatedAt: storedInstant(Date.now()),
}))
for (const sessionId of historical) accounted.set(sessionId, id)
}
@@ -0,0 +1,25 @@
/**
* Durable workspace timestamps in the instant profile every harness boundary accepts.
* @module @deepseek-ai/dsh-workspace/stored-instant
*/
import { formatFourDigitYearInstant } from '@deepseek-ai/dsh-util-time'
/**
* Format one epoch as the canonical instant a workspace record stores.
*
* The shared four-digit-year profile is the one every other durable boundary in
* the harness reads, so a timestamp written here stays readable by them. The
* platform's `toISOString` would instead write an extended year for an epoch
* past 9999 and truncate a fractional epoch, so this rejects both rather than
* storing a value the rest of the system refuses.
* @param epoch - Epoch milliseconds of a workspace record timestamp.
* @returns The canonical four-digit-year instant.
* @throws RangeError when the epoch is not an integer inside the four-digit-year range.
*/
export function storedInstant(epoch: number): string {
const formatted = formatFourDigitYearInstant(epoch)
if (formatted === undefined) {
throw new RangeError(`workspace timestamp is not a four-digit-year integral epoch: ${String(epoch)}`)
}
return formatted
}
@@ -0,0 +1,27 @@
import { describe, expect, it } from 'vitest'
import { storedInstant } from '../src/stored-instant.ts'
describe('storedInstant', () => {
it('formats an integral epoch in the canonical profile', () => {
expect(storedInstant(0)).toBe('1970-01-01T00:00:00.000Z')
expect(storedInstant(Date.UTC(2026, 6, 24, 12, 34, 56, 789)))
.toBe('2026-07-24T12:34:56.789Z')
expect(storedInstant(Date.UTC(9999, 11, 31, 23, 59, 59, 999)))
.toBe('9999-12-31T23:59:59.999Z')
})
it('refuses a fractional epoch instead of truncating it', () => {
expect(() => storedInstant(1_500.5)).toThrow(RangeError)
})
it('refuses an epoch outside the four-digit-year range instead of writing an extended year', () => {
expect(() => storedInstant(Date.UTC(10_000, 0, 1))).toThrow(RangeError)
expect(() => storedInstant(-62_167_219_200_001)).toThrow(RangeError)
})
it('refuses an epoch that is not a number at all', () => {
for (const value of [Number.NaN, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY]) {
expect(() => storedInstant(value)).toThrow(RangeError)
}
})
})
@@ -34,6 +34,9 @@
},
{
"path": "../../util/brand"
},
{
"path": "../../util/time"
}
]
}
+3
View File
@@ -15629,6 +15629,9 @@ importers:
'@deepseek-ai/dsh-brand':
specifier: workspace:*
version: link:../../util/brand
'@deepseek-ai/dsh-util-time':
specifier: workspace:*
version: link:../../util/time
zod:
specifier: 4.4.3
version: 4.4.3