@fluidframework/container-runtime 2.100.0 → 2.101.1

package/lib/summary/summarizerTypes.js.map

@@ -1 +1 @@
-{"version":3,"file":"summarizerTypes.js","sourceRoot":"","sources":["../../src/summary/summarizerTypes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAiCH,MAAM,CAAC,MAAM,oBAAoB,GAAG,YAAY,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type {\n\tIDeltaManager,\n\tContainerWarning,\n} from \"@fluidframework/container-definitions/internal\";\nimport type {\n\tISummarizerEvents,\n\tSummarizerStopReason,\n} from \"@fluidframework/container-runtime-definitions/internal\";\nimport type {\n\tIEventProvider,\n\tITelemetryBaseProperties,\n\tITelemetryBaseLogger,\n} from \"@fluidframework/core-interfaces\";\nimport type { ISummaryTree } from \"@fluidframework/driver-definitions\";\nimport type {\n\tIDocumentMessage,\n\tISequencedDocumentMessage,\n} from \"@fluidframework/driver-definitions/internal\";\nimport type { ISummaryStats } from \"@fluidframework/runtime-definitions/internal\";\nimport type { TelemetryContext } from \"@fluidframework/runtime-utils/internal\";\nimport type {\n\tITelemetryLoggerExt,\n\tITelemetryLoggerPropertyBag,\n} from \"@fluidframework/telemetry-utils/internal\";\n\nimport type { SummarizeReason } from \"./summarizerUtils.js\";\nimport type {\n\tEnqueueSummarizeResult,\n\tISummarizeResults,\n} from \"./summaryDelayLoadedModule/index.js\";\n\nexport const summarizerClientType = \"summarizer\";\n\n/**\n * Similar to AbortSignal, but using promise instead of events\n * @param T - cancellation reason type\n * @internal\n */\nexport interface ICancellationToken<T> {\n\t/**\n\t * Tells if this cancellable token is cancelled\n\t */\n\treadonly cancelled: boolean;\n\t/**\n\t * Promise that gets fulfilled when this cancellable token is cancelled\n\t * @returns reason of cancellation\n\t */\n\treadonly waitCancelled: Promise<T>;\n}\n\n/**\n * Similar to AbortSignal, but using promise instead of events\n * @internal\n */\nexport type ISummaryCancellationToken = ICancellationToken<SummarizerStopReason>;\n\n/**\n * Data required to update internal tracking state after receiving a Summary Ack.\n * @internal\n */\nexport interface IRefreshSummaryAckOptions {\n\t/**\n\t * Handle from the ack's summary op.\n\t */\n\treadonly proposalHandle: string | undefined;\n\t/**\n\t * Handle from the summary ack just received\n\t */\n\treadonly ackHandle: string;\n\t/**\n\t * Reference sequence number from the ack's summary op\n\t */\n\treadonly summaryRefSeq: number;\n\t/**\n\t * Telemetry logger to which telemetry events will be forwarded.\n\t */\n\treadonly summaryLogger: ITelemetryLoggerExt;\n}\n\n/**\n * @internal\n */\nexport interface ISummarizerInternalsProvider {\n\t/**\n\t * Encapsulates the work to walk the internals of the running container to generate a summary\n\t */\n\tsubmitSummary(options: ISubmitSummaryOptions): Promise<SubmitSummaryResult>;\n\n\t/**\n\t * Callback whenever a new SummaryAck is received, to update internal tracking state\n\t */\n\trefreshLatestSummaryAck(options: IRefreshSummaryAckOptions): Promise<void>;\n}\n\n/**\n * @internal\n */\nexport interface ISummarizingWarning extends ContainerWarning {\n\treadonly errorType: \"summarizingError\";\n\treadonly logged: boolean;\n}\n\n/**\n * @internal\n */\nexport interface IConnectableRuntime {\n\treadonly disposed: boolean;\n\treadonly connected: boolean;\n\treadonly clientId: string | undefined;\n\tonce(event: \"connected\" | \"disconnected\" | \"dispose\", listener: () => void): this;\n}\n\n/**\n * @internal\n */\nexport interface ISummarizerRuntime extends IConnectableRuntime {\n\treadonly baseLogger: ITelemetryBaseLogger;\n\t/**\n\t * clientId of parent (non-summarizing) container that owns summarizer container\n\t */\n\treadonly summarizerClientId: string | undefined;\n\treadonly deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;\n\tdisposeFn(): void;\n\tcloseFn(): void;\n\ton(\n\t\tevent: \"op\",\n\t\tlistener: (op: ISequencedDocumentMessage, runtimeMessage?: boolean) => void,\n\t): this;\n\toff(\n\t\tevent: \"op\",\n\t\tlistener: (op: ISequencedDocumentMessage, runtimeMessage?: boolean) => void,\n\t): this;\n}\n\n/**\n * Options affecting summarize behavior.\n * @legacy @beta\n */\nexport interface ISummarizeOptions {\n\t/**\n\t * True to generate the full tree with no handle reuse optimizations; defaults to false\n\t */\n\treadonly fullTree?: boolean;\n}\n\n/**\n * @internal\n */\nexport interface ISubmitSummaryOptions extends ISummarizeOptions {\n\t/**\n\t * Logger to use for correlated summary events\n\t */\n\treadonly summaryLogger: ITelemetryLoggerExt;\n\t/**\n\t * Tells when summary process should be cancelled\n\t */\n\treadonly cancellationToken: ISummaryCancellationToken;\n\t/**\n\t * Summarization may be attempted multiple times. This tells whether this is the final summarization attempt.\n\t */\n\treadonly finalAttempt?: boolean;\n\t/**\n\t * The sequence number of the latest summary used to validate if summary state is correct before summarizing\n\t */\n\treadonly latestSummaryRefSeqNum: number;\n\t/**\n\t * Shared telemetry context for the current summarize attempt.\n\t */\n\ttelemetryContext?: TelemetryContext;\n}\n\n/**\n * @legacy @beta\n */\nexport interface IOnDemandSummarizeOptions extends ISummarizeOptions {\n\t/**\n\t * Reason for generating summary.\n\t */\n\treadonly reason: string;\n\t/**\n\t * In case of a failure, will attempt to retry based on if the failure is retriable.\n\t */\n\treadonly retryOnFailure?: boolean;\n}\n\n/**\n * Options to use when enqueueing a summarize attempt.\n * @legacy @beta\n */\nexport interface IEnqueueSummarizeOptions extends IOnDemandSummarizeOptions {\n\t/**\n\t * If specified, The summarize attempt will not occur until after this sequence number.\n\t */\n\treadonly afterSequenceNumber?: number;\n\n\t/**\n\t * True to override the existing enqueued summarize attempt if there is one.\n\t * This will guarantee that this attempt gets enqueued. If override is false,\n\t * than an existing enqueued summarize attempt will block a new one from being\n\t * enqueued. There can only be one enqueued at a time. Defaults to false.\n\t */\n\treadonly override?: boolean;\n}\n\n/**\n * In addition to the normal summary tree + stats, this contains additional stats\n * only relevant at the root of the tree.\n * @legacy @beta\n */\nexport interface IGeneratedSummaryStats extends ISummaryStats {\n\t/**\n\t * The total number of data stores in the container.\n\t */\n\treadonly dataStoreCount: number;\n\t/**\n\t * The number of data stores that were summarized in this summary.\n\t */\n\treadonly summarizedDataStoreCount: number;\n\t/**\n\t * The number of data stores whose GC reference state was updated in this summary.\n\t */\n\treadonly gcStateUpdatedDataStoreCount?: number;\n\t/**\n\t * The size of the gc blobs in this summary.\n\t */\n\treadonly gcTotalBlobsSize?: number;\n\t/**\n\t * The number of gc blobs in this summary.\n\t */\n\treadonly gcBlobNodeCount?: number;\n\t/**\n\t * The summary number for a container's summary. Incremented on summaries throughout its lifetime.\n\t */\n\treadonly summaryNumber: number;\n}\n\n/**\n * Type for summarization failures that are retriable.\n * @legacy @beta\n */\nexport interface IRetriableFailureError extends Error {\n\treadonly retryAfterSeconds?: number;\n}\n\n/**\n * Base results for all submitSummary attempts.\n * @legacy @beta\n */\nexport interface IBaseSummarizeResult {\n\treadonly stage: \"base\";\n\t/**\n\t * Retriable error object related to failed summarize attempt.\n\t */\n\treadonly error: IRetriableFailureError | undefined;\n\t/**\n\t * Reference sequence number as of the generate summary attempt.\n\t */\n\treadonly referenceSequenceNumber: number;\n\treadonly minimumSequenceNumber: number;\n}\n\n/**\n * Results of submitSummary after generating the summary tree.\n * @legacy @beta\n */\nexport interface IGenerateSummaryTreeResult extends Omit<IBaseSummarizeResult, \"stage\"> {\n\treadonly stage: \"generate\";\n\t/**\n\t * Generated summary tree.\n\t */\n\treadonly summaryTree: ISummaryTree;\n\t/**\n\t * Stats for generated summary tree.\n\t */\n\treadonly summaryStats: IGeneratedSummaryStats;\n\t/**\n\t * Time it took to generate the summary tree and stats.\n\t */\n\treadonly generateDuration: number;\n}\n\n/**\n * Results of submitSummary after uploading the tree to storage.\n * @legacy @beta\n */\nexport interface IUploadSummaryResult extends Omit<IGenerateSummaryTreeResult, \"stage\"> {\n\treadonly stage: \"upload\";\n\t/**\n\t * The handle returned by storage pointing to the uploaded summary tree.\n\t */\n\treadonly handle: string;\n\t/**\n\t * Time it took to upload the summary tree to storage.\n\t */\n\treadonly uploadDuration: number;\n}\n\n/**\n * Results of submitSummary after submitting the summarize op.\n * @legacy @beta\n */\nexport interface ISubmitSummaryOpResult extends Omit<IUploadSummaryResult, \"stage\" | \"error\"> {\n\treadonly stage: \"submit\";\n\t/**\n\t * The client sequence number of the summarize op submitted for the summary.\n\t */\n\treadonly clientSequenceNumber: number;\n\t/**\n\t * Time it took to submit the summarize op to the broadcasting service.\n\t */\n\treadonly submitOpDuration: number;\n}\n\n/**\n * Strict type representing result of a submitSummary attempt.\n * The result consists of 4 possible stages, each with its own data.\n * The data is cumulative, so each stage will contain the data from the previous stages.\n * If the final \"submitted\" stage is not reached, the result may contain the error object.\n *\n * Stages:\n *\n * 1. \"base\" - stopped before the summary tree was even generated, and the result only contains the base data\n *\n * 2. \"generate\" - the summary tree was generated, and the result will contain that tree + stats\n *\n * 3. \"upload\" - the summary was uploaded to storage, and the result contains the server-provided handle\n *\n * 4. \"submit\" - the summarize op was submitted, and the result contains the op client sequence number.\n * @legacy @beta\n */\nexport type SubmitSummaryResult =\n\t| IBaseSummarizeResult\n\t| IGenerateSummaryTreeResult\n\t| IUploadSummaryResult\n\t| ISubmitSummaryOpResult;\n\n/**\n * The stages of Summarize, used to describe how far progress succeeded in case of a failure at a later stage.\n * @legacy @beta\n */\nexport type SummaryStage = SubmitSummaryResult[\"stage\"] | \"unknown\";\n\n/**\n * The data in summarizer result when submit summary stage fails.\n * @legacy @beta\n */\nexport interface SubmitSummaryFailureData {\n\tstage: SummaryStage;\n}\n\n/**\n * @legacy @beta\n */\nexport type SummarizeResultPart<TSuccess, TFailure = undefined> =\n\t| {\n\t\t\tsuccess: true;\n\t\t\tdata: TSuccess;\n\t  }\n\t| {\n\t\t\tsuccess: false;\n\t\t\tdata: TFailure | undefined;\n\t\t\tmessage: string;\n\t\t\terror: IRetriableFailureError;\n\t  };\n\n/**\n * @legacy @beta\n */\nexport interface ISummarizer extends IEventProvider<ISummarizerEvents> {\n\t/**\n\t * Allows {@link ISummarizer} to be used with our {@link @fluidframework/core-interfaces#FluidObject} pattern.\n\t */\n\treadonly ISummarizer?: ISummarizer;\n\n\t/*\n\t * Asks summarizer to move to exit.\n\t * Summarizer will finish current processes, which may take a while.\n\t * For example, summarizer may complete last summary before exiting.\n\t */\n\tstop(reason: SummarizerStopReason): void;\n\n\t/* Closes summarizer. Any pending processes (summary in flight) are abandoned. */\n\tclose(): void;\n\n\trun(onBehalfOf: string): Promise<SummarizerStopReason>;\n\n\t/**\n\t * Attempts to generate a summary on demand. If already running, takes no action.\n\t * @param options - options controlling the summarize attempt\n\t * @returns an alreadyRunning promise if a summarize attempt is already in progress,\n\t * which will resolve when the current attempt completes. At that point caller can\n\t * decide to try again or not. Otherwise, it will return an object containing promises\n\t * that resolve as the summarize attempt progresses. They will resolve with success\n\t * false if a failure is encountered.\n\t */\n\tsummarizeOnDemand(options: IOnDemandSummarizeOptions): ISummarizeResults;\n\t/**\n\t * Enqueue an attempt to summarize after the specified sequence number.\n\t * If afterSequenceNumber is provided, the summarize attempt is \"enqueued\"\n\t * to run once an eligible op comes in with sequenceNumber \\>= afterSequenceNumber.\n\t * @param options - options controlling the summarize attempt\n\t * @returns an object containing an alreadyEnqueued flag to indicate if another\n\t * summarize attempt has already been enqueued. It also may contain an overridden flag\n\t * when alreadyEnqueued is true, that indicates whether this attempt forced the\n\t * previous attempt to abort. If this attempt becomes enqueued, it returns an object\n\t * containing promises that resolve as the summarize attempt progresses. They will\n\t * resolve with success false if a failure is encountered.\n\t */\n\tenqueueSummarize(options: IEnqueueSummarizeOptions): EnqueueSummarizeResult;\n}\n\n/**\n * Data about an attempt to summarize used for heuristics.\n */\nexport interface ISummarizeAttempt {\n\t/**\n\t * Reference sequence number when summary was generated or attempted\n\t */\n\treadonly refSequenceNumber: number;\n\n\t/**\n\t * Time of summary attempt after it was sent or attempted\n\t */\n\treadonly summaryTime: number;\n\n\t/**\n\t * Sequence number of summary op\n\t */\n\tsummarySequenceNumber?: number;\n}\n\n/**\n * Data relevant for summary heuristics.\n */\nexport interface ISummarizeHeuristicData {\n\t/**\n\t * Latest received op sequence number\n\t */\n\tlastOpSequenceNumber: number;\n\n\t/**\n\t * Most recent summary attempt from this client\n\t */\n\treadonly lastAttempt: ISummarizeAttempt;\n\n\t/**\n\t * Most recent summary that received an ack\n\t */\n\treadonly lastSuccessfulSummary: Readonly<ISummarizeAttempt>;\n\n\t/**\n\t * Number of runtime ops since last summary\n\t */\n\tnumRuntimeOps: number;\n\n\t/**\n\t * Number of non-runtime ops since last summary\n\t */\n\tnumNonRuntimeOps: number;\n\n\t/**\n\t * Cumulative size in bytes of all the ops since the last summary\n\t */\n\ttotalOpsSize: number;\n\n\t/**\n\t * Wether or not this instance contains adjusted metrics due to missing op data\n\t */\n\thasMissingOpData: boolean;\n\n\t/**\n\t * Updates lastAttempt and lastSuccessfulAttempt based on the last summary.\n\t * @param lastSummary - last ack summary\n\t */\n\tupdateWithLastSummaryAckInfo(lastSummary: ISummarizeAttempt): void;\n\n\t/**\n\t * Records a summary attempt. If the attempt was successfully sent,\n\t * provide the reference sequence number, otherwise it will be set\n\t * to the last seen op sequence number.\n\t * @param referenceSequenceNumber - reference sequence number of sent summary\n\t */\n\trecordAttempt(referenceSequenceNumber?: number): void;\n\n\t/**\n\t * Mark that the last sent summary attempt has received an ack\n\t */\n\tmarkLastAttemptAsSuccessful(): void;\n\n\topsSinceLastSummary: number;\n}\n\n/**\n * Responsible for running heuristics determining when to summarize.\n */\nexport interface ISummarizeHeuristicRunner {\n\t/**\n\t * Start specific heuristic trackers (ex: idle timer)\n\t */\n\tstart(): void;\n\n\t/**\n\t * Runs the heuristics to determine if it should try to summarize\n\t */\n\trun(): void;\n\n\t/**\n\t * Runs a different heuristic to check if it should summarize before closing\n\t */\n\tshouldRunLastSummary(): boolean;\n\n\t/**\n\t * Disposes of resources\n\t */\n\tdispose(): void;\n}\n\ntype ISummarizeTelemetryRequiredProperties =\n\t/**\n\t * Reason code for attempting to summarize\n\t */\n\t\"summarizeReason\";\n\ntype ISummarizeTelemetryOptionalProperties =\n\t/**\n\t * Number of attempts within the last time window, used for calculating the throttle delay.\n\t */\n\t| \"summaryAttempts\"\n\t/**\n\t * Summarization may be attempted multiple times. This tells whether this is the final summarization attempt\n\t */\n\t| \"finalAttempt\"\n\t| keyof ISummarizeOptions;\n\nexport type ISummarizeTelemetryProperties = Pick<\n\tITelemetryBaseProperties,\n\tISummarizeTelemetryRequiredProperties\n> &\n\tPartial<Pick<ITelemetryBaseProperties, ISummarizeTelemetryOptionalProperties>>;\n\n/**\n * Strategy used to heuristically determine when we should run a summary\n */\nexport interface ISummaryHeuristicStrategy {\n\t/**\n\t * Summarize reason for this summarize heuristic strategy (ex: \"maxTime\")\n\t */\n\tsummarizeReason: Readonly<SummarizeReason>;\n\n\t/**\n\t * Determines if this strategy's summarize criteria been met\n\t * @param configuration - summary configuration we are to check against\n\t * @param heuristicData - heuristic data used to confirm conditions are met\n\t */\n\tshouldRunSummary(\n\t\tconfiguration: ISummaryConfigurationHeuristics,\n\t\theuristicData: ISummarizeHeuristicData,\n\t): boolean;\n}\n\ntype SummaryGeneratorRequiredTelemetryProperties =\n\t/**\n\t * True to generate the full tree with no handle reuse optimizations\n\t */\n\t| \"fullTree\"\n\t/**\n\t * Time since we last attempted to generate a summary\n\t */\n\t| \"timeSinceLastAttempt\"\n\t/**\n\t * Time since we last successfully generated a summary\n\t */\n\t| \"timeSinceLastSummary\";\n\ntype SummaryGeneratorOptionalTelemetryProperties =\n\t/**\n\t * Reference sequence number as of the generate summary attempt.\n\t */\n\t| \"referenceSequenceNumber\"\n\t/**\n\t * minimum sequence number (at the reference sequence number)\n\t */\n\t| \"minimumSequenceNumber\"\n\t/**\n\t * Delta between the current reference sequence number and the reference sequence number of the last attempt\n\t */\n\t| \"opsSinceLastAttempt\"\n\t/**\n\t * Delta between the current reference sequence number and the reference sequence number of the last summary\n\t */\n\t| \"opsSinceLastSummary\"\n\t/**\n\t * Delta in sum of op sizes between the current reference sequence number and the reference\n\t * sequence number of the last summary\n\t */\n\t| \"opsSizesSinceLastSummary\"\n\t/**\n\t * Delta between the number of non-runtime ops since the last summary\n\t */\n\t| \"nonRuntimeOpsSinceLastSummary\"\n\t/**\n\t * Delta between the number of runtime ops since the last summary\n\t */\n\t| \"runtimeOpsSinceLastSummary\"\n\t/**\n\t * Wether or not this instance contains adjusted metrics due to missing op data\n\t */\n\t| \"hasMissingOpData\"\n\t/**\n\t * Time it took to generate the summary tree and stats.\n\t */\n\t| \"generateDuration\"\n\t/**\n\t * The handle returned by storage pointing to the uploaded summary tree.\n\t */\n\t| \"handle\"\n\t/**\n\t * Time it took to upload the summary tree to storage.\n\t */\n\t| \"uploadDuration\"\n\t/**\n\t * The client sequence number of the summarize op submitted for the summary.\n\t */\n\t| \"clientSequenceNumber\"\n\t/**\n\t * Time it took for this summary to be acked after it was generated\n\t */\n\t| \"ackWaitDuration\"\n\t/**\n\t * Reference sequence number of the ack/nack message\n\t */\n\t| \"ackNackSequenceNumber\"\n\t/**\n\t * Actual sequence number of the summary op proposal.\n\t */\n\t| \"summarySequenceNumber\"\n\t/**\n\t * Optional Retry-After time in seconds. If specified, the client should wait this many seconds before retrying.\n\t */\n\t| \"nackRetryAfter\"\n\t/**\n\t * The stage at which the submit summary method failed at. This can help determine what type of failure we have\n\t */\n\t| \"stage\";\n\nexport type SummaryGeneratorTelemetry = Pick<\n\tITelemetryBaseProperties,\n\tSummaryGeneratorRequiredTelemetryProperties\n> &\n\tPartial<Pick<ITelemetryBaseProperties, SummaryGeneratorOptionalTelemetryProperties>>;\n\nexport interface ISummarizeRunnerTelemetry extends ITelemetryLoggerPropertyBag {\n\t/**\n\t * Number of times the summarizer run.\n\t */\n\tsummarizeCount: () => number;\n\t/**\n\t * Number of successful attempts to summarize.\n\t */\n\tsummarizerSuccessfulAttempts: () => number;\n}\n\n/**\n * @legacy @beta\n */\nexport interface ISummaryBaseConfiguration {\n\t/**\n\t * Delay before first attempt to spawn summarizing container.\n\t */\n\tinitialSummarizerDelayMs: number;\n\n\t/**\n\t * Defines the maximum allowed time to wait for a pending summary ack.\n\t * The maximum amount of time client will wait for a summarize is the minimum of\n\t * maxSummarizeAckWaitTime (currently 3 * 60 * 1000) and maxAckWaitTime.\n\t */\n\tmaxAckWaitTime: number;\n\t/**\n\t * Defines the maximum number of Ops in between Summaries that can be\n\t * allowed before forcibly electing a new summarizer client.\n\t */\n\tmaxOpsSinceLastSummary: number;\n}\n\n/**\n * @legacy @beta\n */\nexport interface ISummaryConfigurationHeuristics extends ISummaryBaseConfiguration {\n\tstate: \"enabled\";\n\t/**\n\t * Defines the maximum allowed time, since the last received Ack, before running the summary\n\t * with reason maxTime.\n\t * For example, say we receive ops one by one just before the idle time is triggered.\n\t * In this case, we still want to run a summary since it's been a while since the last summary.\n\t */\n\tmaxTime: number;\n\t/**\n\t * Defines the maximum number of Ops, since the last received Ack, that can be allowed\n\t * before running the summary with reason maxOps.\n\t */\n\tmaxOps: number;\n\t/**\n\t * Defines the minimum number of Ops, since the last received Ack, that can be allowed\n\t * before running the last summary.\n\t */\n\tminOpsForLastSummaryAttempt: number;\n\t/**\n\t * Defines the lower boundary for the allowed time in between summarizations.\n\t * Pairs with maxIdleTime to form a range.\n\t * For example, if we only receive 1 op, we don't want to have the same idle time as say 100 ops.\n\t * Based on the boundaries we set in minIdleTime and maxIdleTime, the idle time will change\n\t * linearly depending on the number of ops we receive.\n\t */\n\tminIdleTime: number;\n\t/**\n\t * Defines the upper boundary for the allowed time in between summarizations.\n\t * Pairs with minIdleTime to form a range.\n\t * For example, if we only receive 1 op, we don't want to have the same idle time as say 100 ops.\n\t * Based on the boundaries we set in minIdleTime and maxIdleTime, the idle time will change\n\t * linearly depending on the number of ops we receive.\n\t */\n\tmaxIdleTime: number;\n\t/**\n\t * Runtime op weight to use in heuristic summarizing.\n\t * This number is a multiplier on the number of runtime ops we process when running summarize heuristics.\n\t * For example: (multiplier) * (number of runtime ops) = weighted number of runtime ops\n\t */\n\truntimeOpWeight: number;\n\t/**\n\t * Non-runtime op weight to use in heuristic summarizing\n\t * This number is a multiplier on the number of non-runtime ops we process when running summarize heuristics.\n\t * For example: (multiplier) * (number of non-runtime ops) = weighted number of non-runtime ops\n\t */\n\tnonRuntimeOpWeight: number;\n\n\t/**\n\t * Number of ops since last summary needed before a non-runtime op can trigger running summary heuristics.\n\t *\n\t * Note: Any runtime ops sent before the threshold is reached will trigger heuristics normally.\n\t * This threshold ONLY applies to non-runtime ops triggering summaries.\n\t *\n\t * For example: Say the threshold is 20. Sending 19 non-runtime ops will not trigger any heuristic checks.\n\t * Sending the 20th non-runtime op will trigger the heuristic checks for summarizing.\n\t */\n\tnonRuntimeHeuristicThreshold?: number;\n}\n\n/**\n * @legacy @beta\n */\nexport interface ISummaryConfigurationDisableSummarizer {\n\tstate: \"disabled\";\n}\n\n/**\n * @legacy @beta\n */\nexport interface ISummaryConfigurationDisableHeuristics extends ISummaryBaseConfiguration {\n\tstate: \"disableHeuristics\";\n}\n\n/**\n * Configuration used internally to indicate on-demand summaries only (no election/heuristics).\n * @legacy @beta\n */\nexport interface ISummaryConfigurationWithSummaryOnRequest extends ISummaryBaseConfiguration {\n\tstate: \"summaryOnRequest\";\n}\n\n/**\n * @legacy @beta\n */\nexport type ISummaryConfiguration =\n\t| ISummaryConfigurationDisableSummarizer\n\t| ISummaryConfigurationDisableHeuristics\n\t| ISummaryConfigurationHeuristics\n\t| ISummaryConfigurationWithSummaryOnRequest;\n"]}
+{"version":3,"file":"summarizerTypes.js","sourceRoot":"","sources":["../../src/summary/summarizerTypes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAiCH,MAAM,CAAC,MAAM,oBAAoB,GAAG,YAAY,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type {\n\tIDeltaManager,\n\tContainerWarning,\n} from \"@fluidframework/container-definitions/internal\";\nimport type {\n\tISummarizerEvents,\n\tSummarizerStopReason,\n} from \"@fluidframework/container-runtime-definitions/internal\";\nimport type {\n\tIEventProvider,\n\tITelemetryBaseProperties,\n\tITelemetryBaseLogger,\n} from \"@fluidframework/core-interfaces\";\nimport type { ISummaryTree } from \"@fluidframework/driver-definitions\";\nimport type {\n\tIDocumentMessage,\n\tISequencedDocumentMessage,\n} from \"@fluidframework/driver-definitions/internal\";\nimport type { ISummaryStats } from \"@fluidframework/runtime-definitions/internal\";\nimport type { TelemetryContext } from \"@fluidframework/runtime-utils/internal\";\nimport type {\n\tITelemetryLoggerExt,\n\tITelemetryLoggerPropertyBag,\n} from \"@fluidframework/telemetry-utils/internal\";\n\nimport type { SummarizeReason } from \"./summarizerUtils.js\";\nimport type {\n\tEnqueueSummarizeResult,\n\tISummarizeResults,\n} from \"./summaryDelayLoadedModule/index.js\";\n\nexport const summarizerClientType = \"summarizer\";\n\n/**\n * Similar to AbortSignal, but using promise instead of events\n * @param T - cancellation reason type\n * @internal\n */\nexport interface ICancellationToken<T> {\n\t/**\n\t * Tells if this cancellable token is cancelled\n\t */\n\treadonly cancelled: boolean;\n\t/**\n\t * Promise that gets fulfilled when this cancellable token is cancelled\n\t * @returns reason of cancellation\n\t */\n\treadonly waitCancelled: Promise<T>;\n}\n\n/**\n * Similar to AbortSignal, but using promise instead of events\n * @internal\n */\nexport type ISummaryCancellationToken = ICancellationToken<SummarizerStopReason>;\n\n/**\n * Data required to update internal tracking state after receiving a Summary Ack.\n * @internal\n */\nexport interface IRefreshSummaryAckOptions {\n\t/**\n\t * Handle from the ack's summary op.\n\t */\n\treadonly proposalHandle: string | undefined;\n\t/**\n\t * Handle from the summary ack just received\n\t */\n\treadonly ackHandle: string;\n\t/**\n\t * Reference sequence number from the ack's summary op\n\t */\n\treadonly summaryRefSeq: number;\n\t/**\n\t * Telemetry logger to which telemetry events will be forwarded.\n\t */\n\treadonly summaryLogger: ITelemetryLoggerExt;\n}\n\n/**\n * @internal\n */\nexport interface ISummarizerInternalsProvider {\n\t/**\n\t * Encapsulates the work to walk the internals of the running container to generate a summary\n\t */\n\tsubmitSummary(options: ISubmitSummaryOptions): Promise<SubmitSummaryResult>;\n\n\t/**\n\t * Callback whenever a new SummaryAck is received, to update internal tracking state\n\t */\n\trefreshLatestSummaryAck(options: IRefreshSummaryAckOptions): Promise<void>;\n}\n\n/**\n * @internal\n */\nexport interface ISummarizingWarning extends ContainerWarning {\n\treadonly errorType: \"summarizingError\";\n\treadonly logged: boolean;\n}\n\n/**\n * @internal\n */\nexport interface IConnectableRuntime {\n\treadonly disposed: boolean;\n\treadonly connected: boolean;\n\treadonly clientId: string | undefined;\n\tonce(event: \"connected\" | \"disconnected\" | \"dispose\", listener: () => void): this;\n}\n\n/**\n * @internal\n */\nexport interface ISummarizerRuntime extends IConnectableRuntime {\n\treadonly baseLogger: ITelemetryBaseLogger;\n\t/**\n\t * clientId of parent (non-summarizing) container that owns summarizer container\n\t */\n\treadonly summarizerClientId: string | undefined;\n\treadonly deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;\n\t/**\n\t * Initiate disposal of the container.\n\t */\n\tdisposeFn(): void;\n\ton(\n\t\tevent: \"op\",\n\t\tlistener: (op: ISequencedDocumentMessage, runtimeMessage?: boolean) => void,\n\t): this;\n\toff(\n\t\tevent: \"op\",\n\t\tlistener: (op: ISequencedDocumentMessage, runtimeMessage?: boolean) => void,\n\t): this;\n}\n\n/**\n * Options affecting summarize behavior.\n * @legacy @beta\n */\nexport interface ISummarizeOptions {\n\t/**\n\t * True to generate the full tree with no handle reuse optimizations; defaults to false\n\t */\n\treadonly fullTree?: boolean;\n}\n\n/**\n * @internal\n */\nexport interface ISubmitSummaryOptions extends ISummarizeOptions {\n\t/**\n\t * Logger to use for correlated summary events\n\t */\n\treadonly summaryLogger: ITelemetryLoggerExt;\n\t/**\n\t * Tells when summary process should be cancelled\n\t */\n\treadonly cancellationToken: ISummaryCancellationToken;\n\t/**\n\t * Summarization may be attempted multiple times. This tells whether this is the final summarization attempt.\n\t */\n\treadonly finalAttempt?: boolean;\n\t/**\n\t * The sequence number of the latest summary used to validate if summary state is correct before summarizing\n\t */\n\treadonly latestSummaryRefSeqNum: number;\n\t/**\n\t * Shared telemetry context for the current summarize attempt.\n\t */\n\ttelemetryContext?: TelemetryContext;\n}\n\n/**\n * @legacy @beta\n */\nexport interface IOnDemandSummarizeOptions extends ISummarizeOptions {\n\t/**\n\t * Reason for generating summary.\n\t */\n\treadonly reason: string;\n\t/**\n\t * In case of a failure, will attempt to retry based on if the failure is retriable.\n\t */\n\treadonly retryOnFailure?: boolean;\n}\n\n/**\n * Options to use when enqueueing a summarize attempt.\n * @legacy @beta\n */\nexport interface IEnqueueSummarizeOptions extends IOnDemandSummarizeOptions {\n\t/**\n\t * If specified, The summarize attempt will not occur until after this sequence number.\n\t */\n\treadonly afterSequenceNumber?: number;\n\n\t/**\n\t * True to override the existing enqueued summarize attempt if there is one.\n\t * This will guarantee that this attempt gets enqueued. If override is false,\n\t * than an existing enqueued summarize attempt will block a new one from being\n\t * enqueued. There can only be one enqueued at a time. Defaults to false.\n\t */\n\treadonly override?: boolean;\n}\n\n/**\n * In addition to the normal summary tree + stats, this contains additional stats\n * only relevant at the root of the tree.\n * @legacy @beta\n */\nexport interface IGeneratedSummaryStats extends ISummaryStats {\n\t/**\n\t * The total number of data stores in the container.\n\t */\n\treadonly dataStoreCount: number;\n\t/**\n\t * The number of data stores that were summarized in this summary.\n\t */\n\treadonly summarizedDataStoreCount: number;\n\t/**\n\t * The number of data stores whose GC reference state was updated in this summary.\n\t */\n\treadonly gcStateUpdatedDataStoreCount?: number;\n\t/**\n\t * The size of the gc blobs in this summary.\n\t */\n\treadonly gcTotalBlobsSize?: number;\n\t/**\n\t * The number of gc blobs in this summary.\n\t */\n\treadonly gcBlobNodeCount?: number;\n\t/**\n\t * The summary number for a container's summary. Incremented on summaries throughout its lifetime.\n\t */\n\treadonly summaryNumber: number;\n}\n\n/**\n * Type for summarization failures that are retriable.\n * @legacy @beta\n */\nexport interface IRetriableFailureError extends Error {\n\treadonly retryAfterSeconds?: number;\n}\n\n/**\n * Base results for all submitSummary attempts.\n * @legacy @beta\n */\nexport interface IBaseSummarizeResult {\n\treadonly stage: \"base\";\n\t/**\n\t * Retriable error object related to failed summarize attempt.\n\t */\n\treadonly error: IRetriableFailureError | undefined;\n\t/**\n\t * Reference sequence number as of the generate summary attempt.\n\t */\n\treadonly referenceSequenceNumber: number;\n\treadonly minimumSequenceNumber: number;\n}\n\n/**\n * Results of submitSummary after generating the summary tree.\n * @legacy @beta\n */\nexport interface IGenerateSummaryTreeResult extends Omit<IBaseSummarizeResult, \"stage\"> {\n\treadonly stage: \"generate\";\n\t/**\n\t * Generated summary tree.\n\t */\n\treadonly summaryTree: ISummaryTree;\n\t/**\n\t * Stats for generated summary tree.\n\t */\n\treadonly summaryStats: IGeneratedSummaryStats;\n\t/**\n\t * Time it took to generate the summary tree and stats.\n\t */\n\treadonly generateDuration: number;\n}\n\n/**\n * Results of submitSummary after uploading the tree to storage.\n * @legacy @beta\n */\nexport interface IUploadSummaryResult extends Omit<IGenerateSummaryTreeResult, \"stage\"> {\n\treadonly stage: \"upload\";\n\t/**\n\t * The handle returned by storage pointing to the uploaded summary tree.\n\t */\n\treadonly handle: string;\n\t/**\n\t * Time it took to upload the summary tree to storage.\n\t */\n\treadonly uploadDuration: number;\n}\n\n/**\n * Results of submitSummary after submitting the summarize op.\n * @legacy @beta\n */\nexport interface ISubmitSummaryOpResult extends Omit<IUploadSummaryResult, \"stage\" | \"error\"> {\n\treadonly stage: \"submit\";\n\t/**\n\t * The client sequence number of the summarize op submitted for the summary.\n\t */\n\treadonly clientSequenceNumber: number;\n\t/**\n\t * Time it took to submit the summarize op to the broadcasting service.\n\t */\n\treadonly submitOpDuration: number;\n}\n\n/**\n * Strict type representing result of a submitSummary attempt.\n * The result consists of 4 possible stages, each with its own data.\n * The data is cumulative, so each stage will contain the data from the previous stages.\n * If the final \"submitted\" stage is not reached, the result may contain the error object.\n *\n * Stages:\n *\n * 1. \"base\" - stopped before the summary tree was even generated, and the result only contains the base data\n *\n * 2. \"generate\" - the summary tree was generated, and the result will contain that tree + stats\n *\n * 3. \"upload\" - the summary was uploaded to storage, and the result contains the server-provided handle\n *\n * 4. \"submit\" - the summarize op was submitted, and the result contains the op client sequence number.\n * @legacy @beta\n */\nexport type SubmitSummaryResult =\n\t| IBaseSummarizeResult\n\t| IGenerateSummaryTreeResult\n\t| IUploadSummaryResult\n\t| ISubmitSummaryOpResult;\n\n/**\n * The stages of Summarize, used to describe how far progress succeeded in case of a failure at a later stage.\n * @legacy @beta\n */\nexport type SummaryStage = SubmitSummaryResult[\"stage\"] | \"unknown\";\n\n/**\n * The data in summarizer result when submit summary stage fails.\n * @legacy @beta\n */\nexport interface SubmitSummaryFailureData {\n\tstage: SummaryStage;\n}\n\n/**\n * @legacy @beta\n */\nexport type SummarizeResultPart<TSuccess, TFailure = undefined> =\n\t| {\n\t\t\tsuccess: true;\n\t\t\tdata: TSuccess;\n\t  }\n\t| {\n\t\t\tsuccess: false;\n\t\t\tdata: TFailure | undefined;\n\t\t\tmessage: string;\n\t\t\terror: IRetriableFailureError;\n\t  };\n\n/**\n * @legacy @beta\n */\nexport interface ISummarizer extends IEventProvider<ISummarizerEvents> {\n\t/**\n\t * Allows {@link ISummarizer} to be used with our {@link @fluidframework/core-interfaces#FluidObject} pattern.\n\t */\n\treadonly ISummarizer?: ISummarizer;\n\n\t/*\n\t * Asks summarizer to move to exit.\n\t * Summarizer will finish current processes, which may take a while.\n\t * For example, summarizer may complete last summary before exiting.\n\t */\n\tstop(reason: SummarizerStopReason): void;\n\n\t/* Closes summarizer. Any pending processes (summary in flight) are abandoned. */\n\tclose(): void;\n\n\trun(onBehalfOf: string): Promise<SummarizerStopReason>;\n\n\t/**\n\t * Attempts to generate a summary on demand. If already running, takes no action.\n\t * @param options - options controlling the summarize attempt\n\t * @returns an alreadyRunning promise if a summarize attempt is already in progress,\n\t * which will resolve when the current attempt completes. At that point caller can\n\t * decide to try again or not. Otherwise, it will return an object containing promises\n\t * that resolve as the summarize attempt progresses. They will resolve with success\n\t * false if a failure is encountered.\n\t */\n\tsummarizeOnDemand(options: IOnDemandSummarizeOptions): ISummarizeResults;\n\t/**\n\t * Enqueue an attempt to summarize after the specified sequence number.\n\t * If afterSequenceNumber is provided, the summarize attempt is \"enqueued\"\n\t * to run once an eligible op comes in with sequenceNumber \\>= afterSequenceNumber.\n\t * @param options - options controlling the summarize attempt\n\t * @returns an object containing an alreadyEnqueued flag to indicate if another\n\t * summarize attempt has already been enqueued. It also may contain an overridden flag\n\t * when alreadyEnqueued is true, that indicates whether this attempt forced the\n\t * previous attempt to abort. If this attempt becomes enqueued, it returns an object\n\t * containing promises that resolve as the summarize attempt progresses. They will\n\t * resolve with success false if a failure is encountered.\n\t */\n\tenqueueSummarize(options: IEnqueueSummarizeOptions): EnqueueSummarizeResult;\n}\n\n/**\n * Data about an attempt to summarize used for heuristics.\n */\nexport interface ISummarizeAttempt {\n\t/**\n\t * Reference sequence number when summary was generated or attempted\n\t */\n\treadonly refSequenceNumber: number;\n\n\t/**\n\t * Time of summary attempt after it was sent or attempted\n\t */\n\treadonly summaryTime: number;\n\n\t/**\n\t * Sequence number of summary op\n\t */\n\tsummarySequenceNumber?: number;\n}\n\n/**\n * Data relevant for summary heuristics.\n */\nexport interface ISummarizeHeuristicData {\n\t/**\n\t * Latest received op sequence number\n\t */\n\tlastOpSequenceNumber: number;\n\n\t/**\n\t * Most recent summary attempt from this client\n\t */\n\treadonly lastAttempt: ISummarizeAttempt;\n\n\t/**\n\t * Most recent summary that received an ack\n\t */\n\treadonly lastSuccessfulSummary: Readonly<ISummarizeAttempt>;\n\n\t/**\n\t * Number of runtime ops since last summary\n\t */\n\tnumRuntimeOps: number;\n\n\t/**\n\t * Number of non-runtime ops since last summary\n\t */\n\tnumNonRuntimeOps: number;\n\n\t/**\n\t * Cumulative size in bytes of all the ops since the last summary\n\t */\n\ttotalOpsSize: number;\n\n\t/**\n\t * Wether or not this instance contains adjusted metrics due to missing op data\n\t */\n\thasMissingOpData: boolean;\n\n\t/**\n\t * Updates lastAttempt and lastSuccessfulAttempt based on the last summary.\n\t * @param lastSummary - last ack summary\n\t */\n\tupdateWithLastSummaryAckInfo(lastSummary: ISummarizeAttempt): void;\n\n\t/**\n\t * Records a summary attempt. If the attempt was successfully sent,\n\t * provide the reference sequence number, otherwise it will be set\n\t * to the last seen op sequence number.\n\t * @param referenceSequenceNumber - reference sequence number of sent summary\n\t */\n\trecordAttempt(referenceSequenceNumber?: number): void;\n\n\t/**\n\t * Mark that the last sent summary attempt has received an ack\n\t */\n\tmarkLastAttemptAsSuccessful(): void;\n\n\topsSinceLastSummary: number;\n}\n\n/**\n * Responsible for running heuristics determining when to summarize.\n */\nexport interface ISummarizeHeuristicRunner {\n\t/**\n\t * Start specific heuristic trackers (ex: idle timer)\n\t */\n\tstart(): void;\n\n\t/**\n\t * Runs the heuristics to determine if it should try to summarize\n\t */\n\trun(): void;\n\n\t/**\n\t * Runs a different heuristic to check if it should summarize before closing\n\t */\n\tshouldRunLastSummary(): boolean;\n\n\t/**\n\t * Disposes of resources\n\t */\n\tdispose(): void;\n}\n\ntype ISummarizeTelemetryRequiredProperties =\n\t/**\n\t * Reason code for attempting to summarize\n\t */\n\t\"summarizeReason\";\n\ntype ISummarizeTelemetryOptionalProperties =\n\t/**\n\t * Number of attempts within the last time window, used for calculating the throttle delay.\n\t */\n\t| \"summaryAttempts\"\n\t/**\n\t * Summarization may be attempted multiple times. This tells whether this is the final summarization attempt\n\t */\n\t| \"finalAttempt\"\n\t| keyof ISummarizeOptions;\n\nexport type ISummarizeTelemetryProperties = Pick<\n\tITelemetryBaseProperties,\n\tISummarizeTelemetryRequiredProperties\n> &\n\tPartial<Pick<ITelemetryBaseProperties, ISummarizeTelemetryOptionalProperties>>;\n\n/**\n * Strategy used to heuristically determine when we should run a summary\n */\nexport interface ISummaryHeuristicStrategy {\n\t/**\n\t * Summarize reason for this summarize heuristic strategy (ex: \"maxTime\")\n\t */\n\tsummarizeReason: Readonly<SummarizeReason>;\n\n\t/**\n\t * Determines if this strategy's summarize criteria been met\n\t * @param configuration - summary configuration we are to check against\n\t * @param heuristicData - heuristic data used to confirm conditions are met\n\t */\n\tshouldRunSummary(\n\t\tconfiguration: ISummaryConfigurationHeuristics,\n\t\theuristicData: ISummarizeHeuristicData,\n\t): boolean;\n}\n\ntype SummaryGeneratorRequiredTelemetryProperties =\n\t/**\n\t * True to generate the full tree with no handle reuse optimizations\n\t */\n\t| \"fullTree\"\n\t/**\n\t * Time since we last attempted to generate a summary\n\t */\n\t| \"timeSinceLastAttempt\"\n\t/**\n\t * Time since we last successfully generated a summary\n\t */\n\t| \"timeSinceLastSummary\";\n\ntype SummaryGeneratorOptionalTelemetryProperties =\n\t/**\n\t * Reference sequence number as of the generate summary attempt.\n\t */\n\t| \"referenceSequenceNumber\"\n\t/**\n\t * minimum sequence number (at the reference sequence number)\n\t */\n\t| \"minimumSequenceNumber\"\n\t/**\n\t * Delta between the current reference sequence number and the reference sequence number of the last attempt\n\t */\n\t| \"opsSinceLastAttempt\"\n\t/**\n\t * Delta between the current reference sequence number and the reference sequence number of the last summary\n\t */\n\t| \"opsSinceLastSummary\"\n\t/**\n\t * Delta in sum of op sizes between the current reference sequence number and the reference\n\t * sequence number of the last summary\n\t */\n\t| \"opsSizesSinceLastSummary\"\n\t/**\n\t * Delta between the number of non-runtime ops since the last summary\n\t */\n\t| \"nonRuntimeOpsSinceLastSummary\"\n\t/**\n\t * Delta between the number of runtime ops since the last summary\n\t */\n\t| \"runtimeOpsSinceLastSummary\"\n\t/**\n\t * Wether or not this instance contains adjusted metrics due to missing op data\n\t */\n\t| \"hasMissingOpData\"\n\t/**\n\t * Time it took to generate the summary tree and stats.\n\t */\n\t| \"generateDuration\"\n\t/**\n\t * The handle returned by storage pointing to the uploaded summary tree.\n\t */\n\t| \"handle\"\n\t/**\n\t * Time it took to upload the summary tree to storage.\n\t */\n\t| \"uploadDuration\"\n\t/**\n\t * The client sequence number of the summarize op submitted for the summary.\n\t */\n\t| \"clientSequenceNumber\"\n\t/**\n\t * Time it took for this summary to be acked after it was generated\n\t */\n\t| \"ackWaitDuration\"\n\t/**\n\t * Reference sequence number of the ack/nack message\n\t */\n\t| \"ackNackSequenceNumber\"\n\t/**\n\t * Actual sequence number of the summary op proposal.\n\t */\n\t| \"summarySequenceNumber\"\n\t/**\n\t * Optional Retry-After time in seconds. If specified, the client should wait this many seconds before retrying.\n\t */\n\t| \"nackRetryAfter\"\n\t/**\n\t * The stage at which the submit summary method failed at. This can help determine what type of failure we have\n\t */\n\t| \"stage\";\n\nexport type SummaryGeneratorTelemetry = Pick<\n\tITelemetryBaseProperties,\n\tSummaryGeneratorRequiredTelemetryProperties\n> &\n\tPartial<Pick<ITelemetryBaseProperties, SummaryGeneratorOptionalTelemetryProperties>>;\n\nexport interface ISummarizeRunnerTelemetry extends ITelemetryLoggerPropertyBag {\n\t/**\n\t * Number of times the summarizer run.\n\t */\n\tsummarizeCount: () => number;\n\t/**\n\t * Number of successful attempts to summarize.\n\t */\n\tsummarizerSuccessfulAttempts: () => number;\n}\n\n/**\n * @legacy @beta\n */\nexport interface ISummaryBaseConfiguration {\n\t/**\n\t * Delay before first attempt to spawn summarizing container.\n\t */\n\tinitialSummarizerDelayMs: number;\n\n\t/**\n\t * Defines the maximum allowed time to wait for a pending summary ack.\n\t * The maximum amount of time client will wait for a summarize is the minimum of\n\t * maxSummarizeAckWaitTime (currently 3 * 60 * 1000) and maxAckWaitTime.\n\t */\n\tmaxAckWaitTime: number;\n\t/**\n\t * Defines the maximum number of Ops in between Summaries that can be\n\t * allowed before forcibly electing a new summarizer client.\n\t */\n\tmaxOpsSinceLastSummary: number;\n}\n\n/**\n * @legacy @beta\n */\nexport interface ISummaryConfigurationHeuristics extends ISummaryBaseConfiguration {\n\tstate: \"enabled\";\n\t/**\n\t * Defines the maximum allowed time, since the last received Ack, before running the summary\n\t * with reason maxTime.\n\t * For example, say we receive ops one by one just before the idle time is triggered.\n\t * In this case, we still want to run a summary since it's been a while since the last summary.\n\t */\n\tmaxTime: number;\n\t/**\n\t * Defines the maximum number of Ops, since the last received Ack, that can be allowed\n\t * before running the summary with reason maxOps.\n\t */\n\tmaxOps: number;\n\t/**\n\t * Defines the minimum number of Ops, since the last received Ack, that can be allowed\n\t * before running the last summary.\n\t */\n\tminOpsForLastSummaryAttempt: number;\n\t/**\n\t * Defines the lower boundary for the allowed time in between summarizations.\n\t * Pairs with maxIdleTime to form a range.\n\t * For example, if we only receive 1 op, we don't want to have the same idle time as say 100 ops.\n\t * Based on the boundaries we set in minIdleTime and maxIdleTime, the idle time will change\n\t * linearly depending on the number of ops we receive.\n\t */\n\tminIdleTime: number;\n\t/**\n\t * Defines the upper boundary for the allowed time in between summarizations.\n\t * Pairs with minIdleTime to form a range.\n\t * For example, if we only receive 1 op, we don't want to have the same idle time as say 100 ops.\n\t * Based on the boundaries we set in minIdleTime and maxIdleTime, the idle time will change\n\t * linearly depending on the number of ops we receive.\n\t */\n\tmaxIdleTime: number;\n\t/**\n\t * Runtime op weight to use in heuristic summarizing.\n\t * This number is a multiplier on the number of runtime ops we process when running summarize heuristics.\n\t * For example: (multiplier) * (number of runtime ops) = weighted number of runtime ops\n\t */\n\truntimeOpWeight: number;\n\t/**\n\t * Non-runtime op weight to use in heuristic summarizing\n\t * This number is a multiplier on the number of non-runtime ops we process when running summarize heuristics.\n\t * For example: (multiplier) * (number of non-runtime ops) = weighted number of non-runtime ops\n\t */\n\tnonRuntimeOpWeight: number;\n\n\t/**\n\t * Number of ops since last summary needed before a non-runtime op can trigger running summary heuristics.\n\t *\n\t * Note: Any runtime ops sent before the threshold is reached will trigger heuristics normally.\n\t * This threshold ONLY applies to non-runtime ops triggering summaries.\n\t *\n\t * For example: Say the threshold is 20. Sending 19 non-runtime ops will not trigger any heuristic checks.\n\t * Sending the 20th non-runtime op will trigger the heuristic checks for summarizing.\n\t */\n\tnonRuntimeHeuristicThreshold?: number;\n}\n\n/**\n * @legacy @beta\n */\nexport interface ISummaryConfigurationDisableSummarizer {\n\tstate: \"disabled\";\n}\n\n/**\n * @legacy @beta\n */\nexport interface ISummaryConfigurationDisableHeuristics extends ISummaryBaseConfiguration {\n\tstate: \"disableHeuristics\";\n}\n\n/**\n * Configuration used internally to indicate on-demand summaries only (no election/heuristics).\n * @legacy @beta\n */\nexport interface ISummaryConfigurationWithSummaryOnRequest extends ISummaryBaseConfiguration {\n\tstate: \"summaryOnRequest\";\n}\n\n/**\n * @legacy @beta\n */\nexport type ISummaryConfiguration =\n\t| ISummaryConfigurationDisableSummarizer\n\t| ISummaryConfigurationDisableHeuristics\n\t| ISummaryConfigurationHeuristics\n\t| ISummaryConfigurationWithSummaryOnRequest;\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/container-runtime",
-  "version": "2.100.0",
+  "version": "2.101.1",
   "description": "Fluid container runtime",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -119,18 +119,18 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "~2.100.0",
-    "@fluidframework/container-definitions": "~2.100.0",
-    "@fluidframework/container-runtime-definitions": "~2.100.0",
-    "@fluidframework/core-interfaces": "~2.100.0",
-    "@fluidframework/core-utils": "~2.100.0",
-    "@fluidframework/datastore": "~2.100.0",
-    "@fluidframework/driver-definitions": "~2.100.0",
-    "@fluidframework/driver-utils": "~2.100.0",
-    "@fluidframework/id-compressor": "~2.100.0",
-    "@fluidframework/runtime-definitions": "~2.100.0",
-    "@fluidframework/runtime-utils": "~2.100.0",
-    "@fluidframework/telemetry-utils": "~2.100.0",
+    "@fluid-internal/client-utils": "~2.101.1",
+    "@fluidframework/container-definitions": "~2.101.1",
+    "@fluidframework/container-runtime-definitions": "~2.101.1",
+    "@fluidframework/core-interfaces": "~2.101.1",
+    "@fluidframework/core-utils": "~2.101.1",
+    "@fluidframework/datastore": "~2.101.1",
+    "@fluidframework/driver-definitions": "~2.101.1",
+    "@fluidframework/driver-utils": "~2.101.1",
+    "@fluidframework/id-compressor": "~2.101.1",
+    "@fluidframework/runtime-definitions": "~2.101.1",
+    "@fluidframework/runtime-utils": "~2.101.1",
+    "@fluidframework/telemetry-utils": "~2.101.1",
     "@tylerbu/sorted-btree-es6": "^2.1.1",
     "double-ended-queue": "^2.1.0-0",
     "lz4js": "^0.2.0",
@@ -140,16 +140,16 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
     "@biomejs/biome": "~2.4.5",
-    "@fluid-internal/mocha-test-setup": "~2.100.0",
-    "@fluid-private/stochastic-test-utils": "~2.100.0",
-    "@fluid-private/test-pairwise-generator": "~2.100.0",
-    "@fluid-tools/benchmark": "^0.58.0",
+    "@fluid-internal/mocha-test-setup": "~2.101.1",
+    "@fluid-private/stochastic-test-utils": "~2.101.1",
+    "@fluid-private/test-pairwise-generator": "~2.101.1",
+    "@fluid-tools/benchmark": "^0.59.0",
     "@fluid-tools/build-cli": "^0.65.0",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.65.0",
     "@fluidframework/container-runtime-previous": "npm:@fluidframework/container-runtime@2.92.0",
     "@fluidframework/eslint-config-fluid": "^9.0.0",
-    "@fluidframework/test-runtime-utils": "~2.100.0",
+    "@fluidframework/test-runtime-utils": "~2.101.1",
     "@microsoft/api-extractor": "7.58.1",
     "@types/double-ended-queue": "^2.1.0",
     "@types/lz4js": "^0.2.0",

package/src/blobManager/blobManager.ts

@@ -229,6 +229,9 @@ interface IBlobManagerInternalEvents {
 
 const createAbortError = (): LoggingError => new LoggingError("uploadBlob aborted");
 
+/**
+ * @internal
+ */
 export const blobManagerBasePath = "_blobs";
 
 export class BlobManager {

package/src/blobManager/blobManagerSnapSum.ts

@@ -18,6 +18,9 @@ export interface IBlobManagerLoadInfo {
 	redirectTable?: [string, string][];
 }
 
+/**
+ * @internal
+ */
 export const redirectTableBlobName = ".redirectTable";
 
 /**
@@ -57,11 +60,15 @@ export const toRedirectTable = (
 	blobManagerLoadInfo: IBlobManagerLoadInfo,
 	logger: ITelemetryLoggerExt,
 ): Map<string, string> => {
-	logger.sendTelemetryEvent({
-		eventName: "AttachmentBlobsLoaded",
-		count: blobManagerLoadInfo.ids?.length ?? 0,
-		redirectTable: blobManagerLoadInfo.redirectTable?.length,
-	});
+	const count = blobManagerLoadInfo.ids?.length ?? 0;
+	const redirectTableLength = blobManagerLoadInfo.redirectTable?.length ?? 0;
+	if (count > 0 || redirectTableLength > 0) {
+		logger.sendTelemetryEvent({
+			eventName: "AttachmentBlobsLoaded",
+			count,
+			redirectTable: redirectTableLength,
+		});
+	}
 	const redirectTable = new Map<string, string>(blobManagerLoadInfo.redirectTable);
 	if (blobManagerLoadInfo.ids !== undefined) {
 		for (const storageId of blobManagerLoadInfo.ids) {

package/src/connectionTelemetry.ts

@@ -7,6 +7,7 @@ import { performanceNow } from "@fluid-internal/client-utils";
 import type { IDeltaManagerFull } from "@fluidframework/container-definitions/internal";
 import type { IContainerRuntimeEvents } from "@fluidframework/container-runtime-definitions/internal";
 import type { ITelemetryBaseLogger, IEventProvider } from "@fluidframework/core-interfaces";
+import { LogLevel } from "@fluidframework/core-interfaces";
 import { assert } from "@fluidframework/core-utils/internal";
 import {
 	type IDocumentMessage,
@@ -303,16 +304,20 @@ class OpPerfTelemetry {
 
 	private reportGettingUpToDate(): void {
 		this.connectionOpSeqNumber = undefined;
-		this.logger.sendPerformanceEvent({
-			eventName: "ConnectionSpeed",
-			duration: performanceNow() - this.connectionStartTime,
-			ops: this.gap,
-			// track time to connect only for first connection.
-			timeToConnect: this.firstConnection
-				? formatTick(this.connectionStartTime - this.bootTime)
-				: undefined,
-			firstConnection: this.firstConnection,
-		});
+		this.logger.sendPerformanceEvent(
+			{
+				eventName: "ConnectionSpeed",
+				duration: performanceNow() - this.connectionStartTime,
+				ops: this.gap,
+				// track time to connect only for first connection.
+				timeToConnect: this.firstConnection
+					? formatTick(this.connectionStartTime - this.bootTime)
+					: undefined,
+				firstConnection: this.firstConnection,
+			},
+			undefined, // error
+			LogLevel.info,
+		);
 	}
 
 	private recordPingTime(latency: number): void {

package/src/containerRuntime.ts

@@ -57,6 +57,7 @@ import type {
 	ITelemetryBaseLogger,
 	Listenable,
 } from "@fluidframework/core-interfaces";
+import { LogLevel } from "@fluidframework/core-interfaces";
 import type {
 	IFluidHandleContext,
 	IFluidHandleInternal,
@@ -1335,7 +1336,12 @@ export class ContainerRuntime
 		targetClientId?: string,
 	) => void;
 	public readonly disposeFn: (error?: ICriticalContainerError) => void;
-	public readonly closeFn: (error?: ICriticalContainerError) => void;
+
+	/**
+	 * Initiate closing of the container due to a critical error.
+	 * @param error - The critical error that caused the container to close.
+	 */
+	private readonly closeFn: (error: ICriticalContainerError) => void;
 
 	public get flushMode(): FlushMode {
 		return this._flushMode;
@@ -1917,6 +1923,7 @@ export class ContainerRuntime
 
 		this.garbageCollector = GarbageCollector.create({
 			runtime: this,
+			closeFn: this.closeFn,
 			gcOptions: runtimeOptions.gcOptions,
 			baseSnapshot,
 			baseLogger: this.mc.logger,
@@ -2133,13 +2140,6 @@ export class ContainerRuntime
 		// (We have to call flush _before_ processing a runtime op, but after is ok for non-runtime op)
 		this.deltaManager.on("op", () => this.flush());
 
-		// logging hardware telemetry
-		this.baseLogger.send({
-			category: "generic",
-			eventName: "DeviceSpec",
-			...getDeviceSpec(),
-		});
-
 		this.mc.logger.sendTelemetryEvent({
 			eventName: "ContainerLoadStats",
 			...this.createContainerMetadata,
@@ -2162,6 +2162,8 @@ export class ContainerRuntime
 			groupedBatchingEnabled: this.groupedBatchingEnabled,
 			initialSequenceNumber: this.deltaManager.initialSequenceNumber,
 			minVersionForCollab: this.minVersionForCollab,
+			// logging hardware telemetry
+			deviceSpec: { ...getDeviceSpec() },
 		});
 
 		ReportOpPerfTelemetry(this.clientId, this._deltaManager, this, this.baseLogger);
@@ -2395,12 +2397,18 @@ export class ContainerRuntime
 		}
 	}
 
+	public close(): void {
+		this.garbageCollector.dispose();
+	}
+
 	public dispose(error?: Error): void {
 		if (this._disposed) {
 			return;
 		}
 		this._disposed = true;
 
+		// The ContainerRuntimeDisposed event is redundant with the loader's ContainerDispose event
+		// (see #27126) and can be removed once the change for ContainerDispose has saturated in telemetry.
 		this.mc.logger.sendTelemetryEvent(
 			{
 				eventName: "ContainerRuntimeDisposed",
@@ -2409,6 +2417,7 @@ export class ContainerRuntime
 				attachState: this.attachState,
 			},
 			error,
+			LogLevel.info,
 		);
 
 		if (this.summaryManager !== undefined) {

package/src/gc/garbageCollection.ts

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
+import type { ICriticalContainerError } from "@fluidframework/container-definitions";
 import type { IRequest } from "@fluidframework/core-interfaces";
 import { assert, LazyPromise, Timer } from "@fluidframework/core-utils/internal";
 import type { ISnapshotTree } from "@fluidframework/driver-definitions/internal";
@@ -141,6 +142,10 @@ export class GarbageCollector implements IGarbageCollector {
 	private completedRuns = 0;
 
 	private readonly runtime: IGarbageCollectionRuntime;
+	/**
+	 * Called when the runtime should close because of an error.
+	 */
+	private readonly closeFn: (error: ICriticalContainerError) => void;
 	private readonly isSummarizerClient: boolean;
 
 	private readonly summaryStateTracker: GCSummaryStateTracker;
@@ -168,6 +173,7 @@ export class GarbageCollector implements IGarbageCollector {
 
 	protected constructor(createParams: IGarbageCollectorCreateParams) {
 		this.runtime = createParams.runtime;
+		this.closeFn = createParams.closeFn;
 		this.isSummarizerClient = createParams.isSummarizerClient;
 		this.getNodePackagePath = createParams.getNodePackagePath;
 		this.getLastSummaryTimestampMs = createParams.getLastSummaryTimestampMs;
@@ -202,14 +208,10 @@ export class GarbageCollector implements IGarbageCollector {
 			}
 			timeoutMs = overrideSessionExpiryTimeoutMs ?? timeoutMs;
 			if (timeoutMs <= 0) {
-				this.runtime.closeFn(
-					new ClientSessionExpiredError(`Client session expired.`, timeoutMs),
-				);
+				this.closeFn(new ClientSessionExpiredError(`Client session expired.`, timeoutMs));
 			}
 			this.sessionExpiryTimer = new Timer(timeoutMs, () => {
-				this.runtime.closeFn(
-					new ClientSessionExpiredError(`Client session expired.`, timeoutMs),
-				);
+				this.closeFn(new ClientSessionExpiredError(`Client session expired.`, timeoutMs));
 			});
 			this.sessionExpiryTimer.start();
 			this.sessionExpiryTimerStarted = Date.now();

package/src/gc/gcDefinitions.ts

@@ -363,10 +363,6 @@ export interface IGarbageCollectionRuntime {
 	 * Returns the type of the GC node.
 	 */
 	getNodeType(nodePath: string): GCNodeType;
-	/**
-	 * Called when the runtime should close because of an error.
-	 */
-	closeFn: (error?: ICriticalContainerError) => void;
 }
 
 /**
@@ -453,6 +449,12 @@ export interface IGarbageCollector {
 	 */
 	isNodeDeleted(nodePath: string): boolean;
 	setConnectionState(canSendOps: boolean, clientId?: string): void;
+	/**
+	 * Cancels all GC timers and clears tracked state so timers do not keep the event loop alive
+	 * or leak memory.
+	 * @remarks
+	 * This is idempotent - it is safe to call multiple times.
+	 */
 	dispose(): void;
 }
 
@@ -497,6 +499,11 @@ export interface IGCNodeUpdatedProps {
  */
 export interface IGarbageCollectorCreateParams {
 	readonly runtime: IGarbageCollectionRuntime;
+	/**
+	 * Initiate closing of the container due to an error.
+	 */
+	readonly closeFn: (error: ICriticalContainerError) => void;
+
 	readonly gcOptions: IGCRuntimeOptions;
 	readonly baseLogger: ITelemetryLoggerExt;
 	readonly existing: boolean;

package/src/index.ts

@@ -30,6 +30,11 @@ export type {
 } from "./messageTypes.js";
 export { ContainerMessageType } from "./messageTypes.js";
 export type { IBlobManagerLoadInfo } from "./blobManager/index.js";
+export {
+	blobManagerBasePath,
+	blobsTreeName,
+	redirectTableBlobName,
+} from "./blobManager/index.js";
 export type { IDataStoreAliasMessage } from "./dataStore.js";
 export { FluidDataStoreRegistry } from "./dataStoreRegistry.js";
 export {

package/src/metadata.ts

@@ -40,6 +40,20 @@ export interface IBatchMetadata {
 	 * Maybe set on first message of a batch, to the batchId generated when resubmitting (set/fixed on first resubmit)
 	 */
 	batchId?: BatchId;
+	/**
+	 * Set on the envelope of a grouped batch op to the number of inner ops it contains.
+	 * Exposed on the wire so consumers can record batch sizes in telemetry without parsing the grouped batch contents.
+	 *
+	 * Observable values:
+	 * - Absent: either this is not a grouped batch envelope (e.g. a singleton batch that bypassed grouping), OR the producing runtime predates this field. Until the rollout is complete, telemetry consumers should treat absence as ambiguous and parse the envelope contents if a precise count is required for a grouped batch.
+	 * - `0`: empty-grouped-batch placeholder produced when a resubmitted batch becomes empty.
+	 * - `N` (N \> 0): grouped batch with N inner ops. For a chunked grouped batch this appears only on the last chunk's envelope (intermediate chunks carry no metadata).
+	 *
+	 * The field is intentionally advisory-only: the runtime does not validate that an inbound value matches the batch's actual inner op count. It is consumed exclusively by off-runtime telemetry.
+	 *
+	 * The field is always (re)stamped at outbound time from the current batch's actual size — `groupBatch` reads `batch.messages.length` directly, `createEmptyGroupedBatch` always writes `0`, and the chunking path only ever sees freshly-grouped envelopes from the same flush. It is never propagated from stashed pending state to the wire: on resubmit, ops re-enter grouping and the count is recomputed from the (possibly squashed, dropped, or added) outbound batch. This means the wire value always reflects the actual outbound size, even when the resubmitted batch differs from the original.
+	 */
+	groupedOpCount?: number;
 }
 
 /**

package/src/opLifecycle/opGroupingManager.ts

@@ -100,7 +100,7 @@ export class OpGroupingManager {
 		const serializedOp = JSON.stringify(emptyGroupedBatch);
 
 		const placeholderMessage: LocalEmptyBatchPlaceholder = {
-			metadata: { batchId: resubmittingBatchId },
+			metadata: { batchId: resubmittingBatchId, groupedOpCount: 0 },
 			localOpMetadata: { emptyBatch: true },
 			referenceSequenceNumber,
 			runtimeOp: emptyGroupedBatch,
@@ -169,7 +169,7 @@ export class OpGroupingManager {
 			...batch,
 			messages: [
 				{
-					metadata: { batchId: groupedBatchId },
+					metadata: { batchId: groupedBatchId, groupedOpCount: batch.messages.length },
 					referenceSequenceNumber: batch.messages[0].referenceSequenceNumber,
 					contents: serializedContent,
 				},

package/src/opLifecycle/opSplitter.ts

@@ -171,12 +171,22 @@ export class OpSplitter {
 			);
 		}
 
-		// The last chunk will be part of the new batch and needs to
-		// preserve the batch metadata of the original batch
+		// The last chunk will be part of the new batch and needs to preserve the
+		// batch metadata of the original batch. groupedOpCount is surfaced here
+		// (and only here, not on intermediate chunks) because intermediate chunks
+		// don't carry ops — they carry parts of a payload that only become ops
+		// once the last chunk is processed and the payload is reassembled.
+		// Stamping every chunk would let an observer double-count messages.
+		// batchId is deliberately not forwarded — it's a runtime dedup field
+		// consumed only after processChunk restores originalMetadata, not by
+		// wire observers.
 		const lastChunk = chunkToBatchMessage(
 			chunks[chunks.length - 1],
 			batch.referenceSequenceNumber,
-			{ batch: firstMessage.metadata?.batch },
+			{
+				batch: firstMessage.metadata?.batch,
+				groupedOpCount: firstMessage.metadata?.groupedOpCount,
+			},
 		);
 
 		this.logger.sendPerformanceEvent({

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/container-runtime";
-export const pkgVersion = "2.100.0";
+export const pkgVersion = "2.101.1";

package/src/summary/summarizerTypes.ts

@@ -125,8 +125,10 @@ export interface ISummarizerRuntime extends IConnectableRuntime {
 	 */
 	readonly summarizerClientId: string | undefined;
 	readonly deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;
+	/**
+	 * Initiate disposal of the container.
+	 */
 	disposeFn(): void;
-	closeFn(): void;
 	on(
 		event: "op",
 		listener: (op: ISequencedDocumentMessage, runtimeMessage?: boolean) => void,