@fluidframework/tree 2.74.0-365691 → 2.74.0

package/src/feature-libraries/forest-summary/incrementalSummaryBuilder.ts

@@ -4,10 +4,7 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
-import type {
-	IExperimentalIncrementalSummaryContext,
-	ISummaryTreeWithStats,
-} from "@fluidframework/runtime-definitions/internal";
+import type { IExperimentalIncrementalSummaryContext } from "@fluidframework/runtime-definitions/internal";
 import { SummaryTreeBuilder } from "@fluidframework/runtime-utils/internal";
 import {
 	brand,
@@ -30,21 +27,7 @@ import type { ISnapshotTree } from "@fluidframework/driver-definitions/internal"
 import { LoggingError } from "@fluidframework/telemetry-utils/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 const 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";
+import { summaryContentBlobKey } from "./summaryFormatV3.js";
 
 /**
  * State that tells whether a summary is currently being tracked.
@@ -206,7 +189,7 @@ function validateReadyToTrackSummary(
  *
  * An example summary tree with incremental summary:
  *     Forest
- *     ├── ForestTree
+ *     ├── contents
  *     ├── 0
  *     |   ├── contents
  *     |   ├── 1
@@ -219,7 +202,7 @@ function validateReadyToTrackSummary(
  *     |   ├── ...
  *     ├── 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".
+ *   - The inline portion of the top-level forest content is stored in a summary 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}.
  * - For each chunk, the structure of the summary tree is the same as the Forest. It contains the following:
@@ -227,16 +210,6 @@ function validateReadyToTrackSummary(
  *     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
@@ -299,11 +272,13 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 	 * contents of the chunks.
 	 * @param readAndParse - A function that reads and parses a blob from the storage service.
 	 */
-	public async load(
-		services: IChannelStorageService,
-		readAndParseChunk: <T extends JsonCompatible<IFluidHandle>>(id: string) => Promise<T>,
-	): Promise<void> {
-		const forestTree = services.getSnapshotTree?.();
+	public async load(args: {
+		services: IChannelStorageService;
+		readAndParseChunk: <T extends JsonCompatible<IFluidHandle>>(
+			chunkBlobPath: string,
+		) => Promise<T>;
+	}): Promise<void> {
+		const forestTree = args.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) {
@@ -320,13 +295,14 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 			// 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))) {
+				const chunkContentsPath = `${chunkSubTreePath}/${summaryContentBlobKey}`;
+				if (!(await args.services.contains(chunkContentsPath))) {
 					throw new LoggingError(
 						`SharedTree: Cannot find contents for incremental chunk ${chunkContentsPath}`,
 					);
 				}
-				const chunkContents = await readAndParseChunk<EncodedFieldBatch>(chunkContentsPath);
+				const chunkContents =
+					await args.readAndParseChunk<EncodedFieldBatch>(chunkContentsPath);
 				this.loadedChunksMap.set(chunkReferenceId, {
 					encodedContents: chunkContents,
 					summaryPath: chunkSubTreePath,
@@ -357,8 +333,9 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 		fullTree: boolean;
 		incrementalSummaryContext: IExperimentalIncrementalSummaryContext | undefined;
 		stringify: SummaryElementStringifier;
+		builder: SummaryTreeBuilder;
 	}): ForestIncrementalSummaryBehavior {
-		const { fullTree, incrementalSummaryContext, stringify } = args;
+		const { fullTree, incrementalSummaryContext, stringify, builder } = 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.
@@ -374,7 +351,7 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 			summarySequenceNumber: incrementalSummaryContext.summarySequenceNumber,
 			latestSummaryBasePath: incrementalSummaryContext.summaryPath,
 			chunkSummaryPath: [],
-			parentSummaryBuilder: new SummaryTreeBuilder(),
+			parentSummaryBuilder: builder,
 			fullTree,
 			stringify,
 		};
@@ -435,7 +412,7 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 				const chunkSummaryBuilder = new SummaryTreeBuilder();
 				this.trackedSummaryProperties.parentSummaryBuilder = chunkSummaryBuilder;
 				chunkSummaryBuilder.addBlob(
-					chunkContentsBlobKey,
+					summaryContentBlobKey,
 					this.trackedSummaryProperties.stringify(chunkEncoder(chunk)),
 				);
 
@@ -467,27 +444,33 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 	 * 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.
+	 * If this is undefined, the summary tree will only contain a summary blob for `forestSummaryRootContent`.
+	 * @param forestSummaryRootContent - The stringified ForestCodec output of top-level Forest content.
+	 * @param forestSummaryRootContentKey - The key to use for the blob containing `forestSummaryRootContent`.
+	 * @param builder - The summary tree builder to use to add the forest's contents. Note that if tracking an incremental
+	 * summary, this builder will be the same as the one tracked in `trackedSummaryProperties`.
 	 * @returns the Forest's summary tree.
 	 */
 	public completeSummary(args: {
 		incrementalSummaryContext: IExperimentalIncrementalSummaryContext | undefined;
-		forestSummaryContent: string;
-	}): ISummaryTreeWithStats {
-		const { incrementalSummaryContext, forestSummaryContent } = args;
+		forestSummaryRootContent: string;
+		forestSummaryRootContentKey: string;
+		builder: SummaryTreeBuilder;
+	}): void {
+		const {
+			incrementalSummaryContext,
+			forestSummaryRootContent,
+			forestSummaryRootContentKey,
+			builder,
+		} = args;
 		if (!this.enableIncrementalSummary || incrementalSummaryContext === undefined) {
-			const summaryBuilder = new SummaryTreeBuilder();
-			summaryBuilder.addBlob(forestSummaryContentKey, forestSummaryContent);
-			return summaryBuilder.getSummaryTree();
+			builder.addBlob(forestSummaryRootContentKey, forestSummaryRootContent);
+			return;
 		}
 
 		validateTrackingSummary(this.forestSummaryState, this.trackedSummaryProperties);
 
-		this.trackedSummaryProperties.parentSummaryBuilder.addBlob(
-			forestSummaryContentKey,
-			forestSummaryContent,
-		);
+		builder.addBlob(forestSummaryRootContentKey, forestSummaryRootContent);
 
 		// 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
@@ -516,9 +499,7 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 		}
 
 		this.forestSummaryState = ForestSummaryTrackingState.ReadyToTrack;
-		const summaryTree = this.trackedSummaryProperties.parentSummaryBuilder.getSummaryTree();
 		this.trackedSummaryProperties = undefined;
-		return summaryTree;
 	}
 
 	/**

package/src/feature-libraries/forest-summary/index.ts

@@ -3,6 +3,6 @@
  * Licensed under the MIT License.
  */
 
-export { forestSummaryKey, ForestSummarizer } from "./forestSummarizer.js";
+export { ForestSummarizer } from "./forestSummarizer.js";
 export { getCodecTreeForForestFormat } from "./codec.js";
-export { ForestFormatVersion } from "./format.js";
+export { ForestFormatVersion } from "./formatCommon.js";

package/src/feature-libraries/forest-summary/summaryFormatCommon.ts

@@ -0,0 +1,41 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * The key for the tree that contains the overall forest's summary tree.
+ * This tree is added by the parent of the forest summarizer.
+ * See {@link ForestIncrementalSummaryBuilder} for details on the summary structure.
+ */
+export const forestSummaryKey = "Forest";
+
+/**
+ * The versions for the forest summary.
+ */
+export enum ForestSummaryFormatVersion {
+	/**
+	 * 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,
+	/**
+	 * This version adds support for summaries with incremental chunks. Also, the ForestSummarizer's root contents are
+	 * stored in {@link summaryContentBlobKeyV3} instead of {@link summaryContentBlobKeyV1}.
+	 * This is not backward compatible with versions 1 and 2.
+	 */
+	v3 = 3,
+	/**
+	 * The latest version of the summary. Must be updated when a new version is added.
+	 */
+	vLatest = v3,
+}
+
+export const supportedForestSummaryFormatVersions = new Set<ForestSummaryFormatVersion>([
+	ForestSummaryFormatVersion.v1,
+	ForestSummaryFormatVersion.v2,
+	ForestSummaryFormatVersion.v3,
+]);

package/src/feature-libraries/forest-summary/summaryFormatV1ToV2.ts

@@ -0,0 +1,11 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * The entire contents of the ForestSummarizer's summary (ForestCodec's output) is added to a blob with this key.
+ * This was added in {@link ForestSummaryFormatVersion.v1 | version 1} and is used in
+ * {@link ForestSummaryFormatVersion.v1 | version 1} and {@link ForestSummaryFormatVersion.v2 | version 2}.
+ */
+export const summaryContentBlobKey = "ForestTree";

