@fluidframework/tree 2.41.0-338186 → 2.41.0

package/lib/util/breakable.js.map

@@ -1 +1 @@
-{"version":3,"file":"breakable.js","sourceRoot":"","sources":["../../src/util/breakable.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\n\n/**\n * An object which can enter a \"broken\" state where trying to use it is a UsageError.\n */\nexport class Breakable {\n\tprivate brokenBy?: Error;\n\n\tpublic constructor(private readonly name: string) {}\n\n\t/**\n\t * Throws if the object is in the broken state.\n\t * @remarks\n\t * Can use {@link throwIfBroken} to apply this to a method.\n\t */\n\tpublic use(): void {\n\t\tif (this.brokenBy !== undefined) {\n\t\t\tthrow new UsageError(\n\t\t\t\t`Invalid use of ${this.name} after it was put into an invalid state by another error.\\nOriginal Error:\\n${this.brokenBy}`,\n\t\t\t);\n\t\t}\n\t}\n\n\t/**\n\t * Puts this object into the broken state, and throws an error.\n\t *\n\t * @throws If already broken by a different error, throws a UsageError, otherwise throws `brokenBy`.\n\t */\n\tpublic break(brokenBy: Error): never {\n\t\t// If already broken by this error, let it bubble up without rethrowing a modified version.\n\t\t// This prevents internal errors like asserts getting rethrown as different errors when wrapped with multiple call to `{@link Breakable.run}` or `{@link breakingMethod}`.\n\t\tif (this.brokenBy !== brokenBy) {\n\t\t\tthis.use();\n\t\t\tthis.brokenBy = brokenBy;\n\t\t}\n\t\tthrow brokenBy;\n\t}\n\n\t/**\n\t * {@link Breakable.break}, except tolerates `unknown` to be more easily used by catch blocks.\n\t * @privateRemarks\n\t * If there is a use-case, this should be made public.\n\t */\n\tpublic rethrowCaught(brokenBy: unknown): never {\n\t\tif (brokenBy instanceof Error) {\n\t\t\tthis.break(brokenBy);\n\t\t}\n\t\tthis.break(\n\t\t\tnew Error(`Non-error thrown breaking ${this.name}. Thrown value: \"${brokenBy}\"`),\n\t\t);\n\t}\n\n\t/**\n\t * Runs code which should break the object if it throws.\n\t * @remarks\n\t * This also throws if already broken like {@link Breakable.use}.\n\t * Any exceptions this catches are re-thrown.\n\t * Can use {@link breakingMethod} to apply this to a method.\n\t */\n\tpublic run<TResult>(breaker: () => TResult): TResult {\n\t\tthis.use();\n\t\ttry {\n\t\t\treturn breaker();\n\t\t} catch (error: unknown) {\n\t\t\tthis.rethrowCaught(error);\n\t\t}\n\t}\n\n\t/**\n\t * Clears the existing broken state.\n\t * @remarks\n\t * This is rarely safe to to: it is only ok when all objects using this breaker are known to not have been left in an invalid state.\n\t * This is pretty much only safe in tests which just were checking a specific error was thrown, and which know that error closepath is actually exception safe.\n\t */\n\tpublic clearError(): void {\n\t\tassert(this.brokenBy !== undefined, 0x9b6 /* No error to clear */);\n\t\tthis.brokenBy = undefined;\n\t}\n}\n\n/**\n * Marks an object as being able to be in a broken state (unknown/unspecified/broken state due to unhandled exception).\n * @remarks\n * See decorators {@link breakingMethod} and {@link throwIfBroken} for ease of use.\n */\nexport interface WithBreakable {\n\treadonly breaker: Breakable;\n}\n\n/**\n * Decorator for methods which should break the object when they throw.\n * @remarks\n * This also throws if already broken like {@link throwIfBroken}.\n * See {@link Breakable.run} for details.\n *\n * This should be used on methods which modify data that could result in an unsupported/broken state if an exception is thrown while modifying.\n * It is ok for breakingMethods to call each-other.\n * @privateRemarks\n * Explicitly capturing the full `Target` type is necessary to make this work with generic methods with unknown numbers of type parameters.\n */\nexport function breakingMethod<\n\tTarget extends ((...args: any[]) => unknown) & ((this: This, ...args: Args) => Return),\n\tThis extends WithBreakable,\n\tArgs extends never[],\n\tReturn,\n>(target: Target, context?: ClassMethodDecoratorContext<This, Target>): Target {\n\tfunction replacementMethod(this: This, ...args: Args): Return {\n\t\tif (this.breaker === undefined) {\n\t\t\t// This case is necessary for when wrapping methods which are invoked inside the constructor of the base class before `breaker` is set.\n\t\t\t// Since the constructor throwing does not return an object, failing to put it into a broken state is not too bad.\n\t\t\t// However when more than just the constructed object should be broken, this can result in missing a break.\n\t\t\treturn target.call(this, ...args);\n\t\t}\n\t\treturn this.breaker.run(() => {\n\t\t\treturn target.call(this, ...args);\n\t\t});\n\t}\n\tmarkBreaker(replacementMethod);\n\tnameFunctionFrom(replacementMethod, target);\n\treturn replacementMethod as Target;\n}\n\n/**\n * Decorator for methods which should throw if the object is in a broken state.\n * @remarks\n * This should be used on methods which read data that could be invalid when the object is broken.\n * @privateRemarks\n * Explicitly capturing the full `Target` type is necessary to make this work with generic methods with unknown numbers of type parameters.\n */\nexport function throwIfBroken<\n\tTarget extends ((...args: any[]) => unknown) & ((this: This, ...args: Args) => Return),\n\tThis extends WithBreakable,\n\tArgs extends never[],\n\tReturn,\n>(target: Target, context: ClassMethodDecoratorContext<This, Target>): Target {\n\tfunction replacementMethod(this: This, ...args: Args): Return {\n\t\tthis.breaker.use();\n\t\treturn target.call(this, ...args);\n\t}\n\tmarkBreaker(replacementMethod);\n\tnameFunctionFrom(replacementMethod, target);\n\treturn replacementMethod as Target;\n}\n\n// eslint-disable-next-line @typescript-eslint/ban-types\ntype PossiblyNamedFunction = Function & { displayName?: undefined | string };\n\n// eslint-disable-next-line @typescript-eslint/ban-types\nfunction nameFunctionFrom(toName: Function, nameFrom: Function): void {\n\t(toName as PossiblyNamedFunction).displayName =\n\t\t(nameFrom as PossiblyNamedFunction).displayName ?? nameFrom.name;\n}\n\nconst isBreakerSymbol: unique symbol = Symbol(\"isBreaker\");\n\n// Accepting any function like value is desired and safe here as this does not call the provided function.\n// eslint-disable-next-line @typescript-eslint/ban-types\nfunction markBreaker(f: Function): void {\n\t(f as unknown as Record<typeof isBreakerSymbol, true>)[isBreakerSymbol] = true;\n}\n\n// Accepting any function like value is desired and safe here as this does not call the provided function.\n// eslint-disable-next-line @typescript-eslint/ban-types\nfunction isBreaker(f: Function): boolean {\n\treturn isBreakerSymbol in (f as unknown as Record<typeof isBreakerSymbol, true>);\n}\n\n/**\n * Decorator for classes which should break when their methods throw.\n * @remarks\n * Applies {@link breakingMethod} to all methods declared directly by class or its base classes.\n * Does not include those on derived classes.\n * Does not include getters or setters, or value properties.\n * Methods already marked as {@link breakingMethod} or {@link throwIfBroken} are unaffected.\n */\nexport function breakingClass<Target extends abstract new (...args: any[]) => WithBreakable>(\n\ttarget: Target,\n\tcontext: ClassDecoratorContext<Target>,\n): Target {\n\t// This could extend target, but doing so adds an extra step in the prototype chain and makes the instances just show up as \"DecoratedBreakable\" in the debugger.\n\tconst DecoratedBreakable = target;\n\n\t// Keep track of what keys we have seen (and already wrapped if needed).\n\t// Used to avoid rewrapping already wrapped properties.\n\t// Preloaded with \"constructor\" to avoid wrapping the constructor as there is no need to set the broken flag when the constructor throws and does not return an object.\n\t// Avoiding wrapping the constructor also avoids messing up the displayed name in the debugger.\n\tconst doNotWrap: Set<string | symbol> = new Set([\"constructor\"]);\n\n\tlet prototype: object | null = target.prototype;\n\twhile (prototype !== null) {\n\t\tfor (const key of Reflect.ownKeys(prototype)) {\n\t\t\tif (!doNotWrap.has(key)) {\n\t\t\t\tdoNotWrap.add(key);\n\t\t\t\tconst descriptor = Reflect.getOwnPropertyDescriptor(prototype, key);\n\t\t\t\tif (descriptor !== undefined) {\n\t\t\t\t\t// Method\n\t\t\t\t\tif (typeof descriptor.value === \"function\") {\n\t\t\t\t\t\tif (!isBreaker(descriptor.value)) {\n\t\t\t\t\t\t\t// This does not affect the original class, see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertyDescriptor\n\t\t\t\t\t\t\tdescriptor.value = breakingMethod(descriptor.value);\n\t\t\t\t\t\t\tObject.defineProperty(DecoratedBreakable.prototype, key, descriptor);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tprototype = Reflect.getPrototypeOf(prototype);\n\t}\n\n\treturn DecoratedBreakable;\n}\n"]}
+{"version":3,"file":"breakable.js","sourceRoot":"","sources":["../../src/util/breakable.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\n\n/**\n * An object which can enter a \"broken\" state where trying to use it is a UsageError.\n * @remarks\n * Use {@link WithBreakable} to apply this to another object.\n * @sealed\n */\nexport class Breakable {\n\tprivate brokenBy?: Error;\n\n\tpublic constructor(\n\t\t/**\n\t\t * A name for a given breakable scope.\n\t\t * @remarks\n\t\t * This is useful for documenting the semantics of a given Breakable and when inspecting things in the debugger, but is currently otherwise unused.\n\t\t */\n\t\tprivate readonly name: string,\n\t) {}\n\n\t/**\n\t * Throws if this object is in the broken state.\n\t * @remarks\n\t * Can use {@link throwIfBroken} to apply this to a method.\n\t */\n\tpublic use(): void {\n\t\tif (this.brokenBy !== undefined) {\n\t\t\tthrow new UsageError(\n\t\t\t\t`Invalid use of ${this.name} after it was put into an invalid state by another error.\\nOriginal Error:\\n${this.brokenBy}`,\n\t\t\t);\n\t\t}\n\t}\n\n\t/**\n\t * Puts this object into the broken state, and throws an error.\n\t *\n\t * @throws If already broken by a different error, throws a UsageError, otherwise throws `brokenBy`.\n\t */\n\tpublic break(brokenBy: Error): never {\n\t\t// If already broken by this error, let it bubble up without rethrowing a modified version.\n\t\t// This prevents internal errors like asserts getting rethrown as different errors when wrapped with multiple call to `{@link Breakable.run}` or `{@link breakingMethod}`.\n\t\tif (this.brokenBy !== brokenBy) {\n\t\t\tthis.use();\n\t\t\tthis.brokenBy = brokenBy;\n\t\t}\n\t\tthrow brokenBy;\n\t}\n\n\t/**\n\t * {@link Breakable.break}, except tolerates `unknown` to be more easily used by catch blocks.\n\t * @privateRemarks\n\t * If there is a use-case, this should be made public.\n\t */\n\tprivate rethrowCaught(brokenBy: unknown): never {\n\t\tif (brokenBy instanceof Error) {\n\t\t\tthis.break(brokenBy);\n\t\t}\n\t\tthis.break(\n\t\t\tnew Error(`Non-error thrown breaking ${this.name}. Thrown value: \"${brokenBy}\"`),\n\t\t);\n\t}\n\n\t/**\n\t * Runs code which should break the object if it throws.\n\t * @remarks\n\t * Like {@link Breakable.use}, this also throws if already broken.\n\t * Any exceptions this catches are re-thrown.\n\t * Can use {@link breakingMethod} to apply this to a method.\n\t */\n\tpublic run<TResult>(breaker: () => TResult): TResult {\n\t\tthis.use();\n\t\ttry {\n\t\t\treturn breaker();\n\t\t} catch (error: unknown) {\n\t\t\tthis.rethrowCaught(error);\n\t\t}\n\t}\n\n\t/**\n\t * Clears the existing broken state.\n\t * @remarks\n\t * This is rarely safe to to: it is only ok when all objects using this breaker are known to not have been left in an invalid state.\n\t * This is pretty much only safe in tests which just were checking a specific error was thrown, and which know that error closepath is actually exception safe.\n\t */\n\tpublic clearError(): void {\n\t\tassert(this.brokenBy !== undefined, 0x9b6 /* No error to clear */);\n\t\tthis.brokenBy = undefined;\n\t}\n}\n\n/**\n * Marks an object as being able to be in a broken state (unknown/unspecified/broken state due to unhandled exception).\n * @remarks\n * See decorators {@link breakingMethod} and {@link throwIfBroken} for ease of use.\n */\nexport interface WithBreakable {\n\t/**\n\t * The breaker for this object.\n\t * @remarks\n\t * If this `breaker` is in the broken state, the `WithBreakable` should be considered in a broken state.\n\t */\n\treadonly breaker: Breakable;\n}\n\n/**\n * Decorator for methods which should break the object when they throw.\n * @remarks\n * This also throws if already broken like {@link throwIfBroken}.\n * See {@link Breakable.run} for details.\n *\n * This should be used on methods which modify data that could result in an unsupported/broken state if an exception is thrown while modifying.\n * It is ok for breakingMethods to call each-other.\n * @privateRemarks\n * Explicitly capturing the full `Target` type is necessary to make this work with generic methods with unknown numbers of type parameters.\n */\nexport function breakingMethod<\n\tTarget extends ((...args: any[]) => unknown) & ((this: This, ...args: Args) => Return),\n\tThis extends WithBreakable,\n\tArgs extends never[],\n\tReturn,\n>(target: Target, context?: ClassMethodDecoratorContext<This, Target>): Target {\n\tfunction replacementMethod(this: This, ...args: Args): Return {\n\t\tif (this.breaker === undefined) {\n\t\t\t// This case is necessary for when wrapping methods which are invoked inside the constructor of the base class before `breaker` is set.\n\t\t\t// Since the constructor throwing does not return an object, failing to put it into a broken state is not too bad.\n\t\t\t// However when more than just the constructed object should be broken, this can result in missing a break.\n\t\t\treturn target.call(this, ...args);\n\t\t}\n\t\treturn this.breaker.run(() => {\n\t\t\treturn target.call(this, ...args);\n\t\t});\n\t}\n\tmarkBreaker(replacementMethod);\n\tnameFunctionFrom(replacementMethod, target);\n\treturn replacementMethod as Target;\n}\n\n/**\n * Decorator for methods which should throw if the object is in a broken state.\n * @remarks\n * This should be used on methods which read data that could be invalid when the object is broken.\n * @privateRemarks\n * Explicitly capturing the full `Target` type is necessary to make this work with generic methods with unknown numbers of type parameters.\n */\nexport function throwIfBroken<\n\tTarget extends ((...args: any[]) => unknown) & ((this: This, ...args: Args) => Return),\n\tThis extends WithBreakable,\n\tArgs extends never[],\n\tReturn,\n>(target: Target, context: ClassMethodDecoratorContext<This, Target>): Target {\n\tfunction replacementMethod(this: This, ...args: Args): Return {\n\t\tthis.breaker.use();\n\t\treturn target.call(this, ...args);\n\t}\n\tmarkBreaker(replacementMethod);\n\tnameFunctionFrom(replacementMethod, target);\n\treturn replacementMethod as Target;\n}\n\n// eslint-disable-next-line @typescript-eslint/ban-types\ntype PossiblyNamedFunction = Function & { displayName?: undefined | string };\n\n// eslint-disable-next-line @typescript-eslint/ban-types\nfunction nameFunctionFrom(toName: Function, nameFrom: Function): void {\n\t(toName as PossiblyNamedFunction).displayName =\n\t\t(nameFrom as PossiblyNamedFunction).displayName ?? nameFrom.name;\n}\n\nconst isBreakerSymbol: unique symbol = Symbol(\"isBreaker\");\n\n// Accepting any function like value is desired and safe here as this does not call the provided function.\n// eslint-disable-next-line @typescript-eslint/ban-types\nfunction markBreaker(f: Function): void {\n\t(f as unknown as Record<typeof isBreakerSymbol, true>)[isBreakerSymbol] = true;\n}\n\n// Accepting any function like value is desired and safe here as this does not call the provided function.\n// eslint-disable-next-line @typescript-eslint/ban-types\nfunction isBreaker(f: Function): boolean {\n\treturn isBreakerSymbol in (f as unknown as Record<typeof isBreakerSymbol, true>);\n}\n\n/**\n * Decorator for classes which should break when their methods throw.\n * @remarks\n * Applies {@link breakingMethod} to all methods declared directly by class or its base classes.\n * Does not include those on derived classes.\n * Does not include getters or setters, or value properties.\n * Methods already marked as {@link breakingMethod} or {@link throwIfBroken} are unaffected.\n */\nexport function breakingClass<Target extends abstract new (...args: any[]) => WithBreakable>(\n\ttarget: Target,\n\tcontext: ClassDecoratorContext<Target>,\n): Target {\n\t// This could extend target, but doing so adds an extra step in the prototype chain and makes the instances just show up as \"DecoratedBreakable\" in the debugger.\n\tconst DecoratedBreakable = target;\n\n\t// Keep track of what keys we have seen (and already wrapped if needed).\n\t// Used to avoid rewrapping already wrapped properties.\n\t// Preloaded with \"constructor\" to avoid wrapping the constructor as there is no need to set the broken flag when the constructor throws and does not return an object.\n\t// Avoiding wrapping the constructor also avoids messing up the displayed name in the debugger.\n\tconst doNotWrap: Set<string | symbol> = new Set([\"constructor\"]);\n\n\tlet prototype: object | null = target.prototype;\n\twhile (prototype !== null) {\n\t\tfor (const key of Reflect.ownKeys(prototype)) {\n\t\t\tif (!doNotWrap.has(key)) {\n\t\t\t\tdoNotWrap.add(key);\n\t\t\t\tconst descriptor = Reflect.getOwnPropertyDescriptor(prototype, key);\n\t\t\t\tif (descriptor !== undefined) {\n\t\t\t\t\t// Method\n\t\t\t\t\tif (typeof descriptor.value === \"function\") {\n\t\t\t\t\t\tif (!isBreaker(descriptor.value)) {\n\t\t\t\t\t\t\t// This does not affect the original class, see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertyDescriptor\n\t\t\t\t\t\t\tdescriptor.value = breakingMethod(descriptor.value);\n\t\t\t\t\t\t\tObject.defineProperty(DecoratedBreakable.prototype, key, descriptor);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tprototype = Reflect.getPrototypeOf(prototype);\n\t}\n\n\treturn DecoratedBreakable;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/tree",
-  "version": "2.41.0-338186",
+  "version": "2.41.0",
   "description": "Distributed tree",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -89,17 +89,17 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "2.41.0-338186",
-    "@fluidframework/container-runtime": "2.41.0-338186",
-    "@fluidframework/core-interfaces": "2.41.0-338186",
-    "@fluidframework/core-utils": "2.41.0-338186",
-    "@fluidframework/datastore-definitions": "2.41.0-338186",
-    "@fluidframework/driver-definitions": "2.41.0-338186",
-    "@fluidframework/id-compressor": "2.41.0-338186",
-    "@fluidframework/runtime-definitions": "2.41.0-338186",
-    "@fluidframework/runtime-utils": "2.41.0-338186",
-    "@fluidframework/shared-object-base": "2.41.0-338186",
-    "@fluidframework/telemetry-utils": "2.41.0-338186",
+    "@fluid-internal/client-utils": "~2.41.0",
+    "@fluidframework/container-runtime": "~2.41.0",
+    "@fluidframework/core-interfaces": "~2.41.0",
+    "@fluidframework/core-utils": "~2.41.0",
+    "@fluidframework/datastore-definitions": "~2.41.0",
+    "@fluidframework/driver-definitions": "~2.41.0",
+    "@fluidframework/id-compressor": "~2.41.0",
+    "@fluidframework/runtime-definitions": "~2.41.0",
+    "@fluidframework/runtime-utils": "~2.41.0",
+    "@fluidframework/shared-object-base": "~2.41.0",
+    "@fluidframework/telemetry-utils": "~2.41.0",
     "@sinclair/typebox": "^0.34.13",
     "@tylerbu/sorted-btree-es6": "^1.8.0",
     "@types/ungap__structured-clone": "^1.2.0",
@@ -109,19 +109,19 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.17.1",
     "@biomejs/biome": "~1.9.3",
-    "@fluid-internal/mocha-test-setup": "2.41.0-338186",
-    "@fluid-private/stochastic-test-utils": "2.41.0-338186",
-    "@fluid-private/test-dds-utils": "2.41.0-338186",
-    "@fluid-private/test-drivers": "2.41.0-338186",
+    "@fluid-internal/mocha-test-setup": "~2.41.0",
+    "@fluid-private/stochastic-test-utils": "~2.41.0",
+    "@fluid-private/test-dds-utils": "~2.41.0",
+    "@fluid-private/test-drivers": "~2.41.0",
     "@fluid-tools/benchmark": "^0.51.0",
     "@fluid-tools/build-cli": "^0.55.0",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.55.0",
-    "@fluidframework/container-definitions": "2.41.0-338186",
-    "@fluidframework/container-loader": "2.41.0-338186",
-    "@fluidframework/eslint-config-fluid": "^5.7.3",
-    "@fluidframework/test-runtime-utils": "2.41.0-338186",
-    "@fluidframework/test-utils": "2.41.0-338186",
+    "@fluidframework/container-definitions": "~2.41.0",
+    "@fluidframework/container-loader": "~2.41.0",
+    "@fluidframework/eslint-config-fluid": "^5.7.4",
+    "@fluidframework/test-runtime-utils": "~2.41.0",
+    "@fluidframework/test-utils": "~2.41.0",
     "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.40.0",
     "@microsoft/api-extractor": "7.52.8",
     "@types/diff": "^3.5.1",

package/src/codec/codec.ts

@@ -333,7 +333,31 @@ export function withSchemaValidation<
  * Versions of Fluid Framework client packages.
  * @remarks
  * Used to express compatibility requirements by indicating the oldest version with which compatibility must be maintained.
+ *
+ * When no compatibility-impacting change is made in a given version, the value associated with its enum entry may point to the older version which it's fully compatible with.
+ * Note that this can change if a future version of the framework introduces an option to use something which is only supported at a particular version. In which case, the values of the enum may shift,
+ * but the semantics of keys in this enum will not change.
+ *
+ * Do not depend on the value of this enums's entries: only depend on the keys (enum members) themselves.
+ *
+ * Some release may also be omitted if there is currently no need to express that specific version.
+ * If the need arises, they might be added in the future.
+ *
  * @privateRemarks
+ * Entries in these enums should document the user facing impact of opting into a particular version.
+ * For example, document if there is an encoding efficiency improvement of oping into that version or newer.
+ * 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.
  * If this is violated (for example a subset of incompatible features from 3.x that are not in 3.0 are back ported to 2.x),
@@ -341,20 +365,52 @@ export function 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
  */
 export enum FluidClientVersion {
+	/**
+	 * Fluid Framework Client 1.4 and newer.
+	 * @remarks
+	 * This opts into support for the 1.4 LTS branch.
+	 * @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.004,
+
 	/** Fluid Framework Client 2.0 and newer. */
-	v2_0 = "v2_0",
+	v2_0 = 2.0,
+
 	/** Fluid Framework Client 2.1 and newer. */
-	v2_1 = "v2_1",
-	/** Fluid Framework Client 2.2 and newer. */
-	v2_2 = "v2_2",
-	/** Fluid Framework Client 2.3 and newer. */
-	v2_3 = "v2_3",
+	// 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 "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.041,
+
+	/**
+	 * Enable unreleased and unfinished features.
+	 * @remarks
+	 * Using this value can result in documents which can not be opened in future versions of the framework.
+	 * It can also result in data corruption by enabling unfinished features which may not handle all cases correctly.
+	 *
+	 * This can be used with specific APIs when the caller has knowledge of what specific features those APIs will be opted into with it.
+	 * This is useful for testing features before they are released, but should not be used in production code.
+	 */
+	EnableUnstableFeatures = Number.POSITIVE_INFINITY,
 }
 
 /**
- * The version of this code.
+ * An up to date version which includes all the important stable features.
+ * @remarks
+ * Use for cases when data is not persisted and thus would only ever be read by the current version of the framework.
+ *
+ * @privateRemarks
+ * Update as needed.
+ * TODO: Consider using packageVersion.ts to keep this current.
  */
-export const currentVersion: FluidClientVersion = FluidClientVersion.v2_3;
+export const currentVersion: FluidClientVersion = FluidClientVersion.v2_0;

package/src/core/change-family/editBuilder.ts

@@ -4,6 +4,7 @@
  */
 
 import type { TaggedChange } from "../rebase/index.js";
+
 import type { ChangeFamily, ChangeFamilyEditor } from "./changeFamily.js";
 
 export abstract class EditBuilder<TChange> implements ChangeFamilyEditor {

package/src/core/forest/forest.ts

@@ -3,9 +3,9 @@
  * Licensed under the MIT License.
  */
 
+import type { Listenable } from "@fluidframework/core-interfaces/internal";
 import { assert } from "@fluidframework/core-utils/internal";
 
-import type { Listenable } from "@fluidframework/core-interfaces/internal";
 import type { FieldKey, TreeStoredSchemaSubscription } from "../schema-stored/index.js";
 import {
 	type Anchor,

package/src/core/index.ts

@@ -147,6 +147,7 @@ export {
 	type SchemaAndPolicy,
 	Multiplicity,
 	type SchemaPolicy,
+	SchemaVersion,
 } from "./schema-stored/index.js";
 
 export {

package/src/core/rebase/types.ts

@@ -70,7 +70,7 @@ export type EncodedChangeAtomId = [ChangesetLocalId, EncodedRevisionTag] | Chang
 export type ChangeAtomIdMap<T> = NestedMap<RevisionTag | undefined, ChangesetLocalId, T>;
 
 /**
- * @returns true iff `a` and `b` are the same.
+ * Returns true iff `a` and `b` are the same.
  */
 export function areEqualChangeAtomIds(a: ChangeAtomId, b: ChangeAtomId): boolean {
 	return a.localId === b.localId && a.revision === b.revision;
@@ -88,7 +88,7 @@ export function areEqualChangeAtomIdOpts(
 }
 
 /**
- * @returns a ChangeAtomId with the given revision and local ID.
+ * Returns a ChangeAtomId with the given revision and local ID.
  */
 export function makeChangeAtomId(
 	localId: ChangesetLocalId,

package/src/core/rebase/utils.ts

@@ -372,8 +372,6 @@ export function rebaseChange<TChange>(
 	};
 }
 
-/**
- */
 export function revisionMetadataSourceFromInfo(
 	revInfos: readonly RevisionInfo[],
 ): RevisionMetadataSource {
@@ -440,19 +438,21 @@ function rollbackFromCommit<TChange>(
 	mintRevisionTag: () => RevisionTag,
 	cache?: boolean,
 ): TaggedChange<TChange, RevisionTag> {
-	const rollback = Rollback.get(commit);
-	if (rollback !== undefined) {
-		return rollback;
+	const cachedRollback = Rollback.get(commit);
+	if (cachedRollback !== undefined) {
+		return cachedRollback;
 	}
 	const tag = mintRevisionTag();
-	const untagged = changeRebaser.invert(commit, true, tag);
-	const deeplyTaggedRollback = changeRebaser.changeRevision(untagged, tag, commit.revision);
-	const fullyTaggedRollback = tagRollbackInverse(deeplyTaggedRollback, tag, commit.revision);
+	const rollback = tagRollbackInverse(
+		changeRebaser.invert(commit, true, tag),
+		tag,
+		commit.revision,
+	);
 
 	if (cache === true) {
-		Rollback.set(commit, fullyTaggedRollback);
+		Rollback.set(commit, rollback);
 	}
-	return fullyTaggedRollback;
+	return rollback;
 }
 
 /**

package/src/core/schema-stored/formatV1.ts

@@ -8,8 +8,6 @@ import { type ObjectOptions, type Static, Type } from "@sinclair/typebox";
 import { unionOptions } from "../../codec/index.js";
 import { type Brand, brandedStringType } from "../../util/index.js";
 
-export const version = 1 as const;
-
 /**
  * Key (aka Name or Label) for a field which is scoped to a specific TreeNodeStoredSchema.
  *

package/src/core/schema-stored/index.ts

@@ -22,6 +22,7 @@ export {
 	storedSchemaDecodeDispatcher,
 	type SchemaAndPolicy,
 	type SchemaPolicy,
+	SchemaVersion,
 } from "./schema.js";
 export {
 	type TreeStoredSchemaSubscription,

package/src/core/schema-stored/schema.ts

@@ -4,8 +4,10 @@
  */
 
 import { fail } from "@fluidframework/core-utils/internal";
+
 import { DiscriminatedUnionDispatcher } from "../../codec/index.js";
 import { type MakeNominal, brand, invertMap } from "../../util/index.js";
+
 import {
 	type FieldKey,
 	type FieldKindIdentifier,
@@ -16,6 +18,13 @@ import {
 } from "./formatV1.js";
 import type { Multiplicity } from "./multiplicity.js";
 
+/**
+ * The format version for the schema.
+ */
+export enum SchemaVersion {
+	v1 = 1,
+}
+
 /**
  * Schema for what {@link TreeLeafValue} is allowed on a Leaf node.
  * @privateRemarks

package/src/core/schema-stored/storedSchemaRepository.ts

@@ -3,10 +3,10 @@
  * Licensed under the MIT License.
  */
 
+import { createEmitter } from "@fluid-internal/client-utils";
+import type { Listenable } from "@fluidframework/core-interfaces/internal";
 import { BTree } from "@tylerbu/sorted-btree-es6";
 
-import type { Listenable } from "@fluidframework/core-interfaces/internal";
-import { createEmitter } from "@fluid-internal/client-utils";
 import { compareStrings } from "../../util/index.js";
 
 import type { TreeNodeSchemaIdentifier } from "./formatV1.js";

package/src/core/tree/anchorSet.ts

@@ -5,10 +5,10 @@
 
 /* eslint-disable @typescript-eslint/no-non-null-assertion */
 
+import { createEmitter } from "@fluid-internal/client-utils";
+import type { Listenable } from "@fluidframework/core-interfaces/internal";
 import { assert, fail } from "@fluidframework/core-utils/internal";
 
-import type { Listenable } from "@fluidframework/core-interfaces/internal";
-import { createEmitter } from "@fluid-internal/client-utils";
 import {
 	type Brand,
 	type BrandedKey,
@@ -22,7 +22,9 @@ import {
 } from "../../util/index.js";
 import type { FieldKey } from "../schema-stored/index.js";
 
+import type { ITreeCursorSynchronous } from "./cursor.js";
 import type * as Delta from "./delta.js";
+import { offsetDetachId } from "./deltaUtil.js";
 import {
 	isDetachedUpPathRoot,
 	type INormalizedUpPath,
@@ -33,8 +35,6 @@ import {
 } from "./pathTree.js";
 import { EmptyKey } from "./types.js";
 import type { DeltaVisitor } from "./visitDelta.js";
-import { offsetDetachId } from "./deltaUtil.js";
-import type { ITreeCursorSynchronous } from "./cursor.js";
 
 /**
  * A way to refer to a particular tree location within an {@link AnchorSet}.
@@ -1075,7 +1075,8 @@ class PathNode extends ReferenceCountedBase implements AnchorNode {
 	}
 
 	/**
-	 * @returns true iff this PathNode is the special root node that sits above all the detached fields.
+	 * Whether or not this `PathNode` is the special root node that sits above all the detached fields.
+	 * @remarks
 	 * In this case, the fields are detached sequences.
 	 * Note that the special root node should never appear in an UpPath
 	 * since UpPaths represent this root as `undefined`.

package/src/core/tree/chunk.ts

@@ -7,12 +7,13 @@ import { assert } from "@fluidframework/core-utils/internal";
 
 import type { ReferenceCounted } from "../../util/index.js";
 import type { FieldKey } from "../schema-stored/index.js";
-import { rootFieldKey } from "./types.js";
+
 import {
 	CursorLocationType,
 	type ITreeCursor,
 	type ITreeCursorSynchronous,
 } from "./cursor.js";
+import { rootFieldKey } from "./types.js";
 
 /**
  * Contiguous part of the tree which get stored together in some data format.

package/src/core/tree/delta.ts

@@ -5,6 +5,7 @@
 
 import type { RevisionTag } from "../rebase/index.js";
 import type { FieldKey } from "../schema-stored/index.js";
+
 import type { TreeChunk } from "./chunk.js";
 
 /**

package/src/core/tree/deltaUtil.ts

@@ -5,8 +5,8 @@
 
 import type { Mutable } from "../../util/index.js";
 import type { FieldKey } from "../schema-stored/index.js";
-import type { TreeChunk } from "./chunk.js";
 
+import type { TreeChunk } from "./chunk.js";
 import type { DetachedNodeId, FieldChanges, Root } from "./delta.js";
 import { rootFieldKey } from "./types.js";
 

package/src/core/tree/detachedFieldIndex.ts

@@ -4,6 +4,7 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
+import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 import { type ICodecOptions, type IJsonCodec, noopValidator } from "../../codec/index.js";
 import {
@@ -31,7 +32,6 @@ import type {
 	Major,
 	Minor,
 } from "./detachedFieldIndexTypes.js";
-import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 /**
  * The tree index records detached field IDs and associates them with a change atom ID.

package/src/core/tree/detachedFieldIndexCodec.ts

@@ -4,12 +4,14 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
+import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 import {
 	type ICodecOptions,
 	type IJsonCodec,
 	makeVersionedValidatedCodec,
 } from "../../codec/index.js";
+import { hasSingle } from "../../util/index.js";
 import type { EncodedRevisionTag, RevisionTagCodec, RevisionTag } from "../rebase/index.js";
 
 import {
@@ -23,8 +25,6 @@ import type {
 	DetachedFieldSummaryData,
 	Major,
 } from "./detachedFieldIndexTypes.js";
-import type { IIdCompressor } from "@fluidframework/id-compressor";
-import { hasSingle } from "../../util/index.js";
 
 class MajorCodec implements IJsonCodec<Major> {
 	public constructor(

package/src/core/tree/pathTree.ts

@@ -4,8 +4,8 @@
  */
 
 import type { FieldKey } from "../schema-stored/index.js";
-import type { DetachedNodeId } from "./delta.js";
 
+import type { DetachedNodeId } from "./delta.js";
 import { type DetachedField, keyAsDetachedField } from "./types.js";
 
 /**
@@ -177,7 +177,8 @@ export type NodeIndex = number;
 export type PlaceIndex = number;
 
 /**
- * @returns the number of nodes above this one.
+ * Gets the number of nodes above this one.
+ * @remarks
  * Zero when the path's parent is undefined, meaning the path represents a node in a detached field.
  * Runs in O(depth) time.
  */
@@ -192,14 +193,14 @@ export function getDepth(path: UpPath): number {
 }
 
 /**
- * @returns a deep copy of the provided path as simple javascript objects.
- * This is safe to hold onto and use deep object comparisons on.
+ * Creates deep copy of the provided path as simple JavaScript object.
+ * @remarks This is safe to hold onto and use deep object comparisons on.
  */
 export function clonePath(path: UpPath): UpPath;
 
 /**
- * @returns a deep copy of the provided path as simple javascript objects.
- * This is safe to hold onto and use deep object comparisons on.
+ * Creates a deep copy of the provided path as simple JavaScript object.
+ * @remarks This is safe to hold onto and use deep object comparisons on.
  */
 export function clonePath(path: UpPath | undefined): UpPath | undefined;
 
@@ -215,8 +216,8 @@ export function clonePath(path: UpPath | undefined): UpPath | undefined {
 }
 
 /**
- * @returns The elements of the given `path`, ordered from root-most to child-most.
- * These elements are unchanged and therefore still point "up".
+ * Gets the elements of the given `path`, ordered from root-most to child-most.
+ * @remarks These elements are unchanged and therefore still point "up".
  */
 export function topDownPath(path: UpPath | undefined): UpPath[] {
 	const out: UpPath[] = [];
@@ -230,8 +231,8 @@ export function topDownPath(path: UpPath | undefined): UpPath[] {
 }
 
 /**
- * @returns true iff `a` and `b` describe the same path.
- *
+ * Returns true if and only if `a` and `b` describe the same path.
+ * @remarks
  * Note that for mutable paths (as used in `AnchorSet`), this equality may change over time: this only checks if the two paths are currently the same.
  */
 export function compareUpPaths(a: UpPath | undefined, b: UpPath | undefined): boolean {
@@ -249,8 +250,8 @@ export function compareUpPaths(a: UpPath | undefined, b: UpPath | undefined): bo
 }
 
 /**
- * @returns true iff `a` and `b` describe the same field path.
- *
+ * Returns true if and only if `a` and `b` describe the same field path.
+ * @remarks
  * Note that for mutable paths (as used in `AnchorSet`), this equality may change over time: this only checks if the two paths are currently the same.
  */
 export function compareFieldUpPaths(a: FieldUpPath, b: FieldUpPath): boolean {

package/src/core/tree/treeTextFormat.ts

@@ -4,6 +4,7 @@
  */
 
 import { fail } from "@fluidframework/core-utils/internal";
+
 import type { FieldKey } from "../schema-stored/index.js";
 
 import type { NodeData } from "./types.js";
@@ -139,7 +140,7 @@ export function setGenericTreeField<T>(
 }
 
 /**
- * @returns keys for fields of `tree`.
+ * Returns keys for fields of `tree`.
  */
 export function genericTreeKeys<T>(tree: GenericFieldsNode<T>): readonly FieldKey[] {
 	const fields = tree.fields;

package/src/core/tree/visitDelta.ts

@@ -6,6 +6,7 @@
 import { assert } from "@fluidframework/core-utils/internal";
 
 import { type NestedMap, setInNestedMap, tryGetFromNestedMap } from "../../util/index.js";
+import type { RevisionTag, TreeChunk } from "../index.js";
 import type { FieldKey } from "../schema-stored/index.js";
 
 import { mapCursorField, type ITreeCursorSynchronous } from "./cursor.js";
@@ -14,7 +15,6 @@ import { areDetachedNodeIdsEqual, offsetDetachId } from "./deltaUtil.js";
 import type { DetachedFieldIndex } from "./detachedFieldIndex.js";
 import type { ForestRootId, Major, Minor } from "./detachedFieldIndexTypes.js";
 import type { NodeIndex, PlaceIndex, Range } from "./pathTree.js";
-import type { RevisionTag, TreeChunk } from "../index.js";
 
 /**
  * Implementation notes:

package/src/core/tree/visitorUtils.ts

@@ -3,18 +3,19 @@
  * Licensed under the MIT License.
  */
 
+import type { IIdCompressor } from "@fluidframework/id-compressor";
+
 import type { ICodecOptions } from "../../codec/index.js";
 import { type IdAllocator, idAllocatorFromMaxId } from "../../util/index.js";
 import type { RevisionTag, RevisionTagCodec } from "../rebase/index.js";
 import type { FieldKey } from "../schema-stored/index.js";
 
+import type { ITreeCursorSynchronous } from "./cursor.js";
 import type { DetachedNodeId, Root } from "./delta.js";
 import { DetachedFieldIndex } from "./detachedFieldIndex.js";
 import type { ForestRootId } from "./detachedFieldIndexTypes.js";
 import type { PlaceIndex, Range } from "./pathTree.js";
 import { type DeltaVisitor, visitDelta } from "./visitDelta.js";
-import type { IIdCompressor } from "@fluidframework/id-compressor";
-import type { ITreeCursorSynchronous } from "./cursor.js";
 
 export function makeDetachedFieldIndex(
 	prefix: string = "Temp",

package/src/feature-libraries/chunked-forest/chunkTree.ts

@@ -4,6 +4,7 @@
  */
 
 import { assert, debugAssert, oob, fail } from "@fluidframework/core-utils/internal";
+import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 import {
 	CursorLocationType,
@@ -26,12 +27,11 @@ import {
 } from "../../core/index.js";
 import { getOrCreate } from "../../util/index.js";
 import type { FullSchemaPolicy } from "../modular-schema/index.js";
+import { isStableNodeIdentifier } from "../node-identifier/index.js";
 
 import { BasicChunk } from "./basicChunk.js";
 import { SequenceChunk } from "./sequenceChunk.js";
 import { type FieldShape, TreeShape, UniformChunk } from "./uniformChunk.js";
-import { isStableNodeIdentifier } from "../node-identifier/index.js";
-import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 export interface Disposable {
 	/**