@fluidframework/tree 2.1.0-281041 → 2.2.0

package/src/shared-tree/sharedTreeChangeEnricher.ts

@@ -87,7 +87,7 @@ export class SharedTreeMutableChangeEnricher
 				case "data": {
 					const delta = intoDelta(tagChange(dataOrSchemaChange.innerChange, revision));
 					const visitor = this.forest.acquireVisitor();
-					visitDelta(delta, visitor, this.removedRoots);
+					visitDelta(delta, visitor, this.removedRoots, revision);
 					visitor.free();
 					break;
 				}

package/src/shared-tree/sharedTreeChangeFamily.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, oob } from "@fluidframework/core-utils/internal";
 
 import type { ICodecFamily, ICodecOptions } from "../codec/index.js";
 import {
@@ -173,8 +173,8 @@ export class SharedTreeChangeFamily
 			0x884 /* SharedTreeChange should have exactly one inner change if no schema change is present. */,
 		);
 
-		const dataChangeIntention = change.change.changes[0];
-		const dataChangeOver = over.change.changes[0];
+		const dataChangeIntention = change.change.changes[0] ?? oob();
+		const dataChangeOver = over.change.changes[0] ?? oob();
 		assert(
 			dataChangeIntention.type === "data" && dataChangeOver.type === "data",
 			0x885 /* Data change should be present. */,

package/src/shared-tree/sharedTreeEditBuilder.ts

@@ -15,7 +15,6 @@ import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
 /**
  * Editor for schema changes.
  * The only currently supported operation is to replace the stored schema.
- * @internal
  */
 export interface ISchemaEditor {
 	/**
@@ -28,7 +27,6 @@ export interface ISchemaEditor {
 
 /**
  * SharedTree editor for transactional tree data and schema changes.
- * @internal
  */
 export interface ISharedTreeEditor extends IDefaultEditBuilder {
 	/**

package/src/shared-tree/treeApi.ts

@@ -11,7 +11,7 @@ import {
 	type TreeNode,
 	type TreeNodeApi,
 	type TreeView,
-	getFlexNode,
+	getOrCreateInnerNode,
 	treeNodeApi,
 } from "../simple-tree/index.js";
 import { fail } from "../util/index.js";
@@ -435,7 +435,7 @@ export function runTransaction<
 	} else {
 		const node = treeOrNode as TNode;
 		const t = transaction as (node: TNode) => TResult | typeof rollback;
-		const context = getFlexNode(node).context;
+		const context = getOrCreateInnerNode(node).context;
 		assert(context instanceof Context, 0x901 /* Unsupported context */);
 		const treeView =
 			contextToTreeView.get(context) ?? fail("Expected view to be registered for context");
@@ -453,9 +453,9 @@ function runTransactionInCheckout<TResult>(
 	for (const constraint of preconditions) {
 		switch (constraint.type) {
 			case "nodeInDocument": {
-				const node = getFlexNode(constraint.node);
+				const node = getOrCreateInnerNode(constraint.node);
 				assert(
-					node.treeStatus() === TreeStatus.InDocument,
+					treeApi.status(constraint.node) === TreeStatus.InDocument,
 					0x90f /* Attempted to apply "nodeExists" constraint when building a transaction, but the node is not in the document. */,
 				);
 				checkout.editor.addNodeExistsConstraint(node.anchorNode);

package/src/shared-tree/treeCheckout.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, oob } from "@fluidframework/core-utils/internal";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 import {
 	UsageError,
@@ -61,7 +61,6 @@ import type { ISharedTreeEditor, SharedTreeEditBuilder } from "./sharedTreeEditB
 
 /**
  * Events for {@link ITreeCheckout}.
- * @internal
  */
 export interface CheckoutEvents {
 	/**
@@ -110,7 +109,6 @@ export type RevertibleFactory = (
  * @privateRemarks
  * API for interacting with a {@link SharedTreeBranch}.
  * Implementations of this interface must implement the {@link branchKey} property.
- * @internal
  */
 export interface ITreeCheckout extends AnchorLocator {
 	/**
@@ -278,7 +276,6 @@ export function createTreeCheckout(
  *
  * To avoid updating observers of the view state with intermediate results during a transaction,
  * use {@link ITreeCheckout#fork} and {@link ISharedTreeFork#merge}.
- * @internal
  */
 export interface ITransaction {
 	/**
@@ -342,7 +339,6 @@ class Transaction implements ITransaction {
  * Branch (like in a version control system) of SharedTree.
  *
  * {@link ITreeCheckout} that has forked off of the main trunk/branch.
- * @internal
  */
 export interface ITreeCheckoutFork extends ITreeCheckout, IDisposable {
 	/**
@@ -387,6 +383,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 +406,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 +414,40 @@ 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"
+						? // Change events will always contain new commits
+							// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+							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.
@@ -450,7 +473,8 @@ export class TreeCheckout implements ITreeCheckoutFork {
 				this.events.emit("afterBatch");
 			}
 			if (event.type === "replace" && getChangeReplaceType(event) === "transactionCommit") {
-				const transactionRevision = event.newCommits[0].revision;
+				const firstCommit = event.newCommits[0] ?? oob();
+				const transactionRevision = firstCommit.revision;
 				for (const transactionStep of event.removedCommits) {
 					this.removedRoots.updateMajor(transactionStep.revision, transactionRevision);
 				}
@@ -518,6 +542,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 +616,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 +632,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 +671,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();
@@ -698,7 +748,6 @@ export class TreeCheckout implements ITreeCheckoutFork {
  * @param transaction - the transaction function. This will be executed immediately. It is passed `view` as an argument for convenience.
  * If this function returns an `Abort` result then the transaction will be aborted. Otherwise, it will be committed.
  * @returns whether or not the transaction was committed or aborted
- * @internal
  */
 export function runSynchronous(
 	view: ITreeCheckout,

package/src/shared-tree/treeView.ts

@@ -12,15 +12,15 @@ 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";
+import type { ITreeCheckout, ITreeCheckoutFork } from "./treeCheckout.js";
 
 /**
  * The portion of {@link FlexTreeView} that does not depend on the schema's type.
  * @privateRemarks
  * Since {@link FlexTreeView}'s schema is invariant, `FlexTreeView<FlexFieldSchema>` does not cover this use case.
- * @internal
  */
 export interface FlexTreeViewGeneric extends IDisposable {
 	/**
@@ -45,7 +45,6 @@ export interface FlexTreeViewGeneric extends IDisposable {
  * @privateRemarks
  * TODO:
  * If schema aware APIs are removed from flex tree, this can be combined with {@link FlexTreeViewGeneric}.
- * @internal
  */
 export interface FlexTreeView<in out TRoot extends FlexFieldSchema>
 	extends FlexTreeViewGeneric {
@@ -65,7 +64,6 @@ export interface FlexTreeView<in out TRoot extends FlexFieldSchema>
  * Branch (like in a version control system) of SharedTree.
  *
  * {@link FlexTreeView} that has forked off of the main trunk/branch.
- * @internal
  */
 export interface ITreeViewFork<in out TRoot extends FlexFieldSchema>
 	extends FlexTreeView<TRoot> {
@@ -77,7 +75,7 @@ export interface ITreeViewFork<in out TRoot extends FlexFieldSchema>
  */
 export class CheckoutFlexTreeView<
 	in out TRoot extends FlexFieldSchema,
-	out TCheckout extends TreeCheckout = TreeCheckout,
+	out TCheckout extends ITreeCheckout = ITreeCheckout,
 > implements FlexTreeView<TRoot>
 {
 	public readonly context: Context;
@@ -94,11 +92,15 @@ export class CheckoutFlexTreeView<
 	}
 
 	public [disposeSymbol](): void {
+		for (const anchorNode of this.checkout.forest.anchors) {
+			tryDisposeTreeNode(anchorNode);
+		}
+
 		this.context[disposeSymbol]();
 		this.onDispose?.();
 	}
 
-	public fork(): CheckoutFlexTreeView<TRoot, TreeCheckout & ITreeCheckoutFork> {
+	public fork(): CheckoutFlexTreeView<TRoot, ITreeCheckout & ITreeCheckoutFork> {
 		const branch = this.checkout.fork();
 		return new CheckoutFlexTreeView(branch, this.schema, this.nodeKeyManager);
 	}

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

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, oob } from "@fluidframework/core-utils/internal";
 import { type TelemetryEventBatcher, measure } from "@fluidframework/telemetry-utils/internal";
 
 import {
@@ -26,6 +26,7 @@ import {
 import { EventEmitter, type Listenable } from "../events/index.js";
 
 import { TransactionStack } from "./transactionStack.js";
+import { fail } from "../util/index.js";
 
 /**
  * Describes a change to a `SharedTreeBranch`. Various operations can mutate the head of the branch;
@@ -80,6 +81,14 @@ export function getChangeReplaceType(
 	// └─ B' (branch Y)                                └─ (branch Y)
 	//
 	// B' is removed and replaced by B because both have the same revision.
+	assert(
+		change.removedCommits[0] !== undefined,
+		0x9e4 /* This wont run due to the length check above */,
+	);
+	assert(
+		change.newCommits[0] !== undefined,
+		0x9e5 /* This wont run because a replace operation always has new commits */,
+	);
 	if (
 		change.removedCommits.length === 1 &&
 		change.removedCommits[0].revision === change.newCommits[0].revision
@@ -137,6 +146,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,19 +377,22 @@ export class SharedTreeBranch<
 
 		this.emit("transactionAborted", this.transactions.size === 0);
 		if (commits.length === 0) {
+			this.emit("transactionRolledBack", this.transactions.size === 0);
 			return [undefined, []];
 		}
 
 		const inverses: TaggedChange<TChange>[] = [];
 		for (let i = commits.length - 1; i >= 0; i--) {
 			const revision = this.mintRevisionTag();
+			const commit =
+				commits[i] ?? fail("This wont run because we are iterating through commits");
 			const inverse = this.changeFamily.rebaser.changeRevision(
-				this.changeFamily.rebaser.invert(commits[i], false),
+				this.changeFamily.rebaser.invert(commit, false),
 				revision,
-				commits[i].revision,
+				commit.revision,
 			);
 
-			inverses.push(tagRollbackInverse(inverse, revision, commits[i].revision));
+			inverses.push(tagRollbackInverse(inverse, revision, commit.revision));
 		}
 		const change =
 			inverses.length > 0 ? this.changeFamily.rebaser.compose(inverses) : undefined;
@@ -387,6 +406,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];
 	}
 
@@ -401,8 +421,7 @@ export class SharedTreeBranch<
 		const { startRevision: startRevisionOriginal } = this.transactions.pop();
 		let startRevision = startRevisionOriginal;
 		while (this.initialTransactionRevToRebasedRev.has(startRevision)) {
-			// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-			startRevision = this.initialTransactionRevToRebasedRev.get(startRevision)!;
+			startRevision = this.initialTransactionRevToRebasedRev.get(startRevision) ?? oob();
 		}
 
 		if (!this.isTransacting()) {
@@ -465,8 +484,10 @@ export class SharedTreeBranch<
 
 		const newCommits = targetCommits.concat(sourceCommits);
 		if (this.isTransacting()) {
-			const src = targetCommits[0].parent?.revision;
-			const dst = targetCommits[targetCommits.length - 1].revision;
+			const firstCommit = targetCommits[0] ?? oob();
+			const lastCommit = targetCommits[targetCommits.length - 1] ?? oob();
+			const src = firstCommit.parent?.revision;
+			const dst = lastCommit.revision;
 			if (src !== undefined && dst !== undefined) {
 				this.initialTransactionRevToRebasedRev.set(src, dst);
 			}

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

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, oob } from "@fluidframework/core-utils/internal";
 import type { ChangeRebaser, GraphCommit } from "../core/index.js";
 import { disposeSymbol } from "../util/index.js";
 import type { ChangeEnricherReadonlyCheckout, ResubmitMachine } from "./index.js";
@@ -74,7 +74,7 @@ export class DefaultResubmitMachine<TChange> implements ResubmitMachine<TChange>
 			const checkout = this.tip.fork();
 			// Roll back the checkout to the state before the oldest commit
 			for (let iCommit = toResubmit.length - 1; iCommit >= 0; iCommit -= 1) {
-				const commit = toResubmit[iCommit];
+				const commit = toResubmit[iCommit] ?? oob();
 				const rollback = this.inverter(commit, true);
 				// WARNING: it's not currently possible to roll back past a schema change (see AB#7265).
 				// Either we have to make it possible to do so, or this logic will have to change to work
@@ -87,7 +87,7 @@ export class DefaultResubmitMachine<TChange> implements ResubmitMachine<TChange>
 				iCommit <= this.latestInFlightCommitWithStaleEnrichments;
 				iCommit += 1
 			) {
-				const commit = toResubmit[iCommit];
+				const commit = toResubmit[iCommit] ?? oob();
 				const enrichedChange = checkout.updateChangeEnrichments(
 					commit.change,
 					commit.revision,
@@ -114,7 +114,7 @@ export class DefaultResubmitMachine<TChange> implements ResubmitMachine<TChange>
 			this.isInResubmitPhase,
 			0x982 /* No available commit to resubmit outside of resubmit phase */,
 		);
-		return this.resubmitQueue[0];
+		return this.resubmitQueue[0] ?? oob();
 	}
 
 	public get isInResubmitPhase(): boolean {

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

@@ -72,6 +72,7 @@ export function makeEditManagerCodecs<TChangeset>(
 		[1, makeV1CodecWithVersion(changeCodecs.resolve(1), revisionTagCodec, options, 1)],
 		[2, makeV1CodecWithVersion(changeCodecs.resolve(2), revisionTagCodec, options, 2)],
 		[3, makeV1CodecWithVersion(changeCodecs.resolve(3), revisionTagCodec, options, 3)],
+		[4, makeV1CodecWithVersion(changeCodecs.resolve(4), revisionTagCodec, options, 4)],
 	]);
 }
 

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

@@ -98,13 +98,18 @@ const SummarySessionBranch = <ChangeSchema extends TSchema>(tChange: ChangeSchem
 export interface EncodedEditManager<TChangeset> {
 	readonly trunk: readonly Readonly<SequencedCommit<TChangeset>>[];
 	readonly branches: readonly [SessionId, Readonly<EncodedSummarySessionBranch<TChangeset>>][];
-	readonly version: 1 | 2 | 3;
+	readonly version: 1 | 2 | 3 | 4;
 }
 
 export const EncodedEditManager = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
 	Type.Object(
 		{
-			version: Type.Union([Type.Literal(1), Type.Literal(2), Type.Literal(3)]),
+			version: Type.Union([
+				Type.Literal(1),
+				Type.Literal(2),
+				Type.Literal(3),
+				Type.Literal(4),
+			]),
 			trunk: Type.Array(SequencedCommit(tChange)),
 			branches: Type.Array(Type.Tuple([SessionIdSchema, SummarySessionBranch(tChange)])),
 		},

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

@@ -76,6 +76,7 @@ export function makeMessageCodecs<TChangeset>(
 		[1, v1Codec],
 		[2, makeV1CodecWithVersion(changeCodecs.resolve(2).json, revisionTagCodec, options, 2)],
 		[3, makeV1CodecWithVersion(changeCodecs.resolve(3).json, revisionTagCodec, options, 3)],
+		[4, makeV1CodecWithVersion(changeCodecs.resolve(4).json, revisionTagCodec, options, 4)],
 	]);
 }
 
@@ -88,7 +89,7 @@ function makeV1CodecWithVersion<TChangeset>(
 		ChangeEncodingContext
 	>,
 	options: ICodecOptions,
-	version: 1 | 2 | 3,
+	version: 1 | 2 | 3 | 4,
 ): IJsonCodec<
 	DecodedMessage<TChangeset>,
 	JsonCompatibleReadOnly,

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

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, oob } from "@fluidframework/core-utils/internal";
 import type {
 	IChannelAttributes,
 	IFluidDataStoreRuntime,
@@ -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.
 	 *
@@ -207,7 +214,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 					change.newCommits.length === 1,
 					0x983 /* Unexpected number of commits when committing transaction */,
 				);
-				this.commitEnricher.prepareCommit(change.newCommits[0], true);
+				this.commitEnricher.prepareCommit(change.newCommits[0] ?? oob(), true);
 			}
 		});
 		this.editManager.localBranch.on("afterChange", (change) => {
@@ -448,7 +455,9 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 			for (const [id, routes] of Object.entries(s.getGCData(fullGC).gcNodes)) {
 				gcNodes[id] ??= [];
 				for (const route of routes) {
-					gcNodes[id].push(route);
+					// Non null asserting here because we are creating an array at gcNodes[id] if it is undefined
+					// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+					gcNodes[id]!.push(route);
 				}
 			}
 		}

package/src/simple-tree/ProxyBinding.md

@@ -24,6 +24,8 @@ This feature is supported by doing some bookkeeping to ensure that the proxy obj
 flex tree nodes and anchor nodes in the tree get associated and disassociated at the right times.
 There are three states that a node proxy can be in: "raw", "marinated" and "cooked".
 
+Note from the public API perspective, `Unhydrated` nodes are "raw", and hydrated nodes are either "marinated" or "cooked".
+
 ### Raw Proxies
 
 A newly created proxy, a.k.a. a **raw** proxy. A raw proxy is produced by invoking the schema-provided constructor for a node:

package/src/simple-tree/api/README.md

@@ -0,0 +1,7 @@
+# simple-tree api
+
+simple-tree content which exists only to implement the public API.
+
+Content in this folder should not be imported from other simple-tree content.
+
+Not all public API types belong here: only ones that the rest of simple tree does not need to depend on for its implementation.