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

Releases as captures

Some repositories keep what they hear as work to curate. headwater feeds them through its Flywheel plugin, whose one part is an adapter that turns each release into a capture (section 9). millpond keeps captures in an inbox, and millpond’s book defines the capture contract, the inbox and curation. What follows is what headwater puts into each capture.

A recorder like any other

The adapter is a recorder: a program that keeps what it hears as its own records. It asks headwater as any asker does, decides how it records each release, and never writes headwater’s state (section 2). headwater never knows which inbox records its releases (design/capture/design.md) and needs no recorder to answer (34).

One capture per release

headwater capture prints one capture line for each release headwater reports (design/capture/design.md):

  • source is release, and event_at is when the release was published, never when headwater found it;
  • raw holds the notes whole, and what the source answered;
  • the excerpt is the notes, asserted by the upstream, of kind ask. It asserts “<name> <version> is released; the repository pins <pin>”, and argues with the declarations a bump moves.

A release is its own excerpt: upstream’s notes are the quote, so no reader session reads it into signals.

The key

A capture’s key is a source event’s identity, the same from every host and every run. headwater keys a release in one of two ways:

  • an entry of a watch list keys as release/<name>/<version>, under the name the list gives it, the key swancloud’s release adapter has used since its first landing;
  • every other release keys by its identity, release/<type>/<namespace>/<name>/<version>, from its Package URL.

Because the pin alone decides what is new (9), the adapter prints a release at every run until the pin moves, and millpond’s dedupe lands it once (S6).

day 1 day 2 day 3 day 4 HEADWATER CAPTURE MILLPOND pin 2026.9.18 reports 2026.10.10 pin 2026.9.18 reports 2026.10.10 pin 2026.9.18 reports 2026.10.10 pin 2026.10.10 nothing newer release/mise/2026.10.10 release/mise/2026.10.10 release/mise/2026.10.10 no line lands the capture once, by its key key already held: passed over key already held: passed over nothing to land a fixer's bump lands
headwater keeps no list of what it reported, so it reports the release at every scan until the pin moves (9). The adapter prints the same key each time, and millpond lands the capture once (S6). The bump that moves the pin is the only thing that stops the line.

In a repository crew runs

In a repository crew runs, a bump comes only as a chore crew’s planner makes from an item. There the herdr plugin’s fix key hands the release to millpond as a capture, and no agent starts outside crew’s plan (design/capture/design.md). The release then reaches a landed bump by the path every capture takes. Curation routes its signal into an item, and the planner proposes the chore. A team bumps the dependency with headwater’s brief in hand, and sluice lands the change. The next scan no longer reports the release, because the pin moved, and nobody wrote an acknowledgement (millpond’s account).

Where the adapter lives

The adapter is headwater’s because it wraps headwater’s domain, and it lives in plugins/flywheel beside headwater’s core. millpond runs it like any other adapter part, on the schedule its inbox’s settings give it (design/capture/design.md).

Not yet in the statement: the key, the files a bump of a watch-list entry moves, and the capture lines, which plan step H1 writes in. See Open questions.