@t4r71/dsh-dual-axis 0.1.0

package/lib/types/read-guard.d.ts

@@ -0,0 +1,34 @@
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** 插件名，loader 诊断用。 */
+export declare const name = "dual-axis-read-guard";
+/** 构造期就要用的服务：缺一个就装载失败，而不是运行期静默放行。 */
+export declare const inject: readonly ["fs", "tools"];
+/** 插件配置。 */
+export interface Config {
+    /** 关闭后本插件完全不注册。 */
+    enabled?: boolean;
+    /** 被检查的读入口工具名。 */
+    readTools?: string[];
+    /** 被检查的写入口工具名。 */
+    writeTools?: string[];
+}
+/** 装载期校验的配置。 */
+export declare const Config: z<Config>;
+/**
+ * 注册两层的轴围栏。
+ * @param ctx - 插件上下文；两个注册都挂在它上面，随它一起卸载。
+ * @param config - 装载期已校验的配置。
+ */
+declare function apply(ctx: Context, config?: Config): Promise<void>;
+/**
+ * 默认导出必须自带 inject / Config / name：Loader.unwrapExports 返回 exports.default 并丢掉
+ * 兄弟具名导出（vendor/loader/src/index.ts:201-208），而 registry 只读 plugin.inject
+ * （vendor/cordis/src/registry.ts:330）—— 挂不上就会不等服务先激活，首次读 ctx.tools 抛错。
+ */
+declare const _default: typeof apply & {
+    inject: readonly ["fs", "tools"];
+    Config: z<Config>;
+};
+export default _default;
+//# sourceMappingURL=read-guard.d.ts.map

package/lib/types/scope-prompt.d.ts

