@fluidframework/tree 2.101.1 → 2.103.0

package/src/feature-libraries/chunked-forest/codec/format/formatVText.ts

@@ -0,0 +1,84 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import * as Type from "@sinclair/typebox";
+import type { Static } from "@sinclair/typebox";
+
+import { unionOptions } from "../../../../codec/index.js";
+
+import { ShapeIndex } from "./formatGeneric.js";
+import { EncodedFieldShape, EncodedValueShape } from "./formatV1.js";
+import { shapesV2 } from "./formatV2.js";
+
+/**
+ * A node shape that derives from another node shape by overlaying property-level overrides.
+ *
+ * @remarks
+ * Compresses runs of node shapes that differ only in a few properties: a base node shape
+ * defines the structural skeleton, and the specialization narrows specific properties.
+ *
+ * For example, a base `FormatNode` with a variable-boolean `bold` field can be specialized
+ * to a shape that pins `bold` to a constant `true` — every node decoded with the
+ * specialization contributes zero stream tokens for `bold`.
+ *
+ * Specialization rules: `type` is always inherited from the resolved base. `fields` overrides
+ * apply per-key: entries whose key matches a base field replace that entry's shape index in
+ * place; entries with new keys are appended after all base fields. For `value` and
+ * `extraFields`: if the property is absent on the wire, the base's value is inherited; if
+ * `null`, the resulting shape has no value / no extraFields (explicit clear); any other value
+ * replaces the base's.
+ *
+ * The `null` sentinel exists because JSON does not preserve `undefined`-valued properties,
+ * so override-vs-inherit cannot be discriminated by property presence after persistence.
+ *
+ * Decoded by {@link applySpecialization}.
+ */
+export type EncodedSpecializedNodeShape = Static<typeof EncodedSpecializedNodeShape>;
+export const EncodedSpecializedNodeShape = Type.Object(
+	{
+		/**
+		 * Index into the enclosing batch's shapes array of the shape this specializes.
+		 * Must resolve to either an {@link EncodedNodeShape} or another
+		 * `EncodedSpecializedNodeShape`; chains are followed transitively until a node shape
+		 * is reached. This restriction is enforced at runtime, not by the schema.
+		 */
+		base: ShapeIndex,
+		/**
+		 * Field-level overrides applied to the resolved base's `fields`. Entries whose key
+		 * matches a base field replace that field's shape index in place; entries with new
+		 * keys are appended after all base fields, in the order given here. Base field order
+		 * is preserved — this is the stream consumption order at decode time, so encoders
+		 * must serialize per-field tokens in the resulting field order, not in this list's order.
+		 */
+		fields: Type.Optional(Type.Array(EncodedFieldShape)),
+		/**
+		 * If absent, inherits the resolved base's value shape. If `null`, the resulting shape
+		 * has no value shape (explicit clear). Any other value replaces the base's.
+		 */
+		value: Type.Optional(Type.Union([EncodedValueShape, Type.Null()])),
+		/**
+		 * If absent, inherits the resolved base's extraFields shape. If `null`, the resulting
+		 * shape has no extraFields (explicit clear). Any other value replaces the base's.
+		 */
+		extraFields: Type.Optional(Type.Union([ShapeIndex, Type.Null()])),
+	},
+	{ additionalProperties: false },
+);
+
+/**
+ * Experimental extension of {@link EncodedChunkShapeV2}.
+ * @remarks
+ * See {@link DiscriminatedUnionDispatcher} for more information on this pattern.
+ */
+export type EncodedChunkShapeVTextExperimental = Static<
+	typeof EncodedChunkShapeVTextExperimental
+>;
+export const EncodedChunkShapeVTextExperimental = Type.Object(
+	{
+		...shapesV2,
+		f: Type.Optional(EncodedSpecializedNodeShape),
+	},
+	unionOptions,
+);

package/src/feature-libraries/chunked-forest/codec/format/index.ts

