Skip to content

Complete durable mail delivery, extraction quality, and first-use workflows - #41

Draft
xuewill wants to merge 6 commits into
mainfrom
codex/development-roadmap
Draft

xuewill wants to merge 6 commits into
mainfrom
codex/development-roadmap

Conversation

@xuewill

@xuewill xuewill commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Mail notifications and outbound requests now persist their delivery work, recover after interrupted execution, and report provider acceptance separately from final delivery. Outbound retries reuse the original provider payload and idempotency key, charge quota once per logical request, and retain uncertain submissions for reconciliation. Signed delivery events support deduplication, early arrival, and terminal-state ordering.

The same change completes first-mail guidance and configuration repair links, adds in-app task documentation, and improves extraction against 60 labelled synthetic emails. Sender authentication uses the trusted Cloudflare platform header. Legacy or sender-supplied headers display as unverified, and AI extraction suggestions must be grounded in the submitted text.

Scope

  • Frontend
  • Worker / Backend
  • Shared package
  • Docs
  • Tooling / CI

The existing notification work includes durable jobs, owner-scoped status/replay, rule explanations, and IANA quiet-hour timezones. This branch also adds migrations 0024–0027, real local Worker/D1/R2 business tests, delayed outbound recovery, precise status timelines, and opt-in supplier/DNS diagnostics.

Verification

  • pnpm test — shared 42, Worker 247, Web 367 tests passed, plus Docs assertions
  • pnpm typecheck — all four workspaces
  • pnpm lint — all four workspaces
  • pnpm build — all four workspaces
  • Version metadata, API catalog, migration numbering, preflight, and whitespace checks
  • Browser smoke — 13 passed, 2 pre-existing visual scaffolds skipped
  • Real local business E2E — 9 passed, including early signed callbacks, stable provider keys, first-mail receipt/copy, in-app documentation, and diagnostics links
  • Rendered desktop and 375px checks with ego lite and E2E screenshots

Failure injection verifies quota atomicity and lease recovery when applying an early delivery event fails during completion. All related writes roll back together. The fixed extraction corpus improved from 40 TP / 18 FP / 7 FN to 47 TP / 0 FP / 0 FN. These are synthetic regression metrics.

Checklist

  • Updated README/docs if structure or behavior changed
  • Kept changes inside the correct layer boundaries
  • Added or updated tests where needed
  • No generated artifacts committed by mistake

Risks / Follow-ups

  • Real Resend, Email Routing, chat delivery, and Workers AI quality/cost/latency require staging validation. Local business E2E uses controlled external-service adapters.
  • Staging Environment secrets and variables were empty when checked on 2026-11-20. Isolated resources and provider credentials must be configured before real-service acceptance.
  • Migration 0027 introduces durable outbound states and request accounting. Older code only understands sent/failed, so rollback must follow the updated runbook and preserve a consistent database/worker pair.
  • Delivery recovery is bounded to 10 tasks and 4 concurrent sends per batch. Explicit domain checks have a 15-second total deadline, up to 24 external requests, and 4 concurrent DNS queries. Production latency, D1 row costs, and backlog remain release measurements.
  • Guides and the roughly 47.5 kB gzip Markdown renderer are lazy-loaded. Each guide uses the same versioned content as the documentation site.

Implementation evidence and remaining release gates are recorded in docs/plans/2026-10-04-development-execution.md, the outbound implementation record, extraction quality report, and HANDOFF.MD.

A subsequent Linux CI run exposed a profile-edit race. Delayed refreshes now preserve edited fields, stale profile reads cannot replace a completed save, and profile/preferences writes share a pending-write guard. Controlled-promise regressions reproduce the original failures and verify ordering, account transitions, and concurrent submission behavior.

Final verification for dd7441f7046efca7e91a20eb7328ab0883af5048 passed all six PR checks:

  • CI — tests, lint, types, and full build
  • E2E — page smoke and real local business workflow
  • Preview Build — passed
  • Vercel documentation preview and its GitHub integration — passed

Staging resources and a dedicated external test inbox have not yet been provisioned, as confirmed on 2026-11-20. Real-service acceptance and production release remain pending.

Why: the landing page described the product (82 text nodes, zero product
imagery) instead of demonstrating it. The hero CTA 立即开始 led straight
into the invite-code wall, open-source/self-host positioning was absent
from the first screen, and the page presented config defaults (a 20/day
send limit) as key metrics alongside fabricated testimonials — trust
risks for an open-source project.

Constraints / tradeoffs:
- Hero becomes a two-column composition: copy (OSS pills 开源/自托管/
  Cloudflare 边缘, serif headline with the rotating word now in brand
  orange, honest CTAs 申请邀请 + 自托管部署 → hosted docs) beside an
  auto-playing inbox demo card (mail arrives → code chip extracts →
  copy state), replacing the abstract 634px orb.
- The stats marquee (config defaults) is replaced by an extraction
  playground: a textarea where pasted text is processed by the REAL
  buildMessageExtraction from @wemail/shared client-side — the same pure
  function the Worker runs. Verified live: re-extraction on input,
  Chinese codes, price/date rejection.
- Demo steps are JS-timed with a reducedMotion prop that skips to the
  final frame; a blanket prefers-reduced-motion CSS guard now covers
  every landing animation (previously 1 guard in 2430 lines).
- Metrics now show verifiable facts (500+ tests, 5-min self-host,
  300+ edge locations, 100% open source); testimonials relabeled
  场景示例 with workflow scenarios, no invented personas.
- Hero headline scales from 10rem editorial display to a column-fitting
  clamp so copy + demo + playground land above the fold.

Verification:
- Full matrix: lint 0, typecheck 0, 532 tests (30+169+333), Playwright
  E2E at baseline parity (landing smoke green).
- Runtime browser verification at 1440 and 390: two-column layout
  renders, playground live-extracts typed input (991177 extracted,
  39.90 rejected), no horizontal overflow, demo steps advance, orb and
  marquee confirmed removed.
- Landing test updated to the new CTA contract and extended with
  playground/demo-region assertions.

Risks: hero visual identity shifts from centered editorial to split
layout; the serif display type and grid identity are retained.

Rejected alternatives: keeping the marquee with different numbers
(config values read as limits, not achievements); linking the secondary
CTA to the in-app /docs placeholder (it is a stub — hosted docs used
instead).
@vercel

vercel Bot commented Oct 6, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
we-mail-docs Ready Ready Preview Nov 20, 2026 7:11am UTC

@xuewill xuewill changed the title Add durable notification recovery and real mail workflow E2E Complete durable mail delivery, extraction quality, and first-use workflows Nov 20, 2026

This branch was successfully deployed

1 active deployment
Preview — dd7441f7 Deployed Nov 20, 2026 by vercel[bot]
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