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 handle resolver verifies exact descriptor and pathname identities, with one bounded retry for unknown Windows observations. It borrows the handle without reading, reopening, closing it, or changing its cursor.
The error helpers are categorizeFsSafeError, isNoReplaceUnsupported, and FsSafeErrorDetails. The no-replace classifier recognizes the documented capability refusal without matching internal cause codes.
#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.
isPathRelativeEscape() rejects absolute paths and relative paths that step above their starting directory at any point. Contained paths such as dir/../file remain relative. It accepts both separators on Windows; on POSIX, a backslash remains a literal filename character.
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.
retainSymlinkInDirectory holds an explicitly identified POSIX symlink through exact-slot no-replace publication; its receipts use the StagedSymlink* and PublishedSymlinkReceipt types. See staged symlinks.
retainFileInDirectory retains an existing Windows NTFS file through a native handle for explicit identity-bound retirement. It is described by RetainFileInDirectoryOptions, RetainedFile, RetainedFileAdmission, RetainedFileExpected, RetainedFileIssue, RetainedFileReceipt, and RetainedFileResult. See retained Windows files.
#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. readOwnerAndDaclBatch() returns those same facts in input order through an isolated asynchronous batch with a whole-process timeout.
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, ReplaceFileDestinationHardlinkPolicy, and ReplaceFileAtomicDestinationState. The assertBeforeMutation option rechecks caller authority before new effects, and onDestinationState reports retained destination identities as ReplaceFileAtomicDestinationState values; see atomic writes.
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(). DirectoryReceipt<T> accepts Stats or BigIntStats input metadata; its default type argument and returned durability receipts remain numeric Stats.
#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.
#watch
@openclaw/fs-safe/watch exports watch() plus WatchScope, WatchEntry, WatchChange, WatchInvalidation, WatchFailure, WatchHealth, WatchOptions, and WatchSubscription. Invalidations are advisory; guarded scans stay authoritative. See filesystem observation for modes, budgets, persistent, and lifecycle.
#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.
#Exact receipt types
ExactFileIdentity is the immutable bigint dev/ino pair returned alongside legacy numeric metadata. ExactIdentityReceipt describes an object with that exactIdentity companion. FileIdentityInput accepts either a traditional FileIdentityStat pair or an explicit exact-companion receipt. ExactDirectoryReceipt guarantees the exact companion on a returned directory receipt while the caller-constructible DirectoryReceipt remains compatible. See the identity round-trip guidance.