@fluidframework/tree 2.53.1 → 2.60.0

package/dist/feature-libraries/forest-summary/forestSummarizer.js.map

@@ -1 +1 @@
-{"version":3,"file":"forestSummarizer.js","sourceRoot":"","sources":["../../../src/feature-libraries/forest-summary/forestSummarizer.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { bufferToString } from \"@fluid-internal/client-utils\";\nimport { assert } from \"@fluidframework/core-utils/internal\";\nimport type { IChannelStorageService } from \"@fluidframework/datastore-definitions/internal\";\nimport type { IIdCompressor } from \"@fluidframework/id-compressor\";\nimport type {\n\tIExperimentalIncrementalSummaryContext,\n\tISummaryTreeWithStats,\n\tITelemetryContext,\n} from \"@fluidframework/runtime-definitions/internal\";\nimport { createSingleBlobSummary } from \"@fluidframework/shared-object-base/internal\";\n\nimport type { CodecWriteOptions } from \"../../codec/index.js\";\nimport {\n\ttype DeltaDetachedNodeBuild,\n\ttype DeltaFieldChanges,\n\ttype FieldKey,\n\ttype IEditableForest,\n\ttype ITreeCursorSynchronous,\n\ttype ITreeSubscriptionCursor,\n\ttype RevisionTagCodec,\n\tTreeNavigationResult,\n\tapplyDelta,\n\tforEachField,\n\tmakeDetachedFieldIndex,\n} from \"../../core/index.js\";\nimport type {\n\tSummarizable,\n\tSummaryElementParser,\n\tSummaryElementStringifier,\n} from \"../../shared-tree-core/index.js\";\nimport { idAllocatorFromMaxId } from \"../../util/index.js\";\nimport { chunkFieldSingle, defaultChunkPolicy } from \"../chunked-forest/index.js\";\nimport type { FieldBatchCodec, FieldBatchEncodingContext } from \"../chunked-forest/index.js\";\n\nimport { type ForestCodec, makeForestSummarizerCodec } from \"./codec.js\";\nimport type { Format } from \"./format.js\";\n/**\n * The storage key for the blob in the summary containing tree data\n */\nexport const treeBlobKey = \"ForestTree\";\n\n/**\n * Provides methods for summarizing and loading a forest.\n */\nexport class ForestSummarizer implements Summarizable {\n\tpublic readonly key = \"Forest\";\n\n\tprivate readonly codec: ForestCodec;\n\n\t/**\n\t * @param encoderContext - The schema if provided here must be mutated by the caller to keep it up to date.\n\t */\n\tpublic constructor(\n\t\tprivate readonly forest: IEditableForest,\n\t\tprivate readonly revisionTagCodec: RevisionTagCodec,\n\t\tfieldBatchCodec: FieldBatchCodec,\n\t\tprivate readonly encoderContext: FieldBatchEncodingContext,\n\t\toptions: CodecWriteOptions,\n\t\tprivate readonly idCompressor: IIdCompressor,\n\t) {\n\t\t// TODO: this should take in CodecWriteOptions, and use it to pick the write version.\n\t\tthis.codec = makeForestSummarizerCodec(options, fieldBatchCodec);\n\t}\n\n\t/**\n\t * Synchronous monolithic summarization of tree content.\n\t *\n\t * TODO: when perf matters, this should be replaced with a chunked async version using a binary format.\n\t *\n\t * @returns a snapshot of the forest's tree as a string.\n\t */\n\tprivate getTreeString(stringify: SummaryElementStringifier): string {\n\t\tconst rootCursor = this.forest.getCursorAboveDetachedFields();\n\t\tconst fieldMap: Map<FieldKey, ITreeCursorSynchronous & ITreeSubscriptionCursor> =\n\t\t\tnew Map();\n\t\t// TODO: Encode all detached fields in one operation for better performance and compression\n\t\tforEachField(rootCursor, (cursor) => {\n\t\t\tconst key = cursor.getFieldKey();\n\t\t\tconst innerCursor = this.forest.allocateCursor(\"getTreeString\");\n\t\t\tassert(\n\t\t\t\tthis.forest.tryMoveCursorToField({ fieldKey: key, parent: undefined }, innerCursor) ===\n\t\t\t\t\tTreeNavigationResult.Ok,\n\t\t\t\t0x892 /* failed to navigate to field */,\n\t\t\t);\n\t\t\tfieldMap.set(key, innerCursor as ITreeCursorSynchronous & ITreeSubscriptionCursor);\n\t\t});\n\t\tconst encoded = this.codec.encode(fieldMap, this.encoderContext);\n\n\t\tfieldMap.forEach((value) => value.free());\n\t\treturn stringify(encoded);\n\t}\n\n\tpublic summarize(props: {\n\t\tstringify: SummaryElementStringifier;\n\t\tfullTree?: boolean;\n\t\ttrackState?: boolean;\n\t\ttelemetryContext?: ITelemetryContext;\n\t\tincrementalSummaryContext?: IExperimentalIncrementalSummaryContext;\n\t}): ISummaryTreeWithStats {\n\t\treturn createSingleBlobSummary(treeBlobKey, this.getTreeString(props.stringify));\n\t}\n\n\tpublic async load(\n\t\tservices: IChannelStorageService,\n\t\tparse: SummaryElementParser,\n\t): Promise<void> {\n\t\tif (await services.contains(treeBlobKey)) {\n\t\t\tconst treeBuffer = await services.readBlob(treeBlobKey);\n\t\t\tconst treeBufferString = bufferToString(treeBuffer, \"utf8\");\n\t\t\t// TODO: this code is parsing data without an optional validator, this should be defined in a typebox schema as part of the\n\t\t\t// forest summary format.\n\t\t\tconst fields = this.codec.decode(parse(treeBufferString) as Format, this.encoderContext);\n\t\t\tconst allocator = idAllocatorFromMaxId();\n\t\t\tconst fieldChanges: [FieldKey, DeltaFieldChanges][] = [];\n\t\t\tconst build: DeltaDetachedNodeBuild[] = [];\n\t\t\tfor (const [fieldKey, field] of fields) {\n\t\t\t\tconst chunked = chunkFieldSingle(field, {\n\t\t\t\t\tpolicy: defaultChunkPolicy,\n\t\t\t\t\tidCompressor: this.idCompressor,\n\t\t\t\t});\n\t\t\t\tconst buildId = { minor: allocator.allocate(chunked.topLevelLength) };\n\t\t\t\tbuild.push({\n\t\t\t\t\tid: buildId,\n\t\t\t\t\ttrees: chunked,\n\t\t\t\t});\n\t\t\t\tfieldChanges.push([fieldKey, [{ count: chunked.topLevelLength, attach: buildId }]]);\n\t\t\t}\n\n\t\t\tassert(this.forest.isEmpty, 0x797 /* forest must be empty */);\n\t\t\tapplyDelta(\n\t\t\t\t{ build, fields: new Map(fieldChanges) },\n\t\t\t\tundefined,\n\t\t\t\tthis.forest,\n\t\t\t\tmakeDetachedFieldIndex(\"init\", this.revisionTagCodec, this.idCompressor),\n\t\t\t);\n\t\t}\n\t}\n}\n"]}
+{"version":3,"file":"forestSummarizer.js","sourceRoot":"","sources":["../../../src/feature-libraries/forest-summary/forestSummarizer.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { bufferToString } from \"@fluid-internal/client-utils\";\nimport { assert } from \"@fluidframework/core-utils/internal\";\nimport type { IChannelStorageService } from \"@fluidframework/datastore-definitions/internal\";\nimport type { IIdCompressor } from \"@fluidframework/id-compressor\";\nimport type {\n\tIExperimentalIncrementalSummaryContext,\n\tISummaryTreeWithStats,\n\tITelemetryContext,\n} from \"@fluidframework/runtime-definitions/internal\";\n\nimport type { CodecWriteOptions } from \"../../codec/index.js\";\nimport {\n\ttype DeltaDetachedNodeBuild,\n\ttype DeltaFieldChanges,\n\ttype FieldKey,\n\ttype IEditableForest,\n\ttype ITreeCursorSynchronous,\n\ttype ITreeSubscriptionCursor,\n\ttype RevisionTagCodec,\n\tTreeNavigationResult,\n\ttype TreeNodeSchemaIdentifier,\n\tapplyDelta,\n\tforEachField,\n\tmakeDetachedFieldIndex,\n} from \"../../core/index.js\";\nimport type {\n\tSummarizable,\n\tSummaryElementParser,\n\tSummaryElementStringifier,\n} from \"../../shared-tree-core/index.js\";\nimport { idAllocatorFromMaxId, type JsonCompatible } from \"../../util/index.js\";\n// eslint-disable-next-line import/no-internal-modules\nimport { chunkFieldSingle, defaultChunkPolicy } from \"../chunked-forest/chunkTree.js\";\nimport type { FieldBatchCodec, FieldBatchEncodingContext } from \"../chunked-forest/index.js\";\n\nimport { type ForestCodec, makeForestSummarizerCodec } from \"./codec.js\";\nimport {\n\tForestIncrementalSummaryBehavior,\n\tForestIncrementalSummaryBuilder,\n\tforestSummaryContentKey,\n} from \"./incrementalSummaryBuilder.js\";\nimport { TreeCompressionStrategyExtended } from \"../treeCompressionUtils.js\";\nimport type { IFluidHandle } from \"@fluidframework/core-interfaces\";\n\n/**\n * The key for the tree that contains the overall forest's summary tree.\n * This tree is added by the parent of the forest summarizer.\n * See {@link ForestIncrementalSummaryBuilder} for details on the summary structure.\n */\nexport const forestSummaryKey = \"Forest\";\n\n/**\n * Provides methods for summarizing and loading a forest.\n */\nexport class ForestSummarizer implements Summarizable {\n\tpublic readonly key = forestSummaryKey;\n\n\tprivate readonly codec: ForestCodec;\n\n\tprivate readonly incrementalSummaryBuilder: ForestIncrementalSummaryBuilder;\n\n\t/**\n\t * @param encoderContext - The schema if provided here must be mutated by the caller to keep it up to date.\n\t */\n\tpublic constructor(\n\t\tprivate readonly forest: IEditableForest,\n\t\tprivate readonly revisionTagCodec: RevisionTagCodec,\n\t\tfieldBatchCodec: FieldBatchCodec,\n\t\tprivate readonly encoderContext: FieldBatchEncodingContext,\n\t\toptions: CodecWriteOptions,\n\t\tprivate readonly idCompressor: IIdCompressor,\n\t\tshouldEncodeFieldIncrementally?: (\n\t\t\tnodeIdentifier: TreeNodeSchemaIdentifier,\n\t\t\tfieldKey: FieldKey,\n\t\t) => boolean,\n\t) {\n\t\t// TODO: this should take in CodecWriteOptions, and use it to pick the write version.\n\t\tthis.codec = makeForestSummarizerCodec(options, fieldBatchCodec);\n\n\t\tconst shouldEncodeFieldIncrementallyLocal = (\n\t\t\tnodeIdentifier: TreeNodeSchemaIdentifier,\n\t\t\tfieldKey: FieldKey,\n\t\t): boolean => shouldEncodeFieldIncrementally?.(nodeIdentifier, fieldKey) ?? false;\n\t\tthis.incrementalSummaryBuilder = new ForestIncrementalSummaryBuilder(\n\t\t\tencoderContext.encodeType ===\n\t\t\t\tTreeCompressionStrategyExtended.CompressedIncremental /* enableIncrementalSummary */,\n\t\t\t(cursor: ITreeCursorSynchronous) => this.forest.chunkField(cursor),\n\t\t\tshouldEncodeFieldIncrementallyLocal,\n\t\t);\n\t}\n\n\t/**\n\t * Summarization of the forest's tree content.\n\t * @returns a summary tree containing the forest's tree content.\n\t * @remarks\n\t * If incremental summary is disabled, all the content will be added to a single summary blob.\n\t * If incremental summary is enabled, the summary will be a tree.\n\t * See {@link ForestIncrementalSummaryBuilder} for details of what this tree looks like.\n\t *\n\t * TODO: when perf matters, this should be replaced with a chunked async version using a binary format.\n\t */\n\tpublic summarize(props: {\n\t\tstringify: SummaryElementStringifier;\n\t\tfullTree?: boolean;\n\t\ttrackState?: boolean;\n\t\ttelemetryContext?: ITelemetryContext;\n\t\tincrementalSummaryContext?: IExperimentalIncrementalSummaryContext;\n\t}): ISummaryTreeWithStats {\n\t\tconst { stringify, fullTree = false, incrementalSummaryContext } = props;\n\n\t\tconst rootCursor = this.forest.getCursorAboveDetachedFields();\n\t\tconst fieldMap: Map<FieldKey, ITreeCursorSynchronous & ITreeSubscriptionCursor> =\n\t\t\tnew Map();\n\t\t// TODO: Encode all detached fields in one operation for better performance and compression\n\t\tforEachField(rootCursor, (cursor) => {\n\t\t\tconst key = cursor.getFieldKey();\n\t\t\tconst innerCursor = this.forest.allocateCursor(\"getTreeString\");\n\t\t\tassert(\n\t\t\t\tthis.forest.tryMoveCursorToField({ fieldKey: key, parent: undefined }, innerCursor) ===\n\t\t\t\t\tTreeNavigationResult.Ok,\n\t\t\t\t0x892 /* failed to navigate to field */,\n\t\t\t);\n\t\t\tfieldMap.set(key, innerCursor as ITreeCursorSynchronous & ITreeSubscriptionCursor);\n\t\t});\n\n\t\t// Let the incremental summary builder know that we are starting a new summary.\n\t\t// It returns whether incremental encoding is enabled.\n\t\tconst incrementalSummaryBehavior = this.incrementalSummaryBuilder.startSummary({\n\t\t\tfullTree,\n\t\t\tincrementalSummaryContext,\n\t\t\tstringify,\n\t\t});\n\t\tconst encoderContext: FieldBatchEncodingContext = {\n\t\t\t...this.encoderContext,\n\t\t\tincrementalEncoderDecoder:\n\t\t\t\tincrementalSummaryBehavior === ForestIncrementalSummaryBehavior.Incremental\n\t\t\t\t\t? this.incrementalSummaryBuilder\n\t\t\t\t\t: undefined,\n\t\t};\n\t\tconst encoded = this.codec.encode(fieldMap, encoderContext);\n\t\tfieldMap.forEach((value) => value.free());\n\n\t\treturn this.incrementalSummaryBuilder.completeSummary({\n\t\t\tincrementalSummaryContext,\n\t\t\tforestSummaryContent: stringify(encoded),\n\t\t});\n\t}\n\n\tpublic async load(\n\t\tservices: IChannelStorageService,\n\t\tparse: SummaryElementParser,\n\t): Promise<void> {\n\t\t// The contents of the top-level forest must be present under a summary blob named `forestSummaryContentKey`.\n\t\t// If the summary was generated as `ForestIncrementalSummaryBehavior.SingleBlob`, this blob will contain all\n\t\t// of forest's contents.\n\t\t// If the summary was generated as `ForestIncrementalSummaryBehavior.Incremental`, this blob will contain only\n\t\t// the top-level forest node's contents.\n\t\t// The contents of the incremental chunks will be in separate tree nodes and will be read later during decoding.\n\t\tassert(\n\t\t\tawait services.contains(forestSummaryContentKey),\n\t\t\t0xc21 /* Forest summary content missing in snapshot */,\n\t\t);\n\n\t\tconst readAndParseBlob = async <T extends JsonCompatible<IFluidHandle>>(\n\t\t\tid: string,\n\t\t): Promise<T> => {\n\t\t\tconst treeBuffer = await services.readBlob(id);\n\t\t\tconst treeBufferString = bufferToString(treeBuffer, \"utf8\");\n\t\t\treturn parse(treeBufferString) as T;\n\t\t};\n\n\t\t// Load the incremental summary builder so that it can download any incremental chunks in the\n\t\t// snapshot.\n\t\tawait this.incrementalSummaryBuilder.load(services, readAndParseBlob);\n\n\t\t// TODO: this code is parsing data without an optional validator, this should be defined in a typebox schema as part of the\n\t\t// forest summary format.\n\t\tconst fields = this.codec.decode(await readAndParseBlob(forestSummaryContentKey), {\n\t\t\t...this.encoderContext,\n\t\t\tincrementalEncoderDecoder: this.incrementalSummaryBuilder,\n\t\t});\n\t\tconst allocator = idAllocatorFromMaxId();\n\t\tconst fieldChanges: [FieldKey, DeltaFieldChanges][] = [];\n\t\tconst build: DeltaDetachedNodeBuild[] = [];\n\t\tfor (const [fieldKey, field] of fields) {\n\t\t\tconst chunked = chunkFieldSingle(field, {\n\t\t\t\tpolicy: defaultChunkPolicy,\n\t\t\t\tidCompressor: this.idCompressor,\n\t\t\t});\n\t\t\tconst buildId = { minor: allocator.allocate(chunked.topLevelLength) };\n\t\t\tbuild.push({\n\t\t\t\tid: buildId,\n\t\t\t\ttrees: chunked,\n\t\t\t});\n\t\t\tfieldChanges.push([fieldKey, [{ count: chunked.topLevelLength, attach: buildId }]]);\n\t\t}\n\n\t\tassert(this.forest.isEmpty, 0x797 /* forest must be empty */);\n\t\tapplyDelta(\n\t\t\t{ build, fields: new Map(fieldChanges) },\n\t\t\tundefined,\n\t\t\tthis.forest,\n\t\t\tmakeDetachedFieldIndex(\"init\", this.revisionTagCodec, this.idCompressor),\n\t\t);\n\t}\n}\n"]}

