@t4r71/dsh-dual-axis 0.1.0

package/lib/types/fs-fence.d.ts

@@ -0,0 +1,196 @@
+/**
+ * The READ-AXIS FENCE: the filesystem backend that enforces the session's read
+ * axis in addition to 0.1.7's write fence.
+ *
+ * NOT MOUNTED, AND NOT WIRED TO THE SESSION AXIS STORE.
+ *
+ * Both facts are deliberate and both are load-bearing for anyone reading this
+ * file, so they are stated here rather than left to the composition:
+ *
+ * - NOT MOUNTED. No profile composes the `dual-axis-fs` row; this package's own
+ *   `cordis.patch.yml` carries it commented out, because installing this backend
+ *   means taking the `fs` service away from the composition's own
+ *   `fs-sandbox` row (`packages/fs/fs-sandbox/src/index.ts`), and two live rows
+ *   registering one service fail startup outright.
+ * - NOT WIRED. {@link ReadAxes} is a TRAILING PARAMETER on each override, the
+ *   0.1.6 way of threading a policy. Nothing produces it: the session-qualified
+ *   read fence actually in force is `./read-guard.ts`, which takes its session
+ *   from `tools/pre-execute` because 0.1.7's filesystem read path carries no
+ *   session at all. A caller that supplies no axes gets
+ *   {@link DualAxisFileSystem.defaultAxes}, i.e. the deployment policy — never
+ *   this package's per-session axis store (`./session-store.ts`). Mounting this
+ *   backend WITHOUT wiring it therefore enforces the deployment default read
+ *   axis for every session, which is not what the two composer dropdowns say.
+ *
+ * What it is still worth keeping for: {@link readAxisRefusal} and
+ * {@link readAxisRefusalAsync} are the canonical containment predicates for a
+ * read axis (sync lexical, async identity-resolving), and `tests/axis.spec.ts`
+ * exercises every branch of them with no filesystem, session, or service.
+ * Retiring the subclass means retiring that coverage with it.
+ *
+ * 0.1.7 deleted the read fence outright. Its `@deepseek-ai/dsh-fs-sandbox`
+ * (147 lines) states the removal in its own header: "Reads pass through
+ * untouched: every mode permits reading", and it overrides only
+ * `writeText` / `editText`. 0.1.6's 358-line version fenced eight read
+ * entry points. This subclass restores that fence on 0.1.7's own interface.
+ *
+ * It extends 0.1.7's `SandboxedFileSystem` rather than `LocalFileSystem`, so
+ * the write fence is inherited unchanged and this class adds exactly one
+ * thing: the read-path check. Every read override delegates to `super`,
+ * which is the sandboxed write class's own inherited implementation — no
+ * storage mechanic is re-implemented here.
+ *
+ * The fence is a policy check in TRUSTED code over a MODEL-CONTROLLED path,
+ * NOT a kernel boundary: canonicalize-then-contain is the complete answer to
+ * this surface.
+ *
+ * @module @t4r71/dsh-dual-axis/fs-fence
+ */
+import { Context } from '@deepseek-ai/cordis';
+import { SandboxedFileSystem } from '@deepseek-ai/dsh-fs-sandbox';
+import type { FsDirEntry, FsInfo, FsPathInfo, FsTarget } from '@deepseek-ai/dsh-fs';
+import { type AxisScope, type EffectiveScopes } from './axis.ts';
+/** The axis pair a read carries; omitted members fall back to the deployment default. */
+export type ReadAxes = Partial<Pick<EffectiveScopes, 'read'>>;
+/**
+ * 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.
+ */
+export declare function readAxisRefusal(read: AxisScope, policy: {
+    workspaceRoot: string;
+}, targetKey: string, contains: (path: string, root: string) => boolean): string | undefined;
+/**
+ * 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.
+ */
+export declare function readAxisRefusalAsync(read: AxisScope, policy: {
+    workspaceRoot: string;
+}, targetKey: string, contains: (path: string, root: string) => Promise<boolean>): Promise<string | undefined>;
+/**
+ * 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.
+ */
+export declare class DualAxisFileSystem extends SandboxedFileSystem {
+    constructor(ctx: Context, config: ConstructorParameters<typeof SandboxedFileSystem>[1]);
+    /**
+     * 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.
+     */
+    protected defaultAxes(): EffectiveScopes;
+    /**
+     * 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.
+     */
+    protected checkedRead(target: FsTarget, axes?: ReadAxes): Promise<FsTarget>;
+    /**
+     * 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.
+     */
+    protected checkedReadPath(path: string, opts?: {
+        cwd?: string;
+    }, axes?: ReadAxes): Promise<FsTarget>;
+    /**
+     * 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.
+     */
+    readText(target: FsTarget, signal?: AbortSignal, axes?: ReadAxes): Promise<string>;
+    /**
+     * 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.
+     */
+    streamText(target: FsTarget, signal?: AbortSignal, axes?: ReadAxes): Promise<AsyncIterable<string>>;
+    /**
+     * 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.
+     */
+    readBytes(target: FsTarget, signal: AbortSignal | undefined, maxBytes: number, axes?: ReadAxes): Promise<Uint8Array>;
+    /**
+     * 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.
+     */
+    readByteRange(target: FsTarget, range: {
+        offset: number;
+        length: number;
+    }, signal?: AbortSignal, axes?: ReadAxes): Promise<Uint8Array>;
+    /**
+     * 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.
+     */
+    listDir(target: FsTarget, signal?: AbortSignal, axes?: ReadAxes): Promise<FsDirEntry[]>;
+    /**
+     * 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.
+     */
+    stat(target: FsTarget, signal?: AbortSignal, axes?: ReadAxes): Promise<FsInfo | undefined>;
+    /**
+     * 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.
+     */
+    lstat(path: string, opts?: {
+        cwd?: string;
+    }, signal?: AbortSignal, axes?: ReadAxes): Promise<FsPathInfo | undefined>;
+}
+export default DualAxisFileSystem;
+//# sourceMappingURL=fs-fence.d.ts.map

