Three defects the first sweep left behind, each caught by a rule the guard did not yet have. Statuses. RULES.md gives three; the tree had 25 values, and the free-text ones were carrying progress. "Implemented (wiring landed)" and "Ratified (rev. 2e). Rev. 2e adds the OpenTaskByPR lookup. Rev. 2d revised section 10..." were both changelogs living in the one field the other rules exempt. Every PRD now declares Draft, Approved or Finalised and nothing else; five that declared nothing now declare one. A revision number moves to **Revision:**, a pointer to the authoritative document to **Authority:**, and what a past revision changed to git. CLAUDE.md's citation of state-store-contract rev. 2e still resolves. Stale cross-references. "Supersedes the 2026-09-03 open question", "this bullet previously said", "an earlier draft of this document claimed" all point at text the reader cannot see, because it was replaced. A supersede marker survives only when it names a file, a section or a symbol that can be found. Temporal hedges. 100 uses of today, currently and right now across 31 files. Each dates its sentence to the day it was written: "[notify] today is one webhook URL, read in one place" stops being true the moment this design lands, while still reading as the premise it rests on. The header-field exemption was also too wide. "**Date:** 2026-09-03, Channel resolved 2026-09-22" smuggled a dated status into the one line the rules did not read; the exemption is now a Date holding only a date and a Status holding only one of the three.
5.8 KiB
Messaging Service boundary and transport design
Status: Approved
Revision: 1
Date: 2026-09-19
Beads issue: archie-core-8cda.6.1
Parent: service-decomposition.md
Prerequisites: Gateway contract extraction (Phase 1), State Store extraction (Phase 2), UI extraction (Phase 3)
This document is the authoritative specification for Phase 4: Messaging Service extraction. It fixes the process boundary, configuration ownership, client contracts, security posture, readiness behavior, channel invariants, and deletion criteria required by archie-core-8cda.6 and its child tasks.
Decision
The Messaging Service (cmd/archie-messaging, composed via internal/app/archiemessaging) owns external channel connections (Telegram, email, webhook) and dispatches inbound messages and commands to the standalone Gateway Service over gRPC via messaging.ChatContract.
It is a peer service to the UI Service and the daemon:
- It serves external chat participants across configured communication platforms.
- It consumes Gateway's
messaging.ChatContractexclusively for chat turn execution, streaming, session queries, cancellation, persona selection, and task control actions. - It holds no direct database connections (
*store.Storeor SQLite), owns no LLM execution or model provider credentials, and has no dependency on the daemon runtime or the UI HTTP server.
Boundary and Ownership
| Concern | Messaging Service owns | Messaging Service consumes | Messaging Service must not own or link |
|---|---|---|---|
| Channel transports | Telegram bot long-polling, Email IMAP/SMTP loops, Inbound Webhook HTTP listener | Gateway ChatContract |
Direct LLM providers, model runtimes, tokenizer libraries |
| Turn dispatch | Inbound message packaging, typing indicators, live streaming updates | ChatContract.Route, ChatContract.Stream |
gateway.Router, runtime.Runtime, agent prompt builders |
| Sessions & History | Platform-to-session key mapping, conversation thread ID translation | ChatContract.GetSession, RecentMessages, RecentTurns |
*store.Store, SessionStore SQLite handles, direct database files |
| Control & Actions | Platform command parsing (/status, /tasks, /cancel, /stop, /persona) |
ChatContract.Snapshot, ApplyTaskAction, Cancel, SetPersona |
daemon.Daemon, workflow execution engine, worktree operations |
| Task Approvals | Channel interactive keyboards, approval callbacks | ChatContract.ApplyTaskAction |
Direct task status mutations, forge comment posters |
| Configuration | Platform bot tokens, allowed sender/user IDs, webhook listen ports | [chat.*] channel configs, Gateway target/token |
config.Holder, forge tokens, repo configs, agent container specs |
| Readiness | Messaging process liveness, channel connectivity, Gateway probe | Gateway ChatContract.Snapshot |
Internal daemon subsystem probes |
Target Service Shape
- Binary entry point:
cmd/archie-messaging/main.goparses CLI flags (-config,-config-overlay,-gateway-target,-gateway-token) and hands execution tointernal/app/archiemessaging.Run. - Application composition:
internal/app/archiemessaging/wires:- Config loading scoped strictly to
[chat.*]and[services.gateway]. - Secret resolution for channel credentials (e.g. Telegram bot token).
- Gateway gRPC client (
internal/infrastructure/gatewayrpc.Client). - Channel lifecycle managers (
internal/channels/status). - Channel instances (
internal/channels/telegram,email,webhook).
- Config loading scoped strictly to
- Turn and Stream Execution:
- Channels adapt inbound platform messages to
messaging.Inbound. - Streaming channels (Telegram) consume
ChatContract.Stream(ctx, inbound)which returns<-chan messaging.ChatEvent, mappingstarted,delta,tool,media,done, anderrorevents directly to live message frames. - Non-streaming channels (email, synchronous webhooks) consume
ChatContract.Route(ctx, inbound).
- Channels adapt inbound platform messages to
Load-Bearing Channel Invariants
The Messaging Service preserves existing invariants defined in AGENTS.md and channel documentation:
- Telegram long-polling: Must call
dropPendingUpdates(ctx, b)beforeb.Start(ctx)and on/restart. - Telegram command menus: Must register command menus simultaneously to
default,all_private_chats, andall_group_chatsviacommands.goto prevent menu shadowing. - No UI detour: Turns and task actions route directly to Gateway's
ChatContract; no HTTP request may ever be sent toarchie-uiorinternal/webui. - Sender Confinement: Telegram sender checks against
allowed_user_idsmust continue to fail closed before initiating any turn dispatch.
Configuration Ownership
cmd/archie-messaging reads only:
[services.gateway].targetand[services.gateway].target_token(or CLI flags).[chat.telegram](token, allowed user IDs).[chat.email](IMAP/SMTP host, ports, credentials).[chat.webhook](listen address, secret).[secrets](for resolving token secret references).
It does not read or decode [forge], [repos], [models], [providers], [runners], [containers], or [nats].
Deletion Gate and Verification
The extraction is guarded by cmd/archie-messaging/architecture_test.go, verifying that go list -deps ./cmd/archie-messaging links zero banned runtime packages:
modernc.org/sqliteandinternal/store(State Store)internal/daemon,internal/app/archied,internal/container,internal/worktree(Daemon runtime)internal/domain/workflow,internal/agentexec,internal/taskrun(Workflow engine)internal/forge,internal/forgerpc(Forge client)internal/gatewayruntime (onlyinternal/domain/messagingandinternal/infrastructure/gatewayrpcare permitted)internal/webui(Dashboard)