feat(datastore): race-id DDS create (alternative to claims, v1 alpha)

.changeset/race-id-dds-create.md

@@ -0,0 +1,22 @@
+---
+"@fluidframework/datastore": minor
+"@fluidframework/datastore-definitions": minor
+"@fluidframework/runtime-definitions": minor
+"__section": feature
+---
+Race-id DDS create: deterministic FWW resolution for concurrent channel creates
+
+Adds an opt-in alpha API for resolving racing DDS creates with deterministic first-writer-wins (FWW) semantics. When multiple clients independently create a channel that they consider semantically the same (for example, a singleton DDS attached to a shared key), all clients converge to the same winner without breaking optimistic local application.
+
+API surface (alpha):
+- `IFluidDataStoreRuntime.createChannel(raceId, type, { onLost })` overload — pass a shared `raceId` agreed across racing clients; the runtime mints a unique internal channel id (`${raceId}#${guid}`).
+- `IAttachMessage.raceId` — optional field that propagates the race id with the attach op.
+- `raceResolved` event on `IFluidDataStoreRuntime` — fires with `{ raceId, winnerChannelId, loserChannelIds }`.
+- `OnRaceLost` callback — invoked on losing clients so the app can merge local edits from the loser channel into the winner.
+
+Resolution semantics: the first attach op for a given `raceId` (per the sequenced order) wins. Subsequent attaches with the same `raceId`, and any channel ops addressed to loser channel ids, are dropped on every client deterministically. Loser->winner redirects are persisted in a `.races` summary blob.
+
+v1 limitations (tracked as follow-ups):
+- Race-id handles, optimistic handle storage, data-store-level races, public `IChannel.dispose()`, and async `onLost` are out of scope.
+- The race overload is rejected while the data store is detached or in staging mode.
+- The summary redirect table is rehydrated asynchronously on load; ops to historical losers may transiently be applied during the load window.

packages/runtime/datastore-definitions/api-report/datastore-definitions.legacy.alpha.api.md

@@ -81,6 +81,10 @@ export interface IFluidDataStoreRuntime extends IEventProvider<IFluidDataStoreRu
     // (undocumented)
     readonly connected: boolean;
     createChannel(id: string | undefined, type: string): IChannel;
+    // @alpha
+    createChannel(raceId: string, type: string, raceOptions: {
+        onLost?: OnRaceLost;
+    }): IChannel;
     // (undocumented)
     readonly deltaManager: IDeltaManagerErased;
     readonly entryPoint: IFluidHandle<FluidObject>;
@@ -130,6 +134,12 @@ export interface IFluidDataStoreRuntimeEvents extends IEvent {
     (event: "connected", listener: (clientId: string) => void): any;
     // (undocumented)
     (event: "readonly", listener: (isReadOnly: boolean) => void): any;
+    // @alpha
+    (event: "raceResolved", listener: (info: {
+        raceId: string;
+        winnerChannelId: string;
+        loserChannelIds: readonly string[];
+    }) => void): any;
 }
 
 // @beta @legacy (undocumented)