package/dist/feature-libraries/forest-summary/incrementalSummaryBuilder.d.ts

@@ -0,0 +1,178 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import type { IExperimentalIncrementalSummaryContext, ISummaryTreeWithStats } from "@fluidframework/runtime-definitions/internal";
+import { type JsonCompatible } from "../../util/index.js";
+import type { ChunkReferenceId, EncodedFieldBatch, IncrementalEncoderDecoder, TreeChunk } from "../chunked-forest/index.js";
+import type { FieldKey, ITreeCursorSynchronous, TreeNodeSchemaIdentifier } from "../../core/index.js";
+import type { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
+import type { IFluidHandle } from "@fluidframework/core-interfaces";
+import type { SummaryElementStringifier } from "../../shared-tree-core/index.js";
+/**
+ * The key for the blob under ForestSummarizer's root.
+ * This blob contains the ForestCodec's output.
+ * See {@link ForestIncrementalSummaryBuilder} for details on the summary structure.
+ */
+export declare const forestSummaryContentKey = "ForestTree";
+/**
+ * State that tells whether a summary is currently being tracked.
+ */
+export declare const ForestSummaryTrackingState: {
+    /** A summary is currently being tracked. */
+    readonly Tracking: "Tracking";
+    /** A summary is ready to be tracked. */
+    readonly ReadyToTrack: "ReadyToTrack";
+};
+export type ForestSummaryTrackingState = (typeof ForestSummaryTrackingState)[keyof typeof ForestSummaryTrackingState];
+/**
+ * The behavior of the forest's incremental summary - whether the summary should be a single blob or incremental.
+ */
+export declare enum ForestIncrementalSummaryBehavior {
+    /**
+     * The forest can encode chunks incrementally, i.e., chunks that support incremental encoding will be encoded
+     * separately - they will be added to a separate tree.
+     * The incremental summary format is described in {@link ForestIncrementalSummaryBuilder}.
+     */
+    Incremental = 0,
+    /**
+     * The forest should encode all of it's data in a single summary blob.
+     * @remarks
+     * The format of the summary will be the same as the old format (pre-incremental summaries) and is fully
+     * backwards compatible with the old format. The summary will basically look like an incremental summary
+     * with no incremental fields - it will only contain the "ForestTree" blob in the summary format described
+     * in {@link ForestIncrementalSummaryBuilder}.
+     */
+    SingleBlob = 1
+}
+/**
+ * Tracks and builds the incremental summary tree for a forest where chunks that support incremental encoding are
+ * stored in a separate tree in the summary under its {@link ChunkReferenceId}.
+ * The summary tree for a chunk is self-sufficient and can be independently loaded and used to reconstruct the
+ * chunk's contents without any additional context from its parent.
+ *
+ * An example summary tree with incremental summary:
+ *     Forest
+ *     ├── ForestTree
+ *     ├── 0
+ *     |   ├── contents
+ *     |   ├── 1
+ *     |   |   ├── contents
+ *     |   |   ├── 2
+ *     |   |   |   ├── contents
+ *     |   ├── 3 - ".../Forest/ForestTree/0/1/3"
+ *     ├── 4
+ *     |   ├── contents
+ *     |   ├── ...
+ *     ├── 5 - "/.../Forest/ForestTree/5"
+ * - Forest is a summary tree node added by the shared tree and contains the following:
+ *   - The inline portion of the top-level forest content is stored in a summary blob called "ForestTree".
+ *     It also contains the {@link ChunkReferenceId}s of the incremental chunks under it.
+ *   - The summary for each incremental chunk under it is stored against its {@link ChunkReferenceId}.
+ * - For each chunk, the structure of the summary tree is the same as the Forest. It contains the following:
+ *   - The inline portion of the chunk content is stored in a blob called "contents".
+ *     It also contains the {@link ChunkReferenceId}s of the incremental chunks under it.
+ *   - The summary for each incremental chunk under it is stored against its {@link ChunkReferenceId}.
+ * - Chunks that do not change between summaries are summarized as handles in the summary tree.
+ * @remarks
+ * It may seem inconsistent that although the structure for the top-level forest tree is similar to that of
+ * an incremental chunk, its content is stored in a summary blob called "ForestTree" while the content for
+ * the incremental chunks are stored in a summary blob called "contents".
+ * This is to keep this summary backwards compatible with old format (before incremental summaries were added)
+ * where the entire forest content was in a summary blob called "ForestTree". So, if incremental summaries were
+ * disabled, the forest content will be fully backwards compatible.
+ * Note that this limits reusing the root node in a location other than root and a non-root node in the root.
+ * We could phase this out by switching to write the top-level contents under "contents" if we want to support
+ * the above. However, there is no plan to do that for now.
+ *
+ * TODO: AB#46752
+ * Add strong types for the summary structure to document it better. It will help make it super clear what the actual
+ * format is in a way that can easily be linked to, documented and inspected.
+ */
+export declare class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecoder {
+    private readonly enableIncrementalSummary;
+    private readonly getChunkAtCursor;
+    /**
+     * {@link IncrementalEncoder.shouldEncodeFieldIncrementally}
+     */
+    readonly shouldEncodeFieldIncrementally: (nodeIdentifier: TreeNodeSchemaIdentifier, fieldKey: FieldKey) => boolean;
+    /**
+     * The next reference ID to use for a chunk.
+     */
+    private nextReferenceId;
+    /**
+     * For a given summary sequence number, keeps track of a chunk's properties that will be used to generate
+     * a summary handle for the chunk if it does not change between summaries.
+     */
+    private readonly chunkTrackingPropertiesMap;
+    /**
+     * The state indicating whether a summary is currently being tracked or not.
+     */
+    forestSummaryState: ForestSummaryTrackingState;
+    /**
+     * The sequence number of the latest summary that was successful.
+     */
+    private latestSummarySequenceNumber;
+    /**
+     * The current state of the summary being tracked.
+     * This is undefined if no summary is currently being tracked.
+     */
+    private trackedSummaryProperties;
+    /**
+     * A map of chunk reference IDs to their encoded contents. This is typically used during the loading of the
+     * forest to retrieve the contents of the chunks that were summarized incrementally.
+     */
+    private readonly encodedChunkContentsMap;
+    constructor(enableIncrementalSummary: boolean, getChunkAtCursor: (cursor: ITreeCursorSynchronous) => TreeChunk, 
+    /**
+     * {@link IncrementalEncoder.shouldEncodeFieldIncrementally}
+     */
+    shouldEncodeFieldIncrementally: (nodeIdentifier: TreeNodeSchemaIdentifier, fieldKey: FieldKey) => boolean);
+    /**
+     * Must be called when the forest is loaded to download the encoded contents of incremental chunks.
+     * @param services - The channel storage service to use to access the snapshot tree and download the
+     * contents of the chunks.
+     * @param readAndParse - A function that reads and parses a blob from the storage service.
+     */
+    load(services: IChannelStorageService, readAndParseChunk: <T extends JsonCompatible<IFluidHandle>>(id: string) => Promise<T>): Promise<void>;
+    /**
+     * Must be called when starting a new forest summary to track it.
+     * @param fullTree - Whether the summary is a full tree summary. If true, the summary will not contain
+     * any summary handles. All chunks must be summarized in full.
+     * @param incrementalSummaryContext - The context for the incremental summary that contains the sequence numbers
+     * for the current and latest summaries.
+     * @param stringify - Serializes content (including {@link (IFluidHandle:interface)}s) for adding to a summary blob.
+     * @returns the behavior of the forest's incremental summary.
+     */
+    startSummary(args: {
+        fullTree: boolean;
+        incrementalSummaryContext: IExperimentalIncrementalSummaryContext | undefined;
+        stringify: SummaryElementStringifier;
+    }): ForestIncrementalSummaryBehavior;
+    /**
+     * {@link IncrementalEncoder.encodeIncrementalField}
+     * @remarks Returns an empty array if the field has no content.
+     */
+    encodeIncrementalField(cursor: ITreeCursorSynchronous, chunkEncoder: (chunk: TreeChunk) => EncodedFieldBatch): ChunkReferenceId[];
+    /**
+     * Must be called after summary generation is complete to finish tracking the summary.
+     * It clears any tracking state and deletes the tracking properties for summaries that are older than the
+     * latest successful summary.
+     * @param incrementalSummaryContext - The context for the incremental summary that contains the sequence numbers.
+     * If this is undefined, the summary tree will only contain a summary blob for `forestSummaryContent`.
+     * @param forestSummaryContent - The stringified ForestCodec output of top-level Forest content.
+     * @returns the Forest's summary tree.
+     */
+    completeSummary(args: {
+        incrementalSummaryContext: IExperimentalIncrementalSummaryContext | undefined;
+        forestSummaryContent: string;
+    }): ISummaryTreeWithStats;
+    /**
+     * Called to get the encoded contents of an incremental chunk with the given reference ID.
+     * This is typically used when loading the forest to retrieve the contents of incremental chunks.
+     * @param referenceId - The reference ID of the chunk to retrieve.
+     * @returns The encoded contents of the chunk.
+     */
+    getEncodedIncrementalChunk(referenceId: ChunkReferenceId): EncodedFieldBatch;
+}
+//# sourceMappingURL=incrementalSummaryBuilder.d.ts.map

package/dist/feature-libraries/forest-summary/incrementalSummaryBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"incrementalSummaryBuilder.d.ts","sourceRoot":"","sources":["../../../src/feature-libraries/forest-summary/incrementalSummaryBuilder.ts"],"names":[],"mappings":"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"}

