@fluidframework/tree 2.74.0-365691 → 2.74.0-368706

package/src/feature-libraries/optional-field/optionalFieldChangeTypes.ts

@@ -6,48 +6,19 @@
 import type { ChangeAtomId } from "../../core/index.js";
 import type { NodeId } from "../modular-schema/index.js";
 
-/**
- * Uniquely identifies a register within the scope of this changeset.
- * The sentinel value "self" is used for the active register, which is a universally shared register
- * (as in, any changeset referring to "self" refers to the register containing the active value of the field).
- *
- * See the model description in {@link OptionalChangeset} for more details.
- */
-export type RegisterId = ChangeAtomId | "self";
-
-export type Move = readonly [src: ChangeAtomId, dst: ChangeAtomId];
-
-export type ChildChange = readonly [register: RegisterId, childChange: NodeId];
-
 /**
  * Changes to an optional field.
  *
- * The model used is that optional field consists of a collection of "registers" with one designated as the "active" register.
- * In a given change input or output context, registers may hold 0 or 1 nodes.
- * Each register is identified using a {@link RegisterId}.
- * The active register holds the current value of the field, and other registers hold detached roots.
+ * The model used is that optional field consists of a single register.
+ * In a given change input or output context, this register may hold 0 or 1 nodes.
  */
 export interface OptionalChangeset {
-	/**
-	 * Each entry signifies the intent to move a node from `src` to `dst`.
-	 * Moves to or from the "self" register are represented in {@link valueReplace}.
-	 *
-	 * These entries should not be interpreted as "applied one after the other", but rather as "applied simultaneously".
-	 * As such, changesets should not contain duplicated src or dst entries.
-	 */
-	readonly moves: readonly Move[];
-
-	/**
-	 * Nested changes to nodes that occupy registers.
-	 *
-	 * Nodes are identified by the register they occupy in the *input* context of the changeset.
-	 */
-	readonly childChanges: readonly ChildChange[];
-
 	/**
 	 * An optional description of how to replace the current value of the field.
 	 */
 	readonly valueReplace?: Replace;
+	readonly nodeDetach?: ChangeAtomId;
+	readonly childChange?: NodeId;
 }
 
 export interface Replace {
@@ -57,13 +28,28 @@ export interface Replace {
 	readonly isEmpty: boolean;
 
 	/**
-	 * The ID for the node to put in this field, or undefined if the field should be emptied.
-	 * Will be "self" when the intention is to keep the current node in this field.
+	 * An ID to associate with the node (if any) which is detached by this edit.
+	 *
+	 * When the field is empty in the input context, this ID is dormant in the sense that it would not be used if the changeset were applied as is.
+	 * However, it can become active if the changeset is rebased over a change that attaches a node in the field.
 	 */
-	readonly src?: RegisterId;
+	readonly dst: ChangeAtomId;
 
 	/**
-	 * An ID to associate with the node (if any) which is detached by this edit.
+	 * The ID for the node to attach in this field, or undefined if no node should be attached.
+	 *
+	 * Note that this ID may refer to the node detached by this changeset:
+	 * The node in the field is detached and associated with ID `dst`,
+	 * then that node is renamed from `dst` to `src` (at the ModularChangeset level),
+	 * then that node is attached back into the field.
+	 * When this is the case, we say that the node is being pinned in the field.
+	 * While a pin has no effect on the document state if applied as-is, its merge semantics are different from an empty changeset.
+	 * This is because rebasing a pin over a change that detaches the node from the field will result in a changeset that re-attaches the node to the field.
+	 * In other words, a pin guarantees that the node will be in the field after the changeset is rebased and applied, whereas an empty changeset does not.
+	 *
+	 * `src` must be structurally different from `dst` even when the changeset is a pin.
+	 * An optional field changeset that aims to attach a node must be able to affect two nodes,
+	 * so unless we want to mint new IDs during rebasing, such a changeset must have two different IDs.
 	 */
-	readonly dst: ChangeAtomId;
+	readonly src?: ChangeAtomId;
 }

package/src/feature-libraries/optional-field/optionalFieldCodecV2.ts

@@ -6,11 +6,12 @@
 import type { TAnySchema } from "@sinclair/typebox";
 
 import type { IJsonCodec } from "../../codec/index.js";
-import type {
-	ChangeAtomId,
-	ChangeEncodingContext,
-	EncodedRevisionTag,
-	RevisionTag,
+import {
+	areEqualChangeAtomIdOpts,
+	type ChangeAtomId,
+	type ChangeEncodingContext,
+	type EncodedRevisionTag,
+	type RevisionTag,
 } from "../../core/index.js";
 import type { Mutable } from "../../util/index.js";
 import { makeChangeAtomIdCodec } from "../changeAtomIdCodec.js";
@@ -21,7 +22,10 @@ import {
 } from "../modular-schema/index.js";
 
 import { EncodedOptionalChangeset, EncodedRegisterId } from "./optionalFieldChangeFormatV2.js";
-import type { OptionalChangeset, RegisterId, Replace } from "./optionalFieldChangeTypes.js";
+import type { OptionalChangeset, Replace } from "./optionalFieldChangeTypes.js";
+import { assert } from "@fluidframework/core-utils/internal";
+
+type RegisterId = ChangeAtomId | "self";
 
 function makeRegisterIdCodec(
 	changeAtomIdCodec: IJsonCodec<
@@ -66,14 +70,13 @@ export function makeOptionalFieldCodec(
 
 	return {
 		encode: (change: OptionalChangeset, context: FieldChangeEncodingContext) => {
-			const encoded: EncodedOptionalChangeset<TAnySchema> = {};
+			assert(
+				change.nodeDetach === undefined ||
+					areEqualChangeAtomIdOpts(change.valueReplace?.src, change.nodeDetach),
+				"This format only supports node detach when it represents a pin",
+			);
 
-			if (change.moves.length > 0) {
-				encoded.m = change.moves.map(([src, dst]) => [
-					changeAtomIdCodec.encode(src, context.baseContext),
-					changeAtomIdCodec.encode(dst, context.baseContext),
-				]);
-			}
+			const encoded: EncodedOptionalChangeset<TAnySchema> = {};
 
 			if (change.valueReplace !== undefined) {
 				encoded.r = {
@@ -81,18 +84,48 @@ export function makeOptionalFieldCodec(
 					d: changeAtomIdCodec.encode(change.valueReplace.dst, context.baseContext),
 				};
 				if (change.valueReplace.src !== undefined) {
-					encoded.r.s = registerIdCodec.encode(change.valueReplace.src, context.baseContext);
+					const srcRegister =
+						change.nodeDetach === undefined ? change.valueReplace.src : "self";
+
+					encoded.r.s = registerIdCodec.encode(srcRegister, context.baseContext);
 				}
 			}
 
-			if (change.childChanges.length > 0) {
-				encoded.c = [];
-				for (const [id, childChange] of change.childChanges) {
-					encoded.c.push([
-						registerIdCodec.encode(id, context.baseContext),
-						context.encodeNode(childChange),
-					]);
-				}
+			const encodedChildChanges: [EncodedRegisterId, EncodedNodeChangeset][] = [];
+
+			if (change.childChange !== undefined) {
+				encodedChildChanges.push([null, context.encodeNode(change.childChange)]);
+			}
+
+			for (const [detachId, nodeId] of context.rootNodeChanges.entries()) {
+				encodedChildChanges.push([
+					changeAtomIdCodec.encode(
+						{ revision: detachId[0], localId: detachId[1] },
+						context.baseContext,
+					),
+					context.encodeNode(nodeId),
+				]);
+			}
+
+			if (encodedChildChanges.length > 0) {
+				encoded.c = encodedChildChanges;
+			}
+
+			const encodedMoves: [EncodedChangeAtomId, EncodedChangeAtomId][] = [];
+			for (const {
+				start: oldId,
+				value: newId,
+				length: count,
+			} of context.rootRenames.entries()) {
+				assert(count === 1, "Unexpected range rename in optional field");
+				encodedMoves.push([
+					changeAtomIdCodec.encode(oldId, context.baseContext),
+					changeAtomIdCodec.encode(newId, context.baseContext),
+				]);
+			}
+
+			if (encodedMoves.length > 0) {
+				encoded.m = encodedMoves;
 			}
 
 			return encoded;
@@ -102,18 +135,7 @@ export function makeOptionalFieldCodec(
 			encoded: EncodedOptionalChangeset<TAnySchema>,
 			context: FieldChangeEncodingContext,
 		) => {
-			const decoded: Mutable<OptionalChangeset> = {
-				moves:
-					encoded.m?.map(([encodedSrc, encodedDst]) => [
-						changeAtomIdCodec.decode(encodedSrc, context.baseContext),
-						changeAtomIdCodec.decode(encodedDst, context.baseContext),
-					]) ?? [],
-				childChanges:
-					encoded.c?.map(([id, encodedChange]) => [
-						registerIdCodec.decode(id, context.baseContext),
-						context.decodeNode(encodedChange),
-					]) ?? [],
-			};
+			const decoded: Mutable<OptionalChangeset> = {};
 
 			if (encoded.r !== undefined) {
 				const replace: Mutable<Replace> = {
@@ -121,10 +143,42 @@ export function makeOptionalFieldCodec(
 					dst: changeAtomIdCodec.decode(encoded.r.d, context.baseContext),
 				};
 				if (encoded.r.s !== undefined) {
-					replace.src = registerIdCodec.decode(encoded.r.s, context.baseContext);
+					const register = registerIdCodec.decode(encoded.r.s, context.baseContext);
+					if (register === "self") {
+						// Note that this is safe as long as we assume that this change will not be rebased
+						// over a move to a sequence field.
+						// The ID of an attach and accompanying detach/rename is arbitrary, except in sequence field where
+						// the ID of the detach becomes a cell ID which may be referenced by other changes.
+						replace.src = context.generateId();
+						decoded.nodeDetach = replace.src;
+					} else {
+						replace.src = register;
+					}
 				}
 				decoded.valueReplace = replace;
 			}
+
+			if (encoded.c !== undefined) {
+				for (const [encodedDetachId, nodeChange] of encoded.c) {
+					if (encodedDetachId !== null) {
+						context.decodeRootNodeChange(
+							changeAtomIdCodec.decode(encodedDetachId, context.baseContext),
+							nodeChange,
+						);
+					} else {
+						decoded.childChange = context.decodeNode(nodeChange);
+					}
+				}
+			}
+
+			for (const [encodedOldId, encodedNewId] of encoded.m ?? []) {
+				context.decodeRootRename(
+					changeAtomIdCodec.decode(encodedOldId, context.baseContext),
+					changeAtomIdCodec.decode(encodedNewId, context.baseContext),
+					1,
+				);
+			}
+
 			return decoded;
 		},
 		encodedSchema: EncodedOptionalChangeset(EncodedNodeChangeset),

package/src/feature-libraries/schema-index/schemaSummarizer.ts

@@ -9,10 +9,10 @@ import type { IChannelStorageService } from "@fluidframework/datastore-definitio
 import { SummaryType } from "@fluidframework/driver-definitions";
 import type {
 	IExperimentalIncrementalSummaryContext,
-	ISummaryTreeWithStats,
 	ITelemetryContext,
+	MinimumVersionForCollab,
 } from "@fluidframework/runtime-definitions/internal";
-import { SummaryTreeBuilder } from "@fluidframework/runtime-utils/internal";
+import type { SummaryTreeBuilder } from "@fluidframework/runtime-utils/internal";
 
 import type { IJsonCodec } from "../../codec/index.js";
 import {
@@ -21,30 +21,73 @@ import {
 	type TreeStoredSchema,
 	schemaDataIsEmpty,
 } from "../../core/index.js";
-import type {
-	Summarizable,
-	SummaryElementParser,
-	SummaryElementStringifier,
+import {
+	VersionedSummarizer,
+	type Summarizable,
+	type SummaryElementParser,
+	type SummaryElementStringifier,
 } from "../../shared-tree-core/index.js";
 import type { JsonCompatible } from "../../util/index.js";
 import type { CollabWindow } from "../incrementalSummarizationUtils.js";
 
 import { encodeRepo } from "./codec.js";
 
-const schemaStringKey = "SchemaString";
+export const schemaStringKey = "SchemaString";
+
 /**
- * Provides methods for summarizing and loading a schema repository.
+ * The versions for the schema summary format.
+ */
+export const enum SchemaSummaryFormatVersion {
+	/**
+	 * 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<SchemaSummaryFormatVersion>([
+	SchemaSummaryFormatVersion.v1,
+	SchemaSummaryFormatVersion.v2,
+]);
+
+/**
+ * Returns the summary version to use as per the given minimum version for collab.
  */
-export class SchemaSummarizer implements Summarizable {
-	public readonly key = "Schema";
+function minVersionToSchemaSummaryFormatVersion(
+	version: MinimumVersionForCollab,
+): SchemaSummaryFormatVersion {
+	// Currently, version 2 is written which adds metadata blob to the summary.
+	return SchemaSummaryFormatVersion.v2;
+}
 
+/**
+ * Provides methods for summarizing and loading a schema repository.
+ */
+export class SchemaSummarizer
+	extends VersionedSummarizer<SchemaSummaryFormatVersion>
+	implements Summarizable
+{
 	private schemaIndexLastChangedSeq: number | undefined;
 
 	public constructor(
 		private readonly schema: MutableTreeStoredSchema,
 		collabWindow: CollabWindow,
 		private readonly codec: IJsonCodec<TreeStoredSchema>,
+		minVersionForCollab: MinimumVersionForCollab,
 	) {
+		super(
+			"Schema",
+			minVersionToSchemaSummaryFormatVersion(minVersionForCollab),
+			supportedVersions,
+			true /* supportPreVersioningFormat */,
+		);
 		this.schema.events.on("afterSchemaChange", () => {
 			// Invalidate the cache, as we need to regenerate the blob if the schema changes
 			// We are assuming that schema changes from remote ops are valid, as we are in a summarization context.
@@ -52,16 +95,15 @@ export class SchemaSummarizer implements Summarizable {
 		});
 	}
 
-	public summarize(props: {
+	protected summarizeInternal(props: {
 		stringify: SummaryElementStringifier;
 		fullTree?: boolean;
 		trackState?: boolean;
 		telemetryContext?: ITelemetryContext;
 		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext;
-	}): ISummaryTreeWithStats {
-		const incrementalSummaryContext = props.incrementalSummaryContext;
-		const builder = new SummaryTreeBuilder();
-		const fullTree = props.fullTree ?? false;
+		builder: SummaryTreeBuilder;
+	}): void {
+		const { builder, incrementalSummaryContext, stringify, fullTree = false } = props;
 		if (
 			!fullTree &&
 			incrementalSummaryContext !== undefined &&
@@ -74,13 +116,12 @@ export class SchemaSummarizer implements Summarizable {
 				`${incrementalSummaryContext.summaryPath}/${schemaStringKey}`,
 			);
 		} else {
-			const dataString = JSON.stringify(this.codec.encode(this.schema));
+			const dataString = stringify(this.codec.encode(this.schema));
 			builder.addBlob(schemaStringKey, dataString);
 		}
-		return builder.getSummaryTree();
 	}
 
-	public async load(
+	protected async loadInternal(
 		services: IChannelStorageService,
 		parse: SummaryElementParser,
 	): Promise<void> {