@fluidframework/tree 2.63.0-358419 → 2.63.0-359461

package/src/simple-tree/api/schemaFactoryBeta.ts

@@ -3,7 +3,41 @@
  * Licensed under the MIT License.
  */
 
-import { SchemaFactory, scoped, type ScopedSchemaName } from "./schemaFactory.js";
+import type {
+	ImplicitAllowedTypes,
+	NodeKind,
+	TreeNodeSchema,
+	TreeNodeSchemaBoth,
+	TreeNodeSchemaClass,
+	TreeNodeSchemaNonClass,
+	WithType,
+} from "../core/index.js";
+
+import {
+	recordSchema,
+	type RecordNodeInsertableData,
+	type TreeRecordNode,
+} from "../node-kinds/index.js";
+import {
+	SchemaFactory,
+	scoped,
+	structuralName,
+	type NodeSchemaOptions,
+	type ScopedSchemaName,
+} from "./schemaFactory.js";
+import type { System_Unsafe, TreeRecordNodeUnsafe } from "./typesUnsafe.js";
+
+// These imports prevent a large number of type references in the API reports from showing up as *_2.
+/* eslint-disable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars, import/no-duplicates */
+import type {
+	FieldProps,
+	FieldSchemaAlpha,
+	FieldPropsAlpha,
+	FieldKind,
+} from "../fieldSchema.js";
+import type { LeafSchema } from "../leafNodeSchema.js";
+import type { SimpleLeafNodeSchema } from "../simpleSchema.js";
+/* eslint-enable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars, import/no-duplicates */
 
 /**
  * {@link SchemaFactory} with additional beta APIs.
@@ -25,4 +59,238 @@ export class SchemaFactoryBeta<
 	): SchemaFactoryBeta<ScopedSchemaName<TScope, T>, TNameInner> {
 		return new SchemaFactoryBeta(scoped(this, name));
 	}
+
+	/**
+	 * Define a structurally typed {@link TreeNodeSchema} for a {@link (TreeRecordNode:interface)}.
+	 *
+	 * @param allowedTypes - The types that may appear in the record.
+	 *
+	 * @remarks
+	 * The identifier for this record is defined as a function of the provided types.
+	 * It is still scoped to this `SchemaFactory`, but multiple calls with the same arguments will return the same
+	 * schema object, providing somewhat structural typing.
+	 * This does not support recursive types.
+	 *
+	 * If using these structurally named records, other types in this schema builder should avoid names of the form `Record<${string}>`.
+	 *
+	 * The underlying data format for `Record` nodes is the same as that for `Map` nodes.
+	 * Therefore, changing an existing `Map` schema to a `Record` schema (or vice versa) is
+	 * a non-breaking change and does not require schema migration.
+	 *
+	 * @example
+	 * The returned schema should be used as a schema directly:
+	 * ```typescript
+	 * const MyRecord = factory.record(factory.number);
+	 * type MyRecord = NodeFromSchema<typeof Record>;
+	 * ```
+	 * Or inline:
+	 * ```typescript
+	 * factory.object("Foo", { myRecord: factory.record(factory.number) });
+	 * ```
+	 *
+	 * @privateRemarks
+	 * The name produced at the type-level here is not as specific as it could be; however, doing type-level sorting and escaping is a real mess.
+	 * There are cases where not having this full type provided will be less than ideal, since TypeScript's structural types will allow assignment between runtime incompatible types at compile time.
+	 * For example, attempts to narrow unions of structural records by name won't work.
+	 * Planned future changes to move to a class based schema system as well as factor function based node construction should mostly avoid these issues,
+	 * though there may still be some problematic cases even after that work is done.
+	 *
+	 * The return value is a class, but its type is intentionally not specific enough to indicate it is a class.
+	 * This prevents callers of this from sub-classing it, which is unlikely to work well (due to the ease of accidentally giving two different calls to this different subclasses)
+	 * when working with structural typing.
+	 *
+	 * {@label STRUCTURAL}
+	 */
+	public record<const T extends TreeNodeSchema | readonly TreeNodeSchema[]>(
+		allowedTypes: T,
+	): TreeNodeSchemaNonClass<
+		/* Name */ ScopedSchemaName<TScope, `Record<${string}>`>,
+		/* Kind */ NodeKind.Record,
+		/* TNode */ TreeRecordNode<T> &
+			WithType<ScopedSchemaName<TScope, `Record<${string}>`>, NodeKind.Record>,
+		/* TInsertable */ RecordNodeInsertableData<T>,
+		/* ImplicitlyConstructable */ true,
+		/* Info */ T,
+		/* TConstructorExtra */ undefined
+	>;
+	/**
+	 * Define (and add to this library) a {@link TreeNodeSchemaClass} for a {@link (TreeRecordNode:interface)}.
+	 *
+	 * @param name - Unique identifier for this schema within this factory's scope.
+	 * @param allowedTypes - The types that may appear in the record.
+	 *
+	 * @remarks
+	 * The underlying data format for `Record` nodes is the same as that for `Map` nodes.
+	 * Therefore, changing an existing `Map` schema to a `Record` schema (or vice versa) is
+	 * a non-breaking change and does not require schema migration.
+	 *
+	 * Like TypeScript `Record`s, record nodes have some potential pitfalls.
+	 * For example: TypeScript makes assumptions about built-in keys being present (e.g. `toString`, `hasOwnProperty`, etc.).
+	 * Since these are otherwise valid keys in a record, this can lead to unexpected behavior.
+	 * To prevent inconsistent behavior, these built-ins are hidden by record nodes.
+	 * This means that if you try to call these built-ins (e.g. `toString()`) on a record node, you will get an error.
+	 *
+	 * @example
+	 * ```typescript
+	 * class NamedRecord extends factory.record("name", factory.number) {}
+	 * ```
+	 *
+	 * {@label NAMED}
+	 */
+	public record<const Name extends TName, const T extends ImplicitAllowedTypes>(
+		name: Name,
+		allowedTypes: T,
+	): TreeNodeSchemaClass<
+		/* Name */ ScopedSchemaName<TScope, Name>,
+		/* Kind */ NodeKind.Record,
+		/* TNode */ TreeRecordNode<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Record>,
+		/* TInsertable */ RecordNodeInsertableData<T>,
+		/* ImplicitlyConstructable */ true,
+		/* Info */ T,
+		/* TConstructorExtra */ undefined
+	>;
+	/**
+	 * {@link SchemaFactoryBeta.record} implementation.
+	 *
+	 * @privateRemarks
+	 * This should return {@link TreeNodeSchemaBoth}: see note on {@link SchemaFactory.map} implementation for details.
+	 */
+	public record<const T extends ImplicitAllowedTypes>(
+		nameOrAllowedTypes: TName | ((T & TreeNodeSchema) | readonly TreeNodeSchema[]),
+		maybeAllowedTypes?: T,
+	): TreeNodeSchema<
+		/* Name */ ScopedSchemaName<TScope, string>,
+		/* Kind */ NodeKind.Record,
+		/* TNode */ TreeRecordNode<T>,
+		/* TInsertable */ RecordNodeInsertableData<T>,
+		/* ImplicitlyConstructable */ true,
+		/* Info */ T
+	> {
+		if (maybeAllowedTypes === undefined) {
+			const types = nameOrAllowedTypes as (T & TreeNodeSchema) | readonly TreeNodeSchema[];
+			const fullName = structuralName("Record", types);
+			return this.getStructuralType(fullName, types, () =>
+				this.namedRecord(
+					fullName,
+					nameOrAllowedTypes as T,
+					/* customizable */ false,
+					/* implicitlyConstructable */ true,
+				),
+			) as TreeNodeSchemaClass<
+				/* Name */ ScopedSchemaName<TScope, string>,
+				/* Kind */ NodeKind.Record,
+				/* TNode */ TreeRecordNode<T>,
+				/* TInsertable */ RecordNodeInsertableData<T>,
+				/* ImplicitlyConstructable */ true,
+				/* Info */ T,
+				/* TConstructorExtra */ undefined
+			>;
+		}
+		const out: TreeNodeSchemaBoth<
+			/* Name */ ScopedSchemaName<TScope, string>,
+			/* Kind */ NodeKind.Record,
+			/* TNode */ TreeRecordNode<T>,
+			/* TInsertable */ RecordNodeInsertableData<T>,
+			/* ImplicitlyConstructable */ true,
+			/* Info */ T,
+			/* TConstructorExtra */ undefined
+		> = this.namedRecord(
+			nameOrAllowedTypes as TName,
+			maybeAllowedTypes,
+			/* customizable */ true,
+			/* implicitlyConstructable */ true,
+		);
+		return out;
+	}
+
+	/**
+	 * Define a {@link TreeNodeSchema} for a {@link (TreeRecordNode:interface)}.
+	 *
+	 * @param name - Unique identifier for this schema within this factory's scope.
+	 *
+	 * @remarks
+	 * This is not intended to be used directly, use the overload of `record` which takes a name instead.
+	 */
+	private namedRecord<
+		Name extends TName | string,
+		const T extends ImplicitAllowedTypes,
+		const ImplicitlyConstructable extends boolean,
+		const TCustomMetadata = unknown,
+	>(
+		name: Name,
+		allowedTypes: T,
+		customizable: boolean,
+		implicitlyConstructable: ImplicitlyConstructable,
+		options?: NodeSchemaOptions<TCustomMetadata>,
+	): TreeNodeSchemaBoth<
+		/* Name */ ScopedSchemaName<TScope, Name>,
+		/* Kind */ NodeKind.Record,
+		/* TNode */ TreeRecordNode<T> &
+			WithType<ScopedSchemaName<TScope, string>, NodeKind.Record>,
+		/* TInsertable */ RecordNodeInsertableData<T>,
+		/* ImplicitlyConstructable */ ImplicitlyConstructable,
+		/* Info */ T,
+		/* TConstructorExtra */ undefined
+	> {
+		const record = recordSchema({
+			identifier: scoped<TScope, TName, Name>(this, name),
+			info: allowedTypes,
+			customizable,
+			implicitlyConstructable,
+			metadata: options?.metadata,
+		});
+
+		return record as TreeNodeSchemaBoth<
+			/* Name */ ScopedSchemaName<TScope, Name>,
+			/* Kind */ NodeKind.Record,
+			/* TNode */ TreeRecordNode<T> &
+				WithType<ScopedSchemaName<TScope, string>, NodeKind.Record>,
+			/* TInsertable */ RecordNodeInsertableData<T>,
+			/* ImplicitlyConstructable */ ImplicitlyConstructable,
+			/* Info */ T,
+			/* TConstructorExtra */ undefined
+		>;
+	}
+
+	/**
+	 * {@link SchemaFactoryBeta.(record:2)} except tweaked to work better for recursive types.
+	 * Use with {@link ValidateRecursiveSchema} for improved type safety.
+	 * @remarks
+	 * This version of `SchemaFactory.record` uses the same workarounds as {@link SchemaFactory.objectRecursive}.
+	 * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.
+	 */
+	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+	public recordRecursive<
+		Name extends TName,
+		const T extends System_Unsafe.ImplicitAllowedTypesUnsafe,
+		const TCustomMetadata = unknown,
+	>(name: Name, allowedTypes: T, options?: NodeSchemaOptions<TCustomMetadata>) {
+		const RecordSchema = this.namedRecord(
+			name,
+			allowedTypes as T & ImplicitAllowedTypes,
+			/* customizable */ true,
+			// Setting this to true seems to work ok currently, but not for other node kinds.
+			// Supporting this could be fragile and might break other future changes, so it's being kept as false for now.
+			/* implicitlyConstructable */ false,
+			options,
+		);
+
+		return RecordSchema as TreeNodeSchemaClass<
+			/* Name */ ScopedSchemaName<TScope, Name>,
+			/* Kind */ NodeKind.Record,
+			/* TNode */ TreeRecordNodeUnsafe<T> &
+				WithType<ScopedSchemaName<TScope, Name>, NodeKind.Record>,
+			/* TInsertable */ {
+				// Ideally this would be
+				// RestrictiveStringRecord<InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>>,
+				// but doing so breaks recursive types.
+				// Instead we do a less nice version:
+				readonly [P in string]: System_Unsafe.InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>;
+			},
+			/* ImplicitlyConstructable */ false,
+			/* Info */ T,
+			/* TConstructorExtra */ undefined,
+			/* TCustomMetadata */ TCustomMetadata
+		>;
+	}
 }

