@contember/bindx 0.1.46 → 0.1.48

package/src/adapter/MockAdapter.ts

@@ -194,7 +194,9 @@ export class MockAdapter implements BackendAdapter {
 		this.applyChanges(entity, changes)
 		this.log('persist result', entity)
 
-		return { ok: true }
+		// Echo the mutated node — PersistResult.data is what the persister reads
+		// nested create IDs out of.
+		return { ok: true, data: entity }
 	}
 
 	/**
@@ -335,11 +337,15 @@ export class MockAdapter implements BackendAdapter {
 	}
 
 	/**
-	 * Creates a related entity with a generated ID.
+	 * Creates a related entity with a generated ID, materializing its own nested
+	 * operations. The persister reconciles a create by reading server IDs out of
+	 * the echoed node, so a nested create left as a raw `{ create: … }` operation
+	 * reads as an unresolved ID and fails the whole persist.
 	 */
 	private createRelatedEntity(data: Record<string, unknown>): Record<string, unknown> {
-		const id = this.generateId()
-		return { id, ...data }
+		const entity: Record<string, unknown> = { id: this.generateId() }
+		this.applyChanges(entity, data)
+		return entity
 	}
 
 	/**
@@ -368,7 +374,11 @@ export class MockAdapter implements BackendAdapter {
 
 		// Generate ID if not provided
 		const id = (data['id'] as string) ?? this.generateId()
-		const entity = { ...data, id }
+		// Materialize relation operations so the echoed node carries the server IDs
+		// of every nested create — the persister reconciles against exactly that.
+		const entity: Record<string, unknown> = { id }
+		this.applyChanges(entity, data)
+		entity['id'] = id
 
 		this.store[entityType]![id] = entity
 		this.log('create result', entity)

package/src/core/ActionDispatcher.ts

@@ -27,6 +27,7 @@ export class ActionDispatcher {
 		eventEmitter?: EventEmitter,
 	) {
 		this.eventEmitter = eventEmitter ?? new EventEmitter()
+		this.store.attachRekeyParticipant(this.eventEmitter)
 	}
 
 	/**
@@ -42,39 +43,46 @@ export class ActionDispatcher {
 	 * Async interceptors are skipped with a warning — use dispatchAsync() for those.
 	 */
 	dispatch(action: Action): void {
-		// Run through middlewares first
-		for (const middleware of this.middlewares) {
-			const result = middleware(action, this.store)
-			if (result === false) {
-				// Middleware can cancel the action
-				return
+		// One dispatch = one undoable gesture. The store records every primary write
+		// made between begin/commit into a single journal entry (no-op without undo).
+		this.store.beginTransaction()
+		try {
+			// Run through middlewares first
+			for (const middleware of this.middlewares) {
+				const result = middleware(action, this.store)
+				if (result === false) {
+					// Middleware can cancel the action
+					return
+				}
 			}
-		}
 
-		// Create and run before event through interceptors (synchronously)
-		const beforeEvent = createBeforeEvent(action, this.store)
-		if (beforeEvent) {
-			const result = this.eventEmitter.runInterceptorsSync(beforeEvent)
-			if (result === null) {
-				// Interceptor cancelled the action
-				return
-			}
-			// If event was modified, update action accordingly
-			if (result !== beforeEvent) {
-				action = this.updateActionFromEvent(action, result)
+			// Create and run before event through interceptors (synchronously)
+			const beforeEvent = createBeforeEvent(action, this.store)
+			if (beforeEvent) {
+				const result = this.eventEmitter.runInterceptorsSync(beforeEvent)
+				if (result === null) {
+					// Interceptor cancelled the action
+					return
+				}
+				// If event was modified, update action accordingly
+				if (result !== beforeEvent) {
+					action = this.updateActionFromEvent(action, result)
+				}
 			}
-		}
 
-		// Capture state before execution (for after events)
-		const stateBefore = captureStateBeforeAction(action, this.store)
+			// Capture state before execution (for after events)
+			const stateBefore = captureStateBeforeAction(action, this.store)
 
-		// Execute the action
-		this.execute(action)
+			// Execute the action
+			this.execute(action)
 
-		// Emit after event
-		const afterEvent = createAfterEvent(action, stateBefore, this.store)
-		if (afterEvent) {
-			this.eventEmitter.emit(afterEvent)
+			// Emit after event
+			const afterEvent = createAfterEvent(action, stateBefore, this.store)
+			if (afterEvent) {
+				this.eventEmitter.emit(afterEvent)
+			}
+		} finally {
+			this.store.commitTransaction()
 		}
 	}
 
@@ -108,16 +116,21 @@ export class ActionDispatcher {
 		// Capture state before execution (for after events)
 		const stateBefore = captureStateBeforeAction(action, this.store)
 
-		// Execute the action
-		this.execute(action)
+		this.store.beginTransaction()
+		try {
+			// Execute the action
+			this.execute(action)
 
-		// Emit after event
-		const afterEvent = createAfterEvent(action, stateBefore, this.store)
-		if (afterEvent) {
-			this.eventEmitter.emit(afterEvent)
-		}
+			// Emit after event
+			const afterEvent = createAfterEvent(action, stateBefore, this.store)
+			if (afterEvent) {
+				this.eventEmitter.emit(afterEvent)
+			}
 
-		return true
+			return true
+		} finally {
+			this.store.commitTransaction()
+		}
 	}
 
 	/**
@@ -174,6 +187,9 @@ export class ActionDispatcher {
 		const index = this.middlewares.indexOf(middleware)
 		if (index !== -1) {
 			this.middlewares.splice(index, 1)
+			if (!this.middlewares.includes(middleware)) {
+				middleware.dispose?.()
+			}
 		}
 	}
 
@@ -373,6 +389,7 @@ export class ActionDispatcher {
 					action.entityType,
 					action.entityId,
 					action.isPersisting,
+					action.pessimistic ?? false,
 				)
 				break
 
@@ -455,7 +472,10 @@ export class ActionDispatcher {
  * Can inspect/modify actions before execution.
  * Return false to cancel the action.
  */
-export type ActionMiddleware = (action: Action, store: SnapshotStore) => boolean | void
+export interface ActionMiddleware {
+	(action: Action, store: SnapshotStore): boolean | void
+	dispose?: () => void
+}
 
 /**
  * Creates a logging middleware for debugging.

package/src/core/actions.ts

@@ -202,6 +202,12 @@ export interface SetPersistingAction {
 	readonly entityType: string
 	readonly entityId: string
 	readonly isPersisting: boolean
+	/**
+	 * Whether this persist is pessimistic. While a pessimistic persist is
+	 * in-flight, handles present the server baseline instead of the (still dirty)
+	 * local data. Ignored when isPersisting is false.
+	 */
+	readonly pessimistic?: boolean
 }
 
 // ==================== Error Actions ====================
@@ -428,8 +434,9 @@ export function setPersisting(
 	entityType: string,
 	entityId: string,
 	isPersisting: boolean,
+	pessimistic: boolean = false,
 ): SetPersistingAction {
-	return { type: 'SET_PERSISTING', entityType, entityId, isPersisting }
+	return { type: 'SET_PERSISTING', entityType, entityId, isPersisting, pessimistic }
 }
 
 /**

package/src/events/EventEmitter.ts

@@ -15,6 +15,9 @@ import type {
 	InterceptorResult,
 	Unsubscribe,
 } from './types.js'
+import type { RekeyContext, Rekeyable } from '../store/RekeyOrchestrator.js'
+
+const SCOPE_SEPARATOR = '\u0000'
 
 interface ScopeKey {
 	entityType: string
@@ -31,7 +34,7 @@ interface ScopeKey {
  * - Field-scoped subscriptions (events for a specific field/relation)
  * - Interceptors for before-events (can cancel or modify)
  */
-export class EventEmitter {
+export class EventEmitter implements Rekeyable {
 	// Global listeners by event type
 	private readonly globalListeners = new Map<string, Set<EventListener<AfterEvent>>>()
 
@@ -44,6 +47,9 @@ export class EventEmitter {
 	// Scoped interceptors
 	private readonly scopedInterceptors = new Map<string, Set<Interceptor<BeforeEvent>>>()
 
+	/** Old scope keys retained so pre-rekey unsubscribe closures still resolve. */
+	private readonly scopeKeyRedirects = new Map<string, string>()
+
 	// ============================================================================
 	// Listener Subscription Methods
 	// ============================================================================
@@ -69,10 +75,11 @@ export class EventEmitter {
 		entityId: string,
 		listener: EventListener<EventTypeMap[T] & AfterEvent>,
 	): Unsubscribe {
-		const key = this.buildScopeKey(eventType, { entityType, entityId })
+		const key = this.resolveScopeKey(this.buildScopeKey(eventType, { entityType, entityId }))
 		const listeners = this.getOrCreateSet(this.scopedListeners, key)
-		listeners.add(listener as EventListener<AfterEvent>)
-		return () => listeners.delete(listener as EventListener<AfterEvent>)
+		const typedListener = listener as EventListener<AfterEvent>
+		listeners.add(typedListener)
+		return () => this.removeScoped(this.scopedListeners, key, typedListener)
 	}
 
 	/**
@@ -85,10 +92,11 @@ export class EventEmitter {
 		fieldName: string,
 		listener: EventListener<EventTypeMap[T] & AfterEvent>,
 	): Unsubscribe {
-		const key = this.buildScopeKey(eventType, { entityType, entityId, fieldName })
+		const key = this.resolveScopeKey(this.buildScopeKey(eventType, { entityType, entityId, fieldName }))
 		const listeners = this.getOrCreateSet(this.scopedListeners, key)
-		listeners.add(listener as EventListener<AfterEvent>)
-		return () => listeners.delete(listener as EventListener<AfterEvent>)
+		const typedListener = listener as EventListener<AfterEvent>
+		listeners.add(typedListener)
+		return () => this.removeScoped(this.scopedListeners, key, typedListener)
 	}
 
 	// ============================================================================
@@ -117,10 +125,11 @@ export class EventEmitter {
 		entityId: string,
 		interceptor: Interceptor<EventTypeMap[T] & BeforeEvent>,
 	): Unsubscribe {
-		const key = this.buildScopeKey(eventType, { entityType, entityId })
+		const key = this.resolveScopeKey(this.buildScopeKey(eventType, { entityType, entityId }))
 		const interceptors = this.getOrCreateSet(this.scopedInterceptors, key)
-		interceptors.add(interceptor as Interceptor<BeforeEvent>)
-		return () => interceptors.delete(interceptor as Interceptor<BeforeEvent>)
+		const typedInterceptor = interceptor as Interceptor<BeforeEvent>
+		interceptors.add(typedInterceptor)
+		return () => this.removeScoped(this.scopedInterceptors, key, typedInterceptor)
 	}
 
 	/**
@@ -133,10 +142,23 @@ export class EventEmitter {
 		fieldName: string,
 		interceptor: Interceptor<EventTypeMap[T] & BeforeEvent>,
 	): Unsubscribe {
-		const key = this.buildScopeKey(eventType, { entityType, entityId, fieldName })
+		const key = this.resolveScopeKey(this.buildScopeKey(eventType, { entityType, entityId, fieldName }))
 		const interceptors = this.getOrCreateSet(this.scopedInterceptors, key)
-		interceptors.add(interceptor as Interceptor<BeforeEvent>)
-		return () => interceptors.delete(interceptor as Interceptor<BeforeEvent>)
+		const typedInterceptor = interceptor as Interceptor<BeforeEvent>
+		interceptors.add(typedInterceptor)
+		return () => this.removeScoped(this.scopedInterceptors, key, typedInterceptor)
+	}
+
+	/**
+	 * Whether any interceptor could receive this event for the given entity.
+	 * Lets a caller skip the (async) interceptor pipeline when nothing is listening.
+	 */
+	hasInterceptors(eventType: string, entityType: string, entityId: string): boolean {
+		const global = this.globalInterceptors.get(eventType)
+		if (global !== undefined && global.size > 0) return true
+
+		const scoped = this.scopedInterceptors.get(this.resolveScopeKey(this.buildScopeKey(eventType, { entityType, entityId })))
+		return scoped !== undefined && scoped.size > 0
 	}
 
 	// ============================================================================
@@ -162,7 +184,7 @@ export class EventEmitter {
 				fieldName,
 			})
 			const result = await this.runInterceptorSet(
-				this.scopedInterceptors.get(fieldKey),
+				this.scopedInterceptors.get(this.resolveScopeKey(fieldKey)),
 				currentEvent,
 			)
 			if (result === null) return null
@@ -176,7 +198,7 @@ export class EventEmitter {
 			entityId: event.entityId,
 		})
 		const entityResult = await this.runInterceptorSet(
-			this.scopedInterceptors.get(entityKey),
+			this.scopedInterceptors.get(this.resolveScopeKey(entityKey)),
 			currentEvent,
 		)
 		if (entityResult === null) return null
@@ -209,7 +231,7 @@ export class EventEmitter {
 				entityId: event.entityId,
 				fieldName,
 			})
-			this.notifyListeners(this.scopedListeners.get(fieldKey), event)
+			this.notifyListeners(this.scopedListeners.get(this.resolveScopeKey(fieldKey)), event)
 		}
 
 		// Entity-level listeners
@@ -217,7 +239,7 @@ export class EventEmitter {
 			entityType: event.entityType,
 			entityId: event.entityId,
 		})
