@fluidframework/merge-tree 1.1.0 → 1.2.0

package/lib/mergeTreeDeltaCallback.d.ts

@@ -7,14 +7,31 @@ import { IMergeTreeGroupMsg, IMergeTreeOp, MergeTreeDeltaType } from "./ops";
 import { PropertySet } from "./properties";
 import { ISegment } from "./mergeTree";
 export declare type MergeTreeDeltaOperationType = typeof MergeTreeDeltaType.ANNOTATE | typeof MergeTreeDeltaType.INSERT | typeof MergeTreeDeltaType.REMOVE;
+/**
+ * Enum-like constant defining the types of "maintenance" events on a merge tree.
+ * Maintenance events correspond to structural segment changes or acks of pending segments.
+ *
+ * Note: these values are assigned negative integers to avoid clashing with `MergeTreeDeltaType`.
+ */
 export declare const MergeTreeMaintenanceType: {
+    /**
+     * Notification that a segment "append" has occurred, i.e. two adjacent segments have been merged.
+     * BEWARE: `deltaSegments` on the corresponding event will contain both the merged segment and the latter
+     * segment, pre-merge.
+     * For example, if the merge tree originally had two adjacent segments [A][B] and called A.append(B) to get
+     * segment [AB], `deltaSegments` would contain [AB] and [B].
+     */
     readonly APPEND: -1;
+    /**
+     * Notification that a segment has been split in two.
+     * `deltaSegments` on the corresponding event will contain the resulting two segments.
+     */
     readonly SPLIT: -2;
     /**
-     * Notification that a segment has been unlinked from the MergeTree.  This occurs during
-     * Zamboni when:
-     *
-     *    b) The segment's tracking collection is empty (e.g., not being tracked for undo/redo).
+     * Notification that a segment has been unlinked (i.e. removed) from the MergeTree.
+     * This occurs on leaf segments during Zamboni when the segment's tracking collection is empty
+     * (e.g., not being tracked for undo/redo).
+     * It also occurs on internal merge tree segments when re-packing children to maintain tree balancing invariants.
      */
     readonly UNLINK: -3;
     /**

package/lib/mergeTreeDeltaCallback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mergeTreeDeltaCallback.d.ts","sourceRoot":"","sources":["../src/mergeTreeDeltaCallback.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,yBAAyB,EAAE,MAAM,sCAAsC,CAAC;AACjF,OAAO,EACH,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EACrB,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,oBAAY,2BAA2B,GACnC,OAAO,kBAAkB,CAAC,QAAQ,GAAG,OAAO,kBAAkB,CAAC,MAAM,GAAG,OAAO,kBAAkB,CAAC,MAAM,CAAC;AAG7G,eAAO,MAAM,wBAAwB;;;IAGjC;;;;;OAKG;;IAEH;;;OAGG;;CAEG,CAAC;AACX,oBAAY,wBAAwB,GAAG,OAAO,wBAAwB,CAAC,MAAM,OAAO,wBAAwB,CAAC,CAAC;AAE9G,oBAAY,4BAA4B,GAAG,2BAA2B,GAAG,wBAAwB,CAAC;AAGlG,MAAM,WAAW,2BAA2B,CAAC,cAAc,SAAS,4BAA4B,GAAG,2BAA2B;IAC1H,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,sBAAsB,EAAE,CAAC;CACpD;AAED,MAAM,WAAW,sBAAsB;IACnC,OAAO,EAAE,QAAQ,CAAC;IAClB,cAAc,CAAC,EAAE,WAAW,CAAC;CAChC;AAED,MAAM,WAAW,qBAAqB;IAClC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;IACtC;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,yBAAyB,CAAC;CACzD;AAED,MAAM,WAAW,4BAA4B;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACnC;AAED,oBAAY,sBAAsB,GAC9B,CAAC,MAAM,EAAE,qBAAqB,EAAE,SAAS,EAAE,2BAA2B,KAAK,IAAI,CAAC;AAGpF,MAAM,WAAW,iCAAkC,SAAQ,2BAA2B,CAAC,wBAAwB,CAAC;CAAI;AAEpH,oBAAY,4BAA4B,GACpC,CAAC,eAAe,EAAE,iCAAiC,EAAE,MAAM,EAAE,qBAAqB,GAAG,SAAS,KAAK,IAAI,CAAC"}
+{"version":3,"file":"mergeTreeDeltaCallback.d.ts","sourceRoot":"","sources":["../src/mergeTreeDeltaCallback.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,yBAAyB,EAAE,MAAM,sCAAsC,CAAC;AACjF,OAAO,EACH,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EACrB,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,oBAAY,2BAA2B,GACnC,OAAO,kBAAkB,CAAC,QAAQ,GAAG,OAAO,kBAAkB,CAAC,MAAM,GAAG,OAAO,kBAAkB,CAAC,MAAM,CAAC;AAE7G;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;IACjC;;;;;;OAMG;;IAEH;;;OAGG;;IAEH;;;;;OAKG;;IAEH;;;OAGG;;CAEG,CAAC;AACX,oBAAY,wBAAwB,GAAG,OAAO,wBAAwB,CAAC,MAAM,OAAO,wBAAwB,CAAC,CAAC;AAE9G,oBAAY,4BAA4B,GAAG,2BAA2B,GAAG,wBAAwB,CAAC;AAGlG,MAAM,WAAW,2BAA2B,CAAC,cAAc,SAAS,4BAA4B,GAAG,2BAA2B;IAC1H,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,sBAAsB,EAAE,CAAC;CACpD;AAED,MAAM,WAAW,sBAAsB;IACnC,OAAO,EAAE,QAAQ,CAAC;IAClB,cAAc,CAAC,EAAE,WAAW,CAAC;CAChC;AAED,MAAM,WAAW,qBAAqB;IAClC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;IACtC;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,yBAAyB,CAAC;CACzD;AAED,MAAM,WAAW,4BAA4B;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACnC;AAED,oBAAY,sBAAsB,GAC9B,CAAC,MAAM,EAAE,qBAAqB,EAAE,SAAS,EAAE,2BAA2B,KAAK,IAAI,CAAC;AAGpF,MAAM,WAAW,iCAAkC,SAAQ,2BAA2B,CAAC,wBAAwB,CAAC;CAAI;AAEpH,oBAAY,4BAA4B,GACpC,CAAC,eAAe,EAAE,iCAAiC,EAAE,MAAM,EAAE,qBAAqB,GAAG,SAAS,KAAK,IAAI,CAAC"}

package/lib/mergeTreeDeltaCallback.js

@@ -2,15 +2,31 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-// Note: Assigned negative integers to avoid clashing with MergeTreeDeltaType
+/**
+ * Enum-like constant defining the types of "maintenance" events on a merge tree.
+ * Maintenance events correspond to structural segment changes or acks of pending segments.
+ *
+ * Note: these values are assigned negative integers to avoid clashing with `MergeTreeDeltaType`.
+ */
 export const MergeTreeMaintenanceType = {
+    /**
+     * Notification that a segment "append" has occurred, i.e. two adjacent segments have been merged.
+     * BEWARE: `deltaSegments` on the corresponding event will contain both the merged segment and the latter
+     * segment, pre-merge.
+     * For example, if the merge tree originally had two adjacent segments [A][B] and called A.append(B) to get
+     * segment [AB], `deltaSegments` would contain [AB] and [B].
+     */
     APPEND: -1,
+    /**
+     * Notification that a segment has been split in two.
+     * `deltaSegments` on the corresponding event will contain the resulting two segments.
+     */
     SPLIT: -2,
     /**
-     * Notification that a segment has been unlinked from the MergeTree.  This occurs during
-     * Zamboni when:
-     *
-     *    b) The segment's tracking collection is empty (e.g., not being tracked for undo/redo).
+     * Notification that a segment has been unlinked (i.e. removed) from the MergeTree.
+     * This occurs on leaf segments during Zamboni when the segment's tracking collection is empty
+     * (e.g., not being tracked for undo/redo).
+     * It also occurs on internal merge tree segments when re-packing children to maintain tree balancing invariants.
      */
     UNLINK: -3,
     /**

package/lib/mergeTreeDeltaCallback.js.map

@@ -1 +1 @@
-{"version":3,"file":"mergeTreeDeltaCallback.js","sourceRoot":"","sources":["../src/mergeTreeDeltaCallback.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAcH,6EAA6E;AAC7E,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACpC,MAAM,EAAE,CAAC,CAAC;IACV,KAAK,EAAE,CAAC,CAAC;IACT;;;;;OAKG;IACH,MAAM,EAAE,CAAC,CAAC;IACV;;;OAGG;IACH,YAAY,EAAE,CAAC,CAAC;CACV,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { ISequencedDocumentMessage } from \"@fluidframework/protocol-definitions\";\nimport {\n    IMergeTreeGroupMsg,\n    IMergeTreeOp,\n    MergeTreeDeltaType,\n} from \"./ops\";\nimport { PropertySet } from \"./properties\";\nimport { ISegment } from \"./mergeTree\";\n\nexport type MergeTreeDeltaOperationType =\n    typeof MergeTreeDeltaType.ANNOTATE | typeof MergeTreeDeltaType.INSERT | typeof MergeTreeDeltaType.REMOVE;\n\n// Note: Assigned negative integers to avoid clashing with MergeTreeDeltaType\nexport const MergeTreeMaintenanceType = {\n    APPEND: -1,\n    SPLIT: -2,\n    /**\n     * Notification that a segment has been unlinked from the MergeTree.  This occurs during\n     * Zamboni when:\n     *\n     *    b) The segment's tracking collection is empty (e.g., not being tracked for undo/redo).\n     */\n    UNLINK: -3,\n    /**\n     * Notification that a local change has been acknowledged by the server.\n     * This means that it has made the round trip to the server and has had a sequence number assigned.\n     */\n    ACKNOWLEDGED: -4,\n} as const;\nexport type MergeTreeMaintenanceType = typeof MergeTreeMaintenanceType[keyof typeof MergeTreeMaintenanceType];\n\nexport type MergeTreeDeltaOperationTypes = MergeTreeDeltaOperationType | MergeTreeMaintenanceType;\n\n// eslint-disable-next-line max-len\nexport interface IMergeTreeDeltaCallbackArgs<TOperationType extends MergeTreeDeltaOperationTypes = MergeTreeDeltaOperationType> {\n    readonly operation: TOperationType;\n    readonly deltaSegments: IMergeTreeSegmentDelta[];\n}\n\nexport interface IMergeTreeSegmentDelta {\n    segment: ISegment;\n    propertyDeltas?: PropertySet;\n}\n\nexport interface IMergeTreeDeltaOpArgs {\n    /**\n     * The group op which contains the operation\n     * if there operation is part of a group op.\n     */\n    readonly groupOp?: IMergeTreeGroupMsg;\n    /**\n     * The merge tree operation\n     */\n    readonly op: IMergeTreeOp;\n    /**\n     * Get the sequence message, should only be null if the\n     * Delta op args are for an unacked local change\n     */\n    readonly sequencedMessage?: ISequencedDocumentMessage;\n}\n\nexport interface IMergeTreeClientSequenceArgs {\n    readonly clientId: number;\n    readonly referenceSequenceNumber: number;\n    readonly sequenceNumber: number;\n}\n\nexport type MergeTreeDeltaCallback =\n    (opArgs: IMergeTreeDeltaOpArgs, deltaArgs: IMergeTreeDeltaCallbackArgs) => void;\n\n// eslint-disable-next-line @typescript-eslint/no-empty-interface\nexport interface IMergeTreeMaintenanceCallbackArgs extends IMergeTreeDeltaCallbackArgs<MergeTreeMaintenanceType> { }\n\nexport type MergeTreeMaintenanceCallback =\n    (MaintenanceArgs: IMergeTreeMaintenanceCallbackArgs, opArgs: IMergeTreeDeltaOpArgs | undefined) => void;\n"]}
+{"version":3,"file":"mergeTreeDeltaCallback.js","sourceRoot":"","sources":["../src/mergeTreeDeltaCallback.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAcH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACpC;;;;;;OAMG;IACH,MAAM,EAAE,CAAC,CAAC;IACV;;;OAGG;IACH,KAAK,EAAE,CAAC,CAAC;IACT;;;;;OAKG;IACH,MAAM,EAAE,CAAC,CAAC;IACV;;;OAGG;IACH,YAAY,EAAE,CAAC,CAAC;CACV,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { ISequencedDocumentMessage } from \"@fluidframework/protocol-definitions\";\nimport {\n    IMergeTreeGroupMsg,\n    IMergeTreeOp,\n    MergeTreeDeltaType,\n} from \"./ops\";\nimport { PropertySet } from \"./properties\";\nimport { ISegment } from \"./mergeTree\";\n\nexport type MergeTreeDeltaOperationType =\n    typeof MergeTreeDeltaType.ANNOTATE | typeof MergeTreeDeltaType.INSERT | typeof MergeTreeDeltaType.REMOVE;\n\n/**\n * Enum-like constant defining the types of \"maintenance\" events on a merge tree.\n * Maintenance events correspond to structural segment changes or acks of pending segments.\n *\n * Note: these values are assigned negative integers to avoid clashing with `MergeTreeDeltaType`.\n */\nexport const MergeTreeMaintenanceType = {\n    /**\n     * Notification that a segment \"append\" has occurred, i.e. two adjacent segments have been merged.\n     * BEWARE: `deltaSegments` on the corresponding event will contain both the merged segment and the latter\n     * segment, pre-merge.\n     * For example, if the merge tree originally had two adjacent segments [A][B] and called A.append(B) to get\n     * segment [AB], `deltaSegments` would contain [AB] and [B].\n     */\n    APPEND: -1,\n    /**\n     * Notification that a segment has been split in two.\n     * `deltaSegments` on the corresponding event will contain the resulting two segments.\n     */\n    SPLIT: -2,\n    /**\n     * Notification that a segment has been unlinked (i.e. removed) from the MergeTree.\n     * This occurs on leaf segments during Zamboni when the segment's tracking collection is empty\n     * (e.g., not being tracked for undo/redo).\n     * It also occurs on internal merge tree segments when re-packing children to maintain tree balancing invariants.\n     */\n    UNLINK: -3,\n    /**\n     * Notification that a local change has been acknowledged by the server.\n     * This means that it has made the round trip to the server and has had a sequence number assigned.\n     */\n    ACKNOWLEDGED: -4,\n} as const;\nexport type MergeTreeMaintenanceType = typeof MergeTreeMaintenanceType[keyof typeof MergeTreeMaintenanceType];\n\nexport type MergeTreeDeltaOperationTypes = MergeTreeDeltaOperationType | MergeTreeMaintenanceType;\n\n// eslint-disable-next-line max-len\nexport interface IMergeTreeDeltaCallbackArgs<TOperationType extends MergeTreeDeltaOperationTypes = MergeTreeDeltaOperationType> {\n    readonly operation: TOperationType;\n    readonly deltaSegments: IMergeTreeSegmentDelta[];\n}\n\nexport interface IMergeTreeSegmentDelta {\n    segment: ISegment;\n    propertyDeltas?: PropertySet;\n}\n\nexport interface IMergeTreeDeltaOpArgs {\n    /**\n     * The group op which contains the operation\n     * if there operation is part of a group op.\n     */\n    readonly groupOp?: IMergeTreeGroupMsg;\n    /**\n     * The merge tree operation\n     */\n    readonly op: IMergeTreeOp;\n    /**\n     * Get the sequence message, should only be null if the\n     * Delta op args are for an unacked local change\n     */\n    readonly sequencedMessage?: ISequencedDocumentMessage;\n}\n\nexport interface IMergeTreeClientSequenceArgs {\n    readonly clientId: number;\n    readonly referenceSequenceNumber: number;\n    readonly sequenceNumber: number;\n}\n\nexport type MergeTreeDeltaCallback =\n    (opArgs: IMergeTreeDeltaOpArgs, deltaArgs: IMergeTreeDeltaCallbackArgs) => void;\n\n// eslint-disable-next-line @typescript-eslint/no-empty-interface\nexport interface IMergeTreeMaintenanceCallbackArgs extends IMergeTreeDeltaCallbackArgs<MergeTreeMaintenanceType> { }\n\nexport type MergeTreeMaintenanceCallback =\n    (MaintenanceArgs: IMergeTreeMaintenanceCallbackArgs, opArgs: IMergeTreeDeltaOpArgs | undefined) => void;\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/merge-tree",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Merge tree",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -61,23 +61,23 @@
   "dependencies": {
     "@fluidframework/common-definitions": "^0.20.1",
     "@fluidframework/common-utils": "^0.32.1",
-    "@fluidframework/container-definitions": "^1.1.0",
-    "@fluidframework/container-utils": "^1.1.0",
-    "@fluidframework/core-interfaces": "^1.1.0",
-    "@fluidframework/datastore-definitions": "^1.1.0",
+    "@fluidframework/container-definitions": "^1.2.0",
+    "@fluidframework/container-utils": "^1.2.0",
+    "@fluidframework/core-interfaces": "^1.2.0",
+    "@fluidframework/datastore-definitions": "^1.2.0",
     "@fluidframework/protocol-definitions": "^0.1028.2000",
-    "@fluidframework/runtime-definitions": "^1.1.0",
-    "@fluidframework/runtime-utils": "^1.1.0",
-    "@fluidframework/shared-object-base": "^1.1.0",
-    "@fluidframework/telemetry-utils": "^1.1.0"
+    "@fluidframework/runtime-definitions": "^1.2.0",
+    "@fluidframework/runtime-utils": "^1.2.0",
+    "@fluidframework/shared-object-base": "^1.2.0",
+    "@fluidframework/telemetry-utils": "^1.2.0"
   },
   "devDependencies": {
     "@fluidframework/build-common": "^0.24.0",
     "@fluidframework/build-tools": "^0.2.74327",
     "@fluidframework/eslint-config-fluid": "^0.28.2000",
-    "@fluidframework/merge-tree-previous": "npm:@fluidframework/merge-tree@^1.0.0",
-    "@fluidframework/mocha-test-setup": "^1.1.0",
-    "@fluidframework/test-runtime-utils": "^1.1.0",
+    "@fluidframework/merge-tree-previous": "npm:@fluidframework/merge-tree@1.1.0",
+    "@fluidframework/mocha-test-setup": "^1.2.0",
+    "@fluidframework/test-runtime-utils": "^1.2.0",
     "@microsoft/api-extractor": "^7.22.2",
     "@rushstack/eslint-config": "^2.5.1",
     "@types/diff": "^3.5.1",
@@ -98,11 +98,7 @@
     "typescript-formatter": "7.1.0"
   },
   "typeValidation": {
-    "version": "1.1.0",
-    "broken": {
-      "ClassDeclaration_Client": {
-        "forwardCompat": false
-      }
-    }
+    "version": "1.2.0",
+    "broken": {}
   }
 }

package/src/client.ts

@@ -803,9 +803,15 @@ export class Client {
                 case MergeTreeDeltaType.INSERT:
                     assert(segment.seq === UnassignedSequenceNumber,
                         0x037 /* "Segment already has assigned sequence number" */);
+                    let segInsertOp = segment;
+                    if (typeof resetOp.seg === "object" && resetOp.seg.props !== undefined) {
+                        segInsertOp = segment.clone();
+                        segInsertOp.properties = resetOp.seg.props;
+                    }
                     newOp = createInsertSegmentOp(
                         segmentPosition,
-                        segment);
+                        segInsertOp,
+                    );
                     break;
 
                 case MergeTreeDeltaType.REMOVE:

package/src/mergeTree.ts

@@ -2549,8 +2549,9 @@ export class MergeTree {
         client: Client,
     ): LocalReferencePosition {
         if (isRemoved(segment)) {
-            if (!refTypeIncludesFlag(refType, ReferenceType.SlideOnRemove)) {
-                throw new UsageError("Can only create SlideOnRemove local reference position on a removed segment");
+            if (!refTypeIncludesFlag(refType, ReferenceType.SlideOnRemove | ReferenceType.Transient)) {
+                throw new UsageError(
+                    "Can only create SlideOnRemove or Transient local reference position on a removed segment");
             }
         }
         const localRefs = segment.localRefs ?? new LocalReferenceCollection(segment);

package/src/mergeTreeDeltaCallback.ts

@@ -15,15 +15,31 @@ import { ISegment } from "./mergeTree";
 export type MergeTreeDeltaOperationType =
     typeof MergeTreeDeltaType.ANNOTATE | typeof MergeTreeDeltaType.INSERT | typeof MergeTreeDeltaType.REMOVE;
 
-// Note: Assigned negative integers to avoid clashing with MergeTreeDeltaType
+/**
+ * Enum-like constant defining the types of "maintenance" events on a merge tree.
+ * Maintenance events correspond to structural segment changes or acks of pending segments.
+ *
+ * Note: these values are assigned negative integers to avoid clashing with `MergeTreeDeltaType`.
+ */
 export const MergeTreeMaintenanceType = {
+    /**
+     * Notification that a segment "append" has occurred, i.e. two adjacent segments have been merged.
+     * BEWARE: `deltaSegments` on the corresponding event will contain both the merged segment and the latter
+     * segment, pre-merge.
+     * For example, if the merge tree originally had two adjacent segments [A][B] and called A.append(B) to get
+     * segment [AB], `deltaSegments` would contain [AB] and [B].
+     */
     APPEND: -1,
+    /**
+     * Notification that a segment has been split in two.
+     * `deltaSegments` on the corresponding event will contain the resulting two segments.
+     */
     SPLIT: -2,
     /**
-     * Notification that a segment has been unlinked from the MergeTree.  This occurs during
-     * Zamboni when:
-     *
-     *    b) The segment's tracking collection is empty (e.g., not being tracked for undo/redo).
+     * Notification that a segment has been unlinked (i.e. removed) from the MergeTree.
+     * This occurs on leaf segments during Zamboni when the segment's tracking collection is empty
+     * (e.g., not being tracked for undo/redo).
+     * It also occurs on internal merge tree segments when re-packing children to maintain tree balancing invariants.
      */
     UNLINK: -3,
     /**