(tree) Tag incremental summary APIs as @Alpha (#25918)

The APIs neede to enable incremental summary have been tagged as @ alpha
so that they can be used by applications.
The list of APIs that are marked @ alpha:
- `configuredSharedTreeAlpha` - This is a new API which is similar to
`configuredSharedTreeBeta` but has a couple more options exposed for
configuring incremental summaries.
- `SharedTreeOptionsAlpha` - Extension of `SharedTreeOptionsBeta` that
includes options to enable incremental summarization.
- `IncrementalEncodingPolicy` - Policy type to determine whether a node
/ field should be incrementally encoded.
- `incrementalEncodingPolicyForAllowedTypes` - This function returns an
`IncrementalEncodingPolicy` which will determine if `AllowedTypes` are
opted into incremental summarization.
- `incrementalSummaryHint` - This is a symbol that should be put in the
metadata property of `AllowedTypes` to opt-in these types to be
incrementally summarized.


[AB#54252](https://dev.azure.com/fluidframework/235294da-091d-4c29-84fc-cdfc3d90890b/_workitems/edit/54252)

[AB#46028](https://dev.azure.com/fluidframework/235294da-091d-4c29-84fc-cdfc3d90890b/_workitems/edit/46028)

Author: agarwal-navin

packages/dds/tree/api-report/tree.alpha.api.md

@@ -169,6 +169,9 @@ export type ConciseTree<THandle = IFluidHandle> = Exclude<TreeLeafValue, IFluidH
     [key: string]: ConciseTree<THandle>;
 };
 
+// @alpha
+export function configuredSharedTreeAlpha(options: SharedTreeOptions): SharedObjectKind<ITree>;
+
 // @beta
 export function configuredSharedTreeBeta(options: SharedTreeOptionsBeta): SharedObjectKind<ITree>;
 
@@ -427,6 +430,15 @@ export type ImplicitFieldSchema = FieldSchema | ImplicitAllowedTypes;
 // @alpha
 export function importCompatibilitySchemaSnapshot(config: JsonCompatibleReadOnly): TreeViewConfiguration;
 
+// @alpha
+export type IncrementalEncodingPolicy = (nodeIdentifier: string | undefined, fieldKey: string) => boolean;
+
+// @alpha
+export function incrementalEncodingPolicyForAllowedTypes(rootSchema: TreeSchema): IncrementalEncodingPolicy;
+
+// @alpha
+export const incrementalSummaryHint: unique symbol;
+
 // @alpha
 export function independentInitializedView<const TSchema extends ImplicitFieldSchema>(config: TreeViewConfiguration<TSchema>, options: ForestOptions & ICodecOptions, content: ViewContent): TreeViewAlpha<TSchema>;
 
@@ -1022,8 +1034,9 @@ export interface SharedTreeFormatOptions {
 }
 
 // @alpha @input
-export interface SharedTreeOptions extends Partial<CodecWriteOptions>, Partial<SharedTreeFormatOptions>, SharedTreeOptionsBeta {
+export interface SharedTreeOptions extends SharedTreeOptionsBeta, Partial<CodecWriteOptions>, Partial<SharedTreeFormatOptions> {
     readonly enableSharedBranches?: boolean;
+    shouldEncodeIncrementally?: IncrementalEncodingPolicy;
 }
 
 // @beta @input
@@ -1475,6 +1488,7 @@ export interface TreeChangeEventsBeta<TNode extends TreeNode = TreeNode> extends
 // @alpha
 export enum TreeCompressionStrategy {
     Compressed = 0,
+    CompressedIncremental = 2,
     Uncompressed = 1
 }
 

packages/dds/tree/src/feature-libraries/chunked-forest/codec/codecs.ts

@@ -29,11 +29,7 @@ import {
 	type Brand,
 	type JsonCompatibleReadOnly,
 } from "../../../util/index.js";
-import {
-	TreeCompressionStrategy,
-	TreeCompressionStrategyExtended,
-	type TreeCompressionStrategyPrivate,
-} from "../../treeCompressionUtils.js";
+import { TreeCompressionStrategy } from "../../treeCompressionUtils.js";
 
 import { decode } from "./chunkDecoding.js";
 import type { FieldBatch } from "./fieldBatch.js";
@@ -109,7 +105,7 @@ export interface IncrementalDecoder {
 export interface IncrementalEncoderDecoder extends IncrementalEncoder, IncrementalDecoder {}
 
 export interface FieldBatchEncodingContext {
-	readonly encodeType: TreeCompressionStrategyPrivate;
+	readonly encodeType: TreeCompressionStrategy;
 	readonly idCompressor: IIdCompressor;
 	readonly originatorId: SessionId;
 	readonly schema?: SchemaAndPolicy;
@@ -190,7 +186,7 @@ export function makeFieldBatchCodec(options: CodecWriteOptions): FieldBatchCodec
 				case TreeCompressionStrategy.Uncompressed:
 					encoded = uncompressedEncodeFn(data);
 					break;
-				case TreeCompressionStrategyExtended.CompressedIncremental:
+				case TreeCompressionStrategy.CompressedIncremental:
 					assert(
 						writeVersion >= FieldBatchFormatVersion.v2,
 						0xca0 /* Unsupported FieldBatchFormatVersion for incremental encoding; must be v2 or higher */,

packages/dds/tree/src/feature-libraries/chunked-forest/codec/incrementalEncodingPolicy.ts

@@ -3,8 +3,6 @@
  * Licensed under the MIT License.
  */
 
-import type { FieldKey, TreeNodeSchemaIdentifier } from "../../../core/index.js";
-
 /**
  * Policy to determine whether a node / field should be incrementally encoded.
  * @param nodeIdentifier - The identifier of the node containing the field.
@@ -16,18 +14,19 @@ import type { FieldKey, TreeNodeSchemaIdentifier } from "../../../core/index.js"
  * but allows reuse of previously encoded unchanged subtrees.
  * Thus it should only be enabled for large subtrees which are modified infrequently.
  * TODO: AB#9068: Measure the actual overhead.
+ * @alpha
  */
 export type IncrementalEncodingPolicy = (
-	nodeIdentifier: TreeNodeSchemaIdentifier | undefined,
-	fieldKey: FieldKey,
+	nodeIdentifier: string | undefined,
+	fieldKey: string,
 ) => boolean;
 
 /**
  * Default policy for incremental encoding is to not encode incrementally.
  */
 export const defaultIncrementalEncodingPolicy: IncrementalEncodingPolicy = (
-	nodeIdentifier: TreeNodeSchemaIdentifier | undefined,
-	fieldKey: FieldKey,
+	nodeIdentifier: string | undefined,
+	fieldKey: string,
 ): boolean => {
 	return false;
 };

packages/dds/tree/src/feature-libraries/forest-summary/forestSummarizer.ts

@@ -48,7 +48,7 @@ import {
 	ForestIncrementalSummaryBuilder,
 	forestSummaryContentKey,
 } from "./incrementalSummaryBuilder.js";
-import { TreeCompressionStrategyExtended } from "../treeCompressionUtils.js";
+import { TreeCompressionStrategy } from "../treeCompressionUtils.js";
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
 
 /**
@@ -85,7 +85,7 @@ export class ForestSummarizer implements Summarizable {
 		this.codec = makeForestSummarizerCodec(options, fieldBatchCodec);
 		this.incrementalSummaryBuilder = new ForestIncrementalSummaryBuilder(
 			encoderContext.encodeType ===
-				TreeCompressionStrategyExtended.CompressedIncremental /* enableIncrementalSummary */,
+				TreeCompressionStrategy.CompressedIncremental /* enableIncrementalSummary */,
 			(cursor: ITreeCursorSynchronous) => this.forest.chunkField(cursor),
 			shouldEncodeIncrementally,
 			initialSequenceNumber,

packages/dds/tree/src/feature-libraries/index.ts

@@ -190,11 +190,7 @@ export {
 	type Observer,
 } from "./flex-tree/index.js";
 
-export {
-	TreeCompressionStrategy,
-	TreeCompressionStrategyExtended,
-	type TreeCompressionStrategyPrivate,
-} from "./treeCompressionUtils.js";
+export { TreeCompressionStrategy } from "./treeCompressionUtils.js";
 
 export { valueSchemaAllows } from "./valueUtilities.js";
 

packages/dds/tree/src/feature-libraries/modular-schema/modularChangeCodecs.ts

@@ -40,10 +40,7 @@ import {
 	chunkFieldSingle,
 	defaultChunkPolicy,
 } from "../chunked-forest/index.js";
-import {
-	TreeCompressionStrategy,
-	type TreeCompressionStrategyPrivate,
-} from "../treeCompressionUtils.js";
+import { TreeCompressionStrategy } from "../treeCompressionUtils.js";
 
 import type { FieldChangeEncodingContext, FieldChangeHandler } from "./fieldChangeHandler.js";
 import type {
@@ -81,7 +78,7 @@ export function makeModularChangeCodecFamily(
 	>,
 	fieldsCodec: FieldBatchCodec,
 	codecOptions: ICodecOptions,
-	chunkCompressionStrategy: TreeCompressionStrategyPrivate = TreeCompressionStrategy.Compressed,
+	chunkCompressionStrategy: TreeCompressionStrategy = TreeCompressionStrategy.Compressed,
 ): ICodecFamily<ModularChangeset, ChangeEncodingContext> {
 	return makeCodecFamily(
 		Array.from(fieldKindConfigurations.entries(), ([version, fieldKinds]) => [
@@ -121,7 +118,7 @@ function makeModularChangeCodec(
 	>,
 	fieldsCodec: FieldBatchCodec,
 	codecOptions: ICodecOptions,
-	chunkCompressionStrategy: TreeCompressionStrategyPrivate = TreeCompressionStrategy.Compressed,
+	chunkCompressionStrategy: TreeCompressionStrategy = TreeCompressionStrategy.Compressed,
 ): ModularChangeCodec {
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 	const getMapEntry = ({ kind, formatVersion }: FieldKindConfigurationEntry) => {

packages/dds/tree/src/feature-libraries/treeCompressionUtils.ts

@@ -20,23 +20,9 @@ export enum TreeCompressionStrategy {
 	 * Use this when debugging or testing and needing to inspect encoded tree content.
 	 */
 	Uncompressed = 1,
-}
-
-/**
- * A private extension of {@link TreeCompressionStrategy} for strategies that are not intended for public use just yet.
- */
-export enum TreeCompressionStrategyExtended {
 	/**
-	 * Optimized for encoded size, same as TreeCompressionStrategy.Compressed. It also enables incremental encoding
+	 * Optimized for encoded size, same as TreeCompressionStrategy.Compressed but it enables incremental encoding
 	 * of the data.
-	 * @remarks
-	 * TODO: AB#41865
-	 * This needs to be stabilized to allow opting into it.
-	 * It could possibly be made the default instead of {@link TreeCompressionStrategy.Compressed}.
 	 */
 	CompressedIncremental = 2,
 }
-
-export type TreeCompressionStrategyPrivate =
-	| TreeCompressionStrategy
-	| TreeCompressionStrategyExtended;

packages/dds/tree/src/index.ts

@@ -52,6 +52,7 @@ export {
 	type TreeIndex,
 	type TreeIndexKey,
 	type TreeIndexNodes,
+	type IncrementalEncodingPolicy,
 } from "./feature-libraries/index.js";
 
 export {
@@ -287,10 +288,13 @@ export {
 	exportCompatibilitySchemaSnapshot,
 	importCompatibilitySchemaSnapshot,
 	checkCompatibility,
+	incrementalSummaryHint,
+	incrementalEncodingPolicyForAllowedTypes,
 } from "./simple-tree/index.js";
 export {
 	SharedTree,
 	configuredSharedTree,
+	configuredSharedTreeAlpha,
 	configuredSharedTreeBeta,
 	configuredSharedTreeBetaLegacy,
 } from "./treeFactory.js";

packages/dds/tree/src/shared-tree-core/index.ts

@@ -27,7 +27,7 @@ export {
 	type SummaryElementParser,
 	type SummaryElementStringifier,
 	type ClonableSchemaAndPolicy,
-	type SharedTreeCoreOptionsInternal as SharedTreCoreOptionsInternal,
+	type SharedTreeCoreOptionsInternal,
 } from "./sharedTreeCore.js";
 
 export type { ResubmitMachine } from "./resubmitMachine.js";

packages/dds/tree/src/shared-tree/sharedTree.ts

@@ -64,7 +64,6 @@ import {
 	makeSchemaCodec,
 	makeTreeChunker,
 	type IncrementalEncodingPolicy,
-	type TreeCompressionStrategyPrivate,
 } from "../feature-libraries/index.js";
 // eslint-disable-next-line import-x/no-internal-modules
 import type { FormatV1 } from "../feature-libraries/schema-index/index.js";
@@ -75,7 +74,7 @@ import {
 	type ClonableSchemaAndPolicy,
 	getCodecTreeForEditManagerFormatWithChange,
 	getCodecTreeForMessageFormatWithChange,
-	type SharedTreCoreOptionsInternal,
+	type SharedTreeCoreOptionsInternal,
 	MessageFormatVersion,
 	SharedTreeCore,
 	EditManagerFormatVersion,
@@ -656,26 +655,19 @@ export function getCodecTreeForSharedTreeFormat(
 export type SharedTreeOptionsBeta = ForestOptions;
 
 /**
- * Configuration options for SharedTree.
+ * Configuration options for SharedTree with alpha features.
  * @alpha @input
  */
 export interface SharedTreeOptions
-	extends Partial<CodecWriteOptions>,
-		Partial<SharedTreeFormatOptions>,
-		SharedTreeOptionsBeta {
+	extends SharedTreeOptionsBeta,
+		Partial<CodecWriteOptions>,
+		Partial<SharedTreeFormatOptions> {
 	/**
 	 * Experimental feature flag to enable shared branches.
 	 * This feature is not yet complete and should not be used in production.
 	 * Defaults to false.
 	 */
 	readonly enableSharedBranches?: boolean;
-}
-
-export interface SharedTreeOptionsInternal
-	extends Partial<SharedTreCoreOptionsInternal>,
-		Partial<ForestOptions>,
-		Partial<SharedTreeFormatOptionsInternal> {
-	disposeForksAfterTransaction?: boolean;
 	/**
 	 * Returns whether a node / field should be incrementally encoded.
 	 * @remarks
@@ -684,6 +676,12 @@ export interface SharedTreeOptionsInternal
 	shouldEncodeIncrementally?: IncrementalEncodingPolicy;
 }
 
+export interface SharedTreeOptionsInternal
+	extends SharedTreeOptions,
+		Partial<SharedTreeCoreOptionsInternal> {
+	disposeForksAfterTransaction?: boolean;
+}
+
 /**
  * Configuration options for SharedTree's internal tree storage.
  * @beta @input
@@ -707,11 +705,6 @@ export interface SharedTreeFormatOptions {
 	treeEncodeType: TreeCompressionStrategy;
 }
 
-export interface SharedTreeFormatOptionsInternal
-	extends Omit<SharedTreeFormatOptions, "treeEncodeType"> {
-	treeEncodeType: TreeCompressionStrategyPrivate;
-}
-
 /**
  * Used to distinguish between different forest types.
  * @remarks
@@ -814,6 +807,7 @@ export const defaultSharedTreeOptions: Required<SharedTreeOptionsInternal> = {
 	shouldEncodeIncrementally: defaultIncrementalEncodingPolicy,
 	editManagerFormatSelector: clientVersionToEditManagerFormatVersion,
 	messageFormatSelector: clientVersionToMessageFormatVersion,
+	enableSharedBranches: false,
 };
 
 /**