refactor(tree): make codec dependencies more explicit and auditable (#25619)

## Description

The main goal of this PR to make the hierarchy of codec dependencies
that are scattered across the SharedTree codebase more explicit and more
auditable. This is accomplished in two ways:

### Specific Version Types

Specific types are introduced for each format version and used whenever
possible. For example, referring to a specific version of the
`EditManager` format is now done with an instance of
`EditManagerFormatVersion` instead of a plain `number` or
`FormatVersion`.

This makes clearer what the space of version number is being addressed.
The type acts as a code reference that can be followed with Ctrl+Click.

This also enforces that version literals correspond to a valid version
for the target version space. For example, the code `const
editManagerVersion: EditManagerFormatVersion = 42;` will not compile
because there is no version 42 for the edit manager format.

### Queryable Codec Trees

This PR introduces the `CodecTree` type so that dependencies between
codec versions can be reified. Most codecs involved in SharedTree now
come with an associated free function that returns a `CodecTree` for a
given version of that codec.
These are used in a new set of snapshot tests that capture the codec
dependency trees of each SharedTree format version. While the primary
motivation of such tests is to end up with files that can easily be
inspected, these tests also have value in preventing unintentional
changes in codec dependencies.

## Other Changes

The changes involved in building the above have also led to the
realization that some dependencies were hard coded in the wrong place:
the format version for representing SharedTree changes used to be hard
coded in the `EditManager` and `Message` codecs. This was questionable
because `EditManager` and `Message` are completely agnostic to such
details. These dependencies are now hard-coded in sharedTree.ts.

## Breaking Changes

None

Author: yann-achard-MS

packages/dds/tree/docs/main/compatibility.md

@@ -215,6 +215,14 @@ For example, a format change in `SchemaChangeCodec` could be implemented by addi
 This new version would use the same code for all bits of `MessageCodec`, `EditManagerCodec`, and `SharedTreeChangeFamilyCodec`, but pass enough context down to `SchemaChangeCodec` to resolve to the newer format.
 In this manner, the mapping between explicitly versioned data and implicitly versioned data for composed codecs is managed in code.
 
+## Auditing Codec Resolution
+
+Because the dependencies between different codec versions are distributed over the various codec layers,
+it can be hard to understand the relationship between top-level `SharedTreeFormatVersion` values from [sharedTree.ts](../../src/shared-tree/sharedTree.ts)
+and the myriad of codec versions available.
+To help audit such relationships, the `getCodecTreeForSharedTreeFormat` function in [sharedTree.ts](../../src/shared-tree/sharedTree.ts) can be used.
+Snapshots of the dependencies are captured in the ["SharedTree Codecs"](../../src/test/shared-tree/sharedTreeCodecs.spec.ts) test suite and can be inspected [on disc](../../src/test/snapshots/codec-tree/SharedTreeFormatVersion.v1.json).
+
 ## Current code guidelines
 
 Codecs which explicitly version their data should export a codec which takes in a write version and supports reading all supported versions.

packages/dds/tree/src/codec/codec.ts

@@ -255,6 +255,52 @@ export interface ICodecFamily<TDecoded, TContext = void> {
  */
 export type FormatVersion = number | undefined;
 
+/**
+ * A format version which is dependent on some parent format version.
+ */
+export interface DependentFormatVersion<
+	TParentVersion extends FormatVersion = FormatVersion,
+	TChildVersion extends FormatVersion = FormatVersion,
+> {
+	/**
+	 * Looks up the child format version for a given parent format version.
+	 * @param parent - The parent format version.
+	 * @returns The corresponding child format version.
+	 */
+	lookup(parent: TParentVersion): TChildVersion;
+}
+
+export class UniqueDependentFormatVersion<TChildVersion extends FormatVersion>
+	implements DependentFormatVersion<FormatVersion, TChildVersion>
+{
+	public constructor(private readonly child: TChildVersion) {}
+	public lookup(_parent: FormatVersion): TChildVersion {
+		return this.child;
+	}
+}
+
+export class MappedDependentFormatVersion<
+	TParentVersion extends FormatVersion = FormatVersion,
+	TChildVersion extends FormatVersion = FormatVersion,
+> implements DependentFormatVersion<TParentVersion, TChildVersion>
+{
+	public constructor(private readonly map: ReadonlyMap<TParentVersion, TChildVersion>) {}
+	public lookup(parent: TParentVersion): TChildVersion {
+		return this.map.get(parent) ?? fail("Unknown parent version");
+	}
+}
+
+export const DependentFormatVersion = {
+	fromUnique: <TChildVersion extends FormatVersion>(child: TChildVersion) =>
+		new UniqueDependentFormatVersion(child),
+	fromMap: <TParentVersion extends FormatVersion, TChildVersion extends FormatVersion>(
+		map: ReadonlyMap<TParentVersion, TChildVersion>,
+	) => new MappedDependentFormatVersion(map),
+	fromPairs: <TParentVersion extends FormatVersion, TChildVersion extends FormatVersion>(
+		pairs: Iterable<[TParentVersion, TChildVersion]>,
+	) => new MappedDependentFormatVersion(new Map(pairs)),
+};
+
 /**
  * Creates a codec family from a registry of codecs.
  * Any codec that is not a {@link IMultiFormatCodec} will be wrapped with a default binary encoding.
@@ -487,3 +533,17 @@ export enum FluidClientVersion {
  * TODO: Consider using packageVersion.ts to keep this current.
  */
 export const currentVersion: FluidClientVersion = FluidClientVersion.v2_0;
+
+export interface CodecTree {
+	readonly name: string;
+	readonly version: FormatVersion;
+	readonly children?: readonly CodecTree[];
+}
+
+export function jsonableCodecTree(tree: CodecTree): JsonCompatibleReadOnly {
+	return {
+		name: tree.name,
+		version: tree.version ?? "null",
+		children: tree.children?.map(jsonableCodecTree),
+	};
+}

packages/dds/tree/src/codec/index.ts

@@ -5,6 +5,7 @@
 
 export {
 	type FormatVersion,
+	DependentFormatVersion,
 	type IBinaryCodec,
 	type ICodecFamily,
 	type ICodecOptions,
@@ -24,6 +25,8 @@ export {
 	toFormatValidator,
 	FormatValidatorNoOp,
 	type FormatValidator,
+	type CodecTree,
+	jsonableCodecTree,
 	extractJsonValidator,
 } from "./codec.js";
 export {

packages/dds/tree/src/core/index.ts

@@ -102,6 +102,8 @@ export {
 	cursorChunk,
 	tryGetChunk,
 	type ChunkedCursor,
+	type DetachedFieldIndexFormatVersion,
+	getCodecTreeForDetachedFieldIndexFormat,
 } from "./tree/index.js";
 
 export {

packages/dds/tree/src/core/tree/detachedFieldIndexCodecs.ts

@@ -6,6 +6,7 @@
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 import {
+	type CodecTree,
 	type CodecWriteOptions,
 	FluidClientVersion,
 	type ICodecFamily,
@@ -42,3 +43,10 @@ export function makeDetachedFieldIndexCodecFamily(
 		[version2, makeDetachedNodeToFieldCodecV2(revisionTagCodec, options, idCompressor)],
 	]);
 }
+
+export type DetachedFieldIndexFormatVersion = 1 | 2;
+export function getCodecTreeForDetachedFieldIndexFormat(
+	version: DetachedFieldIndexFormatVersion,
+): CodecTree {
+	return { name: "DetachedFieldIndex", version };
+}

packages/dds/tree/src/core/tree/index.ts

@@ -118,4 +118,10 @@ export {
 } from "./chunk.js";
 
 export { DetachedFieldIndex } from "./detachedFieldIndex.js";
+
+export {
+	type DetachedFieldIndexFormatVersion,
+	getCodecTreeForDetachedFieldIndexFormat,
+} from "./detachedFieldIndexCodecs.js";
+
 export { type ForestRootId } from "./detachedFieldIndexTypes.js";

packages/dds/tree/src/feature-libraries/chunked-forest/codec/codecs.ts

@@ -7,6 +7,7 @@ import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 import type { IIdCompressor, SessionId } from "@fluidframework/id-compressor";
 
 import {
+	type CodecTree,
 	type FluidClientVersion,
 	type ICodecOptions,
 	type IJsonCodec,
@@ -33,7 +34,7 @@ import {
 
 import { decode } from "./chunkDecoding.js";
 import type { FieldBatch } from "./fieldBatch.js";
-import { EncodedFieldBatch, validVersions } from "./format.js";
+import { EncodedFieldBatch, validVersions, type FieldBatchFormatVersion } from "./format.js";
 import { schemaCompressedEncode } from "./schemaBasedEncode.js";
 import { uncompressedEncode } from "./uncompressedEncode.js";
 
@@ -197,3 +198,7 @@ export function makeFieldBatchCodec(
 		},
 	});
 }
+
+export function getCodecTreeForFieldBatchFormat(version: FieldBatchFormatVersion): CodecTree {
+	return { name: "FieldBatch", version };
+}

packages/dds/tree/src/feature-libraries/chunked-forest/codec/format.ts

@@ -15,6 +15,7 @@ import {
 } from "./formatGeneric.js";
 
 export const version = 1;
+export type FieldBatchFormatVersion = 1;
 
 // Compatible versions used for format/version validation.
 // TODO: A proper version update policy will need to be documented.

packages/dds/tree/src/feature-libraries/chunked-forest/codec/index.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-export { EncodedFieldBatch } from "./format.js";
+export { EncodedFieldBatch, type FieldBatchFormatVersion } from "./format.js";
 export type { FieldBatch } from "./fieldBatch.js";
 export {
 	type FieldBatchCodec,
@@ -14,4 +14,5 @@ export {
 	type IncrementalEncoder,
 	type IncrementalDecoder,
 	type ChunkReferenceId,
+	getCodecTreeForFieldBatchFormat,
 } from "./codecs.js";

packages/dds/tree/src/feature-libraries/chunked-forest/index.ts

@@ -16,6 +16,8 @@ export {
 export { buildChunkedForest } from "./chunkedForest.js";
 export {
 	EncodedFieldBatch,
+	type FieldBatchFormatVersion,
+	getCodecTreeForFieldBatchFormat,
 	type FieldBatch,
 	type FieldBatchCodec,
 	makeFieldBatchCodec,