codex-platform 0.3.0__tar.gz → 0.5.0__tar.gz

codex_platform-0.5.0/.agents/rules/graphify.md

@@ -0,0 +1,9 @@
+## graphify
+
+This component is part of a larger project. It uses a global knowledge graph located at the workspace root (`../graphify-out/`).
+
+Rules:
+- Before answering architecture or codebase questions, read the global report at **`../graphify-out/GRAPH_REPORT.md`** for god nodes and community structure.
+- If `../graphify-out/wiki/index.md` exists, navigate it instead of reading raw files.
+- For cross-module questions, prefer `graphify query`, `graphify path`, or `graphify explain` (run from root or via MCP) over grep.
+- After modifying code files in this session, run `graphify update .` from the **workspace root** to keep the global graph current.

codex_platform-0.5.0/AGENTS.md

@@ -0,0 +1,9 @@
+## graphify
+
+This component is part of a larger project. It uses a global knowledge graph located at the workspace root (`../graphify-out/`).
+
+Rules:
+- Before answering architecture or codebase questions, read the global report at **`../graphify-out/GRAPH_REPORT.md`** for god nodes and community structure.
+- If `../graphify-out/wiki/index.md` exists, navigate it instead of reading raw files.
+- For cross-module questions, prefer `graphify query`, `graphify path`, or `graphify explain` (run from root or via MCP) over grep.
+- After modifying code files in this session, run `graphify update .` from the **workspace root** to keep the global graph current.

{codex_platform-0.3.0 → codex_platform-0.5.0}/CHANGELOG.md

@@ -3,6 +3,31 @@
 All notable changes to this project will be documented in this file.
 Grouped by `Added` · `Changed` · `Deprecated` · `Removed` · `Fixed`.
 
+## [Unreleased]
+
+## [0.5.0] - 2026-04-30
+
+### Added
+- Added `StreamRuntime` and `StreamRuntimeConfig` for grouped Redis Streams workers that can run all handlers in monolith mode or only selected logical groups in split-service mode.
+- Added `StreamHandlerSpec` metadata and `group` / `reply` arguments to stream router and dispatcher decorators.
+- Added `StreamProducer.publish()`, `StreamProducer.request()`, and `StreamProducer.publish_reply()` for correlation-id based request/reply flows.
+
+### Changed
+- Redis Streams payloads now use JSON-safe field encoding for structured values instead of coercing every value to plain `str` or dropping `None`.
+- `StreamConsumer` now implements the `StreamStorageProtocol` used by `StreamProcessor` directly.
+
+## [0.4.0] - 2026-04-22
+
+### Added
+- Synchronous Redis operations: `SyncStringOperations` and `SyncHashOperations` using `redis.Redis`.
+- Added `catch_redis_errors_sync` decorator for synchronous methods.
+- Added `encoder` parameter to `HashOperations.set_fields` and `SyncHashOperations.set_fields`.
+### Added
+- Added `py.typed` marker for PEP 561 compliance — downstream consumers now benefit from full type inference when using mypy or pyright.
+
+### Changed
+- Translated all Russian comments and docstrings to English across `redis_service/exceptions.py`, `workers/arq/config.py`, `notifications/registry.py`, and `streams/__init__.py`.
+
 ## [0.3.0] - 2026-04-05
 
 ### Changed

codex_platform-0.5.0/CLAUDE.md

@@ -0,0 +1,9 @@
+## graphify
+
+This component is part of a larger project. It uses a global knowledge graph located at the workspace root (`../graphify-out/`).
+
+Rules:
+- Before answering architecture or codebase questions, read the global report at **`../graphify-out/GRAPH_REPORT.md`** for god nodes and community structure.
+- If `../graphify-out/wiki/index.md` exists, navigate it instead of reading raw files.
+- For cross-module questions, prefer `graphify query`, `graphify path`, or `graphify explain` (run from root or via MCP) over grep.
+- After modifying code files in this session, run `graphify update .` from the **workspace root** to keep the global graph current.

