@fluidframework/tree 2.52.0 → 2.53.0

package/.eslintrc.cjs

@@ -89,6 +89,19 @@ module.exports = {
 		"unicorn/switch-case-braces": "off",
 		"unicorn/text-encoding-identifier-case": "off",
 
+		"@typescript-eslint/no-restricted-imports": [
+			"error",
+			{
+				"patterns": [
+					{
+						"group": ["./index.js", "**/../index.js"],
+						"message":
+							"Importing from a parent index file tends to cause cyclic dependencies. Import from a more specific sibling file instead.",
+					},
+				],
+			},
+		],
+
 		// #endregion
 	},
 	overrides: [
@@ -102,11 +115,10 @@ module.exports = {
 				"@typescript-eslint/explicit-function-return-type": "off",
 			},
 		},
-		// TODO: Remove this override once this config has been updated to extend at least the "recommended" base config.
 		{
 			files: ["src/test/**/*.generated.ts*"],
 			rules: {
-				"@typescript-eslint/no-explicit-any": ["off"],
+				"@typescript-eslint/no-restricted-imports": ["off"],
 			},
 		},
 	],

package/CHANGELOG.md

@@ -1,5 +1,130 @@
 # @fluidframework/tree
 
+## 2.53.0
+
+### Minor Changes
+
+- TableSchema's "removeColumn" API now removes corresponding cells (alpha) ([#25213](https://github.com/microsoft/FluidFramework/pull/25213)) [b665ba8320d](https://github.com/microsoft/FluidFramework/commit/b665ba8320d9ab6d1b87de81bdf54c2fde20e5c1)
+
+  Previously, the [removeColumn](https://fluidframework.com/docs/api/fluid-framework/tableschema-namespace/table-interface#removecolumn-methodsignature) API on Table nodes derived from [TableSchema](https://fluidframework.com/docs/api/fluid-framework/tableschema-namespace/) (alpha) only removed the `Column` node from the list of columns tracked by the table.
+  To also remove the corresponding cells from the table (which are stored on the `Row` nodes), the user was required to write a custom transaction that removed the column and cells.
+
+  The motivation for this design was due to performance concerns with transactions.
+  Those concerns are still relevant, but the data leak risk of dropping columns without removing corresponding cells seems a greater risk, and we have plans to address the performance issues with transactions.
+
+- Adds staged allowed types to SchemaFactoryAlpha ([#25116](https://github.com/microsoft/FluidFramework/pull/25116)) [59baf03ac7f](https://github.com/microsoft/FluidFramework/commit/59baf03ac7f2f2779533c8c63e1de85c01a0d39a)
+
+  This adds the `staged` API to [`SchemaFactoryAlpha`](https://fluidframework.com/docs/api/fluid-framework/schemafactoryalpha-class).
+  Staged allowed types can be used for schema evolution to add members to an [`AllowedTypes`](https://fluidframework.com/docs/api/fluid-framework/allowedtypes-typealias) while supporting cross version collaboration.
+
+  Staged allowed types are [allowed types](https://fluidframework.com/docs/api/fluid-framework/allowedtypes-typealias) that can be upgraded by [schema upgrades](https://fluidframework.com/docs/api/fluid-framework/treeview-interface#upgradeschema-methodsignature).
+  Before being upgraded, any attempt to insert or move a node to a location which requires its type to be upgraded to be valid will throw an error.
+
+  To add a new member to an `AllowedTypes`, add the type wrapped by `staged`.
+  For example, migrating an array which previously supported only numbers to support both numbers and strings would start by deploying a version of the app using `staged`:
+
+  ```typescript
+  class TestArray extends schemaFactoryAlpha.arrayAlpha("TestArray", [
+    SchemaFactoryAlpha.number,
+    SchemaFactoryAlpha.staged(SchemaFactoryAlpha.string),
+  ]) {}
+  ```
+
+  Once enough clients have this code update, it is safe to allow writing strings to the array.
+  To allow writing strings to the array, a code change must be made to remove the staged annotation:
+
+  ```typescript
+  class TestArray extends schemaFactoryAlpha.arrayAlpha("TestArray", [
+    schemaFactoryAlpha.number,
+    schemaFactoryAlpha.string,
+  ]) {}
+  ```
+
+  Then when opening old documents [upgradeSchema](https://fluidframework.com/docs/api/fluid-framework/treeview-interface#upgradeschema-methodsignature) is used to upgrade the stored schema:
+
+  ```typescript
+  view.upgradeSchema();
+  ```
+
+  The `@alpha` API [extractPersistedSchema](https://fluidframework.com/docs/api/fluid-framework#extractpersistedschema-function) now takes the schema as an `ImplicitAnnotatedFieldSchema` and an additional parameter to filter which staged upgrades it includes.
+
+  Below is a full example of how the schema migration process works.
+  This can also be found in the [tests](https://github.com/microsoft/FluidFramework/blob/main/packages/dds/tree/src/test/simple-tree/api/stagedSchemaUpgrade.spec.ts).
+
+  ```typescript
+  // Schema A: only number allowed
+  const schemaA = SchemaFactoryAlpha.optional([SchemaFactoryAlpha.number]);
+
+  // Schema B: number or string (string is staged)
+  const schemaB = SchemaFactoryAlpha.optional([
+    SchemaFactoryAlpha.number,
+    SchemaFactoryAlpha.staged(SchemaFactoryAlpha.string),
+  ]);
+
+  // Schema C: number or string, both fully allowed
+  const schemaC = SchemaFactoryAlpha.optional([
+    SchemaFactoryAlpha.number,
+    SchemaFactoryAlpha.string,
+  ]);
+
+  // Initialize with schema A.
+  const configA = new TreeViewConfiguration({
+    schema: schemaA,
+  });
+  const viewA = treeA.viewWith(configA);
+  viewA.initialize(5);
+
+  // Since we are running all the different versions of the app in the same process making changes synchronously,
+  // an explicit flush is needed to make them available to each other.
+  synchronizeTrees();
+
+  assert.deepEqual(viewA.root, 5);
+
+  // View the same document with a second tree using schema B.
+  const configB = new TreeViewConfiguration({
+    schema: schemaB,
+  });
+  const viewB = treeB.viewWith(configB);
+  // B cannot write strings to the root.
+  assert.throws(() => (viewB.root = "test"));
+
+  // View the same document with a third tree using schema C.
+  const configC = new TreeViewConfiguration({
+    schema: schemaC,
+  });
+  const viewC = treeC.viewWith(configC);
+  // Upgrade to schema C
+  viewC.upgradeSchema();
+  // Use the newly enabled schema.
+  viewC.root = "test";
+
+  synchronizeTrees();
+
+  // View A is now incompatible with the stored schema:
+  assert.equal(viewA.compatibility.canView, false);
+
+  // View B can still read the document, and now sees the string root which relies on the staged schema.
+  assert.deepEqual(viewB.root, "test");
+  ```
+
+- Allow edits in arrays to be concurrent to dependent edits of transactions with violated constraints ([#25191](https://github.com/microsoft/FluidFramework/pull/25191)) [ef64bae6ab2](https://github.com/microsoft/FluidFramework/commit/ef64bae6ab2848c67d778d14ad56ae021f54ac7a)
+
+  Before this release, making concurrent edits to an array could lead to assertion error `0x8a2` being thrown if the following conditions were met:
+
+  - Some edit `e1` was a transaction with a constraint that turned out to be violated by edits concurrent to (and sequenced before) `e1`
+  - Some edit `e2` was dependent on `e1` (from before the violation of its constraint)
+  - Some edit `e3` was concurrent to and sequenced after both `e1` and `e2`
+  - `e3` was either concurrent to or the revert of some other edit `e0` that predated `e1`, `e2`, and `e3`.
+  - `e0` and `e2` made edits to the same gap (that is, in the same space between nodes) in the sequence/array.
+
+  After this release, these scenarios will work as expected (that is, no assertion error thrown).
+
+- Export TreeNode not only as a type ([#25226](https://github.com/microsoft/FluidFramework/pull/25226)) [eefb9522c01](https://github.com/microsoft/FluidFramework/commit/eefb9522c019ac68d8b4f40d7134116c78a1f2a5)
+
+  `TreeNode` can now be used as a runtime object.
+  This enables checking if an object is a `TreeNode` with `instanceof`.
+  `TreeNode` has customized `instanceof` support so it can detect `TreeNode` instances, even if they hide their prototype like [POJO mode nodes](https://fluidframework.com/docs/api/fluid-framework/schemafactory-class#schemafactory-remarks) do.
+
 ## 2.52.0
 
 ### Minor Changes

package/api-report/tree.alpha.api.md

@@ -15,15 +15,16 @@ export function adaptEnum<TScope extends string, const TEnum extends Record<stri
         }, Record<string, never>, true, Record<string, never>, undefined>; }[keyof TEnum]>;
 };
 
-// @alpha
+// @alpha @input
 export interface AllowedTypeMetadata {
     readonly custom?: unknown;
+    readonly stagedSchemaUpgrade?: SchemaUpgrade;
 }
 
 // @public @system
 export type AllowedTypes = readonly LazyItem<TreeNodeSchema>[];
 
-// @alpha
+// @alpha @input
 export interface AllowedTypesMetadata {
     readonly custom?: unknown;
 }
@@ -31,16 +32,16 @@ export interface AllowedTypesMetadata {
 // @alpha
 export function allowUnused<T>(t?: T): void;
 
-// @alpha
+// @alpha @sealed
 export interface AnnotatedAllowedType<T = LazyItem<TreeNodeSchema>> {
     readonly metadata: AllowedTypeMetadata;
     readonly type: T;
 }
 
-// @alpha
-export interface AnnotatedAllowedTypes {
+// @alpha @sealed
+export interface AnnotatedAllowedTypes<T = LazyItem<TreeNodeSchema>> {
     readonly metadata: AllowedTypesMetadata;
-    readonly types: readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[];
+    readonly types: readonly AnnotatedAllowedType<T>[];
 }
 
 // @public @system
@@ -157,7 +158,7 @@ export function evaluateLazySchema<T extends TreeNodeSchema>(value: LazyItem<T>)
 type ExtractItemType<Item extends LazyItem> = Item extends () => infer Result ? Result : Item;
 
 // @alpha
-export function extractPersistedSchema(schema: SimpleTreeSchema, oldestCompatibleClient: FluidClientVersion): JsonCompatible;
+export function extractPersistedSchema(schema: ImplicitAnnotatedFieldSchema, oldestCompatibleClient: FluidClientVersion, includeStaged: (upgrade: SchemaUpgrade) => boolean): JsonCompatible;
 
 // @alpha @system
 export type FactoryContent = IFluidHandle | string | number | boolean | null | Iterable<readonly [string, InsertableContent]> | readonly InsertableContent[] | FactoryContentObject;
@@ -297,10 +298,10 @@ export type IdentifierIndex = SimpleTreeIndex<string, TreeNode>;
 // @public
 export type ImplicitAllowedTypes = AllowedTypes | TreeNodeSchema;
 
-// @alpha
+// @alpha @input
 export type ImplicitAnnotatedAllowedTypes = TreeNodeSchema | AnnotatedAllowedType | AnnotatedAllowedTypes | readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[];
 
-// @alpha
+// @alpha @input
 export type ImplicitAnnotatedFieldSchema = FieldSchema | ImplicitAnnotatedAllowedTypes;
 
 // @public
@@ -430,16 +431,14 @@ export namespace JsonAsTree {
     export class JsonObject extends _APIExtractorWorkaroundObjectBase {
     }
     const // @system
-    _APIExtractorWorkaroundObjectBase: TreeNodeSchemaClass<"com.fluidframework.json.object", NodeKind.Record, TreeRecordNodeUnsafe_2<readonly [LeafSchema<"null", null>, LeafSchema<"number", number>, LeafSchema<"string", string>, LeafSchema<"boolean", boolean>, () => typeof JsonObject, () => typeof Array]> & WithType<"com.fluidframework.json.object", NodeKind.Record, unknown>, {
+    _APIExtractorWorkaroundObjectBase: TreeNodeSchemaClass<"com.fluidframework.json.object", NodeKind.Record, TreeRecordNodeUnsafe<readonly [LeafSchema<"null", null>, LeafSchema<"number", number>, LeafSchema<"string", string>, LeafSchema<"boolean", boolean>, () => typeof JsonObject, () => typeof Array]> & WithType<"com.fluidframework.json.object", NodeKind.Record, unknown>, {
         readonly [x: string]: string | number | JsonObject | Array | System_Unsafe.InsertableTypedNodeUnsafe<LeafSchema<"boolean", boolean>, LeafSchema<"boolean", boolean>> | null;
     }, false, readonly [LeafSchema<"null", null>, LeafSchema<"number", number>, LeafSchema<"string", string>, LeafSchema<"boolean", boolean>, () => typeof JsonObject, () => typeof Array], undefined>;
-    // (undocumented)
     export type Primitive = TreeNodeFromImplicitAllowedTypes<typeof Primitive>;
     // @system
     export type _RecursiveArrayWorkaroundJsonArray = FixRecursiveArraySchema<typeof Array>;
     const // @system
-    _APIExtractorWorkaroundArrayBase: ArrayNodeCustomizableSchemaUnsafe_2<"com.fluidframework.json.array", readonly [LeafSchema<"null", null>, LeafSchema<"number", number>, LeafSchema<"string", string>, LeafSchema<"boolean", boolean>, () => typeof JsonObject, () => typeof Array], unknown>;
-    // (undocumented)
+    _APIExtractorWorkaroundArrayBase: ArrayNodeCustomizableSchemaUnsafe<"com.fluidframework.json.array", readonly [LeafSchema<"null", null>, LeafSchema<"number", number>, LeafSchema<"string", string>, LeafSchema<"boolean", boolean>, () => typeof JsonObject, () => typeof Array], unknown>;
     export type Tree = TreeNodeFromImplicitAllowedTypes<typeof Tree>;
 }
 
@@ -624,10 +623,8 @@ export interface NodeSchemaOptionsAlpha<out TCustomMetadata = unknown> extends N
 // @alpha
 export const noopValidator: JsonValidator;
 
-// @alpha
-export interface NormalizedAnnotatedAllowedTypes {
-    readonly metadata: AllowedTypesMetadata;
-    readonly types: readonly AnnotatedAllowedType<TreeNodeSchema>[];
+// @alpha @sealed
+export interface NormalizedAnnotatedAllowedTypes extends AnnotatedAllowedTypes<TreeNodeSchema> {
 }
 
 // @public @system
@@ -814,9 +811,9 @@ export class SchemaFactory<out TScope extends string | undefined = string | unde
 export class SchemaFactoryAlpha<out TScope extends string | undefined = string | undefined, TName extends number | string = string> extends SchemaFactory<TScope, TName> {
     arrayAlpha<const Name extends TName, const T extends ImplicitAnnotatedAllowedTypes, const TCustomMetadata = unknown>(name: Name, allowedTypes: T, options?: NodeSchemaOptionsAlpha<TCustomMetadata>): ArrayNodeCustomizableSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata>;
     arrayRecursive<const Name extends TName, const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(name: Name, allowedTypes: T, options?: NodeSchemaOptionsAlpha<TCustomMetadata>): ArrayNodeCustomizableSchemaUnsafe<ScopedSchemaName<TScope, Name>, T, TCustomMetadata>;
-    static readonly identifier: <const TCustomMetadata = unknown>(props?: Omit<FieldProps_2<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha_2<FieldKind_2.Identifier, LeafSchema_2<"string", string> & SimpleLeafNodeSchema_2, TCustomMetadata>;
-    static readonly leaves: readonly [LeafSchema_2<"string", string> & SimpleLeafNodeSchema_2, LeafSchema_2<"number", number> & SimpleLeafNodeSchema_2, LeafSchema_2<"boolean", boolean> & SimpleLeafNodeSchema_2, LeafSchema_2<"null", null> & SimpleLeafNodeSchema_2, LeafSchema_2<"handle", IFluidHandle<unknown>> & SimpleLeafNodeSchema_2];
-    readonly leaves: readonly [LeafSchema_2<"string", string> & SimpleLeafNodeSchema_2, LeafSchema_2<"number", number> & SimpleLeafNodeSchema_2, LeafSchema_2<"boolean", boolean> & SimpleLeafNodeSchema_2, LeafSchema_2<"null", null> & SimpleLeafNodeSchema_2, LeafSchema_2<"handle", IFluidHandle<unknown>> & SimpleLeafNodeSchema_2];
+    static readonly identifier: <const TCustomMetadata = unknown>(props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Identifier, LeafSchema<"string", string> & SimpleLeafNodeSchema, TCustomMetadata>;
+    static readonly leaves: readonly [LeafSchema<"string", string> & SimpleLeafNodeSchema, LeafSchema<"number", number> & SimpleLeafNodeSchema, LeafSchema<"boolean", boolean> & SimpleLeafNodeSchema, LeafSchema<"null", null> & SimpleLeafNodeSchema, LeafSchema<"handle", IFluidHandle<unknown>> & SimpleLeafNodeSchema];
+    readonly leaves: readonly [LeafSchema<"string", string> & SimpleLeafNodeSchema, LeafSchema<"number", number> & SimpleLeafNodeSchema, LeafSchema<"boolean", boolean> & SimpleLeafNodeSchema, LeafSchema<"null", null> & SimpleLeafNodeSchema, LeafSchema<"handle", IFluidHandle<unknown>> & SimpleLeafNodeSchema];
     mapAlpha<Name extends TName, const T extends ImplicitAnnotatedAllowedTypes, const TCustomMetadata = unknown>(name: Name, allowedTypes: T, options?: NodeSchemaOptionsAlpha<TCustomMetadata>): MapNodeCustomizableSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata>;
     mapRecursive<Name extends TName, const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(name: Name, allowedTypes: T, options?: NodeSchemaOptionsAlpha<TCustomMetadata>): MapNodeCustomizableSchemaUnsafe<ScopedSchemaName<TScope, Name>, T, TCustomMetadata>;
     objectAlpha<const Name extends TName, const T extends RestrictiveStringRecord<ImplicitAnnotatedFieldSchema>, const TCustomMetadata = unknown>(name: Name, fields: T, options?: SchemaFactoryObjectOptions<TCustomMetadata>): ObjectNodeSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> & {
@@ -824,15 +821,15 @@ export class SchemaFactoryAlpha<out TScope extends string | undefined = string |
     };
     objectRecursive<const Name extends TName, const T extends RestrictiveStringRecord<System_Unsafe.ImplicitFieldSchemaUnsafe>, const TCustomMetadata = unknown>(name: Name, t: T, options?: SchemaFactoryObjectOptions<TCustomMetadata>): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Object, System_Unsafe.TreeObjectNodeUnsafe<T, ScopedSchemaName<TScope, Name>>, object & System_Unsafe.InsertableObjectFromSchemaRecordUnsafe<T>, false, T, never, TCustomMetadata> & SimpleObjectNodeSchema<TCustomMetadata> & Pick<ObjectNodeSchema, "fields">;
     static readonly optional: {
-        <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha_2<TCustomMetadata>, "defaultProvider"> | undefined): FieldSchemaAlpha_2<FieldKind_2.Optional, T, TCustomMetadata>;
-        <const T_1 extends ImplicitAnnotatedAllowedTypes, const TCustomMetadata_1 = unknown>(t: T_1, props?: Omit<FieldPropsAlpha_2<TCustomMetadata_1>, "defaultProvider"> | undefined): FieldSchemaAlpha_2<FieldKind_2.Optional, UnannotateImplicitAllowedTypes_2<T_1>, TCustomMetadata_1>;
+        <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined): FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata>;
+        <const T_1 extends ImplicitAnnotatedAllowedTypes, const TCustomMetadata_1 = unknown>(t: T_1, props?: Omit<FieldPropsAlpha<TCustomMetadata_1>, "defaultProvider"> | undefined): FieldSchemaAlpha<FieldKind.Optional, UnannotateImplicitAllowedTypes<T_1>, TCustomMetadata_1>;
     };
     readonly optional: {
-        <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha_2<TCustomMetadata>, "defaultProvider"> | undefined): FieldSchemaAlpha_2<FieldKind_2.Optional, T, TCustomMetadata>;
-        <const T_1 extends ImplicitAnnotatedAllowedTypes, const TCustomMetadata_1 = unknown>(t: T_1, props?: Omit<FieldPropsAlpha_2<TCustomMetadata_1>, "defaultProvider"> | undefined): FieldSchemaAlpha_2<FieldKind_2.Optional, UnannotateImplicitAllowedTypes_2<T_1>, TCustomMetadata_1>;
+        <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined): FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata>;
+        <const T_1 extends ImplicitAnnotatedAllowedTypes, const TCustomMetadata_1 = unknown>(t: T_1, props?: Omit<FieldPropsAlpha<TCustomMetadata_1>, "defaultProvider"> | undefined): FieldSchemaAlpha<FieldKind.Optional, UnannotateImplicitAllowedTypes<T_1>, TCustomMetadata_1>;
     };
-    static readonly optionalRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha_2<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe_2<FieldKind_2.Optional, T, TCustomMetadata>;
-    readonly optionalRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha_2<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe_2<FieldKind_2.Optional, T, TCustomMetadata>;
+    static readonly optionalRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Optional, T, TCustomMetadata>;
+    readonly optionalRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Optional, T, TCustomMetadata>;
     record<const T extends TreeNodeSchema | readonly TreeNodeSchema[]>(allowedTypes: T): TreeNodeSchemaNonClass<ScopedSchemaName<TScope, `Record<${string}>`>, NodeKind.Record, TreeRecordNode<T> & WithType<ScopedSchemaName<TScope, `Record<${string}>`>, NodeKind.Record>, RecordNodeInsertableData<T>, true, T, undefined>;
     record<const Name extends TName, const T extends ImplicitAllowedTypes>(name: Name, allowedTypes: T): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Record, TreeRecordNode<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Record>, RecordNodeInsertableData<T>, true, T, undefined>;
     recordAlpha<const Name extends TName, const T extends ImplicitAnnotatedAllowedTypes, const TCustomMetadata = unknown>(name: Name, allowedTypes: T, options?: NodeSchemaOptionsAlpha<TCustomMetadata>): RecordNodeCustomizableSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata>;
@@ -840,16 +837,18 @@ export class SchemaFactoryAlpha<out TScope extends string | undefined = string |
         readonly [x: string]: System_Unsafe.InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>;
     }, false, T, undefined>;
     static readonly required: {
-        <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha_2<TCustomMetadata>, "defaultProvider"> | undefined): FieldSchemaAlpha_2<FieldKind_2.Required, T, TCustomMetadata>;
-        <const T_1 extends ImplicitAnnotatedAllowedTypes, const TCustomMetadata_1 = unknown>(t: T_1, props?: Omit<FieldPropsAlpha_2<TCustomMetadata_1>, "defaultProvider"> | undefined): FieldSchemaAlpha_2<FieldKind_2.Required, UnannotateImplicitAllowedTypes_2<T_1>, TCustomMetadata_1>;
+        <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined): FieldSchemaAlpha<FieldKind.Required, T, TCustomMetadata>;
+        <const T_1 extends ImplicitAnnotatedAllowedTypes, const TCustomMetadata_1 = unknown>(t: T_1, props?: Omit<FieldPropsAlpha<TCustomMetadata_1>, "defaultProvider"> | undefined): FieldSchemaAlpha<FieldKind.Required, UnannotateImplicitAllowedTypes<T_1>, TCustomMetadata_1>;
     };
     readonly required: {
-        <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha_2<TCustomMetadata>, "defaultProvider"> | undefined): FieldSchemaAlpha_2<FieldKind_2.Required, T, TCustomMetadata>;
-        <const T_1 extends ImplicitAnnotatedAllowedTypes, const TCustomMetadata_1 = unknown>(t: T_1, props?: Omit<FieldPropsAlpha_2<TCustomMetadata_1>, "defaultProvider"> | undefined): FieldSchemaAlpha_2<FieldKind_2.Required, UnannotateImplicitAllowedTypes_2<T_1>, TCustomMetadata_1>;
+        <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined): FieldSchemaAlpha<FieldKind.Required, T, TCustomMetadata>;
+        <const T_1 extends ImplicitAnnotatedAllowedTypes, const TCustomMetadata_1 = unknown>(t: T_1, props?: Omit<FieldPropsAlpha<TCustomMetadata_1>, "defaultProvider"> | undefined): FieldSchemaAlpha<FieldKind.Required, UnannotateImplicitAllowedTypes<T_1>, TCustomMetadata_1>;
     };
-    static readonly requiredRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha_2<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe_2<FieldKind_2.Required, T, TCustomMetadata>;
-    readonly requiredRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha_2<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe_2<FieldKind_2.Required, T, TCustomMetadata>;
+    static readonly requiredRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Required, T, TCustomMetadata>;
+    readonly requiredRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Required, T, TCustomMetadata>;
     scopedFactory<const T extends TName, TNameInner extends number | string = string>(name: T): SchemaFactoryAlpha<ScopedSchemaName<TScope, T>, TNameInner>;
+    static staged: <const T extends LazyItem<TreeNodeSchema>>(t: T | AnnotatedAllowedType<T>) => AnnotatedAllowedType<T>;
+    staged: <const T extends LazyItem<TreeNodeSchema>>(t: T | AnnotatedAllowedType<T>) => AnnotatedAllowedType<T>;
 }
 
 // @alpha
@@ -877,6 +876,17 @@ export interface SchemaStatics {
     readonly string: LeafSchema<"string", string>;
 }
 
+// @alpha @sealed @system
+export interface SchemaStaticsAlpha {
+    staged: <const T extends LazyItem<TreeNodeSchema>>(t: T | AnnotatedAllowedType<T>) => AnnotatedAllowedType<T>;
+}
+
+// @alpha @sealed
+export class SchemaUpgrade {
+    // (undocumented)
+    protected _typeCheck: MakeNominal;
+}
+
 // @alpha @input
 export interface SchemaValidationFunction<Schema extends TSchema> {
     check(data: unknown): data is Static<Schema>;
@@ -986,7 +996,7 @@ export namespace System_TableSchema {
         props: InsertableTreeFieldFromImplicitField<UnannotateImplicitFieldSchema<TPropsSchema>>;
     }), true, {
         readonly props: TPropsSchema;
-        readonly id: FieldSchema_2<FieldKind_3.Identifier, LeafSchema_3<"string", string>, unknown>;
+        readonly id: FieldSchema_2<FieldKind_2.Identifier, LeafSchema_2<"string", string>, unknown>;
     }>;
     // @system
     export type CreateRowOptionsBase<TSchemaFactory extends SchemaFactoryAlpha = SchemaFactoryAlpha, TCell extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory<TSchemaFactory> & OptionsWithCellSchema<TCell>;
@@ -1000,8 +1010,8 @@ export namespace System_TableSchema {
         props: InsertableTreeFieldFromImplicitField<UnannotateImplicitFieldSchema<TPropsSchema>>;
     }), true, {
         readonly props: TPropsSchema;
-        readonly id: FieldSchema_2<FieldKind_3.Identifier, LeafSchema_3<"string", string>, unknown>;
-        readonly cells: FieldSchemaAlpha_3<FieldKind_3.Required, TreeNodeSchemaClass<ScopedSchemaName<ScopedSchemaName<TInputScope, "table">, "Row.cells">, NodeKind.Record, TreeRecordNode_2<TCellSchema> & WithType<ScopedSchemaName<ScopedSchemaName<TInputScope, "table">, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2<TCellSchema>, true, TCellSchema, undefined>, unknown>;
+        readonly id: FieldSchema_2<FieldKind_2.Identifier, LeafSchema_2<"string", string>, unknown>;
+        readonly cells: FieldSchemaAlpha_2<FieldKind_2.Required, TreeNodeSchemaClass<ScopedSchemaName<ScopedSchemaName<TInputScope, "table">, "Row.cells">, NodeKind.Record, TreeRecordNode_2<TCellSchema> & WithType<ScopedSchemaName<ScopedSchemaName<TInputScope, "table">, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2<TCellSchema>, true, TCellSchema, undefined>, unknown>;
     }>;
     // @system
     export function createTableSchema<const TInputScope extends string | undefined, const TCellSchema extends ImplicitAllowedTypes, const TColumnSchema extends ColumnSchemaBase<TInputScope, TCellSchema>, const TRowSchema extends RowSchemaBase<TInputScope, TCellSchema>>(inputSchemaFactory: SchemaFactoryAlpha<TInputScope>, _cellSchema: TCellSchema, columnSchema: TColumnSchema, rowSchema: TRowSchema): TreeNodeSchemaCore_2<ScopedSchemaName<ScopedSchemaName<TInputScope, "table">, "Table">, NodeKind.Object, true, {
@@ -1547,21 +1557,18 @@ const typeNameSymbol: unique symbol;
 export const typeSchemaSymbol: unique symbol;
 
 // @alpha @system
-export type UnannotateAllowedType<T extends AnnotatedAllowedType | LazyItem<TreeNodeSchema>> = T extends AnnotatedAllowedType<infer X> ? [X] : T;
-
-// @alpha @system
-export type UnannotateAllowedTypeOrLazyItem<T extends AnnotatedAllowedType | LazyItem<TreeNodeSchema>> = T extends AnnotatedAllowedType<infer X> ? X : T;
+export type UnannotateAllowedType<T extends AnnotatedAllowedType | LazyItem<TreeNodeSchema>> = T extends AnnotatedAllowedType<infer X> ? X : T;
 
 // @alpha @system
 export type UnannotateAllowedTypes<T extends AnnotatedAllowedTypes> = UnannotateAllowedTypesList<T["types"]>;
 
 // @alpha @system
 export type UnannotateAllowedTypesList<T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[]> = {
-    [I in keyof T]: UnannotateAllowedTypeOrLazyItem<T[I]>;
+    [I in keyof T]: UnannotateAllowedType<T[I]>;
 };
 
 // @alpha @system
-export type UnannotateImplicitAllowedTypes<T extends ImplicitAnnotatedAllowedTypes> = T extends AnnotatedAllowedTypes ? UnannotateAllowedTypes<T> : T extends AnnotatedAllowedType ? UnannotateAllowedType<T> : T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[] ? UnannotateAllowedTypesList<T> : T extends TreeNodeSchema ? T : never;
+export type UnannotateImplicitAllowedTypes<T extends ImplicitAnnotatedAllowedTypes> = T extends AnnotatedAllowedTypes ? UnannotateAllowedTypes<T> : T extends AnnotatedAllowedType ? UnannotateAllowedTypesList<[T]> : T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[] ? UnannotateAllowedTypesList<T> : T extends TreeNodeSchema ? T : ImplicitAllowedTypes;
 
 // @alpha @system
 export type UnannotateImplicitFieldSchema<T extends ImplicitAnnotatedFieldSchema> = T extends ImplicitAnnotatedAllowedTypes ? UnannotateImplicitAllowedTypes<T> : T;

package/dist/alpha.d.ts

@@ -171,6 +171,8 @@ export {
 	RunTransactionParams, 
 	SchemaFactoryAlpha, 
 	SchemaFactoryObjectOptions, 
+	SchemaStaticsAlpha, 
+	SchemaUpgrade, 
 	SchemaValidationFunction, 
 	SharedTreeFormatOptions, 
 	SharedTreeFormatVersion, 
@@ -210,7 +212,6 @@ export {
 	TreeViewAlpha, 
 	TreeViewConfigurationAlpha, 
 	UnannotateAllowedType, 
-	UnannotateAllowedTypeOrLazyItem, 
 	UnannotateAllowedTypes, 
 	UnannotateAllowedTypesList, 
 	UnannotateImplicitAllowedTypes, 

package/dist/core/tree/visitDelta.d.ts

@@ -2,12 +2,12 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import type { RevisionTag } from "../index.js";
 import type { FieldKey } from "../schema-stored/index.js";
 import { type ITreeCursorSynchronous } from "./cursor.js";
 import type * as Delta from "./delta.js";
 import type { DetachedFieldIndex } from "./detachedFieldIndex.js";
 import type { NodeIndex, PlaceIndex, Range } from "./pathTree.js";
+import type { RevisionTag } from "../rebase/index.js";
 /**
  * Implementation notes:
  *

package/dist/core/tree/visitDelta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"visitDelta.d.ts","sourceRoot":"","sources":["../../../src/core/tree/visitDelta.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAa,MAAM,aAAa,CAAC;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE1D,OAAO,EAAkB,KAAK,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAC;AAEzC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CACzB,KAAK,EAAE,KAAK,CAAC,IAAI,EACjB,OAAO,EAAE,YAAY,EACrB,kBAAkB,EAAE,kBAAkB,EACtC,cAAc,EAAE,WAAW,GAAG,SAAS,GACrC,IAAI,CA0DN;AA0GD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC5B;;;;;;;;OAQG;IACH,IAAI,IAAI,IAAI,CAAC;IACb;;;;;OAKG;IACH,MAAM,CAAC,OAAO,EAAE,SAAS,sBAAsB,EAAE,EAAE,WAAW,EAAE,QAAQ,GAAG,IAAI,CAAC;IAChF;;;;;OAKG;IACH,OAAO,CAAC,aAAa,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACtD;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,GAAG,IAAI,CAAC;IACvE;;;;;;;;;OASG;IACH,MAAM,CACL,MAAM,EAAE,KAAK,EACb,WAAW,EAAE,QAAQ,EACrB,EAAE,EAAE,KAAK,CAAC,cAAc,EACxB,UAAU,EAAE,OAAO,GACjB,IAAI,CAAC;IAER;;;;;;;OAOG;IACH,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IAElC;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IAEjC;;;;;;;OAOG;IACH,UAAU,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IAEhC;;;;;;;OAOG;IACH,SAAS,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;CAC/B"}
+{"version":3,"file":"visitDelta.d.ts","sourceRoot":"","sources":["../../../src/core/tree/visitDelta.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE1D,OAAO,EAAkB,KAAK,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAC;AAEzC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CACzB,KAAK,EAAE,KAAK,CAAC,IAAI,EACjB,OAAO,EAAE,YAAY,EACrB,kBAAkB,EAAE,kBAAkB,EACtC,cAAc,EAAE,WAAW,GAAG,SAAS,GACrC,IAAI,CA0DN;AA0GD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC5B;;;;;;;;OAQG;IACH,IAAI,IAAI,IAAI,CAAC;IACb;;;;;OAKG;IACH,MAAM,CAAC,OAAO,EAAE,SAAS,sBAAsB,EAAE,EAAE,WAAW,EAAE,QAAQ,GAAG,IAAI,CAAC;IAChF;;;;;OAKG;IACH,OAAO,CAAC,aAAa,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACtD;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,GAAG,IAAI,CAAC;IACvE;;;;;;;;;OASG;IACH,MAAM,CACL,MAAM,EAAE,KAAK,EACb,WAAW,EAAE,QAAQ,EACrB,EAAE,EAAE,KAAK,CAAC,cAAc,EACxB,UAAU,EAAE,OAAO,GACjB,IAAI,CAAC;IAER;;;;;;;OAOG;IACH,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IAElC;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IAEjC;;;;;;;OAOG;IACH,UAAU,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IAEhC;;;;;;;OAOG;IACH,SAAS,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;CAC/B"}

package/dist/core/tree/visitDelta.js.map

@@ -1 +1 @@
-{"version":3,"file":"visitDelta.js","sourceRoot":"","sources":["../../../src/core/tree/visitDelta.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,kEAA6D;AAE7D,kDAA0F;AAI1F,2CAA0E;AAE1E,iDAAyE;AAKzE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;;;;GAUG;AACH,SAAgB,UAAU,CACzB,KAAiB,EACjB,OAAqB,EACrB,kBAAsC,EACtC,cAAuC;IAEvC,MAAM,eAAe,GAAsC,IAAI,GAAG,EAAE,CAAC;IACrE,MAAM,eAAe,GAAsC,IAAI,GAAG,EAAE,CAAC;IACrE,MAAM,aAAa,GAA+B,EAAE,CAAC;IACrD,MAAM,gBAAgB,GAAoC,EAAE,CAAC;IAC7D,MAAM,UAAU,GAAoD,IAAI,GAAG,EAAE,CAAC;IAC9E,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;QAC7D,MAAM,WAAW,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;QAChD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,cAAc,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;YAClD,MAAM,WAAW,GAAG,KAAK,GAAG,CAAC,CAAC;YAC9B,IAAA,yBAAc,EAAC,UAAU,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;QAChE,CAAC;IACF,CAAC,CAAC,CAAC;IACH,MAAM,YAAY,GAAe;QAChC,IAAI,EAAE,UAAU;QAChB,cAAc;QACd,UAAU;QACV,kBAAkB;QAClB,eAAe;QACf,eAAe;QACf,aAAa;QACb,gBAAgB;KAChB,CAAC;IACF,aAAa,CAAC,KAAK,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;IAClD,aAAa,CAAC,KAAK,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;IACnD,aAAa,CAAC,KAAK,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC1C,eAAe,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;IACrD,sBAAsB,CAAC,OAAO,EAAE,eAAe,EAAE,YAAY,CAAC,CAAC;IAC/D,aAAa,CACZ,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,OAAO,EACP,UAAU,EACV,cAAc,CACd,CAAC;IACF,MAAM,YAAY,GAAe;QAChC,IAAI,EAAE,UAAU;QAChB,cAAc;QACd,UAAU;QACV,kBAAkB;QAClB,eAAe;QACf,eAAe;QACf,aAAa;QACb,gBAAgB;KAChB,CAAC;IACF,eAAe,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;IACrD,sBAAsB,CAAC,OAAO,EAAE,eAAe,EAAE,YAAY,CAAC,CAAC;IAC/D,eAAe,CAAC,KAAK,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAC7C,KAAK,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,gBAAgB,EAAE,CAAC;QAC9C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;YACnC,MAAM,QAAQ,GAAG,IAAA,6BAAc,EAAC,EAAE,EAAE,CAAC,CAAC,CAAC;YACvC,MAAM,IAAI,GAAG,kBAAkB,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YACnD,MAAM,KAAK,GAAG,kBAAkB,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;YAClD,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YAC1B,kBAAkB,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QAC1C,CAAC;IACF,CAAC;AACF,CAAC;AA/DD,gCA+DC;AAED;;;;;;;GAOG;AACH,SAAS,sBAAsB,CAC9B,OAAqB,EACrB,KAAwC,EACxC,MAAkB;IAElB,OAAO,KAAK,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC,IAAI,KAAK,EAAE,CAAC;YAC3C,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACnB,MAAM,KAAK,GAAG,MAAM,CAAC,kBAAkB,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;YACzD,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;YAC1B,wGAAwG;YACxG,SAAS,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;YAC7C,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;IACF,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAS,aAAa,CACrB,aAAkD,EAClD,WAAuC,EACvC,kBAAsC,EACtC,OAAqB,EACrB,UAA2D,EAC3D,QAAsB;IAGtB,IAAI,SAAS,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE;QACjE,MAAM,QAAQ,GAAyB,EAAE,CAAC;QAC1C,oHAAoH;QACpH,sHAAsH;QACtH,qHAAqH;QACrH,2FAA2F;QAC3F,kDAAkD;QAClD,IAAI,CAAC,IAAA,sCAAuB,EAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC;YAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;gBACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAA,6BAAc,EAAC,KAAK,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,IAAA,6BAAc,EAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;YACrF,CAAC;QACF,CAAC;QACD,OAAO,QAAQ,CAAC;IACjB,CAAC,CAAC,CAAC;IACH,OAAO,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAyB,EAAE,CAAC;QACzC,MAAM,SAAS,GAAG,SAAS,CAAC,MAAM,CAAC;QACnC,KAAK,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,SAAS,EAAE,CAAC;YAC1C,IAAI,SAAS,GAAG,kBAAkB,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;YACtD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC7B,MAAM,IAAI,GAAG,IAAA,8BAAmB,EAAC,UAAU,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;gBACvE,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;oBACxB,UAAU,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,kBAAkB,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;oBACjE,SAAS,GAAG,kBAAkB,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;gBAChD,CAAC;YACF,CAAC;YACD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC7B,qCAAqC;gBACrC,mEAAmE;gBACnE,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;gBAC/B,SAAS;YACV,CAAC;YACD,IAAI,SAAS,GAAG,kBAAkB,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;YACtD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC7B,6CAA6C;gBAC7C,mEAAmE;gBACnE,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;gBAC/B,SAAS;YACV,CAAC;YACD,SAAS,GAAG,kBAAkB,CAAC,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;YAC5D,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAC1C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC1B,WAAW,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;gBAC9B,WAAW,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;YACpC,CAAC;YACD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;YAC1D,MAAM,QAAQ,GAAG,kBAAkB,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;YAC1D,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;YAC7B,OAAO,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;YAC7D,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;YAC5B,kBAAkB,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QACvC,CAAC;QACD,IAAA,iBAAM,EAAC,OAAO,CAAC,MAAM,GAAG,SAAS,EAAE,KAAK,CAAC,wCAAwC,CAAC,CAAC;QACnF,SAAS,GAAG,OAAO,CAAC;IACrB,CAAC;AACF,CAAC;AA6ID,SAAS,eAAe,CACvB,MAAkC,EAClC,OAAqB,EACrB,MAAkB;IAElB,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAC1B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,EAAE,CAAC;YACnC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;YACxB,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;YACpC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QACxB,CAAC;IACF,CAAC;AACF,CAAC;AAED,SAAS,SAAS,CACjB,KAAa,EACb,MAAkC,EAClC,OAAqB,EACrB,MAAkB;IAElB,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACzB,eAAe,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;AACF,CAAC;AAED;;;;GAIG;AACH,SAAS,UAAU,CAClB,YAAgC,EAChC,OAAqB,EACrB,MAAkB;IAElB,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QACjC,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC/B,IAAA,iBAAM,EACL,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EACtD,KAAK,CAAC,gDAAgD,CACtD,CAAC;YACF,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAChD,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC/B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;gBACxC,MAAM,EAAE,GAAG,IAAA,6BAAc,EAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;gBAC1C,MAAM,IAAI,GAAG,MAAM,CAAC,kBAAkB,CAAC,WAAW,CAAC,EAAE,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC;gBAC9E,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;oBAC/B,MAAM,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;gBAC/C,CAAC;gBACD,MAAM,KAAK,GAAG,MAAM,CAAC,kBAAkB,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;gBACzD,OAAO,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC;YACxF,CAAC;QACF,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC5D,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC;QACrB,CAAC;IACF,CAAC;AACF,CAAC;AAED,SAAS,UAAU,CAClB,EAAwB,EACxB,KAAwC,EACxC,kBAAsC,EACtC,cAAuC,EACvC,OAAqB;IAErB,KAAK,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QACzC,MAAM,WAAW,GAAG,IAAA,6BAAc,EAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QAC1C,IAAI,IAAI,GAAG,kBAAkB,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;QACvD,IAAA,iBAAM,EAAC,IAAI,KAAK,SAAS,EAAE,KAAK,CAAC,8CAA8C,CAAC,CAAC;QACjF,IAAI,GAAG,kBAAkB,CAAC,WAAW,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;QACnE,MAAM,KAAK,GAAG,kBAAkB,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAClD,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC;IAC/B,CAAC;AACF,CAAC;AAED,SAAS,aAAa,CACrB,MAAsD,EACtD,MAAkB,EAClB,OAAqB;IAErB,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAC1B,KAAK,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,MAAM,EAAE,CAAC;YACpC,UAAU,CACT,EAAE,EACF,oBAAoB,CAAC,KAAK,CAAC,EAC3B,MAAM,CAAC,kBAAkB,EACzB,MAAM,CAAC,cAAc,EACrB,OAAO,CACP,CAAC;QACH,CAAC;IACF,CAAC;AACF,CAAC;AAED,SAAS,aAAa,CACrB,MAAwD,EACxD,MAAkB,EAClB,OAAqB;IAErB,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAC1B,KAAK,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;YACrC,IAAI,IAAI,GAAG,MAAM,CAAC,kBAAkB,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;YACrD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACxB,MAAM,IAAI,GAAG,IAAA,8BAAmB,EAAC,MAAM,CAAC,UAAU,EAAE,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;gBACxE,IAAA,iBAAM,EAAC,IAAI,KAAK,SAAS,EAAE,KAAK,CAAC,8BAA8B,CAAC,CAAC;gBACjE,UAAU,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;gBAClF,IAAI,GAAG,MAAM,CAAC,kBAAkB,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;YAC/C,CAAC;YACD,oFAAoF;YACpF,MAAM,CAAC,kBAAkB,CAAC,oBAAoB,CAAC,EAAE,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC;YAC1E,MAAM,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACzC,MAAM,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC1C,CAAC;IACF,CAAC;AACF,CAAC;AAED,SAAS,aAAa,CACrB,MAAuD,EACvD,MAAkB;IAElB,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC;IACtC,CAAC;AACF,CAAC;AAED,SAAS,eAAe,CACvB,QAA8D,EAC9D,MAAkB;IAElB,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,CAAC,gBAAgB,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC;IAC3C,CAAC;AACF,CAAC;AAED;;;GAGG;AACH,SAAS,UAAU,CAClB,YAAgC,EAChC,OAAqB,EACrB,MAAkB;IAElB,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QACjC,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC/B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;gBACxC,MAAM,cAAc,GAAG,IAAA,6BAAc,EAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;gBACtD,IAAI,UAAU,GAAG,MAAM,CAAC,kBAAkB,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC;gBACvE,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;oBAC9B,MAAM,IAAI,GAAG,IAAA,8BAAmB,EAC/B,MAAM,CAAC,UAAU,EACjB,cAAc,CAAC,KAAK,EACpB,cAAc,CAAC,KAAK,CACpB,CAAC;oBACF,IAAA,iBAAM,EAAC,IAAI,KAAK,SAAS,EAAE,KAAK,CAAC,8BAA8B,CAAC,CAAC;oBACjE,UAAU,CACT,cAAc,EACd,CAAC,IAAI,CAAC,EACN,MAAM,CAAC,kBAAkB,EACzB,MAAM,CAAC,cAAc,EACrB,OAAO,CACP,CAAC;oBACF,UAAU,GAAG,MAAM,CAAC,kBAAkB,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;gBACjE,CAAC;gBACD,MAAM,WAAW,GAAG,MAAM,CAAC,kBAAkB,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;gBACrE,MAAM,WAAW,GAAG,KAAK,GAAG,CAAC,CAAC;gBAC9B,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,EAAE,WAAW,CAAC,CAAC;gBAC5C,MAAM,CAAC,kBAAkB,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC;gBACtD,MAAM,MAAM,GAAG,MAAM,CAAC,eAAe,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;gBACtD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBAC1B,MAAM,CAAC,eAAe,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;oBAC1C,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;gBACjD,CAAC;YACF,CAAC;QACF,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC5D,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAChD,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC5D,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC;QACrB,CAAC;IACF,CAAC;AACF,CAAC;AAED;;;;GAIG;AACH,SAAS,oBAAoB,CAAC,KAAgB;IAC7C,OAAO,IAAA,0BAAc,EAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AACxD,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils/internal\";\n\nimport { type NestedMap, setInNestedMap, tryGetFromNestedMap } from \"../../util/index.js\";\nimport type { RevisionTag, TreeChunk } from \"../index.js\";\nimport type { FieldKey } from \"../schema-stored/index.js\";\n\nimport { mapCursorField, type ITreeCursorSynchronous } from \"./cursor.js\";\nimport type * as Delta from \"./delta.js\";\nimport { areDetachedNodeIdsEqual, offsetDetachId } from \"./deltaUtil.js\";\nimport type { DetachedFieldIndex } from \"./detachedFieldIndex.js\";\nimport type { ForestRootId, Major, Minor } from \"./detachedFieldIndexTypes.js\";\nimport type { NodeIndex, PlaceIndex, Range } from \"./pathTree.js\";\n\n/**\n * Implementation notes:\n *\n * The visit is organized into four phases:\n * 1. a detach pass\n * 2. root transfers\n * 3. an attach pass\n * 4. root destructions\n *\n * The core idea is that before content can be attached, it must first exist and be in a detached field.\n *\n * While the detach pass ensures that nodes to be attached are in a detached state, it does not guarantee that they\n * reside in the correct detached field. That is the responsibility of the root transfers phase.\n *\n * The attach phase carries out attaches.\n *\n * After the attach phase, roots destruction is carried out.\n * This needs to happen last to allow modifications to detached roots to be applied before they are destroyed.\n *\n * The details of the delta visit algorithm can impact how/when events are emitted by the objects that own the visitors.\n * For example, as of 2024-03-27, the subtreeChanged event of an AnchorNode is emitted when exiting a node during a\n * delta visit, and thus the two-pass nature of the algorithm means the event fires twice for any given change.\n */\n\n/**\n * Crawls the given `delta`, calling `visitor`'s callback for each change encountered.\n * Each successive call to the visitor callbacks assumes that the change described by earlier calls have been applied\n * to the document tree. For example, for a change that removes the first and third node of a field, the visitor calls\n * will first call detach with a range from indices 0 to 1 then call detach with a range from indices 1 to 2.\n *\n * @param delta - The delta to be crawled.\n * @param visitor - The object to notify of the changes encountered.\n * @param detachedFieldIndex - Index responsible for keeping track of the existing detached fields.\n * @param latestRevision - The latest revision tag associated with this delta.\n */\nexport function visitDelta(\n\tdelta: Delta.Root,\n\tvisitor: DeltaVisitor,\n\tdetachedFieldIndex: DetachedFieldIndex,\n\tlatestRevision: RevisionTag | undefined,\n): void {\n\tconst detachPassRoots: Map<ForestRootId, Delta.FieldMap> = new Map();\n\tconst attachPassRoots: Map<ForestRootId, Delta.FieldMap> = new Map();\n\tconst rootTransfers: Delta.DetachedNodeRename[] = [];\n\tconst rootDestructions: Delta.DetachedNodeDestruction[] = [];\n\tconst refreshers: NestedMap<Major, Minor, ITreeCursorSynchronous> = new Map();\n\tdelta.refreshers?.forEach(({ id: { major, minor }, trees }) => {\n\t\tconst treeCursors = nodeCursorsFromChunk(trees);\n\t\tfor (let i = 0; i < trees.topLevelLength; i += 1) {\n\t\t\tconst offsettedId = minor + i;\n\t\t\tsetInNestedMap(refreshers, major, offsettedId, treeCursors[i]);\n\t\t}\n\t});\n\tconst detachConfig: PassConfig = {\n\t\tfunc: detachPass,\n\t\tlatestRevision,\n\t\trefreshers,\n\t\tdetachedFieldIndex,\n\t\tdetachPassRoots,\n\t\tattachPassRoots,\n\t\trootTransfers,\n\t\trootDestructions,\n\t};\n\tprocessBuilds(delta.build, detachConfig, visitor);\n\tprocessGlobal(delta.global, detachConfig, visitor);\n\tprocessRename(delta.rename, detachConfig);\n\tvisitFieldMarks(delta.fields, visitor, detachConfig);\n\tfixedPointVisitOfRoots(visitor, detachPassRoots, detachConfig);\n\ttransferRoots(\n\t\trootTransfers,\n\t\tattachPassRoots,\n\t\tdetachedFieldIndex,\n\t\tvisitor,\n\t\trefreshers,\n\t\tlatestRevision,\n\t);\n\tconst attachConfig: PassConfig = {\n\t\tfunc: attachPass,\n\t\tlatestRevision,\n\t\trefreshers,\n\t\tdetachedFieldIndex,\n\t\tdetachPassRoots,\n\t\tattachPassRoots,\n\t\trootTransfers,\n\t\trootDestructions,\n\t};\n\tvisitFieldMarks(delta.fields, visitor, attachConfig);\n\tfixedPointVisitOfRoots(visitor, attachPassRoots, attachConfig);\n\tcollectDestroys(delta.destroy, attachConfig);\n\tfor (const { id, count } of rootDestructions) {\n\t\tfor (let i = 0; i < count; i += 1) {\n\t\t\tconst offsetId = offsetDetachId(id, i);\n\t\t\tconst root = detachedFieldIndex.getEntry(offsetId);\n\t\t\tconst field = detachedFieldIndex.toFieldKey(root);\n\t\t\tvisitor.destroy(field, 1);\n\t\t\tdetachedFieldIndex.deleteEntry(offsetId);\n\t\t}\n\t}\n}\n\n/**\n * Visits all nodes in `roots` until none are left.\n * This function tolerates entries being added to and removed from `roots` as part of visits.\n * @param visitor - The visitor to visit the roots with.\n * @param roots - The initial set of roots to visit.\n * Individual entries are removed prior to being visited.\n * @param config - The configuration to use for visits.\n */\nfunction fixedPointVisitOfRoots(\n\tvisitor: DeltaVisitor,\n\troots: Map<ForestRootId, Delta.FieldMap>,\n\tconfig: PassConfig,\n): void {\n\twhile (roots.size > 0) {\n\t\tfor (const [root, modifications] of roots) {\n\t\t\troots.delete(root);\n\t\t\tconst field = config.detachedFieldIndex.toFieldKey(root);\n\t\t\tvisitor.enterField(field);\n\t\t\t// Note: each visit may lead to `roots` being populated with new entries or having some entries removed.\n\t\t\tvisitNode(0, modifications, visitor, config);\n\t\t\tvisitor.exitField(field);\n\t\t}\n\t}\n}\n\n/**\n * Transfers roots from one detached field to another.\n * This occurs in the following circumstances:\n * - A changeset moves then removes a node\n * - A changeset restores then moves a node\n * - A changeset restores then removes a node\n * TODO#5481: update the DetachedFieldIndex instead of moving the nodes around.\n *\n * @param rootTransfers - The transfers to perform.\n * @param mapToUpdate - A map to update based on the transfers being performed.\n * @param detachedFieldIndex - The index to update based on the transfers being performed.\n * @param visitor - The visitor to inform of the transfers being performed.\n */\nfunction transferRoots(\n\trootTransfers: readonly Delta.DetachedNodeRename[],\n\tmapToUpdate: Map<ForestRootId, unknown>,\n\tdetachedFieldIndex: DetachedFieldIndex,\n\tvisitor: DeltaVisitor,\n\trefreshers: NestedMap<Major, Minor, ITreeCursorSynchronous>,\n\trevision?: RevisionTag,\n): void {\n\ttype AtomizedNodeRename = Omit<Delta.DetachedNodeRename, \"count\">;\n\tlet nextBatch = rootTransfers.flatMap(({ oldId, newId, count }) => {\n\t\tconst atomized: AtomizedNodeRename[] = [];\n\t\t// It's possible for a detached node to be revived transiently such that it ends up back in the same detached field.\n\t\t// Making such a transfer wouldn't just be inefficient, it would lead us to mistakenly think we have moved all content\n\t\t// out of the source detached field, and would lead us to delete the tree index entry for that source detached field.\n\t\t// This would effectively result in the tree index missing an entry for the detached field.\n\t\t// This if statement prevents that from happening.\n\t\tif (!areDetachedNodeIdsEqual(oldId, newId)) {\n\t\t\tfor (let i = 0; i < count; i += 1) {\n\t\t\t\tatomized.push({ oldId: offsetDetachId(oldId, i), newId: offsetDetachId(newId, i) });\n\t\t\t}\n\t\t}\n\t\treturn atomized;\n\t});\n\twhile (nextBatch.length > 0) {\n\t\tconst delayed: AtomizedNodeRename[] = [];\n\t\tconst priorSize = nextBatch.length;\n\t\tfor (const { oldId, newId } of nextBatch) {\n\t\t\tlet oldRootId = detachedFieldIndex.tryGetEntry(oldId);\n\t\t\tif (oldRootId === undefined) {\n\t\t\t\tconst tree = tryGetFromNestedMap(refreshers, oldId.major, oldId.minor);\n\t\t\t\tif (tree !== undefined) {\n\t\t\t\t\tbuildTrees(oldId, [tree], detachedFieldIndex, revision, visitor);\n\t\t\t\t\toldRootId = detachedFieldIndex.getEntry(oldId);\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (oldRootId === undefined) {\n\t\t\t\t// The source field is not populated.\n\t\t\t\t// This can happen when another rename needs to be performed first.\n\t\t\t\tdelayed.push({ oldId, newId });\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tlet newRootId = detachedFieldIndex.tryGetEntry(newId);\n\t\t\tif (newRootId !== undefined) {\n\t\t\t\t// The destination field is already occupied.\n\t\t\t\t// This can happen when another rename needs to be performed first.\n\t\t\t\tdelayed.push({ oldId, newId });\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tnewRootId = detachedFieldIndex.createEntry(newId, revision);\n\t\t\tconst fields = mapToUpdate.get(oldRootId);\n\t\t\tif (fields !== undefined) {\n\t\t\t\tmapToUpdate.delete(oldRootId);\n\t\t\t\tmapToUpdate.set(newRootId, fields);\n\t\t\t}\n\t\t\tconst oldField = detachedFieldIndex.toFieldKey(oldRootId);\n\t\t\tconst newField = detachedFieldIndex.toFieldKey(newRootId);\n\t\t\tvisitor.enterField(oldField);\n\t\t\tvisitor.detach({ start: 0, end: 1 }, newField, newId, false);\n\t\t\tvisitor.exitField(oldField);\n\t\t\tdetachedFieldIndex.deleteEntry(oldId);\n\t\t}\n\t\tassert(delayed.length < priorSize, 0x7cf /* transferRoots should make progress */);\n\t\tnextBatch = delayed;\n\t}\n}\n\n/**\n * Visitor for changes in a delta.\n * Must be freed after use.\n */\nexport interface DeltaVisitor {\n\t/**\n\t * Frees/releases the visitor.\n\t *\n\t * Must be called once the visitor finished traversing the delta for a couple of reasons:\n\t *\n\t * 1. Some visitors, such as those from forests, are put into a special mode while they have a visitor, forbidding some actions (like making more visitors).\n\t *\n\t * 2. Some visitors, such as those from an anchorSet, defer some events for batching purposes until the visitor is freed.\n\t */\n\tfree(): void;\n\t/**\n\t * Creates nodes for the given content in a new detached field.\n\t * @param content - The content to create.\n\t * @param destination - The key for a new detached field.\n\t * A field with this key must not already exist.\n\t */\n\tcreate(content: readonly ITreeCursorSynchronous[], destination: FieldKey): void;\n\t/**\n\t * Recursively destroys the given detached field and all of the nodes within it.\n\t * @param detachedField - The key for the detached field to destroy.\n\t * @param count - The number of nodes being destroyed.\n\t * Expected to match the number of nodes in the detached field being destroyed.\n\t */\n\tdestroy(detachedField: FieldKey, count: number): void;\n\t/**\n\t * Transfers all the nodes from a detached field to the current field.\n\t * @param source - The detached field to transfer the nodes from.\n\t * @param count - The number of nodes being attached.\n\t * Expected to match the number of nodes in the source detached field.\n\t * @param destination - The index at which to attach the nodes.\n\t */\n\tattach(source: FieldKey, count: number, destination: PlaceIndex): void;\n\t/**\n\t * Transfers a range of nodes from the current field to a new detached field.\n\t * @param source - The bounds of the range of nodes to detach.\n\t * @param destination - The key for a new detached field.\n\t * A field with this key must not already exist.\n\t * @param id - The ID assigned to the first detached node as a result of the detach. The other nodes in the detached range are assigned subsequent IDs.\n\t * @param isReplaced - Whether the detached content will be replaced by a later attach.\n\t * This is not guaranteed to be true in all cases where it could be true,\n\t * but it is guaranteed to be true in all cases where a later attach is needed to keep the data compliant with the schema.\n\t */\n\tdetach(\n\t\tsource: Range,\n\t\tdestination: FieldKey,\n\t\tid: Delta.DetachedNodeId,\n\t\tisReplaced: boolean,\n\t): void;\n\n\t/**\n\t * Tells the visitor that it should update its \"current location\" to be the Node at the specified index\n\t * within the Field that is the current \"current location\".\n\t * Future calls to methods of {@link DeltaVisitor} will assume that's the location where their effects are happening.\n\t * @param index - The index (within the Field) of the node that should become the new \"current location\".\n\t *\n\t * @remarks This should only be called when the \"current location\" is a Field.\n\t */\n\tenterNode(index: NodeIndex): void;\n\n\t/**\n\t * Tells the visitor that it should update its \"current location\" to be the Field which contains the Node\n\t * that is the current \"current location\".\n\t * Future calls to methods of {@link DeltaVisitor} will assume that's the location where their effects are happening.\n\t * @param index - The index (within its Field) of the node that is being exited.\n\t *\n\t * @remarks This should only be called when the \"current location\" is a Node.\n\t */\n\texitNode(index: NodeIndex): void;\n\n\t/**\n\t * Tells the visitor that it should update its \"current location\" to be the Field with the specified key,\n\t * within the Node that is the current \"current location\".\n\t * Future calls to methods of {@link DeltaVisitor} will assume that's the location where their effects are happening.\n\t * @param key - The key of the field that should become the new \"current location\".\n\t *\n\t * @remarks This should only be called when the \"current location\" is a Node.\n\t */\n\tenterField(key: FieldKey): void;\n\n\t/**\n\t * Tells the visitor that it should update its \"current location\" to be the Node which contains the Field\n\t * that is the current \"current location\".\n\t * Future calls to methods of {@link DeltaVisitor} will assume that's the location where their effects are happening.\n\t * @param key - The key of the field that is being exited.\n\t *\n\t * @remarks This should only be called when the \"current location\" is a Field.\n\t */\n\texitField(key: FieldKey): void;\n}\n\ninterface PassConfig {\n\treadonly func: Pass;\n\n\t/**\n\t * The latest revision tag associated with the given delta. This is used to keep track\n\t * of when repair data should be garbage collected.\n\t */\n\treadonly latestRevision: RevisionTag | undefined;\n\n\treadonly detachedFieldIndex: DetachedFieldIndex;\n\t/**\n\t * A mapping between forest root id and trees that represent refresher data. Each entry is only\n\t * created in the forest once needed.\n\t */\n\treadonly refreshers: NestedMap<Major, Minor, ITreeCursorSynchronous>;\n\t/**\n\t * Nested changes on roots that need to be visited as part of the detach pass.\n\t * Each entry is removed when its associated changes are visited.\n\t */\n\treadonly detachPassRoots: Map<ForestRootId, Delta.FieldMap>;\n\t/**\n\t * Nested changes on roots that need to be visited as part of the attach pass.\n\t * Each entry is removed when its associated changes are visited.\n\t * Some of these roots will attached during the attach pass, in which case the nested changes are visited after\n\t * the node is attached.\n\t * Some of these nodes will never be attached, in which case we visit them in their detached fields at the end of\n\t * the attach pass. Note that such a visit might lead to more nodes being attached, including nodes were visited as\n\t * roots.\n\t */\n\treadonly attachPassRoots: Map<ForestRootId, Delta.FieldMap>;\n\t/**\n\t * Represents transfers of roots from one detached field to another.\n\t */\n\treadonly rootTransfers: Delta.DetachedNodeRename[];\n\t/**\n\t * Represents roots that need to be destroyed.\n\t * Collected as part of the detach pass.\n\t * Carried out at the end of the attach pass.\n\t */\n\treadonly rootDestructions: Delta.DetachedNodeDestruction[];\n}\n\ntype Pass = (delta: Delta.FieldChanges, visitor: DeltaVisitor, config: PassConfig) => void;\n\nfunction visitFieldMarks(\n\tfields: Delta.FieldMap | undefined,\n\tvisitor: DeltaVisitor,\n\tconfig: PassConfig,\n): void {\n\tif (fields !== undefined) {\n\t\tfor (const [key, field] of fields) {\n\t\t\tvisitor.enterField(key);\n\t\t\tconfig.func(field, visitor, config);\n\t\t\tvisitor.exitField(key);\n\t\t}\n\t}\n}\n\nfunction visitNode(\n\tindex: number,\n\tfields: Delta.FieldMap | undefined,\n\tvisitor: DeltaVisitor,\n\tconfig: PassConfig,\n): void {\n\tif (fields !== undefined) {\n\t\tvisitor.enterNode(index);\n\t\tvisitFieldMarks(fields, visitor, config);\n\t\tvisitor.exitNode(index);\n\t}\n}\n\n/**\n * Performs the following:\n * - Collects all roots that may need an attach pass\n * - Executes detaches (bottom-up)\n */\nfunction detachPass(\n\tfieldChanges: Delta.FieldChanges,\n\tvisitor: DeltaVisitor,\n\tconfig: PassConfig,\n): void {\n\tlet index = 0;\n\tfor (const mark of fieldChanges) {\n\t\tif (mark.fields !== undefined) {\n\t\t\tassert(\n\t\t\t\tmark.attach === undefined || mark.detach !== undefined,\n\t\t\t\t0x7d0 /* Invalid nested changes on an additive mark */,\n\t\t\t);\n\t\t\tvisitNode(index, mark.fields, visitor, config);\n\t\t}\n\t\tif (mark.detach !== undefined) {\n\t\t\tfor (let i = 0; i < mark.count; i += 1) {\n\t\t\t\tconst id = offsetDetachId(mark.detach, i);\n\t\t\t\tconst root = config.detachedFieldIndex.createEntry(id, config.latestRevision);\n\t\t\t\tif (mark.fields !== undefined) {\n\t\t\t\t\tconfig.attachPassRoots.set(root, mark.fields);\n\t\t\t\t}\n\t\t\t\tconst field = config.detachedFieldIndex.toFieldKey(root);\n\t\t\t\tvisitor.detach({ start: index, end: index + 1 }, field, id, mark.attach !== undefined);\n\t\t\t}\n\t\t}\n\t\tif (mark.detach === undefined && mark.attach === undefined) {\n\t\t\tindex += mark.count;\n\t\t}\n\t}\n}\n\nfunction buildTrees(\n\tid: Delta.DetachedNodeId,\n\ttrees: readonly ITreeCursorSynchronous[],\n\tdetachedFieldIndex: DetachedFieldIndex,\n\tlatestRevision: RevisionTag | undefined,\n\tvisitor: DeltaVisitor,\n): void {\n\tfor (const [i, tree] of trees.entries()) {\n\t\tconst offsettedId = offsetDetachId(id, i);\n\t\tlet root = detachedFieldIndex.tryGetEntry(offsettedId);\n\t\tassert(root === undefined, 0x929 /* Unable to build tree that already exists */);\n\t\troot = detachedFieldIndex.createEntry(offsettedId, latestRevision);\n\t\tconst field = detachedFieldIndex.toFieldKey(root);\n\t\tvisitor.create([tree], field);\n\t}\n}\n\nfunction processBuilds(\n\tbuilds: readonly Delta.DetachedNodeBuild[] | undefined,\n\tconfig: PassConfig,\n\tvisitor: DeltaVisitor,\n): void {\n\tif (builds !== undefined) {\n\t\tfor (const { id, trees } of builds) {\n\t\t\tbuildTrees(\n\t\t\t\tid,\n\t\t\t\tnodeCursorsFromChunk(trees),\n\t\t\t\tconfig.detachedFieldIndex,\n\t\t\t\tconfig.latestRevision,\n\t\t\t\tvisitor,\n\t\t\t);\n\t\t}\n\t}\n}\n\nfunction processGlobal(\n\tglobal: readonly Delta.DetachedNodeChanges[] | undefined,\n\tconfig: PassConfig,\n\tvisitor: DeltaVisitor,\n): void {\n\tif (global !== undefined) {\n\t\tfor (const { id, fields } of global) {\n\t\t\tlet root = config.detachedFieldIndex.tryGetEntry(id);\n\t\t\tif (root === undefined) {\n\t\t\t\tconst tree = tryGetFromNestedMap(config.refreshers, id.major, id.minor);\n\t\t\t\tassert(tree !== undefined, 0x928 /* refresher data not found */);\n\t\t\t\tbuildTrees(id, [tree], config.detachedFieldIndex, config.latestRevision, visitor);\n\t\t\t\troot = config.detachedFieldIndex.getEntry(id);\n\t\t\t}\n\t\t\t// the revision is updated for any refresher data included in the delta that is used\n\t\t\tconfig.detachedFieldIndex.updateLatestRevision(id, config.latestRevision);\n\t\t\tconfig.detachPassRoots.set(root, fields);\n\t\t\tconfig.attachPassRoots.set(root, fields);\n\t\t}\n\t}\n}\n\nfunction processRename(\n\trename: readonly Delta.DetachedNodeRename[] | undefined,\n\tconfig: PassConfig,\n): void {\n\tif (rename !== undefined) {\n\t\tconfig.rootTransfers.push(...rename);\n\t}\n}\n\nfunction collectDestroys(\n\tdestroys: readonly Delta.DetachedNodeDestruction[] | undefined,\n\tconfig: PassConfig,\n): void {\n\tif (destroys !== undefined) {\n\t\tconfig.rootDestructions.push(...destroys);\n\t}\n}\n\n/**\n * Preforms the following:\n * - Executes attaches (top-down) applying nested changes on the attached nodes\n */\nfunction attachPass(\n\tfieldChanges: Delta.FieldChanges,\n\tvisitor: DeltaVisitor,\n\tconfig: PassConfig,\n): void {\n\tlet index = 0;\n\tfor (const mark of fieldChanges) {\n\t\tif (mark.attach !== undefined) {\n\t\t\tfor (let i = 0; i < mark.count; i += 1) {\n\t\t\t\tconst offsetAttachId = offsetDetachId(mark.attach, i);\n\t\t\t\tlet sourceRoot = config.detachedFieldIndex.tryGetEntry(offsetAttachId);\n\t\t\t\tif (sourceRoot === undefined) {\n\t\t\t\t\tconst tree = tryGetFromNestedMap(\n\t\t\t\t\t\tconfig.refreshers,\n\t\t\t\t\t\toffsetAttachId.major,\n\t\t\t\t\t\toffsetAttachId.minor,\n\t\t\t\t\t);\n\t\t\t\t\tassert(tree !== undefined, 0x92a /* refresher data not found */);\n\t\t\t\t\tbuildTrees(\n\t\t\t\t\t\toffsetAttachId,\n\t\t\t\t\t\t[tree],\n\t\t\t\t\t\tconfig.detachedFieldIndex,\n\t\t\t\t\t\tconfig.latestRevision,\n\t\t\t\t\t\tvisitor,\n\t\t\t\t\t);\n\t\t\t\t\tsourceRoot = config.detachedFieldIndex.getEntry(offsetAttachId);\n\t\t\t\t}\n\t\t\t\tconst sourceField = config.detachedFieldIndex.toFieldKey(sourceRoot);\n\t\t\t\tconst offsetIndex = index + i;\n\t\t\t\tvisitor.attach(sourceField, 1, offsetIndex);\n\t\t\t\tconfig.detachedFieldIndex.deleteEntry(offsetAttachId);\n\t\t\t\tconst fields = config.attachPassRoots.get(sourceRoot);\n\t\t\t\tif (fields !== undefined) {\n\t\t\t\t\tconfig.attachPassRoots.delete(sourceRoot);\n\t\t\t\t\tvisitNode(offsetIndex, fields, visitor, config);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tif (mark.detach === undefined && mark.fields !== undefined) {\n\t\t\tvisitNode(index, mark.fields, visitor, config);\n\t\t}\n\t\tif (mark.detach === undefined || mark.attach !== undefined) {\n\t\t\tindex += mark.count;\n\t\t}\n\t}\n}\n\n/**\n * Converts a chunk of trees into an array of cursors.\n *\n * TODO: Update the visitDelta logic and downstream APIs to avoid splitting up sequences into individual nodes.\n */\nfunction nodeCursorsFromChunk(trees: TreeChunk): ITreeCursorSynchronous[] {\n\treturn mapCursorField(trees.cursor(), (c) => c.fork());\n}\n"]}
+{"version":3,"file":"visitDelta.js","sourceRoot":"","sources":["../../../src/core/tree/visitDelta.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils/internal\";\n\nimport { type NestedMap, setInNestedMap, tryGetFromNestedMap } from \"../../util/index.js\";\n\nimport type { FieldKey } from \"../schema-stored/index.js\";\n\nimport { mapCursorField, type ITreeCursorSynchronous } from \"./cursor.js\";\nimport type * as Delta from \"./delta.js\";\nimport { areDetachedNodeIdsEqual, offsetDetachId } from \"./deltaUtil.js\";\nimport type { DetachedFieldIndex } from \"./detachedFieldIndex.js\";\nimport type { ForestRootId, Major, Minor } from \"./detachedFieldIndexTypes.js\";\nimport type { NodeIndex, PlaceIndex, Range } from \"./pathTree.js\";\nimport type { RevisionTag } from \"../rebase/index.js\";\nimport type { TreeChunk } from \"./chunk.js\";\n\n/**\n * Implementation notes:\n *\n * The visit is organized into four phases:\n * 1. a detach pass\n * 2. root transfers\n * 3. an attach pass\n * 4. root destructions\n *\n * The core idea is that before content can be attached, it must first exist and be in a detached field.\n *\n * While the detach pass ensures that nodes to be attached are in a detached state, it does not guarantee that they\n * reside in the correct detached field. That is the responsibility of the root transfers phase.\n *\n * The attach phase carries out attaches.\n *\n * After the attach phase, roots destruction is carried out.\n * This needs to happen last to allow modifications to detached roots to be applied before they are destroyed.\n *\n * The details of the delta visit algorithm can impact how/when events are emitted by the objects that own the visitors.\n * For example, as of 2024-03-27, the subtreeChanged event of an AnchorNode is emitted when exiting a node during a\n * delta visit, and thus the two-pass nature of the algorithm means the event fires twice for any given change.\n */\n\n/**\n * Crawls the given `delta`, calling `visitor`'s callback for each change encountered.\n * Each successive call to the visitor callbacks assumes that the change described by earlier calls have been applied\n * to the document tree. For example, for a change that removes the first and third node of a field, the visitor calls\n * will first call detach with a range from indices 0 to 1 then call detach with a range from indices 1 to 2.\n *\n * @param delta - The delta to be crawled.\n * @param visitor - The object to notify of the changes encountered.\n * @param detachedFieldIndex - Index responsible for keeping track of the existing detached fields.\n * @param latestRevision - The latest revision tag associated with this delta.\n */\nexport function visitDelta(\n\tdelta: Delta.Root,\n\tvisitor: DeltaVisitor,\n\tdetachedFieldIndex: DetachedFieldIndex,\n\tlatestRevision: RevisionTag | undefined,\n): void {\n\tconst detachPassRoots: Map<ForestRootId, Delta.FieldMap> = new Map();\n\tconst attachPassRoots: Map<ForestRootId, Delta.FieldMap> = new Map();\n\tconst rootTransfers: Delta.DetachedNodeRename[] = [];\n\tconst rootDestructions: Delta.DetachedNodeDestruction[] = [];\n\tconst refreshers: NestedMap<Major, Minor, ITreeCursorSynchronous> = new Map();\n\tdelta.refreshers?.forEach(({ id: { major, minor }, trees }) => {\n\t\tconst treeCursors = nodeCursorsFromChunk(trees);\n\t\tfor (let i = 0; i < trees.topLevelLength; i += 1) {\n\t\t\tconst offsettedId = minor + i;\n\t\t\tsetInNestedMap(refreshers, major, offsettedId, treeCursors[i]);\n\t\t}\n\t});\n\tconst detachConfig: PassConfig = {\n\t\tfunc: detachPass,\n\t\tlatestRevision,\n\t\trefreshers,\n\t\tdetachedFieldIndex,\n\t\tdetachPassRoots,\n\t\tattachPassRoots,\n\t\trootTransfers,\n\t\trootDestructions,\n\t};\n\tprocessBuilds(delta.build, detachConfig, visitor);\n\tprocessGlobal(delta.global, detachConfig, visitor);\n\tprocessRename(delta.rename, detachConfig);\n\tvisitFieldMarks(delta.fields, visitor, detachConfig);\n\tfixedPointVisitOfRoots(visitor, detachPassRoots, detachConfig);\n\ttransferRoots(\n\t\trootTransfers,\n\t\tattachPassRoots,\n\t\tdetachedFieldIndex,\n\t\tvisitor,\n\t\trefreshers,\n\t\tlatestRevision,\n\t);\n\tconst attachConfig: PassConfig = {\n\t\tfunc: attachPass,\n\t\tlatestRevision,\n\t\trefreshers,\n\t\tdetachedFieldIndex,\n\t\tdetachPassRoots,\n\t\tattachPassRoots,\n\t\trootTransfers,\n\t\trootDestructions,\n\t};\n\tvisitFieldMarks(delta.fields, visitor, attachConfig);\n\tfixedPointVisitOfRoots(visitor, attachPassRoots, attachConfig);\n\tcollectDestroys(delta.destroy, attachConfig);\n\tfor (const { id, count } of rootDestructions) {\n\t\tfor (let i = 0; i < count; i += 1) {\n\t\t\tconst offsetId = offsetDetachId(id, i);\n\t\t\tconst root = detachedFieldIndex.getEntry(offsetId);\n\t\t\tconst field = detachedFieldIndex.toFieldKey(root);\n\t\t\tvisitor.destroy(field, 1);\n\t\t\tdetachedFieldIndex.deleteEntry(offsetId);\n\t\t}\n\t}\n}\n\n/**\n * Visits all nodes in `roots` until none are left.\n * This function tolerates entries being added to and removed from `roots` as part of visits.\n * @param visitor - The visitor to visit the roots with.\n * @param roots - The initial set of roots to visit.\n * Individual entries are removed prior to being visited.\n * @param config - The configuration to use for visits.\n */\nfunction fixedPointVisitOfRoots(\n\tvisitor: DeltaVisitor,\n\troots: Map<ForestRootId, Delta.FieldMap>,\n\tconfig: PassConfig,\n): void {\n\twhile (roots.size > 0) {\n\t\tfor (const [root, modifications] of roots) {\n\t\t\troots.delete(root);\n\t\t\tconst field = config.detachedFieldIndex.toFieldKey(root);\n\t\t\tvisitor.enterField(field);\n\t\t\t// Note: each visit may lead to `roots` being populated with new entries or having some entries removed.\n\t\t\tvisitNode(0, modifications, visitor, config);\n\t\t\tvisitor.exitField(field);\n\t\t}\n\t}\n}\n\n/**\n * Transfers roots from one detached field to another.\n * This occurs in the following circumstances:\n * - A changeset moves then removes a node\n * - A changeset restores then moves a node\n * - A changeset restores then removes a node\n * TODO#5481: update the DetachedFieldIndex instead of moving the nodes around.\n *\n * @param rootTransfers - The transfers to perform.\n * @param mapToUpdate - A map to update based on the transfers being performed.\n * @param detachedFieldIndex - The index to update based on the transfers being performed.\n * @param visitor - The visitor to inform of the transfers being performed.\n */\nfunction transferRoots(\n\trootTransfers: readonly Delta.DetachedNodeRename[],\n\tmapToUpdate: Map<ForestRootId, unknown>,\n\tdetachedFieldIndex: DetachedFieldIndex,\n\tvisitor: DeltaVisitor,\n\trefreshers: NestedMap<Major, Minor, ITreeCursorSynchronous>,\n\trevision?: RevisionTag,\n): void {\n\ttype AtomizedNodeRename = Omit<Delta.DetachedNodeRename, \"count\">;\n\tlet nextBatch = rootTransfers.flatMap(({ oldId, newId, count }) => {\n\t\tconst atomized: AtomizedNodeRename[] = [];\n\t\t// It's possible for a detached node to be revived transiently such that it ends up back in the same detached field.\n\t\t// Making such a transfer wouldn't just be inefficient, it would lead us to mistakenly think we have moved all content\n\t\t// out of the source detached field, and would lead us to delete the tree index entry for that source detached field.\n\t\t// This would effectively result in the tree index missing an entry for the detached field.\n\t\t// This if statement prevents that from happening.\n\t\tif (!areDetachedNodeIdsEqual(oldId, newId)) {\n\t\t\tfor (let i = 0; i < count; i += 1) {\n\t\t\t\tatomized.push({ oldId: offsetDetachId(oldId, i), newId: offsetDetachId(newId, i) });\n\t\t\t}\n\t\t}\n\t\treturn atomized;\n\t});\n\twhile (nextBatch.length > 0) {\n\t\tconst delayed: AtomizedNodeRename[] = [];\n\t\tconst priorSize = nextBatch.length;\n\t\tfor (const { oldId, newId } of nextBatch) {\n\t\t\tlet oldRootId = detachedFieldIndex.tryGetEntry(oldId);\n\t\t\tif (oldRootId === undefined) {\n\t\t\t\tconst tree = tryGetFromNestedMap(refreshers, oldId.major, oldId.minor);\n\t\t\t\tif (tree !== undefined) {\n\t\t\t\t\tbuildTrees(oldId, [tree], detachedFieldIndex, revision, visitor);\n\t\t\t\t\toldRootId = detachedFieldIndex.getEntry(oldId);\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (oldRootId === undefined) {\n\t\t\t\t// The source field is not populated.\n\t\t\t\t// This can happen when another rename needs to be performed first.\n\t\t\t\tdelayed.push({ oldId, newId });\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tlet newRootId = detachedFieldIndex.tryGetEntry(newId);\n\t\t\tif (newRootId !== undefined) {\n\t\t\t\t// The destination field is already occupied.\n\t\t\t\t// This can happen when another rename needs to be performed first.\n\t\t\t\tdelayed.push({ oldId, newId });\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tnewRootId = detachedFieldIndex.createEntry(newId, revision);\n\t\t\tconst fields = mapToUpdate.get(oldRootId);\n\t\t\tif (fields !== undefined) {\n\t\t\t\tmapToUpdate.delete(oldRootId);\n\t\t\t\tmapToUpdate.set(newRootId, fields);\n\t\t\t}\n\t\t\tconst oldField = detachedFieldIndex.toFieldKey(oldRootId);\n\t\t\tconst newField = detachedFieldIndex.toFieldKey(newRootId);\n\t\t\tvisitor.enterField(oldField);\n\t\t\tvisitor.detach({ start: 0, end: 1 }, newField, newId, false);\n\t\t\tvisitor.exitField(oldField);\n\t\t\tdetachedFieldIndex.deleteEntry(oldId);\n\t\t}\n\t\tassert(delayed.length < priorSize, 0x7cf /* transferRoots should make progress */);\n\t\tnextBatch = delayed;\n\t}\n}\n\n/**\n * Visitor for changes in a delta.\n * Must be freed after use.\n */\nexport interface DeltaVisitor {\n\t/**\n\t * Frees/releases the visitor.\n\t *\n\t * Must be called once the visitor finished traversing the delta for a couple of reasons:\n\t *\n\t * 1. Some visitors, such as those from forests, are put into a special mode while they have a visitor, forbidding some actions (like making more visitors).\n\t *\n\t * 2. Some visitors, such as those from an anchorSet, defer some events for batching purposes until the visitor is freed.\n\t */\n\tfree(): void;\n\t/**\n\t * Creates nodes for the given content in a new detached field.\n\t * @param content - The content to create.\n\t * @param destination - The key for a new detached field.\n\t * A field with this key must not already exist.\n\t */\n\tcreate(content: readonly ITreeCursorSynchronous[], destination: FieldKey): void;\n\t/**\n\t * Recursively destroys the given detached field and all of the nodes within it.\n\t * @param detachedField - The key for the detached field to destroy.\n\t * @param count - The number of nodes being destroyed.\n\t * Expected to match the number of nodes in the detached field being destroyed.\n\t */\n\tdestroy(detachedField: FieldKey, count: number): void;\n\t/**\n\t * Transfers all the nodes from a detached field to the current field.\n\t * @param source - The detached field to transfer the nodes from.\n\t * @param count - The number of nodes being attached.\n\t * Expected to match the number of nodes in the source detached field.\n\t * @param destination - The index at which to attach the nodes.\n\t */\n\tattach(source: FieldKey, count: number, destination: PlaceIndex): void;\n\t/**\n\t * Transfers a range of nodes from the current field to a new detached field.\n\t * @param source - The bounds of the range of nodes to detach.\n\t * @param destination - The key for a new detached field.\n\t * A field with this key must not already exist.\n\t * @param id - The ID assigned to the first detached node as a result of the detach. The other nodes in the detached range are assigned subsequent IDs.\n\t * @param isReplaced - Whether the detached content will be replaced by a later attach.\n\t * This is not guaranteed to be true in all cases where it could be true,\n\t * but it is guaranteed to be true in all cases where a later attach is needed to keep the data compliant with the schema.\n\t */\n\tdetach(\n\t\tsource: Range,\n\t\tdestination: FieldKey,\n\t\tid: Delta.DetachedNodeId,\n\t\tisReplaced: boolean,\n\t): void;\n\n\t/**\n\t * Tells the visitor that it should update its \"current location\" to be the Node at the specified index\n\t * within the Field that is the current \"current location\".\n\t * Future calls to methods of {@link DeltaVisitor} will assume that's the location where their effects are happening.\n\t * @param index - The index (within the Field) of the node that should become the new \"current location\".\n\t *\n\t * @remarks This should only be called when the \"current location\" is a Field.\n\t */\n\tenterNode(index: NodeIndex): void;\n\n\t/**\n\t * Tells the visitor that it should update its \"current location\" to be the Field which contains the Node\n\t * that is the current \"current location\".\n\t * Future calls to methods of {@link DeltaVisitor} will assume that's the location where their effects are happening.\n\t * @param index - The index (within its Field) of the node that is being exited.\n\t *\n\t * @remarks This should only be called when the \"current location\" is a Node.\n\t */\n\texitNode(index: NodeIndex): void;\n\n\t/**\n\t * Tells the visitor that it should update its \"current location\" to be the Field with the specified key,\n\t * within the Node that is the current \"current location\".\n\t * Future calls to methods of {@link DeltaVisitor} will assume that's the location where their effects are happening.\n\t * @param key - The key of the field that should become the new \"current location\".\n\t *\n\t * @remarks This should only be called when the \"current location\" is a Node.\n\t */\n\tenterField(key: FieldKey): void;\n\n\t/**\n\t * Tells the visitor that it should update its \"current location\" to be the Node which contains the Field\n\t * that is the current \"current location\".\n\t * Future calls to methods of {@link DeltaVisitor} will assume that's the location where their effects are happening.\n\t * @param key - The key of the field that is being exited.\n\t *\n\t * @remarks This should only be called when the \"current location\" is a Field.\n\t */\n\texitField(key: FieldKey): void;\n}\n\ninterface PassConfig {\n\treadonly func: Pass;\n\n\t/**\n\t * The latest revision tag associated with the given delta. This is used to keep track\n\t * of when repair data should be garbage collected.\n\t */\n\treadonly latestRevision: RevisionTag | undefined;\n\n\treadonly detachedFieldIndex: DetachedFieldIndex;\n\t/**\n\t * A mapping between forest root id and trees that represent refresher data. Each entry is only\n\t * created in the forest once needed.\n\t */\n\treadonly refreshers: NestedMap<Major, Minor, ITreeCursorSynchronous>;\n\t/**\n\t * Nested changes on roots that need to be visited as part of the detach pass.\n\t * Each entry is removed when its associated changes are visited.\n\t */\n\treadonly detachPassRoots: Map<ForestRootId, Delta.FieldMap>;\n\t/**\n\t * Nested changes on roots that need to be visited as part of the attach pass.\n\t * Each entry is removed when its associated changes are visited.\n\t * Some of these roots will attached during the attach pass, in which case the nested changes are visited after\n\t * the node is attached.\n\t * Some of these nodes will never be attached, in which case we visit them in their detached fields at the end of\n\t * the attach pass. Note that such a visit might lead to more nodes being attached, including nodes were visited as\n\t * roots.\n\t */\n\treadonly attachPassRoots: Map<ForestRootId, Delta.FieldMap>;\n\t/**\n\t * Represents transfers of roots from one detached field to another.\n\t */\n\treadonly rootTransfers: Delta.DetachedNodeRename[];\n\t/**\n\t * Represents roots that need to be destroyed.\n\t * Collected as part of the detach pass.\n\t * Carried out at the end of the attach pass.\n\t */\n\treadonly rootDestructions: Delta.DetachedNodeDestruction[];\n}\n\ntype Pass = (delta: Delta.FieldChanges, visitor: DeltaVisitor, config: PassConfig) => void;\n\nfunction visitFieldMarks(\n\tfields: Delta.FieldMap | undefined,\n\tvisitor: DeltaVisitor,\n\tconfig: PassConfig,\n): void {\n\tif (fields !== undefined) {\n\t\tfor (const [key, field] of fields) {\n\t\t\tvisitor.enterField(key);\n\t\t\tconfig.func(field, visitor, config);\n\t\t\tvisitor.exitField(key);\n\t\t}\n\t}\n}\n\nfunction visitNode(\n\tindex: number,\n\tfields: Delta.FieldMap | undefined,\n\tvisitor: DeltaVisitor,\n\tconfig: PassConfig,\n): void {\n\tif (fields !== undefined) {\n\t\tvisitor.enterNode(index);\n\t\tvisitFieldMarks(fields, visitor, config);\n\t\tvisitor.exitNode(index);\n\t}\n}\n\n/**\n * Performs the following:\n * - Collects all roots that may need an attach pass\n * - Executes detaches (bottom-up)\n */\nfunction detachPass(\n\tfieldChanges: Delta.FieldChanges,\n\tvisitor: DeltaVisitor,\n\tconfig: PassConfig,\n): void {\n\tlet index = 0;\n\tfor (const mark of fieldChanges) {\n\t\tif (mark.fields !== undefined) {\n\t\t\tassert(\n\t\t\t\tmark.attach === undefined || mark.detach !== undefined,\n\t\t\t\t0x7d0 /* Invalid nested changes on an additive mark */,\n\t\t\t);\n\t\t\tvisitNode(index, mark.fields, visitor, config);\n\t\t}\n\t\tif (mark.detach !== undefined) {\n\t\t\tfor (let i = 0; i < mark.count; i += 1) {\n\t\t\t\tconst id = offsetDetachId(mark.detach, i);\n\t\t\t\tconst root = config.detachedFieldIndex.createEntry(id, config.latestRevision);\n\t\t\t\tif (mark.fields !== undefined) {\n\t\t\t\t\tconfig.attachPassRoots.set(root, mark.fields);\n\t\t\t\t}\n\t\t\t\tconst field = config.detachedFieldIndex.toFieldKey(root);\n\t\t\t\tvisitor.detach({ start: index, end: index + 1 }, field, id, mark.attach !== undefined);\n\t\t\t}\n\t\t}\n\t\tif (mark.detach === undefined && mark.attach === undefined) {\n\t\t\tindex += mark.count;\n\t\t}\n\t}\n}\n\nfunction buildTrees(\n\tid: Delta.DetachedNodeId,\n\ttrees: readonly ITreeCursorSynchronous[],\n\tdetachedFieldIndex: DetachedFieldIndex,\n\tlatestRevision: RevisionTag | undefined,\n\tvisitor: DeltaVisitor,\n): void {\n\tfor (const [i, tree] of trees.entries()) {\n\t\tconst offsettedId = offsetDetachId(id, i);\n\t\tlet root = detachedFieldIndex.tryGetEntry(offsettedId);\n\t\tassert(root === undefined, 0x929 /* Unable to build tree that already exists */);\n\t\troot = detachedFieldIndex.createEntry(offsettedId, latestRevision);\n\t\tconst field = detachedFieldIndex.toFieldKey(root);\n\t\tvisitor.create([tree], field);\n\t}\n}\n\nfunction processBuilds(\n\tbuilds: readonly Delta.DetachedNodeBuild[] | undefined,\n\tconfig: PassConfig,\n\tvisitor: DeltaVisitor,\n): void {\n\tif (builds !== undefined) {\n\t\tfor (const { id, trees } of builds) {\n\t\t\tbuildTrees(\n\t\t\t\tid,\n\t\t\t\tnodeCursorsFromChunk(trees),\n\t\t\t\tconfig.detachedFieldIndex,\n\t\t\t\tconfig.latestRevision,\n\t\t\t\tvisitor,\n\t\t\t);\n\t\t}\n\t}\n}\n\nfunction processGlobal(\n\tglobal: readonly Delta.DetachedNodeChanges[] | undefined,\n\tconfig: PassConfig,\n\tvisitor: DeltaVisitor,\n): void {\n\tif (global !== undefined) {\n\t\tfor (const { id, fields } of global) {\n\t\t\tlet root = config.detachedFieldIndex.tryGetEntry(id);\n\t\t\tif (root === undefined) {\n\t\t\t\tconst tree = tryGetFromNestedMap(config.refreshers, id.major, id.minor);\n\t\t\t\tassert(tree !== undefined, 0x928 /* refresher data not found */);\n\t\t\t\tbuildTrees(id, [tree], config.detachedFieldIndex, config.latestRevision, visitor);\n\t\t\t\troot = config.detachedFieldIndex.getEntry(id);\n\t\t\t}\n\t\t\t// the revision is updated for any refresher data included in the delta that is used\n\t\t\tconfig.detachedFieldIndex.updateLatestRevision(id, config.latestRevision);\n\t\t\tconfig.detachPassRoots.set(root, fields);\n\t\t\tconfig.attachPassRoots.set(root, fields);\n\t\t}\n\t}\n}\n\nfunction processRename(\n\trename: readonly Delta.DetachedNodeRename[] | undefined,\n\tconfig: PassConfig,\n): void {\n\tif (rename !== undefined) {\n\t\tconfig.rootTransfers.push(...rename);\n\t}\n}\n\nfunction collectDestroys(\n\tdestroys: readonly Delta.DetachedNodeDestruction[] | undefined,\n\tconfig: PassConfig,\n): void {\n\tif (destroys !== undefined) {\n\t\tconfig.rootDestructions.push(...destroys);\n\t}\n}\n\n/**\n * Preforms the following:\n * - Executes attaches (top-down) applying nested changes on the attached nodes\n */\nfunction attachPass(\n\tfieldChanges: Delta.FieldChanges,\n\tvisitor: DeltaVisitor,\n\tconfig: PassConfig,\n): void {\n\tlet index = 0;\n\tfor (const mark of fieldChanges) {\n\t\tif (mark.attach !== undefined) {\n\t\t\tfor (let i = 0; i < mark.count; i += 1) {\n\t\t\t\tconst offsetAttachId = offsetDetachId(mark.attach, i);\n\t\t\t\tlet sourceRoot = config.detachedFieldIndex.tryGetEntry(offsetAttachId);\n\t\t\t\tif (sourceRoot === undefined) {\n\t\t\t\t\tconst tree = tryGetFromNestedMap(\n\t\t\t\t\t\tconfig.refreshers,\n\t\t\t\t\t\toffsetAttachId.major,\n\t\t\t\t\t\toffsetAttachId.minor,\n\t\t\t\t\t);\n\t\t\t\t\tassert(tree !== undefined, 0x92a /* refresher data not found */);\n\t\t\t\t\tbuildTrees(\n\t\t\t\t\t\toffsetAttachId,\n\t\t\t\t\t\t[tree],\n\t\t\t\t\t\tconfig.detachedFieldIndex,\n\t\t\t\t\t\tconfig.latestRevision,\n\t\t\t\t\t\tvisitor,\n\t\t\t\t\t);\n\t\t\t\t\tsourceRoot = config.detachedFieldIndex.getEntry(offsetAttachId);\n\t\t\t\t}\n\t\t\t\tconst sourceField = config.detachedFieldIndex.toFieldKey(sourceRoot);\n\t\t\t\tconst offsetIndex = index + i;\n\t\t\t\tvisitor.attach(sourceField, 1, offsetIndex);\n\t\t\t\tconfig.detachedFieldIndex.deleteEntry(offsetAttachId);\n\t\t\t\tconst fields = config.attachPassRoots.get(sourceRoot);\n\t\t\t\tif (fields !== undefined) {\n\t\t\t\t\tconfig.attachPassRoots.delete(sourceRoot);\n\t\t\t\t\tvisitNode(offsetIndex, fields, visitor, config);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tif (mark.detach === undefined && mark.fields !== undefined) {\n\t\t\tvisitNode(index, mark.fields, visitor, config);\n\t\t}\n\t\tif (mark.detach === undefined || mark.attach !== undefined) {\n\t\t\tindex += mark.count;\n\t\t}\n\t}\n}\n\n/**\n * Converts a chunk of trees into an array of cursors.\n *\n * TODO: Update the visitDelta logic and downstream APIs to avoid splitting up sequences into individual nodes.\n */\nfunction nodeCursorsFromChunk(trees: TreeChunk): ITreeCursorSynchronous[] {\n\treturn mapCursorField(trees.cursor(), (c) => c.fork());\n}\n"]}

package/dist/feature-libraries/chunked-forest/index.d.ts

@@ -7,4 +7,5 @@ export { type TreeChunk, dummyRoot } from "../../core/index.js";
 export { chunkTree, defaultChunkPolicy, makeTreeChunker, type IChunker, chunkFieldSingle, chunkField, } from "./chunkTree.js";
 export { buildChunkedForest } from "./chunkedForest.js";
 export { EncodedFieldBatch, type FieldBatch, type FieldBatchCodec, makeFieldBatchCodec, type FieldBatchEncodingContext, fluidVersionToFieldBatchCodecWriteVersion, } from "./codec/index.js";
+export { emptyChunk } from "./emptyChunk.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/feature-libraries/chunked-forest/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/feature-libraries/chunked-forest/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,KAAK,SAAS,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EACN,SAAS,EACT,kBAAkB,EAClB,eAAe,EACf,KAAK,QAAQ,EACb,gBAAgB,EAChB,UAAU,GACV,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EACN,iBAAiB,EACjB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,mBAAmB,EACnB,KAAK,yBAAyB,EAC9B,yCAAyC,GACzC,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/feature-libraries/chunked-forest/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,KAAK,SAAS,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EACN,SAAS,EACT,kBAAkB,EAClB,eAAe,EACf,KAAK,QAAQ,EACb,gBAAgB,EAChB,UAAU,GACV,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EACN,iBAAiB,EACjB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,mBAAmB,EACnB,KAAK,yBAAyB,EAC9B,yCAAyC,GACzC,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}