@powersync/service-core 0.0.0-dev-20260602073133 → 0.0.0-dev-20260909133214

package/src/storage/PersistedSyncConfigContent.ts

@@ -0,0 +1,207 @@
+import { logger as defaultLogger, ErrorCode, ServiceError } from '@powersync/lib-services-framework';
+import {
+  CompatibilityContext,
+  CompatibilityOption,
+  compileEventDefinitions,
+  DEFAULT_HYDRATION_STATE,
+  deserializeSyncPlan,
+  ErrorLocation,
+  HydratedSyncConfig,
+  HydrationState,
+  nodeSqlite,
+  PrecompiledSyncConfig,
+  SqlSyncRules,
+  SyncConfigWithErrors,
+  versionedHydrationState,
+  YamlError
+} from '@powersync/service-sync-rules';
+import * as sqlite from 'node:sqlite';
+import { Logger } from 'winston';
+import { SyncRuleState } from './BucketStorage.js';
+import { SerializedSyncPlan, UpdateSyncRulesOptions } from './BucketStorageFactory.js';
+import { ParsedSyncConfigSet } from './ParsedSyncConfigSet.js';
+import { PersistedSyncConfigStatus } from './PersistedSyncConfigStatus.js';
+import { STORAGE_VERSION_CONFIG, StorageVersionConfig } from './StorageVersionConfig.js';
+
+export interface ParsePersistedSyncConfigContentOptions {
+  content: string;
+  compiledPlan: SerializedSyncPlan | null;
+  storageVersion: number;
+  parseOptions: ParseSyncConfigOptions;
+}
+
+export function parsePersistedSyncConfigContent(options: ParsePersistedSyncConfigContentOptions): SyncConfigWithErrors {
+  const { content, compiledPlan, storageVersion, parseOptions } = options;
+
+  if (compiledPlan == null) {
+    // Fallback: Only parse from YAML if no compiled plan is available.
+    return SqlSyncRules.fromYaml(content, parseOptions);
+  }
+
+  const plan = deserializeSyncPlan(compiledPlan.plan);
+  const compatibility = CompatibilityContext.deserialize(compiledPlan.compatibility);
+  const errors: YamlError[] = [];
+  // Compiled events are additive to plan versions 1 and 2. New readers prefer them when present; when an older plan
+  // does not contain them, normalize the dual-written raw SQL at this loading boundary. This keeps legacy event
+  // evaluators out of PrecompiledSyncConfig while older binaries can continue reading the same persisted config.
+  if (compiledPlan.plan.events == null) {
+    const normalized = compileEventDefinitions(compiledPlan.eventDescriptors, {
+      ...parseOptions,
+      // The legacy evaluator ignored event payload filters. Preserve that behavior for plans deployed before compiled
+      // events existed; a redeploy compiles and validates those filters before the replacement config is activated.
+      compileEventPayloadFilters: false
+    });
+    const fatalErrors = normalized.errors.filter((error) => error.type == 'fatal');
+    if (fatalErrors.length != 0) {
+      throw new Error(
+        `Failed to compile persisted replication events: ${fatalErrors.map((error) => error.message).join(', ')}`
+      );
+    }
+    plan.events = normalized.events;
+    errors.push(...normalized.errors.map((error) => new YamlError(error)));
+  }
+
+  const precompiled = new PrecompiledSyncConfig(plan, compatibility, {
+    defaultSchema: parseOptions.defaultSchema,
+    sourceText: content
+  });
+
+  // Note: If the original content did not define a storage version, this will still set the storage version.
+  // This means asUpdateOptions will not change the storage version, even if the default changes.
+  precompiled.storageVersion = storageVersion;
+
+  if (compiledPlan.errors) {
+    for (const error of compiledPlan.errors) {
+      const location: ErrorLocation | undefined = error.location && {
+        start: error.location.start_offset,
+        end: error.location.end_offset
+      };
+      const asYamlError = new YamlError(new Error(error.message), location);
+      asYamlError.type = error.level;
+
+      errors.push(asYamlError);
+    }
+  }
+
+  return { config: precompiled, errors };
+}
+
+/**
+ * Immutable sync config content for one sync config inside a replication stream.
+ *
+ * This represents the persisted config content. Fetch per-config status with
+ * {@link getSyncConfigStatus}. Use {@link PersistedReplicationStream} for stream
+ * lifecycle concerns such as locking and termination.
+ */
+
+export abstract class PersistedSyncConfigContent implements PersistedSyncConfigContentData {
+  readonly replicationStreamId: number;
+  readonly sync_rules_content: string;
+  readonly compiled_plan: SerializedSyncPlan | null;
+  readonly replicationStreamName: string;
+  readonly storageVersion: number;
+  readonly logger: Logger;
+  readonly syncConfigId: PersistedSyncConfigId | null;
+  readonly syncConfigState: SyncRuleState;
+  readonly version_label: string | undefined;
+
+  constructor(data: PersistedSyncConfigContentData) {
+    this.replicationStreamId = data.replicationStreamId;
+    this.sync_rules_content = data.sync_rules_content;
+    this.compiled_plan = data.compiled_plan;
+    this.replicationStreamName = data.replicationStreamName;
+    this.storageVersion = data.storageVersion;
+    this.syncConfigId = data.syncConfigId ?? null;
+    this.syncConfigState = data.syncConfigState;
+    this.version_label = data.version_label;
+    const versionPrefix = this.version_label == null ? '' : `[${this.version_label}]`;
+    this.logger = defaultLogger.child({ prefix: `[${this.replicationStreamName}]${versionPrefix} ` });
+  }
+
+  /**
+   * Load the storage config.
+   *
+   * This may throw if the persisted storage version is not supported.
+   */
+  getStorageConfig(): StorageVersionConfig {
+    const storageConfig = STORAGE_VERSION_CONFIG[this.storageVersion];
+    if (storageConfig == null) {
+      throw new ServiceError(
+        ErrorCode.PSYNC_S1005,
+        `Unsupported storage version ${this.storageVersion} for replication stream ${this.replicationStreamId}`
+      );
+    }
+    return storageConfig;
+  }
+
+  /**
+   * Parse only this config's content into a single {@link SyncConfigWithErrors}.
+   *
+   * This does not depend on any other configs in the same replication stream.
+   */
+  protected parseSingleConfig(options: ParseSyncConfigOptions): SyncConfigWithErrors {
+    return parsePersistedSyncConfigContent({
+      content: this.sync_rules_content,
+      compiledPlan: this.compiled_plan,
+      storageVersion: this.storageVersion,
+      parseOptions: options
+    });
+  }
+
+  parsed(options: ParseSyncConfigOptions): ParsedSyncConfigSet {
+    let hydrationState: HydrationState;
+    const config = this.parseSingleConfig(options);
+
+    const storageConfig = this.getStorageConfig();
+    if (
+      storageConfig.versionedBuckets ||
+      config.config.compatibility.isEnabled(CompatibilityOption.versionedBucketIds)
+    ) {
+      hydrationState = versionedHydrationState(this.replicationStreamId);
+    } else {
+      hydrationState = DEFAULT_HYDRATION_STATE;
+    }
+
+    let hydrated: HydratedSyncConfig | undefined;
+    return {
+      replicationStreamId: this.replicationStreamId,
+      replicationStreamName: this.replicationStreamName,
+      syncConfigs: [config],
+      hydrationState,
+      get hydratedSyncConfig(): HydratedSyncConfig {
+        hydrated ??= config.config.hydrate({ hydrationState, sqlite: nodeSqlite(sqlite) });
+        return hydrated;
+      }
+    };
+  }
+
+  asUpdateOptions(options?: Omit<UpdateSyncRulesOptions, 'config'>): UpdateSyncRulesOptions {
+    // defaultSchema is not relevant for the parsed version here
+    const parsed = this.parseSingleConfig({ defaultSchema: 'not_applicable' });
+    return {
+      config: { yaml: this.sync_rules_content, plan: this.compiled_plan, parsed },
+      version_label: this.version_label,
+      ...options
+    };
+  }
+
+  /**
+   * Fetch the current persisted state for this exact sync config.
+   */
+  abstract getSyncConfigStatus(): Promise<PersistedSyncConfigStatus | null>;
+}
+export interface PersistedSyncConfigContentData {
+  readonly replicationStreamId: number;
+  readonly sync_rules_content: string;
+  readonly compiled_plan: SerializedSyncPlan | null;
+  readonly replicationStreamName: string;
+  readonly storageVersion: number;
+
+  readonly syncConfigId?: PersistedSyncConfigId | null;
+  readonly syncConfigState: SyncRuleState;
+  readonly version_label?: string;
+}
+export type PersistedSyncConfigId = string;
+export interface ParseSyncConfigOptions {
+  defaultSchema: string;
+}

