@fluidframework/tree 2.73.0 → 2.74.0-368706

package/src/shared-tree-core/{editManagerCodecsV5.ts → editManagerCodecsVSharedBranches.ts}

@@ -25,7 +25,7 @@ import {
 } from "../util/index.js";
 
 import type { SharedBranchSummaryData, SummaryData } from "./editManager.js";
-import { EncodedEditManager } from "./editManagerFormatV5.js";
+import { EncodedEditManager } from "./editManagerFormatVSharedBranches.js";
 import { decodeSharedBranch, encodeSharedBranch } from "./editManagerCodecsCommons.js";
 import type { EncodedSharedBranch } from "./editManagerFormatCommons.js";
 import type { BranchId } from "./branch.js";
@@ -35,7 +35,7 @@ export interface EditManagerEncodingContext {
 	readonly schema?: SchemaAndPolicy;
 }
 
-export function makeV5CodecWithVersion<TChangeset>(
+export function makeSharedBranchesCodecWithVersion<TChangeset>(
 	changeCodec: IMultiFormatCodec<
 		TChangeset,
 		JsonCompatibleReadOnly,
@@ -78,7 +78,7 @@ export function makeV5CodecWithVersion<TChangeset>(
 				);
 				assert(
 					data.originator !== undefined,
-					0xc65 /* Cannot encode V5 summary without originator */,
+					"Cannot encode vSharedBranches summary without originator",
 				);
 				const json: Mutable<EncodedEditManager<TChangeset>> = {
 					main: mainBranch,

package/src/shared-tree-core/editManagerFormatCommons.ts

@@ -136,22 +136,36 @@ export const EditManagerFormatVersion = {
 	v2: 2,
 	/**
 	 * Introduced prior to 2.0 and used beyond.
-	 * Reading capability is currently maintained for backwards compatibility, but it could be removed in the future.
-	 * Writing capability needs to be maintained.
+	 * Reading capability must be maintained for backwards compatibility.
+	 * Writing capability needs to be maintained so long as {@link lowestMinVersionForCollab} is less than 2.2.0.
 	 */
 	v3: 3,
 	/**
-	 * Was inadvertently released in 2.43.0 (through usages of configuredSharedTree) and remains available.
+	 * Introduced in 2.2.0.
+	 * Was inadvertently made usable for writing in 2.43.0 (through configuredSharedTree) and remains available.
 	 * Reading capability must be maintained for backwards compatibility.
-	 * Writing capability needs to be maintained.
-	 * @privateRemarks TODO: stop writing this version.
+	 * Writing capability could be dropped in favor of {@link EditManagerFormatVersion.v3},
+	 * but doing so would make the pattern of writable versions more complex and gain little
+	 * because most of the logic for this format is shared with {@link EditManagerFormatVersion.v3}.
 	 */
 	v4: 4,
+	/**
+	 * This version number was used internally for testing shared branches.
+	 * This format was never made stable.
+	 * This version number is kept here solely to avoid reusing the number: it is not supported for either reading or writing.
+	 * @deprecated Use {@link EditManagerFormatVersion.vSharedBranches} for testing shared branches.
+	 */
+	v5: 5,
 	/**
 	 * Not yet released.
 	 * Only used for testing shared branches.
 	 */
-	v5: 5,
+	vSharedBranches: "shared-branches|v0.1",
+	/**
+	 * Not yet released.
+	 * Only used for testing detached roots.
+	 */
+	vDetachedRoots: "detached-roots|v0.1",
 } as const;
 export type EditManagerFormatVersion = Brand<
 	(typeof EditManagerFormatVersion)[keyof typeof EditManagerFormatVersion],
@@ -161,7 +175,8 @@ export const supportedEditManagerFormatVersions: ReadonlySet<EditManagerFormatVe
 	new Set([
 		EditManagerFormatVersion.v3,
 		EditManagerFormatVersion.v4,
-		EditManagerFormatVersion.v5,
+		EditManagerFormatVersion.vSharedBranches,
+		EditManagerFormatVersion.vDetachedRoots,
 	] as EditManagerFormatVersion[]);
 export const editManagerFormatVersions: ReadonlySet<EditManagerFormatVersion> = new Set(
 	Object.values(EditManagerFormatVersion) as EditManagerFormatVersion[],

package/src/shared-tree-core/editManagerFormatV1toV4.ts

@@ -26,7 +26,8 @@ export interface EncodedEditManager<TChangeset> {
 		| typeof EditManagerFormatVersion.v1
 		| typeof EditManagerFormatVersion.v2
 		| typeof EditManagerFormatVersion.v3
-		| typeof EditManagerFormatVersion.v4;
+		| typeof EditManagerFormatVersion.v4
+		| typeof EditManagerFormatVersion.vDetachedRoots;
 }
 
 export const EncodedEditManager = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
@@ -37,6 +38,7 @@ export const EncodedEditManager = <ChangeSchema extends TSchema>(tChange: Change
 				Type.Literal(EditManagerFormatVersion.v2),
 				Type.Literal(EditManagerFormatVersion.v3),
 				Type.Literal(EditManagerFormatVersion.v4),
+				Type.Literal(EditManagerFormatVersion.vDetachedRoots),
 			]),
 			trunk: Type.Array(SequencedCommit(tChange)),
 			branches: Type.Array(Type.Tuple([SessionIdSchema, SummarySessionBranch(tChange)])),

package/src/shared-tree-core/{editManagerFormatV5.ts → editManagerFormatVSharedBranches.ts}

@@ -15,7 +15,7 @@ const noAdditionalProps: ObjectOptions = { additionalProperties: false };
 /* eslint-disable @typescript-eslint/explicit-function-return-type */
 
 export interface EncodedEditManager<TChangeset> {
-	readonly version: typeof EditManagerFormatVersion.v5;
+	readonly version: typeof EditManagerFormatVersion.vSharedBranches;
 	readonly originator: SessionId;
 	readonly main: EncodedSharedBranch<TChangeset>;
 	readonly branches?: readonly EncodedSharedBranch<TChangeset>[];
@@ -24,7 +24,7 @@ export interface EncodedEditManager<TChangeset> {
 export const EncodedEditManager = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
 	Type.Object(
 		{
-			version: Type.Union([Type.Literal(EditManagerFormatVersion.v5)]),
+			version: Type.Literal(EditManagerFormatVersion.vSharedBranches),
 			originator: SessionIdSchema,
 			main: EncodedSharedBranch(tChange),
 			branches: Type.Optional(Type.Array(EncodedSharedBranch(tChange))),

package/src/shared-tree-core/editManagerSummarizer.ts

@@ -9,10 +9,10 @@ import type { IChannelStorageService } from "@fluidframework/datastore-definitio
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 import type {
 	IExperimentalIncrementalSummaryContext,
-	ISummaryTreeWithStats,
 	ITelemetryContext,
+	MinimumVersionForCollab,
 } from "@fluidframework/runtime-definitions/internal";
-import { createSingleBlobSummary } from "@fluidframework/shared-object-base/internal";
+import type { SummaryTreeBuilder } from "@fluidframework/runtime-utils/internal";
 
 import type { IJsonCodec } from "../codec/index.js";
 import type { ChangeFamily, ChangeFamilyEditor, SchemaAndPolicy } from "../core/index.js";
@@ -24,16 +24,52 @@ import type {
 	Summarizable,
 	SummaryElementParser,
 	SummaryElementStringifier,
-} from "./sharedTreeCore.js";
+} from "./summaryTypes.js";
+import { VersionedSummarizer } from "./versionedSummarizer.js";
 
-const stringKey = "String";
+export const stringKey = "String";
 
 /**
- * Provides methods for summarizing and loading an `EditManager`
+ * The versions for the edit manager summary format.
  */
-export class EditManagerSummarizer<TChangeset> implements Summarizable {
-	public readonly key = "EditManager";
+export const enum EditManagerSummaryFormatVersion {
+	/**
+	 * This version represents summary format before summary versioning was introduced.
+	 */
+	v1 = 1,
+	/**
+	 * This version adds metadata to the summary. This is backward compatible with version 1.
+	 */
+	v2 = 2,
+	/**
+	 * The latest version of the summary. Must be updated when a new version is added.
+	 */
+	vLatest = v2,
+}
+
+const supportedVersions = new Set<EditManagerSummaryFormatVersion>([
+	EditManagerSummaryFormatVersion.v1,
+	EditManagerSummaryFormatVersion.v2,
+]);
+
+/**
+ * Returns the summary version to use as per the given minimum version for collab.
+ */
+function minVersionToEditManagerSummaryFormatVersion(
+	version: MinimumVersionForCollab,
+): EditManagerSummaryFormatVersion {
+	// Currently, version 2 is written which adds metadata blob to the summary.
+	return EditManagerSummaryFormatVersion.v2;
+}
 
+/**
+ * Provides methods for summarizing and loading an `EditManager`
+ */
+export class EditManagerSummarizer<TChangeset>
+	extends VersionedSummarizer<EditManagerSummaryFormatVersion>
+	implements Summarizable
+{
+	public static readonly key = "EditManager";
 	public constructor(
 		private readonly editManager: EditManager<
 			ChangeFamilyEditor,
@@ -47,30 +83,36 @@ export class EditManagerSummarizer<TChangeset> implements Summarizable {
 			EditManagerEncodingContext
 		>,
 		private readonly idCompressor: IIdCompressor,
+		minVersionForCollab: MinimumVersionForCollab,
 		private readonly schemaAndPolicy?: SchemaAndPolicy,
-	) {}
+	) {
+		super(
+			EditManagerSummarizer.key,
+			minVersionToEditManagerSummaryFormatVersion(minVersionForCollab),
+			supportedVersions,
+			true /* supportPreVersioningFormat */,
+		);
+	}
 
-	public summarize(props: {
+	protected summarizeInternal(props: {
 		stringify: SummaryElementStringifier;
 		fullTree?: boolean;
 		trackState?: boolean;
 		telemetryContext?: ITelemetryContext;
 		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext;
-	}): ISummaryTreeWithStats {
-		return this.summarizeCore(props.stringify);
-	}
-
-	private summarizeCore(stringify: SummaryElementStringifier): ISummaryTreeWithStats {
+		builder: SummaryTreeBuilder;
+	}): void {
+		const { stringify, builder } = props;
 		const context: EditManagerEncodingContext =
 			this.schemaAndPolicy !== undefined
 				? { schema: this.schemaAndPolicy, idCompressor: this.idCompressor }
 				: { idCompressor: this.idCompressor };
 		const jsonCompatible = this.codec.encode(this.editManager.getSummaryData(), context);
 		const dataString = stringify(jsonCompatible);
-		return createSingleBlobSummary(stringKey, dataString);
+		builder.addBlob(stringKey, dataString);
 	}
 
-	public async load(
+	protected async loadInternal(
 		services: IChannelStorageService,
 		parse: SummaryElementParser,
 	): Promise<void> {

package/src/shared-tree-core/index.ts

@@ -23,12 +23,18 @@ export {
 
 export {
 	SharedTreeCore,
+	type ClonableSchemaAndPolicy,
+	type SharedTreeCoreOptionsInternal,
+} from "./sharedTreeCore.js";
+export {
+	SharedTreeSummaryFormatVersion,
+	type SharedTreeSummarizableMetadata,
 	type Summarizable,
 	type SummaryElementParser,
 	type SummaryElementStringifier,
-	type ClonableSchemaAndPolicy,
-	type SharedTreeCoreOptionsInternal as SharedTreCoreOptionsInternal,
-} from "./sharedTreeCore.js";
+	summarizablesMetadataKey,
+} from "./summaryTypes.js";
+export { VersionedSummarizer } from "./versionedSummarizer.js";
 
 export type { ResubmitMachine } from "./resubmitMachine.js";
 export { DefaultResubmitMachine } from "./defaultResubmitMachine.js";
@@ -45,6 +51,7 @@ export {
 	type EditManagerCodecOptions,
 	clientVersionToEditManagerFormatVersion,
 	editManagerFormatVersionSelectorForSharedBranches,
+	editManagerFormatVersionSelectorForDetachedRootEditing,
 } from "./editManagerCodecs.js";
 export {
 	EditManagerFormatVersion,
@@ -69,6 +76,7 @@ export {
 	getCodecTreeForMessageFormatWithChange,
 	clientVersionToMessageFormatVersion,
 	messageFormatVersionSelectorForSharedBranches,
+	messageFormatVersionSelectorForDetachedRootEditing,
 } from "./messageCodecs.js";
 export {
 	MessageFormatVersion,

package/src/shared-tree-core/messageCodecV1ToV4.ts

@@ -33,7 +33,8 @@ export function makeV1ToV4CodecWithVersion<TChangeset>(
 		| typeof MessageFormatVersion.v1
 		| typeof MessageFormatVersion.v2
 		| typeof MessageFormatVersion.v3
-		| typeof MessageFormatVersion.v4,
+		| typeof MessageFormatVersion.v4
+		| typeof MessageFormatVersion.vDetachedRoots,
 ): IJsonCodec<
 	DecodedMessage<TChangeset>,
 	JsonCompatibleReadOnly,

package/src/shared-tree-core/{messageCodecV5.ts → messageCodecVSharedBranches.ts}

@@ -14,14 +14,14 @@ import type {
 } from "../core/index.js";
 import type { JsonCompatibleReadOnly } from "../util/index.js";
 
-import { Message } from "./messageFormatV5.js";
+import { Message } from "./messageFormatVSharedBranches.js";
 import type { DecodedMessage } from "./messageTypes.js";
 import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 import type { MessageEncodingContext } from "./messageCodecs.js";
 import { decodeBranchId, encodeBranchId } from "./branchIdCodec.js";
 import type { MessageFormatVersion } from "./messageFormat.js";
 
-export function makeV5CodecWithVersion<TChangeset>(
+export function makeSharedBranchesCodecWithVersion<TChangeset>(
 	changeCodec: ChangeFamilyCodec<TChangeset>,
 	revisionTagCodec: IJsonCodec<
 		RevisionTag,
@@ -30,7 +30,7 @@ export function makeV5CodecWithVersion<TChangeset>(
 		ChangeEncodingContext
 	>,
 	options: ICodecOptions,
-	version: typeof MessageFormatVersion.v5,
+	version: typeof MessageFormatVersion.vSharedBranches,
 ): IJsonCodec<
 	DecodedMessage<TChangeset>,
 	JsonCompatibleReadOnly,

package/src/shared-tree-core/messageCodecs.ts

@@ -34,7 +34,7 @@ import { brand, type JsonCompatibleReadOnly } from "../util/index.js";
 import type { DecodedMessage } from "./messageTypes.js";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 import { makeV1ToV4CodecWithVersion } from "./messageCodecV1ToV4.js";
-import { makeV5CodecWithVersion } from "./messageCodecV5.js";
+import { makeSharedBranchesCodecWithVersion } from "./messageCodecVSharedBranches.js";
 import { MessageFormatVersion, messageFormatVersions } from "./messageFormat.js";
 
 export interface MessageEncodingContext {
@@ -79,7 +79,16 @@ function messageFormatVersionFromOptions(
 export function messageFormatVersionSelectorForSharedBranches(
 	clientVersion: MinimumVersionForCollab,
 ): MessageFormatVersion {
-	return brand(MessageFormatVersion.v5);
+	return brand(MessageFormatVersion.vSharedBranches);
+}
+
+/**
+ * Returns the version that should be used for testing detached root editing.
+ */
+export function messageFormatVersionSelectorForDetachedRootEditing(
+	clientVersion: MinimumVersionForCollab,
+): MessageFormatVersion {
+	return brand(MessageFormatVersion.vDetachedRoots);
 }
 
 export function makeMessageCodec<TChangeset>(
@@ -143,7 +152,8 @@ export function makeMessageCodecs<TChangeset>(
 				];
 			}
 			case MessageFormatVersion.v3:
-			case MessageFormatVersion.v4: {
+			case MessageFormatVersion.v4:
+			case MessageFormatVersion.vDetachedRoots: {
 				const changeCodec = changeCodecs.resolve(
 					dependentChangeFormatVersion.lookup(version),
 				).json;
@@ -152,13 +162,15 @@ export function makeMessageCodecs<TChangeset>(
 					makeV1ToV4CodecWithVersion(changeCodec, revisionTagCodec, options, version),
 				];
 			}
-			case MessageFormatVersion.v5: {
+			case MessageFormatVersion.v5:
+				return [version, makeDiscontinuedCodecVersion(options, version, "2.74.0")];
+			case MessageFormatVersion.vSharedBranches: {
 				const changeCodec = changeCodecs.resolve(
 					dependentChangeFormatVersion.lookup(version),
 				).json;
 				return [
 					version,
-					makeV5CodecWithVersion(changeCodec, revisionTagCodec, options, version),
+					makeSharedBranchesCodecWithVersion(changeCodec, revisionTagCodec, options, version),
 				];
 			}
 			default:

package/src/shared-tree-core/messageFormat.ts

@@ -27,22 +27,36 @@ export const MessageFormatVersion = {
 	v2: 2,
 	/**
 	 * Introduced prior to 2.0 and used beyond.
-	 * Reading capability is currently maintained for backwards compatibility, but it could be removed in the future.
-	 * Writing capability needs to be maintained.
+	 * Reading capability must be maintained for backwards compatibility.
+	 * Writing capability needs to be maintained so long as {@link lowestMinVersionForCollab} is less than 2.2.0.
 	 */
 	v3: 3,
 	/**
-	 * Was inadvertently released in 2.43.0 (through usages of configuredSharedTree) and remains available.
+	 * Introduced in 2.2.0.
+	 * Was inadvertently made usable for writing in 2.43.0 (through configuredSharedTree) and remains available.
 	 * Reading capability must be maintained for backwards compatibility.
-	 * Writing capability needs to be maintained.
-	 * @privateRemarks TODO: stop writing this version.
+	 * Writing capability could be dropped in favor of {@link MessageFormatVersion.v3},
+	 * but doing so would make the pattern of writable versions more complex and gain little
+	 * because most of the logic for this format is shared with {@link MessageFormatVersion.v3}.
 	 */
 	v4: 4,
+	/**
+	 * This version number was used internally for testing shared branches.
+	 * This format was never made stable.
+	 * This version number is kept here solely to avoid reusing the number: it is not supported for either reading or writing.
+	 * @deprecated Use {@link MessageFormatVersion.vSharedBranches} for testing shared branches.
+	 */
+	v5: 5,
 	/**
 	 * Not yet released.
 	 * Only used for testing shared branches.
 	 */
-	v5: 5,
+	vSharedBranches: "shared-branches|v0.1",
+	/**
+	 * Not yet released.
+	 * Only used for testing detached roots.
+	 */
+	vDetachedRoots: "detached-roots|v0.1",
 } as const;
 export type MessageFormatVersion = Brand<
 	(typeof MessageFormatVersion)[keyof typeof MessageFormatVersion],
@@ -51,7 +65,8 @@ export type MessageFormatVersion = Brand<
 export const supportedMessageFormatVersions: ReadonlySet<MessageFormatVersion> = new Set([
 	MessageFormatVersion.v3,
 	MessageFormatVersion.v4,
-	MessageFormatVersion.v5,
+	MessageFormatVersion.vSharedBranches,
+	MessageFormatVersion.vDetachedRoots,
 ] as MessageFormatVersion[]);
 export const messageFormatVersions: ReadonlySet<MessageFormatVersion> = new Set(
 	Object.values(MessageFormatVersion) as MessageFormatVersion[],

package/src/shared-tree-core/messageFormatV1ToV4.ts

@@ -8,6 +8,7 @@ import { type TSchema, Type } from "@sinclair/typebox";
 
 import { type EncodedRevisionTag, RevisionTagSchema, SessionIdSchema } from "../core/index.js";
 import type { JsonCompatibleReadOnly } from "../util/index.js";
+import { MessageFormatVersion } from "./messageFormat.js";
 
 /**
  * The format of messages that SharedTree sends and receives.
@@ -32,7 +33,12 @@ export interface Message {
 	 * This was not set historically and was added before making any breaking changes to the format.
 	 * For that reason, absence of a 'version' field is synonymous with version 1.
 	 */
-	readonly version?: number;
+	readonly version?:
+		| typeof MessageFormatVersion.v1
+		| typeof MessageFormatVersion.v2
+		| typeof MessageFormatVersion.v3
+		| typeof MessageFormatVersion.v4
+		| typeof MessageFormatVersion.vDetachedRoots;
 }
 
 // Return type is intentionally derived.
@@ -42,5 +48,13 @@ export const Message = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
 		revision: RevisionTagSchema,
 		originatorId: SessionIdSchema,
 		changeset: tChange,
-		version: Type.Optional(Type.Number()),
+		version: Type.Optional(
+			Type.Union([
+				Type.Literal(MessageFormatVersion.v1),
+				Type.Literal(MessageFormatVersion.v2),
+				Type.Literal(MessageFormatVersion.v3),
+				Type.Literal(MessageFormatVersion.v4),
+				Type.Literal(MessageFormatVersion.vDetachedRoots),
+			]),
+		),
 	});

package/src/shared-tree-core/{messageFormatV5.ts → messageFormatVSharedBranches.ts}

@@ -9,6 +9,7 @@ import { type TSchema, Type } from "@sinclair/typebox";
 import { type EncodedRevisionTag, RevisionTagSchema, SessionIdSchema } from "../core/index.js";
 import type { JsonCompatibleReadOnly } from "../util/index.js";
 import type { EncodedBranchId } from "./branch.js";
+import { MessageFormatVersion } from "./messageFormat.js";
 
 /**
  * The format of messages that SharedTree sends and receives.
@@ -30,12 +31,9 @@ export interface Message {
 	readonly branchId?: EncodedBranchId;
 
 	/**
-	 * The version of the message. This controls how the message is encoded.
-	 *
-	 * This was not set historically and was added before making any breaking changes to the format.
-	 * For that reason, absence of a 'version' field is synonymous with version 1.
+	 * The version of the message format.
 	 */
-	readonly version?: number;
+	readonly version: typeof MessageFormatVersion.vSharedBranches;
 }
 
 // Return type is intentionally derived.
@@ -46,5 +44,5 @@ export const Message = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
 		originatorId: SessionIdSchema,
 		changeset: Type.Optional(tChange),
 		branchId: Type.Optional(Type.Number()),
-		version: Type.Optional(Type.Number()),
+		version: Type.Literal(MessageFormatVersion.vSharedBranches),
 	});