@fluidframework/tree 2.0.0-dev-rc.1.0.0.224419

package/src/feature-libraries/flex-tree/navigation.ts

@@ -0,0 +1,121 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export const Skip = Symbol("Skip");
+export type Skip = typeof Skip;
+
+/**
+ * Visit iterable tree.
+ *
+ * @remarks
+ * Non-recursive depth first traversal.
+ */
+export function visitIterableTree<T>(
+	root: T,
+	iterator: (t: T) => Iterable<T>,
+	visitor: (item: T) => Skip | void,
+): void {
+	const queue: Iterable<T>[] = [[root]];
+	let next: Iterable<T> | undefined;
+	while ((next = queue.pop())) {
+		for (const child of next) {
+			if (visitor(child) !== Skip) {
+				queue.push(iterator(child));
+			}
+		}
+	}
+}
+
+/**
+ * Visit iterable tree.
+ * Allows state to be computed in parents and passed to children.
+ *
+ * @remarks
+ * Non-recursive depth first traversal.
+ */
+export function visitIterableTreeWithState<T extends Iterable<T>, StatePassedDown>(
+	root: T,
+	initial: StatePassedDown,
+	visitor: (item: T, fromAbove: StatePassedDown) => Skip | StatePassedDown,
+): void {
+	const queue: [StatePassedDown, Iterable<T>][] = [[initial, root]];
+	let next: [StatePassedDown, Iterable<T>] | undefined;
+	while ((next = queue.pop())) {
+		const [state, nestItem] = next;
+		for (const child of nestItem) {
+			const result = visitor(child, state);
+			if (result !== Skip) {
+				queue.push([result, child]);
+			}
+		}
+	}
+}
+
+/**
+ * Visit bipartite iterable tree.
+ *
+ * @remarks
+ * Non-recursive depth first traversal.
+ *
+ * Particularly useful for processing trees with their alternating node and field levels.
+ */
+export function visitBipartiteIterableTree<A extends Iterable<B>, B extends Iterable<A>>(
+	root: A,
+	visitorA: (item: A) => Skip | undefined,
+	visitorB: (item: B) => Skip | undefined,
+) {
+	const queueA = [root];
+	let nextA: A | undefined;
+	while ((nextA = queueA.pop())) {
+		if (visitorA(nextA) !== Skip) {
+			for (const nextB of nextA) {
+				if (visitorB(nextB) !== Skip) {
+					for (const child of nextB) {
+						queueA.push(child);
+					}
+				}
+			}
+		}
+	}
+}
+
+/**
+ * Visit bipartite iterable tree.
+ * Allows state to be computed in parents and passed to children.
+ *
+ * @remarks
+ * Non-recursive depth first traversal.
+ *
+ * Particularly useful for processing trees with their alternating node and field levels.
+ *
+ * @privateRemarks
+ * Other traversal cases, like ones passing data up (via map or reduce patterns) could be supported by extending this or adding more utilities.
+ * Such utility functions really only provide an improvement of hand coding each cases if the non-recessiveness is required.
+ * Since supporting very deeps trees hasn't been a priority, such visitors are also not a priority, and are thus not included here for now.
+ */
+export function visitBipartiteIterableTreeWithState<A, B, StateA, StateB>(
+	root: A,
+	fromAbove: StateA,
+	iterateA: (a: A) => Iterable<B>,
+	iterateB: (b: B) => Iterable<A>,
+	visitorA: (item: A, fromAbove: StateA) => Skip | StateB,
+	visitorB: (item: B, fromAbove: StateB) => Skip | StateA,
+) {
+	const queueA: [A, StateA][] = [[root, fromAbove]];
+	let next: [A, StateA] | undefined;
+	while ((next = queueA.pop())) {
+		const result = visitorA(...next);
+		if (result !== Skip) {
+			for (const nextB of iterateA(next[0])) {
+				const resultB = visitorB(nextB, result);
+				if (resultB !== Skip) {
+					for (const child of iterateB(nextB)) {
+						queueA.push([child, resultB]);
+					}
+				}
+			}
+		}
+	}
+}

