@sema-agent/core 7.15.0 → 7.17.0

package/dist/tools/fs/safety.d.ts

@@ -1,13 +1,13 @@
 import type { ExecutionEnv } from "../../internal/harness-types.js";
 import { protectivePathTargetOf, type ToolCallLike } from "../../core/tool-registry.js";
 /**
- * batch-B (CC 2.1.187 parity): Read/Edit/Write take the file path as `file_path`. Read the target the same way
+ * CC parity: Read/Edit/Write take the file path as `file_path`. Read the target the same way
  * EVERYWHERE the path is consumed from a tool-call's args — not just the tool body but ALSO every gate that
  * extracts the write target to confine it (sensitive-path, skill allowPaths, session allowDirs). A gate that only
  * read `args.path` would see `undefined` for a `file_path` call and either fail-OPEN (circumvent the guard — a real
  * hole) or fail-closed (deny a legitimate write). Single source.
  *
- * The `path` arm is deliberately BROADER than what Read/Edit/Write accept (ruled 2026-08-03): their schema requires
+ * The `path` arm is deliberately BROADER than what Read/Edit/Write accept: their schema requires
  * `file_path` and rejects the retired `path` alias outright (fs-shared.ts FILE_PATH_PARAMS), but this reader is
  * shared with gates that judge OTHER tool vocabularies — Glob's real `path` parameter, deployment-authored tools —
  * and a gate must never see LESS than the tool it is confining might act on. So the asymmetry is the design: the
@@ -15,8 +15,8 @@ import { protectivePathTargetOf, type ToolCallLike } from "../../core/tool-regis
  */
 export declare function fileArgPath(args: unknown): string | undefined;
 /**
- * The WRITE TARGET of a path-confinable write call, tool-aware (b — single source for every
- * gate that confines a write target, same discipline as {@link fileArgPath} above):
+ * The WRITE TARGET of a path-confinable write call, tool-aware — single source for every gate that
+ * confines a write target, same discipline as {@link fileArgPath} above:
  *
  *  · canonical `NotebookEdit` → `notebook_path` FIRST, `file_path`/`path` only as fallback. The tool
  *    itself writes `notebook_path`; its schema tolerates extra keys, so a stray/decoy `file_path` on a
@@ -25,30 +25,30 @@ export declare function fileArgPath(args: unknown): string | undefined;
  *  · every other tool → `file_path`/`path` first ({@link fileArgPath}), `notebook_path` as the
  *    historical fallback (unchanged behavior for the pre-existing gate callers).
  *
- * `canonicalName` is the tool name as mounted (RB-476-A: raw — the legacy normalizer is retired;
- * this module stays dependency-free of the alias table — "NotebookEdit" is the canonical CC name and
- * old→new normalization is identity for it).
+ * `canonicalName` is the tool name as mounted, raw: there is no legacy normalizer, and this module
+ * stays dependency-free of the alias table — "NotebookEdit" is the canonical CC name and old→new
+ * normalization is identity for it.
  */
 export declare function writeTargetPath(call: ToolCallLike, pt?: ReturnType<typeof protectivePathTargetOf>): string | undefined;
 /**
- * The "hand" file tools (design/44) — safety invariants ported from CC's `FileEditTool` (design/43 Rule
- * 7): without these a weak model blind-edits / overwrites files (P0 safety, not polish). This module is
- * the pure/testable core (path resolution + the three edit invariants + content hashing); the tools in
- * this dir compose it. Per-task state and the execution env are passed in (factory-closure wiring,
- * design/44 §11 ruling A), never read from a shared/global.
+ * The "hand" file tools' safety invariants, ported from CC's `FileEditTool`: without these a weak
+ * model blind-edits / overwrites files (a safety property, not polish). This module is the
+ * pure/testable core (path resolution + the three edit invariants + content hashing); the tools in
+ * this dir compose it. Per-task state and the execution env are passed in (factory-closure wiring),
+ * never read from a shared/global.
  */
-/** What we remember about a file the agent has read (design/44 §4). */
+/** What we remember about a file the agent has read. */
 export interface ReadEntry {
     /** SHA-256 of the content at read time. Staleness is detected by content hash, NOT mtime — mtime is
-     *  unreliable across containers/volumes/NFS and across a design/45 suspend→resume on another replica. */
+     *  unreliable across containers/volumes/NFS and across a suspend→resume on another replica. */
     hash: string;
-    /** Total line count at read time, and whether the read was truncated (for the edit truncation hint, S2). */
+    /** Total line count at read time, and whether the read was truncated (for the edit truncation hint). */
     totalLines: number;
     truncated: boolean;
-    /** RB-200 F2 — CC `isPartialView` parity (220 @515151 sets it only when the auto-pagination catch branch
-     *  fires, i.e. the model asked for the file by DEFAULT — no explicit offset/limit — and the token cap
-     *  truncated it anyway; an EXPLICIT offset/limit slice that fits under the cap is NEVER marked this way,
-     *  even though it's equally "not the whole file"). Deliberately narrower than {@link truncated} above,
+    /** CC `isPartialView` parity: set ONLY when the auto-pagination branch fires — the model asked for
+     *  the file by DEFAULT (no explicit offset/limit) and the token cap truncated it anyway. An EXPLICIT
+     *  offset/limit slice that fits under the cap is NEVER marked this way, even though it is equally
+     *  "not the whole file". Deliberately narrower than {@link truncated} above,
      *  which also fires for a fully-intentional, successful slice read (`start>1 || end<total`) — folding
      *  THIS flag into that broader one would make {@link OVERSIZE_READ_ESCAPE_HINT}'s documented promise
      *  ("read it in slices with explicit offset/limit to satisfy the read-first rule") false: a model paging
@@ -56,51 +56,50 @@ export interface ReadEntry {
      *  additive: undefined on every non-Read write-back (Write/Edit re-record the file they just fully wrote)
      *  and on every seeded/attachment entry — those are never partial by construction. */
     isPartialView?: boolean;
-    /** The line window actually served to the model on the last read (design/64 §7.2(6) dedup stub). Lets
+    /** The line window actually served to the model on the last read (the dedup stub's key). Lets
      *  read_file return a `file_unchanged` stub when the SAME window is re-requested and the content hash is
      *  unchanged — saving the re-transmitted body. Optional/additive: undefined (e.g. an entry seeded from an
-     *  older design/45 checkpoint) just means "no dedup", never a false hit. */
+     *  older checkpoint) just means "no dedup", never a false hit. */
     view?: {
         start: number;
         end: number;
     };
