@deepseek-ai/dsh-attachment 0.1.2-alpha.5 → 0.1.3-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: 9561ab4265eb0404f6f60c93c34dab73eed5ffe1
-README.zh.md: 31fcb15c04fadb44c44342e3d1d721d22645732f
+README.md: a812182aeff6d09506a1ea2d4fa8d9a44a175936
+README.zh.md: c487f8204c86d8f0bbdfd85280e8fbab6ea14dec

package/README.md

@@ -1,5 +1,5 @@
 ---
-description: "Durable image attachments for users and maintainers attaching, reusing, or debugging images in prompts and commands."
+description: "Durable image and file attachments for users and maintainers attaching, reusing, or debugging uploads in prompts and commands."
 kind: "package-reference"
 ---
 
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## 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.
+You can attach images and generic files to prompts, and the harness keeps them durably: each source image is admitted and normalized before your message is processed, while any other file is stored byte-for-byte with no format or size limits, and both reappear in conversation history across restarts of the same session. The shipped `dsh` composition enables this with no setup. Browser paths, provider URLs, local storage paths, and base64 never enter durable session events. Images accept raster formats (PNG, JPEG, WebP, GIF) under deployment limits; files accept anything, and the model reads a stored file on demand from its saved read-only path instead of receiving its bytes. Stored objects are never deleted automatically, and audio and video have no dedicated handling yet.
 
 ## Table of Contents
 
@@ -35,9 +35,13 @@ Attach one or more images to a user prompt in the client UI. Each source is chec
 - name: '@deepseek-ai/dsh-attachment-local'
 ```
 
-### Pass images to commands
+### Attach any other file to a prompt
 
-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.
+Any non-image file attaches to a prompt as a generic file: the exact bytes are saved read-only under the harness home, the message records the file name, byte size, and content digest, and the model receives one line naming the saved path so it can read the content with its file tools only when needed. There is no file-type whitelist and no size limit; what you attach is stored verbatim.
+
+### Pass attachments to commands
+
+Commands declaring attachment input receive images and generic files in selection order. Commands that do not accept attachments return an error and retain the composer's draft and cards.
 
 ### Reuse images across the session
 
@@ -63,11 +67,12 @@ This section explains the design decisions behind the seam and the service opera
 - **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.
+- **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. `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).
+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).
 
 ### Source map
 