package/src/feature-libraries/flex-tree/nodeKeys.ts

@@ -0,0 +1,51 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { LocalNodeKey, NodeKeyIndex, NodeKeyManager, StableNodeKey } from "../node-key";
+import { FlexTreeObjectNode } from "./flexTreeTypes";
+
+/**
+ * A collection of utilities for managing {@link StableNodeKey}s.
+ * A node key can be assigned to a node and allows that node to be easily retrieved from the tree at a later time. (see `nodeKey.map`).
+ * @remarks {@link LocalNodeKey}s are put on {@link FlexTreeObjectNode}s via a special field.
+ * A node with a node key in its schema must always have a node key.
+ * @internal
+ */
+export interface NodeKeys {
+	/**
+	 * Create a new {@link LocalNodeKey} which can be used as the key for a node in the tree.
+	 */
+	generate(): LocalNodeKey;
+	/**
+	 * Convert the given {@link LocalNodeKey} into a UUID that can be serialized.
+	 * @param key - the key to convert
+	 */
+	stabilize(key: LocalNodeKey): StableNodeKey;
+	/**
+	 * Convert a {@link StableNodeKey} back into its {@link LocalNodeKey} form.
+	 * @param key - the key to convert
+	 */
+	localize(key: StableNodeKey): LocalNodeKey;
+	/**
+	 * A map of all {@link LocalNodeKey}s in the document to their corresponding nodes.
+	 */
+	readonly map: ReadonlyMap<LocalNodeKey, FlexTreeObjectNode>;
+}
+
+export class SimpleNodeKeys implements NodeKeys {
+	public constructor(
+		public readonly map: NodeKeyIndex,
+		private readonly manager: NodeKeyManager,
+	) {}
+	public generate(): LocalNodeKey {
+		return this.manager.generateLocalNodeKey();
+	}
+	public stabilize(key: LocalNodeKey): StableNodeKey {
+		return this.manager.stabilizeNodeKey(key);
+	}
+	public localize(key: StableNodeKey): LocalNodeKey {
+		return this.manager.localizeNodeKey(key);
+	}
+}

package/src/feature-libraries/flex-tree/treeEvents.ts

