@deepseek-ai/dsh-attachment 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

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/attachment/attachment/README.md
+README.md: 4f450316294e554396adb9a8454051a08d9befd3
+README.zh.md: fe51b0003cdf1659c7c56106b97c6f3139ebe890

package/README.md

@@ -0,0 +1,21 @@
+# @deepseek-ai/dsh-attachment
+
+English | [中文](README.zh.md)
+
+The durable attachment seam. `ctx.attachments` validates and atomically commits immutable image bytes, then returns a serializable `ImageAttachmentRef`; consumers never persist browser paths, object URLs, provider URLs, or base64 in session events.
+
+Unsent composer images remain browser-owned temporary drafts. `validateImage` runs the same admission policy without persisting; batch writers validate every member first so a malformed member cannot strand earlier members as unreferenced objects. `saveImage` commits each accepted image before any model-visible session event is published, and `readImage` verifies the content-addressed object against its logged metadata.
+
+## Model Experience
+
+Indirectly, through the role-neutral core `ImageBlock` and provider adapters that resolve its durable reference.
+
+#### KV Cache effect
+
+Adding an image changes the provider request and therefore invalidates the affected request suffix.
+
+## Known Limitations and Deferred Work
+
+- Version one accepts PNG, JPEG, WebP, and GIF only.
+- Retention and garbage collection are deferred because resumed and forked sessions may share immutable objects.
+- Generic files, audio, video, and persistent unsent drafts require separate lifecycle and provider contracts.

package/README.zh.md

@@ -0,0 +1,21 @@
+# @deepseek-ai/dsh-attachment
+
+[English](README.md) | 中文
+
+持久附件服务边界。`ctx.attachments` 校验并以原子方式提交不可变图片字节，随后返回可序列化的 `ImageAttachmentRef`；消费方绝不会在会话事件中持久保存浏览器路径、对象 URL、提供方 URL 或 base64。
+
+未发送的输入区图片仍是由浏览器持有的临时草稿。`validateImage` 运行相同的准入策略，但不执行持久化；批量写入方会先校验每个成员，避免某个格式错误的成员使较早的成员成为无引用对象。`saveImage` 会在发布任何模型可见的会话事件前提交每张已接受的图片，`readImage` 则根据已记录的元数据校验内容寻址对象。
+
+## 模型体验
+
+该包通过角色无关的核心 `ImageBlock`，以及解析其持久引用的提供方适配器，间接影响模型。
+
+#### KV 缓存影响
+
+添加图片会改变提供方请求，因此会使受影响的请求后缀失效。
+
+## 已知限制与待完成工作
+
+- 第一版仅接受 PNG、JPEG、WebP 和 GIF。
+- 保留策略与垃圾回收尚未实现，因为恢复和 fork 后的会话可能共享不可变对象。
+- 通用文件、音频、视频和持久的未发送草稿需要单独的生命周期与提供方契约。

package/lib/index.js

@@ -0,0 +1,48 @@
+import { Service } from "@deepseek-ai/cordis";
+//#region lib/types/brand.js
+/** Attachment identifier brand. @module @deepseek-ai/dsh-attachment/brand */
+/**
+* Brand a validated storage identifier.
+* @param value - backend-produced opaque identifier.
+* @returns the branded identifier.
+*/
+function AttachmentId(value) {
+	return value;
+}
+//#endregion
+//#region lib/types/error.js
+/** Attachment failure class. @module @deepseek-ai/dsh-attachment/error */
+/**
+* Stable failures suitable for host RPC error mapping.
+*
+* Deliberately re-implements the `HarnessError` shape instead of extending it:
+* the base lives in `@deepseek-ai/dsh-llm`, which itself depends on this
+* package (`ImageBlock` references `ImageAttachmentRef`), so sharing the base
+* would create a dependency cycle. Consumers route on `code`, never on the
+* prototype chain, so the shapes stay interchangeable at the wire boundary.
+*/
+var AttachmentError = class extends Error {
+	/** Stable machine-routing failure code. */
+	code;
+	/**
+	* @param message - human-readable failure description without raw bytes or host paths.
+	* @param code - stable machine-routing code.
+	* @param options - optional chained cause.
+	*/
+	constructor(message, code, options) {
+		super(message, options);
+		this.name = "AttachmentError";
+		this.code = code;
+	}
+};
+//#endregion
+//#region lib/types/index.js
+/** Durable attachment storage seam (`ctx.attachments`). @module @deepseek-ai/dsh-attachment */
+/** Immutable binary attachment service. Implementations validate bytes before publishing a reference. */
+var AttachmentStore = class extends Service {
+	constructor(ctx) {
+		super(ctx, "attachments");
+	}
+};
+//#endregion
+export { AttachmentError, AttachmentId, AttachmentStore, AttachmentStore as default };

package/lib/invariant.js

@@ -0,0 +1,17 @@
+//#region lib/types/invariant.js
+/** Package-owned invariant companion for `@deepseek-ai/dsh-attachment`. @module @deepseek-ai/dsh-attachment/invariant */
+const PACKAGE_NAME = "@deepseek-ai/dsh-attachment";
+/** Cordis companion plugin name. */
+const name = "attachment-invariant";
+/** Service required before package ownership can be reserved. */
+const inject = ["invariants"];
+/** No runtime invariant: this stateless seam owns types while implementations enforce immutable-store checks. */
+const install = () => {};
+/**
+* Register the package invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the registration disposer.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/brand.d.ts

@@ -0,0 +1,11 @@
+/** Attachment identifier brand. @module @deepseek-ai/dsh-attachment/brand */
+import type { Branded } from '@deepseek-ai/dsh-brand';
+/** Opaque content-addressed identifier for one immutable attachment object. */
+export type AttachmentId = Branded<'AttachmentId'>;
+/**
+ * Brand a validated storage identifier.
+ * @param value - backend-produced opaque identifier.
+ * @returns the branded identifier.
+ */
+export declare function AttachmentId(value: string): AttachmentId;
+//# sourceMappingURL=brand.d.ts.map

