@openclaw/fs-safe 0.9.0 → 0.11.0

package/dist/filename.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { WINDOWS_RESERVED_DEVICE_NAMES } from "./device-path.js";
-const WINDOWS_INVALID_FILE_NAME_CHARACTERS = new Set('<>:"/\\|?*');
+import { maxNormalizedUtf8Bytes } from "./unicode-path.js";
+const INVALID_FILE_NAME_CHARACTERS = /[\u0000-\u001f\u007f-\u009f<>:"/\\|?*]/g;
 function trimWindowsIgnoredSuffix(value) {
     let end = value.length;
     while (end > 0) {
@@ -24,7 +25,7 @@ function suffixWindowsReservedDeviceName(fileName) {
 }
 const PORTABLE_FILE_NAME_BYTES = 255;
 function normalizedFileNameBytes(value) {
-    return Math.max(Buffer.byteLength(value.normalize("NFC"), "utf8"), Buffer.byteLength(value.normalize("NFD"), "utf8"));
+    return maxNormalizedUtf8Bytes(value, true);
 }
 /** Keeps short names exact and trims only the filename tail of a composite temp name. */
 export function fitFileNameToPortableComponent(params) {
@@ -65,17 +66,7 @@ export function sanitizeUntrustedFileName(fileName, fallbackName) {
     }
     let base = path.posix.basename(trimmed);
     base = path.win32.basename(base);
-    let cleaned = "";
-    for (let i = 0; i < base.length; i++) {
-        const code = base.charCodeAt(i);
-        if (code < 0x20 ||
-            (code >= 0x7f && code <= 0x9f) ||
-            WINDOWS_INVALID_FILE_NAME_CHARACTERS.has(base[i])) {
-            continue;
-        }
-        cleaned += base[i];
-    }
-    base = cleaned.trim();
+    base = base.replace(INVALID_FILE_NAME_CHARACTERS, "").trim();
     if (!base || base === "." || base === "..") {
         return fallbackName;
     }

package/dist/guarded-mkdir.d.ts

@@ -8,6 +8,7 @@ export declare function mkdirPathComponentsWithGuards(params: {
     rootReal: string;
     targetPath: string;
     beforeComponent?: (componentPath: string) => Promise<void> | void;
+    assertBeforeMutation?: () => void;
     mode?: number;
     rejectSymlinks?: boolean;
 }): Promise<string>;

package/dist/guarded-mkdir.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guarded-mkdir.d.ts","sourceRoot":"","sources":["../src/guarded-mkdir.ts"],"names":[],"mappings":"AA0BA;;;;;GAKG;AACH,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,GAAG,OAAO,CAAC,MAAM,CAAC,CAuDlB"}
+{"version":3,"file":"guarded-mkdir.d.ts","sourceRoot":"","sources":["../src/guarded-mkdir.ts"],"names":[],"mappings":"AA2BA;;;;;GAKG;AACH,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAClE,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,GAAG,OAAO,CAAC,MAAM,CAAC,CAwDlB"}

package/dist/guarded-mkdir.js

@@ -5,13 +5,14 @@ import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./director
 import { FsSafeError } from "./errors.js";
 import { isNotFoundPathError, isPathRelativeEscape } from "./path.js";
 import { directoryComponentNotDirectoryError } from "./root-errors.js";
+import { realpathSync } from "./realpath.js";
 function isSameOrChildPath(candidate, parent) {
     const parentPrefix = parent.endsWith(path.sep) ? parent : `${parent}${path.sep}`;
     return candidate === parent || candidate.startsWith(parentPrefix);
 }
 async function realpathOrThrowNotFile(target) {
     try {
-        return path.resolve(fsSync.realpathSync.native(target));
+        return path.resolve(realpathSync.native(target));
     }
     catch (error) {
         if (isNotFoundPathError(error)) {
@@ -30,7 +31,7 @@ async function realpathOrThrowNotFile(target) {
  */
 export async function mkdirPathComponentsWithGuards(params) {
     const root = path.resolve(params.rootReal);
-    const rootCanonical = path.resolve(fsSync.realpathSync.native(root));
+    const rootCanonical = path.resolve(realpathSync.native(root));
     const target = path.resolve(params.targetPath);
     const relative = path.relative(root, target);
     if (isPathRelativeEscape(relative)) {
@@ -42,6 +43,7 @@ export async function mkdirPathComponentsWithGuards(params) {
         const parentGuard = await createAsyncDirectoryGuard(current);
         await assertAsyncDirectoryGuard(parentGuard);
         await params.beforeComponent?.(next);
+        params.assertBeforeMutation?.();
         try {
             await fs.mkdir(next, { mode: params.mode });
         }

package/dist/guarded-mutation.d.ts

@@ -24,12 +24,14 @@ export declare function guardedRenameSync(params: {
 }): void;
 export declare function guardedRm(params: {
     target: string;
+    assertBeforeMutation?: () => void;
     recursive?: boolean;
     force?: boolean;
     verifyAfter?: boolean;
 }): Promise<void>;
 export declare function guardedRmSync(params: {
     target: string;
+    assertBeforeMutation?: () => void;
     recursive?: boolean;
     force?: boolean;
     verifyAfter?: boolean;

package/dist/guarded-mutation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guarded-mutation.d.ts","sourceRoot":"","sources":["../src/guarded-mutation.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAGnD,OAAO,EAOL,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAE9B,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,MAAM,EAAE,SAAS,sBAAsB,EAAE,EACzC,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACxB,OAAO,GAAE;IACP,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACrE,GACL,OAAO,CAAC,CAAC,CAAC,CAyBZ;AAED,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,MAAM,EAAE,SAAS,kBAAkB,EAAE,EACrC,MAAM,EAAE,MAAM,CAAC,EACf,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC,CAAC,CAWH;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE;IAC1C,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;IAChC,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,CAAC;IACzE,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBhB;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,IAAI,CAUP;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYhB;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,IAAI,CAWP"}
+{"version":3,"file":"guarded-mutation.d.ts","sourceRoot":"","sources":["../src/guarded-mutation.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAGnD,OAAO,EAOL,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAE9B,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,MAAM,EAAE,SAAS,sBAAsB,EAAE,EACzC,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACxB,OAAO,GAAE;IACP,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACrE,GACL,OAAO,CAAC,CAAC,CAAC,CAyBZ;AAED,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,MAAM,EAAE,SAAS,kBAAkB,EAAE,EACrC,MAAM,EAAE,MAAM,CAAC,EACf,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC,CAAC,CAWH;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE;IAC1C,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;IAChC,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,CAAC;IACzE,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBhB;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,IAAI,CAUP;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;IAClC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAahB;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;IAClC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,IAAI,CAaP"}

package/dist/guarded-mutation.js

@@ -67,6 +67,7 @@ export function guardedRenameSync(params) {
 export async function guardedRm(params) {
     const guard = await createAsyncDirectoryGuard(path.dirname(params.target));
     await withAsyncDirectoryGuards([guard], async () => {
+        params.assertBeforeMutation?.();
         await fs.rm(params.target, {
             ...(params.recursive !== undefined ? { recursive: params.recursive } : {}),
             ...(params.force !== undefined ? { force: params.force } : {}),
@@ -75,8 +76,11 @@ export async function guardedRm(params) {
 }
 export function guardedRmSync(params) {
     const guard = createSyncDirectoryGuard(path.dirname(params.target));
-    withSyncDirectoryGuards([guard], () => fsSync.rmSync(params.target, {
-        ...(params.recursive !== undefined ? { recursive: params.recursive } : {}),
-        ...(params.force !== undefined ? { force: params.force } : {}),
-    }), { verifyAfter: params.verifyAfter });
+    withSyncDirectoryGuards([guard], () => {
+        params.assertBeforeMutation?.();
+        fsSync.rmSync(params.target, {
+            ...(params.recursive !== undefined ? { recursive: params.recursive } : {}),
+            ...(params.force !== undefined ? { force: params.force } : {}),
+        });
+    }, { verifyAfter: params.verifyAfter });
 }

package/dist/guest-dispatch-python.d.ts

@@ -0,0 +1,2 @@
+export declare const GUEST_FILESYSTEM_DISPATCH_PYTHON: string;
+//# sourceMappingURL=guest-dispatch-python.d.ts.map

package/dist/guest-dispatch-python.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guest-dispatch-python.d.ts","sourceRoot":"","sources":["../src/guest-dispatch-python.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gCAAgC,QAoHjC,CAAC"}

package/dist/guest-dispatch-python.js

@@ -0,0 +1,117 @@
+export const GUEST_FILESYSTEM_DISPATCH_PYTHON = [
+    "if operation == 'copy':",
+    "    src_root_fd = open_dir(sys.argv[2])",
+    "    dst_root_fd = open_dir(sys.argv[5])",
+    "    src_parent_fd = None",
+    "    dst_parent_fd = None",
+    "    try:",
+    "        src_parent_fd = walk_dir(src_root_fd, sys.argv[3], False)",
+    "        dst_parent_fd = walk_dir(dst_root_fd, sys.argv[6], sys.argv[8] == '1')",
+    "        copy_file_atomic(src_parent_fd, sys.argv[4], dst_parent_fd, sys.argv[7])",
+    "    finally:",
+    "        if src_parent_fd is not None:",
+    "            os.close(src_parent_fd)",
+    "        if dst_parent_fd is not None:",
+    "            os.close(dst_parent_fd)",
+    "        os.close(src_root_fd)",
+    "        os.close(dst_root_fd)",
+    "elif operation == 'write':",
+    "    root_fd = open_dir(sys.argv[2])",
+    "    parent_fd = None",
+    "    try:",
+    "        parent_fd = walk_dir(root_fd, sys.argv[3], sys.argv[5] == '1')",
+    "        write_atomic(parent_fd, sys.argv[4], sys.stdin.buffer)",
+    "    finally:",
+    "        if parent_fd is not None:",
+    "            os.close(parent_fd)",
+    "        os.close(root_fd)",
+    "elif operation == 'create':",
+    "    root_fd = open_dir(sys.argv[2])",
+    "    parent_fd = None",
+    "    try:",
+    "        parent_fd = walk_dir(root_fd, sys.argv[3], sys.argv[5] == '1')",
+    "        try:",
+    "            create_exclusive(parent_fd, sys.argv[4], sys.stdin.buffer)",
+    "        except FileExistsError:",
+    "            sys.exit(SANDBOX_CREATE_EXISTS_EXIT_CODE)",
+    "    finally:",
+    "        if parent_fd is not None:",
+    "            os.close(parent_fd)",
+    "        os.close(root_fd)",
+    "elif operation == 'read':",
+    "    root_fd = open_dir(sys.argv[2])",
+    "    parent_fd = None",
+    "    try:",
+    "        parent_fd = walk_dir(root_fd, sys.argv[3], False)",
+    "        if len(sys.argv) > 5:",
+    "            read_file_bounded(parent_fd, sys.argv[4], int(sys.argv[5]))",
+    "        else:",
+    "            read_file(parent_fd, sys.argv[4])",
+    "    except FileNotFoundError:",
+    "        sys.exit(SANDBOX_READ_NOT_FOUND_EXIT_CODE)",
+    "    finally:",
+    "        if parent_fd is not None:",
+    "            os.close(parent_fd)",
+    "        os.close(root_fd)",
+    "elif operation == 'readdir':",
+    "    root_fd = open_dir(sys.argv[2])",
+    "    target_fd = None",
+    "    try:",
+    "        target_fd = walk_dir(root_fd, sys.argv[3], False)",
+    "        with os.scandir(target_fd) as entries:",
+    "            print(json.dumps([{'name': entry.name, 'isDirectory': entry.is_dir(follow_symlinks=False)} for entry in entries]))",
+    "    finally:",
+    "        if target_fd is not None:",
+    "            os.close(target_fd)",
+    "        os.close(root_fd)",
+    "elif operation == 'mkdirp':",
+    "    root_fd = open_dir(sys.argv[2])",
+    "    target_fd = None",
+    "    try:",
+    "        target_fd = walk_dir(root_fd, sys.argv[3], True)",
+    "        os.fsync(target_fd)",
+    "    finally:",
+    "        if target_fd is not None:",
+    "            os.close(target_fd)",
+    "        os.close(root_fd)",
+    "elif operation == 'remove':",
+    "    root_fd = open_dir(sys.argv[2])",
+    "    parent_fd = None",
+    "    try:",
+    "        parent_fd = walk_dir(root_fd, sys.argv[3], False)",
+    "        try:",
+    "            if sys.argv[5] == '1':",
+    "                remove_tree(parent_fd, sys.argv[4])",
+    "            else:",
+    "                entry_stat = os.lstat(sys.argv[4], dir_fd=parent_fd)",
+    "                if stat.S_ISDIR(entry_stat.st_mode) and not stat.S_ISLNK(entry_stat.st_mode):",
+    "                    os.rmdir(sys.argv[4], dir_fd=parent_fd)",
+    "                else:",
+    "                    os.unlink(sys.argv[4], dir_fd=parent_fd)",
+    "            os.fsync(parent_fd)",
+    "        except FileNotFoundError:",
+    "            if sys.argv[6] != '1':",
+    "                raise",
+    "    finally:",
+    "        if parent_fd is not None:",
+    "            os.close(parent_fd)",
+    "        os.close(root_fd)",
+    "elif operation == 'rename':",
+    "    src_root_fd = open_dir(sys.argv[2])",
+    "    dst_root_fd = open_dir(sys.argv[5])",
+    "    src_parent_fd = None",
+    "    dst_parent_fd = None",
+    "    try:",
+    "        src_parent_fd = walk_dir(src_root_fd, sys.argv[3], False)",
+    "        dst_parent_fd = walk_dir(dst_root_fd, sys.argv[6], sys.argv[8] == '1')",
+    "        move_entry(src_parent_fd, sys.argv[4], dst_parent_fd, sys.argv[7])",
+    "    finally:",
+    "        if src_parent_fd is not None:",
+    "            os.close(src_parent_fd)",
+    "        if dst_parent_fd is not None:",
+    "            os.close(dst_parent_fd)",
+    "        os.close(src_root_fd)",
+    "        os.close(dst_root_fd)",
+    "else:",
+    "    raise RuntimeError('unknown sandbox mutation operation: ' + operation)",
+].join("\n");

package/dist/guest-native-python.d.ts

@@ -0,0 +1,4 @@
+export declare const GUEST_FILESYSTEM_CREATE_STAGING_PYTHON: string;
+export declare const GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON: string;
+export declare const GUEST_FILESYSTEM_CREATE_EXCLUSIVE_PYTHON: string;
+//# sourceMappingURL=guest-native-python.d.ts.map

package/dist/guest-native-python.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guest-native-python.d.ts","sourceRoot":"","sources":["../src/guest-native-python.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,sCAAsC,QA+BvC,CAAC;AAEb,eAAO,MAAM,yCAAyC,QAgD1C,CAAC;AAEb,eAAO,MAAM,wCAAwC,QAqDzC,CAAC"}

package/dist/guest-native-python.js

@@ -0,0 +1,135 @@
+export const GUEST_FILESYSTEM_CREATE_STAGING_PYTHON = [
+    "def create_staging_dir(parent_fd):",
+    "    # This helper guarantees descriptor-relative confinement and no-replace",
+    "    # publication, not content integrity against same-UID peers; they can",
+    "    # also rewrite the destination immediately after publication.",
+    "    prefix = '.openclaw-create-'",
+    "    for _ in range(128):",
+    "        candidate = prefix + secrets.token_hex(6)",
+    "        try:",
+    "            os.mkdir(candidate, 0o700, dir_fd=parent_fd)",
+    "        except FileExistsError:",
+    "            continue",
+    "        created_identity = entry_identity(os.lstat(candidate, dir_fd=parent_fd))",
+    "        staging_fd = None",
+    "        try:",
+    "            staging_fd = open_dir(candidate, dir_fd=parent_fd)",
+    "            if not same_identity(created_identity, os.fstat(staging_fd)):",
+    "                raise OSError(errno.ESTALE, 'create staging directory changed', candidate)",
+    "            return candidate, staging_fd",
+    "        except Exception:",
+    "            if staging_fd is not None:",
+    "                os.close(staging_fd)",
+    "            try:",
+    "                current = os.lstat(candidate, dir_fd=parent_fd)",
+    "                if same_identity(created_identity, current):",
+    "                    os.rmdir(candidate, dir_fd=parent_fd)",
+    "                    os.fsync(parent_fd)",
+    "            except FileNotFoundError:",
+    "                pass",
+    "            raise",
+    "    raise RuntimeError('failed to allocate sandbox create staging directory')",
+].join("\n");
+export const GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON = [
+    "def rename_no_replace(src_parent_fd, src_basename, dst_parent_fd, dst_basename):",
+    "    libc = ctypes.CDLL(None, use_errno=True)",
+    "    is_linux = sys.platform.startswith('linux')",
+    "    if is_linux:",
+    "        rename_fn = getattr(libc, 'renameat2', None)",
+    "        if rename_fn is None:",
+    "            os.link(",
+    "                src_basename,",
+    "                dst_basename,",
+    "                src_dir_fd=src_parent_fd,",
+    "                dst_dir_fd=dst_parent_fd,",
+    "                follow_symlinks=False,",
+    "            )",
+    "            return",
+    "        flags = 1  # RENAME_NOREPLACE",
+    "    elif sys.platform == 'darwin':",
+    "        rename_fn = getattr(libc, 'renameatx_np', None)",
+    "        flags = 0x00000004  # RENAME_EXCL",
+    "    else:",
+    "        rename_fn = None",
+    "        flags = 0",
+    "    if rename_fn is None:",
+    "        raise OSError(errno.ENOSYS, 'atomic no-replace rename is unavailable')",
+    "    rename_fn.argtypes = [ctypes.c_int, ctypes.c_char_p, ctypes.c_int, ctypes.c_char_p, ctypes.c_uint]",
+    "    rename_fn.restype = ctypes.c_int",
+    "    result = rename_fn(",
+    "        src_parent_fd,",
+    "        os.fsencode(src_basename),",
+    "        dst_parent_fd,",
+    "        os.fsencode(dst_basename),",
+    "        flags,",
+    "    )",
+    "    if result != 0:",
+    "        error_code = ctypes.get_errno()",
+    "        unsupported_codes = {errno.ENOSYS, errno.EINVAL, errno.ENOTSUP}",
+    "        if hasattr(errno, 'EOPNOTSUPP'):",
+    "            unsupported_codes.add(errno.EOPNOTSUPP)",
+    "        if is_linux and error_code in unsupported_codes:",
+    "            os.link(",
+    "                src_basename,",
+    "                dst_basename,",
+    "                src_dir_fd=src_parent_fd,",
+    "                dst_dir_fd=dst_parent_fd,",
+    "                follow_symlinks=False,",
+    "            )",
+    "            return",
+    "        raise OSError(error_code, os.strerror(error_code), dst_basename)",
+].join("\n");
+export const GUEST_FILESYSTEM_CREATE_EXCLUSIVE_PYTHON = [
+    "def create_exclusive(parent_fd, basename, stdin_buffer):",
+    "    staging_fd = None",
+    "    staging_name = None",
+    "    temp_fd = None",
+    "    temp_name = 'payload'",
+    "    temp_inode = None",
+    "    try:",
+    "        try:",
+    "            os.lstat(basename, dir_fd=parent_fd)",
+    "        except FileNotFoundError:",
+    "            pass",
+    "        else:",
+    "            raise FileExistsError(errno.EEXIST, os.strerror(errno.EEXIST), basename)",
+    "        staging_name, staging_fd = create_staging_dir(parent_fd)",
+    "        temp_fd = os.open(temp_name, WRITE_FLAGS, 0o600, dir_fd=staging_fd)",
+    "        while True:",
+    "            chunk = stdin_buffer.read(65536)",
+    "            if not chunk:",
+    "                break",
+    "            write_all(temp_fd, chunk)",
+    "        # exclusive create payload is durable before publication",
+    "        os.fsync(temp_fd)",
+    "        temp_inode = inode_identity(os.fstat(temp_fd))",
+    "        # Publish with a native atomic no-replace rename.",
+    "        rename_no_replace(staging_fd, temp_name, parent_fd, basename)",
+    "        target_stat = os.lstat(basename, dir_fd=parent_fd)",
+    "        if temp_inode != inode_identity(target_stat):",
+    "            raise OSError(errno.ESTALE, 'exclusive publication source changed', basename)",
+    "        os.fsync(parent_fd)",
+    "    finally:",
+    "        if temp_fd is not None:",
+    "            os.close(temp_fd)",
+    "        if staging_fd is not None:",
+    "            # Cleanup stays relative to the private pinned directory, so a",
+    "            # parent-path substitution cannot redirect payload deletion.",
+    "            try:",
+    "                os.unlink(temp_name, dir_fd=staging_fd)",
+    "            except FileNotFoundError:",
+    "                pass",
+    "            staging_identity = entry_identity(os.fstat(staging_fd))",
+    "            os.close(staging_fd)",
+    "            staging_removed = False",
+    "            if staging_name is not None:",
+    "                try:",
+    "                    current_staging = os.lstat(staging_name, dir_fd=parent_fd)",
+    "                    if same_identity(staging_identity, current_staging):",
+    "                        os.rmdir(staging_name, dir_fd=parent_fd)",
+    "                        staging_removed = True",
+    "                except FileNotFoundError:",
+    "                    pass",
+    "            if staging_removed:",
+    "                os.fsync(parent_fd)",
+].join("\n");

package/dist/guest.d.ts

@@ -0,0 +1,9 @@
+import { GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON } from "./guest-native-python.js";
+/** Exclusive create found an existing destination, including a lost publication race. */
+export declare const GUEST_FILESYSTEM_CREATE_EXISTS_EXIT_CODE = 17;
+/** Read found a missing parent or file after the admitted root was opened. */
+export declare const GUEST_FILESYSTEM_READ_NOT_FOUND_EXIT_CODE = 2;
+/** Python 3 source for the descriptor-relative guest filesystem protocol. See docs/guest.md. */
+export declare const GUEST_FILESYSTEM_PYTHON: string;
+export { GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON };
+//# sourceMappingURL=guest.d.ts.map

package/dist/guest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guest.d.ts","sourceRoot":"","sources":["../src/guest.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,yCAAyC,EAC1C,MAAM,0BAA0B,CAAC;AAElC,yFAAyF;AACzF,eAAO,MAAM,wCAAwC,KAAK,CAAC;AAC3D,8EAA8E;AAC9E,eAAO,MAAM,yCAAyC,IAAI,CAAC;AAE3D,gGAAgG;AAChG,eAAO,MAAM,uBAAuB,QAmZxB,CAAC;AAEb,OAAO,EAAE,yCAAyC,EAAE,CAAC"}