@deepseek-ai/dsh-brand 0.1.2-alpha.2 → 0.1.2-alpha.4

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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/brand/README.md
-README.md: 646a3e781ce8540277259f4ffd67b78f3049160b
-README.zh.md: 68290b35b64b4f519e2da06fc519d9d008e23646
+README.md: f9bcea11d223645a9bb1d2194a129f353220c684
+README.zh.md: be9d8f828e05655b41b054a11221e382c90ef58b

package/README.md

@@ -1,5 +1,5 @@
 ---
-description: "Nominal string types and stateless constructors for packages that own identifiers crossing package boundaries."
+description: "Nominal string and number types with stateless constructors for packages that own confusable domain values."
 kind: "package-library"
 ---
 
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-brand` makes structurally identical strings non-interchangeable at the type level: a `SessionId` cannot be passed where a `ToolCallId` is expected even though both are plain strings at runtime. `brandString<T>()` applies a nominal brand to one domain-owned string without shared runtime state and lets capability packages own their concrete id types without importing an unrelated capability.
+`dsh-brand` makes structurally identical strings or numbers non-interchangeable at the type level: a `SessionId` cannot be passed where a `ToolCallId` is expected, and an event sequence cannot be passed where a log offset is required. `brandString<T>()` and `brandNumber<T>()` apply nominal brands without shared runtime state, so owning packages can define domain types without importing an unrelated capability.
 
 ## Table of Contents
 
@@ -23,7 +23,7 @@ English | [中文](README.zh.md)
 <a id="use-this-package"></a>
 ## Use this package
 
-Brand the ids a package owns when they cross a package boundary and could plausibly be confused with another package's ids; not every string needs a brand. A branded id is a contract for TypeScript callers: it only ever enters the functions that expect it, and an id from another package is rejected at compile time.
+Brand a domain value when it crosses a package boundary and could plausibly be confused with another value represented by the same primitive; not every string or number needs a brand. A branded value is a contract for TypeScript callers: it enters only functions that expect its domain, and a different brand is rejected at compile time.
 
 ### Branding a string
 
@@ -39,9 +39,23 @@ const sessionId = brandString<SessionId>('session-1')
 
 `brandString()` changes only the static type and performs no runtime validation. Validate domain grammar before calling it when the owning type has one. Once branded, the id compares, logs, serializes to JSON, and crosses the wire as an ordinary string.
 
+### Branding a number
+
+Declare a numeric brand in its owning package and apply it only after that package admits the number:
+
+```ts
+import { brandNumber, type BrandedNumber } from '@deepseek-ai/dsh-brand'
+
+export type SessionSeq = BrandedNumber<'SessionSeq'>
+
+const seq = brandNumber<SessionSeq>(7)
+```
+
+`brandNumber()` returns the original number and performs no validation. The owning package validates requirements such as non-negative safe-integer range before branding. Comparison, arithmetic, logging, JSON serialization, and wire transport retain ordinary number behavior; arithmetic produces an unbranded number that the owner must admit again before it re-enters the domain.
+
 ### When to brand
 
-Brand ids that cross package boundaries and could plausibly be confused — `ToolCallId` in `dsh-llm`, the shared agent/session `SessionId` in `dsh-session`, `JobId` in `dsh-jobs`, `LspProviderId` in `dsh-lsp`. Strings that never leave their owning package do not need this abstraction.
+Brand values that cross package boundaries and could plausibly be confused — `ToolCallId` in `dsh-llm`, the shared agent/session `SessionId` in `dsh-session`, `JobId` in `dsh-jobs`, and `SessionSeq` versus `SessionLogOffset` in `dsh-session`. Values that stay local or cannot be confused do not need this abstraction.
 
 -----
 
@@ -51,18 +65,18 @@ Brand ids that cross package boundaries and could plausibly be confused — `Too
 <details>
 <summary>Implementation internals — click to expand</summary>
 
-The primitive is one intersection type: `string & { readonly [BRAND]: B }`, where `BRAND` is a module-private `unique symbol`.
+The package defines two intersection types, `string & { readonly [BRAND]: B }` and `number & { readonly [BRAND]: B }`, where `BRAND` is a module-private `unique symbol`.
 
 ### Source map
 
 | File | Role |
 |---|---|