package/dist/feature-libraries/forest-summary/incrementalSummaryBuilder.js

@@ -0,0 +1,322 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ForestIncrementalSummaryBuilder = exports.ForestIncrementalSummaryBehavior = exports.ForestSummaryTrackingState = exports.forestSummaryContentKey = void 0;
+const internal_1 = require("@fluidframework/core-utils/internal");
+const internal_2 = require("@fluidframework/runtime-utils/internal");
+const index_js_1 = require("../../util/index.js");
+const driver_definitions_1 = require("@fluidframework/driver-definitions");
+const internal_3 = require("@fluidframework/telemetry-utils/internal");
+/**
+ * The key for the blob under ForestSummarizer's root.
+ * This blob contains the ForestCodec's output.
+ * See {@link ForestIncrementalSummaryBuilder} for details on the summary structure.
+ */
+exports.forestSummaryContentKey = "ForestTree";
+/**
+ * The contents of an incremental chunk is under a summary tree node with its {@link ChunkReferenceId} as the key.
+ * The inline portion of the chunk content is encoded with the forest codec is stored in a blob with this key.
+ * The rest of the chunk contents  is stored in the summary tree under the summary tree node.
+ * See the summary format in {@link ForestIncrementalSummaryBuilder} for more details.
+ */
+const chunkContentsBlobKey = "contents";
+/**
+ * State that tells whether a summary is currently being tracked.
+ */
+exports.ForestSummaryTrackingState = {
+    /** A summary is currently being tracked. */
+    Tracking: "Tracking",
+    /** A summary is ready to be tracked. */
+    ReadyToTrack: "ReadyToTrack",
+};
+/**
+ * The behavior of the forest's incremental summary - whether the summary should be a single blob or incremental.
+ */
+var ForestIncrementalSummaryBehavior;
+(function (ForestIncrementalSummaryBehavior) {
+    /**
+     * The forest can encode chunks incrementally, i.e., chunks that support incremental encoding will be encoded
+     * separately - they will be added to a separate tree.
+     * The incremental summary format is described in {@link ForestIncrementalSummaryBuilder}.
+     */
+    ForestIncrementalSummaryBehavior[ForestIncrementalSummaryBehavior["Incremental"] = 0] = "Incremental";
+    /**
+     * The forest should encode all of it's data in a single summary blob.
+     * @remarks
+     * The format of the summary will be the same as the old format (pre-incremental summaries) and is fully
+     * backwards compatible with the old format. The summary will basically look like an incremental summary
+     * with no incremental fields - it will only contain the "ForestTree" blob in the summary format described
+     * in {@link ForestIncrementalSummaryBuilder}.
+     */
+    ForestIncrementalSummaryBehavior[ForestIncrementalSummaryBehavior["SingleBlob"] = 1] = "SingleBlob";
+})(ForestIncrementalSummaryBehavior || (exports.ForestIncrementalSummaryBehavior = ForestIncrementalSummaryBehavior = {}));
+/**
+ * Validates that a summary is currently being tracked and that the tracked summary properties are defined.
+ * @param forestSummaryState - The current state of the forest summary tracking.
+ * @param trackedSummaryProperties - The properties of the tracked summary, which must be available.
+ */
+function validateTrackingSummary(forestSummaryState, trackedSummaryProperties) {
+    (0, internal_1.assert)(forestSummaryState === exports.ForestSummaryTrackingState.Tracking, 0xc22 /* Not tracking a summary */);
+    (0, internal_1.assert)(trackedSummaryProperties !== undefined, 0xc23 /* Tracked summary properties must be available when tracking a summary */);
+}
+/**
+ * Validates that a summary is ready to be tracked and that the tracked summary properties are undefined.
+ * @param forestSummaryState - The current state of the forest summary tracking.
+ * @param trackedSummaryProperties - The properties of the tracked summary, which must be undefined.
+ */
+function validateReadyToTrackSummary(forestSummaryState, trackedSummaryProperties) {
+    (0, internal_1.assert)(forestSummaryState === exports.ForestSummaryTrackingState.ReadyToTrack, 0xc24 /* Already tracking a summary */);
+    (0, internal_1.assert)(trackedSummaryProperties === undefined, 0xc25 /* Tracked summary properties must not be available when ready to track */);
+}
+/* eslint-disable jsdoc/check-indentation */
+/**
+ * Tracks and builds the incremental summary tree for a forest where chunks that support incremental encoding are
+ * stored in a separate tree in the summary under its {@link ChunkReferenceId}.
+ * The summary tree for a chunk is self-sufficient and can be independently loaded and used to reconstruct the
+ * chunk's contents without any additional context from its parent.
+ *
+ * An example summary tree with incremental summary:
+ *     Forest
+ *     ├── ForestTree
+ *     ├── 0
+ *     |   ├── contents
+ *     |   ├── 1
+ *     |   |   ├── contents
+ *     |   |   ├── 2
+ *     |   |   |   ├── contents
+ *     |   ├── 3 - ".../Forest/ForestTree/0/1/3"
+ *     ├── 4
+ *     |   ├── contents
+ *     |   ├── ...
+ *     ├── 5 - "/.../Forest/ForestTree/5"
+ * - Forest is a summary tree node added by the shared tree and contains the following:
+ *   - The inline portion of the top-level forest content is stored in a summary blob called "ForestTree".
+ *     It also contains the {@link ChunkReferenceId}s of the incremental chunks under it.
+ *   - The summary for each incremental chunk under it is stored against its {@link ChunkReferenceId}.
+ * - For each chunk, the structure of the summary tree is the same as the Forest. It contains the following:
+ *   - The inline portion of the chunk content is stored in a blob called "contents".
+ *     It also contains the {@link ChunkReferenceId}s of the incremental chunks under it.
+ *   - The summary for each incremental chunk under it is stored against its {@link ChunkReferenceId}.
+ * - Chunks that do not change between summaries are summarized as handles in the summary tree.
+ * @remarks
+ * It may seem inconsistent that although the structure for the top-level forest tree is similar to that of
+ * an incremental chunk, its content is stored in a summary blob called "ForestTree" while the content for
+ * the incremental chunks are stored in a summary blob called "contents".
+ * This is to keep this summary backwards compatible with old format (before incremental summaries were added)
+ * where the entire forest content was in a summary blob called "ForestTree". So, if incremental summaries were
+ * disabled, the forest content will be fully backwards compatible.
+ * Note that this limits reusing the root node in a location other than root and a non-root node in the root.
+ * We could phase this out by switching to write the top-level contents under "contents" if we want to support
+ * the above. However, there is no plan to do that for now.
+ *
+ * TODO: AB#46752
+ * Add strong types for the summary structure to document it better. It will help make it super clear what the actual
+ * format is in a way that can easily be linked to, documented and inspected.
+ */
+/* eslint-enable jsdoc/check-indentation */
+class ForestIncrementalSummaryBuilder {
+    constructor(enableIncrementalSummary, getChunkAtCursor, 
+    /**
+     * {@link IncrementalEncoder.shouldEncodeFieldIncrementally}
+     */
+    shouldEncodeFieldIncrementally) {
+        this.enableIncrementalSummary = enableIncrementalSummary;
+        this.getChunkAtCursor = getChunkAtCursor;
+        this.shouldEncodeFieldIncrementally = shouldEncodeFieldIncrementally;
+        /**
+         * The next reference ID to use for a chunk.
+         */
+        this.nextReferenceId = (0, index_js_1.brand)(0);
+        /**
+         * For a given summary sequence number, keeps track of a chunk's properties that will be used to generate
+         * a summary handle for the chunk if it does not change between summaries.
+         */
+        this.chunkTrackingPropertiesMap = new Map();
+        /**
+         * The state indicating whether a summary is currently being tracked or not.
+         */
+        this.forestSummaryState = exports.ForestSummaryTrackingState.ReadyToTrack;
+        /**
+         * The sequence number of the latest summary that was successful.
+         */
+        this.latestSummarySequenceNumber = -1;
+        /**
+         * A map of chunk reference IDs to their encoded contents. This is typically used during the loading of the
+         * forest to retrieve the contents of the chunks that were summarized incrementally.
+         */
+        this.encodedChunkContentsMap = new Map();
+    }
+    /**
+     * Must be called when the forest is loaded to download the encoded contents of incremental chunks.
+     * @param services - The channel storage service to use to access the snapshot tree and download the
+     * contents of the chunks.
+     * @param readAndParse - A function that reads and parses a blob from the storage service.
+     */
+    async load(services, readAndParseChunk) {
+        const forestTree = services.getSnapshotTree?.();
+        // Snapshot tree should be available when loading forest's contents. However, it is an optional function
+        // and may not be implemented by the storage service.
+        if (forestTree === undefined) {
+            return;
+        }
+        // Downloads the contents of incremental chunks in the given snapshot tree. Also, recursively downloads
+        // the contents of incremental chunks in any sub-trees.
+        const downloadChunkContentsInTree = async (snapshotTree, parentTreeKey) => {
+            // All trees in the snapshot tree are for incremental chunks. The key is the chunk's reference ID
+            // and the value is the snapshot tree for the chunk.
+            for (const [chunkReferenceId, chunkSnapshotTree] of Object.entries(snapshotTree.trees)) {
+                const chunkSubTreePath = `${parentTreeKey}${chunkReferenceId}`;
+                const chunkContentsPath = `${chunkSubTreePath}/${chunkContentsBlobKey}`;
+                if (!(await services.contains(chunkContentsPath))) {
+                    throw new internal_3.LoggingError(`SharedTree: Cannot find contents for incremental chunk ${chunkContentsPath}`);
+                }
+                const chunkContents = await readAndParseChunk(chunkContentsPath);
+                this.encodedChunkContentsMap.set(chunkReferenceId, chunkContents);
+                // Recursively download the contents of chunks in this chunk's sub tree.
+                await downloadChunkContentsInTree(chunkSnapshotTree, `${chunkSubTreePath}/`);
+            }
+        };
+        await downloadChunkContentsInTree(forestTree, "");
+    }
+    /**
+     * Must be called when starting a new forest summary to track it.
+     * @param fullTree - Whether the summary is a full tree summary. If true, the summary will not contain
+     * any summary handles. All chunks must be summarized in full.
+     * @param incrementalSummaryContext - The context for the incremental summary that contains the sequence numbers
+     * for the current and latest summaries.
+     * @param stringify - Serializes content (including {@link (IFluidHandle:interface)}s) for adding to a summary blob.
+     * @returns the behavior of the forest's incremental summary.
+     */
+    startSummary(args) {
+        const { fullTree, incrementalSummaryContext, stringify } = args;
+        // If there is no incremental summary context, do not summarize incrementally. This happens in two scenarios:
+        // 1. When summarizing a detached container, i.e., the first ever summary.
+        // 2. When running GC, the default behavior is to call summarize on DDS without incrementalSummaryContext.
+        if (!this.enableIncrementalSummary || incrementalSummaryContext === undefined) {
+            return ForestIncrementalSummaryBehavior.SingleBlob;
+        }
+        validateReadyToTrackSummary(this.forestSummaryState, this.trackedSummaryProperties);
+        this.forestSummaryState = exports.ForestSummaryTrackingState.Tracking;
+        this.latestSummarySequenceNumber = incrementalSummaryContext.latestSummarySequenceNumber;
+        this.trackedSummaryProperties = {
+            summarySequenceNumber: incrementalSummaryContext.summarySequenceNumber,
+            latestSummaryBasePath: incrementalSummaryContext.summaryPath,
+            chunkSummaryPath: [],
+            parentSummaryBuilder: new internal_2.SummaryTreeBuilder(),
+            fullTree,
+            stringify,
+        };
+        return ForestIncrementalSummaryBehavior.Incremental;
+    }
+    /**
+     * {@link IncrementalEncoder.encodeIncrementalField}
+     * @remarks Returns an empty array if the field has no content.
+     */
+    encodeIncrementalField(cursor, chunkEncoder) {
+        // Validate that a summary is currently being tracked and that the tracked summary properties are defined.
+        validateTrackingSummary(this.forestSummaryState, this.trackedSummaryProperties);
+        if (cursor.getFieldLength() === 0) {
+            return [];
+        }
+        let chunkReferenceId;
+        let chunkProperties;
+        const chunk = this.getChunkAtCursor(cursor);
+        // Try and get the properties of the chunk from the latest successful summary.
+        // If it exists and the summary is not a full tree, use the properties to generate a summary handle.
+        // If it does not exist, encode the chunk and generate new properties for it.
+        const previousChunkProperties = (0, index_js_1.tryGetFromNestedMap)(this.chunkTrackingPropertiesMap, this.latestSummarySequenceNumber, chunk);
+        if (previousChunkProperties !== undefined && !this.trackedSummaryProperties.fullTree) {
+            chunkProperties = previousChunkProperties;
+            chunkReferenceId = previousChunkProperties.referenceId;
+            this.trackedSummaryProperties.parentSummaryBuilder.addHandle(`${chunkReferenceId}`, driver_definitions_1.SummaryType.Tree, `${this.trackedSummaryProperties.latestSummaryBasePath}/${previousChunkProperties.summaryPath}`);
+        }
+        else {
+            // Generate a new reference ID for the chunk.
+            chunkReferenceId = (0, index_js_1.brand)(this.nextReferenceId++);
+            // Add the reference ID of this chunk to the chunk summary path and use the path as the summary path
+            // for the chunk in its summary properties.
+            // This is done before encoding the chunk so that the summary path is updated correctly when encoding
+            // any incremental chunks that are under this chunk.
+            this.trackedSummaryProperties.chunkSummaryPath.push(chunkReferenceId);
+            chunkProperties = {
+                referenceId: chunkReferenceId,
+                summaryPath: this.trackedSummaryProperties.chunkSummaryPath.join("/"),
+            };
+            const parentSummaryBuilder = this.trackedSummaryProperties.parentSummaryBuilder;
+            // Create a new summary builder for this chunk to build its summary tree which will be stored in the
+            // parent's summary tree under its reference ID.
+            // Before encoding the chunk, set the parent summary builder to this chunk's summary builder so that
+            // any incremental chunks in the subtree of this chunk will use that as their parent summary builder.
+            const chunkSummaryBuilder = new internal_2.SummaryTreeBuilder();
+            this.trackedSummaryProperties.parentSummaryBuilder = chunkSummaryBuilder;
+            chunkSummaryBuilder.addBlob(chunkContentsBlobKey, this.trackedSummaryProperties.stringify(chunkEncoder(chunk)));
+            // Add this chunk's summary tree to the parent's summary tree. The summary tree contains its encoded
+            // contents and the summary trees of any incremental chunks under it.
+            parentSummaryBuilder.addWithStats(`${chunkReferenceId}`, chunkSummaryBuilder.getSummaryTree());
+            // Restore the parent summary builder and chunk summary path.
+            this.trackedSummaryProperties.parentSummaryBuilder = parentSummaryBuilder;
+            this.trackedSummaryProperties.chunkSummaryPath.pop();
+        }
+        (0, index_js_1.setInNestedMap)(this.chunkTrackingPropertiesMap, this.trackedSummaryProperties.summarySequenceNumber, chunk, chunkProperties);
+        return [chunkReferenceId];
+    }
+    /**
+     * Must be called after summary generation is complete to finish tracking the summary.
+     * It clears any tracking state and deletes the tracking properties for summaries that are older than the
+     * latest successful summary.
+     * @param incrementalSummaryContext - The context for the incremental summary that contains the sequence numbers.
+     * If this is undefined, the summary tree will only contain a summary blob for `forestSummaryContent`.
+     * @param forestSummaryContent - The stringified ForestCodec output of top-level Forest content.
+     * @returns the Forest's summary tree.
+     */
+    completeSummary(args) {
+        const { incrementalSummaryContext, forestSummaryContent } = args;
+        if (!this.enableIncrementalSummary || incrementalSummaryContext === undefined) {
+            const summaryBuilder = new internal_2.SummaryTreeBuilder();
+            summaryBuilder.addBlob(exports.forestSummaryContentKey, forestSummaryContent);
+            return summaryBuilder.getSummaryTree();
+        }
+        validateTrackingSummary(this.forestSummaryState, this.trackedSummaryProperties);
+        this.trackedSummaryProperties.parentSummaryBuilder.addBlob(exports.forestSummaryContentKey, forestSummaryContent);
+        // Copy over the entries from the latest summary to the current summary.
+        // In the current summary, there can be fields that haven't changed since the latest summary and the chunks
+        // in these fields and in any of its children weren't encoded. So, we need get the entries for these chunks
+        // to be able to incrementally summarize them in the next summary.
+        const latestSummaryTrackingMap = this.chunkTrackingPropertiesMap.get(this.latestSummarySequenceNumber);
+        const currentSummaryTrackingMap = this.chunkTrackingPropertiesMap.get(this.trackedSummaryProperties.summarySequenceNumber);
+        if (latestSummaryTrackingMap !== undefined && currentSummaryTrackingMap !== undefined) {
+            for (const [chunk, chunkProperties] of latestSummaryTrackingMap.entries()) {
+                if (!currentSummaryTrackingMap.has(chunk)) {
+                    currentSummaryTrackingMap.set(chunk, chunkProperties);
+                }
+            }
+        }
+        // Delete tracking for summaries that are older than the latest successful summary because they will
+        // never be referenced again for generating summary handles.
+        for (const sequenceNumber of this.chunkTrackingPropertiesMap.keys()) {
+            if (sequenceNumber < this.latestSummarySequenceNumber) {
+                this.chunkTrackingPropertiesMap.delete(sequenceNumber);
+            }
+        }
+        this.forestSummaryState = exports.ForestSummaryTrackingState.ReadyToTrack;
+        const summaryTree = this.trackedSummaryProperties.parentSummaryBuilder.getSummaryTree();
+        this.trackedSummaryProperties = undefined;
+        return summaryTree;
+    }
+    /**
+     * Called to get the encoded contents of an incremental chunk with the given reference ID.
+     * This is typically used when loading the forest to retrieve the contents of incremental chunks.
+     * @param referenceId - The reference ID of the chunk to retrieve.
+     * @returns The encoded contents of the chunk.
+     */
+    getEncodedIncrementalChunk(referenceId) {
+        const chunkEncodedContents = this.encodedChunkContentsMap.get(`${referenceId}`);
+        (0, internal_1.assert)(chunkEncodedContents !== undefined, 0xc26 /* Incremental chunk contents not found */);
+        return chunkEncodedContents;
+    }
+}
+exports.ForestIncrementalSummaryBuilder = ForestIncrementalSummaryBuilder;
+//# sourceMappingURL=incrementalSummaryBuilder.js.map