@@ -0,0 +1,117 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { UpPath, PathVisitor } from "../../core";
+import { FlexTreeNode } from "./flexTreeTypes";
+
+/**
+ * This file provides an API for working with trees which is type safe even when schema is not known.
+ * This means no editing is allowed.
+ *
+ * Schema aware APIs for working with trees should superset this, while sub-setting EditableTree.
+ *
+ * TODO:
+ * This API should replace EditableTree as the default public API for tree access.
+ * SchemaAware builds on this, adding editing and type safe APIs which can be accessed via SchematizeView.
+ * Once this is finished, the unsafe EditableTree types can be removed (or converted to package internal documentation for the proxies).
+ */
+
+/**
+ * An event raised on a {@link FlexTreeNode}.
+ *
+ * @internal
+ */
+export interface TreeEvent {
+	/**
+	 * The node of the tree where the listener receiving the event is attached.
+	 */
+	readonly target: FlexTreeNode;
+}
+
+/**
+ * A collection of events that can be raised by a {@link FlexTreeNode}.
+ * These events are triggered while the internal data structures are being updated.
+ * Thus these events must not trigger reading of the anchorSet or forest.
+ *
+ * TODO:
+ * - Design how events should be ordered.
+ * - Include sub-deltas in events.
+ * - Add more events.
+ * - Have some events (or a way to defer events) until the tree can be read.
+ *
+ * @internal
+ */
+export interface EditableTreeEvents {
+	/**
+	 * Raised when a specific EditableTree node is changing.
+	 * This includes its fields.
+	 * @param upPath - the path corresponding to the location of the node being changed, upward.
+	 */
+	changing(upPath: UpPath): void;
+
+	/**
+	 * Raised when something in the tree is changing, including this node and its descendants.
+	 * The event can optionally return a {@link PathVisitor} to traverse the subtree
+	 * This event is called on every parent (transitively) when a change is occurring.
+	 * Includes changes to this node itself.
+	 * @param upPath - the path corresponding to the location of the node being changed, upward.
+	 * @returns a visitor to traverse the subtree or `void`.
+	 */
+	subtreeChanging(upPath: UpPath): PathVisitor | void;
+
+	/**
+	 * Raised on a node right before a change is applied to one of its fields or the fields of a descendant node.
+	 *
+	 * @param event - The event object. See {@link TreeEvent} for details.
+	 *
+	 * @remarks
+	 * What exactly qualifies as a change that triggers this event (or {@link EditableTreeEvents.afterChange}) is dependent
+	 * on the implementation of SharedTree. In general, these events will fire once for every atomic editing operation
+	 * supported by SharedTree; {@link EditableTreeEvents.beforeChange} before the change is applied, and
+	 * {@link EditableTreeEvents.afterChange} after it is.
+	 *
+	 * {@link FieldKinds.sequence} fields present two exceptions:
+	 *
+	 * The first one is that events will fire separately for each node involved in the operation (when inserting, removing,
+	 * or moving more than one node at a time). This means that, for example, when inserting two nodes into a {@link FieldKinds.sequence}
+	 * field the following will happen:
+	 * - {@link EditableTreeEvents.beforeChange} will fire once before either new node is present in the tree.
+	 * - {@link EditableTreeEvents.afterChange} will fire once after the first node is present in the tree, but the second one isn't.
+	 * - {@link EditableTreeEvents.beforeChange} will fire once before the second node is present in the tree, but the first one already is.
+	 * - {@link EditableTreeEvents.afterChange} will fire once after the second node is present in the tree (so at this point both nodes are).
+	 * Something similar applies to removing nodes from a sequence, and moving them to another sequence.
+	 *
+	 * The second one is that for an operation to move nodes, events will fire *twice* for each node being moved; once
+	 * while they are being detached from their source location, and once when they are being attached at the target location.
+	 */
+	beforeChange(event: TreeEvent): void;
+
+	/**
+	 * Raised on a node right after a change is applied to one of its fields or the fields of a descendant node.
+	 *
+	 * @param event - The event object. See {@link TreeEvent} for details.
+	 *
+	 * @remarks
+	 * What exactly qualifies as a change that triggers this event (or {@link EditableTreeEvents.beforeChange}) is dependent
+	 * on the implementation of SharedTree. In general, these events will fire once for every atomic editing operation supported
+	 * by SharedTree; {@link EditableTreeEvents.beforeChange} before the change is applied, and
+	 * {@link EditableTreeEvents.afterChange} after it is.
+	 *
+	 * {@link FieldKinds.sequence} present two exceptions:
+	 *
+	 * The first one is that events will fire separately for each node involved in the operation (when inserting, removing,
+	 * or moving more than one node at a time). This means that, for example, when inserting two nodes into a {@link FieldKinds.sequence}
+	 * field the following will happen:
+	 * - {@link EditableTreeEvents.beforeChange} will fire once before either new node is present in the tree.
+	 * - {@link EditableTreeEvents.afterChange} will fire once after the first node is present in the tree, but the second one isn't.
+	 * - {@link EditableTreeEvents.beforeChange} will fire once before the second node is present in the tree, but the first one already is.
+	 * - {@link EditableTreeEvents.afterChange} will fire once after the second node is present in the tree (so at this point both nodes are).
+	 * Something similar applies to removing nodes from a sequence, and moving them to another sequence.
+	 *
+	 * The second one is that for an operation to move nodes, events will fire *twice* for each node being moved; once
+	 * while they are being detached from their source location, and once when they are being attached at the target location.
+	 */
+	afterChange(event: TreeEvent): void;
+}

