@fluidframework/tree 2.116.1 → 2.118.0

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

@@ -10,6 +10,7 @@ import type { TSchema } from "@sinclair/typebox";
 import { type EncodedRevisionTag, RevisionTagSchema, SessionIdSchema } from "../core/index.js";
 import type { JsonCompatibleReadOnly } from "../util/index.js";
 
+import { EncodedCustomMetadataTree } from "./customMetadataFormat.js";
 import { MessageFormatVersion } from "./messageFormat.js";
 
 /**
@@ -29,6 +30,12 @@ export interface Message {
 	 */
 	readonly changeset: JsonCompatibleReadOnly;
 
+	/**
+	 * Arbitrary, application-defined metadata to persist alongside the commit in this message.
+	 * @remarks Only written at {@link MessageFormatVersion.v7} and later.
+	 */
+	readonly customMetadata?: EncodedCustomMetadataTree;
+
 	/**
 	 * The version of the message. This controls how the message is encoded.
 	 *
@@ -40,16 +47,25 @@ export interface Message {
 		| typeof MessageFormatVersion.v2
 		| typeof MessageFormatVersion.v3
 		| typeof MessageFormatVersion.v4
-		| typeof MessageFormatVersion.v6;
+		| typeof MessageFormatVersion.v6
+		| typeof MessageFormatVersion.v7;
 }
 
+/* eslint-disable @typescript-eslint/explicit-function-return-type */
 // Return type is intentionally derived.
-// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
-export const Message = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
+// Unlike the summary formats, this schema does not set `additionalProperties: false`: the op envelope
+// has always tolerated unknown properties, and tightening it could reject ops from other versions.
+export const Message = <ChangeSchema extends TSchema>(
+	tChange: ChangeSchema,
+	includeCustomMetadata: boolean,
+) =>
 	Type.Object({
 		revision: RevisionTagSchema,
 		originatorId: SessionIdSchema,
 		changeset: tChange,
+		...(includeCustomMetadata
+			? { customMetadata: Type.Optional(EncodedCustomMetadataTree) }
+			: {}),
 		version: Type.Optional(
 			Type.Union([
 				Type.Literal(MessageFormatVersion.v1),
@@ -57,6 +73,8 @@ export const Message = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
 				Type.Literal(MessageFormatVersion.v3),
 				Type.Literal(MessageFormatVersion.v4),
 				Type.Literal(MessageFormatVersion.v6),
+				Type.Literal(MessageFormatVersion.v7),
 			]),
 		),
 	});
+/* eslint-enable @typescript-eslint/explicit-function-return-type */

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

@@ -11,6 +11,7 @@ import { type EncodedRevisionTag, RevisionTagSchema, SessionIdSchema } from "../
 import type { JsonCompatibleReadOnly } from "../util/index.js";
 
 import type { EncodedBranchId } from "./branch.js";
+import { EncodedCustomMetadataTree } from "./customMetadataFormat.js";
 import { MessageFormatVersion } from "./messageFormat.js";
 
 /**
@@ -41,6 +42,12 @@ export interface Message {
 	 */
 	readonly branchName?: string;
 
+	/**
+	 * Arbitrary, application-defined metadata to persist alongside the commit in this message.
+	 * @remarks See {@link GraphCommit.customMetadata}.
+	 */
+	readonly customMetadata?: EncodedCustomMetadataTree;
+
 	/**
 	 * The version of the message format.
 	 */
@@ -56,5 +63,6 @@ export const Message = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
 		changeset: Type.Optional(tChange),
 		branchId: Type.Optional(Type.Number()),
 		branchName: Type.Optional(Type.String()),
+		customMetadata: Type.Optional(EncodedCustomMetadataTree),
 		version: Type.Literal(MessageFormatVersion.vSharedBranches),
 	});

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

