just-bash 3.0.3 → 3.2.0

package/dist/commands/xan/xan-reshape.d.ts

@@ -1,7 +1,7 @@
 /**
  * Reshape commands: explode, implode, flatmap, pivot, join, merge
  */
-import type { CommandContext, ExecResult } from "../../types.js";
+import type { ExecResult, RuntimeCommandContext } from "../../types.js";
 /**
  * Explode: split delimited column values into multiple rows
  * Usage: xan explode COLUMN [OPTIONS] [FILE]
@@ -9,14 +9,14 @@ import type { CommandContext, ExecResult } from "../../types.js";
  *   --drop-empty         Drop rows where column is empty
  *   -r, --rename NAME    Rename the column
  */
-export declare function cmdExplode(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdExplode(args: string[], ctx: RuntimeCommandContext): Promise<ExecResult>;
 /**
  * Implode: combine consecutive rows with same key, joining column values
  * Usage: xan implode COLUMN [OPTIONS] [FILE]
  *   -s, --separator SEP  Value separator (default: |)
  *   -r, --rename NAME    Rename the column
  */
-export declare function cmdImplode(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdImplode(args: string[], ctx: RuntimeCommandContext): Promise<ExecResult>;
 /**
  * Join: join two CSV files on key columns
  * Usage: xan join KEY1 FILE1 KEY2 FILE2 [OPTIONS]
@@ -25,16 +25,16 @@ export declare function cmdImplode(args: string[], ctx: CommandContext): Promise
  *   --full       Full outer join (keep all rows from both files)
  *   -D, --default VALUE  Default value for missing fields
  */
-export declare function cmdJoin(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdJoin(args: string[], ctx: RuntimeCommandContext): Promise<ExecResult>;
 /**
  * Pivot: reshape data by turning row values into columns
  * Usage: xan pivot COLUMN AGG_EXPR [OPTIONS] [FILE]
  *   -g, --groupby COLS   Group by these columns (default: all other columns)
  */
-export declare function cmdPivot(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdPivot(args: string[], ctx: RuntimeCommandContext): Promise<ExecResult>;
 /**
  * Merge: merge multiple sorted CSV files
  * Usage: xan merge [OPTIONS] FILE1 FILE2 ...
  *   -s, --sort COLUMN   Sort column (files must be pre-sorted by this)
  */
-export declare function cmdMerge(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdMerge(args: string[], ctx: RuntimeCommandContext): Promise<ExecResult>;

package/dist/commands/xan/xan-simple.d.ts

@@ -1,24 +1,24 @@
 /**
  * Simple commands: behead, sample, cat, search, flatmap, fmt
  */
-import type { CommandContext, ExecResult } from "../../types.js";
+import type { ExecResult, RuntimeCommandContext } from "../../types.js";
 /**
  * Behead: remove header row from CSV (output data rows only)
  * Usage: xan behead [FILE]
  */
-export declare function cmdBehead(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdBehead(args: string[], ctx: RuntimeCommandContext): Promise<ExecResult>;
 /**
  * Sample: randomly sample N rows from CSV
  * Usage: xan sample [OPTIONS] <sample-size> [FILE]
  *   --seed SEED    Random seed for reproducibility
  */
-export declare function cmdSample(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdSample(args: string[], ctx: RuntimeCommandContext): Promise<ExecResult>;
 /**
  * Cat: concatenate CSV files
  * Usage: xan cat [OPTIONS] FILE1 FILE2 ...
  *   -p, --pad    Pad missing columns with empty values
  */
-export declare function cmdCat(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdCat(args: string[], ctx: RuntimeCommandContext): Promise<ExecResult>;
 /**
  * Search: filter rows by regex match on any/specific columns
  * Usage: xan search [OPTIONS] PATTERN [FILE]
@@ -26,15 +26,15 @@ export declare function cmdCat(args: string[], ctx: CommandContext): Promise<Exe
  *   -v, --invert         Invert match (exclude matching rows)
  *   -i, --ignore-case    Case insensitive match
  */
-export declare function cmdSearch(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdSearch(args: string[], ctx: RuntimeCommandContext): Promise<ExecResult>;
 /**
  * Flatmap: like map but expression can return multiple rows
  * Usage: xan flatmap EXPR [FILE]
  *   The expression should return an array; each element becomes a row
  */
-export declare function cmdFlatmap(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdFlatmap(args: string[], ctx: RuntimeCommandContext): Promise<ExecResult>;
 /**
  * Fmt: format CSV as a table (alias for view with options)
  * Usage: xan fmt [OPTIONS] [FILE]
  */
-export declare function cmdFmt(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdFmt(args: string[], ctx: RuntimeCommandContext): Promise<ExecResult>;

package/dist/commands/xan/xan-view.d.ts

@@ -1,12 +1,12 @@
 /**
  * View commands: pretty print CSV as table or flattened records
  */
-import type { CommandContext, ExecResult } from "../../types.js";
+import type { ExecResult, RuntimeCommandContext } from "../../types.js";
 /**
  * Flatten: display records vertically, one field per line
  * Usage: xan flatten [OPTIONS] [FILE]
  *   -l, --limit N    Maximum number of rows to display
  *   -s, --select COLS  Select columns to display
  */
-export declare function cmdFlatten(args: string[], ctx: CommandContext): Promise<ExecResult>;
-export declare function cmdView(args: string[], ctx: CommandContext): Promise<ExecResult>;
+export declare function cmdFlatten(args: string[], ctx: RuntimeCommandContext): Promise<ExecResult>;
+export declare function cmdView(args: string[], ctx: RuntimeCommandContext): Promise<ExecResult>;

package/dist/commands/xan/xan.d.ts

@@ -4,7 +4,7 @@
  * Provides ergonomic CLI for CSV operations, translating commands to jq expressions
  * and using the shared query engine. Inspired by xsv and xan tools.
  */
-import type { Command } from "../../types.js";
-export declare const xanCommand: Command;
+import type { RuntimeCommand } from "../../types.js";
+export declare const xanCommand: RuntimeCommand;
 import type { CommandFuzzInfo } from "../fuzz-flags-types.js";
 export declare const flagsForFuzzing: CommandFuzzInfo;

package/dist/commands/xargs/xargs.d.ts

@@ -1,4 +1,4 @@
-import type { Command } from "../../types.js";
-export declare const xargsCommand: Command;
+import type { RuntimeCommand } from "../../types.js";
+export declare const xargsCommand: RuntimeCommand;
 import type { CommandFuzzInfo } from "../fuzz-flags-types.js";
 export declare const flagsForFuzzing: CommandFuzzInfo;

package/dist/commands/yq/formats.d.ts

@@ -4,6 +4,7 @@
  * Supports YAML, JSON, XML, INI, CSV, and TOML formats with conversion between them.
  */
 import type { QueryValue } from "../query-engine/index.js";
+import { type SanitizeParsedDataLimits } from "../query-engine/safe-object.js";
 export type InputFormat = "yaml" | "xml" | "json" | "ini" | "csv" | "toml";
 export type OutputFormat = "yaml" | "json" | "xml" | "ini" | "csv" | "toml";
 /**
@@ -44,21 +45,21 @@ export declare function detectFormatFromExtension(filename: string): InputFormat
 /**
  * Parse input data from the given format into a QueryValue
  */
-export declare function parseInput(input: string, options: FormatOptions): QueryValue;
+export declare function parseInput(input: string, options: FormatOptions, limits?: SanitizeParsedDataLimits): QueryValue;
 /**
  * Parse all YAML documents from input (for slurp mode)
  */
-export declare function parseAllYamlDocuments(input: string): QueryValue[];
+export declare function parseAllYamlDocuments(input: string, limits?: SanitizeParsedDataLimits): QueryValue[];
 /**
  * Extract front-matter from content
  * Front-matter is YAML/TOML/JSON at the start of a file between --- or +++ delimiters
  * Returns { frontMatter: parsed data, content: remaining content } or null if no front-matter
  */
-export declare function extractFrontMatter(input: string): {
+export declare function extractFrontMatter(input: string, limits?: SanitizeParsedDataLimits): {
     frontMatter: QueryValue;
     content: string;
 } | null;
 /**
  * Format a QueryValue for output in the given format
  */
-export declare function formatOutput(value: QueryValue, options: FormatOptions): string;
+export declare function formatOutput(value: QueryValue, options: FormatOptions, maxBytes?: number): string;

package/dist/commands/yq/yq.d.ts

@@ -1,5 +1,5 @@
 /**
- * yq - Command-line YAML/XML/INI/CSV/TOML processor
+ * yq - RuntimeCommand-line YAML/XML/INI/CSV/TOML processor
  *
  * Uses jq-style query expressions to process YAML, XML, INI, CSV, and TOML files.
  * Shares the query engine with jq for consistent filtering behavior.
@@ -7,7 +7,7 @@
  * Inspired by mikefarah/yq (https://github.com/mikefarah/yq)
  * This is a reimplementation for the just-bash sandboxed environment.
  */
-import type { Command } from "../../types.js";
-export declare const yqCommand: Command;
+import type { RuntimeCommand } from "../../types.js";
+export declare const yqCommand: RuntimeCommand;
 import type { CommandFuzzInfo } from "../fuzz-flags-types.js";
 export declare const flagsForFuzzing: CommandFuzzInfo;

package/dist/custom-commands.d.ts

@@ -3,7 +3,10 @@
  *
  * Provides types and utilities for registering user-provided TypeScript commands.
  */
-import type { Command, CommandContext, ExecResult } from "./types.js";
+import { type ByteString } from "./encoding.js";
+import type { IFileSystem } from "./fs/interface.js";
+import { type ExecutionLimitProfile, type ExecutionLimits } from "./limits.js";
+import type { Command, CommandContext, ExecResult, ResolvedCommandContext, RuntimeCommandContext } from "./types.js";
 /**
  * A custom command - either a Command object or a lazy loader.
  */
@@ -13,8 +16,26 @@ export type CustomCommand = Command | LazyCommand;
  */
 export interface LazyCommand {
     name: string;
+    /**
+     * Set false to run through the restricted extension boundary. Commands are
+     * trusted by default for compatibility with existing host integrations.
+     */
+    trusted?: boolean;
     load: () => Promise<Command>;
 }
+/** Inputs for a complete standalone command context, primarily for tests. */
+export interface CommandContextOptions extends Omit<Partial<CommandContext>, "fs" | "limits" | "stdin"> {
+    fs: IFileSystem;
+    stdin?: ByteString;
+    executionLimits?: ExecutionLimits;
+    executionLimitProfile?: ExecutionLimitProfile;
+}
+/**
+ * Build the same resolved public context shape that the interpreter gives a
+ * custom command. This avoids hand-maintained test objects drifting whenever
+ * an internal execution limit is added.
+ */
+export declare function createCommandContext(options: CommandContextOptions): RuntimeCommandContext;
 /**
  * Type guard to check if a custom command is lazy-loaded.
  */
@@ -34,7 +55,9 @@ export declare function isLazyCommand(cmd: CustomCommand): cmd is LazyCommand;
  * await bash.exec("hello Alice"); // "Hello, Alice!\n"
  * ```
  */
-export declare function defineCommand(name: string, execute: (args: string[], ctx: CommandContext) => Promise<ExecResult>): Command;
+export declare function defineCommand(name: string, execute: (args: string[], ctx: ResolvedCommandContext) => Promise<ExecResult>, options?: {
+    trusted?: boolean;
+}): Command;
 /**
  * Create a lazy-loaded wrapper for a custom command.
  * The command is only loaded when first executed.

package/dist/encoding.d.ts

@@ -19,6 +19,8 @@ declare const __byteString: unique symbol;
 export interface ByteString {
     readonly [__byteString]: true;
 }
+/** Return UTF-8 byte length without allocating an encoded copy. */
+export declare function utf8ByteLength(value: string): number;
 /**
  * Tag a latin1 byte buffer (each char = one byte) as a `ByteString`. Use at
  * the pipeline edge: `cmdCtx.stdin = unsafeBytesFromLatin1(prevStdout)`.
@@ -41,21 +43,21 @@ export declare function latin1FromBytes(b: ByteString): string;
  * a binary stream piped into grep). Callers that want hard failure on
  * invalid UTF-8 should encode + decode manually with `{ fatal: true }`.
  */
-export declare function decodeBytesToUtf8(b: ByteString): string;
+export declare function decodeBytesToUtf8(b: ByteString, maxBytes?: number): string;
 /**
  * UTF-8 encode `s` (treating every char as a Unicode codepoint) into a
  * `ByteString`. Use at sites that *know* their input is decoded Unicode
  * text and need to emit it back as bytes — typically the inverse of an
  * earlier `decodeBytesToUtf8` call inside the same command.
  */
-export declare function encodeUtf8ToBytes(s: string): ByteString;
+export declare function encodeUtf8ToBytes(s: string, maxBytes?: number): ByteString;
 /** The empty `ByteString`. */
 export declare const EMPTY_BYTES: ByteString;
 /**
  * Convert a `Uint8Array` to a `ByteString`. Each byte becomes one char.
  * The reverse is `Uint8Array.from(latin1FromBytes(b), (c) => c.charCodeAt(0))`.
  */
-export declare function bytesFromUint8Array(buf: Uint8Array): ByteString;
+export declare function bytesFromUint8Array(buf: Uint8Array, maxBytes?: number): ByteString;
 /**
  * Read a file's raw bytes from any `IFileSystem`. Prefers the optional
  * {@link IFileSystem.readFileBytes} method (built-in filesystems implement

package/dist/execution-output.d.ts

@@ -0,0 +1,28 @@
+import type { ExecutionScope } from "./execution-scope.js";
+import type { ExecResult } from "./types.js";
+/**
+ * Chunked interpreter-output sink backed by the one top-level execution
+ * budget. Accounting metadata follows bytes as compound commands relay child
+ * results, avoiding both budget refreshes and double charging.
+ */
+export declare class ExecutionOutputAccumulator {
+    private readonly scope;
+    private readonly site;
+    private readonly stdoutChunks;
+    private readonly stderrChunks;
+    private stdoutBytes;
+    private stderrBytes;
+    private readonly attachedErrors;
+    constructor(scope: ExecutionScope, site: string);
+    append(stream: "stdout" | "stderr", chunk: string, alreadyAccountedBytes?: number, kind?: "text" | "bytes"): void;
+    /**
+     * Attach output retained before a fatal/control-flow error exactly once for
+     * this accumulator. The bytes have already been charged by the shared scope,
+     * so propagation updates accounting metadata without charging them again.
+     */
+    prependTo(error: unknown): void;
+    appendResult(result: ExecResult, stdout?: string): void;
+    build(exitCode: number, extra?: Partial<ExecResult>): ExecResult;
+    get stdout(): string;
+    get stderr(): string;
+}

package/dist/execution-scope.d.ts

@@ -0,0 +1,89 @@
+import { ExecutionAbortedError } from "./interpreter/errors.js";
+import type { ExecutionLimits } from "./limits.js";
+import type { ExecResult } from "./types.js";
+export interface ResourceLease {
+    release(): void;
+}
+/**
+ * Accounting capability exposed to commands. Administrative lifecycle and
+ * result-accounting operations intentionally remain on ExecutionScope only.
+ */
+export interface CommandExecutionBudget {
+    readonly remainingLiveBytes: number;
+    consumeWork(units?: number, site?: string): number;
+    consumeLimited(kind: string, count: number, maximum: number, site?: string): number;
+    consumeInput(bytes: number, site?: string): number;
+    reserveBytes(bytes: number, site?: string): ResourceLease;
+    reserveBytes(kind: string, bytes: number, site?: string): ResourceLease;
+    enterDepth(kind: string, site?: string): ResourceLease;
+    enterDepth(kind: string, maximum: number, site?: string): ResourceLease;
+    throwIfAborted(site?: string): void;
+    remainingTimeMs(): number;
+    registerCleanup(cleanup: Cleanup): () => void;
+}
+type Cleanup = () => void | Promise<void>;
+/**
+ * Security-sensitive accounting shared by every interpreter descended from a
+ * single public Bash.exec() call. This object is never accepted from callers;
+ * nested exec functions capture it in a closure instead.
+ *
+ * Keep reservations centralized here so future output/byte/filesystem budgets
+ * cannot accidentally be refreshed by starting a child interpreter.
+ */
+export declare class ExecutionScope {
+    private readonly limits;
+    private readonly signal;
+    private commandCount;
+    private workUnits;
+    private liveBytes;
+    private inputBytes;
+    private outputBytes;
+    private readonly countersByKind;
+    private readonly bytesByKind;
+    private readonly depthByKind;
+    private readonly cleanupCallbacks;
+    private poisoned;
+    private closed;
+    private readonly startedAt;
+    /** Bytes still available for prospective intermediate allocations. */
+    get remainingLiveBytes(): number;
+    /** Snapshot used to prove accounting inherited from a nested execution. */
+    get outputBytesUsed(): number;
+    constructor(limits: Required<ExecutionLimits>, signal?: AbortSignal | undefined);
+    private fail;
+    /** Permanently reject later work after an extension misses cancellation. */
+    poisonAfterAbort(error: ExecutionAbortedError): void;
+    private assertUsable;
+    chargeCommand(): number;
+    consumeWork(units?: number, site?: string): number;
+    /** Charge both the aggregate work budget and a narrower operation budget. */
+    consumeLimited(kind: string, count: number, maximum: number, site?: string): number;
+    consumeInput(bytes: number, site?: string): number;
+    consume(kind: string, count?: number, site?: string): number;
+    reserveBytes(bytes: number, site?: string): ResourceLease;
+    reserveBytes(kind: string, bytes: number, site?: string): ResourceLease;
+    appendOutput(stream: "stdout" | "stderr", chunk: string, site?: string, alreadyAccountedBytes?: number, kind?: "text" | "bytes"): number;
+    accountResult(result: ExecResult, site?: string, maximumPriorBytes?: number): ExecResult;
+    /**
+     * Relinquish bytes that were charged while a result was retained but have
+     * since become a transient pipeline input. This is deliberately limited to
+     * bytes carried by internal accounting metadata; callers must not use it to
+     * refund arbitrary output.
+     */
+    /** @internal Use relinquishPipelineOutput; the authority prevents extensions
+     * that receive an ExecutionScope from refunding their own output. */
+    relinquishOutput(bytes: number, site: string, authority: object): void;
+    enterDepth(kind: string, site?: string): ResourceLease;
+    enterDepth(kind: string, maximum: number, site?: string): ResourceLease;
+    throwIfAborted(site?: string): void;
+    remainingTimeMs(): number;
+    registerCleanup(cleanup: Cleanup): () => void;
+    close(): Promise<void>;
+    assertExecDepth(depth: number): void;
+}
+/** Build a least-authority view for command implementations. */
+export declare function createCommandExecutionBudget(scope: ExecutionScope): CommandExecutionBudget;
+/** Release a checked pipeline intermediate without exposing refund authority
+ * through the ExecutionScope capability supplied to custom commands. */
+export declare function relinquishPipelineOutput(scope: ExecutionScope, bytes: number, site?: string): void;
+export {};

package/dist/fatal-execution-error.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Rethrow errors that command-level recovery must never turn into ordinary
+ * command failures. Call this first in broad catch blocks.
+ */
+export declare function rethrowFatalExecutionError(error: unknown): void;

package/dist/fs/identity.d.ts

@@ -0,0 +1,9 @@
+import type { IFileSystem } from "./interface.js";
+/**
+ * Return an inert identity token for a filesystem. The token deliberately has
+ * no prototype or reference back to the filesystem: consumers may safely use
+ * it as a WeakMap key without acquiring filesystem authority.
+ */
+export declare function getFileSystemIdentity(fs: IFileSystem): object;
+/** True only for inert tokens created by getFileSystemIdentity(). */
+export declare function isFileSystemIdentity(value: object): boolean;

package/dist/fs/in-memory-fs/in-memory-fs.d.ts

@@ -4,9 +4,32 @@ export type { BufferEncoding, FileContent, FileEntry, LazyFileEntry, DirectoryEn
 export interface FsData {
     [path: string]: FsEntry;
 }
+export interface InMemoryFsOptions {
+    /** Aggregate materialized file bytes retained by this filesystem. */
+    maxTotalBytes?: number;
+}
 export declare class InMemoryFs implements IFileSystem {
     private data;
-    constructor(initialFiles?: InitialFiles);
+    private entryIdentities;
+    private nextEntryIdentity;
+    private readonly maxTotalBytes;
+    private retainedBytes;
+    /** Number of directory entries retaining each hard-link-compatible buffer. */
+    private contentReferences;
+    private materializedContent;
+    private storedByteLength;
+    private wouldReleaseBytes;
+    /**
+     * Check a newly allocated, unique file body before creating its buffer.
+     * Replacing the final reference to an old body credits those bytes.
+     */
+    private assertCanAllocate;
+    /** Replace one path while updating retained storage in constant time. */
+    private setEntry;
+    private deleteEntry;
+    private contentByteLength;
+    private identityFor;
+    constructor(initialFiles?: InitialFiles, options?: InMemoryFsOptions);
     private ensureParentDirs;
     writeFileSync(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding, metadata?: {
         mode?: number;

package/dist/fs/interface.d.ts

@@ -66,6 +66,10 @@ export interface FsStat {
     mode: number;
     size: number;
     mtime: Date;
+    /** Stable filesystem identity when the backend can expose it safely. */
+    dev?: number | bigint;
+    ino?: number | bigint;
+    identity?: string;
 }
 /**
  * Options for mkdir operation

package/dist/fs/overlay-fs/overlay-fs.d.ts

@@ -36,6 +36,11 @@ export interface OverlayFsOptions {
      * Defaults to 10MB (10485760).
      */
     maxFileReadSize?: number;
+    /**
+     * Maximum bytes retained by copy-on-write files in the memory layer.
+     * Defaults to 1 GiB. Real backing files are not counted until copied.
+     */
+    maxMemoryBytes?: number;
     /**
      * Whether to allow following and creating symlinks on the real filesystem.
      * When false (default), any real-FS path traversing a symlink is rejected
@@ -49,9 +54,17 @@ export declare class OverlayFs implements IFileSystem {
     private readonly mountPoint;
     private readonly readOnly;
     private readonly maxFileReadSize;
+    private readonly maxMemoryBytes;
     private readonly allowSymlinks;
     private readonly memory;
     private readonly deleted;
+    private nextMemoryIdentity;
+    private retainedMemoryBytes;
+    private memoryEntryBytes;
+    private assertMemoryCapacity;
+    private setMemoryEntry;
+    private deleteMemoryEntry;
+    private identityFor;
     constructor(options: OverlayFsOptions);
     /**
      * Throws an error if the filesystem is in read-only mode.

package/dist/fs/path-utils.d.ts

@@ -18,6 +18,8 @@ export declare const SYMLINK_MODE = 511;
  * strip trailing slashes.  Pure function, no I/O.
  */
 export declare function normalizePath(path: string): string;
+/** True when candidate is the same virtual path as parent or below it. */
+export declare function isSameOrDescendantPath(parent: string, candidate: string): boolean;
 /**
  * Validate that a path does not contain null bytes.
  * Null bytes in paths can be used to truncate filenames or bypass security

package/dist/fs/read-write-fs/read-write-fs.d.ts

@@ -37,6 +37,7 @@ export declare class ReadWriteFs implements IFileSystem {
     private readonly canonicalRoot;
     private readonly maxFileReadSize;
     private readonly allowSymlinks;
+    private transactionId;
     constructor(options: ReadWriteFsOptions);
     /**
      * Validate that a resolved real path stays within the sandbox root and
@@ -69,7 +70,17 @@ export declare class ReadWriteFs implements IFileSystem {
     readdirWithFileTypes(path: string): Promise<DirentEntry[]>;
     rm(path: string, options?: RmOptions): Promise<void>;
     cp(src: string, dest: string, options?: CpOptions): Promise<void>;
+    private preflightCopyTree;
     mv(src: string, dest: string): Promise<void>;
+    /** Compare canonical path identity, not user-visible lexical spelling. */
+    private isSameOrDescendantIdentity;
+    private uniqueTransactionPath;
+    /**
+     * Transactional EXDEV fallback. The destination is assembled under a hidden
+     * sibling, then committed by rename. Source removal is also staged by rename,
+     * so failures can restore both visible names without claiming atomicity.
+     */
+    private moveAcrossDevices;
     resolvePath(base: string, path: string): string;
     getAllPaths(): string[];
     private sanitizeError;

package/dist/fs/real-fs-utils.d.ts

@@ -9,7 +9,7 @@
  * live in path-utils.ts (no node:fs dependency, browser-safe) and are
  * re-exported here for convenience.
  */
-export { normalizePath, validatePath } from "./path-utils.js";
+export { isSameOrDescendantPath, normalizePath, validatePath, } from "./path-utils.js";
 /**
  * Check whether `resolved` is equal to, or a child of, `canonicalRoot`.
  * Uses a boundary-safe prefix check (appends `/`) so that `/data` does not

package/dist/fs/traversal.d.ts

@@ -0,0 +1,98 @@
+import type { CommandExecutionBudget } from "../execution-scope.js";
+import type { ExecutionLimits } from "../limits.js";
+import type { FsStat, IFileSystem } from "./interface.js";
+declare const canonicalPathBrand: unique symbol;
+/** A canonical virtual path proven to be inside a particular validation root. */
+export type CanonicalPath<Policy extends string = string> = string & {
+    readonly [canonicalPathBrand]: Policy;
+};
+export interface CanonicalPathPolicy<Policy extends string> {
+    readonly name: Policy;
+    readonly root: string;
+}
+export declare function canonicalizePath<Policy extends string>(fs: IFileSystem, path: string, policy: CanonicalPathPolicy<Policy>): Promise<CanonicalPath<Policy>>;
+export declare class FileSystemPolicyError extends Error {
+    readonly operation: string;
+    readonly virtualPath: string;
+    readonly name = "FileSystemPolicyError";
+    constructor(operation: string, virtualPath: string, message: string);
+}
+export type SameFileResult = "same" | "different" | "unknown";
+export type PathContainmentResult = "inside" | "outside" | "unknown";
+export type ResolvedFileIdentity = {
+    readonly existence: "existing";
+    readonly canonicalPath?: string;
+    readonly stableIdentity?: string;
+} | {
+    readonly existence: "missing";
+    /** Canonical nearest-existing parent plus every missing path component. */
+    readonly canonicalPath?: string;
+} | {
+    readonly existence: "unknown";
+};
+/**
+ * Resolve an existing path to both its canonical spelling and, where the
+ * backend supports it, an alias-resistant identity. For a path that does not
+ * exist, canonicalize the nearest existing parent and append all missing
+ * components. Other failures remain unknown rather than being treated as
+ * non-existence.
+ */
+export declare function resolveFileIdentity(fs: IFileSystem, path: string, budget?: FileTraversalBudget): Promise<ResolvedFileIdentity>;
+/**
+ * Conservatively compare two paths. `unknown` forces destructive callers to
+ * stage work instead of treating an inability to prove identity as inequality.
+ */
+export declare function compareFileIdentity(fs: IFileSystem, left: string, right: string): Promise<SameFileResult>;
+/**
+ * Resolve an existing destination or its nearest existing parent before a
+ * recursive copy/move. This closes lexical-prefix gaps created by directory
+ * aliases while retaining `unknown` for backends that cannot prove it.
+ */
+export declare function compareCanonicalContainment(fs: IFileSystem, sourceDirectory: string, destination: string, budget?: FileTraversalBudget): Promise<PathContainmentResult>;
+export type SymlinkTraversalPolicy = "never" | "follow";
+export interface TraversalBudgetOptions {
+    readonly limits: Required<ExecutionLimits>;
+    readonly signal?: AbortSignal;
+    readonly executionScope?: CommandExecutionBudget;
+    readonly site: string;
+    /** User-facing resource name for commands with established diagnostics. */
+    readonly label?: string;
+}
+/** One shared, command-local view over the top-level execution work budget. */
+export declare class FileTraversalBudget {
+    private readonly options;
+    private entries;
+    private discoveredEntries;
+    private work;
+    constructor(options: TraversalBudgetOptions);
+    checkpoint(work?: number): void;
+    visit(depth: number): void;
+    /**
+     * Reserve directory children before retaining work items for them. A single
+     * readdir can return far more entries than the traversal is allowed to
+     * process, so waiting until each child is visited permits an oversized queue
+     * allocation first.
+     */
+    discover(count: number): void;
+}
+export interface TraversalEntry {
+    readonly path: string;
+    readonly depth: number;
+    readonly stat: FsStat;
+    readonly isSymlink: boolean;
+    readonly phase: "enter" | "leave";
+}
+export interface TraverseFileTreeOptions extends TraversalBudgetOptions {
+    readonly fs: IFileSystem;
+    readonly root: string;
+    readonly symlinks?: SymlinkTraversalPolicy;
+    readonly includeLeave?: boolean;
+    readonly budget?: FileTraversalBudget;
+}
+/**
+ * Iterative, deterministic DFS. Directory identities stay active until their
+ * leave marker, detecting ancestor symlink cycles without suppressing valid
+ * aliases in separate branches.
+ */
+export declare function traverseFileTree(options: TraverseFileTreeOptions, visitor: (entry: TraversalEntry) => void | Promise<void>): Promise<void>;
+export {};