Package manifest declaration ownership
Package manifest 声明归属
External packages need Harness manifest types without depending on boot or client implementations. Keeping declarations beside individual readers obscures the complete configuration API and lets overlapping fields diverge.
English
Problem
External packages need Harness manifest types without depending on boot or client implementations. Keeping declarations beside individual readers obscures the complete configuration API and lets overlapping fields diverge.
Decision
@deepseek-ai/dsh-package-manifest owns DshManifest and its member declarations in one type-only file. The package belongs to the existing utility group and exports no runtime values. The public package metadata decision owns the public field set and the separation from internal tool metadata.
Readers import the shared declarations directly. Boot retains profile loading, raw JSON checks, defaults, and resolved runtime data. Client modules retain their normalized boot graph. The image packer resolves declared paths into directories. The Session catalog generator derives a read-only validated entry with a resolved import path; raw inputs and discovery rules remain local.
App-boot declares a production dependency because its published declarations reference the shared types. Client modules use a development dependency because their published APIs do not expose these types. Internal image-packer and Session catalog declarations stay with their readers. Every package consumer has a TypeScript project reference. External authors import from the utility package; app-boot provides no compatibility re-exports.
Alternatives considered
Keep declarations in individual readers. External authors would depend on runtime implementations, and a partial profile-only definition would omit existing client and build fields.
Create a separate types group. The existing utility group accommodates a type-only library without another package category. Runtime service and event declarations stay with their owners.
Unify the JSON parsers. Sharing declarations does not require changing validation, errors, defaults, or parsed results; those remain owned by each reader.
Consequences
Authors gain one public import path at the cost of a published package and explicit dependency edges. Existing app-boot manifest type imports must use the new package. The profile composition design continues to own runtime semantics; type extraction does not change configuration acceptance or model-visible behavior.
Compiler and packaged NodeNext consumer checks cover public imports. Existing profile, client, image configuration, and Session catalog tests cover reader behavior; documentation checks cover the utility classification and generated package catalogs. Optional declaration fields still require deliberate consumer updates when added.
Manifest format and host compatibility declarations have no enforcement in current installers or loaders. The type-only package supplies neither a SemVer parser nor an installation policy; its README records that limitation so an author declaration is not mistaken for a compatibility check.
中文
问题
外部包需要 Harness manifest 类型，而无需依赖启动器或客户端实现。将声明放在各读取方旁边，会使完整配置 API 难以查找，也容易让重叠字段发生偏离。
决策
@deepseek-ai/dsh-package-manifest 在一个纯类型文件中拥有 DshManifest 及其成员声明。本包属于现有工具库分组，不导出运行时值。公共包元数据决策 拥有公共字段范围及其与内部工具元数据的划分。
各读取方直接导入共享声明。启动器保留 profile 加载、原始 JSON 检查、默认值和解析后的运行时数据。客户端模块保留归一化的启动图。镜像打包器将声明路径解析为目录。Session 目录生成器派生带有已解析导入路径的只读校验结果；原始输入和发现规则仍由本地负责。
App-boot 声明生产依赖，因为其发布的声明文件引用共享类型。客户端模块使用开发依赖，因为其发布 API 不暴露这些类型。内部镜像打包器和 Session 目录声明保留在各自读取方。每个包消费方都有 TypeScript 项目引用。外部作者从工具包导入；app-boot 不提供兼容性再导出。
考虑过的替代方案
将声明保留在各读取方。 外部作者会依赖运行时实现，而仅覆盖 profile 的部分定义会遗漏已有的客户端和构建字段。
创建独立的 types 分组。 现有工具库分组可以容纳纯类型库，无需增加包分类。运行时服务和事件声明仍由各自负责方拥有。
统一 JSON 解析器。 共享声明不要求改变校验、错误、默认值或解析结果；这些仍由各读取方负责。
后果
作者获得统一的公共导入路径，代价是一个发布包和明确的依赖边。已有的 app-boot manifest 类型导入需要改用新包。Profile 组合设计 继续负责运行时语义；类型提取不改变配置接受范围或模型可见行为。
编译器与打包后的 NodeNext 消费方检查覆盖公共导入。已有 profile、客户端、镜像配置和 Session 目录测试覆盖读取行为；文档检查覆盖工具库分类与生成的包目录。新增可选声明字段时，仍需主动更新消费方。
当前安装器和加载器不强制检查 manifest 格式或宿主兼容性声明。纯类型包既不提供 SemVer 解析器，也不提供安装策略；其 README 记录此限制，避免将作者声明误认为兼容性检查。