@@ -16,14 +16,19 @@ export {
 	SpecialField,
 } from "./formatV1.js";
 export { EncodedIncrementalChunkShape, EncodedChunkShapeV2 } from "./formatV2.js";
+export {
+	EncodedChunkShapeVTextExperimental,
+	EncodedSpecializedNodeShape,
+} from "./formatVText.js";
 export {
 	FieldBatchFormatVersion,
 	EncodedFieldBatchV1,
 	EncodedFieldBatchV2,
+	EncodedFieldBatchVTextExperimental,
 	supportsIncrementalEncoding,
 	type EncodedFieldBatchV1OrV2,
 	type EncodedFieldBatchV1AndV2,
-	type EncodedChunkShapeV1OrV2,
+	type EncodedChunkShape,
 } from "./versions.js";
 export type {
 	ShapeIndex,

package/src/feature-libraries/chunked-forest/codec/format/versions.ts

@@ -10,6 +10,7 @@ import { strictEnum, type Values } from "../../../../util/index.js";
 import { EncodedFieldBatchGeneric } from "./formatGeneric.js";
 import { EncodedChunkShapeV1 } from "./formatV1.js";
 import { EncodedChunkShapeV2 } from "./formatV2.js";
+import { EncodedChunkShapeVTextExperimental } from "./formatVText.js";
 
 /**
  * The format version for the field batch.
@@ -29,6 +30,10 @@ export const FieldBatchFormatVersion = strictEnum("FieldBatchFormatVersion", {
 	 * {@link EncodedIncrementalChunkShape} was added in this version.
 	 */
 	v2: 2,
+	/**
+	 * Experimental codec with optimizations for text.
+	 */
+	vTextExperimental: "text",
 });
 
 /**
@@ -68,6 +73,17 @@ export const EncodedFieldBatchV2 = EncodedFieldBatchGeneric(
 	EncodedChunkShapeV2,
 );
 
+/**
+ * Encoded {@link FieldBatch} using the experimental text optimized format.
+ */
+export type EncodedFieldBatchVTextExperimental = Static<
+	typeof EncodedFieldBatchVTextExperimental
+>;
+export const EncodedFieldBatchVTextExperimental = EncodedFieldBatchGeneric(
+	FieldBatchFormatVersion.vTextExperimental,
+	EncodedChunkShapeVTextExperimental,
+);
+
 /**
  * Encoded {@link FieldBatch}, which might use V2 features, but might also have been from a V1 encoder.
  * @remarks
@@ -88,9 +104,14 @@ export type EncodedFieldBatchV1OrV2 = EncodedFieldBatchV1 | EncodedFieldBatchV2;
 export type EncodedFieldBatchV1AndV2 = EncodedFieldBatchV1 & EncodedFieldBatchV2;
 
 /**
- * Encoded chunk shape, which might use V2 features, but might also have been from a V1 encoder.
+ * An encoded chunk shape from any known {@link FieldBatchFormatVersion}.
+ *
  * @remarks
- * Type wise, equivalent to V2, as that is a superset of V1.
- * Used instead of just V2 for clarity.
+ * Use this when working with chunk shapes uniformly across versions — for example, in the
+ * shared decoder dispatcher and in encoder shape base classes. New format versions should
+ * add their chunk shape variant to this union.
  */
-export type EncodedChunkShapeV1OrV2 = EncodedChunkShapeV1 | EncodedChunkShapeV2;
+export type EncodedChunkShape =
+	| EncodedChunkShapeV1
+	| EncodedChunkShapeV2
+	| EncodedChunkShapeVTextExperimental;

package/src/feature-libraries/chunked-forest/codec/nodeEncoder.ts

@@ -4,7 +4,7 @@
  */
 
 import { assert, fail } from "@fluidframework/core-utils/internal";