package/lib/types/error.d.ts

@@ -0,0 +1,21 @@
+/** Attachment failure class. @module @deepseek-ai/dsh-attachment/error */
+/**
+ * Stable failures suitable for host RPC error mapping.
+ *
+ * Deliberately re-implements the `HarnessError` shape instead of extending it:
+ * the base lives in `@deepseek-ai/dsh-llm`, which itself depends on this
+ * package (`ImageBlock` references `ImageAttachmentRef`), so sharing the base
+ * would create a dependency cycle. Consumers route on `code`, never on the
+ * prototype chain, so the shapes stay interchangeable at the wire boundary.
+ */
+export declare class AttachmentError extends Error {
+    /** Stable machine-routing failure code. */
+    readonly code: string;
+    /**
+     * @param message - human-readable failure description without raw bytes or host paths.
+     * @param code - stable machine-routing code.
+     * @param options - optional chained cause.
+     */
+    constructor(message: string, code: string, options?: ErrorOptions);
+}
+//# sourceMappingURL=error.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,38 @@
+/** Durable attachment storage seam (`ctx.attachments`). @module @deepseek-ai/dsh-attachment */
+import { Context, Service } from '@deepseek-ai/cordis';
+import type { ImageAttachmentLimits, ImageAttachmentRef, SaveImageAttachment, StoredImageAttachment } from './types.ts';
+export { AttachmentId } from './brand.ts';
+export { AttachmentError } from './error.ts';
+export type { AttachmentId as AttachmentIdType, ImageAttachmentLimits, ImageAttachmentRef, ImageMediaType, SaveImageAttachment, StoredImageAttachment, } from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        attachments: AttachmentStore;
+    }
+}
+/** Immutable binary attachment service. Implementations validate bytes before publishing a reference. */
+export declare abstract class AttachmentStore extends Service {
+    constructor(ctx: Context);
+    /** Deployment-resolved image policy used by authoritative and fast-path validation. */
+    abstract readonly imageLimits: ImageAttachmentLimits;
+    /**
+     * Validate one image without persisting it.
+     * Batch callers validate every member before saving any member.
+     * @param input - encoded bytes, declared media type, and optional display name.
+     * @returns completion after the encoded raster has been fully decoded.
+     */
+    abstract validateImage(input: SaveImageAttachment): Promise<void>;
+    /**
+     * Validate and durably commit one image before its owning session event is appended.
+     * @param input - encoded bytes, declared media type, and optional display name.
+     * @returns a durable content-addressed reference.
+     */
+    abstract saveImage(input: SaveImageAttachment): Promise<ImageAttachmentRef>;
+    /**
+     * Read one image and verify that bytes still match the recorded reference.
+     * @param ref - durable reference from the session log.
+     * @returns the verified bytes and canonical reference.
+     */
+    abstract readImage(ref: ImageAttachmentRef): Promise<StoredImageAttachment>;
+}
+export default AttachmentStore;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,13 @@
+/** Package-owned invariant companion for `@deepseek-ai/dsh-attachment`. @module @deepseek-ai/dsh-attachment/invariant */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "attachment-invariant";
+/** Service required before package ownership can be reserved. */
+export declare const inject: string[];
+/**
+ * Register the package invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the registration disposer.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,42 @@
+/** Durable attachment vocabulary. @module @deepseek-ai/dsh-attachment/types */
+import type { AttachmentId } from './brand.ts';
+export type { AttachmentId } from './brand.ts';
+/** Raster image formats accepted by the version-one attachment path. */
+export type ImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';
+/** Durable, serializable metadata for one immutable image object. */
+export interface ImageAttachmentRef {
+    /** Opaque storage identifier; never a filesystem path or bearer URL. */
+    attachmentId: AttachmentId;
+    /** Media type verified from the stored bytes. */
+    mediaType: ImageMediaType;
+    /** Exact encoded byte length. */
+    bytes: number;
+    /** Intrinsic encoded width in pixels. */
+    width: number;
+    /** Intrinsic encoded height in pixels. */
+    height: number;
+    /** Optional display name stripped of local path information. */
+    name?: string;
+}
+/** Deployment-resolved limits used by upload admission and request buffering. */
+export interface ImageAttachmentLimits {
+    maxImageBytes: number;
+    maxImagesPerMessage: number;
+    maxMessageImageBytes: number;
+    maxImagePixels: number;
+    mediaTypes: readonly ImageMediaType[];
+}
+/** Request to validate and durably commit one image. */
+export interface SaveImageAttachment {
+    data: Uint8Array;
+    /** Caller-declared media type, checked against fully decoded bytes. */
+    mediaType: ImageMediaType;
+    /** Optional browser/provider display name; it is never interpreted as a path. */
+    name?: string;
+}
+/** Stored image bytes returned after reference and digest verification. */
+export interface StoredImageAttachment {
+    ref: ImageAttachmentRef;
+    data: Uint8Array;
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@deepseek-ai/dsh-attachment",
+  "description": "Durable immutable attachment storage seam for the DeepSeek Harness",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/attachment/attachment"
+  },
+  "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"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}