Skip to content
C.W.K.
Lesson 04 of 08 · published

The Journal Before the Screen

~12 min · journal, replay, retention, sequencing, daemon

Level 0Spark
0 XP0/48 lessons0/12 achievements
0/100 XP to next level100 XP to go0% complete

Live Is a Subscriber, Not the Store

A terminal you walk away from has to remember what happened while you were gone. The naive design writes bytes to the screen and hopes the screen is still there. That design is a projection pretending to be a store. Smolder sequences output into a bounded journal first, then publishes to whoever is attached. The journal is the ordered record. The screen is a subscriber. If you reverse those, a crash of the window becomes a hole in history, and a phone that reconnects has nothing honest to catch up on.

Bounded is not a performance footnote. An unbounded journal is a disk that grows until the daemon holds more than it can keep safe. A bound — a ring of retained output, old chunks dropped — is how the owner stays restartable. You do not get infinite scrollback as a side effect of ownership. You get a truthful prefix of what the process has emitted lately, and you know it is a prefix.

Storage Failure Must Not Kill Live

If the journal cannot write — disk full, permission, a volume that went away — live output still has to reach an attached projection. Retention degrades. The fire does not. A daemon that refuses to print because it cannot file is a daemon that has confused bookkeeping with the job. The operator should see that retention is degraded. They should not see a frozen pane because a log file argued.

That split is the same ownership split as the first lesson, applied to bytes. The process is alive. The drawing surface may be gone. The store may be limping. Only the process's death is allowed to end the stream. Everything else is a subscriber having a bad day, and a subscriber's bad day is not a kill.

Replay Is Not Re-running

When a projection attaches, the owner first fixes a boundary: everything up to this sequence number is history, everything after it is live. It then replays the retained output up to that boundary into the emulator, so the screen looks like a place, not a blank, and only then lets the live bytes after the boundary follow, in order. Nothing is published twice and nothing falls in the gap. Replay suppresses side effects. It does not re-send the bytes to the child. It does not re-fire bells as if they were happening now. It does not re-run commands. It paints history. A replay that talks back to the process is how you duplicate a prompt, or worse, duplicate a submit.

An incomplete prefix is never painted as a screen. If what is retained no longer reaches back far enough — the screen would start in the middle of a line, in the middle of a TUI frame, or after a clear you no longer have — Smolder does not feed those bytes to the emulator and call it caught up. It skips the screen replay, keeps the live process running, and hands you the retained output as plain, readable text: on the Mac the pane says so in one line, offers it under Shell → Show Recovered Output…, and suggests the program's redraw key, such as Control-L. A spinner that says "caught up" over a truncated ring is how people start trusting a screen that was never complete. Catch-up means "this is what we still have," shown for what it is.

Sequence into the journal, then publish to the screen. Live continues if storage limps. Replay paints; it does not talk back. An incomplete prefix becomes readable text, never a fake screen.

Code

Order of bytes, and what replay is allowed to do·text
child PTY  -->  sequencer  -->  bounded journal  -->  attached projections
                     |
                     +-- if journal write fails: still publish live
                         mark retention degraded, do not freeze the pane

# Attach / reconnect
  1. attach: the owner answers "ready" and fixes a boundary sequence
  2. complete retained replay up to that boundary -> paint only
       prefix incomplete? -> NO screen replay; retained plain text, labeled,
                             plus a hint to press the program's redraw key
  3. live output after the boundary follows, in order
       (nothing before it published twice, nothing after it lost)
  4. never tell the child that replay happened

# Replay must suppress
  bells, title-as-event, bracketed-paste replies,
  anything that would look like input or a fresh side effect

# Honest catch-up
  complete prefix   =>  the screen, repainted (still only what is retained)
  incomplete prefix =>  "retained plain output", never a fake screen

External links

Exercise

List three things that must happen when a projection attaches after ten minutes away, and three things that must not. At least one "must not" should be a side effect (bell, title, input). At least one "must" should name what you say if the retained prefix is incomplete.
Hint
If your "must" list includes talking to the child, you have confused replay with re-run. If your "must not" list has no words for the operator, you have confused a truncated ring with being in sync.

Progress

Progress is local-only — sign in to sync across devices.
Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)
Sign in — Please sign in to comment.

No comments yet — be the first.