@deepseek-ai/dsh-util-time 0.1.2-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/util/time/README.md
+README.md: 40f6b4d9ef50f0f35eb9b143ed31cccce352647c
+README.zh.md: f6648415dc1ab89382f92e9f0e6ab9465e7fc2b1

package/README.md

@@ -0,0 +1,68 @@
+---
+description: "IANA time-zone validation and canonicalization for maintainers accepting a caller-reported zone at a wire boundary."
+kind: "package-library"
+---
+
+# dsh-util-time
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Zero-dependency zone vocabulary for the wire boundaries that accept a caller's time zone. `canonicalClientTimeZone` admits `UTC` or an IANA `Area/Location` name and answers the platform-canonical spelling of it, so an alias never reaches a durable record: a zone identity is stored on messages and re-derived later by another process, where an alias would not compare equal. The library validates and canonicalizes only — it formats no time and owns no failure vocabulary, because each boundary throws its own domain code.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [API](#api)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+It is a **library, not a service or plugin**: no `ctx`, registers nothing, holds no state.
+
+Call it at the boundary that receives the zone, before the value reaches anything durable. An unusable name answers `undefined`, and the caller raises its own refusal — `session/invalid-time-zone` for the Session prompt, `subagent/invalid-time-zone` for a subagent continuation.
+
+-----
+
+<a id="api"></a>
+## API
+
+```ts
+import { canonicalClientTimeZone } from '@deepseek-ai/dsh-util-time'
+```
+
+| Export | Role |
+|---|---|
+| `canonicalClientTimeZone(value)` | Canonical `UTC` or IANA `Area/Location` name for an accepted zone, `undefined` for a blank, padded, abbreviated, single-segment, or platform-unsupported one. |
+
+<a id="model-experience"></a>
+## Model Experience
+
+Indirectly, through the consumer that records a canonical zone on a durable message, from which `dsh-time-context` renders the turn's model-visible zone instruction and timestamp.
+
+#### KV Cache effect
+
+None of its own. The consumer that injects a zone-derived line into a request owns that request's cache behavior.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Alias resolution follows the runtime's ICU data** — which name an alias group canonicalizes to is the platform's answer, so two processes on different Node builds can disagree about it.
+- **Validation only** — no formatting, offset arithmetic, DST reasoning, or instant conversion; consumers needing those use `Intl` directly.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,68 @@
+---
+description: "面向在协议边界接收调用方所报时区的维护者，说明 IANA 时区校验与规范化。"
+kind: "package-library"
+---
+
+# dsh-util-time
+
+[English](README.md) | 中文
+
+## 概述
+
+零依赖的时区词汇，供接收调用方时区的协议边界使用。`canonicalClientTimeZone` 只接受 `UTC` 或 IANA `Area/Location` 名称，并回答该名称在当前平台上的规范拼写，因此别名不会进入持久记录：时区标识会存在消息上、并由另一个进程稍后重新推导，别名在那里比不相等。本库只做校验与规范化——不格式化任何时间，也不持有失败词汇，因为每个边界抛自己的域码。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [API](#api)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+它是**库，不是服务也不是插件**：无 `ctx`、不注册任何东西、不持有状态。
+
+在接收时区的那个边界上调用它，让值在进入任何持久物之前先过一遍。不可用的名称回答 `undefined`，由调用方抛出自己的拒绝——Session prompt 用 `session/invalid-time-zone`，subagent 续话用 `subagent/invalid-time-zone`。
+
+-----
+
+<a id="api"></a>
+## API
+
+```ts
+import { canonicalClientTimeZone } from '@deepseek-ai/dsh-util-time'
+```
+
+| 导出 | 职责 |
+|---|---|
+| `canonicalClientTimeZone(value)` | 对接受的时区回答规范的 `UTC` 或 IANA `Area/Location` 名称；空串、带空白、缩写、单段或平台不支持的名称回答 `undefined`。 |
+
+<a id="model-experience"></a>
+## Model Experience
+
+间接影响，取决于把规范时区记到持久消息上的那个消费方——`dsh-time-context` 据此渲染该轮模型可见的时区指令与时间戳。
+
+#### KV Cache effect
+
+自身没有。把时区派生文本注入请求的那个消费方，对该请求的缓存行为负责。
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **别名解析取决于运行时的 ICU 数据**——一个别名组规范化成哪个名称由平台回答，因此两个跑在不同 Node 构建上的进程可能给出不同答案。
+- **只做校验**——不格式化、不做偏移运算、不推导 DST、不做时刻换算；需要这些的消费方直接用 `Intl`。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,31 @@
+//#region lib/types/index.js
+/**
+* Time vocabulary shared by the wire boundaries that accept a caller's zone.
+* Validation and canonicalization only: this library formats nothing and owns
+* no failure vocabulary — each boundary declares and throws its own refusal.
+* @module @deepseek-ai/dsh-util-time
+*/
+/** Strict browser-zone profile: UTC or an IANA Area/Location-style identifier. */
+const IANA_TIME_ZONE = /^[A-Za-z][A-Za-z0-9_+.-]*(?:\/[A-Za-z0-9_+.-]+)+$/;
+/**
+* Validate and canonicalize one caller-supplied IANA zone at a wire boundary.
+*
+* The canonical name is what a later reader needs: a zone identity is stored on
+* durable records and resolved again by another process, so an alias accepted
+* here would not compare equal to the zone a reader derives.
+* @param value - the caller's reported zone name.
+* @returns the canonical zone, or `undefined` when the name is unusable.
+*/
+function canonicalClientTimeZone(value) {
+	if (value.length === 0 || value.trim() !== value || value !== "UTC" && !IANA_TIME_ZONE.test(value)) return void 0;
+	try {
+		const canonical = new Intl.DateTimeFormat("en-US", { timeZone: value }).resolvedOptions().timeZone;
+		/* v8 ignore next -- Intl returns UTC or a canonical IANA Area/Location for accepted input. */
+		if (canonical !== "UTC" && !IANA_TIME_ZONE.test(canonical)) return void 0;
+		return canonical;
+	} catch {
+		return;
+	}
+}
+//#endregion
+export { canonicalClientTimeZone };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-util-time`.
+* @module @deepseek-ai/dsh-util-time/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-util-time";
+/** Cordis companion plugin name. */
+const name = "time-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this pure utility owns no event stream or mutable runtime data; its
+* zone-canonicalization algebra is enforced by unit tests.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Time vocabulary shared by the wire boundaries that accept a caller's zone.
+ * Validation and canonicalization only: this library formats nothing and owns
+ * no failure vocabulary — each boundary declares and throws its own refusal.
+ * @module @deepseek-ai/dsh-util-time
+ */
+/**
+ * Validate and canonicalize one caller-supplied IANA zone at a wire boundary.
+ *
+ * The canonical name is what a later reader needs: a zone identity is stored on
+ * durable records and resolved again by another process, so an alias accepted
+ * here would not compare equal to the zone a reader derives.
+ * @param value - the caller's reported zone name.
+ * @returns the canonical zone, or `undefined` when the name is unusable.
+ */
+export declare function canonicalClientTimeZone(value: string): string | undefined;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-util-time`.
+ * @module @deepseek-ai/dsh-util-time/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "time-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@deepseek-ai/dsh-util-time",
+  "description": "Zero-dependency time vocabulary shared by wire boundaries: canonicalClientTimeZone (IANA zone validation and canonicalization only, no formatting)",
+  "version": "0.1.2-alpha.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/util/time"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2"
+  }
+}