Concepts

This section explains the model behind Bub: why the kernel is small, what one turn actually does, how context is reconstructed from a tape, and where the three extension surfaces meet.

How to read this section

Read the four pages in order on your first pass. Each page is short and self-contained:

1. Philosophy — why the kernel is strict and plugins are loose, and why operators are equivalent.
2. Turn pipeline — what process_inbound runs, in order, and where each fallback kicks in.
3. Tape and context — how an append-only tape becomes the model’s context window.
4. Surfaces — channels, skills, and tools as three independent extension axes.

After your first pass, treat each page as a reference and return to specific sections as you build.

One-glance turn flow

This is the same diagram you will see expanded in Turn pipeline:

inbound envelope
         │
         ▼
╭─────────────────╮      ╭───────────────╮      ╭───────────────╮      ╭───────────────╮
│ resolve_session │────▶│   load_state  │────▶│  build_prompt │────▶│   run_model   │
│                 │      │               │      │               │      │   [_stream]   │
╰─────────────────╯      ╰───────────────╯      ╰───────────────╯      ╰───────┬───────╯
                                                                               │
      ╭───────────────────╮    ╭─────────────────╮    ╭───────────────╮        │
      │ dispatch_outbound │◀──│ render_outbound │◀──│   save_state  │◀──────╯
      │                   │    │                 │    │   (finally)   │
      ╰───────────────────╯    ╰─────────────────╯    ╰───────────────╯

save_state always runs in a finally block; render_outbound and dispatch_outbound run only when the turn succeeds.

Glossary

Quick links to where each term is defined:

• Hook — a pluggy extension point the kernel calls during a turn.
• Plugin — any package registered under the bub entry-point group.
• Tape — an append-only sequence of facts for one session.
• Entry — one immutable record on a tape.
• Anchor — a checkpoint the kernel can rebuild context from.
• Handoff — a constrained phase transition that writes a new anchor.
• Channel — an outward I/O surface (CLI, Telegram, …).
• Skill — a reusable procedure operators (human or agent) can invoke by name.
• Tool — a typed action the model can call.
• Envelope — the duck-typed payload passed through the turn pipeline.

Next steps

• Philosophy — start the section.
• Hooks reference — full hookspec signatures, when you need them.