feat(email-writing): add hardened contextual-orchestrator boundary

[seonghobae]

Stack dependency

This Draft PR is stacked on #1329 (feat/llm-email-writing-context-task4) and implements Task 5 only from the committed LLM email-writing implementation plan.

Customer next action

This PR is orchestrator-boundary only. Customers should continue to write and send email with the current editor and send path. No writing-guidance feature, language profile, or model is available in product. Writing and sending stay on the current path.

Included

• an authenticated, provider-neutral contextual-orchestrator transport for route and conduct modes;
• canonical bare-HTTPS-origin validation, DNS allowlist validation on every attempt, pinned-address transport, redirect denial, and DNS-rebinding detection;
• bounded request messages, response bytes, JSON depth/node count, orchestration trace cardinality, token counters, retries, backoff, and circuit-breaker state;
• strict duplicate-key and non-finite-number rejection, hostile-Unicode rejection, response-mode binding, redacted stable error codes, and no retention of prompts, answers, provider metadata, workflow identifiers, URLs, or credentials;
• a bounded Judge worker lane whose cancellation and shutdown semantics wait for admitted synchronous work without leaking capacity;
• owner-scoped orchestration configuration with encrypted inference credentials, organization-aware uniqueness, secret-free API responses, and a dedicated configuration router/module;
• an idempotent Alembic migration and canonical metadata registration;
• focused transport, lifecycle, API, owner-scope, migration, architecture-boundary, and terminal branch tests;
• read-only Task 5 CI gates for production statement/branch coverage, shipped-symbol docstrings, Ruff, and compileall.

Security and privacy boundary

The browser cannot supply an orchestrator endpoint, credential, model profile, provider route, or orchestration evidence. The server resolves one owner-scoped configuration and rejects incomplete or unsafe settings before dispatch. Upstream payloads are untrusted data, not instructions. Public errors contain stable codes only.

The transport sends only the fixed /v1/chat/completions path, does not follow redirects, does not trust ambient proxy settings, and does not persist upstream response metadata.

Workflow-authority correction — 2026-08-17

The three historical write-capable workflow identities remain absent and were not restored by this retarget:

• .github/workflows/email-writing-orchestrator-promotion.yml;
• .github/workflows/email-writing-orchestrator-promotion-v2.yml;
• .github/workflows/email-writing-task5-finalize.yml.

The remaining PR-local workflow files are read-only test workflows (permissions: contents: read) with persist-credentials: false. No Task 5 PR-local workflow in the current diff is authorized to create/close/merge PRs, enable auto-merge, mutate source, or push commits.

Exact-head retarget onto live #1329

Previous head (exact current PR head at launch):

0c0ac2b598a8338a257e69bcca4d00b6fe20daf5

GitHub last showed base feat/llm-email-writing-context-task4 at stale:

0376d0ac896f6ea86183234495184694b27d7896

Current head (normal merge commit, not squash, not rebase, not force-push):

9cd9b953a2dd236aebe1fcdc25e59ba3e9388505

Live parent #1329 (feat/llm-email-writing-context-task4) merged as the second parent:

4570747ccebd57ccaab30ffc68239f0c9d2f1ca0

Normal merge commit parents:

• first parent: 0c0ac2b598a8338a257e69bcca4d00b6fe20daf5
• second parent: 4570747ccebd57ccaab30ffc68239f0c9d2f1ca0

Live parent #1329 already contains #1328 51fb5e8543247b1e5c790f3fdf98424c8fbed669 / #1327 fb7c406ee1328a6ac42dbaf54bb6852c199d8b0a / #1322 bfc2df112136bb9fe358778d701e78bf9e78b685 / develop@dd8d15191338b841f9e6f3a06507c6a5643b95d0.

ADR numbering follows the live parent:

• calendar ADR-0004 stays unique (0004-status-weighted-calendar-conflicts.md);
• email-writing remains ADR-0005;
• Task 5 transport/security files were unchanged by the merge (no product conflict, no Task 5 semantics edit). Git auto-merged only backend/main.py to keep both the calendar-conflicts and orchestrator-config routers.

Alembic head after merge:

20260813_email_orchestrator

Parent still carries 20260812_email_writing_evidence on 0017_merge_newsdom_carddav_heads. This slice's revision did not collide and remains 20260813_email_orchestrator with down_revision = 20260812_email_writing_evidence.

