@powersync/service-module-mongodb-storage 0.0.0-dev-20260602073133 → 0.0.0-dev-20260909133214

package/test/src/compact-utils.test.ts

@@ -0,0 +1,226 @@
+import {
+  applyCompactionDelta,
+  applyStatsReplacement,
+  bucketStats,
+  chooseCompactionKind,
+  combineAdjacentStats,
+  combineChunkStats,
+  CompactIntervalConfig,
+  CompactionKind,
+  emptyBucketStats,
+  forcedCompactionKind,
+  fullCompactionCheckAt,
+  statsForDocument,
+  statsForDocuments
+} from '@module/storage/implementation/v3/compact-utils.js';
+import { BucketStateDocumentV3 } from '@module/storage/implementation/v3/models.js';
+import { describe, expect, test } from 'vitest';
+
+const INTERVAL_CONFIG: CompactIntervalConfig = {
+  minCompactChunkIntervalMs: 1_000,
+  minCompactFullIntervalMs: 10_000,
+  maxCompactFullIntervalMs: 100_000
+};
+
+function bucketState(overrides: Partial<BucketStateDocumentV3> = {}): BucketStateDocumentV3 {
+  return {
+    _id: { d: 'definition', b: 'bucket[]' },
+    last_op: 10n,
+    next_compact_check: new Date(0),
+    first_uncompacted_write: new Date(0),
+    bucket_stats: { count: 10, bytes: 100n, chunks: 1 },
+    ...overrides
+  };
+}
+
+function compactedState(overrides: Partial<NonNullable<BucketStateDocumentV3['compacted_state']>> = {}) {
+  return {
+    op_id: 5n,
+    checksum: 50n,
+    count: 5,
+    bytes: 50n,
+    chunks: 1,
+    at: new Date(0),
+    ...overrides
+  };
+}
+
+describe('V3 compact utilities', () => {
+  test.each([
+    {
+      name: 'uses the minimum interval before the first full compact',
+      state: bucketState(),
+      expected: new Date(10_000)
+    },
+    {
+      name: 'scales the interval by the uncompacted row ratio',
+      state: bucketState({
+        bucket_stats: { count: 100, bytes: 100n, chunks: 1 },
+        last_full_compact: { op_id: 90n, count: 90, puts: 90, at: new Date(0) }
+      }),
+      expected: new Date(100_000)
+    },
+    {
+      name: 'uses the maximum interval when there are no uncompacted rows',
+      state: bucketState({
+        bucket_stats: { count: 100, bytes: 100n, chunks: 1 },
+        last_full_compact: { op_id: 10n, count: 100, puts: 100, at: new Date(0) }
+      }),
+      expected: new Date(100_000)
+    }
+  ])('$name', ({ state, expected }) => {
+    expect(fullCompactionCheckAt(state, INTERVAL_CONFIG)).toEqual(expected);
+  });
+
+  test('rejects a scheduled bucket without an uncompacted write', () => {
+    expect(() => fullCompactionCheckAt(bucketState({ first_uncompacted_write: undefined }), INTERVAL_CONFIG)).toThrow(
+      'Scheduled V3 bucket bucket[] has no first uncompacted write'
+    );
+  });
+
+  test('chooses a full compact when its check is due', () => {
+    const decision = chooseCompactionKind(
+      bucketState({ bucket_stats: { count: 10, bytes: 100n, chunks: 10 } }),
+      new Date(10_000),
+      INTERVAL_CONFIG
+    );
+
+    expect(decision.kind).toBe(CompactionKind.Full);
+    expect(decision.nextCompactCheck).toEqual({
+      $min: [new Date(70_000), { $dateAdd: { startDate: '$$NOW', unit: 'millisecond', amount: 1_000 } }]
+    });
+  });
+
+  test('chooses a chunk compact after enough chunks and the minimum interval', () => {
+    const decision = chooseCompactionKind(
+      bucketState({
+        bucket_stats: { count: 10, bytes: 100n, chunks: 9 },
+        compacted_state: compactedState({ chunks: 1 })
+      }),
+      new Date(5_000),
+      INTERVAL_CONFIG
+    );
+
+    expect(decision.kind).toBe(CompactionKind.Chunks);
+  });
+
+  test('waits when the chunk interval has not elapsed', () => {
+    const decision = chooseCompactionKind(
+      bucketState({
+        bucket_stats: { count: 10, bytes: 100n, chunks: 9 },
+        compacted_state: compactedState({ chunks: 1, at: new Date(4_500) })
+      }),
+      new Date(5_000),
+      INTERVAL_CONFIG
+    );
+
+    expect(decision.kind).toBeNull();
+  });
+
+  test('schedules only the full check when too few chunks were added', () => {
+    const decision = chooseCompactionKind(
+      bucketState({ bucket_stats: { count: 7, bytes: 70n, chunks: 7 } }),
+      new Date(5_000),
+      INTERVAL_CONFIG
+    );
+
+    expect(decision).toEqual({ kind: null, nextCompactCheck: new Date(70_000) });
+  });
+
+  test.each([
+    {
+      name: 'does not force an unspecified kind',
+      forceKind: undefined,
+      compactedOpId: undefined,
+      maxOpIdCap: undefined,
+      expected: null
+    },
+    {
+      name: 'forces work without previous compacted state',
+      forceKind: CompactionKind.Chunks,
+      compactedOpId: undefined,
+      maxOpIdCap: undefined,
+      expected: CompactionKind.Chunks
+    },
+    {
+      name: 'skips work already compacted through the cap',
+      forceKind: CompactionKind.Chunks,
+      compactedOpId: 5n,
+      maxOpIdCap: 5n,
+      expected: null
+    },
+    {
+      name: 'skips work already compacted through the bucket head',
+      forceKind: CompactionKind.Chunks,
+      compactedOpId: 10n,
+      maxOpIdCap: undefined,
+      expected: null
+    },
+    {
+      name: 'forces work beyond the compacted state',
+      forceKind: CompactionKind.Chunks,
+      compactedOpId: 5n,
+      maxOpIdCap: 6n,
+      expected: CompactionKind.Chunks
+    }
+  ])('$name', ({ forceKind, compactedOpId, maxOpIdCap, expected }) => {
+    const state = bucketState({
+      compacted_state: compactedOpId == null ? undefined : compactedState({ op_id: compactedOpId })
+    });
+    expect(forcedCompactionKind(state, forceKind, { maxOpIdCap })).toBe(expected);
+  });
+
+  test('derives and combines bucket statistics', () => {
+    const state = bucketState({ bucket_stats: { count: 12, bytes: 120n, chunks: 3 } });
+    expect(bucketStats(state)).toEqual({ count: 12, bytes: 120n, chunks: 3 });
+    expect(emptyBucketStats()).toEqual({ count: 0, bytes: 0n, chunks: 0, checksum: 0 });
+    expect(statsForDocument({ count: 2, size: 20, checksum: 10n })).toEqual({
+      count: 2,
+      bytes: 20n,
+      chunks: 1,
+      checksum: 10
+    });
+    expect(
+      statsForDocuments([
+        { count: 2, size: 20, checksum: 10n },
+        { count: 3, size: 30, checksum: 20n }
+      ])
+    ).toEqual({ count: 5, bytes: 50n, chunks: 2, checksum: 30 });
+    expect(
+      combineAdjacentStats(
+        { count: 2, bytes: 20n, chunks: 1, checksum: 10 },
+        { count: 3, bytes: 30n, chunks: 2, checksum: 20 }
+      )
+    ).toEqual({ count: 5, bytes: 50n, chunks: 3, checksum: 30 });
+  });
+
+  test('replaces an overlapping chunk in cached statistics', () => {
+    expect(
+      combineChunkStats(
+        compactedState({ count: 10, bytes: 100n, chunks: 4, checksum: 100n }),
+        { count: 6, bytes: 60n, chunks: 2, checksum: 50 },
+        { count: 3, bytes: 30n, chunks: 1, checksum: 30 }
+      )
+    ).toEqual({ count: 13, bytes: 130n, chunks: 5, checksum: 120 });
+  });
+
+  test('applies compacted statistics as a delta to total bucket statistics', () => {
+    expect(
+      applyCompactionDelta(
+        { count: 20, bytes: 200n, chunks: 8 },
+        { count: 5, bytes: 50n, chunks: 3, checksum: 10 },
+        { count: 3, bytes: 30n, chunks: 1, checksum: 10 }
+      )
+    ).toEqual({ count: 18, bytes: 180n, chunks: 6 });
+  });
+
+  test('applies a stored range replacement to statistics including its checksum', () => {
+    expect(
+      applyStatsReplacement(
+        { count: 20, bytes: 200n, chunks: 8, checksum: 100 },
+        { count: 5, bytes: 50n, chunks: 3, checksum: 40 },
+        { count: 3, bytes: 30n, chunks: 1, checksum: 20 }
+      )
+    ).toEqual({ count: 18, bytes: 180n, chunks: 6, checksum: 80 });
+  });
+});

