@contember/bindx 0.1.46 → 0.1.48

package/src/persistence/PersistExecution.ts

@@ -0,0 +1,217 @@
+import type { DirtyEntity } from './ChangeRegistry.js'
+import type {
+	CollectedHasManyChange,
+	CollectedHasOneChange,
+	CollectedNestedCreate,
+	CollectedNestedEntity,
+	CollectedNestedUpdate,
+	CollectedRelationField,
+} from './MutationCollector.js'
+import type { PersistScope, TransactionMutation } from './types.js'
+import type { SnapshotStore } from '../store/SnapshotStore.js'
+
+export interface ExecutionEntity {
+	readonly entityType: string
+	readonly entityId: string
+	readonly operation: 'create' | 'update' | 'delete'
+	readonly scalarData: Readonly<Record<string, unknown>>
+	readonly nested: boolean
+}
+
+export interface PersistExecution {
+	readonly mutations: readonly TransactionMutation[]
+	readonly entities: readonly ExecutionEntity[]
+	readonly hasOneChanges: readonly CollectedHasOneChange[]
+	readonly hasManyChanges: readonly CollectedHasManyChange[]
+	readonly vetoed: readonly DirtyEntity[]
+	readonly nestedEntities: readonly CollectedNestedEntity[]
+	readonly relationFields: readonly CollectedRelationField[]
+	readonly nestedCreates: readonly CollectedNestedCreate[]
+	readonly nestedUpdates: readonly CollectedNestedUpdate[]
+	readonly suppressedRelationItems: ReadonlyMap<string, ReadonlySet<string>>
+}
+
+export function entityIdentityKey(entityType: string, entityId: string): string {
+	return `${entityType}:${entityId}`
+}
+
+export function createPersistExecution(
+	store: SnapshotStore,
+	mutations: readonly TransactionMutation[],
+	entities: readonly DirtyEntity[],
+	nestedEntities: readonly CollectedNestedEntity[],
+	relationFieldMetadata: readonly CollectedRelationField[],
+	nestedCreateMetadata: readonly CollectedNestedCreate[],
+	nestedUpdateMetadata: readonly CollectedNestedUpdate[],
+	hasOneChanges: readonly CollectedHasOneChange[],
+	hasManyChanges: readonly CollectedHasManyChange[],
+	vetoed: readonly DirtyEntity[],
+	suppressedRelationItems: ReadonlyMap<string, ReadonlySet<string>>,
+	scope: PersistScope,
+): PersistExecution {
+	const uniqueHasOne = new Map(
+		hasOneChanges.map(change => [relationIdentityKey(change.entityType, change.entityId, change.fieldName), change]),
+	)
+	const uniqueHasMany = new Map(
+		hasManyChanges.map(change => [relationIdentityKey(change.entityType, change.entityId, change.fieldName), change]),
+	)
+	const sentHasOneChanges = [...uniqueHasOne.values()]
+	const sentHasManyChanges = [...uniqueHasMany.values()]
+	const uniqueNestedCreates = new Map(
+		nestedCreateMetadata.map(create => [nestedIdentityKey(
+			create.parentEntityType,
+			create.parentEntityId,
+			create.fieldName,
+			create.entityType,
+			create.entityId,
+		), create]),
+	)
+	const uniqueNestedUpdates = new Map(
+		nestedUpdateMetadata.map(update => [nestedIdentityKey(
+			update.parentEntityType,
+			update.parentEntityId,
+			update.fieldName,
+			update.entityType,
+			update.entityId,
+		), update]),
+	)
+	const nestedCreates = [...uniqueNestedCreates.values()]
+	const nestedUpdates = [...uniqueNestedUpdates.values()]
+	const topLevelOperations = new Map(
+		mutations.map(mutation => [entityIdentityKey(mutation.entityType, mutation.entityId), mutation.operation]),
+	)
+	const topLevelMutations = new Map(
+		mutations.map(mutation => [entityIdentityKey(mutation.entityType, mutation.entityId), mutation]),
+	)
+	const uniqueRelationFields = new Map(
+		relationFieldMetadata.map(field => [relationIdentityKey(field.entityType, field.entityId, field.fieldName), field]),
+	)
+	const relationFields = new Map<string, Set<string>>()
+	for (const change of uniqueRelationFields.values()) {
+		const key = entityIdentityKey(change.entityType, change.entityId)
+		const fields = relationFields.get(key)
+		if (fields) fields.add(change.fieldName)
+		else relationFields.set(key, new Set([change.fieldName]))
+	}
+	const nestedKeys = new Set(nestedEntities.map(entity => entityIdentityKey(entity.entityType, entity.entityId)))
+	const nestedMutationData = new Map<string, Readonly<Record<string, unknown>>>()
+	for (const create of nestedCreates) {
+		nestedMutationData.set(entityIdentityKey(create.entityType, create.entityId), create.createData)
+	}
+	for (const update of nestedUpdates) {
+		nestedMutationData.set(entityIdentityKey(update.entityType, update.entityId), update.data)
+		nestedKeys.add(entityIdentityKey(update.entityType, update.entityId))
+	}
+	const all = new Map<string, ExecutionEntity>()
+
+	const candidates: DirtyEntity[] = [...entities]
+	for (const nested of nestedEntities) {
+		candidates.push({
+			entityType: nested.entityType,
+			entityId: nested.entityId,
+			changeType: 'create',
+			dirtyFields: [],
+			dirtyRelations: [],
+		})
+	}
+	for (const nested of nestedUpdates) {
+		candidates.push({
+			entityType: nested.entityType,
+			entityId: nested.entityId,
+			changeType: 'update',
+			dirtyFields: Object.keys(nested.data),
+			dirtyRelations: [],
+		})
+	}
+
+	for (const entity of candidates) {
+		const key = entityIdentityKey(entity.entityType, entity.entityId)
+		if (all.has(key) || vetoed.some(item => entityIdentityKey(item.entityType, item.entityId) === key)) continue
+		const operation = topLevelOperations.get(key) ?? entity.changeType
+		all.set(key, {
+			entityType: entity.entityType,
+			entityId: entity.entityId,
+			operation,
+			scalarData: collectSentScalars(
+				store,
+				entity,
+				scope,
+				topLevelMutations.get(key)?.data ?? nestedMutationData.get(key),
+				relationFields.get(key) ?? new Set(),
+			),
+			nested: nestedKeys.has(key),
+		})
+	}
+
+	return {
+		mutations: mutations.map(mutation => ({
+			...mutation,
+			data: mutation.data ? { ...mutation.data } : undefined,
+		})),
+		entities: [...all.values()],
+		hasOneChanges: sentHasOneChanges.map(change => ({ ...change, transition: { ...change.transition } })),
+		hasManyChanges: sentHasManyChanges.map(change => ({
+			...change,
+			additions: change.additions.map(addition => ({ ...addition })),
+			removals: change.removals.map(removal => ({ ...removal })),
+		})),
+		vetoed: [...vetoed],
+		nestedEntities: [...nestedEntities],
+		relationFields: [...uniqueRelationFields.values()],
+		nestedCreates: nestedCreates.map(create => ({
+			...create,
+			createData: { ...create.createData },
+			knownServerIds: [...create.knownServerIds],
+		})),
+		nestedUpdates: nestedUpdates.map(update => ({ ...update, data: { ...update.data } })),
+		suppressedRelationItems: new Map(
+			[...suppressedRelationItems].map(([key, ids]) => [key, new Set(ids)]),
+		),
+	}
+}
+
+function relationIdentityKey(entityType: string, entityId: string, fieldName: string): string {
+	return `${entityIdentityKey(entityType, entityId)}:${fieldName}`
+}
+
+function nestedIdentityKey(
+	parentEntityType: string,
+	parentEntityId: string,
+	fieldName: string,
+	entityType: string,
+	entityId: string,
+): string {
+	return `${relationIdentityKey(parentEntityType, parentEntityId, fieldName)}>${entityIdentityKey(entityType, entityId)}`
+}
+
+function collectSentScalars(
+	store: SnapshotStore,
+	entity: Pick<DirtyEntity, 'entityType' | 'entityId' | 'changeType' | 'dirtyFields'>,
+	scope: PersistScope,
+	mutationData: Readonly<Record<string, unknown>> | undefined,
+	relationFields: ReadonlySet<string>,
+): Readonly<Record<string, unknown>> {
+	if (entity.changeType === 'delete') return {}
+	if (mutationData) {
+		const result: Record<string, unknown> = {}
+		for (const [field, value] of Object.entries(mutationData)) {
+			if (!relationFields.has(field)) result[field] = value
+		}
+		return result
+	}
+	const snapshot = store.getEntitySnapshot<Record<string, unknown>>(entity.entityType, entity.entityId)
+	if (!snapshot) return {}
+	const fields = scope.type === 'fields'
+		&& scope.entityType === entity.entityType
+		&& scope.entityId === entity.entityId
+		? scope.fields
+		: entity.changeType === 'create'
+			? Object.keys(snapshot.data)
+			: store.getDirtyFields(entity.entityType, entity.entityId)
+	const result: Record<string, unknown> = {}
+	for (const field of fields) {
+		if (field === 'id' && entity.entityId.startsWith('__temp_')) continue
+		result[field] = snapshot.data[field]
+	}
+	return result
+}

