@powersync/service-core 1.20.5 → 1.21.0

package/src/storage/SyncRulesBucketStorage.ts

@@ -2,9 +2,10 @@ import { Logger, ObserverClient } from '@powersync/lib-services-framework';
 import {
   BucketDataSource,
   HydratedSyncRules,
-  ScopedParameterLookup,
-  SqliteJsonRow
+  ParameterLookupRows,
+  ScopedParameterLookup
 } from '@powersync/service-sync-rules';
+import { PerformanceTracer } from '../tracing/PerformanceTracer.js';
 import * as util from '../util/util-index.js';
 import { BucketStorageBatch, FlushedResult, SaveUpdate } from './BucketStorageBatch.js';
 import { BucketStorageFactory } from './BucketStorageFactory.js';
@@ -14,7 +15,7 @@ import { SourceTable } from './SourceTable.js';
 import { SyncStorageWriteCheckpointAPI } from './WriteCheckpointAPI.js';
 
 /**
- * Storage for a specific copy of sync rules.
+ * Storage for a specific replication stream.
  */
 export interface SyncRulesBucketStorage
   extends ObserverClient<SyncRulesBucketStorageListener>,
@@ -23,6 +24,7 @@ export interface SyncRulesBucketStorage
   readonly slot_name: string;
 
   readonly factory: BucketStorageFactory;
+  readonly logger: Logger;
 
   /**
    * Resolve a table, keeping track of it internally.
@@ -47,11 +49,11 @@ export interface SyncRulesBucketStorage
   getParsedSyncRules(options: ParseSyncRulesOptions): HydratedSyncRules;
 
   /**
-   * Terminate the sync rules.
+   * Terminate the replication stream.
    *
    * This clears the storage, and sets state to TERMINATED.
    *
-   * Must only be called on stopped sync rules.
+   * Must only be called on stopped replication streams.
    */
   terminate(options?: TerminateOptions): Promise<void>;
 
@@ -98,7 +100,7 @@ export interface SyncRulesBucketStorage
   /**
    * Yields the latest user write checkpoint whenever the sync checkpoint updates.
    *
-   * The stream stops or errors if this is not the active sync rules (anymore).
+   * The stream stops or errors if this is not the active sync config (anymore).
    */
   watchCheckpointChanges(options: WatchWriteCheckpointOptions): AsyncIterable<StorageCheckpointUpdate>;
 
@@ -196,6 +198,8 @@ export interface CreateWriterOptions extends ParseSyncRulesOptions {
    */
   markRecordUnavailable?: BucketStorageMarkRecordUnavailable;
 
+  tracer?: PerformanceTracer<'storage' | 'evaluate'>;
+
   logger?: Logger;
 }
 
