feat(matrix): Add oracle for event testing (#25505)

This change introduces an oracle to track `conflicts` events in a
SharedMatrix while accounting for changes, like row and column
insertions or deletions. It tracks the latest conflicts in a shared
matrix and adjusts them when rows or columns are inserted, removed, or
shifted. Captures both the conflict winner (currentValue), conflicting
value and the actual cell value (cellValue) to validate consistency.

Key updates:

1. latestConflict Map:
- Stores only the most recent conflict for each cell (row,col).
- Simplifies validation logic and ensures that the oracle always checks
the last winning value rather than needing to track an entire history of
conflicts.

2. Event Listeners for insert/remove row/col Changes:
- rowsChanged and colsChanged call updateLatestHistory to adjust
conflict entries when rows or columns are inserted or deleted.
- cellsChanged iterates over updated cells and captures the current cell
value for existing conflicts, ensuring the oracle can verify the current
state against the conflict’s expected winner.

3. updateLatestHistory Logic:
- Iterates through the latestConflict map and determines which entries
remain valid (keep = true) or should be removed if their row or column
was deleted.
- Shifts row or column indices when rows/columns are inserted beyond the
affected range.
- Uses a new map to avoid mutating latestConflict during iteration

Questions:
1. Does updateLatestHistory correctly update conflicts for all
row/column insertions and deletions?
2. Does the oracle’s structure and validation logic make sense, or is
there any inaccuracy?
3. Are there additional edge cases that need to be handled?
4. Are the event listeners (rowsChanged, colsChanged, cellsChanged)
sufficient to capture all relevant matrix updates? Is there anything
more which can be captured here?
5. How can the matrix oracle track local pending changes for a cell? 
6. Is there a bette way to validate the conflicting value and current
value?

Author: sonalideshpandemsft

packages/dds/matrix/src/test/fuzz.ts

@@ -19,6 +19,8 @@ import { isFluidHandle, toFluidHandleInternal } from "@fluidframework/runtime-ut
 import type { MatrixItem } from "../ops.js";
 import { SharedMatrix, type SharedMatrixFactory } from "../runtime.js";
 
+import { hasSharedMatrixOracle } from "./matrixOracle.js";
+
 /**
  * Supported cell values used within the fuzz model.
  */
@@ -225,7 +227,17 @@ export const baseSharedMatrixModel: Omit<
 	factory: SharedMatrix.getFactory(),
 	generatorFactory: () => takeAsync(50, makeGenerator()),
 	reducer: (state, operation) => reducer(state, operation),
-	validateConsistency: async (a, b) => assertMatricesAreEquivalent(a.channel, b.channel),
+	validateConsistency: async (a, b) => {
+		if (hasSharedMatrixOracle(a.channel)) {
+			a.channel.matrixOracle.validate();
+		}
+
+		if (hasSharedMatrixOracle(b.channel)) {
+			b.channel.matrixOracle.validate();
+		}
+
+		return assertMatricesAreEquivalent(a.channel, b.channel);
+	},
 	minimizationTransforms: ["count", "start", "row", "col"].map((p) => (op) => {
 		if (p in op && typeof op[p] === "number" && op[p] > 0) {
 			op[p]--;

packages/dds/matrix/src/test/matrix.fuzz.spec.ts

@@ -3,19 +3,29 @@
  * Licensed under the MIT License.
  */
 
-import * as path from "node:path";
-
+import { TypedEventEmitter } from "@fluid-internal/client-utils";
 import {
 	createDDSFuzzSuite,
+	registerOracle,
+	type DDSFuzzHarnessEvents,
 	type DDSFuzzModel,
 	type DDSFuzzSuiteOptions,
 } from "@fluid-private/test-dds-utils";
 import { FlushMode } from "@fluidframework/runtime-definitions/internal";
 
 import type { SharedMatrixFactory } from "../runtime.js";
 
-import { _dirname } from "./dirname.cjs";
 import { baseSharedMatrixModel, type Operation } from "./fuzz.js";
+import { SharedMatrixOracle, type IChannelWithOracles } from "./matrixOracle.js";
+
+const oracleEmitter = new TypedEventEmitter<DDSFuzzHarnessEvents>();
+
+oracleEmitter.on("clientCreate", (client) => {
+	const channel = client.channel as IChannelWithOracles;
+	const sharedMatrixOracle = new SharedMatrixOracle(channel);
+	channel.matrixOracle = sharedMatrixOracle;
+	registerOracle(sharedMatrixOracle);
+});
 
 describe("Matrix fuzz tests", function () {
 	/**
@@ -39,7 +49,7 @@ describe("Matrix fuzz tests", function () {
 			clientAddProbability: 0.1,
 		},
 		reconnectProbability: 0,
-		saveFailures: { directory: path.join(_dirname, "../../src/test/results") },
+		emitter: oracleEmitter,
 	};
 
 	const nameModel = (workloadName: string): DDSFuzzModel<SharedMatrixFactory, Operation> => ({

packages/dds/matrix/src/test/matrixOracle.ts

@@ -0,0 +1,224 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { strict as assert } from "node:assert";
+
+import type { IMatrixConsumer } from "@tiny-calc/nano";
+
+import type { ISharedMatrix, SharedMatrix } from "../matrix.js";
+
+import { TestConsumer } from "./testconsumer.js";
+
+interface IConflict<T> {
+	row: number;
+	col: number;
+	currentValue: T;
+	conflictingValue: T;
+	cellValue: T | undefined;
+	lastEvent: "conflict" | "rowChange" | "colChange" | "cellChange";
+}
+
+export class SharedMatrixOracle {
+	private readonly conflictListener: (
+		row: number,
+		col: number,
+		currentValue: unknown,
+		conflictingValue: unknown,
+	) => void;
+	private latestConflict = new Map<string, IConflict<unknown>>();
+	private readonly matrixConsumer: IMatrixConsumer<string>;
+	private readonly testConsumer: TestConsumer;
+
+	constructor(private readonly shared: SharedMatrix) {
+		this.matrixConsumer = {
+			rowsChanged: (start, removed, inserted) => {
+				this.updateLatestHistory("row", start, removed, inserted);
+			},
+			colsChanged: (start, removed, inserted) => {
+				this.updateLatestHistory("col", start, removed, inserted);
+			},
+			cellsChanged: (
+				rowStart: number,
+				colStart: number,
+				rowCount: number,
+				colCount: number,
+			) => {
+				for (let r = rowStart; r < rowStart + rowCount; r++) {
+					for (let c = colStart; c < colStart + colCount; c++) {
+						const key = `${r},${c}`;
+						const existing = this.latestConflict.get(key);
+
+						const cellValue = this.shared.getCell(r, c);
+
+						if (existing) {
+							this.latestConflict.set(key, {
+								...existing,
+								cellValue, // capture current cell value
+								lastEvent: "cellChange",
+							});
+						}
+					}
+				}
+			},
+		};
+
+		this.shared.openMatrix(this.matrixConsumer);
+		this.testConsumer = new TestConsumer(this.shared);
+
+		this.conflictListener = (row, col, currentValue, conflictingValue) => {
+			this.onConflict(row, col, currentValue, conflictingValue);
+		};
+
+		if (this.shared.connected && this.shared.isSetCellConflictResolutionPolicyFWW()) {
+			this.shared.on("conflict", this.conflictListener);
+		}
+	}
+
+	private updateLatestHistory(
+		type: "row" | "col",
+		start: number,
+		removed: number,
+		inserted: number,
+	): void {
+		const newMap = new Map<string, IConflict<unknown>>();
+
+		for (const [key, record] of this.latestConflict) {
+			let keep = true;
+			let { row, col } = record;
+
+			if (type === "row") {
+				if (row >= start && row < start + removed) {
+					keep = false; // row deleted, remove conflict
+				} else if (row >= start + removed) {
+					row += inserted - removed; // shift row
+				}
+			} else {
+				if (col >= start && col < start + removed) {
+					keep = false; // col deleted, remove conflict
+				} else if (col >= start + removed) {
+					col += inserted - removed; // shift col
+				}
+			}
+
+			if (keep) {
+				const key = `${row},${col}`;
+				newMap.set(key, {
+					...record,
+					row,
+					col,
+					lastEvent: type === "row" ? "rowChange" : "colChange",
+				});
+			}
+		}
+		this.latestConflict = newMap;
+	}
+
+	private onConflict(
+		row: number,
+		col: number,
+		currentValue: unknown,
+		conflictingValue: unknown,
+	): void {
+		assert(
+			this.shared.isSetCellConflictResolutionPolicyFWW(),
+			"conflict event should only fire in FWW mode",
+		);
+
+		// Only validate conflicts when the matrix is connected
+		if (this.shared.connected && row < this.shared.rowCount && col < this.shared.colCount) {
+			this.latestConflict.set(`${row},${col}`, {
+				row,
+				col,
+				currentValue,
+				conflictingValue,
+				cellValue: this.testConsumer.getCell(row, col),
+				lastEvent: "conflict",
+			});
+		}
+	}
+
+	public validate(): void {
+		// validate matrix
+		for (let r = 0; r < this.shared.rowCount; r++) {
+			for (let c = 0; c < this.shared.colCount; c++) {
+				const expected = this.testConsumer.getCell(r, c);
+				const actual = this.shared.getCell(r, c);
+				assert.deepStrictEqual(actual, expected, `Mismatch at [${r},${c}]`);
+			}
+		}
+
+		// Validate conflict history
+		for (const [, conflict] of this.latestConflict) {
+			const { row, col, currentValue, conflictingValue, cellValue, lastEvent } = conflict;
+			const inBounds = row < this.shared.rowCount && col < this.shared.colCount;
+			const actual = inBounds ? this.shared.getCell(row, col) : undefined;
+
+			switch (lastEvent) {
+				case "conflict": {
+					// Probably cell is not yet set
+					if (actual === undefined) continue;
+					// Winner must be present in the matrix
+					if (inBounds) {
+						assert.deepStrictEqual(
+							actual,
+							currentValue,
+							`Conflict mismatch at [${row},${col}]:
+					 expected winner=${currentValue},
+					 actual=${actual},
+					 loser=${conflictingValue} with cellValue=${cellValue}`,
+						);
+					}
+					break;
+				}
+				case "rowChange":
+				case "colChange": {
+					// Just check entry is still valid
+					assert.ok(
+						inBounds,
+						`Conflict entry at [${row},${col}] is out-of-bounds after ${lastEvent}`,
+					);
+					break;
+				}
+				case "cellChange": {
+					// Ensure what we recorded matched the matrix state at the time
+					if (inBounds) {
+						assert.deepStrictEqual(
+							actual,
+							cellValue,
+							`Cell change mismatch at [${row},${col}]:
+					 expected=${cellValue},
+					 actual=${actual}`,
+						);
+					}
+					break;
+				}
+				default: {
+					assert.fail(`Unexpected lastEvent type: ${lastEvent}`);
+				}
+			}
+		}
+	}
+
+	public dispose(): void {
+		this.shared.off("conflict", this.conflictListener);
+		this.shared.matrixProducer.closeMatrix(this.matrixConsumer);
+		this.shared.matrixProducer.closeMatrix(this.testConsumer);
+	}
+}
+
+/**
+ * @internal
+ */
+export interface IChannelWithOracles extends SharedMatrix {
+	matrixOracle: SharedMatrixOracle;
+}
+
+/**
+ * Type guard for SharedMatrix with an oracle
+ * @internal
+ */
+export function hasSharedMatrixOracle(s: ISharedMatrix): s is IChannelWithOracles {
+	return "matrixOracle" in s && s.matrixOracle instanceof SharedMatrixOracle;
+}