docs(email): record delivery adapter evidence

2026-08-09 23:48:59 +02:00
parent e9937accd8
commit d44c8ceb08
7 changed files with 40 additions and 19 deletions
@@ -3,11 +3,12 @@
 Updated: 2026-08-09
 - Progress report: `docs/verification/mail-001-job-email-hub.md`
- Commands/results: `docs/audits/verification-log.md` V-126–V-132
+- Commands/results: `docs/audits/verification-log.md` V-126–V-133
 - Hub/legacy-route tests: `job-tracker-ui/src/correspondence-inbox-page.test.tsx`
 - Reused review decision tests: `job-tracker-ui/src/gmail-review-page.test.tsx`
 - Provider-neutral API tests: `JobTrackerApi.Tests/EmailControllerTests.cs`
 - Saved-copy/tenant tests: `JobTrackerApi.Tests/CorrespondenceControllerTests.cs`
 - Send-ledger tests: `JobTrackerApi.Tests/EmailSendAttemptStoreTests.cs`
- Implementation commits: `6008b4a`, `536d403`, `a20775c`, `653f011`
+- Delivery adapter tests: `JobTrackerApi.Tests/EmailProviderDeliveryTests.cs`
 - Implementation commits: `6008b4a`, `536d403`, `a20775c`, `653f011`, `e9937ac`
 - Mocked provider data only; no real email, provider connection, private content, production service or external request was used.
@@ -164,3 +164,4 @@ Output was reduced to filenames and commit counts. The token artifact appears un
 | V-130 | `dotnet test ... --filter FullyQualifiedName~EmailControllerTests --no-restore`; focused hub/review Jest; full backend/frontend; `npm.cmd run build`; `git diff --check` | Repository root / `job-tracker-ui` | Verify owner-scoped neutral status/search/detail, honest read-only capability UI and regression/build hygiene | PASS — provider controller 3/3; hub/review 5/5; backend 604/604; frontend 49/49 suites and 186/186 tests; production build and patch check pass | Provider tests use fakes; frontend uses mocked provider data. Full Jest took 170.377s and retained its existing force-exit/open-handle notice | Browser/provider/production verification remains |
 | V-131 | Focused `EmailControllerTests|CorrespondenceControllerTests`; focused correspondence-inbox Jest; full backend/frontend; `npm.cmd run build`; `git diff --check` | Repository root / `job-tracker-ui` | Verify plain-text provider detail, owner-scoped saved fallback, malformed metadata tolerance, stale-request guard, full regressions and TypeScript | PASS — backend focused 5/5 and full 605/605; frontend focused 5/5 and full 49/49 suites, 188/188 tests; production build and patch check pass | Provider response is mocked and saved data synthetic. Full Jest took 81.434s and retains the existing force-exit/open-handle notice | Browser/real-provider/production verification remains |
 | V-132 | `EmailSendAttemptStoreTests`; backend build/full tests; `dotnet ef migrations has-pending-model-changes`; SQLite/MariaDB up/down scripts; disposable SQLite upgrade/insert/rollback; cleanup verification | Repository root | Verify inert tenant send ledger, idempotency/state safety, additive provider migration and rollback | PASS — focused 3/3; backend 608/608; model current; bounded provider SQL; SQLite unique index/FK/sample row/rollback pass; temp files removed | First MariaDB script exposed SQLite-scaffolded types and was rejected; explicit provider branch corrected it. One parallel test/build attempt contended on compiler output; serial test passed. MariaDB SQL generated only, not executed | Provider/runtime limitation and corrected verification setup |
 | V-133 | Focused delivery/provider/controller tests; full backend; focused inbox Jest; frontend production build; `git diff --check` | Repository root / `job-tracker-ui` | Verify explicit consent scopes, capability reporting, Gmail/Graph payloads, IMAP read-only, rejected/reauth/uncertain classification and regressions | PASS — focused backend 18/18; full backend 613/613; inbox 5/5; production build and patch check pass | Ephemeral encrypted tokens, synthetic recipients/content and mocked HTTP only. No OAuth/provider/email call or real account. Browser/production not run | External provider/production limitation |
