@fluidframework/tree 2.41.0-338401 → 2.41.0

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

@@ -14,6 +14,7 @@ import {
 } from "../../core/index.js";
 import { brand, RangeMap, type Brand, type TupleBTree } from "../../util/index.js";
 import type { TreeChunk } from "../chunked-forest/index.js";
+
 import type { CrossFieldTarget } from "./crossFieldQueries.js";
 
 /**

package/src/feature-libraries/node-identifier/mockNodeIdentifierManager.ts

@@ -6,12 +6,15 @@
 import { assert, fail } from "@fluidframework/core-utils/internal";
 import type { SessionSpaceCompressedId, StableId } from "@fluidframework/id-compressor";
 import { assertIsStableId } from "@fluidframework/id-compressor/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+
+import { brand, extractFromOpaque } from "../../util/index.js";
+
 import type { LocalNodeIdentifier, StableNodeIdentifier } from "./nodeIdentifier.js";
 import {
 	isStableNodeIdentifier,
 	type NodeIdentifierManager,
 } from "./nodeIdentifierManager.js";
-import { brand, extractFromOpaque } from "../../util/index.js";
 
 /**
  * Mock {@link NodeIdentifierManager} that generates deterministic {@link StableNodeIdentifier}s and {@link LocalNodeIdentifier}s.
@@ -50,10 +53,13 @@ export class MockNodeIdentifierManager implements NodeIdentifierManager {
 	}
 
 	public getId(offset: number): StableId {
-		assert(offset >= 0, 0x6e7 /* UUID offset may not be negative */);
 		assert(offset < 281_474_976_710_656, 0x6e8 /* UUID offset must be at most 16^12 */);
-		return assertIsStableId(
-			`a110ca7e-add1-4000-8000-${Math.round(offset).toString(16).padStart(12, "0")}`,
-		);
+		if (offset >= 0 && offset < this.count) {
+			return assertIsStableId(
+				`a110ca7e-add1-4000-8000-${Math.round(offset).toString(16).padStart(12, "0")}`,
+			);
+		} else {
+			throw new UsageError("Local ID offset out of bounds");
+		}
 	}
 }

package/src/feature-libraries/object-forest/objectForest.ts

@@ -3,9 +3,9 @@
  * Licensed under the MIT License.
  */
 
-import { assert, fail } from "@fluidframework/core-utils/internal";
 import { createEmitter } from "@fluid-internal/client-utils";
 import type { Listenable } from "@fluidframework/core-interfaces";
