@powersync/service-core 1.24.0 → 1.26.0

package/dist/storage/SourceTable.js

@@ -1,5 +1,14 @@
 import { DEFAULT_TAG } from '@powersync/service-sync-rules';
 import * as util from '../util/util-index.js';
+/**
+ * Compare source-table ids without coercing between storage-specific types.
+ */
+export function sourceTableIdEquals(left, right) {
+    if (typeof left === 'string' || typeof right === 'string') {
+        return typeof left === 'string' && typeof right === 'string' && left === right;
+    }
+    return left.equals(right);
+}
 /**
  * Represents a resolved source table.
  *
@@ -26,11 +35,11 @@ export class SourceTable {
      */
     syncParameters = true;
     /**
-     * True if this table should fire events for row changes.
+     * True if this table should evaluate event definitions for row changes.
      *
-     * This value is resolved externally, and cached here. When multiple SourceTables exist
-     * for the same SourceTableRef (v3 storage), resolveTables designates exactly one of them
-     * as the event carrier, so that a row change saved once per table fires each event once.
+     * 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.
      */
@@ -88,6 +97,12 @@ export class SourceTable {
     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.
@@ -102,22 +117,39 @@ 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) {
+        return this.copyWithSourceMetadata(sourceMetadata);
+    }
+    copyWithSourceMetadata(sourceMetadata) {
         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)
