@deepseek-ai/dsh-attachment 0.1.0-rc.3 → 0.1.0-rc.7

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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: baeeca0cf939f1a3d4608769b362d532507b90f5
-README.zh.md: 238b90794c510e71fffe34d62b044a5c2ece8a6e
+README.md: 4fe608552492c33d2bd9acddce51ea1cf20acae4
+README.zh.md: a3093fc9dd1f926cb1c54831c6302eb7bbca25c5

package/README.md

@@ -2,9 +2,9 @@
 
 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.
+The durable attachment seam. `ctx.attachments` validates and durably 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. Callers may cancel `readImage`; implementations observe cancellation around backend and verification work and preserve it instead of translating it into a storage failure.
+Unsent composer images remain browser-owned temporary drafts. `validateImage` runs the same admission policy without persisting. `saveImages` owns batch count and aggregate-byte limits, validates every member before writing any member, then commits in order and returns references only after the complete batch succeeds. A later storage failure returns no partial references, although an earlier immutable content-addressed object may remain unreachable until reference-aware garbage collection exists. `AttachmentError.code` uses the closed `AttachmentErrorCode` string union. Its `ImageAdmissionErrorCode` subset marks caller-correctable image-input failures; `isImageAdmissionError` recognizes that subset at runtime so each protocol adapter can map its own error vocabulary. `saveImage` commits one accepted image before any model-visible session event is published, and `readImage` verifies the content-addressed object against its logged metadata. Callers may cancel `readImage`; implementations observe cancellation around backend and verification work and preserve it instead of translating it into a storage failure.
 
 ## Model Experience
 

package/README.zh.md

@@ -2,9 +2,9 @@
 
 [English](README.md) | 中文
 
-持久附件服务边界。`ctx.attachments` 校验并以原子方式提交不可变图片字节，随后返回可序列化的 `ImageAttachmentRef`；消费方绝不会在会话事件中持久保存浏览器路径、对象 URL、提供方 URL 或 base64。
+持久附件服务边界。`ctx.attachments` 校验并持久提交不可变图片字节，随后返回可序列化的 `ImageAttachmentRef`；消费方绝不会在会话事件中持久保存浏览器路径、对象 URL、提供方 URL 或 base64。
 
-未发送的输入区图片仍是由浏览器持有的临时草稿。`validateImage` 运行相同的准入策略，但不执行持久化；批量写入方会先校验每个成员，避免某个格式错误的成员使较早的成员成为无引用对象。`saveImage` 会在发布任何模型可见的会话事件前提交每张已接受的图片，`readImage` 则根据已记录的元数据校验内容寻址对象。调用方可以取消 `readImage`；实现会在后端读取与校验工作的边界观察取消，并保留取消语义，而不会将其转换为存储失败。
+未发送的输入区图片仍是由浏览器持有的临时草稿。`validateImage` 运行相同的准入策略，但不执行持久化。`saveImages` 负责批次图片数量和总字节限制，先校验全部成员，再按顺序提交，并且只在完整批次成功后返回引用。后续存储失败不会返回部分引用，但较早写入的不可变内容寻址对象可能保持不可达，直至具备按引用感知的垃圾回收。`AttachmentError.code` 使用封闭的 `AttachmentErrorCode` 字符串联合类型。其 `ImageAdmissionErrorCode` 子集标记可由调用方修正的图片输入失败；`isImageAdmissionError` 在运行时识别该子集，使每个协议适配器可以映射自己的错误词汇。`saveImage` 会在发布任何模型可见的会话事件前提交一张已接受的图片，`readImage` 则根据已记录的元数据校验内容寻址对象。调用方可以取消 `readImage`；实现会在后端读取与校验工作的边界观察取消，并保留取消语义，而不会将其转换为存储失败。
 
 ## 模型体验
 

package/lib/index.js

@@ -1,17 +1,16 @@
 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 */
+/** Runtime membership for structurally compatible errors crossing package boundaries. */
+const IMAGE_ADMISSION_ERROR_CODE_SET = new Set([
+	"TOO_MANY_IMAGES",
+	"IMAGES_TOO_LARGE",
+	"UNSUPPORTED_IMAGE_TYPE",
+	"INVALID_IMAGE_BASE64",
+	"INVALID_IMAGE",
+	"IMAGE_TYPE_MISMATCH",
+	"IMAGE_TOO_LARGE",
+	"IMAGE_TOO_MANY_PIXELS"
+]);
 /**
 * Stable failures suitable for host RPC error mapping.
 *
@@ -35,6 +34,25 @@ var AttachmentError = class extends Error {
 		this.code = code;
 	}
 };
+/**
+* Distinguish caller-correctable image admission failures from storage faults.
+* @param error - failure raised while validating or persisting an image batch.
+* @returns whether the caller can correct the proposed image content or batch.
+*/
+function isImageAdmissionError(error) {
+	return error instanceof Error && "code" in error && typeof error.code === "string" && IMAGE_ADMISSION_ERROR_CODE_SET.has(error.code);
+}
+//#endregion
+//#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/index.js
 /** Durable attachment storage seam (`ctx.attachments`). @module @deepseek-ai/dsh-attachment */
