@openclaw/fs-safe 0.18.1 → 0.19.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 ## Unreleased
 
+## 0.19.0 - 2026-09-24
+
+### Highlights
+
+- **Strict secret-file durability:** `createSecretFileAtomic()` accepts `durable: "file"` to require every file flush to succeed, including on `EPERM`; parent-directory synchronization remains best effort. ([#644](https://github.com/openclaw/fs-safe/pull/644))
+- **Literal `~` names:** keep FileStore keys, absolute Root reads, discovered walk entries, and ZIP/TAR entries literal instead of treating them as home-directory shorthand. Reads, writes, removal, pruning, extraction, and durable publication select the intended entry. ([#633](https://github.com/openclaw/fs-safe/pull/633))
+- **Native Unix descriptor safety:** reject negative descriptors in low-level root, query, hash, copy, clone, staging, and cleanup calls without Rust panics or working-directory operations. Modern macOS beneath opens report `EBADF` for negative roots instead of `EIO`. ([#640](https://github.com/openclaw/fs-safe/pull/640), [#643](https://github.com/openclaw/fs-safe/pull/643), [#646](https://github.com/openclaw/fs-safe/pull/646))
+
+### Fixes
+
+- **Guest directory permissions:** cross-device moves preserve mode `000`, including nested directories, without changing other modes' umask behavior. Restore top-level permissions through the retained directory descriptor and preserve published entries on failure. Thanks @SebTardif. ([#616](https://github.com/openclaw/fs-safe/pull/616))
+- **ReFS clone cleanup:** remove ordinary partial output when Windows rejects the ignore-readonly deletion flag. Keep readonly attributes intact and include cleanup failures in the original clone error; readonly files or other processes' open handles can still leave output behind. ([#648](https://github.com/openclaw/fs-safe/pull/648))
+
+### Compatibility and documentation
+
+- Secret creation's default and boolean durability options retain their behavior, and `writeSecretFileAtomic()` remains boolean-only. Strict file synchronization preserves existing publication and cleanup semantics: a failure after publication can leave a complete file present. ([#644](https://github.com/openclaw/fs-safe/pull/644))
+- `Root.walk("~")` and `Root.walk("~/dir")` expand home shorthand when iteration starts and return admitted canonical paths relative to the Root. Use `./~/dir` for a literal tilde directory, and prefix returned entry paths with `./` when passing them to another Root method. Relative Root `~/name` inputs still expand home; FileStore keys do not. ([#633](https://github.com/openclaw/fs-safe/pull/633))
+- Guest moves still require OS permission to read mode-000 source directories; they do not widen source permissions. If permission restoration fails after publication, the source and published copy remain for caller reconciliation. ([#616](https://github.com/openclaw/fs-safe/pull/616))
+- Clarify that `Root.append()` and `openWritable()` creation modes remain subject to the process umask and do not chmod existing files. This documents existing behavior. ([#636](https://github.com/openclaw/fs-safe/pull/636))
+
+## 0.18.2 - 2026-09-22
+
+### Fixes
+
+- **Lock errors:** preserve Root stale-removal rejections and `null` or `undefined` retry failures instead of masking them with timeouts or `TypeError`s. ([#624](https://github.com/openclaw/fs-safe/pull/624))
+- **Secret-file reads:** report caught `null` or `undefined` inspection and read failures as structured errors instead of internal `TypeError`s. ([#623](https://github.com/openclaw/fs-safe/pull/623))
+- **Secret-file creation:** preserve `null` or `undefined` thrown by parameter getters instead of masking them with an internal `TypeError`. ([#625](https://github.com/openclaw/fs-safe/pull/625))
+
 ## 0.18.1 - 2026-09-22
 
 ### Fixes

package/dist/advanced.d.ts

@@ -33,4 +33,5 @@ export { resolveHomeRelativePath } from "./home-dir.js";
 export { appendRegularFile, appendRegularFileSync, readRegularFile, readRegularFileSync, resolveRegularFileAppendFlags, statRegularFile, statRegularFileSync, type AppendRegularFileOptions, type RegularFileStatResult, } from "./regular-file.js";
 export { buildRandomTempFilePath, sanitizeTempFileName, type TempFile, tempFile, withTempFile, } from "./temp-target.js";
 export { writeSiblingTempFile, writeViaSiblingTempPath, type WriteSiblingTempFileOptions, type WriteSiblingTempFileResult, } from "./sibling-temp.js";
-export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, type IcaclsResetCommandOptions, type PermissionCommandFailure, type PermissionExec, type WindowsAclEntry, type WindowsAclSummary, } from "./permissions.js";
+export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, type IcaclsResetCommandOptions, type PermissionExec, type WindowsAclEntry, type WindowsAclSummary, } from "./permissions-windows.js";
+export type { PermissionCommandFailure } from "./permission-exec.js";

package/dist/advanced.js

@@ -35,4 +35,4 @@ export { resolveHomeRelativePath } from "./home-dir.js";
 export { appendRegularFile, appendRegularFileSync, readRegularFile, readRegularFileSync, resolveRegularFileAppendFlags, statRegularFile, statRegularFileSync, } from "./regular-file.js";
 export { buildRandomTempFilePath, sanitizeTempFileName, tempFile, withTempFile, } from "./temp-target.js";
 export { writeSiblingTempFile, writeViaSiblingTempPath, } from "./sibling-temp.js";
-export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, } from "./permissions.js";
+export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, } from "./permissions-windows.js";

package/dist/archive-durability.js

@@ -78,7 +78,7 @@ export async function finalizeArchivePublication(params) {
                     const env_1 = { stack: [], error: void 0, hasError: false };
                     try {
                         await assertGuards(file.guards);
-                        const opened = __addDisposableResource(env_1, await params.targetRoot.open(file.relativePath, { hardlinks: "reject", symlinks: "reject" })
+                        const opened = __addDisposableResource(env_1, await params.targetRoot.open(`./${file.relativePath}`, { hardlinks: "reject", symlinks: "reject" })
                             .catch((error) => {
                             if (error instanceof FsSafeError && (error.code === "hardlink" || error.code === "path-alias")) {
                                 throw createArchiveSymlinkTraversalError(file.relativePath);

package/dist/archive-merge.js

@@ -3,7 +3,6 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { ownExtractionDestinationMutation } from "./archive-deadline.js";
 import { assertDirectoryIdentityGuard, assertResolvedInsideDestination, createDirectoryIdentityGuard, createArchiveSymlinkTraversalError, preparePrivateArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
-import {} from "./directory-mode-owner.js";
 import { pinNodeDirectoryForMode } from "./directory-mode-node.js";
 import { assertSyncDirectoryGuard, inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
@@ -251,7 +250,7 @@ async function mergeTree(params, publication, durable = true, entryUmask = 0) {
                                 }
                             };
                         }
-                        await targetRoot.copyIn(relPath, sourcePath, options);
+                        await targetRoot.copyIn(`./${relPath}`, sourcePath, options);
                         check();
                         await assertGuards();
                         await assertResolvedInsideDestination({

package/dist/archive-staging.d.ts

@@ -3,7 +3,6 @@ import { type AsyncDirectoryGuard } from "./directory-guard.js";
 import { type ExtractionDeadline } from "./archive-deadline.js";
 import { ArchiveSecurityError } from "./archive-errors.js";
 export type ArchiveDirectoryGuard = AsyncDirectoryGuard<BigIntStats>;
-export { ArchiveSecurityError, type ArchiveSecurityErrorCode } from "./archive-errors.js";
 export declare function createDirectoryIdentityGuard(dir: string): Promise<ArchiveDirectoryGuard>;
 export declare function assertDirectoryIdentityGuard(guard: ArchiveDirectoryGuard): Promise<void>;
 export declare function prepareArchiveDestinationGuard(destDir: string): Promise<ArchiveDirectoryGuard>;
@@ -29,5 +28,5 @@ export declare function withStagedArchiveDestination<T>(params: {
     stagingDirPrefix?: string;
     run: (stagingDir: string) => Promise<T>;
 }): Promise<T>;
-export { mergeExtractedTreeIntoDestination } from "./archive-merge.js";
 export declare function createArchiveSymlinkTraversalError(originalPath: string): ArchiveSecurityError;
+export {};

package/dist/archive-staging.js

@@ -21,7 +21,6 @@ const ARCHIVE_STAGING_MODE = 0o700;
 function checkExtractionDeadline(deadline) {
     deadline?.check();
 }
-export { ArchiveSecurityError } from "./archive-errors.js";
 function symlinkTraversalError(originalPath) {
     return new ArchiveSecurityError("destination-symlink-traversal", `${ERROR_ARCHIVE_ENTRY_TRAVERSES_SYMLINK}: ${formatErrorDetail(originalPath)}`);
 }
@@ -134,7 +133,9 @@ export async function assertResolvedInsideDestination(params) {
 }
 async function mkdirArchiveOutput(params) {
     try {
-        await params.targetRoot.mkdir(params.relativePath);
+        const relativePath = params.relativePath;
+        // Archive names are literal; retain Root.mkdir's admission without home expansion.
+        await params.targetRoot.mkdir(relativePath === "~" || relativePath.startsWith("~/") ? `./${relativePath}` : relativePath);
     }
     catch (error) {
         if (error instanceof FsSafeError) {
@@ -302,7 +303,6 @@ export async function withStagedArchiveDestination(params) {
         }
     }
 }
-export { mergeExtractedTreeIntoDestination } from "./archive-merge.js";
 export function createArchiveSymlinkTraversalError(originalPath) {
     return symlinkTraversalError(originalPath);
 }

package/dist/archive-zip-preflight.d.ts

@@ -1,5 +1,3 @@
 import { type ArchiveExtractLimits } from "./archive-limits.js";
 import { type ZipArchiveWithFiles } from "./archive-zip-loader.js";
-export { readZipCentralDirectoryEntryCount } from "./archive-zip-count.js";
-export type { ZipArchiveWithFiles } from "./archive-zip-loader.js";
 export declare function loadZipArchiveWithPreflight(buffer: Buffer | Uint8Array, limits?: ArchiveExtractLimits): Promise<ZipArchiveWithFiles>;

package/dist/archive-zip-preflight.js

@@ -1,7 +1,6 @@
 import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, resolveExtractLimits, } from "./archive-limits.js";
 import { admitZipBuffer } from "./archive-zip-admission.js";
 import { loadAdmittedZipArchive } from "./archive-zip-loader.js";
-export { readZipCentralDirectoryEntryCount } from "./archive-zip-count.js";
 export async function loadZipArchiveWithPreflight(buffer, limits) {
     const resolvedLimits = resolveExtractLimits(limits);
     if (buffer.byteLength > resolvedLimits.maxArchiveBytes) {

package/dist/archive.d.ts

@@ -6,10 +6,13 @@ export { resolveArchiveKind, resolvePackedRootDir, type ArchiveKind } from "./ar
 export { readArchiveEntry } from "./archive-read.js";
 export { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, DEFAULT_MAX_ARCHIVE_BYTES_ZIP, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_EXTRACTED_BYTES, DEFAULT_MAX_ENTRY_BYTES, DEFAULT_MAX_META_ENTRY_BYTES, DEFAULT_MAX_ENTRY_PATH_COMPONENTS, type ArchiveExtractLimits, type ArchiveLimitErrorCode, } from "./archive-limits.js";
 export { ArchiveFormatError, type ArchiveFormatErrorCode } from "./archive-errors.js";
-export { ArchiveSecurityError, type ArchiveSecurityErrorCode } from "./archive-staging.js";
-export { createArchiveSymlinkTraversalError, mergeExtractedTreeIntoDestination, prepareArchiveDestinationDir, prepareArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
+export { ArchiveSecurityError, type ArchiveSecurityErrorCode } from "./archive-errors.js";
+export { createArchiveSymlinkTraversalError, prepareArchiveDestinationDir, prepareArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
+export { mergeExtractedTreeIntoDestination } from "./archive-merge.js";
 export { createTarEntryPreflightChecker, type TarEntryInfo } from "./archive-plan.js";
-export { loadZipArchiveWithPreflight, readZipCentralDirectoryEntryCount, type ZipArchiveWithFiles, } from "./archive-zip-preflight.js";
+export { loadZipArchiveWithPreflight } from "./archive-zip-preflight.js";
+export { readZipCentralDirectoryEntryCount } from "./archive-zip-count.js";
+export type { ZipArchiveWithFiles } from "./archive-zip-loader.js";
 export declare function extractArchive(params: ExtractArchiveOptions): Promise<void>;
 export type InspectTarArchiveOptions = Pick<ExtractArchiveOptions, "archivePath" | "timeoutMs" | "limits" | "entryFilter" | "onFiltered">;
 export type InspectedTarEntry = Readonly<Pick<ArchivePlanEntry, "path" | "kind" | "size">>;

package/dist/archive.js

@@ -29,10 +29,12 @@ export { resolveArchiveKind, resolvePackedRootDir } from "./archive-kind.js";
 export { readArchiveEntry } from "./archive-read.js";
 export { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, DEFAULT_MAX_ARCHIVE_BYTES_ZIP, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_EXTRACTED_BYTES, DEFAULT_MAX_ENTRY_BYTES, DEFAULT_MAX_META_ENTRY_BYTES, DEFAULT_MAX_ENTRY_PATH_COMPONENTS, } from "./archive-limits.js";
 export { ArchiveFormatError } from "./archive-errors.js";
-export { ArchiveSecurityError } from "./archive-staging.js";
-export { createArchiveSymlinkTraversalError, mergeExtractedTreeIntoDestination, prepareArchiveDestinationDir, prepareArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
+export { ArchiveSecurityError } from "./archive-errors.js";
+export { createArchiveSymlinkTraversalError, prepareArchiveDestinationDir, prepareArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
+export { mergeExtractedTreeIntoDestination } from "./archive-merge.js";
 export { createTarEntryPreflightChecker } from "./archive-plan.js";
-export { loadZipArchiveWithPreflight, readZipCentralDirectoryEntryCount, } from "./archive-zip-preflight.js";
+export { loadZipArchiveWithPreflight } from "./archive-zip-preflight.js";
+export { readZipCentralDirectoryEntryCount } from "./archive-zip-count.js";
 const SUPPORTS_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in fsConstants;
 const OPEN_WRITE_CREATE_FLAGS = fsConstants.O_WRONLY |
     fsConstants.O_CREAT |

package/dist/directory-guard.d.ts

@@ -36,7 +36,6 @@ export declare function createNearestExistingDirectoryGuard(rootReal: string, ta
 export declare function createNearestExistingDirectoryGuard(rootReal: string, targetPath: string, options: {
     bigint: boolean;
 }): Promise<AnyAsyncDirectoryGuard>;
-export declare function createNearestExistingSyncDirectoryGuard(rootReal: string, targetPath: string): SyncDirectoryGuard;
 export declare function inspectDirectoryIdentity(dir: string, expected?: Pick<BigIntStats, "dev" | "ino">): Promise<BigIntStats>;
 export declare function observeDirectoryIdentitySync(dir: string, options: {
     bigint: true;

package/dist/directory-guard.js

@@ -84,9 +84,6 @@ function assertDirectoryGuard(guard, mode) {
 export async function createNearestExistingDirectoryGuard(rootReal, targetPath, options = { bigint: false }) {
     return nearestExistingDirectoryGuard(rootReal, targetPath, "native", options);
 }
-export function createNearestExistingSyncDirectoryGuard(rootReal, targetPath) {
-    return nearestExistingDirectoryGuard(rootReal, targetPath, "normalized");
-}
 function nearestExistingDirectoryGuard(rootReal, targetPath, mode, options) {
     assertNoWindowsPathAlias(rootReal, "filesystem");
     assertNoWindowsPathAlias(targetPath, "filesystem");

package/dist/directory-mode-node.d.ts

@@ -1,5 +1,23 @@
-import { type BigIntStats } from "node:fs";
-import { type DirectoryModeOwner } from "./directory-mode-owner.js";
+import { type BigIntStats, type Stats } from "node:fs";
+export type DirectoryModeChecks = {
+    check?: () => void;
+    beforeChmod?: () => Promise<void>;
+};
+export type DirectoryModeOwner = {
+    verify(check?: () => void): Promise<void>;
+    apply(mode: number, checks?: DirectoryModeChecks): Promise<void>;
+    close(): Promise<void>;
+};
+export declare function assertOwnedDirectory(expected: Stats | BigIntStats, actual: Stats | BigIntStats): void;
+/** Serializes use and close: even a queued path-based fd operation retains its descriptor. */
+export declare function ownDirectoryMode(params: {
+    inspect: () => Promise<number>;
+    chmod: (mode: number) => Promise<void>;
+    prepareChmod?: () => Promise<void>;
+    verifyChmod?: () => Promise<void>;
+    close: () => Promise<void>;
+    ignoreChmodError?: boolean;
+}): DirectoryModeOwner;
 /** Darwin descriptor inspection avoids requesting directory-content reads. */
 export declare function nodeDarwinDirectoryMetadataFlags(): number;
 export declare function nodeDirectorySearchOnlyFlags(): {

package/dist/directory-mode-node.js

@@ -3,7 +3,83 @@ import fs from "node:fs/promises";
 import { FsSafeError } from "./errors.js";
 import { inspectDirectoryIdentity, inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
-import { assertOwnedDirectory, ownDirectoryMode } from "./directory-mode-owner.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+export function assertOwnedDirectory(expected, actual) {
+    if (actual.isSymbolicLink() || !actual.isDirectory()) {
+        throw new FsSafeError("not-file", "directory mode target must be a real directory");
+    }
+    if (!sameFileIdentityForCleanup(expected, actual)) {
+        throw new FsSafeError("path-mismatch", "directory changed before its mode could be applied");
+    }
+}
+/** Serializes use and close: even a queued path-based fd operation retains its descriptor. */
+export function ownDirectoryMode(params) {
+    let pending = Promise.resolve();
+    let closing;
+    const enqueue = (run) => {
+        if (closing)
+            return Promise.reject(new FsSafeError("path-mismatch", "directory mode owner is closed"));
+        const operation = pending.then(run);
+        pending = operation.catch(() => undefined);
+        return operation;
+    };
+    return {
+        verify: (check) => enqueue(async () => {
+            check?.();
+            await params.inspect();
+            check?.();
+        }),
+        apply: (mode, checks = {}) => enqueue(async () => {
+            // inspect() reports permission bits only; chmod ignores file-type bits,
+            // so tolerate raw stat modes (e.g. S_IFDIR | 0o755) by masking up front.
+            mode &= 0o7777;
+            checks.check?.();
+            const currentMode = await params.inspect();
+            checks.check?.();
+            if (currentMode === mode && !checks.beforeChmod && !checks.check)
+                return;
+            if (currentMode !== mode) {
+                await params.prepareChmod?.();
+                checks.check?.();
+            }
+            await checks.beforeChmod?.();
+            checks.check?.();
+            // Hooks/ancestor checks can yield; recheck the original named association.
+            await params.inspect();
+            checks.check?.();
+            let dispatchDeadlineFailure;
+            if (currentMode !== mode) {
+                checks.check?.();
+                try {
+                    await params.chmod(mode);
+                }
+                catch (error) {
+                    if (!params.ignoreChmodError)
+                        throw error;
+                }
+                // Expiry cannot release the fd while post-dispatch verification is pending.
+                try {
+                    checks.check?.();
+                }
+                catch (error) {
+                    dispatchDeadlineFailure = { error };
+                }
+                await params.verifyChmod?.();
+            }
+            const finalMode = await params.inspect();
+            if (dispatchDeadlineFailure)
+                throw dispatchDeadlineFailure.error;
+            checks.check?.();
+            if (!params.ignoreChmodError && finalMode !== mode) {
+                throw new FsSafeError("path-mismatch", "directory final mode could not be verified");
+            }
+        }),
+        close() {
+            closing ??= pending.then(params.close);
+            return closing;
+        },
+    };
+}
 /** Darwin descriptor inspection avoids requesting directory-content reads. */
 export function nodeDarwinDirectoryMetadataFlags() {
     if (process.platform !== "darwin" || (process.arch !== "x64" && process.arch !== "arm64")) {

package/dist/file-lock-sync-acquisition.js

@@ -66,7 +66,7 @@ export class SyncLockAcquisition {
         }
         catch (waitError) {
             // Exhausted backoff must preserve the filesystem denial diagnosis.
-            if (waitError.code === "file_lock_timeout")
+            if (waitError?.code === "file_lock_timeout")
                 throw error;
             throw waitError;
         }

package/dist/file-lock-sync-root-held.d.ts

@@ -1,5 +1,6 @@
+import { type SyncHeldLock } from "./file-lock-sync-admission.js";
+import type { SidecarLockOptionFields } from "./sidecar-lock-types.js";
 import type { FileLockSyncHandle } from "./file-lock-sync.js";
-import { type SidecarLockSnapshot } from "./sidecar-lock-reclaim.js";
 import { type FileLockSyncRootAuthority, type FileLockSyncRootPath } from "./file-lock-sync-root.js";
 import { type FileLockSyncRootFileReceipt, type FileLockSyncRootSnapshot } from "./file-lock-sync-root-io.js";
 type RootSyncHeldLockReleaseState = "active" | "releasing" | "exit-cleaning" | "released";
@@ -7,22 +8,14 @@ type RootSyncHeldLockHandleDisposition = {
     held: RootSyncHeldLock;
     released: boolean;
 };
-export type RootSyncHeldLock = {
+export type RootSyncHeldLock = SidecarLockOptionFields<SyncHeldLock & {
     deferredExitReleases?: Set<RootSyncHeldLockHandleDisposition>;
-    fd: number | undefined;
-    lockPath: string;
-    normalizedTargetPath: string;
-    parsePayload?: (raw: string) => unknown;
-    refCount: number;
-    reentrantOwner?: string;
     releaseState: RootSyncHeldLockReleaseState;
     revision: number;
     rootAuthority: FileLockSyncRootAuthority;
     rootPath: FileLockSyncRootPath;
     rootReceipt: FileLockSyncRootFileReceipt;
-    snapshot: SidecarLockSnapshot;
-    timer?: NodeJS.Timeout;
-};
+}>;
 export declare function readRootSidecarSnapshotSync(rootPath: FileLockSyncRootPath, parsePayload?: (raw: string) => unknown, onOpenFailure?: (error: unknown) => void, expectedReceipt?: FileLockSyncRootFileReceipt): FileLockSyncRootSnapshot | null;
 export declare function getRootSyncHeldLocks(): Map<string, RootSyncHeldLock>;
 export declare function ensureRootSyncExitCleanupRegistered(): void;

package/dist/file-lock-sync-root-io.d.ts

@@ -14,10 +14,7 @@ export type FileLockSyncRootFileReceipt = Readonly<{
     identity: ExactIdentity;
     parent: DirectoryReceipt;
 }>;
-export type FileLockSyncRootDirectoryReceipt = Readonly<{
-    identity: ExactIdentity;
-    parent: DirectoryReceipt;
-}>;
+export type FileLockSyncRootDirectoryReceipt = FileLockSyncRootFileReceipt;
 export type FileLockSyncRootDiskSnapshot = {
     ownershipToken?: never;
     payload: unknown;

package/dist/file-lock-sync-root-options.d.ts

@@ -1,19 +1,11 @@
 import type { FileLockSyncAcquireOptions } from "./file-lock-sync.js";
-import type { SidecarLockCompromisedInfo, SidecarLockRetryOptions, SidecarLockStaleRecovery } from "./sidecar-lock-types.js";
-type CapturedRootSyncAcquireOptions<TPayload extends Record<string, unknown>> = Readonly<{
-    compromiseCheckIntervalMs?: number;
-    lockPath?: string;
-    onCompromised?: (info: SidecarLockCompromisedInfo) => void;
+import type { SidecarLockRetryOptions } from "./sidecar-lock-types.js";
+type CapturedRootSyncAcquireOptions<TPayload extends Record<string, unknown>> = Readonly<Pick<FileLockSyncAcquireOptions<TPayload>, "compromiseCheckIntervalMs" | "lockPath" | "onCompromised" | "parsePayload" | "payload" | "reentrantOwner" | "staleRecovery" | "timeoutMs"> & {
     optionsReceiver: FileLockSyncAcquireOptions<TPayload>;
-    parsePayload?: (raw: string) => unknown;
-    payload: () => TPayload;
-    reentrantOwner?: string;
     retry: Readonly<SidecarLockRetryOptions>;
     shouldReclaim?: FileLockSyncAcquireOptions<TPayload>["shouldReclaim"];
     shouldRemoveStaleLock?: FileLockSyncAcquireOptions<TPayload>["shouldRemoveStaleLock"];
     staleMs: number;
-    staleRecovery?: SidecarLockStaleRecovery;
-    timeoutMs?: number;
 }>;
 export declare function captureRootSyncAcquireOptions<TPayload extends Record<string, unknown>>(options: FileLockSyncAcquireOptions<TPayload>): CapturedRootSyncAcquireOptions<TPayload>;
 export {};

package/dist/file-lock-sync-root.d.ts

@@ -1,3 +1,4 @@
+import { type DenyMutationPolicy } from "./deny-mutations.js";
 import { type RootContext } from "./root-context.js";
 import type { Root } from "./root-impl.js";
 import type { RootDefaults } from "./root-options.js";
@@ -7,10 +8,7 @@ export type FileLockSyncRootAuthority = Readonly<{
     adapter: object;
     context: RootContext;
     assertBeforeMutation?: () => void;
-    denyMutations?: Readonly<{
-        paths?: readonly string[];
-        prefixes?: readonly string[];
-    }>;
+    denyMutations?: Readonly<DenyMutationPolicy>;
     hardlinks?: RootDefaults["hardlinks"];
     mutationPolicy: RootPathResolutionPolicy;
     readPolicy: RootPathResolutionPolicy;

package/dist/file-store-boundary.d.ts

@@ -1,5 +1,5 @@
 import type { Readable } from "node:stream";
-import { type SyncStoreDirectoryReceipt } from "./file-store-sync-directory.js";
+import { ensureSyncStoreDirectory, type SyncStoreDirectoryReceipt } from "./file-store-sync-directory.js";
 import { type Root } from "./root.js";
 import { prepareSecretFileWrite } from "./secret-file.js";
 export type SyncParentGuard = SyncStoreDirectoryReceipt;
@@ -23,12 +23,8 @@ export declare function ensureParentSync(params: {
     filePath: string;
     mode: number;
 }): SyncParentGuard;
-export declare function ensureStoreDirectorySync(params: {
-    rootDir: string;
-    targetDir: string;
-    mode: number;
-    messagePrefix: "private store" | "store";
-}): SyncParentGuard;
+export declare function ensureStoreDirectorySync(params: Parameters<typeof ensureSyncStoreDirectory>[0]): SyncParentGuard;
+export declare function literalStoreRootPath(relativePath: string): string;
 export declare function assertRelativePath(relativePath: string): string;
 export declare function resolveStorePath(rootDir: string, relativePath: string): string;
 export declare function assertFileStoreMaxBytes(size: number, limit: number | undefined): void;

package/dist/file-store-boundary.js

@@ -7,8 +7,7 @@ import { FsSafeError } from "./errors.js";
 import { assertSyncStoreDirectoryReceipt, ensureSyncStoreDirectory, } from "./file-store-sync-directory.js";
 import { isPathInside, splitSafeRelativePath } from "./path.js";
 import { resolveOpenedFileRealPathForHandle, root } from "./root.js";
-import { ensureTrailingSep } from "./root-context.js";
-import { RootHandle } from "./root-impl.js";
+import { rootFromDirectoryGuard } from "./root-impl.js";
 import { prepareSecretFileWrite } from "./secret-file.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
 import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
@@ -16,7 +15,7 @@ import { readRegularFile } from "./regular-file.js";
 import { errorCauseOptions } from "./root-errors.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 export async function ensureParentInRoot(scopedRoot, relativePath, mode) {
-    const parent = path.posix.dirname(relativePath);
+    const parent = literalStoreRootPath(path.posix.dirname(relativePath));
     if (parent === ".") {
         return;
     }
@@ -32,13 +31,7 @@ export async function openWritableStoreRoot(params) {
 export async function openPrivateStoreLockRoot(params) {
     const { parentGuard } = await prepareSecretFileWrite(params);
     // Bind to the admitted parent, never resolve a replacement into a fresh capability.
-    return new RootHandle({
-        rootDir: parentGuard.dir,
-        rootGuard: { dir: parentGuard.realPath, realPath: parentGuard.realPath, stat: parentGuard.stat },
-        rootReal: parentGuard.realPath,
-        rootWithSep: ensureTrailingSep(parentGuard.realPath),
-        rootIdentity: { dev: parentGuard.stat.dev, ino: parentGuard.stat.ino },
-    }, { hardlinks: "reject" });
+    return rootFromDirectoryGuard(parentGuard, { hardlinks: "reject" });
 }
 async function chmodDirectoryInRootBestEffort(scopedRoot, relativePath, mode) {
     const dirPath = await scopedRoot.resolve(relativePath);
@@ -120,6 +113,10 @@ export function ensureStoreDirectorySync(params) {
     assertSyncStoreDirectoryReceipt(guard);
     return guard;
 }
+// Store keys and directory-entry names are literal, unlike Root's home syntax.
+export function literalStoreRootPath(relativePath) {
+    return relativePath === "~" || relativePath.startsWith("~/") ? `./${relativePath}` : relativePath;
+}
 export function assertRelativePath(relativePath) {
     const raw = relativePath.trim();
     if (!raw || raw !== relativePath) {

package/dist/file-store-prune.js

@@ -2,6 +2,7 @@ import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
+import { literalStoreRootPath } from "./file-store-boundary.js";
 import { isPathInside } from "./path.js";
 import { realpathSync } from "./realpath.js";
 import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
@@ -74,13 +75,13 @@ export async function pruneExpiredStoreEntries(params) {
                     await assertRootGuard();
                     // Keep empty-dir pruning on the same root-bounded remove path as files;
                     // the Root fallback handles empty directories without recursive delete.
-                    await scopedRoot.remove(relativePath, REMOVE_EMPTY_DIRECTORY_OPTIONS).catch(() => undefined);
+                    await scopedRoot.remove(literalStoreRootPath(relativePath), REMOVE_EMPTY_DIRECTORY_OPTIONS).catch(() => undefined);
                 }
                 continue;
             }
             if (stat.isFile() && now - stat.mtimeMs > params.options.ttlMs) {
                 await assertRootGuard();
-                await scopedRoot.remove(relativePath, {
+                await scopedRoot.remove(literalStoreRootPath(relativePath), {
                     assertBeforeMutation: () => {
                         // Removal preparation can outlive the expiry observation above.
                         const current = fsSync.lstatSync(fullPath);