@t4r71/dsh-dual-axis 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 T4R71
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# @t4r71/dsh-dual-axis
+
+The dual-axis access-mode bundle (host half): the file sandbox's read and write axes — each `deny | workspace | all | custom`, with `custom` carrying absolute `allow` and `deny` path lists — as an installable profile layer with its Plugins-page configuration.
+
+## ⚠ This bundle disables an official UI row
+
+Installing this bundle turns OFF the upstream row `ui-permission`
+(`@deepseek-ai/dsh-client-ui-permission-presets`, declared in
+`@deepseek-ai/dsh-web-app`'s `cordis.patch.yml`) — see `cordis.patch.yml` in this package.
+That is a deliberate REPLACEMENT, not a coincidental clash, and it is not reversible by
+flipping `disabled: false` while this bundle is installed.
+
+**What is replaced.** This bundle's client half registers the same three surfaces the
+upstream row registers, which is why the two cannot both be active:
+
+| Surface | Upstream | This bundle |
+| --- | --- | --- |
+| Composer control | `conversation.input.permission` | same slot, two axis dropdowns instead of one preset picker |
+| General-settings row | `settings.general.item`, id `permission`, order `-20` | same slot and id |
+| `/permission` picker | `command.decorate({ name: 'permission' })` | same decoration, over the same command |
+
+Two independent mechanisms would fail a client boot with both rows active, so removing
+the disable is not an option:
+
+1. **`conversation.input.permission` is a single-occupant slot.** `ui-conversation`
+   declares it `{ kind: 'single', scope: 'session' }`, and a second registration throws
+   `single slot "<name>" already has a registration` (`packages/client/ui-slots/src/index.ts:1216-1218`).
+   Renaming a locale namespace does not address this.
+2. **Locale namespaces are single-occupant per (namespace, locale).** Both rows register
+   `permission.access` and `settings.permission`; the second `register` throws
+   `locale namespace "<ns>" already has locale "<locale>"`
+   (`packages/client/locale/src/client/index.ts:415-419`).
+
+**Behaviour that changes.** The composer control becomes two independent read/write axis
+dropdowns (`deny | workspace | all | custom`) submitting `/axis <axis>:<value>` instead of
+one preset picker submitting `/permission <preset>`. The General-settings row keeps its
+position and its default-preset meaning. The `/permission` slash picker keeps the upstream
+preset list.
+
+**To get the official UI back**, uninstall this bundle (drop `@t4r71/dsh-dual-axis` from the
+profile's `dsh.profile.bundles` and from its `package.json` dependencies). The row that
+carries the disable is this package's `cordis.patch.yml`, so it leaves with the bundle and
+`ui-permission` activates again. Leaving the bundle installed and editing the row to
+`disabled: false` restarts the collision above and the client hangs on "Loading plugins".
+
+## Model Experience
+
+The axes are stated to the model in a runtime-context paragraph of their own, contributed under the section name `sandbox:dual-axis` (order `SANDBOX_POLICY + 1`, so it follows 0.1.7's own `sandbox:policy` line rather than interrupting it). The paragraph names both axes as resolved ranges — every allow root and every deny root, not a mode name — and states how they are enforced, including the fact that this build does not intersect them. It is re-rendered at every assembly, so a mid-session axis change reaches the model on the next request.
+
+The paragraph is not a new model-visible input in the log sense: it is derived from the session's stored axis pair, the current definitions of the rule groups that pair references, and the session header's `cwd`, and the agent loop logs the rendered snapshot as model history like every other runtime-context entry. The refusal a fence returns is built from the same `src/scope-prompt.ts` functions, so the range the model read and the range it is denied by cannot disagree.
+
+The axes are NOT in the session log. A package-declared event type is outside 0.1.7's `KNOWN_SESSION_EVENT_TYPES`, and `Session.append` takes no envelope option, so such an event cannot be marked `ignorable` and a log carrying it is refused whole by `validateStoredEvents` — the session becomes unopenable after a restart. The pair therefore lives in this package's own settings namespace (see Settings below), and the only axis record left in a session log is the write base mirrored onto 0.1.7's own `sandbox/mode`.
+
+## What 0.1.7 removed, and what this package carries instead
+
+| Capability | 0.1.6 home | 0.1.7 state | This package |
+| --- | --- | --- | --- |
+| Axis algebra | `dsh-sandbox/access`, `dsh-sandbox/scope` | deleted (0 hits tree-wide) | `src/axis.ts`, `src/scope.ts` |
+| Per-session axis pair | `sandbox/mode` payload `readScope`/`writeScope` | payload locked to `{ mode, source }`; a plugin event type is refused whole by the log validator | `src/session-store.ts` (settings namespace `dual-axis-sessions`), with `src/session-axes.ts` mirroring the write base onto `sandbox/mode` |
+| Read-path fence | `dsh-fs-sandbox` (358 lines, 8 read overrides) | deleted; reads pass through | `src/fs-fence.ts` |
+| Settings section | `settings.register(ns, schema)` | only Loader-entry Config | `src/config.ts` |
+| Dual write entry | `setSandboxScopes` | only `setSandboxMode(session, mode)` | the store writes the pair; `mirrorWriteMode` writes the mode |
+
+## Layout
+
+| Path | Role |
+| --- | --- |
+| `src/axis.ts` | The four axis kinds, the mode bijection, `effectiveScopes` |
+| `src/scope.ts` | `resolveScope` / `scopeContains`: the pure allow/deny range algebra |
+| `src/config.ts` | Loader-entry `Config` with both axes `.volatile()`, and `normalizeScope` |
+| `src/session-store.ts` | The per-session axis pair: namespace `dual-axis-sessions`, the memoized read, the whole-document write with its revision-fence retry, and the GC sweep |
+| `src/session-axes.ts` | The write base's mirror onto 0.1.7's own `sandbox/mode` event |
+| `src/fs-fence.ts` | `DualAxisFileSystem`: the read-path fence |
+| `src/read-guard.ts` | The `/read-guard` entry point: the tool-dispatch fence for both axes |
+| `src/scope-prompt.ts` | The model-facing range text: one source for the runtime-context paragraph and the refusal |
+| `src/index.ts` | The plugin class: registers the axis command and the range paragraph, seeds each new session — a subagent child from its parent's stored pair (`inheritedAxes`), every other session from the settings row's live pair — and schedules the GC sweep |
+| `tests/seed-parity.spec.ts` | The cross-package drift gate: the same rows through this package's `seedPair` and through `@t4r71/dsh-dual-axis-ui`'s `sessionAxesSeed`, asserted byte for byte |
+| `src/fs.ts` | The `/fs` entry point exporting the backend |
+
+## Settings
+
+Two namespaces, both Loader entry ids, each field declared `.volatile()` because 0.1.7 refuses to project or write a non-volatile field.
+
+`dual-axis` is the row the Plugins page edits: the two axes a NEW session starts from (`read`, `write`), the rule-group library (`groups`), and the group ids a new session starts out referencing (`defaultGroups`). All four are SEEDS. For a session that has been USED they are read once, at creation, and never again; for one nobody has used yet the row stays live, and editing it moves that session's axes (see "A session with no record").
+
+A newly created session reads these values through `ctx.settings.describe()` rather than through the `Config` the plugin captured at mount: 0.1.7's loader does not commit a settings-page save back into that captured accessor, so reading it would keep seeding sessions with the value the process started on until the next restart. `describe()` re-projects the entry's live config on every call, which is the same read the settings row's own summary uses. A composition without the `settings` service falls back to the captured `Config`.
+
+```yaml
+- id: dual-axis
+  name: '@t4r71/dsh-dual-axis'
+  config:
+    read: { kind: all }
+    write: { kind: workspace }
+- id: dual-axis-sessions
+  name: '@t4r71/dsh-dual-axis/session-store'
+```
+
+`dual-axis-sessions` is the store: one field, `axes`, `session id -> { read, write }`. It is a separate entry rather than a field on the row above because the row's namespace carries the Plugins-page form, and a field the row's form does not declare is one more thing that form has to render around. The client half registers no page for this namespace.
+
+Every decision path reads the STORE, plus the group library by id, and nothing else — except for a session the store holds NO record of, where the row's seeds are the session's pair until the repair write lands (see "A session with no record"). Once a session has a record, the row's seeds are never consulted for it again. Reading is memoized on the namespace's `revision`, so a decision path pays one `settings.describe()` per document change rather than one per tool dispatch.
+
+### Writing, and what a lost write does
+
+The whole `axes` field is written in one `replace`, because removing a record needs the whole map anyway. Every attempt re-reads the namespace revision first, and a refused write is retried up to four times (0/25/75/200 ms) against the revision the other writer produced. If every attempt is refused the store throws `SessionAxesConflictError` (`code: 'DUAL_AXIS_AXES_CONFLICT'`); `/axis` renders that as a command error beside the picker, and the session-creation path logs it. A write is never reported as applied when it was not stored.
+
+### A session with no record
+
+A session with no record is not an error and it never hides a control. Every live decision path — the model-facing paragraph, the read fence, and `/axis` — reads through `SessionAxesStore.ensure`, which answers `seedPair` (`seedAxesFor`'s pure core): the settings row's `read`/`write` plus its `defaultGroups`, or, for a subagent child, its parent's stored pair. That value is what the session runs under and what the pickers show, so "interface shows A, host enforces B" cannot happen.
+
+### When the record is written
+
+The record is written when the session is USED, not when it is created. `pin` writes at creation only for a session that already has content, and `ensure` schedules its repair write only for one that does; a session with neither a record nor any content is answered by a seed RECOMPUTED ON EVERY READ, so the settings row stays live for it.
+
+This matters because of how a conversation actually starts. The workspace picker reopens the SAME session id when you start a new conversation in the same workspace — measured, not assumed: two consecutive "new session in nvidiaDlssGlom" clicks left `[data-conversation-session]` at the same id, and the workspace's session list was unchanged. Freezing at creation therefore pinned a conversation nobody had had to whatever the row said the day the picker first opened it, and later edits never reached it. A session that has been used freezes as before: the record is the session's own pair from then on.
+
+**"Used" means content beyond the loop's own runtime-context snapshot** (`src/content.ts`, `hasContent`). The agent loop appends that snapshot on every turn, the first included, before any human input exists, so counting it would make every session look used the moment anything rendered its prompt. It is identified by `source.kind === 'runtime-context'`, the discriminant the loop writes and reads back, rather than by its rendered text, which is prose that changes with every contribution. Every other message counts — a real user turn, an assistant reply, the skill catalogue — because each means the session has entered a turn. The predicate walks the session's already-materialized event array with no copy or parse per event, and the sessions it is asked about are exactly the ones nobody has used, so the scan is short.
+
+Two writes therefore freeze a pair, and both are deliberate: the first real turn, and `/axis` — which calls `SessionAxesStore.set` unconditionally, so a manual pick freezes an empty session too, and the manual value wins over any later settings-row edit.
+
+### Degenerate states
+
+A repair never overwrites a record that appeared while it was waiting, and a repair that cannot be stored is logged and re-armed, never thrown at the decision path that scheduled it.
+
+`DEFAULT_AXES` (read `all`, write `workspace`) is what `SessionAxesStore.getOr` answers for a caller that holds no session to build a seed from; it is not the pair a session with no record is held to. `getOr`'s remaining callers hold no session, because `ensure` — which the live paths use — is the one that can answer a seed. An unreadable settings row answers `DEFAULT_AXES` on BOTH sides — `seedPair` and the client half's `SESSION_AXES_FALLBACK` — so even the failure branch agrees.
+
+The client half recomputes that same seed locally (`sessionAxesSeed` in `@t4r71/dsh-dual-axis-ui`, which shares no import with this package), because it must display the pair this host is enforcing for a session the document carries no record of. `tests/seed-parity.spec.ts` feeds both implementations the same rows and asserts the answers are the same bytes, key order included; it is the only thing that stops the two from drifting.
+
+### Garbage collection
+
+Records are dropped when the session they belong to no longer exists, and the signal is the persistence layer: an id absent from `sessionPersistence.list()` has no stored log. The sweep runs at start-up (15 s in, after the loader and the persistence backend are up) and every 30 s after that. It never runs on `session/disposed` — residency churn disposes a session whose file is still on disk, and dropping that record would silently reset a session about to be resumed. A sweep that cannot judge (no persistence service, or a failed listing) removes nothing and says so in the log.
+
+## Building
+
+The package resolves every `@deepseek-ai/*` import from its own `node_modules`: `pnpm install` then `tsc -b` and `tsdown` work in a directory tree that contains nothing but this package. `tsconfig.base.json` holds the compiler options this package needs and declares no `paths`; `tsconfig.json` adds only the package's own entry point.
+
+Tests run from source through tsx (`TSX_TSCONFIG_PATH=tsconfig.runtime.json node --import tsx/esm --test tests/*.spec.ts`) and resolve the same way, with one exception: `tests/settings.spec.ts` and `tests/session-store.spec.ts` read `isVolatilePath` and `volatileForm` from `@deepseek-ai/dsh-settings/schema`, and that package ships `lib/types/schema.js` while declaring no `./schema` subpath in its exports map, so Node cannot resolve the specifier. `tsconfig.runtime.json` maps that one specifier to the shipped file inside the installed dependency. Dropping the mapping requires `@deepseek-ai/dsh-settings` to export `./schema`.
+
+## Known Limitations and Deferred Work
+
+- **The write axis is NOT intersected with the read axis.** This build enforces the two axes independently: `read-guard` grades a write call with the write axis's deny list alone, and the inherited write fence grades the same call by the write axis's base mode. A path the read axis denies is therefore still writable when the write axis allows it. The client half's settings copy states the opposite (`读轴放行、写轴不放行，仍然写不了`), so the copy and the enforcement disagree. The runtime-context paragraph states the enforced behavior, not the intended invariant.
+- **The read axis is enforced at the tool-dispatch layer only.** `read-guard` inspects the four read entry points in its `READ_TOOLS` table (`read`, `read_image`, `grep`, `glob`); a command tool, a child process, or a script is fenced for writes by the sandbox mode but never for reads. Mounting `DualAxisFileSystem` closes that path for `ctx.fs` consumers, which does not include command tools.
+- The refusal text tells the model that reaching a refused path through another tool is not a permitted workaround. That is a rule statement; the enforcement gap above is the reason it cannot be stated as a fence. It also states the layering per axis: the read axis and either axis's allow/deny path entries bind the tool layer alone, while only a write axis's BASE tier is mirrored onto the session sandbox mode and enforced again below that layer — an `all` base mirrors to `danger-full-access` and so has no layer below.
+- **A subagent child whose parent session holds no record falls back to the settings row.** `inheritedAxes` looks the parent's record up by the id the child's header names, resident or not, and returns `undefined` when that id has no record; the child is then seeded with the settings-page pair. It is still seeded, which is what keeps the read fence from falling back to the deployment defaults for that child. Residency deliberately does not participate: the client half reads the same document by the same id and cannot observe which sessions this process has materialized, so keying the seed on residency would make the two halves disagree for exactly that child.
+
+- `DualAxisFileSystem` (`src/fs-fence.ts`) is **not mounted and not wired**. No profile composes its row — the shipped `cordis.patch.yml` carries it commented out, because mounting it means taking the `fs` service from the composition's own `fs-sandbox` row — and its per-call `ReadAxes` trailing parameter has no producer: 0.1.7's `SandboxExecutionPolicy` has no `readScope`/`writeScope` members, so a consumer that does not thread the pair gets the deployment DEFAULT read axis, never this package's per-session store. The read fence actually in force is `read-guard.ts`. The module is kept for `readAxisRefusal` / `readAxisRefusalAsync`, the canonical read-axis containment predicates, and for an operator who replaces the filesystem backend by hand (disable `fs-sandbox`, mount this row, and thread the axes).
+- The client half lives in a separate package (`@t4r71/dsh-dual-axis-ui`); this package declares no `dsh.client`.
+

package/cordis.patch.yml

@@ -0,0 +1,68 @@
+# The dual-axis bundle patch: one row inserting the dual-axis host half, with the
+# two axes a newly created session starts from as its composition config.
+#
+# The row id `dual-axis` is load-bearing twice over in 0.1.7:
+#   - it is the Loader entry id, and thus the settings namespace
+#     (`SettingsForms.write` looks the entry up by `options.id`);
+#   - prefixed with this package's name it forms the `plugins.row.config` slot
+#     entry key the client half registers under.
+#
+# The browser half rides this same row: in 0.1.7 a client entry's id IS its
+# package name (WebBootEntry.id, client/modules/src/client/manifest.ts:53), and
+# dsh.client is one object per package, so both client surfaces — the settings
+# row and the two composer dropdowns — live in the single bundle behind
+# exports["./client"].
+
+- insert:
+    - id: dual-axis
+      name: '@t4r71/dsh-dual-axis'
+      config:
+        read: { kind: all }
+        write: { kind: workspace }
+    # 文件系统半边刻意不在这里挂行：它要接管 `fs` 服务，而本体那一行已经注册了同一个
+    # 服务，两行同时活动会让启动直接失败（required 行不激活 = startup failed）。它同时
+    # 也救不了读轴 —— 0.1.7 的读路径不带会话，那一半永远拿不到要判的轴。要手工换掉
+    # 文件系统后端的话，得同时禁用本体的 `fs-sandbox` 行，见本包 README。
+
+    # 读轴围栏：本体 0.1.7 的读路径不带会话，读轴只能靠工具派发层执行。
+    - id: dual-axis-read-guard
+      name: '@t4r71/dsh-dual-axis/read-guard'
+
+    # 每条会话那对轴的权威存储。这是一行**独立**的 Loader entry，id 就是设置命名空间
+    # （0.1.7 里 ns == entry id），字段只有 `axes`：会话 id → 轴对。
+    #
+    # 为什么不塞进上面那行的 Config：那一行的 ns 绑着设置页的行表单，多一个未声明字段
+    # 会被投影进那张表单；而这一行的 Config 只声明 `axes` 一个 volatile 字段，
+    # 设置页不渲染它（客户端半边没有为它注册行）。
+    - id: dual-axis-sessions
+      name: '@t4r71/dsh-dual-axis/session-store'
+
+    # 纯客户端半边所在的包。它的宿主半边是空插件，这一行存在的唯一理由是
+    # 0.1.7 的客户端扫描只处理有 Loader 行的包。
+    - id: dual-axis-ui
+      name: '@t4r71/dsh-dual-axis-ui'
+
+# 本体的权限界面行：本包的两个界面面取代它，因此必须先禁掉它。
+#
+# 为什么必须禁：本包的浏览器半边注册的是本体那三个界面面本身 —— 同一个
+# `conversation.input.permission` 槽、同一条 `settings.general.item` 行
+# （id `permission`、order -20）、同一个 `/permission` 命令装饰。两条独立的独占
+# 规则因此都会在第二方 apply() 里抛错，fiber 落进 FAILED，客户端启动审计报
+# 「1 entry did not activate」：
+#   - 槽是**单占**的：ui-conversation 把 `conversation.input.permission` 声明为
+#     `{ kind: 'single', scope: 'session' }`，二次注册抛
+#     `single slot "…" already has a registration`
+#     （client/ui-slots/src/index.ts:1216-1218）。改 locale 命名空间绕不开它。
+#   - locale 命名空间按 (ns, locale) **单占**：两侧都注册 `permission.access` 与
+#     `settings.permission`，二次注册抛
+#     `locale namespace "…" already has locale "…"`
+#     （client/locale/src/client/index.ts:415-419）。
+# 这不是可接受的降级：取代关系必须由这个补丁表达，而不是由安装方记得少装一个包。
+# 用户要拿回官方界面，得卸掉本组合包（本行随它一起走），而不是把这里改回 enabled。
+#
+# 这里刻意写出 name：补丁引擎在 name 与目标行不符时打一条警告并跳过
+# （vendor/include/src/index.ts:115-118）。那条警告是安全阀 —— 本体改了那行的包名时，
+# 补丁不再生效而不是误伤同 id 的别的行。
+- id: ui-permission
+  name: '@deepseek-ai/dsh-client-ui-permission-presets'
+  disabled: true

package/lib/fs.js

@@ -0,0 +1,419 @@
+import { SandboxedFileSystem } from "@deepseek-ai/dsh-fs-sandbox";
+import { FsError } from "@deepseek-ai/dsh-fs";
+import { stat } from "node:fs/promises";
+import { dirname, sep } from "node:path";
+import { canonicalPath, writableRoots } from "@deepseek-ai/dsh-sandbox";
+//#region lib/types/containment.js
+/**
+* 目标路径包含判定：把上游 `@deepseek-ai/dsh-fs-sandbox/containment` 的
+* `isPathUnder` 原样内联到本包。
+*
+* 为什么必须内联：fs-sandbox@0.1.7-rc.2 的**发布包** exports 只开出
+* `.`、`./src/*` 与 `./package.json` 三条，**没有 `./containment`**；
+* 而源码工作区里该文件存在，靠路径解析能直接命中。于是同一个 import 在
+* 工作区里编译通过、装成 tgz 后运行期必然抛
+* `Package subpath './containment' is not defined by "exports"`，
+* 使 dual-axis 这个 entry 永远无法激活（fiberPhase 恒为 null）。
+* 自有副本消除这个 install-shape 依赖。
+* @module @t4r71/dsh-dual-axis/containment
+*/
+const MISSING_CODES = /* @__PURE__ */ new Set(["ENOENT", "ENOTDIR"]);
+function isMissing(error) {
+	const code = error.code;
+	return MISSING_CODES.has(code);
+}
+function comparablePath(path, caseSensitive) {
+	return caseSensitive ? path : path.toLowerCase();
+}
+function isLexicallyUnder$1(path, root, caseSensitive) {
+	const comparableTarget = comparablePath(path, caseSensitive);
+	const comparableRoot = comparablePath(root, caseSensitive);
+	if (comparableTarget === comparableRoot) return true;
+	const prefix = comparableRoot.endsWith(sep) ? comparableRoot : comparableRoot + sep;
+	return comparableTarget.startsWith(prefix);
+}
+async function statIfPresent(path) {
+	try {
+		return await stat(path, { bigint: true });
+	} catch (error) {
+		if (isMissing(error)) return void 0;
+		throw error;
+	}
+}
+function sameIdentity(left, right) {
+	return left.dev === right.dev && left.ino === right.ino;
+}
+/**
+* Determine whether a canonical target is a writable root or lies beneath it.
+* The lexical fast path handles normal canonical spellings. When spellings
+* differ, walk the target's existing ancestors and compare filesystem identity
+* with the root; this recognizes Windows long-name/8.3 aliases and casing
+* without weakening containment to a textual approximation.
+* @param path - canonical target key, which may end in a missing suffix.
+* @param root - canonical writable root.
+* @param caseSensitive - whether lexical comparison preserves case; defaults
+*   to the host filesystem convention used by supported platforms.
+* @returns whether the target is the root or a descendant of it.
+*/
+async function isPathUnder(path, root, caseSensitive = process.platform !== "win32") {
+	if (isLexicallyUnder$1(path, root, caseSensitive)) return true;
+	const rootInfo = await statIfPresent(root);
+	if (!rootInfo) return false;
+	let ancestor = path;
+	while (true) {
+		const ancestorInfo = await statIfPresent(ancestor);
+		if (ancestorInfo && sameIdentity(ancestorInfo, rootInfo)) return true;
+		const parent = dirname(ancestor);
+		if (parent === ancestor) return false;
+		ancestor = parent;
+	}
+}
+//#endregion
+//#region lib/types/axis.js
+/** The default READ axis: every mode permitted reading before the axes existed, so the whole host. */
+const DEFAULT_READ_SCOPE = { kind: "all" };
+/**
+* The write scope a legacy `mode` means.
+* @param mode - the sandbox mode.
+* @returns the equivalent write scope.
+*/
+function scopeOfMode(mode) {
+	switch (mode) {
+		case "read-only": return { kind: "deny" };
+		case "workspace-write": return { kind: "workspace" };
+		case "danger-full-access": return { kind: "all" };
+	}
+}
+/**
+* Read the axis pair a resolved policy carries, falling back to the defaults.
+* The policy's `mode` is authoritative for the write axis's BASE: a policy
+* that carries no write axes writes exactly what its mode always meant, so
+* every pre-existing policy keeps its exact behavior.
+*
+* 0.1.7's `SandboxExecutionPolicy` has no `readScope` / `writeScope`
+* members (only `mode`, `workspaceRoot`, `sessionId?`), so the axes arrive
+* through the extra argument this package's own fence passes. The
+* `mode`-derived fallback keeps the function total for the upstream type.
+* @param policy - the resolved policy (supplies `mode`).
+* @param axes - the session's axis pair, when the caller holds one.
+* @returns both axes in force.
+*/
+function effectiveScopes(policy, axes) {
+	return {
+		read: axes?.read ?? DEFAULT_READ_SCOPE,
+		write: axes?.write ?? scopeOfMode(policy.mode)
+	};
+}
+//#endregion
+//#region lib/types/scope.js
+/**
+* The shared path-range ALGEBRA behind both access axes: one pure evaluation
+* from an {@link AxisScope} to the canonical allow and deny root sets the
+* fence consumes.
+*
+* This is the 0.1.7 port of 0.1.6's `@deepseek-ai/dsh-sandbox/scope`
+* (152 lines), reduced to what a fence needs and made source-agnostic:
+*
+* - `workspace` derives its roots from 0.1.7's own
+*   `writableRoots(policy)` (`@deepseek-ai/dsh-sandbox`, re-exported from
+*   `packages/sandbox/sandbox/src/roots.ts:52`), so the fence agrees with
+*   the Seatbelt profile and the write fence by construction.
+* - Containment itself is NOT evaluated here. 0.1.6 took the enforcement
+*   layer's `contains` predicate as a parameter; this port keeps that shape
+*   but narrows it to the SYNCHRONOUS lexical predicate the pure tests use,
+*   and the filesystem-identity fallback lives in the fence
+*   (`fs-fence.ts`), which is where the canonical target key exists.
+*
+* `resolveScope` returns the sets; the fence applies them with deny-wins
+* precedence through {@link scopeContains}.
+*
+* @module @t4r71/dsh-dual-axis/scope
+*/
+/** Thrown when a configured `custom` scope entry cannot name an absolute path. */
+var ScopeConfigError = class extends Error {
+	entry;
+	value;
+	constructor(entry, value) {
+		super(`sandbox scope: \`${entry}\` entry ${JSON.stringify(value)} must be a non-empty absolute path`);
+		this.entry = entry;
+		this.value = value;
+		this.name = "ScopeConfigError";
+	}
+};
+/** Canonicalize one configured custom entry, failing closed on anything that cannot name an absolute host path. */
+function canonicalEntry(value, entry) {
+	if (value.trim().length === 0 || !isAbsoluteSpelling(value)) throw new ScopeConfigError(entry, value);
+	return canonicalPath(value);
+}
+/**
+* Whether a configured path is spelled absolutely on this host. Both POSIX
+* (`/x`) and Windows (`C:\\x`, `\\\\server\\share`) spellings are accepted
+* because a policy may be authored for one world and resolved in another; the
+* canonical resolution that follows is what actually binds it to this host.
+* @param path - the configured path spelling.
+* @returns whether the spelling is absolute.
+*/
+function isAbsoluteSpelling(path) {
+	return path.startsWith("/") || /^[A-Za-z]:[\\/]/.test(path) || path.startsWith("\\\\");
+}
+/**
+* Evaluate one axis against a workspace root. `deny` permits nothing;
+* `workspace` yields the shared writable roots; `all` is unbounded;
+* `custom` yields its base plus its own additions, with its removals listed
+* separately so the fence can apply them with precedence.
+*
+* A `custom` scope whose base is `all` stays unbounded: "everything except
+* these directories" is still everything-except, so its removals must survive
+* into {@link ResolvedScope.deny} rather than being flattened into an allow
+* list that could not express them.
+* @param scope - the axis value.
+* @param policy - the workspace root `workspace` and `custom` scopes resolve against.
+* @returns the evaluated range.
+* @throws {ScopeConfigError} when a `custom` entry is not a non-empty absolute path.
+*/
+function resolveScope(scope, policy) {
+	if (scope.kind !== "custom") return resolveBase(scope.kind, policy);
+	const base = resolveBase(scope.base, policy);
+	const allow = [...base.allow, ...scope.allow.map((entry) => canonicalEntry(entry, "allow"))];
+	const deny = scope.deny.map((entry) => canonicalEntry(entry, "deny"));
+	return {
+		unbounded: base.unbounded,
+		allow: dedupe(allow),
+		deny: dedupe(deny)
+	};
+}
+/** Evaluate a base (or closed) kind — the shared half of {@link resolveScope}. */
+function resolveBase(base, policy) {
+	switch (base) {
+		case "deny": return {
+			unbounded: false,
+			allow: [],
+			deny: []
+		};
+		case "workspace": return {
+			unbounded: false,
+			allow: dedupe(writableRoots({
+				mode: "workspace-write",
+				workspaceRoot: policy.workspaceRoot
+			})),
+			deny: []
+		};
+		case "all": return {
+			unbounded: true,
+			allow: [],
+			deny: []
+		};
+	}
+}
+/** Stable-order dedupe: keeps the first spelling of each value. */
+function dedupe(values) {
+	return [...new Set(values)];
+}
+/**
+* Whether `target` is the root itself or lies beneath it, by canonical
+* spelling. Case-insensitive on Windows, matching that filesystem's
+* convention.
+* @param target - canonical target path.
+* @param root - canonical root path.
+* @param caseSensitive - whether lexical comparison preserves case; defaults to the host convention.
+* @returns whether the target is the root or a descendant of it.
+*/
+function isLexicallyUnder(target, root, caseSensitive = process.platform !== "win32") {
+	const comparableTarget = caseSensitive ? target : target.toLowerCase();
+	const comparableRoot = caseSensitive ? root : root.toLowerCase();
+	if (comparableTarget === comparableRoot) return true;
+	const prefix = comparableRoot.endsWith(sep) ? comparableRoot : comparableRoot + sep;
+	return comparableTarget.startsWith(prefix);
+}
+/**
+* Whether `targetKey` is permitted by an evaluated scope. Removal wins over
+* addition: a deny root containing the target refuses it even when an allow
+* root — or an unbounded axis — would otherwise permit it.
+* @param scope - the evaluated scope.
+* @param targetKey - the target's canonical identity key (the resolved path).
+* @param contains - the containment predicate; defaults to {@link isLexicallyUnder}.
+* @returns whether the scope permits the target.
+*/
+function scopeContains(scope, targetKey, contains = isLexicallyUnder) {
+	for (const root of scope.deny) if (contains(targetKey, root)) return false;
+	if (scope.unbounded) return true;
+	for (const root of scope.allow) if (contains(targetKey, root)) return true;
+	return false;
+}
+//#endregion
+//#region lib/types/fs-fence.js
+/**
+* Decide whether one read axis permits one canonical target key. This is the
+* fence's entire decision, as a pure function: it takes the evaluated range and
+* the containment predicate, so a test can exercise every branch with no
+* filesystem, no session, and no service.
+*
+* The error message names the READ axis's kind, never the mode that would
+* spell it: a read axis of `workspace` would otherwise be reported as
+* "workspace-write", a WRITE mode name this axis has no concept of.
+* @param read - the read axis in force.
+* @param policy - the workspace root a `workspace` read axis derives from.
+* @param targetKey - the target's canonical identity key.
+* @param contains - the containment predicate.
+* @returns `undefined` when permitted, or the refusal message.
+*/
+function readAxisRefusal(read, policy, targetKey, contains) {
+	if (scopeContains(resolveScope(read, policy), targetKey, contains)) return void 0;
+	return refuse(read);
+}
+/**
+* The async twin of {@link readAxisRefusal}: production containment
+* (`isPathUnder`) walks the filesystem identity chain for alias-equivalent
+* roots, so the fence cannot use the lexical predicate alone.
+* @param read - the read axis in force.
+* @param policy - the workspace root a `workspace` read axis derives from.
+* @param targetKey - the target's canonical identity key.
+* @param contains - the async containment predicate.
+* @returns `undefined` when permitted, or the refusal message.
+*/
+async function readAxisRefusalAsync(read, policy, targetKey, contains) {
+	const scope = resolveScope(read, policy);
+	for (const root of scope.deny) if (await contains(targetKey, root)) return refuse(read);
+	if (scope.unbounded) return void 0;
+	for (const root of scope.allow) if (await contains(targetKey, root)) return void 0;
+	return refuse(read);
+}
+/**
+* The single refusal message both predicates return, naming the READ axis's
+* kind rather than the write mode that would spell it.
+* @param read - the refused read axis.
+* @returns the refusal message.
+*/
+function refuse(read) {
+	return `file access denied under the ${read.kind} read axis`;
+}
+/**
+* The read-axis-enforcing filesystem backend. Mount it in place of
+* `@deepseek-ai/dsh-fs-sandbox`: it registers the same `fs` service and
+* inherits that backend's write fence verbatim.
+*/
+var DualAxisFileSystem = class extends SandboxedFileSystem {
+	constructor(ctx, config) {
+		super(ctx, config);
+	}
+	/**
+	* The read axis pair of the session a read belongs to. Reads carry no
+	* session, so the fence resolves the DEPLOYMENT default axes here; a caller
+	* that knows the calling session passes them per call instead.
+	* @returns the deployment default axis pair.
+	*/
+	defaultAxes() {
+		return effectiveScopes(this.ctx.sandboxPolicy.resolve());
+	}
+	/**
+	* Fence the caller's read path against the READ axis, then return the target
+	* for the inherited read. The check happens BEFORE any disk access.
+	* @param target - the target the caller already resolved.
+	* @param axes - the calling session's axis pair; omit for the deployment default.
+	* @returns the same target, once the read axis permits it.
+	* @throws {FsError} `FS_SANDBOX_DENIED` when the read axis refuses the target.
+	*/
+	async checkedRead(target, axes) {
+		const policy = this.ctx.sandboxPolicy.resolve();
+		const refusal = await readAxisRefusalAsync(axes?.read ?? this.defaultAxes().read, policy, target.targetKey, isPathUnder);
+		if (refusal !== void 0) throw new FsError(`cannot read "${target.displayPath}": ${refusal}`, "FS_SANDBOX_DENIED");
+		return target;
+	}
+	/**
+	* Fence `lstat`'s string path by resolving the same target the inherited
+	* implementation will inspect, then applying the read axis. The resolution
+	* happens BEFORE the metadata read, so a refusal never touches the disk, and
+	* the inherited call still receives the original arguments verbatim.
+	* @param path - the requested path, relative to `opts.cwd` or the backend cwd.
+	* @param opts - optional cwd for the resolution.
+	* @param axes - the calling session's axis pair; omit for the deployment default.
+	* @returns the target the inherited `lstat` will inspect.
+	*/
+	async checkedReadPath(path, opts, axes) {
+		return this.checkedRead(await this.resolve(path, opts), axes);
+	}
+	/**
+	* Fence the read by the per-call read axis, then delegate to the inherited
+	* UTF-8 read.
+	* @param target - the resolved target to read.
+	* @param signal - aborts the read.
+	* @param axes - the calling session's axis pair; omit for the deployment default.
+	* @returns the file content from the inherited backend.
+	*/
+	async readText(target, signal, axes) {
+		return super.readText(await this.checkedRead(target, axes), signal);
+	}
+	/**
+	* Fence the read by the per-call read axis, then delegate to the inherited
+	* streaming read. The fence runs BEFORE the iterable is handed out: a refused
+	* stream never produces a chunk.
+	* @param target - the resolved target to stream.
+	* @param signal - aborts the read.
+	* @param axes - the calling session's axis pair; omit for the deployment default.
+	* @returns the inherited chunk iterable.
+	*/
+	async streamText(target, signal, axes) {
+		return super.streamText(await this.checkedRead(target, axes), signal);
+	}
+	/**
+	* Fence the read by the per-call read axis, then delegate to the inherited
+	* bounded byte read.
+	* @param target - the resolved target to read.
+	* @param signal - aborts the read.
+	* @param maxBytes - inclusive byte cap on the complete content.
+	* @param axes - the calling session's axis pair; omit for the deployment default.
+	* @returns the file bytes from the inherited backend.
+	*/
+	async readBytes(target, signal, maxBytes, axes) {
+		return super.readBytes(await this.checkedRead(target, axes), signal, maxBytes);
+	}
+	/**
+	* Fence the read by the per-call read axis, then delegate to the inherited
+	* byte-window read.
+	* @param target - the resolved target to read.
+	* @param range - `offset` and `length` of the window.
+	* @param signal - aborts the read.
+	* @param axes - the calling session's axis pair; omit for the deployment default.
+	* @returns the byte window from the inherited backend.
+	*/
+	async readByteRange(target, range, signal, axes) {
+		return super.readByteRange(await this.checkedRead(target, axes), range, signal);
+	}
+	/**
+	* Fence the listing by the per-call read axis, then delegate to the inherited
+	* directory listing.
+	* @param target - the resolved directory to list.
+	* @param signal - aborts the listing.
+	* @param axes - the calling session's axis pair; omit for the deployment default.
+	* @returns the directory entries from the inherited backend.
+	*/
+	async listDir(target, signal, axes) {
+		return super.listDir(await this.checkedRead(target, axes), signal);
+	}
+	/**
+	* Fence the metadata read by the per-call read axis, then delegate to the
+	* inherited stat.
+	* @param target - the resolved target to inspect.
+	* @param signal - aborts the metadata read.
+	* @param axes - the calling session's axis pair; omit for the deployment default.
+	* @returns the metadata, or `undefined` when the target is absent.
+	*/
+	async stat(target, signal, axes) {
+		return super.stat(await this.checkedRead(target, axes), signal);
+	}
+	/**
+	* Fence the no-follow metadata read by the per-call read axis, then delegate
+	* to the inherited lstat with the caller's arguments unchanged.
+	* @param path - the requested path, relative to `opts.cwd` or the backend cwd.
+	* @param opts - optional cwd for the resolution.
+	* @param signal - aborts the metadata read.
+	* @param axes - the calling session's axis pair; omit for the deployment default.
+	* @returns the path-entry metadata, or `undefined` when the entry is absent.
+	*/
+	async lstat(path, opts, signal, axes) {
+		await this.checkedReadPath(path, opts, axes);
+		return super.lstat(path, opts, signal);
+	}
+};
+//#endregion
+export { DualAxisFileSystem, DualAxisFileSystem as default, readAxisRefusal, readAxisRefusalAsync };