package/src/feature-libraries/flex-tree/unboxed.ts

@@ -0,0 +1,77 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ITreeSubscriptionCursor, inCursorNode } from "../../core";
+import { FieldKind } from "../modular-schema";
+import { FieldKinds } from "../default-schema";
+import { AllowedTypes, TreeFieldSchema, TreeNodeSchema, schemaIsLeaf } from "../typed-schema";
+import { Context } from "./context";
+import {
+	FlexTreeNode,
+	FlexTreeUnboxField,
+	FlexTreeUnboxNode,
+	FlexTreeUnboxNodeUnion,
+} from "./flexTreeTypes";
+import { makeTree } from "./lazyNode";
+import { makeField } from "./lazyField";
+
+/**
+ * See {@link FlexTreeUnboxNode} for documentation on what unwrapping this performs.
+ */
+export function unboxedTree<TSchema extends TreeNodeSchema>(
+	context: Context,
+	schema: TSchema,
+	cursor: ITreeSubscriptionCursor,
+): FlexTreeUnboxNode<TSchema> {
+	if (schemaIsLeaf(schema)) {
+		return cursor.value as FlexTreeUnboxNode<TSchema>;
+	}
+
+	return makeTree(context, cursor) as FlexTreeNode as FlexTreeUnboxNode<TSchema>;
+}
+
+/**
+ * See {@link FlexTreeUnboxNodeUnion} for documentation on what unwrapping this performs.
+ */
+export function unboxedUnion<TTypes extends AllowedTypes>(
+	context: Context,
+	schema: TreeFieldSchema<FieldKind, TTypes>,
+	cursor: ITreeSubscriptionCursor,
+): FlexTreeUnboxNodeUnion<TTypes> {
+	const type = schema.monomorphicChildType;
+	if (type !== undefined) {
+		return unboxedTree(context, type, cursor) as FlexTreeUnboxNodeUnion<TTypes>;
+	}
+	return makeTree(context, cursor) as FlexTreeUnboxNodeUnion<TTypes>;
+}
+
+/**
+ * @param context - the common context of the field.
+ * @param schema - the TreeFieldStoredSchema of the field.
+ * @param cursor - the cursor, which must point to the field being proxified.
+ */
+export function unboxedField<TSchema extends TreeFieldSchema>(
+	context: Context,
+	schema: TSchema,
+	cursor: ITreeSubscriptionCursor,
+): FlexTreeUnboxField<TSchema> {
+	const kind = schema.kind;
+	if (kind === FieldKinds.required) {
+		return inCursorNode(cursor, 0, (innerCursor) =>
+			unboxedUnion(context, schema, innerCursor),
+		) as FlexTreeUnboxField<TSchema>;
+	}
+	if (kind === FieldKinds.optional) {
+		if (cursor.getFieldLength() === 0) {
+			return undefined as FlexTreeUnboxField<TSchema>;
+		}
+		return inCursorNode(cursor, 0, (innerCursor) =>
+			unboxedUnion(context, schema, innerCursor),
+		) as FlexTreeUnboxField<TSchema>;
+	}
+
+	// TODO: forbidden and nodeKey
+	return makeField(context, schema, cursor) as FlexTreeUnboxField<TSchema>;
+}

package/src/feature-libraries/flex-tree/utilities.ts

