@deepseek-ai/dsh-attachment 0.1.1-rc.2 → 0.1.2-alpha.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: 3ad568c7308f1ab85cb4af3fcc2afd3cba9a611a
-README.zh.md: fadbb1c5bbf097c599da651055d63a1ed64cd579
+README.md: 01a5d6ee143ff53175dd7327cd6d419af61938a3
+README.zh.md: 1a1d297297a6815ce5338391af0182e471f99000

package/README.md

@@ -1,16 +1,104 @@
+---
+description: "Durable image attachments for users and maintainers attaching, reusing, or debugging images in prompts and commands."
+kind: "package-reference"
+---
+
 # @deepseek-ai/dsh-attachment
 
 English | [中文](README.zh.md)
 
-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.
+## Summary
+
+You can attach images to prompts and commands, and the harness keeps provider-independent normalized versions durably: each source image is admitted and normalized before your message is processed, reappears in conversation history, and is projected to the selected model route in later turns of the same session. The shipped `dsh` composition enables this with no setup. Attached images survive restarts, while browser paths, provider URLs, local storage paths, and base64 never enter durable session events. Only raster formats (PNG, JPEG, WebP, GIF) are accepted, and unsent composer drafts stay in the browser until you submit. Stored images are never deleted automatically, and non-image files, audio, and video are not supported yet.
+
+## 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
+
+Image attachments work end to end: attach an image to a prompt or a command, and it is saved, shown in history, and sent to the model without any further action from you. In the default `dsh` composition everything is already wired; when you compose your own setup, one plugin enables the capability.
+
+### Attach images to a prompt
+
+Attach one or more images to a user prompt in the client UI. Each source is checked, normalized to a provider-independent 8-bit sRGB/sRGBA raster, and saved before your message is processed; if any image is refused, the whole message fails and nothing is published. Supported source formats are PNG, JPEG, WebP, and GIF; a deployment controls source limits separately from normalized-storage and route-specific request limits. The one plugin below enables durable image attachments (the shipped base composition already mounts it):
+
+```yaml
+- name: '@deepseek-ai/dsh-attachment-local'
+```
+
+### Pass images to commands
+
+Commands that accept image input receive attached images the same way. If a command does not accept images, the harness refuses with an error message instead of silently dropping them.
+
+### Reuse images across the session
+
+Saved normalized images stay in conversation history and are projected into deterministic, route-sized request versions in later turns; after a restart, a resumed session shows and reuses the same images. When the current execution filesystem maps the stored host object, the request descriptor also carries a read-only process path that the model can inspect. When history or a request version is read back, the stored bytes are checked against what was recorded, so a missing, corrupted, or swapped image surfaces as an error rather than wrong bytes.
+
+### What can go wrong
+
+An image can be refused when you attach it — unsupported format, over the size, pixel, or dimension limits, or bytes that do not match their declared type — and the message then fails as a whole. Later, a history read can fail if the stored image was deleted or corrupted on disk. Failures carry stable codes so the client and protocol adapters can explain them in their own words.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the design decisions behind the seam and the service operations that realize the user-visible behavior; observable behavior is fully covered in [Use this package](#use-this-package).
+
+### Design decisions
 
-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.
+- **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.
+- **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 route on `code`, never on the prototype chain.
 
-`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.
+### 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. `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 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
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: abstract `AttachmentStore` service and re-exports |
+| [`src/types.ts`](src/types.ts) | Durable vocabulary: references, limits, upload and store payloads |
+| [`src/admission.ts`](src/admission.ts) | `admitEncodedImages`: canonical-base64 enforcement, then `saveImages` delegation |
+| [`src/error.ts`](src/error.ts) | `AttachmentError` class and the `isImageAdmissionError` runtime subset |
+| [`src/brand.ts`](src/brand.ts) | `AttachmentId` branded opaque identifier |
+| [`src/invariant.ts`](src/invariant.ts) | Invariant companion (no runtime invariant; implementations enforce immutable-store checks) |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+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.
+- [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.
+
+-----
+
+<a id="model-experience"></a>
 ## Model Experience
 
-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.
+Indirectly, through the provider adapter, which resolves each durable reference into an exact request version and sends its stable attachment id and actual dimensions beside the image. When the execution filesystem maps the stored object, the descriptor also includes a read-only process path and a matching extension for a writable copy.
 
 #### KV Cache effect
 
@@ -18,6 +106,29 @@ Adding an image changes the provider request and therefore invalidates the affec
 
 ## 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.
+<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.
+
+- **Raster images only** — PNG, JPEG, WebP, and GIF are accepted; generic files, audio, and video are not supported yet.
+- **Images are never deleted** — stored images are retained indefinitely; nothing removes them automatically.
+- **Unsent drafts are not saved** — a composer draft stays in the browser until you submit the message.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+This Dev Note is working context for maintainers: undecided directions and open questions. It is explicitly non-authoritative — shipped behavior and limits live in the sections above and the package code.
+
+#### Future: reference-aware garbage collection
+
+Resumed and forked sessions may share immutable objects, so any retention policy needs a reference model that accounts for session lineage before objects can be collected. No decision is recorded yet; the local backend currently retains everything.
+
+#### Future: non-image attachments and assistant-side output
+
+Generic files, audio, and video would need separate lifecycle and provider contracts, and the role-neutral `ImageBlock` leaves assistant-side image output as forward compatibility — current production adapters declare text-only output, so only user content carries images. Both directions are undecided.
+
+</details>

package/README.zh.md

@@ -1,23 +1,134 @@
+---
+description: "持久图片附件，供用户与维护者在提示词与命令中附加、复用或排查图片。"
+kind: "package-reference"
+---
+
 # @deepseek-ai/dsh-attachment
 
 [English](README.md) | 中文
 
-持久附件服务边界。`ctx.attachments` 校验并持久提交提供方无关的规范化图片，随后返回可序列化的 `ImageAttachmentRef`；消费方绝不会在会话事件中持久保存浏览器路径、对象 URL、提供方 URL 或 base64。
+## 概述
+
+你可以把图片附加到提示词和命令中，harness 会持久保存提供方无关的规范化版本：每张源图都会在你的消息被处理前准入并规范化，重新出现在对话历史中，并在同一会话的后续轮次投影到所选模型路由。随附的 `dsh` 组合无需任何配置即可支持这一点。已附加的图片在重启后依然存在，而浏览器路径、提供方 URL、本地存储路径与 base64 绝不会进入持久会话事件。只接受光栅格式（PNG、JPEG、WebP、GIF），未发送的输入区草稿在提交前仍留在浏览器中。已存储的图片永远不会被自动删除，通用文件、音频和视频暂不支持。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+图片附件端到端可用：把图片附加到提示词或命令，它会自动保存、显示在历史中并发送给模型，无需你再做任何操作。在默认 `dsh` 组合中一切都已接好；自行组合时，一个插件即可启用该能力。
+
+### 在提示词中附加图片
+
+在客户端 UI 中向用户提示词附加一张或多张图片。每个源图都会在你的消息被处理前接受检查、规范化为提供方无关的 8-bit sRGB/sRGBA 光栅并保存；如果任何一张图片被拒绝，整条消息都会失败且不会发布任何内容。支持的源格式为 PNG、JPEG、WebP 与 GIF；部署方分别控制源图限制、规范化存储限制与路由专用请求限制。下面这一个插件即可启用持久图片附件（随附的 base 组合已经挂载它）：
+
+```yaml
+- name: '@deepseek-ai/dsh-attachment-local'
+```
+
+### 把图片传给命令
+
+接受图片输入的命令以相同方式接收附加图片。如果某个命令不接受图片，harness 会以错误消息拒绝，而不是静默丢弃。
+
+### 在整个会话中复用图片
+
+已保存的规范化图片会保留在对话历史中，并在后续轮次投影为确定性的路由尺寸请求版本；重启后，恢复的会话会显示并复用相同的图片。当前执行文件系统可以映射已存宿主对象时，请求描述符还会携带模型可检查的只读进程路径。回读历史或请求版本时，已存储的字节会与记录的内容比对，因此缺失、损坏或被替换的图片会以错误形式呈现，而不是错误的字节。
+
+### 可能出什么问题
+
+附加图片时可能被拒绝——格式不受支持、超出大小、像素或尺寸限制，或者字节与声明类型不符——此时整条消息失败。之后，如果磁盘上的图片被删除或损坏，历史读取也可能失败。失败带有稳定错误码，客户端与协议适配器可以用自己的措辞解释它们。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释 seam 背后的设计决策，以及实现用户可见行为的服务操作；可观察行为已在[使用本包](#use-this-package)中完整说明。
+
+### 设计决策
 
-未发送的输入区图片仍是由浏览器持有的临时草稿。`validateImage` 运行完整准入策略但不执行持久化。`saveImages` 负责批次图片数量和总字节限制，在发布任何成员前准备全部规范化附件，然后按顺序提交，并且只在完整批次成功后返回引用。后续存储失败不会返回部分引用，但较早写入的不可变内容寻址对象可能保持不可达，直至具备按引用感知的垃圾回收。`AttachmentError.code` 使用封闭的 `AttachmentErrorCode` 字符串联合类型。其 `ImageAdmissionErrorCode` 子集标记可由调用方修正的图片输入失败；`isImageAdmissionError` 在运行时识别该子集，使每个协议适配器可以映射自己的错误词汇。`saveImage` 会在发布任何模型可见的会话事件前提交一张已接受的图片，并直接返回 `ImageAttachmentRef`。规范化过程缩小图片时，引用会通过 `originalDimensions` 记录应用方向后的输入尺寸。`readImage` 根据已记录的元数据校验规范化附件。`readImageRequest` 确定性派生路由所需的请求版本，其身份覆盖附件 ID、变换策略版本、像素和字节预算及编码参数。调用方通过 `Promise.all(refs.map(...))` 组合有序批次，本地实现仍通过实例级限流器、缓存和 singleflight 限制压缩并发。调用方可以取消读取和投影；实现保留取消结果，不把它转换为存储失败。
+- **事件前完成规范化与持久化。** 每个源图都会在批次按序发布前完成准备与校验，因此会话日志绝不会引用部分完成或规范化失败的对象。
+- **不可变且保留策略中立。** 对象一经发布即不可变；恢复和 fork 后的会话可能共享它们，因此引用感知的垃圾回收被推迟，而不是与任何单个会话的删除绑定。
+- **读取时校验。** 读取在返回前把字节和元数据与记录的引用比对，请求投影还会完整解码缓存字节，因此缺失、损坏或被替换的对象都会失败关闭。
+- **角色无关的图片块。** `dsh-llm` 中的 `ImageBlock` 内容块携带 `ImageAttachmentRef`；提供方适配器以显式像素与字节预算把引用解析为确定性请求版本，执行文件系统则可以把不可变宿主对象映射为模型可读的进程路径。
+- **按错误码路由。** `AttachmentError` 重新实现 `HarnessError` 的结构而不是继承它，因为基类位于 `dsh-llm`，而后者依赖本包；消费方按 `code` 路由，绝不依赖原型链。
 
-`admitEncodedImages(attachments, images)` 是每个接受浏览器上传的 RPC 端点（会话 prompt 端点与命令执行器）共用的 wire 入口：它对每个成员强制执行规范 base64，随后把批量准入——限额、校验、有序提交——委托给 `saveImages`。base64 上传形式为 `EncodedImageAttachment`，从 `@deepseek-ai/dsh-attachment/types` 导出，供 wire 契约引用。
+### 服务操作
 
+服务族运行同一条准入与存储流程：每个入口都强制执行源批次限制与规范 base64，在发布任何成员前准备提供方无关的规范化附件，再按输入顺序持久提交而不产生部分结果。`readImageRequest` 派生确定性的路由尺寸变体，其身份包含附件 id、变换版本、像素与字节预算及编码参数。纯函数导出 `requestImageDimensions` 会按总像素预算计算每个投影保持宽高比的尺寸，使提供方与请求定价共享同一套几何计算。`imageHostPath` 只向需要执行世界映射的受信任同进程消费方暴露实现拥有的宿主位置。调用方组合有序批次，而实现拥有压缩并发、缓存与 singleflight。读取和投影保留调用方的取消语义。失败带有稳定且机器可读的错误码，运行时即可识别可由调用方修正的准入子集，让每个协议适配器映射自己的词汇；各操作的确切约定见 [`src/index.ts`](src/index.ts) 与 [`src/error.ts`](src/error.ts)。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：抽象 `AttachmentStore` 服务与再导出 |
+| [`src/types.ts`](src/types.ts) | 持久词汇：引用、限额、上传与存储载荷 |
+| [`src/admission.ts`](src/admission.ts) | `admitEncodedImages`：规范 base64 强制，随后委托 `saveImages` |
+| [`src/error.ts`](src/error.ts) | `AttachmentError` 类与 `isImageAdmissionError` 运行时子集 |
+| [`src/brand.ts`](src/brand.ts) | `AttachmentId` 带类型标记的不透明标识符 |
+| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；实现负责强制不可变存储检查） |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+完整的服务约定与载荷类型请看子系统参考；支撑这一能力的存储请看本地后端。
+
+- [附件子系统参考](../../../docs/subsystems/attachment.zh.md)——服务约定、载荷类型与 `ctx.attachments` 的 cordis 接口面。
+- [本地文件系统后端](../attachment-local/README.zh.md)——你的附加图片在本机上的存储位置。
+- [能力 seam](../../../docs/capability-seams.zh.md)——本能力家族如何拆分为多个角色。
+
+-----
+
+<a id="model-experience"></a>
 ## 模型体验
 
-该包通过角色无关的核心 `ImageBlock`，以及把持久引用解析为确定请求版本的提供方适配器，间接影响模型。请求描述会公开完整附件 ID 和实际请求尺寸。
+该包通过提供方适配器间接影响模型；适配器会把每个持久引用解析为确切请求版本，并在图片旁发送稳定附件 id 与实际尺寸。执行文件系统可以映射已存对象时，描述符还会包含只读进程路径，以及可写副本使用的匹配扩展名。
 
-#### KV 缓存影响
+#### KV Cache 影响
 
 添加图片会改变提供方请求，因此会使受影响的请求后缀失效。
 
-## 已知限制与待完成工作
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制描述了图片附件能做什么、不能做什么；它们是当前包约束，而非任务积压。
+
+- **仅支持光栅图片**——接受 PNG、JPEG、WebP 与 GIF；通用文件、音频和视频暂不支持。
+- **图片永远不会被删除**——已存储的图片无限期保留；没有任何机制自动移除它们。
+- **未发送的草稿不会保存**——输入区草稿在提交消息前一直留在浏览器中。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+本开发备注是维护者的工作上下文：尚未决定的探索方向与开放问题。它明确不具权威性——已交付的行为与限制以上文和包代码为准。
+
+#### 未来：引用感知的垃圾回收
+
+恢复和 fork 后的会话可能共享不可变对象，因此任何保留策略都需要一个能考虑会话血缘的引用模型，之后才能回收对象。目前尚未记录任何决定；本地后端当前保留一切。
+
+#### 未来：非图片附件与助手侧输出
+
+通用文件、音频与视频需要单独的生命周期与提供方契约；角色无关的 `ImageBlock` 也把助手侧图片输出留作前瞻兼容——当前生产适配器声明只输出文本，因此只有用户内容携带图片。两个方向都尚未决定。
 
-- 第一版仅接受 PNG、JPEG、WebP 和 GIF。
-- 保留策略与垃圾回收尚未实现，因为恢复和 fork 后的会话可能共享不可变对象。
-- 通用文件、音频、视频和持久的未发送草稿需要单独的生命周期与提供方契约。
+</details>

package/lib/index.js

@@ -94,6 +94,48 @@ async function admitEncodedImages(attachments, images) {
 	return attachments.saveImages(images.map(saveInput));
 }
 //#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
+*/
+/**
+* Compute aspect-preserving integer dimensions within a hard total-pixel budget.
+* @param width - positive source width.
+* @param height - positive source height.
+* @param maxPixels - positive width-times-height cap.
+* @returns inward-rounded dimensions; small images are not enlarged.
+*/
+function requestImageDimensions(width, height, maxPixels) {
+	const scale = Math.min(1, Math.sqrt(maxPixels / (width * height)));
+	if (scale === 1) return {
+		width,
+		height
+	};
+	if (width >= height) {
+		let projectedWidth = Math.max(1, Math.floor(width * scale));
+		let projectedHeight = Math.max(1, Math.round(projectedWidth * height / width));
+		while (projectedWidth * projectedHeight > maxPixels && projectedWidth > 1) {
+			projectedWidth -= 1;
+			projectedHeight = Math.max(1, Math.round(projectedWidth * height / width));
+		}
+		return {
+			width: projectedWidth,
+			height: projectedHeight
+		};
+	}
+	let projectedHeight = Math.max(1, Math.floor(height * scale));
+	let projectedWidth = Math.max(1, Math.round(projectedHeight * width / height));
+	while (projectedWidth * projectedHeight > maxPixels && projectedHeight > 1) {
+		projectedHeight -= 1;
+		projectedWidth = Math.max(1, Math.round(projectedHeight * width / height));
+	}
+	return {
+		width: projectedWidth,
+		height: projectedHeight
+	};
+}
+//#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. */
@@ -128,9 +170,16 @@ var AttachmentStore = class extends Service {
 		return refs;
 	}
 	/**
+	* Locate the provider-owned normalized object in the harness host filesystem.
+	* @param ref - durable normalized attachment reference.
+	* @returns an absolute host path, or undefined when this backend is not host-file-backed.
+	* @throws an AttachmentError when the durable reference is invalid.
+	*/
+	imageHostPath(ref) {}
+	/**
 	* 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 policy - exact route pixel budget and encoded-byte target; a target no ladder quality meets yields the smallest ladder output.
 	* @param signal - optional cancellation.
 	* @returns request bytes and the cache/upload identity covering every transform input.
 	*/
@@ -140,4 +189,4 @@ var AttachmentStore = class extends Service {
 	}
 };
 //#endregion
-export { AttachmentError, AttachmentId, AttachmentStore, AttachmentStore as default, ImageVariantId, admitEncodedImages, isImageAdmissionError };
+export { AttachmentError, AttachmentId, AttachmentStore, AttachmentStore as default, ImageVariantId, admitEncodedImages, isImageAdmissionError, requestImageDimensions };

package/lib/types/index.d.ts

@@ -5,6 +5,7 @@ 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 { requestImageDimensions } from './request-projection.ts';
 export type { AttachmentId as AttachmentIdType, EncodedImageAttachment, ImageAttachmentLimits, ImageAttachmentRef, ImageRequestPolicy, ImageMediaType, RequestImageAttachment, SaveImageAttachment, StoredImageAttachment, } from './types.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
@@ -55,10 +56,17 @@ export declare abstract class AttachmentStore extends Service {
      * @throws the signal reason when aborted, or a storage error when verification fails.
      */
     abstract readImage(ref: ImageAttachmentRef, signal?: AbortSignal): Promise<StoredImageAttachment>;
+    /**
+     * Locate the provider-owned normalized object in the harness host filesystem.
+     * @param ref - durable normalized attachment reference.
+     * @returns an absolute host path, or undefined when this backend is not host-file-backed.
+     * @throws an AttachmentError when the durable reference is invalid.
+     */
+    imageHostPath(ref: ImageAttachmentRef): string | undefined;
     /**
      * 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 policy - exact route pixel budget and encoded-byte target; a target no ladder quality meets yields the smallest ladder output.
      * @param signal - optional cancellation.
      * @returns request bytes and the cache/upload identity covering every transform input.
      */

package/lib/types/index.js

@@ -4,6 +4,7 @@ import { AttachmentError } from "./error.js";
 export { AttachmentId, ImageVariantId } from "./brand.js";
 export { AttachmentError, isImageAdmissionError } from "./error.js";
 export { admitEncodedImages } from "./admission.js";
+export { requestImageDimensions } from "./request-projection.js";
 /** Immutable binary attachment service. Implementations validate bytes before publishing a reference. */
 export class AttachmentStore extends Service {
     constructor(ctx) {
@@ -46,10 +47,20 @@ export class AttachmentStore extends Service {
             refs.push(await this.saveImage(input));
         return refs;
     }
+    /**
+     * Locate the provider-owned normalized object in the harness host filesystem.
+     * @param ref - durable normalized attachment reference.
+     * @returns an absolute host path, or undefined when this backend is not host-file-backed.
+     * @throws an AttachmentError when the durable reference is invalid.
+     */
+    imageHostPath(ref) {
+        void ref;
+        return undefined;
+    }
     /**
      * 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 policy - exact route pixel budget and encoded-byte target; a target no ladder quality meets yields the smallest ladder output.
      * @param signal - optional cancellation.
      * @returns request bytes and the cache/upload identity covering every transform input.
      */

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

@@ -0,0 +1,16 @@
+/**
+ * Pure request-projection geometry shared by attachment providers and
+ * provider-side request pricing. @module @deepseek-ai/dsh-attachment/request-projection
+ */
+/**
+ * Compute aspect-preserving integer dimensions within a hard total-pixel budget.
+ * @param width - positive source width.
+ * @param height - positive source height.
+ * @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;
+};
+//# sourceMappingURL=request-projection.d.ts.map

package/lib/types/request-projection.js

@@ -0,0 +1,33 @@
+/**
+ * Pure request-projection geometry shared by attachment providers and
+ * provider-side request pricing. @module @deepseek-ai/dsh-attachment/request-projection
+ */
+/**
+ * Compute aspect-preserving integer dimensions within a hard total-pixel budget.
+ * @param width - positive source width.
+ * @param height - positive source height.
+ * @param maxPixels - positive width-times-height cap.
+ * @returns inward-rounded dimensions; small images are not enlarged.
+ */
+export function requestImageDimensions(width, height, maxPixels) {
+    const scale = Math.min(1, Math.sqrt(maxPixels / (width * height)));
+    if (scale === 1)
+        return { width, height };
+    if (width >= height) {
+        let projectedWidth = Math.max(1, Math.floor(width * scale));
+        let projectedHeight = Math.max(1, Math.round(projectedWidth * height / width));
+        while (projectedWidth * projectedHeight > maxPixels && projectedWidth > 1) {
+            projectedWidth -= 1;
+            projectedHeight = Math.max(1, Math.round(projectedWidth * height / width));
+        }
+        return { width: projectedWidth, height: projectedHeight };
+    }
+    let projectedHeight = Math.max(1, Math.floor(height * scale));
+    let projectedWidth = Math.max(1, Math.round(projectedHeight * width / height));
+    while (projectedWidth * projectedHeight > maxPixels && projectedHeight > 1) {
+        projectedHeight -= 1;
+        projectedWidth = Math.max(1, Math.round(projectedHeight * width / height));
+    }
+    return { width: projectedWidth, height: projectedHeight };
+}
+//# sourceMappingURL=request-projection.js.map

package/lib/types/types.d.ts

@@ -62,7 +62,7 @@ export interface StoredImageAttachment {
 export interface ImageRequestPolicy {
     /** Maximum width multiplied by height after aspect-preserving projection. */
     maxPixels: number;
-    /** Encoded-byte cap before base64 expansion or Files API upload. */
+    /** Encoded-byte target before base64 expansion or Files API upload; the smallest quality-ladder output is kept when no quality fits. */
     maxBytes: number;
 }
 /** Cached request version derived from one provider-independent normalized attachment. */

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.2",
+  "version": "0.1.2-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -37,13 +37,13 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-brand": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-brand": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-brand": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-brand": "^0.1.2-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2"
   }
 }