fluid-telegram/InterfaceEvolutionIntent.md

# Interface Evolution Intent — helix-forge-telegram-publishing

**Document version:** IEI-1
**Status:** active
**Last reviewed:** 2026-09-04

---

## 1. Purpose

This document defines the evolutionary intent and governance boundary of the
FLUID interface that publishes HelixForge material to Telegram.

It is subordinate to `helix-forge/INTENT.md` and does not redefine HelixForge's
mission. It answers one question:

> How may this interface evolve while remaining faithful to the service it
> represents?

The FLUID Daimon must treat this document as a constitutional constraint.

---

## 2. Parent Intent

**Parent service/repository:** `helix-forge`

**Parent intent document:** `helix-forge/INTENT.md`

**Relevant parent mission:** HelixForge exists to turn intent into structure,
structure into capability, and capability into lasting progress. The Hall of
Helix is where that work's participants are acknowledged. This interface carries
those acknowledgements outward.

---

## 3. Interface Identity

**Interface name:** HelixForge Telegram Publishing

**Interface identifier:** `helix-forge-telegram-publishing`

**Current operational authority mode:** FLUID-2

FLUID-2 (Advisory) is a deliberate choice, not a starting point to be outgrown
on a schedule. The Daimon may observe, classify pressure and propose
adaptations. It may not generate implementations, run experiments unattended, or
promote anything. This interface 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.

Raising the mode is a governance change under §20, not an operational decision.

**Protocols / interface styles:** REST over HTTP (JSON)

---

## 4. Mission

### Mission statement

> Deliver composed channel posts to a Telegram audience reliably, verifiably,
> and without an unreviewed word ever reaching a subscriber.

The unit of publication is a **post**, not a hall entry. A post is short,
personal and written to travel; a hall entry is a considered first-person
account written for someone reading a repository. They are different pieces of
writing for different readers, and the second is the source of the first rather
than its content.

**Composition is not this interface's job.** Turning an entry into a post that
is condensed, entertaining and reach-optimized is a probabilistic, editorial
task. It happens upstream, before this interface is called. Two reasons, and
the first is architectural rather than stylistic:

1. `ArchitectureBlueprint.md` §48.1 names an LLM in the mandatory request path
   as an anti-pattern. An interface that composed on demand would be
   non-deterministic at exactly the point where determinism is the whole claim.
2. A composed post speaks about a named person's work in HelixForge's voice.
   That deserves a human read before it goes out, and a review step in the
   request path is a review step nobody performs.

### Success looks like

- A composed post reaches the channel without a human formatting it for
  Telegram.
- No post reaches a subscriber unreviewed.
- Every post is traceable to the entry it was written from, so a claim can be
  checked against what the person actually said.
- Publishing twice does not post twice.
- Engagement is attributable to the composition strategy that produced it, so
  the campaign can learn which writing travels.

---

## 5. Intended Consumers

### Primary consumer cohorts

| Cohort | Description | Importance | Notes |
|---|---|---|---|
| `hall-publishing-jobs` | Automation in `hall-of-helix` that publishes finished entries | High | The reason this interface exists |
| `helix-forge-agents` | Agent sessions announcing their own completed work | High | Highest-volume caller; supplies the richest pressure signal |
| `operators` | Humans publishing or correcting by hand | Medium | Low volume, high consequence |

### Secondary cohorts

| Cohort | Description | Importance | Notes |
|---|---|---|---|
| `telegram-subscribers` | Readers of the channel | Medium | Not API consumers; observed through engagement, never individually |

### Explicitly unsupported cohorts

- Third-party services outside the HelixForge boundary.
- Anonymous or unauthenticated callers.
- Anything seeking to publish content it did not author.

---

## 6. Capability Domain

### In scope

- Publishing composed posts to a Telegram channel (Canon PUB-01).
- Rendering a post into Telegram's message forms (Canon PUB-02, MED-02).
- Attaching a visual to a post (Canon MED-01).
- Publication state: what was published, when, as which message.
- Idempotency and correction of previously published posts.
- Recording the composition variant a post came from, and reporting engagement
  against it.
- Bot identity presentation (Canon BOT-01).

### Conditionally in scope

Capabilities that may be introduced if evidence justifies them:

- Scheduling a publication for a later time.
- Publishing other HelixForge material, such as release notes.
- A linked discussion group for comments.
- Publishing to more than one channel from one call.

### Out of scope

- **Composing post text from a source entry.** This belongs to the campaign
  that owns the editorial voice, not to the interface that delivers it. See §7.
- Inbound bot commands and conversation (Canon BOT-02, AGT-01). A second
  revision family may add this later; it is not this interface today.
