@fluidframework/tree 2.117.0 → 3.0.0

package/src/shared-tree/treeAlpha.ts

@@ -42,7 +42,6 @@ import {
 	getKernel,
 	TreeNode,
 	type Unhydrated,
-	TreeBeta,
 	tryGetSchema,
 	createFromCursor,
 	FieldKind,
@@ -75,11 +74,8 @@ import {
 	toInitialSchema,
 	type TreeParsingOptions,
 	type NodeChangedData,
-	type TreeChangeEventsAlpha,
+	type TreeChangeEventsBeta,
 	type ConciseTree,
-	importConcise,
-	exportConcise,
-	borrowCursorFromTreeNodeOrValue,
 	contentSchemaSymbol,
 	type TreeContextAlpha,
 	type TreeNodeSchema,
@@ -88,7 +84,13 @@ import {
 import { brand, extractFromOpaque, type JsonCompatible } from "../util/index.js";
 
 import { independentInitializedView, type ViewContent } from "./independentView.js";
-import { SchematizingSimpleTreeView, ViewSlot } from "./schematizingTreeView.js";
+import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
+import {
+	borrowCursorFromTreeNodeOrValue,
+	exportConcise,
+	importConcise,
+	TreeBeta,
+} from "./treeBeta.js";
 import { UnhydratedTreeContext } from "./unhydratedTreeContext.js";
 
 const identifier: TreeIdentifierUtils = (node: TreeNode): string | undefined => {
@@ -232,24 +234,13 @@ export interface TreeIdentifierUtils {
  */
 export interface TreeAlpha {
 	/**
-	 * Register an event listener on the given node.
-	 * @param node - The node whose events should be subscribed to.
-	 * @param eventName - Which event to subscribe to.
-	 * @param listener - The callback to trigger for the event. The tree can be read during the callback, but it is invalid to modify the tree during this callback.
-	 * @returns A callback function which will deregister the event.
-	 * This callback should be called only once.
-	 * @remarks
-	 * Provides richer events than {@link (TreeBeta:interface).on} for array nodes:
-	 * - `nodeChanged` includes a {@link NodeChangedDataDelta.delta | delta} payload for direct
-	 * changes (insert, remove, move).
-	 * - `treeChanged` also includes a {@link NodeChangedDataDelta.delta | delta} payload and fires
-	 * for both shallow changes and deep changes (e.g. a property of an element changed without
-	 * any direct array change).
+	 * {@inheritDoc (TreeBeta:interface).on}
+	 * @deprecated Use {@link (TreeBeta:interface).on} instead.
 	 */
-	on<K extends keyof TreeChangeEventsAlpha<TNode>, TNode extends TreeNode>(
+	on<K extends keyof TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(
 		node: TNode,
 		eventName: K,
-		listener: NoInfer<TreeChangeEventsAlpha<TNode>[K]>,
+		listener: NoInfer<TreeChangeEventsBeta<TNode>[K]>,
 	): () => void;
 
 	/**
@@ -371,7 +362,7 @@ export interface TreeAlpha {
 	 * @param options - If {@link (TreeAlpha:interface).exportCompressed} was given an `idCompressor`, it must be provided here.
 	 *
 	 * @remarks
-	 * If the data could have been encoded with a different schema, consider encoding the schema along side it using {@link extractPersistedSchema} and loading the data using {@link independentView}.
+	 * If the data could have been encoded with a different schema, consider encoding the schema along side it using {@link extractPersistedSchema} and loading the data using {@link createIndependentTreeViewAlpha}.
 	 *
 	 * @privateRemarks
 	 * This API could be improved:
@@ -795,12 +786,12 @@ function trackObservations<TResult>(
  * @alpha
  */
 export const TreeAlpha: TreeAlpha = {
-	on<K extends keyof TreeChangeEventsAlpha<TNode>, TNode extends TreeNode>(
+	on<K extends keyof TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(
 		node: TNode,
 		eventName: K,
-		listener: NoInfer<TreeChangeEventsAlpha<TNode>[K]>,
+		listener: NoInfer<TreeChangeEventsBeta<TNode>[K]>,
 	): () => void {
-		return treeNodeApi.on(node, eventName, listener);
+		return TreeBeta.on(node, eventName, listener);
 	},
 
 	trackObservations<TResult>(
@@ -832,12 +823,7 @@ export const TreeAlpha: TreeAlpha = {
 		if (!kernel.isHydrated()) {
 			return UnhydratedTreeContext.instance;
 		}
-		const view = kernel.anchorNode.anchorSet.slots.get(ViewSlot);
-		assert(
-			view instanceof SchematizingSimpleTreeView,
-			0xa5c /* Unexpected view implementation */,
-		);
-		return view;
+		return TreeBeta.context(node) as TreeContextAlpha;
 	},
 
 	create<const TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(

package/src/{simple-tree/api → shared-tree}/treeBeta.ts

@@ -3,121 +3,42 @@
  * Licensed under the MIT License.
  */
 
-import type { ITreeCursorSynchronous, TreeFieldStoredSchema } from "../../core/index.js";
-import {
-	defaultSchemaPolicy,
-	FieldKinds,
-	isTreeValue,
-} from "../../feature-libraries/index.js";
-import { brand } from "../../util/index.js";
+import { assert } from "@fluidframework/core-utils/internal";
+
+import type { ITreeCursorSynchronous } from "../core/index.js";
+import { isTreeValue } from "../feature-libraries/index.js";
 import {
-	Context,
+	cloneTree,
+	conciseFromCursor,
+	cursorFromVerbose,
 	getKernel,
 	getOrCreateNodeFromInnerNode,
 	isTreeNode,
-	UnhydratedContext,
-	type NodeKind,
+	treeNodeApi,
+	unhydratedFlexTreeFromInsertable,
+	type ConciseTree,
+	type ImplicitFieldSchema,
+	type InsertableContent,
+	type InsertableField,
+	type InsertableTreeFieldFromImplicitField,
+	// eslint-disable-next-line @typescript-eslint/no-unused-vars -- Used by docs
+	type ObjectSchemaOptions,
+	type TreeChangeEventsBeta,
+	type TreeContextBeta,
+	type TreeEncodingOptions,
+	type TreeFieldFromImplicitField,
 	type TreeLeafValue,
 	type TreeNode,
 	type Unhydrated,
-	type WithType,
-} from "../core/index.js";
-import { getUnhydratedContext } from "../createContext.js";
-import type {
-	ImplicitFieldSchema,
-	InsertableTreeFieldFromImplicitField,
-	TreeFieldFromImplicitField,
-} from "../fieldSchema.js";
-import {
-	unhydratedFlexTreeFromInsertable,
-	type InsertableContent,
-} from "../unhydratedFlexTreeFromInsertable.js";
-import type { InsertableField, UnsafeUnknownSchema } from "../unsafeUnknownSchema.js";
+	type UnsafeUnknownSchema,
+} from "../simple-tree/index.js";
 
-import { conciseFromCursor, type ConciseTree } from "./conciseTree.js";
-import { createFromCursor } from "./create.js";
-import type { TreeEncodingOptions } from "./customTree.js";
-// eslint-disable-next-line @typescript-eslint/no-unused-vars -- Used by docs
-import type { ObjectSchemaOptions } from "./schemaFactory.js";
-import type { TreeChangeEvents } from "./treeChangeEvents.js";
-import { treeNodeApi } from "./treeNodeApi.js";
-import { cursorFromVerbose } from "./verboseTree.js";
+import { ViewSlot } from "./schematizingTreeView.js";
+import { UnhydratedTreeContext } from "./unhydratedTreeContext.js";
 
 // Tests for this file are grouped with those for treeNodeApi.ts as that is where this functionality will eventually land,
 // and where most of the actual implementation is for much of it.
 
-/**
- * Data included for {@link TreeChangeEventsBeta.nodeChanged}.
- * @sealed @beta
- */
-export interface NodeChangedData<TNode extends TreeNode = TreeNode> {
-	/**
-	 * When the node changed is an object or Map node, this lists all the properties which changed.
-	 * @remarks
-	 * This only includes changes to the node itself (which would trigger {@link TreeChangeEvents.nodeChanged}).
-	 *
-	 * Not present when the {@link NodeKind} does not support this feature (currently just ArrayNodes).
-	 *
-	 * When defined, the set should never be empty, since `nodeChanged` will only be triggered when there is a change, and for the supported node types, the only things that can change are properties.
-	 */
-	readonly changedProperties?: ReadonlySet<
-		// For Object nodes, make changedProperties required and strongly typed with the property names from the schema:
-		TNode extends WithType<string, NodeKind.Object, infer TInfo>
-			? string & keyof TInfo
-			: string
-	>;
-}
-
-/**
- * Extensions to {@link TreeChangeEvents} which are not yet stable.
- *
- * @sealed @beta
- */
-export interface TreeChangeEventsBeta<TNode extends TreeNode = TreeNode>
-	extends TreeChangeEvents {
-	/**
-	 * Emitted by a node after a batch of changes has been applied to the tree, if any of the changes affected the node.
-	 *
-	 * - Object nodes define a change as being when the value of one of its properties changes (i.e., the property's value is set, including when set to `undefined`).
-	 *
-	 * - Array nodes define a change as when an element is added, removed, moved or replaced.
-	 *
-	 * - Map nodes define a change as when an entry is added, updated, or removed.
-	 *
-	 * @remarks
-	 * This event is not emitted when:
-	 *
-	 * - Properties of a child node change. Notably, updates to an array node or a map node (like adding or removing
-	 * elements/entries) will emit this event on the array/map node itself, but not on the node that contains the
-	 * array/map node as one of its properties.
-	 *
-	 * - The node is moved to a different location in the tree or removed from the tree.
-	 * In this case the event is emitted on the _parent_ node, not the node itself.
-	 *
-	 * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in
-	 * the client that made the original edit.
-	 *
-	 * When the event is emitted, the tree is guaranteed to be in-schema.
-	 *
-	 * @privateRemarks
-	 * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.
-	 * For example, it will fire when the local client reassigns a child, when part of a remote edit is applied to the
-	 * node, or when the node has to be updated due to resolution of a merge conflict
-	 * (for example a previously applied local change might be undone, then reapplied differently or not at all).
-	 *
-	 * TODO: define and document event ordering (ex: bottom up, with nodeChanged before treeChange on each level).
-	 *
-	 * This defines a property which is a function instead of using the method syntax to avoid function bi-variance issues with the input data to the callback.
-	 */
-	nodeChanged: (
-		data: NodeChangedData<TNode> &
-			// Make the properties of object, map, and record nodes required:
-			(TNode extends WithType<string, NodeKind.Map | NodeKind.Object | NodeKind.Record>
-				? Required<Pick<NodeChangedData<TNode>, "changedProperties">>
-				: unknown),
-	) => void;
-}
-
 /**
  * Extensions to {@link (Tree:interface)} which are not yet stable.
  * @remarks
@@ -125,6 +46,13 @@ export interface TreeChangeEventsBeta<TNode extends TreeNode = TreeNode>
  * @sealed @beta
  */
 export interface TreeBeta {
+	/**
+	 * Retrieve the {@link TreeContextBeta | context} for the given node.
+	 * @param node - The node to query.
+	 * @returns The {@link TreeContextBeta} associated with `node`.
+	 */
+	context(node: TreeNode): TreeContextBeta;
+
 	/**
 	 * Register an event listener on the given node.
 	 * @param node - The node whose events should be subscribed to.
@@ -194,25 +122,6 @@ export interface TreeBeta {
 		node: TreeFieldFromImplicitField<TSchema>,
 	): TreeFieldFromImplicitField<TSchema>;
 
-	// TODO: support more clone options
-	// /**
-	//  * Like {@link (TreeBeta:interface).create}, except deeply clones existing nodes.
-	//  * @remarks
-	//  * This only clones the persisted data associated with a node.
-	//  * Local state, such as properties added to customized schema classes, will not be cloned:
-	//  * they will be initialized however they end up after running the constructor, just like if a remote client had inserted the same nodes.
-	//  */
-	// clone<const TSchema extends ImplicitFieldSchema>(
-	// 	original: TreeFieldFromImplicitField<TSchema>,
-	// 	options?: {
-	// 		/**
-	// 		 * If set, all identifier's in the cloned tree (See {@link SchemaFactory.identifier}) will be replaced with new ones allocated using the default identifier allocation schema.
-	// 		 * Otherwise any identifiers will be preserved as is.
-	// 		 */
-	// 		replaceIdentifiers?: true;
-	// 	},
-	// ): TreeFieldFromImplicitField<TSchema>;
-
 	/**
 	 * Construct tree content that is compatible with the field defined by the provided `schema`.
 	 * @param schema - The schema for what to construct. As this is an {@link ImplicitFieldSchema}, a {@link FieldSchema}, {@link TreeNodeSchema} or {@link AllowedTypes} array can be provided.
@@ -240,8 +149,7 @@ export function borrowCursorFromTreeNodeOrValue(
 		return cursorFromVerbose(node, {});
 	}
 	const kernel = getKernel(node);
-	const cursor = kernel.getInnerNode().borrowCursor();
-	return cursor;
+	return kernel.getInnerNode().borrowCursor();
 }
 
 /**
@@ -274,7 +182,6 @@ export function importConcise<TSchema extends ImplicitFieldSchema | UnsafeUnknow
 		? TreeFieldFromImplicitField<TSchema>
 		: TreeNode | TreeLeafValue | undefined
 > {
-	// Create the tree content from insertable data
 	const mapTree = unhydratedFlexTreeFromInsertable(
 		data as InsertableField<UnsafeUnknownSchema>,
 		schema,
@@ -309,18 +216,39 @@ export function exportConcise(
 		return node;
 	}
 	const config: TreeEncodingOptions = { ...options };
-
 	const kernel = getKernel(node);
 	const cursor = borrowCursorFromTreeNodeOrValue(node);
 	return conciseFromCursor(cursor, kernel.context, config);
 }
 
+function createTree<const TSchema extends ImplicitFieldSchema>(
+	schema: TSchema,
+	data: InsertableTreeFieldFromImplicitField<TSchema>,
+): Unhydrated<TreeFieldFromImplicitField<TSchema>> {
+	const mapTree = unhydratedFlexTreeFromInsertable(
+		data as InsertableContent | undefined,
+		schema,
+	);
+	const result = mapTree === undefined ? undefined : getOrCreateNodeFromInnerNode(mapTree);
+	return result as Unhydrated<TreeFieldFromImplicitField<TSchema>>;
+}
+
 /**
  * Extensions to {@link (Tree:variable)} which are not yet stable.
  * @see {@link (TreeBeta:interface)}.
  * @beta
  */
 export const TreeBeta: TreeBeta = {
+	context(node: TreeNode): TreeContextBeta {
+		const kernel = getKernel(node);
+		if (!kernel.isHydrated()) {
+			return UnhydratedTreeContext.instance;
+		}
+		const view = kernel.anchorNode.anchorSet.slots.get(ViewSlot);
+		assert(view !== undefined, 0xd34 /* A hydrated node must be associated with a view. */);
+		return view;
+	},
+
 	on<K extends keyof TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(
 		node: TNode,
 		eventName: K,
@@ -331,45 +259,6 @@ export const TreeBeta: TreeBeta = {
 
 	importConcise,
 	exportConcise,
-
-	clone<const TSchema extends ImplicitFieldSchema>(
-		node: TreeFieldFromImplicitField<TSchema>,
-	): Unhydrated<TreeFieldFromImplicitField<TSchema>> {
-		// The only non-TreeNode cases are {@link TreeLeafValue} and `undefined` (for an empty optional field) which can be returned as is.
-		if (!isTreeNode(node)) {
-			return node;
-		}
-
-		const kernel = getKernel(node);
-		const cursor = kernel.getInnerNode().borrowCursor();
-
-		// To handle when the node transitively contains unknown optional fields,
-		// derive the context from the source node's stored schema which has stored schema for any such fields and their contents.
-		const flexContext = new UnhydratedContext(
-			defaultSchemaPolicy,
-			kernel.context.flexContext.schema,
-		);
-		const context = new Context(flexContext, getUnhydratedContext(kernel.schema).schema);
-
-		const fieldSchema: TreeFieldStoredSchema = {
-			kind: FieldKinds.required.identifier,
-			types: new Set([brand(kernel.schema.identifier)]),
-			persistedMetadata: undefined,
-		};
-		return createFromCursor(kernel.schema, cursor, fieldSchema, context) as Unhydrated<
-			TreeFieldFromImplicitField<TSchema>
-		>;
-	},
-
-	create<const TSchema extends ImplicitFieldSchema>(
-		schema: TSchema,
-		data: InsertableTreeFieldFromImplicitField<TSchema>,
-	): Unhydrated<TreeFieldFromImplicitField<TSchema>> {
-		const mapTree = unhydratedFlexTreeFromInsertable(
-			data as InsertableContent | undefined,
-			schema,
-		);
-		const result = mapTree === undefined ? undefined : getOrCreateNodeFromInnerNode(mapTree);
-		return result as Unhydrated<TreeFieldFromImplicitField<TSchema>>;
-	},
+	clone: cloneTree,
+	create: createTree,
 };

package/src/shared-tree/treeCheckout.ts

@@ -11,7 +11,11 @@ import type {
 } from "@fluidframework/core-interfaces/internal";
 import { assert, unreachableCase, fail } from "@fluidframework/core-utils/internal";
 import type { IIdCompressor, StableId } from "@fluidframework/id-compressor";
-import { type TelemetryLoggerExt, UsageError } from "@fluidframework/telemetry-utils/internal";
+import {
+	type TelemetryLoggerExt,
+	UsageError,
+	tagCodeArtifacts,
+} from "@fluidframework/telemetry-utils/internal";
 
 import {
 	FluidClientVersion,
@@ -62,10 +66,10 @@ import {
 	type ReadOnlyDetachedFieldIndex,
 	makeAnonChange,
 	type TaggedChange,
-	deltaFieldMapHasVisibleChanges,
 	findCommonAncestor,
 	rebaseBranch,
 	type LocalCommitEvents,
+	getDeltaChangeProfile,
 	findAncestor,
 } from "../core/index.js";
 import {
@@ -409,6 +413,7 @@ export function createTreeCheckout(
 				change: changeFamily.rebaser.compose([]),
 				revision: "root",
 				customMetadata: undefined,
+				wasTrimmed: true,
 			},
 			changeFamily,
 			() => idCompressor.generateCompressedId(),
@@ -610,6 +615,11 @@ export class TreeCheckout implements ITreeCheckout {
 	 * @privateRemarks Exposed for testing purposes.
 	 */
 	public static readonly revertTelemetryEventName = "RevertRevertible";
+	/**
+	 * The name of the telemetry event logged when a schema change is applied.
+	 * @privateRemarks Exposed for testing purposes.
+	 */
+	public static readonly schemaChangeTelemetryEventName = "SchemaChangeApplied";
 
 	readonly #events = createEmitter<CheckoutEvents>();
 	public events: Listenable<CheckoutEvents> = this.#events;
@@ -1171,7 +1181,22 @@ export class TreeCheckout implements ITreeCheckout {
 				// They will however be rebased over the rollback of the schema change. This rebasing will
 				// ensure that these data changes are muted if they would render some trees invalid under the
 				// original (reinstated) schema.
-				this.storedSchema.apply(innerChange.innerChange.schema.new);
+				const newSchema = innerChange.innerChange.schema.new;
+				const telemetryMetrics = getSchemaChangeTelemetryMetrics(
+					this.storedSchema,
+					newSchema,
+					innerChange.innerChange.isInverse,
+				);
+				this.storedSchema.apply(newSchema);
+				this.logger?.sendTelemetryEvent({
+					eventName: TreeCheckout.schemaChangeTelemetryEventName,
+					...tagCodeArtifacts({
+						details: JSON.stringify({
+							...telemetryMetrics,
+							isSharedBranch: this.isSharedBranch,
+						}),
+					}),
+				});
 			} else {
 				fail(0xad1 /* Unknown Shared Tree change type. */);
 			}
@@ -1695,7 +1720,7 @@ export class TreeCheckout implements ITreeCheckout {
 				headCommit,
 				this.mintRevisionTag,
 			);
-			const ignoreNoChangeViolation = !sharedTreeChangeHasVisibleChanges(diff);
+			const ignoreNoChangeViolation = !sharedTreeChangeHasApplicationFacingChanges(diff);
 
 			change = tagChange(
 				rebaseChange(
@@ -1922,6 +1947,54 @@ export class TreeCheckout implements ITreeCheckout {
 	// #endregion Enrichment
 }
 
+function getSchemaChangeTelemetryMetrics(
+	oldSchema: TreeStoredSchema,
+	newSchema: TreeStoredSchema,
+	isInverse: boolean,
+): {
+	changeKind: "initialize" | "upgrade" | "restriction" | "rollback";
+	isInverse: boolean;
+	oldNodeSchemaCount: number;
+	newNodeSchemaCount: number;
+	addedNodeSchemaCount: number;
+	removedNodeSchemaCount: number;
+	rootFieldKindChanged: boolean;
+	oldRootAllowedTypeCount: number;
+	newRootAllowedTypeCount: number;
+} {
+	let addedNodeSchemaCount = 0;
+	for (const identifier of newSchema.nodeSchema.keys()) {
+		if (!oldSchema.nodeSchema.has(identifier)) {
+			addedNodeSchemaCount++;
+		}
+	}
+
+	let removedNodeSchemaCount = 0;
+	for (const identifier of oldSchema.nodeSchema.keys()) {
+		if (!newSchema.nodeSchema.has(identifier)) {
+			removedNodeSchemaCount++;
+		}
+	}
+
+	return {
+		changeKind: isInverse
+			? "rollback"
+			: oldSchema.nodeSchema.size === 0
+				? "initialize"
+				: allowsRepoSuperset(defaultSchemaPolicy, oldSchema, newSchema)
+					? "upgrade"
+					: "restriction",
+		isInverse,
+		oldNodeSchemaCount: oldSchema.nodeSchema.size,
+		newNodeSchemaCount: newSchema.nodeSchema.size,
+		addedNodeSchemaCount,
+		removedNodeSchemaCount,
+		rootFieldKindChanged: oldSchema.rootFieldSchema.kind !== newSchema.rootFieldSchema.kind,
+		oldRootAllowedTypeCount: oldSchema.rootFieldSchema.types.size,
+		newRootAllowedTypeCount: newSchema.rootFieldSchema.types.size,
+	};
+}
+
 /**
  * A helper class that assists {@link TreeCheckout} in preventing functionality from being used while the tree is in the middle of being edited.
  */
@@ -2051,19 +2124,19 @@ function verboseFromCursor(
 }
 
 /**
- * Enumerates through a shared tree change, looking for schema change and field changes that result in visible changes to the tree (e.g. an insert, move, delete).
- * This function also considers changes to detached roots to be visible changes, but not renames of roots or builds of new roots.
+ * Whether the change contains any application-facing changes.
  *
  * @param change - The change to analyze.
- * @returns True if the change contains any schema changes or any field changes that result in visible changes to the tree, false otherwise.
+ * @returns True if the change contains any schema changes or any field changes (either in the document tree or in detached trees), false otherwise.
  */
-function sharedTreeChangeHasVisibleChanges(change: SharedTreeChange): boolean {
+function sharedTreeChangeHasApplicationFacingChanges(change: SharedTreeChange): boolean {
 	for (const inner of change.changes) {
 		if (inner.type === "schema") {
 			return true;
 		}
 		const delta = intoDelta(tagChange(inner.innerChange, undefined));
-		if (deltaFieldMapHasVisibleChanges(delta.fields)) {
+		const profile = getDeltaChangeProfile(delta);
+		if (profile.hasChangesInDocumentTree || profile.hasChangesInDetachedTrees) {
 			return true;
 		}
 	}

package/src/shared-tree-core/editManager.ts

@@ -136,6 +136,7 @@ export class EditManager<
 			revision: rootRevision,
 			change: changeFamily.rebaser.compose([]),
 			customMetadata: undefined,
+			wasTrimmed: true,
 		};
 
 		if (logger !== undefined) {
@@ -340,10 +341,12 @@ export class EditManager<
 		// `newTrunkBase`. Therefore, no branches should have unique references to any of the commits being evicted here.
 		// We mutate the most recent of the evicted commits to become the new trunk base. That way, any other commits that
 		// have parent pointers to the latest evicted commit will stay linked, even though that it is no longer part of the trunk.
-		const newTrunkBase = latestEvicted as Mutable<typeof latestEvicted>;
+		const newTrunkBase = latestEvicted as Mutable<GraphCommit<TChangeset>>;
 
 		// collect the revisions that will be trimmed to send as part of the branch trimmed event
-		const trimmedCommits = getPathFromBase(newTrunkBase, this.trunkBase);
+		const trimmedCommits = getPathFromBase(newTrunkBase, this.trunkBase) as Mutable<
+			GraphCommit<TChangeset>
+		>[];
 		const trimmedRevisions = trimmedCommits.map((c) => c.revision);
 
 		// The minimum sequence number informs us that all peer branches are at least caught up to the tail commit,
@@ -353,9 +356,10 @@ export class EditManager<
 		// Custom metadata shares the lifetime of its commit, so it must be dropped when the commit is
 		// trimmed. The new trunk base stays reachable as the sentinel for the remaining history, so its
 		// metadata is cleared rather than trapped; fully evicted commits get the throwing trap below.
-		(newTrunkBase as Mutable<typeof newTrunkBase>).customMetadata = undefined;
+		newTrunkBase.customMetadata = undefined;
 
-		// Only the last trimmed commit, which is the new trunk base, should remain accessible.
+		// Access to the intrinsic properties of trimmed commits indicates a bug in SharedTree.
+		// Throwing lowers the risk of such a bug causing data loss or corruption.
 		for (const commit of trimmedCommits.slice(0, -1)) {
 			Reflect.defineProperty(commit, "change", {
 				get: () => fail(0xa5e /* Should not access 'change' property of an evicted commit */),
@@ -367,17 +371,21 @@ export class EditManager<
 						0xa5f /* Should not access 'revision' property of an evicted commit */,
 					),
 			});
-			Reflect.defineProperty(commit, "parent", {
-				get: () => fail(0xa60 /* Should not access 'parent' property of an evicted commit */),
-			});
 			Reflect.defineProperty(commit, "customMetadata", {
 				get: () =>
 					fail(0xd36 /* Should not access 'customMetadata' property of an evicted commit */),
 			});
+			Reflect.defineProperty(commit, "parent", {
+				get: () =>
+					assert(false, 0xa60 /* Should not access 'parent' property of an evicted commit */),
+			});
+			commit.wasTrimmed = true;
 		}
 
-		// Dropping the parent field removes (transitively) all references to the evicted commits so they can be garbage collected.
+		// Dropping the parent field (transitively) removes references to the evicted commits so they can be garbage collected.
+		// Allowing the `parent` property to be read from the trunk base (despite it being a trimmed commit) spares readers from having to check `wasTrimmed` in order to safely find the root commit.
 		delete newTrunkBase.parent;
+		newTrunkBase.wasTrimmed = true;
 		this.trunkBase = newTrunkBase;
 
 		this._events.emit("ancestryTrimmed", trimmedRevisions);