@tdxvolt/volt-drive-mcp 0.0.0-stage → 0.1.1

package/src/drive-service.js

@@ -0,0 +1,1083 @@
+import { randomUUID } from "node:crypto";
+import { blobHash, looksBinary, toBytes } from "./bytes.js";
+import { ensureBlob, getBlob } from "./blob.js";
+import { waitForDocumentReady } from "./doc-state.js";
+import {
+  findEntry,
+  findFileAncestor,
+  hasChildren,
+  listDirectory,
+  pathKind,
+  planMove,
+  schemaToMetadata,
+  searchEntriesByPath
+} from "./drive-index.js";
+import { DriveSession } from "./drive-session.js";
+import {
+  DriveError,
+  conflict,
+  forbidden,
+  invalid,
+  notFound,
+  tooLarge
+} from "./errors.js";
+import { ancestorsOf, isWithin, normalizeDrivePath } from "./paths.js";
+import {
+  readLegacyArrayContent,
+  readTextContent,
+  writeTextContent
+} from "./sync-doc.js";
+
+export const DRIVE_RESOURCE_KIND = "volt:drive-database";
+
+const ATTR_INCLUDE = "volt:drive-database-include";
+const ATTR_EXCLUDE = "volt:drive-database-exclude";
+const ATTR_MAX_FILE_SIZE = "volt:drive-database-max-file-size";
+const ATTR_IGNORE_BINARY = "volt:drive-database-ignore-binary-files";
+const ATTR_INCLUDE_HIDDEN = "volt:drive-database-include-hidden";
+const ATTR_NO_COMPACTION = "volt:sync-database-no-compaction";
+const ATTR_VERSION_MODE = "volt:sync-database-version-mode";
+
+const MIB = 1024 * 1024;
+
+/** Defaults for every tunable limit; override via the constructor options. */
+export const DEFAULT_OPTIONS = Object.freeze({
+  /** Refuse every write tool. */
+  readOnly: false,
+  /** Only expose drives matching one of these ids, aliases or names (empty = all). */
+  drives: [],
+  /** Largest file that will be read or written. */
+  maxFileBytes: 10 * MIB,
+  /** Most characters returned from a single read. */
+  maxResponseChars: 100_000,
+  /** Most bytes of a binary file returned (base64) from a single read. */
+  maxBinaryReturnBytes: 1 * MIB,
+  /** How long to wait for a document to sync with the Volt. */
+  syncTimeoutMs: 30_000,
+  /** Content search skips text files larger than this. */
+  contentSearchMaxFileBytes: 512 * 1024,
+  /** Content search scans at most this many files per call. */
+  contentSearchMaxFiles: 500,
+  /** Content search stops after this long. */
+  contentSearchTimeoutMs: 60_000,
+  /** How long the list of drives is cached. */
+  driveListTtlMs: 30_000
+});
+
+const BASE64_RE = /^[A-Za-z0-9+/]*={0,2}$/;
+
+function attributeValue(resource, attributeId) {
+  const attributes = Array.isArray(resource?.attribute) ? resource.attribute : [];
+  for (const attribute of attributes) {
+    if (String(attribute?.attribute_id || "") !== attributeId) {
+      continue;
+    }
+    const value = Array.isArray(attribute?.value) ? attribute.value[0] : null;
+    if (!value || typeof value !== "object") {
+      return undefined;
+    }
+    for (const key of ["string", "integer", "real", "boolean"]) {
+      if (value[key] !== undefined) {
+        return value[key];
+      }
+    }
+  }
+  return undefined;
+}
+
+function booleanAttribute(resource, attributeId, defaultValue) {
+  const raw = attributeValue(resource, attributeId);
+  if (raw === undefined) {
+    return defaultValue;
+  }
+  if (typeof raw === "string") {
+    return ["true", "1", "yes"].includes(raw.trim().toLowerCase());
+  }
+  return Boolean(raw);
+}
+
+function positiveIntegerAttribute(resource, attributeId) {
+  const value = Number(attributeValue(resource, attributeId));
+  return Number.isFinite(value) && value > 0 ? Math.floor(value) : null;
+}
+
+function isoTime(ms) {
+  return typeof ms === "number" && Number.isFinite(ms) && ms > 0
+    ? new Date(ms).toISOString()
+    : null;
+}
+
+/** Run `task` over `items`, `limit` at a time; rejects after all have settled. */
+async function forEachLimited(items, limit, task) {
+  let next = 0;
+  let firstError = null;
+  const worker = async () => {
+    while (next < items.length) {
+      const item = items[next++];
+      try {
+        await task(item);
+      } catch (err) {
+        firstError ??= err;
+      }
+    }
+  };
+  await Promise.all(
+    Array.from({ length: Math.min(limit, items.length) }, worker)
+  );
+  if (firstError) {
+    throw firstError;
+  }
+}
+
+function formatVersionError(err) {
+  const message = err?.message ?? String(err);
+  if (
+    message.includes(ATTR_NO_COMPACTION) ||
+    message.includes("document versioning is not supported")
+  ) {
+    return new DriveError(
+      "File versions are disabled on this drive. Enable file versions in the drive settings.",
+      "unsupported"
+    );
+  }
+  return err instanceof Error ? err : new DriveError(message);
+}
+
+/**
+ * Everything the MCP tools can do with a VoltDrive, with no MCP dependency.
+ *
+ * Talks to the Volt through `volt-client-grpc` and mirrors drive structure
+ * through the Volt's Yjs sync, exactly as the VoltDrive web Explorer does. The
+ * client, Yjs and SyncProvider are injected so the service can be tested
+ * against an in-memory fake.
+ */
+export class DriveService {
+  /**
+   * @param {object} deps
+   * @param {object} deps.client - connected `VoltClient`.
+   * @param {object} deps.Y - the `yjs` module.
+   * @param {Function} deps.SyncProvider - Volt `SyncProvider` class.
+   * @param {() => Promise<void>} [deps.connect] - establishes the connection of
+   *   `client`. When given, it is run lazily before the first use and again
+   *   after a failure, so the service can be created (and an MCP server started)
+   *   before the Volt is reachable.
+   * @param {Partial<typeof DEFAULT_OPTIONS>} [deps.options]
+   * @param {{debug?: Function, info?: Function, error?: Function}} [deps.logger]
+   */
+  constructor({ client, Y, SyncProvider, connect, options = {}, logger }) {
+    this.options = { ...DEFAULT_OPTIONS, ...options };
+    this.ctx = { client, Y, SyncProvider, logger };
+    this.client = client;
+    this.logger = logger;
+    this.sessions = new Map();
+    this._connect = connect ?? null;
+    this._connecting = null;
+    this._driveList = null;
+    this._driveListAt = 0;
+  }
+
+  /**
+   * Make sure the Volt connection is up. Safe to call concurrently and often;
+   * a failed attempt is forgotten so that the next call tries again.
+   */
+  ensureConnected() {
+    if (!this._connect) {
+      return Promise.resolve();
+    }
+    if (!this._connecting) {
+      this._connecting = this._connect().catch((err) => {
+        this._connecting = null;
+        throw new DriveError(
+          `could not connect to the Volt: ${err?.message ?? String(err)}`,
+          "unavailable"
+        );
+      });
+    }
+    return this._connecting;
+  }
+
+  get readOnly() {
+    return this.options.readOnly;
+  }
+
+  _assertWritable() {
+    if (this.options.readOnly) {
+      throw forbidden("this connector is running in read-only mode");
+    }
+  }
+
+  // ---------------------------------------------------------------- drives
+
+  _allowed(resource) {
+    const allow = this.options.drives.map((item) => String(item).toLowerCase());
+    if (allow.length === 0) {
+      return true;
+    }
+    const names = [resource.id, resource.name, ...(resource.alias ?? [])]
+      .filter(Boolean)
+      .map((item) => String(item).toLowerCase());
+    return names.some((name) => allow.includes(name));
+  }
+
+  async _driveResources(force = false) {
+    await this.ensureConnected();
+    const fresh = Date.now() - this._driveListAt < this.options.driveListTtlMs;
+    if (!force && this._driveList && fresh) {
+      return this._driveList;
+    }
+    const response = await this.client.GetResources({
+      kind: [DRIVE_RESOURCE_KIND],
+      include_attributes: false,
+      include_protobuf: false
+    });
+    const resources = Array.isArray(response?.resource) ? response.resource : [];
+    this._driveList = resources
+      .filter((resource) => resource?.id)
+      .filter((resource) => this._allowed(resource));
+    this._driveListAt = Date.now();
+    return this._driveList;
+  }
+
+  /** The drives this connector may use. */
+  async listDrives() {
+    const resources = await this._driveResources(true);
+    return resources
+      .map((resource) => ({
+        id: String(resource.id),
+        name: String(resource.name || resource.id),
+        aliases: (resource.alias ?? []).map(String).filter(Boolean)
+      }))
+      .sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  async _resolveDrive(driveRef) {
+    const ref = String(driveRef ?? "").trim();
+    if (!ref) {
+      throw invalid("drive is required; use list_drives to see the available drives");
+    }
+    const lower = ref.toLowerCase();
+
+    let resources = await this._driveResources();
+    const find = (list) => {
+      const byId = list.filter(
+        (r) => String(r.id) === ref || (r.alias ?? []).includes(ref)
+      );
+      if (byId.length === 1) {
+        return byId;
+      }
+      return list.filter((r) => String(r.name || "").toLowerCase() === lower);
+    };
+
+    let matches = find(resources);
+    if (matches.length === 0) {
+      // The cache may be stale (a drive was created since it was filled).
+      resources = await this._driveResources(true);
+      matches = find(resources);
+    }
+
+    if (matches.length === 0) {
+      throw notFound(
+        `no drive matches '${ref}'; use list_drives to see the available drives`
+      );
+    }
+    if (matches.length > 1) {
+      const options = matches.map((r) => `${r.name} (${r.id})`).join(", ");
+      throw invalid(`'${ref}' matches more than one drive: ${options}; use the id`);
+    }
+    return matches[0];
+  }
+
+  async _session(driveRef) {
+    const resource = await this._resolveDrive(driveRef);
+    let session = this.sessions.get(resource.id);
+    if (!session) {
+      session = new DriveSession(this.ctx, resource, {
+        readOnly: this.options.readOnly,
+        syncTimeoutMs: this.options.syncTimeoutMs
+      });
+      this.sessions.set(resource.id, session);
+    }
+    try {
+      await session.ensureReady();
+    } catch (err) {
+      this.sessions.delete(resource.id);
+      throw err;
+    }
+    return session;
+  }
+
+  async _driveWithAttributes(driveId) {
+    const response = await this.client.GetResource({
+      resource_id: driveId,
+      include_attributes: true
+    });
+    return response?.resource ?? {};
+  }
+
+  /** Summary and settings of a drive, and the state of its local sync. */
+  async getDriveStatus(driveRef) {
+    const session = await this._session(driveRef);
+    const resource = await this._driveWithAttributes(session.id);
+    const entries = session.entries;
+
+    const status = {
+      id: session.id,
+      name: String(resource.name || session.resource.name || session.id),
+      aliases: (resource.alias ?? session.resource.alias ?? []).map(String),
+      fileCount: entries.length,
+      folderCount: session.folders.length,
+      totalBytes: entries.reduce((sum, entry) => sum + entry.size, 0),
+      metadataSynced: session.metaSynced,
+      writable: !this.options.readOnly,
+      settings: {
+        includePatterns: String(attributeValue(resource, ATTR_INCLUDE) ?? ""),
+        excludePatterns: String(attributeValue(resource, ATTR_EXCLUDE) ?? ""),
+        maxFileSizeBytes: positiveIntegerAttribute(resource, ATTR_MAX_FILE_SIZE),
+        includeBinaryFiles: !booleanAttribute(resource, ATTR_IGNORE_BINARY, true),
+        includeHidden: booleanAttribute(resource, ATTR_INCLUDE_HIDDEN, false),
+        versioningEnabled: booleanAttribute(resource, ATTR_NO_COMPACTION, false),
+        versionMode: String(attributeValue(resource, ATTR_VERSION_MODE) ?? "")
+      },
+      localSync: await this._instanceStatus(session.id)
+    };
+    return status;
+  }
+
+  /**
+   * State of any VoltDrive daemon instance hosted by the connected Volt
+   * (null when the Volt cannot say).
+   */
+  _instanceStatus(synapseId, timeoutMs = 3_000) {
+    return new Promise((resolve) => {
+      let call = null;
+      let settled = false;
+      const done = (value) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timer);
+        try {
+          call?.write({ stop: true });
+          call?.end();
+        } catch {
+          // stream already closed
+        }
+        resolve(value);
+      };
+      const timer = setTimeout(() => done(null), timeoutMs);
+
+      try {
+        call = this.client.WatchDriveInstanceStatus({
+          start: { synapse_id: synapseId }
+        });
+      } catch {
+        done(null);
+        return;
+      }
+
+      call.on("data", (payload) => {
+        const update = payload?.update;
+        if (!update) {
+          return;
+        }
+        done({
+          state: String(update.state ?? "DRIVE_INSTANCE_STATE_ABSENT")
+            .replace("DRIVE_INSTANCE_STATE_", "")
+            .toLowerCase(),
+          totalCount: Number(update.total_count ?? 0),
+          completedCount: Number(update.completed_count ?? 0)
+        });
+      });
+      call.on("error", () => done(null));
+      call.on("end", () => done(null));
+    });
+  }
+
+  // ---------------------------------------------------------------- reading
+
+  /** List a folder of a drive. */
+  async listDirectory(driveRef, rawPath, { recursive = false, maxEntries = 500 } = {}) {
+    const path = normalizeDrivePath(rawPath, { allowRoot: true });
+    const session = await this._session(driveRef);
+    const { entries, folders } = session;
+
+    const kind = pathKind(entries, folders, path);
+    if (kind === null) {
+      throw notFound(`no such folder: '${path}'`);
+    }
+    if (kind === "file") {
+      throw invalid(`'${path}' is a file; use read_file`);
+    }
+
+    const items = listDirectory(entries, folders, path, { recursive });
+    const truncated = items.length > maxEntries;
+    return {
+      path,
+      total: items.length,
+      truncated,
+      items: items.slice(0, maxEntries).map((item) => ({
+        ...item,
+        modified: isoTime(item.modified)
+      }))
+    };
+  }
+
+  _requireFile(session, path) {
+    const entry = findEntry(session.entries, path);
+    if (entry) {
+      return entry;
+    }
+    const kind = pathKind(session.entries, session.folders, path);
+    if (kind === "directory") {
+      throw invalid(`'${path}' is a folder; use list_directory`);
+    }
+    throw notFound(`no such file: '${path}'`);
+  }
+
+  /**
+   * Read a file. Text is returned as a string; binary files only when
+   * `encoding` is "base64".
+   *
+   * `offset` and `limit` count characters for text, and bytes for base64.
+   */
+  async readFile(driveRef, rawPath, { offset = 0, limit, encoding = "utf-8" } = {}) {
+    const path = normalizeDrivePath(rawPath);
+    const session = await this._session(driveRef);
+    const entry = this._requireFile(session, path);
+    const { maxFileBytes, maxResponseChars, maxBinaryReturnBytes } = this.options;
+
+    if (entry.size > maxFileBytes) {
+      throw tooLarge(
+        `'${path}' is ${entry.size} bytes, which exceeds the ${maxFileBytes} byte limit`
+      );
+    }
+    if (!Number.isInteger(offset) || offset < 0) {
+      throw invalid("offset must be a non-negative integer");
+    }
+
+    const base = {
+      path,
+      size: entry.size,
+      binary: entry.binary,
+      modified: isoTime(entry.modified)
+    };
+
+    if (entry.binary && encoding !== "base64") {
+      return {
+        ...base,
+        content: null,
+        note: 'binary file: call read_file again with encoding "base64" to fetch its bytes'
+      };
+    }
+
+    await waitForDocumentReady(this.client, session.id, entry.documentId, {
+      timeoutMs: this.options.syncTimeoutMs
+    });
+
+    if (encoding === "base64") {
+      const bytes = await this._readBytes(session, entry);
+      const cap = Math.min(limit ?? maxBinaryReturnBytes, maxBinaryReturnBytes);
+      const slice = bytes.subarray(offset, offset + cap);
+      return {
+        ...base,
+        encoding: "base64",
+        offset,
+        returned: slice.length,
+        total: bytes.length,
+        truncated: offset + slice.length < bytes.length,
+        content: Buffer.from(slice).toString("base64")
+      };
+    }
+
+    const text = await readTextContent(this.ctx, session.id, entry.documentId, {
+      timeoutMs: this.options.syncTimeoutMs
+    });
+    const cap = Math.min(limit ?? maxResponseChars, maxResponseChars);
+    const slice = text.slice(offset, offset + cap);
+    return {
+      ...base,
+      encoding: "utf-8",
+      offset,
+      returned: slice.length,
+      total: text.length,
+      truncated: offset + slice.length < text.length,
+      content: slice
+    };
+  }
+
+  async _readBytes(session, entry) {
+    if (entry.schemaType === "blob") {
+      return getBlob(this.client, session.id, entry.contentHash, entry.documentId, {
+        maxBytes: this.options.maxFileBytes
+      });
+    }
+    if (entry.schemaType === "array") {
+      return readLegacyArrayContent(this.ctx, session.id, entry.documentId, {
+        timeoutMs: this.options.syncTimeoutMs
+      });
+    }
+    const text = await readTextContent(this.ctx, session.id, entry.documentId, {
+      timeoutMs: this.options.syncTimeoutMs
+    });
+    return new TextEncoder().encode(text);
+  }
+
+  /**
+   * Search a drive by file name (`namePattern`: substring or glob) and/or by
+   * text content (`contentQuery`: case-insensitive substring).
+   */
+  async searchFiles(
+    driveRef,
+    { namePattern = "", contentQuery = "", path: rawPath = "", maxResults = 50 } = {}
+  ) {
+    const folder = normalizeDrivePath(rawPath, { allowRoot: true });
+    const session = await this._session(driveRef);
+
+    const candidates = searchEntriesByPath(session.entries, namePattern, folder);
+
+    if (!contentQuery) {
+      const files = candidates.slice(0, maxResults).map((entry) => ({
+        path: entry.path,
+        size: entry.size,
+        modified: isoTime(entry.modified)
+      }));
+      return { files, total: candidates.length, truncated: candidates.length > maxResults };
+    }
+
+    return this._searchContent(session, candidates, contentQuery, maxResults);
+  }
+
+  async _searchContent(session, candidates, query, maxResults) {
+    const needle = query.toLowerCase();
+    const { contentSearchMaxFileBytes, contentSearchMaxFiles, contentSearchTimeoutMs } =
+      this.options;
+
+    const eligible = candidates.filter(
+      (entry) => !entry.binary && entry.size <= contentSearchMaxFileBytes
+    );
+    const scanList = eligible.slice(0, contentSearchMaxFiles);
+    const deadline = Date.now() + contentSearchTimeoutMs;
+
+    const matches = [];
+    let scanned = 0;
+    let unreadable = 0;
+    let stop = false;
+
+    await forEachLimited(scanList, 4, async (entry) => {
+      if (stop || Date.now() > deadline) {
+        stop = true;
+        return;
+      }
+      try {
+        await waitForDocumentReady(this.client, session.id, entry.documentId, {
+          timeoutMs: 5_000
+        });
+        const text = await readTextContent(this.ctx, session.id, entry.documentId, {
+          timeoutMs: 10_000
+        });
+        scanned++;
+        const lines = text.split(/\r?\n/);
+        for (let i = 0; i < lines.length; i++) {
+          if (lines[i].toLowerCase().includes(needle)) {
+            matches.push({
+              path: entry.path,
+              line: i + 1,
+              text: lines[i].length > 300 ? `${lines[i].slice(0, 300)}…` : lines[i]
+            });
+            if (matches.length >= maxResults * 4) {
+              // Enough to fill the result after sorting; stop reading more.
+              stop = true;
+              break;
+            }
+          }
+        }
+      } catch {
+        unreadable++;
+      }
+    });
+
+    matches.sort((a, b) => a.path.localeCompare(b.path) || a.line - b.line);
+    return {
+      matches: matches.slice(0, maxResults),
+      totalMatches: matches.length,
+      truncated: matches.length > maxResults || stop,
+      filesScanned: scanned,
+      filesSkipped: {
+        binary: candidates.filter((entry) => entry.binary).length,
+        tooLarge: candidates.filter(
+          (entry) => !entry.binary && entry.size > contentSearchMaxFileBytes
+        ).length,
+        overScanLimit: Math.max(0, eligible.length - scanList.length),
+        unreadable
+      }
+    };
+  }
+
+  // ---------------------------------------------------------------- writing
+
+  async _driveLimits(driveId) {
+    const resource = await this._driveWithAttributes(driveId);
+    const driveMax = positiveIntegerAttribute(resource, ATTR_MAX_FILE_SIZE);
+    return {
+      maxFileBytes: driveMax
+        ? Math.min(driveMax, this.options.maxFileBytes)
+        : this.options.maxFileBytes,
+      ignoreBinaryFiles: booleanAttribute(resource, ATTR_IGNORE_BINARY, true)
+    };
+  }
+
+  async _setMetadata(session, request) {
+    await this.client.SetSynapseDocumentMetadata({
+      synapse_id: session.id,
+      ...request
+    });
+  }
+
+  /**
+   * Create a file, or replace the content of an existing one when `overwrite`
+   * is set. `encoding` says how `content` is encoded: "utf-8" for text,
+   * "base64" for bytes.
+   */
+  async writeFile(driveRef, rawPath, { content, encoding = "utf-8", overwrite = false }) {
+    this._assertWritable();
+    const path = normalizeDrivePath(rawPath);
+
+    if (typeof content !== "string") {
+      throw invalid("content must be a string");
+    }
+
+    let bytes;
+    let text = null;
+    if (encoding === "base64") {
+      const compact = content.replace(/\s+/g, "");
+      if (!BASE64_RE.test(compact) || compact.length % 4 === 1) {
+        throw invalid("content is not valid base64");
+      }
+      bytes = Buffer.from(compact, "base64");
+    } else if (encoding === "utf-8") {
+      text = content;
+      bytes = Buffer.from(content, "utf8");
+    } else {
+      throw invalid(`unsupported encoding '${encoding}'`);
+    }
+
+    const session = await this._session(driveRef);
+    const limits = await this._driveLimits(session.id);
+    if (bytes.length > limits.maxFileBytes) {
+      throw tooLarge(
+        `content is ${bytes.length} bytes, which exceeds the ${limits.maxFileBytes} byte limit for this drive`
+      );
+    }
+
+    return session.exclusive(async () => {
+      const { entries, folders } = session;
+      const existing = findEntry(entries, path);
+
+      if (!existing && pathKind(entries, folders, path) === "directory") {
+        throw conflict(`'${path}' is a folder`);
+      }
+      const blocker = findFileAncestor(entries, path);
+      if (blocker) {
+        throw conflict(`cannot create '${path}': '${blocker}' is a file`);
+      }
+      if (existing && !overwrite) {
+        throw conflict(`'${path}' already exists; pass overwrite: true to replace it`);
+      }
+      if (existing?.schemaType === "array") {
+        throw conflict(
+          `'${path}' uses a legacy binary format that cannot be modified; delete it and create it again`
+        );
+      }
+
+      // An existing file keeps its kind; a new one is classified by content.
+      const binary = existing ? existing.binary : looksBinary(bytes);
+      if (!binary && looksBinary(bytes)) {
+        throw invalid(
+          `'${path}' is a text file but the content is binary; delete it and create it again`
+        );
+      }
+      if (binary && limits.ignoreBinaryFiles) {
+        throw forbidden(
+          "this drive ignores binary files; enable 'include binary files' in the drive settings to store them"
+        );
+      }
+
+      const documentId = existing?.documentId ?? randomUUID();
+      const json = JSON.stringify({ name: path, s: bytes.length });
+
+      if (binary) {
+        const hash = blobHash(bytes);
+        await ensureBlob(this.client, session.id, hash, bytes, documentId);
+        await this._setMetadata(session, {
+          document_id: documentId,
+          metadata: [{ name: "content", type: "blob" }],
+          json,
+          blob_hash: hash
+        });
+      } else {
+        const body = text ?? new TextDecoder().decode(bytes);
+        if (!existing) {
+          // Content first, so the listing never shows a file without its bytes.
+          if (body.length > 0) {
+            await writeTextContent(this.ctx, session.id, documentId, body, {
+              timeoutMs: this.options.syncTimeoutMs
+            });
+          }
+          await this._setMetadata(session, {
+            document_id: documentId,
+            metadata: [{ name: "content", type: "text" }],
+            json,
+            publish_hash: true
+          });
+        } else {
+          const changed = await writeTextContent(
+            this.ctx,
+            session.id,
+            documentId,
+            body,
+            { timeoutMs: this.options.syncTimeoutMs }
+          );
+          if (changed || existing.size !== bytes.length) {
+            await this._setMetadata(session, {
+              document_id: documentId,
+              metadata: schemaToMetadata(existing),
+              json
+            });
+          }
+        }
+      }
+
+      await session.addFolders(ancestorsOf(path));
+
+      await session.waitFor(() => {
+        const current = findEntry(session.entries, path);
+        return Boolean(current && current.size === bytes.length);
+      });
+
+      return {
+        path,
+        documentId,
+        size: bytes.length,
+        created: !existing,
+        binary
+      };
+    });
+  }
+
+  /** Create a folder (and any missing parents). Idempotent. */
+  async createFolder(driveRef, rawPath) {
+    this._assertWritable();
+    const path = normalizeDrivePath(rawPath);
+    const session = await this._session(driveRef);
+
+    return session.exclusive(async () => {
+      const { entries, folders } = session;
+      const kind = pathKind(entries, folders, path);
+      if (kind === "file") {
+        throw conflict(`'${path}' is a file`);
+      }
+      const blocker = findFileAncestor(entries, path);
+      if (blocker) {
+        throw conflict(`cannot create '${path}': '${blocker}' is a file`);
+      }
+      if (kind === "directory") {
+        return { path, created: false };
+      }
+
+      if (!(await session.addFolders([...ancestorsOf(path), path]))) {
+        throw forbidden("the folders list of this drive is read-only for the current identity");
+      }
+      await session.waitFor(() => session.folders.includes(path));
+      return { path, created: true };
+    });
+  }
+
+  /**
+   * Rename or move a file or folder to the new full path `to`. The destination
+   * must not exist; missing parent folders are created.
+   */
+  async movePath(driveRef, rawFrom, rawTo) {
+    this._assertWritable();
+    const from = normalizeDrivePath(rawFrom);
+    const to = normalizeDrivePath(rawTo);
+    const session = await this._session(driveRef);
+
+    return session.exclusive(async () => {
+      const { entries, folders } = session;
+      const sourceKind = pathKind(entries, folders, from);
+      if (sourceKind === null) {
+        throw notFound(`no such file or folder: '${from}'`);
+      }
+      if (from === to) {
+        throw invalid("source and destination are the same");
+      }
+      if (sourceKind === "directory" && isWithin(to, from)) {
+        throw invalid("cannot move a folder into itself");
+      }
+      if (pathKind(entries, folders, to) !== null) {
+        throw conflict(`'${to}' already exists`);
+      }
+      const blocker = findFileAncestor(entries, to);
+      if (blocker) {
+        throw conflict(`cannot move to '${to}': '${blocker}' is a file`);
+      }
+
+      const { rewrites, folderRenames } = planMove(entries, folders, from, to);
+      if (folderRenames.length > 0 && !session.foldersWritable) {
+        throw forbidden(
+          "the folders list of this drive is read-only for the current identity, so folders cannot be moved"
+        );
+      }
+
+      await forEachLimited(rewrites, 8, ({ entry, newPath }) =>
+        this._setMetadata(session, {
+          document_id: entry.documentId,
+          metadata: schemaToMetadata(entry),
+          json: JSON.stringify({ name: newPath, s: entry.size })
+        })
+      );
+
+      if (sourceKind === "directory" && session.foldersWritable) {
+        await session.mutateFolders((map) => {
+          for (const { from: oldPath, to: newPath } of folderRenames) {
+            map.delete(oldPath);
+            map.set(newPath, true);
+          }
+          for (const ancestor of [...ancestorsOf(to), to]) {
+            if (!map.has(ancestor)) {
+              map.set(ancestor, true);
+            }
+          }
+        });
+      } else {
+        await session.addFolders(ancestorsOf(to));
+      }
+
+      await session.waitFor(() =>
+        rewrites.every(({ entry, newPath }) => {
+          const moved = findEntry(session.entries, newPath);
+          return Boolean(moved && moved.documentId === entry.documentId);
+        })
+      );
+
+      return { from, to, movedFiles: rewrites.length };
+    });
+  }
+
+  /**
+   * Delete a file, or a folder and everything in it when `recursive`. Deleting
+   * a file leaves its containing folders in place.
+   */
+  async deletePath(driveRef, rawPath, { recursive = false } = {}) {
+    this._assertWritable();
+    const path = normalizeDrivePath(rawPath);
+    const session = await this._session(driveRef);
+
+    return session.exclusive(async () => {
+      const { entries, folders } = session;
+      const kind = pathKind(entries, folders, path);
+      if (kind === null) {
+        throw notFound(`no such file or folder: '${path}'`);
+      }
+
+      if (kind === "file") {
+        const entry = findEntry(entries, path);
+        await this.client.DeleteSynapseDocumentMetadata({
+          synapse_id: session.id,
+          document_id: entry.documentId
+        });
+        await session.waitFor(() => !findEntry(session.entries, path));
+        return { path, deletedFiles: 1 };
+      }
+
+      const doomed = entries.filter((entry) => isWithin(entry.path, path));
+      if (hasChildren(entries, folders, path) && !recursive) {
+        throw conflict(
+          `folder '${path}' is not empty (${doomed.length} file${doomed.length === 1 ? "" : "s"}); pass recursive: true to delete it and its contents`
+        );
+      }
+
+      await forEachLimited(doomed, 4, (entry) =>
+        this.client.DeleteSynapseDocumentMetadata({
+          synapse_id: session.id,
+          document_id: entry.documentId
+        })
+      );
+
+      const folderPaths = folders.filter((folder) => isWithin(folder, path));
+      let folderListUpdated = true;
+      if (folderPaths.length > 0) {
+        folderListUpdated = await session.removeFolders(folderPaths);
+      }
+
+      await session.waitFor(
+        () => !session.entries.some((entry) => isWithin(entry.path, path))
+      );
+
+      return {
+        path,
+        deletedFiles: doomed.length,
+        ...(folderListUpdated
+          ? {}
+          : {
+              warning:
+                "files were deleted but the folders list is read-only for the current identity, so empty folders may remain"
+            })
+      };
+    });
+  }
+
+  // ---------------------------------------------------------------- versions
+
+  /** Saved versions of a file, newest first. */
+  async listFileVersions(driveRef, rawPath, { limit = 50, offset = 0 } = {}) {
+    const path = normalizeDrivePath(rawPath);
+    const session = await this._session(driveRef);
+    const entry = this._requireFile(session, path);
+
+    let response;
+    try {
+      response = await this.client.ListSyncDocumentVersions({
+        database_id: session.id,
+        document_id: entry.documentId,
+        limit,
+        offset
+      });
+    } catch (err) {
+      throw formatVersionError(err);
+    }
+
+    const versions = (response?.versions ?? []).map((version) => ({
+      versionId: String(version.version_id),
+      timestamp: isoTime(Number(version.timestamp)),
+      identity: String(version.identity ?? ""),
+      label: String(version.label ?? ""),
+      contentHash: String(version.document_hash ?? "")
+    }));
+    return { path, versions };
+  }
+
+  /** The text of `entry` as it was at a saved version. */
+  async _versionText(session, entry, versionId) {
+    let response;
+    try {
+      response = await this.client.GetSyncDocumentVersion({
+        database_id: session.id,
+        document_id: entry.documentId,
+        version_id: versionId
+      });
+    } catch (err) {
+      throw formatVersionError(err);
+    }
+
+    const state = toBytes(response?.state_update);
+    if (state.length === 0) {
+      return "";
+    }
+    const doc = new this.ctx.Y.Doc();
+    try {
+      doc.guid = entry.documentId;
+      this.ctx.Y.applyUpdateV2(doc, state);
+      return doc.getText("content").toString();
+    } finally {
+      doc.destroy();
+    }
+  }
+
+  /** Read the text content of a file as it was at a saved version. */
+  async readFileVersion(driveRef, rawPath, versionId, { offset = 0, limit } = {}) {
+    const path = normalizeDrivePath(rawPath);
+    const session = await this._session(driveRef);
+    const entry = this._requireFile(session, path);
+    if (entry.binary) {
+      throw invalid("reading earlier versions of binary files is not supported");
+    }
+
+    const text = await this._versionText(session, entry, versionId);
+
+    const cap = Math.min(limit ?? this.options.maxResponseChars, this.options.maxResponseChars);
+    const slice = text.slice(offset, offset + cap);
+    return {
+      path,
+      versionId,
+      encoding: "utf-8",
+      offset,
+      returned: slice.length,
+      total: text.length,
+      truncated: offset + slice.length < text.length,
+      content: slice
+    };
+  }
+
+  /** Save a version checkpoint of a file. */
+  async createFileVersion(driveRef, rawPath, label = "") {
+    this._assertWritable();
+    const path = normalizeDrivePath(rawPath);
+    const session = await this._session(driveRef);
+    const entry = this._requireFile(session, path);
+
+    try {
+      const response = await this.client.CreateSyncDocumentVersion({
+        database_id: session.id,
+        document_id: entry.documentId,
+        label: String(label ?? "").trim()
+      });
+      return { path, versionId: String(response?.version_id ?? "") };
+    } catch (err) {
+      throw formatVersionError(err);
+    }
+  }
+
+  /**
+   * Replace a file's content with that of a saved version. The Volt records an
+   * audit version of the revert, whose id is returned.
+   */
+  async revertFileVersion(driveRef, rawPath, versionId) {
+    this._assertWritable();
+    const path = normalizeDrivePath(rawPath);
+    const session = await this._session(driveRef);
+
+    return session.exclusive(async () => {
+      const entry = this._requireFile(session, path);
+      if (entry.binary) {
+        throw invalid("reverting binary files is not supported");
+      }
+
+      let response;
+      try {
+        response = await this.client.RevertSyncDocumentVersion({
+          database_id: session.id,
+          document_id: entry.documentId,
+          version_id: versionId,
+          label: ""
+        });
+      } catch (err) {
+        throw formatVersionError(err);
+      }
+
+      // The file now holds the version's text. The index records its size,
+      // which clients write, so bring it in line.
+      const text = await this._versionText(session, entry, versionId);
+      const size = Buffer.byteLength(text, "utf8");
+      if (size !== entry.size) {
+        await this._setMetadata(session, {
+          document_id: entry.documentId,
+          metadata: schemaToMetadata(entry),
+          json: JSON.stringify({ name: entry.path, s: size })
+        });
+      }
+
+      return { path, size, auditVersionId: String(response?.version_id ?? "") };
+    });
+  }
+
+  // ---------------------------------------------------------------- lifecycle
+
+  /** Close every open sync stream. */
+  async close() {
+    const sessions = [...this.sessions.values()];
+    this.sessions.clear();
+    await Promise.all(sessions.map((session) => session.close().catch(() => {})));
+  }
+}