package/src/feature-libraries/forest-summary/summaryFormatV3.ts

@@ -0,0 +1,18 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * From {@link ForestSummaryFormatVersion.v3 | version 3} onwards, the inline portion of the top-level forest content
+ * is stored in a summary blob with this key.
+ * If the summary is not incremental, the content stored is the entire forest content.
+ * If the summary is incremental, the contents of the incremental chunks is stored separately:
+ * 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 and is stored in a blob with this key as
+ * well. The rest of the chunk contents  is stored in the summary tree under the summary tree node.
+ *
+ * @remarks
+ * See the summary format in {@link ForestIncrementalSummaryBuilder} for more details.
+ */
+export const summaryContentBlobKey = "contents";

package/src/feature-libraries/forest-summary/summaryTypes.ts

@@ -0,0 +1,41 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
+import {
+	getConfigForMinVersionForCollab,
+	lowestMinVersionForCollab,
+} from "@fluidframework/runtime-utils/internal";
+
+import { FluidClientVersion } from "../../codec/index.js";
+import { ForestSummaryFormatVersion } from "./summaryFormatCommon.js";
+import { summaryContentBlobKey as summaryContentBlobKeyV1ToV2 } from "./summaryFormatV1ToV2.js";
+import { summaryContentBlobKey as summaryContentBlobKeyV3 } from "./summaryFormatV3.js";
+
+/**
+ * Returns the summary format version to use as per the given minimum version for collab.
+ */
+export function minVersionToForestSummaryFormatVersion(
+	version: MinimumVersionForCollab,
+): ForestSummaryFormatVersion {
+	return getConfigForMinVersionForCollab(version, {
+		[lowestMinVersionForCollab]: ForestSummaryFormatVersion.v2,
+		[FluidClientVersion.v2_74]: ForestSummaryFormatVersion.v3,
+	});
+}
+
+/**
+ * Gets the key for the blob containing the forest summary root content based on the summary format version.
+ * @param summaryFormatVersion - The version of the forest summary format.
+ * @returns The key for the forest summary root content blob.
+ */
+export function getForestRootSummaryContentKey(
+	summaryFormatVersion: ForestSummaryFormatVersion | undefined,
+): string {
+	return summaryFormatVersion === undefined ||
+		summaryFormatVersion < ForestSummaryFormatVersion.v3
+		? summaryContentBlobKeyV1ToV2
+		: summaryContentBlobKeyV3;
+}

