@fluidframework/tree 2.117.0 → 2.118.0

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

@@ -3,14 +3,119 @@
  * Licensed under the MIT License.
  */
 
-import type { TreeStoredSchema } from "../../core/index.js";
+import { unreachableCase } from "@fluidframework/core-utils/internal";
+
+import {
+	MapNodeStoredSchema,
+	ObjectNodeStoredSchema,
+	type TreeStoredSchema,
+	ValueSchema,
+} from "../../core/index.js";
 import type { SchemaUpgrade, StagedSchemaUpgradePolicy } from "../core/index.js";
+import { NodeKind } from "../core/index.js";
 import { allowsRepoSuperset, defaultSchemaPolicy } from "../../feature-libraries/index.js";
-import { toUpgradeSchema } from "../toStoredSchema.js";
+import { resolveStoredSchemaGenerationOptions, toUpgradeSchema } from "../toStoredSchema.js";
 import type { TreeSchema } from "../treeSchema.js";
 
-import { getDiscrepanciesInAllowedContent } from "./discrepancies.js";
-import type { SchemaCompatibilityStatus } from "./tree.js";
+import {
+	getDiscrepanciesInAllowedContent,
+	type Discrepancy,
+	type UpgradeLocationCollector,
+} from "./discrepancies.js";
+import type { SchemaCompatibilityStatusBeta, SchemaDiscrepancy } from "./tree.js";
+
+/**
+ * Describes the discrepancies that prevent a view schema from viewing a stored schema as a
+ * readonly array.
+ */
+export function getSchemaIncompatibilityDetails(
+	viewSchema: TreeSchema,
+	stored: TreeStoredSchema,
+): readonly SchemaDiscrepancy[] | undefined {
+	const discrepancies = [...getDiscrepanciesInAllowedContent(viewSchema, stored)];
+	if (discrepancies.length === 0) {
+		return undefined;
+	}
+
+	return discrepancies.map(formatSchemaDiscrepancy);
+}
+
+function formatSchemaDiscrepancy(value: Discrepancy): SchemaDiscrepancy {
+	switch (value.mismatch) {
+		case "allowedTypes": {
+			return {
+				mismatch: value.mismatch,
+				location:
+					value.identifier === undefined
+						? "root"
+						: {
+								nodeType: value.identifier,
+								fieldKey: value.fieldKey,
+							},
+				view: value.view.map(({ type }) => type.identifier).sort(),
+				...(value.stagedView === undefined
+					? {}
+					: {
+							stagedView: value.stagedView.map(({ type }) => type.identifier).sort(),
+						}),
+				stored: [...value.stored].sort(),
+				...(value.viewIsStagedOptional === true ? { viewIsStagedOptional: true } : {}),
+			};
+		}
+		case "fieldKind": {
+			return {
+				mismatch: value.mismatch,
+				location:
+					value.identifier === undefined
+						? "root"
+						: {
+								nodeType: value.identifier,
+								fieldKey: value.fieldKey,
+							},
+				view: value.view,
+				stored: value.stored,
+				...(value.viewIsStagedOptional === true ? { viewIsStagedOptional: true } : {}),
+			};
+		}
+		case "valueSchema": {
+			return {
+				mismatch: value.mismatch,
+				nodeType: value.identifier,
+				view: value.view === undefined ? undefined : ValueSchema[value.view],
+				stored: value.stored === undefined ? undefined : ValueSchema[value.stored],
+			};
+		}
+		case "nodeKind": {
+			const storedNodeKind =
+				value.stored === ObjectNodeStoredSchema
+					? "Object"
+					: value.stored === MapNodeStoredSchema
+						? "Map"
+						: "Leaf";
+			return {
+				mismatch: value.mismatch,
+				nodeType: value.identifier,
+				view: NodeKind[value.view],
+				stored: storedNodeKind,
+			};
+		}
+		default: {
+			return unreachableCase(value);
+		}
+	}
+}
+
+/**
+ * The enablement status of a staged schema upgrade in a document's stored schema.
+ *
+ * @remarks
+ * - `"disabled"` — no locations guarded by the upgrade are enabled in stored schema.
+ * - `"partial"` — at least one location is enabled but not all of them.
+ * - `"enabled"` — all locations guarded by the upgrade are enabled in stored schema.
+ *
+ * @alpha
+ */
+export type StagedUpgradeStatus = "disabled" | "partial" | "enabled";
 
 /**
  * Determines the compatibility of a stored document (based on its stored schema) with a viewer (based on its view schema).
@@ -24,27 +129,59 @@ import type { SchemaCompatibilityStatus } from "./tree.js";
  * @param viewSchema - Schema for the view
  * @param stored - The stored schema to check compatibility against
  * @param stagedSchemaUpgrades - Staged schema upgrades enabled for this view, or explicit stored-schema generation options
+ *
  */
 export function checkSchemaCompatibility(
 	viewSchema: TreeSchema,
 	stored: TreeStoredSchema,
 	stagedSchemaUpgrades?: Iterable<SchemaUpgrade> | StagedSchemaUpgradePolicy,
-): Omit<SchemaCompatibilityStatus, "canInitialize"> {
+): Omit<SchemaCompatibilityStatusBeta, "canInitialize"> & {
+	enabledUpgrades: ReadonlyMap<SchemaUpgrade, StagedUpgradeStatus>;
+} {
 	// The public API surface assumes defaultSchemaPolicy
 	const policy = defaultSchemaPolicy;
+	const configuredPolicy = resolveStoredSchemaGenerationOptions(stagedSchemaUpgrades);
+	const includeAlreadyEnabledUpgrades = configuredPolicy.includeAlreadyEnabledUpgrades ?? true;
+
+	// Collect upgrade locations during the discrepancy walk (single pass).
+	const totalLocations = new Map<SchemaUpgrade, number>();
+	const enabledLocations = new Map<SchemaUpgrade, number>();
+	const upgradeCollector: UpgradeLocationCollector = {
+		allowedType(upgrade, isEnabled) {
+			totalLocations.set(upgrade, (totalLocations.get(upgrade) ?? 0) + 1);
+			if (isEnabled) {
+				enabledLocations.set(upgrade, (enabledLocations.get(upgrade) ?? 0) + 1);
+			}
+		},
+		optionalField(upgrade, isEnabled) {
+			totalLocations.set(upgrade, (totalLocations.get(upgrade) ?? 0) + 1);
+			if (isEnabled) {
+				enabledLocations.set(upgrade, (enabledLocations.get(upgrade) ?? 0) + 1);
+			}
+		},
+	};
 
 	// View schema allows a subset of documents that stored schema does, and the discrepancies are allowed by policy
 	// determined by the view schema (i.e. objects with extra optional fields in the stored schema have opted into allowing this.
 	// In the future, this would also include things like:
 	// - fields with more allowed types in the stored schema than in the view schema have out-of-schema "unknown content" adapters
-	let canView = true;
-
-	for (const _discrepancy of getDiscrepanciesInAllowedContent(viewSchema, stored)) {
-		canView = false;
-		break;
+	// Complete the full walk even after finding an incompatibility so discrepancy details and
+	// staged-upgrade status contain all available information for debugging.
+	const discrepancies: SchemaDiscrepancy[] = [];
+	for (const discrepancy of getDiscrepanciesInAllowedContent(
+		viewSchema,
+		stored,
+		upgradeCollector,
+	)) {
+		discrepancies.push(formatSchemaDiscrepancy(discrepancy));
 	}
+	const canView = discrepancies.length === 0;
 
-	const wouldUpgradeTo = toUpgradeSchema(viewSchema.root, stagedSchemaUpgrades);
+	const enabledUpgrades = computeUpgradeStatuses(totalLocations, enabledLocations);
+	const upgradePolicy = includeAlreadyEnabledUpgrades
+		? includeEnabledUpgrades(configuredPolicy, enabledUpgrades)
+		: configuredPolicy;
+	const wouldUpgradeTo = toUpgradeSchema(viewSchema.root, upgradePolicy);
 
 	const canUpgrade = allowsRepoSuperset(policy, stored, wouldUpgradeTo);
 
@@ -57,5 +194,42 @@ export function checkSchemaCompatibility(
 		canView,
 		canUpgrade,
 		isEquivalent,
+		discrepancies: canView ? undefined : discrepancies,
+		enabledUpgrades,
 	};
 }
+
+function includeEnabledUpgrades(
+	configuredPolicy: StagedSchemaUpgradePolicy,
+	enabledUpgrades: ReadonlyMap<SchemaUpgrade, StagedUpgradeStatus>,
+): StagedSchemaUpgradePolicy {
+	if (enabledUpgrades.size === 0) {
+		return configuredPolicy;
+	}
+	return {
+		includeStaged: (upgrade) =>
+			configuredPolicy.includeStaged(upgrade) || enabledUpgrades.has(upgrade),
+		includeStagedOptional: (upgrade) =>
+			configuredPolicy.includeStagedOptional(upgrade) || enabledUpgrades.has(upgrade),
+	};
+}
+
+/**
+ * Computes the {@link StagedUpgradeStatus} for each upgrade token from total and enabled location counts.
+ * Only tokens with at least one enabled location are included in the returned map.
+ */
+function computeUpgradeStatuses(
+	totalLocations: ReadonlyMap<SchemaUpgrade, number>,
+	enabledLocations: ReadonlyMap<SchemaUpgrade, number>,
+): ReadonlyMap<SchemaUpgrade, StagedUpgradeStatus> {
+	const result = new Map<SchemaUpgrade, StagedUpgradeStatus>();
+	for (const [upgrade, total] of totalLocations) {
+		const enabled = enabledLocations.get(upgrade) ?? 0;
+		if (enabled > 0 && enabled < total) {
+			result.set(upgrade, "partial");
+		} else if (enabled >= total && enabled > 0) {
+			result.set(upgrade, "enabled");
+		}
+	}
+	return result;
+}

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

@@ -26,7 +26,7 @@ import type {
 	JsonCompatibleReadOnlyObject,
 } from "../../util/index.js";
 // eslint-disable-next-line @typescript-eslint/no-unused-vars -- This is referenced by doc comments.
-import type { Unhydrated } from "../core/index.js";
+import type { SchemaUpgrade, Unhydrated } from "../core/index.js";
 import type {
 	ImplicitFieldSchema,
 	InsertableField,
@@ -39,6 +39,7 @@ import type { SimpleTreeSchema } from "../simpleSchema.js";
 import type { UnsafeUnknownSchema } from "../unsafeUnknownSchema.js";
 
 import type { TreeViewConfiguration } from "./configuration.js";
+import type { StagedUpgradeStatus } from "./schemaCompatibilityTester.js";
 import type {
 	RunTransactionParamsAlpha,
 	RunTransactionParamsBeta,
@@ -601,9 +602,9 @@ export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends ID
 	 *
 	 * When using {@link TreeViewConfigurationAlpha} with a {@link ITreeViewConfigurationAlpha.stagedUpgradePolicy},
 	 * staged schema upgrades matching the configured policy are included in the target stored schema.
-	 * Once a staged schema upgrade has been enabled in a document's stored schema, loading that document
-	 * with a view that does not include equivalent staged members in its construction-time policy will cause
-	 * `upgradeSchema` to throw a `UsageError` because the requested target would narrow the stored schema.
+	 * Staged upgrades that are already enabled in the document are also included by default. Set
+	 * {@link (StagedSchemaUpgradePolicy:interface).includeAlreadyEnabledUpgrades} to `false` when
+	 * creating the policy to only include staged upgrades selected explicitly by the policy.
 	 *
 	 * @example Enabling a staged allowed type for documents, selected by a feature flag
 	 *
@@ -675,6 +676,164 @@ export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends ID
 	readonly schema: TSchema;
 }
 
+/**
+ * A discrepancy between a view schema and a document's stored schema.
+ *
+ * @remarks
+ * The `mismatch` property discriminates the different discrepancy shapes.
+ *
+ * @sealed @beta
+ */
+export type SchemaDiscrepancy =
+	| {
+			/**
+			 * Indicates that a field allows different node types in the view and stored schemas.
+			 */
+			readonly mismatch: "allowedTypes";
+			/**
+			 * The field with the discrepancy.
+			 *
+			 * `"root"` identifies the root field. Otherwise, `nodeType` identifies the containing
+			 * node schema and `fieldKey` identifies its field. `fieldKey` is undefined for a map
+			 * node's implicit field.
+			 */
+			readonly location:
+				| "root"
+				| {
+						readonly nodeType: string;
+						readonly fieldKey: string | undefined;
+				  };
+			/**
+			 * Non-staged node type identifiers allowed by the view schema but not the stored schema.
+			 */
+			readonly view: readonly string[];
+			/**
+			 * Staged node type identifiers allowed by the view schema but not the stored schema.
+			 *
+			 * @remarks These types provide rollout context but do not cause the discrepancy.
+			 */
+			readonly stagedView?: readonly string[];
+			/**
+			 * Node type identifiers allowed by the stored schema but not the view schema.
+			 */
+			readonly stored: readonly string[];
+			/**
+			 * Whether the view field is a staged optional field.
+			 *
+			 * @remarks Omitted when false.
+			 */
+			readonly viewIsStagedOptional?: true;
+	  }
+	| {
+			/**
+			 * Indicates that a field has different field kinds in the view and stored schemas.
+			 */
+			readonly mismatch: "fieldKind";
+			/**
+			 * The field with the discrepancy.
+			 *
+			 * `"root"` identifies the root field. Otherwise, `nodeType` identifies the containing
+			 * node schema and `fieldKey` identifies its field. `fieldKey` is undefined for a map
+			 * node's implicit field.
+			 */
+			readonly location:
+				| "root"
+				| {
+						readonly nodeType: string;
+						readonly fieldKey: string | undefined;
+				  };
+			/**
+			 * The field kind required by the view schema.
+			 */
+			readonly view: string;
+			/**
+			 * The field kind recorded in the stored schema.
+			 */
+			readonly stored: string;
+			/**
+			 * Whether the view field is a staged optional field.
+			 *
+			 * @remarks Omitted when false.
+			 */
+			readonly viewIsStagedOptional?: true;
+	  }
+	| {
+			/**
+			 * Indicates that a leaf node accepts different value types in the view and stored schemas.
+			 */
+			readonly mismatch: "valueSchema";
+			/**
+			 * The identifier of the leaf node schema with the discrepancy.
+			 */
+			readonly nodeType: string;
+			/**
+			 * The value schema required by the view, or undefined when it does not constrain values.
+			 */
+			readonly view: string | undefined;
+			/**
+			 * The value schema recorded in the stored schema, or undefined when it does not constrain values.
+			 */
+			readonly stored: string | undefined;
+	  }
+	| {
+			/**
+			 * Indicates that a node is represented by different node kinds in the view and stored schemas.
+			 */
+			readonly mismatch: "nodeKind";
+			/**
+			 * The identifier of the node schema with the discrepancy.
+			 */
+			readonly nodeType: string;
+			/**
+			 * The node kind required by the view schema.
+			 */
+			readonly view: string;
+			/**
+			 * The node kind recorded in the stored schema.
+			 */
+			readonly stored: string;
+	  };
+
+/**
+ * {@link SchemaCompatibilityStatus} with additional beta APIs.
+ *
+ * @sealed @beta
+ */
+export interface SchemaCompatibilityStatusBeta extends SchemaCompatibilityStatus {
+	/**
+	 * Details about the schema discrepancies that prevent this view from accessing the tree.
+	 *
+	 * @remarks
+	 * This property is undefined when {@link SchemaCompatibilityStatus.canView} is true and present
+	 * when `canView` is false.
+	 * It can include application-defined schema identifiers and field keys.
+	 *
+	 * @example Interpreting an allowed-types discrepancy
+	 *
+	 * If a document's stored schema allows `string` for `Todo.title`, but the view schema expects
+	 * `number`, the discrepancy identifies the field and the type permitted by each schema:
+	 *
+	 * ```typescript
+	 * const sf = new SchemaFactory("com.example");
+	 * class Todo extends sf.object("Todo", {
+	 * 	title: sf.number,
+	 * }) {}
+	 *
+	 * const view = asBeta(tree.viewWith(new TreeViewConfiguration({ schema: Todo })));
+	 * if (!view.compatibility.canView) {
+	 * 	// [{
+	 * 	//   mismatch: "allowedTypes",
+	 * 	//   location: { nodeType: "com.example.Todo", fieldKey: "title" },
+	 * 	//   view: ["com.fluidframework.leaf.number"],
+	 * 	//   stored: ["com.fluidframework.leaf.string"],
+	 * 	// }]
+	 * 	console.error(view.compatibility.discrepancies);
+	 * }
+	 * ```
+	 */
+	readonly discrepancies: readonly SchemaDiscrepancy[] | undefined;
+}
+
 /**
  * {@link TreeView} with additional beta APIs.
  * @sealed @beta
@@ -682,6 +841,11 @@ export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends ID
 export interface TreeViewBeta<in out TSchema extends ImplicitFieldSchema>
 	extends TreeView<TSchema>,
 		UntypedTreeView {
+	/**
+	 * {@inheritDoc TreeView.compatibility}
+	 */
+	readonly compatibility: SchemaCompatibilityStatusBeta;
+
 	// Override the base branch method to return a typed view rather than merely a branch.
 	fork(): ReturnType<UntypedTreeView["fork"]> & TreeViewBeta<TSchema>;
 
@@ -773,16 +937,29 @@ export interface TreeViewAlpha<
 	 * Only valid to call when this view's {@link SchemaCompatibilityStatus.canInitialize} is true.
 	 *
 	 * Enables staged schema upgrades declared by {@link ITreeViewConfigurationAlpha.stagedUpgradePolicy} when generating the initial stored schema.
-	 * Once a staged schema upgrade has been enabled in a document's stored schema, loading that document
-	 * with a view that does not include equivalent staged members in its construction-time policy will cause
-	 * a subsequent `upgradeSchema` call to throw a `UsageError` because the stored schema already contains
-	 * the upgraded members and the new target would narrow it.
 	 *
 	 * Applications should typically call this function before attaching a `SharedTree`.
 	 * @param content - The content to initialize the tree with.
 	 */
 	initialize(content: InsertableField<TSchema>): void;
 
+	/**
+	 * Checks whether a staged schema upgrade has been applied to the document's stored schema.
+	 *
+	 * @param upgrade - The upgrade token to check.
+	 *
+	 * @returns The {@link StagedUpgradeStatus} of the upgrade.
+	 *
+	 * @remarks
+	 * Use this to determine whether a document has already been upgraded, for example when deciding
+	 * whether to include an upgrade token in the view configuration after a feature flag rollback.
+	 *
+	 * Results are derived from this view's schema and the current stored schema.
+	 * The full schema is checked even when the view is incompatible with the stored schema, so the
+	 * result includes all locations declared by the view schema.
+	 */
+	isStagedUpgradeEnabled(upgrade: SchemaUpgrade): StagedUpgradeStatus;
+
 	readonly events: Listenable<TreeViewEvents & TreeBranchEvents>;
 
 	// Override the base fork method to return a TreeViewAlpha.

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

@@ -11,6 +11,14 @@ import type { SchemaUpgrade } from "./allowedTypes.js";
  * @alpha
  */
 export interface StagedSchemaUpgradePolicy {
+	/**
+	 * Whether schema upgrades should include staged upgrades that are already enabled in the
+	 * document's stored schema.
+	 *
+	 * @defaultValue `true`
+	 */
+	readonly includeAlreadyEnabledUpgrades?: boolean;
+
 	/**
 	 * Determines whether to include staged allowed types in the resulting stored schema.
 	 * @remarks

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

@@ -4,7 +4,7 @@
  */
 
 import { assert, fail } from "@fluidframework/core-utils/internal";
-import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import { tagSchemaArtifacts, UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { type FlexTreeNode, isFlexTreeNode } from "../../feature-libraries/index.js";
 
@@ -135,6 +135,7 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 			}) which derived from the same SchemaFactory generated class (${JSON.stringify(
 				this.identifier,
 			)}). This is invalid.`,
+			tagSchemaArtifacts({ schemaIdentifier: this.identifier }),
 		);
 	}
 
@@ -237,6 +238,7 @@ export function schemaAsTreeNodeValid(
 			`Schema for ${JSON.stringify(
 				schema.identifier,
 			)} does not extend a SchemaFactory generated class. This is invalid.`,
+			tagSchemaArtifacts({ schemaIdentifier: schema.identifier }),
 		);
 	}
 

package/src/simple-tree/index.ts

@@ -77,6 +77,8 @@ export {
 	type ITreeViewConfiguration,
 	type ITreeViewConfigurationAlpha,
 	type SchemaCompatibilityStatus,
+	type SchemaCompatibilityStatusBeta,
+	type SchemaDiscrepancy,
 	type ITreeConfigurationOptions,
 	SchemaFactory,
 	scoped,
@@ -137,6 +139,7 @@ export {
 	type TreeSchemaEncodingOptions,
 	getJsonSchema,
 	getSimpleSchema,
+	type StagedUpgradeStatus,
 	type VerboseTreeNode,
 	type TreeEncodingOptions,
 	type VerboseTree,
@@ -144,6 +147,7 @@ export {
 	comparePersistedSchema,
 	type ConciseTree,
 	checkSchemaCompatibility,
+	getSchemaIncompatibilityDetails,
 	type Unenforced,
 	type System_Unsafe,
 	type ArrayNodeCustomizableSchemaUnsafe,