package/src/simple-tree/api/tree.ts

@@ -322,18 +322,25 @@ export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends ID
 	readonly compatibility: SchemaCompatibilityStatus;
 
 	/**
-	 * When the schemas are not an exact match and {@link SchemaCompatibilityStatus.canUpgrade} is true,
+	 * When {@link SchemaCompatibilityStatus.canUpgrade} is true,
 	 * this can be used to modify the stored schema to make it match the view schema.
-	 * This will update the compatibility state, and allow access to `root`.
-	 * Beware that this may impact other clients' ability to view the document depending on the application's schema compatibility policy!
 	 * @remarks
-	 * It is an error to call this when {@link SchemaCompatibilityStatus.canUpgrade} is false, and a no-op when the stored and view schema are already an exact match.
+	 * This will update the {@link TreeView.compatibility}, allowing access to `root`.
+	 * Beware that this may impact other clients' ability to view the document: see {@link SchemaCompatibilityStatus.canView} for more information.
+	 *
+	 * It is an error to call this when {@link SchemaCompatibilityStatus.canUpgrade} is false.
+	 * {@link SchemaCompatibilityStatus.canUpgrade} being true does not mean that an upgrade is required, nor that an upgrade will have any effect.
 	 * @privateRemarks
 	 * In the future, more upgrade options could be provided here.
 	 * Some options that could be added:
 	 * - check the actual document contents (not just the schema) and attempt an atomic document update if the data is compatible.
 	 * - apply converters and upgrade the document.
 	 * - apply converters to lazily to adapt the document to the requested view schema (with optional lazy schema updates or transparent conversions on write).
+	 * - update only a specific change (add an optional field, or apply a staged upgrade)
+	 * - update persistedMetadata or not
+	 *
+	 * As persisted metadata becomes more supported, how it interacts with isEquivalent and upgradeSchema should be clarified:
+	 * for now the docs are being left somewhat vague to allow flexibility in this area.
 	 */
 	upgradeSchema(): void;
 