@@ -0,0 +1,130 @@
+/**
+ * The model-facing text of the two access axes: ONE source for both the
+ * runtime-context paragraph the model reads before it acts and the refusal a
+ * fence returns when it acts anyway.
+ *
+ * Why one module: the paragraph and the refusal must state the same range. Two
+ * hand-written copies drift, and the drift is invisible — the model would plan
+ * against one boundary in its context and be denied by a different one. Both
+ * callers therefore call {@link renderAxisRange} for the range sentence and
+ * share {@link NO_BYPASS} and {@link WIDENING_EXIT} verbatim; neither string is
+ * spelled anywhere else in this package.
+ *
+ * Both callers feed it only session-log facts plus the group definitions the
+ * log's ids resolve against: the axis preset is the `dual-axis/scopes` fold (the
+ * projection unit), the workspace root is the session header's `cwd`, and the
+ * group library is the settings row's `groups` field. Nothing here reads ambient
+ * state of its own, so the rendered text is reconstructable from the log and
+ * that library.
+ *
+ * @module @t4r71/dsh-dual-axis/scope-prompt
+ */
+import type { AxisScope } from './axis.ts';
+import type { EffectiveAxes, WriteNarrowing } from './groups.ts';
+/**
+ * The sentence naming what is NOT a way around a refusal. Three facts, all of
+ * which the model otherwise has to guess: the denial is the session's rule
+ * rather than the calling tool's limitation; where each axis is enforced; and
+ * that the two axes are layered differently.
+ *
+ * The layering is stated per axis because asserting it for the whole fence
+ * would be false. `read-guard.ts` enforces the read axis and the allow/deny
+ * path entries of the effective write range at the tool-dispatch layer, and the
+ * write BASE tier a second time below it: `session-axes.ts` mirrors the
+ * narrower of the two bases onto the session `sandbox/mode`, which the command
+ * tools themselves run under. An effective write range based on `all` mirrors
+ * to `danger-full-access`, so for that base there is no layer below the tool
+ * layer at all.
+ */
+export declare const NO_BYPASS: string;
+/**
+ * The sentence naming the only two compliant moves. Both are user-facing, so it
+ * names where the user acts: the settings page row and the two composer
+ * dropdowns are the two surfaces that write the same session axes.
+ */
+export declare const WIDENING_EXIT: string;
+/**
+ * Render one axis as the concrete places it permits and forbids, with the
+ * configured entries already resolved to canonical absolute roots.
+ *
+ * A model plans against directories, not at mode names: `workspace` alone
+ * leaves it guessing whether the platform temp areas count, and `custom`
+ * leaves it guessing which paths were added or removed. {@link resolveScope}
+ * answers both, so this prints its result instead of the axis value.
+ *
+ * A `custom` axis whose entries cannot be resolved (a foreign or hand-edited
+ * log carrying a relative path, which `ScopeConfigError` refuses) is stated as
+ * permitting nothing rather than throwing: the paragraph must not fail the
+ * whole assembly, and a range that cannot be evaluated must never read as a
+ * wider one.
+ * @param axis - the axis value in force.
+ * @param workspaceRoot - the session workspace root a `workspace` and `custom` axis resolve against.
+ * @returns the range sentence, e.g. `kind custom; allowed roots: ["C:\\ws"]; denied roots: ["C:\\ws\\secret"] (a denied path always wins)`.
+ */
+export declare function renderAxisRange(axis: AxisScope, workspaceRoot: string): string;
+/**
+ * The sentence reporting what the write-never-exceeds-read invariant removed.
+ *
+ * Stated because the removal is otherwise invisible: a rule group that grants
+ * write access to a directory the read axis does not cover grants nothing, and a
+ * user who cannot see that concludes the rule was ignored. Empty when the
+ * intersection removed nothing, so a session that narrowed nothing is not
+ * warned about a narrowing that did not happen.
+ * @param narrowing - what the resolution removed from the write axis.
+ * @returns the sentence, or the empty string when nothing was removed.
+ */
+export declare function renderNarrowing(narrowing: WriteNarrowing): string;
+/**
+ * The runtime-context paragraph naming both axes as they stand for one session.
+ *
+ * The write member is the EFFECTIVE write range: the write axis with every
+ * referenced group expanded, intersected with the read axis, and the intersection
+ * is stated rather than left for the model to infer. A model that assumed the
+ * write axis stood alone would plan writes the session refuses; one that assumed
+ * the intersection without being told would refuse work the axes permit.
+ * @param axes - the effective axis pair for the session.
+ * @param workspaceRoot - the session's workspace root.
+ * @returns the paragraph, ready to be contributed as one runtime-context entry.
+ */
+export declare function renderScopePrompt(axes: EffectiveAxes, workspaceRoot: string): string;
+/**
+ * The notice stating that a session's axis preset could not be resolved, so no
+ * path is known to be allowed.
+ *
+ * Rendered both into the prompt and into a refusal, from this one source: an
+ * unresolvable reference — a rule group deleted while a session still references
+ * it — must fail closed everywhere it is met, and must say which id is missing
+ * rather than behaving like a group that allows nothing in particular.
+ * @param problem - the resolution failure, naming the offending id.
+ * @returns the model-facing notice.
+ */
+export declare function unresolvedAxesNotice(problem: string): string;
+/** What one refusal has to name. */
+export interface ScopeRefusal {
+    /** The refused path, as the model spelled it or as the caller resolved it. */
+    readonly displayPath: string;
+    /** Which axis refused. */
+    readonly axis: 'read' | 'write';
+    /**
+     * The refusing range's value. A write refusal carries the EFFECTIVE write
+     * range, so the refusal states the boundary the session actually enforces
+     * rather than the write axis it was derived from.
+     */
+    readonly scope: AxisScope;
+    /** The workspace root that axis resolves against. */
+    readonly workspaceRoot: string;
+    /**
+     * What the read axis removed from the write range, when the refusal is a
+     * write. Stated on the refusal as well as in the prompt: the model is told why
+     * the write axis it was given does not reach this path.
+     */
+    readonly narrowing?: WriteNarrowing;
+}
+/**
+ * The refusal a fence returns for one path, built from the same range sentence
+ * the prompt uses.
+ * @param input - the refused path, the axis that refused it, and the root it resolves against.
+ * @returns the model-facing refusal text.
+ */
+export declare function scopeRefusal(input: ScopeRefusal): string;
+//# sourceMappingURL=scope-prompt.d.ts.map

package/lib/types/scope.d.ts