- Payments and paid content (Canon PAY-*).
- Mini Apps (Canon APP-*).
- Moderation and membership management (Canon COM-02, COM-03).
- Any capability requiring a Telegram user account rather than a bot.

---

## 7. Responsibility Boundaries

### Responsibilities owned by this interface

- Representation: how a composed post becomes a Telegram message.
- Delivery: attaching the visual, the source link, the formatting.
- Validation: refusing a post that arrives unreviewed, unattributed, or in a
  form Telegram cannot carry.
- Routing: which revision serves a publication request.
- Idempotency: recognising a post it has already published.
- Attribution of engagement to composition variants.

### Responsibilities owned by backend systems

| Backend | Responsibility | Boundary |
|---|---|---|
| Telegram Bot API | Message delivery, channel state, subscriber identity | FLUID may request delivery. It may not assume a limit will move, and must treat platform constraints as fixed. |
| `pr-hall-of-helix` (planned) | Composing posts, the editorial voice, choosing what is worth publishing, obtaining subject consent | FLUID publishes what it is given and reports how it performed. It does not write, edit or select. |
| `hall-of-helix` | Entry content, its correctness, and whether it is finished | FLUID never reads or edits an entry. Its only knowledge of one is the id and URL a post cites. |
| OpenBao | Custody of the bot token | FLUID receives a credential. It never stores, logs or forwards one. |

Until `pr-hall-of-helix` exists, composition is done by hand as part of
`FT-WP-0001`. That is a temporary arrangement, and the boundary above is
written for the state it is heading toward rather than the state it is in — so
that the campaign, when it is extracted, finds the seam already cut.

### Explicit non-authority

The Daimon must not autonomously:

- create, rename or delete Telegram channels, groups or bots;
- change channel membership, administrators or permissions;
- read, rotate or re-scope the bot token;
- compose, rewrite, shorten or embellish post text;
- publish a post that carries no reviewer;
- publish to any chat other than those declared in the routing configuration;
- publish a post about a person who has not consented, on either basis in §15.

The last two matter most, and they are the reason composition sits outside this
interface. A post is a condensation written in HelixForge's voice about a named
person's work. It can flatter, it can misstate, and it can put a claim in
someone's mouth that their own entry never made — and in the audit trail an
unfaithful post looks exactly like a faithful one.

The defence is not that the composer is careful. It is that a human read the
post, the post names the entry it came from, and both are recorded before
anything reaches a subscriber.

---

## 8. Consumer Expectation Model

### Concepts consumers should naturally understand

- A **post** is the unit of publication, identified by its own post id.
- A post **cites** the hall entry it was written from; it is not that entry.
- Publishing is **idempotent** on the post id. A recomposition is a new post,
  because it is a different piece of writing about the same work.
- A **publication** has state: pending, published, failed, superseded.

### Interaction patterns considered natural

- Compose a post, have it reviewed, publish it, check its state.
- Re-publish the same post id after a correction and get the same message
  updated.
- List publications by composition variant to compare how they performed.

### Expectations that should be discouraged

- That Telegram formatting is Markdown. It is not, and posts that assume so
  will render wrongly.
- That a post appears instantly. Rate limits are real.
- That this interface will shorten an over-length post. It will refuse it. A
  composition that does not fit was not condensed, and deciding what to cut is
  the composer's judgement, not the deliverer's.
- That publishing a hall entry is possible. It is not: entries are sources, and
  posts are what this interface carries.

---

## 9. Optimization Preferences

### Active optimization regime

`ADOPTION` — the channel has no audience yet. Until it does, discoverability and
client utility matter more than efficiency, and cost is negligible at this
volume.

### Fitness priorities

| Dimension | Priority | Target / Constraint | Notes |
|---|---:|---|---|
| Correctness | High | No post published unreviewed or unattributed | Hard guardrail |
| Client utility | High | One call publishes one post | The reason the interface exists |
| Reliability | High | Publication succeeds or reports why | |
| Discoverability | High | A reader can reach the source entry | Drives the first experiment |
| Security | High | Token never leaves its custody | Hard guardrail |
| Compatibility | Medium | Versioned evolution | Few consumers, all internal |
| Simplicity | Medium | Prefer one publication concept | |
| Performance | Low | Publication is not latency-sensitive | Minutes are acceptable |
| Operational cost | Low | Negligible at this volume | |

### Automatic recommendation policy

`advisory` — the Daimon may recommend regime changes. It may not enact one.

---

## 10. Complexity Budget

### Complexity dimensions

| Dimension | Current | Preferred | Maximum | Scoring method |
|---|---:|---:|---:|---|
| Surface area (operations) | 3 | 4 | 8 | Count of declared operations |
| Concept count | 2 | 3 | 5 | post, publication |
| Parameter dimensionality | 4 | 6 | 12 | Declared parameters across operations |
| Semantic overlap | 0 | 0 | 1 | Operations meaning the same thing |
| Alternative-path count | 1 | 1 | 3 | Ways to achieve one outcome |
| Backend composition count | 1 | 2 | 3 | Backends per operation |
| Active revision count | 1 | 2 | 3 | Concurrently routable revisions |

