@deepseek-ai/dsh-attachment 0.1.5-rc.1 → 0.1.6-alpha.1

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: fc3903cb1ab4ed4a1249ad2ec62c0df633f4a7c4
-README.zh.md: 9e84a5ed8889d541b3cb87fb5e5d5560d36a2bb5
+README.md: d2a667e2d12deadc5e82a83cca6565f0b5a6aae0
+README.zh.md: b5598eb8ccca39d8b5be346c585fd84d3dd38468

package/README.md

@@ -66,13 +66,13 @@ This section explains the design decisions behind the seam and the service opera
 - **Normalize and persist before event.** Every source is prepared and verified before the batch publishes in order, so the session log never references a partial or failed normalization.
 - **Immutable and retention-neutral.** Objects are immutable once published; resumed and forked sessions may share them, so reference-aware garbage collection is deferred rather than tied to any one session's deletion.
 - **Verify on read.** Reads check bytes and metadata against the logged reference before returning them, and request projections fully decode cached bytes, so a missing, corrupted, or swapped object fails closed.
-- **Role-neutral image blocks.** The `ImageBlock` content block in `dsh-llm` carries an `ImageAttachmentRef`; provider adapters resolve it into deterministic request versions with explicit pixel and byte budgets, while execution filesystems may map the immutable host object to a model-readable process path.
+- **Role-neutral image blocks.** The `ImageBlock` content block in `dsh-llm` carries an `ImageAttachmentRef`; provider adapters resolve it into deterministic request versions at an explicit route-chosen target size and byte target, while execution filesystems may map the immutable host object to a model-readable process path.
 - **Error routing by code.** `AttachmentError` re-implements the `HarnessError` shape instead of extending it because the base lives in `dsh-llm`, which depends on this package; consumers use `isAttachmentError` and route on `code`, never on the prototype chain.
 - **Files are verbatim, images are normalized.** `saveFile` commits an existing byte array, `saveFileStream` commits bounded chunks with backpressure and cancellation, `readFileStream` verifies and returns bounded chunks, and `fileHostPath` locates the stored object for read-on-demand projection; neither file write path applies admission limits. The image path keeps its separate normalization, limits, and request-version pipeline. The `FileBlock` content block in `dsh-llm` carries a `FileAttachmentRef`, and request assembly projects it to deterministic handle text for every route.
 
 ### Service operations
 
-The service family runs one admission-and-storage flow: every entry point enforces source batch limits and canonical base64, prepares provider-independent normalized attachments before publishing any member, and commits them durably in input order without partial results. Host prompt consumers pass ordered text, encoded images, and already resolved file references to `ctx.attachments.admitPromptContent()`; the method persists images and passes file references unchanged. Encoded protocol adapters call `ctx.attachments.admitEncodedFile()`, which checks canonical base64 before delegating to `saveFile`; adapters recognize attachment failures through `ctx.attachments.isAttachmentError()`. Generic-file callers choose `saveFile` for existing bytes or `saveFileStream` for a bounded asynchronous byte source; both return the same durable reference, while `readFileStream` verifies its digest and length during a bounded read. `readImageRequest` derives deterministic route-sized variants whose identity includes the attachment id, transform version, pixel and byte budgets, and encoder settings. The pure `requestImageDimensions` export computes each projection's aspect-preserving dimensions from a total-pixel budget, so providers and request pricing share one geometry. `imageHostPath` exposes an implementation-owned host location only to trusted same-process consumers that need execution-world mapping. Callers compose ordered batches while the implementation owns compression concurrency, caching, and singleflight. Reads, streamed writes, and projections preserve caller cancellation. Failures carry stable machine-readable codes, and the caller-correctable admission subset is recognizable at runtime so each protocol adapter maps its own vocabulary; the exact per-operation contracts live in [`src/index.ts`](src/index.ts) and [`src/error.ts`](src/error.ts).
+The service family runs one admission-and-storage flow: every entry point enforces source batch limits and canonical base64, prepares provider-independent normalized attachments before publishing any member, and commits them durably in input order without partial results. Host prompt consumers pass ordered text, encoded images, and already resolved file references to `ctx.attachments.admitPromptContent()`; the method persists images and passes file references unchanged. Encoded protocol adapters call `ctx.attachments.admitEncodedFile()`, which checks canonical base64 before delegating to `saveFile`; adapters recognize attachment failures through `ctx.attachments.isAttachmentError()`. Generic-file callers choose `saveFile` for existing bytes or `saveFileStream` for a bounded asynchronous byte source; both return the same durable reference, while `readFileStream` verifies its digest and length during a bounded read. `readImageRequest` derives deterministic route-sized variants whose identity includes the attachment id, transform version, target dimensions, byte target, and encoder settings. The pure `requestImageDimensions` and `longEdgeDimensions` exports compute aspect-preserving dimensions from a total-pixel budget or an exact long edge, so routes and request pricing share one geometry. `imageHostPath` exposes an implementation-owned host location only to trusted same-process consumers that need execution-world mapping. Callers compose ordered batches while the implementation owns compression concurrency, caching, and singleflight. Reads, streamed writes, and projections preserve caller cancellation. Failures carry stable machine-readable codes, and the caller-correctable admission subset is recognizable at runtime so each protocol adapter maps its own vocabulary; the exact per-operation contracts live in [`src/index.ts`](src/index.ts) and [`src/error.ts`](src/error.ts).
 
 ### Source map
 