-| [`src/index.ts`](src/index.ts) | Branded string type and its stateless constructor |
-| [`src/invariant.ts`](src/invariant.ts) | Invariant companion (no runtime invariant; erasure is enforced by the compiler) |
+| [`src/index.ts`](src/index.ts) | Branded string and number types with stateless constructors |
+| — | No runtime invariant companion is published; this pure utility owns no event stream or mutable runtime data; its value algebra is enforced by unit tests. |
 
 ### How values stay portable
 
-The private symbol never exists at runtime: TypeScript erases it, so branded values have no tag or prototype. `brandString()` returns its input unchanged. Separate installed copies therefore produce interchangeable values without sharing a registry or constructor identity.
+The private symbol never exists at runtime: TypeScript erases it, so branded values have no tag or prototype. `brandString()` and `brandNumber()` return their inputs unchanged. Separate installed copies therefore produce interchangeable values without sharing a registry or constructor identity.
 
 ### Why it stays dependency-free
 
@@ -75,7 +89,7 @@ Keeping these helpers in their own package means `dsh-jobs` can brand `JobId` wi
 <a id="further-exploration"></a>
 ## Further Exploration
 
-Read these pages when you need the ids this primitive brands or the type conventions around it.
+Read these pages when you need the values these primitives brand or the type conventions around them.
 
 - [Core subsystem](../../../docs/subsystems/core.md) — where the shared `SessionId` brand and the type rules are documented.
 - [LSP subsystem](../../../docs/subsystems/lsp.md) — `LspProviderId`, a branded provider id built on this primitive.

package/README.zh.md

@@ -1,5 +1,5 @@
 ---
-description: "供拥有跨包标识符的包使用的名义字符串类型与无状态构造函数。"
+description: "供拥有易混淆领域值的包使用的名义字符串与数字类型及无状态构造函数。"
 kind: "package-library"
 ---
 
@@ -9,7 +9,7 @@ kind: "package-library"
 
 ## 概述
 
-`dsh-brand` 让结构相同的字符串在类型层面不可互换：即使 `SessionId` 与 `ToolCallId` 在运行时都是普通字符串，前者也无法传给期望后者的位置。`brandString<T>()` 为领域拥有的字符串应用名义品牌且不持有共享运行时状态，让能力包可以拥有自己的具体 id 类型，而无需导入不相关的能力。
+`dsh-brand` 让结构相同的字符串或数字在类型层面不可互换：`SessionId` 无法传给期望 `ToolCallId` 的位置，事件序号也无法传给需要日志偏移量的位置。`brandString<T>()` 与 `brandNumber<T>()` 在不持有共享运行时状态的情况下应用名义品牌，让所属包可以定义领域类型，而无需导入不相关的能力。
 
 ## 目录
 
@@ -23,7 +23,7 @@ kind: "package-library"
 <a id="use-this-package"></a>
 ## 使用本包
 
-当包拥有的 id 跨越包边界、并可能与其他包的 id 混淆时，为其添加品牌；并非每个字符串都需要品牌。品牌化 id 是给 TypeScript 调用方的约定：它只会进入期望它的函数，来自其他包的 id 会在编译期被拒绝。
+当领域值跨越包边界，并可能与使用同一原语表示的另一个值混淆时，为其添加品牌；并非每个字符串或数字都需要品牌。品牌化值是给 TypeScript 调用方的约定：它只会进入期望该领域的函数，不同品牌会在编译期被拒绝。
 
 ### 为字符串添加品牌
 
@@ -39,9 +39,23 @@ const sessionId = brandString<SessionId>('session-1')
 
 `brandString()` 只改变静态类型，不执行运行时校验。所属类型若有领域文法，应在调用前完成校验。添加品牌后，该 id 与普通字符串一样比较、记录日志、序列化为 JSON 和跨 wire 传输。
 
