Skip to content

refactor(tui): add accepted mail snapshot seam#663

Open
TZZheng wants to merge 1 commit into
Lingtai-AI:mainfrom
TZZheng:codex/issue-645-p1-accepted-snapshot
Open

refactor(tui): add accepted mail snapshot seam#663
TZZheng wants to merge 1 commit into
Lingtai-AI:mainfrom
TZZheng:codex/issue-645-p1-accepted-snapshot

Conversation

@TZZheng

@TZZheng TZZheng commented Jul 16, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • introduce an immutable accepted ProjectMailSnapshot boundary between the mutable refresh producer cache and mail consumers
  • reserve a nonzero request ordinal synchronously at every production refresh schedule, then reject duplicate, reverse, future, or wrong-generation completions before any mutation or side effect
  • run overlapping initial-load refreshes with independent command-local session caches so completion order cannot strand or roll back the UI
  • deep-clone all mutable mail-cache/message graphs across producer, consumer, and accessor boundaries while preserving nil versus non-nil-empty shapes
  • render current and older-page mail views only from the accepted snapshot
  • document the ownership, ordering, compatibility, and temporary-seam contracts in the TUI/fs anatomy maps

Refs #645.

Scope

This is deliberately the narrow accepted-snapshot seam, not the later root-store migration. It retains the existing producer refresh/tick path and does not add ProjectMailStore, cancellation, mutexes, tickers, scan serialization, or portal changes.

Sequence zero remains a compatibility/test envelope only; every production scheduling path now uses the reserved nonzero request flow.

Test-first evidence

Focused contract tests were written and run before the production repair. Their semantic RED covered:

  • reverse same-generation completion rolling accepted/render/session state backward
  • retained candidate, snapshot, accessor, and nested message aliases
  • mutation of the incoming snapshot pointer/version
  • nil, divergent, and intentionally empty envelope semantics

The same contracts pass at the exact published head.

Validation

Exact head: f9ef7c97f9266a77c9427793e91c7bd691907eed

  • go test ./internal/fs ./internal/tui -count=1 -timeout=120s
  • go test . -count=1 -timeout=120s
  • focused successor tests under -race
  • go vet ./internal/fs ./internal/tui
  • go test -race ./internal/fs ./internal/tui -skip '^TestPortalURLTimeoutKillsChild$' -count=1 -timeout=240s
  • formatting, diff hygiene, anatomy citation, and all-production-scheduler audits

All commands above pass. The literal full aggregate race command fails only the existing TestPortalURLTimeoutKillsChild PID-timing test; the identical failure was reproduced with the identical command on pristine base e8eba005, with no race-detector finding and no failure in this change's packages/contracts.

Independent exact-head reviews:

  • Claude Opus / high effort: PASS
  • Codex gpt-5.6-sol / high effort: PASS

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant