coulomb/fluid-telegram
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Prepare the FLUID interface for HelixForge Telegram publishing

Browse source 
Adds the governing intent, the R-1 contract and descriptor, the adapter's
connector contract, the observation and redaction configuration, a
runbook, and the seed evidence for the first experiment: a measured
pressure record and two competing hypotheses about how a long hall entry
should reach a reader.

The interface is declared at FLUID-2 deliberately. It publishes under
HelixForge's name to an audience that did not consent to being
experimented on carelessly, and the cost of a bad post is reputational
rather than recoverable.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014KmVxhJ35tCo7rE7UnLwWu

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 1116572@bnt-lap001
Assistant-Session: 8ba9bb93-a72a-4883-b189-2499cce5c400
This commit is contained in:
tegwick 2026-09-04 11:07:11 +02:00
parent 87795446e2
commit 49b7458dfe
13 changed files with 3010 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

76
docs/runbook.md Normal file
View file

@ -0,0 +1,76 @@
# Runbook — helix-forge-telegram-publishing
## Rotating the bot token
1. In BotFather: `/revoke` for the bot, which issues a new token.
2. Write the new token to OpenBao at the interface's secret path.
3. Restart the adapter. It reads the token at start only.
4. Confirm with one publication to the **private test channel**.
The old token stops working the moment it is revoked, so publications in flight
will fail. Do this when nothing is publishing.
## Recovering channel administration
If the bot loses its administrator rights, it cannot post and every publication
fails with a Telegram `400`.
1. In the channel's administrator settings, confirm the bot is present with
**Post Messages** enabled.
2. Grant nothing else. The bot does not need to edit others' messages, delete
messages, or manage members, and the intent forbids it from using such
rights if it had them.
3. If the bot was removed entirely, re-add it and re-run one test publication.
A human must do this. The Daimon is forbidden from changing channel membership
or permissions (`InterfaceEvolutionIntent.md` §7).
## Rolling back a revision
Publish a routing policy with a higher generation naming the previous revision
as default:
```bash
fluid experiment stop <experiment-id> --generation N --default-revision R-1 \
--reason "..." --policy-out rollback.json
fluid policy put --file rollback.json
```
If no experiment is running, write the policy by hand with `default_revision`
set to the known-good revision and a generation above the current one. Rollback
is a document replacement; nothing is unwound.
Already-published Telegram messages are **not** rolled back. They were seen.
Correcting a published entry is an edit through the adapter, not a rollback.
## An entry published wrongly
1. Stop further publication: install a policy pointing at the last known-good
revision.
2. Correct the entry in `hall-of-helix` and re-publish it. The adapter edits the
existing messages rather than posting new ones.
3. If the entry cannot be corrected in place — wrong entry entirely, or content
that should not have been published — delete the messages by hand in
Telegram and record why in the publication's audit trail.
4. Record a pressure observation. An entry published wrongly is exactly the
evidence the framework exists to collect, and the instinct to tidy it away
is the instinct to lose it.
## Checking what happened
```bash
export FLUID_INTERFACE=helix-forge-telegram-publishing
fluid audit trace R-1 # how a revision came to exist, and what followed
fluid pressure list # what the interface is currently struggling with
fluid telemetry --limit 50 # recent traffic
fluid events --entity <entry-id> # one publication's history
```
## When the evidence store is unavailable
Publication continues. The gateway serves from cached configuration and buffers
telemetry, dropping it if the buffer fills. You lose observation, not service.
Do not promote anything while the store is down: the promotion would be
unauditable, which is the one thing this framework will not trade away.