@fluidframework/tree 2.41.0-338401 → 2.42.0

package/.vscode/settings.json

@@ -24,6 +24,7 @@
 		"endregion",
 		"fluidframework",
 		"insertable",
+		"parameterizing",
 		"reentrantly",
 		"typeparam",
 		"unannotate",

package/CHANGELOG.md

@@ -1,5 +1,379 @@
 # @fluidframework/tree
 
+## 2.42.0
+
+### Minor Changes
+
+- Fix Tree.key and Tree.parent for Unhydrated nodes after edits ([#24708](https://github.com/microsoft/FluidFramework/pull/24708)) [8aa5c233e2](https://github.com/microsoft/FluidFramework/commit/8aa5c233e2d59f440fd9c923bca14687bb958d66)
+
+  In some cases, editing [Unhydrated](https://fluidframework.com/docs/api/fluid-framework/unhydrated-typealias) nodes could result in incorrect results being returned from [Tree.key](https://fluidframework.com/docs/data-structures/tree/nodes#treekey) and [Tree.parent](https://fluidframework.com/docs/data-structures/tree/nodes#treeparent).
+  This has been fixed.
+
+- Defaulted identifier fields on unhydrated nodes are now enumerable ([#24739](https://github.com/microsoft/FluidFramework/pull/24739)) [3a5d0acfb6](https://github.com/microsoft/FluidFramework/commit/3a5d0acfb65f93a927405241e6047c8a04c8da58)
+
+  Previously, there was a special case for defaulted [identifier](https://fluidframework.com/docs/api/fluid-framework/schemafactory-class#identifier-property) fields on unhydrated nodes where they were not enumerable.
+  This special case has been removed: they are now enumerable independent of hydration status and defaulting.
+
+- Name collisions from structurally named schema now error ([#24707](https://github.com/microsoft/FluidFramework/pull/24707)) [a343f0498f](https://github.com/microsoft/FluidFramework/commit/a343f0498f2039e68aa11e8ede98f32391ce727d)
+
+  It is legal to have multiple [TreeNodeSchema](https://fluidframework.com/docs/api/fluid-framework/treenodeschema-typealias) with the same name so long as they are not used together in the same tree.
+  Using different schema with the same name when building otherwise identical [structurally named](https://fluidframework.com/docs/api/fluid-framework/schemafactory-class#schemafactory-remarks) in the same [SchemaFactory](https://fluidframework.com/docs/api/fluid-framework/schemafactory-class) is not valid, however.
+  Previously doing this would not error, and instead return the first structurally named schema with that name.
+  Now this case throws an informative error:
+
+  ```typescript
+  const factory = new SchemaFactory(undefined);
+  class Child1 extends factory.object("Child", {}) {}
+  class Child2 extends factory.object("Child", {}) {}
+
+  const a = factory.map(Child1);
+
+  // Throws a UsageError with the message:
+  // "Structurally named schema collision: two schema named "Array<["Child"]>" were defined with different input schema."
+  const b = factory.array(Child2);
+  ```
+
+## 2.41.0
+
+### Minor Changes
+
+- TreeAlpha.create now accepts unhydrated nodes ([#24629](https://github.com/microsoft/FluidFramework/pull/24629)) [e63af87aeb](https://github.com/microsoft/FluidFramework/commit/e63af87aeb7ece1ff0969027904c3b18f122d2d1)
+
+  [TreeAlpha.create](https://fluidframework.com/docs/api/fluid-framework/treealpha-interface#create-methodsignature) now accepts [unhydrated](https://fluidframework.com/docs/api/fluid-framework/unhydrated-typealias) nodes.
+  `TreeAlpha.create`'s documentation has been updated to clarify that this is supported.
+
+  Additionally `TreeAlpha.create` no longer throws a "Tree does not conform to schema" error when given a tree omitting an identifier.
+  Instead, the identifier behaves like it would for other ways to build unhydrated nodes: remaining unreadable until hydrated.
+
+- SharedTrees's FluidClientVersion enum (alpha) has been redesigned ([#24638](https://github.com/microsoft/FluidFramework/pull/24638)) [5f3b9d7b7d](https://github.com/microsoft/FluidFramework/commit/5f3b9d7b7d12307d89cbd4b88f5e2d6e1833680d)
+
+  Users of [FluidClientVersion](https://fluidframework.com/docs/api/fluid-framework/fluidclientversion-enum)'s `v2_1`, `v2_2`, and `v2_3` entries should specify `v2_0` instead.
+  This will result in no functional differences since no code currently opts into any additional functionality based on specifying those versions.
+  The new approach avoids listing versions which there is currently no reason to select, and thus these options have been removed.
+  If future work adds support to opt into features which only work starting with some of those versions, they will be re-added at that time.
+
+- ForestTypeExpensiveDebug now validates content against schema ([#24658](https://github.com/microsoft/FluidFramework/pull/24658)) [9d600aae88](https://github.com/microsoft/FluidFramework/commit/9d600aae88b9045392067719638258ea7407c2eb)
+
+  When opting into using [ForestTypeExpensiveDebug](https://fluidframework.com/docs/api/fluid-framework/#foresttypeexpensivedebug-variable) using [configuredSharedTree](https://fluidframework.com/docs/api/fluid-framework/#configuredsharedtree-function), the tree is now checked against the schema on load and after every edit.
+  This should help detect and diagnose document corruption bugs.
+
+  ```typescript
+  const DebugSharedTree = configuredSharedTree({
+    jsonValidator: typeboxValidator,
+    // Now detects corrupted documents which are out of schema.
+    forest: ForestTypeExpensiveDebug,
+  });
+  ```
+
+- The comparePersistedSchema function (alpha) has had its canInitialize parameter removed ([#24606](https://github.com/microsoft/FluidFramework/pull/24606)) [d083a1780a](https://github.com/microsoft/FluidFramework/commit/d083a1780a1db74a922cbfb451d23ab932c0eb32)
+
+  [comparePersistedSchema](https://fluidframework.com/docs/api/tree/#comparepersistedschema-function) has had its `canInitialize` parameter removed.
+  This parameter was only used to add to the output [SchemaCompatibilityStatus](https://fluidframework.com/docs/api/fluid-framework/schemacompatibilitystatus-interface).
+  If a full `SchemaCompatibilityStatus` is still desired, the `canInitialize` value can be added to the result:
+
+  ```typescript
+  // old
+  const result = comparePersistedSchema(a, b, canInitialize);
+  // new
+  const result = { ...comparePersistedSchema(a, b), canInitialize };
+  ```
+
+- TreeNodes now implicitly generate identifiers on access instead of throwing ([#24665](https://github.com/microsoft/FluidFramework/pull/24665)) [cd5976b959](https://github.com/microsoft/FluidFramework/commit/cd5976b959d6b7a5259e3bb9ef816f842724bc6e)
+
+  Accessing a defaulted [identifier](https://fluidframework.com/docs/api/fluid-framework/schemafactory-class#identifier-property) on an [Unhydrated](https://fluidframework.com/docs/api/fluid-framework/unhydrated-typealias) `TreeNode` no longer throws a usage error.
+  Instead, a new UUID is allocated for the identifier and returned.
+  These UUIDs will be more compressible than random ones, since they all come from a single sequence (starting with a random UUID).
+  They will not be fully compressed like the identifiers generated after hydration that leverage the document's [IIdCompressor](https://fluidframework.com/docs/api/id-compressor/iidcompressor-interface).
+
+  ```typescript
+  const factory = new SchemaFactory("test");
+  class HasIdentifier extends schema.object("A", { id: factory.identifier }) {}
+  // This used to throw an error:
+  const id = new HasIdentifier({}).id;
+  ```
+
+- New TableSchema (alpha) APIs ([#24579](https://github.com/microsoft/FluidFramework/pull/24579)) [e565f6838b](https://github.com/microsoft/FluidFramework/commit/e565f6838b31d3e777da942c806606575123f6d6)
+
+  A `TableSchema` utility has been added to Shared Tree for managing dynamic, tabular data.
+  This new `TableSchema` namespace contains APIs for creating column, row, and table [node schema](https://fluidframework.com/docs/api/fluid-framework/treenodeschema-typealias).
+
+  Note: these APIs require the use of [SchemaFactoryAlpha](https://fluidframework.com/docs/api/fluid-framework/schemafactoryalpha-class).
+
+  > [!WARNING]
+  > These APIs are in preview and are subject to change.
+  > Until these APIs have stabilized, it is not recommended to use them in production code.
+  > There may be breaking changes to these APIs and their underlying data format.
+  > Using these APIs in production code may result in data loss or corruption.
+
+  #### Creating a table
+
+  You can craft a table schema with `TableSchema.table`.
+  This includes providing a schema for the cells that will appear in the table:
+
+  ```typescript
+  class MyTable extends TableSchema.table({
+    schemaFactory,
+    cell: schemaFactory.string,
+  }) {}
+
+  const table = new MyTable({
+    columns: [{ id: "column-0" }],
+    rows: [{ id: "row-0", cells: { "column-0": "Hello world!" } }],
+  });
+  ```
+
+  #### Creating a table with custom column and row schema
+
+  To associate additional data with your rows or columns, generate custom row and column schema using `TableSchema.column` and `TableSchema.row`.
+  These schema can then be provided to `TableSchema.table`:
+
+  ```typescript
+  class MyColumn extends TableSchema.column({
+    schemaFactory,
+    cell: Cell,
+    props: schemaFactory.object("TableColumnProps", {
+      label: schemaFactory.string,
+    }),
+  }) {}
+
+  class MyRow extends TableSchema.row({
+    schemaFactory,
+    cell: Cell,
+  }) {}
+
+  class MyTable extends TableSchema.table({
+    schemaFactory,
+    cell: Cell,
+    column: MyColumn,
+    row: MyRow,
+  }) {}
+
+  const table = new MyTable({
+    columns: [
+      new MyColumn({ props: { label: "Entry" } }),
+      new MyColumn({ props: { label: "Date" } }),
+      new MyColumn({ props: { label: "Amount" } }),
+    ],
+    rows: [],
+  });
+  ```
+
+  #### Interacting with the table
+
+  Table trees created using `TableSchema` offer various APIs to make working with tabular data easy.
+  These include:
+
+  - Insertion and removal of columns, rows, and cells.
+  - Cell access by column/row.
+
+  ```typescript
+  // Create an empty table
+  const table = MyTable.empty();
+
+  const column0 = new MyColumn({
+    props: { label: "Column 0" },
+  });
+
+  // Append a column to the end of the table.
+  table.insertColumn({
+    column: column0,
+  });
+
+  const rows = [new MyRow({ cells: {} }), new MyRow({ cells: {} })];
+
+  // Insert rows at the beginning of the table.
+  table.insertRows({
+    index: 0,
+    rows,
+  });
+
+  // Set cell at row 0, column 0.
+  table.setCell({
+    key: {
+      column: column0,
+      row: rows[0],
+    },
+    cell: "Hello",
+  });
+
+  // Set cell at row 1, column 0.
+  table.setCell({
+    key: {
+      column: column0,
+      row: rows[1],
+    },
+    cell: "World",
+  });
+
+  // Remove the first row.
+  // Note: this will also remove the row's cell.
+  table.removeRow(rows[0]);
+
+  // Remove the column.
+  // Note: this will *not* remove the remaining cell under this column.
+  table.removeColumn(column0);
+  ```
+
+  #### Listening for changes
+
+  Listening for changes to table trees behaves just like it would for any other nodes in a Shared Tree (see [here](https://fluidframework.com/docs/data-structures/tree/events) for more details).
+
+  The most straightforward option is to listen for any changes to the table node and its descendants.
+  For example:
+
+  ```typescript
+  class Cell extends schemaFactory.object("TableCell", {
+    value: schemaFactory.string,
+  }) {}
+
+  class Table extends TableSchema.table({
+    schemaFactory,
+    cell: Cell,
+  }) {}
+
+  const table = new Table({
+    columns: [{ id: "column-0" }],
+    rows: [{ id: "row-0", cells: {} }],
+  });
+
+  // Listen for any changes to the table and its children.
+  // The "treeChanged" event will fire when the `table` node or any of its descendants change.
+  Tree.on(table, "treeChanged", () => {
+    // Respond to the change.
+  });
+  ```
+
+  If you need more granular eventing to meet your performance needs, that is possible as well.
+  For example, if you wish to know when the table's list of rows changes, you could do the following:
+
+  ```typescript
+  class Cell extends schemaFactory.object("TableCell", {
+    value: schemaFactory.string,
+  }) {}
+
+  class Table extends TableSchema.table({
+    schemaFactory,
+    cell: Cell,
+  }) {}
+
+  const table = new Table({
+    columns: [{ id: "column-0" }],
+    rows: [{ id: "row-0", cells: {} }],
+  });
+
+  // Listen for any changes to the list of rows.
+  // The "nodeChanged" event will fire only when the `rows` node itself changes (i.e., its own properties change).
+  // In this case, the event will fire when a row is added or removed, or the order of the list is changed.
+  // But it won't fire when a row's properties change, or when the row's cells change, etc.
+  Tree.on(table.rows, "nodeChanged", () => {
+    // Respond to the change.
+  });
+  ```
+
+  #### Limitations
+
+  ##### Orphaned cells
+
+  Cells in the table may become "orphaned."
+  That is, it is possible to enter a state where one or more rows contain cells with no corresponding column.
+  To reduce the likelihood of this, you can manually remove corresponding cells when removing columns.
+
+  For example:
+
+  ```typescript
+  // Remove column1 and all of its cells.
+  // The "transaction" method will ensure that all changes are applied atomically.
+  Tree.runTransaction(table, () => {
+    // Remove column1
+    table.removeColumn(column1);
+
+    // Remove the cell at column1 for each row.
+    for (const row of table.rows) {
+      table.removeCell({
+        column: column1,
+        row,
+      });
+    }
+  });
+  ```
+
+  > [!WARNING]
+  > Note that even with the above precaution, it is possible to enter such an orphaned cell state via the merging of edits.
+  > For example: one client might add a row while another concurrently removes a column, orphaning the cell where the column and row intersected.
+
+- New TreeAlpha.key2 API ([#24623](https://github.com/microsoft/FluidFramework/pull/24623)) [0ddd6b030b](https://github.com/microsoft/FluidFramework/commit/0ddd6b030bf21ef2f315b84e428954ecfe951728)
+
+  The `TreeAlpha.key2` method is meant to eventually replace the public `Tree.key` method.
+  This new method returns `undefined` in the case where there is a root node.
+
+- New TreeAlpha identifier APIs for converting, retrieving, and generating identifiers ([#24218](https://github.com/microsoft/FluidFramework/pull/24218)) [e5b2882132](https://github.com/microsoft/FluidFramework/commit/e5b28821323566112096f05805281b8d5321077d)
+
+  #### TreeAlpha.identifier
+
+  You can retrieve the long identifier with `TreeAlpha.identifier(node)`, where `node` is a `TreeNode`. The long identifier is a stable, compressible UUID generated by the tree.
+  In cases where the node does not yet have an identifier assigned, this will return `undefined`.
+  These cases include:
+
+  - The node does not contain an identifier field.
+  - The node is a non-hydrated node with a user provided identifier. Note that if it is a non-hydrated node without an identifier provided, it will throw an error.
+
+  #### TreeAlpha.identifier.shorten
+
+  You can shorten a long identifier with `TreeAlpha.identifier.shorten(branch, identifier)`, where `branch` is a `TreeBranch`, and `identifier` is a `string`.
+  If the method returns a valid short identifier, this identifier can be passed into `TreeAlpha.identifier.lengthen`
+  to get the original valid long `identifier` back.
+  In the cases where it's not possible to shorten the `identifier`, it will return `undefined`.
+  These cases include:
+
+  - A compressible long identifier, but it is unrecognized by the tree that the node belongs to. This can occur if the identifier is not generated from the tree.
+  - An identifier which is not compressible by the tree. This can occur if the node's identifier was a user provided string.
+
+  #### TreeAlpha.identifier.lengthen
+
+  You can lengthen a short identifier with `TreeAlpha.identifier.lengthen(branch, identifier)`, where `branch` is a `TreeBranch`, and `identifier` is a `number`.
+  If the method returns a valid long identifier, this identifier can be passed into `TreeAlpha.identifier.shorten` to get the original `identifier` back.
+  In the cases where it's not possible to lengthen the `identifier`, this method will throw an error.
+  These cases include:
+
+  - An unrecognized short identifier. This can occur if the identifier is not generated from the tree.
+
+  #### TreeAlpha.identifier.getShort
+
+  You can retrieve the short identifier from a node with `TreeAlpha.identifier.getShort(node)` where `node` is a `TreeNode`.
+  If it is not possible to retrieve the short identifier, it will return `undefined`
+
+  ##### Example for a node with valid identifier
+
+  ```typescript
+  // This will retrieve the short identifier from the node.
+  const shortIdentifier = TreeAlpha.identifier.getShort(
+    nodeWithValidIdentifier,
+  );
+  ```
+
+  ##### Examples for when you get undefined
+
+  In cases where the node provided does not contain an identifier that is recognized or compressible by the tree that the node belongs to, this method will return undefined.
+  This will occur in the following cases:
+
+  - The node is an non-hydrated node with a user provided identifier. Note that if it is an non-hydrated node without an identifier provided, it will throw an error.
+  - The node does not contain an identifier field.
+  - The node contains a compressible long identifier, but it is unrecognized by the tree that the node belongs to. This can occur if the identifier is not generated from the tree.
+  - The node contains an identifier which is not compressible by its id compressor. This can occur if the node's identifier was a user provided string.
+
+  ```typescript
+  // This will return undefined
+  const shortIdentifier = TreeAlpha.identifier.getShort(node);
+  ```
+
+  #### TreeAlpha.identifier.create
+
+  You can create a long identifier from a branch with `TreeAlpha.identifier.create(branch)` where `branch` is a `TreeBranch`.
+
+  ```typescript
+  const createdIdentifier = TreeAlpha.identifier.create(branch);
+  ```
+
 ## 2.40.0
 
 ### Minor Changes

package/api-report/tree.alpha.api.md

@@ -94,6 +94,11 @@ export function cloneWithReplacements(root: unknown, rootKey: string, replacer:
     value: unknown;
 }): unknown;
 
+// @alpha @input
+export interface CodecWriteOptions extends ICodecOptions {
+    readonly oldestCompatibleClient: FluidClientVersion;
+}
+
 // @public
 export enum CommitKind {
     Default = 0,
@@ -274,7 +279,7 @@ export function getSimpleSchema(schema: ImplicitFieldSchema): SimpleTreeSchema;
 // @alpha
 export type HandleConverter<TCustom> = (data: IFluidHandle) => TCustom;
 
-// @alpha
+// @alpha @input
 export interface ICodecOptions {
     readonly jsonValidator: JsonValidator;
 }
@@ -501,7 +506,7 @@ export type JsonTreeSchema = JsonFieldSchema & {
     readonly $defs: Record<JsonSchemaId, JsonNodeSchema>;
 };
 
-// @alpha
+// @alpha @input
 export interface JsonValidator {
     compile<Schema extends TSchema>(schema: Schema): SchemaValidationFunction<Schema>;
 }
@@ -803,7 +808,7 @@ export interface SchemaStatics {
     readonly string: LeafSchema<"string", string>;
 }
 
-// @alpha
+// @alpha @input
 export interface SchemaValidationFunction<Schema extends TSchema> {
     check(data: unknown): data is Static<Schema>;
 }
@@ -827,8 +832,8 @@ export const SharedTreeFormatVersion: {
 // @alpha
 export type SharedTreeFormatVersion = typeof SharedTreeFormatVersion;
 
-// @alpha
-export type SharedTreeOptions = Partial<ICodecOptions> & Partial<SharedTreeFormatOptions> & ForestOptions;
+// @alpha @input
+export type SharedTreeOptions = Partial<CodecWriteOptions> & Partial<SharedTreeFormatOptions> & ForestOptions;
 
 // @alpha @sealed
 export interface SimpleArrayNodeSchema<out TCustomMetadata = unknown> extends SimpleNodeSchemaBase<NodeKind.Array, TCustomMetadata> {
@@ -1175,12 +1180,12 @@ export interface TreeAlpha {
     branch(node: TreeNode): TreeBranch | undefined;
     create<const TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(schema: UnsafeUnknownSchema extends TSchema ? ImplicitFieldSchema : TSchema & ImplicitFieldSchema, data: InsertableField<TSchema>): Unhydrated<TSchema extends ImplicitFieldSchema ? TreeFieldFromImplicitField<TSchema> : TreeNode | TreeLeafValue | undefined>;
     exportCompressed(tree: TreeNode | TreeLeafValue, options: {
-        oldestCompatibleClient: FluidClientVersion;
         idCompressor?: IIdCompressor;
-    }): JsonCompatible<IFluidHandle>;
+    } & Pick<CodecWriteOptions, "oldestCompatibleClient">): JsonCompatible<IFluidHandle>;
     exportConcise(node: TreeNode | TreeLeafValue, options?: TreeEncodingOptions): ConciseTree;
     exportConcise(node: TreeNode | TreeLeafValue | undefined, options?: TreeEncodingOptions): ConciseTree | undefined;
     exportVerbose(node: TreeNode | TreeLeafValue, options?: TreeEncodingOptions): VerboseTree;
+    readonly identifier: TreeIdentifierUtils;
     importCompressed<const TSchema extends ImplicitFieldSchema>(schema: TSchema, compressedData: JsonCompatible<IFluidHandle>, options: {
         idCompressor?: IIdCompressor;
     } & ICodecOptions): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
@@ -1274,6 +1279,15 @@ export interface TreeEncodingOptions {
 // @public
 export type TreeFieldFromImplicitField<TSchema extends ImplicitFieldSchema = FieldSchema> = TSchema extends FieldSchema<infer Kind, infer Types> ? ApplyKind<TreeNodeFromImplicitAllowedTypes<Types>, Kind> : TSchema extends ImplicitAllowedTypes ? TreeNodeFromImplicitAllowedTypes<TSchema> : TreeNode | TreeLeafValue | undefined;
 
+// @alpha @sealed
+export interface TreeIdentifierUtils {
+    (node: TreeNode): string | undefined;
+    create(branch: TreeBranch): string;
+    getShort(node: TreeNode): number | undefined;
+    lengthen(branch: TreeBranch, nodeIdentifier: number): string;
+    shorten(branch: TreeBranch, nodeIdentifier: string): number | undefined;
+}
+
 // @alpha
 export interface TreeIndex<TKey extends TreeIndexKey, TValue> extends ReadonlyMap<TKey, TValue> {
     dispose(): void;

package/dist/alpha.d.ts

@@ -103,6 +103,7 @@ export {
 	ArrayNodePojoEmulationSchema, 
 	ArrayNodeSchema, 
 	BranchableTree, 
+	CodecWriteOptions, 
 	ConciseTree, 
 	FactoryContent, 
 	FactoryContentObject, 
@@ -181,6 +182,7 @@ export {
 	TreeBranchFork, 
 	TreeCompressionStrategy, 
 	TreeEncodingOptions, 
+	TreeIdentifierUtils, 
 	TreeIndex, 
 	TreeIndexKey, 
 	TreeIndexNodes, 

package/dist/codec/codec.d.ts

@@ -29,7 +29,7 @@ export interface IDecoder<TDecoded, TEncoded, TContext> {
 /**
  * Validates data complies with some particular schema.
  * Implementations are typically created by a {@link JsonValidator}.
- * @alpha
+ * @alpha @input
  */
 export interface SchemaValidationFunction<Schema extends TSchema> {
     /**
@@ -39,7 +39,7 @@ export interface SchemaValidationFunction<Schema extends TSchema> {
 }
 /**
  * JSON schema validator compliant with draft 6 schema. See https://json-schema.org.
- * @alpha
+ * @alpha @input
  */
 export interface JsonValidator {
     /**
@@ -55,7 +55,9 @@ export interface JsonValidator {
 }
 /**
  * Options relating to handling of persisted data.
- * @alpha
+ *
+ * @see {@link CodecWriteOptions} for options that are specific to encoding data.
+ * @alpha @input
  */
 export interface ICodecOptions {
     /**
@@ -73,6 +75,24 @@ export interface ICodecOptions {
      */
     readonly jsonValidator: JsonValidator;
 }
+/**
+ * Options relating to encoding of persisted data.
+ * @remarks
+ * Extends {@link ICodecOptions} with options that are specific to encoding data.
+ * @alpha @input
+ */
+export interface CodecWriteOptions extends ICodecOptions {
+    /**
+     * The minimum version of the Fluid Framework client output must be encoded to be compatible with.
+     * @remarks
+     * This is used to ensure that the the output from this codec can be used with older versions of the Fluid Framework client.
+     * This includes both concurrent collaboration, and an older version opening the document later.
+     *
+     * Note that versions older than this should not result in data corruption if they access the data:
+     * the data's format should be versioned and if they can't handle the format they should error.
+     */
+    readonly oldestCompatibleClient: FluidClientVersion;
+}
 /**
  * `TContext` allows passing context to the codec which may configure how data is encoded/decoded.
  * This parameter is typically used for:
@@ -200,6 +220,14 @@ export declare function withSchemaValidation<TInMemoryFormat, EncodedSchema exte
  * Versions with no notable impact can be omitted.
  *
  * These use numeric values for easy threshold comparisons.
+ * Without zero padding, version 2.10 is treated as 2.1, which is numerically less than 2.2.
+ * Adding leading zeros to the minor version ensures correct comparisons.
+ * For example, version 2.20.0 is encoded as 2.020, and version 2.2.0 is encoded as 2.002.
+ * For example FF 2.20.0 is encoded as 2.020 and FF 2.2.0 is encoded as 2.002.
+ *
+ * Three digits was selected as that will likely be enough, while two digits could easily be too few.
+ * If three digits ends up being too few, minor releases of 1000 and higher
+ * could still be handled using something like 2.999_00001 without having to change the lower releases.
  *
  * This scheme assumes a single version will always be enough to communicate compatibility.
  * For this to work, compatibility has to be strictly increasing.
@@ -208,6 +236,8 @@ export declare function withSchemaValidation<TInMemoryFormat, EncodedSchema exte
  * such a system can be added if/when its needed since it will be opt in and thus non-breaking.
  *
  * TODO: this should likely be defined higher in the stack and specified when creating the container, possibly as part of its schema.
+ * TODO: compatibility requirements for how this enum can and cannot be changed should be clarified when/if it's used across multiple layers in the stack.
+ * For example, if needed, would adding more leading zeros to the minor version break things.
  * @alpha
  */
 export declare enum FluidClientVersion {

package/dist/codec/codec.d.ts.map

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

package/dist/codec/codec.js

@@ -128,6 +128,14 @@ exports.withSchemaValidation = withSchemaValidation;
  * Versions with no notable impact can be omitted.
  *
  * These use numeric values for easy threshold comparisons.
+ * Without zero padding, version 2.10 is treated as 2.1, which is numerically less than 2.2.
+ * Adding leading zeros to the minor version ensures correct comparisons.
+ * For example, version 2.20.0 is encoded as 2.020, and version 2.2.0 is encoded as 2.002.
+ * For example FF 2.20.0 is encoded as 2.020 and FF 2.2.0 is encoded as 2.002.
+ *
+ * Three digits was selected as that will likely be enough, while two digits could easily be too few.
+ * If three digits ends up being too few, minor releases of 1000 and higher
+ * could still be handled using something like 2.999_00001 without having to change the lower releases.
  *
  * This scheme assumes a single version will always be enough to communicate compatibility.
  * For this to work, compatibility has to be strictly increasing.
@@ -136,6 +144,8 @@ exports.withSchemaValidation = withSchemaValidation;
  * such a system can be added if/when its needed since it will be opt in and thus non-breaking.
  *
  * TODO: this should likely be defined higher in the stack and specified when creating the container, possibly as part of its schema.
+ * TODO: compatibility requirements for how this enum can and cannot be changed should be clarified when/if it's used across multiple layers in the stack.
+ * For example, if needed, would adding more leading zeros to the minor version break things.
  * @alpha
  */
 var FluidClientVersion;
@@ -147,17 +157,17 @@ var FluidClientVersion;
      * @privateRemarks
      * As long as this code is in Tree, there is no reason to have this option as SharedTree did not exist in 1.4.
      */
-    // v1_4 = 1.4,
+    // v1_4 = 1.004,
     /** Fluid Framework Client 2.0 and newer. */
     FluidClientVersion[FluidClientVersion["v2_0"] = 2] = "v2_0";
     /** Fluid Framework Client 2.1 and newer. */
     // If we think we might want to start allowing opting into something that landed in 2.1 (without opting into something newer),
     // we could add an entry like this to allow users to indicate that they can be opted in once we are ready,
-    // then update it to "v2_1" once we actually have the opt in working.
+    // then update it to "2.001" once we actually have the opt in working.
     // v2_1 = v2_0,
     /** Fluid Framework Client 2.41 and newer. */
     // If we land some new formats in 2.41, we can enable selecting
-    // v2_41 = 2.41,
+    // v2_41 = 2.041,
     /**
      * Enable unreleased and unfinished features.
      * @remarks