Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

millpond

Some events outside a repository should change its work: a release of something it depends on, a decision in a meeting, a deploy that failed. millpond is the inbox those events reach. A program notices each event and hands it to millpond as a capture. millpond records the capture once, turns it into signals, and serves the tools a curation session gives each signal its move through. Curation joins signals into items, and millpond passes each item on: flume launches its work in one worktree, or crew’s plan takes it. sluice lands the work an item becomes. An item that asks a question goes to a sounding, which ends on a conclusion the operator accepts.

adapters the inbox the work landing headwater releases of what a repository declares eddy recorded meetings, a part per service folder drop a file in a folder built into millpond lines millpond the inbox runs adapters on a tick keeps each capture once banks raw files off git holds signals and moves serves curation's tools passes items on a git repository, or a branch in one One worktree flume starts an agent on the brief A sounding one question, one conclusion crew's plan the planner's chores and units send send sluice tests the work as merged, then lands it Flywheel, later built on millpond's crates; reads the same inboxes
headwater and eddy each stand alone, and each carries an adapter part that prints capture lines into millpond. The folder drop needs no tool of its own, so it ships inside millpond. millpond sends an item through flume to one worktree, or to a sounding when it asks a question, or hands it to crew's plan. sluice lands the work of a worktree and of crew's teams.

Why it exists

Every source of events needs the same plumbing: a record of what it has already reported, a place for the raw material, a cut that keeps a quote small, a status a fleet can watch, and a loop that lands each capture. swancloud’s release adapter carries all of it alone today: its own landed list, its work/ and raw/ folders, its 8 KiB cut, its status.json and its landing loop. A meeting source would carry the same plumbing again, and so would every source after it.

millpond holds that plumbing once. An adapter shrinks to the part that knows its source: it lists the source’s events, keys each one, fetches the raw material, and marks a capture that is its own excerpt (115). The dedupe by key, the raw bank, the records, the cut, the cursor and the run’s status are millpond’s.

What it promises

  • A source event is one capture, however many hosts and runs report it (111).
  • Raw material stays on the host and never enters git. The capture points at it (111, 217h).
  • A capture that is its own excerpt gets its one signal as it lands, cut at a line under the inbox’s limit. Every other capture waits, unread, for a reader.
  • A reader’s excerpt appears verbatim in its capture’s raw material, or millpond refuses it (113).
  • Every signal takes exactly one move, every move has a stated consequence, and an unmoved signal is never discarded (107, 116, 118).
  • Weight counts by event date, never by the date of capture (118).
  • The operator decides a batch of moves at a time, and an item at a time, never a signal at a time (109).

Where it stops

millpond never judges what a capture says and never plans across items. A model runs in two places only, a reader and a curation session, and each is a Claude session working through millpond’s tools. Ordering items across teams is crew’s planner today and Flywheel’s later. millpond reads a source only through an adapter, its own built-in ones included. It starts no agent, since flume does; it works no question, since a sounding does; and it tests and lands nothing, since sluice does.

The tools beside it

  • headwater reports releases and advisories for what a repository declares. Its book is at ../headwater/.
  • eddy lists recorded meetings from each meeting service. Its book is at ../eddy/.
  • flume launches and tracks one agent in one worktree through a kind’s stages, and tidies the place when the work lands or is dropped. Its book is at ../flume/.
  • sounding works one question in one session, in a worktree of its own, and ends on a conclusion the operator accepts, sends back for another round, or drops. Its book is at ../sounding/.
  • sluice tests a change as merged and lands it. Its book is at ../sluice/.
  • crew runs teams, plans and bolts. It calls millpond’s, flume’s and sluice’s command lines.
  • Flywheel is built later on the same crates as millpond and reads the same inboxes. crew becomes it (crew ADR 0026).

How to read this book

The chapters follow a capture: the contract it arrives under, the adapters that print it, the seven steps that land it, the inbox that keeps it, the reader that turns it into signals, the curation that moves them, and the items and sends that turn signals into work. Then come the sources millpond runs, the three setups it runs in, and who owns what.

A bare number in parentheses cites Flywheel’s statement, design/flywheel-next/requirements.md, whose record formats and moves millpond keeps. A number after headwater cites headwater’s statement. A rule id such as signals.6 or code.1 cites crew’s docs/architecture/; inputs.6, lists.1, doctor.1 and fleet.6 are swancloud’s. millpond’s own statement is not written yet; Open questions says what it will hold.