@fluidframework/tree 2.82.0 → 2.90.0-378676

package/src/codec/versioned/codec.ts

@@ -3,11 +3,11 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, debugAssert } from "@fluidframework/core-utils/internal";
 import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
 import {
 	getConfigForMinVersionForCollabIterable,
-	type ConfigMapEntry,
+	lowestMinVersionForCollab,
 	type MinimumMinorSemanticVersion,
 	type SemanticVersion,
 } from "@fluidframework/runtime-utils/internal";
@@ -27,9 +27,7 @@ import {
 	withSchemaValidation,
 	type FormatVersion,
 	type CodecWriteOptions,
-	type IMultiFormatCodec,
 	type CodecName,
-	ensureBinaryEncoding,
 	type CodecTree,
 } from "../codec.js";
 
@@ -151,7 +149,7 @@ export function makeVersionDispatchingCodec<TDecoded, TContext>(
 	family: ICodecFamily<TDecoded, TContext>,
 	options: ICodecOptions & { writeVersion: FormatVersion },
 ): IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {
-	const writeCodec = family.resolve(options.writeVersion).json;
+	const writeCodec = family.resolve(options.writeVersion);
 	const supportedVersions = new Set(family.getSupportedFormats());
 	return makeVersionedCodec(supportedVersions, options, {
 		encode(data, context): Versioned {
@@ -159,7 +157,7 @@ export function makeVersionDispatchingCodec<TDecoded, TContext>(
 		},
 		decode(data: Versioned, context) {
 			const codec = family.resolve(data.version);
-			return codec.json.decode(data, context);
+			return codec.decode(data, context);
 		},
 	});
 }
@@ -170,10 +168,9 @@ export function makeVersionDispatchingCodec<TDecoded, TContext>(
  * The codec should not perform its own schema validation.
  * The schema validation gets added when normalizing to {@link NormalizedCodecVersion}.
  */
-export type CodecAndSchema<TDecoded, TContext = void> = { readonly schema: TSchema } & (
-	| IMultiFormatCodec<TDecoded, VersionedJson, JsonCompatibleReadOnly, TContext>
-	| IJsonCodec<TDecoded, VersionedJson, JsonCompatibleReadOnly, TContext>
-);
+export type CodecAndSchema<TDecoded, TContext = void> = {
+	readonly schema: TSchema;
+} & IJsonCodec<TDecoded, VersionedJson, JsonCompatibleReadOnly, TContext>;
 
 /**
  * A codec alongside its format version and schema.
@@ -182,6 +179,14 @@ export interface CodecVersionBase<
 	T = unknown,
 	TFormatVersion extends FormatVersion = FormatVersion,
 > {
+	/**
+	 * When `undefined` the codec will never be selected as a write version except via override.
+	 * @remarks
+	 * This format will be used for decode if data in it needs to be decoded, regardless of `minVersionForCollab`.
+	 * `undefined` should be used for unstable codec versions (with string FormatVersions),
+	 * as well as previously stabilized formats that are discontinued (meaning we always prefer to use some other format for encoding).
+	 */
+	readonly minVersionForCollab: MinimumVersionForCollab | undefined;
 	readonly formatVersion: TFormatVersion;
 	readonly codec: T;
 }
@@ -228,11 +233,8 @@ export interface NormalizedCodecVersion<
  * @remarks
  * Produced by {@link ClientVersionDispatchingCodecBuilder.applyOptions}.
  */
-export interface EvaluatedCodecVersion<
-	TDecoded,
-	TContext,
-	TFormatVersion extends FormatVersion,
-> extends CodecVersionBase<
+interface EvaluatedCodecVersion<TDecoded, TContext, TFormatVersion extends FormatVersion>
+	extends CodecVersionBase<
 		IJsonCodec<TDecoded, VersionedJson, JsonCompatibleReadOnly, TContext>,
 		TFormatVersion
 	> {}
@@ -258,17 +260,16 @@ function normalizeCodecVersion<
 		options: TBuildOptions,
 	): IJsonCodec<TDecoded, VersionedJson, JsonCompatibleReadOnly, TContext> => {
 		const built = codecBuilder(options);
-		// We currently don't expose or use binary formats, but someday we might.
-		const multiFormat = ensureBinaryEncoding<TDecoded, TContext, VersionedJson>(built);
 		return makeVersionedValidatedCodec(
 			options,
 			new Set([codecVersion.formatVersion]),
 			built.schema,
-			multiFormat.json,
+			built,
 		);
 	};
 
 	return {
+		minVersionForCollab: codecVersion.minVersionForCollab,
 		formatVersion: codecVersion.formatVersion,
 		codec,
 	};