@@ -0,0 +1,108 @@
+/**
+ * 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
+ */
+import type { AxisScope } from './axis.ts';
+/** The scope inputs that do not depend on the session: just its workspace root. */
+export interface ScopePolicy {
+    /** Absolute root `workspace` scopes derive from. */
+    workspaceRoot: string;
+}
+/**
+ * One axis's evaluated range. Both sets hold canonical absolute paths; an
+ * empty `allow` means "nothing is permitted" unless {@link unbounded} is set,
+ * because the fence treats the allow-list as exhaustive.
+ */
+export interface ResolvedScope {
+    /**
+     * Whether this axis permits everything except {@link deny} — the `all` base.
+     * A flag, NOT a root path: "no containing boundary" cannot be spelled as a
+     * path. `canonicalPath('/')` resolves to the CURRENT DRIVE's root on Windows
+     * (measured: `M:\` for a session on `M:`), which would silently restrict an
+     * unbounded axis to one volume and deny every other drive — the exact
+     * opposite of what the axis means. Representing it as a path also cannot
+     * survive {@link scopeContains}'s identity comparisons, which are per-volume.
+     */
+    unbounded: boolean;
+    /** Roots this axis permits (the target must be one of them or lie beneath one); ignored when {@link unbounded}. */
+    allow: readonly string[];
+    /** Roots this axis forbids even when an allow root contains them — removal wins. */
+    deny: readonly string[];
+}
+/** Thrown when a configured `custom` scope entry cannot name an absolute path. */
+export declare class ScopeConfigError extends Error {
+    /** Which custom entry was malformed (`allow` or `deny`). */
+    readonly entry: 'allow' | 'deny';
+    /** The offending value as configured. */
+    readonly value: string;
+    constructor(
+    /** Which custom entry was malformed (`allow` or `deny`). */
+    entry: 'allow' | 'deny', 
+    /** The offending value as configured. */
+    value: string);
+}
+/**
+ * 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.
+ */
+export declare function isAbsoluteSpelling(path: string): boolean;
+/**
+ * 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.
+ */
+export declare function resolveScope(scope: AxisScope, policy: ScopePolicy): ResolvedScope;
+/**
+ * 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.
+ */
+export declare function isLexicallyUnder(target: string, root: string, caseSensitive?: boolean): boolean;
+/**
+ * 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.
+ */
+export declare function scopeContains(scope: ResolvedScope, targetKey: string, contains?: (path: string, root: string) => boolean): boolean;
+//# sourceMappingURL=scope.d.ts.map

package/lib/types/session-axes.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The write axis's landing place in a session's LOG, and the reason it is the
+ * only one.
+ *
+ * 0.1.6 carried both axes on the \`sandbox/mode\` event (\`readScope\` /
+ * \`writeScope\` members) and wrote them through \`setSandboxScopes\`. 0.1.7's
+ * \`sandbox/mode\` payload is locked to \`{ mode, source }\` in three independent
+ * places — the \`SessionEventMap\` declaration
+ * (\`packages/sandbox/sandbox-policy/src/session-mode.ts:33-38\`), the session-format
+ * validator
+ * (\`packages/session/session-format-v0-to-v1/src/payload-validation.ts:165-168\`),
+ * and the generated schema (\`docs/persistence-schema.json:11132-11147\`) — so the
+ * path-level axis pair cannot ride on it.
+ *
+ * A package-declared event type is not an alternative: \`Session.append\`
+ * (\`packages/core/session/src/index.ts:722-750\`) builds the envelope as exactly
+ * \`{ type, seq, time, data, surfaceOp?, sourceEventSeqs? }\` and takes no envelope
+ * option, so a type outside \`KNOWN_SESSION_EVENT_TYPES\` cannot be marked
+ * \`ignorable\` (the marker exists only on the READ side,
+ * \`packages/session/session-persistence/src/storage-contract.ts:75\`) and a log
+ * carrying it is refused whole. That refusal is why the pair now lives in
+ * \`./session-store.ts\` instead.
+ *
+ * What REMAINS here is the write base's mirror onto \`sandbox/mode\`: a known type,
+ * carrying the closed three-value mode the operating-system layer enforces. The
+ * mirror is the NARROWER of the two axes' bases, never the write axis's own —
+ * the effective write range is the write axis intersected with the read axis, so
+ * mirroring the wider base would leave the layer below the tool fence granting
+ * writes the intersection forbids.
+ *
+ * @module @t4r71/dsh-dual-axis/session-axes
+ */
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { EffectiveScopes } from './axis.ts';
+/**
+ * Mirror one session's write base onto 0.1.7's own \`sandbox/mode\` event, so the
+ * inherited write fence and the system-prompt policy section agree with the axis
+ * pair this package stores.
+ *
+ * The mirrored TIER is derived from the two axes' bases only, never from a rule
+ * group's contents, so editing a group cannot leave this event stale. Path-level
+ * narrowing is enforced live, where the group definitions are read.
+ *
+ * The event is appended even when it repeats the standing mode: \`sandbox/mode\`
+ * carries no idempotence contract, and a session that gained axes without a
+ * matching mode record would have its write fence read a stale mode.
+ * @param session - the session the axes belong to.
+ * @param axes - the axis pair in force from this event onward.
+ */
+export declare function mirrorWriteMode(session: Session, axes: EffectiveScopes): void;
+//# sourceMappingURL=session-axes.d.ts.map