package/test/src/helpers/MemoryObjectStorage.ts

@@ -0,0 +1,61 @@
+import {
+  ObjectStorage,
+  ObjectStorageOperationOptions,
+  ObjectStoragePutMetadata
+} from '@module/storage/implementation/v3/object-storage/ObjectStorage.js';
+
+export class MemoryObjectStorage implements ObjectStorage {
+  /**
+   * Public for testing purposes.
+   */
+  public readonly store = new Map<string, { data: Uint8Array; metadata: ObjectStoragePutMetadata }>();
+
+  async put(
+    path: string,
+    data: Uint8Array,
+    metadata: ObjectStoragePutMetadata,
+    options?: ObjectStorageOperationOptions
+  ): Promise<void> {
+    options?.signal?.throwIfAborted();
+    this.store.set(path, { data, metadata: metadata });
+  }
+
+  async get(
+    path: string,
+    options?: ObjectStorageOperationOptions
+  ): Promise<{ data: Uint8Array; metadata: ObjectStoragePutMetadata }> {
+    const signal = options?.signal;
+    signal?.throwIfAborted();
+    const data = this.store.get(path);
+    if (!data) {
+      throw new Error(`NotFound: ${path}`);
+    }
+    return data;
+  }
+
+  async *list(prefix: string, options?: ObjectStorageOperationOptions): AsyncIterable<string> {
+    const signal = options?.signal;
+    for (const path of this.store.keys()) {
+      signal?.throwIfAborted();
+      if (path.startsWith(prefix)) {
+        yield path;
+      }
+    }
+  }
+
+  async delete(paths: string[], options?: ObjectStorageOperationOptions): Promise<void> {
+    options?.signal?.throwIfAborted();
+    for (const p of paths) {
+      this.store.delete(p);
+    }
+  }
+
+  async deletePrefix(prefix: string, options?: ObjectStorageOperationOptions): Promise<{ objectCount: number }> {
+    const paths: string[] = [];
+    for await (const path of this.list(prefix, options)) {
+      paths.push(path);
+    }
+    await this.delete(paths, options);
+    return { objectCount: paths.length };
+  }
+}

