@powersync/service-module-mongodb-storage 0.19.0 → 0.21.0

package/src/storage/implementation/v3/MongoCompactorV3.ts

@@ -1,236 +1,726 @@
 import { mongo } from '@powersync/lib-service-mongodb';
-import { logger, ReplicationAssertionError, ServiceAssertionError } from '@powersync/lib-services-framework';
-import { addChecksums, InternalOpId, storage, utils } from '@powersync/service-core';
+import { ReplicationAssertionError, ServiceAssertionError } from '@powersync/lib-services-framework';
+import { addChecksums, formatBytes, InternalOpId, storage, utils } from '@powersync/service-core';
 import { BucketDefinitionId } from '@powersync/service-sync-rules';
 import { BucketDataDoc } from '../common/BucketDataDoc.js';
-import { BucketDataKey, BucketStateDocumentBase } from '../models.js';
-import { ConcurrentCompactionError, DirtyBucket, MongoCompactor } from '../MongoCompactor.js';
+import { BucketDataKey } from '../models.js';
+import { ConcurrentCompactionError, MongoCompactor } from '../MongoCompactor.js';
 import { cacheKey } from '../OperationBatch.js';
 import { loadBucketDataDocument, maxOpId, serializeBucketData } from './bucket-format.js';
 import { BucketDataContextV3 } from './BucketDataContextV3.js';
 import { DEFAULT_MAX_DOC_SIZE_BYTES } from './chunking.js';
+import {
+  applyStatsReplacement,
+  bucketStats,
+  BucketStatsWithChecksum,
+  chooseCompactionKind,
+  combineAdjacentStats,
+  combineChunkStats,
+  CompactIntervalConfig,
+  CompactionContext,
+  CompactionDecision,
+  CompactionKind,
+  CompactionResult,
+  CompactTargetConfig,
+  emptyBucketStats,
+  firstUncompactedWrite,
+  forcedCompactionKind,
+  PendingCompactionGroup,
+  readCompactionBatch,
+  ScheduledCompactionOptions,
+  statsForDocument,
+  statsForDocuments,
+  unclaimedSnapshotFilter
+} from './compact-utils.js';
+import { DEFAULT_MIN_COMPACT_CHUNK_INTERVAL_MS } from './compaction-constants.js';
+import { AVAILABLE_LEASE_EXPR, CompactionLease } from './CompactionLease.js';
 import { BucketDataDocumentV3, BucketStateDocumentV3 } from './models.js';
-import { DefinitionChecksumOperations, MongoChecksumsV3 } from './MongoChecksumsV3.js';
 import type { MongoSyncBucketStorageV3 } from './MongoSyncBucketStorageV3.js';
 import { BucketDataObjectStorage, hydrateBucketDataDocuments } from './object-storage/BucketDataObjectStorage.js';
 import { ObjectStorageLifecycle, PreparedObjectStorageUpload } from './object-storage/ObjectStorageLifecycle.js';
+import { createObjectStorageUsageWriterId, ObjectStorageUsage } from './object-storage/ObjectStorageUsage.js';
 import { VersionedPowerSyncMongoV3 } from './VersionedPowerSyncMongoV3.js';
 
-interface PendingCompactionGroup {
-  /**
-   * Input documents are ordered from oldest to newest, matching `ops`.
-   * Keeping the inputs intact lets unchanged singletons retain their object.
-   */
-  inputs: BucketDataDocumentV3[];
-  ops: BucketDataDoc[];
-  changed: boolean;
-  targetOp: InternalOpId | null;
-}
+const DEFAULT_MIN_COMPACT_FULL_INTERVAL_MS = 2 * 60 * 60 * 1000;
+const DEFAULT_MAX_COMPACT_FULL_INTERVAL_MS = 7 * 24 * 60 * 60 * 1000;
+const DEFAULT_COMPACT_LEASE_DURATION_MS = 10 * 60 * 1000;
+const SCHEDULED_COMPACTION_BATCH_SIZE = 100;
 