package/dist/feature-libraries/forest-summary/incrementalSummaryBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"incrementalSummaryBuilder.js","sourceRoot":"","sources":["../../../src/feature-libraries/forest-summary/incrementalSummaryBuilder.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils/internal\";\nimport type {\n\tIExperimentalIncrementalSummaryContext,\n\tISummaryTreeWithStats,\n} from \"@fluidframework/runtime-definitions/internal\";\nimport { SummaryTreeBuilder } from \"@fluidframework/runtime-utils/internal\";\nimport {\n\tbrand,\n\tsetInNestedMap,\n\ttryGetFromNestedMap,\n\ttype JsonCompatible,\n\ttype NestedMap,\n} from \"../../util/index.js\";\nimport type {\n\tChunkReferenceId,\n\tEncodedFieldBatch,\n\tIncrementalEncoderDecoder,\n\tTreeChunk,\n} from \"../chunked-forest/index.js\";\nimport type {\n\tFieldKey,\n\tITreeCursorSynchronous,\n\tTreeNodeSchemaIdentifier,\n} from \"../../core/index.js\";\nimport { SummaryType } from \"@fluidframework/driver-definitions\";\nimport type { IChannelStorageService } from \"@fluidframework/datastore-definitions/internal\";\nimport type { ISnapshotTree } from \"@fluidframework/driver-definitions/internal\";\nimport { LoggingError } from \"@fluidframework/telemetry-utils/internal\";\nimport type { IFluidHandle } from \"@fluidframework/core-interfaces\";\nimport type { SummaryElementStringifier } from \"../../shared-tree-core/index.js\";\n\n/**\n * The key for the blob under ForestSummarizer's root.\n * This blob contains the ForestCodec's output.\n * See {@link ForestIncrementalSummaryBuilder} for details on the summary structure.\n */\nexport const forestSummaryContentKey = \"ForestTree\";\n\n/**\n * The contents of an incremental chunk is under a summary tree node with its {@link ChunkReferenceId} as the key.\n * The inline portion of the chunk content is encoded with the forest codec is stored in a blob with this key.\n * The rest of the chunk contents  is stored in the summary tree under the summary tree node.\n * See the summary format in {@link ForestIncrementalSummaryBuilder} for more details.\n */\nconst chunkContentsBlobKey = \"contents\";\n\n/**\n * State that tells whether a summary is currently being tracked.\n */\nexport const ForestSummaryTrackingState = {\n\t/** A summary is currently being tracked. */\n\tTracking: \"Tracking\",\n\t/** A summary is ready to be tracked. */\n\tReadyToTrack: \"ReadyToTrack\",\n} as const;\nexport type ForestSummaryTrackingState =\n\t(typeof ForestSummaryTrackingState)[keyof typeof ForestSummaryTrackingState];\n\n/**\n * The properties of a chunk that is tracked for every summary.\n * If a chunk doesn't change between summaries,\n * these properties will be used to generate a summary handle for the chunk.\n */\ninterface ChunkSummaryProperties {\n\t/**\n\t * The reference ID of the chunk which uniquely identifies it under its parent's summary tree.\n\t * The summary for this chunk will be stored against this reference ID as key in the summary tree.\n\t */\n\treadonly referenceId: ChunkReferenceId;\n\t/**\n\t * The path for this chunk's summary in the summary tree relative to the forest's summary tree.\n\t * This path is used to generate a summary handle for the chunk if it doesn't change between summaries.\n\t */\n\treadonly summaryPath: string;\n}\n\n/**\n * The properties of a summary being tracked.\n */\ninterface TrackedSummaryProperties {\n\t/**\n\t * The sequence number of the summary in progress.\n\t */\n\treadonly summarySequenceNumber: number;\n\t/**\n\t * The base path for the latest summary that was successful.\n\t * This is used to generate summary handles.\n\t */\n\treadonly latestSummaryBasePath: string;\n\t/**\n\t * Whether the summary being tracked is a full tree summary.\n\t * If true, the summary will not contain any summary handles. All chunks must be summarized in full.\n\t */\n\treadonly fullTree: boolean;\n\t/**\n\t * Represents the path of a chunk in the summary tree relative to the forest's summary tree.\n\t * Each item in the array is the {@link ChunkReferenceId} of a chunk in the summary tree starting\n\t * from the chunk under forest summary tree.\n\t * When a chunk is summarized, this array will be used to generate the path for the chunk's summary in the\n\t * summary tree.\n\t */\n\treadonly chunkSummaryPath: ChunkReferenceId[];\n\t/**\n\t * The parent summary builder to use to build the incremental summary tree.\n\t * When a chunk is being summarized, it will add its summary to this builder against its reference ID.\n\t */\n\tparentSummaryBuilder: SummaryTreeBuilder;\n\t/**\n\t * Serializes content (including {@link (IFluidHandle:interface)}s) for adding to a summary blob.\n\t */\n\tstringify: SummaryElementStringifier;\n}\n\n/**\n * The behavior of the forest's incremental summary - whether the summary should be a single blob or incremental.\n */\nexport enum ForestIncrementalSummaryBehavior {\n\t/**\n\t * The forest can encode chunks incrementally, i.e., chunks that support incremental encoding will be encoded\n\t * separately - they will be added to a separate tree.\n\t * The incremental summary format is described in {@link ForestIncrementalSummaryBuilder}.\n\t */\n\tIncremental,\n\t/**\n\t * The forest should encode all of it's data in a single summary blob.\n\t * @remarks\n\t * The format of the summary will be the same as the old format (pre-incremental summaries) and is fully\n\t * backwards compatible with the old format. The summary will basically look like an incremental summary\n\t * with no incremental fields - it will only contain the \"ForestTree\" blob in the summary format described\n\t * in {@link ForestIncrementalSummaryBuilder}.\n\t */\n\tSingleBlob,\n}\n\n/**\n * Validates that a summary is currently being tracked and that the tracked summary properties are defined.\n * @param forestSummaryState - The current state of the forest summary tracking.\n * @param trackedSummaryProperties - The properties of the tracked summary, which must be available.\n */\nfunction validateTrackingSummary(\n\tforestSummaryState: ForestSummaryTrackingState,\n\ttrackedSummaryProperties: TrackedSummaryProperties | undefined,\n): asserts trackedSummaryProperties is TrackedSummaryProperties {\n\tassert(\n\t\tforestSummaryState === ForestSummaryTrackingState.Tracking,\n\t\t0xc22 /* Not tracking a summary */,\n\t);\n\tassert(\n\t\ttrackedSummaryProperties !== undefined,\n\t\t0xc23 /* Tracked summary properties must be available when tracking a summary */,\n\t);\n}\n\n/**\n * Validates that a summary is ready to be tracked and that the tracked summary properties are undefined.\n * @param forestSummaryState - The current state of the forest summary tracking.\n * @param trackedSummaryProperties - The properties of the tracked summary, which must be undefined.\n */\nfunction validateReadyToTrackSummary(\n\tforestSummaryState: ForestSummaryTrackingState,\n\ttrackedSummaryProperties: TrackedSummaryProperties | undefined,\n): asserts trackedSummaryProperties is undefined {\n\tassert(\n\t\tforestSummaryState === ForestSummaryTrackingState.ReadyToTrack,\n\t\t0xc24 /* Already tracking a summary */,\n\t);\n\tassert(\n\t\ttrackedSummaryProperties === undefined,\n\t\t0xc25 /* Tracked summary properties must not be available when ready to track */,\n\t);\n}\n\n/* eslint-disable jsdoc/check-indentation */\n/**\n * Tracks and builds the incremental summary tree for a forest where chunks that support incremental encoding are\n * stored in a separate tree in the summary under its {@link ChunkReferenceId}.\n * The summary tree for a chunk is self-sufficient and can be independently loaded and used to reconstruct the\n * chunk's contents without any additional context from its parent.\n *\n * An example summary tree with incremental summary:\n *     Forest\n *     ├── ForestTree\n *     ├── 0\n *     |   ├── contents\n *     |   ├── 1\n *     |   |   ├── contents\n *     |   |   ├── 2\n *     |   |   |   ├── contents\n *     |   ├── 3 - \".../Forest/ForestTree/0/1/3\"\n *     ├── 4\n *     |   ├── contents\n *     |   ├── ...\n *     ├── 5 - \"/.../Forest/ForestTree/5\"\n * - Forest is a summary tree node added by the shared tree and contains the following:\n *   - The inline portion of the top-level forest content is stored in a summary blob called \"ForestTree\".\n *     It also contains the {@link ChunkReferenceId}s of the incremental chunks under it.\n *   - The summary for each incremental chunk under it is stored against its {@link ChunkReferenceId}.\n * - For each chunk, the structure of the summary tree is the same as the Forest. It contains the following:\n *   - The inline portion of the chunk content is stored in a blob called \"contents\".\n *     It also contains the {@link ChunkReferenceId}s of the incremental chunks under it.\n *   - The summary for each incremental chunk under it is stored against its {@link ChunkReferenceId}.\n * - Chunks that do not change between summaries are summarized as handles in the summary tree.\n * @remarks\n * It may seem inconsistent that although the structure for the top-level forest tree is similar to that of\n * an incremental chunk, its content is stored in a summary blob called \"ForestTree\" while the content for\n * the incremental chunks are stored in a summary blob called \"contents\".\n * This is to keep this summary backwards compatible with old format (before incremental summaries were added)\n * where the entire forest content was in a summary blob called \"ForestTree\". So, if incremental summaries were\n * disabled, the forest content will be fully backwards compatible.\n * Note that this limits reusing the root node in a location other than root and a non-root node in the root.\n * We could phase this out by switching to write the top-level contents under \"contents\" if we want to support\n * the above. However, there is no plan to do that for now.\n *\n * TODO: AB#46752\n * Add strong types for the summary structure to document it better. It will help make it super clear what the actual\n * format is in a way that can easily be linked to, documented and inspected.\n */\n/* eslint-enable jsdoc/check-indentation */\nexport class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecoder {\n\t/**\n\t * The next reference ID to use for a chunk.\n\t */\n\tprivate nextReferenceId: ChunkReferenceId = brand(0);\n\n\t/**\n\t * For a given summary sequence number, keeps track of a chunk's properties that will be used to generate\n\t * a summary handle for the chunk if it does not change between summaries.\n\t */\n\tprivate readonly chunkTrackingPropertiesMap: NestedMap<\n\t\tnumber,\n\t\tTreeChunk,\n\t\tChunkSummaryProperties\n\t> = new Map();\n\n\t/**\n\t * The state indicating whether a summary is currently being tracked or not.\n\t */\n\tpublic forestSummaryState: ForestSummaryTrackingState =\n\t\tForestSummaryTrackingState.ReadyToTrack;\n\n\t/**\n\t * The sequence number of the latest summary that was successful.\n\t */\n\tprivate latestSummarySequenceNumber: number = -1;\n\n\t/**\n\t * The current state of the summary being tracked.\n\t * This is undefined if no summary is currently being tracked.\n\t */\n\tprivate trackedSummaryProperties: TrackedSummaryProperties | undefined;\n\n\t/**\n\t * A map of chunk reference IDs to their encoded contents. This is typically used during the loading of the\n\t * forest to retrieve the contents of the chunks that were summarized incrementally.\n\t */\n\tprivate readonly encodedChunkContentsMap: Map<string, EncodedFieldBatch> = new Map();\n\n\tpublic constructor(\n\t\tprivate readonly enableIncrementalSummary: boolean,\n\t\tprivate readonly getChunkAtCursor: (cursor: ITreeCursorSynchronous) => TreeChunk,\n\t\t/**\n\t\t * {@link IncrementalEncoder.shouldEncodeFieldIncrementally}\n\t\t */\n\t\tpublic readonly shouldEncodeFieldIncrementally: (\n\t\t\tnodeIdentifier: TreeNodeSchemaIdentifier,\n\t\t\tfieldKey: FieldKey,\n\t\t) => boolean,\n\t) {}\n\n\t/**\n\t * Must be called when the forest is loaded to download the encoded contents of incremental chunks.\n\t * @param services - The channel storage service to use to access the snapshot tree and download the\n\t * contents of the chunks.\n\t * @param readAndParse - A function that reads and parses a blob from the storage service.\n\t */\n\tpublic async load(\n\t\tservices: IChannelStorageService,\n\t\treadAndParseChunk: <T extends JsonCompatible<IFluidHandle>>(id: string) => Promise<T>,\n\t): Promise<void> {\n\t\tconst forestTree = services.getSnapshotTree?.();\n\t\t// Snapshot tree should be available when loading forest's contents. However, it is an optional function\n\t\t// and may not be implemented by the storage service.\n\t\tif (forestTree === undefined) {\n\t\t\treturn;\n\t\t}\n\n\t\t// Downloads the contents of incremental chunks in the given snapshot tree. Also, recursively downloads\n\t\t// the contents of incremental chunks in any sub-trees.\n\t\tconst downloadChunkContentsInTree = async (\n\t\t\tsnapshotTree: ISnapshotTree,\n\t\t\tparentTreeKey: string,\n\t\t): Promise<void> => {\n\t\t\t// All trees in the snapshot tree are for incremental chunks. The key is the chunk's reference ID\n\t\t\t// and the value is the snapshot tree for the chunk.\n\t\t\tfor (const [chunkReferenceId, chunkSnapshotTree] of Object.entries(snapshotTree.trees)) {\n\t\t\t\tconst chunkSubTreePath = `${parentTreeKey}${chunkReferenceId}`;\n\t\t\t\tconst chunkContentsPath = `${chunkSubTreePath}/${chunkContentsBlobKey}`;\n\t\t\t\tif (!(await services.contains(chunkContentsPath))) {\n\t\t\t\t\tthrow new LoggingError(\n\t\t\t\t\t\t`SharedTree: Cannot find contents for incremental chunk ${chunkContentsPath}`,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tconst chunkContents = await readAndParseChunk<EncodedFieldBatch>(chunkContentsPath);\n\t\t\t\tthis.encodedChunkContentsMap.set(chunkReferenceId, chunkContents);\n\n\t\t\t\t// Recursively download the contents of chunks in this chunk's sub tree.\n\t\t\t\tawait downloadChunkContentsInTree(chunkSnapshotTree, `${chunkSubTreePath}/`);\n\t\t\t}\n\t\t};\n\t\tawait downloadChunkContentsInTree(forestTree, \"\");\n\t}\n\n\t/**\n\t * Must be called when starting a new forest summary to track it.\n\t * @param fullTree - Whether the summary is a full tree summary. If true, the summary will not contain\n\t * any summary handles. All chunks must be summarized in full.\n\t * @param incrementalSummaryContext - The context for the incremental summary that contains the sequence numbers\n\t * for the current and latest summaries.\n\t * @param stringify - Serializes content (including {@link (IFluidHandle:interface)}s) for adding to a summary blob.\n\t * @returns the behavior of the forest's incremental summary.\n\t */\n\tpublic startSummary(args: {\n\t\tfullTree: boolean;\n\t\tincrementalSummaryContext: IExperimentalIncrementalSummaryContext | undefined;\n\t\tstringify: SummaryElementStringifier;\n\t}): ForestIncrementalSummaryBehavior {\n\t\tconst { fullTree, incrementalSummaryContext, stringify } = args;\n\t\t// If there is no incremental summary context, do not summarize incrementally. This happens in two scenarios:\n\t\t// 1. When summarizing a detached container, i.e., the first ever summary.\n\t\t// 2. When running GC, the default behavior is to call summarize on DDS without incrementalSummaryContext.\n\t\tif (!this.enableIncrementalSummary || incrementalSummaryContext === undefined) {\n\t\t\treturn ForestIncrementalSummaryBehavior.SingleBlob;\n\t\t}\n\n\t\tvalidateReadyToTrackSummary(this.forestSummaryState, this.trackedSummaryProperties);\n\n\t\tthis.forestSummaryState = ForestSummaryTrackingState.Tracking;\n\t\tthis.latestSummarySequenceNumber = incrementalSummaryContext.latestSummarySequenceNumber;\n\t\tthis.trackedSummaryProperties = {\n\t\t\tsummarySequenceNumber: incrementalSummaryContext.summarySequenceNumber,\n\t\t\tlatestSummaryBasePath: incrementalSummaryContext.summaryPath,\n\t\t\tchunkSummaryPath: [],\n\t\t\tparentSummaryBuilder: new SummaryTreeBuilder(),\n\t\t\tfullTree,\n\t\t\tstringify,\n\t\t};\n\t\treturn ForestIncrementalSummaryBehavior.Incremental;\n\t}\n\n\t/**\n\t * {@link IncrementalEncoder.encodeIncrementalField}\n\t * @remarks Returns an empty array if the field has no content.\n\t */\n\tpublic encodeIncrementalField(\n\t\tcursor: ITreeCursorSynchronous,\n\t\tchunkEncoder: (chunk: TreeChunk) => EncodedFieldBatch,\n\t): ChunkReferenceId[] {\n\t\t// Validate that a summary is currently being tracked and that the tracked summary properties are defined.\n\t\tvalidateTrackingSummary(this.forestSummaryState, this.trackedSummaryProperties);\n\n\t\tif (cursor.getFieldLength() === 0) {\n\t\t\treturn [];\n\t\t}\n\n\t\tlet chunkReferenceId: ChunkReferenceId;\n\t\tlet chunkProperties: ChunkSummaryProperties;\n\n\t\tconst chunk = this.getChunkAtCursor(cursor);\n\n\t\t// Try and get the properties of the chunk from the latest successful summary.\n\t\t// If it exists and the summary is not a full tree, use the properties to generate a summary handle.\n\t\t// If it does not exist, encode the chunk and generate new properties for it.\n\t\tconst previousChunkProperties = tryGetFromNestedMap(\n\t\t\tthis.chunkTrackingPropertiesMap,\n\t\t\tthis.latestSummarySequenceNumber,\n\t\t\tchunk,\n\t\t);\n\t\tif (previousChunkProperties !== undefined && !this.trackedSummaryProperties.fullTree) {\n\t\t\tchunkProperties = previousChunkProperties;\n\t\t\tchunkReferenceId = previousChunkProperties.referenceId;\n\t\t\tthis.trackedSummaryProperties.parentSummaryBuilder.addHandle(\n\t\t\t\t`${chunkReferenceId}`,\n\t\t\t\tSummaryType.Tree,\n\t\t\t\t`${this.trackedSummaryProperties.latestSummaryBasePath}/${previousChunkProperties.summaryPath}`,\n\t\t\t);\n\t\t} else {\n\t\t\t// Generate a new reference ID for the chunk.\n\t\t\tchunkReferenceId = brand(this.nextReferenceId++);\n\t\t\t// Add the reference ID of this chunk to the chunk summary path and use the path as the summary path\n\t\t\t// for the chunk in its summary properties.\n\t\t\t// This is done before encoding the chunk so that the summary path is updated correctly when encoding\n\t\t\t// any incremental chunks that are under this chunk.\n\t\t\tthis.trackedSummaryProperties.chunkSummaryPath.push(chunkReferenceId);\n\n\t\t\tchunkProperties = {\n\t\t\t\treferenceId: chunkReferenceId,\n\t\t\t\tsummaryPath: this.trackedSummaryProperties.chunkSummaryPath.join(\"/\"),\n\t\t\t};\n\n\t\t\tconst parentSummaryBuilder = this.trackedSummaryProperties.parentSummaryBuilder;\n\t\t\t// Create a new summary builder for this chunk to build its summary tree which will be stored in the\n\t\t\t// parent's summary tree under its reference ID.\n\t\t\t// Before encoding the chunk, set the parent summary builder to this chunk's summary builder so that\n\t\t\t// any incremental chunks in the subtree of this chunk will use that as their parent summary builder.\n\t\t\tconst chunkSummaryBuilder = new SummaryTreeBuilder();\n\t\t\tthis.trackedSummaryProperties.parentSummaryBuilder = chunkSummaryBuilder;\n\t\t\tchunkSummaryBuilder.addBlob(\n\t\t\t\tchunkContentsBlobKey,\n\t\t\t\tthis.trackedSummaryProperties.stringify(chunkEncoder(chunk)),\n\t\t\t);\n\n\t\t\t// Add this chunk's summary tree to the parent's summary tree. The summary tree contains its encoded\n\t\t\t// contents and the summary trees of any incremental chunks under it.\n\t\t\tparentSummaryBuilder.addWithStats(\n\t\t\t\t`${chunkReferenceId}`,\n\t\t\t\tchunkSummaryBuilder.getSummaryTree(),\n\t\t\t);\n\n\t\t\t// Restore the parent summary builder and chunk summary path.\n\t\t\tthis.trackedSummaryProperties.parentSummaryBuilder = parentSummaryBuilder;\n\t\t\tthis.trackedSummaryProperties.chunkSummaryPath.pop();\n\t\t}\n\n\t\tsetInNestedMap(\n\t\t\tthis.chunkTrackingPropertiesMap,\n\t\t\tthis.trackedSummaryProperties.summarySequenceNumber,\n\t\t\tchunk,\n\t\t\tchunkProperties,\n\t\t);\n\t\treturn [chunkReferenceId];\n\t}\n\n\t/**\n\t * Must be called after summary generation is complete to finish tracking the summary.\n\t * It clears any tracking state and deletes the tracking properties for summaries that are older than the\n\t * latest successful summary.\n\t * @param incrementalSummaryContext - The context for the incremental summary that contains the sequence numbers.\n\t * If this is undefined, the summary tree will only contain a summary blob for `forestSummaryContent`.\n\t * @param forestSummaryContent - The stringified ForestCodec output of top-level Forest content.\n\t * @returns the Forest's summary tree.\n\t */\n\tpublic completeSummary(args: {\n\t\tincrementalSummaryContext: IExperimentalIncrementalSummaryContext | undefined;\n\t\tforestSummaryContent: string;\n\t}): ISummaryTreeWithStats {\n\t\tconst { incrementalSummaryContext, forestSummaryContent } = args;\n\t\tif (!this.enableIncrementalSummary || incrementalSummaryContext === undefined) {\n\t\t\tconst summaryBuilder = new SummaryTreeBuilder();\n\t\t\tsummaryBuilder.addBlob(forestSummaryContentKey, forestSummaryContent);\n\t\t\treturn summaryBuilder.getSummaryTree();\n\t\t}\n\n\t\tvalidateTrackingSummary(this.forestSummaryState, this.trackedSummaryProperties);\n\n\t\tthis.trackedSummaryProperties.parentSummaryBuilder.addBlob(\n\t\t\tforestSummaryContentKey,\n\t\t\tforestSummaryContent,\n\t\t);\n\n\t\t// Copy over the entries from the latest summary to the current summary.\n\t\t// In the current summary, there can be fields that haven't changed since the latest summary and the chunks\n\t\t// in these fields and in any of its children weren't encoded. So, we need get the entries for these chunks\n\t\t// to be able to incrementally summarize them in the next summary.\n\t\tconst latestSummaryTrackingMap = this.chunkTrackingPropertiesMap.get(\n\t\t\tthis.latestSummarySequenceNumber,\n\t\t);\n\t\tconst currentSummaryTrackingMap = this.chunkTrackingPropertiesMap.get(\n\t\t\tthis.trackedSummaryProperties.summarySequenceNumber,\n\t\t);\n\t\tif (latestSummaryTrackingMap !== undefined && currentSummaryTrackingMap !== undefined) {\n\t\t\tfor (const [chunk, chunkProperties] of latestSummaryTrackingMap.entries()) {\n\t\t\t\tif (!currentSummaryTrackingMap.has(chunk)) {\n\t\t\t\t\tcurrentSummaryTrackingMap.set(chunk, chunkProperties);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\t// Delete tracking for summaries that are older than the latest successful summary because they will\n\t\t// never be referenced again for generating summary handles.\n\t\tfor (const sequenceNumber of this.chunkTrackingPropertiesMap.keys()) {\n\t\t\tif (sequenceNumber < this.latestSummarySequenceNumber) {\n\t\t\t\tthis.chunkTrackingPropertiesMap.delete(sequenceNumber);\n\t\t\t}\n\t\t}\n\n\t\tthis.forestSummaryState = ForestSummaryTrackingState.ReadyToTrack;\n\t\tconst summaryTree = this.trackedSummaryProperties.parentSummaryBuilder.getSummaryTree();\n\t\tthis.trackedSummaryProperties = undefined;\n\t\treturn summaryTree;\n\t}\n\n\t/**\n\t * Called to get the encoded contents of an incremental chunk with the given reference ID.\n\t * This is typically used when loading the forest to retrieve the contents of incremental chunks.\n\t * @param referenceId - The reference ID of the chunk to retrieve.\n\t * @returns The encoded contents of the chunk.\n\t */\n\tpublic getEncodedIncrementalChunk(referenceId: ChunkReferenceId): EncodedFieldBatch {\n\t\tconst chunkEncodedContents = this.encodedChunkContentsMap.get(`${referenceId}`);\n\t\tassert(\n\t\t\tchunkEncodedContents !== undefined,\n\t\t\t0xc26 /* Incremental chunk contents not found */,\n\t\t);\n\t\treturn chunkEncodedContents;\n\t}\n}\n"]}