@deepseek-ai/dsh-brand 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

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/brand/README.md
+README.md: 68401d95a31ed2122386794ad5256a5cd93bb2a6
+README.zh.md: 0eeb2c8afb5fe1b279f49c839e769b8d0eea0a5a

package/README.md

@@ -0,0 +1,28 @@
+# 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.
+
+## What `Branded` is
+
+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.
+
+```ts
+import 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
+}
+```
+
+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.
+
+## Policy: brand ids that cross package boundaries
+
+A package brands the ids it owns — `CallId` in `dsh-llm`, the shared agent/session `SessionId` in `dsh-session`, and `TaskId` in `dsh-tasks`. Brand cross-package ids that could plausibly be confused; not every string needs one.
+
+This package owns only the primitive. Keeping it dependency-free lets `dsh-tasks`, for example, brand `TaskId` without importing an unrelated capability package merely to reach `Branded`.

package/README.zh.md

@@ -0,0 +1,28 @@
+# dsh-brand
+
+[English](README.md) | 中文
+
+`Branded<B>` 名义类型原语：一个微小的**仅类型**包，无运行时代码，也不依赖其他 harness 包；所有负责跨边界 id 的包都会共享它。
+
+## `Branded` 是什么
+
+品牌使 `SessionId` 和 `CallId` 这样结构相同的字符串在类型层面不可互换，尽管两者在运行时都是普通 `string`。
+
+```ts
+import 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
+}
+```
+
+构造操作通过所属包中各 id 专用的工厂完成。比较、日志记录、JSON 序列化和协议格式（wire format）的行为与普通字符串相同；品牌信息会在编译时被擦除。
+
+## 策略：为跨包边界的 id 添加品牌
+
+包为自己拥有的 id 添加品牌：`CallId` 位于 `dsh-llm`，共享的 agent/会话 `SessionId` 位于 `dsh-session`，`TaskId` 位于 `dsh-tasks`。为可能被混淆的跨包 id 添加品牌，但无需为每个字符串都添加。
+
+该包只负责这一原语。保持无依赖意味着，例如 `dsh-tasks` 可以为 `TaskId` 使用品牌类型，而无需仅为使用 `Branded` 而导入不相关的功能包。

package/lib/index.js

@@ -0,0 +1 @@
+export {};

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#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 pure utility owns no event stream or mutable runtime data; its value
+* 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,29 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * Policy: a package brands the ids it owns — `CallId` in dsh-llm (tool-call
+ * correlation), the shared agent/session `SessionId` in dsh-session, and
+ * `TaskId` in dsh-tasks. 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.
+ *
+ * @module @deepseek-ai/dsh-brand
+ */
+declare const BRAND: unique symbol;
+/** A string carrying a compile-time-only brand `B`. */
+export type Branded<B extends string> = string & {
+    readonly [BRAND]: B;
+};
+export {};
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@deepseek-ai/dsh-brand",
+  "description": "Type-only Branded<B> nominal-typing primitive for the DeepSeek Harness",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/util/brand"
+  },
+  "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": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}