@deepseek-ai/dsh-fs 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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/fs/fs/README.md
+README.md: 62d3febde82e013ace054a9e6242147c1756b0d1
+README.zh.md: 137c1e8da1014bf7dda7c4bf2e667aca6d2f51b5

package/README.md

@@ -0,0 +1,65 @@
+# @deepseek-ai/dsh-fs
+
+English | [中文](README.zh.md)
+
+The **`FileSystem`** (`ctx.fs`) defines the storage primitives in one execution world — resolve paths, expose canonical process paths and file URIs, test containment, read whole or streaming text, inspect/list metadata, write atomically, and apply a literal edit — without saying HOW. Both mutations take their version guard **optionally**, so `ctx.fs` on its own is a complete, unconstrained text-storage seam. This package also owns the `fs/*` policy event vocabulary the tool dispatches and the policy plugin listens for.
+
+This package owns the Service Definition and provider contract layer of the four-layer filesystem stack, split so each concern can evolve (and be swapped) independently (see [the capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md), [the filesystem capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md), [the split-the-filesystem-seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md), and [the file-context event-gate Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)):
+
+| Layer | Package | Role |
+|---|---|---|
+| tool / executor | `@deepseek-ai/dsh-tool-fs` | model-facing `read`/`write`/`edit` schemas + read windowing + text rendering; reads/writes/edits via `ctx.fs`, dispatches the `fs/*` events |
+| policy | `@deepseek-ai/dsh-fs-policy` | observed-state + read-before-edit + version-guarded write/edit, contributed through the `fs/*` event gate (no service) |
+| provider contract | `@deepseek-ai/dsh-fs` (this) | `ctx.fs`: execution-world paths, text IO, and atomic mutation primitives (optional version guard); owns the `fs/*` event vocabulary |
+| provider | `@deepseek-ai/dsh-fs-local` | the host-filesystem implementation |
+
+`fs-sandbox` and `fs-e2b` implement this interface without touching the policy/tool layers.
+
+## Service API (`ctx.fs`)
+
+A backend subclasses `FileSystem` and implements eleven primitives.
+
+| Member | Semantics |
+|---|---|
+| `resolve(path, opts?)` | Resolve a path into a stable `FsTarget` (opaque `targetKey`, `displayPath`). `opts.cwd` is the base a relative `path` resolves against (a caller supplies its session workspace; absolute paths ignore it; omitted ⇒ the backend default), while `opts.signal` aborts a backend round-trip. Async — a remote backend may need I/O. The same file via different paths must yield the same `targetKey`. |
+| `processPath(target)` | Return the canonical absolute path that a subprocess in this provider's execution world can open. This is intentionally distinct from opaque `targetKey`. |
+| `fileUrl(target)` | Return the canonical `file:` URI in the execution world's platform syntax. The backend, not the host process, owns encoding. |
+| `contains(parent, child)` | Test canonical identity/descendant containment without exposing or parsing target keys. Both targets come from this provider. |
+| `stat(target, signal?)` | Return `FsInfo` metadata (`version`, `type`, optional `size`), or `undefined` when the target is absent. Never content. |
+| `lstat(path, opts?, signal?)` | Return `FsPathInfo` metadata without following the final path component when it is a symlink. This is path-shaped so consumers can reject repository-owned symlinks before `resolve` follows them into a target. |
+| `readText(target, signal?)` | Read the whole regular text file as one decoded string. Owns regular-file checks, UTF-8 decoding, binary/NUL rejection (`FS_NOT_TEXT`). |
+| `streamText(target, signal?)` | Stream the same text as decoded chunks for large files (cross-chunk UTF-8 decoding stays here); consumers that need a byte ceiling enforce it while consuming the stream. |
+| `listDir(target, signal?)` | List direct directory children in stable name order. Returns entry names, entry types, resolved child targets, and cheap metadata (`version`/file `size` when available); never reads file contents. Missing targets throw `FS_NOT_FOUND`, non-directories throw `FS_NOT_DIRECTORY`, permission failures throw `FS_PERMISSION_DENIED`, and other backend I/O failures throw `FS_IO_ERROR`. Broken/disappeared children may be returned as `other` without metadata; child permission/IO failures fail the whole listing with the same structured codes. |
+| `writeText(target, content, expected?, signal?)` | Atomic create/replace. `expected` is OPTIONAL: omit ⇒ unconditional create-or-overwrite; supply an `FsWriteIntent` (`createIfAbsent`/`replaceIfVersion`) to guard. `createIfAbsent` must perform a no-replace publication so a creator racing the initial probe is preserved. |
+| `editText(target, edit, expected?, signal?)` | Literal edit. `expected` is OPTIONAL: omit ⇒ unconditional edit of the current content; supply `{ version }` to guard (verified BEFORE matching). A missing target reports `FS_STALE_VERSION` either way. Applies and writes atomically — one mutation critical section. |
+
+The mutation runs inside the backend's per-target lock either way, so an unconditional write/edit is still atomic — "unconditional" drops the *version* precondition, not the atomicity.
+
+## The `fs/*` policy events
+
+This package declares three events (see the generated region of [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface)) so the emitter (`@deepseek-ai/dsh-tool-fs`) and the policy listener (`@deepseek-ai/dsh-fs-policy`) share a vocabulary without the emitter depending on the policy plugin. `fs/write-intent` and `fs/edit-intent` are single-slot decision waterfalls (the listener fully decides, never calling `next()`); `fs/observed` is a fire-and-forget recording event carrying an `FsObservation` discriminated union: present with a version or confirmed absent. They carry only `dsh-fs` vocabulary plus an opaque `object` actor — no model-facing concepts and no agent/session owner structure.
+
+## A provider contract, not the policy layer
+
+`ctx.fs` is deliberately close to fsspec-style storage primitives — half a level above byte-level `cat`/`open`, because it decodes text and rejects binaries so the policy layer never touches raw bytes. It owns UTF-8 decoding, binary rejection, atomic writes, and the literal-edit critical section. It does **not** own line windows, numbered lines, rendered footers, or observed-state. Observed-state, read-before-edit, and version-guarded write/edit are policy a plugin (`@deepseek-ai/dsh-fs-policy`) ADDS by supplying the optional guard — not provider behavior — so a sandboxed/remote backend inherits no model-facing observation policy.
+
+`editText` stays on this seam (not composed in the policy layer from a read plus a write) because version guard + literal match + atomic rewrite must stay inside one critical section for correct error attribution and one-wins/one-stale concurrency, and a remote backend may implement it as a native compare-and-edit.
+
+## Vocabulary
+
+`FsTargetKey` / `FsVersion` are branded opaque ids ([the branded-ids Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-branded-ids.md)) — consumers must not parse `targetKey` or interpret `version`; only `displayPath` is for model/UI output. `FsObservation` distinguishes `{ kind: 'present', version }` from `{ kind: 'absent' }`, so a policy can separate an unseen target from confirmed absence without performing I/O. `FsWriteIntent` is the explicit GUARDED write intent (`createIfAbsent` creates a missing target and rejects an existing one with `FS_NOT_OBSERVED`; `replaceIfVersion` replaces only at the observed version, else `FS_STALE_VERSION`); omitting it from `writeText` is the third, unconditional state. `FsPathInfo` is the no-follow metadata shape that can report `symlink`, unlike target-level `FsInfo`. Failures throw `FsError` (extends `HarnessError`, [the structured error taxonomy Agent Note](../../../.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md)) carrying a stable `FsErrorCode` (`FS_NOT_FOUND`, `FS_NOT_DIRECTORY`, `FS_NOT_TEXT`, `FS_NOT_REGULAR_FILE`, `FS_PERMISSION_DENIED`, `FS_IO_ERROR`, `FS_STALE_VERSION`, `FS_NOT_OBSERVED`, `FS_AMBIGUOUS_EDIT`, `FS_EDIT_NOT_FOUND`, `FS_ABORTED`); the tool registry surfaces `{ name, code }` on `isError` results. See `src/types.ts` for the full contracts.
+
+## Model Experience
+
+Indirectly, through `dsh-tool-fs`, which renders provider text and errors as bounded, retained filesystem tool results.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **Text-only by contract** — backends reject binary/non-UTF-8 content with `FS_NOT_TEXT`; binary-safe operations are a deliberate deferral of [the tool-schemas Agent Note](../../../.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md).
+- **Eleven primitives only** — no delete, rename/move, copy, or watch; `listDir` is single-level, with recursion, globbing, pagination, and search out of scope per [the directory-listing Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md).
+- **No IO deadline** — the seam arms no timeout; cancellation is a best-effort optional `AbortSignal` per primitive (the deliberate [fs-family stance](../README.md)).
+- **Resolve-then-operate costs a remote backend two round-trips per tool call** — folding or caching resolution is left to such a backend.

