@contember/bindx 0.1.46 → 0.1.47

package/src/handles/HasManyListHandle.ts

@@ -33,7 +33,10 @@ import { createAliasProxy } from './proxyFactory.js'
  * @typeParam TSelected - The selected subset of fields (defaults to TEntity for backwards compatibility)
  */
 export class HasManyListHandle<TEntity extends object = object, TSelected = TEntity> extends EntityRelatedHandle {
-	private itemHandleCacheRaw = new Map<string, EntityHandle<TEntity, TSelected>>()
+	// Per-item accessor cache, keyed by the item's canonical (post-rekey) id. Identity is the
+	// point: a still-listed item keeps the same proxy — and with it the same handle, which the
+	// proxy is the only reference to. Kept bounded by syncItemHandleCache, which drops ids
+	// that have left the list.
 	private itemHandleCacheProxy = new Map<string, EntityAccessor<TEntity, TSelected>>()
 
 	/** Runtime brand symbols for validation */
@@ -73,6 +76,9 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 		brands?: Set<symbol>,
 		alias?: string,
 		private readonly selection?: SelectionMeta,
+		// Segments from the query root down to this relation. Items do NOT inherit it:
+		// a has-many restarts the chain, mirroring the collector proxy.
+		private readonly relationPath: readonly string[] = [fieldName],
 	) {
 		super(parentEntityType, parentEntityId, store, dispatcher)
 		this.__brands = brands
@@ -90,8 +96,31 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 		brands?: Set<symbol>,
 		alias?: string,
 		selection?: SelectionMeta,
+		relationPath?: readonly string[],
 	): HasManyAccessor<TEntity, TSelected> {
-		return createAliasProxy<HasManyListHandle<TEntity, TSelected>, HasManyAccessor<TEntity, TSelected>>(new HasManyListHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, itemType, store, dispatcher, schema, brands, alias, selection))
+		return createAliasProxy<HasManyListHandle<TEntity, TSelected>, HasManyAccessor<TEntity, TSelected>>(
+			HasManyListHandle.createRaw<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, itemType, store, dispatcher, schema, brands, alias, selection, relationPath),
+		)
+	}
+
+	/**
+	 * Creates the handle without the alias proxy. Mirrors {@link EntityHandle.createRaw}:
+	 * the class surface (e.g. {@link itemHandleCacheSize}) is not part of HasManyAccessor.
+	 */
+	static createRaw<TEntity extends object = object, TSelected = TEntity>(
+		parentEntityType: string,
+		parentEntityId: string,
+		fieldName: string,
+		itemType: string,
+		store: SnapshotStore,
+		dispatcher: ActionDispatcher,
+		schema: SchemaRegistry,
+		brands?: Set<symbol>,
+		alias?: string,
+		selection?: SelectionMeta,
+		relationPath?: readonly string[],
+	): HasManyListHandle<TEntity, TSelected> {
+		return new HasManyListHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, itemType, store, dispatcher, schema, brands, alias, selection, relationPath)
 	}
 
 	/**
@@ -107,6 +136,7 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 			isArray: true,
 			isRelation: true,
 			targetType: this.itemType,
+			fullPath: this.relationPath,
 		}
 	}
 
@@ -115,21 +145,76 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 	 * Returns selection-aware EntityAccessors that support `item.fieldName.value`.
 	 * Includes planned connections and excludes planned removals.
 	 * Uses ordered IDs to preserve order including after move() operations.
+	 *
+	 * This is also where the item-accessor cache is pruned — see {@link syncItemHandleCache}.
 	 */
 	get items(): EntityAccessor<TEntity, TSelected>[] {
 		this.materializeEmbeddedItems()
 
 		// Use ordered IDs from store (handles removals, connections, and ordering)
-		const orderedIds = this.store.getHasManyOrderedIds(
+		const orderedIds = this.store.getPresentationHasManyOrderedIds(
 			this.entityType,
 			this.entityId,
 			this.fieldName,
 			this.alias,
 		)
 
+		this.syncItemHandleCache(orderedIds)
+
 		return orderedIds.map((id) => this.getItemHandle(id))
 	}
 
+	/**
+	 * Canonical cache key for an item id: a temp id follows its temp→persisted rekey, so a
+	 * lookup by the now-dead temp id reuses the persisted item's handle instead of minting a
+	 * duplicate for the same entity.
+	 */
+	private resolveItemKey(itemId: string): string {
+		return this.store.resolveEntityId(this.itemType, itemId)
+	}
+
+	/**
+	 * Drops cached item accessors for ids that have left the list. Without it the cache keeps an
+	 * accessor for every id the relation has ever shown, for as long as the parent handle lives
+	 * — a paginated / filtered / refetched has-many grows without bound.
+	 *
+	 * Runs before the accessors are resolved and never touches a live id, so an item that is
+	 * still listed keeps the exact same proxy and the exact same handle behind it.
+	 */
+	private syncItemHandleCache(liveIds: readonly string[]): void {
+		if (this.itemHandleCacheProxy.size === 0) return
+		this.canonicalizeItemHandleCache()
+
+		// While the parent persists, the presented list hides planned additions — pruning
+		// against it would drop handles that reappear as soon as the persist settles.
+		if (this.store.isPersisting(this.entityType, this.entityId)) return
+
+		const liveKeys = new Set(liveIds.map(id => this.resolveItemKey(id)))
+		for (const key of this.itemHandleCacheProxy.keys()) {
+			if (liveKeys.has(key)) continue
+			this.itemHandleCacheProxy.delete(key)
+		}
+	}
+
+	private canonicalizeItemHandleCache(): void {
+		for (const [key, proxy] of [...this.itemHandleCacheProxy]) {
+			const canonicalKey = this.resolveItemKey(key)
+			if (canonicalKey === key) continue
+			if (!this.itemHandleCacheProxy.has(canonicalKey)) {
+				this.itemHandleCacheProxy.set(canonicalKey, proxy)
+			}
+			this.itemHandleCacheProxy.delete(key)
+		}
+	}
+
+	/**
+	 * @internal Occupancy of the item-accessor cache. Exposed only so eviction tests can
+	 * assert the cache stays bounded; not part of the HasManyAccessor API.
+	 */
+	get itemHandleCacheSize(): number {
+		return this.itemHandleCacheProxy.size
+	}
+
 	/**
 	 * Propagates the parent's embedded has-many data into per-item snapshots and
 	 * ensures the has-many state exists in the store.
@@ -139,6 +224,12 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 	 * without ever reading `items`, and that path must also see populated data.
 	 * Idempotent within a render — guarded by hasEmbeddedDataChanged.
 	 *
+	 * For the same reason EVERY entry point that reads or writes the has-many state
+	 * calls this first — isDirty and the mutators as well as items/getById. An
+	 * embedded list has no state in the store until it is materialised, so a
+	 * consumer that never iterated saw isDirty === false and had its mutation land
+	 * on a state nobody reads. Keep new entry points on this guard.
+	 *
 	 * @returns false when there is no embedded list data to materialise.
 	 */
 	private materializeEmbeddedItems(): boolean {
@@ -274,11 +365,13 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 	 * Returns selection-aware EntityAccessor that supports direct field access.
 	 */
 	getItemHandle(itemId: string): EntityAccessor<TEntity, TSelected> {
-		let proxy = this.itemHandleCacheProxy.get(itemId)
+		this.canonicalizeItemHandleCache()
+		const key = this.resolveItemKey(itemId)
+		let proxy = this.itemHandleCacheProxy.get(key)
 
 		if (!proxy) {
 			const raw = EntityHandle.createRaw<TEntity, TSelected>(
-				itemId,
+				key,
 				this.itemType,
 				this.store,
 				this.dispatcher,
@@ -287,8 +380,7 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 				this.selection,
 			)
 			proxy = EntityHandle.wrapProxy(raw)
-			this.itemHandleCacheRaw.set(itemId, raw)
-			this.itemHandleCacheProxy.set(itemId, proxy)
+			this.itemHandleCacheProxy.set(key, proxy)
 		}
 
 		return proxy
@@ -311,6 +403,8 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 	 * Checks if the list is dirty (items added/removed/moved/connected/disconnected).
 	 */
 	get isDirty(): boolean {
+		this.materializeEmbeddedItems()
+
 		const state = this.store.getHasMany(
 			this.entityType,
 			this.entityId,
@@ -322,8 +416,7 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 
 		return (
 			state.plannedRemovals.size > 0 ||
-			state.plannedConnections.size > 0 ||
-			state.createdEntities.size > 0 ||
+			state.plannedAdditions.size > 0 ||
 			state.orderedIds !== null
 		)
 	}
@@ -340,6 +433,7 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 	 * Connects an existing entity to this has-many relation.
 	 */
 	connect(itemId: string): void {
+		this.materializeEmbeddedItems()
 		this.dispatcher.dispatch(
 			connectToList(this.entityType, this.entityId, this.fieldName, itemId, this.itemType, this.alias),
 		)
@@ -351,6 +445,7 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 	 * For created entities (via add()), cancels the add operation.
 	 */
 	disconnect(itemId: string): void {
+		this.materializeEmbeddedItems()
 		this.dispatcher.dispatch(
 			removeFromList(this.entityType, this.entityId, this.fieldName, itemId, 'disconnect', this.alias),
 		)
@@ -362,6 +457,7 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 	 * For created entities (via add()), cancels the add operation.
 	 */
 	delete(itemId: string): void {
+		this.materializeEmbeddedItems()
 		this.dispatcher.dispatch(
 			removeFromList(this.entityType, this.entityId, this.fieldName, itemId, 'delete', this.alias),
 		)
@@ -373,16 +469,21 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 	 * For connecting existing entities, use connect() instead.
 	 */
 	add(data?: Partial<TEntity>): string {
+		this.materializeEmbeddedItems()
 
-		// Pre-create entity so we can return tempId
-		const tempId = this.store.createEntity(this.itemType, data as Record<string, unknown>)
+		// One gesture = one undo entry: the pre-create and the list-add are journaled
+		// together so undo removes (and redo re-creates) the whole row.
+		return this.store.transaction(() => {
+			// Pre-create entity so we can return tempId
+			const tempId = this.store.createEntity(this.itemType, data as Record<string, unknown>)
 
-		// Add to has-many relation through dispatcher (enables events/interceptors)
-		this.dispatcher.dispatch(
-			addToList(this.entityType, this.entityId, this.fieldName, this.itemType, tempId, this.alias),
-		)
+			// Add to has-many relation through dispatcher (enables events/interceptors)
+			this.dispatcher.dispatch(
+				addToList(this.entityType, this.entityId, this.fieldName, this.itemType, tempId, this.alias),
+			)
 
-		return tempId
+			return tempId
+		})
 	}
 
 	/**
@@ -395,6 +496,7 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 	 * Falls back to disconnect when schema metadata is not available.
 	 */
 	remove(itemId: string): void {
+		this.materializeEmbeddedItems()
 		this.dispatcher.dispatch(
 			removeFromList(this.entityType, this.entityId, this.fieldName, itemId, this.resolveRemovalType(), this.alias),
 		)
@@ -425,6 +527,7 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 	 * use an 'order' field on the entity.
 	 */
 	move(fromIndex: number, toIndex: number): void {
+		this.materializeEmbeddedItems()
 		this.dispatcher.dispatch(
 			moveInList(this.entityType, this.entityId, this.fieldName, fromIndex, toIndex, this.alias),
 		)
@@ -435,6 +538,7 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 	 * Clears all planned connections and removals.
 	 */
 	reset(): void {
+		this.materializeEmbeddedItems()
 		this.store.resetHasMany(
 			this.entityType,
 			this.entityId,

package/src/handles/HasOneHandle.ts

@@ -1,6 +1,7 @@
 import { EntityRelatedHandle, embeddedDataMatchesSnapshot } from './BaseHandle.js'
 import type { ActionDispatcher } from '../core/ActionDispatcher.js'
 import type { SnapshotStore } from '../store/SnapshotStore.js'
+import type { StoredRelationState } from '../store/RelationStore.js'
 import type { SchemaRegistry } from '../schema/SchemaRegistry.js'
 import type { SelectionMeta } from '../selection/types.js'
 import {
@@ -17,6 +18,7 @@ import {
 	type Unsubscribe,
 	type EntityAccessor,
 	type HasOneAccessor,
+	type HasOneRelationState,
 } from './types.js'
 import { createClientError, type ErrorInput, type FieldError } from '../errors/types.js'
 import type {
@@ -63,6 +65,10 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 		private readonly schema: SchemaRegistry,
 		brands?: Set<symbol>,
 		private readonly selection?: SelectionMeta,
+		private readonly dataFieldName: string = fieldName,
+		// Segments from the query root down to this relation; also the entity path
+		// of whatever it resolves to. See FieldRefMeta.fullPath.
+		private readonly relationPath: readonly string[] = [fieldName],
 	) {
 		super(parentEntityType, parentEntityId, store, dispatcher)
 		this.__brands = brands
@@ -78,8 +84,10 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 		schema: SchemaRegistry,
 		brands?: Set<symbol>,
 		selection?: SelectionMeta,
+		dataFieldName?: string,
+		relationPath?: readonly string[],
 	): HasOneAccessor<TEntity, TSelected> {
-		return createHandleProxy<HasOneHandle<TEntity, TSelected>, HasOneAccessor<TEntity, TSelected>>(new HasOneHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, targetType, store, dispatcher, schema, brands, selection), (target) => target.entityRaw.fields)
+		return HasOneHandle.wrapProxy(new HasOneHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, targetType, store, dispatcher, schema, brands, selection, dataFieldName, relationPath))
 	}
 
 	static createRaw<TEntity extends object = object, TSelected = TEntity>(
@@ -92,12 +100,18 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 		schema: SchemaRegistry,
 		brands?: Set<symbol>,
 		selection?: SelectionMeta,
+		dataFieldName?: string,
+		relationPath?: readonly string[],
 	): HasOneHandle<TEntity, TSelected> {
-		return new HasOneHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, targetType, store, dispatcher, schema, brands, selection)
+		return new HasOneHandle<TEntity, TSelected>(parentEntityType, parentEntityId, fieldName, targetType, store, dispatcher, schema, brands, selection, dataFieldName, relationPath)
 	}
 
 	static wrapProxy<TEntity extends object, TSelected>(handle: HasOneHandle<TEntity, TSelected>): HasOneAccessor<TEntity, TSelected> {
-		return createHandleProxy<HasOneHandle<TEntity, TSelected>, HasOneAccessor<TEntity, TSelected>>(handle, (target) => target.entityRaw.fields)
+		return createHandleProxy<HasOneHandle<TEntity, TSelected>, HasOneAccessor<TEntity, TSelected>>(
+			handle,
+			(target) => target.entityRaw.fields,
+			(target) => target.entityRaw.selectedFieldNames,
+		)
 	}
 
 	/**
@@ -113,6 +127,7 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 			isArray: false,
 			isRelation: true,
 			targetType: this.targetType,
+			fullPath: this.relationPath,
 		}
 	}
 
@@ -137,51 +152,141 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 
 	/**
 	 * Gets the relation state.
-	 * Falls back to snapshot data when no explicit relation state exists,
-	 * so server-loaded has-one relations report 'connected' without
-	 * requiring a prior RelationStore entry.
+	 * Materializes the RelationStore entry from embedded snapshot data first, so a
+	 * server-loaded has-one reports 'connected' without a prior explicit entry.
 	 */
-	get state(): 'connected' | 'disconnected' | 'deleted' | 'creating' {
-		const relation = this.store.getRelation(
+	get state(): HasOneRelationState {
+		this.ensureEntry()
+		const relation = this.store.getPresentationRelation(
 			this.entityType,
 			this.entityId,
 			this.fieldName,
 		)
-		if (relation) {
-			return relation.state
-		}
-		// No explicit relation state — check if snapshot has embedded data
-		if (this.relatedId !== null) {
-			return 'connected'
-		}
-		return 'disconnected'
+		return relation?.state ?? 'disconnected'
 	}
 
 	/**
-	 * Gets the current related entity ID.
-	 * Falls back to entity data if relation state is not initialized.
+	 * Gets the current related entity ID — read exclusively from the RelationStore
+	 * after materializing the entry from embedded snapshot data.
 	 */
 	get relatedId(): string | null {
-		// First check relation state (for manual changes like connect/disconnect)
-		const relation = this.store.getRelation(
+		this.ensureEntry()
+		const relation = this.store.getPresentationRelation(
 			this.entityType,
 			this.entityId,
 			this.fieldName,
 		)
-		if (relation) {
-			return relation.currentId
+		return relation?.currentId ?? null
+	}
+
+	/**
+	 * Materializes this has-one's RelationStore entry from the parent's embedded
+	 * snapshot data, so the store is the single source of truth (symmetric with
+	 * {@link HasManyListHandle.materializeEmbeddedItems}).
+	 *
+	 * Only the relation entry is touched here — child-snapshot propagation stays in
+	 * {@link ensureRelatedEntitySnapshot}, which owns the per-relation propagation
+	 * slot so the two paths never double-consume it.
+	 *
+	 * - No entry yet + the parent embeds a related object with an id → create a
+	 *   `connected` entry (non-notifying) whose server baseline comes from the
+	 *   parent's serverData, so a freshly loaded relation is not dirty
+	 *   (currentId === serverId, state === serverState).
+	 * - Existing entry + parent re-fetch (embedded reference changed) that is NOT
+	 *   locally dirty → advance the server baseline to the new related id.
+	 * - A local connect/disconnect, a placeholder, or a `creating` entry is left
+	 *   untouched — it is detected as a locally-dirty relation.
+	 * - No embedded data and no entry → the relation stays unmaterialized (null).
+	 */
+	private ensureEntry(): void {
+		const existing = this.store.getRelation(this.entityType, this.entityId, this.fieldName)
+		const embeddedData = this.readEmbeddedRelatedData()
+		const embeddedReference = readEmbeddedRelatedReference(embeddedData)
+
+		if (!existing) {
+			if (embeddedReference.kind !== 'connected') return
+			const serverId = this.readServerRelatedId()
+			this.store.getOrCreateRelation(this.entityType, this.entityId, this.fieldName, {
+				currentId: embeddedReference.id,
+				serverId,
+				state: 'connected',
+				serverState: serverId !== null ? 'connected' : 'disconnected',
+				placeholderData: {},
+			})
+			return
 		}
 
-		// Fallback to entity snapshot data (for server-loaded data)
-		const parentSnapshot = this.store.getEntitySnapshot(this.entityType, this.entityId)
-		if (parentSnapshot?.data) {
-			const relatedData = (parentSnapshot.data as Record<string, unknown>)[this.fieldName]
-			if (relatedData && typeof relatedData === 'object' && 'id' in relatedData) {
-				return (relatedData as { id: string }).id
-			}
+		this.advanceServerBaselineOnRefetch(existing, embeddedReference, embeddedData)
+	}
+
+	/**
+	 * On a parent re-fetch (embedded reference changed) advances the relation's
+	 * server baseline to the embedded related id, but only when the relation is
+	 * not locally dirty — a local connect/disconnect/create must survive a re-fetch.
+	 *
+	 * Does NOT consume the propagation slot — {@link ensureRelatedEntitySnapshot}
+	 * owns it. The same reference-change signal drives both, so both run within the
+	 * one render that observes a new parent reference.
+	 *
+	 * The baseline write is NON-NOTIFYING: it runs during a render-phase read, and
+	 * the parent re-fetch that produced the new embedded reference already notified
+	 * subscribers. Notifying again here would mutate the store and synchronously call
+	 * subscribers mid-render, violating the external-store contract (cf.
+	 * {@link ensureRelatedEntitySnapshot}, which refreshes server data with skipNotify
+	 * for the same reason).
+	 */
+	private advanceServerBaselineOnRefetch(
+		existing: StoredRelationState,
+		embeddedReference: EmbeddedRelatedReference,
+		embeddedData: unknown,
+	): void {
+		if (embeddedReference.kind === 'absent') return
+		if (this.isLocallyDirty(existing)) return
+
+		if (embeddedReference.kind === 'null' && existing.serverId === null && existing.serverState === 'disconnected') {
+			return
 		}
+		if (embeddedReference.kind === 'connected' && existing.serverId === embeddedReference.id && existing.serverState === 'connected') {
+			return
+		}
+		if (!this.store.hasEmbeddedDataChanged(this.entityType, this.entityId, this.dataFieldName, embeddedData)) {
+			return
+		}
+
+		if (embeddedReference.kind === 'null') {
+			this.store.setRelation(this.entityType, this.entityId, this.fieldName, {
+				currentId: null,
+				serverId: null,
+				state: 'disconnected',
+				serverState: 'disconnected',
+			}, true)
+			return
+		}
+
+		this.store.setRelation(this.entityType, this.entityId, this.fieldName, {
+			currentId: embeddedReference.id,
+			serverId: embeddedReference.id,
+			state: 'connected',
+			serverState: 'connected',
+		}, true)
+	}
 
-		return null
+	private isLocallyDirty(relation: StoredRelationState): boolean {
+		return (
+			relation.currentId !== relation.serverId ||
+			relation.state !== relation.serverState ||
+			Object.keys(relation.placeholderData).length > 0
+		)
+	}
+
+	/** Reads the embedded related object from the parent's canonical current data. */
+	private readEmbeddedRelatedData(): unknown {
+		return this.getEntityData()?.[this.dataFieldName]
+	}
+
+	/** Extracts the related id from the parent's embedded server data, or null. */
+	private readServerRelatedId(): string | null {
+		return extractRelatedId(this.getServerData()?.[this.dataFieldName])
 	}
 
 	/**
@@ -222,6 +327,7 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 					this.schema,
 					this.__brands,
 					this.selection,
+					this.relationPath,
 				)
 				this.entityHandleCacheProxy = EntityHandle.wrapProxy(this.entityHandleCacheRaw)
 			}
@@ -238,6 +344,7 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 				this.dispatcher,
 				this.schema,
 				this.__brands,
+				this.relationPath,
 			)
 			this.placeholderCacheProxy = PlaceholderHandle.wrapProxy(this.placeholderCacheRaw)
 		}
@@ -289,7 +396,7 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 			return
 		}
 
-		const embeddedData = (parentSnapshot.data as Record<string, unknown>)[this.fieldName]
+		const embeddedData = (parentSnapshot.data as Record<string, unknown>)[this.dataFieldName]
 		if (!embeddedData || typeof embeddedData !== 'object') {
 			return
 		}
@@ -307,7 +414,7 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 		// A new reference means the parent was re-fetched from the server.
 		// Same reference means the embedded data is stale and must not overwrite
 		// child state that may have been updated by a local commit.
-		if (!this.store.hasEmbeddedDataChanged(this.entityType, this.entityId, this.fieldName, embeddedData)) {
+		if (!this.store.hasEmbeddedDataChanged(this.entityType, this.entityId, this.dataFieldName, embeddedData)) {
 			return
 		}
 
@@ -316,7 +423,7 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 		// (e.g. polling). A new reference with identical values means no actual change.
 		const existing = this.store.getEntitySnapshot(this.targetType, id)
 		if (existing?.serverData && embeddedDataMatchesSnapshot(embeddedData as Record<string, unknown>, existing.serverData as Record<string, unknown>)) {
-			this.store.markEmbeddedDataPropagated(this.entityType, this.entityId, this.fieldName, embeddedData)
+			this.store.markEmbeddedDataPropagated(this.entityType, this.entityId, this.dataFieldName, embeddedData)
 			return
 		}
 
@@ -331,7 +438,7 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 			embeddedData as Record<string, unknown>,
 			true, // skipNotify - called during render, data already exists embedded in parent
 		)
-		this.store.markEmbeddedDataPropagated(this.entityType, this.entityId, this.fieldName, embeddedData)
+		this.store.markEmbeddedDataPropagated(this.entityType, this.entityId, this.dataFieldName, embeddedData)
 	}
 
 	/**
@@ -354,6 +461,7 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 	 * Checks if the relation is dirty.
 	 */
 	get isDirty(): boolean {
+		this.ensureEntry()
 		const relation = this.store.getRelation(
 			this.entityType,
 			this.entityId,
@@ -361,11 +469,7 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 		)
 		if (!relation) return false
 
-		return (
-			relation.currentId !== relation.serverId ||
-			relation.state !== relation.serverState ||
-			Object.keys(relation.placeholderData).length > 0
-		)
+		return this.isLocallyDirty(relation)
 	}
 
 	/**
@@ -374,11 +478,15 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 	 * Accessible via proxy as `$create()`.
 	 */
 	create(data?: Partial<TEntity>): string {
-		const tempId = this.store.createEntity(this.targetType, data as Record<string, unknown>)
-		this.dispatcher.dispatch(
-			connectRelation(this.entityType, this.entityId, this.fieldName, tempId, this.targetType),
-		)
-		return tempId
+		// One gesture = one undo entry: the pre-create and the connect are journaled
+		// together so undo removes (and redo re-creates) the created target.
+		return this.store.transaction(() => {
+			const tempId = this.store.createEntity(this.targetType, data as Record<string, unknown>)
+			this.dispatcher.dispatch(
+				connectRelation(this.entityType, this.entityId, this.fieldName, tempId, this.targetType),
+			)
+			return tempId
+		})
 	}
 
 	/**
@@ -574,3 +682,28 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 	}
 
 }
+
+type EmbeddedRelatedReference =
+	| { kind: 'absent' }
+	| { kind: 'null' }
+	| { kind: 'connected'; id: string }
+
+/**
+ * Reads an embedded has-one value while preserving explicit null.
+ */
+function readEmbeddedRelatedReference(embedded: unknown): EmbeddedRelatedReference {
+	if (embedded === undefined) return { kind: 'absent' }
+	if (embedded === null) return { kind: 'null' }
+	if (typeof embedded !== 'object' || !('id' in embedded)) return { kind: 'absent' }
+	const id = embedded.id
+	return typeof id === 'string' ? { kind: 'connected', id } : { kind: 'absent' }
+}
+
+/**
+ * Extracts the related entity id from an embedded has-one object, or null when
+ * the value is not an object with a string id.
+ */
+function extractRelatedId(embedded: unknown): string | null {
+	const reference = readEmbeddedRelatedReference(embedded)
+	return reference.kind === 'connected' ? reference.id : null
+}