@qilin-agent/brand 0.0.0-stage → 3.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+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,46 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/util/brand/README.md
+/:
+  en: 9c53a07c1a04a19a
+  zh: 1fd4666fbc6c39a8
+/qilin-agent-brand:
+  en: ed14efbbe8b6cfcf
+  zh: 7ae20e3c6d72185f
+/qilin-agent-brand/summary:
+  en: 57d5a106e98e6b9d
+  zh: 664ed658a6c38e60
+/qilin-agent-brand/table-of-contents:
+  en: c992e0cd2e7042d6
+  zh: 2e8cd826664632d1
+/qilin-agent-brand/use-this-package:
+  en: abdf7a28d3af06f0
+  zh: 8d68807326b03898
+/qilin-agent-brand/use-this-package/branding-a-string:
+  en: 49b137dc146f5c0a
+  zh: 7fe82acb5ba633e8
+/qilin-agent-brand/use-this-package/branding-a-number:
+  en: fd9617ca2804f47b
+  zh: cd3c0e6bda613509
+/qilin-agent-brand/use-this-package/when-to-brand:
+  en: 4224e7edc4200bfe
+  zh: b1cec114c5ba4024
+/qilin-agent-brand/understand-the-implementation:
+  en: 98a62299f46d5050
+  zh: 042d3c626e1fbe34
+/qilin-agent-brand/understand-the-implementation/source-map:
+  en: 5032eec37cf68046
+  zh: 971402fa5c6c0e63
+/qilin-agent-brand/understand-the-implementation/how-values-stay-portable:
+  en: 6a126aa2e31591c0
+  zh: c85e395cdb0bbb0e
+/qilin-agent-brand/understand-the-implementation/why-it-stays-dependency-free:
+  en: 5bcb11c1ef6fa468
+  zh: 9c389300baa819a8
+/qilin-agent-brand/further-exploration:
+  en: ee41e38fb8fc21cb
+  zh: 67a6a94d3cd29983
+/qilin-agent-brand/dev-note:
+  en: 5de1d6304e00c58f
+  zh: 8d8225361cfa29e5

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+---
+description: "Nominal string and number types with stateless constructors for packages that own confusable domain values."
+kind: "package-library"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/brand
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`qilin-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
+
+- [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 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
+
+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 '@qilin-agent/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.
+
+### 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 '@qilin-agent/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 values that cross package boundaries and could plausibly be confused — `ToolCallId` in `qilin-llm`, the shared agent/session `SessionId` in `qilin-session`, `JobId` in `qilin-jobs`, and `SessionSeq` versus `SessionLogOffset` in `qilin-session`. Values that stay local or cannot be confused do not need this abstraction.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+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 and number types with stateless constructors |
+
+### How values stay portable
+
+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
+
+Keeping these helpers in their own package means `qilin-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 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.
+- [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,107 @@
+---
+description: "供拥有易混淆领域值的包使用的名义字符串与数字类型及无状态构造函数。"
+kind: "package-library"
+---
+
+# @qilin-agent/brand
+
+[English](README.md) | 中文
+
+## 概述
+
+`qilin-brand` 让结构相同的字符串或数字在类型层面不可互换：`SessionId` 无法传给期望 `ToolCallId` 的位置，事件序号也无法传给需要日志偏移量的位置。`brandString<T>()` 与 `brandNumber<T>()` 在不持有共享运行时状态的情况下应用名义品牌，让所属包可以定义领域类型，而无需导入不相关的能力。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+当领域值跨越包边界，并可能与使用同一原语表示的另一个值混淆时，为其添加品牌；并非每个字符串或数字都需要品牌。品牌化值是给 TypeScript 调用方的约定：它只会进入期望该领域的函数，不同品牌会在编译期被拒绝。
+
+### 为字符串添加品牌
+
+在所属包中声明品牌化类型，并在该包准入字符串的位置应用品牌：
+
+```ts
+import { brandString, type Branded } from '@qilin-agent/brand'
+
+export type SessionId = Branded<'SessionId'>
+
+const sessionId = brandString<SessionId>('session-1')
+```
+
+`brandString()` 只改变静态类型，不执行运行时校验。所属类型若有领域文法，应在调用前完成校验。添加品牌后，该 id 在比较、日志记录、JSON 序列化和协议传输中仍表现为普通字符串。
+
+### 为数字添加品牌
+
+在所属包中声明数字品牌，并且仅在该包准入数字之后应用品牌：
+
+```ts
+import { brandNumber, type BrandedNumber } from '@qilin-agent/brand'
+
+export type SessionSeq = BrandedNumber<'SessionSeq'>
+
+const seq = brandNumber<SessionSeq>(7)
+```
+
+`brandNumber()` 原样返回数字，不执行校验。所属包会在添加品牌前校验非负安全整数范围等要求。比较、算术、日志、JSON 序列化与协议传输保留普通数字行为；算术会产生未品牌化数字，所属包必须重新准入该数字，才能让它再次进入领域。
+
+### 何时添加品牌
+
+为跨包边界且可能被混淆的值添加品牌——`qilin-llm` 中的 `ToolCallId`、`qilin-session` 中由 agent（智能体）和会话共享的 `SessionId`、`qilin-jobs` 中的 `JobId`，以及 `qilin-session` 中的 `SessionSeq` 与 `SessionLogOffset`。保持局部或无法混淆的值不需要这种抽象。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+该包定义两个交叉类型：`string & { readonly [BRAND]: B }` 与 `number & { readonly [BRAND]: B }`，其中 `BRAND` 是模块私有的 `unique symbol`。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 品牌化字符串与数字类型及其无状态构造函数 |
+
+### 值为何可移植
+
+私有 symbol 在运行时不存在：TypeScript 会将其擦除，因此品牌化值没有标签或 prototype。`brandString()` 与 `brandNumber()` 都原样返回输入。因此，彼此独立安装的副本无需共享注册表或 constructor identity，也会生成可互换的值。
+
+### 为何保持无依赖
+
+把这些 helper 放在独立包中，意味着 `qilin-jobs` 可以为 `JobId` 添加品牌，而无需导入不相关的能力包；每个能力仍然拥有其具体 id 的含义与校验。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当你需要这些原语所品牌化的值或围绕它们的类型约定时，阅读以下页面。
+
+- [核心子系统](../../../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,32 @@
+//#region lib/types/index.js
+/**
+* Duplicate-install-safe nominal primitive helpers.
+*
+* 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 domain value and keeps no runtime identity or mutable
+* state, so independently installed copies produce interchangeable values.
+*
+* @module @qilin-agent/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;
+}
+/**
+* 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 { brandNumber, brandString };

package/lib/types/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Duplicate-install-safe nominal primitive helpers.
+ *
+ * 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 domain value and keeps no runtime identity or mutable
+ * state, so independently installed copies produce interchangeable values.
+ *
+ * @module @qilin-agent/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;
+};
+/** 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,6 +1,38 @@
 {
   "name": "@qilin-agent/brand",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Stateless branded primitive types for the QiLin",
+  "version": "3.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/util/brand"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  }
 }