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:

flowchart TB
  subgraph row1[" "]
    direction LR
    inbound(["inbound envelope"]) --> resolve["resolve_session"]
    resolve --> load["load_state"]
    load --> prompt["build_prompt"]
    prompt --> model["run_model<br/>[_stream]"]
  end
  subgraph row2[" "]
    direction RL
    save["save_state<br/>(finally)"] --> render["render_outbound"]
    render --> dispatch["dispatch_outbound"]
  end
  model --> save
  style row1 fill:transparent,stroke:transparent
  style row2 fill:transparent,stroke:transparent

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.