@@ -46,12 +46,21 @@ Status: `IN PROGRESS`. Canonical hub routing and provider-neutral read capabilit
 - Deleting the owning job cascades the ledger row. The global owner filter protects direct attempt IDs.
 - The additive migration has provider-specific SQLite/MariaDB types and reversible up/down SQL. No send route, OAuth scope or provider call was enabled.
 ## Implemented provider-delivery adapter increment
 - Gmail and Microsoft Graph authorization URLs now request explicit send consent in addition to read access. Existing read-only connections remain read-only until the user reconnects.
 - Provider status derives send capability from the stored granted scope. IMAP remains read-only because it has no configured outgoing transport.
 - Gmail builds an RFC MIME plain-text message, supports the existing Gmail thread ID, and uses the documented send endpoint. Graph sends plain-text JSON through `sendMail`.
 - HTTP rejection is a known failed-before-delivery category; 401/403 requires reauthorization. Network interruption/cancellation is marked uncertain because acceptance cannot be disproved.
 - Provider response bodies and transport exception details are not returned to callers. Recipient/body fixtures and HTTP transport are synthetic/mocked; no provider was contacted.
 - No application send route exists yet. Consent and adapters cannot be triggered by a JobTracker send button until ledger integration lands.
 ## Verification
- Focused send ledger: 3/3; provider/correspondence controllers: 5/5; hub detail: 5/5.
+- Focused delivery/provider/capability: 18/18; send ledger: 3/3; provider/correspondence controllers: 5/5; hub detail: 5/5.
- Full backend: 608/608; full frontend: 49/49 suites, 188/188 tests.
+- Full backend: 613/613; full frontend: 49/49 suites, 188/188 tests.
 - Production build/TypeScript and `git diff --check`: pass.
- Implementation commits: `6008b4a`, `536d403`, `a20775c`, `653f011`.
+- Implementation commits: `6008b4a`, `536d403`, `a20775c`, `653f011`, `e9937ac`.
 ## Remaining MAIL-001 work
@@ -69,4 +78,4 @@ The first focused Jest invocation exhibited the repository's open-handle delay.
 ## Rollback
-Revert `653f011` (after downgrading the additive migration) for the send ledger, `a20775c` for message detail, `536d403` for neutral reads, then `6008b4a` for routing. Provider scopes remain unchanged.
+Revert `e9937ac` to remove send consent/adapters, then `653f011` (after migration downgrade) for the ledger, followed by the earlier read/routing commits. Existing provider grants are not revoked by a code rollback; disconnect/reconnect is an explicit user action.
@@ -409,3 +409,13 @@
 - **Consequences:** API integration can reserve a unique attempt before external I/O and fail closed on pending/uncertain records. A provider success followed by database failure remains reconcilable rather than blindly retried. User export must include the non-sensitive metadata; job/account deletion cascades it. The migration is additive and EF-owned with explicit SQLite/MariaDB types.
 - **User approval required:** No; the approved MAIL-001 programme requires idempotent/uncertain send safety. This increment is inert and used no provider.
 - **Reversible:** Yes. Before reverting `653f011`, stop send admission, reconcile/drain attempts and downgrade `20260809195014_AddEmailSendAttempts`. No production migration has been applied.
 ## DEC-042 — Send permission is explicit; transport uncertainty fails closed
 - **Date:** 2026-08-09
 - **Decision:** Request Gmail send and Graph Mail.Send scopes on new/reconnected accounts, derive `CanSend` from the stored granted scope, keep IMAP read-only, and expose one neutral delivery contract. Treat an HTTP rejection as known failed-before-delivery, but any network interruption/cancellation as uncertain.
 - **Reason/evidence:** read access cannot authorize send, and existing tokens must not be assumed upgraded. Provider HTTP acceptance is outside the database transaction; after a broken transport the application cannot safely prove that no message was accepted. Mocked HTTP tests prove scope, payload and classification without contacting providers.
 - **Alternatives considered:** reuse application SMTP; silently expand existing token authority; mark all errors failed/retryable; expose provider error bodies; add SMTP credentials to the IMAP connection; enable a route before adapter tests. These misrepresent identity, risk duplicate delivery/data exposure, widen secret storage or invert the required dependency order.
 - **Consequences:** existing connections show read-only until explicit reconnect consent. Gmail supports its provider thread ID; Graph currently sends a new message and does not claim reply-thread semantics. The later API must reserve the ledger before calling either adapter and surface uncertain state for manual reconciliation.
 - **User approval required:** No; this repository-side programme requirement used fake transports only. Real account consent/send still requires an explicitly authorized synthetic provider account.
 - **Reversible:** Yes. Revert `e9937ac` to stop requesting/using send permission. Already granted provider permission is managed by the provider/user connection and is not automatically revoked by a code rollback.