-    /** Millisecond timestamp of the last read/write-back that recorded this entry (
-     *  2026-07-03, compact re-read parity: the post-compaction attachment picks the most RECENTLY
-     *  read files — CC sorts readFileState by timestamp). Optional/additive: undefined (an entry
-     *  seeded from an older checkpoint) sorts last, never breaks. */
+    /** Millisecond timestamp of the last read/write-back that recorded this entry: the post-compaction
+     *  attachment picks the most RECENTLY read files, the way CC sorts readFileState by timestamp.
+     *  Optional/additive: undefined (an entry seeded from an older checkpoint) sorts last, never breaks. */
     lastReadAt?: number;
-    /** CC 2.1.204 parity (`seededFromContext`, cc204-bundle @17889409 / seeding @17917159; 198 zero
-     *  hits): TRUE when the Runner pre-seeded this entry because the file's FULL disk-verbatim text
-     *  was injected into the model's context at startup (ProjectMemoryLoad.seededFiles — CC's
-     *  CLAUDE.md/nested-memory seeding). A DEFAULT whole-file Read of an UNCHANGED seeded file
+    /** CC 2.1.204 parity: TRUE when the Runner pre-seeded this entry because the file's FULL
+     *  disk-verbatim text was injected into the model's context at startup
+     *  (ProjectMemoryLoad.seededFiles — CC's own memory preload). A DEFAULT whole-file Read of an
+     *  UNCHANGED seeded file
      *  answers with the already-in-context reminder instead of re-transmitting the body. Any real
      *  Read / edit write-back records a FRESH entry without this flag, so a file that changed on
      *  disk (hash mismatch) always serves real content and the dedup disarms permanently.
      *  Optional/additive: absent = normal entry. */
     seededFromContext?: boolean;
 }
-/** Per-task record of which files have been read, keyed by canonical path (design/44 §4, §11 ruling A:
- *  owned by prepare-task, closure-captured by the tools; serialized into a design/45 Checkpoint later). */
+/** Per-task record of which files have been read, keyed by canonical path: owned by prepare-task,
+ *  closure-captured by the tools, and serialized into the durable checkpoint. */
 export type ReadFileState = Map<string, ReadEntry>;
