@fluidframework/tree 2.90.0-378676 → 2.90.0

package/.vscode/settings.json

@@ -4,12 +4,13 @@
 	// Also for unknown (but likely related reasons) this cannot be just "lib/test" which is used in the config.
 	// This is not limited to "spec.js" so that benchmarks are included (which will be run in correctness mode).
 	"mochaExplorer.files": ["lib/test/**/*.*js"],
-	// "pruneFiles" is disabled because it causesd "source-map-support/register" to give `Unknown file extension ".ts"` errors.
+	// "pruneFiles" is disabled because it breaks some imports.
 	// "mochaExplorer.pruneFiles": true,
-	"mochaExplorer.require": [
-		"node_modules/@fluid-internal/mocha-test-setup/dist/index.js",
-		"source-map-support/register",
-	],
+	// Parallel testing disabled because of AB#59690.
+	// "mochaExplorer.parallel": true,
+	// We have moderately high test setup overhead, so tons of jobs doesn't work well.
+	// Less than 4 got slower results, and more did not offer any significant gains.
+	"mochaExplorer.jobs": 4,
 	"mochaExplorer.configFile": ".mocharc.cjs",
 	"mochaExplorer.timeout": 999999,
 	// This extension appears to invoke mocha programmatically, meaning that the enablement of this option in the common

package/CHANGELOG.md

@@ -1,5 +1,100 @@
 # @fluidframework/tree
 
