Crate cageforge_path 

Shared native path comparison primitives for Cageforge.

These helpers are lexical only. They do not inspect the filesystem or resolve symlinks; a native backend must perform those operations when its enforcement model requires them.

Reading this crate

Use paths_equal and is_within for direct decisions, and NativePathKey when the same identity must be stored in a map or set. contains_parent_traversal validates a lexical input boundary, while normalize_lexical_path exposes supported Windows aliases. The policy, command, and configuration crates build their higher-level rules on these primitives.

Independent project: Cageforge is not affiliated with, sponsored by, or endorsed by OpenAI.

This crate is a supporting component of the cageforge crate, a cross-platform Rust sandbox for AI agents and untrusted code.

cageforge-path

Read the shared configuration guide for TOML profiles, symbolic paths, local IPC, and first-launch resource rules.

cageforge-path centralizes the small set of path comparisons that must agree across Cageforge crates. It treats path components case-sensitively on POSIX systems and case-insensitively on Windows. Windows drive, UNC, verbatim, and supported device aliases share one lexical identity; malformed native strings remain distinct instead of passing through lossy Unicode conversion.

Portable configuration uses PathDialect and PlatformPathKey when it validates or merges a path for a target platform other than the compiling host. This keeps a Windows overlay’s drive, UNC, separator, and case rules intact even when the TOML is read on Linux or macOS.

The crate does not access the filesystem, resolve symlinks, or canonicalize paths. Native backends remain responsible for those operations.

When to use it

Use this crate when your own code stores, compares, or validates paths and must agree with Cageforge’s policy and configuration layers. It is especially useful for workspace-root maps, protected metadata paths, and component-aware containment checks.

Use a native executor for filesystem enforcement. This crate answers lexical questions such as “is this path below that path?”; the executor adds symlink, junction/reparse-point, mount, and TOCTOU-safe checks before opening a file.

Workspace role

cageforge-path is the shared lexical path-semantics layer.

Crate	Role in the relationship
cageforge-policy	Uses component-aware equality, containment, and path-pattern comparison.
cageforge-command	Validates command working-directory traversal.
cageforge-config	Validates configured workspace-root declarations.
cageforge-policy-compose	Deduplicates and compares effective workspace roots.
cageforge-upstream-review	Validates repository-relative review paths.
cageforge	Re-exports the path model through the application-facing crate.

The helpers define lexical relationships only. A backend still owns filesystem I/O, symlink resolution, canonicalization, and platform capability checks.

Case semantics

The following table is the single path-identity rule shared by the workspace. It is not configurable through TOML or the Rust API.

Value or operation	POSIX (Linux/macOS)	Windows
Absolute and workspace paths	Case-sensitive	Case-insensitive
workspace_roots	Case-sensitive	Case-insensitive
Protected paths such as .git	Case-sensitive	Case-insensitive
Unix socket paths	Case-sensitive	Case-insensitive path comparison
Filesystem glob components	Case-sensitive	Case-insensitive
Environment variable names and filters	Case-insensitive by policy	Case-insensitive by policy
Domain names and domain globs	Case-insensitive by protocol	Case-insensitive by protocol
Profile names and ordinary strings	Exact comparison	Exact comparison

Only the filesystem-related rows use this crate’s native path helpers. The environment and domain rows intentionally have their own portable semantics.

API

• is_within(path, root) checks component-aware containment and does not treat /work-other as a child of /work.
• contains_component_path(path, needle) finds a complete relative component path such as .git without matching a partial component such as .github.
• paths_equal(left, right) compares complete native path components.
• NativePathKey supplies the same equality, hashing, and ordering identity for maps and sets.
• PathDialect selects POSIX or Windows lexical syntax independently of the compiling host.
• is_absolute_text and contains_parent_traversal_text validate path text for that explicit dialect.
• PlatformPathKey supplies target-platform equality, hashing, and ordering for portable configuration merges.
• resolve_lexical_path(base, declaration) resolves a relative or absolute declaration after applying the shared empty, NUL, and parent-traversal checks.
• normalize_lexical_path(path) exposes supported native alias normalization without filesystem access.
• strings_equal(left, right) and case_fold(value) expose the same native comparison rule for path-derived glob matching.
• contains_parent_traversal(path) detects lexical .. components.

The helpers are used by policy evaluation, command working-directory validation, policy composition, and the upstream-review tool so those layers cannot silently develop different Windows behavior.

Smallest useful example

use cageforge_path::{is_within, paths_equal, NativePathKey};
use std::path::Path;

let workspace = Path::new("/work/project");
assert!(is_within(Path::new("/work/project/src/lib.rs"), workspace));
assert!(!is_within(Path::new("/work/project-old"), workspace));
assert!(paths_equal(workspace, Path::new("/work/project")));

let _map_key = NativePathKey::new(workspace);

The policy, command, config, and composition crates already use this layer internally. Depend on it directly when an integration layer builds native path maps or compares paths before handing values to those crates.

API reference: cageforge-path on docs.rs.

Repository: github.com/m62624/cageforge.

Structs

NativePathKey

A hashable and orderable lexical path identity using native case rules.

PlatformPathKey

A hashable lexical path identity for an explicitly selected dialect.

Enums

PathDialect

Lexical path syntax used by a configuration value.

PathResolutionError

The lexical validation failures returned by resolve_lexical_path.

Functions

case_fold

Folds a string using the target platform’s path comparison case rules.

components_equal

Compares two path components with the target platform’s path case rules.

contains_component_path

Returns whether path contains needle as a contiguous component path.

contains_parent_traversal

Returns whether a path contains a lexical parent traversal component.

contains_parent_traversal_text

Returns whether value contains a literal parent traversal component.

is_absolute_text

Returns whether value is absolute according to dialect.

is_within

Returns whether path is the same as or below root by path component.

normalize_lexical_path

Normalizes lexical aliases that the target platform treats as the same path.

paths_equal

Compares two complete paths using the target platform’s path case rules.

resolve_lexical_path

Resolves a relative-or-absolute declaration against base lexically.

strings_equal

Compares path-component strings with the target platform’s path case rules.