### Complexity policy

- New capability should replace or generalize existing capability where
  reasonable.
- Semantic duplication is rejected unless justified in writing.
- Repeated special-case pressure triggers an abstraction review rather than
  another endpoint.
- A candidate exceeding a hard maximum must not be promoted.
- Presentation adaptations do not consume surface-area budget: they change how
  a post is delivered, not what the interface offers.
- Any candidate that would move composition inside this interface is rejected
  regardless of its complexity score. That boundary is not a budget question.

---

## 11. Compatibility Policy

### Compatibility posture

`VERSIONED`

### Rules

- Published revision semantics must not change silently.
- Breaking changes require a successor revision.
- Every consumer is internal and known, so a breaking change is a coordination
  problem rather than a public one — but it is still a successor revision.
- A change to how a post is *delivered* — visual placement, link style,
  formatting — is a presentation adaptation and does not break the contract,
  even though readers will notice it.

### Coexistence expectations

**Default maximum concurrent major revisions:** 2

**Default deprecation period:** 30 days after the last call from any consumer

**Migration assistance required:** yes — this interface has few enough consumers
that migration means telling their owners directly.

---

## 12. Revision and Experiment Policy

### Allowed concurrent exposure

| Revision class | Production traffic allowed? | Max share | Approval required? |
|---|---|---:|---|
| stable | yes | 100% | no |
| candidate | yes | 30% | yes, human |
| experiment | yes | 20% | yes, human |
| deprecated | yes | 100% | no |
| retired | no | 0% | n/a |

### Evolution velocity controls

The Daimon should slow or freeze promotion when:

- any entry has been published in a form that lost content;
- the bot has been rate-limited by Telegram in the last 24 hours;
- a security event has touched the token;
- an experiment is already running. Concurrency limit: 1.

The Daimon may accelerate experimentation when:

- the channel has more than 100 subscribers, giving experiments real power;
- the last three experiments completed without a guardrail breach.

**Note on experiment power.** At current volume — roughly one entry published
per week — an experiment needs months to reach a decidable sample. The evaluator
will report INCONCLUSIVE, and that is the correct answer. Do not shorten windows
to force a verdict.

---

## 13. Hypothesis Policy

### Minimum evidence for hypothesis creation

- At least 5 independent observations, or one unavoidable structural constraint.
- Observation window of at least 14 days for behavioural pressure.
- A structural constraint (a platform limit) may found a hypothesis immediately;
  it does not need repetition to be real.

### Required hypothesis fields

observation, explanation, proposed adaptation, expected outcome, measurement,
success criteria, guardrails, complexity impact, risk, expected learning value.

### Competing hypotheses

`encouraged` — the first pressure this interface faces has at least two
defensible answers, and choosing between them by argument rather than evidence
is exactly the habit FLUID exists to break.

Note the division of labour. Competitions about **delivery** — does a visual
help, does a link preview help — belong to this interface and are run here.
Competitions about **composition** — which editorial voice travels — belong to
the campaign, and are run on the per-variant engagement this interface reports.
Both are legitimate FLUID experiments; only the first is this interface's.

### Reach preference

Prefer the smallest sufficient adaptation. This interface is small enough that a
high-reach abstraction would be speculative; revisit when there are more than
three distinct kinds of pressure.

---

## 14. Adaptation Authority

| Adaptation class | Observe | Propose | Generate | Experiment | Promote |
|---|---:|---:|---:|---:|---:|
| Presentation | yes | yes | no | no | no |
| Contract | yes | yes | no | no | no |
| Composition | yes | yes | no | no | no |
| Implementation | yes | yes | no | no | no |
| Requirement escalation | yes | yes | yes | n/a | n/a |

Every `Generate`, `Experiment` and `Promote` column is `no`, which is what
FLUID-2 means. Requirement escalation is the exception: the Daimon may write a
structured backend requirement, because that artifact is a request to someone
else and carries no authority of its own.

### Absolute prohibitions

The Daimon must not autonomously:

- expand authorization scope;
- weaken tenant isolation;
- bypass deterministic security controls;
- reinterpret legal constraints;
- create backend authority it does not possess;
- publish anything to a live channel;
- alter the content of a hall entry.

---

## 15. Security Requirements

### Authentication

Consumers authenticate to the gateway. The bot token authenticates the adapter
to Telegram and is never a consumer credential.

### Authorization

Only declared cohorts may publish. `telegram-subscribers` is an observed
population, not a caller.

