@fluidframework/tree 2.53.0 → 2.60.0

package/src/shared-tree/sharedTree.ts

@@ -35,6 +35,7 @@ import {
 	SchemaVersion,
 	type TaggedChange,
 	type TreeFieldStoredSchema,
+	type TreeNodeSchemaIdentifier,
 	type TreeNodeStoredSchema,
 	type TreeStoredSchema,
 	TreeStoredSchemaRepository,
@@ -56,6 +57,7 @@ import {
 	makeMitigatedChangeFamily,
 	makeSchemaCodec,
 	makeTreeChunker,
+	type TreeCompressionStrategyPrivate,
 } from "../feature-libraries/index.js";
 // eslint-disable-next-line import/no-internal-modules
 import type { FormatV1 } from "../feature-libraries/schema-index/index.js";
@@ -271,6 +273,7 @@ export class SharedTreeKernel
 			encoderContext,
 			options,
 			idCompressor,
+			options.shouldEncodeFieldIncrementally,
 		);
 		const removedRootsSummarizer = new DetachedFieldIndexSummarizer(removedRoots);
 		const innerChangeFamily = new SharedTreeChangeFamily(
@@ -582,12 +585,25 @@ export type SharedTreeOptions = Partial<CodecWriteOptions> &
 	Partial<SharedTreeFormatOptions> &
 	ForestOptions;
 
-export interface SharedTreeOptionsInternal extends SharedTreeOptions {
+export interface SharedTreeOptionsInternal
+	extends Omit<SharedTreeOptions, "treeEncodeType">,
+		Partial<SharedTreeFormatOptionsInternal> {
 	disposeForksAfterTransaction?: boolean;
+	/**
+	 * Returns whether a field should be incrementally encoded.
+	 * @param nodeIdentifier - The identifier of the node containing the field.
+	 * @param fieldKey - The key of the field to check.
+	 * @remarks
+	 * The policy for which fields should get incremental encoding should eventually be specified some other way.
+	 */
+	shouldEncodeFieldIncrementally?(
+		nodeIdentifier: TreeNodeSchemaIdentifier,
+		fieldKey: FieldKey,
+	): boolean;
 }
 /**
  * Configuration options for SharedTree's internal tree storage.
- * @alpha
+ * @beta @input
  */
 export interface ForestOptions {
 	/**
@@ -598,7 +614,7 @@ export interface ForestOptions {
 
 /**
  * Options for configuring the persisted format SharedTree uses.
- * @alpha
+ * @alpha @input
  */
 export interface SharedTreeFormatOptions {
 	/**
@@ -620,11 +636,22 @@ export interface SharedTreeFormatOptions {
 	formatVersion: SharedTreeFormatVersion[keyof SharedTreeFormatVersion];
 }
 
+export interface SharedTreeFormatOptionsInternal
+	extends Omit<SharedTreeFormatOptions, "treeEncodeType"> {
+	treeEncodeType: TreeCompressionStrategyPrivate;
+}
+
 /**
  * Used to distinguish between different forest types.
  * @remarks
+ * The "Forest" is the internal data structure used to store all the trees (the main tree and any removed ones) for a given view or branch.
+ * ForestTypes should all have the same behavior, but may differ in performance and debuggability.
+ *
  * Current options are {@link ForestTypeReference}, {@link ForestTypeOptimized} and {@link ForestTypeExpensiveDebug}.
- * @sealed @alpha
+ * @privateRemarks
+ * Implement using {@link toForestType}.
+ * Consume using {@link buildConfiguredForest}.
+ * @sealed @beta
  */
 export interface ForestType extends ErasedType<"ForestType"> {}
 
@@ -698,6 +725,12 @@ export const defaultSharedTreeOptions: Required<SharedTreeOptionsInternal> = {
 	treeEncodeType: TreeCompressionStrategy.Compressed,
 	formatVersion: SharedTreeFormatVersion.v3,
 	disposeForksAfterTransaction: true,
+	shouldEncodeFieldIncrementally: (
+		nodeIdentifier: TreeNodeSchemaIdentifier,
+		fieldKey: FieldKey,
+	): boolean => {
+		return false;
+	},
 };
 
 function exportSimpleFieldSchemaStored(schema: TreeFieldStoredSchema): SimpleFieldSchema {

package/src/shared-tree/sharedTreeChangeFamily.ts

@@ -23,7 +23,7 @@ import {
 	ModularChangeFamily,
 	type ModularChangeset,
 	type TreeChunk,
-	type TreeCompressionStrategy,
+	type TreeCompressionStrategyPrivate,
 	fieldKindConfigurations,
 	fieldKinds,
 	makeModularChangeCodecFamily,
@@ -61,7 +61,7 @@ export class SharedTreeChangeFamily
 		revisionTagCodec: RevisionTagCodec,
 		fieldBatchCodec: FieldBatchCodec,
 		codecOptions: ICodecOptions,
-		chunkCompressionStrategy?: TreeCompressionStrategy,
+		chunkCompressionStrategy?: TreeCompressionStrategyPrivate,
 		private readonly idCompressor?: IIdCompressor,
 	) {
 		const modularChangeCodec = makeModularChangeCodecFamily(

package/src/shared-tree/tree.ts

@@ -60,6 +60,9 @@ export interface Tree extends TreeNodeApi {
 export const Tree: Tree = {
 	...treeNodeApi,
 
+	// Note: the implementation details of `createRunTransaction` are deprecated.
+	// We have introduced replacement `@alpha` APIs on `TreeBranch`, but until they are `@public`, we can't reasonably deprecated this.
+	// Once they have been promoted to public, we can deprecate this API.
 	runTransaction: createRunTransaction(),
 
 	contains(parent: TreeNode, child: TreeNode): boolean {

package/src/shared-tree/treeAlpha.ts

@@ -54,6 +54,7 @@ import {
 	toInitialSchema,
 	convertField,
 	toUnhydratedSchema,
+	type TreeParsingOptions,
 } from "../simple-tree/index.js";
 import { brand, extractFromOpaque, type JsonCompatible } from "../util/index.js";
 import {
@@ -201,7 +202,7 @@ export interface TreeIdentifierUtils {
  * Note that {@link (TreeBeta:interface).clone} can create an unhydrated node with unknown optional fields, as it uses the source node's stored schema (if any).
  *
  * Export APIs in this interface include {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields | unknown optional fields}
- * if they are using {@link TreeEncodingOptions.useStoredKeys | stored keys}.
+ * if they are using {@link KeyEncodingOptions.allStoredKeys}.
  *
  * @privateRemarks
  * TODO:
@@ -273,18 +274,16 @@ export interface TreeAlpha {
 	 * @param schema - The schema for what to construct. As this is an {@link ImplicitFieldSchema}, a {@link FieldSchema}, {@link TreeNodeSchema} or {@link AllowedTypes} array can be provided.
 	 * @param data - The data used to construct the field content. See {@link (TreeAlpha:interface).(exportVerbose:1)}.
 	 * @remarks
-	 * This currently does not support input containing {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields| unknown optional fields}.
-	 * @privateRemarks
-	 * See TODOs in {@link TreeEncodingOptions}.
-	 *
-	 * TODO: clarify how this handles out of schema data.
-	 * Does it robustly validate? How do you use it with schema evolution features like staged allowed types and allowUnknownOptionalFields? Which errors are deferred until insertion/hydration?
-	 * Ensure whatever policy is chosen is documented, enforces, tested and applied consistently to all import code paths.
+	 * This currently does not support input containing
+	 * {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields| unknown optional fields} but does support
+	 * {@link SchemaStaticsAlpha.staged | staged} allowed types.
+	 * Non-empty default values for fields are currently not supported (must be provided in the input).
+	 * The content will be validated against the schema and an error will be thrown if out of schema.
 	 */
 	importVerbose<const TSchema extends ImplicitFieldSchema>(
 		schema: TSchema,
 		data: VerboseTree | undefined,
-		options?: Partial<TreeEncodingOptions>,
+		options?: TreeParsingOptions,
 	): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
 
 	/**
@@ -322,7 +321,7 @@ export interface TreeAlpha {
 	 * If an `idCompressor` is provided, it will be used to compress identifiers and thus will be needed to decompress the data.
 	 *
 	 * Always uses "stored" keys.
-	 * See {@link TreeEncodingOptions.useStoredKeys} for details.
+	 * See {@link KeyEncodingOptions.allStoredKeys} for details.
 	 * @privateRemarks
 	 * TODO: It is currently not clear how to work with the idCompressors correctly in the package API.
 	 * Better APIs should probably be provided as there is currently no way to associate an un-hydrated tree with an idCompressor,
@@ -482,7 +481,7 @@ export const TreeAlpha: TreeAlpha = {
 	importVerbose<const TSchema extends ImplicitFieldSchema>(
 		schema: TSchema,
 		data: VerboseTree | undefined,
-		options?: TreeEncodingOptions,
+		options?: TreeParsingOptions,
 	): Unhydrated<TreeFieldFromImplicitField<TSchema>> {
 		const config: TreeEncodingOptions = { ...options };
 		// Create a config which is standalone, and thus can be used without having to refer back to the schema.

package/src/shared-tree/treeCheckout.ts

@@ -50,7 +50,7 @@ import {
 } from "../core/index.js";
 import {
 	type FieldBatchCodec,
-	type TreeCompressionStrategy,
+	type TreeCompressionStrategyPrivate,
 	allowsRepoSuperset,
 	buildForest,
 	createNodeIdentifierManager,
@@ -286,7 +286,7 @@ export function createTreeCheckout(
 		forest?: IEditableForest;
 		fieldBatchCodec?: FieldBatchCodec;
 		removedRoots?: DetachedFieldIndex;
-		chunkCompressionStrategy?: TreeCompressionStrategy;
+		chunkCompressionStrategy?: TreeCompressionStrategyPrivate;
 		logger?: ITelemetryLoggerExt;
 		breaker?: Breakable;
 		disposeForksAfterTransaction?: boolean;

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

@@ -6,6 +6,7 @@
 import type { IFluidLoadable, ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
 import { assert } from "@fluidframework/core-utils/internal";
 import type { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
+import type { ISnapshotTree } from "@fluidframework/driver-definitions/internal";
 import type { IIdCompressor, SessionId } from "@fluidframework/id-compressor";
 import type {
 	IExperimentalIncrementalSummaryContext,
@@ -517,5 +518,21 @@ function scopeStorageService(
 		async list(path) {
 			return service.list(`${scope}${path}`);
 		},
+		getSnapshotTree(): ISnapshotTree | undefined {
+			const snapshotTree = service.getSnapshotTree?.();
+			if (snapshotTree === undefined) {
+				return undefined;
+			}
+			let scopedTree = snapshotTree;
+			for (const element of pathElements) {
+				const tree = scopedTree.trees[element];
+				assert(
+					tree !== undefined,
+					0xc20 /* snapshot tree not found for one of tree's summarizables */,
+				);
+				scopedTree = tree;
+			}
+			return scopedTree;
+		},
 	};
 }

package/src/sharedTreeAttributes.ts

@@ -9,14 +9,14 @@ import { pkgVersion } from "./packageVersion.js";
 
 /**
  * {@inheritDoc @fluidframework/shared-object-base#ISharedObjectFactory."type"}
- * @alpha
+ * @beta
  * @legacy
  */
 export const SharedTreeFactoryType = "https://graph.microsoft.com/types/tree";
 
 /**
  * {@inheritDoc @fluidframework/shared-object-base#ISharedObjectFactory.attributes}
- * @alpha
+ * @beta
  * @legacy
  */
 export const SharedTreeAttributes: IChannelAttributes = {

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

@@ -13,6 +13,7 @@ import {
 	replaceHandles,
 	type TreeEncodingOptions,
 	type HandleConverter,
+	KeyEncodingOptions,
 } from "./customTree.js";
 
 /**
@@ -46,7 +47,7 @@ export function conciseFromCursor(
 	options: TreeEncodingOptions,
 ): ConciseTree {
 	const config: Required<TreeEncodingOptions> = {
-		useStoredKeys: false,
+		keys: KeyEncodingOptions.usePropertyKeys,
 		...options,
 	};
 

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

@@ -4,7 +4,7 @@
  */
 
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
-import { assert, fail } from "@fluidframework/core-utils/internal";
+import { assert, fail, unreachableCase } from "@fluidframework/core-utils/internal";
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
@@ -36,24 +36,56 @@ import { isObjectNodeSchema } from "../node-kinds/index.js";
 /**
  * Options for how to interpret or encode a tree when schema information is available.
  * @alpha
+ * @input
  */
-export interface TreeEncodingOptions {
+export interface TreeEncodingOptions<TKeyOptions = KeyEncodingOptions> {
 	/**
-	 * If true, use the stored keys of object nodes.
-	 * If false, use the property keys.
+	 * How to handle field keys.
 	 * @remarks
 	 * Has no effect on {@link NodeKind}s other than {@link NodeKind.Object}.
 	 *
 	 * {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields|Unknown optional field} will be omitted when using property keys.
-	 * @defaultValue false.
-	 * @privateRemarks
-	 * TODO AB#43548:
-	 * Replace this with an enum that provides three options:
-	 * - `usePropertyKeys`: use property keys. Supported for import and export.
-	 * - `allStoredKeys`: use stored keys, and include unknown optional fields. Supported for export only, at least for the short term.
-	 * - `knownStoredKeys`: use stored keys but do not include unknown optional fields. Supported for import and export.
+	 * @defaultValue {@link KeyEncodingOptions.usePropertyKeys}.
 	 */
-	readonly useStoredKeys?: boolean;
+	readonly keys?: TKeyOptions;
+}
+
+/**
+ * Options for how to interpret a tree when schema information is available.
+ * @alpha
+ * @input
+ */
+export type TreeParsingOptions = TreeEncodingOptions<
+	KeyEncodingOptions.usePropertyKeys | KeyEncodingOptions.knownStoredKeys
+>;
+
+/**
+ * Options for how to encode keys in a tree.
+ * @alpha
+ * @input
+ */
+export enum KeyEncodingOptions {
+	/**
+	 * Use property keys.
+	 * @remarks
+	 * Supported for import and export.
+	 * {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields|Unknown optional fields} will be omitted when using property keys.
+	 */
+	usePropertyKeys = "usePropertyKeys",
+	/**
+	 * Use stored keys, and include {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields|Unknown optional fields}.
+	 * @remarks
+	 * Currently only supported for export.
+	 */
+	allStoredKeys = "allStoredKeys",
+	/**
+	 * Use stored keys but do not include {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields|Unknown optional fields}.
+	 * @remarks
+	 * Supported for import and export.
+	 * For export, this omits unknown optional fields.
+	 * For import, any unexpected fields are errors, regardless of {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields}.
+	 */
+	knownStoredKeys = "knownStoredKeys",
 }
 
 /**
@@ -140,27 +172,12 @@ export function customFromCursor<TChild>(
 				forEachField(reader, () => {
 					assert(reader.getFieldLength() === 1, 0xa19 /* invalid children number */);
 					const storedKey = reader.getFieldKey();
-					let key: string;
-					if (!options.useStoredKeys) {
-						const viewSchema =
-							schema.get(type) ?? fail(0xbff /* missing schema for type in cursor */);
-						if (isObjectNodeSchema(viewSchema)) {
-							const propertyKey = viewSchema.storedKeyToPropertyKey.get(storedKey);
-							if (propertyKey === undefined) {
-								assert(
-									viewSchema.allowUnknownOptionalFields,
-									0xc00 /* found unknown field where not allowed */,
-								);
-								// Skip unknown optional fields when using property keys.
-								return;
-							}
-							key = propertyKey;
-						} else {
-							key = storedKey;
-						}
-					} else {
-						key = storedKey;
+					const key = getKeyFromOptions(options.keys, type, storedKey, schema);
+					if (key === undefined) {
+						// Skip unknown optional fields when using property keys or only known stored keys.
+						return;
 					}
+
 					reader.enterNode(0);
 					fields[key] = childHandler(reader, options, storedSchema, schema);
 					reader.exitNode();
@@ -171,6 +188,59 @@ export function customFromCursor<TChild>(
 	}
 }
 
+/**
+ * Returns the key if one should be used, and undefined if the field should be omitted/skipped.
+ *
+ * @param schema - Collection of known view schema.
+ * If `options` is not `KeyEncodingOptions.allStoredKeys`, this must provide the schema for the `type`.
+ * Note that if using this to perform a recursive walk, and `schema` has all view schema reachable from the starting type,
+ * then it should be safe to use the same schema map on every invocation since types missing from it will only be
+ * encountered after traversing unknown optional fields which for which this will return undefined.
+ *
+ * @remarks
+ * Asserts that if encountering an unknown optional field, the schema allows them.
+ * This is not robustly validated in all cases: when in allStoredKeys, it is not checked
+ * (since the view schema might not even be available).
+ */
+function getKeyFromOptions(
+	options: KeyEncodingOptions,
+	type: TreeNodeSchemaIdentifier,
+	storedKey: FieldKey,
+	schema: ReadonlyMap<string, TreeNodeSchema>,
+): string | undefined {
+	switch (options) {
+		case KeyEncodingOptions.allStoredKeys:
+			// Since this case might be inside of an unknown optional field,
+			// it must not depend on there being a view schema.
+			// Fortunately, its possible to implement this case without one.
+			return storedKey;
+		case KeyEncodingOptions.usePropertyKeys:
+		case KeyEncodingOptions.knownStoredKeys: {
+			// Both these cases avoid traversing into unknown optional fields,
+			// so a view schema should be available.
+			const viewSchema =
+				schema.get(type) ?? fail(0xbff /* missing schema for type in cursor */);
+			if (isObjectNodeSchema(viewSchema)) {
+				const propertyKey = viewSchema.storedKeyToPropertyKey.get(storedKey);
+				if (propertyKey === undefined) {
+					assert(
+						viewSchema.allowUnknownOptionalFields,
+						0xc00 /* found unknown field where not allowed */,
+					);
+					// Skip unknown optional fields when using property keys or only known stored keys.
+					return undefined;
+				} else {
+					return options === KeyEncodingOptions.usePropertyKeys ? propertyKey : storedKey;
+				}
+			} else {
+				return storedKey;
+			}
+		}
+		default:
+			unreachableCase(options);
+	}
+}
+
 /**
  * Builds an {@link CustomTree} from a cursor in Nodes mode.
  * @remarks

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

@@ -6,14 +6,18 @@
 import type { JsonTreeSchema } from "./jsonSchema.js";
 import type { ImplicitAllowedTypes } from "../core/index.js";
 import { toJsonSchema } from "./simpleSchemaToJsonSchema.js";
-import type { TreeEncodingOptions } from "./customTree.js";
+import type { TreeParsingOptions } from "./customTree.js";
 import { TreeViewConfigurationAlpha } from "./configuration.js";
 
 /**
  * Options for how to interpret or encode a tree when schema information is available.
+ * @remarks
+ * This currently extends {@link TreeParsingOptions},
+ * removing the option to declare {@link KeyEncodingOptions.allStoredKeys} since this option is currently not supported.
+ * @input
  * @alpha
  */
-export interface TreeSchemaEncodingOptions extends TreeEncodingOptions {
+export interface TreeSchemaEncodingOptions extends TreeParsingOptions {
 	/**
 	 * If true, fields with default providers (like {@link SchemaFactory.identifier}) will be required.
 	 * If false, they will be optional.
@@ -75,6 +79,7 @@ export interface TreeSchemaEncodingOptions extends TreeEncodingOptions {
  * 1. VerboseTree and (Done) ConciseTree
  * 2. (Done) With and without requiring values with defaults (for insertion vs reading)
  * 3. (Done) Using stored keys and property keys.
+ * 4. Control over unknown optional fields and staged allowed types (able to manually control them and/or get them from some context).
  *
  * This takes in `ImplicitAllowedTypes` since underlying `toJsonSchema` can't handle optional roots.
  *

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

@@ -32,6 +32,7 @@ export {
 	type NodeSchemaOptions,
 	type NodeSchemaOptionsAlpha,
 } from "./schemaFactory.js";
+export { SchemaFactoryBeta } from "./schemaFactoryBeta.js";
 export { SchemaFactoryAlpha, type SchemaStaticsAlpha } from "./schemaFactoryAlpha.js";
 export type {
 	ValidateRecursiveSchema,
@@ -101,6 +102,8 @@ export {
 	tryStoredSchemaAsArray,
 	replaceHandles,
 	type HandleConverter,
+	KeyEncodingOptions,
+	type TreeParsingOptions,
 } from "./customTree.js";
 
 export {

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

@@ -86,7 +86,7 @@ export function singletonSchema<TScope extends string, TName extends string | nu
  * @remarks
  * The string value of the enum is used as the name of the schema: callers must ensure that it is stable and unique.
  * Numeric enums values have the value implicitly converted into a string.
- * Consider making a dedicated schema factory with a nested scope (for example using {@link SchemaFactoryAlpha.scopedFactory}) to avoid the enum members colliding with other schema.
+ * Consider making a dedicated schema factory with a nested scope (for example using {@link SchemaFactoryBeta.scopedFactory}) to avoid the enum members colliding with other schema.
  * @example
  * ```typescript
  * const schemaFactory = new SchemaFactory("com.myApp");

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

@@ -98,6 +98,7 @@ export function schemaFromValue(value: TreeValue): TreeNodeSchema {
 /**
  * Options when declaring an {@link SchemaFactory.object|object node}'s schema
  *
+ * @input
  * @alpha
  */
 export interface SchemaFactoryObjectOptions<TCustomMetadata = unknown>
@@ -147,7 +148,7 @@ export interface SchemaFactoryObjectOptions<TCustomMetadata = unknown>
 	 * It's only when application code reaches into a node
 	 * (either by accessing its fields, spreading it, or some other means) that this problem arises.
 	 */
-	allowUnknownOptionalFields?: boolean;
+	readonly allowUnknownOptionalFields?: boolean;
 }
 
 /**
@@ -340,12 +341,6 @@ export class SchemaFactory<
 		public readonly scope: TScope,
 	) {}
 
-	private scoped<Name extends TName | string>(name: Name): ScopedSchemaName<TScope, Name> {
-		return (
-			this.scope === undefined ? `${name}` : `${this.scope}.${name}`
-		) as ScopedSchemaName<TScope, Name>;
-	}
-
 	/**
 	 * {@inheritDoc SchemaStatics.string}
 	 */
@@ -435,7 +430,7 @@ export class SchemaFactory<
 			true,
 			T
 		> = objectSchema(
-			this.scoped(name),
+			scoped(this, name),
 			fields,
 			true,
 			defaultSchemaFactoryObjectOptions.allowUnknownOptionalFields,
@@ -593,7 +588,7 @@ export class SchemaFactory<
 			T,
 			undefined
 		> = mapSchema(
-			this.scoped(name),
+			scoped(this, name),
 			allowedTypes,
 			implicitlyConstructable,
 			// The current policy is customizable nodes don't get fake prototypes.
@@ -669,7 +664,7 @@ export class SchemaFactory<
 	>;
 
 	/**
-	 * Define (and add to this library) a {@link TreeNodeSchemaClass} for a {@link (TreeArrayNode:interface)}.
+	 * Define a {@link TreeNodeSchemaClass} for a {@link (TreeArrayNode:interface)}.
 	 *
 	 * @param name - Unique identifier for this schema within this factory's scope.
 	 * @param allowedTypes - The types that may appear in the array.
@@ -795,7 +790,7 @@ export class SchemaFactory<
 		undefined
 	> {
 		const array = arraySchema(
-			this.scoped(name),
+			scoped(this, name),
 			allowedTypes,
 			implicitlyConstructable,
 			customizable,
@@ -1063,6 +1058,16 @@ export function structuralName<const T extends string>(
 	return `${collectionName}<${inner}>`;
 }
 
+export function scoped<
+	TScope extends string | undefined,
+	TName extends number | string,
+	Name extends TName | string,
+>(factory: SchemaFactory<TScope, TName>, name: Name): ScopedSchemaName<TScope, Name> {
+	return (
+		factory.scope === undefined ? `${name}` : `${factory.scope}.${name}`
+	) as ScopedSchemaName<TScope, Name>;
+}
+
 /**
  * Used to allocate default identifiers for unhydrated nodes when no context is available.
  * @remarks
@@ -1077,7 +1082,7 @@ const globalIdentifierAllocator: IIdCompressor = createIdCompressor();
  * @typeParam TCustomMetadata - Custom metadata properties to associate with the Node Schema.
  * See {@link NodeSchemaMetadata.custom}.
  *
- * @sealed
+ * @input
  * @public
  */
 export interface NodeSchemaOptions<out TCustomMetadata = unknown> {
@@ -1085,8 +1090,7 @@ export interface NodeSchemaOptions<out TCustomMetadata = unknown> {
 	 * Optional metadata to associate with the Node Schema.
 	 *
 	 * @remarks
-	 * Note: this metadata is not persisted nor made part of the collaborative state; it is strictly client-local.
-	 * Different clients in the same collaborative session may see different metadata for the same field.
+	 * This specifies {@link SimpleNodeSchemaBase.metadata} which has more details about its use.
 	 */
 	readonly metadata?: NodeSchemaMetadata<TCustomMetadata> | undefined;
 }
@@ -1097,12 +1101,15 @@ export interface NodeSchemaOptions<out TCustomMetadata = unknown> {
  * @typeParam TCustomMetadata - Custom metadata properties to associate with the Node Schema.
  * See {@link NodeSchemaMetadata.custom}.
  *
+ * @input
  * @alpha
  */
 export interface NodeSchemaOptionsAlpha<out TCustomMetadata = unknown>
 	extends NodeSchemaOptions<TCustomMetadata> {
 	/**
 	 * The persisted metadata for this schema element.
+	 * @remarks
+	 * This gets exposed via {@link SimpleNodeSchemaBaseAlpha.persistedMetadata}.
 	 */
 	readonly persistedMetadata?: JsonCompatibleReadOnlyObject | undefined;
 }