@powersync/service-core 1.19.2 → 1.20.0

package/dist/storage/BucketStorageFactory.d.ts

@@ -1,9 +1,10 @@
-import { ObserverClient } from '@powersync/lib-services-framework';
+import { BaseObserver } from '@powersync/lib-services-framework';
 import { ParseSyncRulesOptions, PersistedSyncRules, PersistedSyncRulesContent } from './PersistedSyncRulesContent.js';
 import { ReplicationEventPayload } from './ReplicationEventPayload.js';
 import { ReplicationLock } from './ReplicationLock.js';
 import { SyncRulesBucketStorage } from './SyncRulesBucketStorage.js';
 import { ReportStorage } from './ReportStorage.js';
+import { SerializedCompatibilityContext, SyncConfig } from '@powersync/service-sync-rules';
 /**
  * Represents a configured storage provider.
  *
@@ -12,7 +13,7 @@ import { ReportStorage } from './ReportStorage.js';
  *
  * Storage APIs for a specific copy of sync rules are provided by the `SyncRulesBucketStorage` instances.
  */
-export interface BucketStorageFactory extends ObserverClient<BucketStorageFactoryListener>, AsyncDisposable {
+export declare abstract class BucketStorageFactory extends BaseObserver<BucketStorageFactoryListener> implements AsyncDisposable {
     /**
      * Update sync rules from configuration, if changed.
      */
@@ -24,11 +25,11 @@ export interface BucketStorageFactory extends ObserverClient<BucketStorageFactor
     /**
      * Get a storage instance to query sync data for specific sync rules.
      */
-    getInstance(syncRules: PersistedSyncRulesContent, options?: GetIntanceOptions): SyncRulesBucketStorage;
+    abstract getInstance(syncRules: PersistedSyncRulesContent, options?: GetIntanceOptions): SyncRulesBucketStorage;
     /**
      * Deploy new sync rules.
      */
-    updateSyncRules(options: UpdateSyncRulesOptions): Promise<PersistedSyncRulesContent>;
+    abstract updateSyncRules(options: UpdateSyncRulesOptions): Promise<PersistedSyncRulesContent>;
     /**
      * Indicate that a slot was removed, and we should re-sync by creating
      * a new sync rules instance.
@@ -39,7 +40,7 @@ export interface BucketStorageFactory extends ObserverClient<BucketStorageFactor
      *
      * Replication should be restarted after this.
      */
-    restartReplication(sync_rules_group_id: number): Promise<void>;
+    abstract restartReplication(sync_rules_group_id: number): Promise<void>;
     /**
      * Get the sync rules used for querying.
      */
@@ -47,7 +48,7 @@ export interface BucketStorageFactory extends ObserverClient<BucketStorageFactor
     /**
      * Get the sync rules used for querying.
      */
-    getActiveSyncRulesContent(): Promise<PersistedSyncRulesContent | null>;
+    abstract getActiveSyncRulesContent(): Promise<PersistedSyncRulesContent | null>;
     /**
      * Get the sync rules that will be active next once done with initial replicatino.
      */
@@ -55,31 +56,32 @@ export interface BucketStorageFactory extends ObserverClient<BucketStorageFactor
     /**
      * Get the sync rules that will be active next once done with initial replicatino.
      */
-    getNextSyncRulesContent(): Promise<PersistedSyncRulesContent | null>;
+    abstract getNextSyncRulesContent(): Promise<PersistedSyncRulesContent | null>;
     /**
      * Get all sync rules currently replicating. Typically this is the "active" and "next" sync rules.
      */
-    getReplicatingSyncRules(): Promise<PersistedSyncRulesContent[]>;
+    abstract getReplicatingSyncRules(): Promise<PersistedSyncRulesContent[]>;
     /**
      * Get all sync rules stopped but not terminated yet.
      */
-    getStoppedSyncRules(): Promise<PersistedSyncRulesContent[]>;
+    abstract getStoppedSyncRules(): Promise<PersistedSyncRulesContent[]>;
     /**
      * Get the active storage instance.
      */
-    getActiveStorage(): Promise<SyncRulesBucketStorage | null>;
+    abstract getActiveStorage(): Promise<SyncRulesBucketStorage | null>;
     /**
      * Get storage size of active sync rules.
      */
-    getStorageMetrics(): Promise<StorageMetrics>;
+    abstract getStorageMetrics(): Promise<StorageMetrics>;
     /**
      * Get the unique identifier for this instance of Powersync
      */
-    getPowerSyncInstanceId(): Promise<string>;
+    abstract getPowerSyncInstanceId(): Promise<string>;
     /**
      * Get a unique identifier for the system used for storage.
      */
-    getSystemIdentifier(): Promise<BucketStorageSystemIdentifier>;
+    abstract getSystemIdentifier(): Promise<BucketStorageSystemIdentifier>;
+    abstract [Symbol.asyncDispose](): PromiseLike<void>;
 }
 export interface BucketStorageFactoryListener {
     syncStorageCreated: (storage: SyncRulesBucketStorage) => void;
@@ -102,10 +104,36 @@ export interface StorageMetrics {
     replication_size_bytes: number;
 }
 export interface UpdateSyncRulesOptions {
-    content: string;
+    config: {
+        yaml: string;
+        /**
+         * The serialized sync plan for the sync configuration, or `null` for configurations not using the sync stream
+         * compiler.
+         */
+        plan: SerializedSyncPlan | null;
+    };
     lock?: boolean;
-    validate?: boolean;
+    storageVersion?: number;
+}
+export interface SerializedSyncPlan {
+    /**
+     * The serialized plan, from {@link serializeSyncPlan}.
+     */
+    plan: unknown;
+    compatibility: SerializedCompatibilityContext;
+    /**
+     * Event descriptors are not currently represented in the sync plan because they don't use the sync streams compiler
+     * yet.
+     *
+     * We might revisit that in the future, but for now we store SQL text of their definitions here to be able to restore
+     * them.
+     */
+    eventDescriptors: Record<string, string[]>;
 }
+export declare function updateSyncRulesFromYaml(content: string, options?: Omit<UpdateSyncRulesOptions, 'config'> & {
+    validate?: boolean;
+}): UpdateSyncRulesOptions;
+export declare function updateSyncRulesFromConfig(parsed: SyncConfig, options?: Omit<UpdateSyncRulesOptions, 'config'>): UpdateSyncRulesOptions;
 export interface GetIntanceOptions {
     /**
      * Set to true to skip trigger any events for creating the instance.

package/dist/storage/BucketStorageFactory.js

@@ -1,2 +1,71 @@
-export {};
+import { BaseObserver, logger } from '@powersync/lib-services-framework';
+import { PrecompiledSyncConfig, serializeSyncPlan, SqlSyncRules } from '@powersync/service-sync-rules';
+/**
+ * Represents a configured storage provider.
+ *
+ * The provider can handle multiple copies of sync rules concurrently, each with their own storage.
+ * This is to handle replication of a new version of sync rules, while the old version is still active.
+ *
+ * Storage APIs for a specific copy of sync rules are provided by the `SyncRulesBucketStorage` instances.
+ */
+export class BucketStorageFactory extends BaseObserver {
+    /**
+     * Update sync rules from configuration, if changed.
+     */
+    async configureSyncRules(options) {
+        const next = await this.getNextSyncRulesContent();
+        const active = await this.getActiveSyncRulesContent();
+        if (next?.sync_rules_content == options.config.yaml) {
+            logger.info('Sync rules from configuration unchanged');
+            return { updated: false };
+        }
+        else if (next == null && active?.sync_rules_content == options.config.yaml) {
+            logger.info('Sync rules from configuration unchanged');
+            return { updated: false };
+        }
+        else {
+            logger.info('Sync rules updated from configuration');
+            const persisted_sync_rules = await this.updateSyncRules(options);
+            return { updated: true, persisted_sync_rules, lock: persisted_sync_rules.current_lock ?? undefined };
+        }
+    }
+    /**
+     * Get the sync rules used for querying.
+     */
+    async getActiveSyncRules(options) {
+        const content = await this.getActiveSyncRulesContent();
+        return content?.parsed(options) ?? null;
+    }
+    /**
+     * Get the sync rules that will be active next once done with initial replicatino.
+     */
+    async getNextSyncRules(options) {
+        const content = await this.getNextSyncRulesContent();
+        return content?.parsed(options) ?? null;
+    }
+}
+export function updateSyncRulesFromYaml(content, options) {
+    const { config } = SqlSyncRules.fromYaml(content, {
+        // No schema-based validation at this point
+        schema: undefined,
+        defaultSchema: 'not_applicable', // Not needed for validation
+        throwOnError: options?.validate ?? false
+    });
+    return updateSyncRulesFromConfig(config, options);
+}
+export function updateSyncRulesFromConfig(parsed, options) {
+    let plan = null;
+    if (parsed instanceof PrecompiledSyncConfig) {
+        const eventDescriptors = {};
+        for (const event of parsed.eventDescriptors) {
+            eventDescriptors[event.name] = event.sourceQueries.map((q) => q.sql);
+        }
+        plan = {
+            compatibility: parsed.compatibility.serialize(),
+            plan: serializeSyncPlan(parsed.plan),
+            eventDescriptors
+        };
+    }
+    return { config: { yaml: parsed.content, plan }, ...options };
+}
 //# sourceMappingURL=BucketStorageFactory.js.map

package/dist/storage/BucketStorageFactory.js.map

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

package/dist/storage/PersistedSyncRulesContent.d.ts

@@ -1,23 +1,49 @@
 import { HydratedSyncRules, SyncConfigWithErrors } from '@powersync/service-sync-rules';
 import { ReplicationLock } from './ReplicationLock.js';
+import { StorageVersionConfig } from './StorageVersionConfig.js';
+import { SerializedSyncPlan, UpdateSyncRulesOptions } from './BucketStorageFactory.js';
 export interface ParseSyncRulesOptions {
     defaultSchema: string;
 }
-export interface PersistedSyncRulesContent {
+export interface PersistedSyncRulesContentData {
     readonly id: number;
     readonly sync_rules_content: string;
+    readonly compiled_plan: SerializedSyncPlan | null;
     readonly slot_name: string;
     /**
      * True if this is the "active" copy of the sync rules.
      */
     readonly active: boolean;
+    readonly storageVersion: number;
     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;
+}
+export declare abstract class PersistedSyncRulesContent implements PersistedSyncRulesContentData {
+    readonly id: number;
+    readonly sync_rules_content: string;
+    readonly compiled_plan: SerializedSyncPlan | null;
+    readonly slot_name: string;
+    readonly active: boolean;
+    readonly storageVersion: number;
+    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;
+    abstract readonly current_lock: ReplicationLock | null;
+    constructor(data: PersistedSyncRulesContentData);
+    /**
+     * Load the storage config.
+     *
+     * This may throw if the persisted storage version is not supported.
+     */
+    getStorageConfig(): StorageVersionConfig;
     parsed(options: ParseSyncRulesOptions): PersistedSyncRules;
-    lock(): Promise<ReplicationLock>;
+    asUpdateOptions(options?: Omit<UpdateSyncRulesOptions, 'config'>): UpdateSyncRulesOptions;
+    abstract lock(): Promise<ReplicationLock>;
 }
 export interface PersistedSyncRules {
     readonly id: number;

package/dist/storage/PersistedSyncRulesContent.js

@@ -1,2 +1,80 @@
-export {};
+import { CompatibilityContext, CompatibilityOption, DEFAULT_HYDRATION_STATE, deserializeSyncPlan, javaScriptExpressionEngine, PrecompiledSyncConfig, SqlEventDescriptor, SqlSyncRules, versionedHydrationState } from '@powersync/service-sync-rules';
+import { STORAGE_VERSION_CONFIG } from './StorageVersionConfig.js';
+import { ErrorCode, ServiceError } from '@powersync/lib-services-framework';
+export class PersistedSyncRulesContent {
+    id;
+    sync_rules_content;
+    compiled_plan;
+    slot_name;
+    active;
+    storageVersion;
+    last_checkpoint_lsn;
+    last_fatal_error;
+    last_fatal_error_ts;
+    last_keepalive_ts;
+    last_checkpoint_ts;
+    constructor(data) {
+        Object.assign(this, data);
+    }
+    /**
+     * Load the storage config.
+     *
+     * This may throw if the persisted storage version is not supported.
+     */
+    getStorageConfig() {
+        const storageConfig = STORAGE_VERSION_CONFIG[this.storageVersion];
+        if (storageConfig == null) {
+            throw new ServiceError(ErrorCode.PSYNC_S1005, `Unsupported storage version ${this.storageVersion} for sync rules ${this.id}`);
+        }
+        return storageConfig;
+    }
+    parsed(options) {
+        let hydrationState;
+        // Do we have a compiled sync plan? If so, restore from there instead of parsing everything again.
+        let config;
+        if (this.compiled_plan != null) {
+            const plan = deserializeSyncPlan(this.compiled_plan.plan);
+            const compatibility = CompatibilityContext.deserialize(this.compiled_plan.compatibility);
+            const eventDefinitions = [];
+            for (const [name, queries] of Object.entries(this.compiled_plan.eventDescriptors)) {
+                const descriptor = new SqlEventDescriptor(name, compatibility);
+                for (const query of queries) {
+                    descriptor.addSourceQuery(query, options);
+                }
+                eventDefinitions.push(descriptor);
+            }
+            const precompiled = new PrecompiledSyncConfig(plan, compatibility, eventDefinitions, {
+                defaultSchema: options.defaultSchema,
+                engine: javaScriptExpressionEngine(compatibility),
+                sourceText: this.sync_rules_content
+            });
+            config = { config: precompiled, errors: [] };
+        }
+        else {
+            config = SqlSyncRules.fromYaml(this.sync_rules_content, options);
+        }
+        const storageConfig = this.getStorageConfig();
+        if (storageConfig.versionedBuckets ||
+            config.config.compatibility.isEnabled(CompatibilityOption.versionedBucketIds)) {
+            hydrationState = versionedHydrationState(this.id);
+        }
+        else {
+            hydrationState = DEFAULT_HYDRATION_STATE;
+        }
+        return {
+            id: this.id,
+            slot_name: this.slot_name,
+            sync_rules: config,
+            hydratedSyncRules: () => {
+                return config.config.hydrate({ hydrationState });
+            }
+        };
+    }
+    asUpdateOptions(options) {
+        return {
+            config: { yaml: this.sync_rules_content, plan: this.compiled_plan },
+            ...options
+        };
+    }
+}
 //# sourceMappingURL=PersistedSyncRulesContent.js.map

package/dist/storage/PersistedSyncRulesContent.js.map

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

package/dist/storage/StorageVersionConfig.d.ts

@@ -0,0 +1,20 @@
+export interface StorageVersionConfig {
+    /**
+     * Whether versioned bucket names are automatically enabled.
+     *
+     * If this is false, bucket names may still be versioned depending on the sync config.
+     */
+    versionedBuckets: boolean;
+}
+/**
+ * Oldest supported storage version.
+ */
+export declare const LEGACY_STORAGE_VERSION = 1;
+/**
+ * Default storage version for newly persisted sync rules.
+ */
+export declare const CURRENT_STORAGE_VERSION = 2;
+/**
+ * Shared storage-version behavior across storage implementations.
+ */
+export declare const STORAGE_VERSION_CONFIG: Record<number, StorageVersionConfig | undefined>;

package/dist/storage/StorageVersionConfig.js

@@ -0,0 +1,20 @@
+/**
+ * Oldest supported storage version.
+ */
+export const LEGACY_STORAGE_VERSION = 1;
+/**
+ * Default storage version for newly persisted sync rules.
+ */
+export const CURRENT_STORAGE_VERSION = 2;
+/**
+ * Shared storage-version behavior across storage implementations.
+ */
+export const STORAGE_VERSION_CONFIG = {
+    [LEGACY_STORAGE_VERSION]: {
+        versionedBuckets: false
+    },
+    [CURRENT_STORAGE_VERSION]: {
+        versionedBuckets: true
+    }
+};
+//# sourceMappingURL=StorageVersionConfig.js.map

package/dist/storage/StorageVersionConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StorageVersionConfig.js","sourceRoot":"","sources":["../../src/storage/StorageVersionConfig.ts"],"names":[],"mappings":"AASA;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAExC;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AAEzC;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAqD;IACtF,CAAC,sBAAsB,CAAC,EAAE;QACxB,gBAAgB,EAAE,KAAK;KACxB;IACD,CAAC,uBAAuB,CAAC,EAAE;QACzB,gBAAgB,EAAE,IAAI;KACvB;CACF,CAAC"}

package/dist/storage/SyncRulesBucketStorage.d.ts

@@ -163,7 +163,8 @@ export interface CompactOptions {
      *
      * If not specified, compacts all buckets.
      *
-     * These can be individual bucket names, or bucket definition names.
+     * These must be full bucket names (e.g., "global[]", "mybucket[\"user1\"]").
+     * Bucket definition names (e.g., "global") are not supported.
      */
     compactBuckets?: string[];
     compactParameterData?: boolean;

package/dist/storage/SyncRulesBucketStorage.js.map

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

@@ -14,3 +14,4 @@ export * from './SyncRulesBucketStorage.js';
 export * from './PersistedSyncRulesContent.js';
 export * from './ReplicationLock.js';
 export * from './ReportStorage.js';
+export * from './StorageVersionConfig.js';

package/dist/storage/storage-index.js

@@ -14,4 +14,5 @@ export * from './SyncRulesBucketStorage.js';
 export * from './PersistedSyncRulesContent.js';
 export * from './ReplicationLock.js';
 export * from './ReportStorage.js';
+export * from './StorageVersionConfig.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,oBAAoB,CAAC;AACnC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,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,oBAAoB,CAAC;AACnC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC"}

package/dist/sync/BucketChecksumState.d.ts

@@ -1,8 +1,7 @@
-import { BucketDescription, BucketSource, HydratedSyncRules, RequestParameters, ResolvedBucket } from '@powersync/service-sync-rules';
+import { BucketDescription, BucketSource, HydratedSyncRules, QuerierError, RequestParameters, ResolvedBucket } from '@powersync/service-sync-rules';
 import * as storage from '../storage/storage-index.js';
 import * as util from '../util/util-index.js';
 import { Logger } from '@powersync/lib-services-framework';
-import { QuerierError } from '@powersync/service-sync-rules/src/BucketParameterQuerier.js';
 import { JwtPayload } from '../auth/JwtPayload.js';
 import { SyncContext } from './SyncContext.js';
 export interface BucketChecksumStateOptions {
@@ -80,6 +79,11 @@ export interface CheckpointUpdate {
      * If null, assume that any bucket in `buckets` may have been updated.
      */
     updatedBuckets: Set<string> | typeof INVALIDATE_ALL_BUCKETS;
+    /**
+     * Number of parameter query results per sync stream definition (before deduplication).
+     * Map from definition name to count.
+     */
+    parameterQueryResultsByDefinition?: Map<string, number>;
 }
 export declare class BucketParameterState {
     private readonly context;

package/dist/sync/BucketChecksumState.js

@@ -66,7 +66,7 @@ export class BucketChecksumState {
         const userIdForLogs = this.parameterState.syncParams.userId;
         const storage = this.bucketStorage;
         const update = await this.parameterState.getCheckpointUpdate(next);
-        const { buckets: allBuckets, updatedBuckets } = update;
+        const { buckets: allBuckets, updatedBuckets, parameterQueryResultsByDefinition } = update;
         /** Set of all buckets in this checkpoint. */
         const bucketDescriptionMap = new Map(allBuckets.map((b) => [b.bucket, b]));
         if (bucketDescriptionMap.size > this.context.maxBuckets) {
@@ -145,18 +145,22 @@ export class BucketChecksumState {
                 };
             });
             deferredLog = () => {
+                const totalParamResults = computeTotalParamResults(parameterQueryResultsByDefinition);
                 let message = `Updated checkpoint: ${base.checkpoint} | `;
                 message += `write: ${writeCheckpoint} | `;
                 message += `buckets: ${allBuckets.length} | `;
+                if (totalParamResults !== undefined) {
+                    message += `param_results: ${totalParamResults} | `;
+                }
                 message += `updated: ${limitedBuckets(diff.updatedBuckets, 20)} | `;
                 message += `removed: ${limitedBuckets(diff.removedBuckets, 20)}`;
-                this.logger.info(message, {
+                logCheckpoint(this.logger, message, {
                     checkpoint: base.checkpoint,
                     user_id: userIdForLogs,
                     buckets: allBuckets.length,
                     updated: diff.updatedBuckets.length,
                     removed: diff.removedBuckets.length
-                });
+                }, totalParamResults);
             };
             checkpointLine = {
                 checkpoint_diff: {
@@ -169,9 +173,18 @@ export class BucketChecksumState {
         }
         else {
             deferredLog = () => {
+                const totalParamResults = computeTotalParamResults(parameterQueryResultsByDefinition);
                 let message = `New checkpoint: ${base.checkpoint} | write: ${writeCheckpoint} | `;
-                message += `buckets: ${allBuckets.length} ${limitedBuckets(allBuckets, 20)}`;
-                this.logger.info(message, { checkpoint: base.checkpoint, user_id: userIdForLogs, buckets: allBuckets.length });
+                message += `buckets: ${allBuckets.length}`;
+                if (totalParamResults !== undefined) {
+                    message += ` | param_results: ${totalParamResults}`;
+                }
+                message += ` ${limitedBuckets(allBuckets, 20)}`;
+                logCheckpoint(this.logger, message, {
+                    checkpoint: base.checkpoint,
+                    user_id: userIdForLogs,
+                    buckets: allBuckets.length
+                }, totalParamResults);
             };
             bucketsToFetch = allBuckets.map((b) => ({ bucket: b.bucket, priority: b.priority }));
             const subscriptions = [];
@@ -388,11 +401,18 @@ export class BucketParameterState {
             // TODO: Limit number of results even before we get to this point
             // This limit applies _before_ we get the unique set
             const error = new ServiceError(ErrorCode.PSYNC_S2305, `Too many parameter query results: ${update.buckets.length} (limit of ${this.context.maxParameterQueryResults})`);
-            this.logger.error(error.message, {
+            let errorMessage = error.message;
+            const logData = {
                 checkpoint: checkpoint,
                 user_id: this.syncParams.userId,
-                buckets: update.buckets.length
-            });
+                parameter_query_results: update.buckets.length
+            };
+            if (update.parameterQueryResultsByDefinition && update.parameterQueryResultsByDefinition.size > 0) {
+                const breakdown = formatParameterQueryBreakdown(update.parameterQueryResultsByDefinition);
+                errorMessage += breakdown.message;
+                logData.parameter_query_results_by_definition = breakdown.countsByDefinition;
+            }
+            this.logger.error(errorMessage, logData);
             throw error;
         }
         return update;
@@ -440,6 +460,7 @@ export class BucketParameterState {
             }
         }
         let dynamicBuckets;
+        let parameterQueryResultsByDefinition;
         if (hasParameterChange || this.cachedDynamicBuckets == null || this.cachedDynamicBucketSet == null) {
             const recordedLookups = new Set();
             dynamicBuckets = await querier.queryDynamicBucketDescriptions({
@@ -450,6 +471,12 @@ export class BucketParameterState {
                     return checkpoint.base.getParameterSets(lookups);
                 }
             });
+            // Count parameter query results per definition (before deduplication)
+            parameterQueryResultsByDefinition = new Map();
+            for (const bucket of dynamicBuckets) {
+                const count = parameterQueryResultsByDefinition.get(bucket.definition) ?? 0;
+                parameterQueryResultsByDefinition.set(bucket.definition, count + 1);
+            }
             this.cachedDynamicBuckets = dynamicBuckets;
             this.cachedDynamicBucketSet = new Set(dynamicBuckets.map((b) => b.bucket));
             this.lookupsFromPreviousCheckpoint = recordedLookups;
@@ -471,17 +498,65 @@ export class BucketParameterState {
             return {
                 buckets: allBuckets,
                 // We cannot track individual bucket updates for dynamic lookups yet
-                updatedBuckets: INVALIDATE_ALL_BUCKETS
+                updatedBuckets: INVALIDATE_ALL_BUCKETS,
+                parameterQueryResultsByDefinition
             };
         }
         else {
             return {
                 buckets: allBuckets,
-                updatedBuckets: updatedBuckets
+                updatedBuckets: updatedBuckets,
+                parameterQueryResultsByDefinition
             };
         }
     }
 }
+/**
+ * Compute the total number of parameter query results across all definitions.
+ */
+function computeTotalParamResults(parameterQueryResultsByDefinition) {
+    if (!parameterQueryResultsByDefinition) {
+        return undefined;
+    }
+    return Array.from(parameterQueryResultsByDefinition.values()).reduce((sum, count) => sum + count, 0);
+}
+/**
+ * Log a checkpoint message, enriching it with parameter query result counts if available.
+ *
+ * @param logger The logger instance to use
+ * @param message The base message string (param_results will NOT be appended — caller includes it if needed)
+ * @param logData The base log data object
+ * @param totalParamResults The total parameter query results count, or undefined if not applicable
+ */
+function logCheckpoint(logger, message, logData, totalParamResults) {
+    if (totalParamResults !== undefined) {
+        logData.parameter_query_results = totalParamResults;
+    }
+    logger.info(message, logData);
+}
+/**
+ * Format a breakdown of parameter query results by sync rule definition.
+ *
+ * Sorts definitions by count (descending), includes the top 10, and returns both the
+ * formatted message string and the counts record suitable for structured log data.
+ */
+function formatParameterQueryBreakdown(parameterQueryResultsByDefinition) {
+    // Sort definitions by count (descending) and take top 10
+    const allSorted = Array.from(parameterQueryResultsByDefinition.entries()).sort((a, b) => b[1] - a[1]);
+    const sortedDefinitions = allSorted.slice(0, 10);
+    let message = '\nParameter query results by definition:';
+    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`;
+    }
+    return { message, countsByDefinition };
+}
 function limitedBuckets(buckets, limit) {
     buckets = buckets.map((b) => {
         if (typeof b != 'string') {