+import { assert, fail } from "@fluidframework/core-utils/internal";
 
 import {
 	type Anchor,
@@ -29,6 +29,7 @@ import {
 	type PlaceIndex,
 	type Range,
 	type TreeChunk,
+	type TreeFieldStoredSchema,
 	TreeNavigationResult,
 	type TreeNodeSchemaIdentifier,
 	type TreeStoredSchemaSubscription,
@@ -37,16 +38,26 @@ import {
 	aboveRootPlaceholder,
 	combineVisitors,
 	deepCopyMapTree,
+	rootFieldKey,
 } from "../../core/index.js";
 import {
 	assertNonNegativeSafeInteger,
 	assertValidIndex,
 	assertValidRange,
 	brand,
+	breakingMethod,
+	type Breakable,
+	type WithBreakable,
 } from "../../util/index.js";
+import { chunkFieldSingle, defaultChunkPolicy } from "../chunked-forest/index.js";
 import { cursorForMapTreeNode, mapTreeFromCursor } from "../mapTreeCursor.js";
 import { type CursorWithNode, SynchronousCursor } from "../treeCursorUtils.js";
-import { chunkFieldSingle, defaultChunkPolicy } from "../chunked-forest/index.js";
+import {
+	defaultSchemaPolicy,
+	FieldKinds,
+	inSchemaOrThrow,
+	isFieldInSchema,
+} from "../default-schema/index.js";
 
 /** A `MapTree` with mutable fields */
 interface MutableMapTree extends MapTree {
@@ -71,7 +82,7 @@ function getOrCreateField(mapTree: MutableMapTree, key: FieldKey): MutableMapTre
  * This implementation focuses on correctness and simplicity, not performance.
  * It does not use compressed chunks: instead nodes are implemented using objects.
  */
-export class ObjectForest implements IEditableForest {
+export class ObjectForest implements IEditableForest, WithBreakable {
 	private activeVisitor?: DeltaVisitor;
 
 	// All cursors that are in the "Current" state. Must be empty when editing.
@@ -87,6 +98,11 @@ export class ObjectForest implements IEditableForest {
 	}
 
 	public constructor(
+		public readonly breaker: Breakable,
+		/**
+		 * If provided, may be used for validation, but otherwise unused.
+		 */
+		public readonly schema: TreeStoredSchemaSubscription | undefined,
 		public readonly anchors: AnchorSet = new AnchorSet(),
 		public readonly additionalAsserts: boolean = false,
 		roots?: MapTree,
@@ -98,14 +114,18 @@ export class ObjectForest implements IEditableForest {
 						type: aboveRootPlaceholder,
 						fields: new Map(),
 					};
+
+		if (additionalAsserts) {
+			this.checkSchema();
+		}
 	}
 
 	public get isEmpty(): boolean {
 		return this.roots.fields.size === 0;
 	}
 
-	public clone(_: TreeStoredSchemaSubscription, anchors: AnchorSet): ObjectForest {
-		return new ObjectForest(anchors, this.additionalAsserts, this.roots);
+	public clone(schema: TreeStoredSchemaSubscription, anchors: AnchorSet): ObjectForest {
+		return new ObjectForest(this.breaker, schema, anchors, this.additionalAsserts, this.roots);
 	}
 
 	public chunkField(cursor: ITreeCursorSynchronous): TreeChunk {
@@ -116,6 +136,34 @@ export class ObjectForest implements IEditableForest {
 		this.anchors.forget(anchor);
 	}
 
+	/**
+	 * Throw (and break) if content does not match schema.
+	 */
+	@breakingMethod
+	public checkSchema(): void {
+		const schema = this.schema;
+		if (schema !== undefined) {
+			const roots = new Set([...this.roots.fields.keys(), rootFieldKey]);
+			for (const key of roots) {
+				const documentRoot = this.roots.fields.get(key) ?? [];
+				const fieldSchema: TreeFieldStoredSchema =
+					key === rootFieldKey
+						? schema.rootFieldSchema
+						: // TODO: someday we should have schema for detached fields, and use that instead of generating one here.
+							{
+								// Some detached fields may have multiple nodes, so we must treat them as sequences:
+								kind: FieldKinds.sequence.identifier,
+								types: new Set(documentRoot.map((node) => node.type)),
+							};
+				const maybeError = isFieldInSchema(documentRoot, fieldSchema, {
+					schema,
+					policy: defaultSchemaPolicy,
+				});
+				inSchemaOrThrow(maybeError);
+			}
+		}
+	}
+
 	public acquireVisitor(): DeltaVisitor {
 		assert(
 			this.activeVisitor === undefined,
@@ -163,6 +211,11 @@ export class ObjectForest implements IEditableForest {
 					0x76d /* Multiple free calls for same visitor */,
 				);
 				this.forest.activeVisitor = undefined;
+				if (this.forest.additionalAsserts) {
+					// Schema validation:
+					// When doing "additionalAsserts", validate the content against the schema after every batch of edits.
+					this.forest.checkSchema();
+				}
 			}
 			public destroy(detachedField: FieldKey, count: number): void {
 				preEdit();
@@ -542,11 +595,16 @@ class Cursor extends SynchronousCursor implements ITreeSubscriptionCursor {
 // When other forest implementations are created (ex: optimized ones),
 // this function should likely be moved and updated to (at least conditionally) use them.
 /**
- * @returns an implementation of {@link IEditableForest} with no data or schema.
+ * Returns an implementation of {@link IEditableForest} with no content.
+ * @privateRemarks
+ * TODO:
+ * refactor to remove this function, and instead place `ForestTypeReference` and `ForestTypeExpensiveDebug` here as a better way to encapsulate ObjectForest.
  */
 export function buildForest(
+	breaker: Breakable,
+	schema?: TreeStoredSchemaSubscription,
 	anchors?: AnchorSet,
 	additionalAsserts: boolean = false,
 ): ObjectForest {
-	return new ObjectForest(anchors, additionalAsserts);
+	return new ObjectForest(breaker, schema, anchors, additionalAsserts);
 }

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

@@ -13,14 +13,11 @@ import {
 	makeVersionDispatchingCodec,
 	withSchemaValidation,
 } from "../../codec/index.js";
-import {
-	makeSchemaCodec,
-	SchemaCodecVersion,
-	type Format as FormatV1,
-} from "../schema-index/index.js";
+import { makeSchemaCodec, type Format as FormatV1 } from "../schema-index/index.js";
 
 import { EncodedSchemaChange } from "./schemaChangeFormat.js";
 import type { SchemaChange } from "./schemaChangeTypes.js";
+import { SchemaVersion } from "../../core/index.js";
 
 /**
  * Create a family of schema change codecs.
@@ -28,7 +25,7 @@ import type { SchemaChange } from "./schemaChangeTypes.js";
  * @returns The composed codec family.
  */
 export function makeSchemaChangeCodecs(options: ICodecOptions): ICodecFamily<SchemaChange> {
-	return makeCodecFamily([[SchemaCodecVersion.v1, makeSchemaChangeCodecV1(options)]]);
+	return makeCodecFamily([[SchemaVersion.v1, makeSchemaChangeCodecV1(options)]]);
 }
 
 /**
@@ -39,7 +36,7 @@ export function makeSchemaChangeCodecs(options: ICodecOptions): ICodecFamily<Sch
  */
 export function makeSchemaChangeCodec(
 	options: ICodecOptions,
-	writeVersion: SchemaCodecVersion,
+	writeVersion: SchemaVersion,
 ): IJsonCodec<SchemaChange> {
 	const family = makeSchemaChangeCodecs(options);
 	return makeVersionDispatchingCodec(family, { ...options, writeVersion });
@@ -53,7 +50,7 @@ export function makeSchemaChangeCodec(
 function makeSchemaChangeCodecV1(
 	options: ICodecOptions,
 ): IJsonCodec<SchemaChange, EncodedSchemaChange> {
-	const schemaCodec = makeSchemaCodec(options, SchemaCodecVersion.v1);
+	const schemaCodec = makeSchemaCodec(options, SchemaVersion.v1);
 	const schemaChangeCodec: IJsonCodec<SchemaChange, EncodedSchemaChange> = {
 		encode: (schemaChange) => {
 			assert(

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

@@ -4,6 +4,7 @@
  */
 
 import { fail, unreachableCase } from "@fluidframework/core-utils/internal";
+
 import {
 	type FluidClientVersion,
 	type ICodecFamily,
@@ -14,12 +15,13 @@ import {
 	makeVersionedValidatedCodec,
 } from "../../codec/index.js";
 import {
+	SchemaVersion,
 	type TreeNodeSchemaIdentifier,
 	type TreeNodeStoredSchema,
 	type TreeStoredSchema,
 	decodeFieldSchema,
 	encodeFieldSchema,
-	schemaFormatV1,
+	type schemaFormatV1,
 	storedSchemaDecodeDispatcher,
 } from "../../core/index.js";
 import { brand, type JsonCompatible } from "../../util/index.js";
@@ -27,22 +29,15 @@ import { brand, type JsonCompatible } from "../../util/index.js";
 import { Format as FormatV1 } from "./formatV1.js";
 
 /**
- * Versions for the codec that encodes an in-memory representation of a stored schema {@link TreeStoredSchema} into a persisted format (or decodes it in the opposite direction).
- */
-export enum SchemaCodecVersion {
-	v1 = 1,
-}
-
-/**
- * Convert a FluidClientVersion to a SchemaCodecVersion.
+ * Convert a FluidClientVersion to a SchemaVersion.
  * @param clientVersion - The FluidClientVersion to convert.
- * @returns The SchemaCodecVersion that corresponds to the provided FluidClientVersion.
+ * @returns The SchemaVersion that corresponds to the provided FluidClientVersion.
  */
 export function clientVersionToSchemaVersion(
 	clientVersion: FluidClientVersion,
-): SchemaCodecVersion {
+): SchemaVersion {
 	// Only one version of the schema codec is currently supported.
-	return SchemaCodecVersion.v1;
+	return SchemaVersion.v1;
 }
 
 /**
@@ -55,7 +50,7 @@ export function clientVersionToSchemaVersion(
  */
 export function makeSchemaCodec(
 	options: ICodecOptions,
-	writeVersion: SchemaCodecVersion,
+	writeVersion: SchemaVersion,
 ): IJsonCodec<TreeStoredSchema> {
 	const family = makeSchemaCodecs(options);
 	return makeVersionDispatchingCodec(family, { ...options, writeVersion });
@@ -67,7 +62,7 @@ export function makeSchemaCodec(
  * @returns The composed codec family.
  */
 export function makeSchemaCodecs(options: ICodecOptions): ICodecFamily<TreeStoredSchema> {
-	return makeCodecFamily([[SchemaCodecVersion.v1, makeSchemaCodecV1(options)]]);
+	return makeCodecFamily([[SchemaVersion.v1, makeSchemaCodecV1(options)]]);
 }
 
 /**
@@ -76,12 +71,9 @@ export function makeSchemaCodecs(options: ICodecOptions): ICodecFamily<TreeStore
  * @param version - The schema write version.
  * @returns The encoded schema.
  */
-export function encodeRepo(
-	repo: TreeStoredSchema,
-	version: SchemaCodecVersion,
-): JsonCompatible {
+export function encodeRepo(repo: TreeStoredSchema, version: SchemaVersion): JsonCompatible {
 	switch (version) {
-		case SchemaCodecVersion.v1:
+		case SchemaVersion.v1:
 			return encodeRepoV1(repo);
 		default:
 			unreachableCase(version);
@@ -102,7 +94,7 @@ function encodeRepoV1(repo: TreeStoredSchema): FormatV1 {
 		});
 	}
 	return {
-		version: schemaFormatV1.version,
+		version: SchemaVersion.v1,
 		nodes: nodeSchema,
 		root: rootFieldSchema,
 	};
@@ -125,7 +117,7 @@ function decode(f: FormatV1): TreeStoredSchema {
  * @returns The codec.
  */
 function makeSchemaCodecV1(options: ICodecOptions): IJsonCodec<TreeStoredSchema, FormatV1> {
-	return makeVersionedValidatedCodec(options, new Set([schemaFormatV1.version]), FormatV1, {
+	return makeVersionedValidatedCodec(options, new Set([SchemaVersion.v1]), FormatV1, {
 		encode: (data: TreeStoredSchema) => encodeRepoV1(data),
 		decode: (data: FormatV1) => decode(data),
 	});

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

@@ -5,7 +5,7 @@
 
 import { type ObjectOptions, type Static, Type } from "@sinclair/typebox";
 
-import { schemaFormatV1 } from "../../core/index.js";
+import { SchemaVersion, schemaFormatV1 } from "../../core/index.js";
 
 const noAdditionalProps: ObjectOptions = { additionalProperties: false };
 
@@ -21,7 +21,7 @@ const noAdditionalProps: ObjectOptions = { additionalProperties: false };
  */
 export const Format = Type.Object(
 	{
-		version: Type.Literal(schemaFormatV1.version),
+		version: Type.Literal(SchemaVersion.v1),
 		nodes: Type.Record(Type.String(), schemaFormatV1.TreeNodeSchemaDataFormat),
 		root: schemaFormatV1.FieldSchemaFormat,
 	},

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

@@ -7,7 +7,6 @@ export { SchemaSummarizer, encodeTreeSchema } from "./schemaSummarizer.js";
 export {
 	makeSchemaCodec,
 	makeSchemaCodecs,
-	SchemaCodecVersion,
 	clientVersionToSchemaVersion,
 } from "./codec.js";
 export { Format } from "./formatV1.js";

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

@@ -25,10 +25,10 @@ import type {
 	SummaryElementParser,
 	SummaryElementStringifier,
 } from "../../shared-tree-core/index.js";
+import type { JsonCompatible } from "../../util/index.js";
 import type { CollabWindow } from "../incrementalSummarizationUtils.js";
 
 import { encodeRepo } from "./codec.js";
-import type { JsonCompatible } from "../../util/index.js";
 
 const schemaStringKey = "SchemaString";
 /**

package/src/feature-libraries/sequence-field/formatV3.ts

@@ -6,6 +6,7 @@
 import { type ObjectOptions, type Static, type TSchema, Type } from "@sinclair/typebox";
 
 import { unionOptions } from "../../codec/index.js";
+
 import {
 	CellId,
 	CellMark,

package/src/feature-libraries/sequence-field/markQueue.ts

@@ -4,6 +4,7 @@
  */
 
 import { assert, oob } from "@fluidframework/core-utils/internal";
+
 import { type MoveEffectTable, splitMarkForMoveEffects } from "./moveEffectTable.js";
 import type { Mark } from "./types.js";
 import { splitMark } from "./utils.js";

package/src/feature-libraries/sequence-field/prune.ts

@@ -4,6 +4,7 @@
  */
 
 import type { NodeChangePruner } from "../modular-schema/index.js";
+
 import { MarkListFactory } from "./markListFactory.js";
 import type { Changeset } from "./types.js";
 import { withNodeChange } from "./utils.js";

package/src/feature-libraries/sequence-field/rebase.ts

@@ -344,7 +344,7 @@ function rebaseMarkIgnoreChild(
 }
 
 /**
- * @returns A pair of marks that represent the effects which should remain in place in the face of concurrent move,
+ * Returns a pair of marks that represent the effects which should remain in place in the face of concurrent move,
  * and the effects that should be sent to the move destination.
  */
 function separateEffectsForMove(mark: MarkEffect): {

package/src/feature-libraries/sequence-field/relevantRemovedRoots.ts

@@ -7,10 +7,10 @@ import { assert } from "@fluidframework/core-utils/internal";
 
 import { type DeltaDetachedNodeId, offsetDetachId } from "../../core/index.js";
 import { nodeIdFromChangeAtom } from "../deltaUtils.js";
+import type { RelevantRemovedRootsFromChild } from "../modular-schema/index.js";
 
 import type { Changeset, Mark } from "./types.js";
 import { isAttachAndDetachEffect, isDetachOfRemovedNodes, isInsert } from "./utils.js";
-import type { RelevantRemovedRootsFromChild } from "../modular-schema/index.js";
 
 export function* relevantRemovedRoots(
 	change: Changeset,

package/src/feature-libraries/sequence-field/replaceRevisions.ts

@@ -4,7 +4,10 @@
  */
 
 import { unreachableCase } from "@fluidframework/core-utils/internal";
+
 import { type RevisionTag, replaceAtomRevisions } from "../../core/index.js";
+
+import type { MoveMarkEffect } from "./helperTypes.js";
 import { MarkListFactory } from "./markListFactory.js";
 import {
 	type Changeset,
@@ -16,7 +19,6 @@ import {
 	NoopMarkType,
 	type Rename,
 } from "./types.js";
-import type { MoveMarkEffect } from "./helperTypes.js";
 import { isDetach, isRename } from "./utils.js";
 
 export function replaceRevisions(

package/src/feature-libraries/sequence-field/sequenceFieldCodecV1.ts

@@ -15,6 +15,8 @@ import type {
 } from "../../core/index.js";
 import { type JsonCompatibleReadOnly, type Mutable, brand } from "../../util/index.js";
 import { makeChangeAtomIdCodec } from "../changeAtomIdCodec.js";
+import type { FieldChangeEncodingContext } from "../index.js";
+import { EncodedNodeChangeset } from "../modular-schema/index.js";
 
 import {
 	Changeset as ChangesetSchema,
@@ -37,8 +39,6 @@ import {
 	type Rename,
 } from "./types.js";
 import { isNoopMark, normalizeCellRename } from "./utils.js";
-import type { FieldChangeEncodingContext } from "../index.js";
-import { EncodedNodeChangeset } from "../modular-schema/index.js";
 
 export function makeV1Codec(
 	revisionTagCodec: IJsonCodec<

package/src/feature-libraries/sequence-field/sequenceFieldCodecV2.ts

@@ -19,8 +19,11 @@ import type {
 } from "../../core/index.js";
 import { type JsonCompatibleReadOnly, type Mutable, brand } from "../../util/index.js";
 import { makeChangeAtomIdCodec } from "../changeAtomIdCodec.js";
+import type { FieldChangeEncodingContext } from "../index.js";
+import { EncodedNodeChangeset } from "../modular-schema/index.js";
 
 import { Changeset as ChangesetSchema, type Encoded } from "./formatV2.js";
+import type { SequenceCodecHelpers } from "./helperTypes.js";
 import {
 	type Attach,
 	type AttachAndDetach,
@@ -36,9 +39,6 @@ import {
 	type Rename,
 } from "./types.js";
 import { isNoopMark, normalizeCellRename } from "./utils.js";
-import type { FieldChangeEncodingContext } from "../index.js";
-import { EncodedNodeChangeset } from "../modular-schema/index.js";
-import type { SequenceCodecHelpers } from "./helperTypes.js";
 
 export function makeV2CodecHelpers(
 	revisionTagCodec: IJsonCodec<

package/src/feature-libraries/sequence-field/sequenceFieldCodecV3.ts

@@ -12,13 +12,13 @@ import type {
 	RevisionTag,
 } from "../../core/index.js";
 import type { JsonCompatibleReadOnly } from "../../util/index.js";
+import type { FieldChangeEncodingContext } from "../index.js";
+import { EncodedNodeChangeset } from "../modular-schema/index.js";
 
 import { Changeset as ChangesetSchema, type Encoded } from "./formatV3.js";
+import { makeV2CodecHelpers } from "./sequenceFieldCodecV2.js";
 import type { Changeset, Mark, MarkEffect, Rename } from "./types.js";
 import { isNoopMark } from "./utils.js";
-import type { FieldChangeEncodingContext } from "../index.js";
-import { EncodedNodeChangeset } from "../modular-schema/index.js";
-import { makeV2CodecHelpers } from "./sequenceFieldCodecV2.js";
 
 export function makeV3Codec(
 	revisionTagCodec: IJsonCodec<

package/src/feature-libraries/sequence-field/sequenceFieldCodecs.ts

@@ -9,12 +9,12 @@ import type {
 	EncodedRevisionTag,
 	RevisionTag,
 } from "../../core/index.js";
-
-import type { Changeset, MarkList } from "./types.js";
 import type { FieldChangeEncodingContext } from "../index.js";
+
 import { makeV1Codec } from "./sequenceFieldCodecV1.js";
 import { makeV2Codec } from "./sequenceFieldCodecV2.js";
 import { makeV3Codec } from "./sequenceFieldCodecV3.js";
+import type { Changeset, MarkList } from "./types.js";
 
 export const sequenceFieldChangeCodecFactory = (
 	revisionTagCodec: IJsonCodec<

package/src/feature-libraries/sequence-field/sequenceFieldToDelta.ts

@@ -13,6 +13,7 @@ import {
 } from "../../core/index.js";
 import { getLast, hasSome, type Mutable } from "../../util/index.js";
 import { nodeIdFromChangeAtom } from "../deltaUtils.js";
+import type { FieldChangeDelta, ToDelta } from "../modular-schema/index.js";
 
 import { isMoveIn, isMoveOut } from "./moveEffectTable.js";
 import { type MarkList, NoopMarkType } from "./types.js";
@@ -24,7 +25,6 @@ import {
 	getInputCellId,
 	isAttachAndDetachEffect,
 } from "./utils.js";
-import type { FieldChangeDelta, ToDelta } from "../modular-schema/index.js";
 
 export function sequenceFieldToDelta(
 	change: MarkList,

package/src/feature-libraries/sequence-field/utils.ts

@@ -289,7 +289,7 @@ export function compareCellPositionsUsingTombstones(
 }
 
 /**
- * @returns the ID of the cell in the output context of the given detach `mark`.
+ * Gets the ID of the cell in the output context of the given detach `mark`.
  */
 export function getDetachOutputCellId(mark: Detach | Rename): ChangeAtomId {
 	if (isRename(mark)) {
@@ -304,7 +304,7 @@ export function getDetachOutputCellId(mark: Detach | Rename): ChangeAtomId {
 }
 
 /**
- * @returns the ID of the detached node in the output context of the given detach `mark`.
+ * Gets the ID of the detached node in the output context of the given detach `mark`.
  */
 export function getDetachedNodeId(mark: Detach | Rename): ChangeAtomId {
 	switch (mark.type) {
@@ -413,18 +413,18 @@ export function cloneCellId(id: CellId): CellId {
 }
 
 /**
+ * Gets the number of nodes within the output context of the mark.
  * @param mark - The mark to get the length of.
  * @param ignorePairing - When true, the length of a paired mark (e.g. MoveIn/MoveOut) whose matching mark is not active
  * will be treated the same as if the matching mark were active.
- * @returns The number of nodes within the output context of the mark.
  */
 export function getOutputLength(mark: Mark, ignorePairing: boolean = false): number {
 	return areOutputCellsEmpty(mark) ? 0 : mark.count;
 }
 
 /**
+ * Gets the number of nodes within the input context of the mark.
  * @param mark - The mark to get the length of.
- * @returns The number of nodes within the input context of the mark.
  */
 export function getInputLength(mark: Mark): number {
 	return areInputCellsEmpty(mark) ? 0 : mark.count;
@@ -491,7 +491,9 @@ export function settleMark(mark: Mark): Mark {
 }
 
 /**
- * @returns true, iff the given `mark` would have impact on the field when applied.
+ * Returns true if and only iff the given `mark` would have impact on the field when applied.
+ *
+ * @remarks
  * Ignores the impact of nested changes.
  * CellRename effects are considered impactful if they actually change the ID of the cells.
  */

package/src/feature-libraries/treeCursorUtils.ts

@@ -372,14 +372,14 @@ class StackCursor<TNode> extends SynchronousCursor implements CursorWithNode<TNo
 	}
 
 	/**
-	 * @returns the value of the current node
+	 * The value of the current node
 	 */
 	public get value(): Value {
 		return this.adapter.value(this.getNode());
 	}
 
 	/**
-	 * @returns the type of the current node
+	 * The type of the current node
 	 */
 	public get type(): TreeType {
 		return this.adapter.type(this.getNode());

package/src/feature-libraries/treeTextCursor.ts

@@ -66,7 +66,7 @@ export function cursorForJsonableTreeNode(root: JsonableTree): ITreeCursorSynchr
 }
 
 /**
- * @returns an {@link ITreeCursorSynchronous} in fields mode for a JsonableTree field.
+ * Creates an {@link ITreeCursorSynchronous} in fields mode for a JsonableTree field.
  */
 export function cursorForJsonableTreeField(
 	trees: JsonableTree[],

package/src/index.ts

@@ -69,6 +69,7 @@ export {
 	independentInitializedView,
 	type ViewContent,
 	TreeAlpha,
+	type TreeIdentifierUtils,
 	independentView,
 	ForestTypeOptimized,
 	ForestTypeExpensiveDebug,
@@ -166,10 +167,6 @@ export {
 	type UnannotateAllowedTypeOrLazyItem,
 	type UnannotateImplicitFieldSchema,
 	type UnannotateSchemaRecord,
-	// test recursive schema for checking that d.ts files handles schema correctly
-	test_RecursiveObject,
-	test_RecursiveObject_base,
-	test_RecursiveObjectPojoMode,
 	// Beta APIs
 	TreeBeta,
 	type TreeChangeEventsBeta,

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.41.0-338401";
+export const pkgVersion = "2.41.0";

package/src/shared-tree/checkoutFlexTreeView.ts

@@ -4,6 +4,7 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
+
 import {
 	Context,
 	type FlexTreeField,