@buddhilive/dsh-brand 0.1.2-alpha.3

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/brand/README.md
+README.md: 646a3e781ce8540277259f4ffd67b78f3049160b
+README.zh.md: 68290b35b64b4f519e2da06fc519d9d008e23646

package/README.md

@@ -0,0 +1,94 @@
+---
+description: "Nominal string types and stateless constructors for packages that own identifiers crossing package boundaries."
+kind: "package-library"
+---
+
+# @buddhilive/dsh-brand
+
+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.
+
+## 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.
+
+### Branding a string
+
+Declare the branded type in the owning package and apply it at the point where that package admits a string:
+
+```ts
+import { brandString, type Branded } from '@buddhilive/dsh-brand'
+
+export type SessionId = Branded<'SessionId'>
+
+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.
+
+### 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
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,94 @@
+---
+description: "供拥有跨包标识符的包使用的名义字符串类型与无状态构造函数。"
+kind: "package-library"
+---
+
+# @buddhilive/dsh-brand
+
+[English](README.md) | 中文
+
+## 概述
+
+`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 会在编译期被拒绝。
+
+### 为字符串添加品牌
+
+在所属包中声明品牌化类型，并在该包准入字符串的位置应用品牌：
+
+```ts
+import { brandString, type Branded } from '@buddhilive/dsh-brand'
+
+export type SessionId = Branded<'SessionId'>
+
+const sessionId = brandString<SessionId>('session-1')
+```
+
+`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>
+## 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,24 @@
+//#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 @buddhilive/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

@@ -0,0 +1,22 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@buddhilive/dsh-brand`.
+* @module @buddhilive/dsh-brand/invariant
+*/
+const PACKAGE_NAME = "@buddhilive/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/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 @buddhilive/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;
+};
+/**
+ * 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/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@buddhilive/dsh-brand`.
+ * @module @buddhilive/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": "@buddhilive/dsh-brand",
+  "description": "Stateless branded-string primitives for the DeepSeek Harness",
+  "version": "0.1.2-alpha.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Buddhilive/buddhi-ai-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": "MIT",
+  "peerDependencies": {
+    "@buddhilive/dsh-invariants": "^0.1.2-alpha.3",
+    "@deepseek-ai/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "@buddhilive/dsh-invariants": "^0.1.2-alpha.3",
+    "@deepseek-ai/cordis": "^4.0.2"
+  }
+}