@@ -94,7 +94,7 @@ The service family runs one admission-and-storage flow: every entry point enforc
 
 For the full service contract and payload types, read the subsystem reference; for the storage that backs this capability, read the local backend.
 
-- [Attachment subsystem reference](../../../docs/subsystems/attachment.md) — service contract, payload types, and the `ctx.attachments` cordis surface.
+- [Attachment subsystem reference](../../../docs/subsystems/attachment.md) — service contract, payload types, and the `ctx.attachments` Cordis surface.
 - [Local filesystem backend](../attachment-local/README.md) — where your attached images are stored on this machine.
 - [Capability seams](../../../docs/capability-seams.md) — how this capability family is split into roles.
 
@@ -114,7 +114,7 @@ Adding an image changes the provider request and therefore invalidates the affec
 <a id="known-limitations-and-deferred-work"></a>
 
 
-These limits describe what image attachments can and cannot do; they are current package constraints, not a task backlog.
+These limits describe what attachments can and cannot do; they are current package constraints, not a task backlog.
 
 - **Raster image limits apply to images only** — PNG, JPEG, WebP, and GIF are accepted as images under deployment limits; every other file is stored verbatim with no type or size limit, and audio and video have no dedicated handling yet.
 - **Attachments are never deleted** — stored images and files are retained indefinitely; nothing removes them automatically.

package/README.zh.md

@@ -41,7 +41,7 @@ kind: "package-reference"
 
 ### 把附件传给命令
 
-声明接受附件的命令会按选择顺序接收图片与通用文件。不接受附件的命令会返回错误，并保留 composer 的草稿与附件卡。
+声明接受附件的命令会按选择顺序接收图片与通用文件。不接受附件的命令会返回错误，并保留输入区的草稿与附件卡。
 
 ### 在整个会话中复用图片
 
@@ -65,14 +65,14 @@ kind: "package-reference"
 
 - **事件前完成规范化与持久化。** 每个源图都会在批次按序发布前完成准备与校验，因此会话日志绝不会引用部分完成或规范化失败的对象。
 - **不可变且保留策略中立。** 对象一经发布即不可变；恢复和 fork 后的会话可能共享它们，因此引用感知的垃圾回收被推迟，而不是与任何单个会话的删除绑定。
