@deepseek-ai/dsh-package-manifest 0.1.3-alpha.2

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/package-manifest/README.md
+README.md: 971df84d7db3205eb8be75ba895046d4151780d2
+README.zh.md: 8989cbe9bc29bbf8112d5465eac9806c211fa88d

package/README.md

@@ -0,0 +1,85 @@
+---
+description: "Shared TypeScript declarations for package.json.dsh metadata, usable by boot, client, build, and external packages."
+kind: "package-library"
+---
+
+# @deepseek-ai/dsh-package-manifest
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use `DshManifest` to type a package's Harness metadata, or a member type such as `DshClientManifest` for one declaration. Boot, client, build, and external packages import the same types; each reader owns JSON validation and default resolution.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Import from the package root. Use a development dependency when only checking your own source; use a production dependency if your published declarations reference these types.
+
+```ts
+import type { DshClientManifest, DshManifest } from '@deepseek-ai/dsh-package-manifest'
+
+const client: DshClientManifest = { platform: 'web' }
+const dsh: DshManifest = {
+  bundle: { patch: './cordis.patch.yml' },
+  client,
+}
+```
+
+`DshManifest` describes `bundle`, `profile`, `client`, `configTrees`, `sessionFormatMigration`, and `moduleFallback`, not the surrounding npm manifest. `moduleFallback` is launcher-generated metadata and is not an author configuration entry. TypeScript checks this object and erases `import type` during compilation; JSON files cannot import types, and this example does not write a `package.json`. See [`src/types.ts`](src/types.ts) for the declarations.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The package root only re-exports declarations from [`src/types.ts`](src/types.ts). No runtime invariant companion is published because the package has no runtime state or independently observable relationships.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Profile launcher](../../boot/app-boot/README.md#profiles) — manifest loading and composition.
+- [Declaration ownership](../../../.agents/notes/implemented/architecture/2026-09-05-package-manifest-types.md) — scope and dependency rationale.
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as this package only exports types.
+
+#### KV Cache effect
+
+Type declarations add no model input, so provider cache reuse is unaffected.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Static typing only.** These declarations do not validate JSON, check file existence, or supply defaults. `configTrees` serves the experimental image packer, and `sessionFormatMigration` is discovered only for workspace migration packages; declaring them does not register external plugin behavior.
+
+<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,85 @@
+---
+description: "供启动器、客户端、构建工具和外部包共同使用的 package.json.dsh 元数据 TypeScript 声明。"
+kind: "package-library"
+---
+
+# @deepseek-ai/dsh-package-manifest
+
+[English](README.md) | 中文
+
+## 概述
+
+使用 `DshManifest` 为包的 Harness 元数据添加类型，也可用 `DshClientManifest` 等成员类型描述单项声明。启动器、客户端、构建工具和外部包导入同一组类型；各读取方负责 JSON 校验和默认值解析。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与后续工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+从包根导入类型。仅检查自己的源码时使用开发依赖；若发布的声明文件引用这些类型，则使用生产依赖。
+
+```ts
+import type { DshClientManifest, DshManifest } from '@deepseek-ai/dsh-package-manifest'
+
+const client: DshClientManifest = { platform: 'web' }
+const dsh: DshManifest = {
+  bundle: { patch: './cordis.patch.yml' },
+  client,
+}
+```
+
+`DshManifest` 描述 `bundle`、`profile`、`client`、`configTrees`、`sessionFormatMigration` 和 `moduleFallback`，不包含外层 npm manifest。`moduleFallback` 是启动器生成的元数据，不是作者配置项。TypeScript 检查该对象，并在编译时删除 `import type`；JSON 文件不能导入类型，此示例也不会写入 `package.json`。声明见 [`src/types.ts`](src/types.ts)。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+包根仅重新导出 [`src/types.ts`](src/types.ts) 中的声明。本包不发布运行时不变量伴随模块，因为它没有运行时状态或可独立观察的关系。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+- [Profile 启动器](../../boot/app-boot/README.zh.md#profiles)——manifest 加载与组合。
+- [声明归属](../../../.agents/notes/implemented/architecture/2026-09-05-package-manifest-types.zh.md)——范围与依赖依据。
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，因为本包仅导出类型。
+
+#### KV Cache 影响
+
+类型声明不增加模型输入，因此不影响提供方的缓存复用。
+
+## 已知限制与后续工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **仅提供静态类型。** 这些声明不校验 JSON、不检查文件存在性，也不提供默认值。`configTrees` 服务于实验性镜像打包器，`sessionFormatMigration` 仅从工作区迁移包中发现；声明它们不会注册外部插件行为。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1 @@
+export {};

package/lib/types/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Public package manifest types, with no runtime exports.
+ * @module @deepseek-ai/dsh-package-manifest
+ */
+export type { DshBundleManifest, DshClientManifest, DshConfigTreeDeclaration, DshManifest, DshModuleFallbackManifest, DshProfileManifest, DshSessionFormatMigrationManifest, ProfilePatchReload, } from './types.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Shared declarations for `package.json.dsh`.
+ * Each reader owns JSON validation and resolved defaults.
+ * @module @deepseek-ai/dsh-package-manifest/types
+ */
+/** The `dsh` property of an npm manifest; a package may declare several roles. */
+export interface DshManifest {
+    /** Bundle metadata consumed by the profile launcher. */
+    bundle?: DshBundleManifest;
+    /** Profile metadata consumed by the profile launcher. */
+    profile?: DshProfileManifest;
+    /** Client module loading and build metadata. */
+    client?: DshClientManifest;
+    /** Config directories consumed by the experimental deployment-image packer. */
+    configTrees?: DshConfigTreeDeclaration[];
+    /** Adjacent Session migration metadata consumed by the workspace catalog generator. */
+    sessionFormatMigration?: DshSessionFormatMigrationManifest;
+    /**
+     * Launcher-generated module proxy metadata, not an author configuration entry.
+     * @internal
+     */
+    moduleFallback?: DshModuleFallbackManifest;
+}
+/** The configuration layer exported by a bundle package. */
+export interface DshBundleManifest {
+    /** Patch file path relative to the declaring package root. */
+    patch: string;
+}
+/** The bundle composition declared by a profile directory. */
+export interface DshProfileManifest {
+    /** Ordered bundle layer list, using installed package names. */
+    bundles?: string[];
+    /** User patch lifecycle; omitted means `live` for custom profiles. */
+    patchReload?: ProfilePatchReload;
+}
+/** Whether user patch files reload while a profile remains active or apply only at startup. */
+export type ProfilePatchReload = 'live' | 'startup';
+/** Client module declaration read by client-modules and the client build. */
+export interface DshClientManifest {
+    /** Client platform identifier; the Web consumer selects `web`. */
+    platform: string;
+    /** Informational package-name dependencies, not Cordis service injection. */
+    inject?: string[];
+    /** Boot phase-one registration barrier; absent means the shared application batch. */
+    immediately?: boolean;
+    /**
+     * Exact module-table requests beyond the implicit client baseline, including
+     * subpaths such as `<pkg>/client`; absent means baseline externals only.
+     * Type-only imports are erased and create no module request.
+     */
+    external?: string[];
+}
+/** One config directory read from the CLI package by the experimental image packer. */
+export interface DshConfigTreeDeclaration {
+    /** Non-empty destination path in the image; mount values must be unique. */
+    mount: string;
+    /** Non-empty source directory path relative to the declaring package root. */
+    path: string;
+    /** Include the directory's YAML plugin rows in the package roster; absent means false. */
+    scanRoster?: boolean;
+}
+/**
+ * Adjacent Session migration metadata declared on disk. The catalog generator
+ * discovers only packages/session/session-format-vN-to-vN+1, not external plugins.
+ */
+export interface DshSessionFormatMigrationManifest {
+    /** Non-negative safe integer source version; negative zero is rejected. */
+    from: number;
+    /** Non-negative safe integer target version, exactly from + 1. */
+    to: number;
+    /** Non-empty package export path, such as `.` or `./migration`. */
+    export: string;
+    /** Non-empty named export of the migration implementation. */
+    migration: string;
+    /** Non-empty named export of the source version codec. */
+    sourceCodec: string;
+    /** Non-empty named export of the target version codec. */
+    targetCodec: string;
+    /** Non-empty named export of the target header validator. */
+    targetHeaderValidator: string;
+    /** Non-empty named export of the target version restorer. */
+    targetRestorer: string;
+}
+/**
+ * Metadata generated and read by the launcher's module fallback proxies.
+ * @internal
+ */
+export interface DshModuleFallbackManifest {
+    /** Package export subpaths mapped to resolved target file URLs. */
+    targets: Record<string, string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@deepseek-ai/dsh-package-manifest",
+  "description": "Shared type declarations for package.json.dsh configuration fields",
+  "version": "0.1.3-alpha.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/util/package-manifest"
+  },
+  "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": {
+    "@deepseek-ai/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2"
+  }
+}