Public API inventory
This page closes the gap between the narrative guides and the complete package surface. The generated declarations define the exact signatures; the lists below name the lower-frequency exports that are easy to miss when reading only the focused guides. test/public-api.json guards the same inventory during pack checks.
#Main entry and root
The main entry and @openclaw/fs-safe/root expose the root capability types, including ContainmentGuarantee, RootOpenOptions, RootCreateOptions, RootCreateJsonOptions, and WritableOpenMode. The root-bounded iterator uses RootWalkOptions, RootWalkEntry, RootWalkDataEntry, RootWalkEntryKind, RootWalkDataEntryKind, RootWalkSymlinkPolicy, RootWalkLimitBehavior, RootWalkDirectoryErrorBehavior, RootWalkEntryFilter, and RootWalkEntryFilterResult.
The root subpath also exports openLocalFileSafely, readLocalFileSafely, and resolveOpenedFileRealPathForHandle for trusted absolute-file composition. They do not create a root boundary around arbitrary caller input; prefer root() for untrusted paths.
The error helpers are categorizeFsSafeError and FsSafeErrorDetails. The deprecated native-configuration bridge retains the FsSafePythonConfig type.
#path and advanced
safePathSegmentHashedV2 encodes every trimmed install ID with domain-separated SHA-256 into a fixed lowercase segment. The legacy safePathSegmentHashed keeps its existing output but can alias distinct IDs. See install paths for the exact encoding and migration contract.
The lexical path surface additionally exports isNodeError, isPathRelativeEscape, normalizeWindowsPathForComparison, resolveSafeRelativePath, splitSafeRelativePath, and matchUnsafeDeviceReadPath. The device matcher is described by UnsafeDeviceReadPathMatch, UnsafeDeviceReadPathOptions, and UnsafeDeviceReadPathReason.
The advanced root-file primitive exports OpenRootFileParams, OpenRootFileSyncParams, RootFileOpenResult, and RootFileOpenFailureReason. These are composition types for callers building their own pinned-open flow, not substitutes for the higher-level Root verbs.
copyFileHandle and copyFileDescriptorSync share CopyFileHandleOptions to transfer bytes between already-open regular files without taking over their cursors, lifetime, or publication. See borrowed-handle transfers.
readDirectoryIdentity, assertDirectoryIdentitySync, and DirectoryIdentity provide exact directory observations without owning a descriptor or a mutation. The assertion accepts an observed path and optional expected canonical path; see directory identity.
overwriteFileHandle and OverwriteFileHandleOptions provide in-place byte replacement through a borrowed regular-file handle. Its once-only beforeWrite callback admits the complete write and any required best-effort rollback after prefix preparation. See in-place writes.
probePathCaseInsensitiveSync and ProbePathCaseOptions are advanced exports for local ASCII-case observations. An unavailable answer remains undefined; the caller selects any fallback. See path case probing.
resolvePathPrefixSync and ResolvedPathPrefix separate a canonical existing path prefix from its raw unresolved suffix after physical symlink traversal. See resolving path prefixes.
probePathSuffixAliasesSync and ProbePathSuffixAliasesOptions compare selected missing relative suffixes beneath an existing directory using bounded temporary directory probes. The caller owns Unicode-pair policy, caching, and the fallback for undefined. See path suffix alias probing.
#Guest source
@openclaw/fs-safe/guest exports GUEST_FILESYSTEM_PYTHON, GUEST_FILESYSTEM_CREATE_EXISTS_EXIT_CODE, GUEST_FILESYSTEM_READ_NOT_FOUND_EXIT_CODE, and GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON. These are source and protocol constants; the caller launches the Python guest and owns authorization and transport lifetime. See the guest protocol.
#json and store
Standalone structured reads use ReadJsonOptions, ReadRootJsonSyncOptions, ReadRootStructuredFileSyncOptions, and RootStructuredFileReadResult.
The store surface additionally exports FileStoreReadOptions and JsonFileStoreOptions. Durable-queue inspection and recovery use jsonDurableQueueEntryExists, loadJsonDurableQueueEntry, readJsonDurableQueueEntry, and the JsonDurableQueueLoadOptions and JsonDurableQueueReadResult types. unlinkBestEffort is the explicitly best-effort cleanup helper used by those queue flows.
#Permissions and secure files
Permission inspection exposes PermissionCheckOptions and SafeStatResult. Private-directory creation uses CreatePrivateDirectoryOptions. Raw Windows descriptor facts use OwnerAndDaclResult, WindowsAccessControlEntry, and WindowsAceFlags.
Secure reads split their option and result shapes into SecureFileTrustOptions, SecureFilePermissionOptions, SecureFileInjectOptions, SecureFileIoOptions, and SecureFileReadResult.
#Locks, walking, and temp workspaces
The file-lock diagnostics surface includes FileLockHeldEntry, FileLockStaleRecovery, and SidecarLockCompromisedInfo. drainFileLockManagerForTest and resetFileLockManagerForTest are test-only manager controls; production code should not use them as lock recovery.
Standalone walkers use the WalkEntryKind and WalkSymlinkPolicy unions. Private workspaces expose TempPathIdentityReceipt, TempWorkspaceCleanupResult, and TempWorkspaceCleanupSafety so callers can distinguish outcomes and select compatible or required bounded-tree cleanup. Strict workspace creation requires native no-replace quarantine plus retained parent/workspace descriptors; see the creation and cleanup contract.
#Atomic replacement and durability
Atomic helper option and receipt types include MovePathWithCopyFallbackOptions, ReplaceDirectoryAtomicOptions, ReplaceFileAtomicSyncOptions, ReplaceFileAtomicResult, ReplaceFileAtomicRestoreCleanup, ReplaceFileCopyFallbackRestorePolicy, and ReplaceFileDestinationHardlinkPolicy.
The durability surface also exports the synchronous strict syncDirectorySync, plus DirectoryReceipt, DurableDirectoryReceipt, EnsureDurableDirectoryOptions, PublishFileExclusiveResult, PublishFileExclusiveStrategy, PublishFileExclusiveCleanup, PublishFileExclusiveFailurePhase, PublishFileExclusiveDirectorySyncFailure, Sha256FileInput, Sha256FileSyncInput, Sha256FileOptions, and Sha256FileResult. sha256FileSync() provides synchronous pathname or borrowed-descriptor hashing with the same byte-budget and digest-result contracts as sha256File().
#Archives
Archive option and policy types are ExtractArchiveOptions, ArchiveEntryFilter, ArchiveEntryModePolicy, and ArchiveFilteredEntryPolicy. Typed error-code unions are ArchiveFormatErrorCode, ArchiveLimitErrorCode, and ArchiveSecurityErrorCode. TAR and ZIP preflight composition uses TarEntryInfo and ZipArchiveWithFiles.
createArchiveSymlinkTraversalError constructs the typed traversal failure used by extractors. resolvePackedRootDir finds the single packed root when an archive layout permits it; neither helper weakens entry validation.
#Keeping this list honest
Every runtime and type name in test/public-api.json must appear somewhere in README.md or docs/. Documentation examples are also checked so a named import cannot silently move to another package subpath.