@@ -0,0 +1,74 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+	AnchorNode,
+	AnchorSet,
+	DetachedField,
+	anchorSlot,
+	getDetachedFieldContainingPath,
+	rootField,
+} from "../../core";
+import { TreeStatus } from "./flexTreeTypes";
+/**
+ * Checks the detached field and returns the TreeStatus based on whether or not the detached field is a root field.
+ * @param detachedField - the detached field you want to check.
+ * @returns the {@link TreeStatus} from the detached field provided.
+ */
+export function treeStatusFromDetachedField(detachedField: DetachedField): TreeStatus {
+	return detachedField === rootField ? TreeStatus.InDocument : TreeStatus.Removed;
+}
+
+/**
+ * Determines the tree status based on the anchor cache.
+ *
+ * Checks the anchorNode's cache to get the tree status.
+ * If the cache is undefined or stale, it is updated and the treeStatus based on its detachedField is returned.
+ *
+ * @param anchors - the {@link AnchorSet} to compare your anchorNode cache to.
+ * @param anchorNode - the {@link AnchorNode} to get the {@link TreeStatus} of.
+ * @returns - the {@link TreeStatus} of the anchorNode provided.
+ */
+export function treeStatusFromAnchorCache(anchors: AnchorSet, anchorNode: AnchorNode): TreeStatus {
+	const cache = anchorNode.slots.get(detachedFieldSlot);
+	if (cache === undefined) {
+		// If the cache is undefined, set the cache and return the treeStatus based on the detached field.
+		return treeStatusFromDetachedField(
+			getCachedUpdatedDetachedField(anchorNode, anchors.generationNumber),
+		);
+	} else {
+		// If the cache is up to date, return the treeStatus based on the cached detached field.
+		const currentGenerationNumber = anchors.generationNumber;
+		if (cache.generationNumber === currentGenerationNumber) {
+			return treeStatusFromDetachedField(cache.detachedField);
+		}
+		// If the cache is not up to date, update the cache and return the treeStatus based on the updated detached field.
+		return treeStatusFromDetachedField(
+			getCachedUpdatedDetachedField(anchorNode, currentGenerationNumber),
+		);
+	}
+}
+
+/**
+ * Updates the anchorNode cache with the provided generation number, and returns its detachedField.
+ */
+function getCachedUpdatedDetachedField(
+	anchorNode: AnchorNode,
+	generationNumber: number,
+): DetachedField {
+	const detachedField = getDetachedFieldContainingPath(anchorNode);
+	anchorNode.slots.set(detachedFieldSlot, {
+		generationNumber,
+		detachedField,
+	});
+	return detachedField;
+}
+
+export const detachedFieldSlot = anchorSlot<DetachedFieldCache>();
+
+export interface DetachedFieldCache {
+	generationNumber: number;
+	detachedField: DetachedField;
+}

package/src/feature-libraries/forest-summary/codec.ts

@@ -0,0 +1,50 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils";
+import { ICodecOptions, IJsonCodecWithContext } from "../../codec";
+import { FieldKey, ITreeCursorSynchronous } from "../../core";
+import { FieldBatchCodec } from "../chunked-forest";
+// eslint-disable-next-line import/no-internal-modules
+import { Context } from "../chunked-forest/codec/codecs";
+import { makeVersionedValidatedCodec } from "../versioned";
+import { Format } from "./format";
+
+/**
+ * Uses field cursors
+ */
+export type FieldSet = ReadonlyMap<FieldKey, ITreeCursorSynchronous>;
+export type ForestCodec = IJsonCodecWithContext<FieldSet, Format, Format, Context>;
+
+export function makeForestSummarizerCodec(
+	options: ICodecOptions,
+	fieldBatchCodec: FieldBatchCodec,
+): ForestCodec {
+	// TODO: every time context changes, withSchemaValidation and makeVersionedCodec recompile their json validators.
+	// Those should be reused. Making more code context aware could fix that.
+	return (context: Context) => {
+		const inner = fieldBatchCodec(context);
+		return makeVersionedValidatedCodec(options, new Set([1]), Format, {
+			encode: (data: FieldSet): Format => {
+				const keys: FieldKey[] = [];
+				const fields: ITreeCursorSynchronous[] = [];
+				for (const [key, value] of data) {
+					keys.push(key);
+					fields.push(value);
+				}
+				return { keys, fields: inner.encode(fields), version: 1 };
+			},
+			decode: (data: Format): FieldSet => {
+				const out: Map<FieldKey, ITreeCursorSynchronous> = new Map();
+				const fields = inner.decode(data.fields);
+				assert(data.keys.length === fields.length, "mismatched lengths");
+				for (let index = 0; index < fields.length; index++) {
+					out.set(data.keys[index], fields[index]);
+				}
+				return out;
+			},
+		});
+	};
+}