+### 为数字添加品牌
+
+在所属包中声明数字品牌，并且仅在该包准入数字之后应用品牌：
+
+```ts
+import { brandNumber, type BrandedNumber } from '@deepseek-ai/dsh-brand'
+
+export type SessionSeq = BrandedNumber<'SessionSeq'>
+
+const seq = brandNumber<SessionSeq>(7)
+```
+
+`brandNumber()` 原样返回数字，不执行校验。所属包会在添加品牌前校验非负安全整数范围等要求。比较、算术、日志、JSON 序列化与 wire 传输保留普通数字行为；算术会产生未品牌化数字，所属包必须重新准入该数字，才能让它再次进入领域。
+
 ### 何时添加品牌
 
-为跨包边界且可能被混淆的 id 添加品牌——`dsh-llm` 中的 `ToolCallId`、`dsh-session` 中共享的 agent/会话 `SessionId`、`dsh-jobs` 中的 `JobId`、`dsh-lsp` 中的 `LspProviderId`。从不离开所属包的字符串不需要这种抽象。
+为跨包边界且可能被混淆的值添加品牌——`dsh-llm` 中的 `ToolCallId`、`dsh-session` 中共享的 agent/会话 `SessionId`、`dsh-jobs` 中的 `JobId`，以及 `dsh-session` 中的 `SessionSeq` 与 `SessionLogOffset`。保持局部或无法混淆的值不需要这种抽象。
 
 -----
 
@@ -51,18 +65,18 @@ const sessionId = brandString<SessionId>('session-1')
 <details>
 <summary>实现细节——点击展开</summary>
 
-该原语是一个交叉类型：`string & { readonly [BRAND]: B }`，其中 `BRAND` 是模块私有的 `unique symbol`。
+该包定义两个交叉类型：`string & { readonly [BRAND]: B }` 与 `number & { readonly [BRAND]: B }`，其中 `BRAND` 是模块私有的 `unique symbol`。
 
 ### 源码地图
 
 | 文件 | 职责 |
 |---|---|
-| [`src/index.ts`](src/index.ts) | 品牌化字符串类型及其无状态构造函数 |
-| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；擦除由编译器保证） |
+| [`src/index.ts`](src/index.ts) | 品牌化字符串与数字类型及其无状态构造函数 |
+| — | 不发布运行时不变量伴生入口；擦除由编译器保证。 |
 
 ### 值为何可移植
 
-私有 symbol 在运行时不存在：TypeScript 会将其擦除，因此品牌化值没有标签或 prototype。`brandString()` 原样返回输入。因此，彼此独立安装的副本无需共享注册表或 constructor identity，也会生成可互换的值。
+私有 symbol 在运行时不存在：TypeScript 会将其擦除，因此品牌化值没有标签或 prototype。`brandString()` 与 `brandNumber()` 都原样返回输入。因此，彼此独立安装的副本无需共享注册表或 constructor identity，也会生成可互换的值。
 
 ### 为何保持无依赖
 
@@ -75,7 +89,7 @@ const sessionId = brandString<SessionId>('session-1')
 <a id="further-exploration"></a>
 ## 进一步探索
 
-当你需要本原语所品牌化的 id 或围绕它的类型约定时，阅读以下页面。
+当你需要这些原语所品牌化的值或围绕它们的类型约定时，阅读以下页面。
 
 - [核心子系统](../../../docs/subsystems/core.zh.md)——共享 `SessionId` 品牌与类型规则的记录位置。
 - [LSP 子系统](../../../docs/subsystems/lsp.zh.md)——构建在本原语之上的品牌化提供方 id `LspProviderId`。

package/lib/index.js

