@fluidframework/matrix 2.117.0 → 3.0.0

package/CHANGELOG.md

@@ -1,8 +1,42 @@
 # @fluidframework/matrix
 
-## 2.117.0
+## 3.0.0
 
-Dependency updates only.
+### Minor Changes
+
+- Removal of direct CommonJS support ([#28124](https://github.com/microsoft/FluidFramework/pull/28124)) [0f84e3b8878](https://github.com/microsoft/FluidFramework/commit/0f84e3b8878a5e75b2253976d98fd963bbd9db88)
+
+  Direct `require()` import is no longer directly supported.
+  Package is transpiled as ECMAScript Module.
+
+  See [Removal of direct CommonJS support in v3.0](https://github.com/microsoft/FluidFramework/issues/27444) for more information.
+
+- Require modern TypeScript module resolution ([#27970](https://github.com/microsoft/FluidFramework/pull/27970)) [325e2016ca9](https://github.com/microsoft/FluidFramework/commit/325e2016ca9978d4a1f7552c97ba34feac9df41f)
+
+  Fluid Framework Client packages no longer include type declaration compatibility entrypoints for TypeScript's legacy Node10 resolution mode (`"moduleResolution": "node"` or `"node10"`).
+  Applications upgrading to Fluid Framework 3.0 must use one of the following supported configurations:
+  - `"module": "Node16"` with `"moduleResolution": "Node16"`
+  - `"module": "NodeNext"` with `"moduleResolution": "NodeNext"`
+  - `"module": "ESNext"` with `"moduleResolution": "Bundler"`
+
+  Existing public package entrypoints exposed through `package.json` exports, including `/alpha`, `/beta`, and `/legacy`, remain available under supported module resolution modes.
+
+  See [Removal of Node10 resolutions in v3.0](https://github.com/microsoft/FluidFramework/issues/27457) for more information.
+
+- Client packages now target ES2022 ([#27846](https://github.com/microsoft/FluidFramework/pull/27846)) [91c78541bdd](https://github.com/microsoft/FluidFramework/commit/91c78541bddcbca5d6c5f357b023eeaee617d885)
+
+  The TypeScript compilation `target` and `lib` for the Fluid Framework client packages have been raised from ES2021/ES2020 to **ES2022**.
+  The published JavaScript now uses ES2022 language features (with correspondingly less down-leveling), so consuming these packages requires a runtime that supports ES2022.
+  All actively supported Node.js versions and evergreen browsers already meet this requirement.
+
+  Note that Fluid Framework has not officially supported targets older than ES2022 since before 2.0: this is documented in [ClientRequirements.md](https://github.com/microsoft/FluidFramework/blob/main/ClientRequirements.md) as well as the README for every client package.
+
+  It is possible this change could impact users of less up to date JavaScript runtimes.
+  Impacted users can use a tool like [babel](https://babeljs.io/) to transpile out unsupported language features.
+
+- Build with TypeScript 6 ([#28052](https://github.com/microsoft/FluidFramework/pull/28052)) [7ab015c49de](https://github.com/microsoft/FluidFramework/commit/7ab015c49deec84833cdfe1fb5e1606b901f6e81)
+
+  FluidFramework Client SDK is now built using TypeScript 6. Consumers should build with TypeScript v6 or v7 or compatible tooling.
 
 ## 2.116.0
 

package/README.md

@@ -9,15 +9,15 @@ SharedMatrix is a rectangular 2D array of values. Matrix values are a superset o
 
 ## Using Fluid Framework libraries
 
-When taking a dependency on a Fluid Framework library's public APIs, we recommend using a `^` (caret) version range, such as `^1.3.4`.
-While Fluid Framework libraries may use different ranges with interdependencies between other Fluid Framework libraries,
-library consumers should always prefer `^`.
+For a dependency on a Fluid Framework library's public APIs, we recommend a `^` (caret) version range.
+For example, use `^1.3.4`.
 
-If using any of Fluid Framework's unstable APIs (for example, its `beta` APIs), we recommend using a more constrained version range, such as `~`.
+For a dependency on an unstable API, such as a `beta` API, we recommend a more restrictive version range.
+For example, use a `~` version range.
 
 ## Installation
 
-To get started, install the package by running the following command:
+Run this command to install the package:
 
 ```bash
 npm i @fluidframework/matrix
@@ -25,16 +25,16 @@ npm i @fluidframework/matrix
 
 ## Importing from this package
 
-This package leverages [package.json exports](https://nodejs.org/api/packages.html#exports) to separate its APIs by support level.
-For more information on the related support guarantees, see [API Support Levels](https://fluidframework.com/docs/build/releases-and-apitags/#api-support-levels).
+This package uses [package.json exports](https://nodejs.org/api/packages.html#exports) to separate APIs by support level.
+For information about the support guarantees, read [API Support Levels](https://fluidframework.com/docs/build/releases-and-apitags/#api-support-levels).
 
-To access the `public` ([SemVer](https://semver.org/)) APIs, import via `@fluidframework/matrix` like normal.
+Import the `public` APIs from `@fluidframework/matrix`.
 
-To access the `legacy` APIs, import via `@fluidframework/matrix/legacy`.
+Import the `legacy` APIs from `@fluidframework/matrix/legacy`.
 
 ## API Documentation
 
-API documentation for **@fluidframework/matrix** is available at <https://fluidframework.com/docs/apis/matrix>.
+Read the **@fluidframework/matrix** API documentation at <https://fluidframework.com/docs/apis/matrix>.
 
 <!-- prettier-ignore-end -->
 
@@ -183,62 +183,69 @@ ops for C1.
 
 ## Minimum Client Requirements
 
-These are the platform requirements for the current version of Fluid Framework Client Packages.
-These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter.
-For Long Term Support (LTS) versions this can require supporting these platforms for several years.
+Fluid Framework client libraries support the platforms in this document.
+These requirements are intentionally restrictive.
+Within a major version series, we can relax these requirements, but we cannot make them stricter.
+For a Long Term Support (LTS) version, we might need to support these platforms for several years.
 
-It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug.
-If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request.
-When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working.
+Other configurations can work, but Fluid Framework does not support them.
+If an unsupported configuration stops working, we do not classify this as a bug.
+To request support for a configuration that is not listed, file an issue.
+The product team will evaluate your request.
+In the issue, specify the current status of the configuration:
+
+-   The configuration works but needs official support.
+-   The configuration does not work and requires changes.
 
 ### Supported Runtimes
 
--   NodeJs ^22.22.2 except that we will drop support for it [when NodeJs 22 loses its upstream support on 2027-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS at least 1 year before 22 is end-of-life.
-    -   Running Fluid in a Node.js environment with the `--no-experimental-fetch` flag is not supported.
--   Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards).
+-   Fluid Framework supports Node.js versions 22 and 24 while they receive [upstream support](https://nodejs.org/en/about/previous-releases).
+    -   Fluid Framework will stop support for version 22 [when upstream support ends on 2027-04-30](https://github.com/nodejs/release#release-schedule).
+    -   Fluid Framework does not support Node.js with the `--no-experimental-fetch` flag.
+-   Fluid Framework supports modern browsers that support the ES2022 standard library.
 
 ### Supported Tools
 
--   TypeScript 5.4:
-    -   All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported.
-    -   [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required.
-    -   [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported.
-    -   `exactOptionalPropertyTypes` is currently not fully supported.
-        If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases.
+-   [TypeScript 6.0](https://typescriptdocs.com/release-notes/TypeScript%206.0):
+    -   Fluid Framework supports all [`strict`](https://www.typescriptlang.org/tsconfig) options.
+    -   Set the build targets (`lib`, `target`) to `ES2022` or later.
+    -   Enable [`strictNullChecks`](https://www.typescriptlang.org/tsconfig).
+    -   Fluid Framework does not support [configuration options deprecated in TypeScript 6.0](https://typescriptdocs.com/release-notes/TypeScript%206.0#breaking-changes-and-deprecations-in-typescript-6-0).
+    -   Fluid Framework does not fully support `exactOptionalPropertyTypes`.
+        If you enable this option, do not use `in`, `Reflect.has`, `Object.hasOwn`, or `Object.prototype.hasOwnProperty` to narrow members of Fluid Framework types.
+        These methods can incorrectly exclude `undefined` from the possible values.
 -   [webpack](https://webpack.js.org/) 5
-    -   We are not intending to be prescriptive about what bundler to use.
-        Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test.
+    -   We do not require a specific bundler.
+        Other bundlers that handle ES Modules can work, but we actively test only webpack.
 
 ### Module Resolution
 
-[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm).
-Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development.
+In TypeScript `compilerOptions`, use [`Node16`, `Node20`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) module resolution.
+These settings follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm).
+
+Do not use `Node10` module resolution.
 
 ### Module Formats
 
 -   ES Modules:
-    ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported.
--   CommonJs:
-    Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below.
-    This is done to accommodate some workflows without good ES Module support.
-    If you have a workflow you would like included in this list, file an issue.
-    Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here.
-
-    -   Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648))
+    Use ES Modules to consume Fluid Framework client packages, including in Node.js.
+-   CommonJS:
+    Fluid Framework does not officially support CommonJS in version 3.0 or later.
 
 ## Contribution Guidelines
 
-There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid.
+You can [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid Framework in these ways:
 
--   Participate in Q&A in our [GitHub Discussions](https://github.com/microsoft/FluidFramework/discussions).
--   [Submit bugs](https://github.com/microsoft/FluidFramework/issues) and help us verify fixes as they are checked in.
--   Review the [source code changes](https://github.com/microsoft/FluidFramework/pulls).
+-   Answer questions in [GitHub Discussions](https://github.com/microsoft/FluidFramework/discussions).
+-   [Submit bug reports](https://github.com/microsoft/FluidFramework/issues) and help verify fixes.
+-   Review [source code changes](https://github.com/microsoft/FluidFramework/pulls).
 -   [Contribute bug fixes](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md).
 
-Detailed instructions for working in the repo can be found in the [Wiki](https://github.com/microsoft/FluidFramework/blob/main/docs/content/Home.md).
+For detailed instructions, read the [repo documentation](https://github.com/microsoft/FluidFramework/blob/main/docs/content/Home.md).
 
-This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
-For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+This project follows the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information, read the [Code of Conduct frequently asked questions](https://opensource.microsoft.com/codeofconduct/faq/).
+For questions or comments, contact [opencode@microsoft.com](mailto:opencode@microsoft.com).
 
 This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services.
 Use of these trademarks or logos must follow Microsoft’s [Trademark & Brand Guidelines](https://www.microsoft.com/trademarks).
@@ -246,13 +253,9 @@ Use of Microsoft trademarks or logos in modified versions of this project must n
 
 ## Help
 
-Not finding what you're looking for in this README?
-Check out [fluidframework.com](https://fluidframework.com/docs/).
-
-Still not finding what you're looking for?
-Please [file an issue](https://github.com/microsoft/FluidFramework/blob/main/docs/content/Contributing/Submitting-Bugs-and-Feature-Requests.md).
+Read the [Fluid Framework documentation](https://fluidframework.com/docs/) for information about Fluid Framework concepts and APIs.
 
-Thank you!
+To request information that the documentation does not contain, [create an issue](https://github.com/microsoft/FluidFramework/blob/main/docs/content/Contributing/Submitting-Bugs-and-Feature-Requests.md).
 
 ## Trademark
 

package/{api-extractor.json → api-extractor/api-extractor-model.json}

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-model.esm.json"
+	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-model.esm.json"
 }

package/dist/handlecache.js

@@ -16,10 +16,11 @@ const range_js_1 = require("./range.js");
  * so far there's no measurable perf penalty for being a separate object (node 12 x64)
  */
 class HandleCache {
+    vector;
+    handles = [];
+    start = 0;
     constructor(vector) {
         this.vector = vector;
-        this.handles = [];
-        this.start = 0;
     }
     /**
      * Returns the index of the given position in the 'handles' array as a Uint32.

package/dist/handlecache.js.map

@@ -1 +1 @@
-{"version":3,"file":"handlecache.js","sourceRoot":"","sources":["../src/handlecache.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/* eslint-disable no-bitwise */\n\nimport { assert } from \"@fluidframework/core-utils/internal\";\nimport type { IVectorConsumer } from \"@tiny-calc/nano\";\n\nimport { type Handle, isHandleValid } from \"./handletable.js\";\nimport type { PermutationSegment, PermutationVector } from \"./permutationvector.js\";\nimport { ensureRange } from \"./range.js\";\n\n/**\n * Used by PermutationVector to cache position -\\> handle lookups.\n *\n * Perf: Possibly, this should eventually be inlined into PermutationVector itself, but\n * so far there's no measurable perf penalty for being a separate object (node 12 x64)\n */\nexport class HandleCache implements IVectorConsumer<Handle> {\n\tprivate handles: Handle[] = [];\n\tprivate start = 0;\n\n\tconstructor(public readonly vector: PermutationVector) {}\n\n\t/**\n\t * Returns the index of the given position in the 'handles' array as a Uint32.\n\t * (If the position is not in the array, returns an integer greater than 'handles.length').\n\t */\n\tprivate getIndex(position: number): number {\n\t\treturn (position - this.start) >>> 0;\n\t}\n\n\t/**\n\t * Returns the handle currently assigned to the given 'position' (if any).  Check\n\t * the result with 'isValidHandle(..)' to see if a handle has been allocated for\n\t * the given position.\n\t *\n\t * @throws A 'RangeError' if the provided 'position' is out-of-bounds with regards to the\n\t * PermutationVector's length.\n\t */\n\tpublic getHandle(position: number): Handle {\n\t\tconst index = this.getIndex(position);\n\n\t\t// Perf: To encourage inlining, handling of the 'cacheMiss(..)' case has been extracted\n\t\t//       to a separate method.\n\n\t\t// Perf: A cache hit implies that 'position' was in bounds.  Therefore, we can defer\n\t\t//       checking that 'position' is in bounds until 'cacheMiss(..)'.  This yields an\n\t\t//       ~40% speedup when the position is in the cache (node v12 x64).\n\n\t\treturn index < this.handles.length ? this.handles[index] : this.cacheMiss(position);\n\t}\n\n\t/**\n\t * Update the cache when a handle has been allocated for a given position.\n\t */\n\tpublic addHandle(position: number, handle: Handle): void {\n\t\tassert(isHandleValid(handle), 0x017 /* \"Trying to add invalid handle!\" */);\n\n\t\tconst index = this.getIndex(position);\n\t\tif (index < this.handles.length) {\n\t\t\tassert(\n\t\t\t\t!isHandleValid(this.handles[index]),\n\t\t\t\t0x018 /* \"Trying to insert handle into position with already valid handle!\" */,\n\t\t\t);\n\t\t\tthis.handles[index] = handle;\n\t\t}\n\t}\n\n\t/**\n\t * Used by {@link HandleCache.cacheMiss} to retrieve handles for a range of positions.\n\t * @param start - The start position (inclusive).\n\t * @param end - The end position (exclusive).\n\t * @param handles - The array to populate with handles. Note that it is mutated in place.\n\t */\n\tprivate getHandles(start: number, end: number, handles: Handle[]): void {\n\t\t// TODO: This can be accelerated substantially using 'walkSegments()'.  The only catch\n\t\t//       is that\n\n\t\tconst { vector } = this;\n\n\t\tfor (let pos = start; pos < end; pos++) {\n\t\t\t// eslint-disable-next-line @typescript-eslint/no-non-null-assertion\n\t\t\tconst { segment, offset } = vector.getContainingSegment(pos)!;\n\t\t\tconst asPerm = segment as PermutationSegment;\n\t\t\thandles.push(asPerm.start + offset);\n\t\t}\n\t}\n\n\tprivate cacheMiss(position: number): Handle {\n\t\t// Coercing 'position' to an Uint32 allows us to handle a negative 'position' value\n\t\t// with the same logic that handles 'position' >= length.\n\t\tconst _position = position >>> 0;\n\n\t\t// TODO: To bound memory usage, there should be a limit on the maximum size of\n\t\t//       handle[].\n\n\t\t// TODO: To reduce MergeTree lookups, this code should opportunistically grow\n\t\t//       the cache to the next MergeTree segment boundary (within the limits of\n\t\t//       the handle cache).\n\n\t\tif (_position < this.start) {\n\t\t\tconst handles: Handle[] = [];\n\t\t\tthis.getHandles(_position, this.start, handles);\n\t\t\thandles.push(...this.handles);\n\t\t\tthis.handles = handles;\n\t\t\tthis.start = _position;\n\t\t\treturn this.handles[0];\n\t\t} else {\n\t\t\tensureRange(_position, this.vector.getLength());\n\t\t\tthis.getHandles(this.start + this.handles.length, _position + 1, this.handles);\n\t\t\treturn this.handles[this.handles.length - 1];\n\t\t}\n\t}\n\n\t// #region IVectorConsumer\n\n\titemsChanged(start: number, removedCount: number, insertedCount: number): void {\n\t\t// If positions were inserted/removed, our current policy is to trim the array\n\t\t// at the beginning of the invalidate range and lazily repopulate the handles\n\t\t// on demand.\n\t\t//\n\t\t// Some alternatives to consider that preserve the previously cached handles\n\t\t// that are still valid:\n\t\t//\n\t\t//      * Eagerly populate the 'handles[]' with the newly insert values (currently guaranteed\n\t\t//        to be Handle.unallocated, so we don't even need to look them up.)\n\t\t//\n\t\t//      * Use a sentinel value or other mechanism to allow \"holes\" in the cache.\n\n\t\tconst index = this.getIndex(start);\n\t\tif (index < this.handles.length) {\n\t\t\tthis.handles.length = index;\n\t\t}\n\t}\n\n\t// #endregion IVectorConsumer\n}\n"]}
+{"version":3,"file":"handlecache.js","sourceRoot":"","sources":["../src/handlecache.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/* eslint-disable no-bitwise */\n\nimport { assert } from \"@fluidframework/core-utils/internal\";\nimport type { IVectorConsumer } from \"@tiny-calc/nano\";\n\nimport { type Handle, isHandleValid } from \"./handletable.js\";\nimport type { PermutationSegment, PermutationVector } from \"./permutationvector.js\";\nimport { ensureRange } from \"./range.js\";\n\n/**\n * Used by PermutationVector to cache position -\\> handle lookups.\n *\n * Perf: Possibly, this should eventually be inlined into PermutationVector itself, but\n * so far there's no measurable perf penalty for being a separate object (node 12 x64)\n */\nexport class HandleCache implements IVectorConsumer<Handle> {\n\tprivate handles: Handle[] = [];\n\tprivate start = 0;\n\n\tconstructor(public readonly vector: PermutationVector) {}\n\n\t/**\n\t * Returns the index of the given position in the 'handles' array as a Uint32.\n\t * (If the position is not in the array, returns an integer greater than 'handles.length').\n\t */\n\tprivate getIndex(position: number): number {\n\t\treturn (position - this.start) >>> 0;\n\t}\n\n\t/**\n\t * Returns the handle currently assigned to the given 'position' (if any).  Check\n\t * the result with 'isValidHandle(..)' to see if a handle has been allocated for\n\t * the given position.\n\t *\n\t * @throws A 'RangeError' if the provided 'position' is out-of-bounds with regards to the\n\t * PermutationVector's length.\n\t */\n\tpublic getHandle(position: number): Handle {\n\t\tconst index = this.getIndex(position);\n\n\t\t// Perf: To encourage inlining, handling of the 'cacheMiss(..)' case has been extracted\n\t\t//       to a separate method.\n\n\t\t// Perf: A cache hit implies that 'position' was in bounds.  Therefore, we can defer\n\t\t//       checking that 'position' is in bounds until 'cacheMiss(..)'.  This yields an\n\t\t//       ~40% speedup when the position is in the cache (node v12 x64).\n\n\t\treturn index < this.handles.length ? this.handles[index] : this.cacheMiss(position);\n\t}\n\n\t/**\n\t * Update the cache when a handle has been allocated for a given position.\n\t */\n\tpublic addHandle(position: number, handle: Handle): void {\n\t\tassert(isHandleValid(handle), 0x017 /* \"Trying to add invalid handle!\" */);\n\n\t\tconst index = this.getIndex(position);\n\t\tif (index < this.handles.length) {\n\t\t\tassert(\n\t\t\t\t!isHandleValid(this.handles[index]),\n\t\t\t\t0x018 /* \"Trying to insert handle into position with already valid handle!\" */,\n\t\t\t);\n\t\t\tthis.handles[index] = handle;\n\t\t}\n\t}\n\n\t/**\n\t * Used by {@link HandleCache.cacheMiss} to retrieve handles for a range of positions.\n\t * @param start - The start position (inclusive).\n\t * @param end - The end position (exclusive).\n\t * @param handles - The array to populate with handles. Note that it is mutated in place.\n\t */\n\tprivate getHandles(start: number, end: number, handles: Handle[]): void {\n\t\t// TODO: This can be accelerated substantially using 'walkSegments()'.  The only catch\n\t\t//       is that\n\n\t\tconst { vector } = this;\n\n\t\tfor (let pos = start; pos < end; pos++) {\n\t\t\t// eslint-disable-next-line @typescript-eslint/no-non-null-assertion\n\t\t\tconst { segment, offset } = vector.getContainingSegment(pos)!;\n\t\t\tconst asPerm = segment as PermutationSegment;\n\t\t\thandles.push(asPerm.start + offset);\n\t\t}\n\t}\n\n\tprivate cacheMiss(position: number): Handle {\n\t\t// Coercing 'position' to an Uint32 allows us to handle a negative 'position' value\n\t\t// with the same logic that handles 'position' >= length.\n\t\tconst _position = position >>> 0;\n\n\t\t// TODO: To bound memory usage, there should be a limit on the maximum size of\n\t\t//       handle[].\n\n\t\t// TODO: To reduce MergeTree lookups, this code should opportunistically grow\n\t\t//       the cache to the next MergeTree segment boundary (within the limits of\n\t\t//       the handle cache).\n\n\t\tif (_position < this.start) {\n\t\t\tconst handles: Handle[] = [];\n\t\t\tthis.getHandles(_position, this.start, handles);\n\t\t\thandles.push(...this.handles);\n\t\t\tthis.handles = handles;\n\t\t\tthis.start = _position;\n\t\t\treturn this.handles[0];\n\t\t} else {\n\t\t\tensureRange(_position, this.vector.getLength());\n\t\t\tthis.getHandles(this.start + this.handles.length, _position + 1, this.handles);\n\t\t\treturn this.handles[this.handles.length - 1];\n\t\t}\n\t}\n\n\t// #region IVectorConsumer\n\n\titemsChanged(start: number, removedCount: number, insertedCount: number): void {\n\t\t// If positions were inserted/removed, our current policy is to trim the array\n\t\t// at the beginning of the invalidate range and lazily repopulate the handles\n\t\t// on demand.\n\t\t//\n\t\t// Some alternatives to consider that preserve the previously cached handles\n\t\t// that are still valid:\n\t\t//\n\t\t//      * Eagerly populate the 'handles[]' with the newly insert values (currently guaranteed\n\t\t//        to be Handle.unallocated, so we don't even need to look them up.)\n\t\t//\n\t\t//      * Use a sentinel value or other mechanism to allow \"holes\" in the cache.\n\n\t\tconst index = this.getIndex(start);\n\t\tif (index < this.handles.length) {\n\t\t\tthis.handles.length = index;\n\t\t}\n\t}\n\n\t// #endregion IVectorConsumer\n}\n"]}

package/dist/handletable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handletable.d.ts","sourceRoot":"","sources":["../src/handletable.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,0BAAkB,MAAM;IACvB;;OAEG;IACH,IAAI,IAAI;IAER;;OAEG;IACH,KAAK,IAAI;IAET;;;OAGG;IACH,WAAW,cAAc;CACzB;AAED,eAAO,MAAM,aAAa,WAAY,MAAM,KAAG,OAAiC,CAAC;AAEjF;;GAEG;AACH,qBAAa,WAAW,CAAC,CAAC;IAIN,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,GAAE,CAAC,MAAM,GAAG,CAAC,CAAC,EAAQ;IAE1D,KAAK,IAAI,IAAI;IAOpB;;OAEG;IACI,QAAQ,IAAI,MAAM;IAmBzB;;OAEG;IACI,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW;IAQ/C;;OAEG;IACI,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAKjC;;OAEG;IACI,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC;IAI7B;;OAEG;IACI,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAM1C,OAAO,KAAK,IAAI,GAEf;IACD,OAAO,KAAK,IAAI,QAEf;IAEM,iBAAiB,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE;WAI5B,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,GAAG,WAAW,CAAC,CAAC,CAAC;CAG3D"}
+{"version":3,"file":"handletable.d.ts","sourceRoot":"","sources":["../src/handletable.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,0BAAkB,MAAM;IACvB;;OAEG;IACH,IAAI,IAAI;IAER;;OAEG;IACH,KAAK,IAAI;IAET;;;OAGG;IACH,WAAW,cAAc;CACzB;AAED,eAAO,MAAM,aAAa,GAAI,QAAQ,MAAM,KAAG,OAAiC,CAAC;AAEjF;;GAEG;AACH,qBAAa,WAAW,CAAC,CAAC;IAIN,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,GAAE,CAAC,MAAM,GAAG,CAAC,CAAC,EAAQ;IAE1D,KAAK,IAAI,IAAI;IAOpB;;OAEG;IACI,QAAQ,IAAI,MAAM;IAmBzB;;OAEG;IACI,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW;IAQ/C;;OAEG;IACI,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAKjC;;OAEG;IACI,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC;IAI7B;;OAEG;IACI,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAM1C,OAAO,KAAK,IAAI,GAEf;IACD,OAAO,KAAK,IAAI,QAEf;IAEM,iBAAiB,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE;WAI5B,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,GAAG,WAAW,CAAC,CAAC,CAAC;CAG3D"}

package/dist/handletable.js

@@ -11,6 +11,7 @@ exports.isHandleValid = isHandleValid;
  * A handle table provides a fast mapping from an integer `handle` to a value `T`.
  */
 class HandleTable {
+    handles;
     // Note: the first slot of the 'handles' array is reserved to store the pointer to the first
     //       free handle.  We initialize this slot with a pointer to slot '1', which will cause
     //       us to delay allocate the following slot in the array on the first allocation.

package/dist/handletable.js.map

@@ -1 +1 @@
-{"version":3,"file":"handletable.js","sourceRoot":"","sources":["../src/handletable.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAoBI,MAAM,aAAa,GAAG,CAAC,MAAc,EAAW,EAAE,CAAC,MAAM,wBAAgB,CAAC;AAApE,QAAA,aAAa,iBAAuD;AAEjF;;GAEG;AACH,MAAa,WAAW;IACvB,4FAA4F;IAC5F,2FAA2F;IAC3F,sFAAsF;IACtF,YAAoC,UAA0B,CAAC,CAAC,CAAC;QAA7B,YAAO,GAAP,OAAO,CAAsB;IAAG,CAAC;IAE9D,KAAK;QACX,qFAAqF;QACrF,uFAAuF;QACvF,oBAAoB;QACpB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAChD,CAAC;IAED;;OAEG;IACI,QAAQ;QACd,wCAAwC;QACxC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QAEvB,mFAAmF;QACnF,uFAAuF;QACvF,qFAAqF;QACrF,sFAAsF;QACtF,6DAA6D;QAC7D,IAAI,CAAC,IAAI,GAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAY,IAAI,IAAI,GAAG,CAAC,CAAC;QAEvD,mFAAmF;QACnF,sFAAsF;QACtF,qBAAqB;QACrB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,sBAAc,CAAC;QAEjC,OAAO,IAAI,CAAC;IACb,CAAC;IAED;;OAEG;IACI,YAAY,CAAC,KAAa;QAChC,MAAM,OAAO,GAAG,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC;QACvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;YAChC,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC9B,CAAC;QACD,OAAO,OAAO,CAAC;IAChB,CAAC;IAED;;OAEG;IACI,IAAI,CAAC,MAAc;QACzB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC;IACpB,CAAC;IAED;;OAEG;IACI,GAAG,CAAC,MAAc;QACxB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAM,CAAC;IAClC,CAAC;IAED;;OAEG;IACI,GAAG,CAAC,MAAc,EAAE,KAAQ;QAClC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC;IAC9B,CAAC;IAED,wFAAwF;IACxF,uBAAuB;IACvB,IAAY,IAAI;QACf,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,CAAW,CAAC;IAClC,CAAC;IACD,IAAY,IAAI,CAAC,MAAc;QAC9B,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;IAC1B,CAAC;IAEM,iBAAiB;QACvB,OAAO,IAAI,CAAC,OAAO,CAAC;IACrB,CAAC;IAEM,MAAM,CAAC,IAAI,CAAI,IAAoB;QACzC,OAAO,IAAI,WAAW,CAAI,IAAI,CAAC,CAAC;IACjC,CAAC;CACD;AApFD,kCAoFC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport const enum Handle {\n\t/**\n\t * Sentinel representing the absence of a valid handle.\n\t */\n\tnone = 0,\n\n\t/**\n\t * Minimum valid handle.\n\t */\n\tvalid = 1,\n\n\t/**\n\t * Sentinel representing an unallocated Handle.  Used by PermutationVector\n\t * to delay allocate handles when previously empty row/cols become populated.\n\t */\n\tunallocated = -0x80000000,\n}\n\nexport const isHandleValid = (handle: Handle): boolean => handle >= Handle.valid;\n\n/**\n * A handle table provides a fast mapping from an integer `handle` to a value `T`.\n */\nexport class HandleTable<T> {\n\t// Note: the first slot of the 'handles' array is reserved to store the pointer to the first\n\t//       free handle.  We initialize this slot with a pointer to slot '1', which will cause\n\t//       us to delay allocate the following slot in the array on the first allocation.\n\tpublic constructor(private readonly handles: (Handle | T)[] = [1]) {}\n\n\tpublic clear(): void {\n\t\t// Restore the HandleTable's initial state by deleting all items in the handles array\n\t\t// and then re-inserting the value '1' in the 0th slot.  (See comment at `handles` decl\n\t\t// for explanation.)\n\t\tthis.handles.splice(0, this.handles.length, 1);\n\t}\n\n\t/**\n\t * Allocates and returns the next available handle.  Note that freed handles are recycled.\n\t */\n\tpublic allocate(): Handle {\n\t\t// Get the handle to the next free slot.\n\t\tconst free = this.next;\n\n\t\t// Update 'next' to point to the new head of the free list.  We use the contents of\n\t\t// recycled slots to store the free list.  The contents of the handles[free] will point\n\t\t// to the next available slot.  If there are no free slots (i.e., 'handles' is full),\n\t\t// the slot will point to 'handles.length'.  In this case, the handles array will grow\n\t\t// and we update 'next' to point to the new end of the array.\n\t\tthis.next = (this.handles[free] as Handle) ?? free + 1;\n\n\t\t// Out of paranoia, overwrite the contents of the newly allocated free slot with an\n\t\t// invalid handle value.  This may help catch/diagnose bugs in the event the free list\n\t\t// becomes corrupted.\n\t\tthis.handles[free] = Handle.none;\n\n\t\treturn free;\n\t}\n\n\t/**\n\t * Allocates and returns the next available `count` handles.\n\t */\n\tpublic allocateMany(count: Handle): Uint32Array {\n\t\tconst handles = new Uint32Array(count);\n\t\tfor (let i = 0; i < count; i++) {\n\t\t\thandles[i] = this.allocate();\n\t\t}\n\t\treturn handles;\n\t}\n\n\t/**\n\t * Returns the given handle to the free list.\n\t */\n\tpublic free(handle: Handle): void {\n\t\tthis.handles[handle] = this.next;\n\t\tthis.next = handle;\n\t}\n\n\t/**\n\t * Get the value `T` associated with the given handle, if any.\n\t */\n\tpublic get(handle: Handle): T {\n\t\treturn this.handles[handle] as T;\n\t}\n\n\t/**\n\t * Set the value `T` associated with the given handle.\n\t */\n\tpublic set(handle: Handle, value: T): void {\n\t\tthis.handles[handle] = value;\n\t}\n\n\t// Private helpers to get/set the head of the free list, which is stored in the 0th slot\n\t// of the handle array.\n\tprivate get next(): Handle {\n\t\treturn this.handles[0] as Handle;\n\t}\n\tprivate set next(handle: Handle) {\n\t\tthis.handles[0] = handle;\n\t}\n\n\tpublic getSummaryContent(): (Handle | T)[] {\n\t\treturn this.handles;\n\t}\n\n\tpublic static load<T>(data: (Handle | T)[]): HandleTable<T> {\n\t\treturn new HandleTable<T>(data);\n\t}\n}\n"]}
+{"version":3,"file":"handletable.js","sourceRoot":"","sources":["../src/handletable.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAoBI,MAAM,aAAa,GAAG,CAAC,MAAc,EAAW,EAAE,CAAC,MAAM,wBAAgB,CAAC;AAApE,QAAA,aAAa,iBAAuD;AAEjF;;GAEG;AACH,MAAa,WAAW;IAIa;IAHpC,4FAA4F;IAC5F,2FAA2F;IAC3F,sFAAsF;IACtF,YAAoC,UAA0B,CAAC,CAAC,CAAC;QAA7B,YAAO,GAAP,OAAO,CAAsB;IAAG,CAAC;IAE9D,KAAK;QACX,qFAAqF;QACrF,uFAAuF;QACvF,oBAAoB;QACpB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAChD,CAAC;IAED;;OAEG;IACI,QAAQ;QACd,wCAAwC;QACxC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QAEvB,mFAAmF;QACnF,uFAAuF;QACvF,qFAAqF;QACrF,sFAAsF;QACtF,6DAA6D;QAC7D,IAAI,CAAC,IAAI,GAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAY,IAAI,IAAI,GAAG,CAAC,CAAC;QAEvD,mFAAmF;QACnF,sFAAsF;QACtF,qBAAqB;QACrB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,sBAAc,CAAC;QAEjC,OAAO,IAAI,CAAC;IACb,CAAC;IAED;;OAEG;IACI,YAAY,CAAC,KAAa;QAChC,MAAM,OAAO,GAAG,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC;QACvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;YAChC,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC9B,CAAC;QACD,OAAO,OAAO,CAAC;IAChB,CAAC;IAED;;OAEG;IACI,IAAI,CAAC,MAAc;QACzB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC;IACpB,CAAC;IAED;;OAEG;IACI,GAAG,CAAC,MAAc;QACxB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAM,CAAC;IAClC,CAAC;IAED;;OAEG;IACI,GAAG,CAAC,MAAc,EAAE,KAAQ;QAClC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC;IAC9B,CAAC;IAED,wFAAwF;IACxF,uBAAuB;IACvB,IAAY,IAAI;QACf,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,CAAW,CAAC;IAClC,CAAC;IACD,IAAY,IAAI,CAAC,MAAc;QAC9B,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;IAC1B,CAAC;IAEM,iBAAiB;QACvB,OAAO,IAAI,CAAC,OAAO,CAAC;IACrB,CAAC;IAEM,MAAM,CAAC,IAAI,CAAI,IAAoB;QACzC,OAAO,IAAI,WAAW,CAAI,IAAI,CAAC,CAAC;IACjC,CAAC;CACD;AApFD,kCAoFC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport const enum Handle {\n\t/**\n\t * Sentinel representing the absence of a valid handle.\n\t */\n\tnone = 0,\n\n\t/**\n\t * Minimum valid handle.\n\t */\n\tvalid = 1,\n\n\t/**\n\t * Sentinel representing an unallocated Handle.  Used by PermutationVector\n\t * to delay allocate handles when previously empty row/cols become populated.\n\t */\n\tunallocated = -0x80000000,\n}\n\nexport const isHandleValid = (handle: Handle): boolean => handle >= Handle.valid;\n\n/**\n * A handle table provides a fast mapping from an integer `handle` to a value `T`.\n */\nexport class HandleTable<T> {\n\t// Note: the first slot of the 'handles' array is reserved to store the pointer to the first\n\t//       free handle.  We initialize this slot with a pointer to slot '1', which will cause\n\t//       us to delay allocate the following slot in the array on the first allocation.\n\tpublic constructor(private readonly handles: (Handle | T)[] = [1]) {}\n\n\tpublic clear(): void {\n\t\t// Restore the HandleTable's initial state by deleting all items in the handles array\n\t\t// and then re-inserting the value '1' in the 0th slot.  (See comment at `handles` decl\n\t\t// for explanation.)\n\t\tthis.handles.splice(0, this.handles.length, 1);\n\t}\n\n\t/**\n\t * Allocates and returns the next available handle.  Note that freed handles are recycled.\n\t */\n\tpublic allocate(): Handle {\n\t\t// Get the handle to the next free slot.\n\t\tconst free = this.next;\n\n\t\t// Update 'next' to point to the new head of the free list.  We use the contents of\n\t\t// recycled slots to store the free list.  The contents of the handles[free] will point\n\t\t// to the next available slot.  If there are no free slots (i.e., 'handles' is full),\n\t\t// the slot will point to 'handles.length'.  In this case, the handles array will grow\n\t\t// and we update 'next' to point to the new end of the array.\n\t\tthis.next = (this.handles[free] as Handle) ?? free + 1;\n\n\t\t// Out of paranoia, overwrite the contents of the newly allocated free slot with an\n\t\t// invalid handle value.  This may help catch/diagnose bugs in the event the free list\n\t\t// becomes corrupted.\n\t\tthis.handles[free] = Handle.none;\n\n\t\treturn free;\n\t}\n\n\t/**\n\t * Allocates and returns the next available `count` handles.\n\t */\n\tpublic allocateMany(count: Handle): Uint32Array {\n\t\tconst handles = new Uint32Array(count);\n\t\tfor (let i = 0; i < count; i++) {\n\t\t\thandles[i] = this.allocate();\n\t\t}\n\t\treturn handles;\n\t}\n\n\t/**\n\t * Returns the given handle to the free list.\n\t */\n\tpublic free(handle: Handle): void {\n\t\tthis.handles[handle] = this.next;\n\t\tthis.next = handle;\n\t}\n\n\t/**\n\t * Get the value `T` associated with the given handle, if any.\n\t */\n\tpublic get(handle: Handle): T {\n\t\treturn this.handles[handle] as T;\n\t}\n\n\t/**\n\t * Set the value `T` associated with the given handle.\n\t */\n\tpublic set(handle: Handle, value: T): void {\n\t\tthis.handles[handle] = value;\n\t}\n\n\t// Private helpers to get/set the head of the free list, which is stored in the 0th slot\n\t// of the handle array.\n\tprivate get next(): Handle {\n\t\treturn this.handles[0] as Handle;\n\t}\n\tprivate set next(handle: Handle) {\n\t\tthis.handles[0] = handle;\n\t}\n\n\tpublic getSummaryContent(): (Handle | T)[] {\n\t\treturn this.handles;\n\t}\n\n\tpublic static load<T>(data: (Handle | T)[]): HandleTable<T> {\n\t\treturn new HandleTable<T>(data);\n\t}\n}\n"]}

package/dist/matrix.js

@@ -38,6 +38,28 @@ const undoprovider_js_1 = require("./undoprovider.js");
 // TODO: if possible, transition SharedMatrix to not use `any`.
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 class SharedMatrix extends internal_4.SharedObject {
+    id;
+    consumers = new Set();
+    /**
+     * Note: this field only provides a lower-bound on the reference sequence numbers for in-flight ops.
+     * The exact reason isn't understood, but some e2e tests suggest that the runtime may sometimes process
+     * incoming leave/join ops before putting an op that this DDS submits over the wire.
+     *
+     * E.g. SharedMatrix submits an op while deltaManager has lastSequenceNumber = 10, but before the runtime
+     * puts this op over the wire, it processes a client join/leave op with sequence number 11, so the referenceSequenceNumber
+     * on the SharedMatrix op is 11.
+     */
+    inFlightRefSeqs = new double_ended_queue_1.default();
+    getMinInFlightRefSeq = () => this.inFlightRefSeqs.get(0);
+    rows; // Map logical row to storage handle (if any)
+    cols; // Map logical col to storage handle (if any)
+    cells = new sparsearray2d_js_1.SparseArray2D(); // Stores cell values.
+    pending = new sparsearray2d_js_1.SparseArray2D(); // Tracks pending writes.
+    fwwPolicy = {
+        state: "off",
+    };
+    // Used to track if there is any reentrancy in setCell code.
+    reentrantCount = 0;
     /**
      * Constructor for the Shared Matrix
      * @param runtime - DataStore runtime.
@@ -49,62 +71,10 @@ class SharedMatrix extends internal_4.SharedObject {
     constructor(runtime, id, attributes) {
         super(id, runtime, attributes, "fluid_matrix_");
         this.id = id;
-        this.consumers = new Set();
-        /**
-         * Note: this field only provides a lower-bound on the reference sequence numbers for in-flight ops.
-         * The exact reason isn't understood, but some e2e tests suggest that the runtime may sometimes process
-         * incoming leave/join ops before putting an op that this DDS submits over the wire.
-         *
-         * E.g. SharedMatrix submits an op while deltaManager has lastSequenceNumber = 10, but before the runtime
-         * puts this op over the wire, it processes a client join/leave op with sequence number 11, so the referenceSequenceNumber
-         * on the SharedMatrix op is 11.
-         */
-        this.inFlightRefSeqs = new double_ended_queue_1.default();
-        this.getMinInFlightRefSeq = () => this.inFlightRefSeqs.get(0);
-        this.cells = new sparsearray2d_js_1.SparseArray2D(); // Stores cell values.
-        this.pending = new sparsearray2d_js_1.SparseArray2D(); // Tracks pending writes.
-        this.fwwPolicy = {
-            state: "off",
-        };
-        // Used to track if there is any reentrancy in setCell code.
-        this.reentrantCount = 0;
-        // Invoked by PermutationVector to notify IMatrixConsumers of row insertion/deletions.
-        this.onRowDelta = (position, removedCount, insertedCount) => {
-            for (const consumer of this.consumers) {
-                consumer.rowsChanged(position, removedCount, insertedCount, this);
-            }
-        };
-        // Invoked by PermutationVector to notify IMatrixConsumers of col insertion/deletions.
-        this.onColDelta = (position, removedCount, insertedCount) => {
-            for (const consumer of this.consumers) {
-                consumer.colsChanged(position, removedCount, insertedCount, this);
-            }
-        };
-        this.onRowHandlesRecycled = (rowHandles) => {
-            for (const rowHandle of rowHandles) {
-                this.cells.clearRows(/* rowStart: */ rowHandle, /* rowCount: */ 1);
-                this.pending.clearRows(/* rowStart: */ rowHandle, /* rowCount: */ 1);
-                if (this.fwwPolicy.state === "on") {
-                    this.fwwPolicy.cellLastWriteTracker?.clearRows(
-                    /* rowStart: */ rowHandle, 
-                    /* rowCount: */ 1);
-                }
-            }
-        };
-        this.onColHandlesRecycled = (colHandles) => {
-            for (const colHandle of colHandles) {
-                this.cells.clearCols(/* colStart: */ colHandle, /* colCount: */ 1);
-                this.pending.clearCols(/* colStart: */ colHandle, /* colCount: */ 1);
-                if (this.fwwPolicy.state === "on") {
-                    this.fwwPolicy.cellLastWriteTracker?.clearCols(
-                    /* colStart: */ colHandle, 
-                    /* colCount: */ 1);
-                }
-            }
-        };
         this.rows = new permutationvector_js_1.PermutationVector(ops_js_1.SnapshotPath.rows, this.logger, runtime, this.onRowDelta, this.onRowHandlesRecycled, this.getMinInFlightRefSeq);
         this.cols = new permutationvector_js_1.PermutationVector(ops_js_1.SnapshotPath.cols, this.logger, runtime, this.onColDelta, this.onColHandlesRecycled, this.getMinInFlightRefSeq);
     }
+    undo;
     /**
      * Subscribes the given IUndoConsumer to the matrix.
      */
@@ -705,6 +675,40 @@ class SharedMatrix extends internal_4.SharedObject {
             }
         }
     }
+    // Invoked by PermutationVector to notify IMatrixConsumers of row insertion/deletions.
+    onRowDelta = (position, removedCount, insertedCount) => {
+        for (const consumer of this.consumers) {
+            consumer.rowsChanged(position, removedCount, insertedCount, this);
+        }
+    };
+    // Invoked by PermutationVector to notify IMatrixConsumers of col insertion/deletions.
+    onColDelta = (position, removedCount, insertedCount) => {
+        for (const consumer of this.consumers) {
+            consumer.colsChanged(position, removedCount, insertedCount, this);
+        }
+    };
+    onRowHandlesRecycled = (rowHandles) => {
+        for (const rowHandle of rowHandles) {
+            this.cells.clearRows(/* rowStart: */ rowHandle, /* rowCount: */ 1);
+            this.pending.clearRows(/* rowStart: */ rowHandle, /* rowCount: */ 1);
+            if (this.fwwPolicy.state === "on") {
+                this.fwwPolicy.cellLastWriteTracker?.clearRows(
+                /* rowStart: */ rowHandle, 
+                /* rowCount: */ 1);
+            }
+        }
+    };
+    onColHandlesRecycled = (colHandles) => {
+        for (const colHandle of colHandles) {
+            this.cells.clearCols(/* colStart: */ colHandle, /* colCount: */ 1);
+            this.pending.clearCols(/* colStart: */ colHandle, /* colCount: */ 1);
+            if (this.fwwPolicy.state === "on") {
+                this.fwwPolicy.cellLastWriteTracker?.clearCols(
+                /* colStart: */ colHandle, 
+                /* colCount: */ 1);
+            }
+        }
+    };
     switchSetCellPolicy() {
         if (this.fwwPolicy.state === "off") {
             this.fwwPolicy = this.isAttached()