@fluidframework/tree 2.74.0 → 2.81.0-374083

package/src/simple-tree/api/simpleSchemaToJsonSchema.ts

@@ -110,9 +110,9 @@ function convertArrayNodeSchema(schema: SimpleArrayNodeSchema): JsonArrayNodeSch
 	const allowedTypesIdentifiers: ReadonlySet<string> = new Set(
 		schema.simpleAllowedTypes.keys(),
 	);
-	allowedTypesIdentifiers.forEach((type) => {
+	for (const type of allowedTypesIdentifiers) {
 		allowedTypes.push(createSchemaRef(type));
-	});
+	}
 
 	const items: JsonFieldSchema = hasSingle(allowedTypes)
 		? allowedTypes[0]
@@ -132,22 +132,28 @@ function convertArrayNodeSchema(schema: SimpleArrayNodeSchema): JsonArrayNodeSch
 function convertLeafNodeSchema(schema: SimpleLeafNodeSchema): JsonLeafNodeSchema {
 	let type: JsonLeafSchemaType;
 	switch (schema.leafKind) {
-		case ValueSchema.String:
+		case ValueSchema.String: {
 			type = "string";
 			break;
-		case ValueSchema.Number:
+		}
+		case ValueSchema.Number: {
 			type = "number";
 			break;
-		case ValueSchema.Boolean:
+		}
+		case ValueSchema.Boolean: {
 			type = "boolean";
 			break;
-		case ValueSchema.Null:
+		}
+		case ValueSchema.Null: {
 			type = "null";
 			break;
-		case ValueSchema.FluidHandle:
+		}
+		case ValueSchema.FluidHandle: {
 			throw new UsageError("Fluid handles are not supported via JSON Schema.");
-		default:
+		}
+		default: {
 			unreachableCase(schema.leafKind);
+		}
 	}
 
 	return {
@@ -181,13 +187,11 @@ export function convertObjectNodeSchema(
 		copyProperty(fieldSchema.metadata, "description", output);
 		properties[key] = output;
 
-		if (fieldSchema.kind !== FieldKind.Optional) {
-			if (
-				options.requireFieldsWithDefaults ||
-				fieldSchema.props?.defaultProvider === undefined
-			) {
-				required.push(key);
-			}
+		if (
+			fieldSchema.kind !== FieldKind.Optional &&
+			(options.requireFieldsWithDefaults || fieldSchema.props?.defaultProvider === undefined)
+		) {
+			required.push(key);
 		}
 	}
 
@@ -212,9 +216,9 @@ function convertRecordLikeNodeSchema(
 	const allowedTypesIdentifiers: ReadonlySet<string> = new Set(
 		schema.simpleAllowedTypes.keys(),
 	);
-	allowedTypesIdentifiers.forEach((type) => {
+	for (const type of allowedTypesIdentifiers) {
 		allowedTypes.push(createSchemaRef(type));
-	});
+	}
 
 	const output = {
 		type: "object",

package/src/simple-tree/api/simpleTreeIndex.ts

@@ -148,14 +148,14 @@ export function createSimpleTreeIndex<
 	indexableSchema?: readonly TreeNodeSchema[],
 ): SimpleTreeIndex<TKey, TValue> {
 	const indexableSchemaMap = new Map();
-	if (indexableSchema !== undefined) {
-		for (const schemus of indexableSchema) {
-			indexableSchemaMap.set(schemus.identifier, schemus);
-		}
-	} else {
+	if (indexableSchema === undefined) {
 		walkFieldSchema(view.schema, {
 			node: (schemus) => indexableSchemaMap.set(schemus.identifier, schemus),
 		});
+	} else {
+		for (const schemus of indexableSchema) {
+			indexableSchemaMap.set(schemus.identifier, schemus);
+		}
 	}
 
 	const schemaIndexer =
@@ -163,14 +163,14 @@ export function createSimpleTreeIndex<
 			? (schemaIdentifier: TreeNodeSchemaIdentifier) => {
 					// if indexable schema isn't provided, we check if the node is in schema
 					const schemus = indexableSchemaMap.get(schemaIdentifier);
-					if (schemus !== undefined) {
+					if (schemus === undefined) {
+						fail(0xb32 /* node is out of schema */);
+					} else {
 						const keyLocation =
 							typeof indexer === "function" ? indexer(schemus) : indexer.get(schemus);
 						if (keyLocation !== undefined) {
 							return makeGenericKeyFinder<TKey>(brand(keyLocation), isKeyValid);
 						}
-					} else {
-						fail(0xb32 /* node is out of schema */);
 					}
 				}
 			: (schemaIdentifier: TreeNodeSchemaIdentifier) => {

package/src/simple-tree/api/snapshotCompatibilityChecker.ts

@@ -3,6 +3,10 @@
  * Licensed under the MIT License.
  */
 
+import * as semver from "semver-ts";
+import { assert, transformMapValues } from "@fluidframework/core-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import { selectVersionRoundedDown } from "@fluidframework/runtime-utils/internal";
 import type { JsonCompatibleReadOnly } from "../../util/index.js";
 import { toInitialSchema } from "../toStoredSchema.js";
 import { TreeViewConfigurationAlpha, TreeViewConfiguration } from "./configuration.js";
@@ -141,3 +145,500 @@ export function importCompatibilitySchemaSnapshot(
 	// a schema produced by `generateSchemaFromSimpleSchema`.
 	return new TreeViewConfiguration({ schema: viewSchema.root });
 }
+
+/**
+ * The file system methods required by {@link checkSchemaCompatibilitySnapshots}.
+ * @remarks
+ * Implemented by both Node.js `fs` and `path` modules, but other implementations can be provided as needed.
+ *
+ * @example
+ * ```typescript
+ * import path from "node:path";
+ * import fs from "node:fs";
+ *
+ * const nodeFileSystem: SnapshotFileSystem = { ...fs, ...path };
+ * ```
+ *
+ * @privateRemarks
+ * This interface is designed to be compatible with Node.js `fs` and `path` modules.
+ * It is needed to avoid direct dependencies on Node.js APIs in the core library code,
+ * allowing for greater portability and easier testing.
+ *
+ * @input
+ * @alpha
+ */
+export interface SnapshotFileSystem {
+	/**
+	 * Writes a UTF-8 encoded file to disk, replacing the file if it already exists.
+	 *
+	 * @param file - Path to the file to write.
+	 * @param data - String data to be written.
+	 * @param options - Options specifying that the encoding is UTF-8.
+	 */
+	writeFileSync(file: string, data: string, options: { encoding: "utf8" }): void;
+
+	/**
+	 * Reads a UTF-8 encoded file from disk and returns its contents as a string.
+	 *
+	 * @param file - Path to the file to read.
+	 * @param encoding - The text encoding to use when reading the file. Must be `"utf8"`.
+	 * @returns The contents of the file as a string.
+	 */
+	// We include the encoding here to match the function overload for readFileSync that returns a string.
+	readFileSync(file: string, encoding: "utf8"): string;
+
+	/**
+	 * How a {@link TreeView} using the snapshotted schema would report its compatibility with a document created with the current schema.
+	 *
+	 * @param dir - Path of the directory to create.
+	 * @param options - Options indicating that creation should be recursive.
+	 */
+	mkdirSync(dir: string, options: { recursive: true }): void;
+
+	/**
+	 * Reads the contents of a directory.
+	 *
+	 * @param dir - Path of the directory to read.
+	 * @returns An array of names of the directory entries.
+	 */
+	readdirSync(dir: string): readonly string[];
+
+	/**
+	 * Joins two path segments into a single path string.
+	 *
+	 * @param parentPath - The directory path.
+	 * @param childPath - Filename within `parentPath` directory.
+	 * @returns The combined path string.
+	 */
+	join(parentPath: string, childPath: string): string;
+}
+
+/**
+ * The combined compatibility status for both backwards and forwards compatibility checks.
+ */
+export interface CombinedSchemaCompatibilityStatus {
+	/**
+	 * How a {@link TreeView} using the current schema would report its compatibility with the historical snapshot.
+	 */
+	readonly currentViewOfSnapshotDocument: Omit<SchemaCompatibilityStatus, "canInitialize">;
+	/**
+	 * How a {@link TreeView} using the snapshotted schema would report its compatibility with a document created with the current schema.
+	 */
+	readonly snapshotViewOfCurrentDocument: Omit<SchemaCompatibilityStatus, "canInitialize">;
+}
+
+/**
+ * The options for {@link checkSchemaCompatibilitySnapshots}.
+ * @input
+ * @alpha
+ */
+export interface SchemaCompatibilitySnapshotsOptions {
+	/**
+	 * Directory where historical schema snapshots are stored.
+	 */
+	readonly snapshotDirectory: string;
+	/**
+	 * How the `snapshotDirectory` is accessed.
+	 */
+	readonly fileSystem: SnapshotFileSystem;
+	/**
+	 * The current application or library version.
+	 * @remarks
+	 * This uses the {@link https://semver.org/#spec-item-11|ordering defined by semver}.
+	 * It is only compared against the version from previous snapshots (taken from this version when they were created by setting `mode` to "update") and the `minVersionForCollaboration`.
+	 */
+	readonly version: string;
+	/**
+	 * The current view schema.
+	 */
+	readonly schema: TreeViewConfiguration;
+	/**
+	 * The minimum version that the current version is expected to be able to collaborate with.
+	 * @remarks
+	 * This defines a range of versions whose schema must be forwards compatible with trees using the current schema:
+	 * Any schema from snapshots with a version greater than or equal to this must be able to view documents created with the current schema.
+	 * This means that if the current `schema` is used to create a {@link TreeView}, then {@link TreeView.upgradeSchema} is used, the older clients,
+	 * all the way back to this `minVersionForCollaboration` will be able to view and edit the tree using their schema and thus collaborate.
+	 *
+	 * Typically applications will attempt to manage their deployment/update schedule such that all versions concurrently deployed can
+	 * collaborate to avoid users losing access to documents when other users upgrade the schema.
+	 * Such applications can set this to the oldest version currently deployed,
+	 * then rely on {@link checkSchemaCompatibilitySnapshots} to verify that no schema changes are made which would break collaboration with that (or newer) versions.
+	 *
+	 * This is the same approach used by {@link @fluidframework/runtime-definitions#MinimumVersionForCollab}
+	 * except that type is specifically for use with the version of the Fluid Framework client packages,
+	 * and this corresponds to the version of the application or library defining the schema.
+	 */
+	readonly minVersionForCollaboration: string;
+	/**
+	 * When true, every version must be snapshotted, and an increased version number will require a new snapshot.
+	 * @remarks
+	 * If this is true, it is assumed there is a snapshot for every release, and thus it is required that the `minVersionForCollaboration` refer to a version which has a snapshot.
+	 * When this is not true, versions without snapshots are assumed to have the same schema as the latest previous version which has a snapshot, and thus `minVersionForCollaboration`
+	 * can refer to versions between snapshots and will get its schema from the preceding version.
+	 */
+	readonly snapshotUnchangedVersions?: true;
+	/**
+	 * The mode of operation, either "test" or "update".
+	 * @remarks
+	 * In "update" mode, a new snapshot is created if the current schema differs from the latest existing snapshot.
+	 * Note: {@link SchemaCompatibilitySnapshotsOptions.snapshotUnchangedVersions} impacts this behavior.
+	 *
+	 * In "test" mode, an error is thrown if running in "update" mode would have made any changes.
+	 *
+	 * Both modes will throw errors if any compatibility issues are detected (but after updating snapshots in "update" mode so the diff can be used to help debug).
+	 *
+	 * It is recommended that "test" mode be used in automated tests to verify schema compatibility,
+	 * and "update" mode only be used manually to update snapshots when making schema changes (or version changes if `snapshotUnchangedVersions` is true).
+	 */
+	readonly mode: "test" | "update";
+}
+
+/**
+ * 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 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.
+ * @throws Throws an error if any snapshotted schema with a version greater than or equal to `minVersionForCollaboration` cannot view documents created with the current schema.
+ * @remarks
+ * This is intended for use in snapshot-based schema compatibility tests.
+ * Every SharedTree-based component or application with a schema is recommended to use this to verify schema compatibility across versions.
+ *
+ * Schema snapshots should be added to `snapshotDirectory` using this function in "update" mode whenever the schema changes in a compatibility impacting way
+ * (or when `snapshotUnchangedVersions` is true and a new version about to be released is getting prepared for release (and thus `version` changed)).
+ *
+ * This will throw an exception if any snapshotted schema would result in documents that cannot be viewed (after using {@link TreeView.upgradeSchema}), or if any schema with a version greater than or equal to `minVersionForCollaboration` cannot view documents created with the `currentViewSchema`.
+ * See {@link TreeView.compatibility} for more information.
+ *
+ * Proper use of this utility should do a good job at detecting schema compatibility issues,
+ * however it currently does not do a good job of explaining exactly what change to the schema is causing the compatibility issues.
+ * 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.
+ *
+ * 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}.
+ *
+ * This utility does not enforce anything with respect to API compatibility, or special semantics for major, minor, or patch versions.
+ * Libraries which export schema for use by others will need to take special care to ensure the stability contract they offer their users aligns which what is validated by this utility.
+ *
+ * This utility only tests compatibility of the historical snapshots against the current schema; it does not test them against each-other.
+ * Generally any historical schema should have been tested against the ones before them at the time they were current.
+ * If for some reason a version of a schema made it into production that was not compatible with a previous version,
+ * that can still be represented here (but may require manually generating a snapshot for that version)
+ * and this will still allow testing that all historical version can be upgraded to the current one.
+ * If a sufficiently incompatible historical schema were used in production, it may be impossible to make a single schema which can accommodate all of them:
+ * this utility can be used to confirm that is the case, as well as to avoid the problem in the first place by testing schema before each one is deployed.
+ *
+ * @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({
+ * 		version: pkgVersion,
+ * 		schema: config,
+ * 		fileSystem: { ...fs, ...path },
+ * 		minVersionForCollaboration: "2.0.0",
+ * 		mode: process.argv.includes("--snapshot") ? "update" : "test",
+ * 		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.
+ * @alpha
+ */
+export function checkSchemaCompatibilitySnapshots(
+	options: SchemaCompatibilitySnapshotsOptions,
+): void {
+	const checker = new SnapshotCompatibilityChecker(
+		options.snapshotDirectory,
+		options.fileSystem,
+	);
+	const {
+		version: currentVersion,
+		schema: currentViewSchema,
+		mode,
+		minVersionForCollaboration,
+		snapshotUnchangedVersions,
+	} = options;
+	if (semver.valid(currentVersion) === null) {
+		throw new UsageError(
+			`Invalid version: ${JSON.stringify(currentVersion)}. Must be a valid semver version.`,
+		);
+	}
+	if (semver.valid(minVersionForCollaboration) === null) {
+		throw new UsageError(
+			`Invalid minVersionForCollaboration: ${JSON.stringify(minVersionForCollaboration)}. Must be a valid semver version.`,
+		);
+	}
+	if (!semver.lte(minVersionForCollaboration, currentVersion)) {
+		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".`,
+		);
+	}
+
+	const currentEncodedForSnapshotting = exportCompatibilitySchemaSnapshot(currentViewSchema);
+	const snapshots = checker.readAllSchemaSnapshots();
+
+	const compatibilityErrors: string[] = [];
+
+	function updatableError(message: string): void {
+		assert(mode === "test", "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.`,
+		);
+	}
+
+	if (snapshotUnchangedVersions === true) {
+		if (mode === "update") {
+			checker.writeSchemaSnapshot(currentVersion, currentEncodedForSnapshotting);
+			snapshots.set(currentVersion, currentViewSchema);
+		} 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.`,
+				);
+			} else if (
+				JSON.stringify(exportCompatibilitySchemaSnapshot(currentRead)) !==
+				JSON.stringify(currentEncodedForSnapshotting)
+			) {
+				updatableError(
+					`Snapshot for current version ${JSON.stringify(currentVersion)} is out of date.`,
+				);
+			}
+		}
+	} 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 {
+				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])}.`,
+						);
+					}
+				}
+			} 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.`,
+				);
+			}
+		}
+	}
+
+	const compatibilityMap = transformMapValues(snapshots, (snapshot) =>
+		getCompatibility(currentViewSchema, snapshot),
+	);
+
+	let selectedMinVersionForCollaborationSnapshot:
+		| undefined
+		| readonly [string, CombinedSchemaCompatibilityStatus];
+
+	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 {
+			selectedMinVersionForCollaborationSnapshot = [minVersionForCollaboration, minSnapshot];
+		}
+	} else {
+		selectedMinVersionForCollaborationSnapshot = selectVersionRoundedDown(
+			minVersionForCollaboration,
+			compatibilityMap,
+		);
+		if (selectedMinVersionForCollaborationSnapshot === undefined) {
+			compatibilityErrors.push(
+				`No snapshot found with version less than or equal to minVersionForCollaboration ${JSON.stringify(minVersionForCollaboration)}.`,
+			);
+		}
+	}
+
+	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)) {
+			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.`,
+				);
+			}
+			if (
+				compatibility.currentViewOfSnapshotDocument.isEquivalent === false ||
+				compatibility.snapshotViewOfCurrentDocument.isEquivalent === false
+			) {
+				compatibilityErrors.push(
+					`Current version ${JSON.stringify(snapshotVersion)} expected to be equivalent to its snapshot.`,
+				);
+			}
+		} else if (semver.lt(snapshotVersion, currentVersion)) {
+			if (selectedMinVersionForCollaborationSnapshot === undefined) {
+				assert(
+					compatibilityErrors.length > 0,
+					"expected compatibility errors for missing min collab version snapshot",
+				);
+			} 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).
+				}
+			}
+		} else {
+			throw new UsageError(
+				`Unexpected semver comparison result between snapshot version ${JSON.stringify(snapshotVersion)} and app version ${JSON.stringify(currentVersion)}.`,
+			);
+		}
+	}
+
+	if (compatibilityErrors.length > 0) {
+		throw new Error(
+			`Schema compatibility check failed:\n${compatibilityErrors
+				.map((e) => ` - ${e}`)
+				.join("\n")}`,
+		);
+	}
+}
+
+/**
+ * The high-level API for checking snapshot compatibility and generating new snapshots.
+ */
+export class SnapshotCompatibilityChecker {
+	public constructor(
+		/**
+		 * Directory where historical schema snapshots are stored.
+		 */
+		private readonly snapshotDirectory: string,
+		/**
+		 * How the `snapshotDirectory` is accessed.
+		 */
+		private readonly fileSystemMethods: SnapshotFileSystem,
+	) {}
+
+	public writeSchemaSnapshot(snapshotName: string, snapshot: JsonCompatibleReadOnly): void {
+		const fullPath = this.fileSystemMethods.join(
+			this.snapshotDirectory,
+			`${snapshotName}.json`,
+		);
+		this.ensureSnapshotDirectoryExists();
+		this.fileSystemMethods.writeFileSync(fullPath, JSON.stringify(snapshot, undefined, 2), {
+			encoding: "utf8",
+		});
+	}
+
+	public readSchemaSnapshot(snapshotName: string): TreeViewConfiguration {
+		const snapshot = this.readSchemaSnapshotRaw(snapshotName);
+		return importCompatibilitySchemaSnapshot(snapshot);
+	}
+
+	public readSchemaSnapshotRaw(snapshotName: string): JsonCompatibleReadOnly {
+		const fullPath = this.fileSystemMethods.join(
+			this.snapshotDirectory,
+			`${snapshotName}.json`,
+		);
+		const snapshot = JSON.parse(
+			this.fileSystemMethods.readFileSync(fullPath, "utf8"),
+		) as JsonCompatibleReadOnly;
+		return snapshot;
+	}
+
+	/**
+	 * Returns all schema snapshots stored in the snapshot directory, sorted in order of increasing version.
+	 */
+	public readAllSchemaSnapshots(): Map<string, TreeViewConfiguration> {
+		this.ensureSnapshotDirectoryExists();
+		const files = this.fileSystemMethods.readdirSync(this.snapshotDirectory);
+		const versions: string[] = [];
+		for (const file of files) {
+			if (file.endsWith(".json")) {
+				const snapshotName = file.slice(0, ".json".length * -1);
+				versions.push(snapshotName);
+			}
+		}
+		// Ensures that errors are in a consistent and friendly order, independent of file system order.
+		versions.sort((a, b) => semver.compare(a, b));
+
+		const snapshots: Map<string, TreeViewConfiguration> = new Map();
+		for (const version of versions) {
+			snapshots.set(version, this.readSchemaSnapshot(version));
+		}
+		return snapshots;
+	}
+
+	public ensureSnapshotDirectoryExists(): void {
+		this.fileSystemMethods.mkdirSync(this.snapshotDirectory, { recursive: true });
+	}
+}
+
+/**
+ * Gets the compatibility of the current view schema against a historical snapshot.
+ * @param currentViewSchema - The current view schema.
+ * @param previousViewSchema - The historical view schema.
+ * @returns The combined compatibility status.
+ */
+export function getCompatibility(
+	currentViewSchema: TreeViewConfiguration,
+	previousViewSchema: TreeViewConfiguration,
+): CombinedSchemaCompatibilityStatus {
+	const backwardsCompatibilityStatus = checkCompatibility(
+		previousViewSchema,
+		currentViewSchema,
+	);
+
+	const forwardsCompatibilityStatus = checkCompatibility(
+		currentViewSchema,
+		previousViewSchema,
+	);
+
+	return {
+		currentViewOfSnapshotDocument: backwardsCompatibilityStatus,
+		snapshotViewOfCurrentDocument: forwardsCompatibilityStatus,
+	};
+}

