@fluidframework/tree 2.93.0 → 2.101.0

package/CHANGELOG.md

@@ -1,5 +1,79 @@
 # @fluidframework/tree
 
+## 2.101.0
+
+### Minor Changes
+
+- Add SharedTreeOptionsBeta.healUnresolvableIdentifiersOnDecode to recover documents with corrupted identifiers ([#27281](https://github.com/microsoft/FluidFramework/pull/27281)) [d9205ddcd6a](https://github.com/microsoft/FluidFramework/commit/d9205ddcd6a9f0ec11d5422b38e30a6a91a9258c)
+
+  A SharedTree bug can result in corrupted documents due to their attach summary compressing identifier-field values in a way that cannot be uncompressed.
+  This bug manifested as remote clients processing the op throwing an error with the message "Unknown op space ID.".
+
+  This change adds an option (`healUnresolvableIdentifiersOnDecode`) to `configuredSharedTreeBetaLegacy` which will allow documents affected by this bug to load again when enabled.
+  Enabling this option carries some risk, see documentation on the interface itself for more details.
+
+  #### Who is affected
+
+  Only SharedTrees attached to a container that was already attached can be impacted.
+  Furthermore, this bug only occurs when the attached tree contains [`identifier`](https://fluidframework.com/docs/api/tree/schemafactory-class#identifier-property) fields which contain implicitly generated default values.
+
+- Fix a SharedTree document corruption bug ([#27292](https://github.com/microsoft/FluidFramework/pull/27292)) [6f4cdcb7a0a](https://github.com/microsoft/FluidFramework/commit/6f4cdcb7a0a76ba215a361c7b3a12943750fe286)
+
+  A SharedTree bug which could corrupt documents when attaching them to containers has been fixed.
+  See `healUnresolvableIdentifiersOnDecode` on `configuredSharedTreeBetaLegacy` for a potential mitigation path for documents that were already corrupted by this bug.
+
+  #### Who is affected
+
+  Only SharedTrees attached to a container that was already attached can be impacted.
+  Furthermore, this bug only occurs when the attached tree contains [`identifier`](https://fluidframework.com/docs/api/tree/schemafactory-class#identifier-property) fields which contain implicitly generated default values.
+
+## 2.100.0
+
+### Minor Changes
+
+- Node 22 is now the minimum supported Node.js version ([#27116](https://github.com/microsoft/FluidFramework/pull/27116)) [e8214d29663](https://github.com/microsoft/FluidFramework/commit/e8214d29663f5ee98d737daed82506a25d8de8d0)
+
+  All Fluid Framework client packages now require Node.js 22 or later. This aligns with the standing Node upgrade policy as Node 20 reaches end-of-life on April 30, 2026.
+
+- Add SchemaFactoryAlpha.stagedOptionalRecursive for recursive staged-optional fields ([#27042](https://github.com/microsoft/FluidFramework/pull/27042)) [a6e084e2b66](https://github.com/microsoft/FluidFramework/commit/a6e084e2b66a1dd020aecafc74d163806481e55c)
+
+  `SchemaFactoryAlpha.stagedOptionalRecursive(T)` is the recursive-type variant of `stagedOptional` (released in [2.93.0](https://github.com/microsoft/FluidFramework/pull/26918)). Use it for schemas whose types are recursive - the relaxed type constraints work around TypeScript's limitations with recursive schema definitions. Pair it with `ValidateRecursiveSchema` for improved type safety.
+
+  Example:
+
+  ```typescript
+  const sf = new SchemaFactoryAlpha("my-app");
+  class TreeNode extends sf.objectRecursiveAlpha("TreeNode", {
+    value: sf.number,
+    child: sf.stagedOptionalRecursive([() => TreeNode]),
+  }) {}
+  type _check = ValidateRecursiveSchema<typeof TreeNode>;
+  ```
+
+  See `stagedOptional` for the migration pattern (required to stagedOptional to optional).
+
+- Fixed incremental summary bug in SharedTree that may cause repeated summary failures eventually leading to document corruption ([#26990](https://github.com/microsoft/FluidFramework/pull/26990)) [1514c310319](https://github.com/microsoft/FluidFramework/commit/1514c310319074fca0c45449527a336d48801b84)
+
+  Incremental summary for SharedTree is off by default. This bug only affects applications that have explicitly enabled incremental summarization.
+
+  **Affected configurations**
+
+  A session could be affected if all the following were true:
+  - Incremental summarization was enabled (opt-in feature, off by default).
+  - The SharedTree schema had incremental fields nested at least 2 levels deep. For example, a map field marked with `incrementalSummaryHint` that contains objects which themselves have a map field also marked with `incrementalSummaryHint`.
+  - The document was summarized multiple times, with the outer incremental field changing in at least one summary while the inner incremental field remained unchanged.
+
+  **Symptoms**
+
+  Summaries would fail. Depending on the storage service, the error may appear as:
+  - `TypeError: Cannot read properties of undefined (reading 'trees')` (for example, when using SharePoint storage)
+
+  Repeated summary failures can cause a session to accumulate ops without a summary. Once the limit of ops without a summary is reached (~10k), further ops will be rejected, making the document read-only for that session.
+
+  **Mitigation and recovery**
+  - If a session is already affected, turning off incremental summarization will allow summaries to succeed again.
+  - Upgrade to this version to prevent further summary failures.
+
 ## 2.93.0
 
 ### Minor Changes

package/INCREMENTAL_SUMMARY.md

@@ -0,0 +1,89 @@
+# Incremental Summary
+
+Incremental summary is an optimization that avoids re-summarizing parts of the tree that don't change between summaries. Types in a schema can opt in to incremental summarization by being marked with `incrementalSummaryHint`. These types are tracked as independent chunks in the summary. During summarization, if their content hasn't changed since the last summary, their previously generated summaries are reused. As a result, their data doesn't need to be re-encoded (saving processing time), and their summary trees don't need to be uploaded again (reducing summary upload size).
+
+> **Warning:** This is an alpha API and is actively under development. Interfaces and behavior may change in future releases without notice. Do not rely on it in production.
+
+## Requirements
+
+All five of the following must be set for incremental summary to take effect:
+
+| Requirement | Value |
+|---|---|
+| Forest type | [`ForestTypeOptimized`](./src/shared-tree/sharedTree.ts) |
+| Compression strategy | [`TreeCompressionStrategy.CompressedIncremental`](./src/feature-libraries/treeCompressionUtils.ts) |
+| [`shouldEncodeIncrementally`](./src/shared-tree/sharedTree.ts) option | result of [`incrementalEncodingPolicyForAllowedTypes(config)`](./src/simple-tree/api/incrementalAllowedTypes.ts) |
+| `minVersionForCollab` | [`FluidClientVersion.v2_74`](./src/codec/codec.ts) or higher |
+| Schema opt-in | Fields marked with [`incrementalSummaryHint`](./src/simple-tree/api/incrementalAllowedTypes.ts) |
+
+## How to Enable
+
+### 1. Mark fields in your schema
+
+Use `sf.types(...)` with `incrementalSummaryHint` in the `custom` metadata to opt a field in.
+
+```typescript
+import { SchemaFactoryAlpha, incrementalSummaryHint } from "@fluidframework/tree/alpha";
+
+const sf = new SchemaFactoryAlpha("my-app");
+
+class Item extends sf.objectAlpha("Item", {
+    id: sf.number,
+    // This field will be incrementally summarized.
+    payload: sf.types([{ type: sf.string, metadata: {} }], {
+        custom: { [incrementalSummaryHint]: true },
+    }),
+}) {}
+
+class ItemList extends sf.arrayAlpha(
+    "ItemList",
+    // Each element of this array will be tracked as a separate incremental chunk.
+    sf.types([{ type: Item, metadata: {} }], {
+        custom: { [incrementalSummaryHint]: true },
+    }),
+) {}
+
+class Root extends sf.objectAlpha("Root", {
+    items: ItemList,
+}) {}
+```
+
+> **Note:** Incremental summarization is applied to **fields**, not node kinds. Leaf values (string, number, boolean, null) can be incrementally summarized when they are stored in a field that is opted in via `incrementalSummaryHint` (for example, an object field whose allowed type is `string`). Root fields themselves cannot be incrementally summarized, and leaf node kinds do not expose child fields for the policy to apply to.
+
+### 2. Configure the SharedTree
+
+Pass all four required options when creating the SharedTree using `configuredSharedTreeAlpha`:
+
+```typescript
+import {
+    configuredSharedTreeAlpha,
+    ForestTypeOptimized,
+    TreeCompressionStrategy,
+    TreeViewConfigurationAlpha,
+    incrementalEncodingPolicyForAllowedTypes,
+    FluidClientVersion,
+} from "@fluidframework/tree/alpha";
+
+const config = new TreeViewConfigurationAlpha({ schema: Root });
+
+const TreeFactory = configuredSharedTreeAlpha({
+    forest: ForestTypeOptimized,
+    treeEncodeType: TreeCompressionStrategy.CompressedIncremental,
+    shouldEncodeIncrementally: incrementalEncodingPolicyForAllowedTypes(config),
+    minVersionForCollab: FluidClientVersion.v2_74,
+});
+
+const sharedTree = TreeFactory.create(runtime, "tree");
+```
+
+## How `incrementalEncodingPolicyForAllowedTypes` Works
+
+`incrementalEncodingPolicyForAllowedTypes` takes a `TreeSchema` (typically a `TreeViewConfiguration`) and returns an `IncrementalEncodingPolicy` callback. During summarization, the callback is invoked for each field in the tree with the node identifier and field key. It returns `true` if the field was opted in via `incrementalSummaryHint`, directing the summarizer to encode that field as a separate, reusable chunk.
+
+Fields that are _not_ opted in are encoded into the main summary blob as usual.
+
+## Limitations and future work
+
+- Root fields cannot be incrementally summarized (the callback always returns `false` for them).
+- If the view schema doesn't recognize a node type (e.g., due to schema mismatch or unknown optional fields), that node falls back to non-incremental encoding.
+- This feature is `@alpha` and the `incrementalSummaryHint` symbol will be replaced by a dedicated metadata property once the APIs stabilize.

package/README.md

@@ -193,6 +193,12 @@ class Holder extends schemaFactory.object("Holder", { item: itemTypes }) {}
 const holder = new Holder({ item: new ItemA({ a: 42 }) });
 ```
 
+### How do I effectively use SharedTree when using TypeScript's `isolatedDeclarations`?
+
+SharedTree schema heavily use expression types and class expressions as base classes, both of which `isolatedDeclarations` disallows.
+
+See [isolated-declarations.md](docs/user-facing/isolated-declarations.md) for an explanation of the problem and recommended approaches for using SharedTree schema in a project that requires `isolatedDeclarations`.
+
 ## Architecture
 
 This section covers the internal structure of the Tree DDS.

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

@@ -1143,6 +1143,8 @@ export class SchemaFactoryAlpha<out TScope extends string | undefined = string |
     scopedFactoryAlpha<const T extends TName, TNameInner extends number | string = string>(name: T): SchemaFactoryAlpha<ScopedSchemaName<TScope, T>, TNameInner>;
     readonly stagedOptional: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "stagedOptionalUpgrade" | "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata, FieldPropsAlpha<TCustomMetadata>>;
     static readonly stagedOptional: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "stagedOptionalUpgrade" | "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata, FieldPropsAlpha<TCustomMetadata>>;
+    readonly stagedOptionalRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "stagedOptionalUpgrade" | "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Optional, T, TCustomMetadata, FieldPropsAlpha<TCustomMetadata>>;
+    static readonly stagedOptionalRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "stagedOptionalUpgrade" | "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Optional, T, TCustomMetadata, FieldPropsAlpha<TCustomMetadata>>;
     readonly withDefault: <Kind extends FieldKind, Types extends ImplicitAllowedTypes, TCustomMetadata = unknown>(fieldSchema: FieldSchema<Kind, Types, TCustomMetadata>, defaultValue: NodeProvider<ApplyKindInput<InsertableTreeNodeFromImplicitAllowedTypes<Types>, Kind, true>>) => FieldSchemaAlpha<Kind, Types, TCustomMetadata, FieldPropsAlpha<TCustomMetadata> & {
         defaultProvider: DefaultProvider;
     }>;
@@ -1201,6 +1203,7 @@ export interface SchemaStatics {
 // @alpha @sealed @system
 export interface SchemaStaticsAlpha {
     readonly stagedOptional: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider" | "stagedOptionalUpgrade">) => FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata, FieldPropsAlpha<TCustomMetadata>>;
+    readonly stagedOptionalRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider" | "stagedOptionalUpgrade">) => FieldSchemaAlphaUnsafe<FieldKind.Optional, T, TCustomMetadata, FieldPropsAlpha<TCustomMetadata>>;
     readonly withDefault: <Kind extends FieldKind, Types extends ImplicitAllowedTypes, TCustomMetadata = unknown>(fieldSchema: FieldSchema<Kind, Types, TCustomMetadata>, defaultValue: NodeProvider<InsertableTreeFieldFromImplicitField<FieldSchema<Kind, Types>>>) => FieldSchemaAlpha<Kind, Types, TCustomMetadata, FieldPropsAlpha<TCustomMetadata> & {
         defaultProvider: DefaultProvider;
     }>;
@@ -1244,7 +1247,9 @@ export interface SharedTreeOptions extends SharedTreeOptionsBeta, Partial<CodecW
 }
 
 // @beta @input
-export type SharedTreeOptionsBeta = ForestOptions & Partial<CodecWriteOptionsBeta>;
+export interface SharedTreeOptionsBeta extends ForestOptions, Partial<CodecWriteOptionsBeta> {
+    readonly healUnresolvableIdentifiersOnDecode?: boolean;
+}
 
 // @alpha @sealed
 export interface SimpleAllowedTypeAttributes<out Type extends SchemaType = SchemaType> {

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

@@ -597,7 +597,9 @@ export class SchemaUpgrade {
 type ScopedSchemaName<TScope extends string | undefined, TName extends number | string> = TScope extends undefined ? `${TName}` : `${TScope}.${TName}`;
 
 // @beta @input
-export type SharedTreeOptionsBeta = ForestOptions & Partial<CodecWriteOptionsBeta>;
+export interface SharedTreeOptionsBeta extends ForestOptions, Partial<CodecWriteOptionsBeta> {
+    readonly healUnresolvableIdentifiersOnDecode?: boolean;
+}
 
 // @public @sealed @system
 export interface SimpleNodeSchemaBase<out TNodeKind extends NodeKind, out TCustomMetadata = unknown> {

package/api-report/tree.legacy.beta.api.md

@@ -609,7 +609,9 @@ export const SharedTreeAttributes: IChannelAttributes;
 export const SharedTreeFactoryType = "https://graph.microsoft.com/types/tree";
 
 // @beta @input
-export type SharedTreeOptionsBeta = ForestOptions & Partial<CodecWriteOptionsBeta>;
+export interface SharedTreeOptionsBeta extends ForestOptions, Partial<CodecWriteOptionsBeta> {
+    readonly healUnresolvableIdentifiersOnDecode?: boolean;
+}
 
 // @public @sealed @system
 export interface SimpleNodeSchemaBase<out TNodeKind extends NodeKind, out TCustomMetadata = unknown> {

package/dist/core/change-family/changeFamily.d.ts

@@ -17,6 +17,29 @@ export interface ChangeEncodingContext {
     readonly revision: RevisionTag | undefined;
     readonly idCompressor: IIdCompressor;
     readonly schema?: SchemaAndPolicy;
+    /**
+     * `true` when this context is encoding to or decoding from a summary blob.
+     * `false` when this context is for an op (or any other non-summary path,
+     * including utility encoders that aren't tied to persistence).
+     *
+     * @remarks
+     * Used to gate decode-time recovery behavior — for example, healing of
+     * unresolvable identifier IDs — that should only run when loading a
+     * (possibly broken) attach-summary blob, never when applying ops.
+     */
+    readonly isSummary: boolean;
+    /**
+     * If `true`, identifier values that the local id-compressor cannot resolve
+     * during decode are healed into deterministic stable UUIDs instead of
+     * throwing. See {@link FieldBatchEncodingContext.healUnresolvableIdentifiersOnDecode}.
+     * Only takes effect when `isSummary` is also `true`.
+     */
+    readonly healUnresolvableIdentifiersOnDecode?: boolean;
+    /**
+     * The SharedTree's shared-object id, used as input to the deterministic
+     * UUID derivation when {@link healUnresolvableIdentifiersOnDecode} triggers.
+     */
+    readonly sharedObjectId?: string;
 }
 export type ChangeFamilyCodec<TChange> = IJsonCodec<TChange, JsonCompatibleReadOnly, JsonCompatibleReadOnly, ChangeEncodingContext>;
 export interface ChangeFamilyEditor {

package/dist/core/change-family/changeFamily.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"changeFamily.d.ts","sourceRoot":"","sources":["../../../src/core/change-family/changeFamily.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE9E,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEnF,MAAM,WAAW,YAAY,CAAC,OAAO,SAAS,kBAAkB,EAAE,OAAO;IACxE,WAAW,CACV,eAAe,EAAE,MAAM,WAAW,EAClC,cAAc,EAAE,CAAC,MAAM,EAAE,YAAY,CAAC,OAAO,CAAC,KAAK,IAAI,GACrD,OAAO,CAAC;IAEX,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,OAAO,EAAE,qBAAqB,CAAC,CAAC;CAC9D;AAED,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC;CAClC;AAED,MAAM,MAAM,iBAAiB,CAAC,OAAO,IAAI,UAAU,CAClD,OAAO,EACP,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,CACrB,CAAC;AAEF,MAAM,WAAW,kBAAkB;IAClC;;;;;;;OAOG;IACH,gBAAgB,IAAI,IAAI,CAAC;IAEzB;;;;;;;OAOG;IACH,eAAe,IAAI,IAAI,CAAC;CACxB"}
+{"version":3,"file":"changeFamily.d.ts","sourceRoot":"","sources":["../../../src/core/change-family/changeFamily.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE9E,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAG3D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEnF,MAAM,WAAW,YAAY,CAAC,OAAO,SAAS,kBAAkB,EAAE,OAAO;IACxE,WAAW,CACV,eAAe,EAAE,MAAM,WAAW,EAClC,cAAc,EAAE,CAAC,MAAM,EAAE,YAAY,CAAC,OAAO,CAAC,KAAK,IAAI,GACrD,OAAO,CAAC;IAEX,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,OAAO,EAAE,qBAAqB,CAAC,CAAC;CAC9D;AAED,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC;IAClC;;;;;;;;;OASG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,mCAAmC,CAAC,EAAE,OAAO,CAAC;IACvD;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,MAAM,iBAAiB,CAAC,OAAO,IAAI,UAAU,CAClD,OAAO,EACP,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,CACrB,CAAC;AAEF,MAAM,WAAW,kBAAkB;IAClC;;;;;;;OAOG;IACH,gBAAgB,IAAI,IAAI,CAAC;IAEzB;;;;;;;OAOG;IACH,eAAe,IAAI,IAAI,CAAC;CACxB"}

package/dist/core/change-family/changeFamily.js.map

@@ -1 +1 @@
-{"version":3,"file":"changeFamily.js","sourceRoot":"","sources":["../../../src/core/change-family/changeFamily.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { IIdCompressor, SessionId } from \"@fluidframework/id-compressor\";\n\nimport type { ICodecFamily, IJsonCodec } from \"../../codec/index.js\";\nimport type { SchemaAndPolicy } from \"../../core/index.js\";\nimport type { JsonCompatibleReadOnly } from \"../../util/index.js\";\nimport type { ChangeRebaser, RevisionTag, TaggedChange } from \"../rebase/index.js\";\n\nexport interface ChangeFamily<TEditor extends ChangeFamilyEditor, TChange> {\n\tbuildEditor(\n\t\tmintRevisionTag: () => RevisionTag,\n\t\tchangeReceiver: (change: TaggedChange<TChange>) => void,\n\t): TEditor;\n\n\treadonly rebaser: ChangeRebaser<TChange>;\n\treadonly codecs: ICodecFamily<TChange, ChangeEncodingContext>;\n}\n\nexport interface ChangeEncodingContext {\n\treadonly originatorId: SessionId;\n\treadonly revision: RevisionTag | undefined;\n\treadonly idCompressor: IIdCompressor;\n\treadonly schema?: SchemaAndPolicy;\n}\n\nexport type ChangeFamilyCodec<TChange> = IJsonCodec<\n\tTChange,\n\tJsonCompatibleReadOnly,\n\tJsonCompatibleReadOnly,\n\tChangeEncodingContext\n>;\n\nexport interface ChangeFamilyEditor {\n\t/**\n\t * Must be called when a new transaction starts.\n\t *\n\t * Note: transactions are an optional feature. It is valid to make edits outside of a transaction.\n\t *\n\t * For each call to this function, a matching call to `exitTransaction` must be made at a later time.\n\t * Can be called repeatedly to indicate the start of nesting transactions.\n\t */\n\tenterTransaction(): void;\n\n\t/**\n\t * Must be called when a transaction ends.\n\t *\n\t * Note: transactions are an optional feature. It is valid to make edits outside of a transaction.\n\t *\n\t * For each call to this function, a matching call to `enterTransaction` must be made at an earlier time.\n\t * Can be called repeatedly to indicate the end of nesting transactions.\n\t */\n\texitTransaction(): void;\n}\n"]}
+{"version":3,"file":"changeFamily.js","sourceRoot":"","sources":["../../../src/core/change-family/changeFamily.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { IIdCompressor, SessionId } from \"@fluidframework/id-compressor\";\n\nimport type { ICodecFamily, IJsonCodec } from \"../../codec/index.js\";\nimport type { SchemaAndPolicy } from \"../../core/index.js\";\n// eslint-disable-next-line @typescript-eslint/no-unused-vars -- Referenced by doc comments\nimport type { FieldBatchEncodingContext } from \"../../feature-libraries/index.js\";\nimport type { JsonCompatibleReadOnly } from \"../../util/index.js\";\nimport type { ChangeRebaser, RevisionTag, TaggedChange } from \"../rebase/index.js\";\n\nexport interface ChangeFamily<TEditor extends ChangeFamilyEditor, TChange> {\n\tbuildEditor(\n\t\tmintRevisionTag: () => RevisionTag,\n\t\tchangeReceiver: (change: TaggedChange<TChange>) => void,\n\t): TEditor;\n\n\treadonly rebaser: ChangeRebaser<TChange>;\n\treadonly codecs: ICodecFamily<TChange, ChangeEncodingContext>;\n}\n\nexport interface ChangeEncodingContext {\n\treadonly originatorId: SessionId;\n\treadonly revision: RevisionTag | undefined;\n\treadonly idCompressor: IIdCompressor;\n\treadonly schema?: SchemaAndPolicy;\n\t/**\n\t * `true` when this context is encoding to or decoding from a summary blob.\n\t * `false` when this context is for an op (or any other non-summary path,\n\t * including utility encoders that aren't tied to persistence).\n\t *\n\t * @remarks\n\t * Used to gate decode-time recovery behavior — for example, healing of\n\t * unresolvable identifier IDs — that should only run when loading a\n\t * (possibly broken) attach-summary blob, never when applying ops.\n\t */\n\treadonly isSummary: boolean;\n\t/**\n\t * If `true`, identifier values that the local id-compressor cannot resolve\n\t * during decode are healed into deterministic stable UUIDs instead of\n\t * throwing. See {@link FieldBatchEncodingContext.healUnresolvableIdentifiersOnDecode}.\n\t * Only takes effect when `isSummary` is also `true`.\n\t */\n\treadonly healUnresolvableIdentifiersOnDecode?: boolean;\n\t/**\n\t * The SharedTree's shared-object id, used as input to the deterministic\n\t * UUID derivation when {@link healUnresolvableIdentifiersOnDecode} triggers.\n\t */\n\treadonly sharedObjectId?: string;\n}\n\nexport type ChangeFamilyCodec<TChange> = IJsonCodec<\n\tTChange,\n\tJsonCompatibleReadOnly,\n\tJsonCompatibleReadOnly,\n\tChangeEncodingContext\n>;\n\nexport interface ChangeFamilyEditor {\n\t/**\n\t * Must be called when a new transaction starts.\n\t *\n\t * Note: transactions are an optional feature. It is valid to make edits outside of a transaction.\n\t *\n\t * For each call to this function, a matching call to `exitTransaction` must be made at a later time.\n\t * Can be called repeatedly to indicate the start of nesting transactions.\n\t */\n\tenterTransaction(): void;\n\n\t/**\n\t * Must be called when a transaction ends.\n\t *\n\t * Note: transactions are an optional feature. It is valid to make edits outside of a transaction.\n\t *\n\t * For each call to this function, a matching call to `enterTransaction` must be made at an earlier time.\n\t * Can be called repeatedly to indicate the end of nesting transactions.\n\t */\n\texitTransaction(): void;\n}\n"]}

package/dist/core/tree/detachedFieldIndexCodecV1.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"detachedFieldIndexCodecV1.d.ts","sourceRoot":"","sources":["../../../src/core/tree/detachedFieldIndexCodecV1.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,sBAAsB,CAAC;AAEvE,OAAO,EAEN,KAAK,gBAAgB,EAGrB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,KAAK,EAAE,wBAAwB,EAAS,MAAM,8BAA8B,CAAC;AAgDpF,wBAAgB,8BAA8B,CAC7C,gBAAgB,EAAE,gBAAgB,EAClC,YAAY,EAAE,aAAa,GACzB,cAAc,CAAC,wBAAwB,CAAC,CAO1C"}
+{"version":3,"file":"detachedFieldIndexCodecV1.d.ts","sourceRoot":"","sources":["../../../src/core/tree/detachedFieldIndexCodecV1.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,sBAAsB,CAAC;AAEvE,OAAO,EAEN,KAAK,gBAAgB,EAGrB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,KAAK,EAAE,wBAAwB,EAAS,MAAM,8BAA8B,CAAC;AAkDpF,wBAAgB,8BAA8B,CAC7C,gBAAgB,EAAE,gBAAgB,EAClC,YAAY,EAAE,aAAa,GACzB,cAAc,CAAC,wBAAwB,CAAC,CAO1C"}

package/dist/core/tree/detachedFieldIndexCodecV1.js

@@ -44,6 +44,8 @@ class MajorCodec {
             originatorId: this.revisionTagCodec.localSessionId,
             idCompressor: this.idCompressor,
             revision: undefined,
+            // DetachedFieldIndex codecs are only used by the summarizer.
+            isSummary: true,
         });
     }
 }

package/dist/core/tree/detachedFieldIndexCodecV1.js.map

@@ -1 +1 @@
-{"version":3,"file":"detachedFieldIndexCodecV1.js","sourceRoot":"","sources":["../../../src/core/tree/detachedFieldIndexCodecV1.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,kEAA6D;AAI7D,kDAA4C;AAC5C,iDAK4B;AAE5B,yFAA+F;AAC/F,2FAAsF;AAGtF,MAAM,UAAU;IACf,YACkB,gBAAkC,EAClC,YAA2B;QAD3B,qBAAgB,GAAhB,gBAAgB,CAAkB;QAClC,iBAAY,GAAZ,YAAY,CAAe;IAC1C,CAAC;IAEG,MAAM,CAAC,KAAY;QACzB,IAAA,iBAAM,EAAC,KAAK,KAAK,SAAS,EAAE,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvE,MAAM,EAAE,GAAG,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/C;;;;;;;;;;;;;;;;WAgBG;QACH,IAAA,iBAAM,EACL,EAAE,KAAK,MAAM,IAAI,EAAE,IAAI,CAAC,EACxB,KAAK,CAAC,kEAAkE,CACxE,CAAC;QACF,OAAO,EAAE,CAAC;IACX,CAAC;IAEM,MAAM,CAAC,KAAyB;QACtC,IAAA,iBAAM,EACL,KAAK,KAAK,MAAM,IAAI,KAAK,IAAI,CAAC,EAC9B,KAAK,CAAC,kEAAkE,CACxE,CAAC;QACF,OAAO,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,EAAE;YAC1C,YAAY,EAAE,IAAI,CAAC,gBAAgB,CAAC,cAAc;YAClD,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,QAAQ,EAAE,SAAS;SACnB,CAAC,CAAC;IACJ,CAAC;CACD;AAED,SAAgB,8BAA8B,CAC7C,gBAAkC,EAClC,YAA2B;IAE3B,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAAC;IAClE,OAAO,IAAA,4EAAyC,EAC/C,UAAU,EACV,IAAA,gBAAK,EAAC,mEAA+B,CAAC,EAAE,CAAC,EACzC,4BAAiB,CACjB,CAAC;AACH,CAAC;AAVD,wEAUC","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 { IIdCompressor } from \"@fluidframework/id-compressor\";\n\nimport type { CodecAndSchema, IJsonCodec } from \"../../codec/index.js\";\nimport { brand } from \"../../util/index.js\";\nimport {\n\ttype EncodedRevisionTag,\n\ttype RevisionTagCodec,\n\ttype RevisionTag,\n\tRevisionTagSchema,\n} from \"../rebase/index.js\";\n\nimport { makeDetachedFieldIndexCodecFromMajorCodec } from \"./detachedFieldIndexCodecCommon.js\";\nimport { DetachedFieldIndexFormatVersion } from \"./detachedFieldIndexFormatCommon.js\";\nimport type { DetachedFieldSummaryData, Major } from \"./detachedFieldIndexTypes.js\";\n\nclass MajorCodec implements IJsonCodec<Major, EncodedRevisionTag> {\n\tpublic constructor(\n\t\tprivate readonly revisionTagCodec: RevisionTagCodec,\n\t\tprivate readonly idCompressor: IIdCompressor,\n\t) {}\n\n\tpublic encode(major: Major): EncodedRevisionTag {\n\t\tassert(major !== undefined, 0x88e /* Unexpected undefined revision */);\n\t\tconst id = this.revisionTagCodec.encode(major);\n\t\t/**\n\t\t * Preface: this codec is only used at summarization time (not for ops).\n\t\t * Note that the decode path must provide a session id in which to interpret the revision tag.\n\t\t * The revision associated with a detached root generally comes from the session which detaches that subtree,\n\t\t * which isn't generally the local session (nor is it available at decode time with the layering of the tree\n\t\t * package), despite decode using the local session id.\n\t\t *\n\t\t * This is made OK by enforcing that all ids on encode/decode are non-local, since local ids won't be interpretable\n\t\t * at decode time.\n\t\t * This assert is valid because the revision for an acked edit will have already been finalized, and a revision\n\t\t * for a local-only edit will be finalizable at summarization time (local edits can only occur on a summarizing client\n\t\t * if they're created while detached, and local ids made while detached are finalized before generating the attach summary).\n\t\t *\n\t\t * WARNING: the above is true when the whole container transitions from detached to attached,\n\t\t * but not when the container is already attached and it's just the shared-tree that is attaching.\n\t\t * The assert below will fail in such a scenario. This is addressed in the v2 codec.\n\t\t */\n\t\tassert(\n\t\t\tid === \"root\" || id >= 0,\n\t\t\t0x88f /* Expected final id on encode of detached field index revision */,\n\t\t);\n\t\treturn id;\n\t}\n\n\tpublic decode(major: EncodedRevisionTag): RevisionTag {\n\t\tassert(\n\t\t\tmajor === \"root\" || major >= 0,\n\t\t\t0x890 /* Expected final id on decode of detached field index revision */,\n\t\t);\n\t\treturn this.revisionTagCodec.decode(major, {\n\t\t\toriginatorId: this.revisionTagCodec.localSessionId,\n\t\t\tidCompressor: this.idCompressor,\n\t\t\trevision: undefined,\n\t\t});\n\t}\n}\n\nexport function makeDetachedNodeToFieldCodecV1(\n\trevisionTagCodec: RevisionTagCodec,\n\tidCompressor: IIdCompressor,\n): CodecAndSchema<DetachedFieldSummaryData> {\n\tconst majorCodec = new MajorCodec(revisionTagCodec, idCompressor);\n\treturn makeDetachedFieldIndexCodecFromMajorCodec(\n\t\tmajorCodec,\n\t\tbrand(DetachedFieldIndexFormatVersion.v1),\n\t\tRevisionTagSchema,\n\t);\n}\n"]}
+{"version":3,"file":"detachedFieldIndexCodecV1.js","sourceRoot":"","sources":["../../../src/core/tree/detachedFieldIndexCodecV1.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,kEAA6D;AAI7D,kDAA4C;AAC5C,iDAK4B;AAE5B,yFAA+F;AAC/F,2FAAsF;AAGtF,MAAM,UAAU;IACf,YACkB,gBAAkC,EAClC,YAA2B;QAD3B,qBAAgB,GAAhB,gBAAgB,CAAkB;QAClC,iBAAY,GAAZ,YAAY,CAAe;IAC1C,CAAC;IAEG,MAAM,CAAC,KAAY;QACzB,IAAA,iBAAM,EAAC,KAAK,KAAK,SAAS,EAAE,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvE,MAAM,EAAE,GAAG,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/C;;;;;;;;;;;;;;;;WAgBG;QACH,IAAA,iBAAM,EACL,EAAE,KAAK,MAAM,IAAI,EAAE,IAAI,CAAC,EACxB,KAAK,CAAC,kEAAkE,CACxE,CAAC;QACF,OAAO,EAAE,CAAC;IACX,CAAC;IAEM,MAAM,CAAC,KAAyB;QACtC,IAAA,iBAAM,EACL,KAAK,KAAK,MAAM,IAAI,KAAK,IAAI,CAAC,EAC9B,KAAK,CAAC,kEAAkE,CACxE,CAAC;QACF,OAAO,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,EAAE;YAC1C,YAAY,EAAE,IAAI,CAAC,gBAAgB,CAAC,cAAc;YAClD,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,QAAQ,EAAE,SAAS;YACnB,6DAA6D;YAC7D,SAAS,EAAE,IAAI;SACf,CAAC,CAAC;IACJ,CAAC;CACD;AAED,SAAgB,8BAA8B,CAC7C,gBAAkC,EAClC,YAA2B;IAE3B,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAAC;IAClE,OAAO,IAAA,4EAAyC,EAC/C,UAAU,EACV,IAAA,gBAAK,EAAC,mEAA+B,CAAC,EAAE,CAAC,EACzC,4BAAiB,CACjB,CAAC;AACH,CAAC;AAVD,wEAUC","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 { IIdCompressor } from \"@fluidframework/id-compressor\";\n\nimport type { CodecAndSchema, IJsonCodec } from \"../../codec/index.js\";\nimport { brand } from \"../../util/index.js\";\nimport {\n\ttype EncodedRevisionTag,\n\ttype RevisionTagCodec,\n\ttype RevisionTag,\n\tRevisionTagSchema,\n} from \"../rebase/index.js\";\n\nimport { makeDetachedFieldIndexCodecFromMajorCodec } from \"./detachedFieldIndexCodecCommon.js\";\nimport { DetachedFieldIndexFormatVersion } from \"./detachedFieldIndexFormatCommon.js\";\nimport type { DetachedFieldSummaryData, Major } from \"./detachedFieldIndexTypes.js\";\n\nclass MajorCodec implements IJsonCodec<Major, EncodedRevisionTag> {\n\tpublic constructor(\n\t\tprivate readonly revisionTagCodec: RevisionTagCodec,\n\t\tprivate readonly idCompressor: IIdCompressor,\n\t) {}\n\n\tpublic encode(major: Major): EncodedRevisionTag {\n\t\tassert(major !== undefined, 0x88e /* Unexpected undefined revision */);\n\t\tconst id = this.revisionTagCodec.encode(major);\n\t\t/**\n\t\t * Preface: this codec is only used at summarization time (not for ops).\n\t\t * Note that the decode path must provide a session id in which to interpret the revision tag.\n\t\t * The revision associated with a detached root generally comes from the session which detaches that subtree,\n\t\t * which isn't generally the local session (nor is it available at decode time with the layering of the tree\n\t\t * package), despite decode using the local session id.\n\t\t *\n\t\t * This is made OK by enforcing that all ids on encode/decode are non-local, since local ids won't be interpretable\n\t\t * at decode time.\n\t\t * This assert is valid because the revision for an acked edit will have already been finalized, and a revision\n\t\t * for a local-only edit will be finalizable at summarization time (local edits can only occur on a summarizing client\n\t\t * if they're created while detached, and local ids made while detached are finalized before generating the attach summary).\n\t\t *\n\t\t * WARNING: the above is true when the whole container transitions from detached to attached,\n\t\t * but not when the container is already attached and it's just the shared-tree that is attaching.\n\t\t * The assert below will fail in such a scenario. This is addressed in the v2 codec.\n\t\t */\n\t\tassert(\n\t\t\tid === \"root\" || id >= 0,\n\t\t\t0x88f /* Expected final id on encode of detached field index revision */,\n\t\t);\n\t\treturn id;\n\t}\n\n\tpublic decode(major: EncodedRevisionTag): RevisionTag {\n\t\tassert(\n\t\t\tmajor === \"root\" || major >= 0,\n\t\t\t0x890 /* Expected final id on decode of detached field index revision */,\n\t\t);\n\t\treturn this.revisionTagCodec.decode(major, {\n\t\t\toriginatorId: this.revisionTagCodec.localSessionId,\n\t\t\tidCompressor: this.idCompressor,\n\t\t\trevision: undefined,\n\t\t\t// DetachedFieldIndex codecs are only used by the summarizer.\n\t\t\tisSummary: true,\n\t\t});\n\t}\n}\n\nexport function makeDetachedNodeToFieldCodecV1(\n\trevisionTagCodec: RevisionTagCodec,\n\tidCompressor: IIdCompressor,\n): CodecAndSchema<DetachedFieldSummaryData> {\n\tconst majorCodec = new MajorCodec(revisionTagCodec, idCompressor);\n\treturn makeDetachedFieldIndexCodecFromMajorCodec(\n\t\tmajorCodec,\n\t\tbrand(DetachedFieldIndexFormatVersion.v1),\n\t\tRevisionTagSchema,\n\t);\n}\n"]}

package/dist/core/tree/detachedFieldIndexCodecV2.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"detachedFieldIndexCodecV2.d.ts","sourceRoot":"","sources":["../../../src/core/tree/detachedFieldIndexCodecV2.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,+BAA+B,CAAC;AAG7E,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,sBAAsB,CAAC;AACvE,OAAO,KAAK,EAAsB,gBAAgB,EAAe,MAAM,oBAAoB,CAAC;AAK5F,OAAO,KAAK,EAAE,wBAAwB,EAAS,MAAM,8BAA8B,CAAC;AAwCpF,wBAAgB,8BAA8B,CAC7C,gBAAgB,EAAE,gBAAgB,EAClC,YAAY,EAAE,aAAa,GACzB,cAAc,CAAC,wBAAwB,CAAC,CAO1C"}
+{"version":3,"file":"detachedFieldIndexCodecV2.d.ts","sourceRoot":"","sources":["../../../src/core/tree/detachedFieldIndexCodecV2.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,+BAA+B,CAAC;AAG7E,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,sBAAsB,CAAC;AACvE,OAAO,KAAK,EAAsB,gBAAgB,EAAe,MAAM,oBAAoB,CAAC;AAK5F,OAAO,KAAK,EAAE,wBAAwB,EAAS,MAAM,8BAA8B,CAAC;AA0CpF,wBAAgB,8BAA8B,CAC7C,gBAAgB,EAAE,gBAAgB,EAClC,YAAY,EAAE,aAAa,GACzB,cAAc,CAAC,wBAAwB,CAAC,CAO1C"}

package/dist/core/tree/detachedFieldIndexCodecV2.js

@@ -38,6 +38,8 @@ class MajorCodec {
             originatorId: this.revisionTagCodec.localSessionId,
             idCompressor: this.idCompressor,
             revision: undefined,
+            // DetachedFieldIndex codecs are only used by the summarizer.
+            isSummary: true,
         });
     }
 }

package/dist/core/tree/detachedFieldIndexCodecV2.js.map

@@ -1 +1 @@
-{"version":3,"file":"detachedFieldIndexCodecV2.js","sourceRoot":"","sources":["../../../src/core/tree/detachedFieldIndexCodecV2.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,kEAA6D;AAE7D,qEAAoE;AAKpE,yFAA+F;AAC/F,2FAAsF;AACtF,mFAA2E;AAG3E,MAAM,UAAU;IACf,YACkB,gBAAkC,EAClC,YAA2B;QAD3B,qBAAgB,GAAhB,gBAAgB,CAAkB;QAClC,iBAAY,GAAZ,YAAY,CAAe;IAC1C,CAAC;IAEG,MAAM,CAAC,KAAY;QACzB,IAAA,iBAAM,EAAC,KAAK,KAAK,SAAS,EAAE,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvE,MAAM,EAAE,GAAG,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAE/C,IAAI,EAAE,KAAK,MAAM,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;YAC7B;;;eAGG;YACH,IAAA,iBAAM,EAAC,KAAK,KAAK,MAAM,EAAE,KAAK,CAAC,qCAAqC,CAAC,CAAC;YACtE,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;YACjD,OAAO,IAAI,CAAC;QACb,CAAC;QACD,OAAO,EAAE,CAAC;IACX,CAAC;IAEM,MAAM,CAAC,KAAoC;QACjD,IAAA,iBAAM,EACL,KAAK,KAAK,MAAM,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,IAAA,qBAAU,EAAC,KAAK,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,EAClF,KAAK,CAAC,mDAAmD,CACzD,CAAC;QACF,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,IAAA,qBAAU,EAAC,KAAK,CAAC,EAAE,CAAC;YACpD,OAAO,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAC5C,CAAC;QACD,OAAO,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,EAAE;YAC1C,YAAY,EAAE,IAAI,CAAC,gBAAgB,CAAC,cAAc;YAClD,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,QAAQ,EAAE,SAAS;SACnB,CAAC,CAAC;IACJ,CAAC;CACD;AAED,SAAgB,8BAA8B,CAC7C,gBAAkC,EAClC,YAA2B;IAE3B,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAAC;IAClE,OAAO,IAAA,4EAAyC,EAC/C,UAAU,EACV,mEAA+B,CAAC,EAAE,EAClC,wDAAwB,CACxB,CAAC;AACH,CAAC;AAVD,wEAUC","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 { IIdCompressor, StableId } from \"@fluidframework/id-compressor\";\nimport { isStableId } from \"@fluidframework/id-compressor/internal\";\n\nimport type { CodecAndSchema, IJsonCodec } from \"../../codec/index.js\";\nimport type { EncodedRevisionTag, RevisionTagCodec, RevisionTag } from \"../rebase/index.js\";\n\nimport { makeDetachedFieldIndexCodecFromMajorCodec } from \"./detachedFieldIndexCodecCommon.js\";\nimport { DetachedFieldIndexFormatVersion } from \"./detachedFieldIndexFormatCommon.js\";\nimport { StableOrFinalRevisionTag } from \"./detachedFieldIndexFormatV2.js\";\nimport type { DetachedFieldSummaryData, Major } from \"./detachedFieldIndexTypes.js\";\n\nclass MajorCodec implements IJsonCodec<Major> {\n\tpublic constructor(\n\t\tprivate readonly revisionTagCodec: RevisionTagCodec,\n\t\tprivate readonly idCompressor: IIdCompressor,\n\t) {}\n\n\tpublic encode(major: Major): EncodedRevisionTag | StableId {\n\t\tassert(major !== undefined, 0xbfb /* Unexpected undefined revision */);\n\t\tconst id = this.revisionTagCodec.encode(major);\n\n\t\tif (id !== \"root\" && id < 0) {\n\t\t\t/**\n\t\t\t * This code path handles the case where the major revision is not finalized.\n\t\t\t * This can happen the SharedTree is being attached to an already attached container.\n\t\t\t */\n\t\t\tassert(major !== \"root\", 0xbfc /* Major revision cannot be 'root' */);\n\t\t\tconst long = this.idCompressor.decompress(major);\n\t\t\treturn long;\n\t\t}\n\t\treturn id;\n\t}\n\n\tpublic decode(major: EncodedRevisionTag | StableId): RevisionTag {\n\t\tassert(\n\t\t\tmajor === \"root\" || (typeof major === \"string\" && isStableId(major)) || major >= 0,\n\t\t\t0xbfd /* Expected root, stable, or final compressed id */,\n\t\t);\n\t\tif (typeof major === \"string\" && isStableId(major)) {\n\t\t\treturn this.idCompressor.recompress(major);\n\t\t}\n\t\treturn this.revisionTagCodec.decode(major, {\n\t\t\toriginatorId: this.revisionTagCodec.localSessionId,\n\t\t\tidCompressor: this.idCompressor,\n\t\t\trevision: undefined,\n\t\t});\n\t}\n}\n\nexport function makeDetachedNodeToFieldCodecV2(\n\trevisionTagCodec: RevisionTagCodec,\n\tidCompressor: IIdCompressor,\n): CodecAndSchema<DetachedFieldSummaryData> {\n\tconst majorCodec = new MajorCodec(revisionTagCodec, idCompressor);\n\treturn makeDetachedFieldIndexCodecFromMajorCodec(\n\t\tmajorCodec,\n\t\tDetachedFieldIndexFormatVersion.v2,\n\t\tStableOrFinalRevisionTag,\n\t);\n}\n"]}
+{"version":3,"file":"detachedFieldIndexCodecV2.js","sourceRoot":"","sources":["../../../src/core/tree/detachedFieldIndexCodecV2.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,kEAA6D;AAE7D,qEAAoE;AAKpE,yFAA+F;AAC/F,2FAAsF;AACtF,mFAA2E;AAG3E,MAAM,UAAU;IACf,YACkB,gBAAkC,EAClC,YAA2B;QAD3B,qBAAgB,GAAhB,gBAAgB,CAAkB;QAClC,iBAAY,GAAZ,YAAY,CAAe;IAC1C,CAAC;IAEG,MAAM,CAAC,KAAY;QACzB,IAAA,iBAAM,EAAC,KAAK,KAAK,SAAS,EAAE,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvE,MAAM,EAAE,GAAG,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAE/C,IAAI,EAAE,KAAK,MAAM,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;YAC7B;;;eAGG;YACH,IAAA,iBAAM,EAAC,KAAK,KAAK,MAAM,EAAE,KAAK,CAAC,qCAAqC,CAAC,CAAC;YACtE,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;YACjD,OAAO,IAAI,CAAC;QACb,CAAC;QACD,OAAO,EAAE,CAAC;IACX,CAAC;IAEM,MAAM,CAAC,KAAoC;QACjD,IAAA,iBAAM,EACL,KAAK,KAAK,MAAM,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,IAAA,qBAAU,EAAC,KAAK,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,EAClF,KAAK,CAAC,mDAAmD,CACzD,CAAC;QACF,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,IAAA,qBAAU,EAAC,KAAK,CAAC,EAAE,CAAC;YACpD,OAAO,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAC5C,CAAC;QACD,OAAO,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,EAAE;YAC1C,YAAY,EAAE,IAAI,CAAC,gBAAgB,CAAC,cAAc;YAClD,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,QAAQ,EAAE,SAAS;YACnB,6DAA6D;YAC7D,SAAS,EAAE,IAAI;SACf,CAAC,CAAC;IACJ,CAAC;CACD;AAED,SAAgB,8BAA8B,CAC7C,gBAAkC,EAClC,YAA2B;IAE3B,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAAC;IAClE,OAAO,IAAA,4EAAyC,EAC/C,UAAU,EACV,mEAA+B,CAAC,EAAE,EAClC,wDAAwB,CACxB,CAAC;AACH,CAAC;AAVD,wEAUC","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 { IIdCompressor, StableId } from \"@fluidframework/id-compressor\";\nimport { isStableId } from \"@fluidframework/id-compressor/internal\";\n\nimport type { CodecAndSchema, IJsonCodec } from \"../../codec/index.js\";\nimport type { EncodedRevisionTag, RevisionTagCodec, RevisionTag } from \"../rebase/index.js\";\n\nimport { makeDetachedFieldIndexCodecFromMajorCodec } from \"./detachedFieldIndexCodecCommon.js\";\nimport { DetachedFieldIndexFormatVersion } from \"./detachedFieldIndexFormatCommon.js\";\nimport { StableOrFinalRevisionTag } from \"./detachedFieldIndexFormatV2.js\";\nimport type { DetachedFieldSummaryData, Major } from \"./detachedFieldIndexTypes.js\";\n\nclass MajorCodec implements IJsonCodec<Major> {\n\tpublic constructor(\n\t\tprivate readonly revisionTagCodec: RevisionTagCodec,\n\t\tprivate readonly idCompressor: IIdCompressor,\n\t) {}\n\n\tpublic encode(major: Major): EncodedRevisionTag | StableId {\n\t\tassert(major !== undefined, 0xbfb /* Unexpected undefined revision */);\n\t\tconst id = this.revisionTagCodec.encode(major);\n\n\t\tif (id !== \"root\" && id < 0) {\n\t\t\t/**\n\t\t\t * This code path handles the case where the major revision is not finalized.\n\t\t\t * This can happen the SharedTree is being attached to an already attached container.\n\t\t\t */\n\t\t\tassert(major !== \"root\", 0xbfc /* Major revision cannot be 'root' */);\n\t\t\tconst long = this.idCompressor.decompress(major);\n\t\t\treturn long;\n\t\t}\n\t\treturn id;\n\t}\n\n\tpublic decode(major: EncodedRevisionTag | StableId): RevisionTag {\n\t\tassert(\n\t\t\tmajor === \"root\" || (typeof major === \"string\" && isStableId(major)) || major >= 0,\n\t\t\t0xbfd /* Expected root, stable, or final compressed id */,\n\t\t);\n\t\tif (typeof major === \"string\" && isStableId(major)) {\n\t\t\treturn this.idCompressor.recompress(major);\n\t\t}\n\t\treturn this.revisionTagCodec.decode(major, {\n\t\t\toriginatorId: this.revisionTagCodec.localSessionId,\n\t\t\tidCompressor: this.idCompressor,\n\t\t\trevision: undefined,\n\t\t\t// DetachedFieldIndex codecs are only used by the summarizer.\n\t\t\tisSummary: true,\n\t\t});\n\t}\n}\n\nexport function makeDetachedNodeToFieldCodecV2(\n\trevisionTagCodec: RevisionTagCodec,\n\tidCompressor: IIdCompressor,\n): CodecAndSchema<DetachedFieldSummaryData> {\n\tconst majorCodec = new MajorCodec(revisionTagCodec, idCompressor);\n\treturn makeDetachedFieldIndexCodecFromMajorCodec(\n\t\tmajorCodec,\n\t\tDetachedFieldIndexFormatVersion.v2,\n\t\tStableOrFinalRevisionTag,\n\t);\n}\n"]}

package/dist/feature-libraries/chunked-forest/basicChunk.d.ts

@@ -96,10 +96,27 @@ export declare class BasicChunkCursor extends SynchronousCursor implements Chunk
     atChunkRoot(): boolean;
     fork(): BasicChunkCursor;
     get mode(): CursorLocationType;
+    /**
+     * Asserts that the node-only stacks (`indexOfChunkStack` and `indexWithinChunkStack`) are in sync with `siblingStack`.
+     * Since `siblingStack` interleaves field and node levels while the node-only stacks are pushed/popped only on node-level transitions,
+     * their length should always equal the number of node levels traversed.
+     */
+    private assertChunkStacksMatchNodeDepth;
     getFieldKey(): FieldKey;
     private getStackedFieldKey;
     private getStackedNodeIndex;
-    private getStackedNode;
+    private getStackedChunkIndex;
+    private getStackedChunk;
+    /**
+     * Converts a {@link height}, which contains field and node levels, into the corresponding depth/index
+     * for the node-only stacks ({@link indexOfChunkStack} and {@link indexWithinChunkStack}), which are
+     * only pushed on node-level transitions.
+     *
+     * @param height - A depth in {@link siblingStack} to convert. Defaults to {@link siblingStack}'s
+     * current length, which gives the current depth of the node-only stacks.
+     * @returns `floor(height / 2)` — the number of node levels at or below the given stack height.
+     */
+    private getNodeOnlyHeightFromHeight;
     getFieldLength(): number;
     enterNode(index: number): void;
     getPath(prefix?: PathRootPrefix): UpPath;
@@ -116,6 +133,13 @@ export declare class BasicChunkCursor extends SynchronousCursor implements Chunk
     exitField(): void;
     exitNode(): void;
     private getNode;
+    /**
+     * Resolves the chunks that make up the field the cursor is currently in. At the root, this is
+     * {@link root} directly. Otherwise, the cursor must be in {@link CursorLocationType.Fields} mode,
+     * and the result is looked up on the parent node using the current field key.
+     *
+     * @returns The chunks that make up the field the cursor is currently in.
+     */
     private getField;
     get value(): Value;
     get type(): TreeType;

package/dist/feature-libraries/chunked-forest/basicChunk.d.ts.map

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

package/dist/feature-libraries/chunked-forest/basicChunk.js

@@ -130,16 +130,21 @@ class BasicChunkCursor extends treeCursorUtils_js_1.SynchronousCursor {
         if (this.nestedCursor !== undefined) {
             return this.nestedCursor.mode;
         }
-        // Compute the number of nodes deep the current depth is.
-        // We want the floor of the result, which can computed using a bitwise shift assuming the depth is less than 2^31, which seems safe.
-        // eslint-disable-next-line no-bitwise
-        const halfHeight = (this.siblingStack.length + 1) >> 1;
-        (0, internal_1.assert)(this.indexOfChunkStack.length === halfHeight, 0x51c /* unexpected indexOfChunkStack */);
-        (0, internal_1.assert)(this.indexWithinChunkStack.length === halfHeight, 0x51d /* unexpected indexWithinChunkStack */);
+        this.assertChunkStacksMatchNodeDepth();
         return this.siblingStack.length % 2 === 0
             ? 1 /* CursorLocationType.Fields */
             : 0 /* CursorLocationType.Nodes */;
     }
+    /**
+     * Asserts that the node-only stacks (`indexOfChunkStack` and `indexWithinChunkStack`) are in sync with `siblingStack`.
+     * Since `siblingStack` interleaves field and node levels while the node-only stacks are pushed/popped only on node-level transitions,
+     * their length should always equal the number of node levels traversed.
+     */
+    assertChunkStacksMatchNodeDepth() {
+        const halfHeight = this.getNodeOnlyHeightFromHeight();
+        (0, internal_1.assert)(this.indexOfChunkStack.length === halfHeight, 0x51c /* unexpected indexOfChunkStack */);
+        (0, internal_1.assert)(this.indexWithinChunkStack.length === halfHeight, 0x51d /* unexpected indexWithinChunkStack */);
+    }
     getFieldKey() {
         if (this.nestedCursor !== undefined) {
             return this.nestedCursor.getFieldKey();
@@ -157,9 +162,30 @@ class BasicChunkCursor extends treeCursorUtils_js_1.SynchronousCursor {
         (0, internal_1.assert)(height >= 0, 0x521 /* must not be above root */);
         return this.indexStack[height] ?? (0, internal_1.oob)();
     }
-    getStackedNode(height) {
-        const index = this.getStackedNodeIndex(height);
-        return this.siblingStack[height][index];
+    getStackedChunkIndex(height) {
+        (0, internal_1.assert)(height % 2 === 1, 0xcf3 /* must be node height */);
+        (0, internal_1.assert)(height >= 0, 0xcf4 /* must not be above root */);
+        return this.indexOfChunkStack[this.getNodeOnlyHeightFromHeight(height)] ?? (0, internal_1.oob)();
+    }
+    getStackedChunk(height) {
+        const index = this.getStackedChunkIndex(height);
+        const chunk = this.siblingStack[height][index];
+        (0, internal_1.debugAssert)(() => chunk instanceof BasicChunk || "only basic chunks are expected");
+        return chunk;
+    }
+    /**
+     * Converts a {@link height}, which contains field and node levels, into the corresponding depth/index
+     * for the node-only stacks ({@link indexOfChunkStack} and {@link indexWithinChunkStack}), which are
+     * only pushed on node-level transitions.
+     *
+     * @param height - A depth in {@link siblingStack} to convert. Defaults to {@link siblingStack}'s
+     * current length, which gives the current depth of the node-only stacks.
+     * @returns `floor(height / 2)` — the number of node levels at or below the given stack height.
+     */
+    getNodeOnlyHeightFromHeight(height = this.siblingStack.length) {
+        // The bitwise shift computes the floor, which is valid assuming the depth is less than 2^31, which seems safe.
+        // eslint-disable-next-line no-bitwise
+        return height >> 1;
     }
     getFieldLength() {
         if (this.nestedCursor !== undefined) {
@@ -256,6 +282,11 @@ class BasicChunkCursor extends treeCursorUtils_js_1.SynchronousCursor {
         (0, internal_1.assert)(this.mode === 0 /* CursorLocationType.Nodes */, 0x528 /* must be in nodes mode */);
         this.siblingStack.push(this.siblings);
         this.indexStack.push(this.index);
+        // Save the chunk array position of the current node. When siblings contain
+        // multi node chunks, the flat node index diverges from the array position,
+        // so getField needs this to locate the parent in the sibling array.
+        this.indexOfChunkStack.push(this.indexOfChunk);
+        this.indexWithinChunkStack.push(this.indexWithinChunk);
         // For fields, siblings are only used for key lookup and
         // nextField and which has arbitrary iteration order,
         // so making a array of just key here works.
@@ -263,6 +294,7 @@ class BasicChunkCursor extends treeCursorUtils_js_1.SynchronousCursor {
         // at the cost of an allocation here.
         this.index = 0;
         this.siblings = [key];
+        this.assertChunkStacksMatchNodeDepth();
     }
     nextField() {
         if (this.nestedCursor !== undefined) {
@@ -285,8 +317,11 @@ class BasicChunkCursor extends treeCursorUtils_js_1.SynchronousCursor {
         }
         this.siblingStack.push(this.siblings);
         this.indexStack.push(this.index);
+        this.indexOfChunkStack.push(this.indexOfChunk);
+        this.indexWithinChunkStack.push(this.indexWithinChunk);
         this.index = 0;
         this.siblings = [...fields.keys()]; // TODO: avoid this copy
+        this.assertChunkStacksMatchNodeDepth();
         return true;
     }
     seekNodes(offset) {
@@ -343,12 +378,11 @@ class BasicChunkCursor extends treeCursorUtils_js_1.SynchronousCursor {
         }
         this.siblingStack.push(this.siblings);
         this.indexStack.push(this.index);
-        this.indexOfChunkStack.push(this.indexOfChunk);
-        this.indexWithinChunkStack.push(this.indexWithinChunk);
         this.index = 0;
         this.siblings = siblings;
         this.indexOfChunk = 0;
         this.indexWithinChunk = 0;
+        this.assertChunkStacksMatchNodeDepth();
         this.initNestedCursor();
         return true;
     }
@@ -393,6 +427,12 @@ class BasicChunkCursor extends treeCursorUtils_js_1.SynchronousCursor {
         this.siblings =
             this.siblingStack.pop() ?? (0, internal_1.fail)(0xaf0 /* Unexpected siblingStack.length */);
         this.index = this.indexStack.pop() ?? (0, internal_1.fail)(0xaf1 /* Unexpected indexStack.length */);
+        this.indexOfChunk =
+            this.indexOfChunkStack.pop() ?? (0, internal_1.fail)(0xcf5 /* Unexpected indexOfChunkStack.length */);
+        this.indexWithinChunk =
+            this.indexWithinChunkStack.pop() ??
+                (0, internal_1.fail)(0xcf6 /* Unexpected indexWithinChunkStack.length */);
+        this.assertChunkStacksMatchNodeDepth();
     }
     exitNode() {
         if (this.nestedCursor !== undefined) {
@@ -405,22 +445,35 @@ class BasicChunkCursor extends treeCursorUtils_js_1.SynchronousCursor {
         this.siblings =
             this.siblingStack.pop() ?? (0, internal_1.fail)(0xaf2 /* Unexpected siblingStack.length */);
         this.index = this.indexStack.pop() ?? (0, internal_1.fail)(0xaf3 /* Unexpected indexStack.length */);
-        this.indexOfChunk =
-            this.indexOfChunkStack.pop() ?? (0, internal_1.fail)(0xaf4 /* Unexpected indexOfChunkStack.length */);
-        this.indexWithinChunk =
-            this.indexWithinChunkStack.pop() ??
-                (0, internal_1.fail)(0xaf5 /* Unexpected indexWithinChunkStack.length */);
+        // At the Fields level these aren't semantically used, but reset for consistent state
+        // (so a fully-iterated cursor matches a fresh cursor at the same logical position).
+        this.indexOfChunk = 0;
+        this.indexWithinChunk = 0;
+        this.assertChunkStacksMatchNodeDepth();
     }
     getNode() {
         (0, internal_1.assert)(this.mode === 0 /* CursorLocationType.Nodes */, 0x52f /* can only get node when in node */);
-        return this.siblings[this.index];
+        const chunk = this.siblings[this.indexOfChunk];
+        (0, internal_1.debugAssert)(() => chunk instanceof BasicChunk || "only basic chunks are expected");
+        return chunk;
     }
+    /**
+     * Resolves the chunks that make up the field the cursor is currently in. At the root, this is
+     * {@link root} directly. Otherwise, the cursor must be in {@link CursorLocationType.Fields} mode,
+     * and the result is looked up on the parent node using the current field key.
+     *
+     * @returns The chunks that make up the field the cursor is currently in.
+     */
     getField() {
         if (this.siblingStack.length === 0) {
             return this.root;
         }
         (0, internal_1.assert)(this.mode === 1 /* CursorLocationType.Fields */, 0x530 /* can only get field when in fields */);
-        const parent = this.getStackedNode(this.indexStack.length - 1);
+        // The parent node is the `BasicChunk` in the node array at the top of
+        // `siblingStack` while we are in `CursorLocationType.Fields` mode. We need the parent
+        // since a field's chunks are stored on the parent node's `BasicChunk.fields` map, not on
+        // the cursor itself.
+        const parent = this.getStackedChunk(this.siblingStack.length - 1);
         const key = this.getFieldKey();
         const field = parent.fields.get(key) ?? [];
         return field;