@@ -382,6 +389,8 @@ export interface TreeViewAlpha<
  * Information about a view schema's compatibility with the document's stored schema.
  *
  * See SharedTree's README for more information about choosing a compatibility policy.
+ * @privateRemarks
+ * See {@link SchemaCompatibilityTester} for the implementation of this compatibility checking.
  * @sealed @public
  */
 export interface SchemaCompatibilityStatus {
@@ -396,38 +405,41 @@ export interface SchemaCompatibilityStatus {
 	 *
 	 * - schema repository `A` has extra schema which schema `B` doesn't have, but they are unused (i.e. not reachable from the root schema)
 	 *
-	 * - field in schema `A` has allowed field members which the corresponding field in schema `B` does not have, but those types are not constructible (ex: an object node type containing a required field with no allowed types)
+	 * - field in schema `A` has allowed field members which the corresponding field in schema `B` does not have, but those types are not constructible (for example: an object node type containing a required field with no allowed types)
 	 *
 	 * These cases are typically not interesting to applications.
+	 *
+	 * Note that other content in the stored schema that does not impact document compatibility, like {@link NodeSchemaOptionsAlpha.persistedMetadata}, does not affect this field.
+	 *
+	 * For the computation of this equivalence, {@link SchemaStaticsAlpha.staged | staged} schemas are not included.
+	 * If there are any unknown optional fields, even if allowed by {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields}, `isEquivalent` will be false.
 	 */
 	readonly isEquivalent: boolean;
 
 	/**
 	 * Whether the current view schema is sufficiently compatible with the stored schema to allow viewing tree data.
 	 * If false, {@link TreeView.root} will throw upon access.
+	 * @remarks
+	 * If the view schema does not opt into supporting any additional cases, then `canView` is only true when `isEquivalent` is also true.
+	 * The view schema can however opt into supporting additional cases, and thus can also view documents with stored schema which would be equivalent, except for the following discrepancies:
 	 *
-	 * Currently, this field is true iff `isEquivalent` is true.
-	 * Do not rely on this:
-	 * there are near-term plans to extend support for viewing documents when the stored schema contains additional optional fields not present in the view schema.
-	 * The other two types of backward-compatible changes (field relaxations and addition of allowed field types) will eventually be supported as well,
-	 * likely through out-of-schema content adapters that the application can provide alongside their view schema.
+	 * - An object node with {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields} to set to true that has additional optional fields in the stored schema beyond those mentioned in its view schema.
 	 *
-	 * Be aware that even with these SharedTree limitations fixed, application logic may not correctly tolerate the documents allowable by the stored schema!
-	 * Application authors are encouraged to read docs/user-facing/schema-evolution.md and choose a schema compatibility policy that
-	 * aligns with their application's needs.
+	 * - An additional type allowed at a location in the stored schema where it is {@link SchemaStaticsAlpha.staged | staged} in the view schema.
+	 *
+	 * In these cases `canUpgrade` and `isEquivalent` will be false.
 	 *
-	 * @remarks
 	 * When the documents allowed by the view schema is a strict superset of those by the stored schema,
-	 * this is false because writes to the document using the view schema could make the document violate its stored schema.
+	 * `canView` is false because writes to the document using the view schema could make the document violate its stored schema.
 	 * In this case, the stored schema could be updated to match the provided view schema, allowing read-write access to the tree.
 	 * See {@link SchemaCompatibilityStatus.canUpgrade}.
 	 *
-	 * Future version of SharedTree may provide readonly access to the document in this case because that would be safe,
+	 * Future versions of SharedTree may provide readonly access to the document in this case because that would be safe,
 	 * but this is not currently supported.
 	 *
 	 * @privateRemarks
 	 * A necessary condition for this to be true is that the documents allowed by the view schema are a subset of those allowed by the stored schema.
-	 * This is not sufficient: the simple-tree layer's read APIs do not tolerate out-of-schema data.
+	 * This is not sufficient: the simple-tree layer's read APIs only tolerate very specific cases beyond their schema (unknown optional fields).
 	 * For example, if the view schema for a node has a required `Point` field but the stored schema has an optional `Point` field,
 	 * read APIs on the view schema do not work correctly when the document has a node with a missing `Point` field.
 	 * Similar issues happen when the view schema has a field with less allowed types than the stored schema and the document actually leverages those types.
@@ -435,8 +447,15 @@ export interface SchemaCompatibilityStatus {
 	readonly canView: boolean;
 
 	/**
-	 * True iff the view schema supports all possible documents permitted by the stored schema.
+	 * True when {@link TreeView.upgradeSchema} can add support for all content required to be supported by the view schema.
+	 * @remarks
 	 * When true, it is valid to call {@link TreeView.upgradeSchema} (though if the stored schema is already an exact match, this is a no-op).
+	 *
+	 * When adding optional fields to schema which previously were marked with {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields}
+	 * the schema upgrade (assuming no other changes are included) will allow the previous version to view.
+	 * Even this case must still must be done with caution however as only clients with the newly added field will be able to do future upgrades.
+	 * Thus if a version of an application is shipped that adds an unknown optional field, all future versions should include it, even if its no longer used,
+	 * to ensure that documents containing it can still be upgraded.
 	 */
 	readonly canUpgrade: boolean;
 

package/src/simple-tree/api/treeBeta.ts

@@ -9,6 +9,7 @@ import { brand } from "../../util/index.js";
 import {
 	Context,
 	getKernel,
+	getOrCreateNodeFromInnerNode,
 	isTreeNode,
 	UnhydratedContext,
 	type NodeKind,
@@ -17,7 +18,15 @@ import {
 	type WithType,
 } from "../core/index.js";
 import { getUnhydratedContext } from "../createContext.js";
-import type { ImplicitFieldSchema, TreeFieldFromImplicitField } from "../fieldSchema.js";
+import type {
+	ImplicitFieldSchema,
+	InsertableTreeFieldFromImplicitField,
+	TreeFieldFromImplicitField,
+} from "../fieldSchema.js";
+import {
+	unhydratedFlexTreeFromInsertable,
+	type InsertableContent,
+} from "../unhydratedFlexTreeFromInsertable.js";
 
 import { createFromCursor } from "./create.js";
 import type { TreeChangeEvents } from "./treeChangeEvents.js";
@@ -159,6 +168,20 @@ export interface TreeBeta {
 	// 		replaceIdentifiers?: true;
 	// 	},
 	// ): TreeFieldFromImplicitField<TSchema>;
+
+	/**
+	 * Construct tree content that is compatible with the field defined by the provided `schema`.
+	 * @param schema - The schema for what to construct. As this is an {@link ImplicitFieldSchema}, a {@link FieldSchema}, {@link TreeNodeSchema} or {@link AllowedTypes} array can be provided.
+	 * @param data - The data used to construct the field content.
+	 * @remarks
+	 * When providing a {@link TreeNodeSchemaClass}, this is the same as invoking its constructor except that an unhydrated node can also be provided.
+	 * This function exists as a generalization that can be used in other cases as well,
+	 * such as when `undefined` might be allowed (for an optional field), or when the type should be inferred from the data when more than one type is possible.
+	 */
+	create<const TSchema extends ImplicitFieldSchema>(
+		schema: TSchema,
+		data: InsertableTreeFieldFromImplicitField<TSchema>,
+	): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
 }
 
 /**
@@ -202,4 +225,16 @@ export const TreeBeta: TreeBeta = {
 			TreeFieldFromImplicitField<TSchema>
 		>;
 	},
+
+	create<const TSchema extends ImplicitFieldSchema>(
+		schema: TSchema,
+		data: InsertableTreeFieldFromImplicitField<TSchema>,
+	): Unhydrated<TreeFieldFromImplicitField<TSchema>> {
+		const mapTree = unhydratedFlexTreeFromInsertable(
+			data as InsertableContent | undefined,
+			schema,
+		);
+		const result = mapTree === undefined ? undefined : getOrCreateNodeFromInnerNode(mapTree);
+		return result as Unhydrated<TreeFieldFromImplicitField<TSchema>>;
+	},
 };

package/src/simple-tree/api/typesUnsafe.ts

@@ -533,7 +533,7 @@ export interface MapNodeCustomizableSchemaUnsafe<
  * {@link Unenforced} version of {@link TreeRecordNode}.
  * @remarks
  * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
- * @system @sealed @alpha
+ * @system @sealed @beta
  */
 export interface TreeRecordNodeUnsafe<
 	TAllowedTypes extends System_Unsafe.ImplicitAllowedTypesUnsafe,

package/src/simple-tree/core/treeNode.ts

@@ -28,13 +28,14 @@ import { markEager } from "./flexList.js";
  *
  * 2. Explicit construction of {@link Unhydrated} nodes using either {@link TreeNodeSchemaClass} as a constructor or {@link TreeNodeSchemaNonClass|TreeNodeSchemaNonClass.create}.
  * Either way the {@link TreeNodeSchema} produced must be produced using a {@link SchemaFactory}.
+ * There are also higher level APIs which wrap these, including {@link (TreeBeta:interface).create}, {@link (TreeBeta:interface).clone},
+ * and import APIs like {@link (TreeAlpha:interface).importConcise}, {@link (TreeAlpha:interface).importVerbose}, and {@link (TreeAlpha:interface).importCompressed}.
  *
  * 3. Implicit construction: Several APIs which logically require an unhydrated TreeNode also allow passing in a value which could be used to explicitly construct the node instead.
- * These APIs internally call the constructor with the provided value, so it's really just a special case of the above option.
+ * These APIs internally call the constructor with the provided value (typically behaving like {@link (TreeAlpha:interface).create}), so it's really just a special case of the above option.
  * Note that when constructing nodes, sometimes implicit construction is not allowed
  * (either at runtime due to ambiguous types or at compile time due to TypeScript limitations):
  * in such cases, explicit construction must be used.
- *
  * @privateRemarks
  * This is a class not an interface to enable stricter type checking (see {@link TreeNode.#brand})
  * and some runtime enforcement of schema class policy (see the the validation in the constructor).

package/src/simple-tree/core/treeNodeKernel.ts

@@ -385,7 +385,7 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 	readonly #events = createEmitter<KernelEvents>();
 
 	#eventSource: Listenable<KernelEvents> & HasListeners<KernelEvents>;
-	#disposeSourceListeners: Map<keyof KernelEvents, Off> = new Map();
+	readonly #disposeSourceListeners: Map<keyof KernelEvents, Off> = new Map();
 
 	/**
 	 * Buffer of fields that have changed since events were paused.

package/src/simple-tree/node-kinds/record/recordNodeTypes.ts

@@ -28,7 +28,7 @@ import type { RestrictiveStringRecord } from "../../../util/index.js";
  * Therefore code assigning to these fields must explicitly construct nodes using the schema's constructor or create method,
  * or using some other method like {@link (TreeAlpha:interface).create}.
  *
- * @alpha
+ * @beta
  */
 export interface TreeRecordNode<
 	TAllowedTypes extends ImplicitAllowedTypes = ImplicitAllowedTypes,
@@ -44,7 +44,7 @@ export interface TreeRecordNode<
 
 /**
  * Content which can be used to construct a Record node, explicitly or implicitly.
- * @system @alpha
+ * @system @beta
  */
 export type RecordNodeInsertableData<T extends ImplicitAllowedTypes> = RestrictiveStringRecord<
 	InsertableTreeNodeFromImplicitAllowedTypes<T>

package/src/util/brand.ts

@@ -17,7 +17,7 @@ import type { Covariant } from "./typeCheck.js";
  * mismatched branded types will be:
  * `Type 'Name1' is not assignable to type 'Name2'.`
  *
- * These branded types are not opaque: A `Brand<A, B>` can still be used as a `B`.
+ * These branded types are not opaque: A `Brand<A, B>` can still be used as a `A`.
  */
 export type Brand<ValueType, Name> = ValueType & BrandedType<ValueType, Name>;