@catmint-fs/core 0.0.0-prealpha.0

package/dist/index.js

@@ -0,0 +1,1835 @@
+// src/types.ts
+var TransactionError = class extends Error {
+  rootCause;
+  sourceError;
+  rollbackErrors;
+  constructor(message, rootCause, sourceError, rollbackErrors) {
+    super(message);
+    this.name = "TransactionError";
+    this.rootCause = rootCause;
+    this.sourceError = sourceError;
+    this.rollbackErrors = rollbackErrors;
+  }
+};
+
+// src/errors.ts
+var FsError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(`${code}: ${message}`);
+    this.name = "FsError";
+    this.code = code;
+  }
+};
+
+// src/ledger.ts
+var DEFAULT_FILE_MODE = 438;
+var DEFAULT_DIR_MODE = 511;
+var Ledger = class {
+  records = /* @__PURE__ */ new Map();
+  // When chmod and chown coexist on the same path, we track both
+  // using a separate map keyed by path to hold the secondary operation.
+  // E.g., if chmod is the primary, chown data is stored in chmodChownPairs.
+  chmodChownPairs = /* @__PURE__ */ new Map();
+  nextOrder = 0;
+  caseSensitive;
+  constructor(caseSensitive = true) {
+    this.caseSensitive = caseSensitive;
+  }
+  normalizePath(p) {
+    return this.caseSensitive ? p : p.toLowerCase();
+  }
+  has(path2) {
+    return this.records.has(this.normalizePath(path2));
+  }
+  get(path2) {
+    return this.records.get(this.normalizePath(path2))?.change;
+  }
+  getDetail(path2) {
+    const key = this.normalizePath(path2);
+    const rec = this.records.get(key);
+    if (!rec) return null;
+    return this.recordToDetail(rec, key);
+  }
+  recordToDetail(rec, key) {
+    const { change } = rec;
+    switch (change.type) {
+      case "create": {
+        if (change.entryType === "directory") {
+          return {
+            type: "create",
+            entryType: "directory",
+            path: change.path,
+            mode: rec.mode ?? DEFAULT_DIR_MODE,
+            uid: rec.uid ?? 0,
+            gid: rec.gid ?? 0
+          };
+        }
+        return {
+          type: "create",
+          entryType: "file",
+          path: change.path,
+          content: rec.content ?? new Uint8Array(0),
+          mode: rec.mode ?? DEFAULT_FILE_MODE,
+          uid: rec.uid ?? 0,
+          gid: rec.gid ?? 0
+        };
+      }
+      case "update":
+        return {
+          type: "update",
+          path: change.path,
+          content: rec.content ?? new Uint8Array(0),
+          mode: rec.mode ?? DEFAULT_FILE_MODE,
+          uid: rec.uid ?? 0,
+          gid: rec.gid ?? 0
+        };
+      case "delete":
+        return {
+          type: "delete",
+          entryType: change.entryType,
+          path: change.path
+        };
+      case "rename":
+        return {
+          type: "rename",
+          from: change.from,
+          to: change.to
+        };
+      case "chmod": {
+        const pair = this.chmodChownPairs.get(key);
+        if (pair && pair.uid !== void 0 && pair.gid !== void 0) {
+        }
+        return {
+          type: "chmod",
+          path: change.path,
+          mode: change.mode
+        };
+      }
+      case "chown": {
+        const pair = this.chmodChownPairs.get(key);
+        if (pair && pair.mode !== void 0) {
+        }
+        return {
+          type: "chown",
+          path: change.path,
+          uid: change.uid,
+          gid: change.gid
+        };
+      }
+      case "symlink":
+        return {
+          type: "symlink",
+          path: change.path,
+          target: change.target
+        };
+    }
+  }
+  getAll() {
+    const entries = [];
+    const sorted = [...this.records.values()].sort(
+      (a, b) => a.order - b.order
+    );
+    for (const r of sorted) {
+      entries.push(r.change);
+    }
+    return entries;
+  }
+  getAllDetails() {
+    const sorted = [...this.records.entries()].sort(
+      ([, a], [, b]) => a.order - b.order
+    );
+    return sorted.map(([key, rec]) => this.recordToDetail(rec, key));
+  }
+  recordCreate(path2, entryType, content, mode, uid, gid) {
+    const key = this.normalizePath(path2);
+    const existing = this.records.get(key);
+    if (existing && existing.change.type === "delete") {
+      this.records.set(key, {
+        order: this.nextOrder++,
+        change: { type: "update", path: path2 },
+        content,
+        mode,
+        uid,
+        gid
+      });
+      this.chmodChownPairs.delete(key);
+      return;
+    }
+    if (existing && (existing.change.type === "create" || existing.change.type === "update")) {
+      existing.order = this.nextOrder++;
+      if (content !== void 0) existing.content = content;
+      if (mode !== void 0) existing.mode = mode;
+      if (uid !== void 0) existing.uid = uid;
+      if (gid !== void 0) existing.gid = gid;
+      return;
+    }
+    this.records.set(key, {
+      order: this.nextOrder++,
+      change: { type: "create", path: path2, entryType },
+      content,
+      mode,
+      uid,
+      gid
+    });
+    this.chmodChownPairs.delete(key);
+  }
+  recordUpdate(path2, content, mode, uid, gid) {
+    const key = this.normalizePath(path2);
+    const existing = this.records.get(key);
+    if (existing && existing.change.type === "create") {
+      existing.order = this.nextOrder++;
+      if (content !== void 0) existing.content = content;
+      if (mode !== void 0) existing.mode = mode;
+      if (uid !== void 0) existing.uid = uid;
+      if (gid !== void 0) existing.gid = gid;
+      return;
+    }
+    if (existing && existing.change.type === "update") {
+      existing.order = this.nextOrder++;
+      if (content !== void 0) existing.content = content;
+      if (mode !== void 0) existing.mode = mode;
+      if (uid !== void 0) existing.uid = uid;
+      if (gid !== void 0) existing.gid = gid;
+      return;
+    }
+    this.records.set(key, {
+      order: this.nextOrder++,
+      change: { type: "update", path: path2 },
+      content,
+      mode,
+      uid,
+      gid
+    });
+    this.chmodChownPairs.delete(key);
+  }
+  recordDelete(path2, entryType = "file") {
+    const key = this.normalizePath(path2);
+    const existing = this.records.get(key);
+    if (existing && existing.change.type === "create") {
+      this.records.delete(key);
+      this.chmodChownPairs.delete(key);
+      return;
+    }
+    if (existing && existing.change.type === "symlink") {
+      this.records.delete(key);
+      this.chmodChownPairs.delete(key);
+      return;
+    }
+    this.records.set(key, {
+      order: this.nextOrder++,
+      change: { type: "delete", entryType, path: path2 }
+    });
+    this.chmodChownPairs.delete(key);
+  }
+  recordRename(from, to) {
+    const fromKey = this.normalizePath(from);
+    const toKey = this.normalizePath(to);
+    const existing = this.records.get(fromKey);
+    if (existing && existing.change.type === "create") {
+      this.records.delete(fromKey);
+      this.chmodChownPairs.delete(fromKey);
+      this.records.set(toKey, {
+        order: this.nextOrder++,
+        change: { type: "create", path: to, entryType: existing.change.entryType },
+        content: existing.content,
+        mode: existing.mode,
+        uid: existing.uid,
+        gid: existing.gid,
+        target: existing.target
+      });
+      this.chmodChownPairs.delete(toKey);
+      return;
+    }
+    if (existing && existing.change.type === "symlink") {
+      this.records.delete(fromKey);
+      this.chmodChownPairs.delete(fromKey);
+      this.records.set(toKey, {
+        order: this.nextOrder++,
+        change: { type: "symlink", path: to, target: existing.change.target },
+        target: existing.change.target
+      });
+      this.chmodChownPairs.delete(toKey);
+      return;
+    }
+    this.records.set(fromKey, {
+      order: this.nextOrder++,
+      change: { type: "delete", entryType: "file", path: from }
+    });
+    this.chmodChownPairs.delete(fromKey);
+    this.records.set(toKey, {
+      order: this.nextOrder++,
+      change: { type: "rename", from, to }
+    });
+    this.chmodChownPairs.delete(toKey);
+  }
+  recordChmod(path2, mode) {
+    const key = this.normalizePath(path2);
+    const existing = this.records.get(key);
+    if (existing && (existing.change.type === "create" || existing.change.type === "update" || existing.change.type === "symlink")) {
+      existing.mode = mode;
+      return;
+    }
+    if (existing && existing.change.type === "chmod") {
+      existing.change = { type: "chmod", path: path2, mode };
+      existing.mode = mode;
+      return;
+    }
+    if (existing && existing.change.type === "chown") {
+      const chownData = {
+        uid: existing.change.uid,
+        gid: existing.change.gid
+      };
+      this.records.set(key, {
+        order: this.nextOrder++,
+        change: { type: "chmod", path: path2, mode },
+        mode,
+        uid: existing.uid,
+        gid: existing.gid
+      });
+      this.chmodChownPairs.set(key, chownData);
+      return;
+    }
+    this.records.set(key, {
+      order: this.nextOrder++,
+      change: { type: "chmod", path: path2, mode },
+      mode
+    });
+  }
+  recordChown(path2, uid, gid) {
+    const key = this.normalizePath(path2);
+    const existing = this.records.get(key);
+    if (existing && (existing.change.type === "create" || existing.change.type === "update" || existing.change.type === "symlink")) {
+      existing.uid = uid;
+      existing.gid = gid;
+      return;
+    }
+    if (existing && existing.change.type === "chown") {
+      existing.change = { type: "chown", path: path2, uid, gid };
+      existing.uid = uid;
+      existing.gid = gid;
+      return;
+    }
+    if (existing && existing.change.type === "chmod") {
+      const chmodData = { mode: existing.change.mode };
+      this.records.set(key, {
+        order: this.nextOrder++,
+        change: { type: "chown", path: path2, uid, gid },
+        mode: existing.mode,
+        uid,
+        gid
+      });
+      this.chmodChownPairs.set(key, chmodData);
+      return;
+    }
+    this.records.set(key, {
+      order: this.nextOrder++,
+      change: { type: "chown", path: path2, uid, gid },
+      uid,
+      gid
+    });
+  }
+  recordSymlink(path2, target) {
+    const key = this.normalizePath(path2);
+    this.records.set(key, {
+      order: this.nextOrder++,
+      change: { type: "symlink", path: path2, target },
+      target
+    });
+    this.chmodChownPairs.delete(key);
+  }
+  /**
+   * Returns the virtual mode for a path if it has been chmod'd (or created
+   * with a mode) in this ledger.
+   */
+  getVirtualMode(path2) {
+    const rec = this.records.get(this.normalizePath(path2));
+    if (!rec) return void 0;
+    return rec.mode;
+  }
+  /**
+   * Returns virtual ownership for a path if it has been chown'd (or created
+   * with ownership) in this ledger.
+   */
+  getVirtualOwnership(path2) {
+    const rec = this.records.get(this.normalizePath(path2));
+    if (!rec) return void 0;
+    if (rec.uid !== void 0 && rec.gid !== void 0) {
+      return { uid: rec.uid, gid: rec.gid };
+    }
+    return void 0;
+  }
+  /**
+   * Returns the content stored for a path, if any.
+   */
+  getContent(path2) {
+    const rec = this.records.get(this.normalizePath(path2));
+    if (!rec) return void 0;
+    return rec.content;
+  }
+  clear() {
+    this.records.clear();
+    this.chmodChownPairs.clear();
+    this.nextOrder = 0;
+  }
+};
+
+// src/permissions.ts
+async function checkPermission(adapter, ledger, capabilities, path2, op) {
+  if (!capabilities.permissions) {
+    return;
+  }
+  const virtualMode = ledger.getVirtualMode(path2);
+  if (virtualMode !== void 0) {
+    const ownership = ledger.getVirtualOwnership(path2);
+    checkModePermission(
+      virtualMode,
+      op,
+      ownership?.uid,
+      ownership?.gid
+    );
+    return;
+  }
+  if (ledger.has(path2)) {
+    return;
+  }
+  await adapter.checkPermission(path2, op);
+}
+function checkModePermission(mode, op, fileUid, fileGid) {
+  let bit;
+  switch (op) {
+    case "read":
+      bit = 4;
+      break;
+    case "write":
+      bit = 2;
+      break;
+    case "execute":
+      bit = 1;
+      break;
+  }
+  const ownerBits = mode >> 6 & 7;
+  const groupBits = mode >> 3 & 7;
+  const otherBits = mode & 7;
+  if ((otherBits & bit) !== 0) {
+    return;
+  }
+  if ((groupBits & bit) !== 0) {
+    return;
+  }
+  if ((ownerBits & bit) !== 0) {
+    return;
+  }
+  const opName = op === "read" ? "reading" : op === "write" ? "writing" : "executing";
+  throw new FsError("EACCES", `permission denied for ${opName}`);
+}
+
+// src/layer.ts
+var encoder = new TextEncoder();
+var MAX_SYMLINK_DEPTH = 40;
+var DEFAULT_FILE_MODE2 = 438;
+var DEFAULT_DIR_MODE2 = 511;
+var Layer = class {
+  adapter;
+  ledger;
+  capabilities;
+  root;
+  disposed = false;
+  constructor(root, adapter, capabilities) {
+    this.root = root;
+    this.adapter = adapter;
+    this.capabilities = capabilities;
+    this.ledger = new Ledger(capabilities.caseSensitive);
+  }
+  assertNotDisposed() {
+    if (this.disposed) {
+      throw new FsError("DISPOSED", "layer has been disposed");
+    }
+  }
+  /**
+   * Enforce ENOSYS for operations that require symlink support.
+   */
+  assertSymlinksSupported() {
+    if (!this.capabilities.symlinks) {
+      throw new FsError("ENOSYS", "operation not supported: symlinks are disabled");
+    }
+  }
+  resolvePath(p) {
+    if (p.startsWith("/")) return p;
+    return this.root + (this.root.endsWith("/") ? "" : "/") + p;
+  }
+  /**
+   * Follow symlinks to resolve the final path. Used by operations that
+   * follow symlinks (readFile, stat, writeFile, chmod, chown, exists).
+   */
+  async resolveSymlinks(path2, depth = 0) {
+    if (depth > MAX_SYMLINK_DEPTH) {
+      throw new FsError("ELOOP", `too many levels of symbolic links: ${path2}`);
+    }
+    const change = this.ledger.get(path2);
+    if (change && change.type === "symlink") {
+      const target = change.target;
+      const resolved = target.startsWith("/") ? target : this.resolveRelativeTarget(path2, target);
+      return this.resolveSymlinks(resolved, depth + 1);
+    }
+    if (change && change.type === "delete") {
+      throw new FsError("ENOENT", `no such file or directory: ${path2}`);
+    }
+    if (change && (change.type === "create" || change.type === "update")) {
+      return path2;
+    }
+    if (change && change.type === "rename") {
+      return path2;
+    }
+    try {
+      const lstatResult = await this.adapter.lstat(path2);
+      if (lstatResult.isSymbolicLink()) {
+        const target = await this.adapter.readlink(path2);
+        const resolved = target.startsWith("/") ? target : this.resolveRelativeTarget(path2, target);
+        return this.resolveSymlinks(resolved, depth + 1);
+      }
+      return path2;
+    } catch {
+      return path2;
+    }
+  }
+  resolveRelativeTarget(linkPath, target) {
+    const dir = linkPath.substring(0, linkPath.lastIndexOf("/")) || "/";
+    const parts = dir.split("/").filter(Boolean);
+    const targetParts = target.split("/");
+    for (const part of targetParts) {
+      if (part === "..") {
+        parts.pop();
+      } else if (part !== "." && part !== "") {
+        parts.push(part);
+      }
+    }
+    return "/" + parts.join("/");
+  }
+  // --- Reading ---
+  async readFile(path2) {
+    this.assertNotDisposed();
+    const absPath = this.resolvePath(path2);
+    const resolved = await this.resolveSymlinks(absPath);
+    await checkPermission(
+      this.adapter,
+      this.ledger,
+      this.capabilities,
+      resolved,
+      "read"
+    );
+    const change = this.ledger.get(resolved);
+    if (change) {
+      if (change.type === "delete") {
+        throw new FsError(
+          "ENOENT",
+          `no such file or directory: ${resolved}`
+        );
+      }
+      if (change.type === "create" && change.entryType === "directory") {
+        throw new FsError("EISDIR", `illegal operation on a directory: ${resolved}`);
+      }
+      const content = this.ledger.getContent(resolved);
+      if (content !== void 0) {
+        return content;
+      }
+      if (change.type === "rename") {
+        return this.adapter.readFile(change.from);
+      }
+    }
+    return this.adapter.readFile(resolved);
+  }
+  createReadStream(path2) {
+    this.assertNotDisposed();
+    const absPath = this.resolvePath(path2);
+    const self = this;
+    return new ReadableStream({
+      async start(controller) {
+        try {
+          const resolved = await self.resolveSymlinks(absPath);
+          await checkPermission(
+            self.adapter,
+            self.ledger,
+            self.capabilities,
+            resolved,
+            "read"
+          );
+          const change = self.ledger.get(resolved);
+          if (change) {
+            if (change.type === "delete") {
+              controller.error(
+                new FsError(
+                  "ENOENT",
+                  `no such file or directory: ${resolved}`
+                )
+              );
+              return;
+            }
+            if (change.type === "create" && change.entryType === "directory") {
+              controller.error(
+                new FsError("EISDIR", `illegal operation on a directory: ${resolved}`)
+              );
+              return;
+            }
+            const content = self.ledger.getContent(resolved);
+            if (content !== void 0) {
+              controller.enqueue(content);
+              controller.close();
+              return;
+            }
+            if (change.type === "rename") {
+              const reader2 = self.adapter.createReadStream(change.from).getReader();
+              try {
+                while (true) {
+                  const { done, value } = await reader2.read();
+                  if (done) break;
+                  controller.enqueue(value);
+                }
+                controller.close();
+              } catch (err) {
+                controller.error(err);
+              }
+              return;
+            }
+          }
+          const reader = self.adapter.createReadStream(resolved).getReader();
+          try {
+            while (true) {
+              const { done, value } = await reader.read();
+              if (done) break;
+              controller.enqueue(value);
+            }
+            controller.close();
+          } catch (err) {
+            controller.error(err);
+          }
+        } catch (err) {
+          controller.error(err);
+        }
+      }
+    });
+  }
+  async readdir(path2) {
+    this.assertNotDisposed();
+    const absPath = this.resolvePath(path2);
+    const resolved = await this.resolveSymlinks(absPath);
+    const change = this.ledger.get(resolved);
+    if (change && change.type === "delete") {
+      throw new FsError(
+        "ENOENT",
+        `no such file or directory: ${resolved}`
+      );
+    }
+    let entries = [];
+    let isVirtualDir = false;
+    if (change && change.type === "create" && change.entryType === "directory") {
+      isVirtualDir = true;
+    } else {
+      try {
+        entries = await this.adapter.readdir(resolved);
+      } catch (err) {
+        if (!isVirtualDir) throw err;
+      }
+    }
+    const entryMap = /* @__PURE__ */ new Map();
+    for (const entry of entries) {
+      const key = this.capabilities.caseSensitive ? entry.name : entry.name.toLowerCase();
+      entryMap.set(key, entry);
+    }
+    const allChanges = this.ledger.getAll();
+    const dirPrefix = resolved.endsWith("/") ? resolved : resolved + "/";
+    for (const ch of allChanges) {
+      const changePath = this.getChangePath(ch);
+      if (!changePath) continue;
+      if (!changePath.startsWith(dirPrefix)) continue;
+      const relative = changePath.substring(dirPrefix.length);
+      if (relative.includes("/")) continue;
+      const name = relative;
+      const key = this.capabilities.caseSensitive ? name : name.toLowerCase();
+      if (ch.type === "delete") {
+        entryMap.delete(key);
+      } else if (ch.type === "create") {
+        const entryType = ch.entryType;
+        entryMap.set(key, {
+          name,
+          isFile: () => entryType === "file",
+          isDirectory: () => entryType === "directory",
+          isSymbolicLink: () => false
+        });
+      } else if (ch.type === "symlink") {
+        entryMap.set(key, {
+          name,
+          isFile: () => false,
+          isDirectory: () => false,
+          isSymbolicLink: () => true
+        });
+      } else if (ch.type === "update" || ch.type === "rename") {
+        if (!entryMap.has(key)) {
+          entryMap.set(key, {
+            name,
+            isFile: () => true,
+            isDirectory: () => false,
+            isSymbolicLink: () => false
+          });
+        }
+      }
+    }
+    return [...entryMap.values()];
+  }
+  getChangePath(ch) {
+    switch (ch.type) {
+      case "create":
+      case "update":
+      case "delete":
+      case "chmod":
+      case "chown":
+      case "symlink":
+        return ch.path;
+      case "rename":
+        return ch.to;
+      default:
+        return void 0;
+    }
+  }
+  async stat(path2) {
+    this.assertNotDisposed();
+    const absPath = this.resolvePath(path2);
+    const resolved = await this.resolveSymlinks(absPath);
+    return this.statResolved(resolved, true);
+  }
+  async lstat(path2) {
+    this.assertNotDisposed();
+    this.assertSymlinksSupported();
+    const absPath = this.resolvePath(path2);
+    return this.statResolved(absPath, false);
+  }
+  async statResolved(absPath, followSymlinks) {
+    const change = this.ledger.get(absPath);
+    if (change) {
+      if (change.type === "delete") {
+        throw new FsError(
+          "ENOENT",
+          `no such file or directory: ${absPath}`
+        );
+      }
+      if (change.type === "create") {
+        const entryType = change.entryType;
+        const now = Date.now();
+        const detail = this.ledger.getDetail(absPath);
+        const content = this.ledger.getContent(absPath);
+        const size = entryType === "file" ? content?.byteLength ?? 0 : 0;
+        return {
+          mode: detail && "mode" in detail ? detail.mode : entryType === "directory" ? DEFAULT_DIR_MODE2 : DEFAULT_FILE_MODE2,
+          uid: detail && "uid" in detail ? detail.uid : 0,
+          gid: detail && "gid" in detail ? detail.gid : 0,
+          size,
+          atimeMs: now,
+          mtimeMs: now,
+          ctimeMs: now,
+          birthtimeMs: now,
+          isFile: () => entryType === "file",
+          isDirectory: () => entryType === "directory",
+          isSymbolicLink: () => false
+        };
+      }
+      if (change.type === "symlink") {
+        const now = Date.now();
+        return {
+          mode: 511,
+          uid: 0,
+          gid: 0,
+          size: change.target.length,
+          atimeMs: now,
+          mtimeMs: now,
+          ctimeMs: now,
+          birthtimeMs: now,
+          isFile: () => false,
+          isDirectory: () => false,
+          isSymbolicLink: () => true
+        };
+      }
+      if (change.type === "update" || change.type === "rename") {
+        const detail = this.ledger.getDetail(absPath);
+        const content = this.ledger.getContent(absPath);
+        const virtualMode = this.ledger.getVirtualMode(absPath);
+        const virtualOwnership = this.ledger.getVirtualOwnership(absPath);
+        let baseStat;
+        try {
+          if (change.type === "rename") {
+            baseStat = followSymlinks ? await this.adapter.stat(change.from) : await this.adapter.lstat(change.from);
+          } else {
+            baseStat = followSymlinks ? await this.adapter.stat(absPath) : await this.adapter.lstat(absPath);
+          }
+        } catch {
+          const now = Date.now();
+          baseStat = {
+            mode: DEFAULT_FILE_MODE2,
+            uid: 0,
+            gid: 0,
+            size: 0,
+            atimeMs: now,
+            mtimeMs: now,
+            ctimeMs: now,
+            birthtimeMs: now,
+            isFile: () => true,
+            isDirectory: () => false,
+            isSymbolicLink: () => false
+          };
+        }
+        return {
+          ...baseStat,
+          mode: virtualMode ?? baseStat.mode,
+          uid: virtualOwnership?.uid ?? baseStat.uid,
+          gid: virtualOwnership?.gid ?? baseStat.gid,
+          size: content?.byteLength ?? baseStat.size,
+          isFile: baseStat.isFile,
+          isDirectory: baseStat.isDirectory,
+          isSymbolicLink: baseStat.isSymbolicLink
+        };
+      }
+      if (change.type === "chmod" || change.type === "chown") {
+        const virtualMode = this.ledger.getVirtualMode(absPath);
+        const virtualOwnership = this.ledger.getVirtualOwnership(absPath);
+        const baseStat = followSymlinks ? await this.adapter.stat(absPath) : await this.adapter.lstat(absPath);
+        return {
+          ...baseStat,
+          mode: virtualMode ?? baseStat.mode,
+          uid: virtualOwnership?.uid ?? baseStat.uid,
+          gid: virtualOwnership?.gid ?? baseStat.gid,
+          isFile: baseStat.isFile,
+          isDirectory: baseStat.isDirectory,
+          isSymbolicLink: baseStat.isSymbolicLink
+        };
+      }
+    }
+    return followSymlinks ? this.adapter.stat(absPath) : this.adapter.lstat(absPath);
+  }
+  async readlink(path2) {
+    this.assertNotDisposed();
+    this.assertSymlinksSupported();
+    const absPath = this.resolvePath(path2);
+    const change = this.ledger.get(absPath);
+    if (change) {
+      if (change.type === "delete") {
+        throw new FsError(
+          "ENOENT",
+          `no such file or directory: ${absPath}`
+        );
+      }
+      if (change.type === "symlink") {
+        return change.target;
+      }
+      throw new FsError("EINVAL", `invalid argument: ${absPath} is not a symlink`);
+    }
+    return this.adapter.readlink(absPath);
+  }
+  async exists(path2) {
+    this.assertNotDisposed();
+    const absPath = this.resolvePath(path2);
+    try {
+      const resolved = await this.resolveSymlinks(absPath);
+      const change = this.ledger.get(resolved);
+      if (change) {
+        return change.type !== "delete";
+      }
+      return this.adapter.exists(resolved);
+    } catch {
+      return false;
+    }
+  }
+  // --- Writing ---
+  async writeFile(path2, data, options) {
+    this.assertNotDisposed();
+    const absPath = this.resolvePath(path2);
+    const parentDir = absPath.substring(0, absPath.lastIndexOf("/")) || "/";
+    await checkPermission(
+      this.adapter,
+      this.ledger,
+      this.capabilities,
+      parentDir,
+      "write"
+    );
+    let resolved;
+    try {
+      resolved = await this.resolveSymlinks(absPath);
+    } catch (err) {
+      if (err instanceof FsError && err.code === "ENOENT") {
+        resolved = absPath;
+      } else {
+        throw err;
+      }
+    }
+    const content = typeof data === "string" ? encoder.encode(data) : data;
+    const change = this.ledger.get(resolved);
+    if (change) {
+      if (change.type === "create" && change.entryType === "directory") {
+        throw new FsError(
+          "EISDIR",
+          `illegal operation on a directory: ${resolved}`
+        );
+      }
+      if (change.type === "delete") {
+        this.ledger.recordCreate(
+          resolved,
+          "file",
+          content,
+          options?.mode,
+          options?.uid,
+          options?.gid
+        );
+        return;
+      }
+      this.ledger.recordUpdate(
+        resolved,
+        content,
+        options?.mode,
+        options?.uid,
+        options?.gid
+      );
+      return;
+    }
+    const hostExists = await this.adapter.exists(resolved);
+    if (hostExists) {
+      try {
+        const s = await this.adapter.stat(resolved);
+        if (s.isDirectory()) {
+          throw new FsError(
+            "EISDIR",
+            `illegal operation on a directory: ${resolved}`
+          );
+        }
+      } catch (err) {
+        if (err instanceof FsError) throw err;
+      }
+      this.ledger.recordUpdate(
+        resolved,
+        content,
+        options?.mode,
+        options?.uid,
+        options?.gid
+      );
+    } else {
+      this.ledger.recordCreate(
+        resolved,
+        "file",
+        content,
+        options?.mode,
+        options?.uid,
+        options?.gid
+      );
+    }
+  }
+  async mkdir(path2, options) {
+    this.assertNotDisposed();
+    const absPath = this.resolvePath(path2);
+    if (options?.recursive) {
+      const parts = absPath.split("/").filter(Boolean);
+      let current = "";
+      for (const part of parts) {
+        current += "/" + part;
+        const change = this.ledger.get(current);
+        const existsOnHost = await this.adapter.exists(current);
+        if (change) {
+          if (change.type === "delete") {
+            this.ledger.recordCreate(
+              current,
+              "directory",
+              void 0,
+              options?.mode,
+              options?.uid,
+              options?.gid
+            );
+          }
+          continue;
+        }
+        if (!existsOnHost) {
+          this.ledger.recordCreate(
+            current,
+            "directory",
+            void 0,
+            options?.mode,
+            options?.uid,
+            options?.gid
+          );
+        }
+      }
+    } else {
+      const parentDir = absPath.substring(0, absPath.lastIndexOf("/")) || "/";
+      const parentChange = this.ledger.get(parentDir);
+      let parentExists = false;
+      if (parentChange) {
+        parentExists = parentChange.type !== "delete";
+      } else {
+        parentExists = await this.adapter.exists(parentDir);
+      }
+      if (!parentExists) {
+        throw new FsError(
+          "ENOENT",
+          `no such file or directory: ${parentDir}`
+        );
+      }
+      await checkPermission(
+        this.adapter,
+        this.ledger,
+        this.capabilities,
+        parentDir,
+        "write"
+      );
+      const change = this.ledger.get(absPath);
+      if (change && change.type !== "delete") {
+        throw new FsError("EEXIST", `file already exists: ${absPath}`);
+      }
+      const existsOnHost = !change && await this.adapter.exists(absPath);
+      if (existsOnHost) {
+        throw new FsError("EEXIST", `file already exists: ${absPath}`);
+      }
+      this.ledger.recordCreate(
+        absPath,
+        "directory",
+        void 0,
+        options?.mode,
+        options?.uid,
+        options?.gid
+      );
+    }
+  }
+  // --- Deleting ---
+  async rm(path2, options) {
+    this.assertNotDisposed();
+    const absPath = this.resolvePath(path2);
+    const change = this.ledger.get(absPath);
+    if (change && change.type === "delete") {
+      if (options?.force) return;
+      throw new FsError(
+        "ENOENT",
+        `no such file or directory: ${absPath}`
+      );
+    }
+    const existsOnHost = !change && await this.adapter.exists(absPath);
+    if (!change && !existsOnHost) {
+      if (options?.force) return;
+      throw new FsError(
+        "ENOENT",
+        `no such file or directory: ${absPath}`
+      );
+    }
+    const parentDir = absPath.substring(0, absPath.lastIndexOf("/")) || "/";
+    await checkPermission(
+      this.adapter,
+      this.ledger,
+      this.capabilities,
+      parentDir,
+      "write"
+    );
+    let entryType = "file";
+    let isDir = false;
+    if (change) {
+      if (change.type === "create" && change.entryType === "directory") {
+        isDir = true;
+        entryType = "directory";
+      } else if (change.type === "symlink") {
+        entryType = "symlink";
+      }
+    } else if (existsOnHost) {
+      try {
+        const s = await this.adapter.lstat(absPath);
+        if (s.isDirectory()) {
+          isDir = true;
+          entryType = "directory";
+        } else if (s.isSymbolicLink()) {
+          entryType = "symlink";
+        }
+      } catch {
+      }
+    }
+    if (isDir && !options?.recursive) {
+      throw new FsError("EISDIR", `is a directory: ${absPath}`);
+    }
+    if (isDir && options?.recursive) {
+      const allChanges = this.ledger.getAll();
+      const dirPrefix = absPath + "/";
+      for (const ch of allChanges) {
+        const chPath = this.getChangePath(ch);
+        if (chPath && chPath.startsWith(dirPrefix)) {
+          let childType = "file";
+          if (ch.type === "create" && ch.entryType === "directory") {
+            childType = "directory";
+          } else if (ch.type === "symlink") {
+            childType = "symlink";
+          }
+          this.ledger.recordDelete(chPath, childType);
+        }
+      }
+    }
+    this.ledger.recordDelete(absPath, entryType);
+  }
+  async rmdir(path2) {
+    this.assertNotDisposed();
+    const absPath = this.resolvePath(path2);
+    const change = this.ledger.get(absPath);
+    if (change && change.type === "delete") {
+      throw new FsError(
+        "ENOENT",
+        `no such file or directory: ${absPath}`
+      );
+    }
+    let isDir = false;
+    if (change) {
+      isDir = change.type === "create" && change.entryType === "directory";
+    } else {
+      try {
+        const s = await this.adapter.lstat(absPath);
+        isDir = s.isDirectory();
+      } catch {
+        throw new FsError(
+          "ENOENT",
+          `no such file or directory: ${absPath}`
+        );
+      }
+    }
+    if (!isDir) {
+      throw new FsError("ENOTDIR", `not a directory: ${absPath}`);
+    }
+    const entries = await this.readdir(absPath);
+    if (entries.length > 0) {
+      throw new FsError("ENOTEMPTY", `directory not empty: ${absPath}`);
+    }
+    this.ledger.recordDelete(absPath, "directory");
+  }
+  // --- Renaming ---
+  async rename(from, to) {
+    this.assertNotDisposed();
+    const absFrom = this.resolvePath(from);
+    const absTo = this.resolvePath(to);
+    const srcChange = this.ledger.get(absFrom);
+    if (srcChange && srcChange.type === "delete") {
+      throw new FsError(
+        "ENOENT",
+        `no such file or directory: ${absFrom}`
+      );
+    }
+    if (!srcChange) {
+      const srcExists = await this.adapter.exists(absFrom);
+      if (!srcExists) {
+        throw new FsError(
+          "ENOENT",
+          `no such file or directory: ${absFrom}`
+        );
+      }
+    }
+    const destChange = this.ledger.get(absTo);
+    if (destChange && destChange.type !== "delete") {
+      let srcIsDir = false;
+      let destIsDir = false;
+      if (srcChange && srcChange.type === "create") {
+        srcIsDir = srcChange.entryType === "directory";
+      } else if (!srcChange) {
+        try {
+          const s = await this.adapter.lstat(absFrom);
+          srcIsDir = s.isDirectory();
+        } catch {
+        }
+      }
+      if (destChange.type === "create") {
+        destIsDir = destChange.entryType === "directory";
+      }
+      if (srcIsDir !== destIsDir) {
+        if (destIsDir) {
+          throw new FsError("EISDIR", `cannot overwrite directory with non-directory: ${absTo}`);
+        } else {
+          throw new FsError("ENOTDIR", `cannot overwrite non-directory with directory: ${absTo}`);
+        }
+      }
+    }
+    this.ledger.recordRename(absFrom, absTo);
+  }
+  // --- Symlinks ---
+  async symlink(target, path2) {
+    this.assertNotDisposed();
+    this.assertSymlinksSupported();
+    const absPath = this.resolvePath(path2);
+    const parentDir = absPath.substring(0, absPath.lastIndexOf("/")) || "/";
+    await checkPermission(
+      this.adapter,
+      this.ledger,
+      this.capabilities,
+      parentDir,
+      "write"
+    );
+    const change = this.ledger.get(absPath);
+    if (change && change.type !== "delete") {
+      throw new FsError("EEXIST", `file already exists: ${absPath}`);
+    }
+    if (!change) {
+      const existsOnHost = await this.adapter.exists(absPath);
+      if (existsOnHost) {
+        throw new FsError("EEXIST", `file already exists: ${absPath}`);
+      }
+    }
+    this.ledger.recordSymlink(absPath, target);
+  }
+  // --- Permissions ---
+  async chmod(path2, mode) {
+    this.assertNotDisposed();
+    const absPath = this.resolvePath(path2);
+    const resolved = await this.resolveSymlinks(absPath);
+    const change = this.ledger.get(resolved);
+    if (change && change.type === "delete") {
+      throw new FsError(
+        "ENOENT",
+        `no such file or directory: ${resolved}`
+      );
+    }
+    if (!change) {
+      const existsOnHost = await this.adapter.exists(resolved);
+      if (!existsOnHost) {
+        throw new FsError(
+          "ENOENT",
+          `no such file or directory: ${resolved}`
+        );
+      }
+    }
+    this.ledger.recordChmod(resolved, mode);
+  }
+  async chown(path2, uid, gid) {
+    this.assertNotDisposed();
+    const absPath = this.resolvePath(path2);
+    const resolved = await this.resolveSymlinks(absPath);
+    const change = this.ledger.get(resolved);
+    if (change && change.type === "delete") {
+      throw new FsError(
+        "ENOENT",
+        `no such file or directory: ${resolved}`
+      );
+    }
+    if (!change) {
+      const existsOnHost = await this.adapter.exists(resolved);
+      if (!existsOnHost) {
+        throw new FsError(
+          "ENOENT",
+          `no such file or directory: ${resolved}`
+        );
+      }
+    }
+    this.ledger.recordChown(resolved, uid, gid);
+  }
+  async lchown(path2, uid, gid) {
+    this.assertNotDisposed();
+    this.assertSymlinksSupported();
+    const absPath = this.resolvePath(path2);
+    const change = this.ledger.get(absPath);
+    if (change && change.type === "delete") {
+      throw new FsError(
+        "ENOENT",
+        `no such file or directory: ${absPath}`
+      );
+    }
+    if (!change) {
+      const existsOnHost = await this.adapter.exists(absPath);
+      if (!existsOnHost) {
+        throw new FsError(
+          "ENOENT",
+          `no such file or directory: ${absPath}`
+        );
+      }
+    }
+    this.ledger.recordChown(absPath, uid, gid);
+  }
+  async getOwner(path2) {
+    this.assertNotDisposed();
+    const absPath = this.resolvePath(path2);
+    const resolved = await this.resolveSymlinks(absPath);
+    const ownership = this.ledger.getVirtualOwnership(resolved);
+    if (ownership) return ownership;
+    const s = await this.adapter.stat(resolved);
+    return { uid: s.uid, gid: s.gid };
+  }
+  // --- Changes ---
+  getChanges() {
+    this.assertNotDisposed();
+    return this.ledger.getAll();
+  }
+  async getChangeDetail(path2) {
+    this.assertNotDisposed();
+    const absPath = this.resolvePath(path2);
+    return this.ledger.getDetail(absPath);
+  }
+  // --- Apply ---
+  async apply(options) {
+    this.assertNotDisposed();
+    const transaction = options?.transaction ?? false;
+    const allDetails = this.ledger.getAllDetails();
+    if (allDetails.length === 0) {
+      return { applied: 0, errors: [] };
+    }
+    const dirCreates = [];
+    const fileCreatesUpdates = [];
+    const renames = [];
+    const permChanges = [];
+    const fileSymlinkDeletes = [];
+    const dirDeletes = [];
+    for (const detail of allDetails) {
+      switch (detail.type) {
+        case "create":
+          if (detail.entryType === "directory") {
+            dirCreates.push(detail);
+          } else {
+            fileCreatesUpdates.push(detail);
+          }
+          break;
+        case "update":
+          fileCreatesUpdates.push(detail);
+          break;
+        case "rename":
+          renames.push(detail);
+          break;
+        case "chmod":
+        case "chown":
+          permChanges.push(detail);
+          break;
+        case "delete":
+          if (detail.entryType === "directory") {
+            dirDeletes.push(detail);
+          } else {
+            fileSymlinkDeletes.push(detail);
+          }
+          break;
+        case "symlink":
+          fileCreatesUpdates.push(detail);
+          break;
+      }
+    }
+    dirCreates.sort((a, b) => {
+      const aPath = a.type === "create" ? a.path : "";
+      const bPath = b.type === "create" ? b.path : "";
+      return aPath.split("/").length - bPath.split("/").length;
+    });
+    dirDeletes.sort((a, b) => {
+      const aPath = a.type === "delete" ? a.path : "";
+      const bPath = b.type === "delete" ? b.path : "";
+      return bPath.split("/").length - aPath.split("/").length;
+    });
+    const plan = [
+      ...dirCreates,
+      ...fileCreatesUpdates,
+      ...renames,
+      ...permChanges,
+      ...fileSymlinkDeletes,
+      ...dirDeletes
+    ];
+    if (transaction) {
+      return this.applyTransaction(plan);
+    } else {
+      return this.applyBestEffort(plan);
+    }
+  }
+  async applyBestEffort(plan) {
+    let applied = 0;
+    const errors = [];
+    for (const detail of plan) {
+      try {
+        await this.applyOne(detail);
+        applied++;
+      } catch (err) {
+        errors.push({
+          change: this.detailToChangeEntry(detail),
+          error: err instanceof Error ? err : new Error(String(err))
+        });
+      }
+    }
+    this.ledger.clear();
+    return { applied, errors };
+  }
+  async applyTransaction(plan) {
+    const originals = [];
+    let applied = 0;
+    for (const detail of plan) {
+      const path2 = this.getDetailPath(detail);
+      if (path2) {
+        try {
+          const existed = await this.adapter.exists(path2);
+          let content;
+          let stat2;
+          if (existed) {
+            try {
+              stat2 = await this.adapter.lstat(path2);
+              if (stat2.isFile()) {
+                content = await this.adapter.readFile(path2);
+              }
+            } catch {
+            }
+          }
+          originals.push({
+            detail,
+            backup: { existed, content, stat: stat2 }
+          });
+        } catch {
+          originals.push({
+            detail,
+            backup: { existed: false }
+          });
+        }
+      }
+      try {
+        await this.applyOne(detail);
+        applied++;
+      } catch (err) {
+        const rollbackErrors = [];
+        for (let i = originals.length - 2; i >= 0; i--) {
+          const orig = originals[i];
+          try {
+            await this.rollbackOne(orig.detail, orig.backup);
+          } catch (rbErr) {
+            rollbackErrors.push({
+              change: this.detailToChangeEntry(orig.detail),
+              error: rbErr instanceof Error ? rbErr : new Error(String(rbErr))
+            });
+          }
+        }
+        throw new TransactionError(
+          `Transaction failed: ${err instanceof Error ? err.message : String(err)}`,
+          this.detailToChangeEntry(detail),
+          err instanceof Error ? err : new Error(String(err)),
+          rollbackErrors
+        );
+      }
+    }
+    this.ledger.clear();
+    return { applied, errors: [] };
+  }
+  /**
+   * Convert a flat ChangeDetail back to a ChangeEntry for error reporting.
+   */
+  detailToChangeEntry(detail) {
+    switch (detail.type) {
+      case "create":
+        return { type: "create", entryType: detail.entryType, path: detail.path };
+      case "update":
+        return { type: "update", path: detail.path };
+      case "delete":
+        return { type: "delete", entryType: detail.entryType, path: detail.path };
+      case "rename":
+        return { type: "rename", from: detail.from, to: detail.to };
+      case "chmod":
+        return { type: "chmod", path: detail.path, mode: detail.mode };
+      case "chown":
+        return { type: "chown", path: detail.path, uid: detail.uid, gid: detail.gid };
+      case "symlink":
+        return { type: "symlink", path: detail.path, target: detail.target };
+    }
+  }
+  /**
+   * Get the primary path from a ChangeDetail.
+   */
+  getDetailPath(detail) {
+    switch (detail.type) {
+      case "create":
+      case "update":
+      case "delete":
+      case "chmod":
+      case "chown":
+      case "symlink":
+        return detail.path;
+      case "rename":
+        return detail.to;
+      default:
+        return void 0;
+    }
+  }
+  async rollbackOne(detail, backup) {
+    const path2 = this.getDetailPath(detail);
+    if (!path2) return;
+    if (backup.existed) {
+      if (backup.content !== void 0) {
+        await this.adapter.writeFile(path2, backup.content, {
+          mode: backup.stat?.mode
+        });
+      }
+      if (backup.stat) {
+        try {
+          await this.adapter.chmod(path2, backup.stat.mode);
+        } catch {
+        }
+        try {
+          await this.adapter.chown(path2, backup.stat.uid, backup.stat.gid);
+        } catch {
+        }
+      }
+    } else {
+      try {
+        await this.adapter.rm(path2, { recursive: true, force: true });
+      } catch {
+      }
+    }
+  }
+  async applyOne(detail) {
+    switch (detail.type) {
+      case "create": {
+        if (detail.entryType === "directory") {
+          await this.adapter.mkdir(detail.path, {
+            recursive: true,
+            mode: detail.mode,
+            uid: detail.uid,
+            gid: detail.gid
+          });
+        } else {
+          await this.adapter.writeFile(
+            detail.path,
+            detail.content,
+            {
+              mode: detail.mode,
+              uid: detail.uid,
+              gid: detail.gid
+            }
+          );
+        }
+        break;
+      }
+      case "update":
+        await this.adapter.writeFile(
+          detail.path,
+          detail.content,
+          {
+            mode: detail.mode,
+            uid: detail.uid,
+            gid: detail.gid
+          }
+        );
+        break;
+      case "delete":
+        await this.adapter.rm(detail.path, {
+          recursive: true,
+          force: true
+        });
+        break;
+      case "rename":
+        await this.adapter.rename(detail.from, detail.to);
+        break;
+      case "chmod":
+        await this.adapter.chmod(detail.path, detail.mode);
+        break;
+      case "chown":
+        await this.adapter.chown(detail.path, detail.uid, detail.gid);
+        break;
+      case "symlink":
+        await this.adapter.symlink(detail.target, detail.path);
+        break;
+    }
+  }
+  // --- Lifecycle ---
+  dispose() {
+    this.disposed = true;
+    this.ledger.clear();
+  }
+  reset() {
+    this.assertNotDisposed();
+    this.ledger.clear();
+  }
+};
+
+// src/adapters/local.ts
+import * as fs from "fs/promises";
+import * as nodeFs from "fs";
+import * as path from "path";
+var LocalAdapter = class {
+  _capabilities = {
+    permissions: true,
+    symlinks: true,
+    caseSensitive: true
+  };
+  async initialize(root) {
+    const testName = `.catmint-case-probe-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    const testPath = path.join(root, testName);
+    const testPathUpper = path.join(root, testName.toUpperCase());
+    try {
+      await fs.writeFile(testPath, "");
+      let caseSensitive = true;
+      try {
+        await fs.access(testPathUpper);
+        caseSensitive = false;
+      } catch {
+        caseSensitive = true;
+      }
+      this._capabilities = {
+        permissions: true,
+        symlinks: true,
+        caseSensitive
+      };
+    } finally {
+      try {
+        await fs.unlink(testPath);
+      } catch {
+      }
+    }
+  }
+  capabilities() {
+    return this._capabilities;
+  }
+  async readFile(filePath) {
+    try {
+      const buffer = await fs.readFile(filePath);
+      return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    } catch (err) {
+      throw this.mapError(err, filePath);
+    }
+  }
+  createReadStream(filePath) {
+    const nodeStream = nodeFs.createReadStream(filePath);
+    return new ReadableStream({
+      start(controller) {
+        nodeStream.on("data", (chunk) => {
+          controller.enqueue(
+            new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength)
+          );
+        });
+        nodeStream.on("end", () => {
+          controller.close();
+        });
+        nodeStream.on("error", (err) => {
+          controller.error(err);
+        });
+      },
+      cancel() {
+        nodeStream.destroy();
+      }
+    });
+  }
+  async readdir(dirPath) {
+    try {
+      const entries = await fs.readdir(dirPath, { withFileTypes: true });
+      return entries.map((entry) => ({
+        name: entry.name,
+        isFile: () => entry.isFile(),
+        isDirectory: () => entry.isDirectory(),
+        isSymbolicLink: () => entry.isSymbolicLink()
+      }));
+    } catch (err) {
+      throw this.mapError(err, dirPath);
+    }
+  }
+  async stat(filePath) {
+    try {
+      const s = await fs.stat(filePath);
+      return {
+        mode: s.mode,
+        uid: s.uid,
+        gid: s.gid,
+        size: s.size,
+        atimeMs: s.atimeMs,
+        mtimeMs: s.mtimeMs,
+        ctimeMs: s.ctimeMs,
+        birthtimeMs: s.birthtimeMs,
+        isFile: () => s.isFile(),
+        isDirectory: () => s.isDirectory(),
+        isSymbolicLink: () => s.isSymbolicLink()
+      };
+    } catch (err) {
+      throw this.mapError(err, filePath);
+    }
+  }
+  async lstat(filePath) {
+    try {
+      const s = await fs.lstat(filePath);
+      return {
+        mode: s.mode,
+        uid: s.uid,
+        gid: s.gid,
+        size: s.size,
+        atimeMs: s.atimeMs,
+        mtimeMs: s.mtimeMs,
+        ctimeMs: s.ctimeMs,
+        birthtimeMs: s.birthtimeMs,
+        isFile: () => s.isFile(),
+        isDirectory: () => s.isDirectory(),
+        isSymbolicLink: () => s.isSymbolicLink()
+      };
+    } catch (err) {
+      throw this.mapError(err, filePath);
+    }
+  }
+  async readlink(filePath) {
+    try {
+      return await fs.readlink(filePath);
+    } catch (err) {
+      throw this.mapError(err, filePath);
+    }
+  }
+  async exists(filePath) {
+    try {
+      await fs.access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async writeFile(filePath, data, options) {
+    try {
+      await fs.writeFile(filePath, data, { mode: options?.mode });
+      if (options?.uid !== void 0 && options?.gid !== void 0 && (options.uid !== process.getuid?.() || options.gid !== process.getgid?.())) {
+        try {
+          await fs.chown(filePath, options.uid, options.gid);
+        } catch {
+        }
+      }
+    } catch (err) {
+      throw this.mapError(err, filePath);
+    }
+  }
+  async mkdir(dirPath, options) {
+    try {
+      await fs.mkdir(dirPath, {
+        recursive: options?.recursive,
+        mode: options?.mode
+      });
+      if (options?.uid !== void 0 && options?.gid !== void 0) {
+        await fs.chown(dirPath, options.uid, options.gid);
+      }
+    } catch (err) {
+      throw this.mapError(err, dirPath);
+    }
+  }
+  async rm(filePath, options) {
+    try {
+      await fs.rm(filePath, {
+        recursive: options?.recursive,
+        force: options?.force
+      });
+    } catch (err) {
+      throw this.mapError(err, filePath);
+    }
+  }
+  async rmdir(dirPath) {
+    try {
+      await fs.rmdir(dirPath);
+    } catch (err) {
+      throw this.mapError(err, dirPath);
+    }
+  }
+  async rename(from, to) {
+    try {
+      await fs.rename(from, to);
+    } catch (err) {
+      throw this.mapError(err, from);
+    }
+  }
+  async symlink(target, linkPath) {
+    try {
+      await fs.symlink(target, linkPath);
+    } catch (err) {
+      throw this.mapError(err, linkPath);
+    }
+  }
+  async chmod(filePath, mode) {
+    try {
+      await fs.chmod(filePath, mode);
+    } catch (err) {
+      throw this.mapError(err, filePath);
+    }
+  }
+  async chown(filePath, uid, gid) {
+    try {
+      await fs.chown(filePath, uid, gid);
+    } catch (err) {
+      throw this.mapError(err, filePath);
+    }
+  }
+  async lchown(filePath, uid, gid) {
+    try {
+      await fs.lchown(filePath, uid, gid);
+    } catch (err) {
+      throw this.mapError(err, filePath);
+    }
+  }
+  async checkPermission(filePath, op) {
+    let mode;
+    switch (op) {
+      case "read":
+        mode = nodeFs.constants.R_OK;
+        break;
+      case "write":
+        mode = nodeFs.constants.W_OK;
+        break;
+      case "execute":
+        mode = nodeFs.constants.X_OK;
+        break;
+    }
+    try {
+      await fs.access(filePath, mode);
+    } catch (err) {
+      throw this.mapError(err, filePath);
+    }
+  }
+  mapError(err, filePath) {
+    if (err instanceof FsError) return err;
+    const nodeErr = err;
+    const code = nodeErr?.code;
+    switch (code) {
+      case "ENOENT":
+        return new FsError(
+          "ENOENT",
+          `no such file or directory: ${filePath}`
+        );
+      case "EACCES":
+        return new FsError("EACCES", `permission denied: ${filePath}`);
+      case "EPERM":
+        return new FsError(
+          "EPERM",
+          `operation not permitted: ${filePath}`
+        );
+      case "EEXIST":
+        return new FsError(
+          "EEXIST",
+          `file already exists: ${filePath}`
+        );
+      case "ENOTDIR":
+        return new FsError("ENOTDIR", `not a directory: ${filePath}`);
+      case "EISDIR":
+        return new FsError(
+          "EISDIR",
+          `is a directory: ${filePath}`
+        );
+      case "ELOOP":
+        return new FsError(
+          "ELOOP",
+          `too many symbolic links: ${filePath}`
+        );
+      case "EINVAL":
+        return new FsError(
+          "EINVAL",
+          `invalid argument: ${filePath}`
+        );
+      case "ENOTEMPTY":
+        return new FsError(
+          "ENOTEMPTY",
+          `directory not empty: ${filePath}`
+        );
+      default:
+        return new FsError(
+          "ENOSYS",
+          `${code ?? "unknown error"}: ${filePath}: ${nodeErr?.message ?? ""}`
+        );
+    }
+  }
+};
+
+// src/index.ts
+async function createLayer(options) {
+  const { root, adapter: userAdapter } = options;
+  if (!root.startsWith("/")) {
+    throw new FsError("EINVAL", "root must be an absolute path");
+  }
+  const adapter = userAdapter ?? new LocalAdapter();
+  if (adapter.initialize) {
+    await adapter.initialize(root);
+  }
+  const capabilities = adapter.capabilities();
+  return new Layer(root, adapter, capabilities);
+}
+export {
+  FsError,
+  Layer,
+  Ledger,
+  LocalAdapter,
+  TransactionError,
+  createLayer
+};