@@ -75,7 +80,7 @@ The service family runs one admission-and-storage flow: every entry point enforc
 |---|---|
 | [`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) | Browser prompt admission: canonical-base64 enforcement, `saveImages` delegation, and durable prompt-part projection |
+| [`src/admission.ts`](src/admission.ts) | Canonical-base64 enforcement and store delegation for encoded image and file uploads |
 | [`src/error.ts`](src/error.ts) | `AttachmentError` class and the `isImageAdmissionError` runtime subset |
 | [`src/brand.ts`](src/brand.ts) | `AttachmentId` branded opaque identifier |
 | — | No runtime invariant companion is published; this stateless seam owns types while implementations enforce immutable-store checks. |
@@ -98,7 +103,7 @@ For the full service contract and payload types, read the subsystem reference; f
 <a id="model-experience"></a>
 ## Model Experience
 
-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.
+Indirectly, through the provider adapter, which resolves each durable image 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. A generic file never reaches the provider as bytes: every route receives one deterministic handle line naming the file, its byte size, its digest prefix, and the saved read-only path to read with file tools.
 
 #### KV Cache effect
 
@@ -111,8 +116,8 @@ Adding an image changes the provider request and therefore invalidates the affec
 
 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.
+- **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.
 - **Unsent drafts are not saved** — a composer draft stays in the browser until you submit the message.
 
 <a id="dev-note"></a>
@@ -127,8 +132,8 @@ This Dev Note is working context for maintainers: undecided directions and open
 
 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
+#### Future: audio, video, 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.
+Audio and video would need dedicated lifecycle and provider contracts beyond the verbatim file path, 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,5 +1,5 @@
 ---
-description: "持久图片附件，供用户与维护者在提示词与命令中附加、复用或排查图片。"
+description: "持久图片与文件附件，供用户与维护者在提示词与命令中附加、复用或排查上传内容。"
 kind: "package-reference"
 ---
 
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-你可以把图片附加到提示词和命令中，harness 会持久保存提供方无关的规范化版本：每张源图都会在你的消息被处理前准入并规范化，重新出现在对话历史中，并在同一会话的后续轮次投影到所选模型路由。随附的 `dsh` 组合无需任何配置即可支持这一点。已附加的图片在重启后依然存在，而浏览器路径、提供方 URL、本地存储路径与 base64 绝不会进入持久会话事件。只接受光栅格式（PNG、JPEG、WebP、GIF），未发送的输入区草稿在提交前仍留在浏览器中。已存储的图片永远不会被自动删除，通用文件、音频和视频暂不支持。
+你可以把图片和通用文件附加到提示词中，harness 会持久保存它们：每张源图都会在你的消息被处理前准入并规范化，而其他任何文件都按字节原样保存、不设格式与大小限制，两者都会在同一会话重启后重新出现在对话历史中。随附的 `dsh` 组合无需任何配置即可支持这一点。浏览器路径、提供方 URL、本地存储路径与 base64 绝不会进入持久会话事件。图片接受部署限额内的光栅格式（PNG、JPEG、WebP、GIF）；文件接受任何内容，模型不接收文件字节，而是在需要时从保存的只读路径按需读取。已存储对象永远不会被自动删除，音频和视频暂无专门处理。
 
 ## 目录
 
@@ -35,9 +35,13 @@ kind: "package-reference"
 - name: '@deepseek-ai/dsh-attachment-local'
 ```
 
-### 把图片传给命令
+### 在提示词中附加任意其他文件
 
-接受图片输入的命令以相同方式接收附加图片。如果某个命令不接受图片，harness 会以错误消息拒绝，而不是静默丢弃。
+任何非图片文件都以通用文件的形式附加到提示词：确切字节被只读保存在 harness 主目录下，消息记录文件名、字节数与内容摘要，模型收到一行指出保存路径的文本，只在需要时用文件工具读取内容。没有文件类型白名单，也没有大小上限；你附加什么就原样存什么。
+
+### 把附件传给命令
+
+声明接受附件的命令会按选择顺序接收图片与通用文件。不接受附件的命令会返回错误，并保留 composer 的草稿与附件卡。
 
 ### 在整个会话中复用图片
 
@@ -63,11 +67,12 @@ kind: "package-reference"
 - **不可变且保留策略中立。** 对象一经发布即不可变；恢复和 fork 后的会话可能共享它们，因此引用感知的垃圾回收被推迟，而不是与任何单个会话的删除绑定。
 - **读取时校验。** 读取在返回前把字节和元数据与记录的引用比对，请求投影还会完整解码缓存字节，因此缺失、损坏或被替换的对象都会失败关闭。
 - **角色无关的图片块。** `dsh-llm` 中的 `ImageBlock` 内容块携带 `ImageAttachmentRef`；提供方适配器以显式像素与字节预算把引用解析为确定性请求版本，执行文件系统则可以把不可变宿主对象映射为模型可读的进程路径。
-- **按错误码路由。** `AttachmentError` 重新实现 `HarnessError` 的结构而不是继承它，因为基类位于 `dsh-llm`，而后者依赖本包；消费方按 `code` 路由，绝不依赖原型链。
+- **按错误码路由。** `AttachmentError` 重新实现 `HarnessError` 的结构而不是继承它，因为基类位于 `dsh-llm`，而后者依赖本包；消费方用 `isAttachmentError` 识别错误并按 `code` 路由，绝不依赖原型链。
+- **文件原样，图片规范化。**`saveFile` 提交已有字节数组，`saveFileStream` 以背压和取消语义提交有界分块，`readFileStream` 校验并返回有界分块，`fileHostPath` 定位存储对象供按需读取投影；两种文件写入路径都不设准入限制。图片路径保留其独立的规范化、限额与请求版本流水线。`dsh-llm` 中的 `FileBlock` 内容块承载 `FileAttachmentRef`，请求组装把它对每条路由都投影成确定性 handle 文本。
 
 ### 服务操作
 
-服务族运行同一条准入与存储流程：每个入口都强制执行源批次限制与规范 base64，在发布任何成员前准备提供方无关的规范化附件，再按输入顺序持久提交而不产生部分结果。`readImageRequest` 派生确定性的路由尺寸变体，其身份包含附件 id、变换版本、像素与字节预算及编码参数。纯函数导出 `requestImageDimensions` 会按总像素预算计算每个投影保持宽高比的尺寸，使提供方与请求定价共享同一套几何计算。`imageHostPath` 只向需要执行世界映射的受信任同进程消费方暴露实现拥有的宿主位置。调用方组合有序批次，而实现拥有压缩并发、缓存与 singleflight。读取和投影保留调用方的取消语义。失败带有稳定且机器可读的错误码，运行时即可识别可由调用方修正的准入子集，让每个协议适配器映射自己的词汇；各操作的确切约定见 [`src/index.ts`](src/index.ts) 与 [`src/error.ts`](src/error.ts)。
+服务族运行同一条准入与存储流程：每个入口都强制执行源批次限制与规范 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)。
 
 ### 源码地图
 
@@ -75,7 +80,7 @@ kind: "package-reference"
 |---|---|
 | [`src/index.ts`](src/index.ts) | 插件入口：抽象 `AttachmentStore` 服务与再导出 |
 | [`src/types.ts`](src/types.ts) | 持久词汇：引用、限额、上传与存储载荷 |
-| [`src/admission.ts`](src/admission.ts) | 浏览器 prompt 准入：强制规范 base64、委托 `saveImages` 并投影持久 prompt part |
+| [`src/admission.ts`](src/admission.ts) | 对编码图片和文件上传强制执行规范 base64 并委托存储 |
 | [`src/error.ts`](src/error.ts) | `AttachmentError` 类与 `isImageAdmissionError` 运行时子集 |
 | [`src/brand.ts`](src/brand.ts) | `AttachmentId` 带类型标记的不透明标识符 |
 | — | 不发布运行时不变式伴生入口；实现负责强制不可变存储检查。 |
@@ -98,7 +103,7 @@ kind: "package-reference"
 <a id="model-experience"></a>
 ## 模型体验
 
-该包通过提供方适配器间接影响模型；适配器会把每个持久引用解析为确切请求版本，并在图片旁发送稳定附件 id 与实际尺寸。执行文件系统可以映射已存对象时，描述符还会包含只读进程路径，以及可写副本使用的匹配扩展名。
+该包通过提供方适配器间接影响模型；适配器会把每个持久图片引用解析为确切请求版本，并在图片旁发送稳定附件 id 与实际尺寸。执行文件系统可以映射已存对象时，描述符还会包含只读进程路径，以及可写副本使用的匹配扩展名。通用文件的字节永远不会到达提供方：每条路由都收到一行确定性 handle 文本，指出文件名、字节数、摘要前缀，以及供文件工具读取的只读保存路径。
 
 #### KV Cache 影响
 
@@ -109,10 +114,10 @@ kind: "package-reference"
 <a id="known-limitations-and-deferred-work"></a>
 
 
