@fluidframework/tree 2.11.0 → 2.12.0

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

@@ -11,8 +11,12 @@ import {
 	EmptyKey,
 	forEachField,
 	inCursorField,
+	LeafNodeStoredSchema,
 	mapCursorField,
+	ObjectNodeStoredSchema,
 	type ITreeCursor,
+	type TreeNodeSchemaIdentifier,
+	type TreeNodeStoredSchema,
 } from "../../core/index.js";
 import { fail } from "../../util/index.js";
 import type { TreeLeafValue } from "../schemaTypes.js";
@@ -25,6 +29,7 @@ import {
 	stringSchema,
 } from "../leafNodeSchema.js";
 import { isObjectNodeSchema } from "../objectNodeTypes.js";
+import { FieldKinds, valueSchemaAllows } from "../../feature-libraries/index.js";
 
 /**
  * Options for how to encode a tree.
@@ -63,7 +68,7 @@ export type CustomTreeNode<TChild> = TChild[] | { [key: string]: TChild };
 /**
  * Builds an {@link CustomTree} from a cursor in Nodes mode.
  */
-export function customFromCursorInner<TChild, THandle>(
+export function customFromCursor<TChild, THandle>(
 	reader: ITreeCursor,
 	options: Required<EncodeOptions<THandle>>,
 	schema: ReadonlyMap<string, TreeNodeSchema>,
@@ -118,3 +123,66 @@ export function customFromCursorInner<TChild, THandle>(
 		}
 	}
 }
+
+/**
+ * Builds an {@link CustomTree} from a cursor in Nodes mode.
+ * @remarks
+ * Uses stored keys and stored schema.
+ */
+export function customFromCursorStored<TChild>(
+	reader: ITreeCursor,
+	schema: ReadonlyMap<TreeNodeSchemaIdentifier, TreeNodeStoredSchema>,
+	childHandler: (
+		reader: ITreeCursor,
+		schema: ReadonlyMap<TreeNodeSchemaIdentifier, TreeNodeStoredSchema>,
+	) => TChild,
+): CustomTree<TChild, IFluidHandle> {
+	const type = reader.type;
+	const nodeSchema = schema.get(type) ?? fail("missing schema for type in cursor");
+
+	if (nodeSchema instanceof LeafNodeStoredSchema) {
+		assert(valueSchemaAllows(nodeSchema.leafValue, reader.value), 0xa9c /* invalid value */);
+		return reader.value;
+	}
+
+	assert(reader.value === undefined, 0xa9d /* out of schema: unexpected value */);
+
+	const arrayTypes = tryStoredSchemaAsArray(nodeSchema);
+	if (arrayTypes !== undefined) {
+		const field = inCursorField(reader, EmptyKey, () =>
+			mapCursorField(reader, () => childHandler(reader, schema)),
+		);
+		return field;
+	}
+
+	const fields: Record<string, TChild> = {};
+	forEachField(reader, () => {
+		const children = mapCursorField(reader, () => childHandler(reader, schema));
+		if (children.length === 1) {
+			const storedKey = reader.getFieldKey();
+			// Length is checked above.
+			// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+			fields[storedKey] = children[0]!;
+		} else {
+			assert(children.length === 0, 0xa9e /* invalid children number */);
+		}
+	});
+	return fields;
+}
+
+/**
+ * Assumes `schema` corresponds to a simple-tree schema.
+ * If it is an array schema, returns the allowed types for the array field.
+ * Otherwise returns `undefined`.
+ */
+export function tryStoredSchemaAsArray(
+	schema: TreeNodeStoredSchema,
+): ReadonlySet<string> | undefined {
+	if (schema instanceof ObjectNodeStoredSchema) {
+		const empty = schema.getFieldSchema(EmptyKey);
+		if (empty.kind === FieldKinds.sequence.identifier) {
+			assert(schema.objectNodeFields.size === 1, 0xa9f /* invalid schema */);
+			return empty.types;
+		}
+	}
+}

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

