@fluidframework/tree 2.91.0 → 2.92.0

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

@@ -51,14 +51,10 @@ import { BranchCommitEnricher } from "./branchCommitEnricher.js";
 import type { ChangeEnricher } from "./changeEnricher.js";
 import { DefaultResubmitMachine } from "./defaultResubmitMachine.js";
 import { EditManager, minimumPossibleSequenceNumber } from "./editManager.js";
-import { makeEditManagerCodec, type EditManagerCodecOptions } from "./editManagerCodecs.js";
+import { makeEditManagerCodecBuilder } from "./editManagerCodecs.js";
 import type { EditManagerFormatVersion, SeqNumber } from "./editManagerFormatCommons.js";
 import { EditManagerSummarizer } from "./editManagerSummarizer.js";
-import {
-	type MessageCodecOptions,
-	type MessageEncodingContext,
-	makeMessageCodec,
-} from "./messageCodecs.js";
+import { type MessageEncodingContext, makeMessageCodecBuilder } from "./messageCodecs.js";
 import type { MessageFormatVersion } from "./messageFormat.js";
 import type { DecodedMessage } from "./messageTypes.js";
 import type { ResubmitMachine } from "./resubmitMachine.js";
@@ -77,10 +73,7 @@ export interface ClonableSchemaAndPolicy extends SchemaAndPolicy {
 	schema: TreeStoredSchemaRepository;
 }
 