-这些限制描述了图片附件能做什么、不能做什么；它们是当前包约束，而非任务积压。
+这些限制描述了附件能做什么、不能做什么；它们是当前包约束，而非任务积压。
 
-- **仅支持光栅图片**——接受 PNG、JPEG、WebP 与 GIF；通用文件、音频和视频暂不支持。
-- **图片永远不会被删除**——已存储的图片无限期保留；没有任何机制自动移除它们。
+- **光栅图片限制只作用于图片**——图片接受部署限额内的 PNG、JPEG、WebP 与 GIF；其他任何文件都原样保存、不设类型与大小限制，音频和视频暂无专门处理。
+- **附件永远不会被删除**——已存储的图片与文件无限期保留；没有任何机制自动移除它们。
 - **未发送的草稿不会保存**——输入区草稿在提交消息前一直留在浏览器中。
 
 <a id="dev-note"></a>
@@ -127,8 +132,8 @@ kind: "package-reference"
 
 恢复和 fork 后的会话可能共享不可变对象，因此任何保留策略都需要一个能考虑会话血缘的引用模型，之后才能回收对象。目前尚未记录任何决定；本地后端当前保留一切。
 
-#### 未来：非图片附件与助手侧输出
+#### 未来：音频、视频与助手侧输出
 
-通用文件、音频与视频需要单独的生命周期与提供方契约；角色无关的 `ImageBlock` 也把助手侧图片输出留作前瞻兼容——当前生产适配器声明只输出文本，因此只有用户内容携带图片。两个方向都尚未决定。
+音频与视频需要原样文件路径之外的专门生命周期与提供方契约；角色无关的 `ImageBlock` 也把助手侧图片输出留作前瞻兼容——当前生产适配器声明只输出文本，因此只有用户内容携带图片。两个方向都尚未决定。
 
 </details>

package/lib/index.js

@@ -1,8 +1,8 @@
 import { Service } from "@deepseek-ai/cordis";
 import { Buffer } from "node:buffer";
 //#region lib/types/error.js