package/src/simple-tree/api/storedSchema.ts

@@ -4,12 +4,15 @@
  */
 
 import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
-import { FluidClientVersion, type ICodecOptions } from "../../codec/index.js";
-import { SchemaFormatVersion } from "../../core/index.js";
-import { encodeTreeSchema, makeSchemaCodec } from "../../feature-libraries/index.js";
 import {
-	clientVersionToSchemaVersion,
-	type FormatV1,
+	FluidClientVersion,
+	FormatValidatorNoOp,
+	type ICodecOptions,
+} from "../../codec/index.js";
+import { SchemaFormatVersion } from "../../core/index.js";
+import { makeSchemaCodec } from "../../feature-libraries/index.js";
+import type {
+	FormatV1,
 	// eslint-disable-next-line import-x/no-internal-modules
 } from "../../feature-libraries/schema-index/index.js";
 import type { JsonCompatible } from "../../util/index.js";
@@ -59,8 +62,8 @@ export function extractPersistedSchema(
 	includeStaged: (upgrade: SchemaUpgrade) => boolean,
 ): JsonCompatible {
 	const stored = toStoredSchema(schema, { includeStaged });
-	const schemaWriteVersion = clientVersionToSchemaVersion(minVersionForCollab);
-	return encodeTreeSchema(stored, schemaWriteVersion);
+	const codec = makeSchemaCodec({ minVersionForCollab, jsonValidator: FormatValidatorNoOp });
+	return codec.encode(stored) as JsonCompatible;
 }
 
 /**