lakesync 0.1.0

package/dist/compactor.js

@@ -0,0 +1,793 @@
+import {
+  encodeSyncResponse
+} from "./chunk-BNJOGBYK.js";
+import {
+  readParquetToDeltas,
+  writeDeltasToParquet
+} from "./chunk-4ARO6KTJ.js";
+import {
+  Err,
+  FlushError,
+  HLC,
+  LakeSyncError,
+  Ok,
+  rowKey
+} from "./chunk-ICNT7I3K.js";
+import "./chunk-7D4SUZUM.js";
+
+// ../compactor/src/checkpoint-generator.ts
+var DEFAULT_CHECKPOINT_CONFIG = {
+  chunkBytes: 16 * 1024 * 1024
+};
+var ESTIMATED_BASE_BYTES = 200;
+var ESTIMATED_BYTES_PER_COLUMN = 50;
+var CheckpointGenerator = class {
+  adapter;
+  gatewayId;
+  config;
+  constructor(adapter, _schema, gatewayId, config) {
+    this.adapter = adapter;
+    this.gatewayId = gatewayId;
+    this.config = config ?? DEFAULT_CHECKPOINT_CONFIG;
+  }
+  /**
+   * Generate checkpoint chunks from base Parquet files.
+   *
+   * Reads each base file sequentially, accumulates deltas, and flushes
+   * chunks when the estimated byte size exceeds the configured threshold.
+   *
+   * @param baseFileKeys - Storage keys of the base Parquet files
+   * @param snapshotHlc - The HLC timestamp representing this snapshot point
+   * @returns A Result containing the CheckpointResult, or a LakeSyncError on failure
+   */
+  async generate(baseFileKeys, snapshotHlc) {
+    if (baseFileKeys.length === 0) {
+      return Ok({ chunksWritten: 0, bytesWritten: 0, snapshotHlc });
+    }
+    const prefix = `checkpoints/${this.gatewayId}`;
+    const chunkNames = [];
+    let totalBytesWritten = 0;
+    let totalDeltas = 0;
+    let accumulator = [];
+    let accumulatedBytes = 0;
+    for (const key of baseFileKeys) {
+      const getResult = await this.adapter.getObject(key);
+      if (!getResult.ok) {
+        return Err(
+          new LakeSyncError(
+            `Failed to read base file: ${key}`,
+            "CHECKPOINT_READ_ERROR",
+            getResult.error
+          )
+        );
+      }
+      const parseResult = await readParquetToDeltas(getResult.value);
+      if (!parseResult.ok) {
+        return Err(
+          new LakeSyncError(
+            `Failed to parse base file: ${key}`,
+            "CHECKPOINT_PARSE_ERROR",
+            parseResult.error
+          )
+        );
+      }
+      for (const delta of parseResult.value) {
+        accumulator.push(delta);
+        accumulatedBytes += ESTIMATED_BASE_BYTES + delta.columns.length * ESTIMATED_BYTES_PER_COLUMN;
+        if (accumulatedBytes >= this.config.chunkBytes) {
+          const flushResult = await this.flushChunk(
+            prefix,
+            chunkNames.length,
+            accumulator,
+            snapshotHlc
+          );
+          if (!flushResult.ok) return flushResult;
+          totalBytesWritten += flushResult.value;
+          totalDeltas += accumulator.length;
+          chunkNames.push(this.chunkFileName(chunkNames.length));
+          accumulator = [];
+          accumulatedBytes = 0;
+        }
+      }
+    }
+    if (accumulator.length > 0) {
+      const flushResult = await this.flushChunk(
+        prefix,
+        chunkNames.length,
+        accumulator,
+        snapshotHlc
+      );
+      if (!flushResult.ok) return flushResult;
+      totalBytesWritten += flushResult.value;
+      totalDeltas += accumulator.length;
+      chunkNames.push(this.chunkFileName(chunkNames.length));
+    }
+    const manifest = {
+      snapshotHlc: snapshotHlc.toString(),
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      chunkCount: chunkNames.length,
+      totalDeltas,
+      chunks: chunkNames
+    };
+    const manifestBytes = new TextEncoder().encode(JSON.stringify(manifest));
+    const manifestResult = await this.adapter.putObject(
+      `${prefix}/manifest.json`,
+      manifestBytes,
+      "application/json"
+    );
+    if (!manifestResult.ok) {
+      return Err(
+        new LakeSyncError(
+          "Failed to write checkpoint manifest",
+          "CHECKPOINT_WRITE_ERROR",
+          manifestResult.error
+        )
+      );
+    }
+    totalBytesWritten += manifestBytes.byteLength;
+    return Ok({
+      chunksWritten: chunkNames.length,
+      bytesWritten: totalBytesWritten,
+      snapshotHlc
+    });
+  }
+  /**
+   * Get all storage keys produced by a checkpoint generation.
+   * Useful for adding to activeKeys in maintenance to prevent orphan removal.
+   */
+  getCheckpointKeys(chunkCount) {
+    const prefix = `checkpoints/${this.gatewayId}`;
+    const keys = [`${prefix}/manifest.json`];
+    for (let i = 0; i < chunkCount; i++) {
+      keys.push(`${prefix}/${this.chunkFileName(i)}`);
+    }
+    return keys;
+  }
+  chunkFileName(index) {
+    return `chunk-${String(index).padStart(3, "0")}.bin`;
+  }
+  async flushChunk(prefix, index, deltas, snapshotHlc) {
+    const encodeResult = encodeSyncResponse({
+      deltas,
+      serverHlc: snapshotHlc,
+      hasMore: false
+    });
+    if (!encodeResult.ok) {
+      return Err(
+        new LakeSyncError(
+          `Failed to encode checkpoint chunk ${index}`,
+          "CHECKPOINT_ENCODE_ERROR",
+          encodeResult.error
+        )
+      );
+    }
+    const data = encodeResult.value;
+    const chunkKey = `${prefix}/${this.chunkFileName(index)}`;
+    const putResult = await this.adapter.putObject(chunkKey, data, "application/octet-stream");
+    if (!putResult.ok) {
+      return Err(
+        new LakeSyncError(
+          `Failed to write checkpoint chunk: ${chunkKey}`,
+          "CHECKPOINT_WRITE_ERROR",
+          putResult.error
+        )
+      );
+    }
+    return Ok(data.byteLength);
+  }
+};
+
+// ../compactor/src/equality-delete.ts
+var EQUALITY_DELETE_SCHEMA = {
+  table: "_equality_delete",
+  columns: []
+};
+var SENTINEL_HLC = HLC.encode(0, 0);
+async function writeEqualityDeletes(deletedRows, _schema) {
+  if (deletedRows.length === 0) {
+    return Ok(new Uint8Array(0));
+  }
+  try {
+    const syntheticDeltas = deletedRows.map((row, index) => ({
+      op: "DELETE",
+      table: row.table,
+      rowId: row.rowId,
+      clientId: "_compactor",
+      columns: [],
+      hlc: SENTINEL_HLC,
+      deltaId: `eq-delete-${index}`
+    }));
+    return await writeDeltasToParquet(syntheticDeltas, EQUALITY_DELETE_SCHEMA);
+  } catch (err) {
+    const cause = err instanceof Error ? err : new Error(String(err));
+    return Err(new FlushError(`Failed to write equality deletes: ${cause.message}`, cause));
+  }
+}
+async function readEqualityDeletes(data) {
+  if (data.byteLength === 0) {
+    return Ok([]);
+  }
+  const readResult = await readParquetToDeltas(data);
+  if (!readResult.ok) {
+    return Err(
+      new FlushError(
+        `Failed to read equality deletes: ${readResult.error.message}`,
+        readResult.error
+      )
+    );
+  }
+  const rows = readResult.value.map((delta) => ({
+    table: delta.table,
+    rowId: delta.rowId
+  }));
+  return Ok(rows);
+}
+
+// ../compactor/src/compactor.ts
+var Compactor = class {
+  adapter;
+  config;
+  schema;
+  /**
+   * Create a new Compactor instance.
+   *
+   * @param adapter - The lake adapter for reading/writing Parquet files
+   * @param config - Compaction configuration (thresholds and limits)
+   * @param schema - The table schema describing user-defined columns
+   */
+  constructor(adapter, config, schema) {
+    this.adapter = adapter;
+    this.config = config;
+    this.schema = schema;
+  }
+  /**
+   * Compact delta files into base data files.
+   *
+   * Reads delta files from storage, resolves all deltas per row using LWW,
+   * and writes consolidated base files + equality delete files.
+   *
+   * @param deltaFileKeys - Storage keys of the delta Parquet files to compact
+   * @param outputPrefix - Prefix for the output base/delete file keys
+   * @returns A Result containing the CompactionResult, or a LakeSyncError on failure
+   */
+  async compact(deltaFileKeys, outputPrefix) {
+    if (deltaFileKeys.length < this.config.minDeltaFiles) {
+      return Ok({
+        baseFilesWritten: 0,
+        deleteFilesWritten: 0,
+        deltaFilesCompacted: 0,
+        bytesRead: 0,
+        bytesWritten: 0
+      });
+    }
+    const keysToCompact = deltaFileKeys.slice(0, this.config.maxDeltaFiles);
+    const resolveResult = await this.readAndResolveIncrementally(keysToCompact);
+    if (!resolveResult.ok) return resolveResult;
+    const { liveRows, deletedRows, bytesRead } = resolveResult.value;
+    const writeResult = await this.writeOutputFiles(liveRows, deletedRows, outputPrefix);
+    if (!writeResult.ok) return writeResult;
+    return Ok({
+      ...writeResult.value,
+      deltaFilesCompacted: keysToCompact.length,
+      bytesRead
+    });
+  }
+  /**
+   * Read delta files one at a time and incrementally resolve to final row state.
+   *
+   * Memory usage is O(unique rows x columns) rather than O(total deltas),
+   * since each file's deltas are processed and discarded before reading the next.
+   */
+  async readAndResolveIncrementally(keysToCompact) {
+    const rowStates = /* @__PURE__ */ new Map();
+    let bytesRead = 0;
+    for (const key of keysToCompact) {
+      const getResult = await this.adapter.getObject(key);
+      if (!getResult.ok) {
+        return Err(
+          new LakeSyncError(
+            `Failed to read delta file: ${key}`,
+            "COMPACTION_READ_ERROR",
+            getResult.error
+          )
+        );
+      }
+      const data = getResult.value;
+      bytesRead += data.byteLength;
+      const parseResult = await readParquetToDeltas(data);
+      if (!parseResult.ok) {
+        return Err(
+          new LakeSyncError(
+            `Failed to parse delta file: ${key}`,
+            "COMPACTION_PARSE_ERROR",
+            parseResult.error
+          )
+        );
+      }
+      for (const delta of parseResult.value) {
+        const k = rowKey(delta.table, delta.rowId);
+        let state = rowStates.get(k);
+        if (!state) {
+          state = {
+            table: delta.table,
+            rowId: delta.rowId,
+            clientId: delta.clientId,
+            columns: /* @__PURE__ */ new Map(),
+            latestHlc: 0n,
+            latestDeltaId: delta.deltaId,
+            deleteHlc: 0n
+          };
+          rowStates.set(k, state);
+        }
+        if (HLC.compare(delta.hlc, state.latestHlc) > 0) {
+          state.latestHlc = delta.hlc;
+          state.latestDeltaId = delta.deltaId;
+          state.clientId = delta.clientId;
+        }
+        if (delta.op === "DELETE") {
+          if (HLC.compare(delta.hlc, state.deleteHlc) > 0) {
+            state.deleteHlc = delta.hlc;
+          }
+        } else {
+          for (const col of delta.columns) {
+            const existing = state.columns.get(col.column);
+            if (!existing || HLC.compare(delta.hlc, existing.hlc) > 0) {
+              state.columns.set(col.column, {
+                value: col.value,
+                hlc: delta.hlc
+              });
+            }
+          }
+        }
+      }
+    }
+    const liveRows = [];
+    const deletedRows = [];
+    for (const [, state] of rowStates) {
+      let isDeleted = state.deleteHlc > 0n;
+      if (isDeleted) {
+        for (const col of state.columns.values()) {
+          if (HLC.compare(state.deleteHlc, col.hlc) < 0) {
+            isDeleted = false;
+            break;
+          }
+        }
+      }
+      if (isDeleted || state.columns.size === 0) {
+        deletedRows.push({ table: state.table, rowId: state.rowId });
+      } else {
+        const columns = [];
+        for (const col of this.schema.columns) {
+          const colState = state.columns.get(col.name);
+          if (colState && (state.deleteHlc === 0n || HLC.compare(colState.hlc, state.deleteHlc) > 0)) {
+            columns.push({ column: col.name, value: colState.value });
+          }
+        }
+        liveRows.push({
+          op: "INSERT",
+          table: state.table,
+          rowId: state.rowId,
+          clientId: state.clientId,
+          columns,
+          hlc: state.latestHlc,
+          deltaId: state.latestDeltaId
+        });
+      }
+    }
+    return Ok({ liveRows, deletedRows, bytesRead });
+  }
+  /** Write base Parquet file(s) for live rows and equality delete file(s) for deleted rows. */
+  async writeOutputFiles(liveRows, deletedRows, outputPrefix) {
+    let bytesWritten = 0;
+    let baseFilesWritten = 0;
+    let deleteFilesWritten = 0;
+    if (liveRows.length > 0) {
+      const writeResult = await writeDeltasToParquet(liveRows, this.schema);
+      if (!writeResult.ok) {
+        return Err(
+          new LakeSyncError(
+            "Failed to write base file",
+            "COMPACTION_WRITE_ERROR",
+            writeResult.error
+          )
+        );
+      }
+      const baseData = writeResult.value;
+      const timestamp = this.generateTimestamp();
+      const basePath = `${outputPrefix}/base-${timestamp}.parquet`;
+      const putResult = await this.adapter.putObject(
+        basePath,
+        baseData,
+        "application/octet-stream"
+      );
+      if (!putResult.ok) {
+        return Err(
+          new LakeSyncError(
+            `Failed to store base file: ${basePath}`,
+            "COMPACTION_STORE_ERROR",
+            putResult.error
+          )
+        );
+      }
+      bytesWritten += baseData.byteLength;
+      baseFilesWritten = 1;
+    }
+    if (deletedRows.length > 0) {
+      const writeResult = await writeEqualityDeletes(deletedRows, this.schema);
+      if (!writeResult.ok) {
+        return Err(
+          new LakeSyncError(
+            "Failed to write equality delete file",
+            "COMPACTION_WRITE_ERROR",
+            writeResult.error
+          )
+        );
+      }
+      const deleteData = writeResult.value;
+      const timestamp = this.generateTimestamp();
+      const deletePath = `${outputPrefix}/delete-${timestamp}.parquet`;
+      const putResult = await this.adapter.putObject(
+        deletePath,
+        deleteData,
+        "application/octet-stream"
+      );
+      if (!putResult.ok) {
+        return Err(
+          new LakeSyncError(
+            `Failed to store delete file: ${deletePath}`,
+            "COMPACTION_STORE_ERROR",
+            putResult.error
+          )
+        );
+      }
+      bytesWritten += deleteData.byteLength;
+      deleteFilesWritten = 1;
+    }
+    return Ok({ baseFilesWritten, deleteFilesWritten, bytesWritten });
+  }
+  /**
+   * Generate a timestamp string for output file naming.
+   * Uses the current wall clock time with a random suffix for uniqueness.
+   */
+  generateTimestamp() {
+    const now = Date.now();
+    const suffix = Math.random().toString(36).slice(2, 8);
+    return `${now}-${suffix}`;
+  }
+};
+
+// ../compactor/src/maintenance.ts
+var DEFAULT_MAINTENANCE_CONFIG = {
+  retainSnapshots: 5,
+  orphanAgeMs: 60 * 60 * 1e3
+  // 1 hour
+};
+var MaintenanceRunner = class {
+  compactor;
+  adapter;
+  config;
+  checkpointGenerator;
+  /**
+   * Create a new MaintenanceRunner instance.
+   *
+   * @param compactor - The compactor instance for merging delta files
+   * @param adapter - The lake adapter for storage operations
+   * @param config - Maintenance configuration (retention and age thresholds)
+   * @param checkpointGenerator - Optional checkpoint generator; when provided,
+   *   checkpoints are generated after successful compaction
+   */
+  constructor(compactor, adapter, config, checkpointGenerator) {
+    this.compactor = compactor;
+    this.adapter = adapter;
+    this.config = config;
+    this.checkpointGenerator = checkpointGenerator ?? null;
+  }
+  /**
+   * Run the full maintenance cycle: compact, expire, and clean.
+   *
+   * Compacts delta files into base/delete files, then removes orphaned
+   * storage objects that are no longer referenced by any active data.
+   * Files younger than `orphanAgeMs` are never deleted to avoid races
+   * with in-progress flush operations.
+   *
+   * @param deltaFileKeys - Storage keys of the delta Parquet files to compact
+   * @param outputPrefix - Prefix for the output base/delete file keys
+   * @param storagePrefix - Prefix under which all related storage files live
+   * @returns A Result containing the MaintenanceReport, or a LakeSyncError on failure
+   */
+  async run(deltaFileKeys, outputPrefix, storagePrefix) {
+    const compactionResult = await this.compactor.compact(deltaFileKeys, outputPrefix);
+    if (!compactionResult.ok) {
+      return Err(
+        new LakeSyncError(
+          `Maintenance compaction failed: ${compactionResult.error.message}`,
+          "MAINTENANCE_COMPACTION_ERROR",
+          compactionResult.error
+        )
+      );
+    }
+    const compaction = compactionResult.value;
+    const activeKeys = /* @__PURE__ */ new Set();
+    const compactedCount = compaction.deltaFilesCompacted;
+    for (let i = compactedCount; i < deltaFileKeys.length; i++) {
+      activeKeys.add(deltaFileKeys[i]);
+    }
+    const listOutputResult = await this.adapter.listObjects(outputPrefix);
+    if (!listOutputResult.ok) {
+      return Err(
+        new LakeSyncError(
+          `Failed to list output files: ${listOutputResult.error.message}`,
+          "MAINTENANCE_LIST_ERROR",
+          listOutputResult.error
+        )
+      );
+    }
+    for (const obj of listOutputResult.value) {
+      activeKeys.add(obj.key);
+    }
+    let checkpoint;
+    if (this.checkpointGenerator && compaction.baseFilesWritten > 0) {
+      const baseFileKeys = listOutputResult.value.filter((obj) => obj.key.endsWith(".parquet") && obj.key.includes("/base-")).map((obj) => obj.key);
+      if (baseFileKeys.length > 0) {
+        const snapshotHlc = HLC.encode(Date.now(), 0);
+        const checkpointResult = await this.checkpointGenerator.generate(baseFileKeys, snapshotHlc);
+        if (checkpointResult.ok) {
+          checkpoint = checkpointResult.value;
+          const checkpointKeys = this.checkpointGenerator.getCheckpointKeys(
+            checkpoint.chunksWritten
+          );
+          for (const key of checkpointKeys) {
+            activeKeys.add(key);
+          }
+        }
+      }
+    }
+    const orphanResult = await this.removeOrphans(storagePrefix, activeKeys);
+    if (!orphanResult.ok) {
+      return Err(
+        new LakeSyncError(
+          `Maintenance orphan removal failed: ${orphanResult.error.message}`,
+          "MAINTENANCE_ORPHAN_ERROR",
+          orphanResult.error
+        )
+      );
+    }
+    return Ok({
+      compaction,
+      snapshotsExpired: 0,
+      orphansRemoved: orphanResult.value,
+      checkpoint
+    });
+  }
+  /**
+   * Delete orphaned files not referenced by any active data.
+   *
+   * Lists all files under the given storage prefix, compares each
+   * against the set of active keys, and deletes files that are both
+   * unreferenced and older than `orphanAgeMs`. This age guard
+   * prevents deletion of files created by in-progress flush operations.
+   *
+   * @param storagePrefix - The storage prefix to scan for orphaned files
+   * @param activeKeys - Set of storage keys that must be retained
+   * @returns A Result containing the count of deleted files, or a LakeSyncError on failure
+   */
+  async removeOrphans(storagePrefix, activeKeys) {
+    const listResult = await this.adapter.listObjects(storagePrefix);
+    if (!listResult.ok) {
+      return Err(
+        new LakeSyncError(
+          `Failed to list objects for orphan removal: ${listResult.error.message}`,
+          "MAINTENANCE_LIST_ERROR",
+          listResult.error
+        )
+      );
+    }
+    const now = Date.now();
+    const orphanKeys = this.findOrphans(listResult.value, activeKeys, now);
+    if (orphanKeys.length === 0) {
+      return Ok(0);
+    }
+    const deleteResult = await this.adapter.deleteObjects(orphanKeys);
+    if (!deleteResult.ok) {
+      return Err(
+        new LakeSyncError(
+          `Failed to delete orphaned files: ${deleteResult.error.message}`,
+          "MAINTENANCE_DELETE_ERROR",
+          deleteResult.error
+        )
+      );
+    }
+    return Ok(orphanKeys.length);
+  }
+  /**
+   * Identify orphaned file keys from a list of storage objects.
+   *
+   * A file is considered an orphan if it is not in the active keys set
+   * and its last modification time is older than the configured orphan age.
+   */
+  findOrphans(objects, activeKeys, now) {
+    const orphans = [];
+    for (const obj of objects) {
+      if (activeKeys.has(obj.key)) {
+        continue;
+      }
+      const age = now - obj.lastModified.getTime();
+      if (age >= this.config.orphanAgeMs) {
+        orphans.push(obj.key);
+      }
+    }
+    return orphans;
+  }
+};
+
+// ../compactor/src/scheduler.ts
+var DEFAULT_SCHEDULER_CONFIG = {
+  intervalMs: 6e4,
+  enabled: true
+};
+var CompactionScheduler = class {
+  runner;
+  taskProvider;
+  config;
+  timer = null;
+  running = false;
+  inFlightPromise = null;
+  /**
+   * Create a new CompactionScheduler instance.
+   *
+   * @param runner - The maintenance runner to execute on each tick
+   * @param taskProvider - Function that provides maintenance task parameters for each run
+   * @param config - Scheduler configuration (interval and enabled flag)
+   */
+  constructor(runner, taskProvider, config = {}) {
+    this.runner = runner;
+    this.taskProvider = taskProvider;
+    this.config = { ...DEFAULT_SCHEDULER_CONFIG, ...config };
+  }
+  /**
+   * Whether the scheduler is currently active (timer is ticking).
+   */
+  get isRunning() {
+    return this.running;
+  }
+  /**
+   * Start the scheduler interval timer.
+   *
+   * Begins executing maintenance runs at the configured interval.
+   * If the scheduler is already running or disabled, returns an error.
+   *
+   * @returns A Result indicating success or a descriptive error
+   */
+  start() {
+    if (!this.config.enabled) {
+      return Err(new LakeSyncError("Scheduler is disabled", "SCHEDULER_DISABLED"));
+    }
+    if (this.running) {
+      return Err(new LakeSyncError("Scheduler is already running", "SCHEDULER_ALREADY_RUNNING"));
+    }
+    this.running = true;
+    this.timer = setInterval(() => {
+      void this.tick();
+    }, this.config.intervalMs);
+    return Ok(void 0);
+  }
+  /**
+   * Stop the scheduler and wait for any in-progress run to finish.
+   *
+   * Clears the interval timer and, if a maintenance run is currently
+   * executing, awaits its completion before returning.
+   *
+   * @returns A Result indicating success or a descriptive error
+   */
+  async stop() {
+    if (!this.running) {
+      return Err(new LakeSyncError("Scheduler is not running", "SCHEDULER_NOT_RUNNING"));
+    }
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.running = false;
+    if (this.inFlightPromise !== null) {
+      await this.inFlightPromise;
+      this.inFlightPromise = null;
+    }
+    return Ok(void 0);
+  }
+  /**
+   * Manually trigger a single maintenance run.
+   *
+   * Useful for testing or administrative purposes. If a run is already
+   * in progress, skips and returns an error.
+   *
+   * @returns A Result containing the MaintenanceReport, or a LakeSyncError on failure
+   */
+  async runOnce() {
+    if (this.inFlightPromise !== null) {
+      return Err(new LakeSyncError("A maintenance run is already in progress", "SCHEDULER_BUSY"));
+    }
+    return this.executeMaintenance();
+  }
+  /**
+   * Internal tick handler called by the interval timer.
+   * Skips if a previous run is still in progress.
+   */
+  async tick() {
+    if (this.inFlightPromise !== null) {
+      return;
+    }
+    await this.executeMaintenance();
+  }
+  /**
+   * Execute a single maintenance cycle.
+   *
+   * Calls the task provider to get parameters, then runs the maintenance
+   * runner. Tracks the in-flight promise so concurrent runs are prevented.
+   */
+  async executeMaintenance() {
+    const taskResult = await this.resolveTask();
+    if (!taskResult.ok) {
+      return taskResult;
+    }
+    const task = taskResult.value;
+    if (task === null) {
+      return Ok({
+        compaction: {
+          baseFilesWritten: 0,
+          deleteFilesWritten: 0,
+          deltaFilesCompacted: 0,
+          bytesRead: 0,
+          bytesWritten: 0
+        },
+        snapshotsExpired: 0,
+        orphansRemoved: 0
+      });
+    }
+    const promise = this.runner.run(task.deltaFileKeys, task.outputPrefix, task.storagePrefix);
+    this.inFlightPromise = promise;
+    try {
+      const result = await promise;
+      return result;
+    } finally {
+      this.inFlightPromise = null;
+    }
+  }
+  /**
+   * Resolve the maintenance task from the provider, wrapping any thrown
+   * exceptions into a Result error.
+   */
+  async resolveTask() {
+    try {
+      const task = await this.taskProvider();
+      return Ok(task);
+    } catch (error) {
+      return Err(
+        new LakeSyncError(
+          `Task provider failed: ${error instanceof Error ? error.message : String(error)}`,
+          "SCHEDULER_TASK_PROVIDER_ERROR"
+        )
+      );
+    }
+  }
+};
+
+// ../compactor/src/types.ts
+var DEFAULT_COMPACTION_CONFIG = {
+  minDeltaFiles: 10,
+  maxDeltaFiles: 20,
+  targetFileSizeBytes: 128 * 1024 * 1024
+  // 128 MB
+};
+export {
+  CheckpointGenerator,
+  CompactionScheduler,
+  Compactor,
+  DEFAULT_CHECKPOINT_CONFIG,
+  DEFAULT_COMPACTION_CONFIG,
+  DEFAULT_MAINTENANCE_CONFIG,
+  DEFAULT_SCHEDULER_CONFIG,
+  MaintenanceRunner,
+  readEqualityDeletes,
+  writeEqualityDeletes
+};
+//# sourceMappingURL=compactor.js.map