@fluidframework/sequence 0.59.4001 → 1.1.0-75972

package/src/intervalCollection.ts

@@ -7,6 +7,7 @@
 
 import { assert, TypedEventEmitter } from "@fluidframework/common-utils";
 import { IEvent } from "@fluidframework/common-definitions";
+import { UsageError } from "@fluidframework/container-utils";
 import {
     addProperties,
     Client,
@@ -17,25 +18,45 @@ import {
     IntervalConflictResolver,
     IntervalNode,
     IntervalTree,
+    ISegment,
     LocalReference,
     MergeTreeDeltaType,
     PropertiesManager,
     PropertySet,
     RedBlackTree,
     ReferenceType,
+    refTypeIncludesFlag,
     reservedRangeLabelsKey,
     UnassignedSequenceNumber,
 } from "@fluidframework/merge-tree";
 import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
+import { LoggingError } from "@fluidframework/telemetry-utils";
 import { v4 as uuid } from "uuid";
-import { IValueFactory, IValueOpEmitter, IValueOperation, IValueType } from "./defaultMapInterfaces";
+import {
+    IMapMessageLocalMetadata,
+    IValueFactory,
+    IValueOpEmitter,
+    IValueOperation,
+    IValueType,
+    IValueTypeOperationValue,
+} from "./defaultMapInterfaces";
 
 const reservedIntervalIdKey = "intervalId";
 
 export enum IntervalType {
     Simple = 0x0,
     Nest = 0x1,
-    SlideOnRemove = 0x2,
+    /**
+     * SlideOnRemove indicates that the ends of the interval will slide if the segment
+     * they reference is removed and acked.
+     * See `packages\dds\merge-tree\REFERENCEPOSITIONS.md` for details
+     * SlideOnRemove is the default interval behavior and does not need to be specified.
+     */
+    SlideOnRemove = 0x2, // SlideOnRemove is default behavior - all intervals are SlideOnRemove
+    /**
+     * @internal
+     * A temporary interval, used internally
+     */
     Transient = 0x4,
 }
 
@@ -47,6 +68,55 @@ export interface ISerializedInterval {
     properties?: PropertySet;
 }
 
+/**
+ * A size optimization to avoid redundantly storing keys when serializing intervals
+ * as JSON. Intervals are of the format:
+ *
+ * [start, end, sequenceNumber, intervalType, properties]
+ */
+export type CompressedSerializedInterval = [number, number, number, IntervalType, PropertySet];
+
+/**
+ * @internal
+ */
+export interface ISerializedIntervalCollectionV2 {
+    label: string;
+    version: 2;
+    intervals: CompressedSerializedInterval[];
+}
+
+/**
+ * Decompress an interval after loading a summary from JSON. The exact format
+ * of this compression is unspecified and subject to change
+ */
+function decompressInterval(interval: CompressedSerializedInterval, label?: string): ISerializedInterval {
+    return {
+        start: interval[0],
+        end: interval[1],
+        sequenceNumber: interval[2],
+        intervalType: interval[3],
+        properties: { ...interval[4], [reservedRangeLabelsKey]: label },
+    };
+}
+
+/**
+ * Compress an interval prior to serialization as JSON. The exact format of this
+ * compression is unspecified and subject to change
+ */
+function compressInterval(interval: ISerializedInterval): CompressedSerializedInterval {
+    const { start, end, sequenceNumber, intervalType, properties } = interval;
+
+    return [
+        start,
+        end,
+        sequenceNumber,
+        intervalType,
+        // remove the `referenceRangeLabels` property as it is already stored
+        // in the `label` field of the summary
+        { ...properties, [reservedRangeLabelsKey]: undefined },
+    ];
+}
+
 export interface ISerializableInterval extends IInterval {
     properties: PropertySet;
     propertyManager: PropertiesManager;
@@ -69,7 +139,11 @@ export class Interval implements ISerializableInterval {
     constructor(
         public start: number,
         public end: number,
-        props?: PropertySet) {
+        props?: PropertySet,
+    ) {
+        this.propertyManager = new PropertiesManager();
+        this.properties = {};
+
         if (props) {
             this.addProperties(props);
         }
@@ -94,7 +168,7 @@ export class Interval implements ISerializableInterval {
         this.auxProps.push(props);
     }
 
-    public serialize(client: Client) {
+    public serialize(client: Client): ISerializedInterval {
         let seq = 0;
         if (client) {
             seq = client.getCurrentSeq();
@@ -168,12 +242,7 @@ export class Interval implements ISerializableInterval {
         op?: ICombiningOp,
     ): PropertySet | undefined {
         if (newProps) {
-            if (!this.propertyManager) {
-                this.propertyManager = new PropertiesManager();
-            }
-            if (!this.properties) {
-                this.properties = createMap<any>();
-            }
+            this.initializeProperties();
             return this.propertyManager.addProperties(this.properties, newProps, op, seq, collaborating);
         }
     }
@@ -185,7 +254,21 @@ export class Interval implements ISerializableInterval {
             // Return undefined to indicate that no change is necessary.
             return;
         }
-        return new Interval(startPos, endPos, this.properties);
+        const newInterval = new Interval(startPos, endPos);
+        if (this.properties) {
+            newInterval.initializeProperties();
+            this.propertyManager.copyTo(this.properties, newInterval.properties, newInterval.propertyManager);
+        }
+        return newInterval;
+    }
+
+    private initializeProperties(): void {
+        if (!this.propertyManager) {
+            this.propertyManager = new PropertiesManager();
+        }
+        if (!this.properties) {
+            this.properties = createMap<any>();
+        }
     }
 }
 
@@ -197,13 +280,49 @@ export class SequenceInterval implements ISerializableInterval {
         public start: LocalReference,
         public end: LocalReference,
         public intervalType: IntervalType,
-        props?: PropertySet) {
+        props?: PropertySet,
+    ) {
+        this.propertyManager = new PropertiesManager();
+        this.properties = {};
+
         if (props) {
             this.addProperties(props);
         }
     }
 
-    public serialize(client: Client) {
+    private callbacks?: Record<"beforePositionChange" | "afterPositionChange", () => void>;
+
+    /**
+     * @internal
+     * Subscribes to position change events on this interval if there are no current listeners.
+     */
+    public addPositionChangeListeners(beforePositionChange: () => void, afterPositionChange: () => void): void {
+        if (this.callbacks === undefined) {
+            this.callbacks = {
+                beforePositionChange,
+                afterPositionChange,
+            };
+
+            const startCbs = this.start.callbacks ??= {};
+            const endCbs = this.end.callbacks ??= {};
+            startCbs.beforeSlide = endCbs.beforeSlide = beforePositionChange;
+            startCbs.afterSlide = endCbs.afterSlide = afterPositionChange;
+        }
+    }
+
+    /**
+     * @internal
+     * Removes the currently subscribed position change listeners.
+     */
+    public removePositionChangeListeners(): void {
+        if (this.callbacks) {
+            this.callbacks = undefined;
+            this.start.callbacks = undefined;
+            this.end.callbacks = undefined;
+        }
+    }
+
+    public serialize(client: Client): ISerializedInterval {
         const startPosition = this.start.toPosition();
         const endPosition = this.end.toPosition();
         const serializedInterval: ISerializedInterval = {
@@ -212,9 +331,11 @@ export class SequenceInterval implements ISerializableInterval {
             sequenceNumber: client.getCurrentSeq(),
             start: startPosition,
         };
+
         if (this.properties) {
             serializedInterval.properties = this.properties;
         }
+
         return serializedInterval;
     }
 
@@ -277,12 +398,7 @@ export class SequenceInterval implements ISerializableInterval {
         seq?: number,
         op?: ICombiningOp,
     ): PropertySet | undefined {
-        if (!this.propertyManager) {
-            this.propertyManager = new PropertiesManager();
-        }
-        if (!this.properties) {
-            this.properties = createMap<any>();
-        }
+        this.initializeProperties();
         return this.propertyManager.addProperties(this.properties, newProps, op, seq, collab);
     }
 
@@ -293,21 +409,62 @@ export class SequenceInterval implements ISerializableInterval {
     }
 
     public modify(label: string, start: number, end: number, op?: ISequencedDocumentMessage) {
-        const startPos = start ?? this.start.toPosition();
-        const endPos = end ?? this.end.toPosition();
+        const getRefType = (baseType: ReferenceType): ReferenceType => {
+            let refType = baseType;
+            if (op === undefined) {
+                refType &= ~ReferenceType.SlideOnRemove;
+                refType |= ReferenceType.StayOnRemove;
+            }
+            return refType;
+        };
 
-        if (this.start.toPosition() === startPos && this.end.toPosition() === endPos) {
-            // Return undefined to indicate that no change is necessary.
-            return;
+        let startRef = this.start;
+        if (start !== undefined) {
+            startRef = createPositionReference(this.start.getClient(), start, getRefType(this.start.refType), op);
+            startRef.addProperties(this.start.properties);
         }
 
-        const newInterval =
-            createSequenceInterval(label, startPos, endPos, this.start.getClient(), this.intervalType, op);
+        let endRef = this.end;
+        if (end !== undefined) {
+            endRef = createPositionReference(this.end.getClient(), end, getRefType(this.end.refType), op);
+            endRef.addProperties(this.end.properties);
+        }
+
+        startRef.pairedRef = endRef;
+        endRef.pairedRef = startRef;
+
+        const newInterval = new SequenceInterval(startRef, endRef, this.intervalType);
         if (this.properties) {
-            newInterval.addProperties(this.properties);
+            newInterval.initializeProperties();
+            this.propertyManager.copyTo(this.properties, newInterval.properties, newInterval.propertyManager);
         }
         return newInterval;
     }
+
+    private initializeProperties(): void {
+        if (!this.propertyManager) {
+            this.propertyManager = new PropertiesManager();
+        }
+        if (!this.properties) {
+            this.properties = createMap<any>();
+        }
+    }
+}
+
+function createPositionReferenceFromSegoff(
+    client: Client,
+    segoff: { segment: ISegment | undefined; offset: number | undefined; },
+    refType: ReferenceType,
+    op?: ISequencedDocumentMessage): LocalReference {
+    if (segoff.segment) {
+        const ref = client.createLocalReferencePosition(segoff.segment, segoff.offset, refType, undefined);
+        return ref as LocalReference;
+    } else {
+        if (!op && !refTypeIncludesFlag(refType, ReferenceType.Transient)) {
+            throw new UsageError("Non-transient references need segment");
+        }
+        return new LocalReference(client, undefined, 0, refType);
+    }
 }
 
 function createPositionReference(
@@ -315,15 +472,16 @@ function createPositionReference(
     pos: number,
     refType: ReferenceType,
     op?: ISequencedDocumentMessage): LocalReference {
-    const segoff = client.getContainingSegment(pos, op);
-    if (segoff?.segment) {
-        const lref = new LocalReference(client, segoff.segment, segoff.offset, refType);
-        if (refType !== ReferenceType.Transient) {
-            client.addLocalReference(lref);
-        }
-        return lref;
+    let segoff;
+    if (op) {
+        assert((refType & ReferenceType.SlideOnRemove) !== 0, 0x2f5 /* op create references must be SlideOnRemove */);
+        segoff = client.getContainingSegment(pos, op);
+        segoff = client.getSlideToSegment(segoff);
+    } else {
+        assert((refType & ReferenceType.SlideOnRemove) === 0, 0x2f6 /* SlideOnRemove references must be op created */);
+        segoff = client.getContainingSegment(pos);
     }
-    return new LocalReference(client, undefined);
+    return createPositionReferenceFromSegoff(client, segoff, refType, op);
 }
 
 function createSequenceInterval(
@@ -331,38 +489,42 @@ function createSequenceInterval(
     start: number,
     end: number,
     client: Client,
-    intervalType: IntervalType,
+    intervalType?: IntervalType,
     op?: ISequencedDocumentMessage): SequenceInterval {
     let beginRefType = ReferenceType.RangeBegin;
     let endRefType = ReferenceType.RangeEnd;
-    if (intervalType === IntervalType.Nest) {
-        beginRefType = ReferenceType.NestBegin;
-        endRefType = ReferenceType.NestEnd;
-    } else if (intervalType === IntervalType.Transient) {
+    if (intervalType === IntervalType.Transient) {
         beginRefType = ReferenceType.Transient;
         endRefType = ReferenceType.Transient;
-    }
-
-    // TODO: Should SlideOnRemove be the default behavior?
-    if (intervalType & IntervalType.SlideOnRemove) {
-        beginRefType |= ReferenceType.SlideOnRemove;
-        endRefType |= ReferenceType.SlideOnRemove;
+    } else {
+        if (intervalType === IntervalType.Nest) {
+            beginRefType = ReferenceType.NestBegin;
+            endRefType = ReferenceType.NestEnd;
+        }
+        // All non-transient interval references must eventually be SlideOnRemove
+        // To ensure eventual consistency, they must start as StayOnRemove when
+        // pending (created locally and creation op is not acked)
+        if (op) {
+            beginRefType |= ReferenceType.SlideOnRemove;
+            endRefType |= ReferenceType.SlideOnRemove;
+        } else {
+            beginRefType |= ReferenceType.StayOnRemove;
+            endRefType |= ReferenceType.StayOnRemove;
+        }
     }
 
     const startLref = createPositionReference(client, start, beginRefType, op);
     const endLref = createPositionReference(client, end, endRefType, op);
-    if (startLref && endLref) {
-        startLref.pairedRef = endLref;
-        endLref.pairedRef = startLref;
-        const rangeProp = {
-            [reservedRangeLabelsKey]: [label],
-        };
-        startLref.addProperties(rangeProp);
-        endLref.addProperties(rangeProp);
+    startLref.pairedRef = endLref;
+    endLref.pairedRef = startLref;
+    const rangeProp = {
+        [reservedRangeLabelsKey]: [label],
+    };
+    startLref.addProperties(rangeProp);
+    endLref.addProperties(rangeProp);
 
-        const ival = new SequenceInterval(startLref, endLref, intervalType, rangeProp);
-        return ival;
-    }
+    const ival = new SequenceInterval(startLref, endLref, intervalType, rangeProp);
+    return ival;
 }
 
 export function defaultIntervalConflictResolver(a: Interval, b: Interval) {
@@ -387,8 +549,9 @@ export function createIntervalIndex(conflict?: IntervalConflictResolver<Interval
 export class LocalIntervalCollection<TInterval extends ISerializableInterval> {
     private readonly intervalTree = new IntervalTree<TInterval>();
     private readonly endIntervalTree: RedBlackTree<TInterval, TInterval>;
-    private conflictResolver: IntervalConflictResolver<TInterval>;
-    private endConflictResolver: ConflictAction<TInterval, TInterval>;
+    private readonly intervalIdMap: Map<string, TInterval> = new Map();
+    private conflictResolver: IntervalConflictResolver<TInterval> | undefined;
+    private endConflictResolver: ConflictAction<TInterval, TInterval> | undefined;
 
     private static readonly legacyIdPrefix = "legacy";
 
@@ -396,6 +559,8 @@ export class LocalIntervalCollection<TInterval extends ISerializableInterval> {
         private readonly client: Client,
         private readonly label: string,
         private readonly helpers: IIntervalHelpers<TInterval>,
+        /** Callback invoked each time one of the endpoints of an interval slides. */
+        private readonly onPositionChange?: (interval: TInterval) => void,
     ) {
         // eslint-disable-next-line @typescript-eslint/unbound-method
         this.endIntervalTree = new RedBlackTree<TInterval, TInterval>(helpers.compareEnds);
@@ -405,7 +570,7 @@ export class LocalIntervalCollection<TInterval extends ISerializableInterval> {
         this.conflictResolver = conflictResolver;
         this.endConflictResolver =
             (key: TInterval, currentKey: TInterval) => {
-                const ival = this.conflictResolver(key, currentKey);
+                const ival = conflictResolver(key, currentKey);
                 return {
                     data: ival,
                     key: ival,
@@ -423,12 +588,21 @@ export class LocalIntervalCollection<TInterval extends ISerializableInterval> {
         return `${LocalIntervalCollection.legacyIdPrefix}${start}-${end}`;
     }
 
-    public ensureSerializedId(serializedInterval: ISerializedInterval) {
-        if (serializedInterval.properties?.[reservedIntervalIdKey] === undefined) {
+    /**
+     * Validates that a serialized interval has the ID property. Creates an ID
+     * if one does not already exist
+     *
+     * @param serializedInterval - The interval to be checked
+     * @returns The interval's existing or newly created id
+     */
+    public ensureSerializedId(serializedInterval: ISerializedInterval): string {
+        let id: string | undefined = serializedInterval.properties?.[reservedIntervalIdKey];
+        if (id === undefined) {
             // An interval came over the wire without an ID, so create a non-unique one based on start/end.
             // This will allow all clients to refer to this interval consistently.
+            id = this.createLegacyId(serializedInterval.start, serializedInterval.end);
             const newProps = {
-                [reservedIntervalIdKey]: this.createLegacyId(serializedInterval.start, serializedInterval.end),
+                [reservedIntervalIdKey]: id,
             };
             serializedInterval.properties = addProperties(serializedInterval.properties, newProps);
         }
@@ -438,6 +612,8 @@ export class LocalIntervalCollection<TInterval extends ISerializableInterval> {
             enumerable: true,
             writable: false,
         });
+
+        return id;
     }
 
     public mapUntil(fn: (interval: TInterval) => boolean) {
@@ -520,20 +696,19 @@ export class LocalIntervalCollection<TInterval extends ISerializableInterval> {
     }
 
     public findOverlappingIntervals(startPosition: number, endPosition: number) {
-        if (!this.intervalTree.intervals.isEmpty()) {
-            const transientInterval =
-                this.helpers.create(
-                    "transient",
-                    startPosition,
-                    endPosition,
-                    this.client,
-                    IntervalType.Transient);
-
-            const overlappingIntervalNodes = this.intervalTree.match(transientInterval);
-            return overlappingIntervalNodes.map((node) => node.key);
-        } else {
+        if (endPosition < startPosition || this.intervalTree.intervals.isEmpty()) {
             return [];
         }
+        const transientInterval =
+            this.helpers.create(
+                "transient",
+                startPosition,
+                endPosition,
+                this.client,
+                IntervalType.Transient);
+
+        const overlappingIntervalNodes = this.intervalTree.match(transientInterval);
+        return overlappingIntervalNodes.map((node) => node.key);
     }
 
     public previousInterval(pos: number) {
@@ -562,9 +737,20 @@ export class LocalIntervalCollection<TInterval extends ISerializableInterval> {
         return transientInterval;
     }
 
-    public removeExistingInterval(interval: TInterval) {
+    private removeIntervalFromIndex(interval: TInterval) {
         this.intervalTree.removeExisting(interval);
         this.endIntervalTree.remove(interval);
+
+        const id = interval.getIntervalId();
+
+        assert(id !== undefined, 0x311 /* expected id to exist on interval */);
+
+        this.intervalIdMap.delete(id);
+    }
+
+    public removeExistingInterval(interval: TInterval) {
+        this.removeIntervalFromIndex(interval);
+        this.removeIntervalListeners(interval);
     }
 
     public createInterval(
@@ -598,9 +784,9 @@ export class LocalIntervalCollection<TInterval extends ISerializableInterval> {
         return interval;
     }
 
-    public add(interval: TInterval) {
-        assert(Object.prototype.hasOwnProperty.call(interval.properties, reservedIntervalIdKey),
-            0x2c0 /* "ID must be created before adding interval to collection" */);
+    private addIntervalToIndex(interval: TInterval) {
+        const id = interval.getIntervalId();
+        assert(id !== undefined, 0x2c0 /* "ID must be created before adding interval to collection" */);
         // Make the ID immutable.
         Object.defineProperty(interval.properties, reservedIntervalIdKey, {
             configurable: false,
@@ -609,18 +795,16 @@ export class LocalIntervalCollection<TInterval extends ISerializableInterval> {
         });
         this.intervalTree.put(interval, this.conflictResolver);
         this.endIntervalTree.put(interval, interval, this.endConflictResolver);
+        this.intervalIdMap.set(id, interval);
+    }
+
+    public add(interval: TInterval) {
+        this.addIntervalToIndex(interval);
+        this.addIntervalListeners(interval);
     }
 
     public getIntervalById(id: string) {
-        let result: TInterval | undefined;
-        this.mapUntil((interval: TInterval) => {
-            if (interval.getIntervalId() === id) {
-                result = interval;
-                return false;
-            }
-            return true;
-        });
-        return result;
+        return this.intervalIdMap.get(id);
     }
 
     public changeInterval(interval: TInterval, start: number, end: number, op?: ISequencedDocumentMessage) {
@@ -632,10 +816,33 @@ export class LocalIntervalCollection<TInterval extends ISerializableInterval> {
         return newInterval;
     }
 
-    public serialize() {
+    public serialize(): ISerializedIntervalCollectionV2 {
         const client = this.client;
         const intervals = this.intervalTree.intervals.keys();
-        return intervals.map((interval) => interval.serialize(client));
+
+        return {
+            label: this.label,
+            intervals: intervals.map((interval) => compressInterval(interval.serialize(client))),
+            version: 2,
+        };
+    }
+
+    private addIntervalListeners(interval: TInterval) {
+        if (interval instanceof SequenceInterval) {
+            interval.addPositionChangeListeners(
+                () => this.removeIntervalFromIndex(interval),
+                () => {
+                    this.addIntervalToIndex(interval);
+                    this.onPositionChange?.(interval);
+                },
+            );
+        }
+    }
+
+    private removeIntervalListeners(interval: TInterval) {
+        if (interval instanceof SequenceInterval) {
+            interval.removePositionChangeListeners();
+        }
     }
 }
 
@@ -645,7 +852,7 @@ class SequenceIntervalCollectionFactory
     implements IValueFactory<IntervalCollection<SequenceInterval>> {
     public load(
         emitter: IValueOpEmitter,
-        raw: ISerializedInterval[] = [],
+        raw: ISerializedInterval[] | ISerializedIntervalCollectionV2 = [],
     ): IntervalCollection<SequenceInterval> {
         const helpers: IIntervalHelpers<SequenceInterval> = {
             compareEnds: compareSequenceIntervalEnds,
@@ -654,7 +861,7 @@ class SequenceIntervalCollectionFactory
         return new IntervalCollection<SequenceInterval>(helpers, true, emitter, raw);
     }
 
-    public store(value: IntervalCollection<SequenceInterval>): ISerializedInterval[] {
+    public store(value: IntervalCollection<SequenceInterval>): ISerializedIntervalCollectionV2 {
         return value.serializeInternal();
     }
 }
@@ -678,49 +885,27 @@ export class SequenceIntervalCollectionValueType
     private static readonly _factory: IValueFactory<IntervalCollection<SequenceInterval>> =
         new SequenceIntervalCollectionFactory();
 
-    private static readonly _ops: Map<string, IValueOperation<IntervalCollection<SequenceInterval>>> =
-        new Map<string, IValueOperation<IntervalCollection<SequenceInterval>>>(
-            [[
-                "add",
-                {
-                    process: (value, params, local, op) => {
-                        value.ackAdd(params, local, op);
-                    },
-                },
-            ],
-            [
-                "delete",
-                {
-                    process: (value, params, local, op) => {
-                        value.ackDelete(params, local, op);
-                    },
-                },
-            ],
-            [
-                "change",
-                {
-                    process: (value, params, local, op) => {
-                        value.ackChange(params, local, op);
-                    },
-                },
-            ]]);
+    private static readonly _ops = makeOpsMap<SequenceInterval>();
 }
 
 const compareIntervalEnds = (a: Interval, b: Interval) => a.end - b.end;
 
 function createInterval(label: string, start: number, end: number, client: Client): Interval {
-    let rangeProp: PropertySet;
-    if (label && (label.length > 0)) {
-        rangeProp = {
-            [reservedRangeLabelsKey]: [label],
-        };
+    const rangeProp: PropertySet = {};
+
+    if (label && label.length > 0) {
+        rangeProp[reservedRangeLabelsKey] = [label];
     }
+
     return new Interval(start, end, rangeProp);
 }
 
 class IntervalCollectionFactory
     implements IValueFactory<IntervalCollection<Interval>> {
-    public load(emitter: IValueOpEmitter, raw: ISerializedInterval[] = []): IntervalCollection<Interval> {
+    public load(
+        emitter: IValueOpEmitter,
+        raw: ISerializedInterval[] | ISerializedIntervalCollectionV2 = [],
+    ): IntervalCollection<Interval> {
         const helpers: IIntervalHelpers<Interval> = {
             compareEnds: compareIntervalEnds,
             create: createInterval,
@@ -730,7 +915,7 @@ class IntervalCollectionFactory
         return collection;
     }
 
-    public store(value: IntervalCollection<Interval>): ISerializedInterval[] {
+    public store(value: IntervalCollection<Interval>): ISerializedIntervalCollectionV2 {
         return value.serializeInternal();
     }
 }
@@ -753,32 +938,52 @@ export class IntervalCollectionValueType
 
     private static readonly _factory: IValueFactory<IntervalCollection<Interval>> =
         new IntervalCollectionFactory();
-    private static readonly _ops: Map<string, IValueOperation<IntervalCollection<Interval>>> =
-        new Map<string, IValueOperation<IntervalCollection<Interval>>>(
-            [[
-                "add",
-                {
-                    process: (value, params, local, op) => {
-                        value.ackAdd(params, local, op);
-                    },
+    private static readonly _ops = makeOpsMap<Interval>();
+}
+
+function makeOpsMap<T extends ISerializableInterval>(): Map<string, IValueOperation<IntervalCollection<T>>> {
+    const rebase = (
+        collection: IntervalCollection<T>,
+        op: IValueTypeOperationValue,
+        localOpMetadata: IMapMessageLocalMetadata,
+    ) => {
+        const { localSeq } = localOpMetadata;
+        const rebasedValue = collection.rebaseLocalInterval(op.opName, op.value, localSeq);
+        const rebasedOp = { ...op, value: rebasedValue };
+        return { rebasedOp, rebasedLocalOpMetadata: localOpMetadata };
+    };
+
+    return new Map<string, IValueOperation<IntervalCollection<T>>>(
+        [[
+            "add",
+            {
+                process: (collection, params, local, op) => {
+                    collection.ackAdd(params, local, op);
+                },
+                rebase,
+            },
+        ],
+        [
+            "delete",
+            {
+                process: (collection, params, local, op) => {
+                    collection.ackDelete(params, local, op);
                 },
-            ],
-            [
-                "delete",
-                {
-                    process: (value, params, local, op) => {
-                        value.ackDelete(params, local, op);
-                    },
+                rebase: (collection, op, localOpMetadata) => {
+                    // Deletion of intervals is based on id, so requires no rebasing.
+                    return { rebasedOp: op, rebasedLocalOpMetadata: localOpMetadata };
                 },
-            ],
-            [
-                "change",
-                {
-                    process: (value, params, local, op) => {
-                        value.ackChange(params, local, op);
-                    },
+            },
+        ],
+        [
+            "change",
+            {
+                process: (collection, params, local, op) => {
+                    collection.ackChange(params, local, op);
                 },
-            ]]);
+                rebase,
+            },
+        ]]);
 }
 
 export type DeserializeCallback = (properties: PropertySet) => void;
@@ -815,7 +1020,18 @@ export class IntervalCollectionIterator<TInterval extends ISerializableInterval>
 }
 
 export interface IIntervalCollectionEvent<TInterval extends ISerializableInterval> extends IEvent {
-    (event: "addInterval" | "changeInterval" | "deleteInterval",
+    /**
+     * This event is invoked whenever the properties or endpoints of an interval may have changed.
+     * This can happen on:
+     * - endpoint modification (local or remote)
+     * - ack of an endpoint modification
+     * - property change (local or remote)
+     * - position change due to segment sliding (will always appear as a local change)
+     * The `interval` argument reflects the new values.
+     */
+    (event: "changeInterval",
+        listener: (interval: TInterval, local: boolean, op: ISequencedDocumentMessage | undefined) => void);
+    (event: "addInterval" | "deleteInterval",
         listener: (interval: TInterval, local: boolean, op: ISequencedDocumentMessage) => void);
     (event: "propertyChanged", listener: (interval: TInterval, propertyArgs: PropertySet) => void);
 }
@@ -824,34 +1040,49 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
     extends TypedEventEmitter<IIntervalCollectionEvent<TInterval>> {
     private savedSerializedIntervals?: ISerializedInterval[];
     private localCollection: LocalIntervalCollection<TInterval>;
-    private onDeserialize: DeserializeCallback;
+    private onDeserialize: DeserializeCallback | undefined;
     private client: Client;
-    private pendingChangesStart: Map<string, ISerializedInterval[]>;
-    private pendingChangesEnd: Map<string, ISerializedInterval[]>;
+    private readonly pendingChangesStart: Map<string, ISerializedInterval[]> = new Map<string, ISerializedInterval[]>();
+    private readonly pendingChangesEnd: Map<string, ISerializedInterval[]> = new Map<string, ISerializedInterval[]>();
 
     public get attached(): boolean {
         return !!this.localCollection;
     }
 
-    constructor(private readonly helpers: IIntervalHelpers<TInterval>, private readonly requiresClient: boolean,
+    /** @internal */
+    constructor(
+        private readonly helpers: IIntervalHelpers<TInterval>,
+        private readonly requiresClient: boolean,
         private readonly emitter: IValueOpEmitter,
-        serializedIntervals: ISerializedInterval[]) {
+        serializedIntervals: ISerializedInterval[] | ISerializedIntervalCollectionV2,
+    ) {
         super();
-        this.savedSerializedIntervals = serializedIntervals;
+
+        if (Array.isArray(serializedIntervals)) {
+            this.savedSerializedIntervals = serializedIntervals;
+        } else {
+            this.savedSerializedIntervals =
+                serializedIntervals.intervals.map((i) => decompressInterval(i, serializedIntervals.label));
+        }
     }
 
     public attachGraph(client: Client, label: string) {
         if (this.attached) {
-            throw new Error("Only supports one Sequence attach");
+            throw new LoggingError("Only supports one Sequence attach");
         }
 
         if ((client === undefined) && (this.requiresClient)) {
-            throw new Error("Client required for this collection");
+            throw new LoggingError("Client required for this collection");
         }
 
         // Instantiate the local interval collection based on the saved intervals
         this.client = client;
-        this.localCollection = new LocalIntervalCollection<TInterval>(client, label, this.helpers);
+        this.localCollection = new LocalIntervalCollection<TInterval>(
+            client,
+            label,
+            this.helpers,
+            (interval) => this.emit("changeInterval", interval, true, undefined),
+        );
         if (this.savedSerializedIntervals) {
             for (const serializedInterval of this.savedSerializedIntervals) {
                 this.localCollection.ensureSerializedId(serializedInterval);
@@ -865,13 +1096,28 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
         this.savedSerializedIntervals = undefined;
     }
 
+    /**
+     * Gets the next local sequence number, modifying this client's collab window in doing so.
+     */
+    private getNextLocalSeq(): number {
+        return ++this.client.getCollabWindow().localSeq;
+    }
+
     public getIntervalById(id: string) {
         if (!this.attached) {
-            throw new Error("attach must be called before accessing intervals");
+            throw new LoggingError("attach must be called before accessing intervals");
         }
         return this.localCollection.getIntervalById(id);
     }
 
+    /**
+     * Create a new interval and add it to the collection
+     * @param start - interval start position
+     * @param end - interval end position
+     * @param intervalType - type of the interval. All intervals are SlideOnRemove. Intervals may not be Transient.
+     * @param props - properties of the interval
+     * @returns - the created interval
+     */
     public add(
         start: number,
         end: number,
@@ -879,7 +1125,10 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
         props?: PropertySet,
     ) {
         if (!this.attached) {
-            throw new Error("attach must be called prior to adding intervals");
+            throw new LoggingError("attach must be called prior to adding intervals");
+        }
+        if (intervalType & IntervalType.Transient) {
+            throw new LoggingError("Can not add transient intervals");
         }
 
         const interval: TInterval = this.localCollection.addInterval(start, end, intervalType, props);
@@ -893,7 +1142,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
                 start,
             };
             // Local ops get submitted to the server. Remote ops have the deserializer run.
-            this.emitter.emit("add", undefined, serializedInterval);
+            this.emitter.emit("add", undefined, serializedInterval, { localSeq: this.getNextLocalSeq() });
         }
 
         this.emit("addInterval", interval, true, undefined);
@@ -901,13 +1150,19 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
         return interval;
     }
 
-    private deleteExistingInterval(interval: TInterval, local: boolean, op: ISequencedDocumentMessage) {
+    private deleteExistingInterval(interval: TInterval, local: boolean, op?: ISequencedDocumentMessage) {
         // The given interval is known to exist in the collection.
         this.localCollection.removeExistingInterval(interval);
+
         if (interval) {
             // Local ops get submitted to the server. Remote ops have the deserializer run.
             if (local) {
-                this.emitter.emit("delete", undefined, interval.serialize(this.client));
+                this.emitter.emit(
+                    "delete",
+                    undefined,
+                    interval.serialize(this.client),
+                    { localSeq: this.getNextLocalSeq() },
+                );
             } else {
                 if (this.onDeserialize) {
                     this.onDeserialize(interval);
@@ -928,13 +1183,13 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
 
     public changeProperties(id: string, props: PropertySet) {
         if (!this.attached) {
-            throw new Error("Attach must be called before accessing intervals");
+            throw new LoggingError("Attach must be called before accessing intervals");
         }
         if (typeof (id) !== "string") {
-            throw new Error("Change API requires an ID that is a string");
+            throw new LoggingError("Change API requires an ID that is a string");
         }
         if (!props) {
-            throw new Error("changeProperties should be called with a property set");
+            throw new LoggingError("changeProperties should be called with a property set");
         }
 
         const interval = this.getIntervalById(id);
@@ -942,12 +1197,15 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
             // Pass Unassigned as the sequence number to indicate that this is a local op that is waiting for an ack.
             const deltaProps = interval.addProperties(props, true, UnassignedSequenceNumber);
             const serializedInterval: ISerializedInterval = interval.serialize(this.client);
-            // Emit a change op that will only change properties. Add the ID to the property bag provided by the caller.
-            serializedInterval.start = undefined;
-            serializedInterval.end = undefined;
+
+            // Emit a change op that will only change properties. Add the ID to
+            // the property bag provided by the caller.
+            serializedInterval.start = undefined as any;
+            serializedInterval.end = undefined as any;
+
             serializedInterval.properties = props;
             serializedInterval.properties[reservedIntervalIdKey] = interval.getIntervalId();
-            this.emitter.emit("change", undefined, serializedInterval);
+            this.emitter.emit("change", undefined, serializedInterval, { localSeq: this.getNextLocalSeq() });
             this.emit("propertyChanged", interval, deltaProps);
         }
         this.emit("changeInterval", interval, true, undefined);
@@ -955,42 +1213,39 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
 
     public change(id: string, start?: number, end?: number): TInterval | undefined {
         if (!this.attached) {
-            throw new Error("Attach must be called before accessing intervals");
+            throw new LoggingError("Attach must be called before accessing intervals");
         }
+
+        // Force id to be a string.
         if (typeof (id) !== "string") {
-            throw new Error("Change API requires an ID that is a string");
+            throw new LoggingError("Change API requires an ID that is a string");
         }
 
-        // Force id to be a string.
         const interval = this.getIntervalById(id);
         if (interval) {
-            this.localCollection.changeInterval(interval, start, end);
+            const newInterval = this.localCollection.changeInterval(interval, start, end);
             const serializedInterval: ISerializedInterval = interval.serialize(this.client);
             serializedInterval.start = start;
             serializedInterval.end = end;
             // Emit a property bag containing only the ID, as we don't intend for this op to change any properties.
             serializedInterval.properties =
-                {
-                    [reservedIntervalIdKey]: interval.getIntervalId(),
-                };
-            this.emitter.emit("change", undefined, serializedInterval);
+            {
+                [reservedIntervalIdKey]: interval.getIntervalId(),
+            };
+            this.emitter.emit("change", undefined, serializedInterval, { localSeq: this.getNextLocalSeq() });
             this.addPendingChange(id, serializedInterval);
+            this.emit("changeInterval", newInterval, true, undefined);
+            return newInterval;
         }
-        this.emit("changeInterval", interval, true, undefined);
-        return interval;
+        // No interval to change
+        return undefined;
     }
 
     private addPendingChange(id: string, serializedInterval: ISerializedInterval) {
         if (serializedInterval.start !== undefined) {
-            if (!this.pendingChangesStart) {
-                this.pendingChangesStart = new Map<string, ISerializedInterval[]>();
-            }
             this.addPendingChangeHelper(id, this.pendingChangesStart, serializedInterval);
         }
         if (serializedInterval.end !== undefined) {
-            if (!this.pendingChangesEnd) {
-                this.pendingChangesEnd = new Map<string, ISerializedInterval[]>();
-            }
             this.addPendingChangeHelper(id, this.pendingChangesEnd, serializedInterval);
         }
     }
@@ -1000,7 +1255,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
         pendingChanges: Map<string, ISerializedInterval[]>,
         serializedInterval: ISerializedInterval,
     ) {
-        let entries: ISerializedInterval[] = pendingChanges.get(id);
+        let entries: ISerializedInterval[] | undefined = pendingChanges.get(id);
         if (!entries) {
             entries = [];
             pendingChanges.set(id, entries);
@@ -1010,7 +1265,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
 
     private removePendingChange(serializedInterval: ISerializedInterval) {
         // Change ops always have an ID.
-        const id: string = serializedInterval.properties[reservedIntervalIdKey];
+        const id: string = serializedInterval.properties?.[reservedIntervalIdKey];
         if (serializedInterval.start !== undefined) {
             this.removePendingChangeHelper(id, this.pendingChangesStart, serializedInterval);
         }
@@ -1024,26 +1279,26 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
         pendingChanges: Map<string, ISerializedInterval[]>,
         serializedInterval: ISerializedInterval,
     ) {
-        const entries = pendingChanges?.get(id);
+        const entries = pendingChanges.get(id);
         if (entries) {
             const pendingChange = entries.shift();
             if (entries.length === 0) {
                 pendingChanges.delete(id);
             }
-            if (pendingChange.start !== serializedInterval.start ||
-                pendingChange.end !== serializedInterval.end) {
-                throw new Error("Mismatch in pending changes");
+            if (pendingChange?.start !== serializedInterval.start ||
+                pendingChange?.end !== serializedInterval.end) {
+                throw new LoggingError("Mismatch in pending changes");
             }
         }
     }
 
     private hasPendingChangeStart(id: string) {
-        const entries = this.pendingChangesStart?.get(id);
+        const entries = this.pendingChangesStart.get(id);
         return entries && entries.length !== 0;
     }
 
     private hasPendingChangeEnd(id: string) {
-        const entries = this.pendingChangesEnd?.get(id);
+        const entries = this.pendingChangesEnd.get(id);
         return entries && entries.length !== 0;
     }
 
@@ -1055,7 +1310,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
     /** @internal */
     public ackChange(serializedInterval: ISerializedInterval, local: boolean, op: ISequencedDocumentMessage) {
         if (!this.attached) {
-            throw new Error("Attach must be called before accessing intervals");
+            throw new LoggingError("Attach must be called before accessing intervals");
         }
 
         let interval: TInterval | undefined;
@@ -1063,15 +1318,17 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
         if (local) {
             // This is an ack from the server. Remove the pending change.
             this.removePendingChange(serializedInterval);
-            const id: string = serializedInterval.properties[reservedIntervalIdKey];
+            const id: string = serializedInterval.properties?.[reservedIntervalIdKey];
             interval = this.getIntervalById(id);
             if (interval) {
                 // Let the propertyManager prune its pending change-properties set.
                 interval.propertyManager?.ackPendingProperties(
                     {
                         type: MergeTreeDeltaType.ANNOTATE,
-                        props: serializedInterval.properties,
+                        props: serializedInterval.properties ?? {},
                     });
+
+                this.ackInterval(interval, op);
             }
         } else {
             // If there are pending changes with this ID, don't apply the remote start/end change, as the local ack
@@ -1110,7 +1367,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
 
     public addConflictResolver(conflictResolver: IntervalConflictResolver<TInterval>): void {
         if (!this.attached) {
-            throw new Error("attachSequence must be called");
+            throw new LoggingError("attachSequence must be called");
         }
         this.localCollection.addConflictResolver(conflictResolver);
     }
@@ -1126,10 +1383,111 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
 
         // Trigger the async prepare work across all values in the collection
         this.localCollection.map((interval) => {
-            this.onDeserialize(interval);
+            onDeserialize(interval);
         });
     }
 
+    /** @internal */
+    public rebaseLocalInterval(
+        opName: string,
+        serializedInterval: ISerializedInterval,
+        localSeq: number,
+    ) {
+        if (!this.attached) {
+            throw new LoggingError("attachSequence must be called");
+        }
+
+        const { start, end, intervalType, properties, sequenceNumber } = serializedInterval;
+        const startRebased = start === undefined ? undefined :
+            this.client.rebasePosition(start, sequenceNumber, localSeq);
+        const endRebased = end === undefined ? undefined :
+            this.client.rebasePosition(end, sequenceNumber, localSeq);
+
+        const intervalId = properties?.[reservedIntervalIdKey];
+        const rebased: ISerializedInterval = {
+            start: startRebased,
+            end: endRebased,
+            intervalType,
+            sequenceNumber: this.client?.getCurrentSeq() ?? 0,
+            properties,
+        };
+        if (opName === "change" && (this.hasPendingChangeStart(intervalId) || this.hasPendingChangeEnd(intervalId))) {
+            this.removePendingChange(serializedInterval);
+            this.addPendingChange(intervalId, rebased);
+        }
+        return rebased;
+    }
+
+    private getSlideToSegment(lref: LocalReference) {
+        const segoff = { segment: lref.segment, offset: lref.offset };
+        const newSegoff = this.client.getSlideToSegment(segoff);
+        const value: { segment: ISegment | undefined; offset: number | undefined; } | undefined
+            = (segoff.segment === newSegoff.segment && segoff.offset === newSegoff.offset) ? undefined : newSegoff;
+        return value;
+    }
+
+    private setSlideOnRemove(lref: LocalReference) {
+        let refType = lref.refType;
+        refType = refType & ~ReferenceType.StayOnRemove;
+        refType = refType | ReferenceType.SlideOnRemove;
+        lref.refType = refType;
+    }
+
+    private ackInterval(interval: TInterval, op: ISequencedDocumentMessage) {
+        // in current usage, interval is always a SequenceInterval
+        if (!(interval instanceof SequenceInterval)) {
+            return;
+        }
+
+        if (!refTypeIncludesFlag(interval.start, ReferenceType.StayOnRemove) &&
+            !refTypeIncludesFlag(interval.end, ReferenceType.StayOnRemove)) {
+            return;
+        }
+
+        const newStart = this.getSlideToSegment(interval.start);
+        const newEnd = this.getSlideToSegment(interval.end);
+
+        const id = interval.properties[reservedIntervalIdKey];
+        const hasPendingStartChange = this.hasPendingChangeStart(id);
+        const hasPendingEndChange = this.hasPendingChangeEnd(id);
+
+        if (!hasPendingStartChange) {
+            this.setSlideOnRemove(interval.start);
+        }
+
+        if (!hasPendingEndChange) {
+            this.setSlideOnRemove(interval.end);
+        }
+
+        const needsStartUpdate = newStart !== undefined && !hasPendingStartChange;
+        const needsEndUpdate = newEnd !== undefined && !hasPendingEndChange;
+
+        if (needsStartUpdate || needsEndUpdate) {
+            // In this case, where we change the start or end of an interval,
+            // it is necessary to remove and re-add the interval listeners.
+            // This ensures that the correct listeners are added to the ReferencePosition.
+            this.localCollection.removeExistingInterval(interval);
+
+            if (needsStartUpdate) {
+                const props = interval.start.properties;
+                this.client.removeLocalReferencePosition(interval.start);
+                interval.start = createPositionReferenceFromSegoff(this.client, newStart, interval.start.refType, op);
+                if (props) {
+                    interval.start.addProperties(props);
+                }
+            }
+            if (needsEndUpdate) {
+                const props = interval.end.properties;
+                this.client.removeLocalReferencePosition(interval.end);
+                interval.end = createPositionReferenceFromSegoff(this.client, newEnd, interval.end.refType, op);
+                if (props) {
+                    interval.end.addProperties(props);
+                }
+            }
+            this.localCollection.add(interval);
+        }
+    }
+
     /** @deprecated - use ackAdd */
     public addInternal(
         serializedInterval: ISerializedInterval,
@@ -1144,13 +1502,16 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
         local: boolean,
         op: ISequencedDocumentMessage) {
         if (local) {
-            // Local ops were applied when the message was created and there's no "pending add"
-            // state to bookkeep
+            const id: string = serializedInterval.properties?.[reservedIntervalIdKey];
+            const localInterval = this.getIntervalById(id);
+            if (localInterval) {
+                this.ackInterval(localInterval, op);
+            }
             return;
         }
 
         if (!this.attached) {
-            throw new Error("attachSequence must be called");
+            throw new LoggingError("attachSequence must be called");
         }
 
         this.localCollection.ensureSerializedId(serializedInterval);
@@ -1194,19 +1555,22 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
         }
 
         if (!this.attached) {
-            throw new Error("attach must be called prior to deleting intervals");
+            throw new LoggingError("attach must be called prior to deleting intervals");
         }
 
-        this.localCollection.ensureSerializedId(serializedInterval);
-        const interval = this.localCollection.getIntervalById(serializedInterval.properties[reservedIntervalIdKey]);
+        const id = this.localCollection.ensureSerializedId(serializedInterval);
+        const interval = this.localCollection.getIntervalById(id);
         if (interval) {
             this.deleteExistingInterval(interval, local, op);
         }
     }
 
-    public serializeInternal() {
+    /**
+     * @internal
+     */
+    public serializeInternal(): ISerializedIntervalCollectionV2 {
         if (!this.attached) {
-            throw new Error("attachSequence must be called");
+            throw new LoggingError("attachSequence must be called");
         }
 
         return this.localCollection.serialize();
@@ -1251,7 +1615,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
 
     public findOverlappingIntervals(startPosition: number, endPosition: number): TInterval[] {
         if (!this.attached) {
-            throw new Error("attachSequence must be called");
+            throw new LoggingError("attachSequence must be called");
         }
 
         return this.localCollection.findOverlappingIntervals(startPosition, endPosition);
@@ -1259,7 +1623,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
 
     public map(fn: (interval: TInterval) => void) {
         if (!this.attached) {
-            throw new Error("attachSequence must be called");
+            throw new LoggingError("attachSequence must be called");
         }
 
         this.localCollection.map(fn);
@@ -1267,7 +1631,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
 
     public previousInterval(pos: number): TInterval {
         if (!this.attached) {
-            throw new Error("attachSequence must be called");
+            throw new LoggingError("attachSequence must be called");
         }
 
         return this.localCollection.previousInterval(pos);
@@ -1275,7 +1639,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
 
     public nextInterval(pos: number): TInterval {
         if (!this.attached) {
-            throw new Error("attachSequence must be called");
+            throw new LoggingError("attachSequence must be called");
         }
 
         return this.localCollection.nextInterval(pos);