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

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

@@ -0,0 +1,15 @@
+import { BucketDefinitionId, ParameterIndexId } from '@powersync/service-sync-rules';
+import { SingleSyncConfigBucketDefinitionMapping } from './BucketDefinitionMapping.js';
+/**
+ * Persisted storage ids for a replication stream, derived from the rule_mapping documents
+ * of all its sync configs.
+ *
+ * This requires no parsed sync configs, and deliberately does not resolve individual
+ * sources - use the parsed-set-bound {@link BucketDefinitionMapping} for that.
+ */
+export declare class ReplicationStreamStorageIds {
+    private readonly mappings;
+    constructor(mappings: SingleSyncConfigBucketDefinitionMapping[]);
+    get bucketDefinitionIds(): BucketDefinitionId[];
+    get parameterIndexIds(): ParameterIndexId[];
+}

package/dist/storage/implementation/ReplicationStreamStorageIds.js

@@ -0,0 +1,20 @@
+/**
+ * Persisted storage ids for a replication stream, derived from the rule_mapping documents
+ * of all its sync configs.
+ *
+ * This requires no parsed sync configs, and deliberately does not resolve individual
+ * sources - use the parsed-set-bound {@link BucketDefinitionMapping} for that.
+ */
+export class ReplicationStreamStorageIds {
+    mappings;
+    constructor(mappings) {
+        this.mappings = mappings;
+    }
+    get bucketDefinitionIds() {
+        return [...new Set(this.mappings.flatMap((mapping) => mapping.allBucketDefinitionIds()))];
+    }
+    get parameterIndexIds() {
+        return [...new Set(this.mappings.flatMap((mapping) => mapping.allParameterIndexIds()))];
+    }
+}
+//# sourceMappingURL=ReplicationStreamStorageIds.js.map

package/dist/storage/implementation/ReplicationStreamStorageIds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReplicationStreamStorageIds.js","sourceRoot":"","sources":["../../../src/storage/implementation/ReplicationStreamStorageIds.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,MAAM,OAAO,2BAA2B;IACT;IAA7B,YAA6B,QAAmD;QAAnD,aAAQ,GAAR,QAAQ,CAA2C;IAAG,CAAC;IAEpF,IAAI,mBAAmB;QACrB,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAAC,CAAC,CAAC;IAC5F,CAAC;IAED,IAAI,iBAAiB;QACnB,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1F,CAAC;CACF"}

package/dist/storage/storage-index.d.ts

@@ -2,16 +2,25 @@ export * from './bson.js';
 export * from './BucketStorage.js';
 export * from './BucketStorageBatch.js';
 export * from './BucketStorageFactory.js';
+export * from './CheckpointChecksumInvalidatedError.js';
 export * from './ChecksumCache.js';
-export * from './PersistedSyncRulesContent.js';
+export * from './ParsedSyncConfigSet.js';
+export * from './PersistedReplicationStream.js';
+export * from './PersistedSyncConfigContent.js';
+export * from './PersistedSyncConfigStatus.js';
 export * from './ReplicationEventPayload.js';
 export * from './ReplicationLock.js';
 export * from './ReportStorage.js';
 export * from './SourceEntity.js';
 export * from './SourceTable.js';
+export * from './SourceTableReconciler.js';
 export * from './storage-metrics.js';
 export * from './StorageEngine.js';
 export * from './StorageProvider.js';
 export * from './StorageVersionConfig.js';
 export * from './SyncRulesBucketStorage.js';
 export * from './WriteCheckpointAPI.js';
+export * from './implementation/BucketDefinitionMapping.js';
+export * from './implementation/IncrementalReprocessingCompatibility.js';
+export * from './implementation/IncrementalReprocessingSyncConfigLog.js';
+export * from './implementation/ReplicationStreamStorageIds.js';

package/dist/storage/storage-index.js

@@ -2,17 +2,26 @@ export * from './bson.js';
 export * from './BucketStorage.js';
 export * from './BucketStorageBatch.js';
 export * from './BucketStorageFactory.js';
+export * from './CheckpointChecksumInvalidatedError.js';
 export * from './ChecksumCache.js';
