{"_id":"@buddhilive/dsh-brand","name":"@buddhilive/dsh-brand","dist-tags":{"alpha":"0.1.2-alpha.3","latest":"0.1.2-alpha.3"},"versions":{"0.1.2-alpha.3":{"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"},"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"},"_id":"@buddhilive/dsh-brand@0.1.2-alpha.3","bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","_integrity":"sha512-C9z4H0/O6X/Xg3IqoWzEEIG6ouG0n/R0ZrOnw03RdwZ5hoB4JGN4xUBBuB2cMFKQUkVlmaSvjlmzkiz+/Vn9/w==","_resolved":"C:\\DevDojo\\Buddhi\\buddhi-ai-harness\\dist\\npm\\buddhilive-dsh-brand-0.1.2-alpha.3.tgz","_from":"file:C:/DevDojo/Buddhi/buddhi-ai-harness/dist/npm/buddhilive-dsh-brand-0.1.2-alpha.3.tgz","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-C9z4H0/O6X/Xg3IqoWzEEIG6ouG0n/R0ZrOnw03RdwZ5hoB4JGN4xUBBuB2cMFKQUkVlmaSvjlmzkiz+/Vn9/w==","shasum":"bac579bc7dfafedda9855ffd843e196a81d61a05","tarball":"https://registry.npmjs.org/@buddhilive/dsh-brand/-/dsh-brand-0.1.2-alpha.3.tgz","fileCount":9,"unpackedSize":13342,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD4DjsFf8228+yW1OidvFMnWXcxmgq7/0fD8Nj9vGrHfgIgX3HHtP/IYGBoy7lKONBqaDqoi6MQ71BLST0Z/aPKc4c="}]},"_npmUser":{"name":"buddhilive","email":"visitbudkavin@gmail.com"},"directories":{},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dsh-brand_0.1.2-alpha.3_1788164172287_0.852669344996613"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-31T08:16:12.067Z","0.1.2-alpha.3":"2026-08-31T08:16:12.456Z","modified":"2026-08-31T08:16:12.696Z"},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"description":"Stateless branded-string primitives for the DeepSeek Harness","homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/util/brand"},"bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"license":"MIT","readme":"---\ndescription: \"供拥有跨包标识符的包使用的名义字符串类型与无状态构造函数。\"\nkind: \"package-library\"\n---\n\n# @buddhilive/dsh-brand\n\n[English](README.md) | 中文\n\n## 概述\n\n`dsh-brand` 让结构相同的字符串在类型层面不可互换：即使 `SessionId` 与 `ToolCallId` 在运行时都是普通字符串，前者也无法传给期望后者的位置。`brandString<T>()` 为领域拥有的字符串应用名义品牌且不持有共享运行时状态，让能力包可以拥有自己的具体 id 类型，而无需导入不相关的能力。\n\n## 目录\n\n- [使用本包](#use-this-package)\n- [理解实现](#understand-the-implementation)\n- [进一步探索](#further-exploration)\n- [开发备注](#dev-note)\n\n-----\n\n<a id=\"use-this-package\"></a>\n## 使用本包\n\n当包拥有的 id 跨越包边界、并可能与其他包的 id 混淆时，为其添加品牌；并非每个字符串都需要品牌。品牌化 id 是给 TypeScript 调用方的约定：它只会进入期望它的函数，来自其他包的 id 会在编译期被拒绝。\n\n### 为字符串添加品牌\n\n在所属包中声明品牌化类型，并在该包准入字符串的位置应用品牌：\n\n```ts\nimport { brandString, type Branded } from '@buddhilive/dsh-brand'\n\nexport type SessionId = Branded<'SessionId'>\n\nconst sessionId = brandString<SessionId>('session-1')\n```\n\n`brandString()` 只改变静态类型，不执行运行时校验。所属类型若有领域文法，应在调用前完成校验。添加品牌后，该 id 与普通字符串一样比较、记录日志、序列化为 JSON 和跨 wire 传输。\n\n### 何时添加品牌\n\n为跨包边界且可能被混淆的 id 添加品牌——`dsh-llm` 中的 `ToolCallId`、`dsh-session` 中共享的 agent/会话 `SessionId`、`dsh-jobs` 中的 `JobId`、`dsh-lsp` 中的 `LspProviderId`。从不离开所属包的字符串不需要这种抽象。\n\n-----\n\n<a id=\"understand-the-implementation\"></a>\n## 理解实现\n\n<details>\n<summary>实现细节——点击展开</summary>\n\n该原语是一个交叉类型：`string & { readonly [BRAND]: B }`，其中 `BRAND` 是模块私有的 `unique symbol`。\n\n### 源码地图\n\n| 文件 | 职责 |\n|---|---|\n| [`src/index.ts`](src/index.ts) | 品牌化字符串类型及其无状态构造函数 |\n| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；擦除由编译器保证） |\n\n### 值为何可移植\n\n私有 symbol 在运行时不存在：TypeScript 会将其擦除，因此品牌化值没有标签或 prototype。`brandString()` 原样返回输入。因此，彼此独立安装的副本无需共享注册表或 constructor identity，也会生成可互换的值。\n\n### 为何保持无依赖\n\n把这些 helper 放在独立包中，意味着 `dsh-jobs` 可以为 `JobId` 添加品牌，而无需导入不相关的能力包；每个能力仍然拥有其具体 id 的含义与校验。\n\n</details>\n\n-----\n\n<a id=\"further-exploration\"></a>\n## 进一步探索\n\n当你需要本原语所品牌化的 id 或围绕它的类型约定时，阅读以下页面。\n\n- [核心子系统](../../../docs/subsystems/core.zh.md)——共享 `SessionId` 品牌与类型规则的记录位置。\n- [LSP 子系统](../../../docs/subsystems/lsp.zh.md)——构建在本原语之上的品牌化提供方 id `LspProviderId`。\n- [jobs 包](../../jobs/jobs/README.zh.md)——由 jobs 能力拥有的 `JobId` 品牌。\n\n-----\n\n<a id=\"dev-note\"></a>\n## 开发备注\n\n<details>\n<summary>维护者的工作上下文——点击展开</summary>\n\n无。\n\n</details>\n","readmeFilename":"README.zh.md","_rev":"1-899a41ec60755643526ad4fb3ba9f039"}