package/src/feature-libraries/forest-summary/forestSummarizer.ts

@@ -0,0 +1,176 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { bufferToString } from "@fluid-internal/client-utils";
+import { IChannelStorageService } from "@fluidframework/datastore-definitions";
+import {
+	ITelemetryContext,
+	ISummaryTreeWithStats,
+	IGarbageCollectionData,
+} from "@fluidframework/runtime-definitions";
+import { createSingleBlobSummary } from "@fluidframework/shared-object-base";
+import { assert } from "@fluidframework/core-utils";
+import {
+	applyDelta,
+	DeltaFieldChanges,
+	FieldKey,
+	forEachField,
+	IEditableForest,
+	ITreeCursorSynchronous,
+	ITreeSubscriptionCursor,
+	makeDetachedFieldIndex,
+	mapCursorField,
+	TreeNavigationResult,
+	TreeStoredSchemaSubscription,
+} from "../../core";
+import {
+	Summarizable,
+	SummaryElementParser,
+	SummaryElementStringifier,
+} from "../../shared-tree-core";
+import { idAllocatorFromMaxId } from "../../util";
+import { ICodecOptions, noopValidator } from "../../codec";
+import { FieldBatchCodec } from "../chunked-forest";
+import { FullSchemaPolicy } from "../modular-schema";
+import { TreeCompressionStrategy } from "../treeCompressionUtils";
+// eslint-disable-next-line import/no-internal-modules
+import { chunkField, defaultChunkPolicy } from "../chunked-forest/chunkTree";
+import { Format } from "./format";
+import { ForestCodec, makeForestSummarizerCodec } from "./codec";
+/**
+ * The storage key for the blob in the summary containing tree data
+ */
+const treeBlobKey = "ForestTree";
+
+/**
+ * Provides methods for summarizing and loading a forest.
+ */
+export class ForestSummarizer implements Summarizable {
+	public readonly key = "Forest";
+
+	private lazyCodec?: ReturnType<ForestCodec>;
+	private get codec(): ReturnType<ForestCodec> {
+		this.lazyCodec ??= makeForestSummarizerCodec(
+			this.options,
+			this.fieldBatchCodec,
+		)({
+			schema: { schema: this.schema, policy: this.policy },
+			encodeType: this.encodeType,
+		});
+		return this.lazyCodec;
+	}
+
+	public constructor(
+		private readonly forest: IEditableForest,
+		private readonly schema: TreeStoredSchemaSubscription,
+		private readonly policy: FullSchemaPolicy,
+		private readonly encodeType: TreeCompressionStrategy,
+		private readonly fieldBatchCodec: FieldBatchCodec,
+		private readonly options: ICodecOptions = { jsonValidator: noopValidator },
+	) {
+		this.schema.on("beforeSchemaChange", () => {
+			this.lazyCodec = undefined;
+		});
+	}
+
+	/**
+	 * Synchronous monolithic summarization of tree content.
+	 *
+	 * TODO: when perf matters, this should be replaced with a chunked async version using a binary format.
+	 *
+	 * @returns a snapshot of the forest's tree as a string.
+	 */
+	private getTreeString(stringify: SummaryElementStringifier): string {
+		const rootCursor = this.forest.getCursorAboveDetachedFields();
+		const fieldMap: Map<FieldKey, ITreeCursorSynchronous & ITreeSubscriptionCursor> = new Map();
+		// TODO: Encode all detached fields in one operation for better performance and compression
+		forEachField(rootCursor, (cursor) => {
+			const key = cursor.getFieldKey();
+			const innerCursor = this.forest.allocateCursor();
+			assert(
+				this.forest.tryMoveCursorToField(
+					{ fieldKey: key, parent: undefined },
+					innerCursor,
+				) === TreeNavigationResult.Ok,
+				"failed to navigate to field",
+			);
+			fieldMap.set(key, innerCursor as ITreeCursorSynchronous & ITreeSubscriptionCursor);
+		});
+		const encoded = this.codec.encode(fieldMap);
+
+		fieldMap.forEach((value) => value.free());
+		return stringify(encoded);
+	}
+
+	public getAttachSummary(
+		stringify: SummaryElementStringifier,
+		fullTree?: boolean,
+		trackState?: boolean,
+		telemetryContext?: ITelemetryContext,
+	): ISummaryTreeWithStats {
+		return createSingleBlobSummary(treeBlobKey, this.getTreeString(stringify));
+	}
+
+	public async summarize(
+		stringify: SummaryElementStringifier,
+		fullTree?: boolean,
+		trackState?: boolean,
+		telemetryContext?: ITelemetryContext,
+	): Promise<ISummaryTreeWithStats> {
+		return createSingleBlobSummary(treeBlobKey, this.getTreeString(stringify));
+	}
+
+	public getGCData(fullGC?: boolean): IGarbageCollectionData {
+		// TODO: Properly implement garbage collection. Right now, garbage collection is performed automatically
+		// by the code in SharedObject (from which SharedTreeCore extends). The `runtime.uploadBlob` API delegates
+		// to the `BlobManager`, which automatically populates the summary with ISummaryAttachment entries for each
+		// blob.
+		return {
+			gcNodes: {},
+		};
+	}
+
+	public async load(
+		services: IChannelStorageService,
+		parse: SummaryElementParser,
+	): Promise<void> {
+		if (await services.contains(treeBlobKey)) {
+			const treeBuffer = await services.readBlob(treeBlobKey);
+			const treeBufferString = bufferToString(treeBuffer, "utf8");
+			// TODO: this code is parsing data without an optional validator, this should be defined in a typebox schema as part of the
+			// forest summary format.
+			const fields = this.codec.decode(parse(treeBufferString) as Format);
+			const allocator = idAllocatorFromMaxId();
+			const fieldChanges: [FieldKey, DeltaFieldChanges][] = [];
+			for (const [fieldKey, field] of fields) {
+				const chunked = chunkField(field, defaultChunkPolicy);
+				const nodeCursors = chunked.flatMap((chunk) =>
+					mapCursorField(chunk.cursor(), (cursor) => cursor.fork()),
+				);
+				const buildId = { minor: allocator.allocate(nodeCursors.length) };
+
+				fieldChanges.push([
+					fieldKey,
+					{
+						build: [
+							{
+								id: buildId,
+								trees: nodeCursors,
+							},
+						],
+						local: [{ count: nodeCursors.length, attach: buildId }],
+					},
+				]);
+			}
+
+			assert(this.forest.isEmpty, 0x797 /* forest must be empty */);
+			applyDelta(
+				{ fields: new Map(fieldChanges) },
+				this.forest,
+				makeDetachedFieldIndex("init"),
+			);
+		}
+	}
+}

package/src/feature-libraries/forest-summary/format.ts

@@ -0,0 +1,21 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Static, Type } from "@sinclair/typebox";
+import { schemaFormat } from "../../core";
+import { Versioned } from "../versioned";
+
+export const version = 1.0;
+
+export const Format = Type.Object(
+	{
+		version: Type.Literal(version),
+		keys: Type.Array(schemaFormat.FieldKeySchema),
+		fields: Versioned,
+	},
+	{ additionalProperties: false },
+);
+
+export type Format = Static<typeof Format>;