refactor(bindx): decompose store internals (memoized reachability → RelationStore split)

packages/bindx/src/core/ActionDispatcher.ts

@@ -373,6 +373,7 @@ export class ActionDispatcher {
 					action.entityType,
 					action.entityId,
 					action.isPersisting,
+					action.pessimistic ?? false,
 				)
 				break
 

packages/bindx/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 }
 }
 
 /**

packages/bindx/src/handles/BaseHandle.ts

@@ -62,13 +62,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.
 	 */

packages/bindx/src/handles/EntityHandle.ts

@@ -139,11 +139,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
 	}
 

packages/bindx/src/handles/FieldHandle.ts

@@ -87,10 +87,11 @@ export class FieldHandle<T = unknown> extends EntityRelatedHandle {
 	}
 
 	/**
-	 * Gets the current field value.
+	 * Gets the current field value to DISPLAY. While a pessimistic persist is
+	 * in-flight this is the server baseline; otherwise it is the live value.
 	 */
 	get value(): T | null {
-		const data = this.getEntityData()
+		const data = this.getPresentationData()
 		if (!data) return null
 		return getNestedValue(data, this.fieldPath) as T | null
 	}
@@ -105,10 +106,14 @@ export class FieldHandle<T = unknown> extends EntityRelatedHandle {
 	}
 
 	/**
-	 * Checks if the field has been modified.
+	 * Checks if the field has been modified. Compares the CANONICAL value against
+	 * the server value — never the presented value, so a field stays correctly
+	 * dirty even while its display shows the server baseline mid-pessimistic-persist.
 	 */
 	get isDirty(): boolean {
-		return !deepEqual(this.value, this.serverValue)
+		const data = this.getEntityData()
+		const value = data ? (getNestedValue(data, this.fieldPath) as T | null) : null
+		return !deepEqual(value, this.serverValue)
 	}
 
 	/**

packages/bindx/src/handles/HasManyListHandle.ts

@@ -120,7 +120,7 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 		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,
@@ -322,8 +322,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
 		)
 	}

packages/bindx/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 {
@@ -137,51 +139,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.fieldName, 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
 		}
 
-		return null
+		this.store.setRelation(this.entityType, this.entityId, this.fieldName, {
+			currentId: embeddedReference.id,
+			serverId: embeddedReference.id,
+			state: 'connected',
+			serverState: 'connected',
+		}, true)
+	}
+
+	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.fieldName]
+	}
+
+	/** Extracts the related id from the parent's embedded server data, or null. */
+	private readServerRelatedId(): string | null {
+		return extractRelatedId(this.getServerData()?.[this.fieldName])
 	}
 
 	/**
@@ -354,18 +446,15 @@ 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,
 			this.fieldName,
 		)
 		if (!relation) return false
 
-		return (
-			relation.currentId !== relation.serverId ||
-			relation.state !== relation.serverState ||
-			Object.keys(relation.placeholderData).length > 0
-		)
+		return this.isLocallyDirty(relation)
 	}
 
 	/**
@@ -574,3 +663,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
+}