@contember/bindx 0.1.42 → 0.1.44

package/src/handles/HasManyListHandle.ts

@@ -340,7 +340,6 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 	 * Connects an existing entity to this has-many relation.
 	 */
 	connect(itemId: string): void {
-		this.assertNotDisposed()
 		this.dispatcher.dispatch(
 			connectToList(this.entityType, this.entityId, this.fieldName, itemId, this.itemType, this.alias),
 		)
@@ -352,7 +351,6 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 	 * For created entities (via add()), cancels the add operation.
 	 */
 	disconnect(itemId: string): void {
-		this.assertNotDisposed()
 		this.dispatcher.dispatch(
 			removeFromList(this.entityType, this.entityId, this.fieldName, itemId, 'disconnect', this.alias),
 		)
@@ -364,7 +362,6 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 	 * For created entities (via add()), cancels the add operation.
 	 */
 	delete(itemId: string): void {
-		this.assertNotDisposed()
 		this.dispatcher.dispatch(
 			removeFromList(this.entityType, this.entityId, this.fieldName, itemId, 'delete', this.alias),
 		)
@@ -376,7 +373,6 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 	 * For connecting existing entities, use connect() instead.
 	 */
 	add(data?: Partial<TEntity>): string {
-		this.assertNotDisposed()
 
 		// Pre-create entity so we can return tempId
 		const tempId = this.store.createEntity(this.itemType, data as Record<string, unknown>)
@@ -399,7 +395,6 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 	 * Falls back to disconnect when schema metadata is not available.
 	 */
 	remove(itemId: string): void {
-		this.assertNotDisposed()
 		this.dispatcher.dispatch(
 			removeFromList(this.entityType, this.entityId, this.fieldName, itemId, this.resolveRemovalType(), this.alias),
 		)
@@ -430,7 +425,6 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 	 * use an 'order' field on the entity.
 	 */
 	move(fromIndex: number, toIndex: number): void {
-		this.assertNotDisposed()
 		this.dispatcher.dispatch(
 			moveInList(this.entityType, this.entityId, this.fieldName, fromIndex, toIndex, this.alias),
 		)
@@ -441,7 +435,6 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 	 * Clears all planned connections and removals.
 	 */
 	reset(): void {
-		this.assertNotDisposed()
 		this.store.resetHasMany(
 			this.entityType,
 			this.entityId,
@@ -450,19 +443,6 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 		)
 	}
 
-	/**
-	 * Disposes the handle.
-	 */
-	override dispose(): void {
-		super.dispose()
-
-		for (const handle of this.itemHandleCacheRaw.values()) {
-			handle.dispose()
-		}
-		this.itemHandleCacheRaw.clear()
-		this.itemHandleCacheProxy.clear()
-	}
-
 	/**
 	 * Type brand - ensures HasManyRef<Author> is not assignable to HasManyRef<Tag>.
 	 * This is a phantom property that only exists in the type system.
@@ -489,7 +469,6 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 	 * Adds a client-side error to this relation.
 	 */
 	addError(error: ErrorInput): void {
-		this.assertNotDisposed()
 		this.dispatcher.dispatch(
 			addRelationError(this.entityType, this.entityId, this.fieldName, createClientError(error)),
 		)
@@ -499,7 +478,6 @@ export class HasManyListHandle<TEntity extends object = object, TSelected = TEnt
 	 * Clears all errors from this relation.
 	 */
 	clearErrors(): void {
-		this.assertNotDisposed()
 		this.dispatcher.dispatch(
 			clearRelationErrors(this.entityType, this.entityId, this.fieldName),
 		)

package/src/handles/HasOneHandle.ts

@@ -374,7 +374,6 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 	 * Accessible via proxy as `$create()`.
 	 */
 	create(data?: Partial<TEntity>): string {
-		this.assertNotDisposed()
 		const tempId = this.store.createEntity(this.targetType, data as Record<string, unknown>)
 		this.dispatcher.dispatch(
 			connectRelation(this.entityType, this.entityId, this.fieldName, tempId, this.targetType),
@@ -386,7 +385,6 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 	 * Connects the relation to an entity.
 	 */
 	connect(targetId: string): void {
-		this.assertNotDisposed()
 		this.dispatcher.dispatch(
 			connectRelation(this.entityType, this.entityId, this.fieldName, targetId, this.targetType),
 		)
@@ -397,7 +395,6 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 	 * Sets the FK to null — only works when the FK column is nullable.
 	 */
 	disconnect(): void {
-		this.assertNotDisposed()
 		this.dispatcher.dispatch(
 			disconnectRelation(this.entityType, this.entityId, this.fieldName),
 		)
@@ -407,7 +404,6 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 	 * Marks the related entity for deletion.
 	 */
 	delete(): void {
-		this.assertNotDisposed()
 		this.dispatcher.dispatch(
 			deleteRelation(this.entityType, this.entityId, this.fieldName),
 		)
@@ -432,22 +428,9 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 	 * Resets the relation to server state.
 	 */
 	reset(): void {
-		this.assertNotDisposed()
 		this.store.resetRelation(this.entityType, this.entityId, this.fieldName)
 	}
 
-	/**
-	 * Disposes the handle.
-	 */
-	override dispose(): void {
-		super.dispose()
-		this.entityHandleCacheRaw?.dispose()
-		this.entityHandleCacheRaw = null
-		this.entityHandleCacheProxy = null
-		this.placeholderCacheRaw = null
-		this.placeholderCacheProxy = null
-	}
-
 	/**
 	 * Type brand - ensures HasOneRef<Author> is not assignable to HasOneRef<Tag>.
 	 * This is a phantom property that only exists in the type system.
@@ -474,7 +457,6 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 	 * Adds a client-side error to this relation.
 	 */
 	addError(error: ErrorInput): void {
-		this.assertNotDisposed()
 		this.dispatcher.dispatch(
 			addRelationError(this.entityType, this.entityId, this.fieldName, createClientError(error)),
 		)
@@ -484,7 +466,6 @@ export class HasOneHandle<TEntity extends object = object, TSelected = TEntity>
 	 * Clears all errors from this relation.
 	 */
 	clearErrors(): void {
-		this.assertNotDisposed()
 		this.dispatcher.dispatch(
 			clearRelationErrors(this.entityType, this.entityId, this.fieldName),
 		)

package/src/handles/PlaceholderHandle.ts

@@ -187,6 +187,9 @@ export class PlaceholderHandle<TEntity extends object = object, TSelected = TEnt
 	 * Creates a field handle for placeholder data.
 	 * For has-many relations, returns a real (empty) has-many handle bound to this
 	 * placeholder entity, so it behaves identically to a connected one.
+	 * For has-one relations, returns a nested placeholder has-one handle so chains like
+	 * `<HasOne field={parentPlaceholder.profile}>` materialize an inner placeholder
+	 * rather than handing `undefined` to the children callback.
 	 */
 	private createPlaceholderFieldHandle(fieldName: string): unknown {
 		// For has-many relations, return a real HasManyListHandle bound to this placeholder's
@@ -227,6 +230,14 @@ export class PlaceholderHandle<TEntity extends object = object, TSelected = TEnt
 			})
 		}
 
+		// For has-one relations, return a placeholder-of-placeholder has-one handle
+		if (this.schema?.isHasOne(this.targetType, fieldName)) {
+			const innerTargetType = this.schema.getRelationTarget(this.targetType, fieldName)
+			if (innerTargetType) {
+				return this.createPlaceholderHasOneFieldHandle(fieldName, innerTargetType)
+			}
+		}
+
 		const self = this
 
 		return {
@@ -320,6 +331,88 @@ export class PlaceholderHandle<TEntity extends object = object, TSelected = TEnt
 		}
 	}
 
+	/**
+	 * Creates a nested placeholder has-one handle.
+	 *
+	 * Used when a placeholder entity (the outer placeholder) is asked for one of its
+	 * has-one relations — there is no real parent row, so the inner relation is also
+	 * a placeholder. The returned handle exposes the HasOne-shaped surface that
+	 * `<HasOne>` JSX relies on (FIELD_REF_META, $entity, $state) plus field-access
+	 * proxying so chains like `parentPlaceholder.profile.bio.value` resolve to `null`
+	 * instead of throwing.
+	 *
+	 * Mutations (`$connect`, `$create`) are not supported on nested placeholders —
+	 * materialize the outer placeholder first (e.g. by writing to a scalar field or
+	 * connecting the outer relation).
+	 */
+	private createPlaceholderHasOneFieldHandle(fieldName: string, innerTargetType: string): unknown {
+		const self = this
+		const nestedPlaceholderRaw = PlaceholderHandle.createRaw(
+			this.targetType,
+			this.placeholderId,
+			fieldName,
+			innerTargetType,
+			this.store,
+			this.dispatcher,
+			this.schema,
+			this.__brands,
+		)
+		const nestedPlaceholderProxy = PlaceholderHandle.wrapProxy(nestedPlaceholderRaw)
+		const fieldRefMeta: FieldRefMeta = {
+			entityType: self.targetType,
+			entityId: self.placeholderId,
+			path: [fieldName],
+			fieldName,
+			isArray: false,
+			isRelation: true,
+			targetType: innerTargetType,
+		}
+		const noopUnsubscribe: Unsubscribe = () => {}
+
+		const handleLike = {
+			get [FIELD_REF_META](): FieldRefMeta { return fieldRefMeta },
+			get id(): string { return nestedPlaceholderRaw.id },
+			get state(): 'disconnected' { return 'disconnected' },
+			get isConnected(): boolean { return false },
+			get isNew(): boolean { return true },
+			get isPersisting(): boolean { return false },
+			get isDirty(): boolean { return false },
+			get persistedId(): null { return null },
+			get data(): null { return null },
+			get entity(): EntityAccessor<object> { return nestedPlaceholderProxy },
+			get fields() { return nestedPlaceholderRaw.fields },
+			get errors(): readonly FieldError[] { return [] },
+			get hasError(): boolean { return false },
+			get __entityName(): string { return innerTargetType },
+			get __entityType(): unknown { return undefined },
+			get __brands(): Set<symbol> | undefined { return self.__brands },
+			create(): string {
+				throw new Error(`Cannot $create on nested placeholder has-one "${fieldName}" — materialize the outer placeholder first`)
+			},
+			connect(): void {
+				throw new Error(`Cannot $connect on nested placeholder has-one "${fieldName}" — materialize the outer placeholder first`)
+			},
+			disconnect(): void {},
+			delete(): void {},
+			remove(): void {},
+			reset(): void {},
+			addError(_error: ErrorInput): void {},
+			clearErrors(): void {},
+			clearAllErrors(): void {},
+			onConnect(_listener: EventListener<EventTypeMap['relation:connected']>): Unsubscribe { return noopUnsubscribe },
+			onDisconnect(_listener: EventListener<EventTypeMap['relation:disconnected']>): Unsubscribe { return noopUnsubscribe },
+			interceptConnect(_interceptor: Interceptor<EventTypeMap['relation:connecting']>): Unsubscribe { return noopUnsubscribe },
+			interceptDisconnect(_interceptor: Interceptor<EventTypeMap['relation:disconnecting']>): Unsubscribe { return noopUnsubscribe },
+			on<E extends AfterEventTypes>(_eventType: E, _listener: EventListener<EventTypeMap[E]>): Unsubscribe { return noopUnsubscribe },
+			intercept<E extends BeforeEventTypes>(_eventType: E, _interceptor: Interceptor<EventTypeMap[E]>): Unsubscribe { return noopUnsubscribe },
+			onPersisted(_listener: EventListener<EntityPersistedEvent>): Unsubscribe { return noopUnsubscribe },
+			interceptPersisting(_interceptor: Interceptor<EntityPersistingEvent>): Unsubscribe { return noopUnsubscribe },
+			subscribe(_callback: () => void): Unsubscribe { return noopUnsubscribe },
+		}
+
+		return createHandleProxy(handleLike, target => target.fields)
+	}
+
 	/**
 	 * Type brand for EntityRef compatibility.
 	 */

package/src/handles/types.ts

@@ -98,6 +98,16 @@ export interface FieldRefMeta<TEntityName extends string = string> {
 	readonly enumName?: string
 	readonly columnType?: string
 	readonly targetType?: string
+	/**
+	 * Absolute dot-path of segments from the root entity to this field.
+	 * For a top-level field this is `[fieldName]`; for a field reached through
+	 * relations (e.g. `it.author.name`) it is the full chain
+	 * (`['author', 'name']`). `fieldName` / `path` remain the *last* segment
+	 * (relative to the field's own scope) so selection/relation metadata is
+	 * unaffected — consumers that need the full dotted path (DataGrid column
+	 * filter/sort/value extraction) read `fullPath`.
+	 */
+	readonly fullPath?: readonly string[]
 }
 
 export interface InputProps<T> {

package/src/persistence/BatchPersister.ts

@@ -222,6 +222,7 @@ export class BatchPersister {
 			capturedStates = this.captureEntityStates(sortedEntities)
 		}
 
+		let result: PersistenceResult | undefined
 		try {
 			// Build mutations BEFORE resetting state (for pessimistic mode)
 			// The mutations need to contain the dirty data to send to server
@@ -229,13 +230,14 @@ export class BatchPersister {
 
 			if (mutations.length === 0) {
 				// Nothing to persist
-				return {
+				result = {
 					success: true,
 					results: [],
 					successCount: 0,
 					failedCount: 0,
 					skippedCount: 0,
 				}
+				return result
 			}
 
 			// For pessimistic mode, reset entities to server state after capturing
@@ -254,7 +256,8 @@ export class BatchPersister {
 			const transactionResult = await this.executeTransaction(mutations, options?.signal)
 
 			// Process results with captured state for pessimistic mode
-			return this.processTransactionResult(sortedEntities, transactionResult, scope, options, capturedStates)
+			result = this.processTransactionResult(sortedEntities, transactionResult, scope, options, capturedStates)
+			return result
 
 		} finally {
 			// Clear in-flight status
@@ -267,6 +270,14 @@ export class BatchPersister {
 
 			// Unblock undo
 			this.undoManager?.unblock()
+
+			// Reclaim memory: drop snapshots of any created entities orphaned during
+			// editing. Only after a FULLY successful persist — on failure the captured
+			// creates/edits were restored for retry (see processTransactionResult), and
+			// sweeping then could reclaim a create the user still intends to save.
+			if (result?.success) {
+				this.store.sweepUnreachableCreated()
+			}
 		}
 	}
 
@@ -686,7 +697,7 @@ export class BatchPersister {
 							s => s.entityType === entity.entityType && s.entityId === entity.entityId,
 						)
 						if (capturedState) {
-							this.restoreAndCommitEntityState(capturedState)
+							this.restoreEntityState(capturedState, true)
 						}
 					} else {
 						// Commit based on scope
@@ -747,9 +758,10 @@ export class BatchPersister {
 							mutationResult.errorMessage,
 						)
 
-						// Rollback optimistic changes if enabled (and not in pessimistic mode)
-						// In pessimistic mode, we're already at server state, no rollback needed
-						if (rollbackOnError && !isPessimistic) {
+						// Optimistic mode rolls a FAILED entity back to server state only when
+						// rollbackOnError is set. Pessimistic restore is handled below for ALL
+						// captured entities, not just the failed ones.
+						if (!isPessimistic && rollbackOnError) {
 							this.rollbackEntity(entity)
 						}
 					}
@@ -773,6 +785,20 @@ export class BatchPersister {
 					}
 				}
 			}
+
+			// Pessimistic mode: the transaction failed, so from the user's point of view
+			// nothing was committed. Undo the pre-transaction server-view reset for EVERY
+			// captured entity (not only the ones whose individual mutation failed) and keep
+			// the restored data dirty (commit=false) so the user can retry. Restoring even
+			// the entities whose mutation happened to succeed in the non-atomic sequential
+			// fallback is what re-establishes their relation edges to inline-created
+			// children — keeping those creates reachable so the post-persist sweep does not
+			// reclaim a child the user still intends to save (P2).
+			if (isPessimistic && capturedStates) {
+				for (const capturedState of capturedStates) {
+					this.restoreEntityState(capturedState, false)
+				}
+			}
 		}
 
 		return {
@@ -805,46 +831,58 @@ export class BatchPersister {
 	}
 
 	/**
-	 * Restores a captured entity state and commits it.
-	 * Used in pessimistic mode after successful server confirmation.
+	 * Restores a captured entity state (pessimistic mode), optionally committing it.
+	 *
+	 * - commit=true (server confirmed): restore the dirty data and commit it as the
+	 *   new server baseline.
+	 * - commit=false (server rejected): restore the dirty data but leave it dirty, so
+	 *   the user's in-flight edits and creates survive for a retry (P2) instead of
+	 *   being stuck at the server view the pessimistic reset left behind.
 	 */
-	private restoreAndCommitEntityState(capturedState: CapturedEntityState): void {
+	private restoreEntityState(capturedState: CapturedEntityState, commit: boolean): void {
 		if (capturedState.snapshot) {
-			// Restore the entity data from captured snapshot
 			this.store.setEntityData(
 				capturedState.entityType,
 				capturedState.entityId,
 				capturedState.snapshot.data as Record<string, unknown>,
-				true, // Mark as server data since it's now confirmed
+				commit, // server data only when confirmed; otherwise keep it as a dirty edit
 			)
 		}
 
-		// Restore and commit relations
 		for (const [relationKey, relationState] of capturedState.relations) {
 			const fieldName = relationKey.split(':')[2]
 			if (fieldName) {
 				this.store.setRelation(capturedState.entityType, capturedState.entityId, fieldName, {
 					currentId: relationState.currentId,
 					state: relationState.state,
+					// Restore placeholderData too: a has-one in the 'creating' state carries
+					// its inline create payload here, and getDirtyRelations treats a
+					// non-empty placeholderData as a dirty signal. Dropping it on a
+					// commit=false retry would lose the inline data and silently mark the
+					// relation clean. (For commit=true it is cleared by commitRelation below.)
+					placeholderData: relationState.placeholderData,
 				})
-				this.store.commitRelation(capturedState.entityType, capturedState.entityId, fieldName)
+				if (commit) {
+					this.store.commitRelation(capturedState.entityType, capturedState.entityId, fieldName)
+				}
 			}
 		}
 
-		// Restore and commit has-many states
 		for (const [hasManyKey, hasManyState] of capturedState.hasManyStates) {
 			const fieldName = hasManyKey.split(':')[2]
 			if (fieldName) {
 				this.store.restoreHasManyState(capturedState.entityType, capturedState.entityId, fieldName, hasManyState)
-				// Compute new server IDs: serverIds - removals + connections
-				const newServerIds = new Set(hasManyState.serverIds)
-				for (const removedId of hasManyState.plannedRemovals.keys()) {
-					newServerIds.delete(removedId)
-				}
-				for (const connectedId of hasManyState.plannedConnections) {
-					newServerIds.add(connectedId)
+				if (commit) {
+					// Compute new server IDs: serverIds - removals + connections
+					const newServerIds = new Set(hasManyState.serverIds)
+					for (const removedId of hasManyState.plannedRemovals.keys()) {
+						newServerIds.delete(removedId)
+					}
+					for (const connectedId of hasManyState.plannedConnections) {
+						newServerIds.add(connectedId)
+					}
+					this.store.commitHasMany(capturedState.entityType, capturedState.entityId, fieldName, Array.from(newServerIds))
 				}
-				this.store.commitHasMany(capturedState.entityType, capturedState.entityId, fieldName, Array.from(newServerIds))
 			}
 		}
 	}

package/src/store/DirtyTracker.ts

@@ -1,6 +1,7 @@
 import type { EntitySnapshotStore } from './EntitySnapshotStore.js'
 import type { EntityMetaStore } from './EntityMetaStore.js'
 import type { RelationStore } from './RelationStore.js'
+import type { ReachabilityAnalyzer } from './ReachabilityAnalyzer.js'
 import { deepEqual } from '../utils/deepEqual.js'
 
 interface DirtyEntity {
@@ -20,10 +21,15 @@ export class DirtyTracker {
 		private readonly entitySnapshots: EntitySnapshotStore,
 		private readonly meta: EntityMetaStore,
 		private readonly relations: RelationStore,
+		private readonly reachability: ReachabilityAnalyzer,
 	) {}
 
 	getAllDirtyEntities(): DirtyEntity[] {
 		const dirtyEntities: DirtyEntity[] = []
+		// A created entity is a `create` only when reachable from a root through
+		// live relations. A created entity detached from every relation is
+		// unreachable and must not be reported, even if its snapshot still lingers.
+		const reachableCreated = this.reachability.computeReachableCreated()
 
 		for (const key of this.entitySnapshots.keys()) {
 			const [entityType, ...idParts] = key.split(':')
@@ -41,7 +47,9 @@ export class DirtyTracker {
 			}
 
 			if (!this.meta.existsOnServer(entityKey)) {
-				dirtyEntities.push({ entityType, entityId, changeType: 'create' })
+				if (reachableCreated.has(entityKey)) {
+					dirtyEntities.push({ entityType, entityId, changeType: 'create' })
+				}
 				continue
 			}
 

package/src/store/EntityMetaStore.ts

@@ -115,6 +115,16 @@ export class EntityMetaStore {
 		return !this.tempToPersistedId.has(key)
 	}
 
+	/**
+	 * Removes all metadata for an entity (load state, meta, persisting, temp mapping).
+	 */
+	remove(key: string): void {
+		this.loadStates.delete(key)
+		this.entityMetas.delete(key)
+		this.persistingEntities.delete(key)
+		this.tempToPersistedId.delete(key)
+	}
+
 	/**
 	 * Moves all metadata from oldKey to newKey.
 	 */

package/src/store/EntitySnapshotStore.ts

@@ -15,6 +15,14 @@ import {
 export class EntitySnapshotStore {
 	private readonly snapshots = new Map<string, EntitySnapshot>()
 
+	/**
+	 * Index from entity id to its composite key, so reachability walks can resolve
+	 * a relation's child id (which carries no type) to a snapshot in O(1). Ids are
+	 * globally unique (temp ids are minted unique; server ids are UUIDs), so a
+	 * single key per id is unambiguous.
+	 */
+	private readonly idIndex = new Map<string, string>()
+
 	get(key: string): EntitySnapshot | undefined {
 		return this.snapshots.get(key)
 	}
@@ -53,6 +61,7 @@ export class EntitySnapshotStore {
 		)
 
 		this.snapshots.set(key, newSnapshot)
+		this.idIndex.set(id, key)
 		return newSnapshot
 	}
 
@@ -191,6 +200,15 @@ export class EntitySnapshotStore {
 	 * Removes an entity snapshot.
 	 */
 	remove(key: string): void {
+		const existing = this.snapshots.get(key)
+		// Only drop the id→key entry when it still points at THIS key. Ids are
+		// globally unique by construction (server UUIDs / minted temp ids), but if a
+		// caller-supplied id ever collided across types, last-writer-wins means
+		// another snapshot now owns the entry — removing this one must not strand
+		// that survivor as id-unresolvable.
+		if (existing && this.idIndex.get(existing.id) === key) {
+			this.idIndex.delete(existing.id)
+		}
 		this.snapshots.delete(key)
 	}
 
@@ -263,6 +281,7 @@ export class EntitySnapshotStore {
 		const keys = new Set<string>()
 		for (const [key, snapshot] of snapshots) {
 			this.snapshots.set(key, snapshot)
+			this.idIndex.set(snapshot.id, key)
 			keys.add(key)
 		}
 		return keys
@@ -289,14 +308,27 @@ export class EntitySnapshotStore {
 
 		this.snapshots.delete(oldKey)
 		this.snapshots.set(newKey, newSnapshot)
+		this.idIndex.delete(snapshot.id)
+		this.idIndex.set(newId, newKey)
 	}
 
 	keys(): IterableIterator<string> {
 		return this.snapshots.keys()
 	}
 
+	/**
+	 * Resolves an entity id (without its type) to its composite key in O(1).
+	 * Relation state records only child ids, not their types, so this is how a
+	 * reachability walk (and {@link SnapshotStore.isNeverPersisted}) maps a child
+	 * id back to its snapshot. Ids are globally unique, so the mapping is unambiguous.
+	 */
+	keyForId(id: string): string | undefined {
+		return this.idIndex.get(id)
+	}
+
 	clear(): void {
 		this.snapshots.clear()
+		this.idIndex.clear()
 	}
 }
 

package/src/store/ReachabilityAnalyzer.ts

@@ -0,0 +1,92 @@
+import type { EntitySnapshotStore } from './EntitySnapshotStore.js'
+import type { EntityMetaStore } from './EntityMetaStore.js'
+import type { RelationStore } from './RelationStore.js'
+import type { RootRegistry } from './RootRegistry.js'
+
+/**
+ * Computes which never-persisted (created) entities are "live" — i.e. reachable
+ * from a root through live relations.
+ *
+ * This is the single invariant behind create detection: a created entity is a
+ * `create` to be sent to the server iff it is reachable from a root. Roots are
+ * server entities plus explicitly-registered top-level creates (see
+ * {@link RootRegistry}). A created entity that has been detached from every
+ * relation is simply unreachable and produces no mutation — no eager purge of
+ * its snapshot is required for correctness; memory cleanup is a separate
+ * concern handled by a lazy sweep.
+ *
+ * The graph is read from {@link RelationStore} (the source of truth for live
+ * relation membership), never from the subscription parent-child registry,
+ * which is append-mostly for notifications and does not reflect disconnects.
+ */
+export class ReachabilityAnalyzer {
+	constructor(
+		private readonly entitySnapshots: EntitySnapshotStore,
+		private readonly meta: EntityMetaStore,
+		private readonly relations: RelationStore,
+		private readonly roots: RootRegistry,
+	) {}
+
+	/**
+	 * Returns the set of entity keys ("entityType:id") for created
+	 * (never-persisted) entities reachable from a root through live relations.
+	 */
+	computeReachableCreated(): Set<string> {
+		const reachableCreated = new Set<string>()
+		const visited = new Set<string>()
+		const stack: string[] = []
+
+		// Seed roots and, in the same pass, detect whether any never-persisted
+		// (created) snapshot exists at all. Every server entity is a root, and so is
+		// every in-flight (persisting) entity — the latter keeps a created entity
+		// live while it is mid-persist (e.g. pessimistic mode temporarily resets an
+		// update parent to its server view, which would otherwise make a freshly
+		// created child look unreachable during the async transaction window).
+		let hasCreated = false
+		for (const key of this.entitySnapshots.keys()) {
+			const onServer = this.meta.existsOnServer(key)
+			if (!onServer) hasCreated = true
+			if (onServer || this.meta.isPersisting(key)) {
+				stack.push(key)
+			}
+		}
+
+		// Fast path: with no created snapshot anywhere, nothing can be a reachable
+		// create. Skip the O(V·(R+H)) graph walk entirely — the common update-only
+		// form/grid pays only the single existsOnServer scan above (which the seed
+		// loop performs regardless) instead of walking every server entity's edges
+		// on every dirty check (this runs on each store notification, ≈ keystroke).
+		if (!hasCreated) return reachableCreated
+
+		// Seed: explicitly-registered top-level creates (no persisted parent).
+		for (const key of this.roots.keys()) {
+			if (this.entitySnapshots.has(key)) {
+				stack.push(key)
+			}
+		}
+
+		while (stack.length > 0) {
+			const key = stack.pop()!
+			if (visited.has(key)) continue
+			visited.add(key)
+
+			// A created entity reached from a root is a live create. Server roots
+			// are not creates; they fall through to update/delete detection.
+			if (!this.meta.existsOnServer(key)) {
+				reachableCreated.add(key)
+			}
+
+			// Walk through this entity's live child edges. The traversal continues
+			// through created entities too, so a created chain (created child of a
+			// created child of a root) is fully covered.
+			for (const childId of this.relations.getLiveChildIds(`${key}:`)) {
+				const childKey = this.entitySnapshots.keyForId(childId)
+				if (childKey && !visited.has(childKey)) {
+					stack.push(childKey)
+				}
+			}
+		}
+
+		return reachableCreated
+	}
+}