git:20260716.fcea216 to git:20260724.126dedd

# CLAUDE.md - apps/dispatcher

The Slack ingestion edge: Bolt for Python in Socket Mode. Full behavior spec

lives in `apps/dispatcher/README.md`; this file is the enforceable-rule

summary.

## Load-bearing invariants

- **Scope discipline: ack, dedupe, placeholder, enqueue -- nothing else.**

Routing, the finish-race, steer/interrupt, and run orchestration belong to

the worker (`apps/worker`). If you find yourself adding any

decision about *how* a message gets answered, that decision belongs one

layer up -- stop and move it, don't grow the dispatcher's scope.

- **The queued-turn shape is the frozen `QueuedTurn` contract in `packages/`.**

The dispatcher is the producer, but the payload it enqueues was promoted out

of the dispatcher into the channel-neutral `aci_protocol.QueuedTurn` (issue

#7). That shared contract is the Pydantic source of truth guarded by the

schema-compat gate, so the Python producer and the Rust/TS consumers compile

against one shape instead of a hand-mirrored dispatcher-local model. Do not

reintroduce a dispatcher-owned payload model. The producer-owns-the-shape

principle still governs any *new* dispatcher-only field: land a contract

change in `packages/aci-protocol` via an issue/PR first, exactly as #7 did.

- **Idempotency key is the Slack event id, not the message content.** Dedupe

is `SET <dedupe_prefix><event_id> 1 NX EX <ttl>` in Valkey -- O(1), TTL-bounded,

no scan. Order is always claim -> post placeholder -> `XADD`, so a

duplicate delivery can never produce a second placeholder. Do not reorder

these three steps.

- **The queue seam is one `payload` field, not a multi-field Stream entry.**

Each Stream entry carries a single `payload` field holding the

`QueuedTurn` JSON. This lets fields be added to the payload without

reshaping the Stream schema itself -- do not add a second top-level Stream

field for a new piece of data; put it inside the JSON payload.

- **Reconnects are the supervisor's job, not the Slack client's.** The Bolt

socket client self-heals transient drops; `dispatcher.supervisor.Supervisor`

is the outer net for failures the client cannot recover from (connect

failures, unrecoverable exits) and owns graceful shutdown (`request_stop`

wired to SIGINT/SIGTERM). Do not add ad hoc retry logic elsewhere for a

connection failure -- it belongs in the supervisor's `BackoffPolicy`.

## Config surface

`DispatcherConfig()` (a `pydantic_settings.BaseSettings`) reads `SLACK_APP_TOKEN`,

and the backoff tunables. Full table in `apps/dispatcher/README.md`.

## Verify (Slack-free)

```bash

docker compose -f compose.dev.yaml up -d valkey

uv run pytest apps/dispatcher/tests -q

```

Only the Slack Web API client and socket transport are faked. Stream and

dedupe assertions run against the real Valkey from `compose.dev.yaml`.

`tests/test_dispatch.py` drives Bolt's real `SocketModeHandler.handle` end to

end; `tests/test_queue.py` covers the seam and dedupe against real Valkey;

`tests/test_supervisor.py` covers backoff/reconnect/shutdown with a fake

connection. A new test that fakes Valkey instead of using the real one from

the compose stack does not meet this repo's testing bar (root AGENTS.md:

never mock Postgres/Valkey/Langfuse).