@deepseek-ai/dsh-attachment 0.1.1-rc.1 → 0.1.1-rc.2

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: 19232bd4bb86ed33e56fcdca93999967822422ab
-README.zh.md: e5e7aab7c1af30b2b101bdcd218044cd1095ae0d
+README.md: 3ad568c7308f1ab85cb4af3fcc2afd3cba9a611a
+README.zh.md: fadbb1c5bbf097c599da651055d63a1ed64cd579

package/README.md

@@ -2,15 +2,15 @@
 
 English | [中文](README.zh.md)
 
-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.
+The durable attachment seam. `ctx.attachments` validates and durably commits a provider-independent normalized image, 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. `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.
+Unsent composer images remain browser-owned temporary drafts. `validateImage` runs the complete admission policy without persisting. `saveImages` owns batch count and aggregate-byte limits, prepares every normalized attachment before publishing 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 returns its `ImageAttachmentRef`. When normalization reduces the raster, the reference records the orientation-applied input size in `originalDimensions`. `readImage` verifies the normalized attachment against its logged metadata. `readImageRequest` deterministically derives a route-sized request version whose identity covers the attachment id, transform version, pixel and byte budgets, and encoder settings. Callers compose ordered batches with `Promise.all(refs.map(...))`; the local implementation still bounds compression through its instance limiter, cache, and singleflight. Callers may cancel reads and projections; implementations preserve cancellation instead of translating it into a storage failure.
 
 `admitEncodedImages(attachments, images)` is the shared wire entry used by every RPC endpoint that accepts browser uploads (the session prompt endpoint and the command executor): it enforces canonical base64 on every member, then delegates batch admission — limits, validation, ordered commit — to `saveImages`. The base64 upload form is `EncodedImageAttachment`, exported from `@deepseek-ai/dsh-attachment/types` so wire contracts can reference it.
 
 ## Model Experience
 
-Indirectly, through the role-neutral core `ImageBlock` and provider adapters that resolve its durable reference.
+Indirectly, through the role-neutral core `ImageBlock` and provider adapters that resolve its durable reference into an exact request version. Request descriptors expose the complete attachment id and actual request dimensions.
 
 #### KV Cache effect
 

package/README.zh.md

@@ -2,15 +2,15 @@
 
 [English](README.md) | 中文
 
-持久附件服务边界。`ctx.attachments` 校验并持久提交不可变图片字节，随后返回可序列化的 `ImageAttachmentRef`；消费方绝不会在会话事件中持久保存浏览器路径、对象 URL、提供方 URL 或 base64。
+持久附件服务边界。`ctx.attachments` 校验并持久提交提供方无关的规范化图片，随后返回可序列化的 `ImageAttachmentRef`；消费方绝不会在会话事件中持久保存浏览器路径、对象 URL、提供方 URL 或 base64。
 
-未发送的输入区图片仍是由浏览器持有的临时草稿。`validateImage` 运行相同的准入策略，但不执行持久化。`saveImages` 负责批次图片数量和总字节限制，先校验全部成员，再按顺序提交，并且只在完整批次成功后返回引用。后续存储失败不会返回部分引用，但较早写入的不可变内容寻址对象可能保持不可达，直至具备按引用感知的垃圾回收。`AttachmentError.code` 使用封闭的 `AttachmentErrorCode` 字符串联合类型。其 `ImageAdmissionErrorCode` 子集标记可由调用方修正的图片输入失败；`isImageAdmissionError` 在运行时识别该子集，使每个协议适配器可以映射自己的错误词汇。`saveImage` 会在发布任何模型可见的会话事件前提交一张已接受的图片，`readImage` 则根据已记录的元数据校验内容寻址对象。调用方可以取消 `readImage`；实现会在后端读取与校验工作的边界观察取消，并保留取消语义，而不会将其转换为存储失败。
+未发送的输入区图片仍是由浏览器持有的临时草稿。`validateImage` 运行完整准入策略但不执行持久化。`saveImages` 负责批次图片数量和总字节限制，在发布任何成员前准备全部规范化附件，然后按顺序提交，并且只在完整批次成功后返回引用。后续存储失败不会返回部分引用，但较早写入的不可变内容寻址对象可能保持不可达，直至具备按引用感知的垃圾回收。`AttachmentError.code` 使用封闭的 `AttachmentErrorCode` 字符串联合类型。其 `ImageAdmissionErrorCode` 子集标记可由调用方修正的图片输入失败；`isImageAdmissionError` 在运行时识别该子集，使每个协议适配器可以映射自己的错误词汇。`saveImage` 会在发布任何模型可见的会话事件前提交一张已接受的图片，并直接返回 `ImageAttachmentRef`。规范化过程缩小图片时，引用会通过 `originalDimensions` 记录应用方向后的输入尺寸。`readImage` 根据已记录的元数据校验规范化附件。`readImageRequest` 确定性派生路由所需的请求版本，其身份覆盖附件 ID、变换策略版本、像素和字节预算及编码参数。调用方通过 `Promise.all(refs.map(...))` 组合有序批次，本地实现仍通过实例级限流器、缓存和 singleflight 限制压缩并发。调用方可以取消读取和投影；实现保留取消结果，不把它转换为存储失败。
 
 `admitEncodedImages(attachments, images)` 是每个接受浏览器上传的 RPC 端点（会话 prompt 端点与命令执行器）共用的 wire 入口：它对每个成员强制执行规范 base64，随后把批量准入——限额、校验、有序提交——委托给 `saveImages`。base64 上传形式为 `EncodedImageAttachment`，从 `@deepseek-ai/dsh-attachment/types` 导出，供 wire 契约引用。
 
 ## 模型体验
 
-该包通过角色无关的核心 `ImageBlock`，以及解析其持久引用的提供方适配器，间接影响模型。
+该包通过角色无关的核心 `ImageBlock`，以及把持久引用解析为确定请求版本的提供方适配器，间接影响模型。请求描述会公开完整附件 ID 和实际请求尺寸。
 
 #### KV 缓存影响
 

package/lib/index.js

@@ -55,6 +55,14 @@ function isImageAdmissionError(error) {
 function AttachmentId(value) {
 	return value;
 }
+/**
+* Brand a validated request-image transformation identifier.
+* @param value - attachment-provider-produced opaque identifier.
+* @returns the branded identifier.
+*/
+function ImageVariantId(value) {
+	return value;
+}
 //#endregion
 //#region lib/types/admission.js
 /** Wire-form admission of base64-encoded image uploads. @module @deepseek-ai/dsh-attachment/admission */
@@ -101,16 +109,35 @@ var AttachmentStore = class extends Service {
 	* @param inputs - encoded images in their owning message order.
 	* @returns durable references in the exact input order.
 	*/
-	async saveImages(inputs) {
+	validateImageBatch(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");
+	}
+	/**
+	* Validate and durably commit one ordered image batch.
+	* @param inputs - encoded images in owning-message order.
+	* @returns durable normalized attachment references in the same order after every member succeeds.
+	*/
+	async saveImages(inputs) {
+		this.validateImageBatch(inputs);
 		for (const input of inputs) await this.validateImage(input);
 		const refs = [];
 		for (const input of inputs) refs.push(await this.saveImage(input));
 		return refs;
 	}
+	/**
+	* Generate or read one deterministic model-request version from the stored normalized image.
+	* @param ref - durable provider-independent normalized attachment reference.
+	* @param policy - exact route pixel and encoded-byte budget.
+	* @param signal - optional cancellation.
+	* @returns request bytes and the cache/upload identity covering every transform input.
+	*/
+	readImageRequest(ref, policy, signal) {
+		signal?.throwIfAborted();
+		return Promise.reject(new AttachmentError("The mounted attachment provider cannot derive model-request images.", "ATTACHMENT_PROJECTION_UNSUPPORTED"));
+	}
 };
 //#endregion
-export { AttachmentError, AttachmentId, AttachmentStore, AttachmentStore as default, admitEncodedImages, isImageAdmissionError };
+export { AttachmentError, AttachmentId, AttachmentStore, AttachmentStore as default, ImageVariantId, admitEncodedImages, isImageAdmissionError };

package/lib/types/brand.d.ts

@@ -8,4 +8,12 @@ export type AttachmentId = Branded<'AttachmentId'>;
  * @returns the branded identifier.
  */
 export declare function AttachmentId(value: string): AttachmentId;
+/** Opaque deterministic identity for one request-image transformation. */
+export type ImageVariantId = Branded<'ImageVariantId'>;
+/**
+ * Brand a validated request-image transformation identifier.
+ * @param value - attachment-provider-produced opaque identifier.
+ * @returns the branded identifier.
+ */
+export declare function ImageVariantId(value: string): ImageVariantId;
 //# sourceMappingURL=brand.d.ts.map

package/lib/types/brand.js

@@ -7,4 +7,12 @@
 export function AttachmentId(value) {
     return value;
 }
+/**
+ * Brand a validated request-image transformation identifier.
+ * @param value - attachment-provider-produced opaque identifier.
+ * @returns the branded identifier.
+ */
+export function ImageVariantId(value) {
+    return value;
+}
 //# sourceMappingURL=brand.js.map

package/lib/types/error.d.ts

@@ -3,7 +3,7 @@ declare const IMAGE_ADMISSION_ERROR_CODES: readonly ["TOO_MANY_IMAGES", "IMAGES_
 /** 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';
+export type AttachmentErrorCode = ImageAdmissionErrorCode | 'INVALID_ATTACHMENT_REF' | 'ATTACHMENT_CORRUPT' | 'ATTACHMENT_WRITE_FAILED' | 'ATTACHMENT_NOT_FOUND' | 'ATTACHMENT_READ_FAILED' | 'ATTACHMENT_PROJECTION_UNSUPPORTED';
 /**
  * Stable failures suitable for host RPC error mapping.
  *

package/lib/types/index.d.ts

@@ -1,11 +1,11 @@
 /** 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';
+import type { ImageAttachmentLimits, ImageAttachmentRef, ImageRequestPolicy, RequestImageAttachment, SaveImageAttachment, StoredImageAttachment } from './types.ts';
+export { AttachmentId, ImageVariantId } from './brand.ts';
 export { AttachmentError, isImageAdmissionError } from './error.ts';
 export type { AttachmentErrorCode, ImageAdmissionErrorCode } from './error.ts';
 export { admitEncodedImages } from './admission.ts';
-export type { AttachmentId as AttachmentIdType, EncodedImageAttachment, ImageAttachmentLimits, ImageAttachmentRef, ImageMediaType, SaveImageAttachment, StoredImageAttachment, } from './types.ts';
+export type { AttachmentId as AttachmentIdType, EncodedImageAttachment, ImageAttachmentLimits, ImageAttachmentRef, ImageRequestPolicy, ImageMediaType, RequestImageAttachment, SaveImageAttachment, StoredImageAttachment, } from './types.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         attachments: AttachmentStore;
@@ -31,21 +31,38 @@ export declare abstract class AttachmentStore extends Service {
      * @param inputs - encoded images in their owning message order.
      * @returns durable references in the exact input order.
      */
+    protected validateImageBatch(inputs: readonly SaveImageAttachment[]): void;
+    /**
+     * Validate and durably commit one ordered image batch.
+     * @param inputs - encoded images in owning-message order.
+     * @returns durable normalized attachment references in the same order after every member succeeds.
+     */
     saveImages(inputs: readonly SaveImageAttachment[]): Promise<readonly ImageAttachmentRef[]>;
     /**
      * Validate and durably commit one image before its owning session event is appended.
+     * The returned reference describes the persisted normalized image. When
+     * normalization reduces the raster, its `originalDimensions` records the
+     * orientation-applied input dimensions.
      * @param input - encoded bytes, declared media type, and optional display name.
-     * @returns a durable content-addressed reference.
+     * @returns the durable content-addressed normalized image 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.
      * @param signal - optional cancellation for backend read and verification work.
-     * @returns the verified bytes and canonical reference.
+     * @returns the verified bytes and normalized attachment reference.
      * @throws the signal reason when aborted, or a storage error when verification fails.
      */
     abstract readImage(ref: ImageAttachmentRef, signal?: AbortSignal): Promise<StoredImageAttachment>;
+    /**
+     * Generate or read one deterministic model-request version from the stored normalized image.
+     * @param ref - durable provider-independent normalized attachment reference.
+     * @param policy - exact route pixel and encoded-byte budget.
+     * @param signal - optional cancellation.
+     * @returns request bytes and the cache/upload identity covering every transform input.
+     */
+    readImageRequest(ref: ImageAttachmentRef, policy: ImageRequestPolicy, signal?: AbortSignal): Promise<RequestImageAttachment>;
 }
 export default AttachmentStore;
 //# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -1,7 +1,7 @@
 /** Durable attachment storage seam (`ctx.attachments`). @module @deepseek-ai/dsh-attachment */
 import { Service } from '@deepseek-ai/cordis';
 import { AttachmentError } from "./error.js";
-export { AttachmentId } from "./brand.js";
+export { AttachmentId, ImageVariantId } from "./brand.js";
 export { AttachmentError, isImageAdmissionError } from "./error.js";
 export { admitEncodedImages } from "./admission.js";
 /** Immutable binary attachment service. Implementations validate bytes before publishing a reference. */
@@ -17,7 +17,7 @@ export class AttachmentStore extends Service {
      * @param inputs - encoded images in their owning message order.
      * @returns durable references in the exact input order.
      */
-    async saveImages(inputs) {
+    validateImageBatch(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');
@@ -31,6 +31,14 @@ export class AttachmentStore extends Service {
                 throw new AttachmentError(`Image type ${input.mediaType} is not accepted by this deployment.`, 'UNSUPPORTED_IMAGE_TYPE');
             }
         }
+    }
+    /**
+     * Validate and durably commit one ordered image batch.
+     * @param inputs - encoded images in owning-message order.
+     * @returns durable normalized attachment references in the same order after every member succeeds.
+     */
+    async saveImages(inputs) {
+        this.validateImageBatch(inputs);
         for (const input of inputs)
             await this.validateImage(input);
         const refs = [];
@@ -38,6 +46,19 @@ export class AttachmentStore extends Service {
             refs.push(await this.saveImage(input));
         return refs;
     }
+    /**
+     * Generate or read one deterministic model-request version from the stored normalized image.
+     * @param ref - durable provider-independent normalized attachment reference.
+     * @param policy - exact route pixel and encoded-byte budget.
+     * @param signal - optional cancellation.
+     * @returns request bytes and the cache/upload identity covering every transform input.
+     */
+    readImageRequest(ref, policy, signal) {
+        signal?.throwIfAborted();
+        void ref;
+        void policy;
+        return Promise.reject(new AttachmentError('The mounted attachment provider cannot derive model-request images.', 'ATTACHMENT_PROJECTION_UNSUPPORTED'));
+    }
 }
 export default AttachmentStore;
 //# sourceMappingURL=index.js.map

package/lib/types/types.d.ts

@@ -1,9 +1,9 @@
 /** Durable attachment vocabulary. @module @deepseek-ai/dsh-attachment/types */
-import type { AttachmentId } from './brand.ts';
+import type { AttachmentId, ImageVariantId } 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. */
+/** Durable, serializable reference to one immutable normalized image. */
 export interface ImageAttachmentRef {
     /** Opaque storage identifier; never a filesystem path or bearer URL. */
     attachmentId: AttachmentId;
@@ -17,6 +17,14 @@ export interface ImageAttachmentRef {
     height: number;
     /** Optional display name stripped of local path information. */
     name?: string;
+    /**
+     * Input dimensions after applying EXIF orientation and before normalization
+     * scaling. Present only when normalization reduced the image.
+     */
+    originalDimensions?: {
+        width: number;
+        height: number;
+    };
 }
 /** Deployment-resolved limits used by upload admission and request buffering. */
 export interface ImageAttachmentLimits {
@@ -50,4 +58,30 @@ export interface StoredImageAttachment {
     ref: ImageAttachmentRef;
     data: Uint8Array;
 }
+/** Deterministic request-image policy selected by one exact model route. */
+export interface ImageRequestPolicy {
+    /** Maximum width multiplied by height after aspect-preserving projection. */
+    maxPixels: number;
+    /** Encoded-byte cap before base64 expansion or Files API upload. */
+    maxBytes: number;
+}
+/** Cached request version derived from one provider-independent normalized attachment. */
+export interface RequestImageAttachment {
+    /** Cache and upload-index key over the attachment id, policy, and fixed encoder parameters. */
+    variantId: ImageVariantId;
+    /** Durable normalized attachment from which this request version was derived. */
+    attachment: ImageAttachmentRef;
+    /** Encoded request bytes. */
+    data: Uint8Array;
+    mediaType: ImageMediaType;
+    bytes: number;
+    width: number;
+    height: number;
+    /** Provider-compatible sample depth proven after request encoding. */
+    depth: 'uchar';
+    /** Provider-compatible color space proven after request encoding. */
+    space: 'srgb';
+    /** Whether the encoded request version retains an alpha channel. */
+    hasAlpha: boolean;
+}
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-attachment",
   "description": "Durable immutable attachment storage seam for the DeepSeek Harness",
-  "version": "0.1.1-rc.1",
+  "version": "0.1.1-rc.2",
   "publishConfig": {
     "access": "public"
   },
@@ -37,13 +37,13 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-brand": "^0.1.1-rc.1",
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.1"
+    "@deepseek-ai/dsh-brand": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-brand": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-brand": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
     "@deepseek-ai/cordis": "^4.0.1"
   }
 }