@kyneta/yjs-schema 1.6.0 → 1.7.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { BACKING_DOC, KIND, NATIVE, RawPath, STRUCTURAL_YJS_CLIENT_ID, SYNC_COLLABORATIVE, Schema, Zero, advanceSchema, applyChanges, base64ToUint8Array, buildWritableContext, change, createBindingTarget, createDoc, createRef, deriveSchemaBinding, executeBatch, expandMapOpsToLeaves, exportEntirety, exportSince, merge, richTextChange, subscribe, subscribeNode, uint8ArrayToBase64, unwrap, version, versionVectorCompare, versionVectorMeet } from "@kyneta/schema";
+import { BACKING_DOC, KIND, NATIVE, RawPath, STRUCTURAL_YJS_CLIENT_ID, SYNC_COLLABORATIVE, Schema, applyChange, applyChanges, base64ToUint8Array, buildWritableContext, change, createBindingTarget, createDoc, createMaterializeInterpreter, createRef, deriveSchemaBinding, executeBatch, expandMapOpsToLeaves, exportEntirety, exportSince, foldPath, interpret, isNonNullObject, materializeContextFromResolver, merge, pathSchema, plainReader, richTextChange, subscribe, subscribeNode, uint8ArrayToBase64, unwrap, version, versionVectorCompare, versionVectorMeet } from "@kyneta/schema";
 import * as Y from "yjs";
 import { createSnapshot, decodeStateVector, encodeSnapshot, encodeStateVector, snapshot } from "yjs";
 //#region src/populate.ts