@@ -43,6 +61,24 @@ var AttachmentStore = class extends Service {
 	constructor(ctx) {
 		super(ctx, "attachments");
 	}
+	/**
+	* Validate one ordered image batch before committing any member.
+	* Validation failures start no writes; storage failures return no partial
+	* references, although already published content-addressed objects may stay
+	* unreachable until a future retention policy collects them.
+	* @param inputs - encoded images in their owning message order.
+	* @returns durable references in the exact input order.
+	*/
+	async saveImages(inputs) {
+		const { maxImagesPerMessage, maxMessageImageBytes, mediaTypes } = this.imageLimits;
+		if (inputs.length > maxImagesPerMessage) throw new AttachmentError("Image batch exceeds the configured image-count limit.", "TOO_MANY_IMAGES");
+		if (inputs.reduce((sum, input) => sum + input.data.byteLength, 0) > maxMessageImageBytes) throw new AttachmentError("Image batch exceeds the configured aggregate image-byte limit.", "IMAGES_TOO_LARGE");
+		for (const input of inputs) if (!mediaTypes.includes(input.mediaType)) throw new AttachmentError(`Image type ${input.mediaType} is not accepted by this deployment.`, "UNSUPPORTED_IMAGE_TYPE");
+		for (const input of inputs) await this.validateImage(input);
+		const refs = [];
+		for (const input of inputs) refs.push(await this.saveImage(input));
+		return refs;
+	}
 };
 //#endregion
-export { AttachmentError, AttachmentId, AttachmentStore, AttachmentStore as default };
+export { AttachmentError, AttachmentId, AttachmentStore, AttachmentStore as default, isImageAdmissionError };

package/lib/types/error.d.ts

@@ -1,4 +1,9 @@
 /** Attachment failure class. @module @deepseek-ai/dsh-attachment/error */
+declare const IMAGE_ADMISSION_ERROR_CODES: readonly ["TOO_MANY_IMAGES", "IMAGES_TOO_LARGE", "UNSUPPORTED_IMAGE_TYPE", "INVALID_IMAGE_BASE64", "INVALID_IMAGE", "IMAGE_TYPE_MISMATCH", "IMAGE_TOO_LARGE", "IMAGE_TOO_MANY_PIXELS"];
+/** Caller-correctable attachment failure codes raised while admitting image input. */
+export type ImageAdmissionErrorCode = typeof IMAGE_ADMISSION_ERROR_CODES[number];
+/** Stable attachment failure codes used for protocol error routing. */
+export type AttachmentErrorCode = ImageAdmissionErrorCode | 'INVALID_ATTACHMENT_REF' | 'ATTACHMENT_CORRUPT' | 'ATTACHMENT_WRITE_FAILED' | 'ATTACHMENT_NOT_FOUND' | 'ATTACHMENT_READ_FAILED';
 /**
  * Stable failures suitable for host RPC error mapping.
  *
@@ -10,12 +15,21 @@
  */
 export declare class AttachmentError extends Error {
     /** Stable machine-routing failure code. */
-    readonly code: string;
+    readonly code: AttachmentErrorCode;
     /**
      * @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);
+    constructor(message: string, code: AttachmentErrorCode, options?: ErrorOptions);
 }
+/**
+ * Distinguish caller-correctable image admission failures from storage faults.
+ * @param error - failure raised while validating or persisting an image batch.
+ * @returns whether the caller can correct the proposed image content or batch.
+ */
+export declare function isImageAdmissionError(error: unknown): error is AttachmentError & {
+    readonly code: ImageAdmissionErrorCode;
+};
+export {};
 //# sourceMappingURL=error.d.ts.map

package/lib/types/index.d.ts

@@ -2,7 +2,8 @@
 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 { AttachmentError, isImageAdmissionError } from './error.ts';
+export type { AttachmentErrorCode, ImageAdmissionErrorCode } from './error.ts';
 export type { AttachmentId as AttachmentIdType, ImageAttachmentLimits, ImageAttachmentRef, ImageMediaType, SaveImageAttachment, StoredImageAttachment, } from './types.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
@@ -21,6 +22,15 @@ export declare abstract class AttachmentStore extends Service {
      * @returns completion after the encoded raster has been fully decoded.
      */
     abstract validateImage(input: SaveImageAttachment): Promise<void>;
+    /**
+     * Validate one ordered image batch before committing any member.
+     * Validation failures start no writes; storage failures return no partial
+     * references, although already published content-addressed objects may stay
+     * unreachable until a future retention policy collects them.
+     * @param inputs - encoded images in their owning message order.
+     * @returns durable references in the exact input order.
+     */
+    saveImages(inputs: readonly SaveImageAttachment[]): Promise<readonly ImageAttachmentRef[]>;
     /**
      * Validate and durably commit one image before its owning session event is appended.
      * @param input - encoded bytes, declared media type, and optional display name.

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@deepseek-ai/dsh-attachment",
   "description": "Durable immutable attachment storage seam for the DeepSeek Harness",
-  "version": "0.1.0-rc.3",
+  "version": "0.1.0-rc.7",
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
   "repository": {
     "type": "git",
@@ -32,13 +32,13 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-brand": "^0.1.0-rc.3",
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.3",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-brand": "^0.1.0-rc.7",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.7"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-brand": "^0.1.0-rc.3",
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.3",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.7",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-brand": "^0.1.0-rc.7"
   }
 }