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

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: ce05a652e2f863f737bf71fc473224fc16e25ab9
-README.zh.md: 07d1279b601d38d4dcf9ca10ddeccb3c3ed3547b
+README.md: 646a3e781ce8540277259f4ffd67b78f3049160b
+README.zh.md: 68290b35b64b4f519e2da06fc519d9d008e23646

package/README.md

@@ -1,28 +1,94 @@
-# dsh-brand
+---
+description: "Nominal string types and stateless constructors for packages that own identifiers crossing package boundaries."
+kind: "package-library"
+---
+
+# @deepseek-ai/dsh-brand
 
 English | [中文](README.zh.md)
 
-The `Branded<B>` nominal-typing primitive — a tiny, **type-only** package (no runtime code, no harness-package dependency) shared by every package that owns a cross-boundary id.
+## 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.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Dev Note](#dev-note)
+
+-----
+
+<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.
 
-## What `Branded` is
+### Branding a string
 
-A brand makes structurally-identical strings non-interchangeable at the type level: a `SessionId` cannot be passed where a `CallId` is expected, even though both are plain `string`s at runtime.
+Declare the branded type in the owning package and apply it at the point where that package admits a string:
 
 ```ts
-import type { Branded } from '@deepseek-ai/dsh-brand'
+import { brandString, type Branded } from '@deepseek-ai/dsh-brand'
 
 export type SessionId = Branded<'SessionId'>
 
-/** Brand a string as a SessionId (a plain cast — zero runtime cost). */
-export function SessionId(id: string): SessionId {
-  return id as SessionId
-}
+const sessionId = brandString<SessionId>('session-1')
 ```
 
