@fluidframework/tree 2.113.1 → 2.115.0

package/lib/util/compressedIds.js

@@ -2,6 +2,7 @@
  * 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";
@@ -92,6 +93,16 @@ export function tryDecodeEncodedIdWithoutSession(id, idCompressor) {
  * deterministic v5 UUID string — *not* a `StableId`, since that brand requires
  * v4, but still a valid identifier value; the `string` arm of the return type
  * covers this case.
+ *
+ * The recovery (heal) path only occurs because of a prior bug where non-finalized identifiers were
+ * written into summaries. When {@link IdentifierHealingConfig.logger} is supplied, a telemetry event
+ * is recorded on that path so heals can be observed in the wild. The error/throw path is intentionally
+ * not instrumented here: the thrown exception is expected to surface via the application's own error
+ * telemetry, and should never be silently swallowed.
+ *
+ * @param id - The op-space compressed ID to decode.
+ * @param idCompressor - The ID compressor used to normalize the ID.
+ * @param healing - Heal-on-decode configuration. Presence enables healing of non-final IDs.
  */
 export function forceDecodeEncodedIdWithoutSession(id, idCompressor, healing) {
     const decoded = tryDecodeEncodedIdWithoutSession(id, idCompressor);
@@ -100,7 +111,17 @@ export function forceDecodeEncodedIdWithoutSession(id, idCompressor, healing) {
     }
     // `id` is a non-final op-space compressed id.
     if (healing !== undefined) {
-        return uuidV5(`${healing.sharedObjectId}|${id}`, healingNamespace);
+        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);
+        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 { 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\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 */\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\treturn uuidV5(`${healing.sharedObjectId}|${id}`, healingNamespace);\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 * Used internally to prevent the use of this decoder in incremental chunks if it has a session id (which would be wrong in those chunks).\n\t */\n\tprotected 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 { 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"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/tree",
-  "version": "2.113.1",
+  "version": "2.115.0",
   "description": "Distributed tree",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -101,18 +101,17 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "~2.113.1",
-    "@fluidframework/container-runtime": "~2.113.1",
-    "@fluidframework/core-interfaces": "~2.113.1",
-    "@fluidframework/core-utils": "~2.113.1",
-    "@fluidframework/datastore-definitions": "~2.113.1",
-    "@fluidframework/driver-definitions": "~2.113.1",
-    "@fluidframework/id-compressor": "~2.113.1",
-    "@fluidframework/runtime-definitions": "~2.113.1",
-    "@fluidframework/runtime-utils": "~2.113.1",
-    "@fluidframework/shared-object-base": "~2.113.1",
-    "@fluidframework/telemetry-utils": "~2.113.1",
-    "@fluidframework/type-factory": "~2.113.1",
+    "@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",
     "@sinclair/typebox": "^0.34.13",
     "@tylerbu/sorted-btree-es6": "^2.1.1",
     "semver-ts": "^1.0.3",
@@ -122,20 +121,22 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
     "@biomejs/biome": "~2.4.5",
-    "@fluid-internal/mocha-test-setup": "~2.113.1",
-    "@fluid-private/stochastic-test-utils": "~2.113.1",
-    "@fluid-private/test-dds-utils": "~2.113.1",
-    "@fluid-private/test-drivers": "~2.113.1",
+    "@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-tools/benchmark": "^0.59.0",
     "@fluid-tools/build-cli": "^0.65.0",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.65.0",
-    "@fluidframework/container-definitions": "~2.113.1",
-    "@fluidframework/container-loader": "~2.113.1",
+    "@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/test-runtime-utils": "~2.113.1",
-    "@fluidframework/test-utils": "~2.113.1",
-    "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.111.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",
     "@microsoft/api-extractor": "7.58.1",
     "@types/diff": "^3.5.1",
     "@types/easy-table": "^0.0.32",
@@ -158,6 +159,9 @@
     "rimraf": "^6.1.3",
     "typescript": "~5.4.5"
   },
+  "comments": [
+    "Tree test builds and eslint depend on the corresponding ID Compressor test builds because Tree tests import its internal/test-utils export, which resolves to generated test output."
+  ],
   "fluidBuild": {
     "tasks": {
       "build:test:cjs": [
@@ -170,6 +174,10 @@
       ],
       "ci:build:docs": [
         "build:esnext"
+      ],
+      "eslint": [
+        "...",
+        "@fluidframework/id-compressor#build:test:esm"
       ]
     }
   },
@@ -178,7 +186,6 @@
     "entrypoint": "public"
   },
   "scripts": {
-    "api": "fluid-build . --task api",
     "bench": "cross-env FLUID_TEST_PERF_MODE=1 mocha --parallel --jobs 6",
     "bench-comment": "echo \"This package has the longest running benchmark suite, and also has a lot of test enumeration overhead which makes --parentProcess slow. Also --parallel doesn't support --parentProcess. These are several reasons to not use parent process on this specific package.\"",
     "bench:profile": "cross-env FLUID_TEST_PERF_MODE=1 mocha --v8-prof --v8-logfile=profile.log --v8-no-logfile-per-isolate --timeout 999999 --fgrep @ExecutionTime --reporter @fluid-tools/benchmark/dist/mocha/Reporter.js && node --prof-process profile.log > profile.txt && rimraf profile.log && echo See results in profile.txt",
@@ -189,10 +196,11 @@
     "build:commonjs": "fluid-build . --task commonjs",
     "build:compile": "fluid-build . --task compile",
     "build:docs": "api-extractor run --local",
+    "build:entrypoints": "fluid-build . --task build:entrypoints",
     "build:entrypoints:node10": "flub generate node10Entrypoints",
     "build:esnext": "tsc --project ./tsconfig.json",
     "build:genver": "gen-version",
-    "build:test": "npm run build:test:esm && npm run build:test:cjs",
+    "build:test": "concurrently npm:build:test:esm npm:build:test:cjs",
     "build:test:cjs": "fluid-tsc commonjs --project ./src/test/tsconfig.cjs.json",
     "build:test:esm": "tsc --project ./src/test/tsconfig.json",
     "check:are-the-types-wrong": "attw --pack . --exclude-entrypoints ./internal/test",

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

@@ -10,14 +10,31 @@ import type { SchemaAndPolicy } from "../../core/index.js";
 import type { IdentifierHealingConfig, JsonCompatibleReadOnly } from "../../util/index.js";
 import type { ChangeRebaser, RevisionTag, TaggedChange } from "../rebase/index.js";
 
-export interface ChangeFamily<TEditor extends ChangeFamilyEditor, TChange> {
+export type ProcessChangeFn<TChange, TChangeProcessingContext> =
+	TChangeProcessingContext extends never
+		? (change: TChange) => TChange
+		: (change: TChange, context: TChangeProcessingContext) => TChange;
+
+export interface ChangeFamily<
+	TEditor extends ChangeFamilyEditor,
+	TChange,
+	// For simplicity, may be a concrete ChangeFamily implementation such as
+	// ChangeFamilyFoo implements ChangeFamily<EditorFoo, ChangeFoo, ChangeFamilyFoo>
+	// to provide all details and helpers that processFn for ChangeFoo
+	// may require, but there is no requirement to follow that pattern.
+	TChangeProcessingContext = never,
+> {
 	buildEditor(
 		mintRevisionTag: () => RevisionTag,
 		changeReceiver: (change: TaggedChange<TChange>) => void,
 	): TEditor;
 
 	readonly rebaser: ChangeRebaser<TChange>;
-	readonly codecs: ICodecFamily<TChange, ChangeEncodingContext>;
+	readonly codecs: ICodecFamily<TChange, ChangeEncodingContext, ChangeDecodingContext>;
+
+	buildProcessor(
+		processFn: ProcessChangeFn<TChange, TChangeProcessingContext>,
+	): (change: TChange) => TChange;
 }
 
 export interface ChangeEncodingContext {
@@ -36,18 +53,29 @@ export interface ChangeEncodingContext {
 	 * (possibly broken) attach-summary blob, never when applying ops.
 	 */
 	readonly isSummary: boolean;
+}
+
+/**
+ * Context provided to change codecs when decoding.
+ * @remarks
+ * The same as {@link ChangeEncodingContext} except that it omits `schema` (only consulted when
+ * *encoding*, for schema-aware compression) and adds `healing` (only consulted when *decoding*, to
+ * recover unresolvable identifiers from a summary blob).
+ */
+export type ChangeDecodingContext = Omit<ChangeEncodingContext, "schema"> & {
 	/**
 	 * Heal-on-decode workaround configuration. See {@link IdentifierHealingConfig}.
 	 * Only takes effect when `isSummary` is also `true`.
 	 */
 	readonly healing?: IdentifierHealingConfig;
-}
+};
 
 export type ChangeFamilyCodec<TChange> = IJsonCodec<
 	TChange,
 	JsonCompatibleReadOnly,
 	JsonCompatibleReadOnly,
-	ChangeEncodingContext
+	ChangeEncodingContext,
+	ChangeDecodingContext
 >;
 
 export interface ChangeFamilyEditor {

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

@@ -5,11 +5,10 @@
 
 import type { TaggedChange } from "../rebase/index.js";
 
-import type { ChangeFamily, ChangeFamilyEditor } from "./changeFamily.js";
+import type { ChangeFamilyEditor } from "./changeFamily.js";
 
 export abstract class EditBuilder<TChange> implements ChangeFamilyEditor {
 	public constructor(
-		protected readonly changeFamily: ChangeFamily<ChangeFamilyEditor, TChange>,
 		private readonly changeReceiver: (change: TaggedChange<TChange>) => void,
 	) {}
 

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

@@ -7,6 +7,8 @@ export type {
 	ChangeFamily,
 	ChangeFamilyEditor,
 	ChangeEncodingContext,
+	ChangeDecodingContext,
 	ChangeFamilyCodec,
+	ProcessChangeFn,
 } from "./changeFamily.js";
 export { EditBuilder } from "./editBuilder.js";

package/src/core/index.ts

@@ -83,6 +83,7 @@ export {
 	CursorMarker,
 	isCursor,
 	DetachedFieldIndex,
+	type DetachedFieldSummaryData,
 	type ReadOnlyDetachedFieldIndex,
 	type DetachedFieldIndexCheckpoint,
 	type ForestRootId,
@@ -160,13 +161,15 @@ export {
 	SchemaFormatVersion,
 } from "./schema-stored/index.js";
 
-export {
-	type ChangeFamily,
-	type ChangeFamilyCodec,
-	type ChangeEncodingContext,
-	type ChangeFamilyEditor,
-	EditBuilder,
+export type {
+	ChangeFamily,
+	ChangeFamilyCodec,
+	ChangeEncodingContext,
+	ChangeDecodingContext,
+	ChangeFamilyEditor,
+	ProcessChangeFn,
 } from "./change-family/index.js";
+export { EditBuilder } from "./change-family/index.js";
 
 export {
 	areEqualChangeAtomIds,
@@ -179,6 +182,8 @@ export {
 	type GraphCommit,
 	CommitKind,
 	type CommitMetadata,
+	CommitOutcome,
+	type LocalCommitEvents,
 	type LocalChangeMetadata,
 	type RemoteChangeMetadata,
 	type ChangeMetadata,

package/src/core/rebase/index.ts

@@ -12,6 +12,8 @@ export {
 	type GraphCommit,
 	CommitKind,
 	type CommitMetadata,
+	CommitOutcome,
+	type LocalCommitEvents,
 	type LocalChangeMetadata,
 	type RemoteChangeMetadata,
 	type ChangeMetadata,

package/src/core/rebase/types.ts

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
+import type { Listenable } from "@fluidframework/core-interfaces";
 import type {
 	OpSpaceCompressedId,
 	SessionId,
@@ -271,6 +272,72 @@ export interface LocalChangeMetadata extends CommitMetadata {
 	 * ```
 	 */
 	readonly labels: TransactionLabels;
+
+	/**
+	 * Events related to a local change that has been applied.
+	 */
+	readonly events: Listenable<LocalCommitEvents>;
+}
+
+/**
+ * Events related to a local commit that has been applied.
+ * @sealed @alpha
+ */
+export interface LocalCommitEvents {
+	/**
+	 * Fired once a commit has been ordered by the sequencing service.
+	 * @param outcome - information about what changes from the commit were applied or not
+	 *
+	 * @remarks
+	 * Once a commit is sequenced, the following guarantees hold:
+	 * 1. The changes carried by the commit have been persisted and other peers are able to see them.
+	 * 2. There can be no more concurrent changes sequenced before this commit, which means this commit has reached its settled form.
+	 *
+	 * This event can be used by applications to inform the end user that their changes have been saved (`CommitOutcome.FullyApplied`) or rejected (`CommitOutcome.FullyDropped` and `CommitOutcome.NewContentOnly`).
+	 * It can also be used to queue up a new attempt at making the rejected changes. Note however that new edits must be made outside of the event callback.
+	 * @example Notifying the user of the outcome and allowing them to retry:
+	 * ```typescript
+	 * // Use `asAlpha` API to access the settled event API
+	 * const view = asAlpha(tree.viewWith(config));
+	 *
+	 * // Function to clear all contents of the tree, with a precondition that no changes have occurred.
+	 * const clearAllContents = () => {
+	 * 	view.runTransaction(
+	 * 		() => {
+	 * 			// Remove all contents at the root
+	 * 			view.root.removeRange();
+	 * 		},
+	 * 		{ preconditions: [{ type: "noChange" }] },
+	 * 	);
+	 * };
+	 *
+	 * // Register the logic for notifying the user of the outcome and allow them to retry
+	 *  view.events.on("changed", (metadata) => {
+	 * 	if (metadata.isLocal) {
+	 * 		metadata.events.on("settled", (outcome) => {
+	 * 			if (outcome === CommitOutcome.FullyApplied) {
+	 * 				alert("Clear operation succeeded.");
+	 * 			} else {
+	 * 				const shouldTryAgain = confirm(
+	 * 					"The contents have changed. Do you still want to clear everything?",
+	 * 				);
+	 * 				if (shouldTryAgain) {
+	 * 					// It is invalid to make edits during the event callback, so we schedule the retry to occur asynchronously.
+	 * 					setTimeout(clearAllContents);
+	 * 				} else {
+	 * 					alert("Clear operation aborted.");
+	 * 				}
+	 * 			}
+	 * 		});
+	 * 	}
+	 * });
+	 *
+	 * // First attempt to clear all contents.
+	 * // This will synchronously trigger the changed "event" and register the listener for the settled event.
+	 * clearAllContents();
+	 * ```
+	 */
+	settled(outcome: CommitOutcome): void;
 }
 
 /**
@@ -311,6 +378,52 @@ export interface LabelTree {
  */
 export type TransactionLabels = Set<unknown> & { tree?: LabelTree };
 
+/**
+ * Details about what changes from a commit were applied or not.
+ * @alpha
+ */
+export enum CommitOutcome {
+	/**
+	 * All of the changes in the commit were applied.
+	 */
+	FullyApplied,
+	/**
+	 * None of the changes in the commit were applied.
+	 * @remarks
+	 * This occurs when an implicit constraint has been violated.
+	 * Implicit constraints are those that are automatically enforced by SharedTree on all changes.
+	 *
+	 * Such a violation typically arises in one of two scenarios:
+	 * 1. A schema change conflicts with a concurrent data or schema change that was sequenced before it.
+	 * 2. A data change conflicts with a concurrent schema change that was sequenced before it.
+	 */
+	FullyDropped,
+	/**
+	 * Only the creation of new content was applied.
+	 * All other changes (including the insertion and/or modification of the new content) were dropped.
+	 * @remarks
+	 * This occurs when at least one explicit constraint has been violated
+	 * (and no implicit constraints were violated.)
+	 *
+	 * Explicit constraints are those that are explicitly added
+	 * through {@link RunTransactionParamsAlpha.preconditions | preconditions}
+	 * or {@link TransactionCallbackStatusAlpha.preconditionsOnRevert | preconditionsOnRevert}.
+	 *
+	 * The new content may be edited (and potentially inserted) by subsequent commits,
+	 * assuming those commits are not themselves subject to constraint violations.
+	 * Note that, if left uninserted, new content will eventually be garbage-collected from the document.
+	 *
+	 * Applications typically choose to treat this outcome as equivalent to {@link CommitOutcome.FullyDropped | FullyDropped}
+	 * and, when reattempting the change, generate a different copy of the new content if any.
+	 *
+	 * @privateRemarks
+	 * New content is preserved so that subsequent commits that reference it without having to carry their own copies of it.
+	 * This can become expensive: one extra copy per subsequent commit, included in both in cases where we know the prior commit was dropped and in cases where we don't yet know.
+	 * We could instead drop all subsequent commits that reference the new content, but that would create a greater risk of data loss.
+	 */
+	NewContentOnly,
+}
+
 /**
  * Information about a change that has been applied by a remote client.
  * @sealed @alpha

package/src/core/tree/delta.ts

@@ -67,7 +67,7 @@ import type { TreeChunk } from "./chunk.js";
  */
 
 /**
- * Represents the change made to a document.
+ * A change made to a document.
  * Immutable, therefore safe to retain for async processing.
  */
 export interface Root<TTrees = ProtoNodes> {
@@ -122,20 +122,50 @@ export interface Root<TTrees = ProtoNodes> {
 export type ProtoNodes = TreeChunk;
 
 /**
- * Represents a change being made to a part of the document tree.
+ * A change to a contiguous range of a field,
+ * including nested changes described by {@link Mark.fields}.
+ *
+ * @remarks
+ * See {@link FieldChanges} for how these marks are applied to a field.
+ *
+ * The presence of {@link Mark.attach} and {@link Mark.detach} determines the kind of change:
+ *
+ * - Retain (neither `attach` nor `detach` are set): retains `count` existing nodes.
+ * When `count` is `1`, `fields` may describe nested changes to the retained node.
+ * - Detach (`detach` only): removes `count` existing nodes.
+ * When `count` is `1`, `fields` may describe nested changes to the detached node.
+ * - Attach (`attach` only): inserts `count` new nodes.
+ * `fields` must be undefined.
+ * - Replace (both `attach` and `detach`): replaces `count` existing nodes with `count` attached
+ * nodes.
+ * When `count` is `1`, `fields` may describe nested changes to the detached node.
  */
 export interface Mark {
 	/**
-	 * The number of nodes affected.
-	 * When `isAttachMark(mark)` is true, this is the number of new nodes being attached.
-	 * When `isAttachMark(mark)` is false, this the number of existing nodes affected.
-	 * Must be 1 when `fields` is populated.
+	 * The number of existing nodes affected, attached nodes added, or both, according to the
+	 * combination of {@link Mark.attach} and {@link Mark.detach}.
+	 * Must be `1` when {@link Mark.fields} is populated.
+	 * @remarks
+	 * The size of the attached content is never inferred from what is attached: it must be exactly `count`.
+	 * This means that a single mark can represent replacing a run of `count` nodes with `count` new nodes,
+	 * but cannot replace a run of one length with a run of another length.
+	 * Such edits require multiple marks.
+	 *
+	 * Must be a positive integer.
+	 * Marks with a count of `0` are no-ops and should be omitted from {@link FieldChanges}.
 	 */
 	readonly count: number;
 
 	/**
-	 * Modifications to the pre-existing content.
-	 * Must be undefined when `attach` is set but `detach` is not.
+	 * Nested changes to pre-existing content.
+	 * @remarks
+	 * If {@link Mark.detach} is set, these changes apply to the node being detached.
+	 * Otherwise, they apply to the retained node.
+	 *
+	 * May only be set when this mark applies to exactly one pre-existing node.
+	 * Therefore, `fields` must be undefined if:
+	 * - {@link Mark.attach} is set and {@link Mark.detach} is not: in this case there are no pre-existing nodes.
+	 * - {@link Mark.count} is not 1: in this case there is not exactly one node to modify.
 	 */
 	readonly fields?: FieldMap;
 
@@ -154,54 +184,70 @@ export interface Mark {
  * A globally unique ID for a node in a detached field.
  */
 export interface DetachedNodeId {
+	/** Revision in which the ID was allocated, if applicable. */
 	readonly major?: RevisionTag;
+	/** Identifier within the scope of {@link DetachedNodeId.major}. */
 	readonly minor: number;
 }
 
 export type FieldMap = ReadonlyMap<FieldKey, FieldChanges>;
 
 /**
- * Represents changes made to a detached node
+ * Changes made to a detached node.
  */
 export interface DetachedNodeChanges {
+	/** ID of the detached node to modify. */
 	readonly id: DetachedNodeId;
+	/** Changes to the node's fields. */
 	readonly fields: FieldMap;
 }
 
 /**
- * Represents the creation of detached nodes.
+ * The creation of detached nodes.
  *
  * Tree creation is idempotent: if a tree with the same ID already exists,
  * then this build is ignored in favor of the existing tree.
  */
 export interface DetachedNodeBuild<TTrees = ProtoNodes> {
+	/** ID assigned to the first node in {@link DetachedNodeBuild.trees}. */
 	readonly id: DetachedNodeId;
+	/** Nodes to create, assigned consecutive IDs by incrementing {@link DetachedNodeId.minor}. */
 	readonly trees: TTrees;
 }
 
 /**
- * Represents the destruction of detached nodes
+ * The destruction of detached nodes.
  */
 export interface DetachedNodeDestruction {
+	/** ID of the first detached node to destroy. */
 	readonly id: DetachedNodeId;
+	/** Number of consecutively identified nodes to destroy. */
 	readonly count: number;
 }
 
 /**
- * Represents a detached node being assigned a new `DetachedNodeId`.
+ * A detached node being assigned a new `DetachedNodeId`.
  */
 export interface DetachedNodeRename {
+	/** Number of consecutively identified nodes to rename. */
 	readonly count: number;
+	/** Current ID of the first node. */
 	readonly oldId: DetachedNodeId;
+	/** New ID for the first node. */
 	readonly newId: DetachedNodeId;
 }
 
 export interface FieldChanges {
 	/**
-	 * Represents a list of changes to the nodes in the field.
-	 * The index of each mark within the range of nodes, before
-	 * applying any of the changes, is not represented explicitly.
-	 * It corresponds to the sum of `mark.count` values for all previous marks for which `isAttachMark(mark)` is false.
+	 * A list of changes to the nodes in the field.
+	 * @remarks
+	 * This includes changes to the field's nodes and nested changes to those nodes' fields.
+	 *
+	 * The index at which each mark applies is implicit. Marks are applied in order, advancing the
+	 * index according to the kind of {@link Mark} and its {@link Mark.count}.
+	 *
+	 * Because this describes changes rather than content, untouched nodes after the final mark are
+	 * implicitly retained. This is equivalent to a trailing retain mark with the relevant count.
 	 */
 	readonly marks: readonly Mark[];
 }