package/src/storage/PersistedSyncConfigStatus.ts

@@ -0,0 +1,14 @@
+import { SyncRuleState } from './BucketStorage.js';
+import { PersistedSyncConfigId } from './PersistedSyncConfigContent.js';
+
+export interface PersistedSyncConfigStatus {
+  readonly id: PersistedSyncConfigId;
+  readonly replicationStreamId: number;
+  readonly state: SyncRuleState;
+  readonly snapshot_done?: boolean;
+  readonly last_checkpoint_lsn: string | null;
+  readonly last_fatal_error?: string | null;
+  readonly last_fatal_error_ts?: Date | null;
+  readonly last_keepalive_ts?: Date | null;
+  readonly last_checkpoint_ts?: Date | null;
+}

package/src/storage/ReplicationEventPayload.ts

@@ -11,6 +11,11 @@ export type EventData = {
 export type ReplicationEventPayload = {
   batch: BucketStorageBatch;
   data: EventData;
-  event: sync_rules.SqlEventDescriptor;
+  event: sync_rules.HydratedEventDescriptor;
+  /**
+   * Storage-assigned id for this event definition. Present when storage uses persisted event mappings, allowing event
+   * handlers to route custom checkpoints without deriving an id from compiled event content.
+   */
+  event_id?: sync_rules.EventDefinitionId;
   table: SourceTable;
 };

package/src/storage/SourceEntity.ts

@@ -1,5 +1,11 @@
 import { SourceTableRef } from '@powersync/service-sync-rules';
 
+/**
+ * Source-specific JSON metadata. Storage does not interpret it. Source-table APIs use null to
+ * represent the absence of metadata.
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
 export interface ColumnDescriptor {
   name: string;
   /**
@@ -19,10 +25,14 @@ export interface SourceEntityDescriptor extends SourceTableRef {
    * If specified, this is specifically used to detect renames.
    */
   objectId: number | string | undefined;
-  schema: string;
-  name: string;
   /**
    *  The columns that are used to uniquely identify a record in the source entity.
    */
   replicaIdColumns: ColumnDescriptor[];
+  /**
+   * Whether the source always sends complete row data with each operation (e.g. Postgres REPLICA
+   * IDENTITY FULL). When true, no current_data copy is needed. Undefined means the source does not
+   * report this, in which case we default to keeping a copy.
+   */
+  sendsCompleteRows?: boolean;
 }

