@contember/bindx 0.1.46 → 0.1.47

package/src/store/RelationStore.ts

@@ -1,876 +1,327 @@
-import type { HasOneRelationState } from '../handles/types.js'
 import type { EntitySnapshot } from './snapshots.js'
-
-function setsEqual<T>(a: Set<T>, b: Set<T>): boolean {
-	if (a.size !== b.size) return false
-	for (const item of a) {
-		if (!b.has(item)) return false
-	}
-	return true
-}
-
-/**
- * Removal type for has-many items
- */
-export type HasManyRemovalType = 'disconnect' | 'delete'
-
-/**
- * Has-many list state stored in SnapshotStore
- */
-export interface StoredHasManyState {
-	/** IDs of items from server */
-	serverIds: Set<string>
-	/** Explicit ordered list of item IDs, null means use default order (serverIds + plannedConnections) */
-	orderedIds: string[] | null
-	/** Planned removals (disconnect or delete) keyed by entity ID */
-	plannedRemovals: Map<string, HasManyRemovalType>
-	/** Planned connections (IDs to add to the list) */
-	plannedConnections: Set<string>
-	/** Entity IDs created via add() - tracked for proper remove() semantics and mutation generation */
-	createdEntities: Set<string>
-	version: number
-}
-
-/**
- * Relation state stored in SnapshotStore
- */
-export interface StoredRelationState {
-	currentId: string | null
-	serverId: string | null
-	state: HasOneRelationState
-	serverState: HasOneRelationState
-	placeholderData: Record<string, unknown>
-	version: number
-}
+import type { RekeyContext, Rekeyable } from './RekeyOrchestrator.js'
+import {
+	HasOneStore,
+	type SentHasOneTransition,
+	type StoredRelationState,
+} from './HasOneStore.js'
+import {
+	HasManyStore,
+	computeDefaultOrderedIds,
+	type HasManyAdditionKind,
+	type HasManyRemovalType,
+	type SentHasManyDelta,
+	type StoredHasManyState,
+} from './HasManyStore.js'
+
+// Re-exported so existing imports from './RelationStore.js' keep resolving.
+export type { StoredRelationState } from './HasOneStore.js'
+export type { SentHasOneTransition } from './HasOneStore.js'
+export type {
+	HasManyAdditionKind,
+	HasManyRemovalType,
+	SentHasManyAddition,
+	SentHasManyDelta,
+	SentHasManyRemoval,
+	StoredHasManyState,
+} from './HasManyStore.js'
+export { computeDefaultOrderedIds } from './HasManyStore.js'
+
+export type RelationReconciliationResult = 'applied' | 'conflict'
 
 /**
  * Manages has-one and has-many relation state.
  *
  * Relation keys use the format "parentType:parentId:fieldName".
  * Notification is handled by callers via callback returns.
+ *
+ * Thin facade composing a {@link HasOneStore} and a {@link HasManyStore}: each
+ * sub-store owns its own state map and write helper, and the facade merges the
+ * cross-cutting queries (mutation version sum; live-child/parent-key unions;
+ * dirty union) and fans out the cross-cutting mutations (rekey, removeOwned,
+ * clear) to both.
  */
