@bendyline/docblocks 1.1.2 → 2.1.0

package/dist/chunk-6IYMTYMQ.js

@@ -0,0 +1,1692 @@
+import {
+  withFileCommitLock
+} from "./chunk-AEHCVWU5.js";
+import {
+  parentChainWithRoot
+} from "./chunk-GM5YXU4L.js";
+import {
+  isRecord
+} from "./chunk-U722UUFN.js";
+import {
+  bytesEqual,
+  compareSnapshotsByName,
+  compareText,
+  copyBytes,
+  parseFileSystemVersion
+} from "./chunk-P4WATND4.js";
+import {
+  decodeUtf8Text
+} from "./chunk-FA7UNOXK.js";
+import {
+  FsError,
+  WORKSPACE_ROOT,
+  fsErrorFromUnknown,
+  parseWorkspacePath,
+  workspacePathBasename,
+  workspacePathContains,
+  workspacePathDirname
+} from "./chunk-JS6XFWQK.js";
+import {
+  RawIndexedDBFileSystemStore,
+  indexedDBWorkspaceDatabaseName
+} from "./chunk-RVPGQBWR.js";
+
+// src/filesystem/indexeddb-provider-v2.ts
+var ENTRY_SCHEMA_VERSION = 1;
+var STATE_SCHEMA_VERSION = 1;
+var LEGACY_CONFLICT_SCHEMA_VERSION = 2;
+var LEGACY_CONFLICT_SCHEMA_VERSION_V1 = 1;
+var LEGACY_OPAQUE_SCHEMA_VERSION = 2;
+var LEGACY_OPAQUE_SCHEMA_VERSION_V1 = 1;
+var ENTRY_PREFIX = "v2:entry:";
+var STATE_KEY = "v2:state";
+var LEGACY_CONFLICT_PREFIX = "v2:legacy-conflict:";
+var LEGACY_IGNORED_PREFIX = "v2:legacy-ignored:";
+var LEGACY_OPAQUE_PREFIX = "v2:legacy-opaque:";
+var LEGACY_DIRS_KEY = "fs:dirs";
+var LEGACY_PREFIX = "fs:";
+var LEGACY_CONTENT_SUFFIX = ":content";
+var LEGACY_BINARY_SUFFIX = ":binary";
+var LEGACY_META_SUFFIX = ":meta";
+var LegacyNamespaceDetectedError = class extends Error {
+};
+var INDEXEDDB_V2_CAPABILITIES = Object.freeze({
+  writeAtomicity: "cross-context",
+  moveAtomicity: "cross-context",
+  snapshotAtomicity: "cross-context",
+  conditionalWrite: "storage-atomic",
+  recursiveRemove: true,
+  watch: false,
+  caseSensitivity: "sensitive",
+  symlinkPolicy: "unsupported",
+  durability: "best-effort"
+});
+var IndexedDBFileSystemProviderV2 = class {
+  constructor(id, label, options = {}) {
+    this.capabilities = INDEXEDDB_V2_CAPABILITIES;
+    this.subscriptions = /* @__PURE__ */ new Set();
+    this.inFlight = /* @__PURE__ */ new Set();
+    this.initialization = null;
+    this.disposePromise = null;
+    this.storeClosed = false;
+    this.disposed = false;
+    this.id = id;
+    this.label = label;
+    this.store = options.store ?? new RawIndexedDBFileSystemStore(indexedDBWorkspaceDatabaseName(id), "files");
+    this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+    this.closeStoreOnDispose = options.closeStoreOnDispose ?? true;
+    this.versionPrefix = `idb-${encodeURIComponent(id).slice(0, 900) || "workspace"}`;
+  }
+  /** Track accepted storage work so disposal can join it before closing. */
+  runSharedTransaction(mode, operation, work) {
+    this.assertOpen(operation);
+    const transaction = this.store.transaction(mode, work);
+    this.inFlight.add(transaction);
+    void transaction.then(
+      () => this.inFlight.delete(transaction),
+      () => this.inFlight.delete(transaction)
+    );
+    return transaction;
+  }
+  async stat(path) {
+    this.assertOpen("stat");
+    const canonical = parseWorkspacePath(path);
+    await this.ensureInitialized("stat");
+    return this.transaction("readonly", { operation: "stat", path: canonical }, async (tx) => {
+      const entry = await readEntry(tx, canonical);
+      return entry ? toEntrySnapshot(entry) : null;
+    });
+  }
+  async readFile(path) {
+    this.assertOpen("read");
+    const canonical = parseWorkspacePath(path);
+    await this.ensureInitialized("read");
+    return this.transaction("readonly", { operation: "read", path: canonical }, async (tx) => {
+      const entry = await readEntry(tx, canonical);
+      if (!entry) return null;
+      if (entry.kind !== "file") {
+        throw this.error(
+          "type-mismatch",
+          "read",
+          canonical,
+          "Expected a file but found a directory."
+        );
+      }
+      return Object.freeze({ entry: toFileSnapshot(entry), data: copyBytes(entry.data) });
+    });
+  }
+  async readDirectory(path) {
+    this.assertOpen("list");
+    const canonical = parseWorkspacePath(path);
+    await this.ensureInitialized("list");
+    return this.transaction("readonly", { operation: "list", path: canonical }, async (tx) => {
+      const directory = await readEntry(tx, canonical);
+      if (!directory) {
+        throw this.error("not-found", "list", canonical, "Directory does not exist.");
+      }
+      if (directory.kind !== "directory") {
+        throw this.error(
+          "type-mismatch",
+          "list",
+          canonical,
+          "Expected a directory but found a file."
+        );
+      }
+      const paths = await listEntryPaths(tx);
+      const children = [];
+      for (const candidate of paths) {
+        if (candidate && workspacePathDirname(candidate) === canonical) {
+          const entry = await readRequiredEntry(tx, candidate);
+          children.push(toEntrySnapshot(entry));
+        }
+      }
+      children.sort(compareSnapshotsByName);
+      return Object.freeze(children);
+    });
+  }
+  async writeFile(path, data, options = {}) {
+    this.assertOpen("write");
+    const canonical = this.canonicalNonRoot(path, "write");
+    const ownedData = copyBytes(data);
+    await this.ensureInitialized("write");
+    return this.withMutationLock(
+      () => this.transaction("readwrite", { operation: "write", path: canonical }, async (tx) => {
+        await assertNoLegacyConflict(tx, canonical, "write");
+        const mutation = new EntryMutation(tx);
+        const existing = await mutation.get(canonical);
+        if (existing?.kind === "directory") {
+          throw this.error(
+            "type-mismatch",
+            "write",
+            canonical,
+            "Cannot replace a directory with a file."
+          );
+        }
+        const mode = options.mode ?? "upsert";
+        if (mode === "create" && existing) {
+          throw this.error("already-exists", "write", canonical, "File already exists.");
+        }
+        if (mode === "replace" && !existing) {
+          throw this.error("not-found", "write", canonical, "File does not exist.");
+        }
+        this.assertExpectedVersion(existing, options.expectedVersion, "write", canonical);
+        const missingParents = await this.planParents(
+          mutation,
+          canonical,
+          options.createParents ?? false,
+          "write"
+        );
+        const next = await this.nextMutationVersion(tx);
+        this.addDirectories(mutation, missingParents, next);
+        const file = {
+          schemaVersion: ENTRY_SCHEMA_VERSION,
+          kind: "file",
+          path: canonical,
+          data: ownedData,
+          version: next.version,
+          lastModified: next.lastModified
+        };
+        mutation.set(canonical, file);
+        await this.touchParents(mutation, canonical, next);
+        await mutation.commit(next.state);
+        return toFileSnapshot(file);
+      })
+    );
+  }
+  async createDirectory(path, options = {}) {
+    this.assertOpen("create-directory");
+    const canonical = parseWorkspacePath(path);
+    await this.ensureInitialized("create-directory");
+    return this.withMutationLock(
+      () => this.transaction(
+        "readwrite",
+        { operation: "create-directory", path: canonical },
+        async (tx) => {
+          await assertNoLegacyConflict(tx, canonical, "create-directory");
+          const mutation = new EntryMutation(tx);
+          const existing = await mutation.get(canonical);
+          if (existing) {
+            if (existing.kind !== "directory") {
+              throw this.error(
+                "type-mismatch",
+                "create-directory",
+                canonical,
+                "Cannot replace a file with a directory."
+              );
+            }
+            if ((options.mode ?? "ensure") === "create") {
+              throw this.error(
+                "already-exists",
+                "create-directory",
+                canonical,
+                "Directory already exists."
+              );
+            }
+            return toDirectorySnapshot(existing);
+          }
+          const missingParents = await this.planParents(
+            mutation,
+            canonical,
+            options.createParents ?? false,
+            "create-directory"
+          );
+          const next = await this.nextMutationVersion(tx);
+          this.addDirectories(mutation, [...missingParents, canonical], next);
+          await this.touchParents(mutation, canonical, next);
+          await mutation.commit(next.state);
+          const created = await mutation.get(canonical);
+          if (!created || created.kind !== "directory") {
+            throw corrupt("Created directory was not staged.", canonical);
+          }
+          return toDirectorySnapshot(created);
+        }
+      )
+    );
+  }
+  async remove(path, options = {}) {
+    this.assertOpen("remove");
+    const canonical = this.canonicalNonRoot(path, "remove");
+    await this.ensureInitialized("remove");
+    return this.withMutationLock(
+      () => this.transaction("readwrite", { operation: "remove", path: canonical }, async (tx) => {
+        await assertNoLegacyConflictInSubtree(tx, canonical, "remove");
+        const mutation = new EntryMutation(tx);
+        const existing = await mutation.get(canonical);
+        const state = await readRequiredState(tx);
+        if (!existing) {
+          if ((options.missing ?? "error") === "ignore") {
+            return Object.freeze({
+              removed: false,
+              version: parseFileSystemVersion(state.treeVersion)
+            });
+          }
+          throw this.error("not-found", "remove", canonical, "Entry does not exist.");
+        }
+        this.assertExpectedVersion(existing, options.expectedVersion, "remove", canonical);
+        const paths = await mutation.paths();
+        const descendants = paths.filter(
+          (candidate) => workspacePathContains(canonical, candidate, false)
+        );
+        if (existing.kind === "directory" && descendants.length > 0 && !options.recursive) {
+          throw this.error("not-empty", "remove", canonical, "Directory is not empty.");
+        }
+        const next = this.advanceState(state);
+        mutation.delete(canonical);
+        if (existing.kind === "directory") {
+          for (const descendant of descendants) mutation.delete(descendant);
+        }
+        await this.touchParents(mutation, canonical, next);
+        await mutation.commit(next.state);
+        return Object.freeze({ removed: true, version: next.version });
+      })
+    );
+  }
+  async move(oldPath, newPath, options = {}) {
+    this.assertOpen("move");
+    const sourcePath = this.canonicalNonRoot(oldPath, "move");
+    const destinationPath = this.canonicalNonRoot(newPath, "move");
+    await this.ensureInitialized("move");
+    return this.withMutationLock(
+      () => this.transaction(
+        "readwrite",
+        { operation: "move", path: sourcePath, destinationPath },
+        async (tx) => {
+          await assertNoLegacyConflictInSubtree(tx, sourcePath, "move");
+          await assertNoLegacyConflictInSubtree(tx, destinationPath, "move");
+          const mutation = new EntryMutation(tx);
+          const source = await mutation.get(sourcePath);
+          if (!source) {
+            throw this.error("not-found", "move", sourcePath, "Source does not exist.");
+          }
+          this.assertExpectedVersion(source, options.expectedVersion, "move", sourcePath);
+          if (sourcePath === destinationPath) return toEntrySnapshot(source);
+          if (await mutation.get(destinationPath)) {
+            throw new FsError("already-exists", "Destination already exists.", {
+              operation: "move",
+              path: sourcePath,
+              destinationPath
+            });
+          }
+          if (source.kind === "directory" && workspacePathContains(sourcePath, destinationPath, false)) {
+            throw new FsError("invalid-path", "Cannot move a directory into itself.", {
+              operation: "move",
+              path: sourcePath,
+              destinationPath
+            });
+          }
+          const missingParents = await this.planParents(
+            mutation,
+            destinationPath,
+            options.createParents ?? false,
+            "move"
+          );
+          const paths = await mutation.paths();
+          const sourcePaths = paths.filter(
+            (candidate) => workspacePathContains(sourcePath, candidate)
+          );
+          const sourceSet = new Set(sourcePaths);
+          const remapped = [];
+          for (const currentPath of sourcePaths) {
+            const suffix = currentPath.slice(sourcePath.length);
+            const targetPath = parseWorkspacePath(`${destinationPath}${suffix}`);
+            const collision = await mutation.get(targetPath);
+            if (collision && !sourceSet.has(targetPath)) {
+              throw new FsError("already-exists", "A destination descendant already exists.", {
+                operation: "move",
+                path: currentPath,
+                destinationPath: targetPath
+              });
+            }
+            remapped.push([currentPath, targetPath, await mutation.require(currentPath)]);
+          }
+          const state = await readRequiredState(tx);
+          const next = this.advanceState(state);
+          for (const currentPath of sourcePaths) mutation.delete(currentPath);
+          this.addDirectories(mutation, missingParents, next);
+          for (const [, targetPath, current] of remapped) {
+            mutation.set(targetPath, withPathAndVersion(current, targetPath, next));
+          }
+          await this.touchParents(mutation, sourcePath, next);
+          await this.touchParents(mutation, destinationPath, next);
+          await mutation.commit(next.state);
+          return toEntrySnapshot(await mutation.require(destinationPath));
+        }
+      )
+    );
+  }
+  async snapshot() {
+    this.assertOpen("snapshot");
+    await this.ensureInitialized("snapshot");
+    return this.transaction("readonly", { operation: "snapshot" }, async (tx) => {
+      const [state, paths] = await Promise.all([readRequiredState(tx), listEntryPaths(tx)]);
+      const entries = [];
+      for (const path of paths.sort(compareText)) {
+        const entry = await readRequiredEntry(tx, path);
+        entries.push(
+          entry.kind === "file" ? Object.freeze({ ...toFileSnapshot(entry), data: copyBytes(entry.data) }) : toDirectorySnapshot(entry)
+        );
+      }
+      return Object.freeze({
+        version: parseFileSystemVersion(state.treeVersion),
+        entries: Object.freeze(entries)
+      });
+    });
+  }
+  /** IndexedDB has no reliable cross-browser external-change observer. */
+  watch(_listener, options = {}) {
+    this.assertOpen("watch");
+    const error = new FsError("not-supported", "IndexedDB filesystem watching is unavailable.", {
+      operation: "watch"
+    });
+    let closed = false;
+    let disposePromise = null;
+    const ready = Promise.reject(error);
+    void ready.catch((caught) => {
+      try {
+        options.onError?.(caught);
+      } catch {
+      }
+    });
+    const subscription = {
+      get closed() {
+        return closed;
+      },
+      ready,
+      dispose: () => {
+        if (disposePromise) return disposePromise;
+        closed = true;
+        this.subscriptions.delete(subscription);
+        disposePromise = Promise.resolve();
+        return disposePromise;
+      }
+    };
+    this.subscriptions.add(subscription);
+    return subscription;
+  }
+  dispose() {
+    if (this.disposePromise) return this.disposePromise;
+    this.disposed = true;
+    this.disposePromise = (async () => {
+      try {
+        await Promise.allSettled([...this.inFlight]);
+        await Promise.all([...this.subscriptions].map((subscription) => subscription.dispose()));
+      } finally {
+        if (this.closeStoreOnDispose && !this.storeClosed) {
+          this.storeClosed = true;
+          this.store.close?.();
+        }
+      }
+    })();
+    return this.disposePromise;
+  }
+  /** List unresolved, byte-preserving conflicts found during v1 migration. */
+  async listLegacyMigrationConflicts() {
+    this.assertOpen("read");
+    await this.ensureInitialized("read");
+    return this.transaction("readonly", { operation: "read" }, async (tx) => {
+      const keys = (await tx.keys()).filter((key) => key.startsWith(LEGACY_CONFLICT_PREFIX));
+      const conflicts = [];
+      for (const key of keys) {
+        const raw = await tx.get(key);
+        conflicts.push(toPublicLegacyConflict(validateLegacyConflict(raw)));
+      }
+      conflicts.sort((left, right) => compareText(left.path, right.path));
+      return Object.freeze(conflicts);
+    });
+  }
+  /** Resolve quarantined legacy data by choosing v2 or one legacy byte payload. */
+  async resolveLegacyMigrationConflict(path, resolution) {
+    this.assertOpen("write");
+    const canonical = this.canonicalNonRoot(path, "write");
+    await this.ensureInitialized("write");
+    return this.withMutationLock(
+      () => this.transaction("readwrite", { operation: "write", path: canonical }, async (tx) => {
+        const key = legacyConflictKey(canonical);
+        const conflict = validateLegacyConflict(await tx.get(key));
+        if (conflict.path !== canonical) throw corrupt("Legacy conflict key mismatch.", canonical);
+        const mutation = new EntryMutation(tx);
+        const existing = await mutation.get(canonical);
+        if (resolution === "v2") {
+          if (!existing) {
+            throw this.error(
+              "type-mismatch",
+              "write",
+              canonical,
+              "There is no v2 authority to keep at this path."
+            );
+          }
+          await tx.delete(key);
+          return toEntrySnapshot(existing);
+        }
+        const selected = selectLegacyPayload(conflict, resolution, canonical);
+        if (selected.kind === "directory") {
+          if (existing?.kind === "file") {
+            throw this.error(
+              "type-mismatch",
+              "write",
+              canonical,
+              "Move or remove the v2 file before restoring a legacy directory at this path."
+            );
+          }
+          if (existing) {
+            await tx.delete(key);
+            return toDirectorySnapshot(existing);
+          }
+          const missingParents2 = await this.planParents(mutation, canonical, true, "write");
+          const next2 = await this.nextMutationVersion(tx);
+          this.addDirectories(mutation, [...missingParents2, canonical], next2);
+          await this.touchParents(mutation, canonical, next2);
+          await mutation.commit(next2.state);
+          await tx.delete(key);
+          const restored = await mutation.require(canonical);
+          if (restored.kind !== "directory") {
+            throw corrupt("Restored legacy directory was not staged as a directory.", canonical);
+          }
+          return toDirectorySnapshot(restored);
+        }
+        if (existing?.kind === "directory") {
+          throw this.error(
+            "type-mismatch",
+            "write",
+            canonical,
+            "Move or remove the v2 directory before restoring a legacy file at this path."
+          );
+        }
+        const missingParents = await this.planParents(mutation, canonical, true, "write");
+        const next = await this.nextMutationVersion(tx);
+        this.addDirectories(mutation, missingParents, next);
+        const file = {
+          schemaVersion: ENTRY_SCHEMA_VERSION,
+          kind: "file",
+          path: canonical,
+          data: copyBytes(selected.data),
+          version: next.version,
+          lastModified: next.lastModified
+        };
+        mutation.set(canonical, file);
+        await this.touchParents(mutation, canonical, next);
+        await mutation.commit(next.state);
+        await tx.delete(key);
+        return toFileSnapshot(file);
+      })
+    );
+  }
+  /** Explicitly discard every quarantined legacy candidate at a path. */
+  async discardLegacyMigrationConflict(path) {
+    this.assertOpen("remove");
+    const canonical = this.canonicalNonRoot(path, "remove");
+    await this.ensureInitialized("remove");
+    return this.withMutationLock(
+      () => this.transaction("readwrite", { operation: "remove", path: canonical }, async (tx) => {
+        const key = legacyConflictKey(canonical);
+        if (await tx.get(key) === null) return false;
+        await tx.delete(key);
+        return true;
+      })
+    );
+  }
+  /**
+   * List the unrecognized legacy keys this workspace archived during migration.
+   *
+   * Migration deletes the legacy `fs:` namespace, but a key it cannot interpret
+   * is copied aside first rather than dropped: those bytes belong to whatever
+   * tool wrote them against this origin, and DocBlocks is not entitled to
+   * decide they are worthless. Nothing else reads that archive, so without this
+   * call the bytes are invisible and their quota is unaccountable.
+   *
+   * Values are deliberately excluded — an archive large enough to matter is an
+   * archive too large to materialize just to count it. Use
+   * {@link readLegacyOpaqueRecord} for the values themselves.
+   */
+  async listLegacyOpaqueRecords() {
+    this.assertOpen("read");
+    await this.ensureInitialized("read");
+    return this.transaction("readonly", { operation: "read" }, async (tx) => {
+      const keys = (await tx.keys()).filter((key) => key.startsWith(LEGACY_OPAQUE_PREFIX));
+      const summaries = [];
+      for (const key of keys) {
+        summaries.push(
+          toOpaqueSummary(validateLegacyOpaqueRecord(await tx.get(key), key))
+        );
+      }
+      summaries.sort((left, right) => compareText(left.key, right.key));
+      return Object.freeze(summaries);
+    });
+  }
+  /** Retrieve every archived value for one unrecognized legacy key. */
+  async readLegacyOpaqueRecord(key) {
+    this.assertOpen("read");
+    await this.ensureInitialized("read");
+    return this.transaction("readonly", { operation: "read" }, async (tx) => {
+      const archiveKey = legacyOpaqueKey(key);
+      const raw = await tx.get(archiveKey);
+      if (raw === null) return null;
+      return toPublicOpaqueRecord(validateLegacyOpaqueRecord(raw, archiveKey));
+    });
+  }
+  /**
+   * Permanently destroy archived legacy values. This is the only operation that
+   * can lose data the archive exists to protect.
+   *
+   * For every target, all of that key's archived value snapshots are erased and
+   * the quota they held is reclaimed. There is no undo, no tombstone, and no
+   * other copy: migration already deleted the original `fs:` key, so the
+   * archive is the last one. Retrieve anything worth keeping with
+   * {@link readLegacyOpaqueRecord} before calling this.
+   *
+   * Each target must carry the `valueCount` the caller actually observed, which
+   * is why a target is a value returned by {@link listLegacyOpaqueRecords} or
+   * {@link readLegacyOpaqueRecord} rather than a bare key. A stale client can
+   * append a new snapshot at any time; if any target has grown since it was
+   * observed, the whole call fails with `conflict` and destroys nothing, so
+   * re-list and look again. A key that is already absent is not an error —
+   * discarding what is gone is a no-op — but a key whose count disagrees is.
+   *
+   * @returns how many records were destroyed.
+   */
+  async discardLegacyOpaqueRecords(targets) {
+    this.assertOpen("remove");
+    if (targets.length === 0) return 0;
+    await this.ensureInitialized("remove");
+    return this.withMutationLock(
+      () => this.transaction("readwrite", { operation: "remove" }, async (tx) => {
+        const doomed = [];
+        for (const target of targets) {
+          const archiveKey = legacyOpaqueKey(target.key);
+          const raw = await tx.get(archiveKey);
+          if (raw === null) continue;
+          const record = validateLegacyOpaqueRecord(raw, archiveKey);
+          if (record.values.length !== target.valueCount) {
+            throw new FsError(
+              "conflict",
+              `Archived legacy key ${target.key} now holds ${record.values.length} values, not ${target.valueCount}. Read it again before discarding it.`,
+              { operation: "remove", retryable: false }
+            );
+          }
+          doomed.push(archiveKey);
+        }
+        for (const archiveKey of doomed) await tx.delete(archiveKey);
+        return doomed.length;
+      })
+    );
+  }
+  async ensureInitialized(operation) {
+    this.assertOpen(operation);
+    if (this.initialization) return this.initialization;
+    const attempt = this.withMutationLock(
+      () => this.runSharedTransaction("readwrite", operation, (tx) => this.migrateLegacy(tx))
+    );
+    this.initialization = attempt.catch((error) => {
+      this.initialization = null;
+      throw fsErrorFromUnknown(error, { operation });
+    });
+    return this.initialization;
+  }
+  async migrateLegacy(tx) {
+    const existingState = await readState(tx);
+    const keys = await tx.keys();
+    if (existingState) {
+      const root = await readEntry(tx, WORKSPACE_ROOT);
+      if (!root || root.kind !== "directory") {
+        throw corrupt("Initialized v2 filesystem has no root directory.", WORKSPACE_ROOT);
+      }
+      if (existingState.migrationVersion === 1 || keys.some((key) => key.startsWith(LEGACY_PREFIX))) {
+        await this.quarantineExistingLegacy(
+          tx,
+          keys,
+          existingState,
+          existingState.migrationVersion === 1 ? "authority-collision" : "stale-client-write"
+        );
+      }
+      return;
+    }
+    const now = this.now().toISOString();
+    const version = this.makeVersion(1);
+    const entries = /* @__PURE__ */ new Map();
+    for (const path of entryPathsFromKeys(keys)) {
+      entries.set(path, await readRequiredEntry(tx, path));
+    }
+    if (entries.get(WORKSPACE_ROOT)?.kind === "file") {
+      throw corrupt(
+        "Pre-release v2 authority stored a file at the workspace root.",
+        WORKSPACE_ROOT
+      );
+    }
+    entries.set(
+      WORKSPACE_ROOT,
+      entries.get(WORKSPACE_ROOT) ?? directoryRecord(WORKSPACE_ROOT, version, now)
+    );
+    const legacyDirectories = await readLegacyDirectories(tx);
+    const legacyFilePaths = legacyPathsFromKeys(keys);
+    for (const directory of legacyDirectories) {
+      const existing = entries.get(directory);
+      if (existing?.kind === "file" || hasFileAncestor(entries, directory)) {
+        await appendLegacyConflict(
+          tx,
+          directory,
+          directoryRecoveryCandidate("authority-collision", now)
+        );
+        continue;
+      }
+      addParentDirectories(entries, directory, version, now);
+      if (!existing) entries.set(directory, directoryRecord(directory, version, now));
+    }
+    for (const path of legacyFilePaths) {
+      const legacy = await readLegacyFile(tx, path);
+      const existing = entries.get(path);
+      if (existing?.kind === "file") {
+        if (!legacyPayloadsMatchEntry(legacy, existing)) {
+          await appendLegacyConflict(
+            tx,
+            path,
+            fileRecoveryCandidate(legacy, "authority-collision", now)
+          );
+        }
+        continue;
+      }
+      const kindCollision = existing?.kind === "directory" || hasFileAncestor(entries, path);
+      const payloadsDisagree = legacy.content !== null && legacy.binary !== null && !bytesEqual(new TextEncoder().encode(legacy.content), legacy.binary);
+      if (payloadsDisagree || kindCollision || legacy.content === null && legacy.binary === null) {
+        await appendLegacyConflict(
+          tx,
+          path,
+          fileRecoveryCandidate(
+            legacy,
+            kindCollision ? "kind-collision" : payloadsDisagree ? "dual-payload" : "authority-collision",
+            now
+          )
+        );
+        continue;
+      }
+      addParentDirectories(entries, path, version, now);
+      const data = legacy.content !== null ? new TextEncoder().encode(legacy.content).buffer : copyBytes(legacy.binary);
+      entries.set(path, {
+        schemaVersion: ENTRY_SCHEMA_VERSION,
+        kind: "file",
+        path,
+        data: copyBytes(data),
+        version,
+        lastModified: legacy.metadata?.lastModified ?? now
+      });
+    }
+    for (const entry of entries.values()) {
+      await tx.put(entryKey(entry.path), entry);
+    }
+    await deleteLegacyNamespace(tx, keys, now);
+    const state = {
+      schemaVersion: STATE_SCHEMA_VERSION,
+      migrationVersion: 2,
+      mutationCounter: 1,
+      treeVersion: version
+    };
+    await tx.put(STATE_KEY, state);
+  }
+  async quarantineExistingLegacy(tx, keys, state, reason) {
+    const now = this.now().toISOString();
+    const ignored = await readMarkerPaths(
+      tx,
+      keys,
+      LEGACY_IGNORED_PREFIX,
+      validateIgnoredLegacyPath
+    );
+    const legacyDirectories = await readLegacyDirectories(tx);
+    for (const path of legacyDirectories) {
+      if (ignored.has(path)) continue;
+      const entry = await readEntry(tx, path);
+      if (entry?.kind === "directory") continue;
+      await appendLegacyConflict(
+        tx,
+        path,
+        directoryRecoveryCandidate(entry ? "kind-collision" : reason, now)
+      );
+    }
+    for (const path of legacyPathsFromKeys(keys)) {
+      if (ignored.has(path)) continue;
+      const legacy = await readLegacyFile(tx, path);
+      const entry = await readEntry(tx, path);
+      if (entry?.kind === "file" && legacyPayloadsMatchEntry(legacy, entry)) continue;
+      await appendLegacyConflict(
+        tx,
+        path,
+        fileRecoveryCandidate(legacy, entry?.kind === "directory" ? "kind-collision" : reason, now)
+      );
+    }
+    await deleteLegacyNamespace(tx, keys, now);
+    for (const key of keys) {
+      if (key.startsWith(LEGACY_IGNORED_PREFIX)) await tx.delete(key);
+    }
+    if (state.migrationVersion === 1) {
+      await tx.put(STATE_KEY, { ...state, migrationVersion: 2 });
+    }
+  }
+  async transaction(mode, context, operation) {
+    this.assertOpen(context.operation ?? "read");
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      try {
+        const outcome = await this.runSharedTransaction(
+          mode,
+          context.operation ?? "read",
+          async (transaction) => {
+            if (await transaction.hasKeyWithPrefix(LEGACY_PREFIX)) {
+              if (mode === "readonly") throw new LegacyNamespaceDetectedError();
+              const state = await readRequiredState(transaction);
+              await this.quarantineExistingLegacy(
+                transaction,
+                await transaction.keys(),
+                state,
+                "stale-client-write"
+              );
+              return { retry: true };
+            }
+            return { retry: false, value: await operation(transaction) };
+          }
+        );
+        if (outcome.retry) continue;
+        return outcome.value;
+      } catch (error) {
+        if (!(error instanceof LegacyNamespaceDetectedError)) {
+          throw fsErrorFromUnknown(error, context);
+        }
+        try {
+          await this.withMutationLock(
+            () => this.runSharedTransaction(
+              "readwrite",
+              context.operation ?? "read",
+              async (transaction) => {
+                if (!await transaction.hasKeyWithPrefix(LEGACY_PREFIX)) return;
+                const state = await readRequiredState(transaction);
+                await this.quarantineExistingLegacy(
+                  transaction,
+                  await transaction.keys(),
+                  state,
+                  "stale-client-write"
+                );
+              }
+            )
+          );
+        } catch (quarantineError) {
+          throw fsErrorFromUnknown(quarantineError, context);
+        }
+      }
+    }
+    throw new FsError("busy", "A stale IndexedDB client is continuously writing legacy records.", {
+      ...context,
+      retryable: true
+    });
+  }
+  withMutationLock(operation) {
+    return withFileCommitLock(`indexeddb:${this.id}:workspace`, operation);
+  }
+  async nextMutationVersion(tx) {
+    return this.advanceState(await readRequiredState(tx));
+  }
+  advanceState(state) {
+    if (state.mutationCounter >= Number.MAX_SAFE_INTEGER) {
+      throw corrupt("IndexedDB filesystem mutation counter overflowed.");
+    }
+    const mutationCounter = state.mutationCounter + 1;
+    const version = this.makeVersion(mutationCounter);
+    const nextState = {
+      ...state,
+      mutationCounter,
+      treeVersion: version
+    };
+    return { state: nextState, version, lastModified: this.now().toISOString() };
+  }
+  makeVersion(counter) {
+    return parseFileSystemVersion(`${this.versionPrefix}:${counter}`);
+  }
+  async planParents(mutation, path, createParents, operation) {
+    const missing = [];
+    for (const parent of parentChainWithRoot(path)) {
+      const entry = await mutation.get(parent);
+      if (entry?.kind === "file") {
+        throw this.error(
+          "type-mismatch",
+          operation,
+          parent,
+          "A parent path is a file, not a directory."
+        );
+      }
+      if (!entry) {
+        if (!createParents) {
+          throw this.error("not-found", operation, parent, "Parent directory does not exist.");
+        }
+        missing.push(parent);
+      }
+    }
+    return missing;
+  }
+  addDirectories(mutation, paths, next) {
+    for (const path of paths) {
+      mutation.set(path, directoryRecord(path, next.version, next.lastModified));
+    }
+  }
+  async touchParents(mutation, path, next) {
+    for (const parent of parentChainWithRoot(path)) {
+      const entry = await mutation.get(parent);
+      if (entry?.kind === "directory") {
+        mutation.set(parent, directoryRecord(parent, next.version, next.lastModified));
+      }
+    }
+  }
+  canonicalNonRoot(path, operation) {
+    const canonical = parseWorkspacePath(path);
+    if (!canonical) {
+      throw this.error(
+        "invalid-path",
+        operation,
+        canonical,
+        "The workspace root is not a file entry."
+      );
+    }
+    return canonical;
+  }
+  assertExpectedVersion(entry, expected, operation, path) {
+    if (expected === void 0) return;
+    if (expected === null ? !entry : entry?.version === expected) return;
+    throw this.error(
+      "conflict",
+      operation,
+      path,
+      "Entry version does not match the expected version."
+    );
+  }
+  assertOpen(operation) {
+    if (!this.disposed) return;
+    throw new FsError("disposed", "Filesystem provider is disposed.", { operation });
+  }
+  error(code, operation, path, message) {
+    return new FsError(code, message, { operation, path });
+  }
+};
+var EntryMutation = class {
+  constructor(transaction) {
+    this.transaction = transaction;
+    this.cache = /* @__PURE__ */ new Map();
+    this.changed = /* @__PURE__ */ new Map();
+    this.deleted = /* @__PURE__ */ new Set();
+  }
+  async get(path) {
+    if (this.deleted.has(path)) return null;
+    const cached = this.cache.get(path);
+    if (cached !== void 0) return cached;
+    const entry = await readEntry(this.transaction, path);
+    this.cache.set(path, entry);
+    return entry;
+  }
+  async require(path) {
+    const entry = await this.get(path);
+    if (!entry) throw corrupt(`Missing staged entry: ${path}.`, path);
+    return entry;
+  }
+  set(path, entry) {
+    const owned = copyEntry(entry);
+    this.cache.set(path, owned);
+    this.changed.set(path, owned);
+    this.deleted.delete(path);
+  }
+  delete(path) {
+    this.cache.set(path, null);
+    this.changed.delete(path);
+    this.deleted.add(path);
+  }
+  async paths() {
+    const paths = new Set(await listEntryPaths(this.transaction));
+    for (const path of this.deleted) paths.delete(path);
+    for (const path of this.changed.keys()) paths.add(path);
+    return [...paths];
+  }
+  async commit(state) {
+    for (const path of this.deleted) await this.transaction.delete(entryKey(path));
+    for (const [path, entry] of this.changed) await this.transaction.put(entryKey(path), entry);
+    await this.transaction.put(STATE_KEY, state);
+  }
+};
+function entryKey(path) {
+  return `${ENTRY_PREFIX}${path}`;
+}
+function legacyConflictKey(path) {
+  return `${LEGACY_CONFLICT_PREFIX}${path}`;
+}
+function entryPathsFromKeys(keys) {
+  return keys.filter((key) => key.startsWith(ENTRY_PREFIX)).map((key) => {
+    const rawPath = key.slice(ENTRY_PREFIX.length);
+    const path = parseWorkspacePath(rawPath);
+    if (path !== rawPath) throw corrupt(`Non-canonical v2 entry key: ${key}.`);
+    return path;
+  });
+}
+async function listEntryPaths(tx) {
+  return entryPathsFromKeys(await tx.keys());
+}
+async function readEntry(tx, path) {
+  const raw = await tx.get(entryKey(path));
+  return raw === null ? null : validateEntry(raw, path);
+}
+async function readRequiredEntry(tx, path) {
+  const entry = await readEntry(tx, path);
+  if (!entry) throw corrupt(`Missing v2 entry record: ${path}.`, path);
+  return entry;
+}
+function validateEntry(value, expectedPath) {
+  if (!isRecord(value)) throw corrupt(`Corrupt v2 entry record: ${expectedPath}.`, expectedPath);
+  const path = parseWorkspacePath(readString(value.path, "entry path"));
+  if (path !== expectedPath) throw corrupt(`V2 entry path does not match key: ${expectedPath}.`);
+  if (value.schemaVersion !== ENTRY_SCHEMA_VERSION) {
+    throw corrupt(`Unsupported v2 entry schema at ${expectedPath}.`, expectedPath);
+  }
+  const version = parseFileSystemVersion(value.version);
+  const lastModified = readString(value.lastModified, "lastModified");
+  if (value.kind === "directory") {
+    return { schemaVersion: ENTRY_SCHEMA_VERSION, kind: "directory", path, version, lastModified };
+  }
+  if (value.kind !== "file") throw corrupt(`Unknown entry kind at ${expectedPath}.`, expectedPath);
+  return {
+    schemaVersion: ENTRY_SCHEMA_VERSION,
+    kind: "file",
+    path,
+    version,
+    lastModified,
+    data: validateBytes(value.data, expectedPath)
+  };
+}
+async function readState(tx) {
+  const raw = await tx.get(STATE_KEY);
+  return raw === null ? null : validateState(raw);
+}
+async function readRequiredState(tx) {
+  const state = await readState(tx);
+  if (!state) throw corrupt("IndexedDB v2 state record is missing.");
+  return state;
+}
+function validateState(value) {
+  if (!isRecord(value) || value.schemaVersion !== STATE_SCHEMA_VERSION || value.migrationVersion !== 1 && value.migrationVersion !== 2 || typeof value.mutationCounter !== "number" || !Number.isSafeInteger(value.mutationCounter) || value.mutationCounter < 0) {
+    throw corrupt("IndexedDB v2 state record is corrupt.");
+  }
+  return {
+    schemaVersion: STATE_SCHEMA_VERSION,
+    migrationVersion: value.migrationVersion,
+    mutationCounter: value.mutationCounter,
+    treeVersion: parseFileSystemVersion(value.treeVersion)
+  };
+}
+async function readLegacyDirectories(tx) {
+  const raw = await tx.get(LEGACY_DIRS_KEY);
+  if (raw === null) return [];
+  if (!Array.isArray(raw)) throw corrupt("Legacy directory index is corrupt.");
+  const directories = [];
+  for (const value of raw) {
+    if (typeof value !== "string") throw corrupt("Legacy directory index is corrupt.");
+    const path = parseWorkspacePath(value);
+    if (path) directories.push(path);
+  }
+  return directories;
+}
+function legacyPathsFromKeys(keys) {
+  const paths = /* @__PURE__ */ new Set();
+  for (const key of keys) {
+    if (!key.startsWith(LEGACY_PREFIX) || key === LEGACY_DIRS_KEY) continue;
+    const suffix = [LEGACY_CONTENT_SUFFIX, LEGACY_BINARY_SUFFIX, LEGACY_META_SUFFIX].find(
+      (candidate) => key.endsWith(candidate)
+    );
+    if (!suffix) continue;
+    const rawPath = key.slice(LEGACY_PREFIX.length, -suffix.length);
+    try {
+      const path = parseWorkspacePath(rawPath);
+      if (path) paths.add(path);
+    } catch {
+    }
+  }
+  return [...paths];
+}
+async function readLegacyFile(tx, path) {
+  const [rawContent, rawBinary, rawMetadata] = await Promise.all([
+    tx.get(`${LEGACY_PREFIX}${path}${LEGACY_CONTENT_SUFFIX}`),
+    tx.get(`${LEGACY_PREFIX}${path}${LEGACY_BINARY_SUFFIX}`),
+    tx.get(`${LEGACY_PREFIX}${path}${LEGACY_META_SUFFIX}`)
+  ]);
+  if (rawContent !== null && typeof rawContent !== "string") {
+    throw corrupt(`Legacy text payload is corrupt: ${path}.`, path);
+  }
+  return {
+    content: rawContent,
+    binary: rawBinary === null ? null : validateBytes(rawBinary, path),
+    metadata: validateLegacyMetadata(rawMetadata, path)
+  };
+}
+async function readMarkerPaths(transaction, keys, prefix, validate) {
+  const paths = /* @__PURE__ */ new Set();
+  for (const key of keys) {
+    if (!key.startsWith(prefix)) continue;
+    const expectedPath = parseWorkspacePath(key.slice(prefix.length));
+    if (!expectedPath) throw corrupt(`Recovery marker cannot target the workspace root: ${key}.`);
+    const value = await transaction.get(key);
+    const path = validate(value);
+    if (path !== expectedPath)
+      throw corrupt(`Recovery marker path does not match its key: ${key}.`);
+    paths.add(path);
+  }
+  return paths;
+}
+function validateIgnoredLegacyPath(value) {
+  if (!isRecord(value) || value.schemaVersion !== 1 || typeof value.ignoredAt !== "string") {
+    throw corrupt("Ignored legacy recovery marker is corrupt.");
+  }
+  const path = parseWorkspacePath(readString(value.path, "ignored legacy path"));
+  if (!path) throw corrupt("Ignored legacy recovery marker cannot target the workspace root.");
+  return path;
+}
+async function assertNoLegacyConflict(transaction, path, operation) {
+  if (await transaction.get(legacyConflictKey(path)) === null) return;
+  throw legacyConflictBlocked(path, operation);
+}
+async function assertNoLegacyConflictInSubtree(transaction, path, operation) {
+  for (const key of await transaction.keys()) {
+    if (!key.startsWith(LEGACY_CONFLICT_PREFIX)) continue;
+    const conflictPath = parseWorkspacePath(key.slice(LEGACY_CONFLICT_PREFIX.length));
+    if (conflictPath === path || workspacePathContains(path, conflictPath, false)) {
+      throw legacyConflictBlocked(conflictPath, operation);
+    }
+  }
+}
+function legacyConflictBlocked(path, operation) {
+  return new FsError(
+    "conflict",
+    "Resolve the legacy migration conflict before mutating this path.",
+    {
+      operation,
+      path,
+      retryable: false
+    }
+  );
+}
+function validateLegacyMetadata(value, path) {
+  if (value === null) return null;
+  if (!isRecord(value) || typeof value.name !== "string" || typeof value.path !== "string" || typeof value.size !== "number" || !Number.isFinite(value.size) || typeof value.lastModified !== "string") {
+    throw corrupt(`Legacy metadata is corrupt: ${path}.`, path);
+  }
+  return {
+    name: value.name,
+    path: value.path,
+    size: value.size,
+    lastModified: value.lastModified
+  };
+}
+function validateLegacyConflict(value) {
+  if (!isRecord(value)) {
+    throw corrupt("Legacy migration conflict record is corrupt.");
+  }
+  const path = parseWorkspacePath(readString(value.path, "legacy conflict path"));
+  if (!path) throw corrupt("Legacy migration conflict cannot target the workspace root.");
+  if (value.schemaVersion === LEGACY_CONFLICT_SCHEMA_VERSION_V1) {
+    const reason = validateLegacyConflictReason(value.reason);
+    const candidate = {
+      kind: "file",
+      reason,
+      text: value.text === null ? null : readString(value.text, "legacy conflict text"),
+      binary: value.binary === null ? null : validateBytes(value.binary, path),
+      metadata: validateLegacyMetadata(value.metadata, path),
+      detectedAt: readString(value.detectedAt, "legacy conflict detectedAt")
+    };
+    return {
+      schemaVersion: LEGACY_CONFLICT_SCHEMA_VERSION,
+      path,
+      candidates: Object.freeze([candidate])
+    };
+  }
+  if (value.schemaVersion !== LEGACY_CONFLICT_SCHEMA_VERSION || !Array.isArray(value.candidates)) {
+    throw corrupt("Legacy migration conflict record is corrupt.");
+  }
+  const candidates = value.candidates.map(
+    (candidate) => validateLegacyRecoveryCandidate(candidate, path)
+  );
+  if (candidates.length === 0) throw corrupt("Legacy migration conflict has no candidates.", path);
+  return {
+    schemaVersion: LEGACY_CONFLICT_SCHEMA_VERSION,
+    path,
+    candidates: Object.freeze(candidates)
+  };
+}
+function toPublicLegacyConflict(conflict) {
+  const candidates = conflict.candidates.map(toPublicLegacyCandidate);
+  const latest = candidates[candidates.length - 1];
+  return Object.freeze({
+    path: parseWorkspacePath(conflict.path),
+    reason: latest.reason,
+    kind: latest.kind,
+    text: latest.text,
+    binary: latest.binary,
+    metadata: latest.metadata,
+    detectedAt: latest.detectedAt,
+    candidates: Object.freeze(candidates)
+  });
+}
+function validateLegacyRecoveryCandidate(value, path) {
+  if (!isRecord(value) || value.kind !== "file" && value.kind !== "directory") {
+    throw corrupt("Legacy recovery candidate is corrupt.", path);
+  }
+  const kind = value.kind;
+  const text = value.text === null ? null : readString(value.text, "legacy recovery text");
+  const binary = value.binary === null ? null : validateBytes(value.binary, path);
+  const metadata = validateLegacyMetadata(value.metadata, path);
+  if (kind === "directory" && (text !== null || binary !== null || metadata !== null)) {
+    throw corrupt("A legacy directory recovery candidate contains file data.", path);
+  }
+  return {
+    kind,
+    reason: validateLegacyConflictReason(value.reason),
+    text,
+    binary,
+    metadata,
+    detectedAt: readString(value.detectedAt, "legacy recovery detectedAt")
+  };
+}
+function validateLegacyConflictReason(value) {
+  if (value === "dual-payload" || value === "kind-collision" || value === "authority-collision" || value === "stale-client-write") {
+    return value;
+  }
+  throw corrupt("Legacy recovery reason is invalid.");
+}
+function toPublicLegacyCandidate(candidate) {
+  return Object.freeze({
+    kind: candidate.kind,
+    reason: candidate.reason,
+    text: candidate.text,
+    binary: candidate.binary ? copyBytes(candidate.binary) : null,
+    metadata: candidate.metadata ? Object.freeze({ ...candidate.metadata }) : null,
+    detectedAt: candidate.detectedAt
+  });
+}
+async function appendLegacyConflict(transaction, path, candidate) {
+  const key = legacyConflictKey(path);
+  const raw = await transaction.get(key);
+  const existing = raw === null ? null : validateLegacyConflict(raw);
+  if (existing?.candidates.some((item) => recoveryCandidatesEqual(item, candidate))) return;
+  const candidates = [...existing?.candidates ?? [], copyRecoveryCandidate(candidate)];
+  await transaction.put(key, {
+    schemaVersion: LEGACY_CONFLICT_SCHEMA_VERSION,
+    path,
+    candidates
+  });
+}
+function fileRecoveryCandidate(legacy, reason, detectedAt) {
+  return {
+    kind: "file",
+    reason,
+    text: legacy.content,
+    binary: legacy.binary ? copyBytes(legacy.binary) : null,
+    metadata: legacy.metadata ? { ...legacy.metadata } : null,
+    detectedAt
+  };
+}
+function directoryRecoveryCandidate(reason, detectedAt) {
+  return { kind: "directory", reason, text: null, binary: null, metadata: null, detectedAt };
+}
+function copyRecoveryCandidate(candidate) {
+  return {
+    ...candidate,
+    binary: candidate.binary ? copyBytes(candidate.binary) : null,
+    metadata: candidate.metadata ? { ...candidate.metadata } : null
+  };
+}
+function recoveryCandidatesEqual(left, right) {
+  return left.kind === right.kind && left.text === right.text && nullableBytesEqual(left.binary, right.binary) && nullableMetadataEqual(left.metadata, right.metadata);
+}
+function nullableBytesEqual(left, right) {
+  if (left === null || right === null) return left === right;
+  return bytesEqual(left, right);
+}
+function nullableMetadataEqual(left, right) {
+  if (left === null || right === null) return left === right;
+  return left.name === right.name && left.path === right.path && left.size === right.size && left.lastModified === right.lastModified;
+}
+function legacyPayloadsMatchEntry(legacy, entry) {
+  if (legacy.content === null && legacy.binary === null) return false;
+  return (legacy.content === null || bytesEqual(new TextEncoder().encode(legacy.content), entry.data)) && (legacy.binary === null || bytesEqual(legacy.binary, entry.data));
+}
+function hasFileAncestor(entries, path) {
+  return parentChainWithRoot(path).some((parent) => entries.get(parent)?.kind === "file");
+}
+function legacyOpaqueKey(key) {
+  return `${LEGACY_OPAQUE_PREFIX}${encodeURIComponent(key)}`;
+}
+function validateLegacyOpaqueRecord(value, archiveKey) {
+  if (!isRecord(value) || !Array.isArray(value.values)) {
+    throw corrupt(`Archived legacy record is corrupt: ${archiveKey}.`);
+  }
+  const key = readString(value.key, "archived legacy key");
+  if (legacyOpaqueKey(key) !== archiveKey) {
+    throw corrupt(`Archived legacy record key does not match its key: ${archiveKey}.`);
+  }
+  if (value.schemaVersion === LEGACY_OPAQUE_SCHEMA_VERSION_V1) {
+    return {
+      schemaVersion: LEGACY_OPAQUE_SCHEMA_VERSION,
+      key,
+      values: Object.freeze(
+        value.values.map(
+          (item) => ({ value: item, archivedAt: null })
+        )
+      )
+    };
+  }
+  if (value.schemaVersion !== LEGACY_OPAQUE_SCHEMA_VERSION) {
+    throw corrupt(`Unsupported archived legacy record schema: ${archiveKey}.`);
+  }
+  const values = value.values.map((item) => {
+    if (!isRecord(item)) throw corrupt(`Archived legacy value is corrupt: ${archiveKey}.`);
+    return {
+      value: item.value,
+      // A v2 record legitimately carries null here for values it inherited from
+      // the untimestamped v1 shape, so this must stay nullable on the way back
+      // in or re-archiving a v1 record would make it permanently unreadable.
+      archivedAt: item.archivedAt === null ? null : readString(item.archivedAt, "archived legacy timestamp")
+    };
+  });
+  if (values.length === 0) throw corrupt(`Archived legacy record has no values: ${archiveKey}.`);
+  return { schemaVersion: LEGACY_OPAQUE_SCHEMA_VERSION, key, values: Object.freeze(values) };
+}
+function opaqueValueByteLength(value) {
+  if (value instanceof ArrayBuffer) return value.byteLength;
+  if (ArrayBuffer.isView(value)) return value.byteLength;
+  if (typeof value === "string") return new TextEncoder().encode(value).byteLength;
+  return null;
+}
+function toOpaqueSummary(record) {
+  let byteLength = 0;
+  for (const item of record.values) {
+    const size = opaqueValueByteLength(item.value);
+    byteLength = size === null || byteLength === null ? null : byteLength + size;
+  }
+  const stamps = record.values.map((item) => item.archivedAt);
+  return Object.freeze({
+    key: record.key,
+    valueCount: record.values.length,
+    byteLength,
+    firstArchivedAt: stamps[0] ?? null,
+    lastArchivedAt: stamps[stamps.length - 1] ?? null
+  });
+}
+function toPublicOpaqueRecord(record) {
+  return Object.freeze({
+    ...toOpaqueSummary(record),
+    values: Object.freeze(
+      record.values.map(
+        (item) => Object.freeze({
+          value: item.value instanceof ArrayBuffer ? copyBytes(item.value) : item.value,
+          byteLength: opaqueValueByteLength(item.value),
+          archivedAt: item.archivedAt
+        })
+      )
+    )
+  });
+}
+async function deleteLegacyNamespace(transaction, keys, archivedAt) {
+  for (const key of keys) {
+    if (key.startsWith(LEGACY_PREFIX) && !isRecognizedLegacyKey(key)) {
+      const archiveKey = legacyOpaqueKey(key);
+      const existing = await transaction.get(archiveKey);
+      const values = existing === null ? [] : validateLegacyOpaqueRecord(existing, archiveKey).values;
+      await transaction.put(archiveKey, {
+        schemaVersion: LEGACY_OPAQUE_SCHEMA_VERSION,
+        key,
+        values: [...values, { value: await transaction.get(key), archivedAt }]
+      });
+    }
+    if (key.startsWith(LEGACY_PREFIX) || key.startsWith(LEGACY_IGNORED_PREFIX))
+      await transaction.delete(key);
+  }
+}
+function isRecognizedLegacyKey(key) {
+  if (key === LEGACY_DIRS_KEY) return true;
+  const suffix = [LEGACY_CONTENT_SUFFIX, LEGACY_BINARY_SUFFIX, LEGACY_META_SUFFIX].find(
+    (item) => key.endsWith(item)
+  );
+  if (!suffix) return false;
+  const rawPath = key.slice(LEGACY_PREFIX.length, -suffix.length);
+  try {
+    const path = parseWorkspacePath(rawPath);
+    return path !== WORKSPACE_ROOT && path === rawPath;
+  } catch {
+    return false;
+  }
+}
+function selectLegacyPayload(conflict, resolution, path) {
+  const payload = typeof resolution === "string" ? resolution : resolution.payload;
+  const eligible = typeof resolution === "string" ? conflict.candidates.filter(
+    (candidate2) => candidate2.kind === "file" && (payload === "text" ? candidate2.text !== null : candidate2.binary !== null)
+  ) : [conflict.candidates[resolution.candidate]].filter(
+    (candidate2) => candidate2 !== void 0
+  );
+  if (eligible.length !== 1) {
+    throw new FsError(
+      "conflict",
+      "Choose an explicit recovery candidate because multiple legacy versions are quarantined.",
+      { operation: "write", path, retryable: false }
+    );
+  }
+  const candidate = eligible[0];
+  if (payload === "directory") {
+    if (candidate.kind !== "directory") {
+      throw new FsError("type-mismatch", "The selected recovery candidate is not a directory.", {
+        operation: "write",
+        path
+      });
+    }
+    return { kind: "directory" };
+  }
+  if (candidate.kind !== "file") {
+    throw new FsError("type-mismatch", "The selected recovery candidate is a directory.", {
+      operation: "write",
+      path
+    });
+  }
+  const data = payload === "text" ? candidate.text === null ? null : new TextEncoder().encode(candidate.text).buffer : candidate.binary;
+  if (data === null) {
+    throw new FsError("type-mismatch", `The selected candidate has no ${payload} payload.`, {
+      operation: "write",
+      path
+    });
+  }
+  return { kind: "file", data: copyBytes(data) };
+}
+function addParentDirectories(entries, path, version, lastModified) {
+  for (const parent of parentChainWithRoot(path)) {
+    if (!entries.has(parent)) entries.set(parent, directoryRecord(parent, version, lastModified));
+  }
+}
+function directoryRecord(path, version, lastModified) {
+  return {
+    schemaVersion: ENTRY_SCHEMA_VERSION,
+    kind: "directory",
+    path,
+    version,
+    lastModified
+  };
+}
+function withPathAndVersion(entry, path, next) {
+  return entry.kind === "file" ? {
+    schemaVersion: ENTRY_SCHEMA_VERSION,
+    kind: "file",
+    path,
+    data: copyBytes(entry.data),
+    version: next.version,
+    lastModified: next.lastModified
+  } : directoryRecord(path, next.version, next.lastModified);
+}
+function copyEntry(entry) {
+  return entry.kind === "file" ? { ...entry, data: copyBytes(entry.data) } : { ...entry };
+}
+function toEntrySnapshot(entry) {
+  return entry.kind === "file" ? toFileSnapshot(entry) : toDirectorySnapshot(entry);
+}
+function toFileSnapshot(entry) {
+  return Object.freeze({
+    kind: "file",
+    path: parseWorkspacePath(entry.path),
+    name: workspacePathBasename(parseWorkspacePath(entry.path)),
+    size: entry.data.byteLength,
+    version: parseFileSystemVersion(entry.version),
+    lastModified: entry.lastModified
+  });
+}
+function toDirectorySnapshot(entry) {
+  const path = parseWorkspacePath(entry.path);
+  return Object.freeze({
+    kind: "directory",
+    path,
+    name: workspacePathBasename(path),
+    size: null,
+    version: parseFileSystemVersion(entry.version),
+    lastModified: entry.lastModified
+  });
+}
+function validateBytes(value, path) {
+  if (value instanceof ArrayBuffer) return copyBytes(value);
+  if (value instanceof Uint8Array) return copyBytes(value);
+  throw corrupt(`Stored file bytes are corrupt: ${path}.`, path);
+}
+function readString(value, label) {
+  if (typeof value !== "string") throw corrupt(`Invalid ${label}.`);
+  return value;
+}
+function corrupt(message, path) {
+  return new FsError("io", message, { operation: "read", path, retryable: false });
+}
+
+// src/filesystem/indexeddb-provider.ts
+var IndexedDBFileSystemProvider = class {
+  constructor(id, label, options = {}) {
+    this.disposed = false;
+    this.id = id;
+    this.label = label;
+    const store = options.store ?? new RawIndexedDBFileSystemStore(indexedDBWorkspaceDatabaseName(id), "files");
+    this.v2 = new IndexedDBFileSystemProviderV2(id, label, {
+      store,
+      now: options.now,
+      closeStoreOnDispose: true
+    });
+  }
+  /** Release the underlying database connection after accepted work settles. */
+  dispose() {
+    this.disposed = true;
+    return this.v2.dispose();
+  }
+  async readFile(path) {
+    this.assertOpen("read");
+    const canonical = this.path(path);
+    const read = await this.v2.readFile(canonical);
+    return read ? this.decode(read.data, canonical, "read") : null;
+  }
+  async writeFile(path, content) {
+    this.assertOpen("write");
+    await this.v2.writeFile(this.path(path), new TextEncoder().encode(content), {
+      createParents: true
+    });
+  }
+  async commitFile(path, content, expectedContent) {
+    this.assertOpen("write");
+    const canonical = this.path(path);
+    const current = await this.v2.readFile(canonical);
+    const currentContent = current ? this.decode(current.data, canonical, "write") : null;
+    if (currentContent !== expectedContent && currentContent !== content) {
+      return {
+        status: "conflict",
+        content: currentContent,
+        version: current?.entry.version ?? null
+      };
+    }
+    try {
+      const committed = await this.v2.writeFile(canonical, new TextEncoder().encode(content), {
+        createParents: true,
+        expectedVersion: current?.entry.version ?? null
+      });
+      return { status: "committed", version: committed.version };
+    } catch (error) {
+      if (!(error instanceof FsError) || error.code !== "conflict") throw error;
+      const latest = await this.v2.readFile(canonical);
+      return {
+        status: "conflict",
+        content: latest ? this.decode(latest.data, canonical, "write") : null,
+        version: latest?.entry.version ?? null
+      };
+    }
+  }
+  async delete(path) {
+    this.assertOpen("remove");
+    await this.v2.remove(this.path(path), {
+      recursive: true,
+      missing: "ignore"
+    });
+  }
+  async rename(oldPath, newPath) {
+    this.assertOpen("move");
+    await this.v2.move(this.path(oldPath), this.path(newPath), {
+      createParents: true
+    });
+  }
+  async readDirectory(path) {
+    this.assertOpen("list");
+    try {
+      const entries = await this.v2.readDirectory(this.path(path));
+      return entries.map((entry) => ({
+        kind: entry.kind,
+        name: entry.name,
+        path: entry.path
+      }));
+    } catch (error) {
+      if (error instanceof FsError && error.code === "not-found") return [];
+      throw error;
+    }
+  }
+  async exists(path) {
+    this.assertOpen("stat");
+    return await this.v2.stat(this.path(path)) !== null;
+  }
+  async createDirectory(path) {
+    this.assertOpen("create-directory");
+    await this.v2.createDirectory(this.path(path), {
+      createParents: true,
+      mode: "ensure"
+    });
+  }
+  async stat(path) {
+    this.assertOpen("stat");
+    const entry = await this.v2.stat(this.path(path));
+    if (!entry || entry.kind !== "file") return null;
+    return {
+      name: entry.name,
+      path: entry.path,
+      size: entry.size,
+      lastModified: entry.lastModified
+    };
+  }
+  async readBinary(path) {
+    this.assertOpen("read");
+    return (await this.v2.readFile(this.path(path)))?.data ?? null;
+  }
+  async writeBinary(path, data) {
+    this.assertOpen("write");
+    await this.v2.writeFile(this.path(path), data, { createParents: true });
+  }
+  /**
+   * Canonicalize only. Root policy is the v2 authority's to state: it accepts
+   * the root wherever the root is a legitimate target (`stat`, `readDirectory`,
+   * `createDirectory`) and rejects it with one consistent code and message
+   * everywhere else. Re-deriving that policy here is how this facade previously
+   * drifted from both v2 and its sibling facades.
+   */
+  path(path) {
+    return parseWorkspacePath(path);
+  }
+  /**
+   * Byte-authoritative entries may hold payloads that are not valid UTF-8. A
+   * lossy decode would hand the caller replacement characters that a later save
+   * writes back over the user's original bytes, so surface the fault instead.
+   */
+  decode(data, path, operation) {
+    return decodeUtf8Text(data, { label: "The file", operation, path });
+  }
+  assertOpen(operation) {
+    if (!this.disposed) return;
+    throw new FsError("disposed", "Filesystem provider is disposed.", { operation });
+  }
+};
+
+// src/filesystem/indexeddb-content-container.ts
+import { findDocumentPath } from "@bendyline/squisq/storage";
+
+// src/filesystem/internal/mime.ts
+var EXTENSION_MIME_MAP = {
+  ".md": "text/markdown",
+  ".txt": "text/plain",
+  ".json": "application/json",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".png": "image/png",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+  ".mp3": "audio/mpeg",
+  ".wav": "audio/wav",
+  ".ogg": "audio/ogg"
+};
+function guessMimeType(path) {
+  const dot = path.lastIndexOf(".");
+  if (dot === -1) return "application/octet-stream";
+  const ext = path.slice(dot).toLowerCase();
+  return EXTENSION_MIME_MAP[ext] ?? "application/octet-stream";
+}
+
+// src/filesystem/indexeddb-content-container.ts
+var IndexedDBContentContainer = class {
+  constructor(workspaceId) {
+    this.provider = new IndexedDBFileSystemProviderV2(`${workspaceId}-media`, "Media Storage");
+  }
+  async readFile(path) {
+    return (await this.provider.readFile(parseWorkspacePath(path)))?.data ?? null;
+  }
+  async writeFile(path, data, _mimeType) {
+    await this.provider.writeFile(parseWorkspacePath(path), data, {
+      mode: "upsert",
+      createParents: true
+    });
+  }
+  async removeFile(path) {
+    await this.provider.remove(parseWorkspacePath(path), { missing: "ignore" });
+  }
+  async listFiles(prefix) {
+    const entries = [];
+    const walk = async (dir) => {
+      const children = await this.provider.readDirectory(parseWorkspacePath(dir));
+      for (const child of children) {
+        if (child.kind === "directory") {
+          await walk(child.path);
+        } else {
+          const filePath = child.path;
+          if (prefix && !filePath.startsWith(prefix)) continue;
+          entries.push({
+            path: filePath,
+            mimeType: guessMimeType(filePath),
+            size: child.size
+          });
+        }
+      }
+    };
+    await walk(WORKSPACE_ROOT);
+    return entries;
+  }
+  async exists(path) {
+    return await this.provider.stat(parseWorkspacePath(path)) !== null;
+  }
+  async getDocumentPath() {
+    return findDocumentPath(await this.listFiles());
+  }
+  async readDocument() {
+    const docPath = await this.getDocumentPath();
+    if (!docPath) return null;
+    const data = await this.readFile(docPath);
+    if (!data) return null;
+    return new TextDecoder().decode(data);
+  }
+  async writeDocument(markdown, filename) {
+    const name = filename ?? "index.md";
+    const data = new TextEncoder().encode(markdown);
+    await this.writeFile(name, data, "text/markdown");
+  }
+  /** Release the IndexedDB connection when a long-lived container is retired. */
+  async dispose() {
+    await this.provider.dispose();
+  }
+};
+
+export {
+  IndexedDBFileSystemProviderV2,
+  IndexedDBFileSystemProvider,
+  guessMimeType,
+  IndexedDBContentContainer
+};
+//# sourceMappingURL=chunk-6IYMTYMQ.js.map