package/README.zh.md

@@ -0,0 +1,65 @@
+# @deepseek-ai/dsh-fs
+
+[English](README.md) | 中文
+
+**`FileSystem`**（`ctx.fs`）定义同一个执行世界中的存储原语，包括解析路径、公开规范化进程路径与文件 URI、检查包含关系、完整或流式读取文本、检查／列出元数据、原子写入和应用字面量编辑，但不规定实现方式。两个变更操作都**可选** 接收版本防护，因此 `ctx.fs` 本身就是完整且不受约束的文本存储 seam。本包还拥有由工具分派、政策插件监听的 `fs/*` 政策事件词汇。
+
+本包是四层文件系统栈中的提供方约定层；该拆分使每个关注点可以独立演进和替换（见[能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)、[文件系统能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md)、[拆分文件系统 seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md)和[文件上下文事件门禁 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)）：
+
+| 层 | 包 | 角色 |
+|---|---|---|
+| 工具/执行器 | `@deepseek-ai/dsh-tool-fs` | 面向模型的 `read`/`write`/`edit` schema、读取窗口和文本渲染；通过 `ctx.fs` 读取/写入/编辑，并分派 `fs/*` 事件 |
+| 政策 | `@deepseek-ai/dsh-fs-policy` | 已观察状态、编辑前读取和版本防护的写入/编辑，通过 `fs/*` 事件门禁贡献（无服务） |
+| 提供方约定 | `@deepseek-ai/dsh-fs`（本包） | `ctx.fs`：执行世界路径、文本 I/O 与原子变更原语（可选版本防护）；拥有 `fs/*` 事件词汇 |
+| 提供方 | `@deepseek-ai/dsh-fs-local` | 宿主文件系统实现 |
+
+`fs-sandbox` 与 `fs-e2b` 实现该接口，无需更改政策层和工具层。
+
+## 服务 API（`ctx.fs`）
+
+后端继承 `FileSystem` 并实现十一个原语。
+
+| 成员 | 语义 |
+|---|---|
+| `resolve(path, opts?)` | 把路径解析为稳定的 `FsTarget`（不透明 `targetKey`、`displayPath`）。`opts.cwd` 是相对 `path` 解析所依据的基准（调用方提供其会话工作区；绝对路径忽略该值；省略时使用后端默认值），`opts.signal` 则中止后端往返。该方法是异步的，因为远程后端可能需要 I/O。经不同路径到达的同一文件必须产生相同 `targetKey`。 |
+| `processPath(target)` | 返回该提供方执行世界中的子进程可以打开的规范化绝对路径。该路径有意与不透明的 `targetKey` 分离。 |
+| `fileUrl(target)` | 返回采用执行世界平台语法的规范化 `file:` URI。编码由后端而非宿主进程负责。 |
+| `contains(parent, child)` | 在不公开或解析目标 key 的情况下，检查规范化身份相等或后代包含关系。两个目标都来自该提供方。 |
+| `stat(target, signal?)` | 返回 `FsInfo` 元数据（`version`、`type`、可选 `size`）；目标不存在时返回 `undefined`。绝不返回内容。 |
+| `lstat(path, opts?, signal?)` | 当最后一个路径组件是符号链接时，不跟随该组件，返回 `FsPathInfo` 元数据。该方法采用路径形态，使消费方能在 `resolve` 跟随仓库所有的符号链接进入目标前拒绝它。 |
+| `readText(target, signal?)` | 把整个普通文本文件读取为一个解码后的字符串。负责普通文件检查、UTF-8 解码和二进制/NUL 拒绝（`FS_NOT_TEXT`）。 |
+| `streamText(target, signal?)` | 为大文件按解码后的分片流式读取相同文本（跨分片 UTF-8 解码仍由此处负责）；需要字节上限的消费方在消费流时执行该上限。 |
+| `listDir(target, signal?)` | 按稳定名称顺序列出直接子项。返回条目名称、条目类型、解析后的子目标和低成本元数据（若可用则包括 `version`/文件 `size`）；绝不读取文件内容。缺失目标抛出 `FS_NOT_FOUND`，非目录抛出 `FS_NOT_DIRECTORY`，权限失败抛出 `FS_PERMISSION_DENIED`，其他后端 I/O 失败抛出 `FS_IO_ERROR`。损坏/消失的子项可以作为无元数据的 `other` 返回；子项权限/I/O 失败会使用相同结构化代码使整个列表失败。 |
+| `writeText(target, content, expected?, signal?)` | 原子创建/替换。`expected` 是可选的：省略 ⇒ 无条件创建或覆盖；提供 `FsWriteIntent`（`createIfAbsent`/`replaceIfVersion`）⇒ 添加防护。`createIfAbsent` 必须以不替换的方式发布，使初始探测后抢先创建的文件得到保留。 |
+| `editText(target, edit, expected?, signal?)` | 字面量编辑。`expected` 是可选的：省略 ⇒ 无条件编辑当前内容；提供 `{ version }` ⇒ 添加防护，并在匹配之前校验。无论哪种情况，目标缺失都报告 `FS_STALE_VERSION`。应用和写入以原子方式完成，使用同一个变更临界区。 |
+
+无论是否有版本防护，变更都在后端的每目标锁内运行，因此无条件写入/编辑仍是原子的；「无条件」只移除*版本*前置条件，不移除原子性。
+
+## `fs/*` 政策事件
+
+本包声明三个事件（见 [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface) 的生成区块），使发出方（`@deepseek-ai/dsh-tool-fs`）和政策监听器（`@deepseek-ai/dsh-fs-policy`）共享词汇，而无需让发出方依赖政策插件。`fs/write-intent` 和 `fs/edit-intent` 是单槽决策 waterfall（监听器完整决策，绝不调用 `next()`）；`fs/observed` 是发后即忘的记录事件，携带 `FsObservation` 可辨识联合：存在并带有版本，或确认缺失。它们只携带 `dsh-fs` 词汇和一个不透明 `object` 参与者，不含面向模型的概念或 agent（智能体）/会话所有者结构。
+
+## 提供方约定，不是政策层
+
+`ctx.fs` 有意接近 fsspec 风格的存储原语，比字节级 `cat`/`open` 高半层，因为它会解码文本并拒绝二进制，使政策层绝不接触原始字节。它负责 UTF-8 解码、二进制拒绝、原子写入和字面量编辑临界区。它**不** 负责行窗口、编号行、渲染 footer 或已观察状态。已观察状态、编辑前读取和版本防护的写入/编辑属于插件（`@deepseek-ai/dsh-fs-policy`）通过提供可选防护而添加的政策，并非提供方行为，因此沙箱化/远程后端不会继承任何面向模型的观察政策。
+
+`editText` 留在该 seam 上，不由政策层通过读取加写入组合，因为版本防护、字面量匹配和原子重写必须处于同一临界区内，才能正确归因错误并实现一方胜出/一方陈旧的并发；远程后端也可以将其实现为原生比较并编辑操作。
+
+## 词汇
+
+`FsTargetKey` / `FsVersion` 是带品牌的不透明 id（见[品牌 id Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-branded-ids.md)）；消费方不得解析 `targetKey` 或解释 `version`，只有 `displayPath` 用于模型/UI 输出。`FsObservation` 区分 `{ kind: 'present', version }` 与 `{ kind: 'absent' }`，使策略无需执行 I/O 即可分辨未见目标和确认缺失。`FsWriteIntent` 是显式的防护写入意图（`createIfAbsent` 创建缺失目标，并以 `FS_NOT_OBSERVED` 拒绝现有目标；`replaceIfVersion` 只在观察版本上替换，否则为 `FS_STALE_VERSION`）；从 `writeText` 中省略该值就是第三种无条件状态。`FsPathInfo` 是可报告 `symlink` 的不跟随链接元数据形态，区别于目标级 `FsInfo`。失败会抛出 `FsError`（继承 `HarnessError`；见[结构化错误分类 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md)），并携带稳定的 `FsErrorCode`（`FS_NOT_FOUND`、`FS_NOT_DIRECTORY`、`FS_NOT_TEXT`、`FS_NOT_REGULAR_FILE`、`FS_PERMISSION_DENIED`、`FS_IO_ERROR`、`FS_STALE_VERSION`、`FS_NOT_OBSERVED`、`FS_AMBIGUOUS_EDIT`、`FS_EDIT_NOT_FOUND`、`FS_ABORTED`）；工具注册表公开 `{ name, code }`，并将其附在 `isError` 结果上。完整约定见 `src/types.ts`。
+
+## 模型体验
+
+通过 `dsh-tool-fs` 间接产生影响；该消费方把提供方文本和错误渲染为有界且保留的文件系统工具结果。
+
+#### KV Cache 影响
+
+不会直接使缓存失效；具名消费方负责请求前缀的任何变化。
+
+## 已知限制与延期工作
+
+- **约定只支持文本**：后端以 `FS_NOT_TEXT` 拒绝二进制/非 UTF-8 内容；二进制安全操作是[工具 schema Agent Note](../../../.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md)有意延期的工作。
+- **只有十一个原语**：没有删除、重命名/移动、复制或监视；`listDir` 只支持一层，递归、glob、分页和搜索不在范围内，见[目录列出 Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)。
+- **没有 I/O deadline**：该 seam 不启动超时；取消只是每个原语上尽力而为的可选 `AbortSignal`（见有意采用的 [fs 能力族立场](../README.md)）。
+- **先解析后操作使远程后端每次工具调用需要两次往返**：折叠或缓存解析由这种后端自行决定。