@@ -17,7 +17,11 @@ export {
 	type TreeBranchEvents,
 	asTreeViewAlpha,
 } from "./tree.js";
-export { SchemaFactory, type ScopedSchemaName } from "./schemaFactory.js";
+export {
+	SchemaFactory,
+	type ScopedSchemaName,
+	type SchemaFactoryObjectOptions,
+} from "./schemaFactory.js";
 export type {
 	ValidateRecursiveSchema,
 	FixRecursiveArraySchema,
@@ -90,7 +94,13 @@ export {
 	verboseFromCursor,
 } from "./verboseTree.js";
 
-export type { EncodeOptions } from "./customTree.js";
+export {
+	type EncodeOptions,
+	customFromCursorStored,
+	type CustomTreeNode,
+	type CustomTreeValue,
+	tryStoredSchemaAsArray,
+} from "./customTree.js";
 
 export { type ConciseTree, conciseFromCursor } from "./conciseTree.js";
 

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

@@ -18,6 +18,9 @@ import {
 	getOrCreate,
 	isReadonlyArray,
 } from "../../util/index.js";
+// This import is required for intellisense in @link doc comments on mouseover in VSCode.
+// eslint-disable-next-line unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars
+import type { TreeAlpha } from "../../shared-tree/index.js";
 
 import {
 	booleanSchema,
@@ -74,6 +77,7 @@ import type {
 import { createFieldSchemaUnsafe } from "./schemaFactoryRecursive.js";
 import { TreeNodeValid } from "../treeNodeValid.js";
 import { isLazy } from "../flexList.js";
+
 /**
  * Gets the leaf domain schema compatible with a given {@link TreeValue}.
  */
@@ -97,6 +101,58 @@ export function schemaFromValue(value: TreeValue): TreeNodeSchema {
 	}
 }
 
+/**
+ * Options when declaring an {@link SchemaFactory.object|object node}'s schema
+ */
+export interface SchemaFactoryObjectOptions {
+	/**
+	 * Opt in to viewing documents which have unknown optional fields for this object's identifier, i.e. optional fields
+	 * in the document schema which are not present in this object schema declaration.
+	 *
+	 * @defaultValue `false`
+	 * @remarks
+	 * The advantage of enabling this option is that it allows an application ecosystem with staged rollout to more quickly
+	 * upgrade documents to include schema for new optional features.
+	 *
+	 * However, it does come with trade-offs that applications should weigh carefully when it comes to interactions between
+	 * code and documents.
+	 * When opening such documents, the API presented is still determined by the view schema.
+	 * This can have implications on the behavior of edits or code which uses portions of the view schema,
+	 * since this may inadvertently drop data which is present in those optional fields in the document schema.
+	 *
+	 * Consider the following example:
+	 *
+	 * ```typescript
+	 * const sf = new SchemaFactory("com.example");
+	 * class PersonView extends sf.object("Person", { name: sf.string }, { allowUnknownOptionalFields: true }) {}
+	 * class PersonStored extends sf.object("Person", { name: sf.string, nickname: sf.optional(sf.string) }) {}
+	 *
+	 * // Say we have a document which uses `PersonStored` in its schema, and application code constructs
+	 * // a tree view using `PersonView`. If the application for some reason had implemented a function like this:
+	 * function clonePerson(a: PersonView): PersonView {
+	 * 	return new PersonView({ name: a.name });
+	 * }
+	 * // ...or even like this:
+	 * function clonePerson(a: PersonView): PersonView {
+	 *  return new PersonView({ ...a})
+	 * }
+	 * // Then the alleged clone wouldn't actually clone the entire person in either case, it would drop the nickname.
+	 * ```
+	 *
+	 * If an application wants to be particularly careful to preserve all data on a node when editing it, it can use
+	 * {@link TreeAlpha.(importVerbose:2)|import}/{@link TreeAlpha.(exportVerbose:2)|export} APIs with persistent keys.
+	 *
+	 * Note that public API methods which operate on entire nodes (such as `moveTo`, `moveToEnd`, etc. on arrays) do not encounter
+	 * this problem as SharedTree's implementation stores the entire node in its lower layers. It's only when application code
+	 * reaches into a node (either by accessing its fields, spreading it, or some other means) that this problem arises.
+	 */
+	allowUnknownOptionalFields?: boolean;
+}
+
+export const defaultSchemaFactoryObjectOptions: Required<SchemaFactoryObjectOptions> = {
+	allowUnknownOptionalFields: false,
+};
+
 /**
  * The name of a schema produced by {@link SchemaFactory}, including its optional scope prefix.
  *
@@ -333,7 +389,12 @@ export class SchemaFactory<
 		true,
 		T
 	> {
-		return objectSchema(this.scoped(name), fields, true);
+		return objectSchema(
+			this.scoped(name),
+			fields,
+			true,
+			defaultSchemaFactoryObjectOptions.allowUnknownOptionalFields,
+		);
 	}
 
 	/**

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

@@ -30,7 +30,9 @@ export interface SimpleNodeSchemaBase<TNodeKind extends NodeKind> {
  */
 export interface SimpleObjectNodeSchema extends SimpleNodeSchemaBase<NodeKind.Object> {
 	/**
-	 * Schemas for each of the object's fields, keyed off of schema's property keys.
+	 * Schemas for each of the object's fields, keyed off of schema's keys.
+	 * @remarks
+	 * Depending on how this schema was exported, the string keys may be either the property keys or the stored keys.
 	 */
 	readonly fields: Record<string, SimpleFieldSchema>;
 }

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

@@ -200,6 +200,8 @@ export function createSimpleTreeIndex<
 				return treeNodeApi.status(simpleTree);
 			}
 		},
