@deepseek-ai/dsh-fs-local 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-local/README.md
+README.md: a3239905e3eebaae7fa3099122ee3a4ed91d3fe8
+README.zh.md: bbd9d2f66c4e582011bd0ea459e6c342eb653bda

package/README.md

@@ -0,0 +1,44 @@
+# @deepseek-ai/dsh-fs-local
+
+English | [中文](README.zh.md)
+
+The **local-filesystem implementation** of the `ctx.fs` provider contract ([`@deepseek-ai/dsh-fs`](../fs)). Backs the eleven `FileSystem` primitives with the host filesystem; loading it as a plugin populates `ctx.fs`.
+
+```ts ignore-check
+import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
+
+await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
+// ctx.fs uses the local backend; load @deepseek-ai/dsh-fs-policy for the
+// freshness policy gate and @deepseek-ai/dsh-tool-fs to expose read/write/edit.
+```
+
+## Behavior
+
+- **`resolve(path, opts?)`** — a relative `path` resolves against `opts.cwd` when the caller supplies one (the model-facing tools pass the calling agent's session cwd — see [the per-session cwd Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md)), else `config.cwd` (default `process.cwd()`); an absolute `path` ignores both. `opts.signal` is checked before and after local resolution, while a remote sibling backend may use it to abort its round-trip. The `targetKey` is the file's `realpath`, so two input paths reaching the same file through symlinks share one identity, and writes/edits land on the link target (preserving the link). A not-yet-existing path uses the realpathed parent directory plus basename when the parent exists; only an unresolvable parent falls back to the absolute path. `displayPath` is the absolute (un-resolved) path.
+- **Execution-world coordinates** — `processPath` exposes the target's canonical host path, `fileUrl` encodes that path through Node's platform-aware URL conversion, and `contains` uses platform path semantics to test identity or descendant containment without consumers parsing `targetKey`.
+- **`stat` / `lstat`** — return target metadata or `undefined` when absent. `stat` reports `FsInfo` for an already resolved target (`version` = an opaque token derived from bigint `dev:ino:size:mtimeNs:ctimeNs`, `type` of `file`/`directory`/`other`, byte `size`); path-shaped `lstat` reports `FsPathInfo` without following the final symlink and can therefore return `symlink`. Both check cancellation before and after their asynchronous metadata probe, so an abort that lands in flight reports `FS_ABORTED` rather than stale absence.
+- **`readText` / `streamText`** — UTF-8 only. `readText` reads the whole file; `streamText` decodes chunks so a huge file need not be held whole in memory and consumers can enforce their own retention bounds. Both reject invalid UTF-8 and NUL-byte binary samples (`FS_NOT_TEXT`) and non-regular targets. The `read` tool (`@deepseek-ai/dsh-tool-fs`) owns line windowing.
+- **`listDir`** — lists one directory level in stable `name.localeCompare()` order. Each entry carries the child basename, type, resolved child target (`displayPath` under the listed directory, `targetKey` as the realpath identity), and cheap stat metadata (`version`, plus `size` for regular files). It never opens or decodes file contents. Missing targets report `FS_NOT_FOUND`, file/special-file targets report `FS_NOT_DIRECTORY`, aborted calls report `FS_ABORTED`, permission failures report `FS_PERMISSION_DENIED`, and other listing or child metadata I/O failures report `FS_IO_ERROR`. Broken/disappeared children are returned as `other` without metadata, but permission/IO failures while resolving a child fail the whole listing with a structured `FsError`.
+- **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, then fsyncs and publishes. An existing file's mode is preserved, while new files default to `0o600`; on Windows a new file inherits the destination directory's DACL, while replacement copies the target DACL onto the empty temp before writing and publishes through `ReplaceFileW` so the original access policy survives ([Windows DACL preservation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` hard-links the staged file into place as an atomic no-replace publication, so a regular file created after the initial probe is preserved and rejected with `FS_NOT_OBSERVED`, while a non-regular path entry is preserved and rejected with `FS_NOT_REGULAR_FILE`; `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`). An overwrite returns the prior text as its contextual diff basis only when both the opened prior file and UTF-8 replacement are strictly below `config.diffBasisMaxBytes` (default 10 MiB). The descriptor read enforces that limit even if an external writer replaces or changes the file size after the initial probe. Otherwise the provider returns `before: null`, so presentation uses its whole-file fallback.
+- **`editText`** — atomic literal read-modify-write over the same primitive, serialized per target by a mutation lock. The `expected` guard is OPTIONAL: when supplied it verifies the version BEFORE literal matching (a stale edit reports `FS_STALE_VERSION`, never `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT` against newer content); omitting it edits the current content unconditionally. A missing target reports `FS_STALE_VERSION` either way. LF-normalizes for matching, restores the file's dominant CRLF/LF style, and rejects empty `oldString` / zero matches (`FS_EDIT_NOT_FOUND`) or ambiguous multi-matches without `replace_all` (`FS_AMBIGUOUS_EDIT`).
+
+The package-root SDK surface is the default/named `LocalFileSystem` class plus `Config`. Raw I/O lives in `src/fsio.ts` (Cordis-free, independently unit-tested); `src/index.ts` is the thin service wiring.
+
+## Model Experience
+
+Indirectly, through [`dsh-tool-fs`](../tool-fs/README.md), which renders this provider's line-windowed UTF-8 content, mutation acknowledgements, and exact provider messages in capped retained results while versions, atomic-write mechanics, and directory metadata remain internal.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **`config.cwd` is not a sandbox** — it is a resolution default, not containment: absolute paths and `..` escape it. Enforce containment with a stricter `ctx.fs` backend or a permission plugin on the `tools/execute` waterfall ([capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md#consequences)).
+- **Version tokens depend on filesystem metadata** — they combine device, inode, size, nanosecond mtime, and nanosecond ctime; a storage layer that cannot update any of those facts for a rewrite can still defeat the stale guard.
+- **`editText` holds the whole file (plus the edited copy) in memory** — streaming exists only on the read path.
+- **A sub-limit overwrite still buffers a contextual basis** — `writeText` may retain up to just below `config.diffBasisMaxBytes` of prior text in addition to the caller-owned replacement; the bound does not cap the returned `after` value or presentation's whole-file fallback.
+- **Binary detection is asymmetric** — reads NUL-sample only the first 8192 bytes while edits scan the whole buffer, so a file with a late NUL reads fine but rejects edits.
+- **The per-target mutation lock is in-process only** — guarded create still uses an atomic no-replace publication across processes, but replacement writers in another process are caught only when the optional version guard observes their metadata change; they are never serialized.
+- **Guarded creation requires hard-link support** — filesystems or mounts that reject hard-link publication cannot serve `createIfAbsent`; the provider preserves the missing target and reports `FS_IO_ERROR`.
+- **Post-commit cleanup is best effort** — a successful publication remains successful if removal of its owner-only staging directory fails, leaving private residue for later operator cleanup.

package/README.zh.md

@@ -0,0 +1,44 @@
+# @deepseek-ai/dsh-fs-local
+
+[English](README.md) | 中文
+
+`ctx.fs` 提供方约定（[`@deepseek-ai/dsh-fs`](../fs)）的**本地文件系统实现**。它使用宿主文件系统支持十一个 `FileSystem` 原语；将其作为插件加载会填充 `ctx.fs`。
+
+```ts ignore-check
+import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
+
+await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
+// ctx.fs uses the local backend; load @deepseek-ai/dsh-fs-policy for the
+// freshness policy gate and @deepseek-ai/dsh-tool-fs to expose read/write/edit.
+```
+
+## 行为
+
+- **`resolve(path, opts?)`**：相对 `path` 在调用方提供 `opts.cwd` 时以该值为基准解析（面向模型的工具会传入调用 agent（智能体）的会话 cwd；见[每会话 cwd Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md)），否则以 `config.cwd` 为基准（默认 `process.cwd()`）；绝对 `path` 会忽略两者。`opts.signal` 会在本地解析前后检查，远程同级后端则可以用它中止往返。`targetKey` 是文件的 `realpath`，因此经符号链接到达同一文件的两个输入路径会共享一个身份，写入/编辑落在链接目标上，同时保留链接。尚不存在的路径在父目录存在时使用 realpath 后的父目录加 basename；只有父目录无法解析时才回退到绝对路径。`displayPath` 是绝对但未经解析的路径。
+- **执行世界坐标**：`processPath` 公开目标的规范化宿主路径，`fileUrl` 通过 Node 的平台感知 URL 转换对该路径编码，`contains` 则使用平台路径语义检查身份相等或后代包含关系，消费方无需解析 `targetKey`。
+- **`stat` / `lstat`**：返回目标元数据；目标不存在时返回 `undefined`。`stat` 为已解析目标报告 `FsInfo`（`version` 是由 bigint `dev:ino:size:mtimeNs:ctimeNs` 派生的不透明 token，`type` 为 `file`/`directory`/`other`，`size` 以字节计）；路径形态的 `lstat` 不跟随最后一个符号链接，报告 `FsPathInfo`，因此可以返回 `symlink`。两者都会在异步元数据探测前后检查取消，因此飞行中的中止会报告 `FS_ABORTED`，而非陈旧的不存在结果。
+- **`readText` / `streamText`**：只支持 UTF-8。`readText` 读取整个文件；`streamText` 按分片解码，因此超大文件无需整体保存在内存中，消费方也可以执行各自的保留上限。两者都会拒绝无效 UTF-8、包含 NUL 字节的二进制样本（`FS_NOT_TEXT`）以及非普通文件目标。`read` 工具（`@deepseek-ai/dsh-tool-fs`）拥有行窗口逻辑。
+- **`listDir`**：按稳定的 `name.localeCompare()` 顺序列出一层目录。每个条目携带子项 basename、类型、解析后的子目标（`displayPath` 位于所列目录下，`targetKey` 是 realpath 身份）和低成本 stat 元数据（`version`，普通文件另有 `size`）。它绝不会打开或解码文件内容。缺失目标报告 `FS_NOT_FOUND`，文件/特殊文件目标报告 `FS_NOT_DIRECTORY`，已中止调用报告 `FS_ABORTED`，权限失败报告 `FS_PERMISSION_DENIED`，其他列出或子项元数据 I/O 失败报告 `FS_IO_ERROR`。损坏/消失的子项以无元数据的 `other` 返回，但解析子项时出现权限/I/O 失败会让整个列表以结构化 `FsError` 失败。
+- **`writeText`**：原子写入。它会向排他打开的临时文件（`wx`、`0o600`）写入；该文件位于目标旁随机命名的私有暂存目录（`0o700`）内，随后执行 fsync 并发布。现有文件的 mode 会保留，新文件默认为 `0o600`；Windows 上的新文件继承目标目录的 DACL，而替换会在写入前把目标 DACL 复制到空临时文件，并通过 `ReplaceFileW` 发布，使原访问政策得以保留（见 [Windows DACL 保留 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)）。`expected` 防护是可选的：省略时无条件创建或覆盖；`createIfAbsent` 通过硬链接把暂存文件发布到目标位置，以实现原子且不替换的发布，因此初始探测后创建的普通文件会被保留，并以 `FS_NOT_OBSERVED` 拒绝本次写入；非普通路径条目也会被保留，并以 `FS_NOT_REGULAR_FILE` 拒绝；`replaceIfVersion` 只在观察到的版本上替换（目标缺失或版本不匹配均为 `FS_STALE_VERSION`）。仅当打开后的旧文件和 UTF-8 替换内容都严格低于 `config.diffBasisMaxBytes`（默认 10 MiB）时，覆写才返回旧文本作为上下文 diff 基础。即使外部写入方在初次探测后替换文件或改变文件大小，文件描述符读取仍会强制执行该上限；否则提供方返回 `before: null`，由展示层使用整文件回退。
+- **`editText`**：在同一原语之上依次执行原子的字面量读取、修改和写入，并通过变更锁按目标串行化。`expected` 防护是可选的：提供时，会在字面量匹配之前校验版本（陈旧编辑报告 `FS_STALE_VERSION`，绝不会针对较新内容报告 `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT`）；省略时，无条件编辑当前内容。无论哪种情况，目标缺失都报告 `FS_STALE_VERSION`。匹配时规范化为 LF，随后恢复文件主要的 CRLF/LF 风格；空 `oldString` / 零匹配报告 `FS_EDIT_NOT_FOUND`，未设置 `replace_all` 的多个匹配则报告 `FS_AMBIGUOUS_EDIT`。
+
+包根 SDK 接口包含默认/具名 `LocalFileSystem` 类和 `Config`。原始 I/O 位于 `src/fsio.ts`（不依赖 Cordis，单独进行单元测试）；`src/index.ts` 是轻量服务接线。
+
+## 模型体验
+
+通过 [`dsh-tool-fs`](../tool-fs/README.md) 间接产生影响；该消费方把本提供方带行窗口的 UTF-8 内容、变更确认和精确提供方消息渲染为有上限且保留的结果，而版本、原子写入机制和目录元数据保持内部可见。
+
+#### KV Cache 影响
+
+不会直接使缓存失效；具名消费方负责请求前缀的任何变化。
+
+## 已知限制与延期工作
+
+- **`config.cwd` 不是沙箱**：它是解析默认值，而非约束；绝对路径和 `..` 可以逃逸。请使用更严格的 `ctx.fs` 后端或 `tools/execute` waterfall（瀑布式事件）上的权限插件实施约束（见[能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md#consequences)）。
+- **版本 token 依赖文件系统元数据**：它们组合设备、inode、大小、纳秒级 mtime 和纳秒级 ctime；如果存储层在重写时无法更新其中任何一项事实，仍可能绕过陈旧防护。
+- **`editText` 会把整个文件及编辑后的副本保存在内存中**：只有读取路径支持流式处理。
+- **低于上限的覆写仍会缓冲上下文基础**：`writeText` 除调用方持有的替换内容外，最多还会保留略低于 `config.diffBasisMaxBytes` 的旧文本；该上限不限制返回的 `after` 值，也不限制展示层的整文件回退。
+- **二进制检测不对称**：读取只对前 8192 字节执行 NUL 采样，编辑则扫描整个 buffer，因此 NUL 出现在后部的文件可以读取，但编辑会被拒绝。
+- **每目标变更锁仅限进程内**：即使跨进程，带防护的创建仍采用原子且不替换的发布方式；但只有当可选版本防护观察到元数据变化时，系统才能发现其他进程中的替换写入方，且绝不会将其串行化。
+- **带防护的创建要求支持硬链接**：拒绝硬链接发布的文件系统或挂载点无法支持 `createIfAbsent`；提供方会使目标保持缺失状态并报告 `FS_IO_ERROR`。
+- **提交后清理采用尽力而为语义**：如果移除仅所有者可访问的暂存目录失败，成功发布仍视为成功，并留下私有残留供运维人员后续清理。

package/lib/index.js

@@ -0,0 +1,784 @@
+import { constants } from "node:buffer";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep, toNamespacedPath } from "node:path";
+import { pathToFileURL } from "node:url";
+import z from "@deepseek-ai/schemastery";
+import { FileSystem, FsError, FsTargetKey, FsVersion } from "@deepseek-ai/dsh-fs";
+import { randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { chmod, link, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, stat } from "node:fs/promises";
+import { TextDecoder } from "node:util";
+//#region lib/types/win32.js
+/**
+* Windows security-descriptor helpers for atomic local-file replacement. Koffi loads lazily so
+* non-Windows processes never open Win32 libraries.
+* @module @deepseek-ai/dsh-fs-local/win32
+*/
+const DACL_SECURITY_INFORMATION = 4;
+const ERROR_FILE_NOT_FOUND = 2;
+const ERROR_PATH_NOT_FOUND = 3;
+const ERROR_ACCESS_DENIED = 5;
+let bindings;
+async function win32() {
+	if (bindings !== void 0) return bindings;
+	const koffi = (await import("koffi")).default;
+	const advapi32 = koffi.load("advapi32.dll");
+	const kernel32 = koffi.load("kernel32.dll");
+	bindings = {
+		getFileSecurityW: advapi32.func("int __stdcall GetFileSecurityW(const char16_t *path, uint32_t requested, void *descriptor, uint32_t length, _Out_ uint32_t *needed)"),
+		setFileSecurityW: advapi32.func("int __stdcall SetFileSecurityW(const char16_t *path, uint32_t information, const void *descriptor)"),
+		replaceFileW: kernel32.func("int __stdcall ReplaceFileW(const char16_t *replaced, const char16_t *replacement, const char16_t *backup, uint32_t flags, void *exclude, void *reserved)"),
+		getLastError: kernel32.func("uint32_t __stdcall GetLastError()")
+	};
+	return bindings;
+}
+function errnoCode(win32Code) {
+	switch (win32Code) {
+		case ERROR_FILE_NOT_FOUND:
+		case ERROR_PATH_NOT_FOUND: return "ENOENT";
+		case ERROR_ACCESS_DENIED: return "EACCES";
+		default: return "EIO";
+	}
+}
+function win32Error(syscall, win32Code, path) {
+	const code = errnoCode(win32Code);
+	const error = /* @__PURE__ */ new Error(`${syscall} ${code} (Win32 ${win32Code}): ${path}`);
+	error.code = code;
+	error.errno = win32Code;
+	error.syscall = syscall;
+	error.path = path;
+	error.win32Code = win32Code;
+	return error;
+}
+/**
+* Read a file's self-relative DACL security descriptor.
+* @param path - existing file whose DACL is read.
+* @returns a descriptor buffer accepted by `SetFileSecurityW`.
+*/
+async function readFileDaclWin32(path) {
+	const api = await win32();
+	const nativePath = toNamespacedPath(path);
+	const needed = [0];
+	api.getFileSecurityW(nativePath, DACL_SECURITY_INFORMATION, null, 0, needed);
+	if (needed[0] === 0) throw win32Error("GetFileSecurityW", api.getLastError(), path);
+	const descriptor = Buffer.alloc(needed[0]);
+	if (api.getFileSecurityW(nativePath, DACL_SECURITY_INFORMATION, descriptor, descriptor.length, needed) === 0) throw win32Error("GetFileSecurityW", api.getLastError(), path);
+	return descriptor.subarray(0, needed[0]);
+}
+/**
+* Copy an existing file's DACL onto another file and protect it from staging-parent inheritance.
+* The destination must still be empty when confidentiality depends on this call.
+* @param source - existing file whose DACL is copied.
+* @param destination - existing file that receives the protected DACL.
+*/
+async function copyFileDaclWin32(source, destination) {
+	const descriptor = await readFileDaclWin32(source);
+	const api = await win32();
+	if (api.setFileSecurityW(toNamespacedPath(destination), 2147483652, descriptor) === 0) throw win32Error("SetFileSecurityW", api.getLastError(), destination);
+}
+/**
+* Replace a Windows file while preserving the replaced file's ACL and other replace metadata.
+* @param replaced - existing destination file.
+* @param replacement - closed staging file on the same volume.
+*/
+async function replaceFileWin32(replaced, replacement) {
+	const api = await win32();
+	if (api.replaceFileW(toNamespacedPath(replaced), toNamespacedPath(replacement), null, 0, null, null) === 0) throw win32Error("ReplaceFileW", api.getLastError(), replaced);
+}
+//#endregion
+//#region lib/types/fsio.js
+/**
+* Cordis-free local filesystem mechanics. This provider layer returns validated UTF-8 text,
+* streams large files, and rejects binary data; line windows belong to `dsh-tool-fs`. Writes
+* stage an exclusive owner-only file in a private sibling directory and atomically publish it.
+* @module @deepseek-ai/dsh-fs-local/fsio
+*/
+const BINARY_SAMPLE_BYTES = 8192;
+const DIFF_BASIS_READ_CHUNK_BYTES = 64 * 1024;
+function isENOENT(error) {
+	return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function isEEXIST(error) {
+	return error instanceof Error && "code" in error && error.code === "EEXIST";
+}
+/**
+* A path component that is expected to be a directory is a regular file (e.g.
+* resolving `afile/child.txt` when `afile` is a file). Like `ENOENT`, the target
+* cannot exist — so the resolution/probe paths treat it as "absent" rather than
+* letting a raw Node error escape without the structured `FsError` taxonomy.
+*/
+function isENOTDIR(error) {
+	return error instanceof Error && "code" in error && error.code === "ENOTDIR";
+}
+function isAbortError(error) {
+	return error instanceof Error && error.name === "AbortError";
+}
+/* v8 ignore start -- composes secondary cleanup-failure messages, which require a filesystem/kernel fault after the primary failure. */
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/* v8 ignore stop */
+function isPermissionError(error) {
+	return error instanceof Error && "code" in error && (error.code === "EACCES" || error.code === "EPERM");
+}
+function throwIfAborted(signal, verb) {
+	if (signal?.aborted) throw new FsError(`${verb} aborted`, "FS_ABORTED");
+}
+/**
+* `readFile` with the supplied signal, translating a mid-read `AbortError` into
+* the seam's structured `FsError('FS_ABORTED')` (Node rejects an aborted
+* `readFile` with a bare `AbortError`, which would otherwise escape the seam's
+* error taxonomy — the streaming/write paths translate it the same way).
+*/
+async function readFileAbortable(absolutePath, verb, signal) {
+	try {
+		return await readFile(absolutePath, signal ? { signal } : {});
+	} catch (error) {
+		/* v8 ignore next 2 -- a non-abort readFile rejection needs a permission/IO fault racing an open file. */
+		if (!isAbortError(error)) throw error;
+		throw new FsError(`${verb} aborted`, "FS_ABORTED");
+	}
+}
+/** Opaque version token from high-resolution identity and freshness metadata. */
+function versionOf(info) {
+	return FsVersion(`${info.dev}:${info.ino}:${info.size}:${info.mtimeNs}:${info.ctimeNs}`);
+}
+/**
+* Resolve a path to its absolute display path and realpath identity. For a missing target,
+* realpath the nearest existing ancestor and append the missing suffix, preserving identity
+* across symlinked ancestors before and after creation.
+* @param cwd - base directory a relative `path` resolves against.
+* @param path - absolute or relative path; empty/whitespace-only throws `FS_NOT_FOUND`.
+* @returns the absolute display path plus the realpath-derived stable target key.
+*/
+async function resolveLocalTarget(cwd, path) {
+	if (path.trim().length === 0) throw new FsError("file_path must be a non-empty string", "FS_NOT_FOUND");
+	const displayPath = resolve(cwd, path);
+	try {
+		return {
+			displayPath,
+			targetKey: FsTargetKey(await realpath(displayPath))
+		};
+	} catch (error) {
+		/* v8 ignore next -- Windows reports this case as ENOENT and repairs it in the ancestor walk below. */
+		if (isENOTDIR(error)) throw new FsError(`cannot resolve "${displayPath}": a parent path segment is not a directory`, "FS_NOT_FOUND");
+		/* v8 ignore next -- non-ENOENT realpath failure needs a permission/IO fault; ENOENT falls through to ancestor resolution. */
+		if (!isENOENT(error)) throw error;
+	}
+	const missing = [basename(displayPath)];
+	let ancestor = dirname(displayPath);
+	while (true) try {
+		const realAncestor = await realpath(ancestor);
+		/* v8 ignore start -- native Windows coverage exercises this repair; POSIX reports ENOTDIR before this point. */
+		if (process.platform === "win32") {
+			if (!(await stat(realAncestor)).isDirectory()) throw new FsError(`cannot resolve "${displayPath}": a parent path segment is not a directory`, "FS_NOT_FOUND");
+		}
+		/* v8 ignore stop */
+		return {
+			displayPath,
+			targetKey: FsTargetKey(join(realAncestor, ...missing))
+		};
+	} catch (error) {
+		/* v8 ignore next -- native Windows coverage exercises the FsError raised by the repair above. */
+		if (error instanceof FsError) throw error;
+		/* v8 ignore next -- a non-ENOENT realpath failure needs a permission/IO fault. */
+		if (!isENOENT(error)) throw error;
+		const parent = dirname(ancestor);
+		/* v8 ignore next -- the filesystem root always realpaths, so the walk terminates before parent === ancestor. */
+		if (parent === ancestor) return {
+			displayPath,
+			targetKey: FsTargetKey(displayPath)
+		};
+		missing.unshift(basename(ancestor));
+		ancestor = parent;
+	}
+}
+function pathType(info) {
+	if (info.isFile()) return "file";
+	/* v8 ignore else -- Windows has no special-entry fixture for the non-directory branch. */
+	if (info.isDirectory()) return "directory";
+	/* v8 ignore next -- the corresponding special-entry return is covered on POSIX. */
+	return "other";
+}
+function pathLinkType(info) {
+	if (info.isSymbolicLink()) return "symlink";
+	return pathType(info);
+}
+async function probeStats(absolutePath, readStats) {
+	try {
+		return await readStats(absolutePath);
+	} catch (error) {
+		/* v8 ignore next -- a non-ENOENT/ENOTDIR metadata failure needs a permission/IO fault; surface it. */
+		if (!isENOENT(error) && !isENOTDIR(error)) throw error;
+		return null;
+	}
+}
+/**
+* Probe a path for its version, mode, type, and size. Null if absent.
+* @param absolutePath - the path to stat (typically a target key; symlinks are followed).
+* @returns the metadata, or null when the path — or a parent segment — does not exist.
+*/
+async function probe(absolutePath) {
+	const info = await probeStats(absolutePath, (path) => stat(path, { bigint: true }));
+	if (!info) return null;
+	return {
+		version: versionOf(info),
+		mode: Number(info.mode & 511n),
+		type: pathType(info),
+		size: Number(info.size)
+	};
+}
+/**
+* Probe a path without following the final symlink component.
+* @param absolutePath - the path entry to inspect with `lstat` semantics.
+* @returns path-entry metadata, or null when the entry is absent.
+*/
+async function probeNoFollow(absolutePath) {
+	const info = await probeStats(absolutePath, (path) => lstat(path, { bigint: true }));
+	if (!info) return null;
+	return {
+		version: versionOf(info),
+		mode: Number(info.mode & 511n),
+		type: pathLinkType(info),
+		size: Number(info.size)
+	};
+}
+function listingIoError(displayPath, error) {
+	/* v8 ignore next -- defensive pass-through for races where a child resolver has already produced a structured FsError. */
+	if (error instanceof FsError) return error;
+	/* v8 ignore next -- requires the listed target/parent to disappear between successful preflight and listing/child resolution. */
+	if (isENOENT(error) || isENOTDIR(error)) return new FsError(`cannot list "${displayPath}": not found`, "FS_NOT_FOUND", { cause: error });
+	/* v8 ignore next -- Windows chmod does not deny directory listing; POSIX covers permission translation. */
+	if (isPermissionError(error)) return new FsError(`cannot list "${displayPath}": permission denied`, "FS_PERMISSION_DENIED", { cause: error });
+	return new FsError(`cannot list "${displayPath}": ${errorMessage(error)}`, "FS_IO_ERROR", { cause: error });
+}
+async function resolveListedChildTarget(parent, name) {
+	const identity = await resolveLocalTarget(parent.targetKey, name);
+	return {
+		displayPath: join(parent.displayPath, name),
+		targetKey: identity.targetKey
+	};
+}
+/**
+* List direct children of a directory in stable name order. Each child includes
+* a resolved target plus stat metadata when still available; file contents are
+* never read.
+* @param target - the resolved directory to list; a missing or non-directory target throws.
+* @param signal - aborts the listing, checked between children (`FS_ABORTED`).
+* @returns one entry per direct child, sorted by name.
+*/
+async function listDirectory(target, signal) {
+	throwIfAborted(signal, "list");
+	let info;
+	try {
+		info = await probe(target.targetKey);
+	} catch (error) {
+		throw listingIoError(target.displayPath, error);
+	}
+	if (!info) throw new FsError(`cannot list "${target.displayPath}": not found`, "FS_NOT_FOUND");
+	if (info.type !== "directory") throw new FsError(`cannot list "${target.displayPath}": not a directory`, "FS_NOT_DIRECTORY");
+	let entries;
+	try {
+		entries = await readdir(target.targetKey, {
+			withFileTypes: true,
+			encoding: "utf8"
+		});
+	} catch (error) {
+		/* v8 ignore next -- requires permission/kernel failure from readdir after a successful directory stat. */
+		throw listingIoError(target.displayPath, error);
+	}
+	throwIfAborted(signal, "list");
+	const result = [];
+	for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+		throwIfAborted(signal, "list");
+		try {
+			const childTarget = await resolveListedChildTarget(target, entry.name);
+			const childInfo = await probe(childTarget.targetKey);
+			result.push({
+				name: entry.name,
+				type: childInfo?.type ?? "other",
+				target: childTarget,
+				...childInfo ? { version: childInfo.version } : {},
+				...childInfo?.type === "file" ? { size: childInfo.size } : {}
+			});
+		} catch (error) {
+			throw listingIoError(join(target.displayPath, entry.name), error);
+		}
+		throwIfAborted(signal, "list");
+	}
+	return result;
+}
+function notTextError(verb, displayPath) {
+	return new FsError(`cannot ${verb} "${displayPath}": invalid UTF-8 text`, "FS_NOT_TEXT");
+}
+function decodeUtf8(buffer, verb, displayPath) {
+	try {
+		return new TextDecoder("utf-8", { fatal: true }).decode(buffer);
+	} catch (error) {
+		/* v8 ignore next 2 -- TextDecoder({fatal}) only throws TypeError on invalid bytes; any other throw is an unreachable runtime fault. */
+		if (!(error instanceof TypeError)) throw error;
+		throw notTextError(verb, displayPath);
+	}
+}
+function decodeUtf8Stream(decoder, chunk, verb, displayPath) {
+	try {
+		return chunk ? decoder.decode(chunk, { stream: true }) : decoder.decode();
+	} catch (error) {
+		/* v8 ignore next 2 -- TextDecoder({fatal}) only throws TypeError on invalid bytes; any other throw is an unreachable runtime fault. */
+		if (!(error instanceof TypeError)) throw error;
+		throw notTextError(verb, displayPath);
+	}
+}
+async function statRegularFile(target, verb, signal) {
+	throwIfAborted(signal, verb);
+	let info;
+	try {
+		info = await stat(target.targetKey);
+	} catch (error) {
+		/* v8 ignore next 2 -- a non-ENOENT stat failure needs a permission/IO fault; only the not-found path is reachable in tests. */
+		if (!isENOENT(error)) throw error;
+		throw new FsError(`cannot ${verb} "${target.displayPath}": not found`, "FS_NOT_FOUND");
+	}
+	if (!info.isFile()) throw new FsError(`cannot ${verb} "${target.displayPath}": not a regular file`, "FS_NOT_REGULAR_FILE");
+	return info;
+}
+/**
+* Read a whole regular UTF-8 text file into a single decoded string. Rejects
+* non-regular files, invalid UTF-8, and NUL-byte binary samples.
+* @param target - the resolved file to read.
+* @param signal - aborts the read (`FS_ABORTED`).
+* @returns the full decoded text, byte-for-byte (no normalization).
+*/
+async function readWholeText(target, signal) {
+	await statRegularFile(target, "read", signal);
+	const raw = await readFileAbortable(target.targetKey, "read", signal);
+	throwIfAborted(signal, "read");
+	if (raw.subarray(0, BINARY_SAMPLE_BYTES).includes(0)) throw new FsError(`cannot read "${target.displayPath}": binary file`, "FS_NOT_TEXT");
+	return decodeUtf8(raw, "read", target.displayPath);
+}
+/**
+* Stream a whole regular UTF-8 text file as decoded text chunks. Same text
+* semantics as {@link readWholeText} (regular-file check, binary/NUL rejection,
+* cross-chunk UTF-8 decoding), but never holds the whole file in memory.
+* @param target - the resolved file to stream.
+* @param signal - aborts the stream, including between chunks (`FS_ABORTED`).
+* @returns decoded text chunks in file order; chunk boundaries carry no meaning.
+*/
+async function* streamWholeText(target, signal) {
+	await statRegularFile(target, "read", signal);
+	const stream = createReadStream(target.targetKey, signal ? { signal } : {});
+	const decoder = new TextDecoder("utf-8", { fatal: true });
+	let sampledBytes = 0;
+	function scanBinarySample(chunk) {
+		if (sampledBytes >= BINARY_SAMPLE_BYTES) return;
+		const sample = chunk.subarray(0, Math.min(chunk.length, BINARY_SAMPLE_BYTES - sampledBytes));
+		if (sample.includes(0)) throw new FsError(`cannot read "${target.displayPath}": binary file`, "FS_NOT_TEXT");
+		sampledBytes += sample.length;
+	}
+	try {
+		for await (const chunk of stream) {
+			scanBinarySample(chunk);
+			yield decodeUtf8Stream(decoder, chunk, "read", target.displayPath);
+		}
+		yield decodeUtf8Stream(decoder, void 0, "read", target.displayPath);
+	} catch (error) {
+		/* v8 ignore next 4 -- mid-stream errors need an abort/IO fault racing the loop; pre-abort is caught by throwIfAborted. */
+		if (isAbortError(error)) throw new FsError("read aborted", "FS_ABORTED");
+		throw error;
+	}
+}
+async function removeStagingDirOrThrow(stagingDir, originalError, removeStagingDir) {
+	try {
+		await removeStagingDir(stagingDir);
+	} catch (cleanupError) {
+		/* v8 ignore next 1 -- cleanup failure here needs a second filesystem fault after the primary write failure. */
+		throw new FsError(`write failed (${errorMessage(originalError)}) and temp cleanup failed (${errorMessage(cleanupError)})`, "FS_NOT_FOUND", { cause: originalError });
+	}
+	throw originalError;
+}
+async function throwGuardedCreateFailure(error, absolutePath, displayPath, inspectPublicationTarget) {
+	let existing;
+	try {
+		existing = await inspectPublicationTarget(absolutePath);
+	} catch (metadataError) {
+		if (!isENOENT(metadataError) && !isENOTDIR(metadataError)) throw new FsError(`cannot write "${displayPath}": ${errorMessage(metadataError)}`, "FS_IO_ERROR", { cause: metadataError });
+	}
+	if (existing !== void 0) {
+		if (!existing.isFile()) throw new FsError(`cannot write "${displayPath}": not a regular file`, "FS_NOT_REGULAR_FILE", { cause: error });
+		throw new FsError(`cannot overwrite existing "${displayPath}" without reading it first`, "FS_NOT_OBSERVED", { cause: error });
+	}
+	if (isEEXIST(error)) throw new FsError(`cannot overwrite existing "${displayPath}" without reading it first`, "FS_NOT_OBSERVED", { cause: error });
+	throw new FsError(`cannot write "${displayPath}": ${errorMessage(error)}`, "FS_IO_ERROR", { cause: error });
+}
+/**
+* Atomically replace a file through a private, synced staging file in the same directory.
+* POSIX protects the staging directory and file with `0o700` and `0o600`. A new Windows file
+* inherits the destination directory's DACL; a replacement copies the existing target's DACL
+* onto the empty temp before writing and preserves the target descriptor at publication.
+* @param absolutePath - destination; missing parent directories are created.
+* @param content - the full UTF-8 text to write.
+* @param mode - existing destination's POSIX mode to preserve, or `undefined` for a new file;
+* inert as a mode on Windows but identifies replacement security semantics.
+* @param signal - cancellation checked before final publication.
+* @param internals - Test hook for pinning temp names and observing the staged file.
+* @param createIfAbsent - when provided, publish with a hard-link no-replace
+* primitive; a concurrent creator's file is preserved and this write is
+* rejected with `FS_NOT_OBSERVED` using the supplied display path.
+*/
+async function writeFileAtomic(absolutePath, content, mode, signal, internals = {}, createIfAbsent) {
+	throwIfAborted(signal, "write");
+	const directory = dirname(absolutePath);
+	await mkdir(directory, { recursive: true });
+	throwIfAborted(signal, "write");
+	const stagingDir = join(directory, internals.tempDirName?.(absolutePath) ?? `.${basename(absolutePath)}.${process.pid}.${randomUUID()}.tmpdir`);
+	const tempPath = join(stagingDir, internals.tempName?.(absolutePath) ?? `${basename(absolutePath)}.tmp`);
+	const platform = internals.platform ?? process.platform;
+	const copyFileDacl = internals.copyFileDacl ?? copyFileDaclWin32;
+	const replaceFile = internals.replaceFile ?? replaceFileWin32;
+	const linkFile = internals.linkFile ?? link;
+	const inspectPublicationTarget = internals.inspectPublicationTarget ?? ((path) => lstat(path, { bigint: true }));
+	const removeStagingDir = internals.removeStagingDir ?? ((path) => rm(path, {
+		recursive: true,
+		force: true
+	}));
+	let handle;
+	let stagingCreated = false;
+	try {
+		await mkdir(stagingDir, { mode: 448 });
+		stagingCreated = true;
+		await chmod(stagingDir, 448);
+		handle = await open(tempPath, "wx", 384);
+		await handle.chmod(384);
+		if (platform === "win32" && mode !== void 0) await copyFileDacl(absolutePath, tempPath);
+		await handle.writeFile(content, {
+			encoding: "utf8",
+			...signal ? { signal } : {}
+		});
+		await handle.sync();
+		await internals.inspectTemp?.({
+			stagingDir,
+			tempPath
+		});
+		if (mode !== void 0) await handle.chmod(mode);
+		await handle.close();
+		handle = void 0;
+		throwIfAborted(signal, "write");
+		if (createIfAbsent !== void 0) try {
+			await linkFile(tempPath, absolutePath);
+		} catch (error) {
+			await throwGuardedCreateFailure(error, absolutePath, createIfAbsent.displayPath, inspectPublicationTarget);
+		}
+		else if (platform === "win32" && mode !== void 0) try {
+			await replaceFile(absolutePath, tempPath);
+		} catch (error) {
+			if (!isENOENT(error)) throw error;
+			await rename(tempPath, absolutePath);
+		}
+		else await rename(tempPath, absolutePath);
+		try {
+			await removeStagingDir(stagingDir);
+		} catch (_committedStagingCleanupFailure) {}
+	} catch (error) {
+		/* v8 ignore next -- abort-mid-write needs a writeFile/signal race; the non-abort (rename/open) side is tested. */
+		let failure = isAbortError(error) ? new FsError("write aborted", "FS_ABORTED") : error;
+		/* v8 ignore next 8 -- reached only if writeFile/sync throws with the handle open (IO fault); close-failure is a double fault. */
+		if (handle) try {
+			await handle.close();
+		} catch (closeError) {
+			failure = new FsError(`write failed (${errorMessage(failure)}) and temp close failed (${errorMessage(closeError)})`, "FS_NOT_FOUND", { cause: failure });
+		}
+		if (!stagingCreated) throw failure;
+		return removeStagingDirOrThrow(stagingDir, failure, removeStagingDir);
+	}
+}
+/**
+* Collapse CRLF to LF — the canonical in-memory form every edit/diff basis
+* uses. Lone `\r` bytes (not followed by `\n`) are left untouched.
+* @param content - decoded text in whatever line-ending style the file had.
+* @returns the text with every `\r\n` pair replaced by `\n`.
+*/
+function normalizeLineEndings(content) {
+	return content.replaceAll("\r\n", "\n");
+}
+function detectLineEndings(raw) {
+	const sample = raw.slice(0, 4096);
+	const crlfCount = sample.split("\r\n").length - 1;
+	return crlfCount > sample.split("\n").length - 1 - crlfCount ? "CRLF" : "LF";
+}
+/**
+* Convert LF-normalized content back to the line-ending style detected at read
+* time, for write-back. `LF` returns the content unchanged; `CRLF` re-normalizes
+* first so an already-CRLF sequence is never doubled to `\r\r\n`.
+* @param content - the LF-normalized (edited) text.
+* @param lineEndings - the original file's style, as detected by {@link readForEdit}.
+* @returns the text in the original file's line-ending style.
+*/
+function restoreLineEndings(content, lineEndings) {
+	return lineEndings === "LF" ? content : normalizeLineEndings(content).split("\n").join("\r\n");
+}
+function countOccurrences(content, needle) {
+	let count = 0;
+	let index = 0;
+	while (true) {
+		const found = content.indexOf(needle, index);
+		if (found === -1) return count;
+		count += 1;
+		index = found + needle.length;
+	}
+}
+/**
+* Read and decode a file for editing: rejects binaries, returns LF-normalized
+* content plus the original line-ending style for write-back.
+* @param absolutePath - the file to read (typically a target key).
+* @param displayPath - the caller-facing path used in error messages.
+* @param signal - aborts the read (`FS_ABORTED`).
+* @returns the LF-normalized content and the detected style to restore on write-back.
+*/
+async function readForEdit(absolutePath, displayPath, signal) {
+	throwIfAborted(signal, "edit");
+	const buffer = await readFileAbortable(absolutePath, "edit", signal);
+	throwIfAborted(signal, "edit");
+	if (buffer.includes(0)) throw new FsError(`cannot edit "${displayPath}": binary file`, "FS_NOT_TEXT");
+	const raw = decodeUtf8(buffer, "edit", displayPath);
+	return {
+		content: normalizeLineEndings(raw),
+		lineEndings: detectLineEndings(raw)
+	};
+}
+/**
+* Best-effort overwrite diff basis. Binary, invalid UTF-8, a file at/above the byte limit,
+* or a file deleted/made unreadable after the caller's preflight returns `null` so the write
+* still succeeds and presentation falls back to a whole-file diff. The bound is enforced on
+* the opened descriptor rather than a prior path stat, so concurrent external replacement or
+* size changes cannot make this helper buffer more than `maxBytes`.
+* @param absolutePath - the file to read (typically a target key).
+* @param maxBytes - exclusive upper bound for bytes held as the contextual-diff basis.
+* @param signal - aborts the read (`FS_ABORTED`); cancellation propagates, unlike I/O failure.
+* @returns the LF-normalized text, or null for a non-regular, at/above-limit, binary, non-UTF-8,
+* descriptor-size-changed, or unreadable file.
+*/
+async function readTextForDiff(absolutePath, maxBytes, signal) {
+	throwIfAborted(signal, "read");
+	try {
+		const handle = await open(absolutePath, "r");
+		let buffer;
+		let total = 0;
+		let openedSize = 0;
+		try {
+			throwIfAborted(signal, "read");
+			const info = await handle.stat();
+			throwIfAborted(signal, "read");
+			if (!info.isFile()) return null;
+			if (info.size >= maxBytes) return null;
+			openedSize = info.size;
+			buffer = Buffer.allocUnsafe(openedSize + 1);
+			while (total < buffer.length) {
+				throwIfAborted(signal, "read");
+				const length = Math.min(buffer.length - total, DIFF_BASIS_READ_CHUNK_BYTES);
+				const { bytesRead } = await handle.read(buffer, total, length, null);
+				if (bytesRead === 0) break;
+				total += bytesRead;
+			}
+		} finally {
+			await handle.close();
+		}
+		throwIfAborted(signal, "read");
+		if (total !== openedSize) return null;
+		const basis = buffer.subarray(0, total);
+		if (basis.includes(0)) return null;
+		try {
+			return normalizeLineEndings(new TextDecoder("utf-8", { fatal: true }).decode(basis));
+		} catch (error) {
+			/* v8 ignore next 2 -- TextDecoder({fatal}) only throws TypeError on invalid bytes;
+			* any other throw is an unreachable runtime fault. */
+			if (!(error instanceof TypeError)) throw error;
+			return null;
+		}
+	} catch (error) {
+		if (error instanceof FsError) throw error;
+		if (error instanceof Error && "code" in error) return null;
+		throw error;
+	}
+}
+/**
+* Apply a literal replacement to LF-normalized content. Empty or missing search text throws
+* `FS_EDIT_NOT_FOUND`; multiple matches throw `FS_AMBIGUOUS_EDIT` unless `replaceAll` is true.
+* @param content - the current file content, already LF-normalized.
+* @param oldString - literal text to find; CRLF inside it is normalized to LF before
+*   matching.
+* @param newString - literal replacement text, normalized the same way.
+* @param replaceAll - replace every match instead of requiring exactly one.
+* @param displayPath - the caller-facing path used in error messages.
+* @returns the edited LF-normalized content plus how many occurrences were replaced.
+*/
+function applyLiteralEdit(content, oldString, newString, replaceAll, displayPath) {
+	const oldNorm = normalizeLineEndings(oldString);
+	if (oldNorm.length === 0) throw new FsError("old_string must be a non-empty string", "FS_EDIT_NOT_FOUND");
+	const newNorm = normalizeLineEndings(newString);
+	const replacements = countOccurrences(content, oldNorm);
+	if (replacements === 0) throw new FsError(`old_string was not found in "${displayPath}"`, "FS_EDIT_NOT_FOUND");
+	if (!replaceAll && replacements > 1) throw new FsError(`old_string matched ${replacements} times in "${displayPath}"; provide a more specific old_string or set replace_all to true`, "FS_AMBIGUOUS_EDIT");
+	return {
+		content: content.split(oldNorm).join(newNorm),
+		replacements
+	};
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Host-filesystem implementation of `ctx.fs`. Realpath-derived target identity makes aliases
+* share stale guards, and writes through a symlink update its target without replacing the link.
+* @module @deepseek-ai/dsh-fs-local
+*/
+const DEFAULT_DIFF_BASIS_MAX_BYTES = 10 * 1024 * 1024;
+const MAX_DIFF_BASIS_BYTES = Math.min(constants.MAX_LENGTH, constants.MAX_STRING_LENGTH);
+/**
+* The host-filesystem backend. Reads resolve relative paths from {@link Config.cwd}
+* (a resolution default, NOT a containment boundary — see the filesystem
+* capability-seam Agent Note); enforce
+* containment with a stricter backend or a `tools/execute` permission plugin.
+*/
+var LocalFileSystem = class extends FileSystem {
+	static Config = z.object({
+		cwd: z.string().default(process.cwd()),
+		diffBasisMaxBytes: z.number().default(DEFAULT_DIFF_BASIS_MAX_BYTES)
+	});
+	/** Validated config (schemastery applied the defaults before construction). */
+	config;
+	/** Test hook forwarded to fsio for atomic-publication boundaries. */
+	internals = {};
+	/** Per-targetKey tail promise: serializes mutating ops so the read→guard→write
+	* window can't interleave, making concurrent writes/edits deterministically
+	* ordered (one wins, the rest see the new version and reject as stale). */
+	locks = /* @__PURE__ */ new Map();
+	constructor(ctx, config) {
+		super(ctx);
+		const resolved = config;
+		if (!Number.isSafeInteger(resolved.diffBasisMaxBytes) || resolved.diffBasisMaxBytes <= 0 || resolved.diffBasisMaxBytes > MAX_DIFF_BASIS_BYTES) throw new Error(`fs-local: diffBasisMaxBytes must be a positive safe integer no greater than ${MAX_DIFF_BASIS_BYTES}`);
+		this.config = resolved;
+	}
+	/** Run `op` with exclusive access to `targetKey` (FIFO per key). */
+	async withLock(targetKey, op) {
+		const run = (this.locks.get(targetKey) ?? Promise.resolve()).then(op, op);
+		const tail = run.then(() => void 0, () => void 0);
+		this.locks.set(targetKey, tail);
+		try {
+			return await run;
+		} finally {
+			if (this.locks.get(targetKey) === tail) this.locks.delete(targetKey);
+		}
+	}
+	async resolve(path, opts) {
+		if (opts?.signal?.aborted) throw new FsError("resolve aborted", "FS_ABORTED");
+		const local = await resolveLocalTarget(opts?.cwd ?? this.config.cwd, path);
+		if (opts?.signal?.aborted) throw new FsError("resolve aborted", "FS_ABORTED");
+		return {
+			targetKey: local.targetKey,
+			displayPath: local.displayPath
+		};
+	}
+	processPath(target) {
+		return String(target.targetKey);
+	}
+	fileUrl(target) {
+		return pathToFileURL(this.processPath(target)).href;
+	}
+	contains(parent, child) {
+		const path = relative(this.processPath(parent), this.processPath(child));
+		return path === "" || path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path);
+	}
+	async stat(target, signal) {
+		if (signal?.aborted) throw new FsError("stat aborted", "FS_ABORTED");
+		const info = await probe(target.targetKey);
+		if (signal?.aborted) throw new FsError("stat aborted", "FS_ABORTED");
+		if (!info) return void 0;
+		return {
+			version: info.version,
+			type: info.type,
+			size: info.size
+		};
+	}
+	async lstat(path, opts, signal) {
+		if (signal?.aborted) throw new FsError("lstat aborted", "FS_ABORTED");
+		if (path.trim().length === 0) throw new FsError("file_path must be a non-empty string", "FS_NOT_FOUND");
+		const info = await probeNoFollow(resolve(opts?.cwd ?? this.config.cwd, path));
+		if (signal?.aborted) throw new FsError("lstat aborted", "FS_ABORTED");
+		if (!info) return void 0;
+		return {
+			version: info.version,
+			type: info.type,
+			size: info.size
+		};
+	}
+	async readText(target, signal) {
+		return readWholeText({
+			displayPath: target.displayPath,
+			targetKey: target.targetKey
+		}, signal);
+	}
+	streamText(target, signal) {
+		return Promise.resolve(streamWholeText({
+			displayPath: target.displayPath,
+			targetKey: target.targetKey
+		}, signal));
+	}
+	async listDir(target, signal) {
+		return (await listDirectory({
+			displayPath: target.displayPath,
+			targetKey: target.targetKey
+		}, signal)).map((entry) => ({
+			name: entry.name,
+			type: entry.type,
+			target: {
+				targetKey: entry.target.targetKey,
+				displayPath: entry.target.displayPath
+			},
+			...entry.version !== void 0 ? { version: entry.version } : {},
+			...entry.size !== void 0 ? { size: entry.size } : {}
+		}));
+	}
+	async writeText(target, content, expected, signal) {
+		return this.withLock(target.targetKey, async () => {
+			const existing = await probe(target.targetKey);
+			if (existing && existing.type !== "file") throw new FsError(`cannot write "${target.displayPath}": not a regular file`, "FS_NOT_REGULAR_FILE");
+			if (expected?.kind === "replaceIfVersion") {
+				if (!existing) throw new FsError(`cannot write "${target.displayPath}": file no longer exists`, "FS_STALE_VERSION");
+				if (existing.version !== expected.version) throw new FsError(`cannot write "${target.displayPath}": file changed since it was read`, "FS_STALE_VERSION");
+			} else if (expected?.kind === "createIfAbsent" && existing) throw new FsError(`cannot overwrite existing "${target.displayPath}" without reading it first`, "FS_NOT_OBSERVED");
+			const before = existing !== null && Buffer.byteLength(content, "utf8") < this.config.diffBasisMaxBytes ? await readTextForDiff(target.targetKey, this.config.diffBasisMaxBytes, signal) : null;
+			await writeFileAtomic(target.targetKey, content, existing?.mode, signal, this.internals, expected?.kind === "createIfAbsent" ? { displayPath: target.displayPath } : void 0);
+			const after = await probe(target.targetKey);
+			return {
+				operation: existing ? "update" : "create",
+				version: this.versionAfterWrite(after, target),
+				before,
+				after: normalizeLineEndings(content)
+			};
+		});
+	}
+	async editText(target, edit, expected, signal) {
+		return this.withLock(target.targetKey, async () => {
+			const existing = await probe(target.targetKey);
+			if (!existing) throw new FsError(`cannot edit "${target.displayPath}": file changed since it was read`, "FS_STALE_VERSION");
+			if (existing.type !== "file") throw new FsError(`cannot edit "${target.displayPath}": not a regular file`, "FS_NOT_REGULAR_FILE");
+			if (expected && existing.version !== expected.version) throw new FsError(`cannot edit "${target.displayPath}": file changed since it was read`, "FS_STALE_VERSION");
+			const original = await readForEdit(target.targetKey, target.displayPath, signal);
+			const edited = applyLiteralEdit(original.content, edit.oldString, edit.newString, edit.replaceAll, target.displayPath);
+			const content = restoreLineEndings(edited.content, original.lineEndings);
+			await writeFileAtomic(target.targetKey, content, existing.mode, signal, this.internals);
+			const after = await probe(target.targetKey);
+			return {
+				version: this.versionAfterWrite(after, target),
+				before: original.content,
+				after: edited.content
+			};
+		});
+	}
+	/* v8 ignore next 5 -- the post-write probe finding the file absent requires a
+	* concurrent unlink between rename and stat; fall back to a sentinel version. */
+	versionAfterWrite(after, target) {
+		if (after) return after.version;
+		return FsVersion(`missing:${target.targetKey}`);
+	}
+};
+//#endregion
+export { LocalFileSystem, LocalFileSystem as default };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-fs-local`.
+* @module @deepseek-ai/dsh-fs-local/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-fs-local";
+/** Cordis companion plugin name. */
+const name = "fs-local-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this package exposes no independent event sequence or mutable data relation
+* beyond contracts enforced at its owning seam.
+*/
+const install = () => {};
+/**
+* Register this package's 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/fsio.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Cordis-free local filesystem mechanics. This provider layer returns validated UTF-8 text,
+ * streams large files, and rejects binary data; line windows belong to `dsh-tool-fs`. Writes
+ * stage an exclusive owner-only file in a private sibling directory and atomically publish it.
+ * @module @deepseek-ai/dsh-fs-local/fsio
+ */
+import type { BigIntStats } from 'node:fs';
+import { FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs';
+/**
+ * Test hook: lets specs pin the atomic-write temp names (to prove exclusive-open behavior without
+ * a name race), override native boundaries, and observe the staged temp file before publication.
+ */
+export interface FsIoInternals {
+    /** Override the host platform for native-publication unit coverage. */
+    platform?: NodeJS.Platform;
+    /** Override the generated private staging-dir name (relative to the target dir). */
+    tempDirName?: (writePath: string) => string;
+    /** Override the generated temp-file name (relative to the private staging dir). */
+    tempName?: (writePath: string) => string;
+    /** Override the Win32 DACL copy boundary. */
+    copyFileDacl?: (source: string, destination: string) => Promise<void>;
+    /** Override the Win32 security-preserving replacement boundary. */
+    replaceFile?: (replaced: string, replacement: string) => Promise<void>;
+    /** Override the hard-link no-replace publication boundary. */
+    linkFile?: (existingPath: string, newPath: string) => Promise<void>;
+    /** Override target inspection after guarded publication fails. */
+    inspectPublicationTarget?: (path: string) => Promise<BigIntStats>;
+    /** Override staging-directory removal for commit-point failure coverage. */
+    removeStagingDir?: (stagingDir: string) => Promise<void>;
+    /** Test hook after the temp file is written/synced but before final chmod+publication. */
+    inspectTemp?: (paths: {
+        stagingDir: string;
+        tempPath: string;
+    }) => void | Promise<void>;
+}
+/** A resolved local path: the absolute path shown to callers and its realpath identity. */
+export interface LocalTarget {
+    /** Absolute path (symlinks not resolved) — used for display. */
+    displayPath: string;
+    /** Realpath identity — used as the stable target key and the I/O path. */
+    targetKey: FsTargetKey;
+}
+/** Result of probing a path: null when it does not exist. */
+export interface PathInfo {
+    version: FsVersion;
+    mode: number;
+    type: 'file' | 'directory' | 'other';
+    size: number;
+}
+/** Result of probing a path without following the final symlink component. */
+export interface PathLinkInfo {
+    version: FsVersion;
+    mode: number;
+    type: 'file' | 'directory' | 'symlink' | 'other';
+    size: number;
+}
+/** One local directory child with a resolved target and cheap metadata. */
+export interface LocalDirEntry {
+    name: string;
+    type: 'file' | 'directory' | 'other';
+    target: LocalTarget;
+    version?: FsVersion;
+    size?: number;
+}
+/**
+ * Resolve a path to its absolute display path and realpath identity. For a missing target,
+ * realpath the nearest existing ancestor and append the missing suffix, preserving identity
+ * across symlinked ancestors before and after creation.
+ * @param cwd - base directory a relative `path` resolves against.
+ * @param path - absolute or relative path; empty/whitespace-only throws `FS_NOT_FOUND`.
+ * @returns the absolute display path plus the realpath-derived stable target key.
+ */
+export declare function resolveLocalTarget(cwd: string, path: string): Promise<LocalTarget>;
+/**
+ * Probe a path for its version, mode, type, and size. Null if absent.
+ * @param absolutePath - the path to stat (typically a target key; symlinks are followed).
+ * @returns the metadata, or null when the path — or a parent segment — does not exist.
+ */
+export declare function probe(absolutePath: string): Promise<PathInfo | null>;
+/**
+ * Probe a path without following the final symlink component.
+ * @param absolutePath - the path entry to inspect with `lstat` semantics.
+ * @returns path-entry metadata, or null when the entry is absent.
+ */
+export declare function probeNoFollow(absolutePath: string): Promise<PathLinkInfo | null>;
+/**
+ * List direct children of a directory in stable name order. Each child includes
+ * a resolved target plus stat metadata when still available; file contents are
+ * never read.
+ * @param target - the resolved directory to list; a missing or non-directory target throws.
+ * @param signal - aborts the listing, checked between children (`FS_ABORTED`).
+ * @returns one entry per direct child, sorted by name.
+ */
+export declare function listDirectory(target: LocalTarget, signal?: AbortSignal): Promise<LocalDirEntry[]>;
+/**
+ * Read a whole regular UTF-8 text file into a single decoded string. Rejects
+ * non-regular files, invalid UTF-8, and NUL-byte binary samples.
+ * @param target - the resolved file to read.
+ * @param signal - aborts the read (`FS_ABORTED`).
+ * @returns the full decoded text, byte-for-byte (no normalization).
+ */
+export declare function readWholeText(target: LocalTarget, signal?: AbortSignal): Promise<string>;
+/**
+ * Stream a whole regular UTF-8 text file as decoded text chunks. Same text
+ * semantics as {@link readWholeText} (regular-file check, binary/NUL rejection,
+ * cross-chunk UTF-8 decoding), but never holds the whole file in memory.
+ * @param target - the resolved file to stream.
+ * @param signal - aborts the stream, including between chunks (`FS_ABORTED`).
+ * @returns decoded text chunks in file order; chunk boundaries carry no meaning.
+ */
+export declare function streamWholeText(target: LocalTarget, signal?: AbortSignal): AsyncIterable<string>;
+/**
+ * Atomically replace a file through a private, synced staging file in the same directory.
+ * POSIX protects the staging directory and file with `0o700` and `0o600`. A new Windows file
+ * inherits the destination directory's DACL; a replacement copies the existing target's DACL
+ * onto the empty temp before writing and preserves the target descriptor at publication.
+ * @param absolutePath - destination; missing parent directories are created.
+ * @param content - the full UTF-8 text to write.
+ * @param mode - existing destination's POSIX mode to preserve, or `undefined` for a new file;
+ * inert as a mode on Windows but identifies replacement security semantics.
+ * @param signal - cancellation checked before final publication.
+ * @param internals - Test hook for pinning temp names and observing the staged file.
+ * @param createIfAbsent - when provided, publish with a hard-link no-replace
+ * primitive; a concurrent creator's file is preserved and this write is
+ * rejected with `FS_NOT_OBSERVED` using the supplied display path.
+ */
+export declare function writeFileAtomic(absolutePath: string, content: string, mode: number | undefined, signal: AbortSignal | undefined, internals?: FsIoInternals, createIfAbsent?: {
+    displayPath: string;
+}): Promise<void>;
+/** Line ending style detected before LF normalization. */
+export type LineEndings = 'LF' | 'CRLF';
+/**
+ * Collapse CRLF to LF — the canonical in-memory form every edit/diff basis
+ * uses. Lone `\r` bytes (not followed by `\n`) are left untouched.
+ * @param content - decoded text in whatever line-ending style the file had.
+ * @returns the text with every `\r\n` pair replaced by `\n`.
+ */
+declare function normalizeLineEndings(content: string): string;
+/**
+ * Convert LF-normalized content back to the line-ending style detected at read
+ * time, for write-back. `LF` returns the content unchanged; `CRLF` re-normalizes
+ * first so an already-CRLF sequence is never doubled to `\r\r\n`.
+ * @param content - the LF-normalized (edited) text.
+ * @param lineEndings - the original file's style, as detected by {@link readForEdit}.
+ * @returns the text in the original file's line-ending style.
+ */
+declare function restoreLineEndings(content: string, lineEndings: LineEndings): string;
+/**
+ * Read and decode a file for editing: rejects binaries, returns LF-normalized
+ * content plus the original line-ending style for write-back.
+ * @param absolutePath - the file to read (typically a target key).
+ * @param displayPath - the caller-facing path used in error messages.
+ * @param signal - aborts the read (`FS_ABORTED`).
+ * @returns the LF-normalized content and the detected style to restore on write-back.
+ */
+export declare function readForEdit(absolutePath: string, displayPath: string, signal?: AbortSignal): Promise<{
+    content: string;
+    lineEndings: LineEndings;
+}>;
+/**
+ * Best-effort overwrite diff basis. Binary, invalid UTF-8, a file at/above the byte limit,
+ * or a file deleted/made unreadable after the caller's preflight returns `null` so the write
+ * still succeeds and presentation falls back to a whole-file diff. The bound is enforced on
+ * the opened descriptor rather than a prior path stat, so concurrent external replacement or
+ * size changes cannot make this helper buffer more than `maxBytes`.
+ * @param absolutePath - the file to read (typically a target key).
+ * @param maxBytes - exclusive upper bound for bytes held as the contextual-diff basis.
+ * @param signal - aborts the read (`FS_ABORTED`); cancellation propagates, unlike I/O failure.
+ * @returns the LF-normalized text, or null for a non-regular, at/above-limit, binary, non-UTF-8,
+ * descriptor-size-changed, or unreadable file.
+ */
+export declare function readTextForDiff(absolutePath: string, maxBytes: number, signal?: AbortSignal): Promise<string | null>;
+/**
+ * Apply a literal replacement to LF-normalized content. Empty or missing search text throws
+ * `FS_EDIT_NOT_FOUND`; multiple matches throw `FS_AMBIGUOUS_EDIT` unless `replaceAll` is true.
+ * @param content - the current file content, already LF-normalized.
+ * @param oldString - literal text to find; CRLF inside it is normalized to LF before
+ *   matching.
+ * @param newString - literal replacement text, normalized the same way.
+ * @param replaceAll - replace every match instead of requiring exactly one.
+ * @param displayPath - the caller-facing path used in error messages.
+ * @returns the edited LF-normalized content plus how many occurrences were replaced.
+ */
+export declare function applyLiteralEdit(content: string, oldString: string, newString: string, replaceAll: boolean, displayPath: string): {
+    content: string;
+    replacements: number;
+};
+export { normalizeLineEndings, restoreLineEndings };
+//# sourceMappingURL=fsio.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Host-filesystem implementation of `ctx.fs`. Realpath-derived target identity makes aliases
+ * share stale guards, and writes through a symlink update its target without replacing the link.
+ * @module @deepseek-ai/dsh-fs-local
+ */
+import { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { FileSystem, FsVersion } from '@deepseek-ai/dsh-fs';
+import type { FsDirEntry, FsEditOutcome, FsEditRequest, FsInfo, FsPathInfo, FsTarget, FsWriteIntent, FsWriteOutcome } from '@deepseek-ai/dsh-fs';
+import type { FsIoInternals } from './fsio.ts';
+/** Configuration for the local filesystem backend. */
+export interface Config {
+    /** Base directory for relative paths. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /**
+     * Exclusive UTF-8 byte limit on each overwrite-diff side, capped by the
+     * runtime's safe allocation/decode maximum. Defaults to 10 MiB.
+     */
+    diffBasisMaxBytes?: number;
+}
+type ResolvedConfig = Required<Config>;
+/**
+ * The host-filesystem backend. Reads resolve relative paths from {@link Config.cwd}
+ * (a resolution default, NOT a containment boundary — see the filesystem
+ * capability-seam Agent Note); enforce
+ * containment with a stricter backend or a `tools/execute` permission plugin.
+ */
+export declare class LocalFileSystem extends FileSystem {
+    static Config: z<Config>;
+    /** Validated config (schemastery applied the defaults before construction). */
+    readonly config: ResolvedConfig;
+    /** Test hook forwarded to fsio for atomic-publication boundaries. */
+    internals: FsIoInternals;
+    /** Per-targetKey tail promise: serializes mutating ops so the read→guard→write
+     * window can't interleave, making concurrent writes/edits deterministically
+     * ordered (one wins, the rest see the new version and reject as stale). */
+    private locks;
+    constructor(ctx: Context, config: Config);
+    /** Run `op` with exclusive access to `targetKey` (FIFO per key). */
+    private withLock;
+    resolve(path: string, opts?: {
+        cwd?: string;
+        signal?: AbortSignal;
+    }): Promise<FsTarget>;
+    processPath(target: FsTarget): string;
+    fileUrl(target: FsTarget): string;
+    contains(parent: FsTarget, child: FsTarget): boolean;
+    stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>;
+    lstat(path: string, opts?: {
+        cwd?: string;
+    }, signal?: AbortSignal): Promise<FsPathInfo | undefined>;
+    readText(target: FsTarget, signal?: AbortSignal): Promise<string>;
+    streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>;
+    listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>;
+    writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal): Promise<FsWriteOutcome>;
+    editText(target: FsTarget, edit: FsEditRequest, expected?: {
+        version: FsVersion;
+    }, signal?: AbortSignal): Promise<FsEditOutcome>;
+    private versionAfterWrite;
+}
+export default LocalFileSystem;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-fs-local`.
+ * @module @deepseek-ai/dsh-fs-local/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "fs-local-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's 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/win32.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Windows security-descriptor helpers for atomic local-file replacement. Koffi loads lazily so
+ * non-Windows processes never open Win32 libraries.
+ * @module @deepseek-ai/dsh-fs-local/win32
+ */
+/**
+ * Read a file's self-relative DACL security descriptor.
+ * @param path - existing file whose DACL is read.
+ * @returns a descriptor buffer accepted by `SetFileSecurityW`.
+ */
+export declare function readFileDaclWin32(path: string): Promise<Buffer>;
+/**
+ * Copy an existing file's DACL onto another file and protect it from staging-parent inheritance.
+ * The destination must still be empty when confidentiality depends on this call.
+ * @param source - existing file whose DACL is copied.
+ * @param destination - existing file that receives the protected DACL.
+ */
+export declare function copyFileDaclWin32(source: string, destination: string): Promise<void>;
+/**
+ * Replace a Windows file while preserving the replaced file's ACL and other replace metadata.
+ * @param replaced - existing destination file.
+ * @param replacement - closed staging file on the same volume.
+ */
+export declare function replaceFileWin32(replaced: string, replacement: string): Promise<void>;
+//# sourceMappingURL=win32.d.ts.map

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@deepseek-ai/dsh-fs-local",
+  "description": "Local-filesystem implementation of the DeepSeek Harness filesystem seam (ctx.fs)",
+  "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-local"
+  },
+  "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-fs": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "dependencies": {
+    "koffi": "^3.1.0",
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-fs": "^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/cordis": "^4.0.1-rc.1"
+  }
+}