-Construction goes through the per-id factory in the owning package. Comparison, logging, JSON serialization, and the wire format behave as for an ordinary string; the brand is erased at compile time.
+`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.
+
+### 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.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<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`.
+
+### 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) |
+
+### 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.
+
+### Why it stays dependency-free
+
+Keeping these helpers in their own package means `dsh-jobs` can brand `JobId` without importing an unrelated capability package, while each capability still owns the meaning and validation of its concrete ids.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when you need the ids this primitive brands or the type conventions around it.
+
+- [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.
+- [Jobs package](../../jobs/jobs/README.md) — the `JobId` brand owned by the jobs capability.
+
+-----
+
+<a id="dev-note"></a>
+## Dev Note
 
-## Policy: brand ids that cross package boundaries
+<details>
+<summary>Working context for maintainers — click to expand</summary>
 
-A package brands the ids it owns — `CallId` in `dsh-llm`, the shared agent/session `SessionId` in `dsh-session`, and `JobId` in `dsh-jobs`. Brand cross-package ids that could plausibly be confused; not every string needs one.
+None.
 
-This package owns only the primitive. Keeping it dependency-free lets `dsh-jobs`, for example, brand `JobId` without importing an unrelated capability package merely to reach `Branded`.
+</details>

package/README.zh.md

@@ -1,28 +1,94 @@
-# dsh-brand
+---
+description: "供拥有跨包标识符的包使用的名义字符串类型与无状态构造函数。"
+kind: "package-library"
+---
+
+# @deepseek-ai/dsh-brand
 
 [English](README.md) | 中文
 
-`Branded<B>` 名义类型原语：一个微小的**仅类型**包，无运行时代码，也不依赖其他 harness 包；所有负责跨边界 id 的包都会共享它。
+## 概述
+
+`dsh-brand` 让结构相同的字符串在类型层面不可互换：即使 `SessionId` 与 `ToolCallId` 在运行时都是普通字符串，前者也无法传给期望后者的位置。`brandString<T>()` 为领域拥有的字符串应用名义品牌且不持有共享运行时状态，让能力包可以拥有自己的具体 id 类型，而无需导入不相关的能力。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+当包拥有的 id 跨越包边界、并可能与其他包的 id 混淆时，为其添加品牌；并非每个字符串都需要品牌。品牌化 id 是给 TypeScript 调用方的约定：它只会进入期望它的函数，来自其他包的 id 会在编译期被拒绝。
 
-## `Branded` 是什么
+### 为字符串添加品牌
 
-品牌使 `SessionId` 和 `CallId` 这样结构相同的字符串在类型层面不可互换，尽管两者在运行时都是普通 `string`。
+在所属包中声明品牌化类型，并在该包准入字符串的位置应用品牌：
 
 ```ts
-import type { Branded } from '@deepseek-ai/dsh-brand'
+import { brandString, type Branded } from '@deepseek-ai/dsh-brand'
 
 export type SessionId = Branded<'SessionId'>
 
-/** Brand a string as a SessionId (a plain cast — zero runtime cost). */
-export function SessionId(id: string): SessionId {
-  return id as SessionId
-}
+const sessionId = brandString<SessionId>('session-1')
 ```
 
-构造操作通过所属包中各 id 专用的工厂完成。比较、日志记录、JSON 序列化和协议格式（wire format）的行为与普通字符串相同；品牌信息会在编译时被擦除。
+`brandString()` 只改变静态类型，不执行运行时校验。所属类型若有领域文法，应在调用前完成校验。添加品牌后，该 id 与普通字符串一样比较、记录日志、序列化为 JSON 和跨 wire 传输。
+
+### 何时添加品牌
+
+为跨包边界且可能被混淆的 id 添加品牌——`dsh-llm` 中的 `ToolCallId`、`dsh-session` 中共享的 agent/会话 `SessionId`、`dsh-jobs` 中的 `JobId`、`dsh-lsp` 中的 `LspProviderId`。从不离开所属包的字符串不需要这种抽象。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+该原语是一个交叉类型：`string & { readonly [BRAND]: B }`，其中 `BRAND` 是模块私有的 `unique symbol`。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 品牌化字符串类型及其无状态构造函数 |
+| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；擦除由编译器保证） |
+
+### 值为何可移植
+
+私有 symbol 在运行时不存在：TypeScript 会将其擦除，因此品牌化值没有标签或 prototype。`brandString()` 原样返回输入。因此，彼此独立安装的副本无需共享注册表或 constructor identity，也会生成可互换的值。
+
+### 为何保持无依赖
+
+把这些 helper 放在独立包中，意味着 `dsh-jobs` 可以为 `JobId` 添加品牌，而无需导入不相关的能力包；每个能力仍然拥有其具体 id 的含义与校验。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当你需要本原语所品牌化的 id 或围绕它的类型约定时，阅读以下页面。
+
+- [核心子系统](../../../docs/subsystems/core.zh.md)——共享 `SessionId` 品牌与类型规则的记录位置。
+- [LSP 子系统](../../../docs/subsystems/lsp.zh.md)——构建在本原语之上的品牌化提供方 id `LspProviderId`。
+- [jobs 包](../../jobs/jobs/README.zh.md)——由 jobs 能力拥有的 `JobId` 品牌。
+
+-----
+
+<a id="dev-note"></a>
+## 开发备注
 
-## 策略：为跨包边界的 id 添加品牌
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
 
-包为自己拥有的 id 添加品牌：`CallId` 位于 `dsh-llm`，共享的 agent/会话 `SessionId` 位于 `dsh-session`，`JobId` 位于 `dsh-jobs`。为可能被混淆的跨包 id 添加品牌，但无需为每个字符串都添加。
+无。
 
-该包只负责这一原语。保持无依赖意味着，例如 `dsh-jobs` 可以为 `JobId` 使用品牌类型，而无需仅为使用 `Branded` 而导入不相关的功能包。
+</details>

package/lib/index.js

@@ -1 +1,24 @@
-export {};
+//#region lib/types/index.js
+/**
+* Duplicate-install-safe nominal string 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.
+*
+* This package owns no concrete id and keeps no runtime identity or mutable
+* state, so independently installed copies produce interchangeable values.
+*
+* @module @deepseek-ai/dsh-brand
+*/
+/**
+* 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.
+*/
+function brandString(value) {
+	return value;
+}
+//#endregion
+export { brandString };

package/lib/invariant.js

@@ -9,8 +9,7 @@ const name = "brand-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 value
-* algebra is enforced by unit tests.
+* No runtime invariant: this utility owns no event stream, shared identity, or mutable module state.
 */
 const install = () => {};
 /**

package/lib/types/index.d.ts

@@ -1,22 +1,13 @@
 /**
- * The `Branded<B>` nominal-typing primitive — a type-only utility (no runtime
- * code, no harness-package dependency) shared by every package that owns a
- * cross-boundary id.
+ * Duplicate-install-safe nominal string helpers.
  *
  * A brand makes structurally-identical strings non-interchangeable at the type
- * level: a `SessionId` cannot be passed where a `CallId` is expected, even
- * though both are plain strings at runtime. Construction goes through a per-id
- * factory in the OWNING package (a plain cast inside — zero runtime cost);
- * comparison, logging, and serialization all behave as ordinary strings.
+ * 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.
  *
- * Policy: a package brands the ids it owns — `CallId` in dsh-llm (tool-call
- * correlation), the shared agent/session `SessionId` in dsh-session, and
- * `JobId` in dsh-jobs. Branding is for ids that cross package boundaries and
- * could plausibly be confused; not every string needs a brand.
- * This package owns ONLY the primitive — no concrete id, no runtime code beyond
- * the (erased) type — so the brand vocabulary stays dependency-free and a
- * package can brand its ids without depending on an unrelated capability
- * package.
+ * This package owns no concrete id and keeps no runtime identity or mutable
+ * state, so independently installed copies produce interchangeable values.
  *
  * @module @deepseek-ai/dsh-brand
  */
@@ -25,5 +16,11 @@ declare const BRAND: unique symbol;
 export type Branded<B extends string> = string & {
     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;
 export {};
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-brand",
-  "description": "Type-only Branded<B> nominal-typing primitive for the DeepSeek Harness",
-  "version": "0.1.1-rc.2",
+  "description": "Stateless branded-string primitives for the DeepSeek Harness",
+  "version": "0.1.2-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -32,11 +32,11 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2"
   }
 }