@fluidframework/tree 2.73.0 → 2.74.0-368706

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

@@ -62,9 +62,16 @@ import {
 import type { DecodedMessage } from "./messageTypes.js";
 import type { ResubmitMachine } from "./resubmitMachine.js";
 import type { MessageFormatVersion } from "./messageFormat.js";
-
-// TODO: Organize this to be adjacent to persisted types.
-const summarizablesTreeKey = "indexes";
+import {
+	minVersionToSharedTreeSummaryFormatVersion,
+	summarizablesTreeKey,
+	supportedSharedTreeSummaryFormatVersions,
+	type SharedTreeSummaryFormatVersion,
+	type Summarizable,
+	type SummaryElementParser,
+	type SummaryElementStringifier,
+} from "./summaryTypes.js";
+import { VersionedSummarizer } from "./versionedSummarizer.js";
 
 export interface ClonableSchemaAndPolicy extends SchemaAndPolicy {
 	schema: TreeStoredSchemaRepository;
@@ -73,14 +80,17 @@ export interface ClonableSchemaAndPolicy extends SchemaAndPolicy {
 export interface SharedTreeCoreOptionsInternal
 	extends CodecWriteOptions,
 		EditManagerCodecOptions,
-		MessageCodecOptions {}
+		MessageCodecOptions {
+	canMakeDetachedRootEdits: boolean;
+}
 
 /**
  * Generic shared tree, which needs to be configured with indexes, field kinds and other configuration.
  */
 @breakingClass
 export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
-	implements WithBreakable
+	extends VersionedSummarizer<SharedTreeSummaryFormatVersion>
+	implements WithBreakable, Summarizable
 {
 	private readonly editManager: EditManager<TEditor, TChange, ChangeFamily<TEditor, TChange>>;
 	private readonly summarizables: readonly [EditManagerSummarizer<TChange>, ...Summarizable[]];
@@ -139,6 +149,13 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 		enricher?: ChangeEnricherReadonlyCheckout<TChange>,
 		public readonly getEditor: () => TEditor = () => this.getLocalBranch().editor,
 	) {
+		super(
+			summarizablesTreeKey,
+			minVersionToSharedTreeSummaryFormatVersion(options.minVersionForCollab),
+			supportedSharedTreeSummaryFormatVersions,
+			true /* supportPreVersioningFormat */,
+		);
+
 		this.schemaAndPolicy = {
 			schema,
 			policy: schemaPolicy,
@@ -161,6 +178,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 			localSessionId,
 			this.mintRevisionTag,
 			(branchId) => this.registerSharedBranch(branchId),
+			options,
 			rebaseLogger,
 		);
 
@@ -178,6 +196,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 				this.editManager,
 				editManagerCodec,
 				this.idCompressor,
+				options.minVersionForCollab,
 				this.schemaAndPolicy,
 			),
 			...summarizables,
@@ -203,14 +222,16 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 
 	// TODO: SharedObject's merging of the two summary methods into summarizeCore is not what we want here:
 	// We might want to not subclass it, or override/reimplement most of its functionality.
-	@throwIfBroken
-	public summarizeCore(
-		serializer: IFluidSerializer,
-		telemetryContext?: ITelemetryContext,
-		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext,
-		fullTree?: boolean,
-	): ISummaryTreeWithStats {
-		const builder = new SummaryTreeBuilder();
+	protected summarizeInternal(props: {
+		stringify: SummaryElementStringifier;
+		fullTree?: boolean;
+		trackState?: boolean;
+		telemetryContext?: ITelemetryContext;
+		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext;
+		builder: SummaryTreeBuilder;
+	}): void {
+		const { stringify, fullTree, telemetryContext, incrementalSummaryContext, builder } =
+			props;
 		const summarizableBuilder = new SummaryTreeBuilder();
 		// Merge the summaries of all summarizables together under a single ISummaryTree
 		for (const s of this.summarizables) {
@@ -226,28 +247,24 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 			summarizableBuilder.addWithStats(
 				s.key,
 				s.summarize({
-					stringify: (contents: unknown) =>
-						serializer.stringify(contents, this.sharedObject.handle),
+					stringify,
 					fullTree,
 					telemetryContext,
 					incrementalSummaryContext: childIncrementalSummaryContext,
 				}),
 			);
 		}
-
 		builder.addWithStats(summarizablesTreeKey, summarizableBuilder.getSummaryTree());
-		return builder.getSummaryTree();
 	}
 
-	public async loadCore(services: IChannelStorageService): Promise<void> {
-		assert(
-			this.getLocalBranch().getHead() === this.editManager.getTrunkHead("main"),
-			0xaaa /* All local changes should be applied to the trunk before loading from summary */,
-		);
+	protected async loadInternal(
+		services: IChannelStorageService,
+		parse: SummaryElementParser,
+	): Promise<void> {
 		const [editManagerSummarizer, ...summarizables] = this.summarizables;
-		const loadEditManager = this.loadSummarizable(editManagerSummarizer, services);
+		const loadEditManager = this.loadSummarizable(editManagerSummarizer, services, parse);
 		const loadSummarizables = summarizables.map(async (s) =>
-			this.loadSummarizable(s, services),
+			this.loadSummarizable(s, services, parse),
 		);
 
 		if (this.detachedRevision !== undefined) {
@@ -268,6 +285,30 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 		}
 	}
 
+	@throwIfBroken
+	public summarizeCore(
+		serializer: IFluidSerializer,
+		telemetryContext?: ITelemetryContext,
+		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext,
+		fullTree?: boolean,
+	): ISummaryTreeWithStats {
+		return this.summarize({
+			stringify: (contents: unknown) =>
+				serializer.stringify(contents, this.sharedObject.handle),
+			fullTree,
+			telemetryContext,
+			incrementalSummaryContext,
+		});
+	}
+
+	public async loadCore(services: IChannelStorageService): Promise<void> {
+		assert(
+			this.getLocalBranch().getHead() === this.editManager.getTrunkHead("main"),
+			0xaaa /* All local changes should be applied to the trunk before loading from summary */,
+		);
+		await super.load(services, (contents) => this.serializer.parse(contents));
+	}
+
 	private registerSharedBranch(branchId: BranchId): void {
 		this.editManager.getLocalBranch(branchId).events.on("beforeChange", (change) => {
 			if (change.type === "append") {
@@ -286,10 +327,11 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 	private async loadSummarizable(
 		summarizable: Summarizable,
 		services: IChannelStorageService,
+		parse: SummaryElementParser,
 	): Promise<void> {
 		return summarizable.load(
 			scopeStorageService(services, summarizablesTreeKey, summarizable.key),
-			(contents) => this.serializer.parse(contents),
+			parse,
 		);
 	}
 
@@ -646,57 +688,6 @@ function isClonableSchemaPolicy(
 	return schemaAndPolicy.schema !== undefined && schemaAndPolicy.policy !== undefined;
 }
 
-/**
- * Specifies the behavior of a component that puts data in a summary.
- */
-export interface Summarizable {
-	/**
-	 * Field name in summary json under which this element stores its data.
-	 */
-	readonly key: string;
-
-	/**
-	 * {@inheritDoc @fluidframework/datastore-definitions#(IChannel:interface).summarize}
-	 * @param stringify - Serializes the contents of the component (including {@link (IFluidHandle:interface)}s) for storage.
-	 * @param fullTree - A flag indicating whether the attempt should generate a full
-	 * summary tree without any handles for unchanged subtrees. It should only be set to true when generating
-	 * a summary from the entire container. The default value is false.
-	 * @param trackState - An optimization for tracking state of objects across summaries. If the state
-	 * of an object did not change since last successful summary, an
-	 * {@link @fluidframework/protocol-definitions#ISummaryHandle} can be used
-	 * instead of re-summarizing it. If this is `false`, the expectation is that you should never
-	 * send an `ISummaryHandle`, since you are not expected to track state. The default value is true.
-	 * @param telemetryContext - See {@link @fluidframework/runtime-definitions#ITelemetryContext}.
-	 * @param incrementalSummaryContext - See {@link @fluidframework/runtime-definitions#IExperimentalIncrementalSummaryContext}.
-	 */
-	summarize(props: {
-		stringify: SummaryElementStringifier;
-		fullTree?: boolean;
-		trackState?: boolean;
-		telemetryContext?: ITelemetryContext;
-		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext;
-	}): ISummaryTreeWithStats;
-
-	/**
-	 * Allows the component to perform custom loading. The storage service is scoped to this component and therefore
-	 * paths in this component will not collide with those in other components, even if they are the same string.
-	 * @param service - Storage used by the component
-	 * @param parse - Parses serialized data from storage into runtime objects for the component
-	 */
-	load(service: IChannelStorageService, parse: SummaryElementParser): Promise<void>;
-}
-
-/**
- * Serializes the given contents into a string acceptable for storing in summaries, i.e. all
- * Fluid handles have been replaced appropriately by an IFluidSerializer
- */
-export type SummaryElementStringifier = (contents: unknown) => string;
-
-/**
- * Parses a serialized/summarized string into an object, rehydrating any Fluid handles as necessary
- */
-export type SummaryElementParser = (contents: string) => unknown;
-
 /**
  * Compose an {@link IChannelStorageService} which prefixes all paths before forwarding them to the original service
  */

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

@@ -0,0 +1,122 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
+import type {
+	IExperimentalIncrementalSummaryContext,
+	ISummaryTreeWithStats,
+	ITelemetryContext,
+	MinimumVersionForCollab,
+} from "@fluidframework/runtime-definitions/internal";
+
+// TODO: Organize this to be adjacent to persisted types.
+/**
+ * The storage key for the subtree containing all summarizable indexes in the SharedTree summary.
+ */
+export const summarizablesTreeKey = "indexes";
+
+/**
+ * The storage key for the blob containing metadata for the summarizable's summary.
+ */
+export const summarizablesMetadataKey = ".metadata";
+
+/**
+ * Specifies the behavior of a component that puts data in a summary.
+ */
+export interface Summarizable {
+	/**
+	 * Field name in summary json under which this element stores its data.
+	 */
+	readonly key: string;
+
+	/**
+	 * {@inheritDoc @fluidframework/datastore-definitions#(IChannel:interface).summarize}
+	 * @param stringify - Serializes the contents of the component (including {@link (IFluidHandle:interface)}s) for storage.
+	 * @param fullTree - A flag indicating whether the attempt should generate a full
+	 * summary tree without any handles for unchanged subtrees. It should only be set to true when generating
+	 * a summary from the entire container. The default value is false.
+	 * @param trackState - An optimization for tracking state of objects across summaries. If the state
+	 * of an object did not change since last successful summary, an
+	 * {@link @fluidframework/protocol-definitions#ISummaryHandle} can be used
+	 * instead of re-summarizing it. If this is `false`, the expectation is that you should never
+	 * send an `ISummaryHandle`, since you are not expected to track state. The default value is true.
+	 * @param telemetryContext - See {@link @fluidframework/runtime-definitions#ITelemetryContext}.
+	 * @param incrementalSummaryContext - See {@link @fluidframework/runtime-definitions#IExperimentalIncrementalSummaryContext}.
+	 */
+	summarize(props: {
+		stringify: SummaryElementStringifier;
+		fullTree?: boolean;
+		trackState?: boolean;
+		telemetryContext?: ITelemetryContext;
+		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext;
+	}): ISummaryTreeWithStats;
+
+	/**
+	 * Allows the component to perform custom loading. The storage service is scoped to this component and therefore
+	 * paths in this component will not collide with those in other components, even if they are the same string.
+	 * @param service - Storage used by the component
+	 * @param parse - Parses serialized data from storage into runtime objects for the component
+	 */
+	load(service: IChannelStorageService, parse: SummaryElementParser): Promise<void>;
+}
+
+/**
+ * Serializes the given contents into a string acceptable for storing in summaries, i.e. all
+ * Fluid handles have been replaced appropriately by an IFluidSerializer
+ */
+export type SummaryElementStringifier = (contents: unknown) => string;
+
+/**
+ * Parses a serialized/summarized string into an object, rehydrating any Fluid handles as necessary
+ */
+export type SummaryElementParser = (contents: string) => unknown;
+
+/**
+ * The type for the metadata in the summarizable's summary.
+ * The metadata is stored under the {@link summarizablesMetadataKey} key in the summary.
+ * @remarks
+ * This is common metadata used by all summarizables. If a summarizable needs to add more metadata,
+ * it should define its own metadata type that extends this type.
+ */
+// Using type definition instead of interface to make this compatible with JsonCompatible.
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+export type SharedTreeSummarizableMetadata = {
+	/** The version of the SharedTree summary. */
+	readonly version: number;
+};
+
+/**
+ * The versions for the SharedTree summary format.
+ */
+export const enum SharedTreeSummaryFormatVersion {
+	/**
+	 * This version represents summary format before summary versioning was introduced.
+	 */
+	v1 = 1,
+	/**
+	 * This version adds metadata to the summary. This is backward compatible with version 1.
+	 */
+	v2 = 2,
+	/**
+	 * The latest version of the SharedTree summary. Must be updated when a new version is added.
+	 */
+	vLatest = v2,
+}
+
+export const supportedSharedTreeSummaryFormatVersions =
+	new Set<SharedTreeSummaryFormatVersion>([
+		SharedTreeSummaryFormatVersion.v1,
+		SharedTreeSummaryFormatVersion.v2,
+	]);
+
+/**
+ * Returns the summary version to use as per the given minimum version for collab.
+ */
+export function minVersionToSharedTreeSummaryFormatVersion(
+	version: MinimumVersionForCollab,
+): SharedTreeSummaryFormatVersion {
+	// Currently, version 2 is written which adds metadata blob to the summary.
+	return SharedTreeSummaryFormatVersion.v2;
+}

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

@@ -0,0 +1,107 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils/internal";
+import type { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
+import type {
+	IExperimentalIncrementalSummaryContext,
+	ISummaryTreeWithStats,
+	ITelemetryContext,
+} from "@fluidframework/runtime-definitions/internal";
+import { SummaryTreeBuilder } from "@fluidframework/runtime-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import {
+	summarizablesMetadataKey,
+	type SharedTreeSummarizableMetadata,
+	type Summarizable,
+	type SummaryElementParser,
+	type SummaryElementStringifier,
+} from "./summaryTypes.js";
+import { readAndParseSnapshotBlob } from "../util/index.js";
+
+/**
+ * Utility for implementing {@link Summarizable}s classes with versioning.
+ * It handles versioning of summaries - writing version metadata to summaries
+ * and checking version compatibility when loading.
+ */
+export abstract class VersionedSummarizer<TVersion extends number> implements Summarizable {
+	public constructor(
+		/** {@link Summarizable.key} */
+		public readonly key: string,
+		/** The format version of the summary to write in the summary metadata. */
+		private readonly writeVersion: TVersion,
+		/** The set of supported versions that a summary can have for this summarizer to load it. */
+		private readonly supportedVersions: ReadonlySet<TVersion>,
+		/**
+		 * Whether to support loading summaries before versioning was added, i.e., summaries without metadata blob.
+		 * @remarks
+		 * This version may not be supported if the support for the version before metadata blob was dropped.
+		 * In that case, this will not be present in `supportedVersions` and an error will be thrown during load.
+		 */
+		private readonly supportPreVersioningFormat: boolean,
+	) {
+		assert(
+			this.supportedVersions.has(this.writeVersion),
+			`Write version ${this.writeVersion} must be supported.`,
+		);
+	}
+
+	/**
+	 * The summarize function that derived classes must implement. They should use the passed summary tree builder to
+	 * add their summary data.
+	 */
+	protected abstract summarizeInternal(props: {
+		stringify: SummaryElementStringifier;
+		fullTree?: boolean;
+		trackState?: boolean;
+		telemetryContext?: ITelemetryContext;
+		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext;
+		builder: SummaryTreeBuilder;
+	}): void;
+
+	/**
+	 * The load function that derived classes must implement to load their summary data.
+	 */
+	protected abstract loadInternal(
+		services: IChannelStorageService,
+		parse: SummaryElementParser,
+	): Promise<void>;
+
+	public summarize(props: {
+		stringify: SummaryElementStringifier;
+		fullTree?: boolean;
+		trackState?: boolean;
+		telemetryContext?: ITelemetryContext;
+		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext;
+	}): ISummaryTreeWithStats {
+		const builder = new SummaryTreeBuilder();
+		const metadata: SharedTreeSummarizableMetadata = {
+			version: this.writeVersion,
+		};
+		builder.addBlob(summarizablesMetadataKey, props.stringify(metadata));
+		this.summarizeInternal({ ...props, builder });
+		return builder.getSummaryTree();
+	}
+
+	public async load(
+		services: IChannelStorageService,
+		parse: SummaryElementParser,
+	): Promise<void> {
+		if (await services.contains(summarizablesMetadataKey)) {
+			const metadata = await readAndParseSnapshotBlob<SharedTreeSummarizableMetadata>(
+				summarizablesMetadataKey,
+				services,
+				(contents) => parse(contents),
+			);
+			const version = metadata.version as TVersion;
+			if (!this.supportedVersions.has(version)) {
+				throw new UsageError(`Cannot read version ${version} of shared tree summary.`);
+			}
+		} else if (!this.supportPreVersioningFormat) {
+			throw new UsageError(`Cannot read summary without versioning for shared tree summary.`);
+		}
+		await this.loadInternal(services, parse);
+	}
+}

package/src/simple-tree/api/configuration.ts

@@ -3,31 +3,19 @@
  * Licensed under the MIT License.
  */
 
-import {
-	assert,
-	debugAssert,
-	fail,
-	oob,
-	unreachableCase,
-} from "@fluidframework/core-utils/internal";
+import { assert, fail, oob, unreachableCase } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import {
-	type FieldSchemaAlpha,
-	type ImplicitFieldSchema,
-	FieldKind,
-	normalizeFieldSchema,
-} from "../fieldSchema.js";
+import { type FieldSchemaAlpha, type ImplicitFieldSchema, FieldKind } from "../fieldSchema.js";
 import {
 	type AllowedTypesFullEvaluated,
 	NodeKind,
 	type TreeNodeSchema,
-	markSchemaMostDerived,
 } from "../core/index.js";
 import {
-	permissiveStoredSchemaGenerationOptions,
-	restrictiveStoredSchemaGenerationOptions,
-	toStoredSchema,
+	toInitialSchema,
+	toUnhydratedSchema,
+	transformSimpleSchema,
 } from "../toStoredSchema.js";
 import {
 	isArrayNodeSchema,
@@ -42,7 +30,8 @@ import {
 import { getOrCreate } from "../../util/index.js";
 import type { MakeNominal } from "../../util/index.js";
 import { walkFieldSchema } from "../walkFieldSchema.js";
-import type { SimpleNodeSchema, SimpleTreeSchema } from "../simpleSchema.js";
+import type { SchemaType, SimpleNodeSchema } from "../simpleSchema.js";
+import { createTreeSchema, type TreeSchema } from "../treeSchema.js";
 
 /**
  * Options when constructing a tree view.
@@ -187,11 +176,6 @@ export class TreeViewConfiguration<
 	 */
 	public readonly preventAmbiguity!: boolean;
 
-	/**
-	 * {@link TreeSchema.definitions} but with public types.
-	 */
-	protected readonly definitionsInternal!: ReadonlyMap<string, TreeNodeSchema>;
-
 	/**
 	 * Construct a new {@link TreeViewConfiguration}.
 	 *
@@ -225,23 +209,10 @@ export class TreeViewConfiguration<
 		// Ambiguity errors are lower priority to report than invalid schema errors, so collect these in an array and report them all at once.
 		const ambiguityErrors: string[] = [];
 
-		// Eagerly perform this conversion to surface errors sooner.
-		// Includes detection of duplicate schema identifiers.
-		toStoredSchema(config.schema, restrictiveStoredSchemaGenerationOptions);
-		toStoredSchema(config.schema, permissiveStoredSchemaGenerationOptions);
-
-		const definitions = new Map<string, SimpleNodeSchema & TreeNodeSchema>();
-
+		// Validate the schema and collect ambiguity errors.
+		// This does a lot of validation (throwing usage errors as a side effect) in addition to just collecting ambiguity errors.
+		// ambiguityErrors are considered a lower priority, so only thrown if no other errors are found.
 		walkFieldSchema(config.schema, {
-			node: (schema) => {
-				// Ensure all reachable schema are marked as most derived.
-				// This ensures if multiple schema extending the same schema factory generated class are present (or have had instances of them constructed, or get instances of them constructed in the future),
-				// an error is reported.
-				markSchemaMostDerived(schema, true);
-
-				debugAssert(() => !definitions.has(schema.identifier));
-				definitions.set(schema.identifier, schema as SimpleNodeSchema & TreeNodeSchema);
-			},
 			allowedTypes({ types }: AllowedTypesFullEvaluated): void {
 				checkUnion(
 					types.map((t) => t.type),
@@ -251,8 +222,6 @@ export class TreeViewConfiguration<
 			},
 		});
 
-		this.definitionsInternal = definitions;
-
 		if (ambiguityErrors.length !== 0) {
 			// Duplicate errors are common since when two types conflict, both orders error:
 			const deduplicated = new Set(ambiguityErrors);
@@ -273,38 +242,22 @@ export class TreeViewConfigurationAlpha<
 	extends TreeViewConfiguration<TSchema>
 	implements TreeSchema
 {
-	/**
-	 * {@inheritDoc TreeSchema.root}
-	 */
 	public readonly root: FieldSchemaAlpha;
-
-	/**
-	 * {@inheritDoc TreeSchema.definitions}
-	 */
-	public get definitions(): ReadonlyMap<string, SimpleNodeSchema & TreeNodeSchema> {
-		return this.definitionsInternal as ReadonlyMap<string, SimpleNodeSchema & TreeNodeSchema>;
-	}
+	public readonly definitions: ReadonlyMap<
+		string,
+		SimpleNodeSchema<SchemaType.View> & TreeNodeSchema
+	>;
 
 	public constructor(props: ITreeViewConfiguration<TSchema>) {
 		super(props);
-		this.root = normalizeFieldSchema(props.schema);
-	}
-}
+		const treeSchema = createTreeSchema(this.schema);
+		this.root = treeSchema.root;
+		this.definitions = treeSchema.definitions;
 
-/**
- * {@link TreeViewConfigurationAlpha}
- * @sealed @alpha
- */
-export interface TreeSchema extends SimpleTreeSchema {
-	/**
-	 * {@inheritDoc SimpleTreeSchema.root}
-	 */
-	readonly root: FieldSchemaAlpha;
-
-	/**
-	 * {@inheritDoc SimpleTreeSchema.definitions}
-	 */
-	readonly definitions: ReadonlyMap<string, SimpleNodeSchema & TreeNodeSchema>;
+		// Eagerly perform these conversions to surface errors sooner.
+		toInitialSchema(this.root);
+		transformSimpleSchema(treeSchema, toUnhydratedSchema);
+	}
 }
 
 /**

package/src/simple-tree/api/dirtyIndex.ts

@@ -23,6 +23,10 @@ import type { ImplicitFieldSchema } from "../fieldSchema.js";
  * * "new": The node was added.
  * * "changed": A direct child was updated, added, removed, or moved (and the node is not "new").
  * * "moved": The node was moved between/within arrays (and the node is not "new" or "changed").
+ * @privateRemarks
+ * It is unclear how this will handle forward compatibility with other kinds of edits, like moves that are not limited to arrays (attach, detach, swap):
+ * this needs to be sorted out before this is stabilized.
+ * It is also unclear how this is supposed to handle schema changes (which can result in new TreeNode instance, but I think won't trigger "new" here).
  * @alpha
  */
 export type DirtyTreeStatus = "new" | "changed" | "moved";
@@ -51,6 +55,13 @@ export interface DirtyTreeMap {
  * console.log(`The root of the tree is ${dirty.get(view.root) ?? "unchanged"}`);
  * stopTracking();
  * ```
+ * @privateRemarks
+ * This provides an opportunity for user code ("set" on dirty) to run during forest changes, in the middle of processing an edit.
+ * We have generally avoided exposing such times to users and instead flush events after the edit has finished and user facing invariants are known to be restored.
+ * Before stabilizing, how this event relates to other events time/ordering wise should be clarified, and if any APIs have been provided to defer events, that mentioned as well.
+ * Maybe updates should be deferred?
+ *
+ * This is also documented in terms of "forest" which is not a concept in the public API, and thus needs to be redefined in terms of public concepts.
  * @alpha
  */
 export function trackDirtyNodes(

package/src/simple-tree/api/discrepancies.ts

@@ -43,7 +43,7 @@ import {
 	type FieldSchema,
 } from "../fieldSchema.js";
 import { LeafNodeSchema } from "../leafNodeSchema.js";
-import type { TreeSchema } from "./configuration.js";
+import type { TreeSchema } from "../treeSchema.js";
 import { tryStoredSchemaAsArray } from "./customTree.js";
 import { FieldKinds } from "../../feature-libraries/index.js";
 

package/src/simple-tree/api/getSimpleSchema.ts

@@ -3,13 +3,14 @@
  * Licensed under the MIT License.
  */
 
+import { Unchanged } from "../core/index.js";
 import type { ImplicitFieldSchema } from "../fieldSchema.js";
-import type { SimpleTreeSchema } from "../simpleSchema.js";
-
-import { toSimpleTreeSchema } from "./viewSchemaToSimpleSchema.js";
+import type { SchemaType, SimpleTreeSchema } from "../simpleSchema.js";
+import { transformSimpleSchema } from "../toStoredSchema.js";
+import { createTreeSchema } from "../treeSchema.js";
 
 /**
- * Copies data from {@link ImplicitFieldSchema} to create  a {@link SimpleTreeSchema} out of new plain JavaScript objects, Sets and Maps.
+ * Copies data from {@link ImplicitFieldSchema} to create a {@link SimpleTreeSchema} out of new plain JavaScript objects, Sets and Maps.
  *
  * @remarks
  * See also {@link TreeViewConfigurationAlpha} which implements {@link SimpleTreeSchema} as a way to get a `SimpleTreeSchema` without copying the node and field schema and without losing as much type information.
@@ -23,6 +24,12 @@ import { toSimpleTreeSchema } from "./viewSchemaToSimpleSchema.js";
  *
  * @alpha
  */
-export function getSimpleSchema(schema: ImplicitFieldSchema): SimpleTreeSchema {
-	return toSimpleTreeSchema(schema, true);
+export function getSimpleSchema(
+	schema: ImplicitFieldSchema,
+): SimpleTreeSchema<SchemaType.View> {
+	// Convert the input into a TreeSchema: This API should probably be updated to take in a TreeSchema directly
+	// (and maybe a clean way to make TreeSchema from ImplicitFieldSchema other than TreeViewConfigurationAlpha should be provided).
+	const treeSchema = createTreeSchema(schema);
+	// Do the actual copy into clean simple schema objects.
+	return transformSimpleSchema(treeSchema, Unchanged);
 }