-- **读取时校验。** 读取在返回前把字节和元数据与记录的引用比对，请求投影还会完整解码缓存字节，因此缺失、损坏或被替换的对象都会失败关闭。
-- **角色无关的图片块。** `dsh-llm` 中的 `ImageBlock` 内容块携带 `ImageAttachmentRef`；提供方适配器以显式像素与字节预算把引用解析为确定性请求版本，执行文件系统则可以把不可变宿主对象映射为模型可读的进程路径。
+- **读取时校验。** 读取在返回前把字节和元数据与记录的引用比对，请求投影还会完整解码缓存字节，因此缺失、损坏或被替换的对象不会通过校验。
+- **角色无关的图片块。** `dsh-llm` 中的 `ImageBlock` 内容块携带 `ImageAttachmentRef`；提供方适配器按路由显式选定的目标尺寸与字节目标把引用解析为确定性请求版本，执行文件系统则可以把不可变宿主对象映射为模型可读的进程路径。
 - **按错误码路由。** `AttachmentError` 重新实现 `HarnessError` 的结构而不是继承它，因为基类位于 `dsh-llm`，而后者依赖本包；消费方用 `isAttachmentError` 识别错误并按 `code` 路由，绝不依赖原型链。
-- **文件原样，图片规范化。**`saveFile` 提交已有字节数组，`saveFileStream` 以背压和取消语义提交有界分块，`readFileStream` 校验并返回有界分块，`fileHostPath` 定位存储对象供按需读取投影；两种文件写入路径都不设准入限制。图片路径保留其独立的规范化、限额与请求版本流水线。`dsh-llm` 中的 `FileBlock` 内容块承载 `FileAttachmentRef`，请求组装把它对每条路由都投影成确定性 handle 文本。
+- **文件原样，图片规范化。**`saveFile` 提交已有字节数组，`saveFileStream` 以背压和取消语义提交有界分块，`readFileStream` 校验并返回有界分块，`fileHostPath` 定位存储对象供按需读取投影；两种文件写入路径都不设准入限制。图片路径保留其独立的规范化、限额与请求版本流水线。`dsh-llm` 中的 `FileBlock` 内容块承载 `FileAttachmentRef`，请求组装会为每条路由将其投影为确定性的句柄文本。
 
 ### 服务操作
 
-服务族运行同一条准入与存储流程：每个入口都强制执行源批次限制与规范 base64，在发布任何成员前准备提供方无关的规范化附件，再按输入顺序持久提交而不产生部分结果。Host prompt 消费方把有序文本、编码图片和已经解析的文件引用交给 `ctx.attachments.admitPromptContent()`；该方法持久化图片，并让文件引用原样通过。编码协议适配器调用 `ctx.attachments.admitEncodedFile()`，由该方法检查规范 base64 后委托给 `saveFile`；适配器通过 `ctx.attachments.isAttachmentError()` 识别附件错误。通用文件调用方可以用 `saveFile` 提交已有字节，或用 `saveFileStream` 提交有界异步字节源；两者返回相同的持久引用，`readFileStream` 则在有界读取过程中校验摘要与长度。`readImageRequest` 派生确定性的路由尺寸变体，其身份包含附件 id、变换版本、像素与字节预算及编码参数。纯函数导出 `requestImageDimensions` 会按总像素预算计算每个投影保持宽高比的尺寸，使提供方与请求定价共享同一套几何计算。`imageHostPath` 只向需要执行世界映射的受信任同进程消费方暴露实现拥有的宿主位置。调用方组合有序批次，而实现拥有压缩并发、缓存与 singleflight。读取、流式写入和投影保留调用方的取消语义。失败带有稳定且机器可读的错误码，运行时即可识别可由调用方修正的准入子集，让每个协议适配器映射自己的词汇；各操作的确切约定见 [`src/index.ts`](src/index.ts) 与 [`src/error.ts`](src/error.ts)。
+服务族运行同一条准入与存储流程：每个入口都强制执行源批次限制与规范 base64，在发布任何成员前准备提供方无关的规范化附件，再按输入顺序持久提交而不产生部分结果。Host 提示词消费方把有序文本、编码图片和已经解析的文件引用交给 `ctx.attachments.admitPromptContent()`；该方法持久化图片，并让文件引用原样通过。编码协议适配器调用 `ctx.attachments.admitEncodedFile()`，由该方法检查规范 base64 后委托给 `saveFile`；适配器通过 `ctx.attachments.isAttachmentError()` 识别附件错误。通用文件调用方可以用 `saveFile` 提交已有字节，或用 `saveFileStream` 提交有界异步字节源；两者返回相同的持久引用，`readFileStream` 则在有界读取过程中校验摘要与长度。`readImageRequest` 派生确定性的路由尺寸变体，其身份包含附件 id、变换版本、目标尺寸、字节目标及编码参数。纯函数导出 `requestImageDimensions` 与 `longEdgeDimensions` 按总像素预算或精确长边计算保持宽高比的尺寸，使路由与请求定价共享同一套几何计算。`imageHostPath` 只向需要把该位置映射到执行环境的受信任同进程消费方暴露实现拥有的宿主位置。调用方组合有序批次，而实现负责管理压缩并发、缓存与 singleflight。读取、流式写入和投影保留调用方的取消语义。失败带有稳定且机器可读的错误码，运行时即可识别可由调用方修正的准入子集，让每个协议适配器映射自己的词汇；各操作的确切约定见 [`src/index.ts`](src/index.ts) 与 [`src/error.ts`](src/error.ts)。
 
 ### 源码地图
 