-import { isStableId } from "@fluidframework/id-compressor/internal";
+import { isFinalId, isStableId } from "@fluidframework/id-compressor/internal";
 
 import {
 	type FieldKey,
@@ -25,7 +25,7 @@ import {
 	encodeValue,
 } from "./compressedEncode.js";
 import type {
-	EncodedChunkShapeV1OrV2,
+	EncodedChunkShape,
 	EncodedFieldShape,
 	EncodedValueShape,
 } from "./format/index.js";
@@ -36,10 +36,7 @@ import type {
  * The fact this is also a Shape is an implementation detail of the encoder: that allows the shape it uses to be itself,
  * which is an easy way to keep all the related code together without extra objects.
  */
-export class NodeShapeBasedEncoder
-	extends Shape<EncodedChunkShapeV1OrV2>
-	implements NodeEncoder
-{
+export class NodeShapeBasedEncoder extends Shape<EncodedChunkShape> implements NodeEncoder {
 	/**
 	 * Set of keys for fields that are encoded using {@link NodeShapeBasedEncoder.specializedFieldEncoders}.
 	 * TODO: Ensure uniform chunks, encoding and identifier generation sort fields the same.
@@ -82,8 +79,7 @@ export class NodeShapeBasedEncoder
 					// This is not the case for forest summaries at the time of writing, so non-finalized ids are instead written using
 					// their long form (by falling through to the original cursor value).
 					// A scenario where such ids can appear in the summary is in the attach summary of a tree being attached to an already-attached container.
-					// TODO: isFinalId should probably be exported from id-compressor and that could be used to do the narrowing here.
-					if (!context.isSummary || opSpaceId >= 0) {
+					if (!context.isSummary || isFinalId(opSpaceId)) {
 						return opSpaceId;
 					}
 				}
@@ -95,7 +91,7 @@ export class NodeShapeBasedEncoder
 	public encodeNode(
 		cursor: ITreeCursorSynchronous,
 		context: EncoderContext,
-		outputBuffer: BufferFormat<EncodedChunkShapeV1OrV2>,
+		outputBuffer: BufferFormat<EncodedChunkShape>,
 	): void {
 		if (this.type === undefined) {
 			outputBuffer.push(new IdentifierToken(cursor.type));
@@ -109,7 +105,7 @@ export class NodeShapeBasedEncoder
 			cursor.exitField();
 		}
 
-		const otherFieldsBuffer: BufferFormat<EncodedChunkShapeV1OrV2> = [];
+		const otherFieldsBuffer: BufferFormat<EncodedChunkShape> = [];
 
 		forEachField(cursor, () => {
 			const key = cursor.getFieldKey();
@@ -130,8 +126,8 @@ export class NodeShapeBasedEncoder
 
 	public encodeShape(
 		identifiers: DeduplicationTable<string>,
-		shapes: DeduplicationTable<Shape<EncodedChunkShapeV1OrV2>>,
-	): EncodedChunkShapeV1OrV2 {
+		shapes: DeduplicationTable<Shape<EncodedChunkShape>>,
+	): EncodedChunkShape {
 		return {
 			c: {
 				type: encodeOptionalIdentifier(this.type, identifiers),
@@ -144,7 +140,7 @@ export class NodeShapeBasedEncoder
 
 	public countReferencedShapesAndIdentifiers(
 		identifiers: Counter<string>,
-		shapeDiscovered: (shape: Shape<EncodedChunkShapeV1OrV2>) => void,
+		shapeDiscovered: (shape: Shape<EncodedChunkShape>) => void,
 	): void {
 		if (this.type !== undefined) {
 			identifiers.add(this.type);
@@ -160,7 +156,7 @@ export class NodeShapeBasedEncoder
 		}
 	}
 
-	public get shape(): Shape<EncodedChunkShapeV1OrV2> {
+	public get shape(): Shape<EncodedChunkShape> {
 		return this;
 	}
 }
@@ -168,7 +164,7 @@ export class NodeShapeBasedEncoder
 export function encodeFieldShapes(
 	fieldEncoders: readonly KeyedFieldEncoder[],
 	identifiers: DeduplicationTable<string>,
-	shapes: DeduplicationTable<Shape<EncodedChunkShapeV1OrV2>>,
+	shapes: DeduplicationTable<Shape<EncodedChunkShape>>,
 ): EncodedFieldShape[] | undefined {
 	if (fieldEncoders.length === 0) {
 		return undefined;
@@ -197,14 +193,14 @@ function encodeOptionalIdentifier(
 
 function encodeOptionalFieldShape(
 	encoder: FieldEncoder | undefined,
-	shapes: DeduplicationTable<Shape<EncodedChunkShapeV1OrV2>>,
+	shapes: DeduplicationTable<Shape<EncodedChunkShape>>,
 ): number | undefined {
 	return encoder === undefined ? undefined : dedupShape(encoder.shape, shapes);
 }
 
 function dedupShape(
-	shape: Shape<EncodedChunkShapeV1OrV2>,
-	shapes: DeduplicationTable<Shape<EncodedChunkShapeV1OrV2>>,
+	shape: Shape<EncodedChunkShape>,
+	shapes: DeduplicationTable<Shape<EncodedChunkShape>>,
 ): number {
 	return shapes.valueToIndex.get(shape) ?? fail(0xb51 /* missing shape */);
 }

package/src/feature-libraries/chunked-forest/uniformChunk.ts

@@ -113,7 +113,15 @@ export class TreeShape {
 	public readonly fieldsOffsetArray: readonly OffsetShape[];
 	public readonly valuesPerTopLevelNode: number;
 
-	// TODO: this is only needed at chunk roots. Optimize it base on that.
+	/**
+	 * Information about every node in this shape.
+	 * The root is first, and all indexes it uses to refer to other nodes are indexes into this array.
+	 * Beyond that the ordering is an implementation detail of this shape.
+	 * @remarks
+	 * Use of this in contexts where there might be multiple top-level nodes requires some additional care.
+	 * For example {@link Cursor} derives each node's actual position info from this shared
+	 * array plus the node's top-level index within the chunk.
+	 */
 	public readonly positions: readonly NodePositionInfo[];
 
 	/**
@@ -246,25 +254,19 @@ function clonePositions(
 /**
  * The shape (see `TreeShape`) of a sequence of trees, all with the same shape (like `FieldShape`, but without a field key).
  *
- * This shape is optimized (by caching derived data like the positions array),
- * so that when paired with a value array it can be efficiently traversed like a tree by an {@link ITreeCursorSynchronous}.
- * See {@link uniformChunk} for how to do this.
+ * @remarks
+ * Paired with a value array, this lets a {@link UniformChunk} be traversed like a tree by an
+ * {@link ITreeCursorSynchronous}. The {@link Cursor} derives each node's position info from the
+ * shared {@link TreeShape.positions} plus the node's top-level index.
  *
  * TODO: consider storing shape information in WASM
  */
 export class ChunkShape {
-	public readonly positions: readonly (NodePositionInfo | undefined)[];
-
 	public constructor(
 		public readonly treeShape: TreeShape,
 		public readonly topLevelLength: number,
 	) {
 		assert(topLevelLength > 0, 0x4c6 /* topLevelLength must be greater than 0 */);
-
-		// TODO: avoid duplication from inner loop
-		const positions: (NodePositionInfo | undefined)[] = [undefined];
-		clonePositions(0, [dummyRoot, treeShape, topLevelLength], 0, 0, positions);
-		this.positions = positions;
 	}
 
 	public equals(other: ChunkShape): boolean {
@@ -295,17 +297,19 @@ class OffsetShape {
 }
 
 /**
- * Information about a node at a specific position within a uniform chunk.
+ * Information about a node at a specific position within one top-level tree of a {@link TreeShape}.
  */
 class NodePositionInfo implements UpPath {
 	/**
-	 * @param parent - TODO
-	 * @param parentField - TODO
+	 * @param parent - The parent node's {@link NodePositionInfo} or `undefined` for a root.
+	 * @param parentField - The {@link FieldKey} of the field this node occupies within its parent.
 	 * @param parentIndex - indexWithinParentField
-	 * @param indexOfParentField - which field of the parent `parentIndex` is indexing into to locate this.
-	 * @param indexOfParentPosition - Index of parent NodePositionInfo in positions array. TODO: use offsets to avoid copying at top level?
+	 * @param indexOfParentField - Which field of the parent `parentIndex` is indexing into to locate this.
+	 * @param indexOfParentPosition - Index of this node's parent in {@link TreeShape.positions}
 	 * @param shape - Shape of the top level sequence this node is part of
-	 * @param valueOffset - TODO
+	 * @param topLevelLength - Number of siblings in this node's field. For a root this is unused
+	 * @param valueOffset - Offset of this node's value within one top-level tree's slice of the chunk's flat `values` array;
+	 * only valid when `shape.hasValue` (otherwise it's where the value would have gone, and should not be used to read a value).
 	 */
 	public constructor(
 		public readonly parent: NodePositionInfo | undefined, // TODO; general UpPath to allow prefixing here?
@@ -322,16 +326,28 @@ class NodePositionInfo implements UpPath {
 /**
  * The cursor implementation for `UniformChunk`.
  *
- * Works by tracking its location in the chunk's `positions` array.
+ * @remarks
+ * Tracks a flat `positionIndex` and derives each node's position info from the shape's shared
+ * {@link TreeShape.positions} plus the node's top-level index.
  */
 class Cursor extends SynchronousCursor implements ChunkedCursor {
 	private positionIndex!: number; // When in fields mode, this points to the parent node.
-	// Undefined when in root field
+
+	/** Position info for the current node, or `undefined` when in root field. */
 	private nodePositionInfo: NodePositionInfo | undefined;
 
-	// Cached constants for faster access
+	/** Which top-level node of the chunk the current position is within. Valid when nodePositionInfo !== undefined. */
+	private topLevelIndex: number = 0;
+
+	// Cached constants for faster access.
+	/** The chunk's shape. */
 	private readonly shape: ChunkShape;
-	private readonly positions: readonly (NodePositionInfo | undefined)[];
+	/** The chunk's per-tree shape (shape of each top-level tree). */
+	private readonly treeShape: TreeShape;
+	/** Number of positions in one top-level tree (treeShape.positions.length). */
+	private readonly nodeLength: number;
+	/** Number of values per top-level node (treeShape.valuesPerTopLevelNode). */
+	private readonly stride: number;
 
 	public mode: CursorLocationType = CursorLocationType.Fields;
 
@@ -346,7 +362,9 @@ class Cursor extends SynchronousCursor implements ChunkedCursor {
 	public constructor(private readonly chunk: UniformChunk) {
 		super();
 		this.shape = this.chunk.shape;
-		this.positions = this.shape.positions;
+		this.treeShape = this.shape.treeShape;
+		this.nodeLength = this.treeShape.positions.length;
+		this.stride = this.treeShape.valuesPerTopLevelNode;
 		this.fieldKey = dummyRoot;
 		this.moveToPosition(0);
 	}
@@ -377,18 +395,70 @@ class Cursor extends SynchronousCursor implements ChunkedCursor {
 
 	/**
 	 * Change the current node within the chunk.
+	 *
+	 * @param positionIndex - flat position index of the newly selected node. This is NOT an index
+	 * within a field, and is not bounds checked.
+	 *
+	 * @remarks
+	 * Decomposes the index into {@link Cursor.topLevelIndex} and {@link Cursor.nodePositionInfo}.
 	 * See `nodeInfo` for getting data about the current node.
 	 *
-	 * @param positionIndex - index of the position of the newly selected node in `positions`.
-	 * This is NOT an index within a field, and is not bounds checked.
 	 */
 	private moveToPosition(positionIndex: number): void {
-		this.nodePositionInfo = this.positions[positionIndex];
 		this.positionIndex = positionIndex;
-		if (this.nodePositionInfo === undefined) {
-			assert(positionIndex === 0, 0x561 /* expected root at start */);
+		if (positionIndex === 0) {
+			this.nodePositionInfo = undefined;
 			assert(this.mode === CursorLocationType.Fields, 0x562 /* expected root to be a field */);
+			return;
 		}
+		const decoded = this.decodePosition(positionIndex);
+		this.topLevelIndex = decoded.topLevelIndex;
+		this.nodePositionInfo = decoded.info;
+	}
+
+	/**
+	 * Decode a flat `positionIndex` into its components.
+	 *
+	 * @param positionIndex - flat position index of the node to decode. Must be greater than 0;
+	 * @returns the node's index within {@link TreeShape.positions} (`withinTree`), which top-level
+	 * tree holds it (`topLevelIndex`), and the corresponding shared {@link NodePositionInfo} (`info`).
+	 */
+	private decodePosition(positionIndex: number): {
+		withinTree: number;
+		topLevelIndex: number;
+		info: NodePositionInfo;
+	} {
+		const offset = positionIndex - 1;
+		// Find the node's index within treeShape.positions, then which top-level tree holds it.
+		const withinTree = offset % this.nodeLength; // remainder
+		const topLevelIndex = (offset - withinTree) / this.nodeLength; // quotient
+		const info = this.treeShape.positions[withinTree] ?? oob();
+		return { withinTree, topLevelIndex, info };
+	}
+
+	/**
+	 * Build a standalone {@link UpPath} for the node at `positionIndex`. O(depth) allocation.
+	 *
+	 * @remarks
+	 * walks the shared per-tree {@link TreeShape.positions} and applies the top-level index
+	 * at each level. Mirrors how the `BasicChunk` cursor allocates paths.
+	 */
+	private materializePath(positionIndex: number): UpPath | undefined {
+		if (positionIndex === 0) {
+			return undefined;
+		}
+		const { withinTree, topLevelIndex, info } = this.decodePosition(positionIndex);
+		if (info.parent === undefined) {
+			// Top-level node: its parent is the (prefixed) chunk root.
+			return { parent: undefined, parentField: info.parentField, parentIndex: topLevelIndex };
+		}
+		return {
+			parent: this.materializePath(
+				positionIndex - withinTree + (info.indexOfParentPosition ?? oob()),
+			),
+			parentField: info.parentField,
+			parentIndex: info.parentIndex,
+		};
 	}
 
 	/**
@@ -505,36 +575,51 @@ class Cursor extends SynchronousCursor implements ChunkedCursor {
 	private enterRootNodeInner(childIndex: number): void {
 		this.mode = CursorLocationType.Nodes;
 		this.fieldKey = undefined;
-		// 1 for the "undefined" at the beginning of the positions array, then stride by top level tree shape.
-		this.moveToPosition(1 + childIndex * this.shape.treeShape.positions.length);
+		// 1 for the "undefined" root-field marker at position 0, then stride by one top-level tree (nodeLength).
+		this.moveToPosition(1 + childIndex * this.nodeLength);
 		assert(this.fieldIndex === childIndex, 0x543 /* should be at selected child */);
 	}
 
 	public getFieldPath(prefix?: PathRootPrefix): FieldUpPath {
 		return prefixFieldPath(prefix, {
 			field: this.getFieldKey(),
-			parent: this.nodePositionInfo,
+			parent: this.materializePath(this.positionIndex),
 		});
 	}
 
 	public getPath(prefix?: PathRootPrefix): UpPath | undefined {
-		return prefixPath(prefix, this.nodeInfo(CursorLocationType.Nodes));
+		this.nodeInfo(CursorLocationType.Nodes); // assert: in nodes mode at a node
+		return prefixPath(prefix, this.materializePath(this.positionIndex));
 	}
 
 	public get fieldIndex(): number {
-		return this.nodeInfo(CursorLocationType.Nodes).parentIndex;
+		const info = this.nodeInfo(CursorLocationType.Nodes);
+		return info.parent === undefined ? this.topLevelIndex : info.parentIndex;
 	}
 
 	public readonly chunkStart: number = 0;
 
+	/**
+	 * Number of nodes in `info`'s field including `info` itself.
+	 *
+	 * @remarks
+	 * For top-level nodes this is the chunk's `topLevelLength`, read from the chunk
+	 * rather than the node, so the shared per-tree {@link TreeShape.positions} stays independent of
+	 * chunk length; the root entry's own `topLevelLength` field is unused. Nested nodes use the
+	 * field length stored on the node.
+	 */
+	private siblingCount(info: NodePositionInfo): number {
+		return info.parent === undefined ? this.shape.topLevelLength : info.topLevelLength;
+	}
+
 	public get chunkLength(): number {
-		return this.nodeInfo(CursorLocationType.Nodes).topLevelLength;
+		return this.siblingCount(this.nodeInfo(CursorLocationType.Nodes));
 	}
 
 	public seekNodes(offset: number): boolean {
 		const info = this.nodeInfo(CursorLocationType.Nodes);
-		const index = offset + info.parentIndex;
-		if (index >= 0 && index < info.topLevelLength) {
+		const index = offset + this.fieldIndex;
+		if (index >= 0 && index < this.siblingCount(info)) {
 			this.moveToPosition(this.positionIndex + offset * info.shape.positions.length);
 			return true;
 		}
@@ -546,8 +631,8 @@ class Cursor extends SynchronousCursor implements ChunkedCursor {
 		// This is the same as `return this.seekNodes(1);` but slightly faster.
 
 		const info = this.nodeInfo(CursorLocationType.Nodes);
-		const index = info.parentIndex + 1;
-		if (index === info.topLevelLength) {
+		const index = this.fieldIndex + 1;
+		if (index === this.siblingCount(info)) {
 			this.exitNode();
 			return false;
 		}
@@ -557,15 +642,17 @@ class Cursor extends SynchronousCursor implements ChunkedCursor {
 
 	public exitNode(): void {
 		const info = this.nodeInfo(CursorLocationType.Nodes);
-		this.indexOfField =
-			info.indexOfParentField ??
-			fail(0xb0a /* navigation up to root field not yet supported */); // TODO;
+		const withinTree = this.positionIndex - 1 - this.topLevelIndex * this.nodeLength;
+		// Top-level nodes (no parent) exit to the root field at position 0;
+		// nested nodes' parent is `indexOfParentPosition` within the same top-level instance.
+		this.indexOfField = info.indexOfParentField ?? 0;
 		this.fieldKey = info.parentField;
 		this.mode = CursorLocationType.Fields;
 		this.moveToPosition(
-			info.indexOfParentPosition ??
-				fail(0xb0b /* navigation up to root field not yet supported */),
-		); // TODO
+			info.indexOfParentPosition === undefined
+				? 0
+				: this.positionIndex - withinTree + info.indexOfParentPosition,
+		);
 	}
 
 	public firstField(): boolean {
@@ -598,7 +685,7 @@ class Cursor extends SynchronousCursor implements ChunkedCursor {
 	public get value(): Value {
 		const info = this.nodeInfo(CursorLocationType.Nodes);
 		if (info.shape.hasValue) {
-			const value = this.chunk.values[info.valueOffset];
+			const value = this.chunk.values[info.valueOffset + this.topLevelIndex * this.stride];
 			// If mayContainCompressedIds is set, check if the value is a number (i.e. a compressed ID that needs decompression).
 			if (info.shape.mayContainCompressedIds && typeof value === "number") {
 				const idCompressor = this.chunk.idCompressor;

package/src/feature-libraries/default-schema/defaultEditBuilder.ts

@@ -316,6 +316,7 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 		const detachCellId = this.modularBuilder.generateId(count);
 		const attachCellId: CellId = { localId: this.modularBuilder.generateId(count), revision };
 		if (compareFieldUpPaths(sourceField, destinationField)) {
+			// The source and destination fields are the same.
 			const change = sequence.changeHandler.editor.move(
 				sourceIndex,
 				count,
@@ -331,32 +332,53 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 				revision,
 			);
 		} else {
+			// The source and destination fields are different.
 			const detachPath = topDownPath(sourceField.parent);
 			const attachPath = topDownPath(destinationField.parent);
+			/**
+			 * The number of elements, starting from the root, that both paths have in common.
+			 * This defines the lowest common ancestor node (LCA) of the source and destination fields.
+			 */
 			const sharedDepth = getSharedPrefixLength(detachPath, attachPath);
 			let adjustedAttachField = destinationField;
-			// After the above loop, `sharedDepth` is the number of elements, starting from the root,
-			// that both paths have in common.
+			// Check if the detach parent
+			// (the node directly above the location of detach)
+			// is along the attach path,
+			// in which case the attach path might need to be adjusted.
+			// This is synonymous with checking if the attach parent
+			// (the node directly above the location of attach)
+			// is either below or the same as the detach parent.
+			// If not, then the move does not need to be adjusted
+			// as the attach path will not be affected by the detach.
 			if (sharedDepth === detachPath.length) {
-				const attachField = attachPath[sharedDepth]?.parentField ?? destinationField.field;
-				if (attachField === sourceField.field) {
-					// The detach occurs in an ancestor field of the field where the attach occurs.
-					let attachAncestorIndex = attachPath[sharedDepth]?.parentIndex ?? sourceIndex;
-					if (attachAncestorIndex < sourceIndex) {
+				const fieldOnDetachPathUnderLCA = sourceField.field;
+				const firstDifferentAttachAncestor = attachPath[sharedDepth];
+				// Check if the detach location uses the same field as in
+				// the attach path.
+				// Note that when `firstDifferentAttachAncestor` is undefined,
+				// that means the parents are the same. Since earlier call
+				// to `compareFieldUpPaths` returned false, we know that the
+				// fields must be different AND thus no adjustment is needed.
+				if (fieldOnDetachPathUnderLCA === firstDifferentAttachAncestor?.parentField) {
+					// Now working at the level where detach happens along the
+					// attach path.
+					if (firstDifferentAttachAncestor.parentIndex < sourceIndex) {
 						// The attach path runs through a node located before the detached nodes.
 						// No need to adjust the attach path.
-					} else if (sourceIndex + count <= attachAncestorIndex) {
+					} else if (sourceIndex + count <= firstDifferentAttachAncestor.parentIndex) {
 						// The attach path runs through a node located after the detached nodes.
-						// adjust the index for the node at that depth of the path, so that it is interpreted correctly
+						// Adjust the index for the node at that depth of the path, so that it is interpreted correctly
 						// in the composition performed by `submitChanges`.
-						attachAncestorIndex -= count;
-						let parent: UpPath | undefined = attachPath[sharedDepth - 1];
-						const parentField = attachPath[sharedDepth] ?? oob();
+						// Start with path to root that remains intact.
+						let parent = firstDifferentAttachAncestor.parent;
+						// Extend with index-adjusted parent.
 						parent = {
 							parent,
-							parentIndex: attachAncestorIndex,
-							parentField: parentField.parentField,
+							parentIndex: firstDifferentAttachAncestor.parentIndex - count,
+							parentField: firstDifferentAttachAncestor.parentField,
 						};
+						// Extend with the rest of the attach path, which is unaffected
+						// apart from parentage replacements.
 						for (let i = sharedDepth + 1; i < attachPath.length; i += 1) {
 							parent = {
 								...(attachPath[i] ?? oob()),