package/src/storage/SourceTable.ts

@@ -1,18 +1,31 @@
 import {
   BucketDataSource,
+  BucketDefinitionId,
   DEFAULT_TAG,
+  EventDefinitionId,
+  ParameterIndexId,
   ParameterIndexLookupCreator,
   SourceTableRef
 } from '@powersync/service-sync-rules';
 import { bson } from '../index.js';
 import * as util from '../util/util-index.js';
-import { ColumnDescriptor } from './SourceEntity.js';
+import { ColumnDescriptor, JsonValue } from './SourceEntity.js';
 
 /**
  * Format of the id depends on the bucket storage module. It should be consistent within the module.
  */
 export type SourceTableId = string | bson.ObjectId;
 
+/**
+ * Compare source-table ids without coercing between storage-specific types.
+ */
+export function sourceTableIdEquals(left: SourceTableId, right: SourceTableId): boolean {
+  if (typeof left === 'string' || typeof right === 'string') {
+    return typeof left === 'string' && typeof right === 'string' && left === right;
+  }
+  return left.equals(right);
+}
+
 export interface SourceTableOptions {
   id: SourceTableId;
   ref: SourceTableRef;
@@ -21,6 +34,19 @@ export interface SourceTableOptions {
   snapshotComplete: boolean;
   bucketDataSources: BucketDataSource[];
   parameterLookupSources: ParameterIndexLookupCreator[];
+  bucketDataSourceIds?: Set<BucketDefinitionId>;
+  parameterLookupSourceIds?: Set<ParameterIndexId>;
+  /**
+   * Compiled event definitions assigned to this persisted source-table record.
+   *
+   * Undefined is the legacy/non-incremental representation where event selection is
+   * based on the table ref. V3 incremental storage always supplies this set.
+   */
+  eventDefinitionIds?: Set<EventDefinitionId>;
+  /**
+   * Source-specific metadata. Null when no metadata has been recorded.
+   */
+  sourceMetadata?: JsonValue;
 }
 
 export interface TableSnapshotStatus {
@@ -57,14 +83,29 @@ export class SourceTable {
   public syncParameters = true;
 
   /**
-   * True if the table is used in sync config for events.
+   * True if this table should evaluate event definitions for row changes.
    *
-   * This value is resolved externally, and cached here.
+   * This value is resolved externally, and cached here. V3 storage assigns disjoint
+   * event-definition ids to SourceTables for the same physical table. Multiple records
+   * may evaluate different events, but each event id is evaluated through at most one record.
    *
    * Defaults to true for tests.
    */
   public syncEvent = true;
 
+  /**
+   * True if raw data should be stored in current_data collection.
+   *
+   * This is needed when the source sends partial row data (e.g. TOAST values).
+   * When REPLICA IDENTITY FULL is configured, complete rows are always sent,
+   * so we don't need to store raw data.
+   *
+   * This value is resolved externally based on table configuration.
+   *
+   * Defaults to true for tests (conservative approach).
+   */
+  public storeCurrentData = true;
+
   /**
    * Always undefined if snapshotComplete = true.
    *
@@ -109,6 +150,22 @@ export class SourceTable {
     return this.options.parameterLookupSources;
   }
 
+  get bucketDataSourceIds() {
+    return this.options.bucketDataSourceIds;
+  }
+
+  get parameterLookupSourceIds() {
+    return this.options.parameterLookupSourceIds;
+  }
+
+  get eventDefinitionIds() {
+    return this.options.eventDefinitionIds;
+  }
+
+  get sourceMetadata() {
+    return this.options.sourceMetadata ?? null;
+  }
+
   /**
    * Sanitized name of the entity in the format of "{schema}.{entity name}".
    * Suitable for safe use in Postgres queries.
@@ -125,19 +182,42 @@ export class SourceTable {
    * In-memory clone of the table status.
    */
   clone() {
+    return this.copyWithSourceMetadata(this.sourceMetadata);
+  }
+
+  /**
+   * Copy this table with different source metadata, preserving its resolved state.
+   */
+  withSourceMetadata(sourceMetadata: JsonValue) {
+    return this.copyWithSourceMetadata(sourceMetadata);
+  }
+
+  private copyWithSourceMetadata(sourceMetadata: JsonValue) {
     const copy = new SourceTable({
       id: this.id,
-      ref: this.options.ref,
+      ref: { ...this.options.ref },
       objectId: this.objectId,
-      replicaIdColumns: this.replicaIdColumns,
+      replicaIdColumns: this.replicaIdColumns.map((column) => ({ ...column })),
       snapshotComplete: this.snapshotComplete,
-      bucketDataSources: this.bucketDataSources,
-      parameterLookupSources: this.parameterLookupSources
+      bucketDataSources: [...this.bucketDataSources],
+      parameterLookupSources: [...this.parameterLookupSources],
+      bucketDataSourceIds: this.bucketDataSourceIds == null ? undefined : new Set(this.bucketDataSourceIds),
+      parameterLookupSourceIds:
+        this.parameterLookupSourceIds == null ? undefined : new Set(this.parameterLookupSourceIds),
+      eventDefinitionIds: this.eventDefinitionIds == null ? undefined : new Set(this.eventDefinitionIds),
+      sourceMetadata: structuredClone(sourceMetadata)
     });
     copy.syncData = this.syncData;
     copy.syncParameters = this.syncParameters;
     copy.syncEvent = this.syncEvent;
-    copy.snapshotStatus = this.snapshotStatus;
+    copy.storeCurrentData = this.storeCurrentData;
+    copy.snapshotStatus =
+      this.snapshotStatus == null
+        ? undefined
+        : {
+            ...this.snapshotStatus,
+            lastKey: this.snapshotStatus.lastKey?.slice() ?? null
+          };
     return copy;
   }
 
@@ -152,3 +232,11 @@ export class SourceTable {
     }
   }
 }
+
+/**
+ * A cloned SourceTable exposed to reconciliation with public fields typed as read-only.
+ * `options` is omitted so callers cannot mutate the underlying option bag without an explicit cast.
+ */
+export type SourceTableCandidate = Omit<Readonly<SourceTable>, 'options' | 'withSourceMetadata'> & {
+  withSourceMetadata(sourceMetadata: JsonValue): SourceTableCandidate;
+};

package/src/storage/SourceTableReconciler.ts

@@ -0,0 +1,188 @@
+import { ServiceAssertionError } from '@powersync/lib-services-framework';
+import { isDeepStrictEqual } from 'node:util';
+import { JsonValue, SourceEntityDescriptor } from './SourceEntity.js';
+import { SourceTable, SourceTableCandidate, SourceTableId, sourceTableIdEquals } from './SourceTable.js';
+
+/**
+ * A source connector's classification of overlapping persisted tables.
+ */
+export interface SourceTableCandidateResolution {
+  /**
+   * Records storage can reuse. Copies may include updated source metadata.
+   */
+  compatibleTables: ReadonlyArray<SourceTableCandidate>;
+
+  /**
+   * Records that cannot be reused. Every candidate must appear in exactly one result list.
+   */
+  incompatibleTables: ReadonlyArray<SourceTableCandidate>;
+
+  /**
+   * Values for records storage creates during this resolution.
+   */
+  newTableValues: SourceTableCreateValues;
+}
+
+export interface SourceTableCreateValues {
+  /**
+   * Source metadata for new records. Null means no metadata.
+   */
+  sourceMetadata: JsonValue;
+}
+
+/**
+ * Input to a source-owned reconciliation callback. The callback may run inside a storage
+ * transaction, so it must not mutate storage or perform slow external work.
+ */
+export interface SourceTableCandidateReconcilerInput {
+  /**
+   * Source entity being resolved.
+   */
+  source: SourceEntityDescriptor;
+
+  /**
+   * Persisted tables overlapping by name or object id.
+   */
+  candidates: ReadonlyArray<SourceTableCandidate>;
+}
+
+export type SourceTableCandidateReconciler = (
+  input: SourceTableCandidateReconcilerInput
+) => SourceTableCandidateResolution | Promise<SourceTableCandidateResolution>;
+
+/**
+ * Compare replica-id columns in order.
+ */
+export function sameReplicaIdColumns(
+  left: SourceTableCandidate['replicaIdColumns'],
+  right: SourceEntityDescriptor
+): boolean {
+  const target = right.replicaIdColumns;
+  return (
+    left.length == target.length &&
+    left.every(
+      (column, index) =>
+        column.name == target[index].name && column.type == target[index].type && column.typeId == target[index].typeId
+    )
+  );
+}
+
+/**
+ * Compare the shared source-table identity fields.
+ */
+export function sourceIdentityCompatible(source: SourceEntityDescriptor, candidate: SourceTableCandidate): boolean {
+  return (
+    candidate.schema == source.schema &&
+    candidate.name == source.name &&
+    (source.objectId == null || candidate.objectId == source.objectId) &&
+    sameReplicaIdColumns(candidate.replicaIdColumns, source)
+  );
+}
+
+/**
+ * Default identity-based reconciliation for connectors without source-specific metadata.
+ */
+export const defaultSourceTableReconciler: SourceTableCandidateReconciler = ({ source, candidates }) => {
+  const compatibleTables: SourceTableCandidate[] = [];
+  const incompatibleTables: SourceTableCandidate[] = [];
+  for (const candidate of candidates) {
+    if (sourceIdentityCompatible(source, candidate)) {
+      compatibleTables.push(candidate);
+    } else {
+      incompatibleTables.push(candidate);
+    }
+  }
+  return { compatibleTables, incompatibleTables, newTableValues: { sourceMetadata: null } };
+};
+
+/**
+ * Check that every candidate was classified exactly once.
+ */
+export function validateSourceTableCandidateResolution(
+  candidates: ReadonlyArray<SourceTableCandidate>,
+  resolution: SourceTableCandidateResolution
+): void {
+  const classifiedTables = [...resolution.compatibleTables, ...resolution.incompatibleTables];
+
+  for (const candidate of candidates) {
+    const classifications = classifiedTables.filter((table) => sourceTableIdEquals(table.id, candidate.id));
+    if (classifications.length !== 1) {
+      throw new ServiceAssertionError(
+        `Source table candidate ${candidate.id.toString()} must be classified exactly once, got ${classifications.length}`
+      );
+    }
+  }
+
+  for (const table of classifiedTables) {
+    if (!candidates.some((candidate) => sourceTableIdEquals(candidate.id, table.id))) {
+      throw new ServiceAssertionError(`Source table reconciliation returned unknown candidate ${table.id.toString()}`);
+    }
+  }
+}
+
+/**
+ * A source-metadata update to persist.
+ */
+export interface SourceTableMetadataUpdate {
+  id: SourceTableId;
+  sourceMetadata: JsonValue;
+}
+
+/**
+ * Rebuild a resolution from storage-owned tables, applying only reconciler-owned metadata to
+ * compatible tables. All other mutable table state comes from storage.
+ *
+ * Reconciler candidates are typed as read-only, but TypeScript types provide no runtime protection:
+ * callback code can cast a cloned candidate and mutate it. Rematerializing by id ensures those
+ * mutations are not trusted even when the compile-time boundary is bypassed.
+ */
+export function materializeSourceTableResolution(
+  tables: ReadonlyArray<SourceTable>,
+  resolution: SourceTableCandidateResolution
+): MaterializedSourceTableResolution {
+  const findTable = (candidate: SourceTableCandidate): SourceTable => {
+    const table = tables.find((table) => sourceTableIdEquals(table.id, candidate.id));
+    if (table == null) {
+      throw new ServiceAssertionError(`Source table candidate ${candidate.id.toString()} was not persisted`);
+    }
+    return table;
+  };
+  return {
+    compatibleTables: resolution.compatibleTables.map((candidate) =>
+      findTable(candidate).withSourceMetadata(candidate.sourceMetadata)
+    ),
+    incompatibleTables: resolution.incompatibleTables.map(findTable),
+    newTableValues: resolution.newTableValues
+  };
+}
+
+export interface MaterializedSourceTableResolution {
+  compatibleTables: SourceTable[];
+  incompatibleTables: SourceTable[];
+  newTableValues: SourceTableCreateValues;
+}
+
+/**
+ * Return source-metadata changes from compatible candidates, comparing metadata by value against
+ * the original storage-owned tables. The reconciler may mutate its isolated candidate clones, so
+ * those clones cannot be used as the persisted baseline.
+ */
+export function diffSourceTableUpdates(
+  persistedTables: ReadonlyArray<SourceTable>,
+  resolution: SourceTableCandidateResolution
+): SourceTableMetadataUpdate[] {
+  const updates: SourceTableMetadataUpdate[] = [];
+  for (const resolvedTable of resolution.compatibleTables) {
+    const persistedTable = persistedTables.find((table) => sourceTableIdEquals(table.id, resolvedTable.id));
+    if (persistedTable == null) {
+      throw new ServiceAssertionError(
+        `Source table reconciliation returned unknown candidate ${resolvedTable.id.toString()}`
+      );
+    }
+    if (isDeepStrictEqual(persistedTable.sourceMetadata, resolvedTable.sourceMetadata)) {
+      continue;
+    }
+    updates.push({ id: resolvedTable.id, sourceMetadata: resolvedTable.sourceMetadata });
+  }
+  return updates;
+}

package/src/storage/StorageVersionConfig.ts

@@ -39,6 +39,11 @@ export const STORAGE_VERSION_2 = 2;
  */
 export const STORAGE_VERSION_3 = 3;
 
+/**
+ * Same as version 3, but marked as stable.
+ */
+export const STORAGE_VERSION_4 = 4;
+
 /**
  * Oldest supported storage version.
  */
@@ -54,7 +59,7 @@ export const CURRENT_STORAGE_VERSION = STORAGE_VERSION_2;
  *
  * This includes unstable versions.
  */
-export const SUPPORTED_STORAGE_VERSIONS = [STORAGE_VERSION_1, STORAGE_VERSION_2, STORAGE_VERSION_3];
+export const SUPPORTED_STORAGE_VERSIONS = [STORAGE_VERSION_1, STORAGE_VERSION_2, STORAGE_VERSION_3, STORAGE_VERSION_4];
 
 /**
  * Shared storage-version behavior across storage implementations.
@@ -74,5 +79,10 @@ export const STORAGE_VERSION_CONFIG: Record<number, StorageVersionConfig | undef
     version: STORAGE_VERSION_3,
     versionedBuckets: true,
     softDeleteCurrentData: true
+  },
+  [STORAGE_VERSION_4]: {
+    version: STORAGE_VERSION_4,
+    versionedBuckets: true,
+    softDeleteCurrentData: true
   }
 };