Telegram Channel Server Day 5 Part 1: Proving the Listener End to End

Thesis

The Telegram listener only becomes production software when the shell, intake boundary, inbox writes, and CLI wiring survive together in one end-to-end path. Day 5 Part 1 is the integration gate that proves those pieces compose in a real run instead of only passing isolated unit tests.

Angle

Frame the post around one concrete idea:

• Day 3 gave the intake boundary and inbox records.
• Day 4 made stop, recovery, and status observable.
• Day 5 proves the pieces actually compose in a real run.
• A loopback Telegram API server is the right integration boundary for this proof.

Outline

1. Why the final gate has to be end-to-end instead of another isolated seam.
2. How the listener is started and driven from the CLI.
3. What the loopback Telegram API server proves about real update intake.
4. Which inbox and state files prove the listener did real work.
5. Why Part 2 still has to close the packaging gap.

Guardrails

• Do not describe the end-to-end run as a mock.
• Do not call the system complete until packaging install smoke also passes.
• Keep the examples concrete about commands, files, and update handling.

Draft

Day 5 is the point where the Telegram listener stops being a collection of promising seams and becomes a system that can be exercised like an operator would exercise it. The interesting question is no longer whether the listener can parse an update or persist a record. The question is whether the whole foreground path can start, poll, write, and stop while leaving behind evidence that matches the runtime story.

That is why this part of the sprint is not another narrow unit test pass. Loopback smoke is the right boundary because it forces the listener to cross the same layers a real deployment crosses:

• the CLI entrypoint,
• the foreground listener shell,
• the Telegram HTTP boundary,
• the inbox writer,
• and the state files that describe what happened.

The implementation lives under src/pkgs/core/channels/telegram/, so the integration proof should exercise that package as installed code, not as a source-tree assumption. The listener should be started through the CLI in the same shape an operator would use, and the test should watch the on-disk artifacts tell the story back.

The loopback API server matters because it removes ambiguity from the network layer without reducing the proof to a mock. A loopback server can receive the Telegram-shaped request, return a controlled update payload, and let the listener advance through its real intake path. That is enough to prove:

• listen can start the foreground process,
• the intake boundary can poll a Telegram-like response,
• the inbox writer can materialize durable artifacts,
• and close can stop the listener without losing the filesystem trail.

The files are the strongest evidence in this slice. The article should call out the actual artifacts the smoke proves:

• listener/state.yaml records the lifecycle transition.
• listener/history.md records the start and stop events.
• listener/lease.yaml reflects ownership while the process is alive and release after shutdown.
• inbox/<update-id>/raw.json, metadata.yaml, and summary.md show that an update was committed, not merely observed.

That file-level evidence is important because the Day 5 gate is not asking “did the process print the right message?” It is asking whether the org-local filesystem can be trusted as the operational record. If the process exits and the files still describe a consistent run, the listener has crossed the most important production threshold.

The article should also make the CLI path concrete. The listener is expected to be driven by the existing command surface, so the operational story is simple:

PYTHONPATH=src python3 -m cli channels telegram listen /path/to/org
PYTHONPATH=src python3 -m cli channels telegram close /path/to/org

Those commands are not interesting because they exist. They matter because they prove the Telegram listener can be operated from the same command boundary as the rest of the channel surface.

What this part intentionally does not do is close the release story. The smoke can prove that the listener works in a real loopback run, but it cannot prove that the installed artifact still contains the right source packages. That is the Part 2 problem. Part 1 should end by making the handoff explicit: the listener is operationally real, but the release gate still has to prove the installed build includes the Telegram implementation under src/pkgs/core/channels/telegram/.

The right takeaway is narrow and practical: the Telegram listener is now a real foreground system, but Day 5 is only satisfied once the integration proof and the packaging proof both pass. This part establishes the first half of that claim.