Fix invalid UTF-8 during sync and suggest repair-encoding on error (#98)

## Summary

- Validate participant address names and attachment filenames with
`EnsureUTF8()` before database insertion during sync, closing a gap
where subject/body/snippet were already validated but address names and
filenames were not
- The root cause: emails with mis-labeled RFC 2047 headers (e.g.
`=?UTF-8?Q?Jane_Doe=C9ric?=` where the bytes are actually Latin-1) pass
through enmime's address parser with invalid UTF-8, get inserted into
the `participants` table as-is, then cause DuckDB errors when exported
to Parquet
- When invalid string encoding is encountered in query results, show a
hint suggesting `msgvault repair-encoding` to fix existing data
(cherry-picked from #97)

Fixes #95. Supersedes #97 

## Test plan

- [x] `TestFullSync_Latin1InFromName` - Latin-1 É in From name via
mis-labeled RFC 2047
- [x] `TestFullSync_InvalidUTF8InAllAddressFields` - Windows-1252 smart
quotes in From/To/Cc/Bcc
- [x] `TestFullSync_InvalidUTF8InAttachmentFilename` - attachment
filename validation
- [x] `TestFullSync_MultipleEncodingIssuesSameMessage` - mixed Latin-1 +
Windows-1252 in one email
- [x] `TestEncodingErrorHint` - repair-encoding hint on DuckDB encoding
errors
- [x] Full test suite passes
- [x] Linter passes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: liuxiaopai-ai <liuxiaopai-ai@users.noreply.github.com>

Author: 3 people

cmd/msgvault/cmd/list_domains.go

@@ -40,7 +40,7 @@ Examples:
 		// Execute aggregation
 		results, err := engine.Aggregate(cmd.Context(), query.ViewDomains, opts)
 		if err != nil {
-			return fmt.Errorf("aggregate by domain: %w", err)
+			return query.HintRepairEncoding(fmt.Errorf("aggregate by domain: %w", err))
 		}
 
 		if len(results) == 0 {

cmd/msgvault/cmd/list_labels.go

@@ -40,7 +40,7 @@ Examples:
 		// Execute aggregation
 		results, err := engine.Aggregate(cmd.Context(), query.ViewLabels, opts)
 		if err != nil {
-			return fmt.Errorf("aggregate by label: %w", err)
+			return query.HintRepairEncoding(fmt.Errorf("aggregate by label: %w", err))
 		}
 
 		if len(results) == 0 {

cmd/msgvault/cmd/list_senders.go

@@ -40,7 +40,7 @@ Examples:
 		// Execute aggregation
 		results, err := engine.Aggregate(cmd.Context(), query.ViewSenders, opts)
 		if err != nil {
-			return fmt.Errorf("aggregate by sender: %w", err)
+			return query.HintRepairEncoding(fmt.Errorf("aggregate by sender: %w", err))
 		}
 
 		if len(results) == 0 {

cmd/msgvault/cmd/search.go

@@ -81,7 +81,7 @@ Examples:
 		results, err := engine.Search(cmd.Context(), q, searchLimit, searchOffset)
 		fmt.Fprintf(os.Stderr, "\r            \r")
 		if err != nil {
-			return fmt.Errorf("search: %w", err)
+			return query.HintRepairEncoding(fmt.Errorf("search: %w", err))
 		}
 
 		if len(results) == 0 {

internal/query/encoding_hint.go

@@ -0,0 +1,26 @@
+package query
+
+import (
+	"fmt"
+	"strings"
+)
+
+// encodingErrorSubstring is the error text emitted by DuckDB when it encounters
+// invalid UTF-8 in a Parquet file.
+const encodingErrorSubstring = "Invalid string encoding found in Parquet file"
+
+// IsEncodingError reports whether err contains the DuckDB invalid-string-encoding
+// error that can be resolved by running `msgvault repair-encoding`.
+func IsEncodingError(err error) bool {
+	return err != nil && strings.Contains(err.Error(), encodingErrorSubstring)
+}
+
+// HintRepairEncoding wraps err with a user-facing hint suggesting
+// `msgvault repair-encoding` when the error is an encoding error.
+// If err is nil or unrelated, it is returned unchanged.
+func HintRepairEncoding(err error) error {
+	if !IsEncodingError(err) {
+		return err
+	}
+	return fmt.Errorf("%w\nHint: try running 'msgvault repair-encoding' to fix encoding issues", err)
+}

internal/query/encoding_hint_test.go

@@ -0,0 +1,83 @@
+package query
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+)
+
+func TestIsEncodingError(t *testing.T) {
+	tests := []struct {
+		name string
+		err  error
+		want bool
+	}{
+		{"nil error", nil, false},
+		{"unrelated error", errors.New("connection refused"), false},
+		{"encoding error", errors.New("Invalid string encoding found in Parquet file"), true},
+		{"wrapped encoding error", fmt.Errorf("aggregate query: %w", errors.New("Invalid string encoding found in Parquet file")), true},
+		{"encoding error substring", errors.New("scan: Invalid string encoding found in Parquet file foo.parquet"), true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := IsEncodingError(tt.err); got != tt.want {
+				t.Errorf("IsEncodingError() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestHintRepairEncoding(t *testing.T) {
+	t.Run("nil error", func(t *testing.T) {
+		if got := HintRepairEncoding(nil); got != nil {
+			t.Errorf("HintRepairEncoding(nil) = %v, want nil", got)
+		}
+	})
+
+	t.Run("unrelated error passes through", func(t *testing.T) {
+		orig := errors.New("something else")
+		got := HintRepairEncoding(orig)
+		if got != orig {
+			t.Errorf("HintRepairEncoding should return original error unchanged, got %v", got)
+		}
+	})
+
+	t.Run("encoding error gets hint", func(t *testing.T) {
+		orig := errors.New("Invalid string encoding found in Parquet file")
+		got := HintRepairEncoding(orig)
+		if got == nil {
+			t.Fatal("HintRepairEncoding returned nil")
+		}
+		msg := got.Error()
+		if want := "repair-encoding"; !containsSubstring(msg, want) {
+			t.Errorf("expected hint containing %q, got: %s", want, msg)
+		}
+		// Original error should be preserved in the chain
+		if !errors.Is(got, orig) {
+			t.Error("wrapped error should preserve original via errors.Is")
+		}
+	})
+
+	t.Run("wrapped encoding error gets hint", func(t *testing.T) {
+		inner := errors.New("Invalid string encoding found in Parquet file")
+		wrapped := fmt.Errorf("aggregate query: %w", inner)
+		got := HintRepairEncoding(wrapped)
+		msg := got.Error()
+		if want := "repair-encoding"; !containsSubstring(msg, want) {
+			t.Errorf("expected hint containing %q, got: %s", want, msg)
+		}
+	})
+}
+
+func containsSubstring(s, sub string) bool {
+	return len(s) >= len(sub) && (s == sub || len(s) > 0 && contains(s, sub))
+}
+
+func contains(s, sub string) bool {
+	for i := 0; i <= len(s)-len(sub); i++ {
+		if s[i:i+len(sub)] == sub {
+			return true
+		}
+	}
+	return false
+}

internal/store/inspect.go

@@ -139,6 +139,15 @@ func (s *Store) InspectDisplayName(sourceMessageID, recipientType, email string)
 	return displayName, err
 }
 
+// InspectParticipantDisplayName returns the display_name from the participants table for an email.
+func (s *Store) InspectParticipantDisplayName(email string) (string, error) {
+	var displayName string
+	err := s.db.QueryRow(s.Rebind(
+		"SELECT display_name FROM participants WHERE email_address = ?"),
+		email).Scan(&displayName)
+	return displayName, err
+}
+
 // InspectDeletedFromSource checks whether a message has deleted_from_source_at set.
 func (s *Store) InspectDeletedFromSource(sourceMessageID string) (bool, error) {
 	var deletedAt sql.NullTime
@@ -188,6 +197,18 @@ func (s *Store) InspectThreadSourceID(sourceMessageID string) (string, error) {
 	return threadSourceID, err
 }
 
+// InspectAttachment returns the filename and mime_type for the first attachment (by ID) of a message.
+func (s *Store) InspectAttachment(sourceMessageID string) (filename, mimeType string, err error) {
+	err = s.db.QueryRow(s.Rebind(`
+		SELECT a.filename, a.mime_type FROM attachments a
+		JOIN messages m ON a.message_id = m.id
+		WHERE m.source_message_id = ?
+		ORDER BY a.id
+		LIMIT 1
+	`), sourceMessageID).Scan(&filename, &mimeType)
+	return
+}
+
 // InspectMessageDates returns sent_at and internal_date for a message.
 func (s *Store) InspectMessageDates(sourceMessageID string) (sentAt, internalDate string, err error) {
 	err = s.db.QueryRow(s.Rebind(

internal/sync/sync.go

@@ -438,6 +438,18 @@ func (s *Syncer) parseToModel(sourceID int64, raw *gmail.RawMessage, threadID st
 	bodyHTML := textutil.EnsureUTF8(parsed.BodyHTML)
 	snippet := textutil.EnsureUTF8(raw.Snippet)
 
+	// Ensure participant names are valid UTF-8 before database insertion
+	ensureAddressUTF8(parsed.From)
+	ensureAddressUTF8(parsed.To)
+	ensureAddressUTF8(parsed.Cc)
+	ensureAddressUTF8(parsed.Bcc)
+
+	// Ensure attachment filenames and content types are valid UTF-8
+	for i := range parsed.Attachments {
+		parsed.Attachments[i].Filename = textutil.EnsureUTF8(parsed.Attachments[i].Filename)
+		parsed.Attachments[i].ContentType = textutil.EnsureUTF8(parsed.Attachments[i].ContentType)
+	}
+
 	// Ensure participants exist in database
 	allAddresses := append(append(append(parsed.From, parsed.To...), parsed.Cc...), parsed.Bcc...)
 	participantMap, err := s.store.EnsureParticipantsBatch(allAddresses)
@@ -586,6 +598,13 @@ func (s *Syncer) ingestMessage(ctx context.Context, sourceID int64, raw *gmail.R
 	return s.persistMessage(data, labelMap)
 }
 
+// ensureAddressUTF8 validates and converts address names to valid UTF-8 in place.
+func ensureAddressUTF8(addrs []mime.Address) {
+	for i := range addrs {
+		addrs[i].Name = textutil.EnsureUTF8(addrs[i].Name)
+	}
+}
+
 // storeRecipients stores recipient records.
 func (s *Syncer) storeRecipients(messageID int64, recipientType string, addresses []mime.Address, participantMap map[string]int64) error {
 	if len(addresses) == 0 {