@fluidframework/tree 2.116.1 → 2.118.0

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

@@ -67,6 +67,7 @@ export {
 export { walkFieldSchema } from "./walkFieldSchema.js";
 export type { UnsafeUnknownSchema, Insertable } from "./unsafeUnknownSchema.js";
 export {
+	type CommitRevision,
 	type ITree,
 	type TreeView,
 	type ViewableTree,
@@ -76,6 +77,8 @@ export {
 	type ITreeViewConfiguration,
 	type ITreeViewConfigurationAlpha,
 	type SchemaCompatibilityStatus,
+	type SchemaCompatibilityStatusBeta,
+	type SchemaDiscrepancy,
 	type ITreeConfigurationOptions,
 	SchemaFactory,
 	scoped,
@@ -136,6 +139,7 @@ export {
 	type TreeSchemaEncodingOptions,
 	getJsonSchema,
 	getSimpleSchema,
+	type StagedUpgradeStatus,
 	type VerboseTreeNode,
 	type TreeEncodingOptions,
 	type VerboseTree,
@@ -143,6 +147,7 @@ export {
 	comparePersistedSchema,
 	type ConciseTree,
 	checkSchemaCompatibility,
+	getSchemaIncompatibilityDetails,
 	type Unenforced,
 	type System_Unsafe,
 	type ArrayNodeCustomizableSchemaUnsafe,
@@ -159,9 +164,13 @@ export {
 	type InsertableObjectFromSchemaRecordAlphaUnsafe,
 	type TreeViewAlpha,
 	type TreeViewBeta,
+	type UntypedTreeView,
 	type TreeBranch,
 	type TreeBranchAlpha,
+	type UntypedTreeViewAlpha,
 	type TreeBranchEvents,
+	type TreeBranchCommitMetadata,
+	type TreeBranchHistory,
 	getPropertyKeyFromStoredKey,
 	getStoredKey,
 	tryGetSchema,

package/src/tableSchema.ts

@@ -1123,19 +1123,14 @@ export namespace System_TableSchema {
 				preconditionsOnRevert?: readonly TransactionConstraintAlpha[];
 			}): void {
 				const { applyEdits, preconditions, preconditionsOnRevert } = options;
-				const branch = TreeAlpha.branch(this);
+				const context = TreeAlpha.context(this);
 
 				// Ensure events are paused until all of the edits are applied.
 				// This ensures that the user sees the corresponding table-level edit as atomic,
 				// and ensures they are not spammed with intermediate events.
 				withBufferedTreeEvents(() => {
-					if (branch === undefined) {
-						// If this node does not have a corresponding branch, then it is unhydrated.
-						// I.e., it is not part of a collaborative session yet.
-						// Therefore, we don't need to run the edits as a transaction.
-						applyEdits();
-					} else {
-						branch.runTransaction(
+					if (context.isView()) {
+						context.runTransaction(
 							() => {
 								applyEdits();
 								if (preconditionsOnRevert !== undefined) {
@@ -1144,6 +1139,11 @@ export namespace System_TableSchema {
 							},
 							preconditions === undefined ? undefined : { preconditions },
 						);
+					} else {
+						// If this node does not have a corresponding view, then it is unhydrated.
+						// I.e., it is not part of a collaborative session yet.
+						// Therefore, we don't need to run the edits as a transaction.
+						applyEdits();
 					}
 				});
 			}
@@ -1168,7 +1168,7 @@ export namespace System_TableSchema {
 			#buildColumnInDocumentConstraintsForRows(
 				rows: Iterable<RowValueType>,
 			): TransactionConstraintAlpha[] | undefined {
-				if (!TreeAlpha.context(this).isBranch()) {
+				if (!TreeAlpha.context(this).isView()) {
 					return undefined;
 				}
 

package/docs/main/runtime-schema-upgrade.md

@@ -1,208 +0,0 @@
-# Runtime Schema Upgrade Mechanism
-
-> This document was generated by AI. It is intended for consumption by AI agents when working on this feature. Any change to the Runtime Schema Upgrade Mechanism should also update this document so future agents have current design context.
-
-## Summary
-
-Runtime schema upgrades let an application opt specific staged schema upgrades into stored schema when initializing a document or upgrading its stored schema.
-A staged schema upgrade is a schema upgrade that is declared in view schema but omitted from stored schema unless the application explicitly enables it.
-
-Enabled upgrades are provided at view construction time via `stagedUpgradePolicy` in alpha configuration passed to `viewWith`.
-The configured policy is fixed for that view instance and cannot be changed later through view APIs.
-
-This keeps the view schema and upgrade policy together in one place: the view configuration.
-Compatibility checking and schema generation both use that same construction-time upgrade set.
-
-## Problem
-
-### Testing Future Documents
-
-Problem: There is currently no easy way to create a test document that simulates a future version having completed a staged schema upgrade.
-Declaring a staged schema upgrade in the view schema is not enough to change the document: `initialize` and `upgradeSchema` only make that upgrade usable when they include it in the stored schema.
-As a result, an application cannot easily test whether the current version works correctly with documents created or upgraded by a future version.
-
-Solution: tests construct a view with an alpha configuration that includes selected staged schema upgrades which get applied to the stored schema when calling `initialize` or `upgradeSchema`.
-This makes it possible to create documents whose stored schema matches the state a future version would produce, while still running the test against the current application code.
-
-### Production Rollout Control
-
-Problem: In production, developers often need to deploy code that can read and write an upgraded schema before they are ready to enable that schema in documents.
-Without a runtime enablement mechanism, code rollout and feature rollout are coupled: once the staged schema upgrade stops being excluded from stored schema, all relevant documents may begin accepting the upgraded shape.
-This is risky for teams that need gradual rollout, monitoring, or fast rollback but do not have sophisticated slow-rollout tooling.
-
-Solution: applications derive `stagedUpgradePolicy` from feature flags and include it in view construction options.
-Code rollout can deploy support for the upgraded schema first, and feature rollout can later enable the staged schema upgrade by constructing views with the relevant `SchemaUpgrade` values.
-If the feature needs to be rolled back, applications stop constructing views with those values for documents that have not already been upgraded.
-
-The general production rollout process is:
-
-1. Deploy code that understands both the current schema and the upgraded schema.
-   Views are constructed with alpha configuration that includes `stagedUpgradePolicy`, but the flag initially leaves it as `undefined` (restrictive default).
-2. Enable the feature-rollout control.
-   New views are constructed with the relevant `SchemaUpgrade` values enabled.
-3. Existing documents are upgraded through `upgradeSchema`.
-   A schema op is sequenced for each upgraded document.
-   Once the op is in the document, all clients observe the upgraded stored schema, including clients whose local feature flag is off.
-4. New documents initialized while the control is enabled include the same staged schema upgrades from the start.
-5. If an issue is found, disable the feature-rollout control.
-   Callers stop constructing views with the relevant entries for documents that have not yet been upgraded and newly initialized documents do not include those staged schema members.
-   Note: this selective rollback plan is currently difficult in practice.
-   If a document has already enabled a staged upgrade, later calling `upgradeSchema` from a view configured without that token throws a `UsageError` because the request would narrow stored schema.
-   In most deployments it is hard to target only documents that have not already been upgraded, so this step is not generally feasible as written.
-
-Documents upgraded before the rollback continue to support the upgraded schema because their stored schema has already changed.
-Documents created after the rollback do not include that upgrade unless the flag is enabled again.
-
-## Goals
-
-- Allow callers to enable selected staged schema upgrades during `initialize`.
-- Allow callers to enable selected staged schema upgrades during `upgradeSchema`.
-- Make enabling an upgrade granular: only staged schema members associated with the supplied `SchemaUpgrade` values are included in the generated stored schema.
-- Support both production feature-flag rollouts and tests that simulate documents created or upgraded by a future application version.
-- Keep the default behavior unchanged when upgrades are omitted, `undefined`, or empty.
-- Keep view APIs immutable with respect to upgrade enablement after construction.
-- Support an easy integration-test mode that enables all staged upgrades.
-- Support composition/wrapping of generation options.
-
-## API Shape
-
-The alpha flow sets staged-upgrade policy in view construction:
-
-```typescript
-const view = tree.viewWith(
-	new TreeViewConfigurationAlpha({
-		schema: AppSchema,
-		stagedUpgradePolicy: featureFlags.enableFooUpgrade
-			? StagedSchemaUpgradePolicy.enabledStagedUpgrades(fooSchemaUpgrade)
-			: undefined,
-	}),
-);
-
-if (view.compatibility.canInitialize) {
-	view.initialize(initialContent);
-} else if (view.compatibility.canUpgrade) {
-	view.upgradeSchema();
-}
-```
-
-Key properties of this shape:
-
-- The upgrade set is fixed when the view is created.
-- `compatibility.canUpgrade`, `initialize`, and `upgradeSchema` all observe the same configured target.
-
-### Accepting `StagedSchemaUpgradePolicy`
-
-View construction accepts an optional `StagedSchemaUpgradePolicy` policy object via `TreeViewConfigurationAlpha.stagedUpgradePolicy`.
-This keeps policy selection at view construction time while allowing advanced callers to configure staged-type and staged-optional inclusion directly.
-
-The `StagedSchemaUpgradePolicy` namespace provides factory methods:
-
-- `.restrictive` — excludes all staged schema members (default when omitted).
-- `.permissive` — includes all staged schema upgrades (useful for testing).
-- `.enabledStagedUpgrades(...upgrades)` — includes only staged members guarded by the specified `SchemaUpgrade` values.
-
-```typescript
-const enabled = new Set<SchemaUpgrade>([fooSchemaUpgrade]);
-
-const view = tree.viewWith(
-	new TreeViewConfigurationAlpha({
-		schema: AppSchema,
-		stagedUpgradePolicy: {
-			includeStaged: (upgrade) => enabled.has(upgrade),
-			includeStagedOptional: (upgrade) => enabled.has(upgrade),
-		},
-	}),
-);
-```
-
-Custom policy objects conforming to `StagedSchemaUpgradePolicy` are also accepted for advanced use cases.
-
-Benefits:
-
-- Keeps schema-generation policy explicit and colocated with view construction.
-- Supports layered policy composition (base + local override) without adding mutable view APIs.
-- Preserves single-source-of-truth behavior: compatibility checks and schema generation consume the same resolved policy.
-- Enables broad integration-test scenarios (for example, all staged upgrades enabled) with `StagedSchemaUpgradePolicy.permissive`.
-
-Future consideration:
-
-- It may be useful to have the view expose the same type, `StagedSchemaUpgradePolicy`, for what is currently in the stored schema
-- That could let callers test whether a specific upgrade is already included.
-- That could clarify that the exposed policy is the default used when no custom options are declared.
-- Callers could build wrapper policies from that baseline instead of reconstructing it.
-
-## Why Construction-Time Upgrades?
-
-Construction-time configuration keeps staged-upgrade policy colocated with the view schema and avoids mutable runtime policy on the view instance.
-That has practical benefits:
-
-- Eliminates ordering concerns between view creation, compatibility reads, and upgrade declaration calls.
-- Prevents accidental policy drift on a long-lived view.
-- Ensures compatibility checks and schema writes always use the same immutable policy for a given view.
-- Makes testing deterministic because each view clearly represents one schema+upgrade configuration.
-
-## Initialization Versus Upgrade
-
-`initialize(...)` and `upgradeSchema()` both use the configured upgrades but affect different scenarios:
-
-- `upgradeSchema()` upgrades existing document stored schema.
-- `initialize(...)` writes initial stored schema and content for new documents.
-
-The insertion/validation path for initialization must use the same generated schema target as compatibility and upgrade paths.
-
-## Implementation Notes
-
-Stored schema generation remains based on `toUpgradeSchema(root, options?)` and `toInitialSchema(root, options?)`.
-The view is responsible for passing `stagedUpgradePolicy` from construction-time configuration to these helpers.
-
-`StagedSchemaUpgradePolicy.restrictive` and `StagedSchemaUpgradePolicy.permissive` provide built-in defaults for "none" and "all" staged-upgrade inclusion.
-`StagedSchemaUpgradePolicy.enabledStagedUpgrades(...upgrades)` converts a collection of `SchemaUpgrade` values into generation options.
-The `stagedUpgradePolicy` field on `ITreeViewConfigurationAlpha` is used directly as the source policy for compatibility and schema generation.
-
-Behavioral requirements:
-
-- No configured options (or `undefined`) means restrictive default behavior.
-- Configured options enable only staged members guarded by matching `SchemaUpgrade` values.
-- `upgradeSchema()` is a no-op when stored schema is already a superset of the configured target.
-- `upgradeSchema()` throws when the configured target is not a valid repo superset of current stored schema.
-
-## Testing Strategy
-
-Tests should cover both API entry points, the staged schema member kinds that are currently supported, and rollback-oriented production behavior.
-
-Generic runtime API tests should cover shared behavior such as creating a view with `stagedUpgradePolicy` and calling `initialize(content)` to accept enabled staged content, while rejecting that content when options are not configured.
-More specialized staged schema tests should exercise configured options with `upgradeSchema()` for each staged schema feature, such as staged allowed types and staged optional fields.
-
-When `StagedSchemaUpgradePolicy` is accepted at view construction, tests should also cover custom policy-object configuration paths in addition to the namespace factory methods.
-
-For `upgradeSchema`:
-
-- Create a document with the current schema.
-- Construct a view with configured upgrades.
-- Call `upgradeSchema()`.
-- Verify the stored schema includes the staged schema members guarded by the configured upgrade token.
-- Verify clients using a view configuration that omits that token observe expected compatibility/upgrade behavior.
-
-For `initialize`:
-
-- Construct a view with configured upgrades and initialize a new document with `initialize(content)`.
-- Use initial content that requires the upgraded schema.
-- Verify the content is accepted and the stored schema includes the enabled staged schema upgrade.
-- Verify constructing a view without upgrades rejects or excludes content that depends on that upgrade, matching existing restrictive behavior.
-
-For feature-flag rollback behavior:
-
-- Verify documents created or upgraded while the flag is enabled retain the upgraded stored schema.
-- Verify documents created after the flag is disabled omit the upgraded schema when callers construct views without the corresponding upgrade entry.
-
-Schema compatibility helper tests should remain schema-only.
-They can validate compatibility across staged rollout states by comparing stored schema snapshots, but they should not be used as substitutes for runtime tests that sequence schema edits through `initialize` or `upgradeSchema`.
-
-## Compatibility Notes
-
-Enabling a staged schema upgrade changes document stored schema through the existing schema update mechanism.
-Once the schema change is sequenced, the document state is authoritative.
-Clients should not need their local feature flag to be enabled in order to read a document whose stored schema already includes the upgrade, provided their code version understands that schema.
-
-The `upgrades` property names are not persisted.
-Compatibility depends on the schema and the `SchemaUpgrade` values, not on the application-specific flag names used at call sites.