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

507
InterfaceEvolutionIntent.md Normal file
View file

@ -0,0 +1,507 @@
# 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
> Make hall-of-helix entries reliably and faithfully available to a Telegram
> audience, without the people writing them having to think about Telegram.
An entry is written once, as Markdown, in `hall-of-helix/entries/`. Everything
about how it becomes a Telegram post — length, formatting, media, threading —
is this interface's problem and nobody else's.
### Success looks like
- A finished hall entry reaches the channel without a human reformatting it.
- The published form is faithful: no entry is silently truncated, and no
attribution is lost.
- Publishing twice does not post twice.
- When Telegram's constraints and the entry's shape conflict, the conflict
surfaces as recorded pressure rather than as a mangled post.
---
## 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 hall-of-helix entries to a Telegram channel (Canon PUB-01).
- Rendering an entry into Telegram's message forms (Canon PUB-02, MED-02).
- Publication state: what was published, when, as which message.
- Idempotency and correction of previously published entries.
- 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 artifacts, such as release notes.
- Attaching entry visuals as media (Canon MED-01).
- A linked discussion group for comments.
### Out of scope
- 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 an entry becomes one or more Telegram messages.
- Composition: assembling an entry, its metadata and its visual.
- Validation: refusing an entry that cannot be published faithfully.
- Routing: which revision serves a publication request.
- Idempotency: recognising an entry it has already published.
### 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. |
| `hall-of-helix` | Entry content, its correctness, and whether it is finished | FLUID may read entries. It must never edit one to make it publishable. |
| OpenBao | Custody of the bot token | FLUID receives a credential. It never stores, logs or forwards one. |
### 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;
- edit or truncate a hall-of-helix entry to fit a platform constraint;
- publish to any chat other than those declared in the routing configuration;
- post on behalf of a person who has not asked for it.
The last of these matters most. A hall entry is a first-person account someone
wrote about their own work. Publishing it is an act taken on their behalf, and
that authority comes from their having written it — not from the interface
finding it convenient.
---
## 8. Consumer Expectation Model
### Concepts consumers should naturally understand
- An **entry** is the unit of publication, identified by its hall entry id.
- Publishing is **idempotent** on that id.
- A **publication** has state: pending, published, failed, superseded.
### Interaction patterns considered natural
- Publish one finished entry, then check its state.
- Re-publish the same entry after a correction and get the same message updated.
- List what has been published to reconcile against the hall.
### Expectations that should be discouraged
- That Telegram formatting is Markdown. It is not, and entries that assume so
will render wrongly.
- That an entry appears instantly. Rate limits are real.
- That a long entry arrives as one message. It cannot, and the interface's job
is to make that invisible rather than to pretend otherwise.
---
## 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 entry published in a form that loses content | Hard guardrail |
| Client utility | High | One call publishes one entry | The reason the interface exists |
| Reliability | High | Publication succeeds or reports why | |
| Discoverability | High | A reader can reach the full 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 | entry, 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
an entry is rendered, not what the interface offers.
---
## 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 an entry is *rendered* 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.
### 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.
### 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 entry, which revision, which message, and which
consumer asked. The bot token appears in no log, error, telemetry event or
evidence record.
### 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 published entry loses content or attribution | yes |
| Idempotency | Publishing an entry 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 entry, 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 presents an entry. It may not evolve in
whose voice it speaks.