-export class RelationStore {
-	/** Relation states keyed by "parentType:parentId:fieldName" */
-	private readonly relationStates = new Map<string, StoredRelationState>()
+export class RelationStore implements Rekeyable {
+	private readonly hasOne = new HasOneStore()
+	private readonly hasMany = new HasManyStore()
+
+	/**
+	 * Increases whenever EITHER sub-store mutates. Used by {@link ReachabilityAnalyzer}
+	 * to memoize its walk; only monotonic-increase-on-mutation matters, so the sum
+	 * of the two per-store counters is sufficient.
+	 */
+	getMutationVersion(): number {
+		return this.hasOne.getMutationVersion() + this.hasMany.getMutationVersion()
+	}
 
-	/** Has-many list states keyed by "parentType:parentId:fieldName" */
-	private readonly hasManyStates = new Map<string, StoredHasManyState>()
+	/** Editable-layer has-one write counter — read by the undo write-guard. */
+	getEditableHasOneWriteVersion(): number {
+		return this.hasOne.getEditableWriteVersion()
+	}
+
+	/** Editable-layer has-many write counter — read by the undo write-guard. */
+	getEditableHasManyWriteVersion(): number {
+		return this.hasMany.getEditableWriteVersion()
+	}
 
 	// ==================== Has-One Relations ====================
 
-	/**
-	 * Gets or creates relation state.
-	 */
 	getOrCreateRelation(
 		key: string,
 		initial: Omit<StoredRelationState, 'version'>,
 	): StoredRelationState {
-		if (!this.relationStates.has(key)) {
-			this.relationStates.set(key, { ...initial, version: 0 })
-		}
-
-		return this.relationStates.get(key)!
+		return this.hasOne.getOrCreateRelation(key, initial)
 	}
 
-	/**
-	 * Gets relation state.
-	 */
 	getRelation(key: string): StoredRelationState | undefined {
-		return this.relationStates.get(key)
+		return this.hasOne.getRelation(key)
 	}
 
-	/**
-	 * Updates relation state.
-	 * If the relation state doesn't exist, creates it using entity snapshot for server data.
-	 */
 	setRelation(
 		key: string,
 		updates: Partial<Omit<StoredRelationState, 'version'>>,
 		entitySnapshot: EntitySnapshot | undefined,
 		fieldName: string,
 	): void {
-		const existing = this.relationStates.get(key)
-
-		if (!existing) {
-			let serverId: string | null = null
-			let serverState: HasOneRelationState = 'disconnected'
-
-			if (entitySnapshot?.serverData) {
-				const relatedData = (entitySnapshot.serverData as Record<string, unknown>)[fieldName]
-				if (relatedData && typeof relatedData === 'object' && 'id' in relatedData) {
-					serverId = (relatedData as { id: string }).id
-					serverState = 'connected'
-				}
-			}
-
-			this.relationStates.set(key, {
-				currentId: 'currentId' in updates ? updates.currentId! : serverId,
-				serverId,
-				state: 'state' in updates ? updates.state! : serverState,
-				serverState,
-				placeholderData: updates.placeholderData ?? {},
-				version: 0,
-			})
-		} else {
-			this.relationStates.set(key, {
-				...existing,
-				...updates,
-				version: existing.version + 1,
-			})
-		}
+		this.hasOne.setRelation(key, updates, entitySnapshot, fieldName)
 	}
 
-	/**
-	 * Commits relation state (server = current).
-	 */
 	commitRelation(key: string): void {
-		const existing = this.relationStates.get(key)
-		if (!existing) return
+		this.hasOne.commitRelation(key)
+	}
 
-		this.relationStates.set(key, {
-			...existing,
-			serverId: existing.currentId,
-			serverState: existing.state === 'creating' ? 'connected' : existing.state,
-			placeholderData: {},
-			version: existing.version + 1,
-		})
+	reconcileSentRelation(
+		key: string,
+		transition: SentHasOneTransition,
+	): RelationReconciliationResult {
+		return this.hasOne.reconcileSentTransition(key, transition)
 	}
 
-	/**
-	 * Resets relation to server state.
-	 */
 	resetRelation(key: string): void {
-		const existing = this.relationStates.get(key)
-		if (!existing) return
-
-		this.relationStates.set(key, {
-			...existing,
-			currentId: existing.serverId,
-			state: existing.serverState,
-			placeholderData: {},
-			version: existing.version + 1,
-		})
+		this.hasOne.resetRelation(key)
 	}
 
 	// ==================== Has-Many Relations ====================
 
-	/**
-	 * Gets or creates has-many list state.
-	 */
 	getOrCreateHasMany(key: string, serverIds?: string[]): StoredHasManyState {
-		const existing = this.hasManyStates.get(key)
-		if (!existing) {
-			this.hasManyStates.set(key, {
-				serverIds: new Set(serverIds ?? []),
-				orderedIds: null,
-				plannedRemovals: new Map(),
-				plannedConnections: new Set(),
-				createdEntities: new Set(),
-				version: 0,
-			})
-		} else if (serverIds !== undefined) {
-			const newServerIds = new Set(serverIds)
-			if (!setsEqual(existing.serverIds, newServerIds)) {
-				this.hasManyStates.set(key, {
-					...existing,
-					serverIds: newServerIds,
-					orderedIds: null,
-					version: existing.version + 1,
-				})
-			}
-		}
-
-		return this.hasManyStates.get(key)!
+		return this.hasMany.getOrCreateHasMany(key, serverIds)
 	}
 
-	/**
-	 * Gets has-many list state.
-	 */
 	getHasMany(key: string): StoredHasManyState | undefined {
-		return this.hasManyStates.get(key)
+		return this.hasMany.getHasMany(key)
 	}
 
-	/**
-	 * Sets server IDs for a has-many relation.
-	 */
 	setHasManyServerIds(key: string, serverIds: string[]): void {
-		const existing = this.hasManyStates.get(key)
-
-		if (!existing) {
-			this.hasManyStates.set(key, {
-				serverIds: new Set(serverIds),
-				orderedIds: null,
-				plannedRemovals: new Map(),
-				plannedConnections: new Set(),
-				createdEntities: new Set(),
-				version: 0,
-			})
-		} else {
-			this.hasManyStates.set(key, {
-				...existing,
-				serverIds: new Set(serverIds),
-				orderedIds: null,
-				version: existing.version + 1,
-			})
-		}
+		this.hasMany.setHasManyServerIds(key, serverIds)
 	}
 
-	/**
-	 * Plans a removal for a has-many item.
-	 */
 	planHasManyRemoval(key: string, itemId: string, type: HasManyRemovalType): void {
-		const existing = this.hasManyStates.get(key)
-
-		if (!existing) {
-			this.hasManyStates.set(key, {
-				serverIds: new Set(),
-				orderedIds: null,
-				plannedRemovals: new Map([[itemId, type]]),
-				plannedConnections: new Set(),
-				createdEntities: new Set(),
-				version: 0,
-			})
-		} else {
-			const newPlannedRemovals = new Map(existing.plannedRemovals)
-			newPlannedRemovals.set(itemId, type)
-			const newPlannedConnections = new Set(existing.plannedConnections)
-			newPlannedConnections.delete(itemId)
-			let newOrderedIds = existing.orderedIds
-			if (newOrderedIds !== null) {
-				newOrderedIds = newOrderedIds.filter(id => id !== itemId)
-			}
-			const newCreatedEntities = new Set(existing.createdEntities)
-			newCreatedEntities.delete(itemId)
-			this.hasManyStates.set(key, {
-				...existing,
-				orderedIds: newOrderedIds,
-				plannedRemovals: newPlannedRemovals,
-				plannedConnections: newPlannedConnections,
-				createdEntities: newCreatedEntities,
-				version: existing.version + 1,
-			})
-		}
+		this.hasMany.planHasManyRemoval(key, itemId, type)
 	}
 
-	/**
-	 * Plans a connection for a has-many item.
-	 */
 	planHasManyConnection(key: string, itemId: string): void {
-		const existing = this.hasManyStates.get(key)
-
-		if (!existing) {
-			this.hasManyStates.set(key, {
-				serverIds: new Set(),
-				orderedIds: null,
-				plannedRemovals: new Map(),
-				plannedConnections: new Set([itemId]),
-				createdEntities: new Set(),
-				version: 0,
-			})
-		} else {
-			const newPlannedConnections = new Set(existing.plannedConnections)
-			newPlannedConnections.add(itemId)
-			const newPlannedRemovals = new Map(existing.plannedRemovals)
-			newPlannedRemovals.delete(itemId)
-			let newOrderedIds = existing.orderedIds
-			if (newOrderedIds !== null && !newOrderedIds.includes(itemId)) {
-				newOrderedIds = [...newOrderedIds, itemId]
-			}
-			this.hasManyStates.set(key, {
-				...existing,
-				orderedIds: newOrderedIds,
-				plannedConnections: newPlannedConnections,
-				plannedRemovals: newPlannedRemovals,
-				version: existing.version + 1,
-			})
-		}
+		this.hasMany.planHasManyConnection(key, itemId)
 	}
 
-	/**
-	 * Commits has-many state after successful persist.
-	 */
 	commitHasMany(key: string, newServerIds: string[]): void {
-		const existing = this.hasManyStates.get(key)
+		this.hasMany.commitHasMany(key, newServerIds)
+	}
 
-		this.hasManyStates.set(key, {
-			serverIds: new Set(newServerIds),
-			orderedIds: null,
-			plannedRemovals: new Map(),
-			plannedConnections: new Set(),
-			createdEntities: new Set(),
-			version: (existing?.version ?? 0) + 1,
-		})
+	reconcileSentHasMany(
+		key: string,
+		delta: SentHasManyDelta,
+	): RelationReconciliationResult {
+		return this.hasMany.reconcileSentDelta(key, delta)
 	}
 
-	/**
-	 * Resets has-many state to server state (clears planned operations).
-	 */
 	resetHasMany(key: string): void {
-		const existing = this.hasManyStates.get(key)
-		if (!existing) return
-
-		this.hasManyStates.set(key, {
-			serverIds: existing.serverIds,
-			orderedIds: null,
-			plannedRemovals: new Map(),
-			plannedConnections: new Set(),
-			createdEntities: new Set(),
-			version: existing.version + 1,
-		})
+		this.hasMany.resetHasMany(key)
 	}
 
-	/**
-	 * Adds a newly created entity to a has-many relation.
-	 * Used by HasManyListHandle.add() for inline entity creation.
-	 */
 	addToHasMany(key: string, itemId: string): void {
-		const existing = this.hasManyStates.get(key)
-
-		if (!existing) {
-			this.hasManyStates.set(key, {
-				serverIds: new Set(),
-				orderedIds: [itemId],
-				plannedRemovals: new Map(),
-				plannedConnections: new Set([itemId]),
-				createdEntities: new Set([itemId]),
-				version: 0,
-			})
-		} else {
-			const newPlannedConnections = new Set(existing.plannedConnections)
-			newPlannedConnections.add(itemId)
-			const newCreatedEntities = new Set(existing.createdEntities)
-			newCreatedEntities.add(itemId)
-			const currentOrderedIds = existing.orderedIds ?? computeDefaultOrderedIds(existing)
-			const newOrderedIds = [...currentOrderedIds, itemId]
-			this.hasManyStates.set(key, {
-				...existing,
-				orderedIds: newOrderedIds,
-				plannedConnections: newPlannedConnections,
-				createdEntities: newCreatedEntities,
-				version: existing.version + 1,
-			})
-		}
+		this.hasMany.addToHasMany(key, itemId)
 	}
 
-	/**
-	 * Connects an existing (persisted) entity to a has-many relation.
-	 * Unlike addToHasMany, does NOT add to createdEntities — used for
-	 * materializing embedded connect references to existing entities.
-	 */
 	connectExistingToHasMany(key: string, itemId: string): void {
-		const existing = this.hasManyStates.get(key)
-
-		if (!existing) {
-			this.hasManyStates.set(key, {
-				serverIds: new Set(),
-				orderedIds: [itemId],
-				plannedRemovals: new Map(),
-				plannedConnections: new Set([itemId]),
-				createdEntities: new Set(),
-				version: 0,
-			})
-		} else {
-			const newPlannedConnections = new Set(existing.plannedConnections)
-			newPlannedConnections.add(itemId)
-			const currentOrderedIds = existing.orderedIds ?? computeDefaultOrderedIds(existing)
-			const newOrderedIds = [...currentOrderedIds, itemId]
-			this.hasManyStates.set(key, {
-				...existing,
-				orderedIds: newOrderedIds,
-				plannedConnections: newPlannedConnections,
-				version: existing.version + 1,
-			})
-		}
+		this.hasMany.connectExistingToHasMany(key, itemId)
 	}
 
-	/**
-	 * Removes an entity from a has-many relation.
-	 * For newly created entities (via add()), cancels the connection.
-	 * For existing server entities, plans the specified removal type.
-	 * Returns true if the state changed (caller should notify), false if it was a no-op.
-	 */
 	removeFromHasMany(key: string, itemId: string, removalType: HasManyRemovalType): boolean {
-		const existing = this.hasManyStates.get(key)
-		if (!existing) return false
-
-		const isCreatedEntity = existing.createdEntities.has(itemId)
-
-		if (isCreatedEntity) {
-			const newPlannedConnections = new Set(existing.plannedConnections)
-			newPlannedConnections.delete(itemId)
-			const newCreatedEntities = new Set(existing.createdEntities)
-			newCreatedEntities.delete(itemId)
-			let newOrderedIds = existing.orderedIds
-			if (newOrderedIds !== null) {
-				newOrderedIds = newOrderedIds.filter(id => id !== itemId)
-			}
-
-			const newState: StoredHasManyState = {
-				...existing,
-				orderedIds: newOrderedIds,
-				plannedConnections: newPlannedConnections,
-				createdEntities: newCreatedEntities,
-				version: existing.version + 1,
-			}
-
-			if (
-				newPlannedConnections.size === 0 &&
-				newCreatedEntities.size === 0 &&
-				existing.plannedRemovals.size === 0 &&
-				newOrderedIds !== null
-			) {
-				const defaultOrder = computeDefaultOrderedIds(newState)
-				if (arraysEqual(newOrderedIds, defaultOrder)) {
-					newState.orderedIds = null
-				}
-			}
-
-			this.hasManyStates.set(key, newState)
-			return true
-		} else {
-			this.planHasManyRemoval(key, itemId, removalType)
-			return true
-		}
+		return this.hasMany.removeFromHasMany(key, itemId, removalType)
 	}
 
+	moveInHasMany(key: string, fromIndex: number, toIndex: number): void {
+		this.hasMany.moveInHasMany(key, fromIndex, toIndex)
+	}
+
+	getHasManyOrderedIds(key: string): string[] {
+		return this.hasMany.getHasManyOrderedIds(key)
+	}
+
+	// ==================== Reachability / Reverse Lookup ====================
+
 	/**
 	 * Collects the ids of child entities currently reachable through an entity's
-	 * LIVE relations (key prefix "parentType:parentId:"). Used by reachability-based
-	 * create detection to walk the relation graph from roots.
-	 *
-	 * Live edges are:
-	 *   - has-one: currentId, when the relation is not disconnected/deleted
-	 *     (a disconnected relation has a null currentId; a 'deleted' relation is
-	 *     removing its target, so the target is not anchored by it).
-	 *   - has-many: effective members = (serverIds ∪ plannedConnections ∪
-	 *     createdEntities) minus plannedRemovals.
+	 * LIVE relations (key prefix "parentType:parentId:"). Unions the live has-one
+	 * edges with the live has-many members.
 	 */
 	getLiveChildIds(keyPrefix: string): string[] {
 		const ids = new Set<string>()
-
-		for (const [key, state] of this.relationStates) {
-			if (!key.startsWith(keyPrefix)) continue
-			if (state.currentId !== null && state.state !== 'deleted') {
-				ids.add(state.currentId)
-			}
-		}
-
-		for (const [key, state] of this.hasManyStates) {
-			if (!key.startsWith(keyPrefix)) continue
-			for (const id of state.serverIds) {
-				if (!state.plannedRemovals.has(id)) ids.add(id)
-			}
-			for (const id of state.plannedConnections) {
-				if (!state.plannedRemovals.has(id)) ids.add(id)
-			}
-			for (const id of state.createdEntities) {
-				if (!state.plannedRemovals.has(id)) ids.add(id)
-			}
-		}
-
+		this.hasOne.collectLiveChildIds(keyPrefix, ids)
+		this.hasMany.collectLiveChildIds(keyPrefix, ids)
 		return Array.from(ids)
 	}
 
 	/**
-	 * Removes all relation and has-many state owned by an entity (keys under the
-	 * given owner prefix). Called by removeEntity so a removed entity leaves no
-	 * stale relation state behind.
+	 * Collects the composite keys ("parentType:parentId") of every entity that
+	 * currently has a LIVE relation edge pointing at {@link childId} — the reverse
+	 * of {@link getLiveChildIds}. Unions both sub-stores' results, scanning the
+	 * same live edges the forward query reads so the two never disagree.
+	 *
+	 * {@link childId} is a BARE entity id (no type): relation state records child ids
+	 * without their type, so the match is by id alone. This deliberately relies on
+	 * the store-wide invariant that entity ids are globally unique across types
+	 * (server UUIDs / minted temp ids — the same invariant behind
+	 * EntitySnapshotStore's idIndex / keyForId), so a bare id resolves to exactly one
+	 * entity. The forward reachability walk matches on the same bare ids, so making
+	 * this type-aware in isolation would only diverge the two halves of one query.
 	 */
-	removeOwnedRelations(keyPrefix: string): void {
-		for (const key of [...this.relationStates.keys()]) {
-			if (key.startsWith(keyPrefix)) {
-				this.relationStates.delete(key)
-			}
-		}
-		for (const key of [...this.hasManyStates.keys()]) {
-			if (key.startsWith(keyPrefix)) {
-				this.hasManyStates.delete(key)
-			}
-		}
+	getParentKeysForChild(childId: string): Set<string> {
+		const parents = new Set<string>()
+		this.hasOne.collectParentKeysForChild(childId, parents)
+		this.hasMany.collectParentKeysForChild(childId, parents)
+		return parents
 	}
 
+	// ==================== Bulk Operations ====================
+
 	/**
-	 * Moves an item within a has-many relation from one index to another.
+	 * Keys of every has-one relation owned by an entity (owner prefix
+	 * "parentType:parentId:"). Used by the journal's entry-closure to enumerate a
+	 * detached created entity's own relation cells.
 	 */
-	moveInHasMany(key: string, fromIndex: number, toIndex: number): void {
-		const existing = this.hasManyStates.get(key)
-		if (!existing) return
-
-		const currentOrderedIds = existing.orderedIds ?? computeDefaultOrderedIds(existing)
-
-		if (fromIndex < 0 || fromIndex >= currentOrderedIds.length) return
-		if (toIndex < 0 || toIndex >= currentOrderedIds.length) return
-		if (fromIndex === toIndex) return
-
-		const newOrderedIds = [...currentOrderedIds]
-		const movedItem = newOrderedIds.splice(fromIndex, 1)[0]
-		if (movedItem === undefined) return
-		newOrderedIds.splice(toIndex, 0, movedItem)
-
-		this.hasManyStates.set(key, {
-			...existing,
-			orderedIds: newOrderedIds,
-			version: existing.version + 1,
-		})
+	getOwnedRelationKeys(keyPrefix: string): string[] {
+		const keys: string[] = []
+		this.hasOne.collectOwnedKeys(keyPrefix, keys)
+		return keys
 	}
 
 	/**
-	 * Gets the ordered list of item IDs for a has-many relation.
+	 * Keys of every has-many list owned by an entity (owner prefix
+	 * "parentType:parentId:"). Counterpart of {@link getOwnedRelationKeys}.
 	 */
-	getHasManyOrderedIds(key: string): string[] {
-		const existing = this.hasManyStates.get(key)
-		if (!existing) return []
-
-		if (existing.orderedIds !== null) {
-			return existing.orderedIds
-		}
-
-		return computeDefaultOrderedIds(existing)
+	getOwnedHasManyKeys(keyPrefix: string): string[] {
+		const keys: string[] = []
+		this.hasMany.collectOwnedKeys(keyPrefix, keys)
+		return keys
 	}
 
 	/**
-	 * Restores a has-many state from a captured snapshot.
-	 * Used in pessimistic mode after successful server confirmation.
+	 * Removes a single has-one relation state by key (undo restore of an
+	 * absent-before-the-gesture relation).
 	 */
-	restoreHasManyState(key: string, state: StoredHasManyState): void {
-		this.hasManyStates.set(key, {
-			serverIds: new Set(state.serverIds),
-			orderedIds: state.orderedIds ? [...state.orderedIds] : null,
-			plannedRemovals: new Map(state.plannedRemovals),
-			plannedConnections: new Set(state.plannedConnections),
-			createdEntities: new Set(state.createdEntities),
-			version: state.version + 1,
-		})
+	removeRelationState(key: string): void {
+		this.hasOne.removeRelation(key)
 	}
 
-	// ==================== Bulk Operations ====================
-
 	/**
-	 * Commits all relations (hasOne and hasMany) for an entity.
+	 * Removes a single has-many list state by key (undo restore of an
+	 * absent-before-the-gesture list).
 	 */
-	commitAllRelations(keyPrefix: string): void {
-		for (const key of this.relationStates.keys()) {
-			if (key.startsWith(keyPrefix)) {
-				this.commitRelation(key)
-			}
-		}
-
-		for (const [key, state] of this.hasManyStates) {
-			if (key.startsWith(keyPrefix)) {
-				const newServerIds = new Set(state.serverIds)
-				for (const removedId of state.plannedRemovals.keys()) {
-					newServerIds.delete(removedId)
-				}
-				for (const connectedId of state.plannedConnections) {
-					newServerIds.add(connectedId)
-				}
-				this.commitHasMany(key, Array.from(newServerIds))
-			}
-		}
+	removeHasManyState(key: string): void {
+		this.hasMany.removeHasMany(key)
 	}
 
 	/**
-	 * Resets all relations (hasOne and hasMany) for an entity to server state.
+	 * Removes all relation and has-many state owned by an entity (keys under the
+	 * given owner prefix). Called by removeEntity so a removed entity leaves no
+	 * stale relation state behind.
 	 */
-	resetAllRelations(keyPrefix: string): void {
-		for (const key of this.relationStates.keys()) {
-			if (key.startsWith(keyPrefix)) {
-				this.resetRelation(key)
-			}
-		}
-
-		for (const key of this.hasManyStates.keys()) {
-			if (key.startsWith(keyPrefix)) {
-				this.resetHasMany(key)
-			}
-		}
+	removeOwnedRelations(keyPrefix: string): void {
+		this.hasOne.removeOwnedRelations(keyPrefix)
+		this.hasMany.removeOwnedRelations(keyPrefix)
 	}
 
 	/**
-	 * Gets all relation states for an entity.
+	 * Commits all relations (hasOne and hasMany) for an entity.
 	 */
-	getAllRelationsForEntity(keyPrefix: string): Map<string, StoredRelationState> {
-		const result = new Map<string, StoredRelationState>()
-		for (const [key, state] of this.relationStates) {
-			if (key.startsWith(keyPrefix)) {
-				result.set(key, { ...state })
-			}
-		}
-		return result
+	commitAllRelations(keyPrefix: string, pendingItems?: ReadonlyMap<string, ReadonlySet<string>>): void {
+		this.hasOne.commitAllRelations(keyPrefix, pendingItems)
+		this.hasMany.commitAllRelations(keyPrefix, pendingItems)
 	}
 
 	/**
-	 * Gets all has-many states for an entity.
+	 * Resets all relations (hasOne and hasMany) for an entity to server state.
 	 */
-	getAllHasManyForEntity(keyPrefix: string): Map<string, StoredHasManyState> {
-		const result = new Map<string, StoredHasManyState>()
-		for (const [key, state] of this.hasManyStates) {
-			if (key.startsWith(keyPrefix)) {
-				result.set(key, {
-					serverIds: new Set(state.serverIds),
-					orderedIds: state.orderedIds ? [...state.orderedIds] : null,
-					plannedRemovals: new Map(state.plannedRemovals),
-					plannedConnections: new Set(state.plannedConnections),
-					createdEntities: new Set(state.createdEntities),
-					version: state.version,
-				})
-			}
-		}
-		return result
+	resetAllRelations(keyPrefix: string): void {
+		this.hasOne.resetAllRelations(keyPrefix)
+		this.hasMany.resetAllRelations(keyPrefix)
 	}
 
 	// ==================== Dirty Tracking ====================
 
 	/**
-	 * Gets the list of dirty relations for an entity.
+	 * Gets the list of dirty relations (has-one and has-many) for an entity.
 	 */
 	getDirtyRelations(keyPrefix: string): string[] {
 		const dirtyRelations: string[] = []
-
-		for (const [key, state] of this.relationStates) {
-			if (!key.startsWith(keyPrefix)) continue
-			const fieldName = key.slice(keyPrefix.length)
-
-			if (
-				state.currentId !== state.serverId ||
-				state.state !== state.serverState ||
-				Object.keys(state.placeholderData).length > 0
-			) {
-				dirtyRelations.push(fieldName)
-			}
-		}
-
-		for (const [key, state] of this.hasManyStates) {
-			if (!key.startsWith(keyPrefix)) continue
-			const fieldName = key.slice(keyPrefix.length)
-
-			if (state.plannedRemovals.size > 0 || state.plannedConnections.size > 0) {
-				dirtyRelations.push(fieldName)
-			}
-		}
-
+		this.hasOne.collectDirtyRelations(keyPrefix, dirtyRelations)
+		this.hasMany.collectDirtyRelations(keyPrefix, dirtyRelations)
 		return dirtyRelations
 	}
 
 	// ==================== Export/Import ====================
 
-	/**
-	 * Exports relation states for given keys.
-	 */
 	exportRelationStates(keys: string[]): Map<string, StoredRelationState> {
-		const result = new Map<string, StoredRelationState>()
-		for (const key of keys) {
-			const state = this.relationStates.get(key)
-			if (state) {
-				result.set(key, {
-					...state,
-					placeholderData: { ...state.placeholderData },
-				})
-			}
-		}
-		return result
+		return this.hasOne.exportRelationStates(keys)
 	}
 
-	/**
-	 * Exports has-many states for given keys.
-	 */
 	exportHasManyStates(keys: string[]): Map<string, StoredHasManyState> {
-		const result = new Map<string, StoredHasManyState>()
-		for (const key of keys) {
-			const state = this.hasManyStates.get(key)
-			if (state) {
-				result.set(key, {
-					serverIds: new Set(state.serverIds),
-					orderedIds: state.orderedIds ? [...state.orderedIds] : null,
-					plannedRemovals: new Map(state.plannedRemovals),
-					plannedConnections: new Set(state.plannedConnections),
-					createdEntities: new Set(state.createdEntities),
-					version: state.version,
-				})
-			}
-		}
-		return result
+		return this.hasMany.exportHasManyStates(keys)
 	}
 
-	/**
-	 * Imports relation states from a snapshot.
-	 * Returns the keys that were imported for notification.
-	 */
 	importRelationStates(states: Map<string, StoredRelationState>): string[] {
-		const keys: string[] = []
-		for (const [key, state] of states) {
-			this.relationStates.set(key, {
-				...state,
-				placeholderData: { ...state.placeholderData },
-			})
-			keys.push(key)
-		}
-		return keys
+		return this.hasOne.importRelationStates(states)
 	}
 
-	/**
-	 * Imports has-many states from a snapshot.
-	 * Returns the keys that were imported for notification.
-	 */
 	importHasManyStates(states: Map<string, StoredHasManyState>): string[] {
-		const keys: string[] = []
-		for (const [key, state] of states) {
-			this.hasManyStates.set(key, {
-				serverIds: new Set(state.serverIds),
-				orderedIds: state.orderedIds ? [...state.orderedIds] : null,
-				plannedRemovals: new Map(state.plannedRemovals),
-				plannedConnections: new Set(state.plannedConnections),
-				createdEntities: new Set(state.createdEntities),
-				version: state.version + 1,
-			})
-			keys.push(key)
-		}
-		return keys
+		return this.hasMany.importHasManyStates(states)
 	}
 
+	// ==================== Rekey ====================
+
 	/**
 	 * Replaces all occurrences of oldId with newId across relation and hasMany states.
 	 * Used after persist to rekey temp IDs to server-assigned IDs.
 	 */
 	replaceEntityId(oldId: string, newId: string): void {
-		// Replace in has-one relation states: currentId, serverId
-		for (const [key, state] of this.relationStates) {
-			let changed = false
-			let currentId = state.currentId
-			let serverId = state.serverId
-
-			if (currentId === oldId) { currentId = newId; changed = true }
-			if (serverId === oldId) { serverId = newId; changed = true }
-
-			if (changed) {
-				this.relationStates.set(key, { ...state, currentId, serverId, version: state.version + 1 })
-			}
-		}
-
-		// Replace in has-many states: serverIds, orderedIds, plannedConnections, createdEntities, plannedRemovals
-		for (const [key, state] of this.hasManyStates) {
-			let changed = false
-
-			let serverIds = state.serverIds
-			if (serverIds.has(oldId)) {
-				serverIds = new Set(serverIds)
-				serverIds.delete(oldId)
-				serverIds.add(newId)
-				changed = true
-			}
-
-			let orderedIds = state.orderedIds
-			if (orderedIds) {
-				const idx = orderedIds.indexOf(oldId)
-				if (idx !== -1) {
-					orderedIds = [...orderedIds]
-					orderedIds[idx] = newId
-					changed = true
-				}
-			}
-
-			let plannedConnections = state.plannedConnections
-			if (plannedConnections.has(oldId)) {
-				plannedConnections = new Set(plannedConnections)
-				plannedConnections.delete(oldId)
-				plannedConnections.add(newId)
-				changed = true
-			}
-
-			let createdEntities = state.createdEntities
-			if (createdEntities.has(oldId)) {
-				createdEntities = new Set(createdEntities)
-				createdEntities.delete(oldId)
-				createdEntities.add(newId)
-				changed = true
-			}
-
-			let plannedRemovals = state.plannedRemovals
-			if (plannedRemovals.has(oldId)) {
-				const removalType = plannedRemovals.get(oldId)!
-				plannedRemovals = new Map(plannedRemovals)
-				plannedRemovals.delete(oldId)
-				plannedRemovals.set(newId, removalType)
-				changed = true
-			}
-
-			if (changed) {
-				this.hasManyStates.set(key, {
-					serverIds,
-					orderedIds,
-					plannedRemovals,
-					plannedConnections,
-					createdEntities,
-					version: state.version + 1,
-				})
-			}
-		}
+		this.hasOne.replaceEntityId(oldId, newId)
+		this.hasMany.replaceEntityId(oldId, newId)
+	}
+
+	/**
+	 * Migrates an entity's relation state for a temp→persisted rekey: first the
+	 * relation/has-many keys it owns (the parent id in the key), then every value
+	 * reference to its id from other entities' relations.
+	 */
+	rekey(ctx: RekeyContext): void {
+		this.rekeyOwner(ctx.oldKeyPrefix, ctx.newKeyPrefix)
+		this.replaceEntityId(ctx.oldId, ctx.newId)
 	}
 
 	/**
 	 * Rekeys relation/hasMany entries owned by an entity (changes the parent ID in the key).
 	 */
 	rekeyOwner(oldKeyPrefix: string, newKeyPrefix: string): void {
-		const toMoveRelations: [string, StoredRelationState][] = []
-		for (const [key, value] of this.relationStates) {
-			if (key.startsWith(oldKeyPrefix)) {
-				toMoveRelations.push([key, value])
-			}
-		}
-		for (const [oldKey, value] of toMoveRelations) {
-			this.relationStates.delete(oldKey)
-			this.relationStates.set(newKeyPrefix + oldKey.slice(oldKeyPrefix.length), value)
-		}
-
-		const toMoveHasMany: [string, StoredHasManyState][] = []
-		for (const [key, value] of this.hasManyStates) {
-			if (key.startsWith(oldKeyPrefix)) {
-				toMoveHasMany.push([key, value])
-			}
-		}
-		for (const [oldKey, value] of toMoveHasMany) {
-			this.hasManyStates.delete(oldKey)
-			this.hasManyStates.set(newKeyPrefix + oldKey.slice(oldKeyPrefix.length), value)
-		}
+		this.hasOne.rekeyOwner(oldKeyPrefix, newKeyPrefix)
+		this.hasMany.rekeyOwner(oldKeyPrefix, newKeyPrefix)
 	}
 
 	/**
 	 * Clears all relation data.
 	 */
 	clear(): void {
-		this.relationStates.clear()
-		this.hasManyStates.clear()
-	}
-}
-
-// ==================== Helper Functions ====================
-
-/**
- * Computes the default ordered IDs for a has-many relation.
- * Order is: serverIds (minus removals) + plannedConnections
- */
-export function computeDefaultOrderedIds(state: StoredHasManyState): string[] {
-	const result: string[] = []
-
-	for (const id of state.serverIds) {
-		if (!state.plannedRemovals.has(id)) {
-			result.push(id)
-		}
-	}
-
-	for (const id of state.plannedConnections) {
-		if (!result.includes(id)) {
-			result.push(id)
-		}
-	}
-
-	return result
-}
-
-function arraysEqual(a: string[], b: string[]): boolean {
-	if (a.length !== b.length) return false
-	for (let i = 0; i < a.length; i++) {
-		if (a[i] !== b[i]) return false
+		this.hasOne.clear()
+		this.hasMany.clear()
 	}
-	return true
 }