@fluidframework/tree 2.23.0 → 2.30.0

package/lib/util/referenceCounting.d.ts

@@ -2,8 +2,26 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
+/**
+ * An object which counts the number of users / references to it.
+ * @remarks
+ * This implements the [Reference counting](https://en.wikipedia.org/wiki/Reference_counting) pattern.
+ * Getting the reference count correct is difficult in TypeScript and great care must be used.
+ * Because of this, this interface should not be used in the public API.
+ */
 export interface ReferenceCounted {
+    /**
+     * Called to increase the reference count tracked by this object.
+     * @remarks
+     * When a user of this object allows something else to use it,
+     * this should be called.
+     */
     referenceAdded(): void;
+    /**
+     * Called to decrease the reference count tracked by this object.
+     * @remarks
+     * When a user of this object will no longer use it, this should be called.
+     */
     referenceRemoved(): void;
     /**
      * @returns true if mutating this object may impact other users of it.

package/lib/util/referenceCounting.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"referenceCounting.d.ts","sourceRoot":"","sources":["../../src/util/referenceCounting.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,WAAW,gBAAgB;IAChC,cAAc,IAAI,IAAI,CAAC;IAEvB,gBAAgB,IAAI,IAAI,CAAC;IAEzB;;;;OAIG;IACH,QAAQ,IAAI,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,8BAAsB,oBAAqB,YAAW,gBAAgB;IAC/C,OAAO,CAAC,QAAQ;IAAtC,SAAS,aAAqB,QAAQ,GAAE,MAAU;IAE3C,cAAc,CAAC,KAAK,SAAI,GAAG,IAAI;IAI/B,gBAAgB,CAAC,KAAK,SAAI,GAAG,IAAI;IAQjC,QAAQ,IAAI,OAAO;IAInB,cAAc,IAAI,OAAO;IAIhC;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,cAAc,IAAI,IAAI;CACzC"}
+{"version":3,"file":"referenceCounting.d.ts","sourceRoot":"","sources":["../../src/util/referenceCounting.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;;;OAKG;IACH,cAAc,IAAI,IAAI,CAAC;IACvB;;;;OAIG;IACH,gBAAgB,IAAI,IAAI,CAAC;IAEzB;;;;OAIG;IACH,QAAQ,IAAI,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,8BAAsB,oBAAqB,YAAW,gBAAgB;IAC/C,OAAO,CAAC,QAAQ;IAAtC,SAAS,aAAqB,QAAQ,GAAE,MAAU;IAE3C,cAAc,CAAC,KAAK,SAAI,GAAG,IAAI;IAI/B,gBAAgB,CAAC,KAAK,SAAI,GAAG,IAAI;IAQjC,QAAQ,IAAI,OAAO;IAInB,cAAc,IAAI,OAAO;IAIhC;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,cAAc,IAAI,IAAI;CACzC"}

package/lib/util/referenceCounting.js.map

@@ -1 +1 @@
-{"version":3,"file":"referenceCounting.js","sourceRoot":"","sources":["../../src/util/referenceCounting.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAC;AAe7D;;GAEG;AACH,MAAM,OAAgB,oBAAoB;IACzC,YAA8B,WAAmB,CAAC;QAApB,aAAQ,GAAR,QAAQ,CAAY;IAAG,CAAC;IAE/C,cAAc,CAAC,KAAK,GAAG,CAAC;QAC9B,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC;IACxB,CAAC;IAEM,gBAAgB,CAAC,KAAK,GAAG,CAAC;QAChC,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC;QACvB,MAAM,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,EAAE,KAAK,CAAC,wBAAwB,CAAC,CAAC;QAC3D,IAAI,IAAI,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;YACzB,IAAI,CAAC,cAAc,EAAE,CAAC;QACvB,CAAC;IACF,CAAC;IAEM,QAAQ;QACd,OAAO,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;IAC1B,CAAC;IAEM,cAAc;QACpB,OAAO,IAAI,CAAC,QAAQ,KAAK,CAAC,CAAC;IAC5B,CAAC;CAMD","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils/internal\";\n\nexport interface ReferenceCounted {\n\treferenceAdded(): void;\n\n\treferenceRemoved(): void;\n\n\t/**\n\t * @returns true if mutating this object may impact other users of it.\n\t *\n\t * Implementations can return true if the refcount is 1 OR the content is logically immutable.\n\t */\n\tisShared(): boolean;\n}\n\n/**\n * Base class to assist with implementing ReferenceCounted.\n */\nexport abstract class ReferenceCountedBase implements ReferenceCounted {\n\tprotected constructor(private refCount: number = 1) {}\n\n\tpublic referenceAdded(count = 1): void {\n\t\tthis.refCount += count;\n\t}\n\n\tpublic referenceRemoved(count = 1): void {\n\t\tthis.refCount -= count;\n\t\tassert(this.refCount >= 0, 0x4c4 /* Negative ref count */);\n\t\tif (this.refCount === 0) {\n\t\t\tthis.onUnreferenced();\n\t\t}\n\t}\n\n\tpublic isShared(): boolean {\n\t\treturn this.refCount > 1;\n\t}\n\n\tpublic isUnreferenced(): boolean {\n\t\treturn this.refCount === 0;\n\t}\n\n\t/**\n\t * Called when refcount reaches 0.\n\t */\n\tprotected abstract onUnreferenced(): void;\n}\n"]}
+{"version":3,"file":"referenceCounting.js","sourceRoot":"","sources":["../../src/util/referenceCounting.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAC;AAgC7D;;GAEG;AACH,MAAM,OAAgB,oBAAoB;IACzC,YAA8B,WAAmB,CAAC;QAApB,aAAQ,GAAR,QAAQ,CAAY;IAAG,CAAC;IAE/C,cAAc,CAAC,KAAK,GAAG,CAAC;QAC9B,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC;IACxB,CAAC;IAEM,gBAAgB,CAAC,KAAK,GAAG,CAAC;QAChC,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC;QACvB,MAAM,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,EAAE,KAAK,CAAC,wBAAwB,CAAC,CAAC;QAC3D,IAAI,IAAI,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;YACzB,IAAI,CAAC,cAAc,EAAE,CAAC;QACvB,CAAC;IACF,CAAC;IAEM,QAAQ;QACd,OAAO,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;IAC1B,CAAC;IAEM,cAAc;QACpB,OAAO,IAAI,CAAC,QAAQ,KAAK,CAAC,CAAC;IAC5B,CAAC;CAMD","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils/internal\";\n\n/**\n * An object which counts the number of users / references to it.\n * @remarks\n * This implements the [Reference counting](https://en.wikipedia.org/wiki/Reference_counting) pattern.\n * Getting the reference count correct is difficult in TypeScript and great care must be used.\n * Because of this, this interface should not be used in the public API.\n */\nexport interface ReferenceCounted {\n\t/**\n\t * Called to increase the reference count tracked by this object.\n\t * @remarks\n\t * When a user of this object allows something else to use it,\n\t * this should be called.\n\t */\n\treferenceAdded(): void;\n\t/**\n\t * Called to decrease the reference count tracked by this object.\n\t * @remarks\n\t * When a user of this object will no longer use it, this should be called.\n\t */\n\treferenceRemoved(): void;\n\n\t/**\n\t * @returns true if mutating this object may impact other users of it.\n\t *\n\t * Implementations can return true if the refcount is 1 OR the content is logically immutable.\n\t */\n\tisShared(): boolean;\n}\n\n/**\n * Base class to assist with implementing ReferenceCounted.\n */\nexport abstract class ReferenceCountedBase implements ReferenceCounted {\n\tprotected constructor(private refCount: number = 1) {}\n\n\tpublic referenceAdded(count = 1): void {\n\t\tthis.refCount += count;\n\t}\n\n\tpublic referenceRemoved(count = 1): void {\n\t\tthis.refCount -= count;\n\t\tassert(this.refCount >= 0, 0x4c4 /* Negative ref count */);\n\t\tif (this.refCount === 0) {\n\t\t\tthis.onUnreferenced();\n\t\t}\n\t}\n\n\tpublic isShared(): boolean {\n\t\treturn this.refCount > 1;\n\t}\n\n\tpublic isUnreferenced(): boolean {\n\t\treturn this.refCount === 0;\n\t}\n\n\t/**\n\t * Called when refcount reaches 0.\n\t */\n\tprotected abstract onUnreferenced(): void;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/tree",
-  "version": "2.23.0",
+  "version": "2.30.0",
   "description": "Distributed tree",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -89,17 +89,17 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "~2.23.0",
-    "@fluidframework/container-runtime": "~2.23.0",
-    "@fluidframework/core-interfaces": "~2.23.0",
-    "@fluidframework/core-utils": "~2.23.0",
-    "@fluidframework/datastore-definitions": "~2.23.0",
-    "@fluidframework/driver-definitions": "~2.23.0",
-    "@fluidframework/id-compressor": "~2.23.0",
-    "@fluidframework/runtime-definitions": "~2.23.0",
-    "@fluidframework/runtime-utils": "~2.23.0",
-    "@fluidframework/shared-object-base": "~2.23.0",
-    "@fluidframework/telemetry-utils": "~2.23.0",
+    "@fluid-internal/client-utils": "~2.30.0",
+    "@fluidframework/container-runtime": "~2.30.0",
+    "@fluidframework/core-interfaces": "~2.30.0",
+    "@fluidframework/core-utils": "~2.30.0",
+    "@fluidframework/datastore-definitions": "~2.30.0",
+    "@fluidframework/driver-definitions": "~2.30.0",
+    "@fluidframework/id-compressor": "~2.30.0",
+    "@fluidframework/runtime-definitions": "~2.30.0",
+    "@fluidframework/runtime-utils": "~2.30.0",
+    "@fluidframework/shared-object-base": "~2.30.0",
+    "@fluidframework/telemetry-utils": "~2.30.0",
     "@sinclair/typebox": "^0.34.13",
     "@tylerbu/sorted-btree-es6": "^1.8.0",
     "@types/ungap__structured-clone": "^1.2.0",
@@ -109,20 +109,20 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.17.1",
     "@biomejs/biome": "~1.9.3",
-    "@fluid-internal/mocha-test-setup": "~2.23.0",
-    "@fluid-private/stochastic-test-utils": "~2.23.0",
-    "@fluid-private/test-dds-utils": "~2.23.0",
-    "@fluid-private/test-drivers": "~2.23.0",
+    "@fluid-internal/mocha-test-setup": "~2.30.0",
+    "@fluid-private/stochastic-test-utils": "~2.30.0",
+    "@fluid-private/test-dds-utils": "~2.30.0",
+    "@fluid-private/test-drivers": "~2.30.0",
     "@fluid-tools/benchmark": "^0.50.0",
     "@fluid-tools/build-cli": "^0.54.0",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.54.0",
-    "@fluidframework/container-definitions": "~2.23.0",
-    "@fluidframework/container-loader": "~2.23.0",
+    "@fluidframework/container-definitions": "~2.30.0",
+    "@fluidframework/container-loader": "~2.30.0",
     "@fluidframework/eslint-config-fluid": "^5.7.3",
-    "@fluidframework/test-runtime-utils": "~2.23.0",
-    "@fluidframework/test-utils": "~2.23.0",
-    "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.22.0",
+    "@fluidframework/test-runtime-utils": "~2.30.0",
+    "@fluidframework/test-utils": "~2.30.0",
+    "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.23.0",
     "@microsoft/api-extractor": "7.47.8",
     "@types/diff": "^3.5.1",
     "@types/easy-table": "^0.0.32",
@@ -140,7 +140,7 @@
     "easy-table": "^1.1.1",
     "eslint": "~8.55.0",
     "eslint-config-prettier": "~9.0.0",
-    "mocha": "^10.2.0",
+    "mocha": "^10.8.2",
     "mocha-multi-reporters": "^1.5.1",
     "moment": "^2.21.0",
     "prettier": "~3.0.3",

package/src/core/forest/editableForest.ts

@@ -3,22 +3,8 @@
  * Licensed under the MIT License.
  */
 
-import type { SessionSpaceCompressedId, IIdCompressor } from "@fluidframework/id-compressor";
-import { assert } from "@fluidframework/core-utils/internal";
-
-import type { RevisionTagCodec } from "../rebase/index.js";
 import type { FieldKey } from "../schema-stored/index.js";
-import {
-	type Anchor,
-	type DeltaRoot,
-	type DeltaVisitor,
-	type DetachedField,
-	type ITreeCursorSynchronous,
-	combineVisitors,
-	deltaForRootInitialization,
-	makeDetachedFieldIndex,
-	visitDelta,
-} from "../tree/index.js";
+import type { Anchor, DeltaVisitor, DetachedField } from "../tree/index.js";
 
 import type { IForestSubscription, ITreeSubscriptionCursor } from "./forest.js";
 
@@ -39,43 +25,6 @@ export interface IEditableForest extends IForestSubscription {
 	acquireVisitor(): DeltaVisitor;
 }
 
-/**
- * Initializes the given forest with the given content.
- * @remarks The forest must be empty when this function is called.
- * This does not perform an edit in the typical sense.
- * Instead, it creates a delta expressing a creation and insertion of the `content` under the {@link rootFieldKey}, and then applies the delta to the forest.
- * If `visitAnchors` is enabled, then the delta will also be applied to the forest's {@link AnchorSet} (in which case there must be no existing anchors when this function is called).
- *
- * @remarks
- * This does not perform an edit: it updates the forest content as if there was an edit that did that.
- */
-export function initializeForest(
-	forest: IEditableForest,
-	content: readonly ITreeCursorSynchronous[],
-	revisionTagCodec: RevisionTagCodec,
-	idCompressor: IIdCompressor,
-	visitAnchors = false,
-): void {
-	assert(forest.isEmpty, 0x747 /* forest must be empty */);
-	const delta: DeltaRoot = deltaForRootInitialization(content);
-	let visitor = forest.acquireVisitor();
-	if (visitAnchors) {
-		assert(forest.anchors.isEmpty(), 0x9b7 /* anchor set must be empty */);
-		const anchorVisitor = forest.anchors.acquireVisitor();
-		visitor = combineVisitors([visitor, anchorVisitor]);
-	}
-
-	// any detached trees built here are immediately attached so the revision used here doesn't matter
-	// we use a dummy revision to make correctness checks in the detached field index easier
-	visitDelta(
-		delta,
-		visitor,
-		makeDetachedFieldIndex("init", revisionTagCodec, idCompressor),
-		0 as SessionSpaceCompressedId,
-	);
-	visitor.free();
-}
-
 // TODO: Types below here may be useful for input into edit building APIs, but are no longer used here directly.
 
 /**

package/src/core/forest/forest.ts

@@ -14,6 +14,7 @@ import {
 	type DetachedField,
 	type ITreeCursor,
 	type ITreeCursorSynchronous,
+	type TreeChunk,
 	type UpPath,
 	detachedFieldAsKey,
 	rootField,
@@ -82,6 +83,17 @@ export interface IForestSubscription {
 	 */
 	clone(schema: TreeStoredSchemaSubscription, anchors: AnchorSet): IEditableForest;
 
+	/**
+	 * Generate a TreeChunk for the content in the given field cursor.
+	 * This can be used to chunk data that is then inserted into the forest.
+	 *
+	 * @remarks
+	 * Like {@link chunkField}, but forces the results into a single TreeChunk.
+	 * While any TreeChunk is compatible with any forest, this method creates one optimized for this specific forest.
+	 * The provided data must be compatible with the forest's current schema.
+	 */
+	chunkField(cursor: ITreeCursorSynchronous): TreeChunk;
+
 	/**
 	 * Allocates a cursor in the "cleared" state.
 	 * @param source - optional string identifying the source of the cursor for debugging purposes when cursors are not properly cleaned up.
@@ -112,7 +124,7 @@ export interface IForestSubscription {
 	): TreeNavigationResult;
 
 	/**
-	 * Set `cursorToMove` to location described by path.
+	 * Set `cursorToMove` to the {@link CursorLocationType.node} described by path.
 	 * This is NOT a relative move: current position is discarded.
 	 * Path must point to existing node.
 	 */
@@ -147,6 +159,7 @@ export interface IForestSubscription {
 }
 
 /**
+ * Returns an anchor to the given field.
  * @param field - defaults to {@link rootField}.
  * @returns anchor to `field`.
  */
@@ -158,8 +171,10 @@ export function rootAnchor(field: DetachedField = rootField): FieldAnchor {
 }
 
 /**
+ * Moves the given cursor to the given detached fields in the given forest.
+ * @param forest - forest to move cursor in.
+ * @param cursorToMove - cursor to move, must be allocated by the given forest
  * @param field - defaults to {@link rootField}.
- * @returns anchor to `field`.
  */
 export function moveToDetachedField(
 	forest: IForestSubscription,

package/src/core/forest/index.ts

@@ -9,7 +9,6 @@ export {
 	type TreeLocation,
 	isFieldLocation,
 	type ForestLocation,
-	initializeForest,
 } from "./editableForest.js";
 export {
 	type IForestSubscription,

package/src/core/index.ts

@@ -11,6 +11,9 @@ export {
 	AnchorSet,
 	type DetachedField,
 	type UpPath,
+	type NormalizedUpPath,
+	type INormalizedUpPath,
+	type NormalizedFieldUpPath,
 	type Range,
 	type RangeUpPath,
 	type PlaceUpPath,
@@ -71,6 +74,7 @@ export {
 	type AnchorNode,
 	anchorSlot,
 	type UpPathDefault,
+	isDetachedUpPath,
 	inCursorField,
 	inCursorNode,
 	type AnchorEvents,
@@ -83,7 +87,6 @@ export {
 	getDetachedFieldContainingPath,
 	aboveRootPlaceholder,
 	type DeltaRoot,
-	type DeltaProtoNode,
 	type DeltaMark,
 	type DeltaDetachedNodeId,
 	type DeltaFieldMap,
@@ -110,7 +113,6 @@ export {
 	type ForestLocation,
 	type ITreeSubscriptionCursor,
 	ITreeSubscriptionCursorState,
-	initializeForest,
 	type FieldAnchor,
 	moveToDetachedField,
 	type ForestEvents,

package/src/core/tree/anchorSet.ts

@@ -24,9 +24,18 @@ import {
 import type { FieldKey } from "../schema-stored/index.js";
 
 import type * as Delta from "./delta.js";
-import type { PlaceIndex, Range, UpPath } from "./pathTree.js";
+import {
+	isDetachedUpPathRoot,
+	type INormalizedUpPath,
+	type NormalizedUpPath,
+	type PlaceIndex,
+	type Range,
+	type UpPath,
+} from "./pathTree.js";
 import { EmptyKey } from "./types.js";
 import type { DeltaVisitor } from "./visitDelta.js";
+import { offsetDetachId } from "./deltaUtil.js";
+import type { ITreeCursorSynchronous } from "./cursor.js";
 
 /**
  * A way to refer to a particular tree location within an {@link AnchorSet}.
@@ -198,7 +207,7 @@ export interface AnchorSetRootEvents {
 /**
  * Node in a tree of anchors.
  */
-export interface AnchorNode extends UpPath<AnchorNode> {
+export interface AnchorNode extends INormalizedUpPath<AnchorNode> {
 	/**
 	 * Events for this anchor node.
 	 */
@@ -569,6 +578,13 @@ export class AnchorSet implements AnchorLocator {
 			node.parentIndex += destination.parentIndex - coupleInfo.startParentIndex;
 			node.parentPath = destinationPath;
 			node.parentField = destination.parentField;
+			// If the destination is a detached root, propagate its detachedNodeId, otherwise remove any existing one
+			node.detachedNodeId = isDetachedUpPathRoot(destination)
+				? offsetDetachId(
+						destination.detachedNodeId,
+						node.parentIndex - destination.parentIndex,
+					)
+				: undefined;
 		}
 
 		// Update new parent to add children
@@ -821,25 +837,34 @@ export class AnchorSet implements AnchorLocator {
 				this.anchorSet.moveChildren(sourcePath, destinationPath, count);
 				this.depthThresholdForSubtreeChanged = this.currentDepth;
 			},
-			detach(source: Range, destination: FieldKey): void {
+			detach(
+				source: Range,
+				destination: FieldKey,
+				detachedNodeId: Delta.DetachedNodeId,
+			): void {
 				this.notifyChildrenChanging();
-				this.detachEdit(source, destination);
+				this.detachEdit(source, destination, detachedNodeId);
 				this.notifyChildrenChanged();
 			},
-			detachEdit(source: Range, destination: FieldKey): void {
+			detachEdit(
+				source: Range,
+				destination: FieldKey,
+				detachedNodeId: Delta.DetachedNodeId,
+			): void {
 				assert(
 					this.parentField !== undefined,
 					0x7a5 /* Must be in a field in order to detach */,
 				);
-				const sourcePath = {
+				const sourcePath: UpPath = {
 					parent: this.parent,
 					parentField: this.parentField,
 					parentIndex: source.start,
 				};
-				const destinationPath = {
+				const destinationPath: NormalizedUpPath = {
 					parent: this.anchorSet.root,
 					parentField: destination,
 					parentIndex: 0,
+					detachedNodeId,
 				};
 				this.anchorSet.moveChildren(sourcePath, destinationPath, source.end - source.start);
 				this.depthThresholdForSubtreeChanged = this.currentDepth;
@@ -848,9 +873,10 @@ export class AnchorSet implements AnchorLocator {
 				newContentSource: FieldKey,
 				range: Range,
 				oldContentDestination: FieldKey,
+				destinationDetachedNodeId: Delta.DetachedNodeId,
 			): void {
 				this.notifyChildrenChanging();
-				this.detachEdit(range, oldContentDestination);
+				this.detachEdit(range, oldContentDestination, destinationDetachedNodeId);
 				this.attachEdit(newContentSource, range.end - range.start, range.start);
 				this.notifyChildrenChanged();
 			},
@@ -864,7 +890,7 @@ export class AnchorSet implements AnchorLocator {
 					count,
 				);
 			},
-			create(content: Delta.ProtoNodes, destination: FieldKey): void {
+			create(content: ITreeCursorSynchronous[], destination: FieldKey): void {
 				// Nothing to do since content can only be created in a new detached field,
 				// which cannot contain any anchors.
 			},
@@ -969,7 +995,7 @@ enum Status {
  * 2. refcount is non-zero.
  * 3. events are registered.
  */
-class PathNode extends ReferenceCountedBase implements UpPath<PathNode>, AnchorNode {
+class PathNode extends ReferenceCountedBase implements AnchorNode {
 	public status: Status = Status.Alive;
 	/**
 	 * Event emitter for this anchor.
@@ -992,6 +1018,11 @@ class PathNode extends ReferenceCountedBase implements UpPath<PathNode>, AnchorN
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	public readonly slots: BrandedMapSubset<AnchorSlot<any>> = new Map();
 
+	/**
+	 * {@inheritdoc UpPath.detachedNodeId}
+	 */
+	public detachedNodeId: Delta.DetachedNodeId | undefined;
+
 	/**
 	 * Construct a PathNode with refcount 1.
 	 * @param anchorSet - used to determine if this PathNode is already part of a specific anchorSet

package/src/core/tree/delta.ts

@@ -5,8 +5,7 @@
 
 import type { RevisionTag } from "../rebase/index.js";
 import type { FieldKey } from "../schema-stored/index.js";
-
-import type { ITreeCursorSynchronous } from "./cursor.js";
+import type { TreeChunk } from "./chunk.js";
 
 /**
  * This format describes changes that must be applied to a forest in order to update it.
@@ -70,7 +69,7 @@ import type { ITreeCursorSynchronous } from "./cursor.js";
  * Represents the change made to a document.
  * Immutable, therefore safe to retain for async processing.
  */
-export interface Root<TTree = ProtoNode> {
+export interface Root<TTrees = ProtoNodes> {
 	/**
 	 * Changes to apply to the root fields.
 	 */
@@ -83,7 +82,7 @@ export interface Root<TTree = ProtoNode> {
 	 * For example, if one wishes to build a tree which is being renamed from ID A to ID B,
 	 * then the build should be listed under ID A.
 	 */
-	readonly build?: readonly DetachedNodeBuild<TTree>[];
+	readonly build?: readonly DetachedNodeBuild<TTrees>[];
 	/**
 	 * New detached nodes to be destroyed.
 	 * The ordering has no significance.
@@ -97,7 +96,7 @@ export interface Root<TTree = ProtoNode> {
 	 * Refreshers for detached nodes that may need to be recreated.
 	 * The ordering has no significance.
 	 */
-	readonly refreshers?: readonly DetachedNodeBuild<TTree>[];
+	readonly refreshers?: readonly DetachedNodeBuild<TTrees>[];
 	/**
 	 * Changes to apply to detached nodes.
 	 * The ordering has no significance.
@@ -117,25 +116,9 @@ export interface Root<TTree = ProtoNode> {
 }
 
 /**
- * The default representation for inserted content.
- *
- * TODO:
- * Ownership and lifetime of data referenced by this cursor is unclear,
- * so it is a poor abstraction for this use-case which needs to hold onto the data in a non-exclusive (readonly) way.
- * Cursors can be one supported way to input data, but aren't a good storage format.
- */
-export type ProtoNode = ITreeCursorSynchronous;
-
-/**
- * The default representation a chunk (sub-sequence) of inserted content.
- *
- * TODO:
- * See issue TODO with ProtoNode.
- * Additionally, Cursors support sequences, so if using cursors, there are better ways to handle this than an array of cursors,
- * like using a cursor over all the content (starting in fields mode).
- * Long term something like TreeChunk should probably be used here.
+ * The default representation for a chunk (sub-sequence) of inserted content.
  */
-export type ProtoNodes = readonly ProtoNode[];
+export type ProtoNodes = TreeChunk;
 
 /**
  * Represents a change being made to a part of the document tree.
@@ -192,9 +175,9 @@ export interface DetachedNodeChanges {
  * Tree creation is idempotent: if a tree with the same ID already exists,
  * then this build is ignored in favor of the existing tree.
  */
-export interface DetachedNodeBuild<TTree = ProtoNode> {
+export interface DetachedNodeBuild<TTrees = ProtoNodes> {
 	readonly id: DetachedNodeId;
-	readonly trees: readonly TTree[];
+	readonly trees: TTrees;
 }
 
 /**

package/src/core/tree/deltaUtil.ts

@@ -5,12 +5,12 @@
 
 import type { Mutable } from "../../util/index.js";
 import type { FieldKey } from "../schema-stored/index.js";
+import type { TreeChunk } from "./chunk.js";
 
-import type { ITreeCursorSynchronous } from "./cursor.js";
 import type { DetachedNodeId, FieldChanges, Mark, Root } from "./delta.js";
 import { rootFieldKey } from "./types.js";
 
-export const emptyDelta: Root<never> = {};
+export const emptyDelta: Root = {};
 
 export function isAttachMark(mark: Mark): boolean {
 	return mark.attach !== undefined && mark.detach === undefined;
@@ -24,15 +24,15 @@ export function isReplaceMark(mark: Mark): boolean {
 	return mark.detach !== undefined && mark.attach !== undefined;
 }
 
-export function deltaForRootInitialization(content: readonly ITreeCursorSynchronous[]): Root {
-	if (content.length === 0) {
+export function deltaForRootInitialization(content: TreeChunk): Root {
+	if (content.topLevelLength === 0) {
 		return emptyDelta;
 	}
 	const buildId = { minor: 0 };
 	const delta: Root = {
 		build: [{ id: buildId, trees: content }],
 		fields: new Map<FieldKey, FieldChanges>([
-			[rootFieldKey, [{ count: content.length, attach: buildId }]],
+			[rootFieldKey, [{ count: content.topLevelLength, attach: buildId }]],
 		]),
 	};
 	return delta;

package/src/core/tree/index.ts

@@ -33,7 +33,6 @@ export {
 export type {
 	ProtoNodes,
 	Root as DeltaRoot,
-	ProtoNode as DeltaProtoNode,
 	Mark as DeltaMark,
 	DetachedNodeId as DeltaDetachedNodeId,
 	FieldMap as DeltaFieldMap,
@@ -49,6 +48,9 @@ export {
 	topDownPath,
 	getDepth,
 	type UpPath,
+	type NormalizedUpPath,
+	type INormalizedUpPath,
+	type NormalizedFieldUpPath,
 	type FieldUpPath,
 	type Range,
 	type RangeUpPath,
@@ -57,6 +59,7 @@ export {
 	type NodeIndex,
 	compareUpPaths,
 	compareFieldUpPaths,
+	isDetachedUpPathRoot as isDetachedUpPath,
 	getDetachedFieldContainingPath,
 	type UpPathDefault,
 } from "./pathTree.js";

package/src/core/tree/pathTree.ts

@@ -4,6 +4,7 @@
  */
 
 import type { FieldKey } from "../schema-stored/index.js";
+import type { DetachedNodeId } from "./delta.js";
 
 import { type DetachedField, keyAsDetachedField } from "./types.js";
 
@@ -41,12 +42,73 @@ export interface UpPath<TParent = UpPathDefault> {
 	readonly parentIndex: NodeIndex;
 }
 
+/**
+ * Identical to {@link INormalizedUpPath}, but a duplicate declaration is needed to make the default type parameter compile.
+ */
+export type INormalizedUpPathDefault = INormalizedUpPath;
+
+/**
+ * Identical to {@link UpPath}, but a with a {@link DetachedNodeId} to specify the ID of detached roots.
+ * Note that document roots (i.e., any node in the root field) are not considered detached roots and therefore do not have an associated ID.
+ *
+ * Use this interface for implementing a class that needs to be used as a {@link NormalizedUpPath}.
+ */
+export interface INormalizedUpPath<TParent = INormalizedUpPathDefault>
+	extends UpPath<TParent> {
+	readonly detachedNodeId: DetachedNodeId | undefined;
+}
+
+/**
+ * Identical to {@link UpPath}, but a with a {@link DetachedNodeId} to specify the ID of detached roots.
+ * Note that document roots (i.e., any node in the root field) are not considered detached roots and therefore do not have an associated ID.
+ *
+ * Prefer this type over {@link INormalizedUpPath} except when implementing a class that needs to be used as a {@link NormalizedUpPath}.
+ */
+export type NormalizedUpPath =
+	| INormalizedUpPath<NormalizedUpPath>
+	| NormalizedUpPathInterior<NormalizedUpPath>
+	| NormalizedUpPathRoot;
+
+/**
+ * The root element of a {@link NormalizedUpPath}.
+ */
+export interface NormalizedUpPathRoot extends UpPath<undefined> {
+	/**
+	 * The ID associated with this node if it is a detached root.
+	 */
+	readonly detachedNodeId: DetachedNodeId | undefined;
+}
+
+/**
+ * Identical to {@link NormalizedUpPathInterior}, but a duplicate declaration is needed to make the default type parameter compile.
+ */
+export type NormalizedUpPathInteriorDefault = NormalizedUpPathInterior;
+
+/**
+ * An interior (i.e., non-root) element of a {@link NormalizedUpPath}.
+ */
+export interface NormalizedUpPathInterior<
+	TParent = NormalizedUpPathInteriorDefault | NormalizedUpPathRoot,
+> extends UpPath<TParent> {
+	/**
+	 * The parent.
+	 */
+	readonly parent: TParent;
+}
+
 /**
  * Path from a field in the tree upward.
  *
  * See {@link UpPath}.
  */
-export interface FieldUpPath<TUpPath extends UpPath = UpPath> {
+export type NormalizedFieldUpPath<TParent = NormalizedUpPath> = FieldUpPath<TParent>;
+
+/**
+ * Path from a field in the tree upward.
+ *
+ * See {@link FieldUpPath} and {@link NormalizedUpPath}.
+ */
+export interface FieldUpPath<TUpPath = UpPath> {
 	/**
 	 * The parent, or undefined in the case where this path is to a detached sequence.
 	 */
@@ -59,6 +121,15 @@ export interface FieldUpPath<TUpPath extends UpPath = UpPath> {
 	readonly field: FieldKey; // TODO: Type information, including when in DetachedField.
 }
 
+/**
+ * Given an {@link UpPath}, checks if it is a path to a detached root.
+ */
+export function isDetachedUpPathRoot<T>(
+	path: UpPath<T> | NormalizedUpPath,
+): path is NormalizedUpPathRoot {
+	return (path as NormalizedUpPathRoot).detachedNodeId !== undefined;
+}
+
 /**
  * Delimits the extend of a range.
  */