From b0537b857547aeb07c8c7bf604183560054ec2fd Mon Sep 17 00:00:00 2001 From: cesnimda Date: Mon, 10 Aug 2026 10:22:48 +0200 Subject: [PATCH] docs(email): record retry rotation evidence --- docs/audits/verification-log.md | 1 + docs/verification/mail-001-job-email-hub.md | 8 +++++++- docs/work-programmes/decisions.md | 10 ++++++++++ docs/work-programmes/master-progress.md | 6 +++--- docs/work-programmes/master-work-plan.md | 6 +++--- docs/work-programmes/session-handoff.md | 8 ++++---- 6 files changed, 28 insertions(+), 11 deletions(-) diff --git a/docs/audits/verification-log.md b/docs/audits/verification-log.md index b5e4178..ae1864c 100644 --- a/docs/audits/verification-log.md +++ b/docs/audits/verification-log.md @@ -182,3 +182,4 @@ Output was reduced to filenames and commit counts. The token artifact appears un | V-148 | Focused `EmailDraftsControllerTests`; full backend; backend build; staged diff review | Repository root | Verify bounded authenticated draft CRUD, owner/job isolation and optimistic revision conflicts without provider side effects | PASS — focused 4/4; backend 629/629; build 0 warnings/errors; incomplete autosave, validation, unknown provider, foreign job/direct ID/update/delete denial, stale update/delete conflicts and owned delete pass on real SQLite; `a9bb22e` pushed | Synthetic content/local database only; no UI/browser/provider/send/production action | API boundary verified; UI recovery remains | | V-149 | Focused draft API/export/persistence tests; full backend; EF model-current; SQLite/MariaDB up/down migration scripts; staged diff review | Repository root | Prevent refresh-restored drafts from receiving a new delivery identity | PASS — focused 9/9, backend 629/629 and model-current pass; creation assigns a canonical UUID, edits preserve it, exports include it, all-owner list remains tenant-filtered, and reversible provider SQL is generated; `80b5532` pushed | MariaDB SQL generated only; historical JT-019 still blocks full blank SQLite chain; no UI/provider/send/production action | UI safety prerequisite verified | | V-150 | Focused correspondence-inbox Jest; full frontend Jest; production build; staged diff review | `job-tracker-ui` / repository root | Verify explicit reply-draft save, refresh-resume, server identity adoption, conflict handling and safe post-send cleanup | PASS — focused 11/11; frontend 50/50 suites and 196/196 tests; TypeScript/production build pass; save accepts incomplete reply, resume preserves private text, 409 keeps local edits visible, discard/delete and sent cleanup use revision | JSDOM/mocked API only; browser/provider/send/production not exercised; Jest retains existing force-exit notice | Reply recovery verified locally; new-message and durable failed-attempt rotation remain | +| V-151 | Focused `EmailDraftsControllerTests`; full backend; focused/full correspondence-inbox Jest; production build; staged diff review | Repository root / `job-tracker-ui` | Verify persisted delivery identity rotates only after the matching definitive failure | PASS — draft API 5/5; backend 630/630; inbox 12/12; frontend 50 suites/197 tests; build pass; no ledger row/refused, failed/rotated, stale/refused and foreign/not-found paths pass; `29de263` pushed | Synthetic SQLite and mocked UI only; two npm commands were initially run from repository root and failed environmentally before correct-directory reruns passed; no provider/send/production action | Durable failed-attempt rotation verified locally | diff --git a/docs/verification/mail-001-job-email-hub.md b/docs/verification/mail-001-job-email-hub.md index 8b4ff50..9fbbf76 100644 --- a/docs/verification/mail-001-job-email-hub.md +++ b/docs/verification/mail-001-job-email-hub.md @@ -168,12 +168,18 @@ Status: `IN PROGRESS`. Canonical hub routing, provider-neutral reads, explicit-c - Discard and successful-send cleanup use the current revision. If cleanup finds a newer revision after send, the UI warns rather than deleting the newer draft; the stable client-request ID still prevents a second delivery attempt. - Focused UI passes 11/11, full frontend 50 suites/196 tests and the production build pass. These are mocked/JSDOM claims only; browser/provider/production remain gated. +## Implemented definitive-failure draft rotation + +- A saved draft receives a new delivery UUID only through an explicit revisioned action and only when its current UUID matches the authenticated owner's `failed` ledger attempt. +- Missing attempts, stale revisions and foreign draft IDs are refused. Pending, sending, uncertain and sent states never satisfy the terminal-failure predicate and cannot be made retryable through this route. +- Prepare new attempt now persists the rotated UUID/revision before re-enabling send. Draft API passes 5/5, backend 630/630, inbox 12/12, full frontend 197/197 and build pass. + ## Remaining MAIL-001 work - Extend shared provider-neutral thread navigation while preserving provider capability differences; application context and Gmail unlink are now shared. - Add read/unread, pin/read-later/archive/spam/trash only where the provider supports it; identity, disconnected/read-only/send-capable and provider-status failure states are now explicit. - Share thread detail and link/unlink actions between hub and job workspace. -- Add compose-new-message UI and durable explicit failed-attempt identity rotation; saved reply refresh recovery is implemented. +- Add compose-new-message job/provider selection; saved reply recovery and durable failed-attempt rotation are implemented. - Complete account deletion coverage under SEC-009 before production rollout; job-level hard-delete cascade and export coverage are verified. - Preserve minimal audit metadata without sensitive body logging. Free non-AI access is verified; future AI assistance remains a Pro/privacy-gated addition, not a prerequisite for basic email. - Complete remaining link/unlink/dismiss/draft/send/failure/two-user browser/production provider gates. Shared application-context behavior is now covered locally. No real email may be sent during repository verification. diff --git a/docs/work-programmes/decisions.md b/docs/work-programmes/decisions.md index d965d16..d5859cc 100644 --- a/docs/work-programmes/decisions.md +++ b/docs/work-programmes/decisions.md @@ -579,3 +579,13 @@ - **Consequences:** unsaved edits are intentionally not refresh-durable; saved replies are. A successful send attempts revisioned draft cleanup, while the persisted client ID keeps any surviving copy duplicate-safe. Compose-new-message and durable failed-attempt identity rotation remain separate increments. - **User approval required:** No; this is approved local MAIL-001 UI work with mocked APIs and no email/provider action. - **Reversible:** Revert `d3d2b67`; stored drafts remain available through the API/export but no UI consumes them. + +## DEC-059 — Rotate draft delivery identity only from a terminal failure + +- **Date:** 2026-08-10 +- **Decision:** Add an explicit revisioned `new-attempt` action that issues a new draft client-request UUID only when the authenticated owner's matching ledger row is `failed`. Wire the existing Prepare new attempt UI to this action for saved drafts. +- **Reason/evidence:** ordinary edits/refresh must preserve idempotency, while a provider-confirmed failure needs a deliberate recovery path. Pending/sending/uncertain/sent states cannot disprove delivery and must not rotate. Real-SQLite owner/stale/status tests and mocked UI pass. +- **Alternatives considered:** let the browser invent UUIDs; rotate on any error; rotate during save; automatically retry failed sends. These lose durable state, can duplicate uncertain/sent mail or weaken explicit approval. +- **Consequences:** definitively failed drafts can be reviewed and retried under a new ledger identity; all ambiguous or successful attempts remain non-retryable. Unsaved local drafts retain the existing explicit local new-attempt behavior because no durable ledger relationship exists yet. +- **User approval required:** No; this is approved safety work with fake/local evidence and no email/provider call. +- **Reversible:** Revert `29de263`; saved failed drafts then have no durable retry rotation and the UI should not offer that action. diff --git a/docs/work-programmes/master-progress.md b/docs/work-programmes/master-progress.md index f73e884..4077e39 100644 --- a/docs/work-programmes/master-progress.md +++ b/docs/work-programmes/master-progress.md @@ -2,8 +2,8 @@ Updated: 2026-08-10 -- **Overall programme status:** Active. Seven packages are locally verified; nineteen packages through CAREER-002 are implemented with automated/runtime evidence but blocked from applicable browser/provider/production gates; MAIL-001 is in progress with nineteen committed implementation/test increments. Gitea run 609 passes complete pull-request CI in 4m20s; DEP-001 now awaits approved merge-to-main and production verification only. -- **Current work package:** `MAIL-001` — consolidated job-email hub and explicit sending (`IN PROGRESS`); routing/reads/detail, ledger, Gmail/Graph delivery/re-consent, safe send API/UI, recovery, legacy SMTP retirement, send/draft export, revisioned draft API/idempotency and saved reply recovery are committed. Application context, confirmed Gmail unlink and honest disconnected/read-only/send/failure states are shared. New-message UI, failed-attempt rotation and provider mailbox mutations remain; full account deletion stays SEC-009. +- **Overall programme status:** Active. Seven packages are locally verified; nineteen packages through CAREER-002 are implemented with automated/runtime evidence but blocked from applicable browser/provider/production gates; MAIL-001 is in progress with twenty committed implementation/test increments. Gitea run 609 passes complete pull-request CI in 4m20s; DEP-001 now awaits approved merge-to-main and production verification only. +- **Current work package:** `MAIL-001` — consolidated job-email hub and explicit sending (`IN PROGRESS`); routing/reads/detail, ledger, Gmail/Graph delivery/re-consent, safe send API/UI, recovery, legacy SMTP retirement, send/draft export, revisioned draft API/idempotency, saved reply recovery and definitive-failure rotation are committed. Application context, confirmed Gmail unlink and honest disconnected/read-only/send/failure states are shared. New-message UI and provider mailbox mutations remain; full account deletion stays SEC-009. - **Completed work packages:** None are `DONE`; all repository security/AI packages still have applicable browser, provider and/or production gates. - **Locally verified work:** SEC-001, SEC-002, SEC-003, SEC-005A, CORE-001, PROD-002 and DEP-001 (`VERIFIED LOCALLY`). - **Implemented, verification incomplete:** SEC-004, SEC-005B, SEC-008, CORE-002, BG-001, OPS-001A/B/C, POL-001/002, AI-001/002/003/004, UX-001/002, QA-001, CAREER-001 and CAREER-002 (`IMPLEMENTED — NOT VERIFIED`). CAREER-002 now protects unsaved edits and provides tested structured custom-entry, profile-override and preview-error interactions; all automated/build gates pass. @@ -12,7 +12,7 @@ Updated: 2026-08-10 - **Deferred work:** None. Conditional multi-replica coordination, model deletion, realtime operation delivery and unrelated production changes remain outside current packages. - **Next five work packages:** MAIL-001 consolidated email experience; JOBS-001 job-search/application redesign; HOME-001 homepage/Pro promotion; UX-003 authentication/profile polish; PRODUCT-001 homepage/Pro claims. SEC-006/007 resume after package-index permission. - **Status counts:** 7 `VERIFIED LOCALLY`; 19 `IMPLEMENTED — NOT VERIFIED`; 1 `IN PROGRESS`; 8 `NOT STARTED`; 5 `BLOCKED`; 0 `DONE`; 0 `DEFERRED`. -- **Test status:** backend 629/629; frontend 50/50 suites and 196/196 tests; Playwright smoke 4/4; npm audit 0 vulnerabilities; DEP-001 focused router 24/24 and production build pass; MAIL-001 reply-draft UI 11/11, draft API/idempotency 9/9, readable draft export 4/4, draft persistence 1/1, Free send 7/7, provider states 9/9, hub unlink 8/8 UI and 2/2 API, shared context 10/10, prior send export/cascade 16/16, recovery/send 10/10, legacy follow-up/backend worker 10/10, legacy UI 2/2, delivery/capability 18/18, provider/correspondence 5/5 and hub detail 5/5. EF model-current and SQLite/MariaDB up/down draft scripts pass; a full blank-chain SQLite apply remains blocked by pre-existing JT-019 drift. Jest open-handle/slow-run behavior is recorded in V-127/V-128/V-130/V-131/V-135/V-142/V-143/V-144/V-150. +- **Test status:** backend 630/630; frontend 50/50 suites and 197/197 tests; Playwright smoke 4/4; npm audit 0 vulnerabilities; DEP-001 focused router 24/24 and production build pass; MAIL-001 reply-draft UI 12/12, draft API/idempotency/rotation 10/10, readable draft export 4/4, draft persistence 1/1, Free send 7/7, provider states 9/9, hub unlink 8/8 UI and 2/2 API, shared context 10/10, prior send export/cascade 16/16, recovery/send 10/10, legacy follow-up/backend worker 10/10, legacy UI 2/2, delivery/capability 18/18, provider/correspondence 5/5 and hub detail 5/5. EF model-current and SQLite/MariaDB up/down draft scripts pass; a full blank-chain SQLite apply remains blocked by pre-existing JT-019 drift. Jest open-handle/slow-run behavior is recorded in V-127/V-128/V-130/V-131/V-135/V-142/V-143/V-144/V-150/V-151. - **Deployment status:** Gitea pull-request run 609 passed the complete CI job in 4m20s. Deploy was intentionally skipped because the workflow deploys only a `push` to `main`; live remains unchanged. No merge/deployment was performed directly, no production migrations were run and the AI operation worker remains disabled by default. - **Production status:** Unchanged and unverified. No provider/model call, model pull, external request or paid API occurred. - **Known regressions:** None found by automated/local browser checks. Jest still needs `--forceExit` and reports its existing open-handle notice. Email-provider/send tests are fake/local only; real delivery is not claimed. Current MAIL browser evidence is 1280×720 only because the browser surface could not resize or perform native Tab traversal. Interrupted attempts are aged after 15 minutes and notified without retry; the five-minute scan is unmeasured on a large ledger. Direct clean EF-only SQLite migration still hits the pre-existing historical blank-chain defect before later migrations; normal startup owns reconciliation. Cross-feature monthly AI usage accounting remains a rollout gap. diff --git a/docs/work-programmes/master-work-plan.md b/docs/work-programmes/master-work-plan.md index cce0cae..87c815e 100644 --- a/docs/work-programmes/master-work-plan.md +++ b/docs/work-programmes/master-work-plan.md @@ -651,9 +651,9 @@ Ordering differences from the suggested list: - **Required production verification:** provider read/draft/send requires explicit authorized synthetic account; never real unsolicited email. - **Status:** `IN PROGRESS`. - **Blocker:** real provider verification is external; required 375/768/1440/theme/keyboard browser gates were unavailable in the current browser surface. Mocked/local repository implementation remains unblocked. -- **Evidence:** `docs/verification/mail-001-job-email-hub.md`; V-126–V-150. Draft UI 11/11, API/idempotency 9/9, persistence 1/1 with dual-provider reversible SQL and readable export 4/4; Free send policy 7/7; provider states 9/9; hub unlink 8/8 UI and 2/2 API; shared application context focused 10/10; prior send export/cascade focused 16/16; recovery/send focused 10/10; legacy follow-up/worker 10/10; delivery/capability 18/18; provider/correspondence 5/5; hub detail 5/5; backend 629/629; frontend 50/50 suites and 196/196 tests plus build/audit; local empty/disconnected and compatibility-route browser smoke at 1280×720. -- **Commit:** `6008b4a` (hub), `536d403` (neutral reads), `a20775c` (safe detail), `653f011` (ledger), `e9937ac` (Gmail/Graph delivery adapters and consent), `123fc55` (explicit-confirmed send API), `449faeb` (confirmed reply composer), `ee5ef7e` (interrupted-send recovery), `8fe3903` (legacy SMTP retirement), `aff34cc` (content-free export and cascade evidence), `ff547df` (shared application context), `1dabbeb` (confirmed hub unlink), `f9e641c` (honest provider states), `7f41cb2` (Free email policy regression), `14b396a` (inert tenant draft persistence), `2fa4e38` (owner-isolated readable draft export), `a9bb22e` (tenant-safe revisioned draft API), `80b5532` (persisted draft send identity), `d3d2b67` (saved reply recovery/conflicts). -- **Remaining work:** full account deletion remains SEC-009; new-message UI and durable failed-attempt rotation; mailbox category capabilities; browser/production verification. Existing connections need explicit re-consent; IMAP remains read-only. No real email; uncertain sends need manual reconciliation. JT-019 blocks a clean full-chain SQLite rehearsal before the new draft migration. +- **Evidence:** `docs/verification/mail-001-job-email-hub.md`; V-126–V-151. Draft UI 12/12, API/idempotency/rotation 10/10, persistence 1/1 with dual-provider reversible SQL and readable export 4/4; Free send policy 7/7; provider states 9/9; hub unlink 8/8 UI and 2/2 API; shared application context focused 10/10; prior send export/cascade focused 16/16; recovery/send focused 10/10; legacy follow-up/worker 10/10; delivery/capability 18/18; provider/correspondence 5/5; hub detail 5/5; backend 630/630; frontend 50/50 suites and 197/197 tests plus build/audit; local empty/disconnected and compatibility-route browser smoke at 1280×720. +- **Commit:** `6008b4a` (hub), `536d403` (neutral reads), `a20775c` (safe detail), `653f011` (ledger), `e9937ac` (Gmail/Graph delivery adapters and consent), `123fc55` (explicit-confirmed send API), `449faeb` (confirmed reply composer), `ee5ef7e` (interrupted-send recovery), `8fe3903` (legacy SMTP retirement), `aff34cc` (content-free export and cascade evidence), `ff547df` (shared application context), `1dabbeb` (confirmed hub unlink), `f9e641c` (honest provider states), `7f41cb2` (Free email policy regression), `14b396a` (inert tenant draft persistence), `2fa4e38` (owner-isolated readable draft export), `a9bb22e` (tenant-safe revisioned draft API), `80b5532` (persisted draft send identity), `d3d2b67` (saved reply recovery/conflicts), `29de263` (definitive-failure identity rotation). +- **Remaining work:** full account deletion remains SEC-009; new-message job/provider UI; mailbox category capabilities; browser/production verification. Existing connections need explicit re-consent; IMAP remains read-only. No real email; uncertain sends need manual reconciliation. JT-019 blocks a clean full-chain SQLite rehearsal before the new draft migration. ### JOBS-001 — Job-search source and assessment redesign diff --git a/docs/work-programmes/session-handoff.md b/docs/work-programmes/session-handoff.md index 572b811..7cd36c1 100644 --- a/docs/work-programmes/session-handoff.md +++ b/docs/work-programmes/session-handoff.md @@ -2,8 +2,8 @@ Updated: 2026-08-10 -- **Exact current task:** MAIL-001 — add a server-authorized explicit failed-attempt rotation before implementing compose-new-message; preserve one idempotency identity across ordinary edits/refresh. -- **Last completed step:** explicit save/resume/delete/conflict UI for reply drafts was committed/pushed as `d3d2b67`; focused 11/11, frontend 196/196 and production build pass. +- **Exact current task:** MAIL-001 — implement compose-new-message with an owned job and connected send-capable provider selection, reusing the verified draft/save/send boundaries. +- **Last completed step:** server-authorized failed-attempt identity rotation was committed/pushed as `29de263`; draft API 5/5, backend 630/630, inbox 12/12, frontend 197/197 and build pass. - **Files currently modified:** authoritative MAIL-001 tracking/evidence only; persistence/export/API code is committed. - **Commands already run:** dependency/audit/router/full frontend/build; legacy follow-up/export/recovery/provider suites; full backend; Gitea run inspection; Playwright; MAIL context/unlink/provider-state/Free-policy/draft-persistence focused and full suites/build; EF model-current and dual-provider up/down scripts. See V-126–V-146. - **Test results:** npm audit 0 vulnerabilities; Gitea pull-request CI PASS in 4m20s at run 609; backend 625/625; frontend 50/50 suites and 194/194 tests; Playwright 4/4; production build passes. Draft isolation/cascade 1/1; EF model current; SQLite/MariaDB draft up/down scripts pass. Full blank-chain SQLite apply fails earlier in `AddJobEntityAndProspectStages` on missing `LastReminderEmailSentAt` (JT-019). @@ -11,8 +11,8 @@ Updated: 2026-08-10 - **Temporary files or processes:** no task-owned process is running and the failed disposable migration database was removed. Existing synthetic browser evidence/account and startup-created local backup remain documented. No provider account, real email, private content, paid service or production service was accessed. - **Production changes currently active:** none. No deployment, migration, provider connection/sync/send or production payload occurred. - **Rollback status:** downgrade `20260810080858_AddEmailDraftClientRequestId`, then `20260810075206_AddEmailDrafts`, before reverting draft commits; then follow the existing MAIL rollback order (`ee5ef7e`, `449faeb`, `123fc55`/`e9937ac`, ledger downgrade before `653f011`). No production migration/deploy/provider grant occurred. -- **Uncommitted changes:** tracking/evidence for `d3d2b67` and V-150 only; commit and push before failed-attempt rotation. +- **Uncommitted changes:** tracking/evidence for `29de263` and V-151 only; commit and push before compose-new-message. - **Known failures:** live deployment is not verified because PR deploy is intentionally skipped and the active branch is not approved for merge. Draft export/API/UI, full thread/category actions and non-Gmail review remain; existing accounts need re-consent and IMAP stays read-only. A clean full-chain SQLite apply fails in the pre-existing JT-019 migration before the new draft migration. Browser/provider/MariaDB/production unavailable or unverified; recovery scan performance is unmeasured at large ledger scale; Jest open handles; SEC-006 parser dependency work is still separately gated; parser isolation remains SEC-007. -- **Exact next action:** add a revisioned `new-attempt` draft action allowed only after the matching owner ledger attempt is definitively failed; update Prepare new attempt to persist the rotated UUID. Then add compose-new-message job/provider selection. +- **Exact next action:** load the existing paged owned-job list, show only connected send-capable providers, require explicit job/provider selection, and start a local new-message draft that uses the same Save draft and Review and send controls. Add empty/provider/job tests before browser work. - **Work that can continue independently:** remaining MAIL-001 repository work and later UX packages. SEC-006/007 await package-index permission; PROD-001/003/004 await production access. - **Decisions still required from the user:** none for synthetic/code-inspected repository work. Any provider connection or send test, internet/package upgrades, private data, external/paid providers and production actions retain explicit approval/safety gates; SEC-009 retention/legal policy remains unresolved.