fix(review): Apply sees the file under every spelling and rechecks only its choice

Apply now finds the legacy rows of the same physical file however its root
is reached. The roots are real paths while the monitor links under the
directory it watches, so a symlinked or junctioned root, subst or a mapped
drive used to hide the monitor's row and Apply added a second, differently
linked row. Same-name rows are resolved to their physical identity
(normcase(realpath), else samefile); the dependency fingerprint covers all
of them, two rows refuse the choice, one row is enriched under the
ingester's compatible-only rules, and a same-name row the request did not
classify is a changed association.

Apply re-verifies only what the decision depends on: the bytes are still
ambiguous and still offer the chosen candidate. A resolver change that
rewords the reason or reorders candidates leaves pending items applicable.
The resolver version is one constant in prompt_pair_resolver, shared by
ingestion provenance and Needs review.

The transaction's byte check receives the re-hashed digest (or the body's
for Leave unresolved), every Apply refusal branch is tested with zero
writes, and the root listing and realpath calls run on a worker thread.

database/pair_ingestion.py

@@ -9,8 +9,10 @@ from .operations import _coerce_file_info
 
 try:
     from ..utils.hashing import generate_prompt_hash
+    from ..utils.prompt_pair_resolver import RESOLVER_VERSION
 except ImportError:
     from utils.hashing import generate_prompt_hash