-/**
- * Read one bounded prefix from a descending compaction cursor.
- *
- * The document that would cross the byte limit is deliberately not returned:
- * pagination resumes below the last returned `_id`, so that document remains
- * eligible for the next query. The first document is always accepted to ensure
- * progress when a single document exceeds the configured byte limit.
- *
- * `hasMore` is conservative when the document limit is reached. An extra empty
- * query is preferable to exhausting the cursor just to determine whether the
- * limited MongoDB query contained another document.
- */
-async function readCompactionBatch(
-  cursor: mongo.AggregationCursor<BucketDataDocumentV3>,
-  options: { byteLimit: number; documentLimit: number }
-): Promise<{ documents: BucketDataDocumentV3[]; hasMore: boolean }> {
-  const documents: BucketDataDocumentV3[] = [];
-  let cumulativeBytes = 0;
-
-  try {
-    for await (const document of cursor) {
-      if (documents.length > 0 && cumulativeBytes + document.size > options.byteLimit) {
-        return { documents, hasMore: true };
-      }
+interface CompactionGroupResult {
+  documentId: BucketDataKey;
+  stats: BucketStatsWithChecksum;
+}
 
-      documents.push(document);
-      cumulativeBytes += document.size;
+interface CompactionStatsReplacement {
+  before: BucketStatsWithChecksum;
+  after: BucketStatsWithChecksum;
+}
 
-      if (documents.length >= options.documentLimit) {
-        return { documents, hasMore: true };
-      }
-    }
-    return { documents, hasMore: false };
-  } finally {
-    await cursor.close();
-  }
+interface ClearCompactionResult extends CompactionStatsReplacement {
+  opCountDiff: number;
 }
 
-export class MongoCompactorV3 extends MongoCompactor {
+export class MongoCompactorV3 extends MongoCompactor implements CompactIntervalConfig, CompactTargetConfig {
   declare protected readonly db: VersionedPowerSyncMongoV3;
   declare protected readonly storage: MongoSyncBucketStorageV3;
 
-  override async compact(): Promise<void> {
+  readonly minCompactChunkIntervalMs: number;
+  readonly minCompactFullIntervalMs: number;
+  readonly maxCompactFullIntervalMs: number;
+  readonly compactLeaseDurationMs: number;
+  readonly maxOpIdCap: InternalOpId | undefined;
+  private readonly objectStorageUsage: ObjectStorageUsage;
+
+  constructor(bucketStorage: MongoSyncBucketStorageV3, db: VersionedPowerSyncMongoV3, options: storage.CompactOptions) {
+    super(bucketStorage, db, options);
+    this.minCompactChunkIntervalMs = options.minCompactChunkIntervalMs ?? DEFAULT_MIN_COMPACT_CHUNK_INTERVAL_MS;
+    this.minCompactFullIntervalMs = options.minCompactFullIntervalMs ?? DEFAULT_MIN_COMPACT_FULL_INTERVAL_MS;
+    this.maxCompactFullIntervalMs = options.maxCompactFullIntervalMs ?? DEFAULT_MAX_COMPACT_FULL_INTERVAL_MS;
+    this.compactLeaseDurationMs = options.compactLeaseDurationMs ?? DEFAULT_COMPACT_LEASE_DURATION_MS;
+    this.maxOpIdCap = options.maxOpId;
+    this.objectStorageUsage = new ObjectStorageUsage(this.db, this.group_id, createObjectStorageUsageWriterId());
+  }
+
+  override async compact(): Promise<number> {
     if (this.storage.objectStorage) {
       // Clean these before compacting - should be quick in most cases.
       try {
-        await this.objectStorageLifecycle.cleanup(this.logger);
+        await this.objectStorageLifecycle.cleanup(this.logger, { signal: this.signal });
       } catch (e) {
+        if (this.signal?.aborted) {
+          throw e;
+        }
         // In this case, still continue normal compact process
         this.logger.error(`Failed to clean up object storage deletion markers before compaction`, e);
       }
     }
-    await super.compact();
+    await this.deleteOldCheckpointRequests();
+
+    if (this.buckets != null) {
+      await this.compactExplicitBuckets(this.buckets);
+    } else if (this.compactChunksOnly) {
+      // Writers defer their first chunk-compaction check by this fixed default.
+      // Include that interval so this synchronous initial-replication pass
+      // processes the work that existed when it started.
+      await this.compactScheduledBuckets({
+        dueAheadMs: DEFAULT_MIN_COMPACT_CHUNK_INTERVAL_MS,
+        forceKind: CompactionKind.Chunks
+      });
+    } else {
+      await this.compactScheduledBuckets();
+    }
     if (this.storage.objectStorage) {
       // Cleanup for any produced during compacting.
       // Note that markers only expire after a delay, so this may skip many produced during this compact
       // run. However, during long compact runs, this may also have many ones it can clean up.
-      await this.objectStorageLifecycle.cleanup(this.logger);
+      await this.objectStorageLifecycle.cleanup(this.logger, { signal: this.signal });
+      await this.objectStorageUsage.foldStaleWriterDeltas();
     }
+    return this.compactedBucketCount;
   }
 
-  private get objectStorageLifecycle(): ObjectStorageLifecycle {
-    if (!this.storage.objectStorage) {
-      throw new Error('Object storage is not configured');
+  protected override async deleteOldCustomCheckpointRequests() {
+    if (this.deleteCheckpointRequestsBefore == null) {
+      return;
+    }
+
+    for (const collection of await this.db.listCustomCheckpointRequestCollections(this.group_id)) {
+      this.signal?.throwIfAborted();
+      await collection.deleteMany({
+        checkpoint_requested_at: { $exists: true, $lt: this.deleteCheckpointRequestsBefore }
+      });
     }
-    return new ObjectStorageLifecycle(this.db, this.group_id, this.storage.objectStorage);
   }
 
-  public async *dirtyBucketBatches(options: {
-    minBucketChanges: number;
-    minChangeRatio: number;
-  }): AsyncGenerator<DirtyBucket[]> {
-    if (options.minBucketChanges <= 0) {
-      throw new ReplicationAssertionError('minBucketChanges must be >= 1');
-    }
-    const collection = this.db.bucketState(this.group_id) as unknown as mongo.Collection<BucketStateDocumentBase>;
-    yield* this.dirtyBucketBatchesForCollection(
-      collection,
-      { d: new mongo.MinKey(), b: new mongo.MinKey() } as unknown as BucketStateDocumentV3['_id'],
-      { d: new mongo.MaxKey(), b: new mongo.MaxKey() } as unknown as BucketStateDocumentV3['_id'],
-      options,
-      (bucketState) => (bucketState as BucketStateDocumentV3)._id.d
-    );
+  /** An explicit compact request always runs a full compact for its buckets. */
+  private async compactExplicitBuckets(buckets: string[]) {
+    for (const bucket of buckets) {
+      // This is not a super efficient query, but this is not a common use case.
+      // May be optimized later.
+      const states = await this.db
+        .bucketState(this.group_id)
+        .find({ '_id.b': bucket }, { projection: { _id: 1 } })
+        .toArray();
+      for (const state of states) {
+        await using lease = await this.claimBucket({ _id: state._id });
+        if (lease == null || lease.state.first_uncompacted_write == null) {
+          continue;
+        }
+        if (this.isCompactionTargetCovered(lease.state, CompactionKind.Full)) {
+          continue;
+        }
+        const decision = chooseCompactionKind(lease.state, lease.startedAt, this);
+        await this.compactClaimedBucket(lease, CompactionKind.Full, decision);
+      }
+    }
   }
 
-  public async dirtyBucketBatchForChecksums(options: { minBucketChanges: number }): Promise<DirtyBucket[]> {
-    if (options.minBucketChanges <= 0) {
-      throw new ReplicationAssertionError('minBucketChanges must be >= 1');
+  /**
+   * Process scheduled work in bounded batches.
+   *
+   * Batching specifically help to cover cases of many buckets where no compaction is required:
+   * Instead of sequentially claiming and then rescheduling a bucket, this handles it in bulk.
+   *
+   * Buckets that do need compaction are still claimed and processed sequentially.
+   *
+   * Any concurrent workers may read the same batch. Rescheduling filters out buckets handled
+   * by a concurrent worker or replication write, while buckets that do need compaction are
+   * filtered out when claiming a compaction lease.
+   *
+   * We filter scheduled jobs by the job start date, so that the same bucket is not compacted
+   * multiple times in one run. Reschedules fall beyond the fixed boundary. For the run after
+   * initial replication, dueAheadMs extends that boundary to include the first deferred interval.
+   */
+  private async compactScheduledBuckets(options: ScheduledCompactionOptions = {}) {
+    // Writers derive next_compact_check from MongoDB's $$NOW. Use the same
+    // clock for the fixed job boundary so clock skew cannot exclude work at
+    // the exact initial-replication interval.
+    const [{ now: jobStartedAt }] = await this.db.db
+      .aggregate<{ now: Date }>([{ $documents: [{}] }, { $project: { _id: 0, now: '$$NOW' } }])
+      .toArray();
+    const dueBefore = new Date(jobStartedAt.getTime() + (options.dueAheadMs ?? 0));
+    const forceKind = options.forceKind;
+    const rescheduleNotBefore = new Date(dueBefore.getTime() + 1);
+    while (true) {
+      this.signal?.throwIfAborted();
+      const states = await this.findScheduledBucketBatch(dueBefore);
+      if (states.length == 0) {
+        break;
+      }
+
+      const scheduled: {
+        state: BucketStateDocumentV3;
+        decision: CompactionDecision;
+        forcedKind: CompactionKind | null;
+      }[] = [];
+      for (const state of states) {
+        try {
+          scheduled.push({
+            state,
+            decision: chooseCompactionKind(state, jobStartedAt, this),
+            forcedKind: forcedCompactionKind(state, forceKind, this)
+          });
+        } catch (error) {
+          await this.rescheduleFailedBucket(state, rescheduleNotBefore, error);
+        }
+      }
+      const noOpStates = scheduled.filter(
+        ({ state, decision, forcedKind }) =>
+          state.compact_lease == null && (forceKind == null ? decision.kind : forcedKind) == null
+      );
+      await this.rescheduleUnclaimedBuckets(noOpStates, rescheduleNotBefore);
+
+      for (const { state, decision, forcedKind } of scheduled) {
+        const kind = forceKind == null ? decision.kind : forcedKind;
+        if (state.compact_lease == null && kind == null) {
+          continue;
+        }
+
+        try {
+          await using lease = await this.claimBucket({ _id: state._id, next_compact_check: { $lte: dueBefore } });
+          if (lease == null) {
+            continue;
+          }
+          const claimedDecision = chooseCompactionKind(lease.state, lease.startedAt, this);
+          const claimedKind =
+            forceKind == null ? claimedDecision.kind : forcedCompactionKind(lease.state, forceKind, this);
+          if (claimedKind == null) {
+            await this.rescheduleClaimedBucket(lease, claimedDecision, rescheduleNotBefore);
+          } else if (this.isCompactionTargetCovered(lease.state, claimedKind)) {
+            // The run cannot advance this kind's watermark without regressing
+            // already-published progress. Keep any newer work scheduled.
+            await this.rescheduleClaimedBucket(lease, claimedDecision, rescheduleNotBefore);
+          } else {
+            await this.compactClaimedBucket(lease, claimedKind, claimedDecision, rescheduleNotBefore);
+          }
+        } catch (error) {
+          if (this.signal?.aborted) {
+            // When aborted, stop completely, rather than logging and re-scheduling individual buckets.
+            // The lease on the current bucket is still released automatically.
+            throw error;
+          }
+          await this.rescheduleFailedBucket(state, rescheduleNotBefore, error);
+        }
+      }
     }
-    return this.dirtyBucketBatchForChecksumsForCollection(
-      this.db.bucketState(this.group_id) as unknown as mongo.Collection<BucketStateDocumentBase>,
-      {
-        'estimate_since_compact.count': { $gte: options.minBucketChanges }
-      } as unknown as mongo.Filter<BucketStateDocumentBase>,
-      (bucketState) => (bucketState as BucketStateDocumentV3)._id.d
-    );
   }
 
-  protected async writeBucketStateUpdates(): Promise<void> {
-    await this.db
+  /** Read a bounded, priority-ordered snapshot of currently claimable scheduled work. */
+  private async findScheduledBucketBatch(dueBefore: Date): Promise<BucketStateDocumentV3[]> {
+    return this.db
       .bucketState(this.group_id)
-      .bulkWrite(this.bucketStateUpdates as mongo.AnyBulkWriteOperation<BucketStateDocumentV3>[], {
-        ordered: false
-      });
+      .find({
+        next_compact_check: { $lte: dueBefore },
+        ...AVAILABLE_LEASE_EXPR
+      })
+      .sort({ next_compact_check: 1 })
+      .limit(SCHEDULED_COMPACTION_BATCH_SIZE)
+      .toArray();
   }
 
   /**
-   * The compactor operates on persisted definition ids only - never on parsed sources.
-   * This narrowed view makes the source-resolving checksum methods unreachable here.
+   * Reschedule snapshots that were already known to be no-ops without first
+   * taking a lease. Every decision input is compared so a concurrent writer
+   * or compactor simply makes the update a no-op instead of losing work. A
+   * successful reschedule moves beyond this run's fixed selection boundary.
    */
-  private get definitionChecksums(): DefinitionChecksumOperations {
-    return this.storage.checksums as MongoChecksumsV3;
+  private async rescheduleUnclaimedBuckets(
+    states: { state: BucketStateDocumentV3; decision: CompactionDecision }[],
+    notBefore: Date
+  ) {
+    if (states.length == 0) {
+      return;
+    }
+    await this.db.bucketState(this.group_id).bulkWrite(
+      states.map(({ state, decision }) => ({
+        updateOne: {
+          filter: unclaimedSnapshotFilter(state),
+          update: [{ $set: { next_compact_check: this.rescheduleAtOrAfter(decision.nextCompactCheck, notBefore) } }]
+        }
+      })),
+      { ordered: false }
+    );
   }
 
-  protected async computeChecksumsForBuckets(
-    buckets: Pick<DirtyBucket, 'bucket' | 'definitionId'>[]
-  ): Promise<storage.PartialChecksumMap> {
-    return this.definitionChecksums.computePartialChecksumsDirectByDefinition(
-      buckets.map(({ bucket, definitionId }) => {
-        if (definitionId == null) {
-          throw new ServiceAssertionError(`Missing definitionId for bucket checksum update on bucket ${bucket}`);
-        }
-        return {
-          bucket,
-          definitionId,
-          end: this.maxOpId
-        };
-      })
+  /**
+   * Isolate a malformed bucket so it cannot prevent other scheduled buckets
+   * from compacting. The snapshot filter preserves any concurrent write or
+   * compactor result instead of overwriting its next check.
+   */
+  private async rescheduleFailedBucket(state: BucketStateDocumentV3, notBefore: Date, error: unknown) {
+    this.logger.error(`Failed to compact scheduled bucket ${state._id.b}; rescheduling it`, error);
+    try {
+      await this.db
+        .bucketState(this.group_id)
+        .updateOne(unclaimedSnapshotFilter(state), [{ $set: { next_compact_check: notBefore } }]);
+    } catch (rescheduleError) {
+      this.logger.error(`Failed to reschedule bucket ${state._id.b} after a compaction error`, rescheduleError);
+    }
+  }
+
+  /**
+   * Given a bucket filter, claim a lease on the bucket. The filter should include a filter on _id.
+   *
+   * Resolves to null if the bucket is already claimed, not found, or filtered out.
+   */
+  private async claimBucket(
+    filter: mongo.Filter<BucketStateDocumentV3>,
+    sort?: mongo.Sort
+  ): Promise<CompactionLease | null> {
+    return CompactionLease.claim(this.db.bucketState(this.group_id), filter, sort, this.compactLeaseDurationMs);
+  }
+
+  private async compactClaimedBucket(
+    lease: CompactionLease,
+    kind: CompactionKind,
+    decision: CompactionDecision,
+    rescheduleNotBefore?: Date
+  ) {
+    const context = new CompactionContext(
+      lease,
+      kind,
+      decision,
+      rescheduleNotBefore,
+      this.compactionTarget(lease.state)
     );
+    lease.startRenewal();
+    await this.compactSingleBucket(context);
   }
 
-  protected bucketStateFilter(
-    bucket: string,
-    definitionId: BucketDefinitionId | null
-  ): mongo.Filter<BucketStateDocumentBase> {
-    if (definitionId == null) {
-      throw new ServiceAssertionError(`Missing definitionId for V3 bucket state filter on bucket ${bucket}`);
+  private async rescheduleClaimedBucket(lease: CompactionLease, decision: CompactionDecision, notBefore?: Date) {
+    await lease.reschedule(this.rescheduleAtOrAfter(decision.nextCompactCheck, notBefore));
+  }
+
+  private rescheduleAtOrAfter(nextCompactCheck: mongo.Document, notBefore: Date | undefined): mongo.Document {
+    return notBefore == null ? nextCompactCheck : { $max: [nextCompactCheck, notBefore] };
+  }
+
+  private compactionTarget(state: BucketStateDocumentV3): InternalOpId {
+    return this.maxOpIdCap == null || state.last_op < this.maxOpIdCap ? state.last_op : this.maxOpIdCap;
+  }
+
+  private isCompactionTargetCovered(state: BucketStateDocumentV3, kind: CompactionKind): boolean {
+    const target = this.compactionTarget(state);
+    if (kind == CompactionKind.Chunks) {
+      return state.compacted_state != null && state.compacted_state.op_id >= target;
     }
-    return {
-      _id: {
-        d: definitionId,
-        b: bucket
+    if (state.last_full_compact != null && state.last_full_compact.op_id >= target) {
+      return true;
+    }
+    // A full compact may change counts before the checksum-cache boundary.
+    // Wait for the safe target to catch up instead of publishing an older or
+    // stale cache. At the same boundary, full coverage can still advance.
+    return state.compacted_state != null && state.compacted_state.op_id > target;
+  }
+
+  private get objectStorageLifecycle(): ObjectStorageLifecycle {
+    if (!this.storage.objectStorage) {
+      throw new Error('Object storage is not configured');
+    }
+    return new ObjectStorageLifecycle(this.db, this.group_id, this.storage.objectStorage);
+  }
+
+  private async compactSingleBucket(context: CompactionContext) {
+    if (context.kind == CompactionKind.Chunks) {
+      return this.compactSingleBucketChunks(context);
+    }
+
+    return this.compactSingleBucketFully(context);
+  }
+
+  /**
+   * Merge adjacent bucket-data chunks without inspecting their operations
+   * unless a merge is possible. The metadata contains enough information to
+   * update the persisted checksum state and to decide whether a group can fit
+   * in one chunk.
+   */
+  private async compactSingleBucketChunks(context: CompactionContext) {
+    const bucket = context.state._id.b;
+    const resolvedDefinitionId = context.state._id.d;
+    const bucketContext = new BucketDataContextV3(this.db, {
+      bucket,
+      definitionId: resolvedDefinitionId,
+      replicationStreamId: this.group_id
+    });
+    const collection = this.db.bucketData(this.group_id, resolvedDefinitionId);
+    const dataContext = { replicationStreamId: this.group_id, definitionId: resolvedDefinitionId };
+    let previousCompactedState = context.state.compacted_state;
+    // A zero boundary represents an empty prefix, so there is no stored chunk
+    // whose statistics need to be carried into this pass.
+    if (previousCompactedState?.op_id === 0n) {
+      previousCompactedState = undefined;
+    }
+    // Include the last previously compacted chunk as well as new chunks. It
+    // is the only old chunk which can become mergeable with the new tail.
+    let lowerBound =
+      previousCompactedState != null ? bucketContext.docId(previousCompactedState.op_id - 1n) : bucketContext.minId;
+    const upperBound = bucketContext.docId(context.targetOp + 1n);
+    let cachedBoundaryToVerify = previousCompactedState?.op_id;
+
+    let compactedOpId: bigint | null = null;
+    let overlappingCompactedChunk: BucketStatsWithChecksum | undefined;
+    let compactedTail = emptyBucketStats();
+    let pendingChunks: BucketDataDocumentV3[] = [];
+    let pendingSize = 0;
+
+    while (true) {
+      this.signal?.throwIfAborted();
+      await context.lease.throwIfLost();
+
+      const batch = await readCompactionBatch(
+        collection.aggregate<BucketDataDocumentV3>(
+          [
+            {
+              $match: {
+                _id: {
+                  $gt: lowerBound,
+                  $lt: upperBound
+                }
+              }
+            },
+            { $sort: { _id: 1 } },
+            { $limit: this.moveBatchQueryLimit },
+            {
+              $project: {
+                _id: 1,
+                min_op: 1,
+                checksum: 1,
+                count: 1,
+                size: 1,
+                target_op: 1,
+                storage_ref: 1
+              }
+            }
+          ],
+          { batchSize: this.moveBatchQueryLimit + 1 }
+        ),
+        {
+          byteLimit: this.moveBatchByteLimit,
+          documentLimit: this.moveBatchQueryLimit
+        }
+      );
+
+      if (cachedBoundaryToVerify != null) {
+        const cachedBoundary = cachedBoundaryToVerify;
+        cachedBoundaryToVerify = undefined;
+        if (batch.documents[0]?._id.o !== cachedBoundary) {
+          // A previous attempt may have replaced the cached boundary before
+          // finalizing bucket state. Keep the persisted cache available to
+          // readers, but ignore it in this attempt and calculate its
+          // replacement through the normal scan from the bucket beginning.
+          previousCompactedState = undefined;
+          lowerBound = bucketContext.minId;
+          continue;
+        }
       }
+
+      if (batch.documents.length == 0) {
+        break;
+      }
+
+      for (const doc of batch.documents) {
+        compactedOpId = maxOpId(compactedOpId, doc._id.o);
+        const documentStats = statsForDocument(doc);
+        if (previousCompactedState?.op_id === doc._id.o) {
+          overlappingCompactedChunk = documentStats;
+        }
+
+        const nextSize = pendingSize + doc.size;
+        if (pendingChunks.length > 0 && nextSize > DEFAULT_MAX_DOC_SIZE_BYTES) {
+          const groupStats = await this.flushChunkMerge(bucket, pendingChunks, collection, dataContext, bucketContext);
+          compactedTail = combineAdjacentStats(compactedTail, groupStats);
+          pendingChunks = [];
+          pendingSize = 0;
+        }
+
+        pendingChunks.push(doc);
+        pendingSize += doc.size;
+      }
+
+      lowerBound = batch.documents[batch.documents.length - 1]._id;
+      if (!batch.hasMore) {
+        break;
+      }
+    }
+
+    if (pendingChunks.length > 0) {
+      const groupStats = await this.flushChunkMerge(bucket, pendingChunks, collection, dataContext, bucketContext);
+      compactedTail = combineAdjacentStats(compactedTail, groupStats);
+    }
+
+    if (compactedOpId == null) {
+      await this.finalizeSkippedBucket(context);
+      return;
+    }
+
+    const compactedState =
+      previousCompactedState == null
+        ? compactedTail
+        : combineChunkStats(previousCompactedState, compactedTail, overlappingCompactedChunk!);
+    const tailStats =
+      compactedOpId == context.lastOp
+        ? undefined
+        : await this.readBucketStats(bucket, resolvedDefinitionId, context.lastOp, bucketContext.docId(compactedOpId));
+    const result: CompactionResult = {
+      compactedState,
+      bucketStats: tailStats == null ? compactedState : combineAdjacentStats(compactedState, tailStats)
     };
+
+    await this.finalizeCompactedBucket({ context, compactedOpId, compactionResult: result, puts: 0 });
+    this.compactedBucketCount++;
+    this.logger.info(
+      `Compacted bucket chunks ${bucket}: ${result.bucketStats.count} ops, ${result.bucketStats.chunks} chunks, ${formatBytes(result.bucketStats.bytes)}`
+    );
   }
 
-  private async getBucketDataContext(
+  private async flushChunkMerge(
     bucket: string,
-    definitionId: BucketDefinitionId | null
-  ): Promise<BucketDataContextV3 | null> {
-    let resolvedDefinitionId = definitionId;
-
-    if (resolvedDefinitionId == null) {
-      const allDefinitionIds = this.storage.storageIds.bucketDefinitionIds;
-      if (allDefinitionIds.length > 0) {
-        const potentialIds = allDefinitionIds.map((id) => ({ d: id, b: bucket }));
-        const bucketState = await this.db.bucketState(this.group_id).findOne({
-          _id: { $in: potentialIds }
-        });
-        if (bucketState != null) {
-          resolvedDefinitionId = bucketState._id.d;
-        }
+    inputs: BucketDataDocumentV3[],
+    collection: mongo.Collection<BucketDataDocumentV3>,
+    context: { replicationStreamId: number; definitionId: string },
+    bucketContext: BucketDataContextV3
+  ): Promise<BucketStatsWithChecksum> {
+    if (inputs.length == 1) {
+      return statsForDocument(inputs[0]);
+    }
+
+    // The metadata scan deliberately excluded ops. Read inline payloads only
+    // for this merge group; object-storage payloads are fetched below using
+    // the same rule.
+    const inlineInputs = inputs.filter((input) => input.storage_ref == null);
+    if (inlineInputs.length > 0) {
+      const inlineDocuments = await collection
+        .find({ _id: { $in: inlineInputs.map((input) => input._id) } }, { projection: { _id: 1, ops: 1 } })
+        .toArray();
+      const opsById = new Map(inlineDocuments.map((document) => [document._id.o.toString(), document.ops]));
+      for (const input of inlineInputs) {
+        input.ops = opsById.get(input._id.o.toString());
       }
     }
+    await hydrateBucketDataDocuments(inputs, this.storage.objectStorage, { signal: this.signal });
 
-    if (resolvedDefinitionId == null) {
-      return null;
+    const operations = inputs.flatMap((input) => Array.from(loadBucketDataDocument(context, input)));
+    const targetOp = inputs.reduce<InternalOpId | null>(
+      (maxTarget, input) => maxOpId(maxTarget, input.target_op),
+      null
+    );
+    const result = await this.flushCompactionGroup(
+      bucket,
+      {
+        inputs,
+        ops: operations,
+        changed: true,
+        targetOp
+      },
+      bucketContext,
+      context
+    );
+    return result.stats;
+  }
+
+  private async finalizeCompactedBucket({
+    context,
+    compactedOpId,
+    compactionResult,
+    puts
+  }: {
+    context: CompactionContext;
+    compactedOpId: InternalOpId;
+    compactionResult: CompactionResult;
+    puts: number;
+  }) {
+    await context.lease.throwIfLost();
+    const startedStats = bucketStats(context.state);
+    const delta = {
+      count: compactionResult.bucketStats.count - startedStats.count,
+      bytes: compactionResult.bucketStats.bytes - startedStats.bytes,
+      chunks: compactionResult.bucketStats.chunks - startedStats.chunks
+    };
+    const coveredClaimedHead = compactedOpId >= context.lastOp;
+    const concurrentWriteCheck = { $gt: ['$last_op', context.lastOp] };
+    const remainingFullWorkCheck = coveredClaimedHead ? concurrentWriteCheck : true;
+    const nextAfterPartialFullCompact = this.rescheduleAtOrAfter(
+      { $dateAdd: { startDate: '$$NOW', unit: 'millisecond', amount: this.minCompactChunkIntervalMs } },
+      context.rescheduleNotBefore
+    );
+    const nextCheckForUncompactedWork = this.rescheduleAtOrAfter(
+      {
+        $min: [
+          new Date(firstUncompactedWrite(context.state).getTime() + this.maxCompactFullIntervalMs),
+          { $dateAdd: { startDate: '$$NOW', unit: 'millisecond', amount: this.minCompactChunkIntervalMs } }
+        ]
+      },
+      context.rescheduleNotBefore
+    );
+    const update: mongo.Document = {
+      compacted_state: {
+        op_id: compactedOpId,
+        checksum: BigInt(compactionResult.compactedState.checksum),
+        count: compactionResult.compactedState.count,
+        bytes: compactionResult.compactedState.bytes,
+        chunks: compactionResult.compactedState.chunks,
+        at: '$$NOW'
+      },
+      bucket_stats: {
+        count: { $add: ['$bucket_stats.count', delta.count] },
+        bytes: { $add: ['$bucket_stats.bytes', delta.bytes] },
+        chunks: { $add: ['$bucket_stats.chunks', delta.chunks] }
+      },
+      first_uncompacted_write:
+        context.kind == CompactionKind.Full
+          ? { $cond: [remainingFullWorkCheck, '$$NOW', '$$REMOVE'] }
+          : '$first_uncompacted_write',
+      next_compact_check:
+        context.kind == CompactionKind.Full
+          ? { $cond: [remainingFullWorkCheck, nextAfterPartialFullCompact, '$$REMOVE'] }
+          : nextCheckForUncompactedWork
+    };
+    if (context.kind == CompactionKind.Full) {
+      update.last_full_compact = {
+        op_id: compactedOpId,
+        count: compactionResult.compactedState.count,
+        puts,
+        at: '$$NOW'
+      };
     }
 
-    return new BucketDataContextV3(this.db, {
+    await context.lease.finalize(update);
+  }
+
+  private async finalizeSkippedBucket(context: CompactionContext) {
+    // A maxOpId cap can exclude the first remaining document entirely. Avoid
+    // immediately claiming the same no-progress bucket again in this run.
+    await this.rescheduleClaimedBucket(
+      context.lease,
+      {
+        ...context.decision,
+        nextCompactCheck: {
+          $max: [
+            context.decision.nextCompactCheck,
+            { $dateAdd: { startDate: '$$NOW', unit: 'millisecond', amount: this.minCompactChunkIntervalMs } }
+          ]
+        }
+      },
+      context.rescheduleNotBefore
+    );
+  }
+
+  /**
+   * Read bucket stats directly from bucket_data documents.
+   */
+  private async readBucketStats(
+    bucket: string,
+    definitionId: BucketDefinitionId,
+    maxOp: InternalOpId,
+    lowerBound?: BucketDataKey
+  ): Promise<BucketStatsWithChecksum> {
+    const context = new BucketDataContextV3(this.db, {
       bucket,
-      definitionId: resolvedDefinitionId,
+      definitionId,
       replicationStreamId: this.group_id
     });
+    const [stats] = await this.db
+      .bucketData(this.group_id, definitionId)
+      .aggregate<{ count: number; bytes: number | bigint; chunks: number; checksum: bigint }>([
+        {
+          $match: {
+            _id:
+              lowerBound == null
+                ? { $gte: context.minId, $lte: context.docId(maxOp) }
+                : { $gt: lowerBound, $lte: context.docId(maxOp) }
+          }
+        },
+        {
+          $group: {
+            _id: null,
+            count: { $sum: '$count' },
+            bytes: { $sum: '$size' },
+            chunks: { $sum: 1 },
+            checksum: { $sum: '$checksum' }
+          }
+        }
+      ])
+      .toArray();
+    return {
+      count: Number(stats?.count ?? 0),
+      bytes: BigInt(stats?.bytes ?? 0),
+      chunks: Number(stats?.chunks ?? 0),
+      checksum:
+        typeof stats?.checksum == 'bigint'
+          ? Number(BigInt.asIntN(32, stats.checksum))
+          : addChecksums(0, Number(stats?.checksum ?? 0))
+    };
   }
 
-  protected override async compactSingleBucket(bucket: string, definitionId: BucketDefinitionId | null = null) {
-    const bucketContext = await this.getBucketDataContext(bucket, definitionId);
-    if (bucketContext == null) {
-      return;
-    }
-
-    const resolvedDefinitionId = bucketContext.key.definitionId;
+  private async compactSingleBucketFully(context: CompactionContext) {
+    const bucket = context.state._id.b;
+    const resolvedDefinitionId = context.state._id.d;
+    const bucketContext = new BucketDataContextV3(this.db, {
+      bucket,
+      definitionId: resolvedDefinitionId,
+      replicationStreamId: this.group_id
+    });
     const collection = this.db.bucketData(this.group_id, resolvedDefinitionId);
-    const context = { replicationStreamId: this.group_id, definitionId: resolvedDefinitionId };
-
+    const dataContext = { replicationStreamId: this.group_id, definitionId: resolvedDefinitionId };
     const lowerBound = bucketContext.minId;
-    let upperBound = bucketContext.docId(this.maxOpId + 1n);
+    let upperBound = bucketContext.docId(context.targetOp + 1n);
 
-    let totalChecksum = 0;
     let totalOpCount = 0;
-    let totalOpBytes = 0;
 
     let lastNotPut: bigint | null = null;
     let opsSincePut = 0;
     let compactedOpId: bigint | null = null;
     let clearBoundary: { opId: bigint; documentId: BucketDataKey } | null = null;
+    let compactedStats = emptyBucketStats();
     const seen = new Map<string, bigint>();
     let trackingSize = 0;
+    let putCount = 0;
     let pendingGroup: PendingCompactionGroup | null = null;
 
     // --- Read batch from MongoDB ---
     while (true) {
       this.signal?.throwIfAborted();
+      await context.lease.throwIfLost();
 
       const pipeline: mongo.Document[] = [
         {
@@ -280,7 +770,7 @@ export class MongoCompactorV3 extends MongoCompactor {
       // merging is useful, and writes each final object at most once.
       for (const doc of batchDocs) {
         compactedOpId ??= doc._id.o;
-        const originalOps = Array.from(loadBucketDataDocument(context, doc));
+        const originalOps = Array.from(loadBucketDataDocument(dataContext, doc));
 
         let changed = false;
         const compactedOps: BucketDataDoc[] = [];
@@ -299,6 +789,7 @@ export class MongoCompactorV3 extends MongoCompactor {
                 row_id: undefined,
                 source_table: undefined,
                 source_key: undefined,
+                subkey: undefined,
                 data: null
               });
               changed = true;
@@ -313,6 +804,7 @@ export class MongoCompactorV3 extends MongoCompactor {
               }
               compactedOps.push(op);
               if (op.op == 'PUT') {
+                putCount++;
                 lastNotPut = null;
                 opsSincePut = 0;
               } else {
@@ -334,10 +826,6 @@ export class MongoCompactorV3 extends MongoCompactor {
         }
         compactedOps.reverse();
 
-        for (const op of compactedOps) {
-          totalChecksum = addChecksums(totalChecksum, Number(op.checksum));
-          totalOpBytes += op.data?.length ?? 0;
-        }
         totalOpCount += compactedOps.length;
 
         const candidate: PendingCompactionGroup = {
@@ -361,13 +849,14 @@ export class MongoCompactorV3 extends MongoCompactor {
             };
           } else {
             const flushedGroup = pendingGroup;
-            const documentId = await this.flushCompactionGroup(bucket, flushedGroup, bucketContext, context);
+            const result = await this.flushCompactionGroup(bucket, flushedGroup, bucketContext, dataContext);
+            compactedStats = combineAdjacentStats(compactedStats, result.stats);
             if (
               lastNotPut != null &&
               flushedGroup.ops[0].o <= lastNotPut &&
               flushedGroup.ops[flushedGroup.ops.length - 1].o >= lastNotPut
             ) {
-              clearBoundary = { opId: lastNotPut, documentId };
+              clearBoundary = { opId: lastNotPut, documentId: result.documentId };
             }
             pendingGroup = candidate;
           }
@@ -385,16 +874,18 @@ export class MongoCompactorV3 extends MongoCompactor {
     }
 
     if (pendingGroup != null) {
-      const documentId = await this.flushCompactionGroup(bucket, pendingGroup, bucketContext, context);
+      const result = await this.flushCompactionGroup(bucket, pendingGroup, bucketContext, dataContext);
+      compactedStats = combineAdjacentStats(compactedStats, result.stats);
       if (
         lastNotPut != null &&
         pendingGroup.ops[0].o <= lastNotPut &&
         pendingGroup.ops[pendingGroup.ops.length - 1].o >= lastNotPut
       ) {
-        clearBoundary = { opId: lastNotPut, documentId };
+        clearBoundary = { opId: lastNotPut, documentId: result.documentId };
       }
     }
     if (compactedOpId == null) {
+      await this.finalizeSkippedBucket(context);
       return;
     }
 
@@ -404,36 +895,33 @@ export class MongoCompactorV3 extends MongoCompactor {
         throw new ReplicationAssertionError(`Missing CLEAR boundary document for bucket ${bucket}`);
       }
 
-      totalOpCount += await this.clearBucketLeading(
+      const clearResult = await this.clearBucketLeading(
         lastNotPut,
         clearBoundary.documentId,
         bucketContext,
         collection,
-        context
+        dataContext
       );
+      totalOpCount += clearResult.opCountDiff;
+      compactedStats = applyStatsReplacement(compactedStats, clearResult.before, clearResult.after);
     }
 
+    const tailStats =
+      compactedOpId == context.lastOp
+        ? undefined
+        : await this.readBucketStats(bucket, resolvedDefinitionId, context.lastOp, bucketContext.docId(compactedOpId));
+    const result: CompactionResult = {
+      compactedState: compactedStats,
+      bucketStats: tailStats == null ? compactedStats : combineAdjacentStats(compactedStats, tailStats)
+    };
+
     // --- Finalize: update bucket checksums and state ---
-    this.updateBucketChecksums(
-      {
-        bucket,
-        definitionId: resolvedDefinitionId,
-        seen: new Map(),
-        trackingSize: 0,
-        lastNotPut: lastNotPut,
-        opsSincePut: opsSincePut,
-        checksum: totalChecksum,
-        opCount: totalOpCount,
-        opBytes: totalOpBytes
-      },
-      compactedOpId
-    );
-    if (this.bucketStateUpdates.length > 0) {
-      await this.writeBucketStateUpdates();
-      this.bucketStateUpdates = [];
-    }
+    await this.finalizeCompactedBucket({ context, compactedOpId, compactionResult: result, puts: putCount });
 
-    logger.info(`Compacted bucket ${bucket}: ${totalOpCount} surviving ops`);
+    this.compactedBucketCount++;
+    this.logger.info(
+      `Compacted bucket ${bucket}: ${totalOpCount} ops, ${result.bucketStats.chunks} chunks, ${formatBytes(result.bucketStats.bytes)}`
+    );
   }
 
   /**
@@ -447,9 +935,12 @@ export class MongoCompactorV3 extends MongoCompactor {
     group: PendingCompactionGroup,
     bucketContext: BucketDataContextV3,
     context: { replicationStreamId: number; definitionId: string }
-  ): Promise<BucketDataKey> {
+  ): Promise<CompactionGroupResult> {
     if (group.inputs.length == 1 && !group.changed) {
-      return group.inputs[0]._id;
+      return {
+        documentId: group.inputs[0]._id,
+        stats: statsForDocument(group.inputs[0])
+      };
     }
 
     const inputs = group.inputs;
@@ -458,6 +949,7 @@ export class MongoCompactorV3 extends MongoCompactor {
     const expectedChecksum = inputs.reduce((sum, doc) => sum + doc.checksum, 0n);
     const expectedOpCount = inputs.reduce((sum, doc) => sum + doc.count, 0);
     const oldStoragePaths = inputs.flatMap((doc) => (doc.storage_ref ? [doc.storage_ref.path] : []));
+    const oldStorageBytes = inputs.reduce((sum, document) => sum + ObjectStorageUsage.bytes(document), 0n);
     const {
       documents,
       storagePaths: newStoragePaths,
@@ -498,6 +990,7 @@ export class MongoCompactorV3 extends MongoCompactor {
           await bucketContext.collection.deleteMany({ _id: { $in: idsToDelete } }, { session });
           await bucketContext.collection.insertMany(documents, { session });
           await this.finishObjectStorageReplacement(oldStoragePaths, newStoragePaths, uploads, session);
+          await this.recordObjectStorageReplacement(oldStorageBytes, documents, context.definitionId, session);
         },
         {
           writeConcern: { w: 'majority' },
@@ -507,7 +1000,10 @@ export class MongoCompactorV3 extends MongoCompactor {
     } finally {
       await session.endSession();
     }
-    return documents[0]._id;
+    return {
+      documentId: documents[0]._id,
+      stats: statsForDocuments(documents)
+    };
   }
 
   /**
@@ -516,7 +1012,8 @@ export class MongoCompactorV3 extends MongoCompactor {
    * before the known boundary document, then splits that boundary document
    * if it contains ops on both sides of lastNotPut.
    *
-   * Returns the op count diff after replacing cleared ops with CLEAR ops.
+   * Returns the op count and stored-stat changes after replacing cleared ops
+   * with CLEAR ops.
    */
   private async clearBucketLeading(
     lastNotPut: bigint,
@@ -524,8 +1021,10 @@ export class MongoCompactorV3 extends MongoCompactor {
     bucketContext: BucketDataContextV3,
     collection: mongo.Collection<BucketDataDocumentV3 & { bsonSize?: number | bigint }>,
     context: { replicationStreamId: number; definitionId: string }
-  ): Promise<number> {
+  ): Promise<ClearCompactionResult> {
     let opCountDiff = 0;
+    let before = emptyBucketStats();
+    let after = emptyBucketStats();
     const session = this.db.client.startSession();
     try {
       let done = false;
@@ -542,11 +1041,13 @@ export class MongoCompactorV3 extends MongoCompactor {
         );
         done = batch.done;
         opCountDiff += batch.opCountDiff;
+        before = combineAdjacentStats(before, batch.before);
+        after = combineAdjacentStats(after, batch.after);
       }
 
       // The final step is to process the "boundary" document: It may contain some CLEAR/MOVE/REMOVE operations,
       // potentially followed by PUT operations. This is only a single document, so no need for batching.
-      opCountDiff += await this.clearBoundaryDocument(
+      const boundaryResult = await this.clearBoundaryDocument(
         session,
         lastNotPut,
         boundaryDocId,
@@ -554,11 +1055,14 @@ export class MongoCompactorV3 extends MongoCompactor {
         collection,
         context
       );
+      opCountDiff += boundaryResult.opCountDiff;
+      before = combineAdjacentStats(before, boundaryResult.before);
+      after = combineAdjacentStats(after, boundaryResult.after);
     } finally {
       await session.endSession();
     }
 
-    return opCountDiff;
+    return { opCountDiff, before, after };
   }
 
   private async clearLeadingFullDocuments(
@@ -568,18 +1072,23 @@ export class MongoCompactorV3 extends MongoCompactor {
     bucketContext: BucketDataContextV3,
     collection: mongo.Collection<BucketDataDocumentV3 & { bsonSize?: number | bigint }>,
     context: { replicationStreamId: number; definitionId: string }
-  ): Promise<{ done: boolean; opCountDiff: number }> {
+  ): Promise<{ done: boolean; opCountDiff: number } & CompactionStatsReplacement> {
     const bucket = bucketContext.key.bucket;
     this.signal?.throwIfAborted();
-    const prepared = await this.prepareCompactionUploads(bucket, context, [lastNotPut]);
+    let prepared: PreparedObjectStorageUpload[] | undefined;
     let done = false;
     let opCountDiff = 0;
+    let before = emptyBucketStats();
+    let after = emptyBucketStats();
 
     await session.withTransaction(
       async () => {
         done = false;
         opCountDiff = 0;
+        before = emptyBucketStats();
+        after = emptyBucketStats();
         const oldStoragePaths: string[] = [];
+        let oldStorageBytes = 0n;
         const query = collection.find(
           {
             _id: {
@@ -595,6 +1104,7 @@ export class MongoCompactorV3 extends MongoCompactor {
               min_op: 1,
               checksum: 1,
               count: 1,
+              size: 1,
               target_op: 1,
               has_clear_op: 1,
               storage_ref: 1
@@ -609,6 +1119,7 @@ export class MongoCompactorV3 extends MongoCompactor {
         let lastDocId: BucketDataKey | null = null;
         let clearOpCount = 0;
         let gotNonClearOp = false;
+        const inputStats = emptyBucketStats();
 
         for await (const doc of query.stream()) {
           if (doc.min_op > lastNotPut) {
@@ -618,9 +1129,15 @@ export class MongoCompactorV3 extends MongoCompactor {
           }
 
           lastDocId = doc._id;
+          const documentStats = statsForDocument(doc);
+          inputStats.count += documentStats.count;
+          inputStats.bytes += documentStats.bytes;
+          inputStats.chunks += documentStats.chunks;
+          inputStats.checksum = addChecksums(inputStats.checksum, documentStats.checksum);
           if (doc.storage_ref) {
             oldStoragePaths.push(doc.storage_ref.path);
           }
+          oldStorageBytes += ObjectStorageUsage.bytes(doc);
 
           // The compaction scan established that every operation before the
           // boundary is MOVE/REMOVE/CLEAR. Root metadata is sufficient to fold
@@ -646,6 +1163,7 @@ export class MongoCompactorV3 extends MongoCompactor {
           return;
         }
 
+        prepared ??= await this.prepareCompactionUploads(bucket, context, [lastNotPut]);
         this.logger.info(`Flushing CLEAR for ${clearedOpCount} ops at ${lastDocId?.o}`);
         await collection.deleteMany(
           {
@@ -669,8 +1187,11 @@ export class MongoCompactorV3 extends MongoCompactor {
         });
         await collection.insertOne(persisted.documents[0], { session });
         await this.finishObjectStorageReplacement(oldStoragePaths, persisted.storagePaths, persisted.uploads, session);
+        await this.recordObjectStorageReplacement(oldStorageBytes, persisted.documents, context.definitionId, session);
 
         opCountDiff = -clearedOpCount + 1;
+        before = inputStats;
+        after = statsForDocuments(persisted.documents);
       },
       {
         writeConcern: { w: 'majority' },
@@ -678,7 +1199,7 @@ export class MongoCompactorV3 extends MongoCompactor {
       }
     );
 
-    return { done, opCountDiff };
+    return { done, opCountDiff, before, after };
   }
 
   private async clearBoundaryDocument(
@@ -688,16 +1209,21 @@ export class MongoCompactorV3 extends MongoCompactor {
     bucketContext: BucketDataContextV3,
     collection: mongo.Collection<BucketDataDocumentV3 & { bsonSize?: number | bigint }>,
     context: { replicationStreamId: number; definitionId: string }
-  ): Promise<number> {
+  ): Promise<ClearCompactionResult> {
     const bucket = bucketContext.key.bucket;
     this.signal?.throwIfAborted();
     const prepared = await this.prepareCompactionUploads(bucket, context, [lastNotPut, boundaryDocId.o]);
     let opCountDiff = 0;
+    let before = emptyBucketStats();
+    let after = emptyBucketStats();
 
     await session.withTransaction(
       async () => {
         opCountDiff = 0;
+        before = emptyBucketStats();
+        after = emptyBucketStats();
         const oldStoragePaths: string[] = [];
+        let oldStorageBytes = 0n;
         const query = collection.find(
           {
             // This is a range query, but should only ever return two documents:
@@ -716,6 +1242,7 @@ export class MongoCompactorV3 extends MongoCompactor {
               min_op: 1,
               checksum: 1,
               count: 1,
+              size: 1,
               target_op: 1,
               ops: 1,
               storage_ref: 1
@@ -729,6 +1256,7 @@ export class MongoCompactorV3 extends MongoCompactor {
         let clearedOpCount = 0;
         let maxTargetOp: bigint | null = null;
         const boundarySurvivors: BucketDataDoc[] = [];
+        const inputStats = emptyBucketStats();
 
         for await (const doc of query.stream()) {
           docsRead++;
@@ -736,10 +1264,17 @@ export class MongoCompactorV3 extends MongoCompactor {
             throw new ReplicationAssertionError(`Unexpected extra document before CLEAR boundary in bucket ${bucket}`);
           }
 
+          const documentStats = statsForDocument(doc);
+          inputStats.count += documentStats.count;
+          inputStats.bytes += documentStats.bytes;
+          inputStats.chunks += documentStats.chunks;
+          inputStats.checksum = addChecksums(inputStats.checksum, documentStats.checksum);
+
           const isBoundaryDoc = doc._id.o == boundaryDocId.o;
           if (doc.storage_ref) {
             oldStoragePaths.push(doc.storage_ref.path);
           }
+          oldStorageBytes += ObjectStorageUsage.bytes(doc);
           await hydrateBucketDataDocuments([doc], this.storage.objectStorage, { signal: this.signal });
           maxTargetOp = maxOpId(maxTargetOp, doc.target_op);
           for (const op of loadBucketDataDocument(context, doc)) {
@@ -800,8 +1335,11 @@ export class MongoCompactorV3 extends MongoCompactor {
         });
         await collection.insertMany(persisted.documents, { session });
         await this.finishObjectStorageReplacement(oldStoragePaths, persisted.storagePaths, persisted.uploads, session);
+        await this.recordObjectStorageReplacement(oldStorageBytes, persisted.documents, context.definitionId, session);
 
         opCountDiff = -clearedOpCount + 1;
+        before = inputStats;
+        after = statsForDocuments(persisted.documents);
       },
       {
         writeConcern: { w: 'majority' },
@@ -809,7 +1347,7 @@ export class MongoCompactorV3 extends MongoCompactor {
       }
     );
 
-    return opCountDiff;
+    return { opCountDiff, before, after };
   }
 
   /**
@@ -852,6 +1390,22 @@ export class MongoCompactorV3 extends MongoCompactor {
     );
   }
 
+  private async recordObjectStorageReplacement(
+    oldBytes: bigint,
+    newDocuments: Iterable<Pick<BucketDataDocumentV3, 'storage_ref'>>,
+    definitionId: BucketDefinitionId,
+    session: mongo.ClientSession
+  ): Promise<void> {
+    if (!this.storage.objectStorage) {
+      return;
+    }
+    let newBytes = 0n;
+    for (const document of newDocuments) {
+      newBytes += ObjectStorageUsage.bytes(document);
+    }
+    await this.objectStorageUsage.applyDelta(definitionId, newBytes - oldBytes, session);
+  }
+
   private async persistBucketData(
     bucket: string,
     chunks: BucketDataDoc[][],
@@ -908,7 +1462,7 @@ export class MongoCompactorV3 extends MongoCompactor {
         }
 
         const { ops, ...metadata } = serialized;
-        const { fileSize } = await store.store(upload.path, ops!);
+        const { fileSize } = await store.store(upload.path, ops!, { signal: this.signal });
         storagePaths.add(upload.path);
         return {
           ...metadata,