+            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.storeCurrentData = this.storeCurrentData;
-        copy.snapshotStatus = this.snapshotStatus;
+        copy.snapshotStatus =
+            this.snapshotStatus == null
+                ? undefined
+                : {
+                    ...this.snapshotStatus,
+                    lastKey: this.snapshotStatus.lastKey?.slice() ?? null
+                };
         return copy;
     }
     formatSnapshotProgress() {

package/dist/storage/SourceTable.js.map

@@ -1 +1 @@
-{"version":3,"file":"SourceTable.js","sourceRoot":"","sources":["../../src/storage/SourceTable.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SourceTable.js","sourceRoot":"","sources":["../../src/storage/SourceTable.ts"],"names":[],"mappings":"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"}

package/dist/storage/SourceTableReconciler.d.ts

@@ -0,0 +1,83 @@
+import { JsonValue, SourceEntityDescriptor } from './SourceEntity.js';
+import { SourceTable, SourceTableCandidate, SourceTableId } 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 declare function sameReplicaIdColumns(left: SourceTableCandidate['replicaIdColumns'], right: SourceEntityDescriptor): boolean;
+/**
+ * Compare the shared source-table identity fields.
+ */
+export declare function sourceIdentityCompatible(source: SourceEntityDescriptor, candidate: SourceTableCandidate): boolean;
+/**
+ * Default identity-based reconciliation for connectors without source-specific metadata.
+ */
+export declare const defaultSourceTableReconciler: SourceTableCandidateReconciler;
+/**
+ * Check that every candidate was classified exactly once.
+ */
+export declare function validateSourceTableCandidateResolution(candidates: ReadonlyArray<SourceTableCandidate>, resolution: SourceTableCandidateResolution): void;
+/**
+ * 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 declare function materializeSourceTableResolution(tables: ReadonlyArray<SourceTable>, resolution: SourceTableCandidateResolution): MaterializedSourceTableResolution;
+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 declare function diffSourceTableUpdates(persistedTables: ReadonlyArray<SourceTable>, resolution: SourceTableCandidateResolution): SourceTableMetadataUpdate[];

package/dist/storage/SourceTableReconciler.js

@@ -0,0 +1,95 @@
+import { ServiceAssertionError } from '@powersync/lib-services-framework';
+import { isDeepStrictEqual } from 'node:util';
+import { sourceTableIdEquals } from './SourceTable.js';
+/**
+ * Compare replica-id columns in order.
+ */
+export function sameReplicaIdColumns(left, right) {
+    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, candidate) {
+    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 = ({ source, candidates }) => {
+    const compatibleTables = [];
+    const incompatibleTables = [];
+    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, resolution) {
+    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()}`);
+        }
+    }
+}
+/**
+ * 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, resolution) {
+    const findTable = (candidate) => {
+        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
+    };
+}
+/**
+ * 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, resolution) {
+    const updates = [];
+    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;
+}
+//# sourceMappingURL=SourceTableReconciler.js.map

package/dist/storage/SourceTableReconciler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SourceTableReconciler.js","sourceRoot":"","sources":["../../src/storage/SourceTableReconciler.ts"],"names":[],"mappings":"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"}

package/dist/storage/StorageVersionConfig.d.ts

@@ -33,6 +33,10 @@ export declare const STORAGE_VERSION_2 = 2;
  * This is used to build towards incremental reprocessing.
  */
 export declare const STORAGE_VERSION_3 = 3;
+/**
+ * Same as version 3, but marked as stable.
+ */
+export declare const STORAGE_VERSION_4 = 4;
 /**
  * Oldest supported storage version.
  */

package/dist/storage/StorageVersionConfig.js

@@ -16,6 +16,10 @@ export const STORAGE_VERSION_2 = 2;
  * This is used to build towards incremental reprocessing.
  */
 export const STORAGE_VERSION_3 = 3;
+/**
+ * Same as version 3, but marked as stable.
+ */
+export const STORAGE_VERSION_4 = 4;
 /**
  * Oldest supported storage version.
  */
@@ -29,7 +33,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.
  */
@@ -48,6 +52,11 @@ export const STORAGE_VERSION_CONFIG = {
         version: STORAGE_VERSION_3,
         versionedBuckets: true,
         softDeleteCurrentData: true
+    },
+    [STORAGE_VERSION_4]: {
+        version: STORAGE_VERSION_4,
+        versionedBuckets: true,
+        softDeleteCurrentData: true
     }
 };
 //# sourceMappingURL=StorageVersionConfig.js.map

package/dist/storage/StorageVersionConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"StorageVersionConfig.js","sourceRoot":"","sources":["../../src/storage/StorageVersionConfig.ts"],"names":[],"mappings":"AAoBA;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAEnC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAEnC;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAEnC;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,iBAAiB,CAAC;AAExD;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,iBAAiB,CAAC;AAEzD;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,iBAAiB,EAAE,iBAAiB,EAAE,iBAAiB,CAAC,CAAC;AAEpG;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAqD;IACtF,CAAC,iBAAiB,CAAC,EAAE;QACnB,OAAO,EAAE,iBAAiB;QAC1B,gBAAgB,EAAE,KAAK;QACvB,qBAAqB,EAAE,KAAK;KAC7B;IACD,CAAC,iBAAiB,CAAC,EAAE;QACnB,OAAO,EAAE,iBAAiB;QAC1B,gBAAgB,EAAE,IAAI;QACtB,qBAAqB,EAAE,KAAK;KAC7B;IACD,CAAC,iBAAiB,CAAC,EAAE;QACnB,OAAO,EAAE,iBAAiB;QAC1B,gBAAgB,EAAE,IAAI;QACtB,qBAAqB,EAAE,IAAI;KAC5B;CACF,CAAC"}
+{"version":3,"file":"StorageVersionConfig.js","sourceRoot":"","sources":["../../src/storage/StorageVersionConfig.ts"],"names":[],"mappings":"AAoBA;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAEnC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAEnC;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAEnC;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAEnC;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,iBAAiB,CAAC;AAExD;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,iBAAiB,CAAC;AAEzD;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,iBAAiB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,iBAAiB,CAAC,CAAC;AAEvH;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAqD;IACtF,CAAC,iBAAiB,CAAC,EAAE;QACnB,OAAO,EAAE,iBAAiB;QAC1B,gBAAgB,EAAE,KAAK;QACvB,qBAAqB,EAAE,KAAK;KAC7B;IACD,CAAC,iBAAiB,CAAC,EAAE;QACnB,OAAO,EAAE,iBAAiB;QAC1B,gBAAgB,EAAE,IAAI;QACtB,qBAAqB,EAAE,KAAK;KAC7B;IACD,CAAC,iBAAiB,CAAC,EAAE;QACnB,OAAO,EAAE,iBAAiB;QAC1B,gBAAgB,EAAE,IAAI;QACtB,qBAAqB,EAAE,IAAI;KAC5B;IACD,CAAC,iBAAiB,CAAC,EAAE;QACnB,OAAO,EAAE,iBAAiB;QAC1B,gBAAgB,EAAE,IAAI;QACtB,qBAAqB,EAAE,IAAI;KAC5B;CACF,CAAC"}

package/dist/storage/SyncRulesBucketStorage.d.ts

@@ -9,6 +9,7 @@ import { ParsedSyncConfigSet } from './ParsedSyncConfigSet.js';
 import { ParseSyncConfigOptions } from './PersistedSyncConfigContent.js';
 import { SourceEntityDescriptor } from './SourceEntity.js';
 import { SourceTable } from './SourceTable.js';
+import { SourceTableCandidateReconciler } from './SourceTableReconciler.js';
 import { StorageVersionConfig } from './StorageVersionConfig.js';
 import { SyncStorageWriteCheckpointAPI } from './WriteCheckpointAPI.js';
 /**
@@ -75,11 +76,18 @@ export interface SyncRulesBucketStorage extends ObserverClient<SyncRulesBucketSt
      * Errors are cleared on flush.
      */
     reportError(e: any): Promise<void>;
+    /**
+     * Whether parameter compaction can run when {@link CompactOptions.incrementalOnly} is set.
+     *
+     * Storage implementations that do not support incremental parameter compaction must return
+     * false; the compact command will skip parameter compaction in that mode.
+     */
+    supportsIncrementalParameterCompaction(): boolean;
     compact(options?: CompactOptions): Promise<void>;
     /**
-     * Lightweight "compact" process to populate the checksum cache, if any.
+     * Compact storage after initial replication, before the first checkpoint exists.
      */
-    populatePersistentChecksumCache(options: PopulateChecksumCacheOptions): Promise<PopulateChecksumCacheResults>;
+    compactInitialReplication(options: CompactInitialReplicationOptions): Promise<CompactInitialReplicationResults>;
     getCheckpoint(): Promise<ReplicationCheckpoint>;
     /**
      * Given two checkpoints, return the changes in bucket data and parameters that may have occurred
@@ -168,6 +176,11 @@ export interface ResolveTablesOptions {
      * Source table or collection metadata discovered during snapshot or streaming.
      */
     source: SourceEntityDescriptor;
+    /**
+     * Classifies overlapping persisted tables. Defaults to identity-based reconciliation.
+     * This may run inside a storage transaction and must not mutate storage.
+     */
+    reconcileSourceTables?: SourceTableCandidateReconciler;
     /**
      * For tests only - custom id generator for stable ids.
      */
@@ -220,6 +233,13 @@ export interface CreateWriterOptions extends ParseSyncConfigOptions {
     hooks?: StorageHooks;
     tracer?: PerformanceTracer<'storage' | 'evaluate'>;
     logger?: Logger;
+    /**
+     * Aborts long-running storage work started by this writer, such as uploads to object storage.
+     *
+     * This does not replace flushing or committing at the appropriate source boundary: it only
+     * cancels work that is still in flight when replication stops.
+     */
+    signal?: AbortSignal;
 }
 export interface StorageHooks {
     beforeBatchFlush?: (batch: BucketStorageBatch) => Promise<void>;
@@ -258,6 +278,14 @@ export interface CompactOptions {
      */
     compactBuckets?: string[];
     compactParameterData?: boolean;
+    /**
+     * Only perform compaction that can be done incrementally.
+     *
+     * This includes full bucket compaction on MongoDB V3 storage.
+     *
+     * On MongoDB v1 and Postgres storage, this makes compacting a no-op.
+     */
+    incrementalOnly?: boolean;
     /**
      * Delete client-requested write checkpoints created before this time.
      *
@@ -284,6 +312,14 @@ export interface CompactOptions {
      * Number between 0 and 1, default of 0.1.
      */
     minChangeRatio?: number;
+    /** Minimum delay before a V3 bucket is checked for chunk compaction. Default: five minutes. */
+    minCompactChunkIntervalMs?: number;
+    /** Minimum elapsed write pressure before the v3 sliding-scale full compact. Default: two hours. */
+    minCompactFullIntervalMs?: number;
+    /** Maximum age of writes not covered by a v3 full compact. */
+    maxCompactFullIntervalMs?: number;
+    /** How long a v3 worker owns a claimed bucket before another worker may recover it. */
+    compactLeaseDurationMs?: number;
     /**
      * Internal/testing use: Cache size for compacting parameters.
      */
@@ -291,21 +327,21 @@ export interface CompactOptions {
     signal?: AbortSignal;
     logger?: Logger;
 }
-export interface PopulateChecksumCacheOptions {
+export interface CompactInitialReplicationOptions {
     /**
-     * Compute checksums up to this op id.
+     * Compact data up to this op id.
      *
      * Defaults to the highest persisted op id for the replication stream, which covers
-     * the common case of populating the cache right after initial replication, before
+     * the common case of compacting right after initial replication, before
      * the first checkpoint exists.
      */
     maxOpId?: util.InternalOpId;
     minBucketChanges?: number;
     signal?: AbortSignal;
 }
-export interface PopulateChecksumCacheResults {
+export interface CompactInitialReplicationResults {
     /**
-     * Number of buckets we have calculated checksums for.
+     * Number of buckets processed.
      */
     buckets: number;
 }
@@ -338,6 +374,8 @@ export interface BucketDataBatchOptions {
     requestHint?: BucketRequestHint;
     /** Abort any in-progress work for this batch, including object-storage downloads. */
     signal?: AbortSignal;
+    /** Traces data reads performed by the storage implementation. */
+    tracer?: PerformanceTracer<string>;
     /** Limit number of documents returned. Defaults to 1000. */
     limit?: number;
     /**

package/dist/storage/SyncRulesBucketStorage.js.map

@@ -1 +1 @@
-{"version":3,"file":"SyncRulesBucketStorage.js","sourceRoot":"","sources":["../../src/storage/SyncRulesBucketStorage.ts"],"names":[],"mappings":"AA6bA,MAAM,UAAU,UAAU,CAAC,KAAmD;IAC5E,OAAQ,KAAgC,CAAC,OAAO,KAAK,SAAS,CAAC;AACjE,CAAC;AAiBD;;;;GAIG;AACH,MAAM,OAAO,8BAA+B,SAAQ,KAAK;IAE5C;IACA;IAFX,YACW,KAAa,EACb,SAAyC;QAElD,KAAK,CAAC,yCAAyC,KAAK,GAAG,CAAC,CAAC;QAHhD,UAAK,GAAL,KAAK,CAAQ;QACb,cAAS,GAAT,SAAS,CAAgC;IAGpD,CAAC;CACF;AAqDD,MAAM,CAAC,MAAM,yBAAyB,GAAsB;IAC1D,kBAAkB,EAAE,IAAI,GAAG,EAAU;IACrC,qBAAqB,EAAE,IAAI;IAC3B,uBAAuB,EAAE,IAAI,GAAG,EAAU;IAC1C,0BAA0B,EAAE,IAAI;CACjC,CAAC"}
+{"version":3,"file":"SyncRulesBucketStorage.js","sourceRoot":"","sources":["../../src/storage/SyncRulesBucketStorage.ts"],"names":[],"mappings":"AA2eA,MAAM,UAAU,UAAU,CAAC,KAAmD;IAC5E,OAAQ,KAAgC,CAAC,OAAO,KAAK,SAAS,CAAC;AACjE,CAAC;AAiBD;;;;GAIG;AACH,MAAM,OAAO,8BAA+B,SAAQ,KAAK;IAE5C;IACA;IAFX,YACW,KAAa,EACb,SAAyC;QAElD,KAAK,CAAC,yCAAyC,KAAK,GAAG,CAAC,CAAC;QAHhD,UAAK,GAAL,KAAK,CAAQ;QACb,cAAS,GAAT,SAAS,CAAgC;IAGpD,CAAC;CACF;AAqDD,MAAM,CAAC,MAAM,yBAAyB,GAAsB;IAC1D,kBAAkB,EAAE,IAAI,GAAG,EAAU;IACrC,qBAAqB,EAAE,IAAI;IAC3B,uBAAuB,EAAE,IAAI,GAAG,EAAU;IAC1C,0BAA0B,EAAE,IAAI;CACjC,CAAC"}

package/dist/storage/WriteCheckpointAPI.d.ts

@@ -1,3 +1,4 @@
+import { EventDefinitionId } from '@powersync/service-sync-rules';
 export declare enum WriteCheckpointMode {
     /**
      * Raw mappings of `user_id` to `write_checkpoint`s should
@@ -28,7 +29,8 @@ export interface ClientRequestedCheckpointOptions {
      */
     checkpoint_request_id?: bigint;
 }
-export interface CustomWriteCheckpointFilters extends BaseWriteCheckpointIdentifier {
+export type SyncStorageCustomWriteCheckpointFilters = BaseWriteCheckpointIdentifier;
+export interface CustomWriteCheckpointFilters extends SyncStorageCustomWriteCheckpointFilters {
     /**
      * Replication stream which was active when this checkpoint was created.
      */
@@ -40,6 +42,14 @@ export interface BatchedCustomWriteCheckpointOptions extends BaseWriteCheckpoint
      * "write checkpoint" in storage APIs for backwards compatibility.
      */
     checkpoint: bigint;
+    /**
+     * Compiled event definition which created the checkpoint.
+     *
+     * Incremental replication uses this to keep checkpoint records produced by
+     * active and processing sync configs separate. This is required by v3
+     * storage and unused by legacy storage versions.
+     */
+    event_id?: EventDefinitionId;
     /**
      * Required when this custom checkpoint was created from a client checkpoint
      * request and should be eligible for checkpoint request retention cleanup.
@@ -102,11 +112,23 @@ export interface CreateManagedWriteCheckpointsResult {
     shouldAdvance: boolean;
 }
 export declare function uniqueManagedWriteCheckpoints(checkpoints: ManagedWriteCheckpointOptions[]): ManagedWriteCheckpointOptions[];
-export type SyncStorageLastWriteCheckpointFilters = BaseWriteCheckpointIdentifier | ManagedWriteCheckpointFilters;
+export type SyncStorageLastWriteCheckpointFilters = SyncStorageCustomWriteCheckpointFilters | ManagedWriteCheckpointFilters;
 export type LastWriteCheckpointFilters = CustomWriteCheckpointFilters | ManagedWriteCheckpointFilters;
+/** Configures checkpoint ownership and generation for a storage instance. */
+export type WriteCheckpointModeConfig = {
+    mode: WriteCheckpointMode.CUSTOM;
+    /**
+     * Name of the event whose custom checkpoints are served. Storage resolves this name through the active sync
+     * config's persisted mapping; integrations must not construct or persist event ids themselves. Required by
+     * storage implementations that scope custom checkpoints by event definition.
+     */
+    eventName?: string;
+} | {
+    mode: WriteCheckpointMode.MANAGED;
+};
 export interface BaseWriteCheckpointAPI {
     readonly writeCheckpointMode: WriteCheckpointMode;
-    setWriteCheckpointMode(mode: WriteCheckpointMode): void;
+    setWriteCheckpointMode(config: WriteCheckpointModeConfig): void;
     createManagedWriteCheckpoints(checkpoints: ManagedWriteCheckpointOptions[]): Promise<CreateManagedWriteCheckpointsResult>;
 }
 /**

package/dist/storage/WriteCheckpointAPI.js.map

@@ -1 +1 @@
-{"version":3,"file":"WriteCheckpointAPI.js","sourceRoot":"","sources":["../../src/storage/WriteCheckpointAPI.ts"],"names":[],"mappings":"AAAA,MAAM,CAAN,IAAY,mBAYX;AAZD,WAAY,mBAAmB;IAC7B;;;OAGG;IACH,wCAAiB,CAAA;IACjB;;;;OAIG;IACH,0CAAmB,CAAA;AACrB,CAAC,EAZW,mBAAmB,KAAnB,mBAAmB,QAY9B;AAoGD,MAAM,UAAU,6BAA6B,CAC3C,WAA4C;IAE5C,MAAM,MAAM,GAAG,IAAI,GAAG,EAAyC,CAAC;IAEhE,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACrC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QAChD,0EAA0E;QAC1E,4EAA4E;QAC5E,2EAA2E;QAC3E,uEAAuE;QACvE,qEAAqE;QACrE,0EAA0E;QAC1E,4EAA4E;QAC5E,WAAW;QACX,EAAE;QACF,8EAA8E;QAC9E,0EAA0E;QAC1E,sDAAsD;QACtD,IAAI,QAAQ,IAAI,IAAI,IAAI,mCAAmC,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE,CAAC;YAClF,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IAED,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED,SAAS,mCAAmC,CAC1C,QAAuC,EACvC,SAAwC;IAExC,MAAM,iBAAiB,GAAG,QAAQ,CAAC,qBAAqB,CAAC;IACzD,MAAM,kBAAkB,GAAG,SAAS,CAAC,qBAAqB,CAAC;IAE3D,IAAI,kBAAkB,IAAI,IAAI,EAAE,CAAC;QAC/B,OAAO,iBAAiB,IAAI,IAAI,CAAC;IACnC,CAAC;IAED,IAAI,iBAAiB,IAAI,IAAI,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,kBAAkB,GAAG,iBAAiB,CAAC;AAChD,CAAC;AA8BD,MAAM,CAAC,MAAM,6BAA6B,GAAG,mBAAmB,CAAC,OAAO,CAAC"}
+{"version":3,"file":"WriteCheckpointAPI.js","sourceRoot":"","sources":["../../src/storage/WriteCheckpointAPI.ts"],"names":[],"mappings":"AAEA,MAAM,CAAN,IAAY,mBAYX;AAZD,WAAY,mBAAmB;IAC7B;;;OAGG;IACH,wCAAiB,CAAA;IACjB;;;;OAIG;IACH,0CAAmB,CAAA;AACrB,CAAC,EAZW,mBAAmB,KAAnB,mBAAmB,QAY9B;AA8GD,MAAM,UAAU,6BAA6B,CAC3C,WAA4C;IAE5C,MAAM,MAAM,GAAG,IAAI,GAAG,EAAyC,CAAC;IAEhE,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACrC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QAChD,0EAA0E;QAC1E,4EAA4E;QAC5E,2EAA2E;QAC3E,uEAAuE;QACvE,qEAAqE;QACrE,0EAA0E;QAC1E,4EAA4E;QAC5E,WAAW;QACX,EAAE;QACF,8EAA8E;QAC9E,0EAA0E;QAC1E,sDAAsD;QACtD,IAAI,QAAQ,IAAI,IAAI,IAAI,mCAAmC,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE,CAAC;YAClF,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IAED,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED,SAAS,mCAAmC,CAC1C,QAAuC,EACvC,SAAwC;IAExC,MAAM,iBAAiB,GAAG,QAAQ,CAAC,qBAAqB,CAAC;IACzD,MAAM,kBAAkB,GAAG,SAAS,CAAC,qBAAqB,CAAC;IAE3D,IAAI,kBAAkB,IAAI,IAAI,EAAE,CAAC;QAC/B,OAAO,iBAAiB,IAAI,IAAI,CAAC;IACnC,CAAC;IAED,IAAI,iBAAiB,IAAI,IAAI,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,kBAAkB,GAAG,iBAAiB,CAAC;AAChD,CAAC;AA+CD,MAAM,CAAC,MAAM,6BAA6B,GAAG,mBAAmB,CAAC,OAAO,CAAC"}

package/dist/storage/implementation/BucketDefinitionMapping.d.ts

@@ -1,13 +1,17 @@
-import { BucketDataSource, BucketDefinitionId, ParameterIndexId, ParameterIndexLookupCreator, ParameterLookupDefinitionId, SerializedSyncPlan, SourceTableRef, SyncConfigWithErrors } from '@powersync/service-sync-rules';
+import { BucketDataSource, BucketDefinitionId, EventDefinitionId, ParameterIndexId, ParameterIndexLookupCreator, ParameterLookupDefinitionId, SerializedSyncPlan, SourceTableRef, SyncConfigWithErrors } from '@powersync/service-sync-rules';
+/** Minimal shape required to resolve an event's assigned id: its name is the per-config key. */
+export interface NamedEventDefinition {
+    readonly name: string;
+}
 export interface SerializedSyncConfigWithMapping {
     plan: SerializedSyncPlan;
     mapping: SingleSyncConfigBucketDefinitionMapping;
 }
-export type IncrementalMappingDefinitionType = 'bucket_data' | 'parameter_lookup';
+export type IncrementalMappingDefinitionType = 'bucket_data' | 'parameter_lookup' | 'event';
 export interface IncrementalMappingDefinitionChange {
     type: IncrementalMappingDefinitionType;
     name: string;
-    id: BucketDefinitionId | ParameterIndexId;
+    id: BucketDefinitionId | ParameterIndexId | EventDefinitionId;
 }
 export interface IncrementalMappingChanges {
     reusedDefinitions: IncrementalMappingDefinitionChange[];
@@ -36,6 +40,10 @@ export interface PersistedDefinitionMapping {
      * Map of (lookupName, queryId) -> id, unique per replication stream.
      */
     parameter_indexes: Record<string, string>;
+    /**
+     * Map of event name -> id, unique per replication stream. Absent for mappings persisted before events were tracked.
+     */
+    events?: Record<string, string>;
 }
 /**
  * Represents a mapping from bucket data sources and parameter lookup sources to stable IDs used for bucket definition and parameter index persistence.
@@ -53,7 +61,8 @@ export interface BucketDefinitionMapping {
     parameterLookupId(source: ParameterIndexLookupCreator): ParameterIndexId;
     allBucketDefinitionIds(): BucketDefinitionId[];
     allParameterIndexIds(): ParameterIndexId[];
-    syncConfigIdsForSourceTable(selectedSyncConfigIds: string[], table: SourceTableRef, bucketDataSourceIds: BucketDefinitionId[], parameterLookupSourceIds: ParameterIndexId[]): string[];
+    allEventDefinitionIds(): EventDefinitionId[];
+    syncConfigIdsForSourceTable(selectedSyncConfigIds: string[], table: SourceTableRef, bucketDataSourceIds: BucketDefinitionId[], parameterLookupSourceIds: ParameterIndexId[], eventDefinitionIds: EventDefinitionId[]): string[];
     snapshotBlockingSourceTablesFilter(syncConfigId: string): Record<string, unknown>;
 }
 /**
@@ -67,6 +76,7 @@ export interface BucketDefinitionMapping {
 export declare class SingleSyncConfigBucketDefinitionMapping implements BucketDefinitionMapping {
     private definitions;
     private parameterLookupMapping;
+    private events;
     static fromPersistedMapping(mapping: PersistedDefinitionMapping): SingleSyncConfigBucketDefinitionMapping;
     static fromParsedSyncConfig(syncConfig: SyncConfigWithErrors): SingleSyncConfigBucketDefinitionMapping;
     /**
@@ -78,18 +88,22 @@ export declare class SingleSyncConfigBucketDefinitionMapping implements BucketDe
      */
     static constructIncrementalMappingFromSerializedPlans(compatibleConfigs: SerializedSyncConfigWithMapping[], newPlan: SerializedSyncPlan, reservedMappings: SingleSyncConfigBucketDefinitionMapping[]): SingleSyncConfigBucketDefinitionMapping;
     static constructIncrementalMappingWithChanges(compatibleConfigs: SerializedSyncConfigWithMapping[], newPlan: SerializedSyncPlan, reservedMappings: SingleSyncConfigBucketDefinitionMapping[]): IncrementalMappingResult;
-    constructor(definitions?: Record<string, BucketDefinitionId>, parameterLookupMapping?: Record<string, ParameterIndexId>);
+    constructor(definitions?: Record<string, BucketDefinitionId>, parameterLookupMapping?: Record<string, ParameterIndexId>, events?: Record<string, EventDefinitionId>);
     bucketSourceId(source: BucketDataSource): BucketDefinitionId;
     bucketSourceIdByName(uniqueName: string): BucketDefinitionId;
     allBucketDefinitionIds(): BucketDefinitionId[];
     bucketDefinitionEntries(): IncrementalMappingDefinitionChange[];
     allParameterIndexIds(): ParameterIndexId[];
     parameterIndexEntries(): IncrementalMappingDefinitionChange[];
+    allEventDefinitionIds(): EventDefinitionId[];
+    eventDefinitionEntries(): IncrementalMappingDefinitionChange[];
     allDefinitionEntries(): IncrementalMappingDefinitionChange[];
     parameterLookupId(source: ParameterIndexLookupCreator): ParameterIndexId;
     parameterLookupIdByKey(key: string): ParameterIndexId;
+    eventId(event: NamedEventDefinition): EventDefinitionId;
+    eventDefinitionIdByName(name: string): EventDefinitionId;
     serialize(): PersistedDefinitionMapping;
-    syncConfigIdsForSourceTable(selectedSyncConfigIds: string[], _table: SourceTableRef, bucketDataSourceIds: BucketDefinitionId[], parameterLookupSourceIds: ParameterIndexId[]): string[];
+    syncConfigIdsForSourceTable(selectedSyncConfigIds: string[], _table: SourceTableRef, bucketDataSourceIds: BucketDefinitionId[], parameterLookupSourceIds: ParameterIndexId[], eventDefinitionIds: EventDefinitionId[]): string[];
     snapshotBlockingSourceTablesFilter(_syncConfigId: string): Record<string, unknown>;
 }
 /**
@@ -104,6 +118,7 @@ export declare class MultiSyncConfigBucketDefinitionMapping implements BucketDef
     private bucketDataSourceSyncConfigIdsById;
     private parameterLookupMappings;
     private parameterLookupSyncConfigIdsById;
+    private eventDefinitionSyncConfigIdsById;
     private syncConfigsById;
     private mappings;
     constructor(syncConfigs: SyncConfigWithRequiredMapping[]);
@@ -111,7 +126,8 @@ export declare class MultiSyncConfigBucketDefinitionMapping implements BucketDef
     allBucketDefinitionIds(): BucketDefinitionId[];
     parameterLookupId(source: ParameterIndexLookupCreator): ParameterIndexId;
     allParameterIndexIds(): ParameterIndexId[];
-    syncConfigIdsForSourceTable(_selectedSyncConfigIds: string[], table: SourceTableRef, bucketDataSourceIds: BucketDefinitionId[], parameterLookupSourceIds: ParameterIndexId[]): string[];
+    allEventDefinitionIds(): EventDefinitionId[];
+    syncConfigIdsForSourceTable(_selectedSyncConfigIds: string[], _table: SourceTableRef, bucketDataSourceIds: BucketDefinitionId[], parameterLookupSourceIds: ParameterIndexId[], eventDefinitionIds: EventDefinitionId[]): string[];
     snapshotBlockingSourceTablesFilter(syncConfigId: string): Record<string, unknown>;
 }
 export declare function parameterLookupKey(id: ParameterLookupDefinitionId): string;