@@ -287,13 +288,20 @@ export class ClientVersionDispatchingCodecBuilder<
 	TFormatVersion extends FormatVersion,
 	TBuildOptions extends CodecWriteOptions,
 > {
-	public readonly registry: ReadonlyMap<
-		MinimumVersionForCollab,
-		NormalizedCodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions>
-	>;
+	public readonly registry: readonly NormalizedCodecVersion<
+		TDecoded,
+		TContext,
+		TFormatVersion,
+		TBuildOptions
+	>[];
 
 	/**
 	 * Use {@link ClientVersionDispatchingCodecBuilder.build} to create an instance of this class.
+	 * @remarks
+	 * Inputs to this are assumed to be constants in the code controlled by the developers of this package,
+	 * and constructed at least once during tests.
+	 * Because of this, the validation of these inputs done with debugAssert should be sufficient,
+	 * and using debugAssert avoids bloating the bundle size for production users.
 	 */
 	private constructor(
 		/**
@@ -303,9 +311,7 @@ export class ClientVersionDispatchingCodecBuilder<
 		/**
 		 * The registry of codecs which this builder can use to encode and decode data.
 		 */
-		inputRegistry: ConfigMapEntry<
-			CodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions>
-		>,
+		inputRegistry: readonly CodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions>[],
 	) {
 		type Normalized = NormalizedCodecVersion<
 			TDecoded,
@@ -313,18 +319,41 @@ export class ClientVersionDispatchingCodecBuilder<
 			TFormatVersion,
 			TBuildOptions
 		>;
-		const normalizedRegistry = new Map<MinimumVersionForCollab, Normalized>();
-
-		for (const [minVersionForCollab, codec] of Object.entries(inputRegistry) as Iterable<
-			[
-				MinimumVersionForCollab,
-				CodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions>,
-			]
-		>) {
+		const normalizedRegistry: Normalized[] = [];
+		const formats: Set<FormatVersion> = new Set();
+		const versions: Set<string | undefined> = new Set();
+
+		for (const codec of inputRegistry) {
+			debugAssert(
+				() =>
+					!formats.has(codec.formatVersion) ||
+					`duplicate codec format ${name} ${codec.formatVersion}`,
+			);
+			debugAssert(
+				() =>
+					codec.minVersionForCollab === undefined ||
+					typeof codec.formatVersion !== "string" ||
+					`unstable format ${JSON.stringify(codec.formatVersion)} (string formats) must not have a minVersionForCollab in ${name}`,
+			);
+			formats.add(codec.formatVersion);
 			const normalizedCodec = normalizeCodecVersion(codec);
-			normalizedRegistry.set(minVersionForCollab, normalizedCodec);
+			normalizedRegistry.push(normalizedCodec);
+			if (codec.minVersionForCollab !== undefined) {
+				debugAssert(
+					() =>
+						!versions.has(codec.minVersionForCollab) ||
+						`Codec ${name} has multiple entries for version ${JSON.stringify(codec.minVersionForCollab)}`,
+				);
+				versions.add(codec.minVersionForCollab);
+			}
 		}
 
+		debugAssert(
+			() =>
+				versions.has(lowestMinVersionForCollab) ||
+				`Codec ${name} is missing entry for lowestMinVersionForCollab`,
+		);
+
 		this.registry = normalizedRegistry;
 	}
 
@@ -336,18 +365,12 @@ export class ClientVersionDispatchingCodecBuilder<
 	 */
 	public applyOptions(
 		options: TBuildOptions,
-	): [MinimumVersionForCollab, EvaluatedCodecVersion<TDecoded, TContext, TFormatVersion>][] {
-		return Array.from(
-			this.registry,
-			([version, codec]) =>
-				[
-					version,
-					{
-						formatVersion: codec.formatVersion,
-						codec: codec.codec(options),
-					},
-				] as const,
-		);
+	): EvaluatedCodecVersion<TDecoded, TContext, TFormatVersion>[] {
+		return this.registry.map((codec) => ({
+			minVersionForCollab: codec.minVersionForCollab,
+			formatVersion: codec.formatVersion,
+			codec: codec.codec(options),
+		}));
 	}
 
 	/**
@@ -361,7 +384,7 @@ export class ClientVersionDispatchingCodecBuilder<
 		const fromFormatVersion = new Map<
 			FormatVersion,
 			EvaluatedCodecVersion<TDecoded, TContext, TFormatVersion>
-		>(applied.map(([_version, codec]) => [codec.formatVersion, codec]));
+		>(applied.map((codec) => [codec.formatVersion, codec]));
 		return {
 			encode: (data: TDecoded, context: TContext): JsonCompatibleReadOnly => {
 				return writeVersion.codec.encode(data, context);
@@ -382,7 +405,7 @@ The client which encoded this data likely specified an "minVersionForCollab" val
 
 	public getCodecTree(clientVersion: MinimumVersionForCollab): CodecTree {
 		// TODO: add support for children codecs.
-		const selected = getConfigForMinVersionForCollabIterable(clientVersion, this.registry);
+		const selected = getWriteVersionNoOverrides(this.registry, clientVersion);
 		return {
 			name: this.name,
 			version: selected.formatVersion,
@@ -400,7 +423,7 @@ The client which encoded this data likely specified an "minVersionForCollab" val
 	public static build<
 		Name extends CodecName,
 		Entry extends CodecVersion<unknown, unknown, FormatVersion, never>,
-	>(name: Name, inputRegistry: ConfigMapEntry<Entry>) {
+	>(name: Name, inputRegistry: readonly Entry[]) {
 		type TDecoded2 =
 			Entry extends CodecVersion<infer D, unknown, FormatVersion, never> ? D : never;
 		type TContext2 =
@@ -409,18 +432,24 @@ The client which encoded this data likely specified an "minVersionForCollab" val
 			Entry extends CodecVersion<unknown, unknown, infer F, never> ? F : never;
 		type TBuildOptions2 =
 			Entry extends CodecVersion<unknown, unknown, FormatVersion, infer B> ? B : never;
-		const builder = new ClientVersionDispatchingCodecBuilder(
-			name,
-			inputRegistry as ConfigMapEntry<unknown> as ConfigMapEntry<
-				CodecVersion<
-					TDecoded2,
-					// If it does not matter what context is provided, undefined is fine, so allow it to be omitted.
-					unknown extends TContext2 ? void : TContext2,
-					TFormatVersion2,
-					TBuildOptions2
-				>
-			>,
-		);
+
+		type CodecFinal = CodecVersion<
+			TDecoded2,
+			// If it does not matter what context is provided, undefined is fine, so allow it to be omitted.
+			unknown extends TContext2 ? void : TContext2,
+			TFormatVersion2,
+			TBuildOptions2
+		>;
+
+		const input = inputRegistry as readonly unknown[] as readonly CodecFinal[];
+
+		const builder = new ClientVersionDispatchingCodecBuilder<
+			Name,
+			TDecoded2,
+			unknown extends TContext2 ? void : TContext2,
+			TFormatVersion2,
+			TBuildOptions2
+		>(name, input);
 		return builder;
 	}
 }
@@ -433,39 +462,51 @@ The client which encoded this data likely specified an "minVersionForCollab" val
 function getWriteVersion<T extends CodecVersionBase>(
 	name: CodecName,
 	options: CodecWriteOptions,
-	versions: readonly [MinimumMinorSemanticVersion | MinimumVersionForCollab, T][],
+	versions: readonly T[],
 ): T {
 	if (options.writeVersionOverrides?.has(name) === true) {
 		const selectedFormatVersion = options.writeVersionOverrides.get(name);
-		const selected = versions.find(
-			([_v, codec]) => codec.formatVersion === selectedFormatVersion,
-		);
+		const selected = versions.find((codec) => codec.formatVersion === selectedFormatVersion);
 		if (selected === undefined) {
 			throw new UsageError(
-				`Codec "${name}" does not support requested format version ${selectedFormatVersion}. Supported versions are: ${versionList(versions)}.`,
+				`Codec "${name}" does not support requested format version ${JSON.stringify(selectedFormatVersion)}. Supported versions are: ${versionList(versions)}.`,
 			);
 		} else if (options.allowPossiblyIncompatibleWriteVersionOverrides !== true) {
-			const selectedMinVersionForCollab = selected[0];
-			// Currently all versions must specify a minVersionForCollab, so undefined is not expected here.
-			// TODO: It should be possible to have a version which would never be automatically selected for write (and thus does not have or need a minVersionForCollab), but can be selected via override.
-			// Use-cases for this include experimental versions not yet stable, and discontinued or intermediate versions which are mainly being kept for read compatibility but still support writing (perhaps for round-trip testing).
-			// For now, this check should never pass, and there is no way to create such a version yet.
+			const selectedMinVersionForCollab = selected.minVersionForCollab;
 			if (selectedMinVersionForCollab === undefined) {
 				throw new UsageError(
-					`Codec "${name}" does not support requested format version ${selectedFormatVersion} because it does not specify a minVersionForCollab. Use "allowPossiblyIncompatibleWriteVersionOverrides" to suppress this error if appropriate.`,
+					`Codec "${name}" does not support requested format version ${JSON.stringify(selectedFormatVersion)} because it has minVersionForCollab undefined. Use "allowPossiblyIncompatibleWriteVersionOverrides" to suppress this error if appropriate.`,
 				);
 			} else if (gt(selectedMinVersionForCollab, options.minVersionForCollab)) {
 				throw new UsageError(
-					`Codec "${name}" does not support requested format version ${selectedFormatVersion} because it is only compatible back to client version ${selectedMinVersionForCollab} and the requested oldest compatible client was ${options.minVersionForCollab}. Use "allowPossiblyIncompatibleWriteVersionOverrides" to suppress this error if appropriate.`,
+					`Codec "${name}" does not support requested format version ${JSON.stringify(selectedFormatVersion)} because it is only compatible back to client version ${selectedMinVersionForCollab} and the requested oldest compatible client was ${options.minVersionForCollab}. Use "allowPossiblyIncompatibleWriteVersionOverrides" to suppress this error if appropriate.`,
 				);
 			}
 		}
 
-		return selected[1];
+		return selected;
 	}
+
+	return getWriteVersionNoOverrides(versions, options.minVersionForCollab);
+}
+
+/**
+ * Selects which format should be used when writing data, without consider overrides.
+ */
+function getWriteVersionNoOverrides<T extends CodecVersionBase>(
+	versions: readonly T[],
+	minVersionForCollab: MinimumVersionForCollab,
+): T {
+	const stableVersions: [MinimumMinorSemanticVersion | MinimumVersionForCollab, T][] = [];
+	for (const version of versions) {
+		if (version.minVersionForCollab !== undefined) {
+			stableVersions.push([version.minVersionForCollab, version]);
+		}
+	}
+
 	const result: T = getConfigForMinVersionForCollabIterable(
-		options.minVersionForCollab,
-		versions,
+		minVersionForCollab,
+		stableVersions,
 	);
 	return result;
 }
@@ -473,11 +514,6 @@ function getWriteVersion<T extends CodecVersionBase>(
 /**
  * Formats a list of versions for use in UsageErrors.
  */
-function versionList(
-	versions: readonly [
-		MinimumMinorSemanticVersion | MinimumVersionForCollab,
-		CodecVersionBase,
-	][],
-): string {
-	return `${Array.from(versions, ([_v, codec]) => codec.formatVersion).join(", ")}`;
+function versionList(versions: readonly CodecVersionBase[]): string {
+	return JSON.stringify(Array.from(versions, (codec) => codec.formatVersion));
 }

package/src/core/change-family/changeFamily.ts

@@ -14,12 +14,17 @@ export interface ChangeFamily<TEditor extends ChangeFamilyEditor, TChange> {
 	buildEditor(
 		mintRevisionTag: () => RevisionTag,
 		changeReceiver: (change: TaggedChange<TChange>) => void,
+		options?: EditorOptions,
 	): TEditor;
 
 	readonly rebaser: ChangeRebaser<TChange>;
 	readonly codecs: ICodecFamily<TChange, ChangeEncodingContext>;
 }
 
+export interface EditorOptions {
+	readonly enableDetachedRootEditing: boolean; // default is false,
+}
+
 export interface ChangeEncodingContext {
 	readonly originatorId: SessionId;
 	readonly revision: RevisionTag | undefined;

package/src/core/change-family/index.ts

@@ -8,5 +8,6 @@ export type {
 	ChangeFamilyEditor,
 	ChangeEncodingContext,
 	ChangeFamilyCodec,
+	EditorOptions,
 } from "./changeFamily.js";
 export { EditBuilder } from "./editBuilder.js";

package/src/core/index.ts

@@ -74,7 +74,7 @@ export {
 	type AnchorNode,
 	anchorSlot,
 	type UpPathDefault,
-	isDetachedUpPath,
+	isDetachedUpPathRoot,
 	inCursorField,
 	inCursorNode,
 	type AnchorEvents,
@@ -87,6 +87,7 @@ export {
 	type DetachedFieldIndexCheckpoint,
 	type ForestRootId,
 	getDetachedFieldContainingPath,
+	getDetachedFieldContainingFieldPath,
 	aboveRootPlaceholder,
 	type DeltaRoot,
 	type DeltaMark,
@@ -162,6 +163,7 @@ export {
 	type ChangeEncodingContext,
 	type ChangeFamilyEditor,
 	EditBuilder,
+	type EditorOptions,
 } from "./change-family/index.js";
 
 export {
@@ -212,6 +214,7 @@ export {
 	isAncestor,
 	type ChangeAtomIdRangeMap,
 	newChangeAtomIdRangeMap,
+	newChangeAtomIdTransform,
 	comparePartialRevisions,
 	compareChangesetLocalIds,
 	comparePartialChangesetLocalIds,

package/src/core/rebase/changeRebaser.ts

@@ -161,7 +161,12 @@ export function mapTaggedChange<TIn, TOut>(
 export type RevisionIndexer = (tag: RevisionTag) => number | undefined;
 
 export interface RevisionMetadataSource {
-	readonly getIndex: RevisionIndexer;
+	/**
+	 * @returns a positive number if tag2 is a later revision than tag1 or a negative number if tag2 is an earlier revision.
+	 * Returns zero is the order cannot be determined, which happens if both revisions are older
+	 * than the set of revisions handled by this metadata source.
+	 */
+	readonly compareRevisions: (tag1: RevisionTag, tag2: RevisionTag) => number;
 	readonly tryGetInfo: (tag: RevisionTag | undefined) => RevisionInfo | undefined;
 	readonly hasRollback: (tag: RevisionTag) => boolean;
 }

package/src/core/rebase/index.ts

@@ -31,6 +31,7 @@ export {
 	subtractChangeAtomIds,
 	type ChangeAtomIdRangeMap,
 	newChangeAtomIdRangeMap,
+	newChangeAtomIdTransform,
 	comparePartialRevisions,
 	compareChangesetLocalIds,
 	comparePartialChangesetLocalIds,

package/src/core/rebase/types.ts

@@ -296,6 +296,10 @@ export function newChangeAtomIdRangeMap<V>(
 	return new RangeMap(offsetChangeAtomId, subtractChangeAtomIds, offsetValue);
 }
 
+export function newChangeAtomIdTransform(): ChangeAtomIdRangeMap<ChangeAtomId> {
+	return new RangeMap(offsetChangeAtomId, subtractChangeAtomIds, offsetChangeAtomId);
+}
+
 export function subtractChangeAtomIds(a: ChangeAtomId, b: ChangeAtomId): number {
 	const cmp = comparePartialRevisions(a.revision, b.revision);
 	if (cmp !== 0) {

package/src/core/rebase/utils.ts

@@ -327,7 +327,9 @@ export function rebaseBranch<TChange>(
 			},
 		},
 		"sourceChange",
-		() => changeRebaser.compose(editsToCompose),
+		() => {
+			return changeRebaser.compose(editsToCompose);
+		},
 	);
 }
 
@@ -375,23 +377,45 @@ export function rebaseChange<TChange>(
 export function revisionMetadataSourceFromInfo(
 	revInfos: readonly RevisionInfo[],
 ): RevisionMetadataSource {
-	const getIndex = (revision: RevisionTag): number | undefined => {
-		const index = revInfos.findIndex((revInfo) => revInfo.revision === revision);
-		return index >= 0 ? index : undefined;
+	const compareRevisions = (revision1: RevisionTag, revision2: RevisionTag): number => {
+		const index1 = getIndex(revision1);
+		const index2 = getIndex(revision2);
+
+		if (index1 !== undefined) {
+			return index2 === undefined ? -1 : index2 - index1;
+		}
+
+		return index2 === undefined ? 0 : 1;
 	};
+
 	const tryGetInfo = (revision: RevisionTag | undefined): RevisionInfo | undefined => {
 		if (revision === undefined) {
 			return undefined;
 		}
-		const index = getIndex(revision);
-		return index === undefined ? undefined : revInfos[index];
+		return revInfos.find((info) => info.revision === revision);
 	};
 
 	const hasRollback = (revision: RevisionTag): boolean => {
 		return revInfos.some((info) => info.rollbackOf === revision);
 	};
 
-	return { getIndex, tryGetInfo, hasRollback };
+	const getIndex = (revision: RevisionTag): number | undefined => {
+		const index = revInfos.findIndex((revInfo) => revInfo.revision === revision);
+		if (index >= 0) {
+			return index;
+		}
+
+		const rollbackIndex = revInfos.findIndex((revInfo) => revInfo.rollbackOf === revision);
+		if (rollbackIndex >= 0) {
+			// This change is the forward revision of a rollback included in revInfos, so it comes after
+			// all revisions in revInfos. Earlier rollbacks have later forward revisions.
+			return 2 * revInfos.length - rollbackIndex;
+		}
+
+		return undefined;
+	};
+
+	return { compareRevisions, tryGetInfo, hasRollback };
 }
 
 export function rebaseChangeOverChanges<TChange>(

package/src/core/tree/delta.ts

@@ -204,4 +204,10 @@ export interface FieldChanges {
 	 * It corresponds to the sum of `mark.count` values for all previous marks for which `isAttachMark(mark)` is false.
 	 */
 	readonly marks: readonly Mark[];
+
+	/**
+	 * Indicates whether nodes detached by this field can be safely re-attached.
+	 * Defaults to false.
+	 */
+	readonly allowReattach?: boolean;
 }

package/src/core/tree/detachedFieldIndex.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, fail } from "@fluidframework/core-utils/internal";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 import {
@@ -52,6 +52,12 @@ export interface ReadOnlyDetachedFieldIndex {
 	 */
 	toFieldKey(id: ForestRootId): FieldKey;
 
+	/**
+	 * Returns a node ID for the node in the given field.
+	 * @param field - The field key where the detached node resides.
+	 */
+	fromFieldKey(field: FieldKey): Delta.DetachedNodeId;
+
 	/**
 	 * Returns the `ForestRootId` associated with the given id.
 	 * Returns undefined if no such id is known to the index.
@@ -63,6 +69,12 @@ export interface ReadOnlyDetachedFieldIndex {
 	 * Fails if no such id is known to the index.
 	 */
 	getEntry(id: Delta.DetachedNodeId): ForestRootId;
+
+	/**
+	 * Returns the source associated with the given id if any.
+	 * @param id - The detached node ID.
+	 */
+	isAttachable(id: Delta.DetachedNodeId): boolean | undefined;
 }
 
 /**
@@ -197,6 +209,16 @@ export class DetachedFieldIndex implements ReadOnlyDetachedFieldIndex {
 		return brand(`${this.name}-${id}`);
 	}
 
+	public fromFieldKey(field: FieldKey): Delta.DetachedNodeId {
+		// TODO: maintain a lookup table or use field keys that encode the detached node ID
+		for (const { id, root } of this.entries()) {
+			if (this.toFieldKey(root) === field) {
+				return id;
+			}
+		}
+		fail("No known detached roots in the given field");
+	}
+
 	public tryGetEntry(id: Delta.DetachedNodeId): ForestRootId | undefined {
 		return tryGetFromNestedMap(this.detachedNodeToField, id.major, id.minor)?.root;
 	}
@@ -207,6 +229,10 @@ export class DetachedFieldIndex implements ReadOnlyDetachedFieldIndex {
 		return key;
 	}
 
+	public isAttachable(id: Delta.DetachedNodeId): boolean | undefined {
+		return tryGetFromNestedMap(this.detachedNodeToField, id.major, id.minor)?.isAttachable;
+	}
+
 	/**
 	 * Returns the detached root IDs for all the trees that were detached or last modified by the given revision.
 	 */
@@ -259,6 +285,7 @@ export class DetachedFieldIndex implements ReadOnlyDetachedFieldIndex {
 	public createEntry(
 		nodeId?: Delta.DetachedNodeId,
 		revision?: RevisionTag,
+		isAttachable?: boolean,
 		count: number = 1,
 	): ForestRootId {
 		const root = this.rootIdAllocator.allocate(count);
@@ -272,6 +299,7 @@ export class DetachedFieldIndex implements ReadOnlyDetachedFieldIndex {
 				setInNestedMap(this.detachedNodeToField, nodeId.major, nodeId.minor + i, {
 					root: brand<ForestRootId>(root + i),
 					latestRelevantRevision: revision,
+					isAttachable,
 				});
 				setInNestedMap(this.latestRelevantRevisionToFields, revision, root + i, {
 					major: nodeId.major,

package/src/core/tree/detachedFieldIndexCodecs.ts

@@ -24,16 +24,18 @@ type BuildData = CodecWriteOptions & {
 
 export const detachedFieldIndexCodecBuilder = ClientVersionDispatchingCodecBuilder.build(
 	"DetachedFieldIndex",
-	{
-		[lowestMinVersionForCollab]: {
+	[
+		{
+			minVersionForCollab: lowestMinVersionForCollab,
 			formatVersion: DetachedFieldIndexFormatVersion.v1,
 			codec: (buildData: BuildData) =>
 				makeDetachedNodeToFieldCodecV1(buildData.revisionTagCodec, buildData.idCompressor),
 		},
-		[FluidClientVersion.v2_52]: {
+		{
+			minVersionForCollab: FluidClientVersion.v2_52,
 			formatVersion: DetachedFieldIndexFormatVersion.v2,
 			codec: (buildData: BuildData) =>
 				makeDetachedNodeToFieldCodecV2(buildData.revisionTagCodec, buildData.idCompressor),
 		},
-	},
+	],
 );

package/src/core/tree/detachedFieldIndexTypes.ts

@@ -49,4 +49,9 @@ export interface DetachedField {
 	 * `DetachedField` and `Forest` are GC-ed.
 	 */
 	readonly latestRelevantRevision?: RevisionTag;
+
+	/**
+	 * Indicates whether the corresponding root can safely be re-attached.
+	 */
+	readonly isAttachable?: boolean;
 }