@fluidframework/tree 2.115.0 → 2.116.0

package/lib/treeFactory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"treeFactory.d.ts","sourceRoot":"","sources":["../src/treeFactory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,EACN,KAAK,aAAa,EAClB,KAAK,iBAAiB,EAMtB,KAAK,qBAAqB,EAC1B,MAAM,6CAA6C,CAAC;AAQrD,OAAO,EAEN,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAE9B,MAAM,wBAAwB,CAAC;AAQhC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAGpD;;;;GAIG;AACH,MAAM,WAAW,WAAY,SAAQ,aAAa,EAAE,YAAY;CAAG;AA8DnE;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAAG,gBAAgB,CAAC,KAAK,CACjD,CAAC;AAE1B;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,qBAAqB,CAAC,KAAK,CAA4B,CAAC;AAEtF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,wBAAwB,CACvC,OAAO,EAAE,qBAAqB,GAC5B,gBAAgB,CAAC,KAAK,CAAC,CAEzB;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC7C,OAAO,EAAE,qBAAqB,GAC5B,iBAAiB,CAAC,KAAK,CAAC,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAEpD;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACxC,OAAO,EAAE,iBAAiB,GACxB,gBAAgB,CAAC,KAAK,CAAC,CAEzB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,iBAAiB,GACxB,iBAAiB,CAAC,KAAK,CAAC,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAGzD;AAED,wBAAgB,4BAA4B,CAC3C,OAAO,EAAE,yBAAyB,GAChC,iBAAiB,CAAC,KAAK,CAAC,GAAG,qBAAqB,CAAC,KAAK,CAAC,CASzD;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,iBAAiB,GAAG,yBAAyB,CAQpF"}
+{"version":3,"file":"treeFactory.d.ts","sourceRoot":"","sources":["../src/treeFactory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,EACN,KAAK,aAAa,EAClB,KAAK,iBAAiB,EAMtB,KAAK,qBAAqB,EAC1B,MAAM,6CAA6C,CAAC;AAQrD,OAAO,EAEN,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAE9B,MAAM,wBAAwB,CAAC;AAQhC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAGpD;;;;GAIG;AACH,MAAM,WAAW,WAAY,SAAQ,aAAa,EAAE,YAAY;CAAG;AA6DnE;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAAG,gBAAgB,CAAC,KAAK,CACjD,CAAC;AAE1B;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,qBAAqB,CAAC,KAAK,CAA4B,CAAC;AAEtF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,wBAAwB,CACvC,OAAO,EAAE,qBAAqB,GAC5B,gBAAgB,CAAC,KAAK,CAAC,CAEzB;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC7C,OAAO,EAAE,qBAAqB,GAC5B,iBAAiB,CAAC,KAAK,CAAC,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAEpD;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACxC,OAAO,EAAE,iBAAiB,GACxB,gBAAgB,CAAC,KAAK,CAAC,CAEzB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,iBAAiB,GACxB,iBAAiB,CAAC,KAAK,CAAC,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAGzD;AAED,wBAAgB,4BAA4B,CAC3C,OAAO,EAAE,yBAAyB,GAChC,iBAAiB,CAAC,KAAK,CAAC,GAAG,qBAAqB,CAAC,KAAK,CAAC,CASzD;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,iBAAiB,GAAG,yBAAyB,CAQpF"}

package/lib/treeFactory.js

@@ -34,7 +34,7 @@ function treeKernelFactory(options) {
             // C. If neither specifies it, we fall back to a default value default of 2.0 since that is the oldest version that supports SharedTree.
             minVersionForCollab: minVersionForCollab ?? args.minVersionForCollab ?? FluidClientVersion.v2_0,
         };
-        return new SharedTreeKernel(new Breakable("SharedTree", args.logger), args.sharedObject, args.serializer, args.submitLocalMessage, args.lastSequenceNumber, args.initialSequenceNumber, args.logger, args.idCompressor, adjustedOptions);
+        return new SharedTreeKernel(new Breakable("SharedTree", args.logger), args.sharedObject, args.serializer, args.submitLocalMessage, args.lastSequenceNumber, args.initialSequenceNumber, args.idCompressor, adjustedOptions);
     }
     return {
         create: (args) => {

package/lib/treeFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"treeFactory.js","sourceRoot":"","sources":["../src/treeFactory.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 type { IChannelStorageService } from \"@fluidframework/datastore-definitions/internal\";\nimport type { SharedObjectKind } from \"@fluidframework/shared-object-base\";\nimport {\n\ttype ISharedObject,\n\ttype ISharedObjectKind,\n\tmakeSharedObjectKind,\n\ttype KernelArgs,\n\ttype SharedKernelFactory,\n\ttype SharedObjectOptions,\n\ttype FactoryOut,\n\ttype SharedObjectKindAlpha,\n} from \"@fluidframework/shared-object-base/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\n\nimport { FluidClientVersion, type FormatVersion } from \"./codec/index.js\";\nimport {\n\tdetachedFieldIndexCodecBuilder,\n\tDetachedFieldIndexFormatVersion,\n} from \"./core/index.js\";\nimport {\n\tSharedTreeKernel,\n\ttype ITreePrivate,\n\ttype SharedTreeOptions,\n\ttype SharedTreeOptionsBeta,\n\ttype SharedTreeOptionsInternal,\n\ttype SharedTreeKernelView,\n} from \"./shared-tree/index.js\";\nimport {\n\teditManagerCodecName,\n\tEditManagerFormatVersion,\n\tmessageCodecName,\n\tMessageFormatVersion,\n} from \"./shared-tree-core/index.js\";\nimport { SharedTreeFactoryType, SharedTreeAttributes } from \"./sharedTreeAttributes.js\";\nimport type { ITree } from \"./simple-tree/index.js\";\nimport { Breakable, copyProperty } from \"./util/index.js\";\n\n/**\n * {@link ITreePrivate} extended with ISharedObject.\n * @remarks\n * This is used when integration testing this package with the Fluid runtime as it exposes the APIs the runtime consumes to manipulate the tree.\n */\nexport interface ISharedTree extends ISharedObject, ITreePrivate {}\n\n/**\n * Creates a factory for shared tree kernels with the given options.\n * @remarks\n * Exposes {@link ITreePrivate} to allow access to internals in tests without a cast.\n * Code exposing this beyond this package will need to update to a more public type.\n */\nfunction treeKernelFactory(\n\toptions: SharedTreeOptionsInternal,\n): SharedKernelFactory<SharedTreeKernelView> {\n\tfunction treeFromKernelArgs(args: KernelArgs): SharedTreeKernel {\n\t\tif (args.idCompressor === undefined) {\n\t\t\tthrow new UsageError(\"IdCompressor must be enabled to use SharedTree\");\n\t\t}\n\n\t\tconst { minVersionForCollab, ...otherOptions } = options;\n\n\t\tconst adjustedOptions = {\n\t\t\t...otherOptions,\n\t\t\t// Cases:\n\t\t\t// A. If options specifies minVersionForCollab, it takes precedence over args.minVersionForCollab.\n\t\t\t// This value is set when:\n\t\t\t// - A customer using the declarative SharedTree API specifies the setting at the Shared Tree level.\n\t\t\t//   There is currently no way to set it via the declarative API, but it could be added in the future.\n\t\t\t// - treeKernelFactory is invoked in a fuzz test with a specific minVersionForCollab\n\t\t\t// B. Otherwise, we use args.minVersionForCollab, which is propagated from the ContainerRuntime.\n\t\t\t// C. If neither specifies it, we fall back to a default value default of 2.0 since that is the oldest version that supports SharedTree.\n\t\t\tminVersionForCollab:\n\t\t\t\tminVersionForCollab ?? args.minVersionForCollab ?? FluidClientVersion.v2_0,\n\t\t};\n\n\t\treturn new SharedTreeKernel(\n\t\t\tnew Breakable(\"SharedTree\", args.logger),\n\t\t\targs.sharedObject,\n\t\t\targs.serializer,\n\t\t\targs.submitLocalMessage,\n\t\t\targs.lastSequenceNumber,\n\t\t\targs.initialSequenceNumber,\n\t\t\targs.logger,\n\t\t\targs.idCompressor,\n\t\t\tadjustedOptions,\n\t\t);\n\t}\n\n\treturn {\n\t\tcreate: (args: KernelArgs): FactoryOut<SharedTreeKernelView> => {\n\t\t\tconst k = treeFromKernelArgs(args);\n\t\t\treturn { kernel: k, view: k.view };\n\t\t},\n\n\t\tasync loadCore(\n\t\t\targs: KernelArgs,\n\t\t\tstorage: IChannelStorageService,\n\t\t): Promise<FactoryOut<SharedTreeKernelView>> {\n\t\t\tconst k = treeFromKernelArgs(args);\n\t\t\tawait k.loadCore(storage);\n\t\t\treturn { kernel: k, view: k.view };\n\t\t},\n\t};\n}\n\n/**\n * SharedTree is a hierarchical data structure for collaboratively editing strongly typed JSON-like trees\n * of objects, arrays, and other data types.\n * @legacy @beta\n */\nexport const SharedTree: ISharedObjectKind<ITree> & SharedObjectKind<ITree> =\n\tconfiguredSharedTree({});\n\n/**\n * {@link SharedTree} but without legacy types, and with alpha types.\n * @alpha\n */\nexport const SharedTreeAlpha: SharedObjectKindAlpha<ITree> = configuredSharedTree({});\n\n/**\n * {@link SharedTree} but allowing a non-default configuration.\n * @remarks\n * This is useful for debugging and testing.\n * For example it can be used to opt into extra validation or see if opting out of some optimizations fixes an issue.\n *\n * With great care, and knowledge of the support and stability of the options exposed here,\n * this can also be used to opt into some features early or for performance tuning.\n *\n * @example\n * ```typescript\n * import {\n * \tconfiguredSharedTreeBeta,\n * \tForestTypeReference,\n * } from \"fluid-framework/beta\";\n * const SharedTree = configuredSharedTree({\n * \tforest: ForestTypeReference,\n * });\n * ```\n * @privateRemarks\n * The Legacy `ISharedObjectKind<ITree>` type is omitted here for simplicity.\n * @beta\n */\nexport function configuredSharedTreeBeta(\n\toptions: SharedTreeOptionsBeta,\n): SharedObjectKind<ITree> {\n\treturn configuredSharedTree(options);\n}\n\n/**\n * {@link configuredSharedTreeBeta} including the legacy `ISharedObjectKind` type.\n * @privateRemarks\n * This is given a different export name (with legacy appended) to avoid the need to do the special reexport with different types from the fluid-framework package.\n * @legacy @beta\n */\nexport function configuredSharedTreeBetaLegacy(\n\toptions: SharedTreeOptionsBeta,\n): ISharedObjectKind<ITree> & SharedObjectKind<ITree> {\n\treturn configuredSharedTree(options);\n}\n\n/**\n * {@link configuredSharedTreeBeta} but including the alpha {@link SharedTreeOptions}.\n * @alpha\n */\nexport function configuredSharedTreeAlpha(\n\toptions: SharedTreeOptions,\n): SharedObjectKind<ITree> {\n\treturn configuredSharedTree(options);\n}\n\n/**\n * {@link configuredSharedTreeBetaLegacy} but including `@alpha` options.\n *\n * @example\n * ```typescript\n * import {\n * \tTreeCompressionStrategy,\n * \tconfiguredSharedTree,\n * \tFormatValidatorBasic,\n * \tForestTypeReference,\n * } from \"@fluidframework/tree/internal\";\n * const SharedTree = configuredSharedTree({\n * \tforest: ForestTypeReference,\n * \tjsonValidator: FormatValidatorBasic,\n * \ttreeEncodeType: TreeCompressionStrategy.Uncompressed,\n * });\n * ```\n * @privateRemarks\n * This should be legacy, but has to be internal due to no alpha+legacy being setup yet.\n *\n * This should be renamed to `configuredSharedTreeAlpha` to avoid colliding with the eventual public version which will have less options.\n * @internal\n */\nexport function configuredSharedTree(\n\toptions: SharedTreeOptions,\n): ISharedObjectKind<ITree> & SharedObjectKindAlpha<ITree> {\n\tconst internalOptions = resolveOptions(options);\n\treturn configuredSharedTreeInternal(internalOptions);\n}\n\nexport function configuredSharedTreeInternal(\n\toptions: SharedTreeOptionsInternal,\n): ISharedObjectKind<ITree> & SharedObjectKindAlpha<ITree> {\n\tconst sharedObjectOptions: SharedObjectOptions<ITree> = {\n\t\ttype: SharedTreeFactoryType,\n\t\tattributes: SharedTreeAttributes,\n\t\ttelemetryContextPrefix: \"fluid_sharedTree_\",\n\t\tfactory: treeKernelFactory(options),\n\t};\n\n\treturn makeSharedObjectKind<ITree>(sharedObjectOptions);\n}\n\nexport function resolveOptions(options: SharedTreeOptions): SharedTreeOptionsInternal {\n\tconst internal: SharedTreeOptionsInternal = {\n\t\t...resolveFormatOptions(options),\n\t};\n\tfor (const optionName of Object.keys(options)) {\n\t\tcopyProperty(options, optionName, internal);\n\t}\n\treturn internal;\n}\n\nfunction resolveFormatOptions(options: SharedTreeOptions): SharedTreeOptionsInternal {\n\tconst enableSharedBranches = options.enableSharedBranches ?? false;\n\n\tif (enableSharedBranches) {\n\t\treturn sharedBranchesOptions;\n\t}\n\n\treturn {};\n}\n\nconst sharedBranchesOptions: SharedTreeOptionsInternal = {\n\twriteVersionOverrides: new Map<string, FormatVersion>([\n\t\t[editManagerCodecName, EditManagerFormatVersion.vSharedBranches],\n\t\t[messageCodecName, MessageFormatVersion.vSharedBranches],\n\t\t[detachedFieldIndexCodecBuilder.name, DetachedFieldIndexFormatVersion.v2],\n\t]),\n\tallowPossiblyIncompatibleWriteVersionOverrides: true,\n};\n"]}
+{"version":3,"file":"treeFactory.js","sourceRoot":"","sources":["../src/treeFactory.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 type { IChannelStorageService } from \"@fluidframework/datastore-definitions/internal\";\nimport type { SharedObjectKind } from \"@fluidframework/shared-object-base\";\nimport {\n\ttype ISharedObject,\n\ttype ISharedObjectKind,\n\tmakeSharedObjectKind,\n\ttype KernelArgs,\n\ttype SharedKernelFactory,\n\ttype SharedObjectOptions,\n\ttype FactoryOut,\n\ttype SharedObjectKindAlpha,\n} from \"@fluidframework/shared-object-base/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\n\nimport { FluidClientVersion, type FormatVersion } from \"./codec/index.js\";\nimport {\n\tdetachedFieldIndexCodecBuilder,\n\tDetachedFieldIndexFormatVersion,\n} from \"./core/index.js\";\nimport {\n\tSharedTreeKernel,\n\ttype ITreePrivate,\n\ttype SharedTreeOptions,\n\ttype SharedTreeOptionsBeta,\n\ttype SharedTreeOptionsInternal,\n\ttype SharedTreeKernelView,\n} from \"./shared-tree/index.js\";\nimport {\n\teditManagerCodecName,\n\tEditManagerFormatVersion,\n\tmessageCodecName,\n\tMessageFormatVersion,\n} from \"./shared-tree-core/index.js\";\nimport { SharedTreeFactoryType, SharedTreeAttributes } from \"./sharedTreeAttributes.js\";\nimport type { ITree } from \"./simple-tree/index.js\";\nimport { Breakable, copyProperty } from \"./util/index.js\";\n\n/**\n * {@link ITreePrivate} extended with ISharedObject.\n * @remarks\n * This is used when integration testing this package with the Fluid runtime as it exposes the APIs the runtime consumes to manipulate the tree.\n */\nexport interface ISharedTree extends ISharedObject, ITreePrivate {}\n\n/**\n * Creates a factory for shared tree kernels with the given options.\n * @remarks\n * Exposes {@link ITreePrivate} to allow access to internals in tests without a cast.\n * Code exposing this beyond this package will need to update to a more public type.\n */\nfunction treeKernelFactory(\n\toptions: SharedTreeOptionsInternal,\n): SharedKernelFactory<SharedTreeKernelView> {\n\tfunction treeFromKernelArgs(args: KernelArgs): SharedTreeKernel {\n\t\tif (args.idCompressor === undefined) {\n\t\t\tthrow new UsageError(\"IdCompressor must be enabled to use SharedTree\");\n\t\t}\n\n\t\tconst { minVersionForCollab, ...otherOptions } = options;\n\n\t\tconst adjustedOptions = {\n\t\t\t...otherOptions,\n\t\t\t// Cases:\n\t\t\t// A. If options specifies minVersionForCollab, it takes precedence over args.minVersionForCollab.\n\t\t\t// This value is set when:\n\t\t\t// - A customer using the declarative SharedTree API specifies the setting at the Shared Tree level.\n\t\t\t//   There is currently no way to set it via the declarative API, but it could be added in the future.\n\t\t\t// - treeKernelFactory is invoked in a fuzz test with a specific minVersionForCollab\n\t\t\t// B. Otherwise, we use args.minVersionForCollab, which is propagated from the ContainerRuntime.\n\t\t\t// C. If neither specifies it, we fall back to a default value default of 2.0 since that is the oldest version that supports SharedTree.\n\t\t\tminVersionForCollab:\n\t\t\t\tminVersionForCollab ?? args.minVersionForCollab ?? FluidClientVersion.v2_0,\n\t\t};\n\n\t\treturn new SharedTreeKernel(\n\t\t\tnew Breakable(\"SharedTree\", args.logger),\n\t\t\targs.sharedObject,\n\t\t\targs.serializer,\n\t\t\targs.submitLocalMessage,\n\t\t\targs.lastSequenceNumber,\n\t\t\targs.initialSequenceNumber,\n\t\t\targs.idCompressor,\n\t\t\tadjustedOptions,\n\t\t);\n\t}\n\n\treturn {\n\t\tcreate: (args: KernelArgs): FactoryOut<SharedTreeKernelView> => {\n\t\t\tconst k = treeFromKernelArgs(args);\n\t\t\treturn { kernel: k, view: k.view };\n\t\t},\n\n\t\tasync loadCore(\n\t\t\targs: KernelArgs,\n\t\t\tstorage: IChannelStorageService,\n\t\t): Promise<FactoryOut<SharedTreeKernelView>> {\n\t\t\tconst k = treeFromKernelArgs(args);\n\t\t\tawait k.loadCore(storage);\n\t\t\treturn { kernel: k, view: k.view };\n\t\t},\n\t};\n}\n\n/**\n * SharedTree is a hierarchical data structure for collaboratively editing strongly typed JSON-like trees\n * of objects, arrays, and other data types.\n * @legacy @beta\n */\nexport const SharedTree: ISharedObjectKind<ITree> & SharedObjectKind<ITree> =\n\tconfiguredSharedTree({});\n\n/**\n * {@link SharedTree} but without legacy types, and with alpha types.\n * @alpha\n */\nexport const SharedTreeAlpha: SharedObjectKindAlpha<ITree> = configuredSharedTree({});\n\n/**\n * {@link SharedTree} but allowing a non-default configuration.\n * @remarks\n * This is useful for debugging and testing.\n * For example it can be used to opt into extra validation or see if opting out of some optimizations fixes an issue.\n *\n * With great care, and knowledge of the support and stability of the options exposed here,\n * this can also be used to opt into some features early or for performance tuning.\n *\n * @example\n * ```typescript\n * import {\n * \tconfiguredSharedTreeBeta,\n * \tForestTypeReference,\n * } from \"fluid-framework/beta\";\n * const SharedTree = configuredSharedTree({\n * \tforest: ForestTypeReference,\n * });\n * ```\n * @privateRemarks\n * The Legacy `ISharedObjectKind<ITree>` type is omitted here for simplicity.\n * @beta\n */\nexport function configuredSharedTreeBeta(\n\toptions: SharedTreeOptionsBeta,\n): SharedObjectKind<ITree> {\n\treturn configuredSharedTree(options);\n}\n\n/**\n * {@link configuredSharedTreeBeta} including the legacy `ISharedObjectKind` type.\n * @privateRemarks\n * This is given a different export name (with legacy appended) to avoid the need to do the special reexport with different types from the fluid-framework package.\n * @legacy @beta\n */\nexport function configuredSharedTreeBetaLegacy(\n\toptions: SharedTreeOptionsBeta,\n): ISharedObjectKind<ITree> & SharedObjectKind<ITree> {\n\treturn configuredSharedTree(options);\n}\n\n/**\n * {@link configuredSharedTreeBeta} but including the alpha {@link SharedTreeOptions}.\n * @alpha\n */\nexport function configuredSharedTreeAlpha(\n\toptions: SharedTreeOptions,\n): SharedObjectKind<ITree> {\n\treturn configuredSharedTree(options);\n}\n\n/**\n * {@link configuredSharedTreeBetaLegacy} but including `@alpha` options.\n *\n * @example\n * ```typescript\n * import {\n * \tTreeCompressionStrategy,\n * \tconfiguredSharedTree,\n * \tFormatValidatorBasic,\n * \tForestTypeReference,\n * } from \"@fluidframework/tree/internal\";\n * const SharedTree = configuredSharedTree({\n * \tforest: ForestTypeReference,\n * \tjsonValidator: FormatValidatorBasic,\n * \ttreeEncodeType: TreeCompressionStrategy.Uncompressed,\n * });\n * ```\n * @privateRemarks\n * This should be legacy, but has to be internal due to no alpha+legacy being setup yet.\n *\n * This should be renamed to `configuredSharedTreeAlpha` to avoid colliding with the eventual public version which will have less options.\n * @internal\n */\nexport function configuredSharedTree(\n\toptions: SharedTreeOptions,\n): ISharedObjectKind<ITree> & SharedObjectKindAlpha<ITree> {\n\tconst internalOptions = resolveOptions(options);\n\treturn configuredSharedTreeInternal(internalOptions);\n}\n\nexport function configuredSharedTreeInternal(\n\toptions: SharedTreeOptionsInternal,\n): ISharedObjectKind<ITree> & SharedObjectKindAlpha<ITree> {\n\tconst sharedObjectOptions: SharedObjectOptions<ITree> = {\n\t\ttype: SharedTreeFactoryType,\n\t\tattributes: SharedTreeAttributes,\n\t\ttelemetryContextPrefix: \"fluid_sharedTree_\",\n\t\tfactory: treeKernelFactory(options),\n\t};\n\n\treturn makeSharedObjectKind<ITree>(sharedObjectOptions);\n}\n\nexport function resolveOptions(options: SharedTreeOptions): SharedTreeOptionsInternal {\n\tconst internal: SharedTreeOptionsInternal = {\n\t\t...resolveFormatOptions(options),\n\t};\n\tfor (const optionName of Object.keys(options)) {\n\t\tcopyProperty(options, optionName, internal);\n\t}\n\treturn internal;\n}\n\nfunction resolveFormatOptions(options: SharedTreeOptions): SharedTreeOptionsInternal {\n\tconst enableSharedBranches = options.enableSharedBranches ?? false;\n\n\tif (enableSharedBranches) {\n\t\treturn sharedBranchesOptions;\n\t}\n\n\treturn {};\n}\n\nconst sharedBranchesOptions: SharedTreeOptionsInternal = {\n\twriteVersionOverrides: new Map<string, FormatVersion>([\n\t\t[editManagerCodecName, EditManagerFormatVersion.vSharedBranches],\n\t\t[messageCodecName, MessageFormatVersion.vSharedBranches],\n\t\t[detachedFieldIndexCodecBuilder.name, DetachedFieldIndexFormatVersion.v2],\n\t]),\n\tallowPossiblyIncompatibleWriteVersionOverrides: true,\n};\n"]}

package/lib/util/breakable.d.ts

@@ -7,6 +7,10 @@ import { type TelemetryLoggerExt } from "@fluidframework/telemetry-utils/interna
  * An object which can enter a "broken" state where trying to use it is a UsageError.
  * @remarks
  * Use {@link WithBreakable} to apply this to another object.
+ *
+ * A common pattern is to pass a single breaker to all code which shares mutable state and thus could be put into an invalidate state together.
+ * Thus a breaker often represents a scope for or dependency on mutable state which also forms a scope for fault isolation.
+ * As such a scope can have issues (if it couldn't it would need a breaker), an optional {@link Breakable.logger} is included which can be used to log telemetry within this scope.
  * @sealed
  */
 export declare class Breakable {
@@ -20,7 +24,11 @@ export declare class Breakable {
      * Optional logger for telemetry.
      * @remarks
      * When provided, subsystems that have access to a Breakable can use this logger to emit telemetry
-     * without requiring additional plumbing.
+     * without requiring additional plumbing of a logger which also corresponds to the same scope/context of this Breakable.
+     *
+     * Currently, Breakable itself does not eagerly log breakages into the logger, but we may want to change that in the future.
+     * Instead it is assumed that fatal errors will result in exceptions logged through other means,
+     * and the logger here is exposed for users of breaker to log telemetry as desired (for example reporting non-fatal errors or other telemetry).
      */
     readonly logger?: TelemetryLoggerExt | undefined;
     private brokenBy?;
@@ -35,7 +43,11 @@ export declare class Breakable {
      * Optional logger for telemetry.
      * @remarks
      * When provided, subsystems that have access to a Breakable can use this logger to emit telemetry
-     * without requiring additional plumbing.
+     * without requiring additional plumbing of a logger which also corresponds to the same scope/context of this Breakable.
+     *
+     * Currently, Breakable itself does not eagerly log breakages into the logger, but we may want to change that in the future.
+     * Instead it is assumed that fatal errors will result in exceptions logged through other means,
+     * and the logger here is exposed for users of breaker to log telemetry as desired (for example reporting non-fatal errors or other telemetry).
      */
     logger?: TelemetryLoggerExt | undefined);
     /**

package/lib/util/breakable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"breakable.d.ts","sourceRoot":"","sources":["../../src/util/breakable.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAc,KAAK,kBAAkB,EAAE,MAAM,0CAA0C,CAAC;AAE/F;;;;;GAKG;AACH,qBAAa,SAAS;IAIpB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB;;;;;OAKG;aACa,MAAM,CAAC;IAfxB,OAAO,CAAC,QAAQ,CAAC,CAAQ;;IAGxB;;;;OAIG;IACc,IAAI,EAAE,MAAM;IAC7B;;;;;OAKG;IACa,MAAM,CAAC,gCAAoB;IAG5C;;;;OAIG;IACI,GAAG,CACT,OAAO,GAAE,CAAC,QAAQ,EAAE,KAAK,KAAK,MACuF,GACnH,IAAI;IAcP;;;;OAIG;IACI,KAAK,CAAC,QAAQ,EAAE,KAAK,GAAG,KAAK;IAUpC;;;;OAIG;IACH,OAAO,CAAC,aAAa;IASrB;;;;;;;;;;;;OAYG;IACI,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,GAAG,OAAO;IAuBpD;;;;;OAKG;IACI,UAAU,IAAI,IAAI;CAIzB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;CAC5B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC7B,MAAM,SAAS,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC,EACtF,IAAI,SAAS,aAAa,EAC1B,IAAI,SAAS,KAAK,EAAE,EACpB,MAAM,EACL,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,2BAA2B,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,MAAM,CAe7E;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC5B,MAAM,SAAS,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC,EACtF,IAAI,SAAS,aAAa,EAC1B,IAAI,SAAS,KAAK,EAAE,EACpB,MAAM,EACL,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,2BAA2B,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,MAAM,CAQ5E;AAyBD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,SAAS,QAAQ,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,aAAa,EAC1F,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,qBAAqB,CAAC,MAAM,CAAC,GACpC,MAAM,CAiCR"}
+{"version":3,"file":"breakable.d.ts","sourceRoot":"","sources":["../../src/util/breakable.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAc,KAAK,kBAAkB,EAAE,MAAM,0CAA0C,CAAC;AAE/F;;;;;;;;;GASG;AACH,qBAAa,SAAS;IAIpB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB;;;;;;;;;OASG;aACa,MAAM,CAAC;IAnBxB,OAAO,CAAC,QAAQ,CAAC,CAAQ;;IAGxB;;;;OAIG;IACc,IAAI,EAAE,MAAM;IAC7B;;;;;;;;;OASG;IACa,MAAM,CAAC,gCAAoB;IAG5C;;;;OAIG;IACI,GAAG,CACT,OAAO,GAAE,CAAC,QAAQ,EAAE,KAAK,KAAK,MACuF,GACnH,IAAI;IAcP;;;;OAIG;IACI,KAAK,CAAC,QAAQ,EAAE,KAAK,GAAG,KAAK;IAUpC;;;;OAIG;IACH,OAAO,CAAC,aAAa;IASrB;;;;;;;;;;;;OAYG;IACI,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,GAAG,OAAO;IAuBpD;;;;;OAKG;IACI,UAAU,IAAI,IAAI;CAIzB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;CAC5B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC7B,MAAM,SAAS,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC,EACtF,IAAI,SAAS,aAAa,EAC1B,IAAI,SAAS,KAAK,EAAE,EACpB,MAAM,EACL,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,2BAA2B,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,MAAM,CAe7E;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC5B,MAAM,SAAS,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC,EACtF,IAAI,SAAS,aAAa,EAC1B,IAAI,SAAS,KAAK,EAAE,EACpB,MAAM,EACL,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,2BAA2B,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,MAAM,CAQ5E;AAyBD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,SAAS,QAAQ,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,aAAa,EAC1F,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,qBAAqB,CAAC,MAAM,CAAC,GACpC,MAAM,CAiCR"}

package/lib/util/breakable.js

@@ -8,6 +8,10 @@ import { UsageError } from "@fluidframework/telemetry-utils/internal";
  * An object which can enter a "broken" state where trying to use it is a UsageError.
  * @remarks
  * Use {@link WithBreakable} to apply this to another object.
+ *
+ * A common pattern is to pass a single breaker to all code which shares mutable state and thus could be put into an invalidate state together.
+ * Thus a breaker often represents a scope for or dependency on mutable state which also forms a scope for fault isolation.
+ * As such a scope can have issues (if it couldn't it would need a breaker), an optional {@link Breakable.logger} is included which can be used to log telemetry within this scope.
  * @sealed
  */
 export class Breakable {
@@ -22,7 +26,11 @@ export class Breakable {
      * Optional logger for telemetry.
      * @remarks
      * When provided, subsystems that have access to a Breakable can use this logger to emit telemetry
-     * without requiring additional plumbing.
+     * without requiring additional plumbing of a logger which also corresponds to the same scope/context of this Breakable.
+     *
+     * Currently, Breakable itself does not eagerly log breakages into the logger, but we may want to change that in the future.
+     * Instead it is assumed that fatal errors will result in exceptions logged through other means,
+     * and the logger here is exposed for users of breaker to log telemetry as desired (for example reporting non-fatal errors or other telemetry).
      */
     logger) {
         this.name = name;

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, type TelemetryLoggerExt } 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\t/**\n\t\t * Optional logger for telemetry.\n\t\t * @remarks\n\t\t * When provided, subsystems that have access to a Breakable can use this logger to emit telemetry\n\t\t * without requiring additional plumbing.\n\t\t */\n\t\tpublic readonly logger?: TelemetryLoggerExt,\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(\n\t\tmessage: (brokenBy: Error) => string = (brokenBy) =>\n\t\t\t`Invalid use of ${this.name} after it was put into an invalid state by another error.\\nOriginal Error:\\n${brokenBy}`,\n\t): void {\n\t\tif (this.brokenBy !== undefined) {\n\t\t\tconst error = new UsageError(message(this.brokenBy));\n\n\t\t\t// This \"cause\" field is added in ES2022, but using it even without that built in support, it is still helpful.\n\t\t\t// See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause\n\t\t\t// TODO: remove this cast when targeting ES2022 lib or later.\n\t\t\t(error as { cause?: unknown }).cause =\n\t\t\t\t(this.brokenBy as { cause?: unknown }).cause ?? this.brokenBy;\n\n\t\t\tthrow error;\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\t * If `breaker` returns a Promise, the breakable is also broken if that Promise rejects, and the broken state is rechecked when it resolves:\n\t * if the breakable was put into a broken state during the async operation (by some other code path), the resolved value is discarded and the returned Promise rejects with a {@link UsageError}.\n\t *\n\t * This does not serialize concurrent runs: a synchronous run invoked while an async run is in flight will execute immediately, and is only blocked if the breakable is already broken.\n\t * Detection of an async result uses `instanceof Promise`, so custom Promise-like objects and Promises from other realms will be treated as synchronous results.\n\t */\n\tpublic run<TResult>(breaker: () => TResult): TResult {\n\t\tthis.use();\n\t\ttry {\n\t\t\tconst result = breaker();\n\t\t\tif (result instanceof Promise) {\n\t\t\t\treturn result.then(\n\t\t\t\t\t(value: Awaited<TResult>) => {\n\t\t\t\t\t\t// If broken while process was running: this will throw instead of returning the value.\n\t\t\t\t\t\tthis.use(\n\t\t\t\t\t\t\t(brokenBy) =>\n\t\t\t\t\t\t\t\t`${this.name} was put into a broken state during an async operation.\\nOriginal Error:\\n${brokenBy}`,\n\t\t\t\t\t\t);\n\t\t\t\t\t\treturn value;\n\t\t\t\t\t},\n\t\t\t\t\t(error: unknown) => this.rethrowCaught(error),\n\t\t\t\t) as TResult;\n\t\t\t}\n\t\t\treturn result;\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/no-unsafe-function-type\ntype PossiblyNamedFunction = Function & { displayName?: undefined | string };\n\n// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type\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/no-unsafe-function-type\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/no-unsafe-function-type\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 as object;\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\t// Method\n\t\t\t\tif (\n\t\t\t\t\tdescriptor !== undefined &&\n\t\t\t\t\ttypeof descriptor.value === \"function\" &&\n\t\t\t\t\t!isBreaker(descriptor.value)\n\t\t\t\t) {\n\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\tconst method = descriptor.value as (...args: unknown[]) => unknown;\n\t\t\t\t\tdescriptor.value = breakingMethod(method);\n\t\t\t\t\tObject.defineProperty(DecoratedBreakable.prototype, key, descriptor);\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, type TelemetryLoggerExt } 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 *\n * A common pattern is to pass a single breaker to all code which shares mutable state and thus could be put into an invalidate state together.\n * Thus a breaker often represents a scope for or dependency on mutable state which also forms a scope for fault isolation.\n * As such a scope can have issues (if it couldn't it would need a breaker), an optional {@link Breakable.logger} is included which can be used to log telemetry within this scope.\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\t/**\n\t\t * Optional logger for telemetry.\n\t\t * @remarks\n\t\t * When provided, subsystems that have access to a Breakable can use this logger to emit telemetry\n\t\t * without requiring additional plumbing of a logger which also corresponds to the same scope/context of this Breakable.\n\t\t *\n\t\t * Currently, Breakable itself does not eagerly log breakages into the logger, but we may want to change that in the future.\n\t\t * Instead it is assumed that fatal errors will result in exceptions logged through other means,\n\t\t * and the logger here is exposed for users of breaker to log telemetry as desired (for example reporting non-fatal errors or other telemetry).\n\t\t */\n\t\tpublic readonly logger?: TelemetryLoggerExt,\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(\n\t\tmessage: (brokenBy: Error) => string = (brokenBy) =>\n\t\t\t`Invalid use of ${this.name} after it was put into an invalid state by another error.\\nOriginal Error:\\n${brokenBy}`,\n\t): void {\n\t\tif (this.brokenBy !== undefined) {\n\t\t\tconst error = new UsageError(message(this.brokenBy));\n\n\t\t\t// This \"cause\" field is added in ES2022, but using it even without that built in support, it is still helpful.\n\t\t\t// See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause\n\t\t\t// TODO: remove this cast when targeting ES2022 lib or later.\n\t\t\t(error as { cause?: unknown }).cause =\n\t\t\t\t(this.brokenBy as { cause?: unknown }).cause ?? this.brokenBy;\n\n\t\t\tthrow error;\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\t * If `breaker` returns a Promise, the breakable is also broken if that Promise rejects, and the broken state is rechecked when it resolves:\n\t * if the breakable was put into a broken state during the async operation (by some other code path), the resolved value is discarded and the returned Promise rejects with a {@link UsageError}.\n\t *\n\t * This does not serialize concurrent runs: a synchronous run invoked while an async run is in flight will execute immediately, and is only blocked if the breakable is already broken.\n\t * Detection of an async result uses `instanceof Promise`, so custom Promise-like objects and Promises from other realms will be treated as synchronous results.\n\t */\n\tpublic run<TResult>(breaker: () => TResult): TResult {\n\t\tthis.use();\n\t\ttry {\n\t\t\tconst result = breaker();\n\t\t\tif (result instanceof Promise) {\n\t\t\t\treturn result.then(\n\t\t\t\t\t(value: Awaited<TResult>) => {\n\t\t\t\t\t\t// If broken while process was running: this will throw instead of returning the value.\n\t\t\t\t\t\tthis.use(\n\t\t\t\t\t\t\t(brokenBy) =>\n\t\t\t\t\t\t\t\t`${this.name} was put into a broken state during an async operation.\\nOriginal Error:\\n${brokenBy}`,\n\t\t\t\t\t\t);\n\t\t\t\t\t\treturn value;\n\t\t\t\t\t},\n\t\t\t\t\t(error: unknown) => this.rethrowCaught(error),\n\t\t\t\t) as TResult;\n\t\t\t}\n\t\t\treturn result;\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/no-unsafe-function-type\ntype PossiblyNamedFunction = Function & { displayName?: undefined | string };\n\n// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type\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/no-unsafe-function-type\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/no-unsafe-function-type\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 as object;\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\t// Method\n\t\t\t\tif (\n\t\t\t\t\tdescriptor !== undefined &&\n\t\t\t\t\ttypeof descriptor.value === \"function\" &&\n\t\t\t\t\t!isBreaker(descriptor.value)\n\t\t\t\t) {\n\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\tconst method = descriptor.value as (...args: unknown[]) => unknown;\n\t\t\t\t\tdescriptor.value = breakingMethod(method);\n\t\t\t\t\tObject.defineProperty(DecoratedBreakable.prototype, key, descriptor);\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/lib/util/compressedIds.d.ts

@@ -2,8 +2,8 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { type ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
 import type { IIdCompressor, OpSpaceCompressedId, SessionId, SessionSpaceCompressedId } from "@fluidframework/id-compressor";
+import type { TelemetryLoggerExt } from "@fluidframework/telemetry-utils/internal";
 /**
  * An encoded identifier that can be decoded without an originator session id.
  * A finalized compressed id — the same numeric value in op-space and session-space.
@@ -101,7 +101,7 @@ export interface IdentifierHealingConfig {
      * Optional logger used by {@link forceDecodeEncodedIdWithoutSession} to record telemetry
      * when the heal-on-decode recovery path is taken (a non-final identifier is healed).
      */
-    readonly logger?: ITelemetryBaseLogger;
+    readonly logger?: TelemetryLoggerExt;
 }
 /**
  * Decode an op-space compressed id without a session.

package/lib/util/compressedIds.d.ts.map

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

package/lib/util/compressedIds.js

@@ -2,7 +2,6 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { LogLevel } from "@fluidframework/core-interfaces";
 import { assert } from "@fluidframework/core-utils/internal";
 import { isFinalId, isStableId } from "@fluidframework/id-compressor/internal";
 import { v5 as uuidV5 } from "uuid";
@@ -112,15 +111,11 @@ export function forceDecodeEncodedIdWithoutSession(id, idCompressor, healing) {
     // `id` is a non-final op-space compressed id.
     if (healing !== undefined) {
         const healed = uuidV5(`${healing.sharedObjectId}|${id}`, healingNamespace);
-        healing.logger?.send({
-            category: "generic",
-            eventName: "HealUnresolvableIdentifierOnDecode",
-        }, 
         // This telemetry should be very low-volume (and possibly never happen at all),
         // as should only occur when loading documents that were corrupted by a now fixed bug and have not been re-summarized since healing was added.
         // It is useful for monitoring and diagnosing for this to be reported in the same cases in which the error case would be reported,
         // which is the essential level.
-        LogLevel.essential);
+        healing.logger?.sendTelemetryEvent({ eventName: "HealUnresolvableIdentifierOnDecode" });
         return healed;
     }
     throw new Error("Summary could not be loaded due to an incorrectly encoded identifier. See SharedTreeOptionsBeta.healUnresolvableIdentifiersOnDecode for mitigation.");

package/lib/util/compressedIds.js.map

@@ -1 +1 @@
-{"version":3,"file":"compressedIds.js","sourceRoot":"","sources":["../../src/util/compressedIds.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 { LogLevel, type ITelemetryBaseLogger } from \"@fluidframework/core-interfaces\";\nimport { assert } from \"@fluidframework/core-utils/internal\";\nimport type {\n\tIIdCompressor,\n\tOpSpaceCompressedId,\n\tSessionId,\n\tSessionSpaceCompressedId,\n} from \"@fluidframework/id-compressor\";\nimport { isFinalId, isStableId } from \"@fluidframework/id-compressor/internal\";\nimport { v5 as uuidV5 } from \"uuid\";\n\n/**\n * An encoded identifier that can be decoded without an originator session id.\n * A finalized compressed id — the same numeric value in op-space and session-space.\n * @remarks\n * These are safe to use in contexts where the encoding id compressor is available to decode them,\n * even when the session id of the encoding id compressor is not known.\n */\nexport type OriginatorlessEncodedId = SessionSpaceCompressedId & OpSpaceCompressedId;\n\n/**\n * An encoded identifier that may require an originator session id to decode.\n * Any op-space compressed id, either finalized or session-local.\n * @remarks\n * These are only safe to use in contexts where the encoding id compressor is available\n * and the session id of the encoding id compressor is known.\n * Currently the only such case is in ops, excluding attach summary ops.\n */\nexport type OriginatorDependentEncodedId = OpSpaceCompressedId;\n\n/**\n * Selects how identifiers are encoded for transport/persistence.\n */\nexport enum EncodedIdType {\n\t/**\n\t * {@link OriginatorlessEncodedId}.\n\t */\n\tOriginatorless,\n\t/**\n\t * {@link OriginatorDependentEncodedId}.\n\t */\n\tOriginatorDependent,\n}\n\nexport type EncodedId<T extends EncodedIdType> = T extends EncodedIdType.Originatorless\n\t? OriginatorlessEncodedId\n\t: T extends EncodedIdType.OriginatorDependent\n\t\t? OriginatorDependentEncodedId\n\t\t: OriginatorlessEncodedId | OriginatorDependentEncodedId;\n\n/**\n * Context for encoding identifiers.\n * @remarks\n * See {@link FieldBatchDecodingContext} for the decoder.\n */\nexport interface IdEncodingContext {\n\tencodePossiblyCompressedId(id: string): string | EncodedId<EncodedIdType>;\n}\n\n/**\n * Encode a string identifier into a possibly compressed form based on the requested mode.\n *\n * @param id - The string identifier to encode.\n * @param idCompressor - The ID compressor to use for compression.\n * @param encodedIdType - The type of encoding to use. If the context doing the decoding will have the originator {@link SessionId},\n * then {@link EncodedIdType.OriginatorDependent} can be used.\n * Otherwise, {@link EncodedIdType.Originatorless} must be used.\n *\n * @privateRemarks\n * Performance:\n * When trying to optimize to avoid unnecessary identifier decompression, and store identifiers compressed in memory,\n * this will likely need to be updated to allow in SessionSpaceCompressedIds.\n */\nexport function encodePossiblyCompressedId<T extends EncodedIdType>(\n\tid: string,\n\tidCompressor: IIdCompressor,\n\tencodedIdType: T,\n): string | EncodedId<T> {\n\tif (!isStableId(id)) {\n\t\treturn id;\n\t}\n\tconst sessionSpaceCompressedId = idCompressor.tryRecompress(id);\n\tif (sessionSpaceCompressedId === undefined) {\n\t\treturn id;\n\t}\n\tconst opSpaceId = idCompressor.normalizeToOpSpace(sessionSpaceCompressedId);\n\tif (encodedIdType === EncodedIdType.Originatorless) {\n\t\treturn isFinalId(opSpaceId) ? (opSpaceId as unknown as EncodedId<T>) : id;\n\t}\n\treturn opSpaceId as unknown as EncodedId<T>;\n}\n\n/**\n * Namespace used for the deterministic UUIDv5 produced by the heal-on-decode workaround\n * in {@link forceDecodeEncodedIdWithoutSession}.\n *\n * This scheme requires consensus across all clients to function — every client that\n * encounters the same unresolvable id must produce the same v5 UUID.\n */\nconst healingNamespace = \"f8a89df3-6882-400f-b913-4c1f6f0157bd\";\n\n/**\n * Decode an {@link OriginatorlessEncodedId} without needing an originator session id.\n *\n * The id is guaranteed to be final by the type contract; it is normalized via\n * {@link IIdCompressor.tryNormalizeToSessionSpaceWithoutSession}, which handles the\n * cluster-aligned-local case rather than relying on the bare numeric value.\n */\nexport function decodeOriginatorlessEncodedId(\n\tid: OriginatorlessEncodedId,\n\tidCompressor: IIdCompressor,\n): SessionSpaceCompressedId {\n\tconst sessionSpaceId = idCompressor.tryNormalizeToSessionSpaceWithoutSession(id);\n\tassert(\n\t\tsessionSpaceId !== undefined,\n\t\t0xd0a /* OriginatorlessEncodedId must be a finalized compressed id at runtime */,\n\t);\n\treturn sessionSpaceId;\n}\n\n/**\n * Decode an {@link OriginatorDependentEncodedId} using a known originator session id.\n */\nexport function decodeEncodedIdWithOriginator(\n\tid: OriginatorDependentEncodedId,\n\toriginator: SessionId,\n\tidCompressor: IIdCompressor,\n): SessionSpaceCompressedId {\n\treturn idCompressor.normalizeToSessionSpace(id, originator);\n}\n\n/**\n * Decode an {@link OriginatorDependentEncodedId} without a session.\n *\n * Returns the session-space id if `id` is finalized (and therefore resolvable\n * without an originator session), or `undefined` if `id` is a non-final op-space\n * id that cannot be resolved without the originator session.\n */\nexport function tryDecodeEncodedIdWithoutSession(\n\tid: OriginatorDependentEncodedId,\n\tidCompressor: IIdCompressor,\n): SessionSpaceCompressedId | undefined {\n\treturn idCompressor.tryNormalizeToSessionSpaceWithoutSession(id);\n}\n\n/**\n * Configuration for the heal-on-decode workaround. The internal counterpart of\n * the user-facing {@link SharedTreeOptionsBeta.healUnresolvableIdentifiersOnDecode}\n * option — see that option for the user-facing rationale and trade-offs.\n *\n * Carried by decode-side contexts ({@link IdDecoderOptionsOriginatorless},\n * `ChangeEncodingContext.healing`,\n * `EditManagerEncodingContext.healing`, etc.) when the workaround is enabled.\n * Presence enables healing; `undefined` means healing is disabled. There is no separate boolean,\n * which makes it impossible to enable healing without supplying the namespace\n * input.\n */\nexport interface IdentifierHealingConfig {\n\t/**\n\t * The SharedTree's shared-object id, used as the v5 namespace input so\n\t * healed UUIDs are unique across attaches of different documents with the\n\t * same session offsets.\n\t */\n\treadonly sharedObjectId: string;\n\n\t/**\n\t * Optional logger used by {@link forceDecodeEncodedIdWithoutSession} to record telemetry\n\t * when the heal-on-decode recovery path is taken (a non-final identifier is healed).\n\t */\n\treadonly logger?: ITelemetryBaseLogger;\n}\n\n/**\n * Decode an op-space compressed id without a session.\n *\n * Finalized ids are returned as session-space ids (final ids are invariant\n * across the two spaces). Non-final ids are healed via {@link IdentifierHealingConfig}\n * if provided, or cause the resolver to throw otherwise. A healed result is a\n * deterministic v5 UUID string — *not* a `StableId`, since that brand requires\n * v4, but still a valid identifier value; the `string` arm of the return type\n * covers this case.\n *\n * The recovery (heal) path only occurs because of a prior bug where non-finalized identifiers were\n * written into summaries. When {@link IdentifierHealingConfig.logger} is supplied, a telemetry event\n * is recorded on that path so heals can be observed in the wild. The error/throw path is intentionally\n * not instrumented here: the thrown exception is expected to surface via the application's own error\n * telemetry, and should never be silently swallowed.\n *\n * @param id - The op-space compressed ID to decode.\n * @param idCompressor - The ID compressor used to normalize the ID.\n * @param healing - Heal-on-decode configuration. Presence enables healing of non-final IDs.\n */\nexport function forceDecodeEncodedIdWithoutSession(\n\tid: OpSpaceCompressedId,\n\tidCompressor: IIdCompressor,\n\thealing: IdentifierHealingConfig | undefined,\n): SessionSpaceCompressedId | string {\n\tconst decoded = tryDecodeEncodedIdWithoutSession(id, idCompressor);\n\tif (decoded !== undefined) {\n\t\treturn decoded;\n\t}\n\t// `id` is a non-final op-space compressed id.\n\tif (healing !== undefined) {\n\t\tconst healed = uuidV5(`${healing.sharedObjectId}|${id}`, healingNamespace);\n\t\thealing.logger?.send(\n\t\t\t{\n\t\t\t\tcategory: \"generic\",\n\t\t\t\teventName: \"HealUnresolvableIdentifierOnDecode\",\n\t\t\t},\n\t\t\t// This telemetry should be very low-volume (and possibly never happen at all),\n\t\t\t// as should only occur when loading documents that were corrupted by a now fixed bug and have not been re-summarized since healing was added.\n\t\t\t// It is useful for monitoring and diagnosing for this to be reported in the same cases in which the error case would be reported,\n\t\t\t// which is the essential level.\n\t\t\tLogLevel.essential,\n\t\t);\n\t\treturn healed;\n\t}\n\tthrow new Error(\n\t\t\"Summary could not be loaded due to an incorrectly encoded identifier. See SharedTreeOptionsBeta.healUnresolvableIdentifiersOnDecode for mitigation.\",\n\t);\n}\n\n/**\n * Convert a decoded, but possibly compressed, identifier to the decompressed string format.\n *\n * Session-space compressed ids are decompressed to their UUID representation via the compressor.\n * String inputs pass through unchanged — they are already in the stored form,\n * whether a `StableId` UUID, a heal-synthesized v5 UUID or other arbitrary string identifier.\n */\nexport function decompressIdentifierIfNeeded(\n\tid: SessionSpaceCompressedId | string,\n\tidCompressor: Pick<IIdCompressor, \"decompress\">,\n): string {\n\tif (typeof id === \"string\") {\n\t\treturn id;\n\t} else {\n\t\tconst decompressed = idCompressor.decompress(id);\n\t\tassert(typeof decompressed === \"string\", 0xd0b /* Decompressed id must be a string */);\n\t\treturn decompressed;\n\t}\n}\n\n/**\n * Options for creating an {@link IdDecodingContext} without an originator.\n * @remarks\n * Decodes {@link OriginatorlessEncodedId} instances, and optionally has a {@link IdentifierHealingConfig} fallback for {@link OriginatorDependentEncodedId} instances.\n */\nexport interface IdDecoderOptionsOriginatorless {\n\treadonly idCompressor: IIdCompressor;\n\t/**\n\t * Optional {@link IdentifierHealingConfig} to use for healing unresolvable identifiers.\n\t * @privateRemarks\n\t * This is a required field which can be undefined to make it explicit when this is not provided.\n\t * This explicitness helps ensure we we don't accidentally drop the healing config as that would break\n\t * an edge case which does not get a lot of testing.\n\t */\n\treadonly healing: IdentifierHealingConfig | undefined;\n}\n\n/**\n * Options for creating an {@link IdDecodingContext} with an originator.\n * @remarks\n * Decodes {@link OriginatorDependentEncodedId} instances.\n */\nexport interface IdDecoderOptionsWithOriginator {\n\treadonly idCompressor: IIdCompressor;\n\t/**\n\t * The ID of the session that encoded the ids.\n\t */\n\treadonly originatorId: SessionId;\n}\n\n/**\n * Context for decoding identifiers.\n * @remarks\n * Depended on how this is constructed, it may or may not handle {@link OriginatorDependentEncodedId} instances.\n *\n * This intentionally avoids exposing anything which depends on the underlying id-compressor's session ID to avoid confusion with the session ID of the compressor which encoded the data.\n * If the session ID of the encoder which encoded the data is known, that information is baked into `resolveEncodedId`.\n *\n * @privateRemarks\n * We have code (FieldBatchDecodingContext) which sometimes has a session ID and sometimes doesn't, so we need a flexible decoding context.\n * Additionally, since this is about serialized data, having stronger types is often counterproductive, as it just relies more on type casts when parsing.\n * This is why we use this flexible pattern rather than code strongly typed over which kind of encoded ids are expected.\n */\nexport class IdDecodingContext {\n\t/**\n\t * Whether this context resolves identifiers using an originator session ID.\n\t * @remarks\n\t * Consulted by {@link FieldBatchDecodingContext} to prevent using an originator-based\n\t * decoder in incremental chunks (which may come from other sessions, making such a\n\t * decoder wrong there).\n\t */\n\tpublic readonly hasOriginatorSessionId: boolean;\n\n\t/**\n\t * Compressor which can decompress session-space identifiers from {@link resolveEncodedId} as needed.\n\t */\n\tpublic readonly idCompressor: Pick<IIdCompressor, \"decompress\">;\n\n\t/**\n\t * Resolves an encoded op-space identifier to either a session-space ID\n\t * (which {@link idCompressor} can decompress if needed)\n\t * or a string (which passes through unchanged).\n\t * @remarks\n\t * In contexts where non-final identifiers can't be supported (where no originator session is available),\n\t * if a non-final identifier is encountered, this may throw or perform a data healing workaround.\n\t * See {@link FieldBatchDecodingContext.forOp} and {@link FieldBatchDecodingContext.forSummary} for details.\n\t */\n\tpublic readonly resolveEncodedId: (\n\t\tid: OpSpaceCompressedId,\n\t) => SessionSpaceCompressedId | string;\n\n\t/**\n\t * Creates a new instance of the context.\n\t * @param options - The options for creating the context.\n\t */\n\tpublic constructor(\n\t\toptions: IdDecoderOptionsOriginatorless | IdDecoderOptionsWithOriginator,\n\t) {\n\t\tthis.idCompressor = options.idCompressor;\n\t\tif (\"originatorId\" in options) {\n\t\t\tthis.hasOriginatorSessionId = true;\n\t\t\tthis.resolveEncodedId = (id): SessionSpaceCompressedId | string =>\n\t\t\t\toptions.idCompressor.normalizeToSessionSpace(id, options.originatorId);\n\t\t} else {\n\t\t\tthis.hasOriginatorSessionId = false;\n\t\t\tthis.resolveEncodedId = (id): SessionSpaceCompressedId | string =>\n\t\t\t\tforceDecodeEncodedIdWithoutSession(id, options.idCompressor, options.healing);\n\t\t}\n\t}\n}\n"]}
+{"version":3,"file":"compressedIds.js","sourceRoot":"","sources":["../../src/util/compressedIds.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 type {\n\tIIdCompressor,\n\tOpSpaceCompressedId,\n\tSessionId,\n\tSessionSpaceCompressedId,\n} from \"@fluidframework/id-compressor\";\nimport { isFinalId, isStableId } from \"@fluidframework/id-compressor/internal\";\nimport type { TelemetryLoggerExt } from \"@fluidframework/telemetry-utils/internal\";\nimport { v5 as uuidV5 } from \"uuid\";\n\n/**\n * An encoded identifier that can be decoded without an originator session id.\n * A finalized compressed id — the same numeric value in op-space and session-space.\n * @remarks\n * These are safe to use in contexts where the encoding id compressor is available to decode them,\n * even when the session id of the encoding id compressor is not known.\n */\nexport type OriginatorlessEncodedId = SessionSpaceCompressedId & OpSpaceCompressedId;\n\n/**\n * An encoded identifier that may require an originator session id to decode.\n * Any op-space compressed id, either finalized or session-local.\n * @remarks\n * These are only safe to use in contexts where the encoding id compressor is available\n * and the session id of the encoding id compressor is known.\n * Currently the only such case is in ops, excluding attach summary ops.\n */\nexport type OriginatorDependentEncodedId = OpSpaceCompressedId;\n\n/**\n * Selects how identifiers are encoded for transport/persistence.\n */\nexport enum EncodedIdType {\n\t/**\n\t * {@link OriginatorlessEncodedId}.\n\t */\n\tOriginatorless,\n\t/**\n\t * {@link OriginatorDependentEncodedId}.\n\t */\n\tOriginatorDependent,\n}\n\nexport type EncodedId<T extends EncodedIdType> = T extends EncodedIdType.Originatorless\n\t? OriginatorlessEncodedId\n\t: T extends EncodedIdType.OriginatorDependent\n\t\t? OriginatorDependentEncodedId\n\t\t: OriginatorlessEncodedId | OriginatorDependentEncodedId;\n\n/**\n * Context for encoding identifiers.\n * @remarks\n * See {@link FieldBatchDecodingContext} for the decoder.\n */\nexport interface IdEncodingContext {\n\tencodePossiblyCompressedId(id: string): string | EncodedId<EncodedIdType>;\n}\n\n/**\n * Encode a string identifier into a possibly compressed form based on the requested mode.\n *\n * @param id - The string identifier to encode.\n * @param idCompressor - The ID compressor to use for compression.\n * @param encodedIdType - The type of encoding to use. If the context doing the decoding will have the originator {@link SessionId},\n * then {@link EncodedIdType.OriginatorDependent} can be used.\n * Otherwise, {@link EncodedIdType.Originatorless} must be used.\n *\n * @privateRemarks\n * Performance:\n * When trying to optimize to avoid unnecessary identifier decompression, and store identifiers compressed in memory,\n * this will likely need to be updated to allow in SessionSpaceCompressedIds.\n */\nexport function encodePossiblyCompressedId<T extends EncodedIdType>(\n\tid: string,\n\tidCompressor: IIdCompressor,\n\tencodedIdType: T,\n): string | EncodedId<T> {\n\tif (!isStableId(id)) {\n\t\treturn id;\n\t}\n\tconst sessionSpaceCompressedId = idCompressor.tryRecompress(id);\n\tif (sessionSpaceCompressedId === undefined) {\n\t\treturn id;\n\t}\n\tconst opSpaceId = idCompressor.normalizeToOpSpace(sessionSpaceCompressedId);\n\tif (encodedIdType === EncodedIdType.Originatorless) {\n\t\treturn isFinalId(opSpaceId) ? (opSpaceId as unknown as EncodedId<T>) : id;\n\t}\n\treturn opSpaceId as unknown as EncodedId<T>;\n}\n\n/**\n * Namespace used for the deterministic UUIDv5 produced by the heal-on-decode workaround\n * in {@link forceDecodeEncodedIdWithoutSession}.\n *\n * This scheme requires consensus across all clients to function — every client that\n * encounters the same unresolvable id must produce the same v5 UUID.\n */\nconst healingNamespace = \"f8a89df3-6882-400f-b913-4c1f6f0157bd\";\n\n/**\n * Decode an {@link OriginatorlessEncodedId} without needing an originator session id.\n *\n * The id is guaranteed to be final by the type contract; it is normalized via\n * {@link IIdCompressor.tryNormalizeToSessionSpaceWithoutSession}, which handles the\n * cluster-aligned-local case rather than relying on the bare numeric value.\n */\nexport function decodeOriginatorlessEncodedId(\n\tid: OriginatorlessEncodedId,\n\tidCompressor: IIdCompressor,\n): SessionSpaceCompressedId {\n\tconst sessionSpaceId = idCompressor.tryNormalizeToSessionSpaceWithoutSession(id);\n\tassert(\n\t\tsessionSpaceId !== undefined,\n\t\t0xd0a /* OriginatorlessEncodedId must be a finalized compressed id at runtime */,\n\t);\n\treturn sessionSpaceId;\n}\n\n/**\n * Decode an {@link OriginatorDependentEncodedId} using a known originator session id.\n */\nexport function decodeEncodedIdWithOriginator(\n\tid: OriginatorDependentEncodedId,\n\toriginator: SessionId,\n\tidCompressor: IIdCompressor,\n): SessionSpaceCompressedId {\n\treturn idCompressor.normalizeToSessionSpace(id, originator);\n}\n\n/**\n * Decode an {@link OriginatorDependentEncodedId} without a session.\n *\n * Returns the session-space id if `id` is finalized (and therefore resolvable\n * without an originator session), or `undefined` if `id` is a non-final op-space\n * id that cannot be resolved without the originator session.\n */\nexport function tryDecodeEncodedIdWithoutSession(\n\tid: OriginatorDependentEncodedId,\n\tidCompressor: IIdCompressor,\n): SessionSpaceCompressedId | undefined {\n\treturn idCompressor.tryNormalizeToSessionSpaceWithoutSession(id);\n}\n\n/**\n * Configuration for the heal-on-decode workaround. The internal counterpart of\n * the user-facing {@link SharedTreeOptionsBeta.healUnresolvableIdentifiersOnDecode}\n * option — see that option for the user-facing rationale and trade-offs.\n *\n * Carried by decode-side contexts ({@link IdDecoderOptionsOriginatorless},\n * `ChangeEncodingContext.healing`,\n * `EditManagerEncodingContext.healing`, etc.) when the workaround is enabled.\n * Presence enables healing; `undefined` means healing is disabled. There is no separate boolean,\n * which makes it impossible to enable healing without supplying the namespace\n * input.\n */\nexport interface IdentifierHealingConfig {\n\t/**\n\t * The SharedTree's shared-object id, used as the v5 namespace input so\n\t * healed UUIDs are unique across attaches of different documents with the\n\t * same session offsets.\n\t */\n\treadonly sharedObjectId: string;\n\n\t/**\n\t * Optional logger used by {@link forceDecodeEncodedIdWithoutSession} to record telemetry\n\t * when the heal-on-decode recovery path is taken (a non-final identifier is healed).\n\t */\n\treadonly logger?: TelemetryLoggerExt;\n}\n\n/**\n * Decode an op-space compressed id without a session.\n *\n * Finalized ids are returned as session-space ids (final ids are invariant\n * across the two spaces). Non-final ids are healed via {@link IdentifierHealingConfig}\n * if provided, or cause the resolver to throw otherwise. A healed result is a\n * deterministic v5 UUID string — *not* a `StableId`, since that brand requires\n * v4, but still a valid identifier value; the `string` arm of the return type\n * covers this case.\n *\n * The recovery (heal) path only occurs because of a prior bug where non-finalized identifiers were\n * written into summaries. When {@link IdentifierHealingConfig.logger} is supplied, a telemetry event\n * is recorded on that path so heals can be observed in the wild. The error/throw path is intentionally\n * not instrumented here: the thrown exception is expected to surface via the application's own error\n * telemetry, and should never be silently swallowed.\n *\n * @param id - The op-space compressed ID to decode.\n * @param idCompressor - The ID compressor used to normalize the ID.\n * @param healing - Heal-on-decode configuration. Presence enables healing of non-final IDs.\n */\nexport function forceDecodeEncodedIdWithoutSession(\n\tid: OpSpaceCompressedId,\n\tidCompressor: IIdCompressor,\n\thealing: IdentifierHealingConfig | undefined,\n): SessionSpaceCompressedId | string {\n\tconst decoded = tryDecodeEncodedIdWithoutSession(id, idCompressor);\n\tif (decoded !== undefined) {\n\t\treturn decoded;\n\t}\n\t// `id` is a non-final op-space compressed id.\n\tif (healing !== undefined) {\n\t\tconst healed = uuidV5(`${healing.sharedObjectId}|${id}`, healingNamespace);\n\t\t// This telemetry should be very low-volume (and possibly never happen at all),\n\t\t// as should only occur when loading documents that were corrupted by a now fixed bug and have not been re-summarized since healing was added.\n\t\t// It is useful for monitoring and diagnosing for this to be reported in the same cases in which the error case would be reported,\n\t\t// which is the essential level.\n\t\thealing.logger?.sendTelemetryEvent({ eventName: \"HealUnresolvableIdentifierOnDecode\" });\n\t\treturn healed;\n\t}\n\tthrow new Error(\n\t\t\"Summary could not be loaded due to an incorrectly encoded identifier. See SharedTreeOptionsBeta.healUnresolvableIdentifiersOnDecode for mitigation.\",\n\t);\n}\n\n/**\n * Convert a decoded, but possibly compressed, identifier to the decompressed string format.\n *\n * Session-space compressed ids are decompressed to their UUID representation via the compressor.\n * String inputs pass through unchanged — they are already in the stored form,\n * whether a `StableId` UUID, a heal-synthesized v5 UUID or other arbitrary string identifier.\n */\nexport function decompressIdentifierIfNeeded(\n\tid: SessionSpaceCompressedId | string,\n\tidCompressor: Pick<IIdCompressor, \"decompress\">,\n): string {\n\tif (typeof id === \"string\") {\n\t\treturn id;\n\t} else {\n\t\tconst decompressed = idCompressor.decompress(id);\n\t\tassert(typeof decompressed === \"string\", 0xd0b /* Decompressed id must be a string */);\n\t\treturn decompressed;\n\t}\n}\n\n/**\n * Options for creating an {@link IdDecodingContext} without an originator.\n * @remarks\n * Decodes {@link OriginatorlessEncodedId} instances, and optionally has a {@link IdentifierHealingConfig} fallback for {@link OriginatorDependentEncodedId} instances.\n */\nexport interface IdDecoderOptionsOriginatorless {\n\treadonly idCompressor: IIdCompressor;\n\t/**\n\t * Optional {@link IdentifierHealingConfig} to use for healing unresolvable identifiers.\n\t * @privateRemarks\n\t * This is a required field which can be undefined to make it explicit when this is not provided.\n\t * This explicitness helps ensure we we don't accidentally drop the healing config as that would break\n\t * an edge case which does not get a lot of testing.\n\t */\n\treadonly healing: IdentifierHealingConfig | undefined;\n}\n\n/**\n * Options for creating an {@link IdDecodingContext} with an originator.\n * @remarks\n * Decodes {@link OriginatorDependentEncodedId} instances.\n */\nexport interface IdDecoderOptionsWithOriginator {\n\treadonly idCompressor: IIdCompressor;\n\t/**\n\t * The ID of the session that encoded the ids.\n\t */\n\treadonly originatorId: SessionId;\n}\n\n/**\n * Context for decoding identifiers.\n * @remarks\n * Depended on how this is constructed, it may or may not handle {@link OriginatorDependentEncodedId} instances.\n *\n * This intentionally avoids exposing anything which depends on the underlying id-compressor's session ID to avoid confusion with the session ID of the compressor which encoded the data.\n * If the session ID of the encoder which encoded the data is known, that information is baked into `resolveEncodedId`.\n *\n * @privateRemarks\n * We have code (FieldBatchDecodingContext) which sometimes has a session ID and sometimes doesn't, so we need a flexible decoding context.\n * Additionally, since this is about serialized data, having stronger types is often counterproductive, as it just relies more on type casts when parsing.\n * This is why we use this flexible pattern rather than code strongly typed over which kind of encoded ids are expected.\n */\nexport class IdDecodingContext {\n\t/**\n\t * Whether this context resolves identifiers using an originator session ID.\n\t * @remarks\n\t * Consulted by {@link FieldBatchDecodingContext} to prevent using an originator-based\n\t * decoder in incremental chunks (which may come from other sessions, making such a\n\t * decoder wrong there).\n\t */\n\tpublic readonly hasOriginatorSessionId: boolean;\n\n\t/**\n\t * Compressor which can decompress session-space identifiers from {@link resolveEncodedId} as needed.\n\t */\n\tpublic readonly idCompressor: Pick<IIdCompressor, \"decompress\">;\n\n\t/**\n\t * Resolves an encoded op-space identifier to either a session-space ID\n\t * (which {@link idCompressor} can decompress if needed)\n\t * or a string (which passes through unchanged).\n\t * @remarks\n\t * In contexts where non-final identifiers can't be supported (where no originator session is available),\n\t * if a non-final identifier is encountered, this may throw or perform a data healing workaround.\n\t * See {@link FieldBatchDecodingContext.forOp} and {@link FieldBatchDecodingContext.forSummary} for details.\n\t */\n\tpublic readonly resolveEncodedId: (\n\t\tid: OpSpaceCompressedId,\n\t) => SessionSpaceCompressedId | string;\n\n\t/**\n\t * Creates a new instance of the context.\n\t * @param options - The options for creating the context.\n\t */\n\tpublic constructor(\n\t\toptions: IdDecoderOptionsOriginatorless | IdDecoderOptionsWithOriginator,\n\t) {\n\t\tthis.idCompressor = options.idCompressor;\n\t\tif (\"originatorId\" in options) {\n\t\t\tthis.hasOriginatorSessionId = true;\n\t\t\tthis.resolveEncodedId = (id): SessionSpaceCompressedId | string =>\n\t\t\t\toptions.idCompressor.normalizeToSessionSpace(id, options.originatorId);\n\t\t} else {\n\t\t\tthis.hasOriginatorSessionId = false;\n\t\t\tthis.resolveEncodedId = (id): SessionSpaceCompressedId | string =>\n\t\t\t\tforceDecodeEncodedIdWithoutSession(id, options.idCompressor, options.healing);\n\t\t}\n\t}\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/tree",
-  "version": "2.115.0",
+  "version": "2.116.0",
   "description": "Distributed tree",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -101,17 +101,17 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "~2.115.0",
-    "@fluidframework/core-interfaces": "~2.115.0",
-    "@fluidframework/core-utils": "~2.115.0",
-    "@fluidframework/datastore-definitions": "~2.115.0",
-    "@fluidframework/driver-definitions": "~2.115.0",
-    "@fluidframework/id-compressor": "~2.115.0",
-    "@fluidframework/runtime-definitions": "~2.115.0",
-    "@fluidframework/runtime-utils": "~2.115.0",
-    "@fluidframework/shared-object-base": "~2.115.0",
-    "@fluidframework/telemetry-utils": "~2.115.0",
-    "@fluidframework/type-factory": "~2.115.0",
+    "@fluid-internal/client-utils": "~2.116.0",
+    "@fluidframework/core-interfaces": "~2.116.0",
+    "@fluidframework/core-utils": "~2.116.0",
+    "@fluidframework/datastore-definitions": "~2.116.0",
+    "@fluidframework/driver-definitions": "~2.116.0",
+    "@fluidframework/id-compressor": "~2.116.0",
+    "@fluidframework/runtime-definitions": "~2.116.0",
+    "@fluidframework/runtime-utils": "~2.116.0",
+    "@fluidframework/shared-object-base": "~2.116.0",
+    "@fluidframework/telemetry-utils": "~2.116.0",
+    "@fluidframework/type-factory": "~2.116.0",
     "@sinclair/typebox": "^0.34.13",
     "@tylerbu/sorted-btree-es6": "^2.1.1",
     "semver-ts": "^1.0.3",
@@ -119,24 +119,24 @@
     "uuid": "^11.1.0"
   },
   "devDependencies": {
-    "@arethetypeswrong/cli": "^0.18.2",
+    "@arethetypeswrong/cli": "^0.18.5",
     "@biomejs/biome": "~2.4.5",
-    "@fluid-internal/mocha-test-setup": "~2.115.0",
-    "@fluid-private/stochastic-test-utils": "~2.115.0",
-    "@fluid-private/test-dds-utils": "~2.115.0",
-    "@fluid-private/test-drivers": "~2.115.0",
+    "@fluid-internal/mocha-test-setup": "~2.116.0",
+    "@fluid-private/stochastic-test-utils": "~2.116.0",
+    "@fluid-private/test-dds-utils": "~2.116.0",
+    "@fluid-private/test-drivers": "~2.116.0",
     "@fluid-tools/benchmark": "^0.59.0",
-    "@fluid-tools/build-cli": "^0.65.0",
+    "@fluid-tools/build-cli": "^0.67.0",
     "@fluidframework/build-common": "^2.0.3",
-    "@fluidframework/build-tools": "^0.65.0",
-    "@fluidframework/container-definitions": "~2.115.0",
-    "@fluidframework/container-loader": "~2.115.0",
-    "@fluidframework/container-runtime": "~2.115.0",
-    "@fluidframework/eslint-config-fluid": "^13.0.0",
-    "@fluidframework/local-driver": "~2.115.0",
-    "@fluidframework/test-runtime-utils": "~2.115.0",
-    "@fluidframework/test-utils": "~2.115.0",
-    "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.112.0",
+    "@fluidframework/build-tools": "^0.67.0",
+    "@fluidframework/container-definitions": "~2.116.0",
+    "@fluidframework/container-loader": "~2.116.0",
+    "@fluidframework/container-runtime": "~2.116.0",
+    "@fluidframework/eslint-config-fluid": "^14.0.0",
+    "@fluidframework/local-driver": "~2.116.0",
+    "@fluidframework/test-runtime-utils": "~2.116.0",
+    "@fluidframework/test-utils": "~2.116.0",
+    "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.114.0",
     "@microsoft/api-extractor": "7.58.1",
     "@types/diff": "^3.5.1",
     "@types/easy-table": "^0.0.32",

package/src/codec/codec.ts

@@ -5,7 +5,7 @@
 
 import type { ErasedType } from "@fluidframework/core-interfaces/internal";
 import { assert, fail } from "@fluidframework/core-utils/internal";
-import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
+import type { OldestSupportedClientVersion } from "@fluidframework/runtime-definitions/internal";
 import { cleanedPackageVersion as runtimeUtilsCleanedPackageVersion } from "@fluidframework/runtime-utils/internal";
 import type { Static, TAnySchema, TSchema } from "@sinclair/typebox";
 
@@ -149,7 +149,7 @@ export interface CodecWriteOptionsBeta {
 	 * 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 minVersionForCollab: MinimumVersionForCollab;
+	readonly minVersionForCollab: OldestSupportedClientVersion;
 }
 
 /**
@@ -472,7 +472,7 @@ export function withSchemaValidation<
 }
 
 /**
- * Versions of Fluid Framework client packages, usable as a {@link @fluidframework/runtime-definitions#MinimumVersionForCollab}.
+ * Versions of Fluid Framework client packages, usable as a {@link @fluidframework/runtime-definitions#OldestSupportedClientVersion}.
  * @remarks
  * Versions with no notable impact may be omitted, and added later if needed.
  *
@@ -480,7 +480,7 @@ export function withSchemaValidation<
  * Each entry should document:
  * - The user-facing impact of opting into it (e.g. encoding efficiency improvements).
  * - Any new data formats introduced in that version.
- * - Whether those features/formats are enabled by default or require {@link MinimumVersionForCollab | minVersionForCollab} to be set accordingly.
+ * - Whether those features/formats are enabled by default or require {@link OldestSupportedClientVersion | minVersionForCollab} to be set accordingly.
  * @alpha
  */
 export const FluidClientVersion = {
@@ -540,14 +540,14 @@ export const FluidClientVersion = {
 	 * - ModularChangeFormatVersion.v5 - written when minVersionForCollab \>= 2.80
 	 */
 	v2_80: "2.80.0",
-} as const satisfies Record<string, MinimumVersionForCollab>;
+} as const satisfies Record<string, OldestSupportedClientVersion>;
 
 /**
  * An up to date version which includes all stable features.
  * @remarks
  * Use for cases when data is not persisted and thus would only ever be read by the the same version of the code which read this value.
  *
- * The pkgVersion from this package (tree) can not be used here as it is not guaranteed to be a valid MinimumVersionForCollab
+ * The pkgVersion from this package (tree) can not be used here as it is not guaranteed to be a valid OldestSupportedClientVersion
  * and would also unexpectedly disable features in prereleases and on CI if it didn't fail validation.
  * See {@link @fluidframework/runtime-utils/internal#cleanedPackageVersion} for more details on why cleanedPackageVersion is preferred over pkgVersion.
  *
@@ -558,7 +558,7 @@ export const FluidClientVersion = {
  * Reusing this from runtime-utils avoids duplicating the cleanup logic here as well as the cost or recomputing it.
  * If in the future for some reason this becomes not okay, runtime-utils could instead export a function that performs that cleanup logic which could be reused here.
  */
-export const currentVersion: MinimumVersionForCollab = runtimeUtilsCleanedPackageVersion;
+export const currentVersion: OldestSupportedClientVersion = runtimeUtilsCleanedPackageVersion;
 
 /**
  * TODO:

package/src/codec/versioned/codec.ts

@@ -4,7 +4,7 @@
  */
 
 import { assert, debugAssert } from "@fluidframework/core-utils/internal";
-import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
+import type { OldestSupportedClientVersion } from "@fluidframework/runtime-definitions/internal";
 import {
 	getConfigForMinVersionForCollabIterable,
 	lowestMinVersionForCollab,
@@ -179,7 +179,7 @@ export interface CodecVersionBase<
 	 * `undefined` should be used for unstable codec versions (with string FormatVersions),
 	 * as well as previously stabilized formats that are discontinued (meaning we always prefer to use some other format for encoding).
 	 */
-	readonly minVersionForCollab: MinimumVersionForCollab | undefined;
+	readonly minVersionForCollab: OldestSupportedClientVersion | undefined;
 	readonly formatVersion: TFormatVersion;
 	readonly codec: T;
 }
@@ -499,7 +499,7 @@ The client which encoded this data likely specified an "minVersionForCollab" val
 		return this.buildDecoderInternal(options)[1];
 	}
 
-	public getCodecTree(clientVersion: MinimumVersionForCollab): CodecTree<TFormatVersion> {
+	public getCodecTree(clientVersion: OldestSupportedClientVersion): CodecTree<TFormatVersion> {
 		// TODO: add support for children codecs.
 		const selected = getWriteVersionNoOverrides(this.registry, clientVersion);
 		return {
@@ -611,9 +611,9 @@ function getWriteVersion<T extends CodecVersionBase>(
  */
 function getWriteVersionNoOverrides<T extends CodecVersionBase>(
 	versions: readonly T[],
-	minVersionForCollab: MinimumVersionForCollab,
+	minVersionForCollab: OldestSupportedClientVersion,
 ): T {
-	const stableVersions: [MinimumMinorSemanticVersion | MinimumVersionForCollab, T][] = [];
+	const stableVersions: [MinimumMinorSemanticVersion | OldestSupportedClientVersion, T][] = [];
 	for (const version of versions) {
 		if (version.minVersionForCollab !== undefined) {
 			stableVersions.push([version.minVersionForCollab, version]);

package/src/core/forest/editableForest.ts

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
+import type { Breakable } from "../../util/index.js";
 import type { FieldKey } from "../schema-stored/index.js";
 import type { Anchor, DeltaVisitor, DetachedField } from "../tree/index.js";
 
@@ -12,6 +13,7 @@ import type { IForestSubscription, ITreeSubscriptionCursor } from "./forest.js";
  * Editing APIs.
  */
 export interface IEditableForest extends IForestSubscription {
+	readonly breaker: Breakable;
 	/**
 	 * Provides a visitor that can be used to mutate the forest.
 	 *

package/src/core/index.ts

@@ -50,7 +50,7 @@ export {
 	visitDelta,
 	createAnnouncedVisitor,
 	combineVisitors,
-	announceDelta,
+	makeBreakingVisitor,
 	applyDelta,
 	makeDetachedFieldIndex,
 	setGenericTreeField,

package/src/core/tree/index.ts

@@ -94,10 +94,10 @@ export {
 export { type DeltaVisitor, visitDelta } from "./visitDelta.js";
 export {
 	type AnnouncedVisitor,
-	announceDelta,
 	applyDelta,
 	createAnnouncedVisitor,
 	combineVisitors,
+	makeBreakingVisitor,
 	makeDetachedFieldIndex,
 } from "./visitorUtils.js";