package/src/persistence/types.ts

@@ -97,6 +97,12 @@ export interface EntityPersistResult {
 	readonly entityId: string
 	readonly operation: 'create' | 'update' | 'delete'
 	readonly success: boolean
+	/**
+	 * The entity was deliberately not sent (vetoed by an `entity:persisting`
+	 * interceptor). `success` is false, but it counts towards `skippedCount`,
+	 * not `failedCount`.
+	 */
+	readonly skipped?: true
 	readonly error?: PersistError
 	readonly fieldResults?: readonly FieldPersistResult[]
 	/** Server-assigned ID for creates (when tempId was used) */
@@ -121,9 +127,9 @@ export interface PersistenceResult {
 	readonly results: readonly EntityPersistResult[]
 	/** Number of successfully persisted entities */
 	readonly successCount: number
-	/** Number of failed entities */
+	/** Number of entities the server rejected — results with `success: false` and no `skipped` flag */
 	readonly failedCount: number
-	/** Number of entities skipped (e.g., already in-flight) */
+	/** Number of entities not sent: already in-flight, or vetoed by an interceptor (listed in `results` with `skipped`) */
 	readonly skippedCount: number
 }
 

package/src/store/EntityMetaStore.ts

@@ -1,6 +1,6 @@
 import type { LoadStatus } from './snapshots.js'
-import { isPersistedId, isPlaceholderId } from './entityId.js'
 import type { FieldError } from '../errors/types.js'
+import type { RekeyContext, Rekeyable } from './RekeyOrchestrator.js'
 
 /**
  * Entity load state tracking.
@@ -26,7 +26,7 @@ export interface EntityMeta {
  * Keys are pre-computed composite strings (e.g., "entityType:id").
  * Follows the same pattern as ErrorStore and RelationStore.
  */
-export class EntityMetaStore {
+export class EntityMetaStore implements Rekeyable {
 	/** Load states keyed by "entityType:id" */
 	private readonly loadStates = new Map<string, EntityLoadState>()
 
@@ -36,8 +36,37 @@ export class EntityMetaStore {
 	/** Persisting status keyed by "entityType:id" */
 	private readonly persistingEntities = new Set<string>()
 
-	/** Mapping from temp ID to persisted ID (keyed by "entityType:tempId") */
-	private readonly tempToPersistedId = new Map<string, string>()
+	/**
+	 * Entities whose in-flight persist is pessimistic, keyed by "entityType:id".
+	 * A subset of {@link persistingEntities}. While present, the entity is
+	 * presented at its server baseline (see SnapshotStore.getPresentationSnapshot)
+	 * even though its canonical data stays dirty.
+	 */
+	private readonly pessimisticInFlight = new Set<string>()
+
+	/**
+	 * Monotonic counter bumped when reachability-relevant metadata changes —
+	 * `existsOnServer` and `isPersisting` (which seed the reachability roots) plus
+	 * entity removal/rekey. Load state and deletion scheduling do NOT bump it.
+	 * Used by {@link ReachabilityAnalyzer} to memoize its walk.
+	 */
+	private mutationVersion = 0
+
+	/**
+	 * Monotonic counter bumped on EDITABLE-layer meta writes — deletion scheduling,
+	 * the one undoable gesture this store owns. Server-baseline (`setExistsOnServer`),
+	 * load/persist state, removal, rekey, import and clear deliberately do NOT bump
+	 * it. Read by the undo write-guard (see UndoJournal).
+	 */
+	private editableWriteVersion = 0
+
+	getMutationVersion(): number {
+		return this.mutationVersion
+	}
+
+	getEditableWriteVersion(): number {
+		return this.editableWriteVersion
+	}
 
 	// ==================== Load State ====================
 
@@ -60,8 +89,15 @@ export class EntityMetaStore {
 	}
 
 	setExistsOnServer(key: string, existsOnServer: boolean): void {
-		const existing = this.entityMetas.get(key) ?? { existsOnServer: false, isScheduledForDeletion: false }
-		this.entityMetas.set(key, { ...existing, existsOnServer })
+		const existing = this.entityMetas.get(key)
+		if (existing && existing.existsOnServer === existsOnServer) {
+			return
+		}
+		this.entityMetas.set(key, {
+			existsOnServer,
+			isScheduledForDeletion: existing?.isScheduledForDeletion ?? false,
+		})
+		this.mutationVersion++
 	}
 
 	existsOnServer(key: string): boolean {
@@ -71,11 +107,13 @@ export class EntityMetaStore {
 	scheduleForDeletion(key: string): void {
 		const existing = this.entityMetas.get(key) ?? { existsOnServer: false, isScheduledForDeletion: false }
 		this.entityMetas.set(key, { ...existing, isScheduledForDeletion: true })
+		this.editableWriteVersion++
 	}
 
 	unscheduleForDeletion(key: string): void {
 		const existing = this.entityMetas.get(key) ?? { existsOnServer: false, isScheduledForDeletion: false }
 		this.entityMetas.set(key, { ...existing, isScheduledForDeletion: false })
+		this.editableWriteVersion++
 	}
 
 	isScheduledForDeletion(key: string): boolean {
@@ -88,70 +126,72 @@ export class EntityMetaStore {
 		return this.persistingEntities.has(key)
 	}
 
-	setPersisting(key: string, isPersisting: boolean): void {
+	setPersisting(key: string, isPersisting: boolean, pessimistic: boolean = false): void {
 		if (isPersisting) {
-			this.persistingEntities.add(key)
+			if (!this.persistingEntities.has(key)) {
+				this.persistingEntities.add(key)
+				this.mutationVersion++
+			}
+			// The pessimistic flag drives presentation only, not reachability, so it
+			// deliberately does not bump mutationVersion.
+			if (pessimistic) {
+				this.pessimisticInFlight.add(key)
+			} else {
+				this.pessimisticInFlight.delete(key)
+			}
 		} else {
-			this.persistingEntities.delete(key)
+			if (this.persistingEntities.delete(key)) {
+				this.mutationVersion++
+			}
+			this.pessimisticInFlight.delete(key)
 		}
 	}
 
-	// ==================== Temp ID Mapping ====================
-
-	mapTempIdToPersistedId(key: string, persistedId: string): void {
-		this.tempToPersistedId.set(key, persistedId)
-		this.setExistsOnServer(key, true)
-	}
-
-	getPersistedId(key: string, id: string): string | null {
-		if (isPlaceholderId(id)) return null
-		if (isPersistedId(id)) return id
-		return this.tempToPersistedId.get(key) ?? null
-	}
-
-	isNewEntity(key: string, id: string): boolean {
-		if (isPlaceholderId(id)) return true
-		if (isPersistedId(id)) return false
-		return !this.tempToPersistedId.has(key)
+	isPessimisticInFlight(key: string): boolean {
+		return this.pessimisticInFlight.has(key)
 	}
 
 	/**
-	 * Removes all metadata for an entity (load state, meta, persisting, temp mapping).
+	 * Removes all metadata for an entity (load state, meta, persisting).
 	 */
 	remove(key: string): void {
 		this.loadStates.delete(key)
 		this.entityMetas.delete(key)
 		this.persistingEntities.delete(key)
-		this.tempToPersistedId.delete(key)
+		this.pessimisticInFlight.delete(key)
+		this.mutationVersion++
 	}
 
 	/**
-	 * Moves all metadata from oldKey to newKey.
+	 * Moves all metadata from the temp key to the persisted key. The entity has
+	 * just been confirmed by the server, so it is also marked as existing there
+	 * (this replaces the former separate mapTempIdToPersistedId step).
 	 */
-	rekey(oldKey: string, newKey: string): void {
-		const meta = this.entityMetas.get(oldKey)
+	rekey(ctx: RekeyContext): void {
+		const meta = this.entityMetas.get(ctx.oldKey)
 		if (meta) {
-			this.entityMetas.delete(oldKey)
-			this.entityMetas.set(newKey, meta)
+			this.entityMetas.delete(ctx.oldKey)
+			this.entityMetas.set(ctx.newKey, meta)
 		}
 
-		const loadState = this.loadStates.get(oldKey)
+		const loadState = this.loadStates.get(ctx.oldKey)
 		if (loadState) {
-			this.loadStates.delete(oldKey)
-			this.loadStates.set(newKey, loadState)
+			this.loadStates.delete(ctx.oldKey)
+			this.loadStates.set(ctx.newKey, loadState)
 		}
 
-		if (this.persistingEntities.has(oldKey)) {
-			this.persistingEntities.delete(oldKey)
-			this.persistingEntities.add(newKey)
+		if (this.persistingEntities.has(ctx.oldKey)) {
+			this.persistingEntities.delete(ctx.oldKey)
+			this.persistingEntities.add(ctx.newKey)
 		}
 
-		// Move temp ID mapping
-		const persistedId = this.tempToPersistedId.get(oldKey)
-		if (persistedId !== undefined) {
-			this.tempToPersistedId.delete(oldKey)
-			this.tempToPersistedId.set(newKey, persistedId)
+		if (this.pessimisticInFlight.has(ctx.oldKey)) {
+			this.pessimisticInFlight.delete(ctx.oldKey)
+			this.pessimisticInFlight.add(ctx.newKey)
 		}
+
+		this.mutationVersion++
+		this.setExistsOnServer(ctx.newKey, true)
 	}
 
 	// ==================== Bulk Operations ====================
@@ -168,15 +208,19 @@ export class EntityMetaStore {
 	}
 
 	importMetas(metas: Map<string, EntityMeta>): void {
+		let imported = false
 		for (const [key, meta] of metas) {
 			this.entityMetas.set(key, { ...meta })
+			imported = true
 		}
+		if (imported) this.mutationVersion++
 	}
 
 	clear(): void {
 		this.loadStates.clear()
 		this.entityMetas.clear()
 		this.persistingEntities.clear()
-		this.tempToPersistedId.clear()
+		this.pessimisticInFlight.clear()
+		this.mutationVersion++
 	}
 }

package/src/store/EntitySnapshotStore.ts

@@ -2,6 +2,7 @@ import {
 	createEntitySnapshot,
 	type EntitySnapshot,
 } from './snapshots.js'
+import type { RekeyContext, Rekeyable } from './RekeyOrchestrator.js'
 
 /**
  * Manages entity snapshots — core CRUD for immutable entity data.
@@ -12,7 +13,7 @@ import {
  * Follows the same sub-store pattern as ErrorStore, RelationStore, etc.
  * SnapshotStore delegates entity snapshot operations here.
  */
-export class EntitySnapshotStore {
+export class EntitySnapshotStore implements Rekeyable {
 	private readonly snapshots = new Map<string, EntitySnapshot>()
 
 	/**
@@ -23,6 +24,67 @@ export class EntitySnapshotStore {
 	 */
 	private readonly idIndex = new Map<string, string>()
 
+	/**
+	 * Monotonic counter bumped only when the set of keys or the id→key index
+	 * changes (new key, removal, rekey, bulk import, clear). Pure value edits
+	 * (setFieldValue/updateFields/commit/reset/...) do NOT bump it — they cannot
+	 * change reachability — so the per-keystroke edit path keeps the
+	 * {@link ReachabilityAnalyzer} cache warm.
+	 */
+	private mutationVersion = 0
+
+	/**
+	 * Monotonic counter bumped on every EDITABLE-layer snapshot write (local
+	 * setData / updateFields / setFieldValue / reset) — the writes an undo gesture
+	 * must first record. Server-baseline writes (server setData, refreshServerData,
+	 * commit, commitFields) and non-write bookkeeping (remove, bumpVersion, import,
+	 * rekey, clear) deliberately do NOT bump it. Read by the undo write-guard to
+	 * detect a mutating path that wrote without recording. See UndoJournal.
+	 */
+	private editableWriteVersion = 0
+
+	/**
+	 * Monotonic counter bumped on every write that can change a snapshot's `data`
+	 * or `serverData` — i.e. every write that can change whether the entity is
+	 * dirty. Unlike the two counters above it spans BOTH layers: `mutationVersion`
+	 * ignores value edits and `editableWriteVersion` ignores server-baseline writes
+	 * (refreshServerData/commit/commitFields), so neither alone is a sound dirty
+	 * key. {@link bumpVersion} is excluded — it rewrites neither side. Read by
+	 * SnapshotStore.getDirtyVersion() to memoize the full-store dirty scan.
+	 */
+	private dataWriteVersion = 0
+
+	getMutationVersion(): number {
+		return this.mutationVersion
+	}
+
+	getEditableWriteVersion(): number {
+		return this.editableWriteVersion
+	}
+
+	getDataWriteVersion(): number {
+		return this.dataWriteVersion
+	}
+
+	/**
+	 * The single write chokepoint. Every path that installs a snapshot goes through
+	 * here, so {@link dataWriteVersion} cannot be forgotten by a new mutating method
+	 * or a new early-return branch — a stale dirty memo is silent (dead Save button),
+	 * so the bump must not be hand-maintained per call site. Mirrors
+	 * HasOneStore.writeRelation / HasManyStore.writeHasMany.
+	 */
+	private writeSnapshot(key: string, snapshot: EntitySnapshot): void {
+		this.snapshots.set(key, snapshot)
+		this.dataWriteVersion++
+	}
+
+	/** The single delete chokepoint — counterpart of {@link writeSnapshot}. */
+	private deleteSnapshot(key: string): void {
+		if (this.snapshots.delete(key)) {
+			this.dataWriteVersion++
+		}
+	}
+
 	get(key: string): EntitySnapshot | undefined {
 		return this.snapshots.get(key)
 	}
@@ -60,8 +122,13 @@ export class EntitySnapshotStore {
 			(existing?.version ?? 0) + 1,
 		)
 
-		this.snapshots.set(key, newSnapshot)
+		this.writeSnapshot(key, newSnapshot)
+		// The id index resolves relation edges for reachability, which memoizes on
+		// mutationVersion — so any change to the index must move it, not just a new key.
+		const indexChanged = this.idIndex.get(id) !== key
 		this.idIndex.set(id, key)
+		if (!existing || indexChanged) this.mutationVersion++
+		if (!isServerData) this.editableWriteVersion++
 		return newSnapshot
 	}
 
@@ -111,7 +178,7 @@ export class EntitySnapshotStore {
 			existing.version + 1,
 		)
 
-		this.snapshots.set(key, newSnapshot)
+		this.writeSnapshot(key, newSnapshot)
 		return newSnapshot
 	}
 
@@ -135,7 +202,8 @@ export class EntitySnapshotStore {
 			existing.version + 1,
 		)
 
-		this.snapshots.set(key, newSnapshot)
+		this.writeSnapshot(key, newSnapshot)
+		this.editableWriteVersion++
 		return newSnapshot
 	}
 
@@ -156,7 +224,8 @@ export class EntitySnapshotStore {
 			existing.version + 1,
 		)
 
-		this.snapshots.set(key, newSnapshot)
+		this.writeSnapshot(key, newSnapshot)
+		this.editableWriteVersion++
 		return true
 	}
 
@@ -175,7 +244,7 @@ export class EntitySnapshotStore {
 			existing.version + 1,
 		)
 
-		this.snapshots.set(key, newSnapshot)
+		this.writeSnapshot(key, newSnapshot)
 	}
 
 	/**
@@ -193,7 +262,8 @@ export class EntitySnapshotStore {
 			existing.version + 1,
 		)
 
-		this.snapshots.set(key, newSnapshot)
+		this.writeSnapshot(key, newSnapshot)
+		this.editableWriteVersion++
 	}
 
 	/**
@@ -208,13 +278,19 @@ export class EntitySnapshotStore {
 		// that survivor as id-unresolvable.
 		if (existing && this.idIndex.get(existing.id) === key) {
 			this.idIndex.delete(existing.id)
+			this.mutationVersion++
 		}
-		this.snapshots.delete(key)
+		this.deleteSnapshot(key)
 	}
 
 	/**
 	 * Bumps the version of an entity snapshot without changing data.
 	 * Used by SubscriptionManager when child entities change.
+	 *
+	 * The ONE deliberate bypass of {@link writeSnapshot}: it reinstalls the very same
+	 * `data` and `serverData` references under a new version, so it cannot change
+	 * dirtiness and must not invalidate the dirty memo — it runs once per ancestor on
+	 * every notification, which would keep the cache permanently cold.
 	 */
 	bumpVersion(key: string): void {
 		const existing = this.snapshots.get(key)
@@ -256,7 +332,7 @@ export class EntitySnapshotStore {
 			existing.version + 1,
 		)
 
-		this.snapshots.set(key, newSnapshot)
+		this.writeSnapshot(key, newSnapshot)
 	}
 
 	/**
@@ -280,36 +356,39 @@ export class EntitySnapshotStore {
 	importSnapshots(snapshots: Map<string, EntitySnapshot>): Set<string> {
 		const keys = new Set<string>()
 		for (const [key, snapshot] of snapshots) {
-			this.snapshots.set(key, snapshot)
+			this.writeSnapshot(key, snapshot)
 			this.idIndex.set(snapshot.id, key)
 			keys.add(key)
 		}
+		if (keys.size > 0) this.mutationVersion++
 		return keys
 	}
 
 	/**
-	 * Moves a snapshot from oldKey to newKey, updating the id in the snapshot data.
+	 * Moves a snapshot from the temp key to the persisted key, updating the id in
+	 * the snapshot data.
 	 */
-	rekey(oldKey: string, newKey: string, newId: string): void {
-		const snapshot = this.snapshots.get(oldKey)
+	rekey(ctx: RekeyContext): void {
+		const snapshot = this.snapshots.get(ctx.oldKey)
 		if (!snapshot) return
 
 		// Update id field in data and serverData
-		const data = { ...snapshot.data as Record<string, unknown>, id: newId }
-		const serverData = { ...snapshot.serverData as Record<string, unknown>, id: newId }
+		const data = { ...snapshot.data as Record<string, unknown>, id: ctx.newId }
+		const serverData = { ...snapshot.serverData as Record<string, unknown>, id: ctx.newId }
 
 		const newSnapshot = createEntitySnapshot(
-			newId,
+			ctx.newId,
 			snapshot.entityType,
 			data,
 			serverData,
 			snapshot.version + 1,
 		)
 
-		this.snapshots.delete(oldKey)
-		this.snapshots.set(newKey, newSnapshot)
+		this.deleteSnapshot(ctx.oldKey)
+		this.writeSnapshot(ctx.newKey, newSnapshot)
 		this.idIndex.delete(snapshot.id)
-		this.idIndex.set(newId, newKey)
+		this.idIndex.set(ctx.newId, ctx.newKey)
+		this.mutationVersion++
 	}
 
 	keys(): IterableIterator<string> {
@@ -327,8 +406,12 @@ export class EntitySnapshotStore {
 	}
 
 	clear(): void {
+		// Bulk drop: bumps both counters inline rather than per key, the same shape as
+		// HasOneStore.clear / HasManyStore.clear.
 		this.snapshots.clear()
 		this.idIndex.clear()
+		this.mutationVersion++
+		this.dataWriteVersion++
 	}
 }