feat(email-writing): expose bounded advisory review API

[seonghobae]

Scope

Task 10 only: expose the existing Task-9 email-writing review service through an authenticated, owner-scoped HTTP boundary. This is a preparatory Draft stacked on the exact current Task-9 head. It does not consume Inkspan, mutate/send email, resolve provider credentials, publish a Judge policy, or bypass the immutable fast-mlsirm artifact gate.

Exact ancestry and TDD sequence

Parent #1535 is c958b9964f925b6dca99e4c2c4db671934511a40. Exact current Task-10 head is 4c14771acddd150f59b5ce0888d15bae49686b0c. Current head was produced by an ordinary non-force two-parent restack after the Task-5 repair propagated through Tasks 6–9. This PR's semantic delta remains five Task-10 paths; inherited parent repairs are not duplicated as API-owned behavior.

Task-10-owned sequence retained in ancestry:

• RED 6fdba3c58fc34060d4cab9c69e85e18b9db70fc8 defines the HTTP contract before api.email_writing_review exists;
• d88ddbc4310dc00c83b5d185b6082e654e781e82 adds the thin advisory API and fail-closed runtime provider boundary;
• ac05e2680e2f762d8219f9eccf58bb76c844bd86 registers the route in the production FastAPI application;
• 5b66e4b1088367e9944c0d789cc732d1fe9e4a74 tightens transport/error and production-route acceptance tests;
• 4ef89294b4219029926fb081170d08dc21d6196a adds the Python 3.14 focused workflow;
• RED ae6527411c4dee51db753e5576634193f1795878 requires unknown internal service-code masking and bounded OpenAPI 403/404/503 error envelopes;
• 275ed74c37830dce30c7fabed4baf83000946be2 adds EmailWritingReviewErrorResponse, the public error allowlist, generic review_unavailable masking, and OpenAPI error schemas;
• bdd70deba2c4fead89d34db1ce8a9f0a6bc8f143 reconciles the code-current Task-10 contract documentation before the current restack.

No Jules/Cursor branch is modified or used as writable ancestry. All predecessor checks/reviews are stale after the current head movement.

API contract

POST /api/email-writing/review reuses EmailWritingReviewRequest and EmailWritingReviewResponse; no duplicate semantic review schema is introduced. The route passes only the authenticated AuthContext, scoped DB session and strict request into the injected Task-9 service.

The route remains advisory:

• admitted, abstained, unavailable, stale, context-insufficient or disagreement review states do not control mail editing or sending;
• source-email absence within the authorized lookup boundary maps to stable 404 email_unavailable;
• missing owner scope maps to stable 403 review_owner_scope_unavailable;
• allowlisted service/runtime failures map to bounded 503 codes;
• any non-allowlisted service error code collapses to 503 review_unavailable rather than becoming browser-visible causal text;
• OpenAPI explicitly declares the typed 403/404/503 EmailWritingReviewErrorResponse contract;
• malformed transport is rejected by the existing strict Pydantic request contract before service execution;
• no keyword/regex/phrase/sender-domain/recipient-count/language/position semantic fallback is introduced.

Runtime assembly gate

get_email_writing_review_service() intentionally returns no production runtime yet. The endpoint therefore fails closed with 503 {"error_code":"review_runtime_unavailable"} until the exact immutable fast-mlsirm distributable, Task-7 released-symbol consumption and admitted Task-8/Task-9 lineage exist. Tests use FastAPI dependency injection to exercise the real HTTP boundary; they do not create a production fake-success path.

No mutable fast-mlsirm or Inkspan branch, Git URL, source copy, local stub or workspace path is consumed.

Current verification state

For exact current head 4c14771acddd150f59b5ce0888d15bae49686b0c, current task10-review-api job 100237262613 / run 33627082195 is queued before executed steps. Same-head sibling job 100237248527 / run 33627078538 terminated cancelled before useful execution. Both are non-passing; every result from prior heads including bdd70deb… is predecessor evidence.

Runner acquisition is tracked through .github#712; the current leaf head is not churned merely to provoke scheduling. Fresh current-head security/coverage/review evidence remains mandatory after actual runner acquisition.

Dependency / merge boundary

Canonical runtime order remains Task 7 Judge → immutable fast-mlsirm dependency admission/pinning → Task 8 policy → Task 9 review service → Task 10 review API → immutable Inkspan consumer → EmailDetail composer → feedback/benchmark/live evaluation → protected release. This PR may be developed and checked in parallel but remains Draft and must be ordinarily reconstructed/restacked after any predecessor movement. Predecessor checks/reviews do not transfer.

Merge requires an unchanged integration-current head satisfying live protection/rulesets and all applicable CI/security/SAST/dependency/coverage/package/SBOM/provenance/review gates. No self-approval, bypass, force push, destructive rebase or gate weakening.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

PR governance metadata gate is not ready for 4c14771acddd150f59b5ce0888d15bae49686b0c:

• Draft PR: merge automation is paused.