package/lib/index.js

@@ -0,0 +1,77 @@
+import { Service } from "@deepseek-ai/cordis";
+import { HarnessError } from "@deepseek-ai/dsh-llm";
+//#region lib/types/types.js
+/**
+* Vocabulary for the filesystem Service Definition (`ctx.fs`): the opaque target/version
+* identities, the metadata `stat` returns, the write-intent and outcome shapes, the
+* literal-edit request/outcome, and the typed error taxonomy.
+* @module @deepseek-ai/dsh-fs/types
+*/
+/**
+* Brand a string as an {@link FsTargetKey}. For backend use only — a consumer
+* never manufactures a key, it receives one from `resolve()`.
+* @param key - the backend's raw key string (the local backend passes a realpath).
+* @returns the same string, branded; no validation is performed.
+*/
+function FsTargetKey(key) {
+	return key;
+}
+/**
+* Brand a string as an {@link FsVersion}. For backend use only — a consumer
+* never manufactures a version, it receives one from `stat`/write/edit outcomes.
+* @param v - the backend's raw version string.
+* @returns the same string, branded; no validation is performed.
+*/
+function FsVersion(v) {
+	return v;
+}
+/**
+* Typed filesystem error. Extends {@link HarnessError} so it carries a stable
+* {@link FsErrorCode} and chains `cause`. `dsh-fs` owns this vocabulary so
+* backends and the policy layer raise the same codes instead of each inventing
+* message strings.
+*/
+var FsError = class extends HarnessError {
+	code;
+	constructor(message, code, options) {
+		super(message, code, options);
+		this.code = code;
+	}
+};
+//#endregion
+//#region lib/types/index.js
+/**
+* Filesystem Service Definition for one execution world. Backends own stable target
+* identity, process paths and file URIs, containment, text reads, decoding,
+* binary rejection, and atomic mutations. Read windows and
+* observed-state policy stay in consumer and policy plugins; `editText`
+* remains here so version check, literal match, and rewrite share one critical
+* section.
+* @module @deepseek-ai/dsh-fs
+*/
+/**
+* Abstract filesystem provider. Targets must preserve identity across aliases;
+* reads expose regular UTF-8 text or typed errors, listings are stable and
+* content-free, and mutations are atomic. Optional guards add stale protection
+* without changing the unguarded provider contract.
+*/
+var FileSystem = class extends Service {
+	constructor(ctx) {
+		super(ctx, "fs");
+	}
+	/**
+	* The sandbox mode this backend enforces on mutations BY DEFAULT, or
+	* `undefined` when it does not confine at all — the capability fact the tool
+	* layer reads to advertise the escalation fields honestly (mirrors
+	* `BashExecutor.sandboxMode`). The base class and the bare local backend
+	* report `undefined`; a sandboxing backend (`@deepseek-ai/dsh-fs-sandbox`)
+	* overrides it with the deployment default. A session override may make the
+	* effective mode narrower or wider, so strict escalation widening is checked
+	* per call rather than encoded in this default-relative fact.
+	* @returns the configured default mode of a sandboxing backend; `undefined`
+	*   for a backend that never confines.
+	*/
+	get sandboxMode() {}
+};
+//#endregion
+export { FileSystem, FileSystem as default, FsError, FsTargetKey, FsVersion };