package/lib/types/fs.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The filesystem backend half of the dual-axis bundle, as its own entry point.
+ *
+ * It lives behind the `@t4r71/dsh-dual-axis/fs` subpath so the bundle's
+ * default entry stays free of a `dsh-fs-sandbox` runtime import: a deployment
+ * that only wants the axes and the settings page mounts the `dual-axis` row,
+ * and a deployment replacing the sandboxed filesystem mounts
+ * `dual-axis-fs` (both rows are in this package's `cordis.patch.yml`).
+ *
+ * @module @t4r71/dsh-dual-axis/fs
+ */
+export { DualAxisFileSystem, readAxisRefusal, readAxisRefusalAsync } from './fs-fence.ts';
+export type { ReadAxes } from './fs-fence.ts';
+export { DualAxisFileSystem as default } from './fs-fence.ts';
+//# sourceMappingURL=fs.d.ts.map

package/lib/types/groups.d.ts

@@ -0,0 +1,226 @@
+/**
+ * RULE GROUPS and THE ONE resolution from a session's axis preset to the ranges
+ * actually in force.
+ *
+ * A rule group is a named fragment of path rules owned by the settings page
+ * (`dual-axis`'s `groups` Config field). A session references groups BY ID and
+ * never stores their content: ten sessions selecting one group must not become
+ * ten copies of it, because copies drift. Resolving an id against the CURRENT
+ * library is therefore the only place a group's rules enter a decision, and
+ * editing a group takes effect on every session referencing it without a
+ * restart.
+ *
+ * This module is that place, for both axes and for both invariants that ride on
+ * them:
+ *
+ * - **deny wins over allow**, with session-level entries and every selected
+ *   group merged into ONE allow list and ONE deny list first
+ *   ({@link resolveEffectiveAxes}), so a group's removal cannot be overridden by
+ *   a session-level addition.
+ * - **write never exceeds read**: the effective write range is the write axis's
+ *   range INTERSECTED with the read axis's range. A write outside the read range
+ *   would let an agent overwrite a file it cannot read back, so the intersection
+ *   is computed here — in the resolution — and never in a user interface.
+ *
+ * Both the fence and the model-facing prompt call {@link resolveEffectiveAxes},
+ * so the range the model is told about and the range it is held to are the same
+ * computation over the same inputs: the session's own preset (read and write
+ * axes, their own additions and removals, and the group ids they selected) plus
+ * the current definitions of those ids. The settings page's `read` / `write`
+ * defaults and its `defaultGroups` seed are NOT among those inputs: they are
+ * read once, when a session is created.
+ *
+ * A reference to an id the library does not define is refused, never treated as
+ * an empty group: "I excluded it and nothing happened" is the worst failure this
+ * surface can have.
+ *
+ * @module @t4r71/dsh-dual-axis/groups
+ */
+import type { AxisScope, EffectiveScopes } from './axis.ts';
+import type { ResolvedScope, ScopePolicy } from './scope.ts';
+/** One group's rules for one axis. Either list may be absent. */
+export interface RuleGroupAxis {
+    /** Absolute roots this group adds to the base. */
+    readonly allow?: readonly string[];
+    /** Absolute roots this group removes even from the base — removal wins. */
+    readonly deny?: readonly string[];
+}
+/**
+ * A named rule fragment. `id` is what a session stores; `name` is for humans
+ * only and may change freely. A group may carry rules for one axis, the other,
+ * or both.
+ */
+export interface RuleGroup {
+    /** Stable identity a session references; renaming it changes every reference. */
+    readonly id: string;
+    /** The human-readable name; carries no semantics. */
+    readonly name: string;
+    /** The rules this group contributes to the read axis. */
+    readonly read?: RuleGroupAxis;
+    /** The rules this group contributes to the write axis. */
+    readonly write?: RuleGroupAxis;
+}
+/**
+ * What the write-never-exceeds-read invariant removed from the write axis.
+ *
+ * Reported rather than applied silently: a group that only grants write access
+ * to a directory the read axis does not cover grants nothing at all, and a user
+ * who configured it must be able to see that instead of concluding the rule was
+ * ignored.
+ *
+ * This value is the ONE answer to "what did the intersection remove", and it is
+ * published verbatim to the client half inside the session's stored record
+ * (`./session-store.ts`). A browser cannot re-derive it: the path algebra below
+ * canonicalizes every root with `realpath` and derives a `workspace` base from
+ * `os.tmpdir()`, neither of which exists there. Publishing the resolution's own
+ * result is therefore what keeps a surface from claiming a narrowing the fence
+ * does not enforce, or missing one it does.
+ */
+export interface WriteNarrowing {
+    /** Whether the read axis makes the effective write range strictly smaller. */
+    readonly narrowed: boolean;
+    /**
+     * Absolute roots the write axis permitted and the effective range does not.
+     * Holds both the write roots the read axis does not cover and the read roots
+     * the write range newly excludes; empty when {@link lostUnbounded} alone
+     * carries the loss, because an unbounded write axis has no root list to lose.
+     */
+    readonly droppedRoots: readonly string[];
+    /** Whether an unbounded write axis became bounded, which no root list can state. */
+    readonly lostUnbounded: boolean;
+}
+/**
+ * The pair actually in force, with every selected group expanded and the write
+ * axis already intersected with the read axis. Both members are plain
+ * {@link AxisScope} values carrying no group ids, so every consumer resolves
+ * them with the same {@link resolveScope} it used before groups existed.
+ */
+export interface EffectiveAxes {
+    /** The read range in force. */
+    readonly read: AxisScope;
+    /** The write range in force, never wider than {@link read}. */
+    readonly write: AxisScope;
+    /** What the intersection removed from the write axis. */
+    readonly narrowing: WriteNarrowing;
+}
+/**
+ * A resolved pair, or the sentence explaining why it could not be resolved.
+ * Resolution failure is a value rather than a throw because every caller has a
+ * different fail-closed rendering for it: the fence refuses the access, the
+ * prompt states that no path is known to be allowed, and `/axis` returns an
+ * error without writing an event.
+ */
+export type EffectiveAxesResolution = {
+    readonly ok: true;
+    readonly axes: EffectiveAxes;
+} | {
+    readonly ok: false;
+    readonly problem: string;
+};
+/** The narrowing that removed nothing. Exported: it is the stored record's absent value. */
+export declare const NO_NARROWING: WriteNarrowing;
+/**
+ * Read one stored narrowing report, or throw naming the member that is
+ * unreadable.
+ *
+ * An absent member is the legal "nothing was ever published for this record"
+ * state and yields {@link NO_NARROWING}: that is exactly what the fence enforced
+ * before this member existed, so the surface shows no narrowing rather than
+ * inventing one. Anything PRESENT must be well formed — a report whose root list
+ * cannot be read would otherwise be displayed as "nothing was removed".
+ * @param value - the untrusted `narrowing` member of a stored record.
+ * @returns the validated report.
+ * @throws When the member is present and not a well-formed report.
+ */
+export declare function parseNarrowing(value: unknown): WriteNarrowing;
+/**
+ * The group ids a preset references, in first-seen order and without repeats.
+ * Callers use this to skip reading the settings page at all for the sessions
+ * that reference no groups.
+ * @param preset - the session's own axis preset.
+ * @returns the referenced ids.
+ */
+export declare function referencedGroupIds(preset: EffectiveScopes): readonly string[];
+/**
+ * The ids the settings page's library defines, for validating one command entry
+ * before it is recorded.
+ *
+ * An unusable library yields no ids: every `groups` entry is then refused by
+ * name, which is the same fail-closed answer the decision path gives.
+ * @param library - the settings page's current `groups` value, untrusted.
+ * @returns the defined ids.
+ */
+export declare function ruleGroupIds(library: unknown): ReadonlySet<string>;
+/**
+ * Attach the group ids a NEW session starts out referencing to the axes that are
+ * `custom`, leaving every other axis exactly as declared.
+ *
+ * The rule is judged per axis, and only an axis whose OWN kind is `custom` can
+ * carry a reference: checking the settings row instead (a tick that is not
+ * tied to an axis) promoted `read: all` to `read: { kind: 'custom', base: 'all' }`
+ * even though no axis was ever set to custom. An axis of one of the three closed
+ * kinds has nowhere to put an id and is seeded verbatim — promoting it would
+ * report a custom scope the settings page never showed.
+ *
+ * A group may carry rules for either axis or both, and the session selected it
+ * once, so the same list goes on both `custom` axes; the group's `read` rules
+ * then apply where they exist and its `write` rules where they exist. Two axes
+ * are therefore independent: one may take the references while the other keeps
+ * its closed kind.
+ * @param axes - the pair a new session is seeded with.
+ * @param ids - the settings page's `defaultGroups`.
+ * @returns the pair carrying those references.
+ */
+export declare function seedGroupReferences(axes: EffectiveScopes, ids: readonly string[]): EffectiveScopes;
+/**
+ * The intersection of two evaluated ranges, as an evaluated range. Exact for
+ * canonical directory roots: two roots are either nested — the deeper one is
+ * their intersection — or disjoint, and a union of directories intersected with
+ * a union of directories is the union of those pairwise intersections.
+ * @param left - one evaluated range.
+ * @param right - the other evaluated range.
+ * @returns the range permitting exactly what both permit.
+ */
+export declare function intersectResolved(left: ResolvedScope, right: ResolvedScope): ResolvedScope;
+/**
+ * Spell an evaluated range as an axis value that evaluates back to it. The
+ * `deny` base plus the roots themselves is the exact spelling: a `workspace`
+ * base would re-add the platform temp areas this range may never have had.
+ * @param resolved - the evaluated range.
+ * @returns the equivalent axis value.
+ */
+export declare function scopeOfResolved(resolved: ResolvedScope): AxisScope;
+/**
+ * THE resolution: one session's axis preset plus the current group library into
+ * the read and write ranges actually in force.
+ *
+ * The write member of the result is the intersection of the write axis's range
+ * with the read axis's. The write axis keeps its own spelling whenever the
+ * intersection changed nothing, so a session that references no groups and needs
+ * no narrowing is described and enforced exactly as before groups existed.
+ *
+ * An unresolvable reference or an unusable library returns `ok: false` and no
+ * axes: the caller refuses, because resolving a missing id to an empty group
+ * would silently drop rules the user configured.
+ * @param preset - the session's own axis preset, group ids included.
+ * @param library - the settings page's current `groups` value, untrusted.
+ * @param policy - the workspace root a `workspace` base resolves against.
+ * @returns the effective pair, or the sentence explaining why there is none.
+ */
+export declare function resolveEffectiveAxes(preset: EffectiveScopes, library: unknown, policy: ScopePolicy): EffectiveAxesResolution;
+/**
+ * The narrower of two bases, in the containment order `deny` ⊂ `workspace` ⊂
+ * `all`.
+ *
+ * This is the tier the write-never-exceeds-read invariant can express to the
+ * layer BELOW the tool layer. That layer is a single closed sandbox mode
+ * mirrored from the write axis onto the session's `sandbox/mode`, and it cannot
+ * spell a path list; the narrower base is the largest tier both axes contain, so
+ * mirroring it keeps the operating-system confinement inside the intersection
+ * instead of leaving it at the write axis's own, wider base.
+ * @param left - one axis.
+ * @param right - the other axis.
+ * @returns the narrower base.
+ */
+export declare function narrowerBase(left: AxisScope, right: AxisScope): 'deny' | 'workspace' | 'all';
+//# sourceMappingURL=groups.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,205 @@
+/**
+ * 双轴访问模式组合包（宿主半边）：把文件沙箱的两条访问轴 —— 读轴与写轴，
+ * 每条都取 deny | workspace | all | custom，custom 形如
+ * `{ kind: 'custom', base, allow[], deny[] }`，语义是 allow = base ∪ allow − deny
+ * 且 deny 优先 —— 作为一份可安装、可配置的组合层暴露出去。
+ *
+ * 这一层持有两件事：新会话从哪两条轴开始（本行的 Loader entry Config，见
+ * `./config.ts`），以及这两条轴在一条会话里怎么存、怎么读
+ * （`./session-store.ts`，本包自有的设置命名空间 `dual-axis-sessions`，按会话 id
+ * 分区）。它把前者下发到后者的时机是 `ctx.on('session/created')`：0.1.7 里
+ * `packages/interaction/permission-presets/src/index.ts:245` 用同一个钩子钉
+ * 权限预设，本包在它之后注册，因此新会话先拿到预设的 mode，再被本包写上一对轴。
+ * 那一对轴按会话来源分两种：顶层会话取设置页那一行当刻的值，子代理子会话取
+ * **父会话当刻生效的那一对**（见 `./session-store.ts` 的 `inheritedAxes`）。
+ * 同一个种子也是**记录缺席时那条会话被修复成的取值**（`seedAxesFor`），修复由
+ * 三处活读路径上的 `store.ensure` 触发，见该方法的说明。
+ *
+ * 为什么轴不在会话日志里（0.1.7 上游删改所致，逐条依据见 README）：
+ * - 轴代数由 `./axis.ts` 与 `./scope.ts` 自带（0.1.7 全删）。
+ * - 会话内的载体由本包自己声明的事件类型承担在 0.1.7 里**不成立**：该类型不在
+ *   `KNOWN_SESSION_EVENT_TYPES` 里，而 `Session.append` 的信封硬编码、不接
+ *   `ignorable`，于是写过的会话会被 `validateStoredEvents` 整份拒收、冷启动后
+ *   打不开。轴因此搬到 `./session-store.ts`；日志里只保留写轴基准档经
+ *   `sandbox/mode` 的那一次镜像（`./session-axes.ts`）。
+ * - 读路径围栏由 `./fs-fence.ts` 自己实现（0.1.7 的 fs-sandbox 只围栏写）。
+ * - 设置节由本行的 Config + `.volatile()` 承载（0.1.7 删了 `installSection`
+ *   与任意命名空间注册，ns 就是 entry id）。
+ *
+ * 客户端半边在 `@t4r71/dsh-dual-axis-ui`：本包不声明 `dsh.client`。
+ *
+ * @module @t4r71/dsh-dual-axis
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Config } from './config.ts';
+export { DUAL_AXIS_ROW_ID, RETIRED_SETTINGS_NAMESPACE, Config, axesOf, declaredSection, defaultGroupIds, groupLibraryValue, normalizeScope, sameScope, } from './config.ts';
+export type { Config as DualAxisConfig } from './config.ts';
+export { intersectResolved, narrowerBase, referencedGroupIds, resolveEffectiveAxes, ruleGroupIds, scopeOfResolved, seedGroupReferences, } from './groups.ts';
+export type { EffectiveAxes, EffectiveAxesResolution, RuleGroup, RuleGroupAxis, WriteNarrowing, } from './groups.ts';
+export { mirrorWriteMode } from './session-axes.ts';
+export { AXES_WRITE_ATTEMPTS, AXES_WRITE_BACKOFF_MS, Config as SessionAxesConfig, DEFAULT_AXES, SESSION_AXES_FIELD, SESSION_AXES_NAMESPACE, SessionAxesConflictError, SessionAxesStore, parseSessionAxesField, parseSessionAxesRecord, seedAxesFor, seedPair, sessionAxesStore, } from './session-store.ts';
+export type { SessionAxesField, SessionAxesRecord, SessionAxesStoreOptions, SessionAxesSweep, SessionAxesWriter, } from './session-store.ts';
+export { AXIS_COMMAND_NAME, registerAxisCommand } from './axis-command.ts';
+export { parseAxisEntry } from './axis-entry.ts';
+export type { AxisEntryParse } from './axis-entry.ts';
+export { AXIS_BASES, AXIS_KINDS, DEFAULT_READ_SCOPE, DEFAULT_WRITE_SCOPE, effectiveScopes, isModeConsistent, isSandboxMode, modeOfAxisBase, modeOfScope, scopeOfMode, } from './axis.ts';
+export type { AxisBase, AxisScope, AxisScopeKind, EffectiveScopes as EffectiveScopesType } from './axis.ts';
+export { ScopeConfigError, isAbsoluteSpelling, isLexicallyUnder, resolveScope, scopeContains } from './scope.ts';
+export type { ResolvedScope, ScopePolicy } from './scope.ts';
+export { DualAxisFileSystem, readAxisRefusal } from './fs-fence.ts';
+export type { ReadAxes } from './fs-fence.ts';
+export { NO_BYPASS, WIDENING_EXIT, renderAxisRange, renderScopePrompt, scopeRefusal } from './scope-prompt.ts';
+export type { ScopeRefusal } from './scope-prompt.ts';
+/**
+ * 双轴访问模式组合层。
+ *
+ * 挂载时做四件事：自检行里声明的轴形状、在会话创建钩子上给新会话钉一对轴、
+ * 按需回收已经消失的会话的记录、把写轴基准档镜像进日志。改完配置只管之后的
+ * 会话；已经在跑的会话保持它存储里那一对轴。子代理子会话不取设置页的值，
+ * 取它的父会话当刻那一对。
+ */
+export declare class DualAxis {
+    /**
+     * 这一行需要的能力：会话表（补齐挂载前的会话）。依赖是静态字段，Cordis 的
+     * loader 只从插件的 `inject` 属性读它 —— 函数形态导出同名常量不会被采用。
+     */
+    static inject: readonly ["sessions"];
+    /** 本行的组合配置 schema，由 loader 在挂载前校验。 */
+    static Config: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<NoInfer<{
+        read: import("@deepseek-ai/schemastery").default<any, any, "volatile">;
+        write: import("@deepseek-ai/schemastery").default<any, any, "volatile">;
+        groups: import("@deepseek-ai/schemastery").default<NoInfer<any[]>, NoInfer<any[]>, "volatile-defined">;
+        defaultGroups: import("@deepseek-ai/schemastery").default<NoInfer<string[]>, NoInfer<string[]>, "volatile-defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        read: import("@deepseek-ai/schemastery").default<any, any, "volatile">;
+        write: import("@deepseek-ai/schemastery").default<any, any, "volatile">;
+        groups: import("@deepseek-ai/schemastery").default<NoInfer<any[]>, NoInfer<any[]>, "volatile-defined">;
+        defaultGroups: import("@deepseek-ai/schemastery").default<NoInfer<string[]>, NoInfer<string[]>, "volatile-defined">;
+    }>>, "plain">;
+    /**
+     * 本行的组合配置，挂载那一刻的那一份。
+     *
+     * 两条轴都是 `.volatile()` 字段，取值是 schema 的 accessor；但这份 accessor
+     * 是**构造期**解析出来的，0.1.7 的 loader 不把后来的设置改动提交回来，所以它
+     * 只作 {@link declaredAxes} 取不到设置服务时的兜底，不再是新会话的取值来源。
+     */
+    private readonly config;
+    /** 轴的权威存储：本包自有的设置命名空间，按会话 id 分区。 */
+    private readonly store;
+    /**
+     * @param ctx - 宿主上下文，本层读会话表、注册会话钩子、写轴存储都经它。
+     * @param config - 本行的组合配置（挂载那一刻的值）。
+     */
+    constructor(ctx: Context, config: Config);
+    /**
+     * 给一条会话钉上它该有的两条轴。
+     *
+     * 取值来源按会话来源分叉：子代理子会话继承父会话当刻那一对，其余会话取设置页
+     * 那一行当刻的值。这条会话在存储里已经有记录时**一律不写**：那条记录就是这条会话
+     * 自己的轴，设置页此后再改与它无关，而每一次重钉都会把用户在下拉里选过的值按设置页
+     * 覆盖回去。
+     *
+     * **没有内容**的会话同样**不写**：不是「已经有记录」，而是「还不该有记录」。
+     * 工作区选择器在同一个工作区里开新对话时复用同一条会话 id（`docs` 与 README 里
+     * 记着这条实测），所以创建即冻结等于把一条还没人用过的会话按当天的设置页钉死；
+     * 这条会话此后每次读取都由 `ensure` 现算种子，设置页改一行它就跟着改，直到它真的
+     * 被用过。落记录的两个时机因此是：**这一条会话被用过**（`hasContent`），或者
+     * **用户经 `/axis` 手动改过它的轴**（那条写路径无条件落，见 `registerAxisCommand`）。
+     * @param ctx - 宿主上下文，用于读这条会话与它父会话的轴。
+     * @param session - 目标会话。
+     */
+    private pin;
+    /**
+     * 一条会话该有的那一对轴 —— 新会话的种子，也是记录缺席时被修复成的取值。
+     *
+     * `pin` 与三处活读路径上的 `store.ensure` 走的是这同一个方法，所以「新建时写下的」
+     * 与「后来补写的」不可能算出两个答案；没有设置服务的组合里用本行自己的 Config 兜底。
+     * @param ctx - 宿主上下文。
+     * @param session - 目标会话。
+     * @returns 这一对轴。
+     */
+    private seedFor;
+    /**
+     * 这条会话当刻生效的那一对轴 —— 记录缺席时现算种子，有记录时读记录；两条轴都按
+     * 引用的 id **当刻**取组定义，再求写轴 ∩ 读轴。
+     *
+     * 提示词、围栏与客户端显示走的是这**同一处**：解算结果里的 `narrowing` 被原样发布进
+     * 这条会话的记录（{@link SessionAxesStore.refreshNarrowing}），于是界面上说「被削掉了
+     * 这些根」与实际执行的围栏不会有第二个答案 —— 浏览器半边既算不出 `workspace` 底座
+     * （要 `os.tmpdir()`），也算不出根路径的规范拼写（要 `realpath`）。
+     * @param ctx - 宿主上下文。
+     * @param session - 目标会话。
+     * @param workspaceRoot - 这条会话的工作区根，`workspace` 与 `custom` 底座对它的解析。
+     * @returns 生效的一对轴，或解算不出来的原因。
+     */
+    private resolveFor;
+    /**
+     * 按需回收：存储里那些 id 已经不在持久化会话表里的记录。
+     *
+     * 起停各扫一次、此后每 {@link SWEEP_INTERVAL_MS} 一次，都是后台任务：清扫失败只记
+     * 日志，绝不影响会话创建或判定路径。判据（为什么不是 `session/disposed`）见
+     * {@link SessionAxesStore.sweep}。
+     * @param ctx - 宿主上下文。
+     */
+    /**
+     * 把每一条在册会话的收窄结论重新解算并发一次。
+     *
+     * 为什么需要这一步：收窄结论是解算的产物，而解算的输入里就有**组定义**，改一个组的
+     * 规则只改设置文档、不碰任何一条会话。少了这一次重发，界面上那句「读轴削掉了这些根」
+     * 就要等到这条会话下一次被触达（下一轮提示词、下一次工具调用、下一次改轴）才跟上，
+     * 而人在设置页改完组之后回到对话里看下拉时，两者都还没发生。
+     *
+     * 判定路径不受影响：围栏与提示词一直是按 id **现取**组定义的，这里重发的只是那份
+     * 已经解算出来的结论。没有记录的会话跳过 —— 它的轴本来就每次现算，落一份反而会冻住。
+     * @param ctx - 宿主上下文。
+     */
+    private republishNarrowing;
+    private sweepSchedule;
+    /**
+     * 设置页那一行当刻声明的两条轴。
+     *
+     * 走 `ctx.settings.describe()` 而不是构造期捕获的 `this.config`：设置页保存写的
+     * 是 Loader entry 的 config 文档，而 `this.config` 是挂载那一刻解析出来的
+     * volatile accessor 快照。0.1.7 的 loader 不把新值提交回插件实例持有的那一份
+     * （`vendor/loader/src/config/entry.ts:162-195`），所以同一进程内保存后，读
+     * `this.config` 拿到的仍是旧值，必须重启才生效。`describe()` 每次都从
+     * `entry.fiber.config` 重新投影并解 volatile
+     * （`packages/settings/settings/src/index.ts:319-323` +
+     * `packages/settings/settings/src/schema.ts:10-17`），与设置页摘要显示用的是
+     * 同一条读路径，因此这里读到的就是文件里那份值。
+     *
+     * `settings` 不在场的组合（本包可在没有设置服务的宿主里单独装载）退回构造期
+     * 那一份，也就是没有设置页可保存时的唯一取值。
+     * @param ctx - 宿主上下文。
+     * @returns 两条轴。
+     */
+    private declaredAxes;
+    /**
+     * 设置页声明「新会话默认加载」的组 id。
+     *
+     * 只被 {@link pin} 用来播种新会话，判定路径一概不读它 —— 与 read/write 两个默认值同理，
+     * 它描述的是一条**将要建立**的会话，不是任何已经有记录的会话。
+     * @param ctx - 宿主上下文。
+     * @returns 声明的组 id；没有设置服务时为空。
+     */
+    private declaredDefaultGroups;
+}
+/** 首次清扫的延迟：等 loader 把每个入口都激活、持久化后端也装好。 */
+export declare const SWEEP_FIRST_DELAY_MS = 15000;
+/** 之后每次清扫的间隔。 */
+export declare const SWEEP_INTERVAL_MS = 30000;
+/**
+ * 两次重发收窄结论之间的毫秒数 —— 界面上那句「读轴削掉了这些根」跟随组定义的最坏延迟。
+ *
+ * 比回收记录的间隔短：回收只是清理，而这句话是给人读的判断，而它唯一的其他更新时机是
+ * 这条会话被触达（下一轮提示词、下一次工具调用、下一次改轴）—— 人在设置页改完组之后回到
+ * 对话里看下拉时，这三件事都还没发生。重发本身只在结论真的变了时才写文档。
+ */
+export declare const NARROWING_REFRESH_MS = 10000;
+/**
+ * 子代理子会话继承父会话当刻那一对轴 —— 定义搬到了 `./session-store.ts`，
+ * 因为「记录缺席时的修复写」要用同一份计算。此处再导出，保持本包既有的公开面。
+ */
+export { inheritedAxes } from './session-store.ts';
+export default DualAxis;
+//# sourceMappingURL=index.d.ts.map