sequence: expose sided obliterate on ISharedString (#22700)

This PR exposes the new `mergeTreeEnableSidedObliterate` feature flag on
`ISharedSegmentSequence` and `ISharedString`, which allows passing
`InteriorSequencePlace`s as arguments to `obliterateRange`.

packages/dds/sequence/api-report/sequence.legacy.alpha.api.md

@@ -241,7 +241,7 @@ export interface ISharedSegmentSequence<T extends ISegment> extends ISharedObjec
     insertAtReferencePosition(pos: ReferencePosition, segment: T): void;
     insertFromSpec(pos: number, spec: IJSONSegment): void;
     localReferencePositionToPosition(lref: ReferencePosition): number;
-    obliterateRange(start: number, end: number): void;
+    obliterateRange(start: number | InteriorSequencePlace, end: number | InteriorSequencePlace): void;
     posFromRelativePos(relativePos: IRelativePosition): number;
     removeLocalReferencePosition(lref: LocalReferencePosition): LocalReferencePosition | undefined;
     // (undocumented)
@@ -417,7 +417,7 @@ export abstract class SharedSegmentSequence<T extends ISegment> extends SharedOb
     // (undocumented)
     localReferencePositionToPosition(lref: ReferencePosition): number;
     // (undocumented)
-    obliterateRange(start: number, end: number): void;
+    obliterateRange(start: number | InteriorSequencePlace, end: number | InteriorSequencePlace): void;
     protected onConnect(): void;
     protected onDisconnect(): void;
     // (undocumented)

packages/dds/sequence/src/intervalCollectionMapInterfaces.ts

@@ -67,7 +67,9 @@ export interface IMapMessageLocalMetadata {
 export interface SequenceOptions
 	extends Pick<
 		IMergeTreeOptions,
-		"mergeTreeReferencesCanSlideToEndpoint" | "mergeTreeEnableObliterate"
+		| "mergeTreeReferencesCanSlideToEndpoint"
+		| "mergeTreeEnableObliterate"
+		| "mergeTreeEnableSidedObliterate"
 	> {
 	/**
 	 * Enable the ability to use interval APIs that rely on positions before and

packages/dds/sequence/src/sequence.ts

@@ -46,6 +46,7 @@ import {
 	createObliterateRangeOp,
 	createRemoveRangeOp,
 	matchProperties,
+	type InteriorSequencePlace,
 } from "@fluidframework/merge-tree/internal";
 import {
 	ISummaryTreeWithStats,
@@ -253,12 +254,30 @@ export interface ISharedSegmentSequence<T extends ISegment>
 
 	/**
 	 * Obliterate is similar to remove, but differs in that segments concurrently
-	 * inserted into an obliterated range will also be removed
+	 * inserted into an obliterated range will also be removed.
+	 * Inserts are considered concurrent to an obliterate iff the insert op's seq is after the obliterate op's refSeq
+	 * and the insert's refSeq is before the obliterates seq.
+	 * Inserts made by the client which most recently obliterated a range containing the insert position
+	 * are not considered concurrent to any obliteration (the last client to obliterate gets the right to insert).
 	 *
-	 * @param start - The inclusive start of the range to obliterate
-	 * @param end - The exclusive end of the range to obliterate
+	 * The endpoints can either be inclusive or exclusive.
+	 * Exclusive endpoints allow the obliterated range to "grow" to include adjacent concurrently inserted segments on that side.
+	 *
+	 * @param start - The start of the range to obliterate.
+	 * Inclusive if side is Before or a number is provided.
+	 * @param end - The end of the range to obliterate. Inclusive if side is After.
+	 * If a number is provided it is treated as exclusive,
+	 * but the endpoint does not expand in order to preserve existing behavior.
+	 *
+	 * @example Given the initial state `"|ABC>"`,
+	 * `obliterateRange({ pos: 0, side: Side.After }, { pos: 4, side: Side.Before })` obliterates `"ABC"`, leaving only `"|>"`.
+	 * `insertFromSpec(1, { text: "AAA"})` would insert `"AAA"` before |, resulting in `"|AAA>"`.
+	 * If another client does the same thing but inserts `"BBB"` and gets sequenced later, all clients will eventually see `|BBB>`.
 	 */
-	obliterateRange(start: number, end: number): void;
+	obliterateRange(
+		start: number | InteriorSequencePlace,
+		end: number | InteriorSequencePlace,
+	): void;
 
 	/**
 	 * @returns The most recent sequence number which has been acked by the server and processed by this
@@ -496,6 +515,7 @@ export abstract class SharedSegmentSequence<T extends ISegment>
 			"Fluid.Sequence",
 			{
 				mergeTreeEnableObliterate: (c, n) => c.getBoolean(n),
+				mergeTreeEnableSidedObliterate: (c, n) => c.getBoolean(n),
 				intervalStickinessEnabled: (c, n) => c.getBoolean(n),
 				mergeTreeReferencesCanSlideToEndpoint: (c, n) => c.getBoolean(n),
 			},
@@ -545,7 +565,10 @@ export abstract class SharedSegmentSequence<T extends ISegment>
 		this.guardReentrancy(() => this.client.removeRangeLocal(start, end));
 	}
 
-	public obliterateRange(start: number, end: number): void {
+	public obliterateRange(
+		start: number | InteriorSequencePlace,
+		end: number | InteriorSequencePlace,
+	): void {
 		this.guardReentrancy(() => this.client.obliterateRangeLocal(start, end));
 	}
 

packages/framework/fluid-framework/api-report/fluid-framework.legacy.alpha.api.md

@@ -764,7 +764,7 @@ export interface ISharedSegmentSequence<T extends ISegment> extends ISharedObjec
     insertAtReferencePosition(pos: ReferencePosition, segment: T): void;
     insertFromSpec(pos: number, spec: IJSONSegment): void;
     localReferencePositionToPosition(lref: ReferencePosition): number;
-    obliterateRange(start: number, end: number): void;
+    obliterateRange(start: number | InteriorSequencePlace, end: number | InteriorSequencePlace): void;
     posFromRelativePos(relativePos: IRelativePosition): number;
     removeLocalReferencePosition(lref: LocalReferencePosition): LocalReferencePosition | undefined;
     // (undocumented)