fix(notionmeetings): harden hydration fallbacks

Author: salmonumbrella

cmd/msgvault/cmd/notion_meetings.go

@@ -118,7 +118,7 @@ func runNotionMeetingsProbe(ctx context.Context, out io.Writer, client notionMee
 	if _, err := client.ListUsers(ctx, ""); errors.Is(err, notionmeetings.ErrUserInformation) {
 		_, _ = fmt.Fprintln(out, "  User Information: unavailable (attendees remain display-only)")
 	} else if err != nil {
-		return fmt.Errorf("probe Notion User Information access: %w", err)
+		_, _ = fmt.Fprintf(out, "  User Information: unavailable (error: %v; attendees remain display-only)\n", err)
 	} else {
 		_, _ = fmt.Fprintln(out, "  User Information: available")
 	}

cmd/msgvault/cmd/notion_meetings_test.go

@@ -119,6 +119,16 @@ func TestRunNotionMeetingsProbeDegradesWithoutUserInformation(t *testing.T) {
 	assert.Contains(t, out.String(), "User Information: unavailable")
 }
 
+func TestRunNotionMeetingsProbeDegradesOnTransientUserListingFailure(t *testing.T) {
+	var out bytes.Buffer
+	err := runNotionMeetingsProbe(context.Background(), &out, fakeNotionProbe{
+		result: &notionmeetings.QueryResult{}, usersErr: errors.New("rate limit exceeded"),
+	})
+	require.NoError(t, err)
+	assert.Contains(t, out.String(), "User Information: unavailable")
+	assert.Contains(t, out.String(), "rate limit exceeded")
+}
+
 func TestFinishNotionMeetingsImportRefreshesCommittedWritesOnFailure(t *testing.T) {
 	refreshed := 0
 	err := finishNotionMeetingsImport("work", &notionmeetings.ImportSummary{MeetingsAdded: 1},

docs/usage/meetings.md

@@ -261,7 +261,7 @@ Each meeting-note block becomes one `meeting_transcript` message in one
 `meeting` conversation, keyed by the block ID. The body contains deterministic
 title, time, attendee, summary, notes, and transcript sections. Raw format
 `notion_meeting_json` preserves the query object, block trees, Markdown page,
-minimal resolved users, and warnings.
+privacy-safe attendee display labels, minimal resolved users, and warnings.
 
 Notion's `created_by` user is stored as creator metadata and is never assumed
 to be the organizer. Only attendees with provider-verified email addresses

internal/notionmeetings/format.go

@@ -36,16 +36,17 @@ type rawBlockTree struct {
 }
 
 type rawEvidence struct {
-	SchemaVersion int               `json:"schema_version"`
-	Discovery     json.RawMessage   `json:"discovery"`
-	MeetingBlock  json.RawMessage   `json:"meeting_block"`
-	Summary       rawBlockTree      `json:"summary,omitzero"`
-	Notes         rawBlockTree      `json:"notes,omitzero"`
-	Transcript    rawBlockTree      `json:"transcript,omitzero"`
-	PageMarkdown  json.RawMessage   `json:"page_markdown"`
-	Canonical     canonicalEvidence `json:"canonical"`
-	ResolvedUsers []resolvedUser    `json:"resolved_users,omitempty"`
-	Warnings      []string          `json:"warnings,omitempty"`
+	SchemaVersion  int               `json:"schema_version"`
+	Discovery      json.RawMessage   `json:"discovery"`
+	MeetingBlock   json.RawMessage   `json:"meeting_block"`
+	Summary        rawBlockTree      `json:"summary,omitzero"`
+	Notes          rawBlockTree      `json:"notes,omitzero"`
+	Transcript     rawBlockTree      `json:"transcript,omitzero"`
+	PageMarkdown   json.RawMessage   `json:"page_markdown"`
+	Canonical      canonicalEvidence `json:"canonical"`
+	AttendeeLabels []string          `json:"attendee_labels,omitempty"`
+	ResolvedUsers  []resolvedUser    `json:"resolved_users,omitempty"`
+	Warnings       []string          `json:"warnings,omitempty"`
 }
 
 type canonicalEvidence struct {
@@ -86,8 +87,8 @@ func (h *HydratedMeeting) ArchiveSnapshot(sourceID int64, identifier, accountEma
 		MeetingBlock: rawForBlock(h.MeetingBlock),
 		Summary:      rawForTree(h.SummaryTree), Notes: rawForTree(h.NotesTree),
 		Transcript: rawForTree(h.TranscriptTree), PageMarkdown: rawForMarkdown(h.PageMarkdown),
-		Canonical:     canonicalEvidence{Summary: h.Summary, Notes: h.Notes, Transcript: h.Transcript},
-		ResolvedUsers: h.ResolvedUsers, Warnings: h.Warnings,
+		Canonical:      canonicalEvidence{Summary: h.Summary, Notes: h.Notes, Transcript: h.Transcript},
+		AttendeeLabels: h.AttendeeLabels, ResolvedUsers: h.ResolvedUsers, Warnings: h.Warnings,
 	})
 	if err != nil {
 		return meetingarchive.Snapshot{}, fmt.Errorf("marshal Notion raw evidence: %w", err)

internal/notionmeetings/hydrate.go

@@ -61,6 +61,7 @@ type Hydrator struct {
 	users            map[string]User
 	usersRead        bool
 	usersUnavailable bool
+	usersFailure     error
 	requests         int
 	bytes            int
 	blocks           int
@@ -124,11 +125,14 @@ func (h *Hydrator) Hydrate(ctx context.Context, meeting MeetingNote) (*HydratedM
 		return nil, err
 	}
 	markdownTranscript := extractMarkdownTranscript(result.PageMarkdown.Markdown)
-	if result.Transcript == "" && markdownTranscript != "" {
+	markdownComplete := !result.PageMarkdown.Truncated && len(result.PageMarkdown.UnknownBlockIDs) == 0
+	if result.Transcript == "" && markdownTranscript != "" && !markdownComplete {
+		result.Warnings = append(result.Warnings, "page Markdown transcript was incomplete; transcript remains pending")
+	} else if result.Transcript == "" && markdownTranscript != "" {
 		result.Transcript = markdownTranscript
 		result.MarkdownTranscriptFallback = true
 		result.Warnings = append(result.Warnings, "structured transcript was empty; used page Markdown transcript")
-	} else if result.Transcript != "" && markdownTranscript != "" &&
+	} else if result.Transcript != "" && markdownTranscript != "" && markdownComplete &&
 		normalizedContent(result.Transcript) != normalizedContent(markdownTranscript) {
 		result.Warnings = append(result.Warnings, "structured transcript and page Markdown transcript differed")
 	}
@@ -226,14 +230,12 @@ func (h *Hydrator) resolveAttendees(ctx context.Context, result *HydratedMeeting
 				return err
 			}
 			page, err := h.source.ListUsers(ctx, cursor)
-			if errors.Is(err, ErrUserInformation) {
+			if err != nil {
 				h.usersUnavailable = true
+				h.usersFailure = err
 				h.usersRead = true
 				break
 			}
-			if err != nil {
-				return fmt.Errorf("list Notion users: %w", err)
-			}
 			if err := h.reserveBytes(page.Raw); err != nil {
 				return err
 			}
@@ -256,7 +258,12 @@ func (h *Hydrator) resolveAttendees(ctx context.Context, result *HydratedMeeting
 		}
 	}
 	if h.usersUnavailable {
-		result.Warnings = append(result.Warnings, "Notion User Information access unavailable; attendee emails were not resolved")
+		if errors.Is(h.usersFailure, ErrUserInformation) {
+			result.Warnings = append(result.Warnings, "Notion User Information access unavailable; attendee emails were not resolved")
+		} else {
+			result.Warnings = append(result.Warnings,
+				fmt.Sprintf("Notion User Information lookup failed: %v; attendee emails were not resolved", h.usersFailure))
+		}
 	}
 
 	for _, id := range result.Discovery.MeetingNotes.CalendarEvent.Attendees {

internal/notionmeetings/hydrate_test.go

@@ -11,11 +11,12 @@ import (
 )
 
 type fakeHydrationSource struct {
-	blocks   map[string]*Block
-	children map[string]map[string]*BlockPage
-	markdown *MarkdownPage
-	users    map[string]*UserPage
-	usersErr error
+	blocks     map[string]*Block
+	children   map[string]map[string]*BlockPage
+	markdown   *MarkdownPage
+	users      map[string]*UserPage
+	usersErr   error
+	usersCalls int
 }
 
 func (f *fakeHydrationSource) RetrieveBlock(_ context.Context, id string) (*Block, error) {
@@ -39,6 +40,7 @@ func (f *fakeHydrationSource) RetrievePageMarkdown(_ context.Context, _ string,
 }
 
 func (f *fakeHydrationSource) ListUsers(_ context.Context, cursor string) (*UserPage, error) {
+	f.usersCalls++
 	if f.usersErr != nil {
 		return nil, f.usersErr
 	}
@@ -111,7 +113,7 @@ func completeHydrationSource() *fakeHydrationSource {
 			"": {
 				Results: []User{
 					{ID: "user-1", Name: "Test Attendee", Type: "person", Person: UserPerson{Email: "attendee@example.com", EmailVerified: true}},
-					{ID: "user-2", Name: "Unresolved Attendee", Type: "person"},
+					{ID: "user-2", Name: "Unresolved Attendee", Type: "person", Person: UserPerson{Email: "unverified@example.com"}},
 				},
 			},
 		},
@@ -152,6 +154,8 @@ func TestHydratorBuildsCanonicalSnapshotWithoutInventingOrganizer(t *testing.T)
 	assert.Equal(RawFormat, snapshot.RawFormat)
 	assert.Contains(string(snapshot.Raw), `"discovery"`)
 	assert.Contains(string(snapshot.Raw), `"page_markdown"`)
+	assert.Contains(string(snapshot.Raw), `"attendee_labels":["Test Attendee","Unresolved Attendee"]`)
+	assert.NotContains(string(snapshot.Raw), "unverified@example.com")
 	assert.NotContains(string(snapshot.Raw), "user@example.com", "configured identity must not enter provider evidence")
 	assert.Contains(string(snapshot.Metadata), `"creator_user_id":"creator-1"`)
 	assert.Contains(string(snapshot.Metadata), `"unresolved_attendee_ids":["user-2"]`)
@@ -171,6 +175,66 @@ func TestHydratorUsesMarkdownTranscriptFallback(t *testing.T) {
 	assert.Contains(hydrated.Warnings, "structured transcript was empty; used page Markdown transcript")
 }
 
+func TestHydratorLeavesIncompleteMarkdownTranscriptPending(t *testing.T) {
+	tests := []struct {
+		name   string
+		mutate func(*MarkdownPage)
+	}{
+		{
+			name: "truncated",
+			mutate: func(page *MarkdownPage) {
+				page.Truncated = true
+			},
+		},
+		{
+			name: "unknown blocks",
+			mutate: func(page *MarkdownPage) {
+				page.UnknownBlockIDs = []string{"transcript-child-1"}
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			assert := assert.New(t)
+			source := completeHydrationSource()
+			empty := paragraph("transcript-1", "", false)
+			source.blocks["transcript-1"] = &empty
+			source.markdown.Markdown = "# Weekly planning\n\n## Transcript\nTest Speaker: Partial transcript."
+			tt.mutate(source.markdown)
+
+			hydrated, err := NewHydrator(source).Hydrate(context.Background(), hydrationMeeting())
+			require.NoError(t, err)
+			assert.Empty(hydrated.Transcript)
+			assert.False(hydrated.MarkdownTranscriptFallback)
+			assert.Contains(hydrated.Warnings, "page Markdown transcript was incomplete; transcript remains pending")
+		})
+	}
+}
+
+func TestHydratorDoesNotCompareIncompleteMarkdownTranscript(t *testing.T) {
+	source := completeHydrationSource()
+	source.markdown.Markdown = "# Weekly planning\n\n## Transcript\nTest Speaker: Partial conflicting transcript."
+	source.markdown.Truncated = true
+
+	hydrated, err := NewHydrator(source).Hydrate(context.Background(), hydrationMeeting())
+	require.NoError(t, err)
+	assert.NotContains(t, hydrated.Warnings, "structured transcript and page Markdown transcript differed")
+}
+
+func TestHydratorDoesNotWarnAboutIncompleteMarkdownWithoutTranscript(t *testing.T) {
+	source := completeHydrationSource()
+	empty := paragraph("transcript-1", "", false)
+	source.blocks["transcript-1"] = &empty
+	source.markdown.Markdown = "# Weekly planning\n\nMeeting context only."
+	source.markdown.UnknownBlockIDs = []string{"unrelated-block-1"}
+
+	hydrated, err := NewHydrator(source).Hydrate(context.Background(), hydrationMeeting())
+	require.NoError(t, err)
+	assert.Empty(t, hydrated.Transcript)
+	assert.NotContains(t, hydrated.Warnings, "page Markdown transcript was incomplete; transcript remains pending")
+}
+
 func TestHydratorRejectsRepeatedChildCursor(t *testing.T) {
 	source := completeHydrationSource()
 	source.children["notes-1"][""] = &BlockPage{HasMore: true, NextCursor: "same"}
@@ -197,3 +261,23 @@ func TestHydratorDegradesWhenUserInformationIsUnavailable(t *testing.T) {
 	require.NoError(err)
 	assert.Contains(snapshot.Body, "Attendees: user-1, user-2")
 }
+
+func TestHydratorDegradesAndCachesTransientUserListingFailure(t *testing.T) {
+	assert := assert.New(t)
+	require := require.New(t)
+	source := completeHydrationSource()
+	source.usersErr = errors.New("rate limit exceeded")
+	hydrator := NewHydrator(source)
+
+	first, err := hydrator.Hydrate(context.Background(), hydrationMeeting())
+	require.NoError(err)
+	assert.Empty(first.Attendees)
+	assert.Equal([]string{"user-1", "user-2"}, first.AttendeeLabels)
+	assert.Contains(first.Warnings, "Notion User Information lookup failed: rate limit exceeded; attendee emails were not resolved")
+
+	second, err := hydrator.Hydrate(context.Background(), hydrationMeeting())
+	require.NoError(err)
+	assert.Empty(second.Attendees)
+	assert.Contains(second.Warnings, "Notion User Information lookup failed: rate limit exceeded; attendee emails were not resolved")
+	assert.Equal(1, source.usersCalls)
+}

internal/notionmeetings/importer_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"database/sql"
 	"encoding/json"
+	"errors"
 	"testing"
 	"time"
 
@@ -138,6 +139,14 @@ func TestImporterDetectsHydratedSnapshotChangesWithoutDiscoveryEdit(t *testing.T
 			},
 			wantRaw: "Revised page context.",
 		},
+		{
+			name: "attendee display label",
+			mutate: func(source *fakeImportSource) {
+				source.users[""].Results[1].Name = "Renamed Unresolved Attendee"
+			},
+			wantBody: "Attendees: Test Attendee, Renamed Unresolved Attendee",
+			wantRaw:  `"attendee_labels":["Test Attendee","Renamed Unresolved Attendee"]`,
+		},
 	}
 
 	for _, tt := range tests {
@@ -296,6 +305,69 @@ func TestImporterRetriesPendingTranscriptOutsideVisibleLimit(t *testing.T) {
 	assert.Contains(body, "Transcript arrived.")
 }
 
+func TestImporterRetriesTruncatedMarkdownTranscriptUntilComplete(t *testing.T) {
+	assert := assert.New(t)
+	require := require.New(t)
+	st, source, imp := newImporterFixture(t)
+	empty := paragraph("transcript-1", "", false)
+	source.blocks["transcript-1"] = &empty
+	source.markdown.Markdown = "# Weekly planning\n\n## Transcript\nTest Speaker: Partial transcript."
+	source.markdown.Truncated = true
+	source.markdown.Raw = json.RawMessage(`{"object":"page_markdown","id":"page-1","truncated":true}`)
+
+	first, err := imp.Import(context.Background(), ImportOptions{Identifier: "work"})
+	require.NoError(err)
+	state := lastNotionState(t, st, first.SourceID)
+	require.Len(state.Pending, 1)
+	assert.Equal("meeting-1", state.Pending[0].BlockID)
+	var body string
+	require.NoError(st.DB().QueryRow(`SELECT body_text FROM message_bodies`).Scan(&body))
+	assert.NotContains(body, "Partial transcript.")
+
+	fullDiscovery, err := json.Marshal(hydrationMeeting())
+	require.NoError(err)
+	source.blocks["meeting-1"].Raw = fullDiscovery
+	source.query.Results = nil
+	source.markdown.Markdown = "# Weekly planning\n\n## Transcript\nTest Speaker: Complete transcript."
+	source.markdown.Truncated = false
+	source.markdown.Raw = json.RawMessage(`{"object":"page_markdown","id":"page-1","truncated":false}`)
+	imp.now = func() time.Time { return time.Date(2026, 8, 29, 18, 1, 0, 0, time.UTC) }
+
+	second, err := imp.Import(context.Background(), ImportOptions{Identifier: "work"})
+	require.NoError(err)
+	assert.Equal(int64(1), second.MaintenanceRetries)
+	assert.Equal(int64(1), second.MeetingsUpdated)
+	state = lastNotionState(t, st, second.SourceID)
+	assert.Empty(state.Pending)
+	require.NoError(st.DB().QueryRow(`SELECT body_text FROM message_bodies`).Scan(&body))
+	assert.Contains(body, "Complete transcript.")
+}
+
+func TestImporterContinuesWhenUserListingFailsTransiently(t *testing.T) {
+	assert := assert.New(t)
+	require := require.New(t)
+	st, source, imp := newImporterFixture(t)
+	source.usersErr = errors.New("rate limit exceeded")
+
+	summary, err := imp.Import(context.Background(), ImportOptions{Identifier: "work"})
+	require.NoError(err)
+	assert.Equal(int64(1), summary.MeetingsAdded)
+	assert.Zero(summary.Errors)
+
+	var messageID int64
+	require.NoError(st.DB().QueryRow(
+		`SELECT id FROM messages WHERE source_message_id = 'meeting-1'`,
+	).Scan(&messageID))
+	raw, err := st.GetMessageRaw(messageID)
+	require.NoError(err)
+	assert.Contains(string(raw), "Notion User Information lookup failed: rate limit exceeded")
+	var participants int
+	require.NoError(st.DB().QueryRow(
+		`SELECT COUNT(*) FROM message_recipients WHERE message_id = ?`, messageID,
+	).Scan(&participants))
+	assert.Zero(participants)
+}
+
 func TestImporterContinuesVisibleWorkWhenPendingMeetingCannotBeLoaded(t *testing.T) {
 	assert := assert.New(t)
 	require := require.New(t)