Tianyi Cui
8bb8ac8b3c
The background-task change repeated its lifecycle design across implemented RFCs, package READMEs, JSDoc, test commentary, and model-visible schemas. That repetition obscured the contracts that maintainers must preserve and added avoidable prompt tokens. Rewrite the implemented RFCs around the current design, keep authorization, exact-owner cleanup, wait/abort ordering, producer quiescence, and teardown-failure guarantees at their owning surfaces, and remove peer surveys, review history, control-flow narration, and emphatic restatement. Shorten the task and subagent schema wording, synchronize the bilingual tool cookbook, and regenerate the config, service, RFC, tool, and replay snapshot derivatives. Runtime behavior is unchanged; test edits update prose-only assertions and descriptions.
27 lines
1.3 KiB
Markdown
27 lines
1.3 KiB
Markdown
# dsh-brand
|
|
|
|
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: an `AgentId` 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`, `SessionId` in `dsh-session`, `AgentId` in `dsh-agent`, 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`.
|