package/test/src/helpers/s3TestFactory.ts

@@ -0,0 +1,69 @@
+import { ObjectStorage } from '@module/storage/implementation/v3/object-storage/ObjectStorage.js';
+import { S3ObjectStorage } from '@module/storage/implementation/v3/object-storage/S3ObjectStorage.js';
+import { mongoTestStorageFactoryGenerator } from '@module/utils/test-utils.js';
+import { randomUUID } from 'node:crypto';
+import { MemoryObjectStorage } from './MemoryObjectStorage.js';
+
+const minioStorages: S3ObjectStorage[] = [];
+
+export interface S3TestFactoryOptions {
+  url: string;
+  isCI: boolean;
+  inlineThresholdBytes?: number;
+}
+
+function createTestStorageSuite(options: S3TestFactoryOptions, objectStorage: ObjectStorage) {
+  return {
+    objectStorage,
+    factoryGen: mongoTestStorageFactoryGenerator({
+      url: options.url,
+      isCI: options.isCI,
+      objectStorage,
+      inlineThresholdBytes: options.inlineThresholdBytes ?? 0
+    })
+  };
+}
+
+/**
+ * Creates an ObjectStorage instance for S3 tests.
+ * Set MINIO_ENDPOINT to switch all S3 tests from MemoryObjectStorage
+ * to a real MinIO/S3 endpoint.
+ *   MINIO_ENDPOINT=http://localhost:9000
+ */
+export function createS3TestStorageSuite(options: S3TestFactoryOptions) {
+  const minioEndpoint = process.env.MINIO_ENDPOINT;
+  let objectStorage: ObjectStorage;
+  if (minioEndpoint) {
+    const s3 = new S3ObjectStorage({
+      bucket: 'powersync-s3-test',
+      region: 'us-east-1',
+      prefix: `test-${process.pid}-${randomUUID()}`,
+      endpoint: minioEndpoint,
+      forcePathStyle: true,
+      accessKeyId: process.env.MINIO_ACCESS_KEY ?? 'minioadmin',
+      secretAccessKey: process.env.MINIO_SECRET_KEY ?? 'minioadmin'
+    });
+    minioStorages.push(s3);
+    objectStorage = s3;
+  } else {
+    objectStorage = new MemoryObjectStorage();
+  }
+
+  return createTestStorageSuite(options, objectStorage);
+}
+
+/** Remove all objects created by MinIO-backed suites in the current test. */
+export async function cleanupS3TestStorage(): Promise<void> {
+  for (const storage of minioStorages.splice(0)) {
+    await storage.deletePrefix('bucket-data/');
+  }
+}
+
+/** Creates an explicitly memory-backed suite for tests that inspect stored objects. */
+export function createMemoryS3TestStorageSuite(options: S3TestFactoryOptions) {
+  const objectStorage = new MemoryObjectStorage();
+  return {
+    ...createTestStorageSuite(options, objectStorage),
+    objectStorage
+  };
+}

