@fluidframework/tree 2.111.0 → 2.113.0-411909

package/src/simple-tree/core/toStored.ts

@@ -6,18 +6,20 @@
 import type { SchemaUpgrade } from "./allowedTypes.js";
 
 /**
- * Options for transforming a view simple-schema to a stored simple-schema (See {@link TreeStoredSchema}).
+ * Policy controlling which staged schema upgrades are included when generating stored schema from a view schema.
+ * @input
+ * @alpha
  */
-export interface StoredFromViewSchemaGenerationOptions {
+export interface StagedSchemaUpgradePolicy {
 	/**
-	 * Determines whether to include {@link SchemaStaticsBeta.staged | staged} allowed types in the resulting stored schema.
+	 * Determines whether to include staged allowed types in the resulting stored schema.
 	 * @remarks
 	 * Due to caching, the behavior of this function must be pure.
 	 */
 	includeStaged(upgrade: SchemaUpgrade): boolean;
 
 	/**
-	 * Determines whether to treat a {@link SchemaFactoryAlpha.stagedOptional | staged optional} field as optional
+	 * Determines whether to treat a staged optional field as optional
 	 * (rather than required) in the resulting stored schema.
 	 * @remarks
 	 * Due to caching, the behavior of this function must be pure.
@@ -25,6 +27,93 @@ export interface StoredFromViewSchemaGenerationOptions {
 	includeStagedOptional(upgrade: SchemaUpgrade): boolean;
 }
 
+/**
+ * Provides factory methods for creating {@link (StagedSchemaUpgradePolicy:interface)} instances.
+ *
+ * @remarks
+ * Use the properties and methods on this object to obtain staged-schema generation options
+ * for different scenarios:
+ *
+ * - {@link StagedSchemaUpgradePolicyFactory.restrictive} — no staged upgrades (default)
+ *
+ * - {@link StagedSchemaUpgradePolicyFactory.permissive} — all staged upgrades enabled
+ *
+ * - {@link StagedSchemaUpgradePolicyFactory.enabledStagedUpgrades} — only specific upgrades enabled
+ *
+ * @example
+ * ```typescript
+ * // Enable specific upgrades:
+ * const options = StagedSchemaUpgradePolicy.enabledStagedUpgrades(myUpgrade);
+ *
+ * // Use restrictive (default, no staged upgrades):
+ * const options = StagedSchemaUpgradePolicy.restrictive;
+ *
+ * // Use permissive (all staged upgrades, useful for testing):
+ * const options = StagedSchemaUpgradePolicy.permissive;
+ * ```
+ *
+ * @sealed
+ * @alpha
+ */
+export interface StagedSchemaUpgradePolicyFactory {
+	/**
+	 * Restrictive policy — excludes all staged schema members.
+	 *
+	 * @remarks
+	 * Use this when you want the most conservative stored schema for compatibility-sensitive
+	 * scenarios, or when staged schema upgrades should remain disabled.
+	 *
+	 * This is the default behavior when no staged upgrades are enabled.
+	 */
+	readonly restrictive: StagedSchemaUpgradePolicy;
+	/**
+	 * Permissive policy — includes all staged schema upgrades.
+	 *
+	 * @remarks
+	 * Use this for testing, validation, and rollout rehearsal scenarios where you want to exercise
+	 * future document shapes before enabling staged upgrades broadly.
+	 */
+	readonly permissive: StagedSchemaUpgradePolicy;
+	/**
+	 * Creates options that include only the specified staged schema upgrades.
+	 *
+	 * @param upgrades - The staged schema upgrades to enable.
+	 * @returns Options that include only the specified upgrades.
+	 *
+	 * @remarks
+	 * If an empty set of upgrades is passed, the result is equivalent to
+	 * `StagedSchemaUpgradePolicy.restrictive`.
+	 */
+	enabledStagedUpgrades(...upgrades: SchemaUpgrade[]): StagedSchemaUpgradePolicy;
+}
+
+/**
+ * {@inheritDoc (StagedSchemaUpgradePolicyFactory:interface)}
+ * @alpha
+ */
+export const StagedSchemaUpgradePolicy: StagedSchemaUpgradePolicyFactory = {
+	restrictive: {
+		includeStaged: () => false,
+		includeStagedOptional: () => false,
+	},
+
+	permissive: {
+		includeStaged: () => true,
+		includeStagedOptional: () => true,
+	},
+
+	enabledStagedUpgrades(...upgrades: SchemaUpgrade[]): StagedSchemaUpgradePolicy {
+		if (upgrades.length === 0) {
+			return StagedSchemaUpgradePolicy.restrictive;
+		}
+		const enabledUpgradeSet = new Set(upgrades);
+		return {
+			includeStaged: (upgrade) => enabledUpgradeSet.has(upgrade),
+			includeStagedOptional: (upgrade) => enabledUpgradeSet.has(upgrade),
+		};
+	},
+};
+
 /**
  * Marker type indicating that the input schema is already a stored schema.
  */
@@ -42,9 +131,7 @@ export type Unchanged = typeof Unchanged;
 /**
  * Subset of {@link SimpleSchemaTransformationOptions} for when the output is a known to be a stored schema.
  */
-export type StoredSchemaGenerationOptions =
-	| StoredFromViewSchemaGenerationOptions
-	| ExpectStored;
+export type StoredSchemaGenerationOptions = StagedSchemaUpgradePolicy | ExpectStored;
 
 /**
  * Options for transforming a schema.
@@ -54,6 +141,6 @@ export type StoredSchemaGenerationOptions =
  * we will need to add a "ToView" option here.
  */
 export type SimpleSchemaTransformationOptions =
-	| StoredFromViewSchemaGenerationOptions
+	| StagedSchemaUpgradePolicy
 	| ExpectStored
 	| Unchanged;

package/src/simple-tree/index.ts

@@ -59,6 +59,8 @@ export {
 	type AllowedTypesFullFromMixed,
 	AnnotatedAllowedTypesInternal,
 	type NumberKeys,
+	StagedSchemaUpgradePolicy,
+	type StagedSchemaUpgradePolicyFactory,
 	ExpectStored,
 	createSchemaUpgrade,
 } from "./core/index.js";
@@ -72,6 +74,7 @@ export {
 	TreeViewConfiguration,
 	TreeViewConfigurationAlpha,
 	type ITreeViewConfiguration,
+	type ITreeViewConfigurationAlpha,
 	type SchemaCompatibilityStatus,
 	type ITreeConfigurationOptions,
 	SchemaFactory,
@@ -140,7 +143,7 @@ export {
 	extractPersistedSchema,
 	comparePersistedSchema,
 	type ConciseTree,
-	SchemaCompatibilityTester,
+	checkSchemaCompatibility,
 	type Unenforced,
 	type System_Unsafe,
 	type ArrayNodeCustomizableSchemaUnsafe,
@@ -317,8 +320,6 @@ export {
 	toUpgradeSchema,
 	toInitialSchema,
 	toUnhydratedSchema,
-	restrictiveStoredSchemaGenerationOptions,
-	permissiveStoredSchemaGenerationOptions,
 } from "./toStoredSchema.js";
 export {
 	numberSchema,

package/src/simple-tree/node-kinds/array/arrayNode.ts

@@ -109,6 +109,14 @@ export interface TreeArrayNode<
 > extends ReadonlyArrayNode<T> {
 	/**
 	 * Inserts new item(s) at a specified location.
+	 *
+	 * @remarks
+	 * All items inserted by a single call to this method are inserted consecutively.
+	 * The order of the inserted items relative to other concurrently inserted items at the same location is only partially specified:
+	 * Concurrently inserting `[A, B]` and `[X, Y]` at the same location may yield
+	 * either `[A, B, X, Y]` or `[X, Y, A, B]`, regardless of the order in which those edits are sequenced.
+	 * No other interleavings are possible. (e.g. `[A, X, B, Y]` is not possible.)
+	 *
 	 * @param index - The index at which to insert `value`.
 	 * @param value - The content to insert.
 	 * @throws Throws if `index` is not in the range [0, `array.length`).
@@ -117,12 +125,18 @@ export interface TreeArrayNode<
 
 	/**
 	 * Inserts new item(s) at the start of the array.
+	 * @remarks
+	 * Equivalent to `insertAt(0, ...value)`:
+	 * see {@link (TreeArrayNode:interface).insertAt} for details, including merge semantics with concurrent edits.
 	 * @param value - The content to insert.
 	 */
 	insertAtStart(...value: readonly (TNew | IterableTreeArrayContent<TNew>)[]): void;
 
 	/**
 	 * Inserts new item(s) at the end of the array.
+	 * @remarks
+	 * Equivalent to `insertAt(array.length, ...value)`:
+	 * see {@link (TreeArrayNode:interface).insertAt} for details, including merge semantics with concurrent edits.
 	 * @param value - The content to insert.
 	 */
 	insertAtEnd(...value: readonly (TNew | IterableTreeArrayContent<TNew>)[]): void;
@@ -131,10 +145,10 @@ export interface TreeArrayNode<
 	 * Inserts new item(s) at the end of the array.
 	 *
 	 * @remarks
-	 * The order of the inserted items relative to other concurrently inserted items at the same location is only partially specified:
-	 * Concurrently inserting `[A, B]` and `[X, Y]` at the same location may yield
-	 * either `[A, B, X, Y]` or `[X, Y, A, B]`, regardless of the order in which those edits are sequenced.
-	 * No other interleavings are possible. (e.g. `[A, X, B, Y]` is not possible.)
+	 * Unlike `Array.prototype.push`, this method does not return the new length of the array.
+	 *
+	 * Equivalent to `insertAt(array.length, ...value)`:
+	 * see {@link (TreeArrayNode:interface).insertAt} for details, including merge semantics with concurrent edits.
 	 *
 	 * @param value - The content to insert.
 	 */
@@ -460,6 +474,87 @@ export interface TreeArrayNodeAlpha<
 		? InsertableTreeNodeFromImplicitAllowedTypes<TAllowedTypes>
 		: InsertableTreeNodeFromImplicitAllowedTypes<ImplicitAllowedTypes>,
 > extends TreeArrayNode<TAllowedTypes, T, TNew> {
+	/**
+	 * Returns the item located at the specified index.
+	 * @param index - The zero-based index of the item to retrieve.
+	 * Negative indices count back from the last item in the array: for `index < 0`, `index + array.length` is used.
+	 * @returns The item at the specified index, or `undefined` if the index is out of bounds.
+	 */
+	at(index: number): T | undefined;
+
+	/**
+	 * Returns the last item in the array for which the given type guard returns `true`,
+	 * searching from the last item to the first.
+	 * @remarks
+	 * The array's length is captured when the search begins; items are read live as the search progresses.
+	 * If `predicate` edits the array, behavior matches {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findLast | Array.prototype.findLast}.
+	 * @typeParam S - The subtype of `T` asserted by the `predicate` type guard.
+	 * @param predicate - Evaluated once per item, starting from the last item and moving towards the first, until it returns `true`.
+	 * Receives the item, its index, and the array being searched.
+	 * @param thisArg - If provided, used as `this` when invoking `predicate`.
+	 * @returns The last item for which `predicate` returns `true` (narrowed to the guarded type), or `undefined` if there is no such item.
+	 */
+	findLast<S extends T>(
+		predicate: (value: T, index: number, array: readonly T[]) => value is S,
+		thisArg?: unknown,
+	): S | undefined;
+
+	/**
+	 * Returns the last item in the array for which the given predicate returns a truthy value,
+	 * searching from the last item to the first.
+	 * @remarks
+	 * The array's length is captured when the search begins; items are read live as the search progresses.
+	 * If `predicate` edits the array, behavior matches {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findLast | Array.prototype.findLast}.
+	 * @param predicate - Evaluated once per item, starting from the last item and moving towards the first, until it returns a truthy value.
+	 * Receives the item, its index, and the array being searched.
+	 * @param thisArg - If provided, used as `this` when invoking `predicate`.
+	 * @returns The last item for which `predicate` returns a truthy value, or `undefined` if there is no such item.
+	 */
+	findLast(
+		predicate: (value: T, index: number, array: readonly T[]) => unknown,
+		thisArg?: unknown,
+	): T | undefined;
+
+	/**
+	 * Returns the index of the last item in the array for which the given predicate returns a truthy value,
+	 * searching from the last item to the first.
+	 * @remarks
+	 * The array's length is captured when the search begins; items are read live as the search progresses.
+	 * If `predicate` edits the array, behavior matches {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findLastIndex | Array.prototype.findLastIndex}.
+	 * @param predicate - Evaluated once per item, starting from the last item and moving towards the first, until it returns a truthy value.
+	 * Receives the item, its index, and the array being searched.
+	 * @param thisArg - If provided, used as `this` when invoking `predicate`.
+	 * @returns The index of the last item for which `predicate` returns a truthy value, or `-1` if there is no such item.
+	 */
+	findLastIndex(
+		predicate: (value: T, index: number, array: readonly T[]) => unknown,
+		thisArg?: unknown,
+	): number;
+
+	/**
+	 * Removes the last item from the array and returns it.
+	 * @returns The removed item, or `undefined` if the array is empty (in which case the array is not modified).
+	 */
+	pop(): T | undefined;
+
+	/**
+	 * Removes the first item from the array and returns it.
+	 * @returns The removed item, or `undefined` if the array is empty (in which case the array is not modified).
+	 */
+	shift(): T | undefined;
+
+	/**
+	 * Inserts new item(s) at the start of the array.
+	 *
+	 * @param value - The content to insert.
+	 * @remarks
+	 * Unlike `Array.prototype.unshift`, this method does not return the new length of the array.
+	 *
+	 * Equivalent to `insertAt(0, ...value)`:
+	 * see {@link (TreeArrayNode:interface).insertAt} for details, including merge semantics with concurrent edits.
+	 */
+	unshift(...value: readonly (TNew | IterableTreeArrayContent<TNew>)[]): void;
+
 	/**
 	 * Removes existing item(s) and/or adds new item(s).
 	 * @param start - The index at which to start changing the array. If negative, it is treated as `array.length + start`.
@@ -995,6 +1090,58 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 
 		return getOrCreateNodeFromInnerNode(val) as TreeNodeFromImplicitAllowedTypes<T>;
 	}
+	public findLast<S extends TreeNodeFromImplicitAllowedTypes<T>>(
+		predicate: (
+			value: TreeNodeFromImplicitAllowedTypes<T>,
+			index: number,
+			array: readonly TreeNodeFromImplicitAllowedTypes<T>[],
+		) => value is S,
+		thisArg?: unknown,
+	): S | undefined;
+	public findLast(
+		predicate: (
+			value: TreeNodeFromImplicitAllowedTypes<T>,
+			index: number,
+			array: readonly TreeNodeFromImplicitAllowedTypes<T>[],
+		) => unknown,
+		thisArg?: unknown,
+	): TreeNodeFromImplicitAllowedTypes<T> | undefined;
+	public findLast(
+		predicate: (
+			value: TreeNodeFromImplicitAllowedTypes<T>,
+			index: number,
+			array: readonly TreeNodeFromImplicitAllowedTypes<T>[],
+		) => unknown,
+		thisArg?: unknown,
+	): TreeNodeFromImplicitAllowedTypes<T> | undefined {
+		const array = this as readonly TreeNodeFromImplicitAllowedTypes<T>[];
+		for (let index = this.length - 1; index >= 0; index--) {
+			const value = this.at(index) as TreeNodeFromImplicitAllowedTypes<T>;
+			const matched = Boolean(predicate.call(thisArg, value, index, array));
+			if (matched) {
+				return value;
+			}
+		}
+		return undefined;
+	}
+	public findLastIndex(
+		predicate: (
+			value: TreeNodeFromImplicitAllowedTypes<T>,
+			index: number,
+			array: readonly TreeNodeFromImplicitAllowedTypes<T>[],
+		) => unknown,
+		thisArg?: unknown,
+	): number {
+		const array = this as readonly TreeNodeFromImplicitAllowedTypes<T>[];
+		for (let index = this.length - 1; index >= 0; index--) {
+			const value = this.at(index) as TreeNodeFromImplicitAllowedTypes<T>;
+			const matched = Boolean(predicate.call(thisArg, value, index, array));
+			if (matched) {
+				return index;
+			}
+		}
+		return -1;
+	}
 	public insertAt(index: number, ...value: Insertable<T>): void {
 		const field = getSequenceField(this);
 		validateIndex(index, field, "TreeArrayNode.insertAt", true);
@@ -1010,6 +1157,23 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 	public push(...value: Insertable<T>): void {
 		this.insertAt(this.length, ...value);
 	}
+	public unshift(...value: Insertable<T>): void {
+		this.insertAt(0, ...value);
+	}
+	public pop(): TreeNodeFromImplicitAllowedTypes<T> | undefined {
+		const value = this.at(-1);
+		if (value !== undefined) {
+			this.removeAt(this.length - 1);
+		}
+		return value;
+	}
+	public shift(): TreeNodeFromImplicitAllowedTypes<T> | undefined {
+		const value = this.at(0);
+		if (value !== undefined) {
+			this.removeAt(0);
+		}
+		return value;
+	}
 	public removeAt(index: number): void {
 		const field = getSequenceField(this);
 		validateIndex(index, field, "TreeArrayNode.removeAt");

package/src/simple-tree/prepareForInsertion.ts

@@ -155,6 +155,18 @@ function validateAndPrepare(
 	mapTrees: readonly UnhydratedFlexTreeNode[],
 	scheduleHydrationOverride?: HydrationScheduler,
 ): void {
+	// Detecting duplicates here is the lowest level spot which is the same for hydrated and un-hydrated parents,
+	// and is also responsible for other validation, so it seem like the best layer to do this check.
+	const seenRoots = new Set<UnhydratedFlexTreeNode>();
+	for (const node of mapTrees) {
+		if (seenRoots.has(node)) {
+			throw new UsageError(
+				`A ${JSON.stringify(node.type)} node was provided more than once in a single insertion. A node may not be in more than one place in the tree.`,
+			);
+		}
+		seenRoots.add(node);
+	}
+
 	if (hydratedData !== undefined) {
 		// Run `prepareContentForHydration` before walking the tree in `isFieldInSchema`.
 		// This ensures that when `isFieldInSchema` requests identifiers (or any other contextual defaults),

package/src/simple-tree/simpleSchemaFormatV1.ts

@@ -7,7 +7,7 @@
  * This file contains a format for serializing the compatibility impacting subset of simple schema.
 
  * This format can be used for both view and stored simple schema.
- * This only includes all parts of the schema that impact compatibility according to SchemaCompatibilityTester.
+ * This only includes all parts of the schema that impact compatibility according to {@link checkSchemaCompatibility}.
  * It may not include some details which impact maintenance of application enforced invariants (like persisted metadata or logic in view schema).
  */
 

package/src/simple-tree/toStoredSchema.ts

@@ -37,9 +37,9 @@ import {
 	ExpectStored,
 	NodeKind,
 	SchemaUpgrade,
+	StagedSchemaUpgradePolicy,
 	Unchanged,
 	type SimpleSchemaTransformationOptions,
-	type StoredFromViewSchemaGenerationOptions,
 	type StoredSchemaGenerationOptions,
 } from "./core/index.js";
 import { FieldKind, normalizeFieldSchema, type ImplicitFieldSchema } from "./fieldSchema.js";
@@ -64,63 +64,68 @@ import { createTreeSchema } from "./treeSchema.js";
 // The simple-schema related logic from this file and src/simple-tree/core/toStored.ts can be unified and `toStoredSchema` and its other ImplicitFieldSchema consuming variants should probably be removed in favor of acting on TreeSchema and SimpleTreeSchema directly.
 
 const viewToStoredCache = new WeakMap<
-	StoredFromViewSchemaGenerationOptions,
+	StagedSchemaUpgradePolicy,
 	WeakMap<ImplicitFieldSchema, TreeStoredSchema>
 >();
 
-/**
- * Maximally restrictive transformation of a view to stored schema.
- * @remarks
- * This should only be used when the intent is to produce a stored schema is as restrictive as possible while still being compatible with the input view schema.
- * This is typically used for cases where backwards compatibility with past versions of an application is required, like {@link toUpgradeSchema} or {@link toInitialSchema}.
- */
-export const restrictiveStoredSchemaGenerationOptions: StoredFromViewSchemaGenerationOptions =
-	{
-		includeStaged: () => false,
-		includeStagedOptional: () => false,
-	};
+function isStagedSchemaUpgradePolicy(
+	stagedSchemaUpgrades: Iterable<SchemaUpgrade> | StagedSchemaUpgradePolicy,
+): stagedSchemaUpgrades is StagedSchemaUpgradePolicy {
+	return (
+		typeof stagedSchemaUpgrades === "object" &&
+		"includeStaged" in stagedSchemaUpgrades &&
+		"includeStagedOptional" in stagedSchemaUpgrades
+	);
+}
 
 /**
- * Maximally permissive transformation of a view to stored schema.
+ * Resolves a collection of staged schema upgrades into stored-schema generation options.
  * @remarks
- * This should only be used when the intent is to produce a stored schema which allows as much as possible while still being compatible with the input view schema.
- * This is typically used for cases where forwards compatibility with future versions of an application is required, like {@link toUnhydratedSchema}.
- *
- * This is unable to include unknown optional fields in the output, which makes it not truly maximally permissive.
- *
- * TODO: {@link StoredFromViewSchemaGenerationOptions} could be updated to allow a way to inject extra optional fields.
- * If done, then this could take in an existing stored schema, and attempt to generate a valid superset.
- * This could be useful to use as the schema for unhydrated content cloned from hydrated content.
+ * If `stagedSchemaUpgrades` is omitted, returns restrictive options.
  */
-export const permissiveStoredSchemaGenerationOptions: StoredFromViewSchemaGenerationOptions = {
-	includeStaged: () => true,
-	includeStagedOptional: () => true,
-};
+export function resolveStoredSchemaGenerationOptions(
+	stagedSchemaUpgrades?: Iterable<SchemaUpgrade> | StagedSchemaUpgradePolicy,
+): StagedSchemaUpgradePolicy {
+	if (stagedSchemaUpgrades === undefined) {
+		return StagedSchemaUpgradePolicy.restrictive;
+	}
+
+	if (isStagedSchemaUpgradePolicy(stagedSchemaUpgrades)) {
+		return stagedSchemaUpgrades;
+	}
+
+	return StagedSchemaUpgradePolicy.enabledStagedUpgrades(...stagedSchemaUpgrades);
+}
 
 /**
  * Converts a {@link ImplicitFieldSchema} into a {@link TreeStoredSchema} for use in schema upgrades.
- *
- * TODO: once upgrades are more flexible, this should take in more options, including the old schema and specific upgrades to enable.
  */
-export function toUpgradeSchema(root: ImplicitFieldSchema): TreeStoredSchema {
-	return toStoredSchema(root, restrictiveStoredSchemaGenerationOptions);
+export function toUpgradeSchema(
+	root: ImplicitFieldSchema,
+	stagedSchemaUpgrades?: Iterable<SchemaUpgrade> | StagedSchemaUpgradePolicy,
+): TreeStoredSchema {
+	return toStoredSchema(root, resolveStoredSchemaGenerationOptions(stagedSchemaUpgrades));
 }
 
 /**
  * Converts a {@link ImplicitFieldSchema} into a {@link TreeStoredSchema} for use as initial document schema.
  */
-export function toInitialSchema(root: ImplicitFieldSchema): TreeStoredSchema {
-	return toStoredSchema(root, restrictiveStoredSchemaGenerationOptions);
+export function toInitialSchema(
+	root: ImplicitFieldSchema,
+	stagedSchemaUpgrades?: Iterable<SchemaUpgrade> | StagedSchemaUpgradePolicy,
+): TreeStoredSchema {
+	return toStoredSchema(root, resolveStoredSchemaGenerationOptions(stagedSchemaUpgrades));
 }
 
 /**
- * Converts a {@link ImplicitFieldSchema} into a {@link TreeStoredSchema} to used for unhydrated nodes.
+ * Permissive staged schema upgrade policy used for unhydrated node schema generation.
  * @remarks
  * This allows as much as possible, relying on further validation when inserting the content.
  *
  * TODO: this should get additional options to enable support for unknown optional fields.
  */
-export const toUnhydratedSchema = permissiveStoredSchemaGenerationOptions;
+export const toUnhydratedSchema: StagedSchemaUpgradePolicy =
+	StagedSchemaUpgradePolicy.permissive;
 
 /**
  * Converts a {@link ImplicitFieldSchema} into a {@link TreeStoredSchema}.
@@ -137,7 +142,7 @@ export const toUnhydratedSchema = permissiveStoredSchemaGenerationOptions;
  */
 export function toStoredSchema(
 	root: ImplicitFieldSchema,
-	options: StoredFromViewSchemaGenerationOptions,
+	options: StagedSchemaUpgradePolicy,
 ): TreeStoredSchema {
 	const cache = getOrCreate(viewToStoredCache, options, () => new WeakMap());
 	return getOrCreate(cache, root, () => {
@@ -152,7 +157,7 @@ export function toStoredSchema(
  */
 export function transformSimpleSchema(
 	schema: SimpleTreeSchema<SchemaType.View>,
-	options: StoredFromViewSchemaGenerationOptions,
+	options: StagedSchemaUpgradePolicy,
 ): SimpleTreeSchema<SchemaType.Stored>;
 
 /**
@@ -324,7 +329,7 @@ export function getStoredSchema(
  */
 export function transformSimpleNodeSchema(
 	schema: SimpleNodeSchema<SchemaType.View>,
-	options: StoredFromViewSchemaGenerationOptions,
+	options: StagedSchemaUpgradePolicy,
 ): SimpleNodeSchema<SchemaType.Stored>;
 
 /**
@@ -483,7 +488,7 @@ function allowedTypeFilter(
 	if (options === ExpectStored) {
 		if (data.isStaged !== undefined) {
 			throw new UsageError(
-				"Failed to covert view schema to stored schema. The simple schema provided was indicated to be a stored schema by the use of `ExpectStored`, but view schema specific content was encountered which requires a `StoredFromViewSchemaGenerationOptions` to process.",
+				"Failed to covert view schema to stored schema. The simple schema provided was indicated to be a stored schema by the use of `ExpectStored`, but view schema specific content was encountered which requires a `StagedSchemaUpgradePolicy` to process.",
 			);
 		}
 		return true;
@@ -505,7 +510,7 @@ function allowedTypeFilter(
 
 function isStoredFromView(
 	options: SimpleSchemaTransformationOptions,
-): options is StoredFromViewSchemaGenerationOptions {
+): options is StagedSchemaUpgradePolicy {
 	return typeof options === "object" && "includeStaged" in options;
 }
 

package/src/treeFactory.ts

@@ -77,7 +77,7 @@ function treeKernelFactory(
 		};
 
 		return new SharedTreeKernel(
-			new Breakable("SharedTree"),
+			new Breakable("SharedTree", args.logger),
 			args.sharedObject,
 			args.serializer,
 			args.submitLocalMessage,

package/src/util/breakable.ts

@@ -4,7 +4,7 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
-import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import { UsageError, type TelemetryLoggerExt } from "@fluidframework/telemetry-utils/internal";
 
 /**
  * An object which can enter a "broken" state where trying to use it is a UsageError.
@@ -22,6 +22,13 @@ export class Breakable {
 		 * This is useful for documenting the semantics of a given Breakable and when inspecting things in the debugger, but is currently otherwise unused.
 		 */
 		private readonly name: string,
+		/**
+		 * Optional logger for telemetry.
+		 * @remarks
+		 * When provided, subsystems that have access to a Breakable can use this logger to emit telemetry
+		 * without requiring additional plumbing.
+		 */
+		public readonly logger?: TelemetryLoggerExt,
 	) {}
 
 	/**