### Tenant isolation

Single tenant. The interface serves HelixForge and no one else.

### Subject consent

A post speaks publicly about a named person's work. Two bases are recognised:

- **standing** — the contributor agreed, when they took a seat in the hall,
  that HelixForge may write about that work publicly. This is the ordinary case
  and requires the agreement to actually exist, in `hall-of-helix/ENTRY.md`, and
  to be revocable.
- **explicit** — per-post approval from the subject. Required where the post
  makes a claim the entry does not, quotes the subject, or concerns work they
  have since asked not to be publicised.

`not-required` covers posts about the project itself with no personal subject.

A post carrying no basis is refused with 403. Absence of objection is not
consent, and the interface must not treat it as such.

### Data handling

Telegram user identity (Canon ID-01) must not enter the evidence store in any
form. Subscriber engagement is recorded only as aggregate counts, subject to the
cohort minimum size. This is a hard constraint: readers of a public channel have
not consented to individual observation, and a framework built to learn from
consumers must not quietly learn about audiences.

### Logging and provenance

Every publication records which post, which source entry, which reviewer, which
revision, which message, and which consumer asked. The bot token appears in no
log, error, telemetry event or evidence record.

Post *text* is retained in the publication record. It is what was said in
HelixForge's name, and an audit that could not reproduce it would be unable to
answer the only question that matters when a post is disputed.

### AI boundary

AI-generated changes must pass deterministic security policy, tests,
authorization validation and release controls. At FLUID-2 no AI-generated change
reaches this interface at all.

---

## 16. Quality Requirements

| Quality attribute | Requirement | Hard guardrail? |
|---|---|---:|
| Correctness | No post published without a reviewer and a cited source entry | yes |
| Consent | No post about a subject without a recorded basis | yes |
| Idempotency | Publishing a post twice yields one publication | yes |
| Availability | Best effort; publication may be retried | no |
| Reliability | A failed publication reports why and may be retried safely | yes |
| p95 latency | Under 10s excluding Telegram rate limiting | no |
| Error rate | Under 1% of publication attempts | yes |
| Security | Token never leaves custody | yes |
| Auditability | Every publication traceable to post text, source entry, reviewer, revision and caller | yes |
| Rollback | Any revision can be replaced by its predecessor within one policy generation | yes |

---

## 17. Economic Constraints

### Adaptive compute budget

| Budget | Limit |
|---|---:|
| analysis per day | 1 classification pass |
| hypothesis generation | manual only at FLUID-2 |
| candidate generation | not permitted at FLUID-2 |
| concurrent experiments | 1 |
| autonomous implementation effort | none |

### Cost policy

- Adaptive budget exhaustion must not affect publication.
- The dominant cost here is human attention, not compute. A hypothesis that
  needs more review time than the improvement is worth should be deferred.

---

## 18. Backend Capability Escalation

### Preferred requirement destination

Telegram platform constraints cannot be escalated to anyone — there is no
recipient. A requirement naming a Telegram limitation is recorded as evidence
for **boundary learning** instead, and the interface adapts around the
constraint or declares the demand out of scope.

Requirements against `hall-of-helix` (entry structure, metadata) go to that
repository as an issue referencing the originating hypothesis.

### Required response states

ACCEPTED, PLANNED, AVAILABLE, PARTIALLY_AVAILABLE, OUT_OF_SCOPE, REJECTED,
SUPERSEDED.

### Boundary-learning policy

Repeated OUT_OF_SCOPE or REJECTED responses trigger a review of whether the
demand belongs to a neighbouring interface — most likely `fluid-x` or
`fluid-substack`, which face the same publishing problem under different
platform constraints.

---

## 19. Audit and Provenance Policy

For every promoted change the system must retain enough evidence to reconstruct
originating pressure, hypothesis, candidate, verification, approval, deployment,
affected cohorts, measured outcome and final disposition.

### Retention period

Evidence: 365 days. Publication records: indefinite, because they are the record
of what was said in HelixForge's name.

### Immutable evidence store

The fluid-core evidence store, append-only at the database.

---

## 20. Review and Amendment

### Amendment authority

Bernd Worsch, as the owner of `helix-forge`. An amendment is a governance change
and is recorded as a new intent version; the previous version stays retrievable
because revisions published under it were governed by it.

### Review cadence

On any of: raising the authority mode, adding a capability family currently out
of scope, the first 100 subscribers, or annually.

### Last reviewed

2026-09-04 (initial)

---

## 21. Summary

The Daimon should optimize aggressively inside this document and remain
conservative at its boundaries.

This interface may evolve in how it delivers a post. It may not evolve into
writing one.

The voice belongs to the campaign, the work belongs to the person who did it,
and this interface's job is to carry the first without misrepresenting the
second.