+## 2.90.0
+
+### Minor Changes
+
+- Add alpha TextAsTree domain for collaboratively editable text ([#26568](https://github.com/microsoft/FluidFramework/pull/26568)) [06736bd81de](https://github.com/microsoft/FluidFramework/commit/06736bd81dea4c8e44cb13304f471a7b1bca42bd)
+
+  A newly exported `TextAsTree` alpha namespace has been added with an initial version of collaboratively editable text.
+  Users of SharedTree can add `TextAsTree.Tree` nodes to their tree to experiment with it.
+
+- Added new TreeAlpha.context(node) API ([#26432](https://github.com/microsoft/FluidFramework/pull/26432)) [ffa62f45e2c](https://github.com/microsoft/FluidFramework/commit/ffa62f45e2ca6c6106c67ed94f69359336823516)
+
+  This release introduces a node-scoped context that works for both hydrated and [unhydrated](https://fluidframework.com/docs/api/fluid-framework/unhydrated-typealias) [TreeNodes](https://fluidframework.com/docs/api/fluid-framework/treenode-class).
+  The new `TreeContextAlpha` interface exposes `runTransaction` / `runTransactionAsync` methods and an `isBranch()` type guard.
+  `TreeBranchAlpha` now extends `TreeContextAlpha`, so you can keep using branch APIs when available.
+
+  #### Migration
+
+  If you previously used `TreeAlpha.branch(node)` to discover a branch, switch to `TreeAlpha.context(node)` and check `isBranch()`:
+
+  ```ts
+  import { TreeAlpha } from "@fluidframework/tree/alpha";
+
+  const context = TreeAlpha.context(node);
+  if (context.isBranch()) {
+    // Same branch APIs as before
+    context.fork();
+  }
+  ```
+
+  `TreeAlpha.branch(node)` is now deprecated.
+  Prefer the context API above.
+
+  #### New transaction entry point
+
+  You can now run transactions from a node context, regardless of whether the node is hydrated:
+
+  ```ts
+  // A synchronous transaction without a return value
+  const context = TreeAlpha.context(node);
+  context.runTransaction(() => {
+    node.count += 1;
+  });
+  ```
+
+  ```ts
+  // An asynchronous transaction with a return value
+  const context = TreeAlpha.context(node);
+  const result = await context.runTransactionAsync(async () => {
+    await doWork(node);
+    return { value: node.foo };
+  });
+  ```
+
+- Promote checkSchemaCompatibilitySnapshots to beta ([#26288](https://github.com/microsoft/FluidFramework/pull/26288)) [eb4ef62672d](https://github.com/microsoft/FluidFramework/commit/eb4ef62672d33f6a903e3726b58d1f65c24d9150)
+
+  [`checkSchemaCompatibilitySnapshots`](https://fluidframework.com/docs/api/fluid-framework#checkschemacompatibilitysnapshots-function) has been promoted to `@beta`.
+  It is recommended that all SharedTree applications use this API to write schema compatibility tests.
+
+  Usage should look something like:
+
+  ```typescript
+  import fs from "node:fs";
+  import path from "node:path";
+
+  import { snapshotSchemaCompatibility } from "@fluidframework/tree/beta";
+
+  // The TreeViewConfiguration the application uses, which contains the application's schema.
+  import { treeViewConfiguration } from "./schema.js";
+  // The next version of the application which will be released.
+  import { packageVersion } from "./version.js";
+
+  // Provide some way to run the check in "update" mode when updating snapshots is intended.
+  const regenerateSnapshots = process.argv.includes("--snapshot");
+
+  // Setup the actual test. In this case using Mocha syntax.
+  describe("schema", () => {
+    it("schema compatibility", () => {
+      // Select a path to save the snapshots in.
+      // This will depend on how your application organizes its test data.
+      const snapshotDirectory = path.join(
+        import.meta.dirname,
+        "../../../src/test/snapshotCompatibilityCheckerExample/schema-snapshots",
+      );
+      snapshotSchemaCompatibility({
+        snapshotDirectory,
+        fileSystem: { ...fs, ...path },
+        version: packageVersion,
+        minVersionForCollaboration: "2.0.0",
+        schema: treeViewConfiguration,
+        mode: regenerateSnapshots ? "update" : "assert",
+      });
+    });
+  });
+  ```
+
 ## 2.83.0
 
 ### Minor Changes

package/README.md

@@ -53,7 +53,7 @@ API documentation for **@fluidframework/tree** is available at <https://fluidfra
 
 ## Status
 
-Notable considerations that users should be wary of:
+Notable considerations that users should be aware of:
 
 -   The persisted format is stable: documents created with released versions 2.0.0 or greater of this package are fully supported long term.
 -   All range changes are currently atomized.

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

@@ -216,16 +216,16 @@ export type CreateIndependentTreeAlphaOptions = ForestOptions & ((IndependentVie
 export function createIndependentTreeBeta<const TSchema extends ImplicitFieldSchema>(options?: ForestOptions): ViewableTree;
 
 // @alpha
-export function createSimpleTreeIndex<TFieldSchema extends ImplicitFieldSchema, TKey extends TreeIndexKey, TValue>(view: TreeView<TFieldSchema>, indexer: (schema: TreeNodeSchema) => string | undefined, getValue: (nodes: TreeIndexNodes<TreeNode>) => TValue, isKeyValid: (key: TreeIndexKey) => key is TKey): SimpleTreeIndex<TKey, TValue>;
+export function createTreeIndex<TFieldSchema extends ImplicitFieldSchema, TKey extends TreeIndexKey, TValue>(view: TreeView<TFieldSchema>, indexer: (schema: TreeNodeSchema) => string | undefined, getValue: (nodes: TreeIndexNodes<TreeNode>) => TValue, isKeyValid: (key: TreeIndexKey) => key is TKey): TreeIndex<TKey, TValue>;
 
 // @alpha
-export function createSimpleTreeIndex<TFieldSchema extends ImplicitFieldSchema, TKey extends TreeIndexKey, TValue, TSchema extends TreeNodeSchema>(view: TreeView<TFieldSchema>, indexer: (schema: TSchema) => string | undefined, getValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue, isKeyValid: (key: TreeIndexKey) => key is TKey, indexableSchema: readonly TSchema[]): SimpleTreeIndex<TKey, TValue>;
+export function createTreeIndex<TFieldSchema extends ImplicitFieldSchema, TKey extends TreeIndexKey, TValue, TSchema extends TreeNodeSchema>(view: TreeView<TFieldSchema>, indexer: (schema: TSchema) => string | undefined, getValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue, isKeyValid: (key: TreeIndexKey) => key is TKey, indexableSchema: readonly TSchema[]): TreeIndex<TKey, TValue>;
 
 // @alpha
-export function createSimpleTreeIndex<TFieldSchema extends ImplicitFieldSchema, TKey extends TreeIndexKey, TValue>(view: TreeView<TFieldSchema>, indexer: Map<TreeNodeSchema, string>, getValue: (nodes: TreeIndexNodes<TreeNode>) => TValue, isKeyValid: (key: TreeIndexKey) => key is TKey): SimpleTreeIndex<TKey, TValue>;
+export function createTreeIndex<TFieldSchema extends ImplicitFieldSchema, TKey extends TreeIndexKey, TValue>(view: TreeView<TFieldSchema>, indexer: Map<TreeNodeSchema, string>, getValue: (nodes: TreeIndexNodes<TreeNode>) => TValue, isKeyValid: (key: TreeIndexKey) => key is TKey): TreeIndex<TKey, TValue>;
 
 // @alpha
-export function createSimpleTreeIndex<TFieldSchema extends ImplicitFieldSchema, TKey extends TreeIndexKey, TValue, TSchema extends TreeNodeSchema>(view: TreeView<TFieldSchema>, indexer: Map<TreeNodeSchema, string>, getValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue, isKeyValid: (key: TreeIndexKey) => key is TKey, indexableSchema: readonly TSchema[]): SimpleTreeIndex<TKey, TValue>;
+export function createTreeIndex<TFieldSchema extends ImplicitFieldSchema, TKey extends TreeIndexKey, TValue, TSchema extends TreeNodeSchema>(view: TreeView<TFieldSchema>, indexer: Map<TreeNodeSchema, string>, getValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue, isKeyValid: (key: TreeIndexKey) => key is TKey, indexableSchema: readonly TSchema[]): TreeIndex<TKey, TValue>;
 
 // @alpha
 export function decodeSchemaCompatibilitySnapshot(encodedSchema: JsonCompatibleReadOnly, validator?: FormatValidator): SimpleTreeSchema;
@@ -462,7 +462,7 @@ export interface ICodecOptions {
 }
 
 // @alpha
-export type IdentifierIndex = SimpleTreeIndex<string, TreeNode>;
+export type IdentifierIndex = TreeIndex<string, TreeNode>;
 
 // @public
 export type ImplicitAllowedTypes = AllowedTypes | TreeNodeSchema;
@@ -711,6 +711,12 @@ export enum KeyEncodingOptions {
     usePropertyKeys = "usePropertyKeys"
 }
 
+// @alpha @sealed
+export interface LabelTree {
+    label: unknown;
+    sublabels: LabelTree[];
+}
+
 // @public
 export type LazyItem<Item = unknown> = Item | (() => Item);
 
@@ -730,6 +736,7 @@ export interface LocalChangeMetadata extends CommitMetadata {
     getRevertible(onDisposed?: (revertible: RevertibleAlpha) => void): RevertibleAlpha | undefined;
     readonly isLocal: true;
     readonly label?: unknown;
+    readonly labels: TransactionLabels;
 }
 
 // @public @sealed
@@ -900,6 +907,7 @@ export interface RemoteChangeMetadata extends CommitMetadata {
     readonly getRevertible?: undefined;
     readonly isLocal: false;
     readonly label?: undefined;
+    readonly labels: TransactionLabels;
 }
 
 // @alpha
@@ -1110,7 +1118,6 @@ export interface SharedTreeFormatOptions {
 
 // @alpha @input
 export interface SharedTreeOptions extends SharedTreeOptionsBeta, Partial<CodecWriteOptions>, Partial<SharedTreeFormatOptions> {
-    readonly enableDetachedRootEditing?: boolean;
     readonly enableSharedBranches?: boolean;
     shouldEncodeIncrementally?: IncrementalEncodingPolicy;
 }
@@ -1184,9 +1191,6 @@ export interface SimpleRecordNodeSchema<Type extends SchemaType = SchemaType, ou
     readonly simpleAllowedTypes: ReadonlyMap<string, SimpleAllowedTypeAttributes<Type>>;
 }
 
-// @alpha
-export type SimpleTreeIndex<TKey extends TreeIndexKey, TValue> = TreeIndex<TKey, TValue>;
-
 // @alpha @sealed
 export interface SimpleTreeSchema<Type extends SchemaType = SchemaType> {
     readonly definitions: ReadonlyMap<string, SimpleNodeSchema<Type>>;
@@ -1198,7 +1202,7 @@ export function singletonSchema<TScope extends string, TName extends string | nu
     readonly value: TName;
 }, Record<string, never>, true, Record<string, never>, undefined>;
 
-// @alpha @input
+// @beta @input
 export interface SnapshotFileSystem {
     join(parentPath: string, childPath: string): string;
     mkdirSync(dir: string, options: {
@@ -1211,10 +1215,10 @@ export interface SnapshotFileSystem {
     }): void;
 }
 
-// @alpha
+// @beta
 export function snapshotSchemaCompatibility(options: SnapshotSchemaCompatibilityOptions): void;
 
-// @alpha @input
+// @beta @input
 export interface SnapshotSchemaCompatibilityOptions {
     readonly fileSystem: SnapshotFileSystem;
     readonly minVersionForCollaboration: string;
@@ -1454,17 +1458,32 @@ export namespace TableSchema {
     }
 }
 
+// @alpha
+export namespace TextAsTree {
+    export interface Members {
+        characterCount(): number;
+        characters(): Iterable<string>;
+        charactersCopy(): string[];
+        fullString(): string;
+        insertAt(index: number, additionalCharacters: string): void;
+        removeRange(startIndex: number | undefined, endIndex: number | undefined): void;
+    }
+    export interface Statics {
+        fromString(value: string): Tree;
+    }
+    const Tree: Statics & TreeNodeSchema<"com.fluidframework.text.Text", NodeKind, Members & TreeNode & WithType<"com.fluidframework.text.Text", NodeKind, unknown>, never, false>;
+    export type Tree = Members & TreeNode & WithType<"com.fluidframework.text.Text">;
+}
+
 // @alpha
 export function trackDirtyNodes(view: TreeViewAlpha<ImplicitFieldSchema>, dirty: DirtyTreeMap): () => void;
 
 // @alpha
-export type TransactionCallbackStatus<TSuccessValue, TFailureValue> = ({
+export type TransactionCallbackStatus<TSuccessValue, TFailureValue> = ((WithValue<TSuccessValue> & {
     rollback?: false;
-    value: TSuccessValue;
-} | {
+}) | (WithValue<TFailureValue> & {
     rollback: true;
-    value: TFailureValue;
-}) & {
+})) & {
     preconditionsOnRevert?: readonly TransactionConstraintAlpha[];
 };
 
@@ -1474,6 +1493,11 @@ export type TransactionConstraint = NodeInDocumentConstraint;
 // @alpha @sealed
 export type TransactionConstraintAlpha = TransactionConstraint | NoChangeConstraint;
 
+// @alpha @sealed
+export type TransactionLabels = Set<unknown> & {
+    tree?: LabelTree;
+};
+
 // @alpha
 export type TransactionResult = Omit<TransactionResultSuccess<unknown>, "value"> | Omit<TransactionResultFailed<unknown>, "value">;
 
@@ -1481,15 +1505,13 @@ export type TransactionResult = Omit<TransactionResultSuccess<unknown>, "value">
 export type TransactionResultExt<TSuccessValue, TFailureValue> = TransactionResultSuccess<TSuccessValue> | TransactionResultFailed<TFailureValue>;
 
 // @alpha
-export interface TransactionResultFailed<TFailureValue> {
+export interface TransactionResultFailed<TFailureValue> extends WithValue<TFailureValue> {
     success: false;
-    value: TFailureValue;
 }
 
 // @alpha
-export interface TransactionResultSuccess<TSuccessValue> {
+export interface TransactionResultSuccess<TSuccessValue> extends WithValue<TSuccessValue> {
     success: true;
-    value: TSuccessValue;
 }
 
 // @public @sealed
@@ -1503,9 +1525,11 @@ export const Tree: Tree;
 
 // @alpha @sealed
 export interface TreeAlpha {
+    // @deprecated
     branch(node: TreeNode): TreeBranchAlpha | undefined;
     child(node: TreeNode, key: string | number): TreeNode | TreeLeafValue | undefined;
     children(node: TreeNode): Iterable<[propertyKey: string | number, child: TreeNode | TreeLeafValue]>;
+    context(node: TreeNode): TreeContextAlpha;
     create<const TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(schema: UnsafeUnknownSchema extends TSchema ? ImplicitFieldSchema : TSchema & ImplicitFieldSchema, data: InsertableField<TSchema>): Unhydrated<TSchema extends ImplicitFieldSchema ? TreeFieldFromImplicitField<TSchema> : TreeNode | TreeLeafValue | undefined>;
     exportCompressed(tree: TreeNode | TreeLeafValue, options: {
         idCompressor?: IIdCompressor;
@@ -1578,7 +1602,7 @@ export interface TreeBranch extends IDisposable {
 }
 
 // @alpha @sealed
-export interface TreeBranchAlpha extends TreeBranch {
+export interface TreeBranchAlpha extends TreeBranch, TreeContextAlpha {
     applyChange(change: JsonCompatibleReadOnly): void;
     readonly events: Listenable_2<TreeBranchEvents>;
     // (undocumented)
@@ -1619,6 +1643,15 @@ export enum TreeCompressionStrategy {
     Uncompressed = 1
 }
 
+// @alpha
+export interface TreeContextAlpha {
+    isBranch(): this is TreeBranchAlpha;
+    runTransaction<TValue>(transaction: () => WithValue<TValue>, params?: RunTransactionParams): TransactionResultExt<TValue, TValue>;
+    runTransaction(transaction: () => void, params?: RunTransactionParams): TransactionResult;
+    runTransactionAsync<TValue>(transaction: () => Promise<WithValue<TValue>>, params?: RunTransactionParams): Promise<TransactionResultExt<TValue, TValue>>;
+    runTransactionAsync(transaction: () => Promise<void>, params?: RunTransactionParams): Promise<TransactionResult>;
+}
+
 // @beta @input
 export interface TreeEncodingOptions<TKeyOptions = KeyEncodingOptions> {
     readonly keys?: TKeyOptions;
@@ -1636,13 +1669,13 @@ export interface TreeIdentifierUtils {
     shorten(branch: TreeBranch, nodeIdentifier: string): number | undefined;
 }
 
-// @alpha
-export interface TreeIndex<TKey extends TreeIndexKey, TValue> extends ReadonlyMap<TKey, TValue> {
+// @alpha @sealed
+export interface TreeIndex<TKey, TValue> extends ReadonlyMap<TKey, TValue> {
     dispose(): void;
 }
 
 // @alpha
-export type TreeIndexKey = number | string | boolean | IFluidHandle | null;
+export type TreeIndexKey = TreeLeafValue;
 
 // @alpha
 export type TreeIndexNodes<TNode> = readonly [first: TNode, ...rest: TNode[]];
@@ -1916,6 +1949,11 @@ export interface WithType<out TName extends string = string, out TKind extends N
     get [typeSchemaSymbol](): TreeNodeSchemaClass<TName, TKind, TreeNode, never, boolean, TInfo>;
 }
 
+// @alpha
+export interface WithValue<TValue> {
+    value: TValue;
+}
+
 // (No @packageDocumentation comment for this package)
 
 ```

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

@@ -592,6 +592,36 @@ export function singletonSchema<TScope extends string, TName extends string | nu
     readonly value: TName;
 }, Record<string, never>, true, Record<string, never>, undefined>;
 
+// @beta @input
+export interface SnapshotFileSystem {
+    join(parentPath: string, childPath: string): string;
+    mkdirSync(dir: string, options: {
+        recursive: true;
+    }): void;
+    readdirSync(dir: string): readonly string[];
+    readFileSync(file: string, encoding: "utf8"): string;
+    writeFileSync(file: string, data: string, options: {
+        encoding: "utf8";
+    }): void;
+}
+
+// @beta
+export function snapshotSchemaCompatibility(options: SnapshotSchemaCompatibilityOptions): void;
+
+// @beta @input
+export interface SnapshotSchemaCompatibilityOptions {
+    readonly fileSystem: SnapshotFileSystem;
+    readonly minVersionForCollaboration: string;
+    readonly mode: "assert" | "update";
+    readonly rejectSchemaChangesWithNoVersionChange?: true;
+    readonly rejectVersionsWithNoSchemaChange?: true;
+    readonly schema: TreeViewConfiguration;
+    readonly snapshotDirectory: string;
+    readonly snapshotUnchangedVersions?: true;
+    readonly version: string;
+    readonly versionComparer?: (a: string, b: string) => number;
+}
+
 // @beta @system
 export namespace System_TableSchema {
     // @sealed @system

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

@@ -604,6 +604,36 @@ export function singletonSchema<TScope extends string, TName extends string | nu
     readonly value: TName;
 }, Record<string, never>, true, Record<string, never>, undefined>;
 
+// @beta @input
+export interface SnapshotFileSystem {
+    join(parentPath: string, childPath: string): string;
+    mkdirSync(dir: string, options: {
+        recursive: true;
+    }): void;
+    readdirSync(dir: string): readonly string[];
+    readFileSync(file: string, encoding: "utf8"): string;
+    writeFileSync(file: string, data: string, options: {
+        encoding: "utf8";
+    }): void;
+}
+
+// @beta
+export function snapshotSchemaCompatibility(options: SnapshotSchemaCompatibilityOptions): void;
+
+// @beta @input
+export interface SnapshotSchemaCompatibilityOptions {
+    readonly fileSystem: SnapshotFileSystem;
+    readonly minVersionForCollaboration: string;
+    readonly mode: "assert" | "update";
+    readonly rejectSchemaChangesWithNoVersionChange?: true;
+    readonly rejectVersionsWithNoSchemaChange?: true;
+    readonly schema: TreeViewConfiguration;
+    readonly snapshotDirectory: string;
+    readonly snapshotUnchangedVersions?: true;
+    readonly version: string;
+    readonly versionComparer?: (a: string, b: string) => number;
+}
+
 // @beta @system
 export namespace System_TableSchema {
     // @sealed @system

package/dist/alpha.d.ts

@@ -126,6 +126,8 @@ export {
 	SchemaStaticsBeta, 
 	SchemaUpgrade, 
 	SharedTreeOptionsBeta, 
+	SnapshotFileSystem, 
+	SnapshotSchemaCompatibilityOptions, 
 	System_TableSchema, 
 	TableSchema, 
 	TreeBeta, 
@@ -144,7 +146,8 @@ export {
 	configuredSharedTreeBeta, 
 	createIndependentTreeBeta, 
 	enumFromStrings, 
-	singletonSchema,
+	singletonSchema, 
+	snapshotSchemaCompatibility,
 	// #endregion
  
 	// #region @alpha APIs
@@ -198,6 +201,7 @@ export {
 	JsonSchemaType, 
 	JsonStringKeyPatternProperties, 
 	JsonTreeSchema, 
+	LabelTree, 
 	LocalChangeMetadata, 
 	MapNodeCustomizableSchema, 
 	MapNodeCustomizableSchemaUnsafe, 
@@ -231,12 +235,11 @@ export {
 	SimpleObjectFieldSchema, 
 	SimpleObjectNodeSchema, 
 	SimpleRecordNodeSchema, 
-	SimpleTreeIndex, 
 	SimpleTreeSchema, 
-	SnapshotFileSystem, 
-	SnapshotSchemaCompatibilityOptions, 
+	TextAsTree, 
 	TransactionCallbackStatus, 
 	TransactionConstraintAlpha, 
+	TransactionLabels, 
 	TransactionResult, 
 	TransactionResultExt, 
 	TransactionResultFailed, 
@@ -246,6 +249,7 @@ export {
 	TreeBranchEvents, 
 	TreeBranchFork, 
 	TreeCompressionStrategy, 
+	TreeContextAlpha, 
 	TreeIdentifierUtils, 
 	TreeIndex, 
 	TreeIndexKey, 
@@ -261,6 +265,7 @@ export {
 	VerboseTreeNode, 
 	ViewContent, 
 	VoidTransactionCallbackStatus, 
+	WithValue, 
 	allowUnused, 
 	asAlpha, 
 	asTreeViewAlpha, 
@@ -272,7 +277,7 @@ export {
 	createArrayInsertionAnchor, 
 	createIdentifierIndex, 
 	createIndependentTreeAlpha, 
-	createSimpleTreeIndex, 
+	createTreeIndex, 
 	decodeSchemaCompatibilitySnapshot, 
 	encodeSchemaCompatibilitySnapshot, 
 	eraseSchemaDetails, 
@@ -294,7 +299,6 @@ export {
 	replaceConciseTreeHandles, 
 	replaceHandles, 
 	replaceVerboseTreeHandles, 
-	snapshotSchemaCompatibility, 
 	trackDirtyNodes
 	// #endregion
 } from "./index.js";

package/dist/beta.d.ts

@@ -126,6 +126,8 @@ export {
 	SchemaStaticsBeta, 
 	SchemaUpgrade, 
 	SharedTreeOptionsBeta, 
+	SnapshotFileSystem, 
+	SnapshotSchemaCompatibilityOptions, 
 	System_TableSchema, 
 	TableSchema, 
 	TreeBeta, 
@@ -144,6 +146,7 @@ export {
 	configuredSharedTreeBeta, 
 	createIndependentTreeBeta, 
 	enumFromStrings, 
-	singletonSchema
+	singletonSchema, 
+	snapshotSchemaCompatibility
 	// #endregion
 } from "./index.js";

package/dist/codec/codec.d.ts

@@ -253,6 +253,8 @@ export declare const unitCodec: IJsonCodec<0, JsonCompatibleReadOnly, JsonCompat
 /**
  * Wraps a codec with JSON schema validation for its encoded type.
  * @returns An {@link IJsonCodec} which validates the data it encodes and decodes matches the provided schema.
+ * @remarks
+ * Eventually all codecs should use the same pattern implemented by ClientVersionDispatchingCodecBuilder, resulting in that having the only use of this API.
  */
 export declare function withSchemaValidation<TInMemoryFormat, EncodedSchema extends TSchema, TEncodedFormat, TValidate, TContext>(schema: EncodedSchema, codec: IJsonCodec<TInMemoryFormat, TEncodedFormat, TValidate, TContext>, validator?: JsonValidator | FormatValidator): IJsonCodec<TInMemoryFormat, TEncodedFormat, TValidate, TContext>;
 /**

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

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

package/dist/codec/codec.js

@@ -97,6 +97,8 @@ exports.unitCodec = {
 /**
  * Wraps a codec with JSON schema validation for its encoded type.
  * @returns An {@link IJsonCodec} which validates the data it encodes and decodes matches the provided schema.
+ * @remarks
+ * Eventually all codecs should use the same pattern implemented by ClientVersionDispatchingCodecBuilder, resulting in that having the only use of this API.
  */
 function withSchemaValidation(schema, codec, validator) {
     if (!validator) {
@@ -107,15 +109,14 @@ function withSchemaValidation(schema, codec, validator) {
         encode: (obj, context) => {
             const encoded = codec.encode(obj, context);
             if (!compiledFormat.check(encoded)) {
-                (0, internal_1.fail)(0xac0 /* Encoded schema should validate */);
+                (0, internal_1.fail)(0xac0 /* Encoded data should validate */);
             }
             return encoded;
         },
         decode: (encoded, context) => {
             if (!compiledFormat.check(encoded)) {
-                (0, internal_1.fail)(0xac1 /* Encoded schema should validate */);
+                (0, internal_1.fail)(0xac1 /* Data being decoded should validate */);
             }
-            // TODO: would be nice to provide a more specific validate type to the inner codec than the outer one gets.
             return codec.decode(encoded, context);
         },
     };