@@ -83,7 +83,7 @@ kind: "package-reference"
 | [`src/admission.ts`](src/admission.ts) | 对编码图片和文件上传强制执行规范 base64 并委托存储 |
 | [`src/error.ts`](src/error.ts) | `AttachmentError` 类与 `isImageAdmissionError` 运行时子集 |
 | [`src/brand.ts`](src/brand.ts) | `AttachmentId` 带类型标记的不透明标识符 |
-| — | 不发布运行时不变式伴生入口；实现负责强制不可变存储检查。 |
+| — | 不发布运行时不变式伴生入口；这个无状态 seam 承载类型，实现则负责强制执行不可变存储检查。 |
 
 </details>
 
@@ -94,7 +94,7 @@ kind: "package-reference"
 
 完整的服务约定与载荷类型请看子系统参考；支撑这一能力的存储请看本地后端。
 
-- [附件子系统参考](../../../docs/subsystems/attachment.zh.md)——服务约定、载荷类型与 `ctx.attachments` 的 cordis 接口面。
+- [附件子系统参考](../../../docs/subsystems/attachment.zh.md)——服务约定、载荷类型与 `ctx.attachments` 的 Cordis 接口面。
 - [本地文件系统后端](../attachment-local/README.zh.md)——你的附加图片在本机上的存储位置。
 - [能力 seam](../../../docs/capability-seams.zh.md)——本能力家族如何拆分为多个角色。
 
@@ -103,7 +103,7 @@ kind: "package-reference"
 <a id="model-experience"></a>
 ## 模型体验
 
-该包通过提供方适配器间接影响模型；适配器会把每个持久图片引用解析为确切请求版本，并在图片旁发送稳定附件 id 与实际尺寸。执行文件系统可以映射已存对象时，描述符还会包含只读进程路径，以及可写副本使用的匹配扩展名。通用文件的字节永远不会到达提供方：每条路由都收到一行确定性 handle 文本，指出文件名、字节数、摘要前缀，以及供文件工具读取的只读保存路径。
+该包通过提供方适配器间接影响模型；适配器会把每个持久图片引用解析为确切请求版本，并在图片旁发送稳定附件 id 与实际尺寸。执行文件系统可以映射已存对象时，描述符还会包含只读进程路径，以及可写副本使用的匹配扩展名。通用文件的字节永远不会到达提供方：每条路由都收到一行确定性的句柄文本，指出文件名、字节数、摘要前缀，以及供文件工具读取的只读保存路径。
 
 #### KV Cache 影响
 
