@frostpillar/frostpillar-storage-engine 0.0.1

package/dist/index.cjs

@@ -0,0 +1,2957 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BinaryFormatError: () => BinaryFormatError,
+  ClosedDatastoreError: () => ClosedDatastoreError,
+  ConfigurationError: () => ConfigurationError,
+  DatabaseLockedError: () => DatabaseLockedError,
+  Datastore: () => Datastore,
+  FrostpillarError: () => FrostpillarError,
+  IndexCorruptionError: () => IndexCorruptionError,
+  InvalidQueryRangeError: () => InvalidQueryRangeError,
+  PageCorruptionError: () => PageCorruptionError,
+  QuotaExceededError: () => QuotaExceededError,
+  StorageEngineError: () => StorageEngineError,
+  UnsupportedBackendError: () => UnsupportedBackendError,
+  ValidationError: () => ValidationError,
+  indexedDBDriver: () => indexedDBDriver,
+  localStorageDriver: () => localStorageDriver,
+  opfsDriver: () => opfsDriver,
+  syncStorageDriver: () => syncStorageDriver
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors/index.ts
+var FrostpillarError = class extends Error {
+  constructor(message, options) {
+    super(message);
+    this.name = new.target.name;
+    if (options !== void 0) {
+      this.cause = options.cause;
+    }
+  }
+};
+var ValidationError = class extends FrostpillarError {
+};
+var InvalidQueryRangeError = class extends FrostpillarError {
+};
+var ConfigurationError = class extends FrostpillarError {
+};
+var UnsupportedBackendError = class extends FrostpillarError {
+};
+var ClosedDatastoreError = class extends FrostpillarError {
+};
+var StorageEngineError = class extends FrostpillarError {
+};
+var DatabaseLockedError = class extends StorageEngineError {
+};
+var BinaryFormatError = class extends StorageEngineError {
+};
+var PageCorruptionError = class extends StorageEngineError {
+};
+var IndexCorruptionError = class extends StorageEngineError {
+};
+var QuotaExceededError = class extends FrostpillarError {
+};
+var toStorageEngineError = (error, fallbackMessage) => {
+  if (error instanceof StorageEngineError) {
+    return error;
+  }
+  if (error instanceof Error) {
+    return new StorageEngineError(`${fallbackMessage}: ${error.message}`, {
+      cause: error
+    });
+  }
+  return new StorageEngineError(fallbackMessage, { cause: error });
+};
+var toErrorInstance = (error, fallbackMessage) => {
+  if (error instanceof Error) {
+    return error;
+  }
+  return new Error(fallbackMessage, { cause: error });
+};
+
+// src/storage/record/ordering.ts
+var toPublicRecord = (entryId, key, record) => {
+  return {
+    _id: entryId,
+    key,
+    payload: record.payload
+  };
+};
+
+// src/storage/backend/autoCommit.ts
+var emitAutoCommitErrorToListeners = (listeners, error) => {
+  const storageError = error instanceof StorageEngineError ? error : new StorageEngineError(
+    error instanceof Error ? error.message : "Unknown auto-commit storage failure.",
+    { cause: error }
+  );
+  const event = {
+    source: "autoCommit",
+    error: storageError,
+    occurredAt: Date.now()
+  };
+  for (const listener of listeners) {
+    try {
+      const delivered = listener(event);
+      void Promise.resolve(delivered).catch(() => void 0);
+    } catch {
+    }
+  }
+};
+
+// src/storage/backend/asyncMutex.ts
+var AsyncMutex = class {
+  constructor() {
+    this.queue = [];
+    this.head = 0;
+    this.locked = false;
+  }
+  acquire() {
+    if (!this.locked) {
+      this.locked = true;
+      return Promise.resolve(this.createRelease());
+    }
+    return new Promise((resolve) => {
+      this.queue.push(() => resolve(this.createRelease()));
+    });
+  }
+  createRelease() {
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      if (this.head < this.queue.length) {
+        const next = this.queue[this.head];
+        this.queue[this.head] = void 0;
+        this.head += 1;
+        if (this.head > 1024 && this.head > this.queue.length >>> 1) {
+          this.queue = this.queue.slice(this.head);
+          this.head = 0;
+        }
+        next();
+      } else {
+        this.queue.length = 0;
+        this.head = 0;
+        this.locked = false;
+      }
+    };
+  }
+};
+
+// src/storage/backend/encoding.ts
+var computeUtf8ByteLengthJs = (value) => {
+  let bytes = 0;
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code <= 127) {
+      bytes += 1;
+    } else if (code <= 2047) {
+      bytes += 2;
+    } else if (code >= 55296 && code <= 56319) {
+      const next = i + 1 < value.length ? value.charCodeAt(i + 1) : 0;
+      if (next >= 56320 && next <= 57343) {
+        bytes += 4;
+        i++;
+      } else {
+        bytes += 3;
+      }
+    } else if (code >= 56320 && code <= 57343) {
+      bytes += 3;
+    } else {
+      bytes += 3;
+    }
+  }
+  return bytes;
+};
+var hasBuffer = typeof Buffer !== "undefined" && typeof Buffer.byteLength === "function";
+var computeUtf8ByteLength = hasBuffer ? (value) => Buffer.byteLength(value, "utf8") : computeUtf8ByteLengthJs;
+var estimateJsonStringBytes = (value) => {
+  let bytes = 2;
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code === 34 || code === 92) {
+      bytes += 2;
+    } else if (code <= 31) {
+      if (code === 8 || code === 9 || code === 10 || code === 12 || code === 13) {
+        bytes += 2;
+      } else {
+        bytes += 6;
+      }
+    } else if (code <= 127) {
+      bytes += 1;
+    } else if (code <= 2047) {
+      bytes += 2;
+    } else if (code >= 55296 && code <= 56319) {
+      const next = i + 1 < value.length ? value.charCodeAt(i + 1) : 0;
+      if (next >= 56320 && next <= 57343) {
+        bytes += 4;
+        i++;
+      } else {
+        bytes += 6;
+      }
+    } else if (code >= 56320 && code <= 57343) {
+      bytes += 6;
+    } else {
+      bytes += 3;
+    }
+  }
+  return bytes;
+};
+var estimateObjectSizeBytes = (value) => {
+  if (value === null) {
+    return 4;
+  }
+  switch (typeof value) {
+    case "boolean":
+      return value ? 4 : 5;
+    // "true" / "false"
+    case "number":
+      return String(value).length;
+    case "string":
+      return estimateJsonStringBytes(value);
+    case "object": {
+      const obj = value;
+      let size = 2;
+      let visibleCount = 0;
+      for (const k of Object.keys(obj)) {
+        const v = obj[k];
+        if (v === void 0) {
+          continue;
+        }
+        if (visibleCount > 0) {
+          size += 1;
+        }
+        size += estimateJsonStringBytes(k) + 1;
+        size += estimateObjectSizeBytes(v);
+        visibleCount++;
+      }
+      return size;
+    }
+    default:
+      return 0;
+  }
+};
+var JSON_ROOT_WRAPPER_OVERHEAD = 15;
+var estimateRecordSizeBytes = (key, payload) => {
+  return estimateObjectSizeBytes(key) + estimateObjectSizeBytes(payload) + JSON_ROOT_WRAPPER_OVERHEAD;
+};
+var estimateKeySizeBytes = (key) => {
+  return estimateObjectSizeBytes(key);
+};
+
+// src/validation/payload.ts
+var MAX_PAYLOAD_DEPTH = 64;
+var MAX_PAYLOAD_KEY_BYTES = 1024;
+var MAX_PAYLOAD_STRING_BYTES = 65535;
+var MAX_PAYLOAD_KEYS_PER_OBJECT = 256;
+var MAX_PAYLOAD_KEYS_TOTAL = 4096;
+var MAX_PAYLOAD_TOTAL_BYTES = 1048576;
+var NULL_ESTIMATION_BYTES = 4;
+var JSON_KEY_COLON_OVERHEAD = 1;
+var JSON_OBJECT_BRACE_OVERHEAD = 2;
+var JSON_ROOT_WRAPPER_OVERHEAD2 = 15;
+var isPlainObject = (value) => {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  if (Array.isArray(value)) {
+    return false;
+  }
+  const objectValue = value;
+  const prototype = Object.getPrototypeOf(objectValue);
+  return prototype === Object.prototype || prototype === null;
+};
+var addValidationBytes = (state, bytes) => {
+  state.totalValidationBytes += bytes;
+  if (state.totalValidationBytes > MAX_PAYLOAD_TOTAL_BYTES) {
+    throw new ValidationError(
+      `Payload aggregate validation bytes must be <= ${MAX_PAYLOAD_TOTAL_BYTES}.`
+    );
+  }
+};
+var validatePayloadKey = (key, state) => {
+  if (key.trim().length === 0) {
+    throw new ValidationError("Payload keys must be non-empty strings.");
+  }
+  if (key === "__proto__" || key === "constructor" || key === "prototype") {
+    throw new ValidationError(
+      `Payload key "${key}" is reserved and not allowed.`
+    );
+  }
+  const keyBytes = computeUtf8ByteLength(key);
+  if (keyBytes > MAX_PAYLOAD_KEY_BYTES) {
+    throw new ValidationError(
+      `Payload key UTF-8 byte length must be <= ${MAX_PAYLOAD_KEY_BYTES}.`
+    );
+  }
+  state.totalKeyCount += 1;
+  if (state.totalKeyCount > MAX_PAYLOAD_KEYS_TOTAL) {
+    throw new ValidationError(
+      `Payload total key count must be <= ${MAX_PAYLOAD_KEYS_TOTAL}.`
+    );
+  }
+  addValidationBytes(state, estimateJsonStringBytes(key) + JSON_KEY_COLON_OVERHEAD);
+};
+var validateAndCloneValue = (value, depth, state) => {
+  if (value === null) {
+    addValidationBytes(state, NULL_ESTIMATION_BYTES);
+    return null;
+  }
+  if (typeof value === "string") {
+    const stringBytes = computeUtf8ByteLength(value);
+    if (stringBytes > MAX_PAYLOAD_STRING_BYTES) {
+      throw new ValidationError(
+        `Payload string UTF-8 byte length must be <= ${MAX_PAYLOAD_STRING_BYTES}.`
+      );
+    }
+    addValidationBytes(state, estimateJsonStringBytes(value));
+    return value;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new ValidationError("Payload number values must be finite.");
+    }
+    addValidationBytes(state, String(value).length);
+    return value;
+  }
+  if (typeof value === "boolean") {
+    addValidationBytes(state, value ? 4 : 5);
+    return value;
+  }
+  if (typeof value === "bigint") {
+    throw new ValidationError("Payload bigint values are not supported.");
+  }
+  if (typeof value === "object") {
+    if (Array.isArray(value)) {
+      throw new ValidationError("Payload arrays are not supported.");
+    }
+    if (!isPlainObject(value)) {
+      throw new ValidationError("Payload values must be plain objects.");
+    }
+    return validateAndClonePayloadObject(value, depth + 1, state);
+  }
+  throw new ValidationError(
+    "Payload values must be string | number | boolean | null or nested object."
+  );
+};
+var validateAndClonePayloadObject = (payloadObject, depth, state) => {
+  const objectLevel = depth + 1;
+  if (objectLevel > MAX_PAYLOAD_DEPTH) {
+    throw new ValidationError(`Payload nesting depth must be <= ${MAX_PAYLOAD_DEPTH}.`);
+  }
+  if (state.activePath.has(payloadObject)) {
+    throw new ValidationError("Circular payload references are not supported.");
+  }
+  const entries = Object.entries(payloadObject);
+  if (entries.length > MAX_PAYLOAD_KEYS_PER_OBJECT) {
+    throw new ValidationError(`Payload object key count must be <= ${MAX_PAYLOAD_KEYS_PER_OBJECT}.`);
+  }
+  state.activePath.add(payloadObject);
+  const entryCount = entries.length;
+  const commaBytes = entryCount > 1 ? entryCount - 1 : 0;
+  addValidationBytes(state, JSON_OBJECT_BRACE_OVERHEAD + commaBytes);
+  const copied = {};
+  for (const [key, value] of entries) {
+    validatePayloadKey(key, state);
+    copied[key] = validateAndCloneValue(value, depth, state);
+  }
+  state.activePath.delete(payloadObject);
+  return copied;
+};
+var validateAndNormalizePayload = (payload) => {
+  if (!isPlainObject(payload)) {
+    throw new ValidationError("payload must be a non-null plain object.");
+  }
+  const state = {
+    activePath: /* @__PURE__ */ new WeakSet(),
+    totalKeyCount: 0,
+    totalValidationBytes: 0
+  };
+  const cloned = validateAndClonePayloadObject(payload, 0, state);
+  const sizeBytes = state.totalValidationBytes + JSON_ROOT_WRAPPER_OVERHEAD2;
+  return { payload: cloned, sizeBytes };
+};
+
+// src/storage/backend/capacity.ts
+var enforceCapacityPolicy = (capacityState, currentSizeBytes, encodedBytes, getRecordCount, evictOldestRecord) => {
+  if (capacityState === null) {
+    return currentSizeBytes;
+  }
+  if (encodedBytes > capacityState.maxSizeBytes) {
+    throw new QuotaExceededError(
+      "Record exceeds configured capacity.maxSize boundary."
+    );
+  }
+  if (capacityState.policy === "strict") {
+    if (currentSizeBytes + encodedBytes > capacityState.maxSizeBytes) {
+      throw new QuotaExceededError(
+        "Insert exceeds configured capacity.maxSize under strict policy."
+      );
+    }
+    return currentSizeBytes;
+  }
+  let nextSizeBytes = currentSizeBytes;
+  while (nextSizeBytes + encodedBytes > capacityState.maxSizeBytes) {
+    if (getRecordCount() === 0) {
+      throw new QuotaExceededError(
+        "Record cannot fit in turnover policy with empty datastore."
+      );
+    }
+    const evictedBytes = evictOldestRecord();
+    if (!Number.isSafeInteger(evictedBytes) || evictedBytes <= 0) {
+      throw new IndexCorruptionError(
+        "Turnover eviction reported non-progressing reclaimed bytes."
+      );
+    }
+    nextSizeBytes -= evictedBytes;
+  }
+  return Math.max(0, nextSizeBytes);
+};
+
+// src/storage/config/config.shared.ts
+var BYTE_SIZE_REGEX = /^(\d+)(B|KB|MB|GB)$/;
+var BYTE_SIZE_MULTIPLIER = {
+  B: 1,
+  KB: 1024,
+  MB: 1024 * 1024,
+  GB: 1024 * 1024 * 1024
+};
+var FREQUENCY_REGEX = /^(\d+)(ms|s|m|h)$/;
+var FREQUENCY_MULTIPLIER = {
+  ms: 1,
+  s: 1e3,
+  m: 60 * 1e3,
+  h: 60 * 60 * 1e3
+};
+var normalizeByteSizeInput = (value) => {
+  if (value === "backendLimit") {
+    throw new ConfigurationError(
+      'capacity.maxSize "backendLimit" must be resolved before capacity parsing.'
+    );
+  }
+  if (typeof value === "number") {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+      throw new ConfigurationError(
+        "capacity.maxSize must be a positive safe integer."
+      );
+    }
+    return value;
+  }
+  const matched = BYTE_SIZE_REGEX.exec(value);
+  if (matched === null) {
+    throw new ConfigurationError(
+      "capacity.maxSize string must be <positive><B|KB|MB|GB>."
+    );
+  }
+  const amount = Number(matched[1]);
+  if (!Number.isSafeInteger(amount) || amount <= 0) {
+    throw new ConfigurationError(
+      "capacity.maxSize must be a positive safe integer."
+    );
+  }
+  const unit = matched[2];
+  const multiplier = BYTE_SIZE_MULTIPLIER[unit];
+  const total = amount * multiplier;
+  if (!Number.isSafeInteger(total) || total <= 0) {
+    throw new ConfigurationError("capacity.maxSize exceeds safe integer range.");
+  }
+  return total;
+};
+var parseCapacityConfig = (capacity) => {
+  if (capacity === void 0) {
+    return null;
+  }
+  const maxSizeBytes = normalizeByteSizeInput(capacity.maxSize);
+  const policy = capacity.policy ?? "strict";
+  if (policy !== "strict" && policy !== "turnover") {
+    throw new ConfigurationError('capacity.policy must be "strict" or "turnover".');
+  }
+  return { maxSizeBytes, policy };
+};
+var parseFrequencyString = (frequency) => {
+  const matched = FREQUENCY_REGEX.exec(frequency);
+  if (matched === null) {
+    throw new ConfigurationError(
+      "autoCommit.frequency string must be one of: <positive>ms, <positive>s, <positive>m, <positive>h."
+    );
+  }
+  const amount = Number(matched[1]);
+  if (!Number.isSafeInteger(amount) || amount <= 0) {
+    throw new ConfigurationError(
+      "autoCommit.frequency string amount must be a positive safe integer."
+    );
+  }
+  const unit = matched[2];
+  const multiplier = FREQUENCY_MULTIPLIER[unit];
+  const intervalMs = amount * multiplier;
+  if (!Number.isSafeInteger(intervalMs) || intervalMs <= 0) {
+    throw new ConfigurationError(
+      "autoCommit.frequency exceeds safe integer range."
+    );
+  }
+  return intervalMs;
+};
+var parseAutoCommitConfig = (autoCommit) => {
+  if (autoCommit?.maxPendingBytes !== void 0) {
+    if (!Number.isSafeInteger(autoCommit.maxPendingBytes) || autoCommit.maxPendingBytes <= 0) {
+      throw new ConfigurationError(
+        "autoCommit.maxPendingBytes must be a positive safe integer."
+      );
+    }
+  }
+  const maxPendingBytes = autoCommit?.maxPendingBytes ?? null;
+  const frequency = autoCommit?.frequency;
+  if (frequency === void 0 || frequency === "immediate") {
+    return { frequency: "immediate", intervalMs: null, maxPendingBytes };
+  }
+  if (typeof frequency === "number") {
+    if (!Number.isSafeInteger(frequency) || frequency <= 0) {
+      throw new ConfigurationError(
+        "autoCommit.frequency number must be a positive safe integer."
+      );
+    }
+    return { frequency: "scheduled", intervalMs: frequency, maxPendingBytes };
+  }
+  const intervalMs = parseFrequencyString(frequency);
+  return { frequency: "scheduled", intervalMs, maxPendingBytes };
+};
+var VALID_DUPLICATE_KEY_POLICIES = [
+  "allow",
+  "replace",
+  "reject"
+];
+var parseDuplicateKeyConfig = (duplicateKeys) => {
+  if (duplicateKeys === void 0) {
+    return "allow";
+  }
+  if (!VALID_DUPLICATE_KEY_POLICIES.includes(duplicateKeys)) {
+    throw new ConfigurationError(
+      'duplicateKeys must be "allow", "replace", or "reject".'
+    );
+  }
+  return duplicateKeys;
+};
+
+// src/storage/backend/capacityResolver.ts
+var resolveCapacityConfigWithBackendLimit = (config) => {
+  if (config.capacity === void 0) {
+    return void 0;
+  }
+  if (config.capacity.maxSize !== "backendLimit") {
+    return config.capacity;
+  }
+  if (config.driver === void 0) {
+    throw new ConfigurationError(
+      'capacity.maxSize "backendLimit" requires a durable driver.'
+    );
+  }
+  if (config.driver.resolveBackendLimitBytes === void 0) {
+    throw new ConfigurationError(
+      'capacity.maxSize "backendLimit" is not supported by the selected driver.'
+    );
+  }
+  const resolvedMaxSize = config.driver.resolveBackendLimitBytes();
+  return {
+    ...config.capacity,
+    maxSize: resolvedMaxSize
+  };
+};
+var resolveCapacityState = (config) => {
+  const resolvedCapacityConfig = resolveCapacityConfigWithBackendLimit(config);
+  return parseCapacityConfig(resolvedCapacityConfig);
+};
+
+// src/storage/datastore/datastoreLifecycle.ts
+var DatastoreLifecycle = class {
+  constructor() {
+    this.closed = false;
+    this.closing = false;
+    this.closeInFlight = null;
+    this.activeOperationCount = 0;
+    this.activeOperationsDrained = null;
+    this.resolveActiveOperationsDrained = null;
+  }
+  isClosed() {
+    return this.closed;
+  }
+  markClosing() {
+    this.closing = true;
+  }
+  markClosed() {
+    this.closed = true;
+    this.closing = false;
+  }
+  getCloseInFlight() {
+    return this.closeInFlight;
+  }
+  setCloseInFlight(closeInFlight) {
+    this.closeInFlight = closeInFlight;
+  }
+  ensureOpen() {
+    if (this.closed || this.closing) {
+      throw new ClosedDatastoreError("Datastore has been closed.");
+    }
+  }
+  beginOperation() {
+    this.ensureOpen();
+    this.activeOperationCount += 1;
+  }
+  endOperation() {
+    this.activeOperationCount -= 1;
+    if (this.activeOperationCount === 0 && this.resolveActiveOperationsDrained !== null) {
+      const resolve = this.resolveActiveOperationsDrained;
+      this.resolveActiveOperationsDrained = null;
+      this.activeOperationsDrained = null;
+      resolve();
+    }
+  }
+  waitForActiveOperationsToDrain() {
+    if (this.activeOperationCount === 0) {
+      return Promise.resolve();
+    }
+    if (this.activeOperationsDrained === null) {
+      this.activeOperationsDrained = new Promise((resolve) => {
+        this.resolveActiveOperationsDrained = resolve;
+      });
+    }
+    return this.activeOperationsDrained;
+  }
+};
+
+// src/storage/datastore/mutationById.ts
+var getPublicRecordById = (keyIndex, entryId) => {
+  const entry = keyIndex.peekById(entryId);
+  if (entry === null) {
+    return null;
+  }
+  return toPublicRecord(entryId, entry.key, entry.value);
+};
+var buildMergedPayload = (targetRecord, patch, entryKey, skipValidation) => {
+  const merged = { ...targetRecord.payload, ...patch };
+  if (skipValidation) {
+    return {
+      payload: merged,
+      sizeBytes: estimateRecordSizeBytes(entryKey, merged)
+    };
+  }
+  const validationResult = validateAndNormalizePayload(merged);
+  const keyBytes = estimateKeySizeBytes(entryKey);
+  return {
+    payload: validationResult.payload,
+    sizeBytes: validationResult.sizeBytes + keyBytes
+  };
+};
+var updateRecordById = (options) => {
+  const entry = options.keyIndex.peekById(options.id);
+  if (entry === null) {
+    return { updated: false, currentSizeBytes: options.currentSizeBytes, durabilitySignalBytes: 0 };
+  }
+  const targetRecord = entry.value;
+  const oldSize = targetRecord.sizeBytes;
+  const mergedResult = buildMergedPayload(targetRecord, options.patch, entry.key, options.skipPayloadValidation);
+  const mergedPayload = mergedResult.payload;
+  const newSize = mergedResult.sizeBytes;
+  const encodedDelta = newSize - oldSize;
+  if (options.capacityState !== null && encodedDelta > 0 && options.currentSizeBytes + encodedDelta > options.capacityState.maxSizeBytes) {
+    throw new QuotaExceededError("updateById exceeds configured capacity.maxSize boundary.");
+  }
+  const updatedRecord = {
+    payload: mergedPayload,
+    sizeBytes: newSize
+  };
+  if (options.keyIndex.updateById(options.id, updatedRecord) === null) {
+    throw new IndexCorruptionError("Record index state is inconsistent during updateById.");
+  }
+  return {
+    updated: true,
+    currentSizeBytes: Math.max(0, options.currentSizeBytes + encodedDelta),
+    durabilitySignalBytes: Math.abs(encodedDelta)
+  };
+};
+var deleteRecordById = (options) => {
+  const removedFromIndex = options.keyIndex.removeById(options.id);
+  if (removedFromIndex === null) {
+    return {
+      deleted: false,
+      currentSizeBytes: options.currentSizeBytes,
+      durabilitySignalBytes: 0
+    };
+  }
+  const freedBytes = removedFromIndex.value.sizeBytes;
+  return {
+    deleted: true,
+    currentSizeBytes: Math.max(
+      0,
+      options.currentSizeBytes - freedBytes
+    ),
+    durabilitySignalBytes: freedBytes
+  };
+};
+
+// src/storage/datastore/datastoreClose.ts
+var readAggregateErrorConstructor = () => {
+  const candidate = globalThis.AggregateError;
+  if (typeof candidate !== "function") {
+    return null;
+  }
+  return candidate;
+};
+var createCloseAggregateError = (deferredError, closeError) => {
+  const aggregateErrorConstructor = readAggregateErrorConstructor();
+  if (aggregateErrorConstructor !== null) {
+    return new aggregateErrorConstructor(
+      [deferredError, closeError],
+      "Datastore close failed with multiple errors."
+    );
+  }
+  const fallbackError = new Error(
+    "Datastore close failed with multiple errors."
+  );
+  fallbackError.errors = [deferredError, closeError];
+  return fallbackError;
+};
+var closeDatastore = async (options) => {
+  if (options.lifecycle.isClosed()) {
+    return;
+  }
+  const closeInFlight = options.lifecycle.getCloseInFlight();
+  if (closeInFlight !== null) {
+    await closeInFlight;
+    return;
+  }
+  options.lifecycle.markClosing();
+  const closeOperation = performClose(options).finally(() => {
+    options.lifecycle.setCloseInFlight(null);
+  });
+  options.lifecycle.setCloseInFlight(closeOperation);
+  await closeOperation;
+};
+var performClose = async (options) => {
+  const pendingInit = options.getPendingInit();
+  if (pendingInit !== null) {
+    await pendingInit;
+  }
+  await options.lifecycle.waitForActiveOperationsToDrain();
+  let deferredError = options.getPendingInitError();
+  try {
+    await options.getBackendController()?.close();
+  } catch (error) {
+    const closeError = toErrorInstance(
+      error,
+      "Datastore close failed with a non-Error value."
+    );
+    if (deferredError === null) {
+      deferredError = closeError;
+    } else {
+      deferredError = createCloseAggregateError(deferredError, closeError);
+    }
+  }
+  options.setBackendController(null);
+  options.setPendingInitError(null);
+  options.lifecycle.markClosed();
+  options.clearInMemoryState();
+  if (deferredError !== null) {
+    throw deferredError;
+  }
+};
+
+// src/storage/btree/recordKeyIndexBTree.ts
+var import_frostpillar_btree = require("@frostpillar/frostpillar-btree");
+var normalizeComparatorResult = (compared) => {
+  if (!Number.isFinite(compared) || !Number.isInteger(compared)) {
+    throw new IndexCorruptionError(
+      "key comparator must return a finite integer result."
+    );
+  }
+  if (compared === 0) {
+    return 0;
+  }
+  return compared < 0 ? -1 : 1;
+};
+var clampComparatorResult = (compared) => {
+  if (compared === 0) return 0;
+  return compared < 0 ? -1 : 1;
+};
+var buildWrappedComparator = (compareKeys) => {
+  return (left, right) => {
+    const result = compareKeys(left, right);
+    if (result !== result) {
+      throw new IndexCorruptionError("key comparator must not return NaN.");
+    }
+    return clampComparatorResult(result);
+  };
+};
+var RecordKeyIndexBTree = class _RecordKeyIndexBTree {
+  constructor(config) {
+    const wrappedComparator = buildWrappedComparator(config.compareKeys);
+    const treeConfig = {
+      compareKeys: wrappedComparator,
+      duplicateKeys: config.duplicateKeys ?? "allow",
+      enableEntryIdLookup: true
+    };
+    this.tree = new import_frostpillar_btree.InMemoryBTree(treeConfig);
+  }
+  put(key, value) {
+    return this.tree.put(key, value);
+  }
+  putMany(entries) {
+    return this.tree.putMany(entries);
+  }
+  peekById(entryId) {
+    return this.tree.peekById(entryId);
+  }
+  updateById(entryId, value) {
+    return this.tree.updateById(entryId, value);
+  }
+  removeById(entryId) {
+    return this.tree.removeById(entryId);
+  }
+  rangeQuery(start, end) {
+    return this.tree.range(start, end);
+  }
+  deleteRange(start, end) {
+    return this.tree.deleteRange(start, end, {
+      lowerBound: "inclusive",
+      upperBound: "inclusive"
+    });
+  }
+  snapshot() {
+    return this.tree.snapshot();
+  }
+  peekLast() {
+    return this.tree.peekLast();
+  }
+  popFirst() {
+    return this.tree.popFirst();
+  }
+  size() {
+    return this.tree.size();
+  }
+  findFirst(key) {
+    return this.tree.findFirst(key);
+  }
+  findLast(key) {
+    return this.tree.findLast(key);
+  }
+  hasKey(key) {
+    return this.tree.hasKey(key);
+  }
+  keys() {
+    return this.tree.keys();
+  }
+  toJSON() {
+    return this.tree.toJSON();
+  }
+  static fromJSON(json, config) {
+    const wrappedComparator = buildWrappedComparator(config.compareKeys);
+    const adapter = Object.create(_RecordKeyIndexBTree.prototype);
+    const resolvedPolicy = config.duplicateKeys ?? "allow";
+    const patchedJSON = resolvedPolicy !== json.config.duplicateKeys ? { ...json, config: { ...json.config, duplicateKeys: resolvedPolicy } } : json;
+    adapter.tree = import_frostpillar_btree.InMemoryBTree.fromJSON(patchedJSON, wrappedComparator);
+    return adapter;
+  }
+  clear() {
+    this.tree.clear();
+  }
+};
+
+// src/storage/datastore/datastoreKeyDefinition.ts
+var ensureNonEmptyStringKey = (value, fieldName) => {
+  if (typeof value !== "string") {
+    throw new ValidationError(`${fieldName} must be a string.`);
+  }
+  if (value.length === 0) {
+    throw new ValidationError(`${fieldName} must be a non-empty string.`);
+  }
+  return value;
+};
+var DEFAULT_STRING_KEY_DEFINITION = {
+  normalize: (value, fieldName) => {
+    return ensureNonEmptyStringKey(value, fieldName);
+  },
+  compare: (left, right) => {
+    if (left < right) {
+      return -1;
+    }
+    if (left > right) {
+      return 1;
+    }
+    return 0;
+  },
+  serialize: (key) => {
+    return ensureNonEmptyStringKey(key, "key");
+  },
+  deserialize: (serialized) => {
+    return ensureNonEmptyStringKey(serialized, "serialized key");
+  }
+};
+var validateKeyDefinition = (definition) => {
+  if (typeof definition.normalize !== "function") {
+    throw new ConfigurationError("config.key.normalize must be a function.");
+  }
+  if (typeof definition.compare !== "function") {
+    throw new ConfigurationError("config.key.compare must be a function.");
+  }
+  if (typeof definition.serialize !== "function") {
+    throw new ConfigurationError("config.key.serialize must be a function.");
+  }
+  if (typeof definition.deserialize !== "function") {
+    throw new ConfigurationError("config.key.deserialize must be a function.");
+  }
+};
+var resolveKeyDefinition = (config) => {
+  if (config.key === void 0) {
+    return DEFAULT_STRING_KEY_DEFINITION;
+  }
+  validateKeyDefinition(config.key);
+  return config.key;
+};
+var readRawInsertKey = (rawRecord) => {
+  if (Object.prototype.hasOwnProperty.call(rawRecord, "key")) {
+    return {
+      rawKey: rawRecord.key,
+      keyFieldName: "key"
+    };
+  }
+  throw new ValidationError('Record must include "key".');
+};
+
+// src/storage/datastore/Datastore.ts
+var Datastore = class {
+  constructor(config) {
+    this.errorListeners = /* @__PURE__ */ new Set();
+    this.keyDefinition = resolveKeyDefinition(config);
+    const duplicateKeys = parseDuplicateKeyConfig(config.duplicateKeys);
+    this.duplicateKeyPolicy = duplicateKeys;
+    this.keyIndex = new RecordKeyIndexBTree({
+      compareKeys: (left, right) => this.keyDefinition.compare(left, right),
+      duplicateKeys
+    });
+    this.capacityState = resolveCapacityState(config);
+    this.skipPayloadValidation = config.skipPayloadValidation === true;
+    this.lifecycle = new DatastoreLifecycle();
+    this.writeMutex = new AsyncMutex();
+    this.currentSizeBytes = 0;
+    this.backendController = null;
+    this.pendingInit = null;
+    this.pendingInitError = null;
+    if (config.driver === void 0) {
+      if (config.autoCommit !== void 0) {
+        throw new ConfigurationError(
+          "autoCommit requires a durable driver."
+        );
+      }
+      return;
+    }
+    const backendInit = config.driver.init({
+      getSnapshot: () => ({
+        treeJSON: this.keyIndex.toJSON()
+      }),
+      autoCommit: config.autoCommit,
+      onAutoCommitError: (error) => {
+        emitAutoCommitErrorToListeners(this.errorListeners, error);
+      }
+    });
+    if (!isPromiseLike(backendInit)) {
+      this.applyBackendInitResult(backendInit);
+      return;
+    }
+    this.pendingInit = Promise.resolve(backendInit).then((result) => {
+      this.applyBackendInitResult(result);
+    }).catch((error) => {
+      this.pendingInitError = toErrorInstance(error, "Datastore backend initialization failed with a non-Error value.");
+    }).finally(() => {
+      this.pendingInit = null;
+    });
+  }
+  put(record) {
+    return this.runWithOpenExclusive(() => this.putSingle(record));
+  }
+  get(key) {
+    return this.runWithOpen(() => {
+      const normalizedKey = this.keyDefinition.normalize(key, "key");
+      return this.keyIndex.rangeQuery(normalizedKey, normalizedKey).map((e) => toPublicRecord(e.entryId, e.key, e.value));
+    });
+  }
+  getFirst(key) {
+    return this.runWithOpen(() => {
+      const normalizedKey = this.keyDefinition.normalize(key, "key");
+      const entry = this.keyIndex.findFirst(normalizedKey);
+      if (entry === null) {
+        return null;
+      }
+      return toPublicRecord(entry.entryId, entry.key, entry.value);
+    });
+  }
+  getLast(key) {
+    return this.runWithOpen(() => {
+      const normalizedKey = this.keyDefinition.normalize(key, "key");
+      const entry = this.keyIndex.findLast(normalizedKey);
+      if (entry === null) {
+        return null;
+      }
+      return toPublicRecord(entry.entryId, entry.key, entry.value);
+    });
+  }
+  delete(key) {
+    return this.runWithOpenExclusive(() => this.deleteSingle(key));
+  }
+  has(key) {
+    return this.runWithOpen(() => {
+      const normalizedKey = this.keyDefinition.normalize(key, "key");
+      return this.keyIndex.hasKey(normalizedKey);
+    });
+  }
+  getAll() {
+    return this.runWithOpen(() => {
+      return this.keyIndex.snapshot().map((e) => toPublicRecord(e.entryId, e.key, e.value));
+    });
+  }
+  getRange(start, end) {
+    return this.runWithOpen(() => {
+      const normalizedStart = this.keyDefinition.normalize(start, "start");
+      const normalizedEnd = this.keyDefinition.normalize(end, "end");
+      if (normalizeComparatorResult(this.keyDefinition.compare(normalizedStart, normalizedEnd)) > 0) {
+        throw new InvalidQueryRangeError("start must be <= end.");
+      }
+      return this.keyIndex.rangeQuery(normalizedStart, normalizedEnd).map((e) => toPublicRecord(e.entryId, e.key, e.value));
+    });
+  }
+  getMany(keys) {
+    return this.runWithOpen(() => {
+      const normalizedKeys = [];
+      for (const key of keys) {
+        normalizedKeys.push(this.keyDefinition.normalize(key, "key"));
+      }
+      normalizedKeys.sort(
+        (left, right) => clampComparatorResult(this.keyDefinition.compare(left, right))
+      );
+      const results = [];
+      let lastKey = void 0;
+      for (let i = 0; i < normalizedKeys.length; i += 1) {
+        if (i > 0 && clampComparatorResult(this.keyDefinition.compare(normalizedKeys[i], lastKey)) === 0) {
+          continue;
+        }
+        lastKey = normalizedKeys[i];
+        const entries = this.keyIndex.rangeQuery(normalizedKeys[i], normalizedKeys[i]);
+        for (const entry of entries) {
+          results.push(toPublicRecord(entry.entryId, entry.key, entry.value));
+        }
+      }
+      return results;
+    });
+  }
+  putMany(records) {
+    return this.runWithOpenExclusive(async () => {
+      if (this.capacityState === null && this.backendController === null) {
+        for (const record of records) {
+          const { rawKey, keyFieldName } = readRawInsertKey(record);
+          const normalizedKey = this.keyDefinition.normalize(rawKey, keyFieldName);
+          if (this.duplicateKeyPolicy === "reject" && this.keyIndex.findFirst(normalizedKey) !== null) {
+            throw new ValidationError("Duplicate key rejected: a record with this key already exists.");
+          }
+          const normalizedPayload = this.skipPayloadValidation ? record.payload : validateAndNormalizePayload(record.payload).payload;
+          this.keyIndex.put(normalizedKey, { payload: normalizedPayload, sizeBytes: 0 });
+        }
+        return;
+      }
+      if (this.capacityState === null) {
+        for (const record of records) {
+          await this.putSingle(record);
+        }
+        return;
+      }
+      if (this.capacityState.policy === "turnover") {
+        for (const record of records) {
+          await this.putSingle(record);
+        }
+        return;
+      }
+      await this.putManyStrict(records);
+    });
+  }
+  deleteMany(keys) {
+    return this.runWithOpenExclusive(async () => {
+      if (this.backendController === null) {
+        let totalRemoved2 = 0;
+        for (const key of keys) {
+          const normalizedKey = this.keyDefinition.normalize(key, "key");
+          const entries = this.keyIndex.rangeQuery(normalizedKey, normalizedKey);
+          if (entries.length === 0) {
+            continue;
+          }
+          let freedBytes = 0;
+          for (const entry of entries) {
+            freedBytes += entry.value.sizeBytes;
+          }
+          totalRemoved2 += this.keyIndex.deleteRange(normalizedKey, normalizedKey);
+          this.currentSizeBytes = Math.max(0, this.currentSizeBytes - freedBytes);
+        }
+        return totalRemoved2;
+      }
+      let totalRemoved = 0;
+      for (const key of keys) {
+        totalRemoved += await this.deleteSingle(key);
+      }
+      return totalRemoved;
+    });
+  }
+  clear() {
+    return this.runWithOpenExclusive(async () => {
+      this.keyIndex.clear();
+      this.currentSizeBytes = 0;
+      await this.backendController?.handleCleared();
+    });
+  }
+  count() {
+    return this.runWithOpen(() => {
+      return this.keyIndex.size();
+    });
+  }
+  keys() {
+    return this.runWithOpen(() => {
+      const distinctKeys = [];
+      let lastKey = void 0;
+      let isFirst = true;
+      for (const key of this.keyIndex.keys()) {
+        if (isFirst || clampComparatorResult(this.keyDefinition.compare(key, lastKey)) !== 0) {
+          distinctKeys.push(key);
+          lastKey = key;
+          isFirst = false;
+        }
+      }
+      return distinctKeys;
+    });
+  }
+  getById(id) {
+    return this.runWithOpen(() => {
+      return getPublicRecordById(this.keyIndex, id);
+    });
+  }
+  updateById(id, patch) {
+    return this.runWithOpenExclusive(async () => {
+      const result = updateRecordById({
+        keyIndex: this.keyIndex,
+        id,
+        patch,
+        capacityState: this.capacityState,
+        currentSizeBytes: this.currentSizeBytes,
+        skipPayloadValidation: this.skipPayloadValidation
+      });
+      if (!result.updated) {
+        return false;
+      }
+      this.currentSizeBytes = result.currentSizeBytes;
+      await this.backendController?.handleRecordAppended(
+        result.durabilitySignalBytes
+      );
+      return true;
+    });
+  }
+  deleteById(id) {
+    return this.runWithOpenExclusive(async () => {
+      const result = deleteRecordById({
+        keyIndex: this.keyIndex,
+        id,
+        currentSizeBytes: this.currentSizeBytes
+      });
+      if (!result.deleted) {
+        return false;
+      }
+      this.currentSizeBytes = result.currentSizeBytes;
+      await this.backendController?.handleRecordAppended(
+        result.durabilitySignalBytes
+      );
+      return true;
+    });
+  }
+  commit() {
+    return this.runWithOpenExclusive(async () => {
+      await this.backendController?.commitNow();
+    });
+  }
+  on(event, listener) {
+    if (event !== "error") {
+      throw new ValidationError('Only "error" event is supported.');
+    }
+    this.errorListeners.add(listener);
+    return () => {
+      this.off(event, listener);
+    };
+  }
+  off(event, listener) {
+    if (event !== "error") {
+      throw new ValidationError('Only "error" event is supported.');
+    }
+    this.errorListeners.delete(listener);
+  }
+  async close() {
+    await closeDatastore({
+      lifecycle: this.lifecycle,
+      getPendingInit: () => this.pendingInit,
+      getPendingInitError: () => this.pendingInitError,
+      setPendingInitError: (pendingInitError) => {
+        this.pendingInitError = pendingInitError;
+      },
+      getBackendController: () => this.backendController,
+      setBackendController: (backendController) => {
+        this.backendController = backendController;
+      },
+      clearInMemoryState: () => {
+        this.keyIndex.clear();
+        this.errorListeners.clear();
+      }
+    });
+  }
+  resolvePayload(record, normalizedKey) {
+    if (this.skipPayloadValidation) {
+      const payload = record.payload;
+      return { payload, encodedBytes: estimateRecordSizeBytes(normalizedKey, payload) };
+    }
+    const validationResult = validateAndNormalizePayload(record.payload);
+    const keyBytes = estimateKeySizeBytes(normalizedKey);
+    return { payload: validationResult.payload, encodedBytes: validationResult.sizeBytes + keyBytes };
+  }
+  async putSingle(record) {
+    const { rawKey, keyFieldName } = readRawInsertKey(record);
+    const normalizedKey = this.keyDefinition.normalize(rawKey, keyFieldName);
+    if (this.duplicateKeyPolicy === "reject" && this.keyIndex.findFirst(normalizedKey) !== null) {
+      throw new ValidationError(
+        "Duplicate key rejected: a record with this key already exists."
+      );
+    }
+    if (this.capacityState === null && this.backendController === null) {
+      const normalizedPayload2 = this.skipPayloadValidation ? record.payload : validateAndNormalizePayload(record.payload).payload;
+      this.keyIndex.put(normalizedKey, { payload: normalizedPayload2, sizeBytes: 0 });
+      return;
+    }
+    const { payload: normalizedPayload, encodedBytes } = this.resolvePayload(record, normalizedKey);
+    if (this.capacityState === null) {
+      this.keyIndex.put(normalizedKey, { payload: normalizedPayload, sizeBytes: encodedBytes });
+      await this.backendController.handleRecordAppended(encodedBytes);
+      return;
+    }
+    const persistedRecord = { payload: normalizedPayload, sizeBytes: encodedBytes };
+    if (encodedBytes > this.capacityState.maxSizeBytes) {
+      throw new QuotaExceededError("Record exceeds configured capacity.maxSize boundary.");
+    }
+    if (this.duplicateKeyPolicy === "replace") {
+      const existing = this.keyIndex.findFirst(normalizedKey);
+      if (existing !== null) {
+        this.currentSizeBytes = Math.max(0, this.currentSizeBytes - existing.value.sizeBytes);
+        this.keyIndex.removeById(existing.entryId);
+      }
+    }
+    this.currentSizeBytes = enforceCapacityPolicy(
+      this.capacityState,
+      this.currentSizeBytes,
+      encodedBytes,
+      () => this.keyIndex.size(),
+      () => {
+        const evicted = this.keyIndex.popFirst();
+        if (evicted === null) {
+          throw new IndexCorruptionError("Record buffer reported empty state during turnover eviction.");
+        }
+        return evicted.value.sizeBytes;
+      }
+    );
+    this.keyIndex.put(normalizedKey, persistedRecord);
+    this.currentSizeBytes = Math.max(0, this.currentSizeBytes + encodedBytes);
+    await this.backendController?.handleRecordAppended(encodedBytes);
+  }
+  async putManyStrict(records) {
+    const capacityState = this.capacityState;
+    const compare = this.keyDefinition.compare;
+    const tagged = [];
+    for (let i = 0; i < records.length; i += 1) {
+      const { rawKey, keyFieldName } = readRawInsertKey(records[i]);
+      tagged.push({ idx: i, normalizedKey: this.keyDefinition.normalize(rawKey, keyFieldName), record: records[i] });
+    }
+    tagged.sort((a, b) => {
+      const cmp = clampComparatorResult(compare(a.normalizedKey, b.normalizedKey));
+      return cmp !== 0 ? cmp : a.idx - b.idx;
+    });
+    const { prepared, totalBatchDelta } = this.buildStrictBatchEntries(tagged, compare, capacityState.maxSizeBytes);
+    if (this.currentSizeBytes + totalBatchDelta > capacityState.maxSizeBytes) {
+      throw new QuotaExceededError("Insert exceeds configured capacity.maxSize under strict policy.");
+    }
+    let effectiveTotalDelta = 0;
+    let totalEncodedBytes = 0;
+    for (const { normalizedKey, persistedRecord, encodedBytes, replacedBytes } of prepared) {
+      const actualReplaced = replacedBytes > 0 && this.keyIndex.findFirst(normalizedKey) === null ? 0 : replacedBytes;
+      effectiveTotalDelta += encodedBytes - actualReplaced;
+      totalEncodedBytes += encodedBytes;
+      this.keyIndex.put(normalizedKey, persistedRecord);
+    }
+    this.currentSizeBytes = Math.max(0, this.currentSizeBytes + effectiveTotalDelta);
+    await this.backendController?.handleRecordAppended(totalEncodedBytes);
+  }
+  buildStrictBatchEntries(tagged, compare, maxSizeBytes) {
+    const prepared = [];
+    let totalBatchDelta = 0;
+    for (let i = 0; i < tagged.length; i += 1) {
+      const { normalizedKey, record } = tagged[i];
+      const isIntraBatchDuplicate = i > 0 && clampComparatorResult(compare(tagged[i - 1].normalizedKey, normalizedKey)) === 0;
+      if (this.duplicateKeyPolicy === "reject") {
+        if (isIntraBatchDuplicate || this.keyIndex.findFirst(normalizedKey) !== null) {
+          throw new ValidationError("Duplicate key rejected: a record with this key already exists.");
+        }
+      }
+      const { payload: normalizedPayload, encodedBytes } = this.resolvePayload(record, normalizedKey);
+      if (encodedBytes > maxSizeBytes) {
+        throw new QuotaExceededError("Record exceeds configured capacity.maxSize boundary.");
+      }
+      let replacedBytes = 0;
+      if (this.duplicateKeyPolicy === "replace" && isIntraBatchDuplicate) {
+        const prev = prepared[prepared.length - 1];
+        totalBatchDelta -= prev.encodedBytes - prev.replacedBytes;
+        replacedBytes = prev.replacedBytes;
+        prepared.pop();
+      } else if (this.duplicateKeyPolicy === "replace") {
+        const existing = this.keyIndex.findFirst(normalizedKey);
+        replacedBytes = existing !== null ? existing.value.sizeBytes : 0;
+      }
+      const persistedRecord = { payload: normalizedPayload, sizeBytes: encodedBytes };
+      totalBatchDelta += encodedBytes - replacedBytes;
+      prepared.push({ normalizedKey, persistedRecord, encodedBytes, replacedBytes });
+    }
+    return { prepared, totalBatchDelta };
+  }
+  async deleteSingle(key) {
+    const normalizedKey = this.keyDefinition.normalize(key, "key");
+    const entries = this.keyIndex.rangeQuery(normalizedKey, normalizedKey);
+    if (entries.length === 0) {
+      return 0;
+    }
+    let freedBytes = 0;
+    for (const entry of entries) {
+      freedBytes += entry.value.sizeBytes;
+    }
+    const removedCount = this.keyIndex.deleteRange(normalizedKey, normalizedKey);
+    this.currentSizeBytes = Math.max(0, this.currentSizeBytes - freedBytes);
+    await this.backendController?.handleRecordAppended(freedBytes);
+    return removedCount;
+  }
+  // P7: Synchronous fast-path — avoids async/Promise overhead for read operations
+  // when no pending init exists.
+  runWithOpen(operation) {
+    if (this.pendingInit !== null) {
+      return this.pendingInit.then(() => {
+        if (this.pendingInitError !== null) {
+          throw this.pendingInitError;
+        }
+        return this.executeWithLifecycle(operation);
+      });
+    }
+    if (this.pendingInitError !== null) {
+      return Promise.reject(this.pendingInitError);
+    }
+    try {
+      return Promise.resolve(this.executeWithLifecycle(operation));
+    } catch (error) {
+      return Promise.reject(error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+  executeWithLifecycle(operation) {
+    this.lifecycle.beginOperation();
+    try {
+      const result = operation();
+      if (isPromiseLike(result)) {
+        return Promise.resolve(result).then(
+          (value) => {
+            this.lifecycle.endOperation();
+            return value;
+          },
+          (error) => {
+            this.lifecycle.endOperation();
+            throw error;
+          }
+        );
+      }
+      this.lifecycle.endOperation();
+      return result;
+    } catch (error) {
+      this.lifecycle.endOperation();
+      throw error;
+    }
+  }
+  async runWithOpenExclusive(operation) {
+    const release = await this.writeMutex.acquire();
+    try {
+      return await this.runWithOpen(operation);
+    } finally {
+      release();
+    }
+  }
+  applyBackendInitResult(result) {
+    if (result.initialTreeJSON !== null) {
+      this.keyIndex = RecordKeyIndexBTree.fromJSON(
+        result.initialTreeJSON,
+        {
+          compareKeys: (left, right) => {
+            return this.keyDefinition.compare(left, right);
+          },
+          duplicateKeys: this.duplicateKeyPolicy
+        }
+      );
+      this.backfillMissingSizeBytes();
+    }
+    this.currentSizeBytes = result.initialCurrentSizeBytes;
+    this.backendController = result.controller;
+  }
+  backfillMissingSizeBytes() {
+    for (const entry of this.keyIndex.snapshot()) {
+      if (typeof entry.value.sizeBytes !== "number") {
+        const patched = {
+          payload: entry.value.payload,
+          sizeBytes: estimateRecordSizeBytes(entry.key, entry.value.payload)
+        };
+        this.keyIndex.updateById(entry.entryId, patched);
+      }
+    }
+  }
+};
+var isPromiseLike = (value) => {
+  if (typeof value !== "object" && typeof value !== "function" || value === null) {
+    return false;
+  }
+  return typeof value.then === "function";
+};
+
+// src/storage/backend/asyncDurableAutoCommitController.ts
+var AsyncDurableAutoCommitController = class {
+  constructor(autoCommit, onAutoCommitError) {
+    this.autoCommit = autoCommit;
+    this.onAutoCommitError = onAutoCommitError;
+    this.pendingAutoCommitBytes = 0;
+    this.dirtyFromClear = false;
+    this.autoCommitTimer = null;
+    this.commitInFlight = null;
+    this.pendingForegroundCommitRequest = false;
+    this.pendingBackgroundCommitRequest = false;
+    this.closed = false;
+    this.startAutoCommitSchedule();
+  }
+  handleRecordAppended(encodedBytes) {
+    if (this.autoCommit.frequency === "immediate") {
+      return this.commitNow();
+    }
+    this.pendingAutoCommitBytes += encodedBytes;
+    if (this.autoCommit.maxPendingBytes !== null && this.pendingAutoCommitBytes >= this.autoCommit.maxPendingBytes) {
+      return this.queueCommitRequest("foreground");
+    }
+    return Promise.resolve();
+  }
+  handleCleared() {
+    this.dirtyFromClear = true;
+    if (this.autoCommit.frequency === "immediate") {
+      return this.commitNow();
+    }
+    return this.queueCommitRequest("background");
+  }
+  commitNow() {
+    return this.queueCommitRequest("foreground");
+  }
+  async close() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    this.stopAutoCommitSchedule();
+    await this.waitForCommitSettlement();
+    let flushError = null;
+    if (this.pendingAutoCommitBytes > 0 || this.dirtyFromClear) {
+      try {
+        await this.executeSingleCommit();
+        this.pendingAutoCommitBytes = 0;
+        this.dirtyFromClear = false;
+      } catch (error) {
+        flushError = toErrorInstance(
+          error,
+          "Final close-time flush commit failed with a non-Error value."
+        );
+      }
+    }
+    let drainError = null;
+    try {
+      await this.onCloseAfterDrain();
+    } catch (error) {
+      drainError = toErrorInstance(
+        error,
+        "onCloseAfterDrain failed with a non-Error value."
+      );
+    }
+    if (flushError !== null && drainError !== null) {
+      throw createCloseAggregateError2(flushError, drainError);
+    }
+    if (flushError !== null) {
+      throw flushError;
+    }
+    if (drainError !== null) {
+      throw drainError;
+    }
+  }
+  getPendingAutoCommitBytes() {
+    return this.pendingAutoCommitBytes;
+  }
+  onCloseAfterDrain() {
+    return Promise.resolve();
+  }
+  waitForCommitSettlement() {
+    if (this.commitInFlight === null) {
+      return Promise.resolve();
+    }
+    return this.commitInFlight.then(() => void 0).catch(() => void 0);
+  }
+  queueCommitRequest(requestType) {
+    if (requestType === "foreground") {
+      this.pendingForegroundCommitRequest = true;
+    } else {
+      this.pendingBackgroundCommitRequest = true;
+    }
+    if (this.commitInFlight === null) {
+      this.commitInFlight = this.runCommitLoop().finally(() => {
+        this.commitInFlight = null;
+      });
+    }
+    if (requestType === "background") {
+      return Promise.resolve();
+    }
+    return this.commitInFlight;
+  }
+  async runCommitLoop() {
+    let shouldContinue = true;
+    while (shouldContinue) {
+      const runForeground = this.pendingForegroundCommitRequest;
+      const runBackground = this.pendingBackgroundCommitRequest;
+      const runClear = this.dirtyFromClear;
+      this.pendingForegroundCommitRequest = false;
+      this.pendingBackgroundCommitRequest = false;
+      this.dirtyFromClear = false;
+      const shouldRunCommit = runForeground || runBackground && (this.pendingAutoCommitBytes > 0 || runClear);
+      if (!shouldRunCommit) {
+        shouldContinue = false;
+        continue;
+      }
+      try {
+        const committedPendingBytes = this.pendingAutoCommitBytes;
+        await this.executeSingleCommit();
+        this.pendingAutoCommitBytes = Math.max(
+          0,
+          this.pendingAutoCommitBytes - committedPendingBytes
+        );
+      } catch (error) {
+        if (runClear) {
+          this.dirtyFromClear = true;
+        }
+        if (runForeground) {
+          throw toErrorInstance(
+            error,
+            "Foreground auto-commit failed with a non-Error value."
+          );
+        }
+        this.onAutoCommitError(error);
+      }
+      if (!this.pendingForegroundCommitRequest && !this.pendingBackgroundCommitRequest) {
+        shouldContinue = false;
+      }
+    }
+  }
+  startAutoCommitSchedule() {
+    if (this.autoCommit.frequency !== "scheduled" || this.autoCommit.intervalMs === null) {
+      return;
+    }
+    this.autoCommitTimer = setInterval(() => {
+      this.handleAutoCommitTick();
+    }, this.autoCommit.intervalMs);
+    if (typeof this.autoCommitTimer === "object" && this.autoCommitTimer !== null && "unref" in this.autoCommitTimer) {
+      this.autoCommitTimer.unref();
+    }
+  }
+  stopAutoCommitSchedule() {
+    if (this.autoCommitTimer === null) {
+      return;
+    }
+    clearInterval(this.autoCommitTimer);
+    this.autoCommitTimer = null;
+  }
+  handleAutoCommitTick() {
+    if (this.closed) {
+      return;
+    }
+    if (this.pendingAutoCommitBytes <= 0 && !this.dirtyFromClear) {
+      return;
+    }
+    void this.queueCommitRequest("background");
+  }
+};
+var readAggregateErrorConstructor2 = () => {
+  const candidate = globalThis.AggregateError;
+  if (typeof candidate !== "function") {
+    return null;
+  }
+  return candidate;
+};
+var createCloseAggregateError2 = (flushError, drainError) => {
+  const aggregateErrorConstructor = readAggregateErrorConstructor2();
+  if (aggregateErrorConstructor !== null) {
+    return new aggregateErrorConstructor(
+      [flushError, drainError],
+      "Close failed: both final flush and drain produced errors."
+    );
+  }
+  const fallbackError = new Error(
+    "Close failed: both final flush and drain produced errors."
+  );
+  fallbackError.errors = [flushError, drainError];
+  return fallbackError;
+};
+
+// src/storage/drivers/localStorage/localStorageConfig.ts
+var DEFAULT_LOCAL_STORAGE_MAX_CHUNK_CHARS = 32768;
+var DEFAULT_LOCAL_STORAGE_MAX_CHUNKS = 64;
+var parseLocalStorageConfig = (config) => {
+  const keyPrefix = config?.keyPrefix ?? "frostpillar";
+  const databaseKey = config?.databaseKey ?? "default";
+  const maxChunkChars = config?.maxChunkChars ?? DEFAULT_LOCAL_STORAGE_MAX_CHUNK_CHARS;
+  const maxChunks = config?.maxChunks ?? DEFAULT_LOCAL_STORAGE_MAX_CHUNKS;
+  if (!Number.isSafeInteger(maxChunkChars) || maxChunkChars <= 0) {
+    throw new ConfigurationError(
+      "localStorage.maxChunkChars must be a positive safe integer."
+    );
+  }
+  if (!Number.isSafeInteger(maxChunks) || maxChunks <= 0) {
+    throw new ConfigurationError(
+      "localStorage.maxChunks must be a positive safe integer."
+    );
+  }
+  return { keyPrefix, databaseKey, maxChunkChars, maxChunks };
+};
+
+// src/validation/metadata.ts
+var parseNonNegativeSafeInteger = (value, fieldName, backendName) => {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    throw new StorageEngineError(
+      `${backendName} ${fieldName} must be a non-negative safe integer.`
+    );
+  }
+  return value;
+};
+
+// src/storage/drivers/localStorage/localStorageLayout.ts
+var manifestKey = (keyPrefix, databaseKey) => `${keyPrefix}:ls:${databaseKey}:manifest`;
+var chunkKey = (keyPrefix, databaseKey, generation, index) => `${keyPrefix}:ls:${databaseKey}:g:${generation}:chunk:${index}`;
+var cleanupGenerationChunks = (state, generation, knownChunkCount) => {
+  if (knownChunkCount !== null) {
+    if (knownChunkCount <= 0) {
+      return;
+    }
+    for (let i = 0; i < knownChunkCount; i += 1) {
+      state.adapter.removeItem(
+        chunkKey(state.keyPrefix, state.databaseKey, generation, i)
+      );
+    }
+    return;
+  }
+  if (state.maxChunks <= 0) {
+    return;
+  }
+  for (let i = 0; i < state.maxChunks; i += 1) {
+    const key = chunkKey(state.keyPrefix, state.databaseKey, generation, i);
+    if (state.adapter.getItem(key) !== null) {
+      state.adapter.removeItem(key);
+    }
+  }
+};
+var isQuotaBrowserError = (error) => {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  return error.name === "QuotaExceededError" || error.name === "NS_ERROR_DOM_QUOTA_REACHED";
+};
+
+// src/storage/drivers/localStorage/localStorageBackend.ts
+var LS_MAGIC = "FPLS_META";
+var LS_VERSION = 2;
+var detectGlobalLocalStorage = () => {
+  try {
+    const g = globalThis;
+    const ls = g.localStorage;
+    if (ls === null || ls === void 0) {
+      return null;
+    }
+    return ls;
+  } catch {
+    return null;
+  }
+};
+var createLocalStorageBackendState = (adapter, keyPrefix, databaseKey, maxChunkChars, maxChunks) => ({
+  adapter,
+  keyPrefix,
+  databaseKey,
+  maxChunkChars,
+  maxChunks,
+  activeGeneration: 0,
+  commitId: 0,
+  activeChunkCount: 0
+});
+var parseLocalStorageManifest = (manifestRaw, maxChunks) => {
+  let manifest;
+  try {
+    manifest = JSON.parse(manifestRaw);
+  } catch {
+    throw new StorageEngineError("localStorage manifest JSON is malformed.");
+  }
+  if (manifest.magic !== LS_MAGIC || manifest.version !== LS_VERSION) {
+    throw new StorageEngineError(
+      "localStorage manifest magic/version mismatch."
+    );
+  }
+  const chunkCount = parseNonNegativeSafeInteger(
+    manifest.chunkCount,
+    "manifest.chunkCount",
+    "localStorage"
+  );
+  if (chunkCount > maxChunks) {
+    throw new StorageEngineError(
+      `localStorage snapshot requires ${chunkCount} chunks but maxChunks is ${maxChunks}.`
+    );
+  }
+  return manifest;
+};
+var loadLocalStorageChunks = (state, activeGeneration, chunkCount) => {
+  const chunks = [];
+  for (let i = 0; i < chunkCount; i += 1) {
+    const cKey = chunkKey(
+      state.keyPrefix,
+      state.databaseKey,
+      activeGeneration,
+      i
+    );
+    const chunkValue = state.adapter.getItem(cKey);
+    if (typeof chunkValue !== "string") {
+      throw new StorageEngineError(
+        `localStorage chunk "${cKey}" is missing or not a string.`
+      );
+    }
+    chunks.push(chunkValue);
+  }
+  const treeJson = chunks.join("");
+  let parsedTreeJSON;
+  try {
+    parsedTreeJSON = JSON.parse(treeJson);
+  } catch {
+    throw new StorageEngineError("localStorage chunk data JSON is malformed.");
+  }
+  if (typeof parsedTreeJSON !== "object" || parsedTreeJSON === null || Array.isArray(parsedTreeJSON)) {
+    throw new PageCorruptionError("treeJSON must be a non-null plain object.");
+  }
+  return {
+    treeJSON: parsedTreeJSON,
+    rawJsonLength: computeUtf8ByteLength(treeJson)
+  };
+};
+var loadLocalStorageSnapshot = (state) => {
+  const mKey = manifestKey(state.keyPrefix, state.databaseKey);
+  const manifestRaw = state.adapter.getItem(mKey);
+  if (manifestRaw === null) {
+    return { treeJSON: null, currentSizeBytes: 0 };
+  }
+  const manifest = parseLocalStorageManifest(manifestRaw, state.maxChunks);
+  const activeGeneration = parseNonNegativeSafeInteger(
+    manifest.activeGeneration,
+    "manifest.activeGeneration",
+    "localStorage"
+  );
+  const commitId = parseNonNegativeSafeInteger(
+    manifest.commitId,
+    "manifest.commitId",
+    "localStorage"
+  );
+  const chunkCount = parseNonNegativeSafeInteger(
+    manifest.chunkCount,
+    "manifest.chunkCount",
+    "localStorage"
+  );
+  const { treeJSON, rawJsonLength } = loadLocalStorageChunks(state, activeGeneration, chunkCount);
+  const currentSizeBytes = rawJsonLength;
+  state.activeGeneration = activeGeneration;
+  state.commitId = commitId;
+  state.activeChunkCount = chunkCount;
+  return { treeJSON, currentSizeBytes };
+};
+var splitTreeJSONIntoChunks = (treeJSON, maxChunkChars, maxChunks, driverName) => {
+  const dataJson = JSON.stringify(treeJSON);
+  const chunks = [];
+  for (let i = 0; i < dataJson.length; i += maxChunkChars) {
+    chunks.push(dataJson.slice(i, i + maxChunkChars));
+  }
+  if (chunks.length > maxChunks) {
+    throw new QuotaExceededError(
+      `${driverName} snapshot requires ${chunks.length} chunks but maxChunks is ${maxChunks}.`
+    );
+  }
+  return chunks;
+};
+var ensureCommitCountersSafe = (state) => {
+  if (state.commitId >= Number.MAX_SAFE_INTEGER) {
+    throw new StorageEngineError(
+      "localStorage commitId has reached Number.MAX_SAFE_INTEGER."
+    );
+  }
+  if (state.activeGeneration >= Number.MAX_SAFE_INTEGER) {
+    throw new StorageEngineError(
+      "localStorage activeGeneration has reached Number.MAX_SAFE_INTEGER."
+    );
+  }
+};
+var prepareLocalStorageCommit = (state, treeJSON) => {
+  const nextCommitId = state.commitId + 1;
+  const nextGeneration = state.activeGeneration + 1;
+  const chunks = splitTreeJSONIntoChunks(
+    treeJSON,
+    state.maxChunkChars,
+    state.maxChunks,
+    "localStorage"
+  );
+  const newManifest = {
+    magic: LS_MAGIC,
+    version: LS_VERSION,
+    activeGeneration: nextGeneration,
+    commitId: nextCommitId,
+    chunkCount: chunks.length
+  };
+  return {
+    nextCommitId,
+    nextGeneration,
+    chunks,
+    manifestJson: JSON.stringify(newManifest)
+  };
+};
+var writeLocalStorageCommit = (state, preparedCommit) => {
+  try {
+    cleanupGenerationChunks(state, preparedCommit.nextGeneration, null);
+    for (let i = 0; i < preparedCommit.chunks.length; i += 1) {
+      state.adapter.setItem(
+        chunkKey(
+          state.keyPrefix,
+          state.databaseKey,
+          preparedCommit.nextGeneration,
+          i
+        ),
+        preparedCommit.chunks[i]
+      );
+    }
+    state.adapter.setItem(
+      manifestKey(state.keyPrefix, state.databaseKey),
+      preparedCommit.manifestJson
+    );
+  } catch (error) {
+    if (isQuotaBrowserError(error) || error instanceof QuotaExceededError) {
+      throw new QuotaExceededError(
+        "localStorage quota exceeded during commit."
+      );
+    }
+    throw new StorageEngineError("localStorage write failed during commit.");
+  }
+};
+var commitLocalStorageSnapshot = (state, treeJSON) => {
+  ensureCommitCountersSafe(state);
+  const preparedCommit = prepareLocalStorageCommit(state, treeJSON);
+  writeLocalStorageCommit(state, preparedCommit);
+  const previousGeneration = state.activeGeneration;
+  const previousChunkCount = state.activeChunkCount;
+  state.activeGeneration = preparedCommit.nextGeneration;
+  state.commitId = preparedCommit.nextCommitId;
+  state.activeChunkCount = preparedCommit.chunks.length;
+  cleanupGenerationChunks(
+    state,
+    previousGeneration,
+    previousChunkCount
+  );
+};
+
+// src/storage/drivers/localStorage/localStorageBackendController.ts
+var LocalStorageBackendController = class _LocalStorageBackendController extends AsyncDurableAutoCommitController {
+  constructor(backend, autoCommit, getSnapshot, onAutoCommitError) {
+    super(autoCommit, onAutoCommitError);
+    this.backend = backend;
+    this.getSnapshot = getSnapshot;
+  }
+  static create(options) {
+    const adapter = detectGlobalLocalStorage();
+    if (adapter === null) {
+      throw new UnsupportedBackendError(
+        "localStorage is not available in the current runtime environment."
+      );
+    }
+    const lsConfig = parseLocalStorageConfig(options.config);
+    const autoCommit = parseAutoCommitConfig(options.autoCommit);
+    const backend = createLocalStorageBackendState(
+      adapter,
+      lsConfig.keyPrefix,
+      lsConfig.databaseKey,
+      lsConfig.maxChunkChars,
+      lsConfig.maxChunks
+    );
+    const loaded = loadLocalStorageSnapshot(backend);
+    const controller = new _LocalStorageBackendController(
+      backend,
+      autoCommit,
+      options.getSnapshot,
+      options.onAutoCommitError
+    );
+    return {
+      controller,
+      initialTreeJSON: loaded.treeJSON,
+      initialCurrentSizeBytes: loaded.currentSizeBytes
+    };
+  }
+  executeSingleCommit() {
+    const snapshot = this.getSnapshot();
+    commitLocalStorageSnapshot(
+      this.backend,
+      snapshot.treeJSON
+    );
+    return Promise.resolve();
+  }
+};
+
+// src/drivers/localStorage.ts
+var localStorageDriver = (options = {}) => {
+  return {
+    init: (callbacks) => {
+      const result = LocalStorageBackendController.create({
+        config: options,
+        autoCommit: callbacks.autoCommit,
+        getSnapshot: callbacks.getSnapshot,
+        onAutoCommitError: callbacks.onAutoCommitError
+      });
+      return {
+        controller: result.controller,
+        initialTreeJSON: result.initialTreeJSON,
+        initialCurrentSizeBytes: result.initialCurrentSizeBytes
+      };
+    },
+    resolveBackendLimitBytes: () => {
+      const { maxChunkChars, maxChunks } = parseLocalStorageConfig(options);
+      return maxChunkChars * maxChunks;
+    }
+  };
+};
+
+// src/storage/drivers/IndexedDB/indexedDBConfig.ts
+var ensureNonEmptyString = (value, optionName) => {
+  if (value.trim().length === 0) {
+    throw new ConfigurationError(`${optionName} must be a non-empty string.`);
+  }
+};
+var parseIndexedDBConfig = (config) => {
+  const databaseName = config?.databaseName ?? "frostpillar";
+  const objectStoreName = config?.objectStoreName ?? "frostpillar";
+  const version = config?.version ?? 1;
+  ensureNonEmptyString(databaseName, "indexedDB.databaseName");
+  ensureNonEmptyString(objectStoreName, "indexedDB.objectStoreName");
+  if (objectStoreName === "_meta") {
+    throw new ConfigurationError(
+      'indexedDB.objectStoreName must not be "_meta" because it is reserved for internal metadata.'
+    );
+  }
+  if (!Number.isSafeInteger(version) || version <= 0) {
+    throw new ConfigurationError(
+      "indexedDB.version must be a positive safe integer."
+    );
+  }
+  return {
+    databaseName,
+    objectStoreName,
+    version
+  };
+};
+
+// src/storage/drivers/IndexedDB/indexedDBBackend.ts
+var IDB_MAGIC = "FPIDB_META";
+var IDB_VERSION_VALUE = 2;
+var IDB_META_STORE = "_meta";
+var IDB_META_KEY = "config";
+var detectGlobalIndexedDB = () => {
+  try {
+    const g = globalThis;
+    const idb = g.indexedDB;
+    if (idb === null || idb === void 0) {
+      return null;
+    }
+    return idb;
+  } catch {
+    return null;
+  }
+};
+var idbRequest = (req) => new Promise((resolve, reject) => {
+  req.onsuccess = (event) => {
+    resolve(event.target.result);
+  };
+  req.onerror = (event) => {
+    reject(
+      new StorageEngineError(
+        `IndexedDB request failed: ${String(event.target.error?.message ?? "unknown")}`
+      )
+    );
+  };
+});
+var idbTransaction = (tx) => new Promise((resolve, reject) => {
+  tx.oncomplete = () => {
+    resolve();
+  };
+  tx.onerror = () => {
+    reject(new StorageEngineError("IndexedDB transaction failed."));
+  };
+});
+var openIndexedDB = (factory, databaseName, objectStoreName, version) => new Promise((resolve, reject) => {
+  const request = factory.open(databaseName, version);
+  request.onupgradeneeded = (event) => {
+    const db = event.target.result;
+    if (db === null) {
+      return;
+    }
+    if (!db.objectStoreNames.contains(objectStoreName)) {
+      db.createObjectStore(objectStoreName);
+    }
+    if (!db.objectStoreNames.contains(IDB_META_STORE)) {
+      db.createObjectStore(IDB_META_STORE);
+    }
+  };
+  request.onsuccess = (event) => {
+    const db = event.target.result;
+    if (db === null) {
+      reject(new StorageEngineError("IndexedDB open returned null database."));
+      return;
+    }
+    resolve(db);
+  };
+  request.onerror = (event) => {
+    reject(
+      new StorageEngineError(
+        `IndexedDB open failed: ${String(event.target.error?.message ?? "unknown")}`
+      )
+    );
+  };
+});
+var loadIndexedDBSnapshot = async (db, _objectStoreName) => {
+  const tx = db.transaction(
+    [IDB_META_STORE],
+    "readonly"
+  );
+  const txDone = idbTransaction(tx);
+  const metaStore = tx.objectStore(IDB_META_STORE);
+  const metaRaw = await idbRequest(metaStore.get(IDB_META_KEY));
+  await txDone;
+  if (metaRaw === null || metaRaw === void 0) {
+    return { treeJSON: null, currentSizeBytes: 0, commitId: 0 };
+  }
+  const meta = metaRaw;
+  if (meta.magic !== IDB_MAGIC || meta.version !== IDB_VERSION_VALUE) {
+    throw new StorageEngineError("IndexedDB metadata magic/version mismatch.");
+  }
+  const commitId = parseNonNegativeSafeInteger(
+    meta.commitId,
+    "meta.commitId",
+    "IndexedDB"
+  );
+  const treeJSON = meta.treeJSON;
+  if (typeof treeJSON !== "object" || treeJSON === null || Array.isArray(treeJSON)) {
+    throw new PageCorruptionError("treeJSON must be a non-null plain object.");
+  }
+  const currentSizeBytes = computeUtf8ByteLength(JSON.stringify(treeJSON));
+  return { treeJSON, currentSizeBytes, commitId };
+};
+var commitIndexedDBSnapshot = async (db, _objectStoreName, treeJSON, commitId) => {
+  const tx = db.transaction(
+    [IDB_META_STORE],
+    "readwrite"
+  );
+  const txDone = idbTransaction(tx);
+  const metaStore = tx.objectStore(IDB_META_STORE);
+  const meta = {
+    magic: IDB_MAGIC,
+    version: IDB_VERSION_VALUE,
+    commitId,
+    treeJSON
+  };
+  metaStore.put(meta, IDB_META_KEY);
+  await txDone;
+};
+
+// src/storage/drivers/IndexedDB/indexedDBBackendController.ts
+var IndexedDBBackendController = class _IndexedDBBackendController extends AsyncDurableAutoCommitController {
+  constructor(db, objectStoreName, commitId, autoCommit, getSnapshot, onAutoCommitError) {
+    super(autoCommit, onAutoCommitError);
+    this.db = db;
+    this.objectStoreName = objectStoreName;
+    this.commitId = commitId;
+    this.getSnapshot = getSnapshot;
+  }
+  static async create(options) {
+    const factory = detectGlobalIndexedDB();
+    if (factory === null) {
+      throw new UnsupportedBackendError(
+        "indexedDB is not available in the current runtime environment."
+      );
+    }
+    const idbConfig = parseIndexedDBConfig(options.config);
+    const { databaseName, objectStoreName, version } = idbConfig;
+    const autoCommit = parseAutoCommitConfig(options.autoCommit);
+    const db = await openIndexedDB(factory, databaseName, objectStoreName, version);
+    let loaded;
+    try {
+      loaded = await loadIndexedDBSnapshot(db, objectStoreName);
+    } catch (error) {
+      try {
+        db.close();
+      } catch {
+      }
+      throw toErrorInstance(
+        error,
+        "IndexedDB bootstrap failed with a non-Error value."
+      );
+    }
+    const controller = new _IndexedDBBackendController(
+      db,
+      objectStoreName,
+      loaded.commitId,
+      autoCommit,
+      options.getSnapshot,
+      options.onAutoCommitError
+    );
+    return {
+      controller,
+      initialTreeJSON: loaded.treeJSON,
+      initialCurrentSizeBytes: loaded.currentSizeBytes
+    };
+  }
+  async executeSingleCommit() {
+    const snapshot = this.getSnapshot();
+    if (this.commitId >= Number.MAX_SAFE_INTEGER) {
+      throw new StorageEngineError("IndexedDB commitId has reached Number.MAX_SAFE_INTEGER.");
+    }
+    const nextCommitId = this.commitId + 1;
+    await commitIndexedDBSnapshot(
+      this.db,
+      this.objectStoreName,
+      snapshot.treeJSON,
+      nextCommitId
+    );
+    this.commitId = nextCommitId;
+  }
+  onCloseAfterDrain() {
+    this.db.close();
+    return Promise.resolve();
+  }
+};
+
+// src/drivers/indexedDB.ts
+var indexedDBDriver = (options = {}) => {
+  return {
+    init: async (callbacks) => {
+      const result = await IndexedDBBackendController.create({
+        config: options,
+        autoCommit: callbacks.autoCommit,
+        getSnapshot: callbacks.getSnapshot,
+        onAutoCommitError: callbacks.onAutoCommitError
+      });
+      return {
+        controller: result.controller,
+        initialTreeJSON: result.initialTreeJSON,
+        initialCurrentSizeBytes: result.initialCurrentSizeBytes
+      };
+    }
+  };
+};
+
+// src/storage/drivers/opfs/opfsBackend.ts
+var OPFS_MAGIC = "FPOPFS_META";
+var OPFS_VERSION_VALUE = 2;
+var META_FILE = "meta.json";
+var DATA_FILE_A = "data-a.json";
+var DATA_FILE_B = "data-b.json";
+var isNotFoundError = (error) => {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  return error.name === "NotFoundError";
+};
+var isManifestObject = (value) => {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+};
+var detectGlobalOpfs = () => {
+  try {
+    const nav = globalThis;
+    if (typeof nav.navigator?.storage?.getDirectory === "function") {
+      return nav.navigator.storage;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+};
+var openOpfsDirectory = async (storageRoot, directoryName) => {
+  const root = await storageRoot.getDirectory();
+  return root.getDirectoryHandle(directoryName, { create: true });
+};
+var parseOpfsManifest = (metaText) => {
+  let manifestRaw;
+  try {
+    manifestRaw = JSON.parse(metaText);
+  } catch {
+    throw new StorageEngineError("OPFS meta.json JSON is malformed.");
+  }
+  if (!isManifestObject(manifestRaw)) {
+    throw new StorageEngineError("OPFS meta.json must be a JSON object.");
+  }
+  const manifest = manifestRaw;
+  if (manifest.magic !== OPFS_MAGIC || manifest.version !== OPFS_VERSION_VALUE) {
+    throw new StorageEngineError("OPFS meta.json magic/version mismatch.");
+  }
+  if (manifest.activeData !== "a" && manifest.activeData !== "b") {
+    throw new StorageEngineError('OPFS meta.json activeData must be "a" or "b".');
+  }
+  const commitId = parseNonNegativeSafeInteger(
+    manifest.commitId,
+    "meta.json commitId",
+    "OPFS"
+  );
+  return { manifest, commitId, activeData: manifest.activeData };
+};
+var loadOpfsDataFile = async (dir, dataFileName) => {
+  let dataText;
+  try {
+    const dataHandle = await dir.getFileHandle(dataFileName, { create: false });
+    const dataFile = await dataHandle.getFile();
+    dataText = await dataFile.text();
+  } catch {
+    throw new StorageEngineError(`OPFS active data file "${dataFileName}" not found.`);
+  }
+  let parsedTreeJSON;
+  try {
+    parsedTreeJSON = JSON.parse(dataText);
+  } catch {
+    throw new StorageEngineError("OPFS data file JSON is malformed.");
+  }
+  if (typeof parsedTreeJSON !== "object" || parsedTreeJSON === null || Array.isArray(parsedTreeJSON)) {
+    throw new PageCorruptionError("treeJSON must be a non-null plain object.");
+  }
+  return {
+    treeJSON: parsedTreeJSON,
+    rawJsonLength: computeUtf8ByteLength(dataText)
+  };
+};
+var loadOpfsSnapshot = async (dir) => {
+  let metaText;
+  try {
+    const metaHandle = await dir.getFileHandle(META_FILE, { create: false });
+    const metaFile = await metaHandle.getFile();
+    metaText = await metaFile.text();
+  } catch (error) {
+    if (!isNotFoundError(error)) {
+      throw toStorageEngineError(error, "OPFS meta.json read failed");
+    }
+    return {
+      treeJSON: null,
+      currentSizeBytes: 0,
+      commitId: 0,
+      activeData: "a"
+    };
+  }
+  const { commitId, activeData } = parseOpfsManifest(metaText);
+  const dataFileName = activeData === "a" ? DATA_FILE_A : DATA_FILE_B;
+  const { treeJSON, rawJsonLength } = await loadOpfsDataFile(dir, dataFileName);
+  const currentSizeBytes = rawJsonLength;
+  return { treeJSON, currentSizeBytes, commitId, activeData };
+};
+var commitOpfsSnapshot = async (dir, currentActiveData, treeJSON, commitId) => {
+  const nextActiveData = currentActiveData === "a" ? "b" : "a";
+  const dataFileName = nextActiveData === "a" ? DATA_FILE_A : DATA_FILE_B;
+  const dataJson = JSON.stringify(treeJSON);
+  try {
+    const dataHandle = await dir.getFileHandle(dataFileName, { create: true });
+    const dataWritable = await dataHandle.createWritable();
+    await dataWritable.write(dataJson);
+    await dataWritable.close();
+    const newManifest = {
+      magic: OPFS_MAGIC,
+      version: OPFS_VERSION_VALUE,
+      activeData: nextActiveData,
+      commitId
+    };
+    const metaHandle = await dir.getFileHandle(META_FILE, { create: true });
+    const metaWritable = await metaHandle.createWritable();
+    await metaWritable.write(JSON.stringify(newManifest));
+    await metaWritable.close();
+  } catch (error) {
+    throw toStorageEngineError(error, "OPFS commit failed");
+  }
+  return nextActiveData;
+};
+
+// src/storage/drivers/opfs/opfsBackendController.ts
+var DEFAULT_DIRECTORY_NAME = "frostpillar";
+var OpfsBackendController = class _OpfsBackendController extends AsyncDurableAutoCommitController {
+  constructor(dir, activeData, commitId, autoCommit, getSnapshot, onAutoCommitError) {
+    super(autoCommit, onAutoCommitError);
+    this.dir = dir;
+    this.activeData = activeData;
+    this.commitId = commitId;
+    this.getSnapshot = getSnapshot;
+  }
+  static async create(options) {
+    const storageRoot = detectGlobalOpfs();
+    if (storageRoot === null) {
+      throw new UnsupportedBackendError(
+        "opfs (Origin Private File System) is not available in the current runtime environment."
+      );
+    }
+    const opfsConfig = options.config;
+    const directoryName = opfsConfig?.directoryName ?? DEFAULT_DIRECTORY_NAME;
+    const autoCommit = parseAutoCommitConfig(options.autoCommit);
+    const dir = await openOpfsDirectory(storageRoot, directoryName);
+    const loaded = await loadOpfsSnapshot(dir);
+    const controller = new _OpfsBackendController(
+      dir,
+      loaded.activeData,
+      loaded.commitId,
+      autoCommit,
+      options.getSnapshot,
+      options.onAutoCommitError
+    );
+    return {
+      controller,
+      initialTreeJSON: loaded.treeJSON,
+      initialCurrentSizeBytes: loaded.currentSizeBytes
+    };
+  }
+  async executeSingleCommit() {
+    const snapshot = this.getSnapshot();
+    if (this.commitId >= Number.MAX_SAFE_INTEGER) {
+      throw new StorageEngineError("OPFS commitId has reached Number.MAX_SAFE_INTEGER.");
+    }
+    const nextCommitId = this.commitId + 1;
+    this.activeData = await commitOpfsSnapshot(
+      this.dir,
+      this.activeData,
+      snapshot.treeJSON,
+      nextCommitId
+    );
+    this.commitId = nextCommitId;
+  }
+};
+
+// src/drivers/opfs.ts
+var opfsDriver = (options = {}) => {
+  return {
+    init: async (callbacks) => {
+      const result = await OpfsBackendController.create({
+        config: options,
+        autoCommit: callbacks.autoCommit,
+        getSnapshot: callbacks.getSnapshot,
+        onAutoCommitError: callbacks.onAutoCommitError
+      });
+      return {
+        controller: result.controller,
+        initialTreeJSON: result.initialTreeJSON,
+        initialCurrentSizeBytes: result.initialCurrentSizeBytes
+      };
+    }
+  };
+};
+
+// src/storage/drivers/syncStorage/syncStorageConfig.ts
+var DEFAULT_SYNC_STORAGE_MAX_TOTAL_BYTES = 102400;
+var parseSyncStorageMaxTotalBytesForBackendLimit = (config) => {
+  const maxTotalBytes = config?.maxTotalBytes ?? DEFAULT_SYNC_STORAGE_MAX_TOTAL_BYTES;
+  if (!Number.isSafeInteger(maxTotalBytes) || maxTotalBytes <= 0) {
+    throw new ConfigurationError(
+      "syncStorage.maxTotalBytes must be a positive safe integer."
+    );
+  }
+  return maxTotalBytes;
+};
+var parseSyncStorageConfig = (config) => {
+  const keyPrefix = config?.keyPrefix ?? "frostpillar";
+  const databaseKey = config?.databaseKey ?? "default";
+  const maxChunkChars = config?.maxChunkChars ?? 6e3;
+  const maxChunks = config?.maxChunks ?? 511;
+  const maxItemBytes = config?.maxItemBytes ?? 8192;
+  const maxTotalBytes = parseSyncStorageMaxTotalBytesForBackendLimit(config);
+  const maxItems = config?.maxItems ?? 512;
+  if (!Number.isSafeInteger(maxChunkChars) || maxChunkChars <= 0) {
+    throw new ConfigurationError(
+      "syncStorage.maxChunkChars must be a positive safe integer."
+    );
+  }
+  if (!Number.isSafeInteger(maxChunks) || maxChunks <= 0) {
+    throw new ConfigurationError(
+      "syncStorage.maxChunks must be a positive safe integer."
+    );
+  }
+  if (!Number.isSafeInteger(maxItemBytes) || maxItemBytes <= 0) {
+    throw new ConfigurationError(
+      "syncStorage.maxItemBytes must be a positive safe integer."
+    );
+  }
+  if (!Number.isSafeInteger(maxItems) || maxItems <= 0) {
+    throw new ConfigurationError(
+      "syncStorage.maxItems must be a positive safe integer."
+    );
+  }
+  if (maxChunks + 1 > maxItems) {
+    throw new ConfigurationError(
+      "syncStorage.maxChunks + 1 (manifest item) must be <= syncStorage.maxItems."
+    );
+  }
+  return {
+    keyPrefix,
+    databaseKey,
+    maxChunkChars,
+    maxChunks,
+    maxItemBytes,
+    maxTotalBytes,
+    maxItems
+  };
+};
+
+// src/validation/typeGuards.ts
+var isRecordObject = (value) => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+};
+
+// src/storage/drivers/syncStorage/syncStorageAdapter.ts
+var readChromeRuntimeError = (runtime) => {
+  const runtimeMessage = runtime?.lastError?.message;
+  if (runtimeMessage === void 0) {
+    return null;
+  }
+  if (runtimeMessage.trim().length === 0) {
+    return new Error("chrome.runtime.lastError is set with an empty message.");
+  }
+  return new Error(runtimeMessage);
+};
+var callChromeCallbackGet = (syncArea, runtime, keys) => {
+  return new Promise((resolve, reject) => {
+    try {
+      syncArea.get(keys, (items) => {
+        const runtimeError = readChromeRuntimeError(runtime);
+        if (runtimeError !== null) {
+          reject(runtimeError);
+          return;
+        }
+        resolve(items);
+      });
+    } catch (error) {
+      reject(
+        toErrorInstance(error, "chrome.storage.sync.get failed with a non-Error value.")
+      );
+    }
+  });
+};
+var callChromeCallbackSet = (syncArea, runtime, items) => {
+  return new Promise((resolve, reject) => {
+    try {
+      syncArea.set(items, () => {
+        const runtimeError = readChromeRuntimeError(runtime);
+        if (runtimeError !== null) {
+          reject(runtimeError);
+          return;
+        }
+        resolve();
+      });
+    } catch (error) {
+      reject(
+        toErrorInstance(error, "chrome.storage.sync.set failed with a non-Error value.")
+      );
+    }
+  });
+};
+var callChromeCallbackRemove = (syncArea, runtime, keys) => {
+  return new Promise((resolve, reject) => {
+    try {
+      syncArea.remove(keys, () => {
+        const runtimeError = readChromeRuntimeError(runtime);
+        if (runtimeError !== null) {
+          reject(runtimeError);
+          return;
+        }
+        resolve();
+      });
+    } catch (error) {
+      reject(
+        toErrorInstance(
+          error,
+          "chrome.storage.sync.remove failed with a non-Error value."
+        )
+      );
+    }
+  });
+};
+var createBrowserPromiseSyncStorageAdapter = (syncArea) => {
+  return {
+    getItems: async (keys) => {
+      return await syncArea.get(keys);
+    },
+    setItems: async (items) => {
+      await syncArea.set(items);
+    },
+    removeItems: async (keys) => {
+      await syncArea.remove(keys);
+    }
+  };
+};
+var createChromeCallbackSyncStorageAdapter = (syncArea, runtime) => {
+  return {
+    getItems: async (keys) => {
+      return await callChromeCallbackGet(syncArea, runtime, keys);
+    },
+    setItems: async (items) => {
+      await callChromeCallbackSet(syncArea, runtime, items);
+    },
+    removeItems: async (keys) => {
+      await callChromeCallbackRemove(syncArea, runtime, keys);
+    }
+  };
+};
+var hasSyncAreaFunctionShape = (value) => {
+  if (!isRecordObject(value)) {
+    return false;
+  }
+  return typeof value.get === "function" && typeof value.set === "function" && typeof value.remove === "function";
+};
+var hasBrowserPromiseSyncArea = (value) => {
+  return hasSyncAreaFunctionShape(value);
+};
+var hasChromeCallbackSyncArea = (value) => {
+  return hasSyncAreaFunctionShape(value);
+};
+var detectGlobalSyncStorage = () => {
+  try {
+    const globals = globalThis;
+    const browserSync = globals.browser?.storage?.sync;
+    if (hasBrowserPromiseSyncArea(browserSync)) {
+      return createBrowserPromiseSyncStorageAdapter(browserSync);
+    }
+    const chromeSync = globals.chrome?.storage?.sync;
+    if (hasChromeCallbackSyncArea(chromeSync)) {
+      const runtime = globals.chrome?.runtime ?? null;
+      return createChromeCallbackSyncStorageAdapter(chromeSync, runtime);
+    }
+    return null;
+  } catch {
+    return null;
+  }
+};
+
+// src/storage/drivers/syncStorage/syncStorageChunkMaintenance.ts
+var cleanupGenerationChunks2 = async (state, generation, knownChunkCount, chunkKeyResolver) => {
+  if (knownChunkCount !== null) {
+    if (knownChunkCount <= 0) {
+      return;
+    }
+    const knownKeys = [];
+    for (let i = 0; i < knownChunkCount; i += 1) {
+      knownKeys.push(chunkKeyResolver(generation, i));
+    }
+    await state.adapter.removeItems(knownKeys);
+    return;
+  }
+  if (state.maxChunks <= 0) {
+    return;
+  }
+  const speculativeKeys = [];
+  for (let i = 0; i < state.maxChunks; i += 1) {
+    speculativeKeys.push(chunkKeyResolver(generation, i));
+  }
+  const maybeChunks = await state.adapter.getItems(speculativeKeys);
+  const discoveredKeys = speculativeKeys.filter((key) => {
+    return Object.prototype.hasOwnProperty.call(maybeChunks, key);
+  });
+  if (discoveredKeys.length === 0) {
+    return;
+  }
+  await state.adapter.removeItems(discoveredKeys);
+};
+
+// src/storage/drivers/syncStorage/syncStorageQuota.ts
+var utf8Encoder = new TextEncoder();
+var computeSyncStorageItemBytes = (key, value) => {
+  const valueJson = JSON.stringify(value);
+  if (valueJson === void 0) {
+    throw new StorageEngineError(
+      `syncStorage value for key "${key}" cannot be serialized.`
+    );
+  }
+  return utf8Encoder.encode(key).byteLength + utf8Encoder.encode(valueJson).byteLength;
+};
+var isQuotaBrowserError2 = (error) => {
+  if (error instanceof QuotaExceededError) {
+    return true;
+  }
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  const normalized = `${error.name}:${error.message}`;
+  return /quota|max_items|quota_bytes|quota_bytes_per_item/i.test(normalized);
+};
+var validateSyncStorageCommitQuota = (state, generation, chunks, manifest, resolveChunkKey, manifestStorageKey) => {
+  const pendingItems = chunks.map(
+    (chunkValue, chunkIndex) => {
+      return {
+        key: resolveChunkKey(generation, chunkIndex),
+        value: chunkValue
+      };
+    }
+  );
+  pendingItems.push({
+    key: manifestStorageKey,
+    value: manifest
+  });
+  if (pendingItems.length > state.maxItems) {
+    throw new QuotaExceededError(
+      `syncStorage snapshot requires ${pendingItems.length} items but maxItems is ${state.maxItems}.`
+    );
+  }
+  let totalBytes = 0;
+  for (const pendingItem of pendingItems) {
+    const itemBytes = computeSyncStorageItemBytes(
+      pendingItem.key,
+      pendingItem.value
+    );
+    if (itemBytes > state.maxItemBytes) {
+      throw new QuotaExceededError(
+        `syncStorage item "${pendingItem.key}" requires ${itemBytes} bytes but maxItemBytes is ${state.maxItemBytes}.`
+      );
+    }
+    totalBytes += itemBytes;
+  }
+  if (totalBytes > state.maxTotalBytes) {
+    throw new QuotaExceededError(
+      `syncStorage snapshot requires ${totalBytes} bytes but maxTotalBytes is ${state.maxTotalBytes}.`
+    );
+  }
+};
+
+// src/storage/drivers/syncStorage/syncStorageBackend.ts
+var SYNC_STORAGE_MAGIC = "FPSYNC_META";
+var SYNC_STORAGE_VERSION = 2;
+var manifestKey2 = (keyPrefix, databaseKey) => {
+  return `${keyPrefix}:sync:${databaseKey}:manifest`;
+};
+var chunkKey2 = (keyPrefix, databaseKey, generation, index) => {
+  return `${keyPrefix}:sync:${databaseKey}:g:${generation}:chunk:${index}`;
+};
+var createSyncStorageBackendState = (adapter, keyPrefix, databaseKey, maxChunkChars, maxChunks, maxItemBytes, maxTotalBytes, maxItems) => {
+  return {
+    adapter,
+    keyPrefix,
+    databaseKey,
+    maxChunkChars,
+    maxChunks,
+    maxItemBytes,
+    maxTotalBytes,
+    maxItems,
+    activeGeneration: 0,
+    commitId: 0,
+    activeChunkCount: 0
+  };
+};
+var parseSyncManifest = (manifestUnknown, maxChunks) => {
+  if (!isRecordObject(manifestUnknown)) {
+    throw new StorageEngineError("syncStorage manifest must be an object.");
+  }
+  const manifest = manifestUnknown;
+  if (manifest.magic !== SYNC_STORAGE_MAGIC || manifest.version !== SYNC_STORAGE_VERSION) {
+    throw new StorageEngineError("syncStorage manifest magic/version mismatch.");
+  }
+  const chunkCount = parseNonNegativeSafeInteger(
+    manifest.chunkCount,
+    "manifest.chunkCount",
+    "syncStorage"
+  );
+  if (chunkCount > maxChunks) {
+    throw new StorageEngineError(
+      `syncStorage snapshot requires ${chunkCount} chunks but maxChunks is ${maxChunks}.`
+    );
+  }
+  return manifest;
+};
+var loadSyncChunksAndDecodeTreeJSON = async (state, activeGeneration, chunkCount) => {
+  const chunkKeys = [];
+  for (let i = 0; i < chunkCount; i += 1) {
+    chunkKeys.push(
+      chunkKey2(state.keyPrefix, state.databaseKey, activeGeneration, i)
+    );
+  }
+  const chunkValuesByKey = chunkKeys.length === 0 ? {} : await state.adapter.getItems(chunkKeys);
+  const chunks = [];
+  for (const cKey of chunkKeys) {
+    const chunkValue = chunkValuesByKey[cKey];
+    if (typeof chunkValue !== "string") {
+      throw new StorageEngineError(
+        `syncStorage chunk "${cKey}" is missing or not a string.`
+      );
+    }
+    chunks.push(chunkValue);
+  }
+  const treeJson = chunks.join("");
+  let parsedTreeJSON;
+  try {
+    parsedTreeJSON = JSON.parse(treeJson);
+  } catch {
+    throw new StorageEngineError("syncStorage chunk data JSON is malformed.");
+  }
+  if (typeof parsedTreeJSON !== "object" || parsedTreeJSON === null || Array.isArray(parsedTreeJSON)) {
+    throw new PageCorruptionError("treeJSON must be a non-null plain object.");
+  }
+  return {
+    treeJSON: parsedTreeJSON,
+    rawJsonLength: computeUtf8ByteLength(treeJson)
+  };
+};
+var loadSyncStorageSnapshot = async (state) => {
+  const mKey = manifestKey2(state.keyPrefix, state.databaseKey);
+  const manifestMap = await state.adapter.getItems([mKey]);
+  const manifestUnknown = manifestMap[mKey];
+  if (manifestUnknown === void 0) {
+    return { treeJSON: null, currentSizeBytes: 0 };
+  }
+  const manifest = parseSyncManifest(manifestUnknown, state.maxChunks);
+  const activeGeneration = parseNonNegativeSafeInteger(
+    manifest.activeGeneration,
+    "manifest.activeGeneration",
+    "syncStorage"
+  );
+  const commitId = parseNonNegativeSafeInteger(
+    manifest.commitId,
+    "manifest.commitId",
+    "syncStorage"
+  );
+  const chunkCount = parseNonNegativeSafeInteger(
+    manifest.chunkCount,
+    "manifest.chunkCount",
+    "syncStorage"
+  );
+  const { treeJSON, rawJsonLength } = await loadSyncChunksAndDecodeTreeJSON(
+    state,
+    activeGeneration,
+    chunkCount
+  );
+  const currentSizeBytes = rawJsonLength;
+  state.activeGeneration = activeGeneration;
+  state.commitId = commitId;
+  state.activeChunkCount = chunkCount;
+  return { treeJSON, currentSizeBytes };
+};
+var buildSyncChunkKeyResolver = (state) => {
+  return (generation, index) => {
+    return chunkKey2(state.keyPrefix, state.databaseKey, generation, index);
+  };
+};
+var buildSyncCommitItems = (state, chunks, newManifest, nextGeneration) => {
+  const mKey = manifestKey2(state.keyPrefix, state.databaseKey);
+  const items = { [mKey]: newManifest };
+  for (let i = 0; i < chunks.length; i += 1) {
+    const cKey = chunkKey2(state.keyPrefix, state.databaseKey, nextGeneration, i);
+    items[cKey] = chunks[i];
+  }
+  return items;
+};
+var splitSyncTreeJSONIntoChunks = (treeJSON, maxChunkChars, maxChunks) => {
+  const dataJson = JSON.stringify(treeJSON);
+  const chunks = [];
+  for (let i = 0; i < dataJson.length; i += maxChunkChars) {
+    chunks.push(dataJson.slice(i, i + maxChunkChars));
+  }
+  if (chunks.length > maxChunks) {
+    throw new QuotaExceededError(
+      `syncStorage snapshot requires ${chunks.length} chunks but maxChunks is ${maxChunks}.`
+    );
+  }
+  return chunks;
+};
+var ensureSyncCommitCountersSafe = (state) => {
+  if (state.commitId >= Number.MAX_SAFE_INTEGER) {
+    throw new StorageEngineError("syncStorage commitId has reached Number.MAX_SAFE_INTEGER.");
+  }
+  if (state.activeGeneration >= Number.MAX_SAFE_INTEGER) {
+    throw new StorageEngineError("syncStorage activeGeneration has reached Number.MAX_SAFE_INTEGER.");
+  }
+};
+var commitSyncStorageSnapshot = async (state, treeJSON) => {
+  ensureSyncCommitCountersSafe(state);
+  const nextCommitId = state.commitId + 1;
+  const nextGeneration = state.activeGeneration + 1;
+  const chunks = splitSyncTreeJSONIntoChunks(
+    treeJSON,
+    state.maxChunkChars,
+    state.maxChunks
+  );
+  const newManifest = {
+    magic: SYNC_STORAGE_MAGIC,
+    version: SYNC_STORAGE_VERSION,
+    activeGeneration: nextGeneration,
+    commitId: nextCommitId,
+    chunkCount: chunks.length
+  };
+  const resolveChunkKey = buildSyncChunkKeyResolver(state);
+  const mKey = manifestKey2(state.keyPrefix, state.databaseKey);
+  validateSyncStorageCommitQuota(
+    state,
+    nextGeneration,
+    chunks,
+    newManifest,
+    resolveChunkKey,
+    mKey
+  );
+  const newSnapshotItems = buildSyncCommitItems(
+    state,
+    chunks,
+    newManifest,
+    nextGeneration
+  );
+  try {
+    await cleanupGenerationChunks2(state, nextGeneration, null, resolveChunkKey);
+  } catch {
+  }
+  try {
+    await state.adapter.setItems(newSnapshotItems);
+  } catch (error) {
+    if (isQuotaBrowserError2(error)) {
+      throw new QuotaExceededError("syncStorage quota exceeded during commit.");
+    }
+    throw new StorageEngineError(
+      "syncStorage write failed during commit.",
+      { cause: error }
+    );
+  }
+  const previousGeneration = state.activeGeneration;
+  const previousChunkCount = state.activeChunkCount;
+  state.activeGeneration = nextGeneration;
+  state.commitId = nextCommitId;
+  state.activeChunkCount = chunks.length;
+  await cleanupGenerationChunks2(
+    state,
+    previousGeneration,
+    previousChunkCount,
+    resolveChunkKey
+  );
+};
+
+// src/storage/drivers/syncStorage/syncStorageBackendController.ts
+var SyncStorageBackendController = class _SyncStorageBackendController extends AsyncDurableAutoCommitController {
+  constructor(backend, autoCommit, getSnapshot, onAutoCommitError) {
+    super(autoCommit, onAutoCommitError);
+    this.backend = backend;
+    this.getSnapshot = getSnapshot;
+  }
+  static async create(options) {
+    const adapter = detectGlobalSyncStorage();
+    if (adapter === null) {
+      throw new UnsupportedBackendError(
+        "browser sync storage is not available in the current runtime environment."
+      );
+    }
+    const syncConfig = parseSyncStorageConfig(options.config);
+    const autoCommit = parseAutoCommitConfig(options.autoCommit);
+    const backend = createSyncStorageBackendState(
+      adapter,
+      syncConfig.keyPrefix,
+      syncConfig.databaseKey,
+      syncConfig.maxChunkChars,
+      syncConfig.maxChunks,
+      syncConfig.maxItemBytes,
+      syncConfig.maxTotalBytes,
+      syncConfig.maxItems
+    );
+    const loaded = await loadSyncStorageSnapshot(backend);
+    const controller = new _SyncStorageBackendController(
+      backend,
+      autoCommit,
+      options.getSnapshot,
+      options.onAutoCommitError
+    );
+    return {
+      controller,
+      initialTreeJSON: loaded.treeJSON,
+      initialCurrentSizeBytes: loaded.currentSizeBytes
+    };
+  }
+  async executeSingleCommit() {
+    const snapshot = this.getSnapshot();
+    await commitSyncStorageSnapshot(
+      this.backend,
+      snapshot.treeJSON
+    );
+  }
+};
+
+// src/drivers/syncStorage.ts
+var syncStorageDriver = (options = {}) => {
+  return {
+    init: async (callbacks) => {
+      const result = await SyncStorageBackendController.create({
+        config: options,
+        autoCommit: callbacks.autoCommit,
+        getSnapshot: callbacks.getSnapshot,
+        onAutoCommitError: callbacks.onAutoCommitError
+      });
+      return {
+        controller: result.controller,
+        initialTreeJSON: result.initialTreeJSON,
+        initialCurrentSizeBytes: result.initialCurrentSizeBytes
+      };
+    },
+    resolveBackendLimitBytes: () => {
+      return parseSyncStorageMaxTotalBytesForBackendLimit(options);
+    }
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BinaryFormatError,
+  ClosedDatastoreError,
+  ConfigurationError,
+  DatabaseLockedError,
+  Datastore,
+  FrostpillarError,
+  IndexCorruptionError,
+  InvalidQueryRangeError,
+  PageCorruptionError,
+  QuotaExceededError,
+  StorageEngineError,
+  UnsupportedBackendError,
+  ValidationError,
+  indexedDBDriver,
+  localStorageDriver,
+  opfsDriver,
+  syncStorageDriver
+});