+    from utils.prompt_pair_resolver import RESOLVER_VERSION
 
 
 def ingest_resolved_pair(
@@ -51,7 +53,7 @@ def _ingest_resolved_pair_in(
     normalized = normalize_image_path(image_path)
     if provenance is None:
         provenance = {
-            "resolver_version": 1,
+            "resolver_version": RESOLVER_VERSION,
             "positive": positive,
             "negative": negative,
         }

database/review.py

@@ -117,7 +117,7 @@ _DETAIL = (
 )
 # The legacy rows and pair links the ingester's compatibility rules read.
 _DEPENDENT_IMAGES = (
-    "SELECT gi.id,p.hash FROM generated_images gi "
+    "SELECT gi.id,p.hash,gi.image_path FROM generated_images gi "
     "JOIN prompts p ON p.id=gi.prompt_id "
     "WHERE gi.file_path=? OR gi.image_path=? ORDER BY gi.id"
 )
@@ -127,6 +127,12 @@ _DEPENDENT_LINKS = (
     "LEFT JOIN prompts n ON n.id=pp.negative_prompt_id "
     "WHERE ip.image_id=? ORDER BY ip.pair_id"
 )
+# Rows whose spelling ends with the file's name: the candidates for another
+# spelling of the same physical file (the link summaries' filename fallback).
+_SAME_NAME_ROWS = (
+    "SELECT id,image_path FROM generated_images "
+    "WHERE image_path LIKE ? ESCAPE '\\' ORDER BY id"
+)
 _TITLES = (
     "SELECT p.hash,s.title FROM prompts p "
     "JOIN prompt_library_state s ON s.prompt_id=p.id "
@@ -159,18 +165,47 @@ def _validate_spelling(spelled_path: object, locator: str) -> None:
         raise ValueError("spelled_path must be the file's spelling of its locator")
 
 
-def dependency_fingerprint(conn: sqlite3.Connection, image_path: str) -> str:
+def dependent_images(conn: sqlite3.Connection, spellings) -> list:
+    """``(id, image_path, positive_hash)`` of every legacy row of the file.
+
+    ``spellings`` are the paths the file is linked under (the Apply path and
+    every alias of the same physical file); each is matched as the ingester
+    matches one path. Rows are distinct and ordered by id.
+    """
+    found = {}
+    for spelled in dict.fromkeys(spellings):
+        for row in conn.execute(
+            _DEPENDENT_IMAGES, (normalize_image_path(spelled), spelled)
+        ):
+            found[row[0]] = (row[0], row[2], row[1])
+    return [found[key] for key in sorted(found)]
+
+
+def same_name_rows(conn: sqlite3.Connection, name: str) -> list:
+    """``(id, image_path)`` of rows whose spelling may end with ``name``."""
+    # Imported here: operations composes this module's mixin.
+    from .operations import escape_like
+
+    return [
+        (row[0], row[1])
+        for row in conn.execute(_SAME_NAME_ROWS, (f"%{escape_like(name)}",))
+    ]
+
+
+def dependency_fingerprint(
+    conn: sqlite3.Connection, image_path: str, aliases=()
+) -> str:
     """SHA-256 of what Apply's compatibility depends on for ``image_path``.
 
-    The exact legacy rows of the file with their positive hashes, and each
-    row's pair links with the negative hash, read as the ingester reads them.
-    Unrelated prompt changes (tags, titles) do not move it.
+    The exact legacy rows of the file under ``image_path`` and every alias
+    spelling of it, with their positive hashes, and each row's pair links
+    with the negative hash, read as the ingester reads them. Unrelated prompt
+    changes (tags, titles) do not move it.
     """
-    images = conn.execute(
-        _DEPENDENT_IMAGES, (normalize_image_path(image_path), image_path)
-    ).fetchall()
     rows = []
-    for image_id, positive_hash in images:
+    for image_id, _spelled, positive_hash in dependent_images(
+        conn, (image_path, *aliases)
+    ):
         links = conn.execute(_DEPENDENT_LINKS, (image_id,)).fetchall()
         rows.append([image_id, positive_hash, [list(link) for link in links]])
     text = canonical_evidence({"v": 1, "images": rows})
@@ -328,9 +363,14 @@ class ReviewOperations:
             item["total"] = conn.execute(_PENDING_COUNT).fetchone()[0]
         return item
 
-    def review_dependency_fingerprint(self, image_path: str) -> str:
+    def review_dependency_fingerprint(self, image_path: str, aliases=()) -> str:
         with self._annotation_read() as conn:
-            return dependency_fingerprint(conn, image_path)
+            return dependency_fingerprint(conn, image_path, aliases)
+
+    def review_same_name_rows(self, name: str) -> list:
+        """``(id, image_path)`` of legacy rows that may spell a file ``name``."""
+        with self._annotation_read() as conn:
+            return same_name_rows(conn, name)
 
     def stored_prompt_titles(self, texts) -> dict:
         """Library titles of saved prompts by text (dedup hash), when set."""

database/review_decisions.py

@@ -12,6 +12,7 @@ Callers verify the file first (the capture must be the item's bytes and the
 current file must still hash to them); nothing here reads the filesystem.
 """
 
+import os
 import sqlite3
 
 from .annotation_schema import BYTES_TABLE
@@ -25,6 +26,8 @@ from .review import (
     _PENDING_COUNT,
     _queue_row,
     dependency_fingerprint,
+    dependent_images,
+    same_name_rows,
 )
 from .review_schema import DECISIONS_TABLE, ITEMS_TABLE, canonical_evidence
 
@@ -65,6 +68,8 @@ class ReviewCommandError(LibraryCommandError):
         self.total = total
         self.fingerprint = fingerprint
         self.changed = changed
+        # The public view of ``item``, set by the API when it formats one.
+        self.view = None
 
 
 class _Rollback(Exception):
@@ -90,12 +95,18 @@ class ReviewDecisionOperations:
         image_path: str | None = None,
         metadata: dict | None = None,
         expected_fingerprint: str | None = None,
+        aliases: tuple = (),
+        known_rows: frozenset | None = None,
     ) -> dict:
         """Record the decision; return ``{item, total, pair}``.
 
         ``selected`` needs the evidence ``candidate`` (with its ``hash``), the
         ``image_path`` the scan and the monitor link under, the captured
         ``metadata`` and the ``expected_fingerprint`` the reviewer saw.
+        ``aliases`` are the other spellings legacy rows of the same physical
+        file use (a symlinked, junctioned or mapped root) and ``known_rows``
+        the ids of every same-name row the caller classified; a same-name row
+        it did not see is a changed association.
         Raises ``LibraryCommandError("storage-changed")`` after a restore and
         :class:`ReviewCommandError` for every refused decision, with zero
         writes either way.
@@ -119,6 +130,8 @@ class ReviewDecisionOperations:
                     image_path=image_path,
                     metadata=metadata or {},
                     expected_fingerprint=expected_fingerprint,
+                    aliases=tuple(aliases),
+                    known_rows=known_rows,
                 )
         except _Rollback as rollback:
             raise rollback.error from None
@@ -191,8 +204,14 @@ class ReviewDecisionOperations:
         from .pair_ingestion import _ingest_resolved_pair_in
 
         image_path = command["image_path"]
-        fingerprint = dependency_fingerprint(conn, image_path)
-        if fingerprint != command["expected_fingerprint"]:
+        aliases = command["aliases"]
+        fingerprint = dependency_fingerprint(conn, image_path, aliases)
+        known = command["known_rows"]
+        unseen = known is not None and any(
+            row_id not in known
+            for row_id, _path in same_name_rows(conn, os.path.basename(image_path))
+        )
+        if unseen or fingerprint != command["expected_fingerprint"]:
             raise _Rollback(
                 ReviewCommandError(
                     "association-conflict",
@@ -203,6 +222,22 @@ class ReviewDecisionOperations:
                     changed=True,
                 )
             )
+        rows = dependent_images(conn, (image_path, *aliases))
+        if len(rows) > 1:
+            # One file linked under several spellings: no single row to enrich.
+            raise _Rollback(
+                ReviewCommandError(
+                    "association-conflict",
+                    epoch,
+                    item=current,
+                    total=total,
+                    fingerprint=fingerprint,
+                )
+            )
+        if rows:
+            # Enrich the one row of this file under the spelling it was
+            # linked with, so the ingester's compatibility rules see it.
+            image_path = rows[0][1]
         candidate = command["candidate"]
         positive, negative = candidate["positive"], candidate["negative"]
         provenance = {