@fluidframework/tree 2.1.0-281041 → 2.1.0

package/src/shared-tree/treeCheckout.ts

@@ -387,6 +387,11 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		SharedTreeBranch<SharedTreeEditBuilder, SharedTreeChange>
 	>();
 
+	/**
+	 * copies of the removed roots used as snapshots for reverting to previous state when transactions are aborted
+	 */
+	private readonly removedRootsSnapshots: DetachedFieldIndex[] = [];
+
 	/**
 	 * The name of the telemetry event logged for calls to {@link TreeCheckout.revertRevertible}.
 	 * @privateRemarks Exposed for testing purposes.
@@ -405,7 +410,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		private readonly mintRevisionTag: () => RevisionTag,
 		private readonly revisionTagCodec: RevisionTagCodec,
 		private readonly idCompressor: IIdCompressor,
-		private readonly removedRoots: DetachedFieldIndex = makeDetachedFieldIndex(
+		private removedRoots: DetachedFieldIndex = makeDetachedFieldIndex(
 			"repair",
 			revisionTagCodec,
 			idCompressor,
@@ -413,18 +418,38 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		/** Optional logger for telemetry. */
 		private readonly logger?: ITelemetryLoggerExt,
 	) {
+		// when a transaction is started, take a snapshot of the current state of removed roots
+		branch.on("transactionStarted", () => {
+			this.removedRootsSnapshots.push(this.removedRoots.clone());
+		});
+		// when a transaction is committed, the latest snapshot of removed roots can be discarded
+		branch.on("transactionCommitted", () => {
+			this.removedRootsSnapshots.pop();
+		});
+		// after a transaction is rolled back, revert removed roots back to the latest snapshot
+		branch.on("transactionRolledBack", () => {
+			const snapshot = this.removedRootsSnapshots.pop();
+			assert(snapshot !== undefined, 0x9ae /* a snapshot for removed roots does not exist */);
+			this.removedRoots = snapshot;
+		});
+
 		// We subscribe to `beforeChange` rather than `afterChange` here because it's possible that the change is invalid WRT our forest.
 		// For example, a bug in the editor might produce a malformed change object and thus applying the change to the forest will throw an error.
 		// In such a case we will crash here, preventing the change from being added to the commit graph, and preventing `afterChange` from firing.
 		// One important consequence of this is that we will not submit the op containing the invalid change, since op submissions happens in response to `afterChange`.
 		branch.on("beforeChange", (event) => {
 			if (event.change !== undefined) {
+				const revision =
+					event.type === "replace"
+						? event.newCommits[event.newCommits.length - 1].revision
+						: event.change.revision;
+
 				// Conflicts due to schema will be empty and thus are not applied.
 				for (const change of event.change.change.changes) {
 					if (change.type === "data") {
-						const delta = intoDelta(tagChange(change.innerChange, event.change.revision));
+						const delta = intoDelta(tagChange(change.innerChange, revision));
 						this.withCombinedVisitor((visitor) => {
-							visitDelta(delta, visitor, this.removedRoots);
+							visitDelta(delta, visitor, this.removedRoots, revision);
 						});
 					} else if (change.type === "schema") {
 						// Schema changes from a current to a new schema are expected to be backwards compatible.
@@ -518,6 +543,24 @@ export class TreeCheckout implements ITreeCheckoutFork {
 			this.events.emit("commitApplied", data, getRevertible);
 			withinEventContext = false;
 		});
+
+		// When the branch is trimmed, we can garbage collect any repair data whose latest relevant revision is one of the
+		// trimmed revisions.
+		branch.on("ancestryTrimmed", (revisions) => {
+			this.withCombinedVisitor((visitor) => {
+				revisions.forEach((revision) => {
+					// get all the roots last created or used by the revision
+					const roots = this.removedRoots.getRootsLastTouchedByRevision(revision);
+
+					// get the detached field for the root and delete it from the removed roots
+					for (const root of roots) {
+						visitor.destroy(this.removedRoots.toFieldKey(root), 1);
+					}
+
+					this.removedRoots.deleteRootsLastTouchedByRevision(revision);
+				});
+			});
+		});
 	}
 
 	private withCombinedVisitor(fn: (visitor: DeltaVisitor) => void): void {
@@ -574,7 +617,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		this.checkNotDisposed();
 		assert(
 			!view.transaction.inProgress(),
-			"A view cannot be rebased while it has a pending transaction",
+			0x9af /* A view cannot be rebased while it has a pending transaction */,
 		);
 		view.branch.rebaseOnto(this.branch);
 	}
@@ -590,7 +633,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		this.checkNotDisposed();
 		assert(
 			!this.transaction.inProgress(),
-			"Views cannot be merged into a view while it has a pending transaction",
+			0x9b0 /* Views cannot be merged into a view while it has a pending transaction */,
 		);
 		while (view.transaction.inProgress()) {
 			view.transaction.commit();
@@ -629,6 +672,14 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		return trees;
 	}
 
+	/**
+	 * This sets the tip revision as the latest relevant revision for any removed roots that are loaded from a summary.
+	 * This needs to be called right after loading {@link this.removedRoots} from a summary to allow loaded data to be garbage collected.
+	 */
+	public setTipRevisionForLoadedData(revision: RevisionTag): void {
+		this.removedRoots.setRevisionsForLoadedData(revision);
+	}
+
 	private purgeRevertibles(): void {
 		for (const revertible of this.revertibles) {
 			revertible.dispose();

package/src/shared-tree/treeView.ts

@@ -12,6 +12,7 @@ import {
 	type NodeKeyManager,
 	getTreeContext,
 } from "../feature-libraries/index.js";
+import { tryDisposeTreeNode } from "../simple-tree/index.js";
 import { type IDisposable, disposeSymbol } from "../util/index.js";
 
 import type { ITreeCheckout, ITreeCheckoutFork, TreeCheckout } from "./treeCheckout.js";
@@ -94,6 +95,10 @@ export class CheckoutFlexTreeView<
 	}
 
 	public [disposeSymbol](): void {
+		for (const anchorNode of this.checkout.forest.anchors) {
+			tryDisposeTreeNode(anchorNode);
+		}
+
 		this.context[disposeSymbol]();
 		this.onDispose?.();
 	}

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

@@ -137,6 +137,13 @@ export interface SharedTreeBranchEvents<TEditor extends ChangeFamilyEditor, TCha
 	 */
 	transactionAborted(isOuterTransaction: boolean): void;
 
+	/**
+	 * Fired after the current transaction is completely rolled back.
+	 * @param isOuterTransaction - true iff the transaction being aborted is the outermost transaction
+	 * as opposed to a nested transaction.
+	 */
+	transactionRolledBack(isOuterTransaction: boolean): void;
+
 	/**
 	 * Fired after the current transaction is committed.
 	 * @param isOuterTransaction - true iff the transaction being committed is the outermost transaction
@@ -361,6 +368,7 @@ export class SharedTreeBranch<
 
 		this.emit("transactionAborted", this.transactions.size === 0);
 		if (commits.length === 0) {
+			this.emit("transactionRolledBack", this.transactions.size === 0);
 			return [undefined, []];
 		}
 
@@ -387,6 +395,7 @@ export class SharedTreeBranch<
 		this.emit("beforeChange", changeEvent);
 		this.head = startCommit;
 		this.emit("afterChange", changeEvent);
+		this.emit("transactionRolledBack", this.transactions.size === 0);
 		return [change, commits];
 	}
 

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

@@ -95,6 +95,13 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 		return this.getLocalBranch().editor;
 	}
 
+	/**
+	 * Gets the revision at the head of the trunk.
+	 */
+	protected get trunkHeadRevision(): RevisionTag {
+		return this.editManager.getTrunkHead().revision;
+	}
+
 	/**
 	 * Used to encode/decode messages sent to/received from the Fluid runtime.
 	 *

package/src/simple-tree/arrayNode.ts

@@ -27,7 +27,7 @@ import {
 	markContentType,
 	prepareContentForHydration,
 } from "./proxies.js";
-import { getFlexNode } from "./proxyBinding.js";
+import { getFlexNode, getKernel } from "./proxyBinding.js";
 import {
 	NodeKind,
 	type ImplicitAllowedTypes,
@@ -683,7 +683,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 		input: Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>> | InternalTreeNode,
 	) {
 		super(input);
-		getFlexNode(this).on("nodeChanged", () => {
+		getKernel(this).on("nodeChanged", () => {
 			this.#generationNumber += 1;
 		});
 	}

package/src/simple-tree/index.ts

@@ -39,8 +39,8 @@ export {
 	type ApplyKind,
 } from "./schemaTypes.js";
 export { SchemaFactory, type ScopedSchemaName } from "./schemaFactory.js";
-export { getFlexNode } from "./proxyBinding.js";
-export { treeNodeApi, type TreeNodeApi, type TreeChangeEvents } from "./treeNodeApi.js";
+export { getFlexNode, tryDisposeTreeNode } from "./proxyBinding.js";
+export { treeNodeApi, type TreeNodeApi } from "./treeNodeApi.js";
 export { toFlexSchema, cursorFromUnhydratedRoot } from "./toFlexSchema.js";
 export type {
 	FieldHasDefaultUnsafe,
@@ -82,7 +82,7 @@ export {
 
 // TreeNode is only type exported, which prevents use of the class object for unsupported use-cases like direct sub-classing and instancof.
 // See docs on TreeNode for more details.
-export type { TreeNode, Unhydrated, InternalTreeNode } from "./types.js";
+export type { TreeChangeEvents, TreeNode, Unhydrated, InternalTreeNode } from "./types.js";
 export {
 	TreeArrayNode,
 	IterableTreeArrayContent,

package/src/simple-tree/proxies.ts

@@ -20,9 +20,7 @@ import {
 	type FlexFieldSchema,
 	type FlexTreeField,
 	type FlexTreeNode,
-	type FlexTreeNodeEvents,
 	type FlexTreeTypedField,
-	type MapTreeNode,
 	tryGetMapTreeNode,
 	typeNameSymbol,
 	isFlexTreeNode,
@@ -32,7 +30,6 @@ import { type Mutable, fail, isReadonlyArray } from "../util/index.js";
 import { anchorProxy, tryGetFlexNode, tryGetProxy } from "./proxyBinding.js";
 import { tryGetSimpleNodeSchema } from "./schemaCaching.js";
 import type { TreeNode, Unhydrated } from "./types.js";
-import type { Off } from "../events/index.js";
 
 /**
  * Detects if the given 'candidate' is a TreeNode.
@@ -116,7 +113,6 @@ export function getOrCreateNodeProxy(flexNode: FlexTreeNode): TreeNode | TreeVal
 /** The path of a proxy, relative to the root of the content tree that the proxy belongs to */
 interface RelativeProxyPath {
 	readonly path: UpPath;
-	readonly mapTreeNode: MapTreeNode;
 	readonly proxy: TreeNode;
 }
 
@@ -150,8 +146,8 @@ export function prepareContentForHydration(
 			proxyPaths: [],
 		};
 
-		walkMapTree(content, proxies.rootPath, (p, mapTreeNode, proxy) => {
-			proxies.proxyPaths.push({ path: p, mapTreeNode, proxy });
+		walkMapTree(content, proxies.rootPath, (p, proxy) => {
+			proxies.proxyPaths.push({ path: p, proxy });
 		});
 
 		bindProxies([proxies], forest);
@@ -172,8 +168,8 @@ function prepareArrayContentForHydration(
 			},
 			proxyPaths: [],
 		});
-		walkMapTree(content[i], proxies[i].rootPath, (p, mapTreeNode, proxy) => {
-			proxies[i].proxyPaths.push({ path: p, mapTreeNode, proxy });
+		walkMapTree(content[i], proxies[i].rootPath, (p, proxy) => {
+			proxies[i].proxyPaths.push({ path: p, proxy });
 		});
 	}
 
@@ -183,13 +179,13 @@ function prepareArrayContentForHydration(
 function walkMapTree(
 	mapTree: MapTree,
 	path: UpPath,
-	onVisitTreeNode: (path: UpPath, mapTreeNode: MapTreeNode, treeNode: TreeNode) => void,
+	onVisitTreeNode: (path: UpPath, treeNode: TreeNode) => void,
 ): void {
 	const mapTreeNode = tryGetMapTreeNode(mapTree);
 	if (mapTreeNode !== undefined) {
 		const treeNode = tryGetProxy(mapTreeNode);
 		if (treeNode !== undefined) {
-			onVisitTreeNode(path, mapTreeNode, treeNode);
+			onVisitTreeNode(path, treeNode);
 		}
 	}
 
@@ -215,25 +211,8 @@ function bindProxies(proxies: RootedProxyPaths[], forest: IForestSubscription):
 		let i = 0;
 		const off = forest.on("afterRootFieldCreated", (fieldKey) => {
 			(proxies[i].rootPath as Mutable<UpPath>).parentField = fieldKey;
-			for (const { path, mapTreeNode, proxy } of proxies[i].proxyPaths) {
-				const anchorNode = anchorProxy(forest.anchors, path, proxy);
-				mapTreeNode.forwardEvents({
-					on<K extends keyof FlexTreeNodeEvents>(
-						eventName: K,
-						listener: FlexTreeNodeEvents[K],
-					): Off {
-						switch (eventName) {
-							case "nodeChanged": {
-								return anchorNode.on("childrenChangedAfterBatch", listener);
-							}
-							case "treeChanged": {
-								return anchorNode.on("subtreeChangedAfterBatch", listener);
-							}
-							default:
-								fail("Unexpected event subscription");
-						}
-					},
-				});
+			for (const { path, proxy } of proxies[i].proxyPaths) {
+				anchorProxy(forest.anchors, path, proxy);
 			}
 			if (++i === proxies.length) {
 				off();

package/src/simple-tree/proxyBinding.ts

@@ -29,6 +29,7 @@ import type { TreeNode } from "./types.js";
 // eslint-disable-next-line import/no-internal-modules
 import { makeTree } from "../feature-libraries/flex-tree/lazyNode.js";
 import type { TreeMapNode } from "./mapNode.js";
+import { TreeNodeKernel } from "./treeNodeKernel.js";
 
 // This file contains various maps and helpers for supporting proxy binding (a.k.a. proxy hydration).
 // See ./ProxyBinding.md for a high-level overview of the process.
@@ -185,9 +186,31 @@ function bindProxyToAnchorNode(proxy: TreeNode, anchorNode: AnchorNode): void {
 	proxyToAnchorNode.set(proxy, anchorNode);
 	// However, it's fine for an anchor node to rotate through different proxies when the content at that place in the tree is replaced.
 	anchorNode.slots.set(proxySlot, proxy);
+	getKernel(proxy).hydrate(anchorNode);
 }
 
 /**
  * Given a node's schema, return the corresponding object in the proxy-based API.
  */
 type TypedNode<TSchema extends FlexTreeNodeSchema> = TreeNode & WithType<TSchema["name"]>;
+
+export function createKernel(node: TreeNode): void {
+	treeNodeToKernel.set(node, new TreeNodeKernel(node));
+}
+
+export function getKernel(node: TreeNode): TreeNodeKernel {
+	const kernel = treeNodeToKernel.get(node);
+	assert(kernel !== undefined, 0x9b1 /* Expected tree node to have kernel */);
+	return kernel;
+}
+
+export function tryDisposeTreeNode(anchorNode: AnchorNode): void {
+	const treeNode = anchorNode.slots.get(proxySlot);
+	if (treeNode !== undefined) {
+		const kernel = treeNodeToKernel.get(treeNode);
+		assert(kernel !== undefined, 0x9b2 /* Expected tree node to have kernel */);
+		kernel.dispose();
+	}
+}
+
+const treeNodeToKernel = new WeakMap<TreeNode, TreeNodeKernel>();

package/src/simple-tree/tree.ts

@@ -165,7 +165,10 @@ export function walkNodeSchema(
 			walkAllowedTypes(field.allowedTypeSet, visitor, visitedSet);
 		}
 	} else {
-		assert(schema.kind === NodeKind.Array || schema.kind === NodeKind.Map, "invalid schema");
+		assert(
+			schema.kind === NodeKind.Array || schema.kind === NodeKind.Map,
+			0x9b3 /* invalid schema */,
+		);
 		const childTypes = schema.info as ImplicitAllowedTypes;
 		walkFieldSchema(childTypes, visitor, visitedSet);
 	}

package/src/simple-tree/treeNodeApi.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
+import { assert } from "@fluidframework/core-utils/internal";
 
 import { Multiplicity, rootFieldKey } from "../core/index.js";
 import {
@@ -16,7 +16,7 @@ import {
 import { fail, extractFromOpaque, isReadonlyArray } from "../util/index.js";
 
 import { getOrCreateNodeProxy, isTreeNode } from "./proxies.js";
-import { getFlexNode } from "./proxyBinding.js";
+import { getFlexNode, getKernel } from "./proxyBinding.js";
 import { tryGetSimpleNodeSchema } from "./schemaCaching.js";
 import {
 	NodeKind,
@@ -27,7 +27,7 @@ import {
 	type ImplicitAllowedTypes,
 	type TreeNodeFromImplicitAllowedTypes,
 } from "./schemaTypes.js";
-import type { TreeNode } from "./types.js";
+import type { TreeNode, TreeChangeEvents } from "./types.js";
 import {
 	booleanSchema,
 	handleSchema,
@@ -37,6 +37,7 @@ import {
 } from "./leafNodeSchema.js";
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import type { Off } from "../events/index.js";
 
 /**
  * Provides various functions for analyzing {@link TreeNode}s.
@@ -102,7 +103,7 @@ export interface TreeNodeApi {
 	/**
 	 * Returns the {@link TreeStatus} of the given node.
 	 */
-	readonly status: (node: TreeNode) => TreeStatus;
+	status(node: TreeNode): TreeStatus;
 
 	/**
 	 * Returns the {@link SchemaFactory.identifier | identifier} of the given node in the most compressed form possible.
@@ -127,7 +128,7 @@ export interface TreeNodeApi {
  * The `Tree` object holds various functions for analyzing {@link TreeNode}s.
  */
 export const treeNodeApi: TreeNodeApi = {
-	parent: (node: TreeNode): TreeNode | undefined => {
+	parent(node: TreeNode): TreeNode | undefined {
 		const editNode = getFlexNode(node).parentField.parent.parent;
 		if (editNode === undefined) {
 			return undefined;
@@ -140,7 +141,7 @@ export const treeNodeApi: TreeNodeApi = {
 		);
 		return output;
 	},
-	key: (node: TreeNode) => {
+	key(node: TreeNode): string | number {
 		// If the parent is undefined, then this node is under the root field,
 		// so we know its key is the special root one.
 		const parent = treeNodeApi.parent(node);
@@ -156,28 +157,20 @@ export const treeNodeApi: TreeNodeApi = {
 		const viewKey = getViewKeyFromStoredKey(parentSchema, storedKey);
 		return viewKey;
 	},
-	on: <K extends keyof TreeChangeEvents>(
+	on<K extends keyof TreeChangeEvents>(
 		node: TreeNode,
 		eventName: K,
 		listener: TreeChangeEvents[K],
-	) => {
-		const flex = getFlexNode(node);
-		switch (eventName) {
-			case "nodeChanged":
-				return flex.on("nodeChanged", listener);
-			case "treeChanged":
-				return flex.on("treeChanged", listener);
-			default:
-				return unreachableCase(eventName);
-		}
+	): Off {
+		return getKernel(node).on(eventName, listener);
 	},
-	status: (node: TreeNode) => {
-		return getFlexNode(node, true).treeStatus();
+	status(node: TreeNode): TreeStatus {
+		return getKernel(node).getStatus();
 	},
-	is: <TSchema extends ImplicitAllowedTypes>(
+	is<TSchema extends ImplicitAllowedTypes>(
 		value: unknown,
 		schema: TSchema,
-	): value is TreeNodeFromImplicitAllowedTypes<TSchema> => {
+	): value is TreeNodeFromImplicitAllowedTypes<TSchema> {
 		const actualSchema = tryGetSchema(value);
 		if (actualSchema === undefined) {
 			return false;
@@ -304,78 +297,3 @@ function getViewKeyFromStoredKey(
 
 	return storedKey;
 }
-
-/**
- * A collection of events that can be emitted by a {@link TreeNode}.
- *
- * @privateRemarks
- * TODO: add a way to subscribe to a specific field (for nodeChanged and treeChanged).
- * Probably have object node and map node specific APIs for this.
- *
- * TODO: ensure that subscription API for fields aligns with API for subscribing to the root.
- *
- * TODO: add more wider area (avoid needing tons of nodeChanged registration) events for use-cases other than treeChanged.
- * Some ideas:
- *
- * - treeChanged, but with some subtrees/fields/paths excluded
- * - helper to batch several nodeChanged calls to a treeChanged scope
- * - parent change (ex: registration on the parent field for a specific index: maybe allow it for a range. Ex: node event takes optional field and optional index range?)
- * - new content inserted into subtree. Either provide event for this and/or enough info to treeChanged to find and search the new sub-trees.
- * Add separate (non event related) API to efficiently scan tree for given set of types (using low level cursor and schema based filtering)
- * to allow efficiently searching for new content (and initial content) of a given type.
- *
- * @sealed @public
- */
-export interface TreeChangeEvents {
-	/**
-	 * Emitted by a node after a batch of changes has been applied to the tree, if a change affected the node, where a
-	 * change is:
-	 *
-	 * - For an object node, when the value of one of its properties changes (i.e., the property's value is set
-	 * to something else, including `undefined`).
-	 *
-	 * - For an array node, when an element is added, removed, or moved.
-	 *
-	 * - For a map node, 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 it 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).
-	 */
-	nodeChanged(): void;
-
-	/**
-	 * Emitted by a node after a batch of changes has been applied to the tree, when something changed anywhere in the
-	 * subtree rooted at it.
-	 *
-	 * @remarks
-	 * This event is not emitted when the node itself is moved to a different location in the tree or removed from the tree.
-	 * In that case it is emitted on the _parent_ node, not the node itself.
-	 *
-	 * The node itself is part of the subtree, so this event will be emitted even if the only changes are to the properties
-	 * of 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 it is emitted, the tree is guaranteed to be in-schema.
-	 */
-	treeChanged(): void;
-}

package/src/simple-tree/treeNodeKernel.ts

@@ -0,0 +1,91 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils/internal";
+import { createEmitter, type Listenable, type Off } from "../events/index.js";
+import type { TreeChangeEvents, TreeNode } from "./types.js";
+import type { AnchorNode } from "../core/index.js";
+import {
+	flexTreeSlot,
+	isFreedSymbol,
+	LazyEntity,
+	TreeStatus,
+	treeStatusFromAnchorCache,
+} from "../feature-libraries/index.js";
+
+/**
+ * Contains state and an internal API for managing {@link TreeNode}s.
+ * @remarks All {@link TreeNode}s have an associated kernel object.
+ * The kernel has the same lifetime as the node and spans both its unhydrated and hydrated states.
+ * When hydration occurs, the kernel is notified via the {@link TreeNodeKernel.hydrate | hydrate} method.
+ */
+export class TreeNodeKernel implements Listenable<TreeChangeEvents> {
+	#hydrated?: {
+		anchorNode: AnchorNode;
+		offAnchorNode: Off;
+	};
+	#events = createEmitter<TreeChangeEvents>();
+
+	public constructor(public readonly node: TreeNode) {}
+
+	public hydrate(anchorNode: AnchorNode): void {
+		const offChildrenChanged = anchorNode.on("childrenChangedAfterBatch", () => {
+			this.#events.emit("nodeChanged");
+		});
+
+		const offSubtreeChanged = anchorNode.on("subtreeChangedAfterBatch", () => {
+			this.#events.emit("treeChanged");
+		});
+
+		const offAfterDestroy = anchorNode.on("afterDestroy", () => this.dispose());
+
+		this.#hydrated = {
+			anchorNode,
+			offAnchorNode: () => {
+				offChildrenChanged();
+				offSubtreeChanged();
+				offAfterDestroy();
+			},
+		};
+	}
+
+	public dehydrate(): void {
+		this.#hydrated?.offAnchorNode?.();
+		this.#hydrated = undefined;
+	}
+
+	public isHydrated(): boolean {
+		return this.#hydrated !== undefined;
+	}
+
+	public getStatus(): TreeStatus {
+		if (this.#hydrated?.anchorNode === undefined) {
+			return TreeStatus.New;
+		}
+
+		// TODO: Replace this check with the proper check against the cursor state when the cursor becomes part of the kernel
+		const flex = this.#hydrated.anchorNode.slots.get(flexTreeSlot);
+		if (flex !== undefined) {
+			assert(flex instanceof LazyEntity, 0x9b4 /* Unexpected flex node implementation */);
+			if (flex[isFreedSymbol]()) {
+				return TreeStatus.Deleted;
+			}
+		}
+
+		return treeStatusFromAnchorCache(this.#hydrated.anchorNode);
+	}
+
+	public on<K extends keyof TreeChangeEvents>(
+		eventName: K,
+		listener: TreeChangeEvents[K],
+	): Off {
+		return this.#events.on(eventName, listener);
+	}
+
+	public dispose(): void {
+		this.dehydrate();
+		// TODO: go to the context and remove myself from withAnchors
+	}
+}