feat(server): progress locator coherence — percentage-only writes clear stale anchors

The verify/heal pipeline verified only INBOUND context-bearing writes;
stored-row coherence was never enforced. SaveProgress seeds missing
fields from the existing row, so every percentage-only write (KOReader
low-confidence conversion, KOReader no-pointer payloads, Kobo markup
ReadingSync / analytics / sync-from-server, locator-less queue entries)
silently re-paired its NEW percentage with the PREVIOUS writer's stale
CFI+context — the incoherent row shape that fed the client-side
far-anchor restore floor (and, via the read-side anchor handles, could
even hand a first-party client the OLD position's scroll address).

KOReader's converter already declared the right intent ("storing
percentage only — the row's percentage restores approximately"); the
seeding betrayed it. SaveProgressRequest gains ClearLocator, set by the
percentage-only call sites, and the seeding rule honors it: stale
epubcfi/context/character_offset clear (the upsert assigns columns
directly, so NULL sticks) unless the request carries its own. A
request-carried context survives so the verify/heal pass can still mint
a fresh anchor from it; the HTTP merge path (field-absent PUTs
preserve) and all anchor-bearing writes are untouched. The fixed-layout
branch already cleared locators unconditionally — unchanged.

Consumer audit: percentage — the only thing every sync round-trip
exchanges — is untouched on all paths; KOReader pulls on locator-less
rows already support the nil-CFI shape (builder guards
progress.Epubcfi.Valid); first-party restores go percentage-first
instead of floor-fighting a stale anchor.

Tests: TestProgressWeb_LocatorCoherence pins clear-on-declared,
request-carried-context survival, and merge-path preservation. Full
suite with the change: 218 groups, zero failures.

internal/sync/progress.go

@@ -291,10 +291,10 @@ func NewProgressService(db *database.Queries, connManager *ConnectionManager) *P
 }
 
 type SaveProgressRequest struct {
-	MediaItemID     pgtype.UUID
-	UserID          pgtype.UUID
-	Source          string
-	DeviceID        pgtype.UUID
+	MediaItemID pgtype.UUID
+	UserID      pgtype.UUID
+	Source      string
+	DeviceID    pgtype.UUID
 
 	Percentage      *float64
 	Epubcfi         *string
@@ -315,6 +315,16 @@ type SaveProgressRequest struct {
 	DeviceType string
 	DeviceName string
 	Broadcast  bool
+
+	// ClearLocator declares that this write INTENDS to carry no position
+	// locator: percentage-only writers (devices whose converter declined,
+	// Kobo markup percentage syncs, queue entries without CFI). Without it,
+	// seeding below would re-pair the new percentage with the PREVIOUS
+	// writer's stale CFI/context — the incoherent row shape that feeds the
+	// client-side far-anchor restore floor. Locater-less rows are honest:
+	// percentage restores are approximate, and the next anchor-bearing
+	// write re-establishes the pair. Request-supplied fields always win.
+	ClearLocator bool
 }
 
 func (s *ProgressService) SaveProgress(ctx context.Context, req SaveProgressRequest) (database.ReadingProgress, error) {
@@ -407,6 +417,22 @@ func (s *ProgressService) SaveProgress(ctx context.Context, req SaveProgressRequ
 		params.ReadingMode = pgtype.Text{String: *req.ReadingMode, Valid: true}
 	}
 
+	// Locator coherence: a write that declares no locator must not
+	// silently re-pair its new percentage with the previous writer's
+	// stale CFI/context (inherited by the seeding above). Clear them so
+	// the row is an honest percentage-only position. Request-carried
+	// fields always win — and a request-carried context survives so the
+	// verify/heal pass below can mint a fresh anchor from it.
+	if req.ClearLocator && req.Epubcfi == nil {
+		params.Epubcfi = pgtype.Text{}
+		if req.ContextText == nil {
+			params.ContextText = pgtype.Text{}
+		}
+		if req.CharacterOffset == nil {
+			params.CharacterOffset = pgtype.Int8{}
+		}
+	}
+
 	params.LastSyncDevice = pgtype.Text{String: req.Source, Valid: true}
 	params.LastSyncSource = pgtype.Text{String: req.Source, Valid: true}
 

internal/sync/queue.go

@@ -126,29 +126,29 @@ func (p *SyncQueueProcessor) EnqueueProgress(update *ProgressUpdate) error {
 }
 
 type HighlightUpdate struct {
-	DeviceID       pgtype.UUID
-	MediaItemID    pgtype.UUID
-	UserID         pgtype.UUID
-	SelectionText  string
-	StartPosition  string
-	EndPosition    string
-	Color          string
-	NoteText       string
-	EpubcfiStart   string
-	EpubcfiEnd     string
+	DeviceID        pgtype.UUID
+	MediaItemID     pgtype.UUID
+	UserID          pgtype.UUID
+	SelectionText   string
+	StartPosition   string
+	EndPosition     string
+	Color           string
+	NoteText        string
+	EpubcfiStart    string
+	EpubcfiEnd      string
 	PercentageStart float64
 	PercentageEnd   float64
-	Source         string
-	DeviceSyncData map[string]interface{}
+	Source          string
+	DeviceSyncData  map[string]interface{}
 }
 
 type NoteUpdate struct {
-	DeviceID     pgtype.UUID
-	MediaItemID  pgtype.UUID
-	UserID       pgtype.UUID
-	Content      string
-	Position     string
-	Source       string
+	DeviceID       pgtype.UUID
+	MediaItemID    pgtype.UUID
+	UserID         pgtype.UUID
+	Content        string
+	Position       string
+	Source         string
 	DeviceSyncData map[string]interface{}
 }
 
@@ -443,6 +443,10 @@ func (p *SyncQueueProcessor) syncProgress(ctx context.Context, userID pgtype.UUI
 		if v, ok := syncData["epubcfi"].(string); ok {
 			req.Epubcfi = &v
 		}
+		// Entries without a CFI are percentage-only by intent: declare it
+		// so the service clears any inherited stale anchor instead of
+		// re-pairing it with this percentage.
+		req.ClearLocator = req.Epubcfi == nil
 		if v, ok := syncData["context_text"].(string); ok {
 			req.ContextText = &v
 		}