@@ -10,14 +10,10 @@ import { createSnapshot, decodeStateVector, encodeSnapshot, encodeStateVector, s
 * schema's fields, and creates empty containers for each field within a
 * single `doc.transact()` call for atomicity.
 *
-* When `conditional` is true, fields that already exist in the root map
-* are skipped. This is the correct mode after hydration — containers
-* present from stored state must not be overwritten (each `rootMap.set()`
-* is a CRDT write that advances the version vector and may conflict
-* with stored operations).
-*
-* When `conditional` is false (default), all fields are created
-* unconditionally. This is the correct mode for fresh documents.
+* Container fields (text, product, sequence, map) are created if absent;
+* existing containers are preserved (calling `rootMap.set()` on a field
+* that already exists would be a destructive CRDT write). Scalar and sum
+* fields are no-ops — the materializer handles zeros.
 *
 * **Structural identity:** This function temporarily sets `doc.clientID`
 * to `STRUCTURAL_YJS_CLIENT_ID` (0) for the duration of container creation,
@@ -31,22 +27,16 @@ import { createSnapshot, decodeStateVector, encodeSnapshot, encodeStateVector, s
 *
 * @param doc - The Y.Doc to prepare
 * @param schema - The root document schema (a ProductSchema)
-* @param conditional - If true, skip fields that already exist in the root map.
-*   Context: jj:smmulzkm (two-phase substrate construction)
 * @param binding - Optional SchemaBinding for identity-keyed containers.
 */
-function ensureContainers(doc, schema, conditional = false, binding) {
+function ensureContainers(doc, schema, binding) {
 	const rootMap = doc.getMap("root");
 	if (schema[KIND] !== "product") return;
 	const savedClientID = doc.clientID;
 	doc.clientID = STRUCTURAL_YJS_CLIENT_ID;
 	try {
 		doc.transact(() => {
-			for (const [key, fieldSchema] of Object.entries(schema.fields).sort(([a], [b]) => a.localeCompare(b))) {
-				const mapKey = binding?.forward.get(key) ?? key;
-				if (conditional && rootMap.has(mapKey)) continue;
-				ensureRootField(rootMap, mapKey, fieldSchema, binding, key);
-			}
+			for (const [key, fieldSchema] of Object.entries(schema.fields).sort(([a], [b]) => a.localeCompare(b))) ensureRootField(rootMap, binding?.forward.get(key) ?? key, fieldSchema, binding, key);
 		});
 	} finally {
 		doc.clientID = savedClientID;
@@ -60,7 +50,7 @@ function ensureContainers(doc, schema, conditional = false, binding) {
 * - `"product"` → empty Y.Map (recursive for nested products)
 * - `"sequence"` → empty Y.Array
 * - `"map"` → empty Y.Map
-* - `"scalar"` / `"sum"` → Zero.structural default
+* - `"scalar"` / `"sum"` → no-op (materializer zero fallback)
 * - `"counter"` / `"set"` / `"tree"` / `"movable"` → throw (not supported by Yjs)
 *
 * @param rootMap - The root Y.Map to set the field on.
@@ -70,6 +60,7 @@ function ensureContainers(doc, schema, conditional = false, binding) {
 * @param prefix - The absolute schema path prefix for this field (used for nested lookups).
 */
 function ensureRootField(rootMap, key, fieldSchema, binding, prefix) {
+	if (rootMap.has(key)) return;
 	switch (fieldSchema[KIND]) {
 		case "text":
 		case "richtext":
@@ -85,11 +76,7 @@ function ensureRootField(rootMap, key, fieldSchema, binding, prefix) {
 			rootMap.set(key, new Y.Map());
 			return;
 		case "scalar":
-		case "sum": {
-			const zero = Zero.structural(fieldSchema);
-			if (zero !== void 0) rootMap.set(key, zero);
-			return;
-		}
+		case "sum": return;
 		case "counter":
 		case "set":
 		case "tree":
@@ -102,7 +89,7 @@ function ensureRootField(rootMap, key, fieldSchema, binding, prefix) {
 *
 * Only creates containers for fields that require Yjs shared types
 * (text → Y.Text, product → Y.Map, sequence → Y.Array, map → Y.Map).
-* Scalar and sum fields are set to their structural zero defaults.
+* Scalar and sum fields are skipped (materializer zero fallback).
 *
 * **Identity-keying:** When a `binding` is provided, computes the
 * absolute schema path for each nested field (`prefix.fieldName`) and
@@ -134,11 +121,7 @@ function ensureMapContainers(schema, binding, prefix) {
 				map.set(mapKey, new Y.Map());
 				break;
 			case "scalar":
-			case "sum": {
-				const zero = Zero.structural(fieldSchema);
-				if (zero !== void 0) map.set(mapKey, zero);
-				break;
-			}
+			case "sum": break;
 			case "counter":
 			case "set":
 			case "tree":
@@ -158,68 +141,29 @@ function ensureMapContainers(schema, binding, prefix) {
 * - `Y.Text` → terminal (cannot step further)
 * - Plain value → terminal (return `undefined`)
 *
-* @param current - The current position (a Yjs shared type or plain value)
-* @param segment - The path segment to follow
-* @param identity - Optional identity hash to use instead of the segment's resolved value
+* `_nextSchema` is part of the `PathStepper` contract for Loro's root
+* dispatch but is unused here — Yjs's `instanceof` dispatch doesn't
+* need to look ahead at the next schema kind.
 */
-function stepIntoYjs(current, segment, identity) {
+const stepIntoYjs = (current, _nextSchema, segment, identity) => {
 	const resolved = segment.resolve();
 	if (current instanceof Y.Map) return current.get(identity ?? resolved);
 	if (current instanceof Y.Array) return current.get(resolved);
 	if (current instanceof Y.Text) throw new Error(`yjs-resolve: cannot step into Y.Text`);
-}
+};
 /**
 * Resolve a Yjs shared type (or plain value) at the given path.
 *
-* Left-folds over path segments using `advanceSchema` for pure schema
-* descent and `stepIntoYjs` for Yjs-specific navigation.
-*
-* When a `binding` is provided, each step computes the absolute schema
-* path and looks up the identity hash from `binding.forward`. This
-* identity hash is used instead of the field name at every product-field
-* boundary (root and nested).
+* Thin wrapper around `foldPath(stepIntoYjs, ...)`. Returns the
+* `PathFoldResult` shape from core — `{ resolved, schema }`.
 *
-* Returns both the Yjs shared type (or plain value) and the schema at
-* the terminal position. For an empty path, returns the root map and
-* root schema.
+* When a `binding` is provided, every product-field boundary uses the
+* identity hash from `binding.forward` instead of the field name.
 *
-* @param rootMap - The root `Y.Map` obtained via `doc.getMap("root")`
-* @param rootSchema - The root document schema
-* @param path - The path to resolve
-* @param binding - Optional SchemaBinding for identity-keyed navigation.
+* For an empty path, returns the root map and root schema.
 */
 function resolveYjsType(rootMap, rootSchema, path, binding) {
-	let current = rootMap;
-	let schema = rootSchema;
-	let absPath = "";
-	for (let i = 0; i < path.length; i++) {
-		const seg = path.segments[i];
-		if (!seg) throw new Error(`Missing segment at index ${i}`);
-		const nextSchema = advanceSchema(schema, seg);
-		let identity;
-		if (binding && seg.role === "key") {
-			const segStr = seg.resolve();
-			absPath = absPath ? `${absPath}.${segStr}` : segStr;
-			identity = binding.forward.get(absPath);
-		}
-		current = stepIntoYjs(current, seg, identity);
-		schema = nextSchema;
-		if (schema[KIND] === "sum" && i + 1 < path.length) {
-			for (let j = i + 1; j < path.length; j++) {
-				const remaining = path.segments[j];
-				if (!remaining) throw new Error(`Missing segment at index ${j}`);
-				current = current?.[remaining.resolve()];
-			}
-			return {
-				resolved: current,
-				schema
-			};
-		}
-	}
-	return {
-		resolved: current,
-		schema
-	};
+	return foldPath(rootMap, rootSchema, path, stepIntoYjs, binding);
 }
 //#endregion
 //#region src/change-mapping.ts
@@ -254,6 +198,7 @@ function applyChangeToYjs(rootMap, rootSchema, path, change, binding) {
 			return;
 		case "increment": throw new Error(`Yjs substrate does not support "${change.type}" changes. Counter requires a CRDT backend that supports counters (e.g. Loro). Attempted IncrementChange with amount=${change.amount} at path [${pathToString(path)}].`);
 		case "tree": throw new Error(`Yjs substrate does not support "${change.type}" changes. Tree requires a CRDT backend that supports trees (e.g. Loro). Attempted TreeChange at path [${pathToString(path)}].`);
+		case "set-op": throw new Error(`Yjs substrate does not support "${change.type}" changes. Schema.set requires "add-wins-per-key" which is not in YjsLaws. Attempted SetChange at path [${pathToString(path)}].`);
 		default: throw new Error(`applyChangeToYjs: unsupported change type "${change.type}"`);
 	}
 }
@@ -284,7 +229,7 @@ function applyRichTextChange(rootMap, rootSchema, path, change, binding) {
 function applySequenceChange(rootMap, rootSchema, path, change, binding) {
 	const { resolved } = resolveYjsType(rootMap, rootSchema, path, binding);
 	if (!(resolved instanceof Y.Array)) throw new Error(`applyChangeToYjs: SequenceChange target at path [${pathToString(path)}] is not a Y.Array`);
-	const itemSchema = getItemSchema(resolveSchemaAtPath(rootSchema, path));
+	const itemSchema = getItemSchema(pathSchema(rootSchema, path));
 	let cursor = 0;
 	for (const instruction of change.instructions) if ("retain" in instruction) cursor += instruction.retain;
 	else if ("delete" in instruction) resolved.delete(cursor, instruction.delete);
@@ -298,13 +243,13 @@ function applySequenceChange(rootMap, rootSchema, path, change, binding) {
 function applyMapChange(rootMap, rootSchema, path, change, binding) {
 	const { resolved } = resolveYjsType(rootMap, rootSchema, path, binding);
 	if (!(resolved instanceof Y.Map)) throw new Error(`applyChangeToYjs: MapChange target at path [${pathToString(path)}] is not a Y.Map`);
-	const targetSchema = resolveSchemaAtPath(rootSchema, path);
+	const targetSchema = pathSchema(rootSchema, path);
 	if (change.delete) for (const key of change.delete) resolved.delete(key);
 	if (change.set) for (const [key, value] of Object.entries(change.set)) {
 		const yjsValue = maybeCreateSharedType(value, getFieldSchema(targetSchema, key));
 		let mapKey = key;
 		if (binding && targetSchema[KIND] === "product") {
-			const parentAbsPath = path.segments.filter((s) => s.role === "key").map((s) => s.resolve()).join(".");
+			const parentAbsPath = path.segments.filter((s) => s.role === "field").map((s) => s.resolve()).join(".");
 			const absPath = parentAbsPath ? `${parentAbsPath}.${key}` : key;
 			const identity = binding.forward.get(absPath);
 			if (identity) mapKey = identity;
@@ -319,18 +264,18 @@ function applyReplaceChange(rootMap, rootSchema, path, change, binding) {
 	const parentPath = path.slice(0, -1);
 	const { resolved: parent } = resolveYjsType(rootMap, rootSchema, parentPath, binding);
 	const resolved = lastSeg.resolve();
-	if (parent instanceof Y.Map && lastSeg.role === "key") {
-		const targetSchema = resolveSchemaAtPath(rootSchema, path);
+	if (parent instanceof Y.Map && (lastSeg.role === "field" || lastSeg.role === "entry")) {
+		const targetSchema = pathSchema(rootSchema, path);
 		const yjsValue = maybeCreateSharedType(change.value, targetSchema);
 		let mapKey = resolved;
-		if (binding) {
-			const absPath = path.segments.filter((s) => s.role === "key").map((s) => s.resolve()).join(".");
+		if (binding && lastSeg.role === "field") {
+			const absPath = path.segments.filter((s) => s.role === "field").map((s) => s.resolve()).join(".");
 			const identity = binding.forward.get(absPath);
 			if (identity) mapKey = identity;
 		}
 		parent.set(mapKey, yjsValue);
 	} else if (parent instanceof Y.Array && lastSeg.role === "index") {
-		const targetSchema = resolveSchemaAtPath(rootSchema, path);
+		const targetSchema = pathSchema(rootSchema, path);
 		const yjsValue = maybeCreateSharedType(change.value, targetSchema);
 		parent.delete(resolved, 1);
 		parent.insert(resolved, [yjsValue]);
@@ -431,7 +376,7 @@ function createStructuredMap(obj, productSchema) {
 function eventsToOps(events, schema, binding) {
 	const ops = [];
 	for (const event of events) {
-		const kynetaPath = yjsPathToKynetaPath(event.path, binding);
+		const kynetaPath = yjsPathToKynetaPath(event.path, schema, binding);
 		const change = eventToChange(event, schema, kynetaPath, binding);
 		if (change) ops.push({
 			path: kynetaPath,
@@ -441,21 +386,44 @@ function eventsToOps(events, schema, binding) {
 	return expandMapOpsToLeaves(ops, schema);
 }
 /**
-* Convert a Yjs event path (array of string | number) to a kyneta Path.
+* Convert a Yjs event path to a kyneta `RawPath`, walking the schema
+* alongside so each segment is classified as field / entry / index by
+* the current schema kind.
 *
-* `event.path` from `observeDeep` is relative to the observed type.
-* Strings become key segments, numbers become index segments.
+* Why schema-aware and not "did the inverse lookup hit?": the binding's
+* inverse map only covers declared product-field positions reachable
+* without crossing a runtime-keyed container. A declared struct field
+* nested under a `record(...)` value type is reachable via Yjs but
+* absent from `binding.inverse` — without the schema walk it would be
+* misclassified as an entry and then rejected by `advanceSchema`.
 */
-function yjsPathToKynetaPath(yjsPath, binding) {
+function yjsPathToKynetaPath(yjsPath, rootSchema, binding) {
 	let path = RawPath.empty;
+	let schema = rootSchema;
 	for (const segment of yjsPath) if (typeof segment === "string") {
+		let leaf = segment;
 		const absPath = binding?.inverse.get(segment);
 		if (absPath) {
 			const lastDot = absPath.lastIndexOf(".");
-			const leaf = lastDot >= 0 ? absPath.slice(lastDot + 1) : absPath;
+			leaf = lastDot >= 0 ? absPath.slice(lastDot + 1) : absPath;
+		}
+		const kind = schema?.[KIND];
+		if (kind === "product") {
 			path = path.field(leaf);
-		} else path = path.field(segment);
-	} else if (typeof segment === "number") path = path.item(segment);
+			schema = schema?.fields[leaf];
+		} else if (kind === "map" || kind === "set" || kind === "tree") {
+			path = path.entry(leaf);
+			schema = schema?.item;
+		} else {
+			path = path.entry(leaf);
+			schema = void 0;
+		}
+	} else if (typeof segment === "number") {
+		path = path.item(segment);
+		const kind = schema?.[KIND];
+		if (kind === "sequence" || kind === "movable") schema = schema.item;
+		else schema = void 0;
+	}
 	return path;
 }
 /**
@@ -470,7 +438,7 @@ function yjsPathToKynetaPath(yjsPath, binding) {
 */
 function eventToChange(event, rootSchema, kynetaPath, binding) {
 	if (event.target instanceof Y.Text) {
-		if (resolveSchemaAtPath(rootSchema, kynetaPath)[KIND] === "richtext") return richTextEventToChange(event);
+		if (pathSchema(rootSchema, kynetaPath)[KIND] === "richtext") return richTextEventToChange(event);
 		return textEventToChange(event);
 	}
 	if (event.target instanceof Y.Array) return arrayEventToChange(event);
@@ -583,17 +551,6 @@ function extractEventValue(value) {
 	return value;
 }
 /**
-* Resolve the schema at a given path by walking through advanceSchema.
-*/
-function resolveSchemaAtPath(rootSchema, path) {
-	let schema = rootSchema;
-	for (const seg of path.segments) {
-		schema = advanceSchema(schema, seg);
-		if (schema[KIND] === "sum") return schema;
-	}
-	return schema;
-}
-/**
 * Get the item schema from a sequence schema, if available.
 */
 function getItemSchema(schema) {
@@ -612,35 +569,7 @@ function pathToString(path) {
 	return path.segments.map((seg) => String(seg.resolve())).join(".");
 }
 //#endregion
-//#region src/position.ts
-/** Map kyneta Side to Yjs assoc. Left → -1 (left-sticky), Right → 0 (right-sticky). */
-function toYjsAssoc(side) {
-	return side === "left" ? -1 : 0;
-}
-/** Map Yjs assoc to kyneta Side. Negative → left, non-negative → right. */
-function fromYjsAssoc(assoc) {
-	return assoc < 0 ? "left" : "right";
-}
-var YjsPosition = class {
-	rpos;
-	doc;
-	side;
-	constructor(rpos, doc) {
-		this.rpos = rpos;
-		this.doc = doc;
-		this.side = fromYjsAssoc(rpos.assoc);
-	}
-	resolve() {
-		const abs = Y.createAbsolutePositionFromRelativePosition(this.rpos, this.doc);
-		return abs ? abs.index : null;
-	}
-	encode() {
-		return Y.encodeRelativePosition(this.rpos);
-	}
-	transform(_instructions) {}
-};
-//#endregion
-//#region src/reader.ts
+//#region src/yjs-extract.ts
 /**
 * Extract a plain value from a Yjs shared type or return a plain value as-is.
 *
@@ -674,50 +603,71 @@ function yTextToRichTextDelta(ytext) {
 	}
 	return spans;
 }
-/**
-* Creates a Reader that navigates the Yjs shared type tree live,
-* using the schema as a type witness to determine navigation at each
-* path segment.
-*
-* The reader is a live view — mutations to the underlying Y.Doc
-* (via `doc.transact()`, or `Y.applyUpdate()`) are immediately
-* visible through the reader.
-*
-* Internally obtains the root map via `doc.getMap("root")`.
-*
-* @param doc - The Y.Doc to read from.
-* @param schema - The root schema for the document.
-* @param binding - Optional SchemaBinding for identity-keyed navigation.
-*/
-function yjsReader(doc, schema, binding) {
-	const rootMap = doc.getMap("root");
+//#endregion
+//#region src/materialize.ts
+function createYjsResolver(rootMap, rootSchema, binding) {
 	return {
-		read(path) {
-			if (path.length === 0) return rootMap.toJSON();
-			const { resolved, schema: nodeSchema } = resolveYjsType(rootMap, schema, path, binding);
-			if (nodeSchema[KIND] === "richtext" && resolved instanceof Y.Text) return yTextToRichTextDelta(resolved);
-			return extractValue(resolved);
+		resolveValue(path) {
+			return extractValue(resolveYjsType(rootMap, rootSchema, path, binding).resolved);
+		},
+		resolveText(path) {
+			const { resolved } = resolveYjsType(rootMap, rootSchema, path, binding);
+			if (resolved instanceof Y.Text) return resolved.toJSON();
+			const value = extractValue(resolved);
+			return typeof value === "string" ? value : void 0;
 		},
-		arrayLength(path) {
-			const { resolved } = resolveYjsType(rootMap, schema, path, binding);
+		resolveCounter(_path) {},
+		resolveRichText(path) {
+			const { resolved } = resolveYjsType(rootMap, rootSchema, path, binding);
+			if (resolved instanceof Y.Text) return yTextToRichTextDelta(resolved);
+		},
+		resolveLength(path) {
+			const { resolved } = resolveYjsType(rootMap, rootSchema, path, binding);
 			if (resolved instanceof Y.Array) return resolved.length;
-			if (Array.isArray(resolved)) return resolved.length;
-			return 0;
+			return Array.isArray(resolved) ? resolved.length : 0;
 		},
-		keys(path) {
-			const { resolved } = resolveYjsType(rootMap, schema, path, binding);
+		resolveKeys(path) {
+			const { resolved } = resolveYjsType(rootMap, rootSchema, path, binding);
 			if (resolved instanceof Y.Map) return Array.from(resolved.keys());
-			if (resolved !== null && resolved !== void 0 && typeof resolved === "object" && !Array.isArray(resolved)) return Object.keys(resolved);
-			return [];
+			return isNonNullObject(resolved) ? Object.keys(resolved) : [];
 		},
-		hasKey(path, key) {
-			const { resolved } = resolveYjsType(rootMap, schema, path, binding);
-			if (resolved instanceof Y.Map) return resolved.has(key);
-			if (resolved !== null && resolved !== void 0 && typeof resolved === "object" && !Array.isArray(resolved)) return key in resolved;
-			return false;
+		resolveForest(_path) {
+			return [];
 		}
 	};
 }
+function materializeYjsShadow(doc, schema, binding) {
+	const resolver = createYjsResolver(doc.getMap("root"), schema, binding);
+	return interpret(schema, createMaterializeInterpreter(resolver), materializeContextFromResolver(resolver));
+}
+//#endregion
+//#region src/position.ts
+/** Map kyneta Side to Yjs assoc. Left → -1 (left-sticky), Right → 0 (right-sticky). */
+function toYjsAssoc(side) {
+	return side === "left" ? -1 : 0;
+}
+/** Map Yjs assoc to kyneta Side. Negative → left, non-negative → right. */
+function fromYjsAssoc(assoc) {
+	return assoc < 0 ? "left" : "right";
+}
+var YjsPosition = class {
+	rpos;
+	doc;
+	side;
+	constructor(rpos, doc) {
+		this.rpos = rpos;
+		this.doc = doc;
+		this.side = fromYjsAssoc(rpos.assoc);
+	}
+	resolve() {
+		const abs = Y.createAbsolutePositionFromRelativePosition(this.rpos, this.doc);
+		return abs ? abs.index : null;
+	}
+	encode() {
+		return Y.encodeRelativePosition(this.rpos);
+	}
+	transform(_instructions) {}
+};
 //#endregion
 //#region src/version.ts
 /**
@@ -892,33 +842,35 @@ const KYNETA_ORIGIN = "kyneta-prepare";
 */
 function createYjsSubstrate(doc, schema, binding) {
 	const pendingChanges = [];
-	let inOurTransaction = false;
 	let pendingMergeOrigin;
 	let cachedCtx;
 	let accumulatedDs = Y.createDeleteSetFromStructStore(doc.store);
 	const rootMap = doc.getMap("root");
-	const reader = yjsReader(doc, schema, binding);
+	const shadow = materializeYjsShadow(doc, schema, binding);
+	const reader = plainReader(shadow);
 	const substrate = {
 		[BACKING_DOC]: doc,
 		reader,
-		prepare(path, change) {
-			if (!inOurTransaction) pendingChanges.push({
+		prepare(path, change, options) {
+			if (!options?.replay) applyChange(shadow, path, change);
+			if (options?.replay) return;
+			pendingChanges.push({
 				path,
 				change
 			});
 		},
-		onFlush(_origin) {
-			if (!inOurTransaction && pendingChanges.length > 0) {
-				inOurTransaction = true;
-				try {
-					doc.transact(() => {
-						for (const { path, change } of pendingChanges) applyChangeToYjs(rootMap, schema, path, change, binding);
-					}, KYNETA_ORIGIN);
-					pendingChanges.length = 0;
-				} finally {
-					inOurTransaction = false;
-				}
+		onFlush(options) {
+			if (options?.replay) {
+				const fresh = materializeYjsShadow(doc, schema, binding);
+				for (const key of Object.keys(fresh)) shadow[key] = fresh[key];
+				for (const key of Object.keys(shadow)) if (!(key in fresh)) delete shadow[key];
+				return;
 			}
+			if (pendingChanges.length === 0) return;
+			doc.transact(() => {
+				for (const { path, change } of pendingChanges) applyChangeToYjs(rootMap, schema, path, change, binding);
+			}, KYNETA_ORIGIN);
+			pendingChanges.length = 0;
 		},
 		context() {
 			if (!cachedCtx) {
@@ -971,11 +923,11 @@ function createYjsSubstrate(doc, schema, binding) {
 				return null;
 			}
 		},
-		merge(payload, origin) {
+		merge(payload, options) {
 			if (payload.encoding !== "binary" || !(payload.data instanceof Uint8Array)) throw new Error("YjsSubstrate.merge expects binary-encoded payloads. If you recently switched CRDT backends, stale clients may be sending incompatible data.");
-			pendingMergeOrigin = origin;
+			pendingMergeOrigin = options?.origin;
 			try {
-				Y.applyUpdate(doc, payload.data, origin ?? "remote");
+				Y.applyUpdate(doc, payload.data, options?.origin ?? "remote");
 			} finally {
 				pendingMergeOrigin = void 0;
 			}
@@ -987,13 +939,10 @@ function createYjsSubstrate(doc, schema, binding) {
 		if (ops.length === 0) return;
 		if (transaction.deleteSet.clients.size > 0) accumulatedDs = Y.mergeDeleteSets([accumulatedDs, transaction.deleteSet]);
 		const origin = pendingMergeOrigin ?? (typeof transaction.origin === "string" ? transaction.origin : void 0);
-		const ctx = substrate.context();
-		inOurTransaction = true;
-		try {
-			executeBatch(ctx, ops, origin);
-		} finally {
-			inOurTransaction = false;
-		}
+		executeBatch(substrate.context(), ops, {
+			origin,
+			replay: true
+		});
 	});
 	doc.on("afterTransaction", (transaction) => {
 		if (transaction.origin === KYNETA_ORIGIN && transaction.deleteSet.clients.size > 0) accumulatedDs = Y.mergeDeleteSets([accumulatedDs, transaction.deleteSet]);
@@ -1078,7 +1027,7 @@ function createYjsReplica(doc) {
 				return null;
 			}
 		},
-		merge(payload, _origin) {
+		merge(payload, _options) {
 			if (payload.encoding !== "binary" || !(payload.data instanceof Uint8Array)) throw new Error("YjsReplica.merge expects binary-encoded payloads. If you recently switched CRDT backends, stale clients may be sending incompatible data.");
 			Y.applyUpdate(currentDoc, payload.data);
 		}
@@ -1111,13 +1060,13 @@ const yjsSubstrateFactory = {
 	upgrade(replica, schema) {
 		const doc = replica[BACKING_DOC];
 		const binding = trivialBinding(schema);
-		ensureContainers(doc, schema, true, binding);
+		ensureContainers(doc, schema, binding);
 		return createYjsSubstrate(doc, schema, binding);
 	},
 	create(schema) {
 		const doc = new Y.Doc();
 		const binding = trivialBinding(schema);
-		ensureContainers(doc, schema, false, binding);
+		ensureContainers(doc, schema, binding);
 		return createYjsSubstrate(doc, schema, binding);
 	},
 	fromEntirety(payload, schema) {
@@ -1164,13 +1113,13 @@ function createYjsFactory(peerId, binding) {
 		upgrade(replica, schema) {
 			const doc = replica[BACKING_DOC];
 			doc.clientID = numericClientId;
-			ensureContainers(doc, schema, true, binding);
+			ensureContainers(doc, schema, binding);
 			return createYjsSubstrate(doc, schema, binding);
 		},
 		create(schema) {
 			const doc = new Y.Doc();
 			doc.clientID = numericClientId;
-			ensureContainers(doc, schema, false, binding);
+			ensureContainers(doc, schema, binding);
 			return createYjsSubstrate(doc, schema, binding);
 		},
 		fromEntirety(payload, schema) {
@@ -1202,6 +1151,6 @@ const yjs = createBindingTarget({
 	syncProtocol: SYNC_COLLABORATIVE
 });
 //#endregion
-export { NATIVE, Schema, YjsPosition, YjsVersion, applyChangeToYjs, applyChanges, change, createDoc, createRef, createYjsSubstrate, ensureContainers, eventsToOps, exportEntirety, exportSince, fromYjsAssoc, merge, resolveYjsType, stepIntoYjs, subscribe, subscribeNode, toYjsAssoc, unwrap, version, yjs, yjsReader, yjsReplicaFactory, yjsSubstrateFactory };
+export { NATIVE, Schema, YjsPosition, YjsVersion, applyChangeToYjs, applyChanges, change, createDoc, createRef, createYjsSubstrate, ensureContainers, eventsToOps, exportEntirety, exportSince, fromYjsAssoc, merge, resolveYjsType, stepIntoYjs, subscribe, subscribeNode, toYjsAssoc, unwrap, version, yjs, yjsReplicaFactory, yjsSubstrateFactory };
 
 //# sourceMappingURL=index.js.map