@aztec/sequencer-client 0.0.1-commit.b655e406 → 0.0.1-commit.b8a057fa

package/dest/sequencer/metrics.js

@@ -1,4 +1,4 @@
-import { Attributes, Metrics, ValueType } from '@aztec/telemetry-client';
+import { Attributes, Metrics, createUpDownCounterWithDefault } from '@aztec/telemetry-client';
 import { formatUnits } from 'viem';
 export class SequencerMetrics {
     rollup;
@@ -8,6 +8,7 @@ export class SequencerMetrics {
     blockBuildDuration;
     blockBuildManaPerSecond;
     stateTransitionBufferDuration;
+    stateDuration;
     // these are gauges because for individual sequencers building a block is not something that happens often enough to warrant a histogram
     timeToCollectAttestations;
     allowanceToCollectAttestations;
@@ -16,67 +17,113 @@ export class SequencerMetrics {
     rewards;
     slots;
     filledSlots;
+    blockProposalFailed;
+    checkpointProposalSuccess;
+    checkpointPrecheckFailed;
+    checkpointProposalFailed;
+    checkpointSuccess;
+    slashingAttempts;
+    pipelineDepth;
+    pipelineDiscards;
+    pipelineParentCheckpointMismatches;
+    // Fisherman fee analysis metrics
+    fishermanWouldBeIncluded;
+    fishermanTimeBeforeBlock;
+    fishermanPendingBlobTxCount;
+    fishermanIncludedBlobTxCount;
+    fishermanPendingBlobCount;
+    fishermanIncludedBlobCount;
+    fishermanBlockBlobsFull;
+    fishermanMaxBlobCapacity;
+    fishermanCalculatedPriorityFee;
+    fishermanPriorityFeeDelta;
+    fishermanEstimatedCost;
+    fishermanEstimatedOverpayment;
+    fishermanMinedBlobTxPriorityFee;
+    fishermanMinedBlobTxTotalCost;
+    blockInterBlockTime;
+    lastBlockBuiltTimestamp;
+    lastBlockBuiltSlot;
     lastSeenSlot;
     constructor(client, rollup, name = 'Sequencer'){
         this.rollup = rollup;
         this.meter = client.getMeter(name);
         this.tracer = client.getTracer(name);
-        this.blockCounter = this.meter.createUpDownCounter(Metrics.SEQUENCER_BLOCK_COUNT);
-        this.blockBuildDuration = this.meter.createHistogram(Metrics.SEQUENCER_BLOCK_BUILD_DURATION, {
-            unit: 'ms',
-            description: 'Duration to build a block',
-            valueType: ValueType.INT
-        });
-        this.blockBuildManaPerSecond = this.meter.createGauge(Metrics.SEQUENCER_BLOCK_BUILD_MANA_PER_SECOND, {
-            unit: 'mana/s',
-            description: 'Mana per second when building a block',
-            valueType: ValueType.INT
-        });
-        this.stateTransitionBufferDuration = this.meter.createHistogram(Metrics.SEQUENCER_STATE_TRANSITION_BUFFER_DURATION, {
-            unit: 'ms',
-            description: 'The time difference between when the sequencer needed to transition to a new state and when it actually did.',
-            valueType: ValueType.INT
-        });
-        // Init gauges and counters
-        this.blockCounter.add(0, {
-            [Attributes.STATUS]: 'failed'
-        });
-        this.blockCounter.add(0, {
-            [Attributes.STATUS]: 'built'
-        });
-        this.rewards = this.meter.createGauge(Metrics.SEQUENCER_CURRENT_BLOCK_REWARDS, {
-            valueType: ValueType.DOUBLE,
-            description: 'The rewards earned'
-        });
-        this.slots = this.meter.createUpDownCounter(Metrics.SEQUENCER_SLOT_COUNT, {
-            valueType: ValueType.INT,
-            description: 'The number of slots this sequencer was selected for'
+        this.blockCounter = createUpDownCounterWithDefault(this.meter, Metrics.SEQUENCER_BLOCK_COUNT, {
+            [Attributes.STATUS]: [
+                'failed',
+                'built'
+            ]
         });
+        this.blockBuildDuration = this.meter.createHistogram(Metrics.SEQUENCER_BLOCK_BUILD_DURATION);
+        this.blockBuildManaPerSecond = this.meter.createGauge(Metrics.SEQUENCER_BLOCK_BUILD_MANA_PER_SECOND);
+        this.blockInterBlockTime = this.meter.createHistogram(Metrics.SEQUENCER_BLOCK_INTER_BLOCK_TIME);
+        this.stateTransitionBufferDuration = this.meter.createHistogram(Metrics.SEQUENCER_STATE_TRANSITION_BUFFER_DURATION);
+        this.stateDuration = this.meter.createHistogram(Metrics.SEQUENCER_STATE_DURATION);
+        this.rewards = this.meter.createGauge(Metrics.SEQUENCER_CURRENT_SLOT_REWARDS);
+        this.slots = createUpDownCounterWithDefault(this.meter, Metrics.SEQUENCER_SLOT_COUNT);
         /**
      * NOTE: we do not track missed slots as a separate metric. That would be difficult to determine
      * Instead, use a computed metric, `slots - filledSlots` to get the number of slots a sequencer has missed.
-     */ this.filledSlots = this.meter.createUpDownCounter(Metrics.SEQUENCER_FILLED_SLOT_COUNT, {
-            valueType: ValueType.INT,
-            description: 'The number of slots this sequencer has filled'
-        });
-        this.timeToCollectAttestations = this.meter.createGauge(Metrics.SEQUENCER_COLLECT_ATTESTATIONS_DURATION, {
-            description: 'The time spent collecting attestations from committee members',
-            unit: 'ms',
-            valueType: ValueType.INT
+     */ this.filledSlots = createUpDownCounterWithDefault(this.meter, Metrics.SEQUENCER_FILLED_SLOT_COUNT);
+        this.timeToCollectAttestations = this.meter.createGauge(Metrics.SEQUENCER_COLLECT_ATTESTATIONS_DURATION);
+        this.allowanceToCollectAttestations = this.meter.createGauge(Metrics.SEQUENCER_COLLECT_ATTESTATIONS_TIME_ALLOWANCE);
+        this.requiredAttestions = this.meter.createGauge(Metrics.SEQUENCER_REQUIRED_ATTESTATIONS_COUNT);
+        this.collectedAttestions = this.meter.createGauge(Metrics.SEQUENCER_COLLECTED_ATTESTATIONS_COUNT);
+        this.blockProposalFailed = createUpDownCounterWithDefault(this.meter, Metrics.SEQUENCER_BLOCK_PROPOSAL_FAILED_COUNT);
+        this.checkpointProposalSuccess = createUpDownCounterWithDefault(this.meter, Metrics.SEQUENCER_CHECKPOINT_PROPOSAL_SUCCESS_COUNT);
+        this.checkpointSuccess = createUpDownCounterWithDefault(this.meter, Metrics.SEQUENCER_CHECKPOINT_SUCCESS_COUNT);
+        this.checkpointPrecheckFailed = createUpDownCounterWithDefault(this.meter, Metrics.SEQUENCER_CHECKPOINT_PRECHECK_FAILED_COUNT, {
+            [Attributes.ERROR_TYPE]: [
+                'slot_already_taken',
+                'rollup_contract_check_failed',
+                'slot_mismatch',
+                'block_number_mismatch'
+            ]
         });
-        this.allowanceToCollectAttestations = this.meter.createGauge(Metrics.SEQUENCER_COLLECT_ATTESTATIONS_TIME_ALLOWANCE, {
-            description: 'Maximum amount of time to collect attestations',
-            unit: 'ms',
-            valueType: ValueType.INT
+        this.checkpointProposalFailed = createUpDownCounterWithDefault(this.meter, Metrics.SEQUENCER_CHECKPOINT_PROPOSAL_FAILED_COUNT);
+        this.slashingAttempts = createUpDownCounterWithDefault(this.meter, Metrics.SEQUENCER_SLASHING_ATTEMPTS_COUNT);
+        this.pipelineDepth = this.meter.createGauge(Metrics.SEQUENCER_PIPELINE_DEPTH);
+        this.pipelineDiscards = createUpDownCounterWithDefault(this.meter, Metrics.SEQUENCER_PIPELINE_DISCARDS_COUNT);
+        this.pipelineParentCheckpointMismatches = createUpDownCounterWithDefault(this.meter, Metrics.SEQUENCER_PIPELINE_PARENT_CHECKPOINT_MISMATCH_COUNT, {
+            [Attributes.ERROR_TYPE]: [
+                'archiver-sync-timeout',
+                'parent-not-on-l1',
+                'parent-hash-mismatch',
+                'parent-invalid-attestations',
+                'unexpected-parent-appeared'
+            ]
         });
-        this.requiredAttestions = this.meter.createGauge(Metrics.SEQUENCER_REQUIRED_ATTESTATIONS_COUNT, {
-            valueType: ValueType.INT,
-            description: 'The minimum number of attestations required to publish a block'
+        this.pipelineDepth.record(0);
+        // Fisherman fee analysis metrics
+        this.fishermanWouldBeIncluded = createUpDownCounterWithDefault(this.meter, Metrics.FISHERMAN_FEE_ANALYSIS_WOULD_BE_INCLUDED, {
+            [Attributes.OK]: [
+                true,
+                false
+            ],
+            [Attributes.BLOCK_FULL]: [
+                'true',
+                'false'
+            ]
         });
-        this.collectedAttestions = this.meter.createGauge(Metrics.SEQUENCER_COLLECTED_ATTESTATIONS_COUNT, {
-            valueType: ValueType.INT,
-            description: 'The minimum number of attestations required to publish a block'
+        this.fishermanTimeBeforeBlock = this.meter.createHistogram(Metrics.FISHERMAN_FEE_ANALYSIS_TIME_BEFORE_BLOCK);
+        this.fishermanPendingBlobTxCount = this.meter.createHistogram(Metrics.FISHERMAN_FEE_ANALYSIS_PENDING_BLOB_TX_COUNT);
+        this.fishermanIncludedBlobTxCount = this.meter.createHistogram(Metrics.FISHERMAN_FEE_ANALYSIS_INCLUDED_BLOB_TX_COUNT);
+        this.fishermanCalculatedPriorityFee = this.meter.createHistogram(Metrics.FISHERMAN_FEE_ANALYSIS_CALCULATED_PRIORITY_FEE);
+        this.fishermanPriorityFeeDelta = this.meter.createHistogram(Metrics.FISHERMAN_FEE_ANALYSIS_PRIORITY_FEE_DELTA);
+        this.fishermanEstimatedCost = this.meter.createHistogram(Metrics.FISHERMAN_FEE_ANALYSIS_ESTIMATED_COST);
+        this.fishermanEstimatedOverpayment = this.meter.createHistogram(Metrics.FISHERMAN_FEE_ANALYSIS_ESTIMATED_OVERPAYMENT);
+        this.fishermanMinedBlobTxPriorityFee = this.meter.createHistogram(Metrics.FISHERMAN_FEE_ANALYSIS_MINED_BLOB_TX_PRIORITY_FEE);
+        this.fishermanMinedBlobTxTotalCost = this.meter.createHistogram(Metrics.FISHERMAN_FEE_ANALYSIS_MINED_BLOB_TX_TOTAL_COST);
+        this.fishermanPendingBlobCount = this.meter.createHistogram(Metrics.FISHERMAN_FEE_ANALYSIS_PENDING_BLOB_COUNT);
+        this.fishermanIncludedBlobCount = this.meter.createHistogram(Metrics.FISHERMAN_FEE_ANALYSIS_INCLUDED_BLOB_COUNT);
+        this.fishermanBlockBlobsFull = createUpDownCounterWithDefault(this.meter, Metrics.FISHERMAN_FEE_ANALYSIS_BLOCK_BLOBS_FULL, {
+            [Attributes.OK]: [
+                true,
+                false
+            ]
         });
+        this.fishermanMaxBlobCapacity = this.meter.createHistogram(Metrics.FISHERMAN_FEE_ANALYSIS_MAX_BLOB_CAPACITY);
     }
     recordRequiredAttestations(requiredAttestationsCount, allowanceMs) {
         this.requiredAttestions.record(requiredAttestationsCount);
@@ -89,12 +136,19 @@ export class SequencerMetrics {
         this.collectedAttestions.record(count);
         this.timeToCollectAttestations.record(Math.ceil(durationMs));
     }
-    recordBuiltBlock(buildDurationMs, totalMana) {
+    recordBuiltBlock(buildDurationMs, totalMana, slot) {
         this.blockCounter.add(1, {
             [Attributes.STATUS]: 'built'
         });
         this.blockBuildDuration.record(Math.ceil(buildDurationMs));
         this.blockBuildManaPerSecond.record(Math.ceil(totalMana * 1000 / buildDurationMs));
+        // Only record inter-block time between blocks built within the same slot.
+        const now = Date.now();
+        if (this.lastBlockBuiltTimestamp !== undefined && this.lastBlockBuiltSlot === slot) {
+            this.blockInterBlockTime.record(now - this.lastBlockBuiltTimestamp);
+        }
+        this.lastBlockBuiltTimestamp = now;
+        this.lastBlockBuiltSlot = slot;
     }
     recordFailedBlock() {
         this.blockCounter.add(1, {
@@ -106,6 +160,22 @@ export class SequencerMetrics {
             [Attributes.SEQUENCER_STATE]: state
         });
     }
+    recordStateDuration(durationMs, state) {
+        this.stateDuration.record(Math.ceil(durationMs), {
+            [Attributes.SEQUENCER_STATE]: state
+        });
+    }
+    recordPipelineDepth(depth) {
+        this.pipelineDepth.record(depth);
+    }
+    recordPipelineDiscard(count = 1) {
+        this.pipelineDiscards.add(count);
+    }
+    recordPipelineParentCheckpointMismatch(reason) {
+        this.pipelineParentCheckpointMismatches.add(1, {
+            [Attributes.ERROR_TYPE]: reason
+        });
+    }
     incOpenSlot(slot, proposer) {
         // sequencer went through the loop a second time. Noop
         if (slot === this.lastSeenSlot) {
@@ -133,4 +203,141 @@ export class SequencerMetrics {
             }
         }
     }
+    recordCheckpointSuccess() {
+        this.checkpointSuccess.add(1);
+    }
+    recordBlockProposalFailed(reason) {
+        this.blockProposalFailed.add(1, {
+            ...reason && {
+                [Attributes.ERROR_TYPE]: reason
+            }
+        });
+    }
+    recordCheckpointProposalSuccess() {
+        this.checkpointProposalSuccess.add(1);
+    }
+    recordCheckpointPrecheckFailed(checkType) {
+        this.checkpointPrecheckFailed.add(1, {
+            [Attributes.ERROR_TYPE]: checkType
+        });
+    }
+    recordCheckpointProposalFailed(reason) {
+        this.checkpointProposalFailed.add(1, {
+            ...reason && {
+                [Attributes.ERROR_TYPE]: reason
+            }
+        });
+    }
+    recordSlashingAttempt(actionCount) {
+        this.slashingAttempts.add(actionCount);
+    }
+    /**
+   * Records metrics for a completed fisherman fee analysis
+   * @param analysis - The completed fee analysis result
+   */ recordFishermanFeeAnalysis(analysis) {
+        // In fisherman mode, we should always have strategy results
+        if (!analysis.computedPrices.strategyResults || analysis.computedPrices.strategyResults.length === 0) {
+            // This should never happen in fisherman mode - log an error
+            // We don't record metrics without strategy IDs as that defeats the purpose
+            throw new Error(`No strategy results found in fisherman fee analysis ${analysis.id}. This indicates a bug in the fee analysis.`);
+        }
+        // Record metrics for each strategy separately
+        for (const strategyResult of analysis.computedPrices.strategyResults){
+            const strategyAttributes = {
+                [Attributes.FISHERMAN_FEE_STRATEGY_ID]: strategyResult.strategyId
+            };
+            // Record pending block snapshot data (once per strategy for comparison)
+            this.fishermanPendingBlobTxCount.record(analysis.pendingSnapshot.pendingBlobTxCount, strategyAttributes);
+            this.fishermanPendingBlobCount.record(analysis.pendingSnapshot.pendingBlobCount, strategyAttributes);
+            // Record mined block data if available
+            if (analysis.minedBlock) {
+                this.fishermanIncludedBlobTxCount.record(analysis.minedBlock.includedBlobTxCount, strategyAttributes);
+                this.fishermanIncludedBlobCount.record(analysis.minedBlock.includedBlobCount, strategyAttributes);
+                // Record actual fees from blob transactions in the mined block
+                for (const blobTx of analysis.minedBlock.includedBlobTxs){
+                    // Record priority fee per gas in Gwei
+                    const priorityFeeGwei = Number(blobTx.maxPriorityFeePerGas) / 1e9;
+                    this.fishermanMinedBlobTxPriorityFee.record(priorityFeeGwei, strategyAttributes);
+                    // Calculate total cost in ETH
+                    // Cost = (gas * (baseFee + priorityFee)) + (blobCount * blobGasPerBlob * blobBaseFee)
+                    const baseFee = analysis.minedBlock.baseFeePerGas;
+                    const effectiveGasPrice = baseFee + blobTx.maxPriorityFeePerGas;
+                    // Calculate execution cost using actual gas limit from the transaction
+                    const executionCost = blobTx.gas * effectiveGasPrice;
+                    // Calculate blob cost using maxFeePerBlobGas * blobCount * GAS_PER_BLOB
+                    const blobCost = blobTx.maxFeePerBlobGas * BigInt(blobTx.blobCount) * 131072n; // 128KB per blob
+                    const totalCostWei = executionCost + blobCost;
+                    const totalCostEth = Number(totalCostWei) / 1e18;
+                    this.fishermanMinedBlobTxTotalCost.record(totalCostEth, strategyAttributes);
+                }
+            }
+            // Record the calculated priority fee for this strategy
+            const calculatedPriorityFeeGwei = Number(strategyResult.calculatedPriorityFee) / 1e9;
+            this.fishermanCalculatedPriorityFee.record(calculatedPriorityFeeGwei, strategyAttributes);
+            // Record analysis results if available
+            if (analysis.analysis) {
+                this.fishermanTimeBeforeBlock.record(Math.ceil(analysis.analysis.timeBeforeBlockMs), strategyAttributes);
+                // Record whether the block reached 100% blob capacity
+                if (analysis.analysis.blockBlobsFull) {
+                    this.fishermanBlockBlobsFull.add(1, {
+                        ...strategyAttributes,
+                        [Attributes.OK]: true
+                    });
+                } else {
+                    this.fishermanBlockBlobsFull.add(1, {
+                        ...strategyAttributes,
+                        [Attributes.OK]: false
+                    });
+                }
+                // Record the max blob capacity for this block
+                this.fishermanMaxBlobCapacity.record(analysis.analysis.maxBlobCapacity, strategyAttributes);
+                // Record strategy-specific inclusion result
+                if (strategyResult.wouldBeIncluded !== undefined) {
+                    const inclusionAttributes = {
+                        ...strategyAttributes,
+                        [Attributes.BLOCK_FULL]: analysis.analysis.blockBlobsFull ? 'true' : 'false'
+                    };
+                    if (strategyResult.wouldBeIncluded) {
+                        this.fishermanWouldBeIncluded.add(1, {
+                            ...inclusionAttributes,
+                            [Attributes.OK]: true
+                        });
+                    } else {
+                        this.fishermanWouldBeIncluded.add(1, {
+                            ...inclusionAttributes,
+                            [Attributes.OK]: false,
+                            ...strategyResult.exclusionReason && {
+                                [Attributes.ERROR_TYPE]: strategyResult.exclusionReason
+                            }
+                        });
+                    }
+                }
+                // Record strategy-specific priority fee delta
+                if (strategyResult.priorityFeeDelta !== undefined) {
+                    const priorityFeeDeltaGwei = Number(strategyResult.priorityFeeDelta) / 1e9;
+                    const deltaAttributes = {
+                        ...strategyAttributes,
+                        [Attributes.BLOCK_FULL]: analysis.analysis.blockBlobsFull ? 'true' : 'false'
+                    };
+                    this.fishermanPriorityFeeDelta.record(priorityFeeDeltaGwei, deltaAttributes);
+                }
+                // Record estimated cost if available
+                if (strategyResult.estimatedCostEth !== undefined) {
+                    const costAttributes = {
+                        ...strategyAttributes,
+                        [Attributes.BLOCK_FULL]: analysis.analysis.blockBlobsFull ? 'true' : 'false'
+                    };
+                    this.fishermanEstimatedCost.record(strategyResult.estimatedCostEth, costAttributes);
+                }
+                // Record estimated overpayment if available
+                if (strategyResult.estimatedOverpaymentEth !== undefined) {
+                    const overpaymentAttributes = {
+                        ...strategyAttributes,
+                        [Attributes.BLOCK_FULL]: analysis.analysis.blockBlobsFull ? 'true' : 'false'
+                    };
+                    this.fishermanEstimatedOverpayment.record(strategyResult.estimatedOverpaymentEth, overpaymentAttributes);
+                }
+            }
+        }
+    }
 }

package/dest/sequencer/requests_tracker.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Tracks fire-and-forget requests so a shutdown path can interrupt any in-flight work and await it to
+ * settle. Each tracked request is a promise plus an optional interrupt callback; the entry removes itself
+ * from the bag once its promise settles, so the tracker only ever holds requests that are still in flight.
+ */
+export declare class RequestsTracker {
+    private readonly requests;
+    private nextId;
+    /** Number of in-flight requests currently tracked. */
+    get size(): number;
+    /**
+     * Tracks a fire-and-forget request. `interrupt`, when provided, is invoked by {@link interruptRequests}
+     * to cancel the in-flight work so its promise settles promptly. The entry auto-removes once `promise`
+     * settles, whether it resolves or rejects.
+     */
+    trackRequest(promise: Promise<unknown>, interrupt?: () => void): void;
+    /** Interrupts every in-flight request that was tracked with an interrupt callback. */
+    interruptRequests(): void;
+    /** Awaits every currently in-flight request to settle. */
+    awaitRequests(): Promise<void>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVxdWVzdHNfdHJhY2tlci5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3NlcXVlbmNlci9yZXF1ZXN0c190cmFja2VyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUdBOzs7O0dBSUc7QUFDSCxxQkFBYSxlQUFlO0lBQzFCLE9BQU8sQ0FBQyxRQUFRLENBQUMsUUFBUSxDQUFxQztJQUM5RCxPQUFPLENBQUMsTUFBTSxDQUFLO0lBRW5CLHNEQUFzRDtJQUN0RCxJQUFXLElBQUksSUFBSSxNQUFNLENBRXhCO0lBRUQ7Ozs7T0FJRztJQUNJLFlBQVksQ0FBQyxPQUFPLEVBQUUsT0FBTyxDQUFDLE9BQU8sQ0FBQyxFQUFFLFNBQVMsQ0FBQyxFQUFFLE1BQU0sSUFBSSxHQUFHLElBQUksQ0FPM0U7SUFFRCxzRkFBc0Y7SUFDL0UsaUJBQWlCLElBQUksSUFBSSxDQUkvQjtJQUVELDBEQUEwRDtJQUM3QyxhQUFhLElBQUksT0FBTyxDQUFDLElBQUksQ0FBQyxDQUUxQztDQUNGIn0=

package/dest/sequencer/requests_tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requests_tracker.d.ts","sourceRoot":"","sources":["../../src/sequencer/requests_tracker.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqC;IAC9D,OAAO,CAAC,MAAM,CAAK;IAEnB,sDAAsD;IACtD,IAAW,IAAI,IAAI,MAAM,CAExB;IAED;;;;OAIG;IACI,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,EAAE,MAAM,IAAI,GAAG,IAAI,CAO3E;IAED,sFAAsF;IAC/E,iBAAiB,IAAI,IAAI,CAI/B;IAED,0DAA0D;IAC7C,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAE1C;CACF"}

package/dest/sequencer/requests_tracker.js

@@ -0,0 +1,33 @@
+/** A tracked request: the awaitable to wait on, plus an optional interrupt to cancel it early. */ /**
+ * Tracks fire-and-forget requests so a shutdown path can interrupt any in-flight work and await it to
+ * settle. Each tracked request is a promise plus an optional interrupt callback; the entry removes itself
+ * from the bag once its promise settles, so the tracker only ever holds requests that are still in flight.
+ */ export class RequestsTracker {
+    requests = new Map();
+    nextId = 0;
+    /** Number of in-flight requests currently tracked. */ get size() {
+        return this.requests.size;
+    }
+    /**
+   * Tracks a fire-and-forget request. `interrupt`, when provided, is invoked by {@link interruptRequests}
+   * to cancel the in-flight work so its promise settles promptly. The entry auto-removes once `promise`
+   * settles, whether it resolves or rejects.
+   */ trackRequest(promise, interrupt) {
+        const id = this.nextId++;
+        const settled = promise.then(()=>this.requests.delete(id), ()=>this.requests.delete(id));
+        this.requests.set(id, {
+            promise: settled,
+            interrupt
+        });
+    }
+    /** Interrupts every in-flight request that was tracked with an interrupt callback. */ interruptRequests() {
+        for (const { interrupt } of this.requests.values()){
+            interrupt?.();
+        }
+    }
+    /** Awaits every currently in-flight request to settle. */ async awaitRequests() {
+        await Promise.all([
+            ...this.requests.values()
+        ].map((request)=>request.promise));
+    }
+}