@fluidframework/tree 2.74.0-365691 → 2.74.0-370705

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

@@ -7,22 +7,20 @@ import { assert } from "@fluidframework/core-utils/internal";
 import { BTree } from "@tylerbu/sorted-btree-es6";
 
 import {
-	type DeltaDetachedNodeId,
 	type DeltaMark,
 	type FieldKindIdentifier,
 	Multiplicity,
 	type RevisionTag,
 	replaceAtomRevisions,
+	type DeltaFieldChanges,
 } from "../../core/index.js";
 
 import type {
-	FieldChangeDelta,
 	FieldChangeHandler,
 	NestedChangesIndices,
 	NodeChangeComposer,
 	NodeChangePruner,
 	NodeChangeRebaser,
-	RelevantRemovedRootsFromChild,
 	ToDelta,
 } from "./fieldChangeHandler.js";
 import { makeGenericChangeCodec } from "./genericFieldKindCodecs.js";
@@ -37,7 +35,7 @@ import { brandConst } from "../../util/index.js";
 export const genericChangeHandler: FieldChangeHandler<GenericChangeset> = {
 	rebaser: {
 		compose,
-		invert: (change: GenericChangeset): GenericChangeset => change,
+		invert: (change): GenericChangeset => change,
 		rebase: rebaseGenericChange,
 		prune: pruneGenericChange,
 		replaceRevisions,
@@ -49,7 +47,7 @@ export const genericChangeHandler: FieldChangeHandler<GenericChangeset> = {
 			return newGenericChangeset(Array.from(changes));
 		},
 	},
-	intoDelta: (change: GenericChangeset, deltaFromChild: ToDelta): FieldChangeDelta => {
+	intoDelta: (change: GenericChangeset, deltaFromChild: ToDelta): DeltaFieldChanges => {
 		let nodeIndex = 0;
 		const markList: DeltaMark[] = [];
 		for (const [index, nodeChange] of change.entries()) {
@@ -61,9 +59,8 @@ export const genericChangeHandler: FieldChangeHandler<GenericChangeset> = {
 			markList.push({ count: 1, fields: deltaFromChild(nodeChange) });
 			nodeIndex += 1;
 		}
-		return { local: markList };
+		return markList;
 	},
-	relevantRemovedRoots,
 	isEmpty: (change: GenericChangeset): boolean => change.length === 0,
 	getNestedChanges,
 	createEmpty: newGenericChangeset,
@@ -87,7 +84,7 @@ function compose(
 
 function getNestedChanges(change: GenericChangeset): NestedChangesIndices {
 	// For generic changeset, the indices in the input and output contexts are the same.
-	return change.toArray().map(([index, nodeChange]) => [nodeChange, index, index]);
+	return change.toArray().map(([index, nodeChange]) => [nodeChange, index]);
 }
 
 function rebaseGenericChange(
@@ -149,7 +146,7 @@ function pruneGenericChange(
 	for (const [index, node] of changeset.entries()) {
 		const prunedNode = pruneChild(node);
 		if (prunedNode !== undefined) {
-			pruned.set(index, node);
+			pruned.set(index, prunedNode);
 		}
 	}
 	return pruned;
@@ -169,7 +166,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(),
+	},
 );
 
 /**
@@ -185,12 +185,3 @@ export function convertGenericChange<TChange>(
 ): TChange {
 	return target.editor.buildChildChanges(changeset.entries());
 }
-
-function* relevantRemovedRoots(
-	change: GenericChangeset,
-	relevantRemovedRootsFromChild: RelevantRemovedRootsFromChild,
-): Iterable<DeltaDetachedNodeId> {
-	for (const nodeChange of change.values()) {
-		yield* relevantRemovedRootsFromChild(nodeChange);
-	}
-}

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

@@ -8,7 +8,7 @@ import { type ICodecFamily, type IJsonCodec, makeCodecFamily } from "../../codec
 import type { FieldChangeEncodingContext } from "./fieldChangeHandler.js";
 import { EncodedGenericChangeset } from "./genericFieldKindFormat.js";
 import { newGenericChangeset, type GenericChangeset } from "./genericFieldKindTypes.js";
-import { EncodedNodeChangeset } from "./modularChangeFormat.js";
+import { EncodedNodeChangeset } from "./modularChangeFormatV1.js";
 
 export function makeGenericChangeCodec(): ICodecFamily<
 	GenericChangeset,

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

@@ -8,13 +8,16 @@ export {
 	allowsTreeSchemaIdentifierSuperset,
 	allowsFieldSuperset,
 	allowsTreeSuperset,
+	allowsMultiplicitySuperset,
 } from "./comparison.js";
 export { isNeverField, isNeverTree } from "./isNeverTree.js";
 export {
-	addCrossFieldQuery,
-	type CrossFieldManager,
+	type InvertNodeManager,
+	type RebaseNodeManager,
+	type ComposeNodeManager,
 	type CrossFieldMap,
 	type CrossFieldQuerySet,
+	type DetachedNodeEntry,
 	CrossFieldTarget,
 	setInCrossFieldMap,
 } from "./crossFieldQueries.js";
@@ -24,11 +27,10 @@ export {
 	EncodedRevisionInfo,
 	EncodedModularChangeset,
 	EncodedNodeChangeset,
-} from "./modularChangeFormat.js";
+} from "./modularChangeFormatV1.js";
 export { FlexFieldKind, type FullSchemaPolicy } from "./fieldKind.js";
 export {
 	type FieldChangeHandler,
-	type FieldChangeDelta,
 	type FieldChangeRebaser,
 	type FieldEditor,
 	type NodeChangeComposer,
@@ -37,22 +39,26 @@ export {
 	type NodeChangePruner,
 	referenceFreeFieldChangeRebaser,
 	type RebaseRevisionMetadata,
-	type RelevantRemovedRootsFromChild,
 	type ToDelta,
 	NodeAttachState,
 	type FieldChangeEncodingContext,
 	type NestedChangesIndices,
 } from "./fieldChangeHandler.js";
-export type {
-	CrossFieldKey,
-	CrossFieldKeyRange,
-	FieldChange,
-	FieldChangeMap,
-	FieldChangeset,
-	HasFieldChanges,
-	ModularChangeset,
-	NodeExistsConstraint,
-	NodeId,
+export {
+	type CrossFieldKey,
+	type CrossFieldKeyRange,
+	type FieldChange,
+	type FieldChangeMap,
+	type FieldChangeset,
+	type HasFieldChanges,
+	type ModularChangeset,
+	type NodeExistsConstraint,
+	type NodeId,
+	type ChangeAtomIdBTree,
+	type RebaseVersion,
+	getFromChangeAtomIdMap,
+	setInChangeAtomIdMap,
+	rangeQueryChangeAtomIdMap,
 } from "./modularChangeTypes.js";
 export {
 	convertGenericChange,
@@ -69,6 +75,7 @@ export {
 	rebaseRevisionMetadataFromInfo,
 	intoDelta,
 	relevantRemovedRoots,
+	getBuildIds,
 	updateRefreshers,
 } from "./modularChangeFamily.js";
 export { makeModularChangeCodecFamily } from "./modularChangeCodecs.js";