@@ -30,6 +30,7 @@ import type { CodecWriteOptions, DependentFormatVersion, IJsonCodec } from "../c
 import {
 	type ChangeFamily,
 	type ChangeFamilyEditor,
+	CommitKind,
 	type GraphCommit,
 	replaceChange,
 	type RevisionTag,
@@ -669,10 +670,12 @@ export class SharedTreeCore<
 		switch (type) {
 			case "commit": {
 				const {
-					commit: { revision, change },
+					commit: { revision, change, customMetadata },
 					branchId,
 				} = message;
-				this.editManager.getLocalBranch(branchId).apply({ change, revision });
+				this.editManager
+					.getLocalBranch(branchId)
+					.apply({ change, revision }, CommitKind.Default, customMetadata);
 				break;
 			}
 			case "branch": {

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

@@ -15,15 +15,25 @@ import {
 	mintCommit,
 	rebaseBranch,
 	tagChange,
+	CommitKind,
 	type ChangeFamilyEditor,
+	type CustomMetadataTree,
 	type GraphCommit,
 	type ProcessChangeFn,
 	type RevisionTag,
 } from "../core/index.js";
-import { getLast, getOrCreate } from "../util/index.js";
+import { getLast, getOrCreate, type JsonCompatibleReadOnlyObject } from "../util/index.js";
 
 import type { SharedTreeBranch, SharedTreeBranchEvents } from "./branch.js";
 
+/**
+ * A {@link CustomMetadataTree} under construction.
+ */
+interface MutableCustomMetadataTree {
+	metadata: JsonCompatibleReadOnlyObject | undefined;
+	children: MutableCustomMetadataTree[];
+}
+
 /**
  * Describes the result of a transaction.
  * Transactions may either succeed and commit, or fail and abort.
@@ -290,6 +300,15 @@ export interface SquashingTransactionOptions<TChange, TChangeProcessingContext>
 	 * {@link ChangeProcessor.applicability | applicability}.
 	 */
 	readonly postProcessor?: ChangeProcessor<TChange, TChangeProcessingContext>;
+
+	/**
+	 * Arbitrary, application-defined metadata to attach to the commit that this transaction produces.
+	 *
+	 * @remarks
+	 * Each transaction in the stack contributes a node to the resulting {@link CustomMetadataTree}. If
+	 * the transaction produces no commit, the metadata is discarded.
+	 */
+	readonly customMetadata?: JsonCompatibleReadOnlyObject;
 }
 
 /**
@@ -409,6 +428,15 @@ export class SquashingTransactionStack<
 				startOptions?: SquashingTransactionOptions<TChange, TChangeProcessingContext>,
 			): Callbacks<SquashingTransactionOptions<TChange, TChangeProcessingContext>> => {
 				postProcessorStack.push(resolvePostProcessor(startOptions?.postProcessor));
+				// Each transaction in the stack contributes a node to a tree mirroring the nesting, which is
+				// attached to the single commit they produce. `openMetadataNode` is the innermost open node.
+				const rootMetadataNode: MutableCustomMetadataTree = {
+					metadata: startOptions?.customMetadata,
+					children: [],
+				};
+				let openMetadataNode = rootMetadataNode;
+				const hasCustomMetadata = (node: CustomMetadataTree): boolean =>
+					node.metadata !== undefined || node.children.some(hasCustomMetadata);
 				// Keep track of the commit that each transaction was on when it started
 				const startHead = this.activeBranch.getHead();
 				const changeFamily = this.branch.changeFamily;
@@ -490,19 +518,31 @@ export class SquashingTransactionStack<
 									// change in their place so that the view fully reflects the modified
 									// `change`.
 									transactionBranch.removeAfter(startHead);
-									transactionBranch.apply(tagChange(change, transactionRevision));
+									transactionBranch.apply(
+										tagChange(change, transactionRevision),
+										CommitKind.Default,
+										undefined,
+									);
 								}
 
+								const customMetadata = hasCustomMetadata(rootMetadataNode)
+									? rootMetadataNode
+									: undefined;
 								if (targetPath.length === 0) {
 									// No changes were made on the original branch since the transaction began
 									// The transaction commit can be applied directly
-									this.branch.apply(tagChange(change, transactionRevision));
+									this.branch.apply(
+										tagChange(change, transactionRevision),
+										CommitKind.Default,
+										customMetadata,
+									);
 									// The view is already up-to-date so there's nothing more to do
 								} else {
 									// Some changes were made on `branch` since the transaction began
 									const unrebasedHead = mintCommit(startHead, {
 										change,
 										revision: transactionRevision,
+										customMetadata,
 									});
 									// We need to rebase the transaction commit on top of the new changes
 									const rebased = rebaseBranch(
@@ -515,7 +555,7 @@ export class SquashingTransactionStack<
 										rebased.newSourceHead.revision === transactionRevision,
 										0xcd0 /* The transaction commit should be rebased to the tip */,
 									);
-									this.branch.apply(rebased.newSourceHead);
+									this.branch.apply(rebased.newSourceHead, CommitKind.Default, customMetadata);
 									viewUpdate = rebased.sourceChange;
 								}
 							} else {
@@ -546,6 +586,13 @@ export class SquashingTransactionStack<
 					SquashingTransactionOptions<TChange, TChangeProcessingContext>
 				> = (nestedStartOptions) => {
 					postProcessorStack.push(resolvePostProcessor(nestedStartOptions?.postProcessor));
+					const nestedMetadataNode: MutableCustomMetadataTree = {
+						metadata: nestedStartOptions?.customMetadata,
+						children: [],
+					};
+					const metadataParent = openMetadataNode;
+					metadataParent.children.push(nestedMetadataNode);
+					openMetadataNode = nestedMetadataNode;
 					const nestedStartHead = this.activeBranch.getHead();
 					const nestedOuterOnPop = onPush?.();
 					transactionBranch.editor.enterTransaction();
@@ -553,9 +600,12 @@ export class SquashingTransactionStack<
 						// Invoked when a nested transaction ends
 						onPop: (result) => {
 							const nestedPostProcessor = postProcessorStack.pop();
+							openMetadataNode = metadataParent;
 							transactionBranch.editor.exitTransaction();
 							switch (result) {
 								case TransactionResult.Abort: {
+									// The aborted transaction contributed nothing; its node is necessarily the last child.
+									metadataParent.children.pop();
 									// When a transaction is aborted, roll back all the transaction's changes on the current branch
 									transactionBranch.removeAfter(nestedStartHead);
 									break;
@@ -585,6 +635,8 @@ export class SquashingTransactionStack<
 												transactionBranch.removeAfter(nestedStartHead);
 												transactionBranch.apply(
 													tagChange(processedSquash, transactionRevision),
+													CommitKind.Default,
+													undefined,
 												);
 											}
 										}

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

@@ -158,22 +158,22 @@ export interface ITreeViewConfiguration<
 
 /**
  * Property-bag configuration for {@link TreeViewConfigurationAlpha} construction.
+ * @input
  * @alpha
  */
 export interface ITreeViewConfigurationAlpha<
 	TSchema extends ImplicitFieldSchema = ImplicitFieldSchema,
 > extends ITreeViewConfiguration<TSchema> {
 	/**
-	 * Policy for generating stored schema from the view schema.
+	 * Policy for generating stored schema from the view schema during staged schema upgrades.
 	 *
 	 * @remarks
-	 * If omitted or `undefined`, defaults to {@link StagedSchemaUpgradePolicyFactory.restrictive}
-	 * which does not enable any staged schema upgrades.
-	 *
 	 * If provided, this policy is used when generating stored schema to include in documents via
 	 * `initialize` / `upgradeSchema` as well as in {@link snapshotSchemaCompatibility} to validate
 	 * the compatibility of such documents.
 	 *
+	 * @defaultValue {@link StagedSchemaUpgradePolicyFactory.restrictive}
+	 *
 	 * @example Enabling specific staged upgrades
 	 * ```typescript
 	 * const config = new TreeViewConfigurationAlpha({

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

@@ -27,6 +27,7 @@ import {
 	NodeKind,
 	normalizeAndEvaluateAnnotatedAllowedTypes,
 	type AnnotatedAllowedType,
+	type SchemaUpgrade,
 	type TreeNodeSchema,
 } from "../core/index.js";
 import {
@@ -48,6 +49,25 @@ import type { TreeSchema } from "../treeSchema.js";
 
 import { tryStoredSchemaAsArray } from "./customTree.js";
 
+/**
+ * Collects upgrade location data during a schema walk.
+ * @remarks Called for each staged type or staged optional field encountered.
+ */
+export interface UpgradeLocationCollector {
+	/**
+	 * Record a staged allowed type location.
+	 * @param upgrade - The upgrade token guarding this type.
+	 * @param isEnabled - Whether this type is present in stored schema.
+	 */
+	allowedType(upgrade: SchemaUpgrade, isEnabled: boolean): void;
+	/**
+	 * Record a staged optional field location.
+	 * @param upgrade - The upgrade token guarding this field.
+	 * @param isEnabled - Whether the stored field is already optional.
+	 */
+	optionalField(upgrade: SchemaUpgrade, isEnabled: boolean): void;
+}
+
 /**
  * Discriminated union (keyed on `mismatch`) of discrepancies between a view and stored schema which
  * make it possible for content matching the stored schema to be incompatible with the view schema.
@@ -79,6 +99,11 @@ export interface FieldDiscrepancyLocation {
 	 * - the discrepancy is for 'all fields' of a map node
 	 */
 	readonly fieldKey: FieldKey | undefined;
+	/**
+	 * Whether the view field is a staged optional field.
+	 * Omitted when false.
+	 */
+	readonly viewIsStagedOptional?: true;
 }
 
 /**
@@ -94,6 +119,13 @@ export interface AllowedTypeDiscrepancy extends FieldDiscrepancyLocation {
 	 * (excluding {@link SchemaStaticsBeta.staged | staged} schema) which are not allowed in stored schema.
 	 */
 	readonly view: readonly AnnotatedAllowedType<TreeNodeSchema>[];
+	/**
+	 * Staged allowed types in the view schema which are not allowed in stored schema.
+	 *
+	 * @remarks
+	 * These types do not cause the discrepancy and are omitted when there are none.
+	 */
+	readonly stagedView?: readonly AnnotatedAllowedType<TreeNodeSchema>[];
 	/**
 	 * Allowed type identifiers in stored schema which are not allowed in view schema
 	 * (including the view schema's {@link SchemaStaticsBeta.staged | staged} schema).
@@ -174,15 +206,25 @@ function doesNodeKindMatchStoredNodeKind(
 
 /**
  * Finds and reports discrepancies between a view schema and a stored schema which make "canView" false.
+ *
+ * Optionally collects upgrade location information for staged schema upgrades during the same walk.
+ *
  * @remarks
  * See documentation on {@link Discrepancy} and its subtypes for details of possible discrepancies.
  */
 export function* getDiscrepanciesInAllowedContent(
 	view: TreeSchema,
 	stored: TreeStoredSchema,
+	upgradeCollector?: UpgradeLocationCollector,
 ): Iterable<Discrepancy> {
 	// check root field discrepancies
-	yield* getFieldDiscrepancies(view.root, stored.rootFieldSchema, undefined, undefined);
+	yield* getFieldDiscrepancies(
+		view.root,
+		stored.rootFieldSchema,
+		undefined,
+		undefined,
+		upgradeCollector,
+	);
 
 	// Check all of the stored nodes, including their fields for discrepancies.
 	for (const [identifier, storedSchema] of stored.nodeSchema) {
@@ -190,7 +232,7 @@ export function* getDiscrepanciesInAllowedContent(
 
 		// if the view schema has a node that's also in the stored schema, check it.
 		if (viewSchema !== undefined) {
-			yield* getNodeDiscrepancies(identifier, viewSchema, storedSchema);
+			yield* getNodeDiscrepancies(identifier, viewSchema, storedSchema, upgradeCollector);
 		}
 		// Note that nodes that are missing in the view schema are only a problem if other stored schema nodes actually reference them which will produce its own discrepancy, so we can rely on that to produce any needed discrepancies.
 	}
@@ -200,6 +242,7 @@ function* getNodeDiscrepancies(
 	identifier: TreeNodeSchemaIdentifier,
 	view: TreeNodeSchema,
 	stored: TreeNodeStoredSchema,
+	upgradeCollector?: UpgradeLocationCollector,
 ): Iterable<Discrepancy> {
 	if (!doesNodeKindMatchStoredNodeKind(view.kind, getStoredNodeSchemaType(stored))) {
 		yield {
@@ -221,6 +264,7 @@ function* getNodeDiscrepancies(
 				identifier,
 				view,
 				stored as ObjectNodeStoredSchema,
+				upgradeCollector,
 			);
 			break;
 		}
@@ -246,6 +290,8 @@ function* getNodeDiscrepancies(
 				arrayStoredSchema,
 				brand(view.identifier),
 				EmptyKey,
+				false,
+				upgradeCollector,
 			);
 
 			break;
@@ -261,6 +307,7 @@ function* getNodeDiscrepancies(
 				(stored as MapNodeStoredSchema).mapFields,
 				identifier,
 				undefined,
+				upgradeCollector,
 			);
 			break;
 		}
@@ -275,6 +322,7 @@ function* getNodeDiscrepancies(
 				(stored as MapNodeStoredSchema).mapFields,
 				identifier,
 				undefined,
+				upgradeCollector,
 			);
 			break;
 		}
@@ -308,7 +356,7 @@ function* getNodeDiscrepancies(
 export function findExtraAllowedTypes(
 	viewAllowedTypes: readonly AnnotatedAllowedType<TreeNodeSchema>[],
 	storedAllowedTypes: TreeTypeSet,
-): Pick<AllowedTypeDiscrepancy, "view" | "stored"> {
+): Pick<AllowedTypeDiscrepancy, "view" | "stagedView" | "stored"> {
 	const viewNodeSchemaIdentifiers = new Set(
 		viewAllowedTypes.map((value) => value.type.identifier),
 	);
@@ -322,10 +370,19 @@ export function findExtraAllowedTypes(
 			!storedAllowedTypes.has(brand(value.type.identifier)) &&
 			value.metadata.stagedSchemaUpgrade === undefined,
 	);
+	const stagedView = viewAllowedTypes.filter(
+		(value) =>
+			!storedAllowedTypes.has(brand(value.type.identifier)) &&
+			value.metadata.stagedSchemaUpgrade !== undefined,
+	);
 	const stored = [...storedAllowedTypes].filter(
 		(value) => !viewNodeSchemaIdentifiers.has(value),
 	);
-	return { view, stored };
+	return {
+		view,
+		...(stagedView.length === 0 ? {} : { stagedView }),
+		stored,
+	};
 }
 
 /**
@@ -346,16 +403,28 @@ function* getFieldDiscrepancies(
 	stored: TreeFieldStoredSchema,
 	identifier: TreeNodeSchemaIdentifier | undefined,
 	fieldKey: FieldKey | undefined,
+	upgradeCollector?: UpgradeLocationCollector,
 ): Iterable<FieldDiscrepancy> {
 	assert(
 		view instanceof FieldSchemaAlpha,
 		0xbee /* all field schema should be FieldSchemaAlpha */,
 	);
+
+	// Collect staged-optional upgrade location if present.
+	if (upgradeCollector !== undefined && view.isStagedOptional !== false) {
+		upgradeCollector.optionalField(
+			view.isStagedOptional,
+			stored.kind === FieldKinds.optional.identifier,
+		);
+	}
+
 	yield* getAllowedTypeDiscrepancies(
 		view.allowedTypesFull.evaluate().types,
 		stored.types,
 		identifier,
 		fieldKey,
+		view.isStagedOptional !== false,
+		upgradeCollector,
 	);
 
 	const viewKind =
@@ -375,6 +444,7 @@ function* getFieldDiscrepancies(
 			mismatch: "fieldKind",
 			view: viewKind.identifier,
 			stored: stored.kind,
+			...(view.isStagedOptional === false ? {} : { viewIsStagedOptional: true }),
 		} satisfies FieldKindDiscrepancy;
 	}
 }
@@ -396,7 +466,21 @@ function* getAllowedTypeDiscrepancies(
 	stored: TreeTypeSet,
 	identifier: TreeNodeSchemaIdentifier | undefined,
 	fieldKey: FieldKey | undefined,
+	viewIsStagedOptional: boolean,
+	upgradeCollector?: UpgradeLocationCollector,
 ): Iterable<FieldDiscrepancy> {
+	// Collect staged allowed type upgrade locations if present.
+	if (upgradeCollector !== undefined) {
+		for (const allowedType of view) {
+			if (allowedType.metadata.stagedSchemaUpgrade !== undefined) {
+				upgradeCollector.allowedType(
+					allowedType.metadata.stagedSchemaUpgrade,
+					stored.has(brand(allowedType.type.identifier)),
+				);
+			}
+		}
+	}
+
 	const discrepancies = findExtraAllowedTypes(view, stored);
 	if (discrepancies.view.length > 0 || discrepancies.stored.length > 0) {
 		yield {
@@ -404,6 +488,7 @@ function* getAllowedTypeDiscrepancies(
 			identifier,
 			fieldKey,
 			mismatch: "allowedTypes",
+			...(viewIsStagedOptional ? { viewIsStagedOptional: true } : {}),
 		} satisfies AllowedTypeDiscrepancy;
 	}
 }
@@ -424,6 +509,7 @@ function* computeObjectNodeDiscrepancies(
 	identifier: TreeNodeSchemaIdentifier,
 	view: ObjectNodeSchemaPrivate,
 	stored: ObjectNodeStoredSchema,
+	upgradeCollector?: UpgradeLocationCollector,
 ): Iterable<FieldDiscrepancy> {
 	/**
 	 * Similar to the logic used for tracking discrepancies between two node schemas, we will identify
@@ -453,9 +539,18 @@ function* computeObjectNodeDiscrepancies(
 				mismatch: "fieldKind",
 				view: viewKind.identifier,
 				stored: storedEmptyFieldSchema.kind,
+				...(fieldSchema instanceof FieldSchemaAlpha && fieldSchema.isStagedOptional !== false
+					? { viewIsStagedOptional: true }
+					: {}),
 			} satisfies FieldKindDiscrepancy;
 		} else {
-			yield* getFieldDiscrepancies(fieldSchema, storedSchema, identifier, fieldKey);
+			yield* getFieldDiscrepancies(
+				fieldSchema,
+				storedSchema,
+				identifier,
+				fieldKey,
+				upgradeCollector,
+			);
 		}
 	}
 

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

@@ -13,16 +13,23 @@ export {
 	TreeViewConfigurationAlpha,
 } from "./configuration.js";
 export type {
+	CommitRevision,
 	ITree,
 	TreeView,
 	ViewableTree,
 	TreeViewEvents,
 	SchemaCompatibilityStatus,
+	SchemaCompatibilityStatusBeta,
+	SchemaDiscrepancy,
 	TreeViewAlpha,
 	TreeViewBeta,
+	UntypedTreeView,
 	TreeBranch,
 	TreeBranchAlpha,
+	UntypedTreeViewAlpha,
 	TreeBranchEvents,
+	TreeBranchCommitMetadata,
+	TreeBranchHistory,
 	TreeContextAlpha,
 	ITreeAlpha,
 } from "./tree.js";
@@ -100,7 +107,11 @@ export {
 export type { TreeSchemaEncodingOptions } from "./getJsonSchema.js";
 export { getJsonSchema } from "./getJsonSchema.js";
 export { getSimpleSchema } from "./getSimpleSchema.js";
-export { checkSchemaCompatibility } from "./schemaCompatibilityTester.js";
+export {
+	checkSchemaCompatibility,
+	getSchemaIncompatibilityDetails,
+} from "./schemaCompatibilityTester.js";
+export { type StagedUpgradeStatus } from "./schemaCompatibilityTester.js";
 export type {
 	Unenforced,
 	FieldSchemaAlphaUnsafe,