-export interface SharedTreeCoreOptionsInternal
-	extends CodecWriteOptions,
-		EditManagerCodecOptions,
-		MessageCodecOptions {}
+export interface SharedTreeCoreOptionsInternal extends CodecWriteOptions {}
 
 export interface EnrichmentConfig<TChange> {
 	readonly enricher: ChangeEnricher<TChange>;
@@ -186,12 +179,12 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 		this.registerSharedBranch("main");
 
 		const revisionTagCodec = new RevisionTagCodec(idCompressor);
-		const editManagerCodec = makeEditManagerCodec(
-			this.editManager.changeFamily.codecs,
-			changeFormatVersionForEditManager,
+		const editManagerCodec = makeEditManagerCodecBuilder<TChange>().build({
+			...options,
+			changeCodecs: this.editManager.changeFamily.codecs,
+			dependentChangeFormatVersion: changeFormatVersionForEditManager,
 			revisionTagCodec,
-			options,
-		);
+		});
 		this.summarizables = [
 			new EditManagerSummarizer(
 				this.editManager,
@@ -207,12 +200,12 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 			0x350 /* Index summary element keys must be unique */,
 		);
 
-		this.messageCodec = makeMessageCodec(
-			changeFamily.codecs,
-			changeFormatVersionForMessage,
-			new RevisionTagCodec(idCompressor),
-			options,
-		);
+		this.messageCodec = makeMessageCodecBuilder<TChange>().build({
+			...options,
+			changeCodecs: changeFamily.codecs,
+			dependentChangeFormatVersion: changeFormatVersionForMessage,
+			revisionTagCodec: new RevisionTagCodec(idCompressor),
+		});
 
 		if (enrichmentConfig !== undefined) {
 			this.registerSharedBranchForEditing(

package/src/sharedTreeAttributes.ts

@@ -12,6 +12,9 @@ import { pkgVersion } from "./packageVersion.js";
  * @beta
  * @legacy
  */
+// New type string, to be activated once the migration has been fully shipped dark and is safe to flip.
+// See LegacyTypeAwareRegistry in packages/runtime/datastore/src/dataStoreRuntime.ts.
+// export const SharedTreeFactoryType = "tree";
 export const SharedTreeFactoryType = "https://graph.microsoft.com/types/tree";
 
 /**

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

@@ -153,6 +153,16 @@ export {
 	TreeBeta,
 	type TreeChangeEventsBeta,
 } from "./treeBeta.js";
+export {
+	type ArrayNodeDeltaOp,
+	type ArrayNodeInsertOp,
+	type ArrayNodeRemoveOp,
+	type ArrayNodeRetainOp,
+	type NodeChangedDataAlpha,
+	type NodeChangedDataDelta,
+	type NodeChangedDataProperties,
+	type TreeChangeEventsAlpha,
+} from "./treeAlpha.js";
 export { createTreeIndex, type TreeIndexKey } from "./simpleTreeIndex.js";
 export {
 	createIdentifierIndex,

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

@@ -10,8 +10,6 @@ import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import type { TreeValue } from "../../core/index.js";
-// This import is required for intellisense in @link doc comments on mouseover in VSCode.
-// eslint-disable-next-line unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars
 import type { FlexTreeHydratedContextMinimal } from "../../feature-libraries/index.js";
 import {
 	type JsonCompatibleReadOnlyObject,

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

@@ -29,6 +29,7 @@ import {
 import type { LeafSchema } from "../leafNodeSchema.js";
 import {
 	type ArrayNodeCustomizableSchema,
+	type ArrayNodeCustomizableSchemaAlpha,
 	arraySchema,
 	type MapNodeCustomizableSchema,
 	mapSchema,
@@ -518,14 +519,24 @@ export class SchemaFactoryAlpha<
 		name: Name,
 		allowedTypes: T,
 		options?: NodeSchemaOptionsAlpha<TCustomMetadata>,
-	): ArrayNodeCustomizableSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> {
+	): ArrayNodeCustomizableSchemaAlpha<
+		ScopedSchemaName<TScope, Name>,
+		T,
+		true,
+		TCustomMetadata
+	> {
 		return arraySchema(
 			scoped<TScope, TName, Name>(this, name),
 			allowedTypes,
 			true,
 			true,
 			options ?? {},
-		);
+		) as unknown as ArrayNodeCustomizableSchemaAlpha<
+			ScopedSchemaName<TScope, Name>,
+			T,
+			true,
+			TCustomMetadata
+		>;
 	}
 
 	/**

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

@@ -5,17 +5,8 @@
 
 import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
 
-import {
-	FluidClientVersion,
-	FormatValidatorNoOp,
-	type ICodecOptions,
-} from "../../codec/index.js";
-import { SchemaFormatVersion } from "../../core/index.js";
-import { makeSchemaCodec } from "../../feature-libraries/index.js";
-import type {
-	FormatV1,
-	// eslint-disable-next-line import-x/no-internal-modules
-} from "../../feature-libraries/schema-index/index.js";
+import { FormatValidatorNoOp, type ICodecOptions } from "../../codec/index.js";
+import { schemaCodecBuilder } from "../../feature-libraries/index.js";
 import type { JsonCompatible } from "../../util/index.js";
 import type { SchemaUpgrade } from "../core/index.js";
 import { normalizeFieldSchema, type ImplicitFieldSchema } from "../fieldSchema.js";
@@ -63,7 +54,10 @@ export function extractPersistedSchema(
 	includeStaged: (upgrade: SchemaUpgrade) => boolean,
 ): JsonCompatible {
 	const stored = toStoredSchema(schema, { includeStaged });
-	const codec = makeSchemaCodec({ minVersionForCollab, jsonValidator: FormatValidatorNoOp });
+	const codec = schemaCodecBuilder.build({
+		minVersionForCollab,
+		jsonValidator: FormatValidatorNoOp,
+	});
 	return codec.encode(stored) as JsonCompatible;
 }
 
@@ -102,13 +96,8 @@ export function comparePersistedSchema(
 	view: ImplicitFieldSchema,
 	options: ICodecOptions,
 ): Omit<SchemaCompatibilityStatus, "canInitialize"> {
-	// Any version can be passed down to makeSchemaCodec here.
-	// We only use the decode part, which always dispatches to the correct codec based on the version in the data, not the version passed to `makeSchemaCodec`.
-	const schemaCodec = makeSchemaCodec(
-		{ ...options, minVersionForCollab: FluidClientVersion.v2_0 },
-		SchemaFormatVersion.v1,
-	);
-	const stored = schemaCodec.decode(persisted as FormatV1);
+	const schemaCodec = schemaCodecBuilder.buildDecoder(options);
+	const stored = schemaCodec.decode(persisted);
 	const config = new TreeViewConfigurationAlpha({
 		schema: normalizeFieldSchema(view),
 	});

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

@@ -136,6 +136,8 @@ export interface ITreeAlpha extends ITree {
  * @remarks A `TreeBranch` allows for the {@link TreeBranch.fork | creation of branches} and for those branches to later be {@link TreeBranch.merge | merged}.
  *
  * The branch associated directly with the {@link ITree | SharedTree} is the "main" branch, and all other branches fork (directly or transitively) from that main branch.
+ *
+ * See {@link TreeBranchAlpha} for additional APIs that are in an earlier stage of development.
  * @sealed @beta
  */
 export interface TreeBranch extends IDisposable {
@@ -352,6 +354,8 @@ export interface TreeBranchAlpha extends TreeBranch, TreeContextAlpha {
  * Application authors are encouraged to read {@link https://github.com/microsoft/FluidFramework/blob/main/packages/dds/tree/docs/user-facing/schema-evolution.md | schema-evolution.md}
  * and choose a schema compatibility policy that aligns with their application's needs.
  *
+ * See also {@link TreeViewAlpha}, {@link TreeViewBeta} and {@link TreeBranch} for additional APIs that are in earlier stages of development.
+ *
  * @privateRemarks
  * From an API design perspective, `upgradeSchema` could be merged into `viewWith` and/or `viewWith` could return errors explicitly on incompatible documents.
  * Such approaches would make it discoverable that out of schema handling may need to be done.
@@ -559,7 +563,7 @@ export interface SchemaCompatibilityStatus {
  * Events for {@link TreeBranch}.
  * @sealed @alpha
  */
-export interface TreeBranchEvents extends Omit<TreeViewEvents, "commitApplied"> {
+export interface TreeBranchEvents {
 	/**
 	 * Fired when a change is made to the branch. Includes data about the change that is made which listeners
 	 * can use to filter on changes they care about (e.g. local vs. remote changes).
@@ -569,29 +573,12 @@ export interface TreeBranchEvents extends Omit<TreeViewEvents, "commitApplied">
 	 * this change is not revertible.
 	 */
 	changed(data: ChangeMetadata, getRevertible?: RevertibleAlphaFactory): void;
-
-	/**
-	 * Fired when:
-	 *
-	 * - a local commit is applied outside of a transaction
-	 *
-	 * - a local transaction is committed
-	 *
-	 * The event is not fired when:
-	 *
-	 * - a local commit is applied within a transaction
-	 *
-	 * - a remote commit is applied
-	 *
-	 * @param data - information about the commit that was applied
-	 * @param getRevertible - a function provided that allows users to get a revertible for the commit that was applied. If not provided,
-	 * this commit is not revertible.
-	 */
-	commitApplied(data: ChangeMetadata, getRevertible?: RevertibleAlphaFactory): void;
 }
 
 /**
  * Events for {@link TreeView}.
+ * @remarks
+ * See {@link TreeBranchEvents} for more events related to the underlying branch of the SharedTree.
  * @sealed @public
  */
 export interface TreeViewEvents {

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

@@ -0,0 +1,90 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { NodeKind, TreeNode, WithType } from "../core/index.js";
+
+import type { TreeChangeEvents } from "./treeChangeEvents.js";
+export type {
+	ArrayNodeDeltaOp,
+	ArrayNodeInsertOp,
+	ArrayNodeRemoveOp,
+	ArrayNodeRetainOp,
+} from "./treeNodeApi.js";
+import type { ArrayNodeDeltaOp } from "./treeNodeApi.js";
+
+/**
+ * Data included for {@link TreeChangeEventsAlpha.nodeChanged} when the node is an object, map, or record node.
+ * @sealed @alpha
+ */
+export interface NodeChangedDataProperties<TNode extends TreeNode = TreeNode> {
+	/**
+	 * Lists all the properties which changed on the node.
+	 * @remarks
+	 * This only includes changes to the node itself (which would trigger {@link TreeChangeEvents.nodeChanged}).
+	 *
+	 * The set should never be empty, since `nodeChanged` will only be triggered when there is a change, and for the supported node types, the only things that can change are properties.
+	 */
+	readonly changedProperties: ReadonlySet<
+		// For Object nodes, strongly type with the property names from the schema:
+		TNode extends WithType<string, NodeKind.Object, infer TInfo>
+			? string & keyof TInfo
+			: string
+	>;
+}
+
+/**
+ * Data included for {@link TreeChangeEventsAlpha.nodeChanged} when the node is an array node.
+ * @sealed @alpha
+ */
+export interface NodeChangedDataDelta {
+	/**
+	 * The sequential operations describing what changed in the array node.
+	 * @remarks
+	 * The value may be `undefined` in two cases:
+	 * - The node was created locally and has not yet been inserted into a document tree (a known
+	 * temporary limitation, tracked in AB#63261).
+	 * - The document was updated in a way that required multiple internal change passes in a single
+	 * operation (for example, a data change combined with a schema upgrade).
+	 *
+	 * See {@link ArrayNodeDeltaOp} for op semantics.
+	 */
+	readonly delta: readonly ArrayNodeDeltaOp[] | undefined;
+}
+
+/**
+ * The data passed to {@link TreeChangeEventsAlpha.nodeChanged}.
+ * @remarks
+ * - For array nodes: {@link NodeChangedDataDelta} (includes a {@link NodeChangedDataDelta.delta | delta} payload).
+ * - For object, map, and record nodes: {@link NodeChangedDataProperties} (includes {@link NodeChangedDataProperties.changedProperties | changedProperties}).
+ * - For a generic/unknown node type: the union of both.
+ * @alpha
+ */
+export type NodeChangedDataAlpha<TNode extends TreeNode = TreeNode> =
+	TNode extends WithType<string, NodeKind.Array>
+		? NodeChangedDataDelta
+		: TNode extends WithType<string, NodeKind.Map | NodeKind.Object | NodeKind.Record>
+			? NodeChangedDataProperties<TNode>
+			: NodeChangedDataProperties<TNode> | NodeChangedDataDelta;
+
+/**
+ * Extension of {@link TreeChangeEvents} with a richer `nodeChanged` event.
+ * @remarks
+ * Provides a `nodeChanged` event that includes a delta payload for array nodes and
+ * requires `changedProperties` for object, map, and record nodes.
+ * Use via `TreeAlpha.on`.
+ * @sealed @alpha
+ */
+export interface TreeChangeEventsAlpha<TNode extends TreeNode = TreeNode>
+	extends TreeChangeEvents {
+	/**
+	 * Like `TreeChangeEventsBeta.nodeChanged`, but for array nodes the event data includes
+	 * a {@link NodeChangedDataDelta.delta | delta} payload describing the changes as a sequence
+	 * of {@link ArrayNodeDeltaOp} values.
+	 *
+	 * @remarks
+	 * This defines a property which is a function instead of using the method syntax to avoid function bi-variance issues with the input data to the callback.
+	 */
+	nodeChanged: (data: NodeChangedDataAlpha<TNode>) => void;
+}

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

@@ -54,7 +54,7 @@ export interface NodeChangedData<TNode extends TreeNode = TreeNode> {
 	 * @remarks
 	 * This only includes changes to the node itself (which would trigger {@link TreeChangeEvents.nodeChanged}).
 	 *
-	 * Set to `undefined` when the {@link NodeKind} does not support this feature (currently just ArrayNodes).
+	 * Not present when the {@link NodeKind} does not support this feature (currently just ArrayNodes).
 	 *
 	 * When defined, the set should never be empty, since `nodeChanged` will only be triggered when there is a change, and for the supported node types, the only things that can change are properties.
 	 */

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

@@ -6,6 +6,9 @@
 /**
  * A collection of events that can be emitted by a {@link TreeNode}.
  *
+ * @remarks
+ * Access these events via the {@link (Tree:variable)}'s {@link TreeNodeApi.on} method.
+ *
  * @privateRemarks
  * TODO: add a way to subscribe to a specific field (for nodeChanged and treeChanged).
  * Probably have object node and map node specific APIs for this.

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

@@ -8,7 +8,7 @@ import { assert, oob, fail, unreachableCase } from "@fluidframework/core-utils/i
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import { EmptyKey, rootFieldKey } from "../../core/index.js";
+import { EmptyKey, rootFieldKey, type DeltaMark } from "../../core/index.js";
 import { type TreeStatus, isTreeValue, FieldKinds } from "../../feature-libraries/index.js";
 import { extractFromOpaque } from "../../util/index.js";
 import {
@@ -39,6 +39,56 @@ import { isArrayNodeSchema, isObjectNodeSchema } from "../node-kinds/index.js";
 
 import type { TreeChangeEvents } from "./treeChangeEvents.js";
 
+/**
+ * A `"retain"` op in an {@link ArrayNodeDeltaOp} sequence.
+ * Represents elements that were not added or removed (though they may have nested changes).
+ * @sealed @alpha
+ */
+export interface ArrayNodeRetainOp {
+	readonly type: "retain";
+	readonly count: number;
+}
+
+/**
+ * An `"insert"` op in an {@link ArrayNodeDeltaOp} sequence.
+ * Represents elements added to the array.
+ * Read the new element values from the current tree at the positions described by this op.
+ * @sealed @alpha
+ */
+export interface ArrayNodeInsertOp {
+	readonly type: "insert";
+	readonly count: number;
+}
+
+/**
+ * A `"remove"` op in an {@link ArrayNodeDeltaOp} sequence.
+ * Represents elements removed from the array.
+ * @sealed @alpha
+ */
+export interface ArrayNodeRemoveOp {
+	readonly type: "remove";
+	readonly count: number;
+}
+
+/**
+ * A single operation in an array node change delta. Used to efficiently sync an external
+ * representation of an array (e.g. a text editor or virtual list) with tree changes without
+ * needing to snapshot the old state or diff the entire array. Each op describes a contiguous run
+ * of positions in the array before the change. For inserts, read the new element values from the
+ * current tree at those positions.
+ *
+ * @remarks
+ * There is no dedicated `"move"` op. Moves are represented as `"remove"` + `"insert"`.
+ * When an element is moved within the same array it appears
+ * as a `"remove"` at the source position followed by an `"insert"` at the destination position.
+ * When an element is moved across two different arrays, the source array's delta contains a
+ * `"remove"` and the destination array's delta contains an `"insert"` — they cannot be
+ * correlated without additional bookkeeping on the caller's side.
+ *
+ * @sealed @alpha
+ */
+export type ArrayNodeDeltaOp = ArrayNodeRetainOp | ArrayNodeInsertOp | ArrayNodeRemoveOp;
+
 /**
  * Provides various functions for analyzing {@link TreeNode}s.
  *
@@ -105,6 +155,9 @@ export interface TreeNodeApi {
 	 * @param listener - The callback to trigger for the event. The tree can be read during the callback, but it is invalid to modify the tree during this callback.
 	 * @returns A callback function which will deregister the event.
 	 * This callback should be called only once.
+	 * @remarks
+	 * The returned unsubscribe function should be called any time the need for the `listener` callback ends before the node is {@link TreeStatus.Deleted | deleted} (Not just {@link TreeStatus.Removed | removed}).
+	 * Doing so removes the overhead of tracking and triggering the event, and also avoids leaking any memory retained by the callback.
 	 */
 	on<K extends keyof TreeChangeEvents>(
 		node: TreeNode,
@@ -192,8 +245,17 @@ export const treeNodeApi: TreeNodeApi = {
 						listener({ changedProperties });
 					});
 				} else if (isArrayNodeSchema(nodeSchema)) {
-					return kernel.events.on("childrenChangedAfterBatch", () => {
-						listener({ changedProperties: undefined });
+					return kernel.events.on("childrenChangedAfterBatch", ({ fieldMarks }) => {
+						const marks = fieldMarks.get(EmptyKey);
+						// `marks` is undefined when the field was modified across multiple batches
+						// within a single flush (e.g. due to an interleaved schema change) and the
+						// marks could not be composed. Emit `undefined` so callers know the delta is
+						// unavailable rather than receiving stale marks from only the first batch.
+						// TODO: Once the eventing stack is rewritten to walk the composed delta at
+						// flush time, `marks` will always be defined. Remove the `undefined` fallback
+						// and simplify to: `const delta = deltaMarksToArrayOps(marks);`
+						const delta = marks === undefined ? undefined : deltaMarksToArrayOps(marks);
+						listener({ delta });
 					});
 				} else {
 					return kernel.events.on("childrenChangedAfterBatch", ({ changedFields }) => {
@@ -234,6 +296,36 @@ export const treeNodeApi: TreeNodeApi = {
 	},
 };
 
+/**
+ * Converts an array of internal {@link DeltaMark}s for a sequence field into sequential
+ * array delta ops suitable for inclusion in {@link NodeChangedData.delta}.
+ *
+ * Each mark in the delta describes a contiguous run of positions in the original array:
+ * - A mark with only `count` (no attach/detach) → `"retain"` (elements unchanged at this level)
+ * - A mark with only `attach` → `"insert"` (new elements added)
+ * - A mark with only `detach` → `"remove"` (elements removed)
+ * - A mark with both `attach` and `detach` → `"remove"` + `"insert"`
+ *
+ * @privateRemarks
+ * The case where both `attach` and `detach` are set is unreachable today: the sequence-field
+ * encoder never emits such marks for array (EmptyKey) fields. It is handled defensively.
+ */
+function deltaMarksToArrayOps(marks: readonly DeltaMark[]): ArrayNodeDeltaOp[] {
+	const ops: ArrayNodeDeltaOp[] = [];
+	for (const mark of marks) {
+		if (mark.detach !== undefined) {
+			ops.push({ type: "remove", count: mark.count });
+		}
+		if (mark.attach !== undefined) {
+			ops.push({ type: "insert", count: mark.count });
+		} else if (mark.detach === undefined) {
+			// Neither attach nor detach: elements retained (may have nested changes in mark.fields).
+			ops.push({ type: "retain", count: mark.count });
+		}
+	}
+	return ops;
+}
+
 /**
  * Returns a schema for a value if the value is a {@link TreeNode} or a {@link TreeLeafValue}.
  * Returns undefined for other values.

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

@@ -17,6 +17,7 @@ import {
 	anchorSlot,
 	type AnchorEvents,
 	type AnchorNode,
+	type DeltaMark,
 	type FieldKey,
 	type TreeValue,
 } from "../../core/index.js";
@@ -362,6 +363,20 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 	 */
 	readonly #childrenChangedBuffer: Set<FieldKey> = new Set();
 
+	/**
+	 * Buffer of field marks accumulated since events were paused.
+	 * Emitted alongside the buffered changed-fields set when flushed.
+	 */
+	readonly #fieldMarksBuffer: Map<FieldKey, readonly DeltaMark[]> = new Map();
+
+	/**
+	 * Fields whose marks have been permanently invalidated within the current buffer window due to
+	 * two or more separate delta batches touching the same field.
+	 * Once a key is in this set it must never be re-added to the marks buffer, even if
+	 * a third (or later) batch arrives for that field.
+	 */
+	readonly #invalidatedFieldMarkKeys: Set<FieldKey> = new Set();
+
 	/**
 	 * Whether or not the subtree has changed since events were paused.
 	 * When events are flushed, a single {@link AnchorEvents.subTreeChanged} event will be emitted if and only
@@ -399,8 +414,10 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 		this.#eventSource = newSource;
 
 		if (this.#events.hasListeners("childrenChangedAfterBatch")) {
-			const off = this.#eventSource.on("childrenChangedAfterBatch", ({ changedFields }) =>
-				this.#emit("childrenChangedAfterBatch", { changedFields }),
+			const off = this.#eventSource.on(
+				"childrenChangedAfterBatch",
+				({ changedFields, fieldMarks }) =>
+					this.#emit("childrenChangedAfterBatch", { changedFields, fieldMarks }),
 			);
 			this.#disposeSourceListeners.set("childrenChangedAfterBatch", off);
 		}
@@ -421,7 +438,10 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 				0xc4f /* Should not have a dispose function without listeners */,
 			);
 
-			const off = this.#eventSource.on(eventName, (args) => this.#emit(eventName, args));
+			const off: Off =
+				eventName === "childrenChangedAfterBatch"
+					? this.#eventSource.on(eventName, (args) => this.#emit(eventName, args))
+					: this.#eventSource.on(eventName, () => this.#emit(eventName));
 			this.#disposeSourceListeners.set(eventName, off);
 		}
 
@@ -444,13 +464,14 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 		eventName: keyof KernelEvents,
 		arg?: {
 			changedFields: ReadonlySet<FieldKey>;
+			fieldMarks: ReadonlyMap<FieldKey, readonly DeltaMark[]>;
 		},
 	): void {
 		this.#assertNotDisposed();
 		switch (eventName) {
 			case "childrenChangedAfterBatch": {
-				assert(arg !== undefined, 0xc50 /* childrenChangedAfterBatch should have arg */);
-				return this.#handleChildrenChangedAfterBatch(arg.changedFields);
+				assert(arg !== undefined, 0xcea /* childrenChangedAfterBatch requires arg */);
+				return this.#handleChildrenChangedAfterBatch(arg.changedFields, arg.fieldMarks);
 			}
 			case "subtreeChangedAfterBatch": {
 				return this.#handleSubtreeChangedAfterBatch();
@@ -461,13 +482,33 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 		}
 	}
 
-	#handleChildrenChangedAfterBatch(changedFields: ReadonlySet<FieldKey>): void {
+	#handleChildrenChangedAfterBatch(
+		changedFields: ReadonlySet<FieldKey>,
+		fieldMarks: ReadonlyMap<FieldKey, readonly DeltaMark[]>,
+	): void {
 		if (bufferTreeEvents) {
 			for (const fieldKey of changedFields) {
 				this.#childrenChangedBuffer.add(fieldKey);
 			}
+			for (const [key, marks] of fieldMarks) {
+				if (this.#invalidatedFieldMarkKeys.has(key)) {
+					// Already permanently invalidated by an earlier collision; ignore this batch too.
+					// TODO: Once the eventing stack is rewritten to walk the composed delta at flush
+					// time, this collision path will be unreachable and can be removed entirely.
+					continue;
+				}
+				if (this.#fieldMarksBuffer.has(key)) {
+					// A second batch of marks arrived for the same field before the buffer was flushed.
+					// We have no delta composition logic, so permanently invalidate this field so that
+					// any further batches are also discarded rather than incorrectly surfaced.
+					this.#fieldMarksBuffer.delete(key);
+					this.#invalidatedFieldMarkKeys.add(key);
+				} else {
+					this.#fieldMarksBuffer.set(key, marks);
+				}
+			}
 		} else {
-			this.#events.emit("childrenChangedAfterBatch", { changedFields });
+			this.#events.emit("childrenChangedAfterBatch", { changedFields, fieldMarks });
 		}
 	}
 
@@ -488,8 +529,11 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 		if (this.#childrenChangedBuffer.size > 0) {
 			this.#events.emit("childrenChangedAfterBatch", {
 				changedFields: this.#childrenChangedBuffer,
+				fieldMarks: this.#fieldMarksBuffer,
 			});
 			this.#childrenChangedBuffer.clear();
+			this.#fieldMarksBuffer.clear();
+			this.#invalidatedFieldMarkKeys.clear();
 		}
 
 		if (this.#subTreeChangedBuffer) {
@@ -519,6 +563,8 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 		this.#disposeSourceListeners.clear();
 
 		this.#childrenChangedBuffer.clear();
+		this.#fieldMarksBuffer.clear();
+		this.#invalidatedFieldMarkKeys.clear();
 		this.#subTreeChangedBuffer = false;
 
 		this.#disposed = true;

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

@@ -271,7 +271,11 @@ export class UnhydratedFlexTreeNode
 	}
 
 	public emitChangedEvent(key: FieldKey): void {
-		this._events.emit("childrenChangedAfterBatch", { changedFields: new Set([key]) });
+		this._events.emit("childrenChangedAfterBatch", {
+			changedFields: new Set([key]),
+			// Unhydrated nodes are not visited by the delta pipeline, so no field marks are available.
+			fieldMarks: new Map(),
+		});
 
 		// Also emit subtree changed event for this node and all ancestors.
 		this.#emitSubtreeChangedEvents();

package/src/simple-tree/index.ts

@@ -91,12 +91,20 @@ export {
 	singletonSchema,
 	treeNodeApi,
 	type TreeNodeApi,
+	type ArrayNodeDeltaOp,
+	type ArrayNodeInsertOp,
+	type ArrayNodeRemoveOp,
+	type ArrayNodeRetainOp,
 	type NodeChangedData,
+	type NodeChangedDataAlpha,
+	type NodeChangedDataDelta,
+	type NodeChangedDataProperties,
 	borrowCursorFromTreeNodeOrValue,
 	exportConcise,
 	importConcise,
 	TreeBeta,
 	type TreeChangeEventsBeta,
+	type TreeChangeEventsAlpha,
 	type IdentifierIndex,
 	createTreeIndex,
 	createIdentifierIndex,
@@ -248,6 +256,7 @@ export {
 export { tryGetTreeNodeForField } from "./getTreeNodeForField.js";
 export {
 	type ArrayNodeCustomizableSchema,
+	type ArrayNodeCustomizableSchemaAlpha,
 	type ArrayNodePojoEmulationSchema,
 	ArrayNodeSchema,
 	asIndex,
@@ -255,6 +264,7 @@ export {
 	IterableTreeArrayContent,
 	type ReadonlyArrayNode,
 	TreeArrayNode,
+	type TreeArrayNodeAlpha,
 	type MapNodeCustomizableSchema,
 	type MapNodePojoEmulationSchema,
 	MapNodeSchema,