@fluidframework/tree 2.81.1 → 2.83.0

package/lib/simple-tree/api/snapshotCompatibilityChecker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"snapshotCompatibilityChecker.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/snapshotCompatibilityChecker.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"snapshotCompatibilityChecker.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/snapshotCompatibilityChecker.ts"],"names":[],"mappings":"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"}

package/lib/simple-tree/api/snapshotCompatibilityChecker.js

@@ -2,7 +2,7 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { assert, transformMapValues } from "@fluidframework/core-utils/internal";
+import { assert, fail, transformMapValues } from "@fluidframework/core-utils/internal";
 import { selectVersionRoundedDown } from "@fluidframework/runtime-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import * as semver from "semver-ts";
@@ -131,7 +131,7 @@ export function importCompatibilitySchemaSnapshot(config) {
 /**
  * Check `currentViewSchema` for compatibility with a collection of historical schema snapshots stored in `snapshotDirectory`.
  *
- * @throws Throws errors if the input version strings (including those in snapshot file names) are not valid semver versions.
+ * @throws Throws errors if the input version strings (including those in snapshot file names) are not valid semver versions when using default semver version comparison.
  * @throws Throws errors if the input version strings (including those in snapshot file names) are not ordered as expected (current being the highest, and `minVersionForCollaboration` corresponding to the current version or a lower snapshotted version).
  * @throws In `test` mode, throws an error if there is not an up to date snapshot for the current version.
  * @throws Throws an error if any snapshotted schema cannot be upgraded to the current schema.
@@ -151,6 +151,14 @@ export function importCompatibilitySchemaSnapshot(config) {
  * This is a known limitation that will be improved in future releases.
  * These improvements, as well as other changes, may change the exact messages produced by this function in the error cases: no stability of these messages should be assumed.
  *
+ * Unlike some other snapshot based testing tools, this stores more than just the current snapshot: historical snapshots are retained as well.
+ * Retention of these additional historical snapshots, whose content can't be regenerated from the current schema, is necessary to properly test compatibility across versions.
+ * Since there is content in the snapshots which cannot be regenerated, tools which assume all snapshotted content can be regenerated cannot be used here.
+ * This means that tools like Jest's built in snapshot testing are not suitable for this purpose.
+ * These snapshots behave partly like test data, and partly like snapshots.
+ * Typically the easiest way to manage this is to place {@link SnapshotSchemaCompatibilityOptions.snapshotDirectory} inside a directory appropriate for test data,
+ * and use node to provide the filesystem access via {@link SnapshotSchemaCompatibilityOptions.fileSystem}.
+ *
  * For now, locating what change broke compatibility is likely best discovered by making small schema changes one at a time and updating the snapshot and reviewing the diffs.
  * Details for what kinds of changes are breaking and in which ways can be found in the documentation for {@link TreeView.compatibility} and
  * {@link https://fluidframework.com/docs/data-structures/tree/schema-evolution/ | schema-evolution}.
@@ -169,7 +177,7 @@ export function importCompatibilitySchemaSnapshot(config) {
  * @example Mocha test which validates the current `config` can collaborate with all historical version back to 2.0.0, and load and update any versions older than that.
  * ```typescript
  * it("schema compatibility", () => {
- * 	checkSchemaCompatibilitySnapshots({
+ * 	snapshotSchemaCompatibility({
  * 		version: pkgVersion,
  * 		schema: config,
  * 		fileSystem: { ...fs, ...path },
@@ -179,148 +187,213 @@ export function importCompatibilitySchemaSnapshot(config) {
  * 	});
  * });
  * ```
+ * @example Complete Mocha test file
+ * ```typescript
+ * import fs from "node:fs";
+ * import path from "node:path";
+ *
+ * import { snapshotSchemaCompatibility } from "@fluidframework/tree/alpha";
+ *
+ * // The TreeViewConfiguration the application uses, which contains the application's schema.
+ * import { treeViewConfiguration } from "./schema.js";
+ * // The next version of the application which will be released.
+ * import { packageVersion } from "./version.js";
+ *
+ * // Provide some way to run the check in "update" mode when updating snapshots is intended.
+ * const regenerateSnapshots = process.argv.includes("--snapshot");
+ *
+ * // Setup the actual test. In this case using Mocha syntax.
+ * describe("schema", () => {
+ * 	it("schema compatibility", () => {
+ * 		// Select a path to save the snapshots in.
+ * 		// This will depend on how your application organizes its test data.
+ * 		const snapshotDirectory = path.join(
+ * 			import.meta.dirname,
+ * 			"../../../src/test/schema-snapshots",
+ * 		);
+ * 		snapshotSchemaCompatibility({
+ * 			schema: config,
+ * 			fileSystem: { ...fs, ...path },
+ * 			version: pkgVersion,
+ * 			minVersionForCollaboration: "2.0.0",
+ * 			mode: process.argv.includes("--snapshot") ? "update" : "assert",
+ * 			snapshotDirectory,
+ * 		});
+ * 	});
+ * });
+ * ```
  * @privateRemarks
  * Use of this function within this package (for schema libraries released as part of this package) should use {@link testSchemaCompatibilitySnapshots} instead.
  *
- * TODO: this uses the format defined in simpleSchemaCodec.ts.
- * Currently this does not include any versioning information in the snapshot format itself.
- * This would make it hard to do things like upgrade to a new format (perhaps for better diffs, or to support new features) in the future.
- * That code should probably be migrated to a proper versioned codec with a schema and validation.
- * This utility can directly depend on the typebox-validator and inject that as this code should not be bundle size sensitive.
- * This should be addressed before this reached beta stability.
+ * This uses the format defined in simpleSchemaCodec.ts.
+ * This does include versioning information in the snapshot format,
+ * but it would be nice to better unify how we do that versioning and format validation with our codecs.
+ *
+ * See snapshotCompatibilityChecker.example.mts for the large example included above.
  * @alpha
  */
-export function checkSchemaCompatibilitySnapshots(options) {
+export function snapshotSchemaCompatibility(options) {
     const checker = new SnapshotCompatibilityChecker(options.snapshotDirectory, options.fileSystem);
-    const { version: currentVersion, schema: currentViewSchema, mode, minVersionForCollaboration, snapshotUnchangedVersions, } = options;
-    if (semver.valid(currentVersion) === null) {
+    const { version: currentVersion, schema: currentViewSchema, mode, minVersionForCollaboration, snapshotUnchangedVersions, rejectVersionsWithNoSchemaChange, rejectSchemaChangesWithNoVersionChange, } = options;
+    const validateVersion = options.versionComparer === undefined ? semver.valid : (v) => v;
+    const versionComparer = options.versionComparer ?? semver.compare;
+    if (validateVersion(currentVersion) === null) {
         throw new UsageError(`Invalid version: ${JSON.stringify(currentVersion)}. Must be a valid semver version.`);
     }
-    if (semver.valid(minVersionForCollaboration) === null) {
+    if (validateVersion(minVersionForCollaboration) === null) {
         throw new UsageError(`Invalid minVersionForCollaboration: ${JSON.stringify(minVersionForCollaboration)}. Must be a valid semver version.`);
     }
-    if (!semver.lte(minVersionForCollaboration, currentVersion)) {
+    if (versionComparer(minVersionForCollaboration, currentVersion) > 0) {
         throw new UsageError(`Invalid minVersionForCollaboration: ${JSON.stringify(minVersionForCollaboration)}. Must be less than or equal to current version ${JSON.stringify(currentVersion)}.`);
     }
-    if (mode !== "test" && mode !== "update") {
-        throw new UsageError(`Invalid mode: ${JSON.stringify(mode)}. Must be either "test" or "update".`);
+    if (mode !== "assert" && mode !== "update") {
+        throw new UsageError(`Invalid mode: ${JSON.stringify(mode)}. Must be either "assert" or "update".`);
     }
     const currentEncodedForSnapshotting = exportCompatibilitySchemaSnapshot(currentViewSchema);
-    const snapshots = checker.readAllSchemaSnapshots();
+    const snapshots = checker.readAllSchemaSnapshots(versionComparer);
     const compatibilityErrors = [];
-    function updatableError(message) {
-        assert(mode === "test", 0xcc6 /* updatableError should only be called in test mode */);
-        compatibilityErrors.push(`${message} If this is expected, checkSchemaCompatibilitySnapshots can be rerun in "update" mode to update the snapshot.`);
+    const contextNotes = [];
+    function errorWithContext(message) {
+        return new Error([
+            "Schema compatibility check failed:",
+            message,
+            `Snapshots in: ${JSON.stringify(options.snapshotDirectory)}`,
+            `Snapshots exist for versions: ${JSON.stringify([...snapshots.keys()], undefined, "\t")}.`,
+            ...contextNotes,
+        ].join("\n"));
     }
-    if (snapshotUnchangedVersions === true) {
-        if (mode === "update") {
-            checker.writeSchemaSnapshot(currentVersion, currentEncodedForSnapshotting);
-            snapshots.set(currentVersion, currentViewSchema);
+    const compatibilityMap = transformMapValues(snapshots, (snapshot) => getCompatibility(currentViewSchema, snapshot));
+    // Either:
+    // - false: no update needed
+    // - the updateError message (update in update mode, error otherwise)
+    // - an error if the update is disallowed by the flags
+    let wouldUpdate;
+    // Set wouldUpdate
+    {
+        const latestSnapshot = [...snapshots][snapshots.size - 1];
+        if (latestSnapshot === undefined) {
+            wouldUpdate = `No snapshots found.`;
         }
         else {
-            const currentRead = snapshots.get(currentVersion);
-            if (currentRead === undefined) {
-                updatableError(`No snapshot found for version ${JSON.stringify(currentVersion)}: snapshotUnchangedVersions is true, so every version must be snapshotted.`);
+            const latestCompatibility = compatibilityMap.get(latestSnapshot[0]) ??
+                fail(0xcd1 /* missing compatibilityMap entry */);
+            const schemaChange = !latestCompatibility.identicalCompatibility;
+            const versionChange = versionComparer(latestSnapshot[0], currentVersion) !== 0;
+            if (rejectVersionsWithNoSchemaChange === true && versionChange && !schemaChange) {
+                wouldUpdate = errorWithContext(`Rejecting version change (${JSON.stringify(latestSnapshot[0])} to ${JSON.stringify(currentVersion)}) due to rejectVersionsWithNoSchemaChange being set.`);
             }
-            else if (JSON.stringify(exportCompatibilitySchemaSnapshot(currentRead)) !==
-                JSON.stringify(currentEncodedForSnapshotting)) {
-                updatableError(`Snapshot for current version ${JSON.stringify(currentVersion)} is out of date.`);
+            else if (rejectSchemaChangesWithNoVersionChange === true &&
+                schemaChange &&
+                !versionChange) {
+                wouldUpdate = errorWithContext(`Rejecting schema change without version change due to existing  non-equivalent snapshot for version (${JSON.stringify(latestSnapshot[0])} due to rejectSchemaChangesWithNoVersionChange being set.`);
             }
-        }
-    }
-    else {
-        const entries = [...snapshots];
-        const latestSnapshot = entries[entries.length - 1];
-        if (latestSnapshot === undefined) {
-            if (mode === "update") {
-                checker.writeSchemaSnapshot(currentVersion, currentEncodedForSnapshotting);
-                snapshots.set(currentVersion, currentViewSchema);
+            else if (snapshotUnchangedVersions === true) {
+                const currentRead = snapshots.get(currentVersion);
+                if (currentRead === undefined) {
+                    wouldUpdate = `No snapshot found for version ${JSON.stringify(currentVersion)}: snapshotUnchangedVersions is true, so every version must be snapshotted.`;
+                }
+                else if (JSON.stringify(exportCompatibilitySchemaSnapshot(currentRead)) ===
+                    JSON.stringify(currentEncodedForSnapshotting)) {
+                    wouldUpdate = false;
+                }
+                else {
+                    wouldUpdate = `Snapshot for current version ${JSON.stringify(currentVersion)} is out of date.`;
+                }
             }
             else {
-                updatableError(`No snapshots found.`);
-            }
-        }
-        else {
-            if (semver.lte(latestSnapshot[0], currentVersion)) {
-                // Check to see if schema in snapshot is the same as the latest existing snapshot.
-                const oldString = JSON.stringify(exportCompatibilitySchemaSnapshot(latestSnapshot[1]));
-                const currentString = JSON.stringify(currentEncodedForSnapshotting);
-                if (oldString !== currentString) {
-                    // Schema has changed: must create new snapshot.
-                    if (mode === "update") {
-                        checker.writeSchemaSnapshot(currentVersion, currentEncodedForSnapshotting);
-                        snapshots.set(currentVersion, currentViewSchema);
-                    }
-                    else {
-                        updatableError(`Snapshot for current version ${JSON.stringify(currentVersion)} is out of date: schema has changed since latest existing snapshot version ${JSON.stringify(latestSnapshot[0])}.`);
-                    }
+                if (versionComparer(latestSnapshot[0], currentVersion) <= 0) {
+                    wouldUpdate = schemaChange
+                        ? `Snapshot for current version ${JSON.stringify(currentVersion)} is out of date: schema has changed since latest existing snapshot version ${JSON.stringify(latestSnapshot[0])}.`
+                        : false;
+                }
+                else {
+                    wouldUpdate = errorWithContext(`Current version ${JSON.stringify(currentVersion)} is less than latest existing snapshot version ${JSON.stringify(latestSnapshot[0])}: version is expected to increase monotonically.`);
                 }
             }
-            else {
-                throw new UsageError(`Current version ${JSON.stringify(currentVersion)} is less than latest existing snapshot version ${JSON.stringify(latestSnapshot[0])}: version is expected to increase monotonically.`);
+            if (!schemaChange && (snapshotUnchangedVersions !== true || !versionChange)) {
+                // eslint-disable-next-line unicorn/no-lonely-if
+                if (JSON.stringify(exportCompatibilitySchemaSnapshot(latestSnapshot[1])) !==
+                    JSON.stringify(currentEncodedForSnapshotting)) {
+                    // Schema are compatibility wise equivalent, but differ in some way (excluding json formatting).
+                    // TODO: add a "normalize" mode, which do an update only in this case (or maybe even normalize json formatting as well and just always rewrite when !schemaChange)
+                    // This would be useful to minimize diffs from future schema changes.
+                    // This would be particularly useful if adding a second version of the format used in the snapshots.
+                }
             }
         }
     }
-    const compatibilityMap = transformMapValues(snapshots, (snapshot) => getCompatibility(currentViewSchema, snapshot));
-    let selectedMinVersionForCollaborationSnapshot;
-    if (snapshotUnchangedVersions === true) {
-        const minSnapshot = compatibilityMap.get(minVersionForCollaboration);
-        if (minSnapshot === undefined) {
-            compatibilityErrors.push(`Using snapshotUnchangedVersions: a snapshot of the exact minVersionForCollaboration ${JSON.stringify(minVersionForCollaboration)} is required. No snapshot found.`);
+    if (wouldUpdate !== false) {
+        if (wouldUpdate instanceof Error) {
+            throw wouldUpdate;
+        }
+        if (mode === "update") {
+            checker.writeSchemaSnapshot(currentVersion, currentEncodedForSnapshotting);
+            // Update so errors below will reflect the new snapshot.
+            compatibilityMap.set(currentVersion, getCompatibility(currentViewSchema, currentViewSchema));
         }
         else {
-            selectedMinVersionForCollaborationSnapshot = [minVersionForCollaboration, minSnapshot];
+            compatibilityErrors.push(`${wouldUpdate} If this is expected, snapshotSchemaCompatibility can be rerun in "update" mode to update or create the snapshot.`);
+            // This case could update compatibilityMap as well, but it would hide some information about how the existing snapshot might be incompatible with the proposed new one.
+            // This lost information could be annoying if the user's intention was not to edit the schema (which is what we assume in assert mode),
+            // especially once we produce more detailed error messages that can help users understand what changed in the schema.
         }
     }
-    else {
-        selectedMinVersionForCollaborationSnapshot = selectVersionRoundedDown(minVersionForCollaboration, compatibilityMap);
-        if (selectedMinVersionForCollaborationSnapshot === undefined) {
-            compatibilityErrors.push(`No snapshot found with version less than or equal to minVersionForCollaboration ${JSON.stringify(minVersionForCollaboration)}.`);
+    // Add compatibilityErrors and contextNotes as needed regarding minVersionForCollaboration.
+    // This is only done when minVersionForCollaboration is not the current version to avoid extra noise in "assert" mode
+    // (which is the only case that could error when minVersionForCollaboration === currentVersion).
+    if (minVersionForCollaboration !== currentVersion) {
+        if (snapshotUnchangedVersions === true) {
+            const minSnapshot = compatibilityMap.get(minVersionForCollaboration);
+            if (minSnapshot === undefined) {
+                compatibilityErrors.push(`Using snapshotUnchangedVersions: a snapshot of the exact minVersionForCollaboration ${JSON.stringify(minVersionForCollaboration)} is required. No snapshot found.`);
+            }
+        }
+        else {
+            const selectedMinVersionForCollaborationSnapshot = selectVersionRoundedDown(minVersionForCollaboration, compatibilityMap, versionComparer);
+            if (selectedMinVersionForCollaborationSnapshot === undefined) {
+                compatibilityErrors.push(`No snapshot found with version less than or equal to minVersionForCollaboration ${JSON.stringify(minVersionForCollaboration)}.`);
+            }
+            else if (selectedMinVersionForCollaborationSnapshot[0] !== minVersionForCollaboration) {
+                // Add an entry to ensure that the version which spans from before until after the cutoff for collaboration is included in the compatibility checks.
+                compatibilityMap.set(minVersionForCollaboration, selectedMinVersionForCollaborationSnapshot[1]);
+                contextNotes.push(`Due to snapshotUnchangedVersions being false and minVersionForCollaboration (${JSON.stringify(minVersionForCollaboration)}) not having an exact snapshot, the last snapshot before that version (which is ${JSON.stringify(selectedMinVersionForCollaborationSnapshot[0])}) is being also being checked as if it is version ${JSON.stringify(minVersionForCollaboration)}.`);
+            }
         }
     }
+    // Compare all snapshots against the current schema, using the compatibilityMap.
     for (const [snapshotVersion, compatibility] of compatibilityMap) {
         // Current should be able to view all versions.
         if (!compatibility.currentViewOfSnapshotDocument.canUpgrade) {
             compatibilityErrors.push(`Current version ${JSON.stringify(currentVersion)} cannot upgrade documents from ${JSON.stringify(snapshotVersion)}.`);
         }
-        if (semver.eq(snapshotVersion, currentVersion)) {
+        const versionComparisonToCurrent = versionComparer(snapshotVersion, currentVersion);
+        if (versionComparisonToCurrent === 0) {
             if (currentVersion !== snapshotVersion) {
-                throw new UsageError(`Snapshot version ${JSON.stringify(snapshotVersion)} is semantically equal but not string equal to current version ${JSON.stringify(currentVersion)}: this is not supported.`);
+                throw errorWithContext(`Snapshot version ${JSON.stringify(snapshotVersion)} is semantically equal but not string equal to current version ${JSON.stringify(currentVersion)}: this is not supported.`);
             }
-            if (compatibility.currentViewOfSnapshotDocument.isEquivalent === false ||
-                compatibility.snapshotViewOfCurrentDocument.isEquivalent === false) {
-                compatibilityErrors.push(`Current version ${JSON.stringify(snapshotVersion)} expected to be equivalent to its snapshot.`);
+            if (compatibility.identicalCompatibility === false) {
+                assert(wouldUpdate !== false, 0xcd2 /* there should have been an error for the snapshot being out of date */);
             }
         }
-        else if (semver.lt(snapshotVersion, currentVersion)) {
-            if (selectedMinVersionForCollaborationSnapshot === undefined) {
-                assert(compatibilityErrors.length > 0, 0xcc7 /* expected compatibility errors for missing min collab version snapshot */);
+        else if (versionComparisonToCurrent < 0) {
+            // Collaboration with this version is expected to work.
+            if (versionComparer(snapshotVersion, minVersionForCollaboration) >= 0) {
+                // Check that the historical version can view documents from the current version, since collaboration with this one is expected to work.
+                if (!compatibility.snapshotViewOfCurrentDocument.canView) {
+                    compatibilityErrors.push(`Historical version ${JSON.stringify(snapshotVersion)} cannot view documents from ${JSON.stringify(currentVersion)}: these versions are expected to be able to collaborate due to the selected minVersionForCollaboration ${JSON.stringify(minVersionForCollaboration)}.`);
+                }
             }
             else {
-                // Collaboration with this version is expected to work.
-                if (semver.gte(snapshotVersion, selectedMinVersionForCollaborationSnapshot[0])) {
-                    // Check that the historical version can view documents from the current version, since collaboration with this one is expected to work.
-                    if (!compatibility.snapshotViewOfCurrentDocument.canView) {
-                        const message = `Historical version ${JSON.stringify(snapshotVersion)} cannot view documents from ${JSON.stringify(currentVersion)}: these versions are expected to be able to collaborate due to the selected minVersionForCollaboration snapshot version being ${JSON.stringify(selectedMinVersionForCollaborationSnapshot[0])}.`;
-                        compatibilityErrors.push(selectedMinVersionForCollaborationSnapshot[0] === minVersionForCollaboration
-                            ? message
-                            : `${message} The specified minVersionForCollaboration is ${JSON.stringify(minVersionForCollaboration)} which was rounded down to an existing snapshot.`);
-                    }
-                }
-                else {
-                    // This is the case where the historical version is less than the minimum version for collaboration.
-                    // No additional validation is needed here currently, since forwards document compat from these versions is already tested above (since it applies to all snapshots).
-                }
+                // This is the case where the historical version is less than the minimum version for collaboration.
+                // No additional validation is needed here currently, since forwards document compat from these versions is already tested above (since it applies to all snapshots).
             }
         }
         else {
-            throw new UsageError(`Unexpected semver comparison result between snapshot version ${JSON.stringify(snapshotVersion)} and app version ${JSON.stringify(currentVersion)}.`);
+            compatibilityErrors.push(`Snapshot exists for version ${JSON.stringify(snapshotVersion)} which is greater than the current version ${JSON.stringify(currentVersion)}. This is not supported.`);
         }
     }
     if (compatibilityErrors.length > 0) {
-        throw new Error(`Schema compatibility check failed:\n${compatibilityErrors
-            .map((e) => ` - ${e}`)
-            .join("\n")}`);
+        throw errorWithContext(compatibilityErrors.map((e) => ` - ${e}`).join("\n"));
     }
 }
 /**
@@ -342,7 +415,7 @@ export class SnapshotCompatibilityChecker {
     writeSchemaSnapshot(snapshotName, snapshot) {
         const fullPath = this.fileSystemMethods.join(this.snapshotDirectory, `${snapshotName}.json`);
         this.ensureSnapshotDirectoryExists();
-        this.fileSystemMethods.writeFileSync(fullPath, JSON.stringify(snapshot, undefined, 2), {
+        this.fileSystemMethods.writeFileSync(fullPath, JSON.stringify(snapshot, undefined, "\t"), {
             encoding: "utf8",
         });
     }
@@ -358,7 +431,7 @@ export class SnapshotCompatibilityChecker {
     /**
      * Returns all schema snapshots stored in the snapshot directory, sorted in order of increasing version.
      */
-    readAllSchemaSnapshots() {
+    readAllSchemaSnapshots(compare) {
         this.ensureSnapshotDirectoryExists();
         const files = this.fileSystemMethods.readdirSync(this.snapshotDirectory);
         const versions = [];
@@ -369,7 +442,7 @@ export class SnapshotCompatibilityChecker {
             }
         }
         // Ensures that errors are in a consistent and friendly order, independent of file system order.
-        versions.sort((a, b) => semver.compare(a, b));
+        versions.sort(compare);
         const snapshots = new Map();
         for (const version of versions) {
             snapshots.set(version, this.readSchemaSnapshot(version));
@@ -389,9 +462,17 @@ export class SnapshotCompatibilityChecker {
 export function getCompatibility(currentViewSchema, previousViewSchema) {
     const backwardsCompatibilityStatus = checkCompatibility(previousViewSchema, currentViewSchema);
     const forwardsCompatibilityStatus = checkCompatibility(currentViewSchema, previousViewSchema);
+    assert(backwardsCompatibilityStatus.isEquivalent === forwardsCompatibilityStatus.isEquivalent, 0xcd3 /* equality should be symmetric */);
+    // This relies on exportCompatibilitySchemaSnapshot being well normalized, and not differing for non-significant changes.
+    const identicalCompatibility = JSON.stringify(exportCompatibilitySchemaSnapshot(currentViewSchema)) ===
+        JSON.stringify(exportCompatibilitySchemaSnapshot(previousViewSchema));
+    if (identicalCompatibility) {
+        assert(backwardsCompatibilityStatus.isEquivalent, 0xcd4 /* identicalCompatibility should have equivalent stored schema */);
+    }
     return {
         currentViewOfSnapshotDocument: backwardsCompatibilityStatus,
         snapshotViewOfCurrentDocument: forwardsCompatibilityStatus,
+        identicalCompatibility,
     };
 }
 //# sourceMappingURL=snapshotCompatibilityChecker.js.map