@gea-ai/cli-darwin-arm64 0.1.260825-alpha.4

package/system-workers/filesystem.mjs

@@ -0,0 +1,2038 @@
+import { DurableObject } from "cloudflare:workers";
+
+const MAX_ALLOCATION_ID_BYTES = 512;
+const MAX_MUTATION_ID_BYTES = 256;
+const MAX_OPERATIONS_PER_BATCH = 256;
+const MAX_INLINE_FILE_BYTES = 1024 * 1024;
+const MAX_INLINE_BYTES_PER_OBJECT = 16 * 1024 * 1024;
+const MAX_ENTRIES_PER_OBJECT = 100_000;
+const MAX_ENTRIES_PER_DIRECTORY = 4_096;
+const MAX_CHECKPOINT_IMAGE_BYTES = 4 * 1024 * 1024 * 1024;
+const MAX_CHECKPOINT_MANIFEST_BYTES = 16 * 1024 * 1024;
+const MAX_CHECKPOINT_TRANSFER_CHUNK_BYTES = 8 * 1024 * 1024;
+const MAX_SQL_BLOB_BYTES = 1024 * 1024;
+const MAX_PENDING_CHECKPOINT_UPLOADS = 16;
+const CHECKPOINT_UPLOAD_TTL_MS = 24 * 60 * 60 * 1000;
+const RETAINED_CHECKPOINTS = 2;
+const MAX_MOUNT_BYTES = 20 * 1024 * 1024;
+const MAX_MOUNT_FILES = 10_000;
+const MAX_MOUNTS = 16;
+const PROTOCOL_VERSION = 1;
+const UUID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+class FilesystemRequestError extends Error {
+  constructor(status, message, code = "INVALID_REQUEST", retryable = false) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.retryable = retryable;
+  }
+}
+
+export class FilesystemObject extends DurableObject {
+  constructor(ctx, env) {
+    super(ctx, env);
+    this.ctx.storage.sql.exec(`
+      CREATE TABLE IF NOT EXISTS filesystem_meta (
+        singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+        revision INTEGER NOT NULL,
+        logical_bytes INTEGER NOT NULL,
+        entry_count INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS filesystem_entries (
+        path TEXT PRIMARY KEY,
+        parent_path TEXT,
+        name TEXT NOT NULL,
+        kind TEXT NOT NULL CHECK (kind IN ('directory', 'file')),
+        content BLOB,
+        sha256 TEXT,
+        size_bytes INTEGER NOT NULL,
+        created_at_ms INTEGER NOT NULL,
+        modified_at_ms INTEGER NOT NULL,
+        revision INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS filesystem_entries_parent
+        ON filesystem_entries(parent_path, name);
+      CREATE TABLE IF NOT EXISTS filesystem_mutations (
+        mutation_id TEXT PRIMARY KEY,
+        request_hash TEXT NOT NULL,
+        applied_revision INTEGER NOT NULL,
+        result_json TEXT NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS filesystem_changes (
+        revision INTEGER NOT NULL,
+        sequence INTEGER NOT NULL,
+        operation TEXT NOT NULL,
+        path TEXT NOT NULL,
+        kind TEXT NOT NULL,
+        PRIMARY KEY (revision, sequence)
+      );
+      CREATE TABLE IF NOT EXISTS filesystem_checkpoint_meta (
+        singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+        checkpoint_revision INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS filesystem_checkpoints (
+        checkpoint_revision INTEGER PRIMARY KEY,
+        parent_checkpoint_revision INTEGER NOT NULL,
+        checkpoint_id TEXT NOT NULL UNIQUE,
+        image_blob_id TEXT NOT NULL,
+        image_sha256 TEXT NOT NULL,
+        image_size_bytes INTEGER NOT NULL,
+        manifest_blob_id TEXT NOT NULL,
+        manifest_sha256 TEXT NOT NULL,
+        manifest_size_bytes INTEGER NOT NULL,
+        created_at_ms INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS filesystem_checkpoint_blob_chunks (
+        blob_id TEXT NOT NULL,
+        offset INTEGER NOT NULL,
+        content BLOB NOT NULL,
+        PRIMARY KEY (blob_id, offset)
+      );
+      CREATE TABLE IF NOT EXISTS filesystem_checkpoint_uploads (
+        upload_id TEXT PRIMARY KEY,
+        kind TEXT NOT NULL CHECK (kind IN ('image', 'manifest')),
+        sha256 TEXT NOT NULL,
+        size_bytes INTEGER NOT NULL,
+        received_bytes INTEGER NOT NULL,
+        sha256_state_json TEXT NOT NULL,
+        committed INTEGER NOT NULL CHECK (committed IN (0, 1)),
+        created_at_ms INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS filesystem_mounts (
+        mount TEXT PRIMARY KEY,
+        content_id TEXT NOT NULL,
+        mode TEXT NOT NULL CHECK (mode = 'read-only'),
+        file_count INTEGER NOT NULL,
+        size_bytes INTEGER NOT NULL,
+        created_at_ms INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS filesystem_mount_files (
+        mount TEXT NOT NULL,
+        path TEXT NOT NULL,
+        size_bytes INTEGER NOT NULL,
+        PRIMARY KEY (mount, path)
+      );
+      CREATE TABLE IF NOT EXISTS filesystem_mount_file_chunks (
+        mount TEXT NOT NULL,
+        path TEXT NOT NULL,
+        offset INTEGER NOT NULL,
+        content BLOB NOT NULL,
+        PRIMARY KEY (mount, path, offset)
+      );
+    `);
+    this.#initializeFilesystem();
+  }
+
+  async fetch(request) {
+    try {
+      const url = new URL(request.url);
+      if (request.method === "GET" && url.pathname === "/") {
+        return Response.json(this.#inspect());
+      }
+      if (request.method === "POST" && url.pathname === "/batches") {
+        return Response.json(await this.#applyBatch(await readJson(request)));
+      }
+      if (request.method === "POST" && url.pathname === "/invoke") {
+        return Response.json(await this.#invoke(await readJson(request)));
+      }
+      if (request.method === "GET" && url.pathname === "/entries") {
+        return Response.json(this.#listEntries(url.searchParams.get("path")));
+      }
+      if (request.method === "GET" && url.pathname === "/files") {
+        return Response.json(this.#readFile(url.searchParams.get("path")));
+      }
+      return jsonError(404, "Filesystem operation was not found");
+    } catch (error) {
+      if (error instanceof FilesystemRequestError) {
+        return jsonError(
+          error.status,
+          error.message,
+          error.code,
+          error.retryable,
+        );
+      }
+      console.error("FilesystemObject request failed", error);
+      return jsonError(500, "Filesystem operation failed");
+    }
+  }
+
+  #initializeFilesystem() {
+    this.ctx.storage.sql.exec(
+      `INSERT OR IGNORE INTO filesystem_checkpoint_meta
+        (singleton, checkpoint_revision)
+       VALUES (1, 0)`,
+    );
+    const meta = this.ctx.storage.sql
+      .exec("SELECT revision FROM filesystem_meta WHERE singleton = 1")
+      .toArray();
+    if (meta.length !== 0) return;
+
+    const now = Date.now();
+    this.ctx.storage.transactionSync((storage) => {
+      storage.sql.exec(
+        `INSERT INTO filesystem_meta
+          (singleton, revision, logical_bytes, entry_count)
+         VALUES (1, 0, 0, 3)`,
+      );
+      for (const [path, parentPath, name] of [
+        ["/", null, ""],
+        ["/workspace", "/", "workspace"],
+        ["/.gea", "/", ".gea"],
+      ]) {
+        storage.sql.exec(
+          `INSERT INTO filesystem_entries
+            (path, parent_path, name, kind, content, sha256, size_bytes,
+             created_at_ms, modified_at_ms, revision)
+           VALUES (?, ?, ?, 'directory', NULL, NULL, 0, ?, ?, 0)`,
+          path,
+          parentPath,
+          name,
+          now,
+          now,
+        );
+      }
+    });
+  }
+
+  #inspect() {
+    const meta = readMeta(this.ctx.storage);
+    return {
+      revision: meta.revision,
+      logicalBytes: meta.logical_bytes,
+      entryCount: meta.entry_count,
+    };
+  }
+
+  async #applyBatch(input) {
+    const batch = parseBatch(input);
+    const preparedOperations = [];
+    let preparedInlineBytes = 0;
+    for (const operation of batch.operations) {
+      if (operation.type === "createDirectory") {
+        preparedOperations.push(operation);
+        continue;
+      }
+      const content = decodeBase64(operation.contentBase64);
+      if (content.byteLength > MAX_INLINE_FILE_BYTES) {
+        throw new FilesystemRequestError(
+          413,
+          `Inline file content exceeds ${MAX_INLINE_FILE_BYTES} bytes`,
+        );
+      }
+      preparedInlineBytes += content.byteLength;
+      if (preparedInlineBytes > MAX_INLINE_BYTES_PER_OBJECT) {
+        throw new FilesystemRequestError(
+          413,
+          `Batch inline content exceeds ${MAX_INLINE_BYTES_PER_OBJECT} bytes`,
+        );
+      }
+      preparedOperations.push({
+        ...operation,
+        content,
+        sha256: await sha256(content),
+      });
+    }
+
+    const requestHash = await sha256(
+      new TextEncoder().encode(JSON.stringify(batch)),
+    );
+    const prior = this.ctx.storage.sql
+      .exec(
+        `SELECT request_hash, result_json
+           FROM filesystem_mutations
+          WHERE mutation_id = ?`,
+        batch.mutationId,
+      )
+      .toArray();
+    if (prior.length !== 0) return replayMutation(prior[0], requestHash);
+
+    return this.ctx.storage.transactionSync((storage) => {
+      const replay = storage.sql
+        .exec(
+          `SELECT request_hash, result_json
+             FROM filesystem_mutations
+            WHERE mutation_id = ?`,
+          batch.mutationId,
+        )
+        .toArray();
+      if (replay.length !== 0) return replayMutation(replay[0], requestHash);
+
+      const meta = readMeta(storage);
+      if (meta.revision !== batch.expectedRevision) {
+        throw new FilesystemRequestError(
+          409,
+          `Expected filesystem revision ${batch.expectedRevision}, current revision is ${meta.revision}`,
+        );
+      }
+
+      const nextRevision = meta.revision + 1;
+      const changes = [];
+      let logicalBytes = meta.logical_bytes;
+      let entryCount = meta.entry_count;
+      const now = Date.now();
+
+      for (const [sequence, operation] of preparedOperations.entries()) {
+        const parentPath = parentOf(operation.path);
+        requireDirectory(storage, parentPath);
+
+        if (operation.type === "createDirectory") {
+          requireNewPath(storage, operation.path);
+          requireDirectoryCapacity(storage, parentPath);
+          if (entryCount >= MAX_ENTRIES_PER_OBJECT) {
+            throw new FilesystemRequestError(
+              413,
+              `Filesystem contains the maximum ${MAX_ENTRIES_PER_OBJECT} entries`,
+            );
+          }
+          storage.sql.exec(
+            `INSERT INTO filesystem_entries
+              (path, parent_path, name, kind, content, sha256, size_bytes,
+               created_at_ms, modified_at_ms, revision)
+             VALUES (?, ?, ?, 'directory', NULL, NULL, 0, ?, ?, ?)`,
+            operation.path,
+            parentPath,
+            basename(operation.path),
+            now,
+            now,
+            nextRevision,
+          );
+          entryCount += 1;
+        } else {
+          const existing = storage.sql
+            .exec(
+              `SELECT kind, size_bytes
+                 FROM filesystem_entries
+                WHERE path = ?`,
+              operation.path,
+            )
+            .toArray();
+          if (existing.length !== 0 && existing[0].kind !== "file") {
+            throw new FilesystemRequestError(
+              409,
+              `A directory already exists at ${operation.path}`,
+            );
+          }
+          if (existing.length === 0) {
+            requireDirectoryCapacity(storage, parentPath);
+            if (entryCount >= MAX_ENTRIES_PER_OBJECT) {
+              throw new FilesystemRequestError(
+                413,
+                `Filesystem contains the maximum ${MAX_ENTRIES_PER_OBJECT} entries`,
+              );
+            }
+          }
+          const previousSize = existing[0]?.size_bytes ?? 0;
+          const nextLogicalBytes =
+            logicalBytes - previousSize + operation.content.byteLength;
+          if (nextLogicalBytes > MAX_INLINE_BYTES_PER_OBJECT) {
+            throw new FilesystemRequestError(
+              413,
+              `Filesystem inline content exceeds ${MAX_INLINE_BYTES_PER_OBJECT} bytes`,
+            );
+          }
+          if (existing.length === 0) {
+            storage.sql.exec(
+              `INSERT INTO filesystem_entries
+                (path, parent_path, name, kind, content, sha256, size_bytes,
+                 created_at_ms, modified_at_ms, revision)
+               VALUES (?, ?, ?, 'file', ?, ?, ?, ?, ?, ?)`,
+              operation.path,
+              parentPath,
+              basename(operation.path),
+              operation.content,
+              operation.sha256,
+              operation.content.byteLength,
+              now,
+              now,
+              nextRevision,
+            );
+            entryCount += 1;
+          } else {
+            storage.sql.exec(
+              `UPDATE filesystem_entries
+                  SET content = ?, sha256 = ?, size_bytes = ?, modified_at_ms = ?,
+                      revision = ?
+                WHERE path = ?`,
+              operation.content,
+              operation.sha256,
+              operation.content.byteLength,
+              now,
+              nextRevision,
+              operation.path,
+            );
+          }
+          logicalBytes = nextLogicalBytes;
+        }
+
+        const kind =
+          operation.type === "createDirectory" ? "directory" : "file";
+        const change = {
+          operation: operation.type,
+          path: operation.path,
+          kind,
+        };
+        changes.push(change);
+        storage.sql.exec(
+          `INSERT INTO filesystem_changes
+            (revision, sequence, operation, path, kind)
+           VALUES (?, ?, ?, ?, ?)`,
+          nextRevision,
+          sequence,
+          change.operation,
+          change.path,
+          change.kind,
+        );
+      }
+
+      storage.sql.exec(
+        `UPDATE filesystem_meta
+            SET revision = ?, logical_bytes = ?, entry_count = ?
+          WHERE singleton = 1`,
+        nextRevision,
+        logicalBytes,
+        entryCount,
+      );
+      const result = {
+        revision: nextRevision,
+        logicalBytes,
+        changes,
+      };
+      storage.sql.exec(
+        `INSERT INTO filesystem_mutations
+          (mutation_id, request_hash, applied_revision, result_json)
+         VALUES (?, ?, ?, ?)`,
+        batch.mutationId,
+        requestHash,
+        nextRevision,
+        JSON.stringify(result),
+      );
+      return result;
+    });
+  }
+
+  async #invoke(input) {
+    const invocation = parseInvocation(input);
+    let result;
+    switch (invocation.operation) {
+      case "inspect":
+        result = this.#inspect();
+        break;
+      case "inspectCheckpoints":
+        result = this.#inspectCheckpoints();
+        break;
+      case "initializeMount":
+        result = await this.#initializeMount(invocation);
+        break;
+      case "listMounts":
+        result = this.#listMounts();
+        break;
+      case "getMount":
+        result = this.#getMount(invocation.input);
+        break;
+      case "beginCheckpointUpload":
+        result = this.#beginCheckpointUpload(invocation.input);
+        break;
+      case "appendCheckpointUpload":
+        result = this.#appendCheckpointUpload(invocation.input);
+        break;
+      case "commitCheckpoint":
+        result = await this.#commitCheckpoint(invocation);
+        break;
+      case "getCheckpoint":
+        result = this.#getCheckpoint(invocation.input);
+        break;
+      case "readCheckpointBlobRange":
+        result = this.#readCheckpointBlobRange(invocation.input);
+        break;
+      case "beginDirectCheckpointUpload":
+      case "abortDirectCheckpointUpload":
+      case "getDirectCheckpointDownload":
+        throw new FilesystemRequestError(
+          501,
+          "Direct checkpoint transfer is not supported by the Filesystem System Worker",
+          "UNSUPPORTED",
+        );
+      default:
+        throw new FilesystemRequestError(
+          404,
+          `Filesystem operation was not found: ${invocation.operation}`,
+          "UNSUPPORTED",
+        );
+    }
+    return {
+      protocolVersion: PROTOCOL_VERSION,
+      objectId: invocation.objectId,
+      epoch: 1,
+      result,
+    };
+  }
+
+  #inspectCheckpoints() {
+    const revision = readCheckpointRevision(this.ctx.storage);
+    return {
+      checkpointRevision: revision,
+      latestCheckpoint:
+        revision === 0 ? null : readCheckpoint(this.ctx.storage, revision),
+      maxCheckpointImageBytes: MAX_CHECKPOINT_IMAGE_BYTES,
+      maxCheckpointManifestBytes: MAX_CHECKPOINT_MANIFEST_BYTES,
+      maxCheckpointRecords: RETAINED_CHECKPOINTS,
+    };
+  }
+
+  #beginCheckpointUpload(input) {
+    const upload = parseCheckpointUpload(input);
+    this.ctx.storage.transactionSync((storage) => {
+      const staleUploads = storage.sql
+        .exec(
+          `SELECT upload_id
+             FROM filesystem_checkpoint_uploads
+            WHERE committed = 0 AND created_at_ms < ?`,
+          Date.now() - CHECKPOINT_UPLOAD_TTL_MS,
+        )
+        .toArray();
+      for (const stale of staleUploads) {
+        storage.sql.exec(
+          "DELETE FROM filesystem_checkpoint_blob_chunks WHERE blob_id = ?",
+          stale.upload_id,
+        );
+        storage.sql.exec(
+          "DELETE FROM filesystem_checkpoint_uploads WHERE upload_id = ?",
+          stale.upload_id,
+        );
+      }
+    });
+    const existing = this.ctx.storage.sql
+      .exec(
+        `SELECT kind, sha256, size_bytes
+           FROM filesystem_checkpoint_uploads
+          WHERE upload_id = ?`,
+        upload.uploadId,
+      )
+      .toArray();
+    if (existing.length !== 0) {
+      const row = existing[0];
+      if (
+        row.kind !== upload.kind ||
+        row.sha256 !== upload.sha256 ||
+        row.size_bytes !== upload.sizeBytes
+      ) {
+        throw new FilesystemRequestError(
+          409,
+          "Checkpoint upload ID already exists with different metadata",
+        );
+      }
+      return {
+        maxChunkBytes: MAX_CHECKPOINT_TRANSFER_CHUNK_BYTES,
+        sizeBytes: upload.sizeBytes,
+        uploadId: upload.uploadId,
+      };
+    }
+    const pending = this.ctx.storage.sql
+      .exec(
+        "SELECT COUNT(*) AS count FROM filesystem_checkpoint_uploads WHERE committed = 0",
+      )
+      .one();
+    if (pending.count >= MAX_PENDING_CHECKPOINT_UPLOADS) {
+      throw new FilesystemRequestError(
+        409,
+        `Filesystem has reached the ${MAX_PENDING_CHECKPOINT_UPLOADS}-upload limit`,
+      );
+    }
+    this.ctx.storage.sql.exec(
+      `INSERT INTO filesystem_checkpoint_uploads
+        (upload_id, kind, sha256, size_bytes, received_bytes,
+         sha256_state_json, committed, created_at_ms)
+       VALUES (?, ?, ?, ?, 0, ?, 0, ?)`,
+      upload.uploadId,
+      upload.kind,
+      upload.sha256,
+      upload.sizeBytes,
+      JSON.stringify(new Sha256State().toJSON()),
+      Date.now(),
+    );
+    return {
+      maxChunkBytes: MAX_CHECKPOINT_TRANSFER_CHUNK_BYTES,
+      sizeBytes: upload.sizeBytes,
+      uploadId: upload.uploadId,
+    };
+  }
+
+  #appendCheckpointUpload(input) {
+    const append = parseCheckpointAppend(input);
+    return this.ctx.storage.transactionSync((storage) => {
+      const rows = storage.sql
+        .exec(
+          `SELECT size_bytes, received_bytes, sha256_state_json, committed
+             FROM filesystem_checkpoint_uploads
+            WHERE upload_id = ?`,
+          append.uploadId,
+        )
+        .toArray();
+      if (rows.length === 0) {
+        throw new FilesystemRequestError(
+          404,
+          "Checkpoint upload was not found",
+        );
+      }
+      const upload = rows[0];
+      const end = append.offset + append.bytes.byteLength;
+      if (!Number.isSafeInteger(end) || end > upload.size_bytes) {
+        throw new FilesystemRequestError(
+          409,
+          "Checkpoint upload chunk exceeds its declared size",
+        );
+      }
+      if (upload.committed === 1) {
+        const replay = readUploadRange(
+          storage,
+          append.uploadId,
+          append.offset,
+          append.bytes.byteLength,
+        );
+        if (!equalBytes(replay, append.bytes)) {
+          throw new FilesystemRequestError(
+            409,
+            "Committed checkpoint upload bytes cannot be replaced",
+          );
+        }
+        return { receivedBytes: end, uploadId: append.uploadId };
+      }
+      if (upload.received_bytes !== append.offset) {
+        if (upload.received_bytes === end) {
+          const replay = readUploadRange(
+            storage,
+            append.uploadId,
+            append.offset,
+            append.bytes.byteLength,
+          );
+          if (equalBytes(replay, append.bytes)) {
+            return {
+              receivedBytes: end,
+              uploadId: append.uploadId,
+            };
+          }
+        }
+        throw new FilesystemRequestError(
+          409,
+          "Checkpoint upload chunks must be appended sequentially",
+        );
+      }
+      for (let offset = 0; offset < append.bytes.byteLength; ) {
+        const chunk = append.bytes.slice(offset, offset + MAX_SQL_BLOB_BYTES);
+        storage.sql.exec(
+          `INSERT INTO filesystem_checkpoint_blob_chunks
+            (blob_id, offset, content)
+           VALUES (?, ?, ?)`,
+          append.uploadId,
+          append.offset + offset,
+          chunk,
+        );
+        offset += chunk.byteLength;
+      }
+      const digest = Sha256State.fromJSON(JSON.parse(upload.sha256_state_json));
+      digest.update(append.bytes);
+      storage.sql.exec(
+        `UPDATE filesystem_checkpoint_uploads
+            SET received_bytes = ?, sha256_state_json = ?
+          WHERE upload_id = ?`,
+        end,
+        JSON.stringify(digest.toJSON()),
+        append.uploadId,
+      );
+      return { receivedBytes: end, uploadId: append.uploadId };
+    });
+  }
+
+  async #commitCheckpoint(invocation) {
+    const commit = parseCheckpointCommit(invocation);
+    const requestHash = await mutationHash(invocation);
+    const prior = this.ctx.storage.sql
+      .exec(
+        `SELECT request_hash, result_json
+           FROM filesystem_mutations
+          WHERE mutation_id = ?`,
+        invocation.mutationId,
+      )
+      .toArray();
+    if (prior.length !== 0) return replayMutation(prior[0], requestHash);
+
+    return this.ctx.storage.transactionSync((storage) => {
+      const replay = storage.sql
+        .exec(
+          `SELECT request_hash, result_json
+             FROM filesystem_mutations
+            WHERE mutation_id = ?`,
+          invocation.mutationId,
+        )
+        .toArray();
+      if (replay.length !== 0) return replayMutation(replay[0], requestHash);
+      const actualRevision = readCheckpointRevision(storage);
+      if (actualRevision !== commit.expectedCheckpointRevision) {
+        throw new FilesystemRequestError(
+          409,
+          `Workspace checkpoint revision conflict: expected ${commit.expectedCheckpointRevision}, actual ${actualRevision}`,
+        );
+      }
+      const duplicateId = storage.sql
+        .exec(
+          "SELECT 1 AS present FROM filesystem_checkpoints WHERE checkpoint_id = ?",
+          commit.checkpointId,
+        )
+        .toArray();
+      if (duplicateId.length !== 0) {
+        throw new FilesystemRequestError(
+          409,
+          "Workspace checkpoint ID already exists",
+        );
+      }
+      const image = requireCompleteUpload(storage, commit.image, "image");
+      const manifest = requireCompleteUpload(
+        storage,
+        commit.manifest,
+        "manifest",
+      );
+      const nextRevision = actualRevision + 1;
+      const createdAtMs = Date.now();
+      storage.sql.exec(
+        `INSERT INTO filesystem_checkpoints
+          (checkpoint_revision, parent_checkpoint_revision, checkpoint_id,
+           image_blob_id, image_sha256, image_size_bytes, manifest_blob_id,
+           manifest_sha256, manifest_size_bytes, created_at_ms)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        nextRevision,
+        actualRevision,
+        commit.checkpointId,
+        image.upload_id,
+        image.sha256,
+        image.size_bytes,
+        manifest.upload_id,
+        manifest.sha256,
+        manifest.size_bytes,
+        createdAtMs,
+      );
+      storage.sql.exec(
+        `UPDATE filesystem_checkpoint_meta
+            SET checkpoint_revision = ?
+          WHERE singleton = 1`,
+        nextRevision,
+      );
+      for (const upload of [image, manifest]) {
+        storage.sql.exec(
+          `UPDATE filesystem_checkpoint_uploads
+              SET committed = 1
+            WHERE upload_id = ?`,
+          upload.upload_id,
+        );
+      }
+      const retained = storage.sql
+        .exec(
+          `SELECT checkpoint_revision, image_blob_id, manifest_blob_id
+             FROM filesystem_checkpoints
+            ORDER BY checkpoint_revision DESC`,
+        )
+        .toArray();
+      for (const stale of retained.slice(RETAINED_CHECKPOINTS)) {
+        storage.sql.exec(
+          "DELETE FROM filesystem_checkpoint_blob_chunks WHERE blob_id IN (?, ?)",
+          stale.image_blob_id,
+          stale.manifest_blob_id,
+        );
+        storage.sql.exec(
+          "DELETE FROM filesystem_checkpoint_uploads WHERE upload_id IN (?, ?)",
+          stale.image_blob_id,
+          stale.manifest_blob_id,
+        );
+        storage.sql.exec(
+          "DELETE FROM filesystem_checkpoints WHERE checkpoint_revision = ?",
+          stale.checkpoint_revision,
+        );
+      }
+      const checkpoint = checkpointDescriptor({
+        checkpoint_revision: nextRevision,
+        parent_checkpoint_revision: actualRevision,
+        checkpoint_id: commit.checkpointId,
+        image_blob_id: image.upload_id,
+        image_sha256: image.sha256,
+        image_size_bytes: image.size_bytes,
+        manifest_blob_id: manifest.upload_id,
+        manifest_sha256: manifest.sha256,
+        manifest_size_bytes: manifest.size_bytes,
+        created_at_ms: createdAtMs,
+      });
+      const result = { checkpoint, checkpointRevision: nextRevision };
+      storage.sql.exec(
+        `INSERT INTO filesystem_mutations
+          (mutation_id, request_hash, applied_revision, result_json)
+         VALUES (?, ?, ?, ?)`,
+        invocation.mutationId,
+        requestHash,
+        nextRevision,
+        JSON.stringify(result),
+      );
+      return result;
+    });
+  }
+
+  #getCheckpoint(input) {
+    const requested = optionalNonNegativeInteger(
+      input?.checkpointRevision,
+      "checkpointRevision",
+    );
+    const current = readCheckpointRevision(this.ctx.storage);
+    const revision = requested ?? current;
+    if (revision === 0) {
+      throw new FilesystemRequestError(
+        404,
+        "Workspace checkpoint was not found",
+      );
+    }
+    return {
+      checkpoint: readCheckpoint(this.ctx.storage, revision),
+      checkpointRevision: current,
+    };
+  }
+
+  #readCheckpointBlobRange(input) {
+    const range = parseCheckpointRange(input);
+    const checkpoint = readCheckpointRow(
+      this.ctx.storage,
+      range.checkpointRevision,
+    );
+    const sha256 = checkpoint[`${range.kind}_sha256`];
+    const sizeBytes = checkpoint[`${range.kind}_size_bytes`];
+    const blobId = checkpoint[`${range.kind}_blob_id`];
+    if (range.offset >= sizeBytes) {
+      throw new FilesystemRequestError(
+        409,
+        "Workspace checkpoint range starts beyond EOF",
+      );
+    }
+    const length = Math.min(range.length, sizeBytes - range.offset);
+    const bytes = readCheckpointRange(
+      this.ctx.storage,
+      blobId,
+      range.offset,
+      length,
+    );
+    return {
+      checkpointRevision: range.checkpointRevision,
+      dataBase64: encodeBase64(bytes),
+      eof: range.offset + bytes.byteLength === sizeBytes,
+      kind: range.kind,
+      offset: range.offset,
+      sha256,
+      sizeBytes,
+    };
+  }
+
+  async #initializeMount(invocation) {
+    const mount = parseMount(invocation.input);
+    const requestHash = await mutationHash(invocation);
+    const prior = this.ctx.storage.sql
+      .exec(
+        `SELECT request_hash, result_json
+           FROM filesystem_mutations
+          WHERE mutation_id = ?`,
+        invocation.mutationId,
+      )
+      .toArray();
+    if (prior.length !== 0) return replayMutation(prior[0], requestHash);
+    return this.ctx.storage.transactionSync((storage) => {
+      const existingMutation = storage.sql
+        .exec(
+          `SELECT request_hash, result_json
+             FROM filesystem_mutations
+            WHERE mutation_id = ?`,
+          invocation.mutationId,
+        )
+        .toArray();
+      if (existingMutation.length !== 0) {
+        return replayMutation(existingMutation[0], requestHash);
+      }
+      const existing = storage.sql
+        .exec(
+          "SELECT content_id FROM filesystem_mounts WHERE mount = ?",
+          mount.mount,
+        )
+        .toArray();
+      const reused = existing[0]?.content_id === mount.contentId;
+      if (!reused) {
+        if (existing.length === 0) {
+          const count = storage.sql
+            .exec("SELECT COUNT(*) AS count FROM filesystem_mounts")
+            .one();
+          if (count.count >= MAX_MOUNTS) {
+            throw new FilesystemRequestError(
+              409,
+              `Filesystem has reached the ${MAX_MOUNTS}-mount limit`,
+            );
+          }
+        }
+        storage.sql.exec(
+          "DELETE FROM filesystem_mount_file_chunks WHERE mount = ?",
+          mount.mount,
+        );
+        storage.sql.exec(
+          "DELETE FROM filesystem_mount_files WHERE mount = ?",
+          mount.mount,
+        );
+        storage.sql.exec(
+          "DELETE FROM filesystem_mounts WHERE mount = ?",
+          mount.mount,
+        );
+        storage.sql.exec(
+          `INSERT INTO filesystem_mounts
+            (mount, content_id, mode, file_count, size_bytes, created_at_ms)
+           VALUES (?, ?, 'read-only', ?, ?, ?)`,
+          mount.mount,
+          mount.contentId,
+          mount.files.length,
+          mount.sizeBytes,
+          Date.now(),
+        );
+        for (const file of mount.files) {
+          storage.sql.exec(
+            `INSERT INTO filesystem_mount_files
+              (mount, path, size_bytes)
+             VALUES (?, ?, ?)`,
+            mount.mount,
+            file.path,
+            file.bytes.byteLength,
+          );
+          for (let offset = 0; offset < file.bytes.byteLength; ) {
+            const chunk = file.bytes.slice(offset, offset + MAX_SQL_BLOB_BYTES);
+            storage.sql.exec(
+              `INSERT INTO filesystem_mount_file_chunks
+                (mount, path, offset, content)
+               VALUES (?, ?, ?, ?)`,
+              mount.mount,
+              file.path,
+              offset,
+              chunk,
+            );
+            offset += chunk.byteLength;
+          }
+        }
+      }
+      const result = {
+        contentId: mount.contentId,
+        mode: "read-only",
+        mount: mount.mount,
+        reused,
+      };
+      storage.sql.exec(
+        `INSERT INTO filesystem_mutations
+          (mutation_id, request_hash, applied_revision, result_json)
+         VALUES (?, ?, ?, ?)`,
+        invocation.mutationId,
+        requestHash,
+        readMeta(storage).revision,
+        JSON.stringify(result),
+      );
+      return result;
+    });
+  }
+
+  #listMounts() {
+    const mounts = this.ctx.storage.sql
+      .exec(
+        `SELECT mount, content_id, mode, file_count, size_bytes
+           FROM filesystem_mounts
+          ORDER BY mount`,
+      )
+      .toArray()
+      .map((mount) => ({
+        contentId: mount.content_id,
+        fileCount: mount.file_count,
+        mode: mount.mode,
+        mount: mount.mount,
+        sizeBytes: mount.size_bytes,
+      }));
+    return { mounts };
+  }
+
+  #getMount(input) {
+    const mount = parseMountName(input?.mount);
+    const rows = this.ctx.storage.sql
+      .exec(
+        `SELECT content_id, mode
+           FROM filesystem_mounts
+          WHERE mount = ?`,
+        mount,
+      )
+      .toArray();
+    if (rows.length === 0) {
+      throw new FilesystemRequestError(404, `Mount does not exist: ${mount}`);
+    }
+    const files = this.ctx.storage.sql
+      .exec(
+        `SELECT path, size_bytes
+           FROM filesystem_mount_files
+          WHERE mount = ?
+          ORDER BY path`,
+        mount,
+      )
+      .toArray()
+      .map((file) => ({
+        dataBase64: encodeBase64(
+          readMountFile(this.ctx.storage, mount, file.path, file.size_bytes),
+        ),
+        path: file.path,
+      }));
+    return {
+      contentId: rows[0].content_id,
+      files,
+      mode: rows[0].mode,
+      mount,
+    };
+  }
+
+  #listEntries(rawPath) {
+    const path = parsePath(rawPath, "path");
+    requireDirectory(this.ctx.storage, path);
+    const entries = this.ctx.storage.sql
+      .exec(
+        `SELECT path, name, kind, size_bytes, sha256, modified_at_ms, revision
+           FROM filesystem_entries
+          WHERE parent_path = ?
+          ORDER BY name ASC`,
+        path,
+      )
+      .toArray()
+      .map((entry) => ({
+        path: entry.path,
+        name: entry.name,
+        kind: entry.kind,
+        sizeBytes: entry.size_bytes,
+        sha256: entry.sha256,
+        modifiedAtMs: entry.modified_at_ms,
+        revision: entry.revision,
+      }));
+    return { revision: readMeta(this.ctx.storage).revision, entries };
+  }
+
+  #readFile(rawPath) {
+    const path = parsePath(rawPath, "path");
+    const rows = this.ctx.storage.sql
+      .exec(
+        `SELECT content, sha256, size_bytes, modified_at_ms, revision
+           FROM filesystem_entries
+          WHERE path = ? AND kind = 'file'`,
+        path,
+      )
+      .toArray();
+    if (rows.length === 0) {
+      throw new FilesystemRequestError(404, `File does not exist: ${path}`);
+    }
+    const file = rows[0];
+    return {
+      path,
+      contentBase64: encodeBase64(new Uint8Array(file.content)),
+      sha256: file.sha256,
+      sizeBytes: file.size_bytes,
+      modifiedAtMs: file.modified_at_ms,
+      revision: file.revision,
+    };
+  }
+}
+
+export default {
+  async fetch(request, env) {
+    try {
+      const url = new URL(request.url);
+      const match =
+        /^\/v1\/objects\/([^/]+)(\/(?:batches|entries|files|invoke))?$/.exec(
+          url.pathname,
+        );
+      if (!match) return jsonError(404, "Filesystem route was not found");
+
+      const allocationId = parseAllocationId(match[1]);
+      const objectPath = match[2] ?? "/";
+      const body = ["GET", "HEAD"].includes(request.method)
+        ? undefined
+        : await request.arrayBuffer();
+      if (objectPath === "/invoke") {
+        let invocation;
+        try {
+          invocation = JSON.parse(new TextDecoder().decode(body));
+        } catch {
+          throw new FilesystemRequestError(
+            400,
+            "Request body must be valid JSON",
+          );
+        }
+        if (invocation?.objectId !== allocationId) {
+          throw new FilesystemRequestError(
+            409,
+            "Invocation objectId does not match the routed allocation",
+          );
+        }
+      }
+      const objectUrl = new URL(
+        objectPath,
+        "https://filesystem.object.internal",
+      );
+      objectUrl.search = url.search;
+      return env.FILESYSTEM.getByName(allocationId).fetch(objectUrl, {
+        method: request.method,
+        headers: request.headers,
+        body,
+        signal: request.signal,
+      });
+    } catch (error) {
+      if (error instanceof FilesystemRequestError) {
+        return jsonError(
+          error.status,
+          error.message,
+          error.code,
+          error.retryable,
+        );
+      }
+      console.error("Filesystem System Worker request failed", error);
+      return jsonError(500, "Filesystem request failed");
+    }
+  },
+};
+
+function parseInvocation(input) {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) {
+    throw new FilesystemRequestError(400, "Invocation body must be an object");
+  }
+  if (input.protocolVersion !== PROTOCOL_VERSION) {
+    throw new FilesystemRequestError(
+      400,
+      `Unsupported filesystem protocol version: ${String(input.protocolVersion)}`,
+    );
+  }
+  if (input.class !== "filesystem") {
+    throw new FilesystemRequestError(
+      400,
+      "Invocation class must be filesystem",
+    );
+  }
+  const objectId = requireBoundedString(input.objectId, "objectId", 512);
+  if (!UUID_PATTERN.test(objectId)) {
+    throw new FilesystemRequestError(400, "objectId must be a UUID");
+  }
+  const operation = requireBoundedString(input.operation, "operation", 128);
+  requireBoundedString(input.requestId, "requestId", 256);
+  if (
+    !Number.isSafeInteger(input.deadlineMs) ||
+    input.deadlineMs <= 0 ||
+    input.deadlineMs > 15 * 60 * 1000
+  ) {
+    throw new FilesystemRequestError(
+      400,
+      "deadlineMs must be a positive safe integer no greater than 900000",
+    );
+  }
+  if (
+    input.input === null ||
+    typeof input.input !== "object" ||
+    Array.isArray(input.input)
+  ) {
+    throw new FilesystemRequestError(400, "Invocation input must be an object");
+  }
+  const mutationId =
+    input.mutationId === null || input.mutationId === undefined
+      ? null
+      : requireBoundedString(
+          input.mutationId,
+          "mutationId",
+          MAX_MUTATION_ID_BYTES,
+        );
+  if (
+    ["initializeMount", "commitCheckpoint"].includes(operation) &&
+    !mutationId
+  ) {
+    throw new FilesystemRequestError(400, `${operation} requires a mutationId`);
+  }
+  return {
+    deadlineMs: input.deadlineMs,
+    input: input.input,
+    mutationId,
+    objectId,
+    operation,
+    protocolVersion: input.protocolVersion,
+    requestId: input.requestId,
+  };
+}
+
+function parseCheckpointUpload(input) {
+  const kind = parseCheckpointKind(input?.kind);
+  const sizeBytes = positiveSafeInteger(input?.sizeBytes, "sizeBytes");
+  const maximum =
+    kind === "image"
+      ? MAX_CHECKPOINT_IMAGE_BYTES
+      : MAX_CHECKPOINT_MANIFEST_BYTES;
+  if (sizeBytes > maximum) {
+    throw new FilesystemRequestError(
+      413,
+      `${kind} checkpoint exceeds ${maximum} bytes`,
+    );
+  }
+  return {
+    kind,
+    sha256: parseSha256(input?.sha256, "sha256"),
+    sizeBytes,
+    uploadId: requireBoundedString(input?.uploadId, "uploadId", 256),
+  };
+}
+
+function parseCheckpointAppend(input) {
+  const bytes = decodeBase64(input?.dataBase64);
+  if (
+    bytes.byteLength === 0 ||
+    bytes.byteLength > MAX_CHECKPOINT_TRANSFER_CHUNK_BYTES
+  ) {
+    throw new FilesystemRequestError(
+      413,
+      `Checkpoint chunk must contain between 1 and ${MAX_CHECKPOINT_TRANSFER_CHUNK_BYTES} bytes`,
+    );
+  }
+  return {
+    bytes,
+    offset: nonNegativeSafeInteger(input?.offset, "offset"),
+    uploadId: requireBoundedString(input?.uploadId, "uploadId", 256),
+  };
+}
+
+function parseCheckpointCommit(invocation) {
+  const input = invocation.input;
+  if (
+    input.checkpoint === null ||
+    typeof input.checkpoint !== "object" ||
+    Array.isArray(input.checkpoint)
+  ) {
+    throw new FilesystemRequestError(400, "checkpoint must be an object");
+  }
+  const blob = (kind) => {
+    const value = input.checkpoint[kind];
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      throw new FilesystemRequestError(400, `${kind} must be an object`);
+    }
+    if (value.directUpload !== null && value.directUpload !== undefined) {
+      throw new FilesystemRequestError(
+        501,
+        "Direct checkpoint transfer is not supported by the Filesystem System Worker",
+        "UNSUPPORTED",
+      );
+    }
+    const sizeBytes = positiveSafeInteger(value.sizeBytes, `${kind}.sizeBytes`);
+    const maximum =
+      kind === "image"
+        ? MAX_CHECKPOINT_IMAGE_BYTES
+        : MAX_CHECKPOINT_MANIFEST_BYTES;
+    if (sizeBytes > maximum) {
+      throw new FilesystemRequestError(
+        413,
+        `${kind} checkpoint exceeds ${maximum} bytes`,
+      );
+    }
+    return {
+      sha256: parseSha256(value.sha256, `${kind}.sha256`),
+      sizeBytes,
+      uploadId: requireBoundedString(value.uploadId, `${kind}.uploadId`, 256),
+    };
+  };
+  return {
+    checkpointId: requireBoundedString(
+      input.checkpoint.checkpointId,
+      "checkpointId",
+      256,
+    ),
+    expectedCheckpointRevision: nonNegativeSafeInteger(
+      input.expectedCheckpointRevision,
+      "expectedCheckpointRevision",
+    ),
+    image: blob("image"),
+    manifest: blob("manifest"),
+  };
+}
+
+function parseCheckpointRange(input) {
+  const length = positiveSafeInteger(input?.length, "length");
+  if (length > MAX_CHECKPOINT_TRANSFER_CHUNK_BYTES) {
+    throw new FilesystemRequestError(
+      413,
+      `Checkpoint range exceeds ${MAX_CHECKPOINT_TRANSFER_CHUNK_BYTES} bytes`,
+    );
+  }
+  return {
+    checkpointRevision: positiveSafeInteger(
+      input?.checkpointRevision,
+      "checkpointRevision",
+    ),
+    kind: parseCheckpointKind(input?.kind),
+    length,
+    offset: nonNegativeSafeInteger(input?.offset, "offset"),
+  };
+}
+
+function parseCheckpointKind(value) {
+  if (value !== "image" && value !== "manifest") {
+    throw new FilesystemRequestError(
+      400,
+      "Checkpoint kind must be image or manifest",
+    );
+  }
+  return value;
+}
+
+function parseMount(input) {
+  const mount = parseMountName(input?.mount);
+  if (input?.mode !== "read-only") {
+    throw new FilesystemRequestError(400, "Mount mode must be read-only");
+  }
+  const contentId = parseSha256(input?.contentId, "contentId");
+  if (
+    !Array.isArray(input?.files) ||
+    input.files.length === 0 ||
+    input.files.length > MAX_MOUNT_FILES
+  ) {
+    throw new FilesystemRequestError(
+      400,
+      `Mount must contain between 1 and ${MAX_MOUNT_FILES} files`,
+    );
+  }
+  let sizeBytes = 0;
+  const files = input.files
+    .map((file) => {
+      if (file === null || typeof file !== "object" || Array.isArray(file)) {
+        throw new FilesystemRequestError(400, "Mount file must be an object");
+      }
+      const path = parseRelativePath(file.path, "mount file path");
+      const bytes = decodeBase64(file.dataBase64);
+      sizeBytes +=
+        16 + new TextEncoder().encode(path).byteLength + bytes.byteLength;
+      if (sizeBytes > MAX_MOUNT_BYTES) {
+        throw new FilesystemRequestError(
+          413,
+          `Mount content exceeds ${MAX_MOUNT_BYTES} bytes`,
+        );
+      }
+      return { bytes, path };
+    })
+    .sort((left, right) =>
+      compareBytes(
+        new TextEncoder().encode(left.path),
+        new TextEncoder().encode(right.path),
+      ),
+    );
+  if (new Set(files.map((file) => file.path)).size !== files.length) {
+    throw new FilesystemRequestError(409, "Mount file paths must be unique");
+  }
+  const digest = new Sha256State();
+  for (const file of files) {
+    const pathBytes = new TextEncoder().encode(file.path);
+    digest.update(unsigned64Bytes(pathBytes.byteLength));
+    digest.update(pathBytes);
+    digest.update(unsigned64Bytes(file.bytes.byteLength));
+    digest.update(file.bytes);
+  }
+  if (`sha256:${digest.digestHex()}` !== contentId) {
+    throw new FilesystemRequestError(
+      409,
+      "Mount contentId does not match the supplied files",
+    );
+  }
+  return { contentId, files, mount, sizeBytes };
+}
+
+function parseMountName(value) {
+  const mount = requireBoundedString(value, "mount", 256);
+  if (
+    !/^\/[A-Za-z0-9._-]+$/.test(mount) ||
+    ["/workspace", "/.gea", "/tmp"].includes(mount)
+  ) {
+    throw new FilesystemRequestError(
+      400,
+      "Mount must be one non-reserved absolute path segment",
+    );
+  }
+  return mount;
+}
+
+function parseRelativePath(value, field) {
+  const path = requireBoundedString(value, field, 4096);
+  if (path.startsWith("/") || path.includes("\\") || path.includes("\0")) {
+    throw new FilesystemRequestError(
+      400,
+      `${field} must be a relative POSIX path`,
+    );
+  }
+  if (
+    path
+      .split("/")
+      .some((segment) => segment === "" || segment === "." || segment === "..")
+  ) {
+    throw new FilesystemRequestError(400, `${field} must be canonical`);
+  }
+  return path;
+}
+
+function parseSha256(value, field) {
+  if (typeof value !== "string" || !/^sha256:[0-9a-f]{64}$/.test(value)) {
+    throw new FilesystemRequestError(
+      400,
+      `${field} must be a lowercase sha256 digest`,
+    );
+  }
+  return value;
+}
+
+function positiveSafeInteger(value, field) {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new FilesystemRequestError(
+      400,
+      `${field} must be a positive safe integer`,
+    );
+  }
+  return value;
+}
+
+function nonNegativeSafeInteger(value, field) {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new FilesystemRequestError(
+      400,
+      `${field} must be a non-negative safe integer`,
+    );
+  }
+  return value;
+}
+
+function optionalNonNegativeInteger(value, field) {
+  return value === undefined || value === null
+    ? null
+    : nonNegativeSafeInteger(value, field);
+}
+
+function readCheckpointRevision(storage) {
+  return storage.sql
+    .exec(
+      `SELECT checkpoint_revision
+         FROM filesystem_checkpoint_meta
+        WHERE singleton = 1`,
+    )
+    .one().checkpoint_revision;
+}
+
+function readCheckpoint(storage, revision) {
+  return checkpointDescriptor(readCheckpointRow(storage, revision));
+}
+
+function readCheckpointRow(storage, revision) {
+  const rows = storage.sql
+    .exec(
+      `SELECT checkpoint_revision, parent_checkpoint_revision, checkpoint_id,
+              image_blob_id, image_sha256, image_size_bytes,
+              manifest_blob_id, manifest_sha256, manifest_size_bytes,
+              created_at_ms
+         FROM filesystem_checkpoints
+        WHERE checkpoint_revision = ?`,
+      revision,
+    )
+    .toArray();
+  if (rows.length === 0) {
+    throw new FilesystemRequestError(
+      404,
+      `Workspace checkpoint revision was not found: ${revision}`,
+    );
+  }
+  return rows[0];
+}
+
+function checkpointDescriptor(row) {
+  return {
+    checkpointId: row.checkpoint_id,
+    checkpointRevision: row.checkpoint_revision,
+    createdAtMs: row.created_at_ms,
+    image: {
+      sha256: row.image_sha256,
+      sizeBytes: row.image_size_bytes,
+    },
+    manifest: {
+      sha256: row.manifest_sha256,
+      sizeBytes: row.manifest_size_bytes,
+    },
+    parentCheckpointRevision: row.parent_checkpoint_revision,
+  };
+}
+
+function requireCompleteUpload(storage, requested, kind) {
+  const rows = storage.sql
+    .exec(
+      `SELECT upload_id, kind, sha256, size_bytes, received_bytes,
+              sha256_state_json, committed
+         FROM filesystem_checkpoint_uploads
+        WHERE upload_id = ?`,
+      requested.uploadId,
+    )
+    .toArray();
+  if (rows.length === 0) {
+    throw new FilesystemRequestError(
+      409,
+      `${kind} checkpoint upload was not found`,
+    );
+  }
+  const upload = rows[0];
+  if (
+    upload.kind !== kind ||
+    upload.sha256 !== requested.sha256 ||
+    upload.size_bytes !== requested.sizeBytes ||
+    upload.received_bytes !== upload.size_bytes ||
+    upload.committed !== 0
+  ) {
+    throw new FilesystemRequestError(
+      409,
+      `${kind} checkpoint upload metadata is incomplete or inconsistent`,
+    );
+  }
+  const digest = Sha256State.fromJSON(
+    JSON.parse(upload.sha256_state_json),
+  ).digestHex();
+  if (`sha256:${digest}` !== upload.sha256) {
+    throw new FilesystemRequestError(
+      409,
+      `${kind} checkpoint upload digest does not match its declaration`,
+    );
+  }
+  return upload;
+}
+
+function readUploadRange(storage, uploadId, offset, length) {
+  return readChunkRange(
+    storage.sql
+      .exec(
+        `SELECT offset, content
+           FROM filesystem_checkpoint_blob_chunks
+          WHERE blob_id = ?
+            AND offset < ?
+            AND offset + length(content) > ?
+          ORDER BY offset`,
+        uploadId,
+        offset + length,
+        offset,
+      )
+      .toArray(),
+    offset,
+    length,
+  );
+}
+
+function readCheckpointRange(storage, blobId, offset, length) {
+  return readChunkRange(
+    storage.sql
+      .exec(
+        `SELECT offset, content
+           FROM filesystem_checkpoint_blob_chunks
+          WHERE blob_id = ?
+            AND offset < ?
+            AND offset + length(content) > ?
+          ORDER BY offset`,
+        blobId,
+        offset + length,
+        offset,
+      )
+      .toArray(),
+    offset,
+    length,
+  );
+}
+
+function readMountFile(storage, mount, path, sizeBytes) {
+  return readChunkRange(
+    storage.sql
+      .exec(
+        `SELECT offset, content
+           FROM filesystem_mount_file_chunks
+          WHERE mount = ? AND path = ?
+          ORDER BY offset`,
+        mount,
+        path,
+      )
+      .toArray(),
+    0,
+    sizeBytes,
+  );
+}
+
+function readChunkRange(rows, offset, length) {
+  const bytes = new Uint8Array(length);
+  let copied = 0;
+  const end = offset + length;
+  for (const row of rows) {
+    const content = new Uint8Array(row.content);
+    const rowEnd = row.offset + content.byteLength;
+    const start = Math.max(offset, row.offset);
+    const partEnd = Math.min(end, rowEnd);
+    if (partEnd <= start) continue;
+    const sourceStart = start - row.offset;
+    const destinationStart = start - offset;
+    bytes.set(
+      content.subarray(sourceStart, sourceStart + partEnd - start),
+      destinationStart,
+    );
+    copied += partEnd - start;
+  }
+  if (copied !== length) {
+    throw new FilesystemRequestError(
+      500,
+      "Filesystem blob chunks are incomplete",
+      "STORAGE_FAILED",
+      true,
+    );
+  }
+  return bytes;
+}
+
+function equalBytes(left, right) {
+  if (left.byteLength !== right.byteLength) return false;
+  return left.every((byte, index) => byte === right[index]);
+}
+
+function compareBytes(left, right) {
+  const length = Math.min(left.byteLength, right.byteLength);
+  for (let index = 0; index < length; index += 1) {
+    if (left[index] !== right[index]) return left[index] - right[index];
+  }
+  return left.byteLength - right.byteLength;
+}
+
+function unsigned64Bytes(value) {
+  const bytes = new Uint8Array(8);
+  const view = new DataView(bytes.buffer);
+  view.setUint32(0, Math.floor(value / 0x1_0000_0000), false);
+  view.setUint32(4, value >>> 0, false);
+  return bytes;
+}
+
+function parseBatch(input) {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) {
+    throw new FilesystemRequestError(400, "Batch body must be an object");
+  }
+  const expectedRevision = input.expectedRevision;
+  if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0) {
+    throw new FilesystemRequestError(
+      400,
+      "expectedRevision must be a non-negative safe integer",
+    );
+  }
+  const mutationId = requireBoundedString(
+    input.mutationId,
+    "mutationId",
+    MAX_MUTATION_ID_BYTES,
+  );
+  if (!Array.isArray(input.operations) || input.operations.length === 0) {
+    throw new FilesystemRequestError(400, "operations must not be empty");
+  }
+  if (input.operations.length > MAX_OPERATIONS_PER_BATCH) {
+    throw new FilesystemRequestError(
+      413,
+      `A batch may contain at most ${MAX_OPERATIONS_PER_BATCH} operations`,
+    );
+  }
+  const operations = input.operations.map((operation) => {
+    if (
+      operation === null ||
+      typeof operation !== "object" ||
+      Array.isArray(operation)
+    ) {
+      throw new FilesystemRequestError(400, "Each operation must be an object");
+    }
+    const path = parsePath(operation.path, "operation path");
+    if (path === "/" || path === "/workspace" || path === "/.gea") {
+      throw new FilesystemRequestError(
+        409,
+        `Reserved path cannot be changed: ${path}`,
+      );
+    }
+    if (operation.type === "createDirectory") {
+      return { type: "createDirectory", path };
+    }
+    if (operation.type === "writeFile") {
+      if (typeof operation.contentBase64 !== "string") {
+        throw new FilesystemRequestError(
+          400,
+          "writeFile contentBase64 must be a string",
+        );
+      }
+      return {
+        type: "writeFile",
+        path,
+        contentBase64: operation.contentBase64,
+      };
+    }
+    throw new FilesystemRequestError(
+      400,
+      `Unsupported filesystem operation: ${String(operation.type)}`,
+    );
+  });
+  return { expectedRevision, mutationId, operations };
+}
+
+function parseAllocationId(encoded) {
+  let allocationId;
+  try {
+    allocationId = decodeURIComponent(encoded);
+  } catch {
+    throw new FilesystemRequestError(
+      400,
+      "allocation id must be valid URL text",
+    );
+  }
+  requireBoundedString(allocationId, "allocation id", MAX_ALLOCATION_ID_BYTES);
+  if (allocationId.includes("/") || allocationId.includes("\0")) {
+    throw new FilesystemRequestError(
+      400,
+      "allocation id must not contain separators or NUL bytes",
+    );
+  }
+  return allocationId;
+}
+
+async function readJson(request) {
+  try {
+    return await request.json();
+  } catch {
+    throw new FilesystemRequestError(400, "Request body must be valid JSON");
+  }
+}
+
+function readMeta(storage) {
+  return storage.sql
+    .exec(
+      `SELECT revision, logical_bytes, entry_count
+         FROM filesystem_meta
+        WHERE singleton = 1`,
+    )
+    .one();
+}
+
+function requireDirectory(storage, path) {
+  const rows = storage.sql
+    .exec("SELECT kind FROM filesystem_entries WHERE path = ?", path)
+    .toArray();
+  if (rows.length === 0) {
+    throw new FilesystemRequestError(404, `Directory does not exist: ${path}`);
+  }
+  if (rows[0].kind !== "directory") {
+    throw new FilesystemRequestError(409, `Path is not a directory: ${path}`);
+  }
+}
+
+function requireNewPath(storage, path) {
+  const rows = storage.sql
+    .exec("SELECT 1 AS present FROM filesystem_entries WHERE path = ?", path)
+    .toArray();
+  if (rows.length !== 0) {
+    throw new FilesystemRequestError(409, `Path already exists: ${path}`);
+  }
+}
+
+function requireDirectoryCapacity(storage, path) {
+  const row = storage.sql
+    .exec(
+      "SELECT COUNT(*) AS entry_count FROM filesystem_entries WHERE parent_path = ?",
+      path,
+    )
+    .one();
+  if (row.entry_count >= MAX_ENTRIES_PER_DIRECTORY) {
+    throw new FilesystemRequestError(
+      413,
+      `Directory contains the maximum ${MAX_ENTRIES_PER_DIRECTORY} entries: ${path}`,
+    );
+  }
+}
+
+function replayMutation(row, requestHash) {
+  if (row.request_hash !== requestHash) {
+    throw new FilesystemRequestError(
+      409,
+      "mutationId was already used for a different batch",
+    );
+  }
+  return JSON.parse(row.result_json);
+}
+
+function parsePath(value, field) {
+  if (typeof value !== "string") {
+    throw new FilesystemRequestError(400, `${field} must be a string`);
+  }
+  if (value.length === 0 || !value.startsWith("/") || value.includes("\\")) {
+    throw new FilesystemRequestError(
+      400,
+      `${field} must be an absolute POSIX path`,
+    );
+  }
+  if (value.includes("\0")) {
+    throw new FilesystemRequestError(
+      400,
+      `${field} must not contain NUL bytes`,
+    );
+  }
+  const segments = value.split("/");
+  if (
+    value !== "/" &&
+    segments.some((segment, index) => {
+      return (
+        index !== 0 && (segment === "" || segment === "." || segment === "..")
+      );
+    })
+  ) {
+    throw new FilesystemRequestError(400, `${field} must be canonical`);
+  }
+  const encoded = new TextEncoder().encode(value);
+  if (encoded.byteLength > 4096) {
+    throw new FilesystemRequestError(413, `${field} exceeds 4096 bytes`);
+  }
+  return value;
+}
+
+function parentOf(path) {
+  const index = path.lastIndexOf("/");
+  return index === 0 ? "/" : path.slice(0, index);
+}
+
+function basename(path) {
+  return path.slice(path.lastIndexOf("/") + 1);
+}
+
+function requireBoundedString(value, field, maxBytes) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new FilesystemRequestError(
+      400,
+      `${field} must be a non-empty string`,
+    );
+  }
+  if (new TextEncoder().encode(value).byteLength > maxBytes) {
+    throw new FilesystemRequestError(413, `${field} exceeds ${maxBytes} bytes`);
+  }
+  return value;
+}
+
+function decodeBase64(value) {
+  if (
+    !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(
+      value,
+    )
+  ) {
+    throw new FilesystemRequestError(
+      400,
+      "contentBase64 must be canonical base64",
+    );
+  }
+  try {
+    const binary = atob(value);
+    const bytes = Uint8Array.from(binary, (character) =>
+      character.charCodeAt(0),
+    );
+    if (encodeBase64(bytes) !== value) {
+      throw new FilesystemRequestError(
+        400,
+        "contentBase64 must be canonical base64",
+      );
+    }
+    return bytes;
+  } catch {
+    throw new FilesystemRequestError(400, "contentBase64 must be valid base64");
+  }
+}
+
+function encodeBase64(bytes) {
+  let binary = "";
+  for (let offset = 0; offset < bytes.length; offset += 0x8000) {
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + 0x8000));
+  }
+  return btoa(binary);
+}
+
+async function sha256(bytes) {
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+  return Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join(
+    "",
+  );
+}
+
+async function mutationHash(invocation) {
+  const canonical = canonicalJson({
+    input: invocation.input,
+    operation: invocation.operation,
+  });
+  return sha256(new TextEncoder().encode(JSON.stringify(canonical)));
+}
+
+function canonicalJson(value) {
+  if (Array.isArray(value)) return value.map(canonicalJson);
+  if (value === null || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.keys(value)
+      .sort()
+      .map((key) => [key, canonicalJson(value[key])]),
+  );
+}
+
+class Sha256State {
+  static #constants = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1,
+    0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
+    0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786,
+    0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147,
+    0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+    0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b,
+    0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a,
+    0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
+    0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+  ]);
+
+  constructor(
+    words = [
+      0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c,
+      0x1f83d9ab, 0x5be0cd19,
+    ],
+    buffer = new Uint8Array(),
+    bytesHashed = 0,
+  ) {
+    this.words = new Uint32Array(words);
+    this.buffer = new Uint8Array(buffer);
+    this.bytesHashed = bytesHashed;
+  }
+
+  static fromJSON(value) {
+    if (
+      value === null ||
+      typeof value !== "object" ||
+      !Array.isArray(value.words) ||
+      value.words.length !== 8 ||
+      !Array.isArray(value.buffer) ||
+      value.buffer.length >= 64 ||
+      !Number.isSafeInteger(value.bytesHashed) ||
+      value.bytesHashed < 0
+    ) {
+      throw new FilesystemRequestError(
+        500,
+        "Checkpoint digest state is invalid",
+        "STORAGE_FAILED",
+      );
+    }
+    return new Sha256State(value.words, value.buffer, value.bytesHashed);
+  }
+
+  toJSON() {
+    return {
+      buffer: Array.from(this.buffer),
+      bytesHashed: this.bytesHashed,
+      words: Array.from(this.words),
+    };
+  }
+
+  update(bytes) {
+    const input = new Uint8Array(bytes);
+    const combined = new Uint8Array(this.buffer.byteLength + input.byteLength);
+    combined.set(this.buffer);
+    combined.set(input, this.buffer.byteLength);
+    let offset = 0;
+    while (offset + 64 <= combined.byteLength) {
+      this.#compress(combined.subarray(offset, offset + 64));
+      offset += 64;
+    }
+    this.buffer = combined.slice(offset);
+    this.bytesHashed += input.byteLength;
+    if (!Number.isSafeInteger(this.bytesHashed)) {
+      throw new FilesystemRequestError(413, "Digest input is too large");
+    }
+    return this;
+  }
+
+  digestHex() {
+    const clone = new Sha256State(this.words, this.buffer, this.bytesHashed);
+    const paddingBytes = (64 + 56 - ((clone.bytesHashed + 1) % 64)) % 64;
+    const trailer = new Uint8Array(1 + paddingBytes + 8);
+    trailer[0] = 0x80;
+    const bitLength = clone.bytesHashed * 8;
+    const view = new DataView(trailer.buffer);
+    view.setUint32(
+      trailer.byteLength - 8,
+      Math.floor(bitLength / 0x1_0000_0000),
+      false,
+    );
+    view.setUint32(trailer.byteLength - 4, bitLength >>> 0, false);
+    clone.update(trailer);
+    if (clone.buffer.byteLength !== 0) {
+      throw new FilesystemRequestError(
+        500,
+        "Checkpoint digest finalization failed",
+        "STORAGE_FAILED",
+      );
+    }
+    return Array.from(clone.words, (word) =>
+      word.toString(16).padStart(8, "0"),
+    ).join("");
+  }
+
+  #compress(block) {
+    const schedule = new Uint32Array(64);
+    const view = new DataView(block.buffer, block.byteOffset, block.byteLength);
+    for (let index = 0; index < 16; index += 1) {
+      schedule[index] = view.getUint32(index * 4, false);
+    }
+    for (let index = 16; index < 64; index += 1) {
+      const earlier = schedule[index - 15];
+      const later = schedule[index - 2];
+      const sigma0 =
+        rotateRight(earlier, 7) ^ rotateRight(earlier, 18) ^ (earlier >>> 3);
+      const sigma1 =
+        rotateRight(later, 17) ^ rotateRight(later, 19) ^ (later >>> 10);
+      schedule[index] =
+        (schedule[index - 16] + sigma0 + schedule[index - 7] + sigma1) >>> 0;
+    }
+    let [a, b, c, d, e, f, g, h] = this.words;
+    for (let index = 0; index < 64; index += 1) {
+      const sum1 = rotateRight(e, 6) ^ rotateRight(e, 11) ^ rotateRight(e, 25);
+      const choice = (e & f) ^ (~e & g);
+      const first =
+        (h +
+          sum1 +
+          choice +
+          Sha256State.#constants[index] +
+          schedule[index]) >>>
+        0;
+      const sum0 = rotateRight(a, 2) ^ rotateRight(a, 13) ^ rotateRight(a, 22);
+      const majority = (a & b) ^ (a & c) ^ (b & c);
+      const second = (sum0 + majority) >>> 0;
+      h = g;
+      g = f;
+      f = e;
+      e = (d + first) >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (first + second) >>> 0;
+    }
+    this.words[0] = (this.words[0] + a) >>> 0;
+    this.words[1] = (this.words[1] + b) >>> 0;
+    this.words[2] = (this.words[2] + c) >>> 0;
+    this.words[3] = (this.words[3] + d) >>> 0;
+    this.words[4] = (this.words[4] + e) >>> 0;
+    this.words[5] = (this.words[5] + f) >>> 0;
+    this.words[6] = (this.words[6] + g) >>> 0;
+    this.words[7] = (this.words[7] + h) >>> 0;
+  }
+}
+
+function rotateRight(value, count) {
+  return (value >>> count) | (value << (32 - count));
+}
+
+function jsonError(
+  status,
+  message,
+  code = status >= 500 ? "INTERNAL" : "INVALID_REQUEST",
+  retryable = status >= 500,
+) {
+  return Response.json({ error: { code, message, retryable } }, { status });
+}