-/** Runtime membership for structurally compatible errors crossing package boundaries. */
-const IMAGE_ADMISSION_ERROR_CODE_SET = new Set([
+/** Attachment failure class. @module @deepseek-ai/dsh-attachment/error */
+const IMAGE_ADMISSION_ERROR_CODES = [
 	"TOO_MANY_IMAGES",
 	"IMAGES_TOO_LARGE",
 	"UNSUPPORTED_IMAGE_TYPE",
@@ -12,7 +12,21 @@ const IMAGE_ADMISSION_ERROR_CODE_SET = new Set([
 	"IMAGE_TOO_LARGE",
 	"IMAGE_TOO_MANY_PIXELS",
 	"IMAGE_DIMENSION_TOO_LARGE"
-]);
+];
+const ATTACHMENT_ERROR_CODES = [
+	...IMAGE_ADMISSION_ERROR_CODES,
+	"INVALID_FILE_BASE64",
+	"INVALID_ATTACHMENT_REF",
+	"ATTACHMENT_CORRUPT",
+	"ATTACHMENT_WRITE_FAILED",
+	"ATTACHMENT_NOT_FOUND",
+	"ATTACHMENT_READ_FAILED",
+	"ATTACHMENT_PROJECTION_UNSUPPORTED",
+	"ATTACHMENT_FILES_UNSUPPORTED"
+];
+/** Runtime membership for structurally compatible errors crossing package boundaries. */
+const IMAGE_ADMISSION_ERROR_CODE_SET = new Set(IMAGE_ADMISSION_ERROR_CODES);
+const ATTACHMENT_ERROR_CODE_SET = new Set(ATTACHMENT_ERROR_CODES);
 /**
 * Stable failures suitable for host RPC error mapping.
 *
@@ -37,6 +51,14 @@ var AttachmentError = class extends Error {
 	}
 };
 /**
+* Identify attachment failures by their stable code across duplicate package installations.
+* @param error - failure raised while validating, persisting, or reading an attachment.
+* @returns whether the failure carries a recognized attachment error code.
+*/
+function isAttachmentError(error) {
+	return error instanceof Error && "code" in error && typeof error.code === "string" && ATTACHMENT_ERROR_CODE_SET.has(error.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.
@@ -45,33 +67,17 @@ 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;
-}
-/**
-* 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 */
 /** Decode one upload payload while rejecting non-canonical base64 forms. */
-function decodeBase64(data) {
+function decodeCanonicalBase64(data, empty, code) {
 	const decoded = Buffer.from(data, "base64");
-	if (data.length === 0 || decoded.toString("base64") !== data) throw new AttachmentError("Image upload is not canonical base64.", "INVALID_IMAGE_BASE64");
+	if (data.length === 0 && empty === "reject" || decoded.toString("base64") !== data) throw new AttachmentError(code === "INVALID_IMAGE_BASE64" ? "Image upload is not canonical base64." : "File upload is not canonical base64.", code);
 	return new Uint8Array(decoded);
 }
+function decodeBase64(data) {
+	return decodeCanonicalBase64(data, "reject", "INVALID_IMAGE_BASE64");
+}
 /** Store input for one decoded upload. */
 function saveInput(image) {
 	return {
@@ -94,29 +100,41 @@ async function admitEncodedImages(attachments, images) {
 	return attachments.saveImages(images.map(saveInput));
 }
 /**
-* Admit one browser prompt and replace each uploaded image with its durable reference.
-* Text-only prompts do not access the attachment store.
-* @param attachments - the deployment attachment store owning batch policy.
-* @param content - browser prompt parts in message order.
-* @returns admitted prompt parts in the same order as `content`.
-* @throws AttachmentError when the image batch is refused.
+* Admit one wire file upload: enforce canonical base64 (an empty file is a
+* valid zero-byte payload), then delegate verbatim commit to
+* {@link AttachmentStore.saveFile}. The shared entry for every RPC endpoint
+* accepting browser file uploads.
+* @param attachments - the deployment attachment store.
+* @param file - base64-encoded upload and optional display name.
+* @returns the durable content-addressed file reference.
+* @throws AttachmentError on a non-canonical payload or a storage failure.
 */
-async function admitPromptContent(attachments, content) {
-	if (content.every((part) => part.type === "text")) return content.map((part) => ({
-		type: "text",
-		text: part.text
-	}));
-	const refs = await admitEncodedImages(attachments, content.filter((part) => part.type === "image"));
-	let next = 0;
-	return content.map((part) => part.type === "text" ? {
-		type: "text",
-		text: part.text
-	} : {
-		type: "image",
-		attachment: refs[next++]
+async function admitEncodedFile(attachments, file) {
+	return attachments.saveFile({
+		data: decodeCanonicalBase64(file.data, "accept", "INVALID_FILE_BASE64"),
+		...file.name === void 0 ? {} : { name: file.name }
 	});
 }
 //#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;
+}
+/**
+* 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/request-projection.js
 /**
 * Pure request-projection geometry shared by attachment providers and
@@ -193,6 +211,55 @@ var AttachmentStore = class extends Service {
 		return refs;
 	}
 	/**
+	* Admit one Host prompt and replace each uploaded image with its durable reference.
+	* Text and durable file references pass through unchanged. A prompt without image parts performs no storage operation.
+	* @param content - prompt parts in message order after file receipt resolution.
+	* @returns admitted prompt parts in the same order as `content`.
+	* @throws AttachmentError when the image batch is refused.
+	*/
+	async admitPromptContent(content) {
+		if (content.every((part) => part.type !== "image")) return content.map((part) => part.type === "text" ? {
+			type: "text",
+			text: part.text
+		} : {
+			type: "file",
+			attachment: part.attachment
+		});
+		const refs = await admitEncodedImages(this, content.filter((part) => part.type === "image"));
+		let next = 0;
+		return content.map((part) => {
+			if (part.type === "text") return {
+				type: "text",
+				text: part.text
+			};
+			if (part.type === "file") return {
+				type: "file",
+				attachment: part.attachment
+			};
+			return {
+				type: "image",
+				attachment: refs[next++]
+			};
+		});
+	}
+	/**
+	* Decode and durably commit one canonical base64 file upload.
+	* @param input - canonical base64 bytes and optional display name.
+	* @returns the durable content-addressed file reference.
+	* @throws AttachmentError when the encoding or storage operation is refused.
+	*/
+	admitEncodedFile(input) {
+		return admitEncodedFile(this, input);
+	}
+	/**
+	* Identify a failure emitted by this attachment capability by its stable code.
+	* @param error - value caught from an attachment operation.
+	* @returns whether the value is an attachment failure.
+	*/
+	isAttachmentError(error) {
+		return isAttachmentError(error);
+	}
+	/**
 	* 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.
@@ -200,6 +267,46 @@ var AttachmentStore = class extends Service {
 	*/
 	imageHostPath(ref) {}
 	/**
+	* Durably commit one file byte-for-byte before its owning session event is
+	* appended. Files carry no admission limits: any byte content and length is
+	* accepted, and the stored object is the exact submitted bytes. Backends
+	* without verbatim file storage keep this default rejection.
+	* @param input - exact bytes and optional display name.
+	* @returns the durable content-addressed file reference.
+	*/
+	saveFile(input) {
+		return Promise.reject(new AttachmentError("The mounted attachment provider cannot store verbatim files.", "ATTACHMENT_FILES_UNSUPPORTED"));
+	}
+	/**
+	* Durably commit one file byte-for-byte from bounded chunks. Providers must
+	* apply backpressure and must not collect the complete file in memory.
+	* Backends without streamed verbatim storage keep this default rejection.
+	* @param input - ordered exact bytes, optional cancellation, and display name.
+	* @returns the durable content-addressed file reference.
+	*/
+	saveFileStream(input) {
+		return Promise.reject(new AttachmentError("The mounted attachment provider cannot stream verbatim files.", "ATTACHMENT_FILES_UNSUPPORTED"));
+	}
+	/**
+	* Read and verify one verbatim stored file as bounded chunks. Providers must
+	* not collect the complete file in memory. Backends without verbatim file
+	* reads keep this default rejection.
+	* @param ref - durable reference from the session log.
+	* @param signal - optional cancellation for backend reads and verification work.
+	* @returns exact file bytes in order; integrity failures reject the iteration.
+	*/
+	async *readFileStream(ref, signal) {
+		signal?.throwIfAborted();
+		await Promise.reject(new AttachmentError("The mounted attachment provider cannot read verbatim files.", "ATTACHMENT_FILES_UNSUPPORTED"));
+	}
+	/**
+	* Locate the verbatim stored file object in the harness host filesystem.
+	* @param ref - durable file 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.
+	*/
+	fileHostPath(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 budget and encoded-byte target; a target no ladder quality meets yields the smallest ladder output.
@@ -212,4 +319,4 @@ var AttachmentStore = class extends Service {
 	}
 };
 //#endregion
-export { AttachmentError, AttachmentId, AttachmentStore, AttachmentStore as default, ImageVariantId, admitEncodedImages, admitPromptContent, isImageAdmissionError, requestImageDimensions };
+export { AttachmentError, AttachmentId, AttachmentStore, AttachmentStore as default, ImageVariantId, admitEncodedFile, admitEncodedImages, isAttachmentError, isImageAdmissionError, requestImageDimensions };

package/lib/types/admission.d.ts

@@ -1,6 +1,6 @@
 /** Wire-form admission of base64-encoded image uploads. @module @deepseek-ai/dsh-attachment/admission */
 import type { AttachmentStore } from './index.ts';
-import type { AdmittedPromptContentPart, EncodedImageAttachment, ImageAttachmentRef, PromptContentPart } from './types.ts';
+import type { EncodedFileAttachment, EncodedImageAttachment, FileAttachmentRef, ImageAttachmentRef } from './types.ts';
 /**
  * Admit one wire image batch: enforce canonical base64 on every member, then
  * delegate batch admission — count and aggregate-byte limits, media-type and
@@ -13,12 +13,14 @@ import type { AdmittedPromptContentPart, EncodedImageAttachment, ImageAttachment
  */
 export declare function admitEncodedImages(attachments: AttachmentStore, images: readonly EncodedImageAttachment[]): Promise<readonly ImageAttachmentRef[]>;
 /**
- * Admit one browser prompt and replace each uploaded image with its durable reference.
- * Text-only prompts do not access the attachment store.
- * @param attachments - the deployment attachment store owning batch policy.
- * @param content - browser prompt parts in message order.
- * @returns admitted prompt parts in the same order as `content`.
- * @throws AttachmentError when the image batch is refused.
+ * Admit one wire file upload: enforce canonical base64 (an empty file is a
+ * valid zero-byte payload), then delegate verbatim commit to
+ * {@link AttachmentStore.saveFile}. The shared entry for every RPC endpoint
+ * accepting browser file uploads.
+ * @param attachments - the deployment attachment store.
+ * @param file - base64-encoded upload and optional display name.
+ * @returns the durable content-addressed file reference.
+ * @throws AttachmentError on a non-canonical payload or a storage failure.
  */
-export declare function admitPromptContent(attachments: AttachmentStore, content: readonly PromptContentPart[]): Promise<AdmittedPromptContentPart[]>;
+export declare function admitEncodedFile(attachments: AttachmentStore, file: EncodedFileAttachment): Promise<FileAttachmentRef>;
 //# sourceMappingURL=admission.d.ts.map

package/lib/types/admission.js

@@ -2,13 +2,16 @@
 import { Buffer } from 'node:buffer';
 import { AttachmentError } from "./error.js";
 /** Decode one upload payload while rejecting non-canonical base64 forms. */
-function decodeBase64(data) {
+function decodeCanonicalBase64(data, empty, code) {
     const decoded = Buffer.from(data, 'base64');
-    if (data.length === 0 || decoded.toString('base64') !== data) {
-        throw new AttachmentError('Image upload is not canonical base64.', 'INVALID_IMAGE_BASE64');
+    if ((data.length === 0 && empty === 'reject') || decoded.toString('base64') !== data) {
+        throw new AttachmentError(code === 'INVALID_IMAGE_BASE64' ? 'Image upload is not canonical base64.' : 'File upload is not canonical base64.', code);
     }
     return new Uint8Array(decoded);
 }
+function decodeBase64(data) {
+    return decodeCanonicalBase64(data, 'reject', 'INVALID_IMAGE_BASE64');
+}
 /** Store input for one decoded upload. */
 function saveInput(image) {
     return {
@@ -31,22 +34,19 @@ export async function admitEncodedImages(attachments, images) {
     return attachments.saveImages(images.map(saveInput));
 }
 /**
- * Admit one browser prompt and replace each uploaded image with its durable reference.
- * Text-only prompts do not access the attachment store.
- * @param attachments - the deployment attachment store owning batch policy.
- * @param content - browser prompt parts in message order.
- * @returns admitted prompt parts in the same order as `content`.
- * @throws AttachmentError when the image batch is refused.
+ * Admit one wire file upload: enforce canonical base64 (an empty file is a
+ * valid zero-byte payload), then delegate verbatim commit to
+ * {@link AttachmentStore.saveFile}. The shared entry for every RPC endpoint
+ * accepting browser file uploads.
+ * @param attachments - the deployment attachment store.
+ * @param file - base64-encoded upload and optional display name.
+ * @returns the durable content-addressed file reference.
+ * @throws AttachmentError on a non-canonical payload or a storage failure.
  */
-export async function admitPromptContent(attachments, content) {
-    if (content.every(part => part.type === 'text')) {
-        return content.map(part => ({ type: 'text', text: part.text }));
-    }
-    const refs = await admitEncodedImages(attachments, content.filter(part => part.type === 'image'));
-    let next = 0;
-    return content.map(part => part.type === 'text'
-        ? { type: 'text', text: part.text }
-        // admitEncodedImages returns one reference per image part in order.
-        : { type: 'image', attachment: refs[next++] });
+export async function admitEncodedFile(attachments, file) {
+    return attachments.saveFile({
+        data: decodeCanonicalBase64(file.data, 'accept', 'INVALID_FILE_BASE64'),
+        ...file.name === undefined ? {} : { name: file.name },
+    });
 }
 //# sourceMappingURL=admission.js.map

package/lib/types/error.d.ts

@@ -2,8 +2,9 @@
 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", "IMAGE_DIMENSION_TOO_LARGE"];
 /** Caller-correctable attachment failure codes raised while admitting image input. */
 export type ImageAdmissionErrorCode = typeof IMAGE_ADMISSION_ERROR_CODES[number];
+declare const ATTACHMENT_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", "IMAGE_DIMENSION_TOO_LARGE", "INVALID_FILE_BASE64", "INVALID_ATTACHMENT_REF", "ATTACHMENT_CORRUPT", "ATTACHMENT_WRITE_FAILED", "ATTACHMENT_NOT_FOUND", "ATTACHMENT_READ_FAILED", "ATTACHMENT_PROJECTION_UNSUPPORTED", "ATTACHMENT_FILES_UNSUPPORTED"];
 /** 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' | 'ATTACHMENT_PROJECTION_UNSUPPORTED';
+export type AttachmentErrorCode = typeof ATTACHMENT_ERROR_CODES[number];
 /**
  * Stable failures suitable for host RPC error mapping.
  *
@@ -23,6 +24,12 @@ export declare class AttachmentError extends Error {
      */
     constructor(message: string, code: AttachmentErrorCode, options?: ErrorOptions);
 }
+/**
+ * Identify attachment failures by their stable code across duplicate package installations.
+ * @param error - failure raised while validating, persisting, or reading an attachment.
+ * @returns whether the failure carries a recognized attachment error code.
+ */
+export declare function isAttachmentError(error: unknown): error is AttachmentError;
 /**
  * Distinguish caller-correctable image admission failures from storage faults.
  * @param error - failure raised while validating or persisting an image batch.

package/lib/types/error.js

@@ -10,8 +10,20 @@ const IMAGE_ADMISSION_ERROR_CODES = [
     'IMAGE_TOO_MANY_PIXELS',
     'IMAGE_DIMENSION_TOO_LARGE',
 ];
+const ATTACHMENT_ERROR_CODES = [
+    ...IMAGE_ADMISSION_ERROR_CODES,
+    'INVALID_FILE_BASE64',
+    'INVALID_ATTACHMENT_REF',
+    'ATTACHMENT_CORRUPT',
+    'ATTACHMENT_WRITE_FAILED',
+    'ATTACHMENT_NOT_FOUND',
+    'ATTACHMENT_READ_FAILED',
+    'ATTACHMENT_PROJECTION_UNSUPPORTED',
+    'ATTACHMENT_FILES_UNSUPPORTED',
+];
 /** Runtime membership for structurally compatible errors crossing package boundaries. */
 const IMAGE_ADMISSION_ERROR_CODE_SET = new Set(IMAGE_ADMISSION_ERROR_CODES);
+const ATTACHMENT_ERROR_CODE_SET = new Set(ATTACHMENT_ERROR_CODES);
 /**
  * Stable failures suitable for host RPC error mapping.
  *
@@ -35,6 +47,17 @@ export class AttachmentError extends Error {
         this.code = code;
     }
 }
+/**
+ * Identify attachment failures by their stable code across duplicate package installations.
+ * @param error - failure raised while validating, persisting, or reading an attachment.
+ * @returns whether the failure carries a recognized attachment error code.
+ */
+export function isAttachmentError(error) {
+    return error instanceof Error
+        && 'code' in error
+        && typeof error.code === 'string'
+        && ATTACHMENT_ERROR_CODE_SET.has(error.code);
+}
 /**
  * Distinguish caller-correctable image admission failures from storage faults.
  * @param error - failure raised while validating or persisting an image batch.

package/lib/types/index.d.ts

@@ -1,12 +1,13 @@
 /** Durable attachment storage seam (`ctx.attachments`). @module @deepseek-ai/dsh-attachment */
 import { Context, Service } from '@deepseek-ai/cordis';
-import type { ImageAttachmentLimits, ImageAttachmentRef, ImageRequestPolicy, RequestImageAttachment, SaveImageAttachment, StoredImageAttachment } from './types.ts';
+import { AttachmentError } from './error.ts';
+import type { AdmittedPromptContentPart, AttachmentAdmissionPart, EncodedFileAttachment, FileAttachmentRef, ImageAttachmentLimits, ImageAttachmentRef, ImageRequestPolicy, RequestImageAttachment, SaveFileAttachment, SaveFileStreamAttachment, SaveImageAttachment, StoredImageAttachment } from './types.ts';
 export { AttachmentId, ImageVariantId } from './brand.ts';
-export { AttachmentError, isImageAdmissionError } from './error.ts';
+export { AttachmentError, isAttachmentError, isImageAdmissionError } from './error.ts';
 export type { AttachmentErrorCode, ImageAdmissionErrorCode } from './error.ts';
-export { admitEncodedImages, admitPromptContent } from './admission.ts';
+export { admitEncodedFile, admitEncodedImages } from './admission.ts';
 export { requestImageDimensions } from './request-projection.ts';
-export type { AttachmentId as AttachmentIdType, AdmittedPromptContentPart, EncodedImageAttachment, ImageAttachmentLimits, ImageAttachmentRef, ImageRequestPolicy, ImageMediaType, PromptContentPart, RequestImageAttachment, SaveImageAttachment, StoredImageAttachment, } from './types.ts';
+export type { AttachmentId as AttachmentIdType, AdmittedPromptContentPart, AttachmentAdmissionPart, EncodedFileAttachment, EncodedImageAttachment, FileAttachmentRef, ImageAttachmentLimits, ImageAttachmentRef, ImageRequestPolicy, ImageMediaType, PromptContentPart, RequestImageAttachment, SaveFileAttachment, SaveFileStreamAttachment, SaveImageAttachment, StoredImageAttachment, } from './types.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         attachments: AttachmentStore;
@@ -39,6 +40,27 @@ export declare abstract class AttachmentStore extends Service {
      * @returns durable normalized attachment references in the same order after every member succeeds.
      */
     saveImages(inputs: readonly SaveImageAttachment[]): Promise<readonly ImageAttachmentRef[]>;
+    /**
+     * Admit one Host prompt and replace each uploaded image with its durable reference.
+     * Text and durable file references pass through unchanged. A prompt without image parts performs no storage operation.
+     * @param content - prompt parts in message order after file receipt resolution.
+     * @returns admitted prompt parts in the same order as `content`.
+     * @throws AttachmentError when the image batch is refused.
+     */
+    admitPromptContent(content: readonly AttachmentAdmissionPart[]): Promise<AdmittedPromptContentPart[]>;
+    /**
+     * Decode and durably commit one canonical base64 file upload.
+     * @param input - canonical base64 bytes and optional display name.
+     * @returns the durable content-addressed file reference.
+     * @throws AttachmentError when the encoding or storage operation is refused.
+     */
+    admitEncodedFile(input: EncodedFileAttachment): Promise<FileAttachmentRef>;
+    /**
+     * Identify a failure emitted by this attachment capability by its stable code.
+     * @param error - value caught from an attachment operation.
+     * @returns whether the value is an attachment failure.
+     */
+    isAttachmentError(error: unknown): error is AttachmentError;
     /**
      * Validate and durably commit one image before its owning session event is appended.
      * The returned reference describes the persisted normalized image. When
@@ -63,6 +85,39 @@ export declare abstract class AttachmentStore extends Service {
      * @throws an AttachmentError when the durable reference is invalid.
      */
     imageHostPath(ref: ImageAttachmentRef): string | undefined;
+    /**
+     * Durably commit one file byte-for-byte before its owning session event is
+     * appended. Files carry no admission limits: any byte content and length is
+     * accepted, and the stored object is the exact submitted bytes. Backends
+     * without verbatim file storage keep this default rejection.
+     * @param input - exact bytes and optional display name.
+     * @returns the durable content-addressed file reference.
+     */
+    saveFile(input: SaveFileAttachment): Promise<FileAttachmentRef>;
+    /**
+     * Durably commit one file byte-for-byte from bounded chunks. Providers must
+     * apply backpressure and must not collect the complete file in memory.
+     * Backends without streamed verbatim storage keep this default rejection.
+     * @param input - ordered exact bytes, optional cancellation, and display name.
+     * @returns the durable content-addressed file reference.
+     */
+    saveFileStream(input: SaveFileStreamAttachment): Promise<FileAttachmentRef>;
+    /**
+     * Read and verify one verbatim stored file as bounded chunks. Providers must
+     * not collect the complete file in memory. Backends without verbatim file
+     * reads keep this default rejection.
+     * @param ref - durable reference from the session log.
+     * @param signal - optional cancellation for backend reads and verification work.
+     * @returns exact file bytes in order; integrity failures reject the iteration.
+     */
+    readFileStream(ref: FileAttachmentRef, signal?: AbortSignal): AsyncIterable<Uint8Array>;
+    /**
+     * Locate the verbatim stored file object in the harness host filesystem.
+     * @param ref - durable file 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.
+     */
+    fileHostPath(ref: FileAttachmentRef): string | undefined;
     /**
      * Generate or read one deterministic model-request version from the stored normalized image.
      * @param ref - durable provider-independent normalized attachment reference.

package/lib/types/index.js

@@ -1,9 +1,10 @@
 /** Durable attachment storage seam (`ctx.attachments`). @module @deepseek-ai/dsh-attachment */
 import { Service } from '@deepseek-ai/cordis';
-import { AttachmentError } from "./error.js";
+import { admitEncodedFile as admitFileInput, admitEncodedImages } from "./admission.js";
+import { AttachmentError, isAttachmentError as matchesAttachmentError } from "./error.js";
 export { AttachmentId, ImageVariantId } from "./brand.js";
-export { AttachmentError, isImageAdmissionError } from "./error.js";
-export { admitEncodedImages, admitPromptContent } from "./admission.js";
+export { AttachmentError, isAttachmentError, isImageAdmissionError } from "./error.js";
+export { admitEncodedFile, 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 {
@@ -47,6 +48,46 @@ export class AttachmentStore extends Service {
             refs.push(await this.saveImage(input));
         return refs;
     }
+    /**
+     * Admit one Host prompt and replace each uploaded image with its durable reference.
+     * Text and durable file references pass through unchanged. A prompt without image parts performs no storage operation.
+     * @param content - prompt parts in message order after file receipt resolution.
+     * @returns admitted prompt parts in the same order as `content`.
+     * @throws AttachmentError when the image batch is refused.
+     */
+    async admitPromptContent(content) {
+        if (content.every(part => part.type !== 'image')) {
+            return content.map(part => part.type === 'text'
+                ? { type: 'text', text: part.text }
+                : { type: 'file', attachment: part.attachment });
+        }
+        const refs = await admitEncodedImages(this, content.filter(part => part.type === 'image'));
+        let next = 0;
+        return content.map((part) => {
+            if (part.type === 'text')
+                return { type: 'text', text: part.text };
+            if (part.type === 'file')
+                return { type: 'file', attachment: part.attachment };
+            return { type: 'image', attachment: refs[next++] };
+        });
+    }
+    /**
+     * Decode and durably commit one canonical base64 file upload.
+     * @param input - canonical base64 bytes and optional display name.
+     * @returns the durable content-addressed file reference.
+     * @throws AttachmentError when the encoding or storage operation is refused.
+     */
+    admitEncodedFile(input) {
+        return admitFileInput(this, input);
+    }
+    /**
+     * Identify a failure emitted by this attachment capability by its stable code.
+     * @param error - value caught from an attachment operation.
+     * @returns whether the value is an attachment failure.
+     */
+    isAttachmentError(error) {
+        return matchesAttachmentError(error);
+    }
     /**
      * Locate the provider-owned normalized object in the harness host filesystem.
      * @param ref - durable normalized attachment reference.
@@ -57,6 +98,52 @@ export class AttachmentStore extends Service {
         void ref;
         return undefined;
     }
+    /**
+     * Durably commit one file byte-for-byte before its owning session event is
+     * appended. Files carry no admission limits: any byte content and length is
+     * accepted, and the stored object is the exact submitted bytes. Backends
+     * without verbatim file storage keep this default rejection.
+     * @param input - exact bytes and optional display name.
+     * @returns the durable content-addressed file reference.
+     */
+    saveFile(input) {
+        void input;
+        return Promise.reject(new AttachmentError('The mounted attachment provider cannot store verbatim files.', 'ATTACHMENT_FILES_UNSUPPORTED'));
+    }
+    /**
+     * Durably commit one file byte-for-byte from bounded chunks. Providers must
+     * apply backpressure and must not collect the complete file in memory.
+     * Backends without streamed verbatim storage keep this default rejection.
+     * @param input - ordered exact bytes, optional cancellation, and display name.
+     * @returns the durable content-addressed file reference.
+     */
+    saveFileStream(input) {
+        void input;
+        return Promise.reject(new AttachmentError('The mounted attachment provider cannot stream verbatim files.', 'ATTACHMENT_FILES_UNSUPPORTED'));
+    }
+    /**
+     * Read and verify one verbatim stored file as bounded chunks. Providers must
+     * not collect the complete file in memory. Backends without verbatim file
+     * reads keep this default rejection.
+     * @param ref - durable reference from the session log.
+     * @param signal - optional cancellation for backend reads and verification work.
+     * @returns exact file bytes in order; integrity failures reject the iteration.
+     */
+    async *readFileStream(ref, signal) {
+        signal?.throwIfAborted();
+        void ref;
+        await Promise.reject(new AttachmentError('The mounted attachment provider cannot read verbatim files.', 'ATTACHMENT_FILES_UNSUPPORTED'));
+    }
+    /**
+     * Locate the verbatim stored file object in the harness host filesystem.
+     * @param ref - durable file 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.
+     */
+    fileHostPath(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.

package/lib/types/types.d.ts

@@ -26,6 +26,41 @@ export interface ImageAttachmentRef {
         height: number;
     };
 }
+/**
+ * Durable, serializable reference to one verbatim stored file. Files are
+ * stored byte-for-byte with no normalization; `attachmentId` is the sha256
+ * digest of exactly those bytes.
+ */
+export interface FileAttachmentRef {
+    /** Opaque content-addressed storage identifier; never a filesystem path or bearer URL. */
+    attachmentId: AttachmentId;
+    /** Sanitized display filename, also the stored object's leaf name. */
+    name: string;
+    /** Exact byte length. */
+    bytes: number;
+}
+/** Base64-encoded file upload accompanying one wire request. */
+export interface EncodedFileAttachment {
+    /** Canonical base64 encoding of the file bytes. */
+    data: string;
+    /** Optional display name; it is never interpreted as a path. */
+    name?: string;
+}
+/** Request to durably commit one file verbatim. */
+export interface SaveFileAttachment {
+    data: Uint8Array;
+    /** Optional browser/provider display name; it is never interpreted as a path. */
+    name?: string;
+}
+/** Request to durably commit one file from bounded byte chunks. */
+export interface SaveFileStreamAttachment {
+    /** Exact file bytes in order; providers must not retain the complete sequence in memory. */
+    data: AsyncIterable<Uint8Array>;
+    /** Optional cancellation for source reads and storage writes. */
+    signal?: AbortSignal;
+    /** Optional browser/provider display name; it is never interpreted as a path. */
+    name?: string;
+}
 /** Deployment-resolved limits used by upload admission and request buffering. */
 export interface ImageAttachmentLimits {
     maxImageBytes: number;
@@ -48,7 +83,7 @@ export interface EncodedImageAttachment {
 /**
  * Browser-submitted prompt content accepted by Host prompt endpoints; the
  * accepting Host promotes image parts to durable references through
- * `admitPromptContent` before any message is created, so a wire caller can
+ * `ctx.attachments.admitPromptContent()` before any message is created, so a wire caller can
  * never cite an attachment it did not upload.
  */
 export type PromptContentPart = {
@@ -60,13 +95,21 @@ export type PromptContentPart = {
     readonly data: string;
     readonly name?: string;
 };
-/** Host-admitted prompt content with each uploaded image replaced by its durable reference. */
+/** Host prompt content whose file receipts are resolved and whose image bytes await admission. */
+export type AttachmentAdmissionPart = PromptContentPart | {
+    readonly type: 'file';
+    readonly attachment: FileAttachmentRef;
+};
+/** Host-admitted prompt content with every attachment represented by its durable reference. */
 export type AdmittedPromptContentPart = {
     readonly type: 'text';
     readonly text: string;
 } | {
     readonly type: 'image';
     readonly attachment: ImageAttachmentRef;
+} | {
+    readonly type: 'file';
+    readonly attachment: FileAttachmentRef;
 };
 /** Request to validate and durably commit one image. */
 export interface SaveImageAttachment {

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.2-alpha.5",
+  "version": "0.1.3-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -33,10 +33,10 @@
   "license": "MIT",
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-brand": "^0.1.2-alpha.5"
+    "@deepseek-ai/dsh-brand": "^0.1.3-alpha.2"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-brand": "^0.1.2-alpha.5"
+    "@deepseek-ai/dsh-brand": "^0.1.3-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2"
   }
 }