@@ -146,6 +156,9 @@ export type Jsonable<T, TReplaced = never> = boolean extends (T extends never ?
 // @beta @legacy
 export type JsonableTypeWith<T> = undefined | null | boolean | number | string | T | Internal_InterfaceOfJsonableTypesWith<T> | ArrayLike<JsonableTypeWith<T>>;
 
+// @alpha
+export type OnRaceLost = (loser: IChannel, winnerChannelId: string) => void;
+
 // @beta @legacy
 export type Serializable<T> = Jsonable<T, IFluidHandle>;
 

packages/runtime/datastore-definitions/src/dataStoreRuntime.ts

@@ -24,6 +24,22 @@ import type {
 
 import type { IChannel } from "./channel.js";
 
+/**
+ * Callback invoked on the losing client after a channel-creation "race"
+ * resolves. The runtime schedules this asynchronously after the current op
+ * processing step; it does not block op processing.
+ *
+ * @param loser - The local channel that lost the race. This channel's context
+ * has been removed from the runtime; the consumer should stop using it after
+ * this callback returns. The callback should read any state from `loser` and
+ * apply it to the winner via `runtime.getChannel(winnerChannelId)`.
+ * @param winnerChannelId - The id of the winning channel. Use
+ * `IFluidDataStoreRuntime.getChannel` to obtain a handle to it.
+ *
+ * @alpha
+ */
+export type OnRaceLost = (loser: IChannel, winnerChannelId: string) => void;
+
 /**
  * Events emitted by {@link IFluidDataStoreRuntime}.
  * @legacy @beta
@@ -41,6 +57,21 @@ export interface IFluidDataStoreRuntimeEvents extends IEvent {
 	 * The isReadOnly param will express the new readonly state.
 	 */
 	(event: "readonly", listener: (isReadOnly: boolean) => void);
+
+	/**
+	 * Fired after a "race" between concurrent channel creations resolves
+	 * deterministically across all clients. See `createChannel`'s race overload.
+	 *
+	 * @alpha
+	 */
+	(
+		event: "raceResolved",
+		listener: (info: {
+			raceId: string;
+			winnerChannelId: string;
+			loserChannelIds: readonly string[];
+		}) => void,
+	);
 }
 
 /**
@@ -109,6 +140,45 @@ export interface IFluidDataStoreRuntime
 	 */
 	createChannel(id: string | undefined, type: string): IChannel;
 
+	/**
+	 * Creates a new channel that participates in a first-attach-wins "race"
+	 * with concurrent creations on other clients.
+	 *
+	 * @remarks
+	 * All clients calling this overload with the same `raceId` converge on a
+	 * single attached channel: the first attach op sequenced for a given
+	 * `raceId` wins, and every other client's locally-created channel becomes
+	 * a "loser" whose subsequent ops are dropped deterministically by every
+	 * client. The losing client may register an `onLost` callback to merge
+	 * its local state into the winner.
+	 *
+	 * Each racing client receives its own locally-unique channel id; only the
+	 * `raceId` is shared across clients. Use `IChannel.id` on the returned
+	 * channel for local routing.
+	 *
+	 * Throws a `UsageError` if:
+	 * - The document schema has not enabled the race-id channel-create feature.
+	 * - The data store is detached or in staging mode.
+	 * - This client has already created a racing channel with the same `raceId`.
+	 *
+	 * `onLost` is invoked asynchronously (after the current op processing
+	 * step) on the losing client; it does not block op processing. If `onLost`
+	 * is not provided and this client loses, the loser context is silently
+	 * removed and a telemetry event is fired.
+	 *
+	 * @param raceId - Identifier shared across racing clients.
+	 * @param type - Type of the channel.
+	 * @param raceOptions - Race semantics opt-in. Presence of this argument
+	 * marks the call as a race participant.
+	 *
+	 * @alpha
+	 */
+	createChannel(
+		raceId: string,
+		type: string,
+		raceOptions: { onLost?: OnRaceLost },
+	): IChannel;
+
 	/**
 	 * Adds an existing channel to the data store.
 	 *

packages/runtime/datastore-definitions/src/index.ts

@@ -23,6 +23,7 @@ export type {
 	IFluidDataStoreRuntimeAlpha,
 	IFluidDataStoreRuntimeEvents,
 	IFluidDataStoreRuntimeInternalConfig,
+	OnRaceLost,
 	IDeltaManagerErased,
 } from "./dataStoreRuntime.js";
 export type {

packages/runtime/datastore/api-report/datastore.legacy.beta.api.md

@@ -36,8 +36,7 @@ export class FluidDataStoreRuntime extends TypedEventEmitter<IFluidDataStoreRunt
     get clientId(): string | undefined;
     // (undocumented)
     get connected(): boolean;
-    // (undocumented)
-    createChannel(idArg: string | undefined, type: string): IChannel;
+    createChannel(id: string | undefined, type: string): IChannel;
     // (undocumented)
     get deltaManager(): IDeltaManagerErased;
     // (undocumented)