package/test/src/object_storage_lifecycle.test.ts

@@ -0,0 +1,59 @@
+import { createHash } from 'node:crypto';
+import { describe, expect, test } from 'vitest';
+import { ObjectStorageLifecycle } from '../../src/storage/implementation/v3/object-storage/ObjectStorageLifecycle.js';
+import { MemoryObjectStorage } from './helpers/MemoryObjectStorage.js';
+
+describe('ObjectStorageLifecycle', () => {
+  test('escapes bucket names as path segments', () => {
+    const lifecycle = new ObjectStorageLifecycle(null as any, 12, null as any);
+
+    const path = lifecycle.allocatePath('definition', 'bucket/with spaces?and%escapes', 1n, 2n);
+
+    expect(path).toMatch(/^bucket-data\/12\/definition\/bucket%2Fwith%20spaces%3Fand%25escapes\/1-2-[0-9a-f-]+\.bson$/);
+  });
+
+  test('hashes bucket path segments longer than 128 bytes', () => {
+    const lifecycle = new ObjectStorageLifecycle(null as any, 12, null as any);
+    const bucket = '💾/long bucket parameter/'.repeat(20);
+    const hash = createHash('sha256').update(bucket).digest('base64url');
+
+    const path = lifecycle.allocatePath('definition', bucket, 1n, 2n);
+
+    expect(path).toMatch(new RegExp(`^bucket-data/12/definition/sha256-${hash}/1-2-[0-9a-f-]+\\.bson$`));
+  });
+
+  test('deletePrefix removes only objects under the exact prefix', async () => {
+    const objectStorage = new MemoryObjectStorage();
+    const lifecycle = new ObjectStorageLifecycle(null as any, 1, objectStorage);
+    for (const path of [
+      'bucket-data/1/definition/object-1.bson',
+      'bucket-data/12/definition/object-2.bson',
+      'bucket-data/1-other/definition/object-3.bson'
+    ]) {
+      await objectStorage.put(path, new Uint8Array(), {
+        contentType: 'application/bson',
+        contentEncoding: null
+      });
+    }
+
+    await expect(lifecycle.deletePrefix(lifecycle.streamPrefix())).resolves.toEqual({ objectCount: 1 });
+    expect([...objectStorage.store.keys()]).toEqual([
+      'bucket-data/12/definition/object-2.bson',
+      'bucket-data/1-other/definition/object-3.bson'
+    ]);
+  });
+
+  test('definition prefixes do not match ids with the same string prefix', async () => {
+    const objectStorage = new MemoryObjectStorage();
+    const lifecycle = new ObjectStorageLifecycle(null as any, 7, objectStorage);
+    for (const path of ['bucket-data/7/1/object-1.bson', 'bucket-data/7/12/object-2.bson']) {
+      await objectStorage.put(path, new Uint8Array(), {
+        contentType: 'application/bson',
+        contentEncoding: null
+      });
+    }
+
+    await lifecycle.deletePrefix(lifecycle.definitionPrefix('1'));
+    expect([...objectStorage.store.keys()]).toEqual(['bucket-data/7/12/object-2.bson']);
+  });
+});

