fluid-telegram/docs/adapter-contract.md

Telegram adapter — connector capability contract

The adapter is an ordinary HTTP service. fluid-core sits in front of it and asks nothing of it beyond the endpoints below, so it may be written in whatever suits the platform — grammY on Node is the obvious choice for the Telegram Bot API.

What the adapter owns

• Rendering a hall entry into Telegram's message forms.
• Talking to the Telegram Bot API.
• Custody of the bot token for the duration of a call.
• Idempotency: recognising an entry_id it has already published.

What the adapter must not do

• Create, rename or delete channels, groups or bots.
• Change membership, administrators or permissions.
• Post to any chat other than the one it is configured with.
• Edit entry content to make it fit. If an entry cannot be published faithfully, refuse it — that refusal is the pressure signal.
• Log, echo or forward the bot token, including in error messages.

Endpoints

Exactly the three operations in contracts/r1.openapi.yaml, at the same paths. The gateway validates requests against that contract before the adapter sees them, so the adapter may assume shape but must still assume hostile content.

Backend capability contract

Property	Value
Backend identity	Telegram Bot API (api.telegram.org)
Authentication	Bot token, injected at start from OpenBao; never in the image
Timeout	30s per Telegram call
Retry	On 429 only, honouring retry_after. Never retry a sendMessage that may have succeeded
Circuit breaker	5 consecutive failures opens for 60s
Rate limits	~20 messages/minute to a channel; ~30 requests/second overall
Error mapping	429 → 502 with retry_after preserved; 400 → 400; network failure → 502
Tenant propagation	None; single tenant

The idempotency requirement

POST /v1/hall-entries is idempotent on entry_id. The caller is automation that may be retried, and a duplicate hall entry in the channel is not something you can quietly undo — subscribers have already seen it.

The adapter keeps its own mapping from entry_id to the Telegram message ids it produced. On a repeat call it returns 200 with the existing publication rather than posting again. If the entry content has changed, it edits the existing messages rather than posting new ones.

This state is the adapter's, not fluid-core's. The evidence store records that a publication happened; the adapter records which Telegram messages implement it.

Rendering rules

Telegram formatting is not Markdown. Entry Markdown must be converted, not passed through.

Entry construct	Telegram
# Heading	Bold line
**bold**, _italic_	<b>, <i> in HTML parse mode
Fenced code	<pre>
Tables	Flattened to lines; Telegram has no table
Links	<a href>
Frontmatter	Stripped; display_name and recorded_at surfaced in the header

Anything the converter cannot represent faithfully must fail the publication rather than degrade it silently. entry_content_loss is a hard guardrail in both competing hypotheses, and it can only be honest if the adapter refuses rather than approximates.

Telemetry the adapter should emit

The gateway observes the request path already. The adapter adds what only it can see, by POSTing to the control plane's /control/v1/telemetry:

• messages_per_entry — how many Telegram messages one entry became.
• entry_content_loss — whether the conversion dropped anything.
• Telegram rate-limit encounters, as error events with class backend_failure.

It must not emit subscriber identity in any form. Engagement metrics (read_through_rate, reaction_rate) come from Telegram's channel statistics as aggregates, never per-reader.

Configuration

Variable	Meaning
TELEGRAM_BOT_TOKEN	Injected from OpenBao at start
TELEGRAM_CHANNEL_ID	The channel this adapter publishes to
FLUID_CONTROL_URL	Where to POST telemetry
HALL_BASE_URL	Base URL for links back to hall-of-helix

One adapter instance serves one channel. The private test channel and the public channel are separate instances with separate configuration, which is what keeps a test publication from reaching subscribers by accident.