-		this.notifyListeners(this.scopedListeners.get(entityKey), event)
+		this.notifyListeners(this.scopedListeners.get(this.resolveScopeKey(entityKey)), event)
 
 		// Global listeners
 		this.notifyListeners(this.globalListeners.get(event.type), event)
@@ -231,11 +253,42 @@ export class EventEmitter {
 	 * Builds a scope key for listener/interceptor lookup.
 	 */
 	private buildScopeKey(eventType: string, scope: ScopeKey): string {
-		const parts = [eventType, scope.entityType, scope.entityId]
-		if (scope.fieldName) {
-			parts.push(scope.fieldName)
+		const parts = [eventType, scope.entityType, scope.entityId, scope.fieldName ?? '']
+		return parts.join(SCOPE_SEPARATOR)
+	}
+
+	private resolveScopeKey(key: string): string {
+		let resolved = key
+		let next = this.scopeKeyRedirects.get(resolved)
+		while (next && next !== resolved) {
+			resolved = next
+			next = this.scopeKeyRedirects.get(resolved)
+		}
+		return resolved
+	}
+
+	private removeScoped<T>(map: Map<string, Set<T>>, key: string, value: T): void {
+		map.get(this.resolveScopeKey(key))?.delete(value)
+	}
+
+	rekey(ctx: RekeyContext): void {
+		this.rekeyScopedMap(this.scopedListeners, ctx)
+		this.rekeyScopedMap(this.scopedInterceptors, ctx)
+	}
+
+	private rekeyScopedMap<T>(map: Map<string, Set<T>>, ctx: RekeyContext): void {
+		const entityType = ctx.oldKey.slice(0, ctx.oldKey.length - ctx.oldId.length - 1)
+		const oldIdentity = `${SCOPE_SEPARATOR}${entityType}${SCOPE_SEPARATOR}${ctx.oldId}${SCOPE_SEPARATOR}`
+		const newIdentity = `${SCOPE_SEPARATOR}${entityType}${SCOPE_SEPARATOR}${ctx.newId}${SCOPE_SEPARATOR}`
+
+		for (const [oldScopeKey, values] of [...map]) {
+			if (!oldScopeKey.includes(oldIdentity)) continue
+			const newScopeKey = oldScopeKey.replace(oldIdentity, newIdentity)
+			const destination = this.getOrCreateSet(map, newScopeKey)
+			for (const value of values) destination.add(value)
+			map.delete(oldScopeKey)
+			this.scopeKeyRedirects.set(oldScopeKey, newScopeKey)
 		}
-		return parts.join(':')
 	}
 
 	/**
@@ -297,7 +350,7 @@ export class EventEmitter {
 				fieldName,
 			})
 			const result = this.runInterceptorSetSync(
-				this.scopedInterceptors.get(fieldKey),
+				this.scopedInterceptors.get(this.resolveScopeKey(fieldKey)),
 				currentEvent,
 			)
 			if (result === null) return null
@@ -310,7 +363,7 @@ export class EventEmitter {
 			entityId: event.entityId,
 		})
 		const entityResult = this.runInterceptorSetSync(
-			this.scopedInterceptors.get(entityKey),
+			this.scopedInterceptors.get(this.resolveScopeKey(entityKey)),
 			currentEvent,
 		)
 		if (entityResult === null) return null
@@ -424,6 +477,7 @@ export class EventEmitter {
 		this.scopedListeners.clear()
 		this.globalInterceptors.clear()
 		this.scopedInterceptors.clear()
+		this.scopeKeyRedirects.clear()
 	}
 
 	/**
@@ -437,7 +491,7 @@ export class EventEmitter {
 
 		// Count scoped listeners
 		for (const [key, listeners] of this.scopedListeners) {
-			if (key.startsWith(eventType + ':')) {
+			if (key.startsWith(eventType + SCOPE_SEPARATOR)) {
 				count += listeners.size
 			}
 		}

package/src/handles/BaseHandle.ts

@@ -39,13 +39,18 @@ export abstract class BaseHandle {
 export abstract class EntityRelatedHandle extends BaseHandle {
 	constructor(
 		protected readonly entityType: string,
-		protected readonly entityId: string,
+		private readonly sourceEntityId: string,
 		store: SnapshotStore,
 		dispatcher: ActionDispatcher,
 	) {
 		super(store, dispatcher)
 	}
 
+	/** Current canonical id; the handle keeps no mutable rekey state. */
+	protected get entityId(): string {
+		return this.store.resolveEntityId(this.entityType, this.sourceEntityId)
+	}
+
 	/**
 	 * Subscribe to entity changes.
 	 */
@@ -62,13 +67,25 @@ export abstract class EntityRelatedHandle extends BaseHandle {
 	}
 
 	/**
-	 * Get entity data.
+	 * Get the CANONICAL entity data — the live, possibly-dirty values. Use this
+	 * for dirty tracking and any logic that must reflect the user's edits, even
+	 * while a pessimistic persist is in-flight. For values to DISPLAY, use
+	 * {@link getPresentationData}.
 	 */
 	protected getEntityData(): Record<string, unknown> | undefined {
 		const snapshot = this.store.getEntitySnapshot(this.entityType, this.entityId)
 		return snapshot?.data as Record<string, unknown> | undefined
 	}
 
+	/**
+	 * Get the entity data a consumer should DISPLAY. Equals {@link getEntityData}
+	 * except while the entity is pessimistically in-flight, when it returns the
+	 * server baseline (the canonical data stays dirty underneath).
+	 */
+	protected getPresentationData(): Record<string, unknown> | undefined {
+		return this.store.getPresentationSnapshot<Record<string, unknown>>(this.entityType, this.entityId)?.data
+	}
+
 	/**
 	 * Get entity server data.
 	 */

package/src/handles/EntityHandle.ts

@@ -80,6 +80,9 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 		private readonly schema: SchemaRegistry,
 		brands?: Set<symbol>,
 		private readonly selection?: SelectionMeta,
+		// Segments from the query root down to this entity. Empty at a root and at
+		// every has-many item, so item chains restart their own `fullPath`.
+		private readonly entityPath: readonly string[] = [],
 	) {
 		super(entityType, id, store, dispatcher)
 		this.__brands = brands
@@ -93,8 +96,9 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 		schema: SchemaRegistry,
 		brands?: Set<symbol>,
 		selection?: SelectionMeta,
+		entityPath?: readonly string[],
 	): EntityAccessor<T, TSelected> {
-		return EntityHandle.wrapProxy(new EntityHandle<T, TSelected>(id, entityType, store, dispatcher, schema, brands, selection))
+		return EntityHandle.wrapProxy(new EntityHandle<T, TSelected>(id, entityType, store, dispatcher, schema, brands, selection, entityPath))
 	}
 
 	static createRaw<T extends object = object, TSelected = T>(
@@ -105,12 +109,26 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 		schema: SchemaRegistry,
 		brands?: Set<symbol>,
 		selection?: SelectionMeta,
+		entityPath?: readonly string[],
 	): EntityHandle<T, TSelected> {
-		return new EntityHandle<T, TSelected>(id, entityType, store, dispatcher, schema, brands, selection)
+		return new EntityHandle<T, TSelected>(id, entityType, store, dispatcher, schema, brands, selection, entityPath)
 	}
 
 	static wrapProxy<T extends object, TSelected>(handle: EntityHandle<T, TSelected>): EntityAccessor<T, TSelected> {
-		return createHandleProxy<EntityHandle<T, TSelected>, EntityAccessor<T, TSelected>>(handle, (target) => target.fields)
+		return createHandleProxy<EntityHandle<T, TSelected>, EntityAccessor<T, TSelected>>(
+			handle,
+			(target) => target.fields,
+			(target) => target.selectedFieldNames,
+		)
+	}
+
+	/**
+	 * Field names the handle's selection exposes, for enumeration. Without a selection
+	 * nothing is validated and nothing is listed.
+	 */
+	get selectedFieldNames(): readonly string[] {
+		if (!this.selection) return []
+		return [...this.selection.fields.keys()]
 	}
 
 	get [FIELD_REF_META](): FieldRefMeta {
@@ -139,11 +157,14 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 	}
 
 	/**
-	 * Gets the current entity data.
+	 * Gets the current entity data to DISPLAY.
 	 * Returns selected fields subset as specified by TSelected type parameter.
+	 * While a pessimistic persist is in-flight this is the server baseline; the
+	 * canonical snapshot (see {@link getSnapshot}, used for dirty tracking) stays
+	 * dirty underneath.
 	 */
 	get data(): TSelected | null {
-		const snapshot = this.getSnapshot()
+		const snapshot = this.store.getPresentationSnapshot<T>(this.entityType, this.entityId)
 		return (snapshot?.data ?? null) as TSelected | null
 	}
 
@@ -251,24 +272,27 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 	 * Gets a field handle for a specific field.
 	 * Returns cached handle to ensure stable identity.
 	 */
-	field<K extends keyof T>(fieldName: K): FieldAccessor<T[K]> {
-		const cacheKey = String(fieldName)
+	field<K extends keyof T>(fieldName: K, dataFieldName = String(fieldName)): FieldAccessor<T[K]> {
+		const schemaFieldName = String(fieldName)
+		const cacheKey = dataFieldName
 		const cached = this.fieldHandleCache.get(cacheKey)
 
 		if (cached) {
 			return cached.proxy as FieldAccessor<T[K]>
 		}
 
-		const enumName = this.schema.getEnumName(this.entityType, cacheKey)
-		const columnType = this.schema.getColumnType(this.entityType, cacheKey)
+		const enumName = this.schema.getEnumName(this.entityType, schemaFieldName)
+		const columnType = this.schema.getColumnType(this.entityType, schemaFieldName)
 		const raw = FieldHandle.createRaw<T[K]>(
 			this.entityType,
 			this.entityId,
-			[cacheKey],
+			[schemaFieldName],
 			this.store,
 			this.dispatcher,
 			enumName,
 			columnType,
+			[dataFieldName],
+			[...this.entityPath, schemaFieldName],
 		)
 		const proxy = FieldHandle.wrapProxy(raw)
 		this.fieldHandleCache.set(cacheKey, { raw, proxy } as CachedFieldHandle)
@@ -279,8 +303,8 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 	/**
 	 * Gets a has-one relation handle.
 	 */
-	hasOne<TRelated extends object>(fieldName: string, nestedSelection?: SelectionMeta): HasOneAccessor<TRelated> {
-		const cacheKey = `hasOne:${fieldName}`
+	hasOne<TRelated extends object>(fieldName: string, nestedSelection?: SelectionMeta, dataFieldName = fieldName): HasOneAccessor<TRelated> {
+		const cacheKey = `hasOne:${dataFieldName}`
 		const cached = this.relationHandleCache.get(cacheKey)
 
 		if (cached) {
@@ -304,6 +328,8 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 			this.schema,
 			undefined,
 			nestedSelection,
+			dataFieldName,
+			[...this.entityPath, fieldName],
 		)
 		const proxy = HasOneHandle.wrapProxy(raw)
 		this.relationHandleCache.set(cacheKey, { raw, proxy })
@@ -344,6 +370,7 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 			this.__brands,
 			effectiveAlias,
 			nestedSelection,
+			[...this.entityPath, fieldName],
 		)
 		this.relationHandleCache.set(cacheKey, { raw: handle as unknown as RelationHandleRaw, proxy: handle })
 
@@ -379,6 +406,8 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 			this.schema,
 			undefined,
 			undefined,
+			undefined,
+			[...this.entityPath, fieldName],
 		)
 		const proxy = HasOneHandle.wrapProxy(raw)
 		this.relationHandleCache.set(cacheKey, { raw, proxy })
@@ -462,29 +491,31 @@ export class EntityHandle<T extends object = object, TSelected = T> extends Enti
 				}
 
 				const nestedSelection = fieldMeta?.nested
+				const schemaFieldName = fieldMeta?.fieldName ?? fieldName
+				const dataFieldName = fieldMeta?.alias ?? fieldName
 
 				// Use schema to determine field type
-				const fieldDef = this.schema.getFieldDef(this.entityType, fieldName)
+				const fieldDef = this.schema.getFieldDef(this.entityType, schemaFieldName)
 
 				if (!fieldDef || fieldDef.type === 'scalar') {
 					// Scalar field - return FieldHandle
-					return this.field(fieldName as keyof T)
+					return this.field(schemaFieldName as keyof T, dataFieldName)
 				}
 
 				if (fieldDef.type === 'hasOne') {
 					// Has-one relation - return HasOneHandle
-					return this.hasOne(fieldName, nestedSelection)
+					return this.hasOne(schemaFieldName, nestedSelection, dataFieldName)
 				}
 
 				if (fieldDef.type === 'hasMany') {
 					// Has-many relation - return HasManyListHandle.
 					// Thread the selected alias so the handle reads data stored under the
 					// auto-generated alias (e.g. `tags_<hash>`) for params-bearing relations.
-					return this.hasMany(fieldName, fieldMeta?.alias, nestedSelection)
+					return this.hasMany(schemaFieldName, fieldMeta?.alias, nestedSelection)
 				}
 
 				// Unknown field type - fallback to FieldHandle
-				return this.field(fieldName as keyof T)
+				return this.field(schemaFieldName as keyof T, dataFieldName)
 			},
 		})
 	}