package/lib/invariant.js

@@ -0,0 +1,37 @@
+//#region lib/types/invariant.js
+/** Package-owned filesystem event-data invariants. @module @deepseek-ai/dsh-fs/invariant */
+const PACKAGE_NAME = "@deepseek-ai/dsh-fs";
+/** Cordis companion plugin name. */
+const name = "fs-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/** Assert that an event carries a usable opaque target identity. */
+function validateTarget(target, fail) {
+	if (target.targetKey.length === 0) fail("filesystem event targetKey must be non-empty");
+	if (target.displayPath.length === 0) fail("filesystem event displayPath must be non-empty");
+}
+/** Install checks over the filesystem decision and observation event stream. */
+const install = (ctx, fail) => {
+	ctx.on("internal/dispatch", (_mode, eventName, args) => {
+		if (eventName !== "fs/write-intent" && eventName !== "fs/edit-intent" && eventName !== "fs/observed") return;
+		validateTarget(args[0], fail);
+		if (eventName === "fs/observed") {
+			const observation = args[1];
+			switch (observation.kind) {
+				case "present":
+					if (observation.version.length === 0) fail("fs/observed present version must be non-empty");
+					break;
+				case "absent": break;
+				default: fail("fs/observed kind must be present or absent");
+			}
+		}
+	}, { global: true });
+};
+/**
+* Register the filesystem invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Filesystem Service Definition for one execution world. Backends own stable target
+ * identity, process paths and file URIs, containment, text reads, decoding,
+ * binary rejection, and atomic mutations. Read windows and
+ * observed-state policy stay in consumer and policy plugins; `editText`
+ * remains here so version check, literal match, and rewrite share one critical
+ * section.
+ * @module @deepseek-ai/dsh-fs
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox';
+import type { FsDirEntry, FsEditOutcome, FsEditRequest, FsInfo, FsPathInfo, FsObservation, FsTarget, FsVersion, FsWriteIntent, FsWriteOutcome } from './types.ts';
+export { FsError, FsTargetKey, FsVersion, } from './types.ts';
+export type { FsEditOutcome, FsEditRequest, FsDirEntry, FsErrorCode, FsInfo, FsObservation, FsPathInfo, FsTarget, FsWriteIntent, FsWriteOutcome, } from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        fs: FileSystem;
+    }
+    interface Events {
+        /**
+         * Single-slot decision for the next {@link FileSystem.writeText}. Calling
+         * `next()` yields the bare provider's unconditional write; the first listener
+         * that returns an intent owns the decision rather than composing with peers.
+         * @param target - the resolved target about to be written.
+         * @param actor - the opaque tool-execution context the decider keys off.
+         * @mode waterfall
+         */
+        'fs/write-intent'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>;
+        /**
+         * Single-slot decision for the next {@link FileSystem.editText}. Calling
+         * `next()` yields an unconditional edit; the first returned guard wins.
+         * @param target - the resolved target about to be edited.
+         * @param actor - the opaque tool-execution context the decider keys off.
+         * @mode waterfall
+         */
+        'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => {
+            version: FsVersion;
+        } | undefined | Promise<{
+            version: FsVersion;
+        } | undefined>): Promise<{
+            version: FsVersion;
+        } | undefined>;
+        /**
+         * Record an authoritative positive or negative observation. Listeners must
+         * be synchronous recorders: throws fail the tool call and returned promises
+         * are not awaited.
+         * @param target - the target whose presence or absence was observed.
+         * @param observation - present with its version, or confirmed absent.
+         * @param actor - the observing tool-execution context; undefined records nothing useful.
+         * @mode emit
+         */
+        'fs/observed'(target: FsTarget, observation: FsObservation, actor: object | undefined): void;
+    }
+}
+/**
+ * Abstract filesystem provider. Targets must preserve identity across aliases;
+ * reads expose regular UTF-8 text or typed errors, listings are stable and
+ * content-free, and mutations are atomic. Optional guards add stale protection
+ * without changing the unguarded provider contract.
+ */
+export declare abstract class FileSystem extends Service {
+    constructor(ctx: Context);
+    /**
+     * The sandbox mode this backend enforces on mutations BY DEFAULT, or
+     * `undefined` when it does not confine at all — the capability fact the tool
+     * layer reads to advertise the escalation fields honestly (mirrors
+     * `BashExecutor.sandboxMode`). The base class and the bare local backend
+     * report `undefined`; a sandboxing backend (`@deepseek-ai/dsh-fs-sandbox`)
+     * overrides it with the deployment default. A session override may make the
+     * effective mode narrower or wider, so strict escalation widening is checked
+     * per call rather than encoded in this default-relative fact.
+     * @returns the configured default mode of a sandboxing backend; `undefined`
+     *   for a backend that never confines.
+     */
+    get sandboxMode(): SandboxMode | undefined;
+    /**
+     * Resolve a model/plugin-supplied path into a stable {@link FsTarget}. May perform I/O (a
+     * remote/sandboxed backend may need a round-trip to map a path to a stable identity), hence
+     * async even though the local backend only normalizes + realpaths.
+     *
+     * @param path - the path to resolve; relative paths resolve against `opts.cwd`.
+     * @param opts - optional cwd override and cancellation signal.
+     * @returns the stable target; the same file yields the same `targetKey`.
+     */
+    abstract resolve(path: string, opts?: {
+        cwd?: string;
+        signal?: AbortSignal;
+    }): Promise<FsTarget>;
+    /**
+     * Return the canonical absolute path a subprocess in this filesystem's
+     * execution world can open. The path is deliberately separate from
+     * {@link FsTarget.targetKey}: consumers may pass this value to another OS
+     * capability, but must continue treating the target key as opaque.
+     * @param target - the resolved target whose process path is required.
+     * @returns an absolute path in the backend's execution world.
+     */
+    abstract processPath(target: FsTarget): string;
+    /**
+     * Return the canonical `file:` URI for a target in this filesystem's
+     * execution world. Backends own URI encoding because the host platform may
+     * differ from the execution platform.
+     * @param target - the resolved target to encode.
+     * @returns the target's canonical file URI.
+     */
+    abstract fileUrl(target: FsTarget): string;
+    /**
+     * Test canonical containment without exposing or parsing backend target
+     * keys. Both targets must come from this provider.
+     * @param parent - canonical directory target.
+     * @param child - canonical candidate target.
+     * @returns true when `child` is `parent` or a descendant of it.
+     */
+    abstract contains(parent: FsTarget, child: FsTarget): boolean;
+    /**
+     * Return target metadata, or `undefined` when the target does not exist.
+     * @param target - the resolved target to stat.
+     * @param signal - aborts the metadata round-trip.
+     * @returns metadata only, never content; undefined for an absent target.
+     */
+    abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>;
+    /**
+     * Return path metadata without following the final path component when it is a
+     * symbolic link. This is intentionally path-shaped, not target-shaped:
+     * {@link resolve} follows symlinks to produce the stable identity used by
+     * normal reads/writes, while `lstat` lets a consumer reject the path itself
+     * before that follow happens.
+     *
+     * `opts.cwd` follows {@link resolve}'s cwd rules. `undefined` means the path is
+     * absent.
+     * @param path - the path to inspect; relative paths resolve against `opts.cwd`.
+     * @param opts - `cwd` overrides the backend's default base for relative paths.
+     * @param signal - aborts the metadata round-trip.
+     * @returns metadata only, never content; undefined for an absent path.
+     */
+    abstract lstat(path: string, opts?: {
+        cwd?: string;
+    }, signal?: AbortSignal): Promise<FsPathInfo | undefined>;
+    /**
+     * Read the whole regular text file as a single decoded string.
+     * @param target - the resolved target to read.
+     * @param signal - aborts the read.
+     * @returns the full decoded UTF-8 content.
+     */
+    abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>;
+    /**
+     * Stream the whole regular text file as decoded text chunks (same text
+     * semantics as {@link readText}, for large files). The backend owns
+     * cross-chunk UTF-8 decoding and binary rejection so the policy layer never
+     * touches raw bytes.
+     * @param target - the resolved target to read.
+     * @param signal - aborts the stream, including between chunks.
+     * @returns the chunk iterable, decoded and validated like {@link readText}.
+     */
+    abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>;
+    /**
+     * List direct children of a directory in stable name order. Returns resolved
+     * child targets plus cheap metadata only; never reads file contents.
+     * @param target - the resolved directory target.
+     * @param signal - aborts the listing.
+     * @returns one entry per direct child, in stable name order.
+     */
+    abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>;
+    /**
+     * Atomically create or replace UTF-8 text. `expected` guards intent and
+     * staleness; omission allows unconditional overwrite.
+     * @param target - the resolved target to write.
+     * @param content - the full new file content.
+     * @param expected - the write intent guarding the write; omit for unconditional.
+     * @param signal - aborts before atomic publication takes effect.
+     * @param sandboxPolicy - the per-call mode and workspace root this write
+     *   runs under; a sandboxing backend fences the write by it, the bare backend
+     *   ignores it. Omit to leave the backend its own default.
+     * @returns the outcome, including the version the write produced.
+     */
+    abstract writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy): Promise<FsWriteOutcome>;
+    /**
+     * Atomically edit literal text. When supplied, the version guard is checked
+     * before matching so stale content reports `FS_STALE_VERSION`; omission edits
+     * the current content without a freshness precondition.
+     * @param target - the resolved target to edit.
+     * @param edit - the literal search/replace request.
+     * @param expected - the version guard; omit for an unconditional edit.
+     * @param signal - aborts before atomic publication takes effect.
+     * @param sandboxPolicy - the per-call mode and workspace root this edit runs
+     *   under; a sandboxing backend fences the edit by it, the bare backend
+     *   ignores it. Omit to leave the backend its own default.
+     * @returns the outcome, including the version the edit produced.
+     */
+    abstract editText(target: FsTarget, edit: FsEditRequest, expected?: {
+        version: FsVersion;
+    }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy): Promise<FsEditOutcome>;
+}
+export default FileSystem;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,13 @@
+/** Package-owned filesystem event-data invariants. @module @deepseek-ai/dsh-fs/invariant */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "fs-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register the filesystem invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Vocabulary for the filesystem Service Definition (`ctx.fs`): the opaque target/version
+ * identities, the metadata `stat` returns, the write-intent and outcome shapes, the
+ * literal-edit request/outcome, and the typed error taxonomy.
+ * @module @deepseek-ai/dsh-fs/types
+ */
+import { HarnessError } from '@deepseek-ai/dsh-llm';
+import type { Branded } from '@deepseek-ai/dsh-brand';
+/**
+ * Opaque key for stale guards and target lookup. The local backend uses a
+ * realpath-like string; a remote backend might use a workspace URI or file id.
+ * Consumers MUST NOT parse it or assume it is a local absolute path.
+ */
+export type FsTargetKey = Branded<'FsTargetKey'>;
+/**
+ * Brand a string as an {@link FsTargetKey}. For backend use only — a consumer
+ * never manufactures a key, it receives one from `resolve()`.
+ * @param key - the backend's raw key string (the local backend passes a realpath).
+ * @returns the same string, branded; no validation is performed.
+ */
+export declare function FsTargetKey(key: string): FsTargetKey;
+/**
+ * Opaque file-version token — the freshness token a write/edit guards against.
+ * The local backend derives it from high-resolution stat identity and freshness
+ * fields; a remote backend might use a revision id. The policy layer records it
+ * for stale checks; consumers may display related metadata but MUST NOT
+ * interpret this token.
+ */
+export type FsVersion = Branded<'FsVersion'>;
+/**
+ * Brand a string as an {@link FsVersion}. For backend use only — a consumer
+ * never manufactures a version, it receives one from `stat`/write/edit outcomes.
+ * @param v - the backend's raw version string.
+ * @returns the same string, branded; no validation is performed.
+ */
+export declare function FsVersion(v: string): FsVersion;
+/**
+ * One authoritative observation of a target. A present observation carries the
+ * version used by guarded replacement; an absent observation authorizes only a
+ * guarded create, never an edit.
+ */
+export type FsObservation = {
+    readonly kind: 'present';
+    readonly version: FsVersion;
+} | {
+    readonly kind: 'absent';
+};
+/**
+ * A path resolved by a backend into a stable identity. `resolve()` produces
+ * this; every other operation takes it.
+ */
+export interface FsTarget {
+    /** Opaque key for stale guards and target lookup. */
+    targetKey: FsTargetKey;
+    /**
+     * Path for model/UI-facing output. May be a local absolute path,
+     * workspace-relative path, or remote URI depending on the backend.
+     */
+    displayPath: string;
+}
+/**
+ * Metadata about a target — what {@link FileSystem.stat} returns. Lets the
+ * policy layer reject directories/special files before reading and choose
+ * `readText` vs `streamText` from `size` without probing by failure. `version`
+ * is the freshness token. `undefined` from `stat` means the target is absent.
+ */
+export interface FsInfo {
+    /** Opaque freshness token of the target right now. */
+    version: FsVersion;
+    /** Whether the target is a regular file, a directory, or something else. */
+    type: 'file' | 'directory' | 'other';
+    /** Byte size of a regular file, when the backend can report it. */
+    size?: number;
+}
+/**
+ * Metadata about a path without following the final path component when it is a
+ * symbolic link. Unlike {@link FsInfo}, this path-level probe can report
+ * `symlink` so consumers with trust-boundary rules can reject repository-owned
+ * links before resolving a target.
+ */
+export interface FsPathInfo {
+    /** Opaque freshness token of the path entry right now. */
+    version: FsVersion;
+    /** Whether the path entry is a regular file, directory, symlink, or other. */
+    type: 'file' | 'directory' | 'symlink' | 'other';
+    /** Byte size of the path entry, when the backend can report it. */
+    size?: number;
+}
+/**
+ * One direct child returned by {@link FileSystem.listDir}. Listing returns
+ * metadata and resolved targets only; it must not read file contents.
+ */
+export interface FsDirEntry {
+    /** Basename of the child inside the listed directory. */
+    name: string;
+    /** Whether the child is a regular file, a directory, or something else. */
+    type: 'file' | 'directory' | 'other';
+    /** Resolved child target for follow-up operations. */
+    target: FsTarget;
+    /** Opaque freshness token when the backend can report metadata cheaply. */
+    version?: FsVersion;
+    /** Byte size of a regular file, when the backend can report it. */
+    size?: number;
+}
+/**
+ * Guarded write intent. `createIfAbsent` rejects an existing target with
+ * `FS_NOT_OBSERVED`; `replaceIfVersion` rejects absence or mismatch with
+ * `FS_STALE_VERSION`. Omitting the intent from `writeText` means unconditional
+ * create-or-overwrite, not a third union arm.
+ */
+export type FsWriteIntent = {
+    kind: 'createIfAbsent';
+} | {
+    kind: 'replaceIfVersion';
+    version: FsVersion;
+};
+/** Outcome of a full-file write. */
+export interface FsWriteOutcome {
+    /** Whether the write created a new file or replaced an existing one. */
+    operation: 'create' | 'update';
+    /** Opaque version of the file after the write. */
+    version: FsVersion;
+    /**
+     * The file's content BEFORE the write, or `null` when the file did not exist
+     * (a create) or the backend declined a contextual basis (for example, a
+     * binary/non-UTF-8 prior file or either overwrite side reaching its exclusive limit).
+     * LF-normalized storage text (the diff basis), never a diff — a consumer
+     * computes the result-time contextual diff from `before`/`after` when
+     * `before` is present, else falls back to a whole-file diff.
+     */
+    before: string | null;
+    /** The file's content AFTER the write, LF-normalized to share `before`'s diff basis. */
+    after: string;
+}
+/** A literal-replacement edit request. */
+export interface FsEditRequest {
+    /** Literal non-empty text to replace. Must match exactly (after line-ending normalization). */
+    oldString: string;
+    /** Literal replacement text. An empty string deletes the matched text. */
+    newString: string;
+    /** Replace every match instead of requiring exactly one. */
+    replaceAll: boolean;
+}
+/** Outcome of a literal edit. */
+export interface FsEditOutcome {
+    /** Opaque version of the file after the edit. */
+    version: FsVersion;
+    /**
+     * The file's content BEFORE the edit. Raw storage text (LF-normalized by the
+     * backend), never a diff — a consumer computes the result-time contextual diff
+     * (the applied hunk with context) from `before`/`after`.
+     */
+    before: string;
+    /** The file's content AFTER the edit. */
+    after: string;
+}
+/**
+ * Stable, machine-routable codes for filesystem failures. Carried on
+ * {@link FsError}; the tool registry surfaces `{ name, code }` on `isError`
+ * results so retry/permission/UI layers can branch without parsing messages.
+ */
+export type FsErrorCode = 'FS_NOT_FOUND' | 'FS_NOT_DIRECTORY' | 'FS_NOT_TEXT' | 'FS_NOT_REGULAR_FILE' | 'FS_PERMISSION_DENIED' | 'FS_SANDBOX_DENIED' | 'FS_IO_ERROR' | 'FS_STALE_VERSION' | 'FS_NOT_OBSERVED' | 'FS_AMBIGUOUS_EDIT' | 'FS_EDIT_NOT_FOUND' | 'FS_ABORTED';
+/**
+ * Typed filesystem error. Extends {@link HarnessError} so it carries a stable
+ * {@link FsErrorCode} and chains `cause`. `dsh-fs` owns this vocabulary so
+ * backends and the policy layer raise the same codes instead of each inventing
+ * message strings.
+ */
+export declare class FsError extends HarnessError {
+    readonly code: FsErrorCode;
+    constructor(message: string, code: FsErrorCode, options?: ErrorOptions);
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@deepseek-ai/dsh-fs",
+  "description": "Abstract filesystem capability seam (ctx.fs) for the DeepSeek Harness — vocabulary types, the FileSystem service (text IO + optional version-guarded atomic mutations), and the fs/* policy event vocabulary",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/fs/fs"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-sandbox": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-sandbox": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}