-export * from './PersistedSyncRulesContent.js';
+export * from './ParsedSyncConfigSet.js';
+export * from './PersistedReplicationStream.js';
+export * from './PersistedSyncConfigContent.js';
+export * from './PersistedSyncConfigStatus.js';
 export * from './ReplicationEventPayload.js';
 export * from './ReplicationLock.js';
 export * from './ReportStorage.js';
 export * from './SourceEntity.js';
 export * from './SourceTable.js';
+export * from './SourceTableReconciler.js';
 export * from './storage-metrics.js';
 export * from './StorageEngine.js';
 export * from './StorageProvider.js';
 export * from './StorageVersionConfig.js';
 export * from './SyncRulesBucketStorage.js';
 export * from './WriteCheckpointAPI.js';
+export * from './implementation/BucketDefinitionMapping.js';
+export * from './implementation/IncrementalReprocessingCompatibility.js';
+export * from './implementation/IncrementalReprocessingSyncConfigLog.js';
+export * from './implementation/ReplicationStreamStorageIds.js';
 //# sourceMappingURL=storage-index.js.map

package/dist/storage/storage-index.js.map

@@ -1 +1 @@
-{"version":3,"file":"storage-index.js","sourceRoot":"","sources":["../../src/storage/storage-index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oBAAoB,CAAC;AACnC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"storage-index.js","sourceRoot":"","sources":["../../src/storage/storage-index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yCAAyC,CAAC;AACxD,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC;AAChD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AAExC,cAAc,6CAA6C,CAAC;AAC5D,cAAc,0DAA0D,CAAC;AACzE,cAAc,0DAA0D,CAAC;AACzE,cAAc,iDAAiD,CAAC"}

package/dist/storage/storage-metrics.js

@@ -6,50 +6,166 @@ export function createCoreStorageMetrics(engine) {
         description: 'Size of current data stored in PowerSync',
         unit: 'bytes'
     });
+    engine.createObservableGauge({
+        name: StorageMetric.ATTRIBUTED_SOURCE_RECORDS_BYTES,
+        description: 'Size of current data stored in PowerSync by sync config',
+        unit: 'bytes'
+    });
     engine.createObservableGauge({
         name: StorageMetric.OPERATION_SIZE_BYTES,
         description: 'Size of operations stored in PowerSync',
         unit: 'bytes'
     });
+    engine.createObservableGauge({
+        name: StorageMetric.ATTRIBUTED_BUCKET_DATA_BYTES,
+        description: 'Size of operations stored in PowerSync by sync config',
+        unit: 'bytes'
+    });
     engine.createObservableGauge({
         name: StorageMetric.PARAMETER_SIZE_BYTES,
         description: 'Size of parameter data stored in PowerSync',
         unit: 'bytes'
     });
+    engine.createObservableGauge({
+        name: StorageMetric.ATTRIBUTED_PARAMETER_INDEXES_BYTES,
+        description: 'Size of parameter data stored in PowerSync by sync config',
+        unit: 'bytes'
+    });
+    engine.createObservableGauge({
+        name: StorageMetric.OBJECT_STORAGE_SIZE_BYTES,
+        description: 'Size of active object-storage references stored in PowerSync',
+        unit: 'bytes'
+    });
+    engine.createObservableGauge({
+        name: StorageMetric.ATTRIBUTED_OBJECT_STORAGE_BYTES,
+        description: 'Size of active object-storage references by sync config',
+        unit: 'bytes'
+    });
 }
 export function initializeCoreStorageMetrics(engine, storage) {
     const replication_storage_size_bytes = engine.getObservableGauge(StorageMetric.REPLICATION_SIZE_BYTES);
+    const attributed_source_records_bytes = engine.getObservableGauge(StorageMetric.ATTRIBUTED_SOURCE_RECORDS_BYTES);
     const operation_storage_size_bytes = engine.getObservableGauge(StorageMetric.OPERATION_SIZE_BYTES);
+    const attributed_bucket_data_bytes = engine.getObservableGauge(StorageMetric.ATTRIBUTED_BUCKET_DATA_BYTES);
     const parameter_storage_size_bytes = engine.getObservableGauge(StorageMetric.PARAMETER_SIZE_BYTES);
+    const attributed_parameter_indexes_bytes = engine.getObservableGauge(StorageMetric.ATTRIBUTED_PARAMETER_INDEXES_BYTES);
+    const object_storage_size_bytes = engine.getObservableGauge(StorageMetric.OBJECT_STORAGE_SIZE_BYTES);
+    const attributed_object_storage_bytes = engine.getObservableGauge(StorageMetric.ATTRIBUTED_OBJECT_STORAGE_BYTES);
     const MINIMUM_INTERVAL = 60_000;
+    /**
+     * How long a sync config that is no longer present keeps being reported as zero.
+     *
+     * This must comfortably exceed the longest metric export interval, so that every configured
+     * reader observes the zero at least once. The OTLP reader exports every 5 minutes.
+     */
+    const RETIRED_SYNC_CONFIG_INTERVAL = 15 * 60_000;
+    /**
+     * Attribute sets reported at least once, along with the last time each was present in the
+     * storage metrics.
+     *
+     * These gauges are exported with cumulative temporality, which means the metrics SDK keeps
+     * re-exporting the last reported value for every attribute set it has seen, also after we stop
+     * reporting that set. Without this, a sync config that has since been pruned would keep
+     * reporting its last non-zero size indefinitely, so sums over these gauges would drift upwards
+     * permanently. Reporting zero for a while instead leaves the SDK carrying a zero forward.
+     */
+    const reportedSyncConfigs = new Map();
+    const syncConfigKey = (attributes) => JSON.stringify([attributes.sync_config_id, attributes.sync_config_state, attributes.version_label]);
+    const syncConfigAttributes = (syncConfig) => ({
+        sync_config_id: syncConfig.sync_config_id,
+        sync_config_state: syncConfig.sync_config_state,
+        ...(syncConfig.version_label == null ? {} : { version_label: syncConfig.version_label })
+    });
+    const trackSyncConfigs = (metrics) => {
+        if (metrics == null) {
+            // Failed to read the metrics - this says nothing about which sync configs still exist.
+            return;
+        }
+        const now = Date.now();
+        for (const syncConfig of metrics.sync_config_metrics ?? []) {
+            const attributes = syncConfigAttributes(syncConfig);
+            reportedSyncConfigs.set(syncConfigKey(attributes), { attributes, lastSeen: now });
+        }
+        for (const [key, entry] of reportedSyncConfigs) {
+            if (now - entry.lastSeen > RETIRED_SYNC_CONFIG_INTERVAL) {
+                reportedSyncConfigs.delete(key);
+            }
+        }
+    };
     let cachedRequest = undefined;
     let cacheTimestamp = 0;
     const getMetrics = () => {
         if (!cachedRequest || Date.now() - cacheTimestamp > MINIMUM_INTERVAL) {
-            cachedRequest = storage.getStorageMetrics().catch((e) => {
+            cachedRequest = storage
+                .getStorageMetrics()
+                .catch((e) => {
                 logger.error(`Failed to get storage metrics`, e);
                 return null;
+            })
+                .then((metrics) => {
+                trackSyncConfigs(metrics);
+                return metrics;
             });
             cacheTimestamp = Date.now();
         }
         return cachedRequest;
     };
+    function nonNegative(value) {
+        return value == null ? value : Math.max(0, value);
+    }
+    const observationsForSyncConfigs = (metrics, key) => {
+        const observations = [];
+        const present = new Set();
+        for (const syncConfig of metrics.sync_config_metrics ?? []) {
+            const attributes = syncConfigAttributes(syncConfig);
+            present.add(syncConfigKey(attributes));
+            observations.push({ value: nonNegative(syncConfig[key]), attributes });
+        }
+        for (const entry of reportedSyncConfigs.values()) {
+            if (!present.has(syncConfigKey(entry.attributes))) {
+                observations.push({ value: 0, attributes: entry.attributes });
+            }
+        }
+        return observations;
+    };
     replication_storage_size_bytes.setValueProvider(async () => {
+        const metrics = await getMetrics();
+        return nonNegative(metrics?.replication_size_bytes);
+    });
+    attributed_source_records_bytes.setValueProvider(async () => {
         const metrics = await getMetrics();
         if (metrics) {
-            return metrics.replication_size_bytes;
+            return observationsForSyncConfigs(metrics, 'attributed_source_records_bytes');
         }
     });
     operation_storage_size_bytes.setValueProvider(async () => {
+        const metrics = await getMetrics();
+        return nonNegative(metrics?.operations_size_bytes);
+    });
+    attributed_bucket_data_bytes.setValueProvider(async () => {
         const metrics = await getMetrics();
         if (metrics) {
-            return metrics.operations_size_bytes;
+            return observationsForSyncConfigs(metrics, 'attributed_bucket_data_bytes');
         }
     });
     parameter_storage_size_bytes.setValueProvider(async () => {
+        const metrics = await getMetrics();
+        return nonNegative(metrics?.parameters_size_bytes);
+    });
+    attributed_parameter_indexes_bytes.setValueProvider(async () => {
+        const metrics = await getMetrics();
+        if (metrics) {
+            return observationsForSyncConfigs(metrics, 'attributed_parameter_indexes_bytes');
+        }
+    });
+    object_storage_size_bytes.setValueProvider(async () => {
+        const metrics = await getMetrics();
+        return nonNegative(metrics?.object_storage_size_bytes);
+    });
+    attributed_object_storage_bytes.setValueProvider(async () => {
         const metrics = await getMetrics();
         if (metrics) {
-            return metrics.parameters_size_bytes;
+            return observationsForSyncConfigs(metrics, 'attributed_object_storage_bytes');
         }
     });
 }

package/dist/storage/storage-metrics.js.map

@@ -1 +1 @@
-{"version":3,"file":"storage-metrics.js","sourceRoot":"","sources":["../../src/storage/storage-metrics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,mCAAmC,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAIzD,MAAM,UAAU,wBAAwB,CAAC,MAAqB;IAC5D,MAAM,CAAC,qBAAqB,CAAC;QAC3B,IAAI,EAAE,aAAa,CAAC,sBAAsB;QAC1C,WAAW,EAAE,0CAA0C;QACvD,IAAI,EAAE,OAAO;KACd,CAAC,CAAC;IAEH,MAAM,CAAC,qBAAqB,CAAC;QAC3B,IAAI,EAAE,aAAa,CAAC,oBAAoB;QACxC,WAAW,EAAE,wCAAwC;QACrD,IAAI,EAAE,OAAO;KACd,CAAC,CAAC;IAEH,MAAM,CAAC,qBAAqB,CAAC;QAC3B,IAAI,EAAE,aAAa,CAAC,oBAAoB;QACxC,WAAW,EAAE,4CAA4C;QACzD,IAAI,EAAE,OAAO;KACd,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,MAAqB,EAAE,OAA6B;IAC/F,MAAM,8BAA8B,GAAG,MAAM,CAAC,kBAAkB,CAAC,aAAa,CAAC,sBAAsB,CAAC,CAAC;IACvG,MAAM,4BAA4B,GAAG,MAAM,CAAC,kBAAkB,CAAC,aAAa,CAAC,oBAAoB,CAAC,CAAC;IACnG,MAAM,4BAA4B,GAAG,MAAM,CAAC,kBAAkB,CAAC,aAAa,CAAC,oBAAoB,CAAC,CAAC;IAEnG,MAAM,gBAAgB,GAAG,MAAM,CAAC;IAEhC,IAAI,aAAa,GAA+C,SAAS,CAAC;IAC1E,IAAI,cAAc,GAAG,CAAC,CAAC;IAEvB,MAAM,UAAU,GAAG,GAAG,EAAE;QACtB,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,cAAc,GAAG,gBAAgB,EAAE,CAAC;YACrE,aAAa,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE;gBACtD,MAAM,CAAC,KAAK,CAAC,+BAA+B,EAAE,CAAC,CAAC,CAAC;gBACjD,OAAO,IAAI,CAAC;YACd,CAAC,CAAC,CAAC;YACH,cAAc,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC9B,CAAC;QACD,OAAO,aAAa,CAAC;IACvB,CAAC,CAAC;IAEF,8BAA8B,CAAC,gBAAgB,CAAC,KAAK,IAAI,EAAE;QACzD,MAAM,OAAO,GAAG,MAAM,UAAU,EAAE,CAAC;QACnC,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,OAAO,CAAC,sBAAsB,CAAC;QACxC,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,4BAA4B,CAAC,gBAAgB,CAAC,KAAK,IAAI,EAAE;QACvD,MAAM,OAAO,GAAG,MAAM,UAAU,EAAE,CAAC;QACnC,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,OAAO,CAAC,qBAAqB,CAAC;QACvC,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,4BAA4B,CAAC,gBAAgB,CAAC,KAAK,IAAI,EAAE;QACvD,MAAM,OAAO,GAAG,MAAM,UAAU,EAAE,CAAC;QACnC,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,OAAO,CAAC,qBAAqB,CAAC;QACvC,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"storage-metrics.js","sourceRoot":"","sources":["../../src/storage/storage-metrics.ts"],"names":[],"mappings":"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"}

package/dist/sync/BucketChecksumState.d.ts

@@ -3,7 +3,9 @@ import * as storage from '../storage/storage-index.js';
 import * as util from '../util/util-index.js';
 import { Logger } from '@powersync/lib-services-framework';
 import { JwtPayload } from '../auth/JwtPayload.js';
+import { PerformanceTracer } from '../tracing/PerformanceTracer.js';
 import { SyncContext } from './SyncContext.js';
+export type SyncCheckpointTraceCategory = 'checkpoint' | 'parameters' | 'checksum' | 'acquiring_lock' | 'bucket_data' | 'sending' | 's3';
 export interface BucketChecksumStateOptions {
     syncContext: SyncContext;
     bucketStorage: BucketChecksumStateStorage;
@@ -35,6 +37,12 @@ export declare class BucketChecksumState {
      */
     private lastChecksums;
     private lastWriteCheckpoint;
+    /**
+     * The next storage checkpoint diff may be relative to a checksum-invalidated
+     * checkpoint that was never sent to the client. Re-check every bucket once
+     * instead of applying that diff to the last client-visible checksums.
+     */
+    private forceFullChecksumForNextCheckpoint;
     /**
      * Once we've sent the first full checkpoint line including all {@link util.Checkpoint.streams} that the user is
      * subscribed to, we keep an index of the stream names to their index in that array.
@@ -54,6 +62,7 @@ export declare class BucketChecksumState {
     private pendingBucketDownloads;
     private readonly logger;
     constructor(options: BucketChecksumStateOptions);
+    invalidateChecksumBaseline(): void;
     /**
      * Build a new checkpoint line for an underlying storage checkpoint update if any buckets have changed.
      *
@@ -65,7 +74,7 @@ export declare class BucketChecksumState {
      * @param next The updated checkpoint
      * @returns A {@link CheckpointLine} if any of the buckets watched by this connected was updated, or otherwise `null`.
      */
-    buildNextCheckpointLine(next: storage.StorageCheckpointUpdate): Promise<CheckpointLine | null>;
+    buildNextCheckpointLine(next: storage.StorageCheckpointUpdate, tracer?: PerformanceTracer<SyncCheckpointTraceCategory>): Promise<CheckpointLine | null>;
 }
 declare const INVALIDATE_ALL_BUCKETS: unique symbol;
 export interface CheckpointUpdate {
@@ -111,7 +120,7 @@ export declare class BucketParameterState {
      */
     translateResolvedBucket(description: ResolvedBucket, lookupIndex: Map<string, number>): util.ClientBucketDescription;
     isSubscribedToStream(desc: BucketSource): boolean;
-    getCheckpointUpdate(checkpoint: storage.StorageCheckpointUpdate): Promise<CheckpointUpdate>;
+    getCheckpointUpdate(checkpoint: storage.StorageCheckpointUpdate, tracer: PerformanceTracer<SyncCheckpointTraceCategory>): Promise<CheckpointUpdate>;
     /**
      * For static buckets, we can keep track of which buckets have been updated.
      */
@@ -124,6 +133,7 @@ export declare class BucketParameterState {
 export interface CheckpointLine {
     checkpointLine: util.StreamingSyncCheckpointDiff | util.StreamingSyncCheckpoint;
     bucketsToFetch: ResolvedBucket[];
+    bucketDataRequestHint: storage.BucketRequestHint;
     /**
      * Call when a checkpoint line is being sent to a client, to update the internal state.
      */

package/dist/sync/BucketChecksumState.js

@@ -1,7 +1,8 @@
-import { mergeBuckets, RequestParameters } from '@powersync/service-sync-rules';
+import { BucketSourceType, mergeBuckets, RequestParameters } from '@powersync/service-sync-rules';
 import * as util from '../util/util-index.js';
 import { logger as defaultLogger, ErrorCode, ServiceAssertionError, ServiceError } from '@powersync/lib-services-framework';
 import { ParameterSetLimitExceededError } from '../storage/storage-index.js';
+import { PerformanceTracer } from '../tracing/PerformanceTracer.js';
 import { getIntersection, hasIntersection } from './util.js';
 /**
  * Represents the state of the checksums and data for a specific connection.
@@ -23,6 +24,12 @@ export class BucketChecksumState {
      */
     lastChecksums = null;
     lastWriteCheckpoint = null;
+    /**
+     * The next storage checkpoint diff may be relative to a checksum-invalidated
+     * checkpoint that was never sent to the client. Re-check every bucket once
+     * instead of applying that diff to the last client-visible checksums.
+     */
+    forceFullChecksumForNextCheckpoint = false;
     /**
      * Once we've sent the first full checkpoint line including all {@link util.Checkpoint.streams} that the user is
      * subscribed to, we keep an index of the stream names to their index in that array.
@@ -51,6 +58,9 @@ export class BucketChecksumState {
             this.bucketDataPositions.set(name, { start_op_id: BigInt(start) });
         }
     }
+    invalidateChecksumBaseline() {
+        this.forceFullChecksumForNextCheckpoint = true;
+    }
     /**
      * Build a new checkpoint line for an underlying storage checkpoint update if any buckets have changed.
      *
@@ -62,12 +72,14 @@ export class BucketChecksumState {
      * @param next The updated checkpoint
      * @returns A {@link CheckpointLine} if any of the buckets watched by this connected was updated, or otherwise `null`.
      */
-    async buildNextCheckpointLine(next) {
+    async buildNextCheckpointLine(next, tracer) {
+        tracer ??= new PerformanceTracer(`sync checkpoint ${next.base.checkpoint}`);
         const { writeCheckpoint, base } = next;
         const userIdForLogs = this.parameterState.syncParams.userId;
         const storage = this.bucketStorage;
-        const update = await this.parameterState.getCheckpointUpdate(next);
+        const update = await this.parameterState.getCheckpointUpdate(next, tracer);
         const { buckets: allBuckets, updatedBuckets, usedParameterResults } = update;
+        const forceFullChecksum = this.forceFullChecksumForNextCheckpoint;
         /** Set of all buckets in this checkpoint. */
         const bucketDescriptionMap = new Map(allBuckets.map((b) => [b.bucket, b]));
         if (bucketDescriptionMap.size > this.context.maxBuckets) {
@@ -85,19 +97,22 @@ export class BucketChecksumState {
                 const count = bucketsByDefinition.get(definition) ?? 0;
                 bucketsByDefinition.set(definition, count + 1);
             }
-            const breakdown = formatBucketDefinitionBreakdown(bucketsByDefinition);
+            // Only 1 type is allowed per sync config
+            const bucketSourceType = this.parameterState.syncRules.bucketSourceDefinitions[0].type;
+            const breakdown = formatBucketDefinitionBreakdown(bucketsByDefinition, bucketSourceType);
             errorMessage += breakdown.message;
             logData.buckets_by_definition = breakdown.countsByDefinition;
             this.logger.error(errorMessage, logData);
             throw error;
         }
         let checksumMap;
-        if (updatedBuckets != INVALIDATE_ALL_BUCKETS) {
+        if (!forceFullChecksum && updatedBuckets != INVALIDATE_ALL_BUCKETS) {
             if (this.lastChecksums == null) {
                 throw new ServiceAssertionError(`Bucket diff received without existing checksums`);
             }
             // Re-check updated buckets only
             let checksumLookups = [];
+            let hasNewBucket = false;
             let newChecksums = new Map();
             for (let desc of bucketDescriptionMap.values()) {
                 if (!updatedBuckets.has(desc.bucket)) {
@@ -111,10 +126,14 @@ export class BucketChecksumState {
                 }
                 else {
                     checksumLookups.push({ bucket: desc.bucket, source: desc.source });
+                    hasNewBucket ||= !this.lastChecksums.has(desc.bucket);
                 }
             }
             if (checksumLookups.length > 0) {
-                let updatedChecksums = await storage.getChecksums(base.checkpoint, checksumLookups);
+                const requestHint = hasNewBucket ? 'bulk' : 'incremental';
+                let updatedChecksums;
+                using _ = tracer.span('checksum');
+                updatedChecksums = await storage.getChecksums(base, checksumLookups, { requestHint });
                 for (let [bucket, value] of updatedChecksums.entries()) {
                     newChecksums.set(bucket, value);
                 }
@@ -123,11 +142,20 @@ export class BucketChecksumState {
         }
         else {
             // Re-check all buckets
-            const bucketList = [...bucketDescriptionMap.values()].map((b) => ({ bucket: b.bucket, source: b.source }));
-            checksumMap = await storage.getChecksums(base.checkpoint, bucketList);
+            const hasNewBucket = this.lastChecksums == null ||
+                [...bucketDescriptionMap.values()].some((b) => !this.lastChecksums.has(b.bucket));
+            const requestHint = hasNewBucket ? 'bulk' : 'incremental';
+            const bucketList = [...bucketDescriptionMap.values()].map((b) => ({
+                bucket: b.bucket,
+                source: b.source
+            }));
+            using _ = tracer.span('checksum');
+            checksumMap = await storage.getChecksums(base, bucketList, { requestHint });
         }
         // Subset of buckets for which there may be new data in this batch.
         let bucketsToFetch;
+        let bucketDataRequestHint;
+        const newBucketDownloads = new Set();
         let checkpointLine;
         // Log function that is deferred until the checkpoint line is sent to the client.
         let deferredLog;
@@ -140,6 +168,9 @@ export class BucketChecksumState {
                 diff.removedBuckets.length == 0 &&
                 diff.updatedBuckets.length == 0) {
                 // No changes - don't send anything to the client
+                if (forceFullChecksum) {
+                    this.forceFullChecksumForNextCheckpoint = false;
+                }
                 return null;
             }
             let generateBucketsToFetch = new Set();
@@ -160,6 +191,12 @@ export class BucketChecksumState {
             bucketsToFetch = [...generateBucketsToFetch].map((b) => {
                 return bucketDescriptionMap.get(b);
             });
+            for (const bucket of diff.updatedBuckets) {
+                if (!this.lastChecksums.has(bucket.bucket)) {
+                    newBucketDownloads.add(bucket.bucket);
+                }
+            }
+            bucketDataRequestHint = newBucketDownloads.size > 0 ? 'bulk' : 'incremental';
             deferredLog = () => {
                 let message = `Updated checkpoint: ${base.checkpoint} | `;
                 message += `write: ${writeCheckpoint} | `;
@@ -197,6 +234,10 @@ export class BucketChecksumState {
                 }, usedParameterResults);
             };
             bucketsToFetch = allBuckets;
+            for (const bucket of bucketsToFetch) {
+                newBucketDownloads.add(bucket.bucket);
+            }
+            bucketDataRequestHint = 'bulk';
             const subscriptions = [];
             const streamNameToIndex = new Map();
             this.streamNameToIndex = streamNameToIndex;
@@ -230,6 +271,7 @@ export class BucketChecksumState {
         return {
             checkpointLine,
             bucketsToFetch,
+            bucketDataRequestHint,
             advance: () => {
                 hasAdvanced = true;
                 // bucketDataPositions must be updated in-place - it represents the current state of
@@ -261,6 +303,9 @@ export class BucketChecksumState {
                 this.lastChecksums = checksumMap;
                 this.lastWriteCheckpoint = writeCheckpoint;
                 this.pendingBucketDownloads = pendingBucketDownloads;
+                if (forceFullChecksum) {
+                    this.forceFullChecksumForNextCheckpoint = false;
+                }
                 deferredLog();
             },
             getFilteredBucketPositions: (buckets) => {
@@ -383,12 +428,12 @@ export class BucketParameterState {
     isSubscribedToStream(desc) {
         return (desc.subscribedToByDefault && this.includeDefaultStreams) || this.subscribedStreamNames.has(desc.name);
     }
-    async getCheckpointUpdate(checkpoint) {
+    async getCheckpointUpdate(checkpoint, tracer) {
         const querier = this.querier;
         let update;
         if (querier.hasDynamicBuckets) {
             try {
-                update = await this.getCheckpointUpdateDynamic(checkpoint);
+                update = await this.getCheckpointUpdateDynamic(checkpoint, tracer);
             }
             catch (e) {
                 if (e instanceof ParameterSetLimitExceededError) {
@@ -441,7 +486,7 @@ export class BucketParameterState {
     /**
      * For dynamic buckets, we need to re-query the list of buckets every time.
      */
-    async getCheckpointUpdateDynamic(checkpoint) {
+    async getCheckpointUpdateDynamic(checkpoint, tracer) {
         const querier = this.querier;
         const staticBuckets = this.staticBuckets.values();
         const update = checkpoint.update;
@@ -490,6 +535,7 @@ export class BucketParameterState {
                         recordedLookups.add(lookup.serializedRepresentation);
                     }
                     try {
+                        using _ = tracer.span('parameters', definition);
                         const results = await checkpoint.base.getParameterSets(lookups, remainingBudget);
                         const numRows = results.reduce((a, b) => a + b.rows.length, 0);
                         lookupLog.push({ definition, resultsOrLimit: numRows, didExceedLimit: false });
@@ -555,25 +601,27 @@ function logCheckpoint(logger, message, logData, totalParamResults) {
     logger.info(message, logData);
 }
 /**
- * Format a breakdown of dynamic bucket by sync stream definition.
+ * Format a breakdown of dynamic buckets by sync stream or legacy bucket definition.
  *
- * Sorts definitions by count (descending), includes the top 10, and returns both the
+ * Sorts definitions by count (descending), includes the top 100, and returns both the
  * formatted message string and the counts record suitable for structured log data.
  */
-function formatBucketDefinitionBreakdown(bucketsByDefinition) {
-    // Sort definitions by count (descending) and take top 10
+function formatBucketDefinitionBreakdown(bucketsByDefinition, bucketSourceType) {
+    const maxLoggedDefinitions = 100;
+    // Sort definitions by count (descending) and take the largest entries.
     const allSorted = Array.from(bucketsByDefinition.entries()).sort((a, b) => b[1] - a[1]);
-    const sortedDefinitions = allSorted.slice(0, 10);
-    let message = '\Buckets by definition:';
+    const sortedDefinitions = allSorted.slice(0, maxLoggedDefinitions);
+    const sourceLabel = bucketSourceType == BucketSourceType.SYNC_STREAM ? 'sync stream' : 'bucket definition';
+    let message = `\nBuckets by ${sourceLabel}:`;
     const countsByDefinition = {};
     for (const [definition, count] of sortedDefinitions) {
         message += `\n  ${definition}: ${count}`;
         countsByDefinition[definition] = count;
     }
-    if (allSorted.length > 10) {
-        const remainingResults = allSorted.slice(10).reduce((sum, [, count]) => sum + count, 0);
-        const remainingDefinitions = allSorted.length - 10;
-        message += `\n  ... and ${remainingResults} more results from ${remainingDefinitions} definitions`;
+    if (allSorted.length > maxLoggedDefinitions) {
+        const remainingResults = allSorted.slice(maxLoggedDefinitions).reduce((sum, [, count]) => sum + count, 0);
+        const remainingDefinitions = allSorted.length - maxLoggedDefinitions;
+        message += `\n  ... and ${remainingResults} more buckets from ${remainingDefinitions} ${sourceLabel}s`;
     }
     return { message, countsByDefinition };
 }