@@ -134,6 +134,6 @@ kind: "package-reference"
 
 #### 未来：音频、视频与助手侧输出
 
-音频与视频需要原样文件路径之外的专门生命周期与提供方契约；角色无关的 `ImageBlock` 也把助手侧图片输出留作前瞻兼容——当前生产适配器声明只输出文本，因此只有用户内容携带图片。两个方向都尚未决定。
+音频与视频需要原样文件路径之外的专门生命周期与提供方约定；角色无关的 `ImageBlock` 也为助手侧图片输出保留向前兼容空间——当前生产适配器声明只输出文本，因此只有用户内容携带图片。两个方向都尚未决定。
 
 </details>

package/lib/index.js

@@ -137,8 +137,8 @@ function ImageVariantId(value) {
 //#endregion
 //#region lib/types/request-projection.js
 /**
-* Pure request-projection geometry shared by attachment providers and
-* provider-side request pricing. @module @deepseek-ai/dsh-attachment/request-projection
+* Pure request-projection geometry shared by model routes and provider-side
+* request pricing. @module @deepseek-ai/dsh-attachment/request-projection
 */
 /**
 * Compute aspect-preserving integer dimensions within a hard total-pixel budget.
@@ -176,6 +176,28 @@ function requestImageDimensions(width, height, maxPixels) {
 		height: projectedHeight
 	};
 }
+/**
+* Compute aspect-preserving integer dimensions with an exact long edge; the
+* short edge rounds to the nearest pixel, as an encoder resize by the
+* long edge alone.
+* @param width - positive source width.
+* @param height - positive source height.
+* @param longEdge - positive target for the longer source edge.
+* @returns the target dimensions; a long edge at or above the source returns the source unchanged.
+*/
+function longEdgeDimensions(width, height, longEdge) {
+	if (longEdge >= Math.max(width, height)) return {
+		width,
+		height
+	};
+	return width >= height ? {
+		width: longEdge,
+		height: Math.max(1, Math.round(longEdge * height / width))
+	} : {
+		width: Math.max(1, Math.round(longEdge * width / height)),
+		height: longEdge
+	};
+}
 //#endregion
 //#region lib/types/index.js
 /** Durable attachment storage seam (`ctx.attachments`). @module @deepseek-ai/dsh-attachment */
@@ -309,14 +331,14 @@ var AttachmentStore = class extends Service {
 	/**
 	* 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 budget and encoded-byte target; a target no ladder quality meets yields the smallest ladder output.
+	* @param target - route-chosen dimensions and byte target; an unmet byte target yields the smallest ladder output.
 	* @param signal - optional cancellation.
 	* @returns request bytes and the cache/upload identity covering every transform input.
 	*/
-	readImageRequest(ref, policy, signal) {
+	readImageRequest(ref, target, 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, ImageVariantId, admitEncodedFile, admitEncodedImages, isAttachmentError, isImageAdmissionError, requestImageDimensions };
+export { AttachmentError, AttachmentId, AttachmentStore, AttachmentStore as default, ImageVariantId, admitEncodedFile, admitEncodedImages, isAttachmentError, isImageAdmissionError, longEdgeDimensions, requestImageDimensions };

package/lib/types/index.d.ts

@@ -1,13 +1,14 @@
 /** Durable attachment storage seam (`ctx.attachments`). @module @deepseek-ai/dsh-attachment */
 import { Context, Service } from '@deepseek-ai/cordis';
 import { AttachmentError } from './error.ts';
-import type { AdmittedPromptContentPart, AttachmentAdmissionPart, EncodedFileAttachment, FileAttachmentRef, ImageAttachmentLimits, ImageAttachmentRef, ImageRequestPolicy, RequestImageAttachment, SaveFileAttachment, SaveFileStreamAttachment, SaveImageAttachment, StoredImageAttachment } from './types.ts';
+import type { AdmittedPromptContentPart, AttachmentAdmissionPart, EncodedFileAttachment, FileAttachmentRef, ImageAttachmentLimits, ImageAttachmentRef, ImageRequestTarget, RequestImageAttachment, SaveFileAttachment, SaveFileStreamAttachment, SaveImageAttachment, StoredImageAttachment } from './types.ts';
 export { AttachmentId, ImageVariantId } from './brand.ts';
 export { AttachmentError, isAttachmentError, isImageAdmissionError } from './error.ts';
 export type { AttachmentErrorCode, ImageAdmissionErrorCode } from './error.ts';
 export { admitEncodedFile, admitEncodedImages } from './admission.ts';
-export { requestImageDimensions } from './request-projection.ts';
-export type { AttachmentId as AttachmentIdType, AdmittedPromptContentPart, AttachmentAdmissionPart, EncodedFileAttachment, EncodedImageAttachment, FileAttachmentRef, ImageAttachmentLimits, ImageAttachmentRef, ImageRequestPolicy, ImageMediaType, PromptContentPart, RequestImageAttachment, SaveFileAttachment, SaveFileStreamAttachment, SaveImageAttachment, StoredImageAttachment, } from './types.ts';
+export { longEdgeDimensions, requestImageDimensions } from './request-projection.ts';
+export type { ProjectedDimensions } from './request-projection.ts';
+export type { AttachmentId as AttachmentIdType, AdmittedPromptContentPart, AttachmentAdmissionPart, EncodedFileAttachment, EncodedImageAttachment, FileAttachmentRef, ImageAttachmentLimits, ImageAttachmentRef, ImageRequestTarget, ImageMediaType, PromptContentPart, RequestImageAttachment, SaveFileAttachment, SaveFileStreamAttachment, SaveImageAttachment, StoredImageAttachment, } from './types.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         attachments: AttachmentStore;
@@ -121,11 +122,11 @@ export declare abstract class AttachmentStore extends Service {
     /**
      * 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 budget and encoded-byte target; a target no ladder quality meets yields the smallest ladder output.
+     * @param target - route-chosen dimensions and byte target; an unmet byte target yields the smallest ladder output.
      * @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>;
+    readImageRequest(ref: ImageAttachmentRef, target: ImageRequestTarget, signal?: AbortSignal): Promise<RequestImageAttachment>;
 }
 export default AttachmentStore;
 //# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -5,7 +5,7 @@ import { AttachmentError, isAttachmentError as matchesAttachmentError } from "./
 export { AttachmentId, ImageVariantId } from "./brand.js";
 export { AttachmentError, isAttachmentError, isImageAdmissionError } from "./error.js";
 export { admitEncodedFile, admitEncodedImages } from "./admission.js";
-export { requestImageDimensions } from "./request-projection.js";
+export { longEdgeDimensions, requestImageDimensions } from "./request-projection.js";
 /** Immutable binary attachment service. Implementations validate bytes before publishing a reference. */
 export class AttachmentStore extends Service {
     constructor(ctx) {
@@ -147,14 +147,14 @@ export class AttachmentStore extends Service {
     /**
      * 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 budget and encoded-byte target; a target no ladder quality meets yields the smallest ladder output.
+     * @param target - route-chosen dimensions and byte target; an unmet byte target yields the smallest ladder output.
      * @param signal - optional cancellation.
      * @returns request bytes and the cache/upload identity covering every transform input.
      */
-    readImageRequest(ref, policy, signal) {
+    readImageRequest(ref, target, signal) {
         signal?.throwIfAborted();
         void ref;
-        void policy;
+        void target;
         return Promise.reject(new AttachmentError('The mounted attachment provider cannot derive model-request images.', 'ATTACHMENT_PROJECTION_UNSUPPORTED'));
     }
 }

package/lib/types/request-projection.d.ts

@@ -1,7 +1,12 @@
 /**
- * Pure request-projection geometry shared by attachment providers and
- * provider-side request pricing. @module @deepseek-ai/dsh-attachment/request-projection
+ * Pure request-projection geometry shared by model routes and provider-side
+ * request pricing. @module @deepseek-ai/dsh-attachment/request-projection
  */
+/** Integer width and height of one projected image. */
+export interface ProjectedDimensions {
+    width: number;
+    height: number;
+}
 /**
  * Compute aspect-preserving integer dimensions within a hard total-pixel budget.
  * @param width - positive source width.
@@ -9,8 +14,15 @@
  * @param maxPixels - positive width-times-height cap.
  * @returns inward-rounded dimensions; small images are not enlarged.
  */
-export declare function requestImageDimensions(width: number, height: number, maxPixels: number): {
-    width: number;
-    height: number;
-};
+export declare function requestImageDimensions(width: number, height: number, maxPixels: number): ProjectedDimensions;
+/**
+ * Compute aspect-preserving integer dimensions with an exact long edge; the
+ * short edge rounds to the nearest pixel, as an encoder resize by the
+ * long edge alone.
+ * @param width - positive source width.
+ * @param height - positive source height.
+ * @param longEdge - positive target for the longer source edge.
+ * @returns the target dimensions; a long edge at or above the source returns the source unchanged.
+ */
+export declare function longEdgeDimensions(width: number, height: number, longEdge: number): ProjectedDimensions;
 //# sourceMappingURL=request-projection.d.ts.map

package/lib/types/request-projection.js

@@ -1,6 +1,6 @@
 /**
- * Pure request-projection geometry shared by attachment providers and
- * provider-side request pricing. @module @deepseek-ai/dsh-attachment/request-projection
+ * Pure request-projection geometry shared by model routes and provider-side
+ * request pricing. @module @deepseek-ai/dsh-attachment/request-projection
  */
 /**
  * Compute aspect-preserving integer dimensions within a hard total-pixel budget.
@@ -30,4 +30,20 @@ export function requestImageDimensions(width, height, maxPixels) {
     }
     return { width: projectedWidth, height: projectedHeight };
 }
+/**
+ * Compute aspect-preserving integer dimensions with an exact long edge; the
+ * short edge rounds to the nearest pixel, as an encoder resize by the
+ * long edge alone.
+ * @param width - positive source width.
+ * @param height - positive source height.
+ * @param longEdge - positive target for the longer source edge.
+ * @returns the target dimensions; a long edge at or above the source returns the source unchanged.
+ */
+export function longEdgeDimensions(width, height, longEdge) {
+    if (longEdge >= Math.max(width, height))
+        return { width, height };
+    return width >= height
+        ? { width: longEdge, height: Math.max(1, Math.round(longEdge * height / width)) }
+        : { width: Math.max(1, Math.round(longEdge * width / height)), height: longEdge };
+}
 //# sourceMappingURL=request-projection.js.map

package/lib/types/types.d.ts

@@ -124,10 +124,12 @@ 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;
+/** Deterministic request-image target selected by one exact model route for one attachment. */
+export interface ImageRequestTarget {
+    /** Target width in pixels; a target above the source keeps the source width. */
+    width: number;
+    /** Target height in pixels; a target above the source keeps the source height. */
+    height: number;
     /** Encoded-byte target before base64 expansion or Files API upload; the smallest quality-ladder output is kept when no quality fits. */
     maxBytes: number;
 }

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.5-rc.1",
+  "version": "0.1.6-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -32,11 +32,11 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-brand": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-brand": "^0.1.6-alpha.1",
     "@deepseek-ai/cordis": "^4.0.2"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-brand": "^0.1.5-rc.1"
+    "@deepseek-ai/dsh-brand": "^0.1.6-alpha.1",
+    "@deepseek-ai/cordis": "^4.0.2"
   }
 }