@@ -1,13 +1,13 @@
 //#region lib/types/index.js
 /**
-* Duplicate-install-safe nominal string helpers.
+* Duplicate-install-safe nominal primitive helpers.
 *
-* A brand makes structurally-identical strings non-interchangeable at the type
-* level: a `SessionId` cannot be passed where a `ToolCallId` is expected, even
-* though both are plain strings at runtime. Comparison, logging, and
-* serialization all behave as ordinary strings.
+* A brand makes structurally identical strings or numbers non-interchangeable
+* at the type level: a `SessionId` cannot be passed where a `ToolCallId` is
+* expected, and an event sequence cannot be passed as a log offset. Comparison,
+* logging, and serialization retain the underlying primitive behavior.
 *
-* This package owns no concrete id and keeps no runtime identity or mutable
+* This package owns no concrete domain value and keeps no runtime identity or mutable
 * state, so independently installed copies produce interchangeable values.
 *
 * @module @deepseek-ai/dsh-brand
@@ -20,5 +20,13 @@
 function brandString(value) {
 	return value;
 }
+/**
+* Apply a compile-time number brand without changing the value.
+* @param value - number admitted by the domain that owns the target brand.
+* @returns the same number with the requested compile-time brand.
+*/
+function brandNumber(value) {
+	return value;
+}
 //#endregion
-export { brandString };
+export { brandNumber, brandString };

package/lib/types/index.d.ts

@@ -1,12 +1,12 @@
 /**
- * Duplicate-install-safe nominal string helpers.
+ * Duplicate-install-safe nominal primitive helpers.
  *
- * A brand makes structurally-identical strings non-interchangeable at the type
- * level: a `SessionId` cannot be passed where a `ToolCallId` is expected, even
- * though both are plain strings at runtime. Comparison, logging, and
- * serialization all behave as ordinary strings.
+ * A brand makes structurally identical strings or numbers non-interchangeable
+ * at the type level: a `SessionId` cannot be passed where a `ToolCallId` is
+ * expected, and an event sequence cannot be passed as a log offset. Comparison,
+ * logging, and serialization retain the underlying primitive behavior.
  *
- * This package owns no concrete id and keeps no runtime identity or mutable
+ * This package owns no concrete domain value and keeps no runtime identity or mutable
  * state, so independently installed copies produce interchangeable values.
  *
  * @module @deepseek-ai/dsh-brand
@@ -16,11 +16,21 @@ declare const BRAND: unique symbol;
 export type Branded<B extends string> = string & {
     readonly [BRAND]: B;
 };
+/** A number carrying a compile-time-only brand `B`. */
+export type BrandedNumber<B extends string> = number & {
+    readonly [BRAND]: B;
+};
 /**
  * Apply a compile-time string brand without changing the value.
  * @param value - string admitted by the domain that owns the target brand.
  * @returns the same string with the requested compile-time brand.
  */
 export declare function brandString<T extends Branded<string>>(value: string | T): T;
+/**
+ * Apply a compile-time number brand without changing the value.
+ * @param value - number admitted by the domain that owns the target brand.
+ * @returns the same number with the requested compile-time brand.
+ */
+export declare function brandNumber<T extends BrandedNumber<string>>(value: number | T): T;
 export {};
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-brand",
-  "description": "Stateless branded-string primitives for the DeepSeek Harness",
-  "version": "0.1.2-alpha.2",
+  "description": "Stateless branded primitive types for the DeepSeek Harness",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
@@ -18,25 +18,18 @@
       "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/cordis": "^4.0.2",
-    "@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"
+    "@deepseek-ai/cordis": "^4.0.2"
   }
 }

package/lib/invariant.js

@@ -1,22 +0,0 @@
-//#region lib/types/invariant.js
-/**
-* Package-owned invariant companion for `@deepseek-ai/dsh-brand`.
-* @module @deepseek-ai/dsh-brand/invariant
-*/
-const PACKAGE_NAME = "@deepseek-ai/dsh-brand";
-/** Cordis companion plugin name. */
-const name = "brand-invariant";
-/** Service required before the companion can reserve package ownership. */
-const inject = ["invariants"];
-/**
-* No runtime invariant: this utility owns no event stream, shared identity, or mutable module state.
-*/
-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/invariant.d.ts

@@ -1,16 +0,0 @@
-/**
- * Package-owned invariant companion for `@deepseek-ai/dsh-brand`.
- * @module @deepseek-ai/dsh-brand/invariant
- */
-import type { Context } from '@deepseek-ai/cordis';
-/** Cordis companion plugin name. */
-export declare const name = "brand-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