-/** SHA-256 hex of UTF-8 content — the staleness/identity key (design/44 §4 inv 2, jury M1). */
+/** SHA-256 hex of UTF-8 content — the staleness/identity key. */
 export declare function sha256(content: string): string;
 /** A failed path resolution / invariant check, surfaced to the model as a self-correctable tool error. */
 export interface FsViolation {
     code: "path_not_in_root" | "not_read" | "stale" | "ambiguous_edit" | "invalid" | "read_path_denied";
-    /** RB-264 N1: set on the `not_read` violation raised by an AUTO-TRUNCATED read
+    /** Set on the `not_read` violation raised by an AUTO-TRUNCATED read
      *  ({@link ReadEntry.isPartialView}) rather than by a never-read file. Both carry the same CC-verbatim
      *  message; only this one needs {@link PARTIAL_VIEW_READ_ESCAPE_HINT} appended, because for it a plain
      *  re-read is a fixpoint. */
     partialView?: true;
-    /** RB-371 ④: set on `path_not_in_root` (and design/199 `read_path_denied`) — the CANONICAL key the
+    /** Set on `path_not_in_root` and `read_path_denied` — the CANONICAL key the
      *  refused path resolved to (symlinks followed, tracked cwd applied), i.e. the value the fence
      *  actually judged. Rides into the tool result's `details` (see {@link violationDetails}) so a
      *  consumer can count/aggregate boundary refusals from fields instead of regexing the prose. */
     target?: string;
-    /** RB-371 ④: set ONLY on `path_not_in_root` — the containment roots in effect (primary first,
+    /** Set ONLY on `path_not_in_root` — the containment roots in effect (primary first,
      *  then additionalDirectories), canonical form. */
     roots?: readonly string[];
-    /** design/199 件B: set ONLY on `read_path_denied` — the deny-list pattern (verbatim entry text)
+    /** Set ONLY on `read_path_denied` — the deny-list pattern (verbatim entry text)
      *  the judged target matched. */
     pattern?: string;
     message: string;
@@ -108,21 +107,17 @@ export interface FsViolation {
 /**
  * Absolute in EITHER family: POSIX `/…` or drive-letter `C:\…`/`C:/…`.
  *
- * REF-C1 — this is the ONE definition of "already absolute, therefore do not prepend a base". It was
- * independently re-typed at nine coordinates (search.ts ×4, bash-readonly-classifier.ts,
- * core/lsp.ts, core/runner/prepare-task.ts, orchestration/run-spec.ts and here), three of which
- * carried a comment claiming the same philosophy as this file while keeping their own copy. The
- * failure mode is not the duplication itself but the drift it invites: a family added at one
- * coordinate leaves the other eight judging the same string differently, and this predicate gates a
+ * This is the ONE definition of "already absolute, therefore do not prepend a base". The failure mode
+ * of a private re-typing is not the duplication but the drift it invites: a family added at one
+ * coordinate leaves every other copy judging the same string differently, and this predicate gates a
  * security fence (frozen-path deny, readonly-boundary containment) as well as URI key minting.
  * Callers that need a family the predicate does not cover must widen it HERE, not locally.
  *
- * The UNC arm (`\\host\share\…`) was exactly that drift, found already in flight: core/lsp.ts carried it
- * privately while the other eight coordinates did not, so the LSP tool leg resolved a UNC path as
- * absolute while the edit-nudge leg prefixed it with the task root — two URI keys for one file. Folding
- * it in here settles the disagreement in the direction the rest of this file already takes: a literal
- * `\\host\share\…` is win-form (see {@link isWinFormPath}) and `within()` lands it outside every
- * POSIX/drive root, i.e. it is a location the working directory does not contain.
+ * The UNC arm (`\\host\share\…`) is the shape that drift produced: held privately in one consumer, it
+ * made that consumer resolve a UNC path as absolute while a sibling prefixed it with the task root —
+ * two URI keys for one file. Folding it in here settles the disagreement in the direction the rest of
+ * this file takes: a literal `\\host\share\…` is win-form (see {@link isWinFormPath}) and `within()`
+ * lands it outside every POSIX/drive root, i.e. a location the working directory does not contain.
  */
 export declare function isAbsolutePathForm(p: string): boolean;
 /**
@@ -133,10 +128,10 @@ export declare function isAbsolutePathForm(p: string): boolean;
  * contains a literal backslash (legal on POSIX), and `//host/share` is therefore POSIX-form too — which is
  * the whole point: on POSIX that spelling is an ordinary absolute path, not a network share.
  *
- * REF-C2 — this is the ONE definition of the win-family spelling. core/file-snapshot-store.ts held a
- * byte-identical private twin (its manifest key/restore-target folds are conditioned on it) and now
- * imports this one; core/ already depends on this module at seven other coordinates, and this file's own
- * imports are `node:crypto` plus a type, so there is no layering wall between them.
+ * This is the ONE definition of the win-family spelling; core/file-snapshot-store.ts conditions its
+ * manifest key / restore-target folds on this import rather than a private twin. core/ already depends
+ * on this module elsewhere, and this file's own imports are `node:crypto` plus a type, so there is no
+ * layering wall between them.
  */
 export declare function isWinFormPath(p: string): boolean;
 /**
@@ -153,7 +148,7 @@ export declare function isWinFormPath(p: string): boolean;
 export declare function expandHomeTilde(p: string, home: string): string;
 export declare function isBlockedDevicePath(key: string): boolean;
 /**
- * RB-153 — purely LEXICAL path normalization: collapse repeated separators, drop `.` segments, and
+ * Purely LEXICAL path normalization: collapse repeated separators, drop `.` segments, and
  * resolve `..` against the preceding segment. No filesystem access, no cwd: this is a spelling
  * normalizer, not a resolver. (Deliberately NOT `canonicalizeNewPath`'s job — that one walks the real
  * filesystem precisely because folding `..` lexically across a SYMLINKED parent is unsound. Use this one
@@ -164,9 +159,8 @@ export declare function isBlockedDevicePath(key: string): boolean;
  * three different ways. Callers that match a device list against a raw argument must normalize first or
  * the list is a spelling filter rather than a device filter.
  *
- * REF-C3 — coverage, after folding in the two private re-implementations that had grown around this one
- * (the bash classifier's drive-aware wrapper and prepare-task's `normalizeSegments`). The union they
- * covered between them is now the contract here:
+ * Coverage — the union of every fold the callers need, held once here rather than re-implemented per
+ * consumer:
  *  · POSIX absolute — `/a/./b` → `/a/b`; `/..` is `/`, matching the kernel.
  *  · drive-letter (`C:\a\..\b`) and UNC (`\\host\share\..\x`) — prefix preserved, folding applies
  *    to the tail only, and the REJOIN uses the path's own native separator so one file cannot acquire
@@ -175,14 +169,14 @@ export declare function isBlockedDevicePath(key: string): boolean;
  *    `dev/zero` under some other directory is an ordinary file), and a leading `..` is KEPT rather than
  *    popped into nothing — dropping it would move the path.
  *
- * FAMILY-awareness is the one thing none of the three had right. A backslash is a separator only in a
- * win-form path; in a POSIX path it is an ordinary filename character, and the classifier's old
- * unconditional `\`→`/` fold rewrote a POSIX file literally named `a\..\b` into a different location
- * before the boundary check ever saw it (both directions: false refusal and false allow).
+ * FAMILY-awareness is the part a private copy tends to get wrong. A backslash is a separator only in a
+ * win-form path; in a POSIX path it is an ordinary filename character, and an unconditional `\`→`/`
+ * fold rewrites a POSIX file literally named `a\..\b` into a different location before the boundary
+ * check ever sees it — in both directions: false refusal and false allow.
  */
 export declare function normalizeAbsPathLexically(p: string): string;
 /**
- * The READ-leg fold (REF-C3 receipt, R1 verify ISSUE-1): removes `.` segments and duplicate
+ * The READ-leg fold: removes `.` segments and duplicate
  * separators ONLY — transformations that name the SAME file on every real filesystem, symlinks
  * included. `..` is deliberately KEPT: `a/../x` and `x` are different files when `a` is a symlink,
  * and this function's callers go on to OPEN the result (fileInfo/readText), not just to mint a
@@ -197,7 +191,7 @@ export declare function hasBinaryExtension(path: string): boolean;
 export declare function imageMimeForRead(path: string): string | undefined;
 /** Verify the raw bytes actually ARE the image format the extension claims (magic-number sniff). Extension alone
  *  is forgeable: a `.png` holding text / an empty file / a truncated blob would otherwise become a malformed
- *  `ImageContent` that makes the NEXT provider request fail (400). Pure — no I/O. (batch-C.) */
+ *  `ImageContent` that makes the NEXT provider request fail (400). Pure — no I/O. */
 export declare function imageMagicMatches(bytes: Uint8Array, mimeType: string): boolean;
 /** One contiguous byte pattern that must appear at a fixed offset for its signature to match. */
 export interface BinaryMagicSegment {
@@ -216,11 +210,11 @@ export interface BinaryMagicSignature {
     readonly segments: readonly BinaryMagicSegment[];
 }
 /**
- * ANG-5 (external black-box re-review, ruled 2026-08-03) — magic-byte criteria for the formats
- * {@link hasBinaryExtension} names. That list carries 103 extensions; before this table only PDF
- * (`pdfMagicMatches`, in the PDF lane) and the four API image formats ({@link imageMagicMatches}) had a
- * content criterion, so for every other listed format the NAME was the only evidence available. Where the
- * content IS reachable that left identification to the statistical fallback ({@link isBinaryContent}),
+ * Magic-byte criteria for the formats {@link hasBinaryExtension} names. That list carries 103
+ * extensions; without this table only PDF (`pdfMagicMatches`, in the PDF lane) and the four API image
+ * formats ({@link imageMagicMatches}) have a content criterion, so for every other listed format the
+ * NAME is the only evidence available. Where the content IS reachable that leaves identification to
+ * the statistical fallback ({@link isBinaryContent}),
  * which samples the first 8192 decoded characters and passes anything whose control-character ratio
  * stays under 10% — a short archive/executable header followed by printable payload clears that bar
  * and gets delivered as text.
@@ -249,36 +243,147 @@ export declare const BINARY_MAGIC_SIGNATURES: readonly BinaryMagicSignature[];
  */
 export declare function binaryMagicFormat(bytes: Uint8Array): string | undefined;
 /**
- * Content sniff for binary data (design/64 §17.1, CC `constants/files.ts` `isBinaryContent`): a NUL byte,
+ * Content sniff for binary data (CC `isBinaryContent` parity): a NUL byte,
  * or more than 10% non-printable characters in the sample, means binary. Second layer behind
  * {@link hasBinaryExtension} — catches extension-less or mis-named binaries (a `Dockerfile` that is really
  * a compiled blob) that would otherwise be read as mojibake. Plain text (incl. UTF-8, tabs/newlines) passes.
  */
 export declare function isBinaryContent(sample: string): boolean;
 /**
- * CC's own UNC/network-path predicate, verbatim (220 @515523:
- * `n.startsWith("\\\\") || n.startsWith("//")`). Pure.
+ * CC's own UNC/network-path predicate, verbatim (`n.startsWith("\\\\") || n.startsWith("//")`). Pure.
  *
- * RB-279: the predicate is CC's, but CC's POLARITY is the opposite of what sema used it for. In CC this
- * test is an EARLY ALLOW — `return { result: !0 }`, skipping the binary-extension and device checks that
- * follow it — and CC applies it to the NORMALIZED path (`Li` ⇒ `path.normalize`), not the raw argument.
- * See {@link canonicalizeTarget} for how sema now mirrors that (and for the two deliberate differences).
- * This function stays a pure spelling test with no verdict of its own.
+ * In CC this test is an EARLY ALLOW — it skips the binary-extension and device checks that follow it —
+ * and CC applies it to the NORMALIZED path, not the raw argument. See {@link canonicalizeTarget} for
+ * how sema mirrors that and for the two deliberate differences. This function stays a pure spelling
+ * test with no verdict of its own.
  */
 export declare function isUncPath(path: string): boolean;
-/** design/199 件B — the family-aware LEXICAL view of a possibly-relative spelling against a
- *  resolution base (no I/O, `.`/`..` folded via {@link normalizeAbsPathLexically}): the §3.3 second
- *  deny-judgment view. It asks "does the NAME land on a guarded path", complementing the canonical
+/** The two spelling families a tree can be in. Read from the ROOT's spelling (the cwd's when a deployment
+ *  supplies no root) — never from `process.platform`: the exec env may be remote and of the other family. */
+export type PathFamily = "win" | "posix";
+/** The family of a call's tree; `undefined` when the call declares neither root nor cwd (a treeless call
+ *  gets no family invented for it — see {@link pathIdentityOf} for what it can still read). */
+export declare function pathFamilyOf(bases: {
+    readonly root: string;
+    readonly cwd?: string | undefined;
+}): PathFamily;
+export declare function pathFamilyOf(bases: {
+    readonly root?: string | undefined;
+    readonly cwd: string;
+}): PathFamily;
+export declare function pathFamilyOf(bases: {
+    readonly root?: string | undefined;
+    readonly cwd?: string | undefined;
+}): PathFamily | undefined;
+/**
+ * FULLY QUALIFIED under the family. win: drive-rooted (`C:\`/`C:/`) or UNC — a `/x` / `\x` is rooted-not-
+ * qualified and joins the base's drive or share root ({@link joinForFamily}), a `C:rel` is drive-relative.
+ * posix: `/`-rooted. `undefined` (a treeless call): only the anchor-free `/`-rooted form, the one spelling
+ * that names a file without a tree.
+ */
+export declare function isAbsoluteForFamily(family: PathFamily | undefined, p: string): boolean;
+/** The refusal words of {@link win32NamespaceScreen} — a closed set (docs/CLOSED-SETS.md). */
+export declare const WIN32_NAMESPACE_REFUSALS: readonly ["device_namespace", "unmappable_namespace", "unc_on_posix_tree", "drive_relative"];
+export type Win32NamespaceRefusal = (typeof WIN32_NAMESPACE_REFUSALS)[number];
+/** What each refusal word says about the spelling (the message clause after `path "…" `). */
+export declare const WIN32_NAMESPACE_REFUSAL_TEXT: {
+    readonly device_namespace: "is a Win32 device-namespace path (\\\\.\\ names a raw device object, not a file)";
+    readonly unmappable_namespace: "is a Win32 extended-length namespace path with no DOS-path equivalent (only \\\\?\\<drive>: and \\\\?\\UNC\\ forms name files)";
+    readonly unc_on_posix_tree: "is a UNC (\\\\host\\share) spelling, which names no file on a POSIX tree";
+    readonly drive_relative: "is drive-relative (a drive letter with no separator after the colon), a location no tree can locate";
+};
+/** The fence over the text table: `never` while every refusal word has a row. */
+export type NamespaceRefusalTextCoversEveryWord = AssertAllKeysHandled<Exclude<Win32NamespaceRefusal, keyof typeof WIN32_NAMESPACE_REFUSAL_TEXT>>;
+type AssertAllKeysHandled<T extends never> = T;
+/**
+ * The Win32 namespace screen — run on every model-spelled target BEFORE the family join, at every site
+ * (the fs throat, the effective-target reader, the rule side, the glob splitter), so one spelling is
+ * refused with one word everywhere. `\\.\` ⇒ `device_namespace` (every family); `\\?\` mappable ⇒ the
+ * stripped spelling, which is screened ON (a `\\?\UNC\…` on a POSIX tree still refuses), unmappable ⇒
+ * `unmappable_namespace` (every family); a backslash UNC ⇒ passes under `win`, `unc_on_posix_tree` under
+ * `posix` (the canonicalizer's refusal boundary on POSIX trees is preserved: the family rule governs what
+ * is admitted, never what was already refused); `C:rel` under `win` ⇒ `drive_relative`. A treeless call
+ * passes a UNC spelling through — the identity then reads it as relative, as before.
+ */
+export declare function win32NamespaceScreen(spelled: string, family: PathFamily | undefined): {
+    readonly ok: true;
+    readonly spelled: string;
+} | {
+    readonly ok: false;
+    readonly refuse: Win32NamespaceRefusal;
+};
+declare const PATH_IDENTITY: unique symbol;
+/**
+ * The ONE comparison form of an absolute path (upstream's normal form): posix = the lexical-normal
+ * `/`-rooted path; win = `/c/rest` for a drive (letter lower-cased), `//host/share/rest` for UNC, `\`
+ * folded to `/`, `.`/`..` folded with the anchor preserved. A COMPARISON form — never a path to open, never
+ * compared against a native `C:\…` string. Branded: a spelling is not an identity until {@link pathIdentityOf}
+ * has read it.
+ */
+export type PathIdentity = string & {
+    readonly [PATH_IDENTITY]: true;
+};
+/** Why a spelling has no identity: a namespace refusal, `relative` (join it to a base first), or
+ *  `unanchored` (a win `/x` with no tree root to take a drive from). */
+export type PathIdentityRefusal = Win32NamespaceRefusal | "relative" | "unanchored";
+export type PathIdentityReading = {
+    readonly ok: true;
+    readonly identity: PathIdentity;
+} | {
+    readonly ok: false;
+    readonly reason: PathIdentityRefusal;
+};
+/**
+ * The identity of an ABSOLUTE spelling under the family ({@link PathIdentity}). `anchor` is the tree's root
+ * (or cwd) spelling: under `win` a `/`-rooted spelling whose first segment is not a drive letter
+ * (`/proj/x`) anchors on the root's drive or share, as `path.win32.resolve` anchors it on the current
+ * drive; `/c/x` and `/C:/x` are drive spellings (the cygdrive form and the rule grammar's `/`+body), and
+ * `/\\host\share\x` is the grammar's prefix before a UNC. A relative spelling is `relative` — callers join
+ * it to a base FIRST. A treeless call (`family` undefined) reads only the anchor-free `/`-rooted form, as
+ * the POSIX identity; every other spelling names nothing, which is what a missing base answered before.
+ */
+export declare function pathIdentityOf(spelled: string, family: PathFamily | undefined, anchor?: string): PathIdentityReading;
+/** Is the identity a UNC one (`//host/share/…`)? Identities compare by anchor kind first: a UNC identity is
+ *  never under a rooted one and vice versa (upstream's shape parity). */
+export declare function isUncIdentity(identity: PathIdentity): boolean;
+/** Is `s` already an identity under the family — the identity function is the identity on it? The
+ *  runtime twin of the brand for values that arrive from outside the type system. */
+export declare function isPathIdentity(s: string, family: PathFamily | undefined): s is PathIdentity;
+/** Is the identity a DIRECTORY a rule may speak for — anything but the tree's bare root (`/`, a drive root
+ *  `/c`, a share root `//host/share`), which admits nothing? */
+export declare function isIdentityDir(identity: PathIdentity, family: PathFamily | undefined): boolean;
+/** Does the spelling carry a `.` or `..` segment under the family's separators (a backslash is a name byte on
+ *  POSIX)? A rule body with one admits nothing: folding it could make it name a second directory. */
+export declare function carriesDotSegment(spelled: string, family: PathFamily | undefined): boolean;
+/** A model-spelled path bounded for error text (the spelling is unbounded input). */
+export declare function clipSpelling(spelled: string): string;
+/** A ROOTED (not qualified) spelling handed to the SHELL on a win tree (`/d/x`, `/etc`, `\\x`) is the shell's to
+ *  map — the win32 adapter runs Git Bash, where `/d/x` is drive D and `/etc` the MSYS root, neither the cwd's
+ *  drive root — so no lexical reader may resolve it (fail-closed: the operand is unresolvable, the cd mints
+ *  nothing). The ONE statement of that rule, for every shell-facing resolver. */
+export declare function isShellRootedSpellingUnmapped(family: PathFamily | undefined, spelled: string): boolean;
+/** The win family's native spelling of a UNC written with any leading-separator mix (`//host/share/x`, `\\/host/…`
+ *  ⇒ `\\\\host\\share\\x`), for a lexical normalizer that recognises the backslash form only; every other spelling is
+ *  returned as is. */
+export declare function nativeUncSpellingOf(family: PathFamily | undefined, spelled: string): string;
+/**
+ * Join a RELATIVE-OR-ROOTED spelling to a base under the family, without folding (`..` across a symlinked
+ * parent is the env's to resolve). win = `path.win32` semantics: `/x`/`\x` lands on the base's drive or
+ * share root, anything else under the base with the base's own separator. posix = `/`-join.
+ */
+export declare function joinForFamily(family: PathFamily, base: string, rel: string): string;
+/** The family-aware LEXICAL view of a possibly-relative spelling against a resolution base (no I/O,
+ *  `.`/`..` folded via {@link normalizeAbsPathLexically}): the SECOND deny-judgment view. It asks
+ *  "does the NAME land on a guarded path", complementing the canonical
  *  view's "does the TARGET" — a symlink AT a guarded spelling resolves away from it canonically,
  *  and only this view still names it. */
 export declare function lexicalViewOf(spelled: string, base: string): string;
 /**
- * Resolve a model-supplied path to a canonical key AND enforce rootPath containment (design/44 §4
- * inv 5/6/7). Existing paths use `canonicalPath` (resolves symlinks, so the same file can't get two
- * keys). New paths canonicalize the **deepest existing ancestor** then rejoin the missing tail — a
- * symlinked parent therefore cannot land the target outside root. Returns the canonical key, or a
- * `path_not_in_root` violation. (Defense-in-depth at the tool layer; NOT a substitute for a sandboxed
- * `executionEnv` — see design/44 §5.)
+ * Resolve a model-supplied path to a canonical key AND enforce rootPath containment. Existing paths
+ * use `canonicalPath` (resolves symlinks, so the same file cannot get two keys). New paths
+ * canonicalize the **deepest existing ancestor** then rejoin the missing tail — a symlinked parent
+ * therefore cannot land the target outside root. Returns the canonical key, or a `path_not_in_root`
+ * violation. Defense-in-depth at the tool layer; NOT a substitute for a sandboxed `executionEnv`.
  */
 export declare function resolveKey(env: ExecutionEnv, rootCanonical: string, path: string, signal?: AbortSignal, baseCwd?: string, additionalRootsCanonical?: readonly string[], exactFileReadExemption?: (canonicalKey: string) => boolean, readDeny?: {
     matchTarget(canonicalKey: string, lexicalView?: string, opts?: {
@@ -299,11 +404,11 @@ export declare function resolveKey(env: ExecutionEnv, rootCanonical: string, pat
  * doesn't exist yet, the deepest EXISTING ancestor is canonicalized then the missing tail rejoined —
  * so a symlinked parent cannot land the target elsewhere). NO containment check — this is the pure
  * canonicalization shared by `resolveKey` (which adds rootPath containment) and
- * `createSensitivePathPolicy` (design/72 §2.1, which matches the real target against a guarded list).
+ * `createSensitivePathPolicy` (which matches the real target against a guarded list).
  * A single source of truth for symlink resolution: a sensitive-path policy that matched the raw path
- * instead of the real target would compare against the spelling, not the destination (§2.1).
+ * instead of the real target would compare against the spelling, not the destination.
  */
-export declare function canonicalizeTarget(env: ExecutionEnv, path: string, signal?: AbortSignal, baseCwd?: string): Promise<{
+export declare function canonicalizeTarget(env: ExecutionEnv, path: string, signal: AbortSignal | undefined, family: PathFamily, baseCwd?: string): Promise<{
     ok: true;
     key: string;
     aliasResolved?: true;
@@ -311,20 +416,21 @@ export declare function canonicalizeTarget(env: ExecutionEnv, path: string, sign
     ok: false;
     message: string;
     unresolvedSymlink?: true;
+    refused?: Win32NamespaceRefusal;
 }>;
 /** Render a `FsViolation` as the model-facing tool error text (returned, never thrown — model retries). */
 export declare function violationText(toolName: string, v: FsViolation): string;
 /**
- * RB-371 ④ — structured `details` for a rendered violation: non-`undefined` ONLY for
- * `path_not_in_root`, the one code with per-refusal coordinates worth counting (which canonical
- * target, against which roots). Designed to be passed straight as `errorResult`'s second argument by
- * every renderer of a {@link resolveKey} violation — `undefined` keeps the pre-existing detail-less
- * shape for all other violation codes, so nothing else changes byte-wise.
+ * Structured `details` for a rendered violation: non-`undefined` ONLY for the two codes with
+ * per-refusal coordinates worth counting (which canonical target, against which roots or which deny
+ * pattern). Designed to be passed straight as `errorResult`'s second argument by every renderer of a
+ * {@link resolveKey} violation — `undefined` keeps the detail-less shape for all other violation
+ * codes.
  *
- * RB-397-c (回溯复查批): `type` is the WIRE discriminator — the leg's card projector (`createStructuredProjector`, design/388 L4)
- * (tool-output-projection.ts) keys on `details.type`, so without it the card never reached
- * `tool_end.structured` and the "count from fields" promise above held for in-process readers only.
- * `code` stays as-is for the existing RB-371 consumers — the new key is strictly additive.
+ * `type` is the WIRE discriminator: the card projector (`createStructuredProjector`,
+ * tool-output-projection.ts) keys on `details.type`, so without it the card never reaches
+ * `tool_end.structured` and the "count from fields" promise above holds for in-process readers only.
+ * `code` carries the same value for consumers that read it.
  */
 export declare function violationDetails(v: FsViolation): {
     type: "path_not_in_root";
@@ -338,7 +444,7 @@ export declare function violationDetails(v: FsViolation): {
     pattern: string;
 } | undefined;
 /**
- * RB-371 ② — does `p` sit inside ANY of the canonical containment roots? Exposed for the Bash
+ * Does `p` sit inside ANY of the canonical containment roots? Exposed for the Bash
  * tool's post-`cd` disclosure note (fs-bash.ts): the note reuses the SAME segment-aware `within`
  * the fence itself uses, so the disclosure and the fence can never disagree about what counts as
  * "inside". Pure/lexical — callers own any canonicalization of `p` (the tracked cwd stays raw by
@@ -346,37 +452,34 @@ export declare function violationDetails(v: FsViolation): {
  */
 export declare function withinAnyRoot(rootsCanonical: readonly string[], p: string): boolean;
 /**
- * RB-371 ① — the escape-hatch tail for the `path_not_in_root` refusal: its three sibling hints
- * below each name a sanctioned next step; this refusal named none, leaving the model to oscillate
- * between "the boundary is hard" and hunting for a way around it.
+ * The escape-hatch tail for the `path_not_in_root` refusal: like its three sibling hints below, it
+ * names a sanctioned next step, so the model does not oscillate between "the boundary is hard" and
+ * hunting for a way around it.
  *
  * The card names the SANCTIONED way out and nothing else: widening the declaration
- * (`additionalDirectories` / read-only `additionalReadDirectories`, design/119), or the
- * deployment-level `readFace: "open"` for reads.
+ * (`additionalDirectories` / read-only `additionalReadDirectories`), or the deployment-level
+ * `readFace: "open"` for reads.
  *
- * A trailing sentence naming the shell as unconfined by this fence was REMOVED (it had been kept on
- * the argument that a statement of fact is not a recommendation, and that omitting it would only let
- * the model discover the same thing by trial). A live retest settled that argument the other way: a
- * refused agent read the sentence as the next step, went to the shell, and rewrote through it the
- * very file the fence had just protected. A refusal card is a PROMPT surface — naming, at the moment
- * of denial, a second tool that does not enforce the boundary is a recipe whatever its grammar, and
- * the model cannot be relied on to hear "fact, not advice". The underlying fact is unchanged and
- * still documented where humans read it (design/44 §5: the shell is deliberately unconfined by this
- * fence, and every shell call still passes the deployment's approval policy); it is simply no longer
- * handed to the model inside a denial. What the card says now: this is denied, and here is the
- * sanctioned way to be allowed.
+ * It deliberately does NOT name the shell as unconfined by this fence, even though that is a true
+ * statement rather than a recommendation. A live retest settled the question: a refused agent read
+ * such a sentence as the next step, went to the shell, and rewrote through it the very file the fence
+ * had just protected. A refusal card is a PROMPT surface — naming, at the moment of denial, a second
+ * tool that does not enforce the boundary is a recipe whatever its grammar, and the model cannot be
+ * relied on to hear "fact, not advice". The underlying fact is documented where humans read it (the
+ * shell is deliberately unconfined by this fence, and every shell call still passes the deployment's
+ * approval policy); it is simply not handed to the model inside a denial.
  */
 export declare const PATH_NOT_IN_ROOT_ESCAPE_HINT = "(This boundary applies to the structured file tools. If you genuinely need content outside the allowed root(s), ask for the directory to be added to the deployment's additionalDirectories \u2014 or additionalReadDirectories for read-only access; a deployment that wants reads open everywhere can declare readFace: \"open\" instead of listing directories.)";
 /** inv 1 (read-before-edit): a file must have been read this task before it can be edited/overwritten.
  *  Message is CC 2.1.198 live-verbatim (all-tools-live-probe 2026-07-08 §2.1/§3.1/§5.1 — one message for
  *  Edit/Write/NotebookEdit: "before writing to it", not the old sema "before editing").
  *
- * RB-200 F2 (CC 220 corpus-confirmed, @367198/@367671 — Edit and Write spell the read gate identically,
- * `!p || p.isPartialView`): an AUTO-TRUNCATED read (the model asked for the
- * file by default, no explicit offset/limit, and the token cap cut it anyway — {@link ReadEntry.isPartialView})
- * used to satisfy this gate exactly like a full read (`state.has(key)` alone was the whole check) — the
- * model could Write (full overwrite) or Edit a file having genuinely seen only its first page, silently
- * destroying or blind-editing the unseen remainder. CC's own gate treats "never read" and "auto-truncated
+ * CC parity (Edit and Write spell the read gate identically, `!p || p.isPartialView`): an
+ * AUTO-TRUNCATED read (the model asked for the file by default, no explicit offset/limit, and the token
+ * cap cut it anyway — {@link ReadEntry.isPartialView}) must NOT satisfy this gate. With `state.has(key)`
+ * alone as the whole check, the model could Write (full overwrite) or Edit a file having genuinely seen
+ * only its first page, silently destroying or blind-editing the unseen remainder. CC's own gate treats
+ * "never read" and "auto-truncated
  * partial view" identically for BOTH tools — no softer rule for Edit (whose old_string match only touches
  * a small snippet) versus Write (which replaces everything), so this doesn't carve one out either.
  *
@@ -394,8 +497,7 @@ export declare function requireRead(state: ReadFileState, key: string): FsViolat
  */
 export declare const OVERSIZE_READ_ESCAPE_HINT = "(This file is over the Read tool's whole-file byte cap, so a default Read is refused \u2014 read it in slices with explicit offset/limit to satisfy the read-first rule, or inspect/transform it with bash (e.g. `sed -n`, `grep`) instead.)";
 /**
- * RB-264 N1 (repro `notebookedit-tool-read-gate-deadlock` assertion A.c2) —
- * the escape-hatch parenthetical for the OTHER shape of the read-before-edit refusal: the file was read,
+ * The escape-hatch parenthetical for the OTHER shape of the read-before-edit refusal: the file was read,
  * but the read was AUTO-PAGINATED by the output token cap ({@link ReadEntry.isPartialView}), so only the
  * first page was ever seen. The oversize branch above has named its escape route since the fidelity
  * sweep; this branch named none — and it is the worse of the two, because the refusal's own advice
@@ -406,29 +508,29 @@ export declare const OVERSIZE_READ_ESCAPE_HINT = "(This file is over the Read to
  */
 export declare const PARTIAL_VIEW_READ_ESCAPE_HINT = "(Your last Read of this file returned only a PARTIAL view \u2014 the output token cap paginated it, so a default Read will keep returning the same page. Re-read it with explicit offset/limit (start from the page marker's next-page hint) until you have seen the part you are about to change; an explicit slice that fits satisfies the read-first rule. Or inspect/transform it with bash (e.g. `sed -n`, `grep`) instead.)";
 /**
- * RB-264 ⑥W1 — the escape-hatch parenthetical for the ONE shape of the
- * read-first deadlock that nothing observable diagnoses: a file the Read tool REFUSES (binary /
+ * The escape-hatch parenthetical for the ONE shape of the read-first deadlock that nothing observable
+ * diagnoses: a file the Read tool REFUSES (binary /
  * BOM-less UTF-16 / unknown encoding) can never satisfy read-before-write, and — unlike the oversize
  * and partial-view shapes — leaves no trace the refusal renderer can stat for. It is therefore the
  * renderer's FALLBACK hint (least specific, appended only when no sharper branch fired); appending it
  * beside a sharper one would assert something false, since both of those shapes are files Read handled.
  * Kept byte-identical to the sentence Write rendered inline before it moved here.
  *
- * ANG-6 (external black-box re-review, ruled 2026-08-03): the deadlock is a property of the READ GATE,
+ * The deadlock is a property of the READ GATE,
  * not of Write — Edit and NotebookEdit hit the identical dead end and used to render the bare sentence
  * with no way out named. All three now pass this one constant, which is why it is no longer named for
  * the tool that happened to have it first: one sentence, three call sites, nothing to drift apart.
  */
 export declare const READ_REFUSED_ESCAPE_HINT = "(If the Read tool refuses this file (binary/unknown encoding), overwrite or convert it with bash instead \u2014 e.g. `rm` + rewrite, or `iconv`.)";
 /**
- * Edit "no-op" guard (design/64 §7.2(4), CC `FileEditTool:148-153`): refuse an edit whose `old_string`
+ * Edit "no-op" guard (CC FileEditTool parity): refuse an edit whose `old_string`
  * equals `new_string` — without it the edit passes the match check and writes the file back unchanged (a
  * silent no-op that wastes a turn and dirties mtime). Verbatim CC message so a CC-trained model recognizes it.
  */
 export declare function checkNoChange(oldString: string, newString: string): FsViolation | undefined;
 /** inv 2 (staleness): the file's current content hash must match what was recorded at read time.
  *
- *  RB-436-g: takes `ReadEntry | undefined` and treats an ABSENT entry as stale (fail-closed). The three
+ *  Takes `ReadEntry | undefined` and treats an ABSENT entry as stale (fail-closed). The three
  *  write-side callers prove the entry exists with `requireRead`, then re-read the file — an `await` — and
  *  only then reach here, so each was asserting a pre-await invariant across a suspension point with `!`.
  *  Nothing deletes read state mid-turn today (the compaction sweep runs at a turn boundary), so behaviour
@@ -441,7 +543,7 @@ export declare function countOccurrences(haystack: string, needle: string): numb
  * Suggest a sibling filename for a missing path (CC `File does not exist… Did you mean X?` self-heal
  * path, bundle :335883/:478419). Honest scope (1.253 双轨终审): this is the FALLBACK tier — an
  * approximation of CC's Cxe same-directory scan plus a sema-added case-insensitive exact-name match
- * (the case-typo class CC misses). RB-285 (归因更正): CC's FIRST-tier suggester is `G_e` — a GATED
+ * (the case-typo class CC misses). Registered delta: CC's FIRST-tier suggester is a GATED
  * sibling-tree REBASE (`join(cwd, relative(dirname(cwd), missing))`, only for a path under the cwd's
  * parent but not under the cwd), NOT the "re-resolve the filename against cwd" this comment used to
  * claim; the full geometry and the sema delta are recorded at the call site (fs-shared.ts
@@ -460,14 +562,14 @@ export declare function normalizeQuotes(s: string): string;
  */
 export declare function resolveQuoteMatch(content: string, oldString: string): string | undefined;
 /**
- * RB-285 M9 (CC `Pdt` layers 3+4, @366594-366600): resolve `oldString` against `content` across the
+ * CC's forgiving-match layers 3+4: resolve `oldString` against `content` across the
  * escape/literal spelling boundary. Returns the ACTUAL span present in `content` (which is what must be
  * replaced), or `undefined` when neither spelling is present. Pure — call only after an exact match and
  * the curly-quote layer have both missed.
  */
 export declare function resolveEscapeMatch(content: string, oldString: string): string | undefined;
 /**
- * RB-285 M9 (CC `YZu` verbatim, @366561-366587): rewrite `newString` into the SAME spelling the matched
+ * CC `YZu` verbatim: rewrite `newString` into the SAME spelling the matched
  * span uses. Without this, a match found through {@link resolveEscapeMatch} would replace an escaped
  * span with a literal-character replacement (or vice versa) and silently change the file's encoding
  * convention at that spot. Hex case follows what the file itself used, per-character where known and by
@@ -477,7 +579,7 @@ export declare function adaptNewStringEscapes(oldString: string, matchedOld: str
 /** CC `KZu` (@366558): the old_string shapes for which the escape layers above were even attempted —
  *  gates the explanatory note appended to a no-match refusal so it is never a false claim. */
 export declare function escapeMatchWasAttempted(oldString: string): boolean;
-/** RB-285 M9 — CC `KZu`'s note (@367245-367248) verbatim. */
+/** CC `KZu`'s note, verbatim. */
 export declare const ESCAPE_MATCH_MISS_NOTE = "\n(note: Edit also tried swapping \\uXXXX escapes and their characters; neither form matched, so the mismatch is likely elsewhere in old_string. Re-read the file and copy the exact surrounding text.)";
 /**
  * When the quote-forgiving match resolved to a curly-quoted file span, convert the straight quotes in
@@ -508,3 +610,4 @@ export declare function deletionOldString(content: string, oldString: string, ne
  *  matters most (and these refusals return as tool results, which do not pass the loop-level budget). */
 export declare const EDIT_ECHO_MAX_CHARS = 200;
 export declare function checkEditMatch(content: string, oldString: string, replaceAll: boolean, truncated: boolean): FsViolation | undefined;
+export {};