@@ -265,6 +269,8 @@ export interface CompactOptions {
   compactParameterCacheLimit?: number;
 
   signal?: AbortSignal;
+
+  logger?: Logger;
 }
 
 export interface PopulateChecksumCacheOptions {
@@ -320,8 +326,41 @@ export interface ReplicationCheckpoint {
    * Used to resolve "dynamic" parameter queries.
    *
    * This gets parameter sets specific to this checkpoint.
+   *
+   * @throws {@link ParameterSetLimitExceededError}
+   * Thrown if resolved lookups in bucket storage exceed the `limit` parameter.
+   */
+  getParameterSets(lookups: ScopedParameterLookup[], limit: number): Promise<ParameterLookupRows[]>;
+}
+
+/**
+ * An exception thrown by {@link ReplicationCheckpoint} implementations if there are too many parameter results.
+ *
+ * This is not a suitable exception to show to users, `BucketParameterState` adds additional context.
+ */
+export class ParameterSetLimitExceededError extends Error {
+  constructor(
+    readonly limit: number,
+    readonly breakdown?: ParameterQueryInvocationLog[]
+  ) {
+    super(`Too many parameter results (limit was ${limit})`);
+  }
+}
+
+export interface ParameterQueryInvocationLog {
+  /**
+   * The definition for which a parameter query was invoked.
+   *
+   * The exact format of definition is unspecified, it's shown to users to help them debug this failure.
+   */
+  definition: string;
+  /**
+   * If {@link didExceedLimit} is false, the amount of rows returned by the invocation.
+   *
+   * Otherwise, the maximum amount of rows this invocation was allowed to return.
    */
-  getParameterSets(lookups: ScopedParameterLookup[]): Promise<SqliteJsonRow[]>;
+  resultsOrLimit: number;
+  didExceedLimit: boolean;
 }
 
 export interface WatchWriteCheckpointOptions {

package/src/storage/WriteCheckpointAPI.ts

@@ -1,7 +1,7 @@
 export enum WriteCheckpointMode {
   /**
    * Raw mappings of `user_id` to `write_checkpoint`s should
-   * be supplied for each set of sync rules.
+   * be supplied for each replication stream.
    */
   CUSTOM = 'custom',
   /**
@@ -21,7 +21,7 @@ export interface BaseWriteCheckpointIdentifier {
 
 export interface CustomWriteCheckpointFilters extends BaseWriteCheckpointIdentifier {
   /**
-   * Sync rules which were active when this checkpoint was created.
+   * Replication stream which was active when this checkpoint was created.
    */
   sync_rules_id: number;
 }
@@ -35,7 +35,7 @@ export interface BatchedCustomWriteCheckpointOptions extends BaseWriteCheckpoint
 
 export interface CustomWriteCheckpointOptions extends BatchedCustomWriteCheckpointOptions {
   /**
-   * Sync rules which were active when this checkpoint was created.
+   * Replication stream which was active when this checkpoint was created.
    */
   sync_rules_id: number;
 }
@@ -63,8 +63,8 @@ export interface BaseWriteCheckpointAPI {
 
 /**
  * Write Checkpoint API to be used in conjunction with a {@link SyncRulesBucketStorage}.
- * This storage corresponds with a set of sync rules. These APIs don't require specifying a
- * sync rules id.
+ * This storage corresponds with a replication stream. These APIs don't require specifying a
+ * replication stream id.
  */
 export interface SyncStorageWriteCheckpointAPI extends BaseWriteCheckpointAPI {
   lastWriteCheckpoint(filters: SyncStorageLastWriteCheckpointFilters): Promise<bigint | null>;
@@ -72,7 +72,7 @@ export interface SyncStorageWriteCheckpointAPI extends BaseWriteCheckpointAPI {
 
 /**
  * Write Checkpoint API which is interfaced directly with the storage layer. This requires
- * sync rules identifiers for custom write checkpoints.
+ * replication stream identifiers for custom write checkpoints.
  */
 export interface WriteCheckpointAPI extends BaseWriteCheckpointAPI {
   lastWriteCheckpoint(filters: LastWriteCheckpointFilters): Promise<bigint | null>;

package/src/storage/bson.ts

@@ -40,11 +40,6 @@ export const deserializeParameterLookup = (lookup: bson.Binary) => {
   return parsed;
 };
 
-export const getLookupBucketDefinitionName = (lookup: bson.Binary) => {
-  const parsed = deserializeParameterLookup(lookup);
-  return parsed[0] as string;
-};
-
 /**
  * True if this is a bson.UUID.
  *

package/src/sync/BucketChecksumState.ts

@@ -21,6 +21,7 @@ import {
   ServiceError
 } from '@powersync/lib-services-framework';
 import { JwtPayload } from '../auth/JwtPayload.js';
+import { ParameterSetLimitExceededError } from '../storage/storage-index.js';
 import { SyncContext } from './SyncContext.js';
 import { getIntersection, hasIntersection } from './util.js';
 
@@ -118,16 +119,38 @@ export class BucketChecksumState {
     const storage = this.bucketStorage;
 
     const update = await this.parameterState.getCheckpointUpdate(next);
-    const { buckets: allBuckets, updatedBuckets, parameterQueryResultsByDefinition } = update;
+    const { buckets: allBuckets, updatedBuckets, usedParameterResults } = update;
 
     /** Set of all buckets in this checkpoint. */
     const bucketDescriptionMap = new Map(allBuckets.map((b) => [b.bucket, b]));
 
     if (bucketDescriptionMap.size > this.context.maxBuckets) {
-      throw new ServiceError(
+      const error = new ServiceError(
         ErrorCode.PSYNC_S2305,
         `Too many buckets: ${bucketDescriptionMap.size} (limit of ${this.context.maxBuckets})`
       );
+
+      let errorMessage = error.message;
+      const logData: any = {
+        checkpoint: next.base.checkpoint,
+        user_id: this.parameterState.syncParams.userId,
+        buckets: allBuckets.length
+      };
+
+      // Count buckets per definition.
+      const bucketsByDefinition = new Map<string, number>();
+      for (const bucket of bucketDescriptionMap.values()) {
+        const definition = bucket.definition;
+        const count = bucketsByDefinition.get(definition) ?? 0;
+        bucketsByDefinition.set(definition, count + 1);
+      }
+
+      const breakdown = formatBucketDefinitionBreakdown(bucketsByDefinition);
+      errorMessage += breakdown.message;
+      logData.buckets_by_definition = breakdown.countsByDefinition;
+
+      this.logger.error(errorMessage, logData);
+      throw error;
     }
 
     let checksumMap: util.ChecksumMap;
@@ -211,13 +234,10 @@ 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 += `param_results: ${usedParameterResults} | `;
         message += `updated: ${limitedBuckets(diff.updatedBuckets, 20)} | `;
         message += `removed: ${limitedBuckets(diff.removedBuckets, 20)}`;
         logCheckpoint(
@@ -230,7 +250,7 @@ export class BucketChecksumState {
             updated: diff.updatedBuckets.length,
             removed: diff.removedBuckets.length
           },
-          totalParamResults
+          usedParameterResults
         );
       };
 
@@ -244,12 +264,9 @@ export class BucketChecksumState {
       } satisfies util.StreamingSyncCheckpointDiff;
     } else {
       deferredLog = () => {
-        const totalParamResults = computeTotalParamResults(parameterQueryResultsByDefinition);
         let message = `New checkpoint: ${base.checkpoint} | write: ${writeCheckpoint} | `;
         message += `buckets: ${allBuckets.length}`;
-        if (totalParamResults !== undefined) {
-          message += ` | param_results: ${totalParamResults}`;
-        }
+        message += ` | param_results: ${usedParameterResults}`;
         message += ` ${limitedBuckets(allBuckets, 20)}`;
         logCheckpoint(
           this.logger,
@@ -259,7 +276,7 @@ export class BucketChecksumState {
             user_id: userIdForLogs,
             buckets: allBuckets.length
           },
-          totalParamResults
+          usedParameterResults
         );
       };
       bucketsToFetch = allBuckets;
@@ -392,11 +409,8 @@ export interface CheckpointUpdate {
    */
   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>;
+  /** The amount of rows fetched from parameters indexes. */
+  usedParameterResults: number;
 }
 
 export class BucketParameterState {
@@ -502,36 +516,41 @@ export class BucketParameterState {
     const querier = this.querier;
     let update: CheckpointUpdate;
     if (querier.hasDynamicBuckets) {
-      update = await this.getCheckpointUpdateDynamic(checkpoint);
-    } else {
-      update = await this.getCheckpointUpdateStatic(checkpoint);
-    }
-
-    if (update.buckets.length > this.context.maxParameterQueryResults) {
-      // 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})`
-      );
+      try {
+        update = await this.getCheckpointUpdateDynamic(checkpoint);
+      } catch (e: unknown) {
+        if (e instanceof ParameterSetLimitExceededError) {
+          // Too many parameter results, create a breakdown of which streams are responsible for the most queries and
+          // then abort.
+          const error = new ServiceError(
+            ErrorCode.PSYNC_S2305,
+            `Too many parameter query results (limit of ${this.context.maxParameterQueryResults})`
+          );
+
+          let errorMessage = error.message;
+          const logData: any = {
+            checkpoint: checkpoint.base.checkpoint,
+            user_id: this.syncParams.userId
+          };
+
+          if (e.breakdown) {
+            const breakdown = formatParameterQueryBreakdown(e.breakdown);
+            if (breakdown) {
+              errorMessage += breakdown.message;
+              logData.parameterResults = breakdown.largestResults;
+            }
+          }
 
-      let errorMessage = error.message;
-      const logData: any = {
-        checkpoint: checkpoint.base.checkpoint,
-        user_id: this.syncParams.userId,
-        parameter_query_results: update.buckets.length
-      };
+          this.logger.error(errorMessage, logData);
+          throw error;
+        }
 
-      if (update.parameterQueryResultsByDefinition && update.parameterQueryResultsByDefinition.size > 0) {
-        const breakdown = formatParameterQueryBreakdown(update.parameterQueryResultsByDefinition);
-        errorMessage += breakdown.message;
-        logData.parameter_query_results_by_definition = breakdown.countsByDefinition;
+        throw e;
       }
-
-      this.logger.error(errorMessage, logData);
-
-      throw error;
+    } else {
+      update = await this.getCheckpointUpdateStatic(checkpoint);
     }
+
     return update;
   }
 
@@ -545,14 +564,16 @@ export class BucketParameterState {
     if (update.invalidateDataBuckets) {
       return {
         buckets: staticBuckets,
-        updatedBuckets: INVALIDATE_ALL_BUCKETS
+        updatedBuckets: INVALIDATE_ALL_BUCKETS,
+        usedParameterResults: 0
       };
     }
 
     const updatedBuckets = new Set<string>(getIntersection(this.staticBuckets, update.updatedDataBuckets));
     return {
       buckets: staticBuckets,
-      updatedBuckets
+      updatedBuckets,
+      usedParameterResults: 0
     };
   }
 
@@ -584,27 +605,55 @@ export class BucketParameterState {
     }
 
     let dynamicBuckets: ResolvedBucket[];
-    let parameterQueryResultsByDefinition: Map<string, number> | undefined;
+    let usedParameterResults = 0;
     if (hasParameterChange || this.cachedDynamicBuckets == null || this.cachedDynamicBucketSet == null) {
       const recordedLookups = new Set<string>();
+      const parameterLimit = this.context.maxParameterQueryResults;
+      let remainingBudget = parameterLimit;
+
+      // Log of lookups to provide a breakdown if we exceed the dynamic lookup limit.
+      // FIXME: This is horrible, Sync Streams will invoke the callback concurrently and we can't properly deal with
+      // that. We should replace queriers for Sync Streams with an explicit graph structure based on sync plans instead
+      // of adding these checks to the imperative querier interface.
+      const lookupLog: storage.ParameterQueryInvocationLog[] = [];
 
       dynamicBuckets = await querier.queryDynamicBucketDescriptions({
-        getParameterSets(lookups) {
+        getParameterSets: async (lookups, definition) => {
+          if (lookups.length > parameterLimit) {
+            // Sync Streams can chain parameter lookups, so a large output from an earlier call may become the input
+            // here. We reuse the output limit as a generous upper bound; legitimate queries are much smaller.
+            const msg = `Attempted to fetch ${lookups.length} lookups at once, a maximum of ${parameterLimit} lookups are allowed.`;
+            this.logger.error(msg, {
+              user_id: this.syncParams.userId,
+              checkpoint: checkpoint.base.checkpoint,
+              cause: definition
+            });
+            throw new ServiceError(ErrorCode.PSYNC_S2305, msg);
+          }
+
           for (const lookup of lookups) {
             recordedLookups.add(lookup.serializedRepresentation);
           }
 
-          return checkpoint.base.getParameterSets(lookups);
+          try {
+            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 });
+            remainingBudget -= numRows;
+            usedParameterResults += numRows;
+            return results;
+          } catch (e: unknown) {
+            if (e instanceof ParameterSetLimitExceededError) {
+              lookupLog.push({ definition, resultsOrLimit: remainingBudget, didExceedLimit: true });
+              throw new ParameterSetLimitExceededError(parameterLimit, lookupLog);
+            }
+
+            throw e;
+          }
         }
       });
 
-      // Count parameter query results per definition (before deduplication)
-      parameterQueryResultsByDefinition = new Map<string, number>();
-      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<string>(dynamicBuckets.map((b) => b.bucket));
       this.lookupsFromPreviousCheckpoint = recordedLookups;
@@ -628,13 +677,13 @@ export class BucketParameterState {
         buckets: allBuckets,
         // We cannot track individual bucket updates for dynamic lookups yet
         updatedBuckets: INVALIDATE_ALL_BUCKETS,
-        parameterQueryResultsByDefinition
+        usedParameterResults
       };
     } else {
       return {
         buckets: allBuckets,
         updatedBuckets: updatedBuckets,
-        parameterQueryResultsByDefinition
+        usedParameterResults
       };
     }
   }
@@ -668,18 +717,6 @@ export interface CheckpointLine {
 // Use a more specific type to simplify testing
 export type BucketChecksumStateStorage = Pick<storage.SyncRulesBucketStorage, 'getChecksums'>;
 
-/**
- * Compute the total number of parameter query results across all definitions.
- */
-function computeTotalParamResults(
-  parameterQueryResultsByDefinition: Map<string, number> | undefined
-): number | undefined {
-  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.
  *
@@ -701,20 +738,20 @@ function logCheckpoint(
 }
 
 /**
- * Format a breakdown of parameter query results by sync rule definition.
+ * Format a breakdown of dynamic bucket by sync stream 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: Map<string, number>): {
+function formatBucketDefinitionBreakdown(bucketsByDefinition: Map<string, number>): {
   message: string;
   countsByDefinition: Record<string, number>;
 } {
   // Sort definitions by count (descending) and take top 10
-  const allSorted = Array.from(parameterQueryResultsByDefinition.entries()).sort((a, b) => b[1] - a[1]);
+  const allSorted = Array.from(bucketsByDefinition.entries()).sort((a, b) => b[1] - a[1]);
   const sortedDefinitions = allSorted.slice(0, 10);
 
-  let message = '\nParameter query results by definition:';
+  let message = '\Buckets by definition:';
   const countsByDefinition: Record<string, number> = {};
   for (const [definition, count] of sortedDefinitions) {
     message += `\n  ${definition}: ${count}`;
@@ -730,6 +767,33 @@ function formatParameterQueryBreakdown(parameterQueryResultsByDefinition: Map<st
   return { message, countsByDefinition };
 }
 
+function formatParameterQueryBreakdown(log: storage.ParameterQueryInvocationLog[]) {
+  if (log.length == 0) {
+    return;
+  }
+
+  // When an exception about too many parameter results is thrown, the last entry is the one that finally exceeded the
+  // limit.
+  const results = Array.from(log);
+  const failure = results.pop()!;
+
+  let message = '\nInvoked parameter queries by definition:';
+  results.sort((a, b) => b.resultsOrLimit - a.resultsOrLimit);
+  const largestResults = results.splice(0, 9);
+
+  for (const entry of largestResults) {
+    message += `\n  ${entry.definition}: ${entry.resultsOrLimit} results.`;
+  }
+
+  if (largestResults.length < log.length) {
+    message += `\n ... and ${log.length - largestResults.length} more invocations`;
+  }
+
+  message += `\n ${failure.definition} exceeded the remaining limit of ${failure.resultsOrLimit} available results.`;
+  largestResults.push(failure);
+  return { message, largestResults };
+}
+
 function limitedBuckets(buckets: string[] | { bucket: string }[], limit: number) {
   buckets = buckets.map((b) => {
     if (typeof b != 'string') {

package/src/sync/sync.ts

@@ -267,7 +267,7 @@ interface BucketDataRequest {
    * This signal also fires when abort_connection fires.
    */
   abort_batch: AbortSignal;
-  /** User id for debug purposes, not for sync rules. */
+  /** User id for debug purposes, not for sync config. */
   userIdForLogs?: SqliteJsonValue;
   forPriority: BucketPriority | null;
   onRowsSent: (stats: OperationsSentStats) => void;

package/src/tracing/PerformanceTracer.ts

@@ -0,0 +1,126 @@
+import { traceWriter } from './TraceWriter.js';
+
+export interface Span extends Disposable {
+  name: string;
+  startAt: number;
+  endAt: number;
+  selfDuration: number;
+  nestedSince: number | undefined;
+  subtrackFromSelf: number;
+  nestedDurations: Record<string, number>;
+
+  /**
+   * End the span - same as [Symbol.dispose]().
+   *
+   * Safe to call multiple times. Any nested spans will automatically end as well.
+   *
+   * Returns an aggregate record of category -> "selfDuration".
+   */
+  end(): Record<string, number>;
+}
+
+function now() {
+  return Number(process.hrtime.bigint() / 1000n);
+}
+
+let nextThreadId = 1;
+
+/**
+ * Lightweight tracing helper, with two main goals:
+ * 1. Generate aggregate timing info with low overhead.
+ * 2. Optional support for generating trace files during development.
+ *
+ * This is only intended for a single "thread" - concurrent operations on the same instance have undefined behavior.
+ * To trace concurrent operations, use separate instances of PerformanceTracer.
+ *
+ * Spans cannot be overlapping: If a parent span is ended, all nested spans are automatically ended.
+ */
+export class PerformanceTracer<K extends string> {
+  stack: Span[] = [];
+  threadId: number;
+
+  constructor(traceName: string) {
+    this.threadId = nextThreadId;
+    nextThreadId += 1;
+    traceWriter?.write({
+      ph: 'M',
+      cat: '__metadata',
+      name: 'thread_name',
+      pid: process.pid,
+      tid: this.threadId,
+      args: { name: `PowerSync ${traceName}` }
+    });
+  }
+
+  /**
+   * Recommended usage:
+   *
+   *   using _ = tracer.span('cat', 'details');
+   *
+   * The above automatically ends the span when it goes out of scope. Alternatively, call
+   * .end() on the span to end it earlier.
+   *
+   * @param category one of the defined categories
+   * @param subcat optional subcategory. Not used for calculating "self" durations in the aggregate API.
+   */
+  span(category: K, subcat?: string): Span {
+    const stack = this.stack;
+    const index = this.stack.length;
+    const parent = this.stack[this.stack.length - 1];
+    const threadId = this.threadId;
+    const startAt = now();
+    if (parent != null) {
+      parent.nestedSince ??= startAt;
+    }
+    let name: string = category;
+    if (subcat) {
+      name += ':' + subcat;
+    }
+    const s: Span = {
+      name,
+      startAt: now(),
+      selfDuration: 0,
+      endAt: 0,
+      nestedSince: undefined,
+      subtrackFromSelf: 0,
+      nestedDurations: {},
+      end() {
+        if (this.endAt != 0) {
+          return this.nestedDurations;
+        }
+        while (stack.length - 1 > index) {
+          stack[stack.length - 1].end();
+        }
+        const endAt = now();
+        this.endAt = endAt;
+        const endTime = this.nestedSince ?? endAt;
+        this.selfDuration = endTime - startAt - this.subtrackFromSelf;
+        traceWriter?.write({
+          name,
+          cat: 'powersync',
+          ph: 'X',
+          ts: this.startAt,
+          dur: endAt - startAt,
+          pid: process.pid,
+          tid: threadId
+        });
+        stack.pop();
+        if (parent != null) {
+          parent.subtrackFromSelf += endAt - parent.nestedSince!;
+          for (let key in this.nestedDurations) {
+            parent.nestedDurations[key] = (parent.nestedDurations[key] ?? 0) + this.nestedDurations[key];
+          }
+          parent.nestedDurations[category] = (parent.nestedDurations[category] ?? 0) + this.selfDuration;
+          parent.nestedSince = undefined;
+        }
+        return this.nestedDurations;
+      },
+      [Symbol.dispose]() {
+        this.end();
+      }
+    };
+    this.stack.push(s);
+
+    return s;
+  }
+}