package/test/src/object_storage_usage.test.ts

@@ -0,0 +1,255 @@
+import { MongoSyncBucketStorage } from '@module/storage/implementation/createMongoSyncBucketStorage.js';
+import { BucketDataDocumentV3, ObjectStorageUsageDocument } from '@module/storage/implementation/v3/models.js';
+import {
+  OBJECT_STORAGE_USAGE_BASE_WRITER_ID,
+  ObjectStorageUsage
+} from '@module/storage/implementation/v3/object-storage/ObjectStorageUsage.js';
+import { VersionedPowerSyncMongoV3 } from '@module/storage/implementation/v3/VersionedPowerSyncMongoV3.js';
+import * as lib_mongo from '@powersync/lib-service-mongodb';
+import { mongo } from '@powersync/lib-service-mongodb';
+import { updateSyncRulesFromYaml } from '@powersync/service-core';
+import { BucketDefinitionId } from '@powersync/service-sync-rules';
+import { describe, expect, test } from 'vitest';
+import { INITIALIZED_MONGO_STORAGE_FACTORY } from './util.js';
+
+const SYNC_RULES_YAML = `
+bucket_definitions:
+  global:
+    data:
+      - SELECT id FROM items
+`;
+
+type UsageContext = {
+  db: VersionedPowerSyncMongoV3;
+  bucketStorage: MongoSyncBucketStorage;
+  definitionId: BucketDefinitionId;
+};
+
+type UsageEntry = {
+  definition_id: BucketDefinitionId;
+  active_bytes: bigint;
+};
+
+async function withUsageContext<T>(callback: (context: UsageContext) => Promise<T>): Promise<T> {
+  await using factory = await INITIALIZED_MONGO_STORAGE_FACTORY.factory();
+  const syncRules = await factory.updateSyncRules(updateSyncRulesFromYaml(SYNC_RULES_YAML, { storageVersion: 3 }));
+  const bucketStorage = factory.getInstance(syncRules) as MongoSyncBucketStorage;
+  const db = bucketStorage.db as VersionedPowerSyncMongoV3;
+  const definitionId = syncRules.syncConfigContent[0].mapping.allBucketDefinitionIds()[0];
+  return callback({ db, bucketStorage, definitionId });
+}
+
+async function withTransaction<T>(
+  db: VersionedPowerSyncMongoV3,
+  callback: (session: mongo.ClientSession) => Promise<T>
+): Promise<T> {
+  const session = db.client.startSession();
+  try {
+    return await session.withTransaction(() => callback(session));
+  } finally {
+    await session.endSession();
+  }
+}
+
+async function readUsageEntries(
+  db: VersionedPowerSyncMongoV3,
+  replicationStreamId: number,
+  session?: mongo.ClientSession
+): Promise<UsageEntry[]> {
+  const entries = await db.objectStorageUsage
+    .aggregate<{ _id: BucketDefinitionId; active_bytes: bigint }>(
+      [
+        { $match: { '_id.g': replicationStreamId } },
+        { $project: { definitions: { $objectToArray: '$definitions' } } },
+        { $unwind: '$definitions' },
+        { $group: { _id: '$definitions.k', active_bytes: { $sum: '$definitions.v' } } }
+      ],
+      { session, readConcern: 'snapshot' }
+    )
+    .toArray()
+    .catch((error) => {
+      if (lib_mongo.isMongoNamespaceNotFoundError(error)) {
+        return [];
+      }
+      throw error;
+    });
+
+  return entries.map((entry) => ({
+    definition_id: entry._id,
+    active_bytes: BigInt(entry.active_bytes ?? 0)
+  }));
+}
+
+function usageDocument(
+  replicationStreamId: number,
+  writerId: string,
+  definitions: Record<string, bigint>,
+  updatedAt = new Date(0)
+): ObjectStorageUsageDocument {
+  return {
+    _id: { g: replicationStreamId, w: writerId },
+    updated_at: updatedAt,
+    definitions
+  };
+}
+
+function bucketDataDocument(
+  replicationStreamId: number,
+  definitionId: BucketDefinitionId,
+  fileSize: number
+): BucketDataDocumentV3 {
+  return {
+    _id: { b: `${replicationStreamId}-${definitionId}`, o: 1n },
+    min_op: 1n,
+    checksum: 1n,
+    count: 1,
+    size: fileSize,
+    storage_ref: {
+      path: `bucket-data/${replicationStreamId}/${definitionId}/1.bson`,
+      file_size: fileSize
+    }
+  };
+}
+
+describe('ObjectStorageUsage', () => {
+  test('counts a committed reference exactly once after an aborted transaction is retried', async () => {
+    await withUsageContext(async ({ db, bucketStorage, definitionId }) => {
+      const replicationStreamId = bucketStorage.replicationStreamId;
+      const writerId = 'replication-writer';
+      const usage = new ObjectStorageUsage(db, replicationStreamId, writerId);
+      const bucketData = db.bucketData(replicationStreamId, definitionId);
+      const document = bucketDataDocument(replicationStreamId, definitionId, 123);
+
+      await expect(
+        withTransaction(db, async (session) => {
+          await bucketData.insertOne(document, { session });
+          await usage.applyDelta(definitionId, 123n, session);
+          throw new Error('abort this attempt');
+        })
+      ).rejects.toThrow('abort this attempt');
+
+      await withTransaction(db, async (session) => {
+        await bucketData.insertOne(document, { session });
+        await usage.applyDelta(definitionId, 123n, session);
+      });
+
+      expect(await bucketData.countDocuments({ storage_ref: { $exists: true } })).toBe(1);
+      await expect(readUsageEntries(db, replicationStreamId)).resolves.toEqual([
+        { definition_id: definitionId, active_bytes: 123n }
+      ]);
+    });
+  });
+
+  test('snapshot usage reads observe a complete pre-fold view', async () => {
+    await withUsageContext(async ({ db, bucketStorage, definitionId }) => {
+      const replicationStreamId = bucketStorage.replicationStreamId;
+      const usage = new ObjectStorageUsage(db, replicationStreamId);
+      await db.objectStorageUsage.insertMany([
+        usageDocument(replicationStreamId, OBJECT_STORAGE_USAGE_BASE_WRITER_ID, { [definitionId]: 100n }),
+        usageDocument(replicationStreamId, 'replication', { [definitionId]: 20n }),
+        usageDocument(replicationStreamId, 'compactor', { [definitionId]: -5n })
+      ]);
+
+      const readSession = db.client.startSession();
+      try {
+        readSession.startTransaction({ readConcern: { level: 'snapshot' } });
+        await db.objectStorageUsage.findOne(
+          { _id: { g: replicationStreamId, w: OBJECT_STORAGE_USAGE_BASE_WRITER_ID } },
+          { session: readSession }
+        );
+
+        await usage.foldStaleWriterDeltas({ staleWriterMs: 0 });
+        const entries = await readUsageEntries(db, replicationStreamId, readSession);
+
+        await readSession.commitTransaction();
+        expect(entries).toEqual([{ definition_id: definitionId, active_bytes: 115n }]);
+      } catch (error) {
+        await readSession.abortTransaction().catch(() => undefined);
+        throw error;
+      } finally {
+        await readSession.endSession();
+      }
+
+      await expect(readUsageEntries(db, replicationStreamId)).resolves.toEqual([
+        { definition_id: definitionId, active_bytes: 115n }
+      ]);
+    });
+  });
+
+  test('folding preserves totals across both writer/folder commit orders', async () => {
+    await withUsageContext(async ({ db, bucketStorage, definitionId }) => {
+      const replicationStreamId = bucketStorage.replicationStreamId;
+      const writerId = 'reused-writer';
+      const usage = new ObjectStorageUsage(db, replicationStreamId, writerId);
+
+      await withTransaction(db, (session) => usage.applyDelta(definitionId, 10n, session));
+      await db.objectStorageUsage.updateOne(
+        { _id: { g: replicationStreamId, w: writerId } },
+        { $set: { updated_at: new Date(0) } }
+      );
+      await usage.foldStaleWriterDeltas({ staleWriterMs: 0 });
+
+      // The folder committed first and deleted the writer shard. The writer's
+      // next transaction must recreate it through the upsert.
+      await withTransaction(db, (session) => usage.applyDelta(definitionId, 4n, session));
+      expect((await readUsageEntries(db, replicationStreamId))[0].active_bytes).toBe(14n);
+
+      await db.objectStorageUsage.updateOne(
+        { _id: { g: replicationStreamId, w: writerId } },
+        { $set: { updated_at: new Date(0) } }
+      );
+      await usage.foldStaleWriterDeltas({ staleWriterMs: 0 });
+
+      // The writer committed before the folder. Folding the recreated shard
+      // must preserve the same visible total.
+      expect((await readUsageEntries(db, replicationStreamId))[0].active_bytes).toBe(14n);
+    });
+  });
+
+  test('definition cleanup racing a fold removes only that definition, and stream clear is isolated', async () => {
+    await withUsageContext(async ({ db, bucketStorage, definitionId }) => {
+      const replicationStreamId = bucketStorage.replicationStreamId;
+      const otherStreamId = replicationStreamId + 1;
+      const otherDefinitionId = 'other_definition';
+      const usage = new ObjectStorageUsage(db, replicationStreamId);
+
+      await db.objectStorageUsage.insertMany([
+        usageDocument(replicationStreamId, OBJECT_STORAGE_USAGE_BASE_WRITER_ID, {
+          [definitionId]: 3n,
+          [otherDefinitionId]: 7n
+        }),
+        usageDocument(replicationStreamId, 'writer', { [definitionId]: 20n, [otherDefinitionId]: 11n }),
+        usageDocument(otherStreamId, 'other-writer', { [definitionId]: 50n })
+      ]);
+
+      await Promise.all([
+        usage.foldStaleWriterDeltas({ staleWriterMs: 0 }),
+        withTransaction(db, (session) => usage.removeDefinition(definitionId, session))
+      ]);
+
+      await expect(readUsageEntries(db, replicationStreamId)).resolves.toEqual([
+        { definition_id: otherDefinitionId, active_bytes: 18n }
+      ]);
+
+      await withTransaction(db, async (session) => {
+        await new ObjectStorageUsage(db, otherStreamId).removeStream(session);
+      });
+      await db.objectStorageUsage.insertOne(usageDocument(otherStreamId, 'other-writer', { [definitionId]: 50n }));
+
+      await withTransaction(db, async (session) => {
+        await usage.removeStream(session);
+      });
+
+      await expect(ObjectStorageUsage.readAllDefinitionUsage(db)).resolves.toEqual([
+        { replication_stream_id: otherStreamId, definition_id: definitionId, active_bytes: 50n }
+      ]);
+    });
+  });
+
+  test('returns no entries for an absent usage collection', async () => {
+    await withUsageContext(async ({ db, bucketStorage }) => {
+      await db.objectStorageUsage.drop().catch(() => undefined);
+      await expect(readUsageEntries(db, bucketStorage.replicationStreamId)).resolves.toEqual([]);
+    });
+  });
+});