Local validation counts on 9cd9b953a2dd236aebe1fcdc25e59ba3e9388505:

• transport client tests: 18 passed (tests/test_contextual_orchestrator_client.py)
• hardening / lifecycle tests: 7 passed (tests/test_contextual_orchestrator_hardening.py)
• architecture-boundary tests: 1 passed (tests/test_email_writing_orchestrator_module_boundary.py)
• owner-scope tests: 7 passed (tests/test_email_writing_orchestrator_scope.py)
• migration tests: 2 passed (tests/test_email_writing_orchestrator_migration.py)
• config API tests: 3 passed (tests/test_email_writing_orchestrator_config_api.py)
• terminal-coverage tests: 32 passed (tests/test_email_writing_orchestrator_terminal_coverage.py)
• combined focused Task 5 tests: 70 passed
• Task 5 coverage: 100% (522 statements, 148 branches, fail-under=100)
• shipped-symbol docstrings: 6 modules
• ruff: All checks passed
• production-module compileall for Task 5 sources: ok
• git diff --check: ok
• write-capable promotion/finalize workflows: absent
• product Task 5 semantics edits: 0
• stability scan: no Timeout / Fatal / Warn / Denied

Predecessor evidence does not transfer. Checks, reviews, and security evidence recorded for 0c0ac2b5, 0376d0ac, or any earlier head are non-passing for this head.

Merge boundary

Keep this PR Draft while #1329 and its parent stack remain unmerged. This slice does not add candidate-review prompts, fast-mlsirm Judge calls, admission policy, review APIs, editor UI, send/publish behavior, scheduled model calls, or a release. Merge only after the unchanged exact head and its then-live base satisfy every applicable repository/inherited ruleset, all required CI/security/coverage/dependency/package/provenance workflows are terminal-success, every addressed thread is resolved, and a qualifying independent non-author post-last-push approval exists. Queued, pending, skipped-required, neutral, failed, absent, stale, predecessor-head, model-only, status-only, author-only, or cancelled evidence is non-passing. This update does not approve, merge, squash, empty-requeue, force-cancel, or mark Ready.

[coderabbitai]

Warning

Review limit reached

@seonghobae, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 13 minutes

Limit details: You’ve used all 1 included review currently available under your plan.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: e07d76a2-390b-4452-a3a4-5630cc1959b6

📥 Commits

Reviewing files that changed from the base of the PR and between 4570747 and 9cd9b95.

📒 Files selected for processing (18)

• .github/workflows/email-writing-orchestrator-hardening-tdd.yml
• .github/workflows/email-writing-orchestrator-tdd.yml
• backend/alembic/env.py
• backend/alembic/versions/20260813_0001_add_email_writing_orchestrator_config.py
• backend/api/email_writing_orchestrator_config.py
• backend/api/tenant_config.py
• backend/db/email_writing_orchestrator_config.py
• backend/main.py
• backend/services/contextual_orchestrator_client.py
• backend/services/email_writing_orchestrator_port.py
• backend/services/tenant_config_scope.py
• backend/tests/test_contextual_orchestrator_client.py
• backend/tests/test_contextual_orchestrator_hardening.py
• backend/tests/test_email_writing_orchestrator_config_api.py
• backend/tests/test_email_writing_orchestrator_migration.py
• backend/tests/test_email_writing_orchestrator_module_boundary.py
• backend/tests/test_email_writing_orchestrator_scope.py
• backend/tests/test_email_writing_orchestrator_terminal_coverage.py

---

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 9cd9b953a2dd236aebe1fcdc25e59ba3e9388505:

• Draft PR: merge automation is paused.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[seonghobae]

@coderabbitai review

Please review the unchanged exact current head 9cd9b953a2dd236aebe1fcdc25e59ba3e9388505 (normal merge of live parent #1329 4570747c). Predecessor 0c0ac2b5 evidence does not transfer. Local Task 5: 70 passed, 100% coverage. Write-capable promotion/finalize workflows stay absent. Keep Draft. This comment is not an approval.

[coderabbitai]

@seonghobae I will review the exact current head 9cd9b953a2dd236aebe1fcdc25e59ba3e9388505. I will treat predecessor-head evidence as non-passing. I will keep the PR Draft status unchanged.

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.