+		// simple tree indexes are shallow indexes, indicating so allows for a performance optimization
+		true,
 	);
 
 	// all the type checking guarantees that we put nodes of the correct type in the index

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

@@ -4,7 +4,7 @@
  */
 
 import type { ICodecOptions } from "../../codec/index.js";
-import { Compatibility, type TreeStoredSchema } from "../../core/index.js";
+import type { TreeStoredSchema } from "../../core/index.js";
 import {
 	defaultSchemaPolicy,
 	encodeTreeSchema,
@@ -59,7 +59,7 @@ export function extractPersistedSchema(schema: ImplicitFieldSchema): JsonCompati
  * opening a document that used the `persisted` schema and provided `view` to {@link ViewableTree.viewWith}.
  *
  * @param persisted - Schema persisted for a document. Typically persisted alongside the data and assumed to describe that data.
- * @param view - Schema which would be used to view persisted content. Use {@link extractPersistedSchema} to convert the view schema into this format.
+ * @param view - Schema which would be used to view persisted content.
  * @param options - {@link ICodecOptions} used when parsing the provided schema.
  * @param canInitialize - Passed through to the return value unchanged and otherwise unused.
  * @returns The {@link SchemaCompatibilityStatus} a {@link TreeView} would report for this combination of schema.
@@ -75,7 +75,7 @@ export function extractPersistedSchema(schema: ImplicitFieldSchema): JsonCompati
  * assert(
  * 	comparePersistedSchema(
  * 		require("./schema.json"),
- * 		extractPersistedSchema(MySchema),
+ * 		MySchema,
  * 		{ jsonValidator: typeboxValidator },
  * 		false,
  * 	).canUpgrade,
@@ -85,14 +85,13 @@ export function extractPersistedSchema(schema: ImplicitFieldSchema): JsonCompati
  */
 export function comparePersistedSchema(
 	persisted: JsonCompatible,
-	view: JsonCompatible,
+	view: ImplicitFieldSchema,
 	options: ICodecOptions,
 	canInitialize: boolean,
 ): SchemaCompatibilityStatus {
 	const schemaCodec = makeSchemaCodec(options);
 	const stored = schemaCodec.decode(persisted as Format);
-	const viewParsed = schemaCodec.decode(view as Format);
-	const viewSchema = new ViewSchema(defaultSchemaPolicy, {}, viewParsed);
+	const viewSchema = new ViewSchema(defaultSchemaPolicy, {}, view);
 	return comparePersistedSchemaInternal(stored, viewSchema, canInitialize);
 }
 
@@ -105,22 +104,8 @@ export function comparePersistedSchemaInternal(
 	viewSchema: ViewSchema,
 	canInitialize: boolean,
 ): SchemaCompatibilityStatus {
-	const result = viewSchema.checkCompatibility(stored);
-
-	// TODO: AB#8121: Weaken this check to support viewing under additional circumstances.
-	// In the near term, this should support viewing documents with additional optional fields in their schema on object types.
-	// Longer-term (as demand arises), we could also add APIs to constructing view schema to allow for more flexibility
-	// (e.g. out-of-schema content handlers could allow support for viewing docs which have extra allowed types in a particular field)
-	const canView =
-		result.write === Compatibility.Compatible && result.read === Compatibility.Compatible;
-	const canUpgrade = result.read === Compatibility.Compatible;
-	const isEquivalent = canView && canUpgrade;
-	const compatibility: SchemaCompatibilityStatus = {
-		canView,
-		canUpgrade,
-		isEquivalent,
+	return {
+		...viewSchema.checkCompatibility(stored),
 		canInitialize,
 	};
-
-	return compatibility;
 }

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

@@ -12,6 +12,10 @@ import type {
 	RevertibleFactory,
 } from "../../core/index.js";
 
+// This is referenced by doc comments.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars, unused-imports/no-unused-imports
+import type { TreeAlpha } from "../../shared-tree/index.js";
+
 import {
 	type ImplicitFieldSchema,
 	type InsertableField,
@@ -31,6 +35,7 @@ import { markSchemaMostDerived } from "./schemaFactory.js";
 import { fail, getOrCreate } from "../../util/index.js";
 import type { MakeNominal } from "../../util/index.js";
 import { walkFieldSchema } from "../walkFieldSchema.js";
+
 /**
  * A tree from which a {@link TreeView} can be created.
  *
@@ -41,6 +46,7 @@ import { walkFieldSchema } from "../walkFieldSchema.js";
  * Maybe rename "exportJsonSchema" to align on "concise" terminology.
  * Ensure schema exporting APIs here align and reference APIs for exporting view schema to the same formats (which should include stored vs property key choice).
  * Make sure users of independentView can use these export APIs (maybe provide a reference back to the ViewableTree from the TreeView to accomplish that).
+ * Some of these APIs are on ISharedTree and can get moved here.
  * @system @sealed @public
  */
 export interface ViewableTree {

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

@@ -38,7 +38,7 @@ import {
 } from "../leafNodeSchema.js";
 import { isObjectNodeSchema } from "../objectNodeTypes.js";
 import {
-	customFromCursorInner,
+	customFromCursor,
 	type CustomTreeNode,
 	type CustomTreeValue,
 	type EncodeOptions,
@@ -344,7 +344,7 @@ function verboseFromCursorInner<TCustom>(
 	options: Required<EncodeOptions<TCustom>>,
 	schema: ReadonlyMap<string, TreeNodeSchema>,
 ): VerboseTree<TCustom> {
-	const fields = customFromCursorInner(reader, options, schema, verboseFromCursorInner);
+	const fields = customFromCursor(reader, options, schema, verboseFromCursorInner);
 	const nodeSchema = schema.get(reader.type) ?? fail("missing schema for type in cursor");
 	if (nodeSchema.kind === NodeKind.Leaf) {
 		return fields as CustomTreeValue<TCustom>;

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

@@ -5,32 +5,56 @@
 
 import {
 	AdaptedViewSchema,
+	type TreeNodeStoredSchema,
 	type Adapters,
-	Compatibility,
 	type TreeFieldStoredSchema,
 	type TreeNodeSchemaIdentifier,
-	type TreeNodeStoredSchema,
 	type TreeStoredSchema,
 } from "../../core/index.js";
 import { fail } from "../../util/index.js";
 import {
+	FieldKinds,
 	type FullSchemaPolicy,
-	allowsRepoSuperset,
+	type FieldDiscrepancy,
+	getAllowedContentDiscrepancies,
 	isNeverTree,
+	PosetComparisonResult,
+	fieldRealizer,
+	comparePosetElements,
 } from "../../feature-libraries/index.js";
+import {
+	normalizeFieldSchema,
+	type FieldSchema,
+	type ImplicitFieldSchema,
+} from "../schemaTypes.js";
+import { toStoredSchema } from "../toStoredSchema.js";
+import { unreachableCase } from "@fluidframework/core-utils/internal";
+import type { SchemaCompatibilityStatus } from "./tree.js";
 
 /**
  * A collection of View information for schema, including policy.
  */
 export class ViewSchema {
 	/**
-	 * @param schema - Cached conversion of view schema in the stored schema format.
+	 * Cached conversion of the view schema in the stored schema format.
+	 */
+	private readonly viewSchemaAsStored: TreeStoredSchema;
+	/**
+	 * Normalized view schema (implicitly allowed view schema types are converted to their canonical form).
+	 */
+	public readonly schema: FieldSchema;
+
+	/**
+	 * @param viewSchema - Schema for the root field of this view.
 	 */
 	public constructor(
 		public readonly policy: FullSchemaPolicy,
 		public readonly adapters: Adapters,
-		public readonly schema: TreeStoredSchema,
-	) {}
+		viewSchema: ImplicitFieldSchema,
+	) {
+		this.schema = normalizeFieldSchema(viewSchema);
+		this.viewSchemaAsStored = toStoredSchema(this.schema);
+	}
 
 	/**
 	 * Determines the compatibility of a stored document
@@ -42,53 +66,168 @@ export class ViewSchema {
 	 * TODO: this API violates the parse don't validate design philosophy.
 	 * It should be wrapped with (or replaced by) a parse style API.
 	 */
-	public checkCompatibility(stored: TreeStoredSchema): {
-		read: Compatibility;
-		write: Compatibility;
-		writeAllowingStoredSchemaUpdates: Compatibility;
-	} {
+	public checkCompatibility(
+		stored: TreeStoredSchema,
+	): Omit<SchemaCompatibilityStatus, "canInitialize"> {
 		// TODO: support adapters
 		// const adapted = this.adaptRepo(stored);
 
-		const read = allowsRepoSuperset(this.policy, stored, this.schema)
-			? Compatibility.Compatible
-			: // TODO: support adapters
-				// : allowsRepoSuperset(this.policy, adapted.adaptedForViewSchema, this.storedSchema)
-				// ? Compatibility.RequiresAdapters
-				Compatibility.Incompatible;
-		// TODO: Extract subset of adapters that are valid to use on stored
-		// TODO: separate adapters from schema updates
-		const write = allowsRepoSuperset(this.policy, this.schema, stored)
-			? Compatibility.Compatible
-			: // TODO: support adapters
-				// : allowsRepoSuperset(this.policy, this.storedSchema, adapted.adaptedForViewSchema)
-				// TODO: IThis assumes adapters are bidirectional.
-				//   Compatibility.RequiresAdapters
-				Compatibility.Incompatible;
-
-		// TODO: compute this properly (and maybe include the set of schema changes needed for it?).
-		// Maybe updates would happen lazily when needed to store data?
-		// When willingness to updates can avoid need for some adapters,
-		// how should it be decided if the adapter should be used to avoid the update?
-		// TODO: is this case actually bi-variant, making this correct if we did it for each schema independently?
-		let writeAllowingStoredSchemaUpdates =
-			// TODO: This should consider just the updates needed
-			// (ex: when view covers a subset of stored after stored has a update to that subset).
-			allowsRepoSuperset(this.policy, stored, this.schema)
-				? Compatibility.Compatible
-				: // TODO: this assumes adapters can translate in both directions. In general this will not be true.
-					// TODO: this also assumes that schema updates to the adapted repo would translate to
-					// updates on the stored schema, which is also likely untrue.
-					// // TODO: support adapters
-					// allowsRepoSuperset(this.policy, adapted.adaptedForViewSchema, this.storedSchema)
-					// ? Compatibility.RequiresAdapters // Requires schema updates. TODO: consider adapters that can update writes.
-					Compatibility.Incompatible;
-
-		// Since the above does not consider partial updates,
-		// we can improve the tolerance a bit by considering the op-op update:
-		writeAllowingStoredSchemaUpdates = Math.max(writeAllowingStoredSchemaUpdates, write);
-
-		return { read, write, writeAllowingStoredSchemaUpdates };
+		// View schema allows a subset of documents that stored schema does, and the discrepancies are allowed by policy
+		// determined by the view schema (i.e. objects with extra optional fields in the stored schema have opted into allowing this.
+		// In the future, this would also include things like:
+		// - fields with more allowed types in the stored schema than in the view schema have out-of-schema "unknown content" adapters
+		let canView = true;
+		// View schema allows a superset of documents that stored schema does, hence the document could be upgraded to use a persisted version
+		// of this view schema as its stored schema.
+		let canUpgrade = true;
+
+		const updateCompatibilityFromFieldDiscrepancy = (discrepancy: FieldDiscrepancy): void => {
+			switch (discrepancy.mismatch) {
+				case "allowedTypes": {
+					// Since we only track the symmetric difference between the allowed types in the view and
+					// stored schemas, it's sufficient to check if any extra allowed types still exist in the
+					// stored schema.
+					if (
+						discrepancy.stored.some(
+							(identifier) =>
+								!isNeverTree(this.policy, stored, stored.nodeSchema.get(identifier)),
+						)
+					) {
+						// Stored schema has extra allowed types that the view schema does not.
+						canUpgrade = false;
+						canView = false;
+					}
+
+					if (
+						discrepancy.view.some(
+							(identifier) =>
+								!isNeverTree(
+									this.policy,
+									this.viewSchemaAsStored,
+									this.viewSchemaAsStored.nodeSchema.get(identifier),
+								),
+						)
+					) {
+						// View schema has extra allowed types that the stored schema does not.
+						canView = false;
+					}
+					break;
+				}
+				case "fieldKind": {
+					const result = comparePosetElements(
+						discrepancy.stored,
+						discrepancy.view,
+						fieldRealizer,
+					);
+
+					if (result === PosetComparisonResult.Greater) {
+						// Stored schema is more relaxed than view schema.
+						canUpgrade = false;
+						if (
+							discrepancy.view === FieldKinds.forbidden.identifier &&
+							discrepancy.identifier !== undefined &&
+							this.policy.allowUnknownOptionalFields(discrepancy.identifier)
+						) {
+							// When the application has opted into it, we allow viewing documents which have additional
+							// optional fields in the stored schema that are not present in the view schema.
+						} else {
+							canView = false;
+						}
+					}
+
+					if (result === PosetComparisonResult.Less) {
+						// View schema is more relaxed than stored schema.
+						canView = false;
+					}
+
+					if (result === PosetComparisonResult.Incomparable) {
+						canUpgrade = false;
+						canView = false;
+					}
+
+					break;
+				}
+				case "valueSchema": {
+					canView = false;
+					canUpgrade = false;
+					break;
+				}
+				default:
+					unreachableCase(discrepancy);
+			}
+		};
+
+		for (const discrepancy of getAllowedContentDiscrepancies(
+			this.viewSchemaAsStored,
+			stored,
+		)) {
+			if (!canView && !canUpgrade) {
+				break;
+			}
+
+			switch (discrepancy.mismatch) {
+				case "nodeKind": {
+					const viewNodeSchema = this.viewSchemaAsStored.nodeSchema.get(
+						discrepancy.identifier,
+					);
+					const storedNodeSchema = stored.nodeSchema.get(discrepancy.identifier);
+					// We conservatively do not allow node types to change.
+					// The only time this might be valid in the sense that the data canonically converts is converting an object node
+					// to a map node over the union of all the object fields' types.
+					if (discrepancy.stored === undefined) {
+						const viewIsNever =
+							viewNodeSchema !== undefined
+								? isNeverTree(this.policy, this.viewSchemaAsStored, viewNodeSchema)
+								: true;
+						if (!viewIsNever) {
+							// View schema has added a node type that the stored schema doesn't know about.
+							canView = false;
+						}
+					} else if (discrepancy.view === undefined) {
+						const storedIsNever =
+							storedNodeSchema !== undefined
+								? isNeverTree(this.policy, stored, storedNodeSchema)
+								: true;
+						if (!storedIsNever) {
+							// Stored schema has a node type that the view schema doesn't know about.
+							canUpgrade = false;
+						}
+					} else {
+						// Node type exists in both schemas but has changed. We conservatively never allow this.
+						const storedIsNever =
+							storedNodeSchema !== undefined
+								? isNeverTree(this.policy, stored, storedNodeSchema)
+								: true;
+						const viewIsNever =
+							viewNodeSchema !== undefined
+								? isNeverTree(this.policy, this.viewSchemaAsStored, viewNodeSchema)
+								: true;
+						if (!storedIsNever || !viewIsNever) {
+							canView = false;
+							canUpgrade = false;
+						}
+					}
+					break;
+				}
+				case "valueSchema":
+				case "allowedTypes":
+				case "fieldKind": {
+					updateCompatibilityFromFieldDiscrepancy(discrepancy);
+					break;
+				}
+				case "fields": {
+					discrepancy.differences.forEach(updateCompatibilityFromFieldDiscrepancy);
+					break;
+				}
+				// No default
+			}
+		}
+
+		return {
+			canView,
+			canUpgrade,
+			isEquivalent: canView && canUpgrade,
+		};
 	}
 
 	/**
@@ -102,8 +241,15 @@ export class ViewSchema {
 		// since there never is a reason to have a never type as an adapter input,
 		// and its impossible for an adapter to be correctly implemented if its output type is never
 		// (unless its input is also never).
+
 		for (const adapter of this.adapters?.tree ?? []) {
-			if (isNeverTree(this.policy, this.schema, this.schema.nodeSchema.get(adapter.output))) {
+			if (
+				isNeverTree(
+					this.policy,
+					this.viewSchemaAsStored,
+					this.viewSchemaAsStored.nodeSchema.get(adapter.output),
+				)
+			) {
 				fail("tree adapter for stored adapter.output should not be never");
 			}
 		}

package/src/simple-tree/index.ts

@@ -35,6 +35,7 @@ export {
 	type SchemaCompatibilityStatus,
 	type ITreeConfigurationOptions,
 	SchemaFactory,
+	type SchemaFactoryObjectOptions,
 	type ScopedSchemaName,
 	type ValidateRecursiveSchema,
 	type FixRecursiveArraySchema,
@@ -118,6 +119,10 @@ export {
 	conciseFromCursor,
 	createFromCursor,
 	asTreeViewAlpha,
+	customFromCursorStored,
+	type CustomTreeNode,
+	type CustomTreeValue,
+	tryStoredSchemaAsArray,
 } from "./api/index.js";
 export {
 	type NodeFromSchema,
@@ -166,6 +171,7 @@ export {
 	type ObjectFromSchemaRecord,
 	type TreeObjectNode,
 	setField,
+	createUnknownOptionalFieldPolicy,
 } from "./objectNode.js";
 export type { TreeMapNode, MapNodeInsertableData } from "./mapNode.js";
 export {