{codex_platform-0.3.0 → codex_platform-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-platform
-Version: 0.3.0
+Version: 0.5.0
 Summary: Modular async infrastructure (Redis, Streams, ARQ, Notifications) built for Codex, designed for independent use.
 Project-URL: Homepage, https://github.com/codexdlc/codex-platform
 Project-URL: Documentation, https://codexdlc.github.io/codex-platform/

codex_platform-0.5.0/docs/dev/messaging/00_overview.md

@@ -0,0 +1,157 @@
+# `codex-platform.messaging` — Overview
+
+> **Status**: Phase 0 design document. The package described here is the
+> rename + expansion of the existing `codex_platform.notifications` package.
+> No code has been written yet; this file is the contract that drives Phase 2
+> of the migration roadmap.
+
+## Purpose
+
+`codex_platform.messaging` is the **framework-agnostic core** of the codex
+messaging stack. It provides the building blocks that any host framework
+(Django, FastAPI, a bare ARQ worker) can compose to send transactional
+emails, deliver multi-channel notifications, render templates, and route
+inbound replies to a thread.
+
+It deliberately does **not**:
+
+* import any web framework,
+* depend on a database,
+* know about HTTP request/response objects,
+* hold mutable global state beyond a registry of pluggable factories.
+
+If a piece of code needs Django, it does not belong here — it belongs in
+`codex_django.messaging`.
+
+## What lives here
+
+| Sub-package | Owns |
+|-------------|------|
+| `messaging.dto` | Pydantic DTOs that travel across process boundaries (Django ↔ worker, FastAPI ↔ worker). |
+| `messaging.channels` | `NotificationChannel` enum (`email`, `sms`, `telegram`, `whatsapp`). |
+| `messaging.clients` | Concrete protocol-conforming channel implementations (SMTP, SendGrid HTTP, future Telegram). |
+| `messaging.delivery` | Adapters that move a payload to a runtime: ARQ queue, in-process direct send. |
+| `messaging.orchestrator` | `BaseDeliveryOrchestrator` — fallback chain over a list of `DeliveryChannel`s. |
+| `messaging.registry` | `ChannelRegistry` — config-driven factory list. |
+| `messaging.renderer` | Optional Jinja2 renderer for worker-side template mode. |
+| `messaging.threading` | Helpers for RFC 5322 `Message-ID`, `In-Reply-To`, `References` and the neutral `X-Codex-Thread-Key` header. |
+| `messaging.audience` | `AudienceBuilder` protocol + `RecipientDraft` DTO for mass-mail batching. |
+| `messaging.campaigns` | `CampaignDispatcher` protocol + `CampaignBatchDTO` schema for the worker callback contract. |
+| `messaging.workers_contract` | Frozen schema versions and task-name constants the worker must keep in sync with. |
+
+## Layer diagram
+
+```
+                ┌──────────────────────────────┐
+                │ codex_core                    │
+                │  - BaseDTO (Pydantic)         │
+                │  - settings primitives        │
+                └──────────────┬───────────────┘
+                               │
+                ┌──────────────▼───────────────┐
+                │ codex_platform.messaging      │  ← THIS PACKAGE
+                │  (framework-agnostic)         │
+                └──────┬──────────────────┬─────┘
+                       │                  │
+       ┌───────────────▼─────┐  ┌─────────▼────────────┐
+       │ codex_django.       │  │ future:               │
+       │   messaging         │  │ codex_fastapi.        │
+       │ (Django adapters)   │  │   messaging           │
+       └─────────────────────┘  └──────────────────────┘
+                       │                  │
+                       └────────┬─────────┘
+                                │
+                ┌───────────────▼───────────────┐
+                │ project apps (lily_backend, …)│
+                └───────────────────────────────┘
+```
+
+## FastAPI-readiness contract
+
+The whole package must satisfy the following invariants. CI should enforce
+each of them with a static check:
+
+1. **No `import django`** anywhere under `src/codex_platform/messaging/`.
+2. **No transitive Django pull-in.** All channel/orchestrator/renderer code
+   uses `pydantic`, `arq`, `aiosmtplib`, `httpx`, `jinja2` (optional). No
+   adapter from another framework is imported eagerly.
+3. **All cross-process payloads are Pydantic DTOs** that subclass
+   `codex_core.core.BaseDTO`. Plain dicts may be used internally between
+   `messaging.delivery.*.enqueue()` and the worker, but every dict must
+   round-trip through a DTO at both ends.
+4. **All time fields are timezone-aware ISO-8601 strings** in DTOs. The
+   package never assumes a global timezone; the host application is
+   responsible for the wall-clock interpretation.
+5. **All registry entries are functions, not module-level imports.** The
+   registry calls factories lazily so an unconfigured channel does not
+   force a missing dependency import.
+
+## Two delivery modes (kept from `notifications`, made first-class)
+
+### Mode 1 — Worker-rendered (`TemplateNotificationDTO`)
+
+The host pushes a `template_name` + a Redis context key. The worker fetches
+the context, renders the template via Jinja2, then sends.
+
+* **Use when**: content depends on data that may change between enqueue
+  and send (booking time, reschedule), or when you want the worker to
+  share a single template directory across many hosts.
+* **Cost**: worker must have Jinja2 installed and a templates directory.
+
+### Mode 2 — Pre-rendered (`RenderedNotificationDTO`)
+
+The host renders HTML/text in its own template engine and passes the
+result on the wire. The worker only delivers.
+
+* **Use when**: the host has Django templates (i18n, request context,
+  CMS blocks) and you want exactly the same layout in send and preview.
+* **Cost**: payload is larger; you cannot mutate the rendered content
+  after enqueue.
+
+The orchestrator and channels do not care which mode produced the
+payload — they only see the resolved `html_content` / `text_content`
+fields on the DTO.
+
+## What this package does NOT decide
+
+* The shape of recipients, threads, campaigns, or message bodies in a
+  database. That is owned by `codex_django.messaging` (abstract models)
+  and the project (concrete models).
+* The cabinet / admin UI. That is owned by `codex_django.messaging` plus
+  project templates.
+* Audience selection logic (segmentation, GDPR consent, etc.). The
+  package only declares the `AudienceBuilder` protocol; concrete query
+  logic belongs in projects.
+* Provider-specific identity (sender name, reply-to). Those flow into
+  the channel via DTO fields and configuration; the package never
+  hard-codes them.
+
+## Open design points (resolved during doc review)
+
+Listed here so future maintainers can find the rationale:
+
+1. **Decorator API for content builders.** Two competing styles —
+   split (`@email_template` / `@email_rendered`) and unified
+   (`@notification(mode=…)`) — are documented in
+   `codex-django/docs/dev/messaging/03_decorators.md`. The platform
+   layer is agnostic; it sees only the DTO that comes out the other end.
+2. **Inbound transport.** Currently out of scope. The package exposes
+   `messaging.threading` so that any inbound transport (IMAP poller,
+   webhook, S3 bucket) can attach incoming mail to an existing thread
+   using the same headers used on outbound. Concrete inbound transports
+   are deferred.
+3. **Provider-key storage.** `codex_platform.messaging` never reads
+   secrets. SendGrid API key, SMTP password, etc. flow in via the host
+   config object. The host MUST keep secrets out of the database; see
+   `codex-django/docs/dev/messaging/05_settings_migration.md`.
+
+## Referenced documents
+
+* `01_core_dtos_and_protocols.md` — DTO and protocol catalog.
+* `02_channels_and_registry.md` — `DeliveryChannel`, `ChannelRegistry`.
+* `03_renderer_and_templates.md` — Jinja2 renderer + template-key
+  conventions.
+* `04_threading_and_headers.md` — RFC 5322 helpers and the
+  `X-Codex-Thread-Key` neutral header.
+* `05_workers_contract.md` — task names, payload schema versions.
+* `06_migration_from_notifications.md` — concrete rename + alias plan.

codex_platform-0.5.0/docs/dev/messaging/01_core_dtos_and_protocols.md

@@ -0,0 +1,267 @@
+# Core DTOs and Protocols
+
+This document is the canonical reference for every type that crosses a
+process boundary in the `codex_platform.messaging` stack. All DTOs inherit
+from `codex_core.core.BaseDTO` (Pydantic v2 with PII auto-masking in
+`__repr__`). All protocols are `typing.Protocol` so that adapters can be
+implemented in any framework without import gymnastics.
+
+## 1. `messaging.channels`
+
+```python
+class NotificationChannel(StrEnum):
+    EMAIL = "email"
+    TELEGRAM = "telegram"
+    SMS = "sms"
+    WHATSAPP = "whatsapp"
+```
+
+* `StrEnum` (Python 3.11+) so JSON round-trip is implicit.
+* New channels MUST be added to this enum before being used in any DTO;
+  the worker validates payload `channels` against the enum.
+
+## 2. `messaging.dto`
+
+### `NotificationRecipient`
+
+```python
+class NotificationRecipient(BaseDTO):
+    email: str | None = None
+    phone: str | None = None
+```
+
+* Both fields are optional but the orchestrator requires at least one to
+  resolve a destination address; a payload with neither will be logged
+  and dropped.
+* PII is masked in `__repr__` by `BaseDTO`.
+
+### `NotificationPayloadDTO` (base)
+
+```python
+class NotificationPayloadDTO(BaseDTO):
+    notification_id: str
+    recipient: NotificationRecipient
+    channels: list[NotificationChannel] = [NotificationChannel.EMAIL]
+    event_type: str | None = None
+    subject: str | None = None
+```
+
+* `notification_id` is opaque to the platform and is the **only** primary
+  key used to correlate worker callbacks with host-side records. Hosts
+  MUST assign an idempotent value (UUID or content hash) — never an
+  auto-incremented database PK.
+* `event_type` is a free-form domain key (`booking.confirmed`,
+  `conversations.compose_new`, …). The worker emits it back on retry
+  callbacks so the host can route delivery status updates to the right
+  feature.
+* `subject` is set by the host — the platform never derives it.
+
+### `TemplateNotificationDTO`
+
+```python
+class TemplateNotificationDTO(NotificationPayloadDTO):
+    template_name: str
+    context_key: str
+```
+
+* `template_name` is a path relative to the worker's templates directory
+  (e.g. `booking/bk_confirmation.html`). The platform itself does not
+  validate the path; the renderer raises `TemplateNotFound` on send.
+* `context_key` is a Redis key where a JSON-serialized context is stored.
+  Storing context out-of-band keeps the queue payload small and lets the
+  host update context after enqueue (reschedule a booking, re-render).
+
+### `RenderedNotificationDTO`
+
+```python
+class RenderedNotificationDTO(NotificationPayloadDTO):
+    html_content: str
+    text_content: str | None = None
+```
+
+* `html_content` is the final HTML to be delivered. The orchestrator
+  passes it verbatim to the channel.
+* `text_content` is the optional plain-text alternative. If absent, the
+  channel emits a generic fallback string ("Please enable HTML to view
+  this email.").
+
+### `ThreadHeadersDTO` *(new in messaging)*
+
+Promoted out of the worker's `_mailbox_headers()` helper into a real
+DTO so it can be composed with both notification DTOs:
+
+```python
+class ThreadHeadersDTO(BaseDTO):
+    message_id: str             # RFC 5322 Message-ID, host-issued
+    in_reply_to: str | None = None
+    references: list[str] = []
+    thread_key: str             # opaque per-thread token (was X-Lily-Thread-Key)
+    reply_match_token: str | None = None  # token routed back via Reply-To
+```
+
+The two notification DTOs gain an optional `headers: ThreadHeadersDTO | None`
+field. The SMTP / SendGrid channels read it and emit the corresponding
+RFC 5322 headers; channels that don't support headers (SMS, Telegram)
+ignore the field.
+
+### `CampaignBatchDTO` *(new in messaging)*
+
+Replaces the ad-hoc batch payload that
+`features/conversations/tasks/campaign_tasks.py` consumes today.
+
+```python
+class CampaignRecipientDraft(BaseDTO):
+    recipient_id: str
+    email: str
+    first_name: str = ""
+    last_name: str = ""
+    locale: str = "de"
+    unsubscribe_token: str | None = None
+
+class CampaignBatchDTO(BaseDTO):
+    campaign_id: str
+    template_name: str | None = None
+    html_content: str | None = None
+    subject: str
+    recipients: list[CampaignRecipientDraft]
+    base_context: dict[str, Any] = {}     # site_url, logo_url, etc.
+    callback_url: str                     # where the worker reports recipient status
+    callback_token: str                   # opaque, host-issued
+```
+
+* Either `template_name` (template mode) or `html_content` (rendered
+  mode) MUST be set — the worker rejects a batch with both or neither.
+* `callback_url` + `callback_token` decouple the worker from any
+  framework: the worker only knows where to POST. The host validates
+  the token (currently `OPS_WORKER_API_KEY` scoped to
+  `"campaigns.worker"` in lily, see `system/api/auth.py:12-18`).
+
+## 3. `messaging.interfaces`
+
+### `ContentProvider`
+
+```python
+class ContentProvider(Protocol):
+    def get_text(self, key: str) -> str | None: ...
+```
+
+Used by selectors to translate subject / body keys to localized strings.
+The Django adapter wraps `django.utils.translation`; a FastAPI adapter
+will wrap `babel`.
+
+### `ContentCacheAdapter`
+
+```python
+class ContentCacheAdapter(Protocol):
+    def get_cached_value(self, key: str) -> str | None: ...
+    def set_cached_value(self, key: str, value: str, timeout: int) -> None: ...
+```
+
+The platform never imports a cache backend directly. The Django adapter
+wraps `django.core.cache`; a FastAPI adapter will wrap `redis-py` or
+`aiocache`.
+
+## 4. `messaging.orchestrator`
+
+### `DeliveryChannel`
+
+```python
+class DeliveryChannel(Protocol):
+    async def send(
+        self,
+        to: str,
+        subject: str,
+        html_content: str | None,
+        text_content: str | None,
+    ) -> bool: ...
+    def is_available(self) -> bool: ...
+```
+
+* Implementations: `AsyncEmailClient` (SMTP), `SendGridChannel` (HTTP),
+  future `TelegramChannel`, `TwilioSmsChannel`.
+* `is_available()` MUST be cheap — it is called on every dispatch to
+  decide whether to skip the channel.
+* `send()` returns `False` for *logical* failures (recipient rejected,
+  rate-limit exceeded). It MUST raise on infrastructure failures so the
+  orchestrator can fall through to the next channel.
+
+> **Open question**: the current signature does not accept
+> `ThreadHeadersDTO`. The migration adds an optional `headers` keyword
+> argument. Channels that don't support headers (SMS, Telegram) ignore
+> it. Documented in `02_channels_and_registry.md`.
+
+### `BaseDeliveryOrchestrator`
+
+```python
+class BaseDeliveryOrchestrator:
+    def __init__(self, channels: list[DeliveryChannel]) -> None: ...
+    async def deliver(self, payload: NotificationPayloadDTO) -> bool: ...
+```
+
+* Pure: only logs and tries channels in order.
+* Stops on the first `True` return.
+* Logs and falls through on any raised exception.
+* Returns `False` if every channel is exhausted.
+* Does **not** persist anything — the host (or `EmailLog` writer in the
+  Django adapter) is responsible for delivery audit.
+
+## 5. `messaging.delivery`
+
+### `NotificationAdapter`
+
+```python
+class NotificationAdapter(Protocol):
+    def enqueue(self, task_name: str, payload: dict[str, Any]) -> str | None: ...
+```
+
+* Implementations: `ArqNotificationAdapter`, `DirectNotificationAdapter`.
+* Returns a job/task ID when the transport supports tracking; `None`
+  otherwise.
+* Infrastructure errors propagate.
+
+## 6. `messaging.audience` *(new in messaging)*
+
+### `AudienceBuilder` Protocol
+
+```python
+class AudienceBuilder(Protocol):
+    def count(self, audience_filter: dict[str, Any]) -> int: ...
+    def materialize(
+        self, audience_filter: dict[str, Any]
+    ) -> Iterable[CampaignRecipientDraft]: ...
+```
+
+* The filter is a JSON-serializable dict — its shape is project-defined
+  (lily uses `consent_marketing`, `locales`, `service_ids`,
+  `has_appointment_since`).
+* `materialize()` MUST stream — the Django implementation already uses
+  `iterator(chunk_size=500)`. The platform documents this expectation;
+  it is not enforceable in a Protocol.
+
+### `CampaignDispatcher` Protocol
+
+```python
+class CampaignDispatcher(Protocol):
+    def enqueue_batch(self, batch: CampaignBatchDTO) -> str: ...
+```
+
+The lily implementation today (`features/conversations/campaigns/dispatcher.py`)
+returns the ARQ `job_id`. Documented identical here.
+
+## Migration table
+
+| Old (`notifications`) | New (`messaging`) | Notes |
+|-----------------------|-------------------|-------|
+| `NotificationPayloadDTO` | `NotificationPayloadDTO` | Unchanged. |
+| `TemplateNotificationDTO` | `TemplateNotificationDTO` | Unchanged. |
+| `RenderedNotificationDTO` | `RenderedNotificationDTO` | Unchanged. |
+| `NotificationRecipient` | `NotificationRecipient` | Unchanged. |
+| `NotificationChannel` | `NotificationChannel` | Unchanged. |
+| `DeliveryChannel` | `DeliveryChannel` | Adds optional `headers` kwarg. |
+| `ContentProvider` / `ContentCacheAdapter` | unchanged | Unchanged. |
+| *(new)* | `ThreadHeadersDTO` | Promoted from worker helper. |
+| *(new)* | `CampaignRecipientDraft`, `CampaignBatchDTO` | Currently lives in lily. |
+| *(new)* | `AudienceBuilder`, `CampaignDispatcher` | Currently lives in lily. |
+
+The legacy import path `codex_platform.notifications.<X>` MUST keep
+working for at least one minor release; see `06_migration_from_notifications.md`.

codex_platform-0.5.0/docs/dev/messaging/02_channels_and_registry.md

@@ -0,0 +1,166 @@
+# Channels and Channel Registry
+
+## What a "channel" is
+
+A `DeliveryChannel` is a single provider-specific transport: SMTP,
+SendGrid HTTP API, Twilio SMS, Telegram bot, etc. Channels are
+stateless from the orchestrator's perspective — they hold connection
+config but no per-request state.
+
+The orchestrator (`BaseDeliveryOrchestrator`) does not know how many
+channels exist or in which order they should be tried — that is the
+**registry's** job.
+
+## Channel contract (final)
+
+```python
+class DeliveryChannel(Protocol):
+    async def send(
+        self,
+        to: str,
+        subject: str,
+        html_content: str | None,
+        text_content: str | None,
+        headers: ThreadHeadersDTO | None = None,   # new
+    ) -> bool: ...
+
+    def is_available(self) -> bool: ...
+```
+
+* **Returns `True`** — the message was accepted by the provider.
+* **Returns `False`** — recipient was rejected for a *logical* reason
+  (suppression list, invalid address). The orchestrator stops; the next
+  channel will not be tried.
+* **Raises** — infrastructure error (DNS, TLS, connection refused, 5xx
+  from a HTTP API). The orchestrator logs and tries the next channel.
+* **`headers` ignored** when the channel cannot carry RFC 5322 headers
+  (SMS, Telegram, WhatsApp). The orchestrator never inspects the field.
+
+## Built-in channels
+
+### `clients.smtp.AsyncEmailClient`
+
+* Existing implementation — covered in
+  `codex_platform/notifications/clients/smtp.py`.
+* `is_available()` returns `True` iff `smtp_host` is set and not
+  `localhost`.
+* Constructor takes raw config: `smtp_host`, `smtp_port`, `smtp_user`,
+  `smtp_password`, `smtp_from_email`, `smtp_use_tls`.
+* Uses `aiosmtplib`. SSL/STARTTLS auto-detected from port (465 → SSL,
+  587 → STARTTLS).
+* **Migration delta**: gain `smtp_from_name` parameter. Today the
+  rendered `From:` header uses the email-only form because the field
+  does not exist. The host is responsible for passing a non-empty
+  display name (typically `EmailSettings.email_sender_name`).
+
+### `clients.sendgrid.SendGridChannel` *(new, promoted from worker)*
+
+* Today the SendGrid logic lives in
+  `src/workers/core/base_module/email_client.py:103-129` and is
+  hard-wired to `"LILY Beauty Salon"` as the sender name (line 113).
+* Promotion plan:
+  1. Move the HTTP POST + payload assembly into a new
+     `clients/sendgrid.py` module.
+  2. Add it as a registered channel in `ChannelRegistry`. The factory
+     returns `None` when `SENDGRID_API_KEY` is missing.
+  3. Read sender name from the constructor argument; never hard-code.
+
+### Future channels
+
+The package only documents the contract. Concrete `TelegramChannel`,
+`TwilioSmsChannel`, etc. live in `codex_platform.messaging.clients.*`
+when added. Each new channel MUST:
+
+1. Implement `DeliveryChannel`.
+2. Provide a `register_*_channel(registry, config)` helper.
+3. Add an entry to the migration table in
+   `01_core_dtos_and_protocols.md`.
+
+## `ChannelRegistry` (unchanged behavior, documented expectations)
+
+```python
+class ChannelRegistry:
+    def register(
+        self,
+        name: str,
+        factory: Callable[[Any], DeliveryChannel | None],
+    ) -> None: ...
+
+    def build_channels(self, config: Any) -> list[DeliveryChannel]: ...
+```
+
+* `name` is for logging only; duplicates are allowed but the registry
+  emits a `WARNING`.
+* The factory MUST return `None` (not raise) when the channel cannot be
+  configured (missing API key, missing host, etc.). The registry treats
+  exceptions raised inside the factory as registration failures and
+  logs them via `log.exception`.
+* `build_channels(config)` calls every factory in registration order
+  and includes channels that are both non-`None` and report
+  `is_available() == True`. The result is the ordered list passed to
+  `BaseDeliveryOrchestrator`.
+
+### Recommended registration order
+
+```python
+registry = ChannelRegistry()
+registry.register("smtp",      smtp_factory)       # primary
+registry.register("sendgrid",  sendgrid_factory)   # fallback
+# (future) registry.register("amazon_ses", ses_factory)
+```
+
+The orchestrator stops on the first `True` so the **primary** channel
+must be the lowest-cost / highest-trust transport (typically the
+project's own SMTP). Fallbacks come after.
+
+## Fallback semantics — explicit
+
+The orchestrator currently treats any thrown exception as
+"try next channel". That is the right default, but channels MUST be
+careful to:
+
+* Raise for recoverable infrastructure failures (network, TLS, 5xx).
+* Return `False` for permanent rejections (invalid recipient,
+  suppression). Returning `False` stops the chain — this is correct
+  because retrying with a fallback would just re-deliver to a rejected
+  address.
+* **Never** silently swallow exceptions. The orchestrator's audit log
+  is the only signal the host has that the chain failed.
+
+## SendGrid hardcoded-sender bug — explicit fix
+
+`src/workers/core/base_module/email_client.py:113` reads:
+
+```python
+"from": {"email": from_email, "name": "LILY Beauty Salon"}
+```
+
+The migration moves this code into `clients/sendgrid.py` and accepts
+`from_name` via constructor:
+
+```python
+class SendGridChannel:
+    def __init__(self, *, api_key: str, from_email: str, from_name: str = "") -> None:
+        self.api_key = api_key
+        self.from_email = from_email
+        self.from_name = from_name or from_email.split("@")[0]
+```
+
+The host (`codex_django.messaging.adapters.sendgrid_factory`) reads
+`EmailSettings.email_sender_name` and passes it to the factory. Once
+the migration lands, no project-specific string ever leaks into the
+platform layer.
+
+## Anti-patterns
+
+The following patterns are forbidden in any concrete channel:
+
+1. **Reading config off a global `django.conf.settings`** — channels
+   take all config via constructor.
+2. **Mutating the input DTO** — `send()` is read-only on the payload.
+3. **Holding a long-lived connection in the constructor** — channels
+   are created per-worker-startup; if a connection is needed, lazy-init
+   it on the first `send()` call. SMTP currently follows this rule via
+   `aiosmtplib.send` per call.
+4. **Logging the full HTML body or recipient PII** — the
+   `BaseDTO.__repr__` masks PII; channels MUST not bypass it.