Batch absent/deleted subject removal in the Neo4j projection

Follow-up to #1080.

- removeAbsentSubjects and deletePage now route through a single
  removeSubjects() that classifies referenced-vs-unreferenced subjects
  in one query and deletes the unreferenced ones in one query, instead
  of one round trip per subject. Both call sites stay unified on the
  same stub/delete logic.
- subjectIdsWithIncomingRelations excludes self-loops, so a subject
  whose only incoming relation is its own self-reference is deleted
  rather than left as an unreachable orphan stub.
- reduceSubjectToStub collapses the OPTIONAL MATCH cartesian product
  with WITH DISTINCT so the property reset runs once, not once per
  outgoing relation.
- getSubjectIdsByPageId no longer fetches the node properties and
  labels that both callers discard.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: alistair3149

src/GraphDatabasePlugins/Neo4j/Persistence/Neo4jProjectionStore.php

@@ -70,17 +70,18 @@ private function upsertPageNode( TransactionInterface $transaction, Page $page )
 
 	/**
 	 * Removes the subjects that are attached to the page in the graph but are no longer present on the
-	 * page. This reuses deleteSubject so that a removed subject still referenced by other subjects is
+	 * page. This reuses removeSubjects so that a removed subject still referenced by other subjects is
 	 * kept as a stub instead of being deleted, keeping the incoming relations valid.
 	 */
 	private function removeAbsentSubjects( TransactionInterface $transaction, Page $page ): void {
 		$presentSubjectIds = $page->getSubjects()->getAllSubjects()->getIdsAsTextArray();
 
-		foreach ( $this->getSubjectIdsByPageId( $transaction, $page->getId() ) as $attachedSubjectId ) {
-			if ( !in_array( $attachedSubjectId, $presentSubjectIds, true ) ) {
-				$this->deleteSubject( $transaction, new SubjectId( $attachedSubjectId ) );
-			}
-		}
+		$absentSubjectIds = array_values( array_filter(
+			$this->getSubjectIdsByPageId( $transaction, $page->getId() ),
+			fn( string $subjectId ) => !in_array( $subjectId, $presentSubjectIds, true )
+		) );
+
+		$this->removeSubjects( $transaction, $absentSubjectIds );
 	}
 
 	private function detachSubjectsFromPage( TransactionInterface $transaction, PageId $pageId ): void {
@@ -153,9 +154,7 @@ private function updateSubjects( TransactionInterface $transaction, Page $page )
 
 	public function deletePage( PageId $pageId ): void {
 		$this->client->writeTransaction( function ( TransactionInterface $transaction ) use ( $pageId ): void {
-			foreach ( $this->getSubjectIdsByPageId( $transaction, $pageId ) as $subjectId ) {
-				$this->deleteSubject( $transaction, new SubjectId( $subjectId ) );
-			}
+			$this->removeSubjects( $transaction, $this->getSubjectIdsByPageId( $transaction, $pageId ) );
 
 			$this->deletePageNode( $transaction, $pageId );
 		} );
@@ -178,7 +177,7 @@ private function getSubjectIdsByPageId( TransactionInterface $transaction, PageI
 		 */
 		$results = $transaction->run(
 			'MATCH (page:Page {id: $pageId, wiki_id: $wikiId})-[:HasSubject]->(subject:Subject)
-				RETURN subject.id AS id, subject AS properties, labels(subject) AS labels',
+				RETURN subject.id AS id',
 			[ 'pageId' => $pageId->id, 'wikiId' => $this->wikiId ]
 		);
 
@@ -188,17 +187,68 @@ private function getSubjectIdsByPageId( TransactionInterface $transaction, PageI
 		);
 	}
 
-	private function deleteSubject( TransactionInterface $transaction, SubjectId $subjectId ): void {
-		if ( $this->subjectHasIncomingRelations( $transaction, $subjectId ) ) {
-			$this->reduceSubjectToStub( $transaction, $subjectId );
+	/**
+	 * Removes the given subjects from the graph. A subject still referenced by an incoming relation from
+	 * another subject is reduced to a stub so that reference stays valid; the rest are deleted outright.
+	 *
+	 * The referenced/unreferenced split is computed with a single query and the unreferenced subjects are
+	 * deleted with a single query, rather than one round trip per subject.
+	 *
+	 * @param string[] $subjectIds
+	 */
+	private function removeSubjects( TransactionInterface $transaction, array $subjectIds ): void {
+		if ( $subjectIds === [] ) {
+			return;
 		}
-		else {
-			$transaction->run(
-				'MATCH (subject {id: $subjectId})
-				DETACH DELETE subject',
-				[ 'subjectId' => $subjectId->text ]
-			);
+
+		$referencedSubjectIds = $this->subjectIdsWithIncomingRelations( $transaction, $subjectIds );
+
+		$this->deleteSubjects( $transaction, array_values( array_diff( $subjectIds, $referencedSubjectIds ) ) );
+
+		foreach ( $referencedSubjectIds as $subjectId ) {
+			$this->reduceSubjectToStub( $transaction, new SubjectId( $subjectId ) );
+		}
+	}
+
+	/**
+	 * Returns the subset of the given subject ids that still have an incoming relation from a *different*
+	 * subject. HasSubject relations do not count, and neither does a self-loop: a subject whose only
+	 * incoming relation is its own outgoing self-reference has no external referrer, so it is deleted
+	 * rather than kept as an unreachable stub.
+	 *
+	 * @param string[] $subjectIds
+	 * @return string[]
+	 */
+	private function subjectIdsWithIncomingRelations( TransactionInterface $transaction, array $subjectIds ): array {
+		/**
+		 * @var SummarizedResult $result
+		 */
+		$result = $transaction->run(
+			'UNWIND $subjectIds AS subjectId
+				MATCH (subject {id: subjectId})<-[incomingRelation]-(other)
+				WHERE NOT incomingRelation:HasSubject AND other <> subject
+				RETURN DISTINCT subject.id AS id',
+			[ 'subjectIds' => $subjectIds ]
+		);
+
+		return array_map(
+			fn( $record ) => $record->get( 'id' ),
+			$result->toArray()
+		);
+	}
+
+	/**
+	 * @param string[] $subjectIds
+	 */
+	private function deleteSubjects( TransactionInterface $transaction, array $subjectIds ): void {
+		if ( $subjectIds === [] ) {
+			return;
 		}
+
+		$transaction->run(
+			'MATCH (subject) WHERE subject.id IN $subjectIds DETACH DELETE subject',
+			[ 'subjectIds' => $subjectIds ]
+		);
 	}
 
 	/**
@@ -213,6 +263,7 @@ private function reduceSubjectToStub( TransactionInterface $transaction, Subject
 				OPTIONAL MATCH ()-[hasSubject:HasSubject]->(subject)
 				OPTIONAL MATCH (subject)-[outgoingRelation]->()
 				DELETE hasSubject, outgoingRelation
+				WITH DISTINCT subject
 				SET subject = {id: $subjectId, wiki_id: $wikiId}
 				SET subject:Subject',
 			[ 'subjectId' => $subjectId->text, 'wikiId' => $this->wikiId ]
@@ -229,13 +280,4 @@ private function removeNonStubLabels( TransactionInterface $transaction, Subject
 		);
 	}
 
-	private function subjectHasIncomingRelations( TransactionInterface $transaction, SubjectId $subjectId ): bool {
-		return $transaction->run(
-			'MATCH (subject {id: $subjectId})<-[incomingRelation]-()
-			WHERE NOT incomingRelation:HasSubject
-			RETURN incomingRelation',
-			[ 'subjectId' => $subjectId->text ]
-		)->isEmpty() === false;
-	}
-
 }