package/src/feature-libraries/index.ts

@@ -12,7 +12,7 @@ export { allowsValue, assertAllowedValue, isTreeValue } from "./valueUtilities.j
 export {
 	ForestSummarizer,
 	getCodecTreeForForestFormat,
-	type ForestFormatVersion,
+	ForestFormatVersion,
 } from "./forest-summary/index.js";
 export {
 	cursorForMapTreeField,

package/src/feature-libraries/modular-schema/comparison.ts

@@ -3,11 +3,12 @@
  * Licensed under the MIT License.
  */
 
-import { assert, fail } from "@fluidframework/core-utils/internal";
+import { assert, fail, unreachableCase } from "@fluidframework/core-utils/internal";
 
 import {
 	LeafNodeStoredSchema,
 	MapNodeStoredSchema,
+	Multiplicity,
 	ObjectNodeStoredSchema,
 	type TreeFieldStoredSchema,
 	type TreeNodeStoredSchema,
@@ -19,7 +20,7 @@ import {
 import { compareSets } from "../../util/index.js";
 
 import type { FullSchemaPolicy } from "./fieldKind.js";
-import { isNeverTree } from "./isNeverTree.js";
+import { isNeverField, isNeverTree } from "./isNeverTree.js";
 
 /**
  * Returns true iff `superset` is a superset of `original`.
@@ -125,16 +126,47 @@ export function allowsValueSuperset(
  * Returns true iff `superset` is a superset of `original`.
  *
  * This does not require a strict (aka proper) superset: equivalent schema will return true.
+ *
+ * @param monotonicOnly - If true, only allow changes of field kinds which are explicitly listed in {@link FieldKindOptions.allowMonotonicUpgradeFrom}.
+ * This prevents this function from considering two different schema as equivalent, preventing upgrades which would allow their inverse.
+ * This prevents infinite upgrade loops where two clients could keep upgrading between two schema.
+ *
+ * @remarks
+ * True if a client should be able to {@link TreeView.upgradeSchema} from a field schema using this field kind and `originalTypes` to `superset`.
+ *
+ * @privateRemarks
+ * See also {@link FieldKindOptions.allowMonotonicUpgradeFrom} for constraints on the implementation.
  */
 export function allowsFieldSuperset(
 	policy: FullSchemaPolicy,
 	originalData: TreeStoredSchema,
 	original: TreeFieldStoredSchema,
 	superset: TreeFieldStoredSchema,
+	monotonicOnly: boolean = true,
 ): boolean {
-	return (
-		policy.fieldKinds.get(original.kind) ?? fail(0xb1b /* missing kind */)
-	).allowsFieldSuperset(policy, originalData, original.types, superset);
+	if (!monotonicOnly) {
+		if (isNeverField(policy, originalData, original)) {
+			return true;
+		}
+	}
+
+	if (!allowsTreeSchemaIdentifierSuperset(original.types, superset.types)) {
+		return false;
+	}
+
+	if (original.kind === superset.kind) {
+		return true;
+	}
+
+	const supersetKind = policy.fieldKinds.get(superset.kind) ?? fail(0xb1b /* missing kind */);
+
+	if (monotonicOnly) {
+		return supersetKind.options.allowMonotonicUpgradeFrom.has(original.kind);
+	} else {
+		const originalKind =
+			policy.fieldKinds.get(original.kind) ?? fail(0xcab /* missing kind */);
+		return allowsMultiplicitySuperset(originalKind.multiplicity, supersetKind.multiplicity);
+	}
 }
 
 /**
@@ -192,3 +224,30 @@ export function allowsRepoSuperset(
 	// Therefore, we do not need to check them.
 	return true;
 }
+
+/**
+ * Returns true iff `superset` is a superset of `original`.
+ *
+ * This does not require a strict (aka proper) superset: equivalent schema will return true.
+ */
+export function allowsMultiplicitySuperset(
+	original: Multiplicity,
+	superset: Multiplicity,
+): boolean {
+	if (original === superset) {
+		return true;
+	}
+
+	switch (superset) {
+		case Multiplicity.Forbidden:
+			return false;
+		case Multiplicity.Optional:
+			return original === Multiplicity.Single || original === Multiplicity.Forbidden;
+		case Multiplicity.Single:
+			return false;
+		case Multiplicity.Sequence:
+			return true;
+		default:
+			return unreachableCase(superset);
+	}
+}

package/src/feature-libraries/modular-schema/fieldKind.ts

@@ -8,14 +8,10 @@ import type {
 	FieldKindData,
 	Multiplicity,
 	SchemaPolicy,
-	TreeFieldStoredSchema,
-	TreeStoredSchema,
-	TreeTypeSet,
 } from "../../core/index.js";
 import type { MakeNominal } from "../../util/index.js";
 
 import type { FieldChangeHandler, FieldEditor } from "./fieldChangeHandler.js";
-import { isNeverField } from "./isNeverTree.js";
 
 /**
  * Functionality for FieldKinds that is stable,
@@ -54,38 +50,10 @@ export class FlexFieldKind<
 		public readonly multiplicity: TMultiplicity,
 		// TODO: stronger typing
 		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		private readonly options: FieldKindOptions<FieldChangeHandler<any, TEditor>>,
+		public readonly options: FieldKindOptions<FieldChangeHandler<any, TEditor>>,
 	) {
 		this.changeHandler = options.changeHandler;
 	}
-
-	/**
-	 * Returns true if and only if `superset` permits a (non-strict) superset of the subtrees
-	 * allowed by field made from `this` and `originalTypes`.
-	 *
-	 * TODO: clarify the relationship between this and FieldKindData, and issues with cyclic schema upgrades.
-	 */
-	public allowsFieldSuperset(
-		policy: SchemaPolicy,
-		originalData: TreeStoredSchema,
-		originalTypes: TreeTypeSet,
-		superset: TreeFieldStoredSchema,
-	): boolean {
-		if (
-			isNeverField(policy, originalData, {
-				kind: this.identifier,
-				types: originalTypes,
-				// Metadata is not used for this check.
-				persistedMetadata: undefined,
-			})
-		) {
-			return true;
-		}
-		if (isNeverField(policy, originalData, superset)) {
-			return false;
-		}
-		return this.options.allowsTreeSupersetOf(originalTypes, superset);
-	}
 }
 
 /**
@@ -101,15 +69,31 @@ export interface FieldKindOptions<TFieldChangeHandler> {
 	readonly changeHandler: TFieldChangeHandler;
 
 	/**
-	 * Returns true if and only if `superset` permits a (non-strict) superset of the subtrees
-	 * allowed by field made from `this` and `originalTypes`.
+	 * The set of field kinds which can be migrated to this one by a {@link TreeView.upgradeSchema}.
 	 * @remarks
-	 * Used by {@link FlexFieldKind.allowsFieldSuperset}, which handles the `never` cases before calling this.
+	 * Must return false if such an upgrade could violate any invariants of `superset` for any document which is compatible with `this` + `originalTypes`.
+	 *
+	 * Unlike the rest of the FieldKind API, this may change over time without changing the FieldKind identifier without causing decoherence between clients.
+	 * It has a different set of constraints:
+	 *
+	 * - This must never allow an upgrade that could violate any invariants of any field kind required by any version of client for any document content (that was not already invalid).
+	 * This prevents a schema upgrade from causing a document to become out of schema.
+	 * - The set of implementations of this function across all fields kinds and all client versions must never permit a cycle.
+	 * This prevents applications which simply do an upgrade when possible from being able to have two clients both upgrade where one is actually a down grade and they cause an infinite loop of schema upgrade edits.
+	 *
+	 * To help maintain these invariants, any cases where the set of allowed contents does not increase (but is the same so the upgrade is still in schema) must be considered carefully.
+	 * For example, a migration from `Sequence([])` to `Optional([])`  can be problematic despite being permissible
+	 * as it does not change what content is allowed (the field must be empty either way as no types are allowed in it).
+	 * Such cases, if allowed, could lead to cycles if their inverse is also allowed.
+	 * These cases, if supported, can be removed, but if doing so must be documented and still considered when avoiding cycles.
+	 *
+	 * Used by {@link allowsFieldSuperset}.
+	 *
+	 * TODO: this design is rather limiting, and there is some planned work in this area:
+	 * - Provide schema upgrade schema not reliant on this to ensure monotonicity of schema upgrades like AB#7482.
+	 * - This monotonic upgrade scheme can remain useful for features like AB#53604 so it should be kept and refined.
 	 */
-	readonly allowsTreeSupersetOf: (
-		originalTypes: TreeTypeSet,
-		superset: TreeFieldStoredSchema,
-	) => boolean;
+	readonly allowMonotonicUpgradeFrom: ReadonlySet<FieldKindIdentifier>;
 
 	/**
 	 * Kinds (in addition to this) whose edits can be processed by changeHandler.

package/src/feature-libraries/modular-schema/genericFieldKind.ts

@@ -169,7 +169,10 @@ function replaceRevisions(
 export const genericFieldKind: FlexFieldKind = new FlexFieldKind(
 	brandConst("ModularEditBuilder.Generic")<FieldKindIdentifier>(),
 	Multiplicity.Sequence,
-	{ changeHandler: genericChangeHandler, allowsTreeSupersetOf: (types, other) => false },
+	{
+		changeHandler: genericChangeHandler,
+		allowMonotonicUpgradeFrom: new Set(),
+	},
 );
 
 /**

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

@@ -8,6 +8,7 @@ export {
 	allowsTreeSchemaIdentifierSuperset,
 	allowsFieldSuperset,
 	allowsTreeSuperset,
+	allowsMultiplicitySuperset,
 } from "./comparison.js";
 export { isNeverField, isNeverTree } from "./isNeverTree.js";
 export {

package/src/feature-libraries/schema-edits/schemaChangeCodecs.ts

@@ -20,7 +20,6 @@ import { getCodecTreeForSchemaFormat, makeSchemaCodec } from "../schema-index/in
 import { EncodedSchemaChange } from "./schemaChangeFormat.js";
 import type { SchemaChange } from "./schemaChangeTypes.js";
 import { SchemaFormatVersion } from "../../core/index.js";
-import { brand } from "../../util/index.js";
 
 /**
  * Create a family of schema change codecs.
@@ -31,8 +30,8 @@ export function makeSchemaChangeCodecs(
 	options: CodecWriteOptions,
 ): ICodecFamily<SchemaChange> {
 	return makeCodecFamily([
-		[SchemaFormatVersion.v1, makeSchemaChangeCodecV1(options, brand(SchemaFormatVersion.v1))],
-		[SchemaFormatVersion.v2, makeSchemaChangeCodecV1(options, brand(SchemaFormatVersion.v2))],
+		[SchemaFormatVersion.v1, makeSchemaChangeCodecV1(options, SchemaFormatVersion.v1)],
+		[SchemaFormatVersion.v2, makeSchemaChangeCodecV1(options, SchemaFormatVersion.v2)],
 	]);
 }
 

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

@@ -30,7 +30,7 @@ import {
 	encodeFieldSchemaV2,
 	storedSchemaDecodeDispatcher,
 } from "../../core/index.js";
-import { brand, type JsonCompatible } from "../../util/index.js";
+import { brand, unbrand, type JsonCompatible } from "../../util/index.js";
 
 import { Format as FormatV1 } from "./formatV1.js";
 import { Format as FormatV2 } from "./formatV2.js";
@@ -44,12 +44,10 @@ import type { MinimumVersionForCollab } from "@fluidframework/runtime-definition
 export function clientVersionToSchemaVersion(
 	clientVersion: MinimumVersionForCollab,
 ): SchemaFormatVersion {
-	return brand(
-		getConfigForMinVersionForCollab(clientVersion, {
-			[lowestMinVersionForCollab]: SchemaFormatVersion.v1,
-			[FluidClientVersion.v2_43]: SchemaFormatVersion.v2,
-		}),
-	);
+	return getConfigForMinVersionForCollab(clientVersion, {
+		[lowestMinVersionForCollab]: SchemaFormatVersion.v1,
+		[FluidClientVersion.v2_43]: SchemaFormatVersion.v2,
+	});
 }
 
 export function getCodecTreeForSchemaFormat(
@@ -101,9 +99,9 @@ export function encodeRepo(
 	version: SchemaFormatVersion,
 ): JsonCompatible {
 	switch (version) {
-		case SchemaFormatVersion.v1:
+		case unbrand(SchemaFormatVersion.v1):
 			return encodeRepoV1(repo) as JsonCompatible;
-		case SchemaFormatVersion.v2:
+		case unbrand(SchemaFormatVersion.v2):
 			return encodeRepoV2(repo) as JsonCompatible;
 		default:
 			unreachableCase(version);