@fluidframework/tree 2.13.0 → 2.21.0

package/src/feature-libraries/modular-schema/modularChangeFamily.ts

@@ -30,7 +30,6 @@ import {
 	type RevisionTag,
 	type TaggedChange,
 	type UpPath,
-	isEmptyFieldChanges,
 	makeDetachedNodeId,
 	mapCursorField,
 	replaceAtomRevisions,
@@ -40,6 +39,9 @@ import {
 	areEqualChangeAtomIdOpts,
 	tagChange,
 	makeAnonChange,
+	newChangeAtomIdRangeMap,
+	type DeltaDetachedNodeChanges,
+	type DeltaDetachedNodeRename,
 } from "../../core/index.js";
 import {
 	type IdAllocationState,
@@ -51,6 +53,10 @@ import {
 	idAllocatorFromState,
 	type RangeQueryResult,
 	getOrAddInMapLazy,
+	newTupleBTree,
+	mergeTupleBTrees,
+	type TupleBTree,
+	RangeMap,
 } from "../../util/index.js";
 import {
 	type TreeChunk,
@@ -75,18 +81,19 @@ import {
 import { type FieldKindWithEditor, withEditor } from "./fieldKindWithEditor.js";
 import { convertGenericChange, genericFieldKind } from "./genericFieldKind.js";
 import type { GenericChangeset } from "./genericFieldKindTypes.js";
-import type {
-	ChangeAtomIdBTree,
-	CrossFieldKeyRange,
-	CrossFieldKeyTable,
-	FieldChange,
-	FieldChangeMap,
-	FieldChangeset,
-	FieldId,
-	ModularChangeset,
-	NodeChangeset,
-	NodeId,
-	TupleBTree,
+import {
+	type ChangeAtomIdBTree,
+	type CrossFieldKey,
+	type CrossFieldKeyRange,
+	type CrossFieldKeyTable,
+	type FieldChange,
+	type FieldChangeMap,
+	type FieldChangeset,
+	type FieldId,
+	type ModularChangeset,
+	newCrossFieldKeyTable,
+	type NodeChangeset,
+	type NodeId,
 } from "./modularChangeTypes.js";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 
@@ -252,7 +259,7 @@ export class ModularChangeFamily
 				nodeChanges: newTupleBTree(),
 				nodeToParent: newTupleBTree(),
 				nodeAliases: newTupleBTree(),
-				crossFieldKeys: newTupleBTree(),
+				crossFieldKeys: newCrossFieldKeyTable(),
 			};
 		} else if (hasConflicts(change1)) {
 			return change2;
@@ -272,14 +279,14 @@ export class ModularChangeFamily
 		// (since we assume that if two changesets use the same node ID they are referring to the same node),
 		// therefore all collisions will be addressed when processing the intersection of the changesets.
 		const composedNodeChanges: ChangeAtomIdBTree<NodeChangeset> = brand(
-			mergeBTrees(change1.nodeChanges, change2.nodeChanges),
+			mergeTupleBTrees(change1.nodeChanges, change2.nodeChanges),
 		);
 
 		const composedNodeToParent: ChangeAtomIdBTree<FieldId> = brand(
-			mergeBTrees(change1.nodeToParent, change2.nodeToParent),
+			mergeTupleBTrees(change1.nodeToParent, change2.nodeToParent),
 		);
 		const composedNodeAliases: ChangeAtomIdBTree<NodeId> = brand(
-			mergeBTrees(change1.nodeAliases, change2.nodeAliases),
+			mergeTupleBTrees(change1.nodeAliases, change2.nodeAliases),
 		);
 
 		const crossFieldTable = newComposeTable(change1, change2, composedNodeToParent);
@@ -304,13 +311,16 @@ export class ModularChangeFamily
 		);
 
 		// Currently no field kinds require making changes to cross-field keys during composition, so we can just merge the two tables.
-		const composedCrossFieldKeys = mergeBTrees(change1.crossFieldKeys, change2.crossFieldKeys);
+		const composedCrossFieldKeys = RangeMap.union(
+			change1.crossFieldKeys,
+			change2.crossFieldKeys,
+		);
 		return {
 			fieldChanges: composedFields,
 			nodeChanges: composedNodeChanges,
 			nodeToParent: composedNodeToParent,
 			nodeAliases: composedNodeAliases,
-			crossFieldKeys: brand(composedCrossFieldKeys),
+			crossFieldKeys: composedCrossFieldKeys,
 		};
 	}
 
@@ -902,7 +912,7 @@ export class ModularChangeFamily
 			baseToRebasedNodeId: newTupleBTree(),
 			rebasedFields: new Set(),
 			rebasedNodeToParent: brand(change.nodeToParent.clone()),
-			rebasedCrossFieldKeys: brand(change.crossFieldKeys.clone()),
+			rebasedCrossFieldKeys: change.crossFieldKeys.clone(),
 			nodeIdPairs: [],
 			affectedBaseFields: newTupleBTree(),
 			fieldsWithUnattachedChild: new Set(),
@@ -1667,8 +1677,8 @@ export class ModularChangeFamily
 			const keys = getChangeHandler(this.fieldKinds, fieldChange.fieldKind).getCrossFieldKeys(
 				fieldChange.change,
 			);
-			for (const key of keys) {
-				table.set(key, { nodeId: parent, field: fieldKey });
+			for (const { key, count } of keys) {
+				table.set(key, count, { nodeId: parent, field: fieldKey });
 			}
 		}
 	}
@@ -1728,7 +1738,7 @@ export class ModularChangeFamily
 			}
 
 			for (const keyRange of handler.getCrossFieldKeys(fieldChange.change)) {
-				const fields = getFieldsForCrossFieldKey(change, keyRange);
+				const fields = getFieldsForCrossFieldKey(change, keyRange.key, keyRange.count);
 				assert(
 					fields.length === 1 &&
 						fields[0] !== undefined &&
@@ -1748,15 +1758,16 @@ function replaceCrossFieldKeyTableRevisions(
 	newRevision: RevisionTag | undefined,
 	nodeAliases: ChangeAtomIdBTree<NodeId>,
 ): CrossFieldKeyTable {
-	const updated: CrossFieldKeyTable = newTupleBTree();
-	table.forEachPair(([target, revision, id, count], field) => {
-		const updatedKey: CrossFieldKeyRange = [
-			target,
-			replaceRevision(revision, oldRevisions, newRevision),
-			id,
-			count,
-		];
+	const updated: CrossFieldKeyTable = newCrossFieldKeyTable();
+	for (const entry of table.entries()) {
+		const key = entry.start;
+		const updatedKey: CrossFieldKey = {
+			target: key.target,
+			revision: replaceRevision(key.revision, oldRevisions, newRevision),
+			localId: key.localId,
+		};
 
+		const field = entry.value;
 		const normalizedFieldId = normalizeFieldId(field, nodeAliases);
 		const updatedNodeId =
 			normalizedFieldId.nodeId !== undefined
@@ -1768,8 +1779,8 @@ function replaceCrossFieldKeyTableRevisions(
 			nodeId: updatedNodeId,
 		};
 
-		updated.set(updatedKey, updatedValue);
-	});
+		updated.set(updatedKey, entry.length, updatedValue);
+	}
 
 	return updated;
 }
@@ -1816,15 +1827,19 @@ function composeBuildsDestroysAndRefreshers(
 	// composition all the changes already reflected on the tree, but that is not something we
 	// care to support at this time.
 	const allBuilds: ChangeAtomIdBTree<TreeChunk> = brand(
-		mergeBTrees(change1.builds ?? newTupleBTree(), change2.builds ?? newTupleBTree(), true),
+		mergeTupleBTrees(
+			change1.builds ?? newTupleBTree(),
+			change2.builds ?? newTupleBTree(),
+			true,
+		),
 	);
 
 	const allDestroys: ChangeAtomIdBTree<number> = brand(
-		mergeBTrees(change1.destroys ?? newTupleBTree(), change2.destroys ?? newTupleBTree()),
+		mergeTupleBTrees(change1.destroys ?? newTupleBTree(), change2.destroys ?? newTupleBTree()),
 	);
 
 	const allRefreshers: ChangeAtomIdBTree<TreeChunk> = brand(
-		mergeBTrees(
+		mergeTupleBTrees(
 			change1.refreshers ?? newTupleBTree(),
 			change2.refreshers ?? newTupleBTree(),
 			true,
@@ -1997,6 +2012,8 @@ export function updateRefreshers(
 }
 
 /**
+ * Converts a change into the delta format.
+ *
  * @param change - The change to convert into a delta.
  * @param fieldKinds - The field kinds to delegate to.
  */
@@ -2006,13 +2023,27 @@ export function intoDelta(
 ): DeltaRoot {
 	const change = taggedChange.change;
 	const rootDelta: Mutable<DeltaRoot> = {};
+	const global: DeltaDetachedNodeChanges[] = [];
+	const rename: DeltaDetachedNodeRename[] = [];
 
 	if (!hasConflicts(change)) {
 		// If there are no constraint violations, then tree changes apply.
-		const fieldDeltas = intoDeltaImpl(change.fieldChanges, change.nodeChanges, fieldKinds);
+		const fieldDeltas = intoDeltaImpl(
+			change.fieldChanges,
+			change.nodeChanges,
+			fieldKinds,
+			global,
+			rename,
+		);
 		if (fieldDeltas.size > 0) {
 			rootDelta.fields = fieldDeltas;
 		}
+		if (global.length > 0) {
+			rootDelta.global = global;
+		}
+		if (rename.length > 0) {
+			rootDelta.rename = rename;
+		}
 	}
 
 	// Constraint violations should not prevent nodes from being built
@@ -2060,19 +2091,28 @@ function intoDeltaImpl(
 	change: FieldChangeMap,
 	nodeChanges: ChangeAtomIdBTree<NodeChangeset>,
 	fieldKinds: ReadonlyMap<FieldKindIdentifier, FieldKindWithEditor>,
+	global: DeltaDetachedNodeChanges[],
+	rename: DeltaDetachedNodeRename[],
 ): Map<FieldKey, DeltaFieldChanges> {
 	const delta: Map<FieldKey, DeltaFieldChanges> = new Map();
+
 	for (const [field, fieldChange] of change) {
-		const deltaField = getChangeHandler(fieldKinds, fieldChange.fieldKind).intoDelta(
+		const {
+			local: fieldChanges,
+			global: fieldGlobal,
+			rename: fieldRename,
+		} = getChangeHandler(fieldKinds, fieldChange.fieldKind).intoDelta(
 			fieldChange.change,
 			(childChange): DeltaFieldMap => {
 				const nodeChange = nodeChangeFromId(nodeChanges, childChange);
-				return deltaFromNodeChange(nodeChange, nodeChanges, fieldKinds);
+				return deltaFromNodeChange(nodeChange, nodeChanges, fieldKinds, global, rename);
 			},
 		);
-		if (!isEmptyFieldChanges(deltaField)) {
-			delta.set(field, deltaField);
+		if (fieldChanges !== undefined && fieldChanges.length > 0) {
+			delta.set(field, fieldChanges);
 		}
+		fieldGlobal?.forEach((c) => global.push(c));
+		fieldRename?.forEach((r) => rename.push(r));
 	}
 	return delta;
 }
@@ -2081,9 +2121,11 @@ function deltaFromNodeChange(
 	change: NodeChangeset,
 	nodeChanges: ChangeAtomIdBTree<NodeChangeset>,
 	fieldKinds: ReadonlyMap<FieldKindIdentifier, FieldKindWithEditor>,
+	global: DeltaDetachedNodeChanges[],
+	rename: DeltaDetachedNodeRename[],
 ): DeltaFieldMap {
 	if (change.fieldChanges !== undefined) {
-		return intoDeltaImpl(change.fieldChanges, nodeChanges, fieldKinds);
+		return intoDeltaImpl(change.fieldChanges, nodeChanges, fieldKinds, global, rename);
 	}
 	// TODO: update the API to allow undefined to be returned here
 	return new Map();
@@ -2276,10 +2318,10 @@ interface ComposeFieldContext {
 
 function newCrossFieldTable<T>(): CrossFieldTable<T> {
 	return {
-		srcTable: new Map(),
-		dstTable: new Map(),
-		srcDependents: new Map(),
-		dstDependents: new Map(),
+		srcTable: newChangeAtomIdRangeMap(),
+		dstTable: newChangeAtomIdRangeMap(),
+		srcDependents: newChangeAtomIdRangeMap(),
+		dstDependents: newChangeAtomIdRangeMap(),
 		invalidatedFields: new Set(),
 	};
 }
@@ -2337,7 +2379,7 @@ abstract class CrossFieldManagerI<T> implements CrossFieldManager {
 		id: ChangesetLocalId,
 		count: number,
 		addDependency: boolean,
-	): RangeQueryResult<unknown> {
+	): RangeQueryResult<ChangeAtomId, unknown> {
 		if (addDependency) {
 			// We assume that if there is already an entry for this ID it is because
 			// a field handler has called compose on the same node multiple times.
@@ -2422,24 +2464,30 @@ class RebaseManager extends CrossFieldManagerI<FieldChange> {
 		invalidateDependents: boolean,
 	): void {
 		if (invalidateDependents && this.allowInval) {
-			const newFieldIds = getFieldsForCrossFieldKey(this.table.newChange, [
-				target,
-				revision,
-				id,
+			const newFieldIds = getFieldsForCrossFieldKey(
+				this.table.newChange,
+				{
+					target,
+					revision,
+					localId: id,
+				},
 				count,
-			]);
+			);
 
 			assert(
 				newFieldIds.length === 0,
 				0x9c6 /* TODO: Modifying a cross-field key from the new changeset is currently unsupported */,
 			);
 
-			const baseFieldIds = getFieldsForCrossFieldKey(this.table.baseChange, [
-				target,
-				revision,
-				id,
+			const baseFieldIds = getFieldsForCrossFieldKey(
+				this.table.baseChange,
+				{
+					target,
+					revision,
+					localId: id,
+				},
 				count,
-			]);
+			);
 
 			assert(
 				baseFieldIds.length > 0,
@@ -2467,11 +2515,8 @@ class RebaseManager extends CrossFieldManagerI<FieldChange> {
 		id: ChangesetLocalId,
 		count: number,
 	): void {
-		setInCrossFieldKeyTable(
-			this.table.rebasedCrossFieldKeys,
-			target,
-			revision,
-			id,
+		this.table.rebasedCrossFieldKeys.set(
+			{ target, revision, localId: id },
 			count,
 			this.fieldId,
 		);
@@ -2502,12 +2547,15 @@ class ComposeManager extends CrossFieldManagerI<FieldChange> {
 		invalidateDependents: boolean,
 	): void {
 		if (invalidateDependents && this.allowInval) {
-			const newFieldIds = getFieldsForCrossFieldKey(this.table.newChange, [
-				target,
-				revision,
-				id,
+			const newFieldIds = getFieldsForCrossFieldKey(
+				this.table.newChange,
+				{
+					target,
+					revision,
+					localId: id,
+				},
 				count,
-			]);
+			);
 
 			if (newFieldIds.length > 0) {
 				for (const newFieldId of newFieldIds) {
@@ -2517,12 +2565,15 @@ class ComposeManager extends CrossFieldManagerI<FieldChange> {
 					);
 				}
 			} else {
-				const baseFieldIds = getFieldsForCrossFieldKey(this.table.baseChange, [
-					target,
-					revision,
-					id,
+				const baseFieldIds = getFieldsForCrossFieldKey(
+					this.table.baseChange,
+					{
+						target,
+						revision,
+						localId: id,
+					},
 					count,
-				]);
+				);
 
 				assert(
 					baseFieldIds.length > 0,
@@ -2822,8 +2873,8 @@ function buildModularChangesetFromField(props: {
 	const fieldChanges: FieldChangeMap = new Map([[path.field, fieldChange]]);
 
 	if (path.parent === undefined) {
-		for (const key of localCrossFieldKeys) {
-			crossFieldKeys.set(key, { nodeId: undefined, field: path.field });
+		for (const { key, count } of localCrossFieldKeys) {
+			crossFieldKeys.set(key, count, { nodeId: undefined, field: path.field });
 		}
 
 		if (childId !== undefined) {
@@ -2849,8 +2900,8 @@ function buildModularChangesetFromField(props: {
 
 	const parentId: NodeId = { localId: brand(idAllocator.allocate()), revision };
 
-	for (const key of localCrossFieldKeys) {
-		crossFieldKeys.set(key, { nodeId: parentId, field: path.field });
+	for (const { key, count } of localCrossFieldKeys) {
+		crossFieldKeys.set(key, count, { nodeId: parentId, field: path.field });
 	}
 
 	if (childId !== undefined) {
@@ -2975,27 +3026,6 @@ function revisionInfoFromTaggedChange(
 	return revInfos;
 }
 
-function mergeBTrees<K extends readonly unknown[], V>(
-	tree1: TupleBTree<K, V> | undefined,
-	tree2: TupleBTree<K, V> | undefined,
-	preferLeft = true,
-): TupleBTree<K, V> {
-	if (tree1 === undefined) {
-		return tree2 !== undefined ? brand(tree2.clone()) : newTupleBTree<K, V>();
-	}
-
-	const result: TupleBTree<K, V> = brand(tree1.clone());
-	if (tree2 === undefined) {
-		return result;
-	}
-
-	for (const [key, value] of tree2.entries()) {
-		result.set(key, value, !preferLeft);
-	}
-
-	return result;
-}
-
 function fieldChangeFromId(
 	fields: FieldChangeMap,
 	nodes: ChangeAtomIdBTree<NodeChangeset>,
@@ -3071,104 +3101,21 @@ export function getParentFieldId(changeset: ModularChangeset, nodeId: NodeId): F
 	return normalizeFieldId(parentId, changeset.nodeAliases);
 }
 
-export function getFieldsForCrossFieldKey(
+function getFieldsForCrossFieldKey(
 	changeset: ModularChangeset,
-	[target, revision, id, count]: CrossFieldKeyRange,
-): FieldId[] {
-	let firstLocalId: number = id;
-	const lastLocalId = id + count - 1;
-
-	const fields: FieldId[] = [];
-
-	// eslint-disable-next-line no-constant-condition
-	while (true) {
-		const entry = getFirstIntersectingCrossFieldEntry(changeset.crossFieldKeys, [
-			target,
-			revision,
-			brand(firstLocalId),
-			count,
-		]);
-
-		if (entry === undefined) {
-			return fields;
-		}
-
-		const [[_target, _revision, entryId, entryCount], fieldId] = entry;
-		fields.push(normalizeFieldId(fieldId, changeset.nodeAliases));
-
-		const entryLastId = entryId + entryCount - 1;
-		if (entryLastId >= lastLocalId) {
-			return fields;
-		}
-
-		firstLocalId = entryLastId + 1;
-	}
-}
-
-function getFirstIntersectingCrossFieldEntry(
-	table: CrossFieldKeyTable,
-	[target, revision, id, count]: CrossFieldKeyRange,
-): [CrossFieldKeyRange, FieldId] | undefined {
-	const entry = table.nextLowerPair([target, revision, id, Number.POSITIVE_INFINITY]);
-	if (entry === undefined) {
-		return undefined;
-	}
-
-	const [entryTarget, entryRevision, entryId, entryCount] = entry[0];
-	if (entryTarget !== target || entryRevision !== revision) {
-		return undefined;
-	}
-
-	const lastQueryId = id + count - 1;
-	const entryLastId = entryId + entryCount - 1;
-	if (entryId > lastQueryId || entryLastId < id) {
-		return undefined;
-	}
-
-	return entry;
-}
-
-function setInCrossFieldKeyTable(
-	table: CrossFieldKeyTable,
-	target: CrossFieldTarget,
-	revision: RevisionTag | undefined,
-	id: ChangesetLocalId,
+	key: CrossFieldKey,
 	count: number,
-	value: FieldId,
-): void {
-	let entry = getFirstIntersectingCrossFieldEntry(table, [target, revision, id, count]);
-	const lastQueryId = id + count - 1;
-	while (entry !== undefined) {
-		const [entryKey, entryValue] = entry;
-		table.delete(entryKey);
-
-		const [_target, _revision, entryId, entryCount] = entryKey;
-		if (entryId < id) {
-			table.set([target, revision, entryId, id - entryId], entryValue);
-		}
-
-		const lastEntryId = entryId + entryCount - 1;
-		if (lastEntryId > lastQueryId) {
-			table.set(
-				[target, revision, brand(lastQueryId + 1), lastEntryId - lastQueryId],
-				entryValue,
-			);
-			break;
-		}
-
-		const nextId: ChangesetLocalId = brand(lastEntryId + 1);
-		entry = getFirstIntersectingCrossFieldEntry(table, [
-			target,
-			revision,
-			nextId,
-			lastQueryId - nextId + 1,
-		]);
-	}
-
-	table.set([target, revision, id, count], value);
+): FieldId[] {
+	return changeset.crossFieldKeys
+		.getAll(key, count)
+		.map(({ value: fieldId }) => normalizeFieldId(fieldId, changeset.nodeAliases));
 }
 
-function normalizeFieldId(fieldId: FieldId, nodeAliases: ChangeAtomIdBTree<NodeId>): FieldId {
+// This is only exported for use in test utilities.
+export function normalizeFieldId(
+	fieldId: FieldId,
+	nodeAliases: ChangeAtomIdBTree<NodeId>,
+): FieldId {
 	return fieldId.nodeId !== undefined
 		? { ...fieldId, nodeId: normalizeNodeId(fieldId.nodeId, nodeAliases) }
 		: fieldId;
@@ -3195,40 +3142,6 @@ function hasConflicts(change: ModularChangeset): boolean {
 	return (change.constraintViolationCount ?? 0) > 0;
 }
 
-export function newCrossFieldKeyTable(): CrossFieldKeyTable {
-	return newTupleBTree();
-}
-
-export function newTupleBTree<K extends readonly unknown[], V>(
-	entries?: [K, V][],
-): TupleBTree<K, V> {
-	return brand(new BTree<K, V>(entries, compareTuples));
-}
-
-// This assumes that the arrays are the same length.
-function compareTuples(arrayA: readonly unknown[], arrayB: readonly unknown[]): number {
-	for (let i = 0; i < arrayA.length; i++) {
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		const a = arrayA[i] as any;
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		const b = arrayB[i] as any;
-
-		// Less-than and greater-than always return false if either value is undefined,
-		// so we handle undefined separately, treating it as less than all other values.
-		if (a === undefined && b !== undefined) {
-			return -1;
-		} else if (b === undefined && a !== undefined) {
-			return 1;
-		} else if (a < b) {
-			return -1;
-		} else if (a > b) {
-			return 1;
-		}
-	}
-
-	return 0;
-}
-
 interface ModularChangesetContent {
 	fieldChanges: FieldChangeMap;
 	nodeChanges: ChangeAtomIdBTree<NodeChangeset>;

package/src/feature-libraries/modular-schema/modularChangeTypes.ts

@@ -3,16 +3,16 @@
  * Licensed under the MIT License.
  */
 
-import type { BTree } from "@tylerbu/sorted-btree-es6";
-import type {
-	ChangeAtomId,
-	ChangesetLocalId,
-	FieldKey,
-	FieldKindIdentifier,
-	RevisionInfo,
-	RevisionTag,
+import {
+	subtractChangeAtomIds,
+	type ChangeAtomId,
+	type ChangesetLocalId,
+	type FieldKey,
+	type FieldKindIdentifier,
+	type RevisionInfo,
+	type RevisionTag,
 } from "../../core/index.js";
-import type { Brand } from "../../util/index.js";
+import { brand, RangeMap, type Brand, type TupleBTree } from "../../util/index.js";
 import type { TreeChunk } from "../chunked-forest/index.js";
 import type { CrossFieldTarget } from "./crossFieldQueries.js";
 
@@ -71,25 +71,38 @@ export interface ModularChangeset extends HasFieldChanges {
 	readonly refreshers?: ChangeAtomIdBTree<TreeChunk>;
 }
 
-export type TupleBTree<K, V> = Brand<BTree<K, V>, "TupleBTree">;
 export type ChangeAtomIdBTree<V> = TupleBTree<[RevisionTag | undefined, ChangesetLocalId], V>;
-export type CrossFieldKeyTable = TupleBTree<CrossFieldKeyRange, FieldId>;
-export type CrossFieldKeyRange = readonly [
-	CrossFieldTarget,
-	RevisionTag | undefined,
-	ChangesetLocalId,
-	/**
-	 * The length of this range.
-	 * TODO: This does not need to be part of the key and could be part of the value instead.
-	 */
-	number,
-];
-
-export type CrossFieldKey = readonly [
-	CrossFieldTarget,
-	RevisionTag | undefined,
-	ChangesetLocalId,
-];
+
+export type CrossFieldKeyTable = RangeMap<CrossFieldKey, FieldId>;
+
+export function newCrossFieldKeyTable(): CrossFieldKeyTable {
+	return new RangeMap(offsetCrossFieldKey, subtractCrossFieldKeys);
+}
+
+function offsetCrossFieldKey(key: CrossFieldKey, offset: number): CrossFieldKey {
+	return {
+		...key,
+		localId: brand(key.localId + offset),
+	};
+}
+
+function subtractCrossFieldKeys(a: CrossFieldKey, b: CrossFieldKey): number {
+	const cmpTarget = a.target - b.target;
+	if (cmpTarget !== 0) {
+		return cmpTarget * Number.POSITIVE_INFINITY;
+	}
+
+	return subtractChangeAtomIds(a, b);
+}
+
+export interface CrossFieldKey extends ChangeAtomId {
+	readonly target: CrossFieldTarget;
+}
+
+export interface CrossFieldKeyRange {
+	key: CrossFieldKey;
+	count: number;
+}
 
 export interface FieldId {
 	readonly nodeId: NodeId | undefined;