@@ -2,8 +2,8 @@
 Updated: 2026-08-09
- **Overall programme status:** Active. Six 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 four pushed increments.
+- **Overall programme status:** Active. Six 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 five pushed increments.
- **Current work package:** `MAIL-001` — consolidated job-email hub and explicit sending (`IN PROGRESS`); routing, neutral reads, safe detail and an inert durable send ledger are pushed. Provider delivery/re-consent and explicit-send API/UI remain.
+- **Current work package:** `MAIL-001` — consolidated job-email hub and explicit sending (`IN PROGRESS`); routing/reads/detail, durable ledger and fake-verified Gmail/Graph delivery/re-consent are pushed. Explicit-send API/UI remains unavailable until ledger integration.
 - **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 and PROD-002 (`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-09
 - **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:** 6 `VERIFIED LOCALLY`; 19 `IMPLEMENTED — NOT VERIFIED`; 1 `IN PROGRESS`; 8 `NOT STARTED`; 5 `BLOCKED`; 0 `DONE`; 0 `DEFERRED`.
- **Test status:** backend 608/608; frontend 49/49 suites and 188/188 tests; MAIL-001 ledger 3/3, provider/correspondence 5/5 and hub detail 5/5; migration model/up/down/SQLite rehearsal pass; production build and patch check pass. Jest open-handle/slow-run behavior is recorded in V-127/V-128/V-130/V-131.
+- **Test status:** backend 613/613; frontend 49/49 suites and 188/188 tests; MAIL-001 delivery/capability 18/18, ledger 3/3, provider/correspondence 5/5 and hub detail 5/5; migration rehearsal and production build pass. Jest open-handle/slow-run behavior is recorded in V-127/V-128/V-130/V-131.
 - **Deployment status:** No deployment performed. No production migrations were run. 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 suites. Jest still needs `--forceExit` and reports its existing open-handle notice. Email-provider tests are fake/local only; no send capability is claimed. 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.
@@ -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 external; mocked/local implementation not blocked after dependencies.
- **Evidence:** `docs/verification/mail-001-job-email-hub.md`; V-126–V-132. Send ledger 3/3; provider/correspondence 5/5; hub detail 5/5; backend 608/608; frontend 49/49 suites and 188/188 tests plus build.
+- **Evidence:** `docs/verification/mail-001-job-email-hub.md`; V-126–V-133. Delivery/capability 18/18; ledger 3/3; provider/correspondence 5/5; hub detail 5/5; backend 613/613; frontend 49/49 suites and 188/188 tests plus build.
- **Commit:** `6008b4a` (hub), `536d403` (neutral reads), `a20775c` (safe detail), `653f011` (inert durable send ledger).
+- **Commit:** `6008b4a` (hub), `536d403` (neutral reads), `a20775c` (safe detail), `653f011` (ledger), `e9937ac` (Gmail/Graph delivery adapters and consent).
- **Remaining work:** provider send/re-consent adapters and safe classification; explicit confirmed API/UI using the ledger; export/deletion coverage; shared thread/application actions; tenant/free/pro/provider failure tests; browser/production. Existing provider scopes are read-only and legacy follow-up uses application SMTP; do not mislabel either. No real email; uncertain sends need manual reconciliation.
+- **Remaining work:** explicit confirmed API/UI using ledger and adapters; correspondence/audit transaction; export/deletion coverage; shared thread/application actions; tenant/free/pro/duplicate/uncertain tests; browser/production. Existing connections need explicit re-consent; IMAP remains read-only. Legacy follow-up SMTP must not be called provider send. No real email; uncertain sends need manual reconciliation.
 ### JOBS-001 — Job-search source and assessment redesign
@@ -2,17 +2,17 @@
 Updated: 2026-08-09
- **Exact current task:** MAIL-001 — implement fake-transport Gmail/Graph delivery adapters and re-consent capability without external calls, then connect an explicit confirmed API to the durable ledger.
+- **Exact current task:** MAIL-001 — connect one explicit-confirmed owner-scoped API to the durable ledger and provider adapters, persist correspondence/audit safely, then add the editable hub UI without real email.
- **Last completed step:** inert tenant-owned send states/idempotency and additive provider migration were committed/pushed as `653f011`; no route/provider send capability is enabled.
+- **Last completed step:** Gmail/Graph delivery adapters, explicit send consent, honest per-connection capability and rejected-versus-uncertain classification were committed/pushed as `e9937ac`. No application send route exists.
 - **Files currently modified:** MAIL-001 verification/log/master tracking documents only. Application code/tests are committed and pushed.
- **Commands already run:** complete provider/send trace; read/detail/ledger focused and full tests; TypeScript build; EF model parity; SQLite/MariaDB up/down SQL; disposable SQLite migration insert/rollback and safe temp cleanup; four implementation commits/pushes. See V-126–V-132.
+- **Commands already run:** complete provider/send trace; read/detail/ledger/delivery focused and full tests; TypeScript build; EF provider migration rehearsal; five implementation commits/pushes. See V-126–V-133.
- **Test results:** MAIL-001 ledger 3/3, provider/correspondence 5/5, hub detail 5/5; backend 608/608; frontend 49/49 suites and 188/188 tests; migration model/up/down/SQLite rehearsal and production build pass.
+- **Test results:** MAIL-001 delivery/capability 18/18, ledger 3/3, provider/correspondence 5/5, hub detail 5/5; backend 613/613; frontend 49/49 suites and 188/188 tests; migration/model/build gates pass.
 - **Services currently running:** none started intentionally. Exact task-owned hung Jest/build Node processes were stopped; Codex browser runtimes were not touched. Pre-existing Docker services were not changed.
 - **Temporary files or processes:** none. No provider account, private email, external model, 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 `20260809195014_AddEmailSendAttempts` then revert `653f011`; revert `a20775c`, `536d403`, `6008b4a` for prior MAIL increments. No production migration/deploy occurred. Production is unchanged.
+- **Rollback status:** revert `e9937ac` for consent/adapters; downgrade `20260809195014_AddEmailSendAttempts` then revert `653f011`; earlier MAIL commits remain independently reversible. No production migration/deploy occurred. Provider grants, if later obtained, require user disconnect/reconnect to revoke; none were obtained here.
 - **Uncommitted changes:** MAIL-001 evidence/tracking documents only; commit/push before the next application increment.
- **Known failures:** provider delivery/re-consent, explicit-send API/UI, export coverage, full thread actions and non-Gmail review remain; OAuth scopes and IMAP are read-only; legacy follow-up SMTP remains unsafe/mislabeled for this purpose. Real provider/SMTP/MariaDB/production unavailable; Jest open handles; SEC-006 needs internet/package-index permission; parser isolation remains SEC-007.
+- **Known failures:** explicit-send API/UI, correspondence/audit completion, export coverage, full thread actions and non-Gmail review remain; existing accounts need re-consent and IMAP stays read-only. Legacy follow-up SMTP remains unsafe/mislabeled for this purpose. Real provider/SMTP/MariaDB/production unavailable; Jest open handles; SEC-006 needs internet/package-index permission; parser isolation remains SEC-007.
- **Exact next action:** commit/push this evidence, then extend Gmail/Graph services and neutral capabilities behind fake HTTP transports with explicit send scopes and deterministic rejected-versus-uncertain error classification. Do not expose a send route until those tests and ledger integration exist.
+- **Exact next action:** commit/push this evidence, then add a POST API that requires `confirmed=true`, provider, UUID, recipient/subject/body/thread and an owned job; hash/reserve/begin the ledger before